twico-ui 1.5.0 → 1.7.0

package/dist/index.d.cts

@@ -1,5 +1,141 @@
 import * as React from 'react';
 
+interface TwicoProviderProps {
+  /** CSP nonce stamped on every injected `<style>` (for `style-src 'nonce-…'` without `unsafe-inline`). */
+  nonce?: string;
+  children?: React.ReactNode;
+}
+
+declare function TwicoProvider(props: TwicoProviderProps): React.JSX.Element;
+
+/** A friendly, partial token surface. Each entry maps to a `--<group>-<key>` CSS variable. */
+interface ThemeTokens {
+  /** `--color-*` (e.g. `{ primary: "#5b5bd6" }`). */
+  colors?: Record<string, string>;
+  /** `--space-*`. */
+  space?: Record<string, string>;
+  /** `--radius-*`. */
+  radius?: Record<string, string>;
+  /** `--font-*`. */
+  font?: Record<string, string>;
+  /** `--shadow-*`. */
+  shadow?: Record<string, string>;
+  /** Motion vars (e.g. `{ "ease-out": "…", "duration-base": "…" }`) — keyed by the full var suffix. */
+  motion?: Record<string, string>;
+}
+
+/** A CSS custom-property style object (`{ "--color-primary": "…" }`). */
+type Theme = Record<`--${string}`, string>;
+
+/** Map a partial token object onto a `--*` CSS-variable style object. */
+declare function createTheme(partial: ThemeTokens): Theme;
+
+interface ThemeProviderProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** A `createTheme()` result, or a raw partial token object. */
+  theme?: Theme | ThemeTokens;
+  /** `"inline"` sets the vars inline (SSR-safe); `"stylesheet"` injects a scoped, nonce-aware rule. @default "inline" */
+  mode?: "inline" | "stylesheet";
+}
+
+declare function ThemeProvider(props: ThemeProviderProps): React.JSX.Element;
+
+interface FormProps extends React.FormHTMLAttributes<HTMLFormElement> {
+  /** Submit handler — runs after `preventDefault()` (unless `preventDefault={false}`). */
+  onSubmit?: (e: React.FormEvent<HTMLFormElement>) => void;
+  /** Call `event.preventDefault()` before `onSubmit`. @default true */
+  preventDefault?: boolean;
+  /** Disable every control (via a `<fieldset disabled>`) and set `aria-busy`. @default false */
+  loading?: boolean;
+  /** Disable every control (via a `<fieldset disabled>`). @default false */
+  disabled?: boolean;
+  /** Vertical gap between children as a spacing-scale step (e.g. 4 → var(--space-4)). */
+  gap?: number;
+}
+
+declare const Form: React.ForwardRefExoticComponent<FormProps & React.RefAttributes<HTMLFormElement>>;
+
+interface VisuallyHiddenProps extends React.HTMLAttributes<HTMLElement> {
+  /** Element to render. @default "span" */
+  as?: React.ElementType;
+}
+
+declare const VisuallyHidden: React.ForwardRefExoticComponent<
+  VisuallyHiddenProps & React.RefAttributes<HTMLElement>
+>;
+
+interface PortalProps {
+  children?: React.ReactNode;
+}
+
+declare function Portal(props: PortalProps): React.ReactPortal | React.ReactNode | null;
+
+interface ColorSchemeScriptOptions {
+  /** localStorage key holding the theme (matches useColorScheme). @default "twico-theme" */
+  storageKey?: string;
+  /** How the scheme is applied: the `dark` class, or a `[data-…]` attribute value. @default "class" */
+  attribute?: string;
+  /** Scheme to use when nothing is stored (skips the prefers-color-scheme probe). */
+  defaultScheme?: "light" | "dark";
+}
+
+interface ColorSchemeScriptProps extends ColorSchemeScriptOptions {
+  /** CSP nonce for the inline `<script>`. */
+  nonce?: string;
+}
+
+/** The theme-init IIFE as a string, for consumers who inject the script themselves. */
+declare function getColorSchemeScript(options?: ColorSchemeScriptOptions): string;
+
+/** A `<script>` for the SSR `<head>` that applies the persisted color scheme before first paint. */
+declare function ColorSchemeScript(props: ColorSchemeScriptProps): React.JSX.Element;
+
+type KbdProps = React.HTMLAttributes<HTMLElement>;
+
+declare const Kbd: React.ForwardRefExoticComponent<KbdProps & React.RefAttributes<HTMLElement>>;
+
+type PreProps = React.HTMLAttributes<HTMLPreElement>;
+
+declare const Pre: React.ForwardRefExoticComponent<PreProps & React.RefAttributes<HTMLPreElement>>;
+
+interface AnchorProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  /** Element to render (e.g. a router Link). @default "a" */
+  as?: React.ElementType;
+  /** Open in a new tab with rel="noopener noreferrer" and a ↗ affix. @default false */
+  external?: boolean;
+}
+
+declare const Anchor: React.ForwardRefExoticComponent<AnchorProps & React.RefAttributes<HTMLAnchorElement>>;
+
+interface LabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+  /** Id of the control this labels. */
+  htmlFor?: string;
+  /** Append a danger-colored asterisk. @default false */
+  required?: boolean;
+  /** @default "md" */
+  size?: "sm" | "md" | "lg";
+}
+
+declare const Label: React.ForwardRefExoticComponent<LabelProps & React.RefAttributes<HTMLLabelElement>>;
+
+interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "alt"> {
+  /** Image source URL. */
+  src?: string;
+  /** Alternative text (required for accessibility; pass "" for decorative images). */
+  alt: string;
+  /** object-fit value. */
+  fit?: "cover" | "contain" | "fill" | "none" | "scale-down";
+  /** Border radius token (e.g. "md", "lg", "full"). */
+  radius?: string;
+  /** CSS aspect-ratio (e.g. "16/9"). */
+  aspectRatio?: string;
+  /** Source swapped in if the image fails to load. */
+  fallback?: string;
+  /** @default "lazy" */
+  loading?: "lazy" | "eager";
+}
+
+declare const Image: React.ForwardRefExoticComponent<ImageProps & React.RefAttributes<HTMLImageElement>>;
+
 /**
  * Vertically stacked, expandable disclosure panels with smooth height animation.
  *
@@ -288,6 +424,8 @@ interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title">
   title?: React.ReactNode;
   /** Muted subtitle under the title. */
   subtitle?: React.ReactNode;
