@1889ca/ui 0.5.1 → 0.6.0

package/src/effects/Particles.jsx

@@ -0,0 +1,117 @@
+/** Contract: contracts/packages-ui-components/rules.md */
+
+import { useRef, useEffect } from 'react';
+import './particles.css';
+
+/**
+ * Accent-reactive particle field — tiny dots drifting at glacial speed,
+ * tinted to the current accent color. Creates living depth in backgrounds.
+ *
+ * @param {number} count - Number of particles (default 25)
+ * @param {boolean} disabled - Disable the effect
+ */
+export default function Particles({ count = 25, disabled = false }) {
+  const canvasRef = useRef(null);
+  const particles = useRef([]);
+  const raf = useRef(null);
+
+  useEffect(() => {
+    if (disabled) return;
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    const ctx = canvas.getContext('2d');
+    let w, h;
+
+    function resize() {
+      const dpr = window.devicePixelRatio || 1;
+      w = canvas.clientWidth;
+      h = canvas.clientHeight;
+      canvas.width = w * dpr;
+      canvas.height = h * dpr;
+      ctx.scale(dpr, dpr);
+    }
+
+    function initParticles() {
+      particles.current = Array.from({ length: count }, () => ({
+        x: Math.random() * w,
+        y: Math.random() * h,
+        vx: (Math.random() - 0.5) * 0.15,
+        vy: (Math.random() - 0.5) * 0.1 - 0.05,
+        r: Math.random() * 1.5 + 0.5,
+        opacity: Math.random() * 0.4 + 0.1,
+        phase: Math.random() * Math.PI * 2,
+      }));
+    }
+
+    function getAccentColor() {
+      const style = getComputedStyle(document.documentElement);
+      return style.getPropertyValue('--ui-accent').trim() || '#7c6cf0';
+    }
+
+    function hexToRgb(hex) {
+      const n = parseInt(hex.replace('#', ''), 16);
+      return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+    }
+
+    let accentRgb = hexToRgb(getAccentColor());
+    let frameCount = 0;
+
+    function draw() {
+      ctx.clearRect(0, 0, w, h);
+
+      // Refresh accent color every ~120 frames
+      if (frameCount++ % 120 === 0) {
+        accentRgb = hexToRgb(getAccentColor());
+      }
+
+      for (const p of particles.current) {
+        p.x += p.vx;
+        p.y += p.vy;
+
+        // Gentle sine wave drift
+        p.x += Math.sin(p.phase + frameCount * 0.003) * 0.08;
+
+        // Wrap around edges
+        if (p.x < -10) p.x = w + 10;
+        if (p.x > w + 10) p.x = -10;
+        if (p.y < -10) p.y = h + 10;
+        if (p.y > h + 10) p.y = -10;
+
+        // Breathing opacity
+        const breathe = 0.5 + 0.5 * Math.sin(p.phase + frameCount * 0.008);
+        const alpha = p.opacity * (0.6 + 0.4 * breathe);
+
+        ctx.beginPath();
+        ctx.arc(p.x, p.y, p.r, 0, Math.PI * 2);
+        ctx.fillStyle = `rgba(${accentRgb[0]}, ${accentRgb[1]}, ${accentRgb[2]}, ${alpha})`;
+        ctx.fill();
+
+        // Soft glow on larger particles
+        if (p.r > 1.2) {
+          ctx.beginPath();
+          ctx.arc(p.x, p.y, p.r * 3, 0, Math.PI * 2);
+          ctx.fillStyle = `rgba(${accentRgb[0]}, ${accentRgb[1]}, ${accentRgb[2]}, ${alpha * 0.15})`;
+          ctx.fill();
+        }
+      }
+
+      raf.current = requestAnimationFrame(draw);
+    }
+
+    resize();
+    initParticles();
+    draw();
+
+    window.addEventListener('resize', () => { resize(); initParticles(); });
+
+    return () => {
+      if (raf.current) cancelAnimationFrame(raf.current);
+      window.removeEventListener('resize', resize);
+    };
+  }, [count, disabled]);
+
+  if (disabled) return null;
+
+  return <canvas ref={canvasRef} className="ui-particles" aria-hidden="true" />;
+}

