@prestack/thread-ui 0.0.1 → 0.0.2

package/dist/ui/elements/value.tsx

@@ -0,0 +1,30 @@
+'use client'
+
+import { roleClass, type FontRoleId } from '../fonts.ts'
+
+import { type Element, element, useSurface } from '../wrappers.tsx'
+import { shows } from './value.works.ts'
+
+
+export interface ValueProps {
+  readonly validator: string
+  readonly value?: unknown
+  readonly context?: Readonly<Record<string, unknown>>
+  readonly is?: FontRoleId
+  readonly dispatch?: string
+  readonly input?: Readonly<Record<string, unknown>>
+  readonly invokeOn?: 'press' | 'shown'
+}
+
+export const Value: Element<'Value', ValueProps> = element(
+  'Value',
+  (props: ValueProps, className) => {
+    const surface = useSurface({ className: roleClass(props.is, className),
+    invokes: { ...(props.dispatch === undefined ? {} : { dispatch: props.dispatch }), ...(props.input === undefined ? {} : { input: props.input }), ...(props.invokeOn === undefined ? {} : { on: props.invokeOn }) }, })
+    return (
+      shows(props, surface)
+    )
+  },
+  'e-value',
+  {},
+)

package/dist/ui/elements/value.works.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react'
+
+import { renderValue } from '../content.tsx'
+import type { Surface } from '../door.ts'
+import type { ValueProps } from './value.tsx'
+
+export function shows(props: ValueProps, surface: Surface): ReactNode {
+  return renderValue({ validator: props.validator, value: props.value, ...(props.context === undefined ? {} : { context: props.context }) }, surface)
+}

package/dist/ui/elements.ts

