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

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

@@ -0,0 +1,244 @@
+// Pretui — Feed: the WAI-ARIA APG feed pattern with one roving tab stop.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { focusWhen, listen, rovingTabindex } from '../focus';
+import { EmptyState } from './empty-state';
+import { Skeleton } from './skeleton';
+
+// ── Feed ─────────────────────────────────────────────────────────────────
+// The ARIA feed pattern: a stream of independently-authored articles the
+// reader pages through.
+//
+// One deliberate deviation from the APG example, and it is the whole point:
+// APG puts tabindex='0' on EVERY article, so a 200-item feed is 200 tab stops
+// and Tab stops being a way to leave the region. This feed uses a roving
+// tabindex — exactly one article is in the tab sequence, Tab leaves the feed
+// immediately, and Page Down / Page Up / Home / End move between articles.
+// Because Tab already escapes, APG's Control+Home / Control+End escape hatches
+// are unnecessary; plain Home/End jump to the first/last article instead, and
+// are ignored when focus sits inside a control within an article (so typing
+// Home in a reply box still moves the caret).
+//
+// Content is a SLOT, not a prop bag (Law 7): callers render their own article
+// bodies. The kit's Skeleton covers loading and EmptyState covers empty, so a
+// feed never has a blank frame.
+
+/**
+ * The MINIMUM a feed item must carry. It is a lower bound, not the item type:
+ * <Feed> is generic over T extends FeedItem, so a caller passing
+ * `Activity[]` gets `Activity` back in the <:item> block rather than an
+ * open bag of `unknown`. The index signature stays only so an untyped
+ * fixture is still legal — see `defaultRowKey` in data-component.gts for the
+ * kit-wide row-key contract this `id` satisfies.
+ */
+export interface FeedItem {
+  /** stable id — the {{#each}} key and the roving-focus key */
+  id: string;
+  /** accessible name for this article; role='feed' requires each article to
+   * be labelled, so one is synthesised from its position when omitted */
+  label?: string;
+  [key: string]: unknown;
+}
+
+export interface FeedSignature<T extends FeedItem = FeedItem> {
+  Args: {
+    /** the stream, in the order it should read */
+    items: T[];
+    /** accessible name for the feed region (default 'Activity') */
+    label?: string;
+    /** true while more items are loading — sets aria-busy and shows the
+     * skeleton tail */
+    loading?: boolean;
+    /** how many skeleton rows the loading tail shows (default 2) */
+    skeletonCount?: number;
+  };
+  Blocks: {
+    /** one article's content — receives the item (in the caller's own row
+     * type) and its 0-based index */
+    item: [item: T, index: number];
+    /** replaces the default EmptyState when there is nothing to show */
+    empty?: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Feed<T extends FeedItem = FeedItem> extends Component<
+  FeedSignature<T>
+> {
+  @tracked private focusIndex = 0;
+  @tracked private navigating = false;
+
+  get items(): T[] {
+    return this.args.items ?? [];
+  }
+  get label(): string {
+    return this.args.label ?? 'Activity';
+  }
+  get count(): number {
+    return this.items.length;
+  }
+  get isEmpty(): boolean {
+    return this.count === 0 && !this.args.loading;
+  }
+  get busy(): string {
+    return this.args.loading ? 'true' : 'false';
+  }
+  get skeletonRows(): number[] {
+    let n = Math.max(1, Math.floor(this.args.skeletonCount ?? 2));
+    let out: number[] = [];
+    for (let i = 0; i < n; i++) {
+      out.push(i);
+    }
+    return out;
+  }
+  posinset = (index: number): number => index + 1;
+  itemLabel = (item: T, index: number): string =>
+    item.label ?? `Update ${index + 1} of ${this.count}`;
+  isRoving = (index: number): boolean =>
+    index === Math.min(this.focusIndex, Math.max(0, this.count - 1));
+  isFocusTarget = (index: number): boolean =>
+    this.navigating && this.isRoving(index);
+
+  private moveTo(index: number) {
+    if (index < 0 || index >= this.count) {
+      return;
+    }
+    this.navigating = true;
+    this.focusIndex = index;
+  }
+  private indexFromEvent(event: Event): number | undefined {
+    let target = event.target as HTMLElement | null;
+    let el = target?.closest('[data-feed-index]') as HTMLElement | null;
+    let raw = el?.dataset.feedIndex;
+    return raw === undefined ? undefined : Number(raw);
+  }
+
+  // Same early return as Tree.onFocusIn, for the same reason: focusWhen's
+  // el.focus() re-enters this handler synchronously during render, and
+  // writing tracked state there would be a backtracking re-render.
+  onFocusIn = (event: Event) => {
+    let index = this.indexFromEvent(event);
+    if (index === undefined || this.isRoving(index)) {
+      return;
+    }
+    this.navigating = false;
+    this.focusIndex = index;
+  };
+
+  onKeydown = (event: Event) => {
+    let ev = event as KeyboardEvent;
+    if (!this.count) {
+      return;
+    }
+    let index = Math.min(this.focusIndex, this.count - 1);
+    let target = ev.target as HTMLElement | null;
+    let onArticle = !!target?.matches('[data-feed-index]');
+    if (ev.key === 'PageDown') {
+      ev.preventDefault();
+      this.moveTo(Math.min(this.count - 1, index + 1));
+    } else if (ev.key === 'PageUp') {
+      ev.preventDefault();
+      this.moveTo(Math.max(0, index - 1));
+    } else if (ev.key === 'Home' && onArticle) {
+      ev.preventDefault();
+      this.moveTo(0);
+    } else if (ev.key === 'End' && onArticle) {
+      ev.preventDefault();
+      this.moveTo(this.count - 1);
+    }
+  };
+
+  <template>
+    <div class='pretui-feed-host' data-test-pretui-feed ...attributes>
+      {{#if this.isEmpty}}
+        {{#if (has-block 'empty')}}
+          {{yield to='empty'}}
+        {{else}}
+          <EmptyState
+            @title='Nothing has happened yet'
+            @message='Activity from your suppliers and lots will collect here.'
+          />
+        {{/if}}
+      {{else}}
+        <div
+          class='pretui-feed'
+          role='feed'
+          aria-label={{this.label}}
+          aria-busy={{this.busy}}
+          {{listen 'keydown' this.onKeydown}}
+          {{listen 'focusin' this.onFocusIn}}
+        >
+          {{#each this.items key='id' as |item index|}}
+            <article
+              class='pretui-feed-item'
+              data-feed-index={{index}}
+              aria-posinset={{this.posinset index}}
+              aria-setsize={{this.count}}
+              aria-label={{this.itemLabel item index}}
+              {{rovingTabindex (this.isRoving index)}}
+              {{focusWhen (this.isFocusTarget index)}}
+            >
+              {{yield item index to='item'}}
+            </article>
+          {{/each}}
+        </div>
+        {{#if @loading}}
+          {{! the skeleton tail sits OUTSIDE role='feed' — a feed's children
+              must be articles, and a placeholder is not an article }}
+          <div class='pretui-feed-loading' aria-hidden='true'>
+            {{#each this.skeletonRows key='@index' as |row|}}
+              <div class='pretui-feed-skeleton' data-row={{row}}>
+                <Skeleton @width='38%' @height='11px' />
+                <Skeleton @height='11px' />
+                <Skeleton @width='72%' @height='11px' />
+              </div>
+            {{/each}}
+          </div>
+        {{/if}}
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-feed-host {
+          min-width: 0;
+        }
+        .pretui-feed {
+          display: grid;
+          gap: var(--pretui-feed-gap, 10px);
+          min-width: 0;
+        }
+        .pretui-feed-item {
+          position: relative;
+          padding: var(--space-4, 11px) 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)
+          );
+          min-width: 0;
+        }
+        .pretui-feed-item:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-feed-loading {
+          display: grid;
+          gap: var(--pretui-feed-gap, 10px);
+          margin-top: var(--pretui-feed-gap, 10px);
+        }
+        .pretui-feed-skeleton {
+          display: grid;
+          gap: 7px;
+          padding: var(--space-4, 11px) 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>
+}

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

@@ -0,0 +1,56 @@
+## What it is
+
+A stream of independently-authored articles the reader pages through: an activity log, a comment thread, a notifications list, a chat transcript. Use it when items arrive over time and each is a self-contained thing to read. If the sequence is fixed and historical, **Timeline** is simpler and has an `<ol>`'s numbering. If the items are uniform records with columns, **DataGrid**. If they are tiles, **Grid** or **Masonry**.
+
+## The contract
+
+```
+@items: T[]   (T extends FeedItem: { id, label?, …})
+@label? ('Activity'), @loading?, @skeletonCount? (default 2)
+<:item as |item, index|>
+```
+
+**Content is a slot, not a prop bag.** Callers render their own article bodies — Law 7 of the kit. The consequence is that a Feed knows nothing about what is in it, which is why `label` exists on the item (see below).
+
+**It is generic over `T extends FeedItem`.** `FeedItem` is a lower bound, not the item type: pass `Activity[]` and the `<:item>` block yields `Activity`, not `unknown`. The index signature is there only so an untyped fixture stays legal. Compare **Board**, which is deliberately _not_ generic because its yielded value is a position rather than a record — the two decisions are the considered opposite of each other.
+
+**`@loading` sets `aria-busy` and renders a skeleton tail**, and **the tail sits outside `role="feed"`** — a feed's children must all be articles, so putting skeletons inside would produce invalid structure. `EmptyState` covers the empty case, so a feed never has a blank frame.
+
+## Prior art
+
+**Activity feeds normally ship as unlabelled `<div>` soup** — that is the whole comparison set, because Radix, Web Awesome, React Spectrum and shadcn ship no feed component at all. The pattern's only real specification is APG's **Feed**.
+
+So the interesting comparison is against APG itself, and Pretui deviates in one place deliberately:
+
+**APG's feed example puts `tabindex="0"` on every article.** A 200-item feed is therefore 200 tab stops, and Tab stops being a way to leave the region. This feed uses a **roving tabindex** — exactly one article is in the tab sequence, Tab leaves the feed immediately, and Page Down / Page Up / Home / End move between articles.
+
+That deviation cascades correctly: because Tab already escapes, APG's Control+Home / Control+End escape hatches become unnecessary, so **plain Home/End jump to the first and last article** instead. And they are ignored when focus sits inside a control within an article — so pressing Home in a reply box moves the caret rather than jumping the feed. That last detail is the one that separates a considered implementation from a literal one.
+
+Where it is behind a mature feed: **no virtualisation** (200 articles are 200 rendered articles), no infinite-scroll integration (`@loading` is a flag you drive), no read/unread state, and no scroll anchoring when items are prepended.
+
+## Accessibility
+
+Governing pattern: APG **Feed**. This is among the best-implemented components in the kit, and the roving-tabindex deviation is an improvement on the pattern rather than a shortcut.
+
+Present and correct: `role="feed"` with `aria-label`; `aria-busy` while loading; `role="article"` per item with `aria-posinset` and `aria-setsize`; `aria-label` on each article; a roving tabindex so the feed is one tab stop; Page Up/Page Down/Home/End between articles; and the skeleton tail excluded from the feed's children.
+
+**`aria-label` on each article is required by the pattern**, and the component synthesises one from the item's position when `label` is omitted. That is the right fallback — an unlabelled article is announced as "article" and nothing else — but a synthesised "Item 4 of 200" is much worse than "Comment by Ada Lovelace, 3 days ago". **Always pass `label`.** It is the single highest-leverage thing a caller does here.
+
+Gaps:
+
+- **New items arriving are not announced.** `aria-busy` says "loading"; nothing says "12 new items". APG's feed pattern expects the author to manage this, and a `role="status"` region — existing in the DOM before the change — is the fix. It belongs to the caller and nothing prompts for it.
+- **`aria-busy` on the feed suppresses announcements while true**, which is correct behaviour and means the region must be un-busied for anything inside to be announced afterwards.
+- **Focus is not preserved across item prepends.** If new items are unshifted onto `@items`, `aria-posinset` values shift under the reader; there is no scroll or focus anchoring.
+- **`@label` defaults to the literal `'Activity'`** — two feeds on a page are both announced identically.
+- **Articles may contain their own interactive content**, and that content joins the tab sequence normally once focus is inside an article. That is correct, and it means the "one tab stop" claim is about the _articles_, not about everything in the region.
+- **No `aria-describedby` linking an article to its own timestamp or author**; those are content the caller renders.
+
+## Theming
+
+The Feed itself paints very little — it is structure plus focus management. Consumed: `--border` or `--card` for row separation, `--text-ui-md`, and the layout spacing tokens. The loading tail is **Skeleton**'s tokens (`--inset`, `--hover`); the empty state is **EmptyState**'s (`--canvas`, `--primary`, `--font-serif`).
+
+Almost all visual weight belongs to what you yield into `<:item>`, which is the intent: a feed of comments and a feed of build results should look nothing alike, and the component's job is the semantics they share.
+
+The focused-article indicator is the one thing worth checking per theme. Because the feed has a roving tabindex, an article _will_ receive focus, and the ring on it is drawn in `--ring`; if that does not stand out against `--card`, a keyboard user paging with Page Down sees nothing move.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,250 @@
+// Pretui — Feed usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Feed } from './feed';
+import type { FeedItem } from './feed';
+import { Avatar } from './avatar';
+import { StatusChip } from './status-chip';
+import { Token } from './token';
+import { RelativeTime } from './relative-time';
+import { NOW } from '../demo-structure-data';
+
+// ── Feed ← WAI-ARIA APG feed pattern ─────────────────────────────────────
+// The sourcing desk's activity stream. FeedItem is the LOWER BOUND
+// ({ id, label?, … }) and <Feed> is generic over it, so this page passes
+// Activity[] and the <:item> block hands Activity back — item.person reads
+// straight through with neither a cast nor a per-key accessor.
+interface Activity extends FeedItem {
+  person: string;
+  action: string;
+  subject: string;
+  at: string;
+  status: string;
+  token: string;
+}
+
+const ACTIVITY: Activity[] = [
+  {
+    id: 'a1',
+    label: 'Ingrid Halvorsen approved the cupping notes for B-1181',
+    person: 'Ingrid Halvorsen',
+    action: 'approved the cupping notes for',
+    subject: 'Da Hong Pao',
+    at: '2026-08-12T08:40:00Z',
+    status: 'approved',
+    token: 'B-1181',
+  },
+  {
+    id: 'a2',
+    label: 'Yusuf Demirci cleared customs on the Fuzhou container',
+    person: 'Yusuf Demirci',
+    action: 'cleared customs on',
+    subject: 'the Fuzhou container',
+    at: '2026-08-11T17:05:00Z',
+    status: 'complete',
+    token: 'MSKU-4471290',
+  },
+  {
+    id: 'a3',
+    label: 'Mei-Lin Chua re-priced the ceremonial lots',
+    person: 'Mei-Lin Chua',
+    action: 're-priced',
+    subject: 'the ceremonial lots',
+    at: '2026-08-11T09:22:00Z',
+    status: 'in review',
+    token: '$102/kg',
+  },
+  {
+    id: 'a4',
+    label: 'Zanele Mokoena flagged the humidity log for the pu-erh room',
+    person: 'Zanele Mokoena',
+    action: 'flagged the humidity log for',
+    subject: 'the pu-erh room',
+    at: '2026-08-09T14:10:00Z',
+    status: 'blocked',
+    token: '64% RH',
+  },
+  {
+    id: 'a5',
+    label: 'Ryo Katagiri booked the autumn window with Uji Valley Growers',
+    person: 'Ryo Katagiri',
+    action: 'booked the autumn window with',
+    subject: 'Uji Valley Growers',
+    at: '2026-08-07T06:55:00Z',
+    status: 'confirmed',
+    token: 'B-1204',
+  },
+  {
+    id: 'a6',
+    label: 'Priya Raghunathan returned a lot to Nilgiri Leaf Cooperative',
+    person: 'Priya Raghunathan',
+    action: 'returned a lot to',
+    subject: 'Nilgiri Leaf Cooperative',
+    at: '2026-08-04T11:48:00Z',
+    status: 'rejected',
+    token: 'score 74',
+  },
+];
+
+class FeedUsage extends Component {
+  nowValue = NOW;
+
+  @tracked label = 'Sourcing activity';
+  @tracked loading = false;
+  @tracked skeletonCount: number | null = 2;
+  @tracked visible: number | null = 4;
+
+  setLabel = (v: string) => (this.label = v);
+  setLoading = (v: boolean) => (this.loading = v);
+  setSkeletonCount = (v: number | null) => (this.skeletonCount = v);
+  setVisible = (v: number | null) => (this.visible = v);
+
+  get items(): Activity[] {
+    let n = Math.max(0, Math.min(ACTIVITY.length, this.visible ?? 0));
+    return ACTIVITY.slice(0, n);
+  }
+  get skeletonVal() {
+    return this.skeletonCount ?? undefined;
+  }
+  get usage() {
+    let bits = ['@items={{this.items}}', `@label='${this.label}'`];
+    if (this.loading) bits.push('@loading={{true}}');
+    if (this.skeletonCount !== null && this.skeletonCount !== 2) {
+      bits.push(`@skeletonCount={{${this.skeletonCount}}}`);
+    }
+    return `<Feed ${bits.join(' ')}>\n  <:item as |item|>…</:item>\n</Feed>`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Feed'
+      @description="A stream of independently-authored updates the reader pages through — activity, notifications, comments, anything that grows at one end. It implements the WAI-ARIA APG feed pattern: role='feed' with an accessible name, aria-busy flipped while more is loading, and every article carrying aria-posinset/aria-setsize so a screen reader can say 'article 3 of 6' in an infinite list. One deliberate deviation from the APG example, and it is the point: APG puts tabindex='0' on every article, so a 200-item feed is 200 tab stops and Tab stops being a way out. This feed uses a ROVING TABINDEX — exactly one article is in the tab sequence, Tab leaves immediately, and Page Down / Page Up move between articles, with Home/End jumping to the first/last (ignored when focus sits in a control inside an article, so typing Home in a reply box still moves the caret). Because Tab already escapes, APG's Control+Home/Control+End hatches are unnecessary. Content is a slot, not a prop bag: render your own article bodies in <:item>. The loading tail is Skeleton and sits OUTSIDE role='feed' — a feed's children must be articles, and a placeholder is not one — and the empty case is EmptyState, so the frame is never blank."
+      @source={{this.usage}}
+    >
+      <:example>
+        <Feed
+          @items={{this.items}}
+          @label={{this.label}}
+          @loading={{this.loading}}
+          @skeletonCount={{this.skeletonVal}}
+        >
+          <:item as |item|>
+            <div class='feed-row'>
+              <Avatar @name={{item.person}} @size={{26}} />
+              <div class='feed-col'>
+                <p class='feed-line'>
+                  <span class='feed-who'>{{item.person}}</span>
+                  {{item.action}}
+                  <span class='feed-what'>{{item.subject}}</span>
+                </p>
+                <div class='feed-meta'>
+                  <StatusChip @value={{item.status}} />
+                  <Token @value={{item.token}} />
+                  <RelativeTime
+                    class='feed-when'
+                    @date={{item.at}}
+                    @now={{this.nowValue}}
+                  />
+                </div>
+              </div>
+            </div>
+          </:item>
+        </Feed>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='items'
+          @required={{true}}
+          @value={{this.items}}
+          @description='The stream, in the order it should read. Each item needs { id } and may carry { label }; <Feed> is generic over T extends FeedItem, so your own row type flows into the <:item> block untouched.'
+        />
+        <Args.Number
+          @name='items (visible count)'
+          @value={{this.visible}}
+          @min={{0}}
+          @max={{6}}
+          @step={{1}}
+          @defaultValue={{4}}
+          @description='Demo-only knob that slices the fixture. Take it to 0 to see the EmptyState, and watch aria-setsize on every article follow the count.'
+          @onInput={{this.setVisible}}
+        />
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @defaultValue='Activity'
+          @description='Accessible name for the feed region. role="feed" requires one; this is it.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.Bool
+          @name='loading'
+          @value={{this.loading}}
+          @defaultValue={{false}}
+          @description='True while more items are on the way: sets aria-busy="true" on the feed and shows the skeleton tail beneath it.'
+          @onInput={{this.setLoading}}
+        />
+        <Args.Number
+          @name='skeletonCount'
+          @value={{this.skeletonCount}}
+          @min={{1}}
+          @max={{5}}
+          @step={{1}}
+          @defaultValue={{2}}
+          @description='How many placeholder rows the loading tail shows. Match it to your page size so the scroll position does not jump when the real items land.'
+          @onInput={{this.setSkeletonCount}}
+        />
+        <Args.Yield
+          @name=':item'
+          @description='Required. One article’s content — receives (item, index). The <article> element, its roving tabindex, aria-posinset/setsize and aria-label are the component’s; everything inside is yours.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name=':empty'
+          @description='Replaces the default EmptyState shown when there is nothing to read and nothing loading.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .feed-row {
+        display: flex;
+        align-items: flex-start;
+        gap: var(--space-3, 8px);
+        min-width: 0;
+      }
+      .feed-col {
+        display: grid;
+        gap: 5px;
+        min-width: 0;
+      }
+      .feed-line {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        line-height: 1.45;
+        color: var(--muted-foreground);
+      }
+      .feed-who {
+        font-weight: 600;
+        color: var(--foreground);
+      }
+      .feed-what {
+        color: var(--foreground);
+      }
+      .feed-meta {
+        display: flex;
+        align-items: center;
+        flex-wrap: wrap;
+        gap: 6px;
+        min-width: 0;
+      }
+      .feed-when {
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_FEED: Record<string, unknown> = {
+  Feed: FeedUsage,
+};

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

@@ -0,0 +1,127 @@
+// Pretui — FieldError: the message line under a field, one severity glyph per issue.
+import Component from '@glimmer/component';
+import { Token } from './token';
+import { normalizeSeverity } from '../internal/forms-core';
+import type { FormIssue, FormSeverity } from '../internal/forms-core';
+
+// ── FieldError ───────────────────────────────────────────────────────────
+// One issue, rendered. Ported from React Spectrum's <FieldError> (which is
+// errors-only and unstyled by severity) and SLDS's
+// `.slds-form-element__help` (one flat red line, no severity concept).
+//
+// Better than both: three severities on the Law 2 hue treatment (one hue in,
+// a complete treatment out), fail-closed normalisation, optional rule
+// provenance as a Law 3 Token, and — the part everyone gets wrong — a
+// DELIBERATE live-region policy.
+//
+// The live-region policy, stated plainly: role='alert' interrupts. A field
+// message that re-renders on every keystroke must never be a live region, or
+// a screen-reader user is talked over while typing. So @announce is opt-in
+// and FormField only turns it on for `record` mode, where an error appears as
+// the result of one discrete commit. In `submit` mode the ErrorSummary
+// announces by TAKING FOCUS; in `live` mode nothing announces, and the
+// message is still read whenever the field itself is focused because
+// FormField put its id in the control's aria-describedby.
+
+const SEVERITY_GLYPHS: Record<FormSeverity, string> = {
+  // Same glyph vocabulary as Alert, so a field message and a
+  // banner about the same thing read as one system.
+  error: '✕',
+  warning: '!',
+  info: 'i',
+};
+
+export interface FieldErrorSignature {
+  Args: {
+    /** The issue to render. Its message is printed verbatim — a rule author
+     *  wrote it, and rewriting rule copy in a component is how enterprise
+     *  forms end up lying about what failed. */
+    issue: FormIssue;
+    /** Add role='alert'. Default false. Only turn this on where the message
+     *  appears as the result of a discrete commit — never on a control that
+     *  revalidates per keystroke. */
+    announce?: boolean;
+    /** Show `issue.ruleId` as a mono Token after the message (Law 3). */
+    showRuleId?: boolean;
+  };
+  Element: HTMLDivElement;
+}
+
+export class FieldError extends Component<FieldErrorSignature> {
+  get severity(): FormSeverity {
+    return normalizeSeverity(this.args.issue?.severity);
+  }
+  get glyph(): string {
+    return SEVERITY_GLYPHS[this.severity];
+  }
+  get role(): string | undefined {
+    return this.args.announce ? 'alert' : undefined;
+  }
+  get ruleId(): string | undefined {
+    return this.args.showRuleId ? this.args.issue?.ruleId : undefined;
+  }
+  <template>
+    <div
+      class='pretui-field-error'
+      role={{this.role}}
+      data-severity={{this.severity}}
+      data-test-pretui-field-error
+      ...attributes
+    >
+      <span class='pretui-field-error-glyph' aria-hidden='true'>{{this.glyph}}</span>
+      <span class='pretui-field-error-msg'>{{@issue.message}}</span>
+      {{#if this.ruleId}}
+        <Token @value={{this.ruleId}} class='pretui-field-error-rule' />
+      {{/if}}
+    </div>
+    <style scoped>
+      /* above Token's layer, so these win by layer order, not file order */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        /* Law 2 — one hue in, a complete treatment out. The severity picks the
+           hue; the recipe below is written once and reads it. */
+        .pretui-field-error {
+          --pretui-issue-hue: var(--pretui-issue-error, var(--destructive));
+          display: flex;
+          align-items: flex-start;
+          gap: var(--pretui-issue-gap, 5px);
+          font-size: var(--text-ui-sm, 11.5px);
+          line-height: 16px;
+          font-weight: 500;
+          color: color-mix(
+            in oklch,
+            var(--foreground) 22%,
+            var(--pretui-issue-hue)
+          );
+          min-width: 0;
+        }
+        .pretui-field-error[data-severity='warning'] {
+          --pretui-issue-hue: var(--pretui-issue-warning, var(--warning, var(--boxel-warning)));
+        }
+        .pretui-field-error[data-severity='info'] {
+          --pretui-issue-hue: var(--pretui-issue-info, var(--pretui-info, var(--boxel-blue)));
+        }
+        .pretui-field-error-glyph {
+          flex: none;
+          width: 13px;
+          height: 13px;
+          margin-top: 1.5px;
+          border-radius: 50%;
+          display: grid;
+          place-items: center;
+          font-size: 8px;
+          font-weight: 700;
+          line-height: 1;
+          background: var(--pretui-issue-hue);
+          color: var(--pretui-on-neutral, var(--boxel-light));
+        }
+        .pretui-field-error-msg {
+          min-width: 0;
+        }
+        .pretui-field-error .pretui-field-error-rule {
+          flex: none;
+        }
+      }
+    </style>
+  </template>
+}