themelia-react-ui 1.0.1 → 2.0.0

package/dist/components/base/chart/chart.d.ts

@@ -25,15 +25,15 @@ export type ChartConfig = Record<string, {
 })>;
 export type ChartPayloadItem = {
     dataKey?: string | number;
-    /** Form field name, forwarded for native submits. */
+    /** Series name. */
     name?: string | number;
-    /** Current value. Controlled. */
+    /** The series value at the hovered point. */
     value?: string | number | Array<string | number>;
     type?: string;
     /** Overrides the colour of the tooltip indicator. */
     color?: string;
     fill?: string;
-    /** Data points under the cursor. Supplied by Recharts. */
+    /** The raw data row for the hovered point. Supplied by Recharts. */
     payload?: Record<string, unknown>;
 };
 export interface ChartInitialDimension {
@@ -66,11 +66,11 @@ export interface ChartTooltipContentProps extends React.ComponentPropsWithoutRef
     labelFormatter?: (label: React.ReactNode, payload: ChartPayloadItem[]) => React.ReactNode;
     /** Formats each tooltip value. */
     formatter?: (
-    /** Current value. Controlled. */
+    /** The series value at the hovered point. */
     value: NonNullable<ChartPayloadItem['value']>, 
-    /** Form field name, forwarded for native submits. */
+    /** Series name. */
     name: NonNullable<ChartPayloadItem['name']>, item: ChartPayloadItem, index: number, 
-    /** Data points under the cursor. Supplied by Recharts. */
+    /** The raw data row for the hovered point. Supplied by Recharts. */
     payload?: Record<string, unknown>) => React.ReactNode;
     /** Overrides the colour of the tooltip indicator. */
     color?: string;
@@ -89,7 +89,7 @@ declare function ChartTooltipContent({ active, payload, className, indicator, hi
 declare const ChartLegend: React.MemoExoticComponent<(outsideProps: RechartsPrimitive.LegendProps) => React.ReactPortal | null>;
 export interface ChartLegendContentProps extends React.ComponentPropsWithoutRef<'div'> {
     hideIcon?: boolean;
-    /** Data points under the cursor. Supplied by Recharts. */
+    /** Legend entries, one per series. Supplied by Recharts. */
     payload?: ChartPayloadItem[];
     verticalAlign?: 'top' | 'bottom' | 'middle';
     /** Key in the payload holding each series name. */

package/dist/components/base/choice-inputs/checkbox.d.ts

@@ -2,15 +2,14 @@ import { type CheckboxProps } from '../../ui/checkbox';
 /**
  * Checkbox — base wrapper around the shadcn/Base UI checkbox primitive.
  *
- * Base UI renders the root as an inline span; the wrapper makes it an
- * inline-flex control so token size utilities render as a square box instead
- * of collapsing to the two border lines.
+ * The primitive renders an inline-flex square, so token size utilities render
+ * as a box instead of collapsing to the two border lines. Its boundary is the
+ * shared `--input` control border, which keeps 3:1 contrast on every surface in
+ * both themes, like the other field and choice controls.
  *
  * The root ref accepts the actual HTMLElement, including custom button renders.
- * The muted foreground border keeps the unchecked boundary visible in both themes.
- *
- * The wrapper retains its compact corner recipe while deriving it from the
- * shared theme radius, so scoped consumer radius overrides still apply.
+ * The compact corner recipe derives from the shared theme radius, so scoped
+ * consumer radius overrides still apply. The indeterminate state draws a dash.
  */
 declare const Checkbox: import("react").ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & import("react").RefAttributes<HTMLElement>>;
 export { Checkbox };

package/dist/components/base/choice-inputs/choice-types.d.ts

@@ -52,6 +52,15 @@ export declare const choicePillSizeTokens: Record<ChoiceSize, string>;
  * Row padding tokens for ListRadio and any future inline list variant.
  */
 export declare const choiceListSizeTokens: Record<ChoiceSize, string>;
+/**
+ * Shared option-card states for CardRadioGroup and CardCheckboxGroup: the resting
+ * `border-border` divider (declared beside `border` by each owner) steps up to the
+ * 3:1 control boundary on hover, and keyboard focus draws the shared full-strength
+ * ring. Selection and validation are added by each owner.
+ */
+export declare const choiceCardStateClasses = "hover:border-input focus-visible:ring-2 focus-visible:ring-ring";
+/** Optional option glyph: one neutral tile in every state, so colour stays for meaning. */
+export declare const choiceCardIconClasses = "inline-flex shrink-0 items-center justify-center rounded-inner bg-muted text-muted-foreground";
 /** Shared selected-card marker and content clearance; derives from action/icon geometry. */
 export declare const choiceCardMarkerClasses = "absolute top-space-sm end-space-sm size-action-sm text-primary-foreground fill-primary stroke-primary-foreground";
-export declare const choiceCardMarkerClearance = "[&>*:not(svg)]:max-w-[calc(100%_-_var(--spacing-action-sm))]";
+export declare const choiceCardMarkerClearance = "[&>*:not(svg)]:max-w-[calc(100%_-_var(--height-action)*8/9*var(--density-scale))]";

package/dist/components/base/choice-inputs/pill-radio-group.d.ts

@@ -6,6 +6,11 @@
  * Custom-styled buttons rather than the shadcn ToggleGroup primitive: the
  * primitive strips inner rounding when spacing=0, which doesn't match this
  * design system's pill connector style.
+ *
+ * Keyboard follows the native radio-group pattern: the group is one Tab stop
+ * (the selected pill, or the first enabled one), the arrow keys move to the
+ * previous/next enabled pill and select it, Home/End jump to the ends, and
+ * Space/Enter select the focused pill (or clear it when `allowClear` is set).
  */
 import * as React from 'react';
 import { type ChoiceGroupBaseProps, type ChoiceOptionBase } from './choice-types';
@@ -23,5 +28,9 @@ export interface PillRadioGroupProps extends Omit<ChoiceGroupBaseProps, 'name'>
     allowClear?: boolean;
     /** Stretch pills to fill the container. */
     fullWidth?: boolean;
+    /** Accessible name of the group when no visible label is associated with it. */
+    'aria-label'?: string;
+    /** Id of a visible label that names the group. */
+    'aria-labelledby'?: string;
 }
 export declare const PillRadioGroup: React.ForwardRefExoticComponent<PillRadioGroupProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/base/choice-inputs/select-popup.d.ts

@@ -19,8 +19,16 @@ export interface SelectPopupItemProps extends ComponentPropsWithoutRef<typeof ba
 }
 export declare function SelectPopupItem({ children, className, size, density, ...props }: SelectPopupItemProps): import("react").JSX.Element;
 export interface SelectPopupLabelProps extends ComponentPropsWithoutRef<typeof baseui.SelectLabel> {
-    /** Match the group label to the owning form control's text scale. */
+    /**
+     * Owning control scale. Group captions sit one step below the option text:
+     * `sm` and `md` use the compact caption size, `lg` the default text size.
+     * Defaults to `md`.
+     */
     size?: FormControlSize;
 }
+/**
+ * Group caption. Supporting copy rather than another option, so it uses the
+ * secondary medium caption role shared with menu and command group captions.
+ */
 export declare function SelectPopupLabel({ children, className, size, ...props }: SelectPopupLabelProps): import("react").JSX.Element;
 export declare function SelectPopupSeparator({ className, ...props }: ComponentPropsWithoutRef<typeof baseui.SelectSeparator>): import("react").JSX.Element;

package/dist/components/base/choice-inputs/switch-card.d.ts

@@ -2,7 +2,7 @@
  * SwitchCard — bordered settings card with an icon, title, optional
  * description, optional hint, and a trailing switch. The whole card is
  * clickable and toggles the switch; clicking inside the actual switch only
- * toggles once. Active state lifts the border and tints the surface.
+ * toggles once. The on state draws the primary border; the switch itself carries the state.
  *
  * Use for top-of-list "feature" toggles where the switch needs more visual
  * weight than a `ToggleField`. For dense rows, prefer `ToggleField`.

package/dist/components/base/date-pickers/date-picker-field.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Private label / hint / error chrome shared by the DatePicker modes and
+ * MonthYearPicker. It keeps FormField's rhythm and roles: the same label recipe,
+ * the same gap to the trigger and to the supporting line, and a polite alert for
+ * the validation message. Validation marks the trigger, not the label.
+ *
+ * The hint keeps its documented place beside the label and is suppressed while
+ * an error shows. Not part of the public API.
+ */
+import type { ReactNode, Ref } from 'react';
+export interface DatePickerFieldProps {
+    rootRef?: Ref<HTMLDivElement>;
+    className?: string;
+    label?: string;
+    hint?: string;
+    error?: string;
+    /** Id of the trigger the label names. */
+    triggerId: string;
+    /** Id of the validation message the trigger references. */
+    describedById: string;
+    children: ReactNode;
+}
+export declare function DatePickerField({ rootRef, className, label, hint, error, triggerId, describedById, children, }: DatePickerFieldProps): import("react").JSX.Element;

package/dist/components/base/date-pickers/date-picker.recipes.d.ts

@@ -1,18 +1,5 @@
-/**
- * Field-style chrome override applied on top of `<Button>` so the
- * picker trigger reads as a form field — visually identical to
- * `<Input>` (same height, border, padding, focus ring, typography).
- *
- * Mirrors the `Input` component's chrome:
- * - `border-input` border, `rounded-radius-md`, `bg-transparent`
- * - `h-control` + `px-control` + `py-space-xs`
- * - `text-sm` body text, normal weight, `text-foreground`
- * - `focus-visible:border-ring ring-ring/50 ring-[3px]`
- * - `aria-invalid:` destructive ring + border
- * - flat (no shadow) — library is intentionally flat
- *
- * `!` prefix wins against the global `<Button>`'s pill-shaped default
- * + `data-[size=*]` attribute selectors. Caret-icon sits in
- * library-default left padding equal to `<Input startIcon>` rules.
- */
-export declare const PICKER_TRIGGER_CHROME: string;
+import { type FormControlSize } from '../../../lib/ui-provider';
+/** Picker triggers resolve the same explicit/provider/default scale as fields. */
+export declare function usePickerTriggerSize(sizeProp: FormControlSize | undefined): FormControlSize;
+/** Button composition contributes behavior; the shared field owner supplies chrome. */
+export declare function pickerTriggerClasses(size: FormControlSize, iconOnly?: boolean): string;

package/dist/components/base/date-pickers/datepicker.types.d.ts

@@ -1,5 +1,6 @@
 import type { LucideIcon } from 'lucide-react';
 import type { DateRange, PropsSingle, PropsRange, PropsMulti, Locale } from 'react-day-picker';
+import type { FormControlSize } from '../../../lib/ui-provider';
 import type { StringsProp } from '../../../lib/strings';
 import type { ActionPresentation } from '../../../lib/action-presentation';
 import type { ButtonStyle, ButtonTone } from '../buttons';
@@ -64,16 +65,28 @@ export interface DatePickerStrings {
     year: string;
 }
 export interface DatePickerBaseProps {
+    /** Trigger field size. Explicit values override the provider density scale; fallback is md. */
+    size?: FormControlSize;
     /** Caption above the trigger, associated through `htmlFor`. Omit when an external FormField owns the chrome. */
     label?: string;
     /** Short guidance shown beside the label. Suppressed while `error` is set. */
     hint?: string;
     /**
-     * Validation message rendered below the trigger and referenced by the
-     * trigger's `aria-describedby`. Setting it also marks the control invalid
-     * and tints the label.
+     * Validation message rendered below the trigger (as a polite alert) and
+     * referenced by the trigger's `aria-describedby`. Setting it also marks the
+     * trigger invalid; like `FormField`, validation marks the field, not the label.
      */
     error?: string;
+    /**
+     * Marks the trigger invalid without rendering a message, for when an external
+     * `FormField` owns the validation copy. `error` implies it.
+     */
+    invalid?: boolean;
+    /**
+     * Id of the trigger. An external `<FormField label>` assigns its child an id,
+     * so the label names the trigger. Defaults to a generated id.
+     */
+    id?: string;
     /** Disables the trigger and prevents the calendar from opening. */
     disabled?: boolean;
     /** Merged onto the outermost node. */

package/dist/components/base/display/alert-dialog.d.ts

@@ -1,7 +1,12 @@
 import type { TextGap } from '../structure';
 /**
- * AlertDialog — structured base wrapper around the shadcn alert-dialog
- * primitive. Higher-level confirmation recipes belong in features/overlays.
+ * AlertDialog — internal confirmation anatomy behind `ConfirmDialog`.
+ *
+ * Not published from any entrypoint: applications use `ConfirmDialog` from
+ * `themelia-react-ui/features/overlays`, which owns the decision lifecycle.
+ * The surface shares the modal shell, region and typography geometry of the
+ * internal Dialog wrapper; the heading sits inside the scrolling body because
+ * a confirmation reads as one block above its pinned answers.
  */
 import * as React from 'react';
 import { AlertDialog as AlertDialogPrimitive, AlertDialogOverlay, AlertDialogPortal } from '../../ui/alert-dialog';
@@ -15,6 +20,7 @@ export declare const AlertDialogContent: React.ForwardRefExoticComponent<Omit<im
 export declare const AlertDialogHeader: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLDivElement> & React.HTMLAttributes<HTMLDivElement>, "ref"> & {
     textGap?: TextGap;
 } & React.RefAttributes<HTMLDivElement>>;
+/** Scroll-owning region above the pinned answers; rules appear only on edges hiding content. */
 export declare const AlertDialogBody: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
 export declare const AlertDialogFooter: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLDivElement> & React.HTMLAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export declare const AlertDialogTitle: React.ForwardRefExoticComponent<Omit<Omit<import("@base-ui/react").AlertDialogTitleProps, "ref"> & React.RefAttributes<HTMLHeadingElement>, "ref"> & React.RefAttributes<HTMLHeadingElement>>;

package/dist/components/base/display/content-block.d.ts

@@ -1,4 +1,3 @@
-/** @deprecated Use Card with surface="flat" and padding="none" for unframed content. */
 import { type HTMLAttributes, type ReactNode } from 'react';
 import type { ActionMenuAction } from '../action-menu';
 import type { StructureGap } from '../structure';
@@ -68,6 +67,9 @@ export interface ContentBlockProps extends Omit<HTMLAttributes<HTMLDivElement>,
     /** Overrides the block's own copy (overflow-menu and tooltip labels). */
     strings?: StringsProp<ContentBlockStrings>;
 }
-/** Migration adapter only; Card owns all rendering, slots and surface recipes. */
+/**
+ * Migration adapter only; Card owns all rendering, slots and surface recipes.
+ * @deprecated Use Card with surface="flat" and padding="none" for unframed content.
+ */
 export declare const ContentBlock: import("react").ForwardRefExoticComponent<ContentBlockProps & import("react").RefAttributes<HTMLDivElement>>;
 export { defaultContentBlockStrings, type ContentBlockStrings } from './content-block.strings';

package/dist/components/base/display/date-block.d.ts

@@ -31,7 +31,7 @@ export interface DateBlockProps extends Omit<ComponentPropsWithoutRef<'time'>, '
     time?: ReactNode;
     /** Override the machine-readable value placed on the native `<time>`. */
     dateTime?: string;
-    /** date-fns locale. Falls back to `<UIProvider dates={{ locale }}>`. */
+    /** date-fns locale. Falls back to `<UIProvider config={{ dates: { locale } }}>`. */
     locale?: Locale;
     /** Visual layout. @default "stacked" */
     layout?: DateBlockLayout;

package/dist/components/base/display/dialog.d.ts

@@ -1,10 +1,13 @@
 import type { TextGap } from '../structure';
 /**
- * Dialog — structured base wrapper around the shadcn dialog primitive.
+ * Dialog — internal modal anatomy behind `ActionDialog`.
  *
- * Primitive state and composition props pass through unchanged. The package
- * wrapper supplies deliberate modal anatomy: separated header and footer,
- * a scroll-owning body, tokenized spacing, and stable BEM hooks.
+ * Not published from any entrypoint: applications use `ActionDialog` (or
+ * `ConfirmDialog`) from `themelia-react-ui/features/overlays`, which owns the
+ * lifecycle, focus, dismissal and action contract. This wrapper supplies the
+ * modal geometry those features share: one framed popover surface whose shell
+ * owns the block inset and the gap between header, scrolling body and footer,
+ * as Card does, with no static rules between regions.
  */
 import * as React from 'react';
 import { Dialog as DialogPrimitive, DialogOverlay, DialogPortal } from '../../ui/dialog';
@@ -21,7 +24,11 @@ export declare const DialogContent: React.ForwardRefExoticComponent<Omit<import(
 export declare const DialogHeader: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLDivElement> & React.HTMLAttributes<HTMLDivElement>, "ref"> & {
     textGap?: TextGap;
 } & React.RefAttributes<HTMLDivElement>>;
-/** Scroll-owning content region between the fixed dialog header and footer. */
+/**
+ * Scroll-owning content region between the pinned dialog header and footer.
+ * A rule appears on its top or bottom edge only while content is scrolled out
+ * of view there.
+ */
 export declare const DialogBody: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
 export declare const DialogFooter: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLDivElement> & React.HTMLAttributes<HTMLDivElement> & {
     showCloseButton?: boolean;

package/dist/components/base/display/surface-title.d.ts

@@ -1,5 +1,10 @@
 import type { ReactNode } from 'react';
-/** One wrapping title/suffix composition shared by cards and content structures. */
+/**
+ * One wrapping title/suffix composition shared by cards and content structures.
+ * A plain-text title is exposed as a level-2 heading (below the page's h1) so
+ * screen-reader users can move between surfaces; suffix badges stay outside its
+ * accessible name. Custom title nodes keep their own semantics.
+ */
 export declare function SurfaceTitle({ title, suffix, size, className, suffixClassName, dataSlot }: {
     title?: ReactNode;
     suffix?: ReactNode;

package/dist/components/base/feedback/alert.d.ts

@@ -40,7 +40,7 @@ export interface AlertMetadataItemProps extends Omit<ComponentPropsWithoutRef<'d
     label: ReactNode;
     /** User-provided metadata value. May contain a package value primitive. */
     value: ReactNode;
-    /** Applies tabular monospace figures to simple numeric values. */
+    /** Applies tabular figures to simple numeric values, in the sans UI font. */
     numeric?: boolean;
 }
 /** A label/value pair rendered with native `dt` and `dd` semantics. */

package/dist/components/base/feedback/state-display.d.ts

@@ -9,13 +9,13 @@ export interface LoadingStateProps extends DivProps {
     description?: ReactNode;
     /** Completion percentage, 0-100, for determinate loading. */
     progress?: number;
-    /** Which state is shown — loading, empty, or error. */
+    /** `inline` (default) for a chrome-free status inside an existing region; `panel` for one framed surface. */
     variant?: LoadingStateVariant;
     /** Renders placeholder bars instead of a message. */
     skeleton?: boolean | ReactNode;
     /** How many skeleton bars to draw. */
     lines?: number;
-    /** Glyph shown above the message. */
+    /** Leading glyph beside the message. Defaults to a spinning loader. */
     icon?: ReactNode;
 }
 export declare const LoadingState: import("react").ForwardRefExoticComponent<LoadingStateProps & import("react").RefAttributes<HTMLDivElement>>;
@@ -27,12 +27,13 @@ export interface ErrorStateProps extends Omit<DivProps, 'title'> {
     description?: ReactNode;
     /** Control offered alongside the message. */
     action?: ReactNode;
+    /** Renders a retry button (with `retryLabel`) that calls this. Ignored when `action` is set. */
     onRetry?: () => void;
     /** Copy for the retry action in the error state. */
     retryLabel?: ReactNode;
-    /** Which state is shown — loading, empty, or error. */
+    /** `panel` (default) for one framed surface; `inline` for a chrome-free status inside an existing region. */
     variant?: ErrorStateVariant;
-    /** Glyph shown above the message. */
+    /** Leading glyph beside the message. Defaults to an alert icon. */
     icon?: ReactNode;
 }
 export declare const ErrorState: import("react").ForwardRefExoticComponent<ErrorStateProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/base/forms/form-field.d.ts

@@ -31,6 +31,7 @@ export interface FieldChromeProps {
 }
 export interface FormFieldProps extends FieldChromeProps, Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
     children: ReactNode;
+    /** Native ID of the labelled control. With compound children, assign it to the nested control; passive wrappers are left untouched. Direct controls receive an automatic ID when omitted. */
     htmlFor?: string;
     /** ID for the resolved hint, helper, or error; controls can reference it explicitly. */
     supportingTextId?: string;

package/dist/components/base/forms/form-sizing.d.ts

@@ -27,12 +27,12 @@ export declare const formControlIconClasses: {
 export declare const formControlIconOffsetClasses: {
     sm: string;
     md: string;
-    lg: "ps-[calc((var(--control-x)+var(--icon)*1.25+0.5rem)*var(--space-scale))]";
+    lg: "ps-[calc((var(--control-x)+0.5rem)*var(--space-scale)+var(--icon)*1.25)]";
 };
 export declare const formControlEndIconOffsetClasses: {
     sm: string;
     md: string;
-    lg: "pe-[calc((var(--control-x)+var(--icon)*1.25+0.5rem)*var(--space-scale))]";
+    lg: "pe-[calc((var(--control-x)+0.5rem)*var(--space-scale)+var(--icon)*1.25)]";
 };
 export declare const formControlAddonOffsetClasses: {
     sm: string;
@@ -63,11 +63,15 @@ export declare const formControlMinHeightClasses: {
  * Canonical "input-shaped trigger" chrome — used by any control that
  * renders as a button-style trigger but visually has to read as a form
  * field (DatePicker, TimePicker, the inner Select inside composite
- * fields, etc.). Mirrors `Input`'s `border-input rounded-radius
+ * fields, etc.). Mirrors `Input`'s `border-input rounded-inner
  * bg-transparent focus-visible:ring` chrome (no shadow — the library
  * is intentionally flat) plus the size-driven height + horizontal
  * padding.
  *
+ * The displayed value is the field's value, so it follows the editable text
+ * recipe: on coarse pointers it matches the touch input size of an adjoining
+ * `Input` instead of rendering a step smaller.
+ *
  * Kept here so the chrome lives in exactly one place — when we tweak
  * the canonical input look, every trigger picks it up.
  */
@@ -77,6 +81,34 @@ export declare const formTextareaSizeClasses: {
     md: string;
     lg: string;
 };
+/**
+ * Vertical inset of multi-line fields. Their first line sits exactly where a
+ * single-line control of the same size draws its value (inside the 1px border),
+ * so a Textarea beside an Input shares its first line. `1lh` is the field's own
+ * line height, so the inset follows the editable text size on every pointer.
+ */
+export declare const formTextareaInsetClasses: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+/**
+ * Top offsets that centre multi-line field affordances on the first line, where a
+ * single-line control of the same size centres them: the clear target
+ * (`size-control-clear`) and a `size-icon` glyph such as the loading spinner.
+ */
+export declare const formTextareaAffordanceTopClasses: {
+    readonly target: {
+        readonly sm: "top-[calc((var(--height-control)*8/9-1.375rem)*var(--density-scale)/2)]";
+        readonly md: "top-[calc((var(--height-control)-1.375rem)*var(--density-scale)/2)]";
+        readonly lg: "top-[calc((var(--height-control)*10/9-1.375rem)*var(--density-scale)/2)]";
+    };
+    readonly icon: {
+        readonly sm: "top-[calc((var(--height-control)*8/9*var(--density-scale)-var(--icon))/2)]";
+        readonly md: "top-[calc((var(--height-control)*var(--density-scale)-var(--icon))/2)]";
+        readonly lg: "top-[calc((var(--height-control)*10/9*var(--density-scale)-var(--icon))/2)]";
+    };
+};
 export declare const formLabelSizeClasses: {
     sm: string;
     md: string;

package/dist/components/base/forms/workflow.d.ts

@@ -58,6 +58,8 @@ export interface DirtyStateBannerProps {
 }
 export declare function DirtyStateBanner({ title, description, actions, tone, className, }: DirtyStateBannerProps): import("react").JSX.Element;
 export interface SubmitStateButtonProps extends Omit<ButtonProps, 'loading'> {
+    /** Semantic color. Defaults to `primary`: submitting is the form's main command. */
+    tone?: ButtonProps['tone'];
     /** Shows the pending state and blocks repeat submissions. */
     submitting?: boolean;
     /** Whether the form has unsaved changes. */

package/dist/components/base/forms-numeric/coordinates-input.d.ts

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { type StringsProp } from '../../../lib/strings';
+import type { FormControlSize } from '../../../lib/ui-provider';
 export interface CoordinatesObjectValue {
     lat?: string;
     lng?: string;
@@ -43,5 +44,7 @@ export interface CoordinatesInputProps {
     className?: string;
     /** Disabled state */
     disabled?: boolean;
+    /** Control-height preset for both fields. Falls back to `UIProvider.density.defaultScale`, like the other numeric inputs. */
+    size?: FormControlSize;
 }
 export declare const CoordinatesInput: React.ForwardRefExoticComponent<CoordinatesInputProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/base/forms-numeric/rounding-mode-select.d.ts

@@ -5,7 +5,10 @@ export interface RoundingModeSelectProps extends Omit<SelectProps, 'options' | '
     value?: RoundingMode;
     /** Canonical change handler. */
     onValueChange?: (value: RoundingMode | undefined) => void;
-    /** Custom labels for rounding modes */
+    /**
+     * Labels for the rounding modes. Defaults to sentence-case names: `floor` →
+     * "Round down", `half_up` → "Round half up", `ceil` → "Round up".
+     */
     labels?: Partial<Record<RoundingMode, string>>;
 }
 export declare const RoundingModeSelect: import("react").ForwardRefExoticComponent<RoundingModeSelectProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/base/navigation/dropdown-menu.d.ts

@@ -16,13 +16,13 @@ declare function DropdownMenuLabel({ className, inset, children, ...props }: Men
 declare function DropdownMenuItem({ className, inset, variant, children, ...props }: MenuPrimitive.Item.Props & {
     /** Surface inset. */
     inset?: boolean;
-    /** Semantic tone. */
+    /** Row treatment. `destructive` marks a command that removes or destroys data. Defaults to `default`. */
     variant?: 'default' | 'destructive';
 }): React.JSX.Element;
 declare function DropdownMenuLinkItem({ className, inset, variant, children, ...props }: MenuPrimitive.LinkItem.Props & {
     /** Surface inset. */
     inset?: boolean;
-    /** Semantic tone. */
+    /** Row treatment. `destructive` marks a command that removes or destroys data. Defaults to `default`. */
     variant?: 'default' | 'destructive';
 }): React.JSX.Element;
 declare function DropdownMenuSub({ ...props }: MenuPrimitive.SubmenuRoot.Props): React.JSX.Element;

package/dist/components/base/navigation/language-switcher.d.ts

@@ -1,9 +1,12 @@
 import type { LocaleOption } from '../../../types/locale.types';
 export interface LanguageSwitcherProps {
+    /** Locales to offer, in order. The entry with `active: true` is marked as current. */
     locales: LocaleOption[];
+    /** Custom label for each locale. Defaults to `nativeLabel`. */
     onRenderLabel?: (options: LocaleOption) => string;
-    /** Semantic tone. */
+    /** Layout: `buttons` (default) for a row of buttons, `inline` for compact dot-separated text links. */
     variant?: 'buttons' | 'inline';
+    /** Called with the chosen locale's value. Not called for the current locale. */
     onSelect?: (value: string) => void;
 }
 export declare function LanguageSwitcher({ locales, onRenderLabel, variant, onSelect, }: LanguageSwitcherProps): import("react").JSX.Element | null;

package/dist/components/base/navigation/overflow-tab-bar.d.ts

@@ -5,6 +5,11 @@
  * container resize; the active tab is always kept visible by being moved
  * out of the overflow set when needed.
  *
+ * The strip shares the segmented-tab recipe of `NavigationTabs` and `Tabs`:
+ * a muted track, small action-height tabs with default-size labels, and a
+ * lifted card-coloured active tab. Arrow keys, Home and End move focus between
+ * tabs; Enter or Space activates the focused tab.
+ *
  * Use `NavigationTabs` instead when a fixed route set cannot overflow.
  */
 import { type LucideIcon } from 'lucide-react';
@@ -40,4 +45,6 @@ export interface OverflowTabBarProps extends Omit<ComponentPropsWithoutRef<'div'
     /** Overrides this surface's own copy. */
     strings?: StringsProp<OverflowTabBarStrings>;
 }
+/** How many tabs fit, reserving room for the "More" trigger only when something overflows. */
+export declare function fitOverflowTabs(widths: readonly number[], available: number, gap: number, moreWidth: number): number;
 export declare const OverflowTabBar: import("react").ForwardRefExoticComponent<OverflowTabBarProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/base/navigation/page-header/page-header.d.ts

@@ -79,7 +79,10 @@ export interface PageHeadingProps {
     descriptionClassName?: string;
     /** Merged onto the actions cluster. */
     actionsClassName?: string;
-    /** Draws the rule beneath the header. Default: `true`. */
+    /**
+     * Draws a rule beneath the header. Default: `false` — the page rhythm (gap
+     * between header and body) separates them; opt in where a rule is the design.
+     */
     withSeparator?: boolean;
 }
 export declare function PageHeading({ eyebrow, title, description, textGap, headingTag, badge, badges, breadcrumbs, leading, beforeTitle, titlePrefix, titleSuffix, afterDescription, actions, children, className, contentClassName, eyebrowClassName, titleClassName, titleRowClassName, descriptionClassName, actionsClassName, withSeparator, }: PageHeadingProps): import("react").JSX.Element;

package/dist/components/base/navigation/tabs.d.ts

@@ -1,11 +1,9 @@
 /**
  * Typography- and token-aware wrappers around the internal shadcn tabs parts.
  *
- * The shadcn source is left untouched, so its literal `gap-1.5 rounded-md px-2
- * py-1` reached consumers unchanged and opted tabs out of scoped `--space-scale`
- * and `--radius` overrides — the only interactive family in the package that
- * did. These wrappers restate the same values as tokens; `cn` merges them last,
- * so they win. Every value below is pixel-identical to the primitive's default.
+ * Raw anatomy and these wrappers share token-backed spacing. The wrappers
+ * add stable public hooks, canonical corners, scalar text and scroll controls;
+ * the primitive owns tab/list interaction and the nested list inset.
  */
 import type { ComponentProps } from 'react';
 import { Tabs as PrimitiveTabs, TabsContent as PrimitiveTabsContent, TabsList as PrimitiveTabsList, TabsTrigger as PrimitiveTabsTrigger } from '../../ui/tabs';

package/dist/components/base/popover/popover.recipes.d.ts

@@ -1,12 +1,12 @@
 import { type RowDensity } from '../../../lib/row-recipes';
 /** Shared anchored-surface chrome; Menu and Popover retain their own accessible behavior. */
 export declare const popoverRecipes: {
-    readonly surface: "rounded-radius border border-border/60 bg-popover text-popover-foreground shadow-md ring-0";
+    readonly surface: "box-border rounded-radius border border-border bg-popover text-popover-foreground shadow-md ring-0";
     readonly display: "p-surface";
     readonly menu: "p-surface-xs";
     readonly menuRegion: "px-surface-xs py-space-md";
     readonly separator: "mx-0 my-space-xs h-px w-full shrink-0 bg-border/60";
-    readonly row: "min-h-control rounded-inner px-row-x gap-space-sm font-medium leading-tight";
+    readonly row: "box-border min-h-control rounded-inner px-row-x gap-space-sm font-medium leading-tight";
 };
 export type PopoverContentType = 'display' | 'menu';
 /** One surface inset vocabulary for Popover, Command and their collections. */
@@ -24,6 +24,6 @@ export declare const collectionRecipes: {
     readonly interactive: "relative flex cursor-default items-center outline-none select-none transition-colors";
     readonly highlighted: "data-highlighted:bg-accent data-highlighted:text-accent-foreground data-highlighted:[&_svg]:text-accent-foreground";
     readonly disabled: "data-disabled:pointer-events-none data-disabled:opacity-50";
-    readonly destructive: "data-[variant=destructive]:text-destructive data-[variant=destructive]:data-highlighted:bg-destructive/10 data-[variant=destructive]:data-highlighted:text-destructive dark:data-[variant=destructive]:data-highlighted:bg-destructive/20 data-[variant=destructive]:[&_svg]:text-destructive data-[variant=destructive]:data-highlighted:[&_svg]:text-destructive";
+    readonly destructive: "data-[variant=destructive]:text-destructive data-[variant=destructive]:data-highlighted:bg-destructive/10 data-[variant=destructive]:data-highlighted:text-destructive dark:data-[variant=destructive]:data-highlighted:bg-destructive/10 data-[variant=destructive]:[&_svg]:text-destructive data-[variant=destructive]:data-highlighted:[&_svg]:text-destructive";
     readonly tableRow: "min-h-action-xs py-space-2xs";
 };

package/dist/components/base/qr-code/qr-code.d.ts

@@ -1,11 +1,13 @@
 import { type HTMLAttributes } from 'react';
 export type QRCodeProps = HTMLAttributes<HTMLDivElement> & {
+    /** Encoded payload. Pass `aria-label` to describe it; the code is then exposed as one image. */
     data: string;
     foreground?: string;
     background?: string;
     robustness?: 'L' | 'M' | 'Q' | 'H';
 };
 export declare const QRCode: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
+    /** Encoded payload. Pass `aria-label` to describe it; the code is then exposed as one image. */
     data: string;
     foreground?: string;
     background?: string;