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

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

@@ -0,0 +1,197 @@
+// Pretui — Token: a machine value set as jewelry — an id, a key, a code (Law 3).
+import Component from '@glimmer/component';
+import { modifier } from 'ember-modifier';
+import { hueStyle } from '../internal/ink';
+import { cssValue } from '../pretui-css';
+import {
+  resolveSize,
+  type PretuiSize,
+  type PretuiSizeArg,
+} from '../pretui-primitives';
+
+export interface TokenSignature {
+  Args: {
+    value?: string;
+    hue?: string;
+    /** house scale xs|s|m|l|xl; omitted or 'default', Chip's size */
+    size?: PretuiSizeArg;
+    /** let a long value wrap instead of overflowing on one line */
+    wrap?: boolean;
+  };
+  Blocks: { default: [] };
+  Element: HTMLElement;
+}
+
+const HUE_PROPERTY = '--pretui-token-hue';
+
+// The declarations of a style as a sorted list of `property:value`, to tell
+// whether a rewrite changed anything regardless of order.
+function declarations(style: CSSStyleDeclaration): string {
+  let list: string[] = [];
+  for (let i = 0; i < style.length; i++) {
+    let property = style.item(i);
+    list.push(`${property}:${style.getPropertyValue(property).trim()}`);
+  }
+  return list.sort().join('\n');
+}
+
+// A caller's `style` replaces Token's own `style` attribute, so `@hue` is also
+// written as a single property on top of whatever style the element ends up
+// with. The observer puts it back when the caller's style changes later and
+// the attribute is rewritten. The hue the caller's style last set comes back
+// when `@hue` is cleared.
+//
+// The observer drains the record of each of the modifier's own writes as soon
+// as it makes one, so the old value of the first record in a batch it
+// delivers is the attribute as the modifier left it. What changed since is
+// either a caller rewrite, which replaces the whole attribute, or a
+// single-property write by something else on the element (boxel-ui's
+// `setCssVar`, passed through `...attributes`), which leaves the hue in place.
+// So a batch is taken as a caller rewrite when it changed the hue, or when it
+// changed no declaration at all, which only a rewrite of the attribute does (a
+// single-property write that changes nothing queues no record). After a
+// caller rewrite, the hue the element now has is the caller's. After any other
+// batch, the caller's hue stays as it was.
+//
+// The cost: a caller rewrite that sets the hue exactly as `@hue` wrote it, and
+// changes some other declaration, looks like another modifier's write. Its hue
+// is not taken as the caller's, so when `@hue` is cleared the caller's earlier
+// hue comes back, or the hue is removed if the caller had none.
+const keepHue = modifier((el: HTMLElement, [hue]: [string | undefined]) => {
+  let value = cssValue(hue);
+  if (value === undefined) {
+    return;
+  }
+  let read = () => el.style.getPropertyValue(HUE_PROPERTY).trim() || undefined;
+  // The caller's hue keeps its priority, so a caller's `!important` comes back
+  // with it.
+  let callerHue: string | undefined;
+  let callerPriority = '';
+  let readCaller = () => {
+    callerHue = read();
+    callerPriority = el.style.getPropertyPriority(HUE_PROPERTY);
+  };
+  readCaller();
+  let isCallerRewrite = (records: MutationRecord[]) => {
+    if (records.length === 0) {
+      return false;
+    }
+    let before = el.ownerDocument.createElement('span').style;
+    before.cssText = records[0].oldValue ?? '';
+    let changedHue =
+      (before.getPropertyValue(HUE_PROPERTY).trim() || undefined) !== read();
+    return changedHue || declarations(before) === declarations(el.style);
+  };
+  let write = (observer?: MutationObserver) => {
+    if (read() !== value) {
+      el.style.setProperty(HUE_PROPERTY, value);
+      observer?.takeRecords();
+    }
+  };
+  write();
+  let observer = new MutationObserver((records, self) => {
+    if (isCallerRewrite(records)) {
+      readCaller();
+    }
+    write(self);
+  });
+  observer.observe(el, {
+    attributes: true,
+    attributeFilter: ['style'],
+    attributeOldValue: true,
+  });
+  return () => {
+    // Records still queued here were written in the same render, before this
+    // teardown: Glimmer sets the caller's style and runs the caller's
+    // modifiers ahead of this one. If they make a caller rewrite, the hue the
+    // element has now is the caller's, so nothing is put back over it. If not
+    // (another modifier wrote its own property), the caller's hue is put back
+    // as usual.
+    let rewritten = isCallerRewrite(observer.takeRecords());
+    observer.disconnect();
+    if (!rewritten && read() === value) {
+      if (callerHue) {
+        el.style.setProperty(HUE_PROPERTY, callerHue, callerPriority);
+      } else {
+        el.style.removeProperty(HUE_PROPERTY);
+      }
+    }
+  };
+});
+
+// Law 3 — a machine value set like jewelry: mono pill, inline in prose.
+// Carries .35ch side margins; flush (margin 0) as a direct cell/dd child.
+export class Token extends Component<TokenSignature> {
+  get style() {
+    return hueStyle(HUE_PROPERTY, this.args.hue);
+  }
+  // 'default' is the component's own default, which for Token is no step.
+  get size(): PretuiSize | undefined {
+    let { size } = this.args;
+    return size === undefined || size === 'default'
+      ? undefined
+      : resolveSize(size);
+  }
+  <template>
+    <code
+      class='pretui-token'
+      style={{this.style}}
+      data-size={{this.size}}
+      data-wrap={{if @wrap 'true'}}
+      data-test-pretui-token
+      {{keepHue @hue}}
+      ...attributes
+    >
+      {{#if @value}}{{@value}}{{else}}{{yield}}{{/if}}
+    </code>
+    <style scoped>
+      @layer PretComponent {
+        /* Chip's radius, padding and height, so the two line up side by side,
+           but outlined on --card where Chip is filled with --muted: a value,
+           not a label. --pretui-token-hue is the text color; callers set it on
+           the Token or an ancestor, so it is read with a fallback rather than
+           declared here. */
+        .pretui-token {
+          display: inline-block;
+          margin-inline: 0.35ch;
+          vertical-align: baseline;
+          font-family: var(--font-mono);
+          font-size: var(--pretui-token-font-size, var(--boxel-font-size-2xs));
+          /* 18px, matching Chip, until the text needs more */
+          line-height: max(1.125rem, 1.5em);
+          padding: 0 var(--boxel-sp-2xs);
+          border-radius: var(--boxel-border-radius-xs);
+          background-color: var(--card);
+          color: var(--pretui-token-hue, var(--card-foreground));
+          box-shadow: inset 0 0 0 1px var(--border);
+          white-space: nowrap;
+          font-variant-numeric: tabular-nums;
+        }
+        /* size scale, the same steps as Autocomplete's; the ladder has no
+           step under 11px, so xs and s share it */
+        .pretui-token[data-size='xs'] {
+          font-size: var(--pretui-size-xs, var(--boxel-font-size-2xs));
+        }
+        .pretui-token[data-size='s'] {
+          font-size: var(--pretui-size-s, var(--boxel-font-size-2xs));
+        }
+        .pretui-token[data-size='m'] {
+          font-size: var(--pretui-size-m, var(--boxel-font-size-xs));
+        }
+        .pretui-token[data-size='l'] {
+          font-size: var(--pretui-size-l, var(--boxel-font-size-sm));
+        }
+        .pretui-token[data-size='xl'] {
+          font-size: var(--pretui-size-xl, var(--boxel-font-size));
+        }
+        .pretui-token[data-wrap] {
+          white-space: normal;
+          overflow-wrap: anywhere;
+        }
+        :where(td, dd) > .pretui-token {
+          margin-inline: 0;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,63 @@
+## What it is
+
+A machine value set like jewelry: a small mono pill for an id, a hash, a path, a rule name, a key. Law 3 of the kit — machine values are not prose and should not be typeset as prose, but they are also not errors and should not be typeset as code blocks. Use it inline in a sentence, in a table cell, in a definition list. If the value is a human-facing category, use **Chip**. If it is a signed number, **Delta**. If it is a whole code sample, that is `<pre>` inside **Prose**, not this.
+
+## The contract
+
+```
+@value?, @hue?, @size?, @wrap?
+<:default>   — used when @value is absent
+Element: HTMLElement (a <code>)
+```
+
+**It renders `<code>`**, which is the correct element and is what makes it a Token rather than a styled span.
+
+**`@size`** takes the house scale `xs | s | m | l | xl` (and the `sm` / `md` / `lg` / `small` / `medium` / `large` aliases), read from `--pretui-size-*`, falling back to the ladder: `--boxel-font-size-2xs` (xs and s), `-xs` (m), `-sm` (l) and `--boxel-font-size` (xl). It sets the font-size; the line box stays 18px until the text needs more (`max(1.125rem, 1.5em)`), and the padding, radius and margins stay as they are. It lands as `data-size` on the element. Without `@size`, or with `@size='default'` (as on Button, the component's own default), the size is `--boxel-font-size-2xs`; `--pretui-token-font-size` pins it to an exact value instead, such as `var(--boxel-font-size-xs)`. `@size` wins over that property.
+
+**`@hue` and a caller's `style` work together.** Glimmer lets a caller's `style` attribute replace a component's own, so `@hue` is also written as a single `--pretui-token-hue` property on top of whatever style the element ends up with, and written again if the caller's style changes later. The caller's own declarations are kept, and so is a property another modifier on the element sets, such as boxel-ui's `setCssVar`. If the caller's style sets `--pretui-token-hue` as well, `@hue` wins, and the hue the caller's style last set comes back when `@hue` is cleared, including when the caller rewrote its style to `@hue`'s own value. One rewrite is not told apart from another modifier's write: a caller style that sets the hue exactly as `@hue` wrote it and changes some other declaration (dropping a property another modifier set counts). Its hue is not taken as the caller's, so clearing `@hue` brings back the caller's earlier hue, or none. `@size` and `@wrap` are data attributes, so a caller's style cannot remove them.
+
+**`@wrap`** lets a long value (a path, a rule, a phrase) wrap: `white-space: normal` with `overflow-wrap: anywhere`, so it breaks even inside an unbroken id.
+
+Two details worth knowing, both about how it behaves in context:
+
+**`margin-inline: 0.35ch`.** A mono pill dropped into proportional prose sits too tight against its neighbors because the pill's padding is inside the box. A third of a character on each side restores the word rhythm — and because it is `ch`, it scales with the surrounding type.
+
+**`:where(td, dd) > .pretui-token { margin-inline: 0 }`.** As a direct child of a table cell or a definition-list value, the margins go away so the pill aligns flush with the cell edge. The `:where()` keeps specificity at zero so a call site can override without a fight. This is a small thing that makes tables of ids look right without anyone thinking about it.
+
+It has Chip's radius, padding and height, but the opposite treatment: outlined on `--card` with `--card-foreground` text and a `--border` ring, where Chip is filled with `--muted`. The hue, when set, is the text color only.
+
+`font-variant-numeric: tabular-nums` keeps a column of ids from jittering.
+
+## Prior art
+
+Nobody ships this as a component. **shadcn**, **Radix**, **Web Awesome** and **React Spectrum** all leave inline code to a `<code>` element and a stylesheet rule. The closest analogues are editorial rather than compositional: GitHub's inline-code treatment, Stripe's docs, and Notion's inline-code style.
+
+So the comparison is against "a global `code { }` rule", and the improvements are specific:
+
+- **It is a component, so a theme can retune every machine value in the product at once** rather than hunting for a global rule that some card overrode.
+- **`@hue` makes it tintable per instance**, which is what lets **FieldError**'s rule-id provenance, an error trace and a normal id look related but distinguishable.
+- **The context-aware margins** (above) — a global `code` rule cannot know it is in a table cell without the same `:where()` trick, and almost none do it.
+- **The size is a fixed small step** (`--boxel-font-size-2xs` by default), so the mono value sits at about the optical size of body text rather than the visually larger result you get from matching point sizes.
+
+Where it is thinner: no copy affordance (compose **CopyButton** beside it), no truncation for long values (it stays on one line unless `@wrap` is set, so a long path overflows), and no block variant.
+
+## Accessibility
+
+No pattern governs it. `<code>` is a semantic element with no interaction contract.
+
+Notes and gaps:
+
+- **`<code>` semantics are announced inconsistently.** Some screen readers say "code" before the content, some enter a verbatim/character-by-character mode, and most say nothing. That is a property of `<code>`, not of this component, and it is generally the right trade — the element is the honest markup for a machine value.
+- **Long or opaque values are hostile to speech.** A UUID or a hash announced character by character is unusable, and announced as a word is meaningless. If a Token holds something a screen-reader user might need to transcribe, pair it with a **CopyButton** — that is the accessible affordance, not the text.
+- **`white-space: nowrap`** is the default, so a long value overflows its container rather than wrapping, which can push a card horizontally and fail **WCAG 1.4.10 Reflow** at 320px. This is the most likely practical problem: paths and URLs are exactly what people put in Tokens. Set `@wrap` wherever the value can be long.
+- **Contrast.** By default the text is `--card-foreground` on `--card`, the theme's own guaranteed pair. A `@hue` replaces the text color, so pass an ink (`--primary-ink`, `--muted-foreground`), not a pale fill hue, and check it at the size it is used (11px by default, smaller at `@size='xs'`).
+- **The hue carries no meaning** and there is no non-color channel, so do not use `@hue` to encode state — use two components, or add text.
+- Nothing is focusable, correctly.
+
+## Theming
+
+`--card` (the surface) with `--card-foreground` (the text) and `--border` (the ring), plus `--boxel-border-radius-xs`, `--boxel-sp-2xs` and `--font-mono`. `--pretui-token-hue` sets the text color, on the Token (through `@hue`, a class or `style`) or on any ancestor; pass an ink such as `--primary-ink` or `--muted-foreground`, not a pale fill hue. `--pretui-token-font-size` sets an exact size; unset, the default is `--boxel-font-size-2xs`, and `@size` takes the house scale (`--pretui-size-*`).
+
+The default line height matches Chip's 18px, so a Token and a Chip side by side line up.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,128 @@
+// Pretui — Token usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Token } from './token';
+import { PRETUI_SIZES, type PretuiSize } from '../pretui-primitives';
+
+// The size knob's choices: the 2xs default plus the house scale.
+const BODY_SIZE = 'default';
+const SIZES = [BODY_SIZE, ...PRETUI_SIZES];
+// The hue knob's choices: the default plus inks, since the hue is the text
+// color and has to read on --card.
+const DEFAULT_HUE = 'var(--card-foreground)';
+const HUES = [
+  DEFAULT_HUE,
+  'var(--muted-foreground)',
+  'var(--primary-ink)',
+  'var(--success-ink)',
+  'var(--destructive-ink)',
+];
+
+class TokenUsage extends Component {
+  @tracked value = 'records@2.4.0';
+  @tracked size = BODY_SIZE;
+  @tracked hue = DEFAULT_HUE;
+  @tracked wrap = false;
+  setValue = (v: string) => (this.value = v);
+  setSize = (v: string) => (this.size = v);
+  setHue = (v: string) => (this.hue = v);
+  toggleWrap = (v: boolean) => (this.wrap = v);
+  get sizeVal() {
+    return this.size === BODY_SIZE ? undefined : (this.size as PretuiSize);
+  }
+  get hueVal() {
+    return this.hue === DEFAULT_HUE ? undefined : this.hue;
+  }
+  get usage() {
+    let bits = [`@value='${this.value}'`];
+    if (this.sizeVal) {
+      bits.push(`@size='${this.sizeVal}'`);
+    }
+    if (this.hueVal) {
+      bits.push(`@hue='${this.hueVal}'`);
+    }
+    if (this.wrap) {
+      bits.push('@wrap={{true}}');
+    }
+    return `<Token ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Token'
+      @description='Machine values set as jewelry: compact mono pills that remain inline in prose and trim their margin when flush-set in a cell.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <p class='foundation-prose'>Imported
+          <Token
+            @value={{this.value}}
+            @size={{this.sizeVal}}
+            @hue={{this.hueVal}}
+            @wrap={{this.wrap}}
+          />
+          for lot
+          <Token @value='LOT-B-103' />
+          in
+          <Token @value='ctse/pretui' />.</p>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{SIZES}}
+          @defaultValue={{BODY_SIZE}}
+          @description='House scale xs|s|m|l|xl, the same steps as Button; sets the font-size, with the line box growing past 18px. Omitted, the size is --boxel-font-size-2xs, or --pretui-token-font-size when that is set (Pretui addition).'
+          @onInput={{this.setSize}}
+        />
+        <Args.String
+          @name='hue'
+          @value={{this.hue}}
+          @options={{HUES}}
+          @defaultValue={{DEFAULT_HUE}}
+          @description='Validated CSS color for the text. Sets --pretui-token-hue, and stays set when the caller also passes a style attribute.'
+          @onInput={{this.setHue}}
+        />
+        <Args.Bool
+          @name='wrap'
+          @value={{this.wrap}}
+          @defaultValue={{false}}
+          @description='Let a long value (a path, a rule, free text) wrap and break instead of overflowing on one line (Pretui addition).'
+          @onInput={{this.toggleWrap}}
+        />
+        <Args.Yield
+          @name='default'
+          @description='Alternative to value for inline content.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-token-hue'
+          @type='color'
+          @description='Text color. Set on the Token or any ancestor, or through @hue.'
+          @defaultValue='var(--card-foreground)'
+        />
+        <Css.Basic
+          @name='pretui-token-font-size'
+          @type='dimension'
+          @description='Exact font-size for a Token with no @size, such as var(--boxel-font-size-xs). Set on the Token or any ancestor; @size wins over it.'
+          @defaultValue='var(--boxel-font-size-2xs)'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .foundation-prose {
+        margin: 0;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TOKEN: Record<string, unknown> = {
+  Token: TokenUsage,
+};

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

@@ -0,0 +1,62 @@
+// Pretui — Toolbar: a header strip with a title, eyebrow, meta and trailing actions.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+export interface ToolbarSignature {
+  Args: { title?: string; eyebrow?: string; meta?: string };
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+export const Toolbar: TemplateOnlyComponent<ToolbarSignature> = <template>
+  <div class='pretui-toolbar' data-test-pretui-toolbar ...attributes>
+    <div class='pretui-toolbar-id'>
+      {{#if @eyebrow}}<span class='pretui-eyebrow'>{{@eyebrow}}</span>{{/if}}
+      {{#if @title}}<h2>{{@title}}</h2>{{/if}}
+      {{#if @meta}}<span class='pretui-toolbar-meta'>{{@meta}}</span>{{/if}}
+    </div>
+    <div class='pretui-toolbar-actions'>{{yield}}</div>
+  </div>
+  <style scoped>
+    @layer PretComponent {
+      .pretui-toolbar {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: var(--space-4, 11px);
+        min-height: 44px;
+      }
+      .pretui-toolbar-id {
+        display: grid;
+        gap: 1px;
+        min-width: 0;
+      }
+      .pretui-toolbar-id h2 {
+        margin: 0;
+        font-size: var(--text-heading, 19px);
+        font-weight: var(--weight-heading, 700);
+        letter-spacing: var(--track-heading, -0.02em);
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+      .pretui-eyebrow {
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        font-weight: 500;
+        letter-spacing: var(--track-eyebrow, 0.08em);
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+      .pretui-toolbar-meta {
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .pretui-toolbar-actions {
+        display: flex;
+        align-items: center;
+        gap: var(--space-3, 8px);
+        flex: none;
+      }
+    }
+  </style>
+</template>;

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

@@ -0,0 +1,50 @@
+## What it is
+
+The title row above a region: identity on the left (eyebrow, title, meta), actions on the right. It paints nothing — no surface, no border — so it sits directly on a page or above a **Panel** without doubling its chrome. Use it as the header of a view. If the region needs its own surface, use **Panel** (whose header is a lighter version of the same idea). If you need a dense row of icon actions with keyboard traversal, that is **ActionBar** or a **ButtonGroup**; this is a page header, not an ARIA toolbar.
+
+## The contract
+
+```
+@title?, @eyebrow?, @meta?
+<:default>   — the actions
+Element: HTMLDivElement
+```
+
+All three text args are optional and each renders only when present, so a Toolbar can be actions-only.
+
+**The identity column is `min-width: 0` and the title truncates.** `white-space: nowrap; overflow: hidden; text-overflow: ellipsis` on the `<h2>`, with `flex: none` on the actions. The consequence is the right one: when space is tight, the **title** loses characters and the buttons stay whole and clickable. Most hand-built header rows do the opposite and wrap the buttons onto a second line.
+
+`min-height: 44px` sets the row's rhythm even when it holds only text — so a page of stacked sections has consistent header heights whether or not each has actions.
+
+`@meta` is the third line of the identity stack (after eyebrow and title): a record count, a timestamp, a status phrase.
+
+## Prior art
+
+**SLDS `page-header`** is the closest full-featured analogue — a title row with breadcrumb, meta, detail rows, and an action region. **Web Awesome** has no page header; its `wa-page` component handles layout at a higher level. **shadcn** has no header component; the convention is hand-rolled flex markup per page. **React Spectrum** does not ship one either.
+
+So the comparison is really against "everybody writes this by hand", and Pretui's improvement is that **the truncation and flex behaviour are decided once**. The two things every hand-built header gets wrong — actions wrapping instead of the title truncating, and inconsistent row heights — are both fixed by construction here.
+
+Against SLDS: much smaller. No breadcrumb slot (compose **Breadcrumb** above it), no detail-row region, no icon slot, no variants. That is a defensible floor, but note there is no `<:leading>` block, so putting an avatar or an icon before the title means wrapping the whole thing yourself.
+
+The shared eyebrow voice with **Panel**, **DataGrid** and **FormField** is the quiet win: one mono uppercase treatment across the kit means "category" always looks the same.
+
+## Accessibility
+
+No APG pattern applies, and it is worth being explicit about why: **this is not an ARIA toolbar.** The APG **Toolbar** pattern means `role="toolbar"`, a single tab stop, and arrow-key traversal between at least three controls. This component sets no role, so its actions are ordinary tab stops in document order — which is the correct behaviour for a page header with two or three buttons, and would be the wrong behaviour for a dense formatting toolbar. The name is the misleading part, not the implementation.
+
+Gaps:
+
+- **The title is a hard-coded `<h2>`.** Same problem as **Panel**: a card does not know its host's outline, so every Toolbar emits an `h2` whatever its depth. There is no `@headingLevel` knob, and **ErrorSummary** already demonstrates the fix. This is the clearest thing to change.
+- **The truncated title has no `title` attribute and no full-text fallback.** When the `<h2>` ellipsizes there is no way — by pointer or by keyboard — to read the whole thing. Screen readers announce the full text (the string is in the DOM), so this is a sighted-user problem specifically, and a WCAG **1.4.4/1.4.10** concern at high zoom where truncation kicks in early.
+- **The root is a `<div>`, not a `<header>`.** Given it carries the region's heading, `<header>` would give it `banner`-adjacent structure inside a `<section>` for free.
+- **`@eyebrow` and `@meta` are loose text around the heading**, unwired to it — announced in reading order, which is acceptable but means the heading alone is often not self-describing ("Overview" where "REVENUE · Overview · 24 records" is meant).
+- **`min-height: 44px`** is a good target-size floor for the row, but the actions inside are **Button**s at 28px, which clears WCAG 2.5.8's 24×24 minimum only narrowly; adjacent icon actions with no gap will have touching targets.
+- If you _do_ have three or more related icon actions here, wrap them in something with `role="toolbar"` — the pattern's whole point is shortening the tab sequence, and this component does not do it.
+
+## Theming
+
+`--muted-foreground` (eyebrow and meta ink), `--foreground` (title, inherited), `--font-mono` + `--text-ui-xs` + `--track-eyebrow` (eyebrow voice), `--text-heading` + `--weight-heading` + `--track-heading` (title), `--text-ui-sm` (meta), `--space-3` (action gap), `--space-4` (column gap).
+
+The component paints no background and casts no shadow — it inherits whatever it sits on. That is why it composes above a **Panel** without a seam, and it also means a theme cannot give headers their own band without wrapping them. The 44px minimum height is fixed and is the one metric a dense theme would want to retune.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,78 @@
+// Pretui — Toolbar usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Toolbar } from './toolbar';
+import { Button } from './button';
+
+// ── Toolbar ← header/usage.gts ───────────────────────────────────────────
+// Dropped knobs: size (Toolbar has a single scale); hasBackground and
+// hasBottomBorder (Toolbar is transparent chrome — no style args); icon
+// block (no icon slot on Toolbar).
+class ToolbarUsage extends GlimmerComponent {
+  @tracked title = 'Title';
+  @tracked eyebrow = 'pretui / structure';
+  @tracked meta = 'usually shown at the top of card containers';
+  setTitle = (v: string) => (this.title = v);
+  setEyebrow = (v: string) => (this.eyebrow = v);
+  setMeta = (v: string) => (this.meta = v);
+  get usage() {
+    let bits: string[] = [];
+    if (this.eyebrow) bits.push(`@eyebrow='${this.eyebrow}'`);
+    if (this.title) bits.push(`@title='${this.title}'`);
+    if (this.meta) bits.push(`@meta='${this.meta}'`);
+    return `<Toolbar ${bits.join(' ')}>…</Toolbar>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Toolbar'
+      @description='Usually shown at the top of card containers: an identity cluster (eyebrow, title, meta) with actions aligned to the end.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Toolbar
+          @title={{this.title}}
+          @eyebrow={{this.eyebrow}}
+          @meta={{this.meta}}
+          class='toolbar-box'
+        >
+          <Button @tone='neutral' @appearance='outlined' @size='s'>Options</Button>
+          <Button @tone='primary' @size='s'>New</Button>
+        </Toolbar>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='title'
+          @description='Title'
+          @value={{this.title}}
+          @onInput={{this.setTitle}}
+        />
+        <Args.String
+          @name='eyebrow'
+          @description='Mono uppercase overline rendered above the title.'
+          @value={{this.eyebrow}}
+          @onInput={{this.setEyebrow}}
+        />
+        <Args.String
+          @name='meta'
+          @description='Muted meta line rendered under the title.'
+          @value={{this.meta}}
+          @onInput={{this.setMeta}}
+        />
+        <Args.Yield
+          @description='Content aligned to the end of the container — the header :detail block folds in here as the actions area.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .toolbar-box {
+        width: 100%;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TOOLBAR: Record<string, unknown> = {
+  Toolbar: ToolbarUsage,
+};