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

package/bundled-realms/pretui/components/emoji-picker.md

@@ -0,0 +1,53 @@
+## What it is
+
+A searchable emoji grid with skin-tone selection and a recently-used row.
+
+**EmojiButton** is this behind a trigger. Use the picker directly when it lives in a panel that is already open.
+
+## The contract
+
+```
+@onSelect?      — called with the chosen emoji. The only required arg in practice
+@skinTone?      — active skin tone 0-5. Controlled when supplied
+@onSkinTone?    — called when the tone changes; persist it to make the choice sticky
+@recent?        — recently-used emoji, MOST RECENT FIRST, as untoned unicode strings
+@onRecent?      — receives the new recent list after each pick. Persist it verbatim
+@recentLimit?   — how many recent emoji to keep. Default 18
+@columns?       — columns in the grid. Default 9
+@autofocus?     — focus the search field on insert. Default false
+@emojiVersion?  — pin the emoji version instead of detecting it
+@label?         — accessible name for the whole picker. Default 'Emoji picker'
+```
+
+**Recency is positional and carries no timestamp.** `Date.now()` is forbidden in realm code because it breaks indexing determinism — and a wall clock was never needed, because "most recent" is "index 0". The list is handed back whole for the caller to persist verbatim.
+
+**Version detection draws fourteen 1×1 canvases** to work out which emoji the platform can actually render. `@emojiVersion` pins it, which is worth doing when a caller has already measured, or to make a screenshot test deterministic across machines.
+
+**Skin tone is controlled when supplied**, and persisting it through `@onSkinTone` is what makes the choice sticky — a picker that forgets someone's tone on every open is a small, repeated insult.
+
+**`@autofocus` defaults to false.** A picker that steals focus on insert is wrong in a panel and right in a popover, so the decision belongs to whoever placed it.
+
+## Prior art
+
+The emoji-picker component every chat product ships.
+
+Where Pretui is better: recency without a clock, and version detection rather than assuming the platform's emoji font covers what the data claims — the failure being a grid of tofu boxes for anything newer than the OS.
+
+Where it is thinner: no custom or uploaded emoji, no per-server emoji sets, no frequently-used ranking (recency only), and no category jump list beyond the grid's own ordering.
+
+## Accessibility
+
+- **The picker is a named region**, defaulting to "Emoji picker".
+- **Search is the primary path**, and it is text — which makes the whole grid reachable by name rather than by hunting a visual grid.
+- **Every emoji has a name.** A grid of glyphs with no accessible names is unusable, and emoji names are the one case where the visual and the accessible representation genuinely differ.
+- **Skin tone is a real control**, not a long-press gesture, so it is reachable by keyboard.
+- **`@autofocus` moving focus into the search field is right in a popover and wrong in a panel** — placing focus without the reader asking is disorienting when the picker was already on screen.
+- **Version detection prevents the worst failure**: offering an emoji that renders as a tofu box conveys nothing to anyone and is undetectable to a screen-reader user, who will be told a name for a character that shows as a blank.
+
+## Theming
+
+`--pretui-palette-columns` governs the grid rhythm alongside the other palette surfaces in the kit; everything else — the search field, the tone control, the surface — comes from the shared control and overlay tokens.
+
+A picker that themed independently would be conspicuous, because it is usually the only dense grid on a screen otherwise made of rows and fields.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/emoji-picker.usage.gts

