themelia-ui 2.0.0 → 3.0.0

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

@@ -1,9 +1,20 @@
 import { Menu as MenuPrimitive } from '@base-ui/react/menu';
 import { UIPortalContainer } from '../../../lib/ui-provider/index.js';
 import * as React from "react";
+/** A menu that opens from a trigger. It holds the open state the parts share. */
 declare function DropdownMenu({ ...props }: MenuPrimitive.Root.Props): React.JSX.Element;
+/**
+ * Escapes the menu from an ancestor that clips or transforms — a card with overflow hidden,
+ * a scrolling pane. `DropdownMenuContent` portals already; this is for a caller placing the
+ * surface itself.
+ */
 declare function DropdownMenuPortal({ ...props }: MenuPrimitive.Portal.Props): React.JSX.Element;
-declare function DropdownMenuTrigger({ ...props }: MenuPrimitive.Trigger.Props): React.JSX.Element;
+/** The control the menu hangs off. */
+declare function DropdownMenuTrigger({ ...props }: MenuPrimitive.Trigger.Props & Pick<MenuPrimitive.Trigger.Props, "render">): React.JSX.Element;
+/**
+ * The menu's surface. It sizes to its widest row by default, capped at a reading measure;
+ * `width`, `minWidth` and `maxWidth` change that.
+ */
 declare function DropdownMenuContent({ container, align, alignOffset, side, sideOffset, width, minWidth, maxWidth, className, style, ...props }: MenuPrimitive.Popup.Props & Pick<MenuPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset"> & {
     /**
      * Fixed surface width: any CSS length, or `"trigger"` to match the trigger (Select-like).
@@ -12,7 +23,11 @@ declare function DropdownMenuContent({ container, align, alignOffset, side, side
     width?: string | number | "trigger";
     /** Floor for the content-sized default. */
     minWidth?: string | number;
-    /** Ceiling for the content-sized default: a reading measure, so one long label doesn't widen every row. */
+    /**
+     * Ceiling for the content-sized default: a reading measure, so one long label doesn't
+     * widen every row. Unset, the surface also stops at the space available.
+     * @default "20rem"
+     */
     maxWidth?: string | number;
     /**
      * Where the popup renders. Defaults to the nearest `UIPortalHost`, else the primitive's
@@ -20,7 +35,13 @@ declare function DropdownMenuContent({ container, align, alignOffset, side, side
      */
     container?: UIPortalContainer;
 }): React.JSX.Element;
+/** A titled run of items. */
 declare function DropdownMenuGroup({ ...props }: MenuPrimitive.Group.Props): React.JSX.Element;
+/**
+ * A group caption. It must sit inside a `DropdownMenuGroup` — it throws otherwise. The label
+ * is not an item: it is not focusable and arrow keys skip it, which is why a styled item
+ * would be wrong here.
+ */
 declare function DropdownMenuLabel({ className, inset, ...props }: MenuPrimitive.GroupLabel.Props & {
     inset?: boolean;
 }): React.JSX.Element;
@@ -37,22 +58,47 @@ interface MenuRowSlots {
     shortcut?: React.ReactNode;
     /** Trailing content beside the shortcut, for anything that is not a shortcut. */
     trailing?: React.ReactNode;
+    /** Indents a row with no icon, so its label lines up with rows that have one. */
     inset?: boolean;
 }
+/**
+ * A menu row. Its icon, description, shortcut and trailing content are props rather than
+ * children, so every row lays out the same and only the label gives way.
+ */
 declare function DropdownMenuItem({ className, inset, variant, icon, description, shortcut, trailing, children, ...props }: MenuPrimitive.Item.Props & MenuRowSlots & {
+    /** `destructive` marks a row that deletes or discards. */
     variant?: "default" | "destructive";
 }): React.JSX.Element;
