@djangocfg/ui-tools 2.1.310 → 2.1.313

package/src/tools/AudioPlayer/parts/Waveform/waveformInteraction.ts

@@ -0,0 +1,106 @@
+// Pointer interaction for the waveform: click-to-seek, drag-to-scrub,
+// hover indicator + tooltip with time-at-cursor. CSS variables only — no
+// React state, no canvas redraws.
+
+import { formatTime } from '../../utils/formatTime';
+
+const HOVER_X = '--hp';
+const HOVER_OPACITY = '--ho';
+const TOOLTIP_LABEL = '--ht';
+
+export type AttachSeekOptions = {
+  // When the user clicks while paused/idle, also start playback. Drag scrub
+  // never auto-starts (already playing or user is scrubbing without intent).
+  startsPlayback?: boolean;
+  onPlayRequest?: () => void;
+};
+
+export function attachSeek(
+  container: HTMLElement,
+  audio: HTMLAudioElement,
+  options: AttachSeekOptions = {},
+): () => void {
+  let dragging = false;
+  let movedDuringDrag = false;
+  const { startsPlayback = true, onPlayRequest } = options;
+
+  const ratioFor = (clientX: number): number => {
+    const rect = container.getBoundingClientRect();
+    if (rect.width === 0) return 0;
+    return Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+  };
+
+  const seekTo = (clientX: number) => {
+    const dur = Number.isFinite(audio.duration) ? audio.duration : 0;
+    if (dur > 0) audio.currentTime = ratioFor(clientX) * dur;
+  };
+
+  const onPointerDown = (e: PointerEvent) => {
+    if (e.button !== 0 && e.pointerType === 'mouse') return;
+    dragging = true;
+    movedDuringDrag = false;
+    container.setPointerCapture?.(e.pointerId);
+    seekTo(e.clientX);
+  };
+  const onPointerMove = (e: PointerEvent) => {
+    if (!dragging) return;
+    movedDuringDrag = true;
+    seekTo(e.clientX);
+  };
+  const onPointerEnd = (e: PointerEvent) => {
+    if (!dragging) return;
+    const wasDrag = movedDuringDrag;
+    dragging = false;
+    movedDuringDrag = false;
+    try {
+      container.releasePointerCapture?.(e.pointerId);
+    } catch {
+      // ignore
+    }
+    // Click (not drag) while paused → start playback at the seek target.
+    if (!wasDrag && startsPlayback && (audio.paused || audio.ended)) {
+      onPlayRequest?.();
+    }
+  };
+
+  container.addEventListener('pointerdown', onPointerDown);
+  container.addEventListener('pointermove', onPointerMove);
+  container.addEventListener('pointerup', onPointerEnd);
+  container.addEventListener('pointercancel', onPointerEnd);
+
+  return () => {
+    container.removeEventListener('pointerdown', onPointerDown);
+    container.removeEventListener('pointermove', onPointerMove);
+    container.removeEventListener('pointerup', onPointerEnd);
+    container.removeEventListener('pointercancel', onPointerEnd);
+  };
+}
+
+export function attachHover(container: HTMLElement, audio: HTMLAudioElement): () => void {
+  const tooltip = container.querySelector<HTMLElement>('[data-audioplayer-time-tip]');
+
+  const onMove = (e: PointerEvent) => {
+    const rect = container.getBoundingClientRect();
+    if (rect.width === 0) return;
+    const x = Math.max(0, Math.min(rect.width, e.clientX - rect.left));
+    container.style.setProperty(HOVER_X, `${x}px`);
+    container.style.setProperty(HOVER_OPACITY, '1');
+    if (tooltip) {
+      const dur = Number.isFinite(audio.duration) ? audio.duration : 0;
+      const t = (x / rect.width) * dur;
+      tooltip.textContent = formatTime(t);
+      tooltip.style.setProperty(TOOLTIP_LABEL, '1');
+    }
+  };
+  const onLeave = () => {
+    container.style.setProperty(HOVER_OPACITY, '0');
+    if (tooltip) tooltip.style.setProperty(TOOLTIP_LABEL, '0');
+  };
+
+  container.addEventListener('pointermove', onMove);
+  container.addEventListener('pointerleave', onLeave);
+  return () => {
+    container.removeEventListener('pointermove', onMove);
+    container.removeEventListener('pointerleave', onLeave);
+  };
+}

