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

package/bundled-realms/pretui/components/cursor-trail.gts

@@ -0,0 +1,221 @@
+// Pretui — CursorTrail: a trail of dots that follows the pointer.
+import Component from '@glimmer/component';
+import { hash } from '@ember/helper';
+import { htmlSafe } from '@ember/template';
+// Caller-supplied hues are strings and must clear the kit-wide allowlist
+// before they reach an inline style — see pretui-css.gts.
+import { cssDeclaration, cssNumber } from '../pretui-css';
+import { pick, seedFrom } from '../examples';
+import { pointerField } from '../internal/motion-pointer';
+
+// ── CursorTrail ──────────────────────────────────────────────────────────
+// TRANSCRIBED from motion-primitives Cursor + react-bits Blob/Ghost/
+// Pixel/ImageTrail + fancy PixelTrail/ImageTrail.
+//
+// Upstream engines: motion-primitives springs one cursor node's x/y
+// through useSpring on a document-level mousemove; react-bits' trails run
+// a rAF loop over an array of past positions (some of them over a WebGL
+// canvas); fancy's PixelTrail rAF-decays a grid of cell timestamps.
+// Every one of them fades to literally nothing when the pointer leaves,
+// and every one of them binds mousemove so touch gets no trail at all.
+//
+// This version: `pointerField` writes --pretui-px/py; the dots all target
+// the SAME point and differ only in transition-duration, so dot i lags
+// further behind under continuous retargeting — that graduated duration
+// is the whole trail engine (see the header note on why transition-delay
+// cannot do this job). Differences from the springs: no overshoot or
+// wobble, and no per-dot physics — the fan is a pure ease-out ramp.
+//
+// Resting state (Law 8): the dots do not fade out. They converge on the
+// last position, and because each is smaller and fainter than the last,
+// the stack renders as a concentric bullseye — a legible attention marker
+// in a still frame. Before any pointer arrives it parks at @restX/@restY.
+// Encoding (Law 5): that marker is also the FOCUS marker — tab through the
+// field's content and the bullseye travels to the focused child, so the
+// trail states "here is the reader's attention point" on both input
+// paths. Deterministic per-dot size jitter comes from seedFrom/pick.
+const TRAIL_JITTER = [0, 0.05, -0.04, 0.03, -0.06, 0.02, -0.02, 0.06];
+
+interface TrailDot {
+  index: number;
+  depth: number;
+  style: ReturnType<typeof htmlSafe>;
+}
+
+export interface CursorTrailSignature {
+  Args: {
+    /** number of trailing marks, 1–24 — default 6 */
+    count?: number;
+    /** diameter of the head mark in px — default 14 */
+    size?: number;
+    /** seconds the LAST mark takes to reach the pointer; the fan is
+     * linear from ~0.05s at the head to this — default 0.42 */
+    lag?: number;
+    /** any CSS color for the marks — defaults to the --primary token */
+    hue?: string;
+    /** mark geometry: 'dot' (filled), 'ring' (hairline), 'square' */
+    shape?: 'dot' | 'ring' | 'square';
+    /** seed string for the deterministic per-mark size jitter; omit for a
+     * perfectly even fan (no Math.random anywhere) */
+    seed?: string;
+    /** move the marker to a focused child on focusin — default true; this
+     * is the component's keyboard path, turn it off only if the field has
+     * its own focus indicator */
+    followFocus?: boolean;
+    /** resting x origin as a fraction of the field's width — default 0.5 */
+    restX?: number;
+    /** resting y origin as a fraction of the field's height — default 0.5 */
+    restY?: number;
+  };
+  Blocks: {
+    /** the live field — content the trail rides over, fully interactive */
+    default: [];
+    /** replaces the default mark; yields { index, depth } where depth is
+     * 0 at the head and 1 at the tail */
+    mark: [{ index: number; depth: number }];
+  };
+  Element: HTMLDivElement;
+}
+
+export class CursorTrail extends Component<CursorTrailSignature> {
+  get count(): number {
+    let n = Math.round(this.args.count ?? 6);
+    return Math.min(24, Math.max(1, Number.isFinite(n) ? n : 6));
+  }
+  get shape(): 'dot' | 'ring' | 'square' {
+    return this.args.shape ?? 'dot';
+  }
+  get followFocus(): boolean {
+    return this.args.followFocus ?? true;
+  }
+  get dots(): TrailDot[] {
+    let count = this.count;
+    let lag = this.args.lag ?? 0.42;
+    if (!(lag >= 0)) lag = 0.42;
+    let seed = this.args.seed ? seedFrom(this.args.seed) : 0;
+    let out: TrailDot[] = [];
+    for (let i = 0; i < count; i++) {
+      let t = count > 1 ? i / (count - 1) : 0;
+      let jitter = this.args.seed ? pick(seed, i, TRAIL_JITTER) : 0;
+      let scale = Math.max(0.12, (1 - 0.58 * t) * (1 + jitter));
+      let opacity = Math.max(0.08, 1 - 0.72 * t);
+      let dur = 0.05 + lag * t;
+      out.push({
+        index: i,
+        depth: t,
+        style: htmlSafe(
+          `--pretui-trail-scale: ${scale.toFixed(3)};` +
+            ` --pretui-trail-opacity: ${opacity.toFixed(3)};` +
+            ` --pretui-trail-dur: ${dur.toFixed(3)}s`,
+        ),
+      });
+    }
+    return out;
+  }
+  get rootStyle(): ReturnType<typeof htmlSafe> {
+    let bits: string[] = [];
+    {
+      let n = cssNumber(this.args.size, 0, 10000);
+      if (n !== undefined) {
+        bits.push(`--pretui-trail-size: ${n}px`);
+      }
+    }
+    let hue = cssDeclaration('--pretui-trail-hue', this.args.hue);
+    if (hue) bits.push(hue);
+    return htmlSafe(bits.join('; '));
+  }
+  <template>
+    <div
+      class='pretui-trail'
+      style={{this.rootStyle}}
+      data-test-pretui-cursor-trail
+      {{pointerField 0 this.followFocus @restX @restY}}
+      ...attributes
+    >
+      {{yield}}
+      <div class='pretui-trail-layer' aria-hidden='true'>
+        {{#each this.dots key='index' as |d|}}
+          <span
+            class='pretui-trail-mark'
+            data-shape={{this.shape}}
+            style={{d.style}}
+          >
+            {{#if (has-block 'mark')}}
+              {{yield (hash index=d.index depth=d.depth) to='mark'}}
+            {{/if}}
+          </span>
+        {{/each}}
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-trail {
+          position: relative;
+          border-radius: var(--pretui-trail-radius, var(--radius));
+        }
+        .pretui-trail-layer {
+          position: absolute;
+          inset: 0;
+          overflow: hidden;
+          border-radius: inherit;
+          pointer-events: none;
+        }
+        .pretui-trail-mark {
+          position: absolute;
+          top: 0;
+          left: 0;
+          display: block;
+          width: var(--pretui-trail-size, 14px);
+          height: var(--pretui-trail-size, 14px);
+          margin-top: calc(var(--pretui-trail-size, 14px) / -2);
+          margin-left: calc(var(--pretui-trail-size, 14px) / -2);
+          opacity: var(--pretui-trail-opacity, 1);
+          translate: var(--pretui-px, 0px) var(--pretui-py, 0px);
+          scale: var(--pretui-trail-scale, 1);
+          transition: translate var(--pretui-trail-dur, 0.2s)
+            cubic-bezier(0.22, 1, 0.36, 1);
+          will-change: translate;
+        }
+        .pretui-trail-mark[data-shape='dot'] {
+          border-radius: 999px;
+          background: color-mix(
+            in oklch,
+            var(--pretui-trail-hue, var(--primary)) 72%,
+            transparent
+          );
+          box-shadow: 0 0 0 1px
+            color-mix(
+              in oklch,
+              var(--pretui-trail-hue, var(--primary)) 26%,
+              transparent
+            );
+        }
+        .pretui-trail-mark[data-shape='ring'] {
+          border-radius: 999px;
+          background: transparent;
+          box-shadow: inset 0 0 0 2px
+            color-mix(
+              in oklch,
+              var(--pretui-trail-hue, var(--primary)) 78%,
+              transparent
+            );
+        }
+        .pretui-trail-mark[data-shape='square'] {
+          border-radius: 2px;
+          background: color-mix(
+            in oklch,
+            var(--pretui-trail-hue, var(--primary)) 68%,
+            transparent
+          );
+        }
+        /* end state under reduced motion: the marks track the pointer with
+           no lag, i.e. the resting bullseye, never a frozen midpoint */
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-trail-mark {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/cursor-trail.md

@@ -0,0 +1,56 @@
+## What it is
+
+A fan of marks trailing the pointer across a surface: a head mark at the pointer and a tail of progressively smaller, fainter, slower ones behind it.
+
+It is decoration with one saving grace — it has a keyboard path. The marker travels to a focused child, so the trail is not purely a pointer ornament.
+
+## The contract
+
+```
+@count?       — number of trailing marks, 1–24. Default 6
+@size?        — diameter of the head mark in px. Default 14
+@lag?         — seconds the LAST mark takes to reach the pointer; the fan is
+                linear from ~0.05s at the head to this. Default 0.42
+@hue?         — any CSS colour for the marks; defaults to --primary
+@shape?       — 'dot' (filled) | 'ring' (hairline) | 'square'
+@seed?        — seed for deterministic per-mark size jitter; omit for an even fan
+@followFocus? — move the marker to a focused child on focusin. Default true
+@restX?, @restY? — resting origin as a fraction of the field. Default 0.5 each
+
+<:default> — the live field the trail rides over; fully interactive
+<:mark>    — replaces the default mark; yields { index, depth }, depth 0 at head, 1 at tail
+```
+
+**The fan is built from one lag value, not from N.** Each mark's delay interpolates linearly from about 0.05s at the head to `@lag` at the tail, so the shape of the trail is one number rather than a table.
+
+**`@count` is clamped to 1–24.** A trail is an effect, not a particle system.
+
+**The jitter is seeded and deterministic — there is no `Math.random` anywhere.** Omit `@seed` for a perfectly even fan; supply one and the same seed produces the same fan on every render, which is what keeps a card screenshottable.
+
+**`<:mark>` yields depth as a 0–1 fraction**, so a custom mark can size, fade or rotate itself along the trail without knowing how many marks there are.
+
+**The trail rides in a hidden layer over live content**, which stays fully interactive — the marks never intercept a pointer event.
+
+## Prior art
+
+**motion-primitives'** cursor effects and the same family in react-bits.
+
+Where Pretui is better: **determinism and a focus path.** Upstream trails randomise their jitter per frame and are strictly pointer-driven; here the jitter is seeded and the marker follows focus, so the component means something to a keyboard user and produces the same picture twice.
+
+Where it is thinner: no spring physics, no velocity-reactive sizing, no collision or field effects, and a hard cap of 24 marks. The lag fan is linear, with no easing curve across the trail.
+
+## Accessibility
+
+- **The whole trail layer is hidden from assistive technology.** It is ornament; announcing a run of marks would be noise.
+- **`@followFocus` is the keyboard path**, and the reason to leave it on: turn it off only when the field's children have their own clear focus indicators, because otherwise you have removed the one non-pointer thing this component does.
+- **The marks never take a pointer event.** Content underneath stays fully operable, which is the correctness property that matters most for an overlay effect.
+- **This component conveys nothing.** There is no state, no affordance and no feedback in it — treat it as texture, and never as the only indication of anything.
+- **Reduced motion should drop the trail to its resting origin.** With `@restX` and `@restY` at their defaults, that is the centre of the field.
+
+## Theming
+
+`--pretui-trail-size` (from `@size`), `--pretui-trail-hue` (from `@hue`), `--pretui-trail-dur` (from `@lag`), `--pretui-trail-scale` and `--pretui-trail-opacity` (the per-mark falloff), `--pretui-trail-radius` (the shape), plus the shared `--pretui-px` / `--pretui-py` pointer channel.
+
+The falloff tokens are what make a theme able to change the trail's character without touching the component: a theme that wants a subtler trail lowers the opacity floor rather than reducing `@count` at every call site.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/cursor-trail.usage.gts

@@ -0,0 +1,218 @@
+// Pretui — CursorTrail usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { CursorTrail } from './cursor-trail';
+import { lots } from '../demo-motion-pointer';
+
+// ── CursorTrail ──────────────────────────────────────────────────────────
+const SHAPES = ['dot', 'ring', 'square'];
+
+// three deterministic lot lines, shared by the trail and spotlight fields
+
+class CursorTrailUsage extends Component {
+  @tracked count = 6;
+  @tracked size = 14;
+  @tracked lag = 0.42;
+  @tracked hue = '';
+  @tracked shape: 'dot' | 'ring' | 'square' = 'dot';
+  @tracked seed = 'wuyishan-spring';
+  @tracked followFocus = true;
+  @tracked restX = 0.5;
+  @tracked restY = 0.5;
+  shapeOptions = SHAPES;
+  setCount = (v: number | null) => (this.count = v ?? 6);
+  setSize = (v: number | null) => (this.size = v ?? 14);
+  setLag = (v: number | null) => (this.lag = v ?? 0.42);
+  setHue = (v: string) => (this.hue = v);
+  setShape = (v: string) => {
+    if (v === 'dot' || v === 'ring' || v === 'square') this.shape = v;
+  };
+  setSeed = (v: string) => (this.seed = v);
+  setFollowFocus = (v: boolean) => (this.followFocus = v);
+  setRestX = (v: number | null) => (this.restX = v ?? 0.5);
+  setRestY = (v: number | null) => (this.restY = v ?? 0.5);
+  get rows() {
+    return lots('cursor-trail');
+  }
+  get usage() {
+    let bits = [`@count={{${this.count}}}`, `@lag={{${this.lag}}}`];
+    if (this.size !== 14) bits.push(`@size={{${this.size}}}`);
+    if (this.shape !== 'dot') bits.push(`@shape='${this.shape}'`);
+    if (this.hue) bits.push(`@hue='${this.hue}'`);
+    if (this.seed) bits.push(`@seed='${this.seed}'`);
+    if (!this.followFocus) bits.push('@followFocus={{false}}');
+    return `<CursorTrail ${bits.join(' ')}>\n  … field content …\n</CursorTrail>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='CursorTrail'
+      @description='A pointer-following marker over a live field. Upstream trails (motion-primitives Cursor, react-bits Blob/Ghost/Pixel/ImageTrail, fancy PixelTrail) run a rAF spring loop and fade to nothing when the pointer leaves; this one is a graduated CSS transition-duration fan with no loop, and it does not fade — the marks converge into a concentric bullseye at the last position, which is a legible attention marker in a still frame. Law 5 encoding: that marker is also the focus marker — Tab through the field below and it travels to the focused control, so it reports the reader’s attention point on both the pointer and keyboard paths. Touch drags move it too. Honest limit: while the pointer is moving the fan only exists in motion; the still frame gives you the marker, not the streak.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <CursorTrail
+          @count={{this.count}}
+          @size={{this.size}}
+          @lag={{this.lag}}
+          @hue={{this.hue}}
+          @shape={{this.shape}}
+          @seed={{this.seed}}
+          @followFocus={{this.followFocus}}
+          @restX={{this.restX}}
+          @restY={{this.restY}}
+          class='trail-field'
+        >
+          <p class='trail-lede'>Spring bookings awaiting a cupping slot</p>
+          <ul class='trail-list'>
+            {{#each this.rows as |row|}}
+              <li class='trail-row'>
+                <Button @size='xs' @appearance='outlined'>{{row.tea}}</Button>
+                <span class='trail-meta'>{{row.place}} · lot
+                  {{row.lot}}</span>
+              </li>
+            {{/each}}
+          </ul>
+        </CursorTrail>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='count'
+          @defaultValue={{6}}
+          @value={{this.count}}
+          @min={{1}}
+          @max={{24}}
+          @step={{1}}
+          @description='Number of trailing marks, clamped 1–24. Mark 0 is the head; each subsequent mark is smaller, fainter and slower.'
+          @onInput={{this.setCount}}
+        />
+        <Args.Number
+          @name='size'
+          @defaultValue={{14}}
+          @value={{this.size}}
+          @min={{4}}
+          @max={{48}}
+          @step={{1}}
+          @description='Diameter of the head mark in px; the rest scale down from it.'
+          @onInput={{this.setSize}}
+        />
+        <Args.Number
+          @name='lag'
+          @defaultValue={{0.42}}
+          @value={{this.lag}}
+          @min={{0}}
+          @max={{1.5}}
+          @step={{0.02}}
+          @description='Seconds the LAST mark takes to reach the pointer. The fan ramps linearly from ~0.05s at the head. This is a transition duration, not a spring — nothing overshoots.'
+          @onInput={{this.setLag}}
+        />
+        <Args.String
+          @name='shape'
+          @defaultValue='dot'
+          @value={{this.shape}}
+          @options={{this.shapeOptions}}
+          @description='Mark geometry: filled dot, hairline ring, or square. For anything else use the :mark block.'
+          @onInput={{this.setShape}}
+        />
+        <Args.String
+          @name='hue'
+          @value={{this.hue}}
+          @description='Any CSS color for the marks. Empty falls back to the --primary token.'
+          @onInput={{this.setHue}}
+        />
+        <Args.String
+          @name='seed'
+          @value={{this.seed}}
+          @description='Seed string for the deterministic per-mark size jitter (seedFrom/pick — there is no Math.random in realm code). Empty gives a perfectly even fan.'
+          @onInput={{this.setSeed}}
+        />
+        <Args.Bool
+          @name='followFocus'
+          @defaultValue={{true}}
+          @value={{this.followFocus}}
+          @description='Move the marker to a focused child on focusin. This is the component’s keyboard path — turn it off only if the field already has its own focus indicator.'
+          @onInput={{this.setFollowFocus}}
+        />
+        <Args.Number
+          @name='restX'
+          @defaultValue={{0.5}}
+          @value={{this.restX}}
+          @min={{0}}
+          @max={{1}}
+          @step={{0.05}}
+          @description='Resting x origin as a fraction of the field width — where the marker parks before anything has engaged.'
+          @onInput={{this.setRestX}}
+        />
+        <Args.Number
+          @name='restY'
+          @defaultValue={{0.5}}
+          @value={{this.restY}}
+          @min={{0}}
+          @max={{1}}
+          @step={{0.05}}
+          @description='Resting y origin as a fraction of the field height.'
+          @onInput={{this.setRestY}}
+        />
+        <Args.Yield
+          @name='default'
+          @description='The live field. Content keeps all of its own pointer events — the mark layer is pointer-events: none and aria-hidden.'
+        />
+        <Args.Yield
+          @name='mark'
+          @description='Replaces the built-in mark. Yields { index, depth } where depth is 0 at the head and 1 at the tail, so a custom mark can scale itself.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-trail-radius'
+          @type='length'
+          @description='Corner radius of the field and of the clipping mark layer. Defaults to the --radius token.'
+        />
+        <Css.Basic
+          @name='pretui-trail-hue'
+          @type='color'
+          @description='Same channel @hue writes to, for setting the color from a stylesheet instead of an arg.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .trail-field {
+        padding: 18px;
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-card,
+          0 0 0 1px var(--border),
+          0 1px 3px rgb(16 24 40 / 0.06)
+        );
+      }
+      .trail-lede {
+        margin: 0 0 12px;
+        font-size: var(--text-ui-md, 12.5px);
+        text-transform: uppercase;
+        letter-spacing: 0.06em;
+        color: var(--muted-foreground);
+      }
+      .trail-list {
+        margin: 0;
+        padding: 0;
+        list-style: none;
+        display: grid;
+        gap: 8px;
+      }
+      .trail-row {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+      }
+      .trail-meta {
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_CURSOR_TRAIL: Record<string, unknown> = {
+  CursorTrail: CursorTrailUsage,
+};