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

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

@@ -0,0 +1,141 @@
+// Pretui — Marquee: a continuously scrolling strip that pauses on hover and reduced motion.
+import Component from '@glimmer/component';
+import { modifier } from 'ember-modifier';
+
+// ── Marquee — TRANSCRIBED from fancy SimpleMarquee ───────────────────────
+// The original runs a useAnimationFrame loop over motion values with
+// scroll-velocity coupling, drag inertia, hover slowdown springs, and a
+// configurable easing function. This transcription keeps the one job —
+// a seamless drifting strip — as a pure CSS keyframe loop (TIMER LAW):
+// content is rendered twice (second copy aria-hidden), the track
+// translates 0 → -50%, and the loop is seamless because each copy carries
+// its own trailing gap (--pretui-marquee-gap rides INSIDE the copy, so
+// half the track is exactly one copy). @speed is honest px/s: a modifier
+// measures one copy's width (ResizeObserver, disconnected on cleanup —
+// measurement only, never a timer) and sets duration = width / speed.
+// Skipped from the original, deliberately: scroll-velocity direction
+// coupling, drag/inertia, easing functions, vertical directions, repeat
+// count (fixed at 2), and hover SLOWDOWN — @pauseOnHover pauses outright
+// via animation-play-state instead. Reduced motion: the animation is
+// removed and the strip becomes a static overflow-x row (mask lifted so
+// the edges are honest scroll edges).
+
+export interface MarqueeSignature {
+  Args: {
+    /** drift speed in px/s — default 60 */
+    speed?: number;
+    /** 'left' (default) drifts content leftward */
+    direction?: 'left' | 'right';
+    /** pause the loop while the pointer is over the strip */
+    pauseOnHover?: boolean;
+  };
+  Blocks: {
+    /** strip content — rendered twice for the seamless loop */
+    default: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Marquee extends Component<MarqueeSignature> {
+  get direction(): 'left' | 'right' {
+    return this.args.direction ?? 'left';
+  }
+  // Measures one copy (half the track) and converts @speed px/s into the
+  // CSS animation duration. ResizeObserver re-measures when content
+  // reflows; it is disconnected in the modifier's cleanup.
+  trackSpeed = modifier((track: HTMLElement, [speed]: [number | undefined]) => {
+    let apply = () => {
+      let half = track.scrollWidth / 2;
+      let pxPerSecond = Math.max(1, speed ?? 60);
+      track.style.setProperty(
+        '--pretui-marquee-duration',
+        `${Math.max(0.5, half / pxPerSecond).toFixed(2)}s`,
+      );
+    };
+    apply();
+    let observer = new ResizeObserver(apply);
+    observer.observe(track);
+    return () => observer.disconnect();
+  });
+  <template>
+    <div
+      class='pretui-marquee'
+      data-direction={{this.direction}}
+      data-pause-on-hover={{if @pauseOnHover 'true'}}
+      data-test-pretui-marquee
+      ...attributes
+    >
+      <div class='pretui-marquee-track' {{this.trackSpeed @speed}}>
+        <div class='pretui-marquee-copy'>{{yield}}</div>
+        <div class='pretui-marquee-copy' aria-hidden='true'>{{yield}}</div>
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-marquee {
+          overflow: hidden;
+          -webkit-mask-image: linear-gradient(
+            to right,
+            transparent,
+            #000 8%,
+            #000 92%,
+            transparent
+          );
+          mask-image: linear-gradient(
+            to right,
+            transparent,
+            #000 8%,
+            #000 92%,
+            transparent
+          );
+        }
+        .pretui-marquee-track {
+          display: flex;
+          width: max-content;
+          min-width: 100%;
+          animation: pretui-marquee-drift
+            var(--pretui-marquee-duration, 20s)
+            linear
+            infinite;
+        }
+        .pretui-marquee[data-direction='right'] .pretui-marquee-track {
+          animation-direction: reverse;
+        }
+        .pretui-marquee[data-pause-on-hover='true']:hover
+          .pretui-marquee-track {
+          animation-play-state: paused;
+        }
+        /* Each copy carries the inter-item gap AND a matching trailing gap,
+           so copy width includes its seam spacing and -50% lands exactly on
+           the second copy's start. */
+        .pretui-marquee-copy {
+          display: flex;
+          flex: none;
+          min-width: 50%;
+          align-items: center;
+          gap: var(--pretui-marquee-gap, var(--space-5, 16px));
+          padding-inline-end: var(--pretui-marquee-gap, var(--space-5, 16px));
+        }
+        @keyframes pretui-marquee-drift {
+          from {
+            transform: translateX(0);
+          }
+          to {
+            transform: translateX(-50%);
+          }
+        }
+        /* Static overflow row: no loop, honest scroll edges (mask lifted). */
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-marquee {
+            overflow-x: auto;
+            -webkit-mask-image: none;
+            mask-image: none;
+          }
+          .pretui-marquee-track {
+            animation: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,43 @@
+## What it is
+
+A seamless drifting strip of repeated content: logos, tags, a ticker of names. The content is rendered twice and the track loops, so the join is invisible.
+
+## The contract
+
+```
+@speed?        — drift speed in px/s. Default 60
+@direction?    — 'left' (default) | 'right'
+@pauseOnHover? — pause the loop while the pointer is over the strip
+
+<:default> — strip content, rendered twice for the seamless loop
+```
+
+**`@speed` is a rate in pixels per second, not a duration.** That is the difference that makes a marquee usable: a strip of three logos and a strip of thirty drift at the same visual pace, where a fixed duration would make the long one a blur.
+
+**The content is rendered twice**, and the second copy is `aria-hidden`. The loop translates by exactly one copy's width, so the wrap is seamless without measuring anything.
+
+**`@pauseOnHover` is a CSS `:hover` rule**, not a listener — no pointer bindings anywhere.
+
+## Prior art
+
+**fancy's SimpleMarquee** and **AlongSvgPath**, and **motion-primitives' InfiniteSlider**.
+
+Where Pretui is better: the rate is content-independent, and the duplicate copy is hidden from assistive technology rather than being announced twice — which is the defect most marquee implementations ship with, because duplicating the DOM is the easy part and remembering what it does to a screen reader is not.
+
+Where it is thinner: horizontal only, no vertical marquee, no path-following variant (fancy's AlongSvgPath), no gradient mask at the edges, and no pause on focus — only on hover, which means a keyboard user tabbing into a link inside the strip is chasing a moving target.
+
+## Accessibility
+
+- **The second copy is `aria-hidden`**, so the content is announced once rather than twice.
+- **Motion that never stops is a WCAG 2.2.2 problem.** A marquee running for more than five seconds needs a way to pause it, and `@pauseOnHover` is not that: it is pointer-only and it does not persist. If the strip carries anything a reader needs, this component does not currently give them a way to stop it.
+- **Focusable content inside a moving strip is hard to use.** There is no pause on focus, so tabbing to a link in a marquee moves it under the reader. Prefer non-interactive content in the strip.
+- **Reduced motion should stop the drift.** The resting state is the strip at its start position, which is a complete, readable first copy.
+- **Nothing is conveyed by the movement.** It is texture.
+
+## Theming
+
+`--pretui-marquee-duration` (derived from `@speed` and the content's width) and `--pretui-marquee-gap` (the space between repeats).
+
+There are no color tokens — the strip inherits everything from context, which is what lets a marquee of logos sit on any surface without restyling. The gap token is the one thing a theme tunes, and it is what keeps a logo strip's rhythm consistent with the spacing scale around it.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,116 @@
+// Pretui — Marquee usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Marquee } from './marquee';
+
+// ── Marquee ← fancy SimpleMarquee ────────────────────────────────────────
+// Live knobs: speed (the original's baseVelocity, honest px/s),
+// direction (left/right only — the vertical pair is not transcribed),
+// pauseOnHover (replaces the original's slowdownOnHover + slowDownFactor
+// spring). Dropped surface: easing fn, scroll-velocity coupling
+// (useScrollVelocity/scrollAwareDirection/scrollSpringConfig), drag
+// surface (draggable/dragSensitivity/dragVelocityDecay/dragAngle),
+// repeat count (fixed at two copies).
+const MARQUEE_DIRECTIONS = ['left', 'right'];
+
+const MARQUEE_ITEMS = [
+  'Marquee',
+  'Comparison',
+  'StackingCards',
+  'Dock',
+  'Panel',
+  'Accordion',
+  'SplitPanes',
+  'Board',
+];
+
+class MarqueeUsage extends Component {
+  directionOptions = MARQUEE_DIRECTIONS;
+  items = MARQUEE_ITEMS;
+  @tracked speed = 60;
+  @tracked direction = 'left';
+  @tracked pauseOnHover = true;
+  setSpeed = (v: number | null) => (this.speed = v ?? 60);
+  setDirection = (v: string) => (this.direction = v);
+  setPauseOnHover = (v: boolean) => (this.pauseOnHover = v);
+  get directionVal() {
+    return this.direction as 'left' | 'right';
+  }
+  get usage() {
+    let bits = [`@speed={{${this.speed}}}`];
+    if (this.direction !== 'left') bits.push(`@direction='${this.direction}'`);
+    if (this.pauseOnHover) bits.push('@pauseOnHover={{true}}');
+    return `<Marquee ${bits.join(' ')}>\n  <span>…strip content…</span>\n</Marquee>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Marquee'
+      @description='Seamless drifting strip — content is rendered twice and a pure CSS keyframe loop translates the track half its width, so the seam never shows. Speed is honest px/s (a ResizeObserver measures the copy and computes the duration; the loop itself is CSS-only per the timer law). Gradient masks fade both edges. Under prefers-reduced-motion the loop stops and the strip becomes a static overflow row. Transcribed from fancy SimpleMarquee; the rAF motion-value engine (scroll coupling, drag inertia, easing) is deliberately not ported.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Marquee
+          @speed={{this.speed}}
+          @direction={{this.directionVal}}
+          @pauseOnHover={{this.pauseOnHover}}
+        >
+          {{#each this.items as |item|}}
+            <span class='marquee-chip'>{{item}}</span>
+          {{/each}}
+        </Marquee>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='speed'
+          @defaultValue={{60}}
+          @value={{this.speed}}
+          @min={{10}}
+          @max={{240}}
+          @step={{10}}
+          @description='Drift speed in px per second — converted to the CSS animation duration from the measured copy width.'
+          @onInput={{this.setSpeed}}
+        />
+        <Args.String
+          @name='direction'
+          @defaultValue='left'
+          @value={{this.direction}}
+          @options={{this.directionOptions}}
+          @description="Drift direction. 'right' reverses the keyframe loop; the vertical directions of the original are not transcribed."
+          @onInput={{this.setDirection}}
+        />
+        <Args.Bool
+          @name='pauseOnHover'
+          @defaultValue={{false}}
+          @value={{this.pauseOnHover}}
+          @description="Pauses the loop while hovered (animation-play-state) — replaces the original's spring-smoothed slowdown."
+          @onInput={{this.setPauseOnHover}}
+        />
+        <Args.Yield
+          @description='Strip content — rendered twice for the seamless loop (second copy aria-hidden). Inter-item gap rides --pretui-marquee-gap so the seam spacing stays even.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .marquee-chip {
+        flex: none;
+        padding: 4px 12px;
+        border-radius: 999px;
+        background: var(--inset, var(--boxel-100));
+        box-shadow: 0 0 0 1px var(--border);
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        font-weight: 500;
+        letter-spacing: var(--track-eyebrow, 0.08em);
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+        white-space: nowrap;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_MARQUEE: Record<string, unknown> = {
+  Marquee: MarqueeUsage,
+};

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

@@ -0,0 +1,95 @@
+// Pretui — Masonry: native CSS multi-column masonry: no measurement, no JavaScript.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { cssDeclaration, cssNumber, cssStyleFrom } from '../pretui-css';
+
+// ── Masonry ──────────────────────────────────────────────────────────────
+// Staggered multi-column layout with no measuring engine at all.
+//
+// READING ORDER — the correctness trap, stated plainly rather than
+// discovered later. This uses native CSS multi-column, so:
+//   • DOM order, keyboard order, and screen-reader order are the order you
+//     pass @items. Always. That is the accessible order and it never moves.
+//   • The VISUAL order is column-major: item 1 is top-left, and the next item
+//     is BELOW it, not to its right; a column fills to the bottom before the
+//     next column starts.
+// So Masonry is right for a wall of peers (a moodboard, a gallery, tasting
+// notes) and WRONG for ranked content where "first" must read top-left then
+// rightwards — for that use <Grid>, which is row-major. A JS masonry engine
+// buys row-major fill at the price of measuring every child on every resize
+// AND a DOM whose order no longer matches what anyone sees; this component
+// refuses that trade. Under a narrow container it collapses to one column,
+// where column-major and row-major are the same thing.
+//
+// Dropped from the JS originals: per-item measured placement, animated
+// re-flow on resize, and infinite-scroll integration (that is <Feed>'s job).
+
+export interface MasonrySignature<T = unknown> {
+  Args: {
+    /** the items to lay out — rendered through the <:item> block, in the
+     * caller's own row type */
+    items: readonly T[];
+    /** maximum number of columns (default 3); the browser uses fewer when
+     * @min would not fit */
+    columns?: number;
+    /** minimum column width as a CSS length (default 16rem) */
+    min?: string;
+    /** gutter in px (default 14) — also settable as --pretui-masonry-gap */
+    gap?: number;
+  };
+  Blocks: {
+    /** one cell — receives the item and its 0-based index */
+    item: [item: T, index: number];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Masonry<T = unknown> extends Component<MasonrySignature<T>> {
+  get style(): ReturnType<typeof htmlSafe> | undefined {
+    let columns = cssNumber(this.args.columns, 1, 64);
+    let gap = cssNumber(this.args.gap, 0, 512);
+    return cssStyleFrom([
+      columns === undefined
+        ? undefined
+        : `--pretui-masonry-columns: ${Math.floor(columns)}`,
+      cssDeclaration('--pretui-masonry-min', this.args.min),
+      gap === undefined ? undefined : `--pretui-masonry-gap: ${gap}px`,
+    ]);
+  }
+
+  <template>
+    <div
+      class='pretui-masonry'
+      style={{this.style}}
+      data-test-pretui-masonry
+      ...attributes
+    >
+      <div class='pretui-masonry-columns'>
+        {{#each @items key='@index' as |item index|}}
+          <div class='pretui-masonry-cell'>{{yield item index to='item'}}</div>
+        {{/each}}
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-masonry {
+          container-type: inline-size;
+          min-width: 0;
+        }
+        .pretui-masonry-columns {
+          columns: var(--pretui-masonry-min, 16rem)
+            var(--pretui-masonry-columns, 3);
+          column-gap: var(--pretui-masonry-gap, 14px);
+        }
+        .pretui-masonry-cell {
+          /* multicol has no row-gap: the cell's own margin is the gutter */
+          margin: 0 0 var(--pretui-masonry-gap, 14px);
+          break-inside: avoid;
+          /* Safari still needs the legacy alias */
+          -webkit-column-break-inside: avoid;
+          min-width: 0;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,59 @@
+## What it is
+
+A staggered multi-column wall of items of varying heights — a moodboard, a gallery, tasting notes, a wall of quotes. Use it when the items are **peers** and their order does not rank them. If order matters and "first" must read top-left then rightwards, use **Grid**, which is row-major. If items stream in over time, **Feed**.
+
+## The contract
+
+```
+@items: readonly T[]   (required)
+@columns? (default 3), @min? (default '16rem'), @gap? (default 14)
+<:item as |item, index|>
+```
+
+`@columns` is a _maximum_; the browser uses fewer when `@min` will not fit. `@gap` is also settable as `--pretui-masonry-gap`.
+
+**The reading-order trap, stated up front rather than discovered later.** This is native CSS multi-column, so:
+
+- **DOM order, keyboard order and screen-reader order are the order you pass `@items`.** Always. That is the accessible order and it never moves.
+- **The visual order is column-major.** Item 1 is top-left and item 2 is _below_ it, not to its right; a column fills to the bottom before the next begins.
+
+So Masonry is right for a wall of peers and **wrong for ranked content**. When the container is narrower than two `@min` columns it collapses to one column, where column-major and row-major are the same thing.
+
+## Prior art
+
+**react-masonry-css** and the JS masonry engines (Masonry.js, MUI's `Masonry`) all do the same thing: measure every child, compute placements, and re-lay-out on resize. That buys row-major fill — items read left-to-right in visual order — at two prices: measurement jank on every resize, and **a DOM whose order no longer matches what anyone sees**.
+
+Pretui refuses that trade, and the refusal is the design: **zero measurement, zero JS, and the reading order is stated out loud instead of being a surprise.** The component is a `column-count` container and a `{{#each}}`.
+
+That is genuinely better for accessibility and performance, and genuinely worse for one thing: you cannot have row-major fill. The honest framing is that this is a _different_ component from a JS masonry, not a cheaper one, and choosing it means accepting column-major reading. **Grid** is the row-major option.
+
+Also dropped from the JS originals: animated reflow on resize, and infinite-scroll integration (that is **Feed**'s job).
+
+One implementation note worth flagging as a weakness: `{{#each @items key='@index'}}`. Keying by index rather than by a stable id means a reordered or filtered list rebuilds every cell's DOM. For a static moodboard that is fine; for a filterable gallery it discards image decode state and any in-cell interaction. **DataGrid** has the same issue and it is worth fixing in both.
+
+## Accessibility
+
+No pattern governs it; this is layout, and the relevant criteria are WCAG **1.3.2 Meaningful Sequence**, **2.4.3 Focus Order** and **1.4.10 Reflow**.
+
+The central fact is the one above, and it cuts both ways:
+
+- **1.3.2 and 2.4.3 are satisfied by construction.** DOM order is the source order, and nothing reorders it — no `order`, no `grid-row`, no absolute placement. A JS masonry that achieves row-major _visual_ order while leaving DOM order untouched creates exactly the mismatch these criteria prohibit; this component cannot.
+- **But visual and reading order still differ**, because column-major reading is not how most sighted users scan a wall. That is not a WCAG failure — the criteria are about _programmatic_ sequence — but it does mean a sighted user and a screen-reader user encounter the items in different sequences. For peers that is harmless. For anything ranked it is misleading, which is why the component says so.
+
+Other gaps:
+
+- **The container has no list semantics and no accessible name.** No `role="list"`, no `aria-label`, no count. A screen-reader user encounters a run of cells with no indication that they belong together or how many there are. Wrapping in a labelled `role="list"` at the call site is worth doing.
+- **Cells are plain `<div>`s.** Everything about a cell's accessibility — its name, whether it is interactive, whether it is a single click target — belongs to `<:item>`. The usual card-grid failure applies: do not put a click handler on the cell _and_ interactive content inside it.
+- **A cell never splits across columns**: every cell sets `break-inside: avoid`.
+- **Reflow**: `@min` governs when columns drop, and collapsing to one column at narrow widths satisfies **1.4.10** cleanly.
+- Nothing is focusable at the container level, correctly.
+
+## Theming
+
+`--pretui-masonry-columns`, `--pretui-masonry-min` and `--pretui-masonry-gap` — all three settable as tokens _or_ as args (the args write the tokens inline). That is the cleanest theming surface in the structure territory: a theme can set a house masonry rhythm without any call site changing.
+
+The component paints nothing else — no background, no border, no cell chrome. All visual weight belongs to what you yield.
+
+Note the arg-writes-token pattern means a call-site `@gap` beats an ancestor's `--pretui-masonry-gap`, since inline styles win. A theme setting the token gets the default for every Masonry that does not override it, which is the intended layering.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.