@vitavision/ui 0.12.0 → 0.14.0

package/src/components/ui/PoseInput.tsx

@@ -110,14 +110,12 @@ export function PoseInput({
   const scale = translationUnit === "mm" ? 1000 : 1;
   const tPrecision = translationPrecision ?? (translationUnit === "mm" ? 1 : 4);
   const translation = value.translation.map((component) => component * scale);
-  const radians =
-    typed !== null && sameQuaternion(typed.rotation, value.rotation) ? typed.angles : rotationView.toEuler(value.rotation);
+  const radians = typed !== null && sameQuaternion(typed.rotation, value.rotation) ? typed.angles : rotationView.toEuler(value.rotation);
   const degrees = radians.map((angle) => angle * DEGREES);
   const angleLabels = rotationView.labels ?? DEFAULT_ANGLE_LABELS;
 
   if (readOnly) {
-    const join = (values: readonly number[], precision: number) =>
-      values.map((component) => formatNumber(component, precision)).join(" ");
+    const join = (values: readonly number[], precision: number) => values.map((component) => formatNumber(component, precision)).join(" ");
     return (
       <div role="group" aria-label={ariaLabel} data-readonly="" className={cn("min-w-0", className)}>
         <ReadoutStrip
@@ -149,7 +147,11 @@ export function PoseInput({
     <div
       role="group"
       aria-label={ariaLabel}
-      className={cn("grid min-w-0 grid-cols-[auto_minmax(0,1fr)] items-center gap-x-2", byDensity(density, "gap-y-2", "gap-y-1"), className)}
+      className={cn(
+        "grid min-w-0 grid-cols-[auto_minmax(0,1fr)] items-center gap-x-2",
+        byDensity(density, "gap-y-2", "gap-y-1"),
+        className,
+      )}
     >
       <span aria-hidden className={rowLabel}>
         Translation

package/src/components/ui/Progress.tsx

@@ -0,0 +1,80 @@
+/*
+ * How far a long operation has got.
+ *
+ * The bar is in `signal`, not a verdict colour: progress is not a pass or a fail, and a bar
+ * that turned green at 100 % would claim a verdict nobody made. The value text is "412 of
+ * 2,556" rather than a bare percentage, because the count is what a reader checks against
+ * the work ("2,556 strings"), and a screen reader says it as written.
+ */
+
+import type { ComponentProps } from "react";
+
+import { byDensity, useDensity } from "./Density";
+import { cn } from "./cn";
+
+/** Counts written the same on the server and in every browser: `2,556`, `0.5`. */
+const count = new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 });
+
+/**
+ * The accessible value text of a progress: `"412 of 2,556"`, or `null` while indeterminate.
+ *
+ * @param value - Done so far; `null` or `undefined` for an unknown amount.
+ * @param max - The whole. Defaults to 100.
+ * @returns The text, with the value clamped to `[0, max]`.
+ */
+export function progressText(value: number | null | undefined, max = 100): string | null {
+  if (value === null || value === undefined || !Number.isFinite(value)) return null;
+  const whole = max > 0 ? max : 100;
+  return `${count.format(Math.min(Math.max(value, 0), whole))} of ${count.format(whole)}`;
+}
+
+/** Props of `Progress`: a value out of a `max`, or none for an unknown amount, plus the `<div>` props. */
+export type ProgressProps = Omit<ComponentProps<"div">, "children" | "role"> & {
+  /** Done so far, from 0 to `max`; clamped. `null` or left out: indeterminate, the amount unknown. */
+  value?: number | null | undefined;
+  /** The whole. Defaults to 100; a value ≤ 0 counts as 100. */
+  max?: number | undefined;
+  /**
+   * What a screen reader says for the value. Defaults to `"412 of 2,556"`; give your own when
+   * the unit matters ("412 of 2,556 strings").
+   */
+  valueText?: string | undefined;
+};
+
+/**
+ * A progress bar: determinate when it has a `value` (a `max`, 100 by default), indeterminate
+ * without one. Name it with `aria-label` or `aria-labelledby`.
+ *
+ * A `progressbar` with `aria-valuenow`, `aria-valuemax` and `aria-valuetext` ("412 of 2,556",
+ * or your `valueText`); indeterminate, it has none of them, as the ARIA pattern asks.
+ * The track follows the density in force. State is exposed as `data-state`
+ * (`"indeterminate"`, `"loading"` or `"complete"`). With reduced motion the indeterminate bar
+ * holds still.
+ */
+export function Progress({ value, max = 100, valueText, className, ...rest }: ProgressProps) {
+  const density = useDensity();
+  const whole = max > 0 ? max : 100;
+  const text = progressText(value, whole);
+  const done = text === null ? null : Math.min(Math.max(value as number, 0), whole);
+  const state = done === null ? "indeterminate" : done >= whole ? "complete" : "loading";
+  return (
+    <div
+      role="progressbar"
+      aria-valuemin={done === null ? undefined : 0}
+      aria-valuemax={done === null ? undefined : whole}
+      aria-valuenow={done ?? undefined}
+      aria-valuetext={done === null ? undefined : (valueText ?? text ?? undefined)}
+      data-state={state}
+      {...rest}
+      className={cn("relative w-full overflow-hidden rounded-full bg-line", byDensity(density, "h-1.5", "h-1"), className)}
+    >
+      {done === null ? (
+        // A third of the track sweeping across it. Its resting place (reduced motion, a
+        // screenshot) is the left third, still visibly "in progress".
+        <div className="absolute inset-y-0 left-0 w-1/3 animate-progress-sweep rounded-full bg-signal" />
+      ) : (
+        <div className="h-full rounded-full bg-signal transition-[width] duration-300" style={{ width: `${(done / whole) * 100}%` }} />
+      )}
+    </div>
+  );
+}

package/src/components/ui/SegmentedControl.tsx

@@ -110,9 +110,7 @@ export function SegmentedControl({
               SEGMENT_SIZE_CLASSES[size],
               "font-medium transition-colors",
               "has-focus-visible:outline-2 has-focus-visible:outline-offset-1 has-focus-visible:outline-signal",
-              checked
-                ? "bg-surface text-fg shadow-sm"
-                : "text-fg-muted hover:text-fg",
+              checked ? "bg-surface text-fg shadow-sm" : "text-fg-muted hover:text-fg",
               disabled && "cursor-not-allowed",
             )}
           >

package/src/components/ui/Select.tsx

@@ -119,17 +119,9 @@ export function Select({
           )}
         >
           <RadixSelect.Viewport className="p-1">
-            {unsetLabel !== undefined && (
-              <SelectItem value={UNSET_SENTINEL} label={unsetLabel} muted />
-            )}
+            {unsetLabel !== undefined && <SelectItem value={UNSET_SENTINEL} label={unsetLabel} muted />}
             {options.map((option) => (
-              <SelectItem
-                key={option.value}
-                value={option.value}
-                label={option.label}
-                note={option.note}
-                disabled={option.disabled}
-              />
+              <SelectItem key={option.value} value={option.value} label={option.label} note={option.note} disabled={option.disabled} />
             ))}
           </RadixSelect.Viewport>
         </RadixSelect.Content>

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

@@ -8,14 +8,20 @@
  * 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 { ArrowDown, ArrowUp, ArrowUpDown } from "lucide-react";
-import { type KeyboardEvent, type MouseEvent, type ReactNode, useMemo, useState } from "react";
+import { type KeyboardEvent, type MouseEvent, type ReactNode, useLayoutEffect, useMemo, useRef, useState } from "react";
 
 import { byDensity, useDensity } from "./Density";
-import { cn, focusRing } 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> = {
@@ -55,6 +61,29 @@ export type Column<Row> = {
   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;
 
@@ -72,6 +101,11 @@ const SORT_ICONS = { ascending: ArrowUp, descending: ArrowDown, none: ArrowUpDow
  * `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 `selectionFollowsFocus` each of those moves also activates the row it lands on.
+ * 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,
@@ -87,6 +121,8 @@ export function Table<Row>({
   defaultSort = null,
   onSortChange,
   manualSort = false,
+  windowed,
+  selectionFollowsFocus = false,
 }: {
   /** The columns, in order. */
   columns: Column<Row>[];
@@ -105,11 +141,7 @@ export function Table<Row>({
    * modifiers — a list kept in step with a canvas needs shift-range and meta-toggle to mean
    * 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;
+  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. `index` is the row's
    * position in `rows`, whatever the sort. */
@@ -134,6 +166,21 @@ export function Table<Row>({
    * 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;
+  /**
+   * Activate a row as soon as the keyboard moves to it: each arrow key, Page Up / Page Down,
+   * Home or End that lands on another row also calls `onRowClick` for that row, with the key
+   * press as the event — selection follows focus, as in a list where the selected item shows
+   * its detail beside the list. Clicks, Enter and Space work as without it. Leave it off when
+   * activating a row is costly or navigates away: then a reader can move through the rows and
+   * choose one. Needs `onRowClick`.
+   */
+  selectionFollowsFocus?: boolean | undefined;
 }) {
   const density = useDensity();
   const [ownSort, setOwnSort] = useState<TableSort | null>(defaultSort);
@@ -151,26 +198,113 @@ export function Table<Row>({
     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;
+  // With no rows the scroll area is replaced by the `empty` message: measure the new one when
+  // the rows come back, rather than keep observing the one that went away.
+  const hasRows = rows.length > 0;
+  useLayoutEffect(() => {
+    const scroller = scrollRef.current;
+    if (!isWindowed || !hasRows || !scroller || typeof ResizeObserver === "undefined") return;
+    const measure = () => {
+      // A detached element measures 0, which would shrink the window to a row or two.
+      if (!scroller.isConnected) return;
+      const next = { viewport: scroller.clientHeight, header: headRef.current?.offsetHeight ?? 0 };
+      setMeasured((last) => (last?.viewport === next.viewport && last.header === next.header ? last : next));
+    };
+    measure();
+    // A new scroll area starts at the top, whatever the last one was scrolled to.
+    setScrollTop(scroller.scrollTop);
+    const observer = new ResizeObserver(measure);
+    observer.observe(scroller);
+    return () => observer.disconnect();
+  }, [isWindowed, hasRows]);
+
+  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, activating the new row when
+   * selection follows focus; `true` when the key was one.
+   */
+  const moveFocus = (event: KeyboardEvent<HTMLTableRowElement>, position: number): boolean => {
+    const page = windowed ? Math.floor((viewportHeight - headerHeight) / rowHeight) : 10;
+    const target = navigate(event.key, position, order.length, page);
+    if (target === null) return false;
+    if (selectionFollowsFocus && onRowClick && target !== position) {
+      const index = order[target]!;
+      onRowClick(rows[index]!, index, event);
+    }
+    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);
+    }
+    // A row already in the DOM takes focus now: when nothing scrolled, nothing re-renders, and
+    // the pending focus would wait for a render that never comes.
+    const row = bodyRef.current?.querySelector<HTMLElement>(`tr[data-position="${target}"]`);
+    if (row) {
+      pendingFocus.current = null;
+      row.focus({ preventScroll: windowed !== undefined });
+    }
+    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">
+        <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;
@@ -179,7 +313,13 @@ export function Table<Row>({
                 <th
                   key={column.key}
                   scope="col"
-                  style={column.width ? { width: column.width } : undefined}
+                  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}
@@ -190,6 +330,8 @@ export function Table<Row>({
                     "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)]",
                   )}
                 >
                   {sortable ? (
@@ -213,11 +355,7 @@ export function Table<Row>({
                       {column.header}
                       <SortIcon
                         aria-hidden
-                        className={cn(
-                          "shrink-0",
-                          byDensity(density, "size-3", "size-2.5"),
-                          !direction && "text-fg-subtle",
-                        )}
+                        className={cn("shrink-0", byDensity(density, "size-3", "size-2.5"), !direction && "text-fg-subtle")}
                       />
                     </button>
                   ) : (
@@ -228,16 +366,23 @@ export function Table<Row>({
             })}
           </tr>
         </thead>
-        <tbody>
-          {order.map((index) => {
+        <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(
-                  "border-b border-line/60 last:border-0",
+                  // 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",
                 )}
@@ -256,7 +401,8 @@ export function Table<Row>({
                         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, position)) event.preventDefault();
                       }
                     : undefined
                 }
@@ -270,7 +416,10 @@ export function Table<Row>({
                       "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>
@@ -278,6 +427,7 @@ export function Table<Row>({
               </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,
+      )}
+    />
+  );
+}