themelia-ui 3.0.0 → 3.2.0

package/dist/lib/component-vocabulary.d.ts

@@ -1,5 +1,5 @@
-/** Canonical three-step scale for package-owned component recipes. */
-export declare const COMPONENT_SCALES: readonly ["sm", "md", "lg"];
+/** Canonical two-step scale for package-owned component recipes: the default and a smaller one. */
+export declare const COMPONENT_SCALES: readonly ["default", "sm"];
 export type ComponentScale = (typeof COMPONENT_SCALES)[number];
 /** Canonical semantic colour intent for package-owned presentation. */
 export declare const SEMANTIC_TONES: readonly ["neutral", "primary", "secondary", "info", "success", "warning", "destructive"];

package/dist/lib/css-length.d.ts

@@ -0,0 +1,2 @@
+/** A CSS length: a number with a unit or a percentage, or a math or `var()` expression. */
+export type CssLength = `${number}${"px" | "rem" | "em" | "ch" | "%" | "vw" | "vh" | "dvw" | "dvh" | "svw" | "svh" | "lvw" | "lvh"}` | `${"calc" | "min" | "max" | "clamp" | "var"}(${string})`;

package/dist/lib/responsive.d.ts

@@ -2,7 +2,7 @@ import { CSSProperties } from 'react';
 export type Breakpoint = "base" | "sm" | "md" | "lg" | "xl" | "2xl";
 export declare const BREAKPOINTS: Breakpoint[];
 /**
- * Each `--bp-*` min-width from styles/theming/breakpoints.css in px (rem × 16), for the
+ * Each `--bp-*` min-width from styles/breakpoints.css in px (rem × 16), for the
  * JavaScript that cannot read a custom media query. responsive.test.ts holds them in step.
  */
 export declare const BREAKPOINT_MIN_WIDTH: Record<Exclude<Breakpoint, "base">, number>;

package/dist/lib/theming/index.d.ts

@@ -2,3 +2,4 @@ export { deriveThemeElevation, deriveThemePalette, deriveThemeTypeScale } from '
 export type { ThemeElevationRecipe, ThemePaletteRecipe, ThemeTypeScaleRecipe } from './recipes.js';
 export { INK, PAPER, readableForeground, type ForegroundChoice } from './contrast.js';
 export type { ThemeMode, ThemeOverrides, ThemeVariableName } from './types.js';
+export { themes, type ThemeName, type ThemePreset } from './themes/index.js';

package/dist/lib/theming/recipes.d.ts

