twico-ui 1.38.0 → 1.40.0

package/dist/index.d.cts

@@ -138,6 +138,73 @@ interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "al
 
 declare const Image: React.ForwardRefExoticComponent<ImageProps & React.RefAttributes<HTMLImageElement>>;
 
+/** The zoom API passed to a `controls` render function. */
+interface ImageViewerControlsApi {
+  /** Current zoom level. */
+  zoom: number;
+  /** Zoom in one `step`, centered. */
+  zoomIn: () => void;
+  /** Zoom out one `step`, centered. */
+  zoomOut: () => void;
+  /** Reset to `minZoom` and re-center. */
+  reset: () => void;
+  /** Whether zooming in further is possible. */
+  canZoomIn: boolean;
+  /** Whether zooming out further is possible. */
+  canZoomOut: boolean;
+}
+
+/**
+ * A zoomable / pannable image on a fixed stage: pointer-anchored wheel + pinch zoom, drag-to-pan when zoomed
+ * (clamped to the stage), `+` / `-` / `0` keys, and double-click to toggle. Wheel uses a non-passive listener
+ * so the page/dialog behind never scrolls. Set the stage size via `style`/`className` on the root.
+ *
+ * @startingPoint section="Data display" subtitle="Zoomable image viewer" viewport="700x460"
+ */
+interface ImageViewerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
+  /** Image source. */
+  src?: string;
+  /** Accessible description (required). */
+  alt: string;
+  /** Minimum zoom (also the reset level). @default 1 */
+  minZoom?: number;
+  /** Maximum zoom. @default 8 */
+  maxZoom?: number;
+  /** Zoom increment for the wheel / keys / buttons. @default 0.25 */
+  step?: number;
+  /** Controlled zoom level. Pair with `onZoomChange` and echo it back into this prop — pan/anchor math runs
+   *  against the rendered zoom, so a controlled value that never updates would drift. */
+  zoom?: number;
+  /** Initial zoom for the uncontrolled case. @default 1 */
+  defaultZoom?: number;
+  /** Fired with the new zoom level whenever it changes. */
+  onZoomChange?: (zoom: number) => void;
+  /** Zoom level a double-click toggles to (from `minZoom`). @default 2 */
+  doubleClickZoom?: number;
+  /** Built-in zoom in/out/reset controls, or your own. Pass a node, a render function receiving the zoom API,
+   *  or `false` to hide them. @default the built-in controls */
+  controls?: React.ReactNode | ((api: ImageViewerControlsApi) => React.ReactNode) | false;
+  /** How the image fills the stage at 1×. #414: `"scale-down"`/`"none"` (like `Image`) avoid upscaling a small
+   *  image; pan bounds follow the rendered image box. @default "contain" */
+  fit?: "contain" | "cover" | "scale-down" | "none";
+  /** #414: reactive zoom state — pair with `controls={false}` to drive your own toolbar's disabled states
+   *  (the imperative `ref` gives the actions). Fires on mount and whenever the state changes. */
+  onStateChange?: (state: ImageViewerState) => void;
+  /** #414: border-radius token for the stage, e.g. `"md"`, `"lg"`, `"full"`. (Or set the `--twc-iv-radius` /
+   *  `--twc-iv-bg` custom properties on the root.) @default "lg" */
+  radius?: string;
+}
+
+/** #414: the reactive state reported by `onStateChange`. */
+interface ImageViewerState {
+  zoom: number;
+  canZoomIn: boolean;
+  canZoomOut: boolean;
+}
+
+/** #414: `ref` exposes the zoom API ({@link ImageViewerControlsApi}) so a host toolbar can drive it. */
+declare const ImageViewer: React.ForwardRefExoticComponent<ImageViewerProps & React.RefAttributes<ImageViewerControlsApi>>;
+
 /**
  * Vertically stacked, expandable disclosure panels with smooth height animation.
  *
@@ -392,6 +459,17 @@ interface AvatarMenuProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "t
   showName?: boolean;
   /** Show a chevron in the trigger (defaults to `showName`). */
   showChevron?: boolean;