package/src/tools/AudioPlayer/parts/Waveform/waveformRenderer.ts

@@ -0,0 +1,91 @@
+// Pure canvas painters. No React, no DOM events. Re-painted only when peaks
+// change, the container resizes, or theme tokens change. See ADR-003.
+
+import { backingHeight, backingWidth, getDpr } from '../../utils/dpr';
+
+export type PaintPeaksOptions = {
+  color: string;
+  background?: string;
+  barWidth: number;
+  barGap: number;
+  minBarHeight?: number;
+};
+
+function resizeCanvas(canvas: HTMLCanvasElement): { ctx: CanvasRenderingContext2D; cssW: number; cssH: number } | null {
+  const cssW = canvas.clientWidth;
+  const cssH = canvas.clientHeight;
+  if (cssW === 0 || cssH === 0) return null;
+  const dpr = getDpr();
+  const w = backingWidth(cssW, dpr);
+  const h = backingHeight(cssH, dpr);
+  if (canvas.width !== w) canvas.width = w;
+  if (canvas.height !== h) canvas.height = h;
+  const ctx = canvas.getContext('2d', { alpha: true, desynchronized: true });
+  if (!ctx) return null;
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  return { ctx, cssW, cssH };
+}
+
+export function paintPeaks(
+  canvas: HTMLCanvasElement,
+  peaks: Float32Array,
+  opts: PaintPeaksOptions,
+): void {
+  const sized = resizeCanvas(canvas);
+  if (!sized) return;
+  const { ctx, cssW, cssH } = sized;
+  ctx.clearRect(0, 0, cssW, cssH);
+  if (opts.background) {
+    ctx.fillStyle = opts.background;
+    ctx.fillRect(0, 0, cssW, cssH);
+  }
+
+  if (peaks.length === 0) return;
+  const step = Math.max(1, opts.barWidth + opts.barGap);
+  const numBars = Math.max(1, Math.floor(cssW / step));
+  const mid = cssH / 2;
+  const minH = opts.minBarHeight ?? 1;
+
+  ctx.fillStyle = opts.color;
+  for (let i = 0; i < numBars; i++) {
+    const peakIdx = Math.min(peaks.length - 1, Math.floor((i / numBars) * peaks.length));
+    const amp = peaks[peakIdx];
+    const h = Math.max(minH, amp * cssH);
+    const x = i * step;
+    ctx.fillRect(x, mid - h / 2, opts.barWidth, h);
+  }
+}
+
+export type PaintLiveOptions = {
+  color: string;
+  barWidth: number;
+  barGap: number;
+  minBarHeight?: number;
+};
+
+export function paintLive(
+  canvas: HTMLCanvasElement,
+  levels: Float32Array,
+  opts: PaintLiveOptions,
+): void {
+  const sized = resizeCanvas(canvas);
+  if (!sized) return;
+  const { ctx, cssW, cssH } = sized;
+  ctx.clearRect(0, 0, cssW, cssH);
+  if (levels.length === 0) return;
+
+  const step = Math.max(1, opts.barWidth + opts.barGap);
+  const numBars = Math.max(1, Math.floor(cssW / step));
+  const mid = cssH / 2;
+  const minH = opts.minBarHeight ?? 1;
+  // Concentrate visible energy in the lower frequency bands.
+  const usable = Math.floor(levels.length * 0.7);
+
+  ctx.fillStyle = opts.color;
+  for (let i = 0; i < numBars; i++) {
+    const idx = Math.min(usable - 1, Math.floor((i / numBars) * usable));
+    const v = levels[idx] ?? 0;
+    const h = Math.max(minH, v * cssH);
+    ctx.fillRect(i * step, mid - h / 2, opts.barWidth, h);
+  }
+}

package/src/tools/AudioPlayer/parts/index.ts

@@ -0,0 +1 @@
+export {};

package/src/tools/AudioPlayer/store/activePlayerBus.ts

