@1889ca/ui 0.5.1 → 0.6.0

package/src/hooks/useSound.js

@@ -0,0 +1,106 @@
+/** Contract: contracts/packages-ui-hooks/rules.md */
+
+import { useRef, useCallback, useMemo } from 'react';
+
+/**
+ * Opt-in sound design — subtle audio feedback for UI interactions.
+ * Uses Web Audio API to generate sounds procedurally (no audio files).
+ *
+ * @param {boolean} enabled - Enable sound (default false, fully opt-in)
+ * @param {number} volume - Master volume 0-1 (default 0.15)
+ * @returns {{ tick, pop, whoosh, click }}
+ */
+export default function useSound({ enabled = false, volume = 0.15 } = {}) {
+  const ctxRef = useRef(null);
+
+  const getCtx = useCallback(() => {
+    if (!enabled) return null;
+    if (!ctxRef.current) {
+      try {
+        ctxRef.current = new (window.AudioContext || window.webkitAudioContext)();
+      } catch {
+        return null;
+      }
+    }
+    return ctxRef.current;
+  }, [enabled]);
+
+  const play = useCallback((fn) => {
+    const ctx = getCtx();
+    if (!ctx) return;
+    // Resume if suspended (autoplay policy)
+    if (ctx.state === 'suspended') ctx.resume();
+    fn(ctx);
+  }, [getCtx]);
+
+  return useMemo(() => ({
+    /** Soft tick — for toggles, checkboxes */
+    tick: () => play((ctx) => {
+      const osc = ctx.createOscillator();
+      const gain = ctx.createGain();
+      osc.connect(gain);
+      gain.connect(ctx.destination);
+      osc.frequency.setValueAtTime(800, ctx.currentTime);
+      osc.frequency.exponentialRampToValueAtTime(1200, ctx.currentTime + 0.04);
+      gain.gain.setValueAtTime(volume * 0.6, ctx.currentTime);
+      gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + 0.08);
+      osc.start(ctx.currentTime);
+      osc.stop(ctx.currentTime + 0.08);
+    }),
+
+    /** Gentle pop — for toasts, notifications */
+    pop: () => play((ctx) => {
+      const osc = ctx.createOscillator();
+      const gain = ctx.createGain();
+      osc.connect(gain);
+      gain.connect(ctx.destination);
+      osc.type = 'sine';
+      osc.frequency.setValueAtTime(600, ctx.currentTime);
+      osc.frequency.exponentialRampToValueAtTime(900, ctx.currentTime + 0.03);
+      osc.frequency.exponentialRampToValueAtTime(400, ctx.currentTime + 0.12);
+      gain.gain.setValueAtTime(volume * 0.5, ctx.currentTime);
+      gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + 0.15);
+      osc.start(ctx.currentTime);
+      osc.stop(ctx.currentTime + 0.15);
+    }),
+
+    /** Whisper whoosh — for panels sliding, modals opening */
+    whoosh: () => play((ctx) => {
+      const bufferSize = ctx.sampleRate * 0.15;
+      const buffer = ctx.createBuffer(1, bufferSize, ctx.sampleRate);
+      const data = buffer.getChannelData(0);
+      for (let i = 0; i < bufferSize; i++) {
+        data[i] = (Math.random() * 2 - 1) * (1 - i / bufferSize);
+      }
+      const source = ctx.createBufferSource();
+      source.buffer = buffer;
+      const filter = ctx.createBiquadFilter();
+      filter.type = 'bandpass';
+      filter.frequency.setValueAtTime(2000, ctx.currentTime);
+      filter.frequency.exponentialRampToValueAtTime(800, ctx.currentTime + 0.12);
+      filter.Q.value = 0.5;
+      const gain = ctx.createGain();
+      gain.gain.setValueAtTime(volume * 0.3, ctx.currentTime);
+      gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + 0.15);
+      source.connect(filter);
+      filter.connect(gain);
+      gain.connect(ctx.destination);
+      source.start(ctx.currentTime);
+    }),
+
+    /** Micro click — for button presses */
+    click: () => play((ctx) => {
+      const osc = ctx.createOscillator();
+      const gain = ctx.createGain();
+      osc.connect(gain);
+      gain.connect(ctx.destination);
+      osc.type = 'square';
+      osc.frequency.setValueAtTime(1800, ctx.currentTime);
+      osc.frequency.exponentialRampToValueAtTime(600, ctx.currentTime + 0.02);
+      gain.gain.setValueAtTime(volume * 0.2, ctx.currentTime);
+      gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + 0.04);
+      osc.start(ctx.currentTime);
+      osc.stop(ctx.currentTime + 0.04);
+    }),
+  }), [play, volume]);
+}