+  /** #402: stretch the trigger to full width — the name/subtitle column grows and the chevron pins to the
+   *  inline-end — for a sidebar footer account row (pair with `Sidebar footerInset={false}`). In fullWidth mode
+   *  the trigger uses a `radius-md` (not pill) and the menu matches the trigger width. @default false */
+  fullWidth?: boolean;
+  /** #416: fully replace the built-in menu header (avatar + name + subtitle). */
+  header?: React.ReactNode;
+  /** #416: extra content appended under the name/subtitle in the built-in menu header (e.g. a presence line or
+   *  role badge) — menu only, not the trigger. Ignored when `header` is set. */
+  headerExtra?: React.ReactNode;
+  /** #416: menu popup width in px. @default 240 (or the trigger width when `fullWidth`) */
+  menuWidth?: number;
   /** Menu alignment to the trigger. @default "end" */
   align?: "start" | "end";
 }
@@ -466,6 +544,17 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   loading?: boolean;
   /** Stretch to fill the container width. @default false */
   fullWidth?: boolean;
+  /** #398: when `disabled`, stay in the tab order (render `aria-disabled` instead of native `disabled`) so a
+   *  wrapping `Tooltip` explaining *why* it's disabled is reachable by keyboard. Click and Enter/Space are
+   *  still blocked and the disabled styling still applies. @default false */
+  focusableWhenDisabled?: boolean;
+  /** #405: toggle "on" state — sets `aria-pressed` and shows a soft fill + border in the current `tone`
+   *  (works with any `variant`). Omit for a plain (non-toggle) button. @default undefined */
+  pressed?: boolean;
+  /** #411: tone of the pressed ("on") fill — the full status `Tone` scale, so a toggle can carry its own
+   *  selected-state meaning (e.g. success/warning/info/neutral) while `tone` stays `ActionTone` for the
+   *  unpressed action look. Defaults to `tone`. @default undefined */
+  pressedTone?: Tone;
   /** Render as a different element (e.g. "a"). @default "button" */
   as?: "button" | "a";
   /** Link destination — only used with as="a"; scheme-sanitized (javascript:/data:/vbscript: render without href). */
@@ -1924,6 +2013,13 @@ 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;
+  /** #403: table-level column defaults, shallow-merged **under** each column definition before
+   *  normalisation (built-in defaults < `defaultColumn` < the column). A per-column value always wins.
+   *  Set shared flags once instead of repeating them — e.g. a fixed-layout grid:
+   *  `defaultColumn={{ sortable: false, filterable: false, hideable: false, pinnable: false, groupable: false,
+   *  resizable: false, reorderable: false, wrappable: false, disableColumnMenu: true }}`. Like TanStack Table's
+   *  `defaultColumn` / AG Grid's `defaultColDef`. The smart Columns/Filters toolbar buttons follow it too. @default undefined */
+  defaultColumn?: Partial<DatatableColumn<T>>;
   /** 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`. */
@@ -1980,6 +2076,15 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
    *  Shift+Click / Shift+Arrow extend a range from an anchor; selected cells expose `aria-selected` and the
    *  grid is `aria-multiselectable` with `aria-activedescendant` on the active cell. @default "none" */
   selectionMode?: "none" | "row" | "cell";
