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

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

@@ -0,0 +1,43 @@
+## What it is
+
+**EmptyState** under the name shadcn and Ant use. The export is the same class — `import { Empty } from './empty';` resolves to EmptyState — so the tile exists for a port of a shadcn `Empty` block or an agent whose first guess is the shorter word. The contract and the depth are on **EmptyState**; this page maps the shadcn parts onto it. A page-level 404 or success scene is **Result**; a missing linked card is **BrokenLink**; a region that is _loading_ is **Skeleton**, not empty.
+
+## The contract
+
+```
+@title           — required; the absence is always named
+@message?        — the explanation, kept to a 34ch measure
+@texture?        — the tinted radial behind the title (default true)
+@separator?      — the word between two actions (default 'or')
+@size?           — 's' for the compact well inside a card section, 'm' (default) for a page section
+<:default>       — the message with markup in it; wins over @message
+<:action>  <:altAction>
+```
+
+**`@title` is required.** shadcn lets `EmptyTitle` be omitted; here an empty state that does not say what is missing is not accepted.
+
+## Prior art
+
+**shadcn `Empty`** is a composition of parts — `Empty`, `EmptyHeader`, `EmptyMedia` (with an `icon` variant), `EmptyTitle`, `EmptyDescription`, `EmptyContent` — styled as a dashed, centred well. **Ant `Empty`** takes `image` (with two built-in illustrations), `description` and children for the action.
+
+Where this is better: nothing to compose for the common case, a required title, and a generated texture in place of stock illustration so the state reads as designed with zero assets. The `<:altAction>` block gives the second honest path equal billing, which neither kit models.
+
+Where it is thinner: there is no media slot, so shadcn's `EmptyMedia` and Ant's `image` have nowhere to land. There are two sizes, the compact well (`@size='s'`) and the page-section default.
+
+## Accessibility
+
+EmptyState's. No APG pattern governs it. The title is a `<div>` styled as a heading, not an `<h*>`, so it does not structure the region; nothing announces the transition to empty, so a filter that clears a table does so silently — a `role='status'` on the caller's container is the fix. The action is an ordinary tab stop, which is right. If the state replaces a `<tbody>`, the table's semantics go with it; render inside the table instead.
+
+## Theming
+
+EmptyState's tokens: `--canvas` (the recess, deliberately not `--card`), `--primary` (the texture tint), `--font-serif` and `--text-heading` (title), `--muted-foreground` and `--text-ui-md` (message), `--radius-surface`, `--space-2`, `--space-3`, `--space-6`, `--space-9` (at `@size='s'` the padding is a fixed `1rem` and the title reads `--boxel-font-size`). A theme must define `--font-serif` and keep `--canvas` distinguishable from `--card`. Nothing is themed under an Empty name.
+
+## React ecosystem
+
+| shadcn / Ant                             | Pretui                                                |
+| ---------------------------------------- | ----------------------------------------------------- |
+| `<EmptyTitle>`                           | `@title`                                              |
+| `<EmptyDescription>` / Ant `description` | `@message`, or `<:default>` when it carries markup    |
+| `<EmptyContent>` / Ant children          | `<:action>`, and `<:altAction>` for the second path   |
+| `<EmptyMedia>` / Ant `image`             | no equivalent; the texture stands in for art          |
+| `<EmptyHeader>`                          | no equivalent; title and message are laid out for you |

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

@@ -0,0 +1,33 @@
+// Pretui — Empty usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Empty } from './empty';
+
+const EmptyUsage: TemplateOnlyComponent = <template>
+  <FreestyleUsage
+    @name='Empty'
+    @description='EmptyState under the shadcn / Ant name: a named absence with an optional message and action. Reach for this import when a port or an agent already speaks that vocabulary; the component, its contract and its writeup are EmptyState’s.'
+    @source="<Empty @title='No lots match' @message='Try clearing…'><:action>…</:action></Empty>"
+  >
+    <:example>
+      <Empty
+        @title='No lots match'
+        @message='Try clearing the origin and harvest filters.'
+      >
+        <:action><Button @variant='secondary'>Clear filters</Button></:action>
+      </Empty>
+    </:example>
+    <:api as |Args|>
+      <Args.String @name='title' @value='No lots match' @description='Required. shadcn’s EmptyTitle.' />
+      <Args.String @name='message' @value='Try clearing the origin and harvest filters.' @description='shadcn’s EmptyDescription, Ant’s description.' />
+      <Args.Bool @name='texture' @defaultValue={{true}} />
+      <Args.Yield @name='action' @description='shadcn’s EmptyContent.' />
+      <Args.Yield @name='altAction' @description='The second way in, given equal billing.' />
+    </:api>
+  </FreestyleUsage>
+</template>;
+
+export const DEMOS_EMPTY: Record<string, unknown> = {
+  Empty: EmptyUsage,
+};

