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

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

@@ -0,0 +1,58 @@
+## What it is
+
+Figures in sections, with subtotals and totals, set the way an accountant sets them: a profit and loss, a trial balance, an aging, a budget against actuals. Use it wherever rows of money close with a subtotal and a total. For a record listing with sorting, filtering and selection use **DataTable**; for a plain grid of text with no opinion about figures use **Table**. For one headline figure use **Stat**.
+
+## The contract
+
+```
+@columns, @rows
+@label? | @labelledBy? | @caption? (or <:caption>)
+@currency? ('USD'), @locale?, @negative? ('parentheses' | 'minus'), @zero? ('blank' | 'dash' | 'show')
+@density? ('regular' | 'compact'), @framed? (true)
+@onRowSelect?, @selectColumn?
+@expanded?, @defaultExpanded?, @onExpandedChange?, @expandLabel?
+@emptyTitle?, @emptyMessage? (or <:empty>)
+<:cell> for a column of kind 'custom'
+```
+
+A column has a `key`, a `label` and a `kind`: `text`, `code` (mono), `amount`, `number`, `percent`, `quantity` or `custom`. A row has a `key`, a `role` (`line`, `heading`, `subtotal`, `total`), an optional `depth`, its `cells` by column key, optional `data` hooks and optional `children`.
+
+Four decisions worth understanding.
+
+**The caller hands over numbers, never formatted strings.** An amount column holds minor units (cents by default; `scale` says otherwise, so a percent can be held in basis points and a quantity in thousandths). Every figure is set by **FormatNumber**, so the table can't print a value two ways, and a column stays a column of figures a test can read.
+
+**A row says what it is, not how it looks.** Rules, weight and indentation follow from `role`: a rule over each subtotal, a rule over the total and a double rule under it. Every statement in an app reads the same, and a caller can't hand-style a total that disagrees with the others. Totals are marked by weight and rules, never by colour.
+
+**Negatives are parentheses for the eye and "minus" for the ear.** `@negative='parentheses'` (the default) sets the accounting sign, and a visually hidden copy of the value is what a screen reader hears. A column with `sign: 'change'` always shows its sign (+$120.00, −$80.00), for variances and deltas.
+
+**A row can open where it is read.** `children` (an account's months, its sub-accounts, its postings) sit behind a real disclosure button, controlled through `@expanded` or left to the table through `@defaultExpanded`. A child's key is `parentKey/childKey`.
+
+`data` puts `data-*` attributes on a row (camelCase keys become kebab-case; `true` is a bare attribute; null, undefined and false are left off), so a statement can be checked figure by figure without scraping its formatted text. A column with `priority: 'secondary'` folds away when the table, not the viewport, is narrower than 40rem.
+
+## Prior art
+
+The model is the spreadsheet's accounting number format and the hand-set report tables every finance product writes for itself: QuickBooks' and Xero's reports, and the statement layouts of annual accounts. General-purpose data grids (AG Grid, MUI DataGrid, TanStack Table) handle expandable tree rows and aggregation well but leave the accountant's conventions to the caller: the double rule, the parentheses, blank zeros, cents.
+
+Where this one earns its place:
+
+- **Figures in, typography out.** Grids take strings or renderers; this takes cents and a column kind, and the format is the kit's.
+- **Row roles instead of row styles.** A total is a total wherever it appears.
+- **The meaning survives without the typography.** Parentheses are spoken as "minus", disclosure state is `aria-expanded`, and totals are named by their row header.
+
+Where it is thin: no sorting, no column resizing, no virtualisation (a statement is short), and no multi-currency column (one `@currency` per table).
+
+## Accessibility
+
+A real `<table>`, governed by WCAG **1.3.1**.
+
+- Column headers are `<th scope='col'>`. A heading row's cell is `<th scope='rowgroup'>` spanning the table; a subtotal or total leads with `<th scope='row'>`, so its figures are announced with their name.
+- The table is named by `@caption` (a real `<caption>`), `@label` or `@labelledBy`. A named table's scroll region is a focusable `role='region'` with the same name, so a keyboard user can scroll a wide statement.
+- A row with children carries a `Button` with `aria-expanded` and `aria-controls` naming its child rows; the glyph follows the state.
+- With `@onRowSelect`, each line's select cell is a link-styled `Button`, reachable by Tab.
+- With no rows, **EmptyState** replaces the table, rather than leaving an empty grid.
+
+## Theming
+
+`--pretui-statement-max-height` caps the scroll region's height (default none), and the header row stays in view as it scrolls. Otherwise the table reads the theme: `--card` and `--card-foreground` for the frame, `--border` for line rules, `--inset` and `--border-strong` for the header band, `--foreground` for subtotal and total rules, `--muted-foreground` for headings and captions, `--hover` for the line under the pointer, `--ring` for focus, and `--font-mono` for the header and code columns. Figures use tabular numerals in the body font.
+
+The styles sit in `@layer PretComponent`, and the disclosure button's restyling in `@layer PretComposite`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,252 @@
+// Pretui — StatementTable usage page: live example, a knob for every arg, and the API table.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { StatementTable } from './statement-table';
+import type {
+  StatementColumn,
+  StatementRow,
+  StatementTableSignature,
+} from './statement-table';
+
+// A tea house's quarter, in cents, the way the books hold it.
+export const TEA_HOUSE_COLUMNS: StatementColumn[] = [
+  { key: 'code', label: 'No.', kind: 'code', width: '4.5rem' },
+  { key: 'name', label: 'Account' },
+  { key: 'q1', label: 'Q1', kind: 'amount' },
+  { key: 'q2', label: 'Q2', kind: 'amount', priority: 'secondary' },
+];
+export const TEA_HOUSE_ROWS: StatementRow[] = [
+  { key: 'h-income', role: 'heading', cells: { code: 'Income' } },
+  {
+    key: '4000',
+    depth: 1,
+    cells: { code: '4000', name: 'Loose-leaf sales', q1: 4812000, q2: 5126500 },
+    data: { row: true, key: '4000' },
+    children: [
+      {
+        key: 'online',
+        cells: { name: 'Online orders', q1: 2950000, q2: 3180500 },
+      },
+      {
+        key: 'counter',
+        cells: { name: 'Shop counter', q1: 1862000, q2: 1946000 },
+      },
+    ],
+  },
+  {
+    key: '4100',
+    depth: 1,
+    cells: { code: '4100', name: 'Tasting room', q1: 1960000, q2: 2240000 },
+    data: { row: true, key: '4100' },
+  },
+  {
+    key: 't-income',
+    role: 'subtotal',
+    cells: { name: 'Total income', q1: 6772000, q2: 7366500 },
+  },
+  { key: 'h-cogs', role: 'heading', cells: { code: 'Cost of goods sold' } },
+  {
+    key: '5000',
+    depth: 1,
+    cells: { code: '5000', name: 'Leaf purchases', q1: 2830000, q2: 3012000 },
+    data: { row: true, key: '5000' },
+  },
+  {
+    key: '5200',
+    depth: 1,
+    cells: { code: '5200', name: 'Stock count adjustment', q1: 0, q2: -45000 },
+    data: { row: true, key: '5200' },
+  },
+  {
+    key: 't-cogs',
+    role: 'subtotal',
+    cells: { name: 'Total cost of goods sold', q1: 2830000, q2: 2967000 },
+  },
+  {
+    key: 'gross',
+    role: 'subtotal',
+    cells: { name: 'Gross profit', q1: 3942000, q2: 4399500 },
+  },
+  { key: 'h-exp', role: 'heading', cells: { code: 'Expenses' } },
+  {
+    key: '6200',
+    depth: 1,
+    cells: {
+      code: '6200',
+      name: 'Rent — tasting room',
+      q1: 1800000,
+      q2: 1800000,
+    },
+    data: { row: true, key: '6200' },
+  },
+  {
+    key: '6400',
+    depth: 1,
+    cells: { code: '6400', name: 'Wages', q1: 2310000, q2: 2390000 },
+    data: { row: true, key: '6400' },
+  },
+  {
+    key: 't-exp',
+    role: 'subtotal',
+    cells: { name: 'Total expenses', q1: 4110000, q2: 4190000 },
+  },
+  {
+    key: 'net',
+    role: 'total',
+    cells: { name: 'Net income', q1: -168000, q2: 209500 },
+  },
+];
+
+const NEGATIVES = ['parentheses', 'minus'];
+const ZEROS = ['blank', 'dash', 'show'];
+const DENSITIES = ['regular', 'compact'];
+
+// The source line the usage page shows: a string, so its braces are text, not template.
+const SOURCE =
+  '<StatementTable @label="Profit and loss" @columns={{this.columns}} @rows={{this.rows}} />';
+
+class StatementTableUsage extends Component {
+  columns = TEA_HOUSE_COLUMNS;
+  rows = TEA_HOUSE_ROWS;
+  @tracked negative: StatementTableSignature['Args']['negative'] =
+    'parentheses';
+  @tracked zero: StatementTableSignature['Args']['zero'] = 'blank';
+  @tracked density: StatementTableSignature['Args']['density'] = 'regular';
+  @tracked framed = true;
+  @tracked drill = false;
+  @tracked opened = '';
+  setNegative = (v: string) =>
+    (this.negative = v as StatementTableSignature['Args']['negative']);
+  setZero = (v: string) =>
+    (this.zero = v as StatementTableSignature['Args']['zero']);
+  setDensity = (v: string) =>
+    (this.density = v as StatementTableSignature['Args']['density']);
+  setFramed = (v: boolean) => (this.framed = v);
+  setDrill = (v: boolean) => (this.drill = v);
+  open = (row: StatementRow) =>
+    (this.opened = String(row.cells['name'] ?? row.key));
+  get onRowSelect() {
+    return this.drill ? this.open : undefined;
+  }
+  <template>
+    <FreestyleUsage
+      @name='StatementTable'
+      @description='Figures in sections, with subtotals and totals, set the way an accountant sets them: amounts held in cents, negatives in parentheses, zero blank, a rule over each subtotal and a double rule under the total. Rows say what they are; the table decides how they look. A row with children opens in place (4000 opens to its two channels).'
+      @source={{SOURCE}}
+      @viewportMode='wide'
+    >
+      <:example>
+        <StatementTable
+          @label='Tea house profit and loss'
+          @columns={{this.columns}}
+          @rows={{this.rows}}
+          @negative={{this.negative}}
+          @zero={{this.zero}}
+          @density={{this.density}}
+          @framed={{this.framed}}
+          @onRowSelect={{this.onRowSelect}}
+        />
+        {{#if this.opened}}<p>Opened: {{this.opened}}</p>{{/if}}
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='columns'
+          @value={{this.columns}}
+          @description='StatementColumn[]: key, label, kind (text, code, amount, number, percent, quantity, custom), scale, sign, whole, digits, priority, width.'
+        />
+        <Args.Object
+          @name='rows'
+          @value={{this.rows}}
+          @description='StatementRow[]: key, role (line, heading, subtotal, total), depth 0–3, cells by column key, and data for test hooks on the row.'
+        />
+        <Args.String
+          @name='label'
+          @defaultValue=''
+          @description='The name when it is nowhere on screen. Names the table, and makes its scroll box a reachable region.'
+        />
+        <Args.String
+          @name='caption'
+          @defaultValue=''
+          @description='A visible name, rendered as a real caption. Wins over label and labelledBy.'
+        />
+        <Args.String
+          @name='currency'
+          @defaultValue='USD'
+          @description='ISO 4217 code for amount columns.'
+        />
+        <Args.String
+          @name='negative'
+          @value={{this.negative}}
+          @options={{NEGATIVES}}
+          @defaultValue='parentheses'
+          @description='How a negative balance is set. A column with sign change always shows its sign instead.'
+          @onInput={{this.setNegative}}
+        />
+        <Args.String
+          @name='zero'
+          @value={{this.zero}}
+          @options={{ZEROS}}
+          @defaultValue='blank'
+          @description='How a zero amount is set: blank as on a printed statement, a dash, or $0.00.'
+          @onInput={{this.setZero}}
+        />
+        <Args.String
+          @name='density'
+          @value={{this.density}}
+          @options={{DENSITIES}}
+          @defaultValue='regular'
+          @description='Compact takes the xs type size and tighter rows.'
+          @onInput={{this.setDensity}}
+        />
+        <Args.Bool
+          @name='framed'
+          @value={{this.framed}}
+          @defaultValue={{true}}
+          @description='Off drops the frame, for a table seated in a panel.'
+          @onInput={{this.setFramed}}
+        />
+        <Args.Bool
+          @name='onRowSelect (demo knob)'
+          @value={{this.drill}}
+          @defaultValue={{false}}
+          @description='A callback makes each line’s select column a link-style Button that hands back the row. Headings, subtotals and totals never drill.'
+          @onInput={{this.setDrill}}
+        />
+        <Args.Action @name='onRowSelect' @description='(row) => void.' />
+        <Args.String
+          @name='selectColumn'
+          @description='The column that carries the drill-in. Defaults to the first.'
+        />
+        <Args.Object
+          @name='expanded'
+          @description='The keys of the expanded rows, controlled. A child’s key is parentKey/childKey. Omit it and the table keeps its own (seeded by defaultExpanded).'
+        />
+        <Args.Action
+          @name='onExpandedChange'
+          @description='(keys) => void, when a row is opened or closed: the new set of expanded keys.'
+        />
+        <Args.Action
+          @name='expandLabel'
+          @description='(row) => string: the disclosure button’s name, e.g. “Show Loose-leaf sales by channel”.'
+        />
+        <Args.Yield
+          @name='cell'
+          @description='(value, row, column) for every column of kind custom: a status chip, a link, an icon.'
+        />
+        <Args.Yield
+          @name='caption'
+          @description='A rich caption. Wins over @caption.'
+        />
+        <Args.Yield
+          @name='empty'
+          @description='Replaces the empty state when there are no rows.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_STATEMENT_TABLE: Record<string, unknown> = {
+  StatementTable: StatementTableUsage,
+};

package/bundled-realms/pretui/components/status-chip.gts

@@ -0,0 +1,37 @@
+// Pretui — StatusChip: a Chip whose hue is derived from its status value, stable across cards.
+import Component from '@glimmer/component';
+import { Chip } from './chip';
+import { statusHue } from '../internal/ink';
+import {
+  PRETUI_TONES,
+  resolveTone,
+  type PretuiToneArg,
+} from '../pretui-primitives';
+
+export interface StatusChipSignature {
+  Args: { value: string; hue?: string; tone?: PretuiToneArg };
+  Element: HTMLSpanElement;
+}
+
+// A chip whose hue derives from the status VALUE — caller override is the exception.
+export class StatusChip extends Component<StatusChipSignature> {
+  get hue() {
+    return this.args.hue ?? statusHue(this.args.value);
+  }
+  // a toned chip's dot takes its tone unless @hue says otherwise; neutral,
+  // passed or defaulted, keeps the status hue
+  get dotHue() {
+    return resolveTone(this.args.tone, PRETUI_TONES, 'neutral') === 'neutral'
+      ? this.hue
+      : this.args.hue;
+  }
+  <template>
+    <Chip
+      @label={{@value}}
+      @hue={{this.dotHue}}
+      @tone={{@tone}}
+      data-test-pretui-status-chip
+      ...attributes
+    />
+  </template>
+}

package/bundled-realms/pretui/components/status-chip.md

@@ -0,0 +1,48 @@
+## What it is
+
+A **Chip** whose color is derived from the value rather than chosen. Pass `@value='In Review'` and you get a chip whose hue is a stable hash of that string — the same status is the same color on every card, in every list, in every realm, without anyone maintaining a status-to-color map. Use it for any enumerable state field. If you want to choose the color, use **Chip** directly (or pass `@hue` here — the escape exists, but it is meant to be the exception). If the value filters a list, **FilterChips**. If it is a machine value, **Token**.
+
+## The contract
+
+```
+@value: string   (required)
+@hue?            — override; the exception, not the norm
+@tone?           — Chip's tone (default neutral)
+```
+
+Three args, and the last two you should rarely reach for. A toned StatusChip is outlined in that tone and its dot takes the tone unless `@hue` is passed, so `@tone` is for a status whose meaning is fixed, like `live`; the hash hue stays on a neutral chip.
+
+**The hue is a hash, and the hash is the point.** `statusHue()` runs a 32-bit polynomial rolling hash (`h * 31 + charCode`, unsigned) over the string and takes `h % 5` to index `--chart-1` … `--chart-5`. Deterministic, dependency-free, and — the property that matters — **stable across cards, realms and sessions**. No registry, no config, no design review to add a status.
+
+The corollary worth stating plainly: **the hue carries no semantics.** "Failed" is not red because it means failure; it is whatever color its characters hash to. Five buckets also means collisions are common — with six statuses, two will share a color. If your states have meaning that must be conveyed by color (error/warning/success), **the hash is the wrong tool** — pass a `@tone` (StatusChip takes one for a fixed status like `live`, **Chip** for anything else), or use **Alert**.
+
+## Prior art
+
+Nobody else does this, which is either the interesting part or the suspicious part depending on your view.
+
+**Web Awesome `wa-tag`**, **shadcn `Badge`** and **React Spectrum `Badge`** all take a `variant` from a closed semantic enum, and every product using them maintains a `statusColors` map somewhere. **Linear**, **GitHub** and **Jira** all store the color on the status entity — the color is data, chosen by a human, persisted alongside the label.
+
+Pretui's bet is different: in a system where cards are authored quickly and a status field's values are whatever an author typed, there is no entity to hang a color on and no one to choose it. A stable hash gives _consistency_ for free, which is the property that actually makes a list scannable — you learn "green-ish means In Review" within a page, and it stays true everywhere.
+
+Where that bet is better than the alternatives: zero configuration, zero drift, and it works for values the system has never seen. Where it is worse, and it is worth being blunt: **five buckets is a small palette**, collisions are frequent and invisible, and the color will occasionally be actively misleading — a hash that paints "Cancelled" green is not a bug you can fix without the `@hue` escape. Neither Web Awesome nor Spectrum has that failure mode.
+
+The pragmatic guidance: use StatusChip for open-ended categorical fields, and a `@tone` for anything where the color is load-bearing.
+
+## Accessibility
+
+No APG pattern; it is text with a background and carries no role — correct.
+
+Everything **Chip** says applies, and one thing more, which is the important one:
+
+- **Color conveys nothing here, and that is a feature.** Because the hue is a hash, it is _not_ meaningful, so a user who cannot perceive it loses nothing that the label does not already carry. That makes StatusChip trivially **WCAG 1.4.1** compliant in a way that a semantic-color chip is not — the label is always the message.
+- **Contrast does not depend on the hue** (with Chip's legacy mix knobs unset). The text is Chip's `--foreground` on `--muted` (or a tone's `-ink` on `--card`), at **11px, weight 500**; the hash hue only colors the dot, so no `--chart-*` value can make the label illegible.
+- **The dot inherits from Chip and is on by default**, giving each hue a saturated anchor. Since the hues are arbitrary, the dot is doing less work here than it does on a semantic Chip — but it still helps distinguish adjacent chips whose fills are close.
+- **The chip has no relationship to the field it describes.** "In Review" announced next to a record name is loose text; put it in a **KeyValue** row or a **FormField** static block if the property name matters.
+- **No `aria-label` and no title.** The value is the visible text and the accessible text, which is right.
+- Nothing is focusable.
+
+## Theming
+
+Inherits **Chip**'s entire token set; `--pretui-chip-hue` is set here from the hash on a neutral chip, or from `@hue`.
+
+The theme's `--chart-1` through `--chart-5` color the dots, and this component is the reason those five need to work as a _set_: they appear side by side in a list, assigned arbitrarily, so they must be mutually distinguishable as small dots on `--muted`.

package/bundled-realms/pretui/components/status-chip.usage.gts

@@ -0,0 +1,36 @@
+// Pretui — StatusChip usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { StatusChip } from './status-chip';
+
+class StatusChipUsage extends GlimmerComponent {
+  @tracked value = 'in progress';
+  setValue = (v: string) => (this.value = v);
+  <template>
+    <FreestyleUsage
+      @name='StatusChip'
+      @description='A Chip whose hue is derived by hashing the value — same value, same color, every card, no configuration. Type any status below and watch it keep a stable hue.'
+    >
+      <:example>
+        <StatusChip @value={{this.value}} />
+        <StatusChip @value='overdue' />
+        <StatusChip @value='review' />
+        <StatusChip @value='active' />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @required={{true}}
+          @description='The status text; its hash picks one of the five chart hues deterministically.'
+          @onInput={{this.setValue}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_STATUS_CHIP: Record<string, unknown> = {
+  StatusChip: StatusChipUsage,
+};