+  /** #392: keyboard cell-navigation model (WAI-ARIA APG grid pattern), independent of `selectionMode`.
+   *  - `"cell"` (default): arrow keys move focus to the `<td>`; today's behaviour, unchanged.
+   *  - `"widget"`: when a data cell holds exactly **one** interactive control (a toggle button, link, chip,
+   *    switch or checkbox), arrow keys focus that control so **Enter/Space** act on it, and the grid body
+   *    becomes a **single Tab stop** (every other in-cell control is `tabindex=-1`) instead of one stop per
+   *    control. A cell with several controls enters an interaction mode on **Enter/F2** (Tab moves within the
+   *    cell, **Escape** returns to the cell). Text inputs/selects (editing) and checkbox-selection / row-expand
+   *    controls are unaffected. @default "cell" */
+  cellNavigation?: "cell" | "widget";
   /** Fired when a row is clicked in "row" selection mode: (row, key). */
   onRowClick?: (row: T, key: string | number) => void;
   /** #324: controlled highlighted row key for `selectionMode="row"`. When provided, the grid highlights THIS
@@ -1989,17 +2094,32 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
   activeRowId?: string | number | null;
   /** #324: scroll the controlled active row into view when `activeRowId` changes. @default true */
   scrollActiveRowIntoView?: boolean;
+  /** #395: controlled active cell ({ key, field } | null), independent of `selectionMode`. In "cell" mode it
+   *  drives the highlight; in any mode it is the target for `scrollActiveCellIntoView`. Pass `null` to clear.
+   *  Lets a host step through specific cells (next changed cell, next validation error, find-in-grid). */
+  activeCell?: { key: string | number; field: string } | null;
+  /** #395: reveal the `activeCell` inside the grid's own scroller (both axes, honouring the sticky header and
+   *  pinned columns; never scrolls the page). Re-applied when `rows` change, so a server-mode page switch or a
+   *  virtualized mount lands on the cell. Pass an object to center it. @default false */
+  scrollActiveCellIntoView?: boolean | { block?: "nearest" | "center"; inline?: "nearest" | "center" };
   /** Fired when a cell is clicked in "cell" selection mode: (value, row, field). */
   onCellClick?: (value: any, row: T, field: string) => void;
   /** Fired when the active cell changes: ({ key, field } | null). */
   onActiveCellChange?: (cell: { key: string | number; field: string } | null) => void;
+  /** #396: fired at every inline-edit transition so a host can, for example, stand down its own keyboard
+   *  shortcuts while a cell is being edited. `reason` is `"start"` (an editor opened), `"commit"` (it closed
+   *  saving — fired even when the value was unchanged) or `"cancel"` (it closed discarding). The grid root
+   *  also carries a `data-editing` attribute while any editor is open. */
+  onEditingChange?: (cell: { key: string | number; field: string } | null, reason: "start" | "commit" | "cancel") => void;
   /** #317: fired when the rectangular cell selection changes ("cell" mode) — every cell inside the
    *  anchor→focus rectangle, in row-major order. Empty array when the selection clears. */
   onCellSelectionChange?: (cells: Array<{ key: string | number; field: string }>) => void;
   /** #318: enable spreadsheet clipboard on cells ("cell" mode): Ctrl/Cmd+C copies the active cell/range as
    *  TSV, Ctrl/Cmd+X cuts (copy then clear), Ctrl/Cmd+V pastes onto the target rectangle from the active
-   *  cell. Paste is format-restricted by column `copyType` (incompatible cells are skipped) and commits
-   *  through `onRowUpdate`/`onRowsChange` in one batched change; outcomes are announced via `aria-live`.
+   *  cell. Paste is format-restricted by column `copyType` (incompatible cells are skipped). It commits
+   *  through `onRowsChange` in one change and, per cell, through `onRowUpdate` (once per changed field) —
+   *  unless `onCellsCommit` is supplied, which reports the whole paste/cut as a single grouped call instead.
+   *  Outcomes are announced via `aria-live`.
    *  Copy/cut/paste also show a brief **visible** in-grid confirmation toast + a flash on the affected cells
    *  (#320), so sighted users get feedback too. @default false */
   enableClipboard?: boolean;
@@ -2009,6 +2129,11 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
   /** #320: fired after a clipboard paste with the outcome — `written` cells committed, `skipped` cells
    *  rejected (read-only or incompatible `copyType`). */
   onCellsPaste?: (result: { written: number; skipped: number }) => void;
