phlex-reactive 0.13.2 → 0.13.4

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

@@ -1077,6 +1077,7 @@ 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_NO_VALUE = Symbol("persist-no-value")
 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).
@@ -1235,6 +1236,14 @@ function persistEditorReady(el) {
   return typeof el.value === "string"
 }
 
+// The same question for #collectFields. A RICH editor (lexxy/trix) is only
+// ready once its custom element upgraded — Trix defines its elements in a
+// setTimeout after load — and reading it before that yields "", which is issue
+// #8. A bare [contenteditable] is plain DOM and always ready.
+function collectorEditorReady(el) {
+  return PERSIST_EDITOR_TAGS.has(el.localName) ? persistEditorReady(el) : true
+}
+
 // 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.
@@ -1258,6 +1267,33 @@ function persistSelectMultiple(el) {
   return el.tagName === "SELECT" && el.multiple
 }
 
+// How many controls can contribute a value under each `[]` name, counted the
+// way persistSnapshot fills the slot — a radio is the exception there and here.
+// A group of ONE is unambiguous: its single entry can only have come from that
+// control.
+function persistGroupSizes(controls) {
+  const sizes = new Map()
+  for (const { el, name } of controls) {
+    if (el.type === "radio" || !String(name).endsWith("[]")) continue
+    sizes.set(name, (sizes.get(name) ?? 0) + 1)
+  }
+  return sizes
+}
+
+// The value a control that cannot pick its own entry out of a list may take.
+// A list belongs to a `[]` group, and in a group of two or more nothing says
+// which entry came from which control — restoring it would paste
+// "freeform,news" into a text field. A group of ONE has no such ambiguity, and
+// refusing it would silently drop the draft of a plain field whose name merely
+// ends in `[]` (a list JS maintains), which worked before groups existed.
+// Returns PERSIST_NO_VALUE when the control must keep what the server rendered.
+function persistGenericValue(value, name, sizes) {
+  if (!Array.isArray(value)) return value
+  if (sizes.get(name) !== 1 || value.length !== 1) return PERSIST_NO_VALUE
+
+  return value[0]
+}
+
 // 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
