@a4ui/core 0.26.0 → 0.28.0

package/src/ui/DataView.tsx

@@ -0,0 +1,198 @@
+// One dataset, three switchable presentations: table (reuses Table), board
+// (rows grouped into columns, Kanban-style), and gallery (a card grid). The
+// view switcher reuses SegmentedControl; board/gallery cards fall back to a
+// simple key/value list when no `card` renderer is given.
+import type { JSX } from 'solid-js'
+import { createMemo, createSignal, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Badge } from './Badge'
+import type { SegmentedOption } from './SegmentedControl'
+import { SegmentedControl } from './SegmentedControl'
+import { Table, TableBody, TableCell, TableHead, TableHeadCell, TableRow } from './Table'
+
+/** A single table column for {@link DataView}'s table presentation. */
+export interface DataViewColumn<T> {
+  /** Row property this column reads. */
+  key: string
+  /** Column heading text. */
+  header: string
+  /** Custom cell renderer; falls back to `String(row[key])` when omitted. */
+  cell?: (row: T) => JSX.Element
+}
+
+/** Presentation mode offered by {@link DataView}. */
+export type DataViewMode = 'table' | 'board' | 'gallery'
+
+/** Props for {@link DataView}. */
+export interface DataViewProps<T> {
+  data: T[]
+  /** Table columns; also used as the source of truth in board/gallery fallbacks. */
+  columns: DataViewColumn<T>[]
+  /** Stable row identifier, used as a DOM hook for tests/a11y. */
+  getId: (row: T) => string
+  /** For board view: group rows into columns by this key. If omitted, board mode is not offered. */
+  groupBy?: (row: T) => string
+  /** Card renderer for board + gallery. Falls back to a simple key/value list. */
+  card?: (row: T) => JSX.Element
+  /** Which views to offer (in order). Default: `['table', 'gallery']` plus `'board'` when `groupBy` is set. */
+  views?: DataViewMode[]
+  /** Controlled current view. Uncontrolled (internal signal) when omitted. */
+  view?: DataViewMode
+  onViewChange?: (view: DataViewMode) => void
+  class?: string
+}
+
+const MODE_LABELS: Record<DataViewMode, string> = {
+  table: 'Table',
+  board: 'Board',
+  gallery: 'Gallery',
+}
+
+function defaultModes<T>(props: DataViewProps<T>): DataViewMode[] {
+  if (props.views) return props.views
+  return props.groupBy ? ['table', 'board', 'gallery'] : ['table', 'gallery']
+}
+
+/** Key/value fallback used for board + gallery cards when no `card` renderer is given. */
+function FallbackCard<T>(props: { row: T }): JSX.Element {
+  const entries = () => Object.entries(props.row as Record<string, unknown>)
+  return (
+    <dl class="flex flex-col gap-1 text-sm">
+      <For each={entries()}>
+        {([key, value]) => (
+          <div class="flex items-center justify-between gap-3">
+            <dt class="text-muted-foreground">{key}</dt>
+            <dd class="truncate font-medium text-foreground">{String(value)}</dd>
+          </div>
+        )}
+      </For>
+    </dl>
+  )
+}
+
+/**
+ * One dataset, switchable between table, board (grouped columns), and
+ * gallery (card grid) presentations. Generic over the row type — pass
+ * `columns` for the table, an optional `groupBy` to enable the board view,
+ * and an optional `card` renderer reused by board + gallery.
+ *
+ * @example
+ * ```tsx
+ * <DataView
+ *   data={tasks}
+ *   getId={(t) => t.id}
+ *   columns={[
+ *     { key: 'title', header: 'Title' },
+ *     { key: 'status', header: 'Status' },
+ *   ]}
+ *   groupBy={(t) => t.status}
+ *   card={(t) => <span class="font-medium">{t.title}</span>}
+ * />
+ * ```
+ */
+export function DataView<T>(props: DataViewProps<T>): JSX.Element {
+  const modes = createMemo<DataViewMode[]>(() => defaultModes(props))
+
+  const [internalView, setInternalView] = createSignal<DataViewMode>(props.view ?? modes()[0] ?? 'table')
+
+  const view = createMemo(() => props.view ?? internalView())
+
+  const setView = (next: DataViewMode) => {
+    if (props.view === undefined) setInternalView(next)
+    props.onViewChange?.(next)
+  }
+
+  const options = createMemo<SegmentedOption[]>(() =>
+    modes().map((mode) => ({ value: mode, label: MODE_LABELS[mode] })),
+  )
+
+  const groups = createMemo(() => {
+    const groupBy = props.groupBy
+    if (!groupBy) return []
+    const byKey = new Map<string, T[]>()
+    for (const row of props.data) {
+      const key = groupBy(row)
+      const bucket = byKey.get(key)
+      if (bucket) bucket.push(row)
+      else byKey.set(key, [row])
+    }
+    return Array.from(byKey.entries()).map(([key, rows]) => ({ key, rows }))
+  })
+
+  return (
+    <div class={cn('flex w-full flex-col gap-4', props.class)}>
+      <div class="flex items-center justify-end">
+        <SegmentedControl
+          value={view()}
+          onChange={(next) => setView(next as DataViewMode)}
+          options={options()}
+        />
+      </div>
+
+      <Show when={view() === 'table'}>
+        <Table>
+          <TableHead>
+            <TableRow>
+              <For each={props.columns}>{(column) => <TableHeadCell>{column.header}</TableHeadCell>}</For>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            <For each={props.data}>
+              {(row) => (
+                <TableRow data-row-id={props.getId(row)}>
+                  <For each={props.columns}>
+                    {(column) => (
+                      <TableCell>
+                        {column.cell?.(row) ?? String((row as Record<string, unknown>)[column.key])}
+                      </TableCell>
+                    )}
+                  </For>
+                </TableRow>
+              )}
+            </For>
+          </TableBody>
+        </Table>
+      </Show>
+
+      <Show when={view() === 'board' && props.groupBy}>
+        <div class="flex gap-4 overflow-x-auto">
+          <For each={groups()}>
+            {(group) => (
+              <div class="flex min-w-64 flex-col gap-3 rounded-xl border border-border bg-card p-3 text-card-foreground">
+                <div class="flex items-center justify-between gap-2 text-sm font-semibold">
+                  <span class="truncate">{group.key}</span>
+                  <Badge tone="neutral">{group.rows.length}</Badge>
+                </div>
+                <div class="flex flex-col gap-2">
+                  <For each={group.rows}>
+                    {(row) => (
+                      <div
+                        data-row-id={props.getId(row)}
+                        class="rounded-lg border border-border bg-background p-3"
+                      >
+                        {props.card?.(row) ?? <FallbackCard row={row} />}
+                      </div>
+                    )}
+                  </For>
+                </div>
+              </div>
+            )}
+          </For>
+        </div>
+      </Show>
+
+      <Show when={view() === 'gallery'}>
+        <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          <For each={props.data}>
+            {(row) => (
+              <div data-row-id={props.getId(row)} class="card rounded-xl bg-card p-4 text-card-foreground">
+                {props.card?.(row) ?? <FallbackCard row={row} />}
+              </div>
+            )}
+          </For>
+        </div>
+      </Show>
+    </div>
+  )
+}

