@weft-js/warp 0.0.0-stage → 0.1.1

package/src/DateField.tsx

@@ -0,0 +1,221 @@
+import { CalendarIcon } from '@weft-js/warp-icons'
+import { addDays, daysIn, fmt, fmtRange, isoOf, isUnavailable, pickRange, readDate, toIso, daysBetween, defaultPresets, listKey, weekStart, type ChangeReason, type DateRange, type IsoDate, type RangePreset, type SegmentPart } from '@weft-js/warp-core'
+import { derived, state, untrack } from '@weft-js/core'
+import { Button } from './Button'
+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'
+
+/** Props for DateField. */
+export type DateFieldProps = RichFieldProps & Bindable<IsoDate | null> & Openable & {
+  min?: IsoDate | undefined
+  max?: IsoDate | undefined
+  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
+  /** Shows the week number at the start of each calendar row. */
+  weekNumbers?: boolean | undefined
+  parse?: ((text: string, today: IsoDate) => IsoDate | null) | undefined
+}
+
+/**
+ * DateField (04 §2): segments in the field shell and a calendar in the popover (a sheet on phones), Today and Clear in
+ * the foot. `onValueChange` fires only with a complete, valid date or null; a half-typed date stays in the segments
+ * and `error` explains it on blur. The shell's `error` prop, when given, wins.
+ */
+export function DateField({ value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, min, max, isDateUnavailable, firstDayOfWeek, weekNumbers, parse: _parse, locale, today, name, presentation, label, hint, error, disabled, readonly, ...rest }: DateFieldProps) {
+  const env = usePickerEnv(() => locale, () => today)
+  const v = bindable<IsoDate | null>(() => value, () => defaultValue, null, () => onValueChange)
+  const pop = useOpen(() => open, () => defaultOpen, () => onOpenChange)
+  const own = state<string | null>(null)
+  const started = state(false)
+  const clears = state(0)
+  const t = derived(() => messages(env.locale.value))
+  let trigger: HTMLButtonElement | undefined
+  const ctx = () => ({ mode: 'single' as const, value: v.value, today: env.today.value, locale: env.locale.value, min, max, isDateUnavailable })
+  const onEdit = (st: SegmentState, parts: SegmentPart[]) => {
+    started.value = st !== 'empty'
+    own.value = null
+    const take = (iso: IsoDate | null) => { if (iso !== untrack(() => v.value)) v.set(iso, 'keyboard') }
+    if (st !== 'complete') return take(null)
+    const d = readDate(parts)
+    if (d.day! > daysIn(d.year!, d.month!)) { own.value = `${fmt(toIso(d.year!, d.month!, 1), { month: 'long', year: 'numeric' }, env.locale.value)} has ${daysIn(d.year!, d.month!)} days.`; return take(null) }
+    const iso = isoOf(d)
+    if (isUnavailable(iso, ctx())) { own.value = `${fmt(iso, { dateStyle: 'medium' }, env.locale.value)} is ${t.value.unavailable}.`; return take(null) }
+    take(iso)
+  }
+  const choose = (iso: IsoDate | null, reason: ChangeReason) => { own.value = null; v.set(iso, reason); pop.set(false); if (iso === null) { clears.value++; started.value = false } }
+  return (
+    <Composite
+      {...rest}
+      label={label}
+      hint={hint}
+      error={error ?? own.value ?? undefined}
+      disabled={disabled}
+      readonly={readonly}
+      bound={v}
+      onReset={() => { own.value = null; started.value = false }}
+      filled={v.value !== null || started.value}
+      hold={pop.value}
+      attrs={{ onClick: (e: MouseEvent) => { if (!disabled && isSheet(e.currentTarget as Element, presentation) && (e.target as Element).closest?.('[data-part="segment"]')) pop.set(true) } }}
+      control={() => (
+        <>
+          <Segments required={rest.required} kind="date" locale={env.locale.value} value={v.value} today={env.today.value} clears={clears.value} disabled={disabled} readonly={readonly} onEdit={onEdit} onBlurPartial={() => (own.value = 'Enter a complete date, or pick one from the calendar.')} />
+          <Trigger el={(n: HTMLButtonElement) => (trigger = n)} icon={CalendarIcon} label={t.value.choose + (v.value ? `, ${fmt(v.value, { dateStyle: 'full' }, env.locale.value)}` : '')} open={pop.value} disabled={disabled} onToggle={() => pop.set(!pop.value)} />
+          <Hidden name={name} value={() => v.value ?? ''} />
+        </>
+      )}
+      end={
+        <Panel label={t.value.choose} open={pop} trigger={() => trigger!} presentation={presentation}>
+          {() => (
+            <CalendarGrid mode="single" value={() => v.value} locale={env.locale.value} today={env.today.value} min={min} max={max} isDateUnavailable={isDateUnavailable} firstDayOfWeek={firstDayOfWeek} weekNumbers={weekNumbers} autofocus onPick={choose}>
+              <div data-part="foot">
+                <Button emphasis="ghost" size="sm" onClick={() => choose(env.today.value as IsoDate, 'pointer')}>{t.value.todayBtn}</Button>
+                <Button emphasis="ghost" size="sm" onClick={() => choose(null, 'pointer')}>{t.value.clear}</Button>
+              </div>
+            </CalendarGrid>
+          )}
+        </Panel>
+      }
+    />
+  )
+}
+
+export type RangeCompare = 'previous-period' | 'previous-year' | DateRange
+/** Props for DateRangeField. */
+export type DateRangeFieldProps = RichFieldProps & Bindable<DateRange> & Openable & {
+  presets?: RangePreset[] | 'default' | false
+  /** The id of the chosen preset, such as "Last 7 days". Null when the dates were picked by hand. */
+  preset?: string | null
+  /** Called with the preset's id when one is picked, and null when the dates are changed by hand. */
+  onPresetChange?: (id: string | null) => void
+  min?: IsoDate | undefined
+  max?: IsoDate | undefined
+  maxDays?: number
+  /** Return true for a day that can't start or end the range: it shows struck through. */
+  isDateUnavailable?: (d: IsoDate) => boolean
+  months?: 1 | 2 | 'auto'
+  compare?: RangeCompare | null | undefined
+}
+
+/** The comparison range of a selection, for a dashboard's "vs" (04 DateRangeField). */
+export function compareRange(v: DateRange, c: RangeCompare | null | undefined): DateRange | null {
+  if (!c || !v.start || !v.end) return typeof c === 'object' ? c : null
+  if (typeof c === 'object') return c
+  if (c === 'previous-year') return { start: `${+v.start.slice(0, 4) - 1}${v.start.slice(4)}` as IsoDate, end: `${+v.end.slice(0, 4) - 1}${v.end.slice(4)}` as IsoDate }
+  const n = daysBetween(v.start, v.end) + 1
+  return { start: addDays(v.start, -n), end: addDays(v.start, -1) }
+}
+
+/**
+ * DateRangeField (04 §2): two segment groups and one trigger; the popover shows two months (one when narrow) beside a
+ * preset rail. The chosen preset is kept apart from the frozen dates, so a dashboard's "Last 7 days" can roll forward.
+ */
+export function DateRangeField({ value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, presets = 'default', preset, onPresetChange, min, max, maxDays, isDateUnavailable, months = 'auto', compare, locale, today, name, presentation, label, hint, error, disabled, readonly, ...rest }: DateRangeFieldProps) {
+  const env = usePickerEnv(() => locale, () => today)
+  const v = bindable<DateRange>(() => value, () => defaultValue, { start: null, end: null }, () => onValueChange)
+  const pop = useOpen(() => open, () => defaultOpen, () => onOpenChange)
+  const chosen = state<string | null>(untrack(() => preset) ?? null)
+  const jump = state<string | null>(null)
+  const started = state(false)
+  const narrow = state(false)
+  const t = derived(() => messages(env.locale.value))
+  const list = derived(() => (presets === false ? [] : presets === 'default' ? defaultPresets(env.locale.value) : presets))
+  const count = derived(() => (months === 'auto' ? (narrow.value ? 1 : 2) : months))
+  const compared = derived(() => compareRange(v.value, compare))
+  const trouble = derived(() => {
+    const r = v.value
+    if (r.start && r.end && r.end < r.start) return 'The end is before the start.'
+    if (r.start && r.end && maxDays && daysBetween(r.start, r.end) + 1 > maxDays) return `Choose at most ${maxDays} days.`
+    return undefined
+  })
+  const human = (d: string) => fmt(d, { dateStyle: 'medium' }, env.locale.value)
+  const summary = derived(() => {
+    const r = v.value
+    if (!r.start) return 'Pick a start date'
+    if (!r.end) return 'Pick an end date'
+    const n = daysBetween(r.start, r.end) + 1
+    return `${r.start > r.end ? `${human(r.start)} – ${human(r.end)}` : fmtRange(r.start, r.end, env.locale.value)} · ${new Intl.NumberFormat(env.locale.value, { style: 'unit', unit: 'day', unitDisplay: 'long' }).format(n)}`
+  })
+  const said = state('')
+  let trigger: HTMLButtonElement | undefined
+  const set = (r: DateRange, reason: ChangeReason, id: string | null = null) => {
+    chosen.value = id
+    onPresetChange?.(id)
+    v.set(r, reason)
+  }
+  const edit = (which: 'start' | 'end') => (st: SegmentState, parts: SegmentPart[]) => {
+    started.value = st !== 'empty' || !!(which === 'start' ? v.value.end : v.value.start)
+    if (st === 'empty') return set({ ...v.value, [which]: null }, 'keyboard')
+    if (st !== 'complete') return
+    const d = readDate(parts)
+    if (d.day! <= daysIn(d.year!, d.month!)) set({ ...v.value, [which]: isoOf(d) }, 'keyboard')
+  }
+  const editStart = edit('start'), editEnd = edit('end')
+  const applyPreset = (p: RangePreset) => {
+    const r = p.range(env.today.value as IsoDate, weekStart(env.locale.value))
+    set(r, 'pointer', p.id)
+    jump.value = r.end
+    said.value = `${p.label}: ${summary.value}`
+  }
+  const onRail = (e: KeyboardEvent) => {
+    const opts = list.value
+    const at = opts.findIndex(p => p.id === (e.target as HTMLElement).dataset.id)
+    if (at < 0) return
+    const step = narrow.value ? ({ ArrowRight: 'ArrowDown', ArrowLeft: 'ArrowUp' } as Record<string, string>)[e.key] ?? e.key : e.key
+    const m = listKey(step, at, opts.length)
+    if (!m.handled) return
+    e.preventDefault()
+    if (m.pick) return applyPreset(opts[at]!)
+    ;(e.currentTarget as HTMLElement).querySelector<HTMLElement>(`[data-id="${opts[m.to]!.id}"]`)?.focus()
+  }
+  const toggle = () => {
+    narrow.value = isSheet(trigger!, presentation) || (trigger!.ownerDocument.defaultView?.innerWidth ?? 1024) < 640
+    pop.set(!pop.value)
+  }
+  return (
+    <Composite
+      {...rest}
+      label={label}
+      hint={hint}
+      error={error ?? trouble.value}
+      disabled={disabled}
+      readonly={readonly}
+      bound={v}
+      onReset={() => { started.value = false; chosen.value = untrack(() => preset) ?? null }}
+      filled={!!(v.value.start || v.value.end) || started.value}
+      hold={pop.value}
+      control={() => (
+        <>
+          <Segments required={rest.required} kind="date" label="Start" locale={env.locale.value} value={v.value.start} today={env.today.value} disabled={disabled} readonly={readonly} onEdit={editStart} />
+          <span data-part="range-sep" aria-hidden="true">–</span>
+          <Segments required={rest.required} kind="date" label="End" locale={env.locale.value} value={v.value.end} today={env.today.value} disabled={disabled} readonly={readonly} onEdit={editEnd} />
+          <Trigger el={(n: HTMLButtonElement) => (trigger = n)} icon={CalendarIcon} label={t.value.chooseRange + (v.value.start && v.value.end ? `, ${summary.value}` : '')} open={pop.value} disabled={disabled} onToggle={toggle} />
+          <Hidden name={name} value={() => (v.value.start && v.value.end ? `${v.value.start}/${v.value.end}` : '')} />
+        </>
+      )}
+      end={
+        <Panel label={t.value.chooseRange} open={pop} trigger={() => trigger!} presentation={presentation}>
+          {() => (
+            <div data-scope="range-panel" data-narrow={narrow.value ? '' : undefined}>
+              {list.value.length > 0 && (
+                <ul role="listbox" aria-label="Presets" aria-orientation={narrow.value ? 'horizontal' : 'vertical'} onKeyDown={onRail}>
+                  {list.value.map(p => <li key={p.id} role="option" data-id={p.id} tabindex={p.id === (chosen.value ?? list.value[0]!.id) ? '0' : '-1'} aria-selected={p.id === chosen.value ? 'true' : 'false'} onClick={() => applyPreset(p)}>{p.label}</li>)}
+                </ul>
+              )}
+              <div>
+                <CalendarGrid mode="range" months={count.value} value={() => v.value} compare={() => compared.value} goTo={() => jump.value} locale={env.locale.value} today={env.today.value} min={min} max={max} isDateUnavailable={isDateUnavailable} autofocus onPick={(iso, r) => set(pickRange(v.value, iso), r)}>
+                  <div data-part="foot">
+                    <span aria-live="polite">{summary.value}</span>
+                    <Button emphasis="ghost" size="sm" onClick={() => set({ start: null, end: null }, 'pointer')}>{t.value.clear}</Button>
+                  </div>
+                </CalendarGrid>
+              </div>
+              <span class="sr" role="status">{said.value}</span>
+            </div>
+          )}
+        </Panel>
+      }
+    />
+  )
+}

