phlex-reactive 0.12.5 → 0.13.0

data/app/javascript/phlex/reactive/reactive_controller.js

@@ -1055,6 +1055,331 @@ function runTransition(el, transition, flip) {
   setTimeout(cleanup, 350)
 }
 
+// ---------------------------------------------------------------------------
+// Client-only drafts (issue #239) — reactive_persist. A root that declares
+// data-reactive-persist='{"key","ttl","debounce"[,"fields"][,"restore"]}'
+// keeps a localStorage draft of every persistable OWNED control (write on
+// input/change, restore on connect, clear on a successful submit / TTL / the
+// persist_clear op). The storage layer is MODULE-LEVEL and keyed on the root
+// element — the controller's connect/write path and the persist_state /
+// persist_clear client ops (which receive only the element) share it. Every
+// storage access is try/catch'd: a private window, a quota error or blocked
+// storage degrades to "no draft", never a thrown bootstrap. Nothing here
+// leaves the browser: no token, no POST, and phlex-reactive never writes
+// markup into the DOM: native controls are replayed via
+// .value/.checked/.selected, a bare [contenteditable] via textContent, and a
+// rich editor (lexxy-editor, trix-editor — issue #241) through its OWN
+// `value` setter, the same sanitizing import path a paste takes. Never
+// innerHTML.
+// ---------------------------------------------------------------------------
+const PERSIST_VERSION = 1
+const PERSIST_PREFIX = "phlex-reactive:persist:"
+// Never persisted regardless of author intent: no server default to restore
+// into (hidden, file), secrets (password), and non-value controls.
+const PERSIST_EXCLUDED_TYPES = new Set(["hidden", "file", "password", "submit", "button", "reset", "image"])
+const PERSIST_STATE_ATTR = "data-reactive-persist-state"
+// The editor query #collectFields reads (minus the [name] guard — an editor's
+// name may live on its IDL `name` getter: Trix's `input=`-paired hidden input).
+const PERSIST_EDITOR_SELECTOR =
+  ":is(lexxy-editor, trix-editor, [contenteditable=''], [contenteditable=true], [contenteditable=plaintext-only])"
+const PERSIST_EDITOR_TAGS = new Set(["lexxy-editor", "trix-editor"])
+// An editor's own chrome: Lexxy renders its toolbar (a `lexxy-code-language`
+// select, the link dialog's `href` input) INSIDE <lexxy-editor>, Trix as a
+// sibling <trix-toolbar>. Those are named native controls that are not the
+// user's fields — never drafted, never restored into.
+const PERSIST_EDITOR_CHROME = "lexxy-editor, trix-editor, trix-toolbar"
+// The editors' own bubbling change events — the keystroke signal for the
+// draft write, since neither lets its contenteditable's native `input` bubble.
+const PERSIST_EDITOR_CHANGE_EVENTS = ["lexxy:change", "trix-change"]
+// "Is this editor empty" when it exposes no predicate of its own (Lexxy's
+// `isEmpty`, Trix's `editor.getDocument().isEmpty()`): Lexxy's own empty
+// list plus the Trix / contenteditable empties. Exact strings, no HTML
+// parsing — an attachment-only body stays non-blank.
+const PERSIST_EMPTY_HTML = new Set(["", "<p></p>", "<p><br></p>", "<div><br></div>"])
+// Once-per-root guards: a malformed payload warns once; the storage-failure
+// and editor-restore dev notes (debug mode only) print once each.
+const persistPayloadWarned = new WeakSet()
+const persistFailureNoted = new WeakSet()
+const persistEditorNoted = new WeakSet()
+
+// The root's parsed payload, or null (undeclared / malformed → warned once).
+// A control-level "off" (reactive_persist_skip) is never a root payload.
+function persistPayload(root) {
+  const raw = root?.getAttribute?.("data-reactive-persist")
+  if (!raw || raw === "off") return null
+  try {
+    const payload = JSON.parse(raw)
+    if (payload && typeof payload === "object" && typeof payload.key === "string" && payload.key !== "") return payload
+  } catch {
+    // fall through to the warn
+  }
+  if (!persistPayloadWarned.has(root)) {
+    persistPayloadWarned.add(root)
+    console.warn(`[phlex-reactive] malformed reactive_persist payload ${JSON.stringify(raw)} — persistence disabled`)
+  }
+  return null
+}
+
+function persistStorage() {
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage
+  } catch {
+    return null // the accessor itself can throw (blocked site data)
+  }
+}
+
+// The dev lens for "why did nothing come back": ONLY under data-reactive-debug
+// (Phlex::Reactive.debug), once per root — production stays silent.
+function persistNoteFailure(root, error) {
+  if (root?.getAttribute?.("data-reactive-debug") !== "true" || persistFailureNoted.has(root)) return
+  persistFailureNoted.add(root)
+  console.info(`[phlex-reactive] reactive_persist: storage unavailable — draft skipped (${error?.name ?? error})`)
+}
+
+function persistKeyFor(payload) {
+  return PERSIST_PREFIX + payload.key
+}
+
+// Read + validate the draft: null when absent, unparsable, another schema
+// version, or expired (an expired draft is REMOVED on read). Returns
+// { fields, state } with state null when the draft carries none.
+function persistRead(root, payload) {
+  const store = persistStorage()
+  if (!store) return null
+  let raw
+  try {
+    raw = store.getItem(persistKeyFor(payload))
+  } catch (error) {
+    persistNoteFailure(root, error)
+    return null
+  }
+  if (!raw) return null
+  let draft
+  try {
+    draft = JSON.parse(raw)
+  } catch {
+    return null
+  }
+  if (!draft || typeof draft !== "object" || draft.v !== PERSIST_VERSION) return null
+  const ttlMs = Number(payload.ttl) * 1000
+  if (!(Number(draft.savedAt) + ttlMs > Date.now())) {
+    persistRemove(root, payload)
+    return null
+  }
+  const fields = draft.fields && typeof draft.fields === "object" ? draft.fields : {}
+  const state = draft.state && typeof draft.state === "object" ? draft.state : null
+  return { fields, state }
+}
+
+function persistWrite(root, payload, { fields, state }) {
+  const store = persistStorage()
+  if (!store) return false
+  const draft = { v: PERSIST_VERSION, savedAt: Date.now(), fields }
+  if (state) draft.state = state
+  try {
+    store.setItem(persistKeyFor(payload), JSON.stringify(draft))
+    return true
+  } catch (error) {
+    persistNoteFailure(root, error)
+    return false
+  }
+}
+
+function persistRemove(root, payload) {
+  root?.removeAttribute?.(PERSIST_STATE_ATTR)
+  const store = persistStorage()
+  if (!store) return
+  try {
+    store.removeItem(persistKeyFor(payload))
+  } catch (error) {
+    persistNoteFailure(root, error)
+  }
+}
+
+// The persistable controls this root OWNS (#15: a nested reactive root's
+// controls are its own), minus the excluded types, the reactive_persist_skip
+// marker, and — when `fields` narrows the set — any undeclared name. Each
+// entry is { el, name, kind } with kind "native" (input/select/textarea),
+// "editor" (lexxy-editor / trix-editor) or "contenteditable" (a bare named
+// editable element) — issue #241.
+function persistControls(root, payload) {
+  const allow = Array.isArray(payload.fields) ? new Set(payload.fields) : null
+  const out = []
+  const owned = (el) =>
+    el.closest('[data-controller~="reactive"]') === root && el.getAttribute("data-reactive-persist") !== "off"
+  for (const el of root.querySelectorAll("input[name], select[name], textarea[name]")) {
+    if (!owned(el) || PERSIST_EXCLUDED_TYPES.has(el.type) || el.closest(PERSIST_EDITOR_CHROME)) continue
+    if (allow && !allow.has(el.name)) continue
+    out.push({ el, name: el.name, kind: "native" })
+  }
+  for (const el of root.querySelectorAll(PERSIST_EDITOR_SELECTOR)) {
+    if (!owned(el)) continue
+    const name = persistEditorName(el)
+    if (!name || (allow && !allow.has(name))) continue
+    out.push({ el, name, kind: PERSIST_EDITOR_TAGS.has(el.localName) ? "editor" : "contenteditable" })
+  }
+  return out
+}
+
+// The attribute first (Lexxy, a bare contenteditable — which has no `name`
+// IDL property at all), then the IDL getter (Trix resolves it through its
+// `input=`-paired hidden input, which is itself excluded as type=hidden).
+function persistEditorName(el) {
+  return el.getAttribute("name") || (typeof el.name === "string" && el.name) || null
+}
+
+// An editor is READY once its custom element has upgraded and connected: only
+// then does it expose the string `value` accessor (Lexxy's setter throws
+// before connectedCallback created its editor; Trix's discards the value).
+function persistEditorReady(el) {
+  return typeof el.value === "string"
+}
+
+// Ask the editor whether it is empty (Lexxy `isEmpty`; Trix
+// `editor.getDocument().isEmpty()`), else the exact-string fallback. An
+// attachment-only server body is therefore NON-blank and never overwritten.
+function persistEditorBlank(el) {
+  if (typeof el.isEmpty === "boolean") return el.isEmpty
+  const doc = el.editor?.getDocument?.()
+  if (typeof doc?.isEmpty === "function") return doc.isEmpty()
+  return PERSIST_EMPTY_HTML.has(el.value.trim())
+}
+
+// The editor-restore dev lens: ONLY under data-reactive-debug, once per root.
+function persistNoteEditorFailure(root, name, error) {
+  if (root?.getAttribute?.("data-reactive-debug") !== "true" || persistEditorNoted.has(root)) return
+  persistEditorNoted.add(root)
+  console.info(
+    `[phlex-reactive] reactive_persist: could not restore editor ${JSON.stringify(name)} — ${error?.message ?? error}`,
+  )
+}
+
+function persistSelectMultiple(el) {
+  return el.tagName === "SELECT" && el.multiple
+}
+
+// Snapshot the owned controls: radio → the checked value (null when the group
+// has none, so a restore leaves it alone), checkbox → checked, multi-select →
+// the selected values, a rich editor → its serialized `value` (omitted while
+// the element hasn't upgraded — never a phantom ""), a bare contenteditable →
+// its textContent, else .value. Mirrors #collectFields' reads.
+function persistSnapshot(root, payload) {
+  const fields = {}
+  for (const { el, name, kind } of persistControls(root, payload)) {
+    if (kind === "editor") {
+      if (persistEditorReady(el)) fields[name] = el.value
+    } else if (kind === "contenteditable") {
+      fields[name] = el.textContent ?? ""
+    } else if (el.type === "radio") {
+      if (el.checked) fields[name] = el.value
+      else if (!Object.hasOwn(fields, name)) fields[name] = null
+    } else if (el.type === "checkbox") {
+      fields[name] = el.checked
+    } else if (persistSelectMultiple(el)) {
+      fields[name] = [...el.options].filter((o) => o.selected).map((o) => o.value)
+    } else {
+      fields[name] = el.value
+    }
+  }
+  return fields
+}
+
+// Replay the draft into the owned controls. Default (restore: blank): a
+// control the server rendered NON-BLANK keeps its value — a 422 re-render's
+// submitted values beat an older draft. restore: "always" lets the draft win.
+// Values land via .value/.checked/.selected, textContent, or the editor's own
+// `value` setter — never HTML written by us.
+function persistApply(root, payload, fields) {
+  const always = payload.restore === "always"
+  const controls = persistControls(root, payload)
+  for (const { el, name, kind } of controls) {
+    if (!Object.hasOwn(fields, name)) continue
+    const value = fields[name]
+    if (value === null || value === undefined) continue
+    if (kind === "editor") {
+      persistApplyEditor(root, el, name, value, always)
+    } else if (kind === "contenteditable") {
+      if (!always && (el.textContent ?? "").trim() !== "") continue
+      el.textContent = String(value)
+    } else if (el.type === "radio") {
+      if (!always && controls.some((c) => c.kind === "native" && c.el.type === "radio" && c.name === name && c.el.checked)) continue
+      el.checked = el.value === String(value)
+    } else if (el.type === "checkbox") {
+      if (!always && el.checked) continue
+      el.checked = Boolean(value)
+    } else if (persistSelectMultiple(el)) {
+      if (!always && [...el.options].some((o) => o.selected)) continue
+      const wanted = new Set((Array.isArray(value) ? value : [value]).map(String))
+      for (const o of el.options) o.selected = wanted.has(o.value)
+    } else {
+      if (!always && el.value !== "") continue
+      el.value = String(value)
+    }
+  }
+  persistDeferEditors(root, payload, fields)
+}
+
+// A ready editor takes the value through its own setter; the setter is the
+// editor's sanitizing import (Trix HTMLParser, Lexxy $generateNodesFromDOM +
+// sanitizer). A throw (Lexxy before its editor exists) never escapes connect.
+function persistApplyEditor(root, el, name, value, always) {
+  if (!persistEditorReady(el)) return // not upgraded yet — persistDeferEditors re-applies after define
+  if (!always && !persistEditorBlank(el)) return
+  try {
+    el.value = String(value)
+  } catch (error) {
+    persistNoteEditorFailure(root, name, error)
+  }
+}
+
+// An editor whose custom element is not defined yet (Trix defines its elements
+// in a setTimeout after load; a lazily imported Lexxy) cannot take a value now.
+// Re-apply per TAG once it is defined — re-querying the controls (the upgrade
+// may replace the node) and re-checking restore: blank at that moment — unless
+// the root has left the document meanwhile.
+function persistDeferEditors(root, payload, fields) {
+  const registry = globalThis.customElements
+  if (typeof registry?.whenDefined !== "function") return
+  const pending = new Set()
+  for (const el of root.querySelectorAll("lexxy-editor, trix-editor")) {
+    if (!persistEditorReady(el) && !registry.get?.(el.localName)) pending.add(el.localName)
+  }
+  const always = payload.restore === "always"
+  for (const tag of pending) {
+    registry.whenDefined(tag).then(() => {
+      if (!root.isConnected) return
+      for (const { el, name, kind } of persistControls(root, payload)) {
+        if (kind !== "editor" || el.localName !== tag || !Object.hasOwn(fields, name)) continue
+        const value = fields[name]
+        if (value === null || value === undefined) continue
+        persistApplyEditor(root, el, name, value, always)
+      }
+    })
+  }
+}
+
+// The persist_state op body: merge a FLAT bag into the root's draft (re-
+// snapshotting the fields so the write is whole) and mirror it on the root.
+// A root without reactive_persist is a call-site bug — warn and skip.
+function persistWriteState(root, state) {
+  const payload = persistPayload(root)
+  if (!payload) {
+    console.warn("[phlex-reactive] persist_state on a root without reactive_persist — skipped")
+    return
+  }
+  if (!state || typeof state !== "object") return
+  const current = persistRead(root, payload)
+  const merged = { ...(current?.state ?? {}), ...state }
+  if (persistWrite(root, payload, { fields: persistSnapshot(root, payload), state: merged })) {
+    root.setAttribute?.(PERSIST_STATE_ATTR, JSON.stringify(merged))
+  }
+}
+
+function persistClearRoot(root) {
+  const payload = persistPayload(root)
+  if (payload) persistRemove(root, payload)
+}
+
 // The client-op whitelist behind on_client (issue #95, extended in #96). Mirrors
 // Phlex::Reactive::JS's vocabulary; an op name not in this map is
 // warn-and-skipped by #applyOps (client-side default-deny — a stale or newer
