@a4ui/core 0.11.1 → 0.13.0

package/src/layout/sceneEffects.ts

@@ -0,0 +1,49 @@
+// Shared, theme-agnostic pointer effects used by every backdrop (SpaceBackground
+// and ThemedScenery) so the whole UI feels alive on every theme, not just space:
+//   • cursor glow — the `#cursorGlow` element inside `root` follows the pointer
+//   • magnetic buttons — `.magnetic` elements lean toward the cursor
+//   • card edge-glow — `.glow-edge` cards track the pointer via `--mx`/`--my`
+// Returns a cleanup that unbinds every listener. Call only when motion is allowed.
+
+export function bindPointerFx(root: HTMLElement): () => void {
+  const glow = root.querySelector<HTMLElement>('#cursorGlow')
+
+  const onMove = (e: PointerEvent): void => {
+    if (glow) {
+      glow.style.opacity = '1'
+      glow.style.left = `${e.clientX}px`
+      glow.style.top = `${e.clientY}px`
+    }
+    const el = e.target as Element | null
+    const magnetic = el?.closest?.('.magnetic') as HTMLElement | null
+    if (magnetic) {
+      const r = magnetic.getBoundingClientRect()
+      const mx = (e.clientX - (r.left + r.width / 2)) / r.width
+      const my = (e.clientY - (r.top + r.height / 2)) / r.height
+      magnetic.style.transform = `translate(${(mx * 7).toFixed(1)}px, ${(my * 7).toFixed(1)}px)`
+    }
+    const card = el?.closest?.('.glow-edge') as HTMLElement | null
+    if (card) {
+      const r = card.getBoundingClientRect()
+      card.style.setProperty('--mx', `${e.clientX - r.left}px`)
+      card.style.setProperty('--my', `${e.clientY - r.top}px`)
+    }
+  }
+  const onLeave = (): void => {
+    if (glow) glow.style.opacity = '0'
+  }
+  const onOut = (e: PointerEvent): void => {
+    const magnetic = (e.target as Element | null)?.closest?.('.magnetic') as HTMLElement | null
+    if (magnetic) magnetic.style.transform = ''
+  }
+
+  document.addEventListener('pointermove', onMove as EventListener)
+  window.addEventListener('pointerleave', onLeave)
+  document.addEventListener('pointerout', onOut as EventListener)
+
+  return () => {
+    document.removeEventListener('pointermove', onMove as EventListener)
+    window.removeEventListener('pointerleave', onLeave)
+    document.removeEventListener('pointerout', onOut as EventListener)
+  }
+}

package/src/lib/cn.ts

@@ -0,0 +1,17 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/**
+ * Merge Tailwind class lists, resolving conflicting utilities left-to-right
+ * (via `tailwind-merge`) after flattening conditionals/arrays/objects (via `clsx`).
+ * Use this instead of template-string concatenation whenever a component
+ * accepts a `class` override that should win over its own defaults.
+ *
+ * @example
+ * ```ts
+ * cn('px-2 py-1 text-sm', isActive && 'bg-primary text-primary-foreground', props.class)
+ * ```
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs))
+}

package/src/lib/effects.ts

@@ -0,0 +1,71 @@
+// Single "visual effects" switch (merges the old motion + axe-preview toggles).
+// ON by default = the full space-glass experience (translucent glass, starfield,
+// animations). Turning it OFF adds `html.calm`, which makes surfaces opaque,
+// hides the starfield and disables motion — a calm / high-contrast / low-power
+// mode. `?calm=1` forces it off (used by contrast checks).
+import { createSignal } from 'solid-js'
+
+const STORAGE_KEY = 'a4ui-effects'
+
+function lsSafe(): Storage | null {
+  try {
+    return window.localStorage
+  } catch {
+    return null
+  }
+}
+
+function initial(): boolean {
+  try {
+    if (new URLSearchParams(window.location.search).get('calm') === '1') return false
+  } catch {
+    /* ignore */
+  }
+  const raw = lsSafe()?.getItem(STORAGE_KEY)
+  return raw === null ? true : raw === '1' // default ON
+}
+
+function apply(on: boolean): void {
+  if (typeof document === 'undefined') return // SSR-safe: no-op on the server
+  document.documentElement.classList.toggle('calm', !on)
+}
+
+const start = initial()
+apply(start)
+const [effectsOn, setSignal] = createSignal(start)
+
+/**
+ * Reactive accessor for the "visual effects" switch: `true` = full
+ * space-glass experience (glass, starfield, animation), `false` = calm mode.
+ * Backing signal shared module-wide, so every consumer (e.g.
+ * {@link EffectsToggle}) reads the same source of truth.
+ *
+ * @example
+ * ```ts
+ * const effectsOn = useEffects()
+ * console.log(effectsOn()) // true | false
+ * ```
+ */
+export function useEffects() {
+  return effectsOn
+}
+
+/** True when visual effects are OFF (calm mode). Read by motion + charts. */
+export function isCalm(): boolean {
+  return !effectsOn()
+}
+
+/**
+ * Persist and apply the visual-effects switch: toggles `html.calm` (opaque
+ * surfaces, no starfield, no motion when off) and updates {@link useEffects}.
+ *
+ * @example
+ * ```ts
+ * setEffects(false) // enter calm mode
+ * ```
+ */
+export function setEffects(on: boolean): void {
+  lsSafe()?.setItem(STORAGE_KEY, on ? '1' : '0')
+  apply(on)
+  setSignal(on)
+}

