@a4ui/core 0.33.0 → 0.34.0

package/src/ui/OnboardingChecklist.tsx

@@ -0,0 +1,163 @@
+// Card-shaped step list for onboarding/setup flows. Completion state is
+// controlled by the caller (`steps[].done`) but each step also tracks its own
+// expanded/collapsed description locally, following the Collapse idiom.
+import { Check } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createSignal, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Button } from './Button'
+import { RingProgress } from './RingProgress'
+
+/** A single step in an {@link OnboardingChecklist}. */
+export interface OnboardingStep {
+  /** Stable identifier, used as the toggle key and `For` item key. */
+  id: string
+  title: JSX.Element
+  /** Optional detail shown when the step is expanded. */
+  description?: JSX.Element
+  /** Whether the step is complete. */
+  done?: boolean
+  /** Optional call-to-action rendered alongside the description. */
+  action?: { label: string; onClick: () => void }
+}
+
+export interface OnboardingChecklistProps {
+  steps: OnboardingStep[]
+  /** Called with the step id and its next `done` state when the indicator is toggled. */
+  onToggle?: (id: string, done: boolean) => void
+  /** Heading shown above the progress summary. Defaults to `'Getting started'`. */
+  title?: JSX.Element
+  class?: string
+}
+
+/**
+ * Card-shaped onboarding/setup checklist: a header with a completion ring and
+ * "{done} of {total} complete" summary, followed by expandable steps. Each
+ * step has a clickable check indicator (toggles `done` via `onToggle`), a
+ * title, and an optional description + CTA revealed on expand. Completion is
+ * controlled by the caller; expansion is local UI state (one step open at a time).
+ *
+ * @example
+ * ```tsx
+ * const [steps, setSteps] = createSignal<OnboardingStep[]>([
+ *   { id: 'profile', title: 'Complete your profile', done: true },
+ *   {
+ *     id: 'invite',
+ *     title: 'Invite a teammate',
+ *     description: 'Collaborate faster by adding at least one teammate.',
+ *     action: { label: 'Invite', onClick: () => openInviteDialog() },
+ *   },
+ * ])
+ * <OnboardingChecklist
+ *   steps={steps()}
+ *   onToggle={(id, done) =>
+ *     setSteps((prev) => prev.map((s) => (s.id === id ? { ...s, done } : s)))
+ *   }
+ * />
+ * ```
+ */
+export function OnboardingChecklist(props: OnboardingChecklistProps): JSX.Element {
+  const [expanded, setExpanded] = createSignal<string | null>(null)
+
+  const total = () => props.steps.length
+  const done = () => props.steps.filter((step) => step.done).length
+  const percent = () => (total() === 0 ? 0 : (done() / total()) * 100)
+
+  const toggleDone = (step: OnboardingStep): void => {
+    props.onToggle?.(step.id, !step.done)
+  }
+
+  const toggleExpanded = (id: string): void => {
+    setExpanded((prev) => (prev === id ? null : id))
+  }
+
+  return (
+    <div class={cn('rounded-xl border border-border bg-card text-card-foreground', props.class)}>
+      <div class="flex items-center gap-4 border-b border-border p-4">
+        <RingProgress
+          value={percent()}
+          size={56}
+          thickness={6}
+          label={
+            <span class="text-xs">
+              {done()}/{total()}
+            </span>
+          }
+        />
+        <div>
+          <p class="font-semibold text-foreground">{props.title ?? 'Getting started'}</p>
+          <p class="text-sm text-muted-foreground">
+            {done()} of {total()} complete
+          </p>
+        </div>
+      </div>
+      <ul role="list" class="divide-y divide-border">
+        <For each={props.steps}>
+          {(step) => {
+            const isExpanded = () => expanded() === step.id
+            const hasDetail = () => step.description !== undefined || step.action !== undefined
+            return (
+              <li class="p-4">
+                <div class="flex items-start gap-3">
+                  <button
+                    type="button"
+                    role="checkbox"
+                    aria-checked={!!step.done}
+                    aria-label={step.done ? 'Mark step as not done' : 'Mark step as done'}
+                    onClick={() => toggleDone(step)}
+                    class={cn(
+                      'mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full border transition-colors',
+                      step.done
+                        ? 'border-emerald-500 bg-emerald-500 text-white'
+                        : 'border-input bg-background text-transparent hover:border-emerald-500/60',
+                    )}
+                  >
+                    <Check class="h-3.5 w-3.5" />
+                  </button>
+                  <button
+                    type="button"
+                    class="min-w-0 flex-1 text-left"
+                    aria-expanded={hasDetail() ? isExpanded() : undefined}
+                    disabled={!hasDetail()}
+                    onClick={() => hasDetail() && toggleExpanded(step.id)}
+                  >
+                    <span
+                      class={cn(
+                        'block text-sm font-medium',
+                        step.done ? 'text-muted-foreground line-through' : 'text-foreground',
+                      )}
+                    >
+                      {step.title}
+                    </span>
+                  </button>
+                </div>
+                <Show when={hasDetail()}>
+                  <div
+                    class={cn(
+                      'grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none',
+                      isExpanded() ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]',
+                    )}
+                  >
+                    <div class="overflow-hidden">
+                      <div class="mt-2 pl-8 text-sm text-muted-foreground">
+                        <Show when={step.description}>{step.description}</Show>
+                        <Show when={step.action}>
+                          {(action) => (
+                            <Button variant="outline" class="mt-2" onClick={() => action().onClick()}>
+                              {action().label}
+                            </Button>
+                          )}
+                        </Show>
+                      </div>
+                    </div>
+                  </div>
+                </Show>
+              </li>
+            )
+          }}
+        </For>
+      </ul>
+    </div>
+  )
+}

