@a4ui/core 0.12.0 → 0.13.0

package/src/ui/HoldToConfirm.tsx

@@ -0,0 +1,141 @@
+// A destructive/important-action button that requires a press-and-HOLD (not a
+// single click) to confirm — the fill sweeping across the button doubles as a
+// "how much longer" progress affordance, guarding against accidental taps.
+import type { JSX } from 'solid-js'
+import { createSignal, onCleanup } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+export interface HoldToConfirmProps {
+  onConfirm: () => void
+  /** Button label. @default 'Hold to confirm' */
+  label?: string
+  /** How long to hold, in ms. @default 1200 */
+  holdMs?: number
+  disabled?: boolean
+  class?: string
+}
+
+/**
+ * Press-and-hold button for destructive/important actions: `onConfirm` only
+ * fires once the pointer (or Space/Enter) has been held down for `holdMs`.
+ * A fill layer sweeps left-to-right as visual progress; releasing early stops
+ * and resets it. Under reduced motion the hold is still required (gated by a
+ * plain timer instead of the tracked animation), but the fill jumps instead
+ * of sweeping and the success flourish is skipped.
+ *
+ * @example
+ * ```tsx
+ * <HoldToConfirm label="Hold to delete" holdMs={1500} onConfirm={() => deleteItem(id)} />
+ * ```
+ */
+export function HoldToConfirm(props: HoldToConfirmProps): JSX.Element {
+  const [holding, setHolding] = createSignal(false)
+
+  let buttonEl: HTMLButtonElement | undefined
+  let fillEl: HTMLSpanElement | undefined
+  let controls: ReturnType<typeof animate> | undefined
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let active = false
+
+  const holdMs = () => props.holdMs ?? 1200
+
+  const resetFill = (durationSec: number) => {
+    if (!fillEl) return
+    if (motionReduced()) {
+      fillEl.style.transform = 'scaleX(0)'
+      return
+    }
+    animate(fillEl, { scaleX: 0 }, { duration: durationSec, ease: 'easeOut' })
+  }
+
+  const succeed = () => {
+    active = false
+    setHolding(false)
+    props.onConfirm()
+    if (!motionReduced() && buttonEl) {
+      animate(buttonEl, { scale: [1, 1.04, 1] }, { duration: 0.3, ease: 'easeOut' })
+    }
+    resetFill(0.2)
+  }
+
+  const cancel = () => {
+    if (!active) return
+    active = false
+    setHolding(false)
+    controls?.stop()
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      timer = undefined
+    }
+    resetFill(0.15)
+  }
+
+  const start = (event: PointerEvent | KeyboardEvent) => {
+    if (props.disabled || active) return
+    event.preventDefault()
+    active = true
+    setHolding(true)
+
+    if (motionReduced()) {
+      if (fillEl) fillEl.style.transform = 'scaleX(1)'
+      timer = setTimeout(() => {
+        if (active) succeed()
+      }, holdMs())
+      return
+    }
+
+    if (!fillEl) return
+    controls = animate(fillEl, { scaleX: [0, 1] }, { duration: holdMs() / 1000, ease: 'linear' })
+    controls.finished
+      // eslint-disable-next-line solid/reactivity -- promise callback, not a tracked scope; setHolding runs fine here
+      .then(() => {
+        if (active) succeed()
+      })
+      .catch(() => {})
+  }
+
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (event.key !== ' ' && event.key !== 'Enter') return
+    if (event.repeat) return
+    start(event)
+  }
+
+  const onKeyUp = (event: KeyboardEvent) => {
+    if (event.key !== ' ' && event.key !== 'Enter') return
+    cancel()
+  }
+
+  onCleanup(() => {
+    controls?.stop()
+    if (timer !== undefined) clearTimeout(timer)
+  })
+
+  return (
+    <button
+      ref={buttonEl}
+      type="button"
+      disabled={props.disabled}
+      aria-label={props.label ?? 'Hold to confirm'}
+      aria-busy={holding()}
+      class={cn(
+        'relative overflow-hidden rounded-lg border border-border bg-card px-4 py-2 text-sm font-medium disabled:pointer-events-none disabled:opacity-50',
+        props.class,
+      )}
+      onPointerDown={start}
+      onPointerUp={cancel}
+      onPointerLeave={cancel}
+      onKeyDown={onKeyDown}
+      onKeyUp={onKeyUp}
+    >
+      <span
+        aria-hidden="true"
+        ref={fillEl}
+        class="absolute inset-0 origin-left bg-primary/25"
+        style={{ transform: 'scaleX(0)' }}
+      />
+      <span class="relative z-10">{props.label ?? 'Hold to confirm'}</span>
+    </button>
+  )
+}

