@a4ui/core 0.14.0 → 0.15.0

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/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,23 @@
+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;
+}
+/**
+ * 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).
+ *
+ * @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,21 @@
+import { JSX } from 'solid-js';
+export interface TiltCardProps {
+    children: JSX.Element;
+    /** Max tilt in degrees. @default 10 */
+    max?: number;
+    class?: string;
+}
+/**
+ * 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.
+ * Respects `prefers-reduced-motion` (renders static).
+ *
+ * @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.0",
+  "version": "0.15.0",
   "description": "A4ui — Spatial Glass design system & component library for SolidJS (Kobalte behavior + Tailwind glass tokens + motion).",
   "type": "module",
   "license": "MIT",
@@ -98,6 +98,7 @@
     "test": "playwright test",
     "test:ui": "playwright test --ui",
     "test:a11y": "playwright test a11y --project=desktop",
+    "test:visual": "playwright test --config playwright.visual.config.ts",
     "test:report": "playwright show-report",
     "test:package": "node scripts/test-package.mjs",
     "validate": "npm run typecheck && npm run lint && npm run format:check && npm run test:unit && npm run build && npm run test:package",
@@ -137,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.0'
+export const A4UI_VERSION = '0.15.0'
 
 // Helpers (src/lib) — generic, framework-level utilities.
 export { cn } from './lib/cn'
@@ -151,6 +151,11 @@ 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 { Magnetic, type MagneticProps } from './ui/Magnetic'
+export { TiltCard, type TiltCardProps } from './ui/TiltCard'
+export { Spotlight, 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/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>
+  )
+}

package/src/ui/ScrollProgress.tsx

@@ -0,0 +1,61 @@
+// ScrollProgress — a thin bar pinned to the top of the viewport that fills
+// left-to-right as the page scrolls, a common reading-progress indicator.
+// Driven by Motion's `scroll` progress callback (0..1). Renders a static,
+// unfilled bar under reduced motion (no scroll subscription).
+import { onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced, scroll } from '../lib/motion'
+
+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 function ScrollProgress(props: ScrollProgressProps): JSX.Element {
+  let bar!: HTMLDivElement
+
+  onMount(() => {
+    bar.style.transform = 'scaleX(0)'
+
+    if (motionReduced()) return
+
+    const stop = scroll((progress: number) => {
+      bar.style.transform = `scaleX(${progress})`
+    })
+
+    onCleanup(() => stop())
+  })
+
+  return (
+    <div
+      aria-hidden="true"
+      class={cn('fixed top-0 left-0 z-[9999] w-full', props.class)}
+      style={{ height: `${props.height ?? 3}px` }}
+    >
+      <div
+        ref={bar}
+        class="origin-left will-change-transform"
+        style={{
+          height: '100%',
+          width: '100%',
+          'background-color': props.color ?? 'hsl(var(--primary))',
+        }}
+      />
+    </div>
+  )
+}

package/src/ui/Spotlight.tsx

@@ -0,0 +1,83 @@
+// Spotlight — a soft radial glow that follows the cursor inside the wrapped
+// 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
+// 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'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+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
+}
+
+/**
+ * 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).
+ *
+ * @example
+ * ```tsx
+ * <Spotlight color="hsl(var(--primary))" size={220}>
+ *   <div class="rounded-2xl border border-border p-8">Hover for glow</div>
+ * </Spotlight>
+ * ```
+ */
+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)
+    })
+  })
+
+  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

@@ -0,0 +1,80 @@
+// 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.
+import { onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+export interface TiltCardProps {
+  children: JSX.Element
+  /** Max tilt in degrees. @default 10 */
+  max?: number
+  class?: string
+}
+
+/**
+ * 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.
+ * Respects `prefers-reduced-motion` (renders static).
+ *
+ * @example
+ * ```tsx
+ * <TiltCard max={12}>
+ *   <div class="rounded-2xl border border-border bg-card p-6">Card content</div>
+ * </TiltCard>
+ * ```
+ */
+export function TiltCard(props: TiltCardProps): JSX.Element {
+  let root!: HTMLDivElement
+  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()
+    })
+  })
+
+  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' }}>
+        {props.children}
+      </div>
+    </div>
+  )
+}