@jackuait/blok 0.18.0 → 0.19.1

package/src/tools/audio/waveform.ts

@@ -1,4 +1,5 @@
 import { WAVEFORM_BUCKETS } from './constants';
+import { liveAmplitude, headColorBlend, entranceEase } from './liveliness';
 
 /**
  * Reduce raw mono samples to `buckets` peak values normalized to 0..1.
@@ -95,16 +96,51 @@ export function attachWaveform(opts: {
   canvas.className = 'blok-audio-waveform__canvas';
   mount.appendChild(canvas);
 
-  const draw = (): void => {
+  const prefersReducedMotion = (): boolean =>
+    globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+
+  // Animation state. `playing` is true between play and pause/ended and pins the
+  // boost energy at full. On pause we keep the loop alive briefly with `settling`
+  // so the bars glide back to their resting peaks (energy ramps 1→0) instead of
+  // snapping. `energy` reflects the current boost multiplier.
+  const SETTLE_MS = 420;
+  // The comet-head colour blooms in over ENTRANCE_MS each time playback starts.
+  const ENTRANCE_MS = 650;
+  const anim = { playing: false, settling: false, settleStart: 0, entranceStart: 0, rafId: 0 };
+
+  const energyAt = (now: number): number => {
+    if (anim.playing) return 1;
+    if (!anim.settling) return 0;
+    return Math.min(1, Math.max(0, 1 - (now - anim.settleStart) / SETTLE_MS));
+  };
+
+  const entranceAt = (now: number): number => entranceEase((now - anim.entranceStart) / ENTRANCE_MS);
+
+  const draw = (now: number): void => {
     const rect = canvas.getBoundingClientRect();
     if (rect.width <= 0 || rect.height <= 0) return;
     const dpr = globalThis.devicePixelRatio || 1;
-    canvas.width = Math.round(rect.width * dpr);
-    canvas.height = Math.round(rect.height * dpr);
+    const targetW = Math.round(rect.width * dpr);
+    const targetH = Math.round(rect.height * dpr);
+    // Resizing the backing store clears it; only pay that cost when the box
+    // actually changed (every frame of the loop would otherwise reallocate).
+    if (canvas.width !== targetW || canvas.height !== targetH) {
+      canvas.width = targetW;
+      canvas.height = targetH;
+    }
     const ctx = canvas.getContext('2d');
     if (!ctx) return;
-    ctx.scale(dpr, dpr);
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.clearRect(0, 0, rect.width, rect.height);
+
     const played = media.duration ? media.currentTime / media.duration : 0;
+    const playheadIndex = played * peaks.length;
+    const reduced = prefersReducedMotion();
+    const timeSeconds = now / 1000;
+    const energy = reduced ? 0 : energyAt(now);
+    const live = energy > 0;
+    const entrance = live ? entranceAt(now) : 0;
+
     const slot = rect.width / peaks.length;
     const gap = Math.min(2, slot * 0.34);
     const barW = Math.max(1, slot - gap);
@@ -112,11 +148,9 @@ export function attachWaveform(opts: {
     const styles = getComputedStyle(canvas);
     const playedColor = styles.getPropertyValue('--blok-audio-bar-played').trim() || '#222';
     const baseColor = styles.getPropertyValue('--blok-audio-bar').trim() || '#ccc';
-    peaks.forEach((peak, i) => {
-      const h = Math.max(2, peak * rect.height * 0.92);
-      const x = i * slot;
-      const y = (rect.height - h) / 2;
-      ctx.fillStyle = i / peaks.length < played ? playedColor : baseColor;
+    const headColor = styles.getPropertyValue('--blok-audio-bar-head').trim() || playedColor;
+
+    const paintBar = (x: number, y: number, h: number): void => {
       if (typeof ctx.roundRect === 'function') {
         ctx.beginPath();
         ctx.roundRect(x, y, barW, h, radius);
@@ -124,26 +158,91 @@ export function attachWaveform(opts: {
       } else {
         ctx.fillRect(x, y, barW, h);
       }
+    };
+
+    peaks.forEach((peak, i) => {
+      const amp = live
+        ? liveAmplitude({ basePeak: peak, index: i, playheadIndex, timeSeconds, reduced, energy })
+        : peak;
+      const h = Math.max(2, amp * rect.height * 0.92);
+      const x = i * slot;
+      const y = (rect.height - h) / 2;
+      ctx.fillStyle = i < playheadIndex ? playedColor : baseColor;
+      paintBar(x, y, h);
+
+      // Comet-head colour shift — overlay the head tint, its alpha ramping in
+      // with the entrance and fading out on the settle (energy).
+      if (live) {
+        const blend = headColorBlend({ distance: i - playheadIndex, energy, entrance });
+        if (blend > 0.001) {
+          ctx.save();
+          ctx.globalAlpha = Math.min(1, blend);
+          ctx.fillStyle = headColor;
+          paintBar(x, y, h);
+          ctx.restore();
+        }
+      }
     });
   };
 
-  const rafState = { id: 0 };
+  const setSeekVar = (): void => {
+    mount.style.setProperty(
+      '--blok-audio-seek-pct',
+      String(media.duration ? (media.currentTime / media.duration) * 100 : 0),
+    );
+  };
+
+  const loop = (now: number): void => {
+    draw(now);
+    // Keep looping while playing, or while the post-pause settle still has energy.
+    const keepGoing = anim.playing || (anim.settling && energyAt(now) > 0);
+    if (keepGoing) {
+      anim.rafId = requestAnimationFrame(loop);
+    } else {
+      anim.settling = false;
+      anim.rafId = 0;
+    }
+  };
+
+  const onPlay = (): void => {
+    setSeekVar();
+    anim.playing = true;
+    anim.settling = false;
+    // Restart the head-colour entrance so it blooms in on every play.
+    anim.entranceStart = globalThis.performance?.now?.() ?? 0;
+    // No continuous loop under reduced motion — timeupdate alone advances the
+    // played boundary, with no dancing bars.
+    if (!anim.rafId && !prefersReducedMotion()) anim.rafId = requestAnimationFrame(loop);
+  };
+  const onStop = (): void => {
+    // Hand off to the settle ramp so the bars glide down rather than snap. Under
+    // reduced motion there's no loop/boost to settle, so just stop.
+    if (anim.playing && !prefersReducedMotion()) {
+      anim.playing = false;
+      anim.settling = true;
+      anim.settleStart = globalThis.performance?.now?.() ?? 0;
+      if (!anim.rafId) anim.rafId = requestAnimationFrame(loop);
+    } else {
+      anim.playing = false;
+      anim.settling = false;
+      if (anim.rafId) { cancelAnimationFrame(anim.rafId); anim.rafId = 0; }
+      draw(0);
+    }
+  };
+
+  // Keeps the played boundary + seek var current while paused-seeking or when
+  // the continuous loop is off (reduced motion). The loop owns drawing while it
+  // runs, so skip the redundant paint then.
   const onTime = (): void => {
-    if (rafState.id) return;
-    rafState.id = requestAnimationFrame(() => {
-      rafState.id = 0;
-      mount.style.setProperty(
-        '--blok-audio-seek-pct',
-        String(media.duration ? (media.currentTime / media.duration) * 100 : 0),
-      );
-      draw();
-    });
+    setSeekVar();
+    if (!anim.rafId) draw(0);
   };
 
   const seek = (clientX: number): void => {
     if (!media.duration) return;
     media.currentTime = ratioFromPointer(clientX, canvas.getBoundingClientRect()) * media.duration;
-    draw();
+    setSeekVar();
+    if (!anim.rafId) draw(0);
   };
   const drag = { active: false };
   const onDown = (e: PointerEvent): void => { drag.active = true; seek(e.clientX); };
@@ -153,18 +252,25 @@ export function attachWaveform(opts: {
   canvas.addEventListener('pointerdown', onDown);
   globalThis.addEventListener('pointermove', onMove);
   globalThis.addEventListener('pointerup', onUp);
+  media.addEventListener('play', onPlay);
+  media.addEventListener('pause', onStop);
+  media.addEventListener('ended', onStop);
   media.addEventListener('timeupdate', onTime);
-  media.addEventListener('loadedmetadata', draw);
-  draw();
+  media.addEventListener('loadedmetadata', onTime);
+  draw(0);
 
   return {
     destroy(): void {
-      if (rafState.id) cancelAnimationFrame(rafState.id);
+      if (anim.rafId) cancelAnimationFrame(anim.rafId);
+      anim.playing = false;
       canvas.removeEventListener('pointerdown', onDown);
       globalThis.removeEventListener('pointermove', onMove);
       globalThis.removeEventListener('pointerup', onUp);
+      media.removeEventListener('play', onPlay);
+      media.removeEventListener('pause', onStop);
+      media.removeEventListener('ended', onStop);
       media.removeEventListener('timeupdate', onTime);
-      media.removeEventListener('loadedmetadata', draw);
+      media.removeEventListener('loadedmetadata', onTime);
       canvas.remove();
     },
   };

package/types/api/index.d.ts

@@ -18,3 +18,4 @@ export * from './ui';
 export * from './tools';
 
 export * from './theme';
+export * from './width';

package/types/api/width.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Editor content width mode.
+ *
+ * - `'narrow'` — content is constrained to the default `--max-width-content` (the default).
+ * - `'full'`   — content max-width constraint is removed so it fills its container.
+ */
+export type EditorWidth = 'full' | 'narrow';
+
+/**
+ * Describes Blok's width API for controlling the editor content width mode.
+ */
+export interface Width {
+  /**
+   * Returns the current editor content width mode.
+   *
+   * @returns {EditorWidth} the active mode (defaults to `'narrow'`)
+   */
+  get(): EditorWidth;
+
+  /**
+   * Sets the editor content width mode.
+   *
+   * @param {EditorWidth} value - the mode to apply
+   */
+  set(value: EditorWidth): void;
+
+  /**
+   * Toggles the editor content width mode between `'narrow'` and `'full'`.
+   */
+  toggle(): void;
+}

