@a4ui/core 0.12.0 → 0.13.0

package/dist/lib/flyToCart.d.ts

@@ -0,0 +1,25 @@
+export interface FlyToCartOptions {
+    /** Image URL to fly; if omitted, the source element is cloned. */
+    image?: string;
+    /** Flight duration in seconds. @default 0.6 */
+    duration?: number;
+    /** Called when the flight finishes (e.g. to increment the cart count). */
+    onArrive?: () => void;
+}
+/**
+ * Animate a small ghost from `source` to `target` (e.g. product → cart icon),
+ * then a bump on the target. No-op under reduced motion (still calls onArrive).
+ *
+ * @example
+ * ```ts
+ * function onAddToCart(e: MouseEvent) {
+ *   const button = e.currentTarget as HTMLElement
+ *   const cartIcon = document.getElementById('cart-icon')!
+ *   flyToCart(button, cartIcon, {
+ *     image: product.thumbnailUrl,
+ *     onArrive: () => setCartCount((n) => n + 1),
+ *   })
+ * }
+ * ```
+ */
+export declare function flyToCart(source: Element, target: Element, opts?: FlyToCartOptions): void;

package/dist/ui/Curtain.d.ts

@@ -0,0 +1,44 @@
+import { JSX } from 'solid-js';
+export type CurtainVariant = 'fade' | 'doors' | 'blinds' | 'iris' | 'shutter' | 'clip' | 'pixels';
+export interface CurtainProps {
+    /** true = cover the screen; false = uncover (reveal content). */
+    show: boolean;
+    /** Which wipe style. @default 'fade' */
+    variant?: CurtainVariant;
+    /** Overlay color (CSS color / var). @default 'hsl(var(--background))' */
+    color?: string;
+    /** Seconds for one direction. @default 0.6 */
+    duration?: number;
+    /** Called once the screen is fully covered (show went true→covered). */
+    onCovered?: () => void;
+    /** Called once fully uncovered (show went false→revealed). */
+    onRevealed?: () => void;
+    class?: string;
+}
+/**
+ * A controlled full-screen curtain for page/route transitions. Set `show` to
+ * `true` to cover the viewport, `false` to uncover it, and swap your route
+ * content while covered. `variant` picks the wipe style — fade, sliding
+ * doors, blinds, shutter (vertical blinds), iris/circle wipe, a left-to-right
+ * clip wipe, or a pixel-grid cascade —
+ * `onCovered` / `onRevealed` fire once each transition finishes so you can
+ * swap content at exactly the right moment. Skips the animation (and still
+ * fires the callback on the next microtask) under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * const [covered, setCovered] = createSignal(false)
+ * const goTo = (path: string) => setCovered(true)
+ * return (
+ *   <>
+ *     <Curtain
+ *       show={covered()}
+ *       variant="iris"
+ *       onCovered={() => { loadRoute(); setCovered(false) }}
+ *     />
+ *     <Router />
+ *   </>
+ * )
+ * ```
+ */
+export declare function Curtain(props: CurtainProps): JSX.Element;

package/dist/ui/Expandable.d.ts

@@ -0,0 +1,34 @@
+import { JSX } from 'solid-js';
+export interface ExpandableProps {
+    /** Collapsed content — the card users click to expand. */
+    trigger: JSX.Element;
+    /** Expanded panel content. */
+    children: JSX.Element;
+    /** `dialog` = centered panel capped at `maxWidth`; `full` = near-fullscreen. @default 'dialog' */
+    size?: 'dialog' | 'full';
+    /** Max width (px) of the expanded panel when `size='dialog'`. @default 640 */
+    maxWidth?: number;
+    /** Notified when the panel opens/closes. */
+    onOpenChange?: (open: boolean) => void;
+    /** Class for the inline trigger wrapper. */
+    class?: string;
+    /** Class for the expanded panel surface. */
+    panelClass?: string;
+}
+/**
+ * Expands a card into an overlay panel with a shared-element (FLIP) transition —
+ * the card appears to grow into the dialog and shrink back on close. Animates
+ * position + size (never scale) so content stays crisp. Falls back to a plain
+ * show/hide under reduced motion. Close with the ✕, a backdrop click, or Escape.
+ *
+ * @example
+ * ```tsx
+ * <Expandable
+ *   trigger={<Card class="cursor-pointer">Tap to expand</Card>}
+ *   size="dialog"
+ * >
+ *   <div class="p-6">Full details here…</div>
+ * </Expandable>
+ * ```
+ */
+export declare function Expandable(props: ExpandableProps): JSX.Element;

package/dist/ui/FillText.d.ts