+  /** Header actions rendered top-right, opposite the title/subtitle (e.g. a button or menu). */
+  actions?: React.ReactNode;
   /** Footer content (e.g. action buttons). */
   footer?: React.ReactNode;
   /** Visual style. @default "elevated" */
@@ -449,6 +587,8 @@ interface Option {
   label: string;
   /** Optional second line shown under the label. */
   description?: string;
+  /** Disable this option — not selectable, skipped by keyboard navigation. */
+  disabled?: boolean;
 }
 
 /** A labeled group of options (or bare string values). */
@@ -494,6 +634,16 @@ interface ComboboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>
   portal?: boolean;
   /** Minimum popover width in px when portaled (useful when the control is narrow). @default 0 */
   minWidth?: number;
+  /** Called with the raw query on every keystroke — drive a debounced remote fetch (with `loading` + `filter={false}`). */
+  onInputChange?: (query: string) => void;
+  /** Client-side filtering: `false` shows options as-is (server-ranked); a function replaces the default label/description match. */
+  filter?: boolean | ((option: ComboboxOption, query: string) => boolean);
+  /** Show a loading row instead of the option list / empty state. @default false */
+  loading?: boolean;
+  /** Text shown when no options match. @default "No results found" */
+  emptyText?: string;
+  /** Name for a hidden form field so the selected value participates in native form submission. */
+  name?: string;
   /** Composed with the field's open-on-focus behavior — your handler runs first. */
   onFocus?: React.FocusEventHandler<HTMLInputElement>;
   /** Composed with the field's keyboard navigation (Arrows/Enter/Escape) — your handler runs first; call `event.preventDefault()` to suppress it. */
@@ -541,6 +691,8 @@ interface CommandPaletteProps extends React.HTMLAttributes<HTMLDivElement> {
   commands: Command[];
   placeholder?: string;
   emptyText?: string;
+  /** Accessible name for the search input. @default "Command palette search" */
+  searchLabel?: string;
 }
 
 declare function CommandPalette(props: CommandPaletteProps): React.JSX.Element | null;
@@ -702,6 +854,10 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
    *  rearrange only the movable, unpinned columns and leave pinned/actions columns in place.
    *  @default false */
   disableColumnReorder?: boolean;
