themelia-ui 1.0.0

package/dist/lib/forms/field-binding.d.ts

@@ -0,0 +1,47 @@
+/** What a bound field hands to a control. */
+export interface FieldBinding<TValue> {
+    name: string;
+    value: TValue;
+    onValueChange: (value: TValue) => void;
+    onBlur: () => void;
+    /** Present so a control can render its invalid state without a separate lookup. */
+    invalid: boolean;
+    error?: string;
+    disabled?: boolean;
+}
+/** One field's state, as an adapter reports it. */
+export interface FieldState<TValue> {
+    value: TValue;
+    setValue: (value: TValue) => void;
+    onBlur?: () => void;
+    error?: string;
+    disabled?: boolean;
+}
+/**
+ * The adapter contract.
+ *
+ * `useField` IS a hook — it is called once per bound field, unconditionally, during
+ * render. That is what lets an RHF adapter delegate to `useController`, which is
+ * per-field by design and cannot be expressed as a plain lookup.
+ */
+export interface FormControl<TValues = Record<string, unknown>> {
+    useField: <TValue>(name: Extract<keyof TValues, string> | string) => FieldState<TValue>;
+}
+/** Binds one field. The only API a component needs to be form-library agnostic. */
+export declare function useFormFieldBinding<TValue, TValues = Record<string, unknown>>({ name, control, disabled, }: {
+    name: Extract<keyof TValues, string> | string;
+    control: FormControl<TValues>;
+    disabled?: boolean;
+}): FieldBinding<TValue>;
+/**
+ * A `FormControl` over plain React state — the zero-dependency default.
+ *
+ * Enough for the common case of a handful of fields, and it means the headless contract
+ * is usable without installing a form library at all.
+ */
+export declare function useStateFormControl<TValues extends Record<string, unknown>>(initialValues: TValues, options?: {
+    errors?: Partial<Record<keyof TValues, string>>;
+}): FormControl<TValues> & {
+    values: TValues;
+    reset: (next?: TValues) => void;
+};

package/dist/lib/forms/index.d.cts

@@ -0,0 +1 @@
+export { useFormFieldBinding, useStateFormControl, type FieldBinding, type FieldState, type FormControl, } from './field-binding.cjs';

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

@@ -0,0 +1 @@
+export { useFormFieldBinding, useStateFormControl, type FieldBinding, type FieldState, type FormControl, } from './field-binding.js';

package/dist/lib/forms-rhf/index.d.cts

@@ -0,0 +1,9 @@
+import { Control, FieldValues } from 'react-hook-form';
+import { FormControl } from '../forms/index.cjs';
+/**
+ * Wraps an RHF `control` in the kit's headless contract.
+ *
+ * `useField` delegates to `useController`, so registration, validation and dirty tracking
+ * all keep working — this adds a shape, not a second source of truth.
+ */
+export declare function rhfFormControl<TValues extends FieldValues>(control: Control<TValues>): FormControl<TValues>;

package/dist/lib/forms-rhf/index.d.ts

@@ -0,0 +1,9 @@
+import { Control, FieldValues } from 'react-hook-form';
+import { FormControl } from '../forms/index.js';
+/**
+ * Wraps an RHF `control` in the kit's headless contract.
+ *
+ * `useField` delegates to `useController`, so registration, validation and dirty tracking
+ * all keep working — this adds a shape, not a second source of truth.
+ */
+export declare function rhfFormControl<TValues extends FieldValues>(control: Control<TValues>): FormControl<TValues>;

package/dist/lib/observers.d.cts

