@a4ui/core 0.32.0 → 0.34.0

package/src/ui/AudioWaveform.tsx

@@ -0,0 +1,190 @@
+// Bar-style audio waveform over a hidden native <audio> element — no media
+// library. When no real `peaks` are supplied, a deterministic placeholder
+// waveform is derived from the bar index (abs(sin(...)) blend) so the shape
+// is stable across renders instead of reshuffling on every re-render like
+// Math.random() would.
+import { Pause, Play } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createMemo, createSignal, For, onCleanup, onMount, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface AudioWaveformProps {
+  src?: string
+  peaks?: number[]
+  /** Bar row height in pixels. @default 64 */
+  height?: number
+  class?: string
+}
+
+const PLACEHOLDER_BAR_COUNT = 48
+// Demo progress rate (fraction of the fake "duration" per animation frame
+// tick) used only when there's no `src` to drive real audio playback.
+const DEMO_TICK_MS = 100
+const DEMO_STEP = 0.01
+
+/** Deterministic placeholder bar heights (0..1), no Math.random. */
+function placeholderPeaks(count: number): number[] {
+  return Array.from({ length: count }, (_, i) => {
+    const a = Math.abs(Math.sin(i * 0.35))
+    const b = Math.abs(Math.sin(i * 0.09 + 1.2))
+    return 0.15 + 0.85 * (0.65 * a + 0.35 * b)
+  })
+}
+
+/**
+ * Waveform of vertical bars driven by an optional hidden `<audio>` element.
+ * Pass `peaks` (numbers in `0..1`) for a real waveform, or omit it for a
+ * deterministic placeholder shape. The played portion (up to
+ * `currentTime / duration`) is highlighted; clicking a bar seeks there. With
+ * no `src`, playback is simulated on a timer for demo purposes.
+ *
+ * @example
+ * ```tsx
+ * <AudioWaveform src="/media/track.mp3" />
+ * <AudioWaveform peaks={[0.2, 0.8, 0.4, 0.9, 0.3]} height={48} />
+ * ```
+ */
+export function AudioWaveform(props: AudioWaveformProps): JSX.Element {
+  let audioRef: HTMLAudioElement | undefined
+
+  const [playing, setPlaying] = createSignal(false)
+  const [currentTime, setCurrentTime] = createSignal(0)
+  const [duration, setDuration] = createSignal(0)
+
+  const bars = createMemo(() => props.peaks ?? placeholderPeaks(PLACEHOLDER_BAR_COUNT))
+  const progress = createMemo(() => (duration() > 0 ? currentTime() / duration() : 0))
+  const barHeight = () => props.height ?? 64
+
+  const togglePlay = (): void => {
+    if (props.src) {
+      const audio = audioRef
+      if (!audio) return
+      if (audio.paused) void audio.play()
+      else audio.pause()
+      return
+    }
+    // No source: drive a fake demo progress instead of real playback.
+    setPlaying((p) => !p)
+  }
+
+  const seekToRatio = (ratio: number): void => {
+    const clamped = Math.min(Math.max(ratio, 0), 1)
+    if (props.src) {
+      const audio = audioRef
+      if (!audio || !duration()) return
+      audio.currentTime = clamped * duration()
+      return
+    }
+    setCurrentTime(clamped * (duration() || 1))
+  }
+
+  const handleBarClick = (index: number): void => {
+    seekToRatio((index + 0.5) / bars().length)
+  }
+
+  onMount(() => {
+    if (props.src) {
+      const audio = audioRef
+      if (!audio) return
+
+      const onPlay = (): void => {
+        setPlaying(true)
+      }
+      const onPause = (): void => {
+        setPlaying(false)
+      }
+      const onTimeUpdate = (): void => {
+        setCurrentTime(audio.currentTime)
+      }
+      const onLoadedMetadata = (): void => {
+        setDuration(audio.duration || 0)
+      }
+
+      audio.addEventListener('play', onPlay)
+      audio.addEventListener('pause', onPause)
+      audio.addEventListener('timeupdate', onTimeUpdate)
+      audio.addEventListener('loadedmetadata', onLoadedMetadata)
+
+      onCleanup(() => {
+        audio.removeEventListener('play', onPlay)
+        audio.removeEventListener('pause', onPause)
+        audio.removeEventListener('timeupdate', onTimeUpdate)
+        audio.removeEventListener('loadedmetadata', onLoadedMetadata)
+      })
+      return
+    }
+
+    // Demo mode: fake a duration and advance currentTime on an interval while playing.
+    setDuration(30)
+    const interval = setInterval(() => {
+      if (!playing() || motionReduced()) return
+      setCurrentTime((t) => {
+        const next = t + DEMO_STEP * duration()
+        if (next >= duration()) {
+          setPlaying(false)
+          return 0
+        }
+        return next
+      })
+    }, DEMO_TICK_MS)
+    onCleanup(() => clearInterval(interval))
+  })
+
+  return (
+    <div class={cn('card flex items-center gap-3 p-3', props.class)}>
+      <Show when={props.src}>
+        <audio ref={audioRef} src={props.src} />
+      </Show>
+
+      <button
+        type="button"
+        aria-label={playing() ? 'Pause' : 'Play'}
+        onClick={togglePlay}
+        class="flex h-9 w-9 shrink-0 items-center justify-center rounded-full bg-primary text-primary-foreground transition-transform duration-150 hover:scale-105 active:scale-95"
+      >
+        <Show when={playing()} fallback={<Play class="h-4 w-4 translate-x-0.5" fill="currentColor" />}>
+          <Pause class="h-4 w-4" fill="currentColor" />
+        </Show>
+      </button>
+
+      <div
+        role="slider"
+        aria-label="Waveform position"
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-valuenow={Math.round(progress() * 100)}
+        tabIndex={0}
+        class="flex flex-1 cursor-pointer items-center gap-[2px]"
+        style={{ height: `${barHeight()}px` }}
+        onClick={(event) => {
+          const rect = event.currentTarget.getBoundingClientRect()
+          seekToRatio((event.clientX - rect.left) / rect.width)
+        }}
+      >
+        <For each={bars()}>
+          {(peak, index) => {
+            const played = createMemo(() => index() / bars().length <= progress())
+            return (
+              <button
+                type="button"
+                aria-hidden="true"
+                tabIndex={-1}
+                onClick={(event) => {
+                  event.stopPropagation()
+                  handleBarClick(index())
+                }}
+                class={cn(
+                  'w-full min-w-[2px] flex-1 rounded-full transition-colors duration-150',
+                  played() ? 'bg-primary' : 'bg-muted',
+                )}
+                style={{ height: `${Math.max(peak, 0.06) * 100}%` }}
+              />
+            )
+          }}
+        </For>
+      </div>
+    </div>
+  )
+}