+  /** Message rendered when there are no rows (filter-aware default: "No rows match your filters" when a filter/quick-search is active, else "No rows"). */
+  emptyMessage?: React.ReactNode;
+  /** Render a custom empty state inside the table body (e.g. the shipped `<EmptyState/>`). Overrides `emptyMessage`. */
+  renderEmpty?: () => React.ReactNode;
   /** Disable column resizing. When enabled (the default off), drag a header's right edge to resize a
    *  column, or **double-click** that edge to auto-fit the column to its widest visible content
    *  (header + rendered cells), Excel-style. @default false */
@@ -825,6 +981,8 @@ interface DatatableColumn<T = any> {
   pinned?: "left" | "right";
   /** Allow drag-to-resize of this column. @default true */
   resizable?: boolean;
+  /** Allow drag / menu / keyboard reorder of this column (independent of the table-wide `disableColumnReorder`). @default true */
+  reorderable?: boolean;
   /** Summary-footer aggregation: a preset, or a function over the column's values. */
   aggregation?: "sum" | "avg" | "min" | "max" | "count" | ((values: any[], rows: T[]) => React.ReactNode);
   /** Format an aggregation result for the footer (falls back to valueFormatter). */
@@ -969,6 +1127,12 @@ interface DateRangePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   locale?: string;
   /** First day of week: 0 = Sunday … 6 = Saturday. @default 0 */
   weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  /** Earliest selectable date (inclusive); earlier days are disabled. */
+  min?: Date;
+  /** Latest selectable date (inclusive); later days are disabled. */
+  max?: Date;
+  /** Predicate to disable arbitrary dates (return true to disable). */
+  disabledDate?: (date: Date) => boolean;
   /** Disable all interaction (the popover cannot be opened). @default false */
   disabled?: boolean;
   /** Color intent for the focus/open accent. @default "primary" */
@@ -1068,15 +1232,16 @@ declare function EmptyState(props: EmptyStateProps): React.JSX.Element;
 /**
  * Shared form-field chrome (label, hint, error, required asterisk) that wraps ANY control.
  *
- * `Field` is layout-only: it renders the label + your `children` + a single hint/error line,
- * reusing the exact `.twc-field` markup Input/Select inline so every field looks identical.
- * Wiring the control to the messages stays the consumer's job — point your control's
- * `aria-describedby` at the exposed hint/error id (`` `${id}-desc` ``) and set `aria-invalid`
- * when `error` is present. `error` replaces `hint` when both are given (error wins).
+ * `Field` renders the label + your `children` + a single hint/error line, reusing the exact
+ * `.twc-field` markup Input/Select inline so every field looks identical. When `children` is a
+ * SINGLE element, Field auto-wires it: it sets `aria-describedby` (merged with any the child
+ * already has) to the hint/error id (`` `${id}-desc` ``) and `aria-invalid` when `error` is
+ * present (never clobbering a child's explicit `aria-invalid`). Multiple/fragment/string children
+ * keep manual wiring. `error` replaces `hint` when both are given (error wins).
  *
  * @example
  * <Field label="Email" hint="We never share it." htmlFor="email" id="email-field">
- *   <input id="email" aria-describedby="email-field-desc" />
+ *   <input id="email" />
  * </Field>
  */
 interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "id"> {
@@ -1129,6 +1294,12 @@ interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "on
   value?: File[];
   /** Uncontrolled initial file list. @default [] */
   defaultValue?: File[];
+  /** Max size per file in bytes; larger files are rejected (drag + browse). */
+  maxSize?: number;
+  /** Max number of files retained (multiple mode); extra files are rejected. */
+  maxFiles?: number;
+  /** Called with the files that failed validation: `{ file, reason }` where reason is "type" | "size" | "count". */
+  onReject?: (rejections: Array<{ file: File; reason: "type" | "size" | "count" }>) => void;
   onChange?: (files: File[]) => void;
 }
 
@@ -1175,11 +1346,18 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
   size?: "sm" | "md" | "lg";
   /** Color intent for the focus/open accent. @default "primary" */
   tone?: Tone;
-  /** Icon node inside the field, leading edge (prefix). */
+  /** Icon-only node inside the field, leading edge — for a bordered text addon use `leftAddon`. */
   leftIcon?: React.ReactNode;
   /** Optional suffix icon/node inside the field, trailing edge. For `type="password"`, omitting this
-   *  shows a built-in reveal/hide eye toggle; providing `rightIcon` replaces it. */
+   *  shows a built-in reveal/hide eye toggle; providing `rightIcon` replaces it. Icon-only — for a
+   *  bordered text addon use `rightAddon`. */
   rightIcon?: React.ReactNode;
+  /** Bordered text addon flush against the leading edge (e.g. `https://`, `@`) — distinct from the inline `leftIcon`. */
+  leftAddon?: React.ReactNode;
+  /** Bordered text addon flush against the trailing edge (e.g. `.00`, `kg`, `%`). */
+  rightAddon?: React.ReactNode;
+  /** With `maxLength`, render a live `current / max` character counter on the hint/error line; danger-toned near the limit. @default false */
+  showCount?: boolean;
 }
 
 declare function Input(props: InputProps): React.JSX.Element;
