themelia-ui 2.0.0 → 3.0.0

package/.agents/skills/themelia-ui/references/installation.md

@@ -5,7 +5,7 @@ npm install themelia-ui
 ```
 
 React 19 and `react-dom` are required peers. Everything else is optional and only pulled in
-by the family that needs it — see [Optional peers](#optional-peers).
+by the module that needs it; see [Optional peers](#optional-peers).
 
 ## Browser support
 
@@ -17,8 +17,8 @@ list of right-to-left languages and ignores `dir="rtl"`.
 
 ## Import exactly what you use
 
-The package publishes one subpath per family and no broad barrels: there is no
-`themelia-ui/base`, and there will not be. A barrel would pull every family into the bundle
+The package publishes one subpath per module and no broad barrels: there is no
+`themelia-ui/base`, and there will not be. A barrel would pull every module into the bundle
 and make an optional peer reachable from an import that did not ask for it.
 
 ```tsx compile
@@ -27,46 +27,62 @@ import { Stack } from "themelia-ui/base/structure"
 import { Money } from "themelia-ui/primitives"
 ```
 
-The root `themelia-ui` export exists and is optional-peer-free, but it is for
+The root `themelia-ui` export exists and is free of optional peers, but it is for
 prototyping. Shipping code should name subpaths, which keeps the JS and CSS to what you
 use.
 
-The exact import for every family is in
+The exact import for every module is in
 [`docs/generated/imports.md`](imports.md), generated from the package manifest.
 
-## CSS
+## Loading the CSS
 
-Import each family's stylesheet beside its components. The ESM build also imports its own
-CSS, but the CJS build, SSR without a CSS loader and most test runners do not; the explicit
-import behaves the same everywhere and keeps the selected CSS visible in application source.
-Each family stylesheet imports the shared tokens, themes and cascade layer order from
-`core.css` for you.
+The package ships three kinds of stylesheet:
 
-```tsx fragment — shape only, not a program
-import "themelia-ui/base/buttons.css"
-```
+| Import | Contains |
+| --- | --- |
+| `themelia-ui/<module>.css` | `core.css`, then the rules of the module and of the modules it draws with |
+| `themelia-ui/style.css` | `core.css` and every module, in one file |
+| `themelia-ui/core.css` | Tokens, themes, typefaces, the base reset and the cascade layer order; no component rules |
+
+[`imports.md`](imports.md) gives each module's stylesheet path. A module whose
+components draw nothing has no stylesheet.
+
+### Import the stylesheets
+
+The JavaScript imports no CSS. Import each module's stylesheet beside its JavaScript, as the
+examples in these docs do, or `style.css` once. Vite, webpack, Rspack, Next.js and other
+bundlers that handle CSS imports include each file once, however many modules import it. A
+component whose stylesheet is not imported renders unstyled.
+
+### In Node
+
+The package is ES modules, and its JavaScript imports no CSS, so Node loads it as it is:
+server rendering and test runners need no configuration for it, and CommonJS code on Node
+20.19 or later can `require()` it. Jest is the exception, because it transforms nothing in
+`node_modules` by default: exempt the package in `transformIgnorePatterns`.
 
-Import `themelia-ui/core.css` on its own only when application CSS needs the token
-contract before any family stylesheet is loaded. Do not add it merely because you imported
-a family stylesheet; that sheet already imports it.
+### `core.css` on its own
 
-A family whose components draw nothing has no sheet. `imports.md` records which.
+Every module stylesheet begins by importing `core.css`, so a component never needs a
+separate core import to render correctly. Import `core.css` on its own when application CSS
+uses the tokens on a page without kit components, or to place the kit's layers next to
+another layered stylesheet, as in the [Tailwind setup](theming.md#tailwind-css-v4).
 
-If you would rather not track sheets per family, `themelia-ui/style.css` is the
-deduplicated union of all of them, larger than any one app needs.
+### Overriding the kit
 
-Import application overrides after the kit. Component rules live in cascade layers, so
-ordinary unlayered consumer CSS wins without specificity tricks. Select with stable
-`data-slot` and BEM hooks, and select a state with the attributes the primitives set
-(`data-open`, `data-checked`, `data-disabled`, `data-highlighted`, `data-popup-open`).
+Component rules live in the cascade layers `tokens, theming, base, components, utilities`,
+so unlayered application CSS wins over them whatever its order or specificity. Select with
+the stable `data-slot` attributes and BEM hooks such as `{name}--component`, and select a
+state with the attributes the primitives set (`data-open`, `data-checked`, `data-disabled`,
+`data-highlighted`, `data-popup-open`). Hashed CSS Module class names change between
+releases.
 
 ## Optional peers
 
-Every peer other than React is optional, and each is reachable only from the families that
+Every peer other than React is optional, and each is reachable only from the modules that
 use it: a consumer who never imports `features/map` never resolves Leaflet.
 
-The peer-to-family table is in [`docs/generated/imports.md`](imports.md),
-generated from and checked against the package graph.
+The peer-to-module table is in [`docs/generated/imports.md`](imports.md).
 
 The `react-hook-form` adapter, for example, lives behind its own subpath so
 `themelia-ui/forms` stays dependency-free; a consumer on plain React state never resolves
@@ -76,10 +92,10 @@ react-hook-form. See [Forms](forms.md).
 
 The package ships two profiles from one install:
 
-- **General** — typography, formatted primitives, controls, generic patterns, layout shells
+- **General**: typography, formatted primitives, controls, generic blocks, layout shells
   and domain-neutral interaction features.
-- **Admin** — B2B and admin presentation, built only from the general profile.
+- **Admin**: B2B and admin presentation, built only from the general profile.
 
-Which families belong to which is in
-`docs/generated/profiles.md` (`node_modules/themelia-ui/docs/generated/profiles.md`). An admin family may build on a
+Which modules belong to which is in
+`docs/generated/profiles.md` (`node_modules/themelia-ui/docs/generated/profiles.md`). An admin module may build on a
 general one, never the reverse.

package/.agents/skills/themelia-ui/references/migration.md

@@ -1,6 +1,60 @@
 # Compatibility and migration
 
-The package is `2.0.0`. The stable-major policy below applies within a major version.
+What changes between versions, what to do when you upgrade, and which changes a stable major
+allows.
+
+## Upgrading to 3.0
+
+3.0 changes how the package loads, and gives a few props one shape.
+
+**Stylesheets are imported, never implied.** The package is ES modules only, and its
+JavaScript imports no CSS. Import each module's stylesheet beside its JavaScript, or
+`themelia-ui/style.css` once; a component whose stylesheet is not imported renders unstyled.
+`themelia-ui/styles` is gone: import `themelia-ui/core.css` instead. In exchange, Node loads
+the package as it is. Server rendering and test runners need no configuration for it, so
+`ssr.noExternal` and `test.server.deps.inline` entries added for the kit can go, and
+CommonJS code on Node 20.19 or later can `require()` it. Jest still needs the package
+exempted in `transformIgnorePatterns`.
+
+TypeScript flags the rest:
+
+- `Scope` takes `render` instead of `as`: `<Scope vars={vars} render={<section />}>`.
+- `Badge`, `Alert`, `Item`, `ItemMedia`, `InputGroupAddon` and `InputGroupButton` no longer
+  accept `null` for a variant prop; leave the prop out for the default.
+- Every `renderLink` is a `LinkRenderer`: it receives `LinkRenderProps` and returns one
+  element. `ActionLinkRenderer`, `ActionLinkRenderProps` and `ResourceCellLinkProps` are
+  gone. `Pagination` builds its addresses with `pageHref={(page) => …}`, and its
+  `renderLink` receives the href already built.
+
+A tool that reads the published catalogue (`docs/generated/component-index.json`,
+`recipes.json`, the profile records) reads `modules`, `tier` and `dependsOn` where it read
+`families`, `layer` and `dependsOnFamilies`, and passes `--module=` and `--tier=` to
+`find-component.mjs`.
+
+Run the codemod from your project, dry first. It rewrites `themelia-ui/styles`:
+
+```sh
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs src/
+```
+
+Every change with its replacement is listed in the
+migration reference (`node_modules/themelia-ui/docs/generated/migration.md`).
+
+## Upgrading to 2.0.1
+
+A consistency release with no API change. The in-between alpha steps, per-component colour
+names and glyph sizes are retired, and the codemod maps each read to the step that now owns
+its role. Every control takes `--radius-sm` at every size (checkboxes and glyph buttons
+included), badges return to it from 2.0.0's half radius, a wrapper nested in a Card steps
+down to it, every card-like surface is `--card` in dark, and the current navigation item is
+neutral. The groups are in the token contract (`node_modules/themelia-ui/src/styles/TOKENS.md`).
+
+Run the codemod from your project, dry first, if your CSS reads a retired step:
+
+```sh
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
+```
 
 ## Upgrading to 2.0
 
@@ -27,7 +81,7 @@ component name are gone, and the rest settle on fewer decisions:
 - **Two radii.** `--radius` (1rem) for containers and `--radius-sm` (0.5rem) for what sits
   inside them, both plain values. `--radius-surface`, `-popup`, `-lg` and larger read
   `--radius`; `--radius-control`, `-inner` and `-md` read `--radius-sm`. A theme that sets
-  `--radius` should set `--radius-sm` too — nothing derives it.
+  `--radius` should set `--radius-sm` too, because nothing derives it.
 - **Two text colours.** `--foreground` and `--muted-foreground`; `Text type="discrete"` is
   `type="secondary"`.
 - **One control height.** `--height-control` with `--control-h`, `-sm` and `-2xs` (34, 30 and
@@ -35,46 +89,61 @@ component name are gone, and the rest settle on fewer decisions:
   34px (were 36), menubar triggers 30px (were 28) and toast actions 24px.
 - **One density factor.** `--space-scale` is removed: `--density-scale` scales spacing and
   control geometry alike, and every density-scaled length is rounded to a whole pixel. A rule
-  that set both factors now sets `--density-scale` twice after the codemod, and the later
-  one wins.
+  that set both factors sets `--density-scale` twice after the codemod, and the later one
+  wins.
 - **One spacing ladder.** Every package spacing is a `--space-*` step (2, 4, 6, 8, 12, 16,
   24px), a control or row inset, or arithmetic over what it clears. Table cells, Item rows,
   toggles, alerts and toasts move by 2–4px.
 - **Menus stay dark by default**, now decided by the provider: `overlay.darkMenus: false`
   lets them follow the page.
 - **The typefaces ship.** `--font-sans` and `--font-mono` start with Geist and Geist Mono,
-  loaded by `core.css` from `dist/fonts/`, one file per script. The 1.x stacks named Inter and
-  JetBrains Mono and shipped neither, so text rendered in each machine's own font; anything
-  sized to its text is a little wider or narrower now. To keep your own typefaces, set both
-  tokens: the kit's files are then never downloaded. Your bundler must emit the files
-  `core.css` references, as Vite, webpack and Next.js do for `url()` in imported CSS.
+  loaded by `core.css` from `dist/fonts/`, one file per script. Text renders the same on
+  every machine now, so anything sized to its text may be a little wider or narrower. To keep
+  your own typefaces, set both tokens: the kit's files are then never downloaded. Your
+  bundler must emit the files `core.css` references, as Vite, webpack and Next.js do for
+  `url()` in imported CSS.
 - **A browser floor.** Chrome and Edge 125, Firefox 121 and Safari 16.4 or newer, set by
-  `round()`, `:has()` and `:dir()`; 1.x documented none. See
-  [installation](installation.md).
+  `round()`, `:has()` and `:dir()`. See [installation](installation.md#browser-support).
 
 Run the codemod from your project, dry first. It rewrites the moved imports, the renamed
 tokens wherever your CSS or scripts read or set them, and the renamed Tailwind utilities. It
 reports what it will not guess at: a removed token with no successor, an override that now
-sets a shared name, and `rounded-lg` and larger, which are Tailwind's own radii now:
+sets a shared name, and `rounded-md` and larger, which are Tailwind's own radii now:
 
 ```sh
 node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
 node node_modules/themelia-ui/scripts/consumer/codemod.mjs src/
 ```
 
+The codemod does not edit component code. TypeScript flags the renamed components above and
+`type="discrete"`; a few more changes may need a line of your own:
+
+- `NavigationMenu` takes `side`, `sideOffset` and `container`, which moved from each
+  `NavigationMenuContent`.
+- `Textarea` puts `className` on the `<textarea>`; select the box with
+  `[data-slot="textarea-frame"]`.
+- `PageActions` collapses below 1024px; pass `breakpoint={1040}` to keep the old width.
+- `Comments` shows the last three replies, folds a body after six lines and shows three
+  attachments; pass `maxVisibleReplies={0}`, `clampLines={0}` or `maxVisibleAttachments={0}`
+  to show everything.
+- DatePicker's trigger is a combobox named by its label: tests find it with
+  `getByRole("combobox", { name })`.
+- `TableSkeleton` draws the table's edge; pass `framed={false}` inside a card that draws one.
+- `useCopyToClipboard` confirms for 2000ms; pass a duration to keep 1600ms.
+- A theme exported from the Theme Tweaker before 2.0 stops at the first provider; export it
+  again.
+
 Every removed name, token and utility with its replacement is listed in the
 migration reference (`node_modules/themelia-ui/docs/generated/migration.md`).
 
 ## Upgrading to 1.0.4
 
-No import migration is required. 1.0.4 refined the default shape, surface, typography and
-interaction system: structural surfaces used a 12px default radius, compact floating surfaces
-the popup radius role, Preview/Code controls an underline presentation, and nested feature
-surfaces the shared surface hierarchy.
+No import changes. 1.0.4 moved structural surfaces to a 12px default radius, compact
+floating surfaces to a shared popup radius, and nested feature surfaces to the shared
+surface hierarchy.
 
-If custom CSS overrides literal radii, menu chrome, field focus treatments, or nested
-feature surfaces, compare those overrides with the shared semantic roles before keeping
-them.
+If custom CSS overrides literal radii, menu chrome, field focus treatments or nested feature
+surfaces, compare those overrides with the shared semantic roles before keeping them.
 
 See the 1.0.4 changelog (`node_modules/themelia-ui/CHANGELOG.md`) for the complete changes.
 
@@ -86,8 +155,8 @@ TabList keeps its tablist attributes and className on the scrolling element, ins
 `tabs--rail` wrapper that also holds the scroll buttons.
 
 Review custom CSS that depends on tablist parent selectors or overrides component spacing
-and typography. Cards, content blocks, overlays, and domain blocks use the shared surface
-and typography patterns more consistently. Overlay sheets honor their configured named or
+and typography. Cards, content blocks, overlays and domain blocks use the shared surface
+and typography patterns more consistently. Overlay sheets honour their configured named or
 custom cross-axis size.
 
 See the 1.0.3 changelog (`node_modules/themelia-ui/CHANGELOG.md`) for the complete changes.
@@ -95,9 +164,9 @@ See the 1.0.3 changelog (`node_modules/themelia-ui/CHANGELOG.md`) for the comple
 ## Upgrading to 1.0.2
 
 - **Rich text, comments, and activities:** TipTap is the default editor engine. Install
-  `@tiptap/core`, `@tiptap/pm`, and `@tiptap/starter-kit` when importing those families.
+  `@tiptap/core`, `@tiptap/pm`, and `@tiptap/starter-kit` when importing those modules.
   HTML is normalized to the editor schema; use the documented custom extensions or engine
-  seam for other content. Unrelated families and root imports remain independent of these peers.
+  seam for other content. Unrelated modules and root imports remain independent of these peers.
 - **Complete translation maps:** add `applying`, `savedViews`, and `customView` to complete
   `FilterStrings` maps; add `refreshing`, `error`, `refreshError`, and `retry` to complete
   `ActivitiesStrings` maps. Partial overrides keep working. Spreading the corresponding
@@ -112,7 +181,7 @@ See the 1.0.3 changelog (`node_modules/themelia-ui/CHANGELOG.md`) for the comple
 - **Mobile filters:** below 768px, FilterLayout keeps search inline and places editors in
   an inset sheet; saved views become a select. Set `mobilePresentation="inline"` to own the
   mobile arrangement, or `filtering.mobilePresentation` when using DataView.
-- **Media Library:** `view="table"` now shows metadata columns. Use `view="list"` to retain
+- **Media Library:** `view="table"` shows metadata columns. Use `view="list"` to retain
   compact rows. Supply `onUpload` to enable the upload tab; use the upload helpers' stable
   file IDs for progress updates and `applyItemPatch` for custom record shapes.
 - **Mention completion:** custom `MentionInlineSuggestions` compositions should connect
@@ -123,21 +192,17 @@ See the 1.0.3 changelog (`node_modules/themelia-ui/CHANGELOG.md`) for the comple
   retain the normal typography. Nested providers can opt out.
 
 The changelog (`node_modules/themelia-ui/CHANGELOG.md`) records the full changes. Check the
-generated family reference for each adopted feature before adapting custom compositions.
-
-## Before 1.0
+generated module reference for each adopted feature before adapting custom compositions.
 
-A breaking change before the stable release arrived with a codemod or mechanical migration
-instructions: a consumer could apply it by search and replace or by running a script, not
-by re-reading their code and deciding.
+## How changes are classified
 
-Every change is classified as one of:
+Every change is one of:
 
-- **additive** — a new export, a new optional prop
-- **documentation-only** — no runtime or type change
-- **behaviour-preserving internal** — a refactor whose observable behaviour is identical
-- **deprecation** — the old name still works, and says what replaces it
-- **breaking** — anything else
+- **additive**: a new export, a new optional prop
+- **documentation-only**: no runtime or type change
+- **behaviour-preserving internal**: a refactor whose observable behaviour is identical
+- **deprecation**: the old name still works, and says what replaces it
+- **breaking**: anything else
 
 ## Within a stable major
 
@@ -147,16 +212,16 @@ security or correctness makes keeping it unsafe.
 
 ## Import paths
 
-Layer barrels — `themelia-ui/base` and its siblings — are not public and will not become
-public: one specifier pulling an entire layer would also pull every optional peer inside it.
+Tier barrels such as `themelia-ui/base` are not public and will not become public: one
+specifier pulling an entire tier would also pull every optional peer inside it.
 
 If you are migrating from a broad import, the mapping from old specifier to exact subpath is
 in `docs/generated/migration-broad-imports.md` (`node_modules/themelia-ui/docs/generated/migration-broad-imports.md`).
 
 ## What is not a compatibility surface
 
-- **Component tokens.** Component-level custom properties are plumbing and may be renamed
-  or removed in any release. The global contract listed in
+- **Component tokens.** Component-level custom properties are implementation detail and may
+  be renamed or removed in any release. The global contract listed in
   `src/styles/TOKENS.md` (`node_modules/themelia-ui/src/styles/TOKENS.md`) is the contract.
 - **CSS class names.** CSS Modules hashes them. The stable DOM hooks are the
   `{kebab-name}--component` classes and the `data-slot` attributes.
@@ -165,7 +230,6 @@ in `docs/generated/migration-broad-imports.md` (`node_modules/themelia-ui/docs/g
 
 After changing versions, type-check and build the consuming application against the installed
 package rather than a source alias. Run its unit, interaction, accessibility, and production