@@ -0,0 +1,63 @@
+// Single-active-player coordination, with optional cross-tab sync.
+// Each Player instance registers an id and a `pause()` callback. When another
+// player becomes active, all others get paused. Cross-tab via BroadcastChannel.
+
+const CHANNEL = 'djangocfg-audioplayer:active';
+
+type Listener = (activeId: string | null) => void;
+
+let activeId: string | null = null;
+let lastActiveId: string | null = null;
+const listeners = new Set<Listener>();
+const pausers = new Map<string, () => void>();
+
+let channel: BroadcastChannel | null = null;
+function getChannel(): BroadcastChannel | null {
+  if (typeof BroadcastChannel === 'undefined') return null;
+  if (channel) return channel;
+  channel = new BroadcastChannel(CHANNEL);
+  channel.addEventListener('message', (e) => {
+    const next = typeof e.data === 'string' ? e.data : null;
+    if (next === activeId) return;
+    activeId = next;
+    if (next) lastActiveId = next;
+    for (const [id, pause] of pausers) {
+      if (id !== next) pause();
+    }
+    for (const l of listeners) l(next);
+  });
+  return channel;
+}
+
+export function registerPlayer(id: string, pause: () => void): () => void {
+  pausers.set(id, pause);
+  return () => {
+    pausers.delete(id);
+    if (activeId === id) activeId = null;
+  };
+}
+
+export function setActivePlayer(id: string | null): void {
+  if (activeId === id) return;
+  activeId = id;
+  if (id) lastActiveId = id;
+  for (const [pid, pause] of pausers) {
+    if (pid !== id) pause();
+  }
+  for (const l of listeners) l(id);
+  getChannel()?.postMessage(id);
+}
+
+export function getActivePlayer(): string | null {
+  return activeId;
+}
+
+export function getLastActivePlayer(): string | null {
+  return lastActiveId;
+}
+
+export function subscribeActivePlayer(cb: Listener): () => void {
+  listeners.add(cb);
+  getChannel(); // ensure channel hot
+  return () => listeners.delete(cb);
+}

package/src/tools/AudioPlayer/store/createLevelsStore.ts

@@ -0,0 +1,37 @@
+// Imperative store for high-frequency audio levels.
+// React never re-renders on `set()`; consumers read via getCurrent() in their
+// own rAF (typically the live waveform canvas). See ADR-001 §LevelsCtx.
+
+export type LevelsStore = {
+  subscribe: (cb: () => void) => () => void;
+  getCurrent: () => Float32Array;
+  set: (next: Float32Array) => void;
+  setActive: (active: boolean) => void;
+  isActive: () => boolean;
+};
+
+export function createLevelsStore(initial?: Float32Array): LevelsStore {
+  let current = initial ?? new Float32Array(0);
+  let active = false;
+  const listeners = new Set<() => void>();
+
+  return {
+    subscribe(cb) {
+      listeners.add(cb);
+      return () => listeners.delete(cb);
+    },
+    getCurrent() {
+      return current;
+    },
+    set(next) {
+      current = next;
+      for (const cb of listeners) cb();
+    },
+    setActive(value) {
+      active = value;
+    },
+    isActive() {
+      return active;
+    },
+  };
+}

package/src/tools/AudioPlayer/store/index.ts

@@ -0,0 +1,16 @@
+export { createLevelsStore } from './createLevelsStore';
+export type { LevelsStore } from './createLevelsStore';
+export {
+  registerPlayer,
+  setActivePlayer,
+  getActivePlayer,
+  getLastActivePlayer,
+  subscribeActivePlayer,
+} from './activePlayerBus';
+export {
+  getPreferences,
+  setStoredVolume,
+  setStoredMuted,
+  subscribePreferences,
+} from './preferencesStore';
+export type { PlayerPreferences } from './preferencesStore';

package/src/tools/AudioPlayer/store/preferencesStore.ts

