@panphora/hyper-cms 0.4.0

package/src/hypercms.js

@@ -0,0 +1,321 @@
+import { engine } from 'hyper-html-api'
+import * as pathUtil from './path.js'
+import { scaffold } from './scaffold.js'
+import { morphForm } from './morph.js'
+import { injectDefaults } from './templates.js'
+import { deriveFormRules } from './form-rules.js'
+import { buildForm } from './form-builder.js'
+import {
+  bindEvents,
+  commit,
+  commitWithUndo,
+  suppressUndo,
+  onAdd as evOnAdd,
+  onRemove as evOnRemove,
+  extractFormData,
+  stableStringify,
+  restampAllSiblings,
+  coerceBooleans,
+} from './events.js'
+import { mountShell, setShellStyles, markStylesBundled } from './shell.js'
+import { refreshForm, installObserver } from './refresh.js'
+import { warnUnmatchedTemplates } from './diagnostics.js'
+
+export function installStyles(text) {
+  setShellStyles(text)
+}
+
+export function markBundledStyles(doc) {
+  markStylesBundled(doc)
+}
+
+const state = {
+  isOpen: false,
+  ctx: null,
+  shell: null,
+  opts: null,
+}
+
+export function open(opts = {}) {
+  if (state.isOpen) {
+    console.warn('cms.open() called while already open; ignoring')
+    return
+  }
+  const pageRoot = opts.pageRoot || (typeof document !== 'undefined' ? document.body : null)
+  if (!pageRoot) throw new Error('hypercms: no pageRoot available')
+  const doc = pageRoot.ownerDocument || (typeof document !== 'undefined' ? document : null)
+  if (!doc) throw new Error('hypercms: no document available')
+
+  // Resolve rules via the union: an explicit rules object, a token string, or
+  // the default token "cms". findRules is document-scoped, so a head-mounted
+  // rules tag is found even though pageRoot defaults to <body>.
+  const source = opts.rules !== undefined ? opts.rules : 'cms'
+  const found = engine.findRules(doc, source)
+  if (!found) {
+    const what = typeof source === 'string' ? `data-rules-name~="${source}"` : 'the provided rules object'
+    throw new Error(`hypercms: no rules found for ${what}`)
+  }
+  const pageRules = found.rules
+  const rulesTagNode = found.tagNode
+
+  injectDefaults(doc)
+  warnUnmatchedTemplates(doc, pageRules)
+  const formRules = deriveFormRules(pageRules, doc)
+  const data = coerceBooleans(engine.extract(pageRoot, pageRules, { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }), pageRules)
+
+  // Suppress undo around mountShell: it toggles chrome-only classes on
+  // document.body (hcms-open, etc.) which would otherwise land as undoable
+  // page edits. The shell subtree itself is already filtered via save-ignore.
+  const shell = suppressUndo(() => mountShell({
+    mountTo: opts.mountTo || doc.body,
+    side: opts.side || 'right',
+    overlay: !!opts.overlay,
+    showSaveButton: !!opts.showSaveButton,
+    doc,
+  }))
+
+  const ctx = {
+    doc,
+    pageRoot,
+    pageRules,
+    formRules,
+    rulesTagNode,
+    rulesSource: source,
+    formRoot: shell.formRoot,
+    shellRoot: shell.root,
+    errorEl: shell.errorEl,
+    lastFingerprint: null,
+    lastData: null,
+    observerHandle: null,
+    onChange: opts.onChange,
+    onError: opts.onError,
+    onSave: opts.onSave,
+    previouslyFocused: doc.activeElement,
+    dispatch(name, detail) {
+      const Ctor = (doc.defaultView && doc.defaultView.CustomEvent) || (typeof CustomEvent !== 'undefined' ? CustomEvent : null)
+      if (!Ctor) return
+      const ev = new Ctor(name, { bubbles: true, cancelable: name === 'hcms:change' || name === 'hcms:save', detail })
+      shell.root.dispatchEvent(ev)
+    },
+    onCloseRequested() {
+      close()
+    },
+  }
+  ctx.updateFingerprint = () => {
+    ctx.lastFingerprint = stableStringify(extractFormData(ctx))
+  }
+
+  const fragment = buildForm({ pageRules, formRules, data, doc })
+  shell.formRoot.appendChild(fragment)
+
+  bindEvents(ctx)
+  ctx.updateFingerprint()
+
+  ctx.observerHandle = installObserver({
+    onRefresh: () => refreshForm(ctx),
+  })
+
+  // Wire global sortable callback to current ctx (replaced by close()).
+  globalCommitTarget.ctx = ctx
+  installGlobalSortableCommit(doc)
+
+  // Move focus into the shell — survives close+restore via previouslyFocused.
+  focusFirstIn(shell.root)
+
+  state.isOpen = true
+  state.ctx = ctx
+  state.shell = shell
+  state.opts = opts
+
+  ctx.dispatch('hcms:open', { pageRoot })
+}
+
+function focusFirstIn(root) {
+  const sel = 'input:not([disabled]):not([type="hidden"]), textarea:not([disabled]), select:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex="-1"])'
+  const target = root.querySelector(sel)
+  if (target && typeof target.focus === 'function') target.focus()
+}
+
+const globalCommitTarget = { ctx: null }
+
+function installGlobalSortableCommit(doc) {
+  const win = doc.defaultView || (typeof globalThis !== 'undefined' ? globalThis : null)
+  if (!win) return
+  const hypercmsCommitFn = function hypercmsCommitGlobal() {
+    const ctx = globalCommitTarget.ctx
+    if (!ctx) return
+    restampAllSiblings(ctx.formRoot)
+    // Route through commitWithUndo so a drag-reorder lands as a labeled
+    // 'Reorder' commit (not a generic idle 'Edit') and a failed apply's
+    // mutate+rollback is never recorded as a no-op commit. No-op pass-through
+    // when undo isn't loaded.
+    return commitWithUndo('Reorder', () =>
+      commit(extractFormData(ctx), { path: '', structural: true }, ctx)
+    )
+  }
+  if (typeof win.hypercmsCommit !== 'function') win.hypercmsCommit = hypercmsCommitFn
+  // Also mirror to globalThis so non-window contexts (Node tests, workers)
+  // can resolve the bare name from `new Function('hypercmsCommit()')`.
+  if (typeof globalThis !== 'undefined' && typeof globalThis.hypercmsCommit !== 'function') {
+    globalThis.hypercmsCommit = hypercmsCommitFn
+  }
+}
+
+export function close() {
+  if (!state.isOpen) return
+  const { ctx, shell } = state
+  const previouslyFocused = ctx.previouslyFocused
+  ctx.dispatch('hcms:close', null)
+  ctx.observerHandle?.unsubscribe?.()
+  ctx.detachEvents?.()
+  // destroy() removes the chrome-only body classes; suppress so the inverse
+  // class removal doesn't enter the undo stack either.
+  suppressUndo(() => shell.destroy())
+  state.isOpen = false
+  state.ctx = null
+  state.shell = null
+  state.opts = null
+  globalCommitTarget.ctx = null
+  if (previouslyFocused && typeof previouslyFocused.focus === 'function') {
+    try { previouslyFocused.focus() } catch (_) {}
+  }
+}
+
+export function refresh() {
+  if (!state.isOpen) return
+  refreshForm(state.ctx)
+}
+
+export function isOpen() {
+  return state.isOpen
+}
+
+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')
+    const ctx = state.ctx
+    const pathArr = pathUtil.fromString(path)
+    const rule = pathUtil.getRuleAtPath(ctx.pageRules, pathArr)
+    if (rule === undefined) throw new Error(`hypercms: no rule at path "${path}"`)
+    if (typeof rule !== 'string' || rule.endsWith('[]')) {
+      throw new Error(`hypercms: setValue requires a leaf scalar path; "${path}" is not a leaf`)
+    }
+    const field = findLeafField(ctx.formRoot, path)
+    if (!field) throw new Error(`hypercms: no field element at path "${path}"`)
+    writeFieldValue(field, value, ctx.formRoot, path)
+    commit(extractFormData(ctx), { path, structural: false }, ctx)
+  },
+  addItem(arrayPath) {
+    if (!state.isOpen) throw new Error('hypercms: cms is not open')
+    evOnAdd(arrayPath, state.ctx)
+  },
+  removeItem(itemPath) {
+    if (!state.isOpen) throw new Error('hypercms: cms is not open')
+    const ctx = state.ctx
+    const pathArr = pathUtil.fromString(itemPath)
+    // Validate path: must be an array item — last segment is a non-negative
+    // integer, parent rule must be an array (object-array or scalar-array).
+    const lastSeg = pathArr[pathArr.length - 1]
+    if (typeof lastSeg !== 'number') {
+      throw new Error(`hypercms: removeItem requires an item path; "${itemPath}" is not an array index`)
+    }
+    const parentRule = pathUtil.getRuleAtPath(ctx.pageRules, pathArr.slice(0, -1))
+    const parentIsArray = Array.isArray(parentRule) || (typeof parentRule === 'string' && parentRule.endsWith('[]'))
+    if (!parentIsArray) {
+      throw new Error(`hypercms: removeItem requires an item path; parent of "${itemPath}" is not an array`)
+    }
+    const itemEl = ctx.formRoot.querySelector(`[data-hcms-path="${cssEscape(itemPath)}"]`)
+    if (!itemEl) throw new Error(`hypercms: no element at path "${itemPath}"`)
+    evOnRemove(itemEl, ctx)
+  },
+  refresh,
+  _commit() {
+    if (!state.isOpen) return
+    const ctx = state.ctx
+    restampAllSiblings(ctx.formRoot)
+    return commitWithUndo('Update', () =>
+      commit(extractFormData(ctx), { path: '', structural: true }, ctx)
+    )
+  },
+}
+
+function findLeafField(formRoot, path) {
+  const esc = cssEscape(path)
+  // Prefer a tag-qualified leaf (input/textarea/select/img/a) — since v0.3
+  // stamps data-hcms-field on the wrapping container too, a bare attribute
+  // match would resolve to the container and lose the value write.
+  const leafSel =
+    `[data-hcms-path="${esc}"] input[data-hcms-field], ` +
+    `[data-hcms-path="${esc}"] textarea[data-hcms-field], ` +
+    `[data-hcms-path="${esc}"] select[data-hcms-field], ` +
+    `[data-hcms-path="${esc}"] img[data-hcms-field], ` +
+    `[data-hcms-path="${esc}"] a[data-hcms-field], ` +
+    `[data-hcms-path="${esc}"] [contenteditable][data-hcms-field], ` +
+    // Leaf is the path-stamped element itself (inline-stamped fields):
+    `input[data-hcms-path="${esc}"][data-hcms-field], ` +
+    `textarea[data-hcms-path="${esc}"][data-hcms-field], ` +
+    `select[data-hcms-path="${esc}"][data-hcms-field], ` +
+    `img[data-hcms-path="${esc}"][data-hcms-field], ` +
+    `a[data-hcms-path="${esc}"][data-hcms-field], ` +
+    `[contenteditable][data-hcms-path="${esc}"][data-hcms-field]`
+  return formRoot.querySelector(leafSel)
+}
+
+function writeFieldValue(el, value, formRoot, path) {
+  const tag = (el.tagName || '').toUpperCase()
+  const type = (el.getAttribute('type') || '').toLowerCase()
+  if (tag === 'INPUT' && type === 'checkbox') {
+    el.checked = value === true || value === 'true'
+    return
+  }
+  if (tag === 'INPUT' && type === 'radio') {
+    // Radios sharing the same path act as a group. Toggle the matching option.
+    const esc = cssEscape(path)
+    const group = formRoot.querySelectorAll(
+      `[data-hcms-path="${esc}"][data-hcms-field][type="radio"], [data-hcms-path="${esc}"] [data-hcms-field][type="radio"]`
+    )
+    if (group.length) {
+      group.forEach((r) => { r.checked = String(r.value) === String(value ?? '') })
+    } else {
+      el.checked = String(el.value) === String(value ?? '')
+    }
+    return
+  }
+  if (tag === 'IMG') {
+    el.src = value == null ? '' : String(value)
+    return
+  }
+  if (tag === 'A') {
+    el.href = value == null ? '' : String(value)
+    return
+  }
+  if ('value' in el) {
+    el.value = value == null ? '' : String(value)
+    return
+  }
+  el.textContent = value == null ? '' : String(value)
+}
+
+const cms = {
+  open,
+  close,
+  refresh,
+  api,
+  get isOpen() { return state.isOpen },
+  // Power-user exports (mostly for testing + advanced integration)
+  path: pathUtil,
+  scaffold,
+  morphForm,
+}
+
+function cssEscape(value) {
+  if (typeof CSS !== 'undefined' && CSS.escape) return CSS.escape(value)
+  return String(value).replace(/[^a-zA-Z0-9_\-.*]/g, (c) => '\\' + c)
+}
+
+export { cms }
+export default { cms }