package/src/ui/LoadingDots.tsx

@@ -0,0 +1,75 @@
+// Three dots bouncing in a staggered wave — a lightweight indeterminate
+// loading indicator. The bounce is pure CSS (keyframes injected once into the
+// document head) so there's no per-frame JS cost; reduced motion swaps the
+// bounce for a gentle opacity pulse.
+import type { JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface LoadingDotsProps {
+  /** Dot diameter in px. @default 8 */
+  size?: number
+  /** Optional accessible label. @default 'Loading' */
+  label?: string
+  class?: string
+}
+
+const STYLE_ID = 'a4ui-loading-dots-style'
+
+function ensureStyleInjected(): void {
+  if (typeof document === 'undefined' || document.getElementById(STYLE_ID)) return
+  const style = document.createElement('style')
+  style.id = STYLE_ID
+  style.textContent = `
+@keyframes a4-dot-bounce {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-60%); }
+}
+@keyframes a4-dot-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.35; }
+}
+`
+  document.head.appendChild(style)
+}
+
+/**
+ * Three dots bouncing in a staggered wave — an inline, indeterminate loading
+ * indicator. Dots use `bg-current`, so color/size follow the ancestor's text
+ * color; diameter is set via `size`. Falls back to a gentle opacity pulse
+ * under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <LoadingDots label="Loading results" class="text-primary" />
+ * ```
+ */
+export function LoadingDots(props: LoadingDotsProps): JSX.Element {
+  ensureStyleInjected()
+
+  const size = () => props.size ?? 8
+  const animationName = () => (motionReduced() ? 'a4-dot-pulse' : 'a4-dot-bounce')
+
+  const dotStyle = (delayMs: number): JSX.CSSProperties => ({
+    width: `${size()}px`,
+    height: `${size()}px`,
+    'animation-name': animationName(),
+    'animation-duration': '0.6s',
+    'animation-iteration-count': 'infinite',
+    'animation-timing-function': 'ease-in-out',
+    'animation-delay': `${delayMs}ms`,
+  })
+
+  return (
+    <span
+      role="status"
+      aria-label={props.label ?? 'Loading'}
+      class={cn('inline-flex items-center gap-1 text-current', props.class)}
+    >
+      <span class="rounded-full bg-current" style={dotStyle(0)} />
+      <span class="rounded-full bg-current" style={dotStyle(120)} />
+      <span class="rounded-full bg-current" style={dotStyle(240)} />
+    </span>
+  )
+}

package/src/ui/MultiStateBadge.tsx

@@ -0,0 +1,93 @@
+// A status pill that smoothly morphs between idle/loading/success/error: the
+// background/text color tweens via CSS `transition-colors` while the icon and
+// label cross-fade, and each state change gets a spring "pop" via Motion
+// (motion.dev's "multi-state badge" pattern) — skipped under reduced motion.
+import { createEffect, on, Switch, Match, type JSX } from 'solid-js'
+import { Loader2, Check, X } from 'lucide-solid'
+
+import { cn } from '../lib/cn'
+import { motionReduced, animate } from '../lib/motion'
+
+/** The lifecycle state a {@link MultiStateBadge} can be in. */
+export type BadgeState = 'idle' | 'loading' | 'success' | 'error'
+
+export interface MultiStateBadgeProps {
+  /** Current lifecycle state; drives color, icon, and label. */
+  state: BadgeState
+  /** Override the per-state text. Defaults: idle→'Ready', loading→'Working…', success→'Done', error→'Failed'. */
+  labels?: Partial<Record<BadgeState, string>>
+  class?: string
+}
+
+const DEFAULT_LABELS: Record<BadgeState, string> = {
+  idle: 'Ready',
+  loading: 'Working…',
+  success: 'Done',
+  error: 'Failed',
+}
+
+const STATE_CLASSES: Record<BadgeState, string> = {
+  idle: 'bg-muted text-muted-foreground',
+  loading: 'bg-primary/15 text-primary',
+  success: 'bg-green-500/15 text-green-600',
+  error: 'bg-destructive/15 text-destructive',
+}
+
+/**
+ * Status badge that animates between `idle` → `loading` → `success` → `error`,
+ * morphing its color and swapping its icon/label on each transition. Colors
+ * tween via a CSS `transition-colors` class; the pill also gets a spring
+ * "pop" and the icon/label cross-fade via Motion's `animate`, both skipped
+ * when {@link motionReduced} is true.
+ *
+ * @example
+ * ```tsx
+ * <MultiStateBadge state={saveState()} labels={{ error: 'Save failed' }} />
+ * ```
+ */
+export function MultiStateBadge(props: MultiStateBadgeProps): JSX.Element {
+  let rootEl: HTMLSpanElement | undefined
+  let contentEl: HTMLSpanElement | undefined
+
+  const label = () => props.labels?.[props.state] ?? DEFAULT_LABELS[props.state]
+
+  createEffect(
+    on(
+      () => props.state,
+      () => {
+        if (motionReduced()) return
+        if (rootEl) animate(rootEl, { scale: [0.9, 1] }, { type: 'spring', stiffness: 500, damping: 20 })
+        if (contentEl) animate(contentEl, { opacity: [0, 1] }, { duration: 0.2, ease: 'easeOut' })
+      },
+      { defer: true },
+    ),
+  )
+
+  return (
+    <span
+      ref={rootEl}
+      role="status"
+      aria-live="polite"
+      class={cn(
+        'inline-flex items-center gap-1.5 rounded-full px-3 py-1 text-sm font-medium transition-colors',
+        STATE_CLASSES[props.state],
+        props.class,
+      )}
+    >
+      <span ref={contentEl} class="inline-flex items-center gap-1.5">
+        <Switch>
+          <Match when={props.state === 'loading'}>
+            <Loader2 class="h-3.5 w-3.5 animate-spin" />
+          </Match>
+          <Match when={props.state === 'success'}>
+            <Check class="h-3.5 w-3.5" />
+          </Match>
+          <Match when={props.state === 'error'}>
+            <X class="h-3.5 w-3.5" />
+          </Match>
+        </Switch>
+        <span>{label()}</span>
+      </span>
+    </span>
+  )
+}

package/src/ui/NotificationStack.tsx

@@ -0,0 +1,104 @@
+// A stacked-notifications widget (phone lock-screen style): the newest card is
+// full-size on top and older cards peek out behind it, scaled down and offset.
+// Presentational + controlled — the parent owns `items` (newest first) and
+// removes a card when `onDismiss` fires; the stack re-flows with a CSS transition.
+import { For, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animateIn, motionReduced } from '../lib/motion'
+
+export interface StackNotification {
+  id: string | number
+  title: string
+  description?: string
+  icon?: JSX.Element
+}
+
+export interface NotificationStackProps {
+  /** Newest first. The parent owns this array. */
+  items: StackNotification[]
+  /** How many cards are visible before the rest collapse behind. @default 3 */
+  max?: number
+  /** Fired when a card is dismissed; the parent should drop it from `items`. */
+  onDismiss?: (id: string | number) => void
+  class?: string
+}
+
+/**
+ * Stacked notifications. Cards behind the front one are offset down and scaled,
+ * so they peek from the bottom edge; removing the front card promotes the rest
+ * with a smooth transition (skipped under reduced motion). New cards fade/slide
+ * in via `animateIn`.
+ *
+ * @example
+ * ```tsx
+ * const [items, setItems] = createStore<StackNotification[]>([])
+ * <NotificationStack
+ *   items={items}
+ *   onDismiss={(id) => setItems((xs) => xs.filter((x) => x.id !== id))}
+ * />
+ * ```
+ */
+export function NotificationStack(props: NotificationStackProps): JSX.Element {
+  const max = () => props.max ?? 3
+
+  return (
+    <div
+      role="log"
+      aria-live="polite"
+      class={cn('relative w-full max-w-sm', props.class)}
+      // reserve room for the front card plus the peek of those behind it
+      style={{ 'min-height': `${88 + (Math.min(props.items.length, max()) - 1) * 10}px` }}
+    >
+      <For each={props.items}>
+        {(item, i) => {
+          const hidden = () => i() > max() - 1
+          return (
+            <div
+              ref={(el) => animateIn(el, { y: -8 })}
+              class={cn(
+                'card absolute inset-x-0 top-0 rounded-xl border border-border bg-card p-3 shadow-lg',
+                !motionReduced() && 'transition-[transform,opacity] duration-300 ease-out',
+              )}
+              style={{
+                transform: `translateY(${i() * 10}px) scale(${1 - i() * 0.05})`,
+                opacity: hidden() ? 0 : 1 - i() * 0.15,
+                'z-index': props.items.length - i(),
+                'pointer-events': hidden() ? 'none' : 'auto',
+                'transform-origin': 'top center',
+              }}
+            >
+              <div class="flex items-start gap-2.5">
+                {item.icon && <span class="mt-0.5 shrink-0 text-primary">{item.icon}</span>}
+                <div class="min-w-0 flex-1">
+                  <p class="truncate text-sm font-medium text-foreground">{item.title}</p>
+                  {item.description && (
+                    <p class="mt-0.5 line-clamp-2 text-sm text-muted-foreground">{item.description}</p>
+                  )}
+                </div>
+                <button
+                  type="button"
+                  aria-label={`Dismiss ${item.title}`}
+                  onClick={() => props.onDismiss?.(item.id)}
+                  class="shrink-0 rounded-md p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                >
+                  <svg
+                    viewBox="0 0 24 24"
+                    class="h-3.5 w-3.5"
+                    fill="none"
+                    stroke="currentColor"
+                    stroke-width="2.5"
+                    stroke-linecap="round"
+                    aria-hidden="true"
+                  >
+                    <path d="M6 6l12 12M18 6L6 18" />
+                  </svg>
+                </button>
+              </div>
+            </div>
+          )
+        }}
+      </For>
+    </div>
+  )
+}

package/src/ui/NowPlaying.tsx

@@ -0,0 +1,100 @@
+// Compact "now playing" music widget: cover art, title/artist, and an
+// animated equalizer. The bounce is pure CSS (keyframes injected once into
+// the document head), so the bars animate at zero per-frame JS cost — same
+// pattern as LoadingDots. Bars freeze to a static height when playback is
+// paused or under reduced motion.
+import type { JSX } from 'solid-js'
+import { For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface NowPlayingProps {
+  title: string
+  artist?: string
+  /** Cover art URL. */
+  cover?: string
+  /** Whether the equalizer bars are animating. @default true */
+  playing?: boolean
+  class?: string
+}
+
+const STYLE_ID = 'a4ui-now-playing-style'
+
+function ensureStyleInjected(): void {
+  if (typeof document === 'undefined' || document.getElementById(STYLE_ID)) return
+  const style = document.createElement('style')
+  style.id = STYLE_ID
+  style.textContent = `
+@keyframes a4-eq {
+  0%, 100% { transform: scaleY(0.3); }
+  50% { transform: scaleY(1); }
+}
+`
+  document.head.appendChild(style)
+}
+
+// Per-bar duration/delay (seconds) so the bars don't bounce in lockstep.
+const BARS = [
+  { duration: 0.6, delay: 0 },
+  { duration: 0.5, delay: 0.1 },
+  { duration: 0.7, delay: 0.05 },
+  { duration: 0.45, delay: 0.15 },
+  { duration: 0.65, delay: 0.2 },
+]
+
+/**
+ * Compact "now playing" music widget with an animated equalizer. Bars bounce
+ * via CSS keyframes while `playing` is true; they freeze to a low static
+ * height when paused or under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <NowPlaying title="Random Access Memories" artist="Daft Punk" cover="/covers/ram.jpg" playing />
+ * ```
+ */
+export function NowPlaying(props: NowPlayingProps): JSX.Element {
+  ensureStyleInjected()
+
+  const playing = () => (props.playing ?? true) && !motionReduced()
+
+  const barStyle = (bar: (typeof BARS)[number], index: number): JSX.CSSProperties => {
+    if (!playing()) {
+      return {
+        height: '30%',
+        'transform-origin': 'bottom',
+      }
+    }
+    return {
+      height: '100%',
+      'transform-origin': 'bottom',
+      'animation-name': 'a4-eq',
+      'animation-duration': `${bar.duration}s`,
+      'animation-delay': `${bar.delay + index * 0.02}s`,
+      'animation-iteration-count': 'infinite',
+      'animation-timing-function': 'ease-in-out',
+    }
+  }
+
+  return (
+    <div
+      class={cn('flex items-center gap-3 rounded-xl border border-border bg-card p-3', props.class)}
+      aria-label={`Now playing: ${props.title}${props.artist ? ` by ${props.artist}` : ''}`}
+    >
+      <Show when={props.cover} fallback={<div class="h-12 w-12 shrink-0 rounded-lg bg-muted" />}>
+        <img src={props.cover} alt="" class="h-12 w-12 shrink-0 rounded-lg object-cover" />
+      </Show>
+      <div class="min-w-0 flex-1">
+        <p class="truncate font-medium text-foreground">{props.title}</p>
+        <Show when={props.artist}>
+          <p class="truncate text-sm text-muted-foreground">{props.artist}</p>
+        </Show>
+      </div>
+      <div class="flex h-6 items-end gap-0.5">
+        <For each={BARS}>
+          {(bar, index) => <span class="w-1 rounded-full bg-primary" style={barStyle(bar, index())} />}
+        </For>
+      </div>
+    </div>
+  )
+}

package/src/ui/Parallax.tsx

@@ -0,0 +1,51 @@
+// Parallax — moves its children at a fraction of scroll speed for depth,
+// driven by Motion's `scroll` progress callback (0..1) as the element passes
+// through the viewport. No-op (static) under reduced motion.
+import { onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced, scroll } from '../lib/motion'
+
+export interface ParallaxProps {
+  children: JSX.Element
+  /** Parallax strength; positive moves slower/opposite. Pixels of travel across the scroll range. @default 80 */
+  amount?: number
+  class?: string
+}
+
+/**
+ * Wraps `children` in an element that drifts vertically as the page scrolls,
+ * creating a depth effect. Tracks scroll progress of the element itself
+ * against the viewport via Motion's `scroll`; respects `prefers-reduced-motion`
+ * (renders static).
+ *
+ * @example
+ * ```tsx
+ * <Parallax amount={120}>
+ *   <img src="/hero.png" alt="" />
+ * </Parallax>
+ * ```
+ */
+export function Parallax(props: ParallaxProps): JSX.Element {
+  let root!: HTMLDivElement
+
+  onMount(() => {
+    if (motionReduced()) return
+
+    const amount = props.amount ?? 80
+    const stop = scroll(
+      (progress: number) => {
+        root.style.transform = `translateY(${(progress - 0.5) * -2 * amount}px)`
+      },
+      { target: root },
+    )
+
+    onCleanup(() => stop())
+  })
+
+  return (
+    <div ref={root} class={cn('will-change-transform', props.class)}>
+      {props.children}
+    </div>
+  )
+}

package/src/ui/ScrambleText.tsx

@@ -0,0 +1,95 @@
+// Text that "decodes" into place: characters scramble through random glyphs
+// before locking, left to right, into the final string — motion.dev's
+// scramble-text effect, reimplemented here with a plain setInterval (locking
+// one more character's worth of the string on each tick) rather than the
+// `motion` package, since the effect is character substitution, not a tween.
+import { createSignal, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface ScrambleTextProps {
+  text: string
+  /** When to run: on mount, or on hover. @default 'mount' */
+  trigger?: 'mount' | 'hover'
+  /** Total scramble duration in ms. @default 800 */
+  duration?: number
+  class?: string
+}
+
+const GLYPHS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*<>-_'
+const TICK_MS = 30
+
+function randomGlyph(): string {
+  return GLYPHS[Math.floor(Math.random() * GLYPHS.length)] as string
+}
+
+/**
+ * Text that scrambles through random glyphs before "decoding" into the final
+ * string, left to right, over `duration` ms. Runs once on mount by default;
+ * pass `trigger="hover"` to (re)run it — cleanly restarting if it's still
+ * mid-scramble — on pointer hover instead. Renders the final text as-is, with
+ * no scramble, when the user prefers reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <ScrambleText text="ACCESS GRANTED" trigger="hover" duration={600} />
+ * ```
+ */
+export function ScrambleText(props: ScrambleTextProps): JSX.Element {
+  // eslint-disable-next-line solid/reactivity -- one-time seed; scramble() re-reads props.text on each run
+  const [display, setDisplay] = createSignal(props.text)
+  let intervalId: ReturnType<typeof setInterval> | undefined
+
+  const stop = (): void => {
+    if (intervalId === undefined) return
+    clearInterval(intervalId)
+    intervalId = undefined
+  }
+
+  const scramble = (): void => {
+    const text = props.text
+    if (motionReduced()) {
+      setDisplay(text)
+      return
+    }
+
+    // Restart cleanly if a previous scramble (from a prior trigger) is still running.
+    stop()
+    const totalTicks = Math.max(1, Math.round((props.duration ?? 800) / TICK_MS))
+    let tick = 0
+
+    intervalId = setInterval(() => {
+      tick += 1
+
+      if (tick >= totalTicks) {
+        setDisplay(text)
+        stop()
+        return
+      }
+
+      const lockedCount = Math.floor((tick / totalTicks) * text.length)
+      setDisplay(
+        text
+          .split('')
+          .map((char, i) => (char === ' ' || i < lockedCount ? char : randomGlyph()))
+          .join(''),
+      )
+    }, TICK_MS)
+  }
+
+  onMount(() => {
+    if (props.trigger !== 'hover') scramble()
+  })
+  onCleanup(stop)
+
+  const handleMouseEnter = (): void => {
+    if (props.trigger === 'hover') scramble()
+  }
+
+  return (
+    <span class={cn('font-mono', props.class)} onMouseEnter={handleMouseEnter}>
+      {display()}
+    </span>
+  )
+}