fancy-ui-react 0.2.0

package/dist/sound/themes.js

@@ -0,0 +1,355 @@
+import { SOUND_CUES, SOUND_LIMITS } from "./types.js";
+function env(attack, decay, sustain, release) {
+  return { attack, decay, sustain, release };
+}
+function deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const key of Object.keys(value)) {
+      deepFreeze(value[key]);
+    }
+    Object.freeze(value);
+  }
+  return value;
+}
+const FANCY_CUES = {
+  hover: {
+    layers: [
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 1760,
+        frequencyEnd: 1975,
+        gain: 0.12,
+        envelope: env(2, 20, 0, 20),
+        duration: 45,
+        filter: { type: "highpass", frequency: 800 }
+      }
+    ]
+  },
+  press: {
+    layers: [
+      {
+        kind: "oscillator",
+        wave: "triangle",
+        frequency: 520,
+        frequencyEnd: 440,
+        gain: 0.5,
+        envelope: env(2, 35, 0, 25),
+        duration: 70
+      },
+      {
+        kind: "noise",
+        gain: 0.18,
+        envelope: env(1, 18, 0, 8),
+        duration: 30,
+        filter: { type: "bandpass", frequency: 2400, q: 1.2 }
+      }
+    ]
+  },
+  "toggle-on": {
+    layers: [
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 660,
+        gain: 0.4,
+        envelope: env(3, 30, 0.2, 20),
+        duration: 55
+      },
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 880,
+        gain: 0.4,
+        envelope: env(3, 40, 0, 25),
+        duration: 70,
+        delay: 45,
+        filter: { type: "lowpass", frequency: 4e3 }
+      }
+    ]
+  },
+  "toggle-off": {
+    layers: [
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 880,
+        gain: 0.35,
+        envelope: env(3, 30, 0.2, 20),
+        duration: 55
+      },
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 660,
+        gain: 0.32,
+        envelope: env(3, 35, 0, 20),
+        duration: 60,
+        delay: 45,
+        filter: { type: "lowpass", frequency: 3500 }
+      }
+    ]
+  },
+  open: {
+    layers: [
+      {
+        kind: "oscillator",
+        wave: "triangle",
+        frequency: 392,
+        frequencyEnd: 784,
+        gain: 0.35,
+        envelope: env(5, 60, 0.3, 30),
+        duration: 110
+      },
+      {
+        kind: "noise",
+        gain: 0.08,
+        envelope: env(10, 50, 0, 30),
+        duration: 90,
+        filter: { type: "highpass", frequency: 3e3, frequencyEnd: 6e3 }
+      }
+    ]
+  },
+  close: {
+    layers: [
+      {
+        kind: "oscillator",
+        wave: "triangle",
+        frequency: 784,
+        frequencyEnd: 392,
+        gain: 0.3,
+        envelope: env(4, 50, 0.2, 30),
+        duration: 100
+      },
+      {
+        kind: "noise",
+        gain: 0.06,
+        envelope: env(5, 40, 0, 30),
+        duration: 80,
+        filter: { type: "lowpass", frequency: 1500, frequencyEnd: 600 }
+      }
+    ]
+  },
+  select: {
+    layers: [
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 1046.5,
+        gain: 0.35,
+        envelope: env(2, 40, 0, 25),
+        duration: 70
+      },
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 1568,
+        gain: 0.12,
+        envelope: env(2, 30, 0, 18),
+        duration: 50,
+        delay: 10
+      }
+    ]
+  },
+  success: {
+    layers: [
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 523.25,
+        gain: 0.35,
+        envelope: env(4, 60, 0.3, 40),
+        duration: 110,
+        filter: { type: "lowpass", frequency: 5e3 }
+      },
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 659.25,
+        gain: 0.35,
+        envelope: env(4, 60, 0.3, 40),
+        duration: 110,
+        delay: 70,
+        filter: { type: "lowpass", frequency: 5e3 }
+      },
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 783.99,
+        gain: 0.4,
+        envelope: env(4, 60, 0.3, 40),
+        duration: 150,
+        delay: 140,
+        filter: { type: "lowpass", frequency: 5e3 }
+      }
+    ]
+  },
+  error: {
+    layers: [
+      {
+        kind: "oscillator",
+        wave: "sawtooth",
+        frequency: 220,
+        detune: -8,
+        gain: 0.3,
+        envelope: env(5, 70, 0.4, 40),
+        duration: 130,
+        filter: { type: "lowpass", frequency: 900 }
+      },
+      {
+        kind: "oscillator",
+        wave: "sawtooth",
+        frequency: 233,
+        detune: 8,
+        gain: 0.3,
+        envelope: env(5, 70, 0.4, 40),
+        duration: 130,
+        delay: 110,
+        filter: { type: "lowpass", frequency: 900 }
+      }
+    ]
+  },
+  tick: {
+    layers: [
+      {
+        kind: "noise",
+        gain: 0.2,
+        envelope: env(1, 12, 0, 8),
+        duration: 22,
+        filter: { type: "bandpass", frequency: 3500, q: 2 }
+      },
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 2093,
+        gain: 0.08,
+        envelope: env(1, 15, 0, 8),
+        duration: 25
+      }
+    ]
+  },
+  copy: {
+    layers: [
+      {
+        kind: "noise",
+        gain: 0.15,
+        envelope: env(1, 10, 0, 8),
+        duration: 20,
+        filter: { type: "bandpass", frequency: 5e3, q: 1 }
+      },
+      {
+        kind: "oscillator",
+        wave: "sine",
+        frequency: 1318.5,
+        frequencyEnd: 1760,
+        gain: 0.3,
+        envelope: env(2, 50, 0, 25),
+        duration: 80,
+        delay: 8
+      }
+    ]
+  }
+};
+const FANCY_SOUND_THEME = deepFreeze({
+  name: "fancy",
+  cues: FANCY_CUES
+});
+const SOUND_THEMES = Object.freeze({
+  fancy: FANCY_SOUND_THEME
+});
+function getSoundTheme(name) {
+  return SOUND_THEMES[name] ?? FANCY_SOUND_THEME;
+}
+const VALID_WAVES = /* @__PURE__ */ new Set(["sine", "triangle", "square", "sawtooth"]);
+const VALID_FILTERS = /* @__PURE__ */ new Set(["lowpass", "highpass", "bandpass", "notch", "peaking"]);
+function validateSoundTheme(theme) {
+  const problems = [];
+  for (const cue of SOUND_CUES) {
+    const recipe = theme.cues[cue];
+    if (!recipe || !recipe.layers || recipe.layers.length === 0) {
+      problems.push(`${cue}: missing recipe or no layers`);
+      continue;
+    }
+    if (recipe.gain != null) {
+      if (!Number.isFinite(recipe.gain) || recipe.gain < 0) {
+        problems.push(`${cue}: recipe gain must be a finite number >= 0`);
+      } else if (recipe.gain > 1) {
+        problems.push(`${cue}: recipe gain must be <= 1`);
+      }
+    }
+    let maxSpan = 0;
+    recipe.layers.forEach((layer, index) => {
+      const label = `${cue}[${index}]`;
+      const delay = layer.delay ?? 0;
+      const numericFields = [
+        ["gain", layer.gain],
+        ["duration", layer.duration],
+        ["delay", delay],
+        ["envelope.attack", layer.envelope.attack],
+        ["envelope.decay", layer.envelope.decay],
+        ["envelope.sustain", layer.envelope.sustain],
+        ["envelope.release", layer.envelope.release]
+      ];
+      for (const [field, value] of numericFields) {
+        if (!Number.isFinite(value) || value < 0) {
+          problems.push(`${label}: ${field} must be a finite number >= 0`);
+        }
+      }
+      if (Number.isFinite(layer.gain) && layer.gain > 1) {
+        problems.push(`${label}: gain must be <= 1`);
+      }
+      if (Number.isFinite(layer.envelope.sustain) && (layer.envelope.sustain < 0 || layer.envelope.sustain > 1)) {
+        problems.push(`${label}: envelope.sustain must be between 0 and 1`);
+      }
+      const requiredSpan = layer.envelope.attack + layer.envelope.decay + layer.envelope.release;
+      if (Number.isFinite(layer.duration) && layer.duration < requiredSpan) {
+        problems.push(`${label}: duration must be >= attack + decay + release`);
+      }
+      if (Number.isFinite(layer.duration) && layer.duration > SOUND_LIMITS.MAX_LAYER_MS) {
+        problems.push(`${label}: duration must be <= ${SOUND_LIMITS.MAX_LAYER_MS}ms`);
+      }
+      if (layer.kind === "oscillator") {
+        if (!VALID_WAVES.has(layer.wave)) {
+          problems.push(`${label}: invalid wave "${layer.wave}"`);
+        }
+        if (!Number.isFinite(layer.frequency) || layer.frequency <= 0) {
+          problems.push(`${label}: frequency must be a finite number > 0`);
+        }
+        if (layer.frequencyEnd != null && (!Number.isFinite(layer.frequencyEnd) || layer.frequencyEnd <= 0)) {
+          problems.push(`${label}: frequencyEnd must be a finite number > 0`);
+        }
+        if (layer.detune != null && !Number.isFinite(layer.detune)) {
+          problems.push(`${label}: detune must be a finite number`);
+        }
+      }
+      if (layer.filter) {
+        if (!VALID_FILTERS.has(layer.filter.type)) {
+          problems.push(`${label}: invalid filter type "${layer.filter.type}"`);
+        }
+        if (!Number.isFinite(layer.filter.frequency) || layer.filter.frequency <= 0) {
+          problems.push(`${label}: filter frequency must be a finite number > 0`);
+        }
+        if (layer.filter.frequencyEnd != null && (!Number.isFinite(layer.filter.frequencyEnd) || layer.filter.frequencyEnd <= 0)) {
+          problems.push(`${label}: filter frequencyEnd must be a finite number > 0`);
+        }
+        if (layer.filter.q != null && !Number.isFinite(layer.filter.q)) {
+          problems.push(`${label}: filter q must be a finite number`);
+        }
+      }
+      if (Number.isFinite(delay) && Number.isFinite(layer.duration)) {
+        maxSpan = Math.max(maxSpan, delay + layer.duration);
+      }
+    });
+    const spanLimit = cue === "success" || cue === "error" ? 300 : 120;
+    if (maxSpan > spanLimit) {
+      problems.push(`${cue}: total span ${maxSpan}ms exceeds ${spanLimit}ms limit`);
+    }
+  }
+  return problems;
+}
+export {
+  FANCY_SOUND_THEME,
+  SOUND_THEMES,
+  getSoundTheme,
+  validateSoundTheme
+};

