@a4ui/core 0.29.1 → 0.30.0

package/dist/ui/CardSpread.d.ts

@@ -0,0 +1,37 @@
+import { JSX } from 'solid-js';
+/** Fan shape applied when a {@link CardSpread} opens. Defaults to `'arc'`. */
+export type CardSpreadLayout = 'arc' | 'long-arc' | 'linear' | 'corner' | 'cascade' | 'scatter' | 'wheel';
+export interface CardSpreadProps {
+    /** Card contents; each entry becomes one card in the stack. */
+    items: JSX.Element[];
+    /** Fan shape. @default 'arc' */
+    layout?: CardSpreadLayout;
+    /** Controlled open state. Omit to spread on hover instead. */
+    open?: boolean;
+    /** Strength knob: degrees for arced/wheel layouts, px for linear/corner/cascade/scatter. Per-layout default applies when omitted. */
+    spread?: number;
+    class?: string;
+    'aria-label'?: string;
+}
+/**
+ * A stack of cards that fans out into an arc, line, corner, cascade, scatter,
+ * or wheel shape. At rest the cards sit in a near-centered pile; opening
+ * (controlled via `open`, or on hover when uncontrolled) spreads them.
+ * Animates only `transform`/`opacity` (Motion spring) so the fan stays
+ * compositor-only, and falls back to a static fanned layout under reduced
+ * motion.
+ *
+ * @example
+ * ```tsx
+ * <CardSpread
+ *   layout="arc"
+ *   aria-label="Trip itinerary cards"
+ *   items={[
+ *     <div class="p-4">Day 1 — Arrival</div>,
+ *     <div class="p-4">Day 2 — Old Town</div>,
+ *     <div class="p-4">Day 3 — Coast drive</div>,
+ *   ]}
+ * />
+ * ```
+ */
+export declare function CardSpread(props: CardSpreadProps): JSX.Element;

package/dist/ui/Carousel3D.d.ts

@@ -0,0 +1,38 @@
+import { JSX } from 'solid-js';
+/** Layout curve for a {@link Carousel3D}. Defaults to `'coverflow'`. */
+export type Carousel3DVariant = 'coverflow' | 'arc';
+export interface Carousel3DProps {
+    /** Slides shown around the active one, arranged by distance from it. */
+    slides: JSX.Element[];
+    /** Layout curve. @default 'coverflow' */
+    variant?: Carousel3DVariant;
+    /** Controlled active index. */
+    active?: number;
+    /** Initial active index when uncontrolled. @default 0 */
+    defaultActive?: number;
+    /** Fires with the new index whenever the active slide changes. */
+    onChange?: (index: number) => void;
+    class?: string;
+}
+/**
+ * A 3D carousel that arranges slides around the active one on a coverflow or
+ * shallow arc curve — `perspective` + `preserve-3d`, each slide positioned
+ * purely by `transform`/`opacity` (Motion spring) so it stays
+ * compositor-only. Supports controlled/uncontrolled `active`, prev/next
+ * buttons, dot indicators, arrow-key navigation, and pointer-drag swiping.
+ * Falls back to a flat opacity crossfade (no 3D transforms) under reduced
+ * motion.
+ *
+ * @example
+ * ```tsx
+ * <Carousel3D
+ *   variant="coverflow"
+ *   slides={[
+ *     <div class="grid h-full place-items-center rounded-xl border border-border bg-card p-6 text-center">Trail A — Ridge Loop</div>,
+ *     <div class="grid h-full place-items-center rounded-xl border border-border bg-card p-6 text-center">Trail B — Falls Overlook</div>,
+ *     <div class="grid h-full place-items-center rounded-xl border border-border bg-card p-6 text-center">Trail C — Summit Pass</div>,
+ *   ]}
+ * />
+ * ```
+ */
+export declare function Carousel3D(props: Carousel3DProps): JSX.Element;

package/dist/ui/FocusBlurGroup.d.ts

