@a4ui/core 0.29.0 → 0.30.0

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>
+  )
+}

package/src/ui/IconMorphButton.tsx

@@ -0,0 +1,220 @@
+// IconMorphButton — a two-state icon toggle whose glyph morphs between an
+// inactive and active icon with a spring: the outgoing icon scales down +
+// rotates + fades out while the incoming scales up + rotates in + fades in,
+// both stacked absolutely inside a fixed-size box. Built for icon actions
+// with an obvious before/after (copy → copied, mute → muted, follow →
+// following). Optional label crossfades alongside the icon.
+import type { JSX } from 'solid-js'
+import { Show, createEffect, createSignal, onCleanup } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+/** Visual style of an {@link IconMorphButton}. Defaults to `'ghost'`. */
+export type IconMorphButtonVariant = 'solid' | 'ghost' | 'outline'
+
+const VARIANT_CLASSES: Record<IconMorphButtonVariant, string> = {
+  solid: 'bg-primary text-primary-foreground hover:bg-primary/90',
+  outline: 'border border-border bg-transparent text-foreground hover:bg-muted',
+  ghost: 'bg-transparent text-muted-foreground hover:bg-muted hover:text-foreground',
+}
+
+const BASE =
+  'inline-flex h-9 items-center justify-center gap-2 rounded-md text-sm font-medium transition-colors duration-150 focus:outline-none focus:ring-2 focus:ring-ring disabled:pointer-events-none disabled:opacity-50'
+
+const SPRING = { type: 'spring', stiffness: 380, damping: 30 } as const
+
+export interface IconMorphButtonProps {
+  /** Icon shown while `pressed` is `false`, e.g. `<Copy size={18} />`. */
+  inactive: JSX.Element
+  /** Icon shown while `pressed` is `true`, e.g. `<Check size={18} />`. */
+  active: JSX.Element
+  /** Controlled pressed state. Omit to let the button manage its own state. */
+  pressed?: boolean
+  /** Initial pressed state when uncontrolled. Defaults to `false`. */
+  defaultPressed?: boolean
+  /** Fired with the next pressed state, controlled or uncontrolled. */
+  onChange?: (pressed: boolean) => void
+  /**
+   * When greater than `0`, auto-reverts to `inactive` after this many ms once
+   * pressed (e.g. copy → check → copy). The timer is cleared on cleanup and
+   * restarted on every re-press. @default 0
+   */
+  revertAfter?: number
+  /** Optional label shown next to the icon while `pressed` is `false`. */
+  label?: JSX.Element
+  /** Optional label shown next to the icon while `pressed` is `true`. */
+  activeLabel?: JSX.Element
+  /** Visual style. Defaults to `'ghost'`. */
+  variant?: IconMorphButtonVariant
+  class?: string
+  'aria-label'?: string
+}
+
+/**
+ * Two-state icon toggle button whose icon morphs (spring scale + rotate +
+ * fade) between `inactive` and `active` glyphs, stacked in a fixed-size box.
+ * Supports controlled (`pressed`/`onChange`) or uncontrolled
+ * (`defaultPressed`) use, an optional auto-revert timer, and an optional
+ * crossfading label. Falls back to an instant swap under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <IconMorphButton
+ *   inactive={<Copy size={18} />}
+ *   active={<Check size={18} />}
+ *   aria-label="Copy to clipboard"
+ *   revertAfter={1500}
+ *   onChange={(pressed) => {
+ *     if (pressed) void navigator.clipboard?.writeText('npm install @a4ui/core')
+ *   }}
+ * />
+ * ```
+ */
+export function IconMorphButton(props: IconMorphButtonProps): JSX.Element {
+  const [internalPressed, setInternalPressed] = createSignal(props.defaultPressed ?? false)
+  const pressed = (): boolean => props.pressed ?? internalPressed()
+
+  const setPressed = (next: boolean): void => {
+    if (props.pressed === undefined) setInternalPressed(next)
+    props.onChange?.(next)
+  }
+
+  let revertTimer: ReturnType<typeof setTimeout> | undefined
+
+  const handleClick = (): void => {
+    clearTimeout(revertTimer)
+    const next = !pressed()
+    setPressed(next)
+    const revertAfter = props.revertAfter ?? 0
+    if (next && revertAfter > 0) {
+      revertTimer = setTimeout(() => setPressed(false), revertAfter)
+    }
+  }
+
+  let inactiveIconEl: HTMLSpanElement | undefined
+  let activeIconEl: HTMLSpanElement | undefined
+  let inactiveLabelEl: HTMLSpanElement | undefined
+  let activeLabelEl: HTMLSpanElement | undefined
+
+  let iconOutControls: ReturnType<typeof animate> | undefined
+  let iconInControls: ReturnType<typeof animate> | undefined
+  let labelOutControls: ReturnType<typeof animate> | undefined
+  let labelInControls: ReturnType<typeof animate> | undefined
+
+  const setInstant = (el: HTMLElement | undefined, visible: boolean, morph: boolean): void => {
+    if (!el) return
+    el.style.opacity = visible ? '1' : '0'
+    if (morph) el.style.transform = visible ? 'scale(1) rotate(0deg)' : 'scale(0.6) rotate(0deg)'
+  }
+
+  const applyInstant = (isPressed: boolean): void => {
+    setInstant(inactiveIconEl, !isPressed, true)
+    setInstant(activeIconEl, isPressed, true)
+    setInstant(inactiveLabelEl, !isPressed, false)
+    setInstant(activeLabelEl, isPressed, false)
+  }
+
+  let isFirstRun = true
+
+  createEffect(() => {
+    const isPressed = pressed()
+
+    if (isFirstRun) {
+      isFirstRun = false
+      applyInstant(isPressed)
+      return
+    }
+
+    iconOutControls?.stop()
+    iconInControls?.stop()
+    labelOutControls?.stop()
+    labelInControls?.stop()
+
+    if (motionReduced()) {
+      applyInstant(isPressed)
+      return
+    }
+
+    const outgoingIcon = isPressed ? inactiveIconEl : activeIconEl
+    const incomingIcon = isPressed ? activeIconEl : inactiveIconEl
+    const outRotate = isPressed ? 90 : -90
+    const inRotate = isPressed ? -90 : 90
+
+    if (outgoingIcon) {
+      iconOutControls = animate(
+        outgoingIcon,
+        { opacity: [1, 0], scale: [1, 0.6], rotate: [0, outRotate] },
+        SPRING,
+      )
+    }
+    if (incomingIcon) {
+      iconInControls = animate(
+        incomingIcon,
+        { opacity: [0, 1], scale: [0.6, 1], rotate: [inRotate, 0] },
+        SPRING,
+      )
+    }
+
+    const outgoingLabel = isPressed ? inactiveLabelEl : activeLabelEl
+    const incomingLabel = isPressed ? activeLabelEl : inactiveLabelEl
+
+    if (outgoingLabel) {
+      labelOutControls = animate(outgoingLabel, { opacity: [1, 0] }, { duration: 0.18, ease: 'easeOut' })
+    }
+    if (incomingLabel) {
+      labelInControls = animate(incomingLabel, { opacity: [0, 1] }, { duration: 0.18, ease: 'easeOut' })
+    }
+  })
+
+  onCleanup(() => {
+    clearTimeout(revertTimer)
+    iconOutControls?.stop()
+    iconInControls?.stop()
+    labelOutControls?.stop()
+    labelInControls?.stop()
+  })
+
+  const hasLabel = (): boolean => props.label !== undefined || props.activeLabel !== undefined
+
+  return (
+    <button
+      type="button"
+      aria-pressed={pressed()}
+      aria-label={props['aria-label']}
+      onClick={handleClick}
+      class={cn(BASE, hasLabel() ? 'px-3' : 'w-9', VARIANT_CLASSES[props.variant ?? 'ghost'], props.class)}
+    >
+      <span class="relative inline-block h-5 w-5 shrink-0">
+        <span
+          ref={inactiveIconEl}
+          class="absolute inset-0 flex items-center justify-center will-change-transform"
+          aria-hidden={pressed()}
+        >
+          {props.inactive}
+        </span>
+        <span
+          ref={activeIconEl}
+          class="absolute inset-0 flex items-center justify-center will-change-transform"
+          aria-hidden={!pressed()}
+        >
+          {props.active}
+        </span>
+      </span>
+      <Show when={hasLabel()}>
+        <span class="inline-grid">
+          <Show when={props.label}>
+            <span ref={inactiveLabelEl} class="col-start-1 row-start-1" aria-hidden={pressed()}>
+              {props.label}
+            </span>
+          </Show>
+          <Show when={props.activeLabel}>
+            <span ref={activeLabelEl} class="col-start-1 row-start-1" aria-hidden={!pressed()}>
+              {props.activeLabel}
+            </span>
+          </Show>
+        </span>
+      </Show>
+    </button>
+  )
+}