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

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

@@ -0,0 +1,69 @@
+## What it is
+
+A person or entity as a circle: a photo if there is one, hashed initials if there is not. Use it wherever a record has a human owner — a row's assignee, a comment's author, a presence indicator. For several people in a row, wrap them in **AvatarGroup**. For a record that is not a person, **RecordPill** or **EntityDisplay** carries a name and a type. For a status, **Chip**.
+
+## The contract
+
+```
+@name: string   (required)
+@src?, @hue?, @size? (px at a 16px root, written as rem; default 24, i.e. 1.5rem)
+Element: HTMLSpanElement
+```
+
+**`@name` is required even when `@src` is present**, and that is the load-bearing decision: it is the `alt` text on the image, the `title`, the source of the initials fallback, and the seed for the hue. An avatar without a name is a colored circle, and this component makes that unrepresentable.
+
+**Initials are the first letter of up to two whitespace-separated words**, uppercased. "Ada Lovelace" → "AL", "Cher" → "C", "Jean-Luc Picard" → "JP" (the hyphen is not a separator). Non-Latin scripts get their first two characters, which is right for CJK and wrong for scripts with combining marks — worth knowing before using this for arbitrary user input.
+
+**The hue is `statusHue(@name)`** — the same 32-bit hash used by **StatusChip**, over the name — so a given person is the same color on every card and in every realm, with no registry. Everything else derives from that hue by `color-mix`: a 16% fill over `--card`, a 28% hairline, and `--foreground` for the initials. Same Law 2 recipe as **Chip**, tuned lighter. A photo gets a neutral ring instead of the hue ring: `color-mix(--foreground 10%, transparent)`, set on the root because its `overflow: hidden` circle would clip an outline on the square `img`. The name's hue means nothing once the photo shows, and avatars inside **AvatarGroup** still get the group's `--card` ring.
+
+`@size` sets width, height **and** font size (`round(size * 0.42)` to the whole pixel), so initials scale correctly rather than staying 11px in a 48px circle. The number is the diameter in px at a 16px root, and Avatar writes it as `--pretui-avatar-size` in rem (`@size={{40}}` is `2.5rem`), so it follows the root font size. Without `@size`, nothing is written and the size is `--pretui-avatar-size` from the cascade, `1.5rem` by default, so a class, a container query or an ancestor can set it. Give it a `rem`, `px` or container-query length (`cqi`, `cqw`, …). Those keep the 0.42 type ratio. `em` and `%` do not: the font size resolves them against the parent, while the width and height resolve them against the Avatar's own font size and its containing block, so `3em` under a 16px parent is a 60px disc with 20px type.
+
+```css
+@container (min-width: 400px) {
+  .owner-avatar {
+    --pretui-avatar-size: 3rem;
+  }
+}
+```
+
+**`@hue`, `@size` and a caller's `style` work together.** Glimmer lets a caller's `style` attribute replace a component's own, so Avatar also writes `--pretui-avatar-size` and `--pretui-chip-hue` as single properties on top of whatever style the element ends up with, and writes them 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 one of them too, `@size` and `@hue` win, and the caller's value comes back when the arg is cleared. The name-derived hue is a default rather than an arg, so a `--pretui-chip-hue` in the caller's style wins over it. One rewrite is not told apart from another modifier's write: a caller style that sets both properties exactly as Avatar wrote them and changes some other declaration. Its values are not taken as the caller's, so clearing the arg brings back the caller's earlier value.
+
+## Prior art
+
+**Web Awesome `wa-avatar`** takes `image`, `label`, `initials`, `loading` and `shape` (`circle | square | rounded`), with an icon slot as the third fallback tier. **Radix `Avatar`** is `Root`/`Image`/`Fallback` with a `delayMs` on the fallback so a fast-loading image does not flash initials. **React Spectrum `Avatar`** has `src`, `alt`, `size` and `isDisabled`.
+
+Where Pretui is better: **the hue is derived, not chosen.** Web Awesome and Spectrum both give you one neutral avatar color, so a list of eight initials-only avatars is eight identical gray circles — which defeats the purpose. Deriving the hue from the name makes initials-only avatars genuinely scannable, and it costs no configuration.
+
+Where it is behind, and these are real:
+
+- **No fallback-delay handling.** Radix's `delayMs` exists because rendering initials and then swapping to an image one frame later is a visible flicker in a list. Here the `<img>` renders as soon as `@src` is set, so a slow image shows an empty circle until it loads. A broken image does fall back: its `error` event swaps in the initials for that `@src`, and a new `@src` tries the image again.
+- **No `shape` axis** — always a circle.
+- **No icon tier** for entities that are not people.
+- **No `loading="lazy"`** on the image, which matters in a long list.
+
+## Accessibility
+
+No APG pattern; an avatar is an image or a text fallback.
+
+What is right: `alt={{@name}}` on the image is real alternative text rather than an empty or generic string.
+
+Gaps:
+
+- **The initials case is `role='img'` with `aria-label={{@name}}`** on the root, so it is announced as "Ada Lovelace" rather than the letters "A L". With a photo, the root has neither and the `<img>`'s `alt` carries the name, so it is announced once.
+- **`title` is the only hover affordance**, which means no touch access, no keyboard access, and UA-controlled presentation.
+- **`title` repeats the name** on the root in both cases; some readers announce it as well as the `alt` or `aria-label`.
+- **The avatar is decorative in many contexts and nothing says so.** An Avatar next to a name that is already visible should be `aria-hidden`; there is no `@decorative` arg, so it announces redundantly in exactly the layout where it is most common (**EntityDisplay**, **Feed** rows, comment lists).
+- **Contrast**: initials are `--foreground` on a **16%** hue fill over `--card`, so the text is the theme's own foreground on a surface that stays close to `--card`, rather than a hue on its own tint. At the default 24px the type is ~10px, weight 600, mono, which is small, so check the five chart hues per theme.
+
+## Theming
+
+`--pretui-chip-hue` (set per instance from the name hash, and read once into a private `--_avatar-hue` — note it reuses **Chip**'s property name, so an ancestor setting `--pretui-chip-hue` for a chip will _not_ affect an Avatar, because the inline style wins), `--pretui-avatar-size` (the diameter; inline only when `@size` is given, otherwise from the cascade; the `1.5rem` default is declared once, as a private `--_avatar-size` that width, height and the font size all read), `--card` (mix base and the group ring), `--foreground` (the initials, and the ring around a photo), `--border` (mixed into the hairline), `--primary` (the fallback hue when the name is empty), `--font-mono`.
+
+The 16% / 28% mix ratios are fixed — unlike **Chip**, whose ratios are tokenized — so a theme cannot make avatars more or less saturated. A theme or a card can set a default size through `--pretui-avatar-size`; `@size` wins over it. As with **StatusChip**, the palette that matters is `--chart-1` … `--chart-5`, and they must work as a mutually distinguishable set at 16% tint behind small mono type.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Compose **Badge** / **Indicator** for unread/online. Accept `src` /
+`alt` / `fallback` / `name` (initials). **AvatarGroup** is the stack.

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

@@ -0,0 +1,101 @@
+// Pretui — Avatar usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Avatar } from './avatar';
+import { AvatarGroup } from './avatar-group';
+import { HUE_OPTIONS } from '../demo-ink-feedback';
+
+// ── Avatar ← avatar/usage.gts ────────────────────────────────────────────
+// Dropped knobs: userId (Pretui hue + initials derive from @name alone),
+// isReady (no async readiness gate — Avatar renders immediately).
+class AvatarUsage extends GlimmerComponent {
+  @tracked name = 'John Doe';
+  @tracked src = '';
+  @tracked hue = '';
+  @tracked size = 40;
+  setName = (v: string) => (this.name = v);
+  setSrc = (v: string) => (this.src = v);
+  setHue = (v: string) => (this.hue = v);
+  setSize = (v: number | null) => {
+    if (v !== null) {
+      this.size = v;
+    }
+  };
+  get srcVal() {
+    return this.src || undefined;
+  }
+  get hueVal() {
+    return this.hue || undefined;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Avatar'
+      @description="An avatar component that displays a user's initials on a colored background."
+    >
+      <:example>
+        <Avatar
+          @name={{this.name}}
+          @src={{this.srcVal}}
+          @hue={{this.hueVal}}
+          @size={{this.size}}
+        />
+        <AvatarGroup>
+          <Avatar @name='John Doe' @size={{28}} />
+          <Avatar @name='Ada Lovelace' @size={{28}} />
+          <Avatar @name='Grace Hopper' @size={{28}} />
+          <Avatar @name='Alan Turing' @size={{28}} />
+        </AvatarGroup>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='name'
+          @required={{true}}
+          @description='User display name — drives the initials and the name-derived hue.'
+          @value={{this.name}}
+          @onInput={{this.setName}}
+        />
+        <Args.String
+          @name='src'
+          @description='URL of the user thumbnail'
+          @value={{this.src}}
+          @onInput={{this.setSrc}}
+        />
+        <Args.String
+          @name='hue'
+          @description='Override the name-derived hue; sets --pretui-chip-hue, and stays set when the caller also passes a style attribute (Pretui addition).'
+          @options={{HUE_OPTIONS}}
+          @value={{this.hue}}
+          @onInput={{this.setHue}}
+        />
+        <Args.Number
+          @name='size'
+          @description='Avatar diameter in px at a 16px root, written as rem; sets the width, height and font size, and stays set when the caller also passes a style attribute (Pretui addition).'
+          @defaultValue={{24}}
+          @value={{this.size}}
+          @min={{16}}
+          @max={{96}}
+          @step={{4}}
+          @onInput={{this.setSize}}
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-avatar-size'
+          @type='dimension'
+          @description='Diameter for an Avatar with no @size; the font size is 0.42 of it. Give it a rem, px or container-query length: em and % do not keep that ratio. Set on the Avatar or any ancestor, through a class or a container query; @size wins over it.'
+          @defaultValue='1.5rem'
+        />
+        <Css.Basic
+          @name='pretui-chip-hue'
+          @type='color'
+          @description='Color the fill and hairline are mixed from. Set per instance to one of --chart-1 to --chart-5 from the name hash, or through @hue; a value in the caller style wins over the name hash. Falls back to --primary when @hue is rejected.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_AVATAR: Record<string, unknown> = {
+  Avatar: AvatarUsage,
+};

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

@@ -0,0 +1,179 @@
+// Pretui — Backdrop: a scrim, frost or clear layer that separates content from what is behind it.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { clampNum, styleFrom } from '../internal/texture';
+
+// ── Backdrop ─────────────────────────────────────────────────────────────
+
+/** Scrim treatment. `clear` is an invisible click-catcher. */
+export type BackdropTone = 'scrim' | 'frost' | 'clear';
+
+export interface BackdropSignature {
+  Args: {
+    /** Render the scrim. Defaults to true so `<Backdrop />` just works; bind it to keep the entry transition. */
+    open?: boolean;
+    /** `scrim` (tinted), `frost` (tinted + backdrop blur), `clear` (invisible click-catcher). */
+    tone?: BackdropTone;
+    /** Backdrop blur radius in px (0–40). Any tone may set it; `frost` defaults to 8 and keeps its saturation lift when you override the radius. Only a value above 0 turns the filter on — the heaviest thing in this file, a full-surface filter pass on every paint. */
+    blur?: number;
+    /** `fixed` covers the viewport (modal surfaces); `absolute` covers the nearest positioned ancestor (a panel-local scrim). */
+    position?: 'fixed' | 'absolute';
+    /** Dismiss handler. When present the scrim renders as a real `<button>` (click, Enter/Space, Escape); when absent it is an inert `aria-hidden` div. */
+    onDismiss?: () => void;
+    /** Accessible name for the dismiss button. Defaults to "Close". */
+    label?: string;
+    /** Put the dismiss button in the tab order. Off by default — the owning surface owns Escape, and a full-viewport tab stop is noise. */
+    focusable?: boolean;
+    /** Stacking level. Also settable as `--pretui-backdrop-z`. */
+    z?: number;
+  };
+  Blocks: {};
+  Element: HTMLElement;
+}
+
+/**
+ * The scrim/underlay behind a layered surface — dialogs, drawers, sheets,
+ * popovers, media lightboxes.
+ *
+ * Nearest inspirations: motion-primitives' GlowEffect/ProgressiveBlur and
+ * cult-ui's distorted-glass, plus the ad-hoc `<div className="fixed inset-0
+ * bg-black/50" onClick={close} />` that every React overlay tutorial ships.
+ * Better here: the dismiss target is a REAL `<button>` (that pattern's
+ * clickable div has no keyboard path and no accessible name — Enter/Space
+ * and Escape both work here, and `@label` is required in spirit and defaulted
+ * in practice); the tint is one token (`--pretui-overlay-scrim`, the same one
+ * `Dialog`/`Drawer` already paint on `::backdrop`) rather than an opacity
+ * literal; the entry fade is `@starting-style`, so there is no JS mount
+ * transition and reduced motion simply gets the end state.
+ *
+ * Deliberately yields NOTHING: a backdrop that renders children would either
+ * nest interactive content inside a `<button>` (an a11y violation) or force a
+ * second wrapper. The layered surface is a SIBLING of the backdrop, above it
+ * in the stacking order. Documented rather than hidden (Law 7).
+ */
+export class Backdrop extends Component<BackdropSignature> {
+  get open(): boolean {
+    return this.args.open ?? true;
+  }
+  get tone(): BackdropTone {
+    return this.args.tone ?? 'scrim';
+  }
+  get label(): string {
+    return this.args.label ?? 'Close';
+  }
+  // Only a POSITIVE blur opts into the filter. `@blur={{0}}` must not paint a
+  // `backdrop-filter: blur(0px)` — a no-op filter still promotes the scrim to
+  // its own compositing layer and makes it a containing block for fixed
+  // descendants, which is exactly the surprise a full-viewport element should
+  // not spring on the surface above it.
+  get hasBlur(): boolean {
+    let blur = clampNum(this.args.blur, 0, 40);
+    return blur !== undefined && blur > 0;
+  }
+  get style() {
+    let parts: string[] = [];
+    let blur = clampNum(this.args.blur, 0, 40);
+    if (blur !== undefined) parts.push(`--pretui-backdrop-blur: ${blur}px`);
+    let z = clampNum(this.args.z, 0, 2147483000);
+    if (z !== undefined) parts.push(`--pretui-backdrop-z: ${z}`);
+    return styleFrom(parts);
+  }
+  dismiss = () => {
+    this.args.onDismiss?.();
+  };
+  onKeyDown = (e: Event) => {
+    if ((e as KeyboardEvent).key === 'Escape') {
+      e.stopPropagation();
+      this.args.onDismiss?.();
+    }
+  };
+  <template>
+    {{#if this.open}}
+      {{#if @onDismiss}}
+        <button
+          type='button'
+          class='pretui-backdrop'
+          data-tone={{this.tone}}
+          data-position={{if @position @position 'fixed'}}
+          data-blur={{if this.hasBlur 'true' 'false'}}
+          style={{this.style}}
+          aria-label={{this.label}}
+          tabindex={{if @focusable '0' '-1'}}
+          data-test-pretui-backdrop
+          {{on 'click' this.dismiss}}
+          {{on 'keydown' this.onKeyDown}}
+          ...attributes
+        ></button>
+      {{else}}
+        <div
+          class='pretui-backdrop'
+          data-tone={{this.tone}}
+          data-position={{if @position @position 'fixed'}}
+          data-blur={{if this.hasBlur 'true' 'false'}}
+          style={{this.style}}
+          aria-hidden='true'
+          data-test-pretui-backdrop
+          ...attributes
+        ></div>
+      {{/if}}
+    {{/if}}
+    <style scoped>
+      @layer PretComponent {
+        .pretui-backdrop {
+          /* a scrim must escape scroll clipping when it is covering the
+             viewport (lint warns on fixed; accepted, same as overlay.gts) */
+          position: fixed;
+          inset: 0;
+          z-index: var(--pretui-backdrop-z, 50);
+          display: block;
+          margin: 0;
+          padding: 0;
+          border: 0;
+          cursor: var(--pretui-backdrop-cursor, default);
+          background: var(
+            --pretui-backdrop-tint,
+            var(--pretui-overlay-scrim, rgb(16 24 40 / 0.4))
+          );
+          opacity: 1;
+          transition: opacity 180ms cubic-bezier(0.23, 1, 0.32, 1);
+        }
+        .pretui-backdrop[data-position='absolute'] {
+          position: absolute;
+        }
+        .pretui-backdrop[data-tone='frost'] {
+          background: var(
+            --pretui-backdrop-tint,
+            color-mix(in oklch, var(--background) 55%, transparent)
+          );
+          backdrop-filter: blur(var(--pretui-backdrop-blur, 8px))
+            saturate(var(--pretui-backdrop-saturate, 1.3));
+        }
+        .pretui-backdrop[data-tone='clear'] {
+          background: transparent;
+        }
+        /* An explicit @blur opts a NON-frost tone into the filter (frost already
+           reads the same custom property, and excluding it here is what keeps
+           `@tone='frost' @blur={{16}}` from quietly losing frost's saturation
+           lift — same specificity, and this rule comes later). */
+        .pretui-backdrop[data-blur='true']:not([data-tone='frost']) {
+          backdrop-filter: blur(var(--pretui-backdrop-blur, 0px))
+            saturate(var(--pretui-backdrop-saturate, 1));
+        }
+        .pretui-backdrop:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: -3px;
+        }
+        @starting-style {
+          .pretui-backdrop {
+            opacity: 0;
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-backdrop {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,56 @@
+## What it is
+
+The scrim behind a layered surface — a dialog, drawer, sheet, popover or media lightbox — with a dismiss target. Use it when you are building a layered surface that does **not** ride the native top layer. **Dialog** and **Drawer** already get a `::backdrop` from `showModal()` and do not need this; **Popover** and **Menu** already own a transparent close target. Reach for Backdrop when composing something new.
+
+## The contract
+
+```
+@open? (default true), @tone? ('scrim'), @label? ('Close')
+@blur?, @focusable?, @z?
+Blocks: {}   — none
+Element: HTMLElement
+```
+
+**It yields nothing, deliberately.** A backdrop that rendered children would either nest interactive content inside a `<button>` — an accessibility violation — or force a second wrapper. **The layered surface is a _sibling_ of the backdrop, above it in the stacking order.** Documented rather than hidden (Law 7), and it is the first thing to know before reaching for this.
+
+**`@blur={{0}}` does not paint a filter.** Only a positive blur opts in, because a no-op `backdrop-filter: blur(0px)` still promotes the scrim to its own compositing layer _and_ makes it a containing block for fixed-position descendants — which would break every overlay positioned above it. That is a real, non-obvious bug avoided by a guard.
+
+`@z` is also settable as `--pretui-backdrop-z`.
+
+## Prior art
+
+The honest comparison set is **the ad-hoc `<div className="fixed inset-0 bg-black/50" onClick={close} />` that every React overlay tutorial ships**, plus motion-primitives' `GlowEffect`/`ProgressiveBlur` and cult-ui's `distorted-glass` for the visual treatments.
+
+Three concrete improvements over that ubiquitous div:
+
+- **The dismiss target is a real `<button>`.** The tutorial pattern's clickable div has **no keyboard path and no accessible name**. Here Enter and Space work, Escape works, and `@label` is required in spirit and defaulted in practice.
+- **The tint is one token** — `--pretui-overlay-scrim`, the same one **Dialog** and **Drawer** already paint on `::backdrop` — rather than an opacity literal. So every scrim in the product is the same scrim, whether it comes from the platform or from this component.
+- **The entry fade is `@starting-style`**, so there is no JS mount transition and reduced motion simply gets the end state.
+
+Where it is thinner than the motion-primitives treatments: no gradient, no progressive blur, no glow. `@tone` and `@blur` are the whole visual surface.
+
+## Accessibility
+
+No pattern of its own; it is a dismiss affordance under a surface that has its own pattern.
+
+What is right:
+
+- **A real `<button>` with an accessible name**, so the dismiss is keyboard-operable — which is the whole reason this exists rather than a styled div.
+- **Escape works**, not only click.
+- `@focusable` lets a caller decide whether the backdrop joins the tab order at all. Note that **Popover** and **Menu** in this kit both use `tabindex="-1"` on their equivalents, on the reasoning that the panel's own close control is the keyboard route and a full-viewport button in the tab sequence is noise. Both positions are defensible; know which you are choosing.
+
+Gaps and cautions:
+
+- **A backdrop alone does not make a surface modal.** The layered surface above it is a sibling, so nothing is `inert`, nothing is `aria-hidden`, focus is not trapped, and background scroll is not locked. If you are building a modal, **use `Dialog`** — it gets all four from `showModal()` for free. If you are building something the platform cannot express, you must add the inertness yourself; this component will not tell you that you forgot.
+- **`@label` defaults to `'Close'`**, so two backdrops on a page announce identically — and a backdrop is exactly the control a screen-reader user encounters without context.
+- **The backdrop is announced as a button in reading order**, before or after the surface depending on DOM order. Put it before.
+- **Blur is a visual effect with no semantic counterpart**, and a heavy blur over live content can reduce the contrast of anything showing through — which matters if the backdrop is decorative rather than opaque.
+- No `prefers-reduced-transparency` handling for the blur.
+
+## Theming
+
+`--pretui-overlay-scrim` (the tint — shared with **Dialog**'s and **Drawer**'s `::backdrop`, so a theme defines it once), `--pretui-backdrop-z` (stacking level), plus the `@blur` radius as an arg.
+
+`--pretui-overlay-scrim` is the token themes most often get wrong: it must read as a scrim in **both** light and dark, not simply invert. A dark-mode scrim that is pure black at the same alpha as the light one produces an overlay you cannot see through and a surface with no apparent elevation.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,223 @@
+// Pretui — Backdrop usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Backdrop } from './backdrop';
+import type { BackdropTone } from './backdrop';
+import { Button } from './button';
+
+// ── Backdrop ─────────────────────────────────────────────────────────────
+const TONE_OPTIONS: BackdropTone[] = ['scrim', 'frost', 'clear'];
+
+const POSITION_OPTIONS = ['absolute', 'fixed'];
+
+class BackdropUsage extends Component {
+  @tracked open = true;
+  @tracked tone: BackdropTone = 'frost';
+  @tracked blur = 8;
+  @tracked position: 'fixed' | 'absolute' = 'absolute';
+  @tracked label = 'Close the consignment sheet';
+  @tracked focusable = true;
+  @tracked dismissible = true;
+
+  setTone = (v: string) => (this.tone = v as BackdropTone);
+  setBlur = (v: number | null) => (this.blur = v ?? 0);
+  setPosition = (v: string) => (this.position = v as 'fixed' | 'absolute');
+  setLabel = (v: string) => (this.label = v);
+  setFocusable = (v: boolean) => (this.focusable = v);
+  setDismissible = (v: boolean) => (this.dismissible = v);
+  setOpen = (v: boolean) => (this.open = v);
+  dismiss = () => (this.open = false);
+  reopen = () => (this.open = true);
+
+  get toneOptions() {
+    return TONE_OPTIONS;
+  }
+  get positionOptions() {
+    return POSITION_OPTIONS;
+  }
+  get usage() {
+    let bits = [`@open={{this.open}}`, `@tone='${this.tone}'`];
+    if (this.blur !== 8 || this.tone !== 'frost') {
+      bits.push(`@blur={{${this.blur}}}`);
+    }
+    bits.push(`@position='${this.position}'`);
+    if (this.dismissible) {
+      bits.push('@onDismiss={{this.close}}');
+      bits.push(`@label='${this.label}'`);
+      if (this.focusable) bits.push('@focusable={{true}}');
+    }
+    return `<Backdrop ${bits.join(' ')} />\n{{! the layered surface is a SIBLING above it, never a child }}\n<Dialog @open={{this.open}} @onClose={{this.close}} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Backdrop'
+      @description="The scrim/underlay behind a layered surface — dialogs, drawers, sheets, popovers, media lightboxes. Reach for it whenever something floats above the page and the page beneath should read as inactive. Better than the click-catching div with an onClick that every React overlay tutorial ships: when you pass @onDismiss the scrim is a REAL button, so it has an accessible name and answers Enter/Space and Escape as well as click; without @onDismiss it is an inert aria-hidden div rather than a fake control. The tint is one token (--pretui-overlay-scrim — the same value Dialog and Drawer already paint on ::backdrop), so a themed scrim matches the native top-layer one exactly. The entry fade is @starting-style, so there is no JS mount transition and reduced motion simply gets the end state. It yields nothing on purpose: children would either nest interactive content inside a button or force a second wrapper, so the layered surface is a sibling above it, not a child. @tone='frost' is the expensive one — a full-surface backdrop-filter on every paint."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='bd-stage'>
+          <div class='bd-sheet'>
+            <h3 class='bd-title'>Consignment WY-4471</h3>
+            <p class='bd-line'>Silver Peak Trading · Wuyishan → Rotterdam</p>
+            <p class='bd-line'>48 crates · $102/kg · lands 2026-05-07</p>
+            <p class='bd-line'>The sheet keeps painting underneath — a frost
+              scrim blurs it, a clear one only catches the click.</p>
+          </div>
+
+          {{#if this.dismissible}}
+            <Backdrop
+              @open={{this.open}}
+              @tone={{this.tone}}
+              @blur={{this.blur}}
+              @position={{this.position}}
+              @onDismiss={{this.dismiss}}
+              @label={{this.label}}
+              @focusable={{this.focusable}}
+            />
+          {{else}}
+            <Backdrop
+              @open={{this.open}}
+              @tone={{this.tone}}
+              @blur={{this.blur}}
+              @position={{this.position}}
+            />
+          {{/if}}
+
+          <div class='bd-controls'>
+            {{#if this.open}}
+              <span class='bd-hint'>{{if
+                  this.dismissible
+                  'Click the scrim (or Tab to it and press Enter) to dismiss.'
+                  'Inert scrim — no dismiss handler, so nothing to click.'
+                }}</span>
+            {{else}}
+              <Button @tone='primary' {{on 'click' this.reopen}}>Raise the
+                scrim</Button>
+            {{/if}}
+          </div>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Bool
+          @name='open'
+          @value={{this.open}}
+          @onInput={{this.setOpen}}
+          @defaultValue={{true}}
+          @description='Render the scrim. Defaults to true so <Backdrop /> just works; bind it to a real state to keep the @starting-style entry fade.'
+        />
+        <Args.String
+          @name='tone'
+          @options={{this.toneOptions}}
+          @value={{this.tone}}
+          @onInput={{this.setTone}}
+          @defaultValue='scrim'
+          @description='scrim = tinted; frost = tinted plus a backdrop blur and a saturation lift; clear = invisible, purely a click-catcher (the Popover/Select dismissal pattern).'
+        />
+        <Args.Number
+          @name='blur'
+          @min={{0}}
+          @max={{40}}
+          @step={{1}}
+          @value={{this.blur}}
+          @onInput={{this.setBlur}}
+          @defaultValue={{0}}
+          @description='Backdrop blur radius in px (clamped 0–40). Any tone may set it; frost defaults to 8 and keeps its saturation lift when you override the radius. Only a value above 0 turns the filter on — a blur(0px) would still promote the scrim to its own compositing layer and make it a containing block for fixed descendants.'
+        />
+        <Args.String
+          @name='position'
+          @options={{this.positionOptions}}
+          @value={{this.position}}
+          @onInput={{this.setPosition}}
+          @defaultValue='fixed'
+          @description='fixed covers the viewport (the modal case, and the component default). absolute covers the nearest positioned ancestor — a panel-local scrim, which is what this demo uses so the workbench stays visible. Switching this to fixed here will cover the whole workbench; the scrim is still dismissable.'
+        />
+        <Args.Action
+          @name='onDismiss'
+          @description='Dismiss handler. Its presence is the switch between the two renderings: with it the scrim is a real <button> (click, Enter/Space, Escape); without it an inert aria-hidden <div> that swallows nothing. Toggle the row below to see both.'
+          @hideControls={{true}}
+        />
+        <Args.Bool
+          @name='(demo) pass @onDismiss'
+          @value={{this.dismissible}}
+          @onInput={{this.setDismissible}}
+          @defaultValue={{true}}
+          @description='Demo-only switch — not a component arg. Flips between the button rendering and the inert-div rendering.'
+        />
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @onInput={{this.setLabel}}
+          @defaultValue='Close'
+          @description='Accessible name for the dismiss button. Only meaningful when @onDismiss is passed; the inert div is aria-hidden and needs none.'
+        />
+        <Args.Bool
+          @name='focusable'
+          @value={{this.focusable}}
+          @onInput={{this.setFocusable}}
+          @defaultValue={{false}}
+          @description='Put the dismiss button in the tab order. Off by default: the owning surface owns Escape, and a full-viewport tab stop is noise in a focus-trapped dialog. Turn it on when the backdrop is the only way out.'
+        />
+        <Args.Number
+          @name='z'
+          @description='Stacking level for the scrim. Also settable as the --pretui-backdrop-z custom property on any ancestor; defaults to 50, below Popup’s 60.'
+          @defaultValue={{50}}
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @description='Yields nothing, on purpose. Children would either nest interactive content inside a <button> (an a11y violation) or force a second wrapper — so the layered surface is a SIBLING of the backdrop, above it in the stacking order.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .bd-stage {
+        position: relative;
+        min-height: 220px;
+        padding: var(--space-5, 15px);
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        box-shadow: 0 0 0 1px var(--border);
+        overflow: hidden;
+      }
+      .bd-sheet {
+        display: grid;
+        gap: var(--space-2, 6px);
+      }
+      .bd-title {
+        margin: 0;
+        font-size: var(--text-heading, 19px);
+        font-weight: var(--weight-heading, 700);
+        letter-spacing: var(--track-heading, -0.02em);
+        color: var(--foreground);
+      }
+      .bd-line {
+        margin: 0;
+        max-width: 52ch;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+      /* above the scrim, so the demo is never a dead end */
+      .bd-controls {
+        position: absolute;
+        right: var(--space-5, 15px);
+        bottom: var(--space-5, 15px);
+        z-index: 51;
+      }
+      .bd-hint {
+        display: inline-block;
+        padding: var(--space-2, 6px) var(--space-3, 8px);
+        border-radius: var(--radius-chip, 6px);
+        background: var(--card);
+        box-shadow: 0 0 0 1px var(--border);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_BACKDROP: Record<string, unknown> = {
+  Backdrop: BackdropUsage,
+};