@weft-js/warp 0.0.0-stage → 0.1.0

package/src/Table.tsx

@@ -0,0 +1,528 @@
+import { ColumnsIcon } from '@weft-js/warp-icons'
+import { checkState, filterRows, hideRule, pageSlice, popover, pushLayer, rangeOf, sortRows, table, uid, type SortDir } from '@weft-js/warp-core'
+import { derived, onCleanup, onMount, state, type Derived, type Resource, type State, untrack, watch } from '@weft-js/core'
+import { Button } from './Button'
+import { Checkbox } from './Choice'
+import { Search } from './Field'
+import { Select } from './Select'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/components/popover.css' // the Columns panel
+import '@weft-js/warp-core/styles/data/tokens.css'
+import '@weft-js/warp-core/styles/data/base.css'
+import '@weft-js/warp-core/styles/data/table.css'
+import '@weft-js/warp-core/styles/data/desc.css'
+
+/** One Table column. */
+export interface Column<T> {
+  id: string
+  /** Text: it also labels the cell on a phone card and the Columns checkbox. */
+  header: string
+  /** What the cell holds, sorts by and filters on. Default `row[id]`. */
+  value?: ((row: T) => unknown) | undefined
+  /** How the cell draws it. Default the value as text. */
+  cell?: ((row: T) => unknown) | undefined
+  /** `true` sorts by `value`; a function sorts by what it returns. */
+  sort?: (boolean | ((row: T) => unknown)) | undefined
+  numeric?: boolean | undefined
+  /** Sticky at the inline start. */
+  pin?: boolean | undefined
+  rowHeader?: boolean | undefined
+  /** 2 hides under 760px of table width, 3 under 1000px; a row's details still list it. */
+  priority?: 2 | 3 | undefined
+  /** Where it goes on a phone card. */
+  card?: 'title' | 'badge' | 'hide' | undefined
+  resize?: boolean | undefined
+  /** Inline edit: `true` commits the text, a function turns the text into the value. */
+  edit?: (boolean | ((text: string) => unknown)) | undefined
+  /** `true`, or the message to show: an invalid value never commits. */
+  validate?: ((value: unknown) => string | boolean) | undefined
+  /** A number that ticks: the cell flashes on change and the row is never rebuilt. */
+  live?: boolean | undefined
+}
+
+/** The V2 list envelope. `next`/`prev` are cursors; absent means there is no such page. */
+export type ListPage<T> = { items: T[]; total?: number; next?: unknown; prev?: unknown }
+/** The column a table is sorted by, and which way. */
+export type TableSort = { id: string; dir: SortDir }
+/** What a table is showing in place of, or along with, its rows. */
+export type TableStatus = 'ready' | 'loading' | 'empty' | 'error'
+
+/** Props for Table. */
+export interface TableProps<T> {
+  rows: readonly T[] | State<readonly T[]> | Derived<readonly T[]> | Resource<readonly T[] | ListPage<T>>
+  /** Names the table (required, 06 §5). It stays in the accessibility tree when `captionHidden`. */
+  caption: string
+  /** Hides the caption on screen. Screen readers still hear it. */
+  captionHidden?: boolean | undefined
+  columns: Column<T>[]
+  /** The field that identifies a row, or how to get it. Default `id`. */
+  rowKey?: (string | ((row: T) => string)) | undefined
+  /** `cards` stacks each row in a container under 480px wide; `columns` scrolls sideways instead. */
+  phone?: 'cards' | 'columns' | undefined
+  density?: 'compact' | 'cozy' | 'comfortable' | undefined
+  /** Show the filter field, labelled this. */
+  filter?: string | undefined
+  /** A state holding the filter text, so you can read or set it. */
+  query?: State<string> | undefined
+  /** A state holding the sorted column and direction, so you can read or set it. */
+  sort?: State<TableSort | undefined>
+  /** Called with the column and direction when someone sorts. */
+  onSortChange?: ((sort: TableSort) => void) | undefined
+  /** The rows arrive sorted, filtered and paged (a Resource's are): the table only reports what's asked. */
+  server?: boolean | undefined
+  /** Checkboxes, Shift-click ranges and the bulk bar. */
+  selection?: boolean | State<Record<string, boolean>> | undefined
+  /** Called with the keys of every selected row after each change. */
+  onSelectionChange?: ((keys: string[]) => void) | undefined
+  /** The bulk bar's actions. */
+  bulk?: ((keys: string[]) => unknown) | undefined
+  page?: { size: number } | undefined
+  /** Called on Next or Previous, with the page or server cursor to load. */
+  onPageChange?: ((to: unknown, reason: 'next' | 'prev') => void) | undefined
+  /** A row's details. Default a list of every column. */
+  expand?: ((row: T) => unknown) | undefined
+  /** inline (default): they slide open in place at every width. sheet: a panel over the table below 1000px. */
+  details?: 'inline' | 'sheet' | undefined
+  /** Called with the row, the column's id and the new value when a cell edit is committed. */
+  onEdit?: ((row: T, column: string, value: unknown) => void) | undefined
+  /** The toolbar's own actions. */
+  actions?: unknown
+  /** The Columns disclosure. */
+  picker?: boolean | undefined
+  /** Columns hidden from the start, in the server's HTML too. Bind a State to keep what people choose. */
+  hiddenColumns?: readonly string[] | State<readonly string[]> | undefined
+  /** Forces a state; a Resource's own is used otherwise. */
+  status?: TableStatus | undefined
+  /** What to show when there are no rows: a title, a line of text and an action. */
+  empty?: { title?: unknown; text?: unknown; action?: unknown } | undefined
+  error?: { title?: unknown; text?: unknown } | undefined
+  /** Called by the error state's Retry. A Resource refreshes itself as well. */
+  onRetry?: (() => void) | undefined
+  /** A CSS height past which the body scrolls under a sticky header, such as `480px`. */
+  maxHeight?: string | undefined
+  /** The outline level of the table's state and sheet headings, under the page's h1. */
+  heading?: number | undefined
+}
+
+export const chevron = () => <svg aria-hidden="true" focusable="false" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M6 3.5 10.5 8 6 12.5" /></svg>
+export const sortIcon = () => <svg data-part="sort-icon" viewBox="0 0 10 10" aria-hidden="true"><path d="M5 1.5v7M2 5.5l3 3 3-3" fill="none" stroke="currentColor" stroke-width="1.4" /></svg>
+export const columnsIcon = () => <ColumnsIcon />
+const SKELETON_ROWS = 6
+// Table width. warp-data.css draws cards below 600 for data-phone="cards", which also catches a desktop column; from
+// here up the root says "columns" once it's measured, so cards are for a container a table really can't fill.
+const CARDS_BELOW = 480
+const DETAILS_FROM = 1000 // table width: below it `details="sheet"` opens the sheet (06 §5)
+
+const isResource = (r: unknown): r is Resource<unknown> => typeof (r as Resource<unknown> | null | undefined)?.refresh === 'function'
+const isState = (r: object | null | undefined): r is State<unknown> => r != null && !Array.isArray(r) && 'value' in r
+
+type Ctx<T> = {
+  id: string
+  level: number
+  cols: () => Column<T>[]
+  keyOf: (row: T) => string
+  read: (c: Column<T>, row: T) => unknown
+  sel: State<Record<string, boolean>> | undefined
+  open: State<Record<string, boolean>>
+  details: boolean
+  span: () => number
+  title: (row: T) => string
+  pick: (key: string, e: MouseEvent) => void
+  toggle: (row: T, from: HTMLElement) => void
+  body: (row: T) => unknown
+  edit?: ((row: T, column: string, value: unknown) => void) | undefined
+}
+
+/** Every column as a list: what a sheet and a detail row show by default. */
+function Fields<T>({ row, ctx }: { row: T; ctx: Ctx<T> }) {
+  return <dl data-scope="desc">{ctx.cols().map(c => <div key={c.id}><dt>{c.header}</dt><dd>{(c.cell ?? ((r: T) => ctx.read(c, r)))(row)}</dd></div>)}</dl>
+}
+
+export function Editor({ label, start, onDone, onLeave, invalid, describedby }: { label: string; start: string; onDone: (save: boolean, text: string) => void; onLeave?: (save: boolean, text: string) => void; invalid?: boolean; describedby?: string | undefined }) {
+  let input: HTMLInputElement | undefined
+  onMount(() => { input?.focus(); input?.select() })
+  return (
+    <label>
+      <span data-part="sr-only">{label}</span>
+      <input
+        ref={n => (input = n)}
+        data-part="editor"
+        aria-invalid={invalid ? 'true' : undefined}
+        aria-describedby={describedby}
+        value={start}
+        onKeyDown={(e: KeyboardEvent) => {
+          if (e.key !== 'Enter' && e.key !== 'Escape') return
+          e.preventDefault()
+          e.stopPropagation()
+          onDone(e.key === 'Enter', (e.currentTarget as HTMLInputElement).value)
+        }}
+        onBlur={(e: FocusEvent) => (onLeave ?? onDone)(true, (e.currentTarget as HTMLInputElement).value)}
+      />
+    </label>
+  )
+}
+
+// its own component: a new value patches this one text node, and flipping `editing` is the only thing that swaps it
+function Shown<T>({ row, col, value }: { row: T; col: Column<T>; value: () => unknown }) {
+  const c = untrack(() => col)
+  if (c.live) return <><span data-part="dir" aria-hidden="true"></span>{c.cell ? c.cell(row) : value()}</>
+  return <>{c.cell ? c.cell(row) : value()}</>
+}
+
+function Cell<T>({ row, col, ctx }: { row: T; col: Column<T>; ctx: Ctx<T> }) {
+  const c = untrack(() => col)
+  const editing = state(false)
+  const problem = state('')
+  const delta = state<string | undefined>(undefined)
+  const message = () => `${ctx.id}-${ctx.keyOf(row)}-${c.id}-e`
+  const value = () => ctx.read(c, row)
+  let td: HTMLElement | undefined
+  if (c.live) watch(value, (now, was) => {
+    if (was === undefined || now === was) return
+    const dir = (now as number) > (was as number) ? 'up' : 'down'
+    delta.value = delta.value === dir ? `${dir}2` : dir // two names per direction, so the flash replays
+  })
+  let seed = ''
+  const begin = () => { if (c.edit && !editing.value) { seed = String((untrack(value) as string | number | null | undefined) ?? ''); problem.value = ''; editing.value = true } }
+  const done = (save: boolean, text: string) => {
+    if (!editing.value) return
+    if (save) {
+      const next = typeof c.edit === 'function' ? c.edit(text) : text
+      const ok = c.validate?.(next) ?? true
+      if (ok !== true) { problem.value = typeof ok === 'string' ? ok : 'That value is not valid'; return }
+      ctx.edit?.(row, c.id, next)
+    }
+    problem.value = ''
+    editing.value = false
+    td?.focus()
+  }
+  return (
+    <td
+      ref={n => (td = n)}
+      role={c.rowHeader ? 'rowheader' : 'cell'}
+      data-col={c.id}
+      data-label={c.header}
+      data-numeric={c.numeric ? '' : undefined}
+      data-priority={c.priority}
+      data-card={c.card}
+      data-pinned={c.pin ? 'last' : undefined}
+      data-live={c.live ? '' : undefined}
+      data-delta={delta.value}
+      data-editable={c.edit ? '' : undefined}
+      data-invalid={problem.value ? '' : undefined}
+      tabindex={c.edit ? '0' : undefined}
+      aria-description={c.edit ? 'Press Enter to edit' : undefined}
+      onDblClick={c.edit ? begin : undefined}
+      onKeyDown={(c.edit ? (e: KeyboardEvent) => { if (e.target === e.currentTarget && (e.key === 'Enter' || e.key === 'F2')) { e.preventDefault(); begin() } } : undefined)!}
+    >
+      {editing.value
+        ? <><Editor label={`${c.header} for ${ctx.title(row)}`} start={seed} onDone={done} />{problem.value && <span data-part="sr-only" id={message()} role="alert">{problem.value}</span>}</>
+        : <Shown row={row} col={c} value={value} />}
+    </td>
+  )
+}
+
+function Row<T>({ row, ctx }: { row: T; ctx: Ctx<T> }) {
+  const key = () => ctx.keyOf(row)
+  const on = () => !!ctx.sel?.get(key())
+  const opened = () => !!(ctx.open.get(key()) as boolean | undefined)
+  const detail = () => `${ctx.id}-d-${key()}`
+  // a closing row stays until it has slid shut. A timer, because transitionend never comes
+  // when the transition is skipped, and that would strand an empty row
+  const mounted = state(untrack(opened))
+  let tr: HTMLElement | undefined
+  const settle = () => { if (!untrack(opened)) mounted.value = false }
+  watch(opened, now => {
+    if (now) return void (mounted.value = true)
+    if (!mounted.value) return
+    queueMicrotask(() => {
+      const slide = tr?.nextElementSibling?.querySelector('[data-part="slide"]')
+      setTimeout(settle, slide ? parseFloat(getComputedStyle(slide).transitionDuration) * 1000 : 0)
+    })
+  })
+  const click = (e: MouseEvent) => {
+    if ((e.target as Element).closest?.('button, input, select, a, label, [data-editable]')) return
+    ctx.toggle(row, (e.currentTarget as HTMLElement).querySelector<HTMLElement>('[data-part="expand"]')!)
+  }
+  return (
+    <>
+      <tr ref={n => (tr = n)} role="row" data-id={key()} data-selected={on() ? '' : undefined} data-clickable={ctx.details ? '' : undefined} onClick={(ctx.details ? click : undefined)!}>
+        {ctx.sel && <td role="cell" data-part="select" data-pinned="first"><label data-scope="checkbox"><input type="checkbox" checked={ctx.sel.get(key())} aria-label={`Select ${ctx.title(row)}`} onClick={(e: MouseEvent) => ctx.pick(key(), e)} /><span data-part="control"><svg viewBox="0 0 24 24" aria-hidden="true"><path data-part="check" pathLength="1" d="M5 12.5 L9.5 17 L19 7" /></svg></span></label></td>}
+        {ctx.details && <td role="cell" style="padding-inline:4px"><button type="button" data-part="expand" aria-expanded={opened() ? 'true' : 'false'} aria-controls={mounted.value ? detail() : undefined} aria-label={`Details for ${ctx.title(row)}`} onClick={(e: MouseEvent) => ctx.toggle(row, e.currentTarget as HTMLElement)}>{chevron()}</button></td>}
+        {ctx.cols().map(c => <Cell key={c.id} row={row} col={c} ctx={ctx} />)}
+      </tr>
+      {mounted.value && <tr data-part="detail" role="row" id={detail()}><td role="cell" colspan={ctx.span()}><div data-part="slide" data-closing={opened() ? undefined : ''}><div><div>{ctx.body(row)}</div></div></div></td></tr>}
+    </>
+  )
+}
+
+/** The tablet detail sheet (06 §5): non-modal, Escape closes it from anywhere, focus moves to Close and back to the row. */
+function Sheet<T>({ row, ctx, onClose }: { row: T; ctx: Ctx<T>; onClose: (restore?: boolean) => void }) {
+  let close: HTMLElement | undefined
+  let el: HTMLElement | undefined
+  onMount(() => {
+    close?.focus()
+    onCleanup(pushLayer({ el: el!, close: reason => onClose(reason === 'escape') }))
+  })
+  const id = () => `${ctx.id}-sh`
+  return (
+    <div ref={n => (el = n)} data-part="sheet" role="dialog" aria-modal="false" aria-labelledby={id()}>
+      <header>
+        <h4 id={id()} aria-level={ctx.level} style="margin:0">{ctx.title(row)}</h4>
+        <Button emphasis="ghost" tone="neutral" ref={n => (close = n)} onClick={() => onClose(true)}>Close</Button>
+      </header>
+      <div tabindex="0" role="group" aria-labelledby={id()}>{ctx.body(row)}</div>
+    </div>
+  )
+}
+
+export function ColumnsPanel<T>({ id, open, trigger, items, shown, flip }: { id: string; open: State<boolean>; trigger: () => HTMLElement; items: Column<T>[]; shown: (c: Column<T>) => boolean; flip: (c: Column<T>, shown: boolean) => void }) {
+  let panel: HTMLDivElement | undefined
+  use(popover, () => panel, () => ({ open: open.value, trigger: trigger(), side: 'bottom' as const, align: 'end' as const, onClose: () => (open.value = false) }))
+  return (
+    <div ref={n => (panel = n)} data-scope="popover" data-part="content" popover="manual" id={id} role="group" aria-label="Visible columns">
+      {items.map(c => <div key={c.id}><Checkbox checked={shown(c)} onChange={(e: Event) => flip(c, (e.currentTarget as HTMLInputElement).checked)}>{c.header}</Checkbox></div>)}
+    </div>
+  )
+}
+
+/**
+ * A data table (06 §5; data.html:1095-1124): a semantic <table> with explicit ARIA roles, so they survive the phone
+ * cards' display change. Sort, filter, Columns, resize, pin, selection with a bulk bar, details, inline edit and live
+ * cells, in the states ready, loading, empty and error, inside one frame. Rows are keyed: a sort moves nodes, a new
+ * value patches a cell. Given `T[]` it sorts, filters and pages by itself; a Resource or `server` leaves that to the
+ * server and reports what was asked. Queries its own width, never the window.
+ */
+export function Table<T>({ rows, caption, captionHidden, columns, rowKey = 'id', phone = 'cards', density, filter, query, sort, onSortChange, server, selection, onSelectionChange, bulk, page, onPageChange, expand, details = 'inline', onEdit, actions, picker = true, hiddenColumns, status, empty, error, onRetry, maxHeight, heading = 2 }: TableProps<T>) {
+  const id = uid('tbl')
+  const level = untrack(() => heading)
+  const cols = derived(() => columns)
+  const keyOf = (r: T) => String(typeof rowKey === 'function' ? rowKey(r) : (r as Record<string, unknown>)[rowKey])
+  const read = (c: Column<T>, r: T) => (c.value ? c.value(r) : (r as Record<string, unknown>)[c.id])
+  const named = derived(() => cols.value.find(c => c.rowHeader) ?? cols.value[0])
+  const title = (r: T) => String((read(named.value!, r) as string | number | null | undefined) ?? '')
+
+  const typed = untrack(() => query) ?? state('')
+  const order = untrack(() => sort) ?? state<TableSort | undefined>(undefined)
+  const given = untrack(() => selection)
+  const sel = given ? (given === true ? state<Record<string, boolean>>({}) : given) : undefined
+  const open = state<Record<string, boolean>>({})
+  const startHidden = untrack(() => hiddenColumns)
+  const hidden: State<readonly string[]> = isState(startHidden) ? startHidden : state<readonly string[]>(startHidden ?? [])
+  const at = state(0)
+  const sheet = state<{ row: T; from: HTMLElement } | undefined>(undefined)
+  const narrow = () => (el?.clientWidth ?? DETAILS_FROM) < DETAILS_FROM
+  let anchor: string | undefined
+  let el: HTMLDivElement | undefined
+  let columnsButton: HTMLElement | undefined
+  const picking = state(false)
+  // the panel is built on first open and kept, so a closed table carries none of its checkboxes
+  const picked = state(false)
+  const width = state<number | undefined>(undefined)
+  const small = derived(() => width.value !== undefined && width.value < CARDS_BELOW)
+  const shape = derived(() => (phone === 'cards' && (width.value ?? 0) >= CARDS_BELOW ? 'columns' : phone))
+
+  const source = () => (isResource(rows) ? rows.value : isState(rows) ? rows.value : rows) as readonly T[] | ListPage<T> | undefined
+  const remote = derived(() => !!server || isResource(rows))
+  const list = derived<readonly T[]>(() => { const v = source(); return Array.isArray(v) ? v as readonly T[] : (v as ListPage<T> | undefined)?.items ?? [] })
+  const envelope = derived<ListPage<T> | undefined>(() => { const v = source(); return v && !Array.isArray(v) ? v as ListPage<T> : undefined })
+  const shown = derived(() => {
+    if (remote.value) return list.value
+    const c = cols.value
+    const found = filterRows(list.value, typed.value, r => c.map(x => read(x, r)))
+    const s = order.value
+    const by = s && c.find(x => x.id === s.id)
+    if (!s || !by) return found
+    return sortRows(found, typeof by.sort === 'function' ? by.sort : r => read(by, r), s.dir)
+  })
+  const paged = derived(() => {
+    const size = page?.size
+    return size && !remote.value ? pageSlice(shown.value, at.value, size) : undefined
+  })
+  const visible = derived(() => paged.value?.rows ?? shown.value)
+  const phase = derived<TableStatus>(() => {
+    if (status) return status
+    const r = rows
+    if (isResource(r)) {
+      if (r.error) return 'error'
+      if (r.value === undefined) return 'loading'
+    }
+    return visible.value.length ? 'ready' : 'empty'
+  })
+  watch(() => typed.value, (_, was) => { if (was !== undefined) at.value = 0 })
+
+  const keys = derived(() => visible.value.map(keyOf))
+  const chosen = () => Object.keys(sel!.value).filter(k => sel!.value[k])
+  const write = (next: Record<string, boolean>) => { sel!.value = next; onSelectionChange?.(Object.keys(next).filter(k => next[k])) }
+  const pick = (key: string, e: MouseEvent) => {
+    const next = { ...sel!.value }
+    if (e.shiftKey && anchor !== undefined) for (const k of rangeOf(keys.value, anchor, key)) next[k] = true
+    else if (next[key]) delete next[key]
+    else next[key] = true
+    anchor = key
+    write(next)
+  }
+  const headerCheck = derived(() => (sel ? checkState(keys.value, k => !!(sel.get(k) as boolean | undefined)) : 'none'))
+  const pickAll = () => {
+    const next = { ...sel!.value }
+    const off = headerCheck.value === 'all'
+    for (const k of keys.value) { if (off) delete next[k]; else next[k] = true }
+    write(next)
+  }
+
+  const askSort = (c: Column<T>, dir?: SortDir) => {
+    const now = order.value
+    const next = { id: c.id, dir: dir ?? (now?.id === c.id && now.dir === 'ascending' ? 'descending' : 'ascending') }
+    order.value = next
+    onSortChange?.(next)
+  }
+  const sortable = derived(() => cols.value.filter(c => c.sort))
+
+  const hasDetails = untrack(() => expand !== undefined || columns.some(c => c.priority))
+  const toggle = (row: T, from: HTMLElement) => {
+    if (details === 'sheet' && narrow()) { sheet.value = { row, from }; return }
+    const k = keyOf(row)
+    const next = { ...open.value }
+    if (next[k]) delete next[k]
+    else next[k] = true
+    open.value = next
+  }
+  const closeSheet = (restore?: boolean) => { const from = sheet.value?.from; sheet.value = undefined; if (restore) from?.focus() }
+
+  const ctx: Ctx<T> = {
+    id, level, cols: () => cols.value, keyOf, read, sel, open, details: hasDetails, title, pick, toggle,
+    span: () => cols.value.length + (sel ? 1 : 0) + (hasDetails ? 1 : 0),
+    body: row => (expand ? expand(row) : <Fields row={row} ctx={ctx} />),
+    edit: (r, c, v) => onEdit?.(r, c, v),
+  }
+
+  const go = (reason: 'next' | 'prev') => {
+    if (remote.value) return onPageChange?.(reason === 'next' ? envelope.value?.next : envelope.value?.prev, reason)
+    at.value = paged.value!.page + (reason === 'next' ? 1 : -1)
+    onPageChange?.(at.value, reason)
+  }
+  const hasPrev = derived(() => phase.value === 'ready' && (remote.value ? envelope.value?.prev != null : (paged.value?.page ?? 0) > 0))
+  const hasNext = derived(() => phase.value === 'ready' && (remote.value ? envelope.value?.next != null : !!paged.value && paged.value.page < paged.value.pages - 1))
+  const range = derived(() => {
+    if (phase.value !== 'ready') return ''
+    const p = paged.value
+    if (p) return `${p.from}–${p.to} of ${shown.value.length}`
+    const total = envelope.value?.total
+    return total === undefined ? '' : `${visible.value.length} of ${total}`
+  })
+  const count = derived(() => (phase.value === 'ready' && !remote.value ? `${shown.value.length} of ${list.value.length}` : ''))
+  const footer = derived(() => page !== undefined || isResource(rows))
+
+  const retry = () => { onRetry?.(); if (isResource(rows))  rows.refresh() }
+  const clear = () => (typed.value = '')
+  const noticeTitle = derived(() => (phase.value === 'error' ? error?.title ?? 'This couldn’t load' : typed.value ? `No rows match “${typed.value}”` : empty?.title ?? 'Nothing here yet'))
+  const noticeText = derived(() => {
+    if (phase.value === 'error') { return error?.text ?? (isResource(rows) && rows.error instanceof Error ? rows.error.message : 'Try again in a moment.') }
+    return typed.value ? 'Try a shorter term, or clear the filter.' : empty?.text
+  })
+
+  use(table, () => el, () => ({ hidden: hidden.value, rows: visible.value, onWidth: w => (width.value = w) }))
+  onCleanup(() => (sheet.value = undefined))
+
+  const toolbar = derived(() => filter !== undefined || actions !== undefined || !!(picker as unknown))
+  const hideable = derived(() => cols.value.filter(c => !c.pin))
+  const flip = (c: Column<T>, show: boolean) => { hidden.value = show ? hidden.value.filter(x => x !== c.id) : [...hidden.value, c.id] }
+  return (
+    <div ref={n => (el = n)} data-scope="table" data-phone={shape.value} data-state={phase.value} data-density={density} id={id}>
+      {untrack(() => hidden.value.length > 0) && <style data-part="hide"
+        // oxlint-disable-next-line weft/no-html-sink -- hideRule builds a CSS rule from escaped column ids, no markup
+        innerHTML={untrack(() => hideRule(id, hidden.value))}></style>}
+      {toolbar.value && (
+        <div data-part="toolbar">
+          {filter !== undefined && <Search label={filter} value={typed.value} onInput={(e: Event) => (typed.value = (e.currentTarget as HTMLInputElement).value)} />}
+          <span data-part="count" aria-live="polite">{count.value}</span>
+          <span data-part="spacer"></span>
+          {actions}
+          {picker && (
+            <div>
+              <Button emphasis="outline" tone="neutral" ref={n => (columnsButton = n)} aria-expanded={picking.value ? 'true' : 'false'} aria-controls={picked.value ? `${id}-cols` : undefined} onClick={() => { picked.value = true; picking.value = !picking.value }}>{columnsIcon()}Columns</Button>
+              {picked.value && <ColumnsPanel id={`${id}-cols`} open={picking} trigger={() => columnsButton!} items={hideable.value} shown={c => !hidden.value.includes(c.id)} flip={flip} />}
+            </div>
+          )}
+        </div>
+      )}
+      {sel && (
+        <div data-part="bulk" hidden={chosen().length === 0} role="region" aria-label="Bulk actions">
+          <b>{chosen().length} selected</b>
+          {bulk?.(chosen())}
+          <Button emphasis="ghost" onClick={() => write({})}>Clear</Button>
+        </div>
+      )}
+      {phone === 'cards' && small.value && sortable.value.length > 0 && (
+        <div data-part="sortbar">
+          <Select label="Sort by" size="sm" value={order.value?.id ?? ''} placeholder="None" options={sortable.value.map(c => ({ value: c.id, label: c.header }))} onChange={(e: Event) => { const c = cols.value.find(x => x.id === (e.currentTarget as HTMLInputElement).value); if (c) askSort(c, order.value?.dir ?? 'ascending') }} />
+          <Button emphasis="outline" tone="neutral" size="sm" aria-label="Toggle sort direction" disabled={!order.value} onClick={() => { const c = cols.value.find(x => x.id === order.value?.id); if (c) askSort(c, order.value!.dir === 'ascending' ? 'descending' : 'ascending') }}>{order.value?.dir === 'ascending' ? '↑' : '↓'}</Button>
+        </div>
+      )}
+      {/* a scroller (wide on a phone, or `maxHeight`) a keyboard can reach: focus it and the arrows scroll, named by the caption */}
+      <div data-part="viewport" tabindex="0" role="region" aria-labelledby={`${id}-cap`} style={maxHeight ? `--warp-table-max-h:${maxHeight}` : undefined}>
+        <table role="table" aria-labelledby={`${id}-cap`} aria-rowcount={shown.value.length + 1}>
+          <caption id={`${id}-cap`} data-part={captionHidden ? 'sr-only' : undefined}>{caption}</caption>
+          <thead>
+            <tr role="row">
+              {sel && <th role="columnheader" scope="col" data-part="select" data-pinned="first"><Checkbox checked={headerCheck.value === 'all'} indeterminate={headerCheck.value === 'some'} aria-label="Select all rows on this page" onClick={pickAll} /></th>}
+              {hasDetails && <th role="columnheader" scope="col" style="inline-size:1px;padding-inline:4px"><span data-part="sr-only">Details</span></th>}
+              {cols.value.map(c => (
+                <th
+                  key={c.id}
+                  role="columnheader"
+                  scope="col"
+                  data-col={c.id}
+                  data-numeric={c.numeric ? '' : undefined}
+                  data-priority={c.priority}
+                  data-pinned={c.pin ? 'last' : undefined}
+                  aria-sort={order.value?.id === c.id ? order.value.dir : undefined}
+                >
+                  {c.sort ? <button type="button" data-part="sort" onClick={() => askSort(c)}>{c.header}{sortIcon()}</button> : c.header}
+                  {c.resize && <span data-part="resize" role="separator" aria-orientation="vertical" tabindex="0" aria-label={`Resize ${c.header} column`} aria-valuenow="80" aria-valuemin="80" aria-valuemax="480"></span>}
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody aria-busy={phase.value === 'loading' ? 'true' : undefined}>
+            {phase.value === 'loading'
+              ? Array.from({ length: SKELETON_ROWS }, (_, n) => n).map(n => (
+                <tr key={n} role="row">
+                  {sel && <td role="cell" data-part="select"></td>}
+                  {hasDetails && <td role="cell"></td>}
+                  {cols.value.map(c => <td key={c.id} role="cell" data-col={c.id} data-priority={c.priority}><span data-part="skeleton" style={`--w:${30 + ((n * 17 + c.id.length * 9) % 55)}%`}></span></td>)}
+                </tr>
+              ))
+              : phase.value === 'ready'
+                ? visible.value.map(r => <Row key={keyOf(r)} row={r} ctx={ctx} />)
+                : (
+                  <tr role="row">
+                    <td role="cell" colspan={ctx.span()} style="white-space:normal;block-size:auto">
+                      <div data-part="state" data-kind={phase.value} role={phase.value === 'error' ? 'alert' : 'status'}>
+                        <svg viewBox="0 0 72 40" aria-hidden="true"><line x1="8" y1="0" x2="8" y2="40" /><line x1="22" y1="0" x2="22" y2="40" /><line x1="36" y1="0" x2="36" y2="40" /><line x1="50" y1="0" x2="50" y2="40" /><line x1="64" y1="0" x2="64" y2="40" /><path d={phase.value === 'error' ? 'M0 20H30' : 'M0 14H72M0 26H72'} /></svg>
+                        <h4 aria-level={level}>{noticeTitle.value}</h4>
+                        <p>{noticeText.value}</p>
+                        {phase.value === 'error'
+                          ? <Button emphasis="outline" tone="neutral" onClick={retry}>Retry</Button>
+                          : typed.value ? <Button emphasis="outline" tone="neutral" onClick={clear}>Clear filter</Button> : empty?.action}
+                      </div>
+                    </td>
+                  </tr>
+                )}
+          </tbody>
+        </table>
+      </div>
+      {footer.value && (
+        <div data-part="footer">
+          <span>{range.value}</span>
+          <div style="display:flex;gap:8px">
+            <Button emphasis="outline" tone="neutral" size="sm" disabled={!hasPrev.value} onClick={() => go('prev')}>Previous</Button>
+            <Button emphasis="outline" tone="neutral" size="sm" disabled={!hasNext.value} onClick={() => go('next')}>Next</Button>
+          </div>
+        </div>
+      )}
+      {sheet.value && <Sheet row={sheet.value.row} ctx={ctx} onClose={closeSheet} />}
+    </div>
+  )
+}

package/src/Tabs.tsx

@@ -0,0 +1,67 @@
+import { indicator, nextIndex, overflow, uid } from '@weft-js/warp-core'
+import { untrack } from '@weft-js/core'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/components/tabs.css'
+
+/** One tab. */
+export type TabOption<V extends string> = { value: V; label: unknown; disabled?: boolean | undefined }
+
+/**
+ * Tabs (05 §4; components.html:660-706, 1821-1849): line (default) · pill · enclosed. APG automatic activation:
+ * ←/→ move and select (wrapping), Home/End, one tab stop; every tab controls a tabpanel. The indicator travels
+ * through the rail on the sweep curve; a list wider than its box scrolls with edge fades and keeps the selected tab
+ * in view. `children(value)` renders a panel; a pill strip filters one shared panel.
+ */
+export function Tabs<V extends string>({ label, value, onChange, options, variant, children }: { label: string; value: V; onChange: (v: V) => void; options: TabOption<V>[]; variant?: 'line' | 'pill' | 'enclosed' | undefined; children?: (value: V) => unknown }) {
+  const base = uid('tabs')
+  const kind = untrack(() => variant)
+  const tab = (i: number) => `${base}-t${i}`
+  const panel = (i: number) => (kind === 'pill' ? `${base}-p0` : `${base}-p${i}`)
+  let list: HTMLDivElement | undefined
+  use(indicator, () => list, () => ({ selected: '[aria-selected="true"]', at: value }))
+  use(overflow, () => list, () => list?.querySelector<HTMLElement>('[aria-selected="true"]') ?? null)
+  const onKey = (e: KeyboardEvent) => {
+    const tabs = options.filter(o => !o.disabled)
+    const at = tabs.findIndex(o => o.value === value)
+    const rtl = getComputedStyle(e.currentTarget as Element).direction === 'rtl'
+    const to = nextIndex(e.key, at, tabs.length, { rtl })
+    if (to < 0) return
+    e.preventDefault()
+    onChange(tabs[to]!.value)
+    ;(e.currentTarget as HTMLElement).querySelectorAll<HTMLElement>('[role="tab"]')[options.findIndex(o => o.value === tabs[to]!.value)]?.focus() // by position: a hydrated server id isn't this side's
+  }
+  const selected = () => options.findIndex(o => o.value === value)
+  return (
+    <div data-scope="tabs" data-part="root" data-variant={kind === 'line' ? undefined : kind}>
+      <div ref={n => (list = n)} data-part="list" role="tablist" aria-label={label} onKeyDown={onKey}>
+        {options.map((o, i) => (
+          <button
+            key={o.value}
+            data-part="trigger"
+            role="tab"
+            type="button"
+            id={tab(i)}
+            aria-controls={panel(i)}
+            aria-selected={o.value === value ? 'true' : 'false'}
+            tabindex={o.value === value ? undefined : '-1'}
+            disabled={o.disabled}
+            onClick={() => onChange(o.value)}
+          >
+            {o.label}
+          </button>
+        ))}
+        <span data-part="indicator" aria-hidden="true" data-instant=""></span>
+      </div>
+      {kind === 'pill' ? (
+        <div data-part="content" role="tabpanel" id={panel(0)} aria-labelledby={tab(selected())} tabindex="0" hidden={!children}>{children?.(value)}</div>
+      ) : (
+        options.map((o, i) => (
+          <div key={o.value} data-part="content" role="tabpanel" id={panel(i)} aria-labelledby={tab(i)} tabindex="0" hidden={o.value !== value}>
+            {children?.(o.value)}
+          </div>
+        ))
+      )}
+    </div>
+  )
+}

package/src/Tag.tsx

@@ -0,0 +1,15 @@
+import { XIcon } from '@weft-js/warp-icons'
+import type { Tone } from './Button'
+import './styles'
+import '@weft-js/warp-core/styles/components/tag.css'
+
+/** A tag: user content (05 §6). `onRemove` adds the remove button, named "Remove {label}". */
+export function Tag({ tone, swatch, onRemove, label, children, ...rest }: { tone?: Tone | undefined; swatch?: boolean; onRemove?: () => void; /** The name for the remove button, when `children` is an expression (the compiler hands those over as a thunk). */ label?: string | undefined; children: unknown; [attr: string]: unknown }) {
+  return (
+    <span data-scope="tag" data-tone={tone} {...rest}>
+      {swatch && <span data-part="swatch"></span>}
+      {children}
+      {onRemove && <button type="button" data-part="remove" aria-label={`Remove ${(label ?? children) as string}`} onClick={onRemove}><XIcon /></button>}
+    </span>
+  )
+}

package/src/Ticker.tsx

@@ -0,0 +1,36 @@
+import { derived } from '@weft-js/core'
+import './styles'
+import '@weft-js/warp-core/styles/components/ticker.css'
+
+/** Props for Ticker. */
+export interface TickerProps {
+  value: number
+  /** Passed to Intl.NumberFormat: `{ style: 'currency', currency: 'USD' }`. */
+  format?: Intl.NumberFormatOptions | undefined
+  locale?: string | undefined
+}
+
+/**
+ * A number that rolls (05 §5): each digit is a column of 0–9 drawn by CSS and moved by one custom property, so a change
+ * writes one attribute per digit that moved. Digits are keyed from the right, so a new leading digit arrives on its own.
+ * The real value is in the DOM for readers; under reduced motion it swaps.
+ */
+export function Ticker({ value, format, locale }: TickerProps) {
+  const fmt = derived(() => new Intl.NumberFormat(locale, format)) // apart from the text: a tick mustn't rebuild it
+  const text = derived(() => fmt.value.format(value))
+  const parts = derived(() => {
+    // oxlint-disable-next-line typescript/no-misused-spread -- code points are what it wants: a glyph per step, and Intl.Segmenter would cost a hot loop
+    const s = [...text.value]
+    return s.map((c, i) => ({ c, at: s.length - i }))
+  })
+  return (
+    <span data-scope="ticker">
+      <span data-part="sr">{text.value}</span>
+      <span aria-hidden="true">
+        {parts.value.map(p => /\d/.test(p.c)
+          ? <span key={p.at} data-part="digit" style={`--_d:${p.c};--_at:${p.at}`}></span>
+          : <span key={p.at} data-part="sym">{p.c}</span>)}
+      </span>
+    </span>
+  )
+}