@@ -0,0 +1,23 @@
+/**
+ * Observers that are absent outside a browser.
+ *
+ * `ResizeObserver`, `IntersectionObserver` and `matchMedia` are all missing in jsdom, so a
+ * component constructing one unguarded THROWS ON MOUNT in a consumer's unit test. That was
+ * measured, not assumed: `Carousel`, `OverflowTabBar`, `SectionNav` and `useIsMobile` each
+ * crashed in a jsdom render before this existed.
+ *
+ * "Polyfill it yourself" is the usual advice and it is a workaround for something a library
+ * can simply not do. What these observers provide is responsiveness to layout the consumer
+ * is not measuring in a unit test anyway; degrading to "never fires" is exactly right there,
+ * and in a real browser nothing changes.
+ *
+ * Each returns a disposer, so a caller's cleanup is the same shape either way.
+ */
+/** Observes size changes, or does nothing where `ResizeObserver` does not exist. */
+export declare function observeResize(targets: Element | Element[] | null | undefined, onResize: ResizeObserverCallback): () => void;
+/** Observes intersection, or does nothing where `IntersectionObserver` does not exist. */
+export declare function observeIntersection(targets: Element[] | null | undefined, onIntersect: IntersectionObserverCallback, options?: IntersectionObserverInit): () => void;
+/** Subscribes to a media query, or does nothing where `matchMedia` does not exist. */
+export declare function observeMediaQuery(query: string, onChange: () => void): () => void;
+/** Whether a media query matches now. `false` where `matchMedia` does not exist. */
+export declare function mediaQueryMatches(query: string): boolean;

package/dist/lib/observers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Observers that are absent outside a browser.
+ *
+ * `ResizeObserver`, `IntersectionObserver` and `matchMedia` are all missing in jsdom, so a
+ * component constructing one unguarded THROWS ON MOUNT in a consumer's unit test. That was
+ * measured, not assumed: `Carousel`, `OverflowTabBar`, `SectionNav` and `useIsMobile` each
+ * crashed in a jsdom render before this existed.
+ *
+ * "Polyfill it yourself" is the usual advice and it is a workaround for something a library
+ * can simply not do. What these observers provide is responsiveness to layout the consumer
+ * is not measuring in a unit test anyway; degrading to "never fires" is exactly right there,
+ * and in a real browser nothing changes.
+ *
+ * Each returns a disposer, so a caller's cleanup is the same shape either way.
+ */
+/** Observes size changes, or does nothing where `ResizeObserver` does not exist. */
+export declare function observeResize(targets: Element | Element[] | null | undefined, onResize: ResizeObserverCallback): () => void;
+/** Observes intersection, or does nothing where `IntersectionObserver` does not exist. */
+export declare function observeIntersection(targets: Element[] | null | undefined, onIntersect: IntersectionObserverCallback, options?: IntersectionObserverInit): () => void;
+/** Subscribes to a media query, or does nothing where `matchMedia` does not exist. */
+export declare function observeMediaQuery(query: string, onChange: () => void): () => void;
+/** Whether a media query matches now. `false` where `matchMedia` does not exist. */
+export declare function mediaQueryMatches(query: string): boolean;

package/dist/lib/render-with-children.d.cts

@@ -0,0 +1,2 @@
+import { ReactElement, ReactNode } from 'react';
+export declare function renderWithChildren(element: ReactElement, children: ReactNode): ReactElement;

package/dist/lib/render-with-children.d.ts

@@ -0,0 +1,2 @@
+import { ReactElement, ReactNode } from 'react';
+export declare function renderWithChildren(element: ReactElement, children: ReactNode): ReactElement;

package/dist/lib/responsive.d.cts