package/bundled-realms/pretui/components/entity-display.gts

@@ -0,0 +1,126 @@
+// Pretui — EntityDisplay: an entity's icon or thumbnail with its name and tags.
+import Component from '@glimmer/component';
+import { Chip } from './chip';
+
+// ── EntityDisplay ────────────────────────────────────────────────────────
+// Merges entity-icon-display + entity-thumbnail-display semantics: a visual
+// slot (icon or thumbnail dress via @variant) beside a title row with an
+// optional Chip tag, then a subtitle line — or the <:meta> block when the
+// second row needs real markup (meta wins over @subtitle, mirroring the
+// block-beats-arg precedence of the boxel-ui originals).
+export interface EntityDisplaySignature {
+  Args: {
+    title?: string;
+    subtitle?: string;
+    tag?: string;
+    variant?: 'icon' | 'thumbnail';
+    center?: boolean;
+    underline?: boolean;
+  };
+  Blocks: { visual?: []; meta?: [] };
+  Element: HTMLElement;
+}
+
+export class EntityDisplay extends Component<EntityDisplaySignature> {
+  get variant(): 'icon' | 'thumbnail' {
+    return this.args.variant ?? 'icon';
+  }
+  <template>
+    <div
+      class='pretui-entity'
+      data-variant={{this.variant}}
+      data-center={{if @center 'true'}}
+      data-test-pretui-entity-display
+      ...attributes
+    >
+      {{#if (has-block 'visual')}}
+        <span class='pretui-entity-visual'>{{yield to='visual'}}</span>
+      {{/if}}
+      <div class='pretui-entity-info'>
+        <div class='pretui-entity-titlerow'>
+          {{#if @title}}
+            <span
+              class='pretui-entity-title'
+              data-underline={{if @underline 'true'}}
+            >{{@title}}</span>
+          {{/if}}
+          {{#if @tag}}
+            <Chip @label={{@tag}} @dot={{false}} />
+          {{/if}}
+        </div>
+        {{#if (has-block 'meta')}}
+          <div class='pretui-entity-meta'>{{yield to='meta'}}</div>
+        {{else if @subtitle}}
+          <div class='pretui-entity-meta'>{{@subtitle}}</div>
+        {{/if}}
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-entity {
+          display: flex;
+          align-items: flex-start;
+          gap: var(--space-3, 8px);
+          min-width: 0;
+        }
+        .pretui-entity[data-center] {
+          align-items: center;
+        }
+        .pretui-entity-visual {
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          flex: none;
+        }
+        .pretui-entity[data-variant='icon'] .pretui-entity-visual {
+          width: var(--pretui-entity-visual-size, 18px);
+          height: var(--pretui-entity-visual-size, 18px);
+          color: var(--muted-foreground);
+        }
+        .pretui-entity[data-variant='icon'] .pretui-entity-visual :deep(svg) {
+          width: 100%;
+          height: 100%;
+        }
+        .pretui-entity[data-variant='thumbnail'] .pretui-entity-visual {
+          width: var(--pretui-entity-visual-size, 22px);
+          height: var(--pretui-entity-visual-size, 22px);
+          border-radius: var(--radius-chip, 6px);
+          overflow: hidden;
+          background: var(--inset, var(--boxel-100));
+          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+        }
+        .pretui-entity-info {
+          display: grid;
+          gap: 2px;
+          min-width: 0;
+        }
+        .pretui-entity-titlerow {
+          display: flex;
+          align-items: center;
+          flex-wrap: wrap;
+          gap: 6px;
+          min-width: 0;
+        }
+        .pretui-entity-title {
+          font-size: var(--text-ui-md, 12.5px);
+          font-weight: 600;
+          color: var(--foreground);
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-entity-title[data-underline] {
+          text-decoration: underline;
+          text-underline-offset: 2px;
+        }
+        .pretui-entity-meta {
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/entity-display.md

@@ -0,0 +1,50 @@
+## What it is
+
+A record's identity row: a visual (icon or thumbnail) beside a title, an optional tag **Chip**, and a subtitle or meta line. Use it as the standard way a card, a person, a file or a linked record is presented in a list, a search result, a picker row or a header. If the record is a compact inline reference inside prose or a field, that is **RecordPill**. If it is a full tile, **FittedCard**. If the reference is broken, **BrokenLink**.
+
+## The contract
+
+```
+@title?, @subtitle?, @tag?
+@variant? 'icon' | 'thumbnail'   (default 'icon')
+@center?, @underline?
+<:visual>  <:meta>
+Element: HTMLElement
+```
+
+**`@variant` changes the visual slot's dress, not its content.** You always supply the visual through `<:visual>`; `icon` sizes and pads it as a glyph, `thumbnail` as an image. That factoring is why one component replaces two.
+
+**`<:meta>` beats `@subtitle`.** When the second row needs real markup — a **RelativeTime**, a **Token**, two facts separated by a dot — use the block; when it is a string, use the arg. The block-wins precedence mirrors the boxel-ui originals this merges, so a port from either behaves the same.
+
+`@center` centres the whole row (for a card header rather than a list row); `@underline` adds the hover underline that signals the row is a link target.
+
+## Prior art
+
+This is a **fresh merge of boxel-ui's `entity-icon-display` and `entity-thumbnail-display`** into one component, with the tag row reusing Pretui's **Chip**. Two components differing only in how their visual slot is dressed is exactly the kind of duplication a `@variant` axis exists to remove.
+
+Against the field: **React Spectrum** has no entity display; the closest is a `ListView` `Item` with `Text`/`Image` slots. **Web Awesome** has none. **shadcn** has none — the recipe is a flex row with an avatar and two spans, rewritten in every project. **SLDS's `media-object`** is the closest named pattern, and this is essentially that plus a tag.
+
+Where making it a component pays off is the same argument as **Toolbar**'s: the details every hand-rolled media row gets wrong — the title truncating rather than the visual shrinking, the subtitle's ink and size, the tag's alignment — are decided once. And because the tag is a **Chip** rather than a bespoke pill, a tag here and a status elsewhere are visibly the same object.
+
+Where it is thin: **no trailing/actions slot.** A list row almost always wants something on the right — a chevron, a **Menu**, a count — and there is no block for it, so you wrap the whole thing in your own flex row. That is the clearest addition. Also no size axis, and no selected/active state.
+
+## Accessibility
+
+No pattern governs it; it is content layout, subject to WCAG **1.3.1** and **2.4.4 Link Purpose**.
+
+Gaps, and the first two matter most because of where this component is used:
+
+- **`@underline` implies the row is clickable, but nothing here makes it a link.** The component renders a `<div>`; the interactivity is entirely the caller's. The failure mode is the standard card-row one: a click handler on the wrapper `<div>` gives a target that is not focusable, not keyboard-operable and not announced as actionable. If an EntityDisplay is clickable, wrap it in a real `<a>` or `<button>`, and make sure it is not _also_ containing one.
+- **The visual is whatever you yield, and nothing enforces its alt text.** A thumbnail `<img>` with no `alt` announces its filename; an icon with a `<title>` announces twice. For a decorative visual beside a title that already names the record, `aria-hidden` on the visual is usually correct — and nothing prompts for it.
+- **Title, tag and subtitle are three sibling elements with no grouping.** A screen-reader user hears "Q3 Report Draft 3 days ago" as one run with no indication of which part is a status and which is a timestamp. **Chip**'s own note applies: a chip has no relationship to the property it is the value of.
+- **The title is not a heading.** In a card header (`@center`) that is often what it should be, and there is no `@headingLevel` — the same gap **Panel**, **Toolbar** and **EmptyState** have.
+- **Truncation behaviour is unstated** — check whether a long title ellipsizes without a full-text fallback, which is the **Toolbar** problem again.
+- The subtitle's `--muted-foreground` at small size is the usual **1.4.3** thing to verify per theme.
+
+## Theming
+
+`--foreground` (title), `--muted-foreground` (subtitle and meta), plus **Chip**'s full token set for the tag and whatever the visual brings. `data-variant` and `data-center` are reflected on the root, so a stylesheet can dress icon rows and thumbnail rows differently without the component exposing more args.
+
+The visual slot's icon and thumbnail sizes are fixed per variant. Because the tag is a real **Chip**, a theme that retunes `--pretui-chip-mix` moves entity tags along with every other chip — which is the intent, and worth knowing if you were about to tune chips for a status list and forgot they also appear here.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/error-summary.gts

@@ -0,0 +1,321 @@
+// Pretui — ErrorSummary: the list of blocking issues a refused submit focuses.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import { guidFor } from '@ember/object/internals';
+import { modifier } from 'ember-modifier';
+import { iconFor } from '../icon-registry';
+import { FormContext, isBlocking, normalizeSeverity, sortIssues } from '../internal/forms-core';
+import type { FormIssue, FormSeverity } from '../internal/forms-core';
+
+// ── ErrorSummary ─────────────────────────────────────────────────────────
+// The form-level list, and the reason nothing gets dropped.
+//
+// Ported in spirit from the GOV.UK / React Spectrum error-summary pattern
+// (neither SLDS nor React Spectrum ships one as a component). Two deltas
+// from the pattern as usually written:
+//
+//   • Rows are BUTTONS, not `href="#id"` anchors. An anchor mutates the URL,
+//     and inside a Boxel card the URL is the card's — a fragment jump there
+//     is a navigation, not a focus move. The button calls focusPath() and
+//     lands focus on exactly the same element the anchor would have.
+//   • The shell is NOT Alert, even though it would have been
+//     one line. Alert hardcodes role='alert' (danger) / role='status' — a
+//     live region that would re-announce the whole list on every keystroke in
+//     live mode, and double-announce at submit on top of the focus move.
+//     The summary announces by TAKING FOCUS, which is the whole point of it.
+//
+// The correctness contract: every issue in the form appears here. An issue
+// whose targetPath matched no rendered field is rendered with an explicit
+// "not on this form" marking rather than being filtered away, because a
+// dropped error is worse than an ugly one.
+
+interface SummaryRow {
+  issue: FormIssue;
+  severity: FormSeverity;
+  routed: boolean;
+}
+
+export interface ErrorSummarySignature {
+  Args: {
+    /** Issues to summarise, when used WITHOUT a Form. */
+    issues?: FormIssue[];
+    /** The owning form's context. Supplied automatically by `form.Summary`. */
+    form?: FormContext;
+    /** Heading text. Defaults to a count sentence. */
+    title?: string;
+    /** aria-level for the heading — a card does not know its host's outline,
+     *  so the level is a knob rather than a hardcoded <h2>. Default 3. */
+    headingLevel?: number;
+    /** Include warnings and info alongside errors. Default false. */
+    showAdvisory?: boolean;
+    /** Render even before a submit has been attempted. */
+    always?: boolean;
+    /** Add role='alert'. Off by default: the summary announces by taking
+     *  focus, and a live region on top of that double-announces. */
+    announce?: boolean;
+  };
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+export class ErrorSummary extends Component<ErrorSummarySignature> {
+  private guid = guidFor(this);
+
+  get id(): string {
+    return `${this.guid}-summary`;
+  }
+
+  constructor(owner: unknown, args: ErrorSummarySignature['Args']) {
+    super(owner as never, args);
+    this.args.form?.registerSummary(this.id);
+  }
+  willDestroy(): void {
+    super.willDestroy();
+    this.args.form?.unregisterSummary(this.id);
+  }
+
+  get sourceIssues(): FormIssue[] {
+    return this.args.issues ?? this.args.form?.issues ?? [];
+  }
+  get rows(): SummaryRow[] {
+    let issues = this.args.showAdvisory
+      ? sortIssues(this.sourceIssues)
+      : sortIssues(this.sourceIssues.filter(isBlocking));
+    return issues.map((issue) => ({
+      issue,
+      severity: normalizeSeverity(issue.severity),
+      routed: this.isRouted(issue),
+    }));
+  }
+  private isRouted(issue: FormIssue): boolean {
+    let form = this.args.form;
+    if (!form) {
+      return false;
+    }
+    // Before the first registration snapshot lands, assume routed — the
+    // alternative is a one-frame flash of "not on this form" on every issue.
+    return !form.settled || form.isClaimed(issue.targetPath);
+  }
+  /** Only mark unrouted rows when there is a form to be unrouted FROM. */
+  get marksUnrouted(): boolean {
+    return this.args.form !== undefined;
+  }
+  get visible(): boolean {
+    if (this.rows.length === 0) {
+      return false;
+    }
+    if (this.args.always) {
+      return true;
+    }
+    let form = this.args.form;
+    if (!form) {
+      return true;
+    }
+    // A submit-mode form is not "in error" until the user has tried.
+    return form.mode !== 'submit' || form.submitAttempted;
+  }
+  get title(): string {
+    if (this.args.title) {
+      return this.args.title;
+    }
+    let count = this.rows.length;
+    return count === 1
+      ? 'There is 1 issue to fix'
+      : `There are ${count} issues to fix`;
+  }
+  get headingLevel(): string {
+    return String(this.args.headingLevel ?? 3);
+  }
+  get role(): string | undefined {
+    return this.args.announce ? 'alert' : undefined;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- icons are
+  // resolved dynamically from the registry, which is any-typed by design
+  get glyph(): any {
+    return iconFor('circle-alert');
+  }
+
+  claimFocus = modifier((el: HTMLElement) => {
+    if (this.args.form?.takeSummaryFocus()) {
+      el.focus();
+    }
+  });
+
+  goTo = (row: SummaryRow): void => {
+    this.args.form?.focusPath(row.issue.targetPath);
+  };
+
+  <template>
+    {{#if this.visible}}
+      <div
+        class='pretui-error-summary'
+        id={{this.id}}
+        tabindex='-1'
+        role={{this.role}}
+        {{this.claimFocus}}
+        data-test-pretui-error-summary
+        ...attributes
+      >
+        <div class='pretui-error-summary-head'>
+          {{#let this.glyph as |Glyph|}}
+            {{#if Glyph}}
+              <Glyph
+                class='pretui-error-summary-glyph'
+                width='15'
+                height='15'
+                role='presentation'
+              />
+            {{/if}}
+          {{/let}}
+          <div
+            class='pretui-error-summary-title'
+            role='heading'
+            aria-level={{this.headingLevel}}
+          >{{this.title}}</div>
+        </div>
+        {{#if (has-block)}}
+          <p class='pretui-error-summary-intro'>{{yield}}</p>
+        {{/if}}
+        <ul class='pretui-error-summary-list'>
+          {{#each this.rows key='@index' as |row|}}
+            <li class='pretui-error-summary-row' data-severity={{row.severity}}>
+              {{#if row.routed}}
+                <button
+                  type='button'
+                  class='pretui-error-summary-link'
+                  {{on 'click' (fn this.goTo row)}}
+                >{{row.issue.message}}</button>
+              {{else}}
+                <span class='pretui-error-summary-orphan'>
+                  <span class='pretui-error-summary-text'>{{row.issue.message}}</span>
+                  {{#if this.marksUnrouted}}
+                    <span
+                      class='pretui-error-summary-badge'
+                      title={{row.issue.targetPath}}
+                    >no field on this form</span>
+                  {{/if}}
+                </span>
+              {{/if}}
+            </li>
+          {{/each}}
+        </ul>
+      </div>
+    {{/if}}
+    <style scoped>
+      @layer PretComponent {
+        .pretui-error-summary {
+          --pretui-issue-hue: var(--pretui-issue-error, var(--destructive));
+          display: grid;
+          gap: var(--space-3, 8px);
+          padding: var(--space-4, 11px) var(--space-4, 11px)
+            calc(var(--space-4, 11px) - 2px);
+          border-radius: var(--radius-surface, 10px);
+          background: color-mix(
+            in oklch,
+            var(--pretui-issue-hue) var(--pretui-chip-mix, 10%),
+            var(--card)
+          );
+          box-shadow: var(
+            --pretui-shadow-card,
+            0 0 0 1px
+              color-mix(in oklch, var(--pretui-issue-hue) 28%, var(--border))
+          );
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+        }
+        .pretui-error-summary:focus {
+          outline: none;
+        }
+        .pretui-error-summary:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-error-summary-head {
+          display: flex;
+          align-items: center;
+          gap: 7px;
+          min-width: 0;
+        }
+        .pretui-error-summary-glyph {
+          flex: none;
+          --icon-color: var(--pretui-issue-hue);
+          color: var(--pretui-issue-hue);
+        }
+        .pretui-error-summary-title {
+          font-size: var(--text-ui-md, 12.5px);
+          font-weight: 600;
+          color: color-mix(
+            in oklch,
+            var(--foreground) 45%,
+            var(--pretui-issue-hue)
+          );
+        }
+        .pretui-error-summary-intro {
+          margin: 0;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+        }
+        .pretui-error-summary-list {
+          margin: 0;
+          padding: 0 0 0 var(--space-4, 11px);
+          display: grid;
+          gap: 3px;
+        }
+        .pretui-error-summary-row {
+          --pretui-issue-hue: var(--pretui-issue-error, var(--destructive));
+          font-size: var(--text-ui-sm, 11.5px);
+          line-height: 17px;
+          color: color-mix(
+            in oklch,
+            var(--foreground) 22%,
+            var(--pretui-issue-hue)
+          );
+          list-style: disc;
+        }
+        .pretui-error-summary-row[data-severity='warning'] {
+          --pretui-issue-hue: var(--pretui-issue-warning, var(--warning, var(--boxel-warning)));
+        }
+        .pretui-error-summary-row[data-severity='info'] {
+          --pretui-issue-hue: var(--pretui-issue-info, var(--pretui-info, var(--boxel-blue)));
+        }
+        .pretui-error-summary-link {
+          padding: 0;
+          border: 0;
+          background: none;
+          font: inherit;
+          color: inherit;
+          text-align: left;
+          text-decoration: underline;
+          text-underline-offset: 2px;
+          cursor: pointer;
+        }
+        .pretui-error-summary-link:hover {
+          text-decoration-thickness: 2px;
+        }
+        .pretui-error-summary-link:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+          border-radius: 3px;
+        }
+        .pretui-error-summary-orphan {
+          display: inline-flex;
+          align-items: baseline;
+          gap: 6px;
+          flex-wrap: wrap;
+        }
+        .pretui-error-summary-badge {
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-xs, 11px);
+          letter-spacing: var(--track-eyebrow, 0.08em);
+          text-transform: uppercase;
+          padding: 0 5px;
+          border-radius: 4px;
+          color: var(--muted-foreground);
+          background: var(--inset, var(--boxel-100));
+          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/error-summary.md

@@ -0,0 +1,60 @@
+## What it is
+
+The form-level list of everything wrong, and the reason nothing gets dropped. Render it at the top of a **Form** so a refused submit has somewhere to land, and so a user can see the whole problem before hunting for it. It is not a replacement for per-field messages — **FormField** still renders its own — it is the index. For a single message about the form as a whole, use **Alert**; for one issue outside a field, use **FieldError**.
+
+## The contract
+
+```
+@issues?          — when used without a Form
+@form?            — supplied automatically by form.Summary
+@title?           — defaults to a count sentence
+@headingLevel?    — aria-level, default 3
+@showAdvisory?    — include warnings and info, default false
+@always?          — render before a submit has been attempted
+@announce?        — add role='alert', off by default
+<:default>
+```
+
+**`@headingLevel` is a knob, not a hardcoded `<h2>`.** A card does not know its host's outline, so forcing a level would break document structure wherever the card is embedded. This is a Boxel-specific constraint the reference implementations do not have, and getting it wrong produces heading-order violations in every consuming page.
+
+**The correctness contract: every issue in the form appears here.** An issue whose `targetPath` matched no rendered field is rendered with an explicit "not on this form" marking rather than being filtered away. A dropped error is worse than an ugly one, and this is the only component in the territory that can prove nothing was swallowed.
+
+The `unroutedIssues` computation depends on `ClaimSet.settled` — a flag that distinguishes "no field has claimed this path" from "no field has registered yet". Without it the summary would flash every issue as unrouted on first paint.
+
+## Prior art
+
+The canonical spec is **GOV.UK's Error Summary**: render at the top of `<main>` before the `<h1>`, wrap in `role="alert"`, an `<h2>` reading "There is a problem", a `<ul>` of links each `href="#fieldId"`, move keyboard focus to the summary on submit, and keep the summary text verbatim-identical to the inline message. **React Spectrum** and **SLDS** ship neither — this pattern exists as guidance, not as a component, in both.
+
+Two deliberate deltas from the pattern as usually written:
+
+1. **Rows are buttons, not `href="#id"` anchors.** An anchor mutates the URL, and inside a Boxel card the URL is the _card's_ — a fragment jump there is a navigation, not a focus move. The button calls `focusPath()` and lands focus on exactly the element the anchor would have. This is the right call in this environment and it is worth noting that it costs you the ability to copy a link to a specific error.
+2. **The shell is not **Alert\***\*, even though it would have been one line. Alert hardcodes `role="alert"` (danger) or `role="status"` — a live region that would re-announce the whole list on every keystroke in `live` mode, and double-announce at submit on top of the focus move. **The summary announces by taking focus\*\*, which is the whole point of it.
+
+The third improvement over the pattern: GOV.UK's summary lists only the errors it was given. Pretui's marks unrouted issues explicitly, which is the difference between a summary you can trust and one you hope is complete.
+
+## Accessibility
+
+No APG pattern; the governing criteria are WCAG **3.3.1 Error Identification** and, with well-worded messages, **3.3.3 Error Suggestion**. The behavioural contract is GOV.UK's.
+
+What is right:
+
+- **Announcement by focus, not by live region.** `@announce` defaults to off, deliberately. Pairing `role="alert"` with a focus move double-announces; in `live` mode a live region would narrate the whole list on every keystroke.
+- **Focus routing works through collapsed sections.** A summary row calls `focusPath()`, which walks up the section ancestry, opens each collapsed **FormSection** and clears its `hidden` attribute in the same tick so focus lands immediately. A user is never sent to a control they cannot see.
+- Each row's target is resolved by preferring the yielded `controlId`, falling back to the first focusable element inside `[data-pretui-form-control]` (deliberately scoped so the help button is not a candidate), and finally to the field root, which carries `tabindex="-1"`.
+- Heading level is authorable, so the summary does not break the host document's outline.
+
+Gaps:
+
+- **The summary is not focused automatically on render** — it is focused only when `Form.focusInvalid()` runs with `@focusOnInvalid='summary'`, or as the fallback when no invalid field element can be found. GOV.UK's pattern focuses the summary on page load after a server-side rejection; there is no equivalent hook here, so a form re-rendered with issues from a server round trip announces nothing until the user submits again.
+- **Messages are printed verbatim from the rule author.** That is the right architectural choice — rewriting rule copy in a component is how enterprise forms end up lying about what failed — but it means WCAG 3.3.3 conformance depends entirely on how the rules were written, and no component can save you there.
+- **`@showAdvisory` defaults to false**, so warnings and info are absent from the summary by default while still appearing on their fields. That is defensible (the summary is a blocking-issues index) but it means the summary is _not_ a complete list of what the form is saying unless you turn it on.
+- The unrouted marking is visible text, not a distinct role or state — assistive tech hears it as part of the row, which is adequate but undifferentiated.
+- Buttons rather than links means the rows do not appear in a screen reader's link list, which is where some users would look for them.
+
+## Theming
+
+`--destructive`, `--warning`, `--pretui-info` and their on-colours for the severity tiers; `--card` or `--inset` for the shell, `--border` and `--pretui-shadow-hairline` for its edge, `--foreground` and `--muted-foreground` for heading and body ink, plus **Token**'s tokens when rule provenance is shown.
+
+Severity is carried by a glyph and a hue, as in **Alert**, so a field message, a summary row and a banner about the same thing read as one system. A theme that retunes those hues must retune them in all three places or the correspondence breaks — and because severity is conveyed by glyph _and_ hue, it survives WCAG 1.4.1 even if a theme's hues collapse.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.