hyper-html-api 0.12.0 → 0.14.0

package/src/engine/write-policy.js

@@ -1,5 +1,6 @@
 import { POLICY_TOKENS } from '../lib/region-capabilities.js'
 import { WriteRefused } from './errors.js'
+import { isCustomPropertyName, readStyleVar, setStyleVar } from './style-vars.js'
 
 export const WRITE_POLICY = Object.freeze({
   refusedRuleForms: ['innerHTML', 'outerHTML'],
@@ -12,6 +13,11 @@ export const WRITE_POLICY = Object.freeze({
   refusedAttributePrefixes: ['on'],
   urlAttributes: ['href', 'src', 'srcset', 'action', 'formaction', 'poster', 'cite', 'data', 'ping', 'background', 'longdesc', 'usemap', 'xlink:href', 'manifest', 'codebase', 'icon'],
   refusedSchemes: ['javascript', 'vbscript', 'data'],
+  customPropertyValues: Object.freeze({
+    maxLength: 200,
+    refusedCharacters: [';', '{', '}', '<', '>', '\\'],
+    refusedFunctions: ['url', 'src', 'image', 'image-set', '-webkit-image-set', 'cross-fade', 'element', 'expression', 'paint'],
+  }),
 })
 
 const TEXT_PROPS = new Set(['textContent', 'innerText'])
@@ -71,6 +77,48 @@ function isOrHoldsRulesTag(adapter, node) {
   return holdsRulesTag(adapter, node)
 }
 
+// Every quote closed, every bracket closed by its own kind, no comment and no
+// control character. A value that fails this would swallow the declarations
+// after it in the style attribute.
+function unbalancedReason(text) {
+  if (/[\u0000-\u001f\u007f]/.test(text)) return 'control characters are not allowed in a custom property value'
+  const stack = []
+  let quote = null
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]
+    if (quote) {
+      if (c === quote) quote = null
+      continue
+    }
+    if (c === '"' || c === "'") quote = c
+    else if (c === '/' && text[i + 1] === '*') return 'comments are not allowed in a custom property value'
+    else if (c === '(') stack.push(')')
+    else if (c === '[') stack.push(']')
+    else if (c === ')' || c === ']') {
+      if (stack.pop() !== c) return `"${c}" does not close anything in this custom property value`
+    }
+  }
+  if (quote) return 'a custom property value must close its quotes'
+  if (stack.length) return 'a custom property value must close its brackets'
+  return null
+}
+
+// A custom property value that cannot load anything, close its declaration, or
+// carry markup. Colors, font stacks, lengths and keywords all pass.
+export function checkCustomPropertyValue(value, policy = WRITE_POLICY) {
+  const rules = policy.customPropertyValues
+  const text = String(value)
+  if (text.length > rules.maxLength) return `custom property values are limited to ${rules.maxLength} characters`
+  const ch = rules.refusedCharacters.find((c) => text.includes(c))
+  if (ch) return `${JSON.stringify(ch)} is not allowed in a custom property value`
+  const unbalanced = unbalancedReason(text)
+  if (unbalanced) return unbalanced
+  const lower = text.toLowerCase()
+  const fn = rules.refusedFunctions.find((f) => new RegExp(`(^|[^a-z0-9_-])${f.replace(/[-]/g, '\\-')}\\s*\\(`).test(lower))
+  if (fn) return `"${fn}()" is not allowed in a custom property value`
+  return null
+}
+
 // Wraps an adapter so every write is checked against the policy first. A write
 // that breaks it is skipped and recorded; call assertClean() after apply() to
 // throw one WriteRefused listing every violation.
