@specbook/ui 0.0.0-stage → 0.2.0

package/src/panel/SequencePanel.tsx

@@ -0,0 +1,247 @@
+import type { RunResult, StepResult } from '@specbook/core'
+import { useEffect, useMemo, useState } from 'preact/hooks'
+import { EnvBadge } from '../components/EnvBadge'
+import { defaultFor, type FieldSpec, specFromControl } from '../components/Fields'
+import type { SequenceInfo } from '../engine'
+import { engine } from '../runtime'
+import { env, locale, seed, version } from '../store'
+import { ControlsGrid } from './ControlsGrid'
+import { SecretsBar } from './SecretsBar'
+import { StepExchange } from './StepExchange'
+import { useSequenceNotes } from './stepnotes'
+
+/** `Check items #2` belongs to the step `Check items`. */
+const baseName = (n: string) => n.replace(/ #\d+$/, '')
+
+type Live = Record<string, 'running' | 'pass' | 'fail' | 'error' | 'skipped' | 'paused'>
+
+const ICON = {
+  pass: '✓',
+  fail: '✗',
+  error: '!',
+  skipped: '–',
+  running: '…',
+  paused: '⏸',
+  pending: '',
+}
+const short = (v: unknown) => {
+  const s = typeof v === 'string' ? v : JSON.stringify(v)
+  return s.length > 28 ? `${s.slice(0, 27)}…` : s
+}
+
+/** |timeline|request|: the journey on the left, the selected step's exchange on the right. */
+export function SequencePanel({ info }: { info: SequenceInfo }) {
+  const { seq } = info
+  const specs = useMemo(
+    () =>
+      Object.fromEntries(
+        Object.entries((seq.meta.params ?? {}) as Record<string, unknown>).map(([k, c]) => [
+          k,
+          specFromControl(c),
+        ]),
+      ) as Record<string, FieldSpec>,
+    [seq],
+  )
+  const notes = useSequenceNotes(info)
+  // the services the flow calls; steps built by functions are only known when they run, so any such step asks for all
+  const serviceNames = useMemo(() => {
+    const names = new Set<string>()
+    for (const n of seq.nodes) {
+      if (n.kind === 'step' && typeof n.def !== 'function') names.add(n.def.op.service)
+      else if (n.kind === 'step' || n.kind === 'each') return undefined
+    }
+    return [...names]
+  }, [seq])
+  const [params, setParams] = useState<Record<string, unknown>>({})
+  const [result, setResult] = useState<RunResult>()
+  const [live, setLive] = useState<Live>({})
+  const [running, setRunning] = useState(false)
+  const [pause, setPause] = useState<{
+    name: string
+    controls: Record<string, FieldSpec>
+    resolve: (v: Record<string, unknown>) => void
+  }>()
+  const [choice, setChoice] = useState<Record<string, unknown>>({})
+  const [picked, setPicked] = useState<number>(0)
+  // a phone shows the selected step's request and response as a sheet over the timeline
+  const [sheet, setSheet] = useState(false)
+  const [error, setError] = useState<string>()
+
+  useEffect(() => {
+    setParams(Object.fromEntries(Object.entries(specs).map(([k, v]) => [k, defaultFor(v)])))
+    setResult(undefined)
+    setLive({})
+    setPause(undefined)
+  }, [info.file])
+
+  const planned = seq.nodes.map((n) => n.name)
+  const rows: { name: string; step?: StepResult }[] = result
+    ? result.steps.filter((s) => s.kind !== 'auth').map((s) => ({ name: s.name, step: s }))
+    : planned.map((n) => ({ name: n }))
+  const current = rows[picked]?.step
+
+  const run = async () => {
+    setRunning(true)
+    setResult(undefined)
+    setError(undefined)
+    setLive({})
+    setPicked(0)
+    setSheet(false)
+    try {
+      const r = await engine.run(seq, {
+        env: env.value,
+        version: version.value,
+        params,
+        locale: locale.value,
+        seed: seed.value,
+        onEvent: (e) => {
+          if (e.type === 'step:start') setLive((l) => ({ ...l, [e.name]: 'running' }))
+          if (e.type === 'step:end') setLive((l) => ({ ...l, [e.name]: e.status }))
+        },
+        onInput: ({ name, controls }) =>
+          new Promise((resolve) => {
+            const c = controls as Record<string, FieldSpec>
+            setLive((l) => ({ ...l, [name]: 'paused' }))
+            setChoice(Object.fromEntries(Object.entries(c).map(([k, v]) => [k, defaultFor(v)])))
+            setPause({
+              name,
+              controls: c,
+              resolve: (values) => {
+                setPause(undefined)
+                resolve(values)
+              },
+            })
+          }),
+      })
+      setResult(r)
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e))
+    } finally {
+      setRunning(false)
+      setPause(undefined)
+    }
+  }
+
+  const overall = result?.status
+
+  return (
+    <div class={`sequence-panel ${sheet && current ? 'sheet-open' : ''}`} data-seq={seq.meta.id}>
+      <div class="seq-left">
+        <SecretsBar services={serviceNames} />
+        <ControlsGrid title="Controls" specs={specs} values={params} onChange={setParams} />
+        <div class="seq-run">
+          <button type="button" class="btn primary" disabled={running} onClick={run}>
+            {running ? 'Running…' : '▶ Run'}
+          </button>
+          <EnvBadge />
+          {result && (
+            <span class={`badge ${overall}`}>
+              {ICON[overall as 'pass']}{' '}
+              {overall === 'pass' ? 'Passed' : overall === 'fail' ? 'Failed' : 'Error'} ·{' '}
+              {result.totals.passed}/{result.totals.steps} steps · {result.durationMs}ms
+            </span>
+          )}
+        </div>
+        {error && <p class="error-text">{error}</p>}
+        <ol class="journey" part="timeline" aria-label="Timeline">
+          {rows.map((row, i) => {
+            const step = row.step
+            const status = step?.status ?? live[row.name] ?? 'pending'
+            const failed = step?.assertions.filter((a) => !a.pass) ?? []
+            return (
+              <li class={`jstep ${status} ${picked === i ? 'picked' : ''}`}>
+                <div class="jmark">{ICON[status as keyof typeof ICON] || i + 1}</div>
+                <div class="jbody">
+                  <button
+                    type="button"
+                    class="jhead"
+                    disabled={!step}
+                    onClick={(e) => {
+                      const row = e.currentTarget
+                      setPicked(i)
+                      setSheet(true)
+                      // keep the tapped step visible above the sheet that is about to cover the bottom
+                      requestAnimationFrame(() =>
+                        row.scrollIntoView?.({ block: 'start', behavior: 'smooth' }),
+                      )
+                    }}
+                  >
+                    <span class="jname">{row.name}</span>
+                    {step?.response && (
+                      <span class="muted">
+                        {step.response.status} · {step.durationMs}ms
+                      </span>
+                    )}
+                    {step && step.assertions.length > 0 && (
+                      <span class={failed.length ? 'error-text' : 'muted'}>
+                        {step.assertions.length - failed.length}/{step.assertions.length} checks
+                      </span>
+                    )}
+                  </button>
+                  {step?.uses
+                    ?.filter((u) => u.source === 'capture')
+                    .map((u) => (
+                      <span class="cap use" title={`from step "${u.step}"`}>
+                        ← {u.key} <em>from {u.step}</em>
+                      </span>
+                    ))}
+                  {step &&
+                    Object.entries(step.captured).map(([k, v]) => (
+                      <span class="cap make" title={JSON.stringify(v)}>
+                        → {k} <b>{short(v)}</b>
+                      </span>
+                    ))}
+                  {step?.error && <div class="error-text">{step.error}</div>}
+                  {failed.map((a) => (
+                    <div class="error-text">✗ {a.label}</div>
+                  ))}
+                  {status === 'skipped' && (
+                    <div class="muted">Skipped: an earlier step did not pass.</div>
+                  )}
+                  {pause && live[row.name] === 'paused' && (
+                    <div class="pause">
+                      <strong>Your turn: {pause.name}</strong>
+                      <ControlsGrid
+                        title="Choose"
+                        specs={pause.controls}
+                        values={choice}
+                        onChange={setChoice}
+                      />
+                      <button
+                        type="button"
+                        class="btn primary"
+                        onClick={() => pause.resolve(choice)}
+                      >
+                        Continue ▶
+                      </button>
+                    </div>
+                  )}
+                </div>
+              </li>
+            )
+          })}
+        </ol>
+      </div>
+
+      <div class={`seq-right ${sheet && current ? 'sheet-open' : ''}`}>
+        {current && (
+          <button
+            type="button"
+            class="sheet-close"
+            aria-label="Hide step details"
+            onClick={() => setSheet(false)}
+          >
+            <span aria-hidden="true">⌄</span> {current.name}
+          </button>
+        )}
+        {!current && (
+          <div class="rs-empty">
+            <strong>Nothing run yet</strong>
+            <span class="muted">Press Run, then pick a step to see its request and response.</span>
+          </div>
+        )}
+        {current && <StepExchange step={current} note={notes.notes.get(baseName(current.name))} />}
+      </div>
+    </div>
+  )
+}