package/src/morph.js

@@ -0,0 +1,10 @@
+import HyperMorph from 'hyper-morph'
+
+export function morphForm(formRoot, newFragment) {
+  HyperMorph.morph(formRoot, newFragment, {
+    morphStyle: 'innerHTML',
+    ignoreActiveValue: true,
+    restoreFocus: true,
+    formStateSync: 'property',
+  })
+}

package/src/path.js

@@ -0,0 +1,61 @@
+export function toString(path) {
+  return path.map(String).join('.')
+}
+
+export function fromString(str) {
+  if (str === '') return []
+  return str.split('.').map((seg) => (/^\d+$/.test(seg) ? Number(seg) : seg))
+}
+
+export function getRuleAtPath(rules, path) {
+  let node = rules
+  for (const seg of path) {
+    if (node == null) return undefined
+    if (typeof node === 'string') {
+      // Scalar-array rules like 'li[]' contain leaf scalars at integer indices.
+      // Descend by stripping the trailing []; the leaf is treated as a plain
+      // scalar string for path queries.
+      if (node.endsWith('[]') && (typeof seg === 'number' || seg === '*')) {
+        node = node.slice(0, -2)
+        continue
+      }
+      return undefined
+    }
+    if (Array.isArray(node)) {
+      if (typeof seg !== 'number' && seg !== '*') return undefined
+      node = node[1]
+      continue
+    }
+    if (typeof node === 'object') {
+      if (typeof seg === 'number') return undefined
+      if (!(seg in node)) return undefined
+      node = node[seg]
+      continue
+    }
+    return undefined
+  }
+  return node
+}
+
+export function getValueAtPath(data, path) {
+  let node = data
+  for (const seg of path) {
+    if (node == null) return undefined
+    node = node[seg]
+  }
+  return node
+}
+
+export function setAtPath(obj, path, value) {
+  if (path.length === 0) return value
+  const [k, ...rest] = path
+  if (typeof k === 'number') {
+    const next = Array.isArray(obj) ? [...obj] : []
+    next[k] = setAtPath(next[k], rest, value)
+    return next
+  }
+  return {
+    ...(obj && typeof obj === 'object' ? obj : {}),
+    [k]: setAtPath((obj || {})[k], rest, value),
+  }
+}