+  /** #394: when supplied, a paste or cut reports the whole change as ONE call — the grouped patches per row
+   *  (`key`, the updated `row`, and its `patch`) plus `meta.source` — instead of firing `onRowUpdate` once per
+   *  cell (which bursts N writes through a rate-limited API). `onRowsChange` is unaffected. The clipboard
+   *  counterpart of `onBatchUpdate`. */
+  onCellsCommit?: (changes: Array<{ key: string | number; row: T; patch: Partial<T> }>, meta: { source: "paste" | "cut" }) => void;
   /** Show the **Aggregation** toolbar button and start with the totals row on. From that panel the user
    *  toggles totals and picks columns + functions (a column's `aggregation` prop seeds the initial choice);
    *  changing the prop re-applies it. When false (the default) the Aggregation button is hidden. @default false */
@@ -2023,10 +2148,19 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
   showGroupBar?: boolean;
   /** #387: custom content for a group header row (the chevron + collapse/expand toggle are kept). Return the
    *  node to render in place of the default `"<field>: <value>  <count>"` — e.g. a section title + a summary.
-   *  `rows` is the group's rows; `count` is their number. Return `null` to render an empty label (matching
-   *  `renderCell`/`renderHeader`). The content sits **inside** the group's toggle button, so keep it
-   *  non-interactive — a nested button/link would be invalid HTML and its clicks would also toggle the group. */
-  renderGroupLabel?: (group: { field: string; value: unknown; count: number; rows: T[] }) => React.ReactNode;
+   *  `rows` is the group's rows; `count` is their number; `collapsed` is its current state and `toggle()`
+   *  flips it. Return `null` to render an empty label (matching `renderCell`/`renderHeader`). The content sits
+   *  **inside** the group's toggle button, so keep it non-interactive — a nested button/link would be invalid
+   *  HTML and its clicks would also toggle the group. */
+  renderGroupLabel?: (group: { field: string; value: unknown; count: number; rows: T[]; collapsed: boolean; toggle: () => void }) => React.ReactNode;
+  /** #393: which groups are collapsed, as internal group-path keys (`"/status:open"`, nested
+   *  `"/status:open/owner:ann"`). Controlled — pair with `onCollapsedGroupsChange`; omit for uncontrolled. */
+  collapsedGroups?: string[];
+  /** #393: initial collapsed groups for the uncontrolled case (ignored when `collapsedGroups` is set). @default [] */
+  defaultCollapsedGroups?: string[];
+  /** #393: fired when the user collapses/expands a group, with the next array of collapsed group keys. Also
+   *  the way to persist collapse state outside `stateKey`. */
+  onCollapsedGroupsChange?: (keys: string[]) => void;
   /** Enable row pinning — adds "Pin to top/bottom" to each row's actions menu; pinned rows stay sticky above/below the scroll body. @default false */
   rowPinning?: boolean;
   /** Enable reorder of rows: the whole row is mouse-draggable, and a focusable drag handle supports
@@ -2180,10 +2314,17 @@ interface DatatableState {
   columnCombine?: Record<string, { fields: string[]; layout?: "inline" | "stack"; separator?: string; labels?: boolean }>;
   /** #341: user-resized width (px) of the batch-editor's column-name field. Absent until the user drags it. */
   batchNameWidth?: number;