@@ -1248,7 +1426,7 @@ interface ListItemData {
   onClick?: (e: React.MouseEvent) => void;
   /** Makes the row a link. */
   href?: string;
-  /** Highlight as selected. */
+  /** Highlight as selected — also sets `aria-current="page"` on link/button rows. */
   active?: boolean;
 }
 
@@ -1262,6 +1440,8 @@ interface ListProps extends React.HTMLAttributes<HTMLUListElement> {
   items: ListItemData[];
   /** Drop the card chrome (borderless, transparent). @default false */
   plain?: boolean;
+  /** Shown as a centered zero-state row when `items` is empty. @default "Nothing here yet" */
+  emptyMessage?: React.ReactNode;
 }
 
 declare function List(props: ListProps): React.JSX.Element;
@@ -1303,6 +1483,16 @@ interface MultiSelectProps extends Omit<React.InputHTMLAttributes<HTMLInputEleme
   portal?: boolean;
   /** Minimum popover width in px when portaled (useful when the control is narrow). @default 0 */
   minWidth?: number;
+  /** Show a loading row instead of the option list / empty state. @default false */
+  loading?: boolean;
+  /** Text shown when no options match. @default "No results found" */
+  emptyText?: string;
+  /** Name for hidden form fields (one per selected value) for native form submission. */
+  name?: string;
+  /** Cap the number of selectable values; once reached, unselected options become disabled. */
+  max?: number;
+  /** Collapse chips after N into a "+K more" pill. */
+  maxTagCount?: number;
   /** Composed with the field's open-on-focus behavior — your handler runs first. */
   onFocus?: React.FocusEventHandler<HTMLInputElement>;
   /** Composed with the field's keyboard navigation (Arrows/Enter/Escape/Backspace) — your handler runs first; call `event.preventDefault()` to suppress it. */
@@ -1381,6 +1571,8 @@ interface PaginationProps extends Omit<React.HTMLAttributes<HTMLElement>, "onCha
   showPageJumper?: boolean;
   /** Label before the jump input. @default "Go to" */
   jumperLabel?: React.ReactNode;
+  /** Accessible label for each numbered page button (for i18n). @default (n) => `Page ${n}` */
+  getPageLabel?: (page: number) => string;
 }
 
 declare function Pagination(props: PaginationProps): React.JSX.Element;
@@ -1456,15 +1648,68 @@ interface RadioProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
 
 declare function Radio(props: RadioProps): React.JSX.Element;
 