package/src/lib/flyToCart.ts

@@ -0,0 +1,103 @@
+// The classic "add to basket" fly animation: a ghost of the product image
+// arcs from a source element (button/card) to a target element (the cart
+// icon), then the target bumps to acknowledge the drop. Pure JS/DOM (a
+// throwaway ghost node driven by Motion's `animate`), so it works from any
+// click handler without touching component state. Reduced motion skips the
+// flight entirely but still fires `onArrive` so cart counts stay correct.
+import { animate, motionReduced } from './motion'
+
+export interface FlyToCartOptions {
+  /** Image URL to fly; if omitted, the source element is cloned. */
+  image?: string
+  /** Flight duration in seconds. @default 0.6 */
+  duration?: number
+  /** Called when the flight finishes (e.g. to increment the cart count). */
+  onArrive?: () => void
+}
+
+/**
+ * Animate a small ghost from `source` to `target` (e.g. product → cart icon),
+ * then a bump on the target. No-op under reduced motion (still calls onArrive).
+ *
+ * @example
+ * ```ts
+ * function onAddToCart(e: MouseEvent) {
+ *   const button = e.currentTarget as HTMLElement
+ *   const cartIcon = document.getElementById('cart-icon')!
+ *   flyToCart(button, cartIcon, {
+ *     image: product.thumbnailUrl,
+ *     onArrive: () => setCartCount((n) => n + 1),
+ *   })
+ * }
+ * ```
+ */
+export function flyToCart(source: Element, target: Element, opts?: FlyToCartOptions): void {
+  if (typeof document === 'undefined') {
+    opts?.onArrive?.()
+    return
+  }
+
+  if (motionReduced()) {
+    opts?.onArrive?.()
+    return
+  }
+
+  try {
+    const sourceRect = source.getBoundingClientRect()
+    const targetRect = target.getBoundingClientRect()
+
+    const size = 48
+    const sourceCenterX = sourceRect.left + sourceRect.width / 2
+    const sourceCenterY = sourceRect.top + sourceRect.height / 2
+    const targetCenterX = targetRect.left + targetRect.width / 2
+    const targetCenterY = targetRect.top + targetRect.height / 2
+
+    const dx = targetCenterX - sourceCenterX
+    const dy = targetCenterY - sourceCenterY
+
+    const ghost: HTMLElement = opts?.image ? document.createElement('img') : document.createElement('div')
+    if (opts?.image) (ghost as HTMLImageElement).src = opts.image
+
+    ghost.style.position = 'fixed'
+    ghost.style.left = `${sourceCenterX - size / 2}px`
+    ghost.style.top = `${sourceCenterY - size / 2}px`
+    ghost.style.width = `${size}px`
+    ghost.style.height = `${size}px`
+    ghost.style.borderRadius = '9999px'
+    ghost.style.objectFit = 'cover'
+    ghost.style.pointerEvents = 'none'
+    ghost.style.zIndex = '9999'
+    if (!opts?.image) ghost.style.background = 'var(--a4-primary, #6366f1)'
+
+    document.body.appendChild(ghost)
+
+    const duration = opts?.duration ?? 0.6
+
+    const controls = animate(
+      ghost,
+      { x: [0, dx], y: [0, dy], scale: [1, 0.3], opacity: [1, 0.5] },
+      { duration, ease: 'easeInOut' },
+    )
+
+    controls.finished
+      .catch(() => {
+        /* stopped early — still clean up and settle below */
+      })
+      .then(() => {
+        ghost.remove()
+        opts?.onArrive?.()
+        try {
+          animate(target, { scale: [1, 1.25, 1] }, { duration: 0.3, ease: 'easeOut' })
+        } catch {
+          /* target no longer animatable — ignore */
+        }
+      })
+      .catch(() => {
+        /* onArrive threw — nothing more we can do here */
+      })
+  } catch {
+    // Rect reads / DOM writes can fail (detached nodes, hostile environments) —
+    // bail gracefully rather than throwing out of an event handler.
+    opts?.onArrive?.()
+  }
+}