package/src/ui/KpiBlock.tsx

@@ -0,0 +1,58 @@
+// Labelled metric block for dashboards: value + a signed delta chip, with an
+// optional inline chart slot (e.g. a Sparkline from @a4ui/core/charts) passed
+// in by the consumer — this component never imports the charts package.
+import { ArrowDown, ArrowUp } from 'lucide-solid'
+import { Show, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Badge } from './Badge'
+import { Card, CardContent } from './Card'
+
+export interface KpiBlockProps {
+  label: string
+  value: string | number
+  /** Change as a fraction (0.128 = +12.8%). Shows a signed up/down chip. */
+  delta?: number
+  /** Optional chart node (e.g. a <Sparkline/> from @a4ui/core/charts) shown at the bottom. */
+  chart?: JSX.Element
+  class?: string
+}
+
+const formatDelta = (delta: number) => `${delta >= 0 ? '+' : ''}${(delta * 100).toFixed(1)}%`
+
+/**
+ * Labelled metric tile for dashboards: a large value with a signed
+ * up/down delta chip and an optional chart slot at the bottom. The chart is
+ * consumer-supplied (e.g. a `<Sparkline/>` from `@a4ui/core/charts`) — this
+ * component takes it as a prop rather than importing the charts package.
+ *
+ * @example
+ * ```tsx
+ * <KpiBlock label="Monthly revenue" value="$48,204" delta={0.128} />
+ * ```
+ */
+export function KpiBlock(props: KpiBlockProps): JSX.Element {
+  return (
+    <Card glass class={props.class}>
+      <CardContent class="p-5">
+        <p class="text-sm text-muted-foreground">{props.label}</p>
+        <div class="mt-1 flex items-center gap-2">
+          <span class="text-2xl font-semibold text-foreground">{props.value}</span>
+          <Show when={props.delta !== undefined}>
+            <Badge tone={(props.delta as number) >= 0 ? 'success' : 'danger'}>
+              {(props.delta as number) >= 0 ? (
+                <ArrowUp class="h-3 w-3" aria-hidden="true" />
+              ) : (
+                <ArrowDown class="h-3 w-3" aria-hidden="true" />
+              )}
+              {formatDelta(props.delta as number)}
+            </Badge>
+          </Show>
+        </div>
+        <Show when={props.chart}>
+          <div class={cn('mt-3')}>{props.chart}</div>
+        </Show>
+      </CardContent>
+    </Card>
+  )
+}