+interface RadioGroupOption {
+  /** Submitted value for this choice. */
+  value: string;
+  /** Visible label. */
+  label?: React.ReactNode;
+  /** Secondary text under the label. */
+  description?: React.ReactNode;
+  /** Disable just this option. */
+  disabled?: boolean;
+}
+
+/**
+ * Grouped radios with one controlled value, a `role="radiogroup"` container, a hoisted
+ * group label/hint/error, and a shared `name`. Provide choices via `options` or by passing
+ * `<Radio>` children (their `name`/`checked`/`onChange` are injected). Native inputs give
+ * roving tabindex + Arrow-key selection for free.
+ *
+ * @startingPoint section="Inputs" subtitle="Grouped radios with one value" viewport="700x220"
+ */
+interface RadioGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
+  /** Shared `name` for the radios (auto-generated when omitted). */
+  name?: string;
+  /** Controlled selected value. */
+  value?: string;
+  /** Uncontrolled initial value. */
+  defaultValue?: string;
+  /** Called with the newly-selected value. */
+  onChange?: (value: string) => void;
+  /** Choices (alternative to passing `<Radio>` children). */
+  options?: RadioGroupOption[];
+  /** `<Radio>` children (alternative to `options`); their group props are injected. */
+  children?: React.ReactNode;
+  /** Group label (rendered as the radiogroup's accessible name). */
+  label?: React.ReactNode;
+  /** Helper text below the group. */
+  hint?: React.ReactNode;
+  /** Error text below the group; sets `aria-invalid` and is announced once for the whole group. */
+  error?: React.ReactNode;
+  /** Lay the radios in a column or a wrapping row. @default "vertical" */
+  orientation?: "vertical" | "horizontal";
+  /** Disable every radio in the group. @default false */
+  disabled?: boolean;
+  /** Mark the group required (native `required` on the radios + `aria-required`). @default false */
+  required?: boolean;
+  /** Control size applied to each radio. @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Color intent applied to each radio. @default "primary" */
+  tone?: Tone;
+}
+
+declare function RadioGroup(props: RadioGroupProps): React.JSX.Element;
+
 /**
  * Star rating — interactive (click/hover) or read-only display.
  *
  * @startingPoint section="Inputs" subtitle="Star rating" viewport="700x90"
  */
 interface RatingProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue" | "color"> {
-  /** Controlled value (0…count). */
+  /** Controlled value (0…count; 0 means "no rating"). A fractional value renders a partial
+   *  star fill (display) — interactive click/keyboard selection is integer-only. */
   value?: number;
-  /** Uncontrolled initial value. @default 0 */
+  /** Uncontrolled initial value (0 means "no rating"). @default 0 */
   defaultValue?: number;
   /** Number of stars. @default 5 */
   count?: number;
@@ -1474,12 +1719,19 @@ interface RatingProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChan
   tone?: Tone;
   /** Explicit filled-star color; overrides `tone` when set. */
   color?: string;
-  /** Display only, no interaction. @default false */
+  /** Display only — renders a single static value as `role="img"` named "<value> out of <count> stars"
+   *  (overridable via `aria-label`), not a radiogroup of radios. @default false */
   readOnly?: boolean;
   /** Disable all interaction and dim the control. @default false */
   disabled?: boolean;
-  /** Show the numeric value beside the stars. @default false */
+  /** Show the numeric value beside the stars (clean integer, or one decimal for fractional). @default false */
   showValue?: boolean;
+  /** Allow clearing back to 0 — clicking the selected star, or pressing Delete/Backspace, resets to "no rating". @default true */
+  clearable?: boolean;
+  /** Custom formatter for the `showValue` badge and the read-only accessible label. Defaults to a clean integer, or one decimal for fractional values. */
+  format?: (value: number) => React.ReactNode;
+  /** Name for a hidden form field so the value participates in native form submission. */
+  name?: string;
   onChange?: (value: number) => void;
 }
 
@@ -1527,6 +1779,14 @@ interface SelectProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, "onC
   portal?: boolean;
   /** Minimum popover width in px when portaled (useful when the trigger is narrow). @default 0 */
   minWidth?: number;
+  /** Pin the popover to the trigger's width. Set false to size it to the widest option (clamped to the viewport). @default true */
+  matchTriggerWidth?: boolean;
+  /** Show a loading row instead of the option list / empty state (e.g. while fetching options). @default false */
+  loading?: boolean;
+  /** Text shown when no options match. @default "No results found" */
+  emptyText?: string;
+  /** Name for a hidden form field so the selected value participates in native form submission. */
+  name?: string;
 }
 
 /** Alias of the shared {@link Option} type (kept for backward-compatible imports). */
@@ -1626,16 +1886,22 @@ interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChan
   hint?: React.ReactNode;
   /** Error message shown below the track — turns it red (sets `aria-invalid`) and replaces the hint. */
   error?: React.ReactNode;
-  /** Controlled value. */
-  value?: number;
-  /** Uncontrolled initial value. @default 0 */
-  defaultValue?: number;
+  /** Controlled value. A `[number, number]` tuple enables dual-thumb range mode. Clamped into [min, max]. */
+  value?: number | [number, number];
+  /** Uncontrolled initial value (a tuple enables range mode). Clamped into [min, max]. @default 0 */
+  defaultValue?: number | [number, number];
+  /** Force dual-thumb range mode even without a tuple value (defaults the range to [min, max]). @default false */
+  range?: boolean;
   /** @default 0 */
   min?: number;
   /** @default 100 */
   max?: number;
   /** @default 1 */
   step?: number;