package/src/lib/media.ts

@@ -0,0 +1,27 @@
+// Reactive CSS media-query matcher. Used to render EITHER the desktop table or
+// the mobile cards (not both) so a virtualized long list keeps only one
+// structure in the DOM.
+import { createSignal, onCleanup } from 'solid-js'
+
+/**
+ * Reactive `matchMedia` matcher: returns a signal accessor that updates when
+ * the query's match state changes, cleaning up its listener on unmount.
+ * Handy for rendering either a desktop or mobile layout instead of hiding one
+ * with CSS.
+ *
+ * @example
+ * ```tsx
+ * const isDesktop = useMediaQuery('(min-width: 768px)')
+ * return isDesktop() ? <DesktopTable /> : <MobileCards />
+ * ```
+ */
+export function useMediaQuery(query: string): () => boolean {
+  const mql = typeof window !== 'undefined' ? window.matchMedia(query) : null
+  const [matches, setMatches] = createSignal(mql ? mql.matches : false)
+  if (mql) {
+    const on = (e: MediaQueryListEvent) => setMatches(e.matches)
+    mql.addEventListener('change', on)
+    onCleanup(() => mql.removeEventListener('change', on))
+  }
+  return matches
+}

package/src/lib/motion.ts

@@ -0,0 +1,191 @@
+// Shared motion helpers. CSS-driven transitions (Tailwind classes, Kobalte's
+// data-expanded/data-closed keyframes) get their reduced-motion guard for free
+// from the global `@media (prefers-reduced-motion: reduce)` block in styles.css —
+// this module is for the JS-driven paths (Motion's `animate`, the KPI count-up)
+// that can't rely on a CSS media query alone. JS animation uses **Motion**
+// (motion.dev, the `motion` package) — `animate`/`scroll`/`inView`/`stagger` are
+// re-exported below so components (and consumers) share one motion engine.
+import { animate, inView, scroll, stagger, spring } from 'motion'
+import { createEffect, createSignal, onCleanup, untrack, type Accessor } from 'solid-js'
+
+import { isCalm } from './effects'
+
+// Re-export Motion's imperative API so the whole library shares one engine and
+// consumers can reach it without a second dependency.
+export { animate, inView, scroll, stagger, spring }
+
+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)'
+
+/**
+ * Snapshot of the user's reduced-motion preference at call time. Not
+ * reactive to preference changes mid-session (matches theme.ts's one-shot
+ * environment read) — reload picks up changes.
+ *
+ * @example
+ * ```ts
+ * if (prefersReducedMotion()) skipEntranceAnimation()
+ * ```
+ */
+export function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false
+  return window.matchMedia(REDUCED_MOTION_QUERY).matches
+}
+
+// --- "force full motion" override (the ⚡ MotionToggle) --------------------
+// Persisted opt-out from the OS "reduce motion" preference; toggling it also
+// adds/removes `.force-motion` on <html>, which the reduced-motion @media block
+// in styles.css keys off to re-enable CSS animation.
+const FORCE_MOTION_KEY = 'a4ui-motion-forced'
+
+function motionStore(): Storage | null {
+  try {
+    return window.localStorage
+  } catch {
+    return null
+  }
+}
+
+const [motionForced, setMotionForcedSignal] = createSignal(motionStore()?.getItem(FORCE_MOTION_KEY) === '1')
+
+if (typeof document !== 'undefined') {
+  document.documentElement.classList.toggle('force-motion', untrack(motionForced))
+}
+
+/**
+ * Reactive accessor for the persisted "force full motion" opt-out (the ⚡
+ * MotionToggle) — `true` re-enables animation even when the OS requests
+ * reduced motion.
+ *
+ * @example
+ * ```ts
+ * const forced = useMotionForced()
+ * console.log(forced()) // true | false
+ * ```
+ */
+export function useMotionForced(): Accessor<boolean> {
+  return motionForced
+}
+
+/**
+ * Persist the "force full motion" choice, toggle `html.force-motion`
+ * (which the reduced-motion `@media` block in styles.css keys off), and
+ * update {@link useMotionForced}.
+ *
+ * @example
+ * ```ts
+ * setMotionForced(true) // opt back into full motion despite OS setting
+ * ```
+ */
+export function setMotionForced(on: boolean): void {
+  motionStore()?.setItem(FORCE_MOTION_KEY, on ? '1' : '0')
+  if (typeof document !== 'undefined') document.documentElement.classList.toggle('force-motion', on)
+  setMotionForcedSignal(on)
+}
+
+/**
+ * Effective reduced-motion: reduced when calm mode (visual effects OFF) is on,
+ * or when the OS asks for reduced motion and the user hasn't forced it. JS-driven
+ * motion (SpaceBackground, count-up) gates on this rather than
+ * prefersReducedMotion() directly.
+ *
+ * @example
+ * ```ts
+ * if (!motionReduced()) startParallaxLoop()
+ * ```
+ */
+export function motionReduced(): boolean {
+  return isCalm() || (prefersReducedMotion() && !motionForced())
+}
+
+/**
+ * Tweens a numeric signal toward `target()` with Motion's `animate` (ease-out),
+ * for KPI count-ups. Jumps straight to the target under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * const animated = createCountUp(() => props.value, 800)
+ * return <span>{Math.round(animated())}</span>
+ * ```
+ */
+export function createCountUp(target: Accessor<number>, durationMs = 600): Accessor<number> {
+  const [value, setValue] = createSignal(0)
+  let controls: { stop: () => void } | undefined
+
+  createEffect(() => {
+    const to = target()
+    controls?.stop()
+
+    if (motionReduced()) {
+      setValue(to)
+      return
+    }
+
+    const from = untrack(value)
+    if (from === to) return
+
+    controls = animate(from, to, {
+      duration: durationMs / 1000,
+      ease: 'easeOut',
+      onUpdate: (latest: number) => setValue(latest),
+    })
+  })
+
+  onCleanup(() => controls?.stop())
+
+  return value
+}
+
+/**
+ * Fade + slide an element in on mount with Motion (ease-out), respecting
+ * reduced motion (a no-op then). Call it from a ref/onMount; use `delay` to
+ * stagger a row.
+ *
+ * @example
+ * ```tsx
+ * let el!: HTMLDivElement
+ * onMount(() => animateIn(el, { delay: 0.1 }))
+ * return <div ref={el}>…</div>
+ * ```
+ */
+export function animateIn(el: Element, opts: { y?: number; duration?: number; delay?: number } = {}): void {
+  if (motionReduced()) return
+  animate(
+    el,
+    { opacity: [0, 1], y: [opts.y ?? 8, 0] },
+    { duration: opts.duration ?? 0.32, delay: opts.delay ?? 0, ease: 'easeOut' },
+  )
+}
+
+/**
+ * Reveal an element the first time it scrolls into view (fade + slide up), using
+ * Motion's `inView`. Reveals once (won't re-flash on re-entry) and is a no-op
+ * under reduced motion (the element stays visible). Returns a stop function.
+ *
+ * @example
+ * ```tsx
+ * let el!: HTMLDivElement
+ * onMount(() => revealOnScroll(el, { amount: 0.3 }))
+ * return <section ref={el}>…</section>
+ * ```
+ */
+export function revealOnScroll(
+  el: Element,
+  opts: { y?: number; duration?: number; amount?: number } = {},
+): () => void {
+  if (motionReduced()) return () => {}
+  ;(el as HTMLElement).style.opacity = '0'
+  let done = false
+  return inView(
+    el,
+    () => {
+      if (done) return
+      done = true
+      animate(
+        el,
+        { opacity: [0, 1], y: [opts.y ?? 16, 0] },
+        { duration: opts.duration ?? 0.5, ease: 'easeOut' },
+      )
+    },
+    { amount: opts.amount ?? 0.2 },
+  )
+}

