themelia-react-ui 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,27 @@
+/**
+ * Status a region reports about itself.
+ *
+ * `Alert` is the inline notice — a message shown *beside* content that is
+ * otherwise fine. `LoadingState` and `ErrorState` are the whole-region
+ * counterparts: they replace the content while it is pending or after it
+ * failed, and `ErrorState` carries the retry seam. `Progress` reports how far
+ * a known-length task has come, and `Empty` supplies the low-level parts —
+ * media, header, title, description, content — for hand-built empty states.
+ *
+ * The standard empty-state recipe lives in
+ * `themelia-react-ui/blocks/data-display` as `EmptyState`, which composes
+ * the `Empty` parts below; reach for `Empty` directly only when the call site
+ * needs anatomy that recipe does not offer. (The showcase route is
+ * `blocks/empty-state` — that is a preview alias, not a package subpath.)
+ *
+ * Choosing between the two families is about *which* state, not which layer:
+ * `EmptyState` is a centered column for a collection that genuinely has no
+ * rows, while `LoadingState` / `ErrorState` share a left-aligned grid so a
+ * region can move between pending and failed without the layout jumping. They
+ * are deliberately not interchangeable; do not use `LoadingState` to render an
+ * empty state.
+ */
+export * from './alert';
+export * from './empty';
+export * from './progress';
+export * from './state-display';

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

@@ -0,0 +1,81 @@
+/**
+ * Progress — token-driven Base UI progress wrapper for completion, quota,
+ * and long-running task states.
+ *
+ * The root keeps the Base UI accessibility contract while adding a concise
+ * admin summary API (`label`, `description`, `metadata`, `showValue`),
+ * semantic tones, structural sizes, stable DOM hooks, and composition slots.
+ * Consumers can still assemble `ProgressLabel`, `ProgressValue`,
+ * `ProgressTrack`, and `ProgressIndicator` directly.
+ */
+import { Progress as ProgressPrimitive } from '@base-ui/react/progress';
+import { type ReactNode } from 'react';
+import { type ComponentScale } from '../../../lib/ui-provider';
+import { type StringsProp } from '../../../lib/strings';
+import type { SemanticTone } from '../../../lib/component-vocabulary';
+import { defaultProgressStrings, type ProgressStrings } from './progress.strings';
+export type ProgressSize = ComponentScale;
+export type ProgressTone = SemanticTone;
+export interface ProgressProps extends Omit<ProgressPrimitive.Root.Props, 'children' | 'format' | 'getAriaValueText' | 'locale' | 'max' | 'min' | 'value'> {
+    /** Current value. `null` renders an indeterminate state. */
+    value: number | null;
+    /** Minimum value used to normalize the visual percentage. @default 0 */
+    min?: number;
+    /** Maximum value used to normalize the visual percentage. @default 100 */
+    max?: number;
+    /** Intl options for formatting the raw value instead of the default normalized percentage. */
+    format?: Intl.NumberFormatOptions;
+    /** Locale forwarded to `Intl.NumberFormat`. */
+    locale?: Intl.LocalesArgument;
+    /** Human-readable text for the current value. Receives the wrapper's normalized display value. */
+    getAriaValueText?: (formattedValue: string | null, value: number | null) => string;
+    /** Low-level compound content. `headerSlot` takes precedence when both are supplied. */
+    children?: ReactNode;
+    /** Accessible visual label. Supplying it also enables `showValue` by default. */
+    label?: ReactNode;
+    /** Supporting text automatically connected with `aria-describedby`. */
+    description?: ReactNode;
+    /** Optional right-aligned task metadata, such as "18,400 of 25,000 rows". */
+    metadata?: ReactNode;
+    /** Show the formatted value beside the label. Defaults to `true` when `label` is supplied. */
+    showValue?: boolean;
+    /** Replaces the formatted value while retaining the default summary layout. */
+    valueSlot?: ReactNode;
+    /** Replaces the entire content above the track. */
+    headerSlot?: ReactNode;
+    /** Replaces the default track and indicator composition. */
+    trackSlot?: ReactNode;
+    /** Track thickness. @default "default" */
+    size?: ProgressSize;
+    /** Semantic indicator color. @default "primary" */
+    tone?: ProgressTone;
+    /** Props forwarded to the default track. Ignored when `trackSlot` is supplied. */
+    trackProps?: ProgressTrackProps;
+    /** Props forwarded to the default indicator. Ignored when `trackSlot` is supplied. */
+    indicatorProps?: ProgressIndicatorProps;
+    /** Override the indeterminate screen-reader copy. */
+    strings?: StringsProp<ProgressStrings>;
+}
+export interface ProgressTrackProps extends ProgressPrimitive.Track.Props {
+    /** Track thickness. @default "default" */
+    size?: ProgressSize;
+}
+export interface ProgressIndicatorProps extends ProgressPrimitive.Indicator.Props {
+    /** Semantic fill color. @default "primary" */
+    tone?: ProgressTone;
+}
+export interface ProgressLabelProps extends ProgressPrimitive.Label.Props {
+    /** Accessible label content. */
+    children?: ReactNode;
+}
+export interface ProgressValueProps extends Omit<ProgressPrimitive.Value.Props, 'children'> {
+    /** Customize the formatted display while preserving the value semantics. */
+    children?: (formattedValue: string | null, value: number | null) => ReactNode;
+}
+declare const Progress: import("react").ForwardRefExoticComponent<Omit<ProgressProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+declare const ProgressTrack: import("react").ForwardRefExoticComponent<Omit<ProgressTrackProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+declare const ProgressIndicator: import("react").ForwardRefExoticComponent<Omit<ProgressIndicatorProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+declare const ProgressLabel: import("react").ForwardRefExoticComponent<Omit<ProgressLabelProps, "ref"> & import("react").RefAttributes<HTMLSpanElement>>;
+declare const ProgressValue: import("react").ForwardRefExoticComponent<Omit<ProgressValueProps, "ref"> & import("react").RefAttributes<HTMLSpanElement>>;
+export { Progress, ProgressTrack, ProgressIndicator, ProgressLabel, ProgressValue, defaultProgressStrings };
+export type { ProgressStrings };

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