@@ -1265,18 +1301,52 @@ function persistSelectMultiple(el) {
 // its textContent, else .value. Mirrors #collectFields' reads.
 function persistSnapshot(root, payload) {
   const fields = {}
+  // A `[]` name is a group for every control that can contribute a value —
+  // checkboxes, selects, text inputs, editors and contenteditables all append
+  // to one array, mirroring #collectFields. The one exception is a RADIO group,
+  // which means "pick one" and keeps its single value with or without the
+  // suffix, exactly as the collector treats it.
+  //
+  // Reading the slot without this (fields[name] ?? []) breaks as soon as a
+  // non-checkbox shares the group's name: a text input or an editor leaves a
+  // string there, `.push` on it throws inside the draft write, and that write
+  // is swallowed — the root then persists nothing at all, silently. Editors
+  // are collected AFTER the native controls, so they always land last.
+  const groupSlot = (name) => {
+    const existing = fields[name]
+    return Array.isArray(existing) ? existing : (fields[name] = [])
+  }
   for (const { el, name, kind } of persistControls(root, payload)) {
+    const group = String(name).endsWith("[]")
     if (kind === "editor") {
-      if (persistEditorReady(el)) fields[name] = el.value
+      if (persistEditorReady(el)) {
+        if (group) groupSlot(name).push(el.value)
+        else fields[name] = el.value
+      }
     } else if (kind === "contenteditable") {
-      fields[name] = el.textContent ?? ""
+      const text = el.textContent ?? ""
+      if (group) groupSlot(name).push(text)
+      else fields[name] = text
     } 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
+      // A `[]` group drafts the list of ticked values, mirroring #collectFields
+      // (issue #258). Without this the boxes overwrote each other and the draft
+      // held one boolean, which the restore then applied to every box of the
+      // group. A lone checkbox keeps the boolean it has always been.
+      if (group) {
+        const slot = groupSlot(name)
+        if (el.checked) slot.push(el.value)
+      } else {
+        fields[name] = el.checked
+      }
     } else if (persistSelectMultiple(el)) {
-      fields[name] = [...el.options].filter((o) => o.selected).map((o) => o.value)
+      const selected = [...el.options].filter((o) => o.selected).map((o) => o.value)
+      if (group) groupSlot(name).push(...selected)
+      else fields[name] = selected
+    } else if (group) {
+      groupSlot(name).push(el.value)
     } else {
       fields[name] = el.value
     }
@@ -1292,10 +1362,61 @@ function persistSnapshot(root, payload) {
 function persistApply(root, payload, fields) {
   const always = payload.restore === "always"
   const controls = persistControls(root, payload)
+  // Which group names the SERVER rendered with a box already ticked. Computed
+  // BEFORE the loop on purpose: the loop writes `checked`, so asking this
+  // question from inside it would read THIS restore's own work — the first box
+  // it ticks makes every later box of the same group look server-rendered, and
+  // a draft of two values comes back as one. The radio branch below asks the
+  // same question inline and stays correct only because a radio group holds a
+  // single value.
+  const groupSizes = persistGroupSizes(controls)
+  const serverTicked = new Set()
+  for (const control of controls) {
+    if (control.kind === "native" && control.el.type === "checkbox" && control.el.checked) {
+      serverTicked.add(control.name)
+    }
+  }
   for (const { el, name, kind } of controls) {
     if (!Object.hasOwn(fields, name)) continue
-    const value = fields[name]
+    let value = fields[name]
     if (value === null || value === undefined) continue
+    // A multi-select reads a list by matching option values, which is only
+    // sound when the list is ITS list. In a group with another contributor the
+    // entries are mixed, and a text value that happens to equal an option
+    // would select it — measured, a draft of ["blue","freitext"] from a select
+    // plus a text field selected both options. `?? 0` because a name without
+    // the suffix is not in the map at all, and a plain `<select multiple
+    // name="colors">` must keep restoring.
+    if (Array.isArray(value) && persistSelectMultiple(el) && (groupSizes.get(name) ?? 0) > 1) continue
+
+    // An array belongs to a `[]` group, and only a control that can pick ITS
+    // entry out of the list may read it: a checkbox matches by value, a
+    // multi-select by option. Everything else — editors, contenteditables,
+    // text inputs — keeps what the server rendered, because the list does not
+    // record which entry came from which control. This sits ABOVE the branch
+    // chain on purpose: below the editor branch it would never fire for the
+    // very controls that land last in the snapshot.
+    if (Array.isArray(value) && !(el.type === "checkbox" || persistSelectMultiple(el))) {
+      value = persistGenericValue(value, name, groupSizes)
+      if (value === PERSIST_NO_VALUE) continue
+    }
+    // The mirror, for a draft written BEFORE a group was drafted as a list
+    // (#258): there `features[]` held ONE boolean, and applying it here ticks
+    // every box of the group — precisely the state this fix removes, for as
+    // long as the draft lives (default ttl 7 days). A group key that is not a
+    // list is stale by definition, so the control keeps what the server
+    // rendered and the next snapshot overwrites the key. It reads for a
+    // multi-select too: 0.13.2 wrote last-writer-wins per name, so a checkbox
+    // in a mixed group could leave its boolean under the select's name, and
+    // under `restore: "always"` the select would then deselect everything —
+    // `wanted` being Set{"true"} matches no option. Asking for the `[]` suffix
+    // is what leaves a lone `gift` checkbox on the boolean it has always held —
+    // and scoping the rule to the one key whose meaning changed is why
+    // PERSIST_VERSION stays at 1: bumping it would also throw away the drafted
+    // prose of every form that has no checkbox group at all.
+    if ((el.type === "checkbox" || persistSelectMultiple(el)) && String(name).endsWith("[]") && !Array.isArray(value)) {
+      continue
+    }
     if (kind === "editor") {
       persistApplyEditor(root, el, name, value, always)
     } else if (kind === "contenteditable") {
@@ -1304,6 +1425,12 @@ function persistApply(root, payload, fields) {
     } 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" && Array.isArray(value)) {
+      // A drafted group ticks exactly the boxes it held. One box the SERVER
+      // rendered ticked means it had a say, and the draft yields for the whole
+      // group.
+      if (!always && serverTicked.has(name)) continue
+      el.checked = value.map(String).includes(el.value)
     } else if (el.type === "checkbox") {
       if (!always && el.checked) continue
       el.checked = Boolean(value)
@@ -1323,6 +1450,11 @@ function persistApply(root, payload, fields) {
 // 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) {
+  // A list never reaches here: both callers resolve it through
+  // persistGenericValue first — the group of two or more has no mapping back to
+  // this editor, the group of one does. Belt and braces, because this is the
+  // one apply path with a second entry point.
+  if (Array.isArray(value)) return
   if (!persistEditorReady(el)) return // not upgraded yet — persistDeferEditors re-applies after define
   if (!always && !persistEditorBlank(el)) return
   try {
@@ -1348,10 +1480,12 @@ function persistDeferEditors(root, payload, fields) {
   for (const tag of pending) {
     registry.whenDefined(tag).then(() => {
       if (!root.isConnected) return
-      for (const { el, name, kind } of persistControls(root, payload)) {
+      const deferred = persistControls(root, payload)
+      const sizes = persistGroupSizes(deferred)
+      for (const { el, name, kind } of deferred) {
         if (kind !== "editor" || el.localName !== tag || !Object.hasOwn(fields, name)) continue
-        const value = fields[name]
-        if (value === null || value === undefined) continue
+        const value = persistGenericValue(fields[name], name, sizes)
+        if (value === null || value === undefined || value === PERSIST_NO_VALUE) continue
         persistApplyEditor(root, el, name, value, always)
       }
     })
@@ -1390,16 +1524,18 @@ function persistClearRoot(root) {
 // Frozen so nothing can be registered into it at runtime — extending the
 // vocabulary is a gem change, not an app hook.
 const CLIENT_OPS = Object.freeze({
-  show: (el, args) => setHidden(el, false, args),
-  hide: (el, args) => setHidden(el, true, args),
-  toggle: (el, args) => setHidden(el, !el.hidden, args),
+  show: (el, args, resolveTargets) => setVisibility(el, false, args, resolveTargets),
+  hide: (el, args, resolveTargets) => setVisibility(el, true, args, resolveTargets),
+  toggle: (el, args, resolveTargets) => setVisibility(el, !el.hidden, args, resolveTargets),
   add_class: (el, args) => el.classList.add(...(args.classes ?? [])),
   remove_class: (el, args) => el.classList.remove(...(args.classes ?? [])),
   toggle_class: (el, args) => (args.classes ?? []).forEach((c) => el.classList.toggle(c)),
 
   // Attribute ops (issue #96), interpret-time allowlisted. set_attr writes the
   // (already-stringified) value; toggle_attr adds a missing attr (value "") or
-  // removes a present one; remove_attr removes it. A refused name warns + skips.
+  // removes a present one — or, given values [on, off] (issue #271), flips
+  // between them (an absent attr becomes `on`); remove_attr removes it. A
+  // refused name warns + skips.
   set_attr: (el, args) => {
     if (guardAttr(args.name)) el.setAttribute(args.name, args.value ?? "")
   },
@@ -1408,7 +1544,10 @@ const CLIENT_OPS = Object.freeze({
   },
   toggle_attr: (el, args) => {
     if (!guardAttr(args.name)) return
-    if (el.hasAttribute(args.name)) el.removeAttribute(args.name)
+    if (Array.isArray(args.values)) {
+      const [on, off] = args.values
+      el.setAttribute(args.name, el.getAttribute(args.name) === on ? off : on)
+    } else if (el.hasAttribute(args.name)) el.removeAttribute(args.name)
     else el.setAttribute(args.name, "")
   },
 
@@ -1508,6 +1647,18 @@ function setHidden(el, hidden, args) {
   else el.hidden = hidden
 }
 
+// show/hide/toggle (issue #271): flip visibility, then mirror the INTENDED
+// state into the `expanded:` target's aria-expanded — computed before the flip,
+// so a transition never delays or races it. The expanded target resolves with
+// the op's own scoping (root-scoped, or document-wide under global: true).
+function setVisibility(el, hidden, args, resolveTargets) {
+  setHidden(el, hidden, args)
+  if (args?.expanded == null || typeof resolveTargets !== "function") return
+  for (const target of resolveTargets({ ...args, to: args.expanded })) {
+    target.setAttribute?.("aria-expanded", String(!hidden))
+  }
+}
+
 // The interpret-time attribute guard: refuse (warn + skip) a name off the
 // allowlist. Returns true when the op may proceed.
 function guardAttr(name) {
@@ -1813,6 +1964,256 @@ function parseOps(raw) {
   }
 }
 
+// --- on_client binding records (issue #271) -----------------------------------
+// Each on_client call emits ONE record ({on, ops, window?, outside?, confirm?,
+// confirmWhen?}); mix space-joins several onto one element (spaces inside a
+// record ride as \u0020, so the join is unambiguous). Stimulus hands every
+// runOps descriptor on an element the SAME event.params, so runOps selects the
+// record(s) whose descriptor matches the firing event: event.type, the key
+// filter, and window-boundness.
+
+// Stimulus's default keyMappings (letters and digits map to themselves). A
+// custom Stimulus schema is not mirrored — an unknown filter never matches.
+const KEY_FILTER_MAP = Object.freeze({
+  enter: "Enter",
+  tab: "Tab",
+  esc: "Escape",
+  space: " ",
+  up: "ArrowUp",
+  down: "ArrowDown",
+  left: "ArrowLeft",
+  right: "ArrowRight",
+  home: "Home",
+  end: "End",
+  page_up: "PageUp",
+  page_down: "PageDown",
+})
+const KEY_FILTER_MODIFIERS = Object.freeze(["meta", "ctrl", "alt", "shift"])
+
+// Stimulus's rule: the four modifiers must match EXACTLY (ctrl+k is not k);
+// the remaining token is compared to event.key case-insensitively. A
+// non-keyboard event (no event.key) checks the modifiers only. `keyMappings`
+// is the app's Stimulus schema table (custom keys included) when the
+// controller has one; the default table is the fallback.
+function keyFilterMatches(filter, event, keyMappings) {
+  const parts = filter.split("+")
+  for (const mod of KEY_FILTER_MODIFIERS) {
+    if (parts.includes(mod) !== Boolean(event[`${mod}Key`])) return false
+  }
+  const token = parts.find((part) => !KEY_FILTER_MODIFIERS.includes(part))
+  if (token === undefined || typeof event.key !== "string") return true
+  const key =
+    keyMappings && Object.hasOwn(keyMappings, token)
+      ? keyMappings[token]
+      : Object.hasOwn(KEY_FILTER_MAP, token)
+        ? KEY_FILTER_MAP[token]
+        : /^[a-z0-9]$/.test(token)
+          ? token
+          : null
+  return typeof key === "string" && key.toLowerCase() === event.key.toLowerCase()
+}
+
+// Parse data-reactive-ops-param into binding records. Stimulus typecasts a
+// lone record to an object; several records stay a string (JSON.parse fails on
+// the join) and are split here. A LEGACY [[op, args]] list (array or JSON
+// string — a hand-built attr) becomes one record flagged `legacy`: it has no
+// `on`, so it always matches, and runOps reads its flags from event.params. A
+// malformed piece warns and is skipped; its siblings still run (default-deny).
+function parseBindingRecords(raw) {
+  if (Array.isArray(raw)) return [{ ops: raw, legacy: true }]
+  if (raw && typeof raw === "object") return [raw]
+  if (typeof raw !== "string") return []
+  const text = raw.trim()
+  if (text.startsWith("[")) return [{ ops: parseOps(text), legacy: true }]
+  const records = []
+  for (const piece of text.split(" ")) {
+    if (piece === "") continue
+    let record = null
+    try {
+      record = JSON.parse(piece)
+    } catch {
+      record = null
+    }
+    if (record && typeof record === "object" && !Array.isArray(record)) records.push(record)
+    else console.warn(`[phlex-reactive] malformed on_client binding record ${JSON.stringify(piece)} — skipped`)
+  }
+  return records
+}
+
+// Does this record's descriptor match the firing event? The window check
+// matters for an element carrying both `click` and `click@window`: one inside
+// click reaches both listeners, and only currentTarget tells them apart. The
+// `window != null` guard keeps a window-less harness from classifying every
+// undefined currentTarget as window-bound. Only a LEGACY record (no `on` by
+// construction) matches everything; any other record without a descriptor is
+// malformed and never matches (default-deny). `keyMappings === null` skips the
+// key filter (the caller's single-candidate shortcut).
+function bindingMatches(record, event, keyMappings) {
+  if (record.legacy) return true
+  const on = record.on
+  if (typeof on !== "string" || on === "") return false
+  const dot = on.indexOf(".")
+  if (event.type !== (dot < 0 ? on : on.slice(0, dot))) return false
+  const win = globalThis.window
+  const windowBound = win != null && event.currentTarget === win
+  if (Boolean(record.window) !== windowBound) return false
+  return dot < 0 || keyMappings === null || keyFilterMatches(on.slice(dot + 1), event, keyMappings)
+}
+
+// A `once: true` record (PR #272) is spent after its first run. Stimulus
+// removes only that binding's own listener; a regular same-event sibling on
+// the element keeps calling runOps with BOTH records, so the spent one is
+// skipped here. Spent state belongs to the TRIGGER element (a WeakMap, so it
+// is collected with it): a morph/stream that swaps in a fresh element starts
+// fresh, and a byte-identical sibling trigger has its own. A window-bound
+// binding's currentTarget is the window, so there the element's ops attr joins
+// the key (a re-rendered window-bound once trigger with the same markup stays
+// spent — a known limit).
+const spentOnceBindings = new WeakMap()
+function onceBindingSpent(controller, event, record) {
+  if (!record.once) return false
+  const owner = event.currentTarget ?? controller.element
+  let byOwner = spentOnceBindings.get(controller)
+  if (!byOwner) {
+    byOwner = new WeakMap()
+    spentOnceBindings.set(controller, byOwner)
+  }
+  let spent = byOwner.get(owner)
+  if (!spent) {
+    spent = new Set()
+    byOwner.set(owner, spent)
+  }
+  const raw = event.params?.ops
+  const attr = owner === globalThis.window ? `${typeof raw === "string" ? raw : JSON.stringify(raw ?? null)}|` : ""
+  const key = attr + JSON.stringify(record)
+  if (spent.has(key)) return true
+  spent.add(key)
+  return false
+}
+
+// Two identical descriptors on one element (two mix-ed on_client calls with
+// the same event) are two Stimulus bindings, so runOps runs twice for ONE
+// event. The first call runs every matching record; a repeat is a no-op.
+// "Repeat" is (controller, listener target, the element's ops attr): Stimulus
+// walks EVERY binding of one window listener with the SAME event object, so
+// keying on currentTarget alone (= window) would drop every other root's
+// window-bound binding — and a sibling element's within one root. The ops attr
+// is the per-element key (a lone record is typecast to a fresh object per
+// binding, so it is compared by its JSON). Two elements in one root carrying
+// byte-identical window-bound records run once — the same ops, applied once.
+const ranBindings = new WeakMap()
+function bindingsAlreadyRan(event, controller) {
+  if (event === null || typeof event !== "object") return false
+  const raw = event.params?.ops
+  const key = typeof raw === "string" ? raw : JSON.stringify(raw ?? null)
+  let byController = ranBindings.get(event)
+  if (!byController) {
+    byController = new WeakMap()
+    ranBindings.set(event, byController)
+  }
+  let byTarget = byController.get(controller)
+  if (!byTarget) {
+    byTarget = new Map()
+    byController.set(controller, byTarget)
+  }
+  let keys = byTarget.get(event.currentTarget)
+  if (!keys) {
+    keys = new Set()
+    byTarget.set(event.currentTarget, keys)
+  }
+  if (keys.has(key)) return true
+  keys.add(key)
+  return false
+}
+
+// The TEXT reading of a compute control (issue #262) — what a :string input
+// hands the reducer and what the identity/cross-root mirrors paint. A checkbox
+// reads its CHECKED STATE ("true"/"false", the strings reactive_show compares
+// against): its .value is a constant — "1", "on", whatever the markup says —
+// so reading it told the reducer nothing. A radio reads its value only while
+// checked ("" otherwise; the resolver hands over the checked radio of a group).
+// Anything else reads .value, as it always has.
+//
+// Every compute helper takes a CONTROL — the { el, kind } record #recompute's
+// resolver builds, kind being "checkbox", "radio" or "" — and never re-reads
+// el.type: the resolver reads it ONCE per name. Re-reading it in each helper
+// cost the 30-input calculator bench ~60% (16.8 → 27 µs/iter, measured).
+function computeText({ el, kind }) {
+  if (!el) return ""
+  if (kind === "checkbox") return el.checked ? "true" : "false"
+  if (kind === "radio") return el.checked ? (el.value ?? "") : ""
+  return el.value ?? ""
+}
+
+// The control for a name nothing owned resolves to.
+const COMPUTE_NO_CONTROL = Object.freeze({ el: null, kind: "" })
+
+// Whether a value counts as "on" — for a :boolean input read off a control that
+// is not a checkbox, and for an output written INTO a checkbox. A boolean is
+// itself; otherwise "", "0" and "false" are off (what a hidden flag field or a
+// reducer returning 0 means) and anything else is on.
+function computeTruthy(value) {
+  if (typeof value === "boolean") return value
+  if (value == null) return false
+  const text = String(value)
+  return text !== "" && text !== "0" && text !== "false"
+}
+
+// One declared input's value for the reducer, coerced by its declared type
+// (issue #104; checked-state controls issue #262):
+//
+//   "string"  → the text reading, raw (blank/absent → "")
+//   "boolean" → a checkbox's checked state; any other control by computeTruthy
+//   "number"  → a checkbox is 1/0; anything else through Number (blank/NaN → 0,
+//               the nanToZero the hand-written calculators use)
+//
+// A checkbox is 1/0 and never Number(its value): a box is a yes/no, and a
+// reducer that wants an amount writes `gift ? 25 : 0`.
+function computeValue(control, type) {
+  if (type === "string") return computeText(control)
+  const box = control.kind === "checkbox"
+  if (type === "boolean") return box ? Boolean(control.el.checked) : computeTruthy(computeText(control))
+  if (box) return control.el.checked ? 1 : 0
+  const n = Number(computeText(control))
+  return Number.isFinite(n) ? n : 0
+}
+
+// Write one reducer output into the control its name resolved to (issue #262),
+// change-guarded. Returns the element to announce with an `input` event, or
+// null when nothing changed. A checkbox takes the result as its checked state
+// and a radio group checks the radio carrying it — neither ever has its value
+// attribute rewritten, which would change what the control SUBMITS. Anything
+// else takes the result as its .value (issue #76).
+function computeWrite(root, owns, { el, kind }, domName, value) {
+  if (kind === "checkbox") {
+    const checked = computeTruthy(value)
+    if (Boolean(el.checked) === checked) return null
+    el.checked = checked
+    return el
+  }
+  if (kind === "radio") return computeCheckRadio(root, owns, domName, String(value))
+  if (String(value) === el.value) return null
+  el.value = value
+  return el
+}
+
+// Check the owned radio of a group whose value is `wanted`, unchecking the
+// rest — the same per-radio rule a restored draft applies. A value no radio
+// carries clears the group. Returns the radio that GAINED the check, or, for a
+// cleared group, the one that lost it; null when the selection already matched.
+function computeCheckRadio(root, owns, domName, wanted) {
+  let announced = null
+  for (const el of root.querySelectorAll(`[name="${domName}"]`)) {
+    if (el.type !== "radio" || !owns(el)) continue
+    const checked = el.value === wanted
+    if (Boolean(el.checked) === checked) continue
+    el.checked = checked
+    if (checked) announced = el
+    else announced ??= el
+  }
+  return announced
+}
+
 // Normalize a reducer's reserved $ops output (issue #226): the compute `ops`
 // builder (its .ops list), a raw [[name, args], ...] array, or null/undefined
 // (no effect this pass). An EMPTY list is the same as null — "nothing to run"
@@ -1845,7 +2246,7 @@ function applyOps(list, resolveTargets, onZeroTargets) {
     }
     const targets = resolveTargets(args)
     if (targets.length === 0 && onZeroTargets) onZeroTargets(name, args)
-    for (const el of targets) CLIENT_OPS[name](el, args)
+    for (const el of targets) CLIENT_OPS[name](el, args, resolveTargets)
   }
 }
 
@@ -2384,11 +2785,33 @@ export default class extends Controller {
   // the component resets whatever they toggled (by design — a signed action
   // owns state that must survive re-renders).
   runOps(event) {
-    const { ops, confirm, confirmWhen, outside, window: windowBound } = event.params
+    if (bindingsAlreadyRan(event, this)) return
+    const params = event.params ?? {}
     // The trigger element on_client was spread onto (issue #222 ctx: { el }),
     // captured now — currentTarget resets before the confirm resolver's microtask.
     const trigger = event.currentTarget ?? event.target
+    // Issue #271: run only the binding record(s) whose descriptor fired. A
+    // legacy [[op, args]] attr reads its flags from the element-wide params.
+    const records = parseBindingRecords(params.ops)
+    // Stimulus already applied the firing descriptor's key filter (custom
+    // schema keys included), so a lone candidate on type + window-boundness
+    // runs without a second key check; several same-type candidates are told
+    // apart by their key filters, read through the app's Stimulus schema.
+    const candidates = records.filter((record) => bindingMatches(record, event, null))
+    const matching =
+      candidates.length <= 1
+        ? candidates
+        : candidates.filter((record) => bindingMatches(record, event, this.application?.schema?.keyMappings))
+    if (matching.length === 0 && records.length > 0) return this.#warnNoBinding(event)
+    for (const record of matching) {
+      if (onceBindingSpent(this, event, record)) continue
+      this.#runBinding(record.legacy ? { ...params, ops: record.ops } : record, event, trigger)
+    }
+  }
 
+  // One on_client binding (issue #95): its outside guard, preventDefault rule,
+  // confirm gate, then its ops — every flag read from the binding itself.
+  #runBinding({ ops, confirm, confirmWhen, outside, window: windowBound }, event, trigger) {
     // Outside guard FIRST — identical semantics to dispatch() (issue #80): an
     // outside: trigger is a COMPLETE no-op for events inside this root, before
     // preventDefault and before any op runs.
@@ -2426,6 +2849,17 @@ export default class extends Controller {
       })
   }
 
+  // Issue #271: runOps fired but no record matched the event — a hand-edited
+  // attr or a descriptor the matcher doesn't know. Verbose gate only, deduped.
+  #warnNoBinding(event) {
+    if (!this.#verboseEnabled()) return
+    const key = `no-binding|${event.type}|${this.element?.id || "?"}`
+    if (zeroTargetAlreadyWarned(key)) return
+    console.warn(
+      `[phlex-reactive] runOps on #${this.element?.id || "?"} found no on_client binding matching a "${event.type}" event — nothing ran`,
+    )
+  }
+
   // Dirty tracking (issue #103). Wired by reactive_field(dirty: true) /
   // reactive_root(track_dirty: true): an `input` on an owned field runs a FULL
   // re-scan of every field this root owns. NO round trip, NO shipped state — the
@@ -2480,8 +2914,14 @@ export default class extends Controller {
     // predicate in the common no-nested-root case (skipping closest() entirely)
     // and the exact #ownsField check when a nested reactive root is present
     // (issue #15 scoping, byte-identical to before). Resolution is memoized in a
-    // per-CALL Map, FIRST-WINS, so a name read as an input AND written as an
-    // output resolves to the SAME element and is queried once.
+    // per-CALL Map, so a name read as an input AND written as an output
+    // resolves to the SAME element and is queried once.
+    //
+    // Which element a name resolves to (issue #262, mirroring #showFieldValue): a
+    // CHECKBOX wins over the hidden companion Rails renders before it; a radio
+    // group resolves to its CHECKED radio (any radio of the group when none is);
+    // anything else is first-wins. Resolving first-wins across the board handed
+    // the reducer the companion's constant "0" and the first radio's value.
     //
     // Why per-name `[name="X"]` queries and not one bare `[name]` sweep: a single
     // sweep is the natural "one walk", but the resolver must issue the SAME
@@ -2500,25 +2940,37 @@ export default class extends Controller {
 
     const owns = this.#ownershipFilter()
     const byName = new Map()
-    const ownedField = (name) => {
-      if (byName.has(name)) return byName.get(name)
-      let found = null
+    const ownedControl = (name) => {
+      const known = byName.get(name)
+      if (known) return known
+      let radio = null
+      let first = null
+      let control = null
       for (const el of this.element.querySelectorAll(`[name="${scoped(name)}"]`)) {
-        if (owns(el)) {
-          found = el // FIRST-WINS (radio groups, Rails hidden+checkbox name pairs)
+        if (!owns(el)) continue
+        const kind = el.type // read ONCE per element — see computeText
+        if (kind === "checkbox" || (kind === "radio" && el.checked)) {
+          control = { el, kind }
           break
         }
+        if (kind === "radio") radio ??= el
+        else first ??= el
+      }
+      if (!control) {
+        if (radio) control = { el: radio, kind: "radio" }
+        else control = first ? { el: first, kind: "" } : COMPUTE_NO_CONTROL
       }
-      byName.set(name, found)
-      return found
+      byName.set(name, control)
+      return control
     }
 
     // Identity-mirror pass (issue #104), ALWAYS run — even with NO registered
     // reducer, so reactive_text(:title) mirrors a field into its text node with
-    // zero reducer wiring. Each declared input's RAW string value is written to
-    // its owned [data-reactive-text="<name>"] node(s). It runs BEFORE the reducer
+    // zero reducer wiring. Each declared input's RAW text reading (computeText —
+    // a checkbox paints "true"/"false", issue #262) is written to its owned
+    // [data-reactive-text="<name>"] node(s). It runs BEFORE the reducer
     // early-return below so a reducer-less binding still mirrors.
-    for (const name of inputs) this.#mirrorText(name, ownedField(name)?.value ?? "")
+    for (const name of inputs) this.#mirrorText(name, computeText(ownedControl(name)))
 
     const key = this.element.getAttribute("data-reactive-compute-reducer-param")
     const reduce = key ? computeReducer(key) : null
@@ -2526,26 +2978,18 @@ export default class extends Controller {
       // No reducer registered: the identity pass above still ran, so declared
       // cross-root mirrors of the INPUT names still paint (issue #159) — a
       // reducer-less binding mirrors, exactly like the owned-text-node case.
-      this.#applyComputeMirrors({}, ownedField)
+      this.#applyComputeMirrors({}, ownedControl)
       return
     }
 
     const outputs = this.#parseComputeList("data-reactive-compute-outputs-param")
 
-    // Coerce each input per its declared type (issue #104): "string" → the raw
-    // display string (blank/absent → ""); else ("number", the array-form default)
-    // → the numeric coercion (blank/NaN → 0, the nanToZero the hand-written
-    // calculators use). Reads from the memoized resolver — no re-query.
+    // Coerce each input per its declared type (computeValue): "string" raw,
+    // "boolean" a real boolean, else ("number", the array-form default) the
+    // numeric coercion. A checkbox contributes its CHECKED STATE under every
+    // type (issue #262). Reads from the memoized resolver — no re-query.
     const values = {}
-    for (const [name, type] of inputPairs) {
-      const field = ownedField(name)
-      if (type === "string") {
-        values[name] = field?.value ?? ""
-      } else {
-        const n = Number(field?.value)
-        values[name] = Number.isFinite(n) ? n : 0
-      }
-    }
+    for (const [name, type] of inputPairs) values[name] = computeValue(ownedControl(name), type)
 
     // meta.changed stays on #changedComputeField (its own #ownsField check over
     // the raw event target) — NOT this resolver. The issue-#15 nested-rejection
@@ -2564,7 +3008,8 @@ export default class extends Controller {
     //   1. BATCH the field writes from the ONE result. Each output name in the
     //      allowlist (outputs:) whose owned field's value actually changes is
     //      written now (change-guarded) and remembered — but NO `input` event is
-    //      dispatched yet, so nothing re-enters mid-batch.
+    //      dispatched yet, so nothing re-enters mid-batch. A checkbox or radio
+    //      output is written as its CHECKED state (computeWrite, issue #262).
     //   2. PAINT the sinks from the SETTLED values: any owned reactive_text node by
     //      presence (issue #183 change #4 — a text node no longer needs its name in
     //      outputs:), then the cross-root mirror: ids (issue #159).
@@ -2578,11 +3023,10 @@ export default class extends Controller {
     const changedFields = []
     for (const name of outputs) {
       if (name === "$ops" || !(name in result)) continue
-      const field = ownedField(name)
-      if (!field) continue // a non-field output paints as a text sink in phase 2
-      if (String(result[name]) === field.value) continue // change-guard — unchanged, skip
-      field.value = result[name]
-      changedFields.push(field)
+      const control = ownedControl(name)
+      if (!control.el) continue // a non-field output paints as a text sink in phase 2
+      const written = computeWrite(this.element, owns, control, scoped(name), result[name])
+      if (written) changedFields.push(written) // null = change-guard, unchanged
     }
 
     // Phase 2 — text sinks declare themselves (issue #183 change #4): every result
@@ -2599,7 +3043,7 @@ export default class extends Controller {
 
     // Cross-root text mirrors (issue #159) — AFTER the batch + text sinks, so a
     // mirror keyed on a just-written output paints the settled value.
-    this.#applyComputeMirrors(result, ownedField)
+    this.#applyComputeMirrors(result, ownedControl)
 
     // Phase 3 — dispatch the deferred `input` events (issue #183). Real browsers
     // do NOT fire `input` on a programmatic .value write (issue #76), so we do it
@@ -2650,12 +3094,25 @@ export default class extends Controller {
   // CLICKING IT (so its own on(:select) reactive trigger fires — selection stays
   // a signed action); Escape clears. Ephemeral highlight state lives on the DOM
   // (data-reactive-highlighted), never shipped to the client as trusted state.
+  //
+  // Issue #271: a container spread with reactive_listnav(focus: true) carries
+  // data-reactive-listnav-focus-param="true" — ROVING-FOCUS mode for a
+  // role=menu: the same moves shift real focus among the items instead of a
+  // highlight, and Home/End (listnavFirst/listnavLast) jump to the edges.
   listnavNext(event) {
-    this.#moveHighlight(event, +1)
+    this.#listnavMove(event, (current, length) => (current < 0 ? 0 : (current + 1) % length))
   }
 
   listnavPrev(event) {
-    this.#moveHighlight(event, -1)
+    this.#listnavMove(event, (current, length) => (current < 0 ? length - 1 : (current - 1 + length) % length))
+  }
+
+  listnavFirst(event) {
+    this.#listnavMove(event, () => 0)
+  }
+
+  listnavLast(event) {
+    this.#listnavMove(event, (_current, length) => length - 1)
   }
 
   // Enter: activate the highlighted option (fires its reactive select). No-op if
@@ -2673,23 +3130,39 @@ export default class extends Controller {
     for (const el of this.#listnavOptions(event)) el.removeAttribute("data-reactive-highlighted")
   }
 
-  // Move the highlight by `step` (with wrap-around) among THIS root's options.
-  // preventDefault stops Arrow keys from moving the caret in the search input.
-  #moveHighlight(event, step) {
+  // Move among THIS root's options: `pick(current, length)` returns the next
+  // index (current is -1 when nothing is highlighted/focused). preventDefault
+  // stops Arrow keys moving the caret in a search input, and the page scrolling
+  // under a menu. Highlight mode writes data-reactive-highlighted; focus mode
+  // (issue #271) focuses the chosen item, current being the item that is or
+  // contains document.activeElement.
+  #listnavMove(event, pick) {
     const options = this.#listnavOptions(event)
     if (!options.length) return
     event.preventDefault()
 
-    const current = options.findIndex((el) => el.hasAttribute("data-reactive-highlighted"))
-    // From nothing: Down highlights the first option, Up the last.
-    const next = current < 0 ? (step > 0 ? 0 : options.length - 1) : (current + step + options.length) % options.length
+    const focusMode = this.#listnavFocusMode(event)
+    const active = globalThis.document?.activeElement
+    const current = focusMode
+      ? options.findIndex((el) => el === active || (active != null && el.contains?.(active)))
+      : options.findIndex((el) => el.hasAttribute("data-reactive-highlighted"))
+    const chosen = options[pick(current, options.length)]
 
-    for (const el of options) el.removeAttribute("data-reactive-highlighted")
-    const chosen = options[next]
-    chosen.setAttribute("data-reactive-highlighted", "true")
+    if (focusMode) {
+      chosen.focus?.()
+    } else {
+      for (const el of options) el.removeAttribute("data-reactive-highlighted")
+      chosen.setAttribute("data-reactive-highlighted", "true")
+    }
     chosen.scrollIntoView?.({ block: "nearest" })
   }
 
+  // Focus mode is read off the TRIGGER like the option selector (issue #271).
+  #listnavFocusMode(event) {
+    const trigger = event?.currentTarget ?? event?.target ?? this.element
+    return trigger.getAttribute?.("data-reactive-listnav-focus-param") === "true"
+  }
+
   // The option elements this root owns (skips nested reactive roots, issue #15),
   // per the selector on data-reactive-listnav-option-param. The attr rides on the
   // TRIGGER element (the search input on(...) is spread onto), read from the
@@ -3167,10 +3640,11 @@ export default class extends Controller {
   // only (never innerHTML), change-guarded, and NO input dispatch — same
   // contract as #mirrorText. With no mirror declared this is one getAttribute
   // and out — the shipped compute path never touches the document.
-  #applyComputeMirrors(result, ownedField) {
+  #applyComputeMirrors(result, ownedControl) {
     const mirror = this.#parseComputeMirror()
     for (const [name, selectors] of Object.entries(mirror)) {
-      const value = name in result ? result[name] : ownedField(name)?.value
+      const control = name in result ? null : ownedControl(name)
+      const value = name in result ? result[name] : control.el ? computeText(control) : undefined
       if (value === undefined || value === null) continue
       const text = String(value)
       for (const sel of Array.isArray(selectors) ? selectors : [selectors]) {
@@ -3894,6 +4368,7 @@ export default class extends Controller {
     const fields = {}
     const files = []
     const owns = this.#ownershipFilter() // compute ONCE per dispatch (issue #117)
+    const controls = []
     this.element.querySelectorAll("input[name], select[name], textarea[name]").forEach((field) => {
       if (!owns(field)) return
       if (field.type === "file") {
@@ -3901,6 +4376,39 @@ export default class extends Controller {
         // shape (params[name][]) even when the user picked exactly one file —
         // otherwise a [:file] schema would see a lone scalar upload and drop it.
         for (const file of field.files ?? []) files.push({ name: field.name, file, multiple: field.multiple })
+      } else {
+        // Held for a second pass: a hidden input is only a companion if a
+        // checkbox somewhere in the root shares its name, which the first
+        // occurrence cannot know yet.
+        controls.push(field)
+      }
+    })
+    // Collected before the first pass so the editor DOM is walked once.
+    const editors = []
+    this.element.querySelectorAll(`[name]${PERSIST_EDITOR_SELECTOR}`).forEach((el) => {
+      if (owns(el)) editors.push(el) // the SAME hoisted predicate (nested reactive root, issue #15)
+    })
+    const arrayNames = this.#arrayFieldNames(controls)
+    const companionNames = this.#companionNames(controls)
+    for (const field of controls) {
+      if (arrayNames.has(field.name)) {
+        const slot = fields[field.name] ?? (fields[field.name] = [])
+        if (field.type === "checkbox" || field.type === "radio") {
+          // An unchecked box contributes NOTHING, the way a native submission
+          // leaves it out. The group's value is the list of checked values, and
+          // with none checked that list stays an EMPTY ARRAY rather than
+          // vanishing: the action can tell "the operator cleared them" from
+          // "the group never rendered", and an [:string] schema coerces [] to
+          // []. A form body cannot carry the empty array, so #buildFormData
+          // announces the group there instead.
+          if (field.checked) slot.push(field.value)
+        } else if (field.type === "hidden") {
+          if (!companionNames.has(field.name)) slot.push(field.value)
+        } else if (field.multiple && field.options) {
+          for (const option of field.options) if (option.selected) slot.push(option.value)
+        } else {
+          slot.push(field.value)
+        }
       } else if (field.type === "checkbox") {
         fields[field.name] = field.checked
       } else if (field.type === "radio") {
@@ -3908,30 +4416,103 @@ export default class extends Controller {
       } else {
         fields[field.name] = field.value
       }
-    })
+    }
     // Named rich-text / custom editors (lexxy-editor, trix-editor) and bare
     // [contenteditable]. These aren't input/select/textarea, so the query above
     // skips them — without this, a reactive save posts an empty value and
     // silently wipes the field (issue #8). Read whatever the element exposes:
     // a custom editor's serialized `.value`, else its contenteditable text.
-    // Only fill a name the standard controls left absent or empty, so a synced
-    // hidden input (e.g. Trix mirrors into one) still wins when populated.
-    this.element
-      .querySelectorAll("[name]:is(lexxy-editor, trix-editor, [contenteditable=''], [contenteditable=true], [contenteditable=plaintext-only])")
+    // Under a plain name: only fill what the standard controls left absent or
+    // empty, so a synced hidden input (e.g. Trix mirrors into one) still wins
+    // when populated. Under a `[]` name the editor APPENDS to the group slot
+    // instead, and a same-named hidden keeps its own say: nothing here can
+    // tell a hidden that mirrors this editor from one that is a list JS
+    // maintains.
+    editors
       .forEach((el) => {
-        if (!owns(el)) return // reuse the SAME hoisted predicate (nested reactive root — issue #15)
         // A plain element (e.g. a <div contenteditable>) has no `name` IDL
         // property — only the attribute — so read getAttribute, not el.name.
         const name = el.getAttribute("name")
         if (!name) return
+        const own = el.value ?? el.textContent ?? el.innerHTML ?? ""
+        // A `[]` name is a group here too: the editor APPENDS its value
+        // instead of replacing the slot. Assigning a scalar posted
+        // `{"notes[]": "<p>x</p>"}` while the draft snapshot pushed the same
+        // control into an array — the wire and the draft disagreeing about one
+        // field, and a declared array type seeing a string. A same-named hidden
+        // is NOT read as this editor's twin: nothing here can tell a mirror
+        // from a list JS maintains, and a value posted twice is visible while a
+        // suppressed one is not.
         const existing = fields[name]
+        // An editor that has not upgraded yet contributes NOTHING to a group.
+        // Trix defines its elements in a setTimeout after load, and its "" is
+        // not an empty value but an absent one: persistSnapshot omits such an
+        // editor for the same reason, so this keeps the wire and the draft
+        // saying the same thing.
+        if (String(name).endsWith("[]") && !collectorEditorReady(el)) return
+        if (String(name).endsWith("[]") && (existing === undefined || Array.isArray(existing))) {
+          const slot = Array.isArray(existing) ? existing : (fields[name] = [])
+          slot.push(own)
+          return
+        }
+        // A scalar already under a `[]` name can only be a RADIO's: a radio
+        // means "pick one" and keeps its single value with or without the
+        // suffix, which is why #arrayFieldNames excepts it. Converting that to
+        // a group here would discard the chosen value — measured, the post lost
+        // it — so the editor stands down and the rule below applies, which
+        // never overwrites a populated name.
+        // Only fill what the standard controls left absent or empty, so a
+        // synced hidden input still wins when populated.
         if (existing == null || existing === "") {
-          fields[name] = el.value ?? el.textContent ?? el.innerHTML ?? ""
+          fields[name] = own
         }
       })
     return { fields, files }
   }
 
+  // Names collected as an ARRAY rather than a single value: a name carrying the
+  // `[]` suffix, the HTML convention for a group. That suffix is the ONLY
+  // trigger — a group says so, it is not inferred from two controls happening
+  // to share a name. Radios are excluded BY DESIGN: a radio group shares one
+  // name to mean "pick one", and it keeps posting the single checked value,
+  // suffix or not.
+  //
+  // Issue #258: without this, `fields[name] = field.checked` wrote a boolean per
+  // checkbox and same-named boxes overwrote each other, so three boxes with two
+  // ticked left the browser as the LAST box's checked state — the chosen values
+  // never reached the wire, whatever the action's schema declared.
+  #arrayFieldNames(controls) {
+    const names = new Set()
+    for (const field of controls) {
+      // A radio group shares one name BY DESIGN to mean "pick one" and keeps
+      // its single checked value, `[]` suffix or not.
+      if (field.type === "radio") continue
+      if (String(field.name).endsWith("[]")) names.add(field.name)
+    }
+    return names
+  }
+
+  // Names whose group carries a hidden COMPANION: a hidden input is Rails' way
+  // of giving a checkbox a value for the unchecked case, and it is never a
+  // chosen value. Measured from the helpers, the three shapes are:
+  //
+  //   check_box(:u, :sub)
+  //     <input name="u[sub]" type="hidden" value="0"><input type="checkbox" value="1" name="u[sub]">
+  //   check_box(:u, :ids, {multiple: true}, "3")
+  //     <input name="u[ids][]" type="hidden" value="0"><input type="checkbox" value="3" name="u[ids][]">
+  //   collection_check_boxes(...) / an unchecked_value of nil
+  //     <input type="hidden" name="u[ids][]" value="">  — or no hidden at all
+  //
+  // The value differs (unchecked_value, blank, absent), so the value cannot be
+  // the test. What identifies a companion is that a checkbox shares its name.
+  // A hidden WITHOUT a same-named checkbox is a list JS maintains, and its
+  // value is a chosen value like any other.
+  #companionNames(controls) {
+    const names = new Set()
+    for (const field of controls) if (field.type === "checkbox") names.add(field.name)
+    return names
+  }
+
   // Re-compute the dirty flag for EVERY field this root owns in one pass (issue
   // #103), then reflect the total onto the root. Called on an owned field's input
   // (trackDirty), on connect (baseline seed), and after a turbo:morph-element
@@ -4759,9 +5340,35 @@ export default class extends Controller {
     const fd = new FormData()
     fd.append("token", token)
     fd.append("act", action)
+    const emptyGroups = []
     for (const [key, value] of Object.entries(params)) {
-      this.#appendField(fd, this.#wireKey(key), value)
+      // A `[]` name carrying an array is the group shape (issue #258): every
+      // element goes to params[name][], which Rack parses as an array. The
+      // indexed form #appendField writes for a plain array (params[name][0],
+      // params[name][1]) arrives as a hash of index keys — ParamSchema's array
+      // type normalizes that back, but only an array type does, so the two
+      // bodies would stop coercing identically for the same fields.
+      //
+      // An EMPTY group cannot be an empty array in a form body, so it is
+      // ANNOUNCED instead: its key stays absent from params and its name goes
+      // into `empty_groups[]`, a field of its own beside token/act/params. A
+      // blank entry was the obvious alternative and is ambiguous — Rails leaves
+      // `[""]` to the caller, and a `[:date]` or `[:file]` element reads it as
+      // "did not come in", so treating it as "cleared" would change what those
+      // params mean. The field is additive: a server that ignores it behaves
+      // exactly as it does today, and so does a client that never sends it.
+      if (Array.isArray(value) && String(key).endsWith("[]")) {
+        if (value.length === 0) {
+          emptyGroups.push(String(key).slice(0, -2))
+        } else {
+          const wire = `${this.#wireKey(key)}[]`
+          for (const element of value) fd.append(wire, String(element))
+        }
+      } else {
+        this.#appendField(fd, this.#wireKey(key), value)
+      }
     }
+    for (const name of emptyGroups) fd.append("empty_groups[]", name)
     const multiNames = this.#multiFileNames(files)
     for (const { name, file, multiple } of files) {
       // params[name][] when the input is `multiple` (array shape even for one