@juspay/svelte-ui-components 4.25.0 → 4.26.0

package/dist/VoiceOrb/orbMath.js

@@ -0,0 +1,267 @@
+/**
+ * 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`.
+ */
+const SIZE_RANDOMNESS = 0.95;
+const BASE_PARTICLE_SIZE = 1.6;
+export const LISTENING_CYCLE_MS = 3000;
+export const LISTENING_SPEED_RANGE = { min: 0.8, max: 1.2 };
+export const LISTENING_SCALE_RANGE = { min: 0.9, max: 1 };
+/**
+ * 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 const hashSeed = (value) => {
+    let hash = 2166136261 >>> 0;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return hash >>> 0;
+};
+/**
+ * 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 const resolveExplicitSeed = (seed) => {
+    if (typeof seed === 'number' && Number.isFinite(seed)) {
+        return seed >>> 0;
+    }
+    if (typeof seed !== 'string' || seed.trim().length === 0) {
+        return null;
+    }
+    const numeric = Number(seed);
+    return Number.isFinite(numeric) ? numeric >>> 0 : hashSeed(seed);
+};
+/** Mulberry32: small, fast, and reproducible from one integer. */
+export const mulberry32 = (initial) => {
+    let state = initial | 0;
+    return () => {
+        state = (state + 0x6d2b79f5) | 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+};
+/**
+ * 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 const generateOrbParticles = (count, radius, random) => {
+    const safeCount = Number.isFinite(count) && count > 0 ? Math.floor(count) : 0;
+    const safeRadius = Number.isFinite(radius) && radius > 0 ? radius : 140;
+    const minMultiplier = 1 - SIZE_RANDOMNESS * 0.7;
+    const maxMultiplier = 1 + SIZE_RANDOMNESS * 0.2;
+    const particles = [];
+    for (let index = 0; index < safeCount; index += 1) {
+        const theta = random() * Math.PI * 2;
+        const phi = Math.acos(Math.max(-1, Math.min(1, 2 * random() - 1)));
+        const sinPhi = Math.sin(phi);
+        particles.push({
+            baseX: safeRadius * sinPhi * Math.cos(theta),
+            baseY: safeRadius * sinPhi * Math.sin(theta),
+            baseZ: safeRadius * Math.cos(phi),
+            size: BASE_PARTICLE_SIZE * (minMultiplier + random() * (maxMultiplier - minMultiplier))
+        });
+    }
+    return particles;
+};
+/** Rotates about X then Y, which is the order the projection assumes. */
+export const rotateOrbPoint = (point, angleX, angleY) => {
+    const cosX = Math.cos(angleX);
+    const sinX = Math.sin(angleX);
+    const y = point.y * cosX - point.z * sinX;
+    const z = point.y * sinX + point.z * cosX;
+    const cosY = Math.cos(angleY);
+    const sinY = Math.sin(angleY);
+    return {
+        x: z * sinY + point.x * cosY,
+        y,
+        z: z * cosY - point.x * sinY
+    };
+};
+/**
+ * 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 const orbDepthScale = (z, focalLength) => focalLength / (focalLength + z);
+/** The 0..1 breathing envelope, one full cycle per `LISTENING_CYCLE_MS`. */
+export const listeningWave = (elapsedMs) => {
+    const normalized = (elapsedMs % LISTENING_CYCLE_MS) / LISTENING_CYCLE_MS;
+    return (Math.sin(normalized * Math.PI * 2) + 1) / 2;
+};
+export const listeningSpeed = (elapsedMs, speedMultiplier) => {
+    const base = Number.isFinite(speedMultiplier) ? speedMultiplier : 1;
+    const wave = listeningWave(elapsedMs);
+    return (base *
+        (LISTENING_SPEED_RANGE.min + wave * (LISTENING_SPEED_RANGE.max - LISTENING_SPEED_RANGE.min)));
+};
+export const listeningScale = (elapsedMs) => {
+    const wave = listeningWave(elapsedMs);
+    return LISTENING_SCALE_RANGE.min + wave * (LISTENING_SCALE_RANGE.max - LISTENING_SCALE_RANGE.min);
+};
+/**
+ * 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 const parseCssColor = (value) => {
+    const trimmed = value.trim();
+    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(trimmed);
+    if (hex !== null) {
+        const digits = hex[1];
+        const expanded = digits.length === 3
+            ? `${digits[0]}${digits[0]}${digits[1]}${digits[1]}${digits[2]}${digits[2]}`
+            : digits;
+        return {
+            r: Number.parseInt(expanded.slice(0, 2), 16),
+            g: Number.parseInt(expanded.slice(2, 4), 16),
+            b: Number.parseInt(expanded.slice(4, 6), 16)
+        };
+    }
+    const functional = /^rgba?\(([^)]*)\)$/i.exec(trimmed);
+    if (functional === null) {
+        return null;
+    }
+    const channels = functional[1]
+        .split(/[,\s/]+/)
+        .filter((part) => part.length > 0)
+        .map(Number);
+    if (channels.length < 3 || channels.slice(0, 3).some((channel) => !Number.isFinite(channel))) {
+        return null;
+    }
+    const clamp = (channel) => Math.max(0, Math.min(255, Math.round(channel)));
+    return { r: clamp(channels[0]), g: clamp(channels[1]), b: clamp(channels[2]) };
+};
+/*
+ * Audio-reactive envelope.
+ *
+ * The component never opens a microphone. It reads an `AnalyserNode` the
+ * consumer already owns, which keeps permissions, the `AudioContext` lifecycle
+ * and the choice of source (microphone, an element, a synthesised tone) on the
+ * side of the application that has the context to decide them.
+ */
+/** Scale at silence and at full level. Capped at 1 so a shout cannot clip the sphere. */
+export const AUDIO_SCALE_RANGE = { min: 0.82, max: 1 };
+/** Rotation multiplier at silence and at full level, before `speedMultiplier`. */
+export const AUDIO_SPEED_RANGE = { min: 0.5, max: 2.4 };
+/**
+ * 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 const LEVEL_REPORT_EPSILON = 0.01;
+/** Envelope-follower time constants. Fast onset, unhurried decay. */
+export const AUDIO_ATTACK_MS = 60;
+export 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 const rmsFromTimeDomain = (samples) => {
+    if (samples.length === 0) {
+        return 0;
+    }
+    let total = 0;
+    for (const sample of samples) {
+        const excursion = (sample - 128) / 128;
+        total += excursion * excursion;
+    }
+    return Math.sqrt(total / samples.length);
+};
+/**
+ * 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 const followEnvelope = (current, target, deltaMs, attackMs, releaseMs) => {
+    if (!Number.isFinite(current)) {
+        return 0;
+    }
+    if (!Number.isFinite(target) || !Number.isFinite(deltaMs) || deltaMs <= 0) {
+        return current;
+    }
+    const timeConstant = target > current ? attackMs : releaseMs;
+    if (!Number.isFinite(timeConstant) || timeConstant <= 0) {
+        return target;
+    }
+    const coefficient = 1 - Math.exp(-deltaMs / timeConstant);
+    return current + (target - current) * coefficient;
+};
+const clampLevel = (level) => Number.isFinite(level) ? Math.max(0, Math.min(1, level)) : 0;
+export const audioScale = (level) => AUDIO_SCALE_RANGE.min + clampLevel(level) * (AUDIO_SCALE_RANGE.max - AUDIO_SCALE_RANGE.min);
+export const audioSpeed = (level, speedMultiplier) => {
+    const base = Number.isFinite(speedMultiplier) ? speedMultiplier : 1;
+    return (base *
+        (AUDIO_SPEED_RANGE.min + clampLevel(level) * (AUDIO_SPEED_RANGE.max - AUDIO_SPEED_RANGE.min)));
+};
+/*
+ * `prefers-reduced-motion` support.
+ *
+ * The two decorative sources -- idle rotation and the sine-wave breathing
+ * `listening` rides without an `analyser` -- are what the OS setting exists to
+ * suppress. `level` (non-null only while a real `AnalyserNode` is actually
+ * driving the orb) is left alone in both functions below: it reports what the
+ * microphone is doing right now, which is state, not decoration, and freezing
+ * it would take away the only feedback a caller gave the user that the app is
+ * listening. Documented in docs/VoiceOrb.md's Accessibility section.
+ */
+/** Effective rotation speed for one frame. See the reduced-motion note above. */
+export const resolveMotionSpeed = (speedMultiplier, variant, listeningElapsedMs, level, reducedMotion) => {
+    if (level !== null) {
+        return audioSpeed(level, speedMultiplier);
+    }
+    if (reducedMotion) {
+        return 0;
+    }
+    if (variant === 'listening') {
+        return listeningSpeed(listeningElapsedMs, speedMultiplier);
+    }
+    return Number.isFinite(speedMultiplier) ? speedMultiplier : 1;
+};
+/** Effective breathing scale for one frame. Same split as `resolveMotionSpeed`. */
+export const resolveMotionScale = (variant, listeningElapsedMs, level, reducedMotion) => {
+    if (level !== null) {
+        return audioScale(level);
+    }
+    if (reducedMotion || variant !== 'listening') {
+        return 1;
+    }
+    return listeningScale(listeningElapsedMs);
+};

package/dist/VoiceOrb/properties.d.ts

@@ -0,0 +1,105 @@
+export type VoiceOrbVariant = 'idle' | 'listening';
+export type VoiceOrbProperties = OptionalVoiceOrbProperties & VoiceOrbEventProperties;
+export type MandatoryVoiceOrbProperties = Record<string, never>;
+export type OptionalVoiceOrbProperties = {
+    /**
+     * Animation state. `'idle'` rotates at a steady rate; `'listening'` breathes,
+     * to show an assistant is taking input.
+     *
+     * What drives the breathing depends on whether you pass `analyser`. With one,
+     * `'listening'` is driven by the sound itself. Without one, it rides a sine
+     * wave and is decorative — it says "the microphone is open", never "this is
+     * what it hears".
+     */
+    variant?: VoiceOrbVariant;
+    /**
+     * An `AnalyserNode` to drive the orb from, making `variant='listening'` react
+     * to the sound instead of breathing on a timer. Ignored while `'idle'`.
+     *
+     * The node stays yours. This component never calls `getUserMedia`, never
+     * creates an `AudioContext` and never closes one: microphone permission, the
+     * context lifecycle and the choice of source are decisions that need
+     * application context, and a component that grabbed a microphone because it
+     * was mounted would be a worse component.
+     *
+     * Any source works — a live microphone, an `<audio>` element, a synthesised
+     * tone. Closing the context under a mounted orb is safe: the read is guarded
+     * and the orb falls back to the sine wave rather than freezing.
+     */
+    analyser?: AnalyserNode | null;
+    /**
+     * Multiplies the measured level before it drives the orb. Above `1` makes a
+     * quiet speaker fill the sphere; below `1` tames a hot input. Defaults to `1`.
+     *
+     * Only meaningful alongside `analyser`.
+     */
+    sensitivity?: number;
+    /**
+     * Multiplies the rotation rate. `1` is the designed speed; `0` freezes the
+     * orb mid-rotation without unmounting it.
+     */
+    speedMultiplier?: number;
+    /**
+     * Seeds particle placement, so the same value always produces the same orb.
+     * A number and the numeric string that names it resolve to the same seed
+     * -- `seed={42}` and `seed="42"` paint the same orb, which is what lets a
+     * custom-element attribute (always a string) agree with the Svelte prop it
+     * is the markup spelling of. Any other string is hashed as text. Omitted,
+     * every mount looks different.
+     *
+     * Pass something stable per user or per session if you want the orb to look
+     * like the same object across navigations.
+     */
+    seed?: string | number;
+    /** Rendered height in pixels. Width always fills the container. Defaults to `400`. */
+    height?: number;
+    /** Particles on the sphere. Defaults to `1000`. */
+    particleCount?: number;
+    /** Sphere radius in pixels before projection. Defaults to `140`. */
+    radius?: number;
+    /**
+     * Whether pointer movement pushes particles aside. Defaults to `true`.
+     * Set `false` for a purely ambient orb that ignores the pointer.
+     */
+    interactive?: boolean;
+    /** How far from the pointer the repulsion reaches, in pixels. Defaults to `200`. */
+    repelRadius?: number;
+    /**
+     * Persists rotation across mounts under this `localStorage` key prefix, so
+     * the orb resumes where it stopped rather than snapping back.
+     *
+     * Opt-in, and namespaced by the caller, deliberately. Writing to a
+     * consumer's storage uninvited is not a component's decision to make, and a
+     * fixed key would make two orbs on one page overwrite each other.
+     */
+    persistKey?: string;
+    /** CSS class string applied to the orb's root element. */
+    classes?: string;
+    /** Value for the `data-pw` attribute on the root, for test selectors. */
+    testId?: string;
+};
+export type VoiceOrbEventProperties = {
+    /**
+     * Fires once, on the first frame actually painted — not on mount.
+     *
+     * Named `onfirstframe` rather than `onanimationstart` because the latter is a
+     * real `HTMLElement` accessor for the CSS animationstart event: a web-component
+     * prop of that name would shadow the host's own, which `prop-parity` rejects.
+     *
+     * The gap matters: particle generation and the first paint happen after
+     * mount, so a loading overlay removed on mount reveals an empty canvas. This
+     * fires when there is something to see.
+     */
+    onfirstframe?: () => void;
+    /**
+     * The smoothed audio level, 0..1, as it changes. Only fires while `analyser`
+     * is actually driving the orb, plus once on the way back to 0 when it stops,
+     * so a meter does not stick at the last value it saw.
+     *
+     * Rate-limited by change, not by time: it fires when the level moves by at
+     * least 0.01, which means silence is silent rather than 60 calls a second.
+     * It is still a per-frame callback in the loud case — drive a DOM write or a
+     * cheap store from it, not an expensive re-render.
+     */
+    onlevel?: (level: number) => void;
+};

package/dist/VoiceOrb/properties.js

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

package/dist/index.d.ts

@@ -37,6 +37,7 @@ export { default as Tooltip } from './Tooltip/Tooltip.svelte';
 export { default as TypewriterText } from './TypewriterText/TypewriterText.svelte';
 export { tooltip } from './Tooltip/tooltip-action';
 export { default as Shimmer } from './Shimmer/Shimmer.svelte';
+export { default as VoiceOrb } from './VoiceOrb/VoiceOrb.svelte';
 export { default as Progress } from './Progress/Progress.svelte';
 export { default as Pill } from './Pill/Pill.svelte';
 export { default as Pagination } from './Pagination/Pagination.svelte';
@@ -187,6 +188,7 @@ export type * from './ChipInput/properties';
 export type * from './FileDropzoneTrigger/properties';
 export type * from './_chart/highlight';
 export type * from './_chart/narrationHighlighter';
+export type * from './VoiceOrb/properties';
 export type * from './Chat/properties';
 export type * from './Chat/types';
 export type * from './SpeechToText/types';

package/dist/index.js

@@ -37,6 +37,7 @@ export { default as Tooltip } from './Tooltip/Tooltip.svelte';
 export { default as TypewriterText } from './TypewriterText/TypewriterText.svelte';
 export { tooltip } from './Tooltip/tooltip-action';
 export { default as Shimmer } from './Shimmer/Shimmer.svelte';
+export { default as VoiceOrb } from './VoiceOrb/VoiceOrb.svelte';
 export { default as Progress } from './Progress/Progress.svelte';
 export { default as Pill } from './Pill/Pill.svelte';
 export { default as Pagination } from './Pagination/Pagination.svelte';