@@ -0,0 +1,24 @@
+import { CSSProperties } from 'react';
+export type Breakpoint = "base" | "sm" | "md" | "lg" | "xl" | "2xl";
+export declare const BREAKPOINTS: Breakpoint[];
+/** A literal value, or a per-breakpoint object. Every responsive prop accepts both. */
+export type ResponsiveValue<T> = T | Partial<Record<Breakpoint, T>>;
+/**
+ * Turns a responsive prop into per-breakpoint custom properties.
+ *
+ * In `lib` rather than in `base/structure`, where it started: `AspectRatio` is a framing
+ * box in its own family and takes a responsive `ratio` for the same reason a Stack takes a
+ * responsive `gap`, and a family reaching sideways into another family for the mechanism
+ * would be an import the layer graph rightly refuses.
+ *
+ * The source kit compiled these into class tables — six breakpoints times eight gap steps
+ * times five axes, every combination written out as a Tailwind string. That is hundreds of
+ * literals to keep in step, and adding a breakpoint means regenerating all of them.
+ *
+ * Here each breakpoint writes one variable and the module has one media query per
+ * breakpoint that reads it, falling back to the next breakpoint down. Six rules replace
+ * the whole table, and a new gap step costs nothing.
+ */
+export declare function responsiveVars<T extends string | number | boolean>(name: string, value: ResponsiveValue<T> | undefined, transform?: (value: T) => string): CSSProperties;
+/** Merges several responsive prop maps into one style object. */
+export declare function mergeVars(...parts: CSSProperties[]): CSSProperties;

package/dist/lib/responsive.d.ts

@@ -0,0 +1,24 @@
+import { CSSProperties } from 'react';
+export type Breakpoint = "base" | "sm" | "md" | "lg" | "xl" | "2xl";
+export declare const BREAKPOINTS: Breakpoint[];
+/** A literal value, or a per-breakpoint object. Every responsive prop accepts both. */
+export type ResponsiveValue<T> = T | Partial<Record<Breakpoint, T>>;
+/**
+ * Turns a responsive prop into per-breakpoint custom properties.
+ *
+ * In `lib` rather than in `base/structure`, where it started: `AspectRatio` is a framing
+ * box in its own family and takes a responsive `ratio` for the same reason a Stack takes a
+ * responsive `gap`, and a family reaching sideways into another family for the mechanism
+ * would be an import the layer graph rightly refuses.
+ *
+ * The source kit compiled these into class tables — six breakpoints times eight gap steps
+ * times five axes, every combination written out as a Tailwind string. That is hundreds of
+ * literals to keep in step, and adding a breakpoint means regenerating all of them.
+ *
+ * Here each breakpoint writes one variable and the module has one media query per
+ * breakpoint that reads it, falling back to the next breakpoint down. Six rules replace
+ * the whole table, and a new gap step costs nothing.
+ */
+export declare function responsiveVars<T extends string | number | boolean>(name: string, value: ResponsiveValue<T> | undefined, transform?: (value: T) => string): CSSProperties;
+/** Merges several responsive prop maps into one style object. */
+export declare function mergeVars(...parts: CSSProperties[]): CSSProperties;

package/dist/lib/sanitize-html.d.cts

@@ -0,0 +1 @@
+export declare function sanitizeHtml(input: string): string;

package/dist/lib/sanitize-html.d.ts

@@ -0,0 +1 @@
+export declare function sanitizeHtml(input: string): string;

package/dist/lib/ssr-surface-test-utils.d.cts

@@ -0,0 +1,24 @@
+export interface SsrFamily {
+    id: string;
+    source: string;
+}
+export interface SsrFamilyResult {
+    familyId: string;
+    /** False when the module could not be loaded at all, for any reason. */
+    imported: boolean;
+    /** How many capitalised callables were rendered — the sweep's non-vacuity signal. */
+    rendered: number;
+    /** Only failures that name a browser global. Everything else is the caller's problem. */
+    hazards: string[];
+}
+/**
+ * An error that a consumer cannot fix.
+ *
+ * Rendering with no props throws constantly, and that is fine: a missing prop is the
+ * caller's problem and shows up as a type error long before runtime. A single
+ * `window.matchMedia(...)` read at module scope or in a render body is different — it
+ * breaks `import` for every Next.js consumer, at their build step, with a stack that
+ * points into this package rather than at their page.
+ */
+export declare const BROWSER_GLOBAL: RegExp;
+export declare function renderFamilyWithoutBrowser(family: SsrFamily): Promise<SsrFamilyResult>;

package/dist/lib/ssr-surface-test-utils.d.ts