package/src/hooks/useTheme.js

@@ -0,0 +1,90 @@
+/** Contract: contracts/packages-ui-hooks/rules.md */
+import { useState, useEffect, useCallback } from 'react';
+import { deriveAccentTokens } from '../utils/accentColors.js';
+
+const THEME_KEY = 'ui-theme';
+const ACCENT_KEY = 'ui-accent';
+
+/**
+ * Theme manager. Sets `data-theme` attribute on <html> and persists choice.
+ * Optionally sets a custom accent color that overrides the default purple.
+ *
+ * @param {string} defaultTheme - 'dark' | 'light' | 'system' (default: 'system')
+ * @returns {{ theme, resolvedTheme, setTheme, toggle, accent, setAccent, clearAccent }}
+ *   - theme: current setting ('dark' | 'light' | 'system')
+ *   - resolvedTheme: actual applied theme ('dark' | 'light')
+ *   - setTheme(theme): set to 'dark', 'light', or 'system'
+ *   - toggle(): cycle between dark and light
+ *   - accent: current accent hex string or null (null = default purple)
+ *   - setAccent(hex): set a custom accent color, e.g. '#e74c3c'
+ *   - clearAccent(): revert to default purple
+ */
+export default function useTheme(defaultTheme = 'system') {
+  const [theme, setThemeState] = useState(() => {
+    try { return localStorage.getItem(THEME_KEY) || defaultTheme; }
+    catch { return defaultTheme; }
+  });
+
+  const [accent, setAccentState] = useState(() => {
+    try { return localStorage.getItem(ACCENT_KEY) || null; }
+    catch { return null; }
+  });
+
+  const getSystemTheme = useCallback(() => {
+    if (typeof window === 'undefined') return 'dark';
+    return window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
+  }, []);
+
+  const resolvedTheme = theme === 'system' ? getSystemTheme() : theme;
+
+  // Apply data-theme attribute
+  useEffect(() => {
+    const root = document.documentElement;
+    if (theme === 'system') {
+      root.removeAttribute('data-theme');
+    } else {
+      root.setAttribute('data-theme', theme);
+    }
+    try { localStorage.setItem(THEME_KEY, theme); } catch {}
+  }, [theme]);
+
+  // Apply accent color overrides
+  useEffect(() => {
+    const root = document.documentElement;
+    if (!accent) {
+      // Remove overrides — fall back to tokens.css defaults
+      ['--ui-accent', '--ui-accent-hover', '--ui-accent-glow', '--ui-accent-subtle', '--ui-accent-muted']
+        .forEach(prop => root.style.removeProperty(prop));
+      try { localStorage.removeItem(ACCENT_KEY); } catch {}
+      return;
+    }
+    const tokens = deriveAccentTokens(accent, resolvedTheme);
+    Object.entries(tokens).forEach(([prop, value]) => {
+      root.style.setProperty(prop, value);
+    });
+    try { localStorage.setItem(ACCENT_KEY, accent); } catch {}
+  }, [accent, resolvedTheme]);
+
+  // Listen for system preference changes when in system mode
+  useEffect(() => {
+    if (theme !== 'system') return;
+    const mql = window.matchMedia('(prefers-color-scheme: light)');
+    const onChange = () => setThemeState(prev => prev); // force re-render
+    mql.addEventListener('change', onChange);
+    return () => mql.removeEventListener('change', onChange);
+  }, [theme]);
+
+  const setTheme = useCallback((t) => setThemeState(t), []);
+
+  const toggle = useCallback(() => {
+    setThemeState(prev => {
+      const current = prev === 'system' ? getSystemTheme() : prev;
+      return current === 'dark' ? 'light' : 'dark';
+    });
+  }, [getSystemTheme]);
+
+  const setAccent = useCallback((hex) => setAccentState(hex), []);
+  const clearAccent = useCallback(() => setAccentState(null), []);
+
+  return { theme, resolvedTheme, setTheme, toggle, accent, setAccent, clearAccent };
+}