package/src/refresh.js

@@ -0,0 +1,57 @@
+import { engine } from 'hyper-html-api'
+import { buildForm } from './form-builder.js'
+import { morphForm } from './morph.js'
+import { injectDefaults } from './templates.js'
+import { deriveFormRules } from './form-rules.js'
+import { coerceBooleans, applyErrorState } from './events.js'
+
+const ENGINE_OPTS = { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }
+
+export function refreshForm(ctx) {
+  // Re-resolve rules every refresh, source-aware: an object source returns the
+  // same literal (tagNode null); a token source re-resolves the tag so a
+  // livesync-replaced rules tag is picked up. Document-scoped via ctx.doc.
+  const found = engine.findRules(ctx.doc, ctx.rulesSource || 'cms')
+  if (found) {
+    ctx.pageRules = found.rules
+    ctx.rulesTagNode = found.tagNode
+  }
+  // Re-derive formRules so schema changes (rule shape, template overrides) flow through.
+  injectDefaults(ctx.doc)
+  ctx.formRules = deriveFormRules(ctx.pageRules, ctx.doc)
+
+  const newData = coerceBooleans(
+    engine.extract(ctx.pageRoot, ctx.pageRules, ENGINE_OPTS),
+    ctx.pageRules
+  )
+  const fragment = buildForm({
+    pageRules: ctx.pageRules,
+    formRules: ctx.formRules,
+    data: newData,
+    doc: ctx.doc,
+  })
+  morphForm(ctx.formRoot, fragment)
+  // morphForm rebuilds the form structure; inline error slots get wiped. Re-apply
+  // the last error state so error messages survive across observer-driven refreshes
+  // (e.g., the rollback after a failed add).
+  applyErrorState(ctx)
+  // Update fingerprint so subsequent commits against the new page state compare correctly.
+  if (ctx.updateFingerprint) ctx.updateFingerprint()
+}
+
+export function installObserver({ debounce = 100, onRefresh }) {
+  const M = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.Mutation) || null
+  if (!M || typeof M.onAnyChange !== 'function') {
+    throw new Error('hypercms: window.hyperclay.Mutation is required. Load hyperclayjs (or just the mutation utility) before initializing hypercms.')
+  }
+  let paused = 0
+  const unsub = M.onAnyChange({ debounce }, () => {
+    if (paused > 0) return
+    onRefresh()
+  })
+  return {
+    unsubscribe: typeof unsub === 'function' ? unsub : () => {},
+    pause() { paused++ },
+    resume() { paused = Math.max(0, paused - 1) },
+  }
+}