@@ -0,0 +1,18 @@
+import { JSX } from 'solid-js';
+export interface FillTextProps {
+    text: string;
+    /** Seconds per sweep. @default 1.6 */
+    duration?: number;
+    class?: string;
+}
+/**
+ * Renders `text` with a bright gradient band that sweeps across the glyphs
+ * repeatedly, useful as a lightweight loading indicator. Respects
+ * `prefers-reduced-motion` by rendering plain muted text instead of animating.
+ *
+ * @example
+ * ```tsx
+ * <FillText text="Loading results…" />
+ * ```
+ */
+export declare function FillText(props: FillTextProps): JSX.Element;

package/dist/ui/HoldToConfirm.d.ts

@@ -0,0 +1,24 @@
+import { JSX } from 'solid-js';
+export interface HoldToConfirmProps {
+    onConfirm: () => void;
+    /** Button label. @default 'Hold to confirm' */
+    label?: string;
+    /** How long to hold, in ms. @default 1200 */
+    holdMs?: number;
+    disabled?: boolean;
+    class?: string;
+}
+/**
+ * Press-and-hold button for destructive/important actions: `onConfirm` only
+ * fires once the pointer (or Space/Enter) has been held down for `holdMs`.
+ * A fill layer sweeps left-to-right as visual progress; releasing early stops
+ * and resets it. Under reduced motion the hold is still required (gated by a
+ * plain timer instead of the tracked animation), but the fill jumps instead
+ * of sweeping and the success flourish is skipped.
+ *
+ * @example
+ * ```tsx
+ * <HoldToConfirm label="Hold to delete" holdMs={1500} onConfirm={() => deleteItem(id)} />
+ * ```
+ */
+export declare function HoldToConfirm(props: HoldToConfirmProps): JSX.Element;

package/dist/ui/LoadingDots.d.ts

@@ -0,0 +1,20 @@
+import { JSX } from 'solid-js';
+export interface LoadingDotsProps {
+    /** Dot diameter in px. @default 8 */
+    size?: number;
+    /** Optional accessible label. @default 'Loading' */
+    label?: string;
+    class?: string;
+}
+/**
+ * Three dots bouncing in a staggered wave — an inline, indeterminate loading
+ * indicator. Dots use `bg-current`, so color/size follow the ancestor's text
+ * color; diameter is set via `size`. Falls back to a gentle opacity pulse
+ * under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <LoadingDots label="Loading results" class="text-primary" />
+ * ```
+ */
+export declare function LoadingDots(props: LoadingDotsProps): JSX.Element;

package/dist/ui/MultiStateBadge.d.ts

@@ -0,0 +1,23 @@
+import { JSX } from 'solid-js';
+/** The lifecycle state a {@link MultiStateBadge} can be in. */
+export type BadgeState = 'idle' | 'loading' | 'success' | 'error';
+export interface MultiStateBadgeProps {
+    /** Current lifecycle state; drives color, icon, and label. */
+    state: BadgeState;
+    /** Override the per-state text. Defaults: idle→'Ready', loading→'Working…', success→'Done', error→'Failed'. */
+    labels?: Partial<Record<BadgeState, string>>;
+    class?: string;
+}
+/**
+ * Status badge that animates between `idle` → `loading` → `success` → `error`,
+ * morphing its color and swapping its icon/label on each transition. Colors
+ * tween via a CSS `transition-colors` class; the pill also gets a spring
+ * "pop" and the icon/label cross-fade via Motion's `animate`, both skipped
+ * when {@link motionReduced} is true.
+ *
+ * @example
+ * ```tsx
+ * <MultiStateBadge state={saveState()} labels={{ error: 'Save failed' }} />
+ * ```
+ */
+export declare function MultiStateBadge(props: MultiStateBadgeProps): JSX.Element;

package/dist/ui/NotificationStack.d.ts

@@ -0,0 +1,32 @@
+import { JSX } from 'solid-js';
+export interface StackNotification {
+    id: string | number;
+    title: string;
+    description?: string;
+    icon?: JSX.Element;
+}
+export interface NotificationStackProps {
+    /** Newest first. The parent owns this array. */
+    items: StackNotification[];
+    /** How many cards are visible before the rest collapse behind. @default 3 */
+    max?: number;
+    /** Fired when a card is dismissed; the parent should drop it from `items`. */
+    onDismiss?: (id: string | number) => void;
+    class?: string;
+}
+/**
+ * Stacked notifications. Cards behind the front one are offset down and scaled,
+ * so they peek from the bottom edge; removing the front card promotes the rest
+ * with a smooth transition (skipped under reduced motion). New cards fade/slide
+ * in via `animateIn`.
+ *
+ * @example
+ * ```tsx
+ * const [items, setItems] = createStore<StackNotification[]>([])
+ * <NotificationStack
+ *   items={items}
+ *   onDismiss={(id) => setItems((xs) => xs.filter((x) => x.id !== id))}
+ * />
+ * ```
+ */
+export declare function NotificationStack(props: NotificationStackProps): JSX.Element;

