themelia-react-ui 1.0.2 → 2.0.1

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

@@ -16,6 +16,6 @@ export { LanguageSwitcher, type LanguageSwitcherProps } from './language-switche
 export { NavigationTabs, defaultNavigationTabsStrings, type NavigationTabItem, type NavigationTabsProps, type NavigationTabsStrings, type NavigationTabsVariant, } from './navigation-tabs';
 export { Tabs, TabsContent, TabsList, TabsTrigger, type TabsListProps } from './tabs';
 export { defaultTabsScrollStrings, type TabsScrollStrings } from './tab-scroll-viewport';
-export { PageHeading, type PageHeadingProps, type PageHeadingBadge, } from './page-header';
+export { PageHeading, type PageHeadingProps, type PageHeadingBadge, type PageHeaderAction, type PageHeaderLinkRenderProps, type PageHeaderLinkRenderer, } from './page-header';
 export { OverflowTabBar, defaultOverflowTabBarStrings, type OverflowTabBarProps, type OverflowTabBarStrings, type OverflowTabItem, } from './overflow-tab-bar';
 export { PaginationPrimitive, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, defaultPaginationStrings, type PaginationContentProps, type PaginationEllipsisProps, type PaginationItemProps, type PaginationLinkProps, type PaginationNextProps, type PaginationPreviousProps, type PaginationProps, type PaginationStrings, } from './pagination';

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

@@ -1 +1,2 @@
 export { PageHeading, type PageHeadingProps, type PageHeadingBadge, } from './page-header';
+export { type PageHeaderAction, type PageHeaderLinkRenderProps, type PageHeaderLinkRenderer, } from './page-header-commands';

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

@@ -0,0 +1,73 @@
+/**
+ * PageHeaderCommands — role-based commands for page and record headers.
+ *
+ * The role chooses each command's treatment and place: outline secondary
+ * commands, then one solid primary command, then the More actions menu for
+ * overflow and destructive commands, which always closes the row. Below `sm`,
+ * secondary commands collapse into that menu through CSS alone, so server and
+ * client markup agree. PageHeading owns the row, so every header that takes
+ * `primaryAction` and `secondaryActions` places its commands the same way.
+ */
+import type { ComponentType, MouseEvent, ReactNode } from 'react';
+/**
+ * A page command described by its role. `primaryAction` and `secondaryActions`
+ * choose the treatment, so a command carries no tone or button style.
+ */
+export interface PageHeaderAction {
+    /** Stable key. Defaults to the command's position. */
+    id?: string;
+    /** Visible command text. */
+    label: ReactNode;
+    /** Runs the command. When both are set, `onClick` wins over `href`. */
+    onClick?: () => void;
+    /** Navigates through the header's `renderLink` instead of running a callback. */
+    href?: string;
+    target?: string;
+    rel?: string;
+    /** Marks the destination as leaving the app; forwarded to `renderLink`. */
+    external?: boolean;
+    /** Leading glyph. Pass a Lucide icon component. */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Shows the pending indicator and blocks activation. */
+    loading?: boolean;
+    /** Blocks activation while keeping the command visible. */
+    disabled?: boolean;
+    /** Set false to omit the command, for example without permission. */
+    visible?: boolean;
+    /**
+     * Irreversible or harmful command. A destructive secondary command moves to
+     * the More actions menu; a destructive primary command keeps its place with
+     * the destructive treatment. Confirm it from the handler, e.g. ConfirmDialog.
+     */
+    destructive?: boolean;
+}
+/** What a header hands its link renderer for an `href` command. */
+export interface PageHeaderLinkRenderProps {
+    href: string;
+    children: ReactNode;
+    className?: string;
+    target?: string;
+    rel?: string;
+    /** Marks the destination as leaving the app. */
+    external?: boolean;
+    onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+    'aria-label'?: string;
+}
+/** Renders framework links for `href` commands. Layout `renderLink` functions fit. */
+export type PageHeaderLinkRenderer = (props: PageHeaderLinkRenderProps) => ReactNode;
+/** Native anchor fallback, matching the layout default: external links open a new tab. */
+export declare const defaultPageHeaderLinkRenderer: PageHeaderLinkRenderer;
+/** Secondary commands rendered as buttons from `sm` up; later ones overflow. */
+export declare const PAGE_HEADER_INLINE_SECONDARY_LIMIT = 2;
+export interface PageHeaderCommandsProps {
+    primaryAction?: PageHeaderAction;
+    secondaryActions?: readonly PageHeaderAction[];
+    /** Accessible name of the More actions menu trigger. */
+    moreActionsLabel: string;
+    renderLink?: PageHeaderLinkRenderer;
+}
+/** Whether the header has any role-based command to render. */
+export declare function hasPageHeaderCommands(primaryAction: PageHeaderAction | undefined, secondaryActions: readonly PageHeaderAction[] | undefined): boolean;
+export declare function PageHeaderCommands({ primaryAction, secondaryActions, moreActionsLabel, renderLink, }: PageHeaderCommandsProps): import("react").JSX.Element | null;

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