@@ -0,0 +1,104 @@
+// Persistent user preferences (volume, muted). Single localStorage entry,
+// cross-tab sync via the native `storage` event. SSR-safe.
+//
+// Why not Zustand: two fields. Adding a dep + persist middleware is overkill
+// for ~50 LOC of plain code that already matches the activePlayerBus pattern.
+
+const STORAGE_KEY = 'djangocfg-audioplayer:prefs';
+const DEFAULT_VOLUME = 1;
+const DEFAULT_MUTED = false;
+
+export type PlayerPreferences = {
+  volume: number;
+  muted: boolean;
+};
+
+type Listener = (prefs: PlayerPreferences) => void;
+
+let cached: PlayerPreferences | null = null;
+const listeners = new Set<Listener>();
+let storageBound = false;
+
+function clamp01(v: number): number {
+  if (!Number.isFinite(v)) return DEFAULT_VOLUME;
+  return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+
+function readFromStorage(): PlayerPreferences {
+  if (typeof window === 'undefined') {
+    return { volume: DEFAULT_VOLUME, muted: DEFAULT_MUTED };
+  }
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return { volume: DEFAULT_VOLUME, muted: DEFAULT_MUTED };
+    const parsed = JSON.parse(raw) as Partial<PlayerPreferences> | null;
+    return {
+      volume: typeof parsed?.volume === 'number' ? clamp01(parsed.volume) : DEFAULT_VOLUME,
+      muted: typeof parsed?.muted === 'boolean' ? parsed.muted : DEFAULT_MUTED,
+    };
+  } catch {
+    return { volume: DEFAULT_VOLUME, muted: DEFAULT_MUTED };
+  }
+}
+
+function writeToStorage(prefs: PlayerPreferences): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(prefs));
+  } catch {
+    // quota exceeded / disabled — silently ignore.
+  }
+}
+
+function bindStorage(): void {
+  if (storageBound || typeof window === 'undefined') return;
+  storageBound = true;
+  window.addEventListener('storage', (e) => {
+    if (e.key !== STORAGE_KEY) return;
+    cached = readFromStorage();
+    for (const cb of listeners) cb(cached);
+  });
+}
+
+export function getPreferences(): PlayerPreferences {
+  if (!cached) cached = readFromStorage();
+  bindStorage();
+  return cached;
+}
+
+function update(next: PlayerPreferences, persist = true): void {
+  cached = next;
+  if (persist) writeToStorage(next);
+  for (const cb of listeners) cb(next);
+}
+
+export function setStoredVolume(volume: number): void {
+  const current = getPreferences();
+  const v = clamp01(volume);
+  if (v === current.volume) return;
+  update({ ...current, volume: v });
+}
+
+export function setStoredMuted(muted: boolean): void {
+  const current = getPreferences();
+  if (muted === current.muted) return;
+  update({ ...current, muted });
+}
+
+export function subscribePreferences(cb: Listener): () => void {
+  listeners.add(cb);
+  bindStorage();
+  return () => listeners.delete(cb);
+}
+
+// Test-only.
+export function _resetPreferencesForTesting(): void {
+  cached = null;
+  if (typeof window !== 'undefined') {
+    try {
+      window.localStorage.removeItem(STORAGE_KEY);
+    } catch {
+      // ignore
+    }
+  }
+}

package/src/tools/AudioPlayer/styles/webview-safe.css

