@a4ui/core 0.15.0 → 0.17.0

package/src/ui/FloatingActionButton.tsx

@@ -1,6 +1,7 @@
 import type { JSX } from 'solid-js'
 
 import { cn } from '../lib/cn'
+import { spawnRipple } from './Ripple'
 
 /** Screen corner a {@link FloatingActionButton} anchors to. Defaults to `'bottom-right'`. */
 export type FloatingActionButtonPosition = 'bottom-right' | 'bottom-left'
@@ -23,6 +24,12 @@ export interface FloatingActionButtonProps {
   onClick?: () => void
   /** Screen corner to anchor to. Defaults to `'bottom-right'`. */
   position?: FloatingActionButtonPosition
+  /**
+   * Material-style click ripple from the press position. Engine-free (Web
+   * Animations API, shared with {@link spawnRipple}) and reduced-motion aware —
+   * costs nothing when off.
+   */
+  ripple?: boolean
   class?: string
 }
 
@@ -40,7 +47,15 @@ export function FloatingActionButton(props: FloatingActionButtonProps): JSX.Elem
       type="button"
       aria-label={props.label}
       onClick={() => props.onClick?.()}
-      class={cn(FAB_BASE, POSITION_CLASSES[props.position ?? 'bottom-right'], props.class)}
+      onPointerDown={(event) => {
+        if (props.ripple) spawnRipple(event.currentTarget, event, { opacity: 0.35 })
+      }}
+      class={cn(
+        FAB_BASE,
+        POSITION_CLASSES[props.position ?? 'bottom-right'],
+        props.ripple && 'relative overflow-hidden',
+        props.class,
+      )}
     >
       {props.icon}
     </button>

package/src/ui/Image.tsx

@@ -8,6 +8,7 @@ import type { JSX } from 'solid-js'
 import { createSignal, Show } from 'solid-js'
 
 import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
 
 export interface ImageProps {
   src: string
@@ -15,6 +16,12 @@ export interface ImageProps {
   class?: string
   /** When true, clicking the image opens a zoomable lightbox. @default true */
   preview?: boolean
+  /**
+   * Reveal the thumbnail with a blur-up: it starts blurred and slightly scaled,
+   * then eases to sharp once the image finishes loading. Pure CSS transition,
+   * no-op under reduced motion. @default false
+   */
+  blurUp?: boolean
 }
 
 /**
@@ -32,8 +39,29 @@ export function Image(props: ImageProps): JSX.Element {
   const [open, setOpen] = createSignal(false)
   const preview = () => props.preview !== false
 
+  // blur-up: hidden behind the blur until `load` fires (or immediately, if the
+  // image is already cached or reduced motion is on).
+  const [loaded, setLoaded] = createSignal(false)
+  const blurUp = () => props.blurUp === true && !motionReduced()
+  const revealed = () => !blurUp() || loaded()
+
   const img = (
-    <img src={props.src} alt={props.alt} loading="lazy" class={cn('rounded-lg object-cover', props.class)} />
+    <img
+      src={props.src}
+      alt={props.alt}
+      loading="lazy"
+      onLoad={() => setLoaded(true)}
+      ref={(el) => {
+        // A cached image can be complete before `onLoad` binds — reveal it now.
+        if (el.complete) setLoaded(true)
+      }}
+      class={cn(
+        'rounded-lg object-cover',
+        blurUp() && 'transition-[filter,transform] duration-500 ease-out',
+        blurUp() && !revealed() && 'scale-[1.03] blur-lg',
+        props.class,
+      )}
+    />
   )
 
   return (

package/src/ui/List.tsx

@@ -16,6 +16,11 @@ export interface ListItem {
 
 interface ListProps {
   items: ListItem[]
+  /**
+   * Cascade the rows in on mount — each row fades/slides up staggered by its
+   * index. Pure CSS (`list-row-stagger`), reduced-motion aware. @default false
+   */
+  stagger?: boolean
   class?: string
 }
 