package/types/data-attributes.d.ts

@@ -28,6 +28,7 @@ export const DATA_ATTR: {
 
   // Editor Modes
   readonly rtl: 'data-blok-rtl';
+  readonly width: 'data-blok-width';
 
   // Drag and Drop
   readonly dragging: 'data-blok-dragging';

package/types/index.d.ts

@@ -33,6 +33,7 @@ import {
   Theme,
   ThemeMode,
   ResolvedTheme,
+  Width,
 } from './api';
 
 import { OutputData } from './data-formats';
@@ -129,6 +130,8 @@ export {
   Theme,
   ThemeMode,
   ResolvedTheme,
+  Width,
+  EditorWidth,
 } from './api';
 export {
   BlockMutationType,
@@ -204,14 +207,41 @@ export function wrapLegacyInlineTool(
   }
 ): InlineToolConstructable;
 
+/**
+ * The surface of a Blok instance that is guaranteed to exist synchronously,
+ * immediately after `new Blok()` and before `isReady` has resolved.
+ *
+ * Blok constructs its module APIs (`blocks`, `caret`, `history`, `readOnly`, …)
+ * asynchronously: they only become available once `isReady` resolves. Accessing
+ * them earlier returns `undefined` at runtime. Type a reference you hold during
+ * that window as `PendingBlok` so the not-yet-available members are unreachable,
+ * then await `isReady` to obtain the fully-initialized {@link Blok}:
+ *
+ * @example
+ * const pending: PendingBlok = new Blok(config);
+ * const editor = await pending.isReady; // editor is a ready Blok
+ * editor.blocks.render(data);
+ */
+export interface PendingBlok {
+  /** Resolves with the fully-initialized Blok instance once core modules are ready. */
+  isReady: Promise<Blok>;
+  /** Destroy the instance. Safe to call before `isReady` resolves. */
+  destroy(): void;
+  /** Theme API, exposed immediately after construction. */
+  theme: Theme;
+  /** Width API, exposed immediately after construction. */
+  width: Width;
+}
+
 /**
  * Main Blok class
  */
 export class Blok {
-  public isReady: Promise<void>;
+  public isReady: Promise<Blok>;
 
   public blocks: Blocks;
   public caret: Caret;
+  public history: History;
   public sanitizer: Sanitizer;
   public saver: Saver;
   public selection: Selection;
@@ -221,6 +251,7 @@ export class Blok {
   public tooltip: Tooltip;
   public readOnly: ReadOnly;
   public theme: Theme;
+  public width: Width;
   constructor(configuration?: BlokConfig|string);
 
   /**