-bundle checks, then exercise the adopted families across the app's themes and density modes.
-You do not need this repository's scripts or source tree.
+bundle checks, then exercise the adopted modules across the app's themes and density modes.
 
 The focused matrix is in [Verifying a consuming application](verification.md).

package/.agents/skills/themelia-ui/references/provider-and-scoping.md

@@ -47,7 +47,7 @@ When an application embeds another:
 </UIScope>
 ```
 
-Its `config` is its **own overrides only**; inherited values already cascade in.
+Its `config` holds its **own overrides only**; the rest comes from the enclosing provider.
 
 `transparent` (default `true`) removes the element from layout with `display: contents`.
 Custom properties still inherit through it, because inheritance does not depend on the box.
@@ -60,7 +60,7 @@ below a slice as well as at it:
 ```tsx fragment — shape only, not a program
 <UIProvider config={{ theme: { colors: { primary: "blue", secondary: "green" } } }}>
   <UIScope config={{ theme: { colors: { primary: "red" } } }}>
-    {/* primary is red, secondary is still green */}
+    {/* useUIConfig().theme.colors: primary "red", secondary "green" */}
   </UIScope>
 </UIProvider>
 ```
@@ -69,6 +69,14 @@ This applies to every record-shaped field: `theme.colors`, `theme.palette`, `the
 `typography.fonts`, `typography.sizes` and `motion.durations`. Below them a record is a flat
 map of token to value, and a value is replaced, not merged.
 
