@a4ui/core 0.29.1 → 0.31.0

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

package/src/ui/LikeButton.tsx

@@ -0,0 +1,199 @@
+// LikeButton — a like/favorite/save-later toggle driven by the `icon` prop
+// (heart/star/bookmark) instead of three near-identical components. On
+// becoming pressed the icon fills, morphs to the accent color, springs a
+// scale pop (Motion's `spring`), and bursts a handful of tiny icon copies
+// outward (staggered via `stagger`) before fading. Only `transform`/`opacity`
+// are animated, matching this file's Motion helpers (see ../lib/motion.ts).
+import { Bookmark, Heart, Star, type LucideProps } from 'lucide-solid'
+import type { Component, JSX } from 'solid-js'
+import { createEffect, createMemo, createSignal, For, onCleanup, Show } from 'solid-js'
+import { Dynamic } from 'solid-js/web'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced, spring, stagger } from '../lib/motion'
+
+/** Which icon a {@link LikeButton} renders — picks the semantic use (like/favorite/save). */
+export type LikeButtonIcon = 'heart' | 'star' | 'bookmark'
+
+const ICONS: Record<LikeButtonIcon, Component<LucideProps>> = {
+  heart: Heart,
+  star: Star,
+  bookmark: Bookmark,
+}
+
+const BURST_COUNT = 5
+const BURST_RADIUS_PX = 18
+const BURST_STAGGER_S = 0.03
+const BURST_DURATION_S = 0.5
+
+interface BurstParticle {
+  id: number
+  angle: number
+}
+
+export interface LikeButtonProps {
+  /** Controlled pressed state. When set, wins over internal state — pair with `onChange`. */
+  pressed?: boolean
+  /** Initial pressed state for uncontrolled use. @default false */
+  defaultPressed?: boolean
+  onChange?: (pressed: boolean) => void
+  /** Which icon to render. @default 'heart' */
+  icon?: LikeButtonIcon
+  /** Count shown next to the icon (e.g. total likes). */
+  count?: number
+  /** Show `count`. @default false */
+  showCount?: boolean
+  /** Class applied to the icon/count when pressed. @default 'text-primary' */
+  activeClass?: string
+  class?: string
+  'aria-label'?: string
+}
+
+/**
+ * Like/favorite/save-later toggle button. One component covers all three via
+ * `icon` ('heart' | 'star' | 'bookmark') rather than three near-identical
+ * toggles. On becoming pressed the icon fills, morphs to `activeClass`,
+ * springs a scale pop, and bursts a handful of tiny icon copies outward —
+ * skipped under reduced motion, which just flips the filled/unfilled state
+ * instantly. Works controlled (`pressed` + `onChange`) or uncontrolled
+ * (`defaultPressed`).
+ *
+ * @example
+ * ```tsx
+ * <LikeButton defaultPressed count={128} showCount aria-label="Like this post" />
+ * ```
+ */
+export function LikeButton(props: LikeButtonProps): JSX.Element {
+  const [internalPressed, setInternalPressed] = createSignal(props.defaultPressed ?? false)
+  const pressed = createMemo(() => props.pressed ?? internalPressed())
+  const Icon = createMemo(() => ICONS[props.icon ?? 'heart'])
+
+  const [particles, setParticles] = createSignal<BurstParticle[]>([])
+  const particleEls = new Map<number, HTMLSpanElement>()
+  let particleId = 0
+  let iconEl: SVGSVGElement | undefined
+  let countEl: HTMLSpanElement | undefined
+  let popControls: ReturnType<typeof animate> | undefined
+  let disposed = false
+
+  onCleanup(() => {
+    disposed = true
+    popControls?.stop()
+  })
+
+  // Fade + slide the count in whenever it changes (not on initial mount), skipped under reduced motion.
+  let hasMountedCount = false
+  createEffect(() => {
+    void props.count
+    if (hasMountedCount && countEl && !motionReduced()) {
+      animate(countEl, { opacity: [0, 1], y: [-6, 0] }, { duration: 0.22, ease: 'easeOut' })
+    }
+    hasMountedCount = true
+  })
+
+  const playPop = (): void => {
+    if (!iconEl) return
+    popControls?.stop()
+    const el = iconEl
+    popControls = animate(el, { scale: 1.3 }, { type: spring, stiffness: 600, damping: 10 })
+    popControls.finished
+      .then(() => {
+        if (disposed) return
+        popControls = animate(el, { scale: 1 }, { type: spring, stiffness: 500, damping: 14 })
+      })
+      .catch(() => {})
+  }
+
+  const spawnBurst = (): void => {
+    const delayFor = stagger(BURST_STAGGER_S)
+    const next: BurstParticle[] = Array.from({ length: BURST_COUNT }, (_, index) => ({
+      id: particleId++,
+      angle: (360 / BURST_COUNT) * index,
+    }))
+    setParticles((current) => [...current, ...next])
+
+    queueMicrotask(() => {
+      if (disposed) return
+      const finished = next.map((particle, index) => {
+        const el = particleEls.get(particle.id)
+        if (!el) return Promise.resolve()
+        const radians = (particle.angle * Math.PI) / 180
+        const dx = Math.cos(radians) * BURST_RADIUS_PX
+        const dy = Math.sin(radians) * BURST_RADIUS_PX
+        const controls = animate(
+          el,
+          {
+            transform: [
+              'translate(-50%, -50%) scale(0.9)',
+              `translate(calc(-50% + ${dx}px), calc(-50% + ${dy}px)) scale(0.3)`,
+            ],
+            opacity: [1, 0],
+          },
+          { duration: BURST_DURATION_S, delay: delayFor(index, next.length), ease: 'easeOut' },
+        )
+        return controls.finished
+      })
+
+      Promise.allSettled(finished).then(() => {
+        for (const particle of next) particleEls.delete(particle.id)
+        if (disposed) return
+        setParticles((current) => current.filter((p) => !next.some((n) => n.id === p.id)))
+      })
+    })
+  }
+
+  const handleClick = (): void => {
+    const next = !pressed()
+    if (props.pressed === undefined) setInternalPressed(next)
+    props.onChange?.(next)
+
+    if (!next || motionReduced()) return
+    playPop()
+    spawnBurst()
+  }
+
+  return (
+    <button
+      type="button"
+      aria-pressed={pressed()}
+      aria-label={props['aria-label']}
+      class={cn(
+        'inline-flex items-center gap-1.5 rounded-md text-muted-foreground transition-colors hover:text-foreground',
+        pressed() && (props.activeClass ?? 'text-primary'),
+        props.class,
+      )}
+      onClick={handleClick}
+    >
+      <span class="relative inline-flex h-5 w-5 items-center justify-center">
+        <Dynamic
+          component={Icon()}
+          ref={(el: SVGSVGElement) => {
+            iconEl = el
+          }}
+          class={cn('h-5 w-5 will-change-transform', pressed() && 'fill-current')}
+        />
+        <span class="pointer-events-none absolute inset-0" aria-hidden="true">
+          <For each={particles()}>
+            {(particle) => (
+              <span
+                ref={(el) => particleEls.set(particle.id, el)}
+                class="absolute left-1/2 top-1/2 h-2.5 w-2.5 will-change-transform"
+                style={{ transform: 'translate(-50%, -50%)' }}
+              >
+                <Dynamic
+                  component={Icon()}
+                  class={cn('h-2.5 w-2.5 fill-current', props.activeClass ?? 'text-primary')}
+                />
+              </span>
+            )}
+          </For>
+        </span>
+      </span>
+      <Show when={props.showCount}>
+        <span ref={countEl} class="tabular-nums will-change-transform">
+          {props.count}
+        </span>
+      </Show>
+    </button>
+  )
+}