+  /** #393: active grouping fields (from the column ⋮ "Group by" items). Absent when nothing is grouped. */
+  grouping?: string[];
+  /** #393: collapsed group keys (internal group-path strings). Absent when every group is expanded. */
+  collapsedGroups?: string[];
 }
 
 interface DatatableColumn<T = any> {
-  /** Row object key (also the default sort/filter/search/group/export key). */
+  /** Row object key (also the default sort/filter/search/group/export key). **Must be unique within
+   *  `columns`** — it is the column's identity for width, visibility, order, pinning and persisted `stateKey`
+   *  state (a duplicate `field` makes two columns share that state and logs a dev warning). To show one row
+   *  key in two columns, give the second its own `field` and read the value with `valueGetter`. */
   field: string;
   /** Derive the column's value from the whole row (nested/computed) — drives sort, filter,
    *  quick-search, grouping, aggregation, the default cell render, and export. Falls back to
@@ -2229,8 +2370,12 @@ interface DatatableColumn<T = any> {
   minWidth?: number;
   /** Upper bound (px) for the resolved width; `minWidth` wins if they conflict. */
   maxWidth?: number;
-  /** Cell alignment; currently affects the actions column's button justification. @default "right" for number/actions columns, else "left" */
-  align?: "left" | "right";
+  /** Horizontal alignment of the column's body cells and footer (and the actions column's button
+   *  justification), emitted as `data-align` like the `Table` component. Use `"center"` for status icons,
+   *  toggles or short counts. @default "right" for number/actions columns, else "left" */
+  align?: "left" | "center" | "right";
+  /** Header-cell alignment, when it should differ from the body `align`. @default the column's `align` */
+  headerAlign?: "left" | "center" | "right";
   /** Allow sorting this column. @default true */
   sortable?: boolean;
   /** Allow filtering this column. @default true */
@@ -2255,8 +2400,11 @@ interface DatatableColumn<T = any> {
   aggregationFormatter?: (value: any) => React.ReactNode;
   /** Map a row to its exported CSV value (defaults to the raw field value). */
   exportValue?: (value: any, row: T) => string | number;
-  /** Make this column's cells editable (double-click to edit). Overrides the grid `editMode`. */
-  editable?: boolean;
+  /** Make this column's cells editable (double-click to edit). Overrides the grid `editMode`. #424: pass a
+   *  predicate `(row, { field }) => boolean` to make it editable only on the rows that satisfy it (like
+   *  `cellStyle`/`cellClassName`). A `false` result behaves exactly like `editable: false` for that cell — no
+   *  editor on double-click/Enter/F2, and the cell is skipped by paste, cut and the batch editor. */
+  editable?: boolean | ((row: T, ctx: { field: string }) => boolean);
   /** Editor type. "select" (or any column with `valueOptions`) renders a dropdown; else a text/number input by column type. */
   editType?: "text" | "number" | "select";
   /** Full escape hatch for the inline cell editor — render your own control (a searchable / creatable /
@@ -2265,9 +2413,18 @@ interface DatatableColumn<T = any> {
    *  built-in select/text editor. Call `commit(nextValue)` to save (fires `onRowUpdate`/`onRowsChange`)
    *  or `cancel()` to discard. Twico overlay dropdowns (portaled as `.twc-pop`) are exempt from the
    *  cell's outside-click auto-cancel, so a Combobox popover works inside the cell. **Escape cancels**
-   *  the edit automatically (the wrapper calls `cancel()`), so you needn't wire a keydown — stop
-   *  propagation on Escape only if your control needs it (e.g. to close its own open dropdown). */
-  renderEditCell?: (args: { value: any; row: T; field: string; commit: (nextValue: any) => void; cancel: () => void }) => React.ReactNode;
+   *  the edit automatically — but #412: the wrapper IGNORES an Escape a nested control already handled
+   *  (`defaultPrevented`), so a twico Select/Combobox/MultiSelect closing its list inside the editor doesn't
+   *  cancel the whole edit (a second Escape does). A custom control can still `stopPropagation` to keep Escape.
+   *  #390: call `setDraft(next)` as the user types to STAGE a value — click-away then commits the staged
+   *  draft spreadsheet-style (like the built-in editor) instead of discarding it; an editor that never stages
+   *  keeps the cancel-on-click-away behaviour. #413: pass `{ patch: true }` to stage a multi-key PATCH for
+   *  click-away (same no-op rule as `commitPatch`); #423: pass `{ silent: true }` to stage WITHOUT re-rendering
+   *  the grid (for an editor that renders from its own draft state — avoids per-keystroke lag on large pages).
+   *  Call `commitPatch(patch)` to write several stored keys at once
+   *  (a quantity + its unit shown as one column) — it writes `{ ...row, ...patch }` and no-ops only when every
+   *  patched key is unchanged. */
+  renderEditCell?: (args: { value: any; row: T; field: string; commit: (nextValue: any) => void; cancel: () => void; setDraft: (next: any, opts?: { patch?: boolean; silent?: boolean }) => void; commitPatch: (patch: Partial<T>) => void }) => React.ReactNode;
   /** Custom control for this column's clause in the **batch** editor (#247) — the counterpart of
    *  `renderEditCell` for the "Edit N selected rows" popover. Use it when the value is backed by a large,
    *  async, creatable vocabulary that `valueOptions` (a static array) can't express; without it such a
@@ -2328,13 +2485,29 @@ interface DatatableRowAction<T = any> {
   icon?: React.ReactNode;
   /** Accessible label / tooltip / menu text. */
   label: string;
-  /** Click handler, receives the row. */
-  onClick?: (row: T) => void;
+  /** Click handler, receives the row and the click event. Still runs for a plain left-click when `href` is set
+   *  (so client-side routing keeps working); #419: call `e.preventDefault()` there to suppress the native
+   *  navigation before you route (otherwise the browser also follows `href` → a full page load). Modifier and
+   *  middle clicks fall through to the browser. */
+  onClick?: (row: T, e: React.MouseEvent) => void;
+  /** #399: render this action as a link (`<a>`) — middle-click, open-in-new-tab and copy-address all work.
+   *  The URL is scheme-sanitised (`javascript:`/`data:`/`vbscript:` are dropped). A `disabled` action never
+   *  emits an href. */
+  href?: string;
+  /** Anchor `target` for the `href` link (e.g. `"_blank"`). */
+  target?: string;
+  /** Anchor `rel` for the `href` link (pair `rel="noopener noreferrer"` with `target="_blank"`). */
+  rel?: string;
   /** Place in the ⋮ overflow menu instead of inline. @default false */
   showInMenu?: boolean;
   /** Render in danger color. */
   danger?: boolean;
   disabled?: boolean;
+  /** #399: shown when `disabled` — as the tooltip for an inline action and as an inline hint in the ⋮ menu.
+   *  #419: when set, the inline action renders `aria-disabled` (not native `disabled`) so it stays focusable and
+   *  the reason is reachable by hover AND keyboard; click and Enter/Space stay blocked. The menu hint is always
+   *  reachable. */
+  disabledReason?: React.ReactNode;
 }
 
 /** Extra context handed to a batch action's `onClick`. */
@@ -3089,9 +3262,21 @@ interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "on
   /** 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;
+  /** #406: headless mode — render only this element (a camera badge, an "Attach" IconButton, …) instead of the
+   *  dropzone + file list. A click opens the picker and the same accept/maxSize/maxFiles/onReject validation
+   *  still runs; track the files yourself via `value`/`onChange`. */
+  trigger?: React.ReactNode;
+  /** #406: also accept dropped files onto the `trigger` (headless mode only). @default false */
+  dropOnTrigger?: boolean;
+  children?: React.ReactNode;
 }
 
