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

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

@@ -0,0 +1,376 @@
+// Pretui — Waveform: an audio waveform on wavesurfer.js with a keyboard-operable playhead.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { formatClock } from '../internal/reading-format';
+import { cssDeclaration, cssStyleFrom } from '../pretui-css';
+import { Token } from './token';
+import { clamp, stepsFor, waveDelta, waveEngine } from '../internal/media-wave';
+import type { WaveEngine, WavePhase, WaveSteps } from '../internal/media-wave';
+
+/** "0:03 of 0:06" — what a screen reader should say about a playhead. A bare
+ * `aria-valuenow` of `3.417` is technically correct and useless. */
+export function waveValueText(current: number, duration: number): string {
+  return `${formatClock(current)} of ${formatClock(duration)}`;
+}
+
+// ── The lifecycle contract ───────────────────────────────────────────────
+
+// ── Waveform ─────────────────────────────────────────────────────────────
+
+export interface WaveformSignature {
+  Args: {
+    /** URL of the audio. Passed through untouched — the component never
+     * creates or revokes an object URL, so a blob URL stays the caller's. */
+    src: string;
+    /** Accessible name of the scrubber. Required in practice: "slider" with
+     * no name is the single most common failure in this category. */
+    label: string;
+    /** Drawing height in px. Default 96. Reserved before the audio lands, so
+     * nothing reflows when it does. */
+    height?: number;
+    /** Bar width in px, or 0 for a continuous waveform. Default 3. */
+    barWidth?: number;
+    /** Gap between bars in px. Default 2. */
+    barGap?: number;
+    /** Scale peaks to the loudest sample. Default `true`. */
+    normalize?: boolean;
+    /** Seconds moved by one arrow press. Default 1. */
+    step?: number;
+    /** Hide the transport row and the readout, leaving only the wave. */
+    bare?: boolean;
+    onReady?: (duration: number) => void;
+    onSeek?: (seconds: number) => void;
+    onPlayingChange?: (playing: boolean) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class Waveform extends Component<WaveformSignature> {
+  @tracked phase: WavePhase = 'idle';
+  @tracked message = '';
+  @tracked duration = 0;
+  @tracked current = 0;
+  @tracked playing = false;
+
+  engine: WaveEngine | null = null;
+
+  get height(): number {
+    const raw = this.args.height;
+    return typeof raw === 'number' && raw >= 24 ? Math.round(raw) : 96;
+  }
+  get barWidth(): number {
+    const raw = this.args.barWidth;
+    return typeof raw === 'number' && raw >= 0 ? raw : 3;
+  }
+  get barGap(): number {
+    const raw = this.args.barGap;
+    return typeof raw === 'number' && raw >= 0 ? raw : 2;
+  }
+  get normalize(): boolean {
+    return this.args.normalize ?? true;
+  }
+  get wantsRegions(): boolean {
+    return false;
+  }
+  get interact(): boolean {
+    return true;
+  }
+  get engineKey(): string {
+    return [this.height, this.barWidth, this.barGap, this.normalize].join(':');
+  }
+  get steps(): WaveSteps {
+    const fine = typeof this.args.step === 'number' && this.args.step > 0 ? this.args.step : 1;
+    return stepsFor(this.duration, fine);
+  }
+  get valueText(): string {
+    return waveValueText(this.current, this.duration);
+  }
+  get readyMax(): number {
+    return this.duration > 0 ? this.duration : 0;
+  }
+  get boxStyle() {
+    return cssStyleFrom([cssDeclaration('--pretui-wave-height', `${this.height}px`)]);
+  }
+  get statusLabel(): string {
+    switch (this.phase) {
+      case 'loading':
+        return 'Decoding';
+      case 'error':
+        return 'Failed';
+      case 'ready':
+        return this.playing ? 'Playing' : 'Ready';
+      default:
+        return 'Idle';
+    }
+  }
+  get isLoading(): boolean {
+    return this.phase === 'loading';
+  }
+  get isFailed(): boolean {
+    return this.phase === 'error';
+  }
+  /* Glimmer binds a dynamic attribute through the PROPERTY, so a boolean
+     attribute must be `true | undefined` — `false` and `''` both land as a
+     falsy property assignment that silently does nothing, and `'false'` is a
+     truthy string. This is the trap that cost the media territory the most
+     time; it is spelled out here rather than repeated at four call sites. */
+  get ariaDisabled(): 'true' | undefined {
+    return this.phase === 'ready' ? undefined : 'true';
+  }
+  get transportDisabled(): true | undefined {
+    return this.phase === 'ready' ? undefined : true;
+  }
+
+  onEngine = (engine: WaveEngine | null): void => {
+    this.engine = engine;
+  };
+  onPhase = (phase: WavePhase, message: string): void => {
+    this.phase = phase;
+    this.message = message;
+  };
+  onDuration = (seconds: number): void => {
+    this.duration = Number.isFinite(seconds) ? seconds : 0;
+    if (this.phase === 'ready') {
+      this.args.onReady?.(this.duration);
+    }
+  };
+  onTime = (seconds: number): void => {
+    this.current = Number.isFinite(seconds) ? seconds : 0;
+  };
+  onPlaying = (playing: boolean): void => {
+    this.playing = playing;
+    this.args.onPlayingChange?.(playing);
+  };
+  onRegionReady = (): void => undefined;
+
+  seekTo = (seconds: number): void => {
+    const next = clamp(seconds, 0, this.duration);
+    this.current = next;
+    this.engine?.setTime(next);
+    this.args.onSeek?.(next);
+  };
+
+  togglePlay = (): void => {
+    if (!this.engine || this.phase !== 'ready') {
+      return;
+    }
+    if (this.engine.isPlaying()) {
+      this.engine.pause();
+    } else {
+      this.engine.play();
+    }
+  };
+
+  // `{{on}}` types its handler as `(event: Event) => void`; the narrow type
+  // is asserted at the top of each handler rather than in the signature.
+  handleKey = (raw: Event): void => {
+    const event = raw as KeyboardEvent;
+    if (this.phase !== 'ready') {
+      return;
+    }
+    if (event.key === 'Home') {
+      event.preventDefault();
+      this.seekTo(0);
+      return;
+    }
+    if (event.key === 'End') {
+      event.preventDefault();
+      this.seekTo(this.duration);
+      return;
+    }
+    if (event.key === ' ' || event.key === 'Enter') {
+      event.preventDefault();
+      this.togglePlay();
+      return;
+    }
+    const delta = waveDelta(event, this.steps);
+    if (delta !== null) {
+      event.preventDefault();
+      this.seekTo(this.current + delta);
+    }
+  };
+
+  <template>
+    <div
+      class='pretui-wave'
+      data-phase={{this.phase}}
+      data-playing={{if this.playing 'true' 'false'}}
+      data-test-pretui-waveform
+      ...attributes
+    >
+      <div class='pretui-wave-box' style={{this.boxStyle}}>
+        <div
+          class='pretui-wave-canvas'
+          {{waveEngine this @src this.engineKey}}
+        ></div>
+        {{! The scrubber is an EMPTY overlay, deliberately: `role='slider'`
+            takes presentational children only, so the waveform cannot live
+            inside it. It is pointer-transparent, so a click still reaches
+            wavesurfer's own seek; its job is to be the one tab stop and to
+            carry the announced value. }}
+        <div
+          class='pretui-wave-scrub'
+          role='slider'
+          tabindex='0'
+          aria-label={{@label}}
+          aria-valuemin='0'
+          aria-valuemax={{this.readyMax}}
+          aria-valuenow={{this.current}}
+          aria-valuetext={{this.valueText}}
+          aria-disabled={{this.ariaDisabled}}
+          {{on 'keydown' this.handleKey}}
+        ></div>
+        {{#if this.isLoading}}
+          <p class='pretui-wave-veil'>Decoding audio…</p>
+        {{else if this.isFailed}}
+          <p class='pretui-wave-veil pretui-wave-veil--bad'>
+            <span aria-hidden='true'>⚠</span>
+            {{if this.message this.message 'This audio could not be decoded.'}}
+          </p>
+        {{/if}}
+      </div>
+
+      {{#unless @bare}}
+        <div class='pretui-wave-bar'>
+          <button
+            type='button'
+            class='pretui-wave-play'
+            disabled={{this.transportDisabled}}
+            aria-pressed={{if this.playing 'true' 'false'}}
+            {{on 'click' this.togglePlay}}
+          >
+            <span aria-hidden='true'>{{if this.playing '❚❚' '▶'}}</span>
+            <span class='pretui-wave-playText'>{{if this.playing 'Pause' 'Play'}}</span>
+          </button>
+          <span class='pretui-wave-time'>
+            <Token @value={{this.valueText}} />
+          </span>
+          <span class='pretui-wave-status' data-phase={{this.phase}}>
+            {{this.statusLabel}}
+          </span>
+        </div>
+      {{/unless}}
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-wave {
+          display: flex;
+          flex-direction: column;
+          gap: 8px;
+          min-width: 0;
+        }
+        .pretui-wave-box {
+          position: relative;
+          /* Reserved BEFORE the audio lands, so the decode never reflows the
+             page around it — the Law-8 corollary. */
+          min-height: var(--pretui-wave-height, 96px);
+          padding: 6px;
+          border-radius: var(--radius);
+          background: color-mix(
+            in oklch,
+            var(--foreground) 4%,
+            var(--card)
+          );
+          box-shadow: var(
+            --pretui-shadow-hairline,
+            0 0 0 1px var(--border)
+          );
+        }
+        .pretui-wave-scrub {
+          position: absolute;
+          inset: 0;
+          border-radius: var(--radius);
+          /* Focusable but pointer-transparent: the tab stop is here, the
+             pointer seek is wavesurfer's, and neither steals from the other. */
+          pointer-events: none;
+        }
+        .pretui-wave-scrub:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-wave-canvas {
+          min-height: var(--pretui-wave-height, 96px);
+        }
+        .pretui-wave-veil {
+          position: absolute;
+          inset: 0;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          gap: 6px;
+          margin: 0;
+          padding: 0 12px;
+          text-align: center;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+          background: color-mix(
+            in oklch,
+            var(--card) 82%,
+            transparent
+          );
+          border-radius: var(--radius);
+        }
+        .pretui-wave-veil--bad {
+          color: var(--pretui-destructive-ink, var(--boxel-danger));
+        }
+        .pretui-wave-bar {
+          display: flex;
+          align-items: center;
+          gap: 10px;
+          min-width: 0;
+        }
+        .pretui-wave-play {
+          display: inline-flex;
+          align-items: center;
+          gap: 6px;
+          padding: 4px 10px;
+          border: 0;
+          border-radius: 999px;
+          font: inherit;
+          font-size: var(--text-ui-sm, 11.5px);
+          font-weight: 600;
+          color: var(--primary-foreground);
+          background: var(--primary);
+          cursor: pointer;
+        }
+        .pretui-wave-play:disabled {
+          opacity: 0.5;
+          cursor: default;
+        }
+        .pretui-wave-play:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-wave-playText {
+          letter-spacing: 0.01em;
+        }
+        .pretui-wave-time {
+          margin-inline-end: auto;
+        }
+        /* State carries a word, not only a hue. */
+        .pretui-wave-status {
+          font-size: var(--text-ui-xs, 10.5px);
+          font-weight: 600;
+          letter-spacing: 0.04em;
+          text-transform: uppercase;
+          color: var(--muted-foreground);
+        }
+        .pretui-wave-status[data-phase='error'] {
+          color: var(--pretui-destructive-ink, var(--boxel-danger));
+        }
+        .pretui-wave-status[data-phase='ready'] {
+          color: var(--pretui-primary-ink, var(--boxel-highlight-hover));
+        }
+        .dark .pretui-wave-box {
+          background: color-mix(
+            in oklch,
+            var(--foreground) 8%,
+            var(--card)
+          );
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,56 @@
+## What it is
+
+An audio waveform you can operate: the drawing, a transport, a readout, and a scrubber that is a real slider rather than a canvas you can only click at.
+
+Use it when the shape of the audio matters — reviewing a recording, finding a moment, checking levels. When it does not, **AudioPlayer** is the smaller component. For selecting an in/out range over audio, **TrimBar** is the one built on the same engine.
+
+## The contract
+
+```
+@src (required)   — URL of the audio; passed through untouched
+@label (required) — accessible name of the scrubber
+@height?          — drawing height in px. Default 96
+@barWidth?        — bar width in px, or 0 for a continuous waveform. Default 3
+@barGap?          — gap between bars in px. Default 2
+@normalize?       — scale peaks to the loudest sample. Default true
+@step?            — seconds moved by one arrow press. Default 1
+@bare?            — hide the transport row and the readout, leaving only the wave
+@onReady?         — fires with the duration
+@onSeek?          — fires with the new position in seconds
+@onPlayingChange? — fires when playback starts or stops
+```
+
+**`@src` is passed through untouched.** The component never creates or revokes an object URL, so a blob URL stays the caller's to revoke.
+
+**`@label` is required in practice, and the type says so.** A `slider` with no name is the single most common failure in this category.
+
+**The height is reserved before the audio lands**, so nothing reflows when the decode finishes.
+
+**Failure is a state, not a crash.** Construction is wrapped, and `phase` — `idle → loading → ready`, or `error` — is part of the public contract, so a caller and a test can both assert on what happened without asserting that a decode succeeded. That matters more than it sounds: a headless browser has no real media pipeline, so `error` is the _expected_ outcome in the test harness.
+
+**`@bare` drops the transport and the readout but keeps the scrubber.** The keyboard path is never what gets removed.
+
+## Prior art
+
+**WaveSurfer.js** (BSD-3) does the drawing and the decode, owned by a modifier so its lifecycle is tied to the element rather than to a module.
+
+Where Pretui is better, and it is the whole reason this component exists: **wavesurfer gives pointer seeking and nothing else** — no tab stop, no arrow keys, no announced position. Every wavesurfer example on the web is `WaveSurfer.create({container: '#waveform'})` with a play button and no keyboard path at all. Here the wave is a `role='slider'` with one tab stop, ←/→ by `@step`, Shift for a coarse step, PageUp/PageDown, Home/End, Space to play, and an `aria-valuetext` that says "0:03 of 0:06".
+
+Where it is thinner: no regions or markers exposed as a contract (the plugin is loaded, but **TrimBar** is the component that surfaces it), no zoom into the timeline, no multi-channel or spectrogram view, no peak pre-computation — every instance decodes the file itself, which is fine for one and expensive for a list.
+
+## Accessibility
+
+- **The scrubber is a `role='slider'` with a name, a value and a phase.** `aria-valuemin` is 0, `aria-valuemax` is the duration once known, `aria-valuenow` is the playhead.
+- **`aria-valuetext` reads "0:03 of 0:06" rather than a float.** A bare `aria-valuenow` of `3.417` is technically correct and useless.
+- **The scrubber is `aria-disabled` until the audio is ready**, so a reader is not handed a control over something that has not decoded.
+- **The overlay carrying the slider role is deliberately empty**, because `role='slider'` takes presentational children — anything inside it would be hidden from assistive technology, so the visual layers sit beside it rather than within it.
+- **The play button is a toggle with `aria-pressed`**, and its glyph is `aria-hidden` so the state comes from the attribute rather than from a symbol.
+- **The error state carries a hidden warning glyph and visible text**, so a failed decode is readable rather than being an empty box.
+
+## Theming
+
+`--pretui-wave-height` (the reserved drawing height), `--pretui-primary-ink` (the played portion and the transport), `--pretui-destructive-ink` (the error state), `--pretui-shadow-hairline`.
+
+The bar geometry is args rather than tokens, deliberately: `@barWidth` and `@barGap` change what the waveform _is_ at a given zoom rather than how the theme dresses it, and two waveforms in one product may legitimately want different densities. The colors are tokens, so a theme recolors every wave at once and a played/unplayed split always matches the product's primary.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/waveform.usage.gts

@@ -0,0 +1,131 @@
+// Pretui — Waveform usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Waveform } from './waveform';
+import { TONE_WAV } from '../media-examples';
+import { Token } from './token';
+
+// ── Waveform ─────────────────────────────────────────────────────────────
+class WaveformUsage extends Component {
+  src = TONE_WAV;
+
+  @tracked height = 128;
+  @tracked barWidth = 3;
+  @tracked normalize = true;
+  @tracked step = 1;
+  @tracked bare = false;
+  @tracked lastSeek = '—';
+
+  setHeight = (v: number | null) => (this.height = v ?? 128);
+  setBarWidth = (v: number | null) => (this.barWidth = v ?? 3);
+  setNormalize = (v: boolean) => (this.normalize = v);
+  setStep = (v: number | null) => (this.step = v ?? 1);
+  setBare = (v: boolean) => (this.bare = v);
+  noteSeek = (seconds: number) => (this.lastSeek = `${seconds.toFixed(2)}s`);
+
+  get usage(): string {
+    return [
+      '<Waveform',
+      '  @src={{this.src}}',
+      "  @label='Lot B-1180 — desk note'",
+      `  @height={{${this.height}}}`,
+      '  @onSeek={{this.noteSeek}}',
+      '/>',
+    ].join('\n');
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Waveform'
+      @description="wavesurfer.js 7.12.11 (BSD-3-Clause, vendored at ./wavesurfer) decodes the audio and paints the peaks; everything you can reach with a keyboard is Pretui's. Click the wave, then try ← → to seek by a second, Shift for five, PageUp/PageDown for a tenth of the track, Home and End, and Space to play. That is the whole point of the component: wavesurfer gives pointer seeking and nothing else — no tab stop, no arrow keys, no announced position — and every waveform example on the web ships exactly that. Note also what happens when a decode fails: `phase` goes to `error` and the component says so in words, because a headless browser has no real media pipeline and neither does a machine that is offline."
+      @source={{this.usage}}
+    >
+      <:example>
+        <Waveform
+          @src={{this.src}}
+          @label='Lot B-1180 — desk note'
+          @height={{this.height}}
+          @barWidth={{this.barWidth}}
+          @barGap={{2}}
+          @normalize={{this.normalize}}
+          @step={{this.step}}
+          @bare={{this.bare}}
+          @onSeek={{this.noteSeek}}
+        />
+        <p class='dm-readout'>
+          <span class='dm-readoutLabel'>@onSeek</span>
+          <Token @value={{this.lastSeek}} />
+        </p>
+      </:example>
+
+      <:api as |Args|>
+        <Args.String
+          @name='src'
+          @value={{this.src}}
+          @description='URL of the audio. Passed through untouched — the component never creates or revokes an object URL, so a blob URL stays yours to revoke. Here it is a data:audio/wav URL of a speech-shaped desk note over a twelve-note bed, so this page works on a plane and the peaks look like a voice memo rather than twelve bricks.'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='label'
+          @value='Lot B-1180 — desk note'
+          @description="Accessible name of the scrubber. Not optional in practice: a role='slider' with no name is the most common failure in this whole category."
+          @hideControls={{true}}
+        />
+        <Args.Number
+          @name='height'
+          @value={{this.height}}
+          @min={{48}}
+          @max={{240}}
+          @defaultValue={{128}}
+          @description='Drawing height in px. Reserved before the audio lands, so the decode never reflows the page around it.'
+          @onInput={{this.setHeight}}
+        />
+        <Args.Number
+          @name='barWidth'
+          @value={{this.barWidth}}
+          @min={{0}}
+          @max={{8}}
+          @defaultValue={{3}}
+          @description='Bar width in px, or 0 for a continuous waveform.'
+          @onInput={{this.setBarWidth}}
+        />
+        <Args.Bool
+          @name='normalize'
+          @value={{this.normalize}}
+          @defaultValue={{true}}
+          @description='Scale peaks to the loudest sample. Off shows true amplitude, which is right when several clips must be compared.'
+          @onInput={{this.setNormalize}}
+        />
+        <Args.Number
+          @name='step'
+          @value={{this.step}}
+          @min={{0.1}}
+          @max={{5}}
+          @defaultValue={{1}}
+          @description='Seconds moved by one arrow press. Shift is five times this; PageUp/PageDown is a tenth of the track.'
+          @onInput={{this.setStep}}
+        />
+        <Args.Bool
+          @name='bare'
+          @value={{this.bare}}
+          @defaultValue={{false}}
+          @description='Drop the transport row and the readout, leaving only the wave — for when the surrounding surface already has a play button.'
+          @onInput={{this.setBare}}
+        />
+        <Args.Action
+          @name='onSeek'
+          @description='(seconds) on every scrub, keyboard or pointer.'
+        />
+        <Args.Action
+          @name='onReady'
+          @description='(duration) once the audio has decoded.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_WAVEFORM: Record<string, unknown> = {
+  Waveform: WaveformUsage,
+};