@@ -0,0 +1,32 @@
+import { JSX } from 'solid-js';
+export interface FocusBlurGroupProps<T> {
+    /** The full data set to render. */
+    items: T[];
+    /** Row renderer. */
+    children: (item: T, index: number) => JSX.Element;
+    /** Blur (px) applied to non-focused items. @default 2 */
+    blur?: number;
+    /** Opacity (0..1) applied to non-focused items. @default 0.5 */
+    dim?: number;
+    /** Applied to the container — use it for layout (e.g. `flex gap-6`). */
+    class?: string;
+}
+/**
+ * Container that spotlights whichever item is hovered or keyboard-focused:
+ * that item stays sharp and fully opaque while its siblings blur and dim.
+ * Only `opacity`/`filter` transition — never a layout property — and under
+ * `motionReduced()` the blur is skipped (dim-only, no transition) since blur
+ * motion reads as motion-sickness-adjacent.
+ *
+ * @example
+ * ```tsx
+ * <FocusBlurGroup items={navLinks} class="flex gap-6">
+ *   {(link) => (
+ *     <a href={link.href} class="text-sm font-medium text-foreground">
+ *       {link.label}
+ *     </a>
+ *   )}
+ * </FocusBlurGroup>
+ * ```
+ */
+export declare function FocusBlurGroup<T>(props: FocusBlurGroupProps<T>): JSX.Element;

package/dist/ui/IconMorphButton.d.ts

@@ -0,0 +1,50 @@
+import { JSX } from 'solid-js';
+/** Visual style of an {@link IconMorphButton}. Defaults to `'ghost'`. */
+export type IconMorphButtonVariant = 'solid' | 'ghost' | 'outline';
+export interface IconMorphButtonProps {
+    /** Icon shown while `pressed` is `false`, e.g. `<Copy size={18} />`. */
+    inactive: JSX.Element;
+    /** Icon shown while `pressed` is `true`, e.g. `<Check size={18} />`. */
+    active: JSX.Element;
+    /** Controlled pressed state. Omit to let the button manage its own state. */
+    pressed?: boolean;
+    /** Initial pressed state when uncontrolled. Defaults to `false`. */
+    defaultPressed?: boolean;
+    /** Fired with the next pressed state, controlled or uncontrolled. */
+    onChange?: (pressed: boolean) => void;
+    /**
+     * When greater than `0`, auto-reverts to `inactive` after this many ms once
+     * pressed (e.g. copy → check → copy). The timer is cleared on cleanup and
+     * restarted on every re-press. @default 0
+     */
+    revertAfter?: number;
+    /** Optional label shown next to the icon while `pressed` is `false`. */
+    label?: JSX.Element;
+    /** Optional label shown next to the icon while `pressed` is `true`. */
+    activeLabel?: JSX.Element;
+    /** Visual style. Defaults to `'ghost'`. */
+    variant?: IconMorphButtonVariant;
+    class?: string;
+    'aria-label'?: string;
+}
+/**
+ * Two-state icon toggle button whose icon morphs (spring scale + rotate +
+ * fade) between `inactive` and `active` glyphs, stacked in a fixed-size box.
+ * Supports controlled (`pressed`/`onChange`) or uncontrolled
+ * (`defaultPressed`) use, an optional auto-revert timer, and an optional
+ * crossfading label. Falls back to an instant swap under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <IconMorphButton
+ *   inactive={<Copy size={18} />}
+ *   active={<Check size={18} />}
+ *   aria-label="Copy to clipboard"
+ *   revertAfter={1500}
+ *   onChange={(pressed) => {
+ *     if (pressed) void navigator.clipboard?.writeText('npm install @a4ui/core')
+ *   }}
+ * />
+ * ```
+ */
+export declare function IconMorphButton(props: IconMorphButtonProps): JSX.Element;

package/dist/ui/LikeButton.d.ts