package/src/lib/theme.ts

@@ -0,0 +1,113 @@
+// Light/dark theme handling. The dark "night" palette is the default (see
+// styles.css / tokens.css); choosing light sets `data-theme="light"` on the
+// root <html> element. The choice is persisted in localStorage so state
+// survives reloads.
+import { createSignal } from 'solid-js'
+
+const STORAGE_KEY = 'a4ui-theme'
+
+/** The two supported color schemes. `'dark'` (the "night" palette) is the default. */
+export type Theme = 'dark' | 'light'
+
+function isTheme(value: string | null): value is Theme {
+  return value === 'dark' || value === 'light'
+}
+
+function localStorageSafe(): Storage | null {
+  try {
+    return window.localStorage
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Read the persisted theme choice from `localStorage`, defaulting to `'dark'`
+ * when nothing is stored (or storage is unavailable).
+ *
+ * @example
+ * ```ts
+ * const initial = storedTheme() // 'dark' | 'light'
+ * ```
+ */
+export function storedTheme(): Theme {
+  const raw = localStorageSafe()?.getItem(STORAGE_KEY) ?? null
+  return isTheme(raw) ? raw : 'dark'
+}
+
+/**
+ * Reflect a theme onto `<html data-theme>` without touching storage or the
+ * shared signal. Dark is the default (no attribute); light sets
+ * `data-theme="light"`. Prefer {@link setTheme} unless you specifically need
+ * to apply without persisting.
+ *
+ * @example
+ * ```ts
+ * applyTheme('light')
+ * ```
+ */
+export function applyTheme(theme: Theme): void {
+  if (typeof document === 'undefined') return // SSR-safe: no-op on the server
+  const root = document.documentElement
+  if (theme === 'light') {
+    root.setAttribute('data-theme', 'light')
+  } else {
+    root.removeAttribute('data-theme')
+  }
+}
+
+/**
+ * Persist a theme choice to `localStorage` and apply it to `<html>`. Does not
+ * update the shared `useTheme()` signal directly — {@link toggleTheme} does
+ * that after calling this.
+ *
+ * @example
+ * ```ts
+ * setTheme('light')
+ * ```
+ */
+export function setTheme(theme: Theme): void {
+  localStorageSafe()?.setItem(STORAGE_KEY, theme)
+  applyTheme(theme)
+}
+
+/**
+ * The opposite of the given theme. Pure helper (no signal/storage side effects)
+ * used by {@link toggleTheme}.
+ *
+ * @example
+ * ```ts
+ * toggled('dark') // 'light'
+ * ```
+ */
+export function toggled(theme: Theme): Theme {
+  return theme === 'dark' ? 'light' : 'dark'
+}
+
+// Module-level signal so every consumer (ThemeToggle, anything reading the
+// current theme) shares one source of truth, applied once at import time.
+const initial = storedTheme()
+applyTheme(initial)
+const [theme, setThemeSignal] = createSignal<Theme>(initial)
+
+/**
+ * Reactive accessor for the current theme, shared module-wide so every
+ * consumer (e.g. {@link ThemeToggle}, `SpaceBackground`) reads the same
+ * source of truth.
+ *
+ * @example
+ * ```ts
+ * const theme = useTheme()
+ * console.log(theme()) // 'dark' | 'light'
+ * ```
+ */
+export function useTheme() {
+  return theme
+}
+
+/** Flip the current theme (dark↔light), persisting and applying the new value. */
+export function toggleTheme(): void {
+  const next = toggled(theme())
+  setTheme(next)
+  setThemeSignal(next)
+}

package/src/lib/virtual.ts

@@ -0,0 +1,33 @@
+// Helpers for @tanstack/solid-virtual lists.
+import { onMount, type Accessor } from 'solid-js'
+
+/**
+ * Works around a `@tanstack/solid-virtual` bug where the virtualizer measures
+ * a 0×0 viewport: it attaches its `ResizeObserver` during the render pass
+ * (when `getScrollElement` first returns the scroll container), before the
+ * container has been laid out, so it caches a 0×0 size and never renders any
+ * rows. Once layout settles, this detaches+reattaches the scroll element so
+ * the observer re-measures the real height. Call it right after wiring up
+ * the virtualizer, passing the scroll-element signal's getter and setter.
+ *
+ * @example
+ * ```ts
+ * const [scrollEl, setScrollEl] = createSignal<HTMLElement>()
+ * const virtualizer = createVirtualizer({ getScrollElement: scrollEl, ... })
+ * remeasureAfterLayout(scrollEl, setScrollEl)
+ * ```
+ */
+export function remeasureAfterLayout(
+  scrollEl: Accessor<HTMLElement | undefined>,
+  setScrollEl: (v: HTMLElement | undefined) => void,
+): void {
+  onMount(() => {
+    requestAnimationFrame(() => {
+      const el = scrollEl()
+      if (el) {
+        setScrollEl(undefined)
+        setScrollEl(el)
+      }
+    })
+  })
+}