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

package/bundled-realms/pretui/components/alert-dialog.gts

@@ -0,0 +1,223 @@
+// Pretui — AlertDialog: a modal confirmation that demands an explicit answer.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { guidFor } from '@ember/object/internals';
+import { on } from '@ember/modifier';
+import { Dialog } from './dialog';
+import { Button } from './button';
+import type { PretuiTone } from '../pretui-primitives';
+import { listenDocumentCapture } from '../focus';
+
+// ─────────────────────────────────────────────────────────────────────────
+// AlertDialog
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface AlertDialogSignature {
+  Args: {
+    /** controlled open state; omit for uncontrolled */
+    open?: boolean;
+    /** the uncontrolled starting state */
+    defaultOpen?: boolean;
+    /** fires on every transition, controlled or not */
+    onOpenChange?: (open: boolean) => void;
+    /** the question, as a string. `<:header>` takes markup instead. */
+    title?: string;
+    /** the consequence, as a string. `<:default>` takes markup instead. */
+    description?: string;
+    /** the confirm button's label (default 'Continue') */
+    confirmLabel?: string;
+    /** the cancel button's label (default 'Cancel') */
+    cancelLabel?: string;
+    /** tone of the confirm button (default 'danger' — this is the pattern
+     * for destructive actions, and a neutral confirm is the unusual case) */
+    tone?: PretuiTone;
+    /** puts the confirm button in its pending state without disabling it */
+    busy?: boolean;
+    size?: 's' | 'm' | 'l';
+    /** Escape cancels (default true). Outside clicks NEVER dismiss — that is
+     * the difference from Dialog, and it is not a knob. */
+    dismissOnEscape?: boolean;
+    onConfirm?: () => void;
+    onCancel?: () => void;
+  };
+  Blocks: {
+    trigger: [open: boolean, toggle: () => void];
+    header: [];
+    default: [];
+    footer: [confirm: () => void, cancel: () => void];
+  };
+  Element: HTMLDialogElement;
+}
+
+/**
+ * The destructive-confirm every shadcn app has, composed from `Dialog`.
+ *
+ * Four things separate it from a Dialog, and each one is a decision rather
+ * than a style:
+ *
+ *  1. **It is always modal.** A confirmation that can be ignored by clicking
+ *     past it is not a confirmation.
+ *  2. **No dismiss on outside click.** A stray click must not read as an
+ *     answer. `Dialog`'s single `@dismissible` flag conflates outside-click
+ *     with Escape, so this passes `@dismissible={{false}}` and takes Escape
+ *     itself — in the capture phase, so a host listening for Escape cannot
+ *     make one keypress mean two things.
+ *  3. **Focus starts on Cancel.** Cancel is first in DOM order, so the native
+ *     `<dialog>` focusing steps land there with no JS at all — the platform
+ *     doing the work is both smaller and more reliable than a focus call.
+ *     Reading order stays Cancel → Confirm, which is also the shadcn layout.
+ *  4. **`role='alertdialog'`**, which is what tells assistive technology this
+ *     interrupts rather than presents, plus `aria-labelledby` on the question
+ *     and `aria-describedby` on the consequence.
+ *
+ * **Better than shadcn/Radix:** Radix's `AlertDialogAction` closes the dialog
+ * on click whether or not the work succeeded, so a failed confirm leaves no
+ * surface to report the failure on. `@busy` here holds the dialog open with
+ * the confirm button in Button's *pending* state — `aria-busy` and inert, with
+ * focus retained, never the native `disabled` attribute that would drop focus
+ * onto the body mid-action.
+ */
+export class AlertDialog extends Component<AlertDialogSignature> {
+  private guid = guidFor(this);
+  @tracked private internalOpen = this.args.defaultOpen ?? false;
+
+  get isOpen(): boolean {
+    return this.args.open ?? this.internalOpen;
+  }
+  get titleId(): string {
+    return this.guid + '-title';
+  }
+  get descId(): string {
+    return this.guid + '-desc';
+  }
+  get confirmLabel(): string {
+    return this.args.confirmLabel ?? 'Continue';
+  }
+  get cancelLabel(): string {
+    return this.args.cancelLabel ?? 'Cancel';
+  }
+  get tone(): PretuiTone {
+    return this.args.tone ?? 'danger';
+  }
+
+  private setOpen(next: boolean) {
+    if (this.args.open === undefined) {
+      this.internalOpen = next;
+    }
+    this.args.onOpenChange?.(next);
+  }
+
+  toggle = () => {
+    this.setOpen(!this.isOpen);
+  };
+
+  confirm = () => {
+    // Pending is inert without being disabled: a second activation while the
+    // caller's work is in flight must not fire it twice, but the button has
+    // to stay focusable for the announcement to reach anyone.
+    if (this.args.busy) {
+      return;
+    }
+    this.args.onConfirm?.();
+    if (!this.args.busy) {
+      this.setOpen(false);
+    }
+  };
+
+  cancel = () => {
+    this.args.onCancel?.();
+    this.setOpen(false);
+  };
+
+  /** Dialog requires an `@onClose`; with `@dismissible={{false}}` it is never
+   * called, but wiring it to cancel means a platform-level close (a future
+   * `requestClose`, a devtools call) still routes through one path. */
+  onPlatformClose = () => {
+    this.cancel();
+  };
+
+  onEscape = (event: Event) => {
+    if ((this.args.dismissOnEscape ?? true) === false) {
+      return;
+    }
+    let ev = event as KeyboardEvent;
+    if (ev.key !== 'Escape' || !this.isOpen) {
+      return;
+    }
+    ev.preventDefault();
+    ev.stopPropagation();
+    this.cancel();
+  };
+
+  <template>
+    {{#if (has-block 'trigger')}}
+      <span class='pretui-ad-trigger' data-test-pretui-alertdialog-trigger>
+        {{yield this.isOpen this.toggle to='trigger'}}
+      </span>
+    {{/if}}
+
+    <Dialog
+      @open={{this.isOpen}}
+      @onClose={{this.onPlatformClose}}
+      @dismissible={{false}}
+      @size={{@size}}
+      role='alertdialog'
+      aria-labelledby={{this.titleId}}
+      aria-describedby={{this.descId}}
+      data-test-pretui-alertdialog
+      ...attributes
+    >
+      <:title>
+        <span id={{this.titleId}}>
+          {{#if (has-block 'header')}}{{yield to='header'}}{{else}}{{@title}}{{/if}}
+        </span>
+      </:title>
+      <:default>
+        {{#if this.isOpen}}
+          {{!-- Escape is taken in the capture phase and only while open, so
+                the listener's lifetime is exactly the dialog's open life. --}}
+          <span
+            class='pretui-ad-watch'
+            {{listenDocumentCapture 'keydown' this.onEscape}}
+          ></span>
+        {{/if}}
+        <div id={{this.descId}}>
+          {{#if (has-block)}}{{yield}}{{else}}{{@description}}{{/if}}
+        </div>
+      </:default>
+      <:footer>
+        {{#if (has-block 'footer')}}
+          {{yield this.confirm this.cancel to='footer'}}
+        {{else}}
+          {{!-- Cancel first in DOM order: the native dialog focusing steps
+                land on the first focusable, so the safe choice is focused
+                without a single focus() call. --}}
+          <Button
+            @tone='neutral'
+            @appearance='outlined'
+            data-test-pretui-alertdialog-cancel
+            {{on 'click' this.cancel}}
+          >{{this.cancelLabel}}</Button>
+          <Button
+            @tone={{this.tone}}
+            @appearance='accent'
+            @busy={{@busy}}
+            data-test-pretui-alertdialog-confirm
+            {{on 'click' this.confirm}}
+          >{{this.confirmLabel}}</Button>
+        {{/if}}
+      </:footer>
+    </Dialog>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-ad-trigger {
+          display: inline-flex;
+        }
+        .pretui-ad-watch {
+          display: none;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/alert-dialog.md

@@ -0,0 +1,76 @@
+## What it is
+
+A **decision**, not a notification. The user must confirm or cancel before the app continues: delete a record, overwrite a file, leave a dirty form. It is a **Dialog** with a locked contract: a question, its consequence, Cancel and Confirm. Confirm defaults to `@tone='danger'`, because the pattern exists for destructive actions.
+
+If the question is tiny and can sit next to its trigger, use **Popconfirm**. If the message informs rather than asks, and stays in flow, use **Alert**. If it is transient, **Toast**. If the answer needs a form, it is a **Dialog**, not an AlertDialog.
+
+```mermaid
+flowchart TD
+  Q{Needs a decision?}
+  Q -->|in flow, persistent| Alert
+  Q -->|transient| Toast
+  Q -->|tiny, next to trigger| Popconfirm
+  Q -->|blocks the app| AlertDialog
+  Q -->|has a form| Dialog
+```
+
+## The contract
+
+```
+@open?, @defaultOpen?, @onOpenChange?
+@title?, @description?
+@confirmLabel? ('Continue'), @cancelLabel? ('Cancel')
+@tone? (default 'danger' — the confirm button's tone)
+@busy?, @size? ('s' | 'm' | 'l'), @dismissOnEscape? (default true)
+@onConfirm?, @onCancel?
+<:trigger as |open toggle|>   — renders the opener, uncontrolled
+<:header>                     — replaces @title with markup
+<:default>                    — replaces @description with markup
+<:footer as |confirm cancel|> — replaces the Cancel / Confirm pair
+Element: HTMLDialogElement
+```
+
+**Controlled or not.** Pass `@open` and it is controlled. Omit it and `@defaultOpen` sets the starting state, with `<:trigger>` toggling it. `@onOpenChange` fires on every transition either way.
+
+**An outside click never answers.** Dialog's one dismissible flag covers both the scrim and Escape, so AlertDialog turns it off and handles Escape itself. It listens in the capture phase and only while open, so one keypress cannot also reach a host shortcut. `@dismissOnEscape={{false}}` removes even that, leaving the two buttons as the only way out. Outside-click dismissal is not a knob.
+
+**Confirm can wait for the work.** Confirm calls `@onConfirm` and closes, unless `@busy` is true once the handler returns. Then the dialog stays open and the confirm button goes pending through Button's own `@busy`: a spinner, `aria-busy="true"` and `aria-disabled`, never the native `disabled` attribute, so focus stays on it. A second activation while busy is ignored. When the caller clears `@busy` it closes the dialog through `@open` (or `@onOpenChange`), or leaves it open to report a failure in place.
+
+Cancel calls `@onCancel`, then closes. A platform-level close routes through the same path.
+
+## Prior art
+
+**shadcn AlertDialog** is Radix AlertDialog: Root / Trigger / Portal / Overlay / Content, plus Header / Footer / Title / Description / Action / Cancel, with Content `size` `default | sm`. **Ant `Modal.confirm`** is imperative: `Modal.confirm({ title, onOk })`, and agents will emit that shape. **MUI** composes a plain Dialog with `aria-labelledby`. **React Spectrum** `AlertDialog` has a `variant` and focuses the primary button.
+
+Where Pretui is better: **a failed confirm has somewhere to go.** Radix's `AlertDialogAction` closes the dialog on click whether or not the work succeeded. `@busy` holds it open with the button pending and still focused, so the result can be announced where the user is looking. **Focus lands on Cancel** with no script: Cancel is first in DOM order, and the native `<dialog>` focusing steps pick the first focusable. Spectrum focuses the destructive button, and that is the wrong default for this pattern.
+
+Where it is thinner: **no imperative helper.** There is no promise-returning `confirm()` for the Ant shape. The caller renders the component and wires `@open`. **No media slot** for an icon or illustration beside the question.
+
+## Accessibility
+
+APG **Alert and Message Dialogs**. The element is the native `<dialog>` opened modally, with `role="alertdialog"`, `aria-labelledby` on the question and `aria-describedby` on the consequence. The ids are generated per instance, and the tests assert all three.
+
+- **Initial focus is Cancel**, the least destructive choice. That comes from the native focusing steps, and the tests assert the precondition: Cancel is the first button in the dialog, Confirm the second.
+- **Escape cancels, never confirms.** An outside click does nothing. The tests assert both.
+- **Pending is announced, not disabled.** `aria-busy="true"` keeps the confirm button in the accessibility tree and focused while the work runs. The tests assert it carries `aria-busy`, is not natively disabled, and ignores a second activation.
+- **The labels are the caller's job.** "Continue" is a weak default for a destructive action. Say what happens (`@confirmLabel='Delete project'`), and put the consequence in `@description`, which becomes the accessible description.
+- **A custom `<:footer>` gives up the defaults.** Keep Cancel first in DOM order if you want the focus behaviour.
+
+## Theming
+
+AlertDialog adds no tokens of its own. It wears **Dialog**'s: `--card`, `--foreground`, `--muted-foreground`, `--border`, `--radius-surface`, `--pretui-shadow-overlay`, `--pretui-overlay-scrim`, `--text-heading`, `--weight-heading`, `--track-heading`, `--text-body`, `--leading-body`, `--space-3`, `--space-4` and `--space-6`. The buttons are **Button**'s: the confirm tone reads `--destructive` / `--destructive-foreground` for `danger`, and `--pretui-button-*` for size and shape.
+
+A theme that retunes Dialog and Button retunes every AlertDialog with them. The Cancel-then-Confirm order and the outlined-then-accent pairing are fixed.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                         | Give them                                   |
+| ----------------------------------- | ------------------------------------------- |
+| `<AlertDialog open onOpenChange>`   | `@open` / `@onOpenChange`                   |
+| AlertDialogTitle / Description      | `@title` / `@description`, or the blocks    |
+| AlertDialogAction / Cancel          | the default footer, or `<:footer>`          |
+| `variant="destructive"`             | `@tone='danger'` (the default)              |
+| Ant `onOk` / `onCancel`, `okText`   | `@onConfirm` / `@onCancel`, `@confirmLabel` |
+| `Modal.confirm({...})` (imperative) | render the component; no helper             |

package/bundled-realms/pretui/components/alert-dialog.usage.gts

@@ -0,0 +1,128 @@
+// Pretui — AlertDialog usage page.
+import GlimmerComponent from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { tracked } from '@glimmer/tracking';
+import { AlertDialog } from './alert-dialog';
+import { Button } from './button';
+import { FreestyleUsage } from './freestyle-usage';
+
+// ── AlertDialog ──────────────────────────────────────────────────────────
+
+class AlertDialogUsage extends GlimmerComponent {
+  @tracked open = false;
+  @tracked busy = false;
+  @tracked log = '—';
+
+  setOpen = (next: boolean) => (this.open = next);
+  confirmed = () => (this.log = 'Deleted 47 records');
+  cancelled = () => (this.log = 'Cancelled');
+  setBusy = (value: boolean) => (this.busy = value);
+
+  <template>
+    <FreestyleUsage
+      @name='AlertDialog'
+      @description='The destructive confirm, composed from Dialog. Four things separate it from a Dialog and each is a decision rather than a style: it is always modal, an outside click never dismisses it, focus starts on Cancel, and its role is alertdialog so assistive tech is told this interrupts rather than presents. Cancel is FIRST in DOM order, which means the native dialog focusing steps land on the safe choice with no focus() call at all — the platform does the work. Escape is taken in the capture phase, so a host page that also listens for Escape cannot make one keypress mean two things.'
+    >
+      <:example>
+        <div class='oc-row'>
+          <AlertDialog
+            @open={{this.open}}
+            @onOpenChange={{this.setOpen}}
+            @title='Delete 47 records?'
+            @description='They will be removed from the index immediately and from the archive at the next sweep. This cannot be undone.'
+            @confirmLabel='Delete records'
+            @cancelLabel='Keep them'
+            @busy={{this.busy}}
+            @onConfirm={{this.confirmed}}
+            @onCancel={{this.cancelled}}
+          >
+            <:trigger as |isOpen toggle|>
+              <Button
+                @tone='danger'
+                @appearance='outlined'
+                {{on 'click' toggle}}
+              >{{if isOpen 'Close' 'Delete records…'}}</Button>
+            </:trigger>
+          </AlertDialog>
+          <span class='oc-log'>last action: <strong>{{this.log}}</strong></span>
+        </div>
+        <p class='oc-hint'>Open it and press Tab once: focus is already on
+          <em>Keep them</em>, so the first thing the keyboard can do is the safe
+          thing. Click the scrim and nothing happens. Escape cancels.</p>
+      </:example>
+      <:api as |Args|>
+        <Args.Base
+          @name='open / onOpenChange / defaultOpen'
+          @description='The controlled and uncontrolled halves of one contract. onClose alone is never enough — a parent that can be told the dialog closed but cannot open it has not been given control of it.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='title'
+          @description='The question. The header block takes markup instead, and either way the element carries the id that aria-labelledby points at.'
+          @value='Delete 47 records?'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='description'
+          @description='The consequence, wired as aria-describedby. The default block takes markup instead.'
+          @hideControls={{true}}
+        />
+        <Args.Bool
+          @name='busy'
+          @description='Holds the dialog open with the confirm button pending. Radix closes on click whether or not the work succeeded, which leaves a failed confirm with no surface to report on. Pending here is React Aria semantics — aria-busy with focus retained, never the native disabled attribute, which would drop focus on the body mid-action.'
+          @value={{this.busy}}
+          @defaultValue={{false}}
+          @onInput={{this.setBusy}}
+        />
+        <Args.Base
+          @name='tone / confirmLabel / cancelLabel / size'
+          @description='Tone defaults to danger because that is the pattern; a neutral confirm is the unusual case. The two labels should name the verb, not say Yes and No — a button reading Delete records is answerable without re-reading the question.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='dismissOnEscape'
+          @description='Escape cancels by default. Outside clicks NEVER dismiss and that is deliberately not a knob: a stray click must not read as an answer.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='trigger / header / default / footer'
+          @description='The overlay block set. The footer block receives confirm and cancel, so a caller replacing the buttons keeps the wiring. Radix compound children map one to one onto these blocks — AlertDialogTitle is the header block, AlertDialogFooter is the footer block.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .oc-row {
+        display: flex;
+        align-items: center;
+        gap: var(--space-4, 11px);
+        flex-wrap: wrap;
+      }
+      .oc-log {
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .oc-log strong {
+        color: var(--foreground);
+        font-weight: 600;
+      }
+      .oc-hint {
+        margin: var(--space-4, 11px) 0 0;
+        max-width: 62ch;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.6;
+        color: var(--muted-foreground);
+      }
+      .oc-hint em {
+        font-style: normal;
+        font-weight: 600;
+        color: var(--foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_ALERT_DIALOG: Record<string, unknown> = {
+  AlertDialog: AlertDialogUsage,
+};

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

@@ -0,0 +1,163 @@
+// Pretui — Alert: an inline message with a tone, a title and an optional action.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import AlertTriangleIcon from '@cardstack/boxel-icons/alert-triangle';
+import CheckIcon from '@cardstack/boxel-icons/check';
+import InfoIcon from '@cardstack/boxel-icons/info-small';
+import XIcon from '@cardstack/boxel-icons/x';
+import { keepStyle, type KeptProperty } from '../internal/keep-style';
+import { resolveTone } from '../pretui-primitives';
+import type { PretuiToneArg } from '../pretui-primitives';
+import { VisuallyHidden } from './visually-hidden';
+
+type AlertTone = 'info' | 'success' | 'warning' | 'danger';
+const ALERT_TONES: readonly AlertTone[] = [
+  'info',
+  'success',
+  'warning',
+  'danger',
+];
+// shadcn's Alert has one `variant` enum rather than a tone. Both of its
+// values map onto tones this component already paints.
+const ALERT_VARIANTS: Record<string, AlertTone> = {
+  default: 'info',
+  destructive: 'danger',
+};
+// Each tone names its fill and the fill's paired foreground (the ink that
+// reads on the disc). The text is `--foreground`: the `-ink` tokens are only
+// guaranteed on `--background`, `--card` and `--muted`, not on the tint.
+const ALERT_COLORS: Record<AlertTone, { hue: string; onHue: string }> = {
+  info: {
+    hue: 'var(--info)',
+    onHue: 'var(--info-foreground)',
+  },
+  success: {
+    hue: 'var(--success)',
+    onHue: 'var(--success-foreground)',
+  },
+  warning: {
+    hue: 'var(--warning)',
+    onHue: 'var(--warning-foreground)',
+  },
+  danger: {
+    hue: 'var(--destructive)',
+    onHue: 'var(--destructive-foreground)',
+  },
+};
+const ALERT_ICONS = {
+  info: InfoIcon,
+  success: CheckIcon,
+  warning: AlertTriangleIcon,
+  danger: XIcon,
+};
+// The glyph is hidden from assistive technology, so the tone is spoken as a
+// word instead. Without it, `info`, `success` and `warning` all share
+// `role="status"` and are announced identically.
+const ALERT_TONE_LABELS: Record<AlertTone, string> = {
+  info: 'Info',
+  success: 'Success',
+  warning: 'Warning',
+  danger: 'Error',
+};
+
+export interface AlertSignature {
+  Args: {
+    /** accepts the React tone spellings — `destructive`/`error` → danger,
+     * `positive` → success, `notice` → warning. Tones outside the four an
+     * Alert paints fall back to `info` rather than emitting a dead
+     * `data-tone`. */
+    tone?: AlertTone | PretuiToneArg;
+    title?: string;
+    /** alias — shadcn's one-enum Alert API (`default` | `destructive`) */
+    variant?: 'default' | 'destructive';
+    /** the tone word a screen reader hears before the title, in place of the
+     * hidden glyph. Defaults by tone: Info, Success, Warning, Error. */
+    toneLabel?: string;
+  };
+  Blocks: { default: []; action: [] };
+  Element: HTMLDivElement;
+}
+
+export class Alert extends Component<AlertSignature> {
+  get tone(): AlertTone {
+    let fromVariant = this.args.variant
+      ? ALERT_VARIANTS[this.args.variant]
+      : undefined;
+    return resolveTone(this.args.tone, ALERT_TONES, fromVariant ?? 'info');
+  }
+  get role() {
+    return this.tone === 'danger' ? 'alert' : 'status';
+  }
+  get hueStyle() {
+    let { hue, onHue } = ALERT_COLORS[this.tone];
+    return htmlSafe(`--pretui-alert-hue: ${hue}; --pretui-alert-on-hue: ${onHue}`,
+    );
+  }
+  // The same properties again, kept on top of a caller's `style`: a caller's
+  // `style` attribute replaces the component's own, and the tint, hairline
+  // and glyph disc all read these properties.
+  get keptStyle(): KeptProperty[] {
+    let { hue, onHue } = ALERT_COLORS[this.tone];
+    return [
+      { property: '--pretui-alert-hue', value: hue, strength: 'arg' },
+      { property: '--pretui-alert-on-hue', value: onHue, strength: 'arg' },
+    ];
+  }
+  get Glyph() {
+    return ALERT_ICONS[this.tone];
+  }
+  get spokenTone(): string {
+    return `${this.args.toneLabel ?? ALERT_TONE_LABELS[this.tone]}:`;
+  }
+  <template>
+    <div class='pretui-alert' role={{this.role}} style={{this.hueStyle}} {{keepStyle this.keptStyle}} data-test-pretui-alert ...attributes>
+      <span class='pretui-alert-glyph' aria-hidden='true'>
+        <this.Glyph width='12' height='12' />
+      </span>
+      <VisuallyHidden>{{this.spokenTone}}</VisuallyHidden>
+      <div class='pretui-alert-body'>
+        {{#if @title}}<p class='pretui-alert-title'>{{@title}}</p>{{/if}}
+        {{#if (has-block)}}<div>{{yield}}</div>{{/if}}
+        {{#if (has-block 'action')}}<div class='pretui-alert-action'>{{yield to='action'}}</div>{{/if}}
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-alert {
+          --pretui-alert-mix: 20%;
+          display: flex;
+          gap: var(--boxel-sp-xs);
+          padding: var(--boxel-sp-2xs) var(--boxel-sp-xs);
+          border-radius: var(--boxel-border-radius);
+          background-color: color-mix(in oklch, var(--pretui-alert-hue) var(--pretui-alert-mix), var(--card));
+          color: var(--foreground);
+          box-shadow: 0 0 0 1px color-mix(in oklch, var(--pretui-alert-hue) 25%, var(--border));
+          font-size: var(--boxel-font-size-xs);
+        }
+        .pretui-alert-glyph {
+          width: 1rem;
+          height: 1rem;
+          border-radius: 50%;
+          flex: none;
+          display: grid;
+          place-items: center;
+          background-color: var(--pretui-alert-hue);
+          color: var(--pretui-alert-on-hue);
+          margin-top: 1px;
+        }
+        .pretui-alert-body {
+          display: grid;
+          gap: var(--boxel-sp-6xs);
+          min-width: 0;
+        }
+        .pretui-alert-title {
+          margin: 0;
+          font-weight: 600;
+        }
+        .pretui-alert-action {
+          margin-top: var(--boxel-sp-3xs);
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,57 @@
+## What it is
+
+An inline banner carrying a tone: something succeeded, something needs attention, something failed. It sits **in the flow of the page**, next to the thing it is about. Use it for state that persists — a form-level failure, a warning about a record's condition, a note about what a panel is showing. If the message is transient and about an action just taken, use **Toast**. If it belongs to one field, use **FieldError**. If it is the whole content of an empty region, use **EmptyState**.
+
+**Callout** is this same class re-exported under another name, and `callout.md` documents it too, so a change to the tones, roles, glyph or tone word here must also be made there.
+
+## The contract
+
+```
+@tone? 'info' | 'success' | 'warning' | 'danger'   (default 'info')
+@title?
+@toneLabel?   (default by tone: 'Info' | 'Success' | 'Warning' | 'Error')
+<:default>  <:action>
+```
+
+**One hue in, a complete treatment out.** This is the kit's Law 2, and Alert is its clearest expression: `@tone` selects the hue and on-hue custom properties (`--pretui-alert-hue`, `--pretui-alert-on-hue`), and the stylesheet derives the tints from the hue with `color-mix` — a 20% tint over `--card` for the background, a 25% mix with `--border` for the hairline, and the hue neat for the glyph disc. Text uses `--foreground`, so the tint, hairline and disc carry the tone, and the glyph uses the fill's paired `-foreground`. No semantic hexes are baked in anywhere. Adding a fifth tone is one entry in the color map.
+
+Each tone has its own icon from `@cardstack/boxel-icons` (Info, Check, Alert Triangle and X), painted in the tone's `-foreground`. **FieldError** and **ErrorSummary** mark severity with their own glyphs and the same four hues, so a field message, a summary row and a banner about the same thing still read as one system.
+
+**The role flips with the tone**: `danger` gets `role="alert"` (assertive), everything else gets `role="status"` (polite). That is a real decision, not a default — see below.
+
+## Prior art
+
+**Web Awesome `wa-callout`** takes `variant` (`brand|success|neutral|warning|danger`), `appearance` (`accent|filled|outlined|plain`) and `size`, with icon and default slots — a fuller treatment grid, and no ARIA at all (it is presentational by design, leaving the live-region decision to the caller). **shadcn `Alert`** is `default`/`destructive` with `AlertTitle`/`AlertDescription` and hardcodes `role="alert"` on every instance. **React Spectrum `InlineAlert`** has `variant` (`neutral|info|positive|notice|negative`) and, notably, `autoFocus` — it moves focus to itself rather than relying on a live region.
+
+Where Pretui is better than shadcn: **shadcn puts `role="alert"` on an informational banner**, which means an assertive interruption for a message that says "3 records imported". Pretui's tone-driven role is the right granularity — assertive for failures, polite for everything else — and it costs one getter.
+
+Where Pretui is better than Web Awesome: the `color-mix` derivation. Web Awesome's variants are enumerated stylesheets; a new tone means a new block. Here the recipe is written once.
+
+Where it is thinner: no `appearance` axis (Web Awesome's outlined/plain callouts have no equivalent), no dismiss affordance, no icon slot — the icon is fixed per tone.
+
+## Accessibility
+
+Governing pattern: APG **Alert** (`role="alert"`, nothing else required) and the live-region rules generally.
+
+What is right: the assertive/polite split by tone, and the fact that both `alert` and `status` carry implicit `aria-atomic="true"`, so the whole banner is re-read rather than just the changed fragment. The glyph is `aria-hidden`, so the banner is not announced as an image first. The role alone cannot carry the tone: it singles out `danger`, and `info`, `success` and `warning` all share `role="status"`. So a visually hidden tone word sits where the glyph is, and the banner is announced as "Warning: Low credit", the way GOV.UK's warning text carries a hidden "Warning". `@toneLabel` replaces the word, for a translation or a more exact one such as "Caution" on a delete confirmation.
+
+Gaps, and one is significant:
+
+- **The live region is created together with its content.** A live region must exist in the DOM _before_ its content changes to be reliably announced. `{{#if this.showAlert}}<Alert>` mounts the region and its text in the same frame, and several screen readers will say nothing. `role="alert"` is partly exempt — some readers do announce alerts inserted with content already present — but `role="status"` generally is not, so **`info`/`success`/`warning` alerts frequently announce nothing at all**. The fix is the pattern React Aria and Web Awesome both use: one persistent, empty, visually-hidden region that messages are written into. Render the Alert always and toggle its content, or pair it with such a region.
+- **`role="alert"` on a persistent banner is wrong in the other direction.** An Alert that is always present (a standing warning on a record) will be announced on every re-render that touches it. Alerts are for messages that _appear_.
+- **Text is `--foreground`, not the tone's `-ink`.** The `-ink` tokens are only guaranteed on `--background`, `--card` and `--muted`, and the 20% tint is none of those: the default `--destructive-ink` measures under 4.5:1 on the danger tint. `--foreground` clears 4.5:1 on all four tints in light and dark. The glyph disc pairs each fill with its `-foreground`.
+- No dismiss control, so nothing to make keyboard-accessible — which is the honest upside of the smaller API.
+
+## Theming
+
+`--info`, `--success`, `--warning`, `--destructive` (the four tone hues); `--foreground` (text); `--info-foreground`, `--success-foreground`, `--warning-foreground`, `--destructive-foreground` (the glyph's ink on its disc); `--card` (the mix base), `--border` (mixed into the hairline), and the `--boxel-sp-*`, `--boxel-border-radius` and `--boxel-font-size-xs` tokens for geometry and type. The 20% tint strength is the component's own `--pretui-alert-mix`, set on `.pretui-alert`; a caller can override it per instance. A caller's `style` attribute does not remove the tone's hue and on-hue properties: they are written again on top of it.
+
+A theme retunes the entire component by retuning those four hues. Because every derived color is a mix against `--card`, dark mode gets correct dark treatments automatically, but a theme **must** define the four hues at a luminance that survives a 20% mix against a dark `--card`, or all four alerts converge on the same near-black rectangle.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Tremor/WA `Callout` is this component under that name (**Callout**). shadcn Alert is too
+(but they hardcode `role=alert` on info — we do not). Page-level
+outcome is **Result**. Transient is **Toast**.