@@ -0,0 +1,35 @@
+import { JSX } from 'solid-js';
+/** Which icon a {@link LikeButton} renders — picks the semantic use (like/favorite/save). */
+export type LikeButtonIcon = 'heart' | 'star' | 'bookmark';
+export interface LikeButtonProps {
+    /** Controlled pressed state. When set, wins over internal state — pair with `onChange`. */
+    pressed?: boolean;
+    /** Initial pressed state for uncontrolled use. @default false */
+    defaultPressed?: boolean;
+    onChange?: (pressed: boolean) => void;
+    /** Which icon to render. @default 'heart' */
+    icon?: LikeButtonIcon;
+    /** Count shown next to the icon (e.g. total likes). */
+    count?: number;
+    /** Show `count`. @default false */
+    showCount?: boolean;
+    /** Class applied to the icon/count when pressed. @default 'text-primary' */
+    activeClass?: string;
+    class?: string;
+    'aria-label'?: string;
+}
+/**
+ * Like/favorite/save-later toggle button. One component covers all three via
+ * `icon` ('heart' | 'star' | 'bookmark') rather than three near-identical
+ * toggles. On becoming pressed the icon fills, morphs to `activeClass`,
+ * springs a scale pop, and bursts a handful of tiny icon copies outward —
+ * skipped under reduced motion, which just flips the filled/unfilled state
+ * instantly. Works controlled (`pressed` + `onChange`) or uncontrolled
+ * (`defaultPressed`).
+ *
+ * @example
+ * ```tsx
+ * <LikeButton defaultPressed count={128} showCount aria-label="Like this post" />
+ * ```
+ */
+export declare function LikeButton(props: LikeButtonProps): JSX.Element;

package/dist/ui/MicroButton.d.ts

@@ -0,0 +1,32 @@
+import { JSX } from 'solid-js';
+/** Feedback micro-animation a {@link MicroButton} plays. Defaults to `'ring'`. */
+export type MicroButtonEffect = 'spin' | 'shake' | 'pulse' | 'ring' | 'sparkle' | 'glare';
+/** Visual style of a {@link MicroButton}. Defaults to `'solid'`. */
+export type MicroButtonVariant = 'solid' | 'ghost' | 'outline';
+export interface MicroButtonProps {
+    children?: JSX.Element;
+    /** Feedback micro-animation. `'glare'` plays on hover; the rest play on click. @default 'ring' */
+    effect?: MicroButtonEffect;
+    onClick?: (e: MouseEvent) => void;
+    /** Visual style. @default 'solid' */
+    variant?: MicroButtonVariant;
+    disabled?: boolean;
+    class?: string;
+    'aria-label'?: string;
+}
+/**
+ * Small icon/label button that plays a short feedback micro-animation on
+ * interaction — spin, shake, pulse, ring, or sparkle on click, or a diagonal
+ * glare sweep on hover. Every effect animates only `transform`/`opacity`, so
+ * it stays cheap even on low-end devices; decorative particles are spawned
+ * and removed on completion, never left in the DOM. Renders a plain static
+ * `<button>` with no effect under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <MicroButton effect="sparkle" aria-label="Like">
+ *   <Heart size={16} />
+ * </MicroButton>
+ * ```
+ */
+export declare function MicroButton(props: MicroButtonProps): JSX.Element;

package/dist/ui/SlideArrowButton.d.ts

@@ -0,0 +1,30 @@
+import { JSX, ParentProps } from 'solid-js';
+/** Direction the label/arrow slide toward on hover. Defaults to `'right'`. */
+export type SlideArrowDirection = 'right' | 'left';
+/** Visual style of a {@link SlideArrowButton}. Defaults to `'solid'`. */
+export type SlideArrowButtonVariant = 'solid' | 'outline';
+export interface SlideArrowButtonProps extends ParentProps {
+    onClick?: (e: MouseEvent) => void;
+    /** Direction the label/arrow slide toward on hover. Defaults to `'right'`. */
+    direction?: SlideArrowDirection;
+    /** Custom icon; defaults to `ArrowRight`/`ArrowLeft` per `direction`. */
+    icon?: JSX.Element;
+    /** Visual style. Defaults to `'solid'`. */
+    variant?: SlideArrowButtonVariant;
+    disabled?: boolean;
+    class?: string;
+    /** Accessible label, forwarded to the underlying `<button>`. */
+    'aria-label'?: string;
+}
+/**
+ * CTA button: at rest the label sits centered; on hover it slides toward
+ * `direction` while an arrow slides in from the opposite edge. Pure CSS
+ * transform/opacity transitions — no JS animation engine.
+ *
+ * @example
+ * ```tsx
+ * <SlideArrowButton onClick={() => go()}>Get started</SlideArrowButton>
+ * <SlideArrowButton direction="left" variant="outline">Back</SlideArrowButton>
+ * ```
+ */
+export declare function SlideArrowButton(props: SlideArrowButtonProps): JSX.Element;

