@crombolo/render 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/render",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "TSX server rendering and the published-content model for crombolo.",
   "license": "MIT",
   "author": "Crombolo",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.11.0",
+    "@crombolo/core": "0.12.1",
     "@types/react": "^19.3.0"
   }
 }

package/src/form-script.ts

@@ -1,5 +1,6 @@
 /**
- * The progressive-enhancement script for a rendered form.
+ * The progressive-enhancement script for a rendered form: conditions, and
+ * stepping a `step-pages` form one page at a time.
  *
  * Held as a string rather than a file so it travels with the package and needs
  * no build step or path resolution. It is small on purpose: the server
@@ -11,9 +12,11 @@
  * step by `tests/forms-conditions.test.ts`, which runs the same cases through
  * both.
  */
+import { FORM_PAGE_FIELD } from '@crombolo/core'
+
 export const FORM_SCRIPT_PATH = '/crombolo/forms.js'
 
-export const FORM_SCRIPT = `/* crombolo form conditions */
+export const FORM_SCRIPT = `/* crombolo forms: conditions and stepped pages */
 (function () {
   if (window.__cromboloForms) return
 
@@ -78,7 +81,11 @@ export const FORM_SCRIPT = `/* crombolo form conditions */
         continue
       }
       var visible = shown(form, condition)
-      element.hidden = !visible
+      // A stepped form's page is shown by the stepper, which skips one its
+      // condition hides; everything else is shown or hidden here.
+      if (stepped(form) && element.classList.contains('crombolo-form__page'))
+        element.setAttribute('data-condition-hidden', visible ? 'false' : 'true')
+      else element.hidden = !visible
       // A hidden field must not be required, or the browser refuses to submit a
       // form over something nobody can see.
       var wasRequired = element.getAttribute('data-required') === 'true'
@@ -95,16 +102,146 @@ export const FORM_SCRIPT = `/* crombolo form conditions */
     }
   }
 