@@ -0,0 +1,24 @@
+export interface SsrFamily {
+    id: string;
+    source: string;
+}
+export interface SsrFamilyResult {
+    familyId: string;
+    /** False when the module could not be loaded at all, for any reason. */
+    imported: boolean;
+    /** How many capitalised callables were rendered — the sweep's non-vacuity signal. */
+    rendered: number;
+    /** Only failures that name a browser global. Everything else is the caller's problem. */
+    hazards: string[];
+}
+/**
+ * An error that a consumer cannot fix.
+ *
+ * Rendering with no props throws constantly, and that is fine: a missing prop is the
+ * caller's problem and shows up as a type error long before runtime. A single
+ * `window.matchMedia(...)` read at module scope or in a render body is different — it
+ * breaks `import` for every Next.js consumer, at their build step, with a stack that
+ * points into this package rather than at their page.
+ */
+export declare const BROWSER_GLOBAL: RegExp;
+export declare function renderFamilyWithoutBrowser(family: SsrFamily): Promise<SsrFamilyResult>;

package/dist/lib/strings.d.cts

@@ -0,0 +1,57 @@
+/**
+ * Component copy.
+ *
+ * ── The contract ────────────────────────────────────────────────────────────────────
+ * A component with any user-facing copy of its own exports a `defaultXStrings` object
+ * and takes a `strings?: Partial<XStrings>` prop. It resolves them by spreading:
+ *
+ * ```ts
+ * export interface InputStrings { clear: string }
+ * export const defaultInputStrings: InputStrings = { clear: "Clear input" }
+ *
+ * function Input({ strings, ... }: InputProps) {
+ *   const copy = { ...defaultInputStrings, ...strings }
+ * }
+ * ```
+ *
+ * Deliberately NOT a hook or a helper. A spread is one line, it is obvious at the call
+ * site what wins, it works outside React, and it cannot introduce a render-order
+ * dependency. A `useStrings()` would put a hook between a component and a plain object
+ * for no gain, and make every string lookup a reason the component must be a component.
+ *
+ * Overriding is per-instance and partial — a caller supplies only the keys they are
+ * changing, and the rest fall through to the defaults:
+ *
+ * ```tsx
+ * <Input clearable strings={{ clear: "Effacer" }} />
+ * ```
+ *
+ * A value may be a function when the copy interpolates, so a translation can reorder its
+ * parts rather than being handed a pre-joined string:
+ *
+ * ```ts
+ * export interface FileUploadStrings {
+ *   tooLarge: (name: string, limit: string) => string
+ * }
+ * ```
+ *
+ * This type exists only to name the shape in a prop signature. There is no runtime here.
+ *
+ * It is DEEPLY partial, and has to be. `resolveStrings` merges nested dictionaries one key
+ * at a time — the whole reason it exists — but the type was `Partial<T>`, which makes only
+ * the top level optional. So the override the feature exists for,
+ *
+ * ```tsx
+ * <Comments strings={{ composer: { placeholder: "Schreiben…" } }} />
+ * ```
+ *
+ * was a type error demanding every sibling of `placeholder` be restated, while the runtime
+ * beneath it merged exactly as intended. The recursion stops where the runtime's does: only
+ * a plain object recurses, and a function, an array or a ReactNode replaces, because a
+ * caller overriding a formatter means to supply the whole formatter. A union containing a
+ * primitive — which `ReactNode` is — does not extend `object`, so it replaces too.
+ */
+export type StringsProp<T> = {
+    [K in keyof T]?: T[K] extends (...args: never[]) => unknown ? T[K] : T[K] extends readonly unknown[] ? T[K] : T[K] extends object ? StringsProp<T[K]> : T[K];
+};
+export declare function resolveStrings<T extends object>(defaults: T, overrides?: StringsProp<T>): T;