package/dist/ui/TimeMachineStack.d.ts

@@ -0,0 +1,34 @@
+import { JSX } from 'solid-js';
+export interface TimeMachineStackProps {
+    /** Slide contents, one per stack position. */
+    slides: JSX.Element[];
+    /** Controlled active index. Omit to manage it internally. */
+    active?: number;
+    /** Initial active index when uncontrolled. @default 0 */
+    defaultActive?: number;
+    /** Fired whenever the active index changes, via click or keyboard. */
+    onChange?: (index: number) => void;
+    class?: string;
+}
+/**
+ * Apple-style "time machine" depth stack: the active slide is front and
+ * full-size, and the rest recede into the screen behind it — each further
+ * slide translated up, pushed back on Z, scaled down, and dimmed. A vertical
+ * scrubber of real buttons (one per slide), pinned to the right edge, jumps
+ * to any index; the stage handles ArrowUp/ArrowDown (and Left/Right) when
+ * focused. Animates only `transform`/`opacity` (Motion spring); reduced
+ * motion collapses to a flat view of just the active slide.
+ *
+ * @example
+ * ```tsx
+ * <TimeMachineStack
+ *   defaultActive={0}
+ *   slides={[
+ *     <div class="flex h-full items-center justify-center p-6">Sunset over the bay</div>,
+ *     <div class="flex h-full items-center justify-center p-6">Empty beach at dawn</div>,
+ *     <div class="flex h-full items-center justify-center p-6">Fog through the pines</div>,
+ *   ]}
+ * />
+ * ```
+ */
+export declare function TimeMachineStack(props: TimeMachineStackProps): JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a4ui/core",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "description": "A4ui — Spatial Glass design system & component library for SolidJS (Kobalte behavior + Tailwind glass tokens + motion).",
   "type": "module",
   "license": "MIT",
@@ -101,6 +101,7 @@
     "test:visual": "playwright test --config playwright.visual.config.ts",
     "test:report": "playwright show-report",
     "test:package": "node scripts/test-package.mjs",
+    "test:smoke": "node scripts/smoke-console.mjs",
     "validate": "npm run typecheck && npm run lint && npm run format:check && npm run test:unit && npm run build && npm run test:package",
     "prepublishOnly": "npm run validate",
     "prepare": "husky"

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.29.1'
+export const A4UI_VERSION = '0.30.0'
 
 // Helpers (src/lib) — generic, framework-level utilities.
 export { cn } from './lib/cn'
@@ -160,6 +160,26 @@ export { FloatingToolbar, type FloatingToolbarProps } from './ui/FloatingToolbar
 export { PageTransition, type PageTransitionProps } from './ui/PageTransition'
 export { InlineSelect, type InlineSelectProps, type InlineSelectOption } from './ui/InlineSelect'
 
+// Micro-interactions — animated buttons + card/3D transitions (Motion-driven).
+export {
+  MicroButton,
+  type MicroButtonProps,
+  type MicroButtonEffect,
+  type MicroButtonVariant,
+} from './ui/MicroButton'
+export { IconMorphButton, type IconMorphButtonProps, type IconMorphButtonVariant } from './ui/IconMorphButton'
+export { LikeButton, type LikeButtonProps, type LikeButtonIcon } from './ui/LikeButton'
+export {
+  SlideArrowButton,
+  type SlideArrowButtonProps,
+  type SlideArrowButtonVariant,
+  type SlideArrowDirection,
+} from './ui/SlideArrowButton'
+export { FocusBlurGroup, type FocusBlurGroupProps } from './ui/FocusBlurGroup'
+export { CardSpread, type CardSpreadProps, type CardSpreadLayout } from './ui/CardSpread'
+export { Carousel3D, type Carousel3DProps, type Carousel3DVariant } from './ui/Carousel3D'
+export { TimeMachineStack, type TimeMachineStackProps } from './ui/TimeMachineStack'
+
 // Phase 2 — code, search, navigation, master-detail.
 export { CodeTabs, type CodeTabsProps, type CodeTab } from './ui/CodeTabs'
 export { PillSearch, type PillSearchProps, type PillField } from './ui/PillSearch'