@@ -2,12 +2,15 @@
  * PageHeading — reusable visual heading block for sections and resources.
  * Higher-level layout components add routing/back behavior around this base
  * visual primitive instead of reimplementing title, description, badge, and
- * action spacing.
+ * action spacing. `primaryAction` and `secondaryActions` describe commands by
+ * role; the heading owns their treatment and placement for every header built
+ * on it.
  */
 import type { Key, ReactNode } from 'react';
 import { type HeadingTag } from '../../../typography';
 import { type BadgeTone } from '../../badge';
 import { type TextGap } from '../../structure';
+import { type PageHeaderAction, type PageHeaderLinkRenderer } from './page-header-commands';
 export interface PageHeadingBadge {
     label: ReactNode;
     tone?: BadgeTone;
@@ -58,8 +61,28 @@ export interface PageHeadingProps {
     titleSuffix?: ReactNode;
     /** Content directly beneath the description, sharing its alignment — a metadata line. */
     afterDescription?: ReactNode;
-    /** Independent actions column beside the copy; follows it on narrow widths. */
+    /**
+     * Independent actions column beside the copy; follows it on narrow widths.
+     * Holds non-command controls such as a period select; they render before
+     * the role-based commands.
+     */
     actions?: ReactNode;
+    /**
+     * The header's one main command: a solid primary button after the secondary
+     * commands, visible at every width.
+     */
+    primaryAction?: PageHeaderAction;
+    /**
+     * Supporting commands in priority order. The first two render as outline
+     * buttons before the primary command; the rest, and every destructive
+     * command, move into the More actions menu, which always closes the row.
+     * Below `sm`, all secondary commands collapse into that menu.
+     */
+    secondaryActions?: readonly PageHeaderAction[];
+    /** Accessible name of the More actions menu trigger. Default: `'More actions'`. */
+    moreActionsLabel?: string;
+    /** Renders `href` commands as framework links. Defaults to a native anchor. */
+    renderLink?: PageHeaderLinkRenderer;
     /** Content below the whole header block, above the separator. */
     children?: ReactNode;
     /** Merged onto the `<header>` root. */
@@ -79,10 +102,13 @@ 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;
+export declare function PageHeading({ eyebrow, title, description, textGap, headingTag, badge, badges, breadcrumbs, leading, beforeTitle, titlePrefix, titleSuffix, afterDescription, actions, primaryAction, secondaryActions, moreActionsLabel, renderLink, children, className, contentClassName, eyebrowClassName, titleClassName, titleRowClassName, descriptionClassName, actionsClassName, withSeparator, }: PageHeadingProps): import("react").JSX.Element;
 export declare namespace PageHeading {
     var displayName: string;
 }

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: header, scrolling body and footer each own their inset, one
+ * rule separates adjacent visible regions, 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,7 @@ 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. */
 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/signature-pad/signature-pad.types.d.ts

@@ -54,7 +54,11 @@ export interface SignaturePadProps extends Omit<ComponentPropsWithoutRef<'div'>,
     name?: string;
     form?: string;
     required?: boolean;
-    /** Shows the keyboard-accessible typed signature alternative. @default true */
+    /**
+     * Shows the keyboard-accessible typed signature alternative. The typed name is
+     * drawn and exported in the pad's font family: the theme sans unless a font is
+     * set on the pad through `className` or `style`. @default true
+     */
     allowTypedSignature?: boolean;
     /** Ink diameter in CSS drawing pixels; pen pressure varies it. @default 2 */
     strokeWidth?: number;

package/dist/components/base/signature-pad/signature-pad.utils.d.ts

@@ -2,7 +2,15 @@ import type { SignaturePadValue } from './signature-pad.types';
 export declare const emptySignature: SignaturePadValue;
 export declare function isSignatureEmpty(value: SignaturePadValue): boolean;
 export declare function normalizeSignature(value: SignaturePadValue): SignaturePadValue;
+/**
+ * A typed name is drawn in the field's own font family: the theme sans unless the
+ * consumer sets a font on the pad. This fallback applies only outside the DOM.
+ */
+export declare const signatureFallbackFont = "sans-serif";
 /** Drawing geometry, separate from structural UI spacing and theme tokens. */
-export declare function drawSignature(context: CanvasRenderingContext2D, value: SignaturePadValue, width: number, height: number, strokeWidth: number): void;
-/** Semantic currentColor is preserved unless a resolved export ink is supplied. */
-export declare function signaturePadToSVG(value: SignaturePadValue, width?: number, height?: number, strokeWidth?: number, ink?: string): string;
+export declare function drawSignature(context: CanvasRenderingContext2D, value: SignaturePadValue, width: number, height: number, strokeWidth: number, fontFamily?: string): void;
+/**
+ * Semantic currentColor is preserved unless a resolved export ink is supplied. The
+ * typed name uses `fontFamily`, which SignaturePad resolves from its rendered font.
+ */
+export declare function signaturePadToSVG(value: SignaturePadValue, width?: number, height?: number, strokeWidth?: number, ink?: string, fontFamily?: string): string;

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/field-clear-button.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The inline clear action shared by Input, Textarea and Cascader: a native button
+ * drawing the shared clear target, focus edge and glyph. Its owner places it and
+ * supplies the accessible name, handler and disabled state.
+ */
+export declare const FieldClearButton: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;

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,33 @@
+/**
+ * Private drop-target states shared by Dropzone, AvatarUpload and ImageUpload.
+ * An empty target draws the dashed `--input` control boundary, so all three
+ * upload targets read as the same kind of control as every field. Hover, drag
+ * and invalid states replace only the boundary colour and fill.
+ *
+ * Keyboard focus on the hidden file input draws the shared focus frame on the
+ * target (each owner adds the `ring-3` width). The valid and invalid colours are
+ * alternatives, never stacked, so an invalid target keeps its destructive border
+ * and tints the halo instead of tying with the ring colour.
+ */
+export declare const uploadDropTargetRecipes: {
+    readonly idle: "border-input";
+    readonly invalid: "border-destructive";
+    readonly invalidHover: "hover:bg-destructive/5";
+    readonly invalidDragging: "border-destructive bg-destructive/5";
+    readonly dragging: "border-primary bg-primary/10";
+    /** Pointer over an enabled target previews the drop: the boundary takes the primary colour. */
+    readonly hover: "hover:border-primary hover:bg-primary/5";
+    /** A file dragged over an already selected file row: the row keeps its edge and gains the tone halo. */
+    readonly draggingRing: "ring-3 ring-primary/30";
+    readonly invalidDraggingRing: "ring-3 ring-destructive/30";
+    readonly focus: {
+        readonly input: {
+            readonly valid: "has-[input:focus-visible]:border-ring has-[input:focus-visible]:ring-ring/50";
+            readonly invalid: "has-[input:focus-visible]:ring-destructive/30 dark:has-[input:focus-visible]:ring-destructive/50";
+        };
+        readonly filePicker: {
+            readonly valid: "has-[[data-slot=file-picker-input]:focus-visible]:border-ring has-[[data-slot=file-picker-input]:focus-visible]:ring-ring/50";
+            readonly invalid: "has-[[data-slot=file-picker-input]:focus-visible]:ring-destructive/30 dark:has-[[data-slot=file-picker-input]:focus-visible]:ring-destructive/50";
+        };
+    };
+};

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

@@ -7,10 +7,10 @@
  * (chips, country prefix menu, swatch and picker, track, calendar) rather than
  * a text box.
  *
- * This family composes the other two: the phone, colour and tags controls all
- * render `Input` from `base/text-inputs`, and the phone control renders the
- * shared `SelectPopup*` parts from `base/choice-inputs`. The dependency runs
- * one way only.
+ * This family composes the other two: the phone and colour controls render
+ * `Input` from `base/text-inputs`, the tags control draws the same field frame
+ * around its chips, and the phone control renders the shared `SelectPopup*`
+ * parts from `base/choice-inputs`. The dependency runs one way only.
  *
  * Related families:
  *   - `themelia-react-ui/base/text-inputs` — free-form text entry
@@ -18,7 +18,7 @@
  *   - `themelia-react-ui/base/forms-numeric` — money, weight, dimensions
  *   - `themelia-react-ui/base/date-pickers` — calendars and time pickers
  */
-export { TagsInput, type TagsInputProps } from './tags-input';
+export { TagsInput, defaultTagsInputStrings, type TagsInputProps, type TagsInputStrings, } from './tags-input';
 export { PhoneInput, defaultPhoneInputStrings, DEFAULT_COUNTRY_PREFIXES, COUNTRY_PREFIX_MAP, type PhoneInputProps, type PhoneInputStrings, type CountryPrefixOption, type CountryPrefixInput, } from './phone-input';
 export { ColorInput, defaultColorInputStrings, type ColorInputProps, type ColorInputStrings, } from './color-input';
 export { SliderField, defaultSliderStrings, type SliderProps, type SliderStrings, type SliderImitationEvent, } from './slider';

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

@@ -8,49 +8,75 @@ 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;
+    /**
+     * Announced when a commit leaves entries it could not add (too short or
+     * long, duplicate, refused by `validate`, or over `maxTags`). Receives the
+     * rejected entries joined with commas. Defaults to `"Not added: {entries}."`.
+     */
+    notAdded?: (entries: string) => string;
+    /** Accessible name of the recommendation list. Defaults to `"Suggested tags"`. */
+    recommendationsLabel?: string;
 }
 export declare const defaultTagsInputStrings: TagsInputStrings;
 export interface TagsInputProps<T = string> {
     /** ID of the editable input, for an external field label. */
     id?: string;
+    /** Names the editable input when no visible label points at it. */
+    'aria-label'?: string;
+    /** IDs of the elements that label the editable input. */
+    'aria-labelledby'?: string;
     /** Additional supporting/error descriptions associated with the editable control. */
     'aria-describedby'?: string;
-    /** Current value (array of T) */
+    /** Marks the field invalid, like `invalid`; a FormField or form library may inject it. */
+    'aria-invalid'?: boolean | 'true' | 'false';
+    /** Marks the editable input as required for assistive tech. */
+    'aria-required'?: boolean | 'true' | 'false';
+    /** Current value (array of T). Pass it to control the field. */
     value?: T[];
+    /** Initial value when uncontrolled. Ignored when `value` is set. */
+    defaultValue?: T[];
     /** Callback when value changes */
     onValueChange?: (value: T[]) => void;
-    /** Placeholder text for the input */
+    /** Form field name. Each tag is serialised as a hidden `name[]` input (its display value), disabled with the field. */
+    name?: string;
+    /** Placeholder text for the input, shown while there are no tags. */
     placeholder?: string;
     /** Array of recommendations to suggest */
     recommendations?: Array<T | {
         value: T;
         label: string;
     }>;
-    /** Maximum number of tags allowed */
+    /** Maximum number of tags allowed. Entry is refused and announced once it is reached; the input stays focusable. */
     maxTags?: number;
-    /** Show the label for the maximum tags */
+    /** Shows the `strings.summary` count under the field. Requires `maxTags`. */
     showMaxTags?: boolean;
     /** Whether duplicate tags are allowed */
     allowDuplicates?: boolean;
-    /** Custom validation function */
+    /** Custom validation function. Runs after the length, limit and duplicate checks. */
     validate?: (value: T) => boolean;
     /** Whether the input is disabled */
     disabled?: boolean;
-    /** Whether to show the clear all button */
+    /** Shows a clear-all action under the field while there are tags. */
     showClearAll?: boolean;
-    /** Custom tag component */
+    /**
+     * Custom tag component. `index` is the tag's position in the value, and
+     * `onRemove(index)` removes it and moves focus to the neighbouring remove
+     * action (an element with `data-tag-remove`), else the input.
+     */
     renderTag?: (tag: T, index: number, onRemove: (index: number) => void) => React.ReactNode;
-    /** Delimiter for separating tags when pasting */
+    /** Splits typed and pasted text into several tags. Defaults to a comma or a newline. */
     delimiter?: string | RegExp;
     /** Whether to trigger add on blur */
     addOnBlur?: boolean;
     /** Minimum length for a tag */
     minLength?: number;
-    /** Maximum length for a tag */
+    /** Maximum length for a tag. Longer entries are refused and announced, never truncated. */
     maxLength?: number;
-    /** Override default English strings (placeholder, empty list, clear-all). */
+    /** Override default English strings (placeholder, empty list, clear-all, announcements). */
     strings?: StringsProp<TagsInputStrings>;
-    /** Whether tags should be sorted */
+    /** Keeps the value sorted by display text as tags are added. */
     sortTags?: boolean;
     /** Case sensitivity for duplicate checking */
     caseSensitive?: boolean;
@@ -61,7 +87,7 @@ export interface TagsInputProps<T = string> {
     /** Additional class names */
     className?: string;
 }
-export declare function TagsInput<T = string>({ id, 'aria-describedby': ariaDescribedBy, value, onValueChange, placeholder, recommendations, maxTags, showMaxTags, allowDuplicates, validate, disabled, showClearAll, renderTag, delimiter, addOnBlur, minLength, maxLength, sortTags, caseSensitive, field, invalid, className, strings: stringsProp, }: TagsInputProps<T>): React.JSX.Element;
+export declare function TagsInput<T = string>({ id, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-required': ariaRequired, value, defaultValue, onValueChange, name, placeholder, recommendations, maxTags, showMaxTags, allowDuplicates, validate, disabled, showClearAll, renderTag, delimiter, addOnBlur, minLength, maxLength, sortTags, caseSensitive, field, invalid, className, strings: stringsProp, }: TagsInputProps<T>): React.JSX.Element;
 export declare namespace TagsInput {
     var displayName: 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, ...props }: 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,5 @@
+import type { ComponentPropsWithoutRef } from 'react';
+import type { CardProps } from '../../../base/cards';
 import type { StringsProp } from '../../../../lib/strings';
 export type AddressKind = 'shipping' | 'billing' | 'pickup';
 export interface AddressCardStrings {
@@ -10,7 +12,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 Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'title'>, 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.