@ansh-ui/react 0.2.0

package/dist/form.d.cts

@@ -0,0 +1,660 @@
+import * as react from 'react';
+import { ReactNode, InputHTMLAttributes, TextareaHTMLAttributes } from 'react';
+
+/**
+ * The label / description / error scaffolding every form control shares.
+ *
+ * Wiring this by hand is where forms lose their accessibility. The control needs `id` matching the
+ * label's `htmlFor`, `aria-describedby` pointing at *both* the hint and the error, and
+ * `aria-invalid` when it's wrong. Six attributes across four elements, per field — so in practice
+ * some fields get it and some don't.
+ *
+ * `Field` generates the ids and distributes them through context, so a control only has to spread
+ * what `useFieldControl()` returns.
+ *
+ * ```tsx
+ * <Field label="Work email" description="We'll never share it." error={errors.email}>
+ *   <Input type="email" value={email} onChange={…} />
+ * </Field>
+ * ```
+ */
+interface FieldContextValue {
+    id: string;
+    describedBy: string | undefined;
+    invalid: boolean;
+    required: boolean;
+    disabled: boolean;
+}
+/**
+ * Props a control should spread onto its interactive element.
+ *
+ * Returns an empty object outside a `Field`, so every control works standalone — a control that
+ * throws without a wrapper is a control people stop using.
+ */
+declare function useFieldControl(): {
+    id?: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: true;
+    'aria-required'?: true;
+    disabled?: boolean;
+};
+/** The raw context, for controls that need the ids rather than the spreadable props. */
+declare function useFieldContext(): FieldContextValue | null;
+interface FieldProps {
+    label?: ReactNode;
+    /** Helper text below the label. Announced as part of the control's description. */
+    description?: ReactNode;
+    /** Error message. Its presence sets `aria-invalid` on the control. */
+    error?: ReactNode;
+    /** Marks the field required and appends an asterisk to the label. */
+    required?: boolean;
+    disabled?: boolean;
+    /** Label to the side rather than above — denser, for settings screens. */
+    orientation?: 'vertical' | 'horizontal';
+    className?: string;
+    children: ReactNode;
+}
+declare function Field({ label, description, error, required, disabled, orientation, className, children, }: FieldProps): react.JSX.Element;
+interface FieldsetProps {
+    legend: ReactNode;
+    description?: ReactNode;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * A group of related fields.
+ *
+ * A real `<fieldset>`/`<legend>`, because that pairing is what makes a screen reader announce the
+ * group name before each control inside it. A styled `<div>` with a heading looks identical and
+ * conveys nothing.
+ */
+declare function Fieldset({ legend, description, className, children }: FieldsetProps): react.JSX.Element;
+/**
+ * Visually hidden, still announced.
+ *
+ * The clip-path technique rather than `display: none` or `visibility: hidden`, both of which
+ * remove the element from the accessibility tree entirely — which is the opposite of the intent.
+ */
+declare function VisuallyHidden({ children, ...rest }: {
+    children: ReactNode;
+} & React.HTMLAttributes<HTMLSpanElement>): react.JSX.Element;
+
+type InputSize = 'sm' | 'md' | 'lg';
+interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'prefix'> {
+    size?: InputSize;
+    /** Content inside the field, before the text — an icon or a currency symbol. */
+    prefix?: ReactNode;
+    /** Content inside the field, after the text — a unit, or a button. */
+    suffix?: ReactNode;
+    /** Show a clear button when non-empty. */
+    clearable?: boolean;
+    onClear?: () => void;
+    /** Force the error style outside a `Field`. */
+    invalid?: boolean;
+    className?: string;
+    /** Class for the outer wrapper, when there is a prefix or suffix. */
+    wrapperClassName?: string;
+}
+/**
+ * A text input.
+ *
+ * The affordance most inputs get wrong is the click target: with an icon inside the field, clicking
+ * the icon should focus the input. That works here because the wrapper forwards the click, rather
+ * than the icon being an absolutely positioned sibling that swallows it.
+ */
+declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
+interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Grow with the content instead of scrolling. */
+    autoResize?: boolean;
+    /** Upper bound for `autoResize`, in rows. Default `12`. */
+    maxRows?: number;
+    /** Show a live character count. Needs `maxLength` to show a limit. */
+    showCount?: boolean;
+    invalid?: boolean;
+}
+/** A multi-line text input, optionally growing with its content. */
+declare const Textarea: react.ForwardRefExoticComponent<TextareaProps & react.RefAttributes<HTMLTextAreaElement>>;
+interface NumberInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'size' | 'type'> {
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Decimal places to display. Default: inferred from `step`. */
+    precision?: number;
+    size?: InputSize;
+    /** Unit shown after the number — "kg", "%", "days". */
+    unit?: ReactNode;
+    /** Show the stepper buttons. Default `true`. */
+    steppers?: boolean;
+}
+/**
+ * A numeric input with steppers.
+ *
+ * Deliberately `type="text"` with `inputMode="decimal"` rather than `type="number"`. Native number
+ * inputs silently discard invalid intermediate text (typing "1e" clears the field), scroll-wheel
+ * over a focused field changes the value by accident, and the spinner cannot be styled
+ * consistently across browsers. All three are real bugs users hit on data-entry screens.
+ */
+declare const NumberInput: react.ForwardRefExoticComponent<NumberInputProps & react.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Binary and single-choice controls.
+ *
+ * All three wrap a **real** `<input>` rather than painting a div. That decision carries a lot:
+ * form submission works, `:checked` styling works, the label association works, autofill works,
+ * password managers and browser translation work, and every assistive technology already knows what
+ * the control is. The visual is a sibling element the input drives via `:checked + .indicator`.
+ *
+ * The input is not `display: none` — that removes it from the accessibility tree and the tab order.
+ * It is transparent and stretched over the control, so it stays focusable and clickable.
+ */
+interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange' | 'size'> {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+    /** Neither checked nor unchecked — a parent whose children are partly selected. */
+    indeterminate?: boolean;
+    label?: ReactNode;
+    description?: ReactNode;
+    size?: 'sm' | 'md';
+    invalid?: boolean;
+}
+declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.RefAttributes<HTMLInputElement>>;
+interface SwitchProps extends Omit<CheckboxProps, 'indeterminate'> {
+    /** Where the label sits. Default `'end'`; `'start'` suits settings rows. */
+    labelPosition?: 'start' | 'end';
+}
+/**
+ * An on/off toggle.
+ *
+ * `role="switch"` rather than a plain checkbox: it makes a screen reader announce "on"/"off"
+ * instead of "checked"/"not checked", which is the difference between a setting and a selection.
+ *
+ * A switch applies immediately; a checkbox applies on submit. If the change needs a Save button,
+ * the control should be a checkbox.
+ */
+declare const Switch: react.ForwardRefExoticComponent<SwitchProps & react.RefAttributes<HTMLInputElement>>;
+interface RadioGroupProps {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    /** Shared `name`. Generated when omitted, which is fine outside a native form. */
+    name?: string;
+    label?: ReactNode;
+    orientation?: 'vertical' | 'horizontal';
+    disabled?: boolean;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * A group of mutually exclusive choices.
+ *
+ * Native radios already implement roving focus: arrow keys move between them and Tab enters and
+ * leaves the group as a unit. That behaviour is free as long as every input shares a `name`, which
+ * is what this context distributes — and it is why this doesn't reimplement key handling.
+ */
+declare function RadioGroup({ value, defaultValue, onChange, name, label, orientation, disabled, className, children, }: RadioGroupProps): react.JSX.Element;
+interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange' | 'size'> {
+    value: string;
+    label?: ReactNode;
+    description?: ReactNode;
+    size?: 'sm' | 'md';
+}
+declare const Radio: react.ForwardRefExoticComponent<RadioProps & react.RefAttributes<HTMLInputElement>>;
+interface ChoiceCardProps extends RadioProps {
+    icon?: ReactNode;
+}
+/**
+ * A radio rendered as a selectable card — plan pickers, onboarding branches.
+ *
+ * Still a radio underneath, so keyboard and screen-reader behaviour is identical to the plain one.
+ * Selection is marked by a border *and* a check, never colour alone: WCAG 1.4.1 requires that
+ * colour not be the sole carrier of information, and roughly 1 in 12 men cannot rely on it.
+ */
+declare const ChoiceCard: react.ForwardRefExoticComponent<ChoiceCardProps & react.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Shared machinery for `Select` and `Combobox`.
+ *
+ * Both are listboxes: same option shape, same grouping, same active-descendant navigation, same
+ * "skip disabled items" rule. What differs is only how the query is entered — a hidden typeahead
+ * buffer versus a visible text input. Sharing this is what keeps the two consistent; the
+ * alternative is a `Select` whose Home key works and a `Combobox` whose doesn't.
+ */
+interface SelectOption {
+    value: string;
+    label: string;
+    /** Secondary line under the label. */
+    description?: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+    /** Options sharing a group render under one heading. */
+    group?: string;
+    /** Extra text matched by search but never displayed. */
+    keywords?: string;
+}
+/** Move `active` by `delta`, skipping disabled options and stopping at the ends. */
+declare function stepActive(options: readonly SelectOption[], active: number, delta: number, loop?: boolean): number;
+/** First enabled option at or after `from`. */
+declare function firstEnabled(options: readonly SelectOption[], from?: number): number;
+/**
+ * Type-ahead over a listbox with no text input.
+ *
+ * Typing "ca" jumps to "Canada". The buffer resets after a pause, so typing "c", waiting, then "a"
+ * moves to the first "c" and then the first "a" — which is what the native `<select>` does and what
+ * users have internalised over three decades.
+ */
+declare function useTypeahead(options: readonly SelectOption[], onMatch: (index: number) => void, timeout?: number): (key: string) => boolean;
+/**
+ * Subsequence match with a relevance score. `-1` means no match.
+ *
+ * Subsequence rather than substring because that is what users of a modern picker expect: typing
+ * "nds" should find "**N**ew **D**ata**s**ource".
+ */
+declare function scoreOption(query: string, option: SelectOption): number;
+/** Filter and rank options against a query, preserving order when the query is empty. */
+declare function filterOptions(options: readonly SelectOption[], query: string): readonly SelectOption[];
+interface OptionListProps {
+    options: readonly SelectOption[];
+    active: number;
+    selected: readonly string[];
+    listId: string;
+    multiple?: boolean;
+    emptyMessage?: ReactNode;
+    onSelect: (option: SelectOption) => void;
+    onActiveChange: (index: number) => void;
+    /** Highlight the matched characters. */
+    query?: string;
+}
+/** Render the option rows, with group headings emitted on change. */
+declare function OptionList({ options, active, selected, listId, multiple, emptyMessage, onSelect, onActiveChange, query, }: OptionListProps): react.JSX.Element;
+
+interface SelectProps {
+    options: readonly SelectOption[];
+    value?: string | null;
+    defaultValue?: string | null;
+    onChange?: (value: string | null) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    invalid?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+    /** Show a clear button once something is selected. */
+    clearable?: boolean;
+    /** Accessible name when there is no wrapping `Field`. */
+    label?: string;
+    className?: string;
+    /** Emit a hidden input so the value posts in a native form submit. */
+    name?: string;
+    /** Max height of the popup before it scrolls. Default `'18rem'`. */
+    maxHeight?: string;
+    emptyMessage?: ReactNode;
+}
+/**
+ * A single-choice select.
+ *
+ * Follows the ARIA 1.2 collapsed-listbox pattern: the trigger is a `button` with
+ * `aria-haspopup="listbox"`, and while open, focus moves to the listbox with a virtual cursor
+ * carried by `aria-activedescendant`.
+ *
+ * A custom select is only justified when the native one can't do the job — option descriptions,
+ * icons, grouping with custom rendering. When a plain list of strings will do, `<select>` is still
+ * better: it gets the platform's own picker on mobile, which no custom implementation matches.
+ * This exists because CRM and admin screens genuinely need the richer version.
+ */
+declare function Select({ options, value, defaultValue, onChange, placeholder, disabled, invalid, size, clearable, label, className, name, maxHeight, emptyMessage, }: SelectProps): react.JSX.Element;
+
+interface ComboboxProps {
+    options: readonly SelectOption[];
+    /** Selected values. Single-select uses a one-element array. */
+    value?: readonly string[];
+    defaultValue?: readonly string[];
+    onChange?: (value: readonly string[]) => void;
+    multiple?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    invalid?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+    label?: string;
+    className?: string;
+    maxHeight?: string;
+    emptyMessage?: ReactNode;
+    /** Offer the typed text as a new option. Returns the created option's value. */
+    onCreate?: (label: string) => string;
+    /** Text for the create row. Receives the current query. */
+    createLabel?: (query: string) => string;
+    /** Override filtering entirely — for server-side search. */
+    onSearch?: (query: string) => void;
+    /** Skip local filtering, e.g. when `onSearch` already returns filtered options. */
+    filter?: boolean;
+    /** Cap on how many chips render before collapsing to "+N". Default `Infinity`. */
+    maxVisibleChips?: number;
+}
+/**
+ * A searchable select, single or multiple.
+ *
+ * This is the ARIA 1.2 combobox pattern, and the distinguishing detail is that **focus never leaves
+ * the input**. Arrow keys move a virtual cursor announced through `aria-activedescendant`, so the
+ * user can keep typing to narrow the list while navigating it. Implementations that move DOM focus
+ * into the list break that: the next keystroke goes to the list, not the query.
+ *
+ * ```tsx
+ * <Combobox multiple options={owners} value={selected} onChange={setSelected} />
+ * ```
+ */
+declare function Combobox({ options, value, defaultValue, onChange, multiple, placeholder, disabled, invalid, size, label, className, maxHeight, emptyMessage, onCreate, createLabel, onSearch, filter, maxVisibleChips, }: ComboboxProps): react.JSX.Element;
+
+interface SliderMark {
+    value: number;
+    label?: ReactNode;
+}
+interface SliderProps {
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
+    /** Fired once on release — for the expensive work a live `onChange` shouldn't trigger. */
+    onCommit?: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    disabled?: boolean;
+    /** Vertical sliders are for mixers and volume; default is horizontal. */
+    orientation?: 'horizontal' | 'vertical';
+    marks?: readonly SliderMark[];
+    /** Show the value in a bubble above the thumb while dragging. */
+    showValue?: boolean | 'always';
+    /** Format the bubble and the screen-reader announcement. */
+    formatValue?: (value: number) => string;
+    label?: string;
+    className?: string;
+    name?: string;
+}
+/**
+ * A single-value slider.
+ *
+ * The thumb is the focusable element and carries `role="slider"` with the full value triple, so a
+ * screen reader announces "40, slider, minimum 0, maximum 100". Dragging writes the position
+ * straight to a CSS custom property and only commits to React state on release — a re-render per
+ * pointer move is what makes hand-rolled sliders feel sticky.
+ */
+declare function Slider({ value, defaultValue, onChange, onCommit, min, max, step, disabled, orientation, marks, showValue, formatValue, label, className, name, }: SliderProps): react.JSX.Element;
+interface RangeSliderProps extends Omit<SliderProps, 'value' | 'defaultValue' | 'onChange' | 'onCommit' | 'name'> {
+    value?: readonly [number, number];
+    defaultValue?: readonly [number, number];
+    onChange?: (value: readonly [number, number]) => void;
+    onCommit?: (value: readonly [number, number]) => void;
+    /** Smallest allowed gap between the two thumbs. Default `0`. */
+    minDistance?: number;
+}
+/**
+ * A two-thumb range slider — price filters, date windows, numeric facets.
+ *
+ * The thumbs are allowed to pass each other, swapping roles when they do. Blocking the crossing is
+ * the more common implementation and it is worse: a user dragging the lower thumb to the right
+ * hits an invisible wall and has to work out that they need to grab the other one instead.
+ */
+declare function RangeSlider({ value, defaultValue, onChange, onCommit, min, max, step, minDistance, disabled, marks, showValue, formatValue, label, className, }: RangeSliderProps): react.JSX.Element;
+
+interface PinInputProps {
+    /** Number of cells. Default `6`. */
+    length?: number;
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    /** Fired when every cell is filled — wire the verification call here. */
+    onComplete?: (value: string) => void;
+    /** Restrict input. Default `'numeric'`. */
+    type?: 'numeric' | 'alphanumeric';
+    /** Render as password dots. */
+    mask?: boolean;
+    disabled?: boolean;
+    invalid?: boolean;
+    autoFocus?: boolean;
+    label?: string;
+    className?: string;
+}
+/**
+ * A one-time-code input.
+ *
+ * The details that make or break this component are all about paste and autofill:
+ *
+ *  - `autoComplete="one-time-code"` on the first cell is what triggers iOS and Android to offer the
+ *    code from the SMS. Without it users retype a six-digit code by hand.
+ *  - Pasting into any cell distributes across all of them. Users paste from their SMS app
+ *    constantly, and a per-cell input that only accepts the first character is infuriating.
+ *  - Backspace on an empty cell moves back *and* clears, so holding it wipes the field.
+ *
+ * A single input styled to look segmented would be simpler, but the caret cannot be positioned per
+ * segment and mobile keyboards behave inconsistently with it.
+ */
+declare function PinInput({ length, value, defaultValue, onChange, onComplete, type, mask, disabled, invalid, autoFocus, label, className, }: PinInputProps): react.JSX.Element;
+
+interface TagsInputProps {
+    value?: readonly string[];
+    defaultValue?: readonly string[];
+    onChange?: (value: readonly string[]) => void;
+    placeholder?: string;
+    /** Maximum number of tags. The input hides once reached. */
+    max?: number;
+    /** Keys that commit the current text. Default Enter, Tab and comma. */
+    delimiters?: readonly string[];
+    /** Reject a value — return an error string, or `null` to accept. */
+    validate?: (value: string) => string | null;
+    /** Fold duplicates silently instead of flagging them. Default `true`. */
+    dedupe?: boolean;
+    disabled?: boolean;
+    invalid?: boolean;
+    label?: string;
+    className?: string;
+}
+/**
+ * Free-text tags — recipients, labels, keywords.
+ *
+ * Distinct from a multi-`Combobox`: there is no option list, any text is valid. The two are often
+ * conflated, and the giveaway is a "tags" component that forces you to pick from a list.
+ *
+ * Each tag is a real button so it can be reached with Tab and removed with Enter. Removing a tag
+ * moves focus to the next one rather than to the document, which is what stops keyboard users
+ * losing their place after deleting three in a row.
+ */
+declare function TagsInput({ value, defaultValue, onChange, placeholder, max, delimiters, validate, dedupe, disabled, invalid, label, className, }: TagsInputProps): react.JSX.Element;
+
+interface RatingProps {
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
+    /** Number of symbols. Default `5`. */
+    max?: number;
+    /** Allow halves. Default `false`. */
+    allowHalf?: boolean;
+    /** Display only — no interaction, no focus. */
+    readOnly?: boolean;
+    disabled?: boolean;
+    size?: 'sm' | 'md' | 'lg';
+    /** Custom symbol. Defaults to a star. */
+    icon?: ReactNode;
+    label?: string;
+    className?: string;
+    name?: string;
+}
+/**
+ * A star rating.
+ *
+ * Interactive ratings are a **radio group**, not a set of buttons: exactly one of N is chosen, which
+ * is what a radio group means, and it gets arrow-key navigation and correct announcements for free.
+ * Read-only ratings are `role="img"` with a text label instead — "4.2 out of 5" is the entire
+ * content, and exposing five separate radios that can't be changed is noise.
+ */
+declare function Rating({ value, defaultValue, onChange, max, allowHalf, readOnly, disabled, size, icon, label, className, name, }: RatingProps): react.JSX.Element;
+
+interface DropzoneFile {
+    file: File;
+    id: string;
+    /** Object URL for image previews. Revoked automatically on removal. */
+    preview?: string;
+    error?: string;
+}
+interface DropzoneProps {
+    onFiles?: (files: readonly DropzoneFile[]) => void;
+    /** `accept` attribute, e.g. `'image/*,.pdf'`. */
+    accept?: string;
+    multiple?: boolean;
+    /** Per-file size cap, in bytes. */
+    maxSize?: number;
+    /** Maximum number of files. */
+    maxFiles?: number;
+    disabled?: boolean;
+    /** Show thumbnails for images. Default `true`. */
+    previews?: boolean;
+    label?: ReactNode;
+    hint?: ReactNode;
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * A file dropzone with previews and validation.
+ *
+ * Two things distinguish a working dropzone from a broken one:
+ *
+ *  1. **Drag counting.** `dragleave` fires when the pointer crosses onto a *child* element, so the
+ *     naive implementation flickers the highlight constantly while you move across it. A depth
+ *     counter incremented on enter and decremented on leave fixes it.
+ *  2. **A real `<input type="file">` underneath.** Drag-and-drop is unusable with a keyboard, a
+ *     screen reader, or on a phone. The input is the actual control; the drop surface is an
+ *     enhancement layered on top.
+ *
+ * Object URLs are revoked when a file is removed. Skipping that leaks the entire file into memory
+ * for the page's lifetime, which is invisible in testing and obvious after a user uploads forty
+ * photos.
+ */
+declare function Dropzone({ onFiles, accept, multiple, maxSize, maxFiles, disabled, previews, label, hint, className, children, }: DropzoneProps): react.JSX.Element;
+
+interface ColorPickerProps {
+    /** Any CSS colour — hex, rgb, hsl, oklch, or a named colour. */
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    /** Output format. Default `'hex'`. */
+    format?: 'hex' | 'rgb' | 'hsl' | 'oklch';
+    /** Show the alpha slider. Default `false`. */
+    alpha?: boolean;
+    /** Swatches shown under the picker. */
+    presets?: readonly string[];
+    /** Report the contrast ratio against this colour, live. */
+    contrastAgainst?: string;
+    disabled?: boolean;
+    label?: string;
+    className?: string;
+}
+/**
+ * A colour picker built on the engine's colour system.
+ *
+ * The saturation/value plane, hue rail and alpha rail are the conventional layout. What's less
+ * conventional, and the reason this is worth shipping over a generic picker:
+ *
+ *  - **It speaks every format the engine does.** Paste `oklch(62% 0.2 264)` into the text field and
+ *    it parses. Most pickers accept hex and nothing else.
+ *  - **It can report contrast live.** On a theme editor — which is what colour pickers in admin
+ *    tools are usually for — picking a brand colour without seeing that it fails WCAG against your
+ *    background is how inaccessible products get built one reasonable decision at a time.
+ *
+ * State is held as HSV, not as the output string. Round-tripping through hex on every pointer move
+ * loses information: dragging into the black corner would discard the hue, so releasing and
+ * dragging back out returns red instead of the colour you started from.
+ */
+declare function ColorPicker({ value, defaultValue, onChange, format, alpha, presets, contrastAgainst, disabled, label, className, }: ColorPickerProps): react.JSX.Element;
+
+/**
+ * A month calendar.
+ *
+ * Dates are plain `Date` objects normalised to local midnight. No date library: the whole surface
+ * this needs is "add days", "same day?" and "days in month", and pulling in a 70 KB dependency for
+ * that is how component libraries end up heavier than the app using them.
+ *
+ * Local midnight, specifically. Working in UTC makes a date shift by a day for anyone west of
+ * Greenwich — the bug where a birthday saved on the 14th displays as the 13th, which is the single
+ * most reported issue in every date picker ever shipped.
+ *
+ * Keyboard support is the WAI-ARIA date grid pattern: arrows by day, PageUp/PageDown by month,
+ * Shift+PageUp/PageDown by year, Home/End to the week's ends. A calendar without these is
+ * mouse-only, and entering a date of birth by clicking back 300 months is not a real option.
+ */
+/** Strip the time, in local time. */
+declare function startOfDay(date: Date): Date;
+declare function addDays(date: Date, days: number): Date;
+declare function addMonths(date: Date, months: number): Date;
+declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
+type DateRange = {
+    start: Date | null;
+    end: Date | null;
+};
+interface CalendarProps {
+    /** `'single'` picks one date; `'range'` picks a start and an end. */
+    mode?: 'single' | 'range';
+    value?: Date | null | DateRange;
+    defaultValue?: Date | null | DateRange;
+    onChange?: (value: Date | null | DateRange) => void;
+    min?: Date;
+    max?: Date;
+    /** Disable specific dates — weekends, holidays, booked days. */
+    isDateDisabled?: (date: Date) => boolean;
+    /** 0 = Sunday, 1 = Monday. Default: inferred from the locale. */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    locale?: string;
+    /** Months shown side by side. Default `1`; `2` suits range pickers. */
+    months?: number;
+    /** Show ISO week numbers down the left. */
+    showWeekNumbers?: boolean;
+    className?: string;
+}
+declare function Calendar({ mode, value, defaultValue, onChange, min, max, isDateDisabled, weekStartsOn, locale, months, showWeekNumbers, className, }: CalendarProps): react.JSX.Element;
+
+interface DatePickerProps extends Omit<CalendarProps, 'value' | 'defaultValue' | 'onChange' | 'mode' | 'className'> {
+    value?: Date | null;
+    defaultValue?: Date | null;
+    onChange?: (value: Date | null) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    invalid?: boolean;
+    /** Show a clear button once a date is chosen. */
+    clearable?: boolean;
+    /** Format the displayed date. Defaults to the locale's medium date. */
+    format?: (date: Date) => string;
+    label?: string;
+    className?: string;
+    name?: string;
+}
+/**
+ * A date field with a calendar popover.
+ *
+ * The text input is editable, not just a display. Typing "14/03/2026" is faster than clicking
+ * through a calendar for anyone who knows the date they want, and a picker that forces the calendar
+ * is a picker people complain about. The calendar is the fallback for "some Thursday next month",
+ * which is the case typing can't serve.
+ *
+ * Parsing is deliberately forgiving of separators and order within a locale, but never guesses
+ * between `03/04` as March 4th and April 3rd — it follows the locale's own order. Guessing is how
+ * date fields silently record the wrong day.
+ */
+declare function DatePicker({ value, defaultValue, onChange, placeholder, disabled, invalid, clearable, format, label, className, name, locale, ...calendarProps }: DatePickerProps): react.JSX.Element;
+interface DateRangePickerProps extends Omit<CalendarProps, 'value' | 'defaultValue' | 'onChange' | 'mode' | 'className'> {
+    value?: DateRange;
+    defaultValue?: DateRange;
+    onChange?: (value: DateRange) => void;
+    disabled?: boolean;
+    invalid?: boolean;
+    label?: string;
+    className?: string;
+    /** Months shown side by side. Default `2`. */
+    months?: number;
+}
+/**
+ * A start/end date range.
+ *
+ * Two months by default: choosing a range that crosses a month boundary with one month visible
+ * means paging back and forth to compare, which is where users lose track of what they picked.
+ */
+declare function DateRangePicker({ value, defaultValue, onChange, disabled, invalid, label, className, months, locale, ...calendarProps }: DateRangePickerProps): react.JSX.Element;
+
+export { Calendar, type CalendarProps, Checkbox, type CheckboxProps, ChoiceCard, type ChoiceCardProps, ColorPicker, type ColorPickerProps, Combobox, type ComboboxProps, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, Dropzone, type DropzoneFile, type DropzoneProps, Field, type FieldContextValue, type FieldProps, Fieldset, type FieldsetProps, Input, type InputProps, type InputSize, NumberInput, type NumberInputProps, OptionList, type OptionListProps, PinInput, type PinInputProps, Radio, RadioGroup, type RadioGroupProps, type RadioProps, RangeSlider, type RangeSliderProps, Rating, type RatingProps, Select, type SelectOption, type SelectProps, Slider, type SliderMark, type SliderProps, Switch, type SwitchProps, TagsInput, type TagsInputProps, Textarea, type TextareaProps, VisuallyHidden, addDays, addMonths, filterOptions, firstEnabled, isSameDay, scoreOption, startOfDay, stepActive, useFieldContext, useFieldControl, useTypeahead };