package/src/ui/MoneyActionButton.tsx

@@ -0,0 +1,54 @@
+// Prominent CTA reserved for value-moving actions (send / request / pay /
+// withdraw). One accent, tightly scoped to money movement — deliberately
+// bolder than the generic Button so it reads as "this moves money" at a
+// glance, distinct from ordinary actions elsewhere in the UI.
+import { ArrowDownLeft, ArrowUpRight, Banknote, CreditCard } from 'lucide-solid'
+import type { Component, JSX } from 'solid-js'
+import { splitProps } from 'solid-js'
+import { Dynamic } from 'solid-js/web'
+
+import { cn } from '../lib/cn'
+
+/** Money-movement action a {@link MoneyActionButton} represents; picks the leading icon. */
+export type MoneyActionKind = 'send' | 'request' | 'pay' | 'withdraw'
+
+const KIND_ICON: Record<MoneyActionKind, Component<{ class?: string }>> = {
+  send: ArrowUpRight,
+  request: ArrowDownLeft,
+  pay: CreditCard,
+  withdraw: Banknote,
+}
+
+export interface MoneyActionButtonProps {
+  children: JSX.Element
+  /** Which money-movement action this triggers. Defaults to `'send'`. */
+  kind?: MoneyActionKind
+  onClick?: () => void
+  disabled?: boolean
+  class?: string
+}
+
+const BASE =
+  'inline-flex h-full items-center justify-center gap-2 rounded-xl px-5 py-3 text-sm font-semibold bg-primary text-primary-foreground transition-[background-color,transform] duration-150 motion-reduce:transition-none hover:bg-primary/90 active:scale-[0.98] focus:outline-none focus:ring-2 focus:ring-ring disabled:pointer-events-none disabled:opacity-50'
+
+/**
+ * Bold, full-height pill CTA reserved for value-moving actions — send,
+ * request, pay, withdraw. Uses the app's single accent (`bg-primary`) so it
+ * stands out from ordinary buttons, with a leading icon chosen by `kind`.
+ *
+ * @example
+ * ```tsx
+ * <MoneyActionButton kind="send" onClick={() => sendMoney()}>Send</MoneyActionButton>
+ * ```
+ */
+export function MoneyActionButton(props: MoneyActionButtonProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['children', 'kind', 'class'])
+  const Icon = () => KIND_ICON[local.kind ?? 'send']
+
+  return (
+    <button type="button" class={cn(BASE, local.class)} {...rest}>
+      <Dynamic component={Icon()} class="h-4 w-4 shrink-0" aria-hidden="true" />
+      {local.children}
+    </button>
+  )
+}

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/SlashMenu.tsx

