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

package/bundled-realms/pretui/components/dashboard-item.md

@@ -0,0 +1,52 @@
+## What it is
+
+One cell of a **DashboardGrid**: a tile with a drag handle, a placement, and an attachment to the grid's engine.
+
+## The contract
+
+```
+@id (required) — stable id; must match the placement's id
+@host?     — the grid that owns this cell. DashboardGrid supplies it
+@label?    — accessible label for the handle. DashboardGrid supplies the tile's title, label or id; on its own the item falls back to its id
+@live?     — true when the grid is CONTROLLED, the only case where a later change
+             to the placement may be pushed back into a live engine
+@x?, @y?, @w?, @h? — the placement: the seed at registration, and the push value when @live
+@staticStyle? — CSS-grid placement, READ-ONLY MODE ONLY
+
+<:title>   the tile's own heading line
+<:actions> trailing controls in the tile's bar
+<:default> the tile body
+```
+
+**Without `@host` the cell renders as an inert box** — no engine attachment, no drag affordances. That is what read-only mode uses, and it is what makes the cell safe to drop into a static preview without the grid's machinery coming along.
+
+**`@id` must match the placement's id.** The grid keys everything on id rather than index, so a mismatch means a tile the engine cannot place rather than a tile in the wrong spot.
+
+**`@live` is set by the grid, not by the caller**, and it exists so the cell knows whether a placement change is authoritative or historical.
+
+**The placement is a seed at registration and a push value only when live** — which is the per-cell half of the grid's controlled/uncontrolled rule.
+
+**`@staticStyle` is read-only mode only.** An editable cell must never bind `style`, because the live engine keeps its geometry there — binding it would fight the drag.
+
+## Prior art
+
+The grid-item component in dashboard engines.
+
+Where Pretui is better: the inert mode. Most grid items are inseparable from their engine, so rendering a dashboard's layout without the ability to edit it means either shipping the engine anyway or rebuilding the layout by hand.
+
+Where it is thinner: one handle, no per-edge resize grips, and no per-tile constraints (minimum size, aspect lock) beyond what the placement expresses.
+
+## Accessibility
+
+- **The handle is a focusable `role="button"` with a name** from `@label`, not a native `<button>`: gridstack's drag engine ignores presses on native buttons, so a real button could never start a pointer drag. Enter, Space and the arrows on it are the grid's keyboard path.
+- **A tile with no host has no handle**, so an inert dashboard has no controls that lead nowhere.
+- **Inside a DashboardGrid, `@label` comes from the tile's title**, which keeps a grid of handles distinguishable without the caller doing anything. A standalone item falls back to its id, so pass `@label`.
+- **The tile's content keeps its own tab order.** The handle is an addition, not a wrapper that swallows what is inside.
+
+## Theming
+
+Nothing of its own — the cell contributes position and a handle; the surface is whatever the caller renders inside it.
+
+That separation is what lets a dashboard be assembled from the kit's ordinary cards rather than from a dashboard-specific tile.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/dashboard-item.usage.gts

@@ -0,0 +1,87 @@
+// Pretui — DashboardItem usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { Token } from './token';
+import { DashboardItem } from './dashboard-item';
+
+// ── 3. DashboardItem ─────────────────────────────────────────────────────
+const ITEM_SOURCE = `<DashboardItem @id='revenue' @label='Revenue'>
+  <:title>Revenue</:title>
+  <:actions><Token @value='series/revenue@2' /></:actions>
+  <:default>…anything…</:default>
+</DashboardItem>`;
+
+const DashboardItemUsage: TemplateOnlyComponent = <template>
+    <FreestyleUsage
+      @name='DashboardItem'
+      @description="The dashboard cell, on its own. DashboardGrid renders these for you and passes @host — the seam through which the cell registers with the engine and reads adjust-mode state. WITHOUT a host it degrades exactly as shown here: an inert titled panel with no handle and no engine attachment, which is what read-only mode renders and what makes the cell safe to drop into a static preview. The two engine class names on the root are part of the contract; they are inert unless the cell sits inside a .pretui-dashboard-plane."
+      @source={{ITEM_SOURCE}}
+      @viewportMode='narrow'
+    >
+      <:example>
+        <div class='item-demo'>
+          <DashboardItem @id='revenue' @label='Revenue'>
+            <:title>Revenue</:title>
+            <:actions>
+              <Token @value='series/revenue@2' />
+            </:actions>
+            <:default>
+              <p class='item-copy'>The body takes arbitrary content — a chart, a
+                form, another card. It scrolls inside the tile rather than
+                pushing the tile out of the grid.</p>
+            </:default>
+          </DashboardItem>
+        </div>
+      </:example>
+
+      <:api as |Args|>
+        <Args.String
+          @name='id'
+          @description='Stable id. Must match the placement id in the grid layout.'
+          @hideControls={{true}}
+        />
+        <Args.Object
+          @name='host'
+          @description='The grid that owns the cell. DashboardGrid supplies it. Absent, the cell is inert: no handle, no engine attachment, no keyboard mode.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='label'
+          @description="Accessible label for the drag handle — normally the tile's title. Defaults to the id."
+          @hideControls={{true}}
+        />
+        <Args.Number
+          @name='x / y / w / h'
+          @description='The placement, pushed into a live engine whenever it changes. Undefined means "let the engine auto-position this one".'
+          @hideControls={{true}}
+        />
+        <Args.Object
+          @name='staticStyle'
+          @description='CSS-grid placement. Read-only mode ONLY — an editable cell must never bind style, because that is where gridstack keeps the live geometry.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @description='<:title>, <:actions> and the default block (the body).'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .item-demo {
+        display: grid;
+        height: 190px;
+      }
+    .item-copy {
+      margin: 0;
+      font-size: var(--text-ui-md, 12.5px);
+      line-height: 1.55;
+      color: var(--muted-foreground);
+      max-width: 46ch;
+    }
+  </style>
+</template>;
+
+export const DEMOS_DASHBOARD_ITEM: Record<string, unknown> = {
+  DashboardItem: DashboardItemUsage,
+};

