themelia-react-ui 1.0.2 → 2.0.1

package/dist/components/base/buttons/loader-button.d.ts

@@ -33,8 +33,10 @@ interface LoaderButtonContentProps {
     icon?: BaseButtonProps['icon'];
     iconPosition?: BaseButtonProps['iconPosition'];
     size?: ButtonSize;
+    /** Ends the label with an ellipsis instead of wrapping it. */
+    truncate?: boolean;
     children: React.ReactNode;
 }
-export declare function LoaderButtonContent({ isLoading, loadingText, icon: Icon, iconPosition, size: _size, children, }: LoaderButtonContentProps): React.JSX.Element;
+export declare function LoaderButtonContent({ isLoading, loadingText, icon: Icon, iconPosition, size: _size, truncate, children, }: LoaderButtonContentProps): React.JSX.Element;
 declare const LoaderButton: React.ForwardRefExoticComponent<Omit<LoaderButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 export { LoaderButton };

package/dist/components/base/buttons/text-button.d.ts

@@ -8,12 +8,12 @@ import * as React from 'react';
 import { type ComponentScale } from '../../../lib/ui-provider';
 export type TextButtonSize = ComponentScale;
 export type TextButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'size'> & {
-    /** Size preset. */
+    /** Size preset. `md` (default) matches body text; `sm` is the compact 13px role. Defaults to `UIProvider.density.defaultScale`. */
     size?: TextButtonSize;
     children: React.ReactNode;
 };
 export declare const TextButton: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "size"> & {
-    /** Size preset. */
+    /** Size preset. `md` (default) matches body text; `sm` is the compact 13px role. Defaults to `UIProvider.density.defaultScale`. */
     size?: TextButtonSize;
     children: React.ReactNode;
 } & React.RefAttributes<HTMLButtonElement>>;

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