package/src/effects/ambient-glow.css

@@ -0,0 +1,67 @@
+/** Contract: contracts/packages-ui-styles/rules.md */
+
+/*
+ * Ambient Light Bleed — cards emit a soft color glow from their content.
+ * Uses a blurred, scaled copy of the thumbnail behind the card.
+ *
+ * Usage: add class `ui-ambient-glow` to a card wrapper.
+ * Set --ui-glow-color as a CSS variable for solid-color glow,
+ * or the component will use a blurred image copy automatically.
+ */
+
+/* Image-based glow: the card renders a hidden blurred copy behind itself */
+.ui-ambient-glow {
+  position: relative;
+}
+
+.ui-ambient-glow-source {
+  position: absolute;
+  inset: 10%;
+  z-index: -1;
+  filter: blur(40px) saturate(1.8);
+  opacity: 0;
+  transform: scale(1.1);
+  transition: opacity 0.5s var(--ui-ease);
+  pointer-events: none;
+  border-radius: 50%;
+}
+
+.ui-ambient-glow-source img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  border-radius: inherit;
+}
+
+/* Always-on subtle glow */
+.ui-ambient-glow .ui-ambient-glow-source {
+  opacity: 0.35;
+}
+
+/* Intensify on hover */
+.ui-ambient-glow:hover .ui-ambient-glow-source {
+  opacity: 0.55;
+  filter: blur(35px) saturate(2);
+}
+
+/* Solid-color fallback (no image) */
+.ui-ambient-glow--solid {
+  position: relative;
+}
+
+.ui-ambient-glow--solid::after {
+  content: '';
+  position: absolute;
+  inset: 15%;
+  z-index: -1;
+  background: var(--ui-glow-color, var(--ui-accent));
+  filter: blur(40px);
+  opacity: 0;
+  border-radius: 50%;
+  transition: opacity 0.5s var(--ui-ease);
+  pointer-events: none;
+}
+
+.ui-ambient-glow--solid:hover::after {
+  opacity: 0.3;
+}

package/src/effects/edge-light.css

