@weft-js/warp 0.0.0-stage → 0.1.0

package/src/VirtualList.tsx

@@ -0,0 +1,386 @@
+import { derived, DEV, effect, flush, onCleanup, onMount, state, untrack } from '@weft-js/core'
+import { measureEngine, type MeasureHandle, type MeasureProvider } from '@weft-js/core/text'
+import { slices, virtualizer, type VirtualAlign, type VirtualKey, type Virtualizer } from '@weft-js/warp-core'
+import './styles'
+import '@weft-js/warp-core/styles/data/virtual.css'
+
+/** What a list hands out through `control`, to scroll and measure from outside. */
+export interface VirtualControl {
+  scrollTo(key: VirtualKey, align?: VirtualAlign): void
+  scrollToEnd(): void
+  /** Render the row, wherever it is, and move focus to it. */
+  focus(key: VirtualKey): void
+  /** Move focus by rows from the focused one. */
+  move(by: number): void
+  /** The key of the focused or last-focused row. */
+  active(): VirtualKey | undefined
+}
+
+/** Props for VirtualList. */
+export interface VirtualListProps<T> {
+  items: readonly T[]
+  rowKey: (item: T) => VirtualKey
+  children: (item: () => T, index: () => number) => unknown
+  /** The list's name. */
+  label?: string | undefined
+  /** The row's text. Rows get exact heights before they render when the app has `text.measure`, and it's measured otherwise. */
+  text?: (item: T) => string | null | undefined
+  /** Rows that look different around the same text: each gets its own measurement of everything but the text. */
+  variant?: ((item: T) => string) | undefined
+  /** A row's height before it's known. Default 48. */
+  estimate?: number | undefined
+  /** Pixels between rows. */
+  gap?: number | undefined
+  /** Pixels of rows kept rendered past each edge of the view, so a fast scroll shows no gaps. */
+  overscan?: number | undefined
+  /** Rows on the server and in the first paint. Default 20. */
+  initial?: number | undefined
+  /** Stay at the end as rows arrive while the user is within this many pixels of it. */
+  stick?: number | undefined
+  /** `end` opens at the last row and grows upward, as a chat does. */
+  from?: 'start' | 'end' | undefined
+  /** `list` by default (rows are `listitem`s; `group` with `bareRows`); `feed`, `log` and the rest bring their own row role. */
+  role?: string | undefined
+  /** The role each row takes, such as `option` or `article`. */
+  rowRole?: string | undefined
+  /** Rows take no list semantics: what's inside them says what it is, and the scroller is a labelled group. */
+  bareRows?: boolean | undefined
+  /** Keep this role off the scroller and put it on the list inside. */
+  inner?: boolean | undefined
+  /** `ol` renders an ordered list with <li> rows; `div` otherwise. */
+  tag?: 'div' | 'ol' | undefined
+  /** Row keys move focus: ↑/↓, Home/End, one tab stop on the rows. */
+  roving?: boolean | undefined
+  /** The total isn't the list's to know (a log with history to load): `aria-setsize` is -1, and an arrival writes no row. */
+  open?: boolean | undefined
+  /** On a key the list doesn't use. */
+  onRowKey?: ((e: KeyboardEvent, control: VirtualControl) => void) | undefined
+  /** Called when the view nears the first row: load older rows. */
+  onStart?: (() => void) | undefined
+  /** Called when the view nears the last row: load more. */
+  onEnd?: (() => void) | undefined
+  /** Called with `true` when the list starts holding to the end, and `false` when the user scrolls away. */
+  onStick?: ((stuck: boolean) => void) | undefined
+  /** Called when a row's measured height differs from the estimate, with both heights. For tuning. */
+  onDrift?: ((index: number, predicted: number, actual: number) => void) | undefined
+  /** Hands over a control to scroll to, focus or move between rows from outside. */
+  control?: ((c: VirtualControl) => void) | undefined
+  /** The scroller's tabindex. Default 0, none with `roving`. */
+  tabindex?: number | undefined
+  /** The scroller's `data-scope`, for styling it as another component. */
+  scope?: string | undefined
+  /** The scroller's `data-part`, when it is a part of a larger component. */
+  part?: string | undefined
+  /** The inner list's `data-scope`. */
+  listScope?: string | undefined
+  height?: string | undefined
+  /** `aria-busy`: more is loading. */
+  busy?: boolean | undefined
+  class?: string | undefined
+}
+
+type MeasureOptions = Parameters<MeasureProvider['prepare']>[2]
+interface Metric { font: string; line: number; wrap: number; chrome: number; opts: { whiteSpace: 'normal' | 'pre-wrap'; letterSpacing?: number | undefined } }
+const EDGE = 8 // rows from the end at which onStart and onEnd ask for more
+const BATCH = 256 // rows prepared between index updates
+const LONG = 'mmmm '.repeat(400)
+
+function fontOf(c: CSSStyleDeclaration) {
+  return `${c.fontStyle} ${c.fontWeight} ${c.fontSize} ${c.fontFamily}`
+}
+
+/** One row's text and everything around it, read from a real hidden row: nothing here knows warp's padding. */
+function metricOf(probe: HTMLElement): Metric | undefined {
+  const box = probe.querySelector<HTMLElement>('[data-measure]')
+  if (!box) return
+  const c = getComputedStyle(box)
+  const line = parseFloat(c.lineHeight)
+  if (!line) return // `normal` has no one answer
+  box.style.display = 'block'
+  box.textContent = 'x'
+  const chrome = probe.getBoundingClientRect().height - line
+  box.textContent = LONG
+  const wrap = box.getBoundingClientRect().width - (parseFloat(c.paddingInlineStart) || 0) - (parseFloat(c.paddingInlineEnd) || 0)
+  const white = c.whiteSpaceCollapse === 'preserve' || /pre/.test(c.whiteSpace)
+  return { font: fontOf(c), line, wrap, chrome, opts: { whiteSpace: white ? 'pre-wrap' : 'normal', letterSpacing: parseFloat(c.letterSpacing) || undefined } }
+}
+
+/**
+ * A long list (06 §9): one window of rows at known offsets. Give it `text` and rows have exact heights before they
+ * exist; rows the engine can't size are measured when they render, and what's on screen never moves when one corrects.
+ */
+export function VirtualList<T>(props: VirtualListProps<T>) {
+  let el: HTMLElement | undefined, list: HTMLElement | undefined
+  let v: Virtualizer | undefined
+  let engine: MeasureProvider | null = null
+  let stop: (() => void) | undefined
+  let measuredAt = -1
+  let slicing = false, cursor = 0 // what the idle pass has reached: a change behind it is prepared now, ahead of it later
+  const waiting: [HTMLElement, VirtualKey, (undo: () => void) => void][] = []
+  const metrics = new Map<string, Metric>()
+  const prepared = new Map<VirtualKey, { text: string; handle: MeasureHandle; font: string }>()
+  const probes = new Map<string, HTMLElement>()
+  const active = state<VirtualKey | undefined>(undefined)
+  const pending = state<VirtualKey | undefined>(undefined)
+
+  const items = derived(() => props.items)
+  const keyOf = (item: T) => props.rowKey(item)
+  const keys = derived(() => items.value.map(keyOf))
+  const variantOf = (item: T) => props.variant?.(item) ?? ''
+  const first = untrack(() => {
+    const n = items.value.length, count = Math.min(n, props.initial ?? 20)
+    return Array.from({ length: count }, (_, i) => (props.from === 'end' ? n - count + i : i))
+  })
+  // Keys, not indices: a prepend renumbers every row, and that mustn't look like a new set of rows.
+  const shown = state<VirtualKey[]>(untrack(() => first.map(i => keyOf(items.value[i]!))))
+  const index = derived(() => new Map(keys.value.map((k, i) => [k, i])))
+  const rows = derived(() => {
+    const all = items.value, at = index.value
+    return shown.value.flatMap(key => { const i = at.get(key); return i === undefined ? [] : [{ item: all[i]!, i, key }] })
+  })
+
+  const samples = derived(() => {
+    if (!props.text) return []
+    const seen = new Map<string, T>()
+    for (const item of items.value) {
+      const name = variantOf(item)
+      if (!seen.has(name)) seen.set(name, item)
+      if (!props.variant) break
+    }
+    return [...seen]
+  })
+  const probing = state(false)
+
+  function prepare(i: number) {
+    const item = untrack(() => items.value[i]), m = metrics.get(variantOf(item!)), value = props.text?.(item!)
+    if (!engine || !m || value == null) return false
+    const key = keyOf(item!), had = prepared.get(key)
+    if (had && had.text === value && had.font === m.font) return false
+    // Preserved white space leaves the fast tier, so it's asked for only by text that has some to preserve.
+    const handle = engine.prepare(value, m.font, m.opts.whiteSpace === 'pre-wrap' && !/\n| {2}|\t/.test(value) ? { ...m.opts, whiteSpace: 'normal' } as MeasureOptions : m.opts as MeasureOptions)
+    prepared.set(key, { text: value, handle, font: m.font })
+    void handle.ready?.then(() => { const at = index.value.get(key); if (at !== undefined) v?.refresh(at, at + 1) })
+    return true
+  }
+
+  const size = (i: number) => {
+    if (!engine) return
+    const item = items.value[i]!, m = metrics.get(variantOf(item)), p = prepared.get(keyOf(item))
+    if (!m || !p || p.text !== props.text?.(item)) return
+    return m.chrome + Math.max(m.line, engine.layout(p.handle, m.wrap, m.line).height)
+  }
+
+  function calibrate() {
+    metrics.clear()
+    for (const [name, probe] of probes) {
+      const m = metricOf(probe)
+      if (m) metrics.set(name, m)
+    }
+    measuredAt = list?.getBoundingClientRect().width ?? -1
+  }
+
+  /** The window now, so it paints exact; the rest a few ms at a time, so 10,000 rows never block a frame. */
+  function prepareAll() {
+    stop?.()
+    slicing = true
+    cursor = 0
+    for (const key of shown.value) { const i = index.value.get(key); if (i !== undefined) prepare(i) }
+    v?.refresh()
+    let lo = 0, done = 0
+    stop = slices(() => {
+      if (cursor >= items.value.length) {
+        slicing = false
+        if (cursor > lo) v?.refresh(lo, cursor)
+        return false
+      }
+      if (prepare(cursor++)) done++
+      if (done >= BATCH) { v?.refresh(lo, cursor); lo = cursor; done = 0 }
+      return true
+    })
+  }
+
+  function start() {
+    calibrate()
+    prepareAll()
+  }
+
+  const fontsDone = () => { engine?.clear(); prepared.clear(); start() }
+  const root = () => el!.ownerDocument.documentElement
+  let dials: MutationObserver | undefined
+
+  /** Bring a row into view if it isn't. Before its key has arrived this does nothing, and the keys effect comes back. */
+  function reveal(key: VirtualKey) {
+    const i = index.value.get(key)
+    if (i === undefined || !v) return
+    const a = v.anchor(), now = v.sizes.offset(a.index) + a.within, top = v.sizes.offset(i)
+    if (top < now) v.scrollTo(i, 'start')
+    else if (top + v.sizes.get(i)! > now + el!.clientHeight) v.scrollTo(i, 'end')
+  }
+
+  const control: VirtualControl = {
+    scrollTo(key, align) {
+      const i = index.value.get(key)
+      if (i !== undefined) v?.scrollTo(i, align)
+    },
+    scrollToEnd: () => v?.scrollToEnd(),
+    focus(key) {
+      active.value = key
+      pending.value = key
+      v?.update({})
+      reveal(key)
+    },
+    move(by) {
+      const all = keys.value, at = all.indexOf(active.value as VirtualKey)
+      control.focus(all[Math.max(0, Math.min(all.length - 1, (at < 0 ? v!.anchor().index : at) + by))]!)
+    },
+    active: () => active.value,
+  }
+
+  function onKeyDown(e: KeyboardEvent) {
+    if (props.roving && !e.altKey && !e.ctrlKey && !e.metaKey) {
+      const n = keys.value.length
+      const to = e.key === 'ArrowDown' ? 1 : e.key === 'ArrowUp' ? -1 : e.key === 'Home' ? -n : e.key === 'End' ? n : 0
+      if (to && (e.target as HTMLElement).closest?.('[data-part="row"]') === e.target) {
+        e.preventDefault()
+        control.move(to)
+        return
+      }
+    }
+    props.onRowKey?.(e, control)
+  }
+
+  let askedStart = -1, askedEnd = -1
+  function edges(indices: number[]) {
+    const n = keys.value.length
+    if (!n || !indices.length) return
+    if (props.onEnd && indices.at(-1)! >= n - EDGE && askedEnd !== n) { askedEnd = n; props.onEnd() }
+    if (props.onStart && indices[0]! <= EDGE && askedStart !== n) { askedStart = n; props.onStart() }
+  }
+
+  onMount(() => {
+    queueMicrotask(() => {
+      if (!el) return
+      v = virtualizer(el, {
+        keys: untrack(() => keys.value), spacer: list!, estimate: untrack(() => props.estimate ?? 48), gap: untrack(() => props.gap), overscan: untrack(() => props.overscan),
+        stick: untrack(() => props.stick), from: untrack(() => props.from), size: (i, width) => {
+          if (width !== measuredAt && metrics.size) calibrate()
+          return size(i)
+        },
+        pinned: () => (active.value === undefined ? [] : [active.value]),
+        onRange: indices => { for (const i of indices) prepare(i); shown.value = indices.map(i => keys.value[i]!); edges(indices) },
+        onStick: s => props.onStick?.(s), onDrift: (i, p, a) => {
+          props.onDrift?.(i, p, a)
+          if (DEV && engine && Math.abs(p - a) > 1 && prepared.has(keys.value[i]!)) console.debug(`weft: X001 row ${i} predicted ${p}px and renders ${a}px`)
+        },
+      })
+      for (const [row, key, keep] of waiting.splice(0)) keep(v.attach(row, key))
+      effect(() => keys.value, k => {
+        v!.update({ keys: k })
+        const key = untrack(() => pending.value)
+        if (key !== undefined) reveal(key)
+      })
+      effect(() => active.value, () => v!.update({}))
+      untrack(() => props.control?.(control))
+      if (!untrack(() => props.text)) return
+      void measureEngine().then(e => {
+        if (!e || !el) return
+        engine = e
+        probing.value = true
+        flush()
+        start()
+        effect(() => items.value, (_, prev) => {
+          if (prev === undefined) return
+          let lo = -1, hi = 0
+          const to = slicing ? cursor : items.value.length
+          for (let i = 0; i < to; i++) if (prepare(i)) { if (lo < 0) lo = i; hi = i + 1 }
+          if (lo >= 0) v!.refresh(lo, hi)
+        })
+        effect(() => samples.value.length, () => { // a kind of row that wasn't here at the start
+          if (untrack(() => samples.value.every(([name]) => metrics.has(name)))) return
+          queueMicrotask(() => { calibrate(); prepareAll() })
+        })
+        document.fonts?.addEventListener?.('loadingdone', fontsDone)
+        dials = new MutationObserver(() => { calibrate(); prepareAll() })
+        dials.observe(root(), { attributes: true, attributeFilter: ['class', 'style', 'data-theme', 'data-expression', 'data-density'] })
+      })
+    })
+    onCleanup(() => {
+      stop?.()
+      dials?.disconnect()
+      document.fonts?.removeEventListener?.('loadingdone', fontsDone)
+      v?.destroy()
+    })
+  })
+
+  function Row(p: { row: { item: T; i: number; key: VirtualKey } }) {
+    let node: HTMLElement | undefined
+    const key = untrack(() => p.row.key)
+    onMount(() => {
+      let undo: (() => void) | undefined
+      const keep = (u: () => void) => (undo = u)
+      if (v) keep(v.attach(node!, key))
+      else waiting.push([node!, key, keep])
+      onCleanup(() => undo?.())
+      effect(() => pending.value === key, go => {
+        if (!go) return
+        pending.value = undefined
+        ;(node!.querySelector<HTMLElement>('[data-focus]') ?? node!).focus()
+      })
+    })
+    const pos = () => p.row.i
+    const place = untrack(() => `position:absolute;inset-inline:0;inset-block-start:0;transform:translateY(${pos() * (props.estimate ?? 48)}px)`) // the first paint; the virtualizer owns it after
+    const attrs = () => ({
+      ref: (n: HTMLElement) => (node = n),
+      'data-part': 'row',
+      role: rowRole(),
+      'aria-posinset': props.bareRows ? undefined : pos() + 1,
+      'aria-setsize': props.bareRows ? undefined : props.open ? -1 : keys.value.length,
+      'data-index': props.bareRows ? pos() + 1 : undefined,
+      tabindex: props.roving ? (active.value === key || (active.value === undefined && key === shown.value[0]) ? 0 : -1) : undefined,
+      style: place,
+      onFocusIn: () => { active.value = key },
+    })
+    const body = props.children(() => p.row.item, pos)
+    return props.tag === 'ol' ? <li {...attrs()}>{body}</li> : <div {...attrs()}>{body}</div>
+  }
+
+  const inner = untrack(() => props.inner)
+  const listRole = () => props.role ?? (props.bareRows ? 'group' : 'list')
+  /** A list's rows are its items (axe aria-required-children); `feed`, `log` and bare rows bring or need none. */
+  const rowRole = () => props.rowRole ?? (props.tag !== 'ol' && listRole() === 'list' ? 'listitem' : undefined)
+  const listAttrs = () => ({
+    ref: (n: HTMLElement) => (list = n),
+    'data-part': 'spacer',
+    'data-scope': props.listScope,
+    role: inner ? listRole() : props.tag === 'ol' ? undefined : rowRole() ? 'presentation' : undefined,
+    'aria-label': inner ? props.label : undefined,
+    'aria-busy': inner && props.busy ? 'true' : undefined,
+    style: 'position:relative;flex:none',
+  })
+  function Probe(p: { sample: [string, T] }) {
+    const [name, item] = untrack(() => p.sample)
+    const body = props.children(() => item, () => 0) // once: measuring overwrites the row's text
+    const attrs = { ref: (n: HTMLElement) => probes.set(name, n), 'data-part': 'row', 'data-probe': '', 'aria-hidden': 'true', inert: true, style: 'position:absolute;inset-inline:0;inset-block-start:0;visibility:hidden;contain:layout' }
+    return untrack(() => props.tag) === 'ol' ? <li {...attrs}>{body}</li> : <div {...attrs}>{body}</div>
+  }
+  return (
+    <div
+      ref={n => (el = n)}
+      class={props.class}
+      data-scope={props.scope ?? (props.part ? undefined : 'virtual')}
+      data-part={props.part}
+      data-variable={props.scope || props.part ? undefined : ''}
+      role={inner ? undefined : listRole()}
+      aria-label={inner ? undefined : props.label}
+      aria-live={props.role === 'log' ? 'off' : undefined}
+      aria-busy={!inner && props.busy ? 'true' : undefined}
+      tabindex={untrack(() => props.roving) ? undefined : props.tabindex ?? 0}
+      style={props.height ? `block-size:${props.height}` : undefined}
+      onKeyDown={onKeyDown}
+    >
+      {untrack(() => props.tag) === 'ol'
+        ? <ol {...listAttrs()}>{rows.value.map(r => <Row key={r.key} row={r} />)}{probing.value && samples.value.map(s => <Probe key={s[0]} sample={s} />)}</ol>
+        : <div {...listAttrs()}>{rows.value.map(r => <Row key={r.key} row={r} />)}{probing.value && samples.value.map(s => <Probe key={s[0]} sample={s} />)}</div>}
+    </div>
+  )
+}

