@ceebee/ui 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,932 @@
+import * as react from 'react';
+import { ReactNode, ButtonHTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, ReactElement } from 'react';
+import * as _base_ui_react from '@base-ui/react';
+
+/**
+ * Every string the library says out loud. They are here rather than inline because a component
+ * that hard-codes "Previous slide" is an English component, and this library is used to build
+ * products that are not in English.
+ */
+interface Labels {
+    dismiss: string;
+    close: string;
+    clear: string;
+    open: string;
+    previousSlide: string;
+    nextSlide: string;
+    /** Given the 1-based slide number. */
+    goToSlide: (index: number) => string;
+    previousPage: string;
+    nextPage: string;
+    page: (index: number) => string;
+    /** Given the range shown and the total, e.g. "1–20 of 137". */
+    pageSummary: (from: number, to: number, total: number) => string;
+    chooseDate: string;
+    chooseTime: string;
+    previousMonth: string;
+    nextMonth: string;
+    chooseFiles: string;
+    chooseFile: string;
+    dropFilesHere: string;
+    dropFileHere: string;
+    removeFile: (name: string) => string;
+    increase: string;
+    decrease: string;
+    expandNavigation: string;
+    collapseNavigation: string;
+    /** Tour buttons. A Tour's own `labels` prop still wins over these. */
+    back: string;
+    next: string;
+    done: string;
+    skip: string;
+    /** Coachmark and Checklist progress, e.g. "2 of 5". */
+    progress: (current: number, total: number) => string;
+}
+declare const DEFAULT_LABELS: Labels;
+interface LabelsProviderProps {
+    children: ReactNode;
+    /** Only the strings you are replacing; the rest fall back to English. */
+    labels: Partial<Labels>;
+}
+declare function LabelsProvider({ children, labels }: LabelsProviderProps): react.JSX.Element;
+declare function useLabels(): Labels;
+
+type SpringPreset = 'snappy' | 'soft' | 'bouncy';
+type DurationToken = 'instant' | 'fast' | 'base' | 'slow' | 'deliberate';
+interface MotionSettings {
+    /** False when the app disabled motion or the user asked for reduced motion. */
+    enabled: boolean;
+    /** Multiplier on every duration. 0 is equivalent to disabled. */
+    scale: number;
+}
+interface MotionProviderProps {
+    children: ReactNode;
+    /** App-level off switch — for a settings toggle, or for tests. */
+    enabled?: boolean;
+    scale?: number;
+}
+/**
+ * The one place animation is scaled or switched off, and the seam that honours
+ * `prefers-reduced-motion` (ADR 0004). Reduced motion means transforms drop and opacity
+ * stays; it never means a state change happens invisibly.
+ */
+declare function MotionProvider({ children, enabled, scale }: MotionProviderProps): react.JSX.Element;
+interface MotionHelpers extends MotionSettings {
+    /** Seconds for a duration token, already scaled. 0 when motion is off. */
+    duration: (token: DurationToken) => number;
+    /** A Motion transition for a spring preset, collapsing to an instant one when off. */
+    spring: (preset?: SpringPreset) => Record<string, unknown>;
+}
+declare function useMotionSettings(): MotionHelpers;
+
+type ThemeChoice = 'light' | 'dark' | 'system';
+interface ThemeState {
+    choice: ThemeChoice;
+    setChoice: (choice: ThemeChoice) => void;
+    /** What is actually rendering right now, once `system` is resolved. */
+    resolved: 'light' | 'dark';
+}
+/**
+ * Colour itself comes from CSS, not from here (ADR 0002) — this only flips `data-theme`
+ * on the document root, so the first paint is already correct without a blocking script
+ * for anyone who never overrides the system setting.
+ */
+declare function ThemeProvider({ children, defaultChoice, persist, }: {
+    children: ReactNode;
+    defaultChoice?: ThemeChoice;
+    persist?: boolean;
+}): react.JSX.Element;
+declare function useTheme(): ThemeState;
+
+type Tone = 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'danger';
+type Size = 'sm' | 'md' | 'lg';
+
+/** Motion redefines the drag and animation event handlers, so the DOM versions are dropped
+ *  rather than silently conflicting. A button that needs HTML5 drag is not this component. */
+type NativeButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'color' | 'onDrag' | 'onDragStart' | 'onDragEnd' | 'onAnimationStart' | 'onAnimationEnd' | 'onAnimationIteration'>;
+interface ButtonProps extends NativeButtonProps {
+    variant?: 'solid' | 'soft' | 'outline' | 'ghost';
+    tone?: Tone;
+    size?: Size;
+    /** Shown instead of the label, with the button held at its current width. */
+    loading?: boolean;
+    iconStart?: ReactNode;
+    iconEnd?: ReactNode;
+    /** Opts this button out of press feedback without touching the provider. */
+    motion?: boolean;
+}
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface FieldWiring {
+    controlId: string;
+    describedBy: string | undefined;
+    invalid: boolean;
+    required: boolean;
+}
+/** Inputs read their id and aria wiring from here; standalone use returns null. */
+declare function useFieldWiring(): FieldWiring | null;
+interface FieldProps {
+    label: ReactNode;
+    hint?: ReactNode;
+    /** A string renders the message; `true` marks invalid without one. */
+    error?: ReactNode | boolean;
+    required?: boolean;
+    /** Hides the label visually while keeping it for screen readers. */
+    labelHidden?: boolean;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * Label, hint, error, and the `aria-describedby` / `aria-invalid` links between them —
+ * the part that is most often silently wrong. The library owns this and refuses to own
+ * form state or validation (ADR 0011).
+ */
+declare function Field({ label, hint, error, required, labelHidden, className, children }: FieldProps): react.JSX.Element;
+
+interface TextInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    size?: Size;
+    /** Marks invalid when used outside a Field; inside one, the Field decides. */
+    invalid?: boolean;
+}
+declare const TextInput: react.ForwardRefExoticComponent<TextInputProps & react.RefAttributes<HTMLInputElement>>;
+interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    invalid?: boolean;
+}
+declare const Textarea: react.ForwardRefExoticComponent<TextareaProps & react.RefAttributes<HTMLTextAreaElement>>;
+
+interface SelectOption<T extends string = string> {
+    value: T;
+    label: ReactNode;
+    disabled?: boolean;
+}
+interface SelectProps<T extends string = string> {
+    items: Array<SelectOption<T>>;
+    value?: T | null;
+    defaultValue?: T | null;
+    onValueChange?: (value: T) => void;
+    placeholder?: string;
+    size?: Size;
+    disabled?: boolean;
+    invalid?: boolean;
+    name?: string;
+    id?: string;
+    className?: string;
+}
+/**
+ * Listbox behaviour — typeahead, roving focus, scroll containment, form association —
+ * is Base UI's (ADR 0003). This adds the brand and the Field wiring.
+ */
+declare function Select<T extends string = string>({ items, value, defaultValue, onValueChange, placeholder, size, disabled, invalid, name, id, className, }: SelectProps<T>): react.JSX.Element;
+
+interface CheckboxProps {
+    label: ReactNode;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    indeterminate?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    name?: string;
+    value?: string;
+    /** Secondary line under the label — the place for "why would I tick this". */
+    description?: ReactNode;
+    className?: string;
+}
+/** The control and its label are one component: a checkbox whose label is not wired is a bug. */
+declare function Checkbox({ label, checked, defaultChecked, indeterminate, onCheckedChange, disabled, name, value, description, className, }: CheckboxProps): react.JSX.Element;
+interface RadioOption<T extends string = string> {
+    value: T;
+    label: ReactNode;
+    description?: ReactNode;
+    disabled?: boolean;
+}
+interface RadioGroupProps<T extends string = string> {
+    options: Array<RadioOption<T>>;
+    value?: T;
+    defaultValue?: T;
+    onValueChange?: (value: T) => void;
+    name?: string;
+    /** Names the group for assistive technology when it is not inside a Field. */
+    label?: string;
+    direction?: 'column' | 'row';
+    disabled?: boolean;
+    className?: string;
+}
+declare function RadioGroup<T extends string = string>({ options, value, defaultValue, onValueChange, name, label, direction, disabled, className, }: RadioGroupProps<T>): react.JSX.Element;
+interface SwitchProps {
+    label: ReactNode;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    name?: string;
+    description?: ReactNode;
+    /** Label on the left, control on the right — the settings-row arrangement. */
+    justified?: boolean;
+    className?: string;
+}
+/** A Switch applies immediately. If a change needs saving, that is a Checkbox in a form. */
+declare function Switch({ label, checked, defaultChecked, onCheckedChange, disabled, name, description, justified, className, }: SwitchProps): react.JSX.Element;
+
+interface ComboboxOption {
+    value: string;
+    label: string;
+    description?: ReactNode;
+}
+interface ComboboxProps {
+    items: ComboboxOption[];
+    value?: string | null;
+    defaultValue?: string | null;
+    onValueChange?: (value: string | null) => void;
+    placeholder?: string;
+    /** Shown when the query matches nothing. */
+    emptyMessage?: ReactNode;
+    size?: Size;
+    disabled?: boolean;
+    invalid?: boolean;
+    name?: string;
+    className?: string;
+}
+/**
+ * A Select you can type into. Reach for it past roughly a dozen options — below that, scanning a
+ * list is faster than typing, and Select is the simpler component.
+ */
+declare function Combobox({ items, value, defaultValue, onValueChange, placeholder, emptyMessage, size, disabled, invalid, name, className, }: ComboboxProps): react.JSX.Element;
+
+interface DateInputProps {
+    value?: Date | null;
+    defaultValue?: Date | null;
+    onValueChange?: (value: Date | null) => void;
+    min?: Date;
+    max?: Date;
+    /** How the chosen date reads in the field. Defaults to the viewer's locale, medium length. */
+    format?: (date: Date) => string;
+    weekStartsOn?: 0 | 1;
+    size?: Size;
+    disabled?: boolean;
+    invalid?: boolean;
+    placeholder?: string;
+    className?: string;
+}
+/**
+ * Typing and picking, both. Typing is what fast people do and what a date of birth needs; the
+ * calendar is for "the second Tuesday" questions a text field cannot answer.
+ */
+declare function DateInput({ value, defaultValue, onValueChange, min, max, format, weekStartsOn, size, disabled, invalid, placeholder, className, }: DateInputProps): react.JSX.Element;
+
+/** Date arithmetic for the picker. Pure, and dealing only in local calendar days. */
+interface DayCell {
+    date: Date;
+    /** False for the leading and trailing days that belong to the neighbouring months. */
+    inMonth: boolean;
+}
+declare function isSameDay(a: Date | null, b: Date | null): boolean;
+declare function startOfDay(date: Date): Date;
+/**
+ * Six weeks of cells, always. A fixed grid height means the popover does not resize when a
+ * month happens to span five weeks instead of six.
+ */
+declare function monthMatrix(year: number, month: number, weekStartsOn?: 0 | 1): DayCell[][];
+/**
+ * Reads what a person typed. ISO first, then day-first with `/`, `-`, or `.` — day-first because
+ * that is what most of the world writes, and an ambiguous `03/04` has to pick a side.
+ */
+declare function parseDateInput(input: string): Date | null;
+declare function formatISO(date: Date | null): string;
+declare function isOutOfRange(date: Date, min?: Date, max?: Date): boolean;
+
+/** Time-of-day parsing and formatting. Pure, like the date maths next to it. */
+interface TimeValue {
+    hours: number;
+    minutes: number;
+}
+/**
+ * Reads what a person typed: `9`, `9:30`, `0930`, `9.30`, `9 pm`, `21:05`. Returns null rather
+ * than guessing when the result would not be a real time.
+ */
+declare function parseTime(input: string): TimeValue | null;
+declare function formatTime({ hours, minutes }: TimeValue): string;
+declare function timeToMinutes({ hours, minutes }: TimeValue): number;
+/** Every selectable time between two bounds, at `step` minutes. Bounds are inclusive. */
+declare function timeOptions(step: number, min?: TimeValue, max?: TimeValue): TimeValue[];
+declare function isTimeOutOfRange(value: TimeValue, min?: TimeValue, max?: TimeValue): boolean;
+
+interface TimeInputProps {
+    value?: TimeValue | null;
+    defaultValue?: TimeValue | null;
+    onValueChange?: (value: TimeValue | null) => void;
+    min?: TimeValue;
+    max?: TimeValue;
+    /** Minutes between the offered times. Typing is never restricted to them. */
+    step?: number;
+    size?: Size;
+    disabled?: boolean;
+    invalid?: boolean;
+    placeholder?: string;
+    className?: string;
+}
+/**
+ * The DateInput's sibling. Typing accepts what people actually type — `9`, `0930`, `9:30`,
+ * `9pm` — and the list is a convenience on top, never the only way to answer.
+ */
+declare function TimeInput({ value, defaultValue, onValueChange, min, max, step, size, disabled, invalid, placeholder, className, }: TimeInputProps): react.JSX.Element;
+
+/** File acceptance rules, kept pure: what gets rejected and why is worth asserting. */
+interface FileRules {
+    /** Extensions or MIME types, e.g. ['.pdf', 'image/*']. */
+    accept?: string[];
+    /** Bytes. */
+    maxSize?: number;
+    maxFiles?: number;
+    multiple?: boolean;
+}
+interface Rejection {
+    file: File;
+    reason: string;
+}
+declare function matchesAccept(file: File, accept: string[] | undefined): boolean;
+/**
+ * Splits an incoming batch against the rules and what is already held. Every rejection carries
+ * a reason, because a file that disappears without explanation reads as a broken uploader.
+ */
+declare function partitionFiles(incoming: File[], existing: File[], rules: FileRules): {
+    accepted: File[];
+    rejected: Rejection[];
+};
+/** The " — PDF up to 5 MB" tail under the drop zone. Empty when there is nothing to say. */
+declare function describeAccept(rules: FileRules): string;
+
+interface FileDropProps extends FileRules {
+    onFilesChange: (files: File[]) => void;
+    files?: File[];
+    /** Rejections are surfaced rather than swallowed — a file that vanishes silently reads as a bug. */
+    onReject?: (rejections: Array<{
+        file: File;
+        reason: string;
+    }>) => void;
+    disabled?: boolean;
+    children?: ReactNode;
+    className?: string;
+}
+declare function FileDrop({ onFilesChange, files, onReject, accept, maxSize, maxFiles, multiple, disabled, children, className, }: FileDropProps): react.JSX.Element;
+
+/** Numeric input arithmetic, kept pure so the awkward cases are asserted, not hoped for. */
+interface NumberBounds {
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/** Parses what a person typed. Accepts a comma decimal separator; returns null for nonsense. */
+declare function parseNumber(input: string): number | null;
+declare function clamp(value: number, { min, max }: NumberBounds): number;
+/**
+ * Steps by `step` and clamps. Floating point is rounded back to the step's own precision,
+ * because 0.1 + 0.2 must read as 0.3 in an input a person is looking at.
+ */
+declare function stepBy(value: number | null, direction: 1 | -1, bounds: NumberBounds): number;
+declare function decimalPlaces(step: number): number;
+/** Whether stepping in this direction would do anything — drives the disabled state. */
+declare function canStep(value: number | null, direction: 1 | -1, bounds: NumberBounds): boolean;
+
+interface NumberInputProps extends NumberBounds {
+    value?: number | null;
+    defaultValue?: number | null;
+    onValueChange?: (value: number | null) => void;
+    size?: Size;
+    disabled?: boolean;
+    invalid?: boolean;
+    name?: string;
+    placeholder?: string;
+    /** Shown inside the control, e.g. 'kg', 'IDR'. Decorative — keep the unit in the label too. */
+    suffix?: string;
+    className?: string;
+}
+/**
+ * A text input that speaks numbers, not `<input type="number">`: that one scrolls its value
+ * away under the wheel, accepts 'e' and '+', and formats inconsistently across locales.
+ */
+declare function NumberInput({ value, defaultValue, onValueChange, min, max, step, size, disabled, invalid, name, placeholder, suffix, className, }: NumberInputProps): react.JSX.Element;
+
+interface DialogProps {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    title: ReactNode;
+    description?: ReactNode;
+    children?: ReactNode;
+    footer?: ReactNode;
+    size?: 'sm' | 'md' | 'lg';
+    /** Slides from the edge instead of scaling in the centre. */
+    placement?: 'center' | 'end';
+    /** The element that opens it. Omit for a fully controlled dialog. */
+    trigger?: ReactNode;
+    className?: string;
+}
+/**
+ * Focus trapping, scroll locking, dismissal, and the `aria-labelledby` wiring are Base UI's
+ * (ADR 0003). Enter and exit are CSS transitions driven by Base UI's own state attributes,
+ * because Base UI owns this element's mount lifecycle — motion is used where we own it.
+ */
+declare function Dialog({ open, defaultOpen, onOpenChange, title, description, children, footer, size, placement, trigger, className, }: DialogProps): react.JSX.Element;
+declare const DialogClose: react.ForwardRefExoticComponent<Omit<_base_ui_react.AlertDialogCloseProps, "ref"> & react.RefAttributes<HTMLButtonElement>>;
+
+/** Command matching and ranking. Pure — search that ranks badly is a bug you can only see in a test. */
+interface Command {
+    id: string;
+    label: string;
+    /** Extra words that should find this command, e.g. ['logout', 'exit'] for "Sign out". */
+    keywords?: string[];
+    group?: string;
+    shortcut?: string;
+}
+interface RankedCommand<T extends Command = Command> {
+    command: T;
+    score: number;
+}
+/**
+ * Ranks by how the query matched, not by string distance:
+ * an exact label wins, then a label prefix, then a word start, then anything containing it,
+ * then a keyword hit. Ties keep the order the caller supplied, so a curated list stays curated.
+ */
+declare function rankCommand(command: Command, query: string): number;
+declare function filterCommands<T extends Command>(commands: T[], query: string): T[];
+/** Groups in first-seen order, so a ranked list does not shuffle its own headings. */
+declare function groupCommands<T extends Command>(commands: T[]): Array<{
+    group: string | undefined;
+    items: T[];
+}>;
+
+interface PaletteCommand extends Command {
+    icon?: ReactNode;
+    onRun: () => void;
+}
+interface CommandPaletteProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    commands: PaletteCommand[];
+    placeholder?: string;
+    emptyMessage?: ReactNode;
+    className?: string;
+}
+/**
+ * Search over actions. The list is the app's — the palette ranks, renders, and runs, and knows
+ * nothing about what a command does.
+ */
+declare function CommandPalette({ open, onOpenChange, commands, placeholder, emptyMessage, className, }: CommandPaletteProps): react.JSX.Element;
+
+interface ChecklistTask {
+    id: string;
+    label: ReactNode;
+    description?: ReactNode;
+    done?: boolean;
+    onSelect?: () => void;
+}
+interface ChecklistProps {
+    title?: ReactNode;
+    tasks: ChecklistTask[];
+    /** Rendered once every task is done — the reason the checklist can go away. */
+    completeSlot?: ReactNode;
+    className?: string;
+}
+/**
+ * Getting-started tasks with progress. Which tasks are done is the app's knowledge, passed in —
+ * the library does not track anyone's account state, the same rule the Seen Store follows
+ * (ADR 0006).
+ */
+declare function Checklist({ title, tasks, completeSlot, className }: ChecklistProps): react.JSX.Element;
+
+type Side = 'top' | 'right' | 'bottom' | 'left';
+type Align = 'start' | 'center' | 'end';
+interface PopoverProps {
+    trigger: ReactElement;
+    children: ReactNode;
+    side?: Side;
+    align?: Align;
+    /** Distance from the anchor, in px. Keep it at the token step unless the arrow needs room. */
+    sideOffset?: number;
+    showArrow?: boolean;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    className?: string;
+}
+/** Positioning, dismissal, and focus return come from Base UI; this adds the surface (ADR 0003). */
+declare function Popover({ trigger, children, side, align, sideOffset, showArrow, open, onOpenChange, className, }: PopoverProps): react.JSX.Element;
+interface TooltipProps {
+    children: ReactElement;
+    /** Plain text. A tooltip that needs markup is a Popover — screen readers read this as a label. */
+    label: string;
+    side?: Side;
+    delay?: number;
+}
+declare function Tooltip({ children, label, side, delay }: TooltipProps): react.JSX.Element;
+
+interface AlertProps {
+    title?: ReactNode;
+    children?: ReactNode;
+    tone?: Tone;
+    /** Replaces the tone's default icon. Pass null to drop it. */
+    icon?: ReactNode | null;
+    actions?: ReactNode;
+    onDismiss?: () => void;
+    className?: string;
+}
+/**
+ * `danger` and `warning` announce themselves through `role="alert"`; the quieter tones do not,
+ * because a success note that interrupts a screen reader mid-sentence is not helpful.
+ */
+declare function Alert({ title, children, tone, icon, actions, onDismiss, className }: AlertProps): react.JSX.Element;
+
+type ToastPosition = 'bottom-end' | 'bottom-center' | 'bottom-start' | 'top-end' | 'top-center' | 'top-start';
+interface ToastProviderProps {
+    children: ReactNode;
+    /** Milliseconds before a toast leaves on its own. Errors ignore it and stay. */
+    timeout?: number;
+    limit?: number;
+    /** Where the stack lives. Logical, so `end` follows the writing direction. */
+    position?: ToastPosition;
+}
+/**
+ * Wrap the app once. The viewport is rendered here rather than left to the caller, because a
+ * provider without a viewport fails silently: the toast is created and nothing appears.
+ */
+declare function ToastProvider({ children, timeout, limit, position, }: ToastProviderProps): react.JSX.Element;
+interface ToastOptions {
+    title?: string;
+    description?: string;
+    tone?: Extract<Tone, 'info' | 'success' | 'warning' | 'danger'>;
+    timeout?: number;
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+}
+/** Called inside a ToastProvider. Returns the manager, with our vocabulary in front of it. */
+declare function useToast(): {
+    show: ({ title, description, tone, timeout, action }: ToastOptions) => string;
+    close: (id?: string) => void;
+    promise: <Value, T extends any = any>(promise: Promise<Value>, options: _base_ui_react.ToastManagerPromiseOptions<Value, T>) => Promise<Value>;
+};
+
+interface TabItem {
+    value: string;
+    label: ReactNode;
+    /** Count or status shown after the label, e.g. a Badge. */
+    adornment?: ReactNode;
+    disabled?: boolean;
+    content: ReactNode;
+}
+interface TabsProps {
+    items: TabItem[];
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    variant?: 'underline' | 'pill';
+    className?: string;
+}
+/** Roving focus, panel association, and the moving indicator are Base UI's (ADR 0003). */
+declare function Tabs({ items, value, defaultValue, onValueChange, variant, className }: TabsProps): react.JSX.Element;
+
+interface MenuItem {
+    /** Omit everything but `separator` to draw a divider. */
+    separator?: boolean;
+    label?: ReactNode;
+    icon?: ReactNode;
+    shortcut?: string;
+    tone?: Extract<Tone, 'neutral' | 'danger'>;
+    disabled?: boolean;
+    checked?: boolean;
+    onSelect?: () => void;
+}
+interface DropdownMenuProps {
+    trigger: ReactElement;
+    items: MenuItem[];
+    align?: 'start' | 'center' | 'end';
+    side?: 'top' | 'right' | 'bottom' | 'left';
+    className?: string;
+}
+/** Typeahead, roving focus, and dismissal are Base UI's; the surface and the rhythm are ours. */
+declare function DropdownMenu({ trigger, items, align, side, className }: DropdownMenuProps): react.JSX.Element;
+
+interface NavItem {
+    label: ReactNode;
+    icon?: ReactNode;
+    href?: string;
+    onClick?: () => void;
+    active?: boolean;
+    /** A count or status shown at the end of the row. */
+    adornment?: ReactNode;
+    /** One level of children. A parent with children is a disclosure, not a destination. */
+    items?: NavItem[];
+}
+interface NavSection {
+    title?: ReactNode;
+    items: NavItem[];
+}
+interface SidebarProps {
+    sections: NavSection[];
+    /** Brand block at the top — a Logo, usually. */
+    header?: ReactNode;
+    footer?: ReactNode;
+    collapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    className?: string;
+}
+/**
+ * The shell's navigation. Collapsed, it keeps the icons and hides the labels — the labels stay in
+ * the accessible name, and hovering or focusing a rail item opens a flyout carrying that label and
+ * any children, so a collapsed rail stays readable instead of becoming a column of guesses.
+ */
+declare function Sidebar({ sections, header, footer, collapsed, onCollapsedChange, className }: SidebarProps): react.JSX.Element;
+interface TopBarProps {
+    /** Page title, or a Breadcrumbs trail. */
+    title?: ReactNode;
+    subtitle?: ReactNode;
+    /** Search, filters — anything that belongs in the middle. */
+    center?: ReactNode;
+    actions?: ReactNode;
+    sticky?: boolean;
+    className?: string;
+}
+declare function TopBar({ title, subtitle, center, actions, sticky, className }: TopBarProps): react.JSX.Element;
+
+/** Sorting and pagination arithmetic, kept pure so the off-by-ones are asserted (ADR 0012). */
+type SortDirection = 'asc' | 'desc';
+interface SortState {
+    column: string;
+    direction: SortDirection;
+}
+/**
+ * What clicking a header does. Sorting a new column starts ascending; clicking the sorted
+ * column flips it; clicking a descending column clears the sort — three states, because
+ * "back to the order the server gave me" is a state people look for.
+ */
+declare function nextSort(current: SortState | null, column: string): SortState | null;
+declare function ariaSortFor(current: SortState | null, column: string): 'ascending' | 'descending' | 'none';
+interface PageRange {
+    /** Page numbers to render; `null` is an ellipsis. */
+    items: Array<number | null>;
+    totalPages: number;
+    /** 1-based index of the first and last row on this page, for "1–20 of 137". */
+    from: number;
+    to: number;
+}
+/**
+ * The page list, with ellipses. `siblings` is how many pages flank the current one; first and
+ * last are always shown, because jumping to the end is the second most common thing people do.
+ */
+declare function pageRange(page: number, pageSize: number, total: number, siblings?: number): PageRange;
+
+interface Column<Row> {
+    key: string;
+    header: ReactNode;
+    /** Cell content. Given the row, so a column can render a Badge or an Avatar. */
+    cell: (row: Row) => ReactNode;
+    align?: 'start' | 'end';
+    width?: string;
+    sortable?: boolean;
+    /** Hides the column below 720px — for the ones a phone can live without. */
+    secondary?: boolean;
+    /** Clips overflowing text with an ellipsis instead of widening the column. */
+    truncate?: boolean;
+}
+interface DataTableProps<Row> {
+    columns: Array<Column<Row>>;
+    rows: Row[];
+    rowKey: (row: Row) => string;
+    /** Accessible name for the table. */
+    label: string;
+    sort?: SortState | null;
+    onSortChange?: (sort: SortState | null) => void;
+    onRowClick?: (row: Row) => void;
+    /** Rendered in place of the body when there are no rows — an EmptyState, usually. */
+    empty?: ReactNode;
+    className?: string;
+}
+/**
+ * A table, not a grid: no virtualisation, no column resizing, no editing. It renders rows and
+ * sorts by a column, and anything past that is a product feature rather than a design system one.
+ */
+declare function DataTable<Row>({ columns, rows, rowKey, label, sort, onSortChange, onRowClick, empty, className, }: DataTableProps<Row>): react.JSX.Element;
+declare namespace DataTable {
+    var Skeleton: typeof DataTableSkeleton;
+}
+interface DataTableSkeletonProps {
+    columns: number;
+    rows?: number;
+    className?: string;
+}
+/** Same row height and column count as the real table, so the page does not jump (ADR 0009). */
+declare function DataTableSkeleton({ columns, rows, className }: DataTableSkeletonProps): react.JSX.Element;
+
+interface PaginationProps {
+    page: number;
+    pageSize: number;
+    total: number;
+    onPageChange: (page: number) => void;
+    /** Shows "1–20 of 137" beside the controls. */
+    showSummary?: boolean;
+    siblings?: number;
+    className?: string;
+}
+declare function Pagination({ page, pageSize, total, onPageChange, showSummary, siblings, className, }: PaginationProps): react.JSX.Element;
+
+interface ImageProps {
+    src: string;
+    /** Empty string is allowed, and means "decorative" — but it has to be said out loud. */
+    alt: string;
+    /** Width / height, e.g. 16 / 9. Reserves the space so nothing below it jumps. */
+    aspectRatio?: number;
+    /** A tiny data URI, blurred up while the real image loads. */
+    blurDataUrl?: string;
+    /** Flat colour to sit behind the image when there is no blur placeholder. */
+    background?: string;
+    fit?: 'cover' | 'contain';
+    radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl';
+    loading?: 'lazy' | 'eager';
+    className?: string;
+}
+/**
+ * An `<img>` that reserves its space and fades in. It is not a Next.js Image and does not want to
+ * be: no resizing service, no loader — those belong to the framework the app already chose.
+ */
+declare function Image({ src, alt, aspectRatio, blurDataUrl, background, fit, radius, loading, className, }: ImageProps): react.JSX.Element;
+
+interface CarouselProps {
+    children: ReactNode;
+    /** Accessible name — a carousel with no name is an unlabelled region to a screen reader. */
+    label: string;
+    /** Slide width as a CSS length or fraction of the viewport, e.g. '18rem' or '50%'. */
+    slideWidth?: string;
+    gap?: 2 | 3 | 4 | 5;
+    loop?: boolean;
+    align?: 'start' | 'center';
+    /** Milliseconds between advances. Omit for a carousel that only moves when asked. */
+    autoplay?: number;
+    showArrows?: boolean;
+    showDots?: boolean;
+    className?: string;
+}
+declare function CarouselRoot({ children, label, slideWidth, gap, loop, align, autoplay, showArrows, showDots, className, }: CarouselProps): react.JSX.Element;
+interface CarouselSlideProps {
+    children: ReactNode;
+    className?: string;
+}
+declare function CarouselSlide({ children, className }: CarouselSlideProps): react.JSX.Element;
+interface CarouselSkeletonProps {
+    slides?: number;
+    slideWidth?: string;
+    slideHeight?: string;
+    gap?: 2 | 3 | 4 | 5;
+}
+/** Same track geometry as the real carousel, so slides do not resize on load (ADR 0009). */
+declare function CarouselSkeleton({ slides, slideWidth, slideHeight, gap, }: CarouselSkeletonProps): react.JSX.Element;
+declare const Carousel: typeof CarouselRoot & {
+    Slide: typeof CarouselSlide;
+    Skeleton: typeof CarouselSkeleton;
+};
+
+/** Inputs that decide whether a carousel may advance on its own. */
+interface AutoplayConditions {
+    /** The caller asked for autoplay at all. */
+    requested: boolean;
+    pointerInside: boolean;
+    /** Focus is somewhere inside the carousel — keyboard users must not lose their place. */
+    focusInside: boolean;
+    documentHidden: boolean;
+    reducedMotion: boolean;
+}
+/**
+ * Autoplay stops for four separate reasons, and every one of them is a bug when missed:
+ * a hovered carousel that keeps moving, a focused one that steals the slide out from under
+ * a keyboard user, a background tab burning frames, and motion nobody asked for.
+ */
+declare function shouldAutoplay(conditions: AutoplayConditions): boolean;
+
+interface CoachmarkProps {
+    open: boolean;
+    /** The element being pointed at. Already resolved — a Tour does the resolving. */
+    anchor: Element | null;
+    title: ReactNode;
+    children?: ReactNode;
+    side?: Side;
+    align?: Align;
+    /** Dims the page and cuts a hole around the anchor. A number sets the hole's padding in px. */
+    spotlight?: boolean | number;
+    /** e.g. `{ current: 2, total: 5 }` — rendered as "2 of 5" and announced. */
+    progress?: {
+        current: number;
+        total: number;
+    };
+    actions?: ReactNode;
+    onDismiss?: () => void;
+    className?: string;
+}
+/**
+ * One anchored bubble pointing at one element. It knows nothing about sequence and nothing
+ * about who has seen it — those are Tour and the Seen Store (ADR 0006).
+ */
+declare function Coachmark({ open, anchor, title, children, side, align, spotlight, progress, actions, onDismiss, className, }: CoachmarkProps): react.JSX.Element;
+
+/**
+ * How a Tour asks whether someone has already been through it.
+ *
+ * The library ships this interface and no implementation on purpose (ADR 0006): a library that
+ * reaches for localStorage has decided what a user is and where their state lives, and that is
+ * the assumption that makes an onboarding library impossible to remove later.
+ *
+ * A localStorage adapter is four lines; a server-backed one is a fetch. Both are yours.
+ */
+interface SeenStore {
+    /** Whether this tour has been completed or skipped before. May be async. */
+    has: (tourId: string) => boolean | Promise<boolean>;
+    /** Records that it has now. Called once, when the tour finishes or is skipped. */
+    mark: (tourId: string) => void | Promise<void>;
+}
+
+/** Tour sequencing, kept pure so every edge is assertable (ADR 0012). */
+type TourStatus = 'idle' | 'running' | 'finished' | 'skipped';
+interface TourState {
+    index: number;
+    status: TourStatus;
+}
+type TourAction = {
+    type: 'start';
+} | {
+    type: 'next';
+} | {
+    type: 'prev';
+} | {
+    type: 'goto';
+    index: number;
+} | {
+    type: 'skip';
+} | {
+    type: 'finish';
+};
+declare const initialTourState: TourState;
+/**
+ * `stepCount` is passed in rather than held in state because steps are props: a tour whose
+ * steps change while it runs must not point past the end of the new list.
+ */
+declare function tourReducer(state: TourState, action: TourAction, stepCount: number): TourState;
+/** A tour that ended, either way. Both outcomes mark the Seen Store. */
+declare function hasEnded(status: TourStatus): boolean;
+type StepTarget = string | Element | {
+    current: Element | null;
+} | (() => Element | null) | null;
+/**
+ * Resolves a step's target. Returns null rather than throwing when the element is not mounted
+ * yet — the Tour retries, because a target that appears one frame late is normal, not an error.
+ */
+declare function resolveTarget(target: StepTarget, root: ParentNode): Element | null;
+
+interface TourStep {
+    target: StepTarget;
+    title: ReactNode;
+    content?: ReactNode;
+    side?: Side;
+    align?: Align;
+    spotlight?: boolean | number;
+}
+interface TourProps {
+    /** Stable id — this is what the Seen Store remembers. */
+    id: string;
+    steps: TourStep[];
+    /** Starts the tour when it turns true. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Injected by the app; without one the tour runs every time it is opened (ADR 0006). */
+    seenStore?: SeenStore;
+    onFinish?: () => void;
+    onSkip?: () => void;
+    labels?: Partial<Record<'back' | 'next' | 'done' | 'skip', string>>;
+}
+/**
+ * Sequences Coachmarks. It owns order and nothing else: memory is the Seen Store's, the bubble
+ * is the Coachmark's, and the steps belong to the caller.
+ */
+declare function Tour({ id, steps, open, onOpenChange, seenStore, onFinish, onSkip, labels }: TourProps): react.JSX.Element | null;
+
+interface RevealProps {
+    children: ReactNode;
+    /** Direction the content travels from. Under reduced motion it only fades. */
+    from?: 'below' | 'above' | 'left' | 'right' | 'none';
+    distance?: number;
+    delay?: number;
+    spring?: SpringPreset;
+    /** Waits until the element scrolls into view instead of animating on mount. */
+    onView?: boolean;
+    className?: string;
+}
+declare function Reveal({ children, from, distance, delay, spring, onView, className, }: RevealProps): react.JSX.Element;
+interface StaggerProps {
+    children: ReactNode;
+    /** Seconds between children. Collapses to zero under reduced motion. */
+    step?: number;
+    from?: RevealProps['from'];
+    onView?: boolean;
+    className?: string;
+}
+/** Wraps each child in a Reveal with an increasing delay — the list arrives, it does not pop. */
+declare function Stagger({ children, step, from, onView, className }: StaggerProps): react.JSX.Element;
+
+export { Alert, type AlertProps, type Align, type AutoplayConditions, Button, type ButtonProps, Carousel, type CarouselProps, type CarouselSkeletonProps, type CarouselSlideProps, Checkbox, type CheckboxProps, Checklist, type ChecklistProps, type ChecklistTask, Coachmark, type CoachmarkProps, type Column, Combobox, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, DEFAULT_LABELS, DataTable, type DataTableProps, type DataTableSkeletonProps, DateInput, type DateInputProps, type DayCell, Dialog, DialogClose, type DialogProps, DropdownMenu, type DropdownMenuProps, type DurationToken, Field, type FieldProps, FileDrop, type FileDropProps, type FileRules, Image, type ImageProps, type Labels, LabelsProvider, type LabelsProviderProps, type MenuItem, type MotionHelpers, MotionProvider, type MotionProviderProps, type MotionSettings, type NavItem, type NavSection, type NumberBounds, NumberInput, type NumberInputProps, type PageRange, Pagination, type PaginationProps, type PaletteCommand, Popover, type PopoverProps, RadioGroup, type RadioGroupProps, type RadioOption, type RankedCommand, type Rejection, Reveal, type RevealProps, type SeenStore, Select, type SelectOption, type SelectProps, type Side, Sidebar, type SidebarProps, type SortDirection, type SortState, type SpringPreset, Stagger, type StaggerProps, type StepTarget, Switch, type SwitchProps, type TabItem, Tabs, type TabsProps, TextInput, type TextInputProps, Textarea, type TextareaProps, type ThemeChoice, ThemeProvider, TimeInput, type TimeInputProps, type TimeValue, type ToastOptions, type ToastPosition, ToastProvider, type ToastProviderProps, Tooltip, type TooltipProps, TopBar, type TopBarProps, Tour, type TourAction, type TourProps, type TourState, type TourStatus, type TourStep, ariaSortFor, canStep, clamp, decimalPlaces, describeAccept, filterCommands, formatISO, formatTime, groupCommands, hasEnded, initialTourState, isOutOfRange, isSameDay, isTimeOutOfRange, matchesAccept, monthMatrix, nextSort, pageRange, parseDateInput, parseNumber, parseTime, partitionFiles, rankCommand, resolveTarget, shouldAutoplay, startOfDay, stepBy, timeOptions, timeToMinutes, tourReducer, useFieldWiring, useLabels, useMotionSettings, useTheme, useToast };