@@ -0,0 +1,69 @@
+/** Contract: contracts/packages-ui-styles/rules.md */
+
+/*
+ * Edge Light — animated gradient that travels along element borders on hover.
+ * Like light refracting through glass edges.
+ *
+ * Usage: add class `ui-edge-light` to any bordered element.
+ * Works best on glass surfaces (panels, cards, modals).
+ */
+
+@property --ui-edge-angle {
+  syntax: '<angle>';
+  initial-value: 0deg;
+  inherits: false;
+}
+
+.ui-edge-light {
+  --ui-edge-color: var(--ui-accent);
+  --ui-edge-opacity: 0;
+  position: relative;
+}
+
+/* The light beam overlay */
+.ui-edge-light::before {
+  content: '';
+  position: absolute;
+  inset: -1px;
+  border-radius: inherit;
+  padding: 1.5px;
+  background: conic-gradient(
+    from var(--ui-edge-angle),
+    transparent 0%,
+    transparent 20%,
+    color-mix(in srgb, var(--ui-edge-color) calc(var(--ui-edge-opacity) * 50%), transparent) 28%,
+    color-mix(in srgb, var(--ui-edge-color) calc(var(--ui-edge-opacity) * 100%), transparent) 35%,
+    color-mix(in srgb, var(--ui-edge-color) calc(var(--ui-edge-opacity) * 100%), transparent) 40%,
+    color-mix(in srgb, var(--ui-edge-color) calc(var(--ui-edge-opacity) * 50%), transparent) 47%,
+    transparent 55%,
+    transparent 100%
+  );
+  -webkit-mask: linear-gradient(#000, #000) content-box, linear-gradient(#000, #000);
+  -webkit-mask-composite: xor;
+  mask: linear-gradient(#000, #000) content-box, linear-gradient(#000, #000);
+  mask-composite: exclude;
+  pointer-events: none;
+  z-index: 1;
+  transition: --ui-edge-opacity 0.3s var(--ui-ease);
+}
+
+/* Animate on hover */
+.ui-edge-light:hover {
+  --ui-edge-opacity: 1;
+}
+
+.ui-edge-light:hover::before {
+  animation: ui-edge-spin 3s linear infinite;
+}
+
+@keyframes ui-edge-spin {
+  from { --ui-edge-angle: 0deg; }
+  to { --ui-edge-angle: 360deg; }
+}
+
+/* Soft glow beneath the traveling light */
+.ui-edge-light:hover {
+  box-shadow:
+    var(--ui-shadow-float),
+    0 0 20px color-mix(in srgb, var(--ui-edge-color) 10%, transparent);
+}

package/src/effects/glass-tint.css

@@ -0,0 +1,47 @@
+/** Contract: contracts/packages-ui-styles/rules.md */
+
+/*
+ * Context-Aware Glass Tinting — glass surfaces pick up color
+ * from whatever's behind them, not just blur.
+ *
+ * How it works: increases saturation in backdrop-filter and
+ * reduces background opacity, allowing more color to bleed through.
+ * A subtle hue-rotate shift adds warmth/coolness depending on
+ * the content underneath.
+ *
+ * Usage: add `ui-glass-tint` class to any glass surface.
+ * Or enable globally by setting `--ui-glass-tint: 1` on :root.
+ */
+
+.ui-glass-tint,
+:root[style*="--ui-glass-tint"] .ui-modal,
+:root[style*="--ui-glass-tint"] .ui-panel,
+:root[style*="--ui-glass-tint"] .ui-dp-panel,
+:root[style*="--ui-glass-tint"] .ui-slide-panel,
+:root[style*="--ui-glass-tint"] .ui-context-menu {
+  backdrop-filter: blur(var(--ui-glass-blur-heavy)) saturate(1.8) brightness(1.05);
+  background: var(--ui-glass-tinted, rgba(18, 18, 24, 0.6));
+}
+
+/* Light theme variant */
+[data-theme="light"] .ui-glass-tint,
+[data-theme="light"]:root[style*="--ui-glass-tint"] .ui-modal,
+[data-theme="light"]:root[style*="--ui-glass-tint"] .ui-panel,
+[data-theme="light"]:root[style*="--ui-glass-tint"] .ui-dp-panel,
+[data-theme="light"]:root[style*="--ui-glass-tint"] .ui-slide-panel,
+[data-theme="light"]:root[style*="--ui-glass-tint"] .ui-context-menu {
+  backdrop-filter: blur(var(--ui-glass-blur-heavy)) saturate(1.6) brightness(1.02);
+  background: var(--ui-glass-tinted, rgba(255, 255, 255, 0.55));
+}
+
+@media (prefers-color-scheme: light) {
+  :root:not([data-theme]) .ui-glass-tint,
+  :root:not([data-theme])[style*="--ui-glass-tint"] .ui-modal,
+  :root:not([data-theme])[style*="--ui-glass-tint"] .ui-panel,
+  :root:not([data-theme])[style*="--ui-glass-tint"] .ui-dp-panel,
+  :root:not([data-theme])[style*="--ui-glass-tint"] .ui-slide-panel,
+  :root:not([data-theme])[style*="--ui-glass-tint"] .ui-context-menu {
+    backdrop-filter: blur(var(--ui-glass-blur-heavy)) saturate(1.6) brightness(1.02);
+    background: var(--ui-glass-tinted, rgba(255, 255, 255, 0.55));
+  }
+}

package/src/effects/glow-focus.css

@@ -0,0 +1,64 @@
+/** Contract: contracts/packages-ui-styles/rules.md */
+
+/*
+ * Glassmorphic Focus Rings — keyboard focus gets a soft glowing halo
+ * that pulses once, instead of a plain browser outline.
+ *
+ * Applied globally to interactive elements.
+ * Only activates on :focus-visible (keyboard nav), not on mouse clicks.
+ */
+
+@keyframes ui-focus-pulse {
+  0%   { box-shadow: 0 0 0 2px var(--ui-accent), 0 0 8px var(--ui-accent-glow); }
+  50%  { box-shadow: 0 0 0 3px var(--ui-accent), 0 0 20px var(--ui-accent-glow); }
+  100% { box-shadow: 0 0 0 2px var(--ui-accent), 0 0 12px var(--ui-accent-glow); }
+}
+
+/* Buttons */
+.ui-btn:focus-visible {
+  outline: none;
+  animation: ui-focus-pulse 0.6s var(--ui-ease) forwards;
+}
+
+/* Inputs */
+.ui-input:focus-visible {
+  outline: none;
+  animation: ui-focus-pulse 0.6s var(--ui-ease) forwards;
+}
+
+/* Toggle */
+.ui-toggle-track:focus-visible {
+  outline: none;
+  animation: ui-focus-pulse 0.6s var(--ui-ease) forwards;
+}
+
+/* Tab buttons */
+.ui-panel-tab:focus-visible,
+.ui-tab:focus-visible {
+  outline: none;
+  border-radius: var(--ui-radius-sm);
+  animation: ui-focus-pulse 0.6s var(--ui-ease) forwards;
+}
+
+/* Cards — apply to the inner card, not the li */
+.ui-item-card-wrap:focus-visible .ui-item-card {
+  animation: ui-focus-pulse 0.6s var(--ui-ease) forwards;
+}
+
+/* Generic fallback for any focusable ui element */
+[class^="ui-"]:focus-visible:not(.ui-btn):not(.ui-input):not(.ui-toggle-track):not(.ui-panel-tab):not(.ui-tab) {
+  outline: none;
+  animation: ui-focus-pulse 0.6s var(--ui-ease) forwards;
+}
+
+/* Danger variant */
+@keyframes ui-focus-pulse-danger {
+  0%   { box-shadow: 0 0 0 2px var(--ui-danger), 0 0 8px var(--ui-danger-glow); }
+  50%  { box-shadow: 0 0 0 3px var(--ui-danger), 0 0 20px var(--ui-danger-glow); }
+  100% { box-shadow: 0 0 0 2px var(--ui-danger), 0 0 12px var(--ui-danger-glow); }
+}
+
+.ui-btn-danger:focus-visible,
+.ui-btn-danger-ghost:focus-visible {
+  animation: ui-focus-pulse-danger 0.6s var(--ui-ease) forwards;
+}

package/src/effects/haptic.css

@@ -0,0 +1,52 @@
+/** Contract: contracts/packages-ui-styles/rules.md */
+
+/*
+ * Haptic Micro-animations — buttons and toggles get a snappy
+ * scale bounce on press that feels physically tangible.
+ *
+ * Applied globally to .ui-btn and .ui-toggle-track.
+ * No opt-in needed — it replaces the flat scale(0.97) with a spring bounce.
+ */
+
+@keyframes ui-haptic-press {
+  0%   { transform: scale(1); }
+  40%  { transform: scale(0.95); }
+  70%  { transform: scale(1.02); }
+  100% { transform: scale(1); }
+}
+
+@keyframes ui-haptic-press-y {
+  0%   { transform: translateY(0) scale(1); }
+  40%  { transform: translateY(1px) scale(0.95); }
+  70%  { transform: translateY(-1px) scale(1.02); }
+  100% { transform: translateY(0) scale(1); }
+}
+
+/* Override the flat :active scale on buttons */
+.ui-btn:active:not(:disabled) {
+  animation: ui-haptic-press 0.25s var(--ui-ease) forwards;
+}
+
+.ui-btn-primary:active:not(:disabled) {
+  animation: ui-haptic-press-y 0.25s var(--ui-ease) forwards;
+}
+
+/* Toggle knob bounce on state change */
+@keyframes ui-haptic-toggle {
+  0%   { transform: translateX(var(--knob-x)) scale(1, 1); }
+  30%  { transform: translateX(var(--knob-x)) scale(1.15, 0.85); }
+  60%  { transform: translateX(var(--knob-x)) scale(0.92, 1.08); }
+  100% { transform: translateX(var(--knob-x)) scale(1, 1); }
+}
+
+.ui-toggle-track .ui-toggle-knob {
+  --knob-x: 0px;
+}
+
+.ui-toggle-track--on .ui-toggle-knob {
+  --knob-x: 16px;
+}
+
+.ui-toggle-track:active .ui-toggle-knob {
+  animation: ui-haptic-toggle 0.3s var(--ui-ease-spring) forwards;
+}

package/src/effects/particles.css

@@ -0,0 +1,10 @@
+/** Contract: contracts/packages-ui-styles/rules.md */
+
+.ui-particles {
+  position: fixed;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  z-index: 0;
+}

package/src/effects/scroll-parallax.css

@@ -0,0 +1,46 @@
+/** Contract: contracts/packages-ui-styles/rules.md */
+
+/*
+ * Scroll-Linked Parallax — aurora background layers move at
+ * different speeds as the user scrolls. Deeper color blobs
+ * move slower, creating subtle dimensional depth.
+ *
+ * Requires useScrollParallax() hook on the scroll container,
+ * which sets --ui-scroll-y CSS variable.
+ *
+ * The aurora ::before is split into two layers (via an extra element)
+ * that translate at different rates relative to scroll position.
+ */
+
+.ui-aurora--parallax {
+  --ui-scroll-y: 0;
+}
+
+/* Deep layer — moves at 30% scroll speed (slower = further back) */
+.ui-aurora--parallax::before {
+  transform: translateY(calc(var(--ui-scroll-y) * -0.03px));
+  animation: none; /* disable the drift when parallax is active */
+}
+
+/* Add the drift back as a subtle bonus */
+@media (prefers-reduced-motion: no-preference) {
+  .ui-aurora--parallax::before {
+    animation: ui-aurora-drift 25s ease-in-out infinite alternate;
+    /* Combine drift with parallax offset */
+    transform: translateY(calc(var(--ui-scroll-y) * -0.03px));
+  }
+}
+
+/* Surface layer — moves at 80% scroll speed (faster = closer) */
+.ui-parallax-surface {
+  content: '';
+  position: fixed;
+  inset: -10%;
+  pointer-events: none;
+  z-index: 0;
+  background:
+    radial-gradient(ellipse 30% 25% at 25% 30%, rgba(124, 108, 240, 0.04), transparent),
+    radial-gradient(ellipse 25% 20% at 70% 60%, rgba(56, 189, 248, 0.03), transparent);
+  transform: translateY(calc(var(--ui-scroll-y) * -0.08px));
+  transition: transform 0.05s linear;
+}

package/src/hooks/useClickOutside.js

@@ -0,0 +1,26 @@
+/** Contract: contracts/packages-ui-hooks/rules.md */
+import { useEffect } from 'react';
+
+/**
+ * Calls handler when a click lands outside the ref element, or Escape is pressed.
+ * @param {RefObject} ref
+ * @param {function} handler
+ * @param {boolean} active - Only listen when true (default: true)
+ */
+export default function useClickOutside(ref, handler, active = true) {
+  useEffect(() => {
+    if (!active) return;
+    function onMouseDown(e) {
+      if (ref.current && !ref.current.contains(e.target)) handler();
+    }
+    function onKey(e) {
+      if (e.key === 'Escape') handler();
+    }
+    document.addEventListener('mousedown', onMouseDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onMouseDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [ref, handler, active]);
+}

package/src/hooks/useLocalStorage.js

@@ -0,0 +1,25 @@
+/** Contract: contracts/packages-ui-hooks/rules.md */
+import { useState, useEffect } from 'react';
+
+/**
+ * useState backed by localStorage.
+ * @param {string} key - localStorage key
+ * @param {*} initialValue - Fallback if nothing stored
+ * @returns {[*, function]} [value, setValue]
+ */
+export default function useLocalStorage(key, initialValue) {
+  const [value, setValue] = useState(() => {
+    try {
+      const stored = localStorage.getItem(key);
+      return stored !== null ? JSON.parse(stored) : initialValue;
+    } catch {
+      return initialValue;
+    }
+  });
+
+  useEffect(() => {
+    try { localStorage.setItem(key, JSON.stringify(value)); } catch {}
+  }, [key, value]);
+
+  return [value, setValue];
+}

package/src/hooks/useMagnet.js

@@ -0,0 +1,60 @@
+/** Contract: contracts/packages-ui-hooks/rules.md */
+
+import { useRef, useCallback, useEffect } from 'react';
+
+/**
+ * Magnetic cursor attraction — element subtly gravitates toward the cursor on approach.
+ *
+ * @param {object} options
+ * @param {number} options.strength - Pull strength in pixels (default 6)
+ * @param {number} options.radius - Attraction radius in pixels (default 80)
+ * @param {boolean} options.disabled - Disable the effect
+ * @returns {{ ref, handlers: { onMouseMove, onMouseLeave } }}
+ */
+export default function useMagnet({ strength = 3, radius = 60, disabled = false } = {}) {
+  const ref = useRef(null);
+  const raf = useRef(null);
+
+  const onMouseMove = useCallback((e) => {
+    if (disabled || !ref.current) return;
+
+    const el = ref.current;
+    const rect = el.getBoundingClientRect();
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const dx = e.clientX - cx;
+    const dy = e.clientY - cy;
+    const dist = Math.sqrt(dx * dx + dy * dy);
+
+    if (dist > radius) {
+      if (raf.current) cancelAnimationFrame(raf.current);
+      raf.current = requestAnimationFrame(() => {
+        el.style.transform = '';
+      });
+      return;
+    }
+
+    const pull = (1 - dist / radius) * strength;
+    const tx = (dx / dist) * pull || 0;
+    const ty = (dy / dist) * pull || 0;
+
+    if (raf.current) cancelAnimationFrame(raf.current);
+    raf.current = requestAnimationFrame(() => {
+      el.style.transform = `translate(${tx.toFixed(2)}px, ${ty.toFixed(2)}px)`;
+    });
+  }, [strength, radius, disabled]);
+
+  const onMouseLeave = useCallback(() => {
+    if (!ref.current) return;
+    if (raf.current) cancelAnimationFrame(raf.current);
+    ref.current.style.transform = '';
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      if (raf.current) cancelAnimationFrame(raf.current);
+    };
+  }, []);
+
+  return { ref, handlers: { onMouseMove, onMouseLeave } };
+}

package/src/hooks/useMediaQuery.js

@@ -0,0 +1,24 @@
+/** Contract: contracts/packages-ui-hooks/rules.md */
+import { useState, useEffect } from 'react';
+
+/**
+ * Returns true when the given CSS media query matches.
+ * @param {string} query - e.g. '(min-width: 768px)'
+ * @returns {boolean}
+ */
+export default function useMediaQuery(query) {
+  const [matches, setMatches] = useState(() => {
+    if (typeof window === 'undefined') return false;
+    return window.matchMedia(query).matches;
+  });
+
+  useEffect(() => {
+    const mql = window.matchMedia(query);
+    const onChange = (e) => setMatches(e.matches);
+    mql.addEventListener('change', onChange);
+    setMatches(mql.matches);
+    return () => mql.removeEventListener('change', onChange);
+  }, [query]);
+
+  return matches;
+}

package/src/hooks/useScrollParallax.js

@@ -0,0 +1,39 @@
+/** Contract: contracts/packages-ui-hooks/rules.md */
+
+import { useEffect, useRef } from 'react';
+
+/**
+ * Sets --ui-scroll-y CSS variable on the target element based on
+ * window scroll position, enabling CSS-driven parallax effects.
+ *
+ * @param {boolean} disabled - disable the effect
+ * @returns {{ ref }} - attach to the aurora container element
+ */
+export default function useScrollParallax(disabled = false) {
+  const ref = useRef(null);
+  const raf = useRef(null);
+
+  useEffect(() => {
+    if (disabled || !ref.current) return;
+
+    const el = ref.current;
+
+    function onScroll() {
+      if (raf.current) return;
+      raf.current = requestAnimationFrame(() => {
+        el.style.setProperty('--ui-scroll-y', window.scrollY);
+        raf.current = null;
+      });
+    }
+
+    window.addEventListener('scroll', onScroll, { passive: true });
+    onScroll();
+
+    return () => {
+      window.removeEventListener('scroll', onScroll);
+      if (raf.current) cancelAnimationFrame(raf.current);
+    };
+  }, [disabled]);
+
+  return { ref };
+}