package/src/scaffold.js

@@ -0,0 +1,10 @@
+export function scaffold(shape) {
+  if (typeof shape === 'string') return shape.endsWith('[]') ? [] : ''
+  if (Array.isArray(shape)) return []
+  if (typeof shape === 'object' && shape !== null) {
+    const out = {}
+    for (const [k, v] of Object.entries(shape)) out[k] = scaffold(v)
+    return out
+  }
+  return ''
+}

package/src/shell.js

@@ -0,0 +1,132 @@
+const SHELL_STYLE_ID = 'hcms-shell-styles'
+const SHELL_BUNDLED_FLAG = 'hcms-bundled-styles-installed'
+const FOCUSABLE = 'a[href], area[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+const styledDocs = new WeakSet()
+let cssText = ''
+
+export function setShellStyles(text) {
+  cssText = text
+}
+
+export function markStylesBundled(doc) {
+  // Bundler emits a <style data-hcms-bundled-styles> tag and sets this so
+  // the link-based path doesn't double-install.
+  if (!doc) return
+  styledDocs.add(doc)
+  doc[SHELL_BUNDLED_FLAG] = true
+}
+
+let titleIdCounter = 0
+
+export function mountShell({ mountTo, side = 'right', overlay = false, showSaveButton = false, doc }) {
+  ensureStyles(doc)
+  const titleId = `hcms-shell-title-${++titleIdCounter}`
+  const root = doc.createElement('div')
+  root.setAttribute('data-hcms-shell', '')
+  root.setAttribute('save-remove', '')
+  root.setAttribute('save-ignore', '')
+  root.setAttribute('tabindex', '-1')
+  // Dialog semantics: focus is trapped + body scrolling locked, so screen
+  // readers should announce this as a modal dialog with the shell title as
+  // its accessible name.
+  root.setAttribute('role', 'dialog')
+  root.setAttribute('aria-modal', 'true')
+  root.setAttribute('aria-labelledby', titleId)
+  root.className = 'hcms-shell hcms-side-' + side + (overlay ? ' hcms-overlay' : '')
+  root.innerHTML = `
+    <header class="hcms-shell-header">
+      <h2 class="hcms-shell-title" id="${titleId}">Edit</h2>
+      <button type="button" class="hcms-shell-close" data-hcms-action="close" aria-label="Close">×</button>
+    </header>
+    <div class="hcms-shell-error" role="alert" hidden></div>
+    <div data-hcms-form-root class="hcms-form"></div>
+    <footer class="hcms-shell-footer"${showSaveButton ? '' : ' hidden'}>
+      <button type="button" class="hcms-shell-save" data-hcms-action="save">Save</button>
+    </footer>
+  `
+
+  // mountTo may be a nested element inside pageRoot. Use it as-is for the
+  // visual hierarchy; engine reads/writes pass { skip: '[data-hcms-shell]' }
+  // so the engine never traverses into the form regardless of where it's mounted.
+  const host = mountTo || doc.body
+  host.appendChild(root)
+
+  const body = doc.body
+  body.classList.add('hcms-open')
+  if (overlay) body.classList.add('hcms-overlay')
+  if (side === 'left') body.classList.add('hcms-side-left')
+
+  const focusTrap = installFocusTrap(root, doc)
+
+  return {
+    root,
+    formRoot: root.querySelector('[data-hcms-form-root]'),
+    errorEl: root.querySelector('.hcms-shell-error'),
+    saveButton: root.querySelector('.hcms-shell-save'),
+    destroy() {
+      focusTrap.detach()
+      root.remove()
+      body.classList.remove('hcms-open', 'hcms-overlay', 'hcms-side-left')
+    },
+  }
+}
+
+function ensureStyles(doc) {
+  if (!doc) return
+  if (styledDocs.has(doc)) return
+  if (doc[SHELL_BUNDLED_FLAG]) {
+    styledDocs.add(doc)
+    return
+  }
+  if (doc.getElementById(SHELL_STYLE_ID) || doc.querySelector('style[data-hcms-bundled-styles]')) {
+    styledDocs.add(doc)
+    return
+  }
+  if (cssText) {
+    const style = doc.createElement('style')
+    style.id = SHELL_STYLE_ID
+    style.setAttribute('save-remove', '')
+    style.textContent = cssText
+    ;(doc.head || doc.documentElement).appendChild(style)
+    styledDocs.add(doc)
+    return
+  }
+  // No bundled CSS — try resolving the sibling styles.css via import.meta.url.
+  // Browsers ESM-resolved imports place a co-located styles.css next to
+  // hypercms.js. Falls back silently if resolution fails (e.g., bundlers
+  // without an asset emitter).
+  try {
+    const href = new URL('./styles.css', import.meta.url).href
+    const link = doc.createElement('link')
+    link.rel = 'stylesheet'
+    link.id = SHELL_STYLE_ID
+    link.setAttribute('save-remove', '')
+    link.href = href
+    ;(doc.head || doc.documentElement).appendChild(link)
+    styledDocs.add(doc)
+  } catch (_) {
+    // SSR or environments without import.meta.url — author can call
+    // installStyles(text) manually.
+  }
+}
+
+function installFocusTrap(root, doc) {
+  function onKeyDown(e) {
+    if (e.key !== 'Tab') return
+    if (!root.contains(doc.activeElement)) return
+    const focusables = Array.from(root.querySelectorAll(FOCUSABLE))
+    if (focusables.length === 0) return
+    const first = focusables[0]
+    const last = focusables[focusables.length - 1]
+    if (e.shiftKey && doc.activeElement === first) {
+      e.preventDefault()
+      last.focus()
+    } else if (!e.shiftKey && doc.activeElement === last) {
+      e.preventDefault()
+      first.focus()
+    }
+  }
+  doc.addEventListener('keydown', onKeyDown)
+  return { detach: () => doc.removeEventListener('keydown', onKeyDown) }
+}