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

package/bundled-realms/pretui/components/hover-video-player.usage.gts

@@ -0,0 +1,152 @@
+// Pretui — HoverVideoPlayer usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { HoverVideoPlayer } from './hover-video-player';
+
+// ── HoverVideoPlayer ─────────────────────────────────────────────────────
+// A generated poster rather than a fetched thumbnail, so the frame is filled
+// even with no network — and deterministic, because it is a literal.
+const POSTER =
+  'data:image/svg+xml;charset=utf-8,' +
+  encodeURIComponent(
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 180">' +
+      '<rect width="320" height="180" fill="#1d2a26"/>' +
+      '<rect y="118" width="320" height="62" fill="#00a884" opacity="0.28"/>' +
+      '<circle cx="96" cy="118" r="26" fill="#00a884" opacity="0.8"/>' +
+      '<rect y="117" width="320" height="1.5" fill="#00a884"/>' +
+      '</svg>',
+  );
+
+/** Public test clip used by Media Chrome's own documentation; offline, the
+ * frame simply keeps its poster and the toggle reports back that playback
+ * was refused. */
+
+const CLIP =
+  'https://stream.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/high.mp4';
+
+const RATIOS = ['16 / 9', '4 / 3', '1 / 1'];
+
+class HoverVideoPlayerUsage extends GlimmerComponent {
+  @tracked playing = false;
+  @tracked ratio = '16 / 9';
+  @tracked playOnIntent = true;
+
+  setRatio = (ratio: string) => (this.ratio = ratio);
+  setIntent = (on_: boolean) => (this.playOnIntent = on_);
+  changed = (playing: boolean) => (this.playing = playing);
+
+  get statusText(): string {
+    return this.playing ? 'previewing' : 'at rest';
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='HoverVideoPlayer'
+      @description='A thumbnail that becomes a moving preview when you show interest in it, and stops when you stop. Four things the genre routinely gets wrong, fixed here. Touch: upstream binds mouseenter/mouseleave and is simply dead on a phone, so there is always a real play/pause button — fading in on hover or focus for a fine pointer, permanently visible at 44px on a coarse one. Keyboard: focusin/focusout drive the same path as the pointer, so tabbing to the card previews it. Motion preference: prefers-reduced-motion disables hover- and focus-autoplay outright, because a moving image is exactly what that preference is about — the explicit button still works, since the preference is about ambient motion and not about consent. Layout: @ratio reserves the box before the poster loads, so a grid of these does not reflow as they arrive. Playback follows ONE tracked boolean through a modifier — no timer, no rAF, no listener that outlives the element — and a refused play() is routed back to the component so the control never keeps claiming it is playing.'
+    >
+      <:example>
+        <div class='demo-shelf'>
+          <HoverVideoPlayer
+            @src={{CLIP}}
+            @poster={{POSTER}}
+            @label='Repricing the Kandy catalogue'
+            @caption='Repricing the Kandy catalogue'
+            @ratio={{this.ratio}}
+            @playOnIntent={{this.playOnIntent}}
+            @onPlayingChange={{this.changed}}
+          >
+            <:overlay>
+              <span class='demo-badge'>0:42</span>
+            </:overlay>
+          </HoverVideoPlayer>
+          <HoverVideoPlayer
+            @src={{CLIP}}
+            @poster={{POSTER}}
+            @label='Drafting the buying note'
+            @caption='Drafting the buying note'
+            @ratio={{this.ratio}}
+            @playOnIntent={{this.playOnIntent}}
+          />
+        </div>
+        <p class='demo-log'>first frame:
+          <strong>{{this.statusText}}</strong></p>
+        <p class='demo-hint'>Hover it, then Tab to it — both start the
+          preview. The button works either way, and is the only path when the
+          reader has asked for reduced motion.</p>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='ratio'
+          @description='Aspect ratio reserving the frame before anything loads. A caller string, so it goes through the kit-wide cssValue allowlist.'
+          @value={{this.ratio}}
+          @options={{RATIOS}}
+          @onInput={{this.setRatio}}
+          @defaultValue='16 / 9'
+        />
+        <Args.Bool
+          @name='playOnIntent'
+          @description='Preview on hover and focus (default true). Off, the button is the only path — which is also what reduced motion collapses to.'
+          @value={{this.playOnIntent}}
+          @onInput={{this.setIntent}}
+          @defaultValue={{true}}
+        />
+        <Args.Base
+          @name='src / poster / label / caption'
+          @description='The @label arg is REQUIRED: it names the play control and the figure, and an unlabelled video is an unlabelled control. @caption renders under the frame; without one the label is still present, visually hidden.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='muted / loop / rewind / onPlayingChange'
+          @description='Muted and looping by default (an unmuted hover preview is hostile), rewinding to the first frame when the preview stops, and reporting every start and stop so a caller can coordinate a shelf where only one plays at a time.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='overlay'
+          @description='Content laid over the frame — a duration chip, a title, a live badge. It is pointer-transparent, so it never steals the hover the preview depends on.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .demo-shelf {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        gap: 12px;
+        max-width: 34rem;
+      }
+      .demo-badge {
+        display: inline-flex;
+        align-items: center;
+        height: 20px;
+        padding: 0 7px;
+        border-radius: 5px;
+        background: color-mix(in oklch, var(--boxel-dark) 60%, transparent);
+        color: var(--boxel-light);
+        font-family: var(--font-mono);
+        font-size: 10.5px;
+        font-variant-numeric: tabular-nums;
+      }
+      .demo-log {
+        margin: var(--space-4, 11px) 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .demo-log strong {
+        color: var(--foreground);
+        font-weight: 600;
+      }
+      .demo-hint {
+        margin: var(--space-3, 7px) 0 0;
+        max-width: 62ch;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.6;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_HOVER_VIDEO_PLAYER: Record<string, unknown> = {
+  HoverVideoPlayer: HoverVideoPlayerUsage,
+};

package/bundled-realms/pretui/components/icon-button.examples.gts

@@ -0,0 +1,69 @@
+// Pretui — IconButton example gallery.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import {
+  Lab,
+  Mono,
+  Row,
+  SUPPLIERS,
+  TEAS,
+  pick,
+  seedFrom,
+} from '../examples-kit';
+import type { ExampleSpec } from '../examples-kit';
+import ChevronLeftIcon from '@cardstack/boxel-icons/chevron-left';
+import ChevronRightIcon from '@cardstack/boxel-icons/chevron-right';
+import CopyIcon from '@cardstack/boxel-icons/copy';
+import EllipsisIcon from '@cardstack/boxel-icons/ellipsis';
+import PencilIcon from '@cardstack/boxel-icons/pencil';
+import XIcon from '@cardstack/boxel-icons/x';
+import { IconButton } from './icon-button';
+
+// ── IconButton ───────────────────────────────────────────────────────────
+const IBT = seedFrom('IconButton');
+const ibtTea = pick(IBT, 0, TEAS);
+const ibtSupplier = pick(IBT, 1, SUPPLIERS);
+
+const IconButtonToolbar: TemplateOnlyComponent = <template>
+  <Row>
+    <Lab>{{ibtTea}}</Lab>
+    <IconButton @appearance='plain' @label='Edit' @icon={{PencilIcon}} />
+    <IconButton @appearance='plain' @label='Duplicate' @icon={{CopyIcon}} />
+    <IconButton @appearance='plain' @label='More' @icon={{EllipsisIcon}} />
+  </Row>
+</template>;
+
+const IconButtonRemove: TemplateOnlyComponent = <template>
+  <Row>
+    <Lab>{{ibtSupplier}}</Lab>
+    <IconButton @tone='danger' @appearance='accent' @label='Remove supplier' @icon={{XIcon}} />
+  </Row>
+</template>;
+
+const IconButtonPager: TemplateOnlyComponent = <template>
+  <Row>
+    <IconButton @label='Previous page' @icon={{ChevronLeftIcon}} />
+    <Mono>3 / 7</Mono>
+    <IconButton @label='Next page' @icon={{ChevronRightIcon}} />
+  </Row>
+</template>;
+
+export const EXAMPLES_ICON_BUTTON: Record<string, ExampleSpec[]> = {
+  IconButton: [
+    {
+      title: 'Toolbar cluster',
+      note: 'Ghost trio at the end of a record header.',
+      component: IconButtonToolbar,
+    },
+    {
+      title: 'Destructive remove',
+      note: 'The label rides aria-label and the tooltip — never the face.',
+      component: IconButtonRemove,
+    },
+    {
+      title: 'Pager pair',
+      note: 'Mono counter between secondary steppers.',
+      component: IconButtonPager,
+    },
+  ],
+};
+

package/bundled-realms/pretui/components/icon-button.gts

@@ -0,0 +1,153 @@
+// IconButton: a square Button whose face is an icon; the accessible name rides aria-label / title.
+import Component from '@glimmer/component';
+import type { ComponentLike } from '@glint/template';
+import { Button, resolveBusy, resolveDisabled } from './button';
+import type { ButtonSignature } from './button';
+
+export type IconButtonIcon = ComponentLike<{ Element: SVGSVGElement }>;
+
+// Glyph size, in em of the button's font size so it follows @size and the
+// theme's text scale. Set as width/height attributes rather than CSS so the
+// icon has an intrinsic size before any stylesheet applies.
+export const ICON_SIZE = '1.25em';
+
+// Every Button argument, plus what an icon-only button needs.
+export interface IconButtonSignature {
+  Args: ButtonSignature['Args'] & {
+    label: string;
+    /** icon component, rendered before any block content */
+    icon?: IconButtonIcon;
+    /** the @icon's dimensions, which otherwise follow @size */
+    iconWidth?: string | number;
+    iconHeight?: string | number;
+    /** toggle state, as aria-pressed; leave undefined for a plain action.
+     *  Does not apply with @href */
+    pressed?: boolean;
+  };
+  Blocks: { default: [] };
+  Element: HTMLButtonElement | HTMLAnchorElement;
+}
+
+export class IconButton extends Component<IconButtonSignature> {
+  // Secondary chrome by default: neutral and outlined, unless the caller picks
+  // a tone or appearance, or the deprecated @variant names both.
+  get tone() {
+    return this.args.tone ?? (this.args.variant ? undefined : 'neutral');
+  }
+  get appearance() {
+    return this.args.appearance ?? (this.args.variant ? undefined : 'outlined');
+  }
+  get disabled() {
+    return resolveDisabled(this.args);
+  }
+  get busy() {
+    return resolveBusy(this.args);
+  }
+  // aria-label replaces the content as the name, so Button's busy text never
+  // reaches it; the busy label joins the name here instead, and still goes
+  // to Button, which shows it when the button is wide enough.
+  get accessibleName() {
+    let { label, busyLabel, href } = this.args;
+    return this.busy && busyLabel && !href ? `${label} ${busyLabel}` : label;
+  }
+  get ariaPressed() {
+    let { pressed, href } = this.args;
+    return pressed === undefined || href ? undefined : String(pressed);
+  }
+  get iconWidth() {
+    return this.args.iconWidth ?? ICON_SIZE;
+  }
+  get iconHeight() {
+    return this.args.iconHeight ?? ICON_SIZE;
+  }
+  <template>
+    <Button
+      @variant={{@variant}}
+      @tone={{this.tone}}
+      @appearance={{this.appearance}}
+      @size={{@size}}
+      @disabled={{this.disabled}}
+      @shape={{@shape}}
+      @href={{@href}}
+      @busy={{this.busy}}
+      @busyLabel={{@busyLabel}}
+      class='pretui-iconbtn'
+      aria-label={{this.accessibleName}}
+      aria-pressed={{this.ariaPressed}}
+      title={{@label}}
+      data-test-pretui-icon-button
+      ...attributes
+    >
+      {{! hidden because aria-label names the button; an icon with its own
+          <title>, or a text glyph, would otherwise be read a second time }}
+      <span
+        class='pretui-iconbtn-glyph'
+        aria-hidden='true'
+        data-test-pretui-icon-button-glyph
+      >
+        {{#if @icon}}
+          <@icon width={{this.iconWidth}} height={{this.iconHeight}} />
+        {{/if}}
+        {{yield}}
+      </span>
+    </Button>
+    <style scoped>
+      /* above Button's layer, so these win by layer order, not file order */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        .pretui-iconbtn {
+          padding: 0;
+          width: var(--pretui-button-h, 2.24em);
+        }
+        /* square against Button's 24px minimum height at xs */
+        .pretui-iconbtn[data-size='xs'] {
+          width: max(var(--pretui-button-h, 2.24em), 1.5rem);
+        }
+        /* block-level, so the glyph is not set on Button's label line and
+           its baseline */
+        .pretui-iconbtn-glyph {
+          display: flex;
+          align-items: center;
+          justify-content: center;
+        }
+        /* pressed is a tint one step stronger than the filled appearance's,
+           so it reads on outlined, plain and filled alike; an accent fill has
+           no stronger step and a link has no fill, so toggles use another
+           appearance */
+        .pretui-iconbtn[aria-pressed='true']:not(
+            [data-appearance='accent'],
+            [data-appearance='link']
+          ) {
+          --_iconbtn-pressed-base: var(--background);
+          --pretui-btn-surface: color-mix(
+            in oklch,
+            var(--pretui-tone) 28%,
+            var(--_iconbtn-pressed-base)
+          );
+          --pretui-btn-surface-hover: color-mix(
+            in oklch,
+            var(--pretui-btn-tint) 34%,
+            var(--_iconbtn-pressed-base)
+          );
+        }
+        /* over the outlined appearance's own base surface, when a theme sets
+           one, so pressing changes the tint and not the base */
+        .pretui-iconbtn[aria-pressed='true'][data-appearance='outlined'] {
+          --_iconbtn-pressed-base: var(
+            --pretui-button-secondary-bg,
+            var(--background)
+          );
+        }
+        /* not when disabled, whose GrayText edge from Button is its only cue */
+        @media (forced-colors: active) {
+          .pretui-iconbtn[aria-pressed='true']:not(
+              :disabled,
+              [aria-disabled='true']
+            ) {
+            border-color: Highlight;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/icon-button.md

@@ -0,0 +1,72 @@
+## What it is
+
+A square **Button** carrying an icon instead of text, with a mandatory label. Use it in dense chrome where a word will not fit — toolbar affordances, row actions, panel headers, close buttons. If there is room for a word, use **Button**: an icon plus a label is comprehended faster than an icon alone by every measure, and the icon-only form is a space decision, not a clarity one. For a copy-to-clipboard affordance specifically, use **CopyButton**, which adds the confirm-state feedback.
+
+## The contract
+
+```
+@label: string   (required)
+@icon?: ComponentLike<{ Element: SVGSVGElement }>   (rendered before any block content)
+@iconWidth?, @iconHeight?: string | number   (the @icon's size; default 1.25em, so it follows the button's font size)
+@tone?, @appearance?   (default 'neutral' / 'outlined'; forwarded to Button)
+@variant?: ButtonVariant   (deprecated sugar over @tone + @appearance, as on Button)
+@size?: 'xs' | 's' | 'm' | 'l' | 'xl'   (default 'm', forwarded to Button)
+@shape?: 'rounded' | 'pill' | 'square'   (forwarded to Button; 'pill' is a circle, since the button is square)
+@href?: string   (renders an <a>; @busy and @pressed do not apply)
+@pressed?: boolean   (toggle state as aria-pressed; leave undefined for a plain action)
+@busy?, @loading?, @isLoading?, @isPending?   (forwarded to Button)
+@busyLabel?: string   (added after @label in the accessible name while busy; forwarded to Button, which shows it when the button is wide enough)
+@disabled?, @isDisabled?
+<:default>   — the icon, when it is not passed as @icon
+Element: HTMLButtonElement | HTMLAnchorElement
+```
+
+**Every Button argument is accepted, with the same meaning and aliases**: the signature is Button's plus `@label`, `@icon`, `@iconWidth`/`@iconHeight` and `@pressed`. Only the default treatment differs: `neutral` / `outlined`.
+
+**`@label` is required, and it is the whole point of the component existing.** An icon-only `<Button>` has no accessible name and nothing warns you; `IconButton` makes the name non-optional at the type level and applies it as both `aria-label` and `title`. That is the single reason this is a separate export rather than a `size='icon'` variant.
+
+**`@icon` takes an icon component, as boxel-ui's IconButton does**, and sizes it with `width`/`height` attributes so it has an intrinsic size before any stylesheet applies. The default is `1.25em`, so the icon follows the button's font size: it scales with `@size` and with a theme's text scale. `@iconWidth`/`@iconHeight` override that size. boxel-ui calls them `@width`/`@height`; the `icon` prefix keeps them from reading as the button's own size. Block content still works and renders after `@icon`, so a text glyph or an inline SVG needs no wrapper component.
+
+The default treatment is `neutral` / `outlined`, not `primary` / `accent` — icon buttons are almost always secondary chrome, and defaulting the other way would fill toolbars with accent fills.
+
+Sizing is one rule: `padding: 0; width: var(--pretui-button-h, 2.24em)`, the same em-scaled metric Button uses for its height, so the result is a square at every `@size`; at `xs` the width takes the same 24px floor as Button's height. The rules sit in `@layer PretComposite`, above Button's `PretComponent` layer, so they win by layer order rather than by stylesheet order. The rule targets `.pretui-iconbtn` directly: the class and this template's scope attribute both ride `...attributes` onto the composed Button's root element, so a plain compound selector is what matches it.
+
+## Prior art
+
+**Web Awesome** has no separate icon button: `wa-button` takes an icon child and **console-warns when an icon-only button has an unlabeled `wa-icon`** — a runtime nudge instead of a type-level requirement. **React Spectrum `ActionButton`** with `isQuiet` is the analogue, and Spectrum's convention is a `<Text>` child wrapped in a visually-hidden slot so the label is a real child rather than an attribute. **shadcn** uses `<Button size="icon">` and provides no label enforcement whatsoever — an `sr-only` span is left to the developer.
+
+Pretui's improvement over both is small and real: **the label cannot be forgotten.** Web Awesome catches it at runtime in the console, shadcn does not catch it at all, and here it is a required arg. Making the mistake unrepresentable beats warning about it.
+
+**`@tone` and `@appearance` are forwarded to Button**, so IconButton reaches the same seven tones and six appearances as Button. `@variant` is accepted but deprecated, as on Button.
+
+### Differences from boxel-ui IconButton
+
+- **`@width`/`@height` are `@iconWidth`/`@iconHeight`**, since they size the icon, not the button.
+- **`@round` is `@shape='pill'`.** The button is square, so a pill is a circle.
+- **boxel-ui's `@kind` becomes `@tone` × `@appearance`.** `primary-dark` and `text-only` have no single equivalent; pick the pair that matches.
+- **`@size` is Pret UI's scale** (`xs`…`xl`, em-scaled), not boxel-ui's fixed `extra-small` / `small` / `base` / `tall` / `touch` heights.
+- **No `--boxel-icon-button-*` knobs.** Size follows `--pretui-button-h`, and color follows Button's tone and appearance tokens.
+- **`title` is set**, so a sighted mouse user gets a native tooltip that boxel-ui's IconButton does not show.
+
+## Accessibility
+
+Native `<button>`; no APG pattern needed. Space and Enter both activate.
+
+What is right:
+
+- `aria-label={{@label}}` gives the accessible name, and it is required.
+- **The face is `aria-hidden`.** `aria-label` already names the button, so an icon that emits its own `<title>`, or a text glyph such as `✕`, is not read a second time.
+- **`@pressed` sets `aria-pressed`** for a toggle (pin, favorite, bold). Per APG, a toggle's label must not change with its state, so `@label` stays fixed and `aria-pressed` carries the state. A pressed button takes a tint one step stronger than the `filled` appearance's, so the state shows on `outlined`, `plain` and `filled` alike, plus a forced-colors `Highlight` edge. An `accent` appearance has no stronger step to show it and a `link` has no fill, so a toggle should use another appearance.
+- **`@busy` keeps focus** (Button's `aria-disabled` treatment), and `@busyLabel` joins the accessible name, because `aria-label` hides Button's own busy text from it.
+
+Gaps and cautions:
+
+- **`title` is set to the same string as `aria-label`.** This is deliberate — it gives sighted mouse users a native tooltip — but it is a known double-announcement risk: some screen reader and browser combinations read the accessible name and then the `title` as a description. It is also a UA-controlled tooltip, which means no styling and, per WCAG 1.4.13's exception, no dismissible/hoverable obligation. If you want a styled hint, wrap in **Tooltip** and be aware you will then have three sources for one string.
+- **Target size**: 28×28 CSS px at the default size clears WCAG 2.5.8's 24×24 minimum, but only just, and adjacent icon buttons in a toolbar with no gap will have touching targets.
+- **Focus-visible ring inherited from Button**: `outline: 2px solid var(--ring)` with a 2px offset, which matters more here because there is no text to underline or shift.
+
+## Theming
+
+Everything comes from **Button**: `--pretui-tone`/`--pretui-tone-on` per tone, `--radius`, `--hover`, `--border`, `--pretui-edge-highlight`, `--shadow-ink-mid` — plus `--pretui-button-h` (default `2.24em`) for the square width.
+
+A theme retuning `--pretui-button-h` moves IconButton's width and Button's height together, so icon buttons stay square.

package/bundled-realms/pretui/components/icon-button.usage.gts

@@ -0,0 +1,208 @@
+// Pretui — IconButton usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import PlusIcon from '@cardstack/boxel-icons/plus';
+import { FreestyleUsage } from './freestyle-usage';
+import { IconButton } from './icon-button';
+import { BUTTON_SHAPES } from './button';
+import type { ButtonShape } from './button';
+import {
+  PRETUI_APPEARANCES,
+  PRETUI_SIZES,
+  PRETUI_TONES,
+} from '../pretui-primitives';
+import type {
+  PretuiAppearance,
+  PretuiSize,
+  PretuiTone,
+} from '../pretui-primitives';
+
+const TONES = [...PRETUI_TONES];
+const APPEARANCES = [...PRETUI_APPEARANCES];
+const SIZES = [...PRETUI_SIZES];
+const SHAPES = [...BUTTON_SHAPES];
+
+// ── IconButton ← icon-button/usage.gts ───────────────────────────────────
+// Dropped knobs: @round (use @shape='pill'), @class (pass class directly).
+// @size takes Pret UI's scale rather than boxel-ui's fixed heights. The
+// tone and appearance knobs start at neutral / outlined, the 'secondary'
+// default.
+export class IconButtonUsage extends Component {
+  @tracked labelText = 'Add item';
+  @tracked tone = 'neutral';
+  @tracked appearance = 'outlined';
+  @tracked size = 'm';
+  @tracked busy = false;
+  @tracked busyLabel = '';
+  @tracked disabled = false;
+  @tracked href = '';
+  @tracked shape = 'rounded';
+  @tracked pressed: boolean | undefined;
+  setLabel = (v: string) => (this.labelText = v);
+  setTone = (v: string) => (this.tone = v);
+  setAppearance = (v: string) => (this.appearance = v);
+  setSize = (v: string) => (this.size = v);
+  setBusy = (v: boolean) => (this.busy = v);
+  setBusyLabel = (v: string) => (this.busyLabel = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setHref = (v: string) => (this.href = v);
+  setShape = (v: string) => (this.shape = v);
+  setPressed = (v: boolean) => (this.pressed = v);
+  get toneVal() {
+    return this.tone as PretuiTone;
+  }
+  get appearanceVal() {
+    return this.appearance as PretuiAppearance;
+  }
+  get sizeVal() {
+    return this.size as PretuiSize;
+  }
+  get hrefVal() {
+    return this.href || undefined;
+  }
+  get shapeVal() {
+    return this.shape as ButtonShape;
+  }
+  get usage() {
+    let bits = [`@label='${this.labelText}'`];
+    if (this.tone !== 'neutral') bits.push(`@tone='${this.tone}'`);
+    if (this.appearance !== 'outlined') {
+      bits.push(`@appearance='${this.appearance}'`);
+    }
+    if (this.size !== 'm') bits.push(`@size='${this.size}'`);
+    if (this.busy) bits.push('@busy={{true}}');
+    if (this.busyLabel) bits.push(`@busyLabel='${this.busyLabel}'`);
+    if (this.disabled) bits.push('@disabled={{true}}');
+    if (this.href) bits.push(`@href='${this.href}'`);
+    if (this.shape !== 'rounded') bits.push(`@shape='${this.shape}'`);
+    if (this.pressed !== undefined) bits.push(`@pressed={{${this.pressed}}}`);
+    return `<IconButton ${bits.join(' ')} @icon={{PlusIcon}} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='IconButton'
+      @description='Button rendered as a single icon with no text — used in toolbars, table-row actions, and tight UI spots where a labeled button would not fit.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <IconButton
+          @label={{this.labelText}}
+          @tone={{this.toneVal}}
+          @appearance={{this.appearanceVal}}
+          @size={{this.sizeVal}}
+          @busy={{this.busy}}
+          @busyLabel={{this.busyLabel}}
+          @disabled={{this.disabled}}
+          @href={{this.hrefVal}}
+          @shape={{this.shapeVal}}
+          @pressed={{this.pressed}}
+          @icon={{PlusIcon}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='label'
+          @required={{true}}
+          @value={{this.labelText}}
+          @description='Accessible name — rendered as aria-label and title.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='tone'
+          @value={{this.tone}}
+          @options={{TONES}}
+          @defaultValue='neutral'
+          @description='Semantic color, as on Button.'
+          @onInput={{this.setTone}}
+        />
+        <Args.String
+          @name='appearance'
+          @value={{this.appearance}}
+          @options={{APPEARANCES}}
+          @defaultValue='outlined'
+          @description='Visual weight, as on Button.'
+          @onInput={{this.setAppearance}}
+        />
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{SIZES}}
+          @defaultValue='m'
+          @description='Button size; the square and the @icon scale with it.'
+          @onInput={{this.setSize}}
+        />
+        <Args.Bool
+          @name='busy'
+          @value={{this.busy}}
+          @defaultValue={{false}}
+          @description="Button's busy state; the button keeps focus. @loading, @isLoading and @isPending are aliases."
+          @onInput={{this.setBusy}}
+        />
+        <Args.String
+          @name='busyLabel'
+          @value={{this.busyLabel}}
+          @description='Added after @label in the accessible name while busy.'
+          @onInput={{this.setBusyLabel}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @defaultValue={{false}}
+          @description='Disables the button; @isDisabled is an alias.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='href'
+          @value={{this.href}}
+          @description='Renders a link (an <a>) with the same look; @busy and @pressed do not apply.'
+          @onInput={{this.setHref}}
+        />
+        <Args.String
+          @name='shape'
+          @value={{this.shape}}
+          @options={{SHAPES}}
+          @defaultValue='rounded'
+          @description='Corner treatment; pill is a circle, since the button is square.'
+          @onInput={{this.setShape}}
+        />
+        <Args.Bool
+          @name='pressed'
+          @value={{this.pressed}}
+          @description='Toggle state, as aria-pressed; leave unset for a plain action.'
+          @onInput={{this.setPressed}}
+        />
+        <Args.Base
+          @name='icon'
+          @typeLabel='Component'
+          @description="Icon component, sized to the button's font size or by @iconWidth / @iconHeight."
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='iconWidth'
+          @typeLabel='String | Number'
+          @description="The @icon's width; 1.25em of the button's font size by default."
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='iconHeight'
+          @typeLabel='String | Number'
+          @description="The @icon's height; 1.25em of the button's font size by default."
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='variant'
+          @typeLabel='String'
+          @description='Deprecated sugar over @tone + @appearance, as on Button; defaults to secondary.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @description='The icon as block content, when it is not passed as @icon.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_ICON_BUTTON: Record<string, unknown> = {
+  IconButton: IconButtonUsage,
+};