+  /** Large-step increment for PageUp/PageDown. @default Math.max(step, (max - min) / 10) */
+  pageStep?: number;
+  /** Decimal places for the default display + aria value; derived from `step` when unset. */
+  precision?: number;
   disabled?: boolean;
   /** Show the current value at the top-right. @default true */
   showValue?: boolean;
@@ -1643,9 +1909,13 @@ interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChan
   showTicks?: boolean;
   /** Color intent. @default "primary" */
   tone?: Tone;
-  /** Format the displayed value (label + bubble). */
+  /** Format the displayed value (label + bubble). If it returns a node, pair it with `getAriaValueText`. */
   formatValue?: (value: number) => React.ReactNode;
-  onChange?: (value: number) => void;
+  /** Human-readable value for assistive tech (`aria-valuetext`) — use when `formatValue` returns a node. */
+  getAriaValueText?: (value: number) => string;
+  /** Name for hidden form field(s) so the value participates in native form submission. */
+  name?: string;
+  onChange?: (value: number | [number, number]) => void;
 }
 
 declare function Slider(props: SliderProps): React.JSX.Element;
@@ -1785,6 +2055,16 @@ interface TableProps<T = any> extends React.HTMLAttributes<HTMLDivElement> {
   stickyHeader?: boolean;
   /** Cap the table height and give it its own vertical scroll area (CSS length or number of px). */
   maxHeight?: number | string;
+  /** Show shimmering skeleton rows instead of data (e.g. while fetching); sets `aria-busy`. @default false */
+  loading?: boolean;
+  /** Number of skeleton rows to render while `loading`. @default 8 */
+  loadingRows?: number;
+  /** Rendered as a single full-width row when `rows` is empty. @default "No data" */
+  emptyMessage?: React.ReactNode;
+  /** Accessible name applied to the `<table>` (not the wrapper). A raw `aria-label` prop takes precedence. */
+  ariaLabel?: string;
+  /** Renders a visually-hidden `<caption>` naming the table. */
+  caption?: React.ReactNode;
 }
 
 interface TableColumn<T = any> {
@@ -1875,9 +2155,20 @@ interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement
   size?: "sm" | "md" | "lg";
   /** Color intent for the focus/open accent. @default "primary" */
   tone?: Tone;
+  /** Grow to fit content between `minRows` and `maxRows` (resize handle hidden). @default false */
+  autosize?: boolean;
+  /** Minimum rows when `autosize` (falls back to `rows`). */
+  minRows?: number;
+  /** Maximum rows when `autosize`; taller content scrolls. */
+  maxRows?: number;
+  /** With `maxLength`, render a live `current / max` character counter; danger-toned near the limit. @default false */
+  showCount?: boolean;
 }
 
-declare function Textarea(props: TextareaProps): React.JSX.Element;
+/** Forwards `ref` to the inner `<textarea>`. */
+declare const Textarea: React.ForwardRefExoticComponent<
+  TextareaProps & React.RefAttributes<HTMLTextAreaElement>
+>;
 
 interface TimelineItem {
   /** Event title. */
@@ -1915,9 +2206,11 @@ interface ToastProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title">
   title?: React.ReactNode;
   /** Override the tone icon. */
   icon?: React.ReactNode;
-  /** Show close button + handle dismissal. */
+  /** Renders the close button AND is the dismissal handler. The Toast is controlled — it never
+   *  removes itself, so BOTH the close button and `duration` auto-dismiss require this. */
   onClose?: () => void;
-  /** Auto-dismiss after this many ms (paused on hover/focus). `0`/`Infinity` keeps it open. @default 4500 */
+  /** Auto-dismiss after this many ms (paused on hover/focus). **No-op unless `onClose` is provided** —
+   *  the timer's only action is to call `onClose`. `0`/`Infinity` keeps it open. @default 4500 */
   duration?: number;
   children?: React.ReactNode;
 }
@@ -2108,7 +2401,7 @@ interface BoxProps extends React.HTMLAttributes<HTMLElement> {
   shadow?: string;
 }
 
