@invisibleloop/pulse 0.20.60 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.20.60",
+  "version": "0.21.0",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.20.60
+0.21.0

package/src/agent/guide-spec.md

@@ -120,6 +120,7 @@ export default {
 - data-event="change:mutationName" to fire on input change
 - data-action="actionName" on <form> elements only — submits pass FormData to the action
 - Do NOT use data-event on text inputs to mirror value into state — innerHTML re-renders destroy focus. Capture values from FormData in onStart or run instead.
+- **`data-preserve`** on a `<textarea>`, `<input>` or checkbox — a re-render that renders the same value as before leaves what the user typed or ticked alone (without it, any re-render resets a non-focused control to the rendered value). Use it on long-form editors and any field a re-render elsewhere on the page must not wipe; the control still follows the view when the rendered value changes. Not needed on forms that should clear after submit. Children are matched by position, so the control must keep its place: an element that appears above it (an error banner) rebuilds the field and loses the text — render an empty placeholder in that slot, or wrap the field in a `data-key` container. A focused control is never touched, and a marked field won't reset if the view re-renders the same value on purpose.
 - **`data-debounce="300"`** alongside `data-event="input:search"` — fires the mutation 300ms after the last keystroke. Use for live search, filtering. No per-spec timer code needed.
 - **`data-throttle="100"`** alongside `data-event` — fires at most once per 100ms. Use for scroll or resize-like inputs. Both attributes apply to `input` and `change` events. Value is milliseconds.
 - onSuccess AND onError are both required in every action (missing either will cause a runtime error)

package/src/runtime/index.js

@@ -598,6 +598,9 @@ function morphKeyed(cur, nxtEls) {
 }
 
 function morphAttrs(cur, nxt) {
+  // What the previous render said this form control's value/checkedness was — read before the
+  // attributes below overwrite it. data-preserve compares against it (see syncFormProperty).
+  const prevRendered = renderedFormState(cur)
   for (const { name, value } of Array.from(nxt.attributes)) {
     if (cur.getAttribute(name) !== value) {
       // Trusted Types: script[src] is a TrustedScriptURL sink
@@ -612,7 +615,7 @@ function morphAttrs(cur, nxt) {
     if (cur.tagName === 'DIALOG' && name === 'open') continue
     if (!nxt.hasAttribute(name)) cur.removeAttribute(name)
   }
-  syncFormProperty(cur, nxt)
+  syncFormProperty(cur, nxt, prevRendered)
 }
 
 /**
@@ -631,17 +634,31 @@ function morphAttrs(cur, nxt) {
  * has its own guidance (use FormData, not a controlled value) but this
  * covers every other legitimate re-render source.
  */
-function syncFormProperty(cur, nxt) {
+function renderedFormState(el) {
+  const tag = el.tagName
+  if (tag === 'TEXTAREA') return el.textContent
+  if (tag === 'INPUT') return (el.type === 'checkbox' || el.type === 'radio') ? el.hasAttribute('checked') : (el.getAttribute('value') ?? '')
+  return null
+}
+
+function syncFormProperty(cur, nxt, prevRendered = null) {
   const tag = cur.tagName
+  // data-preserve: the view only changes this control when the value it *renders* changes. A re-render
+  // that renders the same value as last time (a button elsewhere on the page, a counter) leaves what
+  // the user typed or ticked alone. Without it every re-render resets a non-focused control to the
+  // rendered value — fine for forms that clear on submit, destructive for a long-form editor.
+  const preserve = nxt.hasAttribute('data-preserve')
   if (tag === 'INPUT' || tag === 'TEXTAREA') {
     const type = cur.type
     if (type === 'checkbox' || type === 'radio') {
       const next = nxt.hasAttribute('checked')
+      if (preserve && next === prevRendered) return
       if (cur.checked !== next) cur.checked = next
     } else if (document.activeElement !== cur) {
       // A textarea has no value attribute: its default value is its child text, which
       // nxt.value reads (and which the HTML parser has already normalised).
       const next = tag === 'TEXTAREA' ? nxt.value : (nxt.getAttribute('value') ?? '')
+      if (preserve && next === prevRendered) return
       if (cur.value !== next) cur.value = next
     }
   } else if (tag === 'SELECT' && document.activeElement !== cur) {