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

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

@@ -0,0 +1,71 @@
+## What it is
+
+The **image agents reach for**: a picture in a frame that reserves its ratio before the bytes arrive, with a load state, a fallback source, a failure face instead of the browser's broken-image icon, and an optional preview. Use it for photos, product shots, avatars at a size and illustrations in cards.
+
+Reach for a neighbour in these cases:
+
+- **AspectRatio** is the plain frame Image sits in. Use it directly for iframes, maps and charts, or for a painted background image.
+- **ImageFrame** is the adapter **MediaViewer** renders a resolved media asset with, including its dimensions caption.
+- **Lightbox** is a gallery grid with full-screen zoom and pan.
+- **Avatar** is an identity disc with initials.
+- **Skeleton** is the placeholder before you even know which image to show.
+
+## The contract
+
+```
+@src?, @alt (required; '' = decorative)
+@ratio? (number or '16 / 9'; defaults to @width / @height, then 4 / 3)
+@fit? ('cover' | 'contain'; default 'cover')
+@width?, @height?, @loading? ('lazy' | 'eager'; default 'lazy')
+@fallback?, @preview?, @previewLabel? (default 'View larger')
+@radius?, @bordered?, @onStatusChange?
+<:fallback>   — what shows when every source has failed
+Element: HTMLDivElement
+```
+
+**The frame is reserved first.** Image renders inside an **AspectRatio**, so its box has its final shape before the image decodes and nothing around it reflows (Law 8). Without `@ratio`, `@width` / `@height` supply one. Without those, it falls back to 4 / 3 instead of collapsing to zero height.
+
+**`@alt` is required, and empty is a decision.** There is no default alt. `@alt=''` renders a decorative `<img alt="">`, and any other value is the image's accessible name.
+
+**Three states, reported.** `data-status` on the frame is `loading`, `loaded` or `error`, and `@onStatusChange` fires on each change. While loading, the frame shows a shimmer on the ground colour and the image is transparent. It fades in once decoded. An image that finished before its listeners were attached, such as one from cache, is read on insert, so it never stays stuck in `loading`.
+
+**One fallback, then a face.** When `@src` fails, `@fallback` is tried once. A fallback identical to `@src` is not retried. When everything has failed, the broken `<img>` is removed and replaced with the `<:fallback>` block, or by default a picture glyph with the alt text written out, so the reader still learns what was meant to be there. A missing `@src` is a failure too. A new `@src` starts the whole sequence over.
+
+**`@preview` opens it larger.** The frame becomes a button. Click or Enter opens a **Dialog** with the image shown `contain` at up to 75% of the viewport height. The button is disabled until the image has loaded, so it never opens onto a broken picture.
+
+## Prior art
+
+**Ant Image** takes `src`, `alt`, `fallback`, `placeholder`, `preview` (with a full toolbar: zoom, rotate, flip, and a group mode) and `width` / `height`. **Mantine Image** takes `src`, `fallbackSrc`, `fit`, `radius` and `h` / `w`. **Chakra Image** takes `fallbackSrc` / `fallback` and `fit`. **MUI** has no component and relies on the plain `img`. Next.js `Image` is the other reference agents know: required `alt`, required dimensions, and reserved space.
+
+Where Pretui is better: **the ratio is always reserved.** Ant and Mantine reserve space only when the caller sets both dimensions, and a missing height is the most common layout-shift bug. **`alt` is required** at the type level, as in Next.js and unlike every component kit above. **Failure keeps the meaning**: the default face writes the alt text out, where Ant and Mantine show a generic placeholder image. **State is observable** through `data-status` and `@onStatusChange`, which Mantine does not expose.
+
+Where it is thinner: **the preview is plain.** There is no zoom, rotate, pan or gallery stepping. Use **Lightbox** for those. There is **no `srcset` / `sizes`** for responsive sources, and **no custom placeholder slot**: the loading state is the shimmer. **One fallback source**, where Ant accepts a node.
+
+## Accessibility
+
+No APG pattern. The rules are about names.
+
+- **The image's name is `@alt`.** An empty alt stays `alt=""`, which is correct for decoration. The tests assert both.
+- **With `@preview`, the button carries the name**: "View larger: Estate at dawn", with `aria-haspopup="dialog"`. The inner `<img>` is `alt=""`, so the name is not read twice. The tests assert all three. The dialog's image carries the real alt, and the dialog is labelled by it.
+- **The failure face keeps the name.** The alt text is shown and exposed as `role="img"` with that label, so a screen reader user hears what is missing rather than nothing. The glyph is `aria-hidden`. The tests assert the label on the failure face.
+- **The preview button is disabled while loading**, so keyboard users cannot open an empty dialog.
+- **Write alt for the context.** The same photo needs different alt text on a product page and in a gallery thumbnail. The component cannot know which, so the text is the caller's job.
+
+## Theming
+
+Image reads **AspectRatio**'s tokens for the frame: `--pretui-aspect-ratio`, `--pretui-aspect-radius` (from `@radius`), `--pretui-aspect-bg` (the loading and failure ground) and `--pretui-shadow-hairline` for `@bordered`. It adds `--card` for the shimmer highlight, `--muted-foreground` and `--text-ui-sm` for the failure face, `--ring` for the preview button's focus ring, `--space-2` / `--space-4`, and `--pretui-dur-enter` / `--pretui-ease-enter` for the fade-in.
+
+The shimmer and the fade are dropped under `prefers-reduced-motion`. `object-fit` follows `@fit`. The preview's 75vh height cap is fixed.
+
+The styles sit in `@layer PretComposite`, above AspectRatio's `PretComponent` layer, so what this component sets on AspectRatio wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.
+
+## React ecosystem
+
+| Agent types                            | Give them                                 |
+| -------------------------------------- | ----------------------------------------- |
+| `<img src alt>`                        | `<Image @src @alt />`                     |
+| Ant `fallback` / Mantine `fallbackSrc` | `@fallback`                               |
+| Ant `preview`                          | `@preview` (plain), or **Lightbox**       |
+| Ant `placeholder`                      | the built-in loading shimmer              |
+| Mantine `fit="contain"` / `radius`     | `@fit='contain'` / `@radius`              |
+| Next.js `<Image width height>`         | `@width` / `@height` (they set the ratio) |

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