-declare function FileUpload(props: FileUploadProps): React.JSX.Element;
+/** #406: imperative handle exposed via a ref — `open()` opens the native file picker. */
+interface FileUploadHandle {
+  open(): void;
+}
+
+declare const FileUpload: React.ForwardRefExoticComponent<FileUploadProps & React.RefAttributes<FileUploadHandle>>;
 
 /**
  * Square (or circular) button for a single icon. Always provide an aria-label.
@@ -3110,6 +3295,16 @@ interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>
   size?: "xs" | "sm" | "md" | "lg";
   /** Fully rounded (circular). @default false */
   round?: boolean;
+  /** #398: when `disabled`, stay focusable (render `aria-disabled` instead of native `disabled`) so a wrapping
+   *  `Tooltip` explaining *why* it's disabled is reachable by keyboard. Click and Enter/Space stay blocked and
+   *  the disabled styling still applies. @default false */
+  focusableWhenDisabled?: boolean;
+  /** #405: toggle "on" state — sets `aria-pressed` and shows a soft fill + border in the current `tone`
+   *  (works with any `variant`), e.g. a pin/unpin or bold/italic icon toggle. @default undefined */
+  pressed?: boolean;
+  /** #411: tone of the pressed ("on") fill — the full status `Tone` scale, so a toggle can carry its own
+   *  selected-state meaning while `tone` stays `ActionTone` for the unpressed look. Defaults to `tone`. @default undefined */
+  pressedTone?: Tone;
   /** #342: render as a different element — use `"a"` for an icon **link** (GitHub icon, external nav, …) so
    *  navigation is a real link, not a button. @default "button" */
   as?: "button" | "a";
