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

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

@@ -0,0 +1,78 @@
+## What it is
+
+A spreadsheet-grade editable data grid: cells you select with the arrow keys, edit in place, sort and quick-filter. **Reach for it when values must be _edited_ in place.** **DataGrid** and **Table** are read-only presentations and are the right choice when values only need to be read — they are far less machinery and, being APG _Tables_, do not put the page into a cell-navigation mode.
+
+## The contract
+
+```
+@rows, @columns, @density? ('compact'|'default'|'roomy'), @zebra? (true)
+@maxHeight? ('22rem'), @editable? (true), @sortable? (true), @defaultSort?
+@filter?, @pinFirstColumn?
+@validate?(next, column, row) → false keeps the editor open with the bad text intact
+@onCommit?(row, key, next), @onSortChange?(sort | null), @onFilterChange?(query)
+<:toolbar as |api|>  <:empty>  <:footer as |api|>
+```
+
+`@validate` returning `false` **keeps the editor open with the bad text intact** — the correct behaviour for a spreadsheet, where discarding what someone typed is worse than holding a bad value.
+
+## Prior art
+
+Ported from **`@cardstack/surfaces` boxel-grid** — a self-contained ESM bundle with `@tanstack/table-core` v9-alpha inlined, copied into this realm (a cross-realm absolute URL cannot be resolved by local `boxel parse`).
+
+**What the engine supplies, and Pretui does not rebuild:** row/column materialisation, per-cell edit gating, commit routing with retry, the `SheetRuntime` cell-selection and edit lifecycle, the keyboard map (arrows move, Tab/Shift-Tab by flat index, Home/End to the row edge, Enter/F2 open the editor, Escape cancels then clears selection), `role="grid"/"row"/"gridcell"` markup, the sticky header, subgrid column threading so tracks can never go jagged, roving tabindex plus `aria-activedescendant`, and the text/number/date/boolean cell widgets with commit-on-blur.
+
+**What Pretui adds, and why — this list is the component:**
+
+1. **The cloth.** boxel-grid declares its palette _on_ the grid element, which beats any inherited value; the documented override channel is the inline `style` splat, so a token map routes every engine variable onto a Pretui token.
+2. **`@chrome='none'` plus our own surface**, because upstream's header ships a fixed `box-shadow` behind no variable — un-themable otherwise, and `:deep()` is forbidden.
+3. **Sort and quick filter.** `getSheet` builds the table with the core row model only — no sorted row model, no column filters — so the engine cannot sort despite advertising `sortable: true`. Pretui sorts and filters the array _before_ handing it over, preserving row object identity so edits still write through.
+4. **Header semantics.** Upstream's examples put `role="columnheader"` directly inside the rowgroup — invalid ARIA, and it fails the realm linter. Pretui wraps them in a real `role="row"` subgrid, carries `aria-sort`, and makes each sortable header a real `<button>`.
+5. **`aria-rowcount` / `-colcount` / `-rowindex` / `-colindex`.** The engine emits none; without them a screen reader cannot say "row 4 of 18".
+6. **Tab is not a trap** — see below.
+7. **PageUp/PageDown and Ctrl+Home/Ctrl+End**, bound through the runtime's public `keyboard.bind()` extension point, because the APG grid pattern expects them and the defaults omit them. Space toggles a boolean cell without opening an editor.
+8. **Edits actually appear.** Row objects are plain and untracked, so after the engine writes `row[key] = next` nothing invalidates and the cell re-renders its _pre-edit_ value. A tracked generation counter bumps on every commit.
+9. **Date columns that work.** `getSheet`'s `type: 'date'` reads through `isoDate()`, which returns `''` for anything that is not a `Date` instance — so an ISO string silently renders an empty column. Pretui declares date columns to the engine as text and passes `@type='date'` to the cell, then validates the ISO shape on commit.
+10. Validation hook, tabular/mono machine values, density, zebra, sticky first column, empty state, and a live status line.
+
+**Honest limits, stated by the source:** **no range selection** (the engine's `select()` sets the range to the single current cell unconditionally; Pretui styles the in-range state so it lights up when the engine fills it in, but does not claim or reimplement it), **no virtual scrolling** (fine to a few hundred rows, not 100k), **no column resize or engine pinning** (`@pinFirstColumn` is honest CSS `position: sticky`), and **no FieldDef-backed columns** — the interesting Boxel seam, which needs a CardDef context; Sheet takes plain objects only.
+
+## Accessibility
+
+Governing pattern: APG **Grid** — one tab stop, arrows move a cell at a time without wrapping, Home/End to the row edges, Ctrl+Home/Ctrl+End to the corners, Page Up/Down by a screenful, Enter/F2 into edit mode, Escape out.
+
+**The most important fix is a WCAG 2.1.2 No Keyboard Trap failure in the engine.** The runtime binds Tab unconditionally: with no cell selected it selects the first cell and calls `preventDefault`, so **focus can never leave the grid**. Pretui intercepts `keydown` in the **capture phase** on its own wrapper and lets Tab through whenever no cell is selected — and always inside the header chrome, so the sort buttons are reachable at all. The resulting model is clean and worth stating to users: **Arrow to enter the cell plane, Escape to leave it, Tab to leave the grid.**
+
+Also added: the four `aria-*count/index` properties (5), valid header row structure with `aria-sort` (4), the missing Page/Ctrl keys (7), and a live status line announcing filter and sort results.
+
+Remaining gaps:
+
+- **The grid's name defaults to "Data sheet".** Pass `@label` on every Sheet; two Sheets on a page left on the default share one name.
+- **In-range styling exists for a selection that cannot happen** — harmless, but a user told about multi-cell selection will not find it.
+- **`@validate` returning false keeps the editor open** and the invalid value visible, but nothing announces _why_ it was rejected; there is no message channel (**WCAG 3.3.1/3.3.3**).
+- **Every visible row renders**; with no virtualisation, `aria-rowcount` equals the rendered count, which is honest but means large data sets are a performance problem before they are an accessibility one.
+- Boolean cells are checkboxes (`aria-checked`) that toggle on Space without an editor, so the new state is announced as the cell's checked state.
+
+## Theming
+
+Every boxel-grid engine token is mapped onto a Pretui token with a light literal fallback, delivered through the inline `style` splat because the engine declares its own palette _on_ the grid element. Pretui-owned chrome (the hairline, the depth shadow, the header band) uses `--card`, `--inset`, `--border`, `--line-strong`, `--stripe`, `--hover`, plus `--font-mono` for machine values and the density scale.
+
+Nothing branches on dark; every value is `var(--token, lightLiteral)`. The one thing a theme cannot reach is anything boxel-grid hard-codes outside its own variable set — which is exactly why `@chrome='none'` exists.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+> [!WARNING]
+> **Name collision.** In shadcn / Radix / MUI, `Sheet` is a **slide-over
+> panel**. In Pretui, Sheet is a **spreadsheet**. Agents who type "Sheet"
+> for a drawer want **Drawer** (also aliased as **SlideOver**).
+
+| Agent types            | Give them                    |
+| ---------------------- | ---------------------------- |
+| Sheet (slide-over)     | **Drawer** / **SlideOver**   |
+| Sheet (spreadsheet)    | this tile                    |
+| Data table / data grid | **DataTable** / **DataGrid** |
+| Excel-like editor      | this tile                    |
+
+Do not rename this component. Do teach the collision in every usage page
+and in the catalog brief (already: "Spreadsheet-grade editable grid").

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

@@ -0,0 +1,318 @@
+// Pretui — Sheet usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Sheet } from './sheet';
+import { SheetToolbar } from './sheet-toolbar';
+import type { SheetColumn, SheetDatum } from './sheet';
+import { LEDGER_COLUMNS, buildLedger } from '../demo-surfaces-grid';
+import type { Lot } from '../demo-surfaces-grid';
+
+// ── Sheet ────────────────────────────────────────────────────────────────
+const DENSITIES = ['compact', 'default', 'roomy'];
+
+function money(n: number): string {
+  return n.toLocaleString('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    maximumFractionDigits: 0,
+  });
+}
+
+// There is no upstream "usage.gts" to port from: boxel-grid ships example
+// CARDS (grid-editable-table.gts, grid-preset-examples.gts) in the
+// realistic-clownfish realm, and this page takes their shape — one real
+// table, edited live — rather than a matrix of dead states. What it adds
+// over those examples is the knob rail: density, zebra, the two master
+// gates, and the pin, all settable while the same selection stays live.
+class SheetUsage extends Component {
+  ledger: Lot[] = buildLedger(16);
+
+  @tracked label = 'Arrivals ledger';
+  @tracked density = 'default';
+  @tracked zebra = true;
+  @tracked editable = true;
+  @tracked sortable = true;
+  @tracked pinFirstColumn = true;
+  @tracked maxHeight = '17rem';
+  @tracked rowCount = 16;
+  @tracked lastEdit = '';
+  @tracked rejected = '';
+
+  setLabel = (v: string) => (this.label = v);
+  setDensity = (v: string) => (this.density = v);
+  setZebra = (v: boolean) => (this.zebra = v);
+  setEditable = (v: boolean) => (this.editable = v);
+  setSortable = (v: boolean) => (this.sortable = v);
+  setPinFirstColumn = (v: boolean) => (this.pinFirstColumn = v);
+  setMaxHeight = (v: string) => (this.maxHeight = v);
+  setRowCount = (v: number | null) => (this.rowCount = v ?? 0);
+
+  get densityVal() {
+    return this.density as 'compact' | 'default' | 'roomy';
+  }
+
+  // Slicing is safe where rebuilding is not: `.slice()` hands back the
+  // SAME row objects, so an edit committed at row 3 survives a change of
+  // row count. A getter that rebuilt the objects would drop every edit.
+  get rows(): SheetDatum[] {
+    return this.ledger.slice(0, this.rowCount);
+  }
+
+  get columns(): SheetColumn[] {
+    return LEDGER_COLUMNS;
+  }
+
+  /** Refuses a weight of zero or less, and a price above five figures —
+   *  returning false keeps the editor open with the bad text intact so
+   *  the reader can correct it instead of losing the keystroke. */
+  validate = (next: unknown, column: SheetColumn, row: SheetDatum): boolean => {
+    if (column.key === 'kilos' && typeof next === 'number' && next <= 0) {
+      this.rejected = `A lot cannot weigh ${next} kg — ${String(row['lot'])} left unchanged.`;
+      return false;
+    }
+    if (column.key === 'price' && typeof next === 'number' && next > 99999) {
+      this.rejected = `${money(next)}/kg is past the ledger's ceiling.`;
+      return false;
+    }
+    this.rejected = '';
+    return true;
+  };
+
+  onCommit = (row: SheetDatum, key: string, next: unknown): void => {
+    this.lastEdit = `${String(row['lot'])} · ${key} → ${String(next)}`;
+  };
+
+  get totalKilos(): number {
+    return this.rows.reduce((sum, row) => sum + Number(row['kilos'] ?? 0), 0);
+  }
+
+  get totalValue(): number {
+    return this.rows.reduce(
+      (sum, row) => sum + Number(row['kilos'] ?? 0) * Number(row['price'] ?? 0),
+      0,
+    );
+  }
+
+  get totalValueLabel(): string {
+    return money(this.totalValue);
+  }
+
+  get usage() {
+    let bits = [
+      `@label='${this.label}'`,
+      '@rows={{this.rows}}',
+      '@columns={{this.columns}}',
+      `@density='${this.densityVal}'`,
+    ];
+    if (!this.zebra) bits.push('@zebra={{false}}');
+    if (!this.editable) bits.push('@editable={{false}}');
+    if (!this.sortable) bits.push('@sortable={{false}}');
+    if (this.pinFirstColumn) bits.push('@pinFirstColumn={{true}}');
+    if (this.maxHeight) bits.push(`@maxHeight='${this.maxHeight}'`);
+    return `<Sheet\n  ${bits.join('\n  ')}\n  @validate={{this.validate}}\n  @onCommit={{this.onCommit}}\n>\n  <:toolbar as |api|>\n    <SheetToolbar @api={{api}} @title='Arrivals' />\n  </:toolbar>\n  <:footer as |api|>\n    …{{api.visibleCount}} of {{api.totalCount}}…\n  </:footer>\n</Sheet>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Sheet'
+      @description='A spreadsheet-grade editable data grid: boxel-grid’s headless runtime (cell selection, edit lifecycle, keyboard map, commit routing with retry) wearing Pretui cloth. Reach for it when values must be EDITED in place — DataGrid and Table are read-only presentations of the same kind of data. Click a cell, arrow around, Enter or F2 to edit, Tab to walk the row, Escape to leave the cell plane and hand Tab back to the page, Space to flip a checkbox. Pretui adds sort and quick filter (the engine builds its table with the core row model only, so it cannot sort on its own), the aria-rowcount/-colcount/-rowindex/-colindex set the engine omits, a real role="row" around the column headers, and a live status line. Honest limits: range selection is styled but not wired (SheetRuntime always resolves the range to the single current cell), there is no virtualisation — every visible row renders, which is fine to a few hundred rows and not a 100k-row grid — column resize and engine column pinning need TanStack state getSheet does not thread (@pinFirstColumn is honest position:sticky), and FieldDef-backed columns need a CardDef context this page has not got.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Sheet
+          @rows={{this.rows}}
+          @columns={{this.columns}}
+          @label={{this.label}}
+          @density={{this.densityVal}}
+          @zebra={{this.zebra}}
+          @editable={{this.editable}}
+          @sortable={{this.sortable}}
+          @pinFirstColumn={{this.pinFirstColumn}}
+          @maxHeight={{this.maxHeight}}
+          @validate={{this.validate}}
+          @onCommit={{this.onCommit}}
+        >
+          <:toolbar as |api|>
+            <SheetToolbar @api={{api}} @title='Arrivals' />
+          </:toolbar>
+          <:footer as |api|>
+            <span class='sg-foot'>
+              <span class='sg-foot-n'>{{this.totalKilos}}</span>
+              kg ·
+              <span class='sg-foot-n'>{{this.totalValueLabel}}</span>
+              across
+              {{api.visibleCount}}
+              lots
+            </span>
+          </:footer>
+        </Sheet>
+
+        <p class='sg-readout' data-tone={{if this.rejected 'warn' 'quiet'}}>
+          {{#if this.rejected}}
+            Rejected —
+            {{this.rejected}}
+          {{else if this.lastEdit}}
+            Last edit —
+            <span class='sg-readout-mono'>{{this.lastEdit}}</span>
+          {{else}}
+            No edits yet. Double-click a cell, or select one and press Enter.
+          {{/if}}
+        </p>
+      </:example>
+
+      <:api as |Args|>
+        <Args.Object
+          @name='rows'
+          @description='The data: an array of plain objects, mutated IN PLACE on commit. Pass a stable array — a getter that rebuilds the objects on every read throws each edit away — and give every row an id, because getSheet keys rows by row.id and falls back to the ordinal, which makes the selected cell jump when a sort reorders things. Sixteen deterministic tea lots here (seedFrom/pick from examples.gts).'
+          @required={{true}}
+          @hideControls={{true}}
+        />
+        <Args.Number
+          @name='rows (count shown)'
+          @description='Not a Sheet arg — a knob on this page, slicing the same array so you can watch the row model, the status line, and the empty state follow. Drag it to 0 for the default empty state.'
+          @value={{this.rowCount}}
+          @min={{0}}
+          @max={{16}}
+          @step={{1}}
+          @onInput={{this.setRowCount}}
+        />
+        <Args.Object
+          @name='columns'
+          @description='Column definitions in display order. Per column: key, label, type (text | number | boolean | date), width (a CSS grid track), align, mono (machine-value typography — default on for number and date), editable, sortable, hint (a small unit note beside the label — chrome, suppressed below 30rem of sheet width, so nothing load-bearing goes there). This ledger sets lot as mono + editable:false and cleared as sortable:false, so you can see both gates act independently of the masters below.'
+          @required={{true}}
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='label'
+          @description='Accessible name for the grid. Always supply a real one — it is what a screen reader announces alongside "row 4 of 16".'
+          @defaultValue='Data sheet'
+          @value={{this.label}}
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='density'
+          @description='Row height and cell padding scale. Drives --pretui-sheet-row-h / --pretui-sheet-cell-pad, which are threaded into the engine through the inline token bridge.'
+          @defaultValue='default'
+          @options={{DENSITIES}}
+          @value={{this.density}}
+          @onInput={{this.setDensity}}
+        />
+        <Args.Bool
+          @name='zebra'
+          @description='Stripe alternate rows. The stripe lives on the ROW, not the cell, so a pinned first column inherits it and stays opaque while the body scrolls sideways.'
+          @defaultValue={{true}}
+          @value={{this.zebra}}
+          @onInput={{this.setZebra}}
+        />
+        <Args.Bool
+          @name='editable'
+          @description='Master edit gate; a column can still opt out with its own editable:false, never in. Turn it off and watch the boolean column keep its checkbox — disabled — instead of degrading to the engine’s readonly "true"/"false" text.'
+          @defaultValue={{true}}
+          @value={{this.editable}}
+          @onInput={{this.setEditable}}
+        />
+        <Args.Bool
+          @name='sortable'
+          @description='Master sort gate. Off means no header buttons at all and no aria-sort — a column that cannot be sorted must not advertise the affordance.'
+          @defaultValue={{true}}
+          @value={{this.sortable}}
+          @onInput={{this.setSortable}}
+        />
+        <Args.Bool
+          @name='pinFirstColumn'
+          @description='Sticks the first column to the left edge. Honest position:sticky, NOT the engine’s column pinning (which needs TanStack pinning state getSheet does not thread). Narrow the artboard until the body scrolls to see it hold.'
+          @defaultValue={{false}}
+          @value={{this.pinFirstColumn}}
+          @onInput={{this.setPinFirstColumn}}
+        />
+        <Args.String
+          @name='maxHeight'
+          @description='CSS max-height for the scroll container, set as --pretui-sheet-max-height. The header stays stuck to the top of it.'
+          @defaultValue='22rem'
+          @value={{this.maxHeight}}
+          @onInput={{this.setMaxHeight}}
+        />
+        <Args.String
+          @name='defaultSort'
+          @description='Initial sort, as { key, dir: "asc" | "desc" }. Unset here so the sheet opens in ledger order; click any header to cycle asc → desc → unsorted.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='filter'
+          @description='Controlled quick-filter text. Omit it (as this page does) and the toolbar’s search field drives the filter itself; supply it and you own the value, with @onFilterChange as the write-back.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='validate'
+          @description='(next, column, row) => boolean, run after type coercion and before the write. Returning false keeps the editor open with the bad text intact. This page refuses a weight of zero or less and a price above five figures — try typing 0 into a Weight cell.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onCommit'
+          @description='(row, key, next) — fires after the value lands on the row object. The "last edit" line under the grid is nothing but this callback, which is how you can tell the edits are real.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onSortChange'
+          @description='(sort | null) — fires as the header cycles asc → desc → unsorted.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onFilterChange'
+          @description='(query) — fires on every quick-filter keystroke.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='<:toolbar>'
+          @description='Chrome above the grid, yielded the SheetApi: { query, setQuery, sort, toggleSort, clearSort, visibleCount, totalCount, columns }. SheetToolbar is the stock filling; anything else you build gets the same handle.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='<:footer>'
+          @description='Summary band below the grid, yielded the same SheetApi. It sits beside the live status line (role="status") that announces filter and sort results — the footer never replaces that announcement. Here: total weight and value across the visible lots.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='<:empty>'
+          @description='Replaces the default EmptyState. The default already distinguishes "no rows yet" from "the filter matched nothing" — drag the row count to 0, then type into the filter, to see both. Rendered OUTSIDE the grid’s rowgroup, because role="rowgroup" admits only role="row" children.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .sg-foot {
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+        white-space: nowrap;
+      }
+      .sg-foot-n {
+        font-family: var(--font-mono);
+        font-variant-numeric: tabular-nums;
+        color: var(--card-foreground);
+      }
+      .sg-readout {
+        margin: var(--space-3, 8px) 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .sg-readout[data-tone='warn'] {
+        color: color-mix(
+          in oklch,
+          var(--foreground) 16%,
+          var(--warning, var(--boxel-warning))
+        );
+      }
+      .sg-readout-mono {
+        font-family: var(--font-mono);
+        font-variant-numeric: tabular-nums;
+        color: var(--card-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SHEET: Record<string, unknown> = {
+  Sheet: SheetUsage,
+};