@weft-js/warp 0.0.0-stage → 0.1.0

package/src/TimeField.tsx

@@ -0,0 +1,237 @@
+import { CalendarIcon, ClockIcon } from '@weft-js/warp-icons'
+import { daysIn, dayPeriods, fieldName, fmt, fmtTime, fromMinutes, hour12, isoOf, listKey, minutes, pad, readDate, readTime, uid, wallTimeIssue, type ChangeReason, type IsoDate, type IsoDateTime, type IsoTime, type SegmentPart, type TimeZoneId } from '@weft-js/warp-core'
+import { derived, flush, onMount, state, untrack } from '@weft-js/core'
+import { CalendarGrid } from './Calendar'
+import { Composite, Hidden, isSheet, messages, Panel, Trigger, bindable, useOpen, usePickerEnv, type Bindable, type Openable, type RichFieldProps } from './Picker'
+import { Segments, type SegmentState } from './Segments'
+import '@weft-js/warp-core/styles/rich/listbox.css'
+import '@weft-js/warp-core/styles/rich/datetime.css'
+
+/** The slot list (04 TimeField): a listbox with an active option, not a row of tab stops. */
+function Slots({ slots, selected, locale, hourCycle, label, onPick, meta }: { slots: string[]; selected: string | null; locale: string; hourCycle?: string | undefined; label: string; onPick: (t: string, r: ChangeReason) => void; meta?: boolean | undefined }) {
+  const id = uid('slots')
+  const near = () => Math.max(0, slots.findIndex(x => x >= (untrack(() => selected) ?? '09:00')))
+  const active = state(untrack(near))
+  let list: HTMLUListElement | undefined
+  const show = (block: ScrollLogicalPosition) => list?.querySelector<HTMLElement>('[data-active]')?.scrollIntoView?.({ block })
+  const onKey = (e: KeyboardEvent) => {
+    const m = listKey(e.key, active.value, slots.length)
+    if (!m.handled) return
+    e.preventDefault()
+    if (m.pick) return onPick(slots[active.value]!, 'keyboard')
+    active.value = m.to
+    flush()
+    show('nearest')
+  }
+  onMount(() => show('center'))
+  return (
+    <ul ref={n => (list = n)} data-part="listbox" role="listbox" tabindex="0" data-initial="" aria-label={label} aria-activedescendant={`${id}-${active.value}`} onKeyDown={onKey}>
+      {slots.map((x, n) => <Slot key={x} id={`${id}-${n}`} time={x} text={fmtTime(x, locale, hourCycle)} selected={x === selected} active={n === active.value} meta={meta} onPick={onPick} />)}
+    </ul>
+  )
+}
+const Slot = ({ id, time, text, selected, active, meta, onPick }: { id: string; time: string; text: string; selected: boolean; active: boolean; meta?: boolean | undefined; onPick: (t: string, r: ChangeReason) => void }) => (
+  <li role="option" id={id} aria-selected={selected ? 'true' : 'false'} data-active={active ? '' : undefined} onClick={() => onPick(time, 'pointer')}>{text}{meta && <span data-part="opt-meta">{time}</span>}</li>
+)
+
+/** The wheel sheet of a phone (04 §1.2): scroll-snap columns; arrows and presses work too. */
+function Wheels({ value, locale, hourCycle, onChange }: { value: string | null; locale: string; hourCycle?: 'h12' | 'h23' | 'auto' | undefined; onChange: (t: IsoTime) => void }) {
+  const h12 = untrack(() => hour12(locale, hourCycle))
+  const start = untrack(() => value) ?? '09:30'
+  const h0 = +start.slice(0, 2), m0 = Math.round(+start.slice(3, 5) / 5) * 5 % 60
+  const periods = untrack(() => dayPeriods(locale))
+  const cols = [
+    { key: 'hour', name: untrack(() => fieldName('hour', locale)), vals: h12 ? [12, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] : Array.from({ length: 24 }, (_, i) => i), cur: state(h12 ? h0 % 12 || 12 : h0), show: (v: number) => (h12 ? String(v) : pad(v)) },
+    { key: 'minute', name: untrack(() => fieldName('minute', locale)), vals: Array.from({ length: 12 }, (_, i) => i * 5), cur: state(m0), show: (v: number) => pad(v) },
+    ...(h12 ? [{ key: 'dayPeriod', name: untrack(() => fieldName('dayPeriod', locale)), vals: [0, 1], cur: state(h0 >= 12 ? 1 : 0), show: (v: number) => periods[v] }] : []),
+  ]
+  const commit = () => {
+    let h = cols[0]!.cur.value
+    if (h12) h = h % 12 + (cols[2]!.cur.value ? 12 : 0)
+    onChange(`${pad(h)}:${pad(cols[1]!.cur.value)}` as IsoTime)
+  }
+  return (
+    <div data-scope="wheels">
+      {cols.map(c => {
+        let list: HTMLUListElement | undefined
+        let timer: ReturnType<typeof setTimeout> | undefined
+        const row = () => (list!.firstElementChild as HTMLElement | null)?.getBoundingClientRect().height || 40
+        const select = (i: number, smooth: boolean) => {
+          i = Math.max(0, Math.min(c.vals.length - 1, i))
+          c.cur.value = c.vals[i]!
+          list?.scrollTo?.({ top: i * row(), behavior: smooth ? 'smooth' : 'instant' })
+          commit()
+        }
+        onMount(() => list?.scrollTo?.({ top: c.vals.indexOf(c.cur.value) * row(), behavior: 'instant' as ScrollBehavior }))
+        const onScroll = () => {
+          clearTimeout(timer)
+          timer = setTimeout(() => {
+            const i = Math.round(list!.scrollTop / row())
+            if (c.vals[i] !== undefined && c.vals[i] !== c.cur.value) { c.cur.value = c.vals[i]; commit() }
+          }, 90)
+        }
+        const onKey = (e: KeyboardEvent) => {
+          const d = ({ ArrowDown: 1, ArrowUp: -1 } as Record<string, number>)[e.key]
+          if (!d) return
+          e.preventDefault()
+          select(c.vals.indexOf(c.cur.value) + d, true)
+        }
+        return (
+          <ul key={c.key} ref={n => (list = n)} role="listbox" tabindex="0" aria-label={c.name} onScroll={onScroll} onKeyDown={onKey}>
+            {c.vals.map(v => <li key={v} role="option" aria-selected={c.cur.value === v ? 'true' : 'false'} onClick={() => select(c.vals.indexOf(v), true)}>{c.show(v)}</li>)}
+          </ul>
+        )
+      })}
+    </div>
+  )
+}
+
+export const stepSlots = (step: number, min?: string  , max?: string  ) => {
+  const from = min ? minutes(min) : 0, to = max ? minutes(max) : 1439
+  const out: string[] = []
+  for (let m = from; m <= to; m += step) out.push(fromMinutes(m))
+  return out
+}
+
+/** Props for TimeField. */
+export type TimeFieldProps = RichFieldProps & Bindable<IsoTime | null> & Openable & {
+  /** `h12` shows AM and PM, `h23` a 24-hour clock, `auto` the locale's. */
+  hourCycle?: 'h12' | 'h23' | 'auto' | undefined
+  step?: number | undefined
+  /** Adds a seconds segment. */
+  seconds?: boolean | undefined
+  min?: IsoTime | undefined
+  max?: IsoTime | undefined
+  slots?: IsoTime[] | undefined
+  /** Only for the DST hint. */
+  date?: IsoDate | undefined
+  timeZone?: TimeZoneId | undefined
+}
+
+/**
+ * TimeField (04 §2): segments in the locale's order and cycle; the trigger opens a slot list (wheels in a phone
+ * sheet). With `date` and `timeZone`, a wall time that doesn't exist or happens twice gets a hint, and a missing one
+ * resolves with `disambiguation: "compatible"`.
+ */
+export function TimeField({ value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, hourCycle, step = 15, seconds, min, max, slots, date, timeZone, locale, today, name, presentation, label, hint, error, disabled, readonly, ...rest }: TimeFieldProps) {
+  const env = usePickerEnv(() => locale, () => today)
+  const v = bindable<IsoTime | null>(() => value, () => defaultValue, null, () => onValueChange)
+  const pop = useOpen(() => open, () => defaultOpen, () => onOpenChange)
+  const started = state(false)
+  const sheet = state(false)
+  const t = derived(() => messages(env.locale.value))
+  const options = derived(() => slots ?? stepSlots(step, min, max))
+  let trigger: HTMLButtonElement | undefined
+  const dst = derived(() => {
+    if (!v.value || !date || !timeZone) return undefined
+    const issue = wallTimeIssue(date, v.value, timeZone)
+    if (!issue) return undefined
+    const day = fmt(date, { month: 'short', day: 'numeric' }, env.locale.value)
+    const city = timeZone.split('/').pop()!.replace(/_/g, ' ')
+    const at = fmtTime(v.value, env.locale.value, hourCycle)
+    return issue.kind === 'gap' ? `${at} doesn't exist on ${day} in ${city}; using ${fmtTime(issue.resolved, env.locale.value, hourCycle)}.` : `${at} happens twice on ${day} in ${city}; using the first.`
+  })
+  const onEdit = (st: SegmentState, parts: SegmentPart[]) => {
+    started.value = st !== 'empty'
+    if (st === 'empty') return v.set(null, 'keyboard')
+    if (st === 'complete') { const x = readTime(parts); if (x) v.set(x, 'keyboard') }
+  }
+  const open_ = () => { sheet.value = isSheet(trigger!, presentation); pop.set(true) }
+  return (
+    <Composite
+      {...rest}
+      label={label}
+      hint={dst.value ?? hint}
+      error={error}
+      disabled={disabled}
+      readonly={readonly}
+      bound={v}
+      onReset={() => (started.value = false)}
+      filled={v.value !== null || started.value}
+      hold={pop.value}
+      control={() => (
+        <>
+          <Segments required={rest.required} kind="time" options={{ hourCycle, seconds }} locale={env.locale.value} value={v.value} today={env.today.value} disabled={disabled} readonly={readonly} onEdit={onEdit} />
+          <Trigger el={(n: HTMLButtonElement) => (trigger = n)} icon={ClockIcon} label={t.value.chooseTime + (v.value ? `, ${fmtTime(v.value, env.locale.value, hourCycle)}` : '')} open={pop.value} disabled={disabled} onToggle={() => (pop.value ? pop.set(false) : open_())} />
+          <Hidden name={name} value={() => v.value ?? ''} />
+        </>
+      )}
+      end={
+        <Panel label={t.value.chooseTime} open={pop} trigger={() => trigger!} presentation={presentation} align="end">
+          {() => (sheet.value
+            ? <Wheels value={v.value} locale={env.locale.value} hourCycle={hourCycle} onChange={x => v.set(x, 'pointer')} />
+            : <Slots slots={options.value} selected={v.value} locale={env.locale.value} hourCycle={hourCycle} label={t.value.chooseTime} meta onPick={(x, r) => { v.set(x as IsoTime, r); pop.set(false) }} />)}
+        </Panel>
+      }
+    />
+  )
+}
+
+/** Props for DateTimeField. */
+export type DateTimeFieldProps = RichFieldProps & Bindable<IsoDateTime | null> & Openable & {
+  min?: IsoDate | undefined
+  max?: IsoDate | undefined
+  /** Return true for a day that can't be picked: it shows struck through. */
+  isDateUnavailable?: ((d: IsoDate) => boolean) | undefined
+  /** The day each calendar row starts on, 0 for Sunday to 6. The locale's otherwise. */
+  firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
+  step?: number | undefined
+}
+
+/**
+ * DateTimeField (04 §2): a date group and a time group in one control and one popover, calendar beside the slot list.
+ * The value is a wall time with no zone; the hint spells it out in full.
+ */
+export function DateTimeField({ value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, min, max, isDateUnavailable, firstDayOfWeek, step = 30, locale, today, name, presentation, label, hint, error, disabled, readonly, ...rest }: DateTimeFieldProps) {
+  const env = usePickerEnv(() => locale, () => today)
+  const v = bindable<IsoDateTime | null>(() => value, () => defaultValue, null, () => onValueChange)
+  const pop = useOpen(() => open, () => defaultOpen, () => onOpenChange)
+  const date = state<string | null>(untrack(() => v.value?.slice(0, 10) ?? null))
+  const time = state<string | null>(untrack(() => v.value?.slice(11) ?? null))
+  let trigger: HTMLButtonElement | undefined
+  const emit = (r: ChangeReason) => v.set(date.value && time.value ? `${date.value}T${time.value}` as IsoDateTime : null, r)
+  const said = derived(() => (v.value ? `${fmt(v.value, { dateStyle: 'full', timeStyle: 'short' }, env.locale.value)} · wall clock, no zone` : hint))
+  const onDate = (st: SegmentState, parts: SegmentPart[]) => {
+    const d = readDate(parts)
+    date.value = st === 'complete' && d.day! <= daysIn(d.year!, d.month!) ? isoOf(d) : null
+    emit('keyboard')
+  }
+  const onTime = (st: SegmentState, parts: SegmentPart[]) => { time.value = st === 'complete' ? readTime(parts) : null; emit('keyboard') }
+  return (
+    <Composite
+      {...rest}
+      label={label}
+      hint={said.value}
+      error={error}
+      disabled={disabled}
+      readonly={readonly}
+      bound={v}
+      onReset={() => { date.value = v.value?.slice(0, 10) ?? null; time.value = v.value?.slice(11) ?? null }}
+      filled={!!(date.value || time.value)}
+      hold={pop.value}
+      control={() => (
+        <>
+          <Segments required={rest.required} kind="date" label="Date" locale={env.locale.value} value={date.value} today={env.today.value} disabled={disabled} readonly={readonly} onEdit={onDate} />
+          <span data-part="literal" class="dt-sep" aria-hidden="true">·</span>
+          <Segments required={rest.required} kind="time" label="Time" locale={env.locale.value} value={time.value} today={env.today.value} disabled={disabled} readonly={readonly} onEdit={onTime} />
+          <Trigger el={(n: HTMLButtonElement) => (trigger = n)} icon={CalendarIcon} label="Choose date and time" open={pop.value} disabled={disabled} onToggle={() => pop.set(!pop.value)} />
+          <Hidden name={name} value={() => v.value ?? ''} />
+        </>
+      )}
+      end={
+        <Panel label="Choose date and time" open={pop} trigger={() => trigger!} presentation={presentation}>
+          {() => (
+            <div class="dt-pop">
+              <CalendarGrid mode="single" value={() => date.value as IsoDate | null} locale={env.locale.value} today={env.today.value} min={min} max={max} isDateUnavailable={isDateUnavailable} firstDayOfWeek={firstDayOfWeek} autofocus onPick={(iso, r) => { date.value = iso; emit(r) }} />
+              <div class="dt-side">
+                <p class="dt-cap">Time</p>
+                <Slots slots={stepSlots(step)} selected={time.value} locale={env.locale.value} label="Time" onPick={(x, r) => { time.value = x; emit(r); pop.set(false) }} />
+              </div>
+            </div>
+          )}
+        </Panel>
+      }
+    />
+  )
+}
+