package/src/Dither.tsx

@@ -0,0 +1,129 @@
+import { ditherField, ditherImage, ditherStage, type Algorithm, type FieldOptions, type Gradient, type MaskSource, type Ramp, type DitherStageOptions } from '@weft-js/warp-core/dither'
+import { derived } from '@weft-js/core'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/canvas/dither.css'
+import '@weft-js/warp-core/styles/canvas/stage.css'
+
+export type { Algorithm, Brush, DitherPainter, DitherPiece, Field as FieldFn, FieldName, Gradient, MaskSource, Pattern, PointerMode, Ramp, Skin } from '@weft-js/warp-core/dither'
+export { LEVEL, PAINTERS } from '@weft-js/warp-core/dither'
+
+const box = (ratio: string | number | undefined, style: unknown) => [ratio === undefined ? undefined : `aspect-ratio:${ratio}`, style].filter(Boolean).join(';') || undefined
+
+/** Props for DitherField. */
+export interface DitherFieldProps extends FieldOptions {
+  /** Fills the nearest positioned ancestor: a section's background. */
+  fill?: boolean
+  /** CSS aspect-ratio. Default 16 / 9 unless `fill`. */
+  ratio?: string | number
+  /** Names the field (role="img"). Without one it is decorative. */
+  label?: string | undefined
+  children?: unknown
+  [attr: string]: unknown
+}
+
+/** A live dithered field (08 §6.7): moves at vivid and balanced, holds still at quiet and under reduced motion. Children sit over it. */
+export function DitherField({ kind, smooth, ramp, spark, pattern, cell, inks, speed, gain, seed, spread, pointer, mask, fade, reveal, fps, fill, ratio, label, children, style, ...rest }: DitherFieldProps) {
+  let node: HTMLCanvasElement | undefined
+  use(ditherField, () => node, () => ({ kind, smooth, ramp, spark, pattern, cell, inks, speed, gain, seed, spread, pointer, mask, fade, reveal, fps }))
+  return (
+    <div {...rest} data-scope="dither" data-fill={fill ? '' : undefined} role={label ? 'img' : undefined} aria-label={label} style={box(ratio ?? (fill ? undefined : '16 / 9'), style)}>
+      <canvas ref={n => (node = n)} aria-hidden="true"></canvas>
+      {children}
+    </div>
+  )
+}
+
+/** Props for Dither. */
+export interface DitherProps {
+  /** An image to dither. The real <img> stays underneath, for alt text, for no script and for a cross-origin failure. */
+  src?: string
+  /** The image's alt text, kept on the real <img> underneath. */
+  alt?: string
+  /** The image's CORS mode. A cross-origin image needs it to be read and dithered. */
+  crossorigin?: 'anonymous' | 'use-credentials'
+  /** With no `src`: the gradient to dither. Default a soft diagonal. */
+  gradient?: Gradient | undefined
+  /** `atkinson` by default for images, `bayer8` for gradients. */
+  algorithm?: Algorithm
+  /** The inks: a tone such as `accent`, or your own list of colours. */
+  ramp?: Ramp
+  /** CSS pixels per dither cell. Larger cells give a coarser, chunkier picture. */
+  cell?: number
+  /** How many inks of the ramp to use. Default: the tier's. */
+  inks?: number
+  contrast?: number
+  invert?: boolean
+  /** Fills the nearest positioned parent instead of keeping a ratio, for a section background. */
+  fill?: boolean
+  ratio?: string | number
+  label?: string | undefined
+  [attr: string]: unknown
+}
+
+/** A still image or gradient, dithered to warp's inks once, and again only when its size or theme changes (08 §6.7). */
+export function Dither({ src, alt, crossorigin, gradient, algorithm, ramp, cell, inks, contrast, invert, fill, ratio, label, style, ...rest }: DitherProps) {
+  let node: HTMLCanvasElement | undefined
+  let img: HTMLImageElement | undefined
+  use(ditherImage, () => node, () => ({ source: img, gradient, algorithm, ramp, cell, inks, contrast, invert }))
+  return (
+    <div {...rest} data-scope="dither" data-fill={fill ? '' : undefined} role={label ? 'img' : undefined} aria-label={label} style={box(ratio ?? (fill ? undefined : '16 / 9'), style)}>
+      {src && <img ref={n => (img = n)} src={src} alt={alt ?? ''} crossorigin={crossorigin} loading="lazy" decoding="async" />}
+      <canvas ref={n => (node = n)} aria-hidden="true"></canvas>
+    </div>
+  )
+}
+
+/** Props for DitherGlyph. */
+export interface DitherGlyphProps extends Omit<FieldOptions, 'mask'> {
+  /** The word to set. It stays in the page as real text for readers and for search. */
+  text?: string | undefined
+  /** Or an SVG path and the size of its box, for a logo or an icon. */
+  path?: string
+  box?: [width: number, height: number]
+  /** Stroke width in the box's units, for a path made of lines. */
+  stroke?: number | undefined
+  /** Or any drawing, in cells. */
+  draw?: (ctx: CanvasRenderingContext2D, cols: number, rows: number) => void
+  /** Names a `path` or `draw` glyph. */
+  label?: string | undefined
+  font?: string
+  weight?: number | string
+  /** Share of the box the shape fills, 0–1. */
+  fit?: number | undefined
+  ratio?: string | number
+  [attr: string]: unknown
+}
+
+/** A word or a logo woven out of a dithered field (08 §6.7). */
+export function DitherGlyph({ text, path, box: viewBox, stroke, draw, label, font, weight, fit, cell = 4, ratio, kind = 'flow', ...rest }: DitherGlyphProps) {
+  const mask = derived<MaskSource>(() => draw ?? (path ? { path, box: viewBox ?? [24, 24], fit, stroke } : { text: text ?? '', font, weight, fit }))
+  return (
+    <DitherField {...rest} kind={kind} cell={cell} mask={mask.value} ratio={ratio ?? '3 / 1'} label={text ? undefined : label}>
+      {text && <span data-part="glyph-text">{text}</span>}
+    </DitherField>
+  )
+}
+
+/** Props for DitherStage. */
+export interface DitherStageProps extends DitherStageOptions {
+  /** `box` paints its own block; `scroll` is a scroller whose view it paints; `page` paints the viewport, for a whole page. */
+  layout?: DitherStageOptions['layout']
+  children?: unknown
+  [attr: string]: unknown
+}
+
+/**
+ * A CanvasStage in the dither look (08 §6.8). Mark any element `data-skin="button"`, `card`, `field` and so on: it keeps
+ * its layout, focus, typing and semantics, and the stage draws it in dithered cells, states and all.
+ */
+export function DitherStage({ layout = 'box', ramp, kind, ground, pattern, cell, speed, drift, rail, veil, ripple, painters, fps, children, ...rest }: DitherStageProps) {
+  let node: HTMLCanvasElement | undefined
+  use(ditherStage, () => node, () => ({ layout, ramp, kind, ground, pattern, cell, speed, drift, rail, veil, ripple, painters, fps }))
+  return (
+    <div {...rest} data-scope="stage" data-paint="dither" 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>
+  )
+}

