@panphora/hyper-cms 0.11.6 → 0.13.0

package/src/form-rules.js

@@ -5,12 +5,19 @@ import {
   componentForScalarRule,
   winningScalarArrayComponent,
 } from './templates.js'
+import { getRuleAtPath } from './path.js'
 
 const TAG_PROP_MAP = {
   IMG: 'src',
   A: 'href',
 }
 
+// The path with every row index replaced by "*": what a field IS, whichever
+// row it sits in. Form rules scope repeated keys by it.
+export function shapeOf(pathArr) {
+  return pathArr.map((seg) => (typeof seg === 'number' || /^[0-9]+$/.test(String(seg)) ? '*' : String(seg))).join('.')
+}
+
 export function fieldPropertyFor(el) {
   if (!el) return 'value'
   const tag = (el.tagName || '').toUpperCase()
@@ -81,7 +88,29 @@ function cssEscape(value) {
 
 const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
 
+// How many scalar leaves, anywhere in the rules, end in each key.
+function countLeafKeys(pageRules) {
+  const counts = new Map()
+  walk(pageRules, null)
+  return counts
+
+  function walk(rule, key) {
+    if (typeof rule === 'string') {
+      if (typeof key === 'string' && !rule.endsWith('[]')) counts.set(key, (counts.get(key) || 0) + 1)
+      return
+    }
+    if (Array.isArray(rule)) {
+      walk(rule[1], null)
+      return
+    }
+    if (rule && typeof rule === 'object') {
+      for (const [k, child] of Object.entries(rule)) walk(child, k)
+    }
+  }
+}
+
 export function deriveFormRules(pageRules, doc) {
+  const leafKeyCounts = countLeafKeys(pageRules)
   return derive(pageRules, [])
 
   function derive(rule, pathArr) {
@@ -106,15 +135,30 @@ export function deriveFormRules(pageRules, doc) {
     const key = pathArr.length ? pathArr[pathArr.length - 1] : null
     const fieldKey = typeof key === 'string' ? key : '__value'
     const inlineEl = findInlineFieldEl(pathArr, fieldKey)
-    if (inlineEl) return fieldSelectorFor(inlineEl, fieldKey)
+    if (inlineEl) return scopeRepeatedKey(pathArr, fieldKey, fieldSelectorFor(inlineEl, fieldKey))
     // No path-bound override: resolve the component this rule opts into
     // (@scalar / @image / @file) and derive the selector from THAT template's
     // leaf tag, so an @image field reads img@src and an @file field reads
     // a@href, while a plain scalar still respects a global @scalar override
     // (e.g. a <textarea>) instead of assuming <input>.
     const shapeEl = findShapeFieldEl(componentForScalarRule(rule, doc, pathArr, pageRules), fieldKey)
-    if (shapeEl) return fieldSelectorFor(shapeEl, fieldKey)
-    return `input[data-hcms-field="${cssEscape(fieldKey)}"]@value`
+    if (shapeEl) return scopeRepeatedKey(pathArr, fieldKey, fieldSelectorFor(shapeEl, fieldKey))
+    return scopeRepeatedKey(pathArr, fieldKey, `input[data-hcms-field="${cssEscape(fieldKey)}"]@value`)
+  }
+
+  // Two scalars with the same last key (hero.background, features.background,
+  // or a card's title and its links' titles) stamp the same data-hcms-field, so
+  // a bare key selector reads the first one for all of them and a commit copies
+  // one field's value into another. A repeated key is scoped by the field's
+  // shape (its path with row indices as "*"), matched exactly, on the field
+  // itself or on the wrapper around it.
+  function scopeRepeatedKey(pathArr, fieldKey, selector) {
+    if ((leafKeyCounts.get(fieldKey) || 0) < 2) return selector
+    const scope = `[data-hcms-path-shape="${cssEscape(shapeOf(pathArr))}"]`
+    const at = selector.lastIndexOf('@')
+    const sel = at === -1 ? selector : selector.slice(0, at)
+    const prop = at === -1 ? '' : selector.slice(at)
+    return `${scope} ${sel}, ${sel}${scope}${prop}`
   }
 
   function scalarArrayRule(rule, pathArr) {
@@ -190,6 +234,7 @@ export function deriveFormRules(pageRules, doc) {
     const candidates = [pathStr, wildcardKey]
     for (let i = pathArr.length - 1; i >= 0; i--) {
       const slice = pathArr.slice(0, i).map((s) => (typeof s === 'number' ? '*' : s))
+      if (shapeKindOf(getRuleAtPath(pageRules, slice)) === 'object') candidates.push(slice.join('.'))
       slice.push('*')
       candidates.push(slice.join('.'))
     }

package/src/hypercms.js

@@ -20,9 +20,13 @@ import {
   teardownSession,
   nextSearchAfterClose,
   shouldAutoOpenFromSearch,
+  modeLifecycle,
+  canWriteNow,
+  pendingWork,
+  quiesceSession,
+  resumeSession,
 } from './session.js'
 import { findLeafField, writeFieldValue } from './events.js'
-import { maybeInjectToggle } from './toggle.js'
 import { platform, onPlatformEvent, MUTATION_READY } from './platform.js'
 import { installHooks } from './hooks.js'
 
@@ -53,17 +57,36 @@ const VIEWS = {
   inline: createInlineView,
 }
 
+// The page says how it wants to be edited, on the rules tag the session will
+// use: data-cms-view="inline". No tag to read it from (a literal rules object),
+// no attribute, or "sidebar" means the sidebar. An unknown value is a page
+// authoring mistake, not a caller error, so it warns and opens the sidebar.
+function declaredView(doc, rules) {
+  const source = rules !== undefined ? rules : 'cms'
+  if (typeof source !== 'string') return 'sidebar'
+  const declared = engine.findRules(doc, source)?.tagNode?.getAttribute?.('data-cms-view')
+  if (!declared || declared === 'sidebar') return 'sidebar'
+  if (VIEWS[declared]) return declared
+  console.warn(`hypercms: unknown data-cms-view "${declared}" on the rules tag, opening the sidebar`)
+  return 'sidebar'
+}
+
 export function open(opts = {}) {
+  return openSession(opts)
+}
+
+function modeExit(doc) {
+  const win = doc && doc.defaultView
+  if (!modeLifecycle(win)) return null
+  const setMode = win.clay && win.clay.setMode
+  if (typeof setMode !== 'function') return null
+  return setMode.call(win.clay, 'view')
+}
+
+function openSession(opts = {}, admitted = false) {
   // Everything that can be rejected is rejected before anything is destroyed. A
   // bad view name or a missing page must not leave a caller with the session
   // they had already torn down.
-  // A bare open() means "make sure the editor is up", not "put it in the
-  // sidebar". Defaulting to sidebar turned every such call into a view switch.
-  const viewName = opts.view || (state.isOpen ? state.ctx.view.name : 'sidebar')
-  const makeView = VIEWS[viewName]
-  if (!makeView) {
-    throw new Error(`hypercms: unknown view "${viewName}" (expected ${Object.keys(VIEWS).join(' or ')})`)
-  }
   // A switch changes the presentation of one session, not the session. Someone
   // calling open({ view: 'sidebar' }) means "show me this in the sidebar"; they
   // are not restating the pageRoot, the rules and the callbacks they opened
@@ -71,12 +94,23 @@ export function open(opts = {}) {
   // document.body with the default rules tag and stops calling onChange.
   // state.opts holds the active session's options and teardown clears it, so it
   // has to be read here, before anything is torn down.
-  const effective = state.isOpen ? { ...state.opts, ...opts, view: viewName } : opts
+  const merged = state.isOpen ? { ...state.opts, ...opts } : opts
 
-  const pageRoot = effective.pageRoot || (typeof document !== 'undefined' ? document.body : null)
+  const pageRoot = merged.pageRoot || (typeof document !== 'undefined' ? document : null)
   if (!pageRoot) throw new Error('hypercms: no pageRoot available')
-  const doc = pageRoot.ownerDocument || (typeof document !== 'undefined' ? document : null)
+  const doc = (pageRoot.nodeType === 9 ? pageRoot : pageRoot.ownerDocument) || (typeof document !== 'undefined' ? document : null)
   if (!doc) throw new Error('hypercms: no document available')
+  if (!admitted && !canWriteNow(doc.defaultView)) return { ok: false, code: 'not-allowed' }
+
+  // A bare open() means "make sure the editor is up", not "put it in the
+  // sidebar": with a session up it keeps that view, otherwise it opens the view
+  // the page declares.
+  const viewName = opts.view || (state.isOpen ? state.ctx.view.name : declaredView(doc, merged.rules))
+  const makeView = VIEWS[viewName]
+  if (!makeView) {
+    throw new Error(`hypercms: unknown view "${viewName}" (expected ${Object.keys(VIEWS).join(' or ')})`)
+  }
+  const effective = state.isOpen ? { ...merged, view: viewName } : opts
 
   // Reopening the view that is already up is a silent no-op, not a warning: a
   // host wiring a button to open({ view }) should be able to call it without
@@ -87,7 +121,7 @@ export function open(opts = {}) {
   let carriedFocus = null
   let previous = null
   if (state.isOpen) {
-    if (state.ctx.view.name === viewName) return
+    if (state.ctx.view.name === viewName) return { ok: true, view: viewName }
     carriedFocus = state.ctx.previouslyFocused
     previous = state.ctx.view.name
     teardownSession(state.ctx, { restoreFocus: false, updateUrl: false, reason: 'switch' })
@@ -101,8 +135,8 @@ export function open(opts = {}) {
     doc,
     pageRoot,
     opts: effective,
-    onCloseRequested: () => close(),
-    onViewRequested: (name) => open({ view: name }),
+    onCloseRequested: () => modeExit(doc) || close(),
+    onViewRequested: (name) => openSession({ view: name }, true),
   })
   // Where focus was before the FIRST open, carried across the switch. Closing
   // the second view should return the person where they started, not to
@@ -134,11 +168,19 @@ export function open(opts = {}) {
     teardownSession(ctx, { dispatch: false, restoreFocus: !!carriedFocus, updateUrl: false })
     throw err
   }
+  return { ok: true, view: viewName }
 }
 
 export function close() {
-  if (!state.isOpen) return
+  if (!state.isOpen) return { ok: false, code: 'no-session' }
+  const doc = state.ctx.doc
+  if (modeLifecycle(doc && doc.defaultView)) {
+    const pending = pendingWork(state.ctx)
+    if (pending.length) return { ok: false, code: 'pending-input', pending }
+    if (!canWriteNow(doc && doc.defaultView)) return { ok: false, code: 'busy' }
+  }
   teardownSession(state.ctx)
+  return { ok: true }
 }
 
 export function refresh() {
@@ -157,13 +199,58 @@ export function currentView() {
   return state.isOpen && state.ctx ? state.ctx.view.name : null
 }
 
+export function prepareModeLease({ doc, pageRoot, opts = {} } = {}) {
+  let owned = null
+  let disposed = false
+  return {
+    ready: Promise.resolve(),
+    enable() {
+      if (disposed) return
+      const target = { ...opts }
+      if (pageRoot) target.pageRoot = pageRoot
+      if (!target.pageRoot) target.pageRoot = (doc && doc.body) || doc || null
+      openSession(target, true)
+      owned = state.ctx
+    },
+    quiesce() {
+      if (disposed || !owned || state.ctx !== owned) return { ok: true }
+      return quiesceSession(owned)
+    },
+    resume() {
+      if (disposed || !owned || state.ctx !== owned) return
+      resumeSession(owned)
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      if (owned && state.ctx === owned) teardownSession(owned)
+      owned = null
+    },
+  }
+}
+
+export function modeParticipant(options = {}) {
+  return {
+    id: 'hypercms',
+    order: 1000,
+    prepare() {
+      return prepareModeLease(options)
+    },
+  }
+}
+
+function assertAdmitting() {
+  if (!state.isOpen) throw new Error('hypercms: cms is not open')
+  if (state.ctx.quiesced) throw new Error('hypercms: the CMS is not admitting new changes')
+}
+
 export const api = {
   getData() {
     if (!state.isOpen) return null
     return extractFormData(state.ctx)
   },
   setValue(path, value) {
-    if (!state.isOpen) throw new Error('hypercms: cms is not open')
+    assertAdmitting()
     const ctx = state.ctx
     const pathArr = pathUtil.fromString(path)
     const rule = pathUtil.getRuleAtPath(ctx.pageRules, pathArr)
@@ -177,11 +264,11 @@ export const api = {
     commit(extractFormData(ctx), { path, structural: false }, ctx)
   },
   addItem(arrayPath) {
-    if (!state.isOpen) throw new Error('hypercms: cms is not open')
+    assertAdmitting()
     evOnAdd(arrayPath, state.ctx)
   },
   removeItem(itemPath) {
-    if (!state.isOpen) throw new Error('hypercms: cms is not open')
+    assertAdmitting()
     const ctx = state.ctx
     const pathArr = pathUtil.fromString(itemPath)
     // Validate path: must be an array item — last segment is a non-negative
@@ -201,7 +288,7 @@ export const api = {
   },
   refresh,
   _commit() {
-    if (!state.isOpen) return
+    if (!state.isOpen || state.ctx.quiesced) return
     const ctx = state.ctx
     restampAllSiblings(ctx.formRoot)
     return commitWithUndo('Update', () =>
@@ -232,6 +319,7 @@ export function maybeAutoOpen() {
   if (state.isOpen) return
   whenReady(() => {
     if (state.isOpen) return
+    if (!canWriteNow()) return
     try {
       open()
     } catch (err) {
@@ -319,23 +407,15 @@ function whenReady(fn) {
 // window, and the guards above no-op there).
 maybeAutoOpen()
 
-// Floating edit-mode toggle at module load (same browser-only no-op in node).
-maybeInjectToggle({
-  open,
-  close,
-  isOpen,
-  getTheme: () => state.opts?.theme,
-  // The same map open() resolves a view name against, so the split button
-  // offers exactly the views this build can actually render.
-  views: Object.keys(VIEWS),
-  hasRules: (doc) => !!engine.findRules(doc, 'cms'),
-})
-
 const cms = {
   open,
   close,
   refresh,
   api,
+  // Whether this page declares CMS rules, so a launcher outside the CMS knows to offer it.
+  hasRules: (doc = document) => !!engine.findRules(doc, 'cms'),
+  prepareModeLease,
+  modeParticipant,
   get isOpen() { return state.isOpen },
   currentView,
   // Power-user exports (mostly for testing + advanced integration)

package/src/page-root.js

@@ -0,0 +1,28 @@
+// The CMS reads and writes the whole document, so a rule can bind <html> (the
+// page's theme properties) or the <head>. Everything that needs an element to
+// stand for the page (event payloads and dispatch, structural rollback, the
+// inline view's page listeners) keeps using <body>, where the content lives.
+export function contentRoot(pageRoot) {
+  if (pageRoot && pageRoot.nodeType === 9) return pageRoot.body || pageRoot.documentElement
+  return pageRoot
+}
+
+// A rule with no selector ("@data-mode", ".") addresses the page root itself.
+// A Document has no attributes or text of its own, so outside a list those
+// rules address <body>, which is what they addressed when <body> was the
+// default root. Inside a list the row is the context and nothing changes.
+export function rootRules(rules, pageRoot) {
+  if (!pageRoot || pageRoot.nodeType !== 9) return rules
+  return walk(rules)
+  function walk(rule) {
+    if (typeof rule === 'string') {
+      if (rule === '.') return 'body'
+      if (rule.startsWith('@')) return `body${rule}`
+      return rule
+    }
+    if (Array.isArray(rule) || !rule || typeof rule !== 'object') return rule
+    const out = {}
+    for (const [k, v] of Object.entries(rule)) out[k] = walk(v)
+    return out
+  }
+}

package/src/refresh.js

@@ -8,6 +8,8 @@ import { findUnresolved, applyUnresolvedState, stripReadOnly } from './unresolve
 import { enhanceFields } from './enhance.js'
 import { platform } from './platform.js'
 import { rowIdentitySeeder } from './row-identity.js'
+import { reconcileFontsLink } from './fonts-link.js'
+import { rootRules } from './page-root.js'
 
 const ENGINE_OPTS = { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }
 
@@ -27,7 +29,7 @@ function refreshPageForm(ctx, { ignoreActiveValue }) {
     // (session.js hands found.rules to view.prepareRules) rather than
     // hardcoding one view's upgrade here — that undid a wider upgrade on the
     // first refresh, silently flattening rich text back to plain.
-    ctx.pageRules = ctx.view.prepareRules(found.rules)
+    ctx.pageRules = ctx.view.prepareRules(rootRules(found.rules, ctx.pageRoot))
     ctx.rulesTagNode = found.tagNode
   }
   // Re-derive formRules so schema changes (rule shape, template overrides) flow through.
@@ -54,6 +56,7 @@ function refreshPageForm(ctx, { ignoreActiveValue }) {
     doc: ctx.doc,
   })
   morphForm(ctx.formRoot, fragment, { ignoreActiveValue })
+  reconcileFontsLink(ctx, newData)
   seeder.seed(ctx.formRoot)
   // The morph can rebuild field nodes, dropping autosize heights and richclay
   // instances (instances are per-element); re-enhance whatever is new.

package/src/session.js

@@ -10,6 +10,7 @@ import { deriveFormRules } from './form-rules.js'
 import { warnUnmatchedTemplates } from './diagnostics.js'
 import { findUnresolved, stripReadOnly } from './unresolved.js'
 import { rowIdentitySeeder } from './row-identity.js'
+import { contentRoot, rootRules } from './page-root.js'
 import {
   commit,
   commitWithUndo,
@@ -21,6 +22,7 @@ import {
 } from './events.js'
 import { installObserver } from './refresh.js'
 import { platform, onPlatformEvent, LIVESYNC_APPLIED } from './platform.js'
+import { reconcileFontsLink } from './fonts-link.js'
 
 const ENGINE_OPTS = { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }
 
@@ -48,7 +50,7 @@ export function createSession({ view, doc, pageRoot, opts = {}, onCloseRequested
   // bare scalar rules whose page element contains child elements are rebound
   // through @innerHTML so links and inline formatting survive the round-trip, and
   // their form fields render the @richtext component.
-  const pageRules = view.prepareRules(found.rules)
+  const pageRules = view.prepareRules(rootRules(found.rules, pageRoot))
   const rulesTagNode = found.tagNode
 
   injectDefaults(doc)
@@ -95,6 +97,7 @@ export function createSession({ view, doc, pageRoot, opts = {}, onCloseRequested
     onError: opts.onError,
     confirmRemove: opts.confirmRemove,
     previouslyFocused: doc.activeElement,
+    quiesced: false,
     dispatch(name, detail) {
       const Ctor = (doc.defaultView && doc.defaultView.CustomEvent) || (typeof CustomEvent !== 'undefined' ? CustomEvent : null)
       if (!Ctor) return
@@ -103,13 +106,13 @@ export function createSession({ view, doc, pageRoot, opts = {}, onCloseRequested
       // inline one without inspecting the DOM. Merged into the caller's detail
       // rather than replacing it: hcms:change still carries .data, hcms:error
       // still carries .error.
-      const payload = { ...(detail || {}), pageRoot, view: view.name }
+      const payload = { ...(detail || {}), pageRoot: contentRoot(pageRoot), view: view.name }
       const ev = new Ctor(name, { bubbles: true, cancelable: name === 'hcms:change', detail: payload })
       // A full-document morph (live sync, a version restore) can replace the
       // view root between mount and dispatch. Falling back to the page keeps the
       // event on the document instead of firing it into a detached tree where no
       // listener will ever see it.
-      const target = view.root && view.root.isConnected !== false ? view.root : pageRoot
+      const target = view.root && view.root.isConnected !== false ? view.root : contentRoot(pageRoot)
       target.dispatchEvent(ev)
     },
     onCloseRequested,
@@ -132,6 +135,10 @@ export function createSession({ view, doc, pageRoot, opts = {}, onCloseRequested
 export function startSession(ctx) {
   ctx.updateFingerprint()
 
+  // A font set outside the CMS (the JSON API, a hand edit) left the fonts link
+  // behind; opening the CMS brings it back in step.
+  reconcileFontsLink(ctx, coerceBooleans(engine.extract(ctx.pageRoot, ctx.pageRules, ENGINE_OPTS), ctx.pageRules))
+
   ctx.observerHandle = installObserver({
     onRefresh: (changes) => ctx.view.refresh('observer', changes),
   })
@@ -236,6 +243,47 @@ function clearState() {
   globalCommitTarget.ctx = null
 }
 
+export function modeLifecycle(win) {
+  const scope = win || (typeof window !== 'undefined' ? window : null)
+  const lifecycle = scope && scope.clay ? scope.clay.modeLifecycle : null
+  return lifecycle && typeof lifecycle.canWrite === 'function' ? lifecycle : null
+}
+
+export function canWriteNow(win) {
+  const lifecycle = modeLifecycle(win)
+  if (!lifecycle) return true
+  try {
+    return lifecycle.canWrite() !== false
+  } catch (_) {
+    return false
+  }
+}
+
+const UPLOADING_SELECTOR = '[data-hcms-uploading]'
+
+export function pendingWork(ctx) {
+  if (!ctx) return []
+  const pending = []
+  if (ctx.uploads && ctx.uploads.size > 0) pending.push('upload')
+  if (ctx.pageRoot && typeof ctx.pageRoot.querySelector === 'function' && ctx.pageRoot.querySelector(UPLOADING_SELECTOR)) {
+    pending.push('preview')
+  }
+  return pending
+}
+
+export function quiesceSession(ctx) {
+  if (!ctx || ctx.closed) return { ok: true }
+  const pending = pendingWork(ctx)
+  if (pending.length) return { ok: false, code: 'pending-input', pending }
+  ctx.quiesced = true
+  return { ok: true }
+}
+
+export function resumeSession(ctx) {
+  if (!ctx || ctx.closed) return
+  ctx.quiesced = false
+}
+
 const globalCommitTarget = { ctx: null }
 
 function installGlobalSortableCommit(doc) {

package/src/targets.js

@@ -10,6 +10,7 @@
 
 import { createDomAdapter } from 'hyper-html-api/dom'
 import { ruleAttrIndex } from 'hyper-html-api/engine'
+import { styleRole } from './templates.js'
 
 const FIND_OPTS = { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }
 // templateAttr:null includes the hidden [cms-template] seed. A list that has been
@@ -44,22 +45,21 @@ const NATIVE_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT'])
 const NON_TEXT_TAGS = new Set([
   'IMG', 'INPUT', 'TEXTAREA', 'SELECT', 'OPTION', 'BR', 'HR', 'VIDEO', 'AUDIO',
   'IFRAME', 'EMBED', 'OBJECT', 'CANVAS', 'SOURCE', 'TRACK', 'AREA', 'COL', 'PARAM',
-  'BUTTON',
+  'BUTTON', 'STYLE', 'SCRIPT', 'LINK', 'META',
 ])
 
-export function resolveTargets(root, rules) {
-  return resolvePageTargets(root, rules)
-}
-
-function resolvePageTargets(root, rules) {
+// `doc` lets each scalar target say whether it is a style field (`style`:
+// 'page', 'section' or null). Without it every target is content.
+export function resolveTargets(root, rules, doc = null) {
   const targets = []
   const lists = []
   const adapter = createDomAdapter(root)
-  walk(adapter, root, rules, [], targets, lists)
+  const roleOf = doc ? (rule, path) => styleRole(rule, doc, path, rules) : () => null
+  walk(adapter, root, rules, [], targets, lists, roleOf)
   return { targets, lists }
 }
 
-function walk(adapter, ctx, rule, path, targets, lists) {
+function walk(adapter, ctx, rule, path, targets, lists, roleOf) {
   if (typeof rule === 'string') {
     // A scalar array ("ul.tags li[]"): every match is its own editable item, and
     // the run of them is a list that can be added to and removed from.
@@ -79,7 +79,7 @@ function walk(adapter, ctx, rule, path, targets, lists) {
     // "." and a bare "@attr" both address the context node itself, so they can
     // never fail to resolve and there is nothing to query.
     const el = !selector || selector === '.' ? ctx : find(adapter, ctx, selector)[0]
-    if (el) targets.push(describe(path, el, rule, attr))
+    if (el) targets.push(describe(path, el, rule, attr, roleOf(rule, path)))
     return
   }
 
@@ -87,13 +87,13 @@ function walk(adapter, ctx, rule, path, targets, lists) {
     const [selector, shape] = rule
     if (typeof selector !== 'string' || !selector) return
     const items = find(adapter, ctx, selector)
-    items.forEach((el, i) => walk(adapter, el, shape, [...path, i], targets, lists))
+    items.forEach((el, i) => walk(adapter, el, shape, [...path, i], targets, lists, roleOf))
     lists.push(makeList(adapter, ctx, path, selector, items, typeof shape === 'string'))
     return
   }
 
   if (rule && typeof rule === 'object') {
-    for (const [key, sub] of Object.entries(rule)) walk(adapter, ctx, sub, [...path, key], targets, lists)
+    for (const [key, sub] of Object.entries(rule)) walk(adapter, ctx, sub, [...path, key], targets, lists, roleOf)
   }
 }
 
@@ -109,8 +109,8 @@ function makeList(adapter, ctx, path, selector, items, scalar) {
   return { path, items, container, scalar }
 }
 
-function describe(path, el, rule, attr) {
-  return { path, el, rule, attr, kind: kindOf(el, attr), icon: iconOf(el, attr) }
+function describe(path, el, rule, attr, style = null) {
+  return { path, el, rule, attr, kind: kindOf(el, attr), icon: iconOf(el, attr), style }
 }
 
 function kindOf(el, attr) {
@@ -147,3 +147,45 @@ function find(adapter, ctx, selector, opts = FIND_OPTS) {
     return []
   }
 }
+
+// Style fields grouped by what they style: every page-level one together, the
+// ones inside a list row with that row, any other with the element it sits on.
+export function styleGroups(targets, lists) {
+  const groups = []
+  const byEl = new Map()
+  let page = null
+  for (const target of targets) {
+    if (!target.style) continue
+    const path = target.path.join('.')
+    if (target.style === 'page') {
+      if (!page) {
+        page = { scope: 'page', el: target.el, list: null, paths: [] }
+        groups.push(page)
+      }
+      page.paths.push(path)
+      continue
+    }
+    const owner = rowOf(target.path, lists)
+    const el = owner ? owner.row : target.el
+    let group = byEl.get(el)
+    if (!group) {
+      group = { scope: owner ? 'row' : 'section', el, list: owner ? owner.list : null, paths: [] }
+      byEl.set(el, group)
+      groups.push(group)
+    }
+    group.paths.push(path)
+  }
+  return groups
+}
+
+// The innermost list row a target path runs through, as { list, row }.
+function rowOf(path, lists) {
+  for (let i = path.length - 1; i >= 0; i--) {
+    if (typeof path[i] !== 'number') continue
+    const prefix = path.slice(0, i).join('.')
+    const list = lists.find((candidate) => candidate.path.join('.') === prefix)
+    const row = list && list.items[path[i]]
+    if (row) return { list, row }
+  }
+  return null
+}