package/src/index.js

@@ -21,6 +21,21 @@ import './components/PasskeyLoginPage.css';
 import './components/UserMenu.css';
 import './components/StatusBar.css';
 import './components/Panel.css';
+import './components/Toast.css';
+import './components/Tooltip.css';
+import './components/Toggle.css';
+import './components/TabBar.css';
+import './components/Skeleton.css';
+import './components/EmptyState.css';
+import './components/ThemeToggle.css';
+
+/* Effects */
+import './effects/edge-light.css';
+import './effects/ambient-glow.css';
+import './effects/haptic.css';
+import './effects/glow-focus.css';
+import './effects/scroll-parallax.css';
+import './effects/glass-tint.css';
 
 /* Components */
 export { default as ContextMenu } from './components/ContextMenu.jsx';
@@ -40,6 +55,13 @@ export { default as PasskeyLoginPage } from './components/PasskeyLoginPage.jsx';
 export { default as UserMenu } from './components/UserMenu.jsx';
 export { default as StatusBar } from './components/StatusBar.jsx';
 export { default as Panel } from './components/Panel.jsx';
+export { ToastProvider, useToast } from './components/Toast.jsx';
+export { default as Tooltip } from './components/Tooltip.jsx';
+export { default as Toggle } from './components/Toggle.jsx';
+export { default as TabBar } from './components/TabBar.jsx';
+export { default as Skeleton } from './components/Skeleton.jsx';
+export { default as EmptyState } from './components/EmptyState.jsx';
+export { default as ThemeToggle } from './components/ThemeToggle.jsx';
 
 /* Auth */
 export { AuthProvider, useAuth } from './auth/AuthProvider.jsx';
@@ -50,6 +72,20 @@ export { default as useMultiSelect } from './hooks/useMultiSelect.js';
 export { default as useItemDrag } from './hooks/useItemDrag.js';
 export { default as useLightboxNav } from './hooks/useLightboxNav.js';
 export { default as useKeyboardShortcuts } from './hooks/useKeyboardShortcuts.js';
+export { default as useClickOutside } from './hooks/useClickOutside.js';
+export { default as useLocalStorage } from './hooks/useLocalStorage.js';
+export { default as useMediaQuery } from './hooks/useMediaQuery.js';
+export { default as useTheme } from './hooks/useTheme.js';
+export { default as useMagnet } from './hooks/useMagnet.js';
+export { default as useScrollParallax } from './hooks/useScrollParallax.js';
+export { default as useSound } from './hooks/useSound.js';
+
+/* Effects (components) */
+export { default as Particles } from './effects/Particles.jsx';
+
+/* Utils */
+export { deriveAccentTokens } from './utils/accentColors.js';
+export { startViewTransition } from './utils/viewTransition.js';
 
 /* Icons */
 export { DownloadIcon, FolderIcon, ChevronLeftIcon, ChevronRightIcon, CloseIcon } from './icons/common.jsx';

package/src/styles/primitives.css

@@ -73,6 +73,15 @@
   pointer-events: none;
 }
 