package/src/Drawer.tsx

@@ -0,0 +1,41 @@
+import { XIcon } from '@weft-js/warp-icons'
+import { dialog, uid } from '@weft-js/warp-core'
+import { derived, type State, untrack } from '@weft-js/core'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/components/button.css' // the close button's markup
+import '@weft-js/warp-core/styles/components/sheet.css'
+import '@weft-js/warp-core/styles/components/dialog.css' // the backdrop and the parts a sheet shares with the dialog
+
+/**
+ * A sheet (05 §3 Drawer/Sheet; components.html:1092-1106): on a native <dialog>, at the side on wide screens and from
+ * the bottom on phones (`side="auto"`: bottom under 600px, decided when it opens). The handle shows only at the
+ * bottom. Initial focus goes to [autofocus], else the title, never the handle. `inline` draws it open in the page's flow,
+ * for docs and previews: a non-modal <dialog open> at its side's shape, with no top layer, scrim or focus trap.
+ */
+export function Drawer({ open, title, description, footer, side = 'auto', inline, children }: { open: State<boolean>; title: unknown; description?: unknown; footer?: unknown; side?: 'auto' | 'right' | 'left' | 'bottom' | 'top'; /** Drawn open in the page's flow, not over it: no top layer, scrim or focus trap. For docs and previews. */ inline?: boolean; children?: unknown }) {
+  const id = uid('sheet')
+  const hasDescription = derived(() => description !== undefined)
+  const foot = derived(() => footer) // one build of the footer, however often it is read
+  let el: HTMLDialogElement | undefined
+  const placed = () => (side === 'auto' ? (typeof innerWidth === 'number' && innerWidth < 600 ? 'bottom' : 'right') : side)
+  const flat = untrack(() => !!inline)
+  if (!flat) use(dialog, () => el, () => {
+    const on = open.value
+    if (on && el) el.dataset.side = placed()
+    return { open: on, onClose: () => (open.value = false) }
+  })
+  const closer = (e: Event) => { if (flat && (e.target as Element).closest?.('[data-close]')) open.value = false }
+  return (
+    <dialog ref={n => (el = n)} open={flat ? open.value : undefined} data-presentation={flat ? 'inline' : undefined} onClick={closer} data-scope="sheet" aria-labelledby={`${id}-t`} aria-describedby={hasDescription.value ? `${id}-d` : undefined} data-side={untrack(() => (side === 'auto' ? 'right' : side))}>
+      <button type="button" data-part="handle" aria-label="Sheet height: tall. Press to shrink."></button>
+      <div data-part="header">
+        <h2 data-part="title" id={`${id}-t`}>{title}</h2>
+        {hasDescription.value && <p data-part="description" id={`${id}-d`}>{description}</p>}
+        <button type="button" data-scope="button" data-emphasis="ghost" data-tone="neutral" data-icon-only="" aria-label="Close" data-part="close" data-close=""><XIcon /></button>
+      </div>
+      <div data-part="body">{children}</div>
+      {foot.value !== undefined && <div data-part="footer">{foot.value}</div>}
+    </dialog>
+  )
+}

