@weft-js/warp 0.0.0-stage → 0.1.0

package/src/Button.tsx

@@ -0,0 +1,100 @@
+import { derived } from '@weft-js/core'
+import type { Interaction } from '@weft-js/core/interaction'
+import { pressOrigin } from '@weft-js/warp-core'
+import { Icon, type IconRef } from './Icon'
+import { useUi } from './use-ui'
+import './styles'
+import '@weft-js/warp-core/styles/components/button.css'
+import '@weft-js/warp-core/styles/components/spinner.css'
+
+/** The colour role a control speaks in. */
+export type Tone = 'neutral' | 'accent' | 'positive' | 'caution' | 'critical' | 'info'
+/** How much weight a control carries, from solid down to a plain link. */
+export type Emphasis = 'solid' | 'soft' | 'outline' | 'ghost' | 'frame' | 'link'
+
+/** Props for Button; anything else lands on the <button>. */
+export interface ButtonProps {
+  /** solid (default) · soft · outline · ghost · frame (the signature) · link. Fixed at creation: it picks the anatomy. */
+  emphasis?: Emphasis | undefined
+  tone?: Tone | undefined
+  size?: 'sm' | 'md' | 'lg' | undefined
+  /** A frame button with the solid fill sweeping in. */
+  fill?: boolean
+  /** At vivid the fill spreads from where the pointer arrives and parts back out, instead of wiping in from the left. Not on frame or link. */
+  follow?: boolean
+  full?: boolean
+  /** Icon only: `label` is then required (it is the accessible name). */
+  icon?: IconRef | undefined
+  /** With `icon` and text: on a phone (or a tablet and a phone) only the icon shows, and the text stays the accessible name. */
+  collapse?: 'phone' | 'tablet' | undefined
+  ref?: ((el: HTMLButtonElement) => unknown) | undefined
+  onClick?: ((e: MouseEvent) => unknown) | undefined
+  label?: string | undefined
+  /** Busy: the label stays the accessible name (hidden by opacity), presses are swallowed, focus stays. */
+  loading?: boolean | undefined
+  /** `interaction()`'s row: real events fill it, and it draws whoever set it. */
+  ui?: Interaction
+  children?: unknown
+  [attr: string]: unknown
+}
+
+const swept = (e: Emphasis) => e !== 'link'
+
+/**
+ * A native button (05 §2): all but link and frame append one [data-part="sweep"], and ::before paints the fill (the wipe,
+ * or with `follow` at vivid the two blobs that close on where the hand arrived); frame carries the six-part signature anatomy (SIGNATURE §1b).
+ */
+export function Button({ emphasis = 'solid', tone, size, fill, follow, full, icon, collapse, label, loading, type = 'button', onClick, ui, ref, children, ...rest }: ButtonProps) {
+  pressOrigin()   // one listener for the page; it only moves buttons that ask to follow
+  let host: HTMLButtonElement | undefined
+  useUi(() => ui, () => host)
+  const canLoad = derived(() => loading !== undefined)
+  const glyph = derived(() => icon)
+  // a loading or aria-disabled button swallows presses (components.html guard())
+  const press = (e: MouseEvent) => {
+    const el = e.currentTarget as HTMLElement
+    if (el.hasAttribute('data-loading') || el.getAttribute('aria-disabled') === 'true') return e.preventDefault()
+    onClick?.(e)
+  }
+  const content = () => <>{glyph.value && <Icon name={glyph.value} />}{collapse && glyph.value && children ? <span data-part="collapse">{children}</span> : children}</>
+  return (
+    <button
+      type={type}
+      data-scope="button"
+      data-emphasis={emphasis === 'solid' ? undefined : emphasis}
+      data-tone={tone}
+      data-size={size === 'md' ? undefined : size}
+      data-fill={emphasis === 'frame' && fill ? '' : undefined}
+      data-follow={follow && emphasis !== 'frame' && emphasis !== 'link' ? '' : undefined}
+      data-full={full ? '' : undefined}
+      data-icon-only={glyph.value && !children ? '' : undefined}
+      data-collapse={glyph.value && children ? collapse : undefined}
+      aria-label={label}
+      data-sweep={swept(emphasis) ? '' : undefined}
+     
+      data-loading={loading ? '' : undefined}
+      aria-busy={loading ? 'true' : undefined}
+      aria-disabled={loading ? 'true' : undefined}
+      onClick={press}
+      {...rest}
+      ref={n => { host = n; ref?.(n) }}
+    >
+      {emphasis === 'frame' ? (
+        <>
+          {fill && <span data-part="sweep-fill" aria-hidden="true"></span>}
+          <span data-part="frame-corners" aria-hidden="true"><i></i><i></i><i></i><i></i></span>
+          <span data-part="sweep-corners" aria-hidden="true"><i></i><i></i><i></i><i></i></span>
+          <span data-part="sweep-outline" aria-hidden="true"><i></i><i></i><i></i><i></i><i></i><i></i></span>
+          <span data-part="sweep-label">{content()}</span>
+          <span data-part="sweep-content" aria-hidden="true">{content()}</span>
+        </>
+      ) : canLoad.value ? (
+        <span data-part="label">{content()}</span>
+      ) : (
+        content()
+      )}
+      {loading && <span data-scope="spinner" data-part="spinner" aria-hidden="true"></span>}
+      {emphasis !== 'frame' && emphasis !== 'link' && <span data-part="sweep" aria-hidden="true"></span>}
+    </button>
+  )
+}