package/src/ui/SheetSnap.tsx

@@ -0,0 +1,264 @@
+// Bottom sheet with drag-to-resize snap points (mobile filter/detail panels,
+// map bottom sheets). Kobalte's Dialog (used by Drawer/Modal) has no notion of
+// intermediate heights, so this rolls its own portal + backdrop + focus/Escape/
+// body-scroll-lock (mirroring Drawer.tsx's overlay idiom) and its own raw
+// pointerdown/move/up + pointer-capture drag loop (there's no shared drag
+// primitive in the repo to reuse). The sheet's height is fixed to the tallest
+// snap point; the *visible* portion is controlled by translating it down in
+// pixels, snapped to one of `snapPoints` (fractions of `window.innerHeight`).
+import { createEffect, createSignal, onCleanup, onMount, Show, type JSX } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { animate, motionReduced } from '../lib/motion'
+import { Portal } from './Portal'
+
+export interface SheetSnapProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  /** Fractions of viewport height, ascending, e.g. `[0.4, 0.9]`. @default [0.5, 0.9] */
+  snapPoints?: number[]
+  /** Index into `snapPoints` to open at. @default 0 */
+  defaultSnap?: number
+  children: JSX.Element
+  class?: string
+}
+
+const DEFAULT_SNAPS = [0.5, 0.9]
+const SPRING_STIFFNESS = 380
+const SPRING_DAMPING = 38
+/** Drag past the lowest snap point by this many px (with no help from velocity) dismisses. */
+const DISMISS_DISTANCE_PX = 100
+/** px/ms; a flick faster than this biases the resolved snap by one level, or dismisses near the bottom. */
+const FLICK_VELOCITY = 0.5
+
+const clamp = (n: number, min: number, max: number) => Math.min(Math.max(n, min), max)
+
+/**
+ * A draggable bottom sheet that rests at one of several height "snap points"
+ * (fractions of viewport height) instead of just open/closed. Drag the handle
+ * to resize with the finger; releasing snaps to the nearest point, biased by
+ * flick velocity (a fast swipe jumps a level), and a hard downward flick/drag
+ * past the lowest point dismisses. Falls back to an instant show/hide at
+ * `defaultSnap` — no drag physics — under reduced motion.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = createSignal(false)
+ * <SheetSnap open={open()} onOpenChange={setOpen} snapPoints={[0.4, 0.9]}>
+ *   <p>Sheet content…</p>
+ * </SheetSnap>
+ * ```
+ */
+export function SheetSnap(props: SheetSnapProps): JSX.Element {
+  const snaps = () => (props.snapPoints?.length ? props.snapPoints : DEFAULT_SNAPS)
+  const defaultIndex = () => clamp(props.defaultSnap ?? 0, 0, snaps().length - 1)
+
+  const [mounted, setMounted] = createSignal(false)
+  const [translateY, setTranslateY] = createSignal(0)
+
+  let previouslyFocused: HTMLElement | null = null
+  let previousBodyOverflow = ''
+
+  // Plain (non-reactive) geometry — recomputed on open and on resize, read
+  // fresh inside the `translateY()`-dependent style expression below.
+  let maxHeightPx = 0
+  let translateYs: number[] = []
+  let snapIndex = 0
+
+  let controls: ReturnType<typeof animate> | undefined
+  let dragging = false
+  let dragStartClientY = 0
+  let dragStartTranslate = 0
+  let lastClientY = 0
+  let lastTime = 0
+  let velocity = 0 // px/ms, positive = moving down (toward closed)
+
+  const computeGeometry = () => {
+    const vh = window.innerHeight
+    const pixelHeights = snaps().map((f) => f * vh)
+    maxHeightPx = Math.max(...pixelHeights)
+    translateYs = pixelHeights.map((h) => maxHeightPx - h)
+  }
+
+  const lockScroll = () => {
+    previousBodyOverflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+  }
+  const unlockScroll = () => {
+    document.body.style.overflow = previousBodyOverflow
+  }
+
+  const animateTo = (target: number, onDone?: () => void) => {
+    controls?.stop()
+    if (motionReduced()) {
+      setTranslateY(target)
+      onDone?.()
+      return
+    }
+    controls = animate(translateY(), target, {
+      type: 'spring',
+      stiffness: SPRING_STIFFNESS,
+      damping: SPRING_DAMPING,
+      onUpdate: (v: number) => setTranslateY(v),
+    })
+    controls.finished.then(() => onDone?.()).catch(() => {})
+  }
+
+  // Mount/unmount + enter/exit animation, driven off the controlled `open` prop.
+  createEffect(() => {
+    if (props.open) {
+      if (mounted()) return
+      computeGeometry()
+      snapIndex = defaultIndex()
+      previouslyFocused = document.activeElement as HTMLElement | null
+      setTranslateY(motionReduced() ? translateYs[snapIndex] : maxHeightPx)
+      setMounted(true)
+      lockScroll()
+    } else if (mounted()) {
+      animateTo(maxHeightPx, () => {
+        setMounted(false)
+        unlockScroll()
+        previouslyFocused?.focus()
+      })
+    }
+  })
+
+  const resolveDragEnd = () => {
+    const current = translateY()
+    const mostClosedY = translateYs[0]
+
+    const draggedPastLowest = current - mostClosedY
+    const fastDownwardNearBottom =
+      velocity > FLICK_VELOCITY && current >= mostClosedY - DISMISS_DISTANCE_PX / 2
+    if (draggedPastLowest > DISMISS_DISTANCE_PX || fastDownwardNearBottom) {
+      props.onOpenChange(false)
+      return
+    }
+
+    let nearest = 0
+    let bestDist = Infinity
+    translateYs.forEach((t, i) => {
+      const d = Math.abs(current - t)
+      if (d < bestDist) {
+        bestDist = d
+        nearest = i
+      }
+    })
+
+    let target = nearest
+    if (velocity > FLICK_VELOCITY) target = Math.max(nearest - 1, 0)
+    else if (velocity < -FLICK_VELOCITY) target = Math.min(nearest + 1, translateYs.length - 1)
+
+    snapIndex = target
+    animateTo(translateYs[target])
+  }
+
+  const onHandlePointerDown = (e: PointerEvent) => {
+    if (motionReduced()) return
+    e.preventDefault()
+    ;(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId)
+    controls?.stop()
+    dragging = true
+    dragStartClientY = e.clientY
+    dragStartTranslate = translateY()
+    lastClientY = e.clientY
+    lastTime = performance.now()
+    velocity = 0
+  }
+
+  const onHandlePointerMove = (e: PointerEvent) => {
+    if (!dragging) return
+    const next = Math.max(dragStartTranslate + (e.clientY - dragStartClientY), 0)
+    setTranslateY(next)
+
+    const now = performance.now()
+    const dt = now - lastTime
+    if (dt > 0) velocity = (e.clientY - lastClientY) / dt
+    lastClientY = e.clientY
+    lastTime = now
+  }
+
+  const onHandlePointerUp = (e: PointerEvent) => {
+    if (!dragging) return
+    dragging = false
+    ;(e.currentTarget as HTMLElement).releasePointerCapture(e.pointerId)
+    resolveDragEnd()
+  }
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Escape' && props.open) props.onOpenChange(false)
+  }
+  const onResize = () => {
+    if (!mounted()) return
+    computeGeometry()
+    setTranslateY(translateYs[clamp(snapIndex, 0, translateYs.length - 1)])
+  }
+
+  onMount(() => {
+    document.addEventListener('keydown', onKeyDown)
+    window.addEventListener('resize', onResize)
+  })
+  onCleanup(() => {
+    document.removeEventListener('keydown', onKeyDown)
+    window.removeEventListener('resize', onResize)
+    controls?.stop()
+    if (mounted()) unlockScroll()
+  })
+
+  return (
+    <Show when={mounted()}>
+      <Portal>
+        <div
+          aria-hidden="true"
+          onClick={() => props.onOpenChange(false)}
+          class="fixed inset-0 z-[9998] bg-black/50 backdrop-blur-[2px]"
+        />
+        <div
+          ref={(el) => {
+            requestAnimationFrame(() => {
+              el.focus()
+              animateTo(translateYs[snapIndex])
+            })
+          }}
+          role="dialog"
+          aria-modal="true"
+          aria-label="Bottom sheet"
+          tabindex={-1}
+          class={cn(
+            'fixed inset-x-0 bottom-0 z-[9999] flex flex-col overflow-hidden rounded-t-2xl border border-border bg-glass shadow-2xl outline-none',
+            props.class,
+          )}
+          style={{
+            height: `${maxHeightPx}px`,
+            transform: `translateY(${translateY()}px)`,
+          }}
+        >
+          <div
+            role="button"
+            tabindex={0}
+            aria-label="Drag handle"
+            onPointerDown={onHandlePointerDown}
+            onPointerMove={onHandlePointerMove}
+            onPointerUp={onHandlePointerUp}
+            onPointerCancel={onHandlePointerUp}
+            onKeyDown={(e) => {
+              if (e.key === 'ArrowUp') {
+                e.preventDefault()
+                snapIndex = Math.min(snapIndex + 1, translateYs.length - 1)
+                animateTo(translateYs[snapIndex])
+              } else if (e.key === 'ArrowDown') {
+                e.preventDefault()
+                snapIndex = Math.max(snapIndex - 1, 0)
+                animateTo(translateYs[snapIndex])
+              }
+            }}
+            class="flex shrink-0 touch-none items-center justify-center py-3 outline-none"
+          >
+            <div class="h-1.5 w-10 rounded-full bg-muted-foreground/40" />
+          </div>
+          <div class="flex-1 overflow-y-auto overscroll-contain px-4 pb-4">{props.children}</div>
+        </div>
+      </Portal>
+    </Show>
+  )
+}

