npm - themelia-ui - Versions diffs - 1.0.0 - Mend

themelia-ui 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2156) hide show

package/docs/generated/migration.md ADDED Viewed

@@ -0,0 +1,146 @@
+<!-- GENERATED by scripts/gen-migration-map.mjs — do not edit. -->
+# Migration
+Everything that changed for a consumer, in one place. The symbol-by-symbol table for the
+removed barrels is in [migration-broad-imports.md](./migration-broad-imports.md).
+`npm run codemod -- <paths…>` applies every change marked mechanical below. The rest name
+the edit to make and why it exists; a codemod that guesses at those would be worse than
+no codemod.
+## Moved subpaths
+The layer above features was renamed, and the admin domains moved into the admin profile. Every one of these is a pure specifier rewrite, which is why `npm run codemod` can do them for you.
+### `themelia-ui/blocks/analytics`
+**Becomes** `themelia-ui/patterns/analytics` — mechanical, the codemod does it.
+`blocks/` became `patterns/`, and the admin domains moved under `admin/patterns/`. The layer kept its position above features; only the name changed.
+### `themelia-ui/blocks/onboarding`
+**Becomes** `themelia-ui/patterns/onboarding` — mechanical, the codemod does it.
+See above.
+### `themelia-ui/blocks/timelines`
+**Becomes** `themelia-ui/patterns/timelines` — mechanical, the codemod does it.
+See above.
+### `themelia-ui/blocks/access`
+**Becomes** `themelia-ui/admin/patterns/access` — mechanical, the codemod does it.
+Admin domains moved into the admin profile, which may build on general families but never the reverse.
+### `themelia-ui/blocks/commerce`
+**Becomes** `themelia-ui/admin/patterns/commerce` — mechanical, the codemod does it.
+See above.
+### `@/services/actions`
+**Becomes** `themelia-ui/features/actions` — mechanical, the codemod does it.
+The action registry was never published; it lived at a source alias no consumer could resolve. It is a family now.
+## Provider changes
+Behaviour, not names. `UIProvider` still exists and still behaves as it did; what changed is that the pieces it composes are now separately available, and that reaching outside the React tree is opt-in.
+### `<UIProvider> writes theme and density onto the document`
+**Becomes** `<UIRoot documentTarget="documentElement">` — by hand.
+Reaching outside the React tree is the one thing here that re-rendering cannot undo, so it is opt-in. `UIProvider` still composes UIRoot and UIScope and behaves as it always did; only new code needs the narrower pieces.
+Add `documentTarget="documentElement"` to the root provider if your application relies on the theme reaching <html>. If it does not, nothing changes.
+### `<UIProvider> renders a wrapper element`
+**Becomes** `<UIRoot> renders nothing` — by hand.
+A box at the top of every application that used one is a layout node nobody asked for, and it broke flex and grid parents expecting their real child.
+Remove any CSS that targeted the provider's wrapper. If you need an element, use <UIScope transparent={false}>.
+## Prop changes
+One idea that had two spellings.
+### `asChild`
+**Becomes** `render` — by hand.
+One idea had two spellings. `render` takes the element as a value, so it can be built conditionally or defaulted, and it does not overload `children`. See docs/adr/0005-polymorphic-render-contract.md.
+`<Button asChild><a href="/x">Go</a></Button>` becomes `<Button render={<a href="/x" />}>Go</Button>`. The children move out of the wrapped element and stay on the component. `node scripts/codemods/as-child-to-render.mjs <paths>` rewrites the cases where the child is a single JSX element and refuses the rest, because a codemod cannot decide which children belong where. Affects Badge and BadgeProps, Button and ButtonProps, OverlayTrigger and OverlayClose (so DialogTrigger, DialogClose, SheetTrigger and SheetClose, which alias them), PopoverTrigger, PopoverAnchor, SidebarMenuButton, SidebarMenuSubButton, TooltipTrigger, AlertDialogAction and AlertDialogCancel. `asChild` is removed, not deprecated: passing it now reaches the DOM as an unknown attribute and React warns.
+### `contentAs`
+**Becomes** `contentRender` — mechanical, the codemod does it.
+One idea in two vocabularies. Every other polymorphic seam in the kit is `render`, and this one shipped as `contentAs` — a string union naming an element rather than an element to render. `verify:api-vocabulary` exists to catch exactly this and its regex only matched `as?: ElementType`, so the single instance of the drift outlived the rule against it.
+`contentAs="div"` becomes `contentRender={<div />}`. Mechanical: the value goes from an element NAME to an element, so `"section"` becomes `<section />`.
+### `FormFieldProps htmlFor: string`
+**Becomes** `FormFieldProps htmlFor: string | false` — mechanical, the codemod does it.
+`false` is how a caller says the field wraps a GROUP of controls rather than one — a radio set, a segmented control, a pair of date inputs. There is no single element for a label to point at, so `FormField` stops inventing an id and describes the group instead. Widening an optional input prop: every call site passing a string, and every call site omitting it, is unaffected.
+Nothing to change when passing a string or omitting the prop. Only a consumer who reads the type back out is affected — `const id: string | undefined = props.htmlFor` becomes `string | false | undefined`. Widen the annotation, or narrow with `htmlFor || undefined`.
+### `fifteen unread default strings keys`
+**Becomes** `removed` — by hand.
+Each of these was declared in a `default*Strings` object and in its exported interface, and read by NOTHING. Overriding one did exactly nothing, silently, which is the worst shape an API can take — the caller has no way to tell it did not work. They accumulated the same way each time: the component owned a label, the design moved that copy to a prop the caller supplies or the feature went away, and the key stayed behind. Removed: `OrderCustomerStrings.viewCustomer`, `OrderSummaryStrings.formatItemCount`, `PaymentMethodStrings.holder`, `SeoStrings.scoreLabel`, `OverflowTabBarStrings.scrollHint`, `AiChatPromptInputStrings.modelPickerAria`, `CommentsStrings.moreActionsLabel`, `DataViewPaginationStrings.morePages`, `FilterStrings.selectDateRange`, `GlobalSearchStrings.idleRecent`, `GlobalSearchStrings.idleSuggestions`, `MediaLibraryStrings.retry`, `MediaLibraryStrings.usedIn`, `ProductVariantBulkTableStrings.optionLabel`, `SideNavStrings.toggleGroup`.
+Delete the override. The copy it appeared to control is either supplied by you already — a `sections[].label`, a slot, an item field — or is no longer rendered. Two keys from the same sweep went the other way and are NOT removed: `CredentialListStrings.copyLabel` now names each row's copy button, and `AiConfirmationStrings.detailsLabel` now names the confirmation's details region; both were unread for the opposite reason, and both are worth setting.
+### `HeaderNotificationsStrings without unreadItem`
+**Becomes** `HeaderNotificationsStrings.unreadItem` — mechanical, the codemod does it.
+Unread was drawn as a tint and a dot, and neither reaches a screen reader — colour alone is not a state — so the row also carried the word. It was a literal `<VisuallyHidden>Unread</VisuallyHidden>`, which no `strings` override could reach and no consumer could translate.
+Nothing to change when passing a partial, which is what the `strings` prop takes. Only code that builds a COMPLETE `HeaderNotificationsStrings` object — a translation table, typically — must add `unreadItem`. The English default is "Unread".
+### `typography written into JSX`
+**Becomes** `CommentsStrings.formatQuoteAttribution and MentionInlineSuggestionsStrings.formatQuery` — mechanical, the codemod does it.
+The em dash before a quoted block's attribution, and the curly quotes around a search term, were written into the JSX. Neither is punctuation every language shares — German sets „…“ and French « … » — so a consumer could translate every key in both interfaces and still be left with English convention.
+Nothing to change when passing a partial, which is what both `strings` props take. Only code that builds a COMPLETE strings object must add the formatter. Defaults: `(caption) => `— ${caption}`` and `(query) => `“${query}”``.
+## CSS imports
+One stylesheet became one per family.
+### `themelia-ui/style.css`
+**Becomes** `one self-contained sheet per family` — by hand.
+One stylesheet meant every consumer shipped every component's rules. The split means you ship what you import.
+Import each family's stylesheet beside its components; the family sheet imports `core.css` and its cascade layer order itself. `docs/generated/imports.md` lists every exact path. `style.css` still exists as the deduplicated union if you would rather not track them.
+## Behaviour changes
+Same name, same signature, a different answer — the kind of change a type checker cannot warn you about.
+### `deriveThemePalette picks a foreground by OKLCH lightness threshold`
+**Becomes** `deriveThemePalette measures WCAG contrast and picks the more readable candidate` — by hand.
+A lightness threshold is a guess about contrast, not contrast. It also understood only `#rrggbb` and `oklch()`, so an `hsl()`, an `rgb()` or a named colour fell through to whatever `mode` said. Sweeping lightness across six hues finds 52 colours where the threshold chose the LESS readable of the two foregrounds.
+Nothing to change; the signature is identical. But `--primary-foreground` MOVES for brand colours in the mid-lightness band, and always towards the more readable answer: #3b82f6 went from white at 3.52:1 (fails WCAG AA) to dark at 5.11:1, and #ef4444 from 3.60:1 to 5.00:1. If you had compensated for the old choice by overriding `--primary-foreground` yourself, drop the override. `readableForeground` from `themelia-ui/theming` reports the ratio it achieved and whether it clears AA, so a seed where neither candidate does — #6366f1 tops out at 4.28:1 — says so instead of passing quietly.