@@ -0,0 +1,126 @@
+// Pretui — Image usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Image } from './image';
+
+// A small inline SVG, so the page renders offline and in the indexer.
+const PHOTO =
+  'data:image/svg+xml;utf8,' +
+  encodeURIComponent(
+    "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 640 480'><defs><linearGradient id='g' x1='0' y1='0' x2='0' y2='1'><stop offset='0' stop-color='#f6c38b'/><stop offset='1' stop-color='#8a5a44'/></linearGradient></defs><rect width='640' height='480' fill='url(#g)'/><circle cx='470' cy='150' r='60' fill='#fde7c2'/><path d='M0 360 L180 240 L320 330 L460 220 L640 350 L640 480 L0 480 Z' fill='#4b3326'/></svg>",
+  );
+const BROKEN = 'data:image/png;base64,AAAA';
+const FIT_OPTIONS = ['cover', 'contain'];
+
+export class ImageUsage extends Component {
+  fitOptions = FIT_OPTIONS;
+  @tracked alt = 'Estate hills at dawn';
+  @tracked ratio = '16 / 9';
+  @tracked fit = 'cover';
+  @tracked preview = true;
+  @tracked broken = false;
+  @tracked useFallback = false;
+  setAlt = (v: string) => (this.alt = v);
+  setRatio = (v: string) => (this.ratio = v);
+  setFit = (v: string) => (this.fit = v);
+  setPreview = (v: boolean) => (this.preview = v);
+  setBroken = (v: boolean) => (this.broken = v);
+  setUseFallback = (v: boolean) => (this.useFallback = v);
+  get src() {
+    return this.broken ? BROKEN : PHOTO;
+  }
+  get fallback() {
+    return this.useFallback ? PHOTO : undefined;
+  }
+  get fitArg() {
+    return this.fit as 'cover' | 'contain';
+  }
+  get usage() {
+    let bits = [`@src={{this.photo}}`, `@alt='${this.alt}'`, `@ratio='${this.ratio}'`];
+    if (this.fit !== 'cover') bits.push(`@fit='${this.fit}'`);
+    if (this.useFallback) bits.push('@fallback={{this.placeholder}}');
+    if (this.preview) bits.push('@preview={{true}}');
+    return `<Image ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Image'
+      @description='An image in a frame that reserves its ratio before the bytes arrive, with a load state, a fallback source, a failure face instead of the broken-image icon, and an optional preview dialog. Alt is required; an empty alt means decorative. AspectRatio is the plain frame; ImageFrame is the MediaViewer adapter.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='img-demo'>
+          <Image
+            @src={{this.src}}
+            @alt={{this.alt}}
+            @ratio={{this.ratio}}
+            @fit={{this.fitArg}}
+            @fallback={{this.fallback}}
+            @preview={{this.preview}}
+            @bordered={{true}}
+          />
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String @name='src' @description='The image source.' />
+        <Args.String
+          @name='alt'
+          @required={{true}}
+          @value={{this.alt}}
+          @description='The accessible name. An empty string marks the image decorative.'
+          @onInput={{this.setAlt}}
+        />
+        <Args.String
+          @name='ratio'
+          @value={{this.ratio}}
+          @description='A number or the CSS spelling. Defaults to width / height, then 4 / 3.'
+          @onInput={{this.setRatio}}
+        />
+        <Args.String
+          @name='fit'
+          @value={{this.fit}}
+          @options={{this.fitOptions}}
+          @defaultValue='cover'
+          @onInput={{this.setFit}}
+        />
+        <Args.Bool
+          @name='preview'
+          @defaultValue={{false}}
+          @value={{this.preview}}
+          @description='Click or Enter opens the image larger in a dialog.'
+          @onInput={{this.setPreview}}
+        />
+        <Args.Bool
+          @name='broken source (demo)'
+          @value={{this.broken}}
+          @description='Swap in a source that fails to decode.'
+          @onInput={{this.setBroken}}
+        />
+        <Args.Bool
+          @name='fallback'
+          @value={{this.useFallback}}
+          @description='A second source tried once when src fails.'
+          @onInput={{this.setUseFallback}}
+        />
+        <Args.Number @name='width' @description='Intrinsic width; with height, the default ratio.' />
+        <Args.Number @name='height' />
+        <Args.String @name='loading' @defaultValue='lazy' />
+        <Args.String @name='previewLabel' @defaultValue='View larger' />
+        <Args.String @name='radius' />
+        <Args.Bool @name='bordered' @defaultValue={{false}} />
+        <Args.Action @name='onStatusChange' @description='loading, loaded or error, whenever it changes.' />
+        <Args.Yield @name='fallback' @description='What shows when every source has failed.' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .img-demo {
+        max-inline-size: 26rem;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_IMAGE: Record<string, unknown> = {
+  Image: ImageUsage,
+};

package/bundled-realms/pretui/components/in-view.gts

@@ -0,0 +1,245 @@
+// Pretui — InView: entrance choreography that fires when content scrolls into view.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { modifier } from 'ember-modifier';
+import { cssNumber } from '../pretui-css';
+import { presetTransform, seconds } from '../internal/motion-core';
+import type { MotionPreset } from '../internal/motion-core';
+
+// ── inViewport (modifier) ────────────────────────────────────────────────
+// Measurement-only IntersectionObserver: it sets data-inview on its element
+// and nothing else. Exported on its own because any component can gate its
+// own CSS on the attribute — the observer is the reusable part, not the
+// wrapper.
+//
+// Note the polarity, which is the accessibility fix over every upstream: the
+// element's RESTING style is the visible end state, and the modifier writes
+// data-inview="false" at install to opt into the hidden pre-state. With no
+// JS, no IntersectionObserver, or in a prerender, the attribute never
+// appears and the content is simply visible. motion-primitives sets
+// `opacity: 0` in React state, so a failed hydration leaves the page blank.
+const ROOT_MARGIN_TOKEN = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:px|%)$/;
+
+export function normalizeRootMargin(value: unknown): string {
+  if (typeof value !== 'string') return '0px';
+  let tokens = value.trim().split(/\s+/);
+  if (
+    tokens.length < 1 ||
+    tokens.length > 4 ||
+    tokens.some((token) => !ROOT_MARGIN_TOKEN.test(token))
+  ) {
+    return '0px';
+  }
+  return tokens.join(' ');
+}
+
+/** `onChange` hears every enter (and, unless `once`, every exit); `enabled`
+ * false leaves the element unobserved. */
+export const inViewport = modifier(
+  (
+    el: HTMLElement,
+    [threshold, rootMargin, once]: [number, string, boolean],
+    {
+      onChange,
+      enabled = true,
+    }: { onChange?: (inView: boolean) => void; enabled?: boolean },
+  ) => {
+    if (!enabled || typeof IntersectionObserver === 'undefined') return;
+    el.setAttribute('data-inview', 'false');
+    let observer = new IntersectionObserver(
+      (entries) => {
+        for (let entry of entries) {
+          if (entry.isIntersecting) {
+            el.setAttribute('data-inview', 'true');
+            if (once) observer.disconnect();
+            onChange?.(true);
+          } else if (!once) {
+            el.setAttribute('data-inview', 'false');
+            onChange?.(false);
+          }
+        }
+      },
+      { threshold, rootMargin: normalizeRootMargin(rootMargin) },
+    );
+    observer.observe(el);
+    return () => observer.disconnect();
+  },
+);
+
+interface InViewCell {
+  item: unknown;
+  index: number;
+  style: ReturnType<typeof htmlSafe>;
+}
+
+// ── InView ───────────────────────────────────────────────────────────────
+// Entrance choreography that fires when content scrolls into view.
+//
+// Ported from motion-primitives' <InView> and react-bits'
+// AnimatedContent / ScrollReveal. Upstream drives every reveal through the
+// motion engine's variants and a per-element JS animation; the stagger is a
+// `delayChildren` value fed into that engine.
+//
+// Better than the inspiration, three ways:
+//   1. No engine. The observer only flips an attribute; the reveal is a CSS
+//      transition, so N revealing children cost one style recalc, not N
+//      animation instances.
+//   2. Resting state is the END state (see inViewport above) — the still
+//      frame is correct content, not a blank box (Law 8), and a
+//      no-JavaScript render is readable.
+//   3. Reduced motion gets the content immediately and unconditionally: the
+//      hidden pre-state is neutralised, not merely un-animated, so a
+//      reduced-motion reader can never be left staring at opacity 0.
+// The stagger is precomputed as `index * --stagger` in a transition-delay —
+// no timers, no sequencing loop.
+//
+// Dropped upstream surface: `viewOptions.root` (an arbitrary scroll root
+// element is not addressable from a template without a ref plumbing surface;
+// use @rootMargin), and per-child custom variant objects (the preset table
+// plus the CSS custom-property channel covers it).
+export interface InViewSignature {
+  Args: {
+    /** entrance preset: fade | rise | fall | scale | slide */
+    enter?: MotionPreset;
+    /** reveal once and disconnect the observer (default true); false re-hides on exit */
+    once?: boolean;
+    /** IntersectionObserver threshold, 0–1 (default 0.2) */
+    threshold?: number;
+    /** IntersectionObserver rootMargin, e.g. '0px 0px -12% 0px' to trip early */
+    rootMargin?: string;
+    /** seconds between consecutive children — only meaningful with @items */
+    stagger?: number;
+    /** transition duration in seconds */
+    duration?: number;
+    /** seconds before the first child moves */
+    delay?: number;
+    /** travel distance in px for rise / fall / slide */
+    distance?: number;
+    /** start scale for the scale preset (0–1) */
+    scale?: number;
+    /** pass a list to stagger it; each entry renders through the :item block. Omit for a single-block reveal. */
+    items?: unknown[];
+  };
+  Blocks: {
+    /* eslint-disable @typescript-eslint/no-explicit-any -- @items is an
+       opaque list (the structure-extras Grid precedent); the block yields
+       each entry back untyped alongside its index */
+    default: [];
+    item: [any, number];
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+  };
+  Element: HTMLDivElement;
+}
+
+export class InView extends Component<InViewSignature> {
+  get once(): boolean {
+    return this.args.once ?? true;
+  }
+  get threshold(): number {
+    return this.args.threshold ?? 0.2;
+  }
+  get rootMargin(): string {
+    return normalizeRootMargin(this.args.rootMargin);
+  }
+  get mode(): 'items' | 'block' {
+    return this.args.items ? 'items' : 'block';
+  }
+  get style(): ReturnType<typeof htmlSafe> {
+    let bits = [
+      `--pretui-inview-from: ${presetTransform(this.args.enter ?? 'rise')}`,
+      `--pretui-inview-duration: ${seconds(this.args.duration, 0.48)}`,
+      `--pretui-inview-delay: ${(this.args.delay ?? 0).toFixed(3)}s`,
+      `--pretui-inview-stagger: ${(this.args.stagger ?? 0).toFixed(3)}s`,
+    ];
+    {
+      let n = cssNumber(this.args.distance, -10000, 10000);
+      if (n !== undefined) {
+        bits.push(`--pretui-motion-distance: ${n}px`);
+      }
+    }
+    {
+      let n = cssNumber(this.args.scale, 0, 100);
+      if (n !== undefined) {
+        bits.push(`--pretui-motion-scale: ${n}`);
+      }
+    }
+    return htmlSafe(bits.join('; '));
+  }
+  get cells(): InViewCell[] {
+    return (this.args.items ?? []).map((item, index) => ({
+      item,
+      index,
+      style: htmlSafe(`--pretui-inview-i: ${index}`),
+    }));
+  }
+  <template>
+    <div
+      class='pretui-inview'
+      data-mode={{this.mode}}
+      style={{this.style}}
+      data-test-pretui-inview
+      {{inViewport this.threshold this.rootMargin this.once}}
+      ...attributes
+    >
+      {{#if @items}}
+        {{#each this.cells key='index' as |cell|}}
+          <div class='pretui-inview-item' style={{cell.style}}>
+            {{yield cell.item cell.index to='item'}}
+          </div>
+        {{/each}}
+      {{else}}
+        {{yield}}
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-inview {
+          display: var(--pretui-inview-display, block);
+        }
+        .pretui-inview-item {
+          display: var(--pretui-inview-item-display, block);
+        }
+        /* The revealed state is the plain, unqualified rule — see the polarity
+           note on inViewport. Only the [data-inview='false'] rules hide, and
+           they only exist once the observer is live. */
+        .pretui-inview[data-mode='block'],
+        .pretui-inview-item {
+          transition-property: opacity, transform;
+          transition-duration: var(--pretui-inview-duration, 480ms);
+          transition-timing-function: var(
+            --pretui-ease-out,
+            cubic-bezier(0.16, 1, 0.3, 1)
+          );
+        }
+        .pretui-inview[data-mode='block'] {
+          transition-delay: var(--pretui-inview-delay, 0s);
+        }
+        .pretui-inview-item {
+          transition-delay: calc(
+            var(--pretui-inview-delay, 0s) + var(--pretui-inview-i, 0) *
+              var(--pretui-inview-stagger, 0s)
+          );
+        }
+        .pretui-inview[data-mode='block'][data-inview='false'],
+        .pretui-inview[data-inview='false'] .pretui-inview-item {
+          opacity: 0;
+          transform: var(--pretui-inview-from, none);
+          transition-delay: 0s;
+        }
+        /* Reduced motion neutralises the pre-state itself, not just the
+           transition — the content is there on the first frame. */
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-inview[data-mode='block'][data-inview='false'],
+          .pretui-inview[data-inview='false'] .pretui-inview-item {
+            opacity: 1;
+            transform: none;
+          }
+          .pretui-inview[data-mode='block'],
+          .pretui-inview-item {
+            transition-property: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/in-view.md

@@ -0,0 +1,53 @@
+## What it is
+
+Entrance choreography that fires when content scrolls into view — a fade, a rise, a scale — optionally staggered across a list.
+
+Use it to give a long page some rhythm. If you want to _defer the work_ rather than animate the arrival, that is **Defer**, and the two are often wanted together.
+
+## The contract
+
+```
+@enter?      — preset: fade | rise | fall | scale | slide
+@once?       — reveal once and disconnect the observer. Default true
+@threshold?  — IntersectionObserver threshold, 0–1. Default 0.2
+@rootMargin? — IntersectionObserver rootMargin, e.g. '0px 0px -12% 0px' to trip early
+@stagger?    — seconds between consecutive children; only meaningful with @items
+@duration?   — transition duration in seconds
+@delay?      — seconds before the first child moves
+@distance?   — travel distance in px for rise / fall / slide
+@scale?      — start scale for the scale preset, 0–1
+@items?      — a list to stagger; each entry renders through <:item>
+
+<:default> — a single-block reveal
+<:item>    — receives each entry and its index
+```
+
+**An IntersectionObserver inside a modifier flips one attribute; everything else is CSS.** The reveal is a transition and the stagger is a precomputed index × interval delay — no engine, no timers, and one style recalculation for the whole list rather than one per child.
+
+**`@once` defaults to true and disconnects the observer** once revealed. Set it false only when you want content to re-hide on exit, which costs a live observer for the page's lifetime.
+
+**The resting style is the finished state.** A still frame, a prerender, or a render with no JavaScript all show real content rather than a blank box. This is the property that makes the component safe to use above the fold.
+
+## Prior art
+
+**motion-primitives' InView** and **react-bits' AnimatedContent/ScrollReveal**.
+
+Where Pretui is better: **the unrevealed state is not the default state.** Most scroll-reveal implementations start elements at `opacity: 0` in CSS and rely on JavaScript to turn them on, which means a prerender, a crawler, or a failed script leaves a blank page. Here the finished state is the base and the observer only adds choreography. The stagger is also computed once as delays rather than driven by a timeline.
+
+Where it is thinner: five presets and no custom keyframes, no exit choreography distinct from the entrance, no per-item override, and no scroll-linked progress — the reveal is a threshold trip, not a scrubbed animation. `@items` yields untyped entries, so the item block is not type-safe.
+
+## Accessibility
+
+- **Content is present and announced before it is revealed.** Because the base style is the finished state, assistive technology never waits on the animation, and the text is in the accessibility tree from first paint.
+- **Reduced motion should collapse every preset to its end state**, which costs nothing here since that state is already the base.
+- **`@once={{false}}` re-hides content on exit**, which is the one configuration to be careful with: content that disappears when scrolled past can surprise a screen-magnifier user working at the edge of the viewport.
+- **The reveal conveys nothing.** Nothing about state, order or importance should depend on it.
+- **A stagger long enough to notice is long enough to annoy.** The delay accumulates across `@items`, so a long list with a generous `@stagger` leaves the last item moving well after the reader arrived at it.
+
+## Theming
+
+`--pretui-inview-duration` (from `@duration`), `--pretui-inview-delay` (from `@delay`), `--pretui-inview-stagger` (from `@stagger`), `--pretui-inview-i` (each child's index), `--pretui-inview-from` (the preset's starting transform), `--pretui-inview-display` and `--pretui-inview-item-display`, over the shared `--pretui-motion-distance` and `--pretui-motion-scale`.
+
+Sharing the distance and scale tokens with the rest of the motion module is what keeps entrances consistent: a theme that shortens travel shortens it for every entrance in the product at once, rather than per call site.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.