@lovett/ui 0.0.1

package/src/sortable-table.tsx

@@ -0,0 +1,198 @@
+/**
+ * SortableTable — generic sortable table with sticky header.
+ *
+ * Promoted in ADR-022 (Phase 3c Discovery reports table, first
+ * committed consumer). Cross-batch consumers: Phase 8 keywords table,
+ * Phase 12 SEMSpec keywords/extensions/locations tables.
+ *
+ * Numeric columns auto-apply tabular-nums + right-align. Click column
+ * headers to sort. Sticky `<thead>` for scrollable bodies. Zebra-stripe
+ * optional.
+ *
+ * Token discipline: all colors via public tokens.
+ */
+
+import { useMemo, useState, type ReactNode } from 'react'
+import { ChevronDown, ChevronUp, ChevronsUpDown } from 'lucide-react'
+
+export interface Column<T> {
+  /** Unique id; doubles as the sort key. Use a `keyof T` string or
+   *  an arbitrary string if `sortValue` is provided. */
+  id: string
+  label: string
+  /** How to render a cell for a row. */
+  accessor: (row: T) => ReactNode
+  /** Optional explicit value used for sorting (defaults to the
+   *  accessor's stringified output for sort comparison). */
+  sortValue?: (row: T) => string | number | null | undefined
+  sortable?: boolean
+  /** Right-align + tabular-nums for numeric columns. Default false. */
+  numeric?: boolean
+  /** Header tooltip text. */
+  tooltip?: string
+  /** Width as a CSS value (e.g. `120px` or `20%`). */
+  width?: string
+}
+
+export interface SortableTableProps<T> {
+  columns: Column<T>[]
+  rows: T[]
+  /** Function returning a stable React key for each row. */
+  rowKey: (row: T) => string
+  /** Initial sort. */
+  initialSort?: { columnId: string; dir: 'asc' | 'desc' }
+  /** Row click handler. */
+  onRowClick?: (row: T) => void
+  /** Rendered when rows.length === 0. */
+  emptyState?: ReactNode
+  /** Zebra stripe alternating rows. Default true. */
+  zebra?: boolean
+  /** Compact density (smaller padding). Default false. */
+  compact?: boolean
+}
+
+export function SortableTable<T>({
+  columns,
+  rows,
+  rowKey,
+  initialSort,
+  onRowClick,
+  emptyState,
+  zebra = true,
+  compact = false,
+}: SortableTableProps<T>) {
+  const [sortColumnId, setSortColumnId] = useState<string | null>(
+    initialSort?.columnId ?? null,
+  )
+  const [sortDir, setSortDir] = useState<'asc' | 'desc'>(
+    initialSort?.dir ?? 'desc',
+  )
+
+  const sortedRows = useMemo(() => {
+    if (!sortColumnId) return rows
+    const col = columns.find((c) => c.id === sortColumnId)
+    if (!col) return rows
+    const valueOf = col.sortValue ?? ((row: T) => String(col.accessor(row)))
+    const dir = sortDir === 'asc' ? 1 : -1
+    return [...rows].sort((a, b) => {
+      const va = valueOf(a)
+      const vb = valueOf(b)
+      if (va == null && vb == null) return 0
+      if (va == null) return 1 * dir
+      if (vb == null) return -1 * dir
+      if (typeof va === 'number' && typeof vb === 'number') return (va - vb) * dir
+      return String(va).localeCompare(String(vb)) * dir
+    })
+  }, [rows, sortColumnId, sortDir, columns])
+
+  const handleHeaderClick = (col: Column<T>) => {
+    if (!col.sortable) return
+    if (sortColumnId === col.id) {
+      setSortDir((d) => (d === 'asc' ? 'desc' : 'asc'))
+    } else {
+      setSortColumnId(col.id)
+      setSortDir(col.numeric ? 'desc' : 'asc')
+    }
+  }
+
+  if (rows.length === 0 && emptyState) {
+    return <>{emptyState}</>
+  }
+
+  const cellPadding = compact ? 'px-2 py-1.5' : 'px-3 py-2.5'
+
+  return (
+    <div
+      className="w-full overflow-x-auto border"
+      style={{
+        borderColor: 'rgb(var(--border))',
+        borderRadius: 'var(--radius-lg)',
+      }}
+    >
+      <table className="w-full border-collapse text-[13px]">
+        <thead
+          className="sticky top-0 z-10"
+          style={{ background: 'rgb(var(--surface-overlay-soft))' }}
+        >
+          <tr>
+            {columns.map((col) => {
+              const isSorted = sortColumnId === col.id
+              const align = col.numeric ? 'text-right' : 'text-left'
+              const ariaSort: 'ascending' | 'descending' | 'none' = !col.sortable
+                ? 'none'
+                : isSorted
+                  ? sortDir === 'asc'
+                    ? 'ascending'
+                    : 'descending'
+                  : 'none'
+              return (
+                <th
+                  key={col.id}
+                  scope="col"
+                  aria-sort={ariaSort}
+                  title={col.tooltip}
+                  className={`${cellPadding} ${align} font-semibold border-b ${
+                    col.sortable ? 'cursor-pointer select-none' : ''
+                  }`}
+                  style={{
+                    color: 'rgb(var(--text-secondary))',
+                    borderColor: 'rgb(var(--border))',
+                    width: col.width,
+                  }}
+                  onClick={() => handleHeaderClick(col)}
+                >
+                  <span className="inline-flex items-center gap-1">
+                    {col.label}
+                    {col.sortable &&
+                      (isSorted ? (
+                        sortDir === 'asc' ? (
+                          <ChevronUp className="h-3 w-3" />
+                        ) : (
+                          <ChevronDown className="h-3 w-3" />
+                        )
+                      ) : (
+                        <ChevronsUpDown
+                          className="h-3 w-3 opacity-40"
+                          aria-hidden
+                        />
+                      ))}
+                  </span>
+                </th>
+              )
+            })}
+          </tr>
+        </thead>
+        <tbody>
+          {sortedRows.map((row, idx) => (
+            <tr
+              key={rowKey(row)}
+              onClick={onRowClick ? () => onRowClick(row) : undefined}
+              className={
+                onRowClick ? 'cursor-pointer transition-colors' : undefined
+              }
+              style={{
+                background:
+                  zebra && idx % 2 === 1
+                    ? 'rgb(var(--surface-overlay-soft) / 0.5)'
+                    : 'transparent',
+              }}
+            >
+              {columns.map((col) => (
+                <td
+                  key={col.id}
+                  className={`${cellPadding} ${col.numeric ? 'text-right tabular-nums font-mono' : 'text-left'} border-b`}
+                  style={{
+                    borderColor: 'rgb(var(--border))',
+                    color: 'rgb(var(--foreground))',
+                  }}
+                >
+                  {col.accessor(row)}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}

package/src/sortable.tsx

@@ -0,0 +1,137 @@
+/**
+ * Sortable primitives built on @dnd-kit. Promoted from brand-ai-extension
+ * `webapp/src/components/brand-profile-v2/sortable.tsx` per ADR-010
+ * Decision 5. CLAUDE.md §1 amended (Decision 6) to permit @dnd-kit/core +
+ * @dnd-kit/sortable + @dnd-kit/utilities as runtime deps.
+ *
+ * - <SortableList> wraps children with DndContext + SortableContext
+ * - <SortableItem> makes a single item draggable with a grab handle
+ * - <DragHandle> is a Lucide-grip handle pre-wired to the listeners
+ */
+
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
+import {
+  DndContext,
+  closestCenter,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+} from '@dnd-kit/core'
+import {
+  arrayMove,
+  SortableContext,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+  horizontalListSortingStrategy,
+  rectSortingStrategy,
+} from '@dnd-kit/sortable'
+import { CSS } from '@dnd-kit/utilities'
+import { GripVertical } from 'lucide-react'
+
+type Strategy = 'vertical' | 'horizontal' | 'grid'
+
+export function SortableList<T>({
+  items,
+  getId,
+  onReorder,
+  strategy = 'vertical',
+  children,
+}: {
+  items: T[]
+  getId: (item: T, index: number) => string
+  onReorder: (items: T[]) => void
+  strategy?: Strategy
+  children: ReactNode
+}) {
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 4 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  )
+
+  const sortIds = items.map(getId)
+
+  const sortingStrategy =
+    strategy === 'horizontal'
+      ? horizontalListSortingStrategy
+      : strategy === 'grid'
+        ? rectSortingStrategy
+        : verticalListSortingStrategy
+
+  const handleDragEnd = (event: DragEndEvent) => {
+    const { active, over } = event
+    if (over && active.id !== over.id) {
+      const oldIndex = sortIds.indexOf(String(active.id))
+      const newIndex = sortIds.indexOf(String(over.id))
+      if (oldIndex >= 0 && newIndex >= 0) {
+        onReorder(arrayMove(items, oldIndex, newIndex))
+      }
+    }
+  }
+
+  return (
+    <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
+      <SortableContext items={sortIds} strategy={sortingStrategy}>
+        {children}
+      </SortableContext>
+    </DndContext>
+  )
+}
+
+export function SortableItem({
+  id,
+  children,
+}: {
+  id: string
+  children: (props: {
+    dragHandleProps: HTMLAttributes<HTMLElement>
+    setNodeRef: (node: HTMLElement | null) => void
+    style: CSSProperties
+    isDragging: boolean
+  }) => ReactNode
+}) {
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+    id,
+  })
+
+  const style: CSSProperties = {
+    transform: CSS.Transform.toString(transform),
+    transition,
+    opacity: isDragging ? 0.4 : 1,
+    position: 'relative',
+    zIndex: isDragging ? 10 : 'auto',
+  }
+
+  return (
+    <>
+      {children({
+        dragHandleProps: { ...attributes, ...listeners } as HTMLAttributes<HTMLElement>,
+        setNodeRef,
+        style,
+        isDragging,
+      })}
+    </>
+  )
+}
+
+export function DragHandle({
+  dragHandleProps,
+  className = '',
+}: {
+  dragHandleProps: HTMLAttributes<HTMLElement>
+  className?: string
+}) {
+  return (
+    <button
+      {...dragHandleProps}
+      type="button"
+      className={`cursor-grab active:cursor-grabbing flex items-center justify-center text-[rgb(var(--text-muted))] hover:text-[rgb(var(--text-secondary))] transition-colors ${className}`}
+      style={{ touchAction: 'none' }}
+      aria-label="Drag to reorder"
+    >
+      <GripVertical className="h-4 w-4" />
+    </button>
+  )
+}

package/src/stat-row.tsx

@@ -0,0 +1,132 @@
+/**
+ * StatRow — the Calculator Shell v2 signature primitive (ADR-076 D2).
+ *
+ * A horizontal row of "step" tiles showing a metric chain compounding
+ * left -> right. Each tile is a near-black brand-ink outer card holding a
+ * recessed white inner panel with the figure; a red arrow between tiles
+ * shows the math compounding. Exactly one tile may be `pivotal` — it
+ * flips from brand-ink to accent red (the "black/red/white rendered in
+ * miniature" that makes black survive without a heavy slab).
+ *
+ *   <StatRow steps={[
+ *     { icon: <Users size={16} />,  label: 'Audience',    value: '120K' },
+ *     { icon: <Repeat size={16} />, label: 'Frequency',   value: '2.0x', pivotal: true },
+ *     { icon: <Eye size={16} />,    label: 'Impressions', value: '240K' },
+ *     { icon: <Wallet size={16} />, label: 'Budget',      value: '$8,160' },
+ *   ]} />
+ *
+ * Presentational + stateless. The caller formats `value` (tabular-nums is
+ * applied here). Inner panels carry a fixed `min-height` so a tile never
+ * resizes as its value's length changes (ADR-076 D5 zero-layout-shift).
+ *
+ * Promoted to @lovett/ui under ADR-076 D2 — the catalog of calculator
+ * consumers clears ADR-008 D3's 2+ consumer gate.
+ */
+
+import { ArrowRight } from 'lucide-react'
+import { Fragment, type ReactNode } from 'react'
+
+export interface StatRowStep {
+  /** Lucide glyph (~16px). Inherits the dark-frame label colour. */
+  icon: ReactNode
+  /** Uppercase metric label (rendered ~9.5px). */
+  label: string
+  /** Pre-formatted figure. Rendered tabular-nums. */
+  value: string
+  /** The single pivotal tile — rendered in `--accent` instead of
+   *  `--brand-ink`. At most one step should set this. */
+  pivotal?: boolean
+}
+
+export interface StatRowProps {
+  steps: StatRowStep[]
+  className?: string
+}
+
+export function StatRow({ steps, className }: StatRowProps) {
+  return (
+    <div className={className} style={{ display: 'flex', alignItems: 'stretch', gap: 0 }}>
+      {steps.map((s, i) => (
+        <Fragment key={i}>
+          {i > 0 && (
+            <div
+              className="flex items-center shrink-0"
+              style={{ padding: '0 2px', color: 'rgb(var(--text-muted))' }}
+              aria-hidden="true"
+            >
+              <ArrowRight size={14} strokeWidth={2.2} />
+            </div>
+          )}
+          <div
+            data-pivotal={s.pivotal ? 'true' : undefined}
+            style={{
+              flex: 1,
+              minWidth: 0,
+              borderRadius: 'var(--radius-lg)',
+              padding: 5,
+              background: s.pivotal
+                ? 'rgb(var(--accent))'
+                : 'rgb(var(--brand-ink))',
+            }}
+          >
+            {/* label row sits on the dark frame */}
+            <div
+              className="flex items-center"
+              style={{
+                gap: 5,
+                padding: '4px 7px 6px',
+                color: 'rgb(255 255 255 / 0.7)',
+                minWidth: 0,
+              }}
+            >
+              <span className="inline-flex shrink-0">{s.icon}</span>
+              {/* Single-line cap: long labels truncate with an ellipsis
+                  (full text on hover via title) instead of wrapping to a
+                  second line and unbalancing the tile row. Keep labels short. */}
+              <span
+                className="font-bold uppercase"
+                title={s.label}
+                style={{
+                  fontSize: '9.5px',
+                  letterSpacing: '0.05em',
+                  whiteSpace: 'nowrap',
+                  overflow: 'hidden',
+                  textOverflow: 'ellipsis',
+                  minWidth: 0,
+                  flex: 1,
+                }}
+              >
+                {s.label}
+              </span>
+            </div>
+            {/* recessed white inner panel — fixed min-height so the tile
+                never resizes as the value's length changes */}
+            <div
+              className="grid place-items-center text-center"
+              style={{
+                background: 'rgb(var(--bg-card))',
+                borderRadius: 10,
+                padding: '12px 10px',
+                minHeight: 46,
+              }}
+            >
+              <span
+                className="font-extrabold tabular-nums"
+                style={{
+                  fontSize: 22,
+                  letterSpacing: '-0.025em',
+                  lineHeight: 1,
+                  color: s.pivotal
+                    ? 'rgb(var(--accent))'
+                    : 'rgb(var(--foreground))',
+                }}
+              >
+                {s.value}
+              </span>
+            </div>
+          </div>
+        </Fragment>
+      ))}
+    </div>
+  )
+}

package/src/stats-grid.tsx

@@ -0,0 +1,38 @@
+/**
+ * StatsGrid — auto-fit responsive grid for MetricCard rows.
+ *
+ * Promoted in ADR-022 (Phase 3c Discovery Analytics, first committed
+ * consumer). Cross-batch consumers: Phase 3a (generation cost row),
+ * Phase 8 (results summary), Phase 12 (review-overview summary).
+ *
+ * Tiny primitive — but stops the auto-fit grid pattern being
+ * re-written 4+ times across the batch.
+ */
+
+import type { ReactNode } from 'react'
+
+export interface StatsGridProps {
+  children: ReactNode
+  /** Minimum column width in px (controls how many cards per row at a
+   *  given viewport). Default 220 — comfortable for 4-up at md+. */
+  minColumnWidth?: number
+  /** Optional className override for the outer container. */
+  className?: string
+}
+
+export function StatsGrid({
+  children,
+  minColumnWidth = 220,
+  className,
+}: StatsGridProps) {
+  return (
+    <div
+      className={className ?? 'grid gap-3'}
+      style={{
+        gridTemplateColumns: `repeat(auto-fit, minmax(${minColumnWidth}px, 1fr))`,
+      }}
+    >
+      {children}
+    </div>
+  )
+}

package/src/step-loader.tsx

@@ -0,0 +1,141 @@
+/**
+ * StepLoader — a sequential, multi-step loading indicator (3-5 steps). Each step
+ * dwells for a believable duration, then the next begins (completed → check, current
+ * → spinner, pending → dot), connected by a vertical rail.
+ *
+ * The defining behavior: the FINAL step is HELD until the real work reports `done`
+ * AND a minimum dwell has elapsed — so a backend that returns faster than usual still
+ * plays the full, believable sequence instead of snapping away. Non-final steps always
+ * advance on their own timers (independent of `done`).
+ *
+ *   <StepLoader steps={[...]} done={isReady} onComplete={() => show()} />
+ */
+
+import { useEffect, useRef, useState } from 'react'
+import { Check, Loader2 } from 'lucide-react'
+
+export interface StepLoaderStep {
+  label: string
+  /** Override the default dwell for this step (ms). */
+  durationMs?: number
+}
+
+export interface StepLoaderProps {
+  /** The ordered steps (3-5). Strings use the default dwell. */
+  steps: ReadonlyArray<string | StepLoaderStep>
+  /** The real work finished — gates completion of the FINAL step only. */
+  done?: boolean
+  /** Fired once the sequence has played out AND `done` is true (+ `minLastStepMs`). */
+  onComplete?: () => void
+  /** Default per-step dwell (ms) for steps without an explicit duration. */
+  defaultStepMs?: number
+  /** Minimum time the final step stays before completing — keeps a fast result believable. */
+  minLastStepMs?: number
+  className?: string
+}
+
+type StepState = 'done' | 'active' | 'pending'
+
+export function StepLoader({
+  steps,
+  done = false,
+  onComplete,
+  defaultStepMs = 2600,
+  minLastStepMs = 1400,
+  className,
+}: StepLoaderProps) {
+  const items = steps.map((s) => (typeof s === 'string' ? { label: s } : s))
+  const n = items.length
+  const [active, setActive] = useState(0)
+  const [complete, setComplete] = useState(false)
+  const completedRef = useRef(false)
+  const minElapsedRef = useRef(false)
+  const doneRef = useRef(done)
+  doneRef.current = done
+  const onCompleteRef = useRef(onComplete)
+  onCompleteRef.current = onComplete
+
+  function fire() {
+    if (completedRef.current) return
+    completedRef.current = true
+    setComplete(true)
+    onCompleteRef.current?.()
+  }
+
+  // Walk the non-final steps on their dwell timers, independent of `done` — the
+  // sequence always plays out so a fast backend still looks believable.
+  useEffect(() => {
+    if (complete || active >= n - 1) return
+    const ms = items[active]?.durationMs ?? defaultStepMs
+    const t = setTimeout(() => setActive((a) => Math.min(a + 1, n - 1)), ms)
+    return () => clearTimeout(t)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [active, n, complete, defaultStepMs])
+
+  // On the final step, hold for `minLastStepMs`, then complete if the work is already
+  // `done` (synchronously, so it flushes) — otherwise mark the dwell done and wait.
+  useEffect(() => {
+    if (active !== n - 1) return
+    const t = setTimeout(() => {
+      minElapsedRef.current = true
+      if (doneRef.current) fire()
+    }, minLastStepMs)
+    return () => clearTimeout(t)
+  }, [active, n, minLastStepMs])
+
+  // When the work finishes after the dwell has already elapsed, complete.
+  useEffect(() => {
+    if (active === n - 1 && done && minElapsedRef.current) fire()
+  }, [done, active, n])
+
+  return (
+    <div className={['flex flex-col', className].filter(Boolean).join(' ')} role="status" aria-live="polite">
+      {items.map((item, i) => {
+        const state: StepState = complete || i < active ? 'done' : i === active ? 'active' : 'pending'
+        const isLast = i === n - 1
+        return (
+          <div key={item.label} className="flex gap-3">
+            {/* marker + connector rail */}
+            <div className="flex flex-col items-center">
+              <span
+                className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-[var(--radius-full)] transition-colors"
+                style={
+                  state === 'done'
+                    ? { background: 'rgb(var(--accent))', color: 'rgb(var(--surface-on-accent))' }
+                    : state === 'active'
+                      ? { boxShadow: 'inset 0 0 0 2px rgb(var(--accent))', color: 'rgb(var(--accent))' }
+                      : { boxShadow: 'inset 0 0 0 2px rgb(var(--border))', color: 'rgb(var(--text-muted))' }
+                }
+                aria-current={state === 'active' ? 'step' : undefined}
+              >
+                {state === 'done' ? (
+                  <Check className="h-4 w-4" />
+                ) : state === 'active' ? (
+                  <Loader2 className="h-4 w-4 animate-spin" />
+                ) : (
+                  <span className="h-1.5 w-1.5 rounded-[var(--radius-full)]" style={{ background: 'currentColor' }} />
+                )}
+              </span>
+              {!isLast && (
+                <span
+                  className="my-1 w-px flex-1 transition-colors"
+                  style={{ minHeight: 12, background: i < active || complete ? 'rgb(var(--accent))' : 'rgb(var(--border))' }}
+                />
+              )}
+            </div>
+            {/* label */}
+            <span
+              className="pt-[5px] pb-2 text-[13.5px] leading-tight transition-colors"
+              style={{
+                color: state === 'pending' ? 'rgb(var(--text-tertiary))' : 'rgb(var(--foreground))',
+                fontWeight: state === 'active' ? 600 : 500,
+              }}
+            >
+              {item.label}
+            </span>
+          </div>
+        )
+      })}
+    </div>
+  )
+}