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

package/bundled-realms/pretui/components/text-rotate.usage.gts

@@ -0,0 +1,73 @@
+// Pretui — TextRotate usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { TextRotate } from './text-rotate';
+
+// ── TextRotate — fresh page (no upstream knob rig) ───────────────────────
+class TextRotateUsage extends Component {
+  @tracked wordsCsv = 'Da Hong Pao, Silver Needle, Gyokuro, Milk Oolong';
+  @tracked interval = 2;
+  setWordsCsv = (v: string) => (this.wordsCsv = v);
+  setInterval = (v: number | null) => (this.interval = v ?? 2);
+  get words(): string[] {
+    return this.wordsCsv
+      .split(',')
+      .map((w) => w.trim())
+      .filter((w) => w.length > 0);
+  }
+  get usage() {
+    let words = this.words.map((w) => `'${w}'`).join(' ');
+    let bits = [`@words={{array ${words}}}`];
+    if (this.interval !== 2) bits.push(`@interval={{${this.interval}}}`);
+    return `<TextRotate ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='TextRotate'
+      @description='Rotating word slot — a clipped one-line window over a vertical reel of words, advanced by a steps() keyframe carousel that wraps seamlessly. Words swap discretely on the interval; reduced motion pins the slot to the first word.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <p class='pretui-rotate-demo-line'>
+          This season we are curing
+          <strong><TextRotate
+              @words={{this.words}}
+              @interval={{this.interval}}
+            /></strong>
+          in the Wuyishan rooms.
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='words'
+          @required={{true}}
+          @value={{this.wordsCsv}}
+          @description='string[] of words to cycle through (comma-separated here for the knob). Fewer than two words renders a static word, no animation. All words are mirrored for assistive tech.'
+          @onInput={{this.setWordsCsv}}
+        />
+        <Args.Number
+          @name='interval'
+          @defaultValue={{2}}
+          @value={{this.interval}}
+          @min={{0.5}}
+          @max={{6}}
+          @step={{0.5}}
+          @description='Seconds each word holds the slot before the reel steps.'
+          @onInput={{this.setInterval}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-rotate-demo-line {
+        margin: 0;
+        font-size: var(--text-ui-lg, 15px);
+        color: var(--foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TEXT_ROTATE: Record<string, unknown> = {
+  TextRotate: TextRotateUsage,
+};

package/bundled-realms/pretui/components/text-scramble.gts

@@ -0,0 +1,189 @@
+// Pretui — TextScramble: text that resolves out of deterministic glyph noise.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { pick, seedFrom } from '../examples';
+
+// ── TextScramble ─────────────────────────────────────────────────────────
+// Letters resolve out of noise — CSS-drivable approximation of
+// motion-primitives' text-scramble.tsx, with the delta on record: the
+// original runs a setInterval that re-randomizes every unresolved char
+// each ~40ms tick (Math.random per frame) while a progress line sweeps
+// left to right. Neither timers nor Math.random exist in realm code, and
+// the tempting pure-CSS alternative — a per-character steps() animation
+// cycling a glyph strip through ::before content — is not feasible
+// (content can't tween through a strip under the scoped-css transpile).
+// The transcription keeps the left-to-right resolve and the churn
+// *impression*: each char is a stack of two seeded noise glyphs (FNV-1a
+// pick off the text itself, so the same text scrambles identically every
+// render) that hand off mid-window and then blur/fade out as the real
+// char blurs in, on staggered delays. Total choreography spans @duration:
+// half stagger sweep, half per-char resolve window.
+const SCRAMBLE_GLYPHS = [
+  '#',
+  '%',
+  '&',
+  '+',
+  '=',
+  '*',
+  '<',
+  '>',
+  '/',
+  '?',
+  '$',
+  '@',
+  '!',
+  '§',
+  '¤',
+  '~',
+];
+
+export interface TextScrambleSignature {
+  Args: {
+    text: string;
+    /** total seconds from first noise to last resolved character */
+    duration?: number;
+  };
+  Element: HTMLSpanElement;
+}
+
+interface ScrambleCell {
+  ch: string;
+  space: boolean;
+  noiseA: string;
+  noiseB: string;
+  style: ReturnType<typeof htmlSafe> | null;
+}
+
+export class TextScramble extends Component<TextScrambleSignature> {
+  get duration(): number {
+    let d = this.args.duration ?? 0.8;
+    return d > 0 ? d : 0.8;
+  }
+  get containerStyle(): ReturnType<typeof htmlSafe> {
+    return htmlSafe(
+      `--pretui-scramble-window: ${(this.duration / 2).toFixed(3)}s`,
+    );
+  }
+  get cells(): ScrambleCell[] {
+    let text = this.args.text ?? '';
+    let chars = Array.from(text);
+    let seed = seedFrom(text);
+    let sweep = this.duration / 2;
+    let last = Math.max(chars.length - 1, 1);
+    return chars.map((ch, i) => {
+      if (ch === ' ') {
+        return { ch, space: true, noiseA: '', noiseB: '', style: null };
+      }
+      return {
+        ch,
+        space: false,
+        noiseA: pick(seed, 2 * i, SCRAMBLE_GLYPHS),
+        noiseB: pick(seed, 2 * i + 1, SCRAMBLE_GLYPHS),
+        style: htmlSafe(
+          `--pretui-scr-delay: ${((i * sweep) / last).toFixed(3)}s`,
+        ),
+      };
+    });
+  }
+  <template>
+    <span
+      class='pretui-scramble'
+      style={{this.containerStyle}}
+      data-test-pretui-text-scramble
+      ...attributes
+    >
+      <span aria-hidden='true'>
+        {{#each this.cells as |c|}}{{#if c.space}}<span class='pretui-scramble-space'>{{c.ch}}</span>{{else}}<span class='pretui-scramble-cell' style={{c.style}}><span class='pretui-scramble-real'>{{c.ch}}</span><span class='pretui-scramble-noise pretui-scramble-noise-a'>{{c.noiseA}}</span><span class='pretui-scramble-noise pretui-scramble-noise-b'>{{c.noiseB}}</span></span>{{/if}}{{/each}}
+      </span>
+      <span class='pretui-sr'>{{@text}}</span>
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-scramble {
+          display: inline-block;
+        }
+        .pretui-scramble-space {
+          white-space: pre;
+        }
+        .pretui-scramble-cell {
+          position: relative;
+          display: inline-block;
+        }
+        /* base styles are the resolved end state; keyframes choreograph */
+        .pretui-scramble-real {
+          animation: pretui-scr-real var(--pretui-scramble-window, 0.4s) linear
+            both;
+          animation-delay: var(--pretui-scr-delay, 0s);
+        }
+        @keyframes pretui-scr-real {
+          0%,
+          60% {
+            opacity: 0;
+            filter: blur(3px);
+          }
+          100% {
+            opacity: 1;
+            filter: blur(0);
+          }
+        }
+        .pretui-scramble-noise {
+          position: absolute;
+          inset: 0;
+          text-align: center;
+          color: var(--muted-foreground);
+          opacity: 0;
+          pointer-events: none;
+        }
+        .pretui-scramble-noise-a {
+          animation: pretui-scr-noise-a var(--pretui-scramble-window, 0.4s)
+            linear both;
+          animation-delay: var(--pretui-scr-delay, 0s);
+        }
+        @keyframes pretui-scr-noise-a {
+          0%,
+          40% {
+            opacity: 1;
+            filter: blur(0);
+          }
+          55%,
+          100% {
+            opacity: 0;
+            filter: blur(2px);
+          }
+        }
+        .pretui-scramble-noise-b {
+          animation: pretui-scr-noise-b var(--pretui-scramble-window, 0.4s)
+            linear both;
+          animation-delay: var(--pretui-scr-delay, 0s);
+        }
+        @keyframes pretui-scr-noise-b {
+          0%,
+          40% {
+            opacity: 0;
+          }
+          50%,
+          72% {
+            opacity: 1;
+          }
+          100% {
+            opacity: 0;
+            filter: blur(2px);
+          }
+        }
+        .pretui-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip: rect(0 0 0 0);
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-scramble-real,
+          .pretui-scramble-noise {
+            animation: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/text-scramble.md

@@ -0,0 +1,42 @@
+## What it is
+
+Letters resolving out of noise, left to right, until the message is there.
+
+It is a CSS approximation of an effect that is normally frame-driven, and the approximation is the interesting part.
+
+## The contract
+
+```
+@text (required) — the message to resolve into
+@duration?       — total seconds from first noise to last resolved character;
+                   a non-positive value is floored
+```
+
+**Each character stacks two seeded noise glyphs that hand off and blur out as the real character blurs in**, on staggered delays swept across the string. Instead of re-randomising every frame — which is what the upstream does and what a timer would cost — the noise is chosen once per character at render.
+
+**The noise is deterministic.** The same text always scrambles the same way, because the glyphs are drawn from a seed derived from the text itself. That matters here beyond tidiness: a card that re-renders during indexing produces the same frames, so a screenshot is reproducible.
+
+**Spaces are left alone**, so word boundaries stay visible through the scramble and the line does not reflow as it resolves.
+
+## Prior art
+
+**motion-primitives' TextScramble**, **fancy-components' ScrambleIn/ScrambleHover** and **react-bits' Scrambled/DecryptedText**.
+
+Where Pretui is better: **no animation frame loop.** Every upstream re-randomises each character on a `requestAnimationFrame` or interval tick, holding the partially-resolved string in state. Here the whole resolve is a CSS schedule computed once, which cannot leak a loop, cannot desync from a re-render, and costs nothing once painted. Determinism is the second win — an effect that looks different on every render cannot be screenshotted or diffed.
+
+Where it is thinner, and honestly so: **two noise glyphs per character is not the same as continuous noise.** The upstream effect churns; this one hands off twice and resolves. At a short duration the difference is invisible; at a long one, it reads as a blur rather than as scrambling. There is also no hover-to-scramble mode, no per-character speed, and no reverse.
+
+## Accessibility
+
+- **The scrambled copy is `aria-hidden`** and the real text is mirrored in a visually-hidden span, so a screen reader gets the message rather than a run of noise glyphs. Announcing the animated layer would be actively harmful here — it is deliberately meaningless characters.
+- **Reduced motion collapses it to the resolved text.** The base styles are the end state, so the kill switch leaves the message rather than a frozen midpoint of noise.
+- **The effect delays legibility for sighted readers only.** Anyone using the mirror has the text immediately; anyone reading the screen waits `@duration`. Keep it short, and keep it away from anything time-sensitive.
+- **Noise glyphs are not in the accessible name**, so a scrambling heading is still a findable heading.
+
+## Theming
+
+`--pretui-scramble-window` (the per-character resolve window) and `--pretui-scr-delay` (each character's staggered start), both derived from `@duration` and the string's length.
+
+There is no color token: the noise and the message are the same ink, inherited from context. That is what makes the resolve read as one piece of text changing rather than as two layers crossfading — and it means a theme needs to do nothing for this component to fit.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/text-scramble.usage.gts

@@ -0,0 +1,80 @@
+// Pretui — TextScramble 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 { TextScramble } from './text-scramble';
+
+// ── TextScramble — fresh page (no upstream knob rig) ─────────────────────
+class TextScrambleUsage extends Component {
+  @tracked text = 'Batch B-1181 · Wuyishan curing room';
+  @tracked duration = 1.2;
+  @tracked run = 0;
+  setText = (v: string) => (this.text = v);
+  setDuration = (v: number | null) => (this.duration = v ?? 1.2);
+  replay = () => (this.run = this.run + 1);
+  get runKey(): number[] {
+    return [this.run];
+  }
+  get usage() {
+    let bits = [`@text='${this.text}'`];
+    if (this.duration !== 1.2) bits.push(`@duration={{${this.duration}}}`);
+    return `<TextScramble ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='TextScramble'
+      @description='Letters resolve out of noise, left to right — a CSS approximation of the RAF-driven original: instead of re-randomizing every frame, each character stacks two seeded noise glyphs that hand off and blur out as the real character blurs in, on staggered delays. Same text, same noise, every render.'
+      @source={{this.usage}}
+    >
+      <:example>
+        {{#each this.runKey key='@identity' as |run|}}
+          <span class='pretui-scramble-demo-line' data-run={{run}}>
+            <TextScramble @text={{this.text}} @duration={{this.duration}} />
+          </span>
+        {{/each}}
+        <div class='pretui-demo-replay'>
+          <Button
+            @size='xs'
+            @appearance='outlined'
+            {{on 'click' this.replay}}
+          >Replay</Button>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='text'
+          @required={{true}}
+          @value={{this.text}}
+          @description='The string that resolves out of noise. Full text mirrored sr-only; the glyph stack is aria-hidden.'
+          @onInput={{this.setText}}
+        />
+        <Args.Number
+          @name='duration'
+          @defaultValue={{0.8}}
+          @value={{this.duration}}
+          @min={{0.4}}
+          @max={{4}}
+          @step={{0.2}}
+          @description='Total seconds from first noise to last resolved character — half stagger sweep, half per-char resolve window.'
+          @onInput={{this.setDuration}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-scramble-demo-line {
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-lg, 15px);
+        color: var(--foreground);
+      }
+      .pretui-demo-replay {
+        margin-top: 12px;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TEXT_SCRAMBLE: Record<string, unknown> = {
+  TextScramble: TextScrambleUsage,
+};

package/bundled-realms/pretui/components/text-shimmer.gts

@@ -0,0 +1,89 @@
+// Pretui — TextShimmer: a light sweep across text that marks it as in progress.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+
+// ── TextShimmer ──────────────────────────────────────────────────────────
+// Gradient sheen sweeping across text — pure CSS transcription of
+// motion-primitives' text-shimmer.tsx: the text is painted by
+// background-clip: text over two stacked layers (a no-repeat sheen
+// gradient above a solid base-color layer) and the sheen's
+// background-position animates 100% → 0% on a linear infinite loop. The
+// upstream dark: utility fork is dropped — base and sheen ride the Pretui
+// token channel (muted-foreground → foreground), so a theme change
+// re-dresses the sweep. Sheen width follows upstream: text length × @spread
+// pixels. Reduced motion shows the base color as plain text.
+export interface TextShimmerSignature {
+  Args: {
+    text: string;
+    /** seconds per sweep */
+    duration?: number;
+    /** sheen half-width in px per character of text */
+    spread?: number;
+  };
+  Element: HTMLSpanElement;
+}
+
+export class TextShimmer extends Component<TextShimmerSignature> {
+  get style(): ReturnType<typeof htmlSafe> {
+    let duration = this.args.duration ?? 2;
+    if (!(duration > 0)) duration = 2;
+    let spread = (this.args.text ?? '').length * (this.args.spread ?? 2);
+    return htmlSafe(
+      `--pretui-shimmer-duration: ${duration.toFixed(3)}s; --pretui-shimmer-spread: ${spread.toFixed(1)}px`,
+    );
+  }
+  <template>
+    <span
+      class='pretui-shimmer'
+      style={{this.style}}
+      data-test-pretui-text-shimmer
+      ...attributes
+    >{{@text}}</span>
+    <style scoped>
+      @layer PretComponent {
+        @keyframes pretui-shimmer-sweep {
+          from {
+            background-position:
+              100% center,
+              0 0;
+          }
+          to {
+            background-position:
+              0% center,
+              0 0;
+          }
+        }
+        .pretui-shimmer {
+          display: inline-block;
+          color: transparent;
+          background:
+            linear-gradient(
+              90deg,
+              transparent calc(50% - var(--pretui-shimmer-spread, 32px)),
+              var(--foreground),
+              transparent calc(50% + var(--pretui-shimmer-spread, 32px))
+            ),
+            linear-gradient(
+              var(--muted-foreground),
+              var(--muted-foreground)
+            );
+          background-size:
+            250% 100%,
+            auto;
+          background-repeat: no-repeat, repeat;
+          -webkit-background-clip: text;
+          background-clip: text;
+          animation: pretui-shimmer-sweep var(--pretui-shimmer-duration, 2s)
+            linear infinite;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-shimmer {
+            animation: none;
+            background: none;
+            color: var(--muted-foreground);
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/text-shimmer.md

@@ -0,0 +1,42 @@
+## What it is
+
+A gradient sheen sweeping across text: `background-clip: text` over an animated two-layer gradient, on a pure-CSS infinite loop.
+
+It is the kit's waiting-state voice for text — a pending lot, an in-flight job, a value still resolving. For a block-shaped placeholder rather than live text, that is **Skeleton**.
+
+## The contract
+
+```
+@text (required) — the text to shimmer
+@duration?       — seconds per sweep; a non-positive value is floored
+@spread?         — sheen half-width, in px per character of text
+```
+
+**`@spread` is per character, not absolute.** The sheen is sized to the length of the text, so a short label and a long sentence get a proportionate sweep instead of the same physical band crossing one in a flash and the other over several seconds.
+
+**The text itself is rendered, not chopped.** Unlike the per-character effects in this module, the sheen is a background over a single text node — which is why this one needs no screen-reader mirror.
+
+**A non-positive duration is floored** rather than producing a zero-length animation.
+
+## Prior art
+
+**motion-primitives' TextShimmer** and **ShimmerWave**, plus **react-bits**.
+
+Where Pretui is better: **the colors ride the token channel** — `--muted-foreground` for the base and `--foreground` for the sheen — rather than being a hardcoded gradient. So a shimmer in dark mode shimmers correctly without anyone restating the gradient, and a shimmering label sits at the same weight as the static labels around it. The sweep is also a pure CSS loop with no JavaScript driving it.
+
+Where it is thinner: one sweep direction, no pause, no finite repeat count, and no way to shimmer anything but a text string — a shimmering row or card needs **Skeleton** instead. There is no wave variant either; motion-primitives' ShimmerWave animates per character, and this does not.
+
+## Accessibility
+
+- **The text is real text in the document**, announced normally. The shimmer is a background treatment, so there is nothing to hide and nothing to mirror.
+- **Reduced motion collapses it to the resolved state.** The base styles are the end state, so stopping the animation leaves legible text in the base colour rather than a frozen gradient mid-sweep.
+- **The shimmer conveys "waiting" visually and only visually.** A screen-reader user is told nothing by it. If the pending state matters — and for an in-flight job it usually does — it needs saying in text or in a live region; this component will not do it for you.
+- **Contrast moves during the sweep.** The base is `--muted-foreground`, which is the lower-contrast end, so text that only just passes at rest passes for less of the cycle. Shimmer is for transient states, not for body copy.
+
+## Theming
+
+`--pretui-shimmer-duration` (seconds per sweep, from `@duration`) and `--pretui-shimmer-spread` (the sheen half-width, from `@spread`), over `--muted-foreground` and `--foreground` for the two gradient stops.
+
+Because both colors are theme tokens rather than literals, a theme retunes every shimmer in the product by retuning its foreground pair — and the sheen is always the brighter of the two, so the effect reads the same way in light and dark without a second definition.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/text-shimmer.usage.gts

@@ -0,0 +1,69 @@
+// Pretui — TextShimmer usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { TextShimmer } from './text-shimmer';
+
+// ── TextShimmer — fresh page (no upstream knob rig) ──────────────────────
+class TextShimmerUsage extends Component {
+  @tracked text = 'Cupping panel in session — scoring Junshan Yinzhen…';
+  @tracked duration = 2;
+  @tracked spread = 2;
+  setText = (v: string) => (this.text = v);
+  setDuration = (v: number | null) => (this.duration = v ?? 2);
+  setSpread = (v: number | null) => (this.spread = v ?? 2);
+  get usage() {
+    let bits = [`@text='${this.text}'`];
+    if (this.duration !== 2) bits.push(`@duration={{${this.duration}}}`);
+    if (this.spread !== 2) bits.push(`@spread={{${this.spread}}}`);
+    return `<TextShimmer ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='TextShimmer'
+      @description='Gradient sheen sweeping across text — background-clip: text over an animated two-layer gradient, pure CSS on a linear infinite loop. The waiting-state voice for pending lots and in-flight work; base and sheen colors ride the token channel (muted-foreground → foreground).'
+      @source={{this.usage}}
+    >
+      <:example>
+        <TextShimmer
+          @text={{this.text}}
+          @duration={{this.duration}}
+          @spread={{this.spread}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='text'
+          @required={{true}}
+          @value={{this.text}}
+          @description='The text the sheen sweeps across — real DOM text, readable by assistive tech.'
+          @onInput={{this.setText}}
+        />
+        <Args.Number
+          @name='duration'
+          @defaultValue={{2}}
+          @value={{this.duration}}
+          @min={{0.5}}
+          @max={{8}}
+          @step={{0.5}}
+          @description='Seconds per sweep, right to left, looping.'
+          @onInput={{this.setDuration}}
+        />
+        <Args.Number
+          @name='spread'
+          @defaultValue={{2}}
+          @value={{this.spread}}
+          @min={{0.5}}
+          @max={{8}}
+          @step={{0.5}}
+          @description='Sheen half-width in px per character — longer strings get a proportionally wider highlight.'
+          @onInput={{this.setSpread}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_TEXT_SHIMMER: Record<string, unknown> = {
+  TextShimmer: TextShimmerUsage,
+};