@a4ui/core 0.29.1 → 0.31.0

package/src/ui/MorphPresets.tsx

@@ -0,0 +1,218 @@
+// MorphPresets — thin, opinionated wrappers over IconMorphButton for common
+// two-state icon toggles (copy, play/pause, mute, lock, theme). Each preset
+// only supplies icons + sensible defaults; the morph animation itself lives
+// in IconMorphButton and is not reimplemented here.
+import type { JSX } from 'solid-js'
+import { Check, Copy, Lock, Moon, Pause, Play, Sun, Unlock, Volume2, VolumeX } from 'lucide-solid'
+
+import { IconMorphButton, type IconMorphButtonVariant } from './IconMorphButton'
+
+export interface CopyButtonProps {
+  /** Text copied to the clipboard when the button is pressed. */
+  value: string
+  /** Optional label shown next to the icon before copying. */
+  label?: JSX.Element
+  /** Optional label shown next to the icon once copied. */
+  copiedLabel?: JSX.Element
+  /** Visual style. Defaults to `'ghost'`. */
+  variant?: IconMorphButtonVariant
+  class?: string
+  'aria-label'?: string
+}
+
+/**
+ * Copy-to-clipboard button that morphs Copy → Check and auto-reverts after
+ * 1.5s.
+ *
+ * @example
+ * ```tsx
+ * <CopyButton value="npm install @a4ui/core" aria-label="Copy install command" />
+ * ```
+ */
+export function CopyButton(props: CopyButtonProps): JSX.Element {
+  return (
+    <IconMorphButton
+      inactive={<Copy size={18} />}
+      active={<Check size={18} />}
+      label={props.label}
+      activeLabel={props.copiedLabel}
+      variant={props.variant}
+      class={props.class}
+      aria-label={props['aria-label']}
+      revertAfter={1500}
+      onChange={(pressed) => {
+        if (pressed) void navigator.clipboard?.writeText(props.value)
+      }}
+    />
+  )
+}
+
+export interface PlayPauseButtonProps {
+  /** Controlled playing state. Omit to let the button manage its own state. */
+  pressed?: boolean
+  /** Initial playing state when uncontrolled. Defaults to `false`. */
+  defaultPressed?: boolean
+  /** Fired with the next playing state, controlled or uncontrolled. */
+  onChange?: (pressed: boolean) => void
+  /** Optional label shown next to the icon while paused. */
+  label?: JSX.Element
+  /** Optional label shown next to the icon while playing. */
+  activeLabel?: JSX.Element
+  /** Visual style. Defaults to `'ghost'`. */
+  variant?: IconMorphButtonVariant
+  class?: string
+  'aria-label'?: string
+}
+
+/**
+ * Play/pause toggle button whose icon morphs Play → Pause.
+ *
+ * @example
+ * ```tsx
+ * <PlayPauseButton defaultPressed={false} aria-label="Play" />
+ * ```
+ */
+export function PlayPauseButton(props: PlayPauseButtonProps): JSX.Element {
+  return (
+    <IconMorphButton
+      inactive={<Play size={18} />}
+      active={<Pause size={18} />}
+      pressed={props.pressed}
+      defaultPressed={props.defaultPressed}
+      onChange={props.onChange}
+      label={props.label}
+      activeLabel={props.activeLabel}
+      variant={props.variant}
+      class={props.class}
+      aria-label={props['aria-label']}
+    />
+  )
+}
+
+export interface MuteButtonProps {
+  /** Controlled muted state. Omit to let the button manage its own state. */
+  pressed?: boolean
+  /** Initial muted state when uncontrolled. Defaults to `false`. */
+  defaultPressed?: boolean
+  /** Fired with the next muted state, controlled or uncontrolled. */
+  onChange?: (pressed: boolean) => void
+  /** Optional label shown next to the icon while unmuted. */
+  label?: JSX.Element
+  /** Optional label shown next to the icon while muted. */
+  activeLabel?: JSX.Element
+  /** Visual style. Defaults to `'ghost'`. */
+  variant?: IconMorphButtonVariant
+  class?: string
+  'aria-label'?: string
+}
+
+/**
+ * Mute toggle button whose icon morphs Volume2 → VolumeX.
+ *
+ * @example
+ * ```tsx
+ * <MuteButton defaultPressed={false} aria-label="Mute" />
+ * ```
+ */
+export function MuteButton(props: MuteButtonProps): JSX.Element {
+  return (
+    <IconMorphButton
+      inactive={<Volume2 size={18} />}
+      active={<VolumeX size={18} />}
+      pressed={props.pressed}
+      defaultPressed={props.defaultPressed}
+      onChange={props.onChange}
+      label={props.label}
+      activeLabel={props.activeLabel}
+      variant={props.variant}
+      class={props.class}
+      aria-label={props['aria-label']}
+    />
+  )
+}
+
+export interface LockButtonProps {
+  /** Controlled locked state. Omit to let the button manage its own state. */
+  pressed?: boolean
+  /** Initial locked state when uncontrolled. Defaults to `false`. */
+  defaultPressed?: boolean
+  /** Fired with the next locked state, controlled or uncontrolled. */
+  onChange?: (pressed: boolean) => void
+  /** Optional label shown next to the icon while unlocked. */
+  label?: JSX.Element
+  /** Optional label shown next to the icon while locked. */
+  activeLabel?: JSX.Element
+  /** Visual style. Defaults to `'ghost'`. */
+  variant?: IconMorphButtonVariant
+  class?: string
+  'aria-label'?: string
+}
+
+/**
+ * Lock toggle button whose icon morphs Unlock → Lock.
+ *
+ * @example
+ * ```tsx
+ * <LockButton defaultPressed={false} aria-label="Lock" />
+ * ```
+ */
+export function LockButton(props: LockButtonProps): JSX.Element {
+  return (
+    <IconMorphButton
+      inactive={<Unlock size={18} />}
+      active={<Lock size={18} />}
+      pressed={props.pressed}
+      defaultPressed={props.defaultPressed}
+      onChange={props.onChange}
+      label={props.label}
+      activeLabel={props.activeLabel}
+      variant={props.variant}
+      class={props.class}
+      aria-label={props['aria-label']}
+    />
+  )
+}
+
+export interface ThemeMorphButtonProps {
+  /** Controlled dark-mode state. Omit to let the button manage its own state. */
+  pressed?: boolean
+  /** Initial dark-mode state when uncontrolled. Defaults to `false`. */
+  defaultPressed?: boolean
+  /** Fired with the next dark-mode state, controlled or uncontrolled. */
+  onChange?: (pressed: boolean) => void
+  /** Optional label shown next to the icon in light mode. */
+  label?: JSX.Element
+  /** Optional label shown next to the icon in dark mode. */
+  activeLabel?: JSX.Element
+  /** Visual style. Defaults to `'ghost'`. */
+  variant?: IconMorphButtonVariant
+  class?: string
+  'aria-label'?: string
+}
+
+/**
+ * Purely presentational theme toggle whose icon morphs Sun → Moon. Does not
+ * touch the theme system itself — wire `pressed`/`onChange` to your theme
+ * state.
+ *
+ * @example
+ * ```tsx
+ * <ThemeMorphButton pressed={isDark()} onChange={setIsDark} aria-label="Toggle theme" />
+ * ```
+ */
+export function ThemeMorphButton(props: ThemeMorphButtonProps): JSX.Element {
+  return (
+    <IconMorphButton
+      inactive={<Sun size={18} />}
+      active={<Moon size={18} />}
+      pressed={props.pressed}
+      defaultPressed={props.defaultPressed}
+      onChange={props.onChange}
+      label={props.label}
+      activeLabel={props.activeLabel}
+      variant={props.variant}
+      class={props.class}
+      aria-label={props['aria-label']}
+    />
+  )
+}

