@juspay/svelte-ui-components 4.25.0 → 4.26.0

package/dist/VoiceOrb/VoiceOrb.svelte

@@ -0,0 +1,400 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import {
+    AUDIO_ATTACK_MS,
+    AUDIO_RELEASE_MS,
+    LEVEL_REPORT_EPSILON,
+    followEnvelope,
+    generateOrbParticles,
+    mulberry32,
+    orbDepthScale,
+    parseCssColor,
+    resolveExplicitSeed,
+    resolveMotionScale,
+    resolveMotionSpeed,
+    rmsFromTimeDomain,
+    rotateOrbPoint,
+    type OrbParticle
+  } from './orbMath';
+  import type { Rgb } from '../types';
+  import { prefersReducedMotion } from '../utils';
+  import type { VoiceOrbProperties } from './properties';
+
+  let {
+    variant = 'idle',
+    speedMultiplier = 1,
+    seed,
+    height = 400,
+    particleCount = 1000,
+    radius = 140,
+    interactive = true,
+    repelRadius = 200,
+    analyser,
+    sensitivity = 1,
+    persistKey,
+    classes,
+    testId,
+    onfirstframe,
+    onlevel
+  }: VoiceOrbProperties = $props();
+
+  const FOCAL_LENGTH = 600;
+  const BASE_ROTATION_X = 0.0021;
+  const BASE_ROTATION_Y = 0.0014;
+  /*
+   * Last resort only, and deliberately a mid-grey that is visible on any
+   * ground. It is reached when neither the custom property nor the inherited
+   * colour normalises, which a browser has to work at to produce. The real
+   * default is the inherited text colour -- see `particleRgb`.
+   */
+  const FALLBACK_PARTICLE_RGB: Rgb = { r: 128, g: 128, b: 128 };
+
+  let canvas: HTMLCanvasElement | null = $state(null);
+  let container: HTMLDivElement | null = $state(null);
+
+  const pointer: { x: number | null; y: number | null } = { x: null, y: null };
+  const orb = { width: 0, height: 0, angleX: 0, angleY: 0 };
+
+  let listeningElapsedMs = 0;
+  /* Explicitly over ArrayBuffer: `getByteTimeDomainData` will not accept the
+     ArrayBufferLike default that a bare `Uint8Array` annotation now means. */
+  let audioBuffer: Uint8Array<ArrayBuffer> | null = null;
+  let audioLevel = 0;
+  let reportedLevel = 0;
+  let resolvedColorInput = '';
+  let resolvedRgb: Rgb = FALLBACK_PARTICLE_RGB;
+  let frame: number | null = null;
+  let previousTime: number | null = null;
+  let announcedFirstFrame = false;
+
+  /*
+   * Resolved once per instance rather than inside `resolveSeed` itself: an
+   * unseeded orb should only ever get a new random pattern from an actual new
+   * mount, never from `particleCount`/`radius` changing underneath it (see
+   * `particles` below, and finding 2 in the review this fixed).
+   */
+  let unseededSeed = Math.floor(Math.random() * 0xffffffff) >>> 0;
+
+  const resolveSeed = (): number => resolveExplicitSeed(seed) ?? unseededSeed;
+
+  /*
+   * $derived rather than assigned once in `onMount`: `particleCount`, `radius`
+   * and `seed` are reactive props, and generating the sphere only at mount
+   * meant changing any of them afterwards silently kept the original geometry.
+   * `unseededSeed` above is what keeps an unseeded orb from also reshuffling
+   * on a change to `particleCount`/`radius` alone.
+   */
+  const particles: readonly OrbParticle[] = $derived.by(() =>
+    generateOrbParticles(particleCount, radius, mulberry32(resolveSeed()))
+  );
+
+  /*
+   * Storage is namespaced by the caller's key and every read is guarded: a
+   * browser with storage disabled throws on access rather than returning null,
+   * and a persisted value can be anything by the time it is read back.
+   */
+  const readPersisted = (suffix: string): number | null => {
+    if (typeof persistKey !== 'string' || persistKey.length === 0) {
+      return null;
+    }
+    try {
+      const raw = localStorage.getItem(`${persistKey}:${suffix}`);
+      if (raw === null) {
+        return null;
+      }
+      const parsed = Number.parseFloat(raw);
+      return Number.isFinite(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  };
+
+  const writePersisted = (): void => {
+    if (typeof persistKey !== 'string' || persistKey.length === 0) {
+      return;
+    }
+    try {
+      localStorage.setItem(`${persistKey}:angleX`, String(orb.angleX));
+      localStorage.setItem(`${persistKey}:angleY`, String(orb.angleY));
+      localStorage.setItem(`${persistKey}:listeningMs`, String(listeningElapsedMs));
+    } catch {
+      /* Storage full or blocked: rotation resumes from zero, which is cosmetic. */
+    }
+  };
+
+  const resize = (): void => {
+    if (canvas === null || container === null) {
+      return;
+    }
+    orb.width = container.clientWidth;
+    orb.height = Number.isFinite(height) && height > 0 ? height : 400;
+    canvas.width = orb.width;
+    canvas.height = orb.height;
+  };
+
+  /*
+   * Assigning an unparseable colour to `fillStyle` is a no-op by spec, so the
+   * candidate is tried against two different sentinels: agreeing reads mean the
+   * browser accepted it, differing reads mean it fell through. Reading it back
+   * yields a normalised `#rrggbb`, which is how `oklch()`, `color(display-p3 ...)`
+   * and named colours reach the particle maths without this component
+   * implementing a CSS colour parser.
+   */
+  const normalizeColor = (context: CanvasRenderingContext2D, value: string): string | null => {
+    if (value.length === 0) {
+      return null;
+    }
+    const previous = context.fillStyle;
+    context.fillStyle = '#000000';
+    context.fillStyle = value;
+    const onBlack = context.fillStyle;
+    context.fillStyle = '#ffffff';
+    context.fillStyle = value;
+    const onWhite = context.fillStyle;
+    context.fillStyle = previous;
+    return typeof onBlack === 'string' && onBlack === onWhite ? onBlack : null;
+  };
+
+  /**
+   * The current smoothed audio level, or null when the orb is not being driven
+   * by audio -- no analyser, or not listening -- in which case the caller falls
+   * back to the sine-wave envelope.
+   *
+   * Wrapped because a consumer closing their `AudioContext` while the orb is
+   * still mounted makes the read throw, and an exception inside the rAF
+   * callback kills the loop for good: the orb would freeze rather than degrade.
+   */
+  const audioEnvelope = (deltaMs: number): number | null => {
+    if (!analyser || variant !== 'listening') {
+      audioLevel = 0;
+      return null;
+    }
+    try {
+      const size = analyser.fftSize;
+      if (audioBuffer === null || audioBuffer.length !== size) {
+        audioBuffer = new Uint8Array(size);
+      }
+      analyser.getByteTimeDomainData(audioBuffer);
+      const gain = Number.isFinite(sensitivity) && sensitivity > 0 ? sensitivity : 1;
+      const target = rmsFromTimeDomain(audioBuffer) * gain;
+      audioLevel = followEnvelope(audioLevel, target, deltaMs, AUDIO_ATTACK_MS, AUDIO_RELEASE_MS);
+      return audioLevel;
+    } catch {
+      return null;
+    }
+  };
+
+  /*
+   * The default is the inherited text colour, so the orb is legible on whatever
+   * ground a consumer puts it on and follows their theme without being told.
+   * A fixed default cannot: the first revision of this component shipped a
+   * light grey that was invisible on a light page.
+   *
+   * Resolved every frame rather than once at mount, so a theme switch reaches a
+   * running orb. The cache key is the raw strings, so the parse only repeats
+   * when the page actually changes -- the `getComputedStyle` read is a colour
+   * lookup, which needs no layout.
+   */
+  const particleRgb = (context: CanvasRenderingContext2D): Rgb => {
+    if (canvas === null) {
+      return resolvedRgb;
+    }
+    const styles = getComputedStyle(canvas);
+    const declared = styles.getPropertyValue('--sui-orb-particle-color').trim();
+    const inherited = styles.color.trim();
+    const input = `${declared}|${inherited}`;
+    if (input === resolvedColorInput) {
+      return resolvedRgb;
+    }
+
+    resolvedColorInput = input;
+    const normalized = normalizeColor(context, declared) ?? normalizeColor(context, inherited);
+    resolvedRgb = (normalized === null ? null : parseCssColor(normalized)) ?? FALLBACK_PARTICLE_RGB;
+    return resolvedRgb;
+  };
+
+  const draw = (time: number): void => {
+    if (canvas === null) {
+      return;
+    }
+    const context = canvas.getContext('2d');
+    if (context === null) {
+      return;
+    }
+
+    const delta = previousTime === null ? 16 : Math.min(64, time - previousTime);
+    previousTime = time;
+    if (variant === 'listening') {
+      listeningElapsedMs += delta;
+    }
+
+    const level = audioEnvelope(delta);
+    const reportable = level ?? 0;
+    if (Math.abs(reportable - reportedLevel) >= LEVEL_REPORT_EPSILON) {
+      reportedLevel = reportable;
+      onlevel?.(reportable);
+    }
+    const speed = resolveMotionSpeed(
+      speedMultiplier,
+      variant,
+      listeningElapsedMs,
+      level,
+      reducedMotion
+    );
+    const normalizedDelta = delta / 16;
+    orb.angleX += BASE_ROTATION_X * speed * normalizedDelta;
+    orb.angleY += BASE_ROTATION_Y * speed * normalizedDelta;
+
+    const rgb = particleRgb(context);
+
+    const centreX = orb.width / 2;
+    const centreY = orb.height / 2;
+    const scale = resolveMotionScale(variant, listeningElapsedMs, level, reducedMotion);
+
+    context.clearRect(0, 0, orb.width, orb.height);
+    context.save();
+    context.translate(centreX, centreY);
+    context.scale(scale, scale);
+    context.translate(-centreX, -centreY);
+
+    for (const particle of particles) {
+      const rotated = rotateOrbPoint(
+        { x: particle.baseX, y: particle.baseY, z: particle.baseZ },
+        orb.angleX,
+        orb.angleY
+      );
+      const depth = orbDepthScale(rotated.z, FOCAL_LENGTH);
+      let x = centreX + rotated.x * depth;
+      let y = centreY + rotated.y * depth;
+
+      if (interactive && pointer.x !== null && pointer.y !== null) {
+        const dx = pointer.x - x;
+        const dy = pointer.y - y;
+        const distance = Math.sqrt(dx * dx + dy * dy);
+        if (distance < repelRadius && distance > 0) {
+          const force = (repelRadius - distance) / repelRadius;
+          x -= (dx / distance) * force * 20;
+          y -= (dy / distance) * force * 20;
+        }
+      }
+
+      const gradient = context.createLinearGradient(centreX, centreY, x, y);
+      gradient.addColorStop(0, `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, 0)`);
+      gradient.addColorStop(0.5, `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${depth * 0.25})`);
+      gradient.addColorStop(1, `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${depth * 0.35})`);
+
+      context.beginPath();
+      context.moveTo(centreX, centreY);
+      context.lineTo(x, y);
+      context.strokeStyle = gradient;
+      context.lineWidth = 0.3;
+      context.stroke();
+
+      context.beginPath();
+      context.arc(x, y, particle.size * depth, 0, Math.PI * 2);
+      context.fillStyle = `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${depth * 0.8})`;
+      context.fill();
+    }
+
+    context.restore();
+
+    if (!announcedFirstFrame) {
+      announcedFirstFrame = true;
+      onfirstframe?.();
+    }
+
+    frame = requestAnimationFrame(draw);
+  };
+
+  /*
+   * `matchMedia` builds a fresh `MediaQueryList` on every call and `draw` runs
+   * on every animation frame, so reading the preference inside `draw` scaled
+   * that work with frame rate. It is read once and kept current by the query's
+   * own `change` event instead; `draw` and the two motion resolvers below see
+   * one consistent value for the whole frame either way.
+   */
+  let reducedMotion = prefersReducedMotion();
+
+  const trackPointer = (event: PointerEvent): void => {
+    if (canvas === null || !interactive) {
+      return;
+    }
+    const rect = canvas.getBoundingClientRect();
+    pointer.x = event.clientX - rect.left;
+    pointer.y = event.clientY - rect.top;
+  };
+
+  const releasePointer = (): void => {
+    pointer.x = null;
+    pointer.y = null;
+  };
+
+  onMount(() => {
+    orb.angleX = readPersisted('angleX') ?? 0;
+    orb.angleY = readPersisted('angleY') ?? 0;
+    listeningElapsedMs = readPersisted('listeningMs') ?? 0;
+
+    resize();
+
+    const observer =
+      typeof ResizeObserver === 'function' ? new ResizeObserver(() => resize()) : null;
+    if (observer !== null && container !== null) {
+      observer.observe(container);
+    }
+
+    const motionQuery =
+      typeof window.matchMedia === 'function'
+        ? window.matchMedia('(prefers-reduced-motion: reduce)')
+        : null;
+    const onMotionChange = (event: MediaQueryListEvent): void => {
+      reducedMotion = event.matches;
+    };
+    if (motionQuery !== null) {
+      reducedMotion = motionQuery.matches;
+      motionQuery.addEventListener('change', onMotionChange);
+    }
+
+    frame = requestAnimationFrame(draw);
+
+    return () => {
+      if (frame !== null) {
+        cancelAnimationFrame(frame);
+        frame = null;
+      }
+      motionQuery?.removeEventListener('change', onMotionChange);
+      observer?.disconnect();
+      writePersisted();
+    };
+  });
+</script>
+
+<div
+  bind:this={container}
+  class="voice-orb {classes ?? ''}"
+  data-pw={typeof testId === 'string' ? testId : null}
+  testID={typeof testId === 'string' ? testId : null}
+>
+  <canvas
+    bind:this={canvas}
+    class="voice-orb-canvas"
+    style:height={`${Number.isFinite(height) && height > 0 ? height : 400}px`}
+    onpointermove={trackPointer}
+    onpointerleave={releasePointer}
+    onpointercancel={releasePointer}
+    aria-hidden="true"
+  ></canvas>
+</div>
+
+<style>
+  .voice-orb {
+    width: 100%;
+    overflow: visible;
+  }
+
+  .voice-orb-canvas {
+    width: 100%;
+    display: block;
+    /* Pointer repulsion needs the move events a default touch gesture would eat. */
+    touch-action: none;
+  }
+</style>

package/dist/VoiceOrb/VoiceOrb.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { VoiceOrbProperties } from './properties';
+declare const VoiceOrb: import("svelte").Component<VoiceOrbProperties, {}, "">;
+type VoiceOrb = ReturnType<typeof VoiceOrb>;
+export default VoiceOrb;

package/dist/VoiceOrb/orbMath.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The deterministic half of `VoiceOrb`, extracted so it can be tested.
+ *
+ * This repo's vitest suite runs no canvas — `getContext` is unimplemented in
+ * jsdom — so anything left inside the component is unreachable by a test. The
+ * geometry, the seeding and the listening envelope are all pure, so they live
+ * here and the component keeps only the drawing. Same split as
+ * `Pill/pillTone.ts` and `Table/normalizeColumns.ts`.
+ */
+import type { Rgb } from '../types';
+import type { VoiceOrbVariant } from './properties';
+export type OrbParticle = {
+    baseX: number;
+    baseY: number;
+    baseZ: number;
+    size: number;
+};
+export type OrbPoint = {
+    x: number;
+    y: number;
+    z: number;
+};
+export declare const LISTENING_CYCLE_MS = 3000;
+export declare const LISTENING_SPEED_RANGE: {
+    min: number;
+    max: number;
+};
+export declare const LISTENING_SCALE_RANGE: {
+    min: number;
+    max: number;
+};
+/**
+ * FNV-1a. A string seed has to produce the same number on every mount, or the
+ * orb a consumer keyed to a session id would look different on each navigation
+ * — which is the whole reason the prop exists.
+ */
+export declare const hashSeed: (value: string) => number;
+/**
+ * Turns an explicit `seed` prop into the integer `mulberry32` wants, or null
+ * when there is nothing explicit to resolve -- the caller then falls back to
+ * its own stable per-mount random value rather than treating null as zero.
+ *
+ * A numeric-looking string is parsed back into the number it names rather
+ * than hashed. Every custom-element attribute arrives as a string -- HTML has
+ * no way to write a "number" attribute -- so without this, the web
+ * component's `<sui-voice-orb seed="42">` would hash `"42"` while the Svelte
+ * `seed={42}` it is meant to be the markup spelling of used the number
+ * directly, and the same intended seed would paint two different orbs
+ * depending on which API reached it. A non-numeric string (a session id)
+ * still hashes, unchanged.
+ */
+export declare const resolveExplicitSeed: (seed?: string | number) => number | null;
+/** Mulberry32: small, fast, and reproducible from one integer. */
+export declare const mulberry32: (initial: number) => (() => number);
+/**
+ * Points spread evenly over a sphere.
+ *
+ * `cos(phi)` is taken uniformly in [-1, 1] rather than `phi` itself: sampling
+ * the angle uniformly packs points towards the poles, because the rings of
+ * constant `phi` near a pole have far less circumference than those at the
+ * equator. The visible symptom is two dense caps and a sparse middle.
+ */
+export declare const generateOrbParticles: (count: number, radius: number, random: () => number) => readonly OrbParticle[];
+/** Rotates about X then Y, which is the order the projection assumes. */
+export declare const rotateOrbPoint: (point: OrbPoint, angleX: number, angleY: number) => OrbPoint;
+/**
+ * Perspective depth for a point: 1 at the sphere's centre plane, larger as it
+ * comes towards the viewer. Used for both scale and opacity, so a particle
+ * behind the sphere reads as further away.
+ */
+export declare const orbDepthScale: (z: number, focalLength: number) => number;
+/** The 0..1 breathing envelope, one full cycle per `LISTENING_CYCLE_MS`. */
+export declare const listeningWave: (elapsedMs: number) => number;
+export declare const listeningSpeed: (elapsedMs: number, speedMultiplier: number) => number;
+export declare const listeningScale: (elapsedMs: number) => number;
+/**
+ * Parses the two colour shapes a browser hands back: `getComputedStyle().color`
+ * is always `rgb()`/`rgba()`, and a canvas `fillStyle` read back after a write
+ * is always `#rrggbb` (or `rgba()` when it carries alpha). Between them those
+ * cover every CSS colour syntax, because the canvas does the hard parsing --
+ * `oklch()`, `color(display-p3 ...)` and named colours all normalise through it.
+ *
+ * The library's own `hexToRgb` handles only hex, which is why this exists
+ * alongside it rather than replacing it.
+ */
+export declare const parseCssColor: (value: string) => Rgb | null;
+/** Scale at silence and at full level. Capped at 1 so a shout cannot clip the sphere. */
+export declare const AUDIO_SCALE_RANGE: {
+    min: number;
+    max: number;
+};
+/** Rotation multiplier at silence and at full level, before `speedMultiplier`. */
+export declare const AUDIO_SPEED_RANGE: {
+    min: number;
+    max: number;
+};
+/**
+ * How far the level must move before `onlevel` fires again.
+ *
+ * Without a threshold the callback runs every frame forever, including through
+ * silence, and a consumer who sets component state from it re-renders 60 times
+ * a second for no reason. A hundredth of the range is below anything a meter
+ * or a caption can show.
+ */
+export declare const LEVEL_REPORT_EPSILON = 0.01;
+/** Envelope-follower time constants. Fast onset, unhurried decay. */
+export declare const AUDIO_ATTACK_MS = 60;
+export declare const AUDIO_RELEASE_MS = 320;
+/**
+ * RMS of one buffer of byte time-domain data, as 0..1.
+ *
+ * `getByteTimeDomainData` centres silence on 128, so each sample is an
+ * excursion from that midpoint rather than a magnitude. Treating the raw byte
+ * as amplitude reads silence as roughly full scale.
+ */
+export declare const rmsFromTimeDomain: (samples: Uint8Array) => number;
+/**
+ * One-pole envelope follower, stepped by wall-clock rather than by frame, so
+ * the response is the same on a 60Hz and a 120Hz display.
+ *
+ * Separate attack and release constants are the point: speech is a burst
+ * followed by a gap, and a symmetric filter either chatters through every
+ * syllable or lags the onset that makes the orb feel connected to the voice.
+ */
+export declare const followEnvelope: (current: number, target: number, deltaMs: number, attackMs: number, releaseMs: number) => number;
+export declare const audioScale: (level: number) => number;
+export declare const audioSpeed: (level: number, speedMultiplier: number) => number;
+/** Effective rotation speed for one frame. See the reduced-motion note above. */
+export declare const resolveMotionSpeed: (speedMultiplier: number, variant: VoiceOrbVariant, listeningElapsedMs: number, level: number | null, reducedMotion: boolean) => number;
+/** Effective breathing scale for one frame. Same split as `resolveMotionSpeed`. */
+export declare const resolveMotionScale: (variant: VoiceOrbVariant, listeningElapsedMs: number, level: number | null, reducedMotion: boolean) => number;