@@ -17,7 +17,7 @@ export interface ThemeElevationRecipe {
 export declare function deriveThemePalette({ primary, mode }: ThemePaletteRecipe): ThemeOverrides;
 export declare function deriveThemeTypeScale({ baseSize, ratio, }: ThemeTypeScaleRecipe): ThemeOverrides;
 /**
- * The whole shadow ladder from one intensity: the default theme's geometry and
- * `--shadow-ink`, with every layer's ink scaled so 0.8 reproduces it exactly.
+ * The two shadows from one intensity: the default theme's geometry, with every layer's ink
+ * scaled so 0.8 reproduces it exactly.
  */
 export declare function deriveThemeElevation({ intensity }: ThemeElevationRecipe): ThemeOverrides;

package/dist/lib/theming/themes/dense.d.ts

@@ -0,0 +1,3 @@
+import { ThemePreset } from './types.js';
+/** Dense: blue on cool neutrals, compact spacing, small corners and bordered cards, for screens full of data. */
+export declare const dense: ThemePreset;

package/dist/lib/theming/themes/editorial.d.ts

@@ -0,0 +1,3 @@
+import { ThemePreset } from './types.js';
+/** Editorial: terracotta on warm paper, serif headings, a step larger type and generous spacing, for reading. */
+export declare const editorial: ThemePreset;

package/dist/lib/theming/themes/index.d.ts

@@ -0,0 +1,8 @@
+export declare const themes: {
+    soft: import('./types.js').ThemePreset;
+    sharp: import('./types.js').ThemePreset;
+    dense: import('./types.js').ThemePreset;
+    editorial: import('./types.js').ThemePreset;
+};
+export type ThemeName = keyof typeof themes;
+export type { ThemePreset } from './types.js';

package/dist/lib/theming/themes/pair.d.ts

@@ -0,0 +1,7 @@
+/** A colour for both modes: the half each element's `color-scheme` picks. */
+export declare const pair: (light: string, dark: string) => string;
+/**
+ * No shadow, written as one. A popup lists `--shadow-lg` after its hairline, and `none` cannot
+ * stand in a list: the whole declaration would drop, taking the hairline with it.
+ */
+export declare const NO_SHADOW = "0 0 transparent";

package/dist/lib/theming/themes/sharp.d.ts

@@ -0,0 +1,3 @@
+import { ThemePreset } from './types.js';
+/** Sharp: monochrome ink, square corners, hairlines instead of shadows, and quick motion. Links keep the kit's blue, so a link still reads as one without its underline. */
+export declare const sharp: ThemePreset;

package/dist/lib/theming/themes/soft.d.ts

@@ -0,0 +1,3 @@
+import { ThemePreset } from './types.js';
+/** Soft: violet on rosy neutrals, large corners, diffuse shadows, comfortable spacing and gentler motion. */
+export declare const soft: ThemePreset;

package/dist/lib/theming/themes/types.d.ts

@@ -0,0 +1,12 @@
+import { UIConfig } from '../../ui-provider/index.js';
+/**
+ * A ready-made theme: the name a picker shows, one line on what it is for, and the provider
+ * config it sets. The config reaches past colour: radii, shadows and border weight (`theme`),
+ * spacing (`density`), type (`typography`), motion, and how components draw themselves
+ * (`defaults`). Pass `config` to `UIProvider`, or spread it under settings of your own.
+ */
+export interface ThemePreset {
+    label: string;
+    description: string;
+    config: UIConfig;
+}

package/dist/lib/ui-provider/index.d.ts

@@ -8,4 +8,4 @@ export { UIConfigContext, UINestedContext, mergeUIConfig, type UIPortalContainer
 export { DEFAULT_UI_CONFIG } from './defaults.js';
 export { configToCssVars, configToAttributes } from './tokens.js';
 export { useUIConfig, useFormatting, useMoneyConfig, useDatesConfig, useOverlayConfig, useTypographyConfig, useDensity, useScale, useDefaults, useUIPortalContainer, } from './hooks.js';
-export type { ColorScheme, ComponentDefaults, ComponentScale, Density, DatesConfig, FormattingConfig, FormsConfig, MoneyConfig, MoneyDisplayMode, MoneyFormatMode, MoneyLayout, MoneySecondaryEmphasis, MotionConfig, OverlayConfig, PaletteToken, ResolvedUIConfig, SemanticToken, TextSize, ThemeConfig, TypographyConfig, UIConfig, } from './types.js';
+export type { ColorScheme, ComponentDefaults, ComponentScale, Density, DatesConfig, FormattingConfig, FormsConfig, MoneyConfig, MoneyDisplayMode, MoneyFormatMode, MoneyLayout, MoneySecondaryEmphasis, MotionConfig, OverlayConfig, ResolvedUIConfig, SemanticToken, TextSize, ThemeConfig, TypographyConfig, UIConfig, } from './types.js';

package/dist/lib/ui-provider/scope.d.ts

@@ -6,15 +6,12 @@ export interface ScopeProps extends useRender.ComponentProps<"div"> {
     transparent?: boolean;
 }
 /**
- * `<Scope>` — a token boundary without the config machinery. Overriding a factor needs a
- * scope boundary, not just any element: derived tokens are declared at `:root`,
- * `[data-ui-scope]`, `[data-density]`, `[data-theme]`, `.light` and `.dark`, so a plain
- * `div` that sets `--density-scale` sets a variable nothing reads. Scope renders
- * `data-ui-scope`, which puts the element on that list. Use it when the change is purely
- * tokens, and `<UIProvider>` when JavaScript config changes too. `render` picks the element,
- * e.g. `render={<section />}`.
+ * `<Scope>` — a region with its own theme variables, without the config machinery. Every
+ * component inside reads the variables it sets, and the element leaves layout alone. Use it
+ * when the change is purely variables, and `<UIProvider>` when JavaScript config changes
+ * too. `render` picks the element, e.g. `render={<section />}`.
  *
- *   <Scope vars={{ "--density-scale": 0.8 }}>
+ *   <Scope vars={{ "--control-height": "2.5rem" }}>
  *     <Toolbar />
  *   </Scope>
  */

package/dist/lib/ui-provider/tokens.d.ts

@@ -1,14 +1,22 @@
-import { UIConfig } from './types.js';
+import { ResolvedUIConfig, UIConfig } from './types.js';
 /**
  * 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.
+ *
+ * `scale` is computed here rather than in CSS: it writes the spacing, control and icon
+ * lengths themselves, from the density in effect (`resolved`, when a scope inherits one), and
+ * the type factor. CSS never multiplies a factor except Text's own `--text-scale`. A scope
+ * that changes density under a scaled ancestor writes its lengths at the inherited scale,
+ * since the ancestor's lengths reach it inline and would outrank the preset.
  */
-export declare function configToCssVars(config: UIConfig): Record<string, string>;
+export declare function configToCssVars(config: UIConfig, resolved?: ResolvedUIConfig): Record<string, string>;
 /**
  * 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.
+ * preset values stay in styles/theme/density.css and a bare `data-density` works too.
+ * `default` writes nothing, so the theme's own lengths, a consumer's `:root` overrides
+ * included, apply; a scope resetting a denser region writes it itself (UIScope).
  */
 export declare function configToAttributes(config: UIConfig): Record<string, string | undefined>;

package/dist/lib/ui-provider/tokens.generated.d.ts

@@ -1,4 +1,6 @@
-/** Semantic tokens a consumer may retheme. Values carry meaning, not raw colour. */
-export type SemanticToken = "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";
-/** Primitive ramp steps. Overriding one moves every semantic that resolves through it. */
-export type PaletteToken = "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";
+/** Colour variables a consumer may retheme, named without the leading `--`. */
+export type SemanticToken = "accent" | "accent-foreground" | "background" | "border" | "card" | "card-foreground" | "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "destructive" | "destructive-foreground" | "foreground" | "info" | "info-foreground" | "input" | "link" | "muted" | "muted-foreground" | "overlay-backdrop" | "popover" | "popover-foreground" | "primary" | "primary-foreground" | "ring" | "secondary" | "secondary-foreground" | "sidebar" | "sidebar-accent" | "sidebar-accent-foreground" | "sidebar-border" | "sidebar-foreground" | "sidebar-ring" | "success" | "success-foreground" | "warning" | "warning-foreground";
+/** Every theme variable. */
+export type ThemeVariable = "--accent" | "--accent-foreground" | "--background" | "--border" | "--border-width" | "--card" | "--card-foreground" | "--chart-1" | "--chart-2" | "--chart-3" | "--chart-4" | "--chart-5" | "--content-width" | "--control-height" | "--control-height-sm" | "--destructive" | "--destructive-foreground" | "--disabled-opacity" | "--duration" | "--duration-fast" | "--ease" | "--font-heading" | "--font-mono" | "--font-sans" | "--foreground" | "--gap" | "--gap-sm" | "--header-height" | "--icon-size" | "--icon-size-sm" | "--info" | "--info-foreground" | "--input" | "--link" | "--muted" | "--muted-foreground" | "--overlay-backdrop" | "--overlay-backdrop-filter" | "--padding" | "--padding-sm" | "--popover" | "--popover-foreground" | "--primary" | "--primary-foreground" | "--radius" | "--radius-pill" | "--radius-sm" | "--ring" | "--secondary" | "--secondary-foreground" | "--shadow" | "--shadow-lg" | "--sidebar" | "--sidebar-accent" | "--sidebar-accent-foreground" | "--sidebar-border" | "--sidebar-foreground" | "--sidebar-ring" | "--sidebar-width" | "--success" | "--success-foreground" | "--text-2xl" | "--text-base" | "--text-lg" | "--text-pxs" | "--text-scale" | "--text-sm" | "--text-xl" | "--text-xs" | "--tint" | "--tint-strong" | "--warning" | "--warning-foreground" | "--z-docked" | "--z-popover" | "--z-sticky" | "--z-toast" | "--z-tooltip";
+/** Each theme variable's declared value; a colour is `light-dark(light, dark)`. */
+export declare const THEME_DEFAULTS: Readonly<Record<ThemeVariable, string>>;

package/dist/lib/ui-provider/types.d.ts

@@ -1,15 +1,12 @@
 import { Locale } from 'date-fns';
 import { ComponentScale } from '../component-vocabulary.js';
-import { PaletteToken, SemanticToken } from './tokens.generated.js';
+import { SemanticToken } from './tokens.generated.js';
 export type { ComponentScale };
-export type { PaletteToken, SemanticToken };
-/** Spacing and control-geometry preset. Sets `--density-scale` through `data-density`. */
+export type { SemanticToken };
+/** Spacing and control-height preset, set through `data-density` (styles/theme/density.css). */
 export type Density = "compact" | "default" | "comfortable";
-/**
- * Step on the type scale. `inherit` lets the surrounding size flow through.
- * `xxs` is deprecated: it renders as `xs`, so write `xs`.
- */
-export type TextSize = "inherit" | "xxs" | "xs" | "pxs" | "sm" | "base" | "lg" | "xl";
+/** Step on the type scale. `inherit` lets the surrounding size flow through. */
+export type TextSize = "inherit" | "xs" | "pxs" | "sm" | "base" | "lg" | "xl";
 export type ColorScheme = "light" | "dark" | "system";
 /** Theme overrides. Token names are generated from the stylesheet, so a typo is a type error. */
 export interface ThemeConfig {
@@ -20,10 +17,11 @@ export interface ThemeConfig {
      * Not derived from `radius`: set both.
      */
     radiusSm?: string;
-    /** Semantic colour overrides. Prefer these to `palette`. */
+    /**
+     * Colour overrides, one value for both modes or a `light-dark(light, dark)` pair. Keys
+     * omit `--`.
+     */
     colors?: Partial<Record<SemanticToken, string>>;
-    /** Primitive ramp overrides: moves every semantic resolving through the step. */
-    palette?: Partial<Record<PaletteToken, string>>;
     /** Escape hatch for custom properties the kit does not define. Keys omit `--`. */
     vars?: Record<string, string>;
 }
@@ -47,8 +45,8 @@ export interface TypographyConfig {
     sizes?: Partial<Record<Exclude<TextSize, "inherit">, string>>;
 }
 export interface MotionConfig {
-    /** Duration overrides, keyed without the `--duration-` prefix. */
-    durations?: Partial<Record<"instant" | "fast" | "normal", string>>;
+    /** The two durations: `fast` writes `--duration-fast`, `normal` writes `--duration`. */
+    durations?: Partial<Record<"fast" | "normal", string>>;
     /** `true` forces motion off; unset respects `prefers-reduced-motion`. */
     reduced?: boolean;
 }
@@ -160,7 +158,7 @@ export interface DatesConfig {
  * ```ts
  * declare module "@/lib/ui-provider" {
  *   interface ComponentDefaults {
- *     button: { tone: ButtonTone; buttonStyle: ButtonStyle }
+ *     button: { tone: ButtonTone; appearance: ButtonAppearance }
  *   }
  * }
  * ```
@@ -177,17 +175,17 @@ export interface UIConfig {
      * @default "system"
      */
     colorScheme?: ColorScheme;
-    /** Radius, colour, palette and custom-property overrides. */
+    /** Radius, colour and custom-property overrides. */
     theme?: ThemeConfig;
     /**
-     * Named spacing and control-geometry preset: `compact`, `default` and `comfortable` scale
-     * by 0.941176 (32px actions), 1 and 1.075. Readable typography is unchanged.
+     * Named spacing and control-height preset. `compact` sets 12px insets and gaps and 32px
+     * controls, `default` 16px and 34px, `comfortable` 20px and 36px. Type keeps its size.
      * @default "default"
      */
     density?: Density;
     /**
-     * Master factor (`--scale`). Geometry, spacing, icons and the type ramp follow it by
-     * default; use `density` or `typography.scale` to move only one of them.
+     * Master factor. The provider writes the spacing, control and icon lengths at this scale,
+     * rounded to whole pixels, and type follows it unless `typography.scale` is set.
      * @default 1
      */
     scale?: number;

package/dist/lib/ui-provider/ui-scope.d.ts

@@ -17,7 +17,7 @@ export interface UIScopeProps extends useRender.ComponentProps<"div"> {
  * `<UIScope>` — a region with its own tokens. Nests freely; writes the custom properties
  * its merged config names and never touches the document: a region governs its subtree,
  * and reaching past it is the root's job, and only when asked. `render` picks the element
- * — Base UI's contract, the same one Item and Stack use — e.g. `<UIScope render={<aside />}>`,
+ * through Base UI's element-substitution contract, e.g. `<UIScope render={<aside />}>`,
  * for places a `div` is invalid.
  */
 export declare function UIScope({ config, transparent, render, className, style, ...props }: UIScopeProps): import("react").JSX.Element;