@geomak/ui 5.7.1 → 5.8.0

package/dist/index.d.cts

@@ -1787,6 +1787,7 @@ interface SkeletonCardProps extends SkeletonBaseProps {
 declare function SkeletonCard({ hasAvatar, lines, className, style }: SkeletonCardProps): react_jsx_runtime.JSX.Element;
 
 interface ButtonProps {
+    /** Button content (text or nodes). */
     content?: React__default.ReactNode;
     /** Visual style variant */
     variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
@@ -1794,12 +1795,15 @@ interface ButtonProps {
     size?: 'sm' | 'md' | 'lg';
     /** HTML button type */
     buttonType?: 'button' | 'submit' | 'reset';
+    /** Show a loading spinner and disable the control. */
     loading?: boolean;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
     /** Inline style overrides (width, etc.). Margins/layout belong in the parent. */
     style?: React__default.CSSProperties;
     /** Leading icon — rendered before content */
     icon?: React__default.ReactNode;
+    /** Click handler. */
     onClick?: React__default.MouseEventHandler<HTMLButtonElement>;
     /**
      * @deprecated Pass `variant` instead. Kept for API compat — currently no-op.
@@ -1870,8 +1874,15 @@ interface FieldLabelProps {
     required?: boolean;
     /** Reveals an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
-    /** Apply horizontal-layout spacing (top margin, no-wrap, shrink). */
+    /** Apply horizontal-layout spacing (no-wrap, shrink). */
     horizontal?: boolean;
+    /**
+     * Vertical alignment of the label against the control in horizontal layout.
+     * `'start'` (default) nudges the label down to meet a standard ~36px input's
+     * first line; `'center'` removes that offset so the label centres against a
+     * short control (Switch, SegmentedControl).
+     */
+    align?: 'start' | 'center';
     style?: React__default.CSSProperties;
     /** Label column width in horizontal layout. */
     width?: string | number;
@@ -1885,7 +1896,7 @@ interface FieldLabelProps {
  *
  * Returns `null` when there's nothing to show (no label and no helperText).
  */
-declare function FieldLabel({ label, htmlFor, required, helperText, horizontal, style, width, className, }: FieldLabelProps): react_jsx_runtime.JSX.Element;
+declare function FieldLabel({ label, htmlFor, required, helperText, horizontal, align, style, width, className, }: FieldLabelProps): react_jsx_runtime.JSX.Element;
 interface FieldProps {
     label?: React__default.ReactNode;
     /** `id` of the control — links the `<label htmlFor>`. */
@@ -1899,6 +1910,12 @@ interface FieldProps {
     required?: boolean;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /**
+     * Label alignment against the control in horizontal layout. `'start'`
+     * (default) for standard-height inputs; `'center'` for short controls
+     * (Switch) so the label lines up with the control's centre.
+     */
+    labelAlign?: 'start' | 'center';
     labelStyle?: React__default.CSSProperties;
     /** Width of the label column in horizontal layout (CSS length). */
     labelWidth?: string | number;
@@ -1921,25 +1938,36 @@ interface FieldProps {
  * medium weight so it reads as the anchor, while the input's placeholder is
  * muted — establishing hierarchy without making the label tiny.
  */
-declare function Field({ label, htmlFor, errorId, errorMessage, layout, required, helperText, labelStyle, labelWidth, className, children, }: FieldProps): react_jsx_runtime.JSX.Element;
+declare function Field({ label, htmlFor, errorId, errorMessage, layout, required, helperText, labelAlign, labelStyle, labelWidth, className, children, }: FieldProps): react_jsx_runtime.JSX.Element;
 
 interface TextInputProps {
+    /** Controlled string value. */
     value?: string;
+    /** Native change handler — read `e.target.value`. */
     onChange?: React__default.ChangeEventHandler<HTMLInputElement>;
+    /** Disable interaction and dim the field. */
     disabled?: boolean;
+    /** Field label rendered above (vertical) or beside (horizontal) the input. */
     label?: React__default.ReactNode;
+    /** `id` for the input + the `<label htmlFor>` link. */
     htmlFor?: string;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
+    /** Native form field name (used for `FormData` serialisation). */
     name?: string;
     /** Native input type. Defaults to `'text'`. */
     type?: 'text' | 'email' | 'url' | 'tel';
+    /** Inline style applied to the `<input>` element. */
     inputStyle?: React__default.CSSProperties;
+    /** Inline style applied to the field shell / adornment wrapper. */
     style?: React__default.CSSProperties;
     /** Label/input orientation. Defaults to `'vertical'`. */
     layout?: 'horizontal' | 'vertical';
     /** Size preset — controls height, padding, and font. Default `'md'`. */
     size?: FieldSize;
+    /** Native blur handler. */
     onBlur?: React__default.FocusEventHandler<HTMLInputElement>;
+    /** Validation message — shown under the input; also flags it red + `aria-invalid`. */
     errorMessage?: React__default.ReactNode;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
@@ -1949,6 +1977,7 @@ interface TextInputProps {
     prefix?: React__default.ReactNode;
     /** Optional trailing adornment (icon / suffix / unit). */
     suffix?: React__default.ReactNode;
+    /** @deprecated Use `htmlFor`. */
     id?: string;
 }
 /**
@@ -1987,24 +2016,37 @@ interface NumberInputProps {
             name?: string;
         };
     }) => void;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
     /** Label/input orientation. Defaults to `'vertical'`. */
     layout?: 'horizontal' | 'vertical';
     /** Size preset. Default `'md'`. */
     size?: FieldSize;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /** Show a required asterisk after the label. */
     required?: boolean;
+    /** Inline style applied to the inner input element. */
     inputStyle?: React__default.CSSProperties;
+    /** Inline style applied to the label. */
     labelStyle?: React__default.CSSProperties;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
+    /** Inline style applied to the control shell. */
     style?: React__default.CSSProperties;
+    /** Minimum allowed value. */
     min?: number;
+    /** Maximum allowed value. */
     max?: number;
+    /** Render read-only — visible but not editable. */
     readOnly?: boolean;
     /** Optional precision for floating-point steps (number of decimal places to round to). */
     precision?: number;
@@ -2044,23 +2086,35 @@ interface NumberInputProps {
 declare function NumberInput({ step, value, onChange, label, htmlFor, name, disabled, layout, size, errorMessage, helperText, required, inputStyle, labelStyle, placeholder, style, min, max, readOnly, precision, }: NumberInputProps): react_jsx_runtime.JSX.Element;
 
 interface PasswordProps {
+    /** Controlled value. */
     value?: string;
+    /** Fires when the value changes. */
     onChange?: React__default.ChangeEventHandler<HTMLInputElement>;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** Inline style applied to the inner input element. */
     inputStyle?: React__default.CSSProperties;
+    /** Inline style applied to the control shell. */
     style?: React__default.CSSProperties;
     /** Label/input orientation. Defaults to `'vertical'`. */
     layout?: 'horizontal' | 'vertical';
     /** Size preset — controls height, padding, and font. Default `'md'`. */
     size?: FieldSize;
+    /** Blur handler — useful for touched/validation timing. */
     onBlur?: React__default.FocusEventHandler<HTMLInputElement>;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /** Show a required asterisk after the label. */
     required?: boolean;
     /** Override the "reveal" (password hidden) icon. */
     showIcon?: React__default.ReactNode;
@@ -2079,14 +2133,23 @@ interface PasswordProps {
 declare function Password({ value, onChange, disabled, label, htmlFor, placeholder, name, inputStyle, style, layout, size, onBlur, errorMessage, helperText, required, showIcon, hideIcon, }: PasswordProps): react_jsx_runtime.JSX.Element;
 
 interface SearchInputProps {
+    /** Controlled value. */
     value?: string;
+    /** Fires when the value changes. */
     onChange?: React__default.ChangeEventHandler<HTMLInputElement>;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** Inline style applied to the inner input element. */
     inputStyle?: React__default.CSSProperties;
+    /** Inline style applied to the control shell. */
     style?: React__default.CSSProperties;
     /** Label/input orientation. Defaults to `'vertical'`. */
     layout?: 'horizontal' | 'vertical';
@@ -2110,8 +2173,9 @@ interface SearchInputProps {
 declare const SearchInput: React__default.ForwardRefExoticComponent<SearchInputProps & React__default.RefAttributes<HTMLInputElement>>;
 
 interface CheckboxProps {
-    /** Controlled checked state */
+    /** Controlled checked state. */
     checked?: boolean;
+    /** Fires `{ target: { checked, id, name } }` for form-handler compatibility. */
     onChange?: (e: {
         target: {
             checked: boolean;
@@ -2119,12 +2183,22 @@ interface CheckboxProps {
             name?: string;
         };
     }) => void;
+    /** Primary label text. */
     label?: React__default.ReactNode;
+    /** Secondary line rendered under the label (same affordance as RadioGroup options). */
+    description?: React__default.ReactNode;
+    /** Native form field name. */
     name?: string;
-    /** `id` for the hidden input and the `<label htmlFor>` link */
+    /** `id` for the control and the `<label htmlFor>` link. */
     htmlFor?: string;
+    /** Validation message — shown under the control; also flags the box red + `aria-invalid`. */
     errorMessage?: React__default.ReactNode;
+    /** Contextual help revealed via an info icon + tooltip beside the label. */
+    helperText?: React__default.ReactNode;
+    /** Disable interaction + dim the control. */
     disabled?: boolean;
+    /** Show a required asterisk after the label. */
+    required?: boolean;
     /**
      * Box + label arrangement.
      * - `'horizontal'` (default): box and label on one row.
@@ -2132,34 +2206,36 @@ interface CheckboxProps {
      */
     layout?: 'horizontal' | 'vertical';
     /**
-     * Where the label sits relative to the box.
-     * - In horizontal: `'right'` (default) → box then label; `'left'` → label then box.
-     * - In vertical: `'right'` (default) → box then label below; `'left'` → label above then box.
+     * Which side of the box the label sits on.
+     * - `'right'` (default): box then label.
+     * - `'left'`: label then box (the description always wraps under the label).
      */
     labelPosition?: 'left' | 'right';
-    /** Contextual help revealed via an info icon + tooltip beside the label. */
-    helperText?: React__default.ReactNode;
-    /** Show a required asterisk after the label. */
-    required?: boolean;
-    /** @deprecated Use `checked` */
+    /** @deprecated Use `checked`. Kept for API compatibility. */
     value?: boolean;
 }
 /**
  * Accessible checkbox powered by Radix Checkbox.
  *
- * Radix handles keyboard activation, focus ring, and `role="checkbox"` ARIA.
- * The check mark pops in with a spring animation on first check.
+ * Radix handles keyboard activation, focus ring, and `role="checkbox"` ARIA;
+ * the check mark pops in with a spring on first check. Supports a secondary
+ * `description`, `helperText` tooltip, left/right label placement, and the
+ * shared error treatment — so it lines up with every other input in a form.
+ *
+ * Emits `{ target: { checked, id, name } }` for drop-in use with existing
+ * change handlers.
  *
  * @example
  * <Checkbox
  *   htmlFor="agree"
  *   label="I agree to the terms"
+ *   description="You can revoke consent any time in settings."
  *   checked={form.agree}
  *   onChange={({ target }) => setField('agree', target.checked)}
  * />
  */
 declare function Checkbox({ checked, value, // legacy alias
-onChange, label, name, htmlFor, errorMessage, disabled, layout, labelPosition, helperText, required, }: CheckboxProps): react_jsx_runtime.JSX.Element;
+onChange, label, description, name, htmlFor, errorMessage, helperText, disabled, required, layout, labelPosition, }: CheckboxProps): react_jsx_runtime.JSX.Element;
 
 interface RadioOption {
     /** Stable value submitted / reported on change. */
@@ -2172,13 +2248,17 @@ interface RadioOption {
     disabled?: boolean;
 }
 interface RadioGroupProps {
+    /** The selectable options. */
     options: RadioOption[];
     /** Controlled selected value. */
     value?: string;
     /** Uncontrolled initial value. */
     defaultValue?: string;
+    /** Fires when the value changes. */
     onChange?: (value: string) => void;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
     /**
      * Option arrangement. `'vertical'` (default) stacks options in a column;
@@ -2193,10 +2273,13 @@ interface RadioGroupProps {
     labelPosition?: 'left' | 'right';
     /** Size preset — controls the dot + text size. Default `'md'`. */
     size?: FieldSize;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Show a required asterisk after the label. */
     required?: boolean;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
 }
 /**
@@ -2229,6 +2312,7 @@ interface SwitchInputProps {
     checked?: boolean;
     /** Uncontrolled initial state. */
     defaultChecked?: boolean;
+    /** Fires when the value changes. */
     onChange?: (e: {
         target: {
             checked: boolean;
@@ -2252,9 +2336,13 @@ interface SwitchInputProps {
     offLabel?: React__default.ReactNode;
     /** Label rendered to the right of the track, emphasised while on. */
     onLabel?: React__default.ReactNode;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** Show a required asterisk after the label. */
     required?: boolean;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
 }
 /**
@@ -2292,11 +2380,17 @@ type DropdownKey = string | number;
  */
 type DropdownValue = DropdownKey | DropdownKey[];
 interface DropdownProps {
+    /** Enable multi-select (value becomes an array of keys). */
     isMultiselect?: boolean;
+    /** Show a search box inside the dropdown panel. */
     hasSearch?: boolean;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** Controlled value. */
     value?: DropdownValue;
+    /** Fires when the value changes. */
     onChange?: (e: {
         target: {
             value: DropdownValue;
@@ -2304,18 +2398,27 @@ interface DropdownProps {
             name?: string;
         };
     }) => void;
+    /** Blur handler — useful for touched/validation timing. */
     onBlur?: React__default.FocusEventHandler;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
     /** Label/input orientation. Defaults to `'vertical'`. */
     layout?: 'horizontal' | 'vertical';
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /** Show a required asterisk after the label. */
     required?: boolean;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
+    /** Inline style applied to the control shell. */
     style?: React__default.CSSProperties;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** The selectable items. */
     items?: DropdownItem[];
+    /** Inline style applied to the label. */
     labelStyle?: React__default.CSSProperties;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
     /** Size preset. Default `'md'`. */
     size?: FieldSize;
@@ -2344,11 +2447,17 @@ interface AutoCompleteItem {
     icon?: React__default.ReactNode;
 }
 interface AutoCompleteProps {
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** Inline style applied to the inner input element. */
     inputStyle?: React__default.CSSProperties;
+    /** Inline style applied to the control shell. */
     style?: React__default.CSSProperties;
     /** Label/input orientation. Defaults to `'vertical'`. */
     layout?: 'horizontal' | 'vertical';
@@ -2370,6 +2479,7 @@ interface AutoCompleteProps {
      * typing. Default `250`. Ignored when `items` is used.
      */
     debounce?: number;
+    /** Fires when a suggestion is selected, with its value. */
     onItemClick?: (value: string) => void;
     /** Custom "empty" message */
     emptyText?: string;
@@ -2385,6 +2495,7 @@ interface AutoCompleteProps {
     helperText?: React__default.ReactNode;
     /** Mark required (asterisk after the label). */
     required?: boolean;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
 }
 /**
@@ -2447,10 +2558,13 @@ interface TreeSelectProps {
             name?: string;
         };
     }) => void;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
     /** Form control id linkage. */
     htmlFor?: string;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
     /** Label/trigger orientation. Defaults to `'horizontal'`. */
     layout?: 'horizontal' | 'vertical';
@@ -2458,8 +2572,11 @@ interface TreeSelectProps {
     helperText?: React__default.ReactNode;
     /** Show a required asterisk after the label. */
     required?: boolean;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
+    /** Inline style applied to the control shell. */
     style?: React__default.CSSProperties;
     /**
      * Whether parent (branch) nodes can be selected. When `false`, parents
@@ -2511,7 +2628,9 @@ interface TreeSelectProps {
 declare function TreeSelect({ label, name, value, onChange, disabled, layout, helperText, required, errorMessage, style, htmlFor, items, placeholder, parentsSelectable, defaultExpandedKeys, size, }: TreeSelectProps): react_jsx_runtime.JSX.Element;
 
 interface FileInputProps {
+    /** Allow selecting more than one file. */
     allowMultiple?: boolean;
+    /** Fires when the value changes. */
     onChange?: (e: {
         target: {
             files: File[];
@@ -2520,8 +2639,11 @@ interface FileInputProps {
             value?: string;
         };
     }) => void;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
     /** Accepted MIME types / extensions, e.g. `'.xlsx,application/pdf'`. */
     accept?: string;
@@ -2531,10 +2653,13 @@ interface FileInputProps {
     hint?: React__default.ReactNode;
     /** Maximum file size in bytes. Files above this are rejected with an error. */
     maxSize?: number;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Show a required asterisk after the label. */
     required?: boolean;
     /** Override the upload glyph in the empty state. */
     icon?: React__default.ReactNode;
@@ -2566,10 +2691,13 @@ interface DatePickerProps {
     value?: Date | null;
     /** Fires with the next date (or `null` if cleared via the clear button). */
     onChange?: (date: Date | null) => void;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
     /** Text shown in the trigger when no date is selected. Default `"Select a date…"`. */
     placeholder?: string;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
     /** Label/trigger orientation. Defaults to `'horizontal'`. */
     layout?: 'horizontal' | 'vertical';
@@ -2577,12 +2705,15 @@ interface DatePickerProps {
     helperText?: React__default.ReactNode;
     /** Show a required asterisk after the label. */
     required?: boolean;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
     /** Earliest selectable date. Dates before this render disabled. */
     min?: Date;
     /** Latest selectable date. Dates after this render disabled. */
     max?: Date;
+    /** Inline style applied to the control shell. */
     style?: React__default.CSSProperties;
     /**
      * Custom formatter for the trigger display. Defaults to
@@ -2635,13 +2766,21 @@ type TemporalPickerProps = DatePickerProps;
 declare function DatePicker({ value, onChange, label, placeholder, htmlFor, name: _name, layout, helperText, required, disabled, errorMessage, min, max, style, format, weekStartsOn, clearable, size, }: DatePickerProps): react_jsx_runtime.JSX.Element;
 
 interface TextAreaProps {
+    /** Controlled value. */
     value?: string;
+    /** Fires when the value changes. */
     onChange?: React__default.ChangeEventHandler<HTMLTextAreaElement>;
+    /** Blur handler — useful for touched/validation timing. */
     onBlur?: React__default.FocusEventHandler<HTMLTextAreaElement>;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
     /** Label/control orientation. Default `'vertical'`. */
     layout?: 'horizontal' | 'vertical';
@@ -2662,11 +2801,15 @@ interface TextAreaProps {
     showCount?: boolean;
     /** CSS `resize` behaviour. Default `'vertical'` (or `'none'` when autoGrow). */
     resize?: 'none' | 'vertical' | 'horizontal' | 'both';
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /** Show a required asterisk after the label. */
     required?: boolean;
+    /** Inline style applied to the control shell. */
     style?: React__default.CSSProperties;
+    /** Inline style applied to the inner input element. */
     inputStyle?: React__default.CSSProperties;
 }
 /**
@@ -2694,16 +2837,19 @@ interface SegmentedOption {
     disabled?: boolean;
 }
 interface SegmentedControlProps {
+    /** The selectable options. */
     options: SegmentedOption[];
     /** Controlled selected value. */
     value?: string;
     /** Uncontrolled initial value. */
     defaultValue?: string;
+    /** Fires when the value changes. */
     onChange?: (value: string) => void;
     /** Size preset. Default `'md'`. */
     size?: FieldSize;
     /** Stretch to fill the container, segments share the width equally. */
     fullWidth?: boolean;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
     /** Optional label, positioned per `layout`. */
     label?: React__default.ReactNode;
@@ -2713,8 +2859,11 @@ interface SegmentedControlProps {
     helperText?: React__default.ReactNode;
     /** Native form field name (emits a hidden input carrying the value). */
     name?: string;
+    /** Show a required asterisk after the label. */
     required?: boolean;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
+    /** Accessible label for the control. */
     'aria-label'?: string;
 }
 /**
@@ -2756,14 +2905,21 @@ interface SliderMark {
     label?: React__default.ReactNode;
 }
 interface SliderProps {
+    /** Controlled value. */
     value?: SliderValue;
+    /** Uncontrolled initial value. */
     defaultValue?: SliderValue;
+    /** Fires when the value changes. */
     onChange?: (value: SliderValue) => void;
     /** Fired once at the end of a drag/keyboard interaction. */
     onChangeEnd?: (value: SliderValue) => void;
+    /** Minimum allowed value. */
     min?: number;
+    /** Maximum allowed value. */
     max?: number;
+    /** Step increment between values. */
     step?: number;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
     /** Show the current value(s) next to the label. */
     showValue?: boolean;
@@ -2773,14 +2929,19 @@ interface SliderProps {
     marks?: SliderMark[];
     /** Show a value tooltip above the thumb while dragging. */
     tooltip?: boolean;
+    /** Size preset — controls height, padding, and font. Default 'md'. */
     size?: FieldSize;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
     /** Show a required asterisk after the label. */
     required?: boolean;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
 }
 /**
@@ -2811,17 +2972,27 @@ interface TagsInputProps {
     value?: string[];
     /** Uncontrolled initial tags. */
     defaultValue?: string[];
+    /** Fires when the value changes. */
     onChange?: (tags: string[]) => void;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
+    /** Label/control orientation: 'horizontal' or 'vertical'. */
     layout?: 'horizontal' | 'vertical';
+    /** Size preset — controls height, padding, and font. Default 'md'. */
     size?: FieldSize;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /** Show a required asterisk after the label. */
     required?: boolean;
     /** Maximum number of tags. Further input is ignored once reached. */
     maxTags?: number;
@@ -2852,20 +3023,29 @@ declare function TagsInput({ value, defaultValue, onChange, label, htmlFor, name
 interface OtpInputProps {
     /** Number of code boxes. Default `6`. */
     length?: number;
+    /** Controlled value. */
     value?: string;
+    /** Fires when the value changes. */
     onChange?: (code: string) => void;
     /** Fired when every box is filled. */
     onComplete?: (code: string) => void;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
     /** `'numeric'` (default) restricts to digits; `'alphanumeric'` allows letters too. */
     mode?: 'numeric' | 'alphanumeric';
     /** Render boxes as masked dots (for PIN entry). */
     masked?: boolean;
+    /** Size preset — controls height, padding, and font. Default 'md'. */
     size?: FieldSize;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
+    /** Show a required asterisk after the label. */
     required?: boolean;
     /** Label/control orientation. Default `'vertical'`. */
     layout?: 'horizontal' | 'vertical';
@@ -2887,8 +3067,11 @@ interface OtpInputProps {
 declare function OtpInput({ length, value, onChange, onComplete, label, htmlFor, name, mode, masked, size, disabled, errorMessage, required, layout, helperText, groupAfter, }: OtpInputProps): react_jsx_runtime.JSX.Element;
 
 interface RatingProps {
+    /** Controlled value. */
     value?: number;
+    /** Uncontrolled initial value. */
     defaultValue?: number;
+    /** Fires when the value changes. */
     onChange?: (value: number) => void;
     /** Number of icons. Default `5`. */
     count?: number;
@@ -2898,12 +3081,17 @@ interface RatingProps {
     readOnly?: boolean;
     /** Clicking the current value again clears to 0. Default `true`. */
     clearable?: boolean;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** Size preset — controls height, padding, and font. Default 'md'. */
     size?: FieldSize;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
     /** Override the icon. Receives a `filled` flag. Default is a star. */
     icon?: (filled: boolean) => React__default.ReactNode;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
     /** Label/control orientation. Default `'vertical'`. */
     layout?: 'horizontal' | 'vertical';
@@ -2932,12 +3120,19 @@ declare function Rating({ value, defaultValue, onChange, count, allowHalf, readO
 interface TimePickerProps {
     /** Value as `"HH:mm"` (24h) or `"HH:mm:ss"`. `null`/`undefined` = unset. */
     value?: string | null;
+    /** Fires when the value changes. */
     onChange?: (value: string | null) => void;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
+    /** Label/control orientation: 'horizontal' or 'vertical'. */
     layout?: 'horizontal' | 'vertical';
+    /** Size preset — controls height, padding, and font. Default 'md'. */
     size?: FieldSize;
     /** Display in 12-hour format with AM/PM (value stays 24h `"HH:mm"`). */
     use12Hours?: boolean;
@@ -2945,11 +3140,15 @@ interface TimePickerProps {
     withSeconds?: boolean;
     /** Minute step. Default `1`. Use `5` / `15` for coarse pickers. */
     minuteStep?: number;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /** Show a required asterisk after the label. */
     required?: boolean;
+    /** Inline style applied to the control shell. */
     style?: React__default.CSSProperties;
 }
 /**
@@ -2974,25 +3173,39 @@ interface DateRangePreset {
     range: () => DateRange;
 }
 interface DateRangePickerProps {
+    /** Controlled value. */
     value?: DateRange;
+    /** Fires when the value changes. */
     onChange?: (range: DateRange) => void;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
+    /** Label/control orientation: 'horizontal' or 'vertical'. */
     layout?: 'horizontal' | 'vertical';
+    /** Size preset — controls height, padding, and font. Default 'md'. */
     size?: FieldSize;
+    /** Earliest selectable date. */
     min?: Date;
+    /** Latest selectable date. */
     max?: Date;
     /** 0 = Sunday, 1 = Monday. Default `0`. */
     weekStartsOn?: 0 | 1;
     /** Quick-select presets shown in a rail beside the calendars. */
     presets?: DateRangePreset[];
+    /** Custom formatter for the displayed value. */
     format?: (d: Date) => string;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /** Show a required asterisk after the label. */
     required?: boolean;
+    /** Inline style applied to the control shell. */
     style?: React__default.CSSProperties;
 }
 /**
@@ -3017,21 +3230,31 @@ declare function DateRangePicker({ value, onChange, label, htmlFor, placeholder,
 interface ColorPickerProps {
     /** Hex string, e.g. `"#0466c8"`. */
     value?: string;
+    /** Fires when the value changes. */
     onChange?: (hex: string) => void;
+    /** Field label, placed above (vertical) or beside (horizontal) the control. */
     label?: React__default.ReactNode;
+    /** The control id; the field label links to it for accessibility. */
     htmlFor?: string;
+    /** Native form field name (used for FormData serialisation). */
     name?: string;
+    /** Label/control orientation: 'horizontal' or 'vertical'. */
     layout?: 'horizontal' | 'vertical';
+    /** Size preset — controls height, padding, and font. Default 'md'. */
     size?: FieldSize;
     /** Preset swatches shown in the popover. Defaults to a balanced 12-color set. */
     swatches?: string[];
     /** Show the native eyedropper / full picker fallback via `<input type="color">`. Default `true`. */
     allowCustom?: boolean;
+    /** Disable interaction and dim the control. */
     disabled?: boolean;
+    /** Validation message — shown under the control; also flags it red and sets aria-invalid. */
     errorMessage?: React__default.ReactNode;
     /** Contextual help revealed via an info icon + tooltip beside the label. */
     helperText?: React__default.ReactNode;
+    /** Show a required asterisk after the label. */
     required?: boolean;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
 }
 /**
@@ -3213,7 +3436,10 @@ interface UseFormReturn {
     isValid: boolean;
     getValue: (name: string) => unknown;
     getValues: () => FormValues;
-    setValue: (name: string, value: unknown) => void;
+    setValue: (name: string, value: unknown, opts?: {
+        validate?: boolean;
+        touch?: boolean;
+    }) => void;
     setValues: (patch: FormValues) => void;
     setError: (name: string, error: string | undefined) => void;
     validateField: (name: string) => Promise<string | undefined>;
@@ -3360,4 +3586,98 @@ declare const FormContext: React$1.Context<FormStore>;
 /** Read the enclosing `<Form>`'s store. Throws if used outside a `<Form>`. */
 declare function useFormStore(): FormStore;
 
-export { AppShell, type AppShellProps, AutoComplete, type AutoCompleteProps, Avatar, type AvatarProps, type AvatarShape, type AvatarSize, type AvatarStatus, Box, type BoxBackground, type BoxBorder, type BoxProps, type BoxRadius, type BoxShadow, Button, type ButtonProps, Catalog, CatalogCarousel, type CatalogCarouselProps, CatalogGrid, type CatalogGridProps, type CatalogProps, Checkbox, type CheckboxProps, ColorPicker, type ColorPickerProps, ContextMenu, type ContextMenuActionItem, type ContextMenuPosition, type ContextMenuProps, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, type DateRangePreset, Drawer, type DrawerProps, Dropdown, type DropdownItem, type DropdownProps, type ErrorMap, type ExpandRowOptions, FadingBase, type FadingBaseProps, Field, type FieldArrayItem, type FieldBindings, FieldHelpIcon, type FieldKind, FieldLabel, type FieldLabelProps, type FieldProps, type FieldRule, type FieldRules, type FieldShellOptions, type FieldSize, type FieldSnapshot, FileInput, type FileInputProps, Flex, type FlexAlign, type FlexDirection, type FlexJustify, type FlexProps, type FlexWrap, Form, FormContext, FormField, type FormFieldProps, type FormProps, FormStore, type FormStoreOptions, type FormValues, Grid, GridCard, type GridCardItem, type GridCardProps, type GridProps, Icon, IconButton, type IconButtonProps, List, type ListItem, type ListProps, LoadingSpinner, type LoadingSpinnerProps, Modal, type ModalProps, type NotificationPayload, NotificationProvider, NumberInput, type NumberInputProps, OpaqueGridCard, type OpaqueGridCardProps, OtpInput, type OtpInputProps, type PaginationOptions, Password, type PasswordProps, Portal, type PortalProps, RadioGroup, type RadioGroupProps, type RadioOption, Rating, type RatingProps, type RulesMap, ScalableContainer, type ScalableContainerProps, SearchInput, type SearchInputProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Sidebar, type SidebarItem, type SidebarProps, type SidebarSection, SkeletonBox, type SkeletonBoxProps, SkeletonCard, type SkeletonCardProps, SkeletonCircle, type SkeletonCircleProps, SkeletonText, type SkeletonTextProps, Slider, type SliderMark, type SliderProps, type SliderValue, type Spacing, Switch, type SwitchInputProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, TagsInput, type TagsInputProps, DatePicker as Temporal, type TemporalPickerProps, TextArea, type TextAreaProps, TextInput, type TextInputProps, type ThemeColors, type ThemeConfig, type ThemeDensity, type ThemeMotion, ThemeProvider, type ThemeProviderProps, type ThemeRadius, type ThemeShadows, ThemeSwitch, type ThemeSwitchProps, type ThemeTypography, TimePicker, type TimePickerProps, Tooltip, type TooltipProps, TooltipProvider, TopBar, type TopBarProps, Tree, type TreeItemClickPayload, type TreeNode, type TreeProps, TreeSelect, type TreeSelectProps, Typography, type TypographyAlign, type TypographyColor, type TypographyProps, type TypographyVariant, type TypographyWeight, type UseFieldArrayReturn, type UseFormFieldOptions, type UseFormReturn, type ValidateTrigger, Wizard, type WizardProps, type WizardStep, fieldShell, isRequired, patterns, runFieldRules, useFieldArray, useForm, useFormField, useFormStore, useNotification };
+/** The normalised value emitted on change / submit. */
+interface CreditCardValue {
+    /** Digits only (no spaces). */
+    number: string;
+    /** Cardholder name. */
+    name: string;
+    /** `MM/YY`. */
+    expiry: string;
+    /** Digits only. */
+    cvv: string;
+    /** Detected brand id (`'visa'`, `'amex'`…) or `null`. */
+    brand: string | null;
+}
+interface CreditCardFormProps {
+    /** Called with the validated card once every field passes on submit. */
+    onSubmit?: (card: CreditCardValue) => void | Promise<void>;
+    /** Called on every keystroke with the current (possibly invalid) card. */
+    onChange?: (card: CreditCardValue) => void;
+    /** Seed the fields (uncontrolled). Number/expiry are auto-formatted. */
+    defaultValue?: Partial<CreditCardValue>;
+    /** Size preset for the inner fields. Default `'md'`. */
+    size?: FieldSize;
+    /** Disable every field + the submit button. */
+    disabled?: boolean;
+    /** Require the cardholder name. Default `true`. */
+    requireName?: boolean;
+    /** Hide the built-in submit button (when embedding in a larger form). */
+    hideSubmit?: boolean;
+    /** Submit button label. Default `'Pay'`. */
+    submitLabel?: React__default.ReactNode;
+    /** Extra classes on the root `<form>`. */
+    className?: string;
+    /** Inline style on the root `<form>`. */
+    style?: React__default.CSSProperties;
+}
+/**
+ * Unified credit-card form built on the oxygen-ui {@link useForm} Form API.
+ *
+ * One component owns all four fields and their cross-field rules — card number
+ * (brand detection + grouping + Luhn), expiry (`MM/YY`, real month, not past),
+ * CVV (brand-aware length), and cardholder name. It is deliberately NOT shipped
+ * as separate inputs: a CVV or expiry field has no meaning outside a card form.
+ *
+ * Self-contained: render it and handle `onSubmit(card)`; the card is only
+ * delivered once everything validates. Use `onChange` for live updates (e.g. a
+ * card preview) and `hideSubmit` to embed it inside a larger form.
+ *
+ * @example
+ * <CreditCardForm onSubmit={(card) => pay(card)} submitLabel="Pay $49" />
+ */
+declare function CreditCardForm({ onSubmit, onChange, defaultValue, size, disabled, requireName, hideSubmit, submitLabel, className, style, }: CreditCardFormProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Zero-dependency credit-card helpers: brand detection, Luhn checksum, and
+ * display formatting. Pure functions — no React, no deps — so they're unit
+ * testable and reusable.
+ */
+interface CardBrand {
+    /** Stable id, e.g. `'visa'`. */
+    id: string;
+    /** Human label, e.g. `'Visa'`. */
+    label: string;
+    /** Short badge text, e.g. `'VISA'`. */
+    short: string;
+    /** Accent colour for the brand badge (hex). */
+    color: string;
+    /** Matches the leading digits of the card number. */
+    pattern: RegExp;
+    /** Valid total digit lengths for this brand. */
+    lengths: number[];
+    /** Expected CVV length (3 for most, 4 for Amex). */
+    cvv: number;
+    /** Zero-based digit indices to insert a space before (grouping). */
+    gaps: number[];
+}
+/** Recognised brands, in match-priority order. */
+declare const CARD_BRANDS: CardBrand[];
+/** Strip everything but digits. */
+declare const onlyDigits: (s: string) => string;
+/** Detect the card brand from a (possibly partial) number. `null` if unknown. */
+declare function detectBrand(value: string): CardBrand | null;
+/** Luhn (mod-10) checksum — the standard card-number integrity check. */
+declare function luhnValid(value: string): boolean;
+/** Format a card number with brand-aware grouping (e.g. `4242 4242 4242 4242`). */
+declare function formatCardNumber(value: string): string;
+/** Validate a card number: known brand, complete length, passing Luhn. */
+declare function cardNumberError(value: string): string | undefined;
+/** Format expiry keystrokes into `MM/YY`, auto-padding the month and slashing. */
+declare function formatExpiry(value: string): string;
+/** Validate `MM/YY`: well-formed, real month, not in the past. */
+declare function expiryError(value: string, now?: Date): string | undefined;
+/** Validate the CVV against the detected brand's expected length. */
+declare function cvvError(value: string, cardNumber: string): string | undefined;
+
+export { AppShell, type AppShellProps, AutoComplete, type AutoCompleteProps, Avatar, type AvatarProps, type AvatarShape, type AvatarSize, type AvatarStatus, Box, type BoxBackground, type BoxBorder, type BoxProps, type BoxRadius, type BoxShadow, Button, type ButtonProps, CARD_BRANDS, type CardBrand, Catalog, CatalogCarousel, type CatalogCarouselProps, CatalogGrid, type CatalogGridProps, type CatalogProps, Checkbox, type CheckboxProps, ColorPicker, type ColorPickerProps, ContextMenu, type ContextMenuActionItem, type ContextMenuPosition, type ContextMenuProps, CreditCardForm, type CreditCardFormProps, type CreditCardValue, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, type DateRangePreset, Drawer, type DrawerProps, Dropdown, type DropdownItem, type DropdownProps, type ErrorMap, type ExpandRowOptions, FadingBase, type FadingBaseProps, Field, type FieldArrayItem, type FieldBindings, FieldHelpIcon, type FieldKind, FieldLabel, type FieldLabelProps, type FieldProps, type FieldRule, type FieldRules, type FieldShellOptions, type FieldSize, type FieldSnapshot, FileInput, type FileInputProps, Flex, type FlexAlign, type FlexDirection, type FlexJustify, type FlexProps, type FlexWrap, Form, FormContext, FormField, type FormFieldProps, type FormProps, FormStore, type FormStoreOptions, type FormValues, Grid, GridCard, type GridCardItem, type GridCardProps, type GridProps, Icon, IconButton, type IconButtonProps, List, type ListItem, type ListProps, LoadingSpinner, type LoadingSpinnerProps, Modal, type ModalProps, type NotificationPayload, NotificationProvider, NumberInput, type NumberInputProps, OpaqueGridCard, type OpaqueGridCardProps, OtpInput, type OtpInputProps, type PaginationOptions, Password, type PasswordProps, Portal, type PortalProps, RadioGroup, type RadioGroupProps, type RadioOption, Rating, type RatingProps, type RulesMap, ScalableContainer, type ScalableContainerProps, SearchInput, type SearchInputProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Sidebar, type SidebarItem, type SidebarProps, type SidebarSection, SkeletonBox, type SkeletonBoxProps, SkeletonCard, type SkeletonCardProps, SkeletonCircle, type SkeletonCircleProps, SkeletonText, type SkeletonTextProps, Slider, type SliderMark, type SliderProps, type SliderValue, type Spacing, Switch, type SwitchInputProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, TagsInput, type TagsInputProps, DatePicker as Temporal, type TemporalPickerProps, TextArea, type TextAreaProps, TextInput, type TextInputProps, type ThemeColors, type ThemeConfig, type ThemeDensity, type ThemeMotion, ThemeProvider, type ThemeProviderProps, type ThemeRadius, type ThemeShadows, ThemeSwitch, type ThemeSwitchProps, type ThemeTypography, TimePicker, type TimePickerProps, Tooltip, type TooltipProps, TooltipProvider, TopBar, type TopBarProps, Tree, type TreeItemClickPayload, type TreeNode, type TreeProps, TreeSelect, type TreeSelectProps, Typography, type TypographyAlign, type TypographyColor, type TypographyProps, type TypographyVariant, type TypographyWeight, type UseFieldArrayReturn, type UseFormFieldOptions, type UseFormReturn, type ValidateTrigger, Wizard, type WizardProps, type WizardStep, cardNumberError, cvvError, detectBrand, expiryError, fieldShell, formatCardNumber, formatExpiry, isRequired, luhnValid, onlyDigits, patterns, runFieldRules, useFieldArray, useForm, useFormField, useFormStore, useNotification };