@@ -0,0 +1,141 @@
+// SlashMenu — filterable "/" insert/command menu (the "type / to insert
+// anything" pattern). Presentational and keyboard-driven; the caller wires
+// the '/' trigger and owns `open` + `query` (usually whatever the user typed
+// after '/').
+import { createEffect, createMemo, createSignal, For, Show, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+
+/** A single insertable item in a {@link SlashMenu}. */
+export interface SlashItem {
+  /** Value passed to `onSelect` when this item is picked. */
+  value: string
+  /** Primary text shown on the row. */
+  label: string
+  /** Optional secondary text shown muted below the label. */
+  description?: string
+  /** Optional leading icon. */
+  icon?: JSX.Element
+  /** Extra terms matched against the query, in addition to label + description. */
+  keywords?: string[]
+}
+
+export interface SlashMenuProps {
+  items: SlashItem[]
+  /** Filter text — typically whatever the user typed after '/'. */
+  query: string
+  /** Invoked with the picked item's `value` (click or Enter). */
+  onSelect: (value: string) => void
+  /** Renders nothing when `false`. @default true */
+  open?: boolean
+  class?: string
+}
+
+/**
+ * Floating, keyboard-navigable menu for a "/"-triggered insert/command flow.
+ * Filters `items` against `query` (case-insensitive match over label +
+ * description + keywords), highlights an active row (↑/↓, wraps), and picks
+ * it on Enter or click. Purely presentational: the caller owns the '/'
+ * trigger, `open`, and `query` — this component only renders the filtered
+ * list and reports the pick.
+ *
+ * @example
+ * ```tsx
+ * const [query, setQuery] = createSignal('')
+ * <SlashMenu
+ *   items={[{ value: 'heading', label: 'Heading', icon: <Heading size={16} /> }]}
+ *   query={query()}
+ *   onSelect={(value) => insertBlock(value)}
+ * />
+ * ```
+ */
+export function SlashMenu(props: SlashMenuProps): JSX.Element {
+  const [active, setActive] = createSignal(0)
+  let rootRef: HTMLDivElement | undefined
+
+  const isOpen = () => props.open ?? true
+
+  const results = createMemo<SlashItem[]>(() => {
+    const q = props.query.trim().toLowerCase()
+    if (!q) return props.items
+    return props.items.filter((item) =>
+      `${item.label} ${item.description ?? ''} ${(item.keywords ?? []).join(' ')}`.toLowerCase().includes(q),
+    )
+  })
+
+  // Keep the highlighted row in range whenever the filtered set changes.
+  createEffect(() => {
+    results()
+    setActive(0)
+  })
+
+  // Focus the menu whenever it opens so arrow keys work immediately.
+  createEffect(() => {
+    if (isOpen()) rootRef?.focus()
+  })
+
+  const pick = (item: SlashItem) => props.onSelect(item.value)
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    const list = results()
+    if (list.length === 0) return
+    if (e.key === 'ArrowDown') {
+      e.preventDefault()
+      setActive((i) => (i + 1) % list.length)
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault()
+      setActive((i) => (i - 1 + list.length) % list.length)
+    } else if (e.key === 'Enter') {
+      e.preventDefault()
+      const item = list[active()]
+      if (item) pick(item)
+    }
+  }
+
+  return (
+    <Show when={isOpen()}>
+      <div
+        ref={rootRef}
+        role="listbox"
+        tabindex={0}
+        onKeyDown={onKeyDown}
+        class={cn(
+          'card max-h-72 overflow-y-auto rounded-lg border border-border bg-card p-1 shadow-lg outline-none',
+          props.class,
+        )}
+      >
+        <Show
+          when={results().length}
+          fallback={<div class="px-3 py-6 text-center text-sm text-muted-foreground">No matches</div>}
+        >
+          <For each={results()}>
+            {(item, i) => (
+              <div
+                role="option"
+                aria-selected={active() === i()}
+                onMouseEnter={() => setActive(i())}
+                onClick={() => pick(item)}
+                class={cn(
+                  'flex cursor-pointer items-center gap-2 rounded-md px-3 py-2 text-left transition-colors',
+                  active() === i() ? 'bg-muted' : undefined,
+                )}
+              >
+                <Show when={item.icon}>
+                  <span class="flex h-4 w-4 shrink-0 items-center justify-center text-muted-foreground">
+                    {item.icon}
+                  </span>
+                </Show>
+                <div class="min-w-0 flex-1">
+                  <div class="truncate text-sm text-foreground">{item.label}</div>
+                  <Show when={item.description}>
+                    <div class="truncate text-xs text-muted-foreground">{item.description}</div>
+                  </Show>
+                </div>
+              </div>
+            )}
+          </For>
+        </Show>
+      </div>
+    </Show>
+  )
+}