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

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

@@ -0,0 +1,321 @@
+// Pretui — Board usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import {
+  autoPlaceKanban,
+  cardsInColumn,
+} from '@cardstack/boxel-ui/components';
+import { FreestyleUsage } from './freestyle-usage';
+import { Board } from './board';
+import type { KanbanColumnConfig, KanbanPlacement } from '@cardstack/boxel-ui/components';
+import type { FittedFormatId } from '@cardstack/boxel-ui/helpers';
+
+// ── Board ← kanban/usage.gts ─────────────────────────────────────────────
+// Ported knobs: cardSize (upstream's three-size view selector becomes a
+// select), hideEmpty, columns/placements object rows, and all five
+// callbacks live (onChange/onSelect/onOpen/onAddCard/onToggleCollapsed).
+// Dropped: the KanbanColumnConfigSidebar half of the upstream page (a
+// separate boxel-ui component, not part of the Board wrap) and the
+// boxel-kanban-* cssVars rows (channel pinned to Pretui tokens by the
+// wrapper). Column colors are instance data, not component CSS.
+interface BoardCard {
+  kind: string;
+  title: string;
+}
+
+const BOARD_COLUMNS: KanbanColumnConfig[] = [
+  {
+    key: 'backlog',
+    label: 'Backlog',
+    color: '#656a73',
+    wipLimit: 0,
+    collapsed: false,
+    sortOrder: 1,
+  },
+  {
+    key: 'in-progress',
+    label: 'In Progress',
+    color: '#b8860b',
+    wipLimit: 2,
+    collapsed: false,
+    sortOrder: 2,
+  },
+  {
+    key: 'review',
+    label: 'Review',
+    color: '#0f766e',
+    wipLimit: 1,
+    collapsed: false,
+    sortOrder: 3,
+  },
+  {
+    key: 'done',
+    label: 'Done',
+    color: '#2e7d5b',
+    wipLimit: null,
+    collapsed: false,
+    sortOrder: 4,
+  },
+];
+
+const BOARD_CARDS: BoardCard[] = [
+  { title: 'Audit drag states', kind: 'Chore' },
+  { title: 'Polish column header', kind: 'Design' },
+  { title: 'Document insertion flow', kind: 'Docs' },
+  { title: 'Ship empty states', kind: 'Feature' },
+  { title: 'Review keyboard handling', kind: 'QA' },
+  { title: 'Publish examples', kind: 'Docs' },
+];
+
+const BOARD_CARD_SIZES = ['double-strip', 'regular-tile', 'compact-card'];
+
+class BoardUsage extends Component {
+  cardSizeOptions = BOARD_CARD_SIZES;
+  @tracked columns: KanbanColumnConfig[] = [...BOARD_COLUMNS];
+  @tracked cards: BoardCard[] = [...BOARD_CARDS];
+  @tracked placements: KanbanPlacement[] = autoPlaceKanban(
+    BOARD_CARDS.length,
+    BOARD_COLUMNS,
+  );
+  @tracked cardSize = 'regular-tile';
+  @tracked hideEmpty = false;
+  @tracked selectedIndex: number | null = null;
+  @tracked openedIndex: number | null = null;
+
+  setCardSize = (v: string) => (this.cardSize = v);
+  get cardSizeVal() {
+    return this.cardSize as FittedFormatId;
+  }
+  setHideEmpty = (v: boolean) => {
+    this.hideEmpty = v;
+    this.columns = this.columns.map((col) =>
+      cardsInColumn(col.key, this.placements).length === 0
+        ? { ...col, collapsed: v }
+        : col,
+    );
+  };
+  handleChange = (placements: KanbanPlacement[]) => {
+    this.placements = placements;
+    if (this.hideEmpty) {
+      this.columns = this.columns.map((col) =>
+        cardsInColumn(col.key, placements).length === 0
+          ? { ...col, collapsed: true }
+          : col,
+      );
+    }
+  };
+  handleSelect = (index: number | null) => (this.selectedIndex = index);
+  handleOpen = (index: number) => (this.openedIndex = index);
+  toggleCollapsed = (col: KanbanColumnConfig | null) => {
+    if (!col) {
+      return;
+    }
+    this.columns = this.columns.map((c) =>
+      c.key === col.key ? { ...c, collapsed: !c.collapsed } : c,
+    );
+  };
+  addCard = (columnKey: string | null) => {
+    let column = this.columns.find((c) => c.key === columnKey);
+    let resolvedKey = column?.key ?? this.columns[0]?.key;
+    if (!resolvedKey) {
+      return;
+    }
+    let nextIndex = this.cards.length;
+    let existing = cardsInColumn(resolvedKey, this.placements);
+    let nextOrder = (existing[existing.length - 1]?.sortOrder ?? 0) + 1;
+    this.cards = [
+      ...this.cards,
+      { title: `New card ${nextIndex + 1}`, kind: 'Draft' },
+    ];
+    this.placements = [
+      ...this.placements,
+      { index: nextIndex, columnId: resolvedKey, sortOrder: nextOrder },
+    ];
+  };
+  cardAt = (index: number): BoardCard => {
+    return this.cards[index] ?? { title: '', kind: '' };
+  };
+  get selectedCard(): BoardCard | null {
+    return this.selectedIndex === null
+      ? null
+      : (this.cards[this.selectedIndex] ?? null);
+  }
+  get openedCard(): BoardCard | null {
+    return this.openedIndex === null
+      ? null
+      : (this.cards[this.openedIndex] ?? null);
+  }
+  get usage() {
+    let bits = [
+      '@columns={{this.columns}}',
+      '@placements={{this.placements}}',
+      '@onChange={{this.handleChange}}',
+    ];
+    if (this.cardSize !== 'regular-tile')
+      bits.push(`@cardSize='${this.cardSize}'`);
+    if (this.hideEmpty) bits.push('@hideEmpty={{true}}');
+    return `<Board ${bits.join(' ')}>\n  <:card as |placement|>…</:card>\n  <:ghost as |dragIndex|>…</:ghost>\n</Board>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Board'
+      @description="Column workflow over a record set — drag cards between configurable lanes. Wraps boxel-ui's KanbanPlane, the newer pure-fn placement engine: columns and card placements are plain data, the consumer renders cards through blocks and owns all state, and every interaction (move, select, open, add, collapse) arrives as a callback. Collapsed columns gather in a hidden-columns tray."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='board-host'>
+          {{#if this.selectedCard}}
+            <p class='board-meta'>Selected: {{this.selectedCard.title}}</p>
+          {{/if}}
+          {{#if this.openedCard}}
+            <p class='board-meta'>Opened: {{this.openedCard.title}}</p>
+          {{/if}}
+          <div class='board-frame'>
+            <Board
+              @boardLabel='Pretui board demo'
+              @columns={{this.columns}}
+              @placements={{this.placements}}
+              @cardSize={{this.cardSizeVal}}
+              @hideEmpty={{this.hideEmpty}}
+              @onChange={{this.handleChange}}
+              @onSelect={{this.handleSelect}}
+              @onOpen={{this.handleOpen}}
+              @onAddCard={{this.addCard}}
+              @onToggleCollapsed={{this.toggleCollapsed}}
+            >
+              <:card as |placement|>
+                {{#let (this.cardAt placement.index) as |card|}}
+                  <div class='board-card'>
+                    <span class='board-card-kind'>{{card.kind}}</span>
+                    <h4 class='board-card-title'>{{card.title}}</h4>
+                  </div>
+                {{/let}}
+              </:card>
+              <:ghost as |dragIndex|>
+                {{#let (this.cardAt dragIndex) as |card|}}
+                  <div class='board-card'>
+                    <span class='board-card-kind'>{{card.kind}}</span>
+                    <h4 class='board-card-title'>{{card.title}}</h4>
+                  </div>
+                {{/let}}
+              </:ghost>
+            </Board>
+          </div>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='columns'
+          @required={{true}}
+          @value={{this.columns}}
+          @description='KanbanColumnConfig[] — key, label, color, wipLimit, collapsed, sortOrder per lane.'
+        />
+        <Args.Object
+          @name='placements'
+          @required={{true}}
+          @value={{this.placements}}
+          @description='KanbanPlacement[] — maps each card index to a columnId and sortOrder. Pure data; autoPlaceKanban seeds an initial spread.'
+        />
+        <Args.String
+          @name='cardSize'
+          @defaultValue='regular-tile'
+          @value={{this.cardSize}}
+          @options={{this.cardSizeOptions}}
+          @description='Fitted format id for card and column sizing within the plane.'
+          @onInput={{this.setCardSize}}
+        />
+        <Args.Bool
+          @name='hideEmpty'
+          @defaultValue={{false}}
+          @value={{this.hideEmpty}}
+          @description='Moves empty columns into the hidden-columns tray alongside explicitly collapsed ones (demo also collapses them on change).'
+          @onInput={{this.setHideEmpty}}
+        />
+        <Args.String
+          @name='boardLabel'
+          @description='Accessible label for the board region.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onChange'
+          @description='Receives the updated KanbanPlacement[] when the drag manager commits a move.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onSelect'
+          @description='Receives the selected card index, or null when selection clears.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onOpen'
+          @description='Receives a card index when a pointer interaction reads as open.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onAddCard'
+          @description='Receives the target column key when a lane add-card affordance is used.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onToggleCollapsed'
+          @description='Receives the KanbanColumnConfig when a column is collapsed or restored — the caller flips the collapsed flag.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='card'
+          @description='Renders one card for a KanbanPlacement — look the record up by placement.index.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='ghost'
+          @description='Renders the drag preview for the active card index.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .board-host {
+        display: grid;
+        gap: var(--space-3, 8px);
+      }
+      .board-meta {
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .board-frame {
+        height: 420px;
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: 0 0 0 1px var(--border);
+        overflow: hidden;
+        background: var(--background);
+      }
+      .board-card {
+        height: 100%;
+        display: grid;
+        align-content: start;
+        gap: 2px;
+        padding: var(--space-4, 11px);
+        overflow: hidden;
+      }
+      .board-card-kind {
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        font-weight: 500;
+        letter-spacing: var(--track-eyebrow, 0.08em);
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+      .board-card-title {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        font-weight: 600;
+        color: var(--card-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_BOARD: Record<string, unknown> = {
+  Board: BoardUsage,
+};

package/bundled-realms/pretui/components/bottom-nav.gts

@@ -0,0 +1,217 @@
+// Pretui — BottomNav: the mobile tab bar docked to the bottom of its pane — three to five destinations, labels always shown.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { fn } from '@ember/helper';
+import { on } from '@ember/modifier';
+import { VisuallyHidden } from './visually-hidden';
+
+export interface BottomNavItem {
+  id: string;
+  label: string;
+  /** A link destination. Without it the item is a button that reports @onChange. */
+  href?: string;
+  /** A short count or mark ('3', 'New'), shown by the label. */
+  badge?: string;
+  /** What the badge means, spoken after it ('unread' reads "3 unread"). */
+  badgeLabel?: string;
+  disabled?: boolean;
+}
+
+export interface BottomNavSignature {
+  Args: {
+    items: BottomNavItem[];
+    /** Controlled current id. Omit for uncontrolled. */
+    value?: string;
+    defaultValue?: string;
+    onChange?: (id: string) => void;
+    /** The navigation landmark's name (default 'Primary'). */
+    label?: string;
+    /** 'sticky' (default) docks to the bottom of the scroll container; 'static' leaves it in flow. */
+    position?: 'sticky' | 'static';
+  };
+  Blocks: {
+    /** One item's icon, yielded the item and whether it is current. */
+    icon: [item: BottomNavItem, current: boolean];
+  };
+  Element: HTMLElement;
+}
+
+/**
+ * MUI BottomNavigation, as navigation rather than a widget: a named `<nav>`
+ * landmark holding a list of links (or buttons, when there is no href), the
+ * current one marked with `aria-current="page"`. Tabs switches content in
+ * flow; Sidebar is the desktop rail.
+ *
+ * Labels are always visible — an icon-only bar makes every reader guess, and
+ * MUI's `showLabels={false}` default is the thing this refuses. It docks to
+ * the bottom of its scroll container with `position: sticky`, not to the
+ * viewport, because a card is rarely the viewport; the safe-area inset pads
+ * it clear of a phone's home indicator.
+ */
+export class BottomNav extends Component<BottomNavSignature> {
+  @tracked private internal: string | undefined = this.args.defaultValue;
+
+  /** Buttons default to the first item; links cannot know the current page, so they wait for @value. */
+  get current(): string | undefined {
+    let first = this.args.items?.[0];
+    return this.args.value ?? this.internal ?? (first && !first.href ? first.id : undefined);
+  }
+  get rows() {
+    return (this.args.items ?? []).map((item) => ({
+      item,
+      current: item.id === this.current,
+      spokenBadge: item.badge ? `${item.badge}${item.badgeLabel ? ' ' + item.badgeLabel : ''}` : undefined,
+    }));
+  }
+  choose = (item: BottomNavItem, event?: Event) => {
+    if (item.disabled) {
+      event?.preventDefault();
+      return;
+    }
+    if (this.args.value === undefined) {
+      this.internal = item.id;
+    }
+    this.args.onChange?.(item.id);
+  };
+
+  <template>
+    <nav
+      class='pretui-bottomnav'
+      aria-label={{if @label @label 'Primary'}}
+      data-position={{if @position @position 'sticky'}}
+      data-test-pretui-bottom-nav
+      ...attributes
+    >
+      <ul class='pretui-bottomnav-list'>
+        {{#each this.rows key='item.id' as |row|}}
+          <li class='pretui-bottomnav-cell'>
+            {{#if row.item.href}}
+              {{! A disabled link keeps role=link, a tab stop and its state: an anchor
+                  without href would drop out of the accessibility tree. }}
+              <a
+                class='pretui-bottomnav-item'
+                href={{if row.item.disabled undefined row.item.href}}
+                role={{if row.item.disabled 'link'}}
+                tabindex={{if row.item.disabled '0'}}
+                aria-current={{if row.current 'page'}}
+                aria-disabled={{if row.item.disabled 'true'}}
+                data-current={{if row.current 'true' 'false'}}
+                data-test-pretui-bottom-nav-item={{row.item.id}}
+                {{on 'click' (fn this.choose row.item)}}
+              >
+                {{#if (has-block 'icon')}}<span class='pretui-bottomnav-icon' aria-hidden='true'>{{yield row.item row.current to='icon'}}</span>{{/if}}
+                <span class='pretui-bottomnav-label'>{{row.item.label}}</span>
+                {{#if row.item.badge}}<span class='pretui-bottomnav-badge' aria-hidden='true'>{{row.item.badge}}</span><VisuallyHidden>{{row.spokenBadge}}</VisuallyHidden>{{/if}}
+              </a>
+            {{else}}
+              <button
+                type='button'
+                class='pretui-bottomnav-item'
+                aria-current={{if row.current 'page'}}
+                aria-disabled={{if row.item.disabled 'true'}}
+                data-current={{if row.current 'true' 'false'}}
+                data-test-pretui-bottom-nav-item={{row.item.id}}
+                {{on 'click' (fn this.choose row.item)}}
+              >
+                {{#if (has-block 'icon')}}<span class='pretui-bottomnav-icon' aria-hidden='true'>{{yield row.item row.current to='icon'}}</span>{{/if}}
+                <span class='pretui-bottomnav-label'>{{row.item.label}}</span>
+                {{#if row.item.badge}}<span class='pretui-bottomnav-badge' aria-hidden='true'>{{row.item.badge}}</span><VisuallyHidden>{{row.spokenBadge}}</VisuallyHidden>{{/if}}
+              </button>
+            {{/if}}
+          </li>
+        {{/each}}
+      </ul>
+    </nav>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-bottomnav {
+          inset-block-end: 0;
+          z-index: var(--pretui-z-sticky, 10);
+          background: var(--pretui-bottomnav-bg, var(--card));
+          box-shadow: 0 -1px 0 var(--border);
+          padding-block-end: env(safe-area-inset-bottom, 0px);
+          font-family: var(--font-sans);
+        }
+        .pretui-bottomnav[data-position='sticky'] {
+          position: sticky;
+        }
+        .pretui-bottomnav-list {
+          display: flex;
+          margin: 0;
+          padding: 0;
+          list-style: none;
+        }
+        .pretui-bottomnav-cell {
+          flex: 1 1 0;
+          min-inline-size: 0;
+        }
+        .pretui-bottomnav-item {
+          position: relative;
+          display: grid;
+          justify-items: center;
+          gap: 0.125rem;
+          inline-size: 100%;
+          min-block-size: 3.5rem;
+          padding: var(--space-2, 0.375rem) var(--space-1, 0.25rem);
+          box-sizing: border-box;
+          border: 0;
+          background: transparent;
+          color: var(--muted-foreground);
+          font: inherit;
+          font-size: var(--text-ui-xs, 0.66rem);
+          text-decoration: none;
+          cursor: pointer;
+        }
+        .pretui-bottomnav-item[data-current='true'] {
+          color: var(--pretui-bottomnav-current, var(--primary));
+          font-weight: 600;
+        }
+        .pretui-bottomnav-item[data-current='true']::before {
+          content: '';
+          position: absolute;
+          inset-block-start: 0;
+          inset-inline: 30%;
+          block-size: 2px;
+          border-radius: 0 0 2px 2px;
+          background: currentColor;
+        }
+        .pretui-bottomnav-item[aria-disabled='true'] {
+          opacity: 0.45;
+          cursor: not-allowed;
+        }
+        .pretui-bottomnav-item:hover {
+          color: var(--foreground);
+        }
+        .pretui-bottomnav-item:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: -2px;
+        }
+        .pretui-bottomnav-icon {
+          display: grid;
+          place-items: center;
+          block-size: 1.375rem;
+        }
+        .pretui-bottomnav-label {
+          max-inline-size: 100%;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-bottomnav-badge {
+          position: absolute;
+          inset-block-start: 0.25rem;
+          inset-inline-start: calc(50% + 0.5rem);
+          min-inline-size: 1rem;
+          padding-inline: 0.25rem;
+          border-radius: 999px;
+          background: var(--destructive);
+          color: var(--card);
+          font-size: 0.6rem;
+          font-weight: 600;
+          line-height: 1rem;
+          text-align: center;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/bottom-nav.md

@@ -0,0 +1,64 @@
+## What it is
+
+**The mobile tab bar docked to the bottom of its pane**: three to five top-level destinations with an icon and a label each. Use it for the primary navigation of a card app on a narrow screen.
+
+Reach for a neighbour when the job is different:
+
+- **Tabs** switches content in the flow of a page.
+- **Sidebar** is the desktop rail.
+- **NavigationMenu** is a site's top navigation.
+
+## The contract
+
+```
+@items ({ id, label, href?, badge?, badgeLabel?, disabled? }[])
+@value?, @defaultValue?, @onChange? (id)
+@label? (default 'Primary'), @position? ('sticky' | 'static'; default 'sticky')
+<:icon as |item current|>
+Element: HTMLElement (a <nav>)
+```
+
+**Navigation, not a widget.** It is a named `<nav>` landmark holding a list. Each item is a link when it has an `href`, and a button that reports `@onChange` when it doesn't. The current item is marked `aria-current="page"`. Button items default to the first. Link items wait for `@value`, because the component can't know the current page.
+
+**Labels are always visible.** An icon-only bar makes every reader guess. MUI's `showLabels` defaults to false, and this refuses that default. A `badge` ("3", "New") sits by the label. The visible mark is hidden from assistive technology, and `badgeLabel` gives its meaning, so the item reads "Lots, 3 new" rather than a bare "3".
+
+**Docked to the pane.** `position: sticky` at the bottom of the scroll container, not `fixed` to the viewport, because a card is rarely the viewport. The bar is padded with `env(safe-area-inset-bottom)` so it clears a phone's home indicator. `@position='static'` leaves it in flow.
+
+A disabled item is shown dimmed, marked `aria-disabled` and refuses the change, and keeps its place. A disabled link keeps `role="link"` and a tab stop, so it doesn't drop out of the accessibility tree.
+
+## Prior art
+
+**MUI `BottomNavigation`** takes `value`, `onChange` and `showLabels`, with `BottomNavigationAction` children (`label`, `icon`, `value`). It is `position: static` by default and usually made `fixed` by the caller. **Ant Mobile `TabBar`** and **Chakra** recipes are similar. Most are built as tabs, with `role="tab"` semantics.
+
+Where Pretui is better: **navigation semantics.** A bottom bar switches between destinations, so a `<nav>` with `aria-current` says that honestly. MUI's buttons announce nothing about which is current. **Labels are always on.** **Pane docking** needs no `position: fixed` workaround.
+
+Where it is thinner: **no hide-on-scroll** and **no ripple**. For more than five destinations, use **Sidebar** or a menu. The component doesn't cap the count, but the layout crowds.
+
+## Accessibility
+
+No APG widget pattern. It is a navigation landmark with links or buttons.
+
+- **A `<nav>` named by `@label`.** The tests assert the tag and the name.
+- **`aria-current="page"`** marks the current item. The tests assert the default, a change, and controlled `@value`.
+- **Links are `<a href>`, and buttons are `type="button"`,** so each works with its native keyboard behaviour. The tests assert both.
+- **Disabled items** carry `aria-disabled="true"` and refuse, which the tests assert.
+- **Icons are `aria-hidden`.** The label names the item.
+- **Touch targets** are at least 3.5rem tall.
+
+## Theming
+
+`--pretui-bottomnav-bg` (default `--card`), `--pretui-bottomnav-current` (default `--primary`), `--border` (the top hairline), `--muted-foreground` and `--foreground` (items), `--destructive` (the badge), `--ring`, `--pretui-z-sticky`, `--font-sans`, `--text-ui-xs`, `--space-1` and `--space-2`.
+
+The current indicator (a 2px bar at the top of the item) and the 3.5rem height are fixed.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                                     | Give them                             |
+| ----------------------------------------------- | ------------------------------------- |
+| MUI `<BottomNavigation value onChange>`         | `<BottomNav @items @value @onChange>` |
+| MUI `<BottomNavigationAction label icon value>` | an item `{ id, label }` + `<:icon>`   |
+| MUI `showLabels`                                | always on                             |
+| `sx={{ position: 'fixed', bottom: 0 }}`         | the default sticky docking            |
+| Ant Mobile `<TabBar>`                           | `<BottomNav>`                         |

package/bundled-realms/pretui/components/bottom-nav.usage.gts

@@ -0,0 +1,68 @@
+// Pretui — BottomNav usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { BottomNav } from './bottom-nav';
+import type { BottomNavItem } from './bottom-nav';
+
+const ITEMS: BottomNavItem[] = [
+  { id: 'home', label: 'Home' },
+  { id: 'lots', label: 'Lots', badge: '3' },
+  { id: 'roasts', label: 'Roasts' },
+  { id: 'account', label: 'Account' },
+];
+const GLYPHS: Record<string, string> = { home: '⌂', lots: '▦', roasts: '◉', account: '◎' };
+
+export class BottomNavUsage extends Component {
+  items = ITEMS;
+  @tracked current = 'lots';
+  setCurrent = (v: string) => (this.current = v);
+  glyph = (id: string) => GLYPHS[id] ?? '•';
+  get usage() {
+    return "<BottomNav @items={{this.items}} @value={{this.current}} @onChange={{this.go}} @label='Roastery'>\n  <:icon as |item|>…</:icon>\n</BottomNav>";
+  }
+  <template>
+    <FreestyleUsage
+      @name='BottomNav'
+      @description='The mobile tab bar docked to the bottom of its pane: a named navigation landmark of links or buttons, the current one marked aria-current, labels always visible. It is sticky inside its scroll container, not fixed to the viewport, and padded clear of the safe area. Tabs switches content in flow; Sidebar is the desktop rail.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='bn-demo'>
+          <p class='bn-demo-body'>Showing: {{this.current}}</p>
+          <BottomNav @items={{this.items}} @value={{this.current}} @onChange={{this.setCurrent}} @label='Roastery'>
+            <:icon as |item|>{{this.glyph item.id}}</:icon>
+          </BottomNav>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='items' @required={{true}} @description='{ id, label, href?, badge?, disabled? }[]' />
+        <Args.String @name='value' @description='Controlled current id; defaultValue seeds the uncontrolled form.' />
+        <Args.Action @name='onChange' />
+        <Args.String @name='label' @defaultValue='Primary' />
+        <Args.String @name='position' @defaultValue='sticky' @description='sticky or static.' />
+        <Args.Yield @name='icon' @description='One item icon, yielded the item and whether it is current.' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .bn-demo {
+        display: grid;
+        grid-template-rows: 1fr auto;
+        block-size: 12rem;
+        max-inline-size: 24rem;
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: 0 0 0 1px var(--border);
+        overflow: hidden;
+      }
+      .bn-demo-body {
+        margin: 0;
+        padding: var(--space-4, 0.6875rem);
+        font-size: var(--text-ui-md, 0.78rem);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_BOTTOM_NAV: Record<string, unknown> = {
+  BottomNav: BottomNavUsage,
+};