package/src/ui/TreeTable.tsx

@@ -0,0 +1,172 @@
+// Hierarchical data table: rows can nest via `children`, expand/collapse lives
+// in the first column (chevron + depth indentation), all other columns render
+// like a plain DataGrid column. Built on the Table primitives + Tree's toggle idiom.
+import { ChevronRight } from 'lucide-solid'
+import type { JSX } from 'solid-js'
+import { createSignal, For, Show } from 'solid-js'
+
+import { cn } from '../lib/cn'
+import { Table, TableBody, TableCell, TableHead, TableHeadCell, TableRow } from './Table'
+
+/** A column definition for {@link TreeTable}. */
+export interface TreeTableColumn<T> {
+  /** Row data property this column reads when `cell` is omitted. */
+  key: string
+  /** Column heading content. */
+  header: JSX.Element
+  /** Custom cell renderer; falls back to `String(row[key])` when omitted. */
+  cell?: (row: T) => JSX.Element
+  /** Right-align the column (numbers, totals). */
+  align?: 'left' | 'right'
+}
+
+/** A single node in a {@link TreeTable}; nodes may nest via `children`. */
+export interface TreeTableRow<T> {
+  /** Unique identifier; used to track expanded state. */
+  id: string
+  /** Row payload passed to each column's `cell` renderer. */
+  data: T
+  /** Child rows revealed when this row is expanded. */
+  children?: TreeTableRow<T>[]
+}
+
+export interface TreeTableProps<T> {
+  columns: TreeTableColumn<T>[]
+  rows: TreeTableRow<T>[]
+  /** Expand every row with children on first render. Defaults to false. */
+  defaultExpanded?: boolean
+  class?: string
+}
+
+function collectIds<T>(rows: TreeTableRow<T>[], out: Set<string>): void {
+  for (const row of rows) {
+    if (row.children?.length) {
+      out.add(row.id)
+      collectIds(row.children, out)
+    }
+  }
+}
+
+/**
+ * Hierarchical table: rows may carry `children`, revealed by clicking the
+ * chevron in the first column. Depth is shown via indentation; expanded state
+ * is tracked internally, seeded fully expanded when `defaultExpanded` is set.
+ *
+ * @example
+ * ```tsx
+ * <TreeTable
+ *   defaultExpanded
+ *   columns={[
+ *     { key: 'name', header: 'Name' },
+ *     { key: 'size', header: 'Size', align: 'right', cell: (row) => `${row.size} KB` },
+ *   ]}
+ *   rows={[
+ *     {
+ *       id: 'src',
+ *       data: { name: 'src', size: 0 },
+ *       children: [{ id: 'index', data: { name: 'index.ts', size: 2 } }],
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+export function TreeTable<T>(props: TreeTableProps<T>): JSX.Element {
+  const [expanded, setExpanded] = createSignal<Set<string>>(
+    props.defaultExpanded ? seedExpanded(props.rows) : new Set<string>(),
+  )
+
+  function seedExpanded(rows: TreeTableRow<T>[]): Set<string> {
+    const ids = new Set<string>()
+    collectIds(rows, ids)
+    return ids
+  }
+
+  const toggle = (id: string) =>
+    setExpanded((prev) => {
+      const next = new Set(prev)
+      if (next.has(id)) next.delete(id)
+      else next.add(id)
+      return next
+    })
+
+  const Rows = (rowsProps: { rows: TreeTableRow<T>[]; depth: number }): JSX.Element => (
+    <For each={rowsProps.rows}>
+      {(row) => {
+        const hasChildren = () => (row.children?.length ?? 0) > 0
+        const isExpanded = () => expanded().has(row.id)
+
+        return (
+          <>
+            <TableRow>
+              <For each={props.columns}>
+                {(col, colIndex) => (
+                  <TableCell class={cn(col.align === 'right' && 'text-right tabular-nums')}>
+                    <Show
+                      when={colIndex() === 0}
+                      fallback={
+                        col.cell
+                          ? col.cell(row.data)
+                          : String((row.data as Record<string, unknown>)[col.key] ?? '')
+                      }
+                    >
+                      <div
+                        class="flex items-center gap-1.5"
+                        style={{ 'padding-left': `${rowsProps.depth * 1}rem` }}
+                      >
+                        <Show
+                          when={hasChildren()}
+                          fallback={<span class="h-3.5 w-3.5 shrink-0" aria-hidden="true" />}
+                        >
+                          <button
+                            type="button"
+                            class="flex h-3.5 w-3.5 shrink-0 items-center justify-center rounded-sm text-muted-foreground hover:text-foreground focus-visible:outline focus-visible:outline-2 focus-visible:outline-ring"
+                            aria-expanded={isExpanded()}
+                            aria-label={isExpanded() ? 'Collapse row' : 'Expand row'}
+                            onClick={() => toggle(row.id)}
+                          >
+                            <ChevronRight
+                              class={cn(
+                                'h-3.5 w-3.5 transition-transform duration-200',
+                                isExpanded() && 'rotate-90',
+                              )}
+                              aria-hidden="true"
+                            />
+                          </button>
+                        </Show>
+                        <span>
+                          {col.cell
+                            ? col.cell(row.data)
+                            : String((row.data as Record<string, unknown>)[col.key] ?? '')}
+                        </span>
+                      </div>
+                    </Show>
+                  </TableCell>
+                )}
+              </For>
+            </TableRow>
+            <Show when={hasChildren() && isExpanded()}>
+              <Rows rows={row.children ?? []} depth={rowsProps.depth + 1} />
+            </Show>
+          </>
+        )
+      }}
+    </For>
+  )
+
+  return (
+    <Table class={props.class}>
+      <TableHead>
+        <TableRow>
+          <For each={props.columns}>
+            {(col) => (
+              <TableHeadCell class={cn(col.align === 'right' && 'text-right')}>{col.header}</TableHeadCell>
+            )}
+          </For>
+        </TableRow>
+      </TableHead>
+      <TableBody>
+        <Rows rows={props.rows} depth={0} />
+      </TableBody>
+    </Table>
+  )
+}