@@ -3125,6 +3320,63 @@ interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>
 
 declare function IconButton(props: IconButtonProps): React.JSX.Element;
 
+/** One toggle button in a {@link ToggleGroup}. */
+interface ToggleGroupItem {
+  /** Unique value emitted through `onValueChange` and matched against `value`/`defaultValue`. */
+  value: string;
+  /** Visible label (omit for an icon-only toggle, then set `aria-label`). */
+  label?: React.ReactNode;
+  /** Leading icon node. */
+  icon?: React.ReactNode;
+  /** Disable just this toggle. */
+  disabled?: boolean;
+  /** #411: pressed ("on") tone for THIS item, overriding the group `tone` — so options can carry their own
+   *  meaning colour (e.g. Allow=success, Deny=danger, Clear=neutral). */
+  tone?: Tone;
+  /** Accessible label — required when the toggle is icon-only. */
+  "aria-label"?: string;
+}
+
+/**
+ * A set of **toggle buttons** (`aria-pressed`) — a tool/mode switch (Allow / Deny / Clear), a formatting bar
+ * (bold / italic), or a segmented control. Per WAI-ARIA it is a *group of toggle buttons*, not a radiogroup:
+ * with `roving`, arrow keys move focus only; Space/Enter/click toggle. Composes `Button` for its look.
+ *
+ * @startingPoint section="Buttons" subtitle="Group of toggle buttons" viewport="700x160"
+ */
+interface ToggleGroupProps {
+  /** The toggles to render. */
+  items: ToggleGroupItem[];
+  /** `"single"` — one value (`string | null`); clicking the active one deselects. `"multiple"` — a `string[]`.
+   *  @default "single" */
+  type?: "single" | "multiple";
+  /** Controlled value: a `string | null` for `"single"`, a `string[]` for `"multiple"`. Pair with `onValueChange`. */
+  value?: string | string[] | null;
+  /** Initial value for the uncontrolled case. */
+  defaultValue?: string | string[] | null;
+  /** Fired with the next value (a `string | null`, or a fresh `string[]`) when a toggle changes. */
+  onValueChange?: (value: string | string[] | null) => void;
+  /** Button size. @default "md" */
+  size?: "xs" | "sm" | "md" | "lg";
+  /** #411: default pressed ("on") fill tone for the group — the full status `Tone` scale (a per-item `tone`
+   *  overrides it). The unpressed look stays action-neutral. @default "primary" */
+  tone?: Tone;
+  /** The button variant used for the OFF (unpressed) look. @default "outline" */
+  variant?: "solid" | "soft" | "outline" | "ghost";
+  /** Opt into roving arrow-key focus (WAI-ARIA) — the group is one Tab stop and arrows move focus between
+   *  toggles. Off by default (each toggle is in the native tab order). @default false */
+  roving?: boolean;
+  /** Layout + roving axis. @default "horizontal" */
+  orientation?: "horizontal" | "vertical";
+  /** Disable the whole group. @default false */
+  disabled?: boolean;
+  /** Accessible label for the `role="group"` container. */
+  "aria-label"?: string;
+  className?: string;
+}
+
+declare function ToggleGroup(props: ToggleGroupProps): React.JSX.Element;
+
 /**
  * Text input with optional label, hint, error state, and inline icons.
  *
@@ -3571,6 +3823,10 @@ interface SidebarProps extends React.HTMLAttributes<HTMLElement> {
   items: SidebarItem[];
   /** Content pinned above the collapse toggle (e.g. a user row). */
   footer?: React.ReactNode;