package/dist/lib/strings.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Component copy.
+ *
+ * ── The contract ────────────────────────────────────────────────────────────────────
+ * A component with any user-facing copy of its own exports a `defaultXStrings` object
+ * and takes a `strings?: Partial<XStrings>` prop. It resolves them by spreading:
+ *
+ * ```ts
+ * export interface InputStrings { clear: string }
+ * export const defaultInputStrings: InputStrings = { clear: "Clear input" }
+ *
+ * function Input({ strings, ... }: InputProps) {
+ *   const copy = { ...defaultInputStrings, ...strings }
+ * }
+ * ```
+ *
+ * Deliberately NOT a hook or a helper. A spread is one line, it is obvious at the call
+ * site what wins, it works outside React, and it cannot introduce a render-order
+ * dependency. A `useStrings()` would put a hook between a component and a plain object
+ * for no gain, and make every string lookup a reason the component must be a component.
+ *
+ * Overriding is per-instance and partial — a caller supplies only the keys they are
+ * changing, and the rest fall through to the defaults:
+ *
+ * ```tsx
+ * <Input clearable strings={{ clear: "Effacer" }} />
+ * ```
+ *
+ * A value may be a function when the copy interpolates, so a translation can reorder its
+ * parts rather than being handed a pre-joined string:
+ *
+ * ```ts
+ * export interface FileUploadStrings {
+ *   tooLarge: (name: string, limit: string) => string
+ * }
+ * ```
+ *
+ * This type exists only to name the shape in a prop signature. There is no runtime here.
+ *
+ * It is DEEPLY partial, and has to be. `resolveStrings` merges nested dictionaries one key
+ * at a time — the whole reason it exists — but the type was `Partial<T>`, which makes only
+ * the top level optional. So the override the feature exists for,
+ *
+ * ```tsx
+ * <Comments strings={{ composer: { placeholder: "Schreiben…" } }} />
+ * ```
+ *
+ * was a type error demanding every sibling of `placeholder` be restated, while the runtime
+ * beneath it merged exactly as intended. The recursion stops where the runtime's does: only
+ * a plain object recurses, and a function, an array or a ReactNode replaces, because a
+ * caller overriding a formatter means to supply the whole formatter. A union containing a
+ * primitive — which `ReactNode` is — does not extend `object`, so it replaces too.
+ */
+export type StringsProp<T> = {
+    [K in keyof T]?: T[K] extends (...args: never[]) => unknown ? T[K] : T[K] extends readonly unknown[] ? T[K] : T[K] extends object ? StringsProp<T[K]> : T[K];
+};
+export declare function resolveStrings<T extends object>(defaults: T, overrides?: StringsProp<T>): T;

package/dist/lib/theming/contrast.d.cts

@@ -0,0 +1,28 @@
+/** The kit's own ink and paper, which is what the derived themes have always used. */
+export declare const INK = "oklch(0.18 0.01 260)";
+export declare const PAPER = "oklch(0.985 0 0)";
+export interface ForegroundChoice {
+    /** The chosen foreground. */
+    color: string;
+    /** WCAG contrast ratio against the background, 1–21. */
+    ratio: number;
+    /**
+     * Whether the ratio clears WCAG AA for body text (4.5:1).
+     *
+     * Reported rather than enforced: a caller handing in a mid-lightness brand colour gets
+     * the best available foreground plus the honest news that neither candidate clears AA,
+     * which is more useful than a silent pass or a thrown error.
+     */
+    meetsAA: boolean;
+    /** `false` when the colour could not be parsed and `mode` decided instead. */
+    measured: boolean;
+}
+/**
+ * The more readable of `candidates` on `background`, measured.
+ *
+ * Falls back to `mode` only when the background cannot be parsed at all — a `var()`, a
+ * `color-mix()`, or anything else whose value is not knowable without a browser.
+ */
+export declare function readableForeground(background: string, mode?: ThemeModeLike, candidates?: readonly [string, string]): ForegroundChoice;
+type ThemeModeLike = "light" | "dark";
+export {};

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

