@sovereignfs/ui 0.21.3 → 0.33.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode, ButtonHTMLAttributes, SelectHTMLAttributes, ReactElement, InputHTMLAttributes, HTMLAttributes } from 'react';
+import { ReactNode, ButtonHTMLAttributes, SelectHTMLAttributes, ReactElement, CSSProperties, InputHTMLAttributes, TextareaHTMLAttributes, HTMLAttributes, PointerEvent, MouseEvent } from 'react';
 
 type BadgeVariant = 'role' | 'status' | 'mono';
 type BadgeStatus = 'active' | 'enabled' | 'deactivated' | 'failed' | 'invited' | 'pending' | 'neutral';
@@ -18,7 +18,7 @@ interface BadgeProps {
  */
 declare function Badge({ variant, status, children }: BadgeProps): react.JSX.Element;
 
-type IconName = 'house' | 'settings' | 'log-out' | 'chevron-right' | 'chevron-left' | 'chevron-down' | 'chevron-up' | 'x' | 'check' | 'plus' | 'trash-2' | 'pencil' | 'rotate-ccw' | 'search' | 'user' | 'shield' | 'lock' | 'eye' | 'eye-off' | 'mail' | 'bell' | 'activity' | 'package' | 'grid-2x2' | 'info' | 'alert-triangle' | 'sliders-horizontal' | 'terminal';
+type IconName = 'house' | 'settings' | 'log-out' | 'chevron-right' | 'chevron-left' | 'chevron-down' | 'chevron-up' | 'x' | 'check' | 'plus' | 'trash-2' | 'pencil' | 'rotate-ccw' | 'search' | 'user' | 'shield' | 'lock' | 'eye' | 'eye-off' | 'mail' | 'bell' | 'activity' | 'package' | 'grid-2x2' | 'info' | 'alert-triangle' | 'calendar' | 'sliders-horizontal' | 'ellipsis-vertical';
 
 /** Decorative icon — visually meaningful but described by surrounding text. */
 type DecorativeProps = {
@@ -34,7 +34,7 @@ interface IconProps {
     /** Name of the icon from the curated Sovereign set. */
     name: IconName;
     /** Visual size. Defaults to `"md"` (20 px). */
-    size?: 'sm' | 'md' | 'lg';
+    size?: 'xs' | 'sm' | 'md' | 'lg';
     /** Additional CSS class applied to the SVG element. */
     className?: string;
 }
@@ -121,6 +121,12 @@ type SelectProps = Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size'> & {
  * Uses the native picker on mobile — no custom dropdown, maximum a11y coverage.
  *
  * RSC-safe: presentational, no hooks, forwards all native select props.
+ *
+ * `className` sizes the outer box (the wrapper), not the `<select>` itself —
+ * the chevron is absolutely positioned against the wrapper, so a className
+ * that constrains only the `<select>` (e.g. `max-width`) shrinks the select
+ * while the wrapper (and thus the chevron) stays full width, leaving the
+ * chevron stranded past the visible box.
  */
 declare function Select({ className, size, children, ...rest }: SelectProps): react.JSX.Element;
 
@@ -147,25 +153,53 @@ interface PopoverProps {
     onClose: () => void;
     /** Which edge of the trigger the panel aligns to. Default: 'right'. */
     align?: 'left' | 'right';
-    /** Panel width in px. Default: 288. */
-    width?: number;
+    /** Panel width in px, or `'trigger'` to match the trigger element's own
+     *  rendered width exactly (e.g. a dropdown under a full-width form field,
+     *  where a fixed pixel width would either overflow or leave a gap
+     *  depending on viewport size). Default: 288. */
+    width?: number | 'trigger';
+    /**
+     * Inline style overrides for the panel, merged after `width`. Escape hatch
+     * for callers that need to override the panel's own chrome (e.g. no
+     * rounded corners for a compact swatch picker) — inline styles always win
+     * regardless of CSS module load order, unlike passing an extra className.
+     */
+    panelStyle?: CSSProperties;
     'aria-label': string;
     children: ReactNode;
 }
 /**
- * Popover — floating panel anchored below a trigger element.
+ * Popover — floating panel anchored to a trigger element, below it by
+ * default.
  *
  * Positioning is `position: absolute` inside a `position: relative` wrapper —
- * no floating-ui dependency. Supports left/right alignment against the trigger edge.
+ * no floating-ui dependency. Supports left/right alignment against the trigger
+ * edge, and automatically opens on whichever side (above or below the
+ * trigger) has more room within the viewport.
+ *
+ * If the panel doesn't fit on *either* side as the trigger currently sits —
+ * common for a tall panel (e.g. a full calendar month) nested partway down a
+ * long scrollable mobile sheet — the trigger's scrollable ancestor is
+ * scrolled so the trigger sits at the top of it first, maximizing the room
+ * available below, then the panel opens downward against that. This mirrors
+ * how most mobile date pickers behave (scroll the page, not the picker) and
+ * avoids the panel needing its own internal scroll in the vast majority of
+ * cases. If it's still too tall even after that (a genuinely tiny viewport,
+ * or an unusually tall panel), it's capped to whatever room actually exists
+ * and scrolls internally as a last resort, rather than rendering past the
+ * edge of the viewport with no way to reach the rest of it.
+ *
  * Closes on outside click or Escape. Does not trap focus (it is non-modal).
  */
-declare function Popover({ trigger, open, onClose, align, width, 'aria-label': ariaLabel, children, }: PopoverProps): react.JSX.Element;
+declare function Popover({ trigger, open, onClose, align, width, panelStyle, 'aria-label': ariaLabel, children, }: PopoverProps): react.JSX.Element;
 
 type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive';
 type ButtonSize = 'sm' | 'md';
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: ButtonVariant;
     size?: ButtonSize;
+    /** Shows a spinner and disables the button while an async action is pending. */
+    loading?: boolean;
     children: ReactNode;
 }
 /**
@@ -174,7 +208,7 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  * renders in both Server and Client Components. All styling references `--sv-*`
  * tokens via CSS Modules; there are no hardcoded values.
  */
-declare function Button({ variant, size, type, className, children, ...rest }: ButtonProps): react.JSX.Element;
+declare function Button({ variant, size, type, loading, disabled, className, children, ...rest }: ButtonProps): react.JSX.Element;
 
 type InputProps = InputHTMLAttributes<HTMLInputElement>;
 /**
@@ -184,6 +218,105 @@ type InputProps = InputHTMLAttributes<HTMLInputElement>;
  */
 declare function Input({ type, className, ...rest }: InputProps): react.JSX.Element;
 
+type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement>;
+/**
+ * Textarea — the primitive multi-line text field. Presentational and
+ * RSC-safe: it forwards all native textarea props to the underlying
+ * `<textarea>`. Styling references `--sv-*` tokens via CSS Modules; there
+ * are no hardcoded values.
+ */
+declare function Textarea({ className, rows, ...rest }: TextareaProps): react.JSX.Element;
+
+interface CodeTextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    invalid?: boolean;
+}
+/**
+ * CodeTextarea — monospace textarea for Markdown, YAML, JSON, and other
+ * whitespace-sensitive content. Pair with FormField for labels, hints, and
+ * validation text.
+ */
+declare function CodeTextarea({ className, rows, spellCheck, wrap, invalid, 'aria-invalid': ariaInvalid, ...rest }: CodeTextareaProps): react.JSX.Element;
+
+type StatusBadgeStatus = 'unmodified' | 'draft' | 'committed' | 'conflict' | 'pending-delete' | 'synced' | 'warning' | 'error';
+interface StatusBadgeProps {
+    status: StatusBadgeStatus;
+    children?: ReactNode;
+    /** Accessible label when the visible text is abbreviated or contextual. */
+    'aria-label'?: string;
+    className?: string;
+}
+/**
+ * StatusBadge — compact inline status indicator for editor lists, draft
+ * workflows, and sync states.
+ */
+declare function StatusBadge({ status, children, className, 'aria-label': ariaLabel, }: StatusBadgeProps): react.JSX.Element;
+
+interface SplitPaneProps {
+    primary: ReactNode;
+    secondary: ReactNode;
+    defaultPrimarySize?: number;
+    minPrimarySize?: number;
+    maxPrimarySize?: number;
+    resizable?: boolean;
+    primaryLabel?: string;
+    secondaryLabel?: string;
+    resizeLabel?: string;
+    className?: string;
+}
+/**
+ * SplitPane — responsive two-pane layout for editor/preview and list/detail
+ * workflows. Desktop panes can be resized; narrow viewports fall back to a
+ * stable single-column stack.
+ */
+declare function SplitPane({ primary, secondary, defaultPrimarySize, minPrimarySize, maxPrimarySize, resizable, primaryLabel, secondaryLabel, resizeLabel, className, }: SplitPaneProps): react.JSX.Element;
+
+interface TagInputProps {
+    value: string[];
+    onChange: (value: string[]) => void;
+    id?: string;
+    name?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    required?: boolean;
+    error?: string;
+    hint?: string;
+    validateTag?: (tag: string, currentTags: string[]) => string | undefined;
+    separators?: RegExp;
+    className?: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: boolean;
+    'aria-label'?: string;
+}
+/**
+ * TagInput — controlled multi-value input for frontmatter tags, labels, and
+ * lightweight taxonomies. Use inside FormField just like a native input.
+ */
+declare function TagInput({ value, onChange, id, name, placeholder, disabled, required, error, hint, validateTag, separators, className, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-label': ariaLabel, }: TagInputProps): react.JSX.Element;
+
+/**
+ * Lets content deep inside a `Dialog` (e.g. a plugin's own route layout,
+ * rendered several levels below wherever the `Dialog` itself is
+ * instantiated) supply the second-row content of the Dialog's mobile
+ * `OverlayHeader` — typically a tab strip. Solves the "double header"
+ * problem: without this, a plugin's own tab strip has no way to reach the
+ * Dialog's header and ends up rendered a second time, as its own sticky bar,
+ * inside the scrolling content area.
+ *
+ * A no-op when there is no enclosing `Dialog` (e.g. the same plugin layout
+ * also rendered on a plain, non-overlay route) — safe to call unconditionally.
+ * Returns whether an enclosing `Dialog` actually received the content, so a
+ * caller that also renders its own inline header/tab-strip copy for the
+ * no-Dialog case can hide that copy on mobile specifically when this
+ * returned `true` (the Dialog's own header is showing it instead there).
+ *
+ * ```tsx
+ * function AccountLayout({ children }) {
+ *   const insideOverlay = useOverlaySecondRow(<nav>...tab strip...</nav>);
+ *   return <div>{children}</div>;
+ * }
+ * ```
+ */
+declare function useOverlaySecondRow(node: ReactNode | null): boolean;
 type DialogSize = 'sm' | 'md' | 'lg' | 'full';
 interface DialogProps {
     /** Whether the dialog is shown. When false, nothing renders. */
@@ -208,29 +341,235 @@ interface DialogProps {
  * is restored to the previously-focused element on close; Tab is trapped within
  * the panel. Styling references `--sv-*` tokens only; on mobile the panel becomes
  * a full-screen sheet regardless of `size`.
+ *
+ * Animated open/close: fade + scale on desktop, slide-up on mobile (matching
+ * the "feels like a page push" framing of the mobile sheet). The `open`/
+ * `onClose` API is unchanged — closing still stays mounted internally for the
+ * exit transition before actually unmounting; `prefers-reduced-motion: reduce`
+ * collapses both to near-instant.
  */
 declare function Dialog({ open, onClose, size, 'aria-label': ariaLabel, title, children, }: DialogProps): react.JSX.Element | null;
 
 interface DrawerProps {
     /** Whether the drawer is shown. When false, nothing renders. */
     open: boolean;
-    /** Called on Esc or scrim click. */
+    /** Called on Esc, scrim click, or a swipe-down past the dismiss threshold. */
     onClose: () => void;
     /** Accessible name for the drawer panel (sets `aria-label`). */
     'aria-label'?: string;
+    /** `'content'` (default) sizes to content, capped at 80dvh. `'half'` fixes
+     *  the panel to 50dvh regardless of content — per the design-system's
+     *  "half screen or less" convention for Drawer, this is the only other
+     *  supported size; taller content should use `Sheet` instead. */
+    snapHeight?: 'content' | 'half';
     children: ReactNode;
 }
 /**
  * Drawer — a dismissable bottom-sheet panel. Used by the mobile shell for
  * plugin navigation; also available to plugins for any bottom-up surface.
  *
- * Behaviour: Esc and scrim-click dismiss; focus moves to the first focusable
- * element on open and is restored on close; Tab is trapped within the panel.
- * The panel respects `env(safe-area-inset-bottom)` so it clears the home
- * indicator in standalone/fullscreen mode. Shares dismissal conventions and
- * tokens (`--sv-color-scrim`, `--sv-shadow-overlay`) with `Dialog`.
+ * Behaviour: Esc, scrim click, or dragging the grab handle down past
+ * `SWIPE_DISMISS_THRESHOLD_PX` all dismiss; focus moves to the first
+ * focusable element on open and is restored on close; Tab is trapped within
+ * the panel. The panel respects `env(safe-area-inset-bottom)` so it clears
+ * the home indicator in standalone/fullscreen mode. Shares dismissal
+ * conventions and tokens (`--sv-color-scrim`, `--sv-shadow-overlay`) with
+ * `Dialog`.
+ *
+ * Animated open/close: slides up from the bottom, scrim fades. The `open`/
+ * `onClose` API is unchanged — closing stays mounted internally for the exit
+ * transition before actually unmounting; `prefers-reduced-motion: reduce`
+ * collapses it to near-instant.
+ *
+ * The grab handle is the *only* drag-initiation region (not the whole panel)
+ * — dragging from body content would fight that content's own internal
+ * scroll, the same reasoning behind the tasks plugin's edge-zone-only
+ * swipe-to-reveal technique.
+ */
+declare function Drawer({ open, onClose, 'aria-label': ariaLabel, snapHeight, children, }: DrawerProps): react.JSX.Element | null;
+
+interface OverlayHeaderProps {
+    /** Overlay title, shown between the optional back button and the trailing
+     *  slots. Optional — some consumers (e.g. `Dialog`'s mobile bar) need the
+     *  row's close button present even when no title applies. */
+    title?: string;
+    /** Always renders a close button; called on click. */
+    onClose: () => void;
+    /** When provided, renders a back-chevron button before the title (for
+     *  hierarchical navigation within a single overlay — going back without
+     *  fully closing it). Omit for a flat overlay that only ever closes. */
+    onBack?: () => void;
+    /** Trailing slot next to the close button — e.g. a "Save" action. */
+    action?: ReactNode;
+    /** A second row below the title row — e.g. a tab strip. */
+    secondRow?: ReactNode;
+    className?: string;
+}
+/**
+ * OverlayHeader — the shared fixed secondary header for `Dialog`'s mobile
+ * mode, `Sheet`, and `Drawer`: title + close (+ optional back button /
+ * trailing action / tab-strip row). Not itself `position: sticky` or
+ * `position: fixed` — it stays visually pinned because the consuming overlay
+ * renders it as a non-scrolling flex sibling before its own scrollable
+ * content region, the same technique `Dialog`'s `.mobileBar` already used
+ * before this component existed to generalize it.
+ *
+ * Content that needs a fully custom header (e.g. an editable title, or
+ * controls that aren't a simple title/back/action shape) should not use this
+ * component — render its own header row instead; `Sheet`'s `title` prop is
+ * optional specifically to leave that escape hatch open.
+ */
+declare function OverlayHeader({ title, onClose, onBack, action, secondRow, className, }: OverlayHeaderProps): react.JSX.Element;
+
+interface SheetProps {
+    /** Whether the sheet is shown. When false, nothing renders. */
+    open: boolean;
+    /** Called on Esc, or the built-in `OverlayHeader`'s close button. There is
+     *  no scrim to tap — a Sheet replaces the content area it fills, not a
+     *  layer floating above it (see the component doc comment). */
+    onClose: () => void;
+    /** Accessible name for the sheet. Defaults to `title` when omitted. */
+    'aria-label'?: string;
+    /** Renders a built-in `OverlayHeader` (title + close, optional back button
+     *  and trailing action). Omit when the content supplies its own header —
+     *  e.g. a form whose title doubles as an editable field. */
+    title?: string;
+    /** Forwarded to `OverlayHeader` — see its own `onBack` doc. Has no effect
+     *  without `title`. */
+    onBack?: () => void;
+    /** Forwarded to `OverlayHeader`'s trailing-action slot. Has no effect
+     *  without `title`. */
+    headerAction?: ReactNode;
+    /**
+     * Which edge the panel slides in from. Defaults to `'bottom'` (detail
+     * views, forms — content the user is reaching down into). `'top'` suits a
+     * short options/actions menu opened from a header button near the top of
+     * the screen, where sliding up from the bottom would travel past empty
+     * space before reaching content that visually belongs near the trigger.
+     */
+    slideFrom?: 'bottom' | 'top';
+    children: ReactNode;
+}
+/**
+ * Sheet — a full-page overlay that replaces a plugin's content area between
+ * the shell's fixed header and footer (RFC 0013's mobile chrome stays visible
+ * and interactive around it), sliding in from an edge instead of centering
+ * like `Dialog`. Promoted from the tasks plugin's `MobileFullPageOverlay`
+ * (now the reference pattern for this component). Desktop has no equivalent
+ * presentation — a desktop layout shows the same content inline (columns,
+ * panes) instead of mounting a `Sheet` at all; this component is for the
+ * mobile case specifically.
+ *
+ * Unlike `Dialog`/`Drawer` there is no scrim: a Sheet visually *replaces* the
+ * region it covers rather than floating a layer above it, so there is no
+ * "outside" to tap-dismiss. Behaviour: Esc dismisses; focus moves into the
+ * panel on open and is restored on close; Tab is trapped within the panel;
+ * animated open/close via the same two-phase mount as `Dialog`/`Drawer`,
+ * respecting `prefers-reduced-motion`.
+ */
+declare function Sheet({ open, onClose, 'aria-label': ariaLabel, title, onBack, headerAction, slideFrom, children, }: SheetProps): react.JSX.Element | null;
+
+interface ConfirmDialogProps {
+    /** Whether the dialog is shown. */
+    open: boolean;
+    /** Called on Esc, backdrop click, or the Cancel button. */
+    onClose: () => void;
+    title: string;
+    /** Accepts rich content (e.g. `Remove <strong>{name}</strong>?`), not just
+     *  plain text. */
+    message: ReactNode;
+    /** Called when the confirm action is clicked. Does not close the dialog
+     *  itself — pass `pending`/close it via `onClose` from the caller once the
+     *  action settles, so an async action that fails can keep the dialog open
+     *  to show `error`. */
+    onConfirm: () => void;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    /** Styles the confirm action as a destructive (red) action. */
+    destructive?: boolean;
+    /** Disables both actions — pair with a `confirmLabel` reflecting the
+     *  in-flight state (e.g. "Removing…") for an `onConfirm` that triggers an
+     *  async action. */
+    pending?: boolean;
+    /** Optional inline error, shown between the message and the actions — e.g.
+     *  a failed async `onConfirm` that keeps the dialog open to report it. */
+    error?: ReactNode;
+}
+/**
+ * ConfirmDialog — a small, content-sized confirm/cancel prompt. Deliberately
+ * NOT built on `Dialog`, which is a fixed-size box by design (so switching
+ * views inside it never resizes the panel) — a confirm prompt is the opposite
+ * case, sized to its message. Built on the native `<dialog>` element instead,
+ * same as the pattern this component replaces (duplicated across the account
+ * and console plugins): top-layer rendering and `::backdrop` come from the
+ * browser for free, which is what makes a confirm opened *from inside*
+ * another overlay (Dialog, Sheet) reliably stack above it without a manual
+ * z-index scheme.
+ *
+ * Same presentation on desktop and mobile — a small centered card, not a
+ * full-screen sheet (unlike Dialog/Sheet, which do fork by viewport).
  */
-declare function Drawer({ open, onClose, 'aria-label': ariaLabel, children }: DrawerProps): react.JSX.Element | null;
+declare function ConfirmDialog({ open, onClose, title, message, onConfirm, confirmLabel, cancelLabel, destructive, pending, error, }: ConfirmDialogProps): react.JSX.Element;
+
+interface MenuItem {
+    type?: 'item';
+    label: string;
+    onSelect: () => void;
+    icon?: IconName;
+    /** Styles the item as a destructive action (e.g. "Delete list"). */
+    destructive?: boolean;
+    disabled?: boolean;
+    /**
+     * Marks the item as one of a mutually-exclusive set (e.g. the active sort
+     * order) — renders a leading checkmark and `role="menuitemradio"` instead
+     * of `role="menuitem"`. Pass this on every item in the group, including
+     * the unchecked ones, so their labels stay aligned with the checked one's
+     * reserved checkmark gutter. Omit entirely for plain action items (e.g.
+     * "Delete list") — they render with no reserved leading space at all.
+     */
+    checked?: boolean;
+}
+/** A non-interactive section heading above a run of items (e.g. "Sort by"). */
+interface MenuLabel {
+    type: 'label';
+    label: string;
+}
+/** A visual divider between sections. */
+interface MenuSeparator {
+    type: 'separator';
+}
+type MenuEntry = MenuItem | MenuLabel | MenuSeparator;
+interface MenuProps {
+    /** The element that opens the menu — rendered as-is; the caller wires its
+     *  onClick to flip `open` (same controlled pattern as `Popover`). */
+    trigger: ReactElement;
+    open: boolean;
+    onClose: () => void;
+    items: MenuEntry[];
+    'aria-label': string;
+    /** Forwarded to `Popover` on desktop. Has no effect on mobile, where the
+     *  menu is always a full-width `Drawer`. */
+    align?: 'left' | 'right';
+}
+/**
+ * Menu — an adaptive action menu: `Popover` on desktop, a bottom-sheet
+ * `Drawer` on mobile. Replaces the desktop-Popover/mobile-Drawer fork that
+ * `⋯` action menus (list options, row actions) otherwise re-derive per
+ * plugin. Same list of `items` renders in both presentations — only the
+ * surrounding chrome (floating panel vs. bottom sheet) differs, matching the
+ * platform's `useIsMobile` breakpoint.
+ *
+ * `items` accepts three entry shapes: a plain action (`MenuItem`, `type`
+ * omitted or `'item'`), a non-interactive section heading (`MenuLabel`,
+ * `type: 'label'`), and a `MenuSeparator` (`type: 'separator'`) — enough to
+ * express grouped sections like "Filter" / "Sort by" above a run of
+ * destructive actions, matching how native OS menus lay out mixed
+ * action/selection groups.
+ *
+ * Selecting an item both closes the menu and calls its `onSelect` — a
+ * consumer's `onSelect` never needs to call `onClose` itself.
+ */
+declare function Menu({ trigger, open, onClose, items, 'aria-label': ariaLabel, align }: MenuProps): react.JSX.Element;
 
 interface ToastItem {
     id: string;
@@ -262,16 +601,32 @@ interface CardProps extends HTMLAttributes<HTMLElement> {
 }
 declare function Card({ as: Tag, interactive, padding, className, children, ...rest }: CardProps): react.JSX.Element;
 
+/** Props to spread onto the field's actual form control. */
+interface FormFieldRenderProps {
+    id: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: boolean;
+    required?: boolean;
+}
 interface FormFieldProps {
     label: string;
     hint?: string;
     error?: string;
-    htmlFor?: string;
+    /** Explicit control id. Auto-generated via `useId()` when omitted. */
+    id?: string;
     required?: boolean;
-    children: ReactNode;
     className?: string;
+    /** Render prop — receives the props that must be spread onto the control
+     * so the label, hint, and error stay associated with it. */
+    children: (field: FormFieldRenderProps) => ReactNode;
 }
-declare function FormField({ label, hint, error, htmlFor, required, children, className, }: FormFieldProps): react.JSX.Element;
+/**
+ * FormField — accessible label + hint/error wrapper for a single form control.
+ * Wires `htmlFor`/`id` and `aria-describedby`/`aria-invalid` onto the control
+ * itself (via the render-prop `field` object), not a surrounding element, so
+ * screen readers reliably announce the hint or error as part of the control.
+ */
+declare function FormField({ label, hint, error, id, required, className, children, }: FormFieldProps): react.JSX.Element;
 
 interface PageHeaderProps {
     title: string;
@@ -324,4 +679,178 @@ interface TooltipProps {
 }
 declare function Tooltip({ content, children, side }: TooltipProps): react.JSX.Element;
 
-export { Avatar, type AvatarProps, Badge, type BadgeProps, type BadgeStatus, type BadgeVariant, type BannerVariant, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Card, type CardProps, Dialog, type DialogProps, type DialogSize, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, FormField, type FormFieldProps, Icon, type IconName, type IconProps, Input, type InputProps, type NavTabItem, NavTabs, type NavTabsProps, PageHeader, type PageHeaderProps, Popover, type PopoverProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectProps, Spinner, type SpinnerProps, SystemBanner, type SystemBannerProps, type TabItem, Tabs, type TabsProps, type ToastContextValue, type ToastItem, ToastProvider, Toggle, type ToggleProps, Tooltip, type TooltipProps, useToast };
+interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange'> {
+    checked: boolean;
+    onChange: (checked: boolean) => void;
+    label: string;
+    /** Renders the label with a strike-through when checked. */
+    strikeThrough?: boolean;
+    disabled?: boolean;
+}
+declare function Checkbox({ checked, onChange, label, strikeThrough, disabled, className, id, ...rest }: CheckboxProps): react.JSX.Element;
+
+interface DragHandleRowProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+    /** Pass drag-listener and drag-control props from dnd-kit here. */
+    handleProps?: HTMLAttributes<HTMLButtonElement>;
+    isDragging?: boolean;
+}
+/**
+ * A row wrapper that surfaces a drag handle on the left.
+ * Consumers attach dnd-kit's useSortable listeners to `handleProps`.
+ */
+declare function DragHandleRow({ children, handleProps, isDragging, className, ...rest }: DragHandleRowProps): react.JSX.Element;
+
+interface CalendarProps {
+    /** Selected date, or `null` for no selection. */
+    value: Date | null;
+    onChange: (date: Date) => void;
+    /** Dates before this are disabled and unselectable. */
+    minDate?: Date;
+    /** Dates after this are disabled and unselectable. */
+    maxDate?: Date;
+    'aria-label'?: string;
+}
+/**
+ * Calendar — a keyboard-navigable month grid. Date-only (no time or range
+ * selection — decision D6 in the mobile design-system plan); a `DatePicker`
+ * field wraps this in a `Popover` (desktop) or `Drawer` (mobile).
+ *
+ * Keyboard (WAI-ARIA APG grid pattern, roving tabindex — exactly one day
+ * button is ever tab-stoppable): arrow keys move focus by day/week, Home/End
+ * jump to the start/end of the focused week, PageUp/PageDown change month,
+ * Enter/Space selects the focused date. Navigating into an adjacent month
+ * (arrow keys at a week's edge, or PageUp/PageDown) updates the displayed
+ * month to follow focus.
+ */
+declare function Calendar({ value, onChange, minDate, maxDate, 'aria-label': ariaLabel, }: CalendarProps): react.JSX.Element;
+
+interface DatePickerProps {
+    value: Date | null;
+    onChange: (date: Date) => void;
+    minDate?: Date;
+    maxDate?: Date;
+    placeholder?: string;
+    'aria-label': string;
+    disabled?: boolean;
+}
+/**
+ * DatePicker — a form field pairing a compact trigger with `Calendar`:
+ * `Popover` on desktop, a bottom-sheet `Drawer` on mobile (the platform's
+ * standard adaptive-surface pattern, matching `Menu`). Date-only (decision
+ * D6 in the mobile design-system plan) — time and range selection are future
+ * scope; recurrence UI stays plugin-side.
+ *
+ * Unlike `Menu`, the trigger is built in rather than supplied by the caller
+ * — a date picker is a form field (consistent with `Input`/`Select`), not an
+ * arbitrary action-menu trigger.
+ */
+declare function DatePicker({ value, onChange, minDate, maxDate, placeholder, 'aria-label': ariaLabel, disabled, }: DatePickerProps): react.JSX.Element;
+
+interface UseLongPressOptions {
+    /** Called once the press has been held for `delay` without exceeding `moveTolerance`. */
+    onLongPress: () => void;
+    /** Hold duration in ms before `onLongPress` fires. Default 500. */
+    delay?: number;
+    /** Accumulated pointer movement (px) that cancels a pending press. Default 10 —
+     *  a real finger jitters a couple of px on a still hold; this must be forgiving
+     *  of that or the gesture never fires. */
+    moveTolerance?: number;
+    /** How long (ms) after firing to swallow the click that may or may not follow.
+     *  Default 700. Time-boxed rather than "clear on next click" — iOS frequently
+     *  sends no click at all after a long hold, so a flag that only clears on the
+     *  next click stays armed forever and silently eats the user's next real tap. */
+    suppressClickMs?: number;
+    /** Fire `navigator.vibrate(10)` when the press triggers, where supported. Default true. */
+    vibrate?: boolean;
+    /** Skip entirely (hooks can't be called conditionally, so this is the escape hatch
+     *  for a caller whose long-press action isn't available in the current state). */
+    disabled?: boolean;
+}
+interface LongPressHandlers {
+    onPointerDown: (e: PointerEvent) => void;
+    onPointerMove: (e: PointerEvent) => void;
+    onPointerUp: (e: PointerEvent) => void;
+    onPointerCancel: (e: PointerEvent) => void;
+    onPointerLeave: (e: PointerEvent) => void;
+    onContextMenu: (e: MouseEvent) => void;
+    onClick: (e: MouseEvent) => void;
+    /** Spread onto the target element. Empty on devices whose primary pointer
+     *  isn't coarse (desktop mouse/trackpad) — see the coarse-pointer gate below. */
+    style: CSSProperties;
+}
+/**
+ * useLongPress — touch-and-hold gesture with the full suppression recipe a
+ * long-press needs to behave, not just a bare timer.
+ *
+ * A naive `setTimeout` started on `pointerdown` and cleared on `pointermove`
+ * fails in three specific ways this hook exists to fix:
+ *  1. Any movement at all cancels it — but a real finger jitters a few px even
+ *     on a "still" hold, so the gesture misfires constantly. `moveTolerance`
+ *     requires deliberate movement before cancelling.
+ *  2. `pointercancel` (the browser converting the touch into a scroll) isn't
+ *     handled — the timer survives and fires mid-scroll. Handled here.
+ *  3. Nothing suppresses the OS's own reaction to a long touch-hold: iOS shows
+ *     its link-preview callout, Android starts text selection or opens a
+ *     context menu, and either can fire *alongside* the gesture this hook
+ *     triggers. `onContextMenu` + the returned `style` (touch-callout,
+ *     user-select, touch-action) close all three, gated to coarse-pointer
+ *     devices only — unconditionally disabling `user-select` would break
+ *     mouse text selection on desktop, which never held this long-press to
+ *     begin with (see `onPointerDown`'s own `pointerType` check).
+ *
+ * The click that may or may not follow a fired long-press (iOS often sends
+ * none at all) is swallowed for `suppressClickMs`, not indefinitely — an
+ * unbounded suppression flag left armed by a browser that never sends that
+ * click silently eats the user's *next* unrelated tap on the same element.
+ */
+declare function useLongPress({ onLongPress, delay, moveTolerance, suppressClickMs, vibrate, disabled, }: UseLongPressOptions): LongPressHandlers;
+
+/**
+ * useDoubleTapHandler — fires `onDoubleTap` on a real double-click (desktop)
+ * or two taps within `DOUBLE_TAP_MS` (touch).
+ *
+ * Only safe when the *single* tap/click has no default action of its own to
+ * preempt — e.g. a colour swatch with nothing to cancel. If the single tap
+ * navigates, opens something, or otherwise does something a following double
+ * needs to be able to undo before it happens, use `useSingleOrDoubleTap`
+ * instead: this hook fires `onDoubleTap` only, leaving any single-tap handling
+ * to the caller's own `onClick`, which already ran immediately and can't be
+ * un-done here.
+ *
+ * The event is passed through to `onDoubleTap` rather than calling
+ * `preventDefault` internally — not every call site needs to cancel
+ * something, so the decision is left to the caller.
+ */
+declare function useDoubleTapHandler<E extends {
+    detail: number;
+}>(onDoubleTap: (e: E) => void): (e: E) => void;
+/**
+ * useSingleOrDoubleTap — for call sites where the single tap/click *does*
+ * have a default action (e.g. navigating) that a following double-tap must be
+ * able to preempt.
+ *
+ * A real double-click gets away with firing the single action immediately and
+ * only detecting the double afterward, because `e.detail === 2` is the
+ * browser's own resolved signal, arriving on the very click that matters. A
+ * touch double-tap has no equivalent "hold on, there might be a second one"
+ * signal — the only way to know is to wait out the window before committing
+ * to the single action, which is what this hook does: `onSingle` is deferred
+ * by `DOUBLE_TAP_MS` and only actually runs if no second tap arrives in that
+ * time. This means every single tap through this hook incurs that latency —
+ * only use it where a genuine double-tap gesture must be able to preempt the
+ * single action; `useDoubleTapHandler` above has no such delay.
+ */
+declare function useSingleOrDoubleTap<E extends {
+    detail: number;
+}>(onSingle: (e: E) => void, onDouble: (e: E) => void): (e: E) => void;
+
+declare const MOBILE_BREAKPOINT_PX = 768;
+/**
+ * useIsMobile — whether the viewport is at or below the platform's mobile
+ * breakpoint. SSR-safe: defaults to `false` (desktop) until the client mounts
+ * and reads the real viewport, avoiding a hydration mismatch on first paint.
+ */
+declare function useIsMobile(breakpointPx?: number): boolean;
+
+export { Avatar, type AvatarProps, Badge, type BadgeProps, type BadgeStatus, type BadgeVariant, type BannerVariant, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Calendar, type CalendarProps, Card, type CardProps, Checkbox, type CheckboxProps, CodeTextarea, type CodeTextareaProps, ConfirmDialog, type ConfirmDialogProps, DatePicker, type DatePickerProps, Dialog, type DialogProps, type DialogSize, DragHandleRow, type DragHandleRowProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, FormField, type FormFieldProps, type FormFieldRenderProps, Icon, type IconName, type IconProps, Input, type InputProps, type LongPressHandlers, MOBILE_BREAKPOINT_PX, Menu, type MenuEntry, type MenuItem, type MenuLabel, type MenuProps, type MenuSeparator, type NavTabItem, NavTabs, type NavTabsProps, OverlayHeader, type OverlayHeaderProps, PageHeader, type PageHeaderProps, Popover, type PopoverProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectProps, Sheet, type SheetProps, Spinner, type SpinnerProps, SplitPane, type SplitPaneProps, StatusBadge, type StatusBadgeProps, type StatusBadgeStatus, SystemBanner, type SystemBannerProps, type TabItem, Tabs, type TabsProps, TagInput, type TagInputProps, Textarea, type TextareaProps, type ToastContextValue, type ToastItem, ToastProvider, Toggle, type ToggleProps, Tooltip, type TooltipProps, type UseLongPressOptions, useDoubleTapHandler, useIsMobile, useLongPress, useOverlaySecondRow, useSingleOrDoubleTap, useToast };