@better-forge/ui 0.0.0-stage → 0.1.0

package/src/components/VaultTypePicker.tsx

@@ -0,0 +1,131 @@
+import { useEffect, useId, useRef, useState } from 'react'
+import { uiConfig } from '../config'
+
+export type VaultTypeValue = 'local' | 'hashicorp'
+
+/** Only a local vault stores values; every external vault holds references to secrets kept in the provider. */
+export const isReferenceVault = (type: VaultTypeValue): boolean => type !== 'local'
+
+/** Icon per vault type, shared by the picker and the vault list so they always match. */
+export const VAULT_TYPE_ICONS: Record<VaultTypeValue, string> = { local: 'storage', hashicorp: 'vpn_key' }
+
+interface VaultTypeOption {
+  value: VaultTypeValue | null
+  label: string
+  hint: string
+  icon: string
+}
+
+/** Vault types in picker order; entries with a null value are announced but cannot be selected yet. */
+const vaultTypeOptions = (): VaultTypeOption[] => [
+  { value: 'local', label: 'Local', hint: `Encrypted in the ${uiConfig().texts.appName} database`, icon: VAULT_TYPE_ICONS.local },
+  { value: 'hashicorp', label: 'HashiCorp Vault', hint: 'Read secrets from your own HashiCorp Vault', icon: VAULT_TYPE_ICONS.hashicorp },
+  { value: null, label: 'Azure Key Vault', hint: 'Coming soon', icon: 'cloud' },
+  { value: null, label: 'GCP Secret Manager', hint: 'Coming soon', icon: 'cloud' },
+  { value: null, label: 'AWS Secrets Manager', hint: 'Coming soon', icon: 'cloud' },
+]
+
+interface Props {
+  value: VaultTypeValue
+  onChange: (type: VaultTypeValue) => void
+}
+
+function TypeIcon({ icon }: { icon: string }) {
+  return (
+    <span className="flex-none w-8 h-8 rounded-lg grid place-items-center" style={{ background: 'var(--admin-icon-container)', color: 'var(--admin-icon-color)' }}>
+      <span className="material-symbols-outlined" aria-hidden="true" style={{ fontSize: 20 }}>{icon}</span>
+    </span>
+  )
+}
+
+/** Vault type list in the same dropdown style as the other type pickers. */
+export function VaultTypePicker({ value, onChange }: Props) {
+  const [open, setOpen] = useState(false)
+  const rootRef = useRef<HTMLDivElement>(null)
+  const buttonRef = useRef<HTMLButtonElement>(null)
+  const labelId = useId()
+  const buttonId = useId()
+  const selected = vaultTypeOptions().find((t) => t.value === value)!
+
+  useEffect(() => {
+    if (!open) return
+    function onPointerDown(e: MouseEvent) {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false)
+    }
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key !== 'Escape') return
+      e.stopPropagation()
+      setOpen(false)
+      buttonRef.current?.focus()
+    }
+    document.addEventListener('mousedown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown, true)
+    return () => {
+      document.removeEventListener('mousedown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown, true)
+    }
+  }, [open])
+
+  function pick(option: VaultTypeOption) {
+    if (!option.value) return
+    setOpen(false)
+    buttonRef.current?.focus()
+    if (option.value !== value) onChange(option.value)
+  }
+
+  return (
+    <div ref={rootRef} className="relative">
+      <span id={labelId} className="block font-mono text-xs uppercase tracking-wider mb-2" style={{ color: 'var(--m3-secondary)' }}>Type</span>
+      <button
+        ref={buttonRef}
+        id={buttonId}
+        type="button"
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        aria-labelledby={`${labelId} ${buttonId}`}
+        onClick={() => setOpen((o) => !o)}
+        className="w-full flex items-center gap-3 text-left rounded-xl px-3 py-2 focus-ring"
+        style={{ background: 'var(--m3-surface-container-lowest)', border: '1px solid var(--m3-outline-variant)', color: 'var(--m3-on-surface)' }}
+      >
+        <TypeIcon icon={selected.icon} />
+        <span className="min-w-0 flex-1">
+          <span className="block text-sm font-semibold">{selected.label}</span>
+          <span className="block text-xs truncate" style={{ color: 'var(--m3-secondary)' }}>{selected.hint}</span>
+        </span>
+        <span className="material-symbols-outlined" aria-hidden="true" style={{ color: 'var(--m3-secondary)' }}>unfold_more</span>
+      </button>
+
+      {open && (
+        <div
+          className="absolute z-10 left-0 right-0 mt-1.5 rounded-xl overflow-hidden shadow-xl"
+          style={{ background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' }}
+        >
+          <div role="listbox" aria-labelledby={labelId} className="max-h-72 overflow-auto p-1.5">
+            {vaultTypeOptions().map((t) => {
+              const disabled = t.value === null
+              const isSelected = t.value === value
+              return (
+                <button
+                  key={t.label}
+                  type="button"
+                  role="option"
+                  aria-selected={isSelected}
+                  aria-disabled={disabled}
+                  onClick={() => pick(t)}
+                  className={`w-full flex items-center gap-3 text-left rounded-lg px-2 py-1.5 focus-ring ${disabled ? 'opacity-40 cursor-not-allowed' : 'hover:bg-[var(--m3-surface-container)]'} ${isSelected ? 'selection-active' : ''}`}
+                  style={{ border: '1px solid transparent' }}
+                >
+                  <TypeIcon icon={t.icon} />
+                  <span className="min-w-0 flex-1">
+                    <span className="block text-sm font-semibold">{t.label}</span>
+                    <span className="block text-xs truncate opacity-75">{t.hint}</span>
+                  </span>
+                </button>
+              )
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/WhatsNew.tsx

@@ -0,0 +1,84 @@
+import { safeLocalStorage } from '@better-forge/contracts'
+import { storageKey } from '../config'
+import { parseChangelog, releasesBetween, summarizeRelease, type ReleaseItem, type ReleaseNotes } from '../lib/changelog'
+import { ModalFooter, ModalHeader, ModalShell } from './ModalShell'
+
+const seenKey = (userId: number) => storageKey(`whatsnew-seen-${userId}`)
+
+/** Remembers that this user has seen the notes up to `version`. */
+export function markWhatsNewSeen(userId: number, version: string): void {
+  safeLocalStorage.set(seenKey(userId), version) // blocked storage: the notes may show again next visit
+}
+
+/**
+ * Releases this user has not seen yet. A user with no record (new, or from before this existed) is only
+ * marked as up to date, so the first run shows nothing.
+ */
+export function pendingWhatsNew(userId: number, changelog: string, current: string): ReleaseNotes[] {
+  try {
+    const seen = safeLocalStorage.get(seenKey(userId))
+    if (seen === null) {
+      markWhatsNewSeen(userId, current)
+      return []
+    }
+    return releasesBetween(parseChangelog(changelog), seen, current).filter((release) => release.groups.length > 0)
+  } catch {
+    return []
+  }
+}
+
+const plural = (count: number, one: string, many: string) => `${count} ${count === 1 ? one : many}`
+
+/** Opening one section closes the others (shared `name`), so the dialog keeps its size. */
+function Section({ title, items, defaultOpen }: { title: string; items: ReleaseItem[]; defaultOpen?: boolean }) {
+  return (
+    <details name="whats-new-sections" open={defaultOpen} className="group rounded-xl" style={{ border: '1px solid var(--m3-outline-variant)' }}>
+      <summary className="flex items-center justify-between gap-2 px-4 py-3 cursor-pointer list-none [&::-webkit-details-marker]:hidden font-headline font-semibold text-sm" style={{ color: 'var(--m3-on-surface)' }}>
+        <span>{title} <span className="font-mono text-xs" style={{ color: 'var(--m3-outline)' }}>({items.length})</span></span>
+        <span aria-hidden="true" className="material-symbols-outlined transition-transform group-open:rotate-180" style={{ fontSize: '20px' }}>expand_more</span>
+      </summary>
+      <ul className="space-y-2 px-4 pb-3 overflow-y-auto" style={{ maxHeight: '40vh' }}>
+        {items.map((item) => (
+          <li key={item.title + item.summary} className="font-sans text-sm" style={{ color: 'var(--m3-on-surface)' }}>
+            {item.title && <span className="font-bold">{item.title}. </span>}{item.summary}
+          </li>
+        ))}
+      </ul>
+    </details>
+  )
+}
+
+/**
+ * The newest release as collapsible sections (the first one with entries open, empty ones left out), earlier ones in one line each.
+ * Only one section is open at a time, so the dialog stays small however many entries a release has.
+ */
+export function WhatsNew({ releases, onClose, docsUrl }: { releases: ReleaseNotes[]; onClose: () => void; docsUrl: string }) {
+  const [latest, ...earlier] = releases.map(summarizeRelease)
+  const sections = [
+    { title: 'New', items: latest!.added },
+    { title: 'Changed', items: latest!.changed },
+    { title: 'Fixes', items: latest!.fixed },
+  ].filter((section) => section.items.length > 0)
+  return (
+    <ModalShell onClose={onClose} label="What's new">
+      <div className="w-full max-w-lg rounded-2xl" style={{ background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' }}>
+        <ModalHeader icon="celebration" title={`What's new in ${latest!.version}`} onClose={onClose} />
+        <div className="p-6 space-y-3">
+          {sections.map((section, index) => <Section key={section.title} title={section.title} items={section.items} defaultOpen={index === 0} />)}
+          {earlier.length > 0 && (
+            <p className="font-sans text-sm pt-1" style={{ color: 'var(--m3-secondary)' }}>
+              Earlier: {earlier.map((release) => `${release.version} (${[
+                release.added.length > 0 && `${release.added.length} new`,
+                release.changed.length > 0 && plural(release.changed.length, 'change', 'changes'),
+                release.fixed.length > 0 && plural(release.fixed.length, 'fix', 'fixes'),
+              ].filter(Boolean).join(', ')})`).join(' · ')}
+            </p>
+          )}
+        </div>
+        <ModalFooter start={<a href={`${docsUrl}/changelog/`} target="_blank" rel="noopener" className="btn btn-secondary">Full changelog</a>}>
+          <button type="button" onClick={onClose} className="btn btn-primary">Got it</button>
+        </ModalFooter>
+      </div>
+    </ModalShell>
+  )
+}

package/src/components/formParts.tsx

@@ -0,0 +1,59 @@
+import type { ReactNode } from 'react'
+
+// Building blocks shared by the forms of the interface and the sections extracted from them.
+
+export interface VaultSummary  { id: number; name: string }
+export interface SecretSummary { id: number; name: string; type: 'userpass' | 'value' | 'json' }
+
+/** What every vault-aware credential picker needs to list vaults and lazily load their secrets. */
+export interface VaultPickerProps {
+  vaults: { id: number; name: string }[]
+  secretsByVault: Record<number, { id: number; name: string; type: string }[]>
+  onLoadSecrets: (vaultId: number) => Promise<void>
+}
+
+// Fields that can be sourced from a json vault secret, per context
+export const JSON_MAPPING_FIELDS: Record<'basic' | 'oauth2' | 'cas' | 'database', { key: string; label: string }[]> = {
+  basic:     [{ key: 'username', label: 'Username' }, { key: 'password', label: 'Password' }],
+  oauth2:    [{ key: 'clientId', label: 'Client ID' }, { key: 'clientSecret', label: 'Client Secret' }],
+  cas:       [{ key: 'username', label: 'Username' }, { key: 'password', label: 'Password' }],
+  database: [{ key: 'username', label: 'Username' }, { key: 'password', label: 'Password' }],
+}
+
+/** The shared caps-style form field: its label is programmatically tied to the control it wraps. */
+export { Field } from './ui'
+
+export function SectionDivider({ label }: { label: string }) {
+  return (
+    <div className="flex items-center gap-3 pt-1">
+      <div style={{ flex: 1, borderTop: '1px solid var(--m3-outline-variant)' }} />
+      <span className="font-mono text-xs uppercase tracking-wider" style={{ color: 'var(--m3-secondary)' }}>{label}</span>
+      <div style={{ flex: 1, borderTop: '1px solid var(--m3-outline-variant)' }} />
+    </div>
+  )
+}
+
+/** Tinted callout: `info` uses the accent blue, `warning` the degraded amber (text colour, not the bar colour). */
+export function Note({ tone, children }: { tone: 'info' | 'warning'; children: ReactNode }) {
+  const color = tone === 'info' ? 'var(--m3-on-primary-container)' : 'var(--m3-degraded)'
+  const tint = tone === 'info' ? color : 'var(--m3-degraded-bar)'
+  return (
+    <div
+      className="flex items-start gap-2 rounded-lg px-3 py-2"
+      style={{ background: `color-mix(in srgb, ${tint} 8%, transparent)`, border: `1px solid color-mix(in srgb, ${tint} 20%, transparent)` }}
+    >
+      {tone === 'info'
+        ? <span className="material-symbols-outlined" aria-hidden="true" style={{ fontSize: '16px', color, lineHeight: '20px' }}>info</span>
+        : <span aria-hidden="true" style={{ color, lineHeight: '20px' }}>⚠</span>}
+      <p className="text-xs" style={{ color: 'var(--m3-on-surface-variant)' }}>{children}</p>
+    </div>
+  )
+}
+
+/** Adds or removes one id from a selection set without mutating it. */
+export function toggleInSet(set: Set<number>, id: number, on: boolean): Set<number> {
+  const next = new Set(set)
+  if (on) next.add(id)
+  else next.delete(id)
+  return next
+}

package/src/components/ui/Alert.tsx

@@ -0,0 +1,45 @@
+import clsx from 'clsx'
+import type { CSSProperties, ReactNode } from 'react'
+
+export type AlertTone = 'error' | 'success' | 'info' | 'warning'
+
+const TONES: Record<AlertTone, { icon: string; style: CSSProperties }> = {
+  error:   { icon: 'error',        style: { background: 'var(--m3-down-bg)', color: 'var(--m3-down)', borderColor: 'color-mix(in srgb, var(--m3-down) 30%, transparent)' } },
+  success: { icon: 'check_circle', style: { background: 'var(--m3-up-bg)', color: 'var(--m3-up)', borderColor: 'color-mix(in srgb, var(--m3-up) 30%, transparent)' } },
+  warning: { icon: 'warning',      style: { background: 'var(--m3-degraded-bg)', color: 'var(--m3-degraded)', borderColor: 'color-mix(in srgb, var(--m3-degraded) 30%, transparent)' } },
+  info:    { icon: 'info',         style: { background: 'var(--m3-surface-container-high)', color: 'var(--m3-on-surface)', borderColor: 'var(--m3-outline-variant)' } },
+}
+
+interface AlertProps {
+  tone: AlertTone
+  children: ReactNode
+  /** Optional bold first line. */
+  title?: ReactNode | undefined
+  /** Renders a × button (aria-label "Dismiss") that calls this. */
+  onDismiss?: (() => void) | undefined
+  className?: string | undefined
+}
+
+/** Inline, token-coloured message box. Errors are announced assertively (role="alert"); other tones politely. */
+export function Alert({ tone, children, title, onDismiss, className }: AlertProps) {
+  const { icon, style } = TONES[tone]
+  return (
+    <div
+      role={tone === 'error' ? 'alert' : 'status'}
+      data-tone={tone}
+      className={clsx('flex items-start gap-3 rounded-xl border px-4 py-3 text-sm', className)}
+      style={style}
+    >
+      <span className="material-symbols-outlined flex-shrink-0 mt-px" aria-hidden="true" style={{ fontSize: '18px' }}>{icon}</span>
+      <div className="flex-1 min-w-0 break-words">
+        {title && <p className="font-semibold">{title}</p>}
+        <div className={title ? 'mt-0.5' : undefined}>{children}</div>
+      </div>
+      {onDismiss && (
+        <button type="button" onClick={onDismiss} aria-label="Dismiss" className="btn-icon -my-1 -mr-2" style={{ color: 'inherit' }}>
+          <span className="material-symbols-outlined" aria-hidden="true" style={{ fontSize: '18px' }}>close</span>
+        </button>
+      )}
+    </div>
+  )
+}

package/src/components/ui/DataTable.tsx

@@ -0,0 +1,225 @@
+import {
+  createContext, useCallback, useContext, useMemo, useRef, useState,
+  type KeyboardEvent, type PointerEvent, type ReactNode, type TableHTMLAttributes, type ThHTMLAttributes,
+} from 'react'
+
+export const MIN_COLUMN_WIDTH = 60
+export const MAX_COLUMN_WIDTH = 600
+const KEY_STEP = 16
+
+interface ResizeHandleProps {
+  /** Column name, used for the accessible description. */
+  label: string
+  /** Current width in px; shown to assistive technology. */
+  width: number | undefined
+  /** Reads the width the column has right now; called when a drag starts and for key presses. */
+  measure: () => number
+  onResize: (width: number) => void
+  /** Restores the default width. */
+  onReset: () => void
+}
+
+/** Grip on the right edge of a column header: drag, arrow keys, double-click or Home to reset. Place it in a `position: relative` header cell. */
+export function ResizeHandle({ label, width, measure, onResize, onReset }: ResizeHandleProps) {
+  const drag = useRef<{ startX: number; startWidth: number } | null>(null)
+  const clamp = (w: number) => Math.min(MAX_COLUMN_WIDTH, Math.max(MIN_COLUMN_WIDTH, Math.round(w)))
+
+  function onPointerDown(e: PointerEvent<HTMLSpanElement>) {
+    e.preventDefault()
+    e.currentTarget.setPointerCapture(e.pointerId)
+    drag.current = { startX: e.clientX, startWidth: measure() }
+  }
+
+  function onPointerMove(e: PointerEvent<HTMLSpanElement>) {
+    if (drag.current) onResize(clamp(drag.current.startWidth + e.clientX - drag.current.startX))
+  }
+
+  function onKeyDown(e: KeyboardEvent<HTMLSpanElement>) {
+    if (e.key === 'ArrowLeft') onResize(clamp(measure() - KEY_STEP))
+    else if (e.key === 'ArrowRight') onResize(clamp(measure() + KEY_STEP))
+    else if (e.key === 'Home') onReset()
+    else return
+    e.preventDefault()
+  }
+
+  return (
+    <span
+      role="separator"
+      aria-orientation="vertical"
+      aria-description={`Resize ${label} column`}
+      aria-valuenow={width}
+      aria-valuemin={MIN_COLUMN_WIDTH}
+      aria-valuemax={MAX_COLUMN_WIDTH}
+      tabIndex={0}
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={() => { drag.current = null }}
+      onPointerCancel={() => { drag.current = null }}
+      onKeyDown={onKeyDown}
+      onDoubleClick={onReset}
+      className="group focus-ring absolute top-0 right-0 z-10 flex h-full w-3 cursor-col-resize touch-none select-none justify-center"
+    >
+      <span
+        aria-hidden="true"
+        className="block h-full w-px opacity-60 transition-all group-hover:w-0.5 group-hover:opacity-100 group-focus-visible:w-0.5 group-focus-visible:opacity-100 group-active:w-0.5 group-active:opacity-100"
+        style={{ background: 'var(--m3-outline-variant)' }}
+      />
+    </span>
+  )
+}
+
+export type SortDirection = 'asc' | 'desc'
+export type SortValue = string | number | boolean | null | undefined
+
+export interface TableSort {
+  key: string | null
+  dir: SortDirection
+  /** Sorts by the column; repeated calls on the same column go ascending, descending, then back to the original order. */
+  toggle: (key: string) => void
+}
+
+const isEmpty = (v: SortValue) => v == null || v === ''
+
+function compareValues(a: SortValue, b: SortValue): number {
+  if (typeof a === 'number' && typeof b === 'number') return a - b
+  if (typeof a === 'boolean' && typeof b === 'boolean') return Number(a) - Number(b)
+  return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: 'base' })
+}
+
+/** Sorts `rows` by the column picked in a `DataTable` header. `accessors` maps a column key to the value to compare; empty values always go last. */
+export function useTableSort<T>(
+  rows: readonly T[],
+  accessors: Readonly<Record<string, (row: T) => SortValue>>,
+  initial?: { key: string; dir?: SortDirection },
+): { rows: T[]; sort: TableSort } {
+  const [key, setKey] = useState<string | null>(initial?.key ?? null)
+  const [dir, setDir] = useState<SortDirection>(initial?.dir ?? 'asc')
+
+  const toggle = useCallback((next: string) => {
+    if (key !== next) { setKey(next); setDir('asc') }
+    else if (dir === 'asc') setDir('desc')
+    else { setKey(null); setDir('asc') }
+  }, [key, dir])
+
+  // The accessors are declared inline by callers; the rows, column and direction are what change the order.
+  const accessorsRef = useRef(accessors)
+  accessorsRef.current = accessors
+
+  const sorted = useMemo(() => {
+    const get = key === null ? undefined : accessorsRef.current[key]
+    if (!get) return [...rows]
+    const sign = dir === 'asc' ? 1 : -1
+    return [...rows].sort((x, y) => {
+      const a = get(x), b = get(y)
+      if (isEmpty(a) || isEmpty(b)) return Number(isEmpty(a)) - Number(isEmpty(b))
+      return sign * compareValues(a, b)
+    })
+  }, [rows, key, dir])
+
+  return { rows: sorted, sort: useMemo(() => ({ key, dir, toggle }), [key, dir, toggle]) }
+}
+
+interface TableContext {
+  sort: TableSort | undefined
+  widths: number[] | null
+  resize: (row: HTMLTableRowElement, index: number, width: number) => void
+  reset: () => void
+}
+
+const DataTableContext = createContext<TableContext | null>(null)
+
+interface DataTableProps extends TableHTMLAttributes<HTMLTableElement> {
+  /** From `useTableSort`; without it the headers are not sortable. */
+  sort?: TableSort
+  children: ReactNode
+}
+
+/**
+ * `<table>` whose `DataTh` headers can be sorted and resized. The first resize fixes every column at its
+ * current width; a drag then moves the boundary to the next column, so the other columns stay where they are.
+ */
+export function DataTable({ sort, children, style, className, ...rest }: DataTableProps) {
+  const [widths, setWidths] = useState<number[] | null>(null)
+
+  const resize = useCallback((row: HTMLTableRowElement, index: number, width: number) => {
+    setWidths((current) => {
+      const next = current ? [...current] : Array.from(row.cells, (cell) => cell.offsetWidth)
+      const own = next[index]
+      if (own === undefined) return current
+      const neighbour = next[index + 1]
+      let delta = width - own
+      if (neighbour !== undefined) delta = Math.min(delta, neighbour - MIN_COLUMN_WIDTH)
+      next[index] = own + delta
+      if (neighbour !== undefined) next[index + 1] = neighbour - delta
+      return next
+    })
+  }, [])
+
+  const context = useMemo<TableContext>(
+    () => ({ sort, widths, resize, reset: () => setWidths(null) }),
+    [sort, widths, resize],
+  )
+
+  return (
+    <DataTableContext.Provider value={context}>
+      <table
+        {...rest}
+        className={`${className ?? ''} ${widths ? '[&_td]:break-words [&_th]:overflow-hidden' : ''}`}
+        style={widths ? { ...style, tableLayout: 'fixed', width: widths.reduce((a, b) => a + b, 0), minWidth: 0 } : style}
+      >
+        {widths && <colgroup>{widths.map((w, i) => <col key={i} style={{ width: w }} />)}</colgroup>}
+        {children}
+      </table>
+    </DataTableContext.Provider>
+  )
+}
+
+interface DataThProps extends ThHTMLAttributes<HTMLTableCellElement> {
+  /** Column key from `useTableSort`'s accessors; makes the header a sort button. */
+  sortKey?: string
+  /** Set false for columns without a title, such as the row actions. */
+  resizable?: boolean
+}
+
+/** `<th>` for a `DataTable`: sortable with `sortKey`, resizable unless `resizable={false}`. Give it the classes and colours you would give a `<th>`. */
+export function DataTh({ sortKey, resizable = true, children, className, style, ...rest }: DataThProps) {
+  const table = useContext(DataTableContext)
+  const ref = useRef<HTMLTableCellElement>(null)
+  const sorted = sortKey !== undefined && table?.sort?.key === sortKey
+  const dir = table?.sort?.dir
+  const label = typeof children === 'string' ? children : sortKey ?? 'this'
+
+  return (
+    <th
+      ref={ref}
+      {...rest}
+      aria-sort={sorted ? (dir === 'asc' ? 'ascending' : 'descending') : rest['aria-sort']}
+      className={`${className ?? ''} ${resizable && table ? 'relative' : ''}`}
+      style={sorted ? { ...style, color: 'var(--m3-primary)' } : style}
+    >
+      {sortKey !== undefined && table?.sort ? (
+        <button
+          type="button"
+          onClick={() => table.sort?.toggle(sortKey)}
+          className="inline-flex items-center gap-1 uppercase tracking-wider rounded focus-ring"
+          style={{ color: 'inherit', userSelect: 'none' }}
+        >
+          {children}
+          {sorted && <span aria-hidden="true" style={{ fontSize: '10px' }}>{dir === 'asc' ? '↑' : '↓'}</span>}
+        </button>
+      ) : children}
+      {resizable && table && (
+        <ResizeHandle
+          label={label}
+          width={table.widths?.[ref.current?.cellIndex ?? -1]}
+          measure={() => ref.current?.offsetWidth ?? MIN_COLUMN_WIDTH}
+          onResize={(w) => {
+            const cell = ref.current
+            if (cell?.parentElement instanceof HTMLTableRowElement) table.resize(cell.parentElement, cell.cellIndex, w)
+          }}
+          onReset={table.reset}
+        />
+      )}
+    </th>
+  )
+}

package/src/components/ui/Field.tsx

@@ -0,0 +1,63 @@
+import clsx from 'clsx'
+import { cloneElement, isValidElement, useId, type ReactElement, type ReactNode } from 'react'
+
+/** Props Field hands to its control so the label, hint and error are programmatically associated. */
+export interface FieldControlProps {
+  id: string
+  'aria-describedby'?: string | undefined
+  'aria-invalid'?: true | undefined
+  'aria-required'?: true | undefined
+}
+
+interface FieldProps {
+  label: ReactNode
+  hint?: ReactNode | undefined
+  error?: ReactNode | undefined
+  required?: boolean | undefined
+  /** Use a specific id for the control (otherwise one is generated, or the child's own `id` is kept). */
+  id?: string | undefined
+  /** `caps`: small mono uppercase label (form default); `plain`: small sentence-case label. */
+  variant?: 'caps' | 'plain' | undefined
+  className?: string | undefined
+  /**
+   * Either a single control element (input/select/textarea/custom component that forwards `id` and aria-*),
+   * which receives the props via cloneElement, or a render function receiving them to spread where needed.
+   */
+  children: ReactElement<Partial<FieldControlProps>> | ((control: FieldControlProps) => ReactNode)
+}
+
+const LABEL_CLASS = {
+  caps: 'block font-mono text-xs uppercase tracking-wider mb-2',
+  plain: 'block text-xs mb-1.5',
+}
+
+export function Field({ label, hint, error, required = false, id, variant = 'caps', className, children }: FieldProps) {
+  const generatedId = useId()
+  const childId = typeof children !== 'function' && isValidElement(children) ? children.props.id : undefined
+  const controlId = id ?? childId ?? generatedId
+  const hintId = hint ? `${controlId}-hint` : undefined
+  const errorId = error ? `${controlId}-error` : undefined
+  const existingDescribedBy = typeof children !== 'function' && isValidElement(children) ? children.props['aria-describedby'] : undefined
+  const describedBy = [existingDescribedBy, hintId, errorId].filter(Boolean).join(' ') || undefined
+
+  const controlProps: FieldControlProps = {
+    id: controlId,
+    'aria-describedby': describedBy,
+    ...(error ? { 'aria-invalid': true as const } : {}),
+    ...(required ? { 'aria-required': true as const } : {}),
+  }
+
+  const control = typeof children === 'function' ? children(controlProps) : cloneElement(children, controlProps)
+
+  return (
+    <div className={className}>
+      <label htmlFor={controlId} className={LABEL_CLASS[variant]} style={{ color: 'var(--m3-secondary)' }}>
+        {label}
+        {required && <span aria-hidden="true" style={{ color: 'var(--m3-down)' }}> *</span>}
+      </label>
+      {control}
+      {hint && <p id={hintId} className="text-xs mt-1.5" style={{ color: 'var(--m3-secondary)' }}>{hint}</p>}
+      {error && <p id={errorId} className={clsx('text-xs', hint ? 'mt-1' : 'mt-1.5')} style={{ color: 'var(--m3-down)' }}>{error}</p>}
+    </div>
+  )
+}

package/src/components/ui/PageHeader.tsx

@@ -0,0 +1,36 @@
+import clsx from 'clsx'
+import type { ReactNode } from 'react'
+
+interface PageContainerProps {
+  children: ReactNode
+  className?: string | undefined
+}
+
+/** Standard page padding and vertical rhythm with the entrance animation every admin page uses. */
+export function PageContainer({ children, className }: PageContainerProps) {
+  return <div className={clsx('p-4 md:p-8 space-y-6 fade-up', className)}>{children}</div>
+}
+
+interface PageHeaderProps {
+  title: ReactNode
+  subtitle?: ReactNode | undefined
+  /** Right-aligned controls (buttons, filters); they wrap under the title on narrow screens. */
+  actions?: ReactNode | undefined
+  /** Extra content rendered under the title row, e.g. tabs or a filter bar. */
+  children?: ReactNode | undefined
+}
+
+export function PageHeader({ title, subtitle, actions, children }: PageHeaderProps) {
+  return (
+    <header className="space-y-4">
+      <div className="flex flex-wrap items-start justify-between gap-x-4 gap-y-3">
+        <div className="min-w-0">
+          <h1 className="font-headline font-bold text-2xl" style={{ color: 'var(--m3-on-surface)' }}>{title}</h1>
+          {subtitle && <p className="text-sm mt-1" style={{ color: 'var(--m3-secondary)' }}>{subtitle}</p>}
+        </div>
+        {actions && <div className="flex flex-wrap items-center gap-2">{actions}</div>}
+      </div>
+      {children}
+    </header>
+  )
+}