@@ -0,0 +1,28 @@
+/** The kit's own ink and paper, which is what the derived themes have always used. */
+export declare const INK = "oklch(0.18 0.01 260)";
+export declare const PAPER = "oklch(0.985 0 0)";
+export interface ForegroundChoice {
+    /** The chosen foreground. */
+    color: string;
+    /** WCAG contrast ratio against the background, 1–21. */
+    ratio: number;
+    /**
+     * Whether the ratio clears WCAG AA for body text (4.5:1).
+     *
+     * Reported rather than enforced: a caller handing in a mid-lightness brand colour gets
+     * the best available foreground plus the honest news that neither candidate clears AA,
+     * which is more useful than a silent pass or a thrown error.
+     */
+    meetsAA: boolean;
+    /** `false` when the colour could not be parsed and `mode` decided instead. */
+    measured: boolean;
+}
+/**
+ * The more readable of `candidates` on `background`, measured.
+ *
+ * Falls back to `mode` only when the background cannot be parsed at all — a `var()`, a
+ * `color-mix()`, or anything else whose value is not knowable without a browser.
+ */
+export declare function readableForeground(background: string, mode?: ThemeModeLike, candidates?: readonly [string, string]): ForegroundChoice;
+type ThemeModeLike = "light" | "dark";
+export {};

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

@@ -0,0 +1,4 @@
+export { deriveThemeElevation, deriveThemePalette, deriveThemeTypeScale } from './recipes.cjs';
+export type { ThemeElevationRecipe, ThemePaletteRecipe, ThemeTypeScaleRecipe } from './recipes.cjs';
+export { INK, PAPER, readableForeground, type ForegroundChoice } from './contrast.cjs';
+export type { ThemeMode, ThemeOverrides, ThemeVariableName } from './types.cjs';

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

@@ -0,0 +1,4 @@
+export { deriveThemeElevation, deriveThemePalette, deriveThemeTypeScale } from './recipes.js';
+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';

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

@@ -0,0 +1,20 @@
+import { ThemeMode, ThemeOverrides } from './types.cjs';
+export interface ThemePaletteRecipe {
+    primary: string;
+    mode?: ThemeMode;
+}
+export interface ThemeTypeScaleRecipe {
+    /** The body anchor, in pixels. The kit's own is 16. */
+    baseSize: number;
+    /** The modular ratio headings step by. */
+    ratio?: number;
+}
+export interface ThemeElevationRecipe {
+    /** 0 is flat, 1 is pronounced. */
+    intensity: number;
+}
+/** A coherent brand from one primary colour. */
+export declare function deriveThemePalette({ primary, mode }: ThemePaletteRecipe): ThemeOverrides;
+export declare function deriveThemeTypeScale({ baseSize, ratio, }: ThemeTypeScaleRecipe): ThemeOverrides;
+/** The whole shadow ladder from one intensity. */
+export declare function deriveThemeElevation({ intensity }: ThemeElevationRecipe): ThemeOverrides;

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

@@ -0,0 +1,20 @@
+import { ThemeMode, ThemeOverrides } from './types.js';
+export interface ThemePaletteRecipe {
+    primary: string;
+    mode?: ThemeMode;
+}
+export interface ThemeTypeScaleRecipe {
+    /** The body anchor, in pixels. The kit's own is 16. */
+    baseSize: number;
+    /** The modular ratio headings step by. */
+    ratio?: number;
+}
+export interface ThemeElevationRecipe {
+    /** 0 is flat, 1 is pronounced. */
+    intensity: number;
+}
+/** A coherent brand from one primary colour. */
+export declare function deriveThemePalette({ primary, mode }: ThemePaletteRecipe): ThemeOverrides;
+export declare function deriveThemeTypeScale({ baseSize, ratio, }: ThemeTypeScaleRecipe): ThemeOverrides;
+/** The whole shadow ladder from one intensity. */
+export declare function deriveThemeElevation({ intensity }: ThemeElevationRecipe): ThemeOverrides;

package/dist/lib/theming/types.d.cts