+  /** #402: remove the built-in padding around `footer` content so an edge-to-edge account row (whose hover
+   *  background should reach the rail edges + the top divider) doesn't need consumer negative margins. #417:
+   *  when no collapse button follows (`collapsible={false}`), the row also reaches the rail's bottom edge. @default true */
+  footerInset?: boolean;
   /** Controlled collapsed state. */
   collapsed?: boolean;
   /** Uncontrolled initial collapsed state. @default false */
@@ -4539,4 +4795,30 @@ 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, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, CardGrid, type CardGridFilter, type CardGridProps, type CardGridQuery, type CardGridSort, type CardGridSortOption, 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 ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableBatchActionContext, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableState, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, Dialog, type DialogProps, type DiffOp, DiffTable, type DiffTableColumn, type DiffTableProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, type FilterClause, type FilterField, type FilterFieldType, type FilterValues, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, 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, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, TimePicker, type TimePickerProps, 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, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, type WithSx, 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 };
+/** #406: options for {@link useFilePicker}. */
+interface UseFilePickerOptions {
+  /** Accepted file types (input accept string, e.g. "image/*,.pdf"). */
+  accept?: string;
+  /** Allow selecting multiple files. @default false */
+  multiple?: boolean;
+  /** Max size per file in bytes; larger files are rejected. */
+  maxSize?: number;
+  /** Max number of files accepted within a SINGLE selection (the hook is stateless — it can't count across
+   *  separate picks; track cumulative selection yourself). */
+  maxFiles?: number;
+  /** Called with the files that passed validation. */
+  onFiles?: (files: File[]) => void;
+  /** Called with rejected files: `{ file, reason }` where reason is "type" | "size" | "count". */
+  onReject?: (rejections: Array<{ file: File; reason: "type" | "size" | "count" }>) => void;
+}
+
+/**
+ * #406: open a native file picker from your own trigger while reusing FileUpload's validation. Render
+ * `<input {...getInputProps()} />` (hidden) once, then call `open()` from any control.
+ */
+declare function useFilePicker(options?: UseFilePickerOptions): {
+  open: () => void;
+  getInputProps: () => React.InputHTMLAttributes<HTMLInputElement> & { ref: React.RefObject<HTMLInputElement | null> };
+};
+
+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 BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, CardGrid, type CardGridFilter, type CardGridProps, type CardGridQuery, type CardGridSort, type CardGridSortOption, 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 ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableBatchActionContext, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableState, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, Dialog, type DialogProps, type DiffOp, DiffTable, type DiffTableColumn, type DiffTableProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, type FilterClause, type FilterField, type FilterFieldType, type FilterValues, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, ImageViewer, type ImageViewerControlsApi, type ImageViewerProps, type ImageViewerState, 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, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, ToggleGroup, type ToggleGroupItem, type ToggleGroupProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFilePickerOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseMediaQueryOptions, VisuallyHidden, type VisuallyHiddenProps, type WithSx, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFilePicker, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };