@weft-js/warp 0.0.0-stage → 0.1.0

package/src/Menu.tsx

@@ -0,0 +1,111 @@
+import { menu, moveShuttle, uid, type Align, type Side } from '@weft-js/warp-core'
+import { onCleanup, onMount, state } from '@weft-js/core'
+import { Button, type ButtonProps } from './Button'
+import { Icon, type IconRef } from './Icon'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/components/menu.css'
+
+/** One line of a Menu: an item, a group label or a separator. */
+export type MenuEntry =
+  | { label: string; onSelect?: () => void; icon?: IconRef | undefined; shortcut?: string; tone?: 'critical' | undefined; disabled?: boolean | undefined; href?: string }
+  | { separator: true }
+  | { group: string }
+
+const Row = ({ e }: { e: Extract<MenuEntry, { label: string }> }) => (
+  <>
+    {e.icon && <Icon name={e.icon} />}
+    <span data-part="item-label">{e.label}</span>
+    {e.shortcut && <span data-part="shortcut">{e.shortcut}</span>}
+  </>
+)
+
+/** Props for Menu. */
+export interface MenuProps {
+  /** The trigger's text. */
+  label: unknown
+  items: MenuEntry[]
+  trigger?: ButtonProps | undefined
+  side?: Side | undefined
+  align?: Align
+}
+
+/**
+ * A menu button (05 §3, APG): the trigger holds its sweep while open and the panel opens from it. warp-core's menu() owns
+ * focus, ↑/↓, Home/End, typeahead, Escape and Tab; the highlight is one shuttle that follows focus and the pointer.
+ */
+export function Menu({ label, items, trigger, side = 'bottom', align = 'start' }: MenuProps) {
+  const id = uid('menu')
+  const open = state(false)
+  const at = state<'first' | 'last'>('first')
+  let button: HTMLButtonElement | undefined
+  let panel: HTMLDivElement | undefined
+  let face: HTMLElement | undefined
+  const close = () => (open.value = false)
+  const follow = (el: HTMLElement) => {
+    moveShuttle(face!, el.offsetTop, el.offsetTop + el.offsetHeight)
+    face!.setAttribute('data-on', '')
+  }
+  onMount(() => {
+    const onToggle = (e: ToggleEvent) => {
+      if (e.newState === 'open') face!.setAttribute('data-instant', '')
+      else {
+        face!.removeAttribute('data-on')
+        face!.style.removeProperty('--warp-a')
+      }
+    }
+    panel!.addEventListener('beforetoggle', onToggle)
+    onCleanup(() => panel!.removeEventListener('beforetoggle', onToggle))
+  })
+  // the panel is shown before menu() moves focus in, so the first move lands without travelling
+  const syncOpen = (el: HTMLElement, o: { open: boolean; at: 'first' | 'last' }) => {
+    const opts = () => ({ open: o.open, at: o.at, trigger: () => button, side, align, onClose: close })
+    if (o.open) el.showPopover?.()
+    const m = menu(el, opts())
+    return {
+      update(n: typeof o) {
+        o = n
+        if (n.open && !el.matches(':popover-open')) el.showPopover?.()
+        m.update(opts())
+        if (!n.open && el.matches(':popover-open')) el.hidePopover?.()
+        if (n.open) requestAnimationFrame(() => requestAnimationFrame(() => face?.removeAttribute('data-instant')))
+      },
+      destroy() { m.destroy() },
+    }
+  }
+  use(syncOpen, () => panel, () => ({ open: open.value, at: at.value }))
+  const onKey = (e: KeyboardEvent) => {
+    if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return
+    e.preventDefault()
+    at.value = e.key === 'ArrowUp' ? 'last' : 'first'
+    open.value = true
+  }
+  const pick = (e: { onSelect?: () => void }) => { close(); button?.focus(); e.onSelect?.() }
+  return (
+    <>
+      <Button emphasis="outline" tone="neutral" {...(trigger ?? {})} ref={(el: HTMLButtonElement) => (button = el)} id={`${id}-b`} aria-haspopup="menu" aria-expanded={open.value ? 'true' : 'false'} aria-controls={id} onClick={() => { at.value = 'first'; open.value = !open.value }} onKeyDown={onKey}>
+        {label}
+      </Button>
+      <div
+        ref={n => (panel = n)}
+        data-scope="menu"
+        data-part="content"
+        role="menu"
+        popover="manual"
+        id={id}
+        aria-labelledby={`${id}-b`}
+        onFocusIn={(e: FocusEvent) => { const t = (e.target as HTMLElement).closest?.<HTMLElement>('[role="menuitem"]'); if (t) follow(t) }}
+        onPointerMove={(e: PointerEvent) => { const t = (e.target as HTMLElement).closest?.<HTMLElement>('[role="menuitem"]:not([aria-disabled="true"])'); if (t && t !== document.activeElement) t.focus({ preventScroll: true }) }}
+      >
+        <span ref={n => (face = n)} data-part="shuttle" aria-hidden="true"></span>
+        {items.map((e, i) => 'separator' in e
+          ? <div key={i} data-part="separator" role="separator"></div>
+          : 'group' in e
+            ? <div key={i} data-part="group-label">{e.group}</div>
+            : e.href && !e.disabled
+              ? <a key={i} href={e.href} data-part="item" role="menuitem" tabindex="-1" data-tone={e.tone} onClick={() => pick(e)}><Row e={e} /></a>
+              : <div key={i} data-part="item" role="menuitem" tabindex="-1" data-tone={e.tone} aria-disabled={e.disabled ? 'true' : undefined} onClick={() => { if (!e.disabled) pick(e) }}><Row e={e} /></div>)}
+      </div>
+    </>
+  )
+}