package/src/DurationField.tsx

@@ -0,0 +1,98 @@
+import { TimerIcon } from '@weft-js/warp-icons'
+import { balance, formatDuration, pad, parseDuration, totalSeconds, type DurationParts, type IsoDuration } from '@weft-js/warp-core'
+import { derived, state, untrack } from '@weft-js/core'
+import { bindable, Composite, Hidden, usePickerEnv, type Bindable, type RichFieldProps } from './Picker'
+
+type Unit = 'd' | 'h' | 'm' | 's'
+const INTL = { d: 'day', h: 'hour', m: 'minute', s: 'second' } as const
+const NAMES = { d: 'Days', h: 'Hours', m: 'Minutes', s: 'Seconds' } as const
+const SHORT = { d: 'd', h: 'h', m: 'min', s: 's' } as const
+const SIZE = { d: 86400, h: 3600, m: 60, s: 1 } as const
+const MAX = { d: 99, h: 99, m: 59, s: 59 } as const
+
+/** Props for DurationField. */
+export type DurationFieldProps = RichFieldProps & Bindable<IsoDuration | null> & {
+  units?: Unit[]
+  max?: IsoDuration | undefined
+  step?: Partial<Record<'h' | 'm' | 's', number>>
+  balance?: boolean
+}
+
+/**
+ * DurationField (04 §2): a spinbutton for each allowed unit; ↑/↓ step with carry into the next unit (Shift for three
+ * steps), and digits fill. The value is an ISO duration, balanced (`PT90M` → `PT1H30M`) unless `balance: false`.
+ */
+export function DurationField({ value, defaultValue, onValueChange, units = ['h', 'm'], max, step, balance: carry = true, locale, today, name, label, hint, error, disabled, ...rest }: DurationFieldProps) {
+  const env = usePickerEnv(() => locale, () => today)
+  const v = bindable<IsoDuration | null>(() => value, () => defaultValue, null, () => onValueChange)
+  const parts = derived(() => parseDuration(v.value))
+  const limit = untrack(() => (max ? totalSeconds(parseDuration(max)) : Infinity))
+  const buf = state('')
+  let group: HTMLDivElement | undefined
+  const say = (u: Unit, n: number) => new Intl.NumberFormat(env.locale.value, { style: 'unit', unit: INTL[u], unitDisplay: 'long' }).format(n)
+  const words = derived(() => {
+    const p = parts.value
+    const on = units.filter(u => p[u])
+    return on.length ? on.map(u => say(u, p[u])).join(' ') : 'No time'
+  })
+  const write = (next: DurationParts, reason: 'keyboard' = 'keyboard') => {
+    const t = Math.max(0, Math.min(limit, totalSeconds(next)))
+    v.set(formatDuration(carry ? balance(t, units) : next), reason)
+  }
+  const onKey = (e: KeyboardEvent) => {
+    const el = (e.target as HTMLElement).closest?.<HTMLElement>('[data-u]')
+    if (!el) return
+    const u = el.dataset.u as Unit
+    const at = units.indexOf(u)
+    const p = parts.value
+    const size = (step?.[u as 'h'] ?? (u === 'm' ? 5 : 1)) * SIZE[u] * (e.shiftKey ? 3 : 1)
+    if (e.key === 'ArrowUp' || e.key === 'ArrowDown') {
+      e.preventDefault()
+      buf.value = ''
+      write(balance(totalSeconds(p) + (e.key === 'ArrowUp' ? size : -size), units))
+    } else if (/^\d$/.test(e.key)) {
+      e.preventDefault()
+      const b = (buf.value + e.key).slice(-2)
+      buf.value = b
+      const n = +b
+      write(n > MAX[u] && !carry ? p : { ...p, [u]: n })
+      if (b.length === 2 && at < units.length - 1) { buf.value = ''; (group!.querySelector(`[data-u="${units[at + 1]}"]`) as HTMLElement).focus() }
+    } else if (e.key === 'Backspace') {
+      e.preventDefault()
+      buf.value = ''
+      write({ ...p, [u]: 0 })
+    } else if (e.key === 'ArrowRight' || e.key === 'ArrowLeft') {
+      const to = units[at + (e.key === 'ArrowRight' ? 1 : -1)]
+      if (to) { e.preventDefault(); (group!.querySelector(`[data-u="${to}"]`) as HTMLElement).focus() }
+    }
+  }
+  return (
+    <Composite
+      icon={TimerIcon}
+      {...rest}
+      label={label}
+      hint={hint ?? words.value}
+      error={error}
+      disabled={disabled}
+      bound={v}
+      onReset={() => (buf.value = '')}
+      filled={totalSeconds(parts.value) > 0}
+      control={() => (
+        <>
+          <div ref={n => (group = n)} data-part="segments" onKeyDown={onKey} onFocusOut={() => (buf.value = '')}>
+            {units.map(u => {
+              const n = derived(() => parts.value[u])
+              return (
+                <>
+                  <span key={u} data-part="segment" data-u={u} role="spinbutton" tabindex={disabled ? undefined : '0'} aria-label={NAMES[u]} aria-required={rest.required ? 'true' : undefined} aria-valuemin="0" aria-valuemax={MAX[u]} aria-valuenow={n.value} aria-valuetext={say(u, n.value)}>{u === units[0] ? n.value : pad(n.value)}</span>
+                  <span data-part="literal" class="unit" aria-hidden="true">{SHORT[u]}</span>
+                </>
+              )
+            })}
+          </div>
+          <Hidden name={name} value={() => v.value ?? ''} />
+        </>
+      )}
+    />
+  )
+}