package/dist/ui/NowPlaying.d.ts

@@ -0,0 +1,21 @@
+import { JSX } from 'solid-js';
+export interface NowPlayingProps {
+    title: string;
+    artist?: string;
+    /** Cover art URL. */
+    cover?: string;
+    /** Whether the equalizer bars are animating. @default true */
+    playing?: boolean;
+    class?: string;
+}
+/**
+ * Compact "now playing" music widget with an animated equalizer. Bars bounce
+ * via CSS keyframes while `playing` is true; they freeze to a low static
+ * height when paused or under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <NowPlaying title="Random Access Memories" artist="Daft Punk" cover="/covers/ram.jpg" playing />
+ * ```
+ */
+export declare function NowPlaying(props: NowPlayingProps): JSX.Element;

package/dist/ui/Parallax.d.ts

@@ -0,0 +1,21 @@
+import { JSX } from 'solid-js';
+export interface ParallaxProps {
+    children: JSX.Element;
+    /** Parallax strength; positive moves slower/opposite. Pixels of travel across the scroll range. @default 80 */
+    amount?: number;
+    class?: string;
+}
+/**
+ * Wraps `children` in an element that drifts vertically as the page scrolls,
+ * creating a depth effect. Tracks scroll progress of the element itself
+ * against the viewport via Motion's `scroll`; respects `prefers-reduced-motion`
+ * (renders static).
+ *
+ * @example
+ * ```tsx
+ * <Parallax amount={120}>
+ *   <img src="/hero.png" alt="" />
+ * </Parallax>
+ * ```
+ */
+export declare function Parallax(props: ParallaxProps): JSX.Element;

package/dist/ui/ScrambleText.d.ts

@@ -0,0 +1,22 @@
+import { JSX } from 'solid-js';
+export interface ScrambleTextProps {
+    text: string;
+    /** When to run: on mount, or on hover. @default 'mount' */
+    trigger?: 'mount' | 'hover';
+    /** Total scramble duration in ms. @default 800 */
+    duration?: number;
+    class?: string;
+}
+/**
+ * Text that scrambles through random glyphs before "decoding" into the final
+ * string, left to right, over `duration` ms. Runs once on mount by default;
+ * pass `trigger="hover"` to (re)run it — cleanly restarting if it's still
+ * mid-scramble — on pointer hover instead. Renders the final text as-is, with
+ * no scramble, when the user prefers reduced motion.
+ *
+ * @example
+ * ```tsx
+ * <ScrambleText text="ACCESS GRANTED" trigger="hover" duration={600} />
+ * ```
+ */
+export declare function ScrambleText(props: ScrambleTextProps): JSX.Element;

package/dist/ui/TextReveal.d.ts

@@ -0,0 +1,23 @@
+import { JSX } from 'solid-js';
+export interface TextRevealProps {
+    text: string;
+    /** Split unit. @default 'word' */
+    by?: 'word' | 'char';
+    /** Reveal when scrolled into view instead of on mount. @default false */
+    onView?: boolean;
+    class?: string;
+}
+/**
+ * Reveals `text`, split into words or characters, with a staggered
+ * fade + slide-up (via Motion's `animate` + `stagger`). Runs once on mount by
+ * default; pass `onView` to instead reveal the first time the component
+ * scrolls into view. Whitespace between words renders as plain text, not an
+ * animated unit. Under reduced motion, everything stays visible and no
+ * animation runs.
+ *
+ * @example
+ * ```tsx
+ * <TextReveal text="Ship it." by="char" onView />
+ * ```
+ */
+export declare function TextReveal(props: TextRevealProps): JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a4ui/core",
-  "version": "0.12.0",
+  "version": "0.13.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.12.0'
+export const A4UI_VERSION = '0.13.0'
 
 // Helpers (src/lib) — generic, framework-level utilities.
 export { cn } from './lib/cn'
@@ -131,6 +131,26 @@ export { Portal, type PortalProps } from './ui/Portal'
 export { Sortable, type SortableProps } from './ui/Sortable'
 export { Clock, type ClockProps } from './ui/Clock'
 
