@baseworks/ui 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * @baseworks/ui — the design system every baseworks surface is built from.
+ *
+ * One palette, warm paper and ultramarine, in a light and a dark form. The
+ * operating system chooses until the viewer does, with `ThemeToggle`. There is
+ * no brand switcher: a second palette is a second design to keep correct.
+ *
+ * Three layers, and they stay in that order:
+ *
+ *   tokens.css      colour, type, spacing. The only place a value is written.
+ *   primitives.css  buttons, cards, tables, forms, dialogs.
+ *   frame.css       the rail, the sub panel, the top bar, the gate.
+ *
+ * The components here are thin: they put the right class on the right element
+ * and hold the behaviour that would otherwise be retyped (outside-click on a
+ * menu, focus placement in a confirm dialog, the highlight in the palette).
+ * Anything that knows what the product *is* belongs in the product.
+ *
+ * Import the stylesheet once, in the root layout:
+ *
+ *   import '@baseworks/ui/styles.css'
+ */
+
+export { Button, IconButton } from './button'
+export type { ButtonProps, ButtonTone } from './button'
+
+export { PageHead, Card, CardBody, CardGrid, Stats, Stat, KeyValue } from './card'
+
+export { Table, Pill, CellName, CellSub } from './table'
+export type { PillTone } from './table'
+
+export { Field, FormRow, FormError, Switch } from './form'
+
+export { Attention, CodeBox, Toast, Chips } from './feedback'
+export type { AttentionTone } from './feedback'
+
+export { ConfirmDialog } from './dialog'
+export type { ConfirmRequest } from './dialog'
+
+export { Popover, MenuItem, MenuHead, MenuSeparator } from './menu'
+
+export { CommandPalette } from './command-palette'
+export type { PaletteItem } from './command-palette'
+
+export { SlideOver } from './slide-over'
+export { Gate } from './gate'
+
+export { Frame, RailTip, useFrame } from './frame'
+export type { FrameProps, FrameCtx } from './frame'
+export { activeModule } from './nav'
+export type { Module, SubItem } from './nav'
+export { AssistantPanel } from './assistant'
+export type { AssistantPanelProps } from './assistant'
+export { navigationCommands } from './commands'
+export { useResource } from './use-resource'
+export type { Resource, ResourceOptions } from './use-resource'
+export { age, until, untilEpoch, money, amount } from './format'
+
+export { applyTheme, currentTheme, resolvedTheme, themeInitScript } from './theme'
+export type { ThemeMode } from './theme'
+export { ThemeToggle } from './theme-toggle'

package/src/menu.tsx