@@ -0,0 +1,5 @@
+export interface ProgressStrings {
+    /** Screen-reader value announced while progress is indeterminate. */
+    indeterminateValue: string;
+}
+export declare const defaultProgressStrings: ProgressStrings;

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

@@ -0,0 +1,39 @@
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+type DivProps = ComponentPropsWithoutRef<'div'>;
+type StateDisplayVariant = 'inline' | 'panel';
+export type LoadingStateVariant = StateDisplayVariant;
+export interface LoadingStateProps extends DivProps {
+    /** Primary line of the state message. */
+    label?: ReactNode;
+    /** Supporting copy under the label. */
+    description?: ReactNode;
+    /** Completion percentage, 0-100, for determinate loading. */
+    progress?: number;
+    /** Which state is shown — loading, empty, or error. */
+    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. */
+    icon?: ReactNode;
+}
+export declare const LoadingState: import("react").ForwardRefExoticComponent<LoadingStateProps & import("react").RefAttributes<HTMLDivElement>>;
+export type ErrorStateVariant = StateDisplayVariant;
+export interface ErrorStateProps extends Omit<DivProps, 'title'> {
+    /** Heading above the description. */
+    title?: ReactNode;
+    /** Supporting copy under the label. */
+    description?: ReactNode;
+    /** Control offered alongside the message. */
+    action?: ReactNode;
+    onRetry?: () => void;
+    /** Copy for the retry action in the error state. */
+    retryLabel?: ReactNode;
+    /** Which state is shown — loading, empty, or error. */
+    variant?: ErrorStateVariant;
+    /** Glyph shown above the message. */
+    icon?: ReactNode;
+}
+export declare const ErrorState: import("react").ForwardRefExoticComponent<ErrorStateProps & import("react").RefAttributes<HTMLDivElement>>;
+export {};

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

