eidos-ui 2.0.0 → 3.0.0

package/README.md

@@ -19,14 +19,14 @@
 
 ## Features
 
-|                     |                                                                                                                        |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Themeable**       | Every design token is a CSS custom property, so palette, spacing, and radii can be overridden without touching source. |
-| **Type-safe**       | Written in TypeScript with full prop typings exported for every component.                                             |
-| **Tree-shakeable**  | Per-component entry points (`eidos-ui/button`, `eidos-ui/table`, ...) keep bundles lean.                               |
-| **Icon-agnostic**   | Works with any icon library - Lucide, MUI Icons, Font Awesome, Remix Icons, or your own.                               |
-| **Accessible**      | Built with keyboard navigation and ARIA semantics in mind.                                                             |
-| **Optimized build** | Bundled with tsup, shipping both ESM and CJS with source maps and `.d.ts` files.                                       |
+|                     |                                                                                                                                                        |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Themeable**       | Every design token is a CSS custom property. Override them statically, or let users change the palette and typography at runtime with `ThemeProvider`. |
+| **Type-safe**       | Written in TypeScript with full prop typings exported for every component.                                                                             |
+| **Tree-shakeable**  | Per-component entry points (`eidos-ui/button`, `eidos-ui/table`, ...) keep bundles lean.                                                               |
+| **Icon-agnostic**   | Works with any icon library - Lucide, MUI Icons, Font Awesome, Remix Icons, or your own.                                                               |
+| **Accessible**      | Built with keyboard navigation and ARIA semantics in mind.                                                                                             |
+| **Optimized build** | Bundled with tsup, shipping both ESM and CJS with source maps and `.d.ts` files.                                                                       |
 
 ## Installation
 