package/src/Feed.tsx

@@ -0,0 +1,74 @@
+import { untrack } from '@weft-js/core'
+import { VirtualList, type VirtualControl } from './VirtualList'
+import './styles'
+import '@weft-js/warp-core/styles/data/timeline.css'
+
+/** One row of a Feed. */
+export interface FeedItem {
+  id: string | number
+  /** Actor, verb and object: the bold line. */
+  what: unknown
+  when?: string
+  /** The body, measured. */
+  detail?: string
+  tone?: string | undefined
+}
+
+/** Props for Feed. */
+export interface FeedProps<T extends FeedItem> {
+  items: readonly T[]
+  label: string
+  height?: string
+  busy?: boolean | undefined
+  /** Near the end: load more. */
+  onEnd?: () => void
+  /** Called when an item's measured height differs from the estimate, with both heights. For tuning. */
+  onDrift?: (index: number, predicted: number, actual: number) => void
+  /** Hands over a control to scroll to, focus or move between items from outside. */
+  control?: (c: VirtualControl) => void
+  /** An item's whole content. Default: knot, what, when, detail. */
+  children?: (item: () => T) => unknown
+}
+
+/** A long activity feed (07 §4): the APG feed pattern on a window. Page Down and Up move between articles. */
+export function Feed<T extends FeedItem>(props: FeedProps<T>) {
+  const render = untrack(() => props.children)
+  const keys = (e: KeyboardEvent, c: VirtualControl) => {
+    if (e.key === 'PageDown' || e.key === 'PageUp') {
+      e.preventDefault()
+      c.move(e.key === 'PageDown' ? 1 : -1)
+    }
+  }
+  return (
+    <VirtualList
+      tag="ol"
+      inner
+      role="feed"
+      rowRole="article"
+      listScope="timeline"
+      label={props.label}
+      height={props.height ?? '480px'}
+      items={props.items}
+      rowKey={i => i.id}
+      text={i => i.detail ?? ''}
+      estimate={56}
+      busy={props.busy}
+      onEnd={props.onEnd}
+      onDrift={props.onDrift}
+      control={props.control}
+      roving
+      onRowKey={keys}
+    >
+      {item => (render
+        ? render(item)
+        : (
+          <>
+            <span data-part="knot" data-tone={item().tone}></span>
+            <span data-part="what">{item().what}</span>
+            <time data-part="when">{item().when}</time>
+            <span data-part="detail" data-measure="">{item().detail}</span>
+          </>
+        ))}
+    </VirtualList>
+  )
+}