@@ -0,0 +1,12 @@
+/**
+ * The vocabulary theme synthesis works in.
+ *
+ * These three lived in `features/theme-tweaker` because that is where they were first
+ * needed. They describe the TOKEN CONTRACT rather than a control panel, and a build script
+ * synthesising a theme has no business importing a React feature to name its own output —
+ * so they live here, and the feature re-exports them unchanged.
+ */
+export type ThemeMode = "light" | "dark";
+export type ThemeVariableName = `--${string}`;
+/** A set of custom-property overrides, ready for a style attribute or a CSS string. */
+export type ThemeOverrides = Partial<Record<ThemeVariableName, string>>;

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

@@ -0,0 +1,12 @@
+/**
+ * The vocabulary theme synthesis works in.
+ *
+ * These three lived in `features/theme-tweaker` because that is where they were first
+ * needed. They describe the TOKEN CONTRACT rather than a control panel, and a build script
+ * synthesising a theme has no business importing a React feature to name its own output —
+ * so they live here, and the feature re-exports them unchanged.
+ */
+export type ThemeMode = "light" | "dark";
+export type ThemeVariableName = `--${string}`;
+/** A set of custom-property overrides, ready for a style attribute or a CSS string. */
+export type ThemeOverrides = Partial<Record<ThemeVariableName, string>>;

package/dist/lib/ui-provider/context.d.cts

@@ -0,0 +1,43 @@
+import { ResolvedUIConfig, UIConfig } from './types.cjs';
+export declare const UIConfigContext: import('react').Context<ResolvedUIConfig>;
+/**
+ * Whether a provider has one above it.
+ *
+ * The outermost provider syncs colour scheme and density to `documentElement`, because
+ * `<body>` is its ANCESTOR and inline custom properties only reach descendants — without
+ * this the page canvas stays light while everything inside it goes dark. A nested
+ * provider must not do that: its scope is its own subtree.
+ */
+export declare const UINestedContext: import('react').Context<boolean>;
+/**
+ * Where a popup should render, so a scope survives the trip.
+ *
+ * Both mechanisms this kit scopes with — CSS custom properties, and the `[data-density]`
+ * and `[data-theme]` selectors — work by inheritance down the DOM tree. A portal moves its
+ * content to `document.body`, which is outside that subtree, so a Select opened inside a
+ * compact dark region rendered at the ROOT's density and theme.
+ *
+ * The remedy is deliberately not a second theme context re-applying the values on the other
+ * side: that would leave two sources of truth for one scope, and they would drift. It is to
+ * portal into an element already INSIDE the scope, and let ordinary inheritance work.
+ */
+export type UIPortalContainer = HTMLElement | ShadowRoot | null;
+/** Published by `UIPortalHost`; read through `useUIPortalContainer`. */
+export declare const UIPortalHostContext: import('react').Context<UIPortalContainer>;
+/**
+ * Merges a config over its parent.
+ *
+ * A scope names what it is CHANGING; everything it does not name it inherits. That holds at
+ * the slice level — setting `typography.defaultTextSize` must not drop the parent's
+ * `typography.fonts` — and it has to hold one level below it too.
+ *
+ * It used to stop at the slice, on the reasoning that naming a colour means replacing that
+ * colour. It does; but `theme.colors` is the record, not the colour. Spreading the slice
+ * replaced the whole record, so a scope setting `colors.primary` silently discarded every
+ * other colour the application had configured — an entire palette lost to naming one entry,
+ * with no error and nothing in the DOM to suggest where it went.
+ *
+ * One extra level, and no further: the record fields are flat maps of token to value, so
+ * below them there is nothing left to merge.
+ */
+export declare function mergeUIConfig(parent: ResolvedUIConfig, config?: UIConfig): ResolvedUIConfig;

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

