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

package/bundled-realms/pretui/components/page-scaffold.usage.gts

@@ -0,0 +1,391 @@
+// Pretui — PageScaffold usage page.
+import Component from '@glimmer/component';
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Chip } from './chip';
+import { Token } from './token';
+import { statusHue } from '../internal/ink';
+import { PageScaffold } from './page-scaffold';
+import type { PageScaffoldPreset } from './page-scaffold';
+
+// ── PageScaffold ─────────────────────────────────────────────────────────
+// Broken out so both frame shapes below can share it without the demo
+// turning into two copies of the same markup.
+const ScaffoldMasthead: TemplateOnlyComponent = <template>
+  <div class='ps-demo-masthead'>
+    <span class='ps-demo-brand'>Leaf &amp; Ledger</span>
+    <span class='ps-demo-account'>Mei-Lin Chua</span>
+  </div>
+  <style scoped>
+    .ps-demo-masthead {
+      display: flex;
+      align-items: baseline;
+      justify-content: space-between;
+      gap: var(--space-4, 11px);
+    }
+    .ps-demo-brand {
+      font-size: var(--text-ui-lg, 14px);
+      font-weight: 650;
+      letter-spacing: var(--track-heading, -0.01em);
+      color: var(--foreground);
+    }
+    .ps-demo-account {
+      font-size: var(--text-ui-sm, 11.5px);
+      color: var(--muted-foreground);
+    }
+  </style>
+</template>;
+
+const ScaffoldSubhead: TemplateOnlyComponent = <template>
+  <div class='ps-demo-subhead'>
+    <span>Lots</span>
+    <span aria-hidden='true'>/</span>
+    <span>Spring 2026</span>
+    <span aria-hidden='true'>/</span>
+    <Token @value='LOT-1181' />
+  </div>
+  <style scoped>
+    .ps-demo-subhead {
+      display: flex;
+      align-items: center;
+      gap: var(--space-2, 5px);
+      font-size: var(--text-ui-sm, 11.5px);
+      color: var(--muted-foreground);
+    }
+  </style>
+</template>;
+
+class ScaffoldNav extends Component {
+  navItems = ['Lots', 'Suppliers', 'Shipments', 'Cupping notes', 'Invoices'];
+  <template>
+    <ul class='ps-demo-nav'>
+      {{#each this.navItems key='@identity' as |item|}}
+        <li>{{item}}</li>
+      {{/each}}
+    </ul>
+    <style scoped>
+      .ps-demo-nav {
+        display: grid;
+        gap: 2px;
+        margin: 0;
+        padding: 0;
+        list-style: none;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+      .ps-demo-nav li {
+        padding: var(--space-2, 5px) var(--space-3, 8px);
+        border-radius: var(--radius-chip, 6px);
+      }
+      .ps-demo-nav li:first-child {
+        background: var(--muted);
+        color: var(--foreground);
+        font-weight: 600;
+      }
+    </style>
+  </template>
+}
+
+const ScaffoldMain: TemplateOnlyComponent = <template>
+  <h2 class='ps-demo-h'>Da Hong Pao, spring pick</h2>
+  <p class='ps-demo-p'>Ninety-six kilograms out of Wuyishan, curing since the
+    fourteenth. Wuyi Origins holds the contract and has asked for the cupping
+    notes before the Rotterdam booking closes.</p>
+  <p class='ps-demo-p'>The humidity log for the curing room is attached to the
+    lot rather than the shipment, which is why it is missing from the customs
+    packet.</p>
+  <style scoped>
+    .ps-demo-h {
+      margin: 0 0 var(--space-3, 8px);
+      font-size: var(--text-ui-lg, 14px);
+      letter-spacing: var(--track-heading, -0.01em);
+      color: var(--foreground);
+    }
+    .ps-demo-p {
+      margin: 0 0 var(--space-3, 8px);
+      max-width: 60ch;
+      line-height: 1.55;
+      color: var(--muted-foreground);
+    }
+  </style>
+</template>;
+
+class ScaffoldAside extends Component {
+  curingHue = statusHue('curing');
+  <template>
+    <dl class='ps-demo-meta'>
+      <dt>Supplier</dt>
+      <dd>Wuyi Origins</dd>
+      <dt>Status</dt>
+      <dd><Chip @label='curing' @hue={{this.curingHue}} /></dd>
+      <dt>Booked</dt>
+      <dd>2026-03-14</dd>
+    </dl>
+    <style scoped>
+      .ps-demo-meta {
+        display: grid;
+        grid-template-columns: auto 1fr;
+        gap: var(--space-2, 5px) var(--space-3, 8px);
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+      }
+      .ps-demo-meta dt {
+        color: var(--muted-foreground);
+      }
+      .ps-demo-meta dd {
+        margin: 0;
+        color: var(--foreground);
+      }
+    </style>
+  </template>
+}
+
+const ScaffoldFooter: TemplateOnlyComponent = <template>
+  <p class='ps-demo-foot'>Ledger closes 2026-09-30 · Kericho, Uji, Wuyishan</p>
+  <style scoped>
+    .ps-demo-foot {
+      margin: 0;
+      font-size: var(--text-ui-xs, 11px);
+      color: var(--muted-foreground);
+    }
+  </style>
+</template>;
+
+// Ported from @cardstack/boxel-layout's `Layout`, with Web Awesome's
+// wa-page as the visual reference for the region set. Knobs follow
+// wa-page's own surface (navigation width, aside width, sticky header,
+// skip link) minus the ones that do not survive the port: wa-page's
+// `slot="..."` string plumbing and `[navigation-placement]` /
+// `[banner-placement]` attributes are gone, because here the shape is
+// DERIVED from which named blocks you pass; its mobile drawer + hamburger
+// is gone too — that is a component, not a frame, and belongs to Drawer.
+class PageScaffoldUsage extends Component {
+  presetOptions = ['bare', 'page', 'notebook', 'tools'];
+
+  @tracked preset = 'page';
+  @tracked label = 'Lot detail';
+  @tracked navLabel = 'Section navigation';
+  @tracked asideLabel = 'Lot metadata';
+  @tracked navWidth = '12rem';
+  @tracked asideWidth = '14rem';
+  @tracked maxWidth = '';
+  @tracked stickyMasthead = false;
+  @tracked divided = false;
+  @tracked skipLink = true;
+  @tracked fullFrame = true;
+
+  setPreset = (v: string) => (this.preset = v);
+  setLabel = (v: string) => (this.label = v);
+  setNavLabel = (v: string) => (this.navLabel = v);
+  setAsideLabel = (v: string) => (this.asideLabel = v);
+  setNavWidth = (v: string) => (this.navWidth = v);
+  setAsideWidth = (v: string) => (this.asideWidth = v);
+  setMaxWidth = (v: string) => (this.maxWidth = v);
+  setStickyMasthead = (v: boolean) => (this.stickyMasthead = v);
+  setDivided = (v: boolean) => (this.divided = v);
+  setSkipLink = (v: boolean) => (this.skipLink = v);
+  setFullFrame = (v: boolean) => (this.fullFrame = v);
+
+  get presetVal() {
+    return this.preset as PageScaffoldPreset;
+  }
+  get maxWidthVal() {
+    return this.maxWidth || undefined;
+  }
+
+  get usage() {
+    let bits = [`@preset='${this.preset}'`, `@label='${this.label}'`];
+    if (this.stickyMasthead) bits.push('@stickyMasthead={{true}}');
+    if (this.divided) bits.push('@divided={{true}}');
+    if (!this.skipLink) bits.push('@skipLink={{false}}');
+    let blocks = this.fullFrame
+      ? '  <:masthead>…</:masthead>\n  <:subhead>…</:subhead>\n  <:navigation>…</:navigation>\n  <:default>…</:default>\n  <:aside>…</:aside>\n  <:footer>…</:footer>'
+      : '  <:masthead>…</:masthead>\n  <:default>…</:default>';
+    return `<PageScaffold ${bits.join(' ')}>\n${blocks}\n</PageScaffold>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='PageScaffold'
+      @description="An application frame with real landmark regions — masthead, subhead, navigation, main, aside, footer — over the boxel-layout presets that supply the reading rhythm. Reach for it as the outermost shell of an isolated card or a tool. Three things it does that its two ancestors do not: the column shape is DERIVED with :has() from the blocks you actually pass, so there is no layout prop to hold wrong; it folds to a single column on an unnamed CONTAINER query, so it responds to the pane it is in rather than the browser window; and it ships a skip link that genuinely moves focus (the <main> takes tabindex=-1), which neither boxel-layout nor wa-page includes. Every hard-coded light hex in the presets (#f8fafc, #e2e8f0, #d1d5db) is repointed at a theme token — the reason this exists instead of 'just use Layout'. Tab into the example and the skip link is the first thing you meet."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='ps-demo-host'>
+          {{#if this.fullFrame}}
+            <PageScaffold
+              @preset={{this.presetVal}}
+              @label={{this.label}}
+              @navLabel={{this.navLabel}}
+              @asideLabel={{this.asideLabel}}
+              @navWidth={{this.navWidth}}
+              @asideWidth={{this.asideWidth}}
+              @maxWidth={{this.maxWidthVal}}
+              @stickyMasthead={{this.stickyMasthead}}
+              @divided={{this.divided}}
+              @skipLink={{this.skipLink}}
+            >
+              <:masthead><ScaffoldMasthead /></:masthead>
+              <:subhead><ScaffoldSubhead /></:subhead>
+              <:navigation><ScaffoldNav /></:navigation>
+              <:default><ScaffoldMain /></:default>
+              <:aside><ScaffoldAside /></:aside>
+              <:footer><ScaffoldFooter /></:footer>
+            </PageScaffold>
+          {{else}}
+            <PageScaffold
+              @preset={{this.presetVal}}
+              @label={{this.label}}
+              @maxWidth={{this.maxWidthVal}}
+              @stickyMasthead={{this.stickyMasthead}}
+              @divided={{this.divided}}
+              @skipLink={{this.skipLink}}
+            >
+              <:masthead><ScaffoldMasthead /></:masthead>
+              <:default><ScaffoldMain /></:default>
+            </PageScaffold>
+          {{/if}}
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='preset'
+          @options={{this.presetOptions}}
+          @value={{this.preset}}
+          @defaultValue='page'
+          @onInput={{this.setPreset}}
+          @description="boxel-layout preset underneath: 'page' (editorial measure and rhythm), 'bare' (no opinions), 'notebook' (divided blocks), 'tools' (panel grid). notebook and tools draw the Pretui surface — hairline plus shadow, never the preset's own border."
+        />
+        <Args.Bool
+          @name='full frame (demo only)'
+          @value={{this.fullFrame}}
+          @defaultValue={{true}}
+          @onInput={{this.setFullFrame}}
+          @description='Not a component arg — switches between passing all six blocks and passing only masthead + main, so you can watch the grid shape derive itself from the blocks rather than from a prop.'
+        />
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @onInput={{this.setLabel}}
+          @description='Accessible name for the <main> region. Give it one whenever a page holds more than one main-ish area.'
+        />
+        <Args.String
+          @name='navLabel'
+          @value={{this.navLabel}}
+          @defaultValue='Section navigation'
+          @onInput={{this.setNavLabel}}
+          @description='Accessible name for the <nav> landmark. Two navs on a page without distinct names is the classic screen-reader trap.'
+        />
+        <Args.String
+          @name='asideLabel'
+          @value={{this.asideLabel}}
+          @defaultValue='Supplementary'
+          @onInput={{this.setAsideLabel}}
+          @description='Accessible name for the <aside> landmark.'
+        />
+        <Args.String
+          @name='navWidth'
+          @value={{this.navWidth}}
+          @defaultValue='14rem'
+          @onInput={{this.setNavWidth}}
+          @description='Width of the navigation rail; any CSS length. Ignored once the container folds to one column.'
+        />
+        <Args.String
+          @name='asideWidth'
+          @value={{this.asideWidth}}
+          @defaultValue='16rem'
+          @onInput={{this.setAsideWidth}}
+          @description='Width of the aside rail; any CSS length.'
+        />
+        <Args.String
+          @name='maxWidth'
+          @value={{this.maxWidth}}
+          @onInput={{this.setMaxWidth}}
+          @description="Cap on the content measure, overriding the preset's own. Empty leaves the preset in charge."
+        />
+        <Args.Bool
+          @name='stickyMasthead'
+          @value={{this.stickyMasthead}}
+          @defaultValue={{false}}
+          @onInput={{this.setStickyMasthead}}
+          @description='Pin the masthead to the top of the scroll container. Set --pretui-page-sticky-top when something else is already pinned above it.'
+        />
+        <Args.Bool
+          @name='divided'
+          @value={{this.divided}}
+          @defaultValue={{false}}
+          @onInput={{this.setDivided}}
+          @description="Hairlines between the bands. Defaults to true under the 'notebook' preset, whose own dividers only reach surface Units and so miss plain regions."
+        />
+        <Args.Bool
+          @name='skipLink'
+          @value={{this.skipLink}}
+          @defaultValue={{true}}
+          @onInput={{this.setSkipLink}}
+          @description='Render the skip-to-content link — first in the tab order, hidden until focused, and it moves focus rather than only scrolling. Turn it off only when an outer frame already provides one.'
+        />
+        <Args.Yield
+          @name='masthead'
+          @hideControls={{true}}
+          @description='Top band, full width, a <header> — product name, account, global actions.'
+        />
+        <Args.Yield
+          @name='subhead'
+          @hideControls={{true}}
+          @description='Second band under the masthead — breadcrumb, filters, a Toolbar.'
+        />
+        <Args.Yield
+          @name='navigation'
+          @hideControls={{true}}
+          @description='The start rail, a <nav> landmark. Passing it turns the body into two columns.'
+        />
+        <Args.Yield
+          @name='default'
+          @hideControls={{true}}
+          @description='The content column, a <main> landmark. The only required block, and the skip-link target.'
+        />
+        <Args.Yield
+          @name='aside'
+          @hideControls={{true}}
+          @description='The end rail, an <aside> landmark — outline, metadata, activity.'
+        />
+        <Args.Yield
+          @name='footer'
+          @hideControls={{true}}
+          @description='Bottom band, full width, a <footer>.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-page-gap'
+          @description='Vertical rhythm between the bands, and the padding above a divided band.'
+        />
+        <Css.Basic
+          @name='pretui-page-column-gap'
+          @description='Gap between navigation, main and aside.'
+        />
+        <Css.Basic
+          @name='pretui-page-sticky-top'
+          @defaultValue='0px'
+          @description='Offset for the sticky masthead and the sticky rails, when something else is pinned above the frame.'
+        />
+        <Css.Basic
+          @name='pretui-page-shadow'
+          @description="Surface depth for the notebook and tools presets, replacing boxel-layout's border."
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .ps-demo-host {
+        container-type: inline-size;
+        padding: var(--space-4, 11px);
+        font-size: var(--text-ui-md, 12.5px);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_PAGE_SCAFFOLD: Record<string, unknown> = {
+  PageScaffold: PageScaffoldUsage,
+};

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

@@ -0,0 +1,150 @@
+// Pretui — Pagination: page navigation with ellipsis windows.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import ChevronLeft from '@cardstack/boxel-icons/chevron-left';
+import ChevronRight from '@cardstack/boxel-icons/chevron-right';
+
+export interface PaginationSignature {
+  Args: { page?: number; defaultPage?: number; pages: number; onPageChange?: (n: number) => void };
+  Element: HTMLElement;
+}
+
+export class Pagination extends Component<PaginationSignature> {
+  @tracked internal = this.args.defaultPage ?? 1;
+  get page() {
+    return this.args.page ?? this.internal;
+  }
+  get list(): (number | '…')[] {
+    let out: (number | '…')[] = [];
+    for (let i = 1; i <= this.args.pages; i++) {
+      if (i === 1 || i === this.args.pages || Math.abs(i - this.page) <= 1) {
+        out.push(i);
+      } else if (out[out.length - 1] !== '…') {
+        out.push('…');
+      }
+    }
+    return out;
+  }
+  // A request for the page already showing reports nothing. That covers a
+  // press on the current page and a press on an edge arrow, which is
+  // aria-disabled rather than natively disabled so it stays in the tab order
+  // and still receives clicks.
+  go = (v: number) => {
+    let n = Math.max(1, Math.min(this.args.pages, v));
+    if (n === this.page) return;
+    if (this.args.page === undefined) {
+      this.internal = n;
+    }
+    this.args.onPageChange?.(n);
+  };
+  isGap = (n: number | '…'): n is '…' => n === '…';
+  prev = () => this.go(this.page - 1);
+  next = () => this.go(this.page + 1);
+  get atStart() {
+    return this.page === 1;
+  }
+  get atEnd() {
+    return this.page === this.args.pages;
+  }
+  isActive = (n: number | '…') => n === this.page;
+  <template>
+    <nav class='pretui-pagination' aria-label='Pagination' data-test-pretui-pagination ...attributes>
+      <button type='button' class='pretui-page' aria-disabled={{if this.atStart 'true'}} aria-label='Previous' {{on 'click' this.prev}}><ChevronLeft class='pretui-chevron' width='12' height='12' aria-hidden='true' /></button>
+      {{#each this.list as |n|}}
+        {{#if (this.isGap n)}}
+          <span class='pretui-gap'>…</span>
+        {{else}}
+          <button
+            type='button'
+            class='pretui-page'
+            aria-label='Page {{n}}'
+            data-state={{if (this.isActive n) 'active'}}
+            aria-current={{if (this.isActive n) 'page'}}
+            {{on 'click' (fn this.go n)}}
+          >{{n}}</button>
+        {{/if}}
+      {{/each}}
+      <button type='button' class='pretui-page' aria-disabled={{if this.atEnd 'true'}} aria-label='Next' {{on 'click' this.next}}><ChevronRight class='pretui-chevron' width='12' height='12' aria-hidden='true' /></button>
+    </nav>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-pagination {
+          display: flex;
+          align-items: center;
+          gap: var(--boxel-sp-6xs);
+          font-size: var(--boxel-font-size-xs);
+        }
+        .pretui-page {
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          min-width: 1.625rem;
+          height: 1.625rem;
+          padding: 0 var(--boxel-sp-2xs);
+          border: 0;
+          border-radius: var(--boxel-border-radius-sm);
+          background-color: transparent;
+          color: var(--muted-foreground);
+          font-family: inherit;
+          font-size: inherit;
+          font-weight: inherit;
+          font-style: inherit;
+          font-stretch: inherit;
+          font-variant: inherit;
+          line-height: inherit;
+          letter-spacing: inherit;
+          font-variant-numeric: tabular-nums;
+          transition-property: scale;
+          transition-duration: 150ms;
+          transition-timing-function: ease-out;
+        }
+        /* The current page keeps its selected fill and ink under the pointer:
+           this rule's specificity would otherwise beat the data-state rule.
+           Gated on a hovering pointer, so a tapped button on a touch screen
+           does not keep the fill. */
+        @media (hover: hover) {
+          .pretui-page:hover:not([aria-disabled='true'], [data-state='active']) {
+            background-color: var(--hover);
+            color: var(--foreground);
+          }
+        }
+        /* Press feedback. Edge arrows that are aria-disabled still receive
+           presses, and the current page ignores them, so neither reacts. */
+        .pretui-page:active:not([aria-disabled='true'], [data-state='active']) {
+          scale: 0.96;
+        }
+        .pretui-page[data-state='active'] {
+          background-color: var(--selected);
+          color: var(--primary-ink);
+          font-weight: 600;
+          box-shadow: 0 0 0 1px var(--border);
+          cursor: default;
+        }
+        /* The arrows are fixed SVGs, so they flip with the writing direction
+           the way the bidi-mirrored glyphs they replace did. */
+        .pretui-chevron:dir(rtl) {
+          scale: -1 1;
+        }
+        .pretui-page:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 1px;
+        }
+        .pretui-page[aria-disabled='true'] {
+          color: var(--subtle-foreground);
+          cursor: default;
+        }
+        .pretui-gap {
+          color: var(--subtle-foreground);
+          padding: 0 var(--boxel-sp-3xs);
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-page {
+            transition-duration: 0s;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,56 @@
+## What it is
+
+Page controls for a paged list: previous, a windowed run of page numbers with ellipses, next. Use it under a **DataGrid** or **Table** whose data arrives a page at a time. If the list loads more on scroll, you do not want this. If the user is stepping through a _process_ rather than a list, use **Stepper** or **StepList**.
+
+## The contract
+
+```
+@pages: number   (required)
+@page?, @defaultPage?, @onPageChange?(n: number)
+Element: HTMLElement (a <nav>)
+```
+
+Hybrid controlled/uncontrolled, the kit-wide idiom: `@page ?? @internal`, with `@internal` written only when `@page === undefined`.
+
+**The window rule is fixed and not configurable:** always show page 1, always show the last page, always show the current page ±1, and collapse everything else to a single `…`. So the strip is at most seven items wide and never changes width as you move through the middle of a long list — which is the property that stops the buttons from sliding under the pointer between clicks. Web Awesome makes the equivalent two knobs (`sibling-count`, `boundary-count`); Pretui hard-codes the pair that produces a stable strip.
+
+`go()` clamps to `[1, @pages]`, so a caller cannot drive it out of range, and ignores a request for the page already showing, so `@onPageChange` fires only when the page would change. A press on the current page, or on an edge arrow at its end, reports nothing.
+
+The gap is a `<span>`, not a button — clicking `…` does nothing.
+
+## Prior art
+
+**There is no APG pattern for pagination.** The composed convention is: a navigation landmark with a distinct `aria-label`, links or buttons in the natural tab sequence, `aria-current="page"` on the active one, and no arrow keys or roving tabindex.
+
+**Web Awesome `wa-pagination`** is the most complete implementation in the field: `total`/`page-size`/`page`, `sibling-count`, `boundary-count`, `with-edges`, `with-summary`, `format` (`standard`|`compact`), `href-template`, `hide-single-page`, a cancelable `wa-before-page-change` event, `<nav aria-label>` → `<ul role="list">` → `<li>`, `aria-current="page"` on the active item, **`aria-disabled` rather than `disabled`** so edge controls stay focusable, a polite live region announcing changes, and clicking an ellipsis jumps ±5. **Ark UI** exposes an `api.pages` array of `{ type: 'page' | 'ellipsis' }` — item-as-data via render prop, structurally the same idea as Pretui's `list` getter. **shadcn** ships presentation only.
+
+Pretui's improvements are narrow but real: the fixed window (above) gives a stable strip that Web Awesome's configurable one does not guarantee, and `font-variant-numeric: tabular-nums` on the page buttons keeps the digits from jittering as the numbers change width — a detail almost everyone misses.
+
+Where it is behind Web Awesome, and it is a fair distance: no summary ("11–20 of 240"), no `href` mode (so pages are not linkable or bookmarkable), no page-size control, no first/last jumps, no ellipsis jump, no cancelable change event, and no announcement.
+
+## Accessibility
+
+No APG pattern; governed by WCAG **2.4.8 Location** (AAA — this is the criterion pagination exists to satisfy), **2.4.4 Link Purpose**, **4.1.2** and **2.5.8 Target Size**.
+
+What is right: the root is a `<nav aria-label="Pagination">`, so it is discoverable by landmark navigation and distinguishable from other navs. The active page carries `aria-current="page"` (alongside the visual `data-state="active"`), which is the one required property of the pattern. Previous/Next carry `aria-label`, and each page number carries `aria-label="Page N"` so "3" is not announced bare. All controls are ordinary tab stops, which is correct — pagination is not a roving-tabindex widget. At either end the edge arrow is marked `aria-disabled="true"` rather than natively `disabled`, so it stays in the tab order — a keyboard user tabbing backward into the strip at page 1 still lands on Previous and hears that it is unavailable — and a press on it does nothing and reports nothing. This is the choice Web Awesome makes. The disabled arrow dims its glyph to `--subtle-foreground` rather than fading the whole button, so its `--ring` focus outline stays at full strength.
+
+Gaps, in order:
+
+- **Page changes are not announced.** After clicking "3" the table content changes and nothing says so; focus stays on the button, which is right, but a polite live region ("Page 3 of 12") is what Web Awesome adds.
+- **Target size**: the buttons are `min-width: 1.625rem; height: 1.625rem` with a gap of about 2px — **below WCAG 2.5.8's 24×24 minimum once you account for the fact that 26px is the outer box and the gap is only 2px**, so adjacent targets effectively touch. Technically 26 ≥ 24 so the criterion passes, but only just, and this is the most-tapped small control in the kit.
+- The arrows render `ChevronLeft` / `ChevronRight` icons with `aria-hidden`, inside buttons that carry `aria-label`; the icons mirror under a right-to-left writing direction.
+- The `…` gap is a `<span>` with no role, announced as "horizontal ellipsis" or skipped. Harmless.
+
+## Theming
+
+`--muted-foreground` (resting ink), `--foreground` (hover ink), `--hover` (hover fill), `--selected` (active fill), `--primary-ink` (active ink), `--border` (the active page's edge), `--subtle-foreground` (a disabled edge arrow), `--ring` (focus outline), `--subtle-foreground` (the ellipsis, like a disabled arrow), `--boxel-font-size-xs`. Spacing and radius come from `--boxel-sp-*` and `--boxel-border-radius-sm`. A press scales a page button to 0.96 (suppressed under `prefers-reduced-motion`); the current page and aria-disabled arrows do not react to it, and hovering the current page keeps its selected look. The hover fill applies only on a device with a hovering pointer, so a tapped button on a touch screen does not keep it.
+
+`--selected` is the notable one: it is the kit's "this row is the chosen one" fill, shared with selection states elsewhere, and a theme that leaves it at the default light blue while retuning `--primary` to a warm hue will produce an active page whose fill and ink disagree. Define the pair together, and check `--primary-ink` for contrast against `--selected` rather than against `--card`.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Compose onto **DataTable** / **List**. Accept `page` / `pageSize` /
+`onPageChange` / `total`. Ant `showSizeChanger` is a Select of page
+sizes — optional enhancement.

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

@@ -0,0 +1,33 @@
+// Pretui — Pagination usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Pagination } from './pagination';
+
+class PaginationUsage extends Component {
+  @tracked page = 4;
+  setPage = (page: number) => (this.page = page);
+  <template>
+    <FreestyleUsage
+      @name='Pagination'
+      @description='Compact page navigation with honest disabled ends and ellipsis windows. The current page is controlled here so every path updates the readout.'
+      @source='<Pagination @pages="12" … />'
+    >
+      <:example>
+        <Pagination @page={{this.page}} @pages={{12}} @onPageChange={{this.setPage}} />
+        <p class='foundation-readout'>Page {{this.page}} of 12</p>
+      </:example>
+      <:api as |Args|>
+        <Args.Number @name='page' @value={{this.page}} @min={{1}} @max={{12}} @onInput={{this.setPage}} />
+        <Args.Number @name='pages' @value={{12}} @min={{1}} />
+        <Args.Number @name='defaultPage' @defaultValue={{1}} />
+        <Args.Action @name='onPageChange' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>.foundation-readout { margin: 8px 0 0; font-family: var(--font-mono); font-size: var(--text-ui-xs); color: var(--muted-foreground); }</style>
+  </template>
+}
+
+export const DEMOS_PAGINATION: Record<string, unknown> = {
+  Pagination: PaginationUsage,
+};