@ultimat3/ui 22.15.0 → 24.0.0

package/src/catalog/parse-component.ts

@@ -46,12 +46,64 @@ export function headerComment(source: string): string {
   return lines.join(' ').trim();
 }
 
-/** The members of `export interface <name> { … }`, generics and all. */
-export function parseProps(source: string, interfaceName: string): PropDoc[] {
-  const body = interfaceBody(source, interfaceName);
-  if (body === undefined) return [];
+/**
+ * Every prop a caller may write for `<name>`: the members of `interface <name>`, its bases' first,
+ * or — where `<name>` is `type <name> = A | B`, one interface per mode — the modes merged.
+ */
+export function parseProps(source: string, typeName: string): PropDoc[] {
+  const modes = unionMembers(source, typeName);
+  if (modes === undefined) return interfaceProps(source, typeName);
+  return mergeModes(modes.map((mode) => interfaceProps(source, mode)));
+}
 
-  const props: PropDoc[] = [];
+/** `GridLinkProps<Row>` names the interface `GridLinkProps`. */
+const withoutTypeArguments = (name: string): string => name.replace(/<[^>]*>/, '').trim();
+
+/** `A`, `B` out of `export type <name> = A | B;`. `undefined` when `<name>` is not such an alias. */
+function unionMembers(source: string, typeName: string): string[] | undefined {
+  const alias = new RegExp(`export type ${typeName}(?:<[^>]*>)?\\s*=\\s*([\\w\\s|<>]+);`).exec(
+    source,
+  );
+  return alias?.[1]
+    ?.split('|')
+    .map((member) => withoutTypeArguments(member))
+    .filter((member) => member !== '');
+}
+
+/**
+ * One row per prop across modes. Required only when EVERY mode requires it — a prop one mode
+ * forbids is optional to a reader choosing between them — and typed as each mode types it.
+ */
+function mergeModes(modes: readonly (readonly PropDoc[])[]): PropDoc[] {
+  const merged = new Map<string, PropDoc>();
+  for (const props of modes) {
+    for (const prop of props) {
+      const seen = merged.get(prop.name);
+      if (seen === undefined) {
+        merged.set(prop.name, prop);
+        continue;
+      }
+      merged.set(prop.name, {
+        name: prop.name,
+        type: seen.type === prop.type ? seen.type : `${seen.type} | ${prop.type}`,
+        required: seen.required && prop.required,
+        doc: seen.doc === '' ? prop.doc : seen.doc,
+      });
+    }
+  }
+  return [...merged.values()].map((prop) => ({
+    ...prop,
+    required: prop.required && modes.every((props) => props.some((p) => p.name === prop.name)),
+  }));
+}
+
+/** The members of `interface <name> { … }`, generics and all, after those of every base. */
+function interfaceProps(source: string, interfaceName: string): PropDoc[] {
+  const declared = interfaceDeclaration(source, interfaceName);
+  if (declared === undefined) return [];
+  const { body, bases } = declared;
+
+  const own: PropDoc[] = [];
   let doc: string[] = [];
   let buffer = '';
   let depth = 0;
@@ -68,11 +120,16 @@ export function parseProps(source: string, interfaceName: string): PropDoc[] {
     // A member ends at a `;` that is not inside a function type or an inline object type.
     if (depth > 0 || !buffer.endsWith(';')) continue;
     const prop = toProp(buffer, doc.join(' ').trim());
-    if (prop !== undefined) props.push(prop);
+    if (prop !== undefined) own.push(prop);
     buffer = '';
     doc = [];
   }
-  return props;
+
+  const names = new Set(own.map((prop) => prop.name));
+  const inherited = bases
+    .flatMap((base) => interfaceProps(source, base))
+    .filter((prop) => !names.has(prop.name));
+  return [...inherited, ...own];
 }
 
 function isComment(line: string): boolean {
@@ -105,9 +162,13 @@ function toProp(declaration: string, doc: string): PropDoc | undefined {
   const match = /^(?:readonly\s+)?('[^']+'|"[^"]+"|\w+)(\?)?:\s*([\s\S]+);$/.exec(declaration);
   if (match === null) return undefined;
   const [, rawName = '', optional, rawType = ''] = match;
+  const type = normaliseType(rawType);
+  // `hrefFor?: undefined` is how one mode of a union forbids another mode's prop: a member that
+  // exists so the prop CANNOT be written is not a prop.
+  if (type === '' || type === 'never') return undefined;
   return {
     name: rawName.replace(/^['"]|['"]$/g, ''),
-    type: normaliseType(rawType),
+    type,
     required: optional === undefined,
     doc,
   };
@@ -126,17 +187,29 @@ function normaliseType(type: string): string {
   );
 }
 
-/** Brace-matched so a nested object type does not end the interface early. */
-function interfaceBody(source: string, interfaceName: string): string | undefined {
-  const header = new RegExp(`export interface ${interfaceName}(?:<[^>]*>)?\\s*\\{`).exec(source);
+/**
+ * Brace-matched so a nested object type does not end the interface early. `export` is optional:
+ * a base shared by two modes is a detail of the file, and its members are still the component's.
+ */
+function interfaceDeclaration(
+  source: string,
+  interfaceName: string,
+): { readonly body: string; readonly bases: readonly string[] } | undefined {
+  const header = new RegExp(
+    `(?:export )?interface ${interfaceName}(?:<[^>]*>)?(?:\\s+extends\\s+([\\w\\s,<>]+?))?\\s*\\{`,
+  ).exec(source);
   if (header === null) return undefined;
+  const bases = (header[1] ?? '')
+    .split(',')
+    .map((base) => withoutTypeArguments(base))
+    .filter((base) => base !== '');
   const start = header.index + header[0].length;
   let depth = 1;
   for (let i = start; i < source.length; i += 1) {
     const char = source[i];
     if (char === '{') depth += 1;
     if (char === '}') depth -= 1;
-    if (depth === 0) return source.slice(start, i);
+    if (depth === 0) return { body: source.slice(start, i), bases };
   }
   return undefined;
 }

package/src/catalog/render-catalog.ts

@@ -13,6 +13,7 @@ import {
   lineHeightTokens,
   radiusTokens,
   spaceTokens,
+  strokeTokens,
   zTokens,
 } from '../tokens/tokens';
 import type { ComponentDoc } from './parse-component';
@@ -99,6 +100,8 @@ ${scaleTable('Space — `--space-*`', spaceTokens)}
 
 ${scaleTable('Radius — `--radius-*`', radiusTokens)}
 
+${scaleTable('Stroke — `--stroke-*`', strokeTokens)}
+
 ${scaleTable('Font size — `--text-*`', fontSizeTokens)}
 
 ${scaleTable('Font weight — `--weight-*`', fontWeightTokens)}
@@ -111,6 +114,23 @@ ${scaleTable('Easing — `--easing-*`', easingTokens)}
 
 ${scaleTable('Z-index — `--z-*`', zTokens)}
 
-${scaleTable('Breakpoints — `@include t.respond-to(<name>)`', breakpointTokens)}
+${scaleTable('Breakpoints — `respond-to` · `respond-down` · `respond-between`', breakpointTokens)}
+
+\`@include t.respond-to(md)\` is \`md\` and wider, \`t.respond-down(md)\` is narrower than \`md\`, and
+\`t.respond-between(md, lg)\` is \`md\` up to \`lg\`. A max-width arm stops 0.02px under its rung, so
+no width matches two of them.
+
+### Computed lengths
+
+${table(
+  ['Function', 'Answers'],
+  [
+    ['`t.rem(24px)`', '`1.5rem` — px, rem or a unitless px count in, rem out'],
+    [
+      '`t.fluid(1rem, 2rem, 20rem, 80rem)`',
+      'one `clamp()`: the first size at a 20rem viewport, the second at 80rem, linear between',
+    ],
+  ],
+)}
 `;
 }

package/src/components/Avatar.module.scss

@@ -47,7 +47,7 @@
     inset-inline-end: 0;
     inline-size: 28%;
     block-size: 28%;
-    border: 2px solid t.role('surface');
+    border: t.stroke(thick) solid t.role('surface');
     border-radius: t.radius(full);
     content: '';
   }

package/src/components/BarChart.module.scss

@@ -26,6 +26,17 @@
   }
 }
 
+// The second series — what went wrong, stacked on what went right.
+.secondary {
+  fill: t.role('danger');
+  opacity: 0.6;
+  transition: opacity t.duration(fast) t.easing(out);
+
+  &:hover {
+    opacity: 1;
+  }
+}
+
 .last {
   opacity: 1;
 }
@@ -36,7 +47,7 @@
   // SVG text scales with the chart: below `sm` these shrink to unreadable specks, and an
   // unreadable label is noise. Every bar still carries its `<title>`.
   display: none;
-  font-size: 8px;
+  font-size: t.rem(8px);
   fill: t.role('fg-muted');
 
   @include t.respond-to(sm) {

package/src/components/BarChart.tsx

@@ -1,4 +1,5 @@
-// A bar chart of one series — clicks per day, signups per week — as static SVG. No charting
+// A bar chart of one series — clicks per day, signups per week — or two stacked (done, and failed
+// on top), as static SVG. No charting
 // library: the framework's own docs use a sparkline pulling one in as the cautionary example, and
 // a route's JS budget counts raw minified bytes. `<rect>` bars cost nothing to hydrate, so the
 // server-rendered shell IS the chart. Geometry lives in `bar-chart-view.ts`.
@@ -7,7 +8,7 @@ import type { JSX } from 'solid-js';
 import { cx } from '../cx';
 import styles from './BarChart.module.scss';
 import type { ChartPoint } from './bar-chart-view';
-import { BAR_CHART, barRects, GRID_STEPS, gridY, maxOf } from './bar-chart-view';
+import { BAR_CHART, barRects, GRID_STEPS, gridY, maxOf, secondaryRects } from './bar-chart-view';
 
 export interface BarChartProps {
   /** The accessible name for the whole chart, already translated. */
@@ -16,11 +17,19 @@ export interface BarChartProps {
   points: readonly ChartPoint[];
   /** Draw the last bar at full strength — the eye lands where the live number is. Default on. */
   highlightLast?: boolean | undefined;
+  /**
+   * Names of the two series, already translated, read by each rect's `<title>`. Give them when a
+   * point carries `secondary`: a stacked bar with no name for its top is two numbers and no key.
+   */
+  seriesLabels?: { readonly primary: string; readonly secondary: string } | undefined;
   class?: string | undefined;
 }
 
 export function BarChart(props: BarChartProps): JSX.Element {
   const rects = (): readonly ReturnType<typeof barRects>[number][] => barRects(props.points);
+  const tops = (): ReturnType<typeof secondaryRects> => secondaryRects(props.points);
+  const named = (label: string | undefined, value: number): string =>
+    label === undefined ? String(value) : `${label} ${value}`;
   const lastIndex = (): number => props.points.length - 1;
   const first = (): ChartPoint | undefined => props.points[0];
   const last = (): ChartPoint | undefined => props.points.at(-1);
@@ -44,20 +53,37 @@ export function BarChart(props: BarChartProps): JSX.Element {
       {props.points.map((point, index) => {
         const rect = rects()[index];
         if (rect === undefined) return null;
+        const top = tops()[index] ?? null;
         return (
-          <rect
-            class={cx(styles['bar'], highlight() && index === lastIndex() && styles['last'])}
-            x={rect.x}
-            y={rect.y}
-            width={rect.width}
-            height={rect.height}
-            rx={2}
-            data-bar="true"
-          >
-            <title>
-              {point.key}: {point.value}
-            </title>
-          </rect>
+          <g>
+            <rect
+              class={cx(styles['bar'], highlight() && index === lastIndex() && styles['last'])}
+              x={rect.x}
+              y={rect.y}
+              width={rect.width}
+              height={rect.height}
+              rx={2}
+              data-bar="true"
+            >
+              <title>{`${point.key}: ${named(props.seriesLabels?.primary, point.value)}`}</title>
+            </rect>
+            {top === null ? null : (
+              <rect
+                class={cx(
+                  styles['secondary'],
+                  highlight() && index === lastIndex() && styles['last'],
+                )}
+                x={top.x}
+                y={top.y}
+                width={top.width}
+                height={top.height}
+                rx={2}
+                data-series="secondary"
+              >
+                <title>{`${point.key}: ${named(props.seriesLabels?.secondary, point.secondary ?? 0)}`}</title>
+              </rect>
+            )}
+          </g>
         );
       })}
       <text class={styles['axis']} x={BAR_CHART.width} y={BAR_CHART.top - 3} text-anchor="end">

package/src/components/Button.tsx

@@ -14,6 +14,7 @@ import type { JSX } from 'solid-js';
 import { ariaBool } from '../a11y';
 import { cx } from '../cx';
 import styles from './Button.module.scss';
+import { buttonClassKeys } from './button-classes';
 import { Spinner } from './Spinner';
 import type { ButtonVariant, Size, Tone } from './variants';
 
@@ -66,14 +67,8 @@ export function Button(props: ButtonProps): JSX.Element {
     <button
       id={props.id}
       type={props.type ?? 'button'}
-      class={cx(
-        styles['button'],
-        styles[`variant-${props.variant ?? 'primary'}`],
-        styles[`tone-${props.tone ?? 'accent'}`],
-        styles[`size-${props.size ?? 'md'}`],
-        props.fullWidth === true && styles['full'],
-        props.class,
-      )}
+      // The keys are `button-classes.ts`'s: `<Link appearance="button">` asks the same function.
+      class={cx(...buttonClassKeys(props).map((key) => styles[key]), props.class)}
       // Only the caller's explicit `disabled` reaches the attribute. `loading` is a state the user
       // is meant to read and wait out, not a control taken away from under them.
       disabled={props.disabled === true ? true : undefined}

package/src/components/Card.module.scss

@@ -17,7 +17,7 @@
 
   &:hover {
     border-color: t.role('accent', 0.4);
-    transform: translateY(-2px);
+    transform: translateY(t.rem(-2px));
     box-shadow: t.shadow(md);
   }
 

package/src/components/Checkbox.module.scss

@@ -34,8 +34,8 @@
     inset-block-start: 0.1rem;
     inline-size: 0.3rem;
     block-size: 0.55rem;
-    border-inline-end: 2px solid t.role('accent-fg');
-    border-block-end: 2px solid t.role('accent-fg');
+    border-inline-end: t.stroke(thick) solid t.role('accent-fg');
+    border-block-end: t.stroke(thick) solid t.role('accent-fg');
     transform: rotate(40deg) scale(0);
     transform-origin: center;
     content: '';
@@ -66,8 +66,8 @@
 }
 
 .input:focus-visible + .box {
-  outline: 2px solid t.role('accent');
-  outline-offset: 2px;
+  outline: t.stroke(thick) solid t.role('accent');
+  outline-offset: t.stroke(thick);
 }
 
 .input[aria-invalid='true'] + .box {

package/src/components/Checkbox.tsx

@@ -12,6 +12,11 @@ export interface CheckboxProps {
   id?: string | undefined;
   name?: string | undefined;
   value?: string | undefined;
+  /**
+   * The id of the `<form>` this box submits with, when it cannot sit inside it — a row checkbox in
+   * a table whose page already holds another form. The platform's own association, no script.
+   */
+  form?: string | undefined;
   checked?: boolean | undefined;
   /** Tri-state for "some children selected". The ONLY thing mirrored to `aria-checked`. */
   indeterminate?: boolean | undefined;
@@ -33,6 +38,7 @@ export function Checkbox(props: CheckboxProps): JSX.Element {
         id={props.id}
         name={props.name}
         value={props.value}
+        form={props.form}
         checked={props.checked === true}
         disabled={props.disabled === true}
         required={props.required === true}

package/src/components/CommandPalette.module.scss

@@ -3,10 +3,14 @@
 .palette {
   position: fixed;
   inset-block-start: 12vh;
-  inset-inline-start: 50%;
+  // Centred by auto margins between two zero insets, never by a 50% inset and a -50% translate:
+  // the inset is logical and the translate physical, so under `dir="rtl"` that pair puts the
+  // palette a whole width off-centre (`rtl-sheets.test.ts`).
+  inset-inline: 0;
   inline-size: min(32rem, calc(100vw - #{t.space(8)}));
   max-block-size: 60vh;
-  margin: 0;
+  margin-block: 0;
+  margin-inline: auto;
   padding: 0;
   border: 1px solid t.role('line');
   border-radius: t.radius(lg);
@@ -20,8 +24,7 @@
   overflow: hidden;
   z-index: t.z(dialog);
 
-  // Transform-only translate keeps the 50% inline offset from fighting `margin-inline`.
-  transform: translateX(-50%) translateY(-4px) scale(0.98);
+  transform: translateY(calc(-1 * #{t.space(1)})) scale(0.98);
   opacity: 0;
   visibility: hidden;
   transition:
@@ -30,7 +33,7 @@
     visibility t.duration(fast) t.easing(out);
 
   &[open] {
-    transform: translateX(-50%) translateY(0) scale(1);
+    transform: translateY(0) scale(1);
     opacity: 1;
     visibility: visible;
     transition-duration: t.duration(base);

package/src/components/DataTable.module.scss

@@ -20,6 +20,8 @@
   border-radius: t.radius(sm);
   color: inherit;
   font: inherit;
+  // The link mode renders this class on an anchor: a sort header reads as a header, not a link.
+  text-decoration: none;
   cursor: pointer;
 
   &:hover {

package/src/components/DataTable.tsx

@@ -33,13 +33,12 @@ export interface Column<Row> {
   width?: string | undefined;
 }
 
-export interface DataTableProps<Row> {
+interface DataTableBaseProps<Row> {
   caption: string;
   columns: readonly Column<Row>[];
   rows: readonly Row[];
   rowKey: (row: Row) => string;
   sort?: SortState | undefined;
-  onSortChange?: (sort: SortState | undefined) => void;
   loading?: boolean | undefined;
   /** An UltimateError (or anything shaped like one) from the query. */
   error?: unknown | undefined;
@@ -49,7 +48,6 @@ export interface DataTableProps<Row> {
   /** Opaque cursors from the query result; absent means no further page. */
   nextCursor?: string | undefined;
   prevCursor?: string | undefined;
-  onCursor?: ((cursor: string, direction: 'next' | 'prev') => void) | undefined;
   stickyHeader?: boolean | undefined;
   density?: 'comfortable' | 'compact' | undefined;
   /** Placeholder row count while loading. Match the usual page size. */
@@ -57,6 +55,31 @@ export interface DataTableProps<Row> {
   class?: string | undefined;
 }
 
+/** The pager and the sort headers call back: the table sits in an island. */
+export interface DataTableCallbackProps<Row> extends DataTableBaseProps<Row> {
+  /** Callback paging. Never beside `hrefFor` — the type refuses the pair. */
+  onCursor?: ((cursor: string, direction: 'next' | 'prev') => void) | undefined;
+  /** Callback sorting. Never beside `sortHrefFor` — the type refuses the pair. */
+  onSortChange?: ((sort: SortState | undefined) => void) | undefined;
+  hrefFor?: undefined;
+  sortHrefFor?: undefined;
+}
+
+/** The pager and the sort headers are anchors: a server-rendered table needs no script. */
+export interface DataTableLinkProps<Row> extends DataTableBaseProps<Row> {
+  /** Link paging: the URL of the page a cursor names, handed to `<Pagination hrefFor>`. */
+  hrefFor: (cursor: string, direction: 'next' | 'prev') => string;
+  /**
+   * Link sorting: the URL of the list under the NEXT sort state of a header's cycle (`undefined`
+   * is "unsorted"). Absent, a sortable header is plain text — never a button with no handler.
+   */
+  sortHrefFor?: ((sort: SortState | undefined) => string) | undefined;
+  onCursor?: undefined;
+  onSortChange?: undefined;
+}
+
+export type DataTableProps<Row> = DataTableCallbackProps<Row> | DataTableLinkProps<Row>;
+
 export function DataTable<Row>(props: DataTableProps<Row>): JSX.Element {
   const ui = useUi();
 
@@ -114,76 +137,117 @@ export function DataTable<Row>(props: DataTableProps<Row>): JSX.Element {
     ));
   };
 
-  const decided = branch();
-  if (decided.kind === 'failed') {
-    return <ErrorState error={decided.error} onRetry={props.onRetry} class={props.class} />;
-  }
+  /** One mode per use, exactly as `Pagination` declares it — the table only hands it through. */
+  const pager = (): JSX.Element =>
+    props.hrefFor === undefined ? (
+      <Pagination
+        nextCursor={props.nextCursor}
+        prevCursor={props.prevCursor}
+        onCursor={props.onCursor}
+      />
+    ) : (
+      <Pagination
+        nextCursor={props.nextCursor}
+        prevCursor={props.prevCursor}
+        hrefFor={props.hrefFor}
+      />
+    );
+
+  const indicator = (key: string): JSX.Element => (
+    <span aria-hidden="true" class={styles['indicator']}>
+      {ariaSortFor(props.sort, key) === 'ascending'
+        ? '▲'
+        : ariaSortFor(props.sort, key) === 'descending'
+          ? '▼'
+          : '↕'}
+    </span>
+  );
 
-  // Unreachable while pending, by the shape of `AsyncBranch` rather than by the order of two ifs:
-  // "No results" under a first page in flight is the bug that ordering used to be all that stopped.
-  if (decided.kind === 'empty') {
+  /**
+   * One mode per table, as the pager has: an anchor at the next state's URL when the table is
+   * linked, a button that calls back when it is not. A linked table with no `sortHrefFor` gets the
+   * header text alone — a `<button>` on a page that never hydrates is a control that does nothing.
+   */
+  const sortControl = (column: Column<Row>): JSX.Element => {
+    if (column.sortable !== true) return column.header;
+    const label = `${column.header}: ${sortLabel(column.key)}`;
+    if (props.hrefFor !== undefined) {
+      const sortHrefFor = props.sortHrefFor;
+      if (sortHrefFor === undefined) return column.header;
+      return (
+        <a
+          class={styles['sortButton']}
+          aria-label={label}
+          href={sortHrefFor(nextSortState(props.sort, column.key))}
+        >
+          {column.header}
+          {indicator(column.key)}
+        </a>
+      );
+    }
+    const onSortChange = props.onSortChange;
     return (
-      <EmptyState
-        title={props.emptyTitle}
-        description={props.emptyDescription}
-        class={props.class}
-      />
+      <button
+        type="button"
+        class={styles['sortButton']}
+        aria-label={label}
+        onClick={() => onSortChange?.(nextSortState(props.sort, column.key))}
+      >
+        {column.header}
+        {indicator(column.key)}
+      </button>
     );
-  }
-
-  return (
-    <div class={cx(styles['wrap'], props.class)}>
-      <Table
-        caption={props.caption}
-        stickyHeader={props.stickyHeader !== false}
-        density={props.density ?? 'comfortable'}
+  };
+
+  // An array, not a fragment: this package's `.tsx` compiles to two factories (Solid's and render's
+  // `h`), and only an array means the same sibling list to both.
+  const table = (decided: AsyncBranch<readonly Row[]>): JSX.Element => [
+    <Table
+      caption={props.caption}
+      stickyHeader={props.stickyHeader !== false}
+      density={props.density ?? 'comfortable'}
+    >
+      <thead>
+        <tr>
+          {props.columns.map((column) => (
+            <th
+              scope="col"
+              style={column.width === undefined ? undefined : { 'inline-size': column.width }}
+              aria-sort={ariaSortFor(props.sort, column.key)}
+              class={column.numeric === true ? styles['numeric'] : undefined}
+            >
+              {sortControl(column)}
+            </th>
+          ))}
+        </tr>
+      </thead>
+      <tbody
+        class={decided.kind === 'ready' && decided.busy ? styles['stale'] : undefined}
+        aria-busy={ariaBool(isBusyBranch(decided))}
       >
-        <thead>
-          <tr>
-            {props.columns.map((column) => (
-              <th
-                scope="col"
-                style={column.width === undefined ? undefined : { 'inline-size': column.width }}
-                aria-sort={ariaSortFor(props.sort, column.key)}
-                class={column.numeric === true ? styles['numeric'] : undefined}
-              >
-                {column.sortable === true ? (
-                  <button
-                    type="button"
-                    class={styles['sortButton']}
-                    aria-label={`${column.header}: ${sortLabel(column.key)}`}
-                    onClick={() => props.onSortChange?.(nextSortState(props.sort, column.key))}
-                  >
-                    {column.header}
-                    <span aria-hidden="true" class={styles['indicator']}>
-                      {ariaSortFor(props.sort, column.key) === 'ascending'
-                        ? '▲'
-                        : ariaSortFor(props.sort, column.key) === 'descending'
-                          ? '▼'
-                          : '↕'}
-                    </span>
-                  </button>
-                ) : (
-                  column.header
-                )}
-              </th>
-            ))}
-          </tr>
-        </thead>
-        <tbody
-          class={decided.kind === 'ready' && decided.busy ? styles['stale'] : undefined}
-          aria-busy={ariaBool(isBusyBranch(decided))}
-        >
-          {body()}
-        </tbody>
-      </Table>
-      {props.nextCursor === undefined && props.prevCursor === undefined ? null : (
-        <Pagination
-          nextCursor={props.nextCursor}
-          prevCursor={props.prevCursor}
-          onCursor={props.onCursor}
-        />
-      )}
-    </div>
-  );
+        {body()}
+      </tbody>
+    </Table>,
+    props.nextCursor === undefined && props.prevCursor === undefined ? null : pager(),
+  ];
+
+  /**
+   * The branch is decided INSIDE the returned JSX, as `AsyncRegion` does: a component body runs
+   * once, so a decision taken there is the decision for the island's whole life — a table that
+   * first rendered its error state kept it after the query recovered.
+   */
+  const content = (): JSX.Element => {
+    const decided = branch();
+    if (decided.kind === 'failed') {
+      return <ErrorState error={decided.error} onRetry={props.onRetry} />;
+    }
+    // Unreachable while pending, by the shape of `AsyncBranch` rather than by the order of two
+    // ifs: "No results" under a first page in flight is the bug that ordering used to stop.
+    if (decided.kind === 'empty') {
+      return <EmptyState title={props.emptyTitle} description={props.emptyDescription} />;
+    }
+    return table(decided);
+  };
+
+  return <div class={cx(styles['wrap'], props.class)}>{content()}</div>;
 }