@a4ui/core 0.14.1 → 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/GradientText.d.ts

@@ -0,0 +1,25 @@
+import { JSX } from 'solid-js';
+export interface GradientTextProps {
+    children: JSX.Element;
+    /** CSS gradient color stop at 0%. @default 'hsl(var(--primary))' */
+    from?: string;
+    /** CSS gradient color stop at 50%. @default 'hsl(var(--accent))' */
+    via?: string;
+    /** CSS gradient color stop at 100%. @default 'hsl(var(--primary))' */
+    to?: string;
+    /** Seconds per loop. @default 4 */
+    duration?: number;
+    class?: string;
+}
+/**
+ * Renders `children` clipped to a horizontal gradient whose position sweeps
+ * back and forth in a loop, for eye-catching headings. Respects
+ * `prefers-reduced-motion` by rendering a static gradient instead of
+ * animating.
+ *
+ * @example
+ * ```tsx
+ * <GradientText duration={6}>Sonora Precision</GradientText>
+ * ```
+ */
+export declare function GradientText(props: GradientTextProps): JSX.Element;

package/dist/ui/Magnetic.d.ts

@@ -0,0 +1,22 @@
+import { JSX } from 'solid-js';
+export interface MagneticProps {
+    children: JSX.Element;
+    /** Max px the element travels toward the cursor. @default 12 */
+    strength?: number;
+    class?: string;
+}
+/**
+ * Wraps `children` in an element that's magnetically drawn toward the
+ * cursor: as the pointer moves within its bounds, the element translates a
+ * fraction of the way toward it (clamped to `strength` px), springing back
+ * to rest on pointerleave. Respects `prefers-reduced-motion` (renders
+ * static).
+ *
+ * @example
+ * ```tsx
+ * <Magnetic strength={16}>
+ *   <button class="rounded-full bg-primary px-6 py-3 text-primary-foreground">Hover me</button>
+ * </Magnetic>
+ * ```
+ */
+export declare function Magnetic(props: MagneticProps): JSX.Element;

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/ScrollProgress.d.ts

@@ -0,0 +1,20 @@
+import { JSX } from 'solid-js';
+export interface ScrollProgressProps {
+    /** Bar height in px. @default 3 */
+    height?: number;
+    /** Bar color (CSS color). @default 'hsl(var(--primary))' */
+    color?: string;
+    class?: string;
+}
+/**
+ * Renders a fixed bar at the top of the viewport whose fill tracks how far
+ * the page has been scrolled. Subscribes to Motion's `scroll` on mount and
+ * scales the inner bar horizontally; respects `prefers-reduced-motion`
+ * (renders a static, empty bar instead).
+ *
+ * @example
+ * ```tsx
+ * <ScrollProgress height={4} color="hsl(var(--accent))" />
+ * ```
+ */
+export declare function ScrollProgress(props: ScrollProgressProps): JSX.Element;

package/dist/ui/Spotlight.d.ts

