@a4ui/core 0.12.0 → 0.13.0

package/src/ui/Curtain.tsx

@@ -0,0 +1,348 @@
+// Curtain — a controlled, full-screen cover→uncover transition primitive for
+// page/route transitions. It collapses motion.dev's "curtains" example family
+// (fade, sliding doors, blinds, shutter, iris, clip-wipe, pixels) into one component driven by a
+// single `show` boolean: `true` plays the "cover" animation (the curtain
+// closes over the screen), `false` plays "uncover" (the curtain opens,
+// revealing whatever's behind it). Swap your route content while covered —
+// `onCovered` fires the instant the screen is fully masked, `onRevealed`
+// once it's fully open again.
+import { createEffect, createSignal, For, Index, on, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced, stagger } from '../lib/motion'
+
+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
+}
+
+interface CurtainControls {
+  finished: Promise<unknown>
+  stop: () => void
+}
+
+type CurtainPhase = 'covered' | 'uncovered' | 'covering' | 'uncovering'
+
+const STRIP_COUNT = 8
+const STRIP_INDICES = Array.from({ length: STRIP_COUNT }, (_, i) => i)
+
+// `pixels` variant: a grid of tiles that pop in/out in a diagonal cascade.
+const PIXEL_COLS = 10
+const PIXEL_ROWS = 6
+const PIXEL_COUNT = PIXEL_COLS * PIXEL_ROWS
+const PIXEL_INDICES = Array.from({ length: PIXEL_COUNT }, (_, i) => i)
+
+function combine(controls: CurtainControls[]): CurtainControls {
+  return {
+    finished: Promise.all(controls.map((c) => c.finished)),
+    stop: () => {
+      for (const c of controls) c.stop()
+    },
+  }
+}
+
+/**
+ * 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 function Curtain(props: CurtainProps): JSX.Element {
+  // eslint-disable-next-line solid/reactivity -- initial seed only; reactivity handled in the createEffect below
+  const [phase, setPhase] = createSignal<CurtainPhase>(props.show ? 'covered' : 'uncovered')
+
+  let controls: CurtainControls | undefined
+  let panelA: HTMLDivElement | undefined
+  let panelB: HTMLDivElement | undefined
+  const strips: (HTMLDivElement | undefined)[] = []
+
+  const color = () => props.color ?? 'hsl(var(--background))'
+
+  function applyFinalState(variant: CurtainVariant, show: boolean): void {
+    switch (variant) {
+      case 'fade':
+        if (panelA) panelA.style.opacity = show ? '1' : '0'
+        break
+      case 'doors':
+        if (panelA) panelA.style.transform = show ? 'translateX(0%)' : 'translateX(-100%)'
+        if (panelB) panelB.style.transform = show ? 'translateX(0%)' : 'translateX(100%)'
+        break
+      case 'blinds':
+        for (const el of strips.slice(0, STRIP_COUNT))
+          if (el) el.style.transform = show ? 'scaleY(1)' : 'scaleY(0)'
+        break
+      case 'shutter':
+        for (const el of strips.slice(0, STRIP_COUNT))
+          if (el) el.style.transform = show ? 'scaleX(1)' : 'scaleX(0)'
+        break
+      case 'iris':
+        if (panelA) panelA.style.clipPath = show ? 'circle(150% at 50% 50%)' : 'circle(0% at 50% 50%)'
+        break
+      case 'clip':
+        if (panelA) panelA.style.clipPath = show ? 'inset(0 0 0 0)' : 'inset(0 100% 0 0)'
+        break
+      case 'pixels':
+        for (const el of strips.slice(0, PIXEL_COUNT)) if (el) el.style.opacity = show ? '1' : '0'
+        break
+    }
+  }
+
+  function play(variant: CurtainVariant, show: boolean, duration: number): CurtainControls | undefined {
+    const ease = 'easeInOut' as const
+
+    switch (variant) {
+      case 'fade': {
+        if (!panelA) return undefined
+        return animate(panelA, { opacity: show ? [0, 1] : [1, 0] }, { duration, ease })
+      }
+      case 'doors': {
+        if (!panelA || !panelB) return undefined
+        const left = animate(panelA, { x: show ? ['-100%', '0%'] : ['0%', '-100%'] }, { duration, ease })
+        const right = animate(panelB, { x: show ? ['100%', '0%'] : ['0%', '100%'] }, { duration, ease })
+        return combine([left, right])
+      }
+      case 'blinds': {
+        const els = strips.slice(0, STRIP_COUNT).filter((el): el is HTMLDivElement => el !== undefined)
+        if (els.length === 0) return undefined
+        return animate(els, { scaleY: show ? [0, 1] : [1, 0] }, { duration, delay: stagger(0.05), ease })
+      }
+      case 'shutter': {
+        const els = strips.slice(0, STRIP_COUNT).filter((el): el is HTMLDivElement => el !== undefined)
+        if (els.length === 0) return undefined
+        return animate(els, { scaleX: show ? [0, 1] : [1, 0] }, { duration, delay: stagger(0.05), ease })
+      }
+      case 'iris': {
+        if (!panelA) return undefined
+        return animate(
+          panelA,
+          {
+            clipPath: show
+              ? ['circle(0% at 50% 50%)', 'circle(150% at 50% 50%)']
+              : ['circle(150% at 50% 50%)', 'circle(0% at 50% 50%)'],
+          },
+          { duration, ease },
+        )
+      }
+      case 'clip': {
+        if (!panelA) return undefined
+        return animate(
+          panelA,
+          {
+            clipPath: show
+              ? ['inset(0 100% 0 0)', 'inset(0 0 0 0)']
+              : ['inset(0 0 0 0)', 'inset(0 100% 0 0)'],
+          },
+          { duration, ease },
+        )
+      }
+      case 'pixels': {
+        const els = strips.slice(0, PIXEL_COUNT).filter((el): el is HTMLDivElement => el !== undefined)
+        if (els.length === 0) return undefined
+        return animate(
+          els,
+          { opacity: show ? [0, 1] : [1, 0] },
+          { duration: duration * 0.5, delay: stagger(0.01, { from: 'first' }), ease },
+        )
+      }
+      default:
+        return undefined
+    }
+  }
+
+  // Initial paint: the panels' inline styles already sit in the "uncovered"
+  // pose, so we only need to snap them to "covered" when show starts true. No
+  // animation on mount — that would flash the curtain in from its covered pose.
+  onMount(() => {
+    if (props.show) applyFinalState(props.variant ?? 'fade', true)
+  })
+
+  // Animate ONLY when `show` actually toggles (defer skips the mount run; variant
+  // and duration are read untracked so switching variant while idle never plays).
+  createEffect(
+    on(
+      () => props.show,
+      (show) => {
+        const variant = props.variant ?? 'fade'
+        const duration = props.duration ?? 0.6
+
+        controls?.stop()
+        controls = undefined
+        setPhase(show ? 'covering' : 'uncovering')
+
+        const settle = () => {
+          setPhase(show ? 'covered' : 'uncovered')
+          if (show) props.onCovered?.()
+          else props.onRevealed?.()
+        }
+
+        if (motionReduced()) {
+          applyFinalState(variant, show)
+          queueMicrotask(settle)
+          return
+        }
+
+        const played = play(variant, show, duration)
+        if (!played) {
+          queueMicrotask(settle)
+          return
+        }
+
+        controls = played
+        played.finished.then(settle).catch(() => {})
+      },
+      { defer: true },
+    ),
+  )
+
+  onCleanup(() => controls?.stop())
+
+  return (
+    <div
+      class={cn('pointer-events-none fixed inset-0 z-[9999]', props.class)}
+      aria-hidden="true"
+      data-curtain-variant={props.variant ?? 'fade'}
+      data-curtain-state={phase()}
+    >
+      {(props.variant ?? 'fade') === 'fade' && (
+        <div
+          class="absolute inset-0"
+          style={{ position: 'absolute', opacity: 0, background: color() }}
+          ref={(el) => {
+            panelA = el
+          }}
+        />
+      )}
+
+      {(props.variant ?? 'fade') === 'doors' && (
+        <>
+          <div
+            class="absolute inset-y-0 left-0 w-1/2"
+            style={{ position: 'absolute', transform: 'translateX(-100%)', background: color() }}
+            ref={(el) => {
+              panelA = el
+            }}
+          />
+          <div
+            class="absolute inset-y-0 right-0 w-1/2"
+            style={{ position: 'absolute', transform: 'translateX(100%)', background: color() }}
+            ref={(el) => {
+              panelB = el
+            }}
+          />
+        </>
+      )}
+
+      {(props.variant ?? 'fade') === 'blinds' && (
+        <Index each={STRIP_INDICES}>
+          {(_, index) => (
+            <div
+              class="absolute left-0 h-[12.5%] w-full origin-top"
+              style={{
+                position: 'absolute',
+                top: `${index * 12.5}%`,
+                transform: 'scaleY(0)',
+                background: color(),
+              }}
+              ref={(el) => {
+                strips[index] = el
+              }}
+            />
+          )}
+        </Index>
+      )}
+
+      {(props.variant ?? 'fade') === 'shutter' && (
+        <For each={STRIP_INDICES}>
+          {(_, index) => (
+            <div
+              class="absolute top-0 h-full w-[12.5%] origin-left"
+              style={{
+                position: 'absolute',
+                left: `${index() * 12.5}%`,
+                transform: 'scaleX(0)',
+                background: color(),
+              }}
+              ref={(el) => {
+                strips[index()] = el
+              }}
+            />
+          )}
+        </For>
+      )}
+
+      {(props.variant ?? 'fade') === 'iris' && (
+        <div
+          class="absolute inset-0"
+          style={{ position: 'absolute', 'clip-path': 'circle(0% at 50% 50%)', background: color() }}
+          ref={(el) => {
+            panelA = el
+          }}
+        />
+      )}
+
+      {(props.variant ?? 'fade') === 'clip' && (
+        <div
+          class="absolute inset-0"
+          style={{ position: 'absolute', 'clip-path': 'inset(0 100% 0 0)', background: color() }}
+          ref={(el) => {
+            panelA = el
+          }}
+        />
+      )}
+
+      {(props.variant ?? 'fade') === 'pixels' && (
+        <div
+          class="absolute inset-0 grid"
+          style={{
+            'grid-template-columns': `repeat(${PIXEL_COLS}, 1fr)`,
+            'grid-template-rows': `repeat(${PIXEL_ROWS}, 1fr)`,
+          }}
+        >
+          <Index each={PIXEL_INDICES}>
+            {(_, index) => (
+              <div
+                style={{ opacity: 0, background: color() }}
+                ref={(el) => {
+                  strips[index] = el
+                }}
+              />
+            )}
+          </Index>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/ui/Expandable.tsx

@@ -0,0 +1,229 @@
+// Shared-element transition: a compact `trigger` (a card) morphs into an
+// expanded overlay panel and back, using a FLIP animation. We animate the
+// panel's position and SIZE (top/left/width/height) rather than a transform
+// scale, so its content never stretches. Covers the motion.dev "family dialog"
+// (size="dialog") and "app store layout" (size="full") patterns with one API.
+import { createSignal, Show, onCleanup, onMount, type JSX } from 'solid-js'
+import { Portal } from 'solid-js/web'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+type Rect = { top: number; left: number; width: number; height: number }
+
+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
+}
+
+const PAD = 24
+
+/**
+ * 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 function Expandable(props: ExpandableProps): JSX.Element {
+  const [open, setOpen] = createSignal(false)
+  let triggerEl: HTMLDivElement | undefined
+  let panelEl: HTMLDivElement | undefined
+  let backdropEl: HTMLDivElement | undefined
+  let originRect: Rect | undefined
+  let controls: ReturnType<typeof animate> | undefined
+
+  const rectOf = (el: Element): Rect => {
+    const r = el.getBoundingClientRect()
+    return { top: r.top, left: r.left, width: r.width, height: r.height }
+  }
+
+  // The panel's resting position/size, computed (not scaled) so text stays sharp.
+  const finalRect = (el: HTMLDivElement): Rect => {
+    const vw = window.innerWidth
+    const vh = window.innerHeight
+    if (props.size === 'full') {
+      const width = vw - PAD * 2
+      const height = vh - PAD * 2
+      return { left: PAD, top: PAD, width, height }
+    }
+    const width = Math.min(props.maxWidth ?? 640, vw - PAD * 2)
+    // Measure the natural height at the target width.
+    el.style.width = `${width}px`
+    el.style.height = 'auto'
+    el.style.maxHeight = `${vh - PAD * 2}px`
+    const natH = el.getBoundingClientRect().height
+    const height = Math.min(natH, vh - PAD * 2)
+    return { left: (vw - width) / 2, top: (vh - height) / 2, width, height }
+  }
+
+  const place = (el: HTMLDivElement, r: Rect) => {
+    el.style.top = `${r.top}px`
+    el.style.left = `${r.left}px`
+    el.style.width = `${r.width}px`
+    el.style.height = `${r.height}px`
+  }
+
+  const doOpen = () => {
+    if (open() || !triggerEl) return
+    originRect = rectOf(triggerEl)
+    setOpen(true)
+    props.onOpenChange?.(true)
+  }
+
+  // Runs once the portalled panel is in the DOM: FLIP from the card to the panel.
+  const runOpenFlip = () => {
+    const el = panelEl
+    if (!el) return
+    const final = finalRect(el)
+    if (motionReduced() || !originRect) {
+      place(el, final)
+      el.style.overflow = 'auto'
+      el.style.opacity = '1'
+      return
+    }
+    place(el, originRect) // first
+    el.style.opacity = '1'
+    void el.offsetWidth // force reflow
+    controls?.stop()
+    controls = animate(
+      el,
+      {
+        top: [originRect.top, final.top],
+        left: [originRect.left, final.left],
+        width: [originRect.width, final.width],
+        height: [originRect.height, final.height],
+      },
+      { type: 'spring', stiffness: 280, damping: 32 },
+    )
+    if (backdropEl) animate(backdropEl, { opacity: [0, 1] }, { duration: 0.25, ease: 'easeOut' })
+    controls.finished
+      .then(() => {
+        el.style.overflow = 'auto'
+      })
+      .catch(() => {})
+  }
+
+  const doClose = () => {
+    if (!open()) return
+    const el = panelEl
+    const back = triggerEl ? rectOf(triggerEl) : originRect
+    if (!el || !back || motionReduced()) {
+      finishClose()
+      return
+    }
+    controls?.stop()
+    el.style.overflow = 'hidden'
+    place(el, rectOf(el)) // pin current
+    void el.offsetWidth
+    controls = animate(
+      el,
+      { top: back.top, left: back.left, width: back.width, height: back.height, opacity: [1, 0.35] },
+      { duration: 0.3, ease: 'easeInOut' },
+    )
+    if (backdropEl) animate(backdropEl, { opacity: [1, 0] }, { duration: 0.25, ease: 'easeIn' })
+    controls.finished.then(finishClose).catch(finishClose)
+  }
+
+  const finishClose = () => {
+    setOpen(false)
+    props.onOpenChange?.(false)
+  }
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') doClose()
+  }
+
+  onMount(() => document.addEventListener('keydown', onKeyDown))
+  onCleanup(() => {
+    document.removeEventListener('keydown', onKeyDown)
+    controls?.stop()
+  })
+
+  return (
+    <>
+      <div
+        ref={triggerEl}
+        role="button"
+        tabindex={0}
+        class={cn('cursor-pointer', props.class)}
+        onClick={doOpen}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault()
+            doOpen()
+          }
+        }}
+      >
+        {props.trigger}
+      </div>
+
+      <Show when={open()}>
+        <Portal>
+          <div
+            ref={backdropEl}
+            aria-hidden="true"
+            onClick={doClose}
+            class="fixed inset-0 z-[9998] bg-black/50 backdrop-blur-sm"
+            style={{ opacity: motionReduced() ? '1' : '0' }}
+          />
+          <div
+            ref={(el) => {
+              panelEl = el
+              // Measure/FLIP after layout settles.
+              requestAnimationFrame(runOpenFlip)
+            }}
+            role="dialog"
+            aria-modal="true"
+            class={cn(
+              'card fixed z-[9999] overflow-hidden rounded-2xl border border-border bg-card shadow-2xl',
+              props.panelClass,
+            )}
+            style={{ opacity: '0', margin: '0' }}
+          >
+            <button
+              type="button"
+              aria-label="Close"
+              onClick={doClose}
+              class="absolute right-3 top-3 z-10 grid h-8 w-8 place-items-center rounded-full bg-muted/80 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+            >
+              <svg
+                viewBox="0 0 24 24"
+                class="h-4 w-4"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2.5"
+                stroke-linecap="round"
+                aria-hidden="true"
+              >
+                <path d="M6 6l12 12M18 6L6 18" />
+              </svg>
+            </button>
+            {props.children}
+          </div>
+        </Portal>
+      </Show>
+    </>
+  )
+}

package/src/ui/FillText.tsx

@@ -0,0 +1,63 @@
+// FillText — text with a color "fill" band sweeping left-to-right on loop,
+// for loading states. The sweep is a background-position animation clipped
+// to the glyphs via `background-clip: text`, driven by Motion's `animate`.
+// Falls back to plain static text under reduced motion.
+import { onCleanup, onMount, Show, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+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 function FillText(props: FillTextProps): JSX.Element {
+  let el!: HTMLSpanElement
+  let controls: { stop: () => void } | undefined
+
+  onMount(() => {
+    if (motionReduced()) return
+
+    controls = animate(
+      el,
+      { backgroundPosition: ['200% 0%', '-200% 0%'] },
+      { duration: props.duration ?? 1.6, ease: 'linear', repeat: Infinity },
+    )
+
+    onCleanup(() => controls?.stop())
+  })
+
+  return (
+    <span role="status" class={cn('font-medium', props.class)}>
+      <Show when={!motionReduced()} fallback={<span class="text-muted-foreground">{props.text}</span>}>
+        <span
+          ref={el}
+          style={{
+            background:
+              'linear-gradient(90deg, hsl(var(--muted-foreground)) 0%, hsl(var(--muted-foreground)) 40%, hsl(var(--foreground)) 50%, hsl(var(--muted-foreground)) 60%, hsl(var(--muted-foreground)) 100%)',
+            'background-size': '200% 100%',
+            '-webkit-background-clip': 'text',
+            'background-clip': 'text',
+            '-webkit-text-fill-color': 'transparent',
+            color: 'transparent',
+          }}
+        >
+          {props.text}
+        </span>
+      </Show>
+    </span>
+  )
+}