@@ -1131,6 +1456,13 @@ const CLIENT_OPS = Object.freeze({
   // an actor reply's stream from a broadcast's, and reply.js legitimately
   // carries this op.
   paste_into: (el) => pasteClipboardInto(el),
+
+  // Client-only drafts (issue #239): merge a flat state bag into the root's
+  // reactive_persist draft / forget the draft. ACTOR-ONLY like focus/submit
+  // (BROADCAST_REFUSED_OPS server-side) — rewriting or wiping every
+  // subscriber's draft from a broadcast would be hostile.
+  persist_state: (el, args) => persistWriteState(el, args.state),
+  persist_clear: (el) => persistClearRoot(el),
 })
 
 // The form a submit op commits (issue #226), in order: the target itself when
@@ -1675,6 +2007,17 @@ export default class extends Controller {
   // Clipboard-trigger availability gate (issue #228): the bound morph re-sync,
   // held for teardown.
   #boundSyncClipboard
+  // Client-only drafts (issue #239): the parsed root payload (null when
+  // undeclared), the restore-complete latch (no write may run before the
+  // connect restore — a connect must never overwrite a draft with server
+  // blanks), the ONE per-root trailing-edge write timer, and the bound
+  // input/change/turbo:submit-end handlers held for teardown.
+  #persistConfig = null
+  #persistRestored = false
+  #persistTimer = null
+  #boundPersistInput
+  #boundPersistChange
+  #boundPersistSubmitEnd
 
   // Mark that a reactive controller actually connected, so the registration
   // guard above knows the controller was registered (issue #26 part 2).
@@ -1716,6 +2059,18 @@ export default class extends Controller {
       this.element.addEventListener?.("turbo:morph-element", this.#boundProbeLazyDefer)
     }
 
+    // Client-only drafts (issue #239) — ONLY when the root declares
+    // data-reactive-persist (one attribute read otherwise). Runs FIRST among
+    // the feature blocks ON PURPOSE: the restore writes the draft into the
+    // owned controls, and every later connect seed (dirty baseline, show,
+    // on-complete's arm-without-fire, filter, tags, nested-json, the compute
+    // self-seed) then reads the restored DOM naturally — no synthetic
+    // input/change events (which would FIRE reactive_on_complete bindings and
+    // reducer $ops on page load). Restore is connect-only: a
+    // turbo:morph-element is server truth arriving, never re-restored.
+    this.#persistConfig = persistPayload(this.element)
+    if (this.#persistConfig) this.#connectPersist()
+
     // Dirty tracking (issue #103) — ONLY when this root opts in (track_dirty: or a
     // reactive_field(dirty:)), so a component that never uses it pays nothing (no
     // baseline scan, no morph listener on every broadcast). A plain (outerHTML)
@@ -1895,6 +2250,10 @@ export default class extends Controller {
   // leading-edge timer holds no pending POST, but leaving it running would leak
   // it past the element's life.
   disconnect() {
+    // Persist FIRST: flush a pending draft write while the fields are still
+    // readable (Turbo disconnects before leaving the page — a fast visit
+    // otherwise loses the last keystrokes).
+    this.#teardownPersist()
     this.#clearAllDebounces()
     this.#clearAllThrottles()
     this.#teardownDirtyTracking()
@@ -3978,6 +4337,92 @@ export default class extends Controller {
 
   // Remove the show-sync listeners on disconnect, so a stray event after a
   // Turbo morph/navigation never re-evaluates against a detached root.
+  // Client-only drafts (issue #239): restore the draft into the owned
+  // controls, expose the state bag, announce, then arm the write listeners.
+  // The restore reads ONCE and never writes back — the restored latch stays
+  // false until it completes, so no listener can clobber the draft with the
+  // server's blanks. The submit-end listener is DOCUMENT-level (the event
+  // fires on the form, which is usually an ANCESTOR of this root) and gated
+  // on the form containing this root.
+  #connectPersist() {
+    const payload = this.#persistConfig
+    this.#persistRestored = false
+    const draft = persistRead(this.element, payload)
+    if (draft) {
+      persistApply(this.element, payload, draft.fields)
+      if (draft.state) this.element.setAttribute?.(PERSIST_STATE_ATTR, JSON.stringify(draft.state))
+      this.#emit("reactive:persist-restored", { key: payload.key, fields: draft.fields, state: draft.state ?? {} })
+    }
+    this.#persistRestored = true
+
+    this.#boundPersistInput = () => this.#schedulePersistWrite()
+    this.#boundPersistChange = () => this.#persistWriteNow()
+    this.#boundPersistSubmitEnd = (event) => this.#persistSubmitEnd(event)
+    this.element.addEventListener?.("input", this.#boundPersistInput)
+    this.element.addEventListener?.("change", this.#boundPersistChange)
+    // Rich editors (#241): Lexical and Trix swallow the native `input` of
+    // their contenteditable, so their own bubbling change events are the
+    // keystroke signal — same trailing-edge debounce as `input`.
+    for (const event of PERSIST_EDITOR_CHANGE_EVENTS) this.element.addEventListener?.(event, this.#boundPersistInput)
+    document.addEventListener?.("turbo:submit-end", this.#boundPersistSubmitEnd)
+  }
+
+  // Trailing-edge debounce for keystrokes — ONE timer per root (a snapshot is
+  // a full pass, so per-field timers would only multiply writes).
+  #schedulePersistWrite() {
+    if (!this.#persistRestored) return
+    const ms = Number(this.#persistConfig?.debounce) || 0
+    if (ms <= 0) return this.#persistWriteNow()
+    if (this.#persistTimer !== null) clearTimeout(this.#persistTimer)
+    this.#persistTimer = setTimeout(() => {
+      this.#persistTimer = null
+      this.#persistWriteNow()
+    }, ms)
+  }
+
+  // Snapshot every persistable owned control and write. Re-reads the current
+  // draft first so a state bag written by persist_state survives the write
+  // (the bag lives in storage, not on the instance — the op has no instance).
+  #persistWriteNow() {
+    if (!this.#persistRestored || !this.#persistConfig) return
+    if (this.#persistTimer !== null) {
+      clearTimeout(this.#persistTimer)
+      this.#persistTimer = null
+    }
+    const payload = this.#persistConfig
+    const current = persistRead(this.element, payload)
+    persistWrite(this.element, payload, { fields: persistSnapshot(this.element, payload), state: current?.state ?? null })
+  }
+
+  // A SUCCESSFUL Turbo form submission of the form that owns this root
+  // forgets the draft. tagName (not instanceof) so a cross-realm form counts.
+  #persistSubmitEnd(event) {
+    if (!event?.detail?.success) return
+    const form = event.target
+    if (form?.tagName !== "FORM" || typeof form.contains !== "function") return
+    if (!form.contains(this.element)) return
+    // Drop a pending keystroke write too — the disconnect flush that follows
+    // Turbo's redirect visit would otherwise resurrect the just-cleared draft.
+    if (this.#persistTimer !== null) {
+      clearTimeout(this.#persistTimer)
+      this.#persistTimer = null
+    }
+    persistRemove(this.element, this.#persistConfig)
+  }
+
+  // Flush a pending write, then drop every listener (disconnect()).
+  #teardownPersist() {
+    if (!this.#persistConfig) return
+    if (this.#persistTimer !== null) this.#persistWriteNow()
+    this.element.removeEventListener?.("input", this.#boundPersistInput)
+    this.element.removeEventListener?.("change", this.#boundPersistChange)
+    for (const event of PERSIST_EDITOR_CHANGE_EVENTS) this.element.removeEventListener?.(event, this.#boundPersistInput)
+    document.removeEventListener?.("turbo:submit-end", this.#boundPersistSubmitEnd)
+    this.#boundPersistInput = this.#boundPersistChange = this.#boundPersistSubmitEnd = undefined
+    this.#persistConfig = null
+    this.#persistRestored = false
+  }
+
   #teardownShowSync() {
     if (!this.#boundSyncShow) return
     this.element.removeEventListener?.("input", this.#boundSyncShow)