@panphora/hyper-cms 0.7.2 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/hyper-cms",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "description": "Live edit-in-place CMS sidebar for HTML pages with a hyper-html-api rules tag",
   "keywords": [
     "HTML",
@@ -13,7 +13,7 @@
   "bugs": {
     "url": "https://github.com/panphora/hypercms/issues"
   },
-  "license": "0BSD",
+  "license": "MIT-0",
   "author": "David Miranda",
   "type": "module",
   "main": "src/hypercms.js",
@@ -44,7 +44,7 @@
     "test:all": "npm run test:node && npm run test:browser"
   },
   "dependencies": {
-    "hyper-html-api": "^0.6.4",
+    "hyper-html-api": "^0.6.5",
     "hyper-morph": "^0.5.0"
   },
   "devDependencies": {

package/src/events.js

@@ -190,7 +190,12 @@ async function maybeCrop(file, fieldEl) {
   const crop = platform('quickcrop')
   if (typeof crop !== 'function') return { file }
   try {
-    const r = await crop(file, { aspect: parseCropAspect(attr), ...CROP_OUTPUT })
+    // QuickCrop's `auto` modal adapter looks only at window.themodal. clayjs
+    // attaches its dialog as clay.modal and deliberately sets no global, so a
+    // clayjs page would silently get QuickCrop's own plain dialog. Naming it here
+    // keeps QuickCrop free of client knowledge and clayjs free of the global.
+    const modal = (typeof window !== 'undefined' && (window.clay?.modal ?? window.themodal)) || 'auto'
+    const r = await crop(file, { aspect: parseCropAspect(attr), modal, ...CROP_OUTPUT })
     if (r === null) return null
     return { file: blobToFile(r.blob, file.name), dataURL: r.dataURL }
   } catch (err) {
@@ -212,8 +217,8 @@ export function parseCropAspect(value) {
   return w / h
 }
 
-// quickcrop returns a nameless Blob; uploadFileBasic rejects raw Blobs and the
-// server keys content-type off the filename extension, so wrap it as a File
+// quickcrop returns a nameless Blob; the legacy uploader rejects raw Blobs and a
+// host keys content-type off the filename extension, so wrap it as a File
 // whose extension matches the encoded mime. Exported for tests.
 export function blobToFile(blob, originalName) {
   const ext = blob.type === 'image/webp' ? '.webp' : blob.type === 'image/jpeg' ? '.jpg' : '.png'
@@ -225,11 +230,25 @@ export function blobToFile(blob, originalName) {
   }
 }
 
-// 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.
+// A file was picked in an @file/@image widget. Optionally crop, ask the host to
+// store the file, 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.
+//
+// The upload either stores the file or it does not, and those are not the same
+// as success and failure. Three outcomes, deliberately spelled out:
+//
+//   stored             write the served URL. The page carries a reference.
+//   cannot store here  embed the bytes. A document open from a plain file server
+//                      or a desktop app has nowhere to put a file, and embedding
+//                      is the RIGHT answer there, not a consolation prize.
+//   failed             write nothing. Embedding a file the host refused for size
+//                      or type is the disease this capability exists to cure: it
+//                      is how a 2 MB photo ends up in the document, in every
+//                      future save, and in every stored version.
+const EMBED_CODES = new Set(['unsupported', 'payment-required'])
+
 export async function onUploadChange(inputEl, ctx) {
   const file = inputEl.files && inputEl.files[0]
   if (!file) return
@@ -246,39 +265,112 @@ export async function onUploadChange(inputEl, ctx) {
   const fileLike = cropped.file
   const previewDataUrl = cropped.dataURL || null
 
-  const upload = platform('uploadFileBasic')
-  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
-    }
+  const upload = platform('upload')
+  if (typeof upload !== 'function') {
+    // No client at all: a bare HTML file with the CMS dropped in. Same outcome as
+    // a host that answers `unsupported`, and silent for the same reason.
+    return finishUpload(inputEl, fieldEl, ctx, pathStr, await embedUrl(fileLike, previewDataUrl, fieldEl), fileLike)
+  }
+
+  // The crop, shown immediately on the thumb's own chrome and NOT on the bound
+  // leaf. Writing a two-megabyte data URL to the leaf makes it the field's value,
+  // and any commit() landing while the upload is in flight would project it
+  // straight into the live page.
+  showFieldUploadPreview(fieldEl, previewDataUrl)
+  setUploadProgress(fieldEl, 0)
+
+  const controller = beginUpload(ctx)
+  let res
+  try {
+    res = await upload(fileLike, {
+      signal: controller?.signal,
+      onProgress: ({ percent }) => setUploadProgress(fieldEl, percent),
+    })
+  } finally {
+    endUpload(ctx, controller)
+    clearUploadProgress(fieldEl)
   }
+
   // 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 (res.code === 'aborted') { resetPicker(inputEl); return }
+
+  if (res.ok) {
+    return finishUpload(inputEl, fieldEl, ctx, pathStr, res.uploads[0].url, fileLike)
   }
-  if (!url) { resetPicker(inputEl); return }
 
+  if (!EMBED_CODES.has(res.code)) {
+    showFieldUploadError(fieldEl, res.msg || 'Upload failed')
+    ctx.dispatch?.('hcms:error', { error: new Error(res.msg || 'Upload failed'), code: res.code, path: pathStr })
+    resetPicker(inputEl)
+    return
+  }
+
+  // Embedded, and only `payment-required` says so. A person editing a file on
+  // their own desktop does not need to be told their file is a file; a person on
+  // a host that WOULD store it, for money, is being told why it did not.
+  const note = res.code === 'payment-required'
+    ? 'This file is stored in the page. Add a paid plan to upload files.'
+    : null
+  return finishUpload(inputEl, fieldEl, ctx, pathStr, await embedUrl(fileLike, previewDataUrl, fieldEl), fileLike, note)
+}
+
+// Write the URL into the leaf and commit once. `url` empty (no FileReader, an
+// unreadable file) means there is nothing to write, and writing '' would clear a
+// picture the person already had.
+//
+// The note goes on AFTER the commit, never before: a successful commit calls
+// setError(ctx, null), which clears every inline slot in the form. Writing the
+// note first leaves the person with an embedded file and no explanation of why.
+function finishUpload(inputEl, fieldEl, ctx, pathStr, url, fileLike, note = null) {
+  if (ctx.closed) { resetPicker(inputEl); return }
+  showFieldUploadPreview(fieldEl, null)
   showFieldUploadError(fieldEl, null)
+  if (!url) { resetPicker(inputEl); return }
   writeUploadLeaf(fieldEl, url, fileLike.name)
   commit(extractFormData(ctx), { path: pathStr, structural: false }, ctx)
+  if (note) showFieldUploadError(fieldEl, note, 'info')
   resetPicker(inputEl)
 }
 
+// The crop when there was one, otherwise the file's own bytes. Always a data:
+// URL and never blob:, so both paths degrade identically: a blob: URL is dead the
+// moment the page reloads, so the no-crop path used to commit a picture that
+// looked right until the person came back to it.
+async function embedUrl(fileLike, previewDataUrl, fieldEl) {
+  return previewDataUrl || (await fileToDataUrl(fileLike, fieldEl))
+}
+
+// The FileReader comes from the field's own realm, never from globalThis: a form
+// mounted into another document reads a File belonging to THAT window, and a
+// reader from a different realm rejects it.
+function fileToDataUrl(file, fieldEl) {
+  const Reader = fieldEl?.ownerDocument?.defaultView?.FileReader || globalThis.FileReader
+  if (!Reader) return Promise.resolve('')
+  return new Promise((resolve) => {
+    const reader = new Reader()
+    reader.onload = () => resolve(typeof reader.result === 'string' ? reader.result : '')
+    reader.onerror = () => resolve('')
+    try { reader.readAsDataURL(file) } catch { resolve('') }
+  })
+}
+
+// In-flight uploads hang off the ctx, so close() tears them down the same way it
+// tears down the observer and the undo subscription. Without this the request
+// keeps running after the editor is gone: harmless to the page, because every
+// write is behind a ctx.closed check, but it holds the connection and the bytes.
+function beginUpload(ctx) {
+  if (typeof AbortController !== 'function') return null
+  const controller = new AbortController()
+  ;(ctx.uploads || (ctx.uploads = new Set())).add(controller)
+  return controller
+}
+
+function endUpload(ctx, controller) {
+  if (controller) ctx.uploads?.delete(controller)
+}
+
 // 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,
@@ -319,15 +411,37 @@ function resetPicker(inputEl) {
   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 '' }
+// The at-upload-time picture, painted on the frame rather than assigned to the
+// leaf, because the leaf IS the field's value. CSS reveals the thumb while
+// [data-hcms-uploading] is set, so the preview shows even on a field that is
+// still empty.
+function showFieldUploadPreview(fieldEl, dataUrl) {
+  const frame = fieldEl.querySelector ? fieldEl.querySelector('.mirk-image__frame') : null
+  if (!frame) return
+  if (dataUrl) frame.style.backgroundImage = `url("${dataUrl.replace(/"/g, '%22')}")`
+  else frame.style.removeProperty('background-image')
+}
+
+// Progress where the person is looking. The percent drives a CSS custom property
+// rather than any markup of its own, so the templates keep their exact shape and
+// a half-finished upload cannot leave an orphan node behind in the form.
+function setUploadProgress(fieldEl, percent) {
+  const pct = Math.max(0, Math.min(100, Number(percent) || 0))
+  fieldEl.setAttribute('data-hcms-uploading', '')
+  fieldEl.style?.setProperty?.('--hcms-upload-progress', `${pct}%`)
+}
+
+function clearUploadProgress(fieldEl) {
+  fieldEl.removeAttribute('data-hcms-uploading')
+  fieldEl.style?.removeProperty?.('--hcms-upload-progress')
 }
 
-function showFieldUploadError(fieldEl, message) {
+// `kind` distinguishes a refusal from a note: 'info' is the file that WAS stored,
+// in the page, and the slot says why rather than shouting about a failure.
+function showFieldUploadError(fieldEl, message, kind = 'error') {
   const slot = fieldEl.querySelector ? fieldEl.querySelector(':scope > .hcms-error') : null
   if (!slot) return
+  slot.classList.toggle('hcms-error--info', !!message && kind === 'info')
   if (message) {
     slot.textContent = message
     slot.hidden = false

package/src/hypercms.js

@@ -339,6 +339,10 @@ export function close() {
   // 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
+  // An upload still in flight is torn down like any other subscription. The
+  // ctx.closed check above already stops it writing; this stops it running.
+  for (const controller of ctx.uploads || []) { try { controller.abort() } catch {} }
+  ctx.uploads?.clear()
   const previouslyFocused = ctx.previouslyFocused
   ctx.dispatch('hcms:close', null)
   toggleCloseParam()

package/src/platform.js

@@ -4,12 +4,11 @@
 //
 // TWO clients provide this and they disagree on names. hyperclayjs owns
 // window.hyperclay; clayjs owns window.clay and renamed things on the way past
-// (onPrepareForSave -> addDocumentTransform, consent -> confirm). clay.RichClay exists,
-// but quickcrop and uploadFileBasic have no clay equivalent at all, so image crop and
-// file upload silently degrade under clayjs. So this is a capability table
-// rather than a namespace pointer: `window.clay ?? window.hyperclay` would resolve
-// to clay, find no onPrepareForSave, and silently stop stripping the CMS's own
-// chrome out of every save.
+// (onPrepareForSave -> addDocumentTransform, consent -> confirm, uploadFileBasic ->
+// upload). So this is a capability table rather than a namespace pointer:
+// `window.clay ?? window.hyperclay` would resolve to clay, find no
+// onPrepareForSave, and silently stop stripping the CMS's own chrome out of every
+// save.
 //
 // Reads happen per call, never cached. A client can install a capability after
 // hypercms evaluates — that is the whole reason whenReady() below exists.
@@ -20,7 +19,59 @@ const CAPABILITIES = {
   consent:          (clay, hyperclay) => clay?.confirm ?? hyperclay?.consent,
   RichClay:         (clay, hyperclay) => clay?.RichClay ?? hyperclay?.RichClay,
   quickcrop:        (clay, hyperclay) => clay?.quickcrop ?? hyperclay?.quickcrop,
-  uploadFileBasic:  (clay, hyperclay) => clay?.uploadFileBasic ?? hyperclay?.uploadFileBasic,
+  upload:           (clay, hyperclay) =>
+    clay?.upload ?? (hyperclay?.uploadFileBasic ? adaptLegacyUpload(hyperclay.uploadFileBasic) : null),
+}
+
+// The one capability where the two clients differ in SHAPE and not just in name,
+// so it is normalized here rather than at the call site. clay.upload answers one
+// envelope for every outcome and never rejects; uploadFileBasic resolves on
+// success and rejects on failure. A pick handler that had to know which client it
+// was riding would grow two of every branch, and the branch that matters most is
+// the one a rejection reads wrong: "this host does not store files" is not a
+// failure, and a caller that catches it as one stops when it should have embedded.
+//
+// The legacy client has no cancellation, so `signal` is honored on the near side
+// only: an upload already in flight runs to completion, and its result is
+// discarded rather than written. That is the same outcome the caller's own
+// ctx.closed check produces, one branch earlier.
+const LEGACY_STATUS_CODES = {
+  402: 'payment-required',
+  413: 'too-large',
+  415: 'unsupported-type',
+  401: 'unauthorized',
+  403: 'forbidden',
+  404: 'not-found',
+}
+
+const aborted = () => ({ ok: false, msg: 'Upload cancelled', msgType: 'skipped', code: 'aborted', uploads: [] })
+
+function adaptLegacyUpload(uploadFileBasic) {
+  return async function upload(file, { onProgress, signal } = {}) {
+    if (signal?.aborted) return aborted()
+    try {
+      // uploadFileBasic reports a bare percent; clay reports {loaded,total,percent}.
+      // Callers draw from `percent`, which is the only field both can supply.
+      const res = await uploadFileBasic(file, {
+        onProgress: (percent) => { onProgress?.({ loaded: null, total: null, percent }) },
+      })
+      if (signal?.aborted) return aborted()
+      const uploads = (res && res.uploads) || []
+      if (typeof uploads[0]?.url !== 'string') {
+        return { ok: false, msg: 'The host accepted the file but did not say where it put it', msgType: 'error', code: 'bad-response', uploads: [] }
+      }
+      return { ok: true, msg: res.msg || 'Uploaded', msgType: res.msgType || 'success', code: res.code || null, uploads }
+    } catch (err) {
+      if (signal?.aborted) return aborted()
+      // The rejection carries the HTTP status and the raw body, so the host's own
+      // code survives the round trip and the caller branches on the reason rather
+      // than pattern-matching a message.
+      let body = {}
+      try { body = JSON.parse(err?.response || '{}') } catch { body = {} }
+      const code = body.code || LEGACY_STATUS_CODES[err?.status] || 'error'
+      return { ok: false, msg: (err && err.message) || 'Upload failed', msgType: 'error', code, uploads: [] }
+    }
+  }
 }
 
 // Pass `win` when the caller already holds a realm (a doc.defaultView from a form

package/src/theme/pixel-quiet.overrides.css

@@ -451,6 +451,41 @@ body.hcms-open.hcms-overlay { overflow: hidden; }
   color: var(--mirk-placeholder-color);
 }
 
+/* ---------- UPLOADING (spec §9) ----------
+   One attribute, [data-hcms-uploading], set on the field for as long as the host
+   has the bytes, plus --hcms-upload-progress carrying the percent. No markup of
+   its own: the templates keep their exact shape, so a half-finished upload cannot
+   leave an orphan node behind in the form. The at-upload-time picture is painted
+   on the frame as a background, never assigned to the bound <img>, because that
+   img IS the field's value and a commit landing mid-upload would write a
+   two-megabyte data URL straight into the live page. */
+.hcms-upload[data-hcms-uploading] .mirk-image__frame {
+  background-size: cover;
+  background-position: center;
+}
+/* The empty state hides the thumb, so an upload into an empty field would have
+   nowhere to show. Uploading reveals it, preview or not. */
+.hcms-upload--image[data-hcms-uploading] .mirk-image__thumb { display: inline-block; }
+.hcms-upload--image[data-hcms-uploading] .mirk-image__upload { display: none; }
+/* No × mid-flight: clearing writes the leaf empty, which says nothing about the
+   request still running and reads as a cancel that is not one. */
+.hcms-upload[data-hcms-uploading] .hcms-upload-clear { display: none; }
+
+.hcms-upload[data-hcms-uploading] .mirk-image__frame::after,
+.hcms-upload--file[data-hcms-uploading] .mirk-file::after {
+  content: "";
+  position: absolute;
+  left: 0;
+  bottom: 0;
+  height: 3px;
+  width: var(--hcms-upload-progress, 0%);
+  background: var(--mirk-bevel-fg);
+  transition: width 120ms linear;
+}
+/* The @file row has no frame to hang the bar on, so it becomes the positioning
+   context itself. */
+.hcms-upload--file[data-hcms-uploading] .mirk-file { position: relative; }
+
 /* clear-× (vendored-inert; data-hcms-action, never .mirk-*__remove). Bare × for
    @file, a pinned corner badge for @image — mirroring .hcms-remove / --card. */
 .hcms-upload-clear {
@@ -511,6 +546,13 @@ body.hcms-open.hcms-overlay { overflow: hidden; }
 .hcms-shell-error[hidden],
 .hcms-error[hidden] { display: none; }
 
+/* A note, not a refusal: the file WAS stored, in the page, and this says why it
+   is not on the host. Same slot, so there is one place a field ever speaks. */
+.hcms-error--info {
+  color: var(--mirk-mark-fg);
+  border-color: var(--mirk-input-border);
+}
+
 /* ---------- SAVE (sits at the end of the scrolling form, not pinned) ---------- */
 .hcms-shell-footer {
   display: flex;

package/src/theme.generated.css

@@ -1462,6 +1462,41 @@ body.hcms-open.hcms-overlay { overflow: hidden; }
   color: var(--mirk-placeholder-color);
 }
 
+/* ---------- UPLOADING (spec §9) ----------
+   One attribute, [data-hcms-uploading], set on the field for as long as the host
+   has the bytes, plus --hcms-upload-progress carrying the percent. No markup of
+   its own: the templates keep their exact shape, so a half-finished upload cannot
+   leave an orphan node behind in the form. The at-upload-time picture is painted
+   on the frame as a background, never assigned to the bound <img>, because that
+   img IS the field's value and a commit landing mid-upload would write a
+   two-megabyte data URL straight into the live page. */
+.hcms-upload[data-hcms-uploading] .mirk-image__frame {
+  background-size: cover;
+  background-position: center;
+}
+/* The empty state hides the thumb, so an upload into an empty field would have
+   nowhere to show. Uploading reveals it, preview or not. */
+.hcms-upload--image[data-hcms-uploading] .mirk-image__thumb { display: inline-block; }
+.hcms-upload--image[data-hcms-uploading] .mirk-image__upload { display: none; }
+/* No × mid-flight: clearing writes the leaf empty, which says nothing about the
+   request still running and reads as a cancel that is not one. */
+.hcms-upload[data-hcms-uploading] .hcms-upload-clear { display: none; }
+
+.hcms-upload[data-hcms-uploading] .mirk-image__frame::after,
+.hcms-upload--file[data-hcms-uploading] .mirk-file::after {
+  content: "";
+  position: absolute;
+  left: 0;
+  bottom: 0;
+  height: 3px;
+  width: var(--hcms-upload-progress, 0%);
+  background: var(--mirk-bevel-fg);
+  transition: width 120ms linear;
+}
+/* The @file row has no frame to hang the bar on, so it becomes the positioning
+   context itself. */
+.hcms-upload--file[data-hcms-uploading] .mirk-file { position: relative; }
+
 /* clear-× (vendored-inert; data-hcms-action, never .mirk-*__remove). Bare × for
    @file, a pinned corner badge for @image — mirroring .hcms-remove / --card. */
 .hcms-upload-clear {
@@ -1522,6 +1557,13 @@ body.hcms-open.hcms-overlay { overflow: hidden; }
 .hcms-shell-error[hidden],
 .hcms-error[hidden] { display: none; }
 
+/* A note, not a refusal: the file WAS stored, in the page, and this says why it
+   is not on the host. Same slot, so there is one place a field ever speaks. */
+.hcms-error--info {
+  color: var(--mirk-mark-fg);
+  border-color: var(--mirk-input-border);
+}
+
 /* ---------- SAVE (sits at the end of the scrolling form, not pinned) ---------- */
 .hcms-shell-footer {
   display: flex;