themelia-react-ui 1.0.2 → 2.0.0

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/datepicker.types.d.ts

@@ -72,11 +72,21 @@ export interface DatePickerBaseProps {
     /** 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-sizing.d.ts

@@ -68,6 +68,10 @@ export declare const formControlMinHeightClasses: {
  * 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/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;

package/dist/components/base/sheet/index.d.ts

@@ -1 +1,29 @@
-export { Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetBody, SheetFooter, SheetTitle, SheetDescription, } from './sheet';
+/**
+ * Deprecated compatibility entrypoint.
+ *
+ * `ActionDrawer` from `themelia-react-ui/features/overlays` is the supported
+ * slide-in panel: it owns the scrim, focus, dismissal, pending lock and action
+ * footer, and `ActionDialog` / `ConfirmDialog` cover centred dialogs. These
+ * parts remain the internal anatomy behind ActionDrawer and the mobile sidebar
+ * drawer, which import the implementation module directly. They keep working
+ * through 1.x for existing callers.
+ */
+export { 
+/** @deprecated Use `ActionDrawer` from `themelia-react-ui/features/overlays`; it owns open state through `open`/`onOpenChange` or `trigger`. */
+Sheet, 
+/** @deprecated Use the `trigger` prop of `ActionDrawer` from `themelia-react-ui/features/overlays`, or `useOverlayVisibility` for an external control. */
+SheetTrigger, 
+/** @deprecated `ActionDrawer` from `themelia-react-ui/features/overlays` renders its own dismiss control (`showCloseButton`) and cancel action. */
+SheetClose, 
+/** @deprecated Use `ActionDrawer` from `themelia-react-ui/features/overlays` (`direction`, `width`, `modal`). */
+SheetContent, 
+/** @deprecated Use the `title`/`description` props of `ActionDrawer` from `themelia-react-ui/features/overlays`. */
+SheetHeader, 
+/** @deprecated Pass content as `children` of `ActionDrawer` from `themelia-react-ui/features/overlays`; it owns the scrolling body. */
+SheetBody, 
+/** @deprecated Use the generated actions or the `footer` prop of `ActionDrawer` from `themelia-react-ui/features/overlays`. */
+SheetFooter, 
+/** @deprecated Use the `title` prop of `ActionDrawer` from `themelia-react-ui/features/overlays`. */
+SheetTitle, 
+/** @deprecated Use the `description` prop of `ActionDrawer` from `themelia-react-ui/features/overlays`. */
+SheetDescription, } from './sheet';

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

@@ -1,10 +1,15 @@
 import type { TextGap } from '../structure';
 /**
- * Sheet — design-system wrapper around the shadcn compound primitive.
+ * Sheet — internal edge-anchored modal anatomy behind `ActionDrawer` and the
+ * mobile sidebar drawer.
  *
- * The root and trigger behavior stay primitive-compatible. The package layer
- * adds a deliberate header / scrollable body / footer structure, calm admin
- * spacing, and stable BEM hooks without narrowing primitive props.
+ * Applications use `ActionDrawer` from `themelia-react-ui/features/overlays`,
+ * which owns the lifecycle, focus, dismissal and action contract; the
+ * `themelia-react-ui/base/sheet` entrypoint remains only as a deprecated
+ * compatibility surface. The panel shares the modal geometry of the internal
+ * Dialog wrapper: the shell owns the block inset and the gap between header,
+ * scrolling body and footer, regions own their inline inset, and one edge rule
+ * separates the panel from the page.
  */
 import * as React from 'react';
 import { Sheet as SheetPrimitive } from '../../ui/sheet';
@@ -24,7 +29,11 @@ export declare const SheetContent: React.ForwardRefExoticComponent<Omit<import("
 export declare const SheetHeader: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLDivElement> & React.HTMLAttributes<HTMLDivElement>, "ref"> & {
     textGap?: TextGap;
 } & React.RefAttributes<HTMLDivElement>>;
-/** Scroll-owning content region between the fixed sheet header and footer. */
+/**
+ * Scroll-owning content region between the pinned sheet header and footer.
+ * A rule appears on its top or bottom edge only while content is scrolled out
+ * of view there.
+ */
 export declare const SheetBody: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
 export declare const SheetFooter: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLDivElement> & React.HTMLAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export declare const SheetTitle: React.ForwardRefExoticComponent<Omit<import("@base-ui/react").AlertDialogTitleProps & {

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

@@ -20,10 +20,11 @@ export interface SpinnerStrings {
 }
 export declare const defaultSpinnerStrings: SpinnerStrings;
 export interface SpinnerProps {
-    /** Display label. */
+    /** Visible label under the indicator; also its accessible name. */
     label?: string;
+    /** Merged onto the indicator graphic (size, colour), not the padded wrapper. */
     className?: string;
-    /** Semantic tone. */
+    /** Indicator style: circular `default`, `shimmer`, or `progress` strip. Defaults to `UIProvider.spinner.defaultVariant`, then `default`. */
     variant?: SpinnerVariant;
     /** Localizes the fallback progress-bar name. */
     strings?: StringsProp<SpinnerStrings>;

package/dist/components/base/structure/structure.types.d.ts

@@ -3,7 +3,7 @@ import type { ComponentScale } from '../../../lib/component-vocabulary';
 export type StructureBreakpoint = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
 export type ResponsiveValue<T> = T | Partial<Record<StructureBreakpoint, T>>;
 export type TextGap = 'normal' | 'dense';
-export type StructureGap = TextGap | 'none' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export type StructureGap = TextGap | 'none' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
 export type StructureAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
 export type StructureJustify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
 export interface StackProps extends useRender.ComponentProps<'div'> {

package/dist/components/base/text-inputs/input-group.d.ts

@@ -35,8 +35,8 @@ export type InputGroupTextareaProps = ComponentProps<typeof InputGroupTextareaPr
 declare function InputGroup({ className, ...props }: InputGroupProps): import("react").JSX.Element;
 /** Leading/trailing (or block start/end) affordance slot inside the frame. */
 declare function InputGroupAddon({ className, align, ...props }: InputGroupAddonProps): import("react").JSX.Element;
-/** Inline action button sized to sit inside the control frame. */
-declare function InputGroupButton({ className, tone, buttonStyle, ...props }: InputGroupButtonProps): import("react").JSX.Element;
+/** Inline action button sized to sit inside the control frame; its label stays on one line. */
+declare function InputGroupButton({ className, tone, buttonStyle, truncate, ...props }: InputGroupButtonProps): import("react").JSX.Element;
 /** Static copy segment — scalar text renders through Typography. */
 declare function InputGroupText({ children, className, ...props }: InputGroupTextProps): import("react").JSX.Element;
 /** Single-line control that inherits the group's frame instead of its own. */

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

@@ -0,0 +1,11 @@
+/**
+ * Private drop-target states shared by Dropzone, AvatarUpload and ImageUpload.
+ * An empty target draws the dashed `--input` control boundary (3:1 on every
+ * surface), so all three upload targets read as the same kind of control.
+ * Hover, drag and invalid states replace only the boundary colour and fill.
+ */
+export declare const uploadDropTargetRecipes: {
+    readonly idle: "border-input";
+    readonly invalid: "border-destructive";
+    readonly dragging: "border-primary bg-primary/10";
+};

package/dist/components/base/value-inputs/date-time-input.d.ts

@@ -7,13 +7,15 @@ export interface DateTimeInputProps {
     placeholder?: string;
     /** Display format for the date */
     readableFormat?: string;
-    /** Step for time selection in minutes */
+    /** Step for time selection, in minutes. Default `30`. */
     stepMinutes?: number;
     /** Use modal for picker */
     modal?: boolean;
-    /** Error state for styling (passed from FormField) */
+    /** Error state for styling (passed from FormField). Validation copy stays with FormField. */
     invalid?: boolean;
     /** Disabled state */
     disabled?: boolean;
+    /** Id of the trigger, so an external `<FormField label>` names it. Defaults to a generated id. */
+    id?: string;
 }
 export declare const DateTimeInput: import("react").ForwardRefExoticComponent<DateTimeInputProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/base/value-inputs/tags-input.d.ts

@@ -8,6 +8,8 @@ export interface TagsInputStrings {
      *  `current` (number of tags entered) and `max` (the limit). The
      *  default is English `"{current} / {max} tags"` — override for i18n. */
     summary: (current: number, max: number) => string;
+    /** Accessible name of a tag's remove action. Defaults to `"Remove {tag}"`. */
+    removeTag?: (tag: string) => string;
 }
 export declare const defaultTagsInputStrings: TagsInputStrings;
 export interface TagsInputProps<T = string> {

package/dist/components/blocks/admin/api-key-list/api-key-list.types.d.ts

@@ -23,7 +23,7 @@ export interface ApiKeyListItem {
      * full secret.
      */
     displayValue?: string;
-    /** Optional per-item icon override (defaults to a Lock). */
+    /** Optional per-item leading icon. Rows render without one by default. */
     icon?: ReactNode;
     /** Disable the per-item dropdown when true. */
     disabled?: boolean;

package/dist/components/blocks/analytics/format-metric-value.d.ts

@@ -1,5 +1,15 @@
+import type { MoneyFormatMode } from '../../../lib/ui-provider';
 import type { MetricData } from './types';
-export declare function formatMetricValue(data: MetricData): string;
+/** Display policy that metric components resolve from UIProvider. */
+export interface FormatMetricValueOptions {
+    /** BCP-47 locale. Metric components pass `UIProvider.formatting.locale`. */
+    locale?: string;
+    /** Currency used when the metric has none. Defaults to `USD`, like UIProvider. */
+    defaultCurrency?: string;
+    /** Money format policy. Defaults to `with_code`, like UIProvider. */
+    moneyFormatMode?: MoneyFormatMode;
+}
+export declare function formatMetricValue(data: MetricData, options?: FormatMetricValueOptions): string;
 /**
  * Resolve the effective `MetricTrend` for a metric — explicit `trend` wins,
  * otherwise we infer from `change.direction` (`up` → positive, `down` →

package/dist/components/blocks/analytics/index.d.ts

@@ -19,7 +19,7 @@
  */
 export type { MetricChange, MetricColorScheme, MetricData, MetricDataPoint, MetricDirection, MetricPeriod, MetricSize, MetricTrend, MetricTrendVariant, MetricValueType, MetricVariant, } from './types';
 export { defaultAnalyticsStrings, type AnalyticsStrings, } from './analytics.strings';
-export { formatMetricValue, resolveTrend } from './format-metric-value';
+export { formatMetricValue, resolveTrend, type FormatMetricValueOptions } from './format-metric-value';
 export { MetricTrendChip, type MetricTrendChipProps } from './atoms/metric-trend-chip';
 export { MetricSparkline, type MetricSparklineProps } from './atoms/metric-sparkline';
 export { MetricSkeleton, type MetricSkeletonProps } from './atoms/metric-skeleton';

package/dist/components/blocks/analytics/use-metric-format-options.d.ts

@@ -0,0 +1,3 @@
+import type { FormatMetricValueOptions } from './format-metric-value';
+/** Metric formatting policy from UIProvider: locale, default currency and money format. */
+export declare function useMetricFormatOptions(): FormatMetricValueOptions;

package/dist/components/blocks/commerce/address-card/address-card.d.ts

@@ -1,5 +1,5 @@
 import { type AddressCardProps } from './types';
-export declare function AddressCard({ kind, name, line1, line2, city, region, postalCode, country, phone, default: defaultAddress, onEdit, onRemove, onMakeDefault, className, strings: stringsProp, }: AddressCardProps): import("react").JSX.Element;
+export declare function AddressCard({ kind, name, line1, line2, city, region, postalCode, country, phone, default: defaultAddress, onEdit, onRemove, onMakeDefault, surface, padding, headerDivider, className, strings: stringsProp, }: AddressCardProps): import("react").JSX.Element;
 export declare namespace AddressCard {
     var displayName: string;
 }

package/dist/components/blocks/commerce/address-card/types.d.ts

@@ -1,3 +1,4 @@
+import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 export type AddressKind = 'shipping' | 'billing' | 'pickup';
 export interface AddressCardStrings {
@@ -10,7 +11,8 @@ export interface AddressCardStrings {
     pickup: string;
 }
 export declare const defaultAddressCardStrings: AddressCardStrings;
-export interface AddressCardProps {
+/** Unframed by default. Set surface="card" to let this owner frame its heading and body. */
+export interface AddressCardProps extends Pick<CardProps, 'surface' | 'padding' | 'headerDivider'> {
     /** What the address is for — billing, shipping, or both. */
     kind?: AddressKind;
     /** Display name. */

package/dist/components/blocks/commerce/booking-calendar-event-card/booking-calendar-event-card.d.ts

@@ -2,6 +2,10 @@ import type { BookingCalendarEventCardProps } from './booking-calendar-event-car
 /**
  * Compact, card-free booking detail composition.
  *
+ * The status sits beside the title, the facts share one label-above-value
+ * layout, and spacing alone separates them from the action: no header rule,
+ * no inset note panel and no rule above the action.
+ *
  * All visible copy is supplied by props, so this component intentionally has
  * no strings file. Frame it with `Card` only when the page needs card
  * chrome.

package/dist/components/blocks/commerce/booking-calendar-event-card/booking-calendar-event-card.types.d.ts

@@ -7,7 +7,7 @@ export interface BookingCalendarEventCardItem {
     label: ReactNode;
     /** Display value. Strings and numbers use the canonical `Value` primitive. */
     value: ReactNode;
-    /** Span both detail columns and receive the emphasized note treatment. */
+    /** Span both detail columns, for a note that should not sit in a column. */
     fullWidth?: boolean;
 }
 /**
@@ -21,7 +21,7 @@ export interface BookingCalendarEventCardProps {
     title: ReactNode;
     /** Optional supporting context shown beneath the title. */
     description?: ReactNode;
-    /** Optional status or metadata rendered at the end of the header. */
+    /** Optional status, rendered beside the title. */
     status?: ReactNode;
     /** Ordered booking facts rendered as a responsive definition list. */
     items: BookingCalendarEventCardItem[];