@@ -108,6 +156,18 @@ export function guardAdapter(adapter, policy = WRITE_POLICY) {
     removeAttr(node, name) {
       if (allowAttr(node, name, null)) adapter.removeAttr(node, name)
     },
+    // The engine's @--name write: one custom property, checked by name and
+    // value. Every other declaration in the attribute is left as it is.
+    styleVar(node, name, value) {
+      if ((readStyleVar(adapter.attr(node, 'style'), name) ?? '') === value) return
+      if (!allowTarget(node)) return
+      if (!isCustomPropertyName(name)) return refuse(node, `"${name}" is not a custom property`)
+      if (value !== '') {
+        const reason = checkCustomPropertyValue(value, policy)
+        if (reason) return refuse(node, reason)
+      }
+      setStyleVar(adapter, node, name, value)
+    },
     prop(node, name, value) {
       if (value === undefined) return adapter.prop(node, name)
       if (policy.refusedRuleForms.includes(name)) return refuse(node, `"@${name}" writes HTML, only text is allowed`)

package/src/page.js

@@ -5,7 +5,7 @@ import { NoRulesTag, RulesParseError } from './engine/errors.js'
 import { parseRelaxed } from './engine/rules.js'
 import { writeDocument } from './write.js'
 
-const PAGE = /^page(?:\.[0-9]+)?$/
+const PAGE = /^blockeditor(?:\.[0-9]+)?$/
 const TEXT = new Set(['paragraph', 'heading', 'list_item', 'callout', 'code_block', 'toggle'])
 const MARKS = ['b', 'i', 's', 'c', 'a']
 
@@ -21,10 +21,19 @@ function refuse(message) {
   throw new PageWriteRefused('invalid-content', message)
 }
 
+// Inert content (a starter article kept in a <template>) is not part of the page, as in a browser.
+// Cheerio parents a template's content under a root node, which closest() does not climb past.
+function live(_, node) {
+  for (let up = node.parent; up; up = up.parent) {
+    if (up.type === 'tag' && (up.name === 'template' || up.name === 'noscript')) return false
+  }
+  return true
+}
+
 function pageNodes($) {
-  const tags = $('script[merge][clay~="live"]').filter((_, node) => PAGE.test($(node).attr('merge')))
+  const tags = $('script[merge][clay~="live"]').filter((_, node) => PAGE.test($(node).attr('merge'))).filter(live)
   if (!tags.length) return null
-  const articles = $('article[data-page]')
+  const articles = $('article[data-blockeditor]').filter(live)
   if (tags.length !== 1 || articles.length !== 1) refuse('Expected one page store and one page article')
   return { tag: tags[0], article: articles[0] }
 }
@@ -316,8 +325,9 @@ export async function writePageDocument(load, html, data, options = {}) {
   const next$ = load(candidate.html, { sourceCodeLocationInfo: true })
   const nextNodes = pageNodes(next$)
   const aligned$ = load(aligned)
-  const changes = pageChanges(next$, nextNodes.article, aligned$, aligned$('article[data-page]')[0], page.blocks, before.model, projection)
-  const unchangedAttrs = canon(next$(nextNodes.article).attr()) === canon(aligned$('article[data-page]').attr())
+  const alignedArticle = pageNodes(aligned$).article
+  const changes = pageChanges(next$, nextNodes.article, aligned$, alignedArticle, page.blocks, before.model, projection)
+  const unchangedAttrs = canon(next$(nextNodes.article).attr()) === canon(aligned$(alignedArticle).attr())
   const proposed = projectionOf(load, proposedBlocks(page.blocks, changes), projection)
   if (!unchangedAttrs || !sameArticle(next$, nextNodes.article, proposed)) {
     refuse('The article edit cannot be represented in the page store')

package/src/site.js

@@ -0,0 +1,164 @@
+import cheerioAdapter from './adapters/cheerio.js'
+import { extract } from './engine/extract.js'
+import { findRulesIn } from './engine/rules-tag.js'
+import { splitRule } from './engine/rule-syntax.js'
+import { writeDocument } from './write.js'
+
+export const SITE_KEY = 'site'
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+// The part of `value` that `rule` declares. Keys the rule does not name are
+// dropped at every level, because the writer refuses unknown keys and a store
+// holds keys other pages use. A key the store does not hold stays absent, and
+// the writer skips an absent key, so the page keeps what it has.
+export function projectSite(rule, value) {
+  if (isPlainObject(rule)) {
+    if (!isPlainObject(value)) return value
+    const out = {}
+    for (const key of Object.keys(rule)) {
+      if (value[key] !== undefined) out[key] = projectSite(rule[key], value[key])
+    }
+    return out
+  }
+  if (Array.isArray(rule) && Array.isArray(value)) {
+    return value.map((item) => projectSite(rule[1], item))
+  }
+  return value
+}
+
+// Writes the store's values into a page through the page's own `site` rule.
+// Never throws for a page problem: a key that cannot be written is listed in
+// `failed` and the other keys still land. `declared` is false when the page has
+// no rules tag or no `site` object in it, and then `html` is `src`.
+export function writeSite(load, src, store, options = {}) {
+  const { token = 'api' } = options
+  const none = { html: src, changed: false, declared: false, applied: [], failed: [] }
+  if (!isPlainObject(store)) return none
+  let found
+  try {
+    found = findRulesIn(cheerioAdapter, load(src).root(), token)
+  } catch (error) {
+    return { ...none, declared: true, failed: [{ key: null, code: error.name, message: error.message }] }
+  }
+  if (!found || !isPlainObject(found.rules) || !isPlainObject(found.rules[SITE_KEY])) return none
+  const data = projectSite(found.rules[SITE_KEY], store)
+  const keys = Object.keys(data)
+  if (keys.length === 0) return { ...none, declared: true }
+  const write = (html, part) => writeDocument(load, html, { [SITE_KEY]: part }, { token, rules: found.rules }).html
+  try {
+    const html = write(src, data)
+    return { html, changed: html !== src, declared: true, applied: keys, failed: [] }
+  } catch {
+    // One key failed. Write them one at a time so the rest still land.
+  }
+  let html = src
+  const applied = []
+  const failed = []
+  for (const key of keys) {
+    try {
+      html = write(html, { [key]: data[key] })
+      applied.push(key)
+    } catch (error) {
+      failed.push({ key, code: error.name, message: error.message })
+    }
+  }
+  return { html, changed: html !== src, declared: true, applied, failed }
+}
+
+// The same rule with each attribute read turned into a read of its element's text, which is
+// null exactly where the element is missing: a missing element can then be told apart from
+// an element without the attribute, which both read as a null attribute.
+function presenceRule(rule) {
+  if (typeof rule === 'string') {
+    const { selector, prop } = splitRule(rule)
+    return prop && !prop.endsWith('[]') ? (selector || '.') : rule
+  }
+  if (Array.isArray(rule)) return rule.length < 2 ? rule : [rule[0], presenceRule(rule[1])]
+  if (isPlainObject(rule)) return Object.fromEntries(Object.entries(rule).map(([key, value]) => [key, presenceRule(value)]))
+  return rule
+}
+
+// The page's own `site` rule and the values the page holds for it right now, read key by
+// key: a key whose rule cannot be read (a broken selector) is listed in `broken` and left
+// out of `data`, and the other keys still read. `present` mirrors `data` for
+// siteValueProblem. Never throws: a page with no rules tag, or no `site` key, declares nothing.
+export function readSite(load, src, options = {}) {
+  const { token = 'api' } = options
+  const none = { declared: false, rule: null, data: {}, present: {}, broken: [] }
+  let root
+  let found
+  try {
+    root = load(src).root()
+    found = findRulesIn(cheerioAdapter, root, token)
+  } catch {
+    return none
+  }
+  if (!found || !isPlainObject(found.rules) || !isPlainObject(found.rules[SITE_KEY])) return none
+  const rule = found.rules[SITE_KEY]
+  const read = (keyRule, key) => extract(cheerioAdapter, root, { [key]: keyRule }, { templateAttr: 'cms-template' })[key]
+  const data = {}
+  const present = {}
+  const broken = []
+  for (const key of Object.keys(rule)) {
+    try {
+      data[key] = read(rule[key], key)
+      present[key] = read(presenceRule(rule[key]), key)
+    } catch {
+      delete data[key]
+      broken.push(key)
+    }
+  }
+  return { declared: true, rule, data, present, broken }
+}
+
+// Why a value read from a page must not be written to the store, or null when it may.
+// A text rule that matched no element reads null, and an emptied list cannot be regrown
+// by writeSite, so both would damage every other page. A null attribute is a real value:
+// it means the attribute is absent, unless `present` (readSite's mirror of the value) shows
+// that the attribute's element is missing too.
+export function siteValueProblem(rule, value, present) {
+  if (typeof rule === 'string') {
+    if (rule.endsWith('[]')) {
+      if (!Array.isArray(value)) return 'unreadable'
+      return value.length === 0 ? 'empty-list' : null
+    }
+    if (value !== null) return null
+    return splitRule(rule).prop === null || present === null ? 'unreadable' : null
+  }
+  if (Array.isArray(rule)) {
+    if (!Array.isArray(value)) return 'unreadable'
+    if (value.length === 0) return 'empty-list'
+    if (rule.length < 2) return null
+    for (const [index, row] of value.entries()) {
+      const problem = siteValueProblem(rule[1], row, Array.isArray(present) ? present[index] : undefined)
+      if (problem) return problem
+    }
+    return null
+  }
+  if (isPlainObject(rule)) {
+    if (!isPlainObject(value)) return 'unreadable'
+    for (const key of Object.keys(rule)) {
+      const problem = siteValueProblem(rule[key], value[key], isPlainObject(present) ? present[key] : undefined)
+      if (problem) return problem
+    }
+    return null
+  }
+  return 'unreadable'
+}
+
+// The store's next value for one key after a page edit. An object keeps the fields the
+// page's rule does not name, because other pages use them. A list is taken whole from
+// the page: rows have no identity to merge by.
+export function mergeSiteEdit(rule, stored, edited) {
+  if (isPlainObject(rule) && isPlainObject(edited)) {
+    const out = isPlainObject(stored) ? { ...stored } : {}
+    for (const key of Object.keys(rule)) {
+      if (edited[key] !== undefined) out[key] = mergeSiteEdit(rule[key], out[key], edited[key])
+    }
+    return out
+  }
+  return edited
+}

package/src/upgrade/migrate.js

@@ -21,7 +21,8 @@ export function migrateInto(adapter, root, dataByName) {
       continue
     }
     const { data, summary } = shapeMatch(dataByName[name], rules)
-    apply(adapter, root, rules, data)
+    // A row whose nested list is empty at that spot in v2 grows from the page's seeds, as a write does.
+    apply(adapter, root, rules, data, { templateAttr: 'cms-template' })
     byName[name] = summary
     totals.carriedOver += summary.carriedOver
     totals.discarded += summary.discarded

package/src/upgrade/run.js

@@ -72,7 +72,37 @@ export async function run({ sourceUrl, dataByName, fromVersion, doc, loc, fetchF
   }
 }
 
+// The engine writes form values as properties, which serialization never sees. The
+// parsed copy has had no other input, so every property that differs from its
+// attribute came from the data and goes into the markup.
+function materializeFormState(doc) {
+  for (const input of doc.querySelectorAll('input')) {
+    const type = (input.getAttribute('type') || '').toLowerCase()
+    if (type === 'file') continue
+    if (type === 'checkbox' || type === 'radio') {
+      if (input.checked !== input.hasAttribute('checked')) input.toggleAttribute('checked', input.checked)
+    } else if (input.value !== (input.getAttribute('value') ?? '')) {
+      input.setAttribute('value', input.value)
+    }
+  }
+  for (const area of doc.querySelectorAll('textarea')) {
+    if (area.value !== area.textContent) area.textContent = area.value
+  }
+  for (const select of doc.querySelectorAll('select')) {
+    const options = [...select.options]
+    if (!select.multiple) {
+      const marked = options.findIndex((option) => option.hasAttribute('selected'))
+      // An unmarked select shows its first option without saying so.
+      if (select.selectedIndex === marked || (marked === -1 && select.selectedIndex <= 0)) continue
+    }
+    for (const option of options) {
+      if (option.selected !== option.hasAttribute('selected')) option.toggleAttribute('selected', option.selected)
+    }
+  }
+}
+
 function serializeDocument(doc) {
+  materializeFormState(doc)
   const name = doc.doctype && doc.doctype.name ? doc.doctype.name : 'html'
   return `<!DOCTYPE ${name}>\n` + doc.documentElement.outerHTML
 }

package/src/upgrade/shape-match.js

@@ -1,14 +1,29 @@
+import { DOM_PROPERTIES_READ_ONLY_SET } from '../engine/dom-properties.js'
+import { ruleAttrIndex } from '../engine/rule-syntax.js'
+
 /**
  * Walk v2Rules pulling matching values from v1Data.
  *
+ * Outside a list, what v1 has no value for keeps v2's template default:
+ *
  *   - Scalar leaves: carry the v1 value if defined, else leave undefined so
  *     the engine keeps v2's template default on apply.
- *   - Object arrays ([sel, shape]): carry v1's items, trimmed to v1's count;
- *     each item shape-matches recursively. Fields v2 added that didn't exist
- *     in v1 are left undefined → template default.
- *   - Scalar arrays (`sel[]`): carry as-is.
+ *   - Lists: carry v1's items, trimmed to v1's count; a list v1 never had
+ *     keeps v2's rows.
  *   - Objects: recurse per key.
  *
+ * Inside a list item nothing keeps a default. A row is the owner's own. It is
+ * written over a v2 sample row, or over a clone of one, so a field left
+ * undefined would take that sample's value (its label, its cover, its done
+ * mark, its id). So in a row:
+ *
+ *   - A field v1 read as null, a field v1 never had (v2 added it), and a
+ *     scalar field where v1 holds an object are all carried as null, and the
+ *     write clears them.
+ *   - A list v1 never had is carried as an empty list.
+ *   - A property nothing can write (tagName, childElementCount) stays
+ *     undefined, because writing null to it refuses the whole write.
+ *
  * Returns { data, summary } where summary counts scalar leaves carried,
  * dropped, and total list items preserved.
  */
@@ -19,31 +34,30 @@ export function shapeMatch(v1Data, v2Rules) {
   return { data, summary }
 }
 
-function walk(rule, v1, summary) {
+function walk(rule, v1, summary, inRow = false) {
   if (typeof rule === 'string') {
     if (rule.endsWith('[]')) {
-      if (!Array.isArray(v1)) return undefined
+      if (!Array.isArray(v1)) return inRow ? [] : undefined
       summary.listItems += v1.length
       summary.carriedOver += v1.length
       return v1
     }
-    if (v1 === undefined || v1 === null) return undefined
-    // A scalar slot can't hold an object/array from v1; leave the template
-    // default (collectDiscards counts the dropped leaves).
-    if (typeof v1 === 'object') return undefined
+    // A scalar slot can't hold an object/array from v1 (collectDiscards counts
+    // the dropped leaves), so it is treated as a slot v1 has no value for.
+    if (v1 == null || typeof v1 === 'object') return inRow && !readOnly(rule) ? null : undefined
     summary.carriedOver++
     return v1
   }
   if (Array.isArray(rule)) {
     const [, shape] = rule
-    if (!Array.isArray(v1)) return undefined
+    if (!Array.isArray(v1)) return inRow ? [] : undefined
     summary.listItems += v1.length
-    return v1.map((item) => walk(shape, item, summary))
+    return v1.map((item) => walk(shape, item, summary, true))
   }
   if (typeof rule === 'object' && rule !== null) {
     const out = {}
     for (const [k, sub] of Object.entries(rule)) {
-      const v = walk(sub, v1 == null ? undefined : v1[k], summary)
+      const v = walk(sub, v1 == null ? undefined : v1[k], summary, inRow)
       if (v !== undefined) out[k] = v
     }
     return out
@@ -51,6 +65,11 @@ function walk(rule, v1, summary) {
   return undefined
 }
 
+function readOnly(rule) {
+  const at = ruleAttrIndex(rule)
+  return at !== -1 && DOM_PROPERTIES_READ_ONLY_SET.has(rule.slice(at + 1))
+}
+
 function collectDiscards(rule, v1, summary) {
   if (v1 == null) return
   if (typeof rule === 'object' && rule !== null && !Array.isArray(rule)) {

package/src/write.js

@@ -46,7 +46,7 @@ export function writeDocument(load, src, data, options = {}) {
   // pays for the field it wrote, not for every rule in the document.
   const written = writtenRules(rules, data)
   const writtenRoot = load(html).root()
-  assertRoundTrip(written, data, extract(cheerioAdapter, writtenRoot, written, opts))
+  assertRoundTrip(written, data, extract(cheerioAdapter, writtenRoot, written, { ...opts, allMatches: true }))
   return { html, changed: html !== src, spliced }
 }