@panphora/hyper-cms 0.4.1 → 0.5.0

package/src/hypercms.js

@@ -2,7 +2,7 @@ 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 { injectDefaults, injectUploadComponents } from './templates.js'
 import { deriveFormRules } from './form-rules.js'
 import { buildForm } from './form-builder.js'
 import {
@@ -36,11 +36,56 @@ const state = {
   opts: null,
 }
 
+// Re-sync the form to the page after a change hypercms did NOT originate.
+// `reason` selects whether the field the user is currently typing in snaps:
+//   'undo' / 'redo' — the user's own deliberate action, so the focused field
+//                     SHOULD snap to the reverted value (ignoreActiveValue:false).
+//   'livesync'      — someone else's / the framework's change, so the user's
+//                     in-progress focused field must NOT be yanked away
+//                     (ignoreActiveValue:true). morphForm re-extracts every
+//                     other field to the new page value, killing the stale-form
+//                     clobber, while leaving the active field alone until blur.
+// Both reasons route through this one handler so there is a single place to
+// maintain the form-resync behavior.
+function resyncForm(ctx, reason) {
+  // open() may have moved on (closed, or reopened with a new ctx) between an
+  // async morph completing and this firing.
+  if (state.ctx !== ctx) return
+  const ignoreActiveValue = reason === 'livesync'
+  if (reason === 'livesync') {
+    // A full-document morph can wipe the shell's <head> stylesheet and the
+    // <body> chrome classes (both live outside the save-ignore shell subtree).
+    // Re-assert them before re-extracting.
+    state.shell?.restoreChrome?.()
+  }
+  refreshForm(ctx, { ignoreActiveValue })
+}
+
+// Strip hypercms's own body chrome from the SAVE clone so it never reaches disk
+// (the shell element itself is [save-remove], but the hcms-open class lives on
+// <body>, outside the stripped subtree). Registered once at first open():
+// onPrepareForSave runs save-only, on a clone, so it never touches the live DOM,
+// and removing absent classes is a no-op when the shell is closed. Guarded so it
+// degrades cleanly when the host save pipeline (hyperclayjs) isn't present.
+let prepareHookInstalled = false
+function installSavePrepareHook() {
+  if (prepareHookInstalled) return
+  const onPrepareForSave =
+    (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.onPrepareForSave) || null
+  if (typeof onPrepareForSave !== 'function') return
+  onPrepareForSave((clonedDocEl) => {
+    const b = clonedDocEl && clonedDocEl.querySelector && clonedDocEl.querySelector('body')
+    if (b) b.classList.remove('hcms-open', 'hcms-overlay', 'hcms-side-left')
+  })
+  prepareHookInstalled = true
+}
+
 export function open(opts = {}) {
   if (state.isOpen) {
     console.warn('cms.open() called while already open; ignoring')
     return
   }
+  installSavePrepareHook()
   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)
@@ -59,6 +104,7 @@ export function open(opts = {}) {
   const rulesTagNode = found.tagNode
 
   injectDefaults(doc)
+  injectUploadComponents(doc, pageRules)
   warnUnmatchedTemplates(doc, pageRules)
   const formRules = deriveFormRules(pageRules, doc)
   const data = coerceBooleans(engine.extract(pageRoot, pageRules, { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }), pageRules)
@@ -71,6 +117,9 @@ export function open(opts = {}) {
     side: opts.side || 'right',
     overlay: !!opts.overlay,
     showSaveButton: !!opts.showSaveButton,
+    title: opts.title,
+    eyebrow: opts.eyebrow,
+    theme: opts.theme,
     doc,
   }))
 
@@ -88,14 +137,15 @@ export function open(opts = {}) {
     lastData: null,
     observerHandle: null,
     undoUnsub: null,
+    livesyncUnsub: null,
     onChange: opts.onChange,
     onError: opts.onError,
-    onSave: opts.onSave,
+    confirmRemove: opts.confirmRemove,
     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 })