package/dist/sound/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Sound design — shared types and constants.
+ *
+ * Themes are DATA (a map from semantic cue to a synthesis recipe) and the
+ * engine is the interpreter. Components only ever name a cue; they never
+ * know how it sounds, which is what lets a future sound theme follow a visual
+ * skin without coupling audio code to it.
+ *
+ * This module has no runtime side effects and touches no browser global.
+ */
+/** Semantic UI cues. Every theme defines a recipe for each one. */
+export declare const SOUND_CUES: readonly ["hover", "press", "toggle-on", "toggle-off", "open", "close", "select", "success", "error", "tick", "copy"];
+export type SoundCue = (typeof SOUND_CUES)[number];
+export declare const SOUND_THEME_NAMES: readonly ["fancy"];
+export type SoundThemeName = (typeof SOUND_THEME_NAMES)[number];
+export interface SoundPlayOptions {
+    /** Multiplier on the cue's own gain, clamped to [0, 1]. Default 1. */
+    volume?: number;
+    /** Semitone offset applied to every oscillator layer, clamped to [-24, 24]. Noise layers are unaffected. Default 0. */
+    pitch?: number;
+    /** Time-stretch divisor on every envelope, duration and delay, clamped to [0.25, 4]. 2 = twice as fast. Default 1. */
+    playbackRate?: number;
+}
+export interface SoundPreferences {
+    /** Master switch. Default false — sound is strictly opt-in. */
+    enabled: boolean;
+    /** 0..1, default 0.5. The engine multiplies it again by SOUND_LIMITS.MASTER_CEILING. */
+    volume: number;
+    theme: SoundThemeName;
+}
+export declare const DEFAULT_SOUND_PREFERENCES: Readonly<SoundPreferences>;
+/** What `localStorage["fancy-ui-sound"]` holds: `{ v: 1, ...SoundPreferences }`. */
+export interface SoundPreferencesV1 extends SoundPreferences {
+    v: 1;
+}
+export declare const SOUND_STORAGE_KEY = "fancy-ui-sound";
+export type SoundWave = "sine" | "triangle" | "square" | "sawtooth";
+/** All times in milliseconds (before `playbackRate`). `sustain` is a level 0..1. */
+export interface SoundEnvelope {
+    attack: number;
+    decay: number;
+    sustain: number;
+    release: number;
+}
+export interface SoundFilter {
+    type: "lowpass" | "highpass" | "bandpass" | "notch" | "peaking";
+    /** Hz at the layer's start. */
+    frequency: number;
+    /** Hz at the layer's end; exponential glide over the layer's `duration` when set. */
+    frequencyEnd?: number;
+    q?: number;
+}
+interface SoundLayerBase {
+    /** Peak linear gain 0..1 (engine clamps to SOUND_LIMITS.LAYER_PEAK_CEILING). */
+    gain: number;
+    envelope: SoundEnvelope;
+    filter?: SoundFilter;
+    /** Ms after the cue's start before this layer begins. Default 0. */
+    delay?: number;
+    /** Total ms from this layer's start to the end of its release. Release begins at `duration - envelope.release`. */
+    duration: number;
+}
+export interface SoundOscillatorLayer extends SoundLayerBase {
+    kind: "oscillator";
+    wave: SoundWave;
+    /** Hz at start. */
+    frequency: number;
+    /** Hz at end; exponential glide over `duration` when set. */
+    frequencyEnd?: number;
+    /** Cents. Default 0. */
+    detune?: number;
+}
+export interface SoundNoiseLayer extends SoundLayerBase {
+    kind: "noise";
+}
+export type SoundLayer = SoundOscillatorLayer | SoundNoiseLayer;
+export interface CueRecipe {
+    layers: SoundLayer[];
+    /** Trim applied to every layer, 0..1. Default 1. */
+    gain?: number;
+}
+export interface SoundThemeDefinition {
+    name: SoundThemeName;
+    cues: Record<SoundCue, CueRecipe>;
+}
+/**
+ * idle         — no AudioContext yet (nothing attempted, or attempted outside a user gesture)
+ * ready        — context running
+ * suspended    — context exists but is suspended/interrupted; resume pending or awaiting next gesture
+ * unsupported  — no AudioContext constructor, or construction threw (also SSR)
+ * blocked      — resume() rejected, or the context is closed
+ */
+export type SoundEngineState = "idle" | "ready" | "suspended" | "unsupported" | "blocked";
+/** Default same-cue minimum interval, ms. Engine-enforced, independent of the action's own guards. */
+export declare const SOUND_MIN_INTERVAL_MS: Readonly<Record<SoundCue, number>>;
+/** Hard safety limits. Not configurable. */
+export declare const SOUND_LIMITS: Readonly<{
+    /** Master gain = prefs.volume * MASTER_CEILING. */
+    MASTER_CEILING: 0.8;
+    /** Per-layer peak gain clamp. */
+    LAYER_PEAK_CEILING: 0.9;
+    /** Concurrent voices; extra `play()` calls are dropped, never steal. */
+    MAX_VOICES: 8;
+    /** Minimum attack / release enforced for click-free edges. */
+    MIN_ATTACK_MS: 2;
+    MIN_RELEASE_MS: 8;
+    /** Longest any single layer may run (guards a malformed theme). */
+    MAX_LAYER_MS: 400;
+}>;
+export interface SoundStatus {
+    /** `true` once an AudioContext constructor was found in this environment. `false` on the server and until first probe. */
+    supported: boolean;
+    enabled: boolean;
+    volume: number;
+    theme: SoundThemeName;
+    engine: SoundEngineState;
+    /** Outcome of the most recent storage read/write. */
+    storage: "untouched" | "ok" | "unavailable" | "error";
+    lastCue: SoundCue | null;
+    /** `performance.now()` of the last cue actually scheduled, or null. */
+    lastPlayedAt: number | null;
+    /** Last swallowed Web Audio / storage error message, for the Sound Lab status line. */
+    lastError: string | null;
+}
+export {};

