@weft-js/warp 0.0.0-stage → 0.1.0

package/src/flow/AuthSteps.tsx

@@ -0,0 +1,120 @@
+import { KeyIcon, LeftIcon, MailIcon } from '@weft-js/warp-icons'
+import { clockLabel, emailError, passwordRules, uid } from '@weft-js/warp-core'
+import { derived, onCleanup, onMount, state, untrack } from '@weft-js/core'
+import { Avatar } from '../parts'
+import { Badge } from '../Badge'
+import { Button } from '../Button'
+import { Input } from '../Field'
+import { FormError, Mark, Rail, StepFrame, Submit, TextLink, Title, useCooldown, useStepForm, type FlowForm, type Heading } from './kit'
+import { PasswordMeter } from './SignUp'
+import '../styles'
+import '@weft-js/warp-core/styles/flows/auth.css'
+import '@weft-js/warp-core/styles/layout/row.css'
+
+const Back = ({ onBack }: { onBack: () => void }) => <div><Button emphasis="ghost" tone="neutral" size="sm" icon={LeftIcon} onClick={onBack}>Back</Button></div>
+
+/** "Check your inbox" (09 §2.1): waiting, so no solid; the address, Open mail app, resend on a countdown, change email. */
+export function MagicLinkSent({ email, title, lede, heading, resendIn = 30, mailHref, onResend, onChangeEmail, onBack }: { email: string; title?: unknown; lede?: unknown; heading?: Heading; resendIn?: number; /** Shows Open email app (phones). */ mailHref?: string; onResend?: () => void; onChangeEmail?: () => void; onBack?: () => void }) {
+  const round = state(0)
+  const left = useCooldown(() => (round.value, resendIn))
+  return (
+    <div data-scope="stack">
+      {onBack && <Back onBack={onBack} />}
+      <Mark><MailIcon /></Mark>
+      <div><Title as={heading}>{title ?? 'Check your inbox'}</Title><p data-part="lede">{lede ?? <>We sent a sign-in link to <b>{email}</b>. It works once and expires in 15 minutes.</>}</p></div>
+      {mailHref && <Button emphasis="frame" full role="link" onClick={() => location.assign(mailHref)}>Open email app</Button>}
+      <div data-part="row">
+        {onResend && <TextLink disabled={left.value > 0} onClick={() => { onResend(); round.value++ }}>{left.value > 0 ? `Resend in ${clockLabel(left.value)}` : 'Resend link'}</TextLink>}
+        {onChangeEmail && <TextLink onClick={onChangeEmail}>Use a different email</TextLink>}
+      </div>
+    </div>
+  )
+}
+
+/** What the reset form collects, across its two steps. */
+export interface ResetValues { email?: string; password?: string; confirm?: string }
+
+/** Props for ResetPassword. */
+export interface ResetPasswordProps extends FlowForm<ResetValues> {
+  /** `request` asks for the email; `password` sets the new one (after the link or the code). */
+  stage?: 'request' | 'password' | undefined
+  onBack?: () => void
+  title?: unknown
+  lede?: unknown
+}
+
+/** Reset (09 §2.1): email → link or code → new password and confirm. Never says whether the email has an account (§2.3). */
+export function ResetPassword(p: ResetPasswordProps) {
+  const id = uid('reset')
+  const stage = untrack(() => p.stage ?? 'request')
+  const password = state('')
+  const ctl = useStepForm<ResetValues>(untrack(() => p), v => (stage === 'request'
+    ? { email: v.email ? emailError(v.email) : 'Enter the email you sign in with.' }
+    : {
+        password: passwordRules(v.password ?? '').every(r => r.met) ? undefined : 'Use at least 8 characters, with a letter and a number.',
+        confirm: v.confirm === v.password ? undefined : "Those passwords don't match.",
+      }))
+  return (
+    <StepFrame ctl={ctl} embedded={!!p.form} labelledby={`${id}-t`}>
+      {p.onBack && <Back onBack={p.onBack} />}
+      <Mark><KeyIcon /></Mark>
+      <div>
+        <Title as={p.heading} id={`${id}-t`}>{p.title ?? (stage === 'request' ? 'Reset your password' : 'Choose a new password')}</Title>
+        <p data-part="lede">{p.lede ?? (stage === 'request' ? "We'll email a link that lets you choose a new one. It expires in 30 minutes." : 'Then sign in with it everywhere.')}</p>
+      </div>
+      <FormError ctl={ctl} />
+      {stage === 'request'
+        ? <Input label="Work email" name="email" type="email" inputmode="email" autocomplete="email" hint="" error={ctl.errors.value.email} onBlur={(e: FocusEvent) => ctl.flag('email', emailError((e.target as HTMLInputElement).value))} />
+        : (
+          <>
+            <div>
+              <Input label="New password" name="password" type="password" autocomplete="new-password" hint="" error={ctl.errors.value.password} onInput={e => (password.value = e.currentTarget.value)} />
+              <PasswordMeter value={password.value} />
+            </div>
+            <Input label="Confirm password" name="confirm" type="password" autocomplete="new-password" hint="" error={ctl.errors.value.confirm} />
+          </>
+        )}
+      <Submit ctl={ctl}>{stage === 'request' ? 'Send reset link' : 'Continue'}</Submit>
+    </StepFrame>
+  )
+}
+
+/** Invite accept (09 §2.1): who invited you, the org and role, "You'll join as…", Join and Decline; `children` holds an inline sign-in or sign-up. */
+export function InviteAccept({ inviter, org, role, email, description, heading, pending, onAccept, onDecline, onOtherAccount, onBack, children }: { inviter: string; org: string; role?: string; email?: unknown; description?: unknown; heading?: Heading; pending?: boolean | undefined; onAccept?: () => void; onDecline?: () => void; onOtherAccount?: () => void; onBack?: () => void; children?: unknown }) {
+  const body = derived(() => children)
+  return (
+    <div data-scope="stack">
+      {onBack && <Back onBack={onBack} />}
+      <div data-scope="row" data-wrap="none">
+        <Avatar name={inviter} size="lg" />
+        <div>
+          <p data-part="lede">{inviter} invited you to</p>
+          <b>{org}</b> {role && <Badge tone="info">{role}</Badge>}
+        </div>
+      </div>
+      <div><Title as={heading}>Join {org}</Title>{email !== undefined && <p data-part="lede">You'll join as <b>{email}</b>. {description}</p>}</div>
+      {body.value !== undefined ? body.value : <Button size="lg" full loading={pending} onClick={onAccept}>Join {org}</Button>}
+      <div data-part="row">
+        {onOtherAccount && <TextLink onClick={onOtherAccount}>Sign in with another account</TextLink>}
+        {onDecline && <Button emphasis="ghost" tone="neutral" size="sm" onClick={onDecline}>Decline</Button>}
+      </div>
+    </div>
+  )
+}
+
+/** Done (09 §2.1): the mark strokes in, then the flow continues after `delay` (at once under reduced motion). */
+export function AuthDone({ title, lede, heading, delay = 1200, onContinue }: { title?: unknown; lede?: unknown; heading?: Heading; delay?: number; onContinue?: (() => void) | undefined }) {
+  onMount(() => {
+    const reduced = matchMedia?.('(prefers-reduced-motion: reduce)')?.matches || document.documentElement.dataset.motion === 'reduce'
+    const t = setTimeout(() => onContinue?.(), reduced ? 0 : untrack(() => delay))
+    onCleanup(() => clearTimeout(t))
+  })
+  return (
+    <div data-scope="stack">
+      <Mark tone="positive" draw />
+      <div><Title as={heading}>{title ?? "You're in"}</Title>{lede !== undefined && <p data-part="lede">{lede}</p>}</div>
+      <div data-scope="row"><Rail value={100} aria-hidden="true" /></div>
+      {onContinue && <Button full size="lg" onClick={onContinue}>Continue</Button>}
+    </div>
+  )
+}

package/src/flow/Checklist.tsx

@@ -0,0 +1,84 @@
+import { XIcon } from '@weft-js/warp-icons'
+import { announce, uid } from '@weft-js/warp-core'
+import { derived, state, watch } from '@weft-js/core'
+import { Button } from '../Button'
+import { Checkbox } from '../Choice'
+import { toast } from '../Toast'
+import { Mark, Rail } from './kit'
+import '@weft-js/warp-core/styles/flows/checklist.css'
+import '@weft-js/warp-core/styles/layout/row.css'
+
+/** One onboarding task. */
+export interface ChecklistItem {
+  id: string
+  title: unknown
+  description?: unknown
+  done?: boolean
+  /** The frame button on the row's end. */
+  action?: { label: string; onClick: () => void } | undefined
+}
+
+/** Props for Checklist. */
+export interface ChecklistProps {
+  title?: unknown
+  subtitle?: unknown
+  /** Derived from server state, never from clicks here: doing the task anywhere checks it. */
+  items: ChecklistItem[]
+  /** A user-checkable list instead; omit it and the boxes only report. */
+  onToggle?: (id: string, done: boolean) => void
+  doneTitle?: unknown
+  doneDescription?: unknown
+  /** Shows Hide; a Toast offers Undo for 10s. */
+  onHide?: () => void
+  onUndoHide?: () => void
+  /** A disclosure on the title (phones: "3 of 5"). */
+  collapsible?: boolean
+  /** A row under the list: "Take the tour". */
+  footer?: unknown
+}
+
+/** The onboarding checklist (09 §3.1): a counter in the head, a rail that fills per item, rows, then "You're set up". */
+export function Checklist({ title = 'Get set up', subtitle, items, onToggle, doneTitle = "You're set up", doneDescription, onHide, onUndoHide, collapsible, footer }: ChecklistProps) {
+  const id = uid('ck')
+  const list = derived(() => items)
+  const count = derived(() => list.value.filter(i => i.done).length)
+  const total = derived(() => list.value.length)
+  const hidden = state(false)
+  const closed = state(false)
+  watch(() => count.value, (n, was) => { if (was !== undefined && n > was) announce(document, n === total.value ? 'All set up.' : `${n} of ${total.value} done.`) })
+  const hide = () => {
+    hidden.value = true
+    onHide?.()
+    toast.show({ title: 'Checklist hidden', description: 'Find it again under Help.', duration: 10000, action: { label: 'Undo', onClick() { hidden.value = false; onUndoHide?.() } } })
+  }
+  return (
+    <section data-scope="checklist" data-state={count.value === total.value && total.value > 0 ? 'complete' : undefined} aria-labelledby={id} hidden={hidden.value || undefined}>
+      <div data-part="head">
+        <div>
+          <h4 data-part="title" id={id} aria-level="3">{title} <span data-part="count">{count.value} of {total.value}</span></h4>
+          {subtitle !== undefined && <p>{subtitle}</p>}
+        </div>
+        <div data-scope="row">
+        {collapsible && <Button emphasis="ghost" tone="neutral" size="sm" aria-expanded={closed.value ? 'false' : 'true'} aria-controls={`${id}-l`} onClick={() => (closed.value = !closed.value)}>{closed.value ? 'Show' : 'Collapse'}</Button>}
+        {onHide && <Button emphasis="ghost" tone="neutral" size="sm" icon={XIcon} label="Hide checklist" onClick={hide} />}
+        </div>
+      </div>
+      <div data-part="progress"><Rail value={total.value ? (count.value / total.value) * 100 : 0} role="progressbar" aria-label="Setup progress" aria-valuemin="0" aria-valuemax={total.value} aria-valuenow={count.value} /></div>
+      <ol id={`${id}-l`} hidden={closed.value || undefined}>
+        {list.value.map(it => (
+          <li key={it.id} data-part="item" data-state={it.done ? 'done' : undefined}>
+            <Checkbox checked={!!it.done} disabled={!onToggle} aria-labelledby={`${id}-${it.id}`} onChange={(e: Event) => onToggle?.(it.id, (e.currentTarget as HTMLInputElement).checked)} />
+            <b id={`${id}-${it.id}`}>{it.title}<span data-part="sr-only">{it.done ? ', done' : ', to do'}</span></b>
+            {it.action ? <Button data-part="action" emphasis="frame" size="sm" onClick={it.action.onClick}>{it.action.label}</Button> : <span></span>}
+            {it.description !== undefined && <p>{it.description}</p>}
+          </li>
+        ))}
+      </ol>
+      <div data-part="done">
+        <Mark tone="positive" draw />
+        <div><b>{doneTitle}</b>{doneDescription !== undefined && <p>{doneDescription}</p>}</div>
+      </div>
+      {footer}
+    </section>
+  )
+}

package/src/flow/ConnBanner.tsx

@@ -0,0 +1,147 @@
+import { ClockIcon, RefreshIcon, SparkleIcon, WifiIcon, WifiOffIcon } from '@weft-js/warp-icons'
+import { announce, connView } from '@weft-js/warp-core'
+import { derived, onCleanup, onMount, state, untrack, watch } from '@weft-js/core'
+import { Button, type ButtonProps } from '../Button'
+import { useCooldown } from './kit'
+import '../styles'
+import '@weft-js/warp-core/styles/flows/tokens.css'
+import '@weft-js/warp-core/styles/flows/base.css'
+import '@weft-js/warp-core/styles/flows/conn.css'
+import '@weft-js/warp-core/styles/components/spinner.css'
+
+type Live<T> = T | { readonly value: T } | (() => { readonly value: T } | T)
+
+const read = <T,>(v: Live<T>): T => {
+  const x = typeof v === 'function' ? (v as () => { readonly value: T } | T)() : v
+  return x !== null && typeof x === 'object' && 'value' in x ? (x).value : x
+}
+/** `online` from @weft-js/core/browser, its result, or a boolean: a factory is called once. */
+function liveOf<T>(get: () => Live<T>) {
+  const src = untrack(get)
+  const once = typeof src === 'function' ? untrack(() => (src as () => Live<T>)()) : undefined
+  return derived(() => (once !== undefined ? read<T>(once) : read<T>(get())))
+}
+
+const RECOVERED_S = 3
+const LATER_MS = 30 * 60 * 1000
+
+/** Props for ConnBanner. */
+export interface ConnBannerProps {
+  /** `online` from `@weft-js/core/browser`, its derived, or a boolean. */
+  online?: Live<boolean>
+  /** The `.live` state (07 §4.4): `live`, `connecting`, `reconnecting`, `offline`. */
+  state?: Live<string | undefined>
+  /** Schema hash mismatch (§5.4). */
+  stale?: Live<boolean | undefined>
+  /** A mutation failed because the contract changed: the Banner turns caution. */
+  contractFailed?: boolean
+  /** Seconds to the next try: weft's backoff. */
+  retryIn?: number
+  /** Adds Retry now, to try before the backoff runs out. */
+  onRetry?: () => void
+  /** Saved changes waiting to sync. */
+  changes?: number
+  /** Save drafts, then reload. */
+  onReload?: () => void
+  /** Later hides the stale banner for 30 minutes. */
+  onLater?: () => void
+  /** "A new version of {name} is ready". */
+  name?: string | undefined
+}
+
+const plural = (n: number) => (n === 1 ? '1 change' : `${n} changes`)
+
+/**
+ * The connection and deploy banner under the shell header (09 §5.3, §5.4): offline with its retry countdown,
+ * reconnecting, "Back online" for 3s, a stale deploy with Reload and Later. Takes its state as props. Offline says so
+ * assertively once and back online politely once; the countdown itself is never announced. Needs a mounted <Toaster />.
+ */
+export function ConnBanner({ online = true, state: conn, stale, contractFailed, retryIn, onRetry, changes = 0, onReload, onLater, name = 'the app' }: ConnBannerProps) {
+  const isOn = liveOf<boolean>(() => online)
+  const st = liveOf<string | undefined>(() => conn)
+  const old = liveOf<boolean | undefined>(() => stale)
+  const later = state(false)
+  const recovered = state(false)
+  const view = derived(() => connView({ online: isOn.value, state: st.value, stale: old.value && !later.value, recovered: recovered.value }))
+  const backIn = useCooldown(() => (recovered.value ? RECOVERED_S : undefined), () => (recovered.value = false))
+  const retry = useCooldown(() => retryIn)
+  let hide: ReturnType<typeof setTimeout> | undefined
+  onCleanup(() => clearTimeout(hide))
+  onMount(() => {
+    watch(() => view.value, (v, was) => {
+      if (v === 'offline') announce(document, "You're offline. Changes are saved on this device.", true)
+      if (v === 'stale') announce(document, `A new version of ${untrack(() => name)} is ready.`)
+      if (was === 'offline' || was === 'reconnecting') {
+        if (v === undefined || v === 'stale') { recovered.value = true; announce(document, 'Back online.') }
+      }
+    })
+  })
+  const postpone = () => {
+    later.value = true
+    hide = setTimeout(() => (later.value = false), LATER_MS)
+    onLater?.()
+  }
+  return (
+    <>
+      {view.value && (
+        <div data-scope="conn" data-state={view.value === 'stale' && contractFailed ? 'limited' : view.value}>
+          {view.value === 'offline' && <>
+            <WifiOffIcon />
+            <span data-part="msg"><b>You're offline.</b> Changes are saved on this device and sync when you reconnect.</span>
+            {retryIn !== undefined && <span>Retrying in {retry.value}s</span>}
+            {onRetry && <Button emphasis="ghost" size="sm" tone="neutral" onClick={onRetry}>Retry now</Button>}
+          </>}
+          {view.value === 'reconnecting' && <>
+            <span data-scope="spinner" aria-hidden="true"></span>
+            <span data-part="msg"><b>Reconnecting…</b> {changes > 0 ? `Sending ${plural(changes)}.` : retryIn !== undefined ? `Trying again in ${retry.value}s.` : ''}</span>
+          </>}
+          {view.value === 'online' && <>
+            <WifiIcon />
+            <span data-part="msg"><b>Back online.</b> {changes > 0 ? `${plural(changes)} synced.` : ''}</span>
+            <span data-part="rail" data-on="" aria-hidden="true"><span data-part="rail-fill" style={`--p:${backIn.value / RECOVERED_S}`}></span></span>
+          </>}
+          {view.value === 'stale' && <>
+            <SparkleIcon />
+            <span data-part="msg"><b>A new version of {name} is ready.</b> {contractFailed ? 'Reload to finish saving.' : 'Reload to update; your draft is kept.'}</span>
+            <Button emphasis="ghost" size="sm" tone="neutral" onClick={postpone}>Later</Button>
+            <Button size="sm" tone="info" onClick={onReload}><RefreshIcon />Reload</Button>
+          </>}
+        </div>
+      )}
+    </>
+  )
+}
+
+/** Props for RateLimited. */
+export interface RateLimitedProps {
+  /** Seconds, from the typed `RATE_LIMITED.retryAfter`: never a guess. */
+  retryAfter: number
+  title?: unknown
+  /** "You can run 5 exports a minute." */
+  description?: unknown
+  /** The action that hit the limit: disabled, labelled "Try again in 20s", and back by itself. */
+  trigger?: ButtonProps
+  /** Called when the wait is over and the action is back. */
+  onDone?: () => void
+}
+
+/** Rate limited (09 §5.5): a caution notice in place with a draining rail. Polite at start and end only; the numbers keep counting under reduced motion. */
+export function RateLimited({ retryAfter, title = 'Limit reached.', description, trigger, onDone }: RateLimitedProps) {
+  const total = derived(() => retryAfter)
+  const left = useCooldown(() => total.value, () => { announce(document, 'You can try again now.'); onDone?.() })
+  const hasTrigger = derived(() => !!trigger)
+  const on = derived(() => left.value > 0)
+  onMount(() => announce(document, `${untrack(() => (typeof title === 'string' ? title : 'Limit reached.'))} Try again in ${untrack(() => total.value)}s.`))
+  return (
+    <div data-scope="stack" style="--_gap:8px">
+      {on.value && (
+        <div data-scope="conn" data-state="limited">
+          <ClockIcon />
+          <span data-part="msg"><b>{title}</b> {description} Try again in {left.value}s.</span>
+          <span data-part="rail" data-on="" aria-hidden="true"><span data-part="rail-fill" style={`--p:${left.value / total.value}`}></span></span>
+        </div>
+      )}
+      {hasTrigger.value && <div><Button {...trigger} disabled={on.value}>{on.value ? `Try again in ${left.value}s` : trigger!.children}</Button></div>}
+    </div>
+  )
+}

package/src/flow/Flow.tsx

@@ -0,0 +1,63 @@
+import { stepFlow } from '@weft-js/warp-core'
+import { derived, state, untrack, watch, type State } from '@weft-js/core'
+import { bindable } from '../Picker'
+import { use } from '@weft-js/warp-core/weft'
+import '../styles'
+import '@weft-js/warp-core/styles/flows/tokens.css'
+import '@weft-js/warp-core/styles/flows/base.css'
+import '@weft-js/warp-core/styles/flows/flow.css'
+
+/** One step of a Flow. */
+export interface FlowStep {
+  id: string
+  /** Announced on arrival ("Step 2 of 4, Shipping"), and the step's accessible name. */
+  label: string
+  /** The step's content: built when the step is first reached, then kept, so what was typed survives Back. */
+  render: () => unknown
+}
+
+/** Props for Flow. */
+export interface FlowProps {
+  steps: FlowStep[]
+  /** The current step's id: a box, a value, or `defaultStep`. */
+  step?: State<string> | string
+  defaultStep?: string
+  onStepChange?: ((id: string) => void) | undefined
+  /** Mirror the step in the URL, one history entry a step: `true` for `?step=`, or the parameter's name. */
+  history?: boolean | string | undefined
+  /** The polite "Step 2 of 4, Shipping" (default true). */
+  announce?: boolean | undefined
+  [attr: string]: unknown
+}
+
+/** Built once, on first arrival: `open` only ever turns true, so nothing is rebuilt as other steps are reached. */
+function Body({ open, render }: { open: boolean; render: () => unknown }) {
+  const on = derived(() => open)
+  return <>{on.value && render()}</>
+}
+
+/**
+ * The step machine (09 §1.1): steps stacked in one grid cell, so height follows the content. On a change the old step
+ * exits, the new one enters from the side it lies on, focus goes to its `[data-autofocus]` or title, the polite region
+ * says where you are, and `history` gives each step a URL. A step is live as soon as it mounts: motion never gates it.
+ */
+export function Flow({ steps, step, defaultStep, onStepChange, history, announce: speak, ...rest }: FlowProps) {
+  const list = untrack(() => steps)
+  const ids = list.map(s => s.id)
+  const at = bindable<string>(() => step, () => defaultStep, ids[0]!, () => onStepChange && (v => onStepChange(v)))
+  const param = derived(() => (history === true ? 'step' : history || undefined))
+  const seen = state<ReadonlySet<string>>(new Set([untrack(() => at.value)]))
+  watch(() => at.value, id => { if (!seen.value.has(id)) seen.value = new Set([...seen.value, id]) })
+  let root: HTMLDivElement | undefined
+  use(stepFlow, () => root, () => ({ step: at.value, steps: ids, label: (id: string) => list.find(s => s.id === id)?.label, history: param.value, announce: speak, onStep: (id: string) => at.set(id) }))
+  return (
+    <div ref={n => (root = n)} data-scope="flow" data-dir="forward" {...rest}>
+      {list.map(s => (
+        <section key={s.id} data-part="step" data-step={s.id} data-state={at.value === s.id ? 'active' : undefined} aria-label={s.label}>
+          <Body open={seen.value.has(s.id)} render={s.render} />
+        </section>
+      ))}
+    </div>
+  )
+}
+

package/src/flow/MfaSetup.tsx

@@ -0,0 +1,103 @@
+import { DownloadIcon } from '@weft-js/warp-icons'
+import { announce, copyText, mapFlowError } from '@weft-js/warp-core'
+import { derived, state, type State } from '@weft-js/core'
+import { Button } from '../Button'
+import { Checkbox } from '../Choice'
+import { Input } from '../Field'
+import { Modal } from '../Modal'
+import { toast } from '../Toast'
+import { Flow } from './Flow'
+import { TextLink } from './kit'
+import '@weft-js/warp-core/styles/layout/row.css'
+
+/** Props for MfaSetup. */
+export interface MfaSetupProps {
+  open: State<boolean>
+  /** The QR code: the app's SVG or image, with its own label. */
+  /** Brings its own light plate, like QRCode: a code must stay dark on light in every theme. */
+  qr?: unknown
+  /** The key for "Can't scan?". */
+  secret: string
+  /** Checks the code: throw, or resolve false, when it's wrong. */
+  onVerify: (code: string) => unknown
+  /** Backup codes, shown once verified. */
+  codes: string[]
+  /** Default: saves `backup-codes.txt`. */
+  onDownload?: (codes: string[]) => void
+  onDone?: () => void
+}
+
+const STEPS = { scan: 'Step 1 of 3 · Scan the code with 1Password, Authy or Google Authenticator.', verify: 'Step 2 of 3 · Enter the code the app shows now.', codes: 'Step 3 of 3 · Save your backup codes.' }
+
+function save(codes: string[]) {
+  const a = document.createElement('a')
+  a.href = URL.createObjectURL(new Blob([codes.join('\n')], { type: 'text/plain' }))
+  a.download = 'backup-codes.txt'
+  a.click()
+  URL.revokeObjectURL(a.href)
+}
+
+/** MFA setup (09 §9, specimen `mfaSetup`): QR and key, confirm a code, backup codes; one dialog over a Flow. Finish waits for "I saved my backup codes". */
+export function MfaSetup({ open, qr, secret, onVerify, codes, onDownload, onDone }: MfaSetupProps) {
+  const step = state<keyof typeof STEPS>('scan')
+  const code = state('')
+  const problem = state<string | undefined>(undefined)
+  const busy = state(false)
+  const saved = state(false)
+  const copy = async (text: string) => { await copyText(document, text); announce(document, 'Copied') }
+  const next = async () => {
+    if (step.value === 'scan') { step.value = 'verify'; return }
+    if (step.value === 'codes') { open.value = false; onDone?.(); return }
+    if (!/^\d{6}$/.test(code.value)) { problem.value = 'Enter the 6 digits from the app.'; return }
+    busy.value = true
+    try {
+      if ((await onVerify(code.value)) === false) problem.value = "That code didn't match. Use the newest one."
+      else { problem.value = undefined; step.value = 'codes' }
+    } catch (e) {
+      const m = mapFlowError(e)
+      if (m.surface === 'toast') toast.show({ title: m.title, description: m.description, tone: 'critical' })
+      else problem.value = m.fields.code ?? m.title
+    } finally { busy.value = false }
+  }
+  const label = derived(() => (step.value === 'codes' ? 'Finish' : 'Continue'))
+  return (
+    <Modal
+      open={open}
+      title="Set up an authenticator app"
+      description={STEPS[step.value]}
+      footer={<>
+        <Button emphasis="frame" data-close="">Cancel</Button>
+        <Button loading={busy.value} disabled={step.value === 'codes' && !saved.value} onClick={next}>{label.value}</Button>
+      </>}
+    >
+      <Flow
+        data-part="mfa"
+        step={step}
+        steps={[
+          { id: 'scan', label: 'scan', render: () => (
+            <div data-scope="stack">
+              {qr}
+              <p>Can't scan? Enter this key: <code>{secret}</code> <TextLink onClick={() => copy(secret)}>Copy key</TextLink></p>
+            </div>
+          ) },
+          { id: 'verify', label: 'confirm', render: () => (
+            <form novalidate onSubmit={(e: SubmitEvent) => { e.preventDefault(); void next() }}>
+              <Input label="6-digit code from the app" name="totp" inputmode="numeric" autocomplete="one-time-code" maxlength="6" hint="" error={problem.value} data-autofocus="" onInput={e => (code.value = e.currentTarget.value)} />
+            </form>
+          ) },
+          { id: 'codes', label: 'backup codes', render: () => (
+            <div data-scope="stack">
+              <p>Each code works once if you lose your phone. Store them somewhere safe; you won't see them again.</p>
+              <ol data-part="codes" aria-label="Backup codes">{codes.map(c => <li key={c}><code>{c}</code></li>)}</ol>
+              <div data-scope="row">
+                <Button emphasis="frame" size="sm" onClick={() => (onDownload ?? save)(codes)}>{() => <><DownloadIcon />Download</>}</Button>
+                <Button emphasis="ghost" tone="neutral" size="sm" onClick={() => copy(codes.join('\n'))}>Copy all</Button>
+              </div>
+              <Checkbox onChange={(e: Event) => (saved.value = (e.currentTarget as HTMLInputElement).checked)}>I saved my backup codes</Checkbox>
+            </div>
+          ) },
+        ]}
+      />
+    </Modal>
+  )
+}

package/src/flow/Otp.tsx

@@ -0,0 +1,114 @@
+import { LeftIcon, ShieldCheckIcon } from '@weft-js/warp-icons'
+import { clockLabel, otpInput, uid } from '@weft-js/warp-core'
+import { derived, state, untrack, watch } from '@weft-js/core'
+import { Button } from '../Button'
+import { use } from '@weft-js/warp-core/weft'
+import { Mark, FormError, StepFrame, Submit, TextLink, Title, useCooldown, useStepForm, type FlowForm } from './kit'
+import '../fields'
+import '@weft-js/warp-core/styles/inputs/field.css'
+import '@weft-js/warp-core/styles/inputs/text.css'
+import '@weft-js/warp-core/styles/flows/otp.css'
+import '@weft-js/warp-core/styles/flows/auth.css'
+
+/** Props for OtpField. */
+export interface OtpFieldProps {
+  label?: unknown
+  name?: string | undefined
+  length?: number
+  hint?: unknown
+  /** Pins every cell critical, clears them and refocuses; the message stays until the next key. */
+  error?: unknown
+  /** `checking` while the code is verified; `success` runs the cascade. */
+  status?: 'idle' | 'checking' | 'success' | undefined
+  /** Submit the form on the last digit (default true); `onComplete` runs either way. */
+  autoSubmit?: boolean
+  onComplete?: (code: string) => void
+  onValueChange?: (code: string) => void
+  /** Show dots (a PIN). */
+  masked?: boolean
+  id?: string
+}
+
+/**
+ * The code input (03 §3, 09 §2.3): one real input painted into cells, so one tab stop, native editing, SMS autofill and
+ * paste of the whole code all just work. The active cell holds its sweep.
+ */
+export function OtpField({ label = '6-digit code', name, length = 6, hint, error, status, autoSubmit = true, onComplete, onValueChange, masked, id: given }: OtpFieldProps) {
+  const id = untrack(() => given) ?? uid('otp')
+  const n = untrack(() => length)
+  const half = Math.ceil(n / 2)
+  const cells = Array.from({ length: n }, (_, i) => [{ k: `c${i}`, i }, ...(i === half - 1 ? [{ k: 'sep', i: -1 }] : [])]).flat()
+  // the error shows until the next key, whatever the prop still says
+  const shown = state(untrack(() => error))
+  watch(() => error, e => { shown.value = e })
+  let root: HTMLDivElement | undefined
+  use(otpInput, () => root, () => ({
+    length: n, invalid: !!shown.value, success: status === 'success',
+    onValue: (v: string) => { if (v) shown.value = undefined; onValueChange?.(v) },
+    onComplete(v: string) {
+      onComplete?.(v)
+      if (autoSubmit) root?.querySelector('input')?.form?.requestSubmit()
+    },
+  }))
+  return (
+    <div data-scope="stack" style="--_gap:8px">
+      <label for={id} data-part="code-label">{label}</label>
+      <div ref={el => (root = el)} data-scope="otp" data-invalid={shown.value ? '' : undefined} data-state={status === 'checking' ? 'pending' : status === 'success' ? 'success' : undefined} data-masked={masked ? '' : undefined}>
+        <input id={id} name={name} inputmode="numeric" autocomplete="one-time-code" maxlength={n} pattern="[0-9]*" enterkeyhint="done" data-autofocus="" aria-describedby={`${id}-m`} aria-invalid={shown.value ? 'true' : undefined} aria-busy={status === 'checking' ? 'true' : undefined} />
+        {cells.map(c => (c.i < 0
+          ? <span key={c.k} data-part="sep" aria-hidden="true"></span>
+          : <span key={c.k} data-part="cell" data-sweep="" aria-hidden="true" style={`--n:${c.i}`}><span data-part="sweep-base" aria-hidden="true"></span><span data-part="sweep" aria-hidden="true"></span><b data-part="char"></b></span>))}
+      </div>
+      <p data-part="message" id={`${id}-m`} role={shown.value ? 'alert' : undefined}>{shown.value ?? hint}</p>
+    </div>
+  )
+}
+
+/** What the code step submits. */
+export interface OtpValues { code: string }
+
+/** Props for OtpStep. */
+export interface OtpStepProps extends FlowForm<OtpValues> {
+  title?: unknown
+  /** "Code sent to •••• 42", or the authenticator line. */
+  lede?: unknown
+  length?: number
+  status?: OtpFieldProps['status'] | undefined
+  hint?: unknown
+  /** Seconds before Resend opens (default 30). */
+  resendIn?: number
+  /** Shows Resend; a press restarts the wait. */
+  onResend?: () => void
+  /** Shows "Use another method". */
+  onOtherMethod?: () => void
+  otherMethodLabel?: unknown
+  onBack?: () => void
+}
+
+/** The MFA step (09 §2.1, §2.3): the code, auto-submitted on the last digit, Verify, resend with its countdown, another method, Back. */
+export function OtpStep(p: OtpStepProps) {
+  const id = uid('otpstep')
+  const ctl = useStepForm<OtpValues>(untrack(() => p))
+  const n = derived(() => p.length ?? 6)
+  const code = state('')
+  const round = state(0)
+  const left = useCooldown(() => (round.value, p.resendIn ?? 30))
+  const resend = () => { p.onResend?.(); round.value++ }
+  const status = derived(() => p.status ?? (ctl.pending.value ? 'checking' : 'idle'))
+  return (
+    <StepFrame ctl={ctl} embedded={!!p.form} labelledby={`${id}-t`}>
+      {p.onBack && <div><Button emphasis="ghost" tone="neutral" size="sm" icon={LeftIcon} onClick={p.onBack}>Back</Button></div>}
+      <Mark><ShieldCheckIcon /></Mark>
+      <div><Title as={p.heading} id={`${id}-t`}>{p.title ?? 'Enter your code'}</Title>{p.lede !== undefined && <p data-part="lede">{p.lede}</p>}</div>
+      <FormError ctl={ctl} />
+      <OtpField name="code" length={n.value} hint={p.hint ?? ''} status={status.value} error={ctl.errors.value.code} onValueChange={v => (code.value = v)} />
+      <Submit ctl={ctl} disabled={code.value.length !== n.value}>Verify</Submit>
+      {(p.onResend || p.onOtherMethod) && (
+        <div data-part="row">
+          {p.onResend && <TextLink disabled={left.value > 0} onClick={resend}>{left.value > 0 ? `Resend in ${clockLabel(left.value)}` : 'Resend code'}</TextLink>}
+          {p.onOtherMethod && <TextLink onClick={p.onOtherMethod}>{p.otherMethodLabel ?? 'Use another method'}</TextLink>}
+        </div>
+      )}
+    </StepFrame>
+  )
+}