@a4ui/core 0.29.1 → 0.31.0

package/src/ui/CardSpread.tsx

@@ -0,0 +1,196 @@
+// CardSpread — a stack of cards that fans out into one of several layouts.
+// Rest state is a tight near-centered stack; opening (controlled via `open`,
+// or on hover when uncontrolled) spreads the cards per `layout`. Only
+// `transform`/`opacity` are animated (Motion spring), never layout properties,
+// so the fan stays compositor-only. Reduced motion renders the spread layout
+// statically (no transition, no hover animation).
+import { createEffect, createSignal, For, on, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+/** Fan shape applied when a {@link CardSpread} opens. Defaults to `'arc'`. */
+export type CardSpreadLayout = 'arc' | 'long-arc' | 'linear' | 'corner' | 'cascade' | 'scatter' | 'wheel'
+
+export interface CardSpreadProps {
+  /** Card contents; each entry becomes one card in the stack. */
+  items: JSX.Element[]
+  /** Fan shape. @default 'arc' */
+  layout?: CardSpreadLayout
+  /** Controlled open state. Omit to spread on hover instead. */
+  open?: boolean
+  /** Strength knob: degrees for arced/wheel layouts, px for linear/corner/cascade/scatter. Per-layout default applies when omitted. */
+  spread?: number
+  class?: string
+  'aria-label'?: string
+}
+
+interface CardTransform {
+  x: number
+  y: number
+  rotate: number
+  origin: string
+}
+
+const DEFAULT_SPREAD: Record<CardSpreadLayout, number> = {
+  arc: 10,
+  'long-arc': 6,
+  linear: 56,
+  corner: 12,
+  cascade: 18,
+  scatter: 14,
+  wheel: 16,
+}
+
+// Deterministic pseudo-random offset in [-1, 1] from an index — no Math.random.
+function pseudoRandom(i: number): number {
+  const s = Math.sin(i * 12.9898) * 43758.5453
+  return (s - Math.floor(s)) * 2 - 1
+}
+
+function restTransform(i: number, n: number): CardTransform {
+  // Resting deck: a gentle symmetric peek-fan (cards' edges show) so the pile
+  // reads as multiple cards even before it opens, without stealing the reveal.
+  const mid = (n - 1) / 2
+  const d = i - mid
+  return { x: d * 7, y: Math.abs(d) * 2.5, rotate: d * 2.5, origin: 'bottom center' }
+}
+
+function openTransform(layout: CardSpreadLayout, i: number, n: number, spread: number): CardTransform {
+  const mid = (n - 1) / 2
+  const d = i - mid
+
+  switch (layout) {
+    case 'arc': {
+      const gap = 44
+      return { x: d * gap, y: Math.abs(d) ** 2 * 6, rotate: d * spread, origin: 'bottom center' }
+    }
+    case 'long-arc': {
+      const gap = 68
+      return { x: d * gap, y: Math.abs(d) ** 2 * 4, rotate: d * spread, origin: 'bottom center' }
+    }
+    case 'linear':
+      return { x: d * spread, y: 0, rotate: 0, origin: 'bottom center' }
+    case 'corner':
+      return { x: i * (spread * 0.6), y: -i * (spread * 0.15), rotate: i * spread, origin: 'bottom left' }
+    case 'cascade':
+      return {
+        x: i * spread,
+        y: i * (spread * 0.55),
+        rotate: (i % 2 === 0 ? 1 : -1) * 3,
+        origin: 'bottom center',
+      }
+    case 'scatter': {
+      const r = pseudoRandom(i)
+      const r2 = pseudoRandom(i + 100)
+      return { x: r * spread * 3, y: r2 * spread * 1.5, rotate: r * spread, origin: 'center center' }
+    }
+    case 'wheel':
+      return { x: d * 18, y: Math.abs(d) * 10, rotate: d * spread, origin: 'bottom center' }
+  }
+}
+
+function transformString(t: CardTransform): string {
+  return `translate(${t.x}px, ${t.y}px) rotate(${t.rotate}deg)`
+}
+
+/**
+ * A stack of cards that fans out into an arc, line, corner, cascade, scatter,
+ * or wheel shape. At rest the cards sit in a near-centered pile; opening
+ * (controlled via `open`, or on hover when uncontrolled) spreads them.
+ * Animates only `transform`/`opacity` (Motion spring) so the fan stays
+ * compositor-only, and falls back to a static fanned layout under reduced
+ * motion.
+ *
+ * @example
+ * ```tsx
+ * <CardSpread
+ *   layout="arc"
+ *   aria-label="Trip itinerary cards"
+ *   items={[
+ *     <div class="p-4">Day 1 — Arrival</div>,
+ *     <div class="p-4">Day 2 — Old Town</div>,
+ *     <div class="p-4">Day 3 — Coast drive</div>,
+ *   ]}
+ * />
+ * ```
+ */
+export function CardSpread(props: CardSpreadProps): JSX.Element {
+  const cardRefs: (HTMLElement | undefined)[] = []
+  const controls: (ReturnType<typeof animate> | undefined)[] = []
+  const [hovered, setHovered] = createSignal(false)
+
+  const layout = () => props.layout ?? 'arc'
+  const spread = () => props.spread ?? DEFAULT_SPREAD[layout()]
+  const isOpen = () => (props.open !== undefined ? props.open : hovered())
+
+  // Reduced motion always renders the fanned layout, statically, regardless
+  // of open/hover state — so `open`/`hover` never trigger visible motion.
+  const applyTransforms = (animated: boolean) => {
+    const n = props.items.length
+    const reduced = motionReduced()
+    const open = reduced ? true : isOpen()
+
+    cardRefs.forEach((card, i) => {
+      if (!card) return
+      const t = open ? openTransform(layout(), i, n, spread()) : restTransform(i, n)
+      card.style.transformOrigin = t.origin
+      card.style.zIndex = String(open ? i : n - i)
+
+      controls[i]?.stop()
+      if (reduced || !animated) {
+        card.style.transform = transformString(t)
+        return
+      }
+      controls[i] = animate(
+        card,
+        { x: t.x, y: t.y, rotate: t.rotate },
+        { type: 'spring', stiffness: 260, damping: 24 },
+      )
+    })
+  }
+
+  // Initial paint only: snap to the correct state (no animation) so a controlled
+  // `open` or a reduced-motion preference doesn't flash the closed stack first.
+  // Deliberately untracked (onMount, not createEffect) — it must run exactly
+  // once, otherwise it would re-fire on every hover/open change and snap the
+  // cards straight to their target, leaving the animated effect below nothing
+  // to spring from.
+  onMount(() => applyTransforms(false))
+  // Subsequent changes to open/hover/layout/spread animate in.
+  createEffect(
+    on([() => props.open, hovered, layout, spread, () => props.items.length], () => applyTransforms(true), {
+      defer: true,
+    }),
+  )
+  onCleanup(() => controls.forEach((c) => c?.stop()))
+
+  const handleEnter = () => {
+    if (props.open === undefined && !motionReduced()) setHovered(true)
+  }
+  const handleLeave = () => {
+    if (props.open === undefined && !motionReduced()) setHovered(false)
+  }
+
+  return (
+    <div
+      role="group"
+      aria-label={props['aria-label']}
+      class={cn('relative inline-block h-56 w-40', props.class)}
+      onPointerEnter={handleEnter}
+      onPointerLeave={handleLeave}
+    >
+      <For each={props.items}>
+        {(item, i) => (
+          <div
+            ref={(el) => (cardRefs[i()] = el)}
+            class="absolute inset-x-0 top-0 h-56 w-40 rounded-xl border border-border bg-card text-card-foreground shadow-sm will-change-transform"
+            style={{ transform: transformString(restTransform(i(), props.items.length)) }}
+          >
+            {item}
+          </div>
+        )}
+      </For>
+    </div>
+  )
+}

package/src/ui/Carousel3D.tsx

@@ -0,0 +1,308 @@
+// Carousel3D — a 3D coverflow/arc carousel. A `perspective` + `preserve-3d`
+// stage holds absolutely-positioned slides that are repositioned ONLY via
+// `transform` (translate/rotateY/scale) + `opacity` — never width/height/
+// top/left — so every pose change stays compositor-only. Transform changes
+// are driven by a Motion spring when the active slide changes. Falls back to
+// a flat opacity crossfade (no 3D) under reduced motion.
+import { ChevronLeft, ChevronRight } from 'lucide-solid'
+import { createEffect, createMemo, createSignal, For, on, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+/** Layout curve for a {@link Carousel3D}. Defaults to `'coverflow'`. */
+export type Carousel3DVariant = 'coverflow' | 'arc'
+
+export interface Carousel3DProps {
+  /** Slides shown around the active one, arranged by distance from it. */
+  slides: JSX.Element[]
+  /** Layout curve. @default 'coverflow' */
+  variant?: Carousel3DVariant
+  /** Controlled active index. */
+  active?: number
+  /** Initial active index when uncontrolled. @default 0 */
+  defaultActive?: number
+  /** Fires with the new index whenever the active slide changes. */
+  onChange?: (index: number) => void
+  class?: string
+}
+
+interface SlidePose {
+  x: number
+  y: number
+  z: number
+  rotateY: number
+  scale: number
+  opacity: number
+}
+
+// Base position (before the per-offset pose) centers each slide in the stage;
+// the transform's x always starts at `-50%` and adds pixel offsets on top.
+const FLAT_TRANSFORM = 'translate3d(-50%, 0, 0)'
+
+const clamp = (value: number, min: number, max: number): number => Math.max(min, Math.min(max, value))
+
+function coverflowPose(offset: number): SlidePose {
+  const spacing = 130
+  const depth = 160
+  const angle = 55
+  return {
+    x: offset * spacing,
+    y: 0,
+    z: -Math.abs(offset) * depth,
+    rotateY: clamp(-offset * angle, -45, 45),
+    scale: offset === 0 ? 1 : 0.82,
+    opacity: clamp(1 - Math.abs(offset) * 0.35, 0, 1),
+  }
+}
+
+function arcPose(offset: number): SlidePose {
+  const spacing = 110
+  const angle = 14
+  const dip = 16
+  return {
+    x: offset * spacing,
+    y: offset ** 2 * dip,
+    z: -Math.abs(offset) * 70,
+    rotateY: clamp(offset * angle, -50, 50),
+    scale: clamp(1 - Math.abs(offset) * 0.16, 0.55, 1),
+    opacity: clamp(1 - Math.abs(offset) * 0.3, 0, 1),
+  }
+}
+
+function poseFor(variant: Carousel3DVariant, offset: number): SlidePose {
+  return variant === 'arc' ? arcPose(offset) : coverflowPose(offset)
+}
+
+function poseTransform(pose: SlidePose): string {
+  return `translate3d(calc(-50% + ${pose.x}px), ${pose.y}px, ${pose.z}px) rotateY(${pose.rotateY}deg) scale(${pose.scale})`
+}
+
+/**
+ * A 3D carousel that arranges slides around the active one on a coverflow or
+ * shallow arc curve — `perspective` + `preserve-3d`, each slide positioned
+ * purely by `transform`/`opacity` (Motion spring) so it stays
+ * compositor-only. Supports controlled/uncontrolled `active`, prev/next
+ * buttons, dot indicators, arrow-key navigation, and pointer-drag swiping.
+ * Falls back to a flat opacity crossfade (no 3D transforms) under reduced
+ * motion.
+ *
+ * @example
+ * ```tsx
+ * <Carousel3D
+ *   variant="coverflow"
+ *   slides={[
+ *     <div class="grid h-full place-items-center rounded-xl border border-border bg-card p-6 text-center">Trail A — Ridge Loop</div>,
+ *     <div class="grid h-full place-items-center rounded-xl border border-border bg-card p-6 text-center">Trail B — Falls Overlook</div>,
+ *     <div class="grid h-full place-items-center rounded-xl border border-border bg-card p-6 text-center">Trail C — Summit Pass</div>,
+ *   ]}
+ * />
+ * ```
+ */
+export function Carousel3D(props: Carousel3DProps): JSX.Element {
+  const [uncontrolled, setUncontrolled] = createSignal(props.defaultActive ?? 0)
+  const count = (): number => props.slides.length
+  const clampIndex = (i: number): number => clamp(i, 0, Math.max(0, count() - 1))
+  const isControlled = (): boolean => props.active !== undefined
+  const active = createMemo((): number =>
+    clampIndex(isControlled() ? (props.active as number) : uncontrolled()),
+  )
+  const variant = (): Carousel3DVariant => props.variant ?? 'coverflow'
+
+  const setActive = (index: number): void => {
+    const next = clampIndex(index)
+    if (next === active()) return
+    if (!isControlled()) setUncontrolled(next)
+    props.onChange?.(next)
+  }
+  const prev = (): void => setActive(active() - 1)
+  const next = (): void => setActive(active() + 1)
+
+  const onKeyDown = (e: KeyboardEvent): void => {
+    if (e.key === 'ArrowLeft') {
+      e.preventDefault()
+      prev()
+    } else if (e.key === 'ArrowRight') {
+      e.preventDefault()
+      next()
+    }
+  }
+
+  // --- pose application (static snap on mount, Motion spring on change) ----
+  let stage: HTMLDivElement | undefined
+  const controls = new Map<number, ReturnType<typeof animate>>()
+
+  const stopAll = (): void => {
+    controls.forEach((c) => c.stop())
+    controls.clear()
+  }
+
+  const items = (): HTMLElement[] =>
+    stage ? Array.from(stage.querySelectorAll<HTMLElement>('[data-carousel3d-item]')) : []
+
+  function applyStatic(): void {
+    const a = active()
+    const v = variant()
+    const reduced = motionReduced()
+    items().forEach((el, i) => {
+      el.style.zIndex = String(-Math.abs(i - a))
+      if (reduced) {
+        el.style.transform = FLAT_TRANSFORM
+        el.style.opacity = i === a ? '1' : '0'
+        return
+      }
+      const pose = poseFor(v, i - a)
+      el.style.transform = poseTransform(pose)
+      el.style.opacity = String(pose.opacity)
+    })
+  }
+
+  function applyAnimated(): void {
+    if (!stage) return
+    const a = active()
+    const v = variant()
+    const reduced = motionReduced()
+    stopAll()
+    items().forEach((el, i) => {
+      el.style.zIndex = String(-Math.abs(i - a))
+      if (reduced) {
+        el.style.transform = FLAT_TRANSFORM
+        controls.set(i, animate(el, { opacity: i === a ? 1 : 0 }, { duration: 0.25, ease: 'easeOut' }))
+        return
+      }
+      const pose = poseFor(v, i - a)
+      controls.set(
+        i,
+        animate(
+          el,
+          {
+            x: pose.x,
+            y: pose.y,
+            z: pose.z,
+            rotateY: pose.rotateY,
+            scale: pose.scale,
+            opacity: pose.opacity,
+          },
+          { type: 'spring', stiffness: 300, damping: 32 },
+        ),
+      )
+    })
+  }
+
+  onMount(applyStatic)
+
+  // Re-pose (animated) whenever the active slide, variant, slide count, or
+  // reduced-motion state changes. `defer: true` skips the initial run — the
+  // onMount `applyStatic` above already seeds the correct pose with no
+  // animation, so a slide never flashes in from an untransformed position.
+  createEffect(on([active, variant, count, motionReduced], () => applyAnimated(), { defer: true }))
+
+  onCleanup(stopAll)
+
+  // --- pointer drag: horizontal movement past a threshold advances one slide
+  // per threshold crossed, so a long drag can page through several slides. --
+  const [dragging, setDragging] = createSignal(false)
+  let startX = 0
+  const DRAG_THRESHOLD = 60
+
+  const onPointerDown = (e: PointerEvent): void => {
+    if (count() < 2) return
+    startX = e.clientX
+    setDragging(true)
+    ;(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId)
+  }
+  const onPointerMove = (e: PointerEvent): void => {
+    if (!dragging()) return
+    const dx = e.clientX - startX
+    if (dx <= -DRAG_THRESHOLD) {
+      next()
+      startX = e.clientX
+    } else if (dx >= DRAG_THRESHOLD) {
+      prev()
+      startX = e.clientX
+    }
+  }
+  const endDrag = (): void => {
+    setDragging(false)
+  }
+
+  return (
+    <div
+      role="region"
+      aria-roledescription="carousel"
+      tabindex="0"
+      class={cn(
+        'flex w-full flex-col gap-4 outline-none focus-visible:ring-2 focus-visible:ring-primary',
+        props.class,
+      )}
+      onKeyDown={onKeyDown}
+    >
+      <div
+        class={cn(
+          'relative h-80 select-none',
+          count() > 1 && 'touch-pan-y cursor-grab active:cursor-grabbing',
+        )}
+        style={{ perspective: '1200px' }}
+        onPointerDown={onPointerDown}
+        onPointerMove={onPointerMove}
+        onPointerUp={endDrag}
+        onPointerCancel={endDrag}
+      >
+        <div ref={stage} class="relative h-full w-full" style={{ 'transform-style': 'preserve-3d' }}>
+          <For each={props.slides}>
+            {(slide, i) => (
+              <div
+                data-carousel3d-item
+                class="absolute left-1/2 top-0 h-full w-64 will-change-transform"
+                aria-hidden={i() !== active()}
+              >
+                {slide}
+              </div>
+            )}
+          </For>
+        </div>
+
+        <button
+          type="button"
+          aria-label="Previous slide"
+          disabled={count() === 0 || active() === 0}
+          onClick={prev}
+          class="absolute left-2 top-1/2 flex h-9 w-9 -translate-y-1/2 items-center justify-center rounded-full bg-primary text-primary-foreground shadow transition-opacity hover:opacity-90 disabled:pointer-events-none disabled:opacity-40"
+        >
+          <ChevronLeft class="h-5 w-5" />
+        </button>
+        <button
+          type="button"
+          aria-label="Next slide"
+          disabled={count() === 0 || active() === count() - 1}
+          onClick={next}
+          class="absolute right-2 top-1/2 flex h-9 w-9 -translate-y-1/2 items-center justify-center rounded-full bg-primary text-primary-foreground shadow transition-opacity hover:opacity-90 disabled:pointer-events-none disabled:opacity-40"
+        >
+          <ChevronRight class="h-5 w-5" />
+        </button>
+      </div>
+
+      <div class="flex items-center justify-center gap-1">
+        <For each={props.slides}>
+          {(_, i) => (
+            // 24×24 hit target (a11y target-size) around a small visual dot.
+            <button
+              type="button"
+              aria-label={`Go to slide ${i() + 1}`}
+              aria-current={active() === i() ? 'true' : undefined}
+              onClick={() => setActive(i())}
+              class="grid h-6 w-6 place-items-center rounded-full focus:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              <span
+                class={cn(
+                  'h-2 w-2 rounded-full transition-colors',
+                  active() === i() ? 'bg-primary' : 'bg-muted',
+                )}
+              />
+            </button>
+          )}
+        </For>
+      </div>
+    </div>
+  )
+}

package/src/ui/FocusBlurGroup.tsx

@@ -0,0 +1,69 @@
+// Spotlight-the-hovered-one container: hovering/focusing one item keeps it
+// sharp/full-opacity while the rest blur + dim. Purely visual — pointer/focus
+// driven, never traps focus or hijacks keyboard. Only `opacity` and `filter`
+// (blur) are animated so the effect stays a compositor-only transition (no
+// layout props ever transition).
+import { createSignal, For, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface FocusBlurGroupProps<T> {
+  /** The full data set to render. */
+  items: T[]
+  /** Row renderer. */
+  children: (item: T, index: number) => JSX.Element
+  /** Blur (px) applied to non-focused items. @default 2 */
+  blur?: number
+  /** Opacity (0..1) applied to non-focused items. @default 0.5 */
+  dim?: number
+  /** Applied to the container — use it for layout (e.g. `flex gap-6`). */
+  class?: string
+}
+
+/**
+ * Container that spotlights whichever item is hovered or keyboard-focused:
+ * that item stays sharp and fully opaque while its siblings blur and dim.
+ * Only `opacity`/`filter` transition — never a layout property — and under
+ * `motionReduced()` the blur is skipped (dim-only, no transition) since blur
+ * motion reads as motion-sickness-adjacent.
+ *
+ * @example
+ * ```tsx
+ * <FocusBlurGroup items={navLinks} class="flex gap-6">
+ *   {(link) => (
+ *     <a href={link.href} class="text-sm font-medium text-foreground">
+ *       {link.label}
+ *     </a>
+ *   )}
+ * </FocusBlurGroup>
+ * ```
+ */
+export function FocusBlurGroup<T>(props: FocusBlurGroupProps<T>): JSX.Element {
+  const [hovered, setHovered] = createSignal<number | null>(null)
+
+  return (
+    <div class={cn(props.class)} onPointerLeave={() => setHovered(null)} onFocusOut={() => setHovered(null)}>
+      <For each={props.items}>
+        {(item, index) => {
+          const isFocused = () => hovered() === null || hovered() === index()
+          const reduced = motionReduced()
+
+          return (
+            <div
+              onPointerEnter={() => setHovered(index())}
+              onFocusIn={() => setHovered(index())}
+              style={{
+                opacity: isFocused() ? 1 : (props.dim ?? 0.5),
+                filter: reduced || isFocused() ? 'none' : `blur(${props.blur ?? 2}px)`,
+                transition: reduced ? 'none' : 'opacity 200ms ease, filter 200ms ease',
+              }}
+            >
+              {props.children(item, index())}
+            </div>
+          )
+        }}
+      </For>
+    </div>
+  )
+}