package/src/ui/Callout.tsx

@@ -0,0 +1,66 @@
+// Prose-embed highlight block for docs/guidance content. Distinct from Alert
+// (a dismissible notification banner): Callout sits inline in a body of text —
+// left accent border, tinted background, comfortable padding — and is never
+// dismissed. Tone tokens are shared with Alert so info/success/warning/danger
+// read identically across both components.
+import { CircleCheck, CircleX, Info, TriangleAlert } from 'lucide-solid'
+import type { Component, JSX } from 'solid-js'
+import { Show } from 'solid-js'
+import { Dynamic } from 'solid-js/web'
+
+import { cn } from '../lib/cn'
+
+/** Semantic tone of a {@link Callout}; drives the accent border, tint, and default icon. */
+export type CalloutTone = 'info' | 'success' | 'warning' | 'danger' | 'neutral'
+
+const TONE: Record<CalloutTone, { wrap: string; icon: string; Icon: Component<{ class?: string }> }> = {
+  info: { wrap: 'border-sky-500 bg-sky-500/10', icon: 'text-sky-500', Icon: Info },
+  success: { wrap: 'border-emerald-500 bg-emerald-500/10', icon: 'text-emerald-500', Icon: CircleCheck },
+  warning: { wrap: 'border-amber-500 bg-amber-500/10', icon: 'text-amber-500', Icon: TriangleAlert },
+  danger: { wrap: 'border-rose-500 bg-rose-500/10', icon: 'text-rose-500', Icon: CircleX },
+  neutral: { wrap: 'border-border bg-muted', icon: 'text-muted-foreground', Icon: Info },
+}
+
+export interface CalloutProps {
+  /** Visual/semantic tone. Defaults to `'info'`. */
+  tone?: 'info' | 'success' | 'warning' | 'danger' | 'neutral'
+  /** Optional bold heading shown above the body. */
+  title?: JSX.Element
+  /** Overrides the tone's default icon. */
+  icon?: JSX.Element
+  children: JSX.Element
+  class?: string
+}
+
+/**
+ * Inline highlighted block for embedding guidance/notes inside prose (docs,
+ * READMEs, long-form content) — a left accent border, a faint tone-tinted
+ * background, and an icon. Unlike {@link Alert} it isn't a dismissible
+ * notification; it's part of the content flow.
+ *
+ * @example
+ * ```tsx
+ * <Callout tone="warning" title="Before you continue">
+ *   This action can't be undone once the migration starts.
+ * </Callout>
+ * ```
+ */
+export function Callout(props: CalloutProps): JSX.Element {
+  const tone = () => TONE[props.tone ?? 'info']
+  return (
+    <div class={cn('flex gap-3 rounded-lg border-l-4 p-4 text-sm text-foreground', tone().wrap, props.class)}>
+      <Show
+        when={props.icon}
+        fallback={<Dynamic component={tone().Icon} class={cn('mt-0.5 h-4 w-4 shrink-0', tone().icon)} />}
+      >
+        {props.icon}
+      </Show>
+      <div class="flex-1">
+        <Show when={props.title}>
+          <p class="font-semibold">{props.title}</p>
+        </Show>
+        <div class="text-muted-foreground">{props.children}</div>
+      </div>
+    </div>
+  )
+}