+      const ev = new Ctor(name, { bubbles: true, cancelable: name === 'hcms:change', detail })
       shell.root.dispatchEvent(ev)
     },
     onCloseRequested() {
@@ -106,6 +156,13 @@ export function open(opts = {}) {
     ctx.lastFingerprint = stableStringify(extractFormData(ctx))
   }
 
+  // Everything past the shell mount touches the live DOM, the module-level state,
+  // and external subscriptions (observer, undo, livesync). A throw in here — most
+  // notably installObserver when window.hyperclay.Mutation isn't loaded — would
+  // otherwise strand the mounted shell in the DOM with no way to close it (close()
+  // early-returns while state.isOpen is false). Tear down whatever was wired,
+  // exactly as close() does, then rethrow so host misuse still fails loudly.
+  try {
   const fragment = buildForm({ pageRules, formRules, data, doc })
   shell.formRoot.appendChild(fragment)
 
@@ -123,12 +180,42 @@ export function open(opts = {}) {
   // the active field. Guarded so it degrades to today's behavior when undo isn't loaded.
   const u = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.undo) || null
   if (u && typeof u.on === 'function') {
-    const onRevert = () => refreshForm(ctx, { ignoreActiveValue: false })
+    const onRevert = () => {
+      if (state.ctx !== ctx) return
+      resyncForm(ctx, 'undo')
+      // A reverted change the consumer persists through onChange (e.g. the
+      // collection dashboard PUTs the record, not the page) would otherwise lag
+      // the undo: refreshForm re-syncs the form but never fires onChange, and a
+      // commit() here would be fingerprint-skipped (refreshForm already updated
+      // it). Extract the reverted state from the PAGE (the source of truth after
+      // an undo/redo; the form can lag a morph) and fire onChange directly, but
+      // only when it actually changed — guards spurious PUTs on undo/redo of
+      // unrelated edits elsewhere on the page.
+      const data = coerceBooleans(
+        engine.extract(ctx.pageRoot, ctx.pageRules, { skip: '[data-hcms-shell]', templateAttr: 'cms-template' }),
+        ctx.pageRules
+      )
+      if (stableStringify(data) !== stableStringify(ctx.lastData)) {
+        ctx.lastData = data
+        ctx.onChange?.(data, { path: '', structural: false })
+      }
+    }
     u.on('undo', onRevert)
     u.on('redo', onRevert)
     ctx.undoUnsub = () => { u.off('undo', onRevert); u.off('redo', onRevert) }
   }
 
+  // Live-sync / version-restore / any framework-applied full-document morph runs
+  // inside window.hyperclay.Mutation.pause(), which the source-blind observer
+  // above is deaf to — so without this the form stays stale after a remote edit
+  // and the next local commit re-applies the stale data, clobbering the remote
+  // change. Subscribe to the morph-applied signal live-sync emits and re-extract
+  // with ignoreActiveValue:true (preserve the user's in-progress field). Same
+  // document live-sync dispatches on; unsubscribed in close().
+  const onLivesync = () => resyncForm(ctx, 'livesync')
+  doc.addEventListener('hyperclay:livesync-applied', onLivesync)
+  ctx.livesyncUnsub = () => doc.removeEventListener('hyperclay:livesync-applied', onLivesync)
+
   // Wire global sortable callback to current ctx (replaced by close()).
   globalCommitTarget.ctx = ctx
   installGlobalSortableCommit(doc)
@@ -142,6 +229,19 @@ export function open(opts = {}) {
   state.opts = opts
 
   ctx.dispatch('hcms:open', { pageRoot })
+  } catch (err) {
+    ctx.observerHandle?.unsubscribe?.()
+    ctx.undoUnsub?.()
+    ctx.livesyncUnsub?.()
+    ctx.detachEvents?.()
+    if (globalCommitTarget.ctx === ctx) globalCommitTarget.ctx = null
+    suppressUndo(() => shell.destroy())
+    state.isOpen = false
+    state.ctx = null
+    state.shell = null
+    state.opts = null
+    throw err
+  }
 }
 
 function focusFirstIn(root) {
@@ -175,13 +275,60 @@ function installGlobalSortableCommit(doc) {
   }
 }
 
+// The query param that drives ?cms=true auto-open. Closing the CMS rewrites it
+// to cms=false (param kept) so a refresh/share of the post-close URL does not
+// auto-reopen.
+const AUTO_OPEN_PARAM = 'cms'
+
+// Pure: given a location.search string, return the search string after a close.
+// Only rewrites when cms=true is present; every other param + ordering is
+// preserved, and a search without cms (or already cms=false) is returned
+// unchanged so we never inject the param into a page that never carried it.
+export function nextSearchAfterClose(search) {
+  const str = typeof search === 'string' ? search : ''
+  const qIndex = str.indexOf('?')
+  const query = qIndex === -1 ? str : str.slice(qIndex + 1)
+  if (!query) return str
+  const params = new URLSearchParams(query)
+  if (params.get(AUTO_OPEN_PARAM) !== 'true') return str
+  params.set(AUTO_OPEN_PARAM, 'false')
+  return '?' + params.toString()
+}
+
+// Pure: should the CMS auto-open for this location.search? Exactly 'true'.
+export function shouldAutoOpenFromSearch(search) {
+  const str = typeof search === 'string' ? search : ''
+  const qIndex = str.indexOf('?')
+  const query = qIndex === -1 ? str : str.slice(qIndex + 1)
+  if (!query) return false
+  return new URLSearchParams(query).get(AUTO_OPEN_PARAM) === 'true'
+}
+
+// Rewrite ?cms=true → ?cms=false via history.replaceState (no reload, hash and
+// every other param preserved). No-op when the param isn't present or the
+// History API is unavailable.
+function toggleCloseParam() {
+  if (typeof window === 'undefined' || !window.location || !window.history) return
+  if (typeof window.history.replaceState !== 'function') return
+  const current = window.location.search
+  const next = nextSearchAfterClose(current)
+  if (next === current) return
+  window.history.replaceState(window.history.state, '', next + window.location.hash)
+}
+
 export function close() {
   if (!state.isOpen) return
   const { ctx, shell } = state
+  // Mark this ctx dead so any in-flight async work (e.g. an upload awaiting the
+  // host uploader) bails instead of mutating the page / firing onChange after
+  // teardown. Mirrors the state.ctx !== ctx guards on the undo/livesync paths.
+  ctx.closed = true
   const previouslyFocused = ctx.previouslyFocused
   ctx.dispatch('hcms:close', null)
+  toggleCloseParam()
   ctx.observerHandle?.unsubscribe?.()
   ctx.undoUnsub?.()
+  ctx.livesyncUnsub?.()
   ctx.detachEvents?.()
   // destroy() removes the chrome-only body classes; suppress so the inverse
   // class removal doesn't enter the undo stack either.
@@ -315,6 +462,104 @@ function writeFieldValue(el, value, formRoot, path) {
   el.textContent = value == null ? '' : String(value)
 }
 
+// ?cms=true auto-open. When the page URL carries cms=true at load, open the CMS
+// for everyone (no gating — this is a feature showcase; a non-admin's edits stay
+// DOM-local and the host save path shows its view-mode notice). open() is
+// idempotent-safe (it warns + returns if already open), so a host that also calls
+// open() never double-mounts. No special opts — host defaults apply.
+//
+// Patience matters here: this runs at module load from the dist IIFE, which a
+// host typically loads BEFORE installing window.hyperclay.Mutation (the Mutation
+// install often sits behind an `await import(...)` that resumes after this script,
+// even after DOMContentLoaded). open() needs <body> AND Mutation, so we poll for
+// both rather than firing eagerly. Firing without Mutation would throw out of
+// installObserver, escape module evaluation, and abort esbuild's
+// window.hypercms assignment — taking the host's own wiring down with it.
+const SAFETY_POLL_MS = 250
+const AUTO_OPEN_DEADLINE_MS = 10000
+export function maybeAutoOpen() {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return
+  if (!shouldAutoOpenFromSearch(window.location ? window.location.search : '')) return
+  if (state.isOpen) return
+  whenReady(() => {
+    if (state.isOpen) return
+    try {
+      open()
+    } catch (err) {
+      console.warn('hypercms: auto-open failed', err)
+    }
+  })
+}
+
+// Auto-open is ready only once <body> is parsed AND window.hyperclay.Mutation is
+// installed (open() needs both). NEVER throw out of module scope.
+function autoOpenReady() {
+  return !!document.body && !!(window.hyperclay && window.hyperclay.Mutation)
+}
+
+// Three layers, in order of preference:
+//   1. Sync fast-path: if <body> and Mutation are already here, fire now.
+//   2. Event: hyperclayjs's mutation.js dispatches 'hyperclay:mutation-ready' the
+//      instant it installs window.hyperclay.Mutation. On loader pages this is
+//      moot — the loader's first wave evaluates mutation before hypercms, so the
+//      fast-path wins — but the event catches any late install (the deferred
+//      `await import()` ordering). The body gate is re-checked in the handler
+//      because the event can land before <body> is parsed.
+//   3. Backstop: a slow self-cancelling 250ms poll for exotic hosts that hand-roll
+//      window.hyperclay.Mutation by direct assignment WITHOUT dispatching the
+//      event. It cancels the moment the event fires, open succeeds, or the
+//      deadline is hit (warn, never throw).
+function whenReady(fn) {
+  if (autoOpenReady()) {
+    fn()
+    return
+  }
+  const deadline = Date.now() + AUTO_OPEN_DEADLINE_MS
+  let done = false
+  let timer = null
+  const finish = () => {
+    if (done) return
+    done = true
+    if (timer !== null) clearInterval(timer)
+    document.removeEventListener('hyperclay:mutation-ready', onMutationReady)
+  }
+  function onMutationReady() {
+    if (state.isOpen) {
+      finish()
+      return
+    }
+    if (autoOpenReady()) {
+      finish()
+      fn()
+    }
+    // Body may still be pending — the one-shot listener is already consumed,
+    // so only the backstop remains to catch it once body arrives.
+  }
+  document.addEventListener('hyperclay:mutation-ready', onMutationReady, { once: true })
+  timer = setInterval(() => {
+    if (state.isOpen) {
+      finish()
+      return
+    }
+    if (autoOpenReady()) {
+      finish()
+      fn()
+      return
+    }
+    if (Date.now() >= deadline) {
+      finish()
+      console.warn(
+        'hypercms: ?cms=true auto-open gave up — window.hyperclay.Mutation never appeared. ' +
+        'Load hyperclayjs (or the mutation utility) so the CMS can initialize.'
+      )
+    }
+  }, SAFETY_POLL_MS)
+}
+
+// Auto-open at module load (browser only — node tests import this without a real
+// window, and the guards above no-op there).
+maybeAutoOpen()
+
 const cms = {
   open,
   close,

package/src/refresh.js

@@ -1,7 +1,7 @@
 import { engine } from 'hyper-html-api'
 import { buildForm } from './form-builder.js'
 import { morphForm } from './morph.js'
-import { injectDefaults } from './templates.js'
+import { injectDefaults, injectUploadComponents } from './templates.js'
 import { deriveFormRules } from './form-rules.js'
 import { coerceBooleans, applyErrorState } from './events.js'
 
@@ -18,6 +18,7 @@ export function refreshForm(ctx, { ignoreActiveValue } = {}) {
   }
   // Re-derive formRules so schema changes (rule shape, template overrides) flow through.
   injectDefaults(ctx.doc)
+  injectUploadComponents(ctx.doc, ctx.pageRules)
   ctx.formRules = deriveFormRules(ctx.pageRules, ctx.doc)
 
   const newData = coerceBooleans(

package/src/shell.js

@@ -19,7 +19,22 @@ export function markStylesBundled(doc) {
 
 let titleIdCounter = 0
 
-export function mountShell({ mountTo, side = 'right', overlay = false, showSaveButton = false, doc }) {
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"]/g, (c) => (
+    { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]
+  ))
+}
+
+export function mountShell({
+  mountTo,
+  side = 'right',
+  overlay = false,
+  showSaveButton = false,
+  title = 'Page content',
+  eyebrow = 'Edit',
+  theme = null,
+  doc,
+}) {
   ensureStyles(doc)
   const titleId = `hcms-shell-title-${++titleIdCounter}`
   const root = doc.createElement('div')
@@ -33,17 +48,45 @@ export function mountShell({ mountTo, side = 'right', overlay = false, showSaveB
   root.setAttribute('role', 'dialog')
   root.setAttribute('aria-modal', 'true')
   root.setAttribute('aria-labelledby', titleId)
-  root.className = 'hcms-shell hcms-side-' + side + (overlay ? ' hcms-overlay' : '')
+  // pixel-quiet is the baked-in look; an optional theme pins light/dark
+  // (otherwise the panel follows the OS via prefers-color-scheme).
+  const themeClass = theme === 'dark' ? ' dark' : theme === 'light' ? ' light' : ''
+  root.className =
+    'hcms-shell pixel-quiet hcms-side-' + side + (overlay ? ' hcms-overlay' : '') + themeClass
+  const titleHtml = escapeHtml(title)
+  const eyebrowHtml = escapeHtml(eyebrow)
+  // Pixel Quiet shell: a scroll-away header + in-flow Save inside .hcms-shell-body,
+  // with a condensed minibar pinned to the panel top once the header scrolls out.
+  // Close + Save are real mirk buttons. The .hcms-* hooks stay so the engine and
+  // events bind exactly as before; only the chrome shape changed.
+  // The Save button has no wiring here: [trigger-save] is the hyperclayjs save
+  // attribute — its save system (or its view-mode notice) handles the click.
+  // Standalone hosts delegate their own [trigger-save] click listener.
   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>
+    <div class="hcms-shell-minibar" aria-hidden="true">
+      <span class="hcms-shell-minibar-title">${titleHtml}</span>
+      <button type="button" class="hcms-shell-close mirk-button mirk-button--small" data-hcms-action="close" aria-label="Close">
+        <span class="mirk-button__label">×</span>
+      </button>
+    </div>
+    <div class="hcms-shell-body">
+      <header class="hcms-shell-header">
+        <div class="hcms-shell-heading">
+          <div class="hcms-shell-eyebrow">${eyebrowHtml}</div>
+          <h2 class="hcms-shell-title" id="${titleId}">${titleHtml}</h2>
+        </div>
+        <button type="button" class="hcms-shell-close mirk-button mirk-button--small" data-hcms-action="close" aria-label="Close">
+          <span class="mirk-button__label">×</span>
+        </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 mirk-button" trigger-save>
+          <span class="mirk-button__label">Save</span>
+        </button>
+      </footer>
+    </div>
   `
 
   // mountTo may be a nested element inside pageRoot. Use it as-is for the
@@ -58,6 +101,7 @@ export function mountShell({ mountTo, side = 'right', overlay = false, showSaveB
   if (side === 'left') body.classList.add('hcms-side-left')
 
   const focusTrap = installFocusTrap(root, doc)
+  const condense = installCondenseOnScroll(root)
 
   return {
     root,
@@ -66,12 +110,36 @@ export function mountShell({ mountTo, side = 'right', overlay = false, showSaveB
     saveButton: root.querySelector('.hcms-shell-save'),
     destroy() {
       focusTrap.detach()
+      condense.detach()
       root.remove()
       body.classList.remove('hcms-open', 'hcms-overlay', 'hcms-side-left')
     },
+    // Re-assert the shell's out-of-subtree chrome after a full-document morph
+    // (e.g. a live-sync apply) wipes it: the stylesheet lives in <head> and the
+    // body classes live on <body>, both outside the save-ignore shell element,
+    // so hyper-morph's head-merge / class reconciliation can strip them.
+    restoreChrome() {
+      reensureStyles(doc)
+      body.classList.add('hcms-open')
+      if (overlay) body.classList.add('hcms-overlay')
+      if (side === 'left') body.classList.add('hcms-side-left')
+    },
   }
 }
 
+// Re-inject the shell stylesheet if a morph (or anything else) removed it.
+// Unlike ensureStyles, this does NOT trust the styledDocs WeakSet: a morph can
+// remove the <style> tag while the WeakSet still marks the doc as "styled", so
+// a naive ensureStyles() call would no-op. Re-check the live DOM, clear the
+// stale mark, and let ensureStyles rebuild from cssText.
+export function reensureStyles(doc) {
+  if (!doc) return
+  if (doc.getElementById(SHELL_STYLE_ID) ||
+      doc.querySelector('style[data-hcms-bundled-styles]')) return
+  styledDocs.delete(doc)
+  ensureStyles(doc)
+}
+
 function ensureStyles(doc) {
   if (!doc) return
   if (styledDocs.has(doc)) return
@@ -92,12 +160,12 @@ function ensureStyles(doc) {
     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).
+  // No bundled CSS — try resolving the sibling generated theme via
+  // import.meta.url. Browsers ESM-resolved imports place a co-located
+  // theme.generated.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 href = new URL('./theme.generated.css', import.meta.url).href
     const link = doc.createElement('link')
     link.rel = 'stylesheet'
     link.id = SHELL_STYLE_ID
@@ -111,6 +179,25 @@ function ensureStyles(doc) {
   }
 }
 
+// Reveal the condensed minibar once the full header scrolls out of the body
+// (pixel-quiet decision 0003). Passive listener; toggles .is-condensed on the
+// shell root when scrollTop passes the header height. No-op if the body or
+// header is missing (e.g. a custom mount that omits them).
+function installCondenseOnScroll(root) {
+  const bodyEl = root.querySelector('.hcms-shell-body')
+  const header = root.querySelector('.hcms-shell-header')
+  if (!bodyEl || !header || typeof bodyEl.addEventListener !== 'function') {
+    return { detach() {} }
+  }
+  const reveal = () => {
+    const trigger = (header.offsetHeight || 0) - 12
+    root.classList.toggle('is-condensed', bodyEl.scrollTop > trigger)
+  }
+  bodyEl.addEventListener('scroll', reveal, { passive: true })
+  reveal()
+  return { detach() { bodyEl.removeEventListener('scroll', reveal) } }
+}
+
 function installFocusTrap(root, doc) {
   function onKeyDown(e) {
     if (e.key !== 'Tab') return