@a4ui/core 0.15.0 → 0.16.0

package/dist/ui/Button.d.ts

@@ -7,6 +7,12 @@ interface ButtonProps extends ParentProps, Omit<JSX.ButtonHTMLAttributes<HTMLBut
     class?: string;
     /** Defaults to "button" so action buttons inside a form never submit it by accident. */
     type?: 'button' | 'submit' | 'reset';
+    /**
+     * 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;
 }
 /**
  * Base button primitive: a plain `<button>` with A4ui's variants, focus ring,
@@ -15,6 +21,7 @@ interface ButtonProps extends ParentProps, Omit<JSX.ButtonHTMLAttributes<HTMLBut
  * @example
  * ```tsx
  * <Button variant="outline" onClick={() => save()}>Save</Button>
+ * <Button ripple onClick={() => save()}>Save</Button> // with a click ripple
  * ```
  */
 export declare function Button(props: ButtonProps): JSX.Element;

package/dist/ui/Card.d.ts

@@ -10,15 +10,29 @@ interface CardProps extends DivProps {
      * for glass cards so the look is uniform; pass `glow={false}` to opt out.
      */
     glow?: boolean;
+    /**
+     * 3D tilt toward the cursor on hover — the same primitive as `<TiltCard>`,
+     * baked in ({@link attachTilt}). Engine-free and reduced-motion aware.
+     */
+    tilt?: boolean;
+    /**
+     * Soft radial glow following the cursor inside the card — the same primitive
+     * as `<Spotlight>`, baked in ({@link attachSpotlight}). Engine-free and
+     * reduced-motion aware.
+     */
+    spotlight?: boolean;
 }
 /**
  * Container surface for grouping related content, with an optional frosted
  * "space glass" look. Compose with {@link CardHeader}, {@link CardTitle}, and
  * {@link CardContent}.
  *
+ * `tilt` and `spotlight` bake in the cursor interactions from the Motion
+ * category — no wrapper components needed.
+ *
  * @example
  * ```tsx
- * <Card glass>
+ * <Card glass tilt spotlight>
  *   <CardHeader>
  *     <CardTitle>Usage</CardTitle>
  *   </CardHeader>

package/dist/ui/Ripple.d.ts

@@ -7,6 +7,17 @@ export interface RippleProps {
     opacity?: number;
     class?: string;
 }
+/**
+ * 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 declare function spawnRipple(container: HTMLElement, event: PointerEvent, opts?: {
+    color?: string;
+    opacity?: number;
+}): void;
 /**
  * Wraps `children` in a `position: relative; overflow: hidden` layer that
  * spawns a Material-style ripple — a circle centered on the pointer's down
@@ -15,10 +26,12 @@ export interface RippleProps {
  * 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>
  * ```
  */

package/dist/ui/Spotlight.d.ts