+  function stepped(form) {
+    return form.getAttribute('data-step-pages') === 'true'
+  }
+
+  function pagesOf(form) {
+    return Array.prototype.slice.call(form.querySelectorAll('.crombolo-form__page'))
+  }
+
+  function open(page) {
+    return page.getAttribute('data-condition-hidden') !== 'true'
+  }
+
+  /** The next page a visitor can reach from \`from\`, going \`step\` (1 or -1); -1 when none. */
+  function neighbour(form, from, step) {
+    var pages = pagesOf(form)
+    for (var i = from + step; i >= 0 && i < pages.length; i += step) if (open(pages[i])) return i
+    return -1
+  }
+
+  function current(form) {
+    return Number(form.getAttribute('data-step-current') || 0)
+  }
+
+  function layout(form) {
+    if (!stepped(form)) return
+    var pages = pagesOf(form)
+    var at = current(form)
+    // A condition can close the page a visitor is on: step back to one that is open.
+    if (!pages[at] || !open(pages[at])) {
+      var back = neighbour(form, at, -1)
+      at = back === -1 ? neighbour(form, -1, 1) : back
+      form.setAttribute('data-step-current', String(at))
+    }
+    for (var i = 0; i < pages.length; i++) pages[i].hidden = i !== at
+    var last = neighbour(form, at, 1) === -1
+    var buttons = {
+      back: form.querySelector('[data-step="back"]'),
+      next: form.querySelector('[data-step="next"]'),
+      submit: form.querySelector('.crombolo-form__submit'),
+    }
+    if (buttons.back) buttons.back.hidden = neighbour(form, at, -1) === -1
+    if (buttons.next) buttons.next.hidden = last
+    if (buttons.submit) buttons.submit.hidden = !last
+  }
+
+  function showErrors(page, errors) {
+    var old = page.querySelectorAll('[data-step-error]')
+    for (var i = 0; i < old.length; i++) old[i].parentNode.removeChild(old[i])
+    var marked = page.querySelectorAll('.crombolo-form__field--invalid')
+    for (var j = 0; j < marked.length; j++) marked[j].classList.remove('crombolo-form__field--invalid')
+    var first = null
+    for (var k = 0; k < errors.length; k++) {
+      var field = page.querySelector('[data-field="' + errors[k].field + '"]')
+      if (!field) continue
+      field.classList.add('crombolo-form__field--invalid')
+      var message = document.createElement('p')
+      message.className = 'crombolo-form__error'
+      message.setAttribute('role', 'alert')
+      message.setAttribute('data-step-error', 'true')
+      message.textContent = errors[k].message
+      field.appendChild(message)
+      if (!first) first = field.querySelector('input, select, textarea')
+    }
+    if (first) first.focus()
+  }
+
+  function go(form, to) {
+    form.setAttribute('data-step-current', String(to))
+    layout(form)
+    var page = pagesOf(form)[to]
+    if (page && page.scrollIntoView) page.scrollIntoView({ block: 'start' })
+    var input = page && page.querySelector('input:not([type="hidden"]), select, textarea')
+    if (input) input.focus()
+  }
+
+  /** Checks this page on the server, then moves on. A failure to reach it moves on too: the submit checks everything. */
+  function next(form) {
+    var at = current(form)
+    var to = neighbour(form, at, 1)
+    if (to === -1) return
+    var button = form.querySelector('[data-step="next"]')
+    if (button) button.disabled = true
+    var data = new FormData(form)
+    data.set('${FORM_PAGE_FIELD}', String(at))
+    fetch(form.action, {
+      method: 'POST',
+      body: data,
+      credentials: 'same-origin',
+      headers: { accept: 'application/json' },
+    })
+      .then(function (response) {
+        return response.json().catch(function () { return { ok: response.ok } })
+      })
+      .catch(function () { return { ok: true } })
+      .then(function (result) {
+        if (button) button.disabled = false
+        var page = pagesOf(form)[at]
+        if (result && result.ok === false && result.errors) return showErrors(page, result.errors)
+        showErrors(page, [])
+        go(form, to)
+      })
+  }
+
+  function attachSteps(form) {
+    if (!stepped(form)) return
+    // After a refused submission, open on the first page the server complained about.
+    var pages = pagesOf(form)
+    for (var i = 0; i < pages.length; i++)
+      if (pages[i].querySelector('.crombolo-form__field--invalid')) {
+        form.setAttribute('data-step-current', String(i))
+        break
+      }
+    layout(form)
+    var nextButton = form.querySelector('[data-step="next"]')
+    var backButton = form.querySelector('[data-step="back"]')
+    if (nextButton) nextButton.addEventListener('click', function () { next(form) })
+    if (backButton)
+      backButton.addEventListener('click', function () {
+        var to = neighbour(form, current(form), -1)
+        if (to !== -1) go(form, to)
+      })
+    // Enter on an earlier page means "next", not "submit".
+    form.addEventListener('submit', function (event) {
+      if (neighbour(form, current(form), 1) === -1) return
+      event.preventDefault()
+      next(form)
+    })
+  }
+
   function attach(form) {
     apply(form)
-    form.addEventListener('input', function () { apply(form) })
-    form.addEventListener('change', function () { apply(form) })
+    attachSteps(form)
+    form.addEventListener('input', function () { apply(form); layout(form) })
+    form.addEventListener('change', function () { apply(form); layout(form) })
   }
 
   // Also the guard against running twice, which two forms on a page would
   // otherwise do. Exposed rather than a bare flag so the suite can hold these
   // two functions against the server's own -- see tests/forms-conditions.
-  window.__cromboloForms = { rule: rule, shown: shown, apply: apply }
+  window.__cromboloForms = { rule: rule, shown: shown, apply: apply, layout: layout, neighbour: neighbour }
 
   var forms = document.querySelectorAll('form.crombolo-form')
   for (var i = 0; i < forms.length; i++) attach(forms[i])

package/src/forms.ts

