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

package/bundled-realms/pretui/components/terminal-animation.gts

@@ -0,0 +1,355 @@
+// Pretui — TerminalAnimation: a replayed command-line session with no JavaScript timing.
+import Component from '@glimmer/component';
+import { cssStyleFrom } from '../pretui-css';
+
+// ── TerminalAnimation ────────────────────────────────────────────────────
+// A command-line session, replayed. The genre's whole appeal is the sense of
+// something happening in order, and the genre's whole implementation problem
+// is that everyone reaches for a timer to get it.
+//
+// There is no timer here, and there is no JavaScript timing of any kind. The
+// schedule is computed once, as arithmetic, into two custom properties per
+// line: when it appears, and (for a command) how long its characters take.
+// The appearance is one keyframe with `animation-delay`; the typing is a
+// `width` sweep with a `steps(n)` timing function set inline from the line's
+// own character count, so each glyph lands on a character boundary.
+//
+// Consequences worth stating:
+//   · Replay is identity, not a clock. Change `@replayToken` and the rows
+//     are re-created, so their animations start over. That is the whole
+//     mechanism.
+//   · `prefers-reduced-motion: reduce` lands on the FINISHED transcript —
+//     every line present at full width — never on a frozen midpoint.
+//   · The animated transcript is `aria-hidden` and mirrored by a complete
+//     visually-hidden copy, the same contract `StreamingText` uses: a
+//     screen reader gets the whole session at once instead of a text that
+//     appears to be still arriving.
+
+export type TerminalLineKind = 'command' | 'output' | 'error' | 'comment';
+
+export interface TerminalLine {
+  /** stable id */
+  id: string;
+  /** what kind of line this is (default 'output') */
+  kind?: TerminalLineKind;
+  /** the line's text */
+  text: string;
+  /** prompt shown before a command (default '$') */
+  prompt?: string;
+}
+
+interface TerminalRow {
+  key: string;
+  id: string;
+  kind: TerminalLineKind;
+  text: string;
+  prompt: string;
+  isCommand: boolean;
+  showCaret: boolean;
+  lineStyle: ReturnType<typeof cssStyleFrom>;
+  typeStyle: ReturnType<typeof cssStyleFrom>;
+}
+
+export interface TerminalAnimationSignature {
+  Args: {
+    /** the session, in the order it ran */
+    lines: TerminalLine[];
+    /** window title (default 'Terminal') */
+    title?: string;
+    /** seconds before the first line appears (default 0.2) */
+    startDelay?: number;
+    /** characters per second while a command types (default 26) */
+    charRate?: number;
+    /**
+     * seconds a non-command line holds the stage before the next one starts
+     * (default 0.45). Separate from `charRate` on purpose — typing and
+     * reading are different rates because they read differently (Law 7).
+     */
+    lineDelay?: number;
+    /** type commands out character by character (default true) */
+    typing?: boolean;
+    /** show the blinking caret after the last line (default true) */
+    caret?: boolean;
+    /**
+     * change this to replay. Every row's key includes it, so a new value
+     * re-creates the rows and their CSS animations start from zero — no
+     * timer, no imperative restart.
+     */
+    replayToken?: string;
+    /** accessible name for the transcript (default 'Terminal session') */
+    label?: string;
+  };
+  Element: HTMLDivElement;
+}
+
+export class TerminalAnimation extends Component<TerminalAnimationSignature> {
+  get title(): string {
+    return this.args.title ?? 'Terminal';
+  }
+  get label(): string {
+    return this.args.label ?? 'Terminal session';
+  }
+  get caret(): boolean {
+    return this.args.caret ?? true;
+  }
+  private get typing(): boolean {
+    return this.args.typing ?? true;
+  }
+  private get charRate(): number {
+    let rate = Number(this.args.charRate ?? 26);
+    return Number.isFinite(rate) && rate > 0 ? rate : 26;
+  }
+  private get lineDelay(): number {
+    let delay = Number(this.args.lineDelay ?? 0.45);
+    return Number.isFinite(delay) && delay >= 0 ? delay : 0.45;
+  }
+  private get startDelay(): number {
+    let delay = Number(this.args.startDelay ?? 0.2);
+    return Number.isFinite(delay) && delay >= 0 ? delay : 0.2;
+  }
+
+  /**
+   * The schedule, computed once. Every value written into a style here is a
+   * number this component formatted — never a caller string — so it needs no
+   * `cssValue` round trip; the only caller strings in the component are text
+   * nodes.
+   */
+  get rows(): TerminalRow[] {
+    let lines = this.args.lines ?? [];
+    let token = this.args.replayToken ?? '0';
+    let at = this.startDelay;
+    let rows: TerminalRow[] = [];
+    for (let i = 0; i < lines.length; i++) {
+      let line = lines[i]!;
+      let kind: TerminalLineKind = line.kind ?? 'output';
+      let isCommand = kind === 'command';
+      let chars = line.text.length;
+      let typeDuration =
+        isCommand && this.typing && chars > 0 ? chars / this.charRate : 0;
+      rows.push({
+        key: token + ':' + line.id,
+        id: line.id,
+        kind,
+        text: line.text,
+        prompt: line.prompt ?? '$',
+        isCommand,
+        showCaret: this.caret && i === lines.length - 1,
+        lineStyle: cssStyleFrom(['--pretui-term-at: ' + at.toFixed(3) + 's']),
+        typeStyle:
+          typeDuration > 0
+            ? cssStyleFrom([
+                '--pretui-term-at: ' + at.toFixed(3) + 's',
+                '--pretui-term-dur: ' + typeDuration.toFixed(3) + 's',
+                '--pretui-term-ch: ' + chars + 'ch',
+                'animation-timing-function: steps(' + chars + ', end)',
+              ])
+            : undefined,
+      });
+      at += typeDuration + this.lineDelay;
+    }
+    return rows;
+  }
+
+  /** the whole session as one string, for the screen-reader mirror */
+  get transcript(): string {
+    return (this.args.lines ?? [])
+      .map((line) =>
+        line.kind === 'command'
+          ? (line.prompt ?? '$') + ' ' + line.text
+          : line.text,
+      )
+      .join('\n');
+  }
+
+  <template>
+    <div class='pretui-term' data-test-pretui-terminal-animation ...attributes>
+      <div class='pretui-term-bar'>
+        <span class='pretui-term-dots' aria-hidden='true'>
+          <i></i><i></i><i></i>
+        </span>
+        <span class='pretui-term-title'>{{this.title}}</span>
+      </div>
+      <figure class='pretui-term-screen'>
+        <figcaption class='pretui-sr'>{{this.label}}</figcaption>
+        {{! Each line is its own block with `white-space: pre`, so authoring
+            whitespace BETWEEN lines cannot leak into the transcript — the
+            reason this is a stack of blocks rather than one <pre>. }}
+        <div class='pretui-term-visual' aria-hidden='true'>
+          {{#each this.rows key='key' as |row|}}
+            <span
+              class='pretui-term-line'
+              data-kind={{row.kind}}
+              style={{row.lineStyle}}
+            >{{#if row.isCommand}}<span
+                  class='pretui-term-prompt'
+                >{{row.prompt}}</span>{{/if}}{{#if row.typeStyle}}<span
+                  class='pretui-term-type'
+                  style={{row.typeStyle}}
+                >{{row.text}}</span>{{else}}<span
+                  class='pretui-term-text'
+                >{{row.text}}</span>{{/if}}{{#if row.showCaret}}<span
+                  class='pretui-term-caret'
+                ></span>{{/if}}</span>
+          {{/each}}
+        </div>
+        <span class='pretui-sr'>{{this.transcript}}</span>
+      </figure>
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-term {
+          border-radius: var(--radius-surface, 12px);
+          overflow: hidden;
+          background: var(--pretui-term-bg, var(--boxel-700));
+          box-shadow: var(
+            --pretui-shadow-card,
+            0 0 0 1px var(--border),
+            0 1px 2px rgb(0 0 0 / 0.2)
+          );
+        }
+        .pretui-term-bar {
+          display: flex;
+          align-items: center;
+          gap: 8px;
+          height: 30px;
+          padding: 0 10px;
+          background: color-mix(
+            in oklch,
+            var(--pretui-term-bg, var(--boxel-700)) 85%,
+            #ffffff
+          );
+        }
+        .pretui-term-dots {
+          display: inline-flex;
+          gap: 5px;
+        }
+        .pretui-term-dots i {
+          width: 9px;
+          height: 9px;
+          border-radius: 50%;
+          background: color-mix(
+            in oklch,
+            var(--pretui-term-bg, var(--boxel-700)) 55%,
+            #ffffff
+          );
+        }
+        .pretui-term-title {
+          font-family: var(--font-mono);
+          font-size: 11px;
+          color: color-mix(
+            in oklch,
+            var(--pretui-term-bg, var(--boxel-700)) 30%,
+            #ffffff
+          );
+        }
+        .pretui-term-screen {
+          position: relative;
+          margin: 0;
+          padding: 12px 14px;
+          min-height: var(--pretui-term-min, 8rem);
+        }
+        .pretui-term-visual {
+          margin: 0;
+          font-family: var(--font-mono);
+          font-size: var(--pretui-term-size, 12px);
+          line-height: 1.65;
+          overflow-x: auto;
+          color: color-mix(in oklch, var(--pretui-term-bg, var(--boxel-700)) 18%, var(--boxel-light));
+        }
+        .pretui-term-line {
+          display: block;
+          white-space: pre;
+          opacity: 0;
+          animation: pretui-term-show 140ms linear var(--pretui-term-at, 0s) both;
+        }
+        @keyframes pretui-term-show {
+          from {
+            opacity: 0;
+          }
+          to {
+            opacity: 1;
+          }
+        }
+        .pretui-term-line[data-kind='error'] {
+          color: color-mix(in oklch, var(--destructive) 70%, var(--boxel-light));
+        }
+        .pretui-term-line[data-kind='comment'] {
+          color: color-mix(in oklch, var(--pretui-term-bg, var(--boxel-700)) 48%, var(--boxel-light));
+        }
+        .pretui-term-line[data-kind='command'] {
+          color: var(--boxel-light);
+        }
+        .pretui-term-prompt {
+          display: inline-block;
+          margin-right: 0.6ch;
+          color: color-mix(in oklch, var(--primary) 45%, var(--boxel-light));
+        }
+        /* the typewriter: a width sweep whose step count is this line's own
+           character count, set inline as an authored declaration */
+        .pretui-term-type {
+          display: inline-block;
+          overflow: hidden;
+          white-space: pre;
+          vertical-align: bottom;
+          width: 0;
+          animation-name: pretui-term-type;
+          animation-duration: var(--pretui-term-dur, 0.6s);
+          animation-delay: var(--pretui-term-at, 0s);
+          animation-fill-mode: both;
+        }
+        @keyframes pretui-term-type {
+          from {
+            width: 0;
+          }
+          to {
+            width: var(--pretui-term-ch, 100%);
+          }
+        }
+        .pretui-term-caret {
+          display: inline-block;
+          width: 0.6ch;
+          height: 1em;
+          margin-left: 0.2ch;
+          vertical-align: text-bottom;
+          background: currentColor;
+          animation: pretui-term-blink 1.1s steps(1, end) infinite;
+        }
+        @keyframes pretui-term-blink {
+          0%,
+          50% {
+            opacity: 1;
+          }
+          50.01%,
+          100% {
+            opacity: 0;
+          }
+        }
+        .pretui-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: pre;
+          margin: 0;
+        }
+        /* the end state, not a frozen midpoint: the whole session, at rest */
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-term-line {
+            animation: none;
+            opacity: 1;
+          }
+          .pretui-term-type {
+            animation: none;
+            width: auto;
+          }
+          .pretui-term-caret {
+            animation: none;
+            opacity: 1;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/terminal-animation.md

@@ -0,0 +1,49 @@
+## What it is
+
+A command-line session, replayed: commands typing out, output appearing, a caret blinking at the end.
+
+The genre's appeal is the sense of something happening in order. The genre's implementation problem is that everyone reaches for a timer to get it. There is none here.
+
+## The contract
+
+```
+@lines (required) — the session, in the order it ran
+@title?       — window title. Default 'Terminal'
+@startDelay?  — seconds before the first line appears. Default 0.2
+@charRate?    — characters per second while a command types. Default 26
+@lineDelay?   — seconds a non-command line holds the stage. Default 0.45
+@typing?      — type commands out character by character. Default true
+@caret?       — show the blinking caret after the last line. Default true
+@replayToken? — change this to replay
+@label?       — accessible name for the transcript. Default 'Terminal session'
+```
+
+**No JavaScript timing of any kind.** The schedule is computed once, as arithmetic, into two custom properties per line — when it appears, and how long its characters take. The entrance is one `animation-delay`; the typing is a width sweep whose `steps()` count is that line's own character count.
+
+**Replay is identity, not a clock.** Every row's key includes `@replayToken`, so a new value re-creates the rows and their CSS animations start from zero. No timer, no imperative restart.
+
+**`@charRate` and `@lineDelay` are separate on purpose.** Typing and reading are different rates because they read differently — a command appearing at reading speed looks broken, and output appearing at typing speed is unreadable.
+
+## Prior art
+
+The animated-terminal component in developer-marketing pages.
+
+Where Pretui is better: the timer-free schedule, and replay by identity. Every implementation of this genre holds an index in state and advances it on an interval, which means it can desync from a re-render, leak on unmount, and cannot be replayed without an imperative handle.
+
+Where it is thinner: no interaction — this is a replay, not a terminal — no ANSI colour parsing, no scrollback, and no pause or scrub.
+
+## Accessibility
+
+- **The transcript is named**, defaulting to "Terminal session".
+- **The window chrome is `aria-hidden`.** The dots are decoration and announcing them would precede every session with noise.
+- **The visual layer is `aria-hidden`**, which means the session's content needs to reach assistive technology as text — a reader should get the transcript, not a description of an animation.
+- **Motion here is decorative in the strictest sense.** Nothing about the session's meaning depends on the order arriving over time; reduced motion should present it complete.
+- **A typing animation delays legibility** for anyone watching, and `@typing={{false}}` is the honest setting for a page where the content matters more than the effect.
+
+## Theming
+
+`--pretui-term-bg`, `--pretui-term-size`, `--pretui-term-ch` (the character cell the width sweep measures in), `--pretui-term-at` and `--pretui-term-dur` (each line's start and duration), `--pretui-term-min`, over `--pretui-shadow-card`, `--pretui-shadow-hairline` and `--pretui-ease-enter`.
+
+`--pretui-term-ch` is the load-bearing one: the typing sweep is a width animation, so it needs the character cell to be a known quantity, and a theme that changes the mono face without checking it will produce typing that stops short of or overshoots its own text.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/terminal-animation.usage.gts

@@ -0,0 +1,110 @@
+// Pretui — TerminalAnimation usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { TerminalAnimation } from './terminal-animation';
+import type { TerminalLine } from './terminal-animation';
+
+// ── TerminalAnimation ────────────────────────────────────────────────────
+const SESSION: TerminalLine[] = [
+  { id: 'l1', kind: 'comment', text: '# reprice the Kandy catalogue' },
+  { id: 'l2', kind: 'command', text: 'boxel lots pull --auction kandy-2025-11' },
+  { id: 'l3', text: 'pulled 18 lots · 4 unsold' },
+  { id: 'l4', kind: 'command', text: 'boxel price --rule pricing.gts --mean 2025' },
+  { id: 'l5', text: 'lot 104  84.1  −2.8% netted' },
+  { id: 'l6', text: 'lot 118  88.6  +9.4% netted' },
+  { id: 'l7', kind: 'error', text: 'warn: freight quote for colombo expires in 6 days' },
+  { id: 'l8', kind: 'command', text: 'boxel receipt changeset-m3k1' },
+  { id: 'l9', text: 'immutable · 2 files · +24 −7' },
+];
+
+class TerminalAnimationUsage extends GlimmerComponent {
+  @tracked replay = 1;
+  @tracked charRate = 26;
+  @tracked lineDelay = 0.45;
+  @tracked typing = true;
+
+  setCharRate = (rate: number) => (this.charRate = rate);
+  setLineDelay = (delay: number) => (this.lineDelay = delay);
+  setTyping = (typing: boolean) => (this.typing = typing);
+  again = () => (this.replay = this.replay + 1);
+
+  get replayToken(): string {
+    return 'run-' + this.replay;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='TerminalAnimation'
+      @description='A command-line session, replayed. The genre’s appeal is the sense of something happening in order; the genre’s implementation problem is that everyone reaches for a timer to get it. There is none here, and no JavaScript timing of any kind: the schedule is computed once, as arithmetic, into two custom properties per line — when it appears, and how long its characters take — so the entrance is one animation-delay and the typing is a width sweep whose steps() count is that line’s own character count. Replay is identity rather than a clock: change @replayToken and the rows are re-created, so their animations start over. Typing and reading are separate rates because they read differently. The animated transcript is aria-hidden with a complete visually-hidden mirror — the StreamingText contract — so a screen reader gets the whole session at once instead of a text that appears to still be arriving, and prefers-reduced-motion lands on the finished transcript, never on a frozen midpoint.'
+    >
+      <:example>
+        <TerminalAnimation
+          @lines={{SESSION}}
+          @title='sourcing-desk — boxel'
+          @charRate={{this.charRate}}
+          @lineDelay={{this.lineDelay}}
+          @typing={{this.typing}}
+          @replayToken={{this.replayToken}}
+          @label='Repricing the Kandy catalogue'
+        />
+        <Button
+          @tone='neutral'
+          @appearance='outlined'
+          @size='s'
+          {{on 'click' this.again}}
+        >Replay</Button>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='lines'
+          @description='The session in the order it ran: { id, kind?: command | output | error | comment, text, prompt? }. Only command lines type; everything else appears whole, which is what a real terminal does.'
+          @value={{SESSION}}
+        />
+        <Args.Number
+          @name='charRate'
+          @description='Characters per second while a command types. Separate knob from @lineDelay on purpose — most libraries ship one "speed" and stop.'
+          @value={{this.charRate}}
+          @onInput={{this.setCharRate}}
+          @defaultValue={{26}}
+          @min={{6}}
+          @max={{80}}
+        />
+        <Args.Number
+          @name='lineDelay'
+          @description='Seconds a non-command line holds the stage before the next one starts.'
+          @value={{this.lineDelay}}
+          @onInput={{this.setLineDelay}}
+          @defaultValue={{0.45}}
+          @min={{0}}
+          @max={{2}}
+          @step={{0.05}}
+        />
+        <Args.Bool
+          @name='typing'
+          @description='Type commands out character by character. Off, every line simply appears on schedule — which is also what reduced motion collapses to, minus the schedule.'
+          @value={{this.typing}}
+          @onInput={{this.setTyping}}
+          @defaultValue={{true}}
+        />
+        <Args.String
+          @name='replayToken'
+          @description='Change it to replay. Every row key includes it, so a new value re-creates the rows and their CSS animations restart — no timer, no imperative restart, no ref.'
+          @value={{this.replayToken}}
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='title / label / startDelay / caret'
+          @description='The window title, the accessible name for the transcript, the pause before the first line, and whether the blinking caret trails the last line.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_TERMINAL_ANIMATION: Record<string, unknown> = {
+  TerminalAnimation: TerminalAnimationUsage,
+};