+.ui-btn:active:not(:disabled) {
+  transform: scale(0.97);
+  transition-duration: 0.1s;
+}
+
+.ui-btn-primary:active:not(:disabled) {
+  transform: translateY(0) scale(0.97);
+}
+
 .ui-btn-sm {
   padding: 0.25rem 0.6rem;
   font-size: 0.78rem;
@@ -122,7 +131,7 @@
 .ui-aurora::before {
   content: '';
   position: fixed;
-  inset: 0;
+  inset: -20%;
   background:
     radial-gradient(ellipse 80% 60% at 15% 10%, rgba(124, 108, 240, 0.084), transparent),
     radial-gradient(ellipse 60% 50% at 85% 20%, rgba(56, 189, 248, 0.056), transparent),
@@ -131,6 +140,14 @@
     radial-gradient(ellipse 40% 30% at 50% 50%, rgba(244, 114, 182, 0.028), transparent);
   pointer-events: none;
   z-index: 0;
+  animation: ui-aurora-drift 25s ease-in-out infinite alternate;
+}
+
+@keyframes ui-aurora-drift {
+  0% { transform: translate(0, 0) rotate(0deg); }
+  33% { transform: translate(2%, -1%) rotate(0.5deg); }
+  66% { transform: translate(-1%, 2%) rotate(-0.5deg); }
+  100% { transform: translate(1%, -2%) rotate(0.3deg); }
 }
 
 .ui-aurora::after {
@@ -148,3 +165,33 @@
   position: relative;
   z-index: 1;
 }
+
+/* ── Light theme adjustments ── */
+
+@media (prefers-color-scheme: light) {
+  :root:not([data-theme]) .ui-aurora::before {
+    background:
+      radial-gradient(ellipse 80% 60% at 15% 10%, rgba(108, 92, 231, 0.08), transparent),
+      radial-gradient(ellipse 60% 50% at 85% 20%, rgba(56, 189, 248, 0.06), transparent),
+      radial-gradient(ellipse 50% 60% at 40% 90%, rgba(168, 85, 247, 0.07), transparent),
+      radial-gradient(ellipse 70% 40% at 75% 75%, rgba(34, 211, 153, 0.05), transparent),
+      radial-gradient(ellipse 40% 30% at 50% 50%, rgba(244, 114, 182, 0.04), transparent);
+  }
+
+  :root:not([data-theme]) .ui-aurora::after {
+    opacity: 0.015;
+  }
+}
+
+[data-theme="light"] .ui-aurora::before {
+  background:
+    radial-gradient(ellipse 80% 60% at 15% 10%, rgba(108, 92, 231, 0.08), transparent),
+    radial-gradient(ellipse 60% 50% at 85% 20%, rgba(56, 189, 248, 0.06), transparent),
+    radial-gradient(ellipse 50% 60% at 40% 90%, rgba(168, 85, 247, 0.07), transparent),
+    radial-gradient(ellipse 70% 40% at 75% 75%, rgba(34, 211, 153, 0.05), transparent),
+    radial-gradient(ellipse 40% 30% at 50% 50%, rgba(244, 114, 182, 0.04), transparent);
+}
+
+[data-theme="light"] .ui-aurora::after {
+  opacity: 0.015;
+}

package/src/styles/tokens.css

@@ -46,7 +46,96 @@
   --ui-shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.5), 0 0 1px rgba(255, 255, 255, 0.05);
   --ui-shadow-float: 0 12px 40px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.06);
 
+  /* Glass surfaces — used by overlays, menus, panels */
+  --ui-glass: rgba(18, 18, 24, 0.82);
+  --ui-glass-heavy: rgba(18, 18, 24, 0.88);
+  --ui-glass-bar: rgba(8, 8, 12, 0.75);
+  --ui-backdrop: rgba(0, 0, 0, 0.5);
+
   /* Transitions */
   --ui-ease: cubic-bezier(0.4, 0, 0.2, 1);
   --ui-ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
 }
