68 lines
3.6 KiB
Plaintext
68 lines
3.6 KiB
Plaintext
|
---
|
||
|
|
title: Workspace adaptations
|
||
|
|
description: Record the implementation differences that must survive updates from the shadcn/ui Base UI source.
|
||
|
|
order: 22
|
||
|
|
toc:
|
||
|
|
- id: baseline
|
||
|
|
title: Upstream baseline
|
||
|
|
- id: icons-and-ripple
|
||
|
|
title: Icons and ripple
|
||
|
|
- id: localization
|
||
|
|
title: Localization
|
||
|
|
- id: popover
|
||
|
|
title: Popover extensions
|
||
|
|
- id: select
|
||
|
|
title: Select correction
|
||
|
|
- id: upgrade-checklist
|
||
|
|
title: Upgrade checklist
|
||
|
|
---
|
||
|
|
|
||
|
|
## Upstream baseline {#baseline}
|
||
|
|
|
||
|
|
The local components began from shadcn/ui's Base UI registry with the `base-vega` style. Use the upstream [component documentation](https://ui.shadcn.com/docs/components/base) and [GitHub source directory](https://github.com/shadcn-ui/ui/tree/main/apps/v4/registry/bases/base/ui) as references, but do not assume the latest upstream version is identical to the workspace snapshot.
|
||
|
|
|
||
|
|
When determining behavior, prefer the local source, then this documentation, then local `components.json`, and only then the latest upstream example.
|
||
|
|
|
||
|
|
## Icons and ripple {#icons-and-ripple}
|
||
|
|
|
||
|
|
`components/icon.tsx` maps Lucide icon names to `@icones/react` components and preserves a set of upstream-compatible export names. Existing components import through that entry point. Convert any `lucide-react` import introduced by the CLI back to the local module.
|
||
|
|
|
||
|
|
`Button` merges its incoming ref with `useRippleRef`. Preserve relative positioning, ref merging, and disabled behavior when updating Button.
|
||
|
|
|
||
|
|
## Localization {#localization}
|
||
|
|
|
||
|
|
Breadcrumb, Calendar, Carousel, Dialog, Pagination, Sheet, Sidebar, Spinner, Toast, and related components replace some hard-coded English with descriptors from `components/i18n.tsx`. When updating these files, inspect accessible labels, screen-reader-only text, and default descriptions in addition to visible UI.
|
||
|
|
|
||
|
|
Only `en-US` and `zh-Hans` catalogs are published. Adding a message requires synchronized changes to:
|
||
|
|
|
||
|
|
1. The `uiMessages` descriptor.
|
||
|
|
2. The `uiMessageIds` type list.
|
||
|
|
3. `messages` in both locale modules.
|
||
|
|
4. The component that consumes the message.
|
||
|
|
|
||
|
|
## Popover extensions {#popover}
|
||
|
|
|
||
|
|
The local `PopoverContent` adds these capabilities beyond the upstream wrapper:
|
||
|
|
|
||
|
|
- Forwarded `anchor` and `positionMethod` options.
|
||
|
|
- `showArrow`, accepting an `AnchoredSurface` configuration object.
|
||
|
|
- `viewportClassName`, separating scrollable content from the overflow-visible outer surface.
|
||
|
|
- An anchor-sized default side offset and continuous curved tail.
|
||
|
|
- `createPopoverHandle` and `PopoverHandle` exports.
|
||
|
|
|
||
|
|
Do not replace the file wholesale with upstream source. In particular, test long-content scrolling, every side, collision flips, narrow triggers, and RTL.
|
||
|
|
|
||
|
|
## Select correction {#select}
|
||
|
|
|
||
|
|
`SelectTrigger` renders `ChevronDownIcon` as a child of `SelectPrimitive.Icon` instead of passing the icon component through `render`. This correction is intentional for the current Base UI and Icones combination. After a Select update, verify that the trigger shows exactly one icon and test SSR and hydration.
|
||
|
|
|
||
|
|
## Upgrade checklist {#upgrade-checklist}
|
||
|
|
|
||
|
|
1. Review the shadcn docs and matching registry source diff before replacing anything.
|
||
|
|
2. Generate through the CLI on a temporary branch or stage files individually, preserving local public exports.
|
||
|
|
3. Convert direct icon dependencies back to `components/icon`.
|
||
|
|
4. Restore translated messages, logical-direction utilities, and local theme classes.
|
||
|
|
5. Give Button, Popover, Select, Calendar, Toast, and Sidebar focused regression coverage.
|
||
|
|
6. Run the UI typecheck, repository lint and format checks, then build a real consuming application.
|
||
|
|
7. Manually inspect light, dark, LTR, RTL, mobile, tablet, and desktop behavior.
|