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

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

@@ -0,0 +1,73 @@
+// Pretui — Badge usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Badge } from './badge';
+import { Avatar } from './avatar';
+import { IconButton } from './icon-button';
+
+const PLACEMENTS = ['top-end', 'top-start', 'bottom-end', 'bottom-start'];
+
+export class BadgeUsage extends Component {
+  placements = PLACEMENTS;
+  @tracked count = 3;
+  @tracked max = 99;
+  @tracked dot = false;
+  @tracked showZero = false;
+  @tracked placement = 'top-end';
+  setCount = (v: number | null) => (this.count = v ?? 0);
+  setMax = (v: number | null) => (this.max = v ?? 99);
+  setDot = (v: boolean) => (this.dot = v);
+  setShowZero = (v: boolean) => (this.showZero = v);
+  setPlacement = (v: string) => (this.placement = v);
+  get usage() {
+    let bits = [`@count={{${this.count}}}`, "@label='unread'"];
+    if (this.max !== 99) bits.push(`@max={{${this.max}}}`);
+    if (this.dot) bits.push('@dot={{true}}');
+    if (this.showZero) bits.push('@showZero={{true}}');
+    if (this.placement !== 'top-end') bits.push(`@placement='${this.placement}'`);
+    return `<Badge ${bits.join(' ')}>\n  <IconButton @label='Messages'>…</IconButton>\n</Badge>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Badge'
+      @description='A count or status mark on the corner of another control: the unread 3 on an inbox button, 99+ on an avatar. The mark is hidden from assistive technology and the meaning is spoken after the child, so the child keeps its own name. The inline pill shadcn calls Badge is Chip; a dot with no number is Indicator.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='bd-demo'>
+          <Badge @count={{this.count}} @max={{this.max}} @dot={{this.dot}} @showZero={{this.showZero}} @placement={{this.placement}} @label='unread'>
+            <IconButton @label='Messages'>✉</IconButton>
+          </Badge>
+          <Badge @count={{128}} @circular={{true}} @label='notifications'>
+            <Avatar @name='Ana Ruiz' />
+          </Badge>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Number @name='count' @value={{this.count}} @onInput={{this.setCount}} />
+        <Args.Number @name='max' @value={{this.max}} @defaultValue={{99}} @description='Above this it reads max+.' @onInput={{this.setMax}} />
+        <Args.Bool @name='dot' @value={{this.dot}} @defaultValue={{false}} @description='A dot instead of the number.' @onInput={{this.setDot}} />
+        <Args.Bool @name='showZero' @value={{this.showZero}} @defaultValue={{false}} @onInput={{this.setShowZero}} />
+        <Args.Bool @name='invisible' @defaultValue={{false}} @description='Hide without unmounting the child.' />
+        <Args.String @name='tone' @defaultValue='danger' />
+        <Args.String @name='placement' @value={{this.placement}} @options={{this.placements}} @defaultValue='top-end' @onInput={{this.setPlacement}} />
+        <Args.Bool @name='circular' @defaultValue={{false}} @description='Pull the mark in for a round child.' />
+        <Args.String @name='label' @value='unread' @description='What the count means, read after it.' />
+        <Args.Yield @name='default' @description='The control the badge sits on.' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .bd-demo {
+        display: flex;
+        align-items: center;
+        gap: var(--space-6, 1.25rem);
+        padding: var(--space-4, 0.6875rem);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_BADGE: Record<string, unknown> = {
+  Badge: BadgeUsage,
+};

package/bundled-realms/pretui/components/bar-list.gts

@@ -0,0 +1,255 @@
+// Pretui — BarList: a ranked list of labelled horizontal bars.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { DataShell, DataSource } from '../data-component';
+import type { DataArgs } from '../data-component';
+import { cssStyleFrom, cssDeclaration } from '../pretui-css';
+import { NUMBERS } from '../internal/structure-chart';
+
+// ── BarList ──────────────────────────────────────────────────────────────
+
+export interface BarListItem {
+  /** Row label. */
+  name: string;
+  /** Magnitude. Negative values are clamped to zero for the bar length. */
+  value: number;
+  /** Optional href — when present the label becomes a link. */
+  href?: string;
+  /** Optional hue override for this row's bar. Validated through `cssValue`. */
+  hue?: string;
+}
+
+export interface BarListArgs extends DataArgs<BarListItem> {
+  /** Sort descending by value before rendering. Default true. */
+  ranked?: boolean;
+  /** Cap the number of rows rendered. The remainder is summarised. */
+  limit?: number;
+  /** Scale the bars against this instead of the largest value — use it to
+   * keep two BarLists comparable side by side. */
+  max?: number;
+  /** Formats the printed value. Defaults to a locale integer. */
+  format?: (value: number) => string;
+  /** Accessible name for the list. */
+  label?: string;
+  /** Row hue. Every bar shares it; per-row `hue` wins. */
+  hue?: string;
+}
+
+export interface BarListSignature {
+  Args: BarListArgs;
+  Blocks: {
+    loading: [];
+    empty: [];
+    error: [];
+  };
+  Element: HTMLDivElement;
+}
+
+interface BarRow {
+  name: string;
+  value: number;
+  display: string;
+  href: string | undefined;
+  style: ReturnType<typeof htmlSafe> | undefined;
+}
+
+/**
+ * The ranked distribution: label, a proportional bar, and the value AS TEXT
+ * on every row. Independently the most-copied dashboard component in the
+ * audit, and a genuine gap in the kit — `Meter` expresses one level, `Chart`
+ * plots a series, and neither answers "which five things are biggest".
+ *
+ * It needs no plotting engine, so it costs a caller nothing at the package
+ * boundary (Law 9): a card that shows a top-five list never loads Plot.
+ *
+ * Better than the inspiration: upstream bar lists render `<div>` rows with
+ * the value in a floated span. Here it is an ordered list — the ranking is
+ * in the markup, not implied by visual order — every row carries
+ * `role=meter`-equivalent text, the bar is `aria-hidden` because the number
+ * beside it already says the same thing, and the bar length is a clamped
+ * NUMBER so no caller string reaches the style attribute unvalidated.
+ */
+export class BarList extends Component<BarListSignature> {
+  data = new DataSource<BarListItem>(() => this.args);
+
+  get ranked(): boolean {
+    return this.args.ranked ?? true;
+  }
+
+  get format(): (value: number) => string {
+    return this.args.format ?? ((value: number) => NUMBERS.format(value));
+  }
+
+  private get ordered(): BarListItem[] {
+    let rows = this.data.visibleRows.slice();
+    if (this.ranked) {
+      rows.sort((a, b) => b.value - a.value);
+    }
+    return rows;
+  }
+
+  get scale(): number {
+    if (this.args.max !== undefined && this.args.max > 0) {
+      return this.args.max;
+    }
+    let top = 0;
+    for (let row of this.ordered) {
+      if (Number.isFinite(row.value) && row.value > top) {
+        top = row.value;
+      }
+    }
+    return top > 0 ? top : 1;
+  }
+
+  get rows(): BarRow[] {
+    let limit =
+      this.args.limit === undefined
+        ? this.ordered.length
+        : Math.max(0, Math.round(this.args.limit));
+    let scale = this.scale;
+    return this.ordered.slice(0, limit).map((row) => {
+      // A clamped number can never carry a semicolon, so the percentage is
+      // safe by construction; the HUE is a caller string and goes through
+      // the kit's allowlist guard instead.
+      let pct = Math.max(0, Math.min(100, (row.value / scale) * 100));
+      return {
+        name: row.name,
+        value: row.value,
+        display: this.format(row.value),
+        href: row.href,
+        style: cssStyleFrom([
+          '--pretui-barlist-fill: ' + pct.toFixed(2) + '%',
+          cssDeclaration('--pretui-barlist-hue', row.hue ?? this.args.hue),
+        ]),
+      };
+    });
+  }
+
+  get remainder(): number {
+    return Math.max(0, this.ordered.length - this.rows.length);
+  }
+
+  <template>
+    <div class='pretui-barlist' data-test-pretui-barlist ...attributes>
+      <DataShell
+        @state={{this.data}}
+        @hasLoading={{has-block 'loading'}}
+        @hasEmpty={{has-block 'empty'}}
+        @hasError={{has-block 'error'}}
+        @emptyTitle='Nothing ranked yet'
+        @emptyMessage='No rows to rank. Once the desk logs something it appears here, largest first.'
+        @skeletonRows={{4}}
+      >
+        <:default>
+          <ol class='pretui-barlist-rows' aria-label={{@label}}>
+            {{#each this.rows key='name' as |row|}}
+              <li class='pretui-barlist-row' style={{row.style}}>
+                {{! The bar is decoration: the number to its right states the
+                    same magnitude, so announcing both would be a stutter. }}
+                <span class='pretui-barlist-bar' aria-hidden='true'></span>
+                <span class='pretui-barlist-name'>
+                  {{#if row.href}}
+                    <a href={{row.href}}>{{row.name}}</a>
+                  {{else}}
+                    {{row.name}}
+                  {{/if}}
+                </span>
+                <span class='pretui-barlist-value'>{{row.display}}</span>
+              </li>
+            {{/each}}
+          </ol>
+          {{#if this.remainder}}
+            <p class='pretui-barlist-more'>
+              {{this.remainder}}
+              more not shown.
+            </p>
+          {{/if}}
+        </:default>
+        <:loading>{{yield to='loading'}}</:loading>
+        <:empty>{{yield to='empty'}}</:empty>
+        <:error>{{yield to='error'}}</:error>
+      </DataShell>
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-barlist {
+          container-type: inline-size;
+          display: block;
+          min-width: 0;
+          font-family: var(--font-sans);
+          color: var(--foreground);
+        }
+        .pretui-barlist-rows {
+          list-style: none;
+          margin: 0;
+          padding: 0;
+          display: grid;
+          gap: var(--pretui-barlist-gap, 3px);
+        }
+        .pretui-barlist-row {
+          position: relative;
+          display: grid;
+          grid-template-columns: 1fr auto;
+          align-items: center;
+          gap: var(--space-3, 8px);
+          min-block-size: var(--pretui-barlist-row-height, 28px);
+          padding: 3px var(--space-3, 8px);
+          border-radius: var(--radius-control, 7px);
+          font-size: var(--text-ui-md, 12.5px);
+        }
+        .pretui-barlist-bar {
+          position: absolute;
+          inset-block: 0;
+          inset-inline-start: 0;
+          inline-size: var(--pretui-barlist-fill, 0%);
+          border-radius: var(--radius-control, 7px);
+          background: color-mix(
+            in oklch,
+            var(--pretui-barlist-hue, var(--chart-2)) 18%,
+            transparent
+          );
+          /* Law 5: the bar grows when the value changes, which encodes the
+             change. It lands on the end state under reduced motion. */
+          transition: inline-size 320ms cubic-bezier(0.23, 1, 0.32, 1);
+        }
+        .pretui-barlist-name {
+          position: relative;
+          min-width: 0;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-barlist-name a {
+          color: inherit;
+          text-decoration-color: color-mix(
+            in oklch,
+            currentColor 40%,
+            transparent
+          );
+        }
+        .pretui-barlist-name a:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+          border-radius: 3px;
+        }
+        .pretui-barlist-value {
+          position: relative;
+          font-variant-numeric: tabular-nums;
+          font-weight: var(--weight-strong, 600);
+          color: var(--muted-foreground);
+        }
+        .pretui-barlist-more {
+          margin: var(--space-3, 8px) 0 0;
+          color: var(--muted-foreground);
+          font-size: var(--text-ui-xs, 11px);
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-barlist-bar {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/bar-list.md

@@ -0,0 +1,49 @@
+## What it is
+
+A ranked list of labelled bars: the "top N by value" list that sits beside a chart rather than in it.
+
+It is a `DataComponent<BarListItem>`, so rows, loading, empty and error states come from that foundation.
+
+## The contract
+
+```
+every DataArgs<BarListItem> arg — @rows or @load, @loadKey, @key, and the rest
+@ranked? — sort descending by value before rendering. Default true
+@limit?  — cap the number of rows rendered; the remainder is summarised
+@max?    — scale the bars against this instead of the largest value
+@format? — formats the printed value. Defaults to a locale integer
+@label?  — accessible name for the list
+@hue?    — row hue; every bar shares it, and a per-row hue wins
+
+<:loading>, <:empty>, <:error>
+```
+
+**`@max` is what keeps two BarLists comparable side by side.** Scaling each list against its own largest value makes two lists look the same shape regardless of magnitude — which is exactly wrong when they are meant to be compared. Pass the same `@max` to both.
+
+**`@limit` summarises the remainder** rather than silently dropping it, so "top 5" does not misrepresent a long tail as nothing.
+
+**`@ranked` defaults to true**, because an unranked bar list is a bar chart with no axis.
+
+## Prior art
+
+The "top N" list in every analytics dashboard, and Tremor's BarList as the closest named equivalent.
+
+Where Pretui is better: `@max` as an explicit comparability lever, the remainder being summarised rather than dropped, and riding **DataComponent** so loading and empty states behave like every other data surface in the kit.
+
+Where it is thinner: no drill-down or row selection, no negative values, no stacked or grouped bars — one value per row — and no inline sparkline.
+
+## Accessibility
+
+- **The rows are an ordered list with an accessible name** from `@label`, which is what conveys rank: a reader is told this is first, second, third.
+- **The bars are `aria-hidden`.** The value is printed as text on every row, so the bar is redundant to anyone not looking at it — and announcing a bar conveys nothing.
+- **The printed value is the data.** `@format` shapes what is announced as well as what is shown.
+- **Rank is conveyed by list order rather than by bar length alone**, which means the ordering survives without sight.
+- **`@hue` is decoration.** Nothing in this component depends on distinguishing one bar's colour from another's.
+
+## Theming
+
+`--pretui-barlist-fill` and `--pretui-barlist-hue` (the bars), `--pretui-barlist-row-height` and `--pretui-barlist-gap` (density), plus `--pretui-chart-key` shared with **Chart**'s legend.
+
+Sharing the chart key token matters when a BarList sits beside a Chart showing the same series: the two should agree on what a given series looks like, and pulling from one token is how that stays true through a theme change.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/bar-list.usage.gts

@@ -0,0 +1,129 @@
+// Pretui — BarList usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { seedFrom } from '../examples';
+import { FreestyleUsage } from './freestyle-usage';
+import { BarList } from './bar-list';
+import type { BarListItem } from './bar-list';
+
+// ── BarList ──────────────────────────────────────────────────────────────
+const REFERRERS: BarListItem[] = [
+  'Direct',
+  'Catalog search',
+  'Assistant suggestion',
+  'Shared link',
+  'Embedded card',
+  'Realm index',
+  'External referral',
+].map((name) => ({
+  name,
+  value: 40 + (seedFrom('referrer#' + name) % 940),
+}));
+
+export class BarListUsage extends Component {
+  @tracked limit = 5;
+  @tracked ranked = true;
+
+  setLimit = (v: number | null) => {
+    this.limit = v ?? 5;
+  };
+  setRanked = (v: boolean) => {
+    this.ranked = v;
+  };
+
+  rows = REFERRERS;
+
+  get usage(): string {
+    return [
+      '<BarList',
+      '  @rows={{this.referrers}}',
+      '  @limit={{' + this.limit + '}}',
+      "  @label='Traffic by source'",
+      '/>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='BarList'
+      @description='The ranked distribution: a label, a proportional bar, and the value as text on every row. It answers "which five things are biggest", which neither Meter (one level) nor Chart (a series) does. No plotting engine — a card that shows a top-five list never loads Plot.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='barlist-stage'>
+          <BarList
+            @rows={{this.rows}}
+            @limit={{this.limit}}
+            @ranked={{this.ranked}}
+            @label='Card opens by traffic source, last 30 days'
+          />
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='rows'
+          @description='BarListItem[] — name, value, and optional href and hue. Accepts @load / @loadKey instead, with the same DataComponent state machine.'
+        />
+        <Args.Bool
+          @name='ranked'
+          @description='Sort descending by value before rendering. Turn it off to keep the caller order — a time-ordered list stays time-ordered.'
+          @defaultValue={{true}}
+          @value={{this.ranked}}
+          @onInput={{this.setRanked}}
+        />
+        <Args.Number
+          @name='limit'
+          @description='Cap the rows rendered. The remainder is reported as a count rather than silently dropped.'
+          @defaultValue={{0}}
+          @min={{1}}
+          @max={{7}}
+          @step={{1}}
+          @value={{this.limit}}
+          @onInput={{this.setLimit}}
+        />
+        <Args.Number
+          @name='max'
+          @description='Scale bars against this instead of the largest value — the way to keep two BarLists comparable side by side.'
+        />
+        <Args.Object
+          @name='format'
+          @description='Formats the printed value. Defaults to a locale number.'
+        />
+        <Args.String
+          @name='hue'
+          @description='Bar hue for every row; a per-row hue wins. Caller strings are validated through the kit cssValue allowlist before they reach the style attribute.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-barlist-row-height'
+          @type='dimension'
+          @description='Minimum row height. Raise it for a touch-first surface.'
+          @defaultValue='28px'
+        />
+        <Css.Basic
+          @name='pretui-barlist-hue'
+          @type='color'
+          @description='Bar fill hue, mixed to 18% against the surface.'
+          @defaultValue='var(--chart-2)'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+
+    <style scoped>
+      .barlist-stage {
+        padding: var(--space-5, 14px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_BAR_LIST: Record<string, unknown> = {
+  BarList: BarListUsage,
+};

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

@@ -0,0 +1,108 @@
+// Pretui — Board: a kanban plane, a thin wrap of boxel-ui KanbanPlane.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { KanbanPlane as BoxelKanbanPlane } from '@cardstack/boxel-ui/components';
+import type { KanbanColumnConfig, KanbanPlacement } from '@cardstack/boxel-ui/components';
+import type { FittedFormatId } from '@cardstack/boxel-ui/helpers';
+
+// ── Board — WRAPS boxel-ui ───────────────────────────────────────────────
+// boxel-ui's KanbanPlane — the newer of its two kanbans, chosen per the
+// matrix ("adopt the newer pure-fn placement engine"): an internally
+// owned drag manager over pure placement functions, configurable columns
+// (KanbanColumnConfig: key/label/color/wipLimit/collapsed/sortOrder),
+// card placements as data (KanbanPlacement: columnId/index/sortOrder), a
+// hidden-columns tray, and per-lane add-card affordances. The consumer
+// renders cards through <:card>/<:ghost> blocks and owns all state —
+// every interaction arrives as a callback. The engine already dresses
+// itself from the semantic tokens (--card, --border, --ring, --primary,
+// --destructive…); the wrapper adds light no-theme fallbacks through the
+// --boxel-kanban-* channel so an unthemed context renders the Pretui
+// light uniform. Column config UI (KanbanColumnConfigSidebar) is a
+// separate boxel-ui component, not part of this wrap.
+//
+// NOT GENERIC, deliberately — the one collection in the kit that keeps a
+// closed row type, and the reason is worth writing down. A KanbanPlacement is
+// `{ columnId, index, sortOrder }`: a POSITION, not a record. The card
+// payload never passes through the board at all — the consumer looks it up by
+// `placement.index` — and boxel-ui's pure placement engine both clones
+// (`placements.map((p) => ({ ...p }))`) and MANUFACTURES placements
+// (`autoPlaceKanban`), so a `T extends KanbanPlacement` yielded from <:card>
+// would be a cast the engine is under no obligation to honour. Typing a lie
+// is worse than typing a position. Grid/Feed/Masonry are generic because
+// their items are the caller's own rows, passed straight through.
+
+export interface BoardSignature {
+  Args: {
+    columns: KanbanColumnConfig[];
+    placements: KanbanPlacement[];
+    /** accessible board label */
+    boardLabel?: string;
+    /** fitted format id for card sizing — 'regular-tile' by default */
+    cardSize?: FittedFormatId;
+    /** move empty columns into the hidden-columns tray */
+    hideEmpty?: boolean;
+    onChange?: (placements: KanbanPlacement[]) => void;
+    onSelect?: (index: number | null) => void;
+    onOpen?: (index: number) => void;
+    onAddCard?: (columnKey: string | null) => void;
+    onToggleCollapsed?: (column: KanbanColumnConfig | null) => void;
+  };
+  Blocks: {
+    card: [KanbanPlacement];
+    ghost: [number];
+  };
+  Element: HTMLDivElement;
+}
+
+export const Board: TemplateOnlyComponent<BoardSignature> = <template>
+  <div class='pretui-board' data-test-pretui-board ...attributes>
+    <BoxelKanbanPlane
+      @boardLabel={{@boardLabel}}
+      @columns={{@columns}}
+      @placements={{@placements}}
+      @cardSize={{@cardSize}}
+      @hideEmpty={{@hideEmpty}}
+      @onChange={{@onChange}}
+      @onSelect={{@onSelect}}
+      @onOpen={{@onOpen}}
+      @onAddCard={{@onAddCard}}
+      @onToggleCollapsed={{@onToggleCollapsed}}
+    >
+      <:card as |placement|>
+        {{yield placement to='card'}}
+      </:card>
+      <:ghost as |dragIndex|>
+        {{yield dragIndex to='ghost'}}
+      </:ghost>
+    </BoxelKanbanPlane>
+  </div>
+  <style scoped>
+    @layer PretComponent {
+      /* The plane fills its host — give the wrapping context a height.
+         Channel values are the Pretui semantic tokens WITH their light
+         fallbacks, so the board holds the light uniform even unthemed
+         (the engine's own defaults lean on bare var(--foreground) etc.,
+         which have no no-theme value). */
+      .pretui-board {
+        height: 100%;
+        min-height: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        letter-spacing: var(--track-ui, 0.01em);
+        color: var(--foreground);
+        --boxel-kanban-fg: var(--foreground, var(--boxel-dark));
+        --boxel-kanban-card-bg: var(--card, var(--boxel-light));
+        --boxel-kanban-card-fg: var(--card-foreground, var(--boxel-dark));
+        --boxel-kanban-col-bg: var(--inset, var(--boxel-100));
+        --boxel-kanban-col-fg: var(--foreground, var(--boxel-dark));
+        --boxel-kanban-ring: var(--primary, var(--boxel-highlight));
+        --boxel-kanban-primary: var(--primary, var(--boxel-highlight));
+        --boxel-kanban-primary-fg: var(--primary-foreground, var(--boxel-dark));
+        --boxel-kanban-destructive: var(--destructive, var(--boxel-danger));
+        --boxel-kanban-destructive-fg: var(--destructive-foreground, var(--boxel-light));
+        --boxel-kanban-muted-fg: var(--muted-foreground, var(--boxel-450));
+        --boxel-kanban-radius: var(--radius, var(--boxel-border-radius));
+        --boxel-kanban-border: var(--border, var(--boxel-border-color));
+        --boxel-kanban-bg: transparent;
+      }
+    }
+  </style>
+</template>;

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

@@ -0,0 +1,54 @@
+## What it is
+
+A kanban board: configurable columns, cards you drag between them, a hidden-columns tray, per-lane add affordances and WIP limits. Reach for it when items move through named states and the movement is the interaction. If the states are a fixed linear process, **StepList** or **Timeline** reads better. If you just want tiles, **Grid**. If the arrangement is spatial and freeform rather than columnar, **NodeCanvas**.
+
+## The contract
+
+```
+@columns: KanbanColumnConfig[]      { key, label, color, wipLimit, collapsed, sortOrder }
+@placements: KanbanPlacement[]      { columnId, index, sortOrder }
+@boardLabel?, @cardSize?, @hideEmpty?
+@onChange?, @onSelect?, @onOpen?, @onAddCard?, @onToggleCollapsed?
+<:card as |placement|>  <:ghost as |dragIndex|>
+```
+
+**The consumer owns all state; every interaction arrives as a callback.** The board never mutates your data — it hands you the next `placements` array and you decide.
+
+**It is deliberately not generic, and the reason is worth reading.** A `KanbanPlacement` is `{ columnId, index, sortOrder }` — a **position, not a record**. The card payload never passes through the board at all; the consumer looks it up by `placement.index`. And boxel-ui's pure placement engine both _clones_ placements (`placements.map(p => ({...p}))`) and _manufactures_ them (`autoPlaceKanban`), so a `T extends KanbanPlacement` yielded from `<:card>` would be a cast the engine is under no obligation to honor. Typing a lie is worse than typing a position. **Grid**, **Feed** and **Masonry** are generic because their items are the caller's own rows passed straight through; Board is the one collection in the kit that keeps a closed row type, and this is why.
+
+`<:ghost>` renders the drag preview, receiving the dragged index.
+
+## Prior art
+
+A **thin runtime wrap of boxel-ui's `KanbanPlane`** — the newer of boxel-ui's two kanbans, chosen per the component matrix as "the pure-fn placement engine". The engine owns a drag manager over pure placement functions, which is the good architecture here: placement is a function of `(placements, from, to)` rather than mutation scattered through drag handlers, so it is testable and undoable.
+
+Against the field: **dnd-kit** and **react-beautiful-dnd** are the reference drag libraries, and neither is a board — you assemble one. **Atlassian's Jira board** is the canonical product. **shadcn**, **Radix**, **Web Awesome** and **React Spectrum** all ship nothing in this space; Spectrum's `dragAndDropHooks` on `ListBox`/`Table` is the closest primitive.
+
+So the honest framing is that this exists because boxel-ui had a board and the kit wanted one cheaply, not because it out-designs a category leader. What it does bring that a dnd-kit assembly does not: WIP limits, a hidden-columns tray and column collapse as first-class config, plus placement-as-data so board state serialises to a card field trivially.
+
+**Column configuration UI is not part of this wrap** — `KanbanColumnConfigSidebar` is a separate boxel-ui component. And the wrapper adds light no-theme fallbacks through the `--boxel-kanban-*` channel, because the engine's own defaults lean on bare `var(--foreground)` and friends, which have no unthemed value.
+
+## Accessibility
+
+This is the component with the largest accessibility surface in the kit and the least of it under Pretui's control. **All behaviour is boxel-ui's KanbanPlane; this wrapper adds no ARIA.** What the engine does today:
+
+- **Keyboard moves.** Space or Enter picks a card up, arrows move it between columns and positions, Space or Enter drops it and Escape cancels, which covers **WCAG 2.1.1 Keyboard**.
+- **Announced drags.** A polite status region speaks each step: "Column 2. Position 3 of 5.", "Card dropped.", "Movement cancelled.".
+- **Structure.** The plane is named by `@boardLabel`, each column carries its label, its body is `role="list"` and every card is a `listitem`.
+- **Gap: no single-pointer alternative.** Moving a card by pointer needs a drag, so **WCAG 2.5.7 Dragging Movements** (AA, 2.2) is not met; a "move to column" control in your `<:card>` block is the usual answer.
+- **Cards need accessible names**, and that is on your `<:card>` block, not the board.
+- **`@hideEmpty` removes columns from the DOM**, which changes the board's structure without announcement.
+
+Pretui-level note: `@boardLabel` is the only accessibility affordance this wrapper exposes. Pass it.
+
+## Theming
+
+Consumed: `--foreground`, `--text-ui-md`, `--track-ui`.
+
+Remapped into the `--boxel-kanban-*` channel, each with an explicit light fallback so the board holds the Pretui light uniform even unthemed: `--boxel-kanban-fg` ← `--foreground`, `-card-bg` ← `--card`, `-card-fg` ← `--card-foreground`, `-col-bg` ← `--inset`, `-col-fg` ← `--foreground`, `-ring` and `-primary` ← `--primary`, `-primary-fg` ← `--primary-foreground`, `-destructive` ← `--destructive`, `-destructive-fg` ← `--destructive-foreground`, `-muted-fg` ← `--muted-foreground`, `-radius` ← `--radius`, `-border` ← `--border`, `-bg` → `transparent`.
+
+**The plane fills its host, so the wrapping context must have a height** — `height: 100%; min-height: 0` on the wrapper means a Board in an auto-height container renders as nothing. That is the first thing to check when it comes up blank.
+
+Column colors come from `KanbanColumnConfig.color` — caller data, not tokens — so a theme cannot retune them and a caller can trivially produce column headers that fail contrast against `--inset`. Prefer deriving those colors from theme tokens at the call site.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.