package/src/ui/MicroButton.tsx

@@ -0,0 +1,205 @@
+// MicroButton — small icon/label button that plays a short, physically-tuned
+// feedback micro-animation on interaction: spin, shake, pulse, ring, sparkle
+// (on click), or a diagonal glare sweep (on hover). Every effect animates only
+// transform/opacity (never layout), and decorative particles spawn then
+// remove themselves — the same one-shot pattern as spawnRipple in Ripple.tsx.
+// No-op (plain static button) under reduced motion.
+import { type JSX, Show, splitProps } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced, stagger } from '../lib/motion'
+
+/** Feedback micro-animation a {@link MicroButton} plays. Defaults to `'ring'`. */
+export type MicroButtonEffect = 'spin' | 'shake' | 'pulse' | 'ring' | 'sparkle' | 'glare'
+
+/** Visual style of a {@link MicroButton}. Defaults to `'solid'`. */
+export type MicroButtonVariant = 'solid' | 'ghost' | 'outline'
+
+const VARIANT_CLASSES: Record<MicroButtonVariant, string> = {
+  solid: 'bg-primary text-primary-foreground',
+  ghost: 'text-foreground hover:bg-muted',
+  outline: 'border border-border text-foreground',
+}
+
+const BASE =
+  'micro-button relative inline-flex items-center justify-center gap-2 rounded-full px-4 py-2 font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50'
+
+const PARTICLE_BASE = 'pointer-events-none absolute will-change-transform'
+
+export interface MicroButtonProps {
+  children?: JSX.Element
+  /** Feedback micro-animation. `'glare'` plays on hover; the rest play on click. @default 'ring' */
+  effect?: MicroButtonEffect
+  onClick?: (e: MouseEvent) => void
+  /** Visual style. @default 'solid' */
+  variant?: MicroButtonVariant
+  disabled?: boolean
+  class?: string
+  'aria-label'?: string
+}
+
+/**
+ * Small icon/label button that plays a short feedback micro-animation on
+ * interaction — spin, shake, pulse, ring, or sparkle on click, or a diagonal
+ * glare sweep on hover. Every effect animates only `transform`/`opacity`, so
+ * it stays cheap even on low-end devices; decorative particles are spawned
+ * and removed on completion, never left in the DOM. Renders a plain static
+ * `<button>` with no effect under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <MicroButton effect="sparkle" aria-label="Like">
+ *   <Heart size={16} />
+ * </MicroButton>
+ * ```
+ */
+export function MicroButton(props: MicroButtonProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['children', 'effect', 'onClick', 'variant', 'disabled', 'class'])
+
+  let buttonEl!: HTMLButtonElement
+  let contentEl!: HTMLSpanElement
+  let glareEl: HTMLSpanElement | undefined
+  let spins = 0
+
+  // Every in-flight animation registers a stopper here so onCleanup can halt
+  // it (and any pending particle removal) if the button unmounts mid-effect.
+  const activeStops = new Set<() => void>()
+
+  const track = (stop: () => void): (() => void) => {
+    activeStops.add(stop)
+    return () => activeStops.delete(stop)
+  }
+
+  const trackTransient = (controls: ReturnType<typeof animate>): void => {
+    const untrack = track(() => controls.stop())
+    controls.then(untrack)
+  }
+
+  const spawnParticle = (build: (el: HTMLSpanElement) => void): HTMLSpanElement => {
+    const el = document.createElement('span')
+    el.setAttribute('aria-hidden', 'true')
+    el.className = PARTICLE_BASE
+    build(el)
+    buttonEl.appendChild(el)
+    return el
+  }
+
+  const trackParticle = (el: HTMLSpanElement, controls: ReturnType<typeof animate>): void => {
+    const untrack = track(() => controls.stop())
+    const finish = (): void => {
+      untrack()
+      el.remove()
+    }
+    controls.then(finish)
+  }
+
+  const playSpin = (): void => {
+    spins += 360
+    trackTransient(animate(contentEl, { rotate: spins }, { type: 'spring', stiffness: 180, damping: 14 }))
+  }
+
+  const playShake = (): void => {
+    trackTransient(animate(contentEl, { x: [0, -4, 4, -3, 3, 0] }, { duration: 0.4, ease: 'easeInOut' }))
+  }
+
+  const spawnRing = (delay: number): void => {
+    const el = spawnParticle((e) => {
+      e.classList.add('inset-0', 'rounded-full', 'border-2', 'border-current')
+    })
+    trackParticle(
+      el,
+      animate(el, { scale: [1, 1.8], opacity: [0.6, 0] }, { duration: 0.7, delay, ease: 'easeOut' }),
+    )
+  }
+
+  const playRing = (): void => spawnRing(0)
+
+  const playPulse = (): void => {
+    spawnRing(0)
+    spawnRing(0.15)
+  }
+
+  const playSparkle = (): void => {
+    const count = 6
+    const radius = 20
+    for (let i = 0; i < count; i++) {
+      const angle = (i / count) * Math.PI * 2
+      const dx = Math.cos(angle) * radius
+      const dy = Math.sin(angle) * radius
+      const el = spawnParticle((e) => {
+        e.classList.add('left-1/2', 'top-1/2', 'h-1', 'w-1', 'rounded-full', 'bg-current')
+        e.style.marginLeft = '-2px'
+        e.style.marginTop = '-2px'
+      })
+      trackParticle(
+        el,
+        animate(
+          el,
+          { x: [0, dx], y: [0, dy], rotate: [0, 180], opacity: [1, 0], scale: [1, 0.4] },
+          { duration: 0.55, delay: stagger(0.03)(i, count), ease: 'easeOut' },
+        ),
+      )
+    }
+  }
+
+  const handleClick = (event: MouseEvent): void => {
+    local.onClick?.(event)
+    if (local.disabled || motionReduced()) return
+    switch (local.effect ?? 'ring') {
+      case 'spin':
+        playSpin()
+        break
+      case 'shake':
+        playShake()
+        break
+      case 'pulse':
+        playPulse()
+        break
+      case 'sparkle':
+        playSparkle()
+        break
+      case 'ring':
+        playRing()
+        break
+      // 'glare' plays on hover, not click — see handlePointerEnter.
+    }
+  }
+
+  const handlePointerEnter = (): void => {
+    if ((local.effect ?? 'ring') !== 'glare' || !glareEl || motionReduced()) return
+    trackTransient(
+      animate(glareEl, { x: ['-100%', '250%'], opacity: [0, 1, 0] }, { duration: 0.6, ease: 'easeInOut' }),
+    )
+  }
+
+  return (
+    <button
+      ref={buttonEl}
+      type="button"
+      class={cn(
+        BASE,
+        VARIANT_CLASSES[local.variant ?? 'solid'],
+        (local.effect ?? 'ring') === 'glare' && 'overflow-hidden',
+        local.class,
+      )}
+      disabled={local.disabled}
+      onClick={handleClick}
+      onPointerEnter={handlePointerEnter}
+      {...rest}
+    >
+      <span
+        ref={contentEl}
+        class="relative inline-flex items-center justify-center gap-2 will-change-transform"
+      >
+        {local.children}
+      </span>
+      <Show when={(local.effect ?? 'ring') === 'glare'}>
+        <span
+          ref={glareEl}
+          aria-hidden="true"
+          class="pointer-events-none absolute inset-y-0 left-0 w-1/3 -skew-x-12 bg-gradient-to-r from-transparent via-foreground/25 to-transparent opacity-0 will-change-transform"
+        />
+      </Show>
+    </button>
+  )
+}