package/dist/sound/types.js

@@ -0,0 +1,54 @@
+const SOUND_CUES = [
+  "hover",
+  "press",
+  "toggle-on",
+  "toggle-off",
+  "open",
+  "close",
+  "select",
+  "success",
+  "error",
+  "tick",
+  "copy"
+];
+const SOUND_THEME_NAMES = ["fancy"];
+const DEFAULT_SOUND_PREFERENCES = Object.freeze({
+  enabled: false,
+  volume: 0.5,
+  theme: "fancy"
+});
+const SOUND_STORAGE_KEY = "fancy-ui-sound";
+const SOUND_MIN_INTERVAL_MS = Object.freeze({
+  hover: 60,
+  tick: 40,
+  select: 40,
+  press: 15,
+  "toggle-on": 15,
+  "toggle-off": 15,
+  open: 15,
+  close: 15,
+  success: 15,
+  error: 15,
+  copy: 15
+});
+const SOUND_LIMITS = Object.freeze({
+  /** Master gain = prefs.volume * MASTER_CEILING. */
+  MASTER_CEILING: 0.8,
+  /** Per-layer peak gain clamp. */
+  LAYER_PEAK_CEILING: 0.9,
+  /** Concurrent voices; extra `play()` calls are dropped, never steal. */
+  MAX_VOICES: 8,
+  /** Minimum attack / release enforced for click-free edges. */
+  MIN_ATTACK_MS: 2,
+  MIN_RELEASE_MS: 8,
+  /** Longest any single layer may run (guards a malformed theme). */
+  MAX_LAYER_MS: 400
+});
+export {
+  DEFAULT_SOUND_PREFERENCES,
+  SOUND_CUES,
+  SOUND_LIMITS,
+  SOUND_MIN_INTERVAL_MS,
+  SOUND_STORAGE_KEY,
+  SOUND_THEME_NAMES
+};

