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/learn/provider-and-scoping.md ADDED Viewed

@@ -0,0 +1,204 @@
+# Provider and scoping
+Three components, and the difference between them is what they are allowed to touch.
+| | Renders | Reaches | Use for |
+|---|---|---|---|
+| `UIRoot` | nothing | the document, if asked | the application's defaults, once per React root |
+| `UIScope` | an element (or nothing) | its subtree | a region that differs from the app |
+| `Scope` | an element | its subtree | a token override with no JavaScript config |
+`UIProvider` composes `UIRoot` and `UIScope` and behaves as it always has. New code should
+reach for the piece it actually needs.
+## UIRoot — once, at the top
+```tsx fragment — shape only, not a program
+<UIRoot config={{ money: { defaultCurrency: "EUR" }, density: "compact" }} documentTarget="documentElement">
+  <App />
+</UIRoot>
+```
+It renders **no element**. 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 that expected their real child.
+`documentTarget` is `false` by default and must be named explicitly. Mirroring theme and
+density onto `<html>` or `<body>` is the only way a root can own the page canvas, and it is
+also the only thing here that touches state outside the React tree. A component that reaches
+for the document unasked fights the next React root, the next test, and any application
+already managing its own `data-theme`.
+Two behaviours matter when an application embeds another:
+- **It restores, it does not remove.** What each attribute was before mount is captured and
+  put back on unmount. The earlier version deleted them, so a provider unmounting inside an
+  app that had set its own theme took that theme with it.
+- **One owner at a time, and it is handed on.** Two independent React roots — a host and an
+  embedded widget — both believe they are the top. Each *asks* for the document; the oldest
+  root still mounted owns it, and the rest leave it alone. When the owner unmounts the
+  document goes to the next root in line rather than reverting, so a widget still on the page
+  is still honoured. `body` and `documentElement` are tracked separately: a root on one does
+  not block a root on the other.
+  What the page looked like before the **first** root arrived is what a final unmount
+  restores — not what the previous owner had written.
+## UIScope — a region
+```tsx fragment — shape only, not a program
+<UIScope config={{ density: "comfortable" }}>
+  <SettingsPanel />
+</UIScope>
+```
+Its `config` is its **own overrides only** — inherited values already cascade in. This is
+worth stating because the opposite is an easy bug to write and a hard one to see: an earlier
+implementation rebuilt the attributes from the raw prop rather than the resolved config, so
+every nested boundary silently reset the theme to the default.
+`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.
+### What a nested config merges
+A scope names what it is **changing**. Everything it does not name it inherits — and that
+holds one level below a slice as well as at it:
+```tsx fragment — shape only, not a program
+<UIRoot config={{ theme: { colors: { primary: "blue", secondary: "green" } } }}>
+  <UIScope config={{ theme: { colors: { primary: "red" } } }}>
+    {/* primary is red, secondary is still green */}
+  </UIScope>
+</UIRoot>
+```
+This applies to every record-shaped field: `theme.colors`, `theme.palette`, `theme.vars`,
+`typography.fonts`, `typography.sizes` and `motion.durations`. Merging stops there, because
+below them a record is a flat map of token to value and a value is replaced, not merged.
+Earlier the merge stopped at the slice, so naming one colour replaced the whole record and
+discarded the rest of the palette — with no error, and nothing in the DOM to say where it
+went.
+## Scope — tokens only
+Overriding a factor requires a **scope boundary**, not just any element:
+```tsx fragment — shape only, not a program
+<Scope vars={{ "--density-scale": 0.8 }}>
+  <Toolbar />
+</Scope>
+```
+Derived tokens are declared at `:root, [data-ui-scope], [data-density], [data-theme], .light,
+.dark` (see [`src/styles/SCOPES.md`](../../src/styles/SCOPES.md)). A plain
+`<div style={{ "--density-scale": 0.8 }}>` sets the variable and nothing reads it — the
+measurements above it already resolved against the old value. `Scope` renders
+`data-ui-scope`, which puts the element on that list and makes every derived token
+re-compute.
+## Portals and scopes
+Both mechanisms a scope uses — CSS custom properties, and the `[data-density]` /
+`[data-theme]` attribute selectors — work by inheritance down the DOM subtree. A portal
+renders somewhere else in the document, so by default neither follows it:
+```tsx fragment — a template with a hole in it
+<UIScope config={{ density: "compact" }}>
+  <DropdownMenu>…</DropdownMenu>   {/* the menu portals to the body, at the ROOT's density */}
+</UIScope>
+```
+Wrap the region in `UIPortalHost` and the popups render inside it instead:
+```tsx fragment — a template with a hole in it
+<UIScope config={{ density: "compact", colorScheme: "dark" }}>
+  <UIPortalHost>
+    <DropdownMenu>
+      <DropdownMenuTrigger>Actions</DropdownMenuTrigger>
+      <DropdownMenuContent>…</DropdownMenuContent>
+    </DropdownMenu>
+  </UIPortalHost>
+</UIScope>
+```
+The host renders one `display: contents` element inside the scope, and every portal in the
+subtree targets it — so the popup is back under the element carrying the scope and ordinary
+inheritance does the rest. DropdownMenu, ContextMenu, Select, Tooltip, HoverCard, Popover,
+NavigationMenu and Toaster all resolve it.
+Precedence, most specific first:
+1. a `container` prop on the component;
+2. the nearest `UIPortalHost`;
+3. the primitive's own default.
+Without a host nothing changes, so adding one is opt-in per region. `UIPortalHost` also
+takes a `container` of its own, for an application that already has a layer it wants popups
+in — a shadow root, or a positioned overlay element it manages itself.
+> An outer `createPortal` around a component does **not** redirect the portal that component
+> creates inside itself. This page used to suggest it did; it never worked, because the
+> portal is created by the component, not by its caller.
+The published behavior is verified for DropdownMenu, ContextMenu, Select, Tooltip,
+HoverCard, Popover, NavigationMenu, and Toaster, including the underlying inheritance rule.
+## Strict Content Security Policy
+Some Base UI-backed controls emit a tiny inline style or pre-hydration script for behavior
+that cannot be expressed by the component stylesheet alone. Put `CSPProvider` at the same
+application boundary as `UIRoot` and pass the request nonce through:
+```tsx fragment — requestNonce, config, and App come from the consuming application
+import { CSPProvider, UIRoot } from "themelia-ui/ui-provider"
+<CSPProvider nonce={requestNonce}>
+  <UIRoot config={config} documentTarget="documentElement">
+    <App />
+  </UIRoot>
+</CSPProvider>
+```
+React 19 hoists styles that carry `precedence`. During streaming SSR, configure the React
+renderer with the same style nonce as the provider; otherwise React deliberately omits the
+attribute and warns about the mismatch.
+When the policy permits no inline elements at all, suppress Base UI's style elements and
+ship the scrollbar rule in the consuming application's stylesheet:
+```tsx fragment — App comes from the consuming application
+<CSPProvider disableStyleElements>
+  <App />
+</CSPProvider>
+```
+```css
+.base-ui-disable-scrollbar { scrollbar-width: none; }
+.base-ui-disable-scrollbar::-webkit-scrollbar { display: none; }
+```
+`disableStyleElements` does not disable kit behavior; it transfers ownership of those
+small rules to the consuming app. It also does not replace the normal `core.css`, family
+CSS, or `style.css` import.
+## Reading the config
+Resolution, in every component:
+```ts fragment — shape only, not a program
+props.value ?? useFooConfig().value ?? componentFallback
+```
+A consumer who passes a prop always wins. A component that pins a prop internally takes the
+choice away from the provider — which is why library code reads `useDefaults` rather than
+hard-coding a size or variant.
+`useUIConfig` returns everything and re-renders on any change; prefer the narrow hook —
+`useMoneyConfig`, `useDatesConfig`, `useDensity`, `useScale`, `useFormatting`,
+`useTypographyConfig`. `useDefaults` is the one components use: it 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.
+What belongs in the provider is stable display policy — money, dates, size, density, scale.
+Per-feature policy, query timing, domain accessors, data and callbacks stay props.

package/docs/learn/theming.md ADDED Viewed

@@ -0,0 +1,177 @@
+# Theming
+A theme author may set **166 names** and stops. Most rebrands begin with the 55 palette,
+semantic-colour, radius, and shadow seeds in the default theme; the exhaustive contract also
+includes the public type, spacing, motion, focus, and layering controls, documented in full in
+[`src/styles/TOKENS.md`](../../src/styles/TOKENS.md).
+The kit also declares a larger component-token layer. Those names are plumbing, not the
+theme-authoring surface: most are a
+`var()` off the contract, and the rest are geometry no theme would touch
+(`--separator-thickness: 1px`). Quoting the component count as if it were the theming surface
+is what makes a kit look unthemeable. The generated token report records the current measured
+counts, and release verification holds both layers to a ceiling
+and fails a component token that does not earn its name — one that does no arithmetic, is
+never re-pointed by a variant or scope, and is not written from JavaScript.
+## Setting a theme
+Declare the contract's names wherever you want them to apply:
+```css
+:root {
+  --primary: oklch(0.55 0.19 250);
+  --radius-md: 10px;
+}
+```
+For a subtree, use a scope boundary rather than a bare element — see
+[Provider and scoping](./provider-and-scoping.md#scope--tokens-only). Derived tokens resolve
+**where they are declared**, so a variable set on an element that is not a boundary is set
+and never read.
+## Scale
+Four factors, and no per-family ones:
+| Factor | Multiplies |
+|---|---|
+| `--scale` | everything, unless a more specific factor overrides |
+| `--space-scale` | spacing steps |
+| `--density-scale` | control heights and row rhythm |
+| `--text-scale` | the type scale |
+The three specific ones default to `--scale`, so setting `--scale` alone moves the whole
+system. `UIProvider`'s `typography.scale` overrides `--text-scale` for every text role in a
+scope—including control labels—without changing its geometry. [`src/styles/FACTORS.md`](../../src/styles/FACTORS.md)
+is the authority.
+Named `density` presets override only `--space-scale` and `--density-scale`. Compact and
+comfortable regions therefore change spacing, control heights, and row rhythm without
+shrinking or enlarging readable typography. Use explicit `scale` when the entire scoped UI
+should move together.
+The ability to scale one *family* alone was removed deliberately: it cost 215 tokens, and of
+385 references carrying a family factor, 217 turned out to be a spacing step that already had
+a name. So a family-shaped token name is not a tuning seam — `--sidebar-p: var(--space-md)`
+buys nothing a consumer can reach, and 82 such names were removed with no pixel changing.
+Package verification rejects measurements that multiply by `--scale` without declaring a
+factor, or multiply by two factors at once. Consumers should use the four public factors
+rather than reconstructing component calculations.
+## Dark mode
+Three signals, all answered:
+```css
+.dark { … }
+[data-theme="dark"] { … }
+@media (prefers-color-scheme: dark) { … }
+```
+Release verification rejects a dark-only override that answers fewer than all three, because
+an app that toggles a class and an app that sets an attribute are both normal, and honouring
+only one leaves the other half-themed.
+In CSS Modules, `.dark` is hashed like any other class. A dark rule must be written
+`:global(.dark)` or it matches nothing — which looks exactly like a theme that does not work
+and reads exactly like a theme that should.
+## Runtime theming
+`features/theme-tweaker` changes theme, density and scale at runtime and persists the result.
+Use it when users make the choice; use `UIRoot` config when the application makes it once.
+## Synthesising a theme in code
+`themelia-ui/theming` turns one brand colour into a coherent set of overrides, with no
+React in the import:
+```ts compile
+import { deriveThemePalette, readableForeground } from "themelia-ui/theming"
+const overrides = deriveThemePalette({ primary: "#3b82f6" })
+// { "--primary": "#3b82f6", "--primary-foreground": "oklch(0.18 0.01 260)", … }
+```
+The derived values stay CSS — `color-mix(in oklch, var(--primary) 10%, var(--background))`
+rather than a computed literal — so they keep following the tokens they derive from.
+Computing them in JavaScript would freeze the relationship at the moment the recipe ran.
+`readableForeground(background)` **measures** WCAG contrast against both candidates and
+returns the better one, with the ratio and whether it clears AA:
+```ts fragment — one expression and its result, not a program
+readableForeground("#6366f1")
+// { color: "oklch(0.985 0 0)", ratio: 4.28, meetsAA: false, measured: true }
+```
+`meetsAA: false` is not a failure to handle — it is the honest answer for a seed where
+neither ink nor paper clears 4.5:1. Pick a darker or lighter brand, or set
+`--primary-foreground` yourself.
+These are also re-exported from `features/theme-tweaker`, which is where they used to live.
+## Design tokens (DTCG)
+`themelia-ui/tokens.json` is the contract in [W3C DTCG][dtcg] format, for Figma and
+tools like Style Dictionary. Colours are OKLCH objects with a `hex` fallback:
+```json
+{ "$value": { "colorSpace": "oklch", "components": [0.45, 0.124, 167.35], "hex": "#00785f" } }
+```
+Two things it deliberately does not carry, both recorded in its own `$extensions`:
+- **`calc()` is resolved.** `--radius-md` exports as `0.5rem`. The number is right; the fact
+  that it follows `--radius` is lost, because DTCG has no arithmetic.
+- **Shadows are absent.** Each is a multi-layer shadow whose colour is a `color-mix`, and
+  resolving it would bake one theme's ink in and present it as the contract.
+The published DTCG artifact is checked so every `$type` is valid, every value matches its
+type, and every `{reference}` resolves — including that no dark token aliases a skipped light
+token.
+[dtcg]: https://www.designtokens.org/TR/drafts/format/
+## Tailwind CSS v4
+The kit ships no Tailwind and needs none. If your application already uses Tailwind v4,
+import the bridge and its utilities resolve against this contract:
+```css
+@import "tailwindcss";
+@import "themelia-ui/core.css";
+@import "themelia-ui/tailwind.css";
+```
+`bg-primary` is `var(--primary)`, `rounded-surface` is the kit's surface radius, `p-md` is
+`var(--space-md)`, `text-sm` is `calc(0.875rem * var(--text-scale))`. Every utility reads the
+token **at the element**, so a `.dark` subtree, a `[data-density="compact"]` scope and a
+nested `UIProvider` all move Tailwind's output the way they move the kit's own.
+**Import it even if you never write a kit-token utility.** The two projects both descend
+from shadcn, so **41 custom-property names collide** — the whole `--radius-*` ladder,
+`--text-xs` through `--text-2xl`, `--shadow-*`, `--font-sans/serif/mono`, `--leading-*`,
+`--ease-*`. Tailwind emits its defaults onto `:root` inside `@layer theme`, and a consumer
+who imports the kit first puts that layer **above** the kit's `tokens` layer. Without the
+bridge, Tailwind wins 23 of those names:
+| what | kit | Tailwind takes it to |
+| --- | --- | --- |
+| `--radius-lg` | `var(--radius)` — 10px, and follows `--radius` | `0.5rem`, fixed |
+| `--text-sm` | `calc(0.875rem * var(--text-scale))` | `0.875rem` — **scoped type scaling stops working** |
+| `--font-sans` | Inter first | Tailwind's system stack |
+| `--animate-pulse` | `cubic-bezier(0.4, 0, 0.2, 1)` | `cubic-bezier(0.4, 0, 0.6, 1)` |
+None of that shows up in the CSS you wrote; it shows up as a slightly wrong radius and a
+density control that stops working. The bridge restates those names with the kit's own
+definitions so the override is a no-op.
+`themelia-ui/tailwind.css` is generated from the same public tokens and checked against
+them. The package's Tailwind v4 consumer fixture compiles the integration and measures the
+resolved values in a browser, including a paired build without the bridge.
+The bridge is a `@theme inline` declaration and nothing else: no rules, no utilities, and
+Tailwind drops every key no utility uses, so importing it costs nothing you do not use.

package/docs/learn/troubleshooting.md ADDED Viewed

@@ -0,0 +1,75 @@
+# Troubleshooting
+## A component is unstyled
+Import its exact family stylesheet beside the JavaScript subpath, or import the complete
+`themelia-ui/style.css` once. A family stylesheet already imports `core.css`; importing
+core alone supplies tokens but no component rules.
+Keep application overrides after package CSS. The package uses cascade layers, so ordinary
+unlayered application CSS wins without `!important` or selector escalation.
+## A subpath does not resolve
+There are no layer barrels such as `themelia-ui/base`. Use the generated
+[import table](../generated/imports.md) or run:
+```bash
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs "what the UI must do"
+```
+Import the returned exact family path and its returned CSS path.
+## An optional peer is missing
+Install only the peers listed for the imported family. The generated import table maps every
+optional peer to the exact families that reach it. If the error names a peer for a family not
+listed there, report it as a package containment defect.
+## A scoped theme or density does not apply
+Set tokens on `UIProvider`, `UIRoot`, `UIScope`, `[data-ui-scope]`, a supported theme signal,
+or another documented scope boundary. Derived custom properties resolve where they are
+declared; setting a source value on an arbitrary descendant can leave its already-resolved
+derived value unchanged. See [Theming](./theming.md) and
+[Provider and scoping](./provider-and-scoping.md).
+## A portal has the wrong theme
+Mount the provider above both the trigger and portal host, and use the package overlay or
+portal surface rather than an unrelated portal root. The provider propagates attributes and
+variables through the supported portal path; a separate DOM root cannot inherit from a
+scope it is not under.
+## A controlled component appears frozen
+A controlled value changes only when the consumer feeds the new value back. Connect the
+documented change callback to state, cache, or URL ownership. If the application does not
+need ownership, omit the controlled prop and use the family's documented default-value API
+when one exists.
+## A link behaves like a button
+Use the `render` or `renderLink` seam with the framework's link element. Do not simulate
+navigation in a click handler. The package's polymorphic contract preserves the rendered
+element's semantics while applying the component's behaviour and geometry.
+## CSP blocks runtime styles
+Use `CSPProvider` with the request nonce. For a policy that forbids style elements entirely,
+set `disableStyleElements` and serve the documented Base UI behaviour rules from an external
+stylesheet. Family CSS itself is ordinary static CSS.
+## The design looks inconsistent after overrides
+Override global semantic tokens first: colour roles, radius, spacing/density, typography,
+and control geometry. Component-level variables are implementation plumbing unless the
+family reference explicitly describes one as an extension point. Avoid overriding hashed
+CSS Module names; target stable `data-slot`, `data-state`, or BEM hooks.
+## Rich text and untrusted HTML
+`RichTextEditor` and editor engines keep drafts unsanitized. Render stored HTML with
+`RichText`, which always sanitizes through an allow-list. Any application-owned
+`dangerouslySetInnerHTML` remains the application's responsibility; see `SECURITY.md` in the
+package root.

package/docs/learn/verification.md ADDED Viewed

@@ -0,0 +1,49 @@
+# Verifying a consuming application
+Package verification proves the published artifacts agree with this repository. A consumer
+still needs a small application-level matrix because routing, data, permissions, copy, and
+theme overrides belong to the application.
+## Minimum release checks
+1. Type-check against the installed package, not a source alias.
+2. Build the production bundle and confirm no optional peer is requested by unused families.
+3. Render every adopted family in light and dark themes.
+4. Exercise compact and comfortable density, plus any custom scale used by the product.
+5. Test keyboard traversal, focus return, dismissal, disabled state, loading state, and
+   destructive confirmations for interactive families.
+6. Run automated accessibility checks, then manually verify names, descriptions, focus
+   order, landmarks, and screen-reader announcements for the product composition.
+7. Check narrow mobile, ordinary desktop, and one wide viewport; include long translated
+   copy, empty data, errors, and the largest plausible record.
+8. Verify CSP and server-rendering paths when the application uses them.
+## A focused smoke test
+```tsx fragment — adapt selectors and navigation to the consuming application's test runner
+test("global search returns focus after dismissal", async ({ page }) => {
+  await page.goto("/app")
+  await page.getByRole("button", { name: "Search" }).click()
+  await expect(page.getByRole("dialog")).toBeVisible()
+  await page.keyboard.press("Escape")
+  await expect(page.getByRole("button", { name: "Search" })).toBeFocused()
+})
+```
+Prefer role- and name-based assertions over CSS Module selectors. `data-slot`, `data-state`,
+and documented BEM hooks are stable when a visual or state assertion genuinely needs a DOM
+hook.
+## Theme contract check
+Create one application fixture that changes primary colour, surface/background roles,
+radius, density, and typography scale at a scope boundary. If a component ignores that
+fixture, report the family and token rather than adding a local patch first—the failure may
+be a missing derivation in the package.
+## Upgrade check
+Read `CHANGELOG.md`, run the package's codemod when a release names one, and compare the
+installed declaration surface through the application's own type-check. Stable 1.x removals
+must carry a deprecated alias for the remainder of the major unless keeping it would be
+unsafe or incorrect; see [API compatibility](./api-compatibility.md).