@@ -0,0 +1,36 @@
+import { JSX } from 'solid-js';
+export interface SpotlightProps {
+    children: JSX.Element;
+    /** Glow color (CSS color). @default 'hsl(var(--primary))' */
+    color?: string;
+    /** Glow radius in px. @default 180 */
+    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 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
+ * <Spotlight color="hsl(var(--primary))" size={220}>
+ *   <div class="rounded-2xl border border-border p-8">Hover for glow</div>
+ * </Spotlight>
+ * ```
+ */
+export declare function Spotlight(props: SpotlightProps): JSX.Element;

package/dist/ui/TiltCard.d.ts

@@ -0,0 +1,34 @@
+import { JSX } from 'solid-js';
+export interface TiltCardProps {
+    children: JSX.Element;
+    /** Max tilt in degrees. @default 10 */
+    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, 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}>
+ *   <div class="rounded-2xl border border-border bg-card p-6">Card content</div>
+ * </TiltCard>
+ * ```
+ */
+export declare function TiltCard(props: TiltCardProps): JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a4ui/core",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "A4ui — Spatial Glass design system & component library for SolidJS (Kobalte behavior + Tailwind glass tokens + motion).",
   "type": "module",
   "license": "MIT",
@@ -138,6 +138,7 @@
     "husky": "^9.1.7",
     "jsdom": "^29.1.1",
     "lint-staged": "^16.4.0",
+    "marked": "^18.0.6",
     "playwright-core": "^1.61.1",
     "prettier": "^3.9.5",
     "solid-element": "^1.9.2",

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.14.1'
+export const A4UI_VERSION = '0.16.0'
 
 // Helpers (src/lib) — generic, framework-level utilities.
 export { cn } from './lib/cn'
@@ -150,7 +150,12 @@ 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, 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'
 
 // Layout (src/layout) — generic shell + backdrop + toggles. App-coupled pieces

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/GradientText.tsx

@@ -0,0 +1,69 @@
+// GradientText — text with a smoothly animated multi-color gradient sweeping
+// across the glyphs on loop. The sweep is a background-position animation
+// clipped to the glyphs via `background-clip: text`, driven by Motion's
+// `animate`. Falls back to a static (non-animated) gradient under reduced
+// motion — still colorful, just not moving.
+import { onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+export interface GradientTextProps {
+  children: JSX.Element
+  /** CSS gradient color stop at 0%. @default 'hsl(var(--primary))' */
+  from?: string
+  /** CSS gradient color stop at 50%. @default 'hsl(var(--accent))' */
+  via?: string
+  /** CSS gradient color stop at 100%. @default 'hsl(var(--primary))' */
+  to?: string
+  /** Seconds per loop. @default 4 */
+  duration?: number
+  class?: string
+}
+
+/**
+ * Renders `children` clipped to a horizontal gradient whose position sweeps
+ * back and forth in a loop, for eye-catching headings. Respects
+ * `prefers-reduced-motion` by rendering a static gradient instead of
+ * animating.
+ *
+ * @example
+ * ```tsx
+ * <GradientText duration={6}>Sonora Precision</GradientText>
+ * ```
+ */
+export function GradientText(props: GradientTextProps): JSX.Element {
+  let el!: HTMLSpanElement
+  let controls: { stop: () => void } | undefined
+
+  onMount(() => {
+    if (motionReduced()) return
+
+    controls = animate(
+      el,
+      { backgroundPosition: ['0% 0%', '200% 0%'] },
+      { duration: props.duration ?? 4, ease: 'linear', repeat: Infinity },
+    )
+
+    onCleanup(() => controls?.stop())
+  })
+
+  return (
+    <span
+      ref={el}
+      class={cn('inline-block font-bold', props.class)}
+      style={{
+        'background-image': `linear-gradient(90deg, ${props.from ?? 'hsl(var(--primary))'} 0%, ${
+          props.via ?? 'hsl(var(--accent))'
+        } 50%, ${props.to ?? 'hsl(var(--primary))'} 100%)`,
+        'background-size': '200% 100%',
+        '-webkit-background-clip': 'text',
+        'background-clip': 'text',
+        '-webkit-text-fill-color': 'transparent',
+        color: 'transparent',
+      }}
+    >
+      {props.children}
+    </span>
+  )
+}

package/src/ui/Magnetic.tsx

@@ -0,0 +1,73 @@
+// Magnetic — pulls its wrapped content toward the cursor while the pointer
+// hovers over it, and springs back to rest on pointerleave. Motion's `animate`
+// drives the translate (a spring, so repeated pointermoves smoothly retarget
+// mid-flight rather than snapping). 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'
+
+export interface MagneticProps {
+  children: JSX.Element
+  /** Max px the element travels toward the cursor. @default 12 */
+  strength?: number
+  class?: string
+}
+
+/**
+ * Wraps `children` in an element that's magnetically drawn toward the
+ * cursor: as the pointer moves within its bounds, the element translates a
+ * fraction of the way toward it (clamped to `strength` px), springing back
+ * to rest on pointerleave. Respects `prefers-reduced-motion` (renders
+ * static).
+ *
+ * @example
+ * ```tsx
+ * <Magnetic strength={16}>
+ *   <button class="rounded-full bg-primary px-6 py-3 text-primary-foreground">Hover me</button>
+ * </Magnetic>
+ * ```
+ */
+export function Magnetic(props: MagneticProps): JSX.Element {
+  let root!: 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 / 2)) / (rect.width / 2)
+      const ny = (event.clientY - (rect.top + rect.height / 2)) / (rect.height / 2)
+      const strength = props.strength ?? 12
+
+      controls?.stop()
+      controls = animate(
+        root,
+        { x: nx * strength, y: ny * strength },
+        { type: 'spring', stiffness: 300, damping: 20 },
+      )
+    }
+
+    const handlePointerLeave = (): void => {
+      controls?.stop()
+      controls = animate(root, { x: 0, y: 0 }, { 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()
+    })
+  })
+
+  return (
+    <div ref={root} class={cn('inline-block will-change-transform', props.class)}>
+      {props.children}
+    </div>
+  )
+}