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

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

@@ -0,0 +1,104 @@
+## What it is
+
+The record listing an agent means by "data table": sortable headers, per-column filters, a column switcher, row selection, expandable detail rows, pinned columns, paging and density, over a plain `<table>`. It is the fourth of the kit's row-drawing things, and the other three are worth naming because the wrong one is a common reach. **Table** is the markup primitive: you write the `<tr>`s. **DataGrid** is the read-only structured grid, args in and rows out, with no toolbar and no view state. **Sheet** is the spreadsheet — editable cells, a real `role='grid'`, the boxel-grid engine. When the pane is too narrow for columns, the same rows go into **List** with **Item** rows, which share this component's selection model and load chrome.
+
+Not built, and not stubbed: virtualization (the kit already has one windowing engine in **AssetGrid**; page instead), tree data (**Tree** is the kit's tree; `<:expanded>` covers per-row detail, and **List** takes the same `<:expanded>` and `@expandedKeys` for the narrow pane), multi-column sort, column resize and drag-reorder, and server-side filtering as a mode (hold `@filters` yourself, feed them into `@loadKey`, and let `@load` return the narrowed set).
+
+## The contract
+
+```
+@columns                              — DataColumn[]: key, label, value?, sortable?, align?, mono?, width?, pin?, fixed?, hidden?, alwaysVisible?, filter?
+@rows? | @dataSource?                 — the records (either spelling); OR
+@load?, @loadKey?                     — an async loader, re-run when the key changes
+@key?                                 — (row, index) => RowKey; pass it
+@caption?, @label?                    — a real <caption>, or a name for the scroll region
+@size?                                — xs|s|m|l|xl; sm/md/lg/small/medium/large/middle accepted
+@sortable?, @sort?, @defaultSort?, @onSortChange?, @comparator?
+@selectionMode?                       — none|single|multi
+@selected?, @defaultSelected?, @onSelectionChange?
+@visibleColumns?, @defaultVisibleColumns?, @onVisibleColumnsChange?, @columnMenu?
+@filters?, @defaultFilters?, @onFiltersChange?
+@expandedKeys?, @defaultExpandedKeys?, @onExpandedChange?
+@pageSize?, @page?, @defaultPage?, @onPageChange?
+@rowLabel?                            — (row, index) => the row's accessible name
+@striped?, @stickyHeader?, @minWidth?
+@busy? | @loading?                    — aria-busy without replacing the rows
+@placeholder?, @itemNoun?, @emptyTitle?, @emptyMessage?, @loadingLabel?, @skeletonRows?
+<:cell as |text row col|>             — one block for every column; switch on col.key
+<:expanded as |row index|>            — supplying it turns on the expander column
+<:actions as |row|>                   — the row's Menu or IconButton
+<:toolbar> <:empty> <:loading> <:error>
+```
+
+**Every view axis is controlled or uncontrolled by the same rule.** Sort, selection, visibility, filters, expansion and page each take a value, a `default*` seed and an `on*Change` callback. Passing the value makes the axis controlled and the component stops writing its own copy; leaving it out lets the component keep state and still report every change. There is no separate flag that switches modes.
+
+**Pass `@key`.** Without it the row's identity is its index, and a listing sorts. The index handed to the key function is absolute across pages, so even the index fallback does not let selection leak from page 1 to page 2, but a keyed row is the only one that survives a sort.
+
+**The `<:cell>` block's first parameter is the printed value**, already through `@placeholder` (`null`, `undefined` and `''` print as the placeholder; booleans as Yes/No). The row is the second parameter, fully typed, so a template never narrows `unknown`. The block is invoked for every column; branch on `col.key`.
+
+**Filtering happens before sorting and before selection.** Two `DataSource` machines are stacked: the loader owns load state, the table owns sort and selection over rows that are already filtered, so select-all means "every row you can see" and a sort never disagrees with a filter. A text filter is a case-insensitive contains match over the printed value; an options filter is a multi-select over a fixed set; `filter.match(row, value)` replaces either. A filter change resets to page 1.
+
+**Pinning is declared, never measured.** A pinned column and every pinned column before it must declare `width`; offsets are summed from those declared widths. A pinned column that follows an unmeasurable one is left unpinned rather than laid on top of it. Ant's `fixed: true` is accepted and means `pin: 'start'`.
+
+**The toolbar earns its space.** It renders only when there is a `<:toolbar>` block, a filterable column, a hideable column, or a current selection. A selectable table with nothing selected has no bar.
+
+## Prior art
+
+**shadcn's Data Table** is a recipe, not a component: TanStack Table plus the Table primitives, Pagination, DropdownMenu and Checkbox, assembled per project. **Ant `Table`** is the enterprise maximalist: `sorter`, `filters`, `rowSelection`, `expandable`, `fixed`, `scroll`, `pagination`. **MUI `DataGrid`** is a product with its own licence tiers. **Tremor `Table`** and **Mantine `Table`** are presentational. **React Aria `Table`** is the accessibility reference and takes on `role='grid'` in full.
+
+What this component fixes, read against that corpus:
+
+- **Sort reaches assistive technology.** shadcn, Mantine and Tremor emit no `aria-sort` at all; Ant sets it only on the active column; MUI only if the caller passes `sortDirection`. Here every sortable `<th>` carries `aria-sort`, `none` when it is not the active one, so the header row says which columns can be sorted as well as which one is. The sort control is a real `<button>`, not Ant's `tabindex='0'` `<th>` or MUI's `<span>` dressed as one, and it carries a visually hidden mirror that names the next state ("sorted ascending — activate to sort descending").
+- **Every `<th>` has `scope='col'`.** shadcn's, Mantine's and Tremor's do not.
+- **Row selection state is on the row.** The corpus uses `data-state`, a class, or `data-selected`; MUI's docs put `role='checkbox'` on the `<tr>`, which makes the row's cells presentational. Here the `<tr>` carries `aria-selected` and `data-selected`, and the operable control stays a real per-row checkbox with its own name.
+- **The scroll container has a tab stop.** MUI's `TableContainer` is `overflow: auto` with no `tabindex` and no role, so a wide table cannot be scrolled from the keyboard; Tremor and shadcn ship the same. Here it is a named `role='region'` in the tab sequence.
+- **Filtered-empty is its own state.** shadcn renders one "No results." for an empty dataset and for filters that matched nothing. Here the second is a distinct state with a Clear filters action; the first is **DataShell**'s empty state.
+- **Filters live in the toolbar.** Ant hides each column's filter behind a funnel icon inside the `<th>`, which puts a second control in the sort cell and leaves the active filter invisible. Here every filterable column gets a labelled toolbar control, and the affected `<th>` is marked `data-filtered`.
+- **Select-all covers the whole filtered set**, and its accessible name says so ("Select all 24 lots"). shadcn and Ant scope it to the page and add a second "select all N" affordance.
+- **No window media queries.** Density and the rest respond to the component's own box.
+
+Where it is thinner: **`role='grid'` is not claimed**, deliberately, so there is no arrow-key cell travel, no `aria-rowindex` and no roving tabindex — the browser's native table navigation and the document tab order are what you get, and the kit's full grid role lives in **Sheet**. No multi-column sort, no column resize, no drag-reorder, no virtualization, no tree rows. Ant's header-cell filter popovers, `rowSelection.getCheckboxProps`, `summary` rows and `expandable.expandRowByClick` have no equivalent.
+
+## Accessibility
+
+Governing pattern: a native `<table>` with the APG **Sorted Table** conventions layered on. `role='grid'` is not claimed, so the APG Grid keyboard contract does not apply and no cell-level focus management is attempted.
+
+What the component does, from its rendered markup and its tests:
+
+- **Every header cell is `<th scope='col'>`.** A sortable one carries `aria-sort` in all three states (`none`, `ascending`, `descending`); a column with `sortable: false` carries no `aria-sort` and renders no button. `@caption` renders a real `<caption>`.
+- **The sort control is a `<button>`** whose text includes a hidden hint naming the state it will move to.
+- **Selectable rows carry `aria-selected`** (`'false'` before anything is picked); a non-selectable table carries no `aria-selected` anywhere. Each row's checkbox or radio is named by `@rowLabel` — pass it, or the name is "Row N". Single-select radios share one `name`, so the browser enforces the single choice.
+- **Select-all is a genuinely mixed checkbox** (`indeterminate` set as a property, so `aria-checked='mixed'` follows) and is named with the count it covers.
+- **The expander is a `<button>`** with `aria-expanded`, an `aria-label` built from the row's name ("Expand Gyokuro"), and `aria-controls` resolving to the detail `<tr>`'s id while the row is open. A collapsed row's detail is not rendered, so it carries no `aria-controls` then rather than a dangling one.
+- **The scroll box is `role='region'`** with an `aria-label` (from `@label`, falling back to `@caption`, then "Table") and `tabindex='0'`.
+- **A `role='status'` live region** announces the settled count: "6 of 24 lots", "3 lots", or "No lots". It is rendered empty at first and filled only from settled load state, so a filter keystroke that re-queries announces once when the results land. Paging composes **Pagination**, whose current page carries `aria-current='page'`.
+- **`@busy` sets `aria-busy`** and dims the scroll box without replacing the rows, so focus and scroll position survive.
+
+The caller's failures to avoid: a `<:cell>` that puts an interactive control in a cell relies on document tab order, which is correct for a table without `role='grid'` but means a long page of buttons is a long Tab sequence; a `<:actions>` trigger needs its own `aria-label` (the usage page shows "Actions for …"); and the meaning of a row must not depend on `@striped` or the selection tint alone — the selected row also gets a rule down its inline start, so it reads in greyscale.
+
+## Theming
+
+Consumed directly: `--foreground`, `--muted-foreground`, `--card`, `--border`, `--primary`, `--primary-foreground`, `--ring`, `--radius`, `--radius-surface`, `--inset`, `--hover`, `--stripe`, `--line-strong`, `--input`, `--field`, `--font-mono`, `--font-sans`, `--text-ui-md`, `--text-ui-sm`, `--track-ui`, `--track-eyebrow`, `--space-2` … `--space-5`, `--pretui-shadow-hairline`, `--pretui-control-rest`, `--pretui-control-border`, `--pretui-edge-highlight`, `--pretui-selected`, `--pretui-dur-snap`, `--pretui-ease-snap`, `--pretui-z-sticky`, `--pretui-z-sticky-header`.
+
+Its own knobs: `--pretui-dt-pick-w` (2.6em), `--pretui-dt-exp-w` (2.2em) and `--pretui-dt-act-w` (3em) are the widths of the selection, expander and actions columns. The template stamps `data-pick`, `data-detail` and `data-actions` on the root and the stylesheet resolves `--pretui-dt-lead` and `--pretui-dt-tail` from them, which is how a pin offset computed in JS can add the control columns without knowing whether they exist. `--pretui-dt-min-w` is set from `@minWidth`.
+
+Density is one axis: `@size` sets the root `font-size` and every internal dimension is in `em`, so a theme retunes the whole table by retuning `--text-ui-md`. Header cells are the eyebrow voice (mono, uppercase, `--track-eyebrow`) on `--inset`. Coarse pointers get 44px rows and 20px checkboxes; `prefers-reduced-motion` removes the chevron transition.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| TanStack / Ant / shadcn                 | Pretui                                                |
+| --------------------------------------- | ----------------------------------------------------- |
+| `columns` / `accessorKey` / `header`    | `@columns` with `key` / `label` / `value`             |
+| `data` / `dataSource`                   | `@rows` (`@dataSource` accepted)                      |
+| `sorting` / `onSortingChange`           | `@sort` / `@onSortChange`                             |
+| `rowSelection` / `onRowSelectionChange` | `@selected` / `@onSelectionChange` + `@selectionMode` |
+| `columnVisibility`                      | `@visibleColumns` / `@onVisibleColumnsChange`         |
+| `columnFilters`                         | `@filters` / `@onFiltersChange`                       |
+| `pagination`                            | `@pageSize` / `@page` / `@onPageChange`               |
+| Ant `expandable`                        | `<:expanded as \|row index\|>`                        |
+| Ant `fixed`                             | `pin` on the column (`fixed: true` accepted)          |
+| Ant `size` / density                    | `@size`                                               |
+| `getRowId`                              | `@key`                                                |
+| empty / loading                         | `<:empty>` / `<:loading>` / `@busy`                   |

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

@@ -0,0 +1,324 @@
+// Pretui — DataTable usage page. The lots come from examples-listing.gts.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { StatusChip } from './status-chip';
+import { Token } from './token';
+import { Menu } from './menu';
+import type { MenuEntry } from '../internal/menu';
+import { DataTable } from './data-table';
+import { Descriptions } from './descriptions';
+import type { DataColumn, FilterState } from './data-table';
+import type { DescriptionsItem } from './descriptions';
+import type { ListingSizeArg } from '../internal/reading-listing';
+import type {
+  RowKey,
+  SelectionMode,
+  SortState,
+} from '../data-component';
+import { GRADES, LOTS, MODES, SIZES, lotLabel } from '../examples-listing';
+import type { Lot } from '../examples-listing';
+
+const GRADE_OPTIONS = GRADES.map((g) => ({ value: g, label: g }));
+const PLACE_OPTIONS = Array.from(new Set(LOTS.map((l) => l.place))).map(
+  (p) => ({ value: p, label: p }),
+);
+
+const COLUMNS: DataColumn<Lot>[] = [
+  { key: 'id', label: 'Lot', mono: true, width: '6.5em', alwaysVisible: true },
+  { key: 'tea', label: 'Tea', filter: { kind: 'text' } },
+  { key: 'supplier', label: 'Supplier' },
+  {
+    key: 'place',
+    label: 'Origin',
+    filter: { kind: 'options', options: PLACE_OPTIONS },
+  },
+  {
+    key: 'grade',
+    label: 'Grade',
+    filter: { kind: 'options', options: GRADE_OPTIONS },
+  },
+  { key: 'kg', label: 'Weight', align: 'end', mono: true, width: '6em' },
+  { key: 'price', label: 'Price', align: 'end', mono: true, width: '7em' },
+];
+
+const PINNED_COLUMNS: DataColumn<Lot>[] = COLUMNS.map((col) =>
+  col.key === 'id' ? { ...col, pin: 'start' as const } : col,
+);
+
+
+class DataTableUsage extends Component {
+  modes = MODES;
+  sizes = SIZES;
+  lots = LOTS;
+  columns = COLUMNS;
+
+  @tracked selectionMode: SelectionMode = 'multi';
+  @tracked size: ListingSizeArg = 'm';
+  @tracked pinFirst = false;
+  @tracked striped = true;
+  @tracked pageSize = 6;
+  @tracked showDetail = true;
+  @tracked lastSort = '—';
+  @tracked lastSelection = '—';
+  @tracked lastFilters = '—';
+
+  setSelectionMode = (v: string) => (this.selectionMode = v as SelectionMode);
+  setSize = (v: string) => (this.size = v as ListingSizeArg);
+  setPinFirst = (v: boolean) => (this.pinFirst = v);
+  setStriped = (v: boolean) => (this.striped = v);
+  setPageSize = (v: number) => (this.pageSize = v);
+  setShowDetail = (v: boolean) => (this.showDetail = v);
+
+  get activeColumns(): DataColumn<Lot>[] {
+    return this.pinFirst ? PINNED_COLUMNS : COLUMNS;
+  }
+
+  rowKey = (row: Lot): RowKey => row.id;
+  rowLabel = (row: Lot): string => lotLabel(row);
+
+  onSortChange = (sort: SortState | null) => {
+    this.lastSort = sort ? sort.key + ' ' + sort.dir : 'unsorted';
+  };
+  onSelectionChange = (keys: RowKey[]) => {
+    this.lastSelection = keys.length ? keys.join(', ') : 'none';
+  };
+  onFiltersChange = (filters: FilterState) => {
+    let parts = Object.keys(filters)
+      .map((key) => {
+        let value = filters[key];
+        let text = Array.isArray(value) ? value.join('+') : String(value);
+        return text.length ? key + '=' + text : '';
+      })
+      .filter((s) => s.length > 0);
+    this.lastFilters = parts.length ? parts.join(' · ') : 'none';
+  };
+
+  rowMenu = (row: Lot): MenuEntry[] => [
+    { label: 'Open ' + row.id },
+    { label: 'Duplicate' },
+    '---',
+    { label: 'Archive', destructive: true },
+  ];
+
+  isPriceCol = (key: string): boolean => key === 'price';
+  isGradeCol = (key: string): boolean => key === 'grade';
+
+  detailItems = (row: Lot): DescriptionsItem[] => [
+    { label: 'Lot', value: row.id, mono: true },
+    { label: 'Supplier', value: row.supplier },
+    { label: 'Origin', value: row.place },
+    { label: 'Grade', value: row.grade },
+    { label: 'Weight', value: String(row.kg) + ' kg', mono: true },
+    { label: 'Price', value: row.price, mono: true },
+    { label: 'Cupping note', value: row.note, span: 'fill' },
+  ];
+
+  actionsLabel = (row: Lot): string => 'Actions for ' + lotLabel(row);
+
+  <template>
+    <FreestyleUsage
+      @name='DataTable'
+      @slug='data-table'
+      @description='The record listing: sortable headers with real aria-sort, per-column filters in the toolbar, a column switcher, row selection, expandable detail rows, pinned columns and density. It is NOT the spreadsheet — that is Sheet — and it is not the markup primitive Table.'
+    >
+      <:example>
+        <div class='dt-demo'>
+          <div class='dt-readout'>
+            <span>sort
+              <strong>{{this.lastSort}}</strong></span>
+            <span>selected
+              <strong>{{this.lastSelection}}</strong></span>
+            <span>filters
+              <strong>{{this.lastFilters}}</strong></span>
+          </div>
+
+          {{#if this.showDetail}}
+            <DataTable
+              @columns={{this.activeColumns}}
+              @rows={{this.lots}}
+              @key={{this.rowKey}}
+              @rowLabel={{this.rowLabel}}
+              @caption='Lots booked this season'
+              @size={{this.size}}
+              @selectionMode={{this.selectionMode}}
+              @striped={{this.striped}}
+              @pageSize={{this.pageSize}}
+              @itemNoun='lot'
+              @minWidth='46rem'
+              @onSortChange={{this.onSortChange}}
+              @onSelectionChange={{this.onSelectionChange}}
+              @onFiltersChange={{this.onFiltersChange}}
+            >
+              <:cell as |text row col|>
+                {{#if (this.isGradeCol col.key)}}
+                  <StatusChip @value={{row.grade}} />
+                {{else if (this.isPriceCol col.key)}}
+                  <Token @value={{row.price}} />
+                {{else}}
+                  {{text}}
+                {{/if}}
+              </:cell>
+              <:expanded as |row|>
+                <Descriptions
+                  @items={{this.detailItems row}}
+                  @columns={{3}}
+                  @bordered={{true}}
+                  @size='s'
+                />
+              </:expanded>
+              <:actions as |row|>
+                <Menu @items={{this.rowMenu row}} @label='Lot actions' @align='end'>
+                  <:trigger as |isOpen toggle|>
+                    <Button
+                      @appearance='plain'
+                      @size='s'
+                      aria-label={{this.actionsLabel row}}
+                      data-open={{if isOpen 'true'}}
+                      {{on 'click' toggle}}
+                    >⋯</Button>
+                  </:trigger>
+                </Menu>
+              </:actions>
+            </DataTable>
+          {{else}}
+            <DataTable
+              @columns={{this.activeColumns}}
+              @rows={{this.lots}}
+              @key={{this.rowKey}}
+              @rowLabel={{this.rowLabel}}
+              @caption='Lots booked this season'
+              @size={{this.size}}
+              @selectionMode={{this.selectionMode}}
+              @striped={{this.striped}}
+              @pageSize={{this.pageSize}}
+              @itemNoun='lot'
+              @minWidth='46rem'
+              @onSortChange={{this.onSortChange}}
+              @onSelectionChange={{this.onSelectionChange}}
+              @onFiltersChange={{this.onFiltersChange}}
+            />
+          {{/if}}
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='columns'
+          @value={{this.columns}}
+          @description='The column model, in display order. Each column carries key (identity, default field read and sort key), label, and optionally value(row), sortable, align, mono, width, pin, hidden, alwaysVisible and filter. Ant spellings land too: fixed:true means pin start.'
+        />
+        <Args.Object
+          @name='rows'
+          @value={{this.lots}}
+          @description='The records. dataSource is accepted as an alias. Supply EITHER rows or load, never both. Filters run in the browser over whatever rows are in hand, eager or loaded; to filter at the source instead, hold filters yourself and feed them into loadKey.'
+        />
+        <Args.Action
+          @name='key'
+          @description='(row, index) => string | number. Pass it. A listing sorts, and without a key an index-keyed row loses its identity the moment it does — selection and expansion would follow the position rather than the record.'
+        />
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{this.sizes}}
+          @defaultValue='m'
+          @description='Density. The house scale is xs|s|m|l|xl and it sets the host font-size only, so every internal dimension scales together. sm/md/lg/default/small/medium/large/middle are accepted spellings.'
+          @onInput={{this.setSize}}
+        />
+        <Args.String
+          @name='selectionMode'
+          @value={{this.selectionMode}}
+          @options={{this.modes}}
+          @defaultValue='none'
+          @description="'none', 'single' or 'multi'. multi adds a header select-all whose mixed state is a real indeterminate checkbox, so it announces aria-checked mixed. Every selected tr carries aria-selected as well as data-selected."
+          @onInput={{this.setSelectionMode}}
+        />
+        <Args.Bool
+          @name='pinFirst (demo knob)'
+          @value={{this.pinFirst}}
+          @defaultValue={{false}}
+          @description='Pins the Lot column with pin start. A pinned column must declare a width — offsets are summed from declared widths, never measured — and a pinned column whose predecessors are unmeasurable is left unpinned rather than laid on top of one. Narrow the artboard to see it hold.'
+          @onInput={{this.setPinFirst}}
+        />
+        <Args.Bool
+          @name='striped'
+          @value={{this.striped}}
+          @defaultValue={{true}}
+          @description='Zebra rows. Pinned cells take the row’s computed background, so striping, hover and selection all survive the pin.'
+          @onInput={{this.setStriped}}
+        />
+        <Args.Number
+          @name='pageSize'
+          @value={{this.pageSize}}
+          @min={{0}}
+          @max={{12}}
+          @step={{1}}
+          @defaultValue={{0}}
+          @description='Rows per page. 0 renders every row and no pager. Paging composes the kit’s Pagination; page / defaultPage / onPageChange drive it, and a filter change resets to page 1 because it is the only page guaranteed to exist in the new result set.'
+          @onInput={{this.setPageSize}}
+        />
+        <Args.Bool
+          @name='expanded block (demo knob)'
+          @value={{this.showDetail}}
+          @defaultValue={{true}}
+          @description='Supplying the expanded named block turns on the expander column. Each toggle is a real button with aria-expanded and aria-controls pointing at the detail row.'
+          @onInput={{this.setShowDetail}}
+        />
+        <Args.Object
+          @name='sort'
+          @description='Controlled sort ({ key, dir } or null); defaultSort seeds the uncontrolled case. Clicking a header cycles ascending → descending → unsorted, and aria-sort on the th follows. Every SORTABLE column carries aria-sort, none when it is not the active one, so the header row says which columns can be sorted as well as which one is.'
+        />
+        <Args.Object
+          @name='filters'
+          @description='Controlled filter state keyed by column: a string for a text filter, an array of values for an options filter. defaultFilters seeds it, onFiltersChange reports it, and a column filter’s own match(row, value) replaces the built-in matcher for dates, ranges or nested paths.'
+        />
+        <Args.Object
+          @name='visibleColumns'
+          @description='Controlled column visibility — the keys that are SHOWN. defaultVisibleColumns seeds it (every column without hidden), onVisibleColumnsChange reports it, and the Columns menu drives it. A column marked alwaysVisible never leaves.'
+        />
+        <Args.Object
+          @name='expandedKeys'
+          @description='Controlled expansion (array of row keys). defaultExpandedKeys seeds it; onExpandedChange reports it.'
+        />
+        <Args.String
+          @name='caption / label'
+          @description='caption renders a real table caption; label names the scroll region when there should be no visible caption. The scroll box is a named region with a tab stop, so a table wider than its pane can be scrolled from the keyboard — MUI, Tremor and shadcn all ship that box with neither.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='minWidth'
+          @description='The width at which the table starts scrolling instead of squeezing. Mantine’s ScrollContainer requires this and is right to: a table with no floor silently crushes its columns to unreadable slivers.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @description='Named blocks: cell (text, row, col) where text is the printed value and row is your own fully typed record — a caller should never have to narrow unknown inside a template; expanded (row) for the detail row; actions (row) for the row menu; toolbar for extra toolbar content; and loading / empty / error, which replace DataShell’s defaults. The filtered-empty state is separate from empty — it means your filters matched nothing and it offers a way out.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .dt-demo {
+        display: grid;
+        gap: var(--space-4, 11px);
+        min-width: 0;
+      }
+      .dt-readout {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--space-4, 11px);
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .dt-readout strong {
+        color: var(--foreground);
+        font-weight: 500;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_DATA_TABLE: Record<string, unknown> = {
+  DataTable: DataTableUsage,
+};

package/bundled-realms/pretui/components/date-picker.gts

@@ -0,0 +1,98 @@
+// Pretui — DatePicker: an Input trigger opening a single-date Calendar.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import { Input } from './input';
+import { Popover } from './popover';
+import { Calendar } from './calendar';
+import { DISPLAY_FMT, fromIso } from '../internal/reading-extras';
+
+// ── DatePicker ───────────────────────────────────────────────────────────
+// Single-date input: readonly Pretui Input trigger + Popover around a
+// single-mode Calendar (the popover renders its content only while open, so
+// the calendar re-derives its view from @value on every open).
+export interface DatePickerSignature {
+  Args: {
+    value?: string; // ISO yyyy-mm-dd (controlled)
+    defaultValue?: string; // ISO yyyy-mm-dd (uncontrolled seed)
+    disabled?: boolean;
+    onValueChange?: (iso: string) => void;
+  };
+  Element: HTMLSpanElement;
+}
+
+export class DatePicker extends Component<DatePickerSignature> {
+  @tracked internal: string | undefined = this.args.defaultValue;
+
+  get selectedIso(): string | undefined {
+    return this.args.value ?? this.internal;
+  }
+  get display(): string {
+    let iso = this.selectedIso;
+    if (!iso) {
+      return '';
+    }
+    let d = fromIso(iso);
+    return d ? DISPLAY_FMT.format(d) : iso;
+  }
+  onTriggerKey = (open: boolean, toggle: () => void, e: Event) => {
+    let key = (e as KeyboardEvent).key;
+    if (!open && (key === 'Enter' || key === ' ' || key === 'ArrowDown')) {
+      e.preventDefault();
+      toggle();
+    }
+  };
+  pick = (close: () => void, iso: string) => {
+    this.internal = iso;
+    this.args.onValueChange?.(iso);
+    close();
+  };
+
+  <template>
+    <span class='pretui-datepicker' data-test-pretui-date-picker ...attributes>
+      <Popover @placement='bottom-start' @label='Choose date'>
+        <:trigger as |open toggle|>
+          <Input
+            @value={{this.display}}
+            @placeholder='Select date'
+            @disabled={{@disabled}}
+            class='pretui-datepicker-trigger'
+            readonly
+            aria-haspopup='dialog'
+            aria-expanded={{if open 'true' 'false'}}
+            {{on 'click' toggle}}
+            {{on 'keydown' (fn this.onTriggerKey open toggle)}}
+          />
+        </:trigger>
+        <:default as |close|>
+          <Calendar
+            @value={{this.selectedIso}}
+            @onValueChange={{fn this.pick close}}
+          />
+        </:default>
+      </Popover>
+    </span>
+    <style scoped>
+      /* above Input's layer, so these win by layer order, not file order */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        .pretui-datepicker {
+          display: inline-block;
+        }
+        .pretui-datepicker-trigger {
+          min-width: 150px;
+          cursor: pointer;
+        }
+        /* the Calendar root is an inline-size container (its width comes from
+           the parent), so the panel takes the one-month width explicitly:
+           7 × 30px cells + 6 × 2px gaps + panel padding. Sized through
+           Popover's own custom-property knobs (they inherit — no :deep()). */
+        .pretui-datepicker {
+          --pretui-popover-width: calc(222px + 2 * var(--space-4, 11px));
+          --pretui-popover-min-width: 0;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/date-picker.md

@@ -0,0 +1,59 @@
+## What it is
+
+A date field: a Pretui **Input** as the trigger, a **Popover** holding a single-mode **Calendar**. Use it wherever a single date is collected. For a start/end pair, **DateRangePicker** — do not compose two of these, because a range needs the prospective-span preview that only range mode gives. For a time of day, **TimeInput**. For a relative timestamp you are displaying rather than collecting, **RelativeTime**.
+
+## The contract
+
+```
+@value? (ISO yyyy-mm-dd), @defaultValue?, @onValueChange?(iso), @disabled?
+```
+
+Four args, and the shortness is the thing to notice — see the gaps below.
+
+ISO `yyyy-mm-dd` strings at the boundary, matching **Calendar** — which means the value a form stores is the value the component speaks, with no parsing step and no timezone in play.
+
+**It is a composition, not a new implementation.** The trigger is the kit's **Input** so it matches every other field in a form pixel for pixel; the surface is the kit's **Popover** so it inherits light-dismiss, Escape and the anchored positioning; the grid is the kit's one **Calendar**. Nothing here re-implements date logic. That is the whole design, and it is why fixing a bug in Calendar fixes it in both date controls at once.
+
+**The trigger opens on Enter, Space or ArrowDown** — the standard combobox-style opening keys — which is a genuine addition over the underlying Popover, whose trigger is otherwise pointer-only.
+
+## Prior art
+
+**React Spectrum `DatePicker`** is the reference: a _segmented_ field (each of day/month/year is its own `role="spinbutton"` with `aria-valuetext`) plus a calendar popover, with `granularity`, `minValue`/`maxValue`, `isDateUnavailable` and full internationalisation through `@internationalized/date`. **Web Awesome** ships no date picker. **shadcn** composes Popover + react-day-picker + a Button trigger.
+
+Where Pretui sits: closer to shadcn's composition than to Spectrum's segmented field, and honestly so. The improvement over the shadcn recipe is that **the trigger is a real text input** rather than a button showing formatted text — so the value is visible, selectable, and copyable — and that everything is kit components rather than an assembly of three libraries.
+
+The improvement over Spectrum, such as it is: much less machinery. The cost is everything Spectrum's machinery buys — no locale support (the formatters are hard-coded `en-US`), no granularity, no unavailable-dates predicate, no time component.
+
+**It also has no date bounds and no placeholder**, which **DateRangePicker** does have: that component takes min and max dates, this one takes four args and none of them constrain the value. A single date that must fall inside a window has to be validated by the form around it.
+
+**The segmented-field question is the interesting trade.** Spectrum's approach — three spinbuttons — is more accessible for keyboard entry and much better for screen readers, because each segment announces its own value and steps independently. A single text input is simpler and lets a user paste a date. Pretui chose the input; that is defensible, and it does mean typed entry has no parsing feedback (see below).
+
+## Accessibility
+
+Governing pattern: APG's **datepicker dialog** — a trigger with `aria-haspopup="dialog"` and `aria-expanded`, a modal or non-modal dialog containing the grid, focus into the dialog on open and back to the trigger on close.
+
+What is right: `aria-haspopup="dialog"` and `aria-expanded` are both present on the trigger — which is more than **Menu** or **Popover** do in this kit, and worth noting as the right pattern the others should copy. Enter/Space/ArrowDown open.
+
+Gaps, and they stack:
+
+- **The Popover's own gaps are inherited.** Focus is not moved into the panel on open and not restored to the trigger on close, and **Escape only works once focus is already inside the panel** — so opening the calendar with the keyboard and pressing Escape does nothing. For a date picker that is a genuine trap: the user has opened a surface they cannot dismiss without tabbing into it first.
+- **All of Calendar's keyboard gaps apply**: Arrow keys only, no Home/End, no Page Up/Down for month, no Shift+Page for year, and no live-region announcement of month changes.
+- **Typed input is not validated or parsed against the calendar.** The trigger is an `Input`; what happens when a user types "next tuesday" or "3/4/26" into it is unspecified by the component, and there is no `aria-invalid`, no error message, and no format hint. **WCAG 3.3.2** wants the expected format stated — use **FormField**'s `@description`.
+- **No accessible name of its own, and no `controlId` arg to wire one.** Unlike **Input**, this component does not accept an id for a wrapper's `<label for>`, so outside a labelling wrapper the name has to arrive as an `aria-label` through `...attributes`.
+- **The selected date is not announced on selection** — the popover closes and the input's value changes silently.
+- **`@disabled` uses the native attribute**, removing the trigger from the tab order.
+- Because Popover renders in place with a `position: fixed` panel, an `overflow: hidden` ancestor can still clip it in some layouts — and the Calendar needs an explicit width from its host, so a mis-sized popover is the first thing to check when the grid renders squashed.
+
+## Theming
+
+Trigger: **Input**'s tokens (`--field`, `--input`, `--primary` via `--ring`, `--ink-3`, `--control-h`, `--radius`, `--text-ui-md`). Surface: **Popover**'s (`--popover`, `--popover-foreground`, `--pretui-shadow-overlay`, and the `--pretui-popover-*` sizing knobs — which is where you set the calendar's width). Grid: **Calendar**'s day-state tokens.
+
+Three components' token sets, no tokens of its own — which is the intended shape. The one thing a theme must do here that it does not have to do elsewhere is **set `--pretui-popover-width` or `--pretui-popover-min-width` wide enough for a month grid**, since Calendar's inline-size containment means it takes its width from the panel rather than pushing the panel open.
+
+The styles sit in `@layer PretComposite`, above Input's `PretComponent` layer, so what this component sets on Input wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.
+
+## React ecosystem
+
+Date only (DateField, `YYYY-MM-DD`, no `T`). Date+time is
+**DateTimePicker**. Range is **DateRangePicker**. Permissive birthday
+is **KnownDate**. Accept `onChange` / `isDisabled` / `min` / `max`.