@@ -0,0 +1,43 @@
+import { ResolvedUIConfig, UIConfig } from './types.js';
+export declare const UIConfigContext: import('react').Context<ResolvedUIConfig>;
+/**
+ * Whether a provider has one above it.
+ *
+ * The outermost provider syncs colour scheme and density to `documentElement`, because
+ * `<body>` is its ANCESTOR and inline custom properties only reach descendants — without
+ * this the page canvas stays light while everything inside it goes dark. A nested
+ * provider must not do that: its scope is its own subtree.
+ */
+export declare const UINestedContext: import('react').Context<boolean>;
+/**
+ * Where a popup should render, so a scope survives the trip.
+ *
+ * Both mechanisms this kit scopes with — CSS custom properties, and the `[data-density]`
+ * and `[data-theme]` selectors — work by inheritance down the DOM tree. A portal moves its
+ * content to `document.body`, which is outside that subtree, so a Select opened inside a
+ * compact dark region rendered at the ROOT's density and theme.
+ *
+ * The remedy is deliberately not a second theme context re-applying the values on the other
+ * side: that would leave two sources of truth for one scope, and they would drift. It is to
+ * portal into an element already INSIDE the scope, and let ordinary inheritance work.
+ */
+export type UIPortalContainer = HTMLElement | ShadowRoot | null;
+/** Published by `UIPortalHost`; read through `useUIPortalContainer`. */
+export declare const UIPortalHostContext: import('react').Context<UIPortalContainer>;
+/**
+ * Merges a config over its parent.
+ *
+ * A scope names what it is CHANGING; everything it does not name it inherits. That holds at
+ * the slice level — setting `typography.defaultTextSize` must not drop the parent's
+ * `typography.fonts` — and it has to hold one level below it too.
+ *
+ * It used to stop at the slice, on the reasoning that naming a colour means replacing that
+ * colour. It does; but `theme.colors` is the record, not the colour. Spreading the slice
+ * replaced the whole record, so a scope setting `colors.primary` silently discarded every
+ * other colour the application had configured — an entire palette lost to naming one entry,
+ * with no error and nothing in the DOM to suggest where it went.
+ *
+ * One extra level, and no further: the record fields are flat maps of token to value, so
+ * below them there is nothing left to merge.
+ */
+export declare function mergeUIConfig(parent: ResolvedUIConfig, config?: UIConfig): ResolvedUIConfig;

package/dist/lib/ui-provider/csp-provider.d.cts

@@ -0,0 +1,10 @@
+import { CSPProviderProps as BaseCSPProviderProps } from '@base-ui/react/csp-provider';
+/**
+ * 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.
+ */
+export interface CSPProviderProps extends Pick<BaseCSPProviderProps, "children" | "nonce" | "disableStyleElements"> {
+}
+export declare function CSPProvider(props: CSPProviderProps): import("react").JSX.Element;

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

@@ -0,0 +1,10 @@
+import { CSPProviderProps as BaseCSPProviderProps } from '@base-ui/react/csp-provider';
+/**
+ * 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.
+ */
+export interface CSPProviderProps extends Pick<BaseCSPProviderProps, "children" | "nonce" | "disableStyleElements"> {
+}
+export declare function CSPProvider(props: CSPProviderProps): import("react").JSX.Element;

package/dist/lib/ui-provider/defaults.d.cts

@@ -0,0 +1,9 @@
+import { ResolvedUIConfig } from './types.cjs';
+/**
+ * Library-wide defaults.
+ *
+ * Only JS-side decisions live here. Anything expressible as a token — colours, radius,
+ * scales, durations — has its default in the stylesheet, because duplicating it in
+ * JavaScript is what let `density` drift between the two halves of the source kit.
+ */
+export declare const DEFAULT_UI_CONFIG: ResolvedUIConfig;

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

@@ -0,0 +1,9 @@
+import { ResolvedUIConfig } from './types.js';
+/**
+ * Library-wide defaults.
+ *
+ * Only JS-side decisions live here. Anything expressible as a token — colours, radius,
+ * scales, durations — has its default in the stylesheet, because duplicating it in
+ * JavaScript is what let `density` drift between the two halves of the source kit.
+ */
+export declare const DEFAULT_UI_CONFIG: ResolvedUIConfig;