cortena-ui 1.2.0 → 1.3.0

package/README.md

@@ -26,6 +26,40 @@ Consuming it: `../../CONSUMING.md`, section "cortena-ui".
   check in light, dark and system-dark; add an entry with every variant and
   size when adding a component.
 
+## Charts in tests
+
+Both chart engines size themselves from the parent box, and under jsdom every
+element measures 0×0. A page test that renders a screen containing a `<Chart>`
+therefore gets an empty `<div>`: no `<svg>`, no bars, nothing to assert. Two
+ways out, in order of preference.
+
+**1. `testMode`, when the test is about the page.** It gives the drawing area a
+600×300 floor, so the chart draws and the page renders as a whole:
+
+```tsx
+<Chart type="bar" data={rows} testMode={import.meta.env.MODE === "test"} />
+```
+
+It is a floor, not a fixed size — a parent that does give the chart 900px still
+gets 900px — so the same prop is harmless in a browser or screenshot test. A
+screen that composes charts internally can take the flag as a prop and pass it
+down, or read it once from the app's own test flag.
+
+**2. Mock the module, when the test is about everything except the chart.**
+Cheaper and faster, and the right choice when the assertion is "the dashboard
+renders" rather than "the chart drew". Mock `cortena-ui`'s `Chart` to a stub
+that echoes what it was handed:
+
+```tsx
+vi.mock("cortena-ui", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("cortena-ui")>()),
+  Chart: (props: { type: string }) => <div data-testid="chart" data-type={props.type} />,
+}));
+```
+
+Neither substitutes for the real check: whether a chart *looks* right is
+settled in the guide and in this package's browser tests, not in a page test.
+
 ## A2UI: the vocabulary agents draw with
 
 `src/a2ui/` is Layer 1 of `cortena-docs/cortenaUI&Design/05-agent-ui.md`: an

package/dist/index.d.ts

@@ -294,7 +294,10 @@ export declare function readAction(value: unknown): {
  *   (the Nivo line shape the webchat emits). `ChartRow[]` is also accepted.
  * - **pie**, **donut**, **funnel**: `ChartSlice[]` — `[{ id, label?, value }]`.
  * - **scatter** (alias `scatterplot`): `ChartSeries[]` — one series per group.
- * - **heatmap**: `ChartSeries[]` — Nivo heatmap shape, `[{ id: row, data: [{ x: column, y: value }] }]`.
+ * - **heatmap**: `ChartSeries[]` — Nivo heatmap shape, `[{ id: row, data: [{ x: column, y: value }] }]` —
+ *   or `ChartMatrix`, the categorical form a correlation / confusion matrix
+ *   already has: `{ rows, columns, values }` with `values[r][c]` at
+ *   `rows[r] × columns[c]`.
  * - **calendar**: `ChartDay[]` — `[{ day: "2026-01-31", value }]`; `from`/`to`
  *   default to the data's range.
  * - **treemap**, **sunburst**: `ChartTree` — Nivo tree, `{ id, children?: [...], value? }`
@@ -322,6 +325,17 @@ interface ChartSlice {
   label?: string;
   value: number;
 }
+/**
+ * A categorical matrix: `values[r][c]` is the cell at `rows[r]` × `columns[c]`.
+ * The shape a correlation matrix, a confusion matrix or a day × hour grid is
+ * already in, so it needs no pivot at the call site. Short rows are padded
+ * with `null` (drawn as the empty colour) rather than treated as zero.
+ */
+interface ChartMatrix {
+  rows: string[];
+  columns: string[];
+  values: Array<Array<number | null | undefined>>;
+}
 /** One day of a calendar heatmap. */
 interface ChartDay {
   day: string;
@@ -336,7 +350,7 @@ interface ChartTree {
   [key: string]: unknown;
 }
 /** The data type accepted for each chart type. */
-type ChartDataFor<T extends ChartType> = T extends "bar" | "radar" ? ChartRow[] | ChartSeries[] : T extends "line" | "area" ? ChartSeries[] | ChartRow[] : T extends "pie" | "donut" | "funnel" ? ChartSlice[] : T extends "scatter" | "scatterplot" | "heatmap" ? ChartSeries[] : T extends "calendar" ? ChartDay[] : T extends "treemap" | "sunburst" ? ChartTree : never;
+type ChartDataFor<T extends ChartType> = T extends "bar" | "radar" ? ChartRow[] | ChartSeries[] : T extends "line" | "area" ? ChartSeries[] | ChartRow[] : T extends "pie" | "donut" | "funnel" ? ChartSlice[] : T extends "heatmap" ? ChartSeries[] | ChartMatrix : T extends "scatter" | "scatterplot" ? ChartSeries[] : T extends "calendar" ? ChartDay[] : T extends "treemap" | "sunburst" ? ChartTree : never;
 /**
  * Per-series presentation, keyed by series id (the `keys` of a row chart, the
  * `id` of a series or slice). Colours default to `var(--ds-viz-1..n)` in key
@@ -382,6 +396,19 @@ interface ChartContainerProps extends Omit<React$1.ComponentProps<"div">, "child
    * `responsive={false}`.
    */
   responsive?: boolean;
+  /**
+   * Give the drawing area a floor of 600×300 so it draws where the layout
+   * gives it none.
+   *
+   * Both engines size themselves from the parent box. Under jsdom nothing has
+   * layout — every element measures 0×0 — so a page test that renders a screen
+   * containing a Chart gets an empty `<div>` and can assert nothing about it.
+   * `testMode` sets `min-width` / `min-height` on the container and hands the
+   * same floor to Recharts' ResponsiveContainer, so the chart draws at
+   * 600×300. It is a floor, not a fixed size: a parent that *does* give the
+   * chart 900px still gets 900px, so a screenshot test is unaffected.
+   */
+  testMode?: boolean;
   children: React$1.ReactNode;
 }
 /**
@@ -392,7 +419,7 @@ interface ChartContainerProps extends Omit<React$1.ComponentProps<"div">, "child
  * cursor classes from tokens with a caption-sm floor for text, so a custom
  * chart composed inside it needs no local colours or fonts.
  */
-declare function ChartContainer({ config, height, responsive, className, style, children, ...props }: ChartContainerProps): React$1.JSX.Element;
+declare function ChartContainer({ config, height, responsive, testMode, className, style, children, ...props }: ChartContainerProps): React$1.JSX.Element;
 /** "No data" placeholder; rendered by Chart when the data is empty. */
 declare function ChartEmpty({ children, ...props }: React$1.ComponentProps<"div">): React$1.JSX.Element;
 /** Error placeholder; rendered by Chart for an `error` prop or a failed Nivo chunk. */
@@ -474,6 +501,14 @@ interface ChartProps<T extends ChartType = ChartType> extends Omit<ChartContaine
  * Colours, fonts, axes, grid, tooltip, legend and the empty, loading and
  * error states all come from cortena-design tokens; a consumer passes data
  * and, optionally, a `config` of labels.
+ *
+ * `heatmap` takes either the Nivo series shape or a categorical
+ * {@link ChartMatrix} — `{ rows, columns, values }` — for the correlation and
+ * confusion matrices that are already in that form.
+ *
+ * `testMode` gives the drawing area a 600×300 floor so a chart still draws
+ * where the layout gives it no size; see {@link ChartContainerProps.testMode}
+ * and README.md, "Charts in tests".
  */
 declare function Chart<T extends ChartType>({ type, data, config, renderer, indexBy, keys, stacked, scale, legend, grid, tooltip, valueFormatter, from, to, loading, error, emptyMessage, className, height, ...props }: ChartProps<T>): React$1.JSX.Element;
 //#endregion
@@ -959,12 +994,22 @@ interface DataTableViewProps<Row extends RowData> {
   /** Error to show above the table, in addition to the server source's. */
   error?: string | Error | null;
   onRowClick?: (row: Row, event: React$1.MouseEvent<HTMLTableRowElement>) => void;
+  /**
+   * The row a detail pane is currently showing, matched against the row id
+   * (`getRowId`, the row index when that is not set). It gets `data-active`
+   * and the `--ds-primary-soft` tint, independent of checkbox selection — a
+   * master/detail list highlights one row without selecting it, and a table
+   * with both can show a selected set and one open row at once.
+   */
+  activeRowId?: string | null;
+  /** Extra classes per row, e.g. to dim rows the app considers stale. */
+  rowClassName?: (row: Row) => string | undefined;
 }
 type DataTableProps<Row extends RowData> = DataTableViewProps<Row> & ({
   instance: DataTableInstance<Row>;
 } | UseDataTableOptions<Row>);
 declare function DataTable<Row extends RowData>(props: DataTableProps<Row>): React$1.JSX.Element;
-declare function DataTableView<Row extends RowData>({ instance, className, maxHeight, virtualize, rowHeight, stickyHeader, density, renderSubComponent, toolbar, bulkActions, toolbarActions, searchPlaceholder, emptyState, emptyMessage, pageSizeOptions, enableExport, exportFileName, loading, error, onRowClick }: DataTableViewProps<Row> & {
+declare function DataTableView<Row extends RowData>({ instance, className, maxHeight, virtualize, rowHeight, stickyHeader, density, renderSubComponent, toolbar, bulkActions, toolbarActions, searchPlaceholder, emptyState, emptyMessage, pageSizeOptions, enableExport, exportFileName, loading, error, onRowClick, activeRowId, rowClassName }: DataTableViewProps<Row> & {
   instance: DataTableInstance<Row>;
 }): React$1.JSX.Element;
 //#endregion
@@ -1281,13 +1326,8 @@ declare function AccordionTrigger({ className, children, ...props }: Accordion$1
 declare function AccordionContent({ className, children, ...props }: Accordion$1.Panel.Props): import("react").JSX.Element;
 //#endregion
 //#region src/components/alert.d.ts
-/**
- * Alert — an inline callout. Tinted variants use the `-soft` fill for the
- * background and the tone colour for the border and icon; the body text stays
- * on the foreground token so it reads in both themes.
- */
 declare const alertVariants: (props?: ({
-  variant?: "default" | "success" | "warn" | "danger" | "info" | null | undefined;
+  variant?: "default" | "success" | "warn" | "destructive" | "danger" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface AlertProps extends React$1.ComponentProps<"div">, VariantProps<typeof alertVariants> {}
 declare function Alert({ className, variant, ...props }: AlertProps): React$1.JSX.Element;
@@ -1310,17 +1350,98 @@ declare function AvatarImage({ className, ...props }: Avatar$1.Image.Props): imp
 declare function AvatarFallback({ className, ...props }: Avatar$1.Fallback.Props): import("react").JSX.Element;
 //#endregion
 //#region src/components/badge.d.ts
-/**
- * Badge — the mono, uppercase status label. Each tone pairs a `-soft` fill
- * with its foreground token; `warn`, `danger` and `secondary` are aliases kept
- * for cortenaweb call sites.
- */
 declare const badgeVariants: (props?: ({
-  variant?: "default" | "success" | "warning" | "warn" | "danger" | "destructive" | "info" | "neutral" | "secondary" | "outline" | null | undefined;
+  variant?: "default" | "success" | "warn" | "destructive" | "danger" | "info" | "warning" | "neutral" | "secondary" | "outline" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface BadgeProps extends React$1.ComponentProps<"span">, VariantProps<typeof badgeVariants> {}
 declare function Badge({ className, variant, ...props }: BadgeProps): React$1.JSX.Element;
 //#endregion
+//#region src/lib/render.d.ts
+/**
+ * The `render` prop for the components that are plain markup rather than Base
+ * UI primitives (Card, SectionCard, ButtonLink, BreadcrumbLink).
+ *
+ * Base UI parts take their own `render` and need nothing from here. The rest
+ * are a `<div>` or an `<a>` this package writes itself, and a consumer
+ * sometimes needs a different element under the same styling: a Card that is
+ * the page's `<aside>` landmark, or a link that is the router's `<Link>`.
+ * Passing an element rather than a component keeps the call site readable and
+ * lets the caller set props on it (`render={<Link to="/x" />}`).
+ *
+ * `props` wins over the passed element's own props, so the `className` and
+ * handlers a component computed are not silently dropped, while the element's
+ * own props (`href`, `to`, `aria-labelledby`) come through untouched. What a
+ * component lets a *caller* override is decided by the order it builds `props`
+ * in, not here. Children are `children`, falling back to the element's.
+ */
+type RenderProp = React$1.ReactElement<Record<string, unknown>>;
+//#endregion
+//#region src/components/breadcrumb.d.ts
+/**
+ * Breadcrumb — the trail above a page title.
+ *
+ * A `<nav aria-label="Breadcrumb">` around an ordered list, which is what
+ * assistive technology expects: the list order is the hierarchy, so a screen
+ * reader announces "list, 4 items" and reads the path in order. Separators are
+ * decorative list items, not text inside the links, so a link's accessible
+ * name is the crumb and nothing else.
+ *
+ * The last crumb is `BreadcrumbPage`, not a link: it is the page you are on,
+ * so it carries `aria-current="page"` and is not focusable. Everything before
+ * it is a `BreadcrumbLink`.
+ *
+ * ```tsx
+ * <Breadcrumb>
+ *   <BreadcrumbList>
+ *     <BreadcrumbItem>
+ *       <BreadcrumbLink href="/">Home</BreadcrumbLink>
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem>
+ *       <BreadcrumbEllipsis />
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem>
+ *       <BreadcrumbPage>Invoice 4021</BreadcrumbPage>
+ *     </BreadcrumbItem>
+ *   </BreadcrumbList>
+ * </Breadcrumb>
+ * ```
+ *
+ * **Router links.** `BreadcrumbLink` renders an `<a>` by default. Pass
+ * `render` with the router's link component and the class name, `href` and
+ * handlers are merged onto it, the same contract as `ButtonLink`:
+ * `render={<NextLink href="/projects" />}` or
+ * `render={<Link to="/projects" />}`. This is deliberately not Base UI's
+ * `render` — a breadcrumb is markup, not a Base UI primitive — but it takes
+ * the same shape so there is one thing to remember.
+ */
+declare function Breadcrumb({ className, ...props }: React$1.ComponentProps<"nav">): React$1.JSX.Element;
+declare function BreadcrumbList({ className, ...props }: React$1.ComponentProps<"ol">): React$1.JSX.Element;
+declare function BreadcrumbItem({ className, ...props }: React$1.ComponentProps<"li">): React$1.JSX.Element;
+interface BreadcrumbLinkProps extends React$1.ComponentProps<"a"> {
+  /** Replace the rendered `<a>` with a router link; props are merged onto it. */
+  render?: RenderProp;
+}
+declare function BreadcrumbLink({ className, render, children, ...props }: BreadcrumbLinkProps): React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>>;
+/**
+ * The current page: the last crumb, which is not a link.
+ *
+ * A plain `<span aria-current="page">`, deliberately not `role="link"` with
+ * `aria-disabled` — a disabled link that cannot be focused is a fiction, and
+ * it makes `getByRole("link")` return a crumb that navigates nowhere. With a
+ * span, the roles in the trail are exactly the crumbs you can travel to.
+ */
+declare function BreadcrumbPage({ className, ...props }: React$1.ComponentProps<"span">): React$1.JSX.Element;
+/** Decorative divider between two crumbs; a chevron unless children replace it. */
+declare function BreadcrumbSeparator({ className, children, ...props }: React$1.ComponentProps<"li">): React$1.JSX.Element;
+/**
+ * Stands in for the crumbs a long trail collapses; put it inside a
+ * BreadcrumbItem. The glyph is hidden and the label is not: an ellipsis that
+ * announces nothing leaves a screen-reader user with a gap in the path.
+ */
+declare function BreadcrumbEllipsis({ className, children, ...props }: React$1.ComponentProps<"span">): React$1.JSX.Element;
+//#endregion
 //#region src/components/button.d.ts
 /**
  * Button.
@@ -1333,7 +1454,7 @@ declare function Badge({ className, variant, ...props }: BadgeProps): React$1.JS
  * rendered element, which is Base UI's equivalent.
  */
 declare const buttonVariants: (props?: ({
-  variant?: "destructive" | "secondary" | "outline" | "primary" | "ghost" | "soft" | "link" | null | undefined;
+  variant?: "link" | "destructive" | "secondary" | "outline" | "primary" | "ghost" | "soft" | null | undefined;
   size?: "sm" | "md" | "lg" | "icon" | "icon-sm" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface ButtonProps extends React$1.ComponentProps<typeof Button$1>, VariantProps<typeof buttonVariants> {}
@@ -1356,10 +1477,10 @@ declare function Button({ className, variant, size, ...props }: ButtonProps): Re
 interface ButtonLinkProps extends Omit<React$1.ComponentProps<"a">, "children">, Pick<ButtonProps, "variant" | "size"> {
   children?: React$1.ReactNode;
   /** Replace the rendered `<a>` with a router link; props are merged onto it. */
-  render?: React$1.ReactElement<Record<string, unknown>>;
+  render?: RenderProp;
   disabled?: boolean;
 }
-declare function ButtonLink({ className, variant, size, render, disabled, children, ...props }: ButtonLinkProps): React$1.JSX.Element;
+declare function ButtonLink({ className, variant, size, render, disabled, children, ...props }: ButtonLinkProps): React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>>;
 //#endregion
 //#region src/components/calendar.d.ts
 /**
@@ -1390,8 +1511,21 @@ interface CardProps extends React$1.ComponentProps<"div"> {
   hover?: boolean;
   /** Draw the border in the ring colour, for a selected or highlighted card. */
   accent?: boolean;
+  /**
+   * Replace the rendered `<div>` with another element, so a card can *be* the
+   * landmark rather than sit inside a wrapper that is one:
+   * `render={<aside />}` for a sidebar panel, `render={<section />}` (with an
+   * `aria-labelledby` pointing at its title) for a labelled region,
+   * `render={<article />}` for a self-contained item in a feed. Props set on
+   * the passed element come through; the card's own styling wins.
+   */
+  render?: RenderProp;
 }
-declare function Card({ className, hover, accent, ...props }: CardProps): React$1.JSX.Element;
+/**
+ * Card — the bordered surface everything else sits on. `render` changes the
+ * element without changing the look, which is how a card becomes a landmark.
+ */
+declare function Card({ className, hover, accent, render, children, ...props }: CardProps): React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>>;
 declare function CardHeader({ className, ...props }: React$1.ComponentProps<"div">): React$1.JSX.Element;
 declare function CardTitle({ className, ...props }: React$1.ComponentProps<"div">): React$1.JSX.Element;
 declare function CardDescription({ className, ...props }: React$1.ComponentProps<"div">): React$1.JSX.Element;
@@ -1722,6 +1856,10 @@ interface DropzoneProps extends Omit<React$1.ComponentProps<"div">, "children" |
   /** Most files accepted per drop; `0` means unlimited. */
   maxFiles?: number;
   disabled?: boolean;
+  /** Do not open the file dialog on click; for a zone that wraps clickable content. @default false */
+  noClick?: boolean;
+  /** Do not open the file dialog on Enter or Space; pair with `noClick`. @default false */
+  noKeyboard?: boolean;
   /** Primary line of the default body. */
   label?: React$1.ReactNode;
   /** Muted second line of the default body; derived from `accept` and `maxSize` when omitted. */
@@ -1729,7 +1867,7 @@ interface DropzoneProps extends Omit<React$1.ComponentProps<"div">, "children" |
   /** Replace the default body. A function receives react-dropzone's state. */
   children?: React$1.ReactNode | ((state: DropzoneState) => React$1.ReactNode);
 }
-declare function Dropzone({ onFiles, onReject, accept, multiple, maxSize, maxFiles, disabled, label, hint, children, className, ref, ...props }: DropzoneProps): React$1.JSX.Element;
+declare function Dropzone({ onFiles, onReject, accept, multiple, maxSize, maxFiles, disabled, noClick, noKeyboard, label, hint, children, className, ref, ...props }: DropzoneProps): React$1.JSX.Element;
 interface FileListProps extends Omit<React$1.ComponentProps<"ul">, "children"> {
   files: readonly File[];
   /** Called with the file and its index when its remove button is pressed; the button is hidden when omitted. */
@@ -1796,7 +1934,7 @@ declare function ErrorBanner({ message, onDismiss, onRetry, className, ...props
  * list) it renders whenever the list has a message.
  */
 declare const fieldVariants: (props?: ({
-  orientation?: "vertical" | "horizontal" | null | undefined;
+  orientation?: "horizontal" | "vertical" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface FieldProps extends React$1.ComponentProps<typeof Field$1.Root>, VariantProps<typeof fieldVariants> {}
 declare function Field({ className, orientation, invalid, ...props }: FieldProps): React$1.JSX.Element;
@@ -2063,6 +2201,10 @@ interface SectionCardProps extends Omit<CardProps, "title"> {
  * SectionCard — a Card with a header row (title, description, actions), a
  * body and an optional footer. It composes the Card parts rather than
  * restyling them, so a SectionCard and a hand-built Card look identical.
+ *
+ * `render` is Card's and reaches the outer element, so a section card can be
+ * the landmark it is named after: `render={<section aria-labelledby={id} />}`
+ * with the same `id` on the title, or `render={<aside />}` for a side panel.
  */
 declare function SectionCard({ title, description, actions, footer, flush, bodyClassName, children, ...props }: SectionCardProps): React$1.JSX.Element;
 //#endregion
@@ -2104,8 +2246,33 @@ declare function Segmented<T extends string = string>({ className, value, onValu
  * - `onValueChange` receives `(value, eventDetails)`.
  * - `SelectContent` defaults to the dropdown layout; pass
  *   `alignItemWithTrigger` for Base UI's native-like overlay of the selected item.
+ *
+ * ## Typing the value
+ *
+ * `null` is the cleared / placeholder state, so `onValueChange` always hands
+ * back `Value | null`, never bare `Value`. Name the value type on the element
+ * to keep that union at `string | null` instead of letting inference widen it:
+ *
+ * ```tsx
+ * const [status, setStatus] = useState("");
+ *
+ * <Select<string>
+ *   // "" is not a value any item carries; `|| null` is the placeholder state,
+ *   // which is what makes SelectValue fall back to its `placeholder`.
+ *   value={status || null}
+ *   onValueChange={(next) => setStatus(next ?? "")} // next: string | null
+ * >
+ * ```
+ *
+ * Without the explicit `<string>` the type argument is inferred from `value`,
+ * so a `string | null` value widens `Value` and the handler's parameter turns
+ * into `string | null | null`. Multi-select narrows too:
+ * `<Select<string, true> multiple>` hands back `string[]`, never `null`.
+ *
+ * `SelectProps` is the same props type, for a wrapper that forwards them.
  */
-declare function Select<Value, Multiple extends boolean | undefined = false>(props: Select$1.Root.Props<Value, Multiple>): import("react").JSX.Element;
+type SelectProps<Value = string, Multiple extends boolean | undefined = false> = Select$1.Root.Props<Value, Multiple>;
+declare function Select<Value, Multiple extends boolean | undefined = false>(props: SelectProps<Value, Multiple>): import("react").JSX.Element;
 declare function SelectGroup({ className, ...props }: Select$1.Group.Props): import("react").JSX.Element;
 declare function SelectValue({ className, ...props }: Select$1.Value.Props): import("react").JSX.Element;
 interface SelectTriggerProps extends Select$1.Trigger.Props {
@@ -2137,15 +2304,15 @@ interface SeparatorProps extends React$1.ComponentProps<typeof Separator$1> {
 declare function Separator({ className, orientation, decorative, ...props }: SeparatorProps): React$1.JSX.Element;
 //#endregion
 //#region src/components/sheet.d.ts
-/**
- * Sheet: a Dialog whose Popup is anchored to one edge of the viewport.
- *
- * Same Base UI parts as Dialog (Root, Trigger, Portal, Backdrop, Popup, Title,
- * Description, Close); only the Popup's placement differs, chosen by `side`.
- * `SheetContent` composes Portal + Backdrop + Popup so consumers keep writing
- * `<SheetContent side="right">…</SheetContent>`.
- */
-declare function Sheet(props: Dialog$1.Root.Props): React$1.JSX.Element;
+interface SheetProps extends Dialog$1.Root.Props {
+  /**
+   * `true` (default) traps focus, locks page scroll and draws a backdrop.
+   * `false` draws no backdrop and traps nothing, for a panel read alongside
+   * the app. `"trap-focus"` keeps focus in but leaves the page scrollable.
+   */
+  modal?: boolean | "trap-focus";
+}
+declare function Sheet({ modal, ...props }: SheetProps): React$1.JSX.Element;
 declare function SheetTrigger(props: Dialog$1.Trigger.Props): React$1.JSX.Element;
 declare function SheetClose(props: Dialog$1.Close.Props): React$1.JSX.Element;
 declare function SheetPortal(props: Dialog$1.Portal.Props): React$1.JSX.Element;
@@ -2174,20 +2341,6 @@ declare function SheetDescription({ className, ...props }: Dialog$1.Description.
 declare function Skeleton({ className, ...props }: React$1.ComponentProps<"div">): React$1.JSX.Element;
 //#endregion
 //#region src/components/sortable-list.d.ts
-/**
- * SortableList.
- *
- * A reorderable list over dnd-kit: `DndContext` + `SortableContext` around one
- * `useSortable` item per entry. The list owns nothing — it calls `onReorder`
- * with the next array and the consumer stores it. Pointer and keyboard sensors
- * are wired (Space picks up, arrows move, Space drops, Escape cancels) and a
- * `DragOverlay` paints the lifted copy with `--ds-shadow-lg` while the item
- * left behind dims and takes the ring colour.
- *
- * By default the whole row is the drag activator. Pass `handle` to restrict
- * dragging to a `<SortableHandle>` (or any element given `handleProps`) so
- * buttons and inputs inside a row stay clickable.
- */
 /** Spread onto the element that should start a drag. */
 interface SortableHandleProps extends Partial<DraggableAttributes> {
   ref: (element: HTMLElement | null) => void;
@@ -2202,17 +2355,39 @@ interface SortableRenderState {
   /** True for the item being dragged (and for the overlay copy). */
   isDragging: boolean;
 }
+/** What moved where, passed to `onReorder` alongside the reordered array. */
+interface SortableReorderDetails {
+  /** Index the item came from, in the array as it was passed in. */
+  from: number;
+  /** Index it landed on. */
+  to: number;
+  /** Id of the item that moved (`getId` of the dragged item). */
+  activeId: UniqueIdentifier;
+  /** Id of the item it was dropped onto. */
+  overId: UniqueIdentifier;
+}
 interface SortableListProps<T> extends Omit<React$1.ComponentProps<"ul">, "children"> {
   items: readonly T[];
   /** Stable id per item; must be unique within the list. */
   getId: (item: T) => UniqueIdentifier;
-  /** Called with the reordered array after a successful drop. */
-  onReorder: (next: T[]) => void;
+  /**
+   * Called with the reordered array after a successful drop, and with the move
+   * itself — `{ from, to, activeId, overId }` — for a server that persists a
+   * position rather than the whole list.
+   */
+  onReorder: (next: T[], details: SortableReorderDetails) => void;
   renderItem: (item: T, state: SortableRenderState) => React$1.ReactNode;
   /** Layout axis; also selects the sorting strategy. */
   orientation?: "vertical" | "horizontal";
   /** Only a `<SortableHandle>` (or an element given `handleProps`) starts a drag. */
   handle?: boolean;
+  /**
+   * Let a finger scroll the page over the rows. Defaults to `handle`: `true`
+   * in handle mode, `false` in whole-row mode, which is what each already did.
+   * `true` on a whole-row list drops `touch-none` and uses a TouchSensor with
+   * delay activation, so a swipe scrolls and a held press drags.
+   */
+  touchScroll?: boolean;
   /** Disables every sensor and hides the handles. */
   disabled?: boolean;
   /** Class name for each item wrapper. */
@@ -2224,21 +2399,41 @@ interface SortableListProps<T> extends Omit<React$1.ComponentProps<"ul">, "child
  * `renderItem`. Hidden (kept in layout) when the list is disabled.
  */
 declare function SortableHandle({ className, children, ...props }: React$1.ComponentProps<"button">): React$1.JSX.Element;
-declare function SortableList<T>({ items, getId, onReorder, renderItem, orientation, handle, disabled, itemClassName: itemClass, className, ...props }: SortableListProps<T>): React$1.JSX.Element;
+declare function SortableList<T>({ items, getId, onReorder, renderItem, orientation, handle, disabled, touchScroll, itemClassName: itemClass, className, ...props }: SortableListProps<T>): React$1.JSX.Element;
 //#endregion
 //#region src/components/spinner.d.ts
 interface SpinnerProps extends React$1.ComponentProps<"span"> {
   /** Diameter in px. Defaults to 16. */
   size?: number;
+  /**
+   * `inverse` for a spinner on a filled surface — inside a primary or
+   * destructive Button, on a toast, on any `-foreground` pairing. The default
+   * ring is `--ds-border` with a `--ds-primary` leading edge, which all but
+   * disappears on a primary fill; `inverse` draws both from
+   * `--ds-primary-foreground` instead.
+   */
+  tone?: "default" | "inverse";
 }
 /**
- * Spinner — a ring with a primary-coloured leading edge. Announces itself as
+ * Spinner — a ring with a coloured leading edge. Announces itself as
  * `role="status"` with a "Loading" label; pass `aria-label` to override.
+ *
+ * ```tsx
+ * <Button disabled>
+ *   <Spinner tone="inverse" /> Saving…
+ * </Button>
+ * ```
  */
-declare function Spinner({ className, size, style, ...props }: SpinnerProps): React$1.JSX.Element;
+declare function Spinner({ className, size, tone, style, ...props }: SpinnerProps): React$1.JSX.Element;
 //#endregion
 //#region src/components/status-dot.d.ts
-type StatusDotTone = "accent" | "success" | "warning" | "danger" | "info" | "neutral";
+/**
+ * The error tone is `destructive`, the same spelling Button, Alert and Badge
+ * use. `danger` is a deprecated alias of it and paints the same.
+ */
+type StatusDotTone = "accent" | "success" | "warning" | "destructive" |
+/** @deprecated Use `destructive`; this alias paints the same. */
+"danger" | "info" | "neutral";
 interface StatusDotProps extends Omit<React$1.ComponentProps<"span">, "children"> {
   tone?: StatusDotTone;
   /** Adds a pinging halo behind the dot for "currently active" states. */
@@ -2323,7 +2518,7 @@ declare function Textarea({ className, autoGrow, onChange, ref, ...props }: Text
  * `toastManager` to `Toaster` when you need to fire toasts outside React.
  */
 declare const toastVariants: (props?: ({
-  variant?: "default" | "success" | "warning" | "destructive" | null | undefined;
+  variant?: "default" | "success" | "destructive" | "warning" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 /** The Base UI toast manager: `{ toasts, add, close, update, promise }`. */
 declare const useToast: typeof Toast$1.useToastManager;
@@ -2480,5 +2675,5 @@ export declare function themeFromBackground(background: unknown): ResolvedCorten
 export declare function themeFromMessage(data: unknown): CortenaTheme | null;
 export declare function useCortenaTheme(options?: UseCortenaThemeOptions): UseCortenaThemeResult;
 //#endregion
-export { type A2UIAction, type A2UIActionSpec, type A2UIBeginRendering, type A2UICatalogue, type A2UICatalogueDoc, type A2UICatalogueEntry, type A2UIChildList, type A2UIChildren, type A2UIColumn, type A2UIComponentDoc, type A2UIComponentSpec, type A2UICreateSurface, type A2UIDataBinding, type A2UIDeleteSurface, type A2UIExample, type A2UIFoldResult, type A2UIGroup, type A2UIMessage, type A2UIMessageInput, type A2UINodeInfo, type A2UIPropertyValue, type A2UIRendererProps, type A2UIResolvedAction, type A2UIRow, type A2UISurface, type A2UITableSource, type A2UIUpdateComponents, type A2UIUpdateDataModel, type A2UIView, type A2UIViewProps, type Accept, Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertIcon, type AlertProps, AlertTitle, Area, AreaChart, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, Bar, BarChart, Button, ButtonLink, type ButtonLinkProps, type ButtonProps, Calendar, CalendarDayButton, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardProps, CardTitle, CartesianGrid, Cell, Chart, type ChartConfig, ChartContainer, type ChartContainerProps, type ChartDataFor, type ChartDay, ChartEmpty, type ChartEngine, ChartError, ChartLegend, ChartLegendContent, type ChartLegendContentProps, ChartLoading, type ChartPoint, type ChartProps, type ChartRenderer, type ChartRow, type ChartScale, type ChartScales, type ChartSeries, type ChartSlice, ChartTooltip, ChartTooltipContent, type ChartTooltipContentProps, type ChartTree, type ChartType, Checkbox, type CheckboxProps, Chip, type ChipProps, type ClientSource, type CodeRendererProps, Combobox, ComboboxChip, type ComboboxChipProps, ComboboxChips, type ComboboxChipsProps, ComboboxClear, ComboboxCollection, ComboboxContent, type ComboboxContentProps, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, type ComboboxInputProps, ComboboxItem, ComboboxSeparator, ComboboxStatus, ComboboxTrigger, ComboboxValue, Command, CommandDialog, type CommandDialogProps, CommandEmpty, CommandGroup, CommandInput, CommandItem, type CommandItemProps, CommandList, CommandLoading, CommandSeparator, CommandShortcut, ComposedChart, type CortenaTheme, type CortenaThemeMessage, type DataSource, DataTable, type DataTableCell, type DataTableColumn, type DataTableColumnDef, DataTableColumnHeader, type DataTableColumnHeaderProps, type DataTableColumnMeta, type DataTableEditable, type DataTableEditingCell, DataTableExportMenu, type DataTableExportMenuProps, DataTableFacetedFilter, type DataTableFacetedFilterOption, type DataTableFacetedFilterProps, type DataTableFeatures, type DataTableInstance, DataTablePagination, type DataTablePaginationMode, type DataTablePaginationProps, type DataTableProps, type DataTableRow, type DataTableState, type DataTableTable, DataTableToolbar, type DataTableToolbarProps, DataTableView, DataTableViewOptions, type DataTableViewOptionsProps, type DataTableViewProps, DateField, type DateFieldProps, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, Dialog, DialogBody, DialogClose, DialogContent, type DialogContentProps, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuGroup, DropdownMenuItem, type DropdownMenuItemProps, DropdownMenuLabel, type DropdownMenuLabelProps, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, type DropdownMenuSubTriggerProps, DropdownMenuTrigger, Dropzone, type DropzoneProps, type DropzoneState, EmptyState, type EmptyStateProps, ErrorBanner, type ErrorBannerProps, type ExportCell, type ExportSheet, Field, FieldContent, FieldControl, type FieldControlProps, FieldDescription, type FieldDescriptionProps, FieldError, type FieldErrorItem, type FieldErrorProps, FieldGroup, FieldLabel, type FieldLabelProps, type FieldProps, Fieldset, FieldsetLegend, type FieldsetLegendProps, type FieldsetProps, FileList, type FileListProps, type FileRejection, Form, FormControl, type FormControlProps, FormDescription, type FormDescriptionProps, FormField, FormItem, type FormItemProps, FormLabel, type FormLabelProps, FormMessage, type FormMessageProps, Funnel, FunnelChart, Input, type InputProps, type JsonSchema, Kbd, Label, LabelList, type LabelProps, Line, LineChart, LoadingSkeleton, type LoadingSkeletonPreset, type LoadingSkeletonProps, Markdown, type Components as MarkdownComponents, type MarkdownProps, type NivoTheme, PageHeader, type PageHeaderProps, Pie, PieChart, PolarAngleAxis, PolarGrid, PolarRadiusAxis, Popover, PopoverClose, PopoverContent, type PopoverContentProps, PopoverDescription, PopoverTitle, PopoverTrigger, Progress, ProgressIndicator, ProgressLabel, type ProgressProps, ProgressTrack, ProgressValue, Radar, RadarChart, RadioGroup, RadioGroupItem, type RadioGroupItemProps, type RadioGroupProps, RechartsLegend, RechartsTooltip, ReferenceLine, type ResolvedCortenaTheme, ResponsiveContainer, Scatter, ScatterChart, ScrollArea, type ScrollAreaProps, ScrollBar, SectionCard, type SectionCardProps, Segmented, type SegmentedOption, type SegmentedProps, Select, SelectContent, type SelectContentProps, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, type SelectTriggerProps, SelectValue, Separator, type SeparatorProps, type ServerSource, Sheet, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Skeleton, SortableHandle, type SortableHandleProps, SortableList, type SortableListProps, type SortableRenderState, Spinner, type SpinnerProps, StatusDot, type StatusDotProps, type StatusDotTone, type SubmitHandler, Switch, type SwitchProps, type TableQuery, type TableResult, Tabs, TabsContent, TabsIndicator, TabsList, TabsTrigger, Textarea, type TextareaProps, Toast, type ToastProps, Toaster, type ToasterProps, Toolbar, ToolbarEnd, type ToolbarProps, ToolbarSeparator, ToolbarStart, Tooltip, TooltipContent, type TooltipContentProps, TooltipProvider, TooltipTrigger, type UseCortenaThemeOptions, type UseCortenaThemeResult, type UseDataTableOptions, type UseFormFieldReturn, type UseFormReturn, XAxis, YAxis, alertVariants, arrayMove, badgeVariants, buttonVariants, chipVariants, fieldVariants, formatDateDefault, formatDateISO, formatDateLong, formatDateShort, formatFileSize, formatRelative, inputClassName, labelVariants, markdownSanitizeSchema, parseDateDefault, parseDateISO, sheetVariants, textareaClassName, toastVariants, useComboboxFilter, useForm, useFormField, useToast, zodResolver };
+export { type A2UIAction, type A2UIActionSpec, type A2UIBeginRendering, type A2UICatalogue, type A2UICatalogueDoc, type A2UICatalogueEntry, type A2UIChildList, type A2UIChildren, type A2UIColumn, type A2UIComponentDoc, type A2UIComponentSpec, type A2UICreateSurface, type A2UIDataBinding, type A2UIDeleteSurface, type A2UIExample, type A2UIFoldResult, type A2UIGroup, type A2UIMessage, type A2UIMessageInput, type A2UINodeInfo, type A2UIPropertyValue, type A2UIRendererProps, type A2UIResolvedAction, type A2UIRow, type A2UISurface, type A2UITableSource, type A2UIUpdateComponents, type A2UIUpdateDataModel, type A2UIView, type A2UIViewProps, type Accept, Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertIcon, type AlertProps, AlertTitle, Area, AreaChart, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, Bar, BarChart, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, type BreadcrumbLinkProps, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, ButtonLink, type ButtonLinkProps, type ButtonProps, Calendar, CalendarDayButton, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardProps, CardTitle, CartesianGrid, Cell, Chart, type ChartConfig, ChartContainer, type ChartContainerProps, type ChartDataFor, type ChartDay, ChartEmpty, type ChartEngine, ChartError, ChartLegend, ChartLegendContent, type ChartLegendContentProps, ChartLoading, type ChartMatrix, type ChartPoint, type ChartProps, type ChartRenderer, type ChartRow, type ChartScale, type ChartScales, type ChartSeries, type ChartSlice, ChartTooltip, ChartTooltipContent, type ChartTooltipContentProps, type ChartTree, type ChartType, Checkbox, type CheckboxProps, Chip, type ChipProps, type ClientSource, type CodeRendererProps, Combobox, ComboboxChip, type ComboboxChipProps, ComboboxChips, type ComboboxChipsProps, ComboboxClear, ComboboxCollection, ComboboxContent, type ComboboxContentProps, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, type ComboboxInputProps, ComboboxItem, ComboboxSeparator, ComboboxStatus, ComboboxTrigger, ComboboxValue, Command, CommandDialog, type CommandDialogProps, CommandEmpty, CommandGroup, CommandInput, CommandItem, type CommandItemProps, CommandList, CommandLoading, CommandSeparator, CommandShortcut, ComposedChart, type CortenaTheme, type CortenaThemeMessage, type DataSource, DataTable, type DataTableCell, type DataTableColumn, type DataTableColumnDef, DataTableColumnHeader, type DataTableColumnHeaderProps, type DataTableColumnMeta, type DataTableEditable, type DataTableEditingCell, DataTableExportMenu, type DataTableExportMenuProps, DataTableFacetedFilter, type DataTableFacetedFilterOption, type DataTableFacetedFilterProps, type DataTableFeatures, type DataTableInstance, DataTablePagination, type DataTablePaginationMode, type DataTablePaginationProps, type DataTableProps, type DataTableRow, type DataTableState, type DataTableTable, DataTableToolbar, type DataTableToolbarProps, DataTableView, DataTableViewOptions, type DataTableViewOptionsProps, type DataTableViewProps, DateField, type DateFieldProps, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, Dialog, DialogBody, DialogClose, DialogContent, type DialogContentProps, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuGroup, DropdownMenuItem, type DropdownMenuItemProps, DropdownMenuLabel, type DropdownMenuLabelProps, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, type DropdownMenuSubTriggerProps, DropdownMenuTrigger, Dropzone, type DropzoneProps, type DropzoneState, EmptyState, type EmptyStateProps, ErrorBanner, type ErrorBannerProps, type ExportCell, type ExportSheet, Field, FieldContent, FieldControl, type FieldControlProps, FieldDescription, type FieldDescriptionProps, FieldError, type FieldErrorItem, type FieldErrorProps, FieldGroup, FieldLabel, type FieldLabelProps, type FieldProps, Fieldset, FieldsetLegend, type FieldsetLegendProps, type FieldsetProps, FileList, type FileListProps, type FileRejection, Form, FormControl, type FormControlProps, FormDescription, type FormDescriptionProps, FormField, FormItem, type FormItemProps, FormLabel, type FormLabelProps, FormMessage, type FormMessageProps, Funnel, FunnelChart, Input, type InputProps, type JsonSchema, Kbd, Label, LabelList, type LabelProps, Line, LineChart, LoadingSkeleton, type LoadingSkeletonPreset, type LoadingSkeletonProps, Markdown, type Components as MarkdownComponents, type MarkdownProps, type NivoTheme, PageHeader, type PageHeaderProps, Pie, PieChart, PolarAngleAxis, PolarGrid, PolarRadiusAxis, Popover, PopoverClose, PopoverContent, type PopoverContentProps, PopoverDescription, PopoverTitle, PopoverTrigger, Progress, ProgressIndicator, ProgressLabel, type ProgressProps, ProgressTrack, ProgressValue, Radar, RadarChart, RadioGroup, RadioGroupItem, type RadioGroupItemProps, type RadioGroupProps, RechartsLegend, RechartsTooltip, ReferenceLine, type ResolvedCortenaTheme, ResponsiveContainer, Scatter, ScatterChart, ScrollArea, type ScrollAreaProps, ScrollBar, SectionCard, type SectionCardProps, Segmented, type SegmentedOption, type SegmentedProps, Select, SelectContent, type SelectContentProps, SelectGroup, SelectItem, SelectLabel, type SelectProps, SelectSeparator, SelectTrigger, type SelectTriggerProps, SelectValue, Separator, type SeparatorProps, type ServerSource, Sheet, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, type SheetProps, SheetTitle, SheetTrigger, Skeleton, SortableHandle, type SortableHandleProps, SortableList, type SortableListProps, type SortableRenderState, type SortableReorderDetails, Spinner, type SpinnerProps, StatusDot, type StatusDotProps, type StatusDotTone, type SubmitHandler, Switch, type SwitchProps, type TableQuery, type TableResult, Tabs, TabsContent, TabsIndicator, TabsList, TabsTrigger, Textarea, type TextareaProps, Toast, type ToastProps, Toaster, type ToasterProps, Toolbar, ToolbarEnd, type ToolbarProps, ToolbarSeparator, ToolbarStart, Tooltip, TooltipContent, type TooltipContentProps, TooltipProvider, TooltipTrigger, type UseCortenaThemeOptions, type UseCortenaThemeResult, type UseDataTableOptions, type UseFormFieldReturn, type UseFormReturn, XAxis, YAxis, alertVariants, arrayMove, badgeVariants, buttonVariants, chipVariants, fieldVariants, formatDateDefault, formatDateISO, formatDateLong, formatDateShort, formatFileSize, formatRelative, inputClassName, labelVariants, markdownSanitizeSchema, parseDateDefault, parseDateISO, sheetVariants, textareaClassName, toastVariants, useComboboxFilter, useForm, useFormField, useToast, zodResolver };
 //# sourceMappingURL=index.d.ts.map