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

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

@@ -0,0 +1,292 @@
+// Pretui — TextMorph: text that morphs from one string to the next.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+
+// ═══════════════════════════════════════════════════════════════════════
+// TextMorph
+// ═══════════════════════════════════════════════════════════════════════
+
+/** What happens to one glyph across a morph. */
+export type MorphRole = 'keep' | 'out' | 'in';
+
+/** One glyph's part in the morph, in final render order. */
+export interface MorphStep {
+  ch: string;
+  role: MorphRole;
+}
+
+/** Beyond this length the quadratic diff is skipped — a morph between two
+ * paragraphs is not a thing anyone can read anyway, and the component must
+ * never become the reason a render is slow. */
+const MORPH_LIMIT = 240;
+
+/**
+ * The shared-letter plan for morphing `from` into `to`.
+ *
+ * A longest-common-subsequence diff, which is what makes this component
+ * different from a cross-fade: letters present in BOTH strings, in the same
+ * relative order, keep their identity and stay put, so `Da Hong Pao` →
+ * `Da Yu Ling` visibly keeps its `Da ` and its `o`. The reader sees the two
+ * strings are relatives. Every other implementation of this effect that is
+ * not motion-primitives' just fades one out and the other in, which
+ * communicates nothing.
+ *
+ * Pure, and the whole reason this is testable without a browser.
+ */
+export function morphPlan(from: string, to: string): MorphStep[] {
+  let a = Array.from(from ?? '');
+  let b = Array.from(to ?? '');
+  if (a.length === 0) {
+    return b.map((ch) => ({ ch, role: 'in' as const }));
+  }
+  if (b.length === 0) {
+    return a.map((ch) => ({ ch, role: 'out' as const }));
+  }
+  if (a.length > MORPH_LIMIT || b.length > MORPH_LIMIT) {
+    return [
+      ...a.map((ch) => ({ ch, role: 'out' as const })),
+      ...b.map((ch) => ({ ch, role: 'in' as const })),
+    ];
+  }
+
+  // Classic LCS table. Rows are `a`, columns are `b`.
+  let table: number[][] = [];
+  for (let i = 0; i <= a.length; i++) {
+    table.push(new Array<number>(b.length + 1).fill(0));
+  }
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      let row = table[i] as number[];
+      let below = table[i + 1] as number[];
+      row[j] =
+        a[i] === b[j]
+          ? (below[j + 1] as number) + 1
+          : Math.max(below[j] as number, row[j + 1] as number);
+    }
+  }
+
+  let steps: MorphStep[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      steps.push({ ch: b[j] as string, role: 'keep' });
+      i++;
+      j++;
+      continue;
+    }
+    let below = table[i + 1] as number[];
+    let row = table[i] as number[];
+    if ((below[j] as number) >= (row[j + 1] as number)) {
+      steps.push({ ch: a[i] as string, role: 'out' });
+      i++;
+    } else {
+      steps.push({ ch: b[j] as string, role: 'in' });
+      j++;
+    }
+  }
+  while (i < a.length) {
+    steps.push({ ch: a[i] as string, role: 'out' });
+    i++;
+  }
+  while (j < b.length) {
+    steps.push({ ch: b[j] as string, role: 'in' });
+    j++;
+  }
+  return steps;
+}
+
+interface MorphCell {
+  key: string;
+  ch: string;
+  role: MorphRole;
+  style: ReturnType<typeof htmlSafe>;
+}
+
+export interface TextMorphSignature {
+  Args: {
+    /** the CURRENT string. Changing it is what triggers a morph — the
+     * component remembers what it was showing, so a caller never has to pass
+     * both halves. Mirrored in an sr-only span; the glyph stack is
+     * `aria-hidden`. */
+    text: string;
+    /** seconds one glyph takes to leave or arrive (default 0.32) */
+    duration?: number;
+    /** seconds between consecutive glyphs (default 0.012). Set it to 0 for
+     * a single simultaneous swap. */
+    stagger?: number;
+    /** the string being morphed FROM, stated explicitly. Supply it and the
+     * render is a pure function of the arguments with no memory involved —
+     * preferable wherever the caller already holds both strings. Omit it and
+     * the component remembers what it last showed. */
+    from?: string;
+  };
+  Element: HTMLSpanElement;
+}
+
+export class TextMorph extends Component<TextMorphSignature> {
+  // All four are deliberately UNTRACKED. They are a memo over @text (which
+  // IS tracked, so anything reading it recomputes when it changes), and
+  // tracking them would turn the memo write into a backtracking re-render.
+  //
+  // The memo lives in a METHOD rather than a getter for two reasons. The
+  // lint gate rejects assignment inside a getter (ember/no-side-effects) and
+  // it is right to: a getter that mutates is invisible to a reader and to
+  // the tracking system alike. Written as a call, the memo is something the
+  // template asks for once per render, on purpose.
+  private previousText = '';
+  private currentText: string | undefined;
+  private generation = 0;
+  private cached: MorphStep[] = [];
+
+  /** The current plan, recomputing it if @text has moved on since the last
+   * time it was asked for. Idempotent: calling it twice in one render
+   * returns the same array and bumps nothing. */
+  private currentPlan(): MorphStep[] {
+    let next = this.args.text ?? '';
+    let stated = this.args.from;
+    if (stated !== undefined) {
+      // Fully controlled: no memory, and the era is the pair itself so a
+      // change to either string rebuilds the spans and restarts the CSS.
+      return morphPlan(stated, next);
+    }
+    if (next !== this.currentText) {
+      this.previousText = this.currentText ?? '';
+      this.currentText = next;
+      this.generation = this.generation + 1;
+      this.cached = morphPlan(this.previousText, next);
+    }
+    return this.cached;
+  }
+
+  /** The identity stamp mixed into every span key. Changing it is how a CSS
+   * animation is restarted without a timer: the element is a new element. */
+  private currentEra(): string {
+    let stated = this.args.from;
+    if (stated !== undefined) {
+      return stated.length + '>' + (this.args.text ?? '').length + ':' + stated;
+    }
+    return String(this.generation);
+  }
+
+  get duration(): number {
+    let raw = this.args.duration;
+    return raw !== undefined && Number.isFinite(raw) && raw > 0 ? raw : 0.32;
+  }
+  get stagger(): number {
+    let raw = this.args.stagger;
+    return raw !== undefined && Number.isFinite(raw) && raw >= 0 ? raw : 0.012;
+  }
+  get containerStyle(): ReturnType<typeof htmlSafe> {
+    return htmlSafe(
+      '--pretui-morph-dur: ' +
+        this.duration.toFixed(3) +
+        's; --pretui-morph-step: ' +
+        this.stagger.toFixed(3) +
+        's',
+    );
+  }
+  get cells(): MorphCell[] {
+    let steps = this.currentPlan();
+    let era = this.currentEra();
+    return steps.map((step, index) => ({
+      key: era + ':' + index + ':' + step.role + ':' + step.ch,
+      ch: step.ch,
+      role: step.role,
+      style: htmlSafe('--pretui-morph-i: ' + index),
+    }));
+  }
+
+  <template>
+    <span
+      class='pretui-morph'
+      style={{this.containerStyle}}
+      data-test-pretui-text-morph
+      ...attributes
+    >
+      <span aria-hidden='true'>
+        {{~#each this.cells key='key' as |cell|~}}
+          <span
+            class='pretui-morph-cell'
+            data-role={{cell.role}}
+            style={{cell.style}}
+          >{{cell.ch}}</span>
+        {{~/each~}}
+      </span>
+      <span class='pretui-morph-sr'>{{@text}}</span>
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-morph {
+          display: inline-block;
+          white-space: pre;
+        }
+        .pretui-morph-cell {
+          display: inline-block;
+          white-space: pre;
+        }
+        /* END STATE for a departing glyph: gone. Collapsing the font-size
+           rather than the width is the trick wave 1 established — it takes the
+           glyph's advance width with it exactly, so the surviving letters
+           close the gap with no measuring. */
+        .pretui-morph-cell[data-role='out'] {
+          font-size: 0;
+          opacity: 0;
+          animation: pretui-morph-out var(--pretui-morph-dur, 0.32s)
+            cubic-bezier(0.4, 0, 1, 1) both;
+          animation-delay: calc(
+            var(--pretui-morph-i, 0) * var(--pretui-morph-step, 0.012s)
+          );
+        }
+        @keyframes pretui-morph-out {
+          from {
+            font-size: 1em;
+            opacity: 1;
+            translate: 0 0;
+          }
+          to {
+            font-size: 0;
+            opacity: 0;
+            translate: 0 -0.35em;
+          }
+        }
+        /* END STATE for an arriving glyph: present. Arrivals wait for the
+           departures, so the line never overshoots its final width. */
+        .pretui-morph-cell[data-role='in'] {
+          font-size: 1em;
+          opacity: 1;
+          animation: pretui-morph-in var(--pretui-morph-dur, 0.32s)
+            cubic-bezier(0, 0, 0.2, 1) both;
+          animation-delay: calc(
+            var(--pretui-morph-dur, 0.32s) + var(--pretui-morph-i, 0) *
+              var(--pretui-morph-step, 0.012s)
+          );
+        }
+        @keyframes pretui-morph-in {
+          from {
+            font-size: 0;
+            opacity: 0;
+            translate: 0 0.35em;
+          }
+        }
+        .pretui-morph-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip: rect(0 0 0 0);
+          white-space: nowrap;
+        }
+        /* Reduced motion lands on the END STATE, which for this component is
+           the complete text and nothing else: departing glyphs are already
+           collapsed to nothing by their base styles, arriving glyphs are
+           already at full size. Never a frozen midpoint. */
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-morph-cell {
+            animation: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,45 @@
+## What it is
+
+A string changing into another string, with the shared letters kept in place.
+
+It is the clearest case in the kit of motion that carries meaning rather than decorating: **the transition _is_ the information.** Which letters survive tells you how the two strings relate — that "draft" became "drafted" rather than being replaced by an unrelated word.
+
+## The contract
+
+```
+@text (required) — the CURRENT string; changing it is what triggers a morph
+@from?           — the string being morphed FROM, stated explicitly
+@duration?       — seconds one glyph takes to leave or arrive. Default 0.32
+@stagger?        — seconds between consecutive glyphs. Default 0.012;
+                   0 gives a single simultaneous swap
+```
+
+**Changing `@text` triggers the morph.** The component remembers what it was showing, so a caller never has to pass both halves.
+
+**`@from` is the better path when you have it.** Supply it and the render is a pure function of the arguments with no memory involved — preferable wherever the caller already holds both strings, and the only version that behaves identically on a re-render.
+
+**`@stagger` at 0.012 is deliberately small.** This is not an entrance effect; the glyphs should read as one word rearranging, not as a wave crossing a line.
+
+## Prior art
+
+**motion-primitives' TextMorph.**
+
+Where Pretui is better: **`@from` exists.** The upstream is memory-only, which means a component that re-mounts morphs from nothing, and a test cannot assert on a morph without driving a state change first. Making the source string statable turns the whole thing into a pure function. The schedule is also CSS rather than a frame loop.
+
+Where it is thinner: the shared-letter matching is positional rather than a real diff, so two strings that share letters in a different order will not find them. There is no per-glyph colour or emphasis during the morph, and no way to morph between strings of wildly different lengths gracefully — the stagger runs over the longer of the two.
+
+## Accessibility
+
+- **The glyph stack is `aria-hidden` and the current string is mirrored in a visually-hidden span.** A string chopped into one span per glyph is not text to a screen reader — it is a pile of letters, and several engines will spell it out.
+- **The mirror carries `@text`, the destination**, so assistive technology is told what the value _is_ rather than what it was.
+- **Reduced motion lands on the end state**, never a frozen midpoint. The base styles are the end state and the keyframes only supply the journey, so `animation: none` is a complete kill switch.
+- **The meaning the morph carries is visual only.** A sighted reader learns that the two strings are related from the letters that stayed; a screen-reader user just gets the new value. If the relationship matters, it needs saying.
+- **Rapid changes overlap.** A value updating faster than `@duration` leaves glyphs mid-flight; this is a component for occasional changes, not for a live counter.
+
+## Theming
+
+`--pretui-morph-dur` (from `@duration`), `--pretui-morph-step` (from `@stagger`), `--pretui-morph-i` (each glyph's index).
+
+No color tokens: the morph inherits ink and typeface from context, which is what makes it usable inside a heading or a table cell without looking like a widget. The theme affects it only through the text 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/text-morph.usage.gts

@@ -0,0 +1,117 @@
+// Pretui — TextMorph 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 { TextMorph } from './text-morph';
+
+// ── TextMorph ───────────────────────────────────────────────────────────
+const MORPH_LOTS = [
+  'Da Hong Pao',
+  'Da Yu Ling',
+  'Silver Needle',
+  'Jasmine Dragon Pearls',
+  'Aged Shou Pu-erh',
+];
+
+class TextMorphUsage extends Component {
+  @tracked step = 0;
+  @tracked duration = 0.32;
+  @tracked stagger = 0.012;
+
+  setDuration = (v: number | null) => (this.duration = v ?? 0.32);
+  setStagger = (v: number | null) => (this.stagger = v ?? 0.012);
+
+  get current(): string {
+    return MORPH_LOTS[this.step % MORPH_LOTS.length] as string;
+  }
+  advance = () => (this.step = this.step + 1);
+
+  get usage(): string {
+    return (
+      '<TextMorph @text={{this.lotName}} @duration={{' +
+      this.duration +
+      '}} @stagger={{' +
+      this.stagger +
+      '}} />'
+    );
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='TextMorph'
+      @description='One string changing INTO another, with the shared letters kept. A longest-common-subsequence diff decides which glyphs survive, so Da Hong Pao to Da Yu Ling visibly keeps its Da and its o — the reader sees the two strings are relatives. This is the clearest Law 5 case in the kit: the transition IS the information, and the cross-fade every other library ships throws it away. Departing glyphs collapse their font-size, which takes their advance width with them exactly, so the survivors close the gap with nothing measured.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-morph-demo'>
+          <p class='pretui-morph-demo-line'>
+            <TextMorph
+              @text={{this.current}}
+              @duration={{this.duration}}
+              @stagger={{this.stagger}}
+            />
+          </p>
+          <Button
+            @size='xs'
+            @appearance='outlined'
+            {{on 'click' this.advance}}
+          >Next lot</Button>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='text'
+          @required={{true}}
+          @value={{this.current}}
+          @hideControls={{true}}
+          @description='The CURRENT string. Changing it is what triggers a morph — the component remembers what it was showing, so a caller never has to pass both halves.'
+        />
+        <Args.String
+          @name='from'
+          @description='The string being morphed FROM, stated explicitly. Supply it and the render is a pure function of the arguments with no memory involved.'
+        />
+        <Args.Number
+          @name='duration'
+          @value={{this.duration}}
+          @defaultValue={{0.32}}
+          @min={{0.1}}
+          @max={{1.5}}
+          @step={{0.02}}
+          @description='Seconds one glyph takes to leave or arrive. Arrivals wait for the departures, so the line never overshoots its final width.'
+          @onInput={{this.setDuration}}
+        />
+        <Args.Number
+          @name='stagger'
+          @value={{this.stagger}}
+          @defaultValue={{0.012}}
+          @min={{0}}
+          @max={{0.12}}
+          @step={{0.004}}
+          @description='Seconds between consecutive glyphs. Set it to 0 for a single simultaneous swap.'
+          @onInput={{this.setStagger}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-morph-demo {
+        display: grid;
+        gap: var(--space-3, 8px);
+        justify-items: start;
+      }
+      .pretui-morph-demo-line {
+        margin: 0;
+        min-height: 1.6em;
+        font-size: var(--text-heading, 19px);
+        font-weight: var(--weight-heading, 700);
+        letter-spacing: var(--track-heading, -0.02em);
+        color: var(--foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TEXT_MORPH: Record<string, unknown> = {
+  TextMorph: TextMorphUsage,
+};

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

@@ -0,0 +1,121 @@
+// Pretui — TextRotate: a word slot that cycles through a list of words.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+
+// ── TextRotate ───────────────────────────────────────────────────────────
+// Rotating word slot — transcription of fancy-components' text-rotate.tsx
+// reduced to its CSS-expressible core: a clipped one-line slot over a
+// vertical reel of words, advanced by one keyframe animation running
+// translateY(0 → -N lines) with steps(N, end) over N × @interval seconds,
+// infinite. The step count and duration ride inline style (keyframe
+// percentages can't be parameterized, but steps() count and duration can),
+// and the first word repeats at the reel's tail so the 100% frame wraps
+// seamlessly. Dropped upstream surface: the motion/react enter-exit slide,
+// per-char stagger, and splitBy modes — steps() swaps words discretely,
+// which is the honest timer-free reading of a "word slot". Reduced motion
+// pins the reel to the first word.
+export interface TextRotateSignature {
+  Args: {
+    words: string[];
+    /** seconds each word holds the slot */
+    interval?: number;
+  };
+  Element: HTMLSpanElement;
+}
+
+export class TextRotate extends Component<TextRotateSignature> {
+  get words(): string[] {
+    return (this.args.words ?? []).filter((w) => w.length > 0);
+  }
+  get canRotate(): boolean {
+    return this.words.length > 1;
+  }
+  get firstWord(): string {
+    return this.words[0] ?? '';
+  }
+  // reel = words + repeated first word, so the wrap frame lands on a twin
+  get reel(): string[] {
+    return [...this.words, this.firstWord];
+  }
+  get srText(): string {
+    return this.words.join(', ');
+  }
+  get reelStyle(): ReturnType<typeof htmlSafe> {
+    let n = this.words.length;
+    let interval = this.args.interval ?? 2;
+    if (!(interval > 0)) interval = 2;
+    return htmlSafe(
+      `--pretui-rotate-count: ${n}; animation-duration: ${(n * interval).toFixed(2)}s; animation-timing-function: steps(${n}, end)`,
+    );
+  }
+  <template>
+    <span class='pretui-rotate' data-test-pretui-text-rotate ...attributes>
+      {{#if this.canRotate}}
+        <span class='pretui-rotate-mask' aria-hidden='true'>
+          <span class='pretui-rotate-reel' style={{this.reelStyle}}>
+            {{#each this.reel as |word|}}
+              <span class='pretui-rotate-word'>{{word}}</span>
+            {{/each}}
+          </span>
+        </span>
+        <span class='pretui-sr'>{{this.srText}}</span>
+      {{else}}
+        {{this.firstWord}}
+      {{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-rotate {
+          display: inline-block;
+        }
+        .pretui-rotate-mask {
+          display: inline-block;
+          overflow: hidden;
+          height: var(--pretui-rotate-line, 1.4em);
+          /* overflow != visible turns the inline-block baseline into its
+             bottom edge; -0.4em reseats the inner baseline (0.2em
+             half-leading + ~0.2em descender) on the surrounding line —
+             empirical, override --pretui-rotate-line to retune */
+          vertical-align: -0.4em;
+        }
+        .pretui-rotate-reel {
+          display: flex;
+          flex-direction: column;
+          animation-name: pretui-rotate-step;
+          animation-iteration-count: infinite;
+          /* duration + steps(N, end) arrive via inline style */
+        }
+        .pretui-rotate-word {
+          height: var(--pretui-rotate-line, 1.4em);
+          line-height: var(--pretui-rotate-line, 1.4em);
+          white-space: nowrap;
+        }
+        @keyframes pretui-rotate-step {
+          from {
+            transform: translateY(0);
+          }
+          to {
+            transform: translateY(
+              calc(
+                var(--pretui-rotate-count, 1) * -1 *
+                  var(--pretui-rotate-line, 1.4em)
+              )
+            );
+          }
+        }
+        .pretui-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip: rect(0 0 0 0);
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-rotate-reel {
+            animation: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,44 @@
+## What it is
+
+A slot of phrases rotating through one line: a clipped one-line window over a vertical reel of words, advanced discretely on an interval.
+
+Use it for a headline whose subject changes — "built for _designers_ / _engineers_ / _teams_". For revealing a single string, that is **Typewriter**; for text that arrives live, **StreamingText**.
+
+## The contract
+
+```
+@words (required) — the phrases, in order
+@interval?        — seconds each word holds the slot
+```
+
+**The reel ends where it began.** The carousel is a `steps()` keyframe sequence over a vertical stack whose last frame is the first word again, so the wrap is seamless rather than a snap back to the top.
+
+**Words swap discretely, not by sliding through.** `steps()` means each word holds its full interval and then the next is there — no intermediate half-word state, which is what makes it readable rather than a blur.
+
+**Empty words are ignored**, and **a single word degrades to plain text** with no animation at all. A one-item rotation is a label.
+
+**Reduced motion pins the slot to the first word.**
+
+## Prior art
+
+**motion-primitives' TextLoop and TextRoll**, **react-bits' RotatingText**, and **fancy-components' TextRotate**.
+
+Where Pretui is better: **no timer.** Every upstream drives the rotation from a JavaScript interval holding an index in state; here the whole cycle is one CSS animation computed at render, so it cannot desync, cannot leak, and costs nothing after the first paint. The seamless wrap is also handled by duplicating the first word at the end of the reel rather than by a modulo in a state update.
+
+Where it is thinner: no per-word timing — every word holds for the same `@interval`, so a long phrase gets the same beat as a short one — no direction control, no enter/exit transition beyond the step, and no way to pause on hover or on focus. There is no completion event either, since nothing is watching.
+
+## Accessibility
+
+- **Every word is mirrored in a visually-hidden span**, so a screen reader is told the full set rather than whichever word happened to be in the window when it reached the line. That is the correct trade: a rotating slot has no single truthful moment to announce.
+- **The animated reel is `aria-hidden`**, so the words are not announced twice and the clipped ones are not announced at all.
+- **Reduced motion pins the first word**, which is the one to put first — it is what a reader who has asked for stillness will see, permanently.
+- **Nothing is focusable**, and the rotation is not interactive.
+- **A rotating word cannot carry meaning a reader must act on.** By the time someone reads it, it may have changed. Use it for tone, not for instruction.
+
+## Theming
+
+`--pretui-rotate-count` (the number of words, which sets the keyframe stepping) and `--pretui-rotate-line` (the slot's line height, which is what the window clips to).
+
+Both are derived rather than themed — the rotation's geometry follows its content. Color and typeface come entirely from context, so the slot matches the heading it sits in without a token of its own.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.