@@ -45,6 +45,7 @@ npm install lucide-react
 ```tsx
 import { Button, Tooltip } from 'eidos-ui';
 import 'eidos-ui/styles';
+import 'eidos-ui/fonts'; // optional - bundled Plus Jakarta Sans + JetBrains Mono
 
 function App() {
   return (
@@ -91,6 +92,11 @@ These are the same groups used in Storybook, so the README and the docs sidebar
 - Toolbar
 - Breadcrumb
 
+**Theming**
+
+- ThemeProvider
+- ThemeEditor
+
 **Elements**
 
 - Button
@@ -120,7 +126,6 @@ These are the same groups used in Storybook, so the README and the docs sidebar
 - Switch
 - Slider
 - ColorPicker
-- DatePicker
 - OTPInput
 - TagInput
 - FileUpload
@@ -139,7 +144,9 @@ These are the same groups used in Storybook, so the README and the docs sidebar
 **Data**
 
 - Table
+- TableFiltersDropdown
 - DataGrid
+- DatePicker
 - Timeline
 - VirtualList
 
@@ -180,15 +187,19 @@ npm run storybook
 
 ## Theming
 
-All design tokens are exposed as CSS custom properties, so themes can be overridden globally without touching component source.
+Every design token is a CSS custom property. There are two ways to change them, depending on whether the theme is fixed at build time or chosen by the user.
+
+### Static overrides
+
+Redeclare any token in your own stylesheet:
 
 ```css
 :root {
-  /* Colors */
-  --primary-color: #6366f1;
-  --secondary-color: #ec4899;
+  /* Colours - each family also has -dark, -light, -rgb and -contrast */
+  --primary-color: #5c5de8;
+  --secondary-color: #617087;
 
-  /* Spacing */
+  /* Spacing (em-based, so it scales with font size) */
   --spacing-md: 1em;
   --spacing-lg: 1.5em;
 
@@ -197,15 +208,54 @@ All design tokens are exposed as CSS custom properties, so themes can be overrid
 }
 ```
 
-Individual component styles can also be targeted directly, following each component's `eidos-<name>` BEM-style class names:
+Individual components can also be targeted directly, following each component's `eidos-<name>` BEM-style class names:
 
 ```css
 .eidos-button--filled.eidos-button--primary {
   border-radius: 20px;
-  background: linear-gradient(to right, #6366f1, #8b5cf6);
+  background: linear-gradient(to right, #5c5de8, #8b5cf6);
 }
 ```
 
+### Runtime theming
+
+`ThemeProvider` applies a theme at runtime — for a settings screen, a per-tenant palette, or a colour a user picks. Supply one base colour per family and the shades, tints, ramp steps and accessible foregrounds are derived from it:
+
+```tsx
+import { ThemeProvider, ThemeEditor } from 'eidos-ui';
+
+<ThemeProvider defaultTheme={{ colors: { primary: '#0ea5e9' } }}>
+  <App />
+</ThemeProvider>;
+```
+
+`ThemeEditor` is a ready-made panel for editing the active theme, with live WCAG contrast readouts per colour:
+
+```tsx
+<ThemeProvider theme={theme} onThemeChange={saveThemeForUser}>
+  <ThemeEditor />
+  <App />
+</ThemeProvider>
+```
+
+Ten things are editable — seven colour bases, two font stacks, and a font scale. Tokens are written through the CSSOM to `document.documentElement`, which needs **no Content Security Policy allowance** and covers portaled overlays too. A theme equal to the preset writes nothing at all.
+
+Use `useTheme()` to read or change it from your own UI, and `toCss()` to export the resolved tokens as a `:root` block you can paste into a stylesheet — useful for baking a theme in at build time.
+
+### Fonts
+
+The theme names Plus Jakarta Sans and JetBrains Mono, but a font stack only _names_ families — it cannot install them. Import the bundled copies to actually use them:
+
+```ts
+import 'eidos-ui/fonts';
+```
+
+This is a separate entry point because these are the only rules in the library that fetch a subresource; importing it means allowing `font-src 'self'` (already covered by `default-src 'self'`). Skip it and the stylesheet fetches nothing, falling back to system fonts.
+
+For a font of your own, `registerFontFace(family, arrayBuffer)` registers one at runtime with no CSP allowance at all.
+
+See the **Theming** and **Content Security Policy** pages in Storybook for the full reference.
+
 ## TypeScript
 
 Every component ships with exported prop types:

package/dist/Avatar.types-BY-C09Ke.d.cts

@@ -0,0 +1,23 @@
+import React__default from 'react';
+
+type AvatarSize = 'sm' | 'md' | 'lg';
+type AvatarColor = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'gray';
+interface AvatarProps {
+    src?: string;
+    alt?: string;
+    name?: string;
+    size?: AvatarSize;
+    color?: AvatarColor;
+    shape?: 'circle' | 'square';
+    fallback?: React__default.ReactNode;
+    className?: string;
+    onClick?: () => void;
+}
+interface AvatarGroupProps {
+    children: React__default.ReactNode;
+    max?: number;
+    size?: AvatarSize;
+    className?: string;
+}
+
+export type { AvatarColor as A, AvatarGroupProps as a, AvatarProps as b, AvatarSize as c };

package/dist/Avatar.types-BY-C09Ke.d.ts

@@ -0,0 +1,23 @@
+import React__default from 'react';
+
+type AvatarSize = 'sm' | 'md' | 'lg';
+type AvatarColor = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'gray';
+interface AvatarProps {
+    src?: string;
+    alt?: string;
+    name?: string;
+    size?: AvatarSize;
+    color?: AvatarColor;
+    shape?: 'circle' | 'square';
+    fallback?: React__default.ReactNode;
+    className?: string;
+    onClick?: () => void;
+}
+interface AvatarGroupProps {
+    children: React__default.ReactNode;
+    max?: number;
+    size?: AvatarSize;
+    className?: string;
+}
+
+export type { AvatarColor as A, AvatarGroupProps as a, AvatarProps as b, AvatarSize as c };

package/dist/{Header.types-BZi80bWz.d.cts → Header.types-B3QtuiL-.d.cts}

@@ -1,10 +1,14 @@
 import { T as TextButtonProps, I as IconButtonProps } from './Button.types-DZRCVqyN.cjs';
 
 interface HeaderProps {
-    /** Page or section title. */
-    title: string;
+    /**
+     * Page or section title. Accepts inline nodes alongside the text - a
+     * status `Pill`/`Chip` beside the title is the common case - not just a
+     * string. Keep the children inline-level; the title is a heading.
+     */
+    title: React.ReactNode;
     /** Supporting text rendered below the title. */
-    subtitle?: string | React.ReactNode;
+    subtitle?: React.ReactNode;
     /** Trailing action buttons, rendered right-aligned. */
     actions?: HeaderActionProps[];
     className?: string;

package/dist/{Header.types-DJt-q01P.d.ts → Header.types-C6w0FBY8.d.ts}

@@ -1,10 +1,14 @@
 import { T as TextButtonProps, I as IconButtonProps } from './Button.types-BH0CPyPx.js';
 
 interface HeaderProps {
-    /** Page or section title. */
-    title: string;
+    /**
+     * Page or section title. Accepts inline nodes alongside the text - a
+     * status `Pill`/`Chip` beside the title is the common case - not just a
+     * string. Keep the children inline-level; the title is a heading.
+     */
+    title: React.ReactNode;
     /** Supporting text rendered below the title. */
-    subtitle?: string | React.ReactNode;
+    subtitle?: React.ReactNode;
     /** Trailing action buttons, rendered right-aligned. */
     actions?: HeaderActionProps[];
     className?: string;

package/dist/{Table.types-Cl5gR8r9.d.cts → Table.types-CPj-udMc.d.cts}

@@ -85,9 +85,30 @@ interface TableColumnCommon {
     }[];
     dateFilterMode?: 'single' | 'multiple' | 'range';
     width?: string;
+    /**
+     * Cell text alignment. Applies in table mode only: card view renders each
+     * field as a label above its value, where aligning the value away from its
+     * own label reads as a misalignment rather than a choice.
+     *
+     * Ignored on `type: 'icon'` and `type: 'action'` columns, which are always
+     * centred - they hold a single control in a fixed-width cell, so there is
+     * nothing to align it within. `DataGrid`'s actions column behaves the same.
+     */
     align?: 'left' | 'center' | 'right';
     /** Enables position:sticky on this column */
     pin?: 'left' | 'right';
+    /**
+     * Render this column's value as the card's title instead of a label:value
+     * field row. Only the first column with `cardHeader` set is used - if
+     * several are marked, the rest render as normal fields.
+     */
+    cardHeader?: boolean;
+    /**
+     * Render this column's value as the card's subtitle, directly under the
+     * `cardHeader` value. Only the first column with `cardSubheader` set is
+     * used. Has no effect without a `cardHeader` column also being set.
+     */
+    cardSubheader?: boolean;
 }
 /**
  * A column bound to the row field named by `key`, which is what lets `render`
@@ -170,7 +191,48 @@ interface TableProps<T extends object = Record<string, unknown>> {
     rowKey?: RowKey<T>;
     selectedRows?: string[];
     defaultSelectedRows?: string[];
+    /**
+     * Fires with every selected key, plus the row object for each of those keys.
+     *
+     * `selectedKeys` is authoritative; `selectedRows` is best-effort. The row
+     * for each selected key is cached, so a row selected while it was rendered
+     * still comes back after `data` has moved on - but a key that was selected
+     * before the table ever saw its row (seeded via `defaultSelectedRows`, say)
+     * has no row to hand back.
+     */
     onSelectionChange?: (selectedKeys: string[], selectedRows: T[]) => void;
+    /**
+     * What the select-all control acts on - the header checkbox in table mode,
+     * or the toolbar checkbox in card view (where there is no header row):
+     *
+     * - `'all'` - every row in `data`, across pages.
+     * - `'page'` - only the rows currently rendered.
+     *
+     * Either way it only ever adds to or removes from the rows in its own
+     * scope, so a selection made on another page survives.
+     *
+     * `'all'` can only reach the rows the table actually holds: if `data` is one
+     * page of a larger set (with `totalItems` describing the whole), it cannot
+     * know the keys of rows it has never received, and says so with a dev-only
+     * warning. Matches `DataGrid.selectAllScope`.
+     *
+     * @default 'all'
+     */
+    selectAllScope?: 'all' | 'page';
+    /**
+     * Resolves the keys of **every** row matching the current query, including
+     * rows not present in `data`. Supplying it adds a "Select all N" action to
+     * the toolbar once everything the table does hold is selected.
+     *
+     * Only relevant when `data` is a subset of a larger set and `totalItems`
+     * describes the whole - a table paginating its own `data` already has every
+     * key. Called with no arguments, may be async (the action shows a loading
+     * state), and whatever it returns replaces the selection.
+     *
+     * Matches `DataGrid.onSelectAllMatching`, which is where this mostly earns
+     * its keep: `DataGrid` has a real server-side pagination mode.
+     */
+    onSelectAllMatching?: () => string[] | Promise<string[]>;
     bulkActions?: BulkAction<T>[];
     density?: 'compact' | 'comfortable' | 'spacious';
     showColumnVisibility?: boolean;
@@ -178,6 +240,39 @@ interface TableProps<T extends object = Record<string, unknown>> {
     showDensity?: boolean;
     draggableColumns?: boolean;
     onColumnReorder?: (newColumns: TableColumn<T>[]) => void;
+    /**
+     * On by default: below `cardViewBreakpoint`, or once the table's own width
+     * can no longer fit every visible column at a usable width, swap the table
+     * for a stacked list of cards - one per row. Only the row rendering
+     * changes; the toolbar, pagination, filtering, sorting and selection all
+     * keep working. `draggableColumns` has no effect in card view (there are no
+     * column headers to drag).
+     *
+     * Matches `DataGridProps.hasCardView` - both components use the same
+     * defaults and the same measured-container logic. Set to `false` to always
+     * render a table.
+     *
+     * @default true
+     */
+    hasCardView?: boolean;
+    /**
+     * Container width (px) at/below which card view kicks in. This is an
+     * explicit floor - card view also switches on automatically, regardless
+     * of this value, once the container can't fit every visible column at a
+     * usable minimum width, so a many-column table never has to overflow
+     * horizontally waiting for a hand-tuned breakpoint.
+     *
+     * @default 640
+     */
+    cardViewBreakpoint?: number;
+    /**
+     * Cards lay out in a responsive grid (CSS `repeat(auto-fill, minmax(...))`)
+     * rather than one per row - this sets the minimum width (px) a card can
+     * shrink to before the next one wraps to a new row.
+     *
+     * @default 280
+     */
+    cardMinWidth?: number;
 }
 
 export type { BulkAction as B, FilterValue as F, RowKey as R, TableColumn as T, BulkActionButton as a, BulkActionSplitButton as b, BulkActionSplitOption as c, TableCustomColumn as d, TableFilters as e, TableProps as f, TableValueColumn as g };

package/dist/{Table.types-jhPb7JNU.d.ts → Table.types-CZZ7QWAI.d.ts}

@@ -85,9 +85,30 @@ interface TableColumnCommon {
     }[];
     dateFilterMode?: 'single' | 'multiple' | 'range';
     width?: string;
+    /**
+     * Cell text alignment. Applies in table mode only: card view renders each
+     * field as a label above its value, where aligning the value away from its
+     * own label reads as a misalignment rather than a choice.
+     *
+     * Ignored on `type: 'icon'` and `type: 'action'` columns, which are always
+     * centred - they hold a single control in a fixed-width cell, so there is
+     * nothing to align it within. `DataGrid`'s actions column behaves the same.
+     */
     align?: 'left' | 'center' | 'right';
     /** Enables position:sticky on this column */
     pin?: 'left' | 'right';
+    /**
+     * Render this column's value as the card's title instead of a label:value
+     * field row. Only the first column with `cardHeader` set is used - if
+     * several are marked, the rest render as normal fields.
+     */
+    cardHeader?: boolean;
+    /**
+     * Render this column's value as the card's subtitle, directly under the
+     * `cardHeader` value. Only the first column with `cardSubheader` set is
+     * used. Has no effect without a `cardHeader` column also being set.
+     */
+    cardSubheader?: boolean;
 }
 /**
  * A column bound to the row field named by `key`, which is what lets `render`
@@ -170,7 +191,48 @@ interface TableProps<T extends object = Record<string, unknown>> {
     rowKey?: RowKey<T>;
     selectedRows?: string[];
     defaultSelectedRows?: string[];
+    /**
+     * Fires with every selected key, plus the row object for each of those keys.
+     *
+     * `selectedKeys` is authoritative; `selectedRows` is best-effort. The row
+     * for each selected key is cached, so a row selected while it was rendered
+     * still comes back after `data` has moved on - but a key that was selected
+     * before the table ever saw its row (seeded via `defaultSelectedRows`, say)
+     * has no row to hand back.
+     */
     onSelectionChange?: (selectedKeys: string[], selectedRows: T[]) => void;
+    /**
+     * What the select-all control acts on - the header checkbox in table mode,
+     * or the toolbar checkbox in card view (where there is no header row):
+     *
+     * - `'all'` - every row in `data`, across pages.
+     * - `'page'` - only the rows currently rendered.
+     *
+     * Either way it only ever adds to or removes from the rows in its own
+     * scope, so a selection made on another page survives.
+     *
+     * `'all'` can only reach the rows the table actually holds: if `data` is one
+     * page of a larger set (with `totalItems` describing the whole), it cannot
+     * know the keys of rows it has never received, and says so with a dev-only
+     * warning. Matches `DataGrid.selectAllScope`.
+     *
+     * @default 'all'
+     */
+    selectAllScope?: 'all' | 'page';
+    /**
+     * Resolves the keys of **every** row matching the current query, including
+     * rows not present in `data`. Supplying it adds a "Select all N" action to
+     * the toolbar once everything the table does hold is selected.
+     *
+     * Only relevant when `data` is a subset of a larger set and `totalItems`
+     * describes the whole - a table paginating its own `data` already has every
+     * key. Called with no arguments, may be async (the action shows a loading
+     * state), and whatever it returns replaces the selection.
+     *
+     * Matches `DataGrid.onSelectAllMatching`, which is where this mostly earns
+     * its keep: `DataGrid` has a real server-side pagination mode.
+     */
+    onSelectAllMatching?: () => string[] | Promise<string[]>;
     bulkActions?: BulkAction<T>[];
     density?: 'compact' | 'comfortable' | 'spacious';
     showColumnVisibility?: boolean;
@@ -178,6 +240,39 @@ interface TableProps<T extends object = Record<string, unknown>> {
     showDensity?: boolean;
     draggableColumns?: boolean;
     onColumnReorder?: (newColumns: TableColumn<T>[]) => void;
+    /**
+     * On by default: below `cardViewBreakpoint`, or once the table's own width
+     * can no longer fit every visible column at a usable width, swap the table
+     * for a stacked list of cards - one per row. Only the row rendering
+     * changes; the toolbar, pagination, filtering, sorting and selection all
+     * keep working. `draggableColumns` has no effect in card view (there are no
+     * column headers to drag).
+     *
+     * Matches `DataGridProps.hasCardView` - both components use the same
+     * defaults and the same measured-container logic. Set to `false` to always
+     * render a table.
+     *
+     * @default true
+     */
+    hasCardView?: boolean;
+    /**
+     * Container width (px) at/below which card view kicks in. This is an
+     * explicit floor - card view also switches on automatically, regardless
+     * of this value, once the container can't fit every visible column at a
+     * usable minimum width, so a many-column table never has to overflow
+     * horizontally waiting for a hand-tuned breakpoint.
+     *
+     * @default 640
+     */
+    cardViewBreakpoint?: number;
+    /**
+     * Cards lay out in a responsive grid (CSS `repeat(auto-fill, minmax(...))`)
+     * rather than one per row - this sets the minimum width (px) a card can
+     * shrink to before the next one wraps to a new row.
+     *
+     * @default 280
+     */
+    cardMinWidth?: number;
 }
 
 export type { BulkAction as B, FilterValue as F, RowKey as R, TableColumn as T, BulkActionButton as a, BulkActionSplitButton as b, BulkActionSplitOption as c, TableCustomColumn as d, TableFilters as e, TableProps as f, TableValueColumn as g };

package/dist/ThemeProvider.types-DgXN0gEH.d.cts

@@ -0,0 +1,88 @@
+import React__default from 'react';
+
+/** The seven themeable colour families. */
+type ThemeColorKey = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'hyperlink';
+/**
+ * A themeable colour: either a bare hex string, or an object that also pins the
+ * foreground to place on it.
+ *
+ * `contrast` exists because the provider writes tokens inline on
+ * `document.documentElement`, and inline styles beat author stylesheets - a
+ * consumer who must have a specific foreground could otherwise only override it
+ * with `!important`. Leave it unset to have it computed (see `pickContrast`).
+ */
+type ThemeColorValue = string | {
+    base: string;
+    contrast?: string;
+};
+type ThemeColors = Partial<Record<ThemeColorKey, ThemeColorValue>>;
+/** A selectable font stack, as offered by `ThemeEditor`. */
+interface ThemeFontOption {
+    /** Display name, e.g. "Plus Jakarta Sans". */
+    label: string;
+    /** The full CSS font stack written to the token. */
+    value: string;
+}
+interface ThemeTypography {
+    /** Replaces `--font-family-primary`. A full CSS font stack. */
+    fontFamily?: string;
+    /** Replaces `--font-family-mono`. A full CSS font stack. */
+    monoFamily?: string;
+    /**
+     * Multiplier applied to all eight `--font-size-*` tokens. 1 is the preset.
+     *
+     * Note that `--spacing-*` is declared in `em`, so this scales most padding
+     * and gaps along with the text rather than only the glyphs.
+     */
+    fontScale?: number;
+}
+/**
+ * A theme. Every field is optional and anything omitted falls back to
+ * `defaultTheme`, so a theme may be as small as one colour.
+ *
+ * Named `ThemeConfig` rather than `Theme` to avoid colliding with the `Theme`
+ * exported by MUI, styled-components and others in a consumer's namespace.
+ */
+interface ThemeConfig {
+    colors?: ThemeColors;
+    typography?: ThemeTypography;
+}
+/** A theme with every field populated - what the provider actually applies. */
+interface ResolvedTheme {
+    colors: Record<ThemeColorKey, {
+        base: string;
+        contrast?: string;
+    }>;
+    typography: Required<ThemeTypography>;
+}
+interface ThemeContextValue {
+    /** The theme as supplied, with omitted fields left absent. */
+    theme: ThemeConfig;
+    /** The same theme with every field filled in from the preset. */
+    resolvedTheme: ResolvedTheme;
+    /** Replaces the whole theme. */
+    setTheme: (theme: ThemeConfig) => void;
+    /** Deep-merges a partial theme into the current one. */
+    updateTheme: (patch: ThemeConfig) => void;
+    /** Returns to the preset. */
+    resetTheme: () => void;
+    /** True when nothing differs from the preset, so no tokens are being written. */
+    isDefault: boolean;
+    /** The resolved theme as a `:root { … }` CSS block. */
+    toCss: () => string;
+}
+interface ThemeProviderProps {
+    children: React__default.ReactNode;
+    /**
+     * Controlled theme. Pair with `onThemeChange` and own persistence yourself -
+     * this is the mode to use when the theme comes from a user record on your
+     * server.
+     */
+    theme?: ThemeConfig;
+    /** Initial theme for uncontrolled usage. Ignored when `theme` is supplied. */
+    defaultTheme?: ThemeConfig;
+    /** Fires whenever the theme changes, in both controlled and uncontrolled mode. */
+    onThemeChange?: (theme: ThemeConfig) => void;
+}
+
+export type { ResolvedTheme as R, ThemeColorKey as T, ThemeColorValue as a, ThemeColors as b, ThemeConfig as c, ThemeContextValue as d, ThemeFontOption as e, ThemeProviderProps as f, ThemeTypography as g };

package/dist/ThemeProvider.types-DgXN0gEH.d.ts

@@ -0,0 +1,88 @@
+import React__default from 'react';
+
+/** The seven themeable colour families. */
+type ThemeColorKey = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'hyperlink';
+/**
+ * A themeable colour: either a bare hex string, or an object that also pins the
+ * foreground to place on it.
+ *
+ * `contrast` exists because the provider writes tokens inline on
+ * `document.documentElement`, and inline styles beat author stylesheets - a
+ * consumer who must have a specific foreground could otherwise only override it
+ * with `!important`. Leave it unset to have it computed (see `pickContrast`).
+ */
+type ThemeColorValue = string | {
+    base: string;
+    contrast?: string;
+};
+type ThemeColors = Partial<Record<ThemeColorKey, ThemeColorValue>>;
+/** A selectable font stack, as offered by `ThemeEditor`. */
+interface ThemeFontOption {
+    /** Display name, e.g. "Plus Jakarta Sans". */
+    label: string;
+    /** The full CSS font stack written to the token. */
+    value: string;
+}
+interface ThemeTypography {
+    /** Replaces `--font-family-primary`. A full CSS font stack. */
+    fontFamily?: string;
+    /** Replaces `--font-family-mono`. A full CSS font stack. */
+    monoFamily?: string;
+    /**
+     * Multiplier applied to all eight `--font-size-*` tokens. 1 is the preset.
+     *
+     * Note that `--spacing-*` is declared in `em`, so this scales most padding
+     * and gaps along with the text rather than only the glyphs.
+     */
+    fontScale?: number;
+}
+/**
+ * A theme. Every field is optional and anything omitted falls back to
+ * `defaultTheme`, so a theme may be as small as one colour.
+ *
+ * Named `ThemeConfig` rather than `Theme` to avoid colliding with the `Theme`
+ * exported by MUI, styled-components and others in a consumer's namespace.
+ */
+interface ThemeConfig {
+    colors?: ThemeColors;
+    typography?: ThemeTypography;
+}
+/** A theme with every field populated - what the provider actually applies. */
+interface ResolvedTheme {
+    colors: Record<ThemeColorKey, {
+        base: string;
+        contrast?: string;
+    }>;
+    typography: Required<ThemeTypography>;
+}
+interface ThemeContextValue {
+    /** The theme as supplied, with omitted fields left absent. */
+    theme: ThemeConfig;
+    /** The same theme with every field filled in from the preset. */
+    resolvedTheme: ResolvedTheme;
+    /** Replaces the whole theme. */
+    setTheme: (theme: ThemeConfig) => void;
+    /** Deep-merges a partial theme into the current one. */
+    updateTheme: (patch: ThemeConfig) => void;
+    /** Returns to the preset. */
+    resetTheme: () => void;
+    /** True when nothing differs from the preset, so no tokens are being written. */
+    isDefault: boolean;
+    /** The resolved theme as a `:root { … }` CSS block. */
+    toCss: () => string;
+}
+interface ThemeProviderProps {
+    children: React__default.ReactNode;
+    /**
+     * Controlled theme. Pair with `onThemeChange` and own persistence yourself -
+     * this is the mode to use when the theme comes from a user record on your
+     * server.
+     */
+    theme?: ThemeConfig;
+    /** Initial theme for uncontrolled usage. Ignored when `theme` is supplied. */
+    defaultTheme?: ThemeConfig;
+    /** Fires whenever the theme changes, in both controlled and uncontrolled mode. */
+    onThemeChange?: (theme: ThemeConfig) => void;
+}
+
+export type { ResolvedTheme as R, ThemeColorKey as T, ThemeColorValue as a, ThemeColors as b, ThemeConfig as c, ThemeContextValue as d, ThemeFontOption as e, ThemeProviderProps as f, ThemeTypography as g };