package/src/admin/ApiKeys.tsx

@@ -0,0 +1,136 @@
+import { KeyIcon } from '@weft-js/warp-icons'
+import { agoText, usedWithinDay } from '@weft-js/warp-core'
+import { derived, state, type State } from '@weft-js/core'
+import { Badge } from '../Badge'
+import { Button } from '../Button'
+import { Checkbox } from '../Choice'
+import { Input } from '../Field'
+import { Modal } from '../Modal'
+import { Select } from '../Select'
+import { Table, type Column } from '../Table'
+import { toast } from '../Toast'
+import { ConfirmDialog, TypeToConfirm } from './Danger'
+import { SecretReveal, useReveal } from './Secret'
+import { afterFlush, guarded, latch, read } from './atoms'
+import '../styles'
+import '@weft-js/warp-core/styles/flows/tokens.css'
+import '@weft-js/warp-core/styles/flows/base.css'
+import '@weft-js/warp-core/styles/rich/helpers.css'
+import '@weft-js/warp-core/styles/layout/tokens.css'
+import '@weft-js/warp-core/styles/layout/row.css'
+import '@weft-js/warp-core/styles/layout/stack.css'
+import '@weft-js/warp-core/styles/flows/api-key.css'
+import '@weft-js/warp-core/styles/flows/choice.css'
+
+/** An API key as listed: never the secret, only its prefix. */
+export type ApiKey = { id: string; name: string; prefix: string; scopes: string[]; created: string; lastUsed?: string }
+/** What the create form hands to `onCreate`. */
+export type KeyDraft = { name: string; scopes: string[]; expires: string }
+
+/** Props for ApiKeys. */
+export interface ApiKeysProps {
+  keys: readonly ApiKey[] | State<readonly ApiKey[]>
+  kind?: 'test' | 'live' | undefined
+  /** Now, for "last used" and the 24-hour revoke rule. */
+  now: string
+  scopes?: { value: string; label: string }[]
+  expiries?: { value: string; label: string }[]
+  /** Fresh credentials first (09 §2.1, a 5-minute grant); false stops. */
+  onReauth?: (reason: string) => Promise<boolean>
+  /** Returns the full secret, which leaves this component only through the Copy button. */
+  onCreate: (draft: KeyDraft) => Promise<string>
+  onRevoke: (key: ApiKey) => Promise<void> | void
+}
+
+const SCOPES = [{ value: 'read', label: 'Read projects and deploys' }, { value: 'deploy', label: 'Trigger deploys' }, { value: 'admin', label: 'Manage members (admins only)' }]
+const EXPIRIES = [{ value: '30', label: 'In 30 days' }, { value: '90', label: 'In 90 days' }, { value: 'never', label: 'Never' }]
+
+/**
+ * API keys (09 §4.2): a DataTable of prefixes. Create asks for re-auth, then name, scopes and expiry, then shows the key
+ * once: it can't be dismissed before "I've saved it". Revoke is type-to-confirm when the key was used in the last 24 h.
+ * Live keys sit behind SignGate, which the app wraps around this component.
+ */
+export function ApiKeys({ keys, kind = 'test', now, scopes = SCOPES, expiries = EXPIRIES, onReauth, onCreate, onRevoke }: ApiKeysProps) {
+  const creating = state(false)
+  const { secret, seen } = useReveal(creating)
+  const dialog = guarded(creating, () => !secret.value || seen.value)
+  const armed = latch(creating)
+  const name = state('')
+  const chosen = state<string[]>(['read'])
+  const expires = state('90')
+  const nameError = state('')
+  const scopeError = state('')
+  const busy = state(false)
+  const revoking = state<ApiKey | undefined>(undefined)
+  const typedOpen = state(false)
+  const plainOpen = state(false)
+  let opener: HTMLElement | undefined
+  let form: HTMLElement | undefined
+  const list = derived(() => read(keys))
+  const title = derived(() => (kind === 'live' ? 'live' : 'test'))
+
+  const start = async (e: MouseEvent) => {
+    opener = e.currentTarget as HTMLElement
+    if (onReauth && !(await onReauth('Creating an API key needs a fresh sign-in.'))) return
+    name.value = ''; chosen.value = ['read']; expires.value = '90'; nameError.value = ''; scopeError.value = ''
+    creating.value = true
+  }
+  const make = async () => {
+    if (busy.value) return
+    const n = name.value.trim()
+    nameError.value = !n ? 'Name the key so you can find it later.' : list.value.some(k => k.name.toLowerCase() === n.toLowerCase()) ? 'You already have a key with that name.' : ''
+    scopeError.value = chosen.value.length ? '' : 'Pick at least one scope.'
+    if (nameError.value || scopeError.value) return afterFlush(() => form?.querySelector<HTMLElement>('[aria-invalid="true"]')?.focus())
+    busy.value = true
+    try { secret.value = await onCreate({ name: n, scopes: chosen.value, expires: expires.value }) }
+    catch { toast.show({ title: 'The key wasn’t created', description: 'Try again in a moment.', tone: 'critical', action: { label: 'Retry', onClick: make } }) }
+    finally { busy.value = false }
+    if (secret.value) afterFlush(() => form?.ownerDocument.querySelector<HTMLElement>('dialog[open] input[readonly]')?.focus())
+  }
+  const toggle = (v: string, on: boolean) => { chosen.value = on ? [...chosen.value, v] : chosen.value.filter(x => x !== v); scopeError.value = '' }
+  const revoke = (k: ApiKey) => {
+    revoking.value = k
+    if (usedWithinDay(k.lastUsed, now)) typedOpen.value = true
+    else plainOpen.value = true
+  }
+  const gone = async () => {
+    const k = revoking.value!
+    await onRevoke(k)
+    toast.show({ title: `“${k.name}” revoked`, description: 'Requests with it now get 401.', tone: 'critical' })
+    afterFlush(() => opener?.focus())
+  }
+  const columns: Column<ApiKey>[] = [
+    { id: 'name', header: 'Name', rowHeader: true, card: 'title', cell: k => <span data-scope="row"><b>{k.name}</b>{k.scopes.map(s => <Badge key={s}>{s}</Badge>)}</span> },
+    { id: 'prefix', header: 'Key', cell: k => <span data-scope="api-key"><code data-part="prefix">{k.prefix}…</code></span> },
+    { id: 'created', header: 'Created' },
+    { id: 'lastUsed', header: 'Last used', value: k => (k.lastUsed ? agoText(k.lastUsed, now) : 'Never') },
+    { id: 'revoke', header: 'Actions', value: () => '', cell: k => <Button emphasis="soft" tone="critical" size="sm" aria-label={`Revoke ${k.name}`} onClick={(e: MouseEvent) => { opener ??= e.currentTarget as HTMLElement; revoke(k) }}>Revoke</Button> },
+  ]
+  const tools = derived(() => <Button onClick={start}>{`Create ${title.value} key`}</Button>) // one build: Table reads the prop twice
+  const footer = derived(() => (secret.value
+    ? <Button disabled={!seen.value} onClick={() => (dialog.value = false)}>Done</Button>
+    : <><Button emphasis="frame" data-close="">Cancel</Button><Button loading={busy.value} onClick={make}>Create key</Button></>))
+  return (
+    <div data-scope="stack">
+      <Table caption={`${title.value === 'live' ? 'Live' : 'Test'} API keys`} captionHidden rows={list} columns={columns} picker={false} heading={3} actions={tools.value} empty={{ title: 'No keys yet', text: 'Create one to call the API.' }} />
+      {armed.value && (
+        <Modal open={dialog} alert={!!secret.value} title={secret.value ? 'Copy your new key' : `Create a ${title.value} key`} description={secret.value ? 'You won’t see it again. Store it in your secrets manager now.' : 'Give it a name you’ll recognise in the audit log.'} footer={<>{footer.value}</>}>
+          {secret.value
+            ? <SecretReveal label={name.value} secret={secret.value} done={seen} ack="I’ve saved this key somewhere safe" />
+            : (
+              <form ref={n => (form = n)} data-scope="stack" style="padding-block-start:var(--warp-space-related)" novalidate onSubmit={(e: Event) => { e.preventDefault(); void make() }}>
+                <Input label="Key name" placeholder="e.g. CI deploys" autofocus value={name.value} error={nameError.value} onInput={e => { name.value = e.currentTarget.value; nameError.value = '' }} />
+                <fieldset data-scope="choice">
+                  <legend>Scopes</legend>
+                  {scopes.map(s => <Checkbox key={s.value} checked={chosen.value.includes(s.value)} error={s === scopes[0] && scopeError.value ? scopeError.value : undefined} onChange={(e: Event) => toggle(s.value, (e.currentTarget as HTMLInputElement).checked)}>{s.label}</Checkbox>)}
+                </fieldset>
+                <Select label="Expires" options={expiries} value={expires.value} onChange={(e: Event) => (expires.value = (e.currentTarget as HTMLInputElement).value)} />
+              </form>
+            )}
+        </Modal>
+      )}
+      <TypeToConfirm open={typedOpen} glyph={KeyIcon} title={`Revoke “${revoking.value?.name}”?`} description="This key was used in the last 24 hours. Anything using it stops working right away." confirmText={revoking.value?.name ?? ''} action="Revoke key" onConfirm={gone} />
+      <ConfirmDialog open={plainOpen} glyph={KeyIcon} tone="critical" title={`Revoke “${revoking.value?.name}”?`} description="Anything still using it stops working right away." action="Revoke key" onConfirm={gone} />
+    </div>
+  )
+}