-declare function Box(props: BoxProps): React.JSX.Element;
+declare const Box: React.ForwardRefExoticComponent<BoxProps & React.RefAttributes<HTMLElement>>;
 
 /** Centered, max-width content wrapper with responsive horizontal padding. */
 interface ContainerProps extends React.HTMLAttributes<HTMLElement> {
@@ -2126,7 +2419,7 @@ interface ContainerProps extends React.HTMLAttributes<HTMLElement> {
   padded?: boolean;
 }
 
-declare function Container(props: ContainerProps): React.JSX.Element;
+declare const Container: React.ForwardRefExoticComponent<ContainerProps & React.RefAttributes<HTMLElement>>;
 
 /** Responsive column counts per breakpoint (base + sm/md/lg/xl at 640/768/1024/1280px). */
 type ResponsiveColumns = { base?: number; sm?: number; md?: number; lg?: number; xl?: number };
@@ -2159,7 +2452,7 @@ interface GridProps extends React.HTMLAttributes<HTMLElement> {
   justifyContent?: React.CSSProperties["justifyContent"];
 }
 
-declare function Grid(props: GridProps): React.JSX.Element;
+declare const Grid: React.ForwardRefExoticComponent<GridProps & React.RefAttributes<HTMLElement>>;
 
 /** Flex layout primitive — rows or columns with token-based gaps. */
 interface StackProps extends React.HTMLAttributes<HTMLElement> {
@@ -2199,7 +2492,7 @@ interface StackProps extends React.HTMLAttributes<HTMLElement> {
   divider?: React.ReactNode;
 }
 
-declare function Stack(props: StackProps): React.JSX.Element;
+declare const Stack: React.ForwardRefExoticComponent<StackProps & React.RefAttributes<HTMLElement>>;
 
 /** Inline code, or a scrollable multi-line block with an optional copy button. */
 interface CodeProps extends React.HTMLAttributes<HTMLElement> {
@@ -2253,7 +2546,7 @@ interface HeadingProps extends React.HTMLAttributes<HTMLElement> {
   lineClamp?: number;
 }
 
-declare function Heading(props: HeadingProps): React.JSX.Element;
+declare const Heading: React.ForwardRefExoticComponent<HeadingProps & React.RefAttributes<HTMLElement>>;
 
 /** Body text with token sizes and semantic color tones. Renders <p> by default. */
 interface TextProps extends React.HTMLAttributes<HTMLElement> {
@@ -2278,7 +2571,7 @@ interface TextProps extends React.HTMLAttributes<HTMLElement> {
   lineClamp?: number;
 }
 
-declare function Text(props: TextProps): React.JSX.Element;
+declare const Text: React.ForwardRefExoticComponent<TextProps & React.RefAttributes<HTMLElement>>;
 
 /** SSR-safe `useLayoutEffect` (falls back to `useEffect` on the server). */
 declare const useIsomorphicLayoutEffect: typeof React.useLayoutEffect;
@@ -2429,6 +2722,8 @@ declare function useId(prefix?: string): string;
 interface UseFocusTrapOptions {
   /** Restore focus to the previously-focused element when the trap deactivates. @default true */
   restoreFocus?: boolean;
+  /** Element to focus on activate instead of the first focusable — a ref or a `() => Element | null`. */
+  initialFocus?: React.RefObject<HTMLElement | null> | (() => HTMLElement | null | undefined);
 }
 
 /**
@@ -2449,4 +2744,4 @@ declare function useFocusTrap<T extends HTMLElement = HTMLElement>(
  */
 declare function usePortal(): (node: React.ReactNode) => React.ReactPortal | React.ReactNode | null;
 
-export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, Dialog, type DialogProps, Divider, type DividerProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, Grid, type GridProps, Heading, type HeadingProps, type HeadingSize, IconButton, type IconButtonProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, type PolymorphicAs, Popover, type PopoverProps, Progress, type ProgressProps, Radio, type RadioProps, Rating, type RatingProps, type ResponsiveColumns, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Stack, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextProps, type TextTone, Textarea, type TextareaProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };
+export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, Dialog, type DialogProps, Divider, type DividerProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, Form, type FormProps, Grid, type GridProps, Heading, type HeadingProps, type HeadingSize, IconButton, type IconButtonProps, Image, type ImageProps, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, type PolymorphicAs, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, Rating, type RatingProps, type ResponsiveColumns, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Stack, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };