@vitavision/ui 0.11.0 → 0.13.0

package/src/components/ui/Slider.tsx

@@ -69,10 +69,7 @@ export function Slider({
         max={max}
         step={step}
         disabled={disabled}
-        className={cn(
-          "relative flex h-5 min-w-0 flex-1 touch-none items-center select-none",
-          "data-disabled:opacity-50",
-        )}
+        className={cn("relative flex h-5 min-w-0 flex-1 touch-none items-center select-none", "data-disabled:opacity-50")}
       >
         <RadixSlider.Track className="relative h-1 grow overflow-hidden rounded-full bg-line">
           <RadixSlider.Range className="absolute h-full bg-signal" />
@@ -88,9 +85,7 @@ export function Slider({
           )}
         />
       </RadixSlider.Root>
-      {readout && (
-        <span className="shrink-0 font-mono text-xs text-fg tabular-nums">{readout}</span>
-      )}
+      {readout && <span className="shrink-0 font-mono text-xs text-fg tabular-nums">{readout}</span>}
     </div>
   );
 }

package/src/components/ui/Table.tsx

@@ -4,12 +4,24 @@
  * `numeric` is the column property that matters here. Quantities are set in mono with
  * tabular figures and aligned right, so a column of scores or measurements can be compared
  * by eye down its decimal point rather than read one row at a time.
+ *
+ * Sorting is per column and follows the sortable-table pattern of the ARIA Authoring
+ * Practices: the header's content is a button, and only the sorted header carries
+ * `aria-sort`. The order itself lives in `tableSort.ts`.
+ *
+ * `windowed` renders only the rows in view, between two spacer rows that keep the scroll
+ * height, so a table of thousands of rows scrolls as fast as one of thirty. It stays a real
+ * `<table>`: the rows that are rendered carry `aria-rowindex` and the table `aria-rowcount`, so
+ * a reader still hears "row 2,041 of 5,001". The arithmetic lives in `tableWindow.ts`.
  */
 
-import type { KeyboardEvent, MouseEvent, ReactNode } from "react";
+import { ArrowDown, ArrowUp, ArrowUpDown } from "lucide-react";
+import { type KeyboardEvent, type MouseEvent, type ReactNode, useLayoutEffect, useMemo, useRef, useState } from "react";
 
 import { byDensity, useDensity } from "./Density";
-import { cn } from "./cn";
+import { cn, focusRing, focusRingInset } from "./cn";
+import { isSortable, nextSort, type SortDirection, sortOrder, type TableSort } from "./tableSort";
+import { navigate, rowWindow, scrollTopFor } from "./tableWindow";
 
 /** One column of a `Table`: its header and how to render a row's cell. */
 export type Column<Row> = {
@@ -23,14 +35,76 @@ export type Column<Row> = {
   width?: string;
   /** The cell's content for a row. */
   cell: (row: Row) => ReactNode;
+  /**
+   * Whether the header sorts the table. Defaults to `true` when the column has a `sortValue`
+   * or a `compare`. Set it `true` with neither for a column the app sorts itself (see the
+   * table's `manualSort`), or `false` to keep a column with a `sortValue` unsortable.
+   */
+  sortable?: boolean | undefined;
+  /**
+   * The value the column sorts by. Numbers compare by value; strings by a fixed English
+   * collation that reads digit runs as numbers ("frame 9" before "frame 10"), so a server
+   * render and the browser agree; numbers come before strings. `null`, `undefined` and `NaN`
+   * go last in both directions.
+   */
+  sortValue?: ((row: Row) => number | string | null | undefined) | undefined;
+  /**
+   * A full ascending comparison, for an order one value cannot express (two fields, a rank):
+   * negative when `a` comes first. Takes precedence over `sortValue`. Reversed for
+   * `"descending"`; rows that compare equal keep their order in `rows` either way.
+   */
+  compare?: ((a: Row, b: Row) => number) | undefined;
+  /**
+   * The direction of the first click on the header. Defaults to `"ascending"`; `"descending"`
+   * suits a score, where the best comes first.
+   */
+  firstSort?: SortDirection | undefined;
 };
 
+/**
+ * Windowed rendering for a long table: only the rows in view, plus `overscan` on each side,
+ * are in the DOM. The rows scroll under a sticky header drawn on `surface`, the panel colour.
+ */
+export interface TableWindowing {
+  /**
+   * Every body row's height in px. Rows are drawn exactly this tall and cells keep to one line
+   * (longer content is cut with an ellipsis), so it must be at least the density's own row
+   * height: 36 px comfortable, 22 px compact.
+   */
+  rowHeight: number;
+  /**
+   * The scroll area's height in px, header included. Leave it out to fill the height of the
+   * container, which must then have one (a flex child with `min-h-0`, a fixed-height panel).
+   */
+  height?: number | undefined;
+  /** Rows rendered beyond each edge of the view, so a fast scroll shows no gap. Defaults to 8. */
+  overscan?: number | undefined;
+}
+
+/** Rows per screen before a windowed table has measured itself (a server render, the first paint). */
+const INITIAL_ROWS = 20;
+
+/** The header icon for a sort state: the direction when sorted, both arrows when only sortable. */
+const SORT_ICONS = { ascending: ArrowUp, descending: ArrowDown, none: ArrowUpDown } as const;
+
 /**
  * A table of rows, with numeric columns set in mono and right-aligned.
  *
  * With `onRowClick` the rows are keyboard-reachable (Tab, then Enter or Space) while keeping
  * their table semantics. The active row carries `aria-current` and `data-state="active"`;
  * padding follows the density in force. With no rows it renders the `empty` message instead.
+ *
+ * A column with a `sortValue` or a `compare` gets a header button: each click moves its sort
+ * from the column's `firstSort` direction to the other one, then back to the rows' own order.
+ * The sorted header carries `aria-sort` and `data-sort` (`"ascending"` or `"descending"`);
+ * other sortable headers carry `data-sort="none"`. The sort is kept by the table (from
+ * `defaultSort`) or controlled (`sort` with `onSortChange`); with `manualSort` the headers
+ * show it and the rows render as given. Row callbacks always receive a row's index in `rows`,
+ * whatever the order on screen.
+ *
+ * Activatable rows also move focus with the arrow keys, Page Up / Page Down and Home / End.
+ * With `windowed` the table scrolls itself (vertically, under a sticky header), renders only the
+ * rows in view, and uses a fixed layout: give columns a `width` where the content needs it.
  */
 export function Table<Row>({
   columns,
@@ -42,12 +116,17 @@ export function Table<Row>({
   onRowClick,
   isRowActive,
   onRowHover,
+  sort: controlledSort,
+  defaultSort = null,
+  onSortChange,
+  manualSort = false,
+  windowed,
 }: {
   /** The columns, in order. */
   columns: Column<Row>[];
-  /** The rows, in order. */
+  /** The rows, in their own order: the order shown while the table is not sorted. */
   rows: Row[];
-  /** A stable key per row. */
+  /** A stable key per row. `index` is the row's position in `rows`, whatever the sort. */
   rowKey: (row: Row, index: number) => string | number;
   /** Shown instead of the table when there are no rows. Defaults to "Nothing here.". */
   empty?: ReactNode;
@@ -58,103 +137,270 @@ export function Table<Row>({
   /** Makes rows activatable. Keyboard-reachable, so a table used as a list of
    * destinations is not a mouse-only control. The event is passed so a caller can read
    * modifiers — a list kept in step with a canvas needs shift-range and meta-toggle to mean
-   * the same thing in both places. */
-  onRowClick?: (
-    row: Row,
-    index: number,
-    event: MouseEvent<HTMLTableRowElement> | KeyboardEvent<HTMLTableRowElement>,
-  ) => void;
+   * the same thing in both places. `index` is the row's position in `rows`, whatever the
+   * sort. */
+  onRowClick?: (row: Row, index: number, event: MouseEvent<HTMLTableRowElement> | KeyboardEvent<HTMLTableRowElement>) => void;
   /** Marks the row that is current — the selected match, the open frame. Rendered as
-   * `aria-current`, so it is announced rather than only tinted. */
+   * `aria-current`, so it is announced rather than only tinted. `index` is the row's
+   * position in `rows`, whatever the sort. */
   isRowActive?: (row: Row, index: number) => boolean;
   /** Pointer enter/leave, for tables kept in step with a canvas overlay.
-   * `null` on leave. */
+   * `null` on leave. `index` is the row's position in `rows`, whatever the sort. */
   onRowHover?: (row: Row | null, index: number | null) => void;
+  /**
+   * The sort, controlled: a column `key` and a direction, or `null` for the rows' own order.
+   * Leave it undefined and the table keeps the sort itself, starting from `defaultSort`.
+   */
+  sort?: TableSort | null | undefined;
+  /** The sort the table starts with when `sort` is not given. Defaults to `null`, the rows' own order. */
+  defaultSort?: TableSort | null | undefined;
+  /**
+   * Called on a header click with the new sort: the column's `firstSort` direction, then the
+   * other, then `null`. A click on another column starts that column at its `firstSort`.
+   */
+  onSortChange?: ((sort: TableSort | null) => void) | undefined;
+  /**
+   * The app orders the rows (on a server, say): the headers show the sort and report clicks,
+   * and the rows render exactly as given. Mark the columns it can sort `sortable: true`.
+   */
+  manualSort?: boolean | undefined;
+  /**
+   * Render only the rows in view, for a long table: every row `rowHeight` tall, in a scroll
+   * area of `height` (or the container's height) under a sticky header. Sorting, row
+   * callbacks and keyboard navigation work as without it.
+   */
+  windowed?: TableWindowing | undefined;
 }) {
   const density = useDensity();
+  const [ownSort, setOwnSort] = useState<TableSort | null>(defaultSort);
+  const controlled = controlledSort !== undefined;
+  const sort = controlled ? controlledSort : ownSort;
+  // Indices into `rows`, so a row keeps its own index (and key) for the callbacks below.
+  const order = useMemo(
+    () => (manualSort ? rows.map((_, index) => index) : sortOrder(rows, columns, sort)),
+    [rows, columns, sort, manualSort],
+  );
+
+  const changeSort = (column: Column<Row>) => {
+    const next = nextSort(sort, column);
+    if (!controlled) setOwnSort(next);
+    onSortChange?.(next);
+  };
+
+  const rowHeight = windowed?.rowHeight ?? 0;
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const headRef = useRef<HTMLTableSectionElement>(null);
+  const bodyRef = useRef<HTMLTableSectionElement>(null);
+  // The row to focus once it is rendered: a key press may scroll to a row that is not in the DOM yet.
+  const pendingFocus = useRef<number | null>(null);
+  const [scrollTop, setScrollTop] = useState(0);
+  const [measured, setMeasured] = useState<{ viewport: number; header: number } | null>(null);
+  const viewportHeight = measured?.viewport ?? windowed?.height ?? INITIAL_ROWS * rowHeight;
+  const headerHeight = measured?.header ?? 0;
+  const range = windowed
+    ? rowWindow({ rowCount: order.length, rowHeight, scrollTop, viewportHeight, headerHeight, overscan: windowed.overscan ?? 8 })
+    : { start: 0, end: order.length, before: 0, after: 0 };
+
+  const isWindowed = windowed !== undefined;
+  useLayoutEffect(() => {
+    const scroller = scrollRef.current;
+    if (!isWindowed || !scroller || typeof ResizeObserver === "undefined") return;
+    const measure = () => {
+      const next = { viewport: scroller.clientHeight, header: headRef.current?.offsetHeight ?? 0 };
+      setMeasured((last) => (last?.viewport === next.viewport && last.header === next.header ? last : next));
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(scroller);
+    return () => observer.disconnect();
+  }, [isWindowed]);
+
+  useLayoutEffect(() => {
+    const target = pendingFocus.current;
+    if (target === null) return;
+    const row = bodyRef.current?.querySelector<HTMLElement>(`tr[data-position="${target}"]`);
+    if (!row) return;
+    pendingFocus.current = null;
+    row.focus({ preventScroll: isWindowed });
+  });
+
+  /** Moves focus from the row at `position` for a navigation key; `true` when the key was one. */
+  const moveFocus = (key: string, position: number): boolean => {
+    const page = windowed ? Math.floor((viewportHeight - headerHeight) / rowHeight) : 10;
+    const target = navigate(key, position, order.length, page);
+    if (target === null) return false;
+    pendingFocus.current = target;
+    const scroller = scrollRef.current;
+    if (windowed && scroller) {
+      const top = scrollTopFor(target, { rowHeight, scrollTop: scroller.scrollTop, viewportHeight, headerHeight });
+      scroller.scrollTop = top;
+      // Render the target's window now rather than on the scroll event, so it can take focus.
+      setScrollTop(scroller.scrollTop);
+    }
+    const row = bodyRef.current?.querySelector<HTMLElement>(`tr[data-position="${target}"]`);
+    if (row && !windowed) {
+      pendingFocus.current = null;
+      row.focus();
+    }
+    return true;
+  };
 
   if (rows.length === 0) {
-    return (
-      <p
-        className={cn(
-          "text-center text-fg-muted",
-          byDensity(density, "py-6 text-sm", "py-3 text-xs"),
-          className,
-        )}
-      >
-        {empty}
-      </p>
-    );
+    return <p className={cn("text-center text-fg-muted", byDensity(density, "py-6 text-sm", "py-3 text-xs"), className)}>{empty}</p>;
   }
 
+  const spacer = (height: number) => (
+    // Stands in for the rows outside the window. Hidden: it is no row of the table.
+    <tr aria-hidden="true" style={{ height }}>
+      <td colSpan={columns.length} className="p-0" />
+    </tr>
+  );
+
+  // A scroll area must be reachable from the keyboard: through its rows or header buttons when
+  // it has them, else as a tab stop of its own.
+  const scrollStop = windowed !== undefined && !onRowClick && !columns.some(isSortable);
+
   return (
-    <div className={cn("w-full overflow-x-auto", className)}>
-      <table className={cn("w-full text-left", byDensity(density, "text-sm", "text-[11px]"))}>
+    <div
+      ref={scrollRef}
+      className={cn("w-full", windowed ? scrollStop && focusRingInset : "overflow-x-auto", className)}
+      // What the window arithmetic relies on is inline rather than a class, so it holds under
+      // any stylesheet: the scroll area, the fixed layout, the sticky header, the row height.
+      style={windowed ? { overflow: "auto", height: windowed.height ?? "100%" } : undefined}
+      onScroll={windowed ? (event) => setScrollTop(event.currentTarget.scrollTop) : undefined}
+      {...(scrollStop ? { tabIndex: 0, role: "region", "aria-label": caption ?? "Table" } : {})}
+    >
+      <table
+        className={cn("w-full text-left", byDensity(density, "text-sm", "text-[11px]"))}
+        style={windowed ? { tableLayout: "fixed" } : undefined}
+        aria-rowcount={windowed ? order.length + 1 : undefined}
+      >
         {caption && <caption className="sr-only">{caption}</caption>}
-        <thead>
-          <tr className="border-b border-line">
-            {columns.map((column) => (
-              <th
-                key={column.key}
-                scope="col"
-                style={column.width ? { width: column.width } : undefined}
-                className={cn(
-                  "font-medium text-fg-muted",
-                  byDensity(density, "pb-2 pr-3 text-xs", "pb-1 pr-2 text-[10px]"),
-                  column.numeric && "text-right",
-                )}
-              >
-                {column.header}
-              </th>
-            ))}
-          </tr>
-        </thead>
-        <tbody>
-          {rows.map((row, index) => (
-            <tr
-              key={rowKey(row, index)}
-              data-state={isRowActive?.(row, index) ? "active" : undefined}
-              className={cn(
-                "border-b border-line/60 last:border-0",
-                onRowClick && "cursor-pointer hover:bg-raised",
-                isRowActive?.(row, index) && "bg-signal/10",
-              )}
-              tabIndex={onRowClick ? 0 : undefined}
-              // Deliberately *not* `role="button"`. Overriding a `<tr>`'s implicit `row`
-              // makes its `<td>`s' implicit `cell` invalid too — the cells have no row to
-              // belong to — so a screen reader stops announcing the table as a table and a
-              // reader loses the column each value came from, which on a table of
-              // quantities is the whole content. `tabIndex` plus the Enter/Space handler
-              // below is what makes the row reachable; the role stays what the element is.
-              aria-current={isRowActive?.(row, index) ? true : undefined}
-              onClick={onRowClick ? (event) => onRowClick(row, index, event) : undefined}
-              onKeyDown={
-                onRowClick
-                  ? (event) => {
-                      if (event.key === "Enter" || event.key === " ") {
-                        event.preventDefault();
-                        onRowClick(row, index, event);
-                      }
-                    }
-                  : undefined
-              }
-              onPointerEnter={onRowHover ? () => onRowHover(row, index) : undefined}
-              onPointerLeave={onRowHover ? () => onRowHover(null, null) : undefined}
-            >
-              {columns.map((column) => (
-                <td
+        <thead ref={headRef}>
+          <tr className="border-b border-line" aria-rowindex={windowed ? 1 : undefined}>
+            {columns.map((column) => {
+              const sortable = isSortable(column);
+              const direction = sortable && sort?.key === column.key ? sort.direction : undefined;
+              const SortIcon = SORT_ICONS[direction ?? "none"];
+              return (
+                <th
                   key={column.key}
+                  scope="col"
+                  style={
+                    windowed
+                      ? { position: "sticky", top: 0, zIndex: 1, ...(column.width ? { width: column.width } : {}) }
+                      : column.width
+                        ? { width: column.width }
+                        : undefined
+                  }
+                  // Only the sorted header: `aria-sort="none"` on every other one would be
+                  // announced on each, and tells a reader nothing.
+                  aria-sort={direction}
+                  data-sort={sortable ? (direction ?? "none") : undefined}
                   className={cn(
-                    "align-middle text-fg last:pr-0",
-                    byDensity(density, "py-2 pr-3", "py-0.5 pr-2"),
-                    column.numeric && "text-right font-mono tabular-nums",
+                    // `last:pr-0`, as on the body cells: the last column's header ends where
+                    // its values do, so a numeric header sits flush with its numbers.
+                    "font-medium text-fg-muted last:pr-0",
+                    byDensity(density, "pb-2 pr-3 text-xs", "pb-1 pr-2 text-[10px]"),
+                    column.numeric && "text-right",
+                    // A sticky cell leaves its row's border behind: it draws its own rule.
+                    windowed && "bg-surface shadow-[inset_0_-1px_0_var(--line)]",
                   )}
                 >
-                  {column.cell(row)}
-                </td>
-              ))}
-            </tr>
-          ))}
+                  {sortable ? (
+                    <button
+                      type="button"
+                      onClick={() => changeSort(column)}
+                      className={cn(
+                        // Block-level `flex`, not `inline-flex`: an inline box would sit on the
+                        // cell's line box and make a sortable header row 2px taller than a plain
+                        // one. The padding, cancelled by the margin, gives the focus ring room
+                        // without moving the label off the column's edge.
+                        "-mx-1 flex w-fit max-w-full cursor-pointer items-center gap-1 rounded-control px-1",
+                        "font-medium transition-colors hover:text-fg",
+                        focusRing,
+                        // The arrow sits on the inner side of a right-aligned header, so the
+                        // label stays flush with the numbers under it.
+                        column.numeric ? "ml-auto flex-row-reverse text-right" : "text-left",
+                        direction && "text-fg",
+                      )}
+                    >
+                      {column.header}
+                      <SortIcon
+                        aria-hidden
+                        className={cn("shrink-0", byDensity(density, "size-3", "size-2.5"), !direction && "text-fg-subtle")}
+                      />
+                    </button>
+                  ) : (
+                    column.header
+                  )}
+                </th>
+              );
+            })}
+          </tr>
+        </thead>
+        <tbody ref={bodyRef}>
+          {range.before > 0 && spacer(range.before)}
+          {order.slice(range.start, range.end).map((index, offset) => {
+            const row = rows[index]!;
+            const active = isRowActive?.(row, index) ?? false;
+            const position = range.start + offset;
+            return (
+              <tr
+                key={rowKey(row, index)}
+                data-position={position}
+                aria-rowindex={windowed ? position + 2 : undefined}
+                style={windowed ? { height: rowHeight } : undefined}
+                data-state={active ? "active" : undefined}
+                className={cn(
+                  // A windowed row's rule is a shadow on its cells: a collapsed border would add
+                  // half a pixel to every row, and the arithmetic counts whole rows.
+                  !windowed && "border-b border-line/60 last:border-0",
+                  onRowClick && "cursor-pointer hover:bg-raised",
+                  active && "bg-signal/10",
+                )}
+                tabIndex={onRowClick ? 0 : undefined}
+                // Deliberately *not* `role="button"`. Overriding a `<tr>`'s implicit `row`
+                // makes its `<td>`s' implicit `cell` invalid too — the cells have no row to
+                // belong to — so a screen reader stops announcing the table as a table and a
+                // reader loses the column each value came from, which on a table of
+                // quantities is the whole content. `tabIndex` plus the Enter/Space handler
+                // below is what makes the row reachable; the role stays what the element is.
+                aria-current={active ? true : undefined}
+                onClick={onRowClick ? (event) => onRowClick(row, index, event) : undefined}
+                onKeyDown={
+                  onRowClick
+                    ? (event) => {
+                        if (event.key === "Enter" || event.key === " ") {
+                          event.preventDefault();
+                          onRowClick(row, index, event);
+                          // Navigation keys belong to a control inside the row while it has focus.
+                        } else if (event.target === event.currentTarget && moveFocus(event.key, position)) event.preventDefault();
+                      }
+                    : undefined
+                }
+                onPointerEnter={onRowHover ? () => onRowHover(row, index) : undefined}
+                onPointerLeave={onRowHover ? () => onRowHover(null, null) : undefined}
+              >
+                {columns.map((column) => (
+                  <td
+                    key={column.key}
+                    className={cn(
+                      "align-middle text-fg last:pr-0",
+                      byDensity(density, "py-2 pr-3", "py-0.5 pr-2"),
+                      column.numeric && "text-right font-mono tabular-nums",
+                      windowed && "shadow-[inset_0_-1px_0_color-mix(in_oklab,var(--line)_60%,transparent)]",
+                    )}
+                    // One line per row keeps every row `rowHeight` tall.
+                    style={windowed ? { whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" } : undefined}
+                  >
+                    {column.cell(row)}
+                  </td>
+                ))}
+              </tr>
+            );
+          })}
+          {range.after > 0 && spacer(range.after)}
         </tbody>
       </table>
     </div>

package/src/components/ui/Textarea.tsx

@@ -0,0 +1,149 @@
+/*
+ * Multi-line text entry.
+ *
+ * The auto-grow is measured, not CSS: `field-sizing: content` would need no script, but it
+ * is not in every engine the packages run in (the desktop shells embed WebKit), and it
+ * cannot stop at a row count. The textarea renders `minRows` tall on the server, so the
+ * first paint already has the right floor; after mount its height follows the content
+ * between the two bounds.
+ */
+
+import { type ChangeEvent, type ComponentProps, type Ref, useCallback, useLayoutEffect, useRef } from "react";
+
+import { useFieldDescription } from "./Field";
+import { controlClasses } from "./Input";
+import { cn } from "./cn";
+
+/**
+ * Props of `Textarea`: every `<textarea>` prop, `ref` included, plus an invalid state, the
+ * mono face, and growing with the content between `minRows` and `maxRows`.
+ */
+export type TextareaProps = ComponentProps<"textarea"> & {
+  /** Called with the new text on every edit, alongside the native `onChange`. */
+  onValueChange?: ((value: string) => void) | undefined;
+  /**
+   * Marks the value as wrong: `aria-invalid`, `data-invalid` and a border in the defect
+   * colour. Inside a `Field` with an `error` it is on without this. Say what is wrong in
+   * text too (the field's `error`): the border alone is a colour.
+   */
+  invalid?: boolean | undefined;
+  /** Sets the text in IBM Plex Mono, for code, JSON, lists, or strings whose characters all matter. */
+  mono?: boolean | undefined;
+  /**
+   * Grows with the content from this many lines. Set it or `maxRows` to turn growing on;
+   * `rows` is then ignored.
+   */
+  minRows?: number | undefined;
+  /** Stops growing at this many lines and scrolls beyond them. Set it or `minRows` to turn growing on. */
+  maxRows?: number | undefined;
+};
+
+/** Sets a ref of either kind. */
+function assign<T>(ref: Ref<T> | undefined, value: T | null): void {
+  if (typeof ref === "function") ref(value);
+  else if (ref) ref.current = value;
+}
+
+/**
+ * Fits a textarea's height to its content between `minRows` and `maxRows` lines, and scrolls
+ * only past the cap.
+ */
+function fit(node: HTMLTextAreaElement, minRows: number, maxRows: number | undefined): void {
+  const style = getComputedStyle(node);
+  // `normal` is no length: take the usual 1.2 of the font size.
+  const line = Number.parseFloat(style.lineHeight) || Number.parseFloat(style.fontSize) * 1.2 || 20;
+  const border = Number.parseFloat(style.borderTopWidth) + Number.parseFloat(style.borderBottomWidth);
+  const chrome = Number.parseFloat(style.paddingTop) + Number.parseFloat(style.paddingBottom) + border;
+  const min = minRows * line + chrome;
+  const max = maxRows === undefined ? Number.POSITIVE_INFINITY : Math.max(min, maxRows * line + chrome);
+  // Measure the content at the smallest height, so the box can shrink as well as grow.
+  node.style.height = `${min}px`;
+  const content = node.scrollHeight + border;
+  node.style.height = `${Math.min(Math.max(content, min), max)}px`;
+  node.style.overflowY = content > max + 0.5 ? "auto" : "hidden";
+}
+
+/**
+ * Multi-line text, on the shared control palette. Takes every `<textarea>` prop, `ref`
+ * included; inside a `Field` it is described by the field's description and error, and
+ * shown invalid while the field has an error.
+ *
+ * With `minRows` or `maxRows` it grows with its content between the two (and scrolls past
+ * `maxRows`); without them it is `rows` tall and the reader can resize it. State is exposed
+ * as `data-invalid`.
+ */
+export function Textarea({
+  className,
+  "aria-describedby": describedBy,
+  invalid,
+  mono = false,
+  minRows,
+  maxRows,
+  rows,
+  value,
+  onChange,
+  onValueChange,
+  ref,
+  ...rest
+}: TextareaProps) {
+  const field = useFieldDescription(describedBy);
+  const isInvalid = invalid === true || field["aria-invalid"] === true;
+  const grows = minRows !== undefined || maxRows !== undefined;
+  const floor = Math.max(1, Math.floor(minRows ?? 1));
+  const cap = maxRows === undefined ? undefined : Math.max(floor, Math.floor(maxRows));
+
+  const node = useRef<HTMLTextAreaElement | null>(null);
+  const setNode = useCallback(
+    (element: HTMLTextAreaElement | null) => {
+      node.current = element;
+      assign(ref, element);
+    },
+    [ref],
+  );
+
+  // On mount, and when a controlled value changes from outside (typing refits in `change`).
+  useLayoutEffect(() => {
+    if (grows && node.current) fit(node.current, floor, cap);
+  }, [grows, floor, cap, mono, value]);
+
+  // A change of width rewraps the text.
+  useLayoutEffect(() => {
+    const element = node.current;
+    if (!grows || !element || typeof ResizeObserver === "undefined") return undefined;
+    let width = element.clientWidth;
+    const observer = new ResizeObserver(() => {
+      if (element.clientWidth === width) return;
+      width = element.clientWidth;
+      fit(element, floor, cap);
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [grows, floor, cap]);
+
+  const change = (event: ChangeEvent<HTMLTextAreaElement>) => {
+    onChange?.(event);
+    onValueChange?.(event.currentTarget.value);
+    if (grows) fit(event.currentTarget, floor, cap);
+  };
+
+  return (
+    <textarea
+      {...field}
+      aria-invalid={isInvalid || undefined}
+      data-invalid={isInvalid ? "" : undefined}
+      {...rest}
+      {...(value === undefined ? {} : { value })}
+      ref={setNode}
+      rows={grows ? floor : rows}
+      onChange={change}
+      className={cn(
+        controlClasses,
+        "py-1.5",
+        grows && "resize-none",
+        mono && "font-mono",
+        "data-invalid:border-defect data-invalid:hover:border-defect",
+        className,
+      )}
+    />
+  );
+}