@@ -0,0 +1,127 @@
+import type { Threaded } from '@prestack/thread/core/thread'
+
+import type { Wearing } from './token.ts'
+
+interface Arranging extends Threaded {
+  readonly arranges?: boolean
+  readonly sets?: Readonly<Record<string, string>>
+
+  readonly tag?: string | Readonly<Record<string, string>>
+  readonly raises?: readonly string[]
+
+  readonly carries?: Readonly<Record<string, string>>
+
+  readonly always?: readonly string[]
+
+  readonly places?: Readonly<Record<string, Readonly<Record<string, string>>>>
+
+  readonly works?: string
+
+  readonly measures?: readonly string[]
+
+  readonly reads?: string
+
+  readonly gives?: readonly string[]
+
+  readonly keeps?: boolean
+
+  readonly animates?: boolean
+
+  readonly shows?: string
+
+  readonly called?: string
+
+  readonly wires?: string
+
+  readonly dresses?: string
+}
+
+interface Catalogue extends Threaded {
+  readonly files: string
+  readonly declares?: readonly Arranging[]
+}
+
+const arranging = <const T extends readonly Arranging[]>(
+  rows: T & {
+    readonly [I in keyof T]: (T[I] extends { readonly sets: infer Said }
+      ? { readonly sets: { readonly [P in keyof Said]: Wearing<Said[P] & string> } }
+      : unknown) &
+      (T[I] extends { readonly places: infer Inside }
+        ? {
+            readonly places: {
+              readonly [R in keyof Inside]: {
+                readonly [P in keyof Inside[R]]: Wearing<Inside[R][P] & string>
+              }
+            }
+          }
+        : unknown)
+  },
+): T => rows
+
+export const ELEMENTS = {
+  id: 'element',
+  at: 'thread/ui/elements.ts',
+  files: 'ui/*.tsx',
+  describes: 'An interface part, and function only: what it does, what it carries and which signals it raises, never how it looks and never markup a person writes. Its look is a variant it wears, its wording arrives as a message key rather than as words, and `thread elements` writes its file from this row, so the file is never typed. Every part this framework ships is listed here, an app adds its own to the same list, and a row that goes missing breaks the build, because what the framework offers is not an app’s to withdraw. A thing made of parts already listed here is a composition, not a new element.',
+  version: 1,
+  cites: [
+    {
+      on: '2026-08-31',
+      said: 'elements does not hold anything that can render anything, its functionality only . only our compiler can translate things into proper css and html and only at build time do we produce a renderable result.',
+    },
+    {
+      on: '2026-08-29',
+      said: 'CLI actually generates the tsx file, and you MUST give the file its body, properly.',
+    },
+  ],
+  declares: arranging([
+    { id: 'accordion', at: 'thread/ui/elements/accordion.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', keeps: true, works: './accordion.works.ts', carries: { items: 'parting', initial: 'ordering', exclusive: 'flag', onChange: 'choosing' }, places: { section: { tag: 'div', each: 'items', by: 'id', gives: 'section', holds: 'header region' }, header: { tag: 'button', gives: 'header', shows: 'label' }, region: { tag: 'div', gives: 'region', shows: 'inside' } }, describes: 'Sections that open one at a time, for long material somebody reads part of.' },
+    { id: 'aspect-ratio', at: 'thread/ui/elements/aspect-ratio.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', arranges: true, carries: { ratio: 'count' }, measures: ['ratio'], works: './aspect-ratio.works.ts', sets: { aspectRatio: 'ratio' }, describes: 'A slot that keeps its proportions whatever width it gets, so a loading picture reserves its room.' },
+    { id: 'avatar', at: 'thread/ui/elements/avatar.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'span', reads: 'picture', carries: { labelKey: 'naming', src: 'picture', initials: 'words' }, works: './avatar.works.ts', places: { picture: { tag: 'img', shows: 'src' }, lettering: { shows: 'lettering' } }, describes: 'A person or an organisation as a small picture, falling back to initials when there is no image.' },
+    { id: 'badge', at: 'thread/ui/elements/badge.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'span', carries: { labelKey: 'wording', count: 'count', max: 'count' }, works: './badge.works.ts', describes: 'A short status word attached to something else. For counts and states, never for an action.' },
+    { id: 'bars', at: 'thread/ui/elements/bars.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', reads: 'picture', keeps: true, works: './bars.works.ts', carries: { rows: 'listing', by: 'ruling', value: 'ruling', format: 'words', titleKey: 'titling' }, places: { bar: { each: 'rows', by: 'by', marks: 'sized', holds: 'label amount' }, label: { shows: 'label' }, amount: { shows: 'amount' } }, describes: 'Quantities compared across categories. The default when the horizontal axis is not time.' },
+    { id: 'box', at: 'thread/ui/elements/box.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', arranges: true, reads: 'grouping', raises: ['scrolling'], carries: { labelKey: 'titling' }, describes: 'The declared `div`. Groups children, optionally as a landmark region, and optionally scrolls. A box that scrolls raises `scrolling`, which a variant may dress; naming one makes it a group, and leaving it unnamed leaves it a box.' },
+    { id: 'breadcrumb', at: 'thread/ui/elements/breadcrumb.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'nav', called: 'nav.breadcrumb', works: './breadcrumb.works.ts', carries: { map: 'mapping', current: 'ruling' }, places: { step: { tag: 'Link.linkInline', each: 'steps', by: 'id', gives: 'crumb' } }, describes: 'The trail back up from wherever somebody is, derived from the route rather than assembled by hand.' },
+    { id: 'button', at: 'thread/ui/elements/button.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'button', keeps: true, works: './button.works.tsx', wires: 'wires', carries: { label: 'wording', with: 'holding', icon: 'words', shows: 'words', type: 'words', disabled: 'flag', loading: 'flag', dispatch: 'words', input: 'holding', navigateTo: 'words', onPress: 'doing' }, places: { symbol: { when: 'iconed', shows: 'symbol', display: 'layout-flex', alignItems: 'align-centre' }, wording: { when: 'worded', shows: 'wording' } }, describes: 'A press that runs a declared workflow or goes to a declared screen. The only way to start either from a tap.' },
+    { id: 'column', at: 'thread/ui/elements/column.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', describes: 'Children stacked top to bottom. The vertical arrangement, and the default shape of a form.', arranges: true, sets: { display: 'layout-flex', flexDirection: 'flow-down', gap: 'space-3' } },
+    { id: 'consent', at: 'thread/ui/elements/consent.tsx', by: 'thread elements', runs: 'thread elements --own --check', keeps: true, works: './consent.works.tsx', carries: { decision: 'judging', onDecide: 'judged', policyKey: 'noting', preselected: 'ordering' }, places: { panel: { tag: 'Box.card', holds: 'body' }, body: { tag: 'Column', holds: 'title policy list actions' }, title: { tag: 'Text', gives: 'title' }, policy: { tag: 'Text', when: 'hasPolicy', gives: 'policy' }, list: { tag: 'Column', holds: 'category' }, category: { tag: 'Box', each: 'categories', by: 'id', holds: 'words switch fixed' }, words: { tag: 'Column', holds: 'label describe' }, label: { tag: 'Text', gives: 'label' }, describe: { tag: 'Text', gives: 'describe' }, switch: { tag: 'Toggle.input', when: 'optional', gives: 'chooser' }, fixed: { tag: 'Text', when: 'required', gives: 'fixed' }, actions: { tag: 'Box', holds: 'withdraw decline accept accept-all' }, withdraw: { tag: 'Button.buttonQuiet', when: 'withdrawable', gives: 'withdraw' }, decline: { tag: 'Button.buttonBorder', gives: 'decline' }, accept: { tag: 'Button.buttonBorder', gives: 'accept' }, 'accept-all': { tag: 'Button.buttonFill', gives: 'acceptAll' } }, describes: 'The complete permission-to-collect surface, with every declared category and its decision.' },
+    { id: 'donut', at: 'thread/ui/elements/donut.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'svg', reads: 'picture', keeps: true, works: './donut.works.ts', carries: { rows: 'listing', by: 'ruling', value: 'ruling', titleKey: 'titling' }, places: { slice: { tag: 'circle', each: 'rows', by: 'by', gives: 'slice' } }, describes: 'Parts of one whole, for a handful of slices. Beyond that the reading is worse than a bar.' },
+    { id: 'each', at: 'thread/ui/elements/each.tsx', by: 'thread elements', runs: 'thread elements --own --check', works: './each.works.tsx', carries: { rows: 'anything', by: 'ruling', children: 'drawing', settles: 'words', paced: 'words' }, describes: 'One rendered thing per row of data. The construct that replaces mapping over an array by hand.' },
+    { id: 'empty', at: 'thread/ui/elements/empty.tsx', by: 'thread elements', runs: 'thread elements --own --check', always: ['empty'], tag: 'div', describes: 'What a surface says when its read answered with nothing. Never the same rendering as still loading.' },
+    { id: 'field', at: 'thread/ui/elements/field.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'label', keeps: true, works: './field.works.ts', carries: { name: 'ruling', validator: 'ruling', labelKey: 'wording', value: 'words', onValue: 'picking', context: 'holding', autocomplete: 'words', disabled: 'flag' }, places: { caption: { shows: 'labelKey' }, entry: { tag: 'input', gives: 'entry' }, fault: { reads: 'alarm', shows: 'fault' } }, describes: 'One value being typed, governed entirely by the validator it names — keyboard, mask, limit and message.' },
+    { id: 'funnel', at: 'thread/ui/elements/funnel.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', reads: 'picture', keeps: true, works: './funnel.works.ts', carries: { rows: 'listing', by: 'ruling', value: 'ruling', format: 'words', titleKey: 'titling' }, places: { stage: { each: 'rows', by: 'by', marks: 'sized', holds: 'label amount' }, label: { shows: 'label' }, amount: { shows: 'amount' } }, describes: 'Fall-off between ordered stages, with the drop at each step derived rather than supplied.' },
+    { id: 'gauge', at: 'thread/ui/elements/gauge.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'svg', reads: 'picture', keeps: true, works: './gauge.works.ts', carries: { value: 'count', min: 'count', max: 'count', labelKey: 'naming' }, places: { track: { tag: 'path', gives: 'track' }, needle: { tag: 'path', gives: 'needle' } }, describes: 'A single quantity against a target, where the reading is how far along rather than how much.' },
+    { id: 'grid', at: 'thread/ui/elements/grid.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', describes: 'Children arranged, and nothing more. Its tracks are not something a row can state — the style guide binds no track property, deliberately — so this sets nothing and a caller that wants a set of equal panels wraps a `Row` instead. Kept, and its sentence made true, because the one it carried promised tracks it has never laid out: “as many equal tracks as the container allows”, on a row with no `sets` at all.', arranges: true },
+    { id: 'heatmap', at: 'thread/ui/elements/heatmap.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', reads: 'picture', keeps: true, works: './heatmap.works.ts', carries: { rows: 'listing', by: 'ruling', x: 'ruling', y: 'ruling', value: 'words', titleKey: 'titling' }, places: { cell: { each: 'rows', by: 'by', marks: 'sized' } }, describes: 'Density across two axes, for when the pattern matters more than any single cell.' },
+    { id: 'hit-box', at: 'thread/ui/elements/hit-box.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', arranges: true, keeps: true, works: './hit-box.works.tsx', wires: 'wires', carries: { gesture: 'ruling', tuning: 'tuning', axis: 'words', grabs: 'subjecting', accepts: 'ordering', collects: 'subjecting', dwell: 'count', moves: 'flag', onDrop: 'doing', dispatch: 'words', input: 'holding' }, sets: { display: 'layout-block', touchAction: 'touch', userSelect: 'pick', visibility: 'shown', position: 'flow' }, measures: ['touch', 'pick', 'shown', 'flow', 'width', 'height', 'carry', 'grip'], places: { carried: { tag: 'div', shows: 'carried', position: 'position-pinned', left: 'space-0', top: 'space-0', width: 'width', height: 'height', transform: 'carry', transformOrigin: 'grip', pointerEvents: 'reach-through', userSelect: 'picking-off', zIndex: 'layer-carried', willChange: 'readying-movement' } }, describes: 'A region that claims a gesture, composed with anything and declared by nothing. Put it where the grab should be, not on the element.' },
+    { id: 'glyph', at: 'thread/ui/elements/glyph.tsx', by: 'thread elements', runs: 'thread elements --own --check', carries: { name: 'ruling', labelKey: 'noting' }, works: './glyph.works.tsx', describes: 'A semantic pictogram — `close`, `search` — resolved from whichever set the design chose at build time. It is laid out rather than left inline, because an `svg` that is left inline stands on a text baseline: the line it sits on keeps a descender\'s worth of room under the drawing, so the drawing rides above the middle of whatever holds it and the wording beside it reads as sitting lower. Measured 2026-09-03 in `thread-palette-lab`: a 24px symbol in a 28px box, its centre 2.00px above the row\'s and the wording\'s 0.36px below — 2.36px apart, the same amount everywhere, on every icon in the app.', sets: { display: 'layout-flex' } },
+    { id: 'image', at: 'thread/ui/elements/image.tsx', by: 'thread elements', runs: 'thread elements --own --check', carries: { src: 'source', altKey: 'naming' }, tag: 'img', describes: 'A picture with alternative wording, for photographs and artwork rather than for interface symbols.' },
+    { id: 'line-chart', at: 'thread/ui/elements/line-chart.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'svg', reads: 'picture', keeps: true, works: './line-chart.works.ts', carries: { rows: 'listing', by: 'words', value: 'ruling', titleKey: 'titling' }, places: { line: { tag: 'polyline', each: 'lines', by: 'group', gives: 'drawing' } }, describes: 'A quantity over time, with axes. The chart for a trend somebody will read values off.' },
+    { id: 'link', at: 'thread/ui/elements/link.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'a', keeps: true, shows: 'labelKey', carries: { navigateTo: 'ruling', labelKey: 'wording', is: 'styling' }, works: './link.works.ts', describes: 'Wording that carries somebody to a declared screen. A press that navigates and does not act.' },
+    { id: 'media', at: 'thread/ui/elements/media.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: { by: 'as', image: 'img', video: 'video', audio: 'audio', file: 'a' }, carries: { as: 'words', src: 'source', altKey: 'naming' }, describes: 'Whatever a media or file value turns out to be — a picture, a clip, a document — rendered by its kind.' },
+    { id: 'menu', at: 'thread/ui/elements/menu.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'span', keeps: true, works: './menu.works.tsx', dresses: 'opener', measures: ['x', 'y'], carries: { labelKey: 'wording', items: 'listing', side: 'words' }, places: { opener: { tag: 'button', gives: 'opener', shows: 'labelKey' }, portal: { tag: 'Presented', gives: 'portal', holds: 'layer' }, layer: { tag: 'div', gives: 'listing', holds: 'row', position: 'position-lifted', left: 'x', top: 'y' }, row: { tag: 'MenuRow', each: 'items', by: 'labelKey', gives: 'row' } }, describes: 'Actions revealed on demand from a trigger, with keyboard traversal and dismissal already handled.' },
+    { id: 'money', at: 'thread/ui/elements/money.tsx', by: 'thread elements', runs: 'thread elements --own --check', carries: { value: 'amount', is: 'styling' }, works: './money.works.ts', describes: 'An amount with its currency, formatted for the locale. Never a number and a symbol concatenated.' },
+    { id: 'pagination', at: 'thread/ui/elements/pagination.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'nav', called: 'nav.pagination', works: './pagination.works.ts', carries: { map: 'mapping', sequence: 'ordering', current: 'ruling' }, places: { step: { tag: 'Link.linkInline', each: 'steps', by: 'id', gives: 'step' } }, describes: 'Movement between pages of a long result, for when scrolling to the end is not reasonable.' },
+    { id: 'progress', at: 'thread/ui/elements/progress.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', reads: 'progress', carries: { value: 'count', target: 'count', labelKey: 'naming' }, measures: ['fraction', 'span'], works: './progress.works.ts', places: { bar: { width: 'span' } }, describes: 'Work advancing toward a known end. The determinate half of what a spinner shows.' },
+    { id: 'radio-group', at: 'thread/ui/elements/radio-group.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', reads: 'choices', keeps: true, works: './radio-group.works.ts', carries: { name: 'ruling', labelKey: 'naming', options: 'listing', chosen: 'words', onValue: 'picking', disabled: 'flag' }, places: { option: { tag: 'label', each: 'options', by: 'value', holds: 'control caption' }, control: { tag: 'input', reads: 'choosing', gives: 'option' }, caption: { shows: 'caption' } }, describes: 'One answer from a short set, all visible at once. The version of a picker with nothing hidden.' },
+    { id: 'row', at: 'thread/ui/elements/row.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', describes: 'Children left to right at the width each one needs. The horizontal arrangement, and the one this catalogue did not have — measured 2026-08-31: a column stacks, a grid cuts equal tracks, a stack overlaps, and a box states what it means rather than which way it runs, so a label beside a button had no declared shape and every app drew it with a host element.', arranges: true, sets: { display: 'layout-flex', flexDirection: 'flow-across', alignItems: 'align-centre', gap: 'space-3' } },
+    { id: 'scatter', at: 'thread/ui/elements/scatter.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'svg', reads: 'picture', keeps: true, works: './scatter.works.ts', carries: { rows: 'listing', x: 'ruling', y: 'ruling', titleKey: 'titling' }, places: { point: { tag: 'circle', each: 'rows', keyed: 'position', gives: 'point' } }, describes: 'Two measurements plotted against each other, to show whether they move together.' },
+    { id: 'select', at: 'thread/ui/elements/select.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'label', carries: { labelKey: 'wording', options: 'listing', value: 'words', onValue: 'picking' }, works: './select.works.ts', places: { label: { shows: 'labelKey' }, control: { tag: 'select', reads: 'chooser', shows: 'value', holds: 'option' }, option: { tag: 'option', each: 'options', by: 'value', shows: 'labelKey' } }, describes: 'One answer picked from a closed list somebody scrolls. For a handful of options, prefer radios.' },
+    { id: 'separator', at: 'thread/ui/elements/separator.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', reads: 'divider', carries: { labelKey: 'noting', orientation: 'words' }, places: { label: { shows: 'labelKey' } }, describes: 'A visible break between groups, announced as one rather than drawn as a border on a neighbour.' },
+    { id: 'skeleton', at: 'thread/ui/elements/skeleton.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'span', reads: 'placeholder', carries: { lines: 'count' }, places: { line: { each: 'lines' } }, describes: 'The shape of content that has not arrived, sized like the real thing so nothing jumps when it does.' },
+    { id: 'slider', at: 'thread/ui/elements/slider.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'input', reads: 'sliding', gives: ['min', 'max', 'step'], carries: { labelKey: 'naming', value: 'count', min: 'count', max: 'count', step: 'count', onValue: 'moving' }, works: './slider.works.ts', describes: 'A number chosen along a range, where the approximate value matters more than the exact one.' },
+    { id: 'sparkline', at: 'thread/ui/elements/sparkline.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'svg', reads: 'placeholder', keeps: true, works: './sparkline.works.ts', carries: { rows: 'listing', value: 'ruling' }, places: { line: { tag: 'polyline', gives: 'drawing' } }, describes: 'A shape over time with no axes, small enough to sit inside a row of text.' },
+    { id: 'spinner', at: 'thread/ui/elements/spinner.tsx', by: 'thread elements', runs: 'thread elements --own --check', carries: { labelKey: 'naming' }, always: ['spinner'], tag: 'span', describes: 'Work in progress with no measurable end. Where the end IS measurable, show progress instead.' },
+    { id: 'stack', at: 'thread/ui/elements/stack.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', describes: 'Children on the z-axis, overlapping by a token offset — an avatar sitting over the top edge of a panel.', arranges: true },
+    { id: 'stat', at: 'thread/ui/elements/stat.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'figure', carries: { labelKey: 'wording', value: 'amount', compare: 'count', format: 'words' }, works: './stat.works.ts', places: { figure: { shows: 'figure' }, caption: { tag: 'figcaption', shows: 'labelKey' }, delta: { shows: 'delta' } }, describes: 'One headline number with its movement, derived. Passing a precomputed delta is how a dashboard disagrees with itself.' },
+    { id: 'surface', at: 'thread/ui/elements/surface.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', arranges: true, keeps: true, animates: true, works: './surface.works.ts', describes: 'A plain painted panel wearing a resolved look, for when the treatment IS the content.' },
+    { id: 'table', at: 'thread/ui/elements/table.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'table', keeps: true, works: './table.works.ts', carries: { rows: 'listing', columns: 'listing', by: 'ruling', titleKey: 'titling' }, places: { head: { tag: 'thead', holds: 'heading' }, heading: { tag: 'tr', holds: 'headed' }, headed: { tag: 'th', each: 'columns', by: 'field', gives: 'heading', shows: 'heading' }, body: { tag: 'tbody', holds: 'record' }, record: { tag: 'tr', each: 'rows', by: 'by', holds: 'cell' }, cell: { tag: 'td', each: 'columns', by: 'field', shows: 'cell' } }, describes: 'Rows and columns somebody scans and compares. Reach for this when the exact values are the point.' },
+    { id: 'tabs', at: 'thread/ui/elements/tabs.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'div', keeps: true, works: './tabs.works.ts', carries: { items: 'parting', initial: 'words', onChange: 'picking', orientation: 'words' }, dresses: 'strip', places: { strip: { tag: 'div', gives: 'strip', holds: 'tab', display: 'layout-flex', alignItems: 'align-centre' }, tab: { tag: 'button', each: 'items', by: 'id', gives: 'tab', shows: 'label', display: 'layout-flex', alignItems: 'align-centre', justifyContent: 'align-centre', height: 'control-md', padding: 'control-pad-y control-pad-x', borderRadius: 'control-radius', borderWidth: 'edge-hair', borderStyle: 'line-off', borderColor: 'colour-clear', background: 'colour-clear', color: 'colour-ink', cursor: 'cursor-press', transition: 'motion-quick ease-out' }, panel: { tag: 'div', when: 'opened', gives: 'panel', shows: 'inside' } }, describes: 'Sibling panels where only one is visible, switched without going anywhere. Not navigation between screens. It `dresses` its strip rather than itself, which is the difference between a row of tabs and a capsule: the element wraps the strip AND the panel, so a variant landing on the element put `radius-lg` and a filled material around the whole assembly — measured 2026-09-03, and it is what made tabs read as one pill with a page inside it. The tab itself states its own look here because every key it had was structural, so the generator emitted a `button` with no class at all and nothing any style guide row said could reach it.' },
+    { id: 'text', at: 'thread/ui/elements/text.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'span', shows: 'k', sets: { display: 'layout-inline-block' }, carries: { k: 'wording', with: 'holding', is: 'styling', announce: 'announcing' }, describes: 'The only place a message key becomes visible words. Every sentence a person reads passes through here. It sets `inline-block` because that is what makes a font role\'s trim reach it: `text-box-trim` acts on a block container\'s line boxes and an inline box is not one, so a role carrying the trim governed nothing wherever wording rendered inline. Measured 2026-09-03 at a 1280 viewport: 62 of 90 text elements trimmed to their cap height exactly without this, 72 with it, and the number wrapping to more than one line was 4 either way — it costs no wrapping. Inline-block rather than block because wording still belongs in a line beside other things when an app puts it there.' },
+    { id: 'textarea', at: 'thread/ui/elements/textarea.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'label', carries: { labelKey: 'wording', name: 'words', value: 'words', onValue: 'picking', validator: 'words', rows: 'count' }, works: './textarea.works.ts', places: { label: { shows: 'labelKey' }, control: { tag: 'textarea', reads: 'writing', shows: 'value', takes: 'name rows validator' } }, describes: 'Prose being typed across more than one line, where the shape of what is written matters.' },
+    { id: 'time', at: 'thread/ui/elements/time.tsx', by: 'thread elements', runs: 'thread elements --own --check', keeps: true, carries: { value: 'amount', relative: 'flag', is: 'styling' }, works: './time.works.ts', describes: 'A moment, formatted absolutely or as distance from now. Never a date somebody assembled from parts.' },
+    { id: 'toggle', at: 'thread/ui/elements/toggle.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'label', carries: { labelKey: 'wording', on: 'flag', onToggle: 'telling' }, works: './toggle.works.ts', places: { control: { tag: 'input', reads: 'choice', shows: 'on' }, label: { shows: 'labelKey' } }, describes: 'A single yes-or-no answer, flipped in place. Reach for this rather than two mutually exclusive buttons.' },
+    { id: 'tooltip', at: 'thread/ui/elements/tooltip.tsx', by: 'thread elements', runs: 'thread elements --own --check', tag: 'span', arranges: true, keeps: true, works: './tooltip.works.ts', dresses: 'bubble', measures: ['x', 'y'], carries: { labelKey: 'wording', side: 'words' }, places: { bubble: { tag: 'span', when: 'showing', gives: 'bubble', shows: 'labelKey', position: 'position-lifted', left: 'x', top: 'y' } }, describes: 'A short clarification revealed by hovering or focusing. Never the only place something is said.' },
+    { id: 'value', at: 'thread/ui/elements/value.tsx', by: 'thread elements', runs: 'thread elements --own --check', carries: { validator: 'ruling', value: 'amount', context: 'holding', is: 'styling' }, works: './value.works.ts', describes: 'A single formatted datum, punctuated by the validator that governs its kind rather than by the caller.' },
+  ]),
+} as const satisfies Catalogue

package/dist/ui/focus-scope.ts

@@ -0,0 +1,121 @@
+'use client'
+
+import { useEffect, type RefObject } from 'react'
+
+const CANDIDATES = [
+  'a[href]',
+  'button',
+  'input',
+  'select',
+  'textarea',
+  '[tabindex]',
+  'audio[controls]',
+  'video[controls]',
+  '[contenteditable]:not([contenteditable="false"])',
+].join(',')
+
+function reachable(element: Element): boolean {
+  for (let node: Element | null = element; node !== null; node = node.parentElement) {
+    if (node.hasAttribute('hidden') || node.hasAttribute('inert')) return false
+
+    const style = getComputedStyle(node)
+    if (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse') return false
+  }
+  return true
+}
+
+export function tabbables(root: Element): readonly HTMLElement[] {
+  return [...root.querySelectorAll<HTMLElement>(CANDIDATES)].filter((element) => {
+    if (element.hasAttribute('disabled')) return false
+
+    if (element.tabIndex < 0) return false
+    if (element instanceof HTMLInputElement && element.type === 'hidden') return false
+    return reachable(element)
+  })
+}
+
+const SCOPES: RefObject<HTMLElement | null>[] = []
+
+function innermost(ref: RefObject<HTMLElement | null>): boolean {
+  const element = ref.current
+  if (element === null) return false
+  return !SCOPES.some((other) => {
+    const candidate = other.current
+    return other !== ref && candidate !== null && element.contains(candidate)
+  })
+}
+
+export function useFocusScope(
+  ref: RefObject<HTMLElement | null>,
+  options: { readonly active: boolean; readonly trapFocus: boolean; readonly returnFocus: boolean },
+): void {
+  const { active, trapFocus, returnFocus } = options
+
+  useEffect(() => {
+    if (!active) return
+    const element = ref.current
+    if (element === null) return
+
+    const previous = document.activeElement instanceof HTMLElement ? document.activeElement : null
+
+    if (returnFocus) {
+      const first = tabbables(element)[0]
+      if (first !== undefined) {
+        first.focus()
+      } else {
+
+        if (!element.hasAttribute('tabindex')) element.setAttribute('tabindex', '-1')
+        element.focus()
+      }
+    }
+
+    SCOPES.push(ref)
+
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key !== 'Tab' || !trapFocus) return
+
+      if (!innermost(ref)) return
+      const root = ref.current
+      if (root === null) return
+
+      const list = tabbables(root)
+      if (list.length === 0) {
+
+        event.preventDefault()
+        return
+      }
+
+      const firstItem = list[0] as HTMLElement
+      const lastItem = list[list.length - 1] as HTMLElement
+      const activeNow = document.activeElement
+
+      if (event.shiftKey) {
+        if (activeNow === firstItem || activeNow === root || !root.contains(activeNow)) {
+          event.preventDefault()
+          lastItem.focus()
+        }
+        return
+      }
+      if (activeNow === lastItem || activeNow === root || !root.contains(activeNow)) {
+        event.preventDefault()
+        firstItem.focus()
+      }
+    }
+
+    document.addEventListener('keydown', onKeyDown, true)
+
+    return () => {
+      document.removeEventListener('keydown', onKeyDown, true)
+      const at = SCOPES.lastIndexOf(ref)
+
+      if (at !== -1) SCOPES.splice(at, 1)
+
+      if (!returnFocus) return
+      if (previous !== null && previous.isConnected) {
+        previous.focus()
+        return
+      }
+      document.body.focus()
+    }
+  }, [active, trapFocus, returnFocus, ref])
+}