@@ -46,8 +51,11 @@ export function List(props: ListProps): JSX.Element {
   return (
     <ul class={cn('divide-y divide-border rounded-lg border border-border', props.class)}>
       <For each={props.items}>
-        {(item) => (
-          <li class="flex items-center gap-3 px-4 py-3">
+        {(item, i) => (
+          <li
+            class={cn('flex items-center gap-3 px-4 py-3', props.stagger && 'list-row-stagger')}
+            style={props.stagger ? { 'animation-delay': `${i() * 60}ms` } : undefined}
+          >
             <Show when={item.avatar}>
               <div class="shrink-0">{item.avatar}</div>
             </Show>

package/src/ui/Ripple.tsx

@@ -1,15 +1,13 @@
-// Material-style click ripple: a wrapper that spawns an expanding, fading
-// circle from the pointer's down position on every `pointerdown` — Motion's
-// `animate` drives the scale/opacity tween since each ripple is a one-shot
-// spawn-then-discard element, not a persistent CSS transition. `x`/`y` are
-// animated to a constant -50% alongside `scale` so Motion (which owns the
-// element's `transform` once it's animating any transform sub-property)
-// composes `translate(-50%,-50%) scale(...)` itself rather than clobbering a
-// translate we'd otherwise have set by hand via inline style.
-import { createSignal, For, onCleanup, type JSX } from 'solid-js'
+// Material-style click ripple: an expanding, fading circle from the pointer's
+// down position on every `pointerdown`. The tween is driven by the native Web
+// Animations API (el.animate) — each ripple is a one-shot spawn-then-discard
+// element, so there's nothing for a JS animation engine to add. Being
+// engine-free is deliberate: it lets <Button ripple> bake this in without
+// pulling the `motion` package into every Button consumer's bundle.
+import { type JSX } from 'solid-js'
 
 import { cn } from '../lib/cn'
-import { animate, motionReduced } from '../lib/motion'
+import { motionReduced } from '../lib/motion'
 
 export interface RippleProps {
   children: JSX.Element
@@ -20,14 +18,58 @@ export interface RippleProps {
   class?: string
 }
 
-interface RippleInstance {
-  id: number
-  x: number
-  y: number
-  size: number
-}
+/**
+ * Spawns one Material-style ripple inside `container` at the pointer's
+ * position, expanding to cover the container and fading out, then removes
+ * itself. The container must be `position: relative; overflow: hidden`.
+ * Engine-free (Web Animations API); no-op under reduced motion. This is the
+ * primitive behind {@link Ripple} and `<Button ripple>`.
+ */
+export function spawnRipple(
+  container: HTMLElement,
+  event: PointerEvent,
+  opts: { color?: string; opacity?: number } = {},
+): void {
+  if (motionReduced()) return
+  const rect = container.getBoundingClientRect()
+  const x = event.clientX - rect.left
+  const y = event.clientY - rect.top
+  // Diameter = 2× the distance to the farthest corner, so the circle always
+  // covers the whole container from wherever the press landed.
+  const size =
+    2 *
+    Math.max(
+      Math.hypot(x, y),
+      Math.hypot(rect.width - x, y),
+      Math.hypot(x, rect.height - y),
+      Math.hypot(rect.width - x, rect.height - y),
+    )
 
-let nextRippleId = 0
+  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: opts.color ?? 'currentColor',
+    pointerEvents: 'none',
+    transform: 'translate(-50%,-50%) scale(0)',
+  })
+  container.appendChild(el)
+
+  const animation = el.animate(
+    [
+      { transform: 'translate(-50%,-50%) scale(0)', opacity: String(opts.opacity ?? 0.3) },
+      { transform: 'translate(-50%,-50%) scale(1)', opacity: '0' },
+    ],
+    { duration: 600, easing: 'ease-out' },
+  )
+  const done = (): void => el.remove()
+  animation.finished.then(done).catch(done)
+}
 
 /**
  * Wraps `children` in a `position: relative; overflow: hidden` layer that
@@ -37,59 +79,23 @@ let nextRippleId = 0
  * itself once its animation finishes. A no-op under reduced motion: children
  * still render, but no ripple ever spawns.
  *
+ * Buttons don't need the wrapper — use `<Button ripple>` instead.
+ *
  * @example
  * ```tsx
  * <Ripple color="white" opacity={0.25}>
- *   <button class="rounded-lg bg-primary px-4 py-2 text-primary-foreground">Save</button>
+ *   <div class="rounded-lg bg-primary px-4 py-2 text-primary-foreground">Save</div>
  * </Ripple>
  * ```
  */
 export function Ripple(props: RippleProps): JSX.Element {
-  const [ripples, setRipples] = createSignal<RippleInstance[]>([])
-  const active = new Set<ReturnType<typeof animate>>()
-
   let containerEl: HTMLSpanElement | undefined
 
-  const remove = (id: number): void => {
-    setRipples((current) => current.filter((ripple) => ripple.id !== id))
-  }
-
-  const spawnAnimation = (el: HTMLSpanElement, id: number, opacity: number): void => {
-    const controls = animate(
-      el,
-      { x: ['-50%', '-50%'], y: ['-50%', '-50%'], scale: [0, 1], opacity: [opacity, 0] },
-      { duration: 0.6, ease: 'easeOut' },
-    )
-    active.add(controls)
-    controls.finished
-      .then(() => {
-        active.delete(controls)
-        remove(id)
-      })
-      .catch(() => {})
-  }
-
   const handlePointerDown = (event: PointerEvent): void => {
-    if (motionReduced() || !containerEl) return
-
-    const rect = containerEl.getBoundingClientRect()
-    const x = event.clientX - rect.left
-    const y = event.clientY - rect.top
-    const maxDist = Math.max(
-      Math.hypot(x, y),
-      Math.hypot(rect.width - x, y),
-      Math.hypot(x, rect.height - y),
-      Math.hypot(rect.width - x, rect.height - y),
-    )
-
-    setRipples((current) => [...current, { id: nextRippleId++, x, y, size: maxDist * 2 }])
+    if (!containerEl) return
+    spawnRipple(containerEl, event, { color: props.color, opacity: props.opacity })
   }
 
-  onCleanup(() => {
-    active.forEach((controls) => controls.stop())
-    active.clear()
-  })
-
   return (
     <span
       ref={containerEl}
@@ -97,23 +103,6 @@ export function Ripple(props: RippleProps): JSX.Element {
       onPointerDown={handlePointerDown}
     >
       {props.children}
-      <span aria-hidden="true" class="pointer-events-none absolute inset-0">
-        <For each={ripples()}>
-          {(ripple) => (
-            <span
-              ref={(el) => spawnAnimation(el, ripple.id, props.opacity ?? 0.3)}
-              class="absolute rounded-full"
-              style={{
-                left: `${ripple.x}px`,
-                top: `${ripple.y}px`,
-                width: `${ripple.size}px`,
-                height: `${ripple.size}px`,
-                background: props.color ?? 'currentColor',
-              }}
-            />
-          )}
-        </For>
-      </span>
     </span>
   )
 }

package/src/ui/Skeleton.tsx

@@ -1,4 +1,5 @@
-// Pulsing placeholder for loading content — plain div, no primitive.
+// Placeholder for loading content — plain div, no primitive. Pulses by default;
+// opt into a sweeping shimmer band with `shimmer`.
 import type { JSX } from 'solid-js'
 
 import { cn } from '../lib/cn'
@@ -6,18 +7,29 @@ import { cn } from '../lib/cn'
 interface SkeletonProps {
   /** Size/shape the placeholder to match the content it stands in for, e.g. `"h-4 w-32 rounded-full"`. */
   class?: string
+  /**
+   * Use a light band sweeping across the placeholder instead of the default
+   * pulse. Pure CSS (`.skeleton-shimmer`), token-tinted, reduced-motion aware.
+   */
+  shimmer?: boolean
 }
 
 /**
- * Pulsing placeholder block for content that is still loading. Plain `div`,
- * no Kobalte primitive — size it via `class` to match the shape of the real
- * content (text line, avatar, card, etc.).
+ * Placeholder block for content that is still loading. Plain `div`, no Kobalte
+ * primitive — size it via `class` to match the shape of the real content (text
+ * line, avatar, card, etc.). Pulses by default; pass `shimmer` for a sweeping
+ * light band instead.
  *
  * @example
  * ```tsx
  * <Skeleton class="h-4 w-48" />
+ * <Skeleton shimmer class="h-4 w-48" /> // sweeping band instead of pulse
  * ```
  */
 export function Skeleton(props: SkeletonProps): JSX.Element {
-  return <div class={cn('animate-pulse rounded-md bg-muted', props.class)} />
+  return (
+    <div
+      class={cn('rounded-md bg-muted', props.shimmer ? 'skeleton-shimmer' : 'animate-pulse', props.class)}
+    />
+  )
 }

package/src/ui/SpeedDial.tsx

@@ -5,6 +5,7 @@ import { createSignal, For, Show } from 'solid-js'
 
 import { cn } from '../lib/cn'
 import { animate, motionReduced } from '../lib/motion'
+import { spawnRipple } from './Ripple'
 
 /** A single action in a {@link SpeedDial} — an icon button with an accessible label. */
 export interface SpeedDialAction {
@@ -74,7 +75,8 @@ export function SpeedDial(props: SpeedDialProps): JSX.Element {
         aria-label={open() ? 'Close actions' : 'Open actions'}
         aria-expanded={open()}
         onClick={() => setOpen((v) => !v)}
-        class="flex h-14 w-14 items-center justify-center rounded-full bg-primary text-primary-foreground shadow-lg transition-transform duration-150 active:scale-[0.97] focus:outline-none focus:ring-2 focus:ring-ring"
+        onPointerDown={(event) => spawnRipple(event.currentTarget, event, { opacity: 0.35 })}
+        class="relative flex h-14 w-14 items-center justify-center overflow-hidden rounded-full bg-primary text-primary-foreground shadow-lg transition-transform duration-150 active:scale-[0.97] focus:outline-none focus:ring-2 focus:ring-ring"
       >
         <span class={cn('inline-flex transition-transform duration-150', open() && 'rotate-45')}>
           {props.icon ?? <Plus class="h-6 w-6" />}

package/src/ui/Spotlight.tsx

@@ -2,7 +2,8 @@
 // element, like a light hovering over the surface. This is a plain CSS
 // follow (the overlay's `background` is written directly on pointermove)
 // rather than a Motion tween: a radial-gradient position update has no
-// transform to spring, so there's nothing for Motion to add here. Only the
+// transform to spring, so there's nothing for an animation engine to add.
+// Engine-free, which lets <Card spotlight> bake it in for free. Only the
 // fade in/out on enter/leave uses a CSS `transition: opacity`. No-op (no
 // glow, children still render) under reduced motion.
 import { onCleanup, onMount, type JSX } from 'solid-js'
@@ -19,11 +20,56 @@ export interface SpotlightProps {
   class?: string
 }
 
+/**
+ * Appends a cursor-following radial-glow overlay inside `el` (which must be
+ * `position: relative; overflow: hidden`) and binds the pointer handlers.
+ * Returns a cleanup that unbinds and removes the overlay. Engine-free; no-op
+ * under reduced motion. This is the primitive behind {@link Spotlight} and
+ * `<Card spotlight>`.
+ */
+export function attachSpotlight(el: HTMLElement, opts: { color?: string; size?: number } = {}): () => void {
+  if (motionReduced()) return () => {}
+
+  const overlay = document.createElement('span')
+  overlay.setAttribute('aria-hidden', 'true')
+  overlay.className = 'pointer-events-none absolute inset-0 opacity-0 transition-opacity duration-300'
+  el.appendChild(overlay)
+
+  const size = opts.size ?? 180
+  const color = opts.color ?? 'hsl(var(--primary))'
+
+  const paint = (x: number, y: number): void => {
+    overlay.style.background = `radial-gradient(${size}px circle at ${x}px ${y}px, color-mix(in srgb, ${color} 30%, transparent), transparent 70%)`
+  }
+  const handlePointerMove = (event: PointerEvent): void => {
+    const rect = el.getBoundingClientRect()
+    paint(event.clientX - rect.left, event.clientY - rect.top)
+  }
+  const handlePointerEnter = (): void => {
+    overlay.style.opacity = '1'
+  }
+  const handlePointerLeave = (): void => {
+    overlay.style.opacity = '0'
+  }
+
+  el.addEventListener('pointermove', handlePointerMove)
+  el.addEventListener('pointerenter', handlePointerEnter)
+  el.addEventListener('pointerleave', handlePointerLeave)
+  return () => {
+    el.removeEventListener('pointermove', handlePointerMove)
+    el.removeEventListener('pointerenter', handlePointerEnter)
+    el.removeEventListener('pointerleave', handlePointerLeave)
+    overlay.remove()
+  }
+}
+
 /**
  * Wraps `children` in a `position: relative; overflow: hidden` layer with a
  * radial glow that tracks the cursor, fading in on pointerenter and out on
- * pointerleave. Children render above the glow. Respects
- * `prefers-reduced-motion` (renders children with no glow at all).
+ * pointerleave. Children render below the (pointer-transparent) glow.
+ * Respects `prefers-reduced-motion` (renders children with no glow at all).
+ *
+ * A4ui's own `Card` can do this without the wrapper — `<Card spotlight>`.
  *
  * @example
  * ```tsx
@@ -34,50 +80,15 @@ export interface SpotlightProps {
  */
 export function Spotlight(props: SpotlightProps): JSX.Element {
   let root!: HTMLDivElement
-  let overlay!: HTMLSpanElement
 
   onMount(() => {
-    if (motionReduced()) return
-
-    const size = props.size ?? 180
-    const color = props.color ?? 'hsl(var(--primary))'
-
-    const paint = (x: number, y: number): void => {
-      overlay.style.background = `radial-gradient(${size}px circle at ${x}px ${y}px, color-mix(in srgb, ${color} 30%, transparent), transparent 70%)`
-    }
-
-    const handlePointerMove = (event: PointerEvent): void => {
-      const rect = root.getBoundingClientRect()
-      paint(event.clientX - rect.left, event.clientY - rect.top)
-    }
-
-    const handlePointerEnter = (): void => {
-      overlay.style.opacity = '1'
-    }
-
-    const handlePointerLeave = (): void => {
-      overlay.style.opacity = '0'
-    }
-
-    root.addEventListener('pointermove', handlePointerMove)
-    root.addEventListener('pointerenter', handlePointerEnter)
-    root.addEventListener('pointerleave', handlePointerLeave)
-
-    onCleanup(() => {
-      root.removeEventListener('pointermove', handlePointerMove)
-      root.removeEventListener('pointerenter', handlePointerEnter)
-      root.removeEventListener('pointerleave', handlePointerLeave)
-    })
+    const cleanup = attachSpotlight(root, { color: props.color, size: props.size })
+    onCleanup(cleanup)
   })
 
   return (
     <div ref={root} class={cn('relative overflow-hidden', props.class)}>
       {props.children}
-      <span
-        ref={overlay}
-        aria-hidden="true"
-        class="pointer-events-none absolute inset-0 opacity-0 transition-opacity duration-300"
-      />
     </div>
   )
 }

package/src/ui/TiltCard.tsx

@@ -1,12 +1,12 @@
 // TiltCard — tilts its wrapped content in 3D toward the cursor on hover, like
-// a card catching the light. The outer element sets the CSS perspective; the
-// inner element (which actually rotates) gets `transform-style: preserve-3d`
-// so nested content keeps its own depth. Motion's `animate` drives the
-// rotate/scale as a spring. No-op (static) under reduced motion.
+// a card catching the light. The tilt is a direct transform smoothed by a CSS
+// transition (engine-free — no `motion` dependency), which keeps it cheap
+// enough for <Card tilt> to bake in without growing every Card consumer's
+// bundle. No-op (static) under reduced motion.
 import { onCleanup, onMount, type JSX } from 'solid-js'
 
 import { cn } from '../lib/cn'
-import { animate, motionReduced } from '../lib/motion'
+import { motionReduced } from '../lib/motion'
 
 export interface TiltCardProps {
   children: JSX.Element
@@ -15,12 +15,54 @@ export interface TiltCardProps {
   class?: string
 }
 
+/**
+ * Binds a cursor-following 3D tilt: pointer moves over `listenEl` rotate
+ * `animEl` toward the cursor (clamped to `max` degrees) with a slight lift,
+ * easing back flat on pointerleave. Returns a cleanup that unbinds and clears
+ * the transform. Engine-free (CSS transitions); no-op under reduced motion.
+ * This is the primitive behind {@link TiltCard} and `<Card tilt>` — pass the
+ * same element twice to tilt the element the pointer is over.
+ */
+export function attachTilt(
+  listenEl: HTMLElement,
+  animEl: HTMLElement,
+  opts: { max?: number } = {},
+): () => void {
+  if (motionReduced()) return () => {}
+  animEl.style.willChange = 'transform'
+
+  const move = (event: PointerEvent): void => {
+    const rect = listenEl.getBoundingClientRect()
+    const nx = (event.clientX - rect.left) / rect.width - 0.5
+    const ny = (event.clientY - rect.top) / rect.height - 0.5
+    const max = opts.max ?? 10
+    animEl.style.transition = 'transform 0.15s ease-out'
+    animEl.style.transform = `perspective(800px) rotateX(${(ny * -2 * max).toFixed(2)}deg) rotateY(${(nx * 2 * max).toFixed(2)}deg) scale(1.02)`
+  }
+  const leave = (): void => {
+    animEl.style.transition = 'transform 0.4s ease'
+    animEl.style.transform = 'perspective(800px) rotateX(0deg) rotateY(0deg) scale(1)'
+  }
+
+  listenEl.addEventListener('pointermove', move)
+  listenEl.addEventListener('pointerleave', leave)
+  return () => {
+    listenEl.removeEventListener('pointermove', move)
+    listenEl.removeEventListener('pointerleave', leave)
+    animEl.style.transform = ''
+    animEl.style.transition = ''
+    animEl.style.willChange = ''
+  }
+}
+
 /**
  * Wraps `children` in a card that tilts in 3D toward the cursor: as the
  * pointer moves within its bounds, the card rotates on both axes (clamped to
- * `max` degrees) and lifts slightly, springing back flat on pointerleave.
+ * `max` degrees) and lifts slightly, easing back flat on pointerleave.
  * Respects `prefers-reduced-motion` (renders static).
  *
+ * A4ui's own `Card` can do this without the wrapper — `<Card tilt>`.
+ *
  * @example
  * ```tsx
  * <TiltCard max={12}>
@@ -33,46 +75,13 @@ export function TiltCard(props: TiltCardProps): JSX.Element {
   let inner!: HTMLDivElement
 
   onMount(() => {
-    if (motionReduced()) return
-
-    let controls: ReturnType<typeof animate> | undefined
-
-    const handlePointerMove = (event: PointerEvent): void => {
-      const rect = root.getBoundingClientRect()
-      const nx = (event.clientX - rect.left) / rect.width - 0.5
-      const ny = (event.clientY - rect.top) / rect.height - 0.5
-      const max = props.max ?? 10
-
-      controls?.stop()
-      controls = animate(
-        inner,
-        { rotateX: ny * -2 * max, rotateY: nx * 2 * max, scale: 1.02 },
-        { type: 'spring', stiffness: 300, damping: 20 },
-      )
-    }
-
-    const handlePointerLeave = (): void => {
-      controls?.stop()
-      controls = animate(
-        inner,
-        { rotateX: 0, rotateY: 0, scale: 1 },
-        { type: 'spring', stiffness: 300, damping: 20 },
-      )
-    }
-
-    root.addEventListener('pointermove', handlePointerMove)
-    root.addEventListener('pointerleave', handlePointerLeave)
-
-    onCleanup(() => {
-      root.removeEventListener('pointermove', handlePointerMove)
-      root.removeEventListener('pointerleave', handlePointerLeave)
-      controls?.stop()
-    })
+    const cleanup = attachTilt(root, inner, { max: props.max })
+    onCleanup(cleanup)
   })
 
   return (
     <div ref={root} class={cn('inline-block', props.class)} style={{ perspective: '800px' }}>
-      <div ref={inner} class="will-change-transform" style={{ 'transform-style': 'preserve-3d' }}>
+      <div ref={inner} style={{ 'transform-style': 'preserve-3d' }}>
         {props.children}
       </div>
     </div>