package/bundled-realms/pretui/components/data-grid.gts

@@ -0,0 +1,263 @@
+// Pretui — DataGrid: a data-driven table with sortable columns.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+
+export interface ColumnSpec {
+  key: string;
+  label: string;
+  num?: boolean;
+  mono?: boolean;
+  align?: 'left' | 'right';
+  sortable?: boolean;
+}
+export type Row = Record<string, any>;
+export interface SortSpec {
+  key: string;
+  dir: 'asc' | 'desc';
+}
+
+export interface DataGridSignature {
+  Args: {
+    columns: ColumnSpec[];
+    rows: Row[];
+    rowKey?: string;
+    selectable?: boolean;
+    defaultSort?: SortSpec;
+    onSortChange?: (s: SortSpec | null) => void;
+    onSelectedChange?: (keys: unknown[]) => void;
+  };
+  Blocks: { cell: [row: Row, column: ColumnSpec] };
+  Element: HTMLDivElement;
+}
+
+// THE records table: mono eyebrow headers, zebra stripe, hover, selection.
+export class DataGrid extends Component<DataGridSignature> {
+  @tracked sort: SortSpec | null = this.args.defaultSort ?? null;
+  @tracked selected: unknown[] = [];
+
+  get rowKey() {
+    return this.args.rowKey ?? 'id';
+  }
+  get selectedInRows(): unknown[] {
+    let keys = new Set(this.args.rows.map((row) => row[this.rowKey]));
+    return this.selected.filter((key) => keys.has(key));
+  }
+  get sorted(): Row[] {
+    let s = this.sort;
+    if (!s) {
+      return this.args.rows;
+    }
+    let dir = s.dir === 'desc' ? -1 : 1;
+    return [...this.args.rows].sort((a, b) => {
+      let av = a[s.key];
+      let bv = b[s.key];
+      return (av > bv ? 1 : av < bv ? -1 : 0) * dir;
+    });
+  }
+  get allOn() {
+    return this.args.rows.length > 0 && this.selectedInRows.length === this.args.rows.length;
+  }
+  clickSort = (c: ColumnSpec) => {
+    if (c.sortable === false) {
+      return;
+    }
+    let s = this.sort;
+    this.sort = !s || s.key !== c.key
+      ? { key: c.key, dir: 'asc' }
+      : s.dir === 'asc'
+        ? { key: c.key, dir: 'desc' }
+        : null;
+    this.args.onSortChange?.(this.sort);
+  };
+  toggle = (key: unknown) => {
+    let current = this.selectedInRows;
+    this.selected = current.includes(key)
+      ? current.filter((x) => x !== key)
+      : [...current, key];
+    this.args.onSelectedChange?.(this.selected);
+  };
+  toggleAll = () => {
+    this.selected = this.allOn ? [] : this.args.rows.map((r) => r[this.rowKey]);
+    this.args.onSelectedChange?.(this.selected);
+  };
+  sortMark = (c: ColumnSpec) => {
+    let s = this.sort;
+    if (!s || s.key !== c.key) {
+      return '';
+    }
+    return s.dir === 'asc' ? ' ↑' : ' ↓';
+  };
+  sortState = (c: ColumnSpec) => {
+    let s = this.sort;
+    return s && s.key === c.key ? s.dir : undefined;
+  };
+  isSelected = (row: Row) => this.selectedInRows.includes(row[this.rowKey]);
+  cellValue = (row: Row, c: ColumnSpec) => row[c.key];
+  keyFor = (row: Row) => row[this.rowKey];
+
+  <template>
+    <div class='pretui-gridwrap' data-test-pretui-datagrid ...attributes>
+      <table class='pretui-datagrid'>
+        <thead>
+          <tr>
+            {{#if @selectable}}
+              <th class='pretui-selcol'>
+                <input
+                  type='checkbox'
+                  class='pretui-checkbox'
+                  checked={{this.allOn}}
+                  aria-label='Select all'
+                  {{on 'change' this.toggleAll}}
+                />
+              </th>
+            {{/if}}
+            {{#each @columns as |c|}}
+              <th
+                data-sort={{this.sortState c}}
+                data-align={{if c.align c.align 'left'}}
+              >
+                <button
+                  type='button'
+                  class='pretui-th-btn'
+                  {{on 'click' (fn this.clickSort c)}}
+                >{{c.label}}{{this.sortMark c}}</button>
+              </th>
+            {{/each}}
+          </tr>
+        </thead>
+        <tbody>
+          {{#each this.sorted key='@index' as |row|}}
+            <tr data-state={{if (this.isSelected row) 'selected'}}>
+              {{#if @selectable}}
+                <td>
+                  <input
+                    type='checkbox'
+                    class='pretui-checkbox'
+                    checked={{this.isSelected row}}
+                    aria-label='Select row'
+                    {{on 'change' (fn this.toggle (this.keyFor row))}}
+                  />
+                </td>
+              {{/if}}
+              {{#each @columns as |c|}}
+                <td
+                  class='{{if c.num "pretui-num"}} {{if c.mono "pretui-mono"}}'
+                  data-align={{if c.align c.align 'left'}}
+                >
+                  {{#if (has-block 'cell')}}
+                    {{yield row c to='cell'}}
+                  {{else}}
+                    {{this.cellValue row c}}
+                  {{/if}}
+                </td>
+              {{/each}}
+            </tr>
+          {{/each}}
+        </tbody>
+      </table>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-gridwrap {
+          overflow: auto;
+          border-radius: inherit;
+        }
+        .pretui-datagrid {
+          width: 100%;
+          border-collapse: collapse;
+          font-size: var(--text-ui-md, 12.5px);
+          background: var(--card);
+        }
+        .pretui-datagrid th {
+          position: sticky;
+          top: 0;
+          z-index: 2;
+          height: 30px;
+          padding: 0 10px;
+          text-align: left;
+          font-family: var(--font-mono);
+          font-size: 10px;
+          font-weight: 500;
+          letter-spacing: var(--track-eyebrow, 0.08em);
+          text-transform: uppercase;
+          color: var(--muted-foreground);
+          background: var(--inset, var(--boxel-100));
+          box-shadow: inset 0 -1px 0 var(--line-strong, var(--boxel-400));
+          white-space: nowrap;
+          cursor: pointer;
+          user-select: none;
+        }
+        .pretui-datagrid th[data-sort] {
+          color: var(--foreground);
+        }
+        .pretui-th-btn {
+          background: none;
+          border: 0;
+          padding: 0;
+          font: inherit;
+          letter-spacing: inherit;
+          text-transform: inherit;
+          color: inherit;
+          cursor: pointer;
+          white-space: inherit;
+        }
+        .pretui-datagrid td {
+          height: 32px;
+          padding: 0 10px;
+          box-shadow: inset 0 -1px 0 var(--border);
+          white-space: nowrap;
+        }
+        .pretui-datagrid th[data-align='right'],
+        .pretui-datagrid td[data-align='right'] {
+          text-align: right;
+        }
+        .pretui-datagrid tbody tr:nth-child(even) td {
+          background: var(--stripe, var(--boxel-100));
+        }
+        .pretui-datagrid tbody tr:hover td {
+          background: var(--hover, var(--boxel-100));
+        }
+        .pretui-datagrid tbody tr[data-state='selected'] td {
+          background: var(--pretui-selected, var(--boxel-100));
+        }
+        .pretui-num {
+          text-align: right;
+          font-variant-numeric: tabular-nums;
+        }
+        .pretui-mono {
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-sm, 11.5px);
+        }
+        .pretui-selcol {
+          width: 32px;
+        }
+        .pretui-checkbox {
+          appearance: none;
+          width: 15px;
+          height: 15px;
+          margin: 0;
+          border-radius: 5px;
+          background: var(--pretui-control-rest, var(--field, var(--boxel-light)));
+          box-shadow: 0 0 0 1px var(--pretui-control-border, var(--input));
+          cursor: pointer;
+          display: inline-grid;
+          place-content: center;
+        }
+        .pretui-checkbox:checked {
+          background: var(--primary);
+          box-shadow: 0 0 0 1px color-mix(in oklch, var(--primary) 70%, var(--border)),
+            var(--pretui-edge-highlight, inset 0 1px 0 rgb(255 255 255 / 0.14));
+        }
+        .pretui-checkbox:checked::before {
+          content: '';
+          width: 9px;
+          height: 9px;
+          background: var(--primary-foreground);
+          clip-path: polygon(14% 47%, 38% 70%, 86% 18%, 96% 30%, 39% 89%, 4% 58%);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/data-grid.md

@@ -0,0 +1,64 @@
+## What it is
+
+The records table: columns declared as data, rows as objects, with sortable headers, zebra striping, hover, sticky headers and optional row selection. Reach for it whenever you are showing a homogeneous list of records and the columns are known. If you need custom markup in every cell and no data-driven machinery, use **Table**, which is this component's shell as a yieldable primitive — same cloth, no engine. For a handful of label/value pairs about _one_ record, use **KeyValue**; for a spreadsheet with editing, use **Sheet**.
+
+## The contract
+
+```
+@columns: { key, label, num?, mono?, align?, sortable? }[]
+@rows: Record<string, any>[]
+@rowKey? (default 'id')
+@selectable?, @defaultSort?: { key, dir }
+@onSortChange?(sort | null), @onSelectedChange?(keys)
+<:cell as |row, column|>   — optional per-cell override
+```
+
+**Sort cycles through three states, not two:** ascending → descending → **unsorted**. Most tables trap you in a sort once you start; this one lets you get back to the source order, and `@onSortChange` receives `null` for that state. Small, and correct.
+
+\*\*The `num` and `mono` flags are declared on a column, not per cell: numeric columns get tabular figures and right alignment, mono columns get the mono face. Declaring this on the column means every cell agrees, which is the thing hand-built tables lose first.
+
+`<:cell>` is an override, not a requirement — omit it and cells print `row[column.key]`.
+
+Selection is internal state published through `@onSelectedChange`; there is no controlled selection arg, so selection is uncontrolled only.
+
+## Prior art
+
+**React Aria Components `Table`** renders a real `<table>` with `role="grid"`, and exposes `selectionMode`, `selectionBehavior`, `sortDescriptor`/`onSortChange`, `Column isRowHeader`/`allowsSorting`/width props, `ResizableTableContainer`, drag-and-drop hooks, and `keyboardNavigationBehavior: 'arrow' | 'tab'`. **AG Grid** is the enterprise reference — virtualisation, pinning, grouping, aggregation. **shadcn** has no grid at all: `Table` is styled semantic markup and the behaviour is a TanStack recipe layered on top.
+
+Pretui sits deliberately at the small end, and the choice of **APG Table over APG Grid is the right one**: the Grid pattern (arrow-key cell navigation, Ctrl+Space/Shift+Space selection, F2 edit mode, a single tab stop) exists for tables whose cells contain widgets, and paying its cost for a read-mostly records list makes the table _harder_ to use, not easier. APG's Table pattern lists its keyboard interaction as "Not applicable" — every focusable thing is a normal tab stop — and that is what this is.
+
+Where it improves on the small-end competition: sorting, selection, sticky headers, zebra and the numeric/mono typographic system all arrive from a column declaration, where shadcn gives you none of it.
+
+Two implementation choices worth flagging as weaknesses rather than differences:
+
+- **The sort comparator is a raw `>`/`<` on the cell value.** No locale-aware string collation (so accented names sort wrongly), no numeric coercion for numeric strings, no stable handling of `null`/`undefined`. `Intl.Collator` would fix the first two in a line.
+- **Rows are keyed by `@index`, not by `@rowKey`.** `{{#each this.sorted key='@index'}}` means a sort discards DOM identity for every row — the opposite of what `@rowKey` was declared for, and it forces a full re-render (and loses any in-cell DOM state) on every sort. This looks like an oversight; `key=this.rowKey` is the fix.
+
+## Accessibility
+
+Governing pattern: APG **Table** (not Grid — see above). Structure is a real `<table>`/`<thead>`/`<tbody>`/`<th>`/`<td>`, which is most of the battle.
+
+Gaps, in rough order of severity:
+
+- **No `aria-sort` on the sorted header.** The component tracks sort state and reflects it as `data-sort` for styling, but the ARIA property that tells a screen-reader user which column is sorted and in which direction is absent. The only signal is a `↑`/`↓` glyph appended to the header button's text, which is announced inconsistently across readers. This is the clearest single fix, and `data-sort` already holds the value.
+- **No `scope="col"` on header cells.** Browsers infer column scope for a simple single-row `<thead>`, so this usually works — but it is one attribute and it removes the guesswork.
+- **No accessible name for the table.** There is no `<caption>` and no `aria-label` arg, so a page with three tables announces three unnamed tables.
+- **The select-all checkbox has no indeterminate state.** When some rows are selected it shows unchecked, which misrepresents the state. `Checkbox` in this kit has no indeterminate support either, so this is a shared gap — and select-all is precisely the pattern `aria-checked="mixed"` exists for.
+- **Row checkboxes are all labelled "Select row".** In a fifty-row table, fifty identical labels. They should name the row (`Select {{row.name}}`), which the component has the data to do.
+- **Sorting changes the row order with no announcement.** A `role="status"` region saying "sorted by Name, ascending" is what React Aria does; nothing here announces.
+- **`user-select: none` on headers** blocks selecting header text, which is a minor but real cost with no upside for a button-containing header.
+- Sticky headers plus `overflow: auto` mean the table can scroll horizontally; there is no `tabindex="0"` on the scroll container, so a keyboard-only user cannot scroll a wide table without tabbing through its cells (WCAG 2.1.1).
+
+## Theming
+
+`--card` (table surface), `--inset` (header band), `--line-strong` (header underline), `--border` (row rules), `--stripe` (zebra), `--hover` (row hover), `--muted-foreground` and `--foreground` (header ink, resting and sorted), `--font-mono` and `--track-eyebrow` (the mono eyebrow header voice), `--text-ui-md`.
+
+Header type is a hard-coded 10px uppercase mono — the kit's eyebrow voice — and is not tokenized, so a theme cannot resize it. A theme **must** define `--stripe` distinctly from both `--card` and `--hover`, or zebra striping and hover become indistinguishable and the row you are pointing at stops being obvious.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Closest to React Aria `TableView` / a read-only Ant Table. Interactive
+listing UX (sort + row selection + column visibility + pagination) is
+**DataTable**. Spreadsheet editing is **Sheet**.

package/bundled-realms/pretui/components/data-grid.usage.gts

@@ -0,0 +1,50 @@
+// Pretui — DataGrid usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { DataGrid } from './data-grid';
+import { LOT_ROWS } from '../demo-foundations';
+
+const LOT_COLUMNS = [
+  { key: 'lot', label: 'Lot', mono: true },
+  { key: 'tea', label: 'Tea' },
+  { key: 'origin', label: 'Origin' },
+  { key: 'chests', label: 'Chests', num: true, align: 'right' as const },
+];
+
+class DataGridUsage extends Component {
+  columns = LOT_COLUMNS;
+  rows = LOT_ROWS;
+  @tracked selected: unknown[] = [];
+  setSelected = (keys: unknown[]) => (this.selected = keys);
+  cell = (row: Record<string, unknown>, column: { key: string }) => String(row[column.key] ?? '');
+  <template>
+    <FreestyleUsage
+      @name='DataGrid'
+      @description='The read-only records table: sortable headers, zebra rows and optional native-checkbox selection. Row identity is explicit and sample data is visible in the API panel.'
+      @source='<DataGrid @rowKey="lot" @selectable="true" … />'
+      @viewportMode='wide'
+    >
+      <:example>
+        <DataGrid @columns={{this.columns}} @rows={{this.rows}} @rowKey='lot' @selectable={{true}} @onSelectedChange={{this.setSelected}}>
+          <:cell as |row column|>{{this.cell row column}}</:cell>
+        </DataGrid>
+        <p class='foundation-readout'>Selected: {{this.selected.length}}</p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='columns' @value={{this.columns}} />
+        <Args.Object @name='rows' @value={{this.rows}} />
+        <Args.String @name='rowKey' @value='lot' @defaultValue='id' />
+        <Args.Bool @name='selectable' @value={{true}} />
+        <Args.Action @name='onSortChange' />
+        <Args.Action @name='onSelectedChange' />
+        <Args.Yield @name='cell' @description='Receives row and column.' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>.foundation-readout { margin: 8px 0 0; font: var(--text-ui-xs) var(--font-mono); color: var(--muted-foreground); }</style>
+  </template>
+}
+
+export const DEMOS_DATA_GRID: Record<string, unknown> = {
+  DataGrid: DataGridUsage,
+};