package/src/Modal.tsx

@@ -0,0 +1,40 @@
+import { XIcon } from '@weft-js/warp-icons'
+import { dialog, uid } from '@weft-js/warp-core'
+import { derived, untrack, type State } from '@weft-js/core'
+import type { Tone } from './Button'
+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/dialog.css'
+
+/**
+ * A modal dialog on the native <dialog> (05 §3; components.html:1067-1090): showModal, focus to [autofocus] or the
+ * title, back to the opener on every close path, scroll lock by CSS. Named by its title, described by its
+ * description. `open` is a box: the dialog writes false when the user closes it. `alert` makes it an alert dialog
+ * (no backdrop dismiss; focus Cancel by giving it autofocus). `inline` draws it open in the page's flow, for docs and
+ * previews: a non-modal <dialog open> with no top layer, scrim, focus trap or scroll lock; `open` still shows and hides it.
+ */
+export function Modal({ open, title, description, footer, size, placement, alert, tone, mark, inline, children }: { open: State<boolean>; title: unknown; description?: unknown; footer?: unknown; size?: 'sm' | 'md' | 'lg' | undefined; /** Where it sits, and the edge it arrives from. */ placement?: 'center' | 'top' | 'bottom' | 'left' | 'right' | 'full' | undefined; alert?: boolean | undefined; tone?: Tone | undefined; /** Drawn above the title (09's result mark). */ mark?: unknown; /** 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('dlg')
+  const hasDescription = derived(() => description !== undefined)
+  const sign = derived(() => mark)
+  const foot = derived(() => footer) // one build of the footer, however often it is read
+  let el: HTMLDialogElement | undefined
+  const flat = untrack(() => !!inline)
+  if (!flat) use(dialog, () => el, () => ({ open: open.value, onClose: () => (open.value = false) }))
+  // inline: [data-close] still closes it, by `open`, as the dialog action would
+  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="dialog" role={alert ? 'alertdialog' : undefined} data-size={size === 'md' ? undefined : size} data-placement={placement === 'center' ? undefined : placement} data-tone={tone} aria-labelledby={`${id}-t`} aria-describedby={hasDescription.value ? `${id}-d` : undefined}>
+      <div data-part="header">
+        {sign.value}
+        <h2 data-part="title" id={`${id}-t`}>{title}</h2>
+        {hasDescription.value && <p data-part="description" id={`${id}-d`}>{description}</p>}
+        {/* <Button emphasis="ghost" tone="neutral" icon={XIcon} label="Close"> as its markup: a ghost button needs no JS */}
+        <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/MonthPicker.tsx

@@ -0,0 +1,190 @@
+import { DownIcon, LeftIcon, RightIcon } from '@weft-js/warp-icons'
+import { addDays, dow, fmt, fmtRange, isoWeek, isoWeekStart, pad, toIso, weekOf, ymd, type ChangeReason, type IsoMonth, type IsoWeek } from '@weft-js/warp-core'
+import { derived, flush, state, untrack } from '@weft-js/core'
+import { Button } from './Button'
+import { CalendarGrid } from './Calendar'
+import { bindable, Composite, Hidden, Panel, useOpen, usePickerEnv, type Bindable, type Openable, type RichFieldProps } from './Picker'
+import '@weft-js/warp-core/styles/rich/monthgrid.css'
+import '@weft-js/warp-core/styles/rich/gap-rows.css'
+
+export type Cell = { v: string; text: string; name: string }
+
+/**
+ * The period grid (04 §2): a title with arrows over rows of cells, one tab stop. ←/→ ±1, ↑/↓ ± a row, PageUp/PageDown
+ * a page, Enter/Space picks; cells are named in full.
+ */
+function PeriodGrid({ title, cells, columns, value, current, prev, next, onPage, onPick, wide }: { title: string; cells: Cell[]; columns: number; value: string | null; current: string; prev: string; next: string; onPage: (d: number) => void; onPick: (v: string, r: ChangeReason) => void; wide?: boolean }) {
+  const at = state(untrack(() => value ?? current))
+  let box: HTMLDivElement | undefined
+  const rows = derived(() => Array.from({ length: Math.ceil(cells.length / columns) }, (_, r) => ({ k: cells[r * columns]!.v, cells: cells.slice(r * columns, r * columns + columns) })))
+  const stop = derived(() => (cells.some(c => c.v === at.value) ? at.value : cells[0]!.v))
+  const focus = () => { flush(); box?.querySelector<HTMLElement>('[role="gridcell"][tabindex="0"]')?.focus() }
+  const onKey = (e: KeyboardEvent) => {
+    const el = (e.target as Element).closest?.<HTMLElement>('[data-v]')
+    if (!el) return
+    const i = cells.findIndex(c => c.v === el.dataset.v)
+    const d = ({ ArrowLeft: -1, ArrowRight: 1, ArrowUp: -columns, ArrowDown: columns } as Record<string, number>)[e.key]
+    if (d) {
+      e.preventDefault()
+      if (i + d < 0) onPage(-1)
+      else if (i + d >= cells.length) onPage(1)
+      else at.value = cells[i + d]!.v
+      focus()
+    } else if (e.key === 'PageUp' || e.key === 'PageDown') { e.preventDefault(); onPage(e.key === 'PageUp' ? -1 : 1); focus() }
+    else if (e.key === 'Home' || e.key === 'End') { e.preventDefault(); at.value = cells[e.key === 'Home' ? 0 : cells.length - 1]!.v; focus() }
+    else if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); onPick(cells[i]!.v, 'keyboard') }
+  }
+  return (
+    <div ref={n => (box = n)} data-scope="monthgrid" onKeyDown={onKey}>
+      <div data-part="head">
+        <Button emphasis="ghost" size="sm" icon={LeftIcon} label={prev} data-icon="" onClick={() => onPage(-1)} />
+        <b aria-live="polite">{title}</b>
+        <Button emphasis="ghost" size="sm" icon={RightIcon} label={next} data-icon="" onClick={() => onPage(1)} />
+      </div>
+      <div role="grid" aria-label={title} class={wide ? 'pg' : undefined} style={wide ? `--c:${columns}` : undefined}>
+        {rows.value.map(r => (
+          <div key={r.k} role="row">
+            {r.cells.map(c => <button key={c.v} type="button" role="gridcell" data-v={c.v} data-initial={c.v === stop.value ? '' : undefined} tabindex={c.v === stop.value ? '0' : '-1'} aria-selected={c.v === value ? 'true' : 'false'} aria-current={c.v === current ? 'date' : undefined} onClick={() => onPick(c.v, 'pointer')}><span aria-hidden="true">{c.text}</span><span class="sr">{c.name + (c.v === current ? ', this period' : '')}</span></button>)}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+const monthCells = (year: number, locale: string): Cell[] => Array.from({ length: 12 }, (_, i) => ({ v: `${year}-${pad(i + 1)}`, text: fmt(toIso(year, i + 1, 1), { month: 'short' }, locale), name: fmt(toIso(year, i + 1, 1), { month: 'long', year: 'numeric' }, locale) }))
+const yearOf = (v: string | null, today: string) => +(v ?? today).slice(0, 4)
+
+/** The `pick` button of a field whose whole control opens its panel. */
+function PickButton({ el, text, label, open, disabled, onToggle }: { el: (b: HTMLButtonElement) => void; text: string; label: string; open: boolean; disabled?: boolean | undefined; onToggle: () => void }) {
+  return (
+    <button ref={n => el(n)} type="button" data-part="pick" aria-haspopup="dialog" aria-expanded={open ? 'true' : 'false'} aria-label={label} disabled={disabled} onClick={onToggle}>
+      <span>{text}</span><DownIcon />
+    </button>
+  )
+}
+
+/** Props for MonthPicker. */
+export type MonthPickerProps = RichFieldProps & Bindable<IsoMonth | null> & Openable & { min?: IsoMonth | undefined; max?: IsoMonth | undefined }
+
+/** MonthPicker (04 §2): a 3×4 grid of the locale's short month names with year arrows. */
+export function MonthPicker({ value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, locale, today, name, presentation, label, disabled, ...rest }: MonthPickerProps) {
+  const env = usePickerEnv(() => locale, () => today)
+  const v = bindable<IsoMonth | null>(() => value, () => defaultValue, null, () => onValueChange)
+  const pop = useOpen(() => open, () => defaultOpen, () => onOpenChange)
+  const year = state(yearOf(untrack(() => v.value), untrack(() => env.today.value)))
+  const shown = derived(() => (v.value ? fmt(`${v.value}-01`, { month: 'long', year: 'numeric' }, env.locale.value) : ''))
+  let trigger: HTMLButtonElement | undefined
+  return (
+    <Composite
+      {...rest}
+      label={label}
+      disabled={disabled}
+      bound={v}
+      filled={!!v.value}
+      hold={pop.value}
+      control={() => <><PickButton el={n => (trigger = n)} text={shown.value} label={`${label}, ${shown.value || 'none'}`} open={pop.value} disabled={disabled} onToggle={() => pop.set(!pop.value)} /><Hidden name={name} value={() => v.value ?? ''} /></>}
+      end={
+        <Panel label="Choose a month" open={pop} trigger={() => trigger!} presentation={presentation}>
+          {() => <PeriodGrid title={String(year.value)} cells={monthCells(year.value, env.locale.value)} columns={3} value={v.value} current={env.today.value.slice(0, 7)} prev="Previous year" next="Next year" onPage={d => (year.value += d)} onPick={(x, r) => { v.set(x as IsoMonth, r); pop.set(false) }} />}
+        </Panel>
+      }
+    />
+  )
+}
+
+/** WeekPicker's props: a field whose value is an ISO week, or null. */
+export type WeekPickerProps = RichFieldProps & Bindable<IsoWeek | null> & Openable & {
+  /** The day each grid row starts on: `iso` (the default) starts on Monday, so a row is one ISO 8601 week; `locale` starts on the locale's first day of the week. The value is an ISO week either way. */
+  numbering?: 'iso' | 'locale'
+}
+
+const weekName = (w: string, locale: string) => {
+  const s = isoWeekStart(w)
+  return `Week ${+w.slice(6)}, ${fmtRange(s, addDays(s, 6), locale, { month: 'long', day: 'numeric', year: 'numeric' })}`
+}
+
+/** WeekPicker (04 §2): the month grid with a leading week number; selection covers the whole row. */
+export function WeekPicker({ value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, numbering = 'iso', locale, today, name, presentation, label, disabled, ...rest }: WeekPickerProps) {
+  const env = usePickerEnv(() => locale, () => today)
+  const v = bindable<IsoWeek | null>(() => value, () => defaultValue, null, () => onValueChange)
+  const pop = useOpen(() => open, () => defaultOpen, () => onOpenChange)
+  const shown = derived(() => (v.value ? `Week ${+v.value.slice(6)}, ${v.value.slice(0, 4)}` : ''))
+  let trigger: HTMLButtonElement | undefined
+  return (
+    <Composite
+      {...rest}
+      label={label}
+      disabled={disabled}
+      bound={v}
+      filled={!!v.value}
+      hold={pop.value}
+      control={() => <><PickButton el={n => (trigger = n)} text={shown.value} label={v.value ? `${label}, ${shown.value}, ${weekName(v.value, env.locale.value)}` : `${label}, none`} open={pop.value} disabled={disabled} onToggle={() => pop.set(!pop.value)} /><Hidden name={name} value={() => v.value ?? ''} /></>}
+      end={
+        <Panel label="Choose a week" open={pop} trigger={() => trigger!} presentation={presentation}>
+          {() => <CalendarGrid mode="week" value={() => v.value} firstDayOfWeek={numbering === 'iso' ? 1 : undefined} weekNumbers locale={env.locale.value} today={env.today.value} autofocus onPick={(iso, r) => { v.set(weekOf(iso), r); pop.set(false) }} />}
+        </Panel>
+      }
+    />
+  )
+}
+
+export type Granularity = 'year' | 'quarter' | 'month' | 'week'
+/** Props for PeriodPicker. */
+export type PeriodPickerProps = RichFieldProps & Bindable<string | null> & Openable & { granularity?: Granularity }
+
+const granularityOf = (v: string | null | undefined): Granularity => (!v ? 'month' : /-W/.test(v) ? 'week' : /-Q/.test(v) ? 'quarter' : /-/.test(v) ? 'month' : 'year')
+
+/** A period value in words (`Q4 2026`, `October 2026`, `Week 44, 2026`). */
+function periodText(v: string, locale: string) {
+  const g = granularityOf(v)
+  return g === 'year' ? v : g === 'quarter' ? `Q${v.slice(-1)} ${v.slice(0, 4)}` : g === 'month' ? fmt(`${v}-01`, { month: 'long', year: 'numeric' }, locale) : `Week ${+v.slice(6)}, ${v.slice(0, 4)}`
+}
+
+function periodCells(g: Granularity, year: number, locale: string): Cell[] {
+  if (g === 'year') { const b = Math.floor(year / 12) * 12; return Array.from({ length: 12 }, (_, i) => ({ v: `${b + i}`, text: `${b + i}`, name: `${b + i}` })) }
+  if (g === 'quarter') return [1, 2, 3, 4].map(q => ({ v: `${year}-Q${q}`, text: `Q${q}`, name: `Q${q} ${year}, ${fmt(toIso(year, q * 3 - 2, 1), { month: 'short' }, locale)} to ${fmt(toIso(year, q * 3, 1), { month: 'short' }, locale)}` }))
+  if (g === 'month') return monthCells(year, locale)
+  const out: Cell[] = []
+  let d = toIso(year, 1, 4) as string
+  d = addDays(d, -((dow(d) + 6) % 7))
+  for (let i = 0; i < 53; i++, d = addDays(d, 7)) {
+    const w = isoWeek(d)
+    if (w.year !== year) break
+    out.push({ v: `${w.year}-W${pad(w.week)}`, text: `W${w.week}`, name: `Week ${w.week}, ${fmt(d, { month: 'short', day: 'numeric' }, locale)} to ${fmt(addDays(d, 6), { month: 'short', day: 'numeric', year: 'numeric' }, locale)}` })
+  }
+  return out
+}
+
+/** PeriodPicker (04 §2): one trigger, one grid whose granularity switches. Values: `2026`, `2026-Q4`, `2026-10`, `2026-W44`. */
+export function PeriodPicker({ value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, granularity, locale, today, name, presentation, label, disabled, ...rest }: PeriodPickerProps) {
+  const env = usePickerEnv(() => locale, () => today)
+  const v = bindable<string | null>(() => value, () => defaultValue, null, () => onValueChange)
+  const pop = useOpen(() => open, () => defaultOpen, () => onOpenChange)
+  const g = derived(() => granularity ?? granularityOf(v.value))
+  const year = state(yearOf(untrack(() => v.value), untrack(() => env.today.value)))
+  const shown = derived(() => (v.value ? periodText(v.value, env.locale.value) : ''))
+  const span = derived(() => { const b = Math.floor(year.value / 12) * 12; return g.value === 'year' ? `${b}–${b + 11}` : String(year.value) })
+  const current = derived(() => {
+    const t = env.today.value
+    const [y, m] = ymd(t)
+    return { year: `${y}`, quarter: `${y}-Q${Math.ceil(m / 3)}`, month: t.slice(0, 7), week: weekOf(t) }[g.value]
+  })
+  let trigger: HTMLButtonElement | undefined
+  return (
+    <Composite
+      {...rest}
+      label={label}
+      disabled={disabled}
+      bound={v}
+      filled={!!v.value}
+      hold={pop.value}
+      control={() => <><PickButton el={n => (trigger = n)} text={shown.value} label={`${label}, ${shown.value || 'none'}`} open={pop.value} disabled={disabled} onToggle={() => pop.set(!pop.value)} /><Hidden name={name} value={() => v.value ?? ''} /></>}
+      end={
+        <Panel label="Choose a period" open={pop} trigger={() => trigger!} presentation={presentation}>
+          {() => <PeriodGrid wide title={span.value} cells={periodCells(g.value, year.value, env.locale.value)} columns={g.value === 'quarter' ? 4 : g.value === 'week' ? 7 : 3} value={v.value} current={current.value} prev="Previous" next="Next" onPage={d => (year.value += d * (g.value === 'year' ? 12 : 1))} onPick={(x, r) => { v.set(x, r); pop.set(false) }} />}
+        </Panel>
+      }
+    />
+  )
+}

package/src/Nav.tsx

@@ -0,0 +1,20 @@
+import { navIndicator } from '@weft-js/warp-core'
+import { use } from '@weft-js/warp-core/weft'
+import './styles'
+import '@weft-js/warp-core/styles/components/nav.css'
+
+/**
+ * Links with warp's sliding bar. It grows in from an item's edge, slides as the route or the pointer moves, and grows
+ * out through the far edge. Mark the current link with `aria-current` (`Link` from `@weft-js/start` does). `spy` follows
+ * the headings of a table of contents. The bar is on the current link in the server's HTML, so nothing moves on load.
+ */
+export function Nav({ label, axis = 'x', spy, children, ...rest }: { label: string; axis?: 'x' | 'y'; spy?: boolean | undefined; children?: unknown; [attr: string]: unknown }) {
+  let el: HTMLElement | undefined
+  use(navIndicator, () => el, () => ({ axis, spy }))
+  return (
+    <nav {...rest} ref={n => (el = n)} data-scope="nav" data-axis={axis} aria-label={label}>
+      {children}
+      <span data-part="indicator" aria-hidden="true"></span>
+    </nav>
+  )
+}

package/src/NumberField.tsx

@@ -0,0 +1,78 @@
+import { DownIcon } from '@weft-js/warp-icons'
+import { derived, untrack } from '@weft-js/core'
+import { bindable, type Bindable } from './bind'
+import { Field, type FieldShell } from './Field'
+import '@weft-js/warp-core/styles/inputs/text.css'
+
+/** Props for NumberField. */
+export type NumberFieldProps = FieldShell & Bindable<number | null> & { min?: number; max?: number; step?: number; name?: string; required?: boolean }
+
+const PAGE = 10
+
+/**
+ * A number in the field shell (03: `inputmode` over `type="number"`, which changes on a wheel, takes "e" and has its own
+ * locale bugs). The input stays real text, so editing, paste and the numeric keypad are the OS's; warp adds APG spinbutton
+ * keys (↑/↓, Page keys, Home/End with a bound) and two steppers. Text that isn't a number leaves the value alone until blur.
+ */
+export function NumberField({ value, defaultValue, onValueChange, min, max, step = 1, name, disabled, readonly, ...rest }: NumberFieldProps) {
+  const v = bindable<number | null>(() => value, () => defaultValue, null, () => onValueChange)
+  const fit = (n: number) => Math.min(max ?? Infinity, Math.max(min ?? -Infinity, n))
+  const shown = derived(() => (v.value === null ? '' : String(v.value)))
+  let input: HTMLInputElement | undefined
+  const write = (n: number | null) => {
+    if (n !== untrack(() => v.value)) v.set(n, 'keyboard')
+    if (input) input.value = n === null ? '' : String(n)
+  }
+  const nudge = (by: number) => write(fit((untrack(() => v.value) ?? min ?? 0) + by))
+  const onKey = (e: KeyboardEvent) => {
+    if (disabled || readonly) return
+    const by = ({ ArrowUp: step, ArrowDown: -step, PageUp: step * PAGE, PageDown: -step * PAGE } as Record<string, number>)[e.key]
+    if (by) { e.preventDefault(); return nudge(by) }
+    if (e.key === 'Home' && min !== undefined) { e.preventDefault(); write(min) }
+    if (e.key === 'End' && max !== undefined) { e.preventDefault(); write(max) }
+  }
+  const onInput = (e: Event) => {
+    const text = (e.currentTarget as HTMLInputElement).value.trim()
+    const n = Number(text)
+    if (text === '') v.set(null, 'keyboard')
+    else if (Number.isFinite(n)) v.set(fit(n), 'keyboard')
+  }
+  const onBlur = () => { if (input) input.value = untrack(() => shown.value) }
+  const stepper = (label: string, by: number, off: boolean) => (
+    <button type="button" data-part="step" tabindex="-1" aria-label={label} disabled={disabled || readonly || off} onMouseDown={(e: Event) => e.preventDefault()} onClick={() => nudge(by)}><DownIcon /></button>
+  )
+  return (
+    <Field
+      {...rest}
+      disabled={disabled}
+      readonly={readonly}
+      filled={shown.value !== ''}
+      end={<span data-part="steps">{stepper('Increase', step, max !== undefined && v.value !== null && v.value >= max)}{stepper('Decrease', -step, min !== undefined && v.value !== null && v.value <= min)}</span>}
+      control={p => (
+        <input
+          ref={n => (input = n)}
+          data-part="input"
+          id={p.id}
+          role="spinbutton"
+          type="text"
+          inputmode={step % 1 || (min ?? 0) < 0 ? 'decimal' : 'numeric'}
+          autocomplete="off"
+          name={name}
+          placeholder=" "
+          required={p.rest.required}
+          disabled={disabled}
+          readonly={readonly}
+          value={shown.value}
+          aria-valuenow={v.value ?? undefined}
+          aria-valuemin={min}
+          aria-valuemax={max}
+          aria-describedby={p.describedby}
+          aria-invalid={p.invalid ? 'true' : undefined}
+          onInput={onInput}
+          onKeyDown={onKey}
+          onBlur={onBlur}
+        />
+      )}
+    />
+  )
+}

package/src/Pagination.tsx

@@ -0,0 +1,122 @@
+import { infiniteScroll, pageList, uid } from '@weft-js/warp-core'
+import { derived, flush, untrack, type State } from '@weft-js/core'
+import { Button } from './Button'
+import { bindable } from './bind'
+import { CompactSelect } from './Select'
+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/pagination.css'
+import '@weft-js/warp-core/styles/data/load-more.css'
+
+/** Props for PaginationBar. */
+export type PaginationBarProps = {
+  /** The nav landmark's name; give each bar on a page its own. */
+  label?: string
+  /** offset (default): numbered pages. cursor: Previous and Next, for a list with no page count. */
+  mode?: 'offset' | 'cursor'
+  /** 1-based. */
+  page?: State<number> | number
+  /** The page it opens on when `page` isn't given. */
+  defaultPage?: number
+  /** Hears the new page (offset) or page index (cursor) on every move. */
+  onPageChange?: (page: number) => void
+  /** offset: how many rows there are. */
+  total?: number
+  /** Rows per page: a State to share it, or a number. 25 without it. */
+  size?: State<number> | number
+  /** The choices in the rows-per-page menu. */
+  sizes?: number[]
+  /** Hears a new rows-per-page choice; the bar goes back to page 1. */
+  onSizeChange?: (size: number) => void
+  /** cursor: there is a page after this one, so Next is on. */
+  hasMore?: boolean
+  /** cursor: there is a page before this one, so Previous is on. */
+  hasPrev?: boolean
+  /** cursor: the 0-based page showing, which `onPageChange` steps from. */
+  pageIndex?: number
+  /** cursor: how many rows there are in all, when known ("Showing 50 of 1,200"). */
+  supply?: number
+  /** cursor: how many rows have loaded so far; `(pageIndex + 1) * size` without it. */
+  totalFetched?: number
+  /** The locale its numbers are written in. en-US without it. */
+  locale?: string
+}
+
+/**
+ * The pagination bar (06 §8; data.html:1893-1913). Offset mode: rows per page, the range, ‹ 1 … 4 5 6 … 100 › and Go to;
+ * under 520px of its own width only ‹ current › remain and the range says the rest. Cursor mode: Previous and Next,
+ * and how many are showing. A press keeps focus on the current page, whichever button that now is.
+ */
+export function PaginationBar({ label = 'Pagination', mode = 'offset', page, defaultPage, onPageChange, total = 0, size, sizes = [10, 25, 50, 100], onSizeChange, hasMore, hasPrev, pageIndex = 0, supply, totalFetched, locale }: PaginationBarProps) {
+  const at = bindable<number>(() => page, () => defaultPage, 1, () => p => onPageChange?.(p))
+  const per = bindable<number>(() => size, () => undefined, 25, () => s => onSizeChange?.(s))
+  const pages = derived(() => Math.max(1, Math.ceil(total / per.value)))
+  const current = derived(() => Math.min(pages.value, Math.max(1, at.value)))
+  const fmt = (n: number) => n.toLocaleString(locale ?? 'en-US')
+  let nav: HTMLElement | undefined
+  const go = (p: number) => {
+    at.set(Math.min(pages.value, Math.max(1, p)))
+    flush()
+    nav?.querySelector<HTMLElement>('[aria-current="page"]')?.focus()
+  }
+  const jump = (e: KeyboardEvent) => {
+    if (e.key !== 'Enter') return
+    e.preventDefault()
+    const box = e.currentTarget as HTMLInputElement
+    const n = parseInt(box.value, 10)
+    if (n) at.set(Math.min(pages.value, Math.max(1, n)))
+    box.value = ''
+  }
+  if (untrack(() => mode) === 'cursor') {
+    return (
+      <nav data-scope="pagination" aria-label={label}>
+        <span>{`Showing ${fmt(totalFetched ?? (pageIndex + 1) * per.value)}${supply !== undefined ? ` of ${fmt(supply)}` : ''}${hasMore ? ' · more available' : ''}`}</span>
+        <span data-part="spacer"></span>
+        <ol>
+          <li><Button emphasis="outline" tone="neutral" size="sm" disabled={!hasPrev} onClick={() => onPageChange?.(pageIndex - 1)}>Previous</Button></li>
+          <li><Button emphasis="outline" tone="neutral" size="sm" disabled={!hasMore} onClick={() => onPageChange?.(pageIndex + 1)}>Next</Button></li>
+        </ol>
+      </nav>
+    )
+  }
+  const id = uid('pg')
+  const first = derived(() => (total ? (current.value - 1) * per.value + 1 : 0))
+  // "Go to" and its box are one item, so the bar never wraps between them: the pair moves to the next line together
+  return (
+    <nav ref={n => (nav = n)} data-scope="pagination" aria-label={label}>
+      <span data-part="field">
+        <span aria-hidden="true">Rows<span data-part="long"> per page</span></span>
+        <CompactSelect label="Rows per page" value={String(per.value)} options={sizes.map(s => ({ value: String(s), label: String(s) }))} onValueChange={v => { per.set(+v); at.set(1) }} />
+      </span>
+      <span>{`${fmt(first.value)}–${fmt(Math.min(total, current.value * per.value))} of ${fmt(total)}`}</span>
+      <span data-part="spacer"></span>
+      <ol>
+        <li><button type="button" data-part="page" data-edge="" disabled={current.value === 1} aria-label="Previous page" onClick={() => go(current.value - 1)}>‹</button></li>
+        {pageList(current.value, pages.value).map((p, i) => <li key={p === 'gap' ? `gap${i}` : p} data-part={p === 'gap' ? 'gap' : undefined} aria-hidden={p === 'gap' ? 'true' : undefined}>{p === 'gap' ? '…' : <button type="button" data-part="page" aria-current={p === current.value ? 'page' : undefined} aria-label={`Page ${p}`} onClick={() => go(p)}>{p}</button>}</li>)}
+        <li><button type="button" data-part="page" data-edge="" disabled={current.value === pages.value} aria-label="Next page" onClick={() => go(current.value + 1)}>›</button></li>
+      </ol>
+      <span data-part="field" data-goto="">
+        <label for={`${id}-go`}>Go to<span data-part="sr-only"> page</span></label>
+        <input id={`${id}-go`} data-part="jump" inputmode="numeric" placeholder={String(pages.value)} onKeyDown={jump} />
+      </span>
+    </nav>
+  )
+}
+
+/**
+ * Load more (06 §8): a sentinel watched with a 120px margin, and a button that is always there as the fallback. Set
+ * `loading` while a page is on its way (the list shows its skeletons and `aria-busy`); `done` swaps in the end message.
+ */
+export function LoadMore({ onLoad, loading, done, message, auto = true, root }: { onLoad: () => void; loading?: boolean | undefined; done?: boolean; message?: unknown; auto?: boolean; root?: (() => HTMLElement | null) | undefined }) {
+  let el: HTMLDivElement | undefined
+  const reach = () => { if (auto && !loading && !done) onLoad() }
+  use(infiniteScroll, () => el, () => ({ onReach: reach, root: root?.() }))
+  return (
+    <div ref={n => (el = n)} data-scope="load-more">
+      <span aria-live="polite">{loading ? 'Loading…' : message}</span>
+      {!done && <Button emphasis="outline" tone="neutral" disabled={!!loading} onClick={onLoad}>Load more</Button>}
+    </div>
+  )
+}

package/src/PaymentCard.tsx

@@ -0,0 +1,63 @@
+import { CardIcon } from '@weft-js/warp-icons'
+import { cardBrand, cardMask } from '@weft-js/warp-core'
+import { derived, state, untrack } from '@weft-js/core'
+import { Field, type FieldShell } from './Field'
+import { use } from '@weft-js/warp-core/weft'
+import '@weft-js/warp-core/styles/rich/payment.css'
+
+/** The card field a payment provider mounts, as far as warp talks to it. */
+export interface ProviderField { on(e: 'focus' | 'blur' | 'change', f: (ev: { complete?: boolean | undefined; error?: string | undefined }) => void): void; destroy(): void }
+/** The field styles warp hands a provider, since its iframe can't read ours. */
+export interface ProviderAppearance { fontFamily: string; fontSize: string; color: string; errorColor: string; borderRadius: string; borderColor: string }
+/** Props for PaymentCardInput. */
+export type PaymentCardInputProps = FieldShell & { mount: (el: HTMLElement, appearance: ProviderAppearance) => ProviderField }
+
+/**
+ * PaymentCardInput (04 §5): the field shell around the provider's hosted field, driven by its events, with warp's
+ * tokens passed into its appearance API. warp never renders an input for a raw card number.
+ */
+export function PaymentCardInput({ mount, label, hint, error, ...rest }: PaymentCardInputProps) {
+  const focused = state(false)
+  const filled = state(false)
+  const failed = state<string | undefined>(undefined)
+  let host: HTMLDivElement | undefined
+  const attach = (el: HTMLDivElement) => {
+    const css = getComputedStyle(el)
+    const token = (t: string) => css.getPropertyValue(`--warp-${t}`).trim()
+    const field = untrack(() => mount)(el, { fontFamily: css.fontFamily, fontSize: token('text-control-size'), color: token('color-text'), errorColor: token('color-critical-text'), borderRadius: token('radius-control'), borderColor: token('color-border-control') })
+    field.on('focus', () => (focused.value = true))
+    field.on('blur', () => (focused.value = false))
+    field.on('change', ev => { filled.value = ev.complete ?? filled.value; failed.value = ev.error })
+    return { update() {}, destroy: () => field.destroy() }
+  }
+  use(attach, () => host)
+  return (
+    <Field
+      icon={CardIcon}
+      {...rest}
+      group
+      label={label}
+      hint={hint ?? 'Secured by your payment provider. warp never sees the number.'}
+      error={error ?? failed.value}
+      filled={filled.value}
+      hold={focused.value}
+      control={() => <div ref={n => (host = n)} data-part="provider" role="group" aria-label={`${label}, hosted by the payment provider`}></div>}
+    />
+  )
+}
+
+/** Props for CardNumberText. */
+export type CardNumberTextProps = { last4: string; bin?: string; brand?: string; expiry?: { month: number; year: number } }
+
+/** CardNumberText (04 §5): the display of a saved card, `•••• 4242`, with the brand from the BIN and expiry as MM/YY. */
+export function CardNumberText({ last4, bin, brand, expiry }: CardNumberTextProps) {
+  const name = derived(() => brand ?? cardBrand(bin ?? ''))
+  const exp = derived(() => (expiry ? `${String(expiry.month).padStart(2, '0')}/${String(expiry.year % 100).padStart(2, '0')}` : ''))
+  // a span can't be named (aria-prohibited-attr): the mask is hidden from screen readers and the words are said instead
+  return (
+    <span data-card-text="">
+      <span aria-hidden="true">{name.value ? `${name.value} ` : ''}{cardMask(last4, name.value)}{exp.value ? ` · ${exp.value}` : ''}</span>
+      <span data-part="sr-only">{`${name.value || 'Card'} ending ${last4}`}{exp.value ? `, expires ${exp.value}` : ''}</span>
+    </span>
+  )
+}