package/src/ui/SlideArrowButton.tsx

@@ -0,0 +1,108 @@
+// SlideArrowButton — CTA button where the label slides toward `direction` on
+// hover while an arrow slides in from the opposite edge. Pure CSS
+// (transform + opacity only), so it needs no JS animation engine and gets
+// the reduced-motion guard for free from the global @media block in styles.css.
+import type { JSX, ParentProps } from 'solid-js'
+import { Show, splitProps } from 'solid-js'
+import { ArrowLeft, ArrowRight } from 'lucide-solid'
+
+import { cn } from '../lib/cn'
+
+/** 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'
+
+const VARIANT_CLASSES: Record<SlideArrowButtonVariant, string> = {
+  solid: 'bg-primary text-primary-foreground hover:bg-primary/90',
+  outline: 'border border-border bg-transparent text-foreground hover:bg-muted',
+}
+
+const BUTTON_BASE =
+  'group relative inline-flex items-center justify-center overflow-hidden rounded-md px-4 py-2 text-sm font-medium focus:outline-none focus:ring-2 focus:ring-ring disabled:pointer-events-none disabled:opacity-50'
+
+// Both the label and the arrow only ever animate `transform`/`opacity` —
+// compositor-only properties — so this is a plain CSS transition, no JS
+// animation loop and no layout thrashing.
+const TRANSITION = 'transition-transform duration-200 ease-out'
+
+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 function SlideArrowButton(props: SlideArrowButtonProps): JSX.Element {
+  const [local, rest] = splitProps(props, [
+    'children',
+    'onClick',
+    'direction',
+    'icon',
+    'variant',
+    'disabled',
+    'class',
+    'aria-label',
+  ])
+
+  const direction = (): SlideArrowDirection => local.direction ?? 'right'
+  const isRight = () => direction() === 'right'
+
+  const icon = (): JSX.Element =>
+    local.icon ??
+    (isRight() ? (
+      <ArrowRight class="h-4 w-4" aria-hidden="true" />
+    ) : (
+      <ArrowLeft class="h-4 w-4" aria-hidden="true" />
+    ))
+
+  // Label slides fully out of the way (100%) in the hover direction, arrow
+  // slides in the same amount from the opposite edge — they swap places.
+  const labelClasses = (): string =>
+    cn(TRANSITION, isRight() ? 'group-hover:-translate-x-full' : 'group-hover:translate-x-full')
+
+  const arrowClasses = (): string =>
+    cn(
+      'absolute inset-0 flex items-center justify-center opacity-0',
+      TRANSITION,
+      'transition-[transform,opacity]',
+      isRight()
+        ? 'translate-x-full group-hover:translate-x-0 group-hover:opacity-100'
+        : '-translate-x-full group-hover:translate-x-0 group-hover:opacity-100',
+    )
+
+  return (
+    <button
+      type="button"
+      disabled={local.disabled}
+      class={cn(BUTTON_BASE, VARIANT_CLASSES[local.variant ?? 'solid'], local.class)}
+      aria-label={local['aria-label']}
+      onClick={(e) => local.onClick?.(e)}
+      {...rest}
+    >
+      <span class={labelClasses()}>{local.children}</span>
+      <Show when={!local.disabled}>
+        <span class={arrowClasses()}>{icon()}</span>
+      </Show>
+    </button>
+  )
+}

package/src/ui/TimeMachineStack.tsx

@@ -0,0 +1,197 @@
+// TimeMachineStack — Apple-style "time machine" depth stack: the active slide
+// sits full-size at the front while the rest recede into the screen behind it
+// (translated up, pushed back on Z, scaled down, dimmed), with a vertical
+// scrubber of real buttons to jump to any index. Only `transform`/`opacity`
+// are animated (Motion spring), so the stack stays compositor-only. Reduced
+// motion collapses to a flat view of just the active slide.
+import { createEffect, createSignal, For, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+
+// Depth-stack geometry, per unit of depth (slides behind the active one).
+const DY = 26 // px recede upward per depth step
+const DZ = 64 // px pushed back on z per depth step
+const SCALE_STEP = 0.08
+const MIN_SCALE = 0.7
+const OPACITY_STEP = 0.18
+
+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
+}
+
+interface DepthTransform {
+  y: number
+  z: number
+  scale: number
+  opacity: number
+  zIndex: number
+  pointerEvents: 'auto' | 'none'
+}
+
+// depth = index - active. depth 0 is the active (front) slide; depth > 0
+// slides recede behind it. depth < 0 are already-viewed slides — they fly
+// forward, out of the stack, and vanish rather than reversing the recede math.
+function depthTransform(index: number, active: number): DepthTransform {
+  const depth = index - active
+  if (depth >= 0) {
+    return {
+      y: -depth * DY,
+      z: -depth * DZ,
+      scale: Math.max(1 - depth * SCALE_STEP, MIN_SCALE),
+      opacity: Math.max(1 - depth * OPACITY_STEP, 0),
+      zIndex: -depth,
+      pointerEvents: depth === 0 ? 'auto' : 'none',
+    }
+  }
+  return { y: DY, z: DZ * 0.5, scale: 1.05, opacity: 0, zIndex: -depth, pointerEvents: 'none' }
+}
+
+/**
+ * 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 function TimeMachineStack(props: TimeMachineStackProps): JSX.Element {
+  const [internalActive, setInternalActive] = createSignal(props.defaultActive ?? 0)
+  const active = () => props.active ?? internalActive()
+
+  const goTo = (index: number): void => {
+    const clamped = Math.max(0, Math.min(props.slides.length - 1, index))
+    if (props.active === undefined) setInternalActive(clamped)
+    props.onChange?.(clamped)
+  }
+
+  const onKeyDown = (e: KeyboardEvent): void => {
+    if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
+      e.preventDefault()
+      goTo(active() + 1)
+    } else if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') {
+      e.preventDefault()
+      goTo(active() - 1)
+    }
+  }
+
+  const slideEls = new Map<number, HTMLElement>()
+  const controls = new Map<number, ReturnType<typeof animate>>()
+
+  const applyTransform = (index: number, animated: boolean): void => {
+    const el = slideEls.get(index)
+    if (!el) return
+
+    if (motionReduced()) {
+      // Flat: only the active slide is visible, no depth, no animation.
+      const isActive = index === active()
+      controls.get(index)?.stop()
+      el.style.transform = 'none'
+      el.style.opacity = isActive ? '1' : '0'
+      el.style.zIndex = isActive ? '1' : '0'
+      el.style.pointerEvents = isActive ? 'auto' : 'none'
+      return
+    }
+
+    const t = depthTransform(index, active())
+    el.style.zIndex = String(t.zIndex)
+    el.style.pointerEvents = t.pointerEvents
+
+    if (!animated) {
+      el.style.transform = `translateY(${t.y}px) translateZ(${t.z}px) scale(${t.scale})`
+      el.style.opacity = String(t.opacity)
+      return
+    }
+
+    controls.get(index)?.stop()
+    const anim = animate(
+      el,
+      { y: t.y, z: t.z, scale: t.scale, opacity: t.opacity },
+      { type: 'spring', stiffness: 300, damping: 32 },
+    )
+    controls.set(index, anim)
+  }
+
+  const syncAll = (animated: boolean): void => {
+    props.slides.forEach((_, index) => applyTransform(index, animated))
+  }
+
+  onMount(() => syncAll(false))
+  createEffect(() => {
+    active() // track active-index changes (controlled or internal)
+    syncAll(true)
+  })
+  onCleanup(() => controls.forEach((c) => c.stop()))
+
+  return (
+    <div class={cn('relative flex h-80 w-full gap-4', props.class)}>
+      <div
+        role="group"
+        aria-roledescription="time machine stack"
+        tabindex="0"
+        class="relative min-w-0 flex-1 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        style={{ perspective: '1200px' }}
+        onKeyDown={onKeyDown}
+      >
+        <div class="relative h-full w-full" style={{ 'transform-style': 'preserve-3d' }}>
+          <For each={props.slides}>
+            {(slide, index) => (
+              <div
+                ref={(el) => {
+                  slideEls.set(index(), el)
+                  onCleanup(() => slideEls.delete(index()))
+                }}
+                aria-hidden={index() !== active()}
+                class="absolute inset-0 origin-bottom overflow-hidden rounded-xl border border-border bg-card text-card-foreground shadow-lg will-change-transform"
+              >
+                {slide}
+              </div>
+            )}
+          </For>
+        </div>
+      </div>
+
+      <div
+        role="group"
+        aria-label="Jump to slide"
+        class="flex shrink-0 flex-col items-end justify-center gap-1.5"
+      >
+        <For each={props.slides}>
+          {(_, index) => (
+            <button
+              type="button"
+              aria-label={`Slide ${index() + 1} of ${props.slides.length}`}
+              aria-current={index() === active() ? 'true' : undefined}
+              onClick={() => goTo(index())}
+              class={cn(
+                'h-1.5 w-6 rounded-full transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                index() === active() ? 'bg-primary' : 'bg-muted hover:bg-muted-foreground/40',
+              )}
+            />
+          )}
+        </For>
+      </div>
+    </div>
+  )
+}