package/src/panel/StepExchange.tsx

@@ -0,0 +1,118 @@
+import type { Encoding, StepResult } from '@specbook/core'
+import { useEffect, useState } from 'preact/hooks'
+import { engine, registry } from '../runtime'
+import type { Defs, JsonSchema } from '../schema'
+import { statusClass, statusName } from '../status'
+import { version } from '../store'
+import { StepCodeSample } from './CodeSample'
+import { queryString, RequestView } from './RequestView'
+import { ResponseView } from './ResponseView'
+
+/**
+ * The selected step of a run, laid out like an operation: a bar with method, URL and result, then
+ * Request and Response tabs (the response checked against the operation's schema).
+ */
+export function StepExchange({ step, note }: { step: StepResult; note?: string }) {
+  const [tab, setTab] = useState<'request' | 'response'>('response')
+  const [schemas, setSchemas] = useState<Record<string, JsonSchema>>()
+  const [defs, setDefs] = useState<Defs>()
+  const [reqSchema, setReqSchema] = useState<JsonSchema>()
+  const [encoding, setEncoding] = useState<Encoding>('json')
+  const req = step.request
+  const key = req?.opId ? `${req.service}/${req.opId}` : undefined
+
+  useEffect(() => {
+    setTab('response')
+  }, [step.name])
+
+  useEffect(() => {
+    let live = true
+    setSchemas(undefined)
+    setDefs(undefined)
+    setReqSchema(undefined)
+    if (key && req) {
+      registry.schemas[key]?.().then(
+        (m: { default: JsonSchema }) => live && setReqSchema(m.default),
+      )
+      engine
+        .operationMeta(key, version.value)
+        .then((m) => live && setEncoding(m?.encoding ?? 'json'))
+      registry.responseSchemas[key]?.().then(
+        (m: { default: Record<string, JsonSchema> }) => live && setSchemas(m.default),
+      )
+      registry.definitions[req.service]?.().then(
+        (m: { default: Defs }) => live && setDefs(m.default),
+      )
+    }
+    return () => {
+      live = false
+    }
+  }, [key])
+
+  const response = step.response
+  const url = req ? `${req.url}${queryString(req.query)}` : ''
+
+  return (
+    <div class="step-exchange">
+      {req && (
+        <div class="rq-bar">
+          <span class={`method ${req.method}`}>{req.method}</span>
+          <div class="rq-url" title={url}>
+            <code>{url}</code>
+          </div>
+          {response && (
+            <span class={`result-chip ${statusClass(response.status)}`}>
+              {response.status} {statusName(response.status)} · {response.durationMs} ms
+            </span>
+          )}
+        </div>
+      )}
+
+      {note && (
+        <details class="step-about" key={step.name}>
+          <summary>About this step</summary>
+          <div class="doc-custom" dangerouslySetInnerHTML={{ __html: note }} />
+        </details>
+      )}
+
+      <div class="rq-tabs" role="tablist">
+        {(
+          [
+            ['request', 'Request'],
+            ['response', 'Response'],
+          ] as const
+        ).map(([id, label]) => (
+          <button
+            type="button"
+            role="tab"
+            aria-selected={tab === id}
+            class={`rq-tab ${tab === id ? 'on' : ''}`}
+            onClick={() => setTab(id)}
+          >
+            {label}
+            {id === 'response' && response && (
+              <span class={`state-dot ${statusClass(response.status)}`}>{response.status}</span>
+            )}
+          </button>
+        ))}
+      </div>
+
+      <div class="rq-pane">
+        <div class="tab-pane" hidden={tab !== 'request'}>
+          {req ? (
+            <StepCodeSample
+              request={req}
+              encoding={encoding}
+              sent={<RequestView request={req} hideBar docs={{ schema: reqSchema, defs }} />}
+            />
+          ) : (
+            <RequestView request={req} hideBar docs={{ schema: reqSchema, defs }} />
+          )}
+        </div>
+        <div class="tab-pane" hidden={tab !== 'response'}>
+          <ResponseView step={step} schemas={schemas} defs={defs} hideRequest />
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/panel/completions.ts

@@ -0,0 +1,114 @@
+import {
+  type Defs,
+  describe,
+  type JsonSchema,
+  kindOf,
+  propsOf,
+  schemaAt,
+  summary,
+  unwrap,
+} from '../schema'
+import { jsonCursor } from './jsonCursor'
+
+/** The shape the editor's autocomplete extension consumes (see prism-code-editor's `CompletionResult`). */
+export interface Option {
+  label: string
+  detail?: string
+  icon?: string
+  insert?: string
+  tabStops?: number[]
+  boost?: number
+  from?: number
+  /** a longer description for the documentation popup */
+  doc?: string
+}
+export interface Completions {
+  from: number
+  to: number
+  options: Option[]
+}
+
+/** Descriptions are markdown; the popup shows plain text, so links keep just their label. */
+const plain = (s: string | undefined) =>
+  s?.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/[`*_]{1,2}/g, '')
+
+const typeLabel = (u: JsonSchema, defs: Defs) => {
+  const kind = kindOf(u)
+  if (kind === 'array') return `${kindOf(unwrap(u.items, defs))}[]`
+  return u.format ? `${kind} · ${u.format}` : kind
+}
+
+/** The empty value of the right kind that goes after `"key": `, with the cursor placed inside it. */
+function skeleton(u: JsonSchema): { text: string; stop: number } {
+  const kind = kindOf(u)
+  if (kind === 'object') return { text: '{}', stop: 1 }
+  if (kind === 'array') return { text: '[]', stop: 1 }
+  if (kind === 'boolean') return { text: 'false', stop: 5 }
+  if (kind === 'number' || kind === 'integer') return { text: '0', stop: 1 }
+  return { text: '""', stop: 1 }
+}
+
+/**
+ * Completions for the JSON body editor: the properties the schema allows at the cursor (minus the ones
+ * already there), or the allowed values for the property being written. `root` is the request schema and
+ * `prefix` the path of the body inside it (`['data']`).
+ */
+export function jsonCompletions(
+  root: JsonSchema | undefined,
+  defs: Defs,
+  prefix: (string | number)[],
+  text: string,
+  pos: number,
+): Completions | undefined {
+  if (!root) return undefined
+  const cur = jsonCursor(text, pos)
+  if (!cur) return undefined
+  const at = schemaAt(root, [...prefix, ...cur.path], defs)
+  if (!at) return undefined
+  const u = unwrap(at, defs)
+
+  if (cur.mode === 'key') {
+    if (kindOf(u) !== 'object' && !u.properties) return undefined
+    const props = propsOf(u, defs).filter((p) => !cur.existing.has(p.name))
+    if (props.length === 0) return undefined
+    const options: Option[] = props.map((p) => {
+      const pu = unwrap(p.schema, defs)
+      const sk = skeleton(pu)
+      const key = JSON.stringify(p.name)
+      const head = cur.hasColon ? key : `${key}: `
+      const insert = cur.hasColon ? key : `${head}${sk.text}`
+      return {
+        label: p.name,
+        detail: `${typeLabel(pu, defs)}${p.required ? ' · required' : ''}`,
+        icon: pu.deprecated ? 'text' : 'property',
+        insert,
+        tabStops: cur.hasColon ? undefined : [head.length + sk.stop],
+        boost: p.required ? 10 : 0,
+        // inside a string the filter should match the letters typed after the opening quote
+        from: cur.inString ? cur.from + 1 : undefined,
+        doc: plain(summary(describe(pu), 400)),
+      }
+    })
+    return { from: cur.from, to: cur.to, options }
+  }
+
+  // value mode
+  const values: Option[] = []
+  const add = (v: unknown, detail?: string) => {
+    const json = JSON.stringify(v)
+    values.push({
+      label: typeof v === 'string' ? v : json,
+      insert: json,
+      icon: 'enum',
+      detail,
+      from: cur.inString ? cur.from + 1 : undefined,
+    })
+  }
+  if (Array.isArray(u.enum)) for (const v of u.enum) add(v)
+  else if (kindOf(u) === 'boolean') {
+    add(true)
+    add(false)
+  } else return undefined
+  if (u.nullable === true) add(null, 'null')
+  return { from: cur.from, to: cur.to, options: values }
+}

package/src/panel/draft.ts

@@ -0,0 +1,106 @@
+import {
+  type Encoding,
+  type Example,
+  fromFormRows,
+  fromRows,
+  type Row,
+  toFormRows,
+  toRows,
+} from '@specbook/core'
+
+export type FieldRow = Row & { file?: File }
+
+/** The request as the user sees and edits it. Path/query/headers are grid rows; the body depends on encoding. */
+export interface Draft {
+  path: Row[]
+  query: Row[]
+  headers: Row[]
+  /** json, graphql and text bodies */
+  body: string
+  /** form, multipart and binary bodies */
+  fields: FieldRow[]
+  /**
+   * How a form body is edited: nested JSON (the default; flattened to brackets when sent) or the
+   * key/value grid. Drafts stored before this existed have only a grid, so they keep it.
+   */
+  formView?: 'json' | 'grid'
+}
+
+/** Whether the body is edited as rows: multipart always, form when its grid view is chosen. */
+export const gridMode = (d: Draft, e: Encoding) =>
+  e === 'multipart' || (e === 'form' && (d.formView ?? 'grid') === 'grid')
+
+export function draftFrom(ex: Example, encoding: Encoding): Draft {
+  const body = ex.body
+  const rows = encoding === 'multipart' || encoding === 'form'
+  return {
+    path: toRows(ex.path),
+    query: toRows(ex.query),
+    headers: toRows(ex.headers),
+    body:
+      body === undefined || encoding === 'multipart' || encoding === 'binary'
+        ? ''
+        : typeof body === 'string' && encoding === 'text'
+          ? body
+          : JSON.stringify(body, null, 2),
+    fields: rows
+      ? toFormRows(body)
+      : encoding === 'binary' && typeof body === 'string'
+        ? [{ key: 'file', value: body, enabled: true }]
+        : [],
+    formView: encoding === 'form' ? 'json' : undefined,
+  }
+}
+
+export interface RequestParts {
+  path?: Record<string, unknown>
+  query?: Record<string, unknown>
+  headers?: Record<string, string>
+  data?: unknown
+}
+
+const nonEmpty = <T extends object>(o: T) => (Object.keys(o).length ? o : undefined)
+
+/** Throws a readable message when the JSON body does not parse. */
+export function requestParts(d: Draft, encoding: Encoding): RequestParts {
+  let data: unknown
+  if (gridMode(d, encoding)) data = fromFormRows(d.fields)
+  else if (encoding === 'binary') {
+    const f = d.fields.find((r) => r.enabled)
+    data = f?.file ?? f?.value
+  } else if (d.body.trim() !== '') {
+    if (encoding === 'text') data = d.body
+    else
+      try {
+        data = JSON.parse(d.body)
+      } catch (e) {
+        throw new Error(`Invalid JSON: ${(e as Error).message}`)
+      }
+  }
+  return {
+    path: nonEmpty(fromRows(d.path)),
+    query: nonEmpty(fromRows(d.query)),
+    headers: nonEmpty(fromRows(d.headers)) as Record<string, string> | undefined,
+    data,
+  }
+}
+
+/** The editable state for storage; picked files are never persisted. */
+export const forStorage = (d: Draft) => ({
+  ...d,
+  fields: d.fields.map(({ file: _file, ...r }) => r),
+})
+
+/** What the request will be called with, for the URL bar: path params filled in, enabled query rows appended. */
+export function previewUrl(template: string, path: Row[], query: Row[], base = ''): string {
+  const enc = (v: string) => (v.includes('{{') ? v : encodeURIComponent(v))
+  const p = template.replace(/\{([^}]+)\}/g, (m, name: string) => {
+    const r = path.find((x) => x.key === name && x.enabled && x.value !== '')
+    return r ? enc(r.value) : m
+  })
+  const qs = query
+    .filter((r) => r.enabled && r.key !== '')
+    .map((r) => `${enc(r.key)}=${enc(r.value)}`)
+    .join('&')
+  return `${base.replace(/\/+$/, '')}${p}${qs ? `?${qs}` : ''}`
+}

package/src/panel/fieldnotes-split.ts

@@ -0,0 +1,55 @@
+/** Section a field belongs to in a request schema (`{ path, query, headers, data }`). */
+export type FieldSection = 'path' | 'query' | 'headers' | 'data'
+
+const SECTIONS = new Set<string>(['path', 'query', 'headers', 'data'])
+
+export interface FieldNotes {
+  /** the page without the field sections */
+  intro: string
+  /** `section.path` -> HTML, e.g. `data.address.city` */
+  notes: Map<string, string>
+}
+
+/** `items[0].price` and `items.price` are the same field. */
+const segments = (s: string) => (s.match(/[^.[\]]+/g) ?? []).filter((p) => !/^\d+$/.test(p))
+
+/** The key notes are stored and looked up by. */
+export function noteKey(section: FieldSection, path: string): string {
+  return [section, ...segments(path)].join('.')
+}
+
+/** A heading's text becomes a key when it names a field: `name`, `data.name`, `query.status`. */
+function headingKey(text: string): string | undefined {
+  const parts = segments(text.trim())
+  if (parts.length === 0) return undefined
+  const first = parts[0] as string
+  if (parts.length >= 2 && SECTIONS.has(first)) return parts.join('.')
+  return ['data', ...parts].join('.')
+}
+
+const plain = (h: string) =>
+  h
+    .replace(/<[^>]+>/g, '')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+
+/**
+ * A heading made of one inline code span (`## \`data.name\``) attaches the text under it, up to the next
+ * heading of that kind, to that field. Everything else stays in the intro.
+ */
+export function splitFieldNotes(html: string): FieldNotes {
+  const notes = new Map<string, string>()
+  if (!html) return { intro: html, notes }
+  const intro: string[] = []
+  for (const chunk of html.split(/(?=<h[1-6][ >])/)) {
+    const m = /^<h([1-6])[^>]*>\s*<code>([^<]+)<\/code>\s*<\/h\1>/.exec(chunk)
+    const key = m ? headingKey(plain(m[2] as string)) : undefined
+    if (m && key) {
+      const prev = notes.get(key)
+      const body = chunk.slice(m[0].length)
+      notes.set(key, prev ? prev + body : body)
+    } else intro.push(chunk)
+  }
+  return { intro: intro.join(''), notes }
+}

package/src/panel/fieldnotes.ts

@@ -0,0 +1,40 @@
+import { useEffect, useMemo, useState } from 'preact/hooks'
+import { registry } from '../runtime'
+import { type FieldNotes, splitFieldNotes } from './fieldnotes-split'
+
+export { type FieldNotes, type FieldSection, noteKey, splitFieldNotes } from './fieldnotes-split'
+
+export interface OperationNotes extends FieldNotes {
+  /** the page replaces the spec's description instead of following it */
+  replace: boolean
+  /** an operation page exists */
+  found: boolean
+  /** the page has finished loading (or there is none), so what follows it will not move */
+  loaded: boolean
+}
+
+const NONE = { intro: '', notes: new Map(), replace: false, found: false }
+
+/** The markdown that sits with an operation (`.../<Operation>/README.md` or `requests/<service>/docs/<Operation>.md`), split into intro and field notes. */
+export function useOperationNotes(key: string): OperationNotes {
+  const [html, setHtml] = useState<string>()
+  const [loaded, setLoaded] = useState(false)
+  const page = registry.docs.find((d) => d.operation === key)
+  useEffect(() => {
+    let live = true
+    setHtml(undefined)
+    setLoaded(!page)
+    page
+      ?.load()
+      .then((h: string) => live && setHtml(h))
+      .catch(() => {})
+      .finally(() => live && setLoaded(true))
+    return () => {
+      live = false
+    }
+  }, [key, page])
+  return useMemo(() => {
+    if (!page || html === undefined) return { ...NONE, loaded }
+    return { ...splitFieldNotes(html), replace: !!page.replace, found: true, loaded }
+  }, [html, page, loaded])
+}