package/src/Toast.tsx

@@ -0,0 +1,56 @@
+import { XIcon } from '@weft-js/warp-icons'
+import { toaster, toastStore, type Toast, type ToastInput, type ToastPromise } from '@weft-js/warp-core'
+import { onCleanup, state } from '@weft-js/core'
+import { Icon, toneIcon } from './Icon'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/components/button.css' // the action and dismiss buttons' markup
+import '@weft-js/warp-core/styles/components/spinner.css'
+import '@weft-js/warp-core/styles/components/toast.css'
+
+let store: ReturnType<typeof toastStore> | undefined
+const toasts = () => (store ??= toastStore())
+
+/**
+ * Show a toast from anywhere (05 §5): `toast.show({ title, description, tone, action })`. Needs one <Toaster />.
+ * Life is 5s + 60ms a word, 10s with an action; a critical toast with an action stays until dismissed.
+ */
+export const toast = {
+  show: (t: ToastInput) => toasts().show(t),
+  dismiss: (id: string) => toasts().dismiss(id),
+  /** One toast through a promise's life: `pending`, then `done` or `error`, in place. Returns the promise. */
+  promise: <T,>(p: Promise<T>, messages: ToastPromise<T>) => toasts().promise(p, messages),
+}
+
+/**
+ * The toast region and the two pre-mounted live regions (05 §5; components.html:1115-1117). Mount once, near the
+ * root. While a modal is open they move into it, or it would make them inert. Newest first; three stack, collapsed, and fan out on hover or focus (which pauses every timer); swipe or
+ * Dismiss removes one; F8 focuses the newest.
+ */
+export function Toaster({ position }: { /** Which corner or edge. Bottom right by default. */ position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' } = {}) {
+  const list = state<Toast[]>(toasts().get())
+  onCleanup(toasts().subscribe(v => (list.value = v)))
+  let region: HTMLElement | undefined
+  use(toaster, () => region, () => toasts())
+  return (
+    <>
+      <section ref={n => (region = n)} data-scope="toast" data-part="region" data-position={position === 'bottom-right' ? undefined : position} aria-label="Notifications (F8)" tabindex="-1">
+        {list.value.map(t => (
+          <div key={t.id} data-scope="toast" data-part="root" data-id={t.id} data-tone={t.tone ?? 'neutral'} data-state={t.state} role="group" aria-label={t.title}>
+            {t.loading ? <span data-scope="spinner" data-part="icon" aria-hidden="true"></span> : <Icon name={toneIcon[t.tone ?? 'neutral']} data-part="icon" />}
+            <div data-part="title">{t.title}</div>
+            {t.description && <div data-part="description">{t.description}</div>}
+            <div data-part="actions">
+              {/* ghost <Button>s as their markup: they need no JS */}
+              {t.action && <button type="button" data-scope="button" data-emphasis="ghost" data-size="sm" data-act="" onClick={() => { t.action!.onClick(); toast.dismiss(t.id) }}>{t.action.label}</button>}
+              <button type="button" data-scope="button" data-emphasis="ghost" data-tone="neutral" data-size="sm" data-icon-only="" aria-label="Dismiss" data-x="" onClick={() => toast.dismiss(t.id)}><XIcon /></button>
+            </div>
+            {t.life > 0 && <span data-part="progress" aria-hidden="true"></span>}
+          </div>
+        ))}
+      </section>
+      <div data-scope="announcer" role="status" aria-live="polite" aria-atomic="true"></div>
+      <div data-scope="announcer" role="alert" aria-live="assertive" aria-atomic="true"></div>
+    </>
+  )
+}

package/src/Toggle.tsx

@@ -0,0 +1,42 @@
+import { derived } from '@weft-js/core'
+import type { Interaction } from '@weft-js/core/interaction'
+import { Icon, type IconRef } from './Icon'
+import { useUi } from './use-ui'
+import './styles'
+import '@weft-js/warp-core/styles/components/toggle-button.css'
+import '@weft-js/warp-core/styles/components/chip.css' // the pressed toggle's forced-colours rule lives with the chip
+
+/** Props for Toggle. */
+export type ToggleProps = {
+  ref?: ((el: HTMLButtonElement) => void) | undefined
+  onClick?: ((e: MouseEvent) => void) | undefined
+  /** Called as the pointer comes over the button. */
+  onPointerEnter?: ((e: PointerEvent) => void) | undefined
+  pressed: boolean
+  icon?: IconRef | undefined
+  label?: string | undefined
+  size?: 'sm' | 'md' | 'lg' | undefined
+  ui?: Interaction
+  children?: unknown
+  [attr: string]: unknown
+}
+
+/** A toggle button (05 §2): `aria-pressed`, the sweep held while pressed. */
+export function Toggle({ pressed, icon, label, size, ui, ref, children, onClick, onPointerEnter, ...rest }: ToggleProps) {
+  let host: HTMLButtonElement | undefined
+  useUi(() => ui, () => host)
+  const glyph = derived(() => icon)
+  // Released from pressed, the fill goes at once; the held stroke goes with it when the pointer and focus leave, so it
+  // doesn't retract across the face as a stray bracket. A plain hover keeps the sweep's own exit.
+  const click = (e: MouseEvent) => {
+    if (host?.getAttribute('aria-pressed') === 'true') host.dataset.released = ''
+    else delete host?.dataset.released
+    onClick?.(e)
+  }
+  const enter = (e: PointerEvent) => { if (host?.getAttribute('aria-pressed') !== 'true') delete host?.dataset.released; onPointerEnter?.(e) }
+  return (
+    <button type="button" data-scope="toggle" aria-pressed={pressed ? 'true' : 'false'} aria-label={label} data-size={size === 'md' ? undefined : size} data-sweep="" {...rest} onClick={click} onPointerEnter={enter} ref={n => { host = n; ref?.(n) }}>
+      {glyph.value && <Icon name={glyph.value} />}{children}<span data-part="sweep" aria-hidden="true"></span>
+    </button>
+  )
+}

package/src/Tooltip.tsx

@@ -0,0 +1,32 @@
+import { tooltip, uid, type Align, type Side } from '@weft-js/warp-core'
+import { untrack } from '@weft-js/core'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/components/tooltip.css'
+
+/**
+ * A hint on hover and keyboard focus, never essential (05 §3, §10 H1): `children` is the trigger (one focusable
+ * element); the tip follows it in the DOM as a manual popover in the top layer. The trigger is described by the tip
+ * unless its accessible name already says the same words (an icon button named "Settings" with tip "Settings").
+ * `inline` draws the tip shown, under its trigger in the page's flow, for docs and previews: no top layer, no hover wait.
+ */
+export function Tooltip({ content, kbd, side, align, inline, children }: { content: string; kbd?: string; side?: Side; align?: Align; /** Shown under the trigger, in the page's flow: no top layer or hover wait. For docs and previews. */ inline?: boolean; children: unknown }) {
+  const id = uid('tip')
+  const flat = untrack(() => !!inline)
+  let tip: HTMLDivElement | undefined
+  // the trigger is the element before the tip; it is described by the tip unless its name already says the same
+  const attach = (el: HTMLElement, o: { side?: Side | undefined; align?: Align | undefined }) => {
+    const trigger = el.previousElementSibling as HTMLElement
+    if (trigger.getAttribute('aria-label') !== el.textContent) trigger.setAttribute('aria-describedby', [trigger.getAttribute('aria-describedby'), id].filter(Boolean).join(' '))
+    if (flat) return { update() {}, destroy() {} } // shown in flow: nothing to place, open or close
+    const action = tooltip(el, { trigger, side: o.side, align: o.align })
+    return { update: (n: { side?: Side | undefined; align?: Align | undefined }) => action.update({ trigger, side: n.side, align: n.align }), destroy: () => action.destroy() }
+  }
+  use(attach, () => tip, () => ({ side, align }))
+  return (
+    <>
+      {children}
+      <div ref={n => (tip = n)} data-scope="tooltip" data-part="content" role="tooltip" popover={flat ? undefined : 'manual'} data-presentation={flat ? 'inline' : undefined} id={id}>{content}{kbd && <kbd>{kbd}</kbd>}</div>
+    </>
+  )
+}

package/src/Type.tsx

@@ -0,0 +1,46 @@
+// Type by role (01 §2, PLAN §6): the spec defines the roles as tokens and leaves the element to the app, so these
+// are what an app reads them through. A size, weight or colour is never a prop.
+import { untrack } from '@weft-js/core'
+import type { TextRole, Tone } from '@weft-js/core/ds'
+import './styles'
+import '@weft-js/warp-core/styles/components/link.css'
+import './type.css'
+
+type Open = { children?: unknown; [attr: string]: unknown }
+
+type HeadingRole = 'display' | 'title' | 'heading' | 'label'
+
+/** The role each level takes by default, so a page's `h1` is one size everywhere (`weft check` keeps the same table: D006). */
+const ROLE: Record<number, HeadingRole> = { 1: 'title', 2: 'heading', 3: 'heading', 4: 'label', 5: 'label', 6: 'label' }
+
+/**
+ * A real heading: `level` is the document outline (default 2) and picks the role: `title` for h1, `heading` for h2 and
+ * h3, `label` below. `role` overrides the look, so the two can differ, and `weft check` flags a level that renders at
+ * two roles in one app (D006). It follows `level` for skips too (D035).
+ */
+export function Heading({ level = 2, role, children, ...rest }: Open & { level?: 1 | 2 | 3 | 4 | 5 | 6 | undefined; role?: HeadingRole | undefined }) {
+  const n = untrack(() => level)
+  const look = () => role ?? ROLE[n]
+  if (n === 1) return <h1 data-scope="text" data-role={look()} {...rest}>{children}</h1>
+  if (n === 2) return <h2 data-scope="text" data-role={look()} {...rest}>{children}</h2>
+  if (n === 3) return <h3 data-scope="text" data-role={look()} {...rest}>{children}</h3>
+  if (n === 4) return <h4 data-scope="text" data-role={look()} {...rest}>{children}</h4>
+  if (n === 5) return <h5 data-scope="text" data-role={look()} {...rest}>{children}</h5>
+  return <h6 data-scope="text" data-role={look()} {...rest}>{children}</h6>
+}
+
+/** Text in a role. A paragraph by default; `inline` makes it a span. `tone` colours it, `subtle` and `faint` quieten it. */
+export function Text({ role, tone, subtle, faint, inline, children, ...rest }: Open & { role?: TextRole; tone?: Tone | undefined; subtle?: boolean; faint?: boolean; inline?: boolean }) {
+  const ink = () => (subtle ? 'subtle' : faint ? 'faint' : undefined)
+  if (untrack(() => inline)) return <span data-scope="text" data-role={role} data-tone={tone} data-ink={ink()} {...rest}>{children}</span>
+  return <p data-scope="text" data-role={role} data-tone={tone} data-ink={ink()} {...rest}>{children}</p>
+}
+
+/**
+ * A link (05 §4): underlined, with the underline sweep. `subtle` takes the surrounding ink, and `external` opens a new
+ * tab and says so. A bare `<a>` gets warp's colour from the base layer; this adds the rest, and D007 points to it.
+ */
+export function Link({ href, subtle, external, children, ...rest }: Open & { href: string; subtle?: boolean | undefined; external?: boolean | undefined }) {
+  if (untrack(() => external)) return <a data-scope="link" data-variant={subtle ? 'subtle' : undefined} href={href} target="_blank" rel="noopener noreferrer" {...rest}>{children}<span class="vh"> (opens in a new tab)</span></a>
+  return <a data-scope="link" data-variant={subtle ? 'subtle' : undefined} href={href} {...rest}>{children}</a>
+}