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

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

@@ -0,0 +1,67 @@
+## What it is
+
+Suggest-as-you-type over a list, where the value may be free text.
+
+That last clause is the whole difference from **Combobox**: an autocomplete's value **is** what the reader typed, and the suggestions are help. A combobox's value is constrained to its listbox. If a typed value that matches nothing is still a legal answer, you want this one.
+
+## The contract
+
+```
+@value?, @defaultValue?   — controlled / uncontrolled text
+@items? / @options?       — the suggestion collection; options is the React-kit alias
+@open?, @defaultOpen?, @onOpenChange? — the suggestion layer
+@onSearch?                — the debounced query, for a caller that fetches;
+                            pair with @filter='none'
+@onCommit?                — fires when a value is COMMITTED — Enter, a click, or blur —
+                            with the suggestion when one was chosen, undefined for free text
+@debounce?                — SECONDS of quiet before @onSearch. Default 0, which fires on
+                            every keystroke and schedules no timer at all
+@filter?                  — matching strategy
+@enterCommits?            — what Enter means when the highlight and the typed text disagree:
+                            'deliberate' (default) | 'highlight' | 'text'
+@autoHighlight?           — pre-highlight the first row when suggestions appear
+@openOnFocus?             — open the layer on focus. Default true
+@minChars?                — suppress the layer until this many characters are typed
+@clearable?, @invalid?, @disabled?, @required?, @readonly?, @placeholder?
+@busy? / @loading? / @isPending? — aria-busy, a progress line, and FOCUS RETAINED
+@label?, @controlId?, @describedBy?
+@emptyText?               — replaces the built-in "No matches" line
+@tone?, @appearance?, @size?
+
+<:item>  — replaces the row body; yields the item and { query, active }
+<:empty> — replaces the built-in empty line
+```
+
+**`@onCommit` is the callback that distinguishes typing from meaning it.** It fires on Enter, a click or a blur, and it tells you _which_ happened: a suggestion object when one was chosen, `undefined` when the reader meant their own text.
+
+**`@enterCommits` defaults to `'deliberate'`, and that is the interesting decision.** When the highlight and the typed text disagree, Enter takes the typed text unless the reader deliberately moved to the highlight. An automatic highlight does **not** win Enter — so `@autoHighlight` is a visual aid rather than a trap that silently replaces what someone typed.
+
+**`@debounce` is in seconds, and 0 schedules no timer at all.** The default fires on every keystroke.
+
+**`@label` renders a real `sr-only` `<label for>` unless a wrapper claims the field with `@controlId`**, so the field is named whether or not it sits inside a **Field**.
+
+## Prior art
+
+**Mantine**, **MUI**, **Ant**, **Base UI** and **React Aria** all ship an Autocomplete.
+
+Where Pretui is better: **`@enterCommits` as an explicit contract.** Every upstream has an implicit answer to "what does Enter do when I've typed something and a row is highlighted", and most of them silently discard the typed text. Making it a named arg with a conservative default turns a surprise into a decision. The commit callback distinguishing chosen-from-list versus free text is the second: most kits emit a value and leave the caller to guess.
+
+Where it is thinner: no multi-select or token mode — that is **TokenInput** — no grouped or sectioned suggestions, no async loading state beyond `@busy`, and no virtualisation, so a very long suggestion list renders in full.
+
+## Accessibility
+
+- **Rows are rendered inside an `aria-hidden` face, and the option's accessible name is computed rather than scraped.** That is what makes `<:item>` safe: any markup is legal in the block because none of it reaches the accessibility tree.
+- **`@disabled` keeps the field focusable.** It sets `aria-disabled` and `readonly` rather than the native `disabled`, so a reader can still reach the field and hear that it's unavailable, while the text can't be edited. The Clear button is hidden.
+- **`@busy` retains focus.** A field that disables itself while fetching suggestions throws the reader to the document mid-word.
+- **The field is always named** — through `@label` as an `sr-only` label, or through a wrapper's `@controlId`.
+- **`@minChars` suppresses the layer silently.** A reader who types one character and gets nothing is not told why; if the threshold is high, say so in `@placeholder` or in help text.
+- **The deliberate Enter mode is an accessibility property, not only a usability one.** A screen-reader user arrowing through suggestions has moved deliberately; someone typing has not, and their text should survive.
+- **`@emptyText` and `<:empty>` mean "no matches" is stated** rather than being an empty box.
+
+## Theming
+
+Tone, appearance and size resolve through the kit's shared recipe system, so the field matches every other control in a form at the same size. A tone sets two properties: `--pretui-tone`, the fill (`--primary`, `--info`, `--success`, `--warning`, `--destructive`, `--attention`) for tints, and `--pretui-tone-ink`, its `-ink`, for rings, the busy arc and the matched text, since a fill misses the contrast a line or text needs. The default neutral field has the field style it shares with **Input** and **Select**: a plain `--field` face, Button's corner (`calc(var(--radius) - 2px)`) and a `--boxel-form-control-height-sm` (1.75rem) height at size m. Other appearances read `--field` or `--card` with its foreground; the edge is `--input` when neutral (pulled toward `--foreground` on hover, as on Select) and the tone's `-ink` otherwise, `--destructive-ink` when invalid, `--ring` for focus and `--muted-foreground` for the placeholder. Sizes come from `--pretui-size-*`, falling back to `--boxel-font-size-2xs` (xs and s), `-xs` (m, as on Select), `-sm` (l) and `--boxel-font-size` (xl). On touch screens (`pointer: coarse`) the field's text, its placeholder and the suggestions are at least 16px (`--boxel-form-control-touch-font-size`), so iOS doesn't zoom into the field on focus; its height keeps the size's value.
+
+The suggestion layer is a `--popover` surface with `--popover-foreground`, `--shadow-md`, the field's corner and the kit's `dropdown` stacking tier, the same elevation and radius as a **Select**'s, so the two don't look like different products. The clear button is a plain neutral **Button** with a boxel-icons `x`.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,339 @@
+// Pretui — Autocomplete usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Autocomplete } from './autocomplete';
+import type { AutocompleteItem } from './autocomplete';
+import {
+  PRETUI_APPEARANCES,
+  PRETUI_SIZES,
+  PRETUI_TONES,
+} from '../pretui-primitives';
+import type {
+  PretuiAppearance,
+  PretuiSize,
+  PretuiTone,
+} from '../pretui-primitives';
+
+const TONES = [...PRETUI_TONES];
+const APPEARANCES = [...PRETUI_APPEARANCES];
+const SIZES = [...PRETUI_SIZES];
+const FILTERS = ['contains', 'starts-with', 'none'];
+const ENTER_MODES = ['deliberate', 'highlight', 'text'];
+
+// ── Autocomplete ← MUI freeSolo / Mantine / Base UI / Ant AutoComplete ───
+const CITIES: AutocompleteItem[] = [
+  { value: 'Amsterdam', meta: 'NL' },
+  { value: 'Antwerp', meta: 'BE' },
+  { value: 'Athens', meta: 'GR' },
+  { value: 'Auckland', meta: 'NZ' },
+  { value: 'Barcelona', meta: 'ES' },
+  { value: 'Belgrade', meta: 'RS' },
+  { value: 'Berlin', meta: 'DE' },
+  { value: 'Bogotá', meta: 'CO' },
+  { value: 'Copenhagen', meta: 'DK' },
+  { value: 'Dakar', meta: 'SN' },
+  { value: 'Edinburgh', meta: 'GB' },
+  { value: 'Kyoto', meta: 'JP', disabled: true },
+  { value: 'Lisbon', meta: 'PT' },
+  { value: 'Montréal', meta: 'CA' },
+  { value: 'Reykjavík', meta: 'IS' },
+  { value: 'Valparaíso', meta: 'CL' },
+];
+
+export class AutocompleteUsage extends Component {
+  tones = TONES;
+  appearances = APPEARANCES;
+  sizes = SIZES;
+  filters = FILTERS;
+  enterModes = ENTER_MODES;
+  cities = CITIES;
+
+  @tracked value = '';
+  @tracked committedValue = '(nothing committed yet)';
+  @tracked lastQuery = '';
+  @tracked filter = 'contains';
+  @tracked enterCommits = 'deliberate';
+  @tracked autoHighlight = false;
+  @tracked openOnFocus = true;
+  @tracked clearable = true;
+  @tracked busy = false;
+  @tracked invalid = false;
+  @tracked disabled = false;
+  @tracked tone = 'neutral';
+  @tracked appearance = 'filled-outlined';
+  @tracked sizeName = 'm';
+  @tracked minChars = 0;
+  @tracked maxVisible = 8;
+
+  setValue = (v: string) => (this.value = v);
+  onCommit = (v: string, item?: AutocompleteItem) => {
+    this.committedValue = item ? v + ' (suggestion)' : v + ' (free text)';
+  };
+  onSearch = (q: string) => (this.lastQuery = q);
+  setFilter = (v: string) => (this.filter = v);
+  setEnterCommits = (v: string) => (this.enterCommits = v);
+  setAutoHighlight = (v: boolean) => (this.autoHighlight = v);
+  setOpenOnFocus = (v: boolean) => (this.openOnFocus = v);
+  setClearable = (v: boolean) => (this.clearable = v);
+  setBusy = (v: boolean) => (this.busy = v);
+  setInvalid = (v: boolean) => (this.invalid = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setTone = (v: string) => (this.tone = v);
+  setAppearance = (v: string) => (this.appearance = v);
+  setSize = (v: string) => (this.sizeName = v);
+  setMinChars = (v: number | null) => (this.minChars = v ?? 0);
+  setMaxVisible = (v: number | null) => (this.maxVisible = v ?? 8);
+
+  get filterVal() {
+    return this.filter as 'contains' | 'starts-with' | 'none';
+  }
+  get enterVal() {
+    return this.enterCommits as 'deliberate' | 'highlight' | 'text';
+  }
+  get toneVal() {
+    return this.tone as PretuiTone;
+  }
+  get appearanceVal() {
+    return this.appearance as PretuiAppearance;
+  }
+  get sizeVal() {
+    return this.sizeName as PretuiSize;
+  }
+  get usage() {
+    return [
+      '<Autocomplete',
+      '@items={{this.cities}}',
+      '@value={{this.value}}',
+      '@onChange={{this.setValue}}',
+      '@onCommit={{this.onCommit}}',
+      "@label='City'",
+      '/>',
+    ].join(' ');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Autocomplete'
+      @description='Free text WITH suggestions beside it. Combobox constrains the value to its listbox and Lookup resolves a record; here the typed string stands on its own, which is what MUI calls freeSolo. The hard question is what Enter means when the highlighted suggestion and the typed text disagree — this component answers it in one exported six-line function and one knob, where MUI hides the same rule in four interacting flags. Home and End are deliberately left to the caret, because the value is prose.'
+      @source={{this.usage}}
+      @viewportMode='narrow'
+    >
+      <:example>
+        <div class='ac-demo-slot'>
+          <Autocomplete
+            @items={{this.cities}}
+            @value={{this.value}}
+            @onChange={{this.setValue}}
+            @onCommit={{this.onCommit}}
+            @onSearch={{this.onSearch}}
+            @label='City'
+            @placeholder='Type a city, or anything else'
+            @filter={{this.filterVal}}
+            @enterCommits={{this.enterVal}}
+            @autoHighlight={{this.autoHighlight}}
+            @openOnFocus={{this.openOnFocus}}
+            @clearable={{this.clearable}}
+            @busy={{this.busy}}
+            @invalid={{this.invalid}}
+            @disabled={{this.disabled}}
+            @tone={{this.toneVal}}
+            @appearance={{this.appearanceVal}}
+            @size={{this.sizeVal}}
+            @minChars={{this.minChars}}
+            @maxVisible={{this.maxVisible}}
+          />
+        </div>
+        <p class='pretui-demo-readout' data-test-ac-readout>
+          value = {{this.value}} · committed = {{this.committedValue}} · last
+          query = {{this.lastQuery}}
+        </p>
+        <p class='pretui-demo-note'>
+          Try it: type
+          <b>be</b>, then press Enter without touching the arrows — you get the
+          text you typed. Type
+          <b>be</b>
+          again, press ArrowDown to Belgrade, then Enter — you get Belgrade.
+          Turn autoHighlight on and repeat the first one: the pre-highlighted
+          row still does not win, because the reader did not put it there.
+          Kyoto is disabled and the arrows step over it.
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='items'
+          @description='The suggestion collection. Each carries a value, an optional label, an optional meta line and an optional disabled flag. options is accepted as an alias, since that is the noun every React kit uses.'
+          @value={{this.cities}}
+        />
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @description='Controlled text. In an autocomplete the value IS what the reader typed — that is the whole difference from Combobox, whose value is constrained to its listbox. Omit and seed defaultValue for uncontrolled use.'
+          @onInput={{this.setValue}}
+        />
+        <Args.Action
+          @name='onChange'
+          @description='Fires on every keystroke with the current text. onValueChange is accepted as an alias and both fire if both are supplied.'
+        />
+        <Args.Action
+          @name='onCommit'
+          @description='Fires when a value is MEANT rather than merely typed — Enter, a click on a suggestion, or blur — with the chosen item as a second argument and undefined for free text. This is the callback that separates typing from deciding, and no React source in the survey exposes it.'
+        />
+        <Args.Action
+          @name='onSearch'
+          @description='The debounced query, for a caller that fetches suggestions. Pair it with filter set to none, since the server already decided what matches.'
+        />
+        <Args.Number
+          @name='debounce'
+          @defaultValue={{0}}
+          @description='Seconds of quiet before onSearch fires. Seconds, not milliseconds — the kit uses seconds for every duration. Zero, the default, fires on every keystroke and schedules no timer at all; any non-zero handle is owned by an ember-modifier and cleared in its destructor.'
+        />
+        <Args.String
+          @name='filter'
+          @defaultValue='contains'
+          @value={{this.filter}}
+          @options={{this.filters}}
+          @description='Local matching. contains is what every React kit ships, starts-with is the prefix behaviour an identifier field wants, and none means the caller has already filtered — the correct mode for async, where re-filtering the server answer against the current keystroke hides rows it deliberately returned.'
+          @onInput={{this.setFilter}}
+        />
+        <Args.String
+          @name='enterCommits'
+          @defaultValue='deliberate'
+          @value={{this.enterCommits}}
+          @options={{this.enterModes}}
+          @description='What Enter means when the highlight and the typed text disagree. deliberate lets a suggestion win only when the reader arrowed to it with the keyboard; highlight is the strict listbox behaviour; text never lets a suggestion win. MUI reaches the same default through an undocumented branch on whether the highlight was programmatic.'
+          @onInput={{this.setEnterCommits}}
+        />
+        <Args.Bool
+          @name='autoHighlight'
+          @defaultValue={{false}}
+          @value={{this.autoHighlight}}
+          @description='Pre-highlight the first row when suggestions appear. Note that an automatic highlight still does not win Enter under the default enterCommits — that combination is exactly the bug this component is designed not to have.'
+          @onInput={{this.setAutoHighlight}}
+        />
+        <Args.Bool
+          @name='openOnFocus'
+          @defaultValue={{true}}
+          @value={{this.openOnFocus}}
+          @description='Open the suggestion layer when the field receives focus, provided there is anything to suggest.'
+          @onInput={{this.setOpenOnFocus}}
+        />
+        <Args.Number
+          @name='minChars'
+          @defaultValue={{0}}
+          @value={{this.minChars}}
+          @description='Hold the layer shut until this many characters are typed. The layer still reports open through onOpenChange, so a controlled caller never desynchronises.'
+          @onInput={{this.setMinChars}}
+        />
+        <Args.Number
+          @name='maxVisible'
+          @defaultValue={{8}}
+          @value={{this.maxVisible}}
+          @description='Cap on rendered rows. The rest are reachable by narrowing, which is the honest alternative to a scroll container holding four hundred options.'
+          @onInput={{this.setMaxVisible}}
+        />
+        <Args.Bool
+          @name='clearable'
+          @defaultValue={{false}}
+          @value={{this.clearable}}
+          @description='Show a named clear button once the field has text.'
+          @onInput={{this.setClearable}}
+        />
+        <Args.Bool
+          @name='busy'
+          @defaultValue={{false}}
+          @value={{this.busy}}
+          @description='Pending: aria-busy on the field, a spinner, and focus retained. loading and isPending are accepted as aliases.'
+          @onInput={{this.setBusy}}
+        />
+        <Args.Bool
+          @name='invalid'
+          @defaultValue={{false}}
+          @value={{this.invalid}}
+          @description='Error dress plus aria-invalid. isInvalid is accepted as an alias. The focus ring still wins over the error ring, so a reader can always see where they are.'
+          @onInput={{this.setInvalid}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @description='Dims and inerts through aria-disabled, never the native attribute. isDisabled is accepted as an alias.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='label'
+          @defaultValue='Search'
+          @description='Accessible name, rendered as a real sr-only label pointing at the field. A wrapper that owns the visible label passes controlId instead, and then this component renders no label of its own — two names on one field is a defect, and realm lint agrees.'
+        />
+        <Args.String
+          @name='tone'
+          @defaultValue='neutral'
+          @value={{this.tone}}
+          @options={{this.tones}}
+          @description='Semantic hue for the field and the matched run in each row.'
+          @onInput={{this.setTone}}
+        />
+        <Args.String
+          @name='appearance'
+          @defaultValue='filled-outlined'
+          @value={{this.appearance}}
+          @options={{this.appearances}}
+          @description='The field recipe. filled-outlined is the house default dress for inputs.'
+          @onInput={{this.setAppearance}}
+        />
+        <Args.String
+          @name='size'
+          @defaultValue='m'
+          @value={{this.sizeName}}
+          @options={{this.sizes}}
+          @description='Size scale. Accepts sm, md, lg and default as aliases.'
+          @onInput={{this.setSize}}
+        />
+        <Args.Bool
+          @name='open'
+          @description='Controlled suggestion layer. Pair with onOpenChange; defaultOpen is the uncontrolled seed.'
+        />
+        <Args.Yield
+          @name='item'
+          @description='Replaces the default row body, yielding the item and the live query. It renders inside an aria-hidden face, so any markup is legal here — the option name is computed rather than scraped, which is what keeps a caller who yields an avatar from failing realm lint in their own file.'
+        />
+        <Args.Yield
+          @name='empty'
+          @description='Replaces the built-in empty line. The built-in one is deliberate — a mark, the reason, and the next action — rather than a bare no results.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-ac-h'
+          @description='Minimum field height: --boxel-form-control-height-sm at size m, scaled off the text size at the others.'
+          @defaultValue='var(--boxel-form-control-height-sm)'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      /* The layer renders in place and is absolutely positioned, so the demo
+         slot reserves room for it rather than letting it clip the artboard. */
+      .ac-demo-slot {
+        min-height: 18em;
+        max-width: 26em;
+      }
+      .pretui-demo-readout {
+        margin: 12px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+      .pretui-demo-note {
+        margin: 16px 0 0;
+        font-size: var(--text-ui-xs, 11px);
+        line-height: 1.5;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+
+export const DEMOS_AUTOCOMPLETE: Record<string, unknown> = {
+  Autocomplete: AutocompleteUsage,
+};

package/bundled-realms/pretui/components/avatar-group.gts

@@ -0,0 +1,30 @@
+// Pretui — AvatarGroup: an overlapping stack of Avatars with a count overflow.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+export interface AvatarGroupSignature {
+  Blocks: { default: [] };
+  Element: HTMLSpanElement;
+}
+
+// Overlapping avatar row; the card-colored ring separates neighbors.
+export const AvatarGroup: TemplateOnlyComponent<AvatarGroupSignature> = <template>
+  <span class='pretui-avatar-group' data-test-pretui-avatar-group ...attributes>
+    {{yield}}
+  </span>
+  <style scoped>
+    /* above Avatar's layer, so these win by layer order, not file order */
+    @layer PretComponent, PretComposite;
+    @layer PretComposite {
+      .pretui-avatar-group {
+        display: inline-flex;
+      }
+      .pretui-avatar-group > :deep(.pretui-avatar) {
+        margin-left: -6px;
+        box-shadow: 0 0 0 2px var(--card);
+      }
+      .pretui-avatar-group > :deep(.pretui-avatar:first-child) {
+        margin-left: 0;
+      }
+    }
+  </style>
+</template>;

package/bundled-realms/pretui/components/avatar-group.md

@@ -0,0 +1,48 @@
+## What it is
+
+A row of overlapping **Avatar**s, each ringed in the card colour so neighbours stay separate. Use it where several people share a thing and you need to show that at a glance without a list — reviewers on a document, attendees, watchers, presence in a room. If the people need to be individually identifiable or actionable, use a real list. If there are more than about five, cap the row and add a count.
+
+## The contract
+
+```
+<:default>   — the Avatars
+Element: HTMLSpanElement
+```
+
+**No args at all.** It is a layout wrapper: an `inline-flex` with a `-6px` left margin on every child Avatar except the first, and a 2px `--card` ring replacing each Avatar's normal hairline. That ring is what makes the overlap legible — without it, two adjacent avatars of similar hue merge into a blob.
+
+The styling reaches its children through `:deep(.pretui-avatar)`, which is a deliberate, narrow use of the escape hatch: the component must restyle content it did not render. The consequence is that **it only works on Pretui `Avatar`s** — an arbitrary circle yielded in will not overlap or get the ring.
+
+**Overflow is entirely yours.** There is no overflow arg, no `+3` chip, no truncation. A group of forty avatars renders forty avatars. In practice you slice the array at the call site and put a **Chip** after the group.
+
+## Prior art
+
+**Web Awesome** has no avatar group. **Radix** has none. **React Spectrum `AvatarGroup`** takes `label`, `size` and `orientation`, and — crucially — is a **labelled group** with real semantics. **shadcn** documents an avatar-stack recipe with a `-space-x-2` utility and nothing else. **Material** and **Ant** both ship `max`/`maxCount` with an overflow avatar.
+
+So the field splits into "a CSS trick" (shadcn, and effectively this) and "a semantic group with overflow handling" (Spectrum, Ant). Pretui is on the CSS-trick side, and the honest reading is that this is the thinnest component in the ink territory relative to its prior art.
+
+What it does get right: **the ring is `--card`, not white.** That is the difference between a group that works on a panel and one that shows white halos on every dark or tinted surface, and it is the single most common bug in hand-rolled avatar stacks. Because the ring is a token, the group composes onto any Pretui surface correctly.
+
+What it is missing, concretely: `@max` with an overflow indicator (the most-requested feature and present in every mature implementation), a group label, `@size` currying so children do not each need their own, and reverse stacking order (the first avatar sits on top here, so a long row's _last_ avatar is the least visible — most implementations invert the `z-index` so the leftmost is on top, which this achieves by DOM order rather than deliberately).
+
+## Accessibility
+
+No APG pattern.
+
+This is where the gap versus React Spectrum matters most, and it is worth being direct:
+
+- **The group has no accessible name and no group semantics.** No `role="group"`, no `aria-label`, no list markup. A screen-reader user encounters a run of avatars with no indication that they belong together, and no count. Spectrum's `AvatarGroup label` exists precisely for this — "Reviewers, 4 people". Adding `role="group"` plus an `@label` arg would be the single highest-value change to this component.
+- **Each avatar announces individually**, and inherits **Avatar**'s own gap: an initials-only Avatar has no accessible name at all (the initials are announced as letters, and the full name lives in an unreliable `title`). So a group of five initials-only avatars announces as "AL JP MK RS TW" — ten letters, no names. In a group this compounds from a minor issue into an unusable one.
+- **No count is available anywhere.** Sighted users can see five circles; a screen-reader user gets five unlabelled fragments and no total. Since overflow is the caller's job, the "+3" that would carry it is not part of the component either.
+- **Overlap and target size**: if the avatars are interactive (wrapped in links at the call site), the `-6px` overlap means each target is partially occluded by its neighbour, and the leftmost 6px of every avatar after the first is unclickable. That is a **WCAG 2.5.8 Target Size** concern for interactive groups. Non-interactive groups are unaffected.
+- **The ring is decorative** and contributes nothing to the accessibility tree — correct.
+
+Practical guidance: wrap the group in a labelled `role="group"` or a `<ul>` at the call site, give each Avatar an `aria-label`, and render a visible count.
+
+## Theming
+
+`--card` (the 2px separator ring). That is the only token this component consumes directly; everything else belongs to the **Avatar**s inside it.
+
+The `-6px` overlap and the 2px ring width are fixed, so a theme cannot make the stack tighter or looser. The ring being `--card` means a group placed on `--canvas` or `--inset` — an **EmptyState**, a table's header band, a striped row — will show rings in the wrong color. That is the one placement trap: the component assumes it sits on a card surface, and there is no token to tell it otherwise.
+
+The styles sit in `@layer PretComposite`, above Avatar's `PretComponent` layer, so what this component sets on Avatar wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.

package/bundled-realms/pretui/components/avatar-group.usage.gts

@@ -0,0 +1,39 @@
+// Pretui — AvatarGroup usage page.
+import Component from '@glimmer/component';
+import { FreestyleUsage } from './freestyle-usage';
+import { Avatar } from './avatar';
+import { AvatarGroup } from './avatar-group';
+
+const PEOPLE = [
+  { name: 'Mei-Lin Chua', hue: 'var(--chart-1)' },
+  { name: 'Tomás Aravena', hue: 'var(--chart-2)' },
+  { name: 'Priya Raghunathan', hue: 'var(--chart-3)' },
+  { name: 'Kwame Boateng', hue: 'var(--chart-4)' },
+];
+
+class AvatarGroupUsage extends Component {
+  people = PEOPLE;
+  <template>
+    <FreestyleUsage
+      @name='AvatarGroup'
+      @description='A compact overlap for named people. Every Avatar retains its own accessible name; the card-coloured ring separates neighbours without adding a new hue.'
+      @source='<AvatarGroup><Avatar @name="Mei-Lin Chua" />…</AvatarGroup>'
+    >
+      <:example>
+        <AvatarGroup>
+          {{#each this.people as |person|}}
+            <Avatar @name={{person.name}} @hue={{person.hue}} @size={{32}} />
+          {{/each}}
+        </AvatarGroup>
+      </:example>
+      <:api as |Args|>
+        <Args.Yield @name='default' @description='Avatar children in display order.' />
+        <Args.Object @name='sample people' @value={{this.people}} @description='Representative fixture data for the yielded Avatars.' />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_AVATAR_GROUP: Record<string, unknown> = {
+  AvatarGroup: AvatarGroupUsage,
+};

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

@@ -0,0 +1,134 @@
+// Pretui — Avatar: an identity disc with a name-derived hue and initials.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { cssDeclaration, cssStyleFrom, cssValue } from '../pretui-css';
+import { statusHue } from '../internal/ink';
+import { keepStyle, type KeptProperty } from '../internal/keep-style';
+
+export interface AvatarSignature {
+  Args: {
+    name: string;
+    src?: string;
+    hue?: string;
+    /** diameter in px at a 16px root, written as rem; omitted, 24 (1.5rem) */
+    size?: number;
+  };
+  Element: HTMLSpanElement;
+}
+
+const SIZE_PROPERTY = '--pretui-avatar-size';
+const HUE_PROPERTY = '--pretui-chip-hue';
+
+export class Avatar extends Component<AvatarSignature> {
+  @tracked failedSrc: string | undefined;
+
+  get initials() {
+    return (this.args.name ?? '')
+      .split(/\s+/)
+      .map((w) => w[0])
+      .slice(0, 2)
+      .join('')
+      .toUpperCase();
+  }
+  get showImage(): boolean {
+    return Boolean(this.args.src) && this.args.src !== this.failedSrc;
+  }
+  imageError = () => {
+    this.failedSrc = this.args.src;
+  };
+  // The diameter as rem, from a px figure at a 16px root. Omitted, nothing is
+  // written and the stylesheet's 1.5rem (or a caller's --pretui-avatar-size,
+  // from a class, a container query or an ancestor) applies.
+  get size(): string | undefined {
+    let size = Number(this.args.size) || undefined;
+    return size === undefined ? undefined : `${size / 16}rem`;
+  }
+  get explicitHue(): string | undefined {
+    return this.args.hue ?? undefined;
+  }
+  // An explicit @hue is validated; without one the hue is the name's hash.
+  get hue(): string | undefined {
+    let hue = this.explicitHue;
+    return hue === undefined ? statusHue(this.args.name ?? '') : cssValue(hue);
+  }
+  get style() {
+    return cssStyleFrom([
+      cssDeclaration(SIZE_PROPERTY, this.size),
+      cssDeclaration(HUE_PROPERTY, this.hue),
+    ]);
+  }
+  // The same properties again, kept on top of a caller's `style`. @hue and
+  // @size win over the caller's; the name-derived hue only fills in when the
+  // caller's style sets no hue of its own.
+  get keptStyle(): KeptProperty[] {
+    return [
+      { property: SIZE_PROPERTY, value: this.size, strength: 'arg' },
+      {
+        property: HUE_PROPERTY,
+        value: this.hue,
+        strength: this.explicitHue === undefined ? 'default' : 'arg',
+      },
+    ];
+  }
+  <template>
+    <span
+      class='pretui-avatar'
+      title={{@name}}
+      role={{unless this.showImage 'img'}}
+      aria-label={{unless this.showImage @name}}
+      data-has-image={{if this.showImage 'true'}}
+      style={{this.style}}
+      {{keepStyle this.keptStyle}}
+      data-test-pretui-avatar
+      ...attributes
+    >
+      {{#if this.showImage}}<img src={{@src}} alt={{@name}} {{on 'error' this.imageError}} />{{else}}{{this.initials}}{{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-avatar {
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          /* the default diameter, declared once */
+          --_avatar-size: var(--pretui-avatar-size, 1.5rem);
+          --_avatar-hue: var(--pretui-chip-hue, var(--primary));
+          width: var(--_avatar-size);
+          height: var(--_avatar-size);
+          /* 0.42 of the diameter; rounded to the whole pixel below where
+             round() is supported */
+          font-size: calc(var(--_avatar-size) * 0.42);
+          border-radius: 50%;
+          font-family: var(--font-mono);
+          font-weight: 600;
+          background-color: color-mix(in oklch, var(--_avatar-hue) 16%, var(--card));
+          color: var(--foreground);
+          box-shadow: 0 0 0 1px color-mix(in oklch, var(--_avatar-hue) 28%, var(--border));
+          overflow: hidden;
+          flex: none;
+        }
+        /* Gated rather than declared after the calc() fallback: a value
+           containing var() is accepted at parse time, so an engine without
+           round() would keep it, fail at computed-value time, and inherit
+           the parent's font size instead of using the fallback. */
+        @supports (font-size: round(1px, 1px)) {
+          .pretui-avatar {
+            font-size: round(calc(var(--_avatar-size) * 0.42), 1px);
+          }
+        }
+        /* A photo gets a neutral ring: the name's hue carries no meaning once
+           the photo shows. The ring sits on the root, whose overflow: hidden
+           circle would clip an outline on the square img. */
+        .pretui-avatar[data-has-image] {
+          box-shadow: 0 0 0 1px color-mix(in oklch, var(--foreground) 10%, transparent);
+        }
+        .pretui-avatar img {
+          width: 100%;
+          height: 100%;
+          object-fit: cover;
+        }
+      }
+    </style>
+  </template>
+}