+// Motion components (src/ui) — animation primitives built on the `motion` engine
+// (adapted from motion.dev examples). All tree-shakeable and reduced-motion aware;
+// `motion` is external, so importing one of these is the only thing that pulls it.
+export { ScrambleText, type ScrambleTextProps } from './ui/ScrambleText'
+export { TextReveal, type TextRevealProps } from './ui/TextReveal'
+export { HoldToConfirm, type HoldToConfirmProps } from './ui/HoldToConfirm'
+export { LoadingDots, type LoadingDotsProps } from './ui/LoadingDots'
+export { Curtain, type CurtainProps, type CurtainVariant } from './ui/Curtain'
+export { Parallax, type ParallaxProps } from './ui/Parallax'
+export { FillText, type FillTextProps } from './ui/FillText'
+export {
+  NotificationStack,
+  type NotificationStackProps,
+  type StackNotification,
+} from './ui/NotificationStack'
+export { MultiStateBadge, type MultiStateBadgeProps, type BadgeState } from './ui/MultiStateBadge'
+export { NowPlaying, type NowPlayingProps } from './ui/NowPlaying'
+export { Expandable, type ExpandableProps } from './ui/Expandable'
+export { flyToCart, type FlyToCartOptions } from './lib/flyToCart'
+
 // Layout (src/layout) — generic shell + backdrop + toggles. App-coupled pieces
 // (Sidebar, Topbar, CompanySwitcher, DemoBanner, CommandPalette) stay in the app.
 export { AppShell } from './layout/AppShell'

package/src/lib/flyToCart.ts

@@ -0,0 +1,103 @@
+// The classic "add to basket" fly animation: a ghost of the product image
+// arcs from a source element (button/card) to a target element (the cart
+// icon), then the target bumps to acknowledge the drop. Pure JS/DOM (a
+// throwaway ghost node driven by Motion's `animate`), so it works from any
+// click handler without touching component state. Reduced motion skips the
+// flight entirely but still fires `onArrive` so cart counts stay correct.
+import { animate, motionReduced } from './motion'
+
+export interface FlyToCartOptions {
+  /** Image URL to fly; if omitted, the source element is cloned. */
+  image?: string
+  /** Flight duration in seconds. @default 0.6 */
+  duration?: number
+  /** Called when the flight finishes (e.g. to increment the cart count). */
+  onArrive?: () => void
+}
+
+/**
+ * Animate a small ghost from `source` to `target` (e.g. product → cart icon),
+ * then a bump on the target. No-op under reduced motion (still calls onArrive).
+ *
+ * @example
+ * ```ts
+ * function onAddToCart(e: MouseEvent) {
+ *   const button = e.currentTarget as HTMLElement
+ *   const cartIcon = document.getElementById('cart-icon')!
+ *   flyToCart(button, cartIcon, {
+ *     image: product.thumbnailUrl,
+ *     onArrive: () => setCartCount((n) => n + 1),
+ *   })
+ * }
+ * ```
+ */
+export function flyToCart(source: Element, target: Element, opts?: FlyToCartOptions): void {
+  if (typeof document === 'undefined') {
+    opts?.onArrive?.()
+    return
+  }
+
+  if (motionReduced()) {
+    opts?.onArrive?.()
+    return
+  }
+
+  try {
+    const sourceRect = source.getBoundingClientRect()
+    const targetRect = target.getBoundingClientRect()
+
+    const size = 48
+    const sourceCenterX = sourceRect.left + sourceRect.width / 2
+    const sourceCenterY = sourceRect.top + sourceRect.height / 2
+    const targetCenterX = targetRect.left + targetRect.width / 2
+    const targetCenterY = targetRect.top + targetRect.height / 2
+
+    const dx = targetCenterX - sourceCenterX
+    const dy = targetCenterY - sourceCenterY
+
+    const ghost: HTMLElement = opts?.image ? document.createElement('img') : document.createElement('div')
+    if (opts?.image) (ghost as HTMLImageElement).src = opts.image
+
+    ghost.style.position = 'fixed'
+    ghost.style.left = `${sourceCenterX - size / 2}px`
+    ghost.style.top = `${sourceCenterY - size / 2}px`
+    ghost.style.width = `${size}px`
+    ghost.style.height = `${size}px`
+    ghost.style.borderRadius = '9999px'
+    ghost.style.objectFit = 'cover'
+    ghost.style.pointerEvents = 'none'
+    ghost.style.zIndex = '9999'
+    if (!opts?.image) ghost.style.background = 'var(--a4-primary, #6366f1)'
+
+    document.body.appendChild(ghost)
+
+    const duration = opts?.duration ?? 0.6
+
+    const controls = animate(
+      ghost,
+      { x: [0, dx], y: [0, dy], scale: [1, 0.3], opacity: [1, 0.5] },
+      { duration, ease: 'easeInOut' },
+    )
+
+    controls.finished
+      .catch(() => {
+        /* stopped early — still clean up and settle below */
+      })
+      .then(() => {
+        ghost.remove()
+        opts?.onArrive?.()
+        try {
+          animate(target, { scale: [1, 1.25, 1] }, { duration: 0.3, ease: 'easeOut' })
+        } catch {
+          /* target no longer animatable — ignore */
+        }
+      })
+      .catch(() => {
+        /* onArrive threw — nothing more we can do here */
+      })
+  } catch {
+    // Rect reads / DOM writes can fail (detached nodes, hostile environments) —
+    // bail gracefully rather than throwing out of an event handler.
+    opts?.onArrive?.()
+  }
+}