package/src/ui/Confetti.tsx

@@ -0,0 +1,131 @@
+// Decorative confetti burst: a spawn-then-remove particle idiom (same as
+// Ripple.tsx) driven by the native Web Animations API — each piece is a
+// one-shot element with nothing for a JS animation engine to add. Angle and
+// velocity per piece are derived deterministically from the piece's index
+// (via Math.sin), not Math.random, so a burst is reproducible and doesn't
+// depend on an RNG.
+import { createEffect, on, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface ConfettiProps {
+  /** Bump this (e.g. a counter) to fire a burst. Mount does not count. */
+  trigger?: number
+  /** Number of pieces per burst. @default 80 */
+  count?: number
+  class?: string
+}
+
+const CONFETTI_COLORS = ['hsl(var(--primary))', 'hsl(var(--accent))', 'hsl(var(--foreground))']
+
+/**
+ * Fires one burst of confetti pieces from the bottom-center of `container`,
+ * flying up and outward in a fan, rotating, then falling with gravity and
+ * fading out — each piece removes itself once its animation finishes. Angle,
+ * speed, fall distance and spin are derived deterministically from each
+ * piece's index (Math.sin), so the same `count` always produces the same
+ * fan. `container` should be `position: relative` (or already positioned)
+ * with `overflow: hidden` so pieces don't affect layout. No-op under
+ * {@link motionReduced}. This is the primitive behind {@link Confetti}.
+ *
+ * @example
+ * ```ts
+ * fireConfetti(cardEl, { count: 120 })
+ * ```
+ */
+export function fireConfetti(container: HTMLElement, opts: { count?: number } = {}): void {
+  if (motionReduced()) return
+  const count = opts.count ?? 80
+  const rect = container.getBoundingClientRect()
+  const originX = rect.width / 2
+  const originY = rect.height
+
+  for (let i = 0; i < count; i++) {
+    // Fan the burst across a ~126° arc centered straight up; wobble is a
+    // deterministic pseudo-random 0..1 derived from the index.
+    const spread = Math.PI * 0.7
+    const wobble = Math.sin(i * 12.9898) * 0.5 + 0.5
+    const angle = -Math.PI / 2 + (wobble - 0.5) * spread
+    const speed = 180 + (Math.sin(i * 4.567) * 0.5 + 0.5) * 160
+    const dx = Math.cos(angle) * speed
+    const dy = Math.sin(angle) * speed
+    const fall = 200 + (Math.sin(i * 5.113) * 0.5 + 0.5) * 160
+    const rotation = 240 + (Math.sin(i * 3.377) * 0.5 + 0.5) * 640
+    const duration = 900 + (Math.sin(i * 2.1) * 0.5 + 0.5) * 500
+
+    const el = document.createElement('span')
+    el.setAttribute('aria-hidden', 'true')
+    Object.assign(el.style, {
+      position: 'absolute',
+      left: `${originX}px`,
+      top: `${originY}px`,
+      width: `${5 + (i % 3) * 2}px`,
+      height: `${10 + (i % 4) * 2}px`,
+      borderRadius: '1px',
+      background: CONFETTI_COLORS[i % CONFETTI_COLORS.length],
+      pointerEvents: 'none',
+    })
+    container.appendChild(el)
+
+    const animation = el.animate(
+      [
+        { transform: 'translate(-50%,-50%) translate(0px,0px) rotate(0deg)', opacity: '1' },
+        {
+          transform: `translate(-50%,-50%) translate(${dx * 0.7}px,${dy}px) rotate(${rotation * 0.5}deg)`,
+          opacity: '1',
+          offset: 0.45,
+        },
+        {
+          transform: `translate(-50%,-50%) translate(${dx}px,${dy + fall}px) rotate(${rotation}deg)`,
+          opacity: '0',
+        },
+      ],
+      { duration, easing: 'cubic-bezier(0.2, 0.6, 0.4, 1)' },
+    )
+    const done = (): void => el.remove()
+    animation.finished.then(done).catch(done)
+  }
+}
+
+/**
+ * Absolutely-positioned confetti layer: fires a burst of colored pieces from
+ * the bottom-center whenever `trigger` changes (the initial mount does not
+ * fire one). Purely decorative — `pointer-events-none` and `aria-hidden`.
+ * Place it inside a `position: relative` container; pair with a `count`
+ * prop, or reach for {@link fireConfetti} directly to fire into an
+ * arbitrary element outside Solid's render tree.
+ *
+ * @example
+ * ```tsx
+ * const [bursts, setBursts] = createSignal(0)
+ * return (
+ *   <div class="relative h-64">
+ *     <Confetti trigger={bursts()} count={100} />
+ *     <Button onClick={() => setBursts((n) => n + 1)}>Celebrate</Button>
+ *   </div>
+ * )
+ * ```
+ */
+export function Confetti(props: ConfettiProps): JSX.Element {
+  let containerEl: HTMLDivElement | undefined
+
+  createEffect(
+    on(
+      () => props.trigger,
+      () => {
+        if (!containerEl) return
+        fireConfetti(containerEl, { count: props.count })
+      },
+      { defer: true },
+    ),
+  )
+
+  return (
+    <div
+      ref={containerEl}
+      class={cn('absolute inset-0 overflow-hidden pointer-events-none', props.class)}
+      aria-hidden="true"
+    />
+  )
+}

package/src/ui/CouponField.tsx

@@ -0,0 +1,120 @@
+// Input + Apply button with explicit idle/loading/success/error states.
+// Rejected coupons surface as { ok: false } and render inline; unexpected
+// rejections from `onApply` are not caught here, so they propagate as
+// unhandled rejections instead of being silently swallowed.
+import { CircleCheck, X } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createSignal, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Button } from './Button'
+import { Input } from './Input'
+import { Spinner } from './Spinner'
+
+export interface CouponFieldProps {
+  /** Validate/apply a coupon code. Resolve with `{ ok: false }` for a rejected
+   * code — do not throw for expected rejections, only for unexpected failures. */
+  onApply: (code: string) => Promise<{ ok: boolean; message?: string; discount?: string }>
+  placeholder?: string
+  class?: string
+}
+
+type State =
+  | { status: 'idle' | 'loading' }
+  | { status: 'success'; code: string; discount?: string }
+  | { status: 'error'; message: string }
+
+/**
+ * Coupon/promo code input with an "Apply" button. Tracks explicit
+ * idle/loading/success/error state: loading shows a spinner and disables the
+ * input, success shows the applied discount with a way to remove it and try
+ * another code, error shows the failure message inline and lets the user retry.
+ * Rejections are read from the resolved `{ ok: false }` result, not caught
+ * exceptions — an unexpected throw from `onApply` propagates uncaught.
+ *
+ * @example
+ * ```tsx
+ * <CouponField
+ *   onApply={async (code) => {
+ *     const res = await api.applyCoupon(code)
+ *     return res.valid
+ *       ? { ok: true, discount: '-$10' }
+ *       : { ok: false, message: 'That code has expired.' }
+ *   }}
+ * />
+ * ```
+ */
+export function CouponField(props: CouponFieldProps): JSX.Element {
+  const [code, setCode] = createSignal('')
+  const [state, setState] = createSignal<State>({ status: 'idle' })
+
+  const apply = async (): Promise<void> => {
+    const value = code().trim()
+    if (!value || state().status === 'loading') return
+    setState({ status: 'loading' })
+    const result = await props.onApply(value)
+    if (result.ok) {
+      setState({ status: 'success', code: value, discount: result.discount })
+    } else {
+      setState({ status: 'error', message: result.message ?? 'This code could not be applied.' })
+    }
+  }
+
+  const remove = (): void => {
+    setCode('')
+    setState({ status: 'idle' })
+  }
+
+  const isLoading = () => state().status === 'loading'
+  const isSuccess = () => state().status === 'success'
+
+  return (
+    <div class={cn('flex flex-col gap-2', props.class)}>
+      <Show
+        when={!isSuccess()}
+        fallback={
+          <div class="flex items-center justify-between rounded-md border border-emerald-500/30 bg-emerald-500/10 px-3 py-2 text-sm">
+            <span class="flex items-center gap-2 text-emerald-500">
+              <CircleCheck class="h-4 w-4 shrink-0" />
+              <span class="text-foreground">
+                {(state() as { status: 'success'; code: string; discount?: string }).discount ?? 'Discount'}{' '}
+                applied
+              </span>
+            </span>
+            <button
+              type="button"
+              aria-label="Remove coupon"
+              onClick={remove}
+              class="text-muted-foreground hover:text-foreground"
+            >
+              <X class="h-4 w-4" />
+            </button>
+          </div>
+        }
+      >
+        <div class="flex gap-2">
+          <Input
+            value={code()}
+            onInput={setCode}
+            disabled={isLoading()}
+            placeholder={props.placeholder ?? 'Coupon code'}
+            onKeyDown={(ev) => {
+              if (ev.key === 'Enter') {
+                ev.preventDefault()
+                void apply()
+              }
+            }}
+          />
+          <Button variant="outline" disabled={isLoading() || !code().trim()} onClick={() => void apply()}>
+            <Show when={isLoading()} fallback="Apply">
+              <Spinner class="h-4 w-4" label="Applying coupon" />
+            </Show>
+          </Button>
+        </div>
+        <Show when={state().status === 'error'}>
+          <p class="text-sm text-destructive">{(state() as { status: 'error'; message: string }).message}</p>
+        </Show>
+      </Show>
+    </div>
+  )
+}