@@ -0,0 +1,77 @@
+/* AudioPlayer v6 — WebView-safe baseline. Compositor-only animations.
+ * Kept under 80 LOC per folder-structure budget.
+ */
+
+.audioplayer-press {
+  transition: transform 80ms cubic-bezier(0.4, 0, 0.6, 1);
+}
+.audioplayer-press:active {
+  transform: scale(0.97);
+}
+
+.audioplayer-shimmer {
+  position: relative;
+  overflow: hidden;
+}
+.audioplayer-shimmer::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    color-mix(in oklab, var(--color-foreground, #fff) 8%, transparent) 50%,
+    transparent 100%
+  );
+  background-size: 200% 100%;
+  animation: audioplayer-shimmer 1400ms linear infinite;
+}
+
+@keyframes audioplayer-shimmer {
+  from {
+    background-position: 200% 0;
+  }
+  to {
+    background-position: -200% 0;
+  }
+}
+
+@keyframes audioplayer-bar {
+  0%, 100% {
+    height: 25%;
+  }
+  50% {
+    height: 95%;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .audioplayer-press,
+  .audioplayer-shimmer::after,
+  .audioplayer-bars span {
+    animation: none !important;
+    transition: none !important;
+    transform: none !important;
+  }
+}
+
+.audioplayer canvas {
+  image-rendering: auto;
+}
+
+/* No hover on touch — also no time-tooltip nor hover-cursor on the waveform.
+ * Avoids a stuck tip after a tap-and-release. */
+@media (hover: none), (pointer: coarse) {
+  .audioplayer .audioplayer-tip,
+  .audioplayer .audioplayer-hover {
+    display: none !important;
+  }
+}
+
+/* Bigger tap targets on touch + small viewports (Apple HIG ≥ 44px). */
+@media (pointer: coarse) {
+  .audioplayer .audioplayer-press[aria-label] {
+    min-width: 40px;
+    min-height: 40px;
+  }
+}

package/src/tools/AudioPlayer/types.ts

@@ -0,0 +1,95 @@
+// Public types for the AudioPlayer v6.
+// See packages/ui-tools/@dev/@refactoring6-audioplayer/04-implementation/api.md
+
+export type WaveformMode = 'peaks' | 'live' | 'bars' | 'progress' | 'none';
+
+export type WaveformConfig = {
+  mode?: WaveformMode;
+  peaks?: Float32Array;
+  height?: number;
+  barWidth?: number;
+  barGap?: number;
+  bgColor?: string;
+  fgColor?: string;
+  decodeOnMount?: boolean;
+};
+
+export type ReactiveCoverMode = false | 'subtle';
+export type PlayerVariant = 'default' | 'compact' | 'auto';
+export type PlayerErrorReason = 'network' | 'decode' | 'unsupported' | 'unknown';
+
+export type PlayerProps = {
+  src: string;
+  peaks?: Float32Array;
+
+  title?: string;
+  artist?: string;
+  album?: string;
+  cover?: string;
+
+  variant?: PlayerVariant;
+  className?: string;
+
+  waveform?: WaveformConfig;
+  reactiveCover?: ReactiveCoverMode;
+
+  autoplay?: boolean;
+  loop?: boolean;
+  initialVolume?: number;
+  muted?: boolean;
+  preload?: 'none' | 'metadata' | 'auto';
+  exclusive?: boolean;
+
+  onPrev?: () => void;
+  onNext?: () => void;
+
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  onError?: (reason: PlayerErrorReason, e: unknown) => void;
+  onTimeUpdate?: (currentTime: number, duration: number) => void;
+
+  ariaLabel?: string;
+  enableKeyboardShortcuts?: boolean;
+
+  // When the user clicks on the waveform while paused, also start playback.
+  // Default true — clicking on a time mark almost always means "play here".
+  // Set false for embeds where stray clicks shouldn't trigger sound.
+  seekStartsPlayback?: boolean;
+};
+
+export type PlayerStateKind =
+  | 'idle'
+  | 'loading'
+  | 'decoding'
+  | 'ready'
+  | 'playing'
+  | 'paused'
+  | 'ended'
+  | 'error';
+
+export type PlayerState =
+  | { kind: 'idle' | 'loading' }
+  | { kind: 'decoding'; duration: number }
+  | { kind: 'ready' | 'playing' | 'paused' | 'ended'; duration: number; peaks?: Float32Array }
+  | { kind: 'error'; reason: PlayerErrorReason; duration: number };
+
+export type PlayerControls = {
+  play: () => Promise<void>;
+  pause: () => void;
+  toggle: () => Promise<void>;
+  seek: (seconds: number) => void;
+  seekTo: (ratio: number) => void;
+  setVolume: (v: number) => void;
+  toggleMute: () => void;
+  toggleLoop: () => void;
+};
+
+export type PlayerHandle = {
+  audio: HTMLAudioElement;
+  play: () => Promise<void>;
+  pause: () => void;
+  seek: (seconds: number) => void;
+  getCurrentTime: () => number;
+  getDuration: () => number;
+};

package/src/tools/AudioPlayer/utils/bucketize.ts

@@ -0,0 +1,27 @@
+// Reduce an audio channel down to `buckets` peak amplitude samples in [0, 1].
+// Used by decodePeaks; pure.
+
+export function bucketize(channel: Float32Array, buckets: number): Float32Array {
+  const out = new Float32Array(buckets);
+  if (buckets <= 0 || channel.length === 0) return out;
+  const samplesPerBucket = Math.max(1, Math.floor(channel.length / buckets));
+  let peakMax = 0;
+  for (let b = 0; b < buckets; b++) {
+    const start = b * samplesPerBucket;
+    const end = Math.min(start + samplesPerBucket, channel.length);
+    let max = 0;
+    for (let i = start; i < end; i++) {
+      const v = channel[i];
+      const abs = v < 0 ? -v : v;
+      if (abs > max) max = abs;
+    }
+    out[b] = max;
+    if (max > peakMax) peakMax = max;
+  }
+  // Normalize so the loudest bucket reaches 1.0 — keeps quiet tracks visible.
+  if (peakMax > 0 && peakMax < 1) {
+    const scale = 1 / peakMax;
+    for (let i = 0; i < out.length; i++) out[i] *= scale;
+  }
+  return out;
+}

package/src/tools/AudioPlayer/utils/clamp.ts

@@ -0,0 +1,5 @@
+export function clamp(value: number, min: number, max: number): number {
+  if (value < min) return min;
+  if (value > max) return max;
+  return value;
+}

package/src/tools/AudioPlayer/utils/dpr.ts

@@ -0,0 +1,19 @@
+// Device pixel ratio helpers. Clamped to 2 to keep canvases under iOS 15 GPU
+// process limits (research 01 §canvas).
+
+const MAX_DPR = 2;
+const MAX_BACKING_WIDTH = 2048;
+
+export function getDpr(): number {
+  if (typeof window === 'undefined') return 1;
+  const dpr = window.devicePixelRatio ?? 1;
+  return Math.min(Math.max(dpr, 1), MAX_DPR);
+}
+
+export function backingWidth(cssWidth: number, dpr = getDpr()): number {
+  return Math.min(Math.round(cssWidth * dpr), MAX_BACKING_WIDTH);
+}
+
+export function backingHeight(cssHeight: number, dpr = getDpr()): number {
+  return Math.round(cssHeight * dpr);
+}

package/src/tools/AudioPlayer/utils/formatTime.ts

@@ -1,10 +1,14 @@
-/**
- * formatTime - Format seconds to mm:ss string
- */
-
+// Formats seconds as `m:ss` or `h:mm:ss`. NaN/Infinity → "0:00".
 export function formatTime(seconds: number): string {
-  if (!seconds || !isFinite(seconds) || seconds < 0) return '0:00';
-  const mins = Math.floor(seconds / 60);
-  const secs = Math.floor(seconds % 60);
-  return `${mins}:${secs.toString().padStart(2, '0')}`;
+  if (!Number.isFinite(seconds) || seconds < 0) return '0:00';
+  const total = Math.floor(seconds);
+  const s = total % 60;
+  const m = Math.floor(total / 60) % 60;
+  const h = Math.floor(total / 3600);
+  const ss = s.toString().padStart(2, '0');
+  if (h > 0) {
+    const mm = m.toString().padStart(2, '0');
+    return `${h}:${mm}:${ss}`;
+  }
+  return `${m}:${ss}`;
 }

package/src/tools/AudioPlayer/utils/index.ts

@@ -1,6 +1,5 @@
-/**
- * AudioPlayer utilities - Public API
- */
-
+export { clamp } from './clamp';
 export { formatTime } from './formatTime';
-export { audioDebug } from './debug';
+export { bucketize } from './bucketize';
+export { getDpr, backingWidth, backingHeight } from './dpr';
+export { readCssVar } from './readCssVar';

package/src/tools/AudioPlayer/utils/readCssVar.ts

@@ -0,0 +1,7 @@
+// Resolve a CSS custom property on an element via getComputedStyle.
+// Returns the trimmed value, or `fallback` if undefined / empty.
+export function readCssVar(el: Element, name: string, fallback = ''): string {
+  if (typeof window === 'undefined') return fallback;
+  const value = getComputedStyle(el).getPropertyValue(name).trim();
+  return value || fallback;
+}