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

package/bundled-realms/pretui/components/date-time-picker.usage.gts

@@ -0,0 +1,64 @@
+// Pretui — DateTimePicker usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { DateTimePicker } from './date-time-picker';
+
+const GRANULARITIES = ['minute', 'second'];
+
+export class DateTimePickerUsage extends Component {
+  granularities = GRANULARITIES;
+  @tracked value = '2026-10-02T07:30';
+  @tracked granularity = 'minute';
+  setValue = (v: string) => (this.value = v);
+  setGranularity = (v: string) => (this.granularity = v);
+  get granularityArg() {
+    return this.granularity as 'minute' | 'second';
+  }
+  get usage() {
+    let bits = ['@value={{this.startsAt}}', '@onChange={{this.setStartsAt}}', "@label='Roast starts'"];
+    if (this.granularity !== 'minute') bits.push(`@granularity='${this.granularity}'`);
+    return `<DateTimePicker ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='DateTimePicker'
+      @description='A date and a time in one field with one popover: the calendar and the time segments together, and Done commits a single wall-clock datetime such as 2026-10-02T07:30. Done waits until both halves are set; closing without it keeps the committed value.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='dt-demo'>
+          <DateTimePicker @value={{this.value}} @onChange={{this.setValue}} @granularity={{this.granularityArg}} @label='Roast starts' />
+          <p class='dt-demo-value'>Value: <code>{{this.value}}</code></p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String @name='value' @description="'YYYY-MM-DDTHH:MM', with ':SS' at second granularity. defaultValue seeds the uncontrolled form." />
+        <Args.Action @name='onChange' @description='The committed datetime, on Done. onValueChange is an alias.' />
+        <Args.String @name='granularity' @value={{this.granularity}} @options={{this.granularities}} @defaultValue='minute' @onInput={{this.setGranularity}} />
+        <Args.String @name='hourCycle' @defaultValue='24' />
+        <Args.String @name='label' @defaultValue='Date and time' />
+        <Args.String @name='placeholder' />
+        <Args.String @name='minDate' />
+        <Args.String @name='maxDate' />
+        <Args.Bool @name='disabled' @defaultValue={{false}} />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .dt-demo {
+        display: grid;
+        gap: var(--space-2, 0.375rem);
+        padding-block-end: 22rem;
+      }
+      .dt-demo-value {
+        margin: 0;
+        font-size: var(--text-ui-sm, 0.72rem);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_DATE_TIME_PICKER: Record<string, unknown> = {
+  DateTimePicker: DateTimePickerUsage,
+};

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

@@ -0,0 +1,374 @@
+// Pretui — Defer: renders its content only when it becomes visible, idle or intended.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { modifier } from 'ember-modifier';
+import { inViewport } from './in-view';
+import { Skeleton } from './skeleton';
+import { cssDeclaration, cssStyleFrom } from '../pretui-css';
+
+// ═════════════════════════════════════════════════════════════════════════
+// Defer
+// ═════════════════════════════════════════════════════════════════════════
+//
+// From `catalog-app/components/card-with-hydration.gts`.
+//
+// Better than the inspiration:
+//
+//  1. **The guard actually guards.** The upstream wrote
+//     `new Boolean(this.hydratedCardId)` — a Boolean *object*, which is
+//     truthy even wrapping `undefined`, so the condition it looks like was
+//     never once false. Here the gate is one tracked boolean and one arg.
+//  2. **Four triggers, and every one of them is reachable.** The upstream
+//     had `mouseenter` and nothing else: no focus path, no touch path, no
+//     click, no intersection — so keyboard and touch readers never hydrated
+//     anything, ever. `intent` mode renders a real, named `<button>` over
+//     the placeholder (hover, focus, tap and Enter all reveal); `visible`
+//     uses an IntersectionObserver; `idle` uses a one-shot, modifier-owned
+//     idle callback; `manual` obeys `@when` alone.
+//  3. **The placeholder reserves the final layout's space.** The upstream
+//     reserved nothing, so every hydration shoved the page. `@minHeight` /
+//     `@aspect` size the gate itself, and `min-block-size` is kept after the
+//     swap so the box can never shrink back.
+//  4. **`aria-busy` while pending, and a placeholder that is `aria-hidden`.**
+//     The upstream announced nothing at all; a shimmer with no `aria-busy`
+//     is a decoration that lies.
+//  5. **No error branch.** The upstream painted failures as an
+//     `rgba(255,0,0,0.1)` tint with no icon, no text and no `role='alert'` —
+//     colour-only error. The right fix is not a better tint: loading and
+//     failing belong to the *deferred content*, not to the gate that decided
+//     when to render it. Defer renders; whatever it renders owns its own
+//     states (that is what `DataComponent` is for).
+//  6. **`cursor: pointer` only where something is clickable.** The upstream
+//     put it on an element with no click handler, and an `outline` on
+//     `:hover` but never on focus.
+//  7. **Named transition + reduced motion.** `transition: ease 0.2s` names
+//     no property; here the reveal is a `@starting-style` fade on opacity
+//     alone, and `prefers-reduced-motion` lands on the end state.
+//
+// Distinct from `InView`, deliberately: InView always renders its content
+// and animates the entrance; Defer decides whether to render at all. They
+// share the mechanism, InView's `inViewport` modifier, not the job.
+
+export type DeferTrigger = 'visible' | 'idle' | 'intent' | 'manual';
+
+interface IdleScheduler {
+  requestIdleCallback?: (
+    callback: () => void,
+    options?: { timeout: number },
+  ) => number;
+  cancelIdleCallback?: (handle: number) => void;
+}
+
+/**
+ * Reveal when the main thread goes quiet.
+ *
+ * The realm's timer law in full: the handle is owned by this modifier, it is
+ * cleared in the destructor, and it is **one-shot** — nothing here re-arms,
+ * which is the property that keeps `await settled()` from hanging the whole
+ * suite. `requestIdleCallback` where it exists (with its own timeout as the
+ * upper bound), a single `setTimeout` where it does not.
+ */
+export const revealsWhenIdle = modifier(
+  (_el: HTMLElement, [armed, timeout, reveal]: [boolean, number, () => void]) => {
+    if (!armed) {
+      return;
+    }
+    let scope = globalThis as typeof globalThis & IdleScheduler;
+    let idleHandle: number | undefined;
+    let timerHandle: ReturnType<typeof setTimeout> | undefined;
+    if (typeof scope.requestIdleCallback === 'function') {
+      idleHandle = scope.requestIdleCallback(() => {
+        idleHandle = undefined;
+        reveal();
+      }, { timeout });
+    } else {
+      timerHandle = setTimeout(() => {
+        timerHandle = undefined;
+        reveal();
+      }, timeout);
+    }
+    return () => {
+      if (idleHandle !== undefined && typeof scope.cancelIdleCallback === 'function') {
+        scope.cancelIdleCallback(idleHandle);
+      }
+      if (timerHandle !== undefined) {
+        clearTimeout(timerHandle);
+      }
+    };
+  },
+);
+
+export interface DeferSignature {
+  Args: {
+    /**
+     * What decides. `visible` (default) — an IntersectionObserver.
+     * `intent` — a named button covering the placeholder: hover, focus, tap
+     * or Enter. `idle` — the first idle slice. `manual` — `@when` only.
+     */
+    trigger?: DeferTrigger;
+    /**
+     * Explicit gate. When `true` the content renders immediately regardless
+     * of `@trigger`; when `false` the trigger still applies. This is the
+     * caller's override, not a lock.
+     */
+    when?: boolean;
+    /** Stay revealed once revealed (default true). `false` re-hides on exit — for content too heavy to keep alive off-screen. */
+    once?: boolean;
+    /** IntersectionObserver threshold, 0–1. Default 0. */
+    threshold?: number;
+    /** IntersectionObserver rootMargin — '200px' to start early. Default '200px'. */
+    rootMargin?: string;
+    /** Upper bound in SECONDS on the idle wait. Default 2. */
+    idleTimeout?: number;
+    /** Reserved height while pending — kept afterwards as a floor. Any CSS length. */
+    minHeight?: string;
+    /** Reserved aspect ratio while pending, e.g. '16 / 9'. Dropped once revealed. */
+    aspect?: string;
+    /** Accessible name of the intent button. Default 'Load content'. */
+    intentLabel?: string;
+    /** Visible caption on the intent affordance. Omit for a bare surface. */
+    intentText?: string;
+    /** Announced politely once, after the swap. Silent by default — content arriving on scroll is not news. */
+    announceText?: string;
+    /** Fires the first time the content is revealed. */
+    onReveal?: () => void;
+  };
+  Blocks: {
+    /** The deferred subtree. Rendered only once the gate opens. */
+    default: [];
+    /** Replaces the Skeleton. Must occupy the reserved box. Requires an explicit `<:default>` alongside it. */
+    placeholder: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Defer extends Component<DeferSignature> {
+  @tracked private tripped = false;
+  /** Set once the content has been shown at least once. */
+  @tracked private everRevealed = false;
+
+  get trigger(): DeferTrigger {
+    return this.args.trigger ?? 'visible';
+  }
+  get once(): boolean {
+    return this.args.once ?? true;
+  }
+  get threshold(): number {
+    let value = this.args.threshold;
+    return typeof value === 'number' && value >= 0 && value <= 1 ? value : 0;
+  }
+  get rootMargin(): string {
+    return this.args.rootMargin ?? '200px';
+  }
+  /** Seconds in, milliseconds out — the kit speaks seconds everywhere. */
+  get idleTimeout(): number {
+    let seconds = this.args.idleTimeout;
+    return Math.round(
+      (typeof seconds === 'number' && seconds > 0 ? seconds : 2) * 1000,
+    );
+  }
+  get revealed(): boolean {
+    if (this.args.when === true) {
+      return true;
+    }
+    if (this.once && this.everRevealed) {
+      return true;
+    }
+    return this.tripped;
+  }
+  get pending(): boolean {
+    return !this.revealed;
+  }
+  get busyAttr(): string {
+    return this.pending ? 'true' : 'false';
+  }
+  get stateAttr(): string {
+    return this.revealed ? 'revealed' : 'pending';
+  }
+  /** Arm the observer only while it could still do something: until the
+   * first reveal, or for good when the content re-hides on exit. */
+  get watching(): boolean {
+    return this.trigger === 'visible' && (!this.once || !this.revealed);
+  }
+  get idling(): boolean {
+    return this.trigger === 'idle' && !this.revealed;
+  }
+  get showIntent(): boolean {
+    return this.trigger === 'intent' && this.pending;
+  }
+  get intentLabel(): string {
+    return this.args.intentLabel ?? 'Load content';
+  }
+  get liveText(): string {
+    return this.revealed && this.args.announceText ? this.args.announceText : '';
+  }
+
+  /**
+   * The reservation. `min-block-size` is written on the host and kept for
+   * good — a floor cannot cause a shift. `aspect-ratio` is only written
+   * while pending, because keeping it would distort real content.
+   */
+  get hostStyle() {
+    return cssStyleFrom([
+      cssDeclaration('min-block-size', this.args.minHeight),
+      this.pending ? cssDeclaration('aspect-ratio', this.args.aspect) : undefined,
+    ]);
+  }
+
+  reveal = (): void => {
+    if (this.revealed) {
+      return;
+    }
+    this.tripped = true;
+    if (!this.everRevealed) {
+      this.everRevealed = true;
+      this.args.onReveal?.();
+    }
+  };
+
+  onViewport = (inView: boolean): void => {
+    if (inView) {
+      this.reveal();
+    } else if (!this.once) {
+      this.tripped = false;
+    }
+  };
+
+  <template>
+    <div
+      class='pretui-defer'
+      data-state={{this.stateAttr}}
+      data-trigger={{this.trigger}}
+      aria-busy={{this.busyAttr}}
+      style={{this.hostStyle}}
+      data-test-pretui-defer
+      {{inViewport
+        this.threshold
+        this.rootMargin
+        this.once
+        enabled=this.watching
+        onChange=this.onViewport
+      }}
+      {{revealsWhenIdle this.idling this.idleTimeout this.reveal}}
+      ...attributes
+    >
+      {{#if this.revealed}}
+        <div class='pretui-defer-content' data-test-pretui-defer-content>
+          {{yield}}
+        </div>
+      {{else}}
+        <div class='pretui-defer-slot' data-test-pretui-defer-placeholder>
+          {{#if (has-block 'placeholder')}}
+            {{yield to='placeholder'}}
+          {{else}}
+            <Skeleton @height='100%' />
+          {{/if}}
+          {{#if this.showIntent}}
+            {{!--
+              A real button, not a div with a hover handler. It carries the
+              only accessible name in the subtree (the Skeleton is
+              aria-hidden), so hover, focus, tap and Enter are one control
+              rather than four code paths.
+            --}}
+            <button
+              type='button'
+              class='pretui-defer-intent'
+              aria-label={{this.intentLabel}}
+              data-test-pretui-defer-intent
+              {{on 'click' this.reveal}}
+              {{on 'pointerenter' this.reveal}}
+              {{on 'focus' this.reveal}}
+            >{{#if @intentText}}<span
+                  class='pretui-defer-intent-text'
+                >{{@intentText}}</span>{{/if}}</button>
+          {{/if}}
+        </div>
+      {{/if}}
+      <span class='pretui-sr' role='status' data-test-pretui-defer-live>{{this.liveText}}</span>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-defer {
+          display: grid;
+          align-content: stretch;
+          min-width: 0;
+          position: relative;
+        }
+        .pretui-defer-content,
+        .pretui-defer-slot {
+          min-width: 0;
+        }
+        .pretui-defer-slot {
+          display: grid;
+          align-content: stretch;
+          position: relative;
+          border-radius: var(--radius-surface, 10px);
+          overflow: hidden;
+        }
+        /* The swap is a fade on opacity only, from a @starting-style — no
+           transform, because content that slides in has moved the layout the
+           placeholder just spent its life reserving. */
+        .pretui-defer-content {
+          opacity: 1;
+          transition: opacity var(--pretui-dur-snap, 180ms)
+            var(--pretui-ease-snap, cubic-bezier(0.23, 1, 0.32, 1));
+        }
+        @starting-style {
+          .pretui-defer-content {
+            opacity: 0;
+          }
+        }
+        /* The intent affordance covers the placeholder rather than sitting
+           beside it: the whole reserved box is the target, which is how it
+           clears 44px on touch without a size arg. */
+        .pretui-defer-intent {
+          position: absolute;
+          inset: 0;
+          display: grid;
+          place-items: center;
+          border: 0;
+          border-radius: inherit;
+          background: transparent;
+          color: var(--muted-foreground);
+          font: inherit;
+          font-size: var(--text-ui-sm, 11.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          cursor: pointer;
+          transition: background var(--pretui-dur-snap, 180ms)
+            var(--pretui-ease-snap, cubic-bezier(0.23, 1, 0.32, 1));
+        }
+        .pretui-defer-intent:hover {
+          background: var(--hover, var(--boxel-100));
+        }
+        .pretui-defer-intent:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: -2px;
+        }
+        .pretui-defer-intent-text {
+          padding: var(--space-2, 6px) var(--space-4, 12px);
+          border-radius: var(--radius);
+          background: var(--card);
+          box-shadow: 0 0 0 1px var(--border);
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-defer-content,
+          .pretui-defer-intent {
+            transition: none;
+          }
+        }
+        .pretui-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          margin: -1px;
+          padding: 0;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+          border: 0;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,61 @@
+## What it is
+
+A render gate: hold a subtree until it is in view, until the browser is idle, until the reader asks for it, or until a flag says so — with a placeholder that reserves the final space in the meantime.
+
+It is about _work_, not choreography. **InView** animates an arrival; Defer decides whether the content is built at all. They compose.
+
+## The contract
+
+```
+@trigger?      — 'visible' (default, IntersectionObserver) | 'intent' | 'idle' | 'manual'
+@when?         — explicit gate: true renders immediately regardless of @trigger;
+                 false leaves the trigger in charge. A caller override, not a lock
+@once?         — stay revealed once revealed. Default true
+@threshold?    — IntersectionObserver threshold, 0–1. Default 0
+@rootMargin?   — IntersectionObserver rootMargin. Default '200px'
+@idleTimeout?  — upper bound in seconds on the idle wait. Default 2
+@minHeight?    — reserved height while pending; kept afterwards as a floor
+@aspect?       — reserved aspect ratio while pending; dropped once revealed
+@intentLabel?  — accessible name of the intent button. Default 'Load content'
+@intentText?   — visible caption on the intent affordance
+@announceText? — announced politely once, after the swap. Silent by default
+@onReveal?     — fires the first time the content is revealed
+
+<:default>     — the deferred subtree; rendered only once the gate opens
+<:placeholder> — replaces the Skeleton; must occupy the reserved box
+```
+
+**The placeholder reserves the final space**, which is the whole reason this is safe to use on a long page: content arriving does not push everything below it down. `@minHeight` survives as a floor afterwards; `@aspect` is dropped once revealed.
+
+**`@when` is an override, not a lock.** True renders now; false does not prevent the trigger from firing. A caller cannot use it to hold content closed.
+
+**`@rootMargin` defaults to 200px**, so visible-triggered content starts before it is on screen and is usually there by the time the reader arrives.
+
+**`@trigger='intent'` puts a named button over the placeholder** — hover, focus, tap or Enter all open it. That is the trigger to use for anything expensive enough that a scroll-past should not pay for it.
+
+**`@once={{false}}` re-hides on exit** with `@trigger='visible'`, for content too heavy to keep alive off-screen: the observer stays armed, and the content unmounts when it scrolls away and mounts again when it returns. `@onReveal` still fires only the first time.
+
+## Prior art
+
+**boxel-catalog's card-with-hydration** is the source.
+
+Where Pretui is better: four triggers rather than one, a reserved box rather than a collapsing placeholder, and an intent affordance that is a real button with an accessible name — so the "load this" path is not hover-only.
+
+Where it is thinner: no priority or concurrency control across several Defers on a page — they all open independently — no retry if the deferred subtree throws, and no way to pre-warm without revealing. The idle trigger is bounded by `@idleTimeout` rather than being truly opportunistic.
+
+## Accessibility
+
+- **It is silent by default, and that is the right default.** Content arriving because someone scrolled is not news, and a live region that announces every deferred block on a long page is unusable. `@announceText` is the opt-in for the cases where the arrival genuinely matters.
+- **The announcement is polite and fires once**, after the swap — not on every re-reveal.
+- **The intent affordance is a real button** with an accessible name defaulting to "Load content", operable by Enter and by tap as well as by hover. An intent gate that only responds to hover would be unreachable by keyboard.
+- **`@intentLabel` is the accessible name and `@intentText` the visible caption** — separate args, so a bare surface can still be named.
+- **The reserved box prevents layout shift**, which is a genuine accessibility property: content moving under a reader mid-sentence affects everyone, and most of all anyone using magnification.
+- **Deferred content is not in the accessibility tree until it renders.** A screen-reader user moving by heading will not find a heading inside an unopened Defer — so do not defer navigation landmarks or anything a reader might jump to.
+
+## Theming
+
+`@minHeight` and `@aspect` are caller values rather than tokens, since a reserved box is a property of the content rather than of the theme. The default placeholder is the kit's **Skeleton**, so it inherits that component's tokens and a theme retunes every pending block at once.
+
+`<:placeholder>` must occupy the reserved box — a placeholder smaller than the content reintroduces exactly the layout shift the component exists to prevent.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,174 @@
+// Pretui — Defer usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Defer } from './defer';
+
+// ── Defer ────────────────────────────────────────────────────────────────
+const TRIGGERS = ['visible', 'idle', 'intent', 'manual'];
+
+// Dropped upstream surface: the error branch. Loading and failing belong to
+// the deferred content, not to the gate that decided when to render it.
+class DeferUsage extends Component {
+  triggers = TRIGGERS;
+
+  @tracked trigger = 'intent';
+  @tracked minHeight = '120px';
+  @tracked aspect = '';
+  @tracked intentText = 'Show the chart';
+  @tracked revealCount = 0;
+  @tracked nonce = 0;
+
+  setTrigger = (v: string) => {
+    this.trigger = v;
+    this.nonce = this.nonce + 1;
+  };
+  setMinHeight = (v: string) => (this.minHeight = v);
+  setAspect = (v: string) => (this.aspect = v);
+  setIntentText = (v: string) => (this.intentText = v);
+  onReveal = () => (this.revealCount = this.revealCount + 1);
+  reset = () => (this.nonce = this.nonce + 1);
+
+  get triggerValue() {
+    return this.trigger as 'visible' | 'idle' | 'intent' | 'manual';
+  }
+  /** One keyed entry — bumping the nonce tears the gate down and builds a
+   *  fresh one, which is how the demo re-arms without a timer. */
+  get gates() {
+    return [{ id: 'gate-' + this.nonce }];
+  }
+  get aspectValue() {
+    return this.aspect.length > 0 ? this.aspect : undefined;
+  }
+  get usage() {
+    return "<Defer @trigger='" +
+      this.trigger +
+      "' @minHeight='" +
+      this.minHeight +
+      "' @onReveal={{this.load}}><:default>expensive thing</:default></Defer>";
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Defer'
+      @description='A render gate. The subtree is not rendered until it is worth paying for — when it scrolls into view, when the main thread goes idle, when the reader signals intent, or when a caller flag says so — and the placeholder reserves the final space so nothing shifts when the content lands. Reset re-arms the gate.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-demo-defer'>
+          {{#each this.gates key='id' as |gate|}}
+            <Defer
+              @trigger={{this.triggerValue}}
+              @minHeight={{this.minHeight}}
+              @aspect={{this.aspectValue}}
+              @intentLabel='Load the revenue chart'
+              @intentText={{this.intentText}}
+              @announceText='Revenue chart loaded'
+              @onReveal={{this.onReveal}}
+            >
+              <:placeholder>
+                <div class='pretui-demo-skel' aria-hidden='true'>
+                  reserved space
+                </div>
+              </:placeholder>
+              <:default>
+                <div class='pretui-demo-heavy'>
+                  The expensive thing — a chart, a map, an editor, a WebGL
+                  scene. Rendered exactly once,
+                  {{gate.id}}.
+                </div>
+              </:default>
+            </Defer>
+          {{/each}}
+        </div>
+        <p class='pretui-demo-readout' data-test-defer-readout>
+          revealed
+          {{this.revealCount}}
+          times
+        </p>
+        <Button
+          @tone='neutral'
+          @appearance='outlined'
+          data-test-defer-reset
+          {{on 'click' this.reset}}
+        >Reset the gate</Button>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='trigger'
+          @defaultValue='visible'
+          @value={{this.trigger}}
+          @options={{this.triggers}}
+          @description='What decides. visible uses an IntersectionObserver; intent renders a real named button over the placeholder so hover, focus, tap and Enter are one control; idle uses a one-shot modifier-owned idle callback; manual obeys the when flag alone.'
+          @onInput={{this.setTrigger}}
+        />
+        <Args.String
+          @name='minHeight'
+          @defaultValue=''
+          @value={{this.minHeight}}
+          @description='Reserved height while pending, kept afterwards as a floor. A floor can never cause a shift, which an aspect ratio can.'
+          @onInput={{this.setMinHeight}}
+        />
+        <Args.String
+          @name='aspect'
+          @defaultValue=''
+          @value={{this.aspect}}
+          @description='Reserved aspect ratio while pending, dropped once revealed so real content is never distorted.'
+          @onInput={{this.setAspect}}
+        />
+        <Args.String
+          @name='intentText'
+          @defaultValue=''
+          @value={{this.intentText}}
+          @description='Visible caption on the intent affordance. The accessible name comes from intentLabel and is always required.'
+          @onInput={{this.setIntentText}}
+        />
+        <Args.Action
+          @name='onReveal'
+          @description='Fires the first time the content is revealed.'
+        />
+        <Args.Yield
+          @name='placeholder'
+          @description='Replaces the Skeleton. Supplying it requires an explicit default block alongside — a Glimmer rule, not a Defer one.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-demo-defer {
+        display: grid;
+        gap: var(--space-4, 12px);
+      }
+      .pretui-demo-skel {
+        display: grid;
+        place-items: center;
+        height: 100%;
+        border-radius: var(--radius-surface, 10px);
+        background: var(--inset, var(--boxel-100));
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--ink-3, var(--boxel-400));
+      }
+      .pretui-demo-heavy {
+        display: grid;
+        place-items: center;
+        height: 100%;
+        padding: var(--space-5, 16px);
+        border-radius: var(--radius-surface, 10px);
+        background: color-mix(in oklch, var(--primary) 10%, var(--card));
+        font-size: var(--text-ui-md, 12.5px);
+        text-align: center;
+      }
+      .pretui-demo-readout {
+        margin: var(--space-3, 8px) 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        font-variant-numeric: tabular-nums;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_DEFER: Record<string, unknown> = {
+  Defer: DeferUsage,
+};