package/dist/sound/use-sound.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The React bindings over the sound singleton.
+ *
+ * Two audiences, two hooks. A component with a `sound` PROP only ever plays a
+ * cue, so it uses `useSoundCue` and never subscribes. A control that RENDERS
+ * the preference — SoundToggle, the docs' Sound Lab — reads the store through
+ * `useSound` / `useSoundEnabled` / `useSoundStatus`, which subscribe and which
+ * trigger the one lazy `localStorage` read from an effect.
+ */
+import { type SoundController, type SoundSnapshot } from "./sound.js";
+import type { SoundCue, SoundEngineState, SoundPlayOptions, SoundStatus } from "./types.js";
+/** The imperative half of `useSound()`'s return value. */
+export type SoundControls = Pick<SoundController, "play" | "unlock" | "enable" | "disable" | "toggle" | "setEnabled" | "setVolume" | "setTheme">;
+/**
+ * A cue player for a component's own `sound` prop. Permanently identity-stable;
+ * a no-op while `enabled` is falsy.
+ *
+ * DELIBERATELY DOES NOT SUBSCRIBE — a Button must not re-render because the
+ * user changed the volume in a settings panel elsewhere on the page. Whether a
+ * cue is audible is decided inside `sound.play()` at call time, which is also
+ * where the lazy hydration happens for this path.
+ */
+export declare function useSoundCue(enabled: boolean | undefined): (cue: SoundCue, options?: SoundPlayOptions) => void;
+/**
+ * The full store plus the imperative controls. Subscribes, and runs
+ * `hydrateSound()` in an effect. For controls that RENDER the preference.
+ */
+export declare function useSound(): SoundSnapshot & SoundControls;
+/**
+ * Just the master switch. Selecting the scalar rather than the snapshot is what
+ * keeps a toggle from re-rendering on every cue: `status.lastPlayedAt` moves on
+ * each `play()`, and `useSyncExternalStore` bails out when the selected value
+ * is `Object.is`-equal.
+ */
+export declare function useSoundEnabled(): boolean;
+/**
+ * The live status object (identity-cached by the store).
+ *
+ * A reader of the WHOLE object wakes for every field, `lastCue` and
+ * `lastPlayedAt` included — so a component using this re-renders on every cue
+ * played anywhere on the page. Read a single field through a selector hook
+ * (`useSoundEnabled`, `useSoundEngineState`) unless you genuinely render more
+ * than one.
+ */
+export declare function useSoundStatus(): SoundStatus;
+/**
+ * Just the engine's state. Internal to the family — SoundToggle renders this
+ * one field of `status`, and `markPlayed()` rewrites the whole status object on
+ * every cue, so selecting the scalar is what keeps a toggle from re-rendering
+ * because a button elsewhere on the page made a sound. Same `Object.is`
+ * bail-out `useSoundEnabled` relies on.
+ */
+export declare function useSoundEngineState(): SoundEngineState;