@@ -0,0 +1,32 @@
+/**
+ * ControlledFormField — react-hook-form integration for the optional-peer-free
+ * `FormField` presentation component. Keeping this binding in its own module
+ * prevents unrelated display and form-chrome consumers from loading RHF.
+ */
+import type { ComponentProps, ReactNode } from 'react';
+import { type Control, type ControllerFieldState, type ControllerRenderProps, type FieldPath, type FieldValues, type RegisterOptions } from 'react-hook-form';
+import { FormField } from './form-field';
+import { type ControlledFormFieldStrings } from './controlled-form-field.strings';
+import { type StringsProp } from '../../../lib/strings';
+type FieldChromeProps = Omit<ComponentProps<typeof FormField>, 'children' | 'error' | 'htmlFor'>;
+export type FormFieldErrorGetter<TName extends string> = (field: TName) => string | undefined;
+export interface ControlledFormFieldProps<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>> extends FieldChromeProps {
+    /** Field name in the react-hook-form schema. */
+    name: TName;
+    /** The form's `control` object from `useForm`. */
+    control: Control<TFieldValues>;
+    /** Validation rules passed to react-hook-form. */
+    rules?: RegisterOptions<TFieldValues, TName>;
+    /** Validation message, overriding the one derived from form state. */
+    error?: FormFieldErrorGetter<TName>;
+    /** Overrides the field's own copy. */
+    strings?: StringsProp<ControlledFormFieldStrings>;
+    children: (field: ControllerRenderProps<TFieldValues, TName>, 
+    /** Validation message, overriding the one derived from form state. */
+    error: string | undefined, invalid: boolean, fieldState: ControllerFieldState) => ReactNode;
+}
+export declare function ControlledFormField<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>({ name, control, rules, error: errorGetter, strings: stringsProp, children, ...chromeProps }: ControlledFormFieldProps<TFieldValues, TName>): import("react").JSX.Element;
+export declare namespace ControlledFormField {
+    var displayName: string;
+}
+export { defaultControlledFormFieldStrings, type ControlledFormFieldStrings, } from './controlled-form-field.strings';

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

@@ -0,0 +1,7 @@
+export interface ControlledFormFieldStrings {
+    required: string;
+    requiredWithLabel: string;
+    invalid: string;
+}
+export declare const defaultControlledFormFieldStrings: ControlledFormFieldStrings;
+export declare function interpolateControlledFormFieldString(template: string, label: string): string;

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