+/**
+ * An item that navigates. A real anchor, so middle-click and copy-link work and a screen
+ * reader announces a link rather than a button.
+ */
 declare function DropdownMenuLinkItem({ className, inset, variant, icon, description, shortcut, trailing, children, ...props }: MenuPrimitive.LinkItem.Props & MenuRowSlots & {
+    /** `destructive` marks a row that deletes or discards. */
     variant?: "default" | "destructive";
 }): React.JSX.Element;
+/**
+ * A nested menu: `DropdownMenuSubTrigger`, then `DropdownMenuSubContent`. It holds the open
+ * state both belong to.
+ */
 declare function DropdownMenuSub({ ...props }: MenuPrimitive.SubmenuRoot.Props): React.JSX.Element;
+/** The row that opens a nested menu. It belongs to a `DropdownMenuSub`, which holds the open state. */
 declare function DropdownMenuSubTrigger({ className, inset, children, ...props }: MenuPrimitive.SubmenuTrigger.Props & {
     inset?: boolean;
 }): React.JSX.Element;
+/** The panel a nested menu opens. It belongs to a `DropdownMenuSub`, which holds the open state. */
 declare function DropdownMenuSubContent({ align, alignOffset, side, sideOffset, className, ...props }: React.ComponentProps<typeof DropdownMenuContent>): React.JSX.Element;
-declare function DropdownMenuCheckboxItem({ className, children, checked, inset, icon, description, ...props }: MenuPrimitive.CheckboxItem.Props & Pick<MenuRowSlots, "icon" | "description" | "inset">): React.JSX.Element;
-declare function DropdownMenuRadioGroup({ ...props }: MenuPrimitive.RadioGroup.Props): React.JSX.Element;
+/** A row that toggles rather than closing. */
+declare function DropdownMenuCheckboxItem({ className, children, checked, inset, icon, description, ...props }: MenuPrimitive.CheckboxItem.Props & Pick<MenuPrimitive.CheckboxItem.Props, "checked" | "onCheckedChange"> & Pick<MenuRowSlots, "icon" | "description" | "inset">): React.JSX.Element;
+/** One choice from the menu: a set of `DropdownMenuRadioItem`s. */
+declare function DropdownMenuRadioGroup({ ...props }: MenuPrimitive.RadioGroup.Props & Pick<MenuPrimitive.RadioGroup.Props, "value" | "onValueChange">): React.JSX.Element;
+/** A single-choice item inside a `DropdownMenuRadioGroup`, carrying its own indicator. */
 declare function DropdownMenuRadioItem({ className, children, inset, icon, description, ...props }: MenuPrimitive.RadioItem.Props & Pick<MenuRowSlots, "icon" | "description" | "inset">): React.JSX.Element;
+/** The rule between runs of items. */
 declare function DropdownMenuSeparator({ className, ...props }: MenuPrimitive.Separator.Props): React.JSX.Element;
+/**
+ * The key hint on the trailing edge of an item. Presentational: it announces nothing,
+ * because the shortcut is already on the item that owns it.
+ */
 declare function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
 export { DropdownMenu, DropdownMenuPortal, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuItem, DropdownMenuLinkItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, };

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

@@ -4,6 +4,8 @@ export interface AlertMetadataItem {
     value: ReactNode;
 }
 export interface AlertMetadataProps extends Omit<ComponentProps<"dl">, "children"> {
+    /** Key/value detail under the message — a request id, a timestamp, a failing field. */
     items: AlertMetadataItem[];
 }
+/** Key/value pairs under an alert's message, as a `<dl>` so each pair is read together. */
 export declare function AlertMetadata({ items, className, ...props }: AlertMetadataProps): import("react").JSX.Element | null;

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