package/docs/generated/profiles.md ADDED Viewed

@@ -0,0 +1,140 @@
+<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
+# Profiles
+One package, two profiles over one downward dependency graph.
+A profile is a **dependency ceiling**, not a subject-matter category, and not a bundle.
+It says which direction an import may travel; it says nothing about what a family is FOR.
+96 of the 98 documented families are `general`, and that includes the
+product, order and resource workflows an admin application is mostly built from —
+`general` does not mean "not useful in admin software".
+**general** — 96 families. Does not depend on an admin family.
+**admin** — 2 families. Terminal: may depend on general families, and may
+never be imported by one.
+What a consumer downloads is decided by the exact subpaths they import, not by a profile:
+there is no general bundle and no admin bundle. The machine-readable records —
+`themelia-ui/profiles/general.json` and `.../admin.json` — list every subpath
+available below each ceiling and the optional peers that come with it.
+The rule between them is enforced twice: `verify:composition` fails any general family that
+names `src/components/admin`, and `verify:architecture` fails the same edge in the manifest.
+A general consumer therefore cannot accidentally acquire a domain vocabulary, and an admin
+component cannot become a place where application policy hides.
+## The graph
+```text
+foundation → typography → primitives → base ─┬─ layout ────┐
+                                             ├─ features ──┼→ patterns → admin
+                                             └─────────────┘
+```
+`layout` and `features` are siblings. Neither may import `patterns`; a pattern may
+assemble either one. `admin` is the terminal profile layer.
+## Families
+| family | profile | layer | depends on |
+| --- | --- | --- | --- |
+| `admin/patterns/access` | admin | admin | 8 |
+| `admin/patterns/commerce` | admin | admin | 17 |
+| `base/accordion` | general | base | 1 |
+| `base/action-menu` | general | base | 3 |
+| `base/alert-dialog` | general | base | 1 |
+| `base/aspect-ratio` | general | base | — |
+| `base/avatar` | general | base | — |
+| `base/badge` | general | base | 1 |
+| `base/batch-action-bar` | general | base | 2 |
+| `base/buttons` | general | base | 3 |
+| `base/cards` | general | base | 6 |
+| `base/carousel` | general | base | 1 |
+| `base/chart` | general | base | — |
+| `base/choice-inputs` | general | base | 5 |
+| `base/combobox` | general | base | 1 |
+| `base/command` | general | base | 2 |
+| `base/context-menu` | general | base | 1 |
+| `base/copyable` | general | base | 3 |
+| `base/date-pickers` | general | base | 5 |
+| `base/dialog` | general | base | 1 |
+| `base/direction` | general | base | — |
+| `base/display` | general | base | 5 |
+| `base/dropdown-menu` | general | base | — |
+| `base/feedback` | general | base | 2 |
+| `base/forms` | general | base | 4 |
+| `base/forms-numeric` | general | base | 2 |
+| `base/hover-card` | general | base | — |
+| `base/input-group` | general | base | 3 |
+| `base/item` | general | base | 2 |
+| `base/label` | general | base | 1 |
+| `base/menubar` | general | base | 1 |
+| `base/navigation` | general | base | 6 |
+| `base/navigation-menu` | general | base | — |
+| `base/otp-input` | general | base | 1 |
+| `base/overlay` | general | base | 2 |
+| `base/popover` | general | base | 2 |
+| `base/popover-menu` | general | base | 3 |
+| `base/qr-code` | general | base | — |
+| `base/repeaters` | general | base | 5 |
+| `base/resizable` | general | base | — |
+| `base/sheet` | general | base | 1 |
+| `base/sidebar` | general | base | 7 |
+| `base/skeleton` | general | base | — |
+| `base/slot` | general | base | — |
+| `base/spinner` | general | base | — |
+| `base/structure` | general | base | — |
+| `base/table` | general | base | 1 |
+| `base/text-inputs` | general | base | — |
+| `base/timeline` | general | base | 1 |
+| `base/toaster` | general | base | — |
+| `base/toggle` | general | base | — |
+| `base/toolbar` | general | base | 1 |
+| `base/tooltip` | general | base | — |
+| `base/typography` | general | typography | — |
+| `base/upload` | general | base | 4 |
+| `base/value-inputs` | general | base | 5 |
+| `features/actions` | general | features | 5 |
+| `features/activities` | general | features | 8 |
+| `features/ai-chat` | general | features | 8 |
+| `features/async-preview` | general | features | 6 |
+| `features/combobox` | general | features | 6 |
+| `features/comments` | general | features | 13 |
+| `features/data-view` | general | features | 6 |
+| `features/event-calendar` | general | features | 7 |
+| `features/filters` | general | features | 11 |
+| `features/global-search` | general | features | 10 |
+| `features/kanban` | general | features | 3 |
+| `features/map` | general | features | 7 |
+| `features/media-library` | general | features | 15 |
+| `features/mentions` | general | features | 4 |
+| `features/overlays` | general | features | 6 |
+| `features/products` | general | features | 17 |
+| `features/resource` | general | features | 6 |
+| `features/resource-assignment` | general | features | 7 |
+| `features/rich-text-editor` | general | features | 3 |
+| `features/rich-text-editor/tiptap` | general | features | — |
+| `features/schema-form` | general | features | 11 |
+| `features/suggestions` | general | features | 2 |
+| `features/sync` | general | features | 4 |
+| `features/table` | general | features | 13 |
+| `features/theme-tweaker` | general | features | 16 |
+| `forms` | general | foundation | — |
+| `forms-rhf` | general | foundation | — |
+| `layout/app-shell` | general | layout | 1 |
+| `layout/auth` | general | layout | 1 |
+| `layout/containers` | general | layout | — |
+| `layout/header` | general | layout | 9 |
+| `layout/navigation` | general | layout | 3 |
+| `layout/page` | general | layout | 4 |
+| `layout/settings` | general | layout | 1 |
+| `layout/sidebar` | general | layout | 6 |
+| `layout/workspace` | general | layout | 5 |
+| `patterns/analytics` | general | patterns | 8 |
+| `patterns/onboarding` | general | patterns | 4 |
+| `patterns/timelines` | general | patterns | 5 |
+| `primitives` | general | primitives | 1 |
+| `theming` | general | foundation | — |
+| `ui-provider` | general | foundation | — |