@a4ui/core 0.27.0 → 0.29.0

package/src/ui/ScrollScene.tsx

@@ -0,0 +1,70 @@
+// ScrollScene — binds a render prop to the element's own scroll progress (0
+// as it enters the viewport from the bottom, 1 as it leaves past the top),
+// for scroll-driven storytelling. Unlike Parallax (which applies a fixed
+// transform via Motion's `scroll`), this exposes the raw progress signal so
+// the caller decides what to do with it.
+import { createSignal, onCleanup, onMount, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+export interface ScrollSceneProps {
+  /** Render-prop receiving a reactive progress accessor (0..1). */
+  children: (progress: () => number) => JSX.Element
+  class?: string
+}
+
+/**
+ * Wraps `children` in an element that tracks its own scroll progress: 0 when
+ * its top edge reaches the bottom of the viewport, 1 when its bottom edge
+ * passes the top of the viewport. Progress is exposed as a reactive accessor
+ * via a render prop, so the caller drives whatever transform/animation it
+ * wants — this component only measures. Scroll position isn't itself motion,
+ * so it keeps measuring under `prefers-reduced-motion`; it just never
+ * animates anything on its own.
+ *
+ * @example
+ * ```tsx
+ * <ScrollScene>
+ *   {(progress) => (
+ *     <div style={{ opacity: progress() }}>Reveal on scroll</div>
+ *   )}
+ * </ScrollScene>
+ * ```
+ */
+export function ScrollScene(props: ScrollSceneProps): JSX.Element {
+  let root!: HTMLDivElement
+  const [progress, setProgress] = createSignal(0)
+
+  onMount(() => {
+    let ticking = false
+
+    const measure = () => {
+      ticking = false
+      const rect = root.getBoundingClientRect()
+      const viewportH = window.innerHeight
+      const raw = (viewportH - rect.top) / (viewportH + rect.height)
+      setProgress(Math.min(1, Math.max(0, raw)))
+    }
+
+    const onScrollOrResize = () => {
+      if (ticking) return
+      ticking = true
+      requestAnimationFrame(measure)
+    }
+
+    measure()
+    window.addEventListener('scroll', onScrollOrResize, { passive: true })
+    window.addEventListener('resize', onScrollOrResize, { passive: true })
+
+    onCleanup(() => {
+      window.removeEventListener('scroll', onScrollOrResize)
+      window.removeEventListener('resize', onScrollOrResize)
+    })
+  })
+
+  return (
+    <div ref={root} class={cn(props.class)}>
+      {props.children(progress)}
+    </div>
+  )
+}

package/src/ui/SideRail.tsx

@@ -0,0 +1,120 @@
+// Vertical navigation rail — the vertical alternative to BottomNavigation / a
+// compact sidebar. Icon-first, optional labels under each icon; when labels
+// are hidden, the icon is wrapped in a Tooltip instead.
+import type { JSX } from 'solid-js'
+import { For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Tooltip } from './Tooltip'
+
+/** A single destination within a {@link SideRail}. */
+export interface SideRailItem {
+  value: string
+  label: string
+  icon?: JSX.Element
+  /** Optional badge (e.g. an unread count) rendered on the item. */
+  badge?: JSX.Element
+}
+
+export interface SideRailProps {
+  items: SideRailItem[]
+  value: string
+  onChange: (value: string) => void
+  /** Show text labels under icons. When false, labels go in a tooltip. @default true */
+  labels?: boolean
+  class?: string
+}
+
+/**
+ * Narrow vertical column of stacked icon+label destinations — the vertical
+ * counterpart to {@link BottomNavigation} for side placement. The active item
+ * is highlighted with a left indicator bar and `aria-selected`. ArrowUp/
+ * ArrowDown move the selection between items (roving activation, matching the
+ * WAI-ARIA tabs pattern). Renders inline where placed — the consumer is
+ * responsible for positioning (e.g. `fixed inset-y-0 left-0`).
+ *
+ * @example
+ * ```tsx
+ * <SideRail
+ *   value={section()}
+ *   onChange={setSection}
+ *   items={[
+ *     { value: 'home', label: 'Home', icon: <HomeIcon /> },
+ *     { value: 'inbox', label: 'Inbox', icon: <InboxIcon />, badge: <Badge tone="info">3</Badge> },
+ *     { value: 'settings', label: 'Settings', icon: <SettingsIcon /> },
+ *   ]}
+ * />
+ * ```
+ */
+export function SideRail(props: SideRailProps): JSX.Element {
+  const showLabels = () => props.labels ?? true
+
+  const move = (delta: 1 | -1, currentIndex: number) => {
+    const count = props.items.length
+    const nextIndex = (currentIndex + delta + count) % count
+    const next = props.items[nextIndex]
+    if (next) props.onChange(next.value)
+  }
+
+  return (
+    <div
+      role="tablist"
+      aria-orientation="vertical"
+      class={cn('flex w-20 flex-col items-stretch gap-1 border-r border-border bg-glass py-2', props.class)}
+    >
+      <For each={props.items}>
+        {(item, index) => {
+          const active = () => item.value === props.value
+
+          const onKeyDown = (event: KeyboardEvent) => {
+            if (event.key === 'ArrowDown') {
+              event.preventDefault()
+              move(1, index())
+            } else if (event.key === 'ArrowUp') {
+              event.preventDefault()
+              move(-1, index())
+            }
+          }
+
+          const button = (
+            <button
+              type="button"
+              role="tab"
+              aria-selected={active()}
+              tabIndex={active() ? 0 : -1}
+              onClick={() => props.onChange(item.value)}
+              onKeyDown={onKeyDown}
+              class={cn(
+                'relative flex flex-col items-center gap-1 px-2 py-2.5 text-[11px] transition-colors',
+                active() ? 'text-primary' : 'text-muted-foreground hover:text-foreground',
+              )}
+            >
+              <span
+                aria-hidden="true"
+                class={cn(
+                  'absolute inset-y-1 left-0 w-0.5 rounded-full bg-primary transition-opacity',
+                  active() ? 'opacity-100' : 'opacity-0',
+                )}
+              />
+              <span class="relative inline-flex">
+                {item.icon}
+                <Show when={item.badge}>
+                  <span class="absolute -right-2 -top-2">{item.badge}</span>
+                </Show>
+              </span>
+              <Show when={showLabels()}>
+                <span class="truncate">{item.label}</span>
+              </Show>
+            </button>
+          )
+
+          return (
+            <Show when={showLabels()} fallback={<Tooltip content={item.label}>{button}</Tooltip>}>
+              {button}
+            </Show>
+          )
+        }}
+      </For>
+    </div>
+  )
+}

package/src/ui/Spaces.tsx

@@ -0,0 +1,139 @@
+// Switchable "context" containers (like browser Spaces / workspaces): one
+// space's content is visible at a time, sliding horizontally between spaces
+// on a translateX track (mirrors Carousel's pointer-drag swipe), with a
+// dot/pill indicator rail below. Controlled (`activeId`+`onChange`) or
+// uncontrolled (internal signal, defaults to the first space).
+import { createMemo, createSignal, For, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface Space {
+  id: string
+  label: string
+  icon?: JSX.Element
+  content: JSX.Element
+}
+
+export interface SpacesProps {
+  spaces: Space[]
+  /** Controlled active space. Uncontrolled (internal signal, defaults to the first space) when omitted. */
+  activeId?: string
+  onChange?: (id: string) => void
+  class?: string
+}
+
+/**
+ * Swipeable, switchable "context" containers — one space visible at a time,
+ * sliding horizontally between spaces, with a dot/pill indicator rail to jump
+ * directly to one. Drag/touch to swipe (the track follows the pointer and
+ * snaps on release past a threshold), same engine-free approach as Carousel.
+ *
+ * @example
+ * ```tsx
+ * <Spaces
+ *   spaces={[
+ *     { id: 'personal', label: 'Personal', icon: <User class="h-4 w-4" />, content: <PersonalPane /> },
+ *     { id: 'work', label: 'Work', icon: <Briefcase class="h-4 w-4" />, content: <WorkPane /> },
+ *   ]}
+ * />
+ * ```
+ */
+export function Spaces(props: SpacesProps): JSX.Element {
+  const [internalId, setInternalId] = createSignal<string | undefined>(props.spaces[0]?.id)
+
+  const activeId = createMemo(() => props.activeId ?? internalId())
+  const count = (): number => props.spaces.length
+  const activeIndex = createMemo(() => {
+    const i = props.spaces.findIndex((s) => s.id === activeId())
+    return i < 0 ? 0 : i
+  })
+
+  const select = (id: string): void => {
+    if (props.activeId === undefined) setInternalId(id)
+    props.onChange?.(id)
+  }
+  const selectIndex = (i: number): void => {
+    const n = count()
+    if (n === 0) return
+    const space = props.spaces[((i % n) + n) % n]
+    if (space) select(space.id)
+  }
+
+  // --- drag/touch swipe (engine-free; the track follows the pointer, then the
+  // CSS transition snaps to the resolved space on release) -------------------
+  let viewport: HTMLDivElement | undefined
+  const [dragging, setDragging] = createSignal(false)
+  const [dragPx, setDragPx] = createSignal(0)
+  let startX = 0
+
+  const onPointerDown = (e: PointerEvent): void => {
+    if (count() < 2) return
+    startX = e.clientX
+    setDragging(true)
+    ;(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId)
+  }
+  const onPointerMove = (e: PointerEvent): void => {
+    if (dragging()) setDragPx(e.clientX - startX)
+  }
+  const endDrag = (): void => {
+    if (!dragging()) return
+    const width = viewport?.clientWidth ?? 1
+    const dx = dragPx()
+    const threshold = Math.max(48, width * 0.2)
+    if (dx <= -threshold) selectIndex(activeIndex() + 1)
+    else if (dx >= threshold) selectIndex(activeIndex() - 1)
+    setDragPx(0)
+    setDragging(false)
+  }
+
+  return (
+    <div class={cn('flex flex-col gap-3', props.class)}>
+      <div
+        ref={viewport}
+        class="relative overflow-hidden rounded-xl border border-border bg-card text-card-foreground"
+      >
+        <div
+          class={cn(
+            'flex',
+            count() > 1 && 'touch-pan-y cursor-grab active:cursor-grabbing',
+            !dragging() && !motionReduced() && 'transition-transform duration-500 ease-out',
+          )}
+          style={{ transform: `translateX(calc(-${activeIndex() * 100}% + ${dragPx()}px))` }}
+          onPointerDown={onPointerDown}
+          onPointerMove={onPointerMove}
+          onPointerUp={endDrag}
+          onPointerCancel={endDrag}
+        >
+          <For each={props.spaces}>{(space) => <div class="w-full shrink-0">{space.content}</div>}</For>
+        </div>
+      </div>
+
+      <div role="tablist" aria-label="Spaces" class="flex items-center justify-center gap-1">
+        <For each={props.spaces}>
+          {(space) => {
+            const isActive = () => space.id === activeId()
+            return (
+              <button
+                type="button"
+                role="tab"
+                aria-selected={isActive()}
+                aria-label={space.label}
+                onClick={() => select(space.id)}
+                class={cn(
+                  'flex h-7 items-center gap-1.5 rounded-full px-2 text-xs font-medium transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                  isActive()
+                    ? 'bg-primary text-primary-foreground'
+                    : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+                )}
+              >
+                {space.icon}
+                <span class={cn(!isActive() && 'sr-only sm:not-sr-only')}>{space.label}</span>
+              </button>
+            )
+          }}
+        </For>
+      </div>
+    </div>
+  )
+}

package/src/ui/StickyReveal.tsx

@@ -0,0 +1,103 @@
+// StickyReveal — a tall scroll region whose inner content pins in place
+// (`position: sticky`) while a subtle fade/rise reveal plays as the section
+// scrolls through the viewport. Built for a pinned hero/feature moment, not
+// for scrollytelling with multiple discrete steps (see ScrollProgress-style
+// primitives for that). Listener is bound in onMount (client-only, SSR-safe)
+// and rAF-throttled; skipped entirely under reduced motion.
+import type { JSX } from 'solid-js'
+import { createSignal, onCleanup, onMount } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { motionReduced } from '../lib/motion'
+
+export interface StickyRevealProps {
+  children: JSX.Element
+  /** Total scroll distance of the section (the taller it is, the longer the pin). CSS length, e.g. '200vh'. @default '180vh' */
+  height?: string
+  class?: string
+}
+
+// Reveal ramps in over the first 40% of scroll progress through the section,
+// then holds fully visible, then fades back out over the last 15% so the
+// content doesn't just vanish when the pin releases.
+const REVEAL_END = 0.4
+const FADE_OUT_START = 0.85
+
+/**
+ * A pinned hero/feature section: the outer element reserves `height` of
+ * scroll distance while the inner content sticks to the viewport and fades +
+ * rises in as the user scrolls through it. Needs real scroll room above/below
+ * to see the effect — drop it inside a page with enough surrounding content
+ * (or bump `height`) rather than in a short isolated container.
+ *
+ * @example
+ * ```tsx
+ * <StickyReveal height="200vh">
+ *   <Card class="p-10 text-center">
+ *     <h2 class="text-3xl font-bold">Pinned moment</h2>
+ *   </Card>
+ * </StickyReveal>
+ * ```
+ */
+export function StickyReveal(props: StickyRevealProps): JSX.Element {
+  const reduced = motionReduced()
+  const [progress, setProgress] = createSignal(reduced ? 1 : 0)
+
+  let outerEl: HTMLDivElement | undefined
+  let rafId: number | null = null
+
+  const measure = () => {
+    rafId = null
+    if (!outerEl) return
+    const rect = outerEl.getBoundingClientRect()
+    const viewportH = window.innerHeight || 1
+    const total = rect.height - viewportH
+    if (total <= 0) {
+      setProgress(1)
+      return
+    }
+    const raw = -rect.top / total
+    setProgress(Math.min(1, Math.max(0, raw)))
+  }
+
+  const onScroll = () => {
+    if (rafId !== null) return
+    rafId = requestAnimationFrame(measure)
+  }
+
+  onMount(() => {
+    if (reduced) return
+    measure()
+    window.addEventListener('scroll', onScroll, { passive: true })
+    window.addEventListener('resize', onScroll, { passive: true })
+    onCleanup(() => {
+      window.removeEventListener('scroll', onScroll)
+      window.removeEventListener('resize', onScroll)
+      if (rafId !== null) cancelAnimationFrame(rafId)
+    })
+  })
+
+  const visibility = () => {
+    const p = progress()
+    const rampIn = Math.min(1, p / REVEAL_END)
+    const rampOut = p <= FADE_OUT_START ? 1 : Math.max(0, 1 - (p - FADE_OUT_START) / (1 - FADE_OUT_START))
+    return Math.min(rampIn, rampOut)
+  }
+
+  const innerStyle = (): JSX.CSSProperties => {
+    if (reduced) return { opacity: 1, transform: 'none' }
+    const v = visibility()
+    return {
+      opacity: v,
+      transform: `translateY(${(1 - v) * 24}px)`,
+    }
+  }
+
+  return (
+    <div ref={outerEl} class={cn('relative', props.class)} style={{ height: props.height ?? '180vh' }}>
+      <div class="sticky top-0 flex h-screen items-center justify-center">
+        <div style={innerStyle()}>{props.children}</div>
+      </div>
+    </div>
+  )
+}

package/src/ui/TransactionFeed.tsx

@@ -0,0 +1,130 @@
+// Dense transaction/activity list for finance dashboards: icon, title +
+// subtitle on the left, currency amount (+ optional date) on the right.
+// Outgoing amounts render in the default foreground; incoming amounts use a
+// success text tone (never a hardcoded green) so it recolors with the theme.
+import { For, Show, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single row in a {@link TransactionFeed}. */
+export interface Transaction {
+  id: string
+  title: string
+  subtitle?: string
+  /** Negative = outgoing, positive (or zero) = incoming. */
+  amount: number
+  /** ISO or display string. Required to group rows when `groupByDate` is set. */
+  date?: string
+  icon?: JSX.Element
+}
+
+export interface TransactionFeedProps {
+  transactions: Transaction[]
+  /** ISO 4217 currency code. Defaults to `'USD'`. */
+  currency?: string
+  /** BCP 47 locale used for formatting. Defaults to `'en-US'`. */
+  locale?: string
+  /** Group rows under date headers (uses each tx.date). @default false */
+  groupByDate?: boolean
+  class?: string
+}
+
+interface TransactionGroup {
+  date: string
+  items: Transaction[]
+}
+
+/** Groups transactions by `date`, preserving first-seen order of each group. */
+function groupTransactions(transactions: Transaction[]): TransactionGroup[] {
+  const groups: TransactionGroup[] = []
+  const byDate = new Map<string, TransactionGroup>()
+  for (const tx of transactions) {
+    const key = tx.date ?? ''
+    let group = byDate.get(key)
+    if (!group) {
+      group = { date: key, items: [] }
+      byDate.set(key, group)
+      groups.push(group)
+    }
+    group.items.push(tx)
+  }
+  return groups
+}
+
+/**
+ * Dense vertical list of transactions/activity for finance dashboards. Each
+ * row shows an optional leading icon, a title + subtitle, and the amount
+ * formatted as currency — incoming (`amount >= 0`) in a success text tone,
+ * outgoing as `-$X` in the default foreground. Optionally groups rows under
+ * `text-xs uppercase` date headers via `groupByDate`.
+ *
+ * @example
+ * ```tsx
+ * <TransactionFeed
+ *   transactions={[
+ *     { id: '1', title: 'Acme Corp', subtitle: 'Invoice #1042', amount: 1200, date: '2026-07-18' },
+ *     { id: '2', title: 'Cloud Hosting', subtitle: 'Monthly plan', amount: -49.99, date: '2026-07-17' },
+ *   ]}
+ * />
+ * ```
+ */
+export function TransactionFeed(props: TransactionFeedProps): JSX.Element {
+  const format = (value: number) =>
+    new Intl.NumberFormat(props.locale ?? 'en-US', {
+      style: 'currency',
+      currency: props.currency ?? 'USD',
+    }).format(Math.abs(value))
+
+  const row = (tx: Transaction, showDate: boolean) => (
+    <li class="flex items-center gap-3 py-2.5">
+      <Show when={tx.icon}>
+        <div class="flex h-9 w-9 shrink-0 items-center justify-center rounded-full bg-muted">{tx.icon}</div>
+      </Show>
+      <div class="min-w-0 flex-1">
+        <p class="truncate text-sm font-medium text-foreground">{tx.title}</p>
+        <Show when={tx.subtitle}>
+          <p class="truncate text-xs text-muted-foreground">{tx.subtitle}</p>
+        </Show>
+      </div>
+      <div class="shrink-0 text-right">
+        <p
+          class={cn(
+            'text-sm font-medium tabular-nums',
+            tx.amount >= 0 ? 'text-emerald-400 light:text-emerald-700' : 'text-foreground',
+          )}
+        >
+          {tx.amount >= 0 ? format(tx.amount) : `-${format(tx.amount)}`}
+        </p>
+        <Show when={showDate && tx.date}>
+          <p class="text-xs text-muted-foreground">{tx.date}</p>
+        </Show>
+      </div>
+    </li>
+  )
+
+  return (
+    <Show
+      when={props.groupByDate}
+      fallback={
+        <ul class={cn('divide-y divide-border/60', props.class)}>
+          <For each={props.transactions}>{(tx) => row(tx, true)}</For>
+        </ul>
+      }
+    >
+      <div class={cn('flex flex-col gap-4', props.class)}>
+        <For each={groupTransactions(props.transactions)}>
+          {(group) => (
+            <div>
+              <Show when={group.date}>
+                <p class="mb-1 text-xs uppercase text-muted-foreground">{group.date}</p>
+              </Show>
+              <ul class="divide-y divide-border/60">
+                <For each={group.items}>{(tx) => row(tx, false)}</For>
+              </ul>
+            </div>
+          )}
+        </For>
+      </div>
+    </Show>
+  )
+}