npm - themelia-ui - Versions diffs - 2.0.1 → 3.1.0 - Mend

themelia-ui 2.0.1 → 3.1.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 (2005) hide show

package/.agents/skills/themelia-ui/references/components/ui-provider.md DELETED Viewed

@@ -1,726 +0,0 @@
-<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
-# `ui-provider`
-Setting display defaults, theme, density and scale for the app or a subtree.
-## Selection
-- **Use when:** Setting display defaults, theme, density and scale for the app or a subtree.
-- **Avoid when:** The value is per-feature policy or domain data, which stays a prop.
-- **Consider instead:** `features/theme-tweaker`
-- **Stability:** stable.
-## Import
-```tsx fragment — import-only example
-import { CSPProvider } from "themelia-ui/ui-provider"
-```
-## Composition
-This family has no component-family dependencies.
-Application policy—routing, fetching, persistence, permissions, and translation—stays
-outside the package and arrives through the public props, callbacks, slots, or accessors below.
-## Public declarations
-### `ColorScheme`
-Kind: type.
-```text
-"light" | "dark" | "system"
-```
-### `ComponentDefaults`
-Kind: interface.
-Per-component prop defaults. Empty here; each family augments it from its own directory:
-```ts fragment — declaration JSDoc excerpt
-declare module "@/lib/ui-provider" {
-  interface ComponentDefaults {
-    button: { tone: ButtonTone; buttonStyle: ButtonStyle }
-  }
-}
-```
-No own members are present in the normalized public snapshot.
-### `ComponentScale`
-Kind: type.
-```text
-(typeof COMPONENT_SCALES)[number]
-```
-### `configToAttributes`
-Kind: callable.
-Attributes the stylesheet keys off. Density is an attribute, not a variable, so the
-preset values stay in styles/tokens/foundation.css and a bare `data-density` works too.
-```text
-(config: UIConfig) => Record<string, string | undefined>
-```
-### `configToCssVars`
-Kind: callable.
-Translates the token-bearing half of a config into CSS custom properties, returned as a
-style object for the scope's own element so nesting merges through the cascade.
-The rule: a value that can be a token is CSS; a decision a component makes in JavaScript
-stays in context. Nothing appears in both.
-```text
-(config: UIConfig) => Record<string, string>
-```
-### `CSPProvider`
-Kind: callable.
-```text
-(props: CSPProviderProps) => import("react").JSX.Element
-```
-### `CSPProviderProps`
-Kind: interface.
-Configures the inline style/script policy used by Base UI-backed kit components.
-Supply the request's nonce when inline elements are allowed by nonce, or set
-`disableStyleElements` when the consuming app provides the equivalent CSS itself.
-Extends: `Pick<BaseCSPProviderProps, "children" | "nonce" | "disableStyleElements">`.
-No own members are present in the normalized public snapshot.
-### `DatesConfig`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `weekStartsOn` | no | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | First day of the week in calendars and pickers. 0 = Sunday. |
-| `format` | no | `string` | date-fns pattern the date primitives fall back to. |
-| `timeFormat` | no | `string` | date-fns pattern for a time of day. `"p"` uses the locale's own convention. |
-| `locale` | no | `Locale` | The date-fns locale object that translates month and weekday names. Not derived from<br>`formatting.locale`, so the bundle carries only the locale the consumer imports. |
-| `formatRelativeTime` | no | `(date: Date, now: Date) => string` | Replaces the relative-time wording ("7 days ago", "in 2 hours"). |
-### `DEFAULT_UI_CONFIG`
-Kind: const.
-```text
-ResolvedUIConfig
-```
-### `Density`
-Kind: type.
-Spacing and control-geometry preset. Sets `--density-scale` through `data-density`.
-```text
-"compact" | "default" | "comfortable"
-```
-### `FormattingConfig`
-Kind: interface.
-The locale shared by every formatter. Money and dates have their own slices.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `locale` | no | `string` | BCP-47 tag used by every Intl formatter in the kit. |
-### `FormsConfig`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `preventIPhoneZoom` | no | `boolean` | Opt in to a 16px minimum for native text fields on detected iPhones only. Default false. |
-### `mergeUIConfig`
-Kind: callable.
-Merges a config over its parent. A scope inherits everything it does not name, down to
-the record fields: setting `theme.colors.primary` keeps the parent's other colours.
-```text
-(parent: ResolvedUIConfig, config?: UIConfig) => ResolvedUIConfig
-```
-### `MoneyConfig`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `defaultCurrency` | no | `string` | Used when a `<Money>` is given no currency. |
-| `displayCurrency` | no | `string` | A converted currency shown beside the primary one. |
-| `dualPricingEnabled` | no | `boolean` | The master switch. Off, a `secondary` passed at a call site still renders. |
-| `displayMode` | no | `MoneyDisplayMode` |  |
-| `layout` | no | `MoneyLayout` |  |
-| `formatMode` | no | `MoneyFormatMode` |  |
-### `MoneyDisplayMode`
-Kind: type.
-Whether a second currency shows. `dynamic` shows it only when the two codes differ.
-```text
-"primary-only" | "dual" | "dynamic"
-```
-### `MoneyFormatMode`
-Kind: type.
-How an amount is written. Separate from WHICH currency it is in.
-```text
-"decimal" | "with-code" | "with-symbol"
-```
-### `MoneyLayout`
-Kind: type.
-Where the second value sits.
-```text
-"inline" | "stacked"
-```
-### `MoneySecondaryEmphasis`
-Kind: type.
-How loud the second value is against the first.
-```text
-"discrete" | "muted" | "match" | "hidden"
-```
-### `MotionConfig`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `durations` | no | `Partial<Record<"instant" \| "fast" \| "normal", string>>` | Duration overrides, keyed without the `--duration-` prefix. |
-| `reduced` | no | `boolean` | `true` forces motion off; unset respects `prefers-reduced-motion`. |
-### `OverlayConfig`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `backdropBlur` | no | `number \| string` | Blur behind a modal's scrim, in px (a number) or any CSS length. Off by default: a<br>backdrop filter repaints everything behind the surface each frame. |
-| `darkMenus` | no | `boolean` | Dropdown and context menus render in the dark scheme whatever the page is. Default<br>`true`; `false` lets them follow the scheme they are portalled into, like other popups.<br>A config value, not a CSS switch: Firefox lacks CSS `if()`. |
-### `PaletteToken`
-Kind: type.
-Primitive ramp steps. Overriding one moves every semantic that resolves through it.
-```text
-"brand-300" | "brand-350" | "brand-600" | "brand-950" | "danger-400" | "danger-600" | "danger-950" | "info-400" | "info-600" | "info-950" | "link-400" | "link-600" | "neutral-0" | "neutral-100" | "neutral-150" | "neutral-200" | "neutral-25" | "neutral-400" | "neutral-50" | "neutral-500" | "neutral-550" | "neutral-700" | "neutral-75" | "neutral-750" | "neutral-800" | "neutral-850" | "neutral-875" | "neutral-900" | "neutral-950" | "pure-black" | "series-1" | "series-1-dark" | "series-2" | "series-2-dark" | "series-3" | "series-3-dark" | "series-4" | "series-4-dark" | "series-5" | "series-5-dark" | "success-400" | "success-600" | "success-950" | "violet-500" | "warning-300" | "warning-500" | "warning-700" | "warning-900" | "warning-950" | "white-a10" | "white-a15"
-```
-### `ResolvedUIConfig`
-Kind: interface.
-A config with every JS-side decision resolved. Token slices stay partial by design.
-Extends: `UIConfig`.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `colorScheme` | yes | `ColorScheme` |  |
-| `overlay` | yes | `OverlayConfig & { darkMenus: boolean; }` |  |
-| `density` | yes | `Density` |  |
-| `scale` | yes | `number` |  |
-| `typography` | yes | `TypographyConfig & { defaultTextSize: TextSize; }` |  |
-| `formatting` | yes | `Required<FormattingConfig>` |  |
-| `money` | yes | `Required<Omit<MoneyConfig, "displayCurrency">> & Pick<MoneyConfig, "displayCurrency">` | `displayCurrency` stays optional: having none is the ordinary case, not a gap. |
-| `dates` | yes | `Required<Omit<DatesConfig, "locale" \| "formatRelativeTime">> & Pick<DatesConfig, "locale" \| "formatRelativeTime">` | `locale` and `formatRelativeTime` stay optional: English is built in. |
-### `Scope`
-Kind: callable.
-`<Scope>` — a token boundary without the config machinery. Derived tokens re-compute
-only at a scope boundary (styles/SCOPES.md), so a factor set on a plain `div` changes
-nothing; this renders `data-ui-scope`. Use `<UIProvider>` when JavaScript config changes too.
-  <Scope vars={{ "--density-scale": 0.8 }}>
-    <Toolbar />
-  </Scope>
-```text
-({ vars, as: Tag, transparent, className, style, children, }: { vars: Record<string, string | number>; as?: ElementType; transparent?: boolean; className?: string; style?: CSSProperties; children: ReactNode; }) => import("react").JSX.Element
-```
-### `SemanticToken`
-Kind: type.
-Semantic tokens a consumer may retheme. Values carry meaning, not raw colour.
-```text
-"accent" | "accent-foreground" | "background" | "border" | "card" | "card-foreground" | "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "destructive" | "destructive-accent" | "destructive-foreground" | "foreground" | "info" | "info-foreground" | "input" | "inverse-background" | "inverse-border" | "inverse-decoration" | "inverse-disabled" | "inverse-foreground" | "inverse-muted" | "inverse-subtle" | "inverse-surface" | "inverse-surface-strong" | "link-color" | "muted" | "muted-foreground" | "popover" | "popover-foreground" | "primary" | "primary-accent" | "primary-foreground" | "ring" | "secondary" | "secondary-foreground" | "sidebar" | "sidebar-accent" | "sidebar-accent-foreground" | "sidebar-border" | "sidebar-foreground" | "sidebar-primary" | "sidebar-primary-foreground" | "sidebar-ring" | "success" | "success-foreground" | "warning" | "warning-accent" | "warning-foreground"
-```
-### `TextSize`
-Kind: type.
-Step on the type scale. `inherit` lets the surrounding size flow through.
-`xxs` is deprecated: it renders as `xs`, so write `xs`.
-```text
-"inherit" | "xxs" | "xs" | "pxs" | "sm" | "base" | "lg" | "xl"
-```
-### `ThemeConfig`
-Kind: interface.
-Theme overrides. Token names are generated from the stylesheet, so a typo is a type error.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `radius` | no | `string` | The container radius — cards, dialogs, popovers, menus. Writes `--radius`. |
-| `radiusSm` | no | `string` | The inner radius — controls, rows, chips, badges, tooltips. Writes `--radius-sm`.<br>Not derived from `radius`: set both. |
-| `colors` | no | `Partial<Record<SemanticToken, string>>` | Semantic colour overrides. Prefer these to `palette`. |
-| `palette` | no | `Partial<Record<PaletteToken, string>>` | Primitive ramp overrides: moves every semantic resolving through the step. |
-| `vars` | no | `Record<string, string>` | Escape hatch for custom properties the kit does not define. Keys omit `--`. |
-### `TypographyConfig`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `scale` | no | `number` | Type factor (`--text-scale`): multiplies every type role, control labels included, and<br>leaves geometry alone. Unset, type follows `scale`. |
-| `defaultTextSize` | no | `TextSize` | Size components fall back to when they set none. Defaults to `sm` (14px). |
-| `fonts` | no | `Partial<Record<"sans" \| "serif" \| "mono" \| "heading", string>>` | Font stack overrides. |
-| `sizes` | no | `Partial<Record<Exclude<TextSize, "inherit">, string>>` | Per-step size overrides, keyed without the `--text-` prefix. |
-### `UIConfig`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `colorScheme` | no | `ColorScheme` | Colour scheme. `system` follows `prefers-color-scheme`. |
-| `theme` | no | `ThemeConfig` |  |
-| `density` | no | `Density` | Named spacing/control-density preset. Readable typography is unchanged. |
-| `scale` | no | `number` | Whole-UI factor (`--scale`). Default 1. Multiplies geometry, spacing, icons and type; use<br>`density` or `typography.scale` to move only one of them. |
-| `typography` | no | `TypographyConfig` |  |
-| `motion` | no | `MotionConfig` |  |
-| `overlay` | no | `OverlayConfig` |  |
-| `forms` | no | `FormsConfig` |  |
-| `formatting` | no | `FormattingConfig` |  |
-| `money` | no | `MoneyConfig` |  |
-| `dates` | no | `DatesConfig` |  |
-| `defaults` | no | `{ [K in keyof ComponentDefaults]?: Partial<ComponentDefaults[K]>; }` |  |
-### `UIConfigContext`
-Kind: const.
-```text
-import('react').Context<ResolvedUIConfig>
-```
-### `UIDocumentTarget`
-Kind: type.
-Where a root may mirror its attributes, or `false` to leave the document alone.
-```text
-"documentElement" | "body" | false
-```
-### `UINestedContext`
-Kind: const.
-```text
-import('react').Context<boolean>
-```
-### `UIPortalContainer`
-Kind: type.
-Where a popup should render so it keeps its scope. Theme and density inherit down the
-DOM, so popups portal into an element inside the scope rather than `document.body`.
-```text
-HTMLElement | ShadowRoot | null
-```
-### `UIPortalHost`
-Kind: callable.
-Keeps popups inside this subtree, so they inherit the scope's custom properties and
-`[data-density]` / `[data-theme]` attributes instead of the root's.
-```tsx fragment — declaration JSDoc excerpt
-<UIScope config={{ density: "compact", colorScheme: "dark" }}>
-  <UIPortalHost>
-    <DropdownMenu>…</DropdownMenu>
-  </UIPortalHost>
-</UIScope>
-```
-Opt-in per region; without a host, popups portal to the document as usual.
-```text
-({ container, children }: UIPortalHostProps) => import("react").JSX.Element
-```
-### `UIPortalHostProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `container` | no | `UIPortalContainer` | Portal into this element (a shadow root, an app-managed layer) instead of one the host renders. |
-| `children` | yes | `ReactNode` |  |
-### `UIProvider`
-Kind: callable.
-`<UIProvider>` — composes `UIRoot` and `UIScope`: outermost, a root that themes
-`documentElement` plus a scope; nested, a scope only. Prefer `UIRoot` and `UIScope`
-directly, which let a root decline the document.
-```text
-({ config, transparent, className, style, children }: UIProviderProps) => import("react").JSX.Element
-```
-### `UIProviderProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `config` | no | `UIConfig` | Merged over the enclosing provider, or over the library defaults at the root. |
-| `transparent` | no | `boolean` | Removes the wrapper from layout with `display: contents`; custom properties still<br>inherit. Set `false` when the scope should be a real box, such as a themed panel. |
-| `className` | no | `string` |  |
-| `style` | no | `CSSProperties` |  |
-| `children` | yes | `ReactNode` |  |
-### `UIRoot`
-Kind: callable.
-`<UIRoot>` — the application's configuration, once. Renders no element; region scoping
-is `UIScope`, which does.
-```text
-({ config, documentTarget, children }: UIRootProps) => import("react").JSX.Element
-```
-### `UIRootProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `config` | no | `UIConfig` | The application's defaults. Merged over the library's own. |
-| `documentTarget` | no | `UIDocumentTarget` | Which element gets the theme and density attributes, or `false` (default) for none.<br>Opt-in because it writes outside the tree, which could fight another root or an app's<br>own `data-theme`; it is the only way a root can theme the page canvas. |
-| `children` | yes | `ReactNode` |  |
-### `UIScope`
-Kind: callable.
-`<UIScope>` — a region with its own tokens. Nests freely; writes only its own custom
-property overrides and never touches the document. `render` picks the element, e.g.
-`<UIScope render={<aside />}>`, for places a `div` is invalid.
-```text
-({ config, transparent, render, className, style, ...props }: UIScopeProps) => import("react").JSX.Element
-```
-### `UIScopeProps`
-Kind: interface.
-Extends: `useRender.ComponentProps<"div">`.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `config` | no | `UIConfig` | Merged over the nearest enclosing scope or root. |
-| `transparent` | no | `boolean` | Removes the element from layout with `display: contents`; custom properties still<br>inherit. Set `false` when the scope should be a real box, such as a themed panel. |
-### `useDatesConfig`
-Kind: callable.
-Week start, the fallback pattern, the date-fns locale, and the relative-time hook.
-```text
-() => Required<Omit<DatesConfig, "locale" | "formatRelativeTime">> & Pick<DatesConfig, "locale" | "formatRelativeTime">
-```
-### `useDefaults`
-Kind: callable.
-Per-component prop defaults for one family: the component passes its own defaults and
-the scope's overrides merge on top, so defaults stay beside their component.
-```text
-(family: K, fallback: ComponentDefaults[K]) => ComponentDefaults[K]
-```
-### `useDensity`
-Kind: callable.
-```text
-() => { density: Density; scale: number; }
-```
-### `useFormatting`
-Kind: callable.
-The scope's locale. Money and dates read it through their own hooks as well.
-```text
-() => Required<FormattingConfig>
-```
-### `useMoneyConfig`
-Kind: callable.
-Currency policy — the default code, the display code, and how a pair is rendered.
-```text
-() => Required<Omit<MoneyConfig, "displayCurrency">> & Pick<MoneyConfig, "displayCurrency">
-```
-### `useOverlayConfig`
-Kind: callable.
-Overlay policy — whether menus render dark, and the modal scrim's blur.
-```text
-() => OverlayConfig & { darkMenus: boolean; }
-```
-### `useScale`
-Kind: callable.
-The scope's geometry factor. Components read tokens, not this — it is for callers.
-```text
-() => number
-```
-### `useTypographyConfig`
-Kind: callable.
-```text
-() => TypographyConfig & { defaultTextSize: TextSize; }
-```
-### `useUIConfig`
-Kind: callable.
-The whole resolved config for this scope. Prefer a narrower hook below.
-```text
-() => ResolvedUIConfig
-```
-### `useUIPortalContainer`
-Kind: callable.
-The container a portal in this subtree should use: the caller's `explicit` value, else
-the nearest `UIPortalHost`, else `undefined` so the primitive keeps its own default.
-```text
-(explicit?: UIPortalContainer) => UIPortalContainer | undefined
-```
-## Preview recipes
-Preview route: Dropdown & context menu — `/dropdown-menu`
-### Dark by default, decided by the provider
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIProvider config={{ overlay: { darkMenus: false } }}>
-  <App />
-</UIProvider>
-```
-### Scale
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Scope vars={{ "--density-scale": 0.875 }}>…</Scope>
-```
-### Decided once, not per call site
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIProvider config={{ defaults: { sheet: { size: "26rem", inset: true } } }}>
-  <App />
-</UIProvider>
-```
-### A blurred scrim, when a product wants one
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIProvider config={{ overlay: { backdropBlur: 4 } }}>
-  <App />
-</UIProvider>
-```
-### In another language
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-import { de } from "date-fns/locale"
-<UIProvider config={{ dates: { locale: de } }}>…</UIProvider>
-{/* or hand the wording over completely */}
-<UIProvider
-  config={{ dates: { formatRelativeTime: (date, now) => t.relative(date, now) } }}
-/>
-```
-### The factor
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIProvider config={{ scale: 0.875 }}>
-  <Toolbar />
-</UIProvider>
-```
-### Why not size props
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-{/* smaller type, control geometry untouched */}
-<UIProvider config={{ typography: { scale: 0.875 } }}>…</UIProvider>
-{/* denser geometry, type held at its default */}
-<UIProvider config={{ scale: 0.875, typography: { scale: 1 } }}>…</UIProvider>
-```
-### Two levels of control
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-/* everything denser */
-<UIProvider config={{ scale: 0.875 }}>
-/* heights and rows only — gaps untouched */
-<Scope vars={{ "--density-scale": 0.875 }}>
-/* gaps and padding only — control heights untouched */
-<Scope vars={{ "--density-scale": 0.875 }}>
-/* one measurement, leaving everything else alone */
-<Scope vars={{ "--button-h": "2.75rem" }}>
-/* a plain div does NOT work: overriding a factor needs a scope
-   boundary, or the measurements above it have already resolved. */
-```
-### Why two factors, and no third
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIProvider config={{ scale: 1.125 }}>
-  <Page>
-    <UIProvider config={{ scale: 0.875 }}>
-      <Toolbar />
-    </UIProvider>
-  </Page>
-</UIProvider>
-```
-### Density presets
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIProvider config={{ density: "compact" }}>…</UIProvider>
-{/* or, with no provider at all */}
-<div data-density="compact">…</div>
-```
-### Semantic tier
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIProvider config={{ theme: { colors: { primary: "oklch(0.55 0.2 25)" } } }}>
-```
-### A scope is a region
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIScope config={{ density: "compact" }}>
-  <Toolbar />
-</UIScope>
-```
-### Nesting merges
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIScope config={{ colorScheme: "dark" }}>
-  <UIScope config={{ density: "compact" }}>…</UIScope>
-</UIScope>
-```
-### render decides the element
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIScope render={<aside />} config={{ density: "compact" }}>…</UIScope>
-```
-### Popups stay inside the scope
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<UIScope config={{ density: "compact" }}>
-  <UIPortalHost>
-    <DropdownMenu>
-      <DropdownMenuTrigger render={<Button>Actions</Button>} />
-      <DropdownMenuContent>
-        <DropdownMenuItem>Duplicate</DropdownMenuItem>
-      </DropdownMenuContent>
-    </DropdownMenu>
-  </UIPortalHost>
-</UIScope>
-```