@@ -0,0 +1,38 @@
+/**
+ * FormField — optional-peer-free presentation chrome for a label, control,
+ * hint/helper, and validation error. The react-hook-form integration lives in
+ * `controlled-form-field.tsx` so presentational consumers do not load RHF.
+ */
+import * as React from 'react';
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+export interface FieldChromeProps {
+    /** Caption rendered above the control, associated through `htmlFor`. */
+    label?: ReactNode;
+    /** Marks the field required and renders the required indicator by the label. */
+    required?: boolean;
+    /**
+     * Lowest-priority supporting line: shown only when neither `error` nor
+     * `helperText` is set. Use for formatting rules and expectations.
+     */
+    hint?: ReactNode;
+    /**
+     * Validation message, and the highest-priority supporting line — it replaces
+     * `helperText` and `hint` rather than stacking with them. Rendered with
+     * `role="alert"` and `aria-live="polite"` in the error tone.
+     */
+    error?: ReactNode;
+    /**
+     * Middle-priority supporting line: replaces `hint`, and is itself replaced by
+     * `error`. The field renders exactly one supporting line, resolved as
+     * `error || helperText || hint` — copy the user still needs while fixing a
+     * validation failure therefore belongs in the `error` message itself.
+     */
+    helperText?: ReactNode;
+}
+export interface FormFieldProps extends FieldChromeProps, Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
+    children: ReactNode;
+    htmlFor?: string;
+    /** ID for the resolved hint, helper, or error; controls can reference it explicitly. */
+    supportingTextId?: string;
+}
+export declare const FormField: React.ForwardRefExoticComponent<FormFieldProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,86 @@
+import type { ComponentScale } from '../../../lib/component-vocabulary';
+export declare const formControlSizeClasses: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+export declare const formControlHorizontalPaddingClasses: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+export declare const formControlPaddingClasses: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+export declare const formControlInlineGapClasses: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+export declare const formControlIconClasses: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+export declare const formControlIconOffsetClasses: {
+    sm: string;
+    md: string;
+    lg: "ps-[calc((var(--control-x)+var(--icon)*1.25+0.5rem)*var(--space-scale))]";
+};
+export declare const formControlEndIconOffsetClasses: {
+    sm: string;
+    md: string;
+    lg: "pe-[calc((var(--control-x)+var(--icon)*1.25+0.5rem)*var(--space-scale))]";
+};
+export declare const formControlAddonOffsetClasses: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+export declare const formControlEndAddonOffsetClasses: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+export declare const formControlCountOffsetClasses: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+/**
+ * Min-heights matching `formControlSizeClasses` so multi-line trigger
+ * variants (e.g. `Select` showing wrapped descriptions) can keep the
+ * size's vertical rhythm without locking to a fixed `h-{n}`.
+ */
+export declare const formControlMinHeightClasses: {
+    sm: string;
+    md: string;
+    lg: 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-radius
+ * 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.
+ */
+export declare function formFieldTriggerClasses(size: ComponentScale): string;
+export declare const formTextareaSizeClasses: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+export declare const formLabelSizeClasses: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+export declare function resolveFormControlSize(sizeProp: ComponentScale | undefined, defaultScale: ComponentScale | undefined): ComponentScale;
+export declare function resolveFormLabelSize(sizeProp: ComponentScale | undefined, defaultScale: ComponentScale | undefined): ComponentScale;

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

@@ -0,0 +1,4 @@
+export * from './form-field';
+export * from './controlled-form-field';
+export * from './workflow';
+export { OperationPasswordForm, type OperationPasswordFormProps } from './operation-password-form';

package/dist/components/base/forms/operation-password-form.d.ts

@@ -0,0 +1,16 @@
+export type ErrorBag = Record<string, string | string[] | undefined>;
+export interface OperationPasswordFormProps {
+    formId: string;
+    onSubmit: (data: {
+        password: string;
+    }) => Promise<void>;
+    errors?: ErrorBag;
+    /** Shows the pending indicator. */
+    loading?: boolean;
+    /** Display label. */
+    label: string;
+}
+export declare function OperationPasswordForm(props: OperationPasswordFormProps): import("react").JSX.Element;
+export declare namespace OperationPasswordForm {
+    var displayName: string;
+}

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

@@ -0,0 +1,68 @@
+/** Form workflow primitives — section chrome, errors, dirty state, and submit state. */
+import type { ReactNode } from 'react';
+import type { ButtonProps } from '../buttons';
+import type { SmartCardSurface } from '../cards';
+import type { AlertTone } from '../feedback';
+export interface FormSectionProps {
+    /** Section title. */
+    title?: ReactNode;
+    /** Supporting sentence under the title. */
+    description?: ReactNode;
+    /** Controls in the section header. */
+    actions?: ReactNode;
+    children?: ReactNode;
+    /** Content below the section body. */
+    footer?: ReactNode;
+    /** Outer chrome. Use `flat` when the section already sits inside a card. */
+    surface?: SmartCardSurface;
+    className?: string;
+    /** Merged onto the section body. */
+    contentClassName?: string;
+}
+export declare function FormSection({ title, description, actions, children, footer, surface, className, contentClassName, }: FormSectionProps): import("react").JSX.Element;
+export interface FormActionsBarProps {
+    /** Action content used when `trailing` is not provided. */
+    children?: ReactNode;
+    /** Optional status or context shown before the actions. Scalar copy uses secondary Typography. */
+    leading?: ReactNode;
+    /** Preferred action slot. When provided, it takes precedence over `children`. */
+    trailing?: ReactNode;
+    /** Keep the bar attached to the bottom of its nearest scrolling ancestor. */
+    sticky?: boolean;
+    className?: string;
+}
+/** Responsive form-footer chrome for status and consumer-owned actions. */
+export declare function FormActionsBar({ children, leading, trailing, sticky, className, }: FormActionsBarProps): import("react").JSX.Element;
+export interface ErrorSummaryProps {
+    /** Section title. */
+    title: ReactNode;
+    /** Supporting sentence under the title. */
+    description?: ReactNode;
+    /** Validation messages listed in the error summary. */
+    errors?: readonly ReactNode[];
+    /** Control offered alongside the summary. */
+    action?: ReactNode;
+    className?: string;
+}
+export declare function ErrorSummary({ title, description, errors, action, className, }: ErrorSummaryProps): import("react").JSX.Element;
+export interface DirtyStateBannerProps {
+    /** Section title. */
+    title: ReactNode;
+    /** Supporting sentence under the title. */
+    description?: ReactNode;
+    /** Controls in the section header. */
+    actions?: ReactNode;
+    /** Semantic tone of the banner. */
+    tone?: Extract<AlertTone, 'neutral' | 'info' | 'warning'>;
+    className?: string;
+}
+export declare function DirtyStateBanner({ title, description, actions, tone, className, }: DirtyStateBannerProps): import("react").JSX.Element;
+export interface SubmitStateButtonProps extends Omit<ButtonProps, 'loading'> {
+    /** Shows the pending state and blocks repeat submissions. */
+    submitting?: boolean;
+    /** Whether the form has unsaved changes. */
+    dirty?: boolean;
+    /** Disables submit until `dirty` is true, so a clean form cannot be re-saved. */
+    disableWhenPristine?: boolean;
+}
+export declare function SubmitStateButton({ submitting, dirty, disableWhenPristine, disabled, children, ...props }: SubmitStateButtonProps): import("react").JSX.Element;

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

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import { type StringsProp } from '../../../lib/strings';
+export interface CoordinatesObjectValue {
+    lat?: string;
+    lng?: string;
+}
+export type CoordinatesValue = string | CoordinatesObjectValue;
+export interface CoordinatesInputStrings {
+    /** Above-field label for the latitude input. Empty string hides it. */
+    latLabel: string;
+    /** Above-field label for the longitude input. Empty string hides it. */
+    lngLabel: string;
+    /** Placeholder shown in the latitude input. */
+    latPlaceholder: string;
+    /** Placeholder shown in the longitude input. */
+    lngPlaceholder: string;
+    /** Anchor text for the Google Maps preview link. Empty string hides it. */
+    previewLinkLabel: string;
+}
+export declare const defaultCoordinatesInputStrings: CoordinatesInputStrings;
+export interface CoordinatesInputProps {
+    /** Controlled value */
+    value?: CoordinatesValue;
+    /** Default value for uncontrolled mode */
+    defaultValue?: CoordinatesValue;
+    /** Output format */
+    format?: 'string' | 'object';
+    /** Change handler */
+    onChange?: (e: {
+        target: {
+            value: CoordinatesValue;
+        };
+    }) => void;
+    /** Number of decimal places */
+    decimalPlaces?: number;
+    /** Show preview link to Google Maps */
+    showPreviewLink?: boolean;
+    /** Override default strings (labels + placeholders + preview link). */
+    strings?: StringsProp<CoordinatesInputStrings>;
+    /** Error state for styling (passed from FormField) */
+    invalid?: boolean;
+    /** Additional class names */
+    className?: string;
+    /** Disabled state */
+    disabled?: boolean;
+}
+export declare const CoordinatesInput: React.ForwardRefExoticComponent<CoordinatesInputProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,44 @@
+import { type StringsProp } from '../../../lib/strings';
+import { type DecimalInputProps, type DecimalInputStrings } from './decimal-input';
+export interface CurrencyOption {
+    value: string;
+    label: string;
+}
+export interface CurrencyInputStrings extends DecimalInputStrings {
+    /** Accessible name for the currency selector. */
+    currencyAriaLabel: string;
+}
+export declare const defaultCurrencyInputStrings: CurrencyInputStrings;
+export interface CurrencyInputProps extends Omit<DecimalInputProps, 'label' | 'hint' | 'helperText' | 'error' | 'strings'> {
+    /** Current currency value */
+    currency?: string;
+    /** Default currency if uncontrolled */
+    defaultCurrency?: string;
+    /** List of available currencies (simple strings or objects with value/label) */
+    currencies?: (string | CurrencyOption)[];
+    /** Callback when currency changes */
+    onCurrencyChange?: (currency: string) => void;
+    /** Position of currency dropdown */
+    currencyPosition?: 'start' | 'end';
+    /** Disable currency selection */
+    disableCurrencySelector?: boolean;
+    /** Placeholder for currency dropdown */
+    currencyPlaceholder?: string;
+    /** Width of the currency dropdown */
+    currencyWidth?: string;
+    /** Label for currency field (sub-label) */
+    currencyLabel?: string;
+    /** Localizes the selector name and inherited decimal-stepper labels. */
+    strings?: StringsProp<CurrencyInputStrings>;
+    /** Error state for styling (passed from FormField) */
+    invalid?: boolean;
+    /** Called when the input is misconfigured (mismatched currency/defaultCurrency
+     *  while the selector is disabled, missing currency, etc.). The library
+     *  also DEV-logs the same message to the console. */
+    onConfigError?: (message: string, details: {
+        currency?: string;
+        defaultCurrency?: string;
+        disableCurrencySelector?: boolean;
+    }) => void;
+}
+export declare const CurrencyInput: import("react").NamedExoticComponent<Omit<CurrencyInputProps, "ref"> & import("react").RefAttributes<HTMLInputElement>>;

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

@@ -0,0 +1,53 @@
+/**
+ * DecimalInput — text-based numeric input with decimal-place enforcement,
+ * locale-friendly comma → dot normalisation, optional min/max clamping,
+ * rounding mode (`round` / `floor` / `ceil` / `half-even`), and optional
+ * stepper buttons when `step` is set.
+ *
+ * Wraps the base `Input` so all add-on / icon / clear / loading features
+ * still work. Extra features layered on top:
+ *
+ *  - `step` — when set, renders − / + stepper buttons that snap the value
+ *    to a multiple of `step` (anchored at `min` if provided, else 0).
+ *  - `roundingMode` — controls how stepper / blur normalisation rounds
+ *    half values; default `'round'` (round-half-up).
+ *  - `normalizeOnBlur` (default `true`) — pads the displayed value to the
+ *    full `decimalPlaces` count and clamps to `[min, max]` when the field
+ *    loses focus.
+ *
+ * The `value` prop is always a plain string (consumers parse it as needed)
+ * so RHF / Inertia can treat it like any other input.
+ */
+import * as React from 'react';
+import { type StringsProp } from '../../../lib/strings';
+import { type InputProps } from '../text-inputs';
+export type DecimalRoundingMode = 'round' | 'floor' | 'ceil' | 'half-even';
+export interface DecimalInputStrings {
+    /** Accessible label for the decrement stepper. */
+    decrement: string;
+    /** Accessible label for the increment stepper. */
+    increment: string;
+}
+export declare const defaultDecimalInputStrings: DecimalInputStrings;
+export interface DecimalInputProps extends Omit<InputProps, 'type' | 'inputMode' | 'strings'> {
+    /** Maximum fractional digits accepted and used during normalization. */
+    decimalPlaces?: number;
+    /** Minimum accepted numeric value. */
+    min?: number;
+    /** Maximum accepted numeric value. */
+    max?: number;
+    /** Whether a leading negative sign is accepted. */
+    allowNegative?: boolean;
+    /** Whether the field may remain blank. */
+    allowEmpty?: boolean;
+    /** When set, renders − / + steppers and snaps the value to multiples of `step`. */
+    step?: number;
+    /** How to round when normalising on blur or stepping. Default `'round'`. */
+    roundingMode?: DecimalRoundingMode;
+    /** Pad to full decimalPlaces and clamp to [min, max] on blur. Default `true`. */
+    normalizeOnBlur?: boolean;
+    /** String overrides for stepper aria-labels. */
+    strings?: StringsProp<DecimalInputStrings>;
+}
+declare const DecimalInput: React.ForwardRefExoticComponent<Omit<DecimalInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+export { DecimalInput };

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

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import { type StringsProp } from '../../../lib/strings';
+import { type FormControlSize } from '../../../lib/ui-provider';
+export interface DimensionObject {
+    width?: string;
+    height?: string;
+    depth?: string;
+}
+export type DimensionValue = string | DimensionObject;
+export type DimensionUnit = 'mm' | 'cm' | 'm' | 'in' | 'ft' | 'px';
+export interface DimensionsInputStrings {
+    width: string;
+    height: string;
+    depth: string;
+    unit: string;
+    widthPlaceholder: string;
+    heightPlaceholder: string;
+    depthPlaceholder: string;
+}
+export declare const defaultDimensionsInputStrings: DimensionsInputStrings;
+export interface DimensionsInputProps {
+    /** Current value (string "WxHxD" or object { width, height, depth }) */
+    value?: DimensionValue;
+    /** Default value for uncontrolled mode */
+    defaultValue?: DimensionValue;
+    /** Format type: 'string' for "WxHxD" or 'object' for { width, height, depth } */
+    format?: 'string' | 'object';
+    /** Current length unit value. */
+    unit?: DimensionUnit;
+    /** Default length unit for uncontrolled mode. */
+    defaultUnit?: DimensionUnit;
+    /** Label for width input (sub-label) */
+    widthLabel?: string;
+    /** Label for height input (sub-label) */
+    heightLabel?: string;
+    /** Label for depth/length input (sub-label) */
+    depthLabel?: string;
+    /** Label for unit selector (sub-label) */
+    unitLabel?: string;
+    /** Placeholder for the unit select */
+    unitPlaceholder?: string;
+    /** Placeholder for width */
+    widthPlaceholder?: string;
+    /** Placeholder for height */
+    heightPlaceholder?: string;
+    /** Placeholder for depth */
+    depthPlaceholder?: string;
+    /** Form control size — flows through `useDensityConfig().defaultScale`. */
+    size?: FormControlSize;
+    /** Callback when value changes */
+    onChange?: (e: {
+        target: {
+            value: DimensionValue;
+        };
+    }) => void;
+    /** Callback when unit changes */
+    onUnitChange?: (unit: DimensionUnit) => void;
+    /** Number of decimal places. Defaults to 2 */
+    decimalPlaces?: number;
+    /** Minimum value for all dimensions */
+    min?: number;
+    /** Maximum value for all dimensions */
+    max?: number;
+    /** Show unit selector. Defaults to true */
+    showUnitSelector?: boolean;
+    /** Disable unit selector */
+    disableUnitSelector?: boolean;
+    /** Layout orientation. Defaults to 'horizontal' */
+    layout?: 'horizontal' | 'vertical';
+    /** Error state for styling (passed from FormField) */
+    invalid?: boolean;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** String overrides merged over defaults. Direct props (e.g. `widthLabel`) win over `strings` keys. */
+    strings?: StringsProp<DimensionsInputStrings>;
+}
+export declare const DimensionsInput: React.ForwardRefExoticComponent<DimensionsInputProps & React.RefAttributes<HTMLDivElement>>;