package/src/Calendar.tsx

@@ -0,0 +1,162 @@
+import { LeftIcon, RightIcon } from '@weft-js/warp-icons'
+import { addMonths, dayState, fmt, gridKey, isoWeek, isWeekend, isUnavailable, messages, monthEnd, monthStart, monthWeeks, ymd, weekStart, weekdays, type CalendarContext, type CalendarMode, type CalendarValue, type ChangeReason, type DateRange, type IsoDate } from '@weft-js/warp-core'
+import { derived, flush, state, untrack, watch } from '@weft-js/core'
+import { Button } from './Button'
+import { bindable, uid, usePickerEnv, type Bindable } from './Picker'
+import './styles'
+import '@weft-js/warp-core/styles/rich/calendar-grid.css'
+
+export interface GridProps {
+  mode: CalendarMode
+  months?: number
+  value: () => CalendarValue
+  compare?: () => DateRange | null | undefined
+  locale: string
+  today: string
+  min?: string | undefined
+  max?: string | undefined
+  isDateUnavailable?: ((d: IsoDate) => boolean) | undefined
+  firstDayOfWeek?: number | undefined
+  weekNumbers?: boolean | undefined
+  /** Marks the focused day `data-initial`, so a panel opens onto it. */
+  autofocus?: boolean
+  onPick: (iso: IsoDate, reason: ChangeReason) => void
+  onHover?: (iso: IsoDate | null) => void
+  onUnavailable?: (iso: IsoDate) => void
+  /** A cursor from outside (a preset moved the months). */
+  goTo?: () => string | null | undefined
+  children?: unknown
+}
+
+const startOf = (v: CalendarValue, today: string, mode: CalendarMode) => (mode === 'range' ? (v as DateRange)?.start : mode === 'multiple' ? [...((v as IsoDate[]) ?? [])].sort()[0] : mode === 'week' ? null : (v as string | null)) ?? today
+
+/**
+ * The APG date grid (04 §1.4): one table per month, one tab stop on the cursor's day. Blank cells stand for days of
+ * other months. A day is never named "14" alone: every button carries the full date and its state.
+ */
+export function CalendarGrid(p: GridProps) {
+  const firstDay = derived(() => p.firstDayOfWeek ?? weekStart(p.locale))
+  const count = () => p.months ?? 1
+  const cursor = state(untrack(() => startOf(p.value(), p.today, p.mode)))
+  const view = state(monthStart(untrack(() => cursor.value)))
+  const hover = state<string | null>(null)
+  const anim = state<'next' | 'prev' | undefined>(undefined)
+  let box: HTMLDivElement | undefined
+  const shown = derived(() => Array.from({ length: count() }, (_, n) => ({ month: addMonths(view.value, n) })))
+  const heads = derived(() => weekdays(firstDay.value, p.locale))
+  const t = derived(() => messages(p.locale))
+  const context = (): CalendarContext => ({ mode: p.mode, value: p.value(), compare: p.compare?.(), today: p.today, locale: p.locale, hover: hover.value, min: p.min, max: p.max, isDateUnavailable: p.isDateUnavailable })
+  const lastDay = () => monthEnd(addMonths(view.value, count() - 1))
+  const moveTo = (iso: string) => {
+    if (iso < view.value) { anim.value = 'prev'; view.value = monthStart(iso) }
+    else if (iso > lastDay()) { anim.value = 'next'; view.value = monthStart(addMonths(iso, -(count() - 1))) }
+    cursor.value = iso
+  }
+  const focusCursor = () => { flush(); box?.querySelector<HTMLElement>('[data-part="day"][tabindex="0"]')?.focus() }
+  const pick = (iso: string, reason: ChangeReason) => {
+    if (isUnavailable(iso, context())) return p.onUnavailable?.(iso as IsoDate)
+    cursor.value = iso
+    hover.value = null
+    p.onPick(iso as IsoDate, reason)
+  }
+  const onKey = (e: KeyboardEvent) => {
+    if (!(e.target as Element).closest?.('[data-part="day"]')) return
+    const to = gridKey(e.key, e.shiftKey, cursor.value, firstDay.value, getComputedStyle(box!).direction === 'rtl')
+    if (!to) return
+    e.preventDefault()
+    if (to === 'pick') return pick(cursor.value, 'keyboard')
+    if (p.mode === 'range') hover.value = to
+    moveTo(to)
+    focusCursor()
+  }
+  const onClick = (e: MouseEvent) => {
+    const b = (e.target as Element).closest?.<HTMLElement>('[data-part="day"]')
+    if (b) pick(b.dataset.date!, 'pointer')
+  }
+  const onOver = (e: PointerEvent) => {
+    const b = (e.target as Element).closest?.<HTMLElement>('[data-part="day"]')
+    if (p.mode !== 'range' || !b || hover.value === b.dataset.date) return
+    hover.value = b.dataset.date!
+    p.onHover?.(hover.value as IsoDate)
+  }
+  const onLeave = () => { if (p.mode === 'range') { hover.value = null; p.onHover?.(null) } }
+  const page = (d: number) => { anim.value = d > 0 ? 'next' : 'prev'; view.value = addMonths(view.value, d); cursor.value = addMonths(cursor.value, d) }
+  watch(() => p.goTo?.(), iso => { if (iso) moveTo(iso) })
+  return (
+    <div ref={n => (box = n)} data-scope="calendar" data-part="root">
+      <Button emphasis="ghost" size="sm" icon={LeftIcon} label={t.value.prev} data-part="nav" data-dir="prev" data-icon="" onClick={() => page(-1)} />
+      <Button emphasis="ghost" size="sm" icon={RightIcon} label={t.value.next} data-part="nav" data-dir="next" data-icon="" onClick={() => page(1)} />
+      <div data-part="months" data-anim={anim.value} onKeyDown={onKey} onClick={onClick} onPointerOver={onOver} onPointerLeave={onLeave}>
+        {shown.value.map(m => <Month key={m.month} month={m.month} heads={heads.value} first={firstDay.value} weekNumbers={p.weekNumbers} locale={p.locale} wholeWeek={p.mode === 'week'} ctx={context} cursor={cursor.value} initial={p.autofocus} />)}
+      </div>
+      {p.children}
+    </div>
+  )
+}
+
+function Month({ month, heads, first, weekNumbers, locale, wholeWeek, ctx, cursor, initial }: { month: string; heads: readonly (readonly [string, string, number])[]; first: number; weekNumbers?: boolean | undefined; locale: string; wholeWeek: boolean; ctx: () => CalendarContext; cursor: string; initial?: boolean | undefined }) {
+  const cap = uid('cap')
+  const weeks = derived(() => monthWeeks(month, first).map(days => ({ days: days.map((iso, c) => ({ iso, k: iso ?? `b${c}`, weekday: (first + c) % 7 })), k: days.find(Boolean)!, week: isoWeek(days.find(Boolean)!).week })))
+  return (
+    <div data-part="month">
+      <div data-part="caption" id={cap} aria-live="polite">{fmt(month, { month: 'long', year: 'numeric' }, locale)}</div>
+      <table role="grid" aria-labelledby={cap}>
+        <thead>
+          <tr>
+            {weekNumbers && <th scope="col" abbr={messages(locale).week}><span class="sr">{messages(locale).week}</span></th>}
+            {heads.map(h => <th key={h[0]} scope="col" abbr={h[0]}>{h[1]}</th>)}
+          </tr>
+        </thead>
+        <tbody>
+          {weeks.value.map(w => (
+            <tr key={w.k}>
+              {weekNumbers && <th scope="row" data-part="week">{w.week}</th>}
+              {w.days.map(d => (d.iso ? <Day key={d.k} iso={d.iso} weekend={isWeekend(d.weekday, locale)} locale={locale} wholeWeek={wholeWeek} ctx={ctx} cursor={cursor} initial={initial} /> : <td key={d.k} role="gridcell"></td>))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+
+function Day({ iso, weekend, locale, ctx, cursor, initial }: { iso: IsoDate; weekend: boolean; locale: string; wholeWeek: boolean; ctx: () => CalendarContext; cursor: string; initial?: boolean | undefined }) {
+  const s = derived(() => dayState(iso, ctx()))
+  const n = derived(() => new Intl.NumberFormat(locale).format(ymd(iso)[2]))
+  return (
+    <td role="gridcell" aria-selected={s.value.cellSelected ? 'true' : 'false'} data-range={s.value.range} data-preview={s.value.preview ? '' : undefined} data-compare={s.value.compare ? '' : undefined}>
+      <button type="button" data-part="day" data-date={iso} tabindex={iso === cursor ? '0' : '-1'} data-initial={initial && iso === cursor ? '' : undefined} data-weekend={weekend ? '' : undefined} data-selected={s.value.selected ? '' : undefined} data-booked={s.value.unavailable && s.value.booked ? '' : undefined} aria-current={s.value.today ? 'date' : undefined} aria-disabled={s.value.unavailable ? 'true' : undefined} aria-label={s.value.name}>{n.value}</button>
+    </td>
+  )
+}
+
+export type InlineCalendarValue = IsoDate | IsoDate[] | DateRange | null
+
+/**
+ * InlineCalendar (04 §2): the same grid, standalone, for availability and booking. 1–3 months; `single`, `multiple`
+ * (toggles days, announces the count) or `range`. No field shell: `aria-label` names it.
+ */
+export function InlineCalendar({ selection = 'single', months = 1, value, defaultValue, onValueChange, min, max, isDateUnavailable, firstDayOfWeek, weekNumbers, locale, today, ...rest }: Bindable<InlineCalendarValue> & { selection?: 'single' | 'multiple' | 'range'; months?: 1 | 2 | 3; min?: string | undefined; max?: string | undefined; isDateUnavailable?: ((d: IsoDate) => boolean) | undefined; firstDayOfWeek?: number | undefined; weekNumbers?: boolean | undefined; locale?: string | undefined; today?: string | undefined; 'aria-label': string }) {
+  const env = usePickerEnv(() => locale, () => today)
+  const empty = (): InlineCalendarValue => (selection === 'multiple' ? [] : selection === 'range' ? { start: null, end: null } : null)
+  const v = bindable<InlineCalendarValue>(() => value, () => defaultValue, untrack(empty), () => onValueChange)
+  const said = state('')
+  const onPick = (iso: IsoDate, reason: ChangeReason) => {
+    if (selection === 'single') return v.set(iso, reason)
+    if (selection === 'multiple') {
+      const now = (v.value as IsoDate[]) ?? []
+      const next = now.includes(iso) ? now.filter(d => d !== iso) : [...now, iso]
+      v.set(next, reason)
+      said.value = next.length === 1 ? '1 day selected' : `${next.length} days selected`
+      return
+    }
+    const r = v.value as DateRange
+    v.set(!r?.start || r.end ? { start: iso, end: null } : iso < r.start ? { start: iso, end: r.start } : { start: r.start, end: iso }, reason)
+  }
+  return (
+    <div role="group" {...rest}>
+      <CalendarGrid mode={selection} months={months} value={() => v.value} locale={env.locale.value} today={env.today.value} min={min} max={max} isDateUnavailable={isDateUnavailable} firstDayOfWeek={firstDayOfWeek} weekNumbers={weekNumbers} onPick={onPick} />
+      <span class="sr" role="status">{said.value}</span>
+    </div>
+  )
+}

package/src/Canvas.tsx

@@ -0,0 +1,110 @@
+import { surface, type Frame, type SurfaceOptions } from '@weft-js/warp-core/canvas'
+import { state, untrack } from '@weft-js/core'
+import { uid } from '@weft-js/warp-core'
+import { floatStage, stage, stageSelect, type StageOptions } from '@weft-js/warp-core/stage'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/canvas/canvas.css'
+import '@weft-js/warp-core/styles/canvas/stage.css'
+
+export type { Frame, Pointer } from '@weft-js/warp-core/canvas'
+export type { Piece as StagePiece, Press, Scene, Scroll, StageLayout, StagePainter, Word } from '@weft-js/warp-core/stage'
+
+/** Props for Canvas. */
+export interface CanvasProps {
+  /** Paints one frame: `ctx` is already scaled to CSS pixels. Return true to be called again without `animate`. */
+  draw: (frame: Frame) => boolean | void
+  /** Moves at balanced and vivid. Quiet and reduced motion paint one frame, with `still` set. */
+  animate?: boolean
+  /** Caps the frame rate while it animates. Uncapped by default, at the display's rate. */
+  fps?: number
+  /** Whole-cell mode: `width` and `height` count cells of this many CSS pixels, scaled up without smoothing. */
+  cell?: number
+  /** Settings for the 2D context, such as `{ alpha: false }`. Read once, when the canvas attaches. */
+  context?: SurfaceOptions['context']
+  /** Called before the repaint when a theme, tier or motion dial changes around the canvas. Read colours again here. */
+  onTheme?: () => void
+  /** Track the pointer into `frame.pointer`, and repaint when it moves over the canvas. */
+  pointer?: boolean
+  /** Names the drawing (role="img"). Without one it is decorative. */
+  label?: string | undefined
+  [attr: string]: unknown
+}
+
+/** A canvas that handles pixel ratio, resize, off-screen and reduced motion, for anything warp doesn't draw itself (08 §6.7). */
+export function Canvas({ draw, animate, fps, cell, context, onTheme, pointer, label, ...rest }: CanvasProps) {
+  let node: HTMLCanvasElement | undefined
+  use(surface, () => node, () => ({ draw, animate, fps, cell, context, onTheme, pointer }))
+  return <div {...rest} data-scope="canvas"><canvas ref={n => (node = n)} role={label ? 'img' : undefined} aria-label={label} aria-hidden={label ? undefined : 'true'}></canvas></div>
+}
+
+/** Props for CanvasStage. */
+export interface CanvasStageProps extends StageOptions {
+  /** `box` paints its own block; `scroll` is a scroller whose view it paints; `page` paints the viewport, for a whole page. */
+  layout?: StageOptions['layout']
+  /** A modal's stage: the dialog spans the viewport and the stage centres its panel. */
+  veil?: boolean | undefined
+  children?: unknown
+  [attr: string]: unknown
+}
+
+/**
+ * A canvas that paints the page laid out inside it (08 §6.8). Mark any element `data-skin="button"`, `card`, or a name of
+ * your own: it keeps its layout, focus, typing and semantics, and your painters draw it with a 2D context, states and all.
+ */
+export function CanvasStage({ layout = 'box', painters, background, overlay, paint, animate, cell, fps, rail, context, onTheme, veil, children, ...rest }: CanvasStageProps) {
+  let node: HTMLCanvasElement | undefined
+  use(stage, () => node, () => ({ layout, painters, background, overlay, paint, animate, cell, fps, rail, context, onTheme }))
+  return (
+    <div {...rest} data-scope="stage" data-layout={layout} data-rail={rail ? '' : undefined} data-veil={veil ? '' : undefined}>
+      <div data-part="paint" aria-hidden="true"><canvas ref={n => (node = n)}></canvas></div>
+      {children}
+    </div>
+  )
+}
+
+/** One choice of a StageSelect: a string is its own value and label. */
+export type StageOption = string | { value: string; label: string; disabled?: boolean | undefined }
+
+/** Props for StageSelect. */
+export interface StageSelectProps {
+  options: StageOption[]
+  /** The value it starts on; the first option when left out. */
+  value?: string | undefined
+  /** Puts the value in a form, through a hidden input. */
+  name?: string | undefined
+  disabled?: boolean | undefined
+  /** Hears each value picked. */
+  onChange?: ((value: string) => void) | undefined
+  [attr: string]: unknown
+}
+
+/**
+ * A select a stage draws, list and all (APG select-only combobox). Its trigger is a `field` skin; its list floats in the
+ * top layer as a stage of its own, in the look of the one around it, with `menu` and `option` skins. Wrap it in a
+ * `<label>` to name it.
+ */
+export function StageSelect({ options, value, name, disabled, onChange, ...rest }: StageSelectProps) {
+  const items = untrack(() => options).map(o => (typeof o === 'string' ? { value: o, label: o } : o))
+  const current = state(untrack(() => value) ?? items[0]?.value ?? '')
+  const id = uid('stage-sel')
+  let trigger: HTMLButtonElement | undefined, paint: HTMLCanvasElement | undefined
+  use(stageSelect, () => trigger, () => ({ value: current.value, onPick: (v: string) => { current.value = v; onChange?.(v) } }))
+  use(floatStage, () => paint)
+  return (
+    <span data-part="select">
+      <button {...rest} ref={n => (trigger = n)} type="button" data-skin="field" role="combobox" aria-haspopup="listbox" aria-expanded="false" aria-controls={id} disabled={disabled}>
+        {items.find(i => i.value === current.value)?.label ?? ''}
+      </button>
+      <div popover="manual" data-scope="stage" data-layout="box" data-part="float">
+        <div data-part="paint" aria-hidden="true"><canvas ref={n => (paint = n)}></canvas></div>
+        <div role="listbox" id={id} data-skin="menu">
+          {items.map((o, i) => (
+            <div key={o.value} role="option" id={`${id}-${i}`} data-skin="option" data-value={o.value} aria-selected={current.value === o.value ? 'true' : 'false'} aria-disabled={o.disabled ? 'true' : undefined}>{o.label}</div>
+          ))}
+        </div>
+      </div>
+      {name && <input type="hidden" name={name} value={current.value} />}
+    </span>
+  )
+}

package/src/Card.tsx

@@ -0,0 +1,29 @@
+import { untrack } from '@weft-js/core'
+import type { Interaction } from '@weft-js/core/interaction'
+import { useUi } from './use-ui'
+import './styles'
+import '@weft-js/warp-core/styles/components/surface.css'
+
+/**
+ * A surface (05 §1, §6: Card, Panel). Interactive cards (`href` or `onClick`) are links or buttons and always carry
+ * the sweep at every stop; static ones carry `data-sweep="surface"`, which only `data-flair="sweep"` shows.
+ */
+export function Card({ eyebrow, title, href, onClick, sweep = true, ui, ref, children, ...rest }: { ref?: ((el: HTMLElement) => void) | undefined; eyebrow?: unknown; title?: unknown; href?: string; onClick?: ((e: MouseEvent) => void) | undefined; sweep?: boolean; ui?: Interaction; children?: unknown; [attr: string]: unknown }) {
+  let host: HTMLElement | undefined
+  const took = (n: HTMLElement) => { host = n; ref?.(n) }
+  useUi(() => ui, () => host)
+  const interactive = untrack(() => !!(href || onClick))
+  const swept = untrack(() => sweep)
+  const parts = () => (
+    <>
+      {eyebrow !== undefined && <span data-part="eyebrow">{eyebrow}</span>}
+      {title !== undefined && <span data-part="title">{title}</span>}
+      {children}
+      {swept && <span data-part="sweep" aria-hidden="true"></span>}
+    </>
+  )
+  const sweepAttr = swept ? (interactive ? '' : 'surface') : undefined
+  if (untrack(() => href)) return <a href={href} data-scope="surface" data-sweep={sweepAttr} onClick={onClick!} {...rest} ref={took}>{parts()}</a>
+  if (interactive) return <button type="button" data-scope="surface" data-sweep={sweepAttr} onClick={onClick!} {...rest} ref={took}>{parts()}</button>
+  return <div data-scope="surface" data-sweep={sweepAttr} {...rest} ref={took}>{parts()}</div>
+}

package/src/Chart.tsx

@@ -0,0 +1,133 @@
+import { uid } from '@weft-js/warp-core'
+import { chart, SSR_RADIUS, SSR_WIDTH, tableHTML, toHTML, type Ctx, type Form } from '@weft-js/warp-core/charts'
+import { derived, untrack } from '@weft-js/core'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/data/tokens.css'
+import '@weft-js/warp-core/styles/data/base.css'
+import '@weft-js/warp-core/styles/data/chart.css'
+import '@weft-js/warp-core/styles/data/legend.css'
+import '@weft-js/warp-core/styles/data/tooltip.css'
+
+/** What every chart shares around its plot: the caption, the toolbar and the loading, empty and error states. */
+export type ChartFrame = {
+  title: string
+  /** The title's heading level: one below the heading the chart sits under. Default 3, a chart in a page section. */
+  level?: 2 | 3 | 4 | 5 | 6
+  description?: unknown
+  /** Beside the view toggle: a layout switch, a range picker. */
+  toolbar?: unknown
+  /** Replaces the plot, in the same frame (06 §12). With no data the frame shows `empty` on its own. */
+  state?: 'loading' | 'empty' | 'error' | undefined
+  loading?: string | undefined
+  /** The title and detail shown in place of the plot when there is no data. */
+  empty?: { title: string; detail?: unknown } | undefined
+  error?: { title: string; detail?: unknown } | undefined
+  /** The next step under an empty or error state: a Retry button. */
+  action?: unknown
+}
+type Props<C> = ChartFrame & C & { form: Form<C> }
+
+// props that are the frame's, not a form's: a JSX prop builds its element each time it's read, so these are read once
+const FRAME = new Set(['form', 'level', 'description', 'toolbar', 'action', 'empty', 'error', 'loading'])
+
+const Drawn = ({ stroke }: { stroke: string }) => (
+  <svg width="72" height="40" viewBox="0 0 72 40" aria-hidden="true">
+    <path d="M8 0V40M22 0V40M36 0V40M50 0V40M64 0V40" stroke="var(--warp-color-border-strong)" />
+    <path d={stroke === 'var(--warp-color-critical-solid)' ? 'M0 20H30' : 'M0 14H72M0 26H72'} stroke={stroke} stroke-width="2" />
+  </svg>
+)
+
+function Standby({ state, title, text, action }: { state: 'loading' | 'empty' | 'error'; title: string; text?: { title: string; detail?: unknown } | undefined; action?: unknown }) {
+  if (untrack(() => state) === 'loading')
+    return (
+      <div data-part="state" role="status" aria-busy="true">
+        <div aria-hidden="true" style="display:flex;align-items:end;gap:10px;block-size:118px;inline-size:100%;padding-inline:6px">
+          {[40, 70, 55, 90, 64, 80, 96].map(h => <span key={h} data-part="skeleton" style={`--h:${h}px`}></span>)}
+        </div>
+        {text?.title ?? `Loading ${title}…`}
+      </div>
+    )
+  const failed = untrack(() => state) === 'error'
+  return (
+    <div data-part="state" role={failed ? 'alert' : 'status'}>
+      <Drawn stroke={failed ? 'var(--warp-color-critical-solid)' : 'var(--warp-color-accent-solid)'} />
+      <b style="color:var(--warp-color-text)">{text?.title ?? (failed ? `Couldn’t load ${title}` : `No ${title}`)}</b>
+      {text?.detail}
+      {action}
+    </div>
+  )
+}
+
+function Ready<C>(p: { form: Form<C>; cfg: () => C; id: string; root: () => HTMLElement | undefined }) {
+  const id = () => p.id
+  // the first layout, once: from here on `chart` owns these nodes, so nothing below re-renders them
+  const first = derived(() => untrack(() => p.form.plot(p.cfg(), SSR_WIDTH, { id: p.id, hidden: new Set(), r: SSR_RADIUS } satisfies Ctx)))
+  const legend = derived(() => p.form.legend?.(p.cfg()) ?? [])
+  const table = derived(() => tableHTML(p.form.table(p.cfg())))
+  const summary = derived(() => {
+    const c = p.cfg() as C & { summary?: string | ((c: C) => string) | undefined }
+    return typeof c.summary === 'function' ? c.summary(c) : c.summary ?? p.form.summary(c)
+  })
+  use(chart<C>, () => p.root(), () => ({ form: p.form, cfg: p.cfg(), id: p.id }))
+  return (
+    <>
+      {p.form.ramp !== undefined
+        ? <ul data-scope="legend" aria-label="Scale"><li style="display:flex;align-items:center;gap:6px;font-size:var(--warp-text-caption-size);color:var(--warp-color-text-subtle);padding-inline:6px">Fewer {[0, 1, 2, 3, 4, 5].slice(p.form.ramp).map(b => <i key={b} style={`display:inline-block;inline-size:11px;block-size:11px;border-radius:2px;background:var(--warp-color-data-seq-${b})`}></i>)} More</li></ul>
+        : legend.value.length > 0 && (
+          <ul data-scope="legend" aria-label="Series">
+            {legend.value.map((s, i) => <li key={s.name}><button type="button" aria-pressed="true" data-si={i} style={`--_dc:${s.color}`}><i data-shape={p.form.swatch ?? 'box'}></i>{s.name}{s.value !== undefined && <> <b>{s.value}</b></>}</button></li>)}
+          </ul>
+        )}
+      <div data-part="plot">
+        <div data-scope="tooltip" data-part="chart-tip" aria-hidden="true"></div>
+        <svg data-part="svg" viewBox={`0 0 ${first.value.w ?? SSR_WIDTH} ${first.value.h}`} width={first.value.w ?? SSR_WIDTH} height={first.value.h} style={first.value.style} role="group" aria-roledescription={p.form.kind} aria-labelledby={`${id()}-t`} aria-describedby={`${id()}-s`}
+          // oxlint-disable-next-line weft/no-html-sink -- toHTML escapes every text and attribute of the scene
+          innerHTML={toHTML(first.value.body)}></svg>
+      </div>
+      <div data-part="table" tabindex="0" role="region" aria-labelledby={`${id()}-t`}
+        // oxlint-disable-next-line weft/no-html-sink -- tableHTML escapes every cell
+        innerHTML={table.value}></div>
+      <p data-part="summary" id={`${id()}-s`}>{summary.value}</p>
+    </>
+  )
+}
+
+/**
+ * The frame every chart shares (06 §12): figure > head · legend · plot (svg, tooltip) · table · summary. The plot is
+ * laid out once here, so the server sends a whole chart, and from then on warp-core's `chart` owns it: width and data
+ * changes rewrite attributes on the same nodes, and the legend and the view toggle are delegated from the figure.
+ */
+export function Chart<C extends { data: unknown; title: string }>(props: Props<C>) {
+  const id = uid('chart')
+  let figure: HTMLElement | undefined
+  const cfg = () => {
+    const c: Record<string, unknown> = {}
+    for (const k of Object.keys(props)) if (!FRAME.has(k)) c[k] = (props as Record<string, unknown>)[k]
+    return c as C
+  }
+  const hasData = () => { const d = props.data; return d !== undefined && d !== null && (!Array.isArray(d) || d.length > 0) }
+  const status = () => props.state ?? (hasData() ? undefined : 'empty')
+  return (
+    <figure ref={n => (figure = n)} data-scope="chart" data-view="chart" data-enter="wait">
+      <div data-part="head">
+        <div>
+          <h3 id={`${id}-t`} aria-level={props.level === 3 ? undefined : props.level} style="margin:0;font-family:var(--warp-text-heading-font);font-size:calc(var(--warp-text-heading-size) - 3px);font-weight:var(--warp-text-heading-weight);letter-spacing:var(--warp-text-heading-tracking)">{props.title}</h3>
+          {props.description !== undefined && <p style="margin:2px 0 0;font-size:var(--warp-text-caption-size);color:var(--warp-color-text-subtle)">{props.description}</p>}
+        </div>
+        <div style="display:flex;flex-wrap:wrap;align-items:center;gap:8px">
+          {props.toolbar}
+          {status() === undefined && (
+            <div data-part="view-toggle" role="group" aria-label="View">
+              <button type="button" aria-pressed="true" data-view="chart" aria-label="Chart view"><svg aria-hidden="true" focusable="false" viewBox="0 0 16 16"><path d="M2 13.5h12M3.5 10.5l3-3.5 2.5 2 3.5-4.5" /></svg></button>
+              <button type="button" aria-pressed="false" data-view="table" aria-label="Table view"><svg aria-hidden="true" focusable="false" viewBox="0 0 16 16"><rect x="2" y="2.5" width="12" height="11" rx="1.5" /><path d="M2 6.5h12M2 10h12M6.5 6.5v7" /></svg></button>
+            </div>
+          )}
+        </div>
+      </div>
+      {status() === undefined
+        ? <Ready form={props.form} cfg={cfg} id={id} root={() => figure} />
+        : <Standby state={status()!} title={props.title} text={status() === 'loading' ? (props.loading === undefined ? undefined : { title: props.loading }) : status() === 'error' ? props.error : props.empty} action={props.action} />}
+    </figure>
+  )
+}

package/src/Charts.tsx

@@ -0,0 +1,69 @@
+// The chart forms (06 §12), one line each: a form is a pure layout in warp-core, and `Chart` is the frame around it.
+// Nothing here runs at import, so an app pays only for the forms it renders.
+import { spark as sparkAction, sparkScene, SSR_WIDTH, toHTML, bar, box, brush, bubble, candlestick, combo, donut, funnel, gauge, heat, histogram, line, radar, radial, sankey, scatter, stream, sunburst, tile, treemap, waterfall, type BarConfig, type BoxConfig, type BrushConfig, type CandleConfig, type ComboConfig, type DonutConfig, type FunnelConfig, type GaugeConfig, type HeatConfig, type HistConfig, type LineConfig, type RadarConfig, type RadialConfig, type SankeyConfig, type ScatterConfig, type StreamConfig, type SunConfig, type TileConfig, type TreemapConfig, type WaterConfig } from '@weft-js/warp-core/charts'
+import { state, untrack } from '@weft-js/core'
+import { Button } from './Button'
+import { Chart, type ChartFrame } from './Chart'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/data/tokens.css'
+import '@weft-js/warp-core/styles/data/base.css'
+
+/** Lines over a shared x axis. */
+export const LineChart = (p: ChartFrame & LineConfig) => <Chart form={line} {...p} />
+/** Bars, grouped or stacked. */
+export const BarChart = (p: ChartFrame & BarConfig) => <Chart form={bar} {...p} />
+/** Bars and lines on one plot. */
+export const ComboChart = (p: ChartFrame & ComboConfig) => <Chart form={combo} {...p} />
+/** A ring of parts of a whole. */
+export const DonutChart = (p: ChartFrame & DonutConfig) => <Chart form={donut} {...p} />
+/** Concentric arcs, one per value. */
+export const RadialChart = (p: ChartFrame & RadialConfig) => <Chart form={radial} {...p} />
+/** Stages narrowing from first to last. */
+export const FunnelChart = (p: ChartFrame & FunnelConfig) => <Chart form={funnel} {...p} />
+/** Dots at x and y. */
+export const ScatterChart = (p: ChartFrame & ScatterConfig) => <Chart form={scatter} {...p} />
+/** Dots at x and y, sized by a third value. */
+export const BubbleChart = (p: ChartFrame & ScatterConfig) => <Chart form={bubble} {...p} />
+/** Values binned into equal ranges. */
+export const Histogram = (p: ChartFrame & HistConfig) => <Chart form={histogram} {...p} />
+/** A grid of cells coloured by value. */
+export const HeatGrid = (p: ChartFrame & HeatConfig) => <Chart form={heat} {...p} />
+/** Series on axes spread around a circle. */
+export const RadarChart = (p: ChartFrame & RadarConfig) => <Chart form={radar} {...p} />
+/** Nested rectangles sized by value. */
+export const Treemap = (p: ChartFrame & TreemapConfig) => <Chart form={treemap} {...p} />
+/** Nested rings sized by value. */
+export const Sunburst = (p: ChartFrame & SunConfig) => <Chart form={sunburst} {...p} />
+/** Flows between stages, band width showing the amount. */
+export const SankeyChart = (p: ChartFrame & SankeyConfig) => <Chart form={sankey} {...p} />
+/** Open, high, low and close per period. */
+export const CandlestickChart = (p: ChartFrame & CandleConfig) => <Chart form={candlestick} {...p} />
+/** Quartiles and whiskers per group. */
+export const BoxPlot = (p: ChartFrame & BoxConfig) => <Chart form={box} {...p} />
+/** A running total, each step a rise or a fall. */
+export const WaterfallChart = (p: ChartFrame & WaterConfig) => <Chart form={waterfall} {...p} />
+/** A long series with a window dragged over it. */
+export const BrushChart = (p: ChartFrame & BrushConfig) => <Chart form={brush} {...p} />
+/** Regions drawn as equal tiles. */
+export const TileMap = (p: ChartFrame & TileConfig) => <Chart form={tile} {...p} />
+/** One value on an arc between its bounds. */
+export const GaugeChart = (p: ChartFrame & GaugeConfig) => <Chart form={gauge} {...p} />
+
+/** A rolling window (06 §12): one `d` write per tick on a fixed domain. Pausing holds the window and shows it as a table. */
+export function StreamChart(p: ChartFrame & Omit<StreamConfig, 'paused'>) {
+  const paused = state(false)
+  let held = untrack(() => p.data)
+  const flip = () => { held = p.data; paused.value = !paused.value }
+  return <Chart form={stream} {...p} data={paused.value ? held : p.data} paused={paused.value} toolbar={<Button emphasis="outline" onClick={flip}>{paused.value ? 'Resume' : 'Pause'}</Button>} />
+}
+
+/** No axes, end dot, `aria-hidden`: a sparkline is context inside a labelled parent. */
+/** `format` says a hovered point the way the headline beside it does (`v => \`${v}%\``), so the unit carries over. */
+export function Sparkline({ values, color, format }: { values: number[]; color?: string | undefined; format?: ((value: number) => string) | undefined }) {
+  let svg: SVGSVGElement | undefined
+  use(sparkAction, () => svg, () => (format ? { values, format } : values))
+  return <svg ref={n => (svg = n)} data-part="spark" viewBox={`0 0 ${SSR_WIDTH} 36`} aria-hidden="true" preserveAspectRatio="none" style={`display:block;inline-size:100%;block-size:36px;overflow:visible${color ? `;--_dc:${color}` : ''}`}
+    // oxlint-disable-next-line weft/no-html-sink -- toHTML escapes every text and attribute of the scene
+    innerHTML={toHTML(sparkScene(untrack(() => values), SSR_WIDTH))}></svg>
+}

package/src/Chip.tsx

@@ -0,0 +1,27 @@
+import { CheckIcon } from '@weft-js/warp-icons'
+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 './fields'
+import '@weft-js/warp-core/styles/inputs/choice.css'
+// the inputs form sits on the components chip (inputs.html loads both): pressed fill, forced colours
+import '@weft-js/warp-core/styles/components/chip.css'
+import '@weft-js/warp-core/styles/components/toggle-button.css'
+
+const sweepParts = () => <><span data-part="sweep-base" aria-hidden="true"></span><span data-part="sweep" aria-hidden="true"></span></>
+
+/** A filter chip (03 §4 Chips): a toggle button; pressed pins the sweep on accent-soft and draws the check. */
+export function Chip({ pressed, count, icon, ui, ref, children, ...rest }: { ref?: ((el: HTMLButtonElement) => unknown) | undefined; pressed?: boolean; count?: unknown; icon?: IconRef | undefined; ui?: Interaction; children?: unknown; [attr: string]: unknown }) {
+  let host: HTMLButtonElement | undefined
+  useUi(() => ui, () => host)
+  const glyph = derived(() => icon)
+  return (
+    <button type="button" data-scope="chip" data-sweep="" aria-pressed={pressed ? 'true' : 'false'} {...rest} ref={n => { host = n; ref?.(n) }}>
+      {sweepParts()}
+      {pressed ? <CheckIcon data-part="check" /> : glyph.value && <Icon name={glyph.value} />}
+      {children}
+      {count !== undefined && <span data-part="count">{count}</span>}
+    </button>
+  )
+}