package/src/ui/CardSpread.tsx

@@ -0,0 +1,194 @@
+// CardSpread — a stack of cards that fans out into one of several layouts.
+// Rest state is a tight near-centered stack; opening (controlled via `open`,
+// or on hover when uncontrolled) spreads the cards per `layout`. Only
+// `transform`/`opacity` are animated (Motion spring), never layout properties,
+// so the fan stays compositor-only. Reduced motion renders the spread layout
+// statically (no transition, no hover animation).
+import { createEffect, createSignal, For, on, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+/** Fan shape applied when a {@link CardSpread} opens. Defaults to `'arc'`. */
+export type CardSpreadLayout = 'arc' | 'long-arc' | 'linear' | 'corner' | 'cascade' | 'scatter' | 'wheel'
+
+export interface CardSpreadProps {
+  /** Card contents; each entry becomes one card in the stack. */
+  items: JSX.Element[]
+  /** Fan shape. @default 'arc' */
+  layout?: CardSpreadLayout
+  /** Controlled open state. Omit to spread on hover instead. */
+  open?: boolean
+  /** Strength knob: degrees for arced/wheel layouts, px for linear/corner/cascade/scatter. Per-layout default applies when omitted. */
+  spread?: number
+  class?: string
+  'aria-label'?: string
+}
+
+interface CardTransform {
+  x: number
+  y: number
+  rotate: number
+  origin: string
+}
+
+const DEFAULT_SPREAD: Record<CardSpreadLayout, number> = {
+  arc: 10,
+  'long-arc': 6,
+  linear: 56,
+  corner: 12,
+  cascade: 18,
+  scatter: 14,
+  wheel: 16,
+}
+
+// Deterministic pseudo-random offset in [-1, 1] from an index — no Math.random.
+function pseudoRandom(i: number): number {
+  const s = Math.sin(i * 12.9898) * 43758.5453
+  return (s - Math.floor(s)) * 2 - 1
+}
+
+function restTransform(i: number): CardTransform {
+  // Tight near-centered stack: a hair of offset/rotation per card so the
+  // pile still reads as separate cards.
+  return { x: i * 1.5, y: -i * 1, rotate: (i % 2 === 0 ? 1 : -1) * 1.5, origin: 'bottom center' }
+}
+
+function openTransform(layout: CardSpreadLayout, i: number, n: number, spread: number): CardTransform {
+  const mid = (n - 1) / 2
+  const d = i - mid
+
+  switch (layout) {
+    case 'arc': {
+      const gap = 44
+      return { x: d * gap, y: Math.abs(d) ** 2 * 6, rotate: d * spread, origin: 'bottom center' }
+    }
+    case 'long-arc': {
+      const gap = 68
+      return { x: d * gap, y: Math.abs(d) ** 2 * 4, rotate: d * spread, origin: 'bottom center' }
+    }
+    case 'linear':
+      return { x: d * spread, y: 0, rotate: 0, origin: 'bottom center' }
+    case 'corner':
+      return { x: i * (spread * 0.6), y: -i * (spread * 0.15), rotate: i * spread, origin: 'bottom left' }
+    case 'cascade':
+      return {
+        x: i * spread,
+        y: i * (spread * 0.55),
+        rotate: (i % 2 === 0 ? 1 : -1) * 3,
+        origin: 'bottom center',
+      }
+    case 'scatter': {
+      const r = pseudoRandom(i)
+      const r2 = pseudoRandom(i + 100)
+      return { x: r * spread * 3, y: r2 * spread * 1.5, rotate: r * spread, origin: 'center center' }
+    }
+    case 'wheel':
+      return { x: d * 18, y: Math.abs(d) * 10, rotate: d * spread, origin: 'bottom center' }
+  }
+}
+
+function transformString(t: CardTransform): string {
+  return `translate(${t.x}px, ${t.y}px) rotate(${t.rotate}deg)`
+}
+
+/**
+ * A stack of cards that fans out into an arc, line, corner, cascade, scatter,
+ * or wheel shape. At rest the cards sit in a near-centered pile; opening
+ * (controlled via `open`, or on hover when uncontrolled) spreads them.
+ * Animates only `transform`/`opacity` (Motion spring) so the fan stays
+ * compositor-only, and falls back to a static fanned layout under reduced
+ * motion.
+ *
+ * @example
+ * ```tsx
+ * <CardSpread
+ *   layout="arc"
+ *   aria-label="Trip itinerary cards"
+ *   items={[
+ *     <div class="p-4">Day 1 — Arrival</div>,
+ *     <div class="p-4">Day 2 — Old Town</div>,
+ *     <div class="p-4">Day 3 — Coast drive</div>,
+ *   ]}
+ * />
+ * ```
+ */
+export function CardSpread(props: CardSpreadProps): JSX.Element {
+  const cardRefs: (HTMLElement | undefined)[] = []
+  const controls: (ReturnType<typeof animate> | undefined)[] = []
+  const [hovered, setHovered] = createSignal(false)
+
+  const layout = () => props.layout ?? 'arc'
+  const spread = () => props.spread ?? DEFAULT_SPREAD[layout()]
+  const isOpen = () => (props.open !== undefined ? props.open : hovered())
+
+  // Reduced motion always renders the fanned layout, statically, regardless
+  // of open/hover state — so `open`/`hover` never trigger visible motion.
+  const applyTransforms = (animated: boolean) => {
+    const n = props.items.length
+    const reduced = motionReduced()
+    const open = reduced ? true : isOpen()
+
+    cardRefs.forEach((card, i) => {
+      if (!card) return
+      const t = open ? openTransform(layout(), i, n, spread()) : restTransform(i)
+      card.style.transformOrigin = t.origin
+      card.style.zIndex = String(open ? i : n - i)
+
+      controls[i]?.stop()
+      if (reduced || !animated) {
+        card.style.transform = transformString(t)
+        return
+      }
+      controls[i] = animate(
+        card,
+        { x: t.x, y: t.y, rotate: t.rotate },
+        { type: 'spring', stiffness: 260, damping: 24 },
+      )
+    })
+  }
+
+  // Initial paint only: snap to the correct state (no animation) so a controlled
+  // `open` or a reduced-motion preference doesn't flash the closed stack first.
+  // Deliberately untracked (onMount, not createEffect) — it must run exactly
+  // once, otherwise it would re-fire on every hover/open change and snap the
+  // cards straight to their target, leaving the animated effect below nothing
+  // to spring from.
+  onMount(() => applyTransforms(false))
+  // Subsequent changes to open/hover/layout/spread animate in.
+  createEffect(
+    on([() => props.open, hovered, layout, spread, () => props.items.length], () => applyTransforms(true), {
+      defer: true,
+    }),
+  )
+  onCleanup(() => controls.forEach((c) => c?.stop()))
+
+  const handleEnter = () => {
+    if (props.open === undefined && !motionReduced()) setHovered(true)
+  }
+  const handleLeave = () => {
+    if (props.open === undefined && !motionReduced()) setHovered(false)
+  }
+
+  return (
+    <div
+      role="group"
+      aria-label={props['aria-label']}
+      class={cn('relative inline-block h-56 w-40', props.class)}
+      onPointerEnter={handleEnter}
+      onPointerLeave={handleLeave}
+    >
+      <For each={props.items}>
+        {(item, i) => (
+          <div
+            ref={(el) => (cardRefs[i()] = el)}
+            class="absolute inset-x-0 top-0 h-56 w-40 rounded-xl border border-border bg-card text-card-foreground shadow-sm will-change-transform"
+            style={{ transform: transformString(restTransform(i())) }}
+          >
+            {item}
+          </div>
+        )}
+      </For>
+    </div>
+  )
+}