package/src/admin/Audit.tsx

@@ -0,0 +1,93 @@
+import { agoText, announce, plural } from '@weft-js/warp-core'
+import { derived, onCleanup, state, type State } from '@weft-js/core'
+import { Button } from '../Button'
+import { LiveStatus, type LiveState } from '../parts'
+import { Tooltip } from '../Tooltip'
+import { Segmented } from '../Choice'
+import { Select } from '../Select'
+import { Table, type Column } from '../Table'
+import { read } from './atoms'
+import '../styles'
+import '@weft-js/warp-core/styles/flows/tokens.css'
+import '@weft-js/warp-core/styles/flows/base.css'
+import '@weft-js/warp-core/styles/rich/helpers.css'
+import '@weft-js/warp-core/styles/layout/tokens.css'
+import '@weft-js/warp-core/styles/layout/row.css'
+import '@weft-js/warp-core/styles/layout/stack.css'
+
+/** One line of the audit log. */
+export type AuditEvent = { id: string; at: string; actor: string; category: string; verb: string; target: string; href?: string; ip: string; diff?: { field: string; from: string; to: string }[] }
+
+/** Props for AuditLog. */
+export interface AuditLogProps {
+  events: readonly AuditEvent[] | State<readonly AuditEvent[]>
+  now: string
+  categories?: { value: string; label: string }[]
+  /** The realtime pill, when the rows come from a live query. */
+  live?: LiveState | undefined
+  /** Resolve with `{ retryAfter }` (seconds) when rate limited (§5.5). */
+  onExport?: () => Promise<{ retryAfter?: number } | void>
+}
+
+const RANGES = [{ value: 'all', label: 'Any time', hours: Infinity }, { value: '24h', label: 'Last 24 hours', hours: 24 }, { value: '7d', label: 'Last 7 days', hours: 168 }, { value: '30d', label: 'Last 30 days', hours: 720 }]
+
+/**
+ * The audit log (09 §4.5): a read-only DataTable. Time is relative, exact on hover and focus; each event opens its diff.
+ * Filters: actor, action, date range. New rows arrive by key, so a live query never rebuilds the table.
+ */
+const stamp = (at: string) => at.replace('T', ' ').replace(/:\d\dZ$/, ' UTC')
+
+/** The audit log: who did what and when, filtered by category and actor, with an export. */
+export function AuditLog({ events, now, categories = [{ value: 'all', label: 'All' }], live, onExport }: AuditLogProps) {
+  const category = state('all')
+  const actor = state('all')
+  const range = state('all')
+  const wait = state(0)
+  const list = derived(() => read(events))
+  const actors = derived(() => [{ value: 'all', label: 'Everyone' }, ...[...new Set(list.value.map(e => e.actor))].map(a => ({ value: a, label: a }))])
+  const shown = derived(() => {
+    const hours = RANGES.find(r => r.value === range.value)!.hours
+    return list.value.filter(e => (category.value === 'all' || e.category === category.value) && (actor.value === 'all' || e.actor === actor.value) && Date.parse(now) - Date.parse(e.at) <= hours * 36e5)
+  })
+  let tick: ReturnType<typeof setInterval> | undefined
+  let root: HTMLElement | undefined
+  const say = (t: string) => { if (root) announce(root.ownerDocument, t) }
+  onCleanup(() => clearInterval(tick))
+  const refilter = () => queueMicrotask(() => say(`${plural(shown.value.length, 'event')} shown`))
+  const exportIt = async () => {
+    const r = await onExport?.()
+    if (!r?.retryAfter) return
+    wait.value = r.retryAfter
+    say(`Export limit reached. Try again in ${r.retryAfter} seconds.`)
+    tick = setInterval(() => {
+      wait.value -= 1
+      if (wait.value > 0) return
+      clearInterval(tick)
+      say('You can export again.')
+    }, 1000)
+  }
+  const columns: Column<AuditEvent>[] = [
+    { id: 'at', header: 'When', sort: r => r.at, cell: e => { const at = stamp(e.at); return <Tooltip content={at}><time datetime={e.at} tabindex="0">{agoText(e.at, now)}</time></Tooltip> } },
+    { id: 'actor', header: 'Who', rowHeader: true, card: 'title' },
+    { id: 'what', header: 'What', value: e => `${e.verb} ${e.target}`, cell: e => <>{e.verb} {e.href ? <a href={e.href}>{e.target}</a> : e.target}</> },
+    { id: 'ip', header: 'IP', priority: 2, cell: e => <code>{e.ip}</code> },
+  ]
+  const diff = (e: AuditEvent) => (e.diff?.length
+    ? <dl data-scope="desc">{e.diff.map(d => <div key={d.field}><dt>{d.field}</dt><dd>{d.from} → {d.to}</dd></div>)}</dl>
+    : <span class="muted">No field changes were recorded.</span>)
+  const hasLive = derived(() => live !== undefined)
+  return (
+    <div ref={n => (root = n)} data-scope="stack">
+      <div data-scope="row" data-justify="between">
+        <Segmented label="Filter events" size="sm" value={category.value} options={categories} onChange={v => { category.value = v; refilter() }} />
+        {hasLive.value && <LiveStatus state={live!} label="Audit log" />}
+      </div>
+      <div data-scope="row">
+        <div data-grow=""><Select label="Actor" size="sm" options={actors.value} value={actor.value} onChange={(e: Event) => { actor.value = (e.currentTarget as HTMLInputElement).value; refilter() }} /></div>
+        <div data-grow=""><Select label="Date range" size="sm" options={RANGES} value={range.value} onChange={(e: Event) => { range.value = (e.currentTarget as HTMLInputElement).value; refilter() }} /></div>
+        {onExport && <Button emphasis="frame" aria-disabled={wait.value > 0 ? 'true' : undefined} onClick={exportIt}>{wait.value > 0 ? `Try again in ${wait.value}s` : 'Export CSV'}</Button>}
+      </div>
+      <Table caption="Recent events" captionHidden rows={shown} columns={columns} picker={false} heading={3} details="sheet" expand={diff} empty={{ title: 'Nothing matches', text: 'Try a wider filter.' }} />
+    </div>
+  )
+}