@@ -0,0 +1,235 @@
+// Pretui — EmojiPicker usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { EmojiPicker } from './emoji-picker';
+import type { EmojiSelection } from './emoji-picker';
+import { FreestyleUsage } from './freestyle-usage';
+
+// ── EmojiPicker ──────────────────────────────────────────────────────────
+
+class EmojiPickerUsage extends Component {
+  @tracked columns = 9;
+  @tracked recentLimit = 18;
+  @tracked autofocus = false;
+  @tracked label = 'Emoji picker';
+
+  @tracked skinTone = 0;
+  @tracked recent: readonly string[] = [];
+  @tracked picked: EmojiSelection | undefined;
+
+  setColumns = (v: number) => (this.columns = v);
+  setRecentLimit = (v: number) => (this.recentLimit = v);
+  setAutofocus = (v: boolean) => (this.autofocus = v);
+  setLabel = (v: string) => (this.label = v);
+
+  onSelect = (selection: EmojiSelection) => (this.picked = selection);
+  onSkinTone = (tone: number) => (this.skinTone = tone);
+  onRecent = (recent: readonly string[]) => (this.recent = recent);
+
+  get recentReadout(): string {
+    return this.recent.length ? this.recent.join('  ') : '(nothing picked yet)';
+  }
+
+  get pickedReadout(): string {
+    if (!this.picked) {
+      return '(nothing picked yet)';
+    }
+    return this.picked.unicode + '  ' + this.picked.annotation;
+  }
+
+  get usage(): string {
+    let bits = ['@onSelect={{this.insert}}'];
+    if (this.columns !== 9) {
+      bits.push('@columns=' + String(this.columns));
+    }
+    if (this.recentLimit !== 18) {
+      bits.push('@recentLimit=' + String(this.recentLimit));
+    }
+    if (this.autofocus) {
+      bits.push('@autofocus=true');
+    }
+    return '<EmojiPicker ' + bits.join(' ') + ' />';
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='EmojiPicker'
+      @description='A searchable emoji picker with category tabs, skin-tone
+        selection, a recently-used list and a keyboard-complete grid. Search,
+        ranking and skin-tone handling are ported from emoji-picker-element
+        (Apache-2.0); the UI is Pretui, because that library delivers its
+        controls inside a shadow root with 27 custom properties and no slots —
+        no font, no shadow and a dark branch of its own. The 1,923-emoji
+        dataset is local and lazily imported, so the picker makes no network
+        request and works offline. Everything but the first Tab is arrow keys:
+        the grid is one tab stop with roving tabindex, arrows move in two
+        dimensions, Home and End go to the row ends, Ctrl with them goes to
+        the ends of the whole category, PageUp and PageDown move five rows,
+        and ArrowUp out of the top row returns to the search field.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='emoji-stage'>
+          <EmojiPicker
+            @onSelect={{this.onSelect}}
+            @columns={{this.columns}}
+            @recentLimit={{this.recentLimit}}
+            @autofocus={{this.autofocus}}
+            @label={{this.label}}
+            @skinTone={{this.skinTone}}
+            @onSkinTone={{this.onSkinTone}}
+            @recent={{this.recent}}
+            @onRecent={{this.onRecent}}
+          />
+          <dl class='emoji-readout'>
+            <dt>Last pick</dt>
+            <dd>{{this.pickedReadout}}</dd>
+            <dt>Recent, most recent first</dt>
+            <dd class='emoji-mono'>{{this.recentReadout}}</dd>
+            <dt>Skin tone</dt>
+            <dd class='emoji-mono'>{{this.skinTone}}</dd>
+          </dl>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='columns'
+          @defaultValue={{9}}
+          @value={{this.columns}}
+          @description='Columns in the grid, clamped to 4-16. Drives the
+            arrow-key geometry as well as the layout, so ArrowDown always
+            means "one row down" whatever the caller picks.'
+          @onInput={{this.setColumns}}
+        />
+        <Args.Number
+          @name='recentLimit'
+          @defaultValue={{18}}
+          @value={{this.recentLimit}}
+          @description='How many recently-used emoji to keep, 0-64. Set 0 to
+            drop the recents tab entirely.'
+          @onInput={{this.setRecentLimit}}
+        />
+        <Args.Bool
+          @name='autofocus'
+          @defaultValue={{false}}
+          @value={{this.autofocus}}
+          @description='Focus the search field on insert. Off by default —
+            a picker rendered inline must not steal focus; EmojiButton turns
+            it on because a popover that opens should be typed into.'
+          @onInput={{this.setAutofocus}}
+        />
+        <Args.String
+          @name='label'
+          @defaultValue='Emoji picker'
+          @value={{this.label}}
+          @description='Accessible name for the whole picker.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.Number
+          @name='skinTone'
+          @description='Active skin tone 0-5. Controlled when supplied — pair
+            it with @onSkinTone and persist the value to make the choice
+            sticky across sessions.'
+        />
+        <Args.Action
+          @name='onSkinTone'
+          @description='Receives the new tone as a number 0-5.'
+        />
+        <Args.Array
+          @name='recent'
+          @description='Recently-used emoji, MOST RECENT FIRST, as untoned
+            unicode strings. Ordering is positional and carries no timestamp:
+            Date.now() is forbidden in realm code, and "most recent" is
+            "index 0". Controlled when supplied; otherwise the picker keeps a
+            session-local list.'
+        />
+        <Args.Action
+          @name='onRecent'
+          @description='Receives the new recent array after every pick.
+            Persist it verbatim — it is already the storage format.'
+        />
+        <Args.Number
+          @name='emojiVersion'
+          @description='Pin the emoji version instead of detecting it.
+            Detection draws fourteen 1x1 canvases to find the newest version
+            the font can actually paint, and hides anything newer so you get
+            no tofu. Pin it to make a screenshot test deterministic.'
+        />
+        <Args.Action
+          @name='onSelect'
+          @description='Receives { unicode, annotation, base, skinTone }.
+            `unicode` has the tone applied and is what you insert; `base` is
+            the untoned identity used by the recent list; `annotation` is the
+            CLDR name and is safe to use as alt text.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-emoji-width'
+          @type='dimension'
+          @description='Max width of the picker. Default 22rem.'
+        />
+        <Css.Basic
+          @name='pretui-emoji-height'
+          @type='dimension'
+          @description='Height of the scrolling grid. Default 15rem.'
+        />
+        <Css.Basic
+          @name='pretui-emoji-cell'
+          @type='dimension'
+          @description='Cell size. Default 2rem, and 2.75rem on coarse
+            pointers so touch targets clear 44px.'
+        />
+        <Css.Basic
+          @name='pretui-emoji-glyph'
+          @type='dimension'
+          @description='Emoji font size inside a cell. Default 1.25rem.'
+        />
+        <Css.Basic
+          @name='pretui-emoji-font'
+          @type='string'
+          @description='Colour-emoji font stack. Twemoji Mozilla is listed
+            first on purpose: Firefox bundles it on Windows and Linux and
+            updates faster than the OS, so leaving it later mixes glyph
+            generations within one grid.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+
+    <style scoped>
+      .emoji-stage {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: flex-start;
+        gap: 20px;
+      }
+
+      .emoji-readout {
+        display: grid;
+        grid-template-columns: max-content;
+        gap: 2px 0;
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+      }
+
+      .emoji-readout dt {
+        color: var(--muted-foreground);
+        text-transform: uppercase;
+        letter-spacing: 0.06em;
+      }
+
+      .emoji-readout dd {
+        margin: 0 0 10px;
+        color: var(--foreground);
+      }
+
+      .emoji-mono {
+        font-family: var(--font-mono);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_EMOJI_PICKER: Record<string, unknown> = {
+  EmojiPicker: EmojiPickerUsage,
+};

package/bundled-realms/pretui/components/empty-state.gts

@@ -0,0 +1,162 @@
+// Pretui — EmptyState: the kit's zero-data surface, with one or two honest
+// ways forward and the texture that marks it as intentional.
+import Component from '@glimmer/component';
+import { resolveSize, type PretuiSizeArg } from '../pretui-primitives';
+
+/** The two steps an EmptyState paints: 's' is the compact well, 'm' the page-section default. */
+export type EmptyStateSize = 's' | 'm';
+const EMPTY_STATE_SIZES: Record<string, EmptyStateSize> = {
+  xs: 's',
+  s: 's',
+  m: 'm',
+  l: 'm',
+  xl: 'm',
+};
+
+export interface EmptyStateSignature {
+  Args: {
+    title: string;
+    message?: string;
+    texture?: boolean;
+    /** wording of the separator between the two paths (default 'or') */
+    separator?: string;
+    /** 's' is the compact well for an empty note inside a card section; 'm' (default) sizes for a page section */
+    size?: PretuiSizeArg;
+  };
+  Blocks: {
+    /** The message with markup in it (a Token, a link, emphasis); wins over @message when both are given. */
+    default: [];
+    action: [];
+    /**
+     * The SECOND way in. An empty state usually has two honest answers —
+     * "choose an existing one" / "paste a URL", "import" / "start blank",
+     * "connect an account" / "upload a CSV" — and burying one of them makes
+     * the reader guess which is the real path. Both get equal billing with a
+     * separator between, folding to a stack at narrow container widths.
+     */
+    altAction: [];
+  };
+  Element: HTMLDivElement;
+}
+
+// The one place texture lives (Law 6).
+export class EmptyState extends Component<EmptyStateSignature> {
+  get showTexture() {
+    return this.args.texture ?? true;
+  }
+  get separator() {
+    return this.args.separator ?? 'or';
+  }
+  // data-size is always set, 'm' included, as on every sized component in the kit.
+  get size(): EmptyStateSize {
+    return EMPTY_STATE_SIZES[resolveSize(this.args.size)] ?? 'm';
+  }
+  <template>
+    <div
+      class='pretui-empty'
+      data-size={{this.size}}
+      data-test-pretui-empty
+      ...attributes
+    >
+      {{#if this.showTexture}}<div class='pretui-empty-texture'></div>{{/if}}
+      <div class='pretui-empty-title'>{{@title}}</div>
+      {{#if (has-block)}}
+        {{! A div, not a p: the caller's markup may contain block elements. }}
+        <div class='pretui-empty-msg'>{{yield}}</div>
+      {{else if @message}}
+        <p class='pretui-empty-msg'>{{@message}}</p>
+      {{/if}}
+      {{#if (has-block 'altAction')}}
+        <div class='pretui-empty-paths'>
+          <div class='pretui-empty-action'>{{yield to='action'}}</div>
+          <div class='pretui-empty-sep' aria-hidden='true'>{{this.separator}}</div>
+          <div class='pretui-empty-action'>{{yield to='altAction'}}</div>
+        </div>
+      {{else if (has-block 'action')}}
+        <div class='pretui-empty-action'>{{yield to='action'}}</div>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-empty {
+          display: grid;
+          place-items: center;
+          text-align: center;
+          gap: var(--boxel-sp-xs);
+          padding: var(--boxel-sp-3xl) var(--boxel-sp-lg);
+          position: relative;
+          overflow: hidden;
+          border-radius: var(--radius);
+          background-color: var(--canvas);
+          color: var(--foreground);
+        }
+        /* compact: the well an empty note sits in inside a card section */
+        .pretui-empty[data-size='s'] {
+          padding: var(--boxel-sp);
+        }
+        .pretui-empty-texture {
+          position: absolute;
+          inset: 0;
+          pointer-events: none;
+          background: radial-gradient(
+            ellipse 60% 45% at 50% 42%,
+            color-mix(in oklch, var(--primary) 8%, transparent),
+            transparent 70%
+          );
+        }
+        .pretui-empty-title {
+          position: relative;
+          font-family: var(--font-serif);
+          font-size: var(--boxel-heading-font-size);
+          font-weight: var(--boxel-heading-font-weight);
+        }
+        .pretui-empty[data-size='s'] .pretui-empty-title {
+          font-size: var(--boxel-font-size);
+        }
+        .pretui-empty-msg {
+          position: relative;
+          margin: 0;
+          font-size: var(--boxel-font-size-xs);
+          max-width: 34ch;
+        }
+        .pretui-empty-action {
+          position: relative;
+          margin-top: var(--boxel-sp-2xs);
+        }
+        /* Two equal paths with a rule between. The rule is drawn on the
+           separator itself so it stretches to whatever the row/column is —
+           no measurement, and it flips axis with the fold. */
+        /* flex-wrap rather than a container query: EmptyState is often an auto
+           -sized grid/flex item, and `container-type: inline-size` would apply
+           inline-size containment to it and collapse that case. Wrapping folds
+           the two paths into a stack at exactly the width where they stop
+           fitting, with no containment side effect. */
+        .pretui-empty-paths {
+          position: relative;
+          display: flex;
+          flex-wrap: wrap;
+          align-items: center;
+          justify-content: center;
+          gap: var(--boxel-sp-sm);
+        }
+        .pretui-empty-sep {
+          display: flex;
+          align-items: center;
+          flex: 1 1 6rem;
+          gap: var(--boxel-sp-xs);
+          margin-top: var(--boxel-sp-2xs);
+          font-size: var(--boxel-font-size-2xs);
+          text-transform: lowercase;
+        }
+        .pretui-empty-sep::before,
+        .pretui-empty-sep::after {
+          content: '';
+          flex: 1;
+          min-inline-size: var(--boxel-sp-sm);
+          block-size: 1px;
+          background-color: var(--border);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/empty-state.md

@@ -0,0 +1,63 @@
+## What it is
+
+What a region shows when it has nothing to show: a title, an optional message, and an optional action. Reach for it in place of a blank area whenever a list, table, search result or panel body is legitimately empty. If the region is _loading_ rather than empty, use **Skeleton** or **LoadingState** — an empty state shown during a fetch is a lie. If the emptiness is an error, use **Alert**. If a single reference is missing, **BrokenLink**.
+
+## The contract
+
+```
+@title: string   (required)
+@message?, @texture? (default true), @separator? (default 'or'), @size? (default 'm')
+<:default>   — the message with markup in it; wins over @message
+<:action>  <:altAction>
+Element: HTMLDivElement
+```
+
+**`@title` is required and `@message` is not.** That ordering is the opinion: an empty state must always name what is absent, and may explain. A component that let you render a lone paragraph would produce the vague "Nothing here yet" that empty states are notorious for.
+
+**This is the one place texture lives.** The kit's Law 6 says decoration is confined, and an EmptyState is where it is allowed: a radial gradient at 8% `--primary` centred slightly above the middle. `@texture={{false}}` turns it off for dense contexts. Everything else in the kit is flat, and that is what makes this read as a deliberate pause rather than as ornament.
+
+**The message takes markup through `<:default>`.** `@message` is plain text. When the message needs a **Token**, a link or emphasis, pass the message as the block; it renders in the same place with the same type, colour and measure. The `@message` arg renders in a `<p>`; the block renders in a `<div>`, because the caller's markup may contain block elements. A block wins over its arg, as on **Notification**, **AlertDialog** and **Card**: if both are given, the block renders and `@message` does not.
+
+**`@size`** takes the house scale (`xs | s | m | l | xl` and the `sm` / `md` / `lg` / `small` / `medium` / `large` / `default` aliases) and paints two steps. `s` is the compact well for an empty note inside a card section: `--boxel-sp` padding on every side and the title at `--boxel-font-size`. `m`, the default, is sized for a page section. `xs` lands on `s`, and `l` / `xl` on `m`. The resolved step lands as `data-size`, `'s'` or `'m'`, on every render, the default included.
+
+`max-width: 34ch` on the message is the measure at which a centred paragraph stays scannable — wider and the eye loses the line, and centred text is much less forgiving of long measures than left-aligned.
+
+The title is set in `--font-serif`. That is the only serif in the control and structure territories, and it is the signal that this is a moment of address rather than a label.
+
+## Prior art
+
+**React Spectrum `IllustratedMessage`** is the closest match — an illustration slot, `Heading`, `Content`, and it is what Spectrum's tables render via `renderEmptyState`. **shadcn** ships no empty state; it is a documentation recipe. **Web Awesome** has none. **SLDS** has an `illustration` blueprint with a fixed set of SVGs.
+
+Pretui differs on the illustration question, and it is the interesting one: Spectrum and SLDS both centre the pattern on an **illustration**, which means every product must commission or choose art, and most ship the same three stock SVGs everywhere. Pretui substitutes a **generated texture** — a tinted radial that picks up the theme's `--primary` — so an empty state looks intentional and on-brand with zero assets. That is a genuinely better default for a system where cards are authored quickly.
+
+The other improvement: **`@title` being required**. Spectrum's `Heading` is optional.
+
+Where it is behind: no illustration slot and no `<:icon>`, and only two sizes (a compact well and the page-section default) where Spectrum's `IllustratedMessage` scales its illustration and heading together.
+
+## Accessibility
+
+No APG pattern. Relevant criteria: WCAG **1.3.1**, **2.4.6 Headings and Labels**, and the live-region rules if the state appears dynamically.
+
+Gaps, and the first two are the real ones:
+
+- **The title is a `<div>`, not a heading.** `.pretui-empty-title` is styled to look like one (serif, `--text-heading`) but carries no `<h*>` and no `role="heading"`, so it does not appear in a screen reader's heading list and does not structure the region. Given that **Panel** and **Toolbar** in this same territory hard-code `<h2>`, the inconsistency is striking — and the right answer for all three is the same authorable `@headingLevel` that **ErrorSummary** already has.
+- **Nothing announces the transition to empty.** When a filter reduces a table to nothing, the empty state replaces the rows silently. A `role="status"` on the container would announce "No matching records" — and would have to exist before the change to work, which is the usual live-region caveat. This is the single most useful addition.
+- **The texture layer has no `aria-hidden`**, though it is an empty `<div>` with no content, so nothing is announced — correct by accident rather than by declaration.
+- **The empty state does not replace a table's semantics.** If you render it _instead of_ a `<tbody>`, screen-reader users lose the table's structure and get a bare region. React Spectrum's `renderEmptyState` renders inside the grid for exactly this reason. Placement is the caller's responsibility here.
+- `@message` is limited to `34ch` and centred; long messages will be several short centred lines, which is harder to read for users with dyslexia (WCAG **1.4.8**, AAA).
+- The action in `<:action>` is an ordinary tab stop, which is right — an empty state should not trap or auto-focus.
+
+## Theming
+
+`--canvas` with its paired `--foreground` (the surface and the ink for the title, message and separator — note it is **not** `--card`, so an EmptyState reads as a recess inside a Panel rather than as another card), `--border` (the separator rules), `--primary` (the texture tint, at 8%), `--font-serif`, `--boxel-heading-font-size` and `--boxel-heading-font-weight` (title), `--boxel-font-size-xs` (message), `--boxel-font-size-2xs` (separator), `--radius`, and `--boxel-sp-2xs/xs/sm/lg/3xl` for the gaps and padding. At `@size='s'` the padding is `--boxel-sp` and the title reads `--boxel-font-size`, so `--boxel-sp-lg/3xl` padding and `--boxel-heading-font-size` no longer apply.
+
+The message and separator are set in `--foreground`, at the smaller size, because the contract guarantees `--muted-foreground` only on `--background`, `--card` and `--muted`, not on the neutral `--canvas`.
+
+The title uses the theme's `--font-serif` (IBM Plex Serif by default), which is used almost nowhere else in the kit, so it is the component's one moment of typographic voice. A theme must also keep `--canvas` distinguishable from `--card`, or the empty state stops reading as a recess and the whole effect flattens.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+shadcn/Ant `Empty` is this component under that name (**Empty**). Page-level 404/success
+is **Result**. A missing linked card is **BrokenLink**.

package/bundled-realms/pretui/components/empty-state.usage.gts

@@ -0,0 +1,113 @@
+// Pretui — EmptyState usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Token } from './token';
+import { EmptyState, type EmptyStateSize } from './empty-state';
+
+const SIZES: EmptyStateSize[] = ['m', 's'];
+
+class EmptyStateUsage extends Component {
+  @tracked title = 'No lots match';
+  @tracked message = '';
+  @tracked texture = true;
+  @tracked size: EmptyStateSize = 'm';
+  setTitle = (v: string) => (this.title = v);
+  setMessage = (v: string) => (this.message = v);
+  toggleTexture = (v: boolean) => (this.texture = v);
+  setSize = (v: string) => (this.size = v as EmptyStateSize);
+  get messageVal() {
+    return this.message || undefined;
+  }
+  get usage() {
+    let bits = [`@title='${this.title}'`];
+    if (this.messageVal) {
+      bits.push(`@message='${this.messageVal}'`);
+    }
+    if (this.size !== 'm') {
+      bits.push(`@size='${this.size}'`);
+    }
+    if (!this.texture) {
+      bits.push('@texture={{false}}');
+    }
+    let message = this.messageVal
+      ? ''
+      : '<:default>Try clearing the <Token …/> filters.</:default>';
+    return `<EmptyState ${bits.join(' ')}>${message}<:action>…</:action></EmptyState>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='EmptyState'
+      @description='A named absence with optional action. Texture is confined to this low-information surface and never competes with data.'
+      @source={{this.usage}}
+    >
+      <:example>
+        {{! A block wins over @message, so the block is passed only while the message knob is empty. }}
+        {{#if this.messageVal}}
+          <EmptyState
+            @title={{this.title}}
+            @message={{this.messageVal}}
+            @texture={{this.texture}}
+            @size={{this.size}}
+          >
+            <:action><Button @tone='neutral' @appearance='outlined'>Clear filters</Button></:action>
+          </EmptyState>
+        {{else}}
+          <EmptyState
+            @title={{this.title}}
+            @texture={{this.texture}}
+            @size={{this.size}}
+          >
+            <:default>Try clearing the
+              <Token @value='origin' />
+              and
+              <Token @value='harvest' />
+              filters.</:default>
+            <:action><Button @tone='neutral' @appearance='outlined'>Clear filters</Button></:action>
+          </EmptyState>
+        {{/if}}
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='title'
+          @value={{this.title}}
+          @onInput={{this.setTitle}}
+        />
+        <Args.String
+          @name='message'
+          @value={{this.message}}
+          @description='Plain-text message. The default block wins over it when both are given; this page passes the block only while the knob is empty.'
+          @onInput={{this.setMessage}}
+        />
+        <Args.Bool
+          @name='texture'
+          @value={{this.texture}}
+          @defaultValue={{true}}
+          @onInput={{this.toggleTexture}}
+        />
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{SIZES}}
+          @defaultValue='m'
+          @description="House scale. 's' is the compact well for an empty note inside a card section (--boxel-sp padding, the title at --boxel-font-size); 'm' sizes for a page section. xs lands on s, l and xl on m (Pretui addition)."
+          @onInput={{this.setSize}}
+        />
+        <Args.Yield
+          @name='default'
+          @description='The message with markup in it (a Token, a link, emphasis), in the same place and type as @message. Wins over @message when both are given.'
+        />
+        <Args.Yield @name='action' />
+        <Args.Yield
+          @name='altAction'
+          @description='The second way in, given equal billing with a separator between.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_EMPTY_STATE: Record<string, unknown> = {
+  EmptyState: EmptyStateUsage,
+};

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

@@ -0,0 +1,2 @@
+// Pretui — Empty: The shadcn / Ant name for EmptyState.
+export { EmptyState as Empty } from './empty-state';