@@ -0,0 +1,62 @@
+'use client'
+
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+
+/**
+ * A menu anchored to the button that opens it.
+ *
+ * It closes on a click anywhere outside itself, which every dropdown in the
+ * frame needs and each one used to implement again. `align="rail"` is the
+ * variant that opens to the right of the icon rail instead of below the button.
+ */
+export function Popover({ trigger, children, align = 'below', menuClassName, menuStyle, label }: {
+  /** Rendered with the open state so the trigger can show it (a caret, a pressed look). */
+  trigger: (props: { open: boolean; toggle: () => void }) => ReactNode
+  children: ReactNode | ((close: () => void) => ReactNode)
+  align?: 'below' | 'rail'
+  menuClassName?: string
+  menuStyle?: React.CSSProperties
+  label?: string
+}) {
+  const [open, setOpen] = useState(false)
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (!open) return
+    const close = (e: MouseEvent) => { if (!rootRef.current?.contains(e.target as Node)) setOpen(false) }
+    const esc = (e: KeyboardEvent) => { if (e.key === 'Escape') setOpen(false) }
+    document.addEventListener('mousedown', close)
+    document.addEventListener('keydown', esc)
+    return () => { document.removeEventListener('mousedown', close); document.removeEventListener('keydown', esc) }
+  }, [open])
+
+  const cls = ['brand-menu', align === 'rail' && 'org-menu rail', menuClassName].filter(Boolean).join(' ')
+  return (
+    <div className="brand-pop" ref={rootRef}>
+      {trigger({ open, toggle: () => setOpen((v) => !v) })}
+      {open && (
+        <div className={cls} style={menuStyle} role="menu" aria-label={label}>
+          {typeof children === 'function' ? children(() => setOpen(false)) : children}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** One row in a Popover. `selected` marks the current choice with a tick. */
+export function MenuItem({ selected, onClick, children }:
+  { selected?: boolean; onClick?: () => void; children: ReactNode }) {
+  return (
+    <button className={'brand-opt' + (selected ? ' sel' : '')} onClick={onClick} role="menuitem">
+      {children}{selected && <span className="check">✓</span>}
+    </button>
+  )
+}
+
+export function MenuHead({ children }: { children: ReactNode }) {
+  return <div className="org-menu-head">{children}</div>
+}
+
+export function MenuSeparator() {
+  return <div className="org-menu-sep" role="separator" />
+}

package/src/nav.ts

@@ -0,0 +1,47 @@
+/**
+ * The shape of a module list — not any particular list.
+ *
+ * A surface supplies its own modules: the console's are the realm's services,
+ * a product's are its own screens. What is shared is the shape and the rule
+ * for which one is active, because the frame renders both the same way.
+ */
+
+export type SubItem = {
+  label: string
+  /** A route to go to. */
+  href?: string
+  /** A card on the module's own page to scroll to. */
+  hash?: string
+  /** Which count to show beside the label, looked up in `counts`. */
+  countKey?: string
+  /** Designed, not built. The frame says so rather than navigating. */
+  soon?: boolean
+}
+
+export type Module = {
+  key: string
+  href: string
+  title: string
+  /** Shown under the title when no count is configured. */
+  desc: string
+  descCountKey?: string
+  descCountLabel?: string
+  /**
+   * The service this module is a face for, if it needs one. The frame does not
+   * use this — a surface filters its own list before passing it in — but it
+   * travels with the module so that filter has something to read.
+   */
+  service?: string
+  items: SubItem[]
+}
+
+/**
+ * The module a path belongs to: the longest `href` that prefixes it, so
+ * `/reports/vat` picks `reports` over `/`. Falls back to the first module.
+ */
+export function activeModule(pathname: string, modules: Module[]): Module {
+  const found = modules
+    .filter((m) => (m.href === '/' ? pathname === '/' : pathname.startsWith(m.href)))
+    .sort((a, b) => b.href.length - a.href.length)[0]
+  return found ?? modules[0]!
+}

package/src/primitives.css

@@ -0,0 +1,239 @@
+/* @baseworks/ui — primitives.
+
+   The pieces a screen is built from: buttons, cards, tables, forms, dialogs.
+   They know nothing about what the product is; every colour comes from
+   tokens.css. Classes, not utilities: one name per component, so a screen reads
+   as markup rather than as a list of measurements. */
+
+/* Page header — the title of a screen and one line saying what it is. */
+.page-head{display:flex;align-items:flex-end;gap:16px;margin:4px 0 20px;flex-wrap:wrap}
+.page-head h1{font-family:var(--display);font-size:27px;font-weight:400;margin:0;letter-spacing:-.01em;text-wrap:balance}
+.page-head p{margin:2px 0 0;color:var(--muted);font-size:13px}
+.page-head .spacer{flex:1}
+/* The light/dark toggle. Which icon shows is decided by the same conditions
+   tokens.css uses to pick the palette, so it is correct in the first paint and
+   needs no script until someone clicks it. */
+.theme-toggle .i-to-dark,.theme-toggle .i-to-light{display:none;line-height:0}
+.theme-toggle .i-to-dark{display:inline-block}
+@media (prefers-color-scheme: dark){
+  :root:not([data-theme="light"]) .theme-toggle .i-to-dark{display:none}
+  :root:not([data-theme="light"]) .theme-toggle .i-to-light{display:inline-block}
+}
+:root[data-theme="dark"] .theme-toggle .i-to-dark{display:none}
+:root[data-theme="dark"] .theme-toggle .i-to-light{display:inline-block}
+:root[data-theme="light"] .theme-toggle .i-to-dark{display:inline-block}
+:root[data-theme="light"] .theme-toggle .i-to-light{display:none}
+
+/* Buttons. One shape; ghost is the quiet one, danger the irreversible one. */
+.btn{
+  display:inline-flex;align-items:center;gap:8px;padding:8px 14px;border-radius:8px;font-weight:600;
+  background:var(--accent);color:var(--accent-ink);
+}
+.btn:hover{filter:brightness(1.06)}
+.btn.ghost{background:var(--surface);color:var(--ink);border:1px solid var(--line-strong);font-weight:500}
+.btn.ghost:hover{background:var(--surface2);filter:none}
+.btn.sm{padding:5px 10px;font-size:12.5px;border-radius:7px}
+.btn.danger{background:var(--crit);color:#fff}
+.btn.danger[disabled]{opacity:.45;cursor:not-allowed}
+.btn[disabled]{opacity:.6;cursor:progress}
+/* Cards, the stat strip, and key/value rows. */
+/* Cards stacked down a page need air between them, and a screen is usually a
+   stack of them. The gap lives on the card rather than on a wrapper so a screen
+   can put one anywhere without remembering to space it; inside `.grid2` the
+   grid's own gap takes over and this is cancelled. */
+.card{background:var(--surface);border:1px solid var(--line);border-radius:12px;margin-bottom:16px}
+.card:last-child{margin-bottom:0}
+.grid2>.card{margin-bottom:0}
+.card-pad{padding:18px}
+.card-head{
+  display:flex;align-items:baseline;gap:10px;flex-wrap:wrap;
+  padding:14px 18px;border-bottom:1px solid var(--line);
+}
+.card-head h2{padding:0;border:0}
+.card-head .cell-sub{margin-left:auto;text-align:right}
+/* What you can do to the card's contents, in its header. `margin-left:auto`
+   pushes it right; when a hint is there too, the hint has already claimed the
+   auto margin and this simply follows it. */
+.card-actions{margin-left:auto;display:flex;gap:8px;flex:none}
+.card-head .cell-sub + .card-actions{margin-left:14px}
+.stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:12px;margin-bottom:20px}
+.stat{padding:16px 18px}
+.stat .k{font-size:12px;color:var(--muted);display:flex;align-items:center;gap:6px}
+.stat .v{font-family:var(--sans);font-size:30px;font-weight:600;line-height:1.15;margin-top:4px}
+.stat .s{font-size:12px;color:var(--faint);margin-top:2px}
+.stat .s b{color:var(--ok);font-weight:600}
+.grid2{display:grid;grid-template-columns:1.4fr 1fr;gap:16px}
+@media(max-width:980px){.grid2{grid-template-columns:1fr}}
+.card h2{font-size:13px;font-weight:600;margin:0;padding:14px 18px;border-bottom:1px solid var(--line);display:flex;align-items:center;gap:8px}
+.card h2 .mini{margin-left:auto;font-size:12px;color:var(--accent);font-weight:600;cursor:pointer}
+.kv{display:flex;justify-content:space-between;gap:16px;padding:8px 0;border-bottom:1px solid var(--line);font-size:13px}
+.kv:last-child{border-bottom:0}
+.kv>span:first-child{color:var(--muted)}
+/* Attention strip — something the reader has to know before acting. */
+.attn{
+  display:flex;align-items:center;gap:12px;padding:10px 14px;border-radius:10px;
+  border:1px solid var(--line);background:var(--surface);font-size:13px;
+}
+.attn .sev{width:8px;height:8px;border-radius:50%;flex:none}
+.attn.warn .sev{background:var(--warn)}
+.attn.warn{border-color:var(--warn);border-left-width:3px}
+.attn.crit .sev{background:var(--crit)}
+.attn.crit{border-color:var(--crit);border-left-width:3px}
+.attn .act{margin-left:auto;color:var(--accent);font-weight:600;flex:none}
+/* Lists: an activity feed and a progress bar. */
+.feed{list-style:none;margin:0;padding:6px 0}
+.feed li{display:flex;gap:12px;padding:9px 18px;font-size:13px;align-items:baseline}
+.feed li+li{border-top:1px solid var(--line)}
+.feed time{font-family:var(--mono);font-size:11px;color:var(--faint);flex:none;width:44px}
+.feed .via{margin-left:auto;flex:none;font-size:11px;color:var(--faint);border:1px solid var(--line);border-radius:99px;padding:1px 8px}
+.feed .via.chat{color:var(--accent);border-color:var(--accent)}
+.prog{height:4px;border-radius:99px;background:var(--surface2);margin-top:8px;overflow:hidden}
+.prog i{display:block;height:100%;background:var(--accent);border-radius:99px}
+/* Tables, their toolbar, status pills, and the per-row menu.
+
+   The row menu is position:fixed and takes its coordinates from JS, because
+   the scroll container's overflow would otherwise clip it. */
+.toolbar{display:flex;align-items:center;gap:10px;margin-bottom:14px;flex-wrap:wrap}
+.toolbar input[type=search]{
+  border:1px solid var(--line-strong);border-radius:8px;padding:7px 12px;background:var(--surface);
+  min-width:220px;color:var(--ink);
+}
+.toolbar input::placeholder{color:var(--faint)}
+.table-wrap{overflow-x:auto;border:1px solid var(--line);border-radius:12px;background:var(--surface)}
+table{border-collapse:collapse;width:100%;font-size:13px;min-width:640px}
+th{
+  text-align:left;font-size:11px;text-transform:uppercase;letter-spacing:.08em;color:var(--faint);
+  font-weight:600;padding:10px 16px;border-bottom:1px solid var(--line);white-space:nowrap;
+}
+td{padding:12px 16px;border-bottom:1px solid var(--line);vertical-align:middle}
+tr:last-child td{border-bottom:none}
+tbody tr:hover{background:var(--surface2)}
+.cell-name{font-weight:600}
+.cell-name .cell-tag{
+  margin-left:7px;font-size:10px;font-weight:600;text-transform:uppercase;letter-spacing:.07em;
+  color:var(--muted);border:1px solid var(--line-strong);border-radius:99px;padding:1px 6px;
+  vertical-align:1px;white-space:nowrap;
+}
+.cell-sub{font-size:11.5px;color:var(--faint)}
+.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;font-weight:600;border-radius:99px;padding:2px 10px}
+.pill .d{width:6px;height:6px;border-radius:50%}
+.pill.ok{background:var(--ok-soft);color:var(--ok)}
+.pill.ok .d{background:var(--ok)}
+.pill.off{background:var(--surface2);color:var(--muted)}
+.pill.off .d{background:var(--faint)}
+.pill.warn{background:var(--warn-soft);color:var(--warn)}
+.pill.warn .d{background:var(--warn)}
+.pill.crit{background:var(--crit-soft);color:var(--crit)}
+.pill.crit .d{background:var(--crit)}
+.pill.acc{background:var(--accent-soft);color:var(--accent)}
+.pill.acc .d{background:var(--accent)}
+.row-actions{color:var(--faint);font-weight:700;letter-spacing:.1em}
+.row-menu{
+  position:fixed;z-index:80;min-width:170px;
+  max-height:calc(100vh - 16px);overflow-y:auto;
+  background:var(--surface);border:1px solid var(--line);border-radius:10px;
+  box-shadow:var(--shadow);padding:6px;display:flex;flex-direction:column;gap:2px;
+}
+.row-menu button{
+  text-align:left;padding:7px 10px;border-radius:7px;font-size:13px;color:var(--ink);width:100%;
+}
+.row-menu button:hover{background:var(--surface2)}
+.row-menu button.danger{color:var(--crit)}
+.row-menu button.danger:hover{background:var(--crit-soft)}
+/* Tabs. */
+.tabs{display:flex;gap:2px;border-bottom:1px solid var(--line);margin-bottom:16px;overflow-x:auto}
+.tab{
+  position:relative;padding:9px 14px;font-size:13px;font-weight:600;color:var(--muted);
+  border-bottom:2px solid transparent;white-space:nowrap;background:none;
+}
+.tab:hover{color:var(--ink)}
+.tab.active{color:var(--ink);border-bottom-color:var(--accent)}
+.tab-badge{
+  display:inline-block;margin-left:7px;min-width:17px;padding:1px 5px;border-radius:9px;
+  background:var(--accent-soft);color:var(--accent);font-size:11px;font-weight:700;text-align:center;
+}
+.tab-badge.warn{background:color-mix(in srgb,var(--warn) 18%,transparent);color:var(--warn)}
+/* Forms: fields, single-line rows, switches, errors.
+
+   The input selector excludes what is not a text box rather than listing what
+   is: a new input type should inherit the field styling by default, and a
+   checkbox stretched to 100% width is the bug this avoids. */
+.form-error{
+  font-size:12.5px;color:var(--crit);background:var(--crit-soft);
+  border-radius:8px;padding:8px 12px;
+}
+.sw{width:34px;height:20px;border-radius:99px;background:var(--line-strong);position:relative;transition:background .15s;flex:none}
+.sw::after{content:"";position:absolute;top:2px;left:2px;width:16px;height:16px;border-radius:50%;background:var(--surface);transition:left .15s;box-shadow:0 1px 3px rgba(0,0,0,.25)}
+.sw.on{background:var(--ok)}
+.sw.on::after{left:16px}
+.field label{display:block;font-size:12px;font-weight:600;color:var(--muted);margin-bottom:6px}
+.field input:not([type=checkbox]):not([type=radio]):not([type=range]),
+.field select,
+.field textarea,
+.form-row input:not([type=checkbox]):not([type=radio]),
+.form-row select{
+  width:100%;border:1px solid var(--line-strong);border-radius:8px;padding:9px 12px;
+  background:var(--surface);color:var(--ink);
+}
+.optline{display:flex;align-items:center;gap:10px;padding:10px 0;border-top:1px solid var(--line);font-size:13px}
+.optline small{color:var(--faint);display:block}
+.optline .sw{margin-left:auto}
+.form-row{display:flex;gap:8px;flex-wrap:wrap;align-items:center}
+.form-row input{flex:1;min-width:220px}
+.form-row select{flex:none;width:auto;min-width:150px}
+.form-row .btn{flex:none}
+/* Chips — a short, clickable suggestion. */
+.chips{display:flex;flex-wrap:wrap;gap:6px}
+.chip{font-size:12px;border:1px solid var(--line-strong);background:var(--surface);border-radius:99px;padding:5px 12px;color:var(--muted)}
+.chip:hover{border-color:var(--accent);color:var(--accent)}
+/* A block of literal text: a token, a command, a config fragment. */
+.codebox{font-family:var(--mono);font-size:12.5px;background:var(--surface2);border:1px solid var(--line);border-radius:8px;padding:10px 12px;white-space:pre-wrap;word-break:break-all}
+/* Dialog — a decision that blocks the page until it is answered. */
+.dialog-wrap{
+  position:fixed;inset:0;z-index:90;display:flex;align-items:flex-start;justify-content:center;
+  padding:16vh 16px 24px;overflow-y:auto;background:rgba(10,16,15,.5);
+}
+.dialog{
+  width:min(440px,92vw);background:var(--surface);border:1px solid var(--line);
+  border-radius:14px;box-shadow:var(--shadow);overflow:hidden;
+}
+.dialog-head{display:flex;align-items:center;gap:10px;padding:16px 20px;border-bottom:1px solid var(--line)}
+.dialog-head .sev{width:8px;height:8px;border-radius:50%;background:var(--crit);flex:none;box-shadow:0 0 0 3px var(--crit-soft)}
+.dialog-head h3{margin:0;font-size:15.5px;font-family:var(--sans);font-weight:600}
+.dialog-body{padding:18px 20px;max-height:62vh;overflow-y:auto;display:flex;flex-direction:column;gap:12px;font-size:13.5px;line-height:1.5}
+.dialog-body p{margin:0}
+.dialog-losses{margin:0;padding-left:18px;color:var(--muted);font-size:13px;display:flex;flex-direction:column;gap:3px}
+.dialog-foot{padding:14px 20px;border-top:1px solid var(--line);display:flex;gap:10px;justify-content:flex-end}
+/* Slide-over panel: a form that keeps the page behind it visible. */
+.scrim{position:fixed;inset:0;background:rgba(10,16,15,.45);z-index:60;opacity:0;pointer-events:none;transition:opacity .18s}
+.scrim.on{opacity:1;pointer-events:auto}
+.panel{
+  position:fixed;top:0;right:0;height:100vh;width:min(480px,100vw);z-index:70;background:var(--surface);
+  border-left:1px solid var(--line);box-shadow:var(--shadow);transform:translateX(102%);transition:transform .22s ease;
+  display:flex;flex-direction:column;
+}
+.panel.on{transform:none}
+.panel-head{display:flex;align-items:center;gap:10px;padding:16px 20px;border-bottom:1px solid var(--line)}
+.panel-head .icon-btn{margin-left:auto}
+.panel-head h3{margin:0;font-size:16px;font-family:var(--sans);font-weight:600}
+.panel-body{flex:1;overflow-y:auto;padding:20px;display:flex;flex-direction:column;gap:18px}
+.panel-foot{padding:14px 20px;border-top:1px solid var(--line);display:flex;gap:10px;justify-content:flex-end}
+/* Command palette. */
+.cmdk{position:fixed;inset:0;z-index:80;display:none;align-items:flex-start;justify-content:center;padding-top:14vh;background:rgba(10,16,15,.45)}
+.cmdk.on{display:flex}
+.cmdk-box{width:min(560px,92vw);background:var(--surface);border:1px solid var(--line);border-radius:14px;box-shadow:var(--shadow);overflow:hidden}
+.cmdk-box input{
+  width:100%;border:none;background:transparent;padding:16px 20px;font-size:15px;color:var(--ink);outline:none;
+  border-bottom:1px solid var(--line);
+}
+.cmdk-list{max-height:320px;overflow-y:auto;padding:8px}
+.cmdk-item{width:100%;display:flex;align-items:center;gap:12px;text-align:left;padding:10px 12px;border-radius:8px;font-size:13.5px}
+.cmdk-item:hover,.cmdk-item.hl{background:var(--accent-soft)}
+.cmdk-item .k{font-family:var(--mono);font-size:11px;color:var(--faint);margin-left:auto}
+/* Toast — the receipt for something that already happened. */
+.toast{
+  position:fixed;bottom:24px;left:50%;transform:translateX(-50%) translateY(80px);z-index:90;
+  background:var(--ink);color:var(--bg);padding:10px 18px;border-radius:10px;font-size:13px;font-weight:500;
+  transition:transform .22s ease;box-shadow:var(--shadow);max-width:90vw;
+}
+.toast.on{transform:translateX(-50%) translateY(0)}

package/src/slide-over.tsx

@@ -0,0 +1,66 @@
+'use client'
+
+import { useEffect, useRef, type ReactNode } from 'react'
+
+/**
+ * A form that slides in from the right and keeps the page behind it visible —
+ * for adding to a list while still reading the list you are adding to.
+ *
+ * The panel stays in the DOM and is moved off-screen, which is what makes the
+ * animation possible and creates two problems it has to solve itself:
+ *
+ * - `autoFocus` on a field inside fires when the panel first mounts, closed, so
+ *   opening it leaves focus on the button behind. The first field is focused
+ *   here instead, and only when `open` changes — an effect that also depended on
+ *   `onClose` re-ran on every render, because a caller writing `onClose={() =>
+ *   setOpen(false)}` passes a new function each time, and the focus then jumped
+ *   back to the first field on every keystroke in any other one.
+ * - A closed panel's fields are still tabbable. `inert` takes the whole thing
+ *   out of the tab order and away from assistive technology until it is open,
+ *   so a keyboard does not wander into a panel nobody can see.
+ */
+export function SlideOver({ open, onClose, title, footer, children }: {
+  open: boolean
+  onClose: () => void
+  title: ReactNode
+  footer?: ReactNode
+  children: ReactNode
+}) {
+  const bodyRef = useRef<HTMLDivElement>(null)
+  // Read through a ref so the effect below depends on `open` alone. See the
+  // note above: depending on the callback itself made it re-run per render.
+  const closeRef = useRef(onClose)
+  closeRef.current = onClose
+
+  useEffect(() => {
+    if (!open) return
+    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') closeRef.current() }
+    document.addEventListener('keydown', onKey)
+    // After the frame that opens it: focusing an element still being
+    // transformed into place scrolls the panel oddly in some browsers.
+    const t = setTimeout(() => {
+      bodyRef.current?.querySelector<HTMLElement>(
+        'input:not([disabled]), select:not([disabled]), textarea:not([disabled])',
+      )?.focus()
+    }, 60)
+    return () => { document.removeEventListener('keydown', onKey); clearTimeout(t) }
+  }, [open])
+
+  return (
+    <>
+      <div className={'scrim' + (open ? ' on' : '')} onClick={onClose} />
+      <aside
+        className={'panel' + (open ? ' on' : '')}
+        inert={!open}
+        aria-label={typeof title === 'string' ? title : undefined}
+      >
+        <div className="panel-head">
+          <h3>{title}</h3>
+          <button className="icon-btn" aria-label="Close" onClick={onClose}>✕</button>
+        </div>
+        <div className="panel-body" ref={bodyRef}>{children}</div>
+        {footer && <div className="panel-foot">{footer}</div>}
+      </aside>
+    </>
+  )
+}

package/src/styles.css

@@ -0,0 +1,7 @@
+/* @baseworks/ui — the whole stylesheet.
+   Import this once, in the app's root layout:  import '@baseworks/ui/styles.css'
+   The three files can also be imported separately when a product wants the
+   tokens and primitives without the frame. */
+@import './tokens.css';
+@import './primitives.css';
+@import './frame.css';

package/src/table.tsx

@@ -0,0 +1,53 @@
+import type { ReactNode } from 'react'
+
+export type PillTone = 'neutral' | 'ok' | 'off' | 'warn' | 'crit' | 'acc'
+
+/** A status, as a word and a colour. Never a colour alone. */
+export function Pill({ tone = 'neutral', children }: { tone?: PillTone; children: ReactNode }) {
+  return (
+    <span className={'pill' + (tone === 'neutral' ? '' : ` ${tone}`)}>
+      {tone !== 'neutral' && <span className="d" />}{children}
+    </span>
+  )
+}
+
+/**
+ * The first line of a cell: the thing's name.
+ *
+ * `tag` is the small note that belongs to the name rather than to a column of
+ * its own — "you", "active", "default". It has its own class instead of
+ * borrowing the rail's, which only has a rule inside the rail and rendered as
+ * bare text pushed against the name everywhere else.
+ */
+export function CellName({ children, tag }: { children: ReactNode; tag?: ReactNode }) {
+  return <div className="cell-name">{children}{tag && <span className="cell-tag">{tag}</span>}</div>
+}
+
+/** The quiet second line: an id, a timestamp, a reason. */
+export function CellSub({ children }: { children: ReactNode }) {
+  return <div className="cell-sub">{children}</div>
+}
+
+/**
+ * A table with its scroll container.
+ *
+ * `note` renders as a single full-width row and is the only thing shown when
+ * there are no rows: loading, an error, or "nothing here yet". Screens used to
+ * hand-roll that row with a colSpan they had to keep in sync with the header;
+ * `columns` gives the count for free.
+ */
+export function Table({ columns, note, children }:
+  { columns: ReactNode[]; note?: ReactNode; children?: ReactNode }) {
+  const empty = !children || (Array.isArray(children) && children.flat().filter(Boolean).length === 0)
+  return (
+    <div className="table-wrap">
+      <table>
+        <thead><tr>{columns.map((c, i) => <th key={i}>{c}</th>)}</tr></thead>
+        <tbody>
+          {children}
+          {note && empty && <tr><td colSpan={columns.length}><div className="cell-sub">{note}</div></td></tr>}
+        </tbody>
+      </table>
+    </div>
+  )
+}

package/src/theme-toggle.tsx

@@ -0,0 +1,33 @@
+'use client'
+
+import { applyTheme, resolvedTheme } from './theme'
+
+/**
+ * Light ↔ dark, in the top bar.
+ *
+ * Both icons are rendered and CSS hides one, using the same conditions
+ * tokens.css uses to pick the palette. The alternative — asking JavaScript
+ * which theme is on and rendering that icon — cannot know the answer until
+ * after hydration, so a viewer on a dark system would see the wrong icon for a
+ * frame on every load. Here the icon is right in the first paint, and script
+ * runs only when someone clicks.
+ */
+export function ThemeToggle({ prefix }: { prefix?: string }) {
+  return (
+    <button
+      className="icon-btn theme-toggle"
+      title="Switch between light and dark"
+      aria-label="Switch between light and dark"
+      onClick={() => applyTheme(resolvedTheme() === 'dark' ? 'light' : 'dark', prefix)}
+    >
+      {/* Shown in light: a moon, because it offers dark. */}
+      <span className="i-to-dark" aria-hidden="true">
+        <svg width="17" height="17" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5"><path d="M13.5 9.5A5.8 5.8 0 0 1 6.5 2.5a5.8 5.8 0 1 0 7 7Z"/></svg>
+      </span>
+      {/* Shown in dark: a sun. */}
+      <span className="i-to-light" aria-hidden="true">
+        <svg width="17" height="17" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5"><circle cx="8" cy="8" r="3"/><path d="M8 1.5v1.6M8 12.9v1.6M1.5 8h1.6M12.9 8h1.6M3.4 3.4l1.1 1.1M11.5 11.5l1.1 1.1M12.6 3.4l-1.1 1.1M4.5 11.5l-1.1 1.1"/></svg>
+      </span>
+    </button>
+  )
+}

package/src/theme.ts

@@ -0,0 +1,55 @@
+/**
+ * Theme.
+ *
+ * There is one palette — see tokens.css — in a light and a dark form. The
+ * operating system decides which, until someone says otherwise: `data-theme` on
+ * <html> forces a form in both directions, and `ThemeToggle` is the control
+ * that sets it.
+ *
+ * The choice is remembered per browser, so it has to be restored before the
+ * first paint — `themeInitScript()` in <head>, or the page renders the system's
+ * answer and then flips to the stored one.
+ */
+
+export type ThemeMode = 'system' | 'light' | 'dark'
+
+const themeKey = (prefix: string) => `${prefix}.theme`
+
+/** What the document is showing now — not what is stored. */
+export function currentTheme(): ThemeMode {
+  if (typeof document === 'undefined') return 'system'
+  const t = document.documentElement.dataset['theme']
+  return t === 'dark' || t === 'light' ? t : 'system'
+}
+
+/**
+ * What the viewer is actually seeing: the forced form if there is one, else the
+ * system's. This is the honest answer to "which theme is on" — `currentTheme()`
+ * says `system`, which is a setting, not a colour.
+ */
+export function resolvedTheme(): 'light' | 'dark' {
+  const forced = currentTheme()
+  if (forced !== 'system') return forced
+  if (typeof window === 'undefined') return 'light'
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+}
+
+/** Force a form, or hand the decision back to the system. Remembered per browser. */
+export function applyTheme(mode: ThemeMode, prefix = 'bw'): void {
+  if (mode === 'system') delete document.documentElement.dataset['theme']
+  else document.documentElement.dataset['theme'] = mode
+  try { localStorage.setItem(themeKey(prefix), mode) } catch { /* private mode: the choice just does not persist */ }
+}
+
+/**
+ * The snippet for <head>, for a product that uses `applyTheme`. It is
+ * deliberately tiny and wrapped in try/catch: a browser that refuses
+ * localStorage must still render the page.
+ *
+ * A product with no toggle does not need this at all — with nothing stored,
+ * `prefers-color-scheme` already decides.
+ */
+export function themeInitScript(prefix = 'bw'): string {
+  return `try{var t=localStorage.getItem("${themeKey(prefix)}");`
+    + `if(t==="dark"||t==="light")document.documentElement.dataset.theme=t}catch(e){}`
+}