package/src/ui/CursorTrail.tsx

@@ -0,0 +1,88 @@
+// Decorative cursor trail: same spawn-then-remove particle idiom as
+// Ripple.tsx / Confetti.tsx, driven by the native Web Animations API. The
+// layer itself is pointer-events-none, so the listener lives on the
+// `relative` parent that hosts it.
+import { onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface CursorTrailProps {
+  /** Blob tone. @default 'primary' */
+  color?: 'primary' | 'accent'
+  /** Blob diameter in px. @default 24 */
+  size?: number
+  class?: string
+}
+
+const SPAWN_THROTTLE_MS = 20
+
+/**
+ * Layer that spawns a soft, blurred blob at the cursor position on every
+ * throttled `pointermove` over its parent, scaling down and fading out as
+ * it removes itself — leaving a trail. Must sit inside a `position:
+ * relative` parent (the layer listens on `parentElement`, since it is
+ * itself `pointer-events-none`). Purely decorative — `pointer-events-none`
+ * and `aria-hidden`. No-op under {@link motionReduced}; listeners are
+ * cleaned up on unmount.
+ *
+ * @example
+ * ```tsx
+ * <div class="relative h-48 rounded-lg border">
+ *   <CursorTrail color="accent" size={32} />
+ * </div>
+ * ```
+ */
+export function CursorTrail(props: CursorTrailProps): JSX.Element {
+  let layerEl: HTMLDivElement | undefined
+  let lastSpawn = 0
+
+  const handlePointerMove = (event: PointerEvent): void => {
+    if (motionReduced() || !layerEl) return
+    const now = performance.now()
+    if (now - lastSpawn < SPAWN_THROTTLE_MS) return
+    lastSpawn = now
+
+    const rect = layerEl.getBoundingClientRect()
+    const x = event.clientX - rect.left
+    const y = event.clientY - rect.top
+    const size = props.size ?? 24
+    const tone = props.color === 'accent' ? 'accent' : 'primary'
+
+    const el = document.createElement('span')
+    el.setAttribute('aria-hidden', 'true')
+    Object.assign(el.style, {
+      position: 'absolute',
+      left: `${x}px`,
+      top: `${y}px`,
+      width: `${size}px`,
+      height: `${size}px`,
+      borderRadius: '9999px',
+      background: `hsl(var(--${tone}) / 0.35)`,
+      filter: 'blur(6px)',
+      pointerEvents: 'none',
+      transform: 'translate(-50%,-50%) scale(1)',
+    })
+    layerEl.appendChild(el)
+
+    const animation = el.animate(
+      [
+        { transform: 'translate(-50%,-50%) scale(1)', opacity: '1' },
+        { transform: 'translate(-50%,-50%) scale(0.2)', opacity: '0' },
+      ],
+      { duration: 500, easing: 'ease-out' },
+    )
+    const done = (): void => el.remove()
+    animation.finished.then(done).catch(done)
+  }
+
+  onMount(() => {
+    const parent = layerEl?.parentElement
+    parent?.addEventListener('pointermove', handlePointerMove)
+    onCleanup(() => parent?.removeEventListener('pointermove', handlePointerMove))
+  })
+
+  return (
+    <div ref={layerEl} class={cn('absolute inset-0 pointer-events-none', props.class)} aria-hidden="true" />
+  )
+}