@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/table-of-contents.usage.gts

@@ -0,0 +1,270 @@
+// Pretui — TableOfContents usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { TableOfContents } from './table-of-contents';
+import type { TocItem } from './table-of-contents';
+import { Token } from './token';
+
+// ── TableOfContents ← docs-site scroll-spy TOCs ──────────────────────────
+// The example needs a real scrolling document for the observer to spy on,
+// so the page ships one: the sourcing manual, in its own scroll pane beside
+// the TOC. The component auto-roots its IntersectionObserver on the nearest
+// scrollable ancestor of the first heading, which is exactly that pane — no
+// wiring from the caller.
+const MANUAL: TocItem[] = [
+  { id: 'sm-season', label: 'Before the season', level: 1 },
+  { id: 'sm-booking', label: 'Booking a lot', level: 1 },
+  { id: 'sm-deposit', label: 'Deposits', level: 2 },
+  { id: 'sm-window', label: 'The pick window', level: 2 },
+  { id: 'sm-cupping', label: 'Cupping', level: 1 },
+  { id: 'sm-scoring', label: 'Scoring', level: 2 },
+  { id: 'sm-customs', label: 'Shipping and customs', level: 1 },
+  { id: 'sm-storage', label: 'Storage', level: 1 },
+];
+
+class TableOfContentsUsage extends Component {
+  items = MANUAL;
+
+  @tracked label = 'On this page';
+  @tracked spy = true;
+  @tracked band: number | null = 38;
+  @tracked activeLabel = 'Before the season';
+
+  setLabel = (v: string) => (this.label = v);
+  setSpy = (v: boolean) => (this.spy = v);
+  setBand = (v: number | null) => (this.band = v);
+  onActiveChange = (id: string) => {
+    this.activeLabel = MANUAL.find((i) => i.id === id)?.label ?? id;
+  };
+
+  get bandVal() {
+    return this.band ?? undefined;
+  }
+  get usage() {
+    let bits = ['@items={{this.items}}', `@label='${this.label}'`];
+    if (!this.spy) bits.push('@spy={{false}}');
+    if (this.band !== null && this.band !== 38) {
+      bits.push(`@band={{${this.band}}}`);
+    }
+    bits.push('@onActiveChange={{this.onActiveChange}}');
+    return `<TableOfContents\n  ${bits.join('\n  ')}\n/>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='TableOfContents'
+      @description="Document navigation that knows where the reader is. It renders a nav landmark around an ordered list of anchors, marks the current section with aria-current='location', and moves a single travelling bar down the rail as you scroll — the marker is a sibling of the list carrying aria-hidden, so assistive tech reads eight links and no chrome. Section tracking is ONE IntersectionObserver created inside a modifier and disconnected on cleanup: no scroll handler, no re-measure per frame, no timer. It auto-roots on the nearest scrollable ancestor of the first heading, so a TOC beside a scrolling panel (like the manual on the right) works with no wiring. Scroll the manual to watch the marker travel; @band sets how far down the pane a heading must reach before it counts as current. Honest limits: no collapsible sub-lists (levels indent instead — an accordion in a TOC hides the thing the reader came for), and activation does not scroll for you; the anchor's href does whatever the caller's scroll-behavior says."
+      @source={{this.usage}}
+    >
+      <:example>
+        {{! the query container must be an ANCESTOR of the rule's subject —
+            an unnamed @container can never match the container element
+            itself, so .toc-layout gets a wrapper rather than the type }}
+        <div class='toc-wrap'>
+          <div class='toc-layout'>
+            <TableOfContents
+              class='toc-side'
+              @items={{this.items}}
+              @label={{this.label}}
+              @spy={{this.spy}}
+              @band={{this.bandVal}}
+              @onActiveChange={{this.onActiveChange}}
+            />
+            <div class='toc-doc'>
+              <section id='sm-season'>
+                <h3 class='toc-h'>Before the season</h3>
+                <p class='toc-p'>Every spring the desk re-reads last year's
+                  scorecards before a single call is placed. Wuyi Origins and Uji
+                  Valley Growers carry standing bookings; everyone else is quoted
+                  fresh against the current sheet.</p>
+                <p class='toc-p'>The manual exists because the same four mistakes
+                  repeat: a deposit sent before the pick window is confirmed, a
+                  cupping filed against the wrong lot id, a container booked
+                  without the phytosanitary paperwork, and a crate stored above
+                  the humidity ceiling.</p>
+              </section>
+              <section id='sm-booking'>
+                <h3 class='toc-h'>Booking a lot</h3>
+                <p class='toc-p'>A booking is a promise about a harvest that has
+                  not happened yet. Name the estate, the cultivar, the target
+                  weight and the pick window, and nothing else.</p>
+              </section>
+              <section id='sm-deposit'>
+                <h4 class='toc-h toc-h-sub'>Deposits</h4>
+                <p class='toc-p'>Thirty percent on signature, the balance against
+                  the bill of lading. Never send a deposit against an unconfirmed
+                  window — Fujian Maritime Tea will hold it, but Darjeeling First
+                  Flush Ltd. will not.</p>
+              </section>
+              <section id='sm-window'>
+                <h4 class='toc-h toc-h-sub'>The pick window</h4>
+                <p class='toc-p'>Two weeks either side of the estate's own
+                  estimate. Alishan Cloud Farms quotes narrow and hits it; Kericho
+                  Leaf Union quotes wide and drifts late.</p>
+              </section>
+              <section id='sm-cupping'>
+                <h3 class='toc-h'>Cupping</h3>
+                <p class='toc-p'>Every arriving lot is cupped blind against the
+                  sample that sold it. Three cups, one taster, notes filed the
+                  same day against the lot id and nothing else.</p>
+              </section>
+              <section id='sm-scoring'>
+                <h4 class='toc-h toc-h-sub'>Scoring</h4>
+                <p class='toc-p'>A hundred-point sheet, but only the band matters:
+                  above ninety it goes to the ceremonial menu, eighty to ninety to
+                  the house blend, below eighty back to the supplier with the
+                  cups photographed.</p>
+              </section>
+              <section id='sm-customs'>
+                <h3 class='toc-h'>Shipping and customs</h3>
+                <p class='toc-p'>Sea freight from Fuzhou, air only for first
+                  flush. The paperwork travels ahead of the container, never with
+                  it, and the customs broker gets the cupping certificate before
+                  the vessel sails.</p>
+              </section>
+              <section id='sm-storage'>
+                <h3 class='toc-h'>Storage</h3>
+                <p class='toc-p'>Sixty percent relative humidity, no light, no
+                  neighbours with a smell. Pu-erh is the exception and lives in
+                  its own room, which is the only reason the humidity logs are
+                  audited monthly.</p>
+                <p class='toc-p'>Anything that fails an audit is re-cupped before
+                  it is re-priced, not after.</p>
+              </section>
+            </div>
+          </div>
+        </div>
+        <p class='sd-readout'>
+          Current section:
+          <Token @value={{this.activeLabel}} />
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='items'
+          @required={{true}}
+          @value={{this.items}}
+          @description='Sections in document order. Each TocItem is { id, label, level? } where id is the target element’s DOM id — it becomes the link’s href fragment and the observer’s target.'
+        />
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @defaultValue='On this page'
+          @description='Accessible name for the nav landmark.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.Bool
+          @name='spy'
+          @value={{this.spy}}
+          @defaultValue={{true}}
+          @description='Watch the document and follow the reader’s scroll. Defaults to @links: on for fragment links, off for buttons, whose ids need not be DOM ids. Turn it off to drive the active section entirely from @activeId.'
+          @onInput={{this.setSpy}}
+        />
+        <Args.Number
+          @name='band'
+          @value={{this.band}}
+          @min={{5}}
+          @max={{90}}
+          @step={{1}}
+          @defaultValue={{38}}
+          @description='How far down the scroll pane, as a percentage, a heading must reach before it becomes current. Low values make the TOC eager; high values make it lag behind the reader.'
+          @onInput={{this.setBand}}
+        />
+        <Args.String
+          @name='activeId'
+          @description='Controlled active id. Pass it and the component stops owning the active state — the observer still reports through @onActiveChange.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='defaultActiveId'
+          @description='Initial active id when uncontrolled. Defaults to the first item.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onActiveChange'
+          @description='Fires with the id whenever the active section changes, from a click or from the observer.'
+          @hideControls={{true}}
+        />
+        <Args.Bool
+          @name='links'
+          @defaultValue={{true}}
+          @description='Rows are fragment links (a href="#id"). False renders them as button type=button with no href, and the component does no scrolling: a caller whose sections sit in its own scroll panel scrolls from the @onSelect event’s currentTarget. @spy then defaults off.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onSelect'
+          @description='Fires with (id, event) when a row is clicked, in either mode. It only reports: passing it never changes what renders, so link-mode rows keep their hrefs.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name=':item'
+          @description='Replaces the row text. Receives (item, active, index) so a caller can render a count, an icon, a progress dot, or a step number beside the label.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .toc-wrap {
+        container-type: inline-size;
+        min-width: 0;
+      }
+      .toc-layout {
+        display: grid;
+        grid-template-columns: 13rem 1fr;
+        gap: var(--boxel-sp);
+        align-items: start;
+        min-width: 0;
+      }
+      .toc-side {
+        position: sticky;
+        top: 0;
+      }
+      .toc-doc {
+        max-height: 19rem;
+        overflow-y: auto;
+        padding: var(--boxel-sp-sm) var(--boxel-sp);
+        border-radius: var(--boxel-border-radius);
+        background-color: var(--card);
+        color: var(--card-foreground);
+        box-shadow: 0 0 0 1px var(--border);
+        min-width: 0;
+      }
+      .toc-h {
+        margin: var(--boxel-sp) 0 var(--boxel-sp-3xs);
+        font-size: var(--boxel-font-size-sm);
+        font-weight: 600;
+      }
+      .toc-h-sub {
+        font-size: var(--boxel-font-size-xs);
+        color: var(--muted-foreground);
+      }
+      .toc-doc section:first-child .toc-h {
+        margin-top: 0;
+      }
+      .toc-p {
+        margin: 0 0 var(--boxel-sp-2xs);
+        font-size: var(--boxel-font-size-xs);
+        line-height: 1.55;
+        color: var(--muted-foreground);
+        max-width: 56ch;
+      }
+      .sd-readout {
+        margin: var(--boxel-sp-xs) 0 0;
+        font-size: var(--boxel-font-size-2xs);
+        color: var(--muted-foreground);
+      }
+      /* unnamed container query only — the named forms silently delete every
+         following rule in the transpiled stylesheet */
+      @container (max-width: 34rem) {
+        .toc-layout {
+          grid-template-columns: 1fr;
+        }
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TABLE_OF_CONTENTS: Record<string, unknown> = {
+  TableOfContents: TableOfContentsUsage,
+};

package/bundled-realms/pretui/components/table.gts

@@ -0,0 +1,158 @@
+// Pretui — Table: the DataGrid shell as a yieldable primitive for custom tables.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { eq } from '@cardstack/boxel-ui/helpers';
+
+// Table — the DataGrid shell as a yieldable primitive (added for the
+// freestyle dogfood pass: composite tables that need custom cell content —
+// like the Component API table — wear the same cloth as DataGrid without its
+// data-driven machinery). Yielded rows/cells are styled via :deep().
+export interface TableSignature {
+  Args: {
+    /** the table's accessible name, rendered as a real `<caption>` */
+    caption?: string;
+    /** accessible name when no name is on screen; lands as `aria-label` on
+     * the `<table>` and is dropped when a caption or `@labelledBy` names it */
+    label?: string;
+    /** id of an on-screen element (a heading) that names the table; lands as
+     * `aria-labelledby` on the `<table>` and is dropped when a caption renders */
+    labelledBy?: string;
+    /** false drops the table's own radius and hairline, for a table seated
+     * inside a panel that already draws them (default true) */
+    framed?: boolean;
+  };
+  Blocks: { caption: []; head: []; body: [] };
+  Element: HTMLDivElement;
+}
+
+// The <:caption> block wins over @caption, the way a block wins over its arg
+// on Notification, AlertDialog and Card. A caption is the table's name, so
+// @labelledBy and @label only land when neither renders, and @labelledBy wins
+// over @label, as aria-labelledby does over aria-label.
+export const Table: TemplateOnlyComponent<TableSignature> = <template>
+  <div
+    class='pretui-tablewrap'
+    data-framed={{if (eq @framed false) 'false'}}
+    data-test-pretui-table
+    ...attributes
+  >
+    <table
+      class='pretui-table'
+      aria-labelledby={{if
+        (has-block 'caption')
+        null
+        (if @caption null @labelledBy)
+      }}
+      aria-label={{if
+        (has-block 'caption')
+        null
+        (if @caption null (if @labelledBy null @label))
+      }}
+    >
+      {{#if (has-block 'caption')}}
+        <caption class='pretui-table-caption'>{{yield to='caption'}}</caption>
+      {{else if @caption}}
+        <caption class='pretui-table-caption'>{{@caption}}</caption>
+      {{/if}}
+      <thead>{{yield to='head'}}</thead>
+      <tbody>{{yield to='body'}}</tbody>
+    </table>
+  </div>
+  <style scoped>
+    @layer PretComponent {
+      /* overflow: auto makes the wrapper the scroll container of the sticky
+         header, so the header only sticks once the wrapper itself scrolls
+         vertically. A caller bounds it with --pretui-table-max-height; unset,
+         the wrapper grows with its rows and the header scrolls away with them. */
+      .pretui-tablewrap {
+        --pretui-table-head-height: 1.875rem;
+
+        overflow: auto;
+        /* a focused cell scrolls clear of the sticky header */
+        scroll-padding-block-start: var(--pretui-table-head-height);
+        min-width: 0;
+        max-width: 100%;
+        max-height: var(--pretui-table-max-height, none);
+        border-radius: var(--boxel-border-radius);
+        box-shadow: 0 0 0 1px var(--border);
+        background-color: var(--card);
+        color: var(--card-foreground);
+      }
+      .pretui-tablewrap[data-framed='false'] {
+        border-radius: 0;
+        box-shadow: none;
+      }
+      .pretui-table {
+        width: 100%;
+        border-collapse: collapse;
+        font-size: var(--boxel-font-size-xs);
+      }
+      .pretui-table-caption {
+        padding: var(--boxel-sp-2xs) var(--boxel-sp-xs);
+        text-align: start;
+        color: var(--muted-foreground);
+        font-size: var(--boxel-caption-font-size);
+        font-weight: var(--boxel-caption-font-weight);
+        line-height: var(--boxel-caption-line-height);
+        letter-spacing: var(--boxel-caption-letter-spacing);
+      }
+      /* The header voice is inherited from thead, so it reaches the column
+         headers and never a row header th in the body. */
+      .pretui-table thead {
+        font-family: var(--font-mono);
+        font-size: var(--boxel-ui-label-font-size);
+        letter-spacing: var(--boxel-ui-label-letter-spacing);
+        text-transform: uppercase;
+        white-space: nowrap;
+      }
+      /* cells wrap, so the body line height clears the 1.4 floor */
+      .pretui-table tbody {
+        vertical-align: top;
+        line-height: var(--boxel-line-height-md);
+      }
+      /* :deep() only for what the browser's th rule overrides and for what
+         doesn't inherit. */
+      .pretui-table :deep(thead th) {
+        position: sticky;
+        top: 0;
+        z-index: 2;
+        height: var(--pretui-table-head-height);
+        padding: 0 var(--boxel-sp-xs);
+        text-align: start;
+        font-weight: var(--boxel-ui-label-font-weight);
+        background-color: var(--inset);
+        color: var(--foreground);
+        box-shadow: inset 0 -1px 0 var(--border-strong);
+      }
+      .pretui-table :deep(td),
+      .pretui-table :deep(tbody th) {
+        padding: var(--boxel-sp-2xs) var(--boxel-sp-xs);
+        box-shadow: inset 0 -1px 0 var(--border);
+      }
+      /* the frame (Table's own ring, or the panel a frameless table sits in)
+         already draws the bottom edge */
+      .pretui-table :deep(tbody tr:last-child td),
+      .pretui-table :deep(tbody tr:last-child th) {
+        box-shadow: none;
+      }
+      /* Kept off td: at this specificity it would beat a layered caller's
+         own cell alignment, such as a right-aligned number column. */
+      .pretui-table :deep(tbody th) {
+        text-align: start;
+      }
+      /* on the cells, so a caller that repaints a cell replaces the stripe
+         or hover instead of stacking a second one over the row's */
+      .pretui-table :deep(tbody tr:nth-child(even) td),
+      .pretui-table :deep(tbody tr:nth-child(even) th) {
+        background-color: var(--stripe);
+        color: var(--foreground);
+      }
+      @media (hover: hover) {
+        .pretui-table :deep(tbody tr:hover td),
+        .pretui-table :deep(tbody tr:hover th) {
+          background-color: var(--hover);
+          color: var(--foreground);
+        }
+      }
+    }
+  </style>
+</template>;

package/bundled-realms/pretui/components/table.md

@@ -0,0 +1,80 @@
+## What it is
+
+**DataGrid's shell without its engine.** You write the `<tr>`/`<th>`/`<td>` markup; the component supplies the surface, an optional `<caption>`, the mono header band over the column headers (sticky inside a height-bounded wrapper, see below), zebra striping, hover, the scroll container and the rounded hairline edge. Reach for it when the cells need arbitrary content and there is no uniform row shape to declare — a component API reference, a comparison matrix, a table whose cells hold controls. If your data _is_ a list of records with known columns, use **DataGrid**, which gives you sorting and selection for free. For key/value pairs about one record, **KeyValue**.
+
+It was added for the freestyle dogfood pass, when composite tables like the Component API table needed to wear the same cloth as DataGrid without inheriting its data-driven machinery.
+
+## The contract
+
+```
+@caption?   — the table's name, rendered as a real <caption>
+@labelledBy? — id of an on-screen element that names the table (aria-labelledby on the <table>)
+@label?     — the name when it is nowhere on screen (aria-label on the <table>)
+@framed?    — false drops the radius and hairline, for a table inside a panel (default true)
+<:caption>  — a rich caption; wins over @caption
+<:head>   <:body>
+Element: HTMLDivElement
+```
+
+**The caption.** `@caption` renders a `<caption>` as the table's first child, where HTML requires it, so the table is named by it ("table, Lots in the warehouse"). The `<:caption>` block renders into the same `<caption>` and keeps its markup; if both are given, the block wins, the way a block wins over its arg on Notification, AlertDialog and Card. The caption is set in the caption role in the muted ink, above the header band. When the name is already on screen — a section heading right above the table — give that element an id and pass it as `@labelledBy`, which lands as `aria-labelledby` on the `<table>` itself, so the name can't drift from the heading. Keep `@label` for a name that is nowhere on screen; it lands as `aria-label` on the `<table>`. `...attributes` go on the wrapper `<div>`, so an `aria-label` or `aria-labelledby` passed as an attribute names the wrapper, not the table; use the args. A caption wins over both: with either caption present, neither attribute is set. `@labelledBy` wins over `@label`, as `aria-labelledby` does over `aria-label`, so only one name is ever set.
+
+**`@label` and `@labelledBy` name the `<table>`, which deliberately differs from DataTable.** DataTable's `@label` names its scroll region (a `role='region'` box with a tab stop) and sits alongside its caption: the caption names the table, the label names the region. Table has no such region — its wrapper is a plain `<div>` — so the only thing left to name is the `<table>`, and a caption already does that. Hence `@label` and `@labelledBy` here are the caption's stand-ins rather than a second name, and are dropped when a caption renders.
+
+The one non-obvious thing: **the yielded cells are styled partly through `:deep()`.** The component renders `<thead>` and `<tbody>` itself, so the inherited properties sit on those two elements and flow into your cells: the mono header voice, its ink and `nowrap` on `thead`, and top alignment on `tbody`. What the browser's `th` rule overrides (weight, alignment) and what doesn't inherit (padding, height, backgrounds, row rules, the sticky position) has to reach into content the component did not render, so `.pretui-table :deep(thead th)`, `:deep(td)`, `:deep(tbody th)`, `:deep(tbody tr:nth-child(even) td)`, `:deep(tbody tr:hover td)` and `:deep(tbody tr:last-child td)` (each with its `th` twin; the last one drops the last row rule where the frame already draws the edge) do that work. Zebra and hover paint the cells, so a caller that repaints a cell replaces them rather than tinting over them. This is a legitimate, narrow use of the escape hatch — the alternative would be a `<Table.Row>`/`<Table.Cell>` component pair, which buys type safety at the cost of the "just write a table" affordance the component exists to provide.
+
+**The header band is scoped to `thead`.** Only the column headers in `<:head>` get the sticky mono band; the header voice is set on `thead`, so it never reaches the body. A row header — `<th scope='row'>` in `<:body>` — wears the body-cell rules instead: the cell padding, the row rule, zebra and hover, top alignment and start alignment, keeping the browser's bold `th` weight. So a matrix with row headers needs no override to undo the band.
+
+Practical consequence: **your `<th>` and `<td>` get the house styling automatically, and you cannot easily opt out of it.** A cell that needs different padding needs its own class and a higher-specificity rule from the call site.
+
+## Prior art
+
+**shadcn `Table`** is the closest analogue — `Table`/`TableHeader`/`TableBody`/`TableRow`/`TableHead`/`TableCell`/`TableCaption`, each a styled element, with zero behaviour. **Web Awesome** ships no table at all. **React Aria Components `Table`** is the opposite pole: a full collection API with selection, sorting and resizing, and no way to just hand it markup.
+
+Pretui differs from shadcn on one axis and it is the interesting one: **shadcn gives you seven components, Pretui gives you three blocks.** shadcn's approach types every part and lets each be styled independently; Pretui's means a table is `<Table><:head><tr>…</tr></:head><:body>…</:body></Table>`, with `<:caption>` standing in for `TableCaption`, with native elements throughout — nothing to import, nothing to learn, and native table semantics you cannot accidentally lose by nesting a `<div>` in a `<tbody>`.
+
+The improvement over both: it **reads the boxel theme contract**, so a hand-built table follows whatever theme the card wears — surface, header band, zebra, hover, type roles and spacing ladder — with no Pret-only tokens and no literal fallbacks. DataGrid still reads Pret's own tokens and fixed metrics for the same parts, so the two differ: Table's header is set in the label role at the label size, DataGrid's in a fixed 10px eyebrow.
+
+The cost, stated plainly: no sorting, no selection, no virtualization, no column definitions, and no way to add them without switching components.
+
+## Accessibility
+
+Governing pattern: APG **Table**, whose keyboard interaction section reads "Not applicable" — every focusable element inside is an ordinary tab stop. That is the correct pattern for this component, and it is the caller's job to honour it.
+
+**Almost all of the accessibility here is yours, not the component's.** It renders `<table>`, `<thead>` and `<tbody>` and nothing else, so:
+
+- **You must supply `scope="col"` / `scope="row"`** on header cells. The component adds nothing.
+- **You must supply a name** if the table needs one: `@caption` or `<:caption>` for a visible `<caption>`, `@labelledBy` with the id of the heading when the name is already on screen, or `@label` when it is nowhere on screen. Don't write a `<caption>` into `<:head>`: it would land inside `<thead>`, which is invalid.
+- **You must supply `aria-sort`** if you build sortable headers, and the `aria-live` announcement that goes with a sort.
+- **If your cells contain widgets**, you are in APG **Grid** territory, and this component gives you none of it — no roving tabindex, no arrow navigation, no `role="grid"`. That is the point at which you should stop and use a real grid.
+
+Component-level gaps:
+
+- **The scroll container has no `tabindex="0"`.** `overflow: auto` on a wide table means a keyboard-only user cannot scroll it without tabbing through cells, which fails WCAG **2.1.1** for a table of static text. One attribute fixes it, and it would fix DataGrid too.
+- `vertical-align: top` on the body (inherited by every cell) is a good default for mixed-height content and worth knowing about before you fight it.
+
+## Theming
+
+Everything comes from the boxel theme contract:
+
+- **Surfaces and ink:** `--card` with `--card-foreground` (the wrapper, which cells inherit), `--inset` with `--foreground` (the header band), `--muted-foreground` (the caption), `--stripe` (zebra) and `--hover` (row hover, on devices that hover), each with `--foreground`.
+- **Rules and edge:** `--border` (row rules and the outer hairline), `--border-strong` (header underline), `--boxel-border-radius` (the frame's corner).
+- **Type:** `--boxel-font-size-xs` (the table), the caption role (`--boxel-caption-font-size`, `-font-weight`, `-line-height`, `-letter-spacing`), the label role for the header band (`--boxel-ui-label-font-size`, `-font-weight`, `-letter-spacing`), and `--font-mono` for its family.
+- **Spacing:** `--boxel-sp-2xs` (block padding of the caption and cells) and `--boxel-sp-xs` (inline padding of the caption, header and cells, so their text shares one start edge).
+
+The header band's height is `--pretui-table-head-height` (1.875rem), declared on the wrapper so a caller can set it; the wrapper also reads it as `scroll-padding-block-start`, so a focused cell scrolls clear of the sticky header. Body cells take a 1.4 line height (`--boxel-line-height-md`), since they wrap. **The header only sticks inside a wrapper that scrolls vertically.** `overflow: auto` makes the wrapper the header's scroll container, and with no height limit it never scrolls, so the header leaves with the rows. Set `--pretui-table-max-height` on the table (or an ancestor) to bound the wrapper, for example `--pretui-table-max-height: 24rem`; the rows then scroll under a header that stays put. Unset, it is `none` and the table is as tall as its rows. `--stripe` must be distinguishable from both `--card` and `--hover`, or zebra and hover collapse into each other.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Four listing surfaces — do not collapse them:
+
+| Job                               | Tile                         |
+| --------------------------------- | ---------------------------- |
+| Markup `<table>`                  | **Table** (this)             |
+| Read-only structured grid         | **DataGrid**                 |
+| Record listing (sort/select/page) | **DataTable** stub           |
+| Spreadsheet editor                | **Sheet** — not shadcn Sheet |
+
+shadcn `Table` is this tile. shadcn `Data Table` (TanStack recipe) is
+the **DataTable** stub.

package/bundled-realms/pretui/components/table.usage.gts

@@ -0,0 +1,44 @@
+// Pretui — Table usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Token } from './token';
+import { Table } from './table';
+import { LOT_ROWS } from '../demo-foundations';
+
+class TableUsage extends Component {
+  rows = LOT_ROWS;
+  @tracked framed = true;
+  setFramed = (v: boolean) => (this.framed = v);
+  <template>
+    <FreestyleUsage
+      @name='Table'
+      @description='A yieldable table shell for custom cells. It shares DataGrid cloth but leaves row data, semantics and interactions with the caller.'
+      @source='<Table><:head>…</:head><:body>…</:body></Table>'
+      @viewportMode='wide'
+    >
+      <:example>
+        <Table @framed={{this.framed}}>
+          <:head><tr><th>Lot</th><th>Tea</th><th>Origin</th><th>Chests</th></tr></:head>
+          <:body>{{#each this.rows as |row|}}<tr><td><Token @value={{row.lot}} /></td><td>{{row.tea}}</td><td>{{row.origin}}</td><td>{{row.chests}}</td></tr>{{/each}}</:body>
+        </Table>
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='sample rows' @value={{this.rows}} />
+        <Args.Bool
+          @name='framed'
+          @value={{this.framed}}
+          @defaultValue={{true}}
+          @description='Off drops the radius and hairline, for a table inside a panel.'
+          @onInput={{this.setFramed}}
+        />
+        <Args.Yield @name='head' @description='Table header rows.' />
+        <Args.Yield @name='body' @description='Table body rows.' />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_TABLE: Record<string, unknown> = {
+  Table: TableUsage,
+};