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

package/bundled-realms/pretui/components/trim-bar.usage.gts

@@ -0,0 +1,112 @@
+// Pretui — TrimBar usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { TrimBar } from './trim-bar';
+import type { TrimRange } from './trim-bar';
+import { TONE_WAV } from '../media-examples';
+import { Token } from './token';
+
+// ── TrimBar ──────────────────────────────────────────────────────────────
+class TrimBarUsage extends Component {
+  src = TONE_WAV;
+
+  @tracked minGap = 0.2;
+  @tracked step = 0.1;
+  @tracked height = 72;
+  @tracked range = '—';
+
+  setMinGap = (v: number | null) => (this.minGap = v ?? 0.2);
+  setStep = (v: number | null) => (this.step = v ?? 0.1);
+  setHeight = (v: number | null) => (this.height = v ?? 72);
+  noteChange = (r: TrimRange) =>
+    (this.range = `${r.start.toFixed(2)} → ${r.end.toFixed(2)}`);
+
+  get usage(): string {
+    return [
+      '<TrimBar',
+      '  @src={{this.src}}',
+      "  @label='Desk note'",
+      '  @onChange={{this.noteChange}}',
+      '  @onCommit={{this.save}}',
+      '/>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='TrimBar'
+      @description="An in/out selection over any time-based source, on wavesurfer's regions plugin. Tab to the in-point handle and hold ← or →: it moves by a tenth of a second, five times that with Shift, and it cannot cross the out-point — the two handles clamp against each other with a minimum gap rather than swapping. The design decision worth arguing with: the regions plugin's own handles are pointer-only divs inside wavesurfer's shadow root, unreachable by keyboard and unstylable from outside, so the region here is created with drag and resize OFF and the two handles are real focusable elements in the light DOM. One visual, one interaction model, and every trimmer in the wild fails this test."
+      @source={{this.usage}}
+    >
+      <:example>
+        <TrimBar
+          @src={{this.src}}
+          @label='Desk note'
+          @minGap={{this.minGap}}
+          @step={{this.step}}
+          @height={{this.height}}
+          @onChange={{this.noteChange}}
+        />
+        <p class='dm-readout'>
+          <span class='dm-readoutLabel'>@onChange</span>
+          <Token @value={{this.range}} />
+        </p>
+      </:example>
+
+      <:api as |Args|>
+        <Args.String
+          @name='src'
+          @value={{this.src}}
+          @description='URL of the audio to trim over.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='label'
+          @value='Desk note'
+          @description="Accessible name of the trimmer. Each handle derives its own from it — 'Desk note — in point', 'Desk note — out point' — so a screen reader never has two identically named sliders."
+          @hideControls={{true}}
+        />
+        <Args.Number
+          @name='minGap'
+          @value={{this.minGap}}
+          @min={{0.05}}
+          @max={{2}}
+          @defaultValue={{0.1}}
+          @description='Smallest selection the handles may leave, in seconds. This is what stops a keyboard user from collapsing the range to nothing and then being unable to prise the two handles apart again.'
+          @onInput={{this.setMinGap}}
+        />
+        <Args.Number
+          @name='step'
+          @value={{this.step}}
+          @min={{0.05}}
+          @max={{1}}
+          @defaultValue={{0.1}}
+          @description='Seconds moved by one arrow press.'
+          @onInput={{this.setStep}}
+        />
+        <Args.Number
+          @name='height'
+          @value={{this.height}}
+          @min={{48}}
+          @max={{200}}
+          @defaultValue={{72}}
+          @description='Drawing height in px.'
+          @onInput={{this.setHeight}}
+        />
+        <Args.Action
+          @name='onChange'
+          @description='({start, end}) continuously while dragging and on every key press.'
+        />
+        <Args.Action
+          @name='onCommit'
+          @description='({start, end}) once, when a drag ends or a key settles — the one to persist on.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_TRIM_BAR: Record<string, unknown> = {
+  TrimBar: TrimBarUsage,
+};

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

@@ -0,0 +1,122 @@
+// Pretui — Typewriter: text that types itself in, character by character.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+
+// ── Typewriter ───────────────────────────────────────────────────────────
+// Character-by-character reveal — the static-choreography sibling of
+// StreamingText (reading.gts): StreamingText paces live agent output that
+// arrives word-by-word; Typewriter choreographs a string it already holds.
+// Timer-law transcription notes (vs fancy-components' typewriter.tsx,
+// which drives a setTimeout state machine):
+//   - Each char span carries `--pretui-type-i` and the container carries
+//     `--pretui-type-step: 1/@speed s`; the reveal is
+//     `animation-delay: calc(index * var(--step))` with a steps(1) snap —
+//     no interval ticks.
+//   - Unrevealed chars animate from font-size: 0, so the line grows as it
+//     "types" and the caret rides the insertion point instead of parking
+//     at the end of an invisible full-width line.
+//   - No @loop / delete-and-retype cycle: a coherent CSS loop of a
+//     staggered per-char reveal needs per-index keyframe percentages
+//     (every char must share one period), which static scoped CSS cannot
+//     express — so the upstream waitTime/deleteSpeed/loop surface is
+//     deliberately out of scope. Re-render the component to replay.
+export interface TypewriterSignature {
+  Args: {
+    text: string;
+    /** reveal rate in characters per second (Law 7: unitless rate) */
+    speed?: number;
+    /** blinking insertion-point caret */
+    caret?: boolean;
+    /** seconds before the first character lands */
+    startDelay?: number;
+  };
+  Element: HTMLSpanElement;
+}
+
+export class Typewriter extends Component<TypewriterSignature> {
+  get containerStyle(): ReturnType<typeof htmlSafe> {
+    let speed = this.args.speed ?? 16;
+    if (!(speed > 0)) speed = 16;
+    let delay = this.args.startDelay ?? 0;
+    return htmlSafe(
+      `--pretui-type-step: ${(1 / speed).toFixed(4)}s; --pretui-type-delay: ${delay.toFixed(3)}s`,
+    );
+  }
+  get chars(): { ch: string; style: ReturnType<typeof htmlSafe> }[] {
+    return Array.from(this.args.text ?? '').map((ch, i) => ({
+      ch,
+      style: htmlSafe(`--pretui-type-i: ${i}`),
+    }));
+  }
+  <template>
+    <span
+      class='pretui-type'
+      style={{this.containerStyle}}
+      data-test-pretui-typewriter
+      ...attributes
+    >
+      <span aria-hidden='true'>
+        {{#each this.chars as |c|}}<span class='pretui-type-char' style={{c.style}}>{{c.ch}}</span>{{/each}}{{#if @caret}}<span class='pretui-type-caret'></span>{{/if}}
+      </span>
+      <span class='pretui-sr'>{{@text}}</span>
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-type {
+          display: inline;
+        }
+        @keyframes pretui-type-char-in {
+          from {
+            font-size: 0;
+            opacity: 0;
+          }
+          to {
+            font-size: 1em;
+            opacity: 1;
+          }
+        }
+        .pretui-type-char {
+          white-space: pre;
+          animation: pretui-type-char-in 1ms steps(1, end) both;
+          animation-delay: calc(
+            var(--pretui-type-delay, 0s) +
+              var(--pretui-type-i, 0) * var(--pretui-type-step, 0.0625s)
+          );
+        }
+        @keyframes pretui-type-caret-blink {
+          0%,
+          49% {
+            opacity: 1;
+          }
+          50%,
+          100% {
+            opacity: 0;
+          }
+        }
+        .pretui-type-caret {
+          display: inline-block;
+          width: 0.5ch;
+          height: 1em;
+          vertical-align: -0.12em;
+          margin-left: 1px;
+          border-radius: 1px;
+          background: currentColor;
+          animation: pretui-type-caret-blink 1.06s steps(1, end) infinite;
+        }
+        .pretui-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip: rect(0 0 0 0);
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-type-char,
+          .pretui-type-caret {
+            animation: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,45 @@
+## What it is
+
+Character-by-character reveal of a string you already have, on a pure-CSS stagger, with an optional caret that rides the insertion point.
+
+It is the static-choreography sibling of **StreamingText**: StreamingText paces live agent output arriving word by word, Typewriter choreographs a string it already holds. If the text is still arriving, you want the other one.
+
+## The contract
+
+```
+@text (required) — the string to reveal
+@speed?          — reveal rate in characters per second
+@caret?          — blinking insertion-point caret
+@startDelay?     — seconds before the first character lands
+```
+
+**`@speed` is a rate, not a duration.** Characters per second, so the same value reads the same across strings of different lengths. A non-positive speed falls back rather than dividing by zero.
+
+**There are no timers.** Each character span carries its index as a custom property and the container carries one step duration; the reveal is an `animation-delay` of `index × step` with a `steps(1)` snap. The schedule is computed once per render.
+
+**Unrevealed characters animate from zero font-size**, so the line _grows_ as it types and the caret rides the insertion point — rather than parking at the end of an invisible full-width line, which is what a simple opacity reveal gives you.
+
+**There is no loop or delete-and-retype cycle, and that is a real limitation.** A coherent CSS loop of a staggered per-character reveal needs per-index keyframe percentages — every character has to share one period — which static scoped CSS cannot express. The upstream `waitTime`/`deleteSpeed`/`loop` surface is deliberately out of scope. Re-render the component to replay.
+
+## Prior art
+
+**cult-ui's typewriter**, **fancy-components' Typewriter** and **react-bits** — transcribed in behaviour, never in code.
+
+Where Pretui is better: **no timer state machine.** fancy-components drives a `setTimeout` loop that holds the revealed prefix in component state; here the whole reveal is one CSS schedule, which means it cannot desync, cannot leak a timer, and costs nothing after the first paint. The growing line and the riding caret are also more faithful to a real typewriter than the usual full-width reveal.
+
+Where it is thinner: no loop, no delete-and-retype, no per-word or per-line mode, no pause/resume, and no completion callback — there is no JavaScript watching the animation, so nothing to fire one from.
+
+## Accessibility
+
+- **The animated copy is chopped into per-character spans and hidden**, with the whole string mirrored in a visually-hidden span beside it. Without that, a screen reader would announce the text one character at a time, which is the standard failure of every per-character effect.
+- **Reduced motion collapses it to the finished line.** The base styles _are_ the end state and the keyframes only supply the choreography, so `animation: none` is a complete kill switch rather than a freeze at an arbitrary frame.
+- **The caret is decoration** and carries no meaning; it is not an insertion point anyone can type at.
+- **Text that is still animating is already fully available** to assistive technology, so a reader is never waiting on the animation to learn what it says.
+
+## Theming
+
+`--pretui-type-step` (seconds per character, derived from `@speed`), `--pretui-type-i` (each character's index), `--pretui-type-delay` (from `@startDelay`).
+
+The effect inherits its color and typeface entirely from context — there is no ink token — which is what lets it be dropped into a heading, a label or a paragraph without looking like a different component. A theme changes how this looks by changing 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/typewriter.usage.gts

@@ -0,0 +1,105 @@
+// Pretui — Typewriter 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 { Typewriter } from './typewriter';
+
+// ── Typewriter — fresh page (no upstream knob rig) ───────────────────────
+class TypewriterUsage extends Component {
+  @tracked text =
+    'Confirm the spring booking — Da Hong Pao, Wuyishan lot B-1181.';
+  @tracked speed = 16;
+  @tracked caret = true;
+  @tracked startDelay = 0;
+  @tracked run = 0;
+  setText = (v: string) => (this.text = v);
+  setSpeed = (v: number | null) => (this.speed = v ?? 16);
+  setCaret = (v: boolean) => (this.caret = v);
+  setStartDelay = (v: number | null) => (this.startDelay = v ?? 0);
+  replay = () => (this.run = this.run + 1);
+  // identity-keyed single-item list: bumping run tears down and rebuilds
+  // the component, restarting its CSS animations — the timer-free replay
+  get runKey(): number[] {
+    return [this.run];
+  }
+  get usage() {
+    let bits = [`@text='${this.text}'`];
+    if (this.speed !== 16) bits.push(`@speed={{${this.speed}}}`);
+    if (this.caret) bits.push('@caret={{true}}');
+    if (this.startDelay) bits.push(`@startDelay={{${this.startDelay}}}`);
+    return `<Typewriter ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Typewriter'
+      @description='Character-by-character reveal on a pure-CSS stagger — the static-choreography sibling of StreamingText (reading.gts): StreamingText paces live agent output arriving word-by-word, Typewriter choreographs a string it already holds. The line grows as it types, so the caret rides the insertion point.'
+      @source={{this.usage}}
+    >
+      <:example>
+        {{#each this.runKey key='@identity' as |run|}}
+          <Typewriter
+            @text={{this.text}}
+            @speed={{this.speed}}
+            @caret={{this.caret}}
+            @startDelay={{this.startDelay}}
+            data-run={{run}}
+          />
+        {{/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 to type out. The full text is mirrored in an sr-only span; the animated copy is aria-hidden.'
+          @onInput={{this.setText}}
+        />
+        <Args.Number
+          @name='speed'
+          @defaultValue={{16}}
+          @value={{this.speed}}
+          @min={{1}}
+          @max={{60}}
+          @step={{1}}
+          @description='Reveal rate in characters per second — each char lands at index / speed seconds.'
+          @onInput={{this.setSpeed}}
+        />
+        <Args.Bool
+          @name='caret'
+          @defaultValue={{false}}
+          @value={{this.caret}}
+          @description='Blinking insertion-point caret; blinks via CSS steps, sits after the last revealed character.'
+          @onInput={{this.setCaret}}
+        />
+        <Args.Number
+          @name='startDelay'
+          @defaultValue={{0}}
+          @value={{this.startDelay}}
+          @min={{0}}
+          @max={{5}}
+          @step={{0.5}}
+          @description='Seconds before the first character lands — for sequencing several Typewriters into one choreography.'
+          @onInput={{this.setStartDelay}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-demo-replay {
+        margin-top: 12px;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TYPEWRITER: Record<string, unknown> = {
+  Typewriter: TypewriterUsage,
+};