+
+/* ── Light theme ── */
+
+[data-theme="light"] {
+  /* Core palette */
+  --ui-bg: #f5f5f7;
+  --ui-surface: rgba(0, 0, 0, 0.03);
+  --ui-surface-raised: rgba(0, 0, 0, 0.06);
+  --ui-surface-solid: #eaeaef;
+  --ui-border: rgba(0, 0, 0, 0.1);
+  --ui-border-subtle: rgba(0, 0, 0, 0.06);
+  --ui-border-strong: rgba(0, 0, 0, 0.16);
+
+  /* Accent — slightly deeper for contrast on light */
+  --ui-accent: #6c5ce7;
+  --ui-accent-hover: #5a4bd6;
+  --ui-accent-glow: rgba(108, 92, 231, 0.2);
+  --ui-accent-subtle: rgba(108, 92, 231, 0.08);
+  --ui-accent-muted: rgba(108, 92, 231, 0.12);
+
+  /* Semantic */
+  --ui-danger: #e84057;
+  --ui-danger-glow: rgba(232, 64, 87, 0.15);
+  --ui-success: #22b573;
+
+  /* Text */
+  --ui-text: #1a1a2e;
+  --ui-text-muted: #5c5c7a;
+  --ui-text-subtle: #9494ab;
+
+  /* Glass surfaces */
+  --ui-glass: rgba(255, 255, 255, 0.82);
+  --ui-glass-heavy: rgba(255, 255, 255, 0.9);
+  --ui-glass-bar: rgba(255, 255, 255, 0.8);
+  --ui-backdrop: rgba(0, 0, 0, 0.25);
+
+  /* Shadows — lighter, warmer */
+  --ui-shadow: 0 1px 3px rgba(0, 0, 0, 0.08), 0 1px 2px rgba(0, 0, 0, 0.06);
+  --ui-shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.1), 0 0 1px rgba(0, 0, 0, 0.08);
+  --ui-shadow-float: 0 12px 40px rgba(0, 0, 0, 0.12), 0 0 0 1px rgba(0, 0, 0, 0.06);
+}
+
+/* Auto light mode — respects system preference when no data-theme is set */
+@media (prefers-color-scheme: light) {
+  :root:not([data-theme]) {
+    /* Core palette */
+    --ui-bg: #f5f5f7;
+    --ui-surface: rgba(0, 0, 0, 0.03);
+    --ui-surface-raised: rgba(0, 0, 0, 0.06);
+    --ui-surface-solid: #eaeaef;
+    --ui-border: rgba(0, 0, 0, 0.1);
+    --ui-border-subtle: rgba(0, 0, 0, 0.06);
+    --ui-border-strong: rgba(0, 0, 0, 0.16);
+
+    /* Accent */
+    --ui-accent: #6c5ce7;
+    --ui-accent-hover: #5a4bd6;
+    --ui-accent-glow: rgba(108, 92, 231, 0.2);
+    --ui-accent-subtle: rgba(108, 92, 231, 0.08);
+    --ui-accent-muted: rgba(108, 92, 231, 0.12);
+
+    /* Semantic */
+    --ui-danger: #e84057;
+    --ui-danger-glow: rgba(232, 64, 87, 0.15);
+    --ui-success: #22b573;
+
+    /* Text */
+    --ui-text: #1a1a2e;
+    --ui-text-muted: #5c5c7a;
+    --ui-text-subtle: #9494ab;
+
+    /* Glass surfaces */
+    --ui-glass: rgba(255, 255, 255, 0.82);
+    --ui-glass-heavy: rgba(255, 255, 255, 0.9);
+    --ui-glass-bar: rgba(255, 255, 255, 0.8);
+    --ui-backdrop: rgba(0, 0, 0, 0.25);
+
+    /* Shadows */
+    --ui-shadow: 0 1px 3px rgba(0, 0, 0, 0.08), 0 1px 2px rgba(0, 0, 0, 0.06);
+    --ui-shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.1), 0 0 1px rgba(0, 0, 0, 0.08);
+    --ui-shadow-float: 0 12px 40px rgba(0, 0, 0, 0.12), 0 0 0 1px rgba(0, 0, 0, 0.06);
+  }
+}

