@panphora/hyper-cms 0.4.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/hyper-cms",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Live edit-in-place CMS sidebar for HTML pages with a hyper-html-api rules tag",
   "keywords": [
     "HTML",
@@ -20,7 +20,8 @@
   "module": "src/hypercms.js",
   "exports": {
     ".": "./src/hypercms.js",
-    "./styles.css": "./src/styles.css"
+    "./styles.css": "./src/theme.generated.css",
+    "./theme.css": "./src/theme.generated.css"
   },
   "files": [
     "LICENSE",
@@ -30,7 +31,8 @@
     "dist/*.js"
   ],
   "scripts": {
-    "build": "npx esbuild src/hypercms-bundle.js --bundle --minify --format=iife --global-name=hypercms --loader:.css=text --outfile=dist/hypercms.min.js",
+    "build:theme": "node scripts/build-theme.js",
+    "build": "npm run build:theme && npx esbuild src/hypercms-bundle.js --bundle --minify --format=iife --global-name=hypercms --loader:.css=text --outfile=dist/hypercms.min.js",
     "prepublishOnly": "npm run build",
     "copy-to-hyperclayjs": "npm run build && node scripts/copy-to-hyperclayjs.js",
     "test:node": "node --test 'test-node/**/*.test.js'",

package/src/events.js

@@ -1,7 +1,7 @@
 import { engine } from 'hyper-html-api'
 import { applyWithRollback } from './apply-loop.js'
-import { fromString as pathFromString } from './path.js'
-import { buildItem } from './form-builder.js'
+import { fromString as pathFromString, getRuleAtPath } from './path.js'
+import { buildItem, fileNameFromUrl } from './form-builder.js'
 import { scaffold } from './scaffold.js'
 
 const BOUND = new WeakSet()
@@ -56,6 +56,11 @@ export function bindEvents(ctx) {
     if (!target || !target.closest) return
     if (!target.closest('[data-hcms-form-root]')) return
     if (!target.matches('input, textarea, select')) return
+    // The upload picker fires `input` too, but its .value is the OS fake path
+    // (C:\fakepath\…); it's handled on `change` via onUploadChange. The wrapper
+    // carries data-hcms-field, so without this guard the closest() below would
+    // route the fake path into onScalarChange.
+    if (target.matches('input[type="file"]')) return
     if (!target.closest('[data-hcms-field]') && !target.hasAttribute?.('data-hcms-field')) return
     onScalarChange(target, ctx)
   }
@@ -64,6 +69,10 @@ export function bindEvents(ctx) {
     const target = e.target
     if (!target || !target.closest) return
     if (!target.closest('[data-hcms-form-root]')) return
+    if (target.matches('input[type="file"][data-hcms-upload]')) {
+      onUploadChange(target, ctx)
+      return
+    }
     if (target.matches('input[type="checkbox"], input[type="radio"], select')) {
       onScalarChange(target, ctx)
     }
@@ -75,11 +84,11 @@ export function bindEvents(ctx) {
     const actionEl = target.closest('[data-hcms-action]')
     if (!actionEl) return
     const action = actionEl.getAttribute('data-hcms-action')
-    // add/remove/move must live inside the form root; close/save inside the shell.
+    // add/remove/move must live inside the form root; close inside the shell.
     // Ignore stray data-hcms-action attributes elsewhere on the page.
-    if (action === 'add' || action === 'remove' || action === 'move-up' || action === 'move-down') {
+    if (action === 'add' || action === 'remove' || action === 'move-up' || action === 'move-down' || action === 'clear-upload') {
       if (!actionEl.closest('[data-hcms-form-root]')) return
-    } else if (action === 'close' || action === 'save') {
+    } else if (action === 'close') {
       if (!actionEl.closest('[data-hcms-shell]')) return
     }
     if (action === 'add') {
@@ -90,15 +99,15 @@ export function bindEvents(ctx) {
     } else if (action === 'remove') {
       const itemEl = actionEl.closest('[data-hcms-card], [data-hcms-array-item]')
       if (!itemEl) return
-      onRemove(itemEl, ctx)
+      requestRemove(itemEl, ctx)
     } else if (action === 'move-up' || action === 'move-down') {
       const itemEl = actionEl.closest('[data-hcms-card], [data-hcms-array-item]')
       if (!itemEl) return
       onMove(itemEl, action === 'move-up' ? -1 : 1, ctx)
+    } else if (action === 'clear-upload') {
+      onClearUpload(actionEl, ctx)
     } else if (action === 'close') {
       ctx.onCloseRequested?.()
-    } else if (action === 'save') {
-      onSave(ctx)
     }
   }
 
@@ -115,10 +124,169 @@ export function bindEvents(ctx) {
   }
 }
 
+// Element PROPERTIES a form field projects to that fire NO MutationRecord, so
+// hyper-undo's observer can't see them (an input's live `value`, a checkbox's
+// `checked`). Text projections ARE observed (characterData) and need nothing
+// here. Kept narrow on purpose: the broader engine DOM_PROPERTIES_WRITE_SET
+// includes observable writes (innerHTML/outerHTML) we must NOT double-record.
+const UNOBSERVED_FIELD_PROPS = new Set(['value', 'checked'])
+
+// Resolve the page element + property a scalar field projects to, but ONLY for
+// the unobserved-property case above. `pathStr` is the field's FULL path (the
+// scalar field element carries data-hcms-path = full path, e.g. "name" or
+// "products.0.name"). Returns { el, prop, oldValue } captured from the live page
+// BEFORE the apply, or null when the projection is text, targets an array item
+// (the engine's ctx isn't pageRoot then), or can't be resolved.
+function resolveUnobservedProjection(ctx, pathStr) {
+  if (!pathStr) return null
+  const fullPath = pathFromString(pathStr)
+  // Array-item fields project under a per-item engine ctx, not pageRoot. Resolving
+  // pageRoot.querySelector(selector) would grab the wrong item, so skip — the edit
+  // simply keeps today's no-undo behavior rather than recording a wrong revert.
+  if (fullPath.some((seg) => typeof seg === 'number' || seg === '*')) return null
+  const rule = getRuleAtPath(ctx.pageRules, fullPath)
+  if (typeof rule !== 'string') return null
+  const at = rule.lastIndexOf('@')
+  if (at === -1) return null                       // text projection — observed
+  const prop = rule.slice(at + 1)
+  if (!UNOBSERVED_FIELD_PROPS.has(prop)) return null
+  const selector = rule.slice(0, at)
+  const el = selector ? ctx.pageRoot.querySelector(selector) : ctx.pageRoot
+  if (!el) return null
+  return { el, prop, oldValue: el[prop] }
+}
+
 export function onScalarChange(target, ctx) {
   const fieldEl = target.closest('[data-hcms-field]') || target
   const pathStr = fieldEl.closest('[data-hcms-path]')?.getAttribute('data-hcms-path') || ''
+  // Capture the projected page value BEFORE commit() overwrites it. Property
+  // writes (@value/@checked) leave no MutationRecord, so without recording them
+  // explicitly they produce no undo step (text projections are observed).
+  const proj = resolveUnobservedProjection(ctx, pathStr)
   commit(extractFormData(ctx), { path: pathStr, structural: false }, ctx)
+  if (proj) {
+    const u = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.undo) || null
+    if (u && typeof u.recordValue === 'function') {
+      u.recordValue(proj.el, { prop: proj.prop, oldValue: proj.oldValue, newValue: proj.el[proj.prop] })
+    }
+  }
+}
+
+// Crop adapter seam. A pass-through today; Slice 6 fills the body to route the
+// file through window.hyperclay.quickcrop before upload when the field opts in
+// via data-hcms-crop. Returns { file, dataURL? }, or null to abort (crop
+// cancelled). Keeping ALL crop coupling here means no other upload code changes
+// when crop lands.
+async function maybeCrop(file /*, fieldEl */) {
+  return { file }
+}
+
+// A file was picked in an @file/@image widget. Optionally crop, upload via the
+// host's uploadFileBasic (or fall back to a local object-URL preview), write the
+// resulting URL into the bound img.src / a.href leaf, then commit once. The leaf
+// attribute change is an observed page mutation, so undo gets a clean step with
+// no commitWithUndo. Async; failures surface inline and reset the picker.
+export async function onUploadChange(inputEl, ctx) {
+  const file = inputEl.files && inputEl.files[0]
+  if (!file) return
+  const fieldEl = inputEl.closest('[data-hcms-path]')
+  if (!fieldEl) return
+  const pathStr = fieldEl.getAttribute('data-hcms-path') || ''
+
+  const cropped = await maybeCrop(file, fieldEl)
+  if (!cropped || ctx.closed) { resetPicker(inputEl); return }
+  const fileLike = cropped.file
+  const previewDataUrl = cropped.dataURL || null
+
+  const upload = (typeof window !== 'undefined' && window.hyperclay && window.hyperclay.uploadFileBasic) || null
+  let url = null
+  if (typeof upload === 'function') {
+    try {
+      const res = await upload(fileLike)
+      // uploadFileBasic resolves the full envelope { uploads:[{name,nodeId,url}], … };
+      // the served URL is uploads[0].url, NOT res.url.
+      url = res && res.uploads && res.uploads[0] && res.uploads[0].url
+    } catch (err) {
+      if (ctx.closed) { resetPicker(inputEl); return }
+      showFieldUploadError(fieldEl, (err && err.message) || 'Upload failed')
+      ctx.dispatch?.('hcms:error', { error: err, path: pathStr })
+      resetPicker(inputEl)
+      return
+    }
+  }
+  // The editor may have been closed while the upload was in flight; bail before
+  // writing the (now detached) form leaf or committing to the live page.
+  if (ctx.closed) { resetPicker(inputEl); return }
+  if (!url) {
+    // No host uploader (or it returned nothing): local preview only, which the
+    // commit persists into the page as a blob:/data: URL — non-persistent, by
+    // design (documented), so the widget still works in a bare page / demo.
+    url = previewDataUrl || makeLocalPreviewUrl(fileLike)
+  }
+  if (!url) { resetPicker(inputEl); return }
+
+  showFieldUploadError(fieldEl, null)
+  writeUploadLeaf(fieldEl, url, fileLike.name)
+  commit(extractFormData(ctx), { path: pathStr, structural: false }, ctx)
+  resetPicker(inputEl)
+}
+
+// The × on an upload widget. Clears the bound leaf to empty and commits, so the
+// :has()-driven chrome falls back to the empty state. Removes immediately (no
+// consent gate) per the approved design; distinct from the "remove" action,
+// which deletes a whole array item.
+export function onClearUpload(actionEl, ctx) {
+  const fieldEl = actionEl.closest('[data-hcms-path]')
+  if (!fieldEl) return
+  const pathStr = fieldEl.getAttribute('data-hcms-path') || ''
+  writeUploadLeaf(fieldEl, '', '')
+  const input = fieldEl.querySelector('input[type="file"][data-hcms-upload]')
+  if (input) resetPicker(input)
+  showFieldUploadError(fieldEl, null)
+  commit(extractFormData(ctx), { path: pathStr, structural: false }, ctx)
+}
+
+function findUploadLeaf(fieldEl) {
+  return fieldEl.querySelector
+    ? fieldEl.querySelector('img[data-hcms-field], a[data-hcms-field]')
+    : null
+}
+
+// Write a URL into the widget's bound leaf: an <img>'s src, or an <a>'s href
+// plus its visible filename text. Empty url clears to the empty state.
+function writeUploadLeaf(fieldEl, url, fileName) {
+  const leaf = findUploadLeaf(fieldEl)
+  if (!leaf) return
+  const tag = (leaf.tagName || '').toUpperCase()
+  if (tag === 'IMG') {
+    leaf.src = url || ''
+  } else if (tag === 'A') {
+    leaf.href = url || ''
+    leaf.textContent = url ? (fileName || fileNameFromUrl(url)) : ''
+  }
+}
+
+function resetPicker(inputEl) {
+  // Clear the selection so re-picking the same file fires `change` again.
+  try { inputEl.value = '' } catch { /* some inputs reject programmatic clear */ }
+}
+
+function makeLocalPreviewUrl(file) {
+  const U = (typeof URL !== 'undefined' && URL.createObjectURL) ? URL : null
+  if (!U) return ''
+  try { return U.createObjectURL(file) } catch { return '' }
+}
+
+function showFieldUploadError(fieldEl, message) {
+  const slot = fieldEl.querySelector ? fieldEl.querySelector(':scope > .hcms-error') : null
+  if (!slot) return
+  if (message) {
+    slot.textContent = message
+    slot.hidden = false
+  } else {
+    slot.textContent = ''
+    slot.hidden = true
+  }
 }
 
 export function onAdd(arrayPath, ctx) {
@@ -186,6 +354,51 @@ export function onMove(itemEl, direction, ctx) {
   )
 }
 
+const DEFAULT_CONFIRM_REMOVE = 'Delete this item?'
+
+// Resolve whether removing an item from `arrayEl` should confirm first, and with
+// what prompt. Most specific wins: a per-array `data-hcms-confirm-remove`
+// attribute (a string overrides the prompt; "off"/"false"/"no"/"0" disables that
+// one array), then the global `confirmRemove` open() option (a string overrides
+// the prompt, true forces every list, false disables everything), then the
+// built-in default. The default confirms card removals (object-array items hold
+// several fields) and leaves scalar-array chips instant. Returns the prompt to
+// confirm with, or null to remove without asking.
+function resolveRemoveConfirm(arrayEl, ctx) {
+  const attr = arrayEl && arrayEl.getAttribute('data-hcms-confirm-remove')
+  if (attr != null) {
+    if (/^(off|false|no|0)$/i.test(attr.trim())) return null
+    return attr || DEFAULT_CONFIRM_REMOVE
+  }
+  const global = ctx && ctx.confirmRemove
+  if (global === false) return null
+  if (typeof global === 'string') return global || DEFAULT_CONFIRM_REMOVE
+  if (global === true) return DEFAULT_CONFIRM_REMOVE
+  return arrayEl && arrayEl.getAttribute('data-hcms-shape') === 'object-array'
+    ? DEFAULT_CONFIRM_REMOVE
+    : null
+}
+
+// Built-in delete confirmation: every list-item removal routes through here so
+// the policy applies uniformly. Confirmation uses hyperclay's consent() (the
+// styled modal) when the host page provides it, falls back to native confirm(),
+// and proceeds when neither exists (non-browser). Programmatic api.removeItem()
+// bypasses this by calling onRemove directly, the way undo treats deliberate
+// actions.
+export function requestRemove(itemEl, ctx) {
+  const arrayEl = itemEl.closest('[data-hcms-shape="object-array"], [data-hcms-shape="scalar-array"]')
+  const message = resolveRemoveConfirm(arrayEl, ctx)
+  if (message == null) return onRemove(itemEl, ctx)
+  const consent = typeof window !== 'undefined' && (window.hyperclay?.consent || window.consent)
+  if (typeof consent === 'function') {
+    Promise.resolve(consent(message)).then(() => onRemove(itemEl, ctx), () => {})
+  } else if (typeof window !== 'undefined' && typeof window.confirm === 'function') {
+    if (window.confirm(message)) onRemove(itemEl, ctx)
+  } else {
+    onRemove(itemEl, ctx)
+  }
+}
+
 export function onRemove(itemEl, ctx) {
   const path = itemEl.getAttribute('data-hcms-path') || ''
   const parent = itemEl.parentElement
@@ -208,12 +421,6 @@ export function onRemove(itemEl, ctx) {
   )
 }
 
-export function onSave(ctx) {
-  const data = extractFormData(ctx)
-  ctx.dispatch?.('hcms:save', { data })
-  ctx.onSave?.(data)
-}
-
 export function commit(newData, info, ctx) {
   const fingerprint = stableStringify(newData)
   if (fingerprint === ctx.lastFingerprint) return { ok: true, skipped: true }

package/src/form-builder.js

@@ -3,9 +3,23 @@ import {
   isInlineTemplate,
   humanize,
   shapeKindOf,
+  componentForScalarRule,
 } from './templates.js'
 import { fieldPropertyFor } from './form-rules.js'
 
+// The visible label for a file field is the basename of its URL value; the
+// bound leaf still carries the full URL in href so it round-trips byte-stable.
+export function fileNameFromUrl(url) {
+  if (!url) return ''
+  const clean = String(url).split(/[?#]/)[0]
+  const base = clean.split('/').pop() || clean
+  try {
+    return decodeURIComponent(base)
+  } catch {
+    return base
+  }
+}
+
 export function buildForm({ pageRules, formRules: _formRules, data, doc }) {
   const fragment = doc.createDocumentFragment()
   const root = buildNode(pageRules, [], data, doc)
@@ -25,15 +39,19 @@ export function buildItem({ shape, itemShape, pathArr, data, doc }) {
 
 function buildNode(rule, pathArr, data, doc) {
   const kind = shapeKindOf(rule)
-  if (kind === 'scalar') return buildScalar(pathArr, data, doc)
+  if (kind === 'scalar') return buildScalar(rule, pathArr, data, doc)
   if (kind === 'object') return buildObject(rule, pathArr, data, doc)
   if (kind === 'object-array') return buildObjectArray(rule, pathArr, data, doc)
   if (kind === 'scalar-array') return buildScalarArray(rule, pathArr, data, doc)
   return null
 }
 
-function buildScalar(pathArr, data, doc) {
-  const tpl = resolveTemplate(pathArr, '@scalar', doc)
+function buildScalar(rule, pathArr, data, doc) {
+  // Opt-in upload components select a richer template (@image/@file) off the
+  // bound rule's @prop suffix; plain scalars stay @scalar. A path-bound
+  // template override still wins inside resolveTemplate.
+  const componentKey = componentForScalarRule(rule, doc)
+  const tpl = resolveTemplate(pathArr, componentKey, doc)
   if (!tpl) throw new Error(`hypercms: missing template for scalar at "${pathArr.join('.')}"`)
   const node = cloneTemplate(tpl, doc)
   stampPath(node, pathArr)
@@ -45,9 +63,20 @@ function buildScalar(pathArr, data, doc) {
   stampContainerField(node, lastKey(pathArr))
   setLabel(node, lastKey(pathArr))
   populateScalarValue(node, data)
+  if (componentKey === '@file') syncFileLeafText(node)
   return node
 }
 
+// The @file leaf is an <a> whose value is the href; populateScalarValue sets
+// href but not the visible text, so derive the filename here. Empty href leaves
+// the anchor empty, which the theme's :empty placeholder dresses as "No file
+// chosen". Scoped to the default chrome's .mirk-file__name so author overrides
+// keep their own text.
+function syncFileLeafText(node) {
+  const a = node.querySelector ? node.querySelector('a.mirk-file__name[data-hcms-field]') : null
+  if (a) a.textContent = fileNameFromUrl(a.getAttribute('href'))
+}
+
 function buildObject(rule, pathArr, data, doc) {
   const tpl = resolveTemplate(pathArr, '@object', doc)
   if (!tpl) throw new Error(`hypercms: missing template for object at "${pathArr.join('.')}"`)

package/src/form-rules.js

@@ -1,4 +1,4 @@
-import { shapeKindOf, findTemplate, isInlineTemplate } from './templates.js'
+import { shapeKindOf, findTemplate, isInlineTemplate, componentForScalarRule } from './templates.js'
 
 const TAG_PROP_MAP = {
   IMG: 'src',
@@ -99,10 +99,12 @@ export function deriveFormRules(pageRules, doc) {
     const fieldKey = typeof key === 'string' ? key : '__value'
     const inlineEl = findInlineFieldEl(pathArr, fieldKey)
     if (inlineEl) return fieldSelectorFor(inlineEl, fieldKey)
-    // No path-bound override: look up the actual @scalar template (which
-    // sites may override globally with e.g. <textarea>) and derive the
-    // selector from its leaf tag instead of assuming <input>.
-    const shapeEl = findShapeFieldEl('@scalar', 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), fieldKey)
     if (shapeEl) return fieldSelectorFor(shapeEl, fieldKey)
     return `input[data-hcms-field="${cssEscape(fieldKey)}"]@value`
   }

package/src/hypercms-bundle.js

@@ -1,7 +1,10 @@
 import * as core from './hypercms.js'
-import stylesText from './styles.css'
+import themeText from './theme.generated.css'
+// Install mirk's delegated component runtime (tags chips, number stepper, etc.)
+// as a side effect. Idempotent + document-delegated, so safe to include once.
+import './vendor/mirk.vendor.js'
 
-core.installStyles(stylesText)
+core.installStyles(themeText)
 
 export const cms = core.cms
 export default { cms: core.cms }