package/dist/sound/use-sound.js

@@ -0,0 +1,82 @@
+"use client";
+import { useSyncExternalStore, useMemo, useCallback, useEffect } from "react";
+import { useLiveRef } from "../internals/dom/use-live-ref.js";
+import { subscribeSound, getSoundSnapshot, getSoundServerSnapshot, sound, hydrateSound } from "./sound.js";
+const CONTROLS = Object.freeze({
+  play(cue, options) {
+    sound.play(cue, options);
+  },
+  unlock() {
+    return sound.unlock();
+  },
+  enable() {
+    sound.enable();
+  },
+  disable() {
+    sound.disable();
+  },
+  toggle() {
+    return sound.toggle();
+  },
+  setEnabled(enabled) {
+    sound.setEnabled(enabled);
+  },
+  setVolume(volume) {
+    sound.setVolume(volume);
+  },
+  setTheme(theme) {
+    sound.setTheme(theme);
+  }
+});
+const getEnabled = () => getSoundSnapshot().enabled;
+const getServerEnabled = () => getSoundServerSnapshot().enabled;
+const getStatus = () => getSoundSnapshot().status;
+const getServerStatus = () => getSoundServerSnapshot().status;
+const getEngineState = () => getSoundSnapshot().status.engine;
+const getServerEngineState = () => getSoundServerSnapshot().status.engine;
+function useHydrateSound() {
+  useEffect(() => {
+    hydrateSound();
+  }, []);
+}
+function useSoundCue(enabled) {
+  const enabledRef = useLiveRef(enabled);
+  return useCallback(
+    (cue, options) => {
+      if (!enabledRef.current) return;
+      sound.play(cue, options);
+    },
+    [enabledRef]
+  );
+}
+function useSound() {
+  const snapshot = useSyncExternalStore(
+    subscribeSound,
+    getSoundSnapshot,
+    getSoundServerSnapshot
+  );
+  useHydrateSound();
+  return useMemo(() => ({ ...snapshot, ...CONTROLS }), [snapshot]);
+}
+function useSoundEnabled() {
+  const enabled = useSyncExternalStore(subscribeSound, getEnabled, getServerEnabled);
+  useHydrateSound();
+  return enabled;
+}
+function useSoundStatus() {
+  const status = useSyncExternalStore(subscribeSound, getStatus, getServerStatus);
+  useHydrateSound();
+  return status;
+}
+function useSoundEngineState() {
+  const engineState = useSyncExternalStore(subscribeSound, getEngineState, getServerEngineState);
+  useHydrateSound();
+  return engineState;
+}
+export {
+  useSound,
+  useSoundCue,
+  useSoundEnabled,
+  useSoundEngineState,
+  useSoundStatus
+};