package/src/utils/accentColors.js

@@ -0,0 +1,85 @@
+/** Contract: contracts/packages-ui-hooks/rules.md */
+
+/**
+ * Parse a hex color string to { r, g, b } (0-255).
+ */
+function hexToRgb(hex) {
+  const h = hex.replace('#', '');
+  const full = h.length === 3
+    ? h.split('').map(c => c + c).join('')
+    : h;
+  const n = parseInt(full, 16);
+  return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };
+}
+
+/**
+ * Convert RGB to HSL. Returns { h: 0-360, s: 0-100, l: 0-100 }.
+ */
+function rgbToHsl({ r, g, b }) {
+  r /= 255; g /= 255; b /= 255;
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return { h: 0, s: 0, l: l * 100 };
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+  else if (max === g) h = ((b - r) / d + 2) / 6;
+  else h = ((r - g) / d + 4) / 6;
+  return { h: h * 360, s: s * 100, l: l * 100 };
+}
+
+/**
+ * Convert HSL back to hex string.
+ */
+function hslToHex({ h, s, l }) {
+  s /= 100; l /= 100;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => {
+    const k = (n + h / 30) % 12;
+    const color = l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
+    return Math.round(255 * color).toString(16).padStart(2, '0');
+  };
+  return `#${f(0)}${f(8)}${f(4)}`;
+}
+
+/**
+ * Derive the 5 accent CSS custom properties from a single hex color.
+ * Adjusts for dark vs light theme context.
+ *
+ * @param {string} hex - Base accent color, e.g. '#7c6cf0'
+ * @param {'dark'|'light'} mode - Current resolved theme
+ * @returns {Object} Map of CSS property name → value
+ */
+export function deriveAccentTokens(hex, mode = 'dark') {
+  const rgb = hexToRgb(hex);
+  const hsl = rgbToHsl(rgb);
+
+  // For light mode, nudge lightness down slightly for contrast on white
+  const primary = mode === 'light' && hsl.l > 45
+    ? hslToHex({ h: hsl.h, s: hsl.s, l: Math.max(hsl.l - 8, 40) })
+    : hex;
+
+  const primaryRgb = hexToRgb(primary);
+
+  // Hover: darken by ~6% lightness
+  const hoverHsl = rgbToHsl(primaryRgb);
+  const hover = hslToHex({
+    h: hoverHsl.h,
+    s: hoverHsl.s,
+    l: Math.max(hoverHsl.l - 6, 10),
+  });
+
+  const { r, g, b } = primaryRgb;
+  const glowAlpha = mode === 'light' ? 0.2 : 0.25;
+  const subtleAlpha = 0.08;
+  const mutedAlpha = mode === 'light' ? 0.12 : 0.15;
+
+  return {
+    '--ui-accent': primary,
+    '--ui-accent-hover': hover,
+    '--ui-accent-glow': `rgba(${r}, ${g}, ${b}, ${glowAlpha})`,
+    '--ui-accent-subtle': `rgba(${r}, ${g}, ${b}, ${subtleAlpha})`,
+    '--ui-accent-muted': `rgba(${r}, ${g}, ${b}, ${mutedAlpha})`,
+  };
+}

package/src/utils/viewTransition.js

@@ -0,0 +1,16 @@
+/** Contract: contracts/packages-ui-utils/rules.md */
+
+/**
+ * Start a View Transition if the API is available.
+ * Falls back to running the callback immediately on unsupported browsers.
+ *
+ * @param {function} callback - DOM mutation to animate
+ * @returns {ViewTransition|null}
+ */
+export function startViewTransition(callback) {
+  if (document.startViewTransition) {
+    return document.startViewTransition(callback);
+  }
+  callback();
+  return null;
+}