hyper-html-api 0.10.0 → 0.11.0

package/src/engine/splice.js

@@ -54,6 +54,20 @@ export function trackAdapter(adapter) {
       if (from) mark(from)
       return adapter.insertAt(parent, node, index)
     },
+    insertBefore(ref, node) {
+      const p = adapter.parent(ref)
+      if (p) mark(p)
+      const from = adapter.parent(node)
+      if (from) mark(from)
+      return adapter.insertBefore(ref, node)
+    },
+    insertAfter(ref, node) {
+      const p = adapter.parent(ref)
+      if (p) mark(p)
+      const from = adapter.parent(node)
+      if (from) mark(from)
+      return adapter.insertAfter(ref, node)
+    },
     remove(node) {
       const p = adapter.parent(node)
       if (p) mark(p)

package/src/engine/write-policy.js

@@ -105,6 +105,9 @@ export function guardAdapter(adapter, policy = WRITE_POLICY) {
       if (value === undefined) return adapter.attr(node, name)
       if (allowAttr(node, name, value)) adapter.attr(node, name, value)
     },
+    removeAttr(node, name) {
+      if (allowAttr(node, name, null)) adapter.removeAttr(node, name)
+    },
     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/lib/content-dom.js

@@ -1,6 +1,6 @@
 // GENERATED from clayjs/src/lib/content-dom.js. Edit ClayJS and run `npm run propagate:foundation`.
 
-import { capabilitySelector, hasCapability } from './region-capabilities.js'
+import { capabilitySelector, hasCapability, CAPABILITIES, expandsTo, hasPolicyToken } from './region-capabilities.js'
 
 const UNSUPPORTED_SELECTOR = /:(?:focus(?:-within|-visible)?|hover|active|visited|defined)\b/i
 
@@ -9,10 +9,9 @@ function copyControlState(source, copy) {
   const type = (source.getAttribute?.('type') || '').toLowerCase()
   if ('value' in source && 'value' in copy && source.tagName !== 'OPTION' && type !== 'checkbox' && type !== 'radio' && type !== 'file') copy.value = source.value
   if (source.tagName === 'INPUT' && (type === 'checkbox' || type === 'radio')) copy.checked = source.checked
+  // Each surviving option carries its own selection, so a <select> whose excluded
+  // options were removed from the copy keeps the rest in step with the page.
   if (source.tagName === 'OPTION') copy.selected = source.selected
-  if (source.tagName === 'SELECT') {
-    for (let i = 0; i < source.options.length; i++) copy.options[i].selected = source.options[i].selected
-  }
   if ('indeterminate' in source && 'indeterminate' in copy) copy.indeterminate = source.indeterminate
 }
 
@@ -27,46 +26,77 @@ function matchesWithin(node, selector, boundary, inherit) {
   return false
 }
 
-function importTree(source, targetDocument, capability, capabilityMatch, exclude, boundary, inherit, maps) {
-  if (source.nodeType === 1 && (
-    (inherit
-      ? hasCapability(source, capability)
-      : matchesWithin(source, capabilityMatch, boundary, false)) ||
-    (exclude && (inherit && source !== boundary ? source.matches(exclude) : matchesWithin(source, exclude, boundary, inherit)))
-  )) return null
-  const copy = targetDocument.importNode(source, false)
+// One native deep clone, then a lockstep walk of the two isomorphic trees that
+// records provenance, collects controls, and marks excluded subtrees for removal.
+// The browser's clone is far cheaper than importing node by node. The root answers
+// for its ancestors once; below it the walk is top-down, so with inheritance each
+// element answers only for its own markers: an excluded ancestor is never entered.
+function excluded(source, capability, capabilityMatch, exclude, boundary, inherit) {
+  return (inherit
+    ? hasCapability(source, capability)
+    : matchesWithin(source, capabilityMatch, boundary, false)) ||
+    !!(exclude && (inherit && source !== boundary ? source.matches(exclude) : matchesWithin(source, exclude, boundary, inherit)))
+}
+
+// The test closestWithCapability makes at each level, for this element alone.
+function hasOwnCapability(element, capability) {
+  const definition = CAPABILITIES[capability]
+  return definition.tokens.some(token => expandsTo(element, token)) ||
+    definition.bundles.some(bundle => hasPolicyToken(element, bundle))
+}
+
+const CONTROL_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT', 'OPTION'])
+
+function pairTree(source, copy, maps, drop) {
+  if (source.nodeType === 1 && drop(source)) { maps.dropped.push(copy); return }
   maps.cloneToLive.set(copy, source)
   maps.liveToClone.set(source, copy)
-  const sourceChildren = source.nodeType === 1 && source.tagName === 'TEMPLATE' ? source.content : source
-  const copyChildren = copy.nodeType === 1 && copy.tagName === 'TEMPLATE' ? copy.content : copy
-  if (sourceChildren !== source) {
-    maps.cloneToLive.set(copyChildren, sourceChildren)
-    maps.liveToClone.set(sourceChildren, copyChildren)
-  }
-  for (const child of sourceChildren.childNodes || []) {
-    const childCopy = importTree(child, targetDocument, capability, capabilityMatch, exclude, boundary, inherit, maps)
-    if (childCopy) {
-      copyChildren.appendChild(childCopy)
-      if (child.nodeType === 1) copyControlState(child, childCopy)
+  let sourceChildren = source
+  let copyChildren = copy
+  if (source.nodeType === 1) {
+    if (CONTROL_TAGS.has(source.tagName)) maps.controls.push(source, copy)
+    if (source.tagName === 'TEMPLATE') {
+      // The deep clone also copied the template's own child nodes, which are not its
+      // content and were never part of the view.
+      while (copy.firstChild) copy.removeChild(copy.firstChild)
+      sourceChildren = source.content
+      copyChildren = copy.content
+      maps.cloneToLive.set(copyChildren, sourceChildren)
+      maps.liveToClone.set(sourceChildren, copyChildren)
     }
+  } else if (source.nodeType !== 11) return
+  let c = copyChildren.firstChild
+  for (let s = sourceChildren.firstChild; s && c; s = s.nextSibling) {
+    pairTree(s, c, maps, drop)
+    c = c.nextSibling
   }
-  if (source.nodeType === 1) copyControlState(source, copy)
-  return copy
 }
 
-export function createContentView(context, { capability = 'data', exclude = null, inherit = true } = {}) {
+export function createContentView(context, { capability = 'data', exclude = null, inherit = true, provenance = null } = {}) {
   if (!context) throw new TypeError('createContentView requires a DOM context')
   const sourceDocument = context.nodeType === 9 ? context : context.ownerDocument
   if (!sourceDocument?.implementation?.createHTMLDocument) {
     throw new TypeError('createContentView requires an HTML DOM implementation')
   }
   const inertDocument = sourceDocument.implementation.createHTMLDocument('')
-  const cloneToLive = new WeakMap()
+  const cloneToLive = provenance || new WeakMap()
   const liveToClone = new WeakMap()
   const sourceRoot = context.nodeType === 9 ? context.documentElement : context
   if (exclude) inertDocument.documentElement.matches(exclude)
   const capabilityMatch = capabilitySelector(capability)
-  const root = importTree(sourceRoot, inertDocument, capability, capabilityMatch, exclude, sourceRoot, inherit, { cloneToLive, liveToClone })
+  const drop = inherit
+    ? (el) => hasOwnCapability(el, capability) || !!(exclude && el.matches(exclude))
+    : (el) => excluded(el, capability, capabilityMatch, exclude, sourceRoot, false)
+  let root = null
+  if (sourceRoot.nodeType !== 1 || !excluded(sourceRoot, capability, capabilityMatch, exclude, sourceRoot, inherit)) {
+    root = inertDocument.importNode(sourceRoot, true)
+    const maps = { cloneToLive, liveToClone, dropped: [], controls: [] }
+    pairTree(sourceRoot, root, maps, drop)
+    for (const node of maps.dropped) node.remove()
+    // Control state is copied once the copy holds only what the view keeps, so a
+    // <select> sees exactly the options the old node-by-node import gave it.
+    for (let i = 0; i < maps.controls.length; i += 2) copyControlState(maps.controls[i], maps.controls[i + 1])
+  }
   if (context.nodeType === 9 && root) {
     inertDocument.replaceChild(root, inertDocument.documentElement)
     liveToClone.set(context, inertDocument)

package/src/lib/region-capabilities.js

@@ -23,6 +23,7 @@ export const POLICY_TOKENS = Object.freeze([
   'no-data',
   'freeze',
   'editor-ui',
+  'live',
 ])
 
 export function hasPolicyToken(element, token) {

package/src/write.js

@@ -1,8 +1,10 @@
 import cheerioAdapter from './adapters/cheerio.js'
 import { apply } from './engine/apply.js'
+import { extract } from './engine/extract.js'
 import { findRulesIn } from './engine/rules-tag.js'
 import { guardAdapter } from './engine/write-policy.js'
 import { planWrite } from './engine/write-plan.js'
+import { assertRoundTrip } from './engine/round-trip.js'
 import { trackAdapter, spliceDocument } from './engine/splice.js'
 import { NoRulesTag, RulesParseError, WriteRejected } from './engine/errors.js'
 
@@ -10,8 +12,8 @@ import { NoRulesTag, RulesParseError, WriteRejected } from './engine/errors.js'
 // (options.rules) or the document's own rules tag, under the content-only
 // policy. `load` is cheerio.load, passed in so this package keeps cheerio out
 // of its browser bundles. Returns the new source and whether anything changed.
-// Throws NoRulesTag, RulesParseError, WriteRejected, WriteRefused, ShapeMismatch
-// or EmptyListInsert, always before producing any output.
+// Throws NoRulesTag, RulesParseError, WriteRejected, WriteRefused, ShapeMismatch,
+// EmptyListInsert or WriteNotRoundTripped, always before producing any output.
 export function writeDocument(load, src, data, options = {}) {
   const { token = 'api' } = options
   const $ = load(src, { sourceCodeLocationInfo: true })
@@ -29,11 +31,41 @@ export function writeDocument(load, src, data, options = {}) {
   }
   const plan = planWrite(cheerioAdapter, root, rules, data)
   if (plan.unknownKeys.length || plan.unmatched.length) throw new WriteRejected(plan.unknownKeys, plan.unmatched)
+  const opts = { templateAttr: 'cms-template' }
   const tracker = trackAdapter(cheerioAdapter)
   const guarded = guardAdapter(tracker)
-  apply(guarded, root, rules, data, { templateAttr: 'cms-template' })
+  apply(guarded, root, rules, data, opts)
   guarded.assertClean()
-  if (tracker.dirty.size === 0) return { html: src, changed: false, spliced: true }
-  const { html, spliced } = spliceDocument(load, src, $, tracker)
+  const { html, spliced } = tracker.dirty.size === 0
+    ? { html: src, spliced: true }
+    : spliceDocument(load, src, $, tracker)
+  // The in-memory tree is not the contract: only the source the caller gets
+  // back is. Re-parse it and compare the caller's projection, so a write that
+  // serialization dropped throws instead of returning a false success. Only the
+  // rules the payload names are re-extracted: a one-field write on a large page
+  // 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), {
+    adapter: cheerioAdapter,
+    root: writtenRoot,
+    opts,
+  })
   return { html, changed: html !== src, spliced }
 }
+
+// The top-level subset of `rules` that the payload names, which is exactly what
+// the guard checks: an omitted rule is not part of this write and must not be
+// able to fail it. A scalar or list rule already IS the whole projection.
+function writtenRules(rules, data) {
+  if (!isPlainObject(rules) || !isPlainObject(data)) return rules
+  const subset = {}
+  for (const key of Object.keys(data)) {
+    if (Object.prototype.hasOwnProperty.call(rules, key)) subset[key] = rules[key]
+  }
+  return subset
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}