@crombolo/core 0.11.0 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/core",
-  "version": "0.11.0",
+  "version": "0.13.1",
   "description": "Domain model, entity keys and shared contracts for crombolo. No I/O.",
   "license": "MIT",
   "author": "Crombolo",

package/src/api-paths.ts

@@ -12,6 +12,12 @@ export const MANAGEMENT_API_PREFIX = '/umbraco/management/api/'
 
 export const MANAGEMENT_API_PATH = `${MANAGEMENT_API_PREFIX}v1`
 
+/**
+ * Umbraco's Delivery API, at the path its contract and every headless client
+ * use, wherever the backoffice is mounted.
+ */
+export const DELIVERY_API_PREFIX = '/umbraco/delivery/api'
+
 /** `server-event.context.js`: `${serverURL}/umbraco/serverEventHub`. */
 export const SERVER_EVENT_HUB_PATH = '/umbraco/serverEventHub'
 

package/src/form-submissions.ts

@@ -11,8 +11,10 @@
  * is a client-side concern tied to CSS classes.
  */
 import {
+  choiceOptions,
   type FormCondition,
   type FormConditionRule,
+  type FormTypes,
   formFieldType,
   type SchemaForm,
   type SchemaFormField,
@@ -30,6 +32,11 @@ export interface FormFieldError {
 export interface FormValueToStore {
   fieldAlias: string
   values: string[]
+  /**
+   * What the visitor saw for each value, for a choice drawn from a source: the
+   * value is a key, and the label keeps the entry readable once that key is gone.
+   */
+  labels?: string[]
 }
 
 export interface SubmissionResult {
@@ -168,6 +175,8 @@ export interface ValidateSubmissionOptions {
    * forward. Values for other pages are still carried through.
    */
   page?: number
+  /** The field types in play: the built-ins, and the wired bundles'. */
+  types?: FormTypes
 }
 
 const DATE = /^\d{4}-\d{2}-\d{2}(?:T[\d:.]+Z?)?$/
@@ -189,7 +198,7 @@ export function validateSubmission(
     errors.push({ field: field.alias, message })
 
   for (const { field, page } of visibleFields(form, submitted)) {
-    const info = formFieldType(field.type)
+    const info = formFieldType(field.type, options.types)
     // A presentational field collects nothing, so there is nothing to check and
     // nothing to store — and a value posted for one is ignored, not kept.
     if (!info || info.presentational) continue
@@ -222,6 +231,7 @@ export function validateSubmission(
     }
 
     let accepted = present
+    const allowed = new Map(choiceOptions(field).map((option) => [option.value, option.label]))
     switch (info.stores) {
       case 'string': {
         const value = first(present)
@@ -239,7 +249,7 @@ export function validateSubmission(
               fail(field, `${label(field)} cannot be after ${field.max}`)
           }
         }
-        if (info.choices && !field.values.includes(value))
+        if (info.choices && !allowed.has(value))
           fail(field, `${label(field)} is not one of the choices`)
         if (field.pattern) {
           let matches = true
@@ -256,9 +266,9 @@ export function validateSubmission(
         break
       }
       case 'strings': {
-        const unknown = present.filter((value) => !field.values.includes(value))
+        const unknown = present.filter((value) => !allowed.has(value))
         if (unknown.length > 0) fail(field, `${label(field)} is not one of the choices`)
-        accepted = present.filter((value) => field.values.includes(value))
+        accepted = present.filter((value) => allowed.has(value))
         break
       }
       case 'number': {
@@ -285,7 +295,26 @@ export function validateSubmission(
         break
       }
     }
-    values.push({ fieldAlias: field.alias, values: accepted })
+    // A bundle's own check, once the kind's have passed: a broken one refuses
+    // the value rather than the whole submission.
+    if (info.validate && !errors.some((error) => error.field === field.alias)) {
+      let message: string | undefined
+      try {
+        message = info.validate(accepted, field.settings ?? {})
+      } catch {
+        message = `${label(field)} could not be checked`
+      }
+      if (message) fail(field, message)
+    }
+    values.push(
+      field.source
+        ? {
+            fieldAlias: field.alias,
+            values: accepted,
+            labels: accepted.map((value) => allowed.get(value) ?? value),
+          }
+        : { fieldAlias: field.alias, values: accepted },
+    )
   }
 
   return { ok: errors.length === 0, errors, values }

package/src/forms.ts

@@ -5,13 +5,16 @@
  * renderer need it, and `render` depends on `core` alone. What a form *is* is
  * domain knowledge; how it is written to a file is not.
  *
- * Field types are an internal registry rather than an extension point: the TOML
- * vocabulary, the validator, the renderer and the entry value shape all have to
- * agree, and freezing that contract before anything has stressed it would be a
- * promise made too early (`docs/forms.md`).
+ * The built-in field and workflow types are fixed here. A server bundle adds
+ * its own through `FormTypes`, which is passed to whatever parses, validates or
+ * renders a form rather than held globally (`docs/forms.md`, "Types from a
+ * bundle").
  */
 
-export type FormFieldType =
+/** A field type's name: a built-in one, or one a wired bundle provides. */
+export type FormFieldType = string
+
+export type BuiltInFormFieldType =
   | 'shortAnswer'
   | 'longAnswer'
   | 'email'
@@ -30,6 +33,23 @@ export type FormFieldType =
 /** How a submitted value is stored, which decides how an entry reads it back. */
 export type FormValueKind = 'string' | 'strings' | 'number' | 'boolean' | 'files' | 'none'
 
+/** What a declared setting holds, which is also the editor the designer draws for it. */
+export type FormSettingKind = 'text' | 'number' | 'boolean' | 'list'
+
+export type FormSettingValue = string | number | boolean | string[]
+
+/**
+ * One setting a type accepts. For a built-in type `key` is the field's own
+ * property; for a bundle's type the value lives in the field's `settings`.
+ */
+export interface FormSettingDeclaration {
+  key: string
+  label: string
+  kind: FormSettingKind
+  required?: boolean
+  description?: string
+}
+
 export interface FormFieldTypeInfo {
   type: FormFieldType
   label: string
@@ -43,6 +63,15 @@ export interface FormFieldTypeInfo {
   presentational: boolean
   /** The settings this type accepts beyond the ones every field has. */
   settings: readonly FormFieldSetting[]
+  /** The same, as the designer edits them; a bundle's type declares only these. */
+  declared: readonly FormSettingDeclaration[]
+  /** The wired bundle that provides it; absent for a built-in type. */
+  bundle?: string
+  /** A check of a submitted value beyond its kind's: a message when it is wrong. */
+  validate?(
+    values: readonly string[],
+    settings: Readonly<Record<string, FormSettingValue>>,
+  ): string | undefined
 }
 
 export type FormFieldSetting =
@@ -60,7 +89,24 @@ export type FormFieldSetting =
 
 const TEXTUAL = ['placeholder', 'maxlength', 'default-value'] as const
 
-export const FORM_FIELD_TYPES: readonly FormFieldTypeInfo[] = [
+/** How the designer edits each built-in setting, by its file key. */
+const SETTING_DECLARATIONS: Record<FormFieldSetting, FormSettingDeclaration> = {
+  placeholder: { key: 'placeholder', label: 'Placeholder', kind: 'text' },
+  maxlength: { key: 'maxlength', label: 'Maximum length', kind: 'number' },
+  rows: { key: 'rows', label: 'Rows', kind: 'number' },
+  min: { key: 'min', label: 'Minimum', kind: 'number' },
+  max: { key: 'max', label: 'Maximum', kind: 'number' },
+  step: { key: 'step', label: 'Step', kind: 'number' },
+  accept: { key: 'accept', label: 'Accepted file types', kind: 'list' },
+  'max-size-kb': { key: 'maxSizeKb', label: 'Largest file (KB)', kind: 'number' },
+  content: { key: 'content', label: 'Content', kind: 'text' },
+  'default-value': { key: 'defaultValue', label: 'Default value', kind: 'text' },
+  multiple: { key: 'multiple', label: 'Allow several files', kind: 'boolean' },
+}
+
+type BuiltInInfo = Omit<FormFieldTypeInfo, 'declared' | 'type'> & { type: BuiltInFormFieldType }
+
+const BUILT_IN_INFO: readonly BuiltInInfo[] = [
   {
     type: 'shortAnswer',
     label: 'Short answer',
@@ -176,11 +222,10 @@ export const FORM_FIELD_TYPES: readonly FormFieldTypeInfo[] = [
   },
 ]
 
-const BY_TYPE = new Map(FORM_FIELD_TYPES.map((info) => [info.type, info]))
-
-export function formFieldType(type: string): FormFieldTypeInfo | undefined {
-  return BY_TYPE.get(type as FormFieldType)
-}
+export const FORM_FIELD_TYPES: readonly FormFieldTypeInfo[] = BUILT_IN_INFO.map((info) => ({
+  ...info,
+  declared: info.settings.map((setting) => SETTING_DECLARATIONS[setting]),
+}))
 
 export const FORM_FIELD_TYPE_NAMES: readonly string[] = FORM_FIELD_TYPES.map((info) => info.type)
 
@@ -230,6 +275,8 @@ export interface SchemaFormField {
   key?: string
   alias: string
   type: FormFieldType
+  /** A bundle type's own settings, as it declares them; never set on a built-in type. */
+  settings?: Record<string, FormSettingValue>
   caption: string
   helpText?: string
   mandatory: boolean
@@ -243,6 +290,13 @@ export interface SchemaFormField {
   autocomplete?: string
   /** A choice list, for the types that take one. */
   values: string[]
+  /** Where the choice list comes from instead, kept once rather than in every form. */
+  source?: ChoiceSource
+  /**
+   * The options a source resolved to, filled in at render and at submit; never
+   * read from or written to the file.
+   */
+  options?: ChoiceOption[]
   placeholder?: string
   defaultValue?: string
   content?: string
@@ -257,6 +311,53 @@ export interface SchemaFormField {
   condition?: FormCondition
 }
 
+/** The kinds of list a choice field can draw its options from. */
+export const CHOICE_SOURCE_KINDS = ['content', 'dictionary'] as const
+
+export type ChoiceSourceKind = (typeof CHOICE_SOURCE_KINDS)[number]
+
+/**
+ * A choice list kept somewhere else: the children of a content node (by key), or
+ * the children of a dictionary item (by name). docs/forms.md, "Choices from a source".
+ */
+export interface ChoiceSource {
+  kind: ChoiceSourceKind
+  parent: string
+}
+
+/** One option: what is stored when it is chosen, and what a visitor sees. */
+export interface ChoiceOption {
+  value: string
+  label: string
+}
+
+/** The options a choice field offers: its source's, once resolved, or its own values. */
+export function choiceOptions(field: SchemaFormField): ChoiceOption[] {
+  if (field.options) return field.options
+  if (field.source) return []
+  return field.values.map((value) => ({ value, label: value }))
+}
+
+/** The form with every source-backed field's options filled in by `resolve`. */
+export function withResolvedChoices(
+  form: SchemaForm,
+  resolve: (source: ChoiceSource) => ChoiceOption[],
+): SchemaForm {
+  if (!allFormFields(form).some((field) => field.source)) return form
+  return {
+    ...form,
+    pages: form.pages.map((page) => ({
+      ...page,
+      groups: page.groups.map((group) => ({
+        ...group,
+        fields: group.fields.map((field) =>
+          field.source ? { ...field, options: resolve(field.source) } : field,
+        ),
+      })),
+    })),
+  }
+}
+
 export interface SchemaFormGroup {
   caption?: string
   /** A simple column count; the renderer lays the fields out across it. */
@@ -271,14 +372,165 @@ export interface SchemaFormPage {
   condition?: FormCondition
 }
 
-export type FormWorkflowType = 'sendEmail' | 'saveAsContent' | 'sendToUrl'
+/** A workflow type's name: a built-in one, or one a wired bundle provides. */
+export type FormWorkflowType = string
+
+export type BuiltInFormWorkflowType = 'sendEmail' | 'saveAsContent' | 'sendToUrl'
 
-export const FORM_WORKFLOW_TYPES: readonly FormWorkflowType[] = [
+export const FORM_WORKFLOW_TYPES: readonly BuiltInFormWorkflowType[] = [
   'sendEmail',
   'saveAsContent',
   'sendToUrl',
 ]
 
+export interface FormWorkflowTypeInfo {
+  type: FormWorkflowType
+  label: string
+  /** A bundle type's settings; the built-in three are checked by the validator's own table. */
+  declared: readonly FormSettingDeclaration[]
+  bundle?: string
+  /** A check across its settings beyond their declarations: a message when they are wrong. */
+  validate?(settings: Readonly<Record<string, unknown>>): string | undefined
+}
+
+/** The field and workflow types a site can use: the built-ins and its wired bundles'. */
+export interface FormTypes {
+  fields: ReadonlyMap<string, FormFieldTypeInfo>
+  workflows: ReadonlyMap<string, FormWorkflowTypeInfo>
+}
+
+const BUILT_IN_WORKFLOW_LABELS: Record<BuiltInFormWorkflowType, string> = {
+  sendEmail: 'Send an e-mail',
+  saveAsContent: 'Save as content',
+  sendToUrl: 'Send to a URL',
+}
+
+export const BUILT_IN_FORM_TYPES: FormTypes = {
+  fields: new Map(FORM_FIELD_TYPES.map((info) => [info.type, info])),
+  workflows: new Map(
+    FORM_WORKFLOW_TYPES.map((type) => [
+      type,
+      { type, label: BUILT_IN_WORKFLOW_LABELS[type], declared: [] },
+    ]),
+  ),
+}
+
+export function isBuiltInFieldType(type: string): type is BuiltInFormFieldType {
+  return FORM_FIELD_TYPE_NAMES.includes(type)
+}
+
+export function isBuiltInWorkflowType(type: string): type is BuiltInFormWorkflowType {
+  return (FORM_WORKFLOW_TYPES as readonly string[]).includes(type)
+}
+
+export function formFieldType(
+  type: string,
+  types: FormTypes = BUILT_IN_FORM_TYPES,
+): FormFieldTypeInfo | undefined {
+  return types.fields.get(type)
+}
+
+const TYPE_NAME = /^[a-z][A-Za-z0-9]{1,31}$/
+
+/**
+ * The built-ins plus a bundle's types, or why they cannot be added: a name that
+ * is not camelCase, one already taken, or a setting declared twice. Pure.
+ */
+export function formTypesWith(
+  base: FormTypes,
+  bundle: string,
+  added: {
+    fields?: readonly Omit<FormFieldTypeInfo, 'bundle' | 'settings'>[]
+    workflows?: readonly Omit<FormWorkflowTypeInfo, 'bundle'>[]
+  },
+): { types: FormTypes; problems: string[] } {
+  const problems: string[] = []
+  const fields = new Map(base.fields)
+  const workflows = new Map(base.workflows)
+  const check = (
+    kind: 'field' | 'workflow',
+    type: string,
+    taken: ReadonlyMap<string, { bundle?: string }>,
+    declared: readonly FormSettingDeclaration[],
+  ): boolean => {
+    const owner = taken.get(type)
+    if (!TYPE_NAME.test(type)) {
+      problems.push(
+        `The bundle "${bundle}" names a ${kind} type "${type}", which is not a camelCase name of 2–32 letters and digits.`,
+      )
+      return false
+    }
+    if (owner) {
+      problems.push(
+        `The bundle "${bundle}" adds the ${kind} type "${type}", which ${owner.bundle ? `the bundle "${owner.bundle}" already provides` : 'is built in'}.`,
+      )
+      return false
+    }
+    const keys = new Set<string>()
+    for (const setting of declared) {
+      if (keys.has(setting.key))
+        problems.push(
+          `The bundle "${bundle}"'s ${kind} type "${type}" declares the setting "${setting.key}" twice.`,
+        )
+      keys.add(setting.key)
+    }
+    return true
+  }
+  for (const field of added.fields ?? [])
+    if (check('field', field.type, fields, field.declared))
+      fields.set(field.type, { ...field, settings: [], bundle })
+  for (const workflow of added.workflows ?? [])
+    if (check('workflow', workflow.type, workflows, workflow.declared))
+      workflows.set(workflow.type, { ...workflow, bundle })
+  return { types: { fields, workflows }, problems }
+}
+
+/**
+ * Why `settings` does not satisfy `declared`: a setting it does not declare, a
+ * required one missing, or a value of the wrong kind. Pure; `where` prefixes
+ * each message.
+ */
+export function settingsProblems(
+  declared: readonly FormSettingDeclaration[],
+  settings: Readonly<Record<string, unknown>>,
+  where: string,
+): string[] {
+  const problems: string[] = []
+  const known = new Map(declared.map((setting) => [setting.key, setting]))
+  for (const key of Object.keys(settings))
+    if (!known.has(key))
+      problems.push(
+        `${where} has the setting "${key}", which it does not take${known.size > 0 ? `; it takes ${[...known.keys()].join(', ')}` : ''}.`,
+      )
+  for (const setting of declared) {
+    const value = settings[setting.key]
+    if (value === undefined || value === '') {
+      if (setting.required) problems.push(`${where} needs the setting "${setting.key}".`)
+      continue
+    }
+    const fits =
+      setting.kind === 'text'
+        ? typeof value === 'string'
+        : setting.kind === 'number'
+          ? typeof value === 'number' && Number.isFinite(value)
+          : setting.kind === 'boolean'
+            ? typeof value === 'boolean'
+            : Array.isArray(value) && value.every((item) => typeof item === 'string')
+    if (!fits)
+      problems.push(
+        `${where} has the setting "${setting.key}" as ${JSON.stringify(value)}, which is not ${KIND_WORDS[setting.kind]}.`,
+      )
+  }
+  return problems
+}
+
+const KIND_WORDS: Record<FormSettingKind, string> = {
+  text: 'text',
+  number: 'a number',
+  boolean: 'true or false',
+  list: 'a list of text',
+}
+
 /** The state transition a workflow runs on. */
 export type FormWorkflowTrigger = 'submit' | 'approve'
 
@@ -300,6 +552,11 @@ export interface SchemaForm {
   storeEntries: boolean
   /** Entries wait as `submitted` until someone approves them. */
   requiresApproval: boolean
+  /**
+   * Shows one page at a time in the browser, checking each on the server before
+   * the next. Without JavaScript every page shows at once, as when it is off.
+   */
+  stepPages?: boolean
   submitLabel?: string
   nextLabel?: string
   previousLabel?: string
@@ -326,6 +583,9 @@ export function allFormFields(form: SchemaForm): SchemaFormField[] {
 }
 
 /** Every field that stores something, which is what an entry and an export carry. */
-export function storingFormFields(form: SchemaForm): SchemaFormField[] {
-  return allFormFields(form).filter((field) => formFieldType(field.type)?.stores !== 'none')
+export function storingFormFields(
+  form: SchemaForm,
+  types: FormTypes = BUILT_IN_FORM_TYPES,
+): SchemaFormField[] {
+  return allFormFields(form).filter((field) => formFieldType(field.type, types)?.stores !== 'none')
 }

package/src/index.ts

@@ -3,6 +3,7 @@ export * from './content-types.ts'
 export * from './documents.ts'
 export * from './form-submissions.ts'
 export * from './forms.ts'
+export * from './json-patch.ts'
 export * from './notifications.ts'
 export * from './object-types.ts'
 export * from './paging.ts'
@@ -13,3 +14,4 @@ export * from './return-urls.ts'
 export * from './sections.ts'
 export * from './uploads.ts'
 export * from './users.ts'
+export * from './workflows.ts'

package/src/json-patch.ts

@@ -0,0 +1,144 @@
+/**
+ * JSON Patch with Umbraco's filter segments: `replace`, `add` and `remove` over
+ * paths like `/values[alias=title,culture=null,segment=null]/value`. Operations
+ * apply in order to a copy; any failure fails the lot. docs/api-contract.md.
+ */
+
+export interface PatchOperation {
+  op: string
+  path: string
+  value?: unknown
+}
+
+export type PatchResult = { ok: true; value: unknown } | { ok: false; reason: string }
+
+type Step =
+  | { kind: 'key'; key: string }
+  | { kind: 'append' }
+  | { kind: 'filter'; conditions: Array<[string, string | null]> }
+
+class PatchError extends Error {}
+
+const unescapeSegment = (segment: string) => segment.replace(/~1/g, '/').replace(/~0/g, '~')
+
+function parseFilter(body: string, path: string): Step {
+  const conditions = body.split(',').map((pair): [string, string | null] => {
+    const at = pair.indexOf('=')
+    if (at <= 0) throw new PatchError(`The filter "[${body}]" in "${path}" needs key=value pairs.`)
+    const value = unescapeSegment(pair.slice(at + 1))
+    return [unescapeSegment(pair.slice(0, at)), value.toLowerCase() === 'null' ? null : value]
+  })
+  return { kind: 'filter', conditions }
+}
+
+export function parsePatchPath(path: string): Step[] {
+  if (!path.startsWith('/') || path.length < 2)
+    throw new PatchError(`"${path}" is not a path: it must start with "/" and name something.`)
+  const steps: Step[] = []
+  for (const segment of path.slice(1).split('/')) {
+    const open = segment.indexOf('[')
+    if (open === -1) {
+      steps.push(
+        segment === '-' ? { kind: 'append' } : { kind: 'key', key: unescapeSegment(segment) },
+      )
+      continue
+    }
+    if (!segment.endsWith(']')) throw new PatchError(`The filter in "${path}" is not closed.`)
+    if (open > 0) steps.push({ kind: 'key', key: unescapeSegment(segment.slice(0, open)) })
+    steps.push(parseFilter(segment.slice(open + 1, -1), path))
+  }
+  steps.forEach((step, index) => {
+    if (step.kind === 'append' && index !== steps.length - 1)
+      throw new PatchError(`"-" may only end a path, in "${path}".`)
+  })
+  return steps
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+function matchIndex(array: unknown[], step: Extract<Step, { kind: 'filter' }>, path: string) {
+  const index = array.findIndex(
+    (element) =>
+      isRecord(element) &&
+      step.conditions.every(([key, value]) =>
+        value === null
+          ? element[key] === undefined || element[key] === null
+          : element[key] === value,
+      ),
+  )
+  if (index === -1) throw new PatchError(`Nothing in the list matches the filter in "${path}".`)
+  return index
+}
+
+function arrayIndex(array: unknown[], key: string, path: string, allowEnd: boolean): number {
+  if (!/^(0|[1-9]\d*)$/.test(key))
+    throw new PatchError(`"${key}" is not a list position, in "${path}".`)
+  const index = Number(key)
+  if (index > array.length || (!allowEnd && index === array.length))
+    throw new PatchError(`Position ${index} is past the end of the list, in "${path}".`)
+  return index
+}
+
+function child(container: unknown, step: Step, path: string): unknown {
+  if (Array.isArray(container)) {
+    if (step.kind === 'filter') return container[matchIndex(container, step, path)]
+    if (step.kind === 'key') return container[arrayIndex(container, step.key, path, false)]
+  } else if (isRecord(container) && step.kind === 'key') {
+    if (!(step.key in container)) throw new PatchError(`There is no "${step.key}" in "${path}".`)
+    return container[step.key]
+  }
+  throw new PatchError(`"${path}" does not lead anywhere in the document.`)
+}
+
+function applyOne(root: unknown, operation: PatchOperation): unknown {
+  const { op, path } = operation
+  if (op !== 'replace' && op !== 'add' && op !== 'remove')
+    throw new PatchError(
+      `"${op}" is not an operation this endpoint supports: use replace, add or remove.`,
+    )
+  if (op !== 'remove' && !('value' in operation))
+    throw new PatchError(`"${op}" at "${path}" needs a value.`)
+  const steps = parsePatchPath(path)
+  const last = steps[steps.length - 1] as Step
+  if (last.kind === 'append' && op !== 'add')
+    throw new PatchError(`"-" appends, so only add may use it, in "${path}".`)
+  let parent = root
+  for (const step of steps.slice(0, -1)) parent = child(parent, step, path)
+
+  if (Array.isArray(parent)) {
+    const index =
+      last.kind === 'append'
+        ? parent.length
+        : last.kind === 'filter'
+          ? matchIndex(parent, last, path)
+          : arrayIndex(parent, last.key, path, op === 'add')
+    if (op === 'remove') parent.splice(index, 1)
+    else if (op === 'add' && last.kind !== 'filter') parent.splice(index, 0, operation.value)
+    else parent[index] = operation.value
+    return root
+  }
+  if (isRecord(parent) && last.kind === 'key') {
+    if (op === 'remove') {
+      if (!(last.key in parent))
+        throw new PatchError(`There is no "${last.key}" to remove, in "${path}".`)
+      delete parent[last.key]
+    } else parent[last.key] = operation.value
+    return root
+  }
+  throw new PatchError(`"${path}" does not lead anywhere in the document.`)
+}
+
+export function applyJsonPatch(
+  document: unknown,
+  operations: readonly PatchOperation[],
+): PatchResult {
+  try {
+    let value = structuredClone(document)
+    for (const operation of operations) value = applyOne(value, operation)
+    return { ok: true, value }
+  } catch (error) {
+    if (error instanceof PatchError) return { ok: false, reason: error.message }
+    throw error
+  }
+}

package/src/problem-details.ts

@@ -31,6 +31,10 @@ export function problemResponse(problem: ProblemDetails, headers?: HeadersInit):
   })
 }
 
+/** Contention that outlasted the wait: the caller may simply try again. */
+export const serviceBusy = (detail: string) =>
+  problemDetails({ title: 'Service Unavailable', status: 503, detail, operationStatus: 'Busy' })
+
 export const notFound = (title = 'Not Found', detail?: string) =>
   problemDetails({ title, status: 404, detail, operationStatus: 'NotFound' })
 

package/src/sections.ts

@@ -25,6 +25,8 @@ export const SECTION_ALIASES = {
   // commercial add-on there. Form building is in core here, so the section is
   // real and the alias resolves (`docs/forms.md`).
   forms: 'Crombolo.Section.Forms',
+  // Approval workflows: Umbraco Workflow's section, in core here (story 028).
+  workflow: 'Crombolo.Section.Workflow',
 } as const
 
 export type AppAlias = keyof typeof SECTION_ALIASES

package/src/workflows.ts

@@ -0,0 +1,227 @@
+/**
+ * Approval workflows (story 028): a workflow is an acyclic graph of stages, each
+ * approved by named user groups. Arrows out of a stage are followed in
+ * parallel; a stage with several arrows in waits for all of them; when every
+ * last stage has approved, the page is published. `docs/workflows.md`.
+ *
+ * The model and the graph rules are here, pure, so the schema check, the
+ * engine and the designer agree on what a workflow means.
+ */
+
+/** How many of a stage's approvers must approve: one, a majority, all, or a number. */
+export type StageRequirement = 'one' | 'majority' | 'all' | number
+
+/** What saving a page does while it waits for approval. */
+export type WorkflowOnEdit = 'withdraw' | 'approve-latest' | 'lock' | 'lock-after-first-approval'
+
+/** Whether the person who made the change may approve it. */
+export type WorkflowSelfApproval = 'refused' | 'allowed' | 'automatic'
+
+/** When a decision needs a comment. */
+export type WorkflowComments = 'optional' | 'on-send-back' | 'always'
+
+/** What a request in flight does when its workflow changes. */
+export type WorkflowOnChange = 'keep' | 'restart' | 'withdraw'
+
+export const WORKFLOW_ON_EDIT: readonly WorkflowOnEdit[] = [
+  'withdraw',
+  'approve-latest',
+  'lock',
+  'lock-after-first-approval',
+]
+export const WORKFLOW_SELF_APPROVAL: readonly WorkflowSelfApproval[] = [
+  'refused',
+  'allowed',
+  'automatic',
+]
+export const WORKFLOW_COMMENTS: readonly WorkflowComments[] = ['optional', 'on-send-back', 'always']
+export const WORKFLOW_ON_CHANGE: readonly WorkflowOnChange[] = ['keep', 'restart', 'withdraw']
+
+/** Where a send-back from a stage goes. */
+export const SEND_BACK_TO_EDITOR = 'editor'
+
+export interface WorkflowStage {
+  alias: string
+  name?: string
+  /** User group aliases. */
+  approvers: string[]
+  required: StageRequirement
+  /** Stage aliases that follow this one; empty for a last stage. */
+  next: string[]
+  /** `editor`, or the alias of an earlier stage on this one's path. */
+  sendBack: string
+  /** Where the designer drew it. */
+  position?: { x: number; y: number }
+}
+
+export interface SchemaWorkflow {
+  key?: string
+  alias: string
+  name: string
+  appliesTo: { branches: string[]; contentTypes: string[] }
+  publishersMaySkip: boolean
+  onEdit: WorkflowOnEdit
+  selfApproval: WorkflowSelfApproval
+  comments: WorkflowComments
+  unpublish: boolean
+  onChange: WorkflowOnChange
+  stages: WorkflowStage[]
+}
+
+const byAlias = (workflow: SchemaWorkflow) => new Map(workflow.stages.map((s) => [s.alias, s]))
+
+/** The stages with no arrow in: a valid workflow has exactly one. Pure. */
+export function startStages(workflow: SchemaWorkflow): string[] {
+  const reached = new Set(workflow.stages.flatMap((s) => s.next))
+  return workflow.stages.filter((s) => !reached.has(s.alias)).map((s) => s.alias)
+}
+
+/** The stages with an arrow into this one. Pure. */
+export function incomingStages(workflow: SchemaWorkflow, alias: string): string[] {
+  return workflow.stages.filter((s) => s.next.includes(alias)).map((s) => s.alias)
+}
+
+/** Every stage this one can be reached from. Pure. */
+export function ancestorStages(workflow: SchemaWorkflow, alias: string): Set<string> {
+  const found = new Set<string>()
+  const visit = (at: string) => {
+    for (const parent of incomingStages(workflow, at)) {
+      if (found.has(parent)) continue
+      found.add(parent)
+      visit(parent)
+    }
+  }
+  visit(alias)
+  return found
+}
+
+/** Every stage reachable from this one, itself excluded. Pure. */
+export function descendantStages(workflow: SchemaWorkflow, alias: string): Set<string> {
+  const stages = byAlias(workflow)
+  const found = new Set<string>()
+  const visit = (at: string) => {
+    for (const child of stages.get(at)?.next ?? []) {
+      if (found.has(child)) continue
+      found.add(child)
+      visit(child)
+    }
+  }
+  visit(alias)
+  return found
+}
+
+/** Whether adding an arrow `from` → `to` would close a loop. Pure. */
+export function wouldLoop(workflow: SchemaWorkflow, from: string, to: string): boolean {
+  return from === to || descendantStages(workflow, to).has(from)
+}
+
+/** What is wrong with a workflow's graph, in words; empty when it is sound. Pure. */
+export function workflowGraphProblems(
+  workflow: SchemaWorkflow,
+): Array<{ path: string; message: string }> {
+  const problems: Array<{ path: string; message: string }> = []
+  const seen = new Set<string>()
+  workflow.stages.forEach((stage, i) => {
+    if (seen.has(stage.alias))
+      problems.push({ path: `stage[${i}].alias`, message: `"${stage.alias}" names two stages` })
+    seen.add(stage.alias)
+  })
+  if (workflow.stages.length === 0)
+    return [{ path: 'stage', message: 'a workflow needs at least one stage' }]
+  workflow.stages.forEach((stage, i) => {
+    for (const next of stage.next)
+      if (!seen.has(next))
+        problems.push({ path: `stage[${i}].next`, message: `there is no stage "${next}"` })
+    if (stage.approvers.length === 0)
+      problems.push({ path: `stage[${i}].approvers`, message: 'a stage needs an approver group' })
+    if (
+      typeof stage.required === 'number' &&
+      (!Number.isInteger(stage.required) || stage.required < 1)
+    )
+      problems.push({ path: `stage[${i}].required`, message: 'a number of approvers is 1 or more' })
+  })
+  if (problems.length > 0) return problems
+
+  // A loop first: the rest of the rules assume there is none.
+  const state = new Map<string, 'visiting' | 'done'>()
+  const stages = byAlias(workflow)
+  let loop: string | undefined
+  const visit = (alias: string): void => {
+    if (loop) return
+    state.set(alias, 'visiting')
+    for (const next of stages.get(alias)?.next ?? []) {
+      if (state.get(next) === 'visiting') loop = `${alias} → ${next}`
+      else if (!state.has(next)) visit(next)
+    }
+    state.set(alias, 'done')
+  }
+  for (const stage of workflow.stages) if (!state.has(stage.alias)) visit(stage.alias)
+  if (loop) return [{ path: 'stage', message: `the stages loop (${loop})` }]
+
+  const starts = startStages(workflow)
+  if (starts.length !== 1)
+    problems.push({
+      path: 'stage',
+      message: `a workflow starts at one stage, and this one starts at ${starts.length}: ${starts.join(', ')}`,
+    })
+  workflow.stages.forEach((stage, i) => {
+    if (stage.sendBack === SEND_BACK_TO_EDITOR) return
+    if (!ancestorStages(workflow, stage.alias).has(stage.sendBack))
+      problems.push({
+        path: `stage[${i}].send-back`,
+        message: `"${stage.alias}" can send back only to the editor or a stage before it, and "${stage.sendBack}" is not`,
+      })
+  })
+  return problems
+}
+
+/** How many approvals a stage needs, given how many people its groups hold. Pure. */
+export function approvalsNeeded(required: StageRequirement, members: number): number {
+  const available = Math.max(members, 1)
+  if (required === 'one') return 1
+  if (required === 'all') return available
+  if (required === 'majority') return Math.floor(available / 2) + 1
+  // More than the groups hold could never be met; the groups are the ceiling.
+  return Math.min(required, available)
+}
+
+/**
+ * The stages that become waiting now that `approved` are done: every stage
+ * whose arrows in all come from approved stages, not already reached. Pure.
+ */
+export function stagesNowWaiting(
+  workflow: SchemaWorkflow,
+  approved: ReadonlySet<string>,
+  reached: ReadonlySet<string>,
+): string[] {
+  return workflow.stages
+    .filter((stage) => !reached.has(stage.alias))
+    .filter((stage) => {
+      const from = incomingStages(workflow, stage.alias)
+      return from.length > 0 && from.every((alias) => approved.has(alias))
+    })
+    .map((stage) => stage.alias)
+}
+
+/** Whether every last stage has approved, which publishes the page. Pure. */
+export function workflowComplete(workflow: SchemaWorkflow, approved: ReadonlySet<string>): boolean {
+  return workflow.stages.filter((s) => s.next.length === 0).every((s) => approved.has(s.alias))
+}
+
+/**
+ * The workflow that covers a page: the nearest branch root among the page and
+ * its ancestors (nearest first), and only then one naming its content type. Pure.
+ */
+export function workflowFor(
+  workflows: readonly SchemaWorkflow[],
+  chain: readonly string[],
+  contentTypeAlias: string | undefined,
+): SchemaWorkflow | undefined {
+  const lower = (value: string) => value.toLowerCase()
+  for (const key of [...chain].reverse()) {
+    const found = workflows.find((w) => w.appliesTo.branches.some((b) => lower(b) === lower(key)))
+    if (found) return found
+  }
+  if (!contentTypeAlias) return undefined
+  return workflows.find((w) => w.appliesTo.contentTypes.includes(contentTypeAlias))
+}