@@ -37,7 +37,9 @@ export interface CarouselProps extends ComponentPropsWithoutRef<'div'> {
      * ```
      *
      * Use `inside` to overlay the controls on the viewport and skip the gutter
-     * entirely.
+     * entirely; they get an opaque background so slide content never shows
+     * through. `overlay` adds a shadow for media slides, and `inline` keeps
+     * the controls in document flow (see `CarouselNavigation`).
      */
     controlPlacement?: CarouselControlPlacement;
     /** Receives the carousel API so the consumer can drive it from outside. */

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, the same one every field, choice control and
+ * outline button draws.
  *
  * 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,27 @@ 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 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))]";
+/**
+ * Shared option-card states for CardRadioGroup and CardCheckboxGroup: the resting
+ * `border-border` divider (declared beside `border` by each owner) steps up to the
+ * control boundary on hover, and keyboard focus draws the shared focus frame.
+ * Selection and validation are added by each owner as data/aria variants, so they
+ * keep their border while focused.
+ */
+export declare const choiceCardStateClasses: string;
+/** 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";
+/**
+ * A control track exactly one label line tall. Pair it with the label's own text
+ * role (size and leading) and align the row to its start: a checkbox, radio,
+ * switch or selection marker then centres on the label's first line at every
+ * scale, whether or not the label wraps.
+ */
+export declare const choiceControlTrackClasses = "flex h-lh shrink-0 items-center";
+/**
+ * Shared selected-card marker, derived from action geometry. It sits in a
+ * `choiceControlTrackClasses` track beside the option label, inside a slot that
+ * keeps its width while unselected so selecting never rewraps the label.
+ */
+export declare const choiceCardMarkerClasses = "size-action-sm shrink-0 text-primary-foreground fill-primary stroke-primary-foreground";
+export declare const choiceCardMarkerSlotClasses = "inline-flex size-action-sm shrink-0 items-center justify-center";

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/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, rule and typography geometry of
+ * the internal Dialog wrapper: a pinned heading region, an optional scrolling
+ * body and pinned answers, with one rule between adjacent visible regions.
  */
 import * as React from 'react';
 import { AlertDialog as AlertDialogPrimitive, AlertDialogOverlay, AlertDialogPortal } from '../../ui/alert-dialog';
@@ -12,9 +17,11 @@ export declare const AlertDialogContent: React.ForwardRefExoticComponent<Omit<im
 } & {
     container?: import("../../../lib/theme-scope").ThemePortalContainer;
 }, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export declare const AlertDialogHeader: React.ForwardRefExoticComponent<Omit<React.ClassAttributes<HTMLDivElement> & React.HTMLAttributes<HTMLDivElement>, "ref"> & {
+export declare const AlertDialogHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
     textGap?: TextGap;
+    align?: "start" | "center";
 } & React.RefAttributes<HTMLDivElement>>;
+/** Scroll-owning region between the pinned heading and the pinned answers. */
 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
+ * header, scrolling body and footer each own their inset, with exactly one rule
+ * between adjacent visible regions (`modalRegionRecipes`).
  */
 import * as React from 'react';
 import { Dialog as DialogPrimitive, DialogOverlay, DialogPortal } from '../../ui/dialog';
@@ -21,7 +24,7 @@ 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. */
 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/icon-badge/icon-badge.d.ts

@@ -4,7 +4,7 @@
  * coupon checks, conversation initials, search-result tones, AI-bot avatars.
  *
  * Tones reuse the shadcn semantic tokens, with the foreground colour picked
- * to read against a 10–15% background tint (e.g. `bg-success/15 text-success`).
+ * to read against its tone's shared tint (`toneRecipes`, contrast-tested).
  * For a fully-saturated mark (primary fill, inverse foreground), use
  * `tone="primary"` and pass `solid`.
  *

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

@@ -59,17 +59,24 @@ export declare const formControlMinHeightClasses: {
     md: string;
     lg: string;
 };
+/**
+ * The one field frame, drawn by `Input` on its native field and by
+ * `formFieldTriggerClasses` on button-shaped triggers: the `--input` boundary,
+ * inner radius, transparent fill (the library is intentionally flat), control
+ * height, editable text size, control padding and the shared focus, invalid and
+ * disabled states. Layout (`flex`, width) stays with each owner.
+ *
+ * The displayed value is the field's value, so it follows the editable text
+ * recipe: on coarse pointers a trigger matches the touch input size of an
+ * adjoining `Input` instead of rendering a step smaller.
+ */
+export declare function formFieldFrameClasses(size: ComponentScale): string;
 /**
  * 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-inner
- * bg-transparent focus-visible:ring` chrome (no shadow — the library
- * is intentionally flat) plus the size-driven height + horizontal
- * padding.
- *
- * Kept here so the chrome lives in exactly one place — when we tweak
- * the canonical input look, every trigger picks it up.
+ * field (DatePicker, TimePicker, Cascader, the inner Select inside composite
+ * fields, etc.). It is `Input`'s own frame plus button resets, so when the
+ * canonical input look changes every trigger picks it up.
  */
 export declare function formFieldTriggerClasses(size: ComponentScale): string;
 export declare const formTextareaSizeClasses: {
@@ -77,6 +84,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/metadata-list/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * metadata-list — label/value facts about one entity.
+ *
+ * A base structure: it composes typography, primitives and base display parts,
+ * and any surface (Card, panel, drawer or block) places it. Previously
+ * published from `themelia-react-ui/blocks/data-display`, which re-exports it
+ * as a deprecated compatibility path.
+ */
+export { MetadataList, defaultMetadataListStrings } from './metadata-list';
+export type { MetadataDensity, MetadataInlineListItem, MetadataLayout, MetadataListItem, MetadataListProps, MetadataListStrings, } from './metadata-list';
+export { MetadataValue } from './metadata-value';
+export type { MetadataValueDescriptor, MetadataValueKind, MetadataValueProps, } from './metadata-value';

package/dist/components/{blocks/data-display/metadata → base/metadata-list}/metadata-list.d.ts

@@ -1,37 +1,28 @@
-/**
- * MetadataList — flexible label/value list for entity metadata.
- *
- * Three layouts:
- *  - `grid` (default): label-on-top, value-below cells for entity details.
- *  - `rows`: two-column definition rows with hairline separators.
- *  - `inline`: label/separator/value pairs that wrap, suitable for
- *    pill-style summaries (e.g. "Created Jan 4 · By Alice · v3.2").
- *
- * Each item supports an optional icon, tooltip, React-node value, custom
- * `render`, and per-item `emptyLabel`. Falls back to the shared `EMPTY` when
- * both are missing. Returns `null` when the list is empty so callers can render
- * unconditionally.
- */
-import { type LucideIcon } from 'lucide-react';
 import React from 'react';
-import { type ResponsiveValue } from '../../../base/structure';
-import { type StringsProp } from '../../../../lib/strings';
+import { type ResponsiveValue } from '../structure';
+import { type StringsProp } from '../../../lib/strings';
 import { defaultMetadataListStrings, type MetadataListStrings } from './metadata-list.strings';
 import { type MetadataValueDescriptor } from './metadata-value';
 export type { MetadataListStrings };
 export { defaultMetadataListStrings };
 export type MetadataListItem = {
-    /** Stable identity for this entry. */
+    /** Stable identity for this entry. Without one the label and index stand in. */
     id?: string;
     /** Display label. */
     label: React.ReactNode;
+    /** A node, or a descriptor that names the fact's kind. */
     value?: React.ReactNode | MetadataValueDescriptor | null;
-    /** Supporting copy shown under the label. */
+    /** Supporting copy shown under the value. */
     description?: React.ReactNode | null;
+    /** Shown from an info trigger beside the label, named after the label through `strings.formatInfoAriaLabel`. */
     tooltip?: React.ReactNode;
-    /** Leading glyph. */
-    icon?: LucideIcon;
+    /** Leading glyph. Any component that accepts `className`, including Lucide icons. */
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    /** Shown when this item's value is absent, in place of the list's `emptyLabel`. */
     emptyLabel?: React.ReactNode;
+    /** Takes over the value. The output sits in the value box, so it inherits the value's type role. */
     render?: (item: MetadataListItem) => React.ReactNode;
 };
 export type MetadataInlineListItem = Omit<MetadataListItem, 'description'> & {
@@ -54,7 +45,11 @@ type MetadataListSharedProps = {
     className?: string;
     /** Character placed between a label and its value. Defaults to a colon. */
     separator?: string;
-    /** Divider between items — `true` for the default rule, or a character for inline layouts. */
+    /**
+     * Divider between items, off by default. In `rows`, any truthy value draws a
+     * rule between rows (never at the ends). In `inline`, `true` places a middle
+     * dot (`·`) and a string places that character.
+     */
     itemSeparator?: boolean | string;
     /** Per-instance string overrides (deep-merged over `defaultMetadataListStrings`). */
     strings?: StringsProp<MetadataListStrings>;
@@ -64,15 +59,23 @@ type MetadataGridRowsProps = MetadataListSharedProps & {
     items: MetadataListItem[];
     /** `grid` flows items into `columns`; `rows` stacks them one per line. Default: `grid`. */
     layout?: 'grid' | 'rows';
+    /**
+     * Rows layout only. `start` (default) places values and descriptions at the
+     * start of proportional label/value tracks; `end` pins them to the row's end
+     * edge, for figures that read down a column.
+     */
+    valueAlign?: 'start' | 'end';
 };
 type MetadataInlineProps = MetadataListSharedProps & {
-    /** Values to render, without labels. */
+    /** Label/value pairs run together on wrapping lines. Inline items take no description. */
     items: MetadataInlineListItem[];
-    /** Runs the values together on one line, separated by `itemSeparator`. */
+    /** Runs the label/value pairs together on one line, separated by `itemSeparator`. */
     layout: 'inline';
+    /** Not used by the inline layout. */
+    valueAlign?: never;
 };
 export type MetadataListProps = MetadataGridRowsProps | MetadataInlineProps;
-export declare function MetadataList({ items, columns, density, emptyLabel, title, titleSeparator, className, layout, separator, itemSeparator, strings: stringsProp, }: MetadataListProps): React.JSX.Element | null;
+export declare function MetadataList({ items, columns, density, emptyLabel, title, titleSeparator, className, layout, separator, itemSeparator, valueAlign, strings: stringsProp, }: MetadataListProps): React.JSX.Element | null;
 export declare namespace MetadataList {
     var displayName: string;
 }

package/dist/components/{blocks/data-display/metadata → base/metadata-list}/metadata-value.d.ts

@@ -6,8 +6,8 @@
  */
 import type { ReactNode } from 'react';
 import type { Locale } from 'date-fns';
-import { type BadgeProps } from '../../../base/badge';
-import { type DateInput, type DatePreset, type MoneyProps, type TimeProps } from '../../../primitives';
+import { type BadgeProps } from '../badge';
+import { type DateInput, type DatePreset, type MoneyProps, type TimeProps } from '../../primitives';
 export type MetadataValueKind = 'text' | 'mono' | 'email' | 'phone' | 'url' | 'link' | 'date' | 'time' | 'datetime' | 'money' | 'badge' | 'node' | 'empty';
 type MetadataDisplayValue = Exclude<ReactNode, null | undefined>;
 type MetadataDateInput = Exclude<DateInput, null | undefined>;