+That is the configuration components read, and the CSS follows it: each scope writes the
+merged overrides on its element, so inside the nested scope above `--primary` is red and
+`--secondary` is green. Raw inputs (palette steps, radii, fonts, durations and the scale
+factors) inherit through every boundary. Semantic colours and type sizes do not: a `Scope`,
+or any other element on the boundary list, declares them again from the palette. To keep a
+colour across one of those, set it through `theme.palette` or declare it at the boundary
+list; see [Theming](theming.md#setting-a-theme).
+
 ## Scope — tokens only
 
 Overriding a factor requires a **scope boundary**, not just any element:
@@ -79,6 +87,9 @@ Overriding a factor requires a **scope boundary**, not just any element:
 </Scope>
 ```
 
+`Scope` renders a `div` without layout. `render` picks another element, as on every
+component (`render={<section />}`), and `transparent={false}` gives it a box.
+
 Derived tokens are declared at `:root, [data-ui-scope], [data-density], [data-theme], .light,
 .dark` (see `src/styles/SCOPES.md` (`node_modules/themelia-ui/src/styles/SCOPES.md`)). A plain
 `<div style={{ "--density-scale": 0.8 }}>` sets the variable and nothing reads it: the
@@ -113,7 +124,8 @@ Wrap the region in `UIPortalHost` and the popups render inside it instead:
 
 The host renders one `display: contents` element inside the scope, and every portal in the
 subtree targets it, so the popup inherits from the scope. DropdownMenu, ContextMenu, Select,
-Tooltip, HoverCard, Popover, NavigationMenu and Toaster all resolve it.
+Combobox, Tooltip, HoverCard, Popover, NavigationMenu and Toaster all resolve it. An
+`Overlay` needs no host: it renders in place, and the popups inside it portal into it.
 
 Precedence, most specific first:
 
@@ -163,7 +175,7 @@ ship the scrollbar rule in the consuming application's stylesheet:
 ```
 
 `disableStyleElements` does not disable kit behavior; it moves those small rules into the
-consuming app. It does not replace the normal `core.css`, family CSS, or `style.css` import.
+consuming app. It does not replace the normal `core.css`, module stylesheet, or `style.css` import.
 
 ## Reading the config
 
@@ -180,7 +192,7 @@ provider, so read `useDefaults` rather than hard-coding a size or variant.
 `useMoneyConfig`, `useDatesConfig`, `useOverlayConfig`, `useDensity`, `useScale`,
 `useFormatting`, `useTypographyConfig`. `useDefaults` takes the component's *own* defaults
 and merges the scope's over them, which keeps the values beside the component, makes the
-call order-independent, and lets an unused family tree-shake away.
+call order-independent, and lets an unused module tree-shake away.
 
 The provider holds stable display policy: money, dates, size, density, scale. Per-feature
 policy, query timing, domain accessors, data and callbacks stay props.
@@ -195,8 +207,8 @@ still take precedence over provider defaults.
 and supplies that state to its provider. Its internal editor state alone does not change
 an enclosing provider. Keep unfinished text edits separate from applied configuration:
 for example, validate a locale with `Intl.getCanonicalLocales` before passing it to
-formatting components. The [Theme Tweaker recipe](components/features--theme-tweaker.md)
-shows this wiring and keeps the last valid preview while a locale is being typed.
+formatting components. [Editing a theme at runtime](theming.md#editing-a-theme-at-runtime)
+shows the wiring.
 
 ## Optional iPhone input zoom prevention