@@ -9,14 +9,28 @@ declare const alertVariants: (props?: ({
 export type AlertTone = "neutral" | "primary" | "secondary" | "destructive" | "warning" | "success" | "info";
 export type AlertVariant = "default" | "inverse";
 export interface AlertProps extends React.ComponentProps<"div">, VariantProps<typeof alertVariants> {
+    /** Semantic colour intent. Never `default` — the vocabulary is fixed across the kit. */
+    tone?: AlertTone;
     /**
-     * Leading glyph. Defaults to the tone's own; pass a node to replace it, or `false`
-     * for an alert that must have none.
+     * Structural presentation. `inverse` is a solid slab for a single emphatic notice; the
+     * tone still describes the intent.
+     */
+    variant?: AlertVariant;
+    /**
+     * Leading glyph. Defaults to the tone's own conventional glyph; pass a node to replace
+     * it, or `false` for an alert that must have none.
      */
     icon?: React.ReactNode | false;
 }
+/**
+ * A notice in a tone. Status tones bring their own glyph, so colour is not the only signal.
+ * A destructive alert interrupts the screen reader; every other tone is a polite status.
+ */
 declare function Alert({ className, tone, variant, icon, children, ...props }: AlertProps): React.JSX.Element;
+/** The alert's heading. It inherits the alert's ink. */
 declare function AlertTitle({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+/** The message, in the secondary text role. */
 declare function AlertDescription({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+/** A single control, positioned in reserved inline space so it never overlaps the text. */
 declare function AlertAction({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 export { Alert, AlertTitle, AlertDescription, AlertAction };

package/dist/components/base/feedback/empty-illustrations.d.ts

@@ -1,13 +1,32 @@
 export interface EmptyIllustrationProps {
     className?: string;
 }
-/** Three stacked cards fading out — the generic "no records". */
+/**
+ * Three stacked cards fading out — the generic "no records". Drawn from the theme's own
+ * tokens rather than shipped as an image, so it follows a rebrand and costs no request.
+ */
 export declare function StackedCardsIllustration({ className }: EmptyIllustrationProps): import("react").JSX.Element;
-/** Two staggered documents — for invoices, reports, files. */
+/**
+ * Two staggered documents — for invoices, reports, files. Drawn from the theme's own tokens
+ * rather than shipped as an image, so an empty state cannot be the one thing on the page
+ * that ignores a rebrand — and it costs no request.
+ */
 export declare function DocumentStackIllustration({ className }: EmptyIllustrationProps): import("react").JSX.Element;
-/** An open tray under a check — for "all caught up", not for "nothing exists". */
+/**
+ * An open tray under a check — for "all caught up", not for "nothing exists". Drawn from the
+ * theme's own tokens rather than shipped as an image, so it follows a rebrand and costs no
+ * request.
+ */
 export declare function InboxCleanIllustration({ className }: EmptyIllustrationProps): import("react").JSX.Element;
-/** A magnifier on a soft disc — for "nothing matches", not "nothing exists". */
+/**
+ * A magnifier on a soft disc — for "nothing matches", not "nothing exists". Drawn from the
+ * theme's own tokens rather than shipped as an image, so it follows a rebrand and costs no
+ * request.
+ */
 export declare function SearchGlassIllustration({ className }: EmptyIllustrationProps): import("react").JSX.Element;
-/** Three overlapping discs — for people: members, customers, contributors. */
+/**
+ * Three overlapping discs — for people: members, customers, contributors. Drawn from the
+ * theme's own tokens rather than shipped as an image, so it follows a rebrand and costs no
+ * request.
+ */
 export declare function UsersCircleIllustration({ className }: EmptyIllustrationProps): import("react").JSX.Element;

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

@@ -24,24 +24,51 @@ export interface EmptyMediaContext {
     mediaVariant: EmptyMediaVariant;
 }
 export interface EmptyProps extends Omit<React.ComponentProps<"div">, "title"> {
-    /** Icon or illustration. */
+    /** Icon or illustration: the visual. */
     media?: React.ReactNode;
+    /**
+     * The media's chrome. `none` renders the media raw; `icon` and `icon-soft` set a glyph in
+     * a tile; `illustration` centres it with room below.
+     */
     mediaVariant?: EmptyMediaVariant;
     /** Media as a function of the variant, for a visual that changes with its chrome. */
     renderMedia?: (context: EmptyMediaContext) => React.ReactNode;
+    /**
+     * Names the absence: "No invoices yet", not "Nothing here". Falls back to `strings.title`,
+     * so a bare `<Empty />` still renders during scaffolding.
+     */
     title?: React.ReactNode;
-    /** `false` hides it, for a title that already tells the whole story. */
+    /**
+     * Why it is empty, or what will fill it. `false` hides it, for a title that already tells
+     * the whole story.
+     */
     description?: React.ReactNode | false;
-    /** Buttons or links offering the next step. */
+    /**
+     * Buttons or links offering the next step. An empty state that only explains is a dead
+     * end.
+     */
     action?: React.ReactNode;
     /** Quiet copy under the action — a hint, a learn-more, a shortcut. */
     footer?: React.ReactNode;
+    /**
+     * Breathing room, on both axes: `sm` for panels and cells, `lg` for a whole page. The
+     * inline padding is what keeps copy off a dashed edge.
+     */
     padding?: EmptyPadding;
     /**
      * The dashed outline. Off by default; use it when the empty state stands in for a card's
      * body and the edge says "something goes here".
      */
     border?: boolean;
+    /**
+     * Overrides this state's own copy: `title`, `description`, and `ariaLabel`. The region
+     * announces through `role="status"`, so a list that empties out while the reader is on the
+     * page says so.
+     */
     strings?: Partial<EmptyStrings>;
 }
+/**
+ * What a surface shows when it has nothing to show, with an `action` slot for the next step.
+ * `mediaVariant` dresses the media, and `padding` sizes it from a panel cell to a whole page.
+ */
 export declare function Empty({ media, mediaVariant, renderMedia, title, description, action, footer, padding, border, className, children, strings, "aria-label": ariaLabel, ...props }: EmptyProps): React.JSX.Element;

package/dist/components/base/feedback/progress-circle.d.ts

@@ -6,14 +6,29 @@ import { ProgressTone } from './progress.js';
  */
 import * as React from "react";
 export interface ProgressCircleProps extends React.ComponentProps<"div"> {
-    /** 0–`max`. Non-finite values resolve to 0; overflow fills rather than wrapping. */
+    /**
+     * 0–`max`. Non-finite values resolve to 0; overflow fills rather than wrapping. There is
+     * no indeterminate ring: a travelling band reads as unknown, a spinning circle reads as a
+     * spinner.
+     */
     value: number;
     /** A finite positive upper bound; invalid values resolve to 100. */
     max?: number;
+    /**
+     * Semantic colour intent, as on `Progress`.
+     * @default "primary"
+     */
     tone?: ProgressTone;
     /** Accessible name. Required when no visible label describes the ring. */
     label?: string;
-    /** What sits in the hole — a percentage, a count, a verdict glyph. */
+    /**
+     * What sits in the hole — a percentage, a count, a verdict glyph. The reason to draw a
+     * ring at all.
+     */
     children?: React.ReactNode;
 }
+/**
+ * A determinate ring with the reading inside it, for tiles, scores and grids of small
+ * measures. Its size comes from `--progress-circle`; there is no size prop.
+ */
 export declare function ProgressCircle({ value, max, tone, label, children, className, style, ...props }: ProgressCircleProps): React.JSX.Element;

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

@@ -9,8 +9,17 @@ export interface ProgressProps extends Omit<React.ComponentProps<"div">, "childr
     value?: number;
     /** A finite positive upper bound; invalid values resolve to 100. */
     max?: number;
+    /**
+     * Semantic colour intent. Left unset the bar takes the primary tone — a progress bar that
+     * changes colour at a threshold is the caller's decision, not the component's.
+     * @default "primary"
+     */
     tone?: ProgressTone;
     /** Accessible name. Required when no visible label describes the bar. */
     label?: string;
 }
+/**
+ * A `progressbar` with its real bounds. Omit `value` for indeterminate; the ARIA value
+ * attributes are then dropped rather than reporting 0%.
+ */
 export declare function Progress({ value, max, tone, label, className, ...props }: ProgressProps): React.JSX.Element;

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

@@ -2,18 +2,28 @@ import { ComponentProps, ReactNode } from 'react';
 import { StringsProp } from '../../../lib/strings.js';
 import { ErrorStateStrings, LoadingStateStrings } from './states.strings.js';
 export interface LoadingStateProps extends ComponentProps<"div"> {
-    /** Replaces the default copy. */
+    /** Copy for the wait, replacing the default. */
     label?: ReactNode;
+    /** Overrides the default copy. */
     strings?: StringsProp<LoadingStateStrings>;
 }
+/**
+ * A whole region that is working. A region, not an overlay — it occupies what the content
+ * will occupy. Distinct from `Empty` and `ErrorState`: the three are different answers and
+ * must look different.
+ */
 export declare function LoadingState({ label, strings, className, ...props }: LoadingStateProps): import("react").JSX.Element;
 export interface ErrorStateProps extends Omit<ComponentProps<"div">, "title"> {
     title?: ReactNode;
     description?: ReactNode;
-    /** Renders the retry control when set. */
+    /**
+     * Renders the retry control when set. With neither this nor `action`, the state reports
+     * the failure without offering a dead button.
+     */
     onRetry?: () => void;
     /** Replaces the retry control entirely. */
     action?: ReactNode;
     strings?: StringsProp<ErrorStateStrings>;
 }
+/** A whole region that has failed, announced at once. */
 export declare function ErrorState({ title, description, onRetry, action, strings, className, ...props }: ErrorStateProps): import("react").JSX.Element;

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

@@ -4,7 +4,14 @@
  */
 import * as React from "react";
 export interface FieldGroupProps extends React.ComponentProps<"fieldset"> {
+    /** The group's one label, announced when focus enters the group. */
     legend?: React.ReactNode;
+    /** The group's one supporting line. */
     description?: React.ReactNode;
 }
+/**
+ * Several fields sharing one label and one supporting line — a date range, a name split in
+ * two. A real `<fieldset>` and `<legend>`, so the legend is announced when focus enters the
+ * group.
+ */
 export declare function FieldGroup({ legend, description, className, children, ...props }: FieldGroupProps): React.JSX.Element;

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

@@ -6,15 +6,24 @@
  */
 import * as React from "react";
 export interface FieldChromeProps {
-    /** Caption above the control, associated through `htmlFor`. */
+    /**
+     * Caption above the control, wired to it by a generated id unless the control has one of
+     * its own, or `htmlFor` names one.
+     */
     label?: React.ReactNode;
-    /** Marks the field required and renders the indicator beside the label. */
+    /**
+     * Marks the label and the control: the indicator beside the label, and `aria-required`
+     * on the control.
+     */
     required?: boolean;
     /** Lowest priority: shown only when neither `error` nor `helperText` is set. */
     hint?: React.ReactNode;
     /** Middle priority: replaces `hint`, and is itself replaced by `error`. */
     helperText?: React.ReactNode;
-    /** Highest priority. Announced politely and switches the control to its invalid state. */
+    /**
+     * Highest priority of the three supporting lines. Announced politely and switches the
+     * control to its invalid state.
+     */
     error?: React.ReactNode;
 }
 /** Wiring a custom or wrapped control receives from `FormField`. */
@@ -27,13 +36,18 @@ export interface FormFieldControlProps {
 }
 export type FormFieldControl = React.ReactNode | ((controlProps: FormFieldControlProps) => React.ReactNode);
 export interface FormFieldProps extends FieldChromeProps, Omit<React.ComponentProps<"div">, "children"> {
-    /** A direct control, or an explicit adapter for a wrapped/custom control. */
+    /**
+     * A direct control, or an explicit adapter for a wrapped/custom control. Use the function
+     * form when a consumer wrapper hides the actual control, and spread the supplied id and
+     * aria props onto it.
+     */
     children: FormFieldControl;
     /** Label beside the control instead of above it — for settings rows. */
     orientation?: "vertical" | "horizontal";
     /**
      * The id the caption addresses, or `false` when there is no single labelable element.
-     * A string is for a control that can't take the generated id. `false` is for a cluster
+     * A string associates the label with a control that already has an id, instead of the
+     * generated one, or one that can't take it. `false` is for a cluster
      * (repeater, checkbox group, segments): the field becomes a named `group` instead. Opt-in,
      * because a group sharing its control's name makes `getByLabelText` ambiguous.
      */

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

@@ -5,32 +5,46 @@ import { AlertTone } from '../feedback/index.js';
 import { StringsProp } from '../../../lib/strings.js';
 import { DirtyStateBannerStrings, ErrorSummaryStrings, SubmitStateButtonStrings } from './workflow.strings.js';
 export interface FormSectionProps {
+    /** The header line. */
     title?: ReactNode;
+    /** The copy under the title. */
     description?: ReactNode;
-    /** Controls in the section header. */
+    /** Controls on the title's own line. */
     actions?: ReactNode;
     children?: ReactNode;
+    /** A footer below the fields. */
     footer?: ReactNode;
-    /** Outer chrome. Use `flat` when the section already sits inside a card. */
+    /**
+     * Outer chrome. Use `flat` when the section already sits inside a card, which is most of
+     * them.
+     */
     surface?: CardSurface;
     className?: string;
 }
+/** A titled group of fields, on a card's surface. */
 export declare function FormSection({ title, description, actions, children, footer, surface, className, }: FormSectionProps): import("react").JSX.Element;
 export interface FormActionsBarProps {
     /** The actions. `trailing` wins when both are given. */
     children?: ReactNode;
     /** Status or context before the actions — "Last saved 2 minutes ago". */
     leading?: ReactNode;
+    /** The actions, in place of `children`. It wins when both are given. */
     trailing?: ReactNode;
-    /** Pins the bar to the bottom of its nearest scrolling ancestor. */
+    /**
+     * Pins the bar to the foot of its nearest scrolling ancestor, for a form longer than the
+     * viewport.
+     */
     sticky?: boolean;
     className?: string;
 }
+/** A form's actions in one row, with room for status before them. */
 export declare function FormActionsBar({ children, leading, trailing, sticky, className }: FormActionsBarProps): import("react").JSX.Element;
 export interface ErrorSummaryProps {
-    /** Overrides the counted heading. */
+    /** Replaces the heading, which otherwise counts the list. */
     title?: ReactNode;
+    /** Copy under the heading. */
     description?: ReactNode;
+    /** The problems, one per item. An item may link to its field. */
     errors?: readonly ReactNode[];
     /** A control beside the summary — "Review the first problem". */
     action?: ReactNode;
@@ -53,13 +67,22 @@ export interface DirtyStateBannerProps {
     description?: ReactNode;
     /** Save and discard, usually. */
     actions?: ReactNode;
+    /**
+     * Deliberately narrower than `AlertTone`: unsaved work is neither an error nor a
+     * success.
+     */
     tone?: Extract<AlertTone, "neutral" | "info" | "warning">;
     strings?: StringsProp<DirtyStateBannerStrings>;
     className?: string;
 }
+/** Tells the reader there are unsaved changes, with the actions that resolve them. */
 export declare function DirtyStateBanner({ title, description, actions, tone, strings, className, }: DirtyStateBannerProps): import("react").JSX.Element;
 export type SubmitState = "idle" | "submitting" | "succeeded";
 export interface SubmitStateButtonProps extends Omit<ButtonProps, "loading" | "children"> {
+    /**
+     * Drives the label and the disabled state. The label is the message, so a spinner never
+     * replaces the answer.
+     */
     state?: SubmitState;
     strings?: StringsProp<SubmitStateButtonStrings>;
 }

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

@@ -7,15 +7,32 @@ export interface CurrencyOption {
 export interface CurrencyInputProps extends Omit<DecimalInputProps, "prefix"> {
     /** Controlled currency code, e.g. "EUR". */
     currency?: string;
+    /** The starting currency code, for an uncontrolled field. */
     defaultCurrency?: string;
+    /** Called with the new currency code: a separate channel from the amount. */
     onCurrencyChange?: (currency: string) => void;
-    /** Codes are looked up in CURRENCY_SYMBOLS; anything else takes a full option. */
+    /**
+     * Which codes the picker offers. Codes are looked up in `CURRENCY_SYMBOLS`; anything else
+     * takes a full option.
+     */
     currencies?: (string | CurrencyOption)[];
     /** Which side the selector sits on. */
     currencyPosition?: "start" | "end";
+    /** Drops the currency selector, for an amount whose currency is decided elsewhere in the form. */
     disableCurrencySelector?: boolean;
-    /** Overrides this field's own copy — the currency selector's name. */
+    /**
+     * Overrides this field's own copy. It extends the decimal strings, which extend the input
+     * strings — a currency field is one of each, so it owns the selector's name, the two
+     * steppers, and the clear action alike.
+     */
     strings?: Partial<CurrencyInputStrings>;
+    /** The error surface. The message stays on the `FormField`. */
     invalid?: boolean;
 }
+/**
+ * An amount and its currency in separate channels: "€1,234.50" in one string would need a
+ * locale-dependent parse downstream. The amount is `value`, a string — read
+ * `event.target.value` in `onChange`; the currency code travels through `currency` and
+ * `onCurrencyChange`.
+ */
 export declare const CurrencyInput: import('react').ForwardRefExoticComponent<Omit<CurrencyInputProps, "ref"> & import('react').RefAttributes<HTMLInputElement>>;

package/dist/components/base/forms-numeric/currency-symbols.d.ts

@@ -1,2 +1,6 @@
-/** A starting set. Anything not here is passed as a full option. */
+/**
+ * The code-to-symbol map the currency options are labelled from, exported so a caller can
+ * render the same symbol elsewhere. A starting set: anything not here is passed as a full
+ * option.
+ */
 export declare const CURRENCY_SYMBOLS: Record<string, string>;

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

@@ -2,24 +2,30 @@ import { InputProps } from '../text-inputs/index.js';
 import { DecimalInputStrings } from './forms-numeric.strings.js';
 import { RoundingMode } from './decimal.format.js';
 import * as React from "react";
-export interface DecimalInputProps extends Omit<InputProps, "type" | "inputMode"> {
-    /** Maximum fractional digits accepted, and used when normalising. */
+export interface DecimalInputProps extends Omit<InputProps, "type" | "inputMode">, Pick<React.ComponentProps<"input">, "value" | "onChange"> {
+    /** How many digits after the separator are accepted, and used when normalising. */
     decimalPlaces?: number;
+    /** The lower bound. */
     min?: number;
+    /** The upper bound. */
     max?: number;
+    /** Accepts a minus sign. */
     allowNegative?: boolean;
-    /** Lets the field be left blank. */
+    /** Lets the field be left blank: a blank is a valid value. */
     allowEmpty?: boolean;
-    /** Renders − / + buttons that snap the value to multiples of this. */
+    /** The increment: renders − / + buttons that snap the value to multiples of this. */
     step?: number;
     /**
      * How halves are resolved when stepping or normalising. `half-even` (bankers' rounding)
      * avoids accumulating bias across many money rows.
      */
     roundingMode?: RoundingMode;
-    /** Pads to the full decimal places and clamps to the range on blur. */
+    /**
+     * Rounds, pads to the full decimal places and clamps to the range when focus leaves.
+     * Doing it per keystroke would fight the reader mid-number.
+     */
     normalizeOnBlur?: boolean;
-    /** Overrides this field's own copy — the two icon-only steppers. */
+    /** Overrides this field's own copy — the two icon-only steppers, plus everything `Input` contributes. */
     strings?: Partial<DecimalInputStrings>;
     /**
      * A unit rendered after the field, inside the stepper group — wrapping a stepped field in
@@ -27,4 +33,9 @@ export interface DecimalInputProps extends Omit<InputProps, "type" | "inputMode"
      */
     endAdornment?: React.ReactNode;
 }
+/**
+ * The numeric field this family builds on: a text input, not `type="number"`, whose spinner
+ * is unstyleable, whose wheel changes values, and whose invalid input reads back as "". The
+ * `value` is always a plain string, never a number: read `event.target.value` in `onChange`.
+ */
 export declare const DecimalInput: React.ForwardRefExoticComponent<Omit<DecimalInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/components/base/forms-numeric/decimal.format.d.ts

@@ -1,5 +1,8 @@
 export type RoundingMode = "round" | "floor" | "ceil" | "half-even";
-/** Accepts a comma as the decimal separator — most of the world types one. */
+/**
+ * The formatting `DecimalInput` applies as the reader types, exported so a caller can match
+ * it. Accepts a comma as the decimal separator — most of the world types one.
+ */
 export declare function formatDecimal(value: string, decimalPlaces: number, allowNegative: boolean): string;
 /**
  * Reads a pasted, externally formatted number into the "1234.56" form `formatDecimal`
@@ -10,4 +13,8 @@ export declare function formatDecimal(value: string, decimalPlaces: number, allo
  * negative; scientific notation is expanded.
  */
 export declare function normalizePastedNumber(text: string, decimalPlaces: number): string;
+/**
+ * The rounding `DecimalInput` applies, exported so a caller can match it: `value` to
+ * `decimals` places under a `RoundingMode`.
+ */
 export declare function applyRounding(value: number, decimals: number, mode: RoundingMode): number;

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

@@ -9,4 +9,9 @@ export interface MoneyInputProps extends Omit<CurrencyInputProps, "value" | "def
     value?: MoneyValue;
     onValueChange?: (value: MoneyValue) => void;
 }
+/**
+ * The same field as `CurrencyInput`, taking a single `{ amount, currency }` object, for a form
+ * that stores it that way: it cannot submit one without the other. The amount stays a
+ * string — floats lose cents, and parsing is the caller's decision.
+ */
 export declare const MoneyInput: import('react').ForwardRefExoticComponent<Omit<MoneyInputProps, "ref"> & import('react').RefAttributes<HTMLInputElement>>;

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

@@ -7,4 +7,10 @@ export type PercentageInputProps = Omit<DecimalInputProps, "allowNegative"> & {
     /** Lets the value go below zero — a change in percent, rather than a proportion. */
     allowNegative?: boolean;
 };
+/**
+ * `DecimalInput` bounded to a percentage, with a trailing `%`. The value is the number only,
+ * as a string — the `%` is chrome, not data: read `event.target.value` in `onChange`. With a
+ * `step`, the sign moves inside the stepper group: a stepper field is already a shell, and a
+ * second one around it would double the border.
+ */
 export declare const PercentageInput: import('react').ForwardRefExoticComponent<Omit<PercentageInputProps, "ref"> & import('react').RefAttributes<HTMLInputElement>>;

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

@@ -9,4 +9,8 @@ export interface RoundingModeSelectProps extends Omit<SelectProps, "options" | "
     /** Replaces the mode labels. */
     strings?: Partial<RoundingModeStrings>;
 }
+/**
+ * The rounding policies as a control, offering exactly the modes `DecimalInput` accepts —
+ * `round`, `floor`, `ceil`, and `half-even` when asked for. `strings` replaces the labels.
+ */
 export declare const RoundingModeSelect: import('react').ForwardRefExoticComponent<RoundingModeSelectProps & import('react').RefAttributes<HTMLButtonElement>>;