@@ -7,11 +7,24 @@ export interface SpotlightProps {
     size?: number;
     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 declare function attachSpotlight(el: HTMLElement, opts?: {
+    color?: string;
+    size?: number;
+}): () => void;
 /**
  * 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

package/dist/ui/TiltCard.d.ts

@@ -5,12 +5,25 @@ export interface TiltCardProps {
     max?: number;
     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 declare function attachTilt(listenEl: HTMLElement, animEl: HTMLElement, opts?: {
+    max?: number;
+}): () => void;
 /**
  * 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}>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a4ui/core",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "A4ui — Spatial Glass design system & component library for SolidJS (Kobalte behavior + Tailwind glass tokens + motion).",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -8,7 +8,7 @@
 //   import '@a4ui/core/styles.css'
 //   import { Button, Card, Modal } from '@a4ui/core'
 
-export const A4UI_VERSION = '0.15.0'
+export const A4UI_VERSION = '0.16.0'
 
 // Helpers (src/lib) — generic, framework-level utilities.
 export { cn } from './lib/cn'
@@ -150,10 +150,10 @@ export { MultiStateBadge, type MultiStateBadgeProps, type BadgeState } from './u
 export { NowPlaying, type NowPlayingProps } from './ui/NowPlaying'
 export { Expandable, type ExpandableProps } from './ui/Expandable'
 export { Typewriter, type TypewriterProps } from './ui/Typewriter'
-export { Ripple, type RippleProps } from './ui/Ripple'
+export { Ripple, spawnRipple, type RippleProps } from './ui/Ripple'
 export { Magnetic, type MagneticProps } from './ui/Magnetic'
-export { TiltCard, type TiltCardProps } from './ui/TiltCard'
-export { Spotlight, type SpotlightProps } from './ui/Spotlight'
+export { TiltCard, attachTilt, type TiltCardProps } from './ui/TiltCard'
+export { Spotlight, attachSpotlight, type SpotlightProps } from './ui/Spotlight'
 export { ScrollProgress, type ScrollProgressProps } from './ui/ScrollProgress'
 export { GradientText, type GradientTextProps } from './ui/GradientText'
 export { flyToCart, type FlyToCartOptions } from './lib/flyToCart'

package/src/ui/Button.tsx

@@ -2,6 +2,7 @@ import type { JSX, ParentProps } from 'solid-js'
 import { splitProps } from 'solid-js'
 
 import { cn } from '../lib/cn'
+import { spawnRipple } from './Ripple'
 
 /** Visual style of a {@link Button}. Defaults to `'primary'`. */
 export type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost'
@@ -24,6 +25,12 @@ interface ButtonProps extends ParentProps, Omit<JSX.ButtonHTMLAttributes<HTMLBut
   class?: string
   /** Defaults to "button" so action buttons inside a form never submit it by accident. */
   type?: 'button' | 'submit' | 'reset'
+  /**
+   * 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
 }
 
 /**
@@ -33,14 +40,29 @@ interface ButtonProps extends ParentProps, Omit<JSX.ButtonHTMLAttributes<HTMLBut
  * @example
  * ```tsx
  * <Button variant="outline" onClick={() => save()}>Save</Button>
+ * <Button ripple onClick={() => save()}>Save</Button> // with a click ripple
  * ```
  */
 export function Button(props: ButtonProps): JSX.Element {
-  const [local, rest] = splitProps(props, ['variant', 'class', 'type', 'children'])
+  const [local, rest] = splitProps(props, ['variant', 'class', 'type', 'children', 'ripple', 'onPointerDown'])
+
+  const handlePointerDown: JSX.EventHandler<HTMLButtonElement, PointerEvent> = (event) => {
+    if (local.ripple) spawnRipple(event.currentTarget, event, { opacity: 0.35 })
+    const user = local.onPointerDown
+    if (typeof user === 'function') user(event)
+    else if (user) user[0](user[1], event)
+  }
+
   return (
     <button
       type={local.type ?? 'button'}
-      class={cn(BUTTON_BASE, VARIANT_CLASSES[local.variant ?? 'primary'], local.class)}
+      class={cn(
+        BUTTON_BASE,
+        VARIANT_CLASSES[local.variant ?? 'primary'],
+        local.ripple && 'relative overflow-hidden',
+        local.class,
+      )}
+      onPointerDown={handlePointerDown}
       {...rest}
     >
       {local.children}

package/src/ui/Card.tsx

@@ -1,8 +1,10 @@
 // Card + 4 sub-parts (no CardFooter/CardDescription — add if needed).
 import type { JSX, ParentProps } from 'solid-js'
-import { splitProps } from 'solid-js'
+import { onCleanup, onMount, splitProps } from 'solid-js'
 
 import { cn } from '../lib/cn'
+import { attachSpotlight } from './Spotlight'
+import { attachTilt } from './TiltCard'
 
 interface DivProps extends ParentProps {
   class?: string
@@ -16,6 +18,17 @@ interface CardProps extends DivProps {
    * for glass cards so the look is uniform; pass `glow={false}` to opt out.
    */
   glow?: boolean
+  /**
+   * 3D tilt toward the cursor on hover — the same primitive as `<TiltCard>`,
+   * baked in ({@link attachTilt}). Engine-free and reduced-motion aware.
+   */
+  tilt?: boolean
+  /**
+   * Soft radial glow following the cursor inside the card — the same primitive
+   * as `<Spotlight>`, baked in ({@link attachSpotlight}). Engine-free and
+   * reduced-motion aware.
+   */
+  spotlight?: boolean
 }
 
 /**
@@ -23,9 +36,12 @@ interface CardProps extends DivProps {
  * "space glass" look. Compose with {@link CardHeader}, {@link CardTitle}, and
  * {@link CardContent}.
  *
+ * `tilt` and `spotlight` bake in the cursor interactions from the Motion
+ * category — no wrapper components needed.
+ *
  * @example
  * ```tsx
- * <Card glass>
+ * <Card glass tilt spotlight>
  *   <CardHeader>
  *     <CardTitle>Usage</CardTitle>
  *   </CardHeader>
@@ -34,16 +50,29 @@ interface CardProps extends DivProps {
  * ```
  */
 export function Card(props: CardProps): JSX.Element {
-  const [local, rest] = splitProps(props, ['class', 'children', 'glass', 'glow'])
+  const [local, rest] = splitProps(props, ['class', 'children', 'glass', 'glow', 'tilt', 'spotlight'])
   // Glow defaults to the card's glass state when not explicitly set.
   const showGlow = () => (local.glow ?? local.glass) === true
+
+  let el: HTMLDivElement | undefined
+  onMount(() => {
+    const cleanups = [
+      local.tilt && el ? attachTilt(el, el) : null,
+      local.spotlight && el ? attachSpotlight(el) : null,
+    ].filter((f): f is () => void => f !== null)
+    onCleanup(() => cleanups.forEach((f) => f()))
+  })
+
   return (
     <div
+      ref={el}
       class={cn(
         local.glass
           ? 'card rounded-xl text-card-foreground'
           : 'rounded-xl border border-border bg-card text-card-foreground shadow-sm',
         showGlow() && 'glow-edge',
+        local.spotlight && 'relative overflow-hidden',
+        local.tilt && 'will-change-transform',
         local.class,
       )}
       {...rest}

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