@@ -17,13 +17,18 @@
  * `docs/forms.md` says why this diverges from Umbraco's theme folders.
  */
 import {
+  BUILT_IN_FORM_TYPES,
+  type BuiltInFormFieldType,
+  choiceOptions,
   FORM_HONEYPOT_FIELD,
   FORM_RENDERED_FIELD,
   FORM_TOKEN_FIELD,
   type FormFieldError,
   type FormFieldType,
   type FormSubmissionState,
+  type FormTypes,
   formFieldType,
+  isBuiltInFieldType,
   isShown,
   type SchemaForm,
   type SchemaFormField,
@@ -54,6 +59,23 @@ export function setFormTokenSigner(
   signer = sign
 }
 
+/**
+ * The field types a wired bundle adds, and how each draws itself. Process-wide
+ * for the reason the signer is: bundles are wired once per process, at boot.
+ * A site's own `components` still wins over a bundle's renderer.
+ */
+let registered: { types: FormTypes; renderers: ReadonlyMap<string, FormFieldRenderer> } = {
+  types: BUILT_IN_FORM_TYPES,
+  renderers: new Map(),
+}
+
+export function setFormFieldTypes(
+  types: FormTypes,
+  renderers: ReadonlyMap<string, FormFieldRenderer>,
+): void {
+  registered = { types, renderers }
+}
+
 export const formAction = (form: SchemaForm): string =>
   `${FORM_SUBMIT_PATH}/${encodeURIComponent(form.key ?? form.alias)}`
 
@@ -119,7 +141,7 @@ const checked = (values: readonly string[]): boolean =>
   values.some((value) => value === 'true' || value === 'on' || value === '1')
 
 /** The input types that are a plain `<input>` differing only by `type`. */
-const INPUT_TYPES: Partial<Record<FormFieldType, string>> = {
+const INPUT_TYPES: Partial<Record<BuiltInFormFieldType, string>> = {
   shortAnswer: 'text',
   email: 'email',
   number: 'number',
@@ -131,7 +153,7 @@ function textInput({ field, values, id, name, error, shown }: FormFieldRenderPro
   return element(
     'input',
     attrs({
-      type: INPUT_TYPES[field.type] ?? 'text',
+      type: INPUT_TYPES[field.type as BuiltInFormFieldType] ?? 'text',
       id,
       name,
       value: first(values),
@@ -159,7 +181,7 @@ const describedBy = (
   return ids.length > 0 ? ids.join(' ') : undefined
 }
 
-const DEFAULTS: Record<FormFieldType, FormFieldRenderer> = {
+const DEFAULTS: Record<BuiltInFormFieldType, FormFieldRenderer> = {
   shortAnswer: textInput,
   email: textInput,
   number: textInput,
@@ -229,13 +251,13 @@ const DEFAULTS: Record<FormFieldType, FormFieldRenderer> = {
           field.mandatory || first(values) === ''
             ? element('option', { value: '', children: field.placeholder ?? '' })
             : null,
-          ...field.values.map((option) =>
+          ...choiceOptions(field).map((option) =>
             element(
               'option',
               attrs({
-                value: option,
-                selected: option === first(values) || undefined,
-                children: option,
+                value: option.value,
+                selected: option.value === first(values) || undefined,
+                children: option.label,
               }),
             ),
           ),
@@ -247,7 +269,7 @@ const DEFAULTS: Record<FormFieldType, FormFieldRenderer> = {
     element('div', {
       class: 'crombolo-form__choices',
       role: 'radiogroup',
-      children: field.values.map((option, index) =>
+      children: choiceOptions(field).map((option, index) =>
         element('label', {
           class: 'crombolo-form__choice',
           children: [
@@ -257,12 +279,12 @@ const DEFAULTS: Record<FormFieldType, FormFieldRenderer> = {
                 type: 'radio',
                 id: `${id}-${index}`,
                 name,
-                value: option,
-                checked: option === first(values) || undefined,
+                value: option.value,
+                checked: option.value === first(values) || undefined,
                 required: (field.mandatory && shown) || undefined,
               }),
             ),
-            element('span', { children: option }),
+            element('span', { children: option.label }),
           ],
         }),
       ),
@@ -271,7 +293,7 @@ const DEFAULTS: Record<FormFieldType, FormFieldRenderer> = {
   multipleChoice: ({ field, values, id, name }) =>
     element('div', {
       class: 'crombolo-form__choices',
-      children: field.values.map((option, index) =>
+      children: choiceOptions(field).map((option, index) =>
         element('label', {
           class: 'crombolo-form__choice',
           children: [
@@ -281,11 +303,11 @@ const DEFAULTS: Record<FormFieldType, FormFieldRenderer> = {
                 type: 'checkbox',
                 id: `${id}-${index}`,
                 name,
-                value: option,
-                checked: values.includes(option) || undefined,
+                value: option.value,
+                checked: values.includes(option.value) || undefined,
               }),
             ),
-            element('span', { children: option }),
+            element('span', { children: option.label }),
           ],
         }),
       ),
@@ -333,7 +355,11 @@ export function rendererFor(
   type: FormFieldType,
   components: FormFieldComponents | undefined,
 ): FormFieldRenderer | undefined {
-  return components?.[type] ?? DEFAULTS[type]
+  return (
+    components?.[type] ??
+    registered.renderers.get(type) ??
+    (isBuiltInFieldType(type) ? DEFAULTS[type] : undefined)
+  )
 }
 
 function renderField(
@@ -345,7 +371,7 @@ function renderField(
     idPrefix: string
   },
 ): Child {
-  const info = formFieldType(field.type)
+  const info = formFieldType(field.type, registered.types)
   if (!info) return null
   const renderer = rendererFor(field.type, options.components)
   if (!renderer) return null
@@ -459,9 +485,9 @@ function renderPage(
 /**
  * A form, as HTML.
  *
- * Every page is rendered into one form rather than one page at a time. A
- * multi-page definition therefore submits in one go; stepping through pages with
- * a round trip each is a refinement on top of this, not a different shape.
+ * Every page is rendered into one form. With `step-pages` the script shows one
+ * at a time and checks each on the server before the next; answers stay in the
+ * form, uploads included, until the one submission at the end.
  */
 export function Form(props: FormProps): RawHtml {
   const form = props.form
@@ -495,6 +521,7 @@ export function Form(props: FormProps): RawHtml {
   if (props.className) classes.push(props.className)
 
   const key = form.key ?? form.alias
+  const stepped = form.stepPages === true && form.pages.length > 1
   const renderedAt = props.renderedAt ?? Date.now()
   const token = props.token ?? signer?.(key, renderedAt)
 
@@ -508,6 +535,7 @@ export function Form(props: FormProps): RawHtml {
       enctype: hasUpload ? 'multipart/form-data' : undefined,
       class: classes.join(' '),
       'data-form': form.alias,
+      'data-step-pages': stepped ? 'true' : undefined,
       novalidate: undefined,
       children: [
         errors.length > 0
@@ -545,11 +573,33 @@ export function Form(props: FormProps): RawHtml {
           : null,
         element('div', {
           class: 'crombolo-form__actions',
-          children: element('button', {
-            type: 'submit',
-            class: 'crombolo-form__submit',
-            children: form.submitLabel ?? 'Submit',
-          }),
+          children: [
+            // Hidden until the script takes over: without it every page shows
+            // and the form submits in one go, so these would do nothing.
+            stepped
+              ? element('button', {
+                  type: 'button',
+                  class: 'crombolo-form__back',
+                  'data-step': 'back',
+                  hidden: true,
+                  children: form.previousLabel ?? 'Back',
+                })
+              : null,
+            stepped
+              ? element('button', {
+                  type: 'button',
+                  class: 'crombolo-form__next',
+                  'data-step': 'next',
+                  hidden: true,
+                  children: form.nextLabel ?? 'Next',
+                })
+              : null,
+            element('button', {
+              type: 'submit',
+              class: 'crombolo-form__submit',
+              children: form.submitLabel ?? 'Submit',
+            }),
+          ],
         }),
       ],
     }),

package/src/media.ts

@@ -124,6 +124,10 @@ export class PublishedMedia {
   readonly name: string
   readonly mediaType: { alias: string }
   readonly properties: PublishedProperty[]
+  readonly parentId: number
+  readonly sortOrder: number
+  readonly createDate: Date
+  readonly updateDate: Date
 
   constructor(init: {
     key: string
@@ -131,12 +135,20 @@ export class PublishedMedia {
     name: string
     mediaTypeAlias: string
     properties: PublishedProperty[]
+    parentId?: number
+    sortOrder?: number
+    createDate?: Date
+    updateDate?: Date
   }) {
     this.key = init.key
     this.id = init.id
     this.name = init.name
     this.mediaType = { alias: init.mediaTypeAlias }
     this.properties = init.properties
+    this.parentId = init.parentId ?? -1
+    this.sortOrder = init.sortOrder ?? 0
+    this.createDate = init.createDate ?? new Date(0)
+    this.updateDate = init.updateDate ?? this.createDate
   }
 
   /** The file's URL: what `umbracoFile` holds. */

package/src/published-cache.ts

@@ -12,7 +12,12 @@
  * navigation resolve within the culture of the page that asks.
  */
 
-import type { SchemaForm } from '@crombolo/core'
+import {
+  type ChoiceOption,
+  type ChoiceSource,
+  type SchemaForm,
+  withResolvedChoices,
+} from '@crombolo/core'
 import { PublishedMedia } from './media.ts'
 import { type Navigation, PublishedContent, type PublishedProperty } from './model.ts'
 import { matchRedirect, type RedirectRule } from './redirects.ts'
@@ -71,12 +76,52 @@ export interface PublishedContentSource {
   loadLanguages?(): Promise<PublishedLanguage[]>
   /** Dictionary translations, by item key then culture; none when omitted. */
   loadDictionary?(): Promise<Map<string, Map<string, string>>>
+  /** Every dictionary item with its parent's name, for choice lists; none when omitted. */
+  loadDictionaryOutline?(): Promise<DictionaryOutlineItem[]>
   /** Redirect rules, configured ones first; none when omitted. */
   loadRedirects?(): Promise<RedirectRule[]>
   /** Published library elements, for the pickers that point at them; none when omitted. */
   loadElements?(): Promise<PublishedElementNode[]>
   /** Content type aliases by key, so a block knows its element type; none when omitted. */
   loadContentTypeAliases?(): Promise<Map<string, string>>
+  /** How URLs are built; Umbraco's defaults when omitted. */
+  loadUrlOptions?(): Promise<PublishedUrlOptions>
+}
+
+/** `HideTopLevelNodeFromPath`: true, Umbraco's default, leaves the top-level page out of paths. */
+export interface PublishedUrlOptions {
+  hideTopLevel: boolean
+}
+
+const RTL_LANGUAGES = new Set([
+  'ar',
+  'arc',
+  'ckb',
+  'dv',
+  'fa',
+  'ha',
+  'he',
+  'khw',
+  'ks',
+  'ps',
+  'sd',
+  'ur',
+  'yi',
+])
+
+/** Whether a culture is written right to left, as .NET's `TextInfo.IsRightToLeft` says. Pure. */
+export function isRightToLeft(culture: string | null | undefined): boolean {
+  if (!culture) return false
+  try {
+    const locale = new Intl.Locale(culture) as Intl.Locale & {
+      getTextInfo?: () => { direction?: string }
+    }
+    const direction = locale.getTextInfo?.().direction
+    if (direction) return direction === 'rtl'
+    return RTL_LANGUAGES.has(locale.language)
+  } catch {
+    return false
+  }
 }
 
 /**
@@ -99,6 +144,11 @@ export interface PublishedMediaNode {
   name: string
   mediaTypeAlias: string
   properties: PublishedProperty[]
+  /** Its place in the media tree; a root item's parent is -1. */
+  parentId?: number
+  sortOrder?: number
+  createDate?: Date
+  updateDate?: Date
 }
 
 /** The published tree in one culture. */
@@ -113,10 +163,18 @@ export interface CultureView {
   parentIdOf: Map<number, number>
 }
 
+export interface DictionaryOutlineItem {
+  key: string
+  name: string
+  parentName: string | null
+}
+
 export interface CacheSnapshot {
   /** Keyed by lowercase culture; `''` holds an invariant site's single view. */
   views: Map<string, CultureView>
   defaultCulture: string | null
+  /** `HideTopLevelNodeFromPath`, as this snapshot was built with it. */
+  hideTopLevel?: boolean
   /** Routes without a hostname, in the default culture. */
   byRoute: Map<string, PublishedContent>
   /** `<domain name>:<route below it>`, for requests that match a hostname. */
@@ -132,6 +190,8 @@ export interface CacheSnapshot {
   media: Map<string, PublishedMedia>
   /** Item key (lowercase) → culture (lowercase) → translation. */
   dictionary: Map<string, Map<string, string>>
+  /** Every dictionary item, for a choice list drawn from one item's children. */
+  dictionaryOutline: DictionaryOutlineItem[]
   /** Content type key (lowercase) → alias. */
   contentTypeAliases: Map<string, string>
 }
@@ -177,6 +237,7 @@ const EMPTY: CacheSnapshot = {
   languages: [],
   media: new Map(),
   dictionary: new Map(),
+  dictionaryOutline: [],
   contentTypeAliases: new Map(),
 }
 
@@ -222,6 +283,10 @@ export class PublishedCache {
   #snapshot: CacheSnapshot = EMPTY
   #loaded = false
   #options: PublishedCacheOptions
+  /** Moves on every invalidation, so a build that one overtook is not kept as current. */
+  #generation = 0
+  #building: { generation: number; done: Promise<CacheSnapshot> } | undefined
+  #snapshotGeneration = -1
 
   constructor(source: PublishedContentSource, options: PublishedCacheOptions = {}) {
     this.#source = source
@@ -231,14 +296,35 @@ export class PublishedCache {
   /** Dropped on publish or unpublish; the next read rebuilds it. */
   invalidate(): void {
     this.#loaded = false
+    this.#generation += 1
   }
 
+  /**
+   * The current snapshot, building it if it was dropped. Readers that arrive
+   * while it builds share that build rather than each starting one; a build
+   * an invalidation overtook still answers, but the next read builds again.
+   */
   async snapshot(): Promise<CacheSnapshot> {
-    if (!this.#loaded) {
-      this.#snapshot = await this.#build()
-      this.#loaded = true
-    }
-    return this.#snapshot
+    if (this.#loaded) return this.#snapshot
+    const generation = this.#generation
+    if (this.#building?.generation === generation) return this.#building.done
+    const done = this.#build().then((snapshot) => {
+      // A slower, older build must not replace a newer one that finished first.
+      if (generation >= this.#snapshotGeneration) {
+        this.#snapshot = snapshot
+        this.#snapshotGeneration = generation
+      }
+      if (this.#generation === generation) this.#loaded = true
+      return snapshot
+    })
+    const building = { generation, done }
+    this.#building = building
+    void done
+      .finally(() => {
+        if (this.#building === building) this.#building = undefined
+      })
+      .catch(() => {})
+    return done
   }
 
   #view(snapshot: CacheSnapshot, culture: string | null | undefined): CultureView | undefined {
@@ -372,6 +458,42 @@ export class PublishedCache {
     return out
   }
 
+  /** Every published document a culture can see, in tree order: what a headless query scans. */
+  async contentIn(culture?: string | null): Promise<PublishedContent[]> {
+    const snapshot = await this.snapshot()
+    const view = this.#view(snapshot, culture)
+    if (!view) return []
+    const out: PublishedContent[] = []
+    const walk = (items: readonly PublishedContent[]) => {
+      for (const item of items) {
+        out.push(item)
+        walk(view.childrenOf.get(item.id) ?? [])
+      }
+    }
+    walk(view.roots)
+    return out
+  }
+
+  /** Every media item, in tree order. */
+  async allMedia(): Promise<PublishedMedia[]> {
+    return [...(await this.snapshot()).media.values()]
+  }
+
+  /** How URLs are built here: whether the top-level page is left out of paths. */
+  async hidesTopLevel(): Promise<boolean> {
+    return (await this.snapshot()).hideTopLevel ?? true
+  }
+
+  /** The culture a request gets when it names none. */
+  async defaultCulture(): Promise<string | null> {
+    return (await this.snapshot()).defaultCulture
+  }
+
+  /** Whether a culture has a view here: a language the site has. */
+  async hasCulture(culture: string): Promise<boolean> {
+    return (await this.snapshot()).views.has(viewKey(culture))
+  }
+
   /** The published children of a document, or of the tree root; keys, once each. */
   async childKeys(parentKey: string | null): Promise<string[]> {
     const snapshot = await this.snapshot()
@@ -405,7 +527,7 @@ export class PublishedCache {
     return {
       content: (key) => view?.byKey.get(key.toLowerCase()),
       media: (key) => snapshot.media.get(key.toLowerCase()),
-      form: this.#options.form,
+      form: this.#formsIn(snapshot, view, culture ?? null),
       contentTypeAlias: (key) => snapshot.contentTypeAliases.get(key.toLowerCase()),
       urlOf: (content) => content.url,
       mediaUrlOf: (item) => (item as PublishedMedia).url,
@@ -472,6 +594,7 @@ export class PublishedCache {
     const domains = (await this.#source.loadDomains?.()) ?? []
     const languages = (await this.#source.loadLanguages?.()) ?? []
     const dictionary = new Map<string, Map<string, string>>()
+    const dictionaryOutline = (await this.#source.loadDictionaryOutline?.()) ?? []
     for (const [key, translations] of (await this.#source.loadDictionary?.()) ?? new Map())
       dictionary.set(
         key.toLowerCase(),
@@ -515,6 +638,7 @@ export class PublishedCache {
     const firstRootId = nodes
       .filter((node) => node.parentId <= 0)
       .sort((a, b) => a.sortOrder - b.sortOrder)[0]?.id
+    const { hideTopLevel } = (await this.#source.loadUrlOptions?.()) ?? { hideTopLevel: true }
 
     const byRoute = new Map<string, PublishedContent>()
     const byDomainRoute = new Map<string, PublishedContent>()
@@ -555,26 +679,38 @@ export class PublishedCache {
         )
       }
 
+      // Umbraco gathers a path from the page up and reverses it into root-first
+      // order only for a left-to-right culture; a right-to-left one keeps the
+      // page's own segment first.
+      const rtl = isRightToLeft(culture)
+      const inPathOrder = (segments: string[]) => (rtl ? [...segments].reverse() : segments)
+
       /**
        * Umbraco's default (`HideTopLevelNodeFromPath`): a top-level node's segment
        * is left out of every URL below it, the first top-level node is `/`, and any
-       * other is `/<segment>`. A route only exists if every ancestor is also
-       * published in the culture — an unpublished ancestor breaks the route rather
-       * than leaving a reachable orphan.
+       * other is `/<segment>`. With it off, every path starts with its top-level
+       * page's segment, the first one's included. A route only exists if every
+       * ancestor is also published in the culture — an unpublished ancestor breaks
+       * the route rather than leaving a reachable orphan.
        */
       const routeOf = (node: PublishedNode): string | undefined => {
         if (node.parentId <= 0)
-          return node.id === firstRootId ? '/' : joinPath([segmentOf.get(node.id) as string])
+          return node.id === firstRootId && hideTopLevel
+            ? '/'
+            : joinPath([segmentOf.get(node.id) as string])
         const segments: string[] = []
         let current: PublishedNode = node
         for (;;) {
           const parent = nodeById.get(current.parentId)
           if (!parent || !segmentOf.has(parent.id)) return undefined
           segments.unshift(segmentOf.get(current.id) as string)
-          if (parent.parentId <= 0) break
+          if (parent.parentId <= 0) {
+            if (!hideTopLevel) segments.unshift(segmentOf.get(parent.id) as string)
+            break
+          }
           current = parent
         }
-        return joinPath(segments)
+        return joinPath(inPathOrder(segments))
       }
 
       /** The route below the nearest document with a hostname for this culture, if there is one. */
@@ -585,7 +721,7 @@ export class PublishedCache {
         let current: PublishedNode | undefined = node
         while (current && segmentOf.has(current.id)) {
           const domain = domainFor(current.id, culture)
-          if (domain) return { domain, route: joinPath(segments) }
+          if (domain) return { domain, route: joinPath(inPathOrder(segments)) }
           segments.unshift(segmentOf.get(current.id) as string)
           current = nodeById.get(current.parentId)
         }
@@ -657,6 +793,10 @@ export class PublishedCache {
         )
         if (isDefault && !byRoute.has(route.toLowerCase()))
           byRoute.set(route.toLowerCase(), content)
+        // With the top level shown the home page's URL is its own segment, but `/`
+        // still has to answer with it.
+        if (!hideTopLevel && isDefault && node.id === firstRootId && !domainRoute)
+          byRoute.set('/', content)
         // Every hostname on the rooting document serves its own culture's view;
         // one with no culture serves the default's
         if (domainRoute)
@@ -686,7 +826,11 @@ export class PublishedCache {
         // Read lazily: the map is filled just below, with this very context, so an
         // element picking another element resolves too.
         element: (key) => view.elements.get(key.toLowerCase()),
-        form: this.#options.form,
+        form: this.#formsIn(
+          { dictionary, dictionaryOutline, languages, defaultCulture },
+          view,
+          culture,
+        ),
         contentTypeAlias: (key) => contentTypeAliases.get(key.toLowerCase()),
         urlOf: (content) => content.url,
         mediaUrlOf: (item) => item.url,
@@ -736,6 +880,7 @@ export class PublishedCache {
     return {
       views,
       defaultCulture,
+      hideTopLevel,
       byRoute,
       byDomainRoute,
       domains,
@@ -745,9 +890,76 @@ export class PublishedCache {
       languages,
       media,
       dictionary,
+      dictionaryOutline,
       contentTypeAliases,
     }
   }
+
+  /** Form lookups whose source-backed choices resolve against this view and culture. */
+  #formsIn(
+    snapshot: ChoiceSnapshot,
+    view: CultureView | undefined,
+    culture: string | null,
+  ): ((key: string) => SchemaForm | undefined) | undefined {
+    const lookup = this.#options.form
+    if (!lookup) return undefined
+    return (key) => {
+      const form = lookup(key)
+      return form
+        ? withResolvedChoices(form, (source) => resolveChoices(snapshot, view, culture, source))
+        : undefined
+    }
+  }
+
+  /** What a choice source offers now, in `culture`: for the designer, and for a submission. */
+  async choiceOptions(source: ChoiceSource, culture?: string | null): Promise<ChoiceOption[]> {
+    const snapshot = await this.snapshot()
+    return resolveChoices(snapshot, this.#view(snapshot, culture), culture ?? null, source)
+  }
+
+  /** The form with its source-backed choices resolved, as a page in `culture` would render it. */
+  async resolveForm(form: SchemaForm, culture?: string | null): Promise<SchemaForm> {
+    const snapshot = await this.snapshot()
+    const view = this.#view(snapshot, culture)
+    return withResolvedChoices(form, (source) =>
+      resolveChoices(snapshot, view, culture ?? null, source),
+    )
+  }
+}
+
+type ChoiceSnapshot = Pick<
+  CacheSnapshot,
+  'dictionary' | 'dictionaryOutline' | 'languages' | 'defaultCulture'
+>
+
+/**
+ * A choice source's options: a published page's children by key and name, or a
+ * dictionary item's children by key and translation. Nothing when the parent is gone.
+ */
+export function resolveChoices(
+  snapshot: ChoiceSnapshot,
+  view: CultureView | undefined,
+  culture: string | null,
+  source: ChoiceSource,
+): ChoiceOption[] {
+  if (source.kind === 'content') {
+    const parent = view?.byKey.get(source.parent.toLowerCase())
+    if (!parent || !view) return []
+    return (view.childrenOf.get(parent.id) ?? []).map((child) => ({
+      value: child.key,
+      label: child.name,
+    }))
+  }
+  if (source.kind === 'dictionary') {
+    const parent = source.parent.toLowerCase()
+    return snapshot.dictionaryOutline
+      .filter((item) => item.parentName?.toLowerCase() === parent)
+      .map((item) => ({
+        value: item.key,
+        label: translate(snapshot, item.name, culture) || item.name,
+      }))
+  }
+  return []
 }
 
 /**
@@ -813,7 +1025,11 @@ function descendantsOf(view: CultureView, content: PublishedContent): PublishedC
 }
 
 /** A dictionary item's translation in `culture`, then its fallback languages; '' when none. */
-export function translate(snapshot: CacheSnapshot, key: string, culture: string | null): string {
+export function translate(
+  snapshot: Pick<CacheSnapshot, 'dictionary' | 'languages' | 'defaultCulture'>,
+  key: string,
+  culture: string | null,
+): string {
   const item = snapshot.dictionary.get(key.toLowerCase())
   if (!item) return ''
   const wanted = culture ?? snapshot.defaultCulture