phlex-reactive 0.13.2 → 0.13.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb580ca60e8e64b7857e665f34e5311e35f66c8aa4348135c61286456b06649f
-  data.tar.gz: fb25bb13bd78f0923f6a7a3c5ea383101cca16eaf9b808607e074c49dbbaa583
+  metadata.gz: ce768022637774ec42b7bca32e6533613fb563c792d9c82f58c8b07eea722e7f
+  data.tar.gz: 42a470435e59c6a364f3845a4626bdbb0b8e23a1cc7aadcb0c2281b89c922555
 SHA512:
-  metadata.gz: 6d50f4794edea6b74bf4178df8d4a271e947e8bc3eef268d19ba8cb855c3207e87ee9c3bd345a22b3d9192f58510bb00860278c64a59c7f1e1b3478b72af62c0
-  data.tar.gz: '0233287800960c1886865f7df4fe2785237820d16e212b616e1971c879d0a97abd373f55588f2921aef4bd742d8cb053ffb2b560a81862517767dbd883556fac'
+  metadata.gz: d2f238f055aabaf9466212ab07158ae2ba40139207b77b118b12fcafb18ca43ad14a2f48b82ea666345375e19afd499bba456c9bec4e978b12875a560f215637
+  data.tar.gz: 19105c1e86bec4015e9be48f42b4580c0adf6fa70fa1a00d6b5e4c2c5e9a3f5f297095b4fbaf9dcca3a49a6b6c254ef1070998b7f895e4bf6de085d5d152e66d

data/CHANGELOG.md

@@ -9,6 +9,41 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Several `on_client` bindings on one element (#271).** Two `on_client`
+  calls merged with `mix` now both work — e.g. a root that closes a menu on an
+  outside click AND on Escape. Each call carries its own descriptor, flags and
+  `confirm:`, and the client runs only the binding whose event (type, key
+  filter, window-boundness) fired. An outside guard or confirm never leaks onto
+  a sibling binding.
+
+- **`toggle_attr(to, name, on, off)` — flip between two values (#271).**
+  `js.toggle_attr("#trigger", "aria-expanded", "true", "false")` keeps a
+  two-valued attribute (`aria-expanded`, `aria-pressed`, `data-state`) honest;
+  an absent attribute becomes `on`. One value, or two equal values, raise at
+  build time. Without values it is the presence toggle it always was.
+
+- **`expanded:` on `show`/`hide`/`toggle` (#271).** `js.toggle("#menu",
+  expanded: "#trigger")` writes the op's intended state into the trigger's
+  `aria-expanded` (`show` → `"true"`, `hide` → `"false"`, `toggle` → the
+  state after the flip: `"true"` when the target was hidden), before any
+  transition. Resolved with the op's own scoping.
+
+- **`reactive_listnav(focus: true)` — roving focus for menus (#271).** Spread
+  on a `role="menu"` container: Arrow Down/Up move real focus among
+  `[role=menuitem]` (wrapping), Home/End jump to the edges. Enter/Space stay
+  native activation; Escape is the caller's `on_client("keydown.esc", …)`.
+  Without `focus:` the helper is byte-identical to before.
+
+- **`pending_template` — opt-in pending MARKUP for `reply.pending` (#249).** A
+  row component that defines `pending_template` now has its markup swapped by
+  `reply.pending` (a real "Queued" badge, a genuinely removed button), in
+  addition to the #248 markers. The swap renders a memoized anonymous subclass
+  whose `.name` is the row's own, so a row that signs its token still verifies
+  on its next action; the memo resets on Rails code reload. A template that
+  drops the row's `id` raises before anything is enqueued. Rows without the
+  hook are byte-identical to before. The swapped markup is undone only by a
+  settle that replaces or removes the row.
+
 - **`bin/release` — the release front door, ported from pgbus.** Works out the
   next version (`patch` by default, `minor`, `major`, or an explicit `X.Y.Z`
   with an optional `v`), prints the commits since the last tag, and hands off
@@ -441,6 +476,141 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **`reactive_compute` never saw a checkbox's checked state (#262).**
+  `#recompute` resolved each declared name first-wins and read `.value`, which
+  for a checkbox is a constant. Measured: a Rails `check_box` pair read `0`
+  ticked or not (the hidden companion comes first), a lone `value="1"` box read
+  `1` either way, and a box with no value attribute read `0` (`Number("on")` is
+  NaN). A radio group read its FIRST radio's value, whichever was checked. The
+  reducer ran on the toggle, from values that could not have changed.
+
+  A checkbox now contributes its checked state, coerced by the declared type:
+  `1`/`0` as a `:number` (and in the array form), `"true"`/`"false"` as a
+  `:string`, and `true`/`false` under the new **`:boolean`** type. It wins over
+  its same-named hidden companion, as it already did for `reactive_show`. A radio
+  group contributes its checked radio's value. The identity mirror and the
+  `mirror:` fallback paint the same reading.
+
+  Outputs were wrong the same way: a result whose name resolved to a checkbox
+  pair wrote `.value` on the hidden companion, changing what the UNCHECKED state
+  submits and leaving the box alone. An output now sets a checkbox's `checked`
+  from the result's truthiness (`""`, `"0"`, `"false"`, `0` and `false` untick)
+  and checks the radio of a group that carries the result.
+
+  **If a reducer relied on the old reading**, it changes: a lone checkbox with a
+  numeric `value` used to read that number regardless of state and now reads
+  `1`/`0` — write the amount in the reducer (`gift ? 25 : 0`). Apps that worked
+  around the defect by reading the box from `document` inside the reducer keep
+  working and can drop the workaround.
+
+  Cost, same machine, happy-dom (engine-relative): the 30-input calculator
+  bench goes from 16.3 to 18.4 µs/iter, allocations flat. That is one `el.type`
+  read per declared name, which is what telling a checkbox from a text field
+  takes.
+
+- **The dropped-param hints said nothing for a schema with string keys.**
+  `ParamSchema.compile` keeps keys as the author wrote them, so
+  `params: { "date" => :string }` is valid, but the #16/#21 hints only looked
+  up symbol keys. The param was still dropped and logged, just without the hint
+  that says where the schema declares it.
+
+- **A checkbox group collapsed to one boolean, and the chosen values never left
+  the browser (#258).** `#collectFields` wrote `fields[name] = field.checked` for
+  every checkbox, so several boxes sharing a `features[]` name overwrote each
+  other and the action received the LAST box's checked state — `{}` under a
+  `[:string]` schema, `"false"` under a flat `:string` one, silent either way,
+  while a native submission of the same boxes sends
+  `features[]=news&features[]=events`. A name ending in `[]` is now collected as
+  an array of the chosen values: a ticked box contributes its `value`, an
+  unticked one nothing, a `<select multiple>` its selected options. The suffix is
+  the only trigger — a group says so rather than being inferred from two controls
+  sharing a name.
+
+  **That makes the suffix a migration point.** ANY `[]`-named control now
+  contributes to an array, including a single one and including a named rich
+  editor or bare contenteditable, which the collector reads in a second pass: a
+  lone `<input type="text" name="tags[]">` used to post `"abc"` and now posts
+  `["abc"]`. An editor sharing its `[]` name with another control adds its
+  value to the group instead of standing down behind it, so the entry count
+  changes there too. Beside a radio it still stands down, because a radio keeps
+  its single value with or without the suffix. A ready but empty editor
+  contributes an empty string, the way an empty text field in the same group
+  does. An unticked box still contributes nothing. A hidden input under the
+  same name keeps contributing: nothing in the DOM tells a hidden that mirrors
+  an editor from one that is a list JS maintains, and a value posted twice is
+  visible where a swallowed one is not. Against a flat `params: { tags: :string
+  }` the array coerces to the literal `"[\"abc\"]"` — silently, with a 200. A
+  control whose name ends in `[]` has to be declared as an array type (`tags:
+  [:string]`), or renamed without the suffix if it was never meant as a list.
+
+  Three shapes keep their meaning on purpose: a lone checkbox without `[]` stays
+  the documented yes/no boolean, a radio group keeps its single checked value
+  with or without the suffix, and a hidden input sharing a name with a checkbox
+  is that box's companion. The companion is identified by the shared name, not
+  by its value, because Rails renders three of them: `check_box` emits
+  `value="0"`, `check_box(..., multiple: true)` the same under a `[]` name, and
+  `collection_check_boxes` a blank one — or none at all with
+  `unchecked_value: nil`. Reading the second shape by value collected
+  `["0","0","0","3"]` for three boxes with the third ticked.
+
+  A form body can't carry an empty array, so a cleared group used to go missing
+  whenever the client sent a form body (as soon as a file input holds a file),
+  and the action got its keyword default instead of `[]`. Now the client names
+  the cleared group in `empty_groups[]`, a field next to `token`, `act` and
+  `params`, and the endpoint sets it to `[]`. A request without that field
+  behaves as before, and a group that carries values keeps them.
+
+  It applies to params the action declares as an array, by plain name or with
+  the component's `reactive_scope` in front, and only at the top level. A group
+  declared one level down or inside nested attributes is ignored and keeps its
+  keyword default; `verbose_errors` logs it. The endpoint never takes the key it
+  writes from the request. It looks the name up in the declaration and writes
+  the declared key, so a request can't create a param the action didn't ask for.
+
+  A blank entry (`params[name][]=""`) would have been the other way, but the
+  schema reads `[""]` per element type, and for a `[:file]` param behind
+  `has_many_attached` that is the difference between "not sent" and "remove the
+  attachments".
+
+  `post_reactive_multipart` takes `empty_groups:` so a request spec can send a
+  cleared group the way the client does. `ParamSchema#array_param(name)`
+  returns the declared key for an array param, or `nil`.
+
+  `reactive_persist` drafts such a group as the list of ticked values and
+  restores exactly those boxes; before, the draft held one boolean and the
+  restore ticked every box of the group. Whether the server already rendered a
+  box ticked — in which case it keeps its say and the draft yields — is decided
+  once before the restore walks the controls, because the walk writes `checked`
+  as it goes and asking from inside it would read the restore's own work: the
+  first box it ticks would make every later box of the group look
+  server-rendered, and a draft of two values would come back as one. A
+  non-checkbox control sharing the group's name additionally threw inside the
+  draft write, which is swallowed — the root then persisted nothing at all,
+  silently. On restore, such a control keeps what the server rendered whenever
+  the group has two or more contributors: the list records the values, not
+  which control each one came from, so replaying it would paste `freeform,news`
+  into a text field, an editor, or a contenteditable. A group of ONE
+  contributor has no such ambiguity — its single entry can only have come from
+  that control — so a plain field whose name merely ends in `[]`, the usual
+  shape for a list JS maintains, keeps its draft exactly as it did before
+  groups existed. A `<select multiple>` reads a list by matching option values,
+  which is only sound when the list is its own: sharing a group with another
+  contributor, it too keeps what the server rendered, since a text value that
+  happens to equal an option would otherwise select it.
+
+  Drafts written before this release are not discarded, but their group key is
+  no longer applied to the controls that read a list: it holds one boolean (or,
+  in a mixed group, whichever control wrote last), and applying that kept
+  causing damage for as long as the draft lived — by default seven days after
+  the upgrade. The damage differed by control. A checkbox group came back fully
+  ticked. A `<select multiple>` sharing the group's name lost its rendered
+  selection instead, because under `restore: "always"` the select branch skips
+  the "the server had a say" check and matches `Set{"true"}` against its
+  options, where nothing matches. The next snapshot replaces the key with the
+  list. Only that one key changed meaning, which is why `PERSIST_VERSION` stays
+  where it is: bumping it would also throw away the drafted prose of every form
+  that has no checkbox group at all.
+
 - **`reply.pending` kept its settle handle under
   `enqueue_after_transaction_commit = true` (#254).** The handle was captured in
   `Phlex::Reactive::Settles#serialize`, which reads a thread-local that lives
@@ -622,6 +792,18 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **`on_client` emits a binding record (#271).** `data-reactive-ops-param` now
+  holds `{"on":…,"ops":[…], "window"?, "outside"?, "confirm"?, "confirmWhen"?}`
+  instead of the bare `[[op, args]]` list, with every space written as
+  `\u0020`. `on_client` no longer writes the element-wide
+  `data-reactive-outside-param` / `-window-param` / `-confirm-param` /
+  `-confirm-when-param` (`on(...)` still does). A hand-built legacy
+  `[[op, args]]` attribute still runs, reading its flags from those params as
+  before. **Upgrade note:** apps served by the engine's importmap pin get the
+  matching client automatically; an app that bundles its own copy of
+  `reactive_controller.js` must rebuild from the shipped source, or its
+  `on_client` triggers go dead (the old client parses only arrays).
+
 - **Client build toolchain: bun 1.3.14 → 1.4.0.** `.bun-version`, the root `engines.bun`
   floor, and the docs `packageManager` pin all move together. The shipped
   `*.min.js` / `.map` artifacts (and their vendored twins under

data/README.md

@@ -385,7 +385,7 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `busy_on(:save)` | Mark any element so it carries `data-reactive-busy` **only while `save` is in flight** — a spinner styled with pure CSS, zero Ruby. See [Loading states](#declarative-loading-states-loading--disable_with). |
 | `on(:action, once: true)` | Fire at most once, then unbind (Stimulus's native `:once`). |
 | `on_client(:click, js.toggle("#menu"))` | **Client-only** trigger: applies declared DOM ops with ZERO round trip — no token, no POST, ever. Takes the same `window:`/`once:`/`outside:` modifiers. See [Client-only ops](#client-only-ops-on_client--js--zero-round-trips). |
-| `js` | The immutable op builder behind `on_client`: `show`/`hide`/`toggle` (the `hidden` attribute, with an optional `transition:`), `add_class`/`remove_class`/`toggle_class`, `set_attr`/`remove_attr`/`toggle_attr` (allowlisted names), `focus`/`focus_first`, `text` (set `textContent` — XSS-safe), `dispatch`, `submit` (requestSubmit the target's own form), `paste_into` (read the clipboard into a field, gesture-gated), and `persist_state`/`persist_clear` (the `reactive_persist` draft) — chainable. |
+| `js` | The immutable op builder behind `on_client`: `show`/`hide`/`toggle` (the `hidden` attribute, with an optional `transition:` and `expanded:`), `add_class`/`remove_class`/`toggle_class`, `set_attr`/`remove_attr`/`toggle_attr` (allowlisted names; `toggle_attr` also flips between two values), `focus`/`focus_first`, `text` (set `textContent` — XSS-safe), `dispatch`, `submit` (requestSubmit the target's own form), `paste_into` (read the clipboard into a field, gesture-gated), and `persist_state`/`persist_clear` (the `reactive_persist` draft) — chainable. |
 | `reactive_field(:param, **attrs)` | The attribute hash that binds a control to an action param (no magic `name:`) — spread onto any control: `input(**reactive_field(:value, value: @record.name))`, `select(**reactive_field(:status)) { … }`. |
 | `reactive_text(:name, initial)` | Mirror a compute output (or a declared input) into a **text node** — a live preview heading, a character counter, `"Hello, {name}"` — via `textContent` (XSS-safe). The text sibling of `reactive_field`; carries no `name`, so it's never POSTed. See [Client-side computes](#client-side-computes-reactive_compute--reactive_text). |
 | `reactive_show(if:/if_any:/unless:)` | **Value-conditional visibility** (the `x-show`/`data-show` case): spread onto the element to show/hide — it toggles `hidden` from the fields' **current values**, client-only, zero round trip. One conditions language: a **Hash is an AND**, an **Array is membership**, a **Range is a threshold**, `if_any:` is OR-of-AND, `unless:` negates. `reactive_values` computes first paint; `disable:` disables a hidden section's controls. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
@@ -393,10 +393,10 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_persist(key:, ttl: 7.days)` | **Client-only drafts**: spread on the **root** (once) and the generic controller keeps a `localStorage` draft of every **owned** control — debounced write on `input`, immediate on `change`, flushed on disconnect, restored into **blank** controls on the next connect (`restore: :always` lets the draft win), cleared by a successful Turbo submit / `ttl` / `js.persist_clear`. Never hidden/file/password; `reactive_persist_skip` opts a control out; `fields:` narrows. See [Client-only drafts](#client-only-drafts-reactive_persist). |
 | `js.persist_state(step: 2)` / `js.persist_clear` | The draft ops (actor-only): merge a flat state bag into the draft (restored as `data-reactive-persist-state` + the `reactive:persist-restored` event) / forget the draft. |
 | `reactive_filter(:field, option: nil, group: nil, empty: nil)` | **Client-side option filtering** for a preloaded combobox: spread onto the root and name the **field** that drives it — `reactive_filter(:q)` compiles `:q` to `[name="q"]` (scope-aware) and typing shows/hides the options by their `data-reactive-filter-text` haystack, **zero round trips**. `option:` defaults to `[role=option]`; optional `group:` collapses an all-hidden group header; `empty:` reveals a no-matches node. `input:` is the escape hatch — a raw CSS selector for a **name-less** driving input (`input: "#tags_query"`), the form-builder case. See [Client-side option filtering](#client-side-option-filtering-reactive_filter). |
-| `reactive_listnav("[role=option]")` | The **standalone** combobox keyboard wiring (Arrow/Enter/Escape) for an input that fires **no action** — the preload-and-filter case. Same behavior as `on(…, listnav:)`, minus the POST. |
+| `reactive_listnav("[role=option]")` | The **standalone** combobox keyboard wiring (Arrow/Enter/Escape) for an input that fires **no action** — the preload-and-filter case. Same behavior as `on(…, listnav:)`, minus the POST. `reactive_listnav(focus: true)` is the **roving-focus** variant for a `role="menu"` container: Arrow Down/Up move real focus among `[role=menuitem]` (wrapping), Home/End jump to the edges; Enter/Space stay native and Escape is yours to bind. |
 | `reactive_tags(:tags)` | **Tag-chip input** (the combobox/tags widget): spread onto the root and name the hidden field that stores the **comma-joined** value — the client maintains that field + the chip list entirely client-side (form state, zero round trips), rebuilding chips from your server-owned `<template>`. Composes with `reactive_filter` (type to narrow) and `reactive_listnav` (Enter picks the highlighted option). `name:` is the escape hatch — a **verbatim** wire name (`name: "user[tags]"`, never re-scoped), the form-builder case. See [Tag-chip input](#tag-chip-input-reactive_tags). |
 | `reactive_tags_add` / `reactive_tags_option(tag)` / `reactive_tags_remove(tag)` | The tags triggers, all **client-only**: `reactive_tags_add` on the query input adds the typed text on Enter (mix it **after** `reactive_listnav`; Enter never submits the enclosing form); `reactive_tags_option` makes a preloaded suggestion add its declared tag on click; `reactive_tags_remove` is a chip's remove button (no arg inside the template — the client fills the tag per chip). |
-| `reactive_compute :name, inputs: { title: :string, qty: :number }, outputs:` | **Typed** inputs: a `:string` reaches the JS reducer raw, a `:number` is coerced through `Number`. The array form (`inputs: %i[a b]`) stays all-numeric; the **permit-style** form (`inputs: [:qty, title: :string]`) mixes both — bare symbols default `:number`, a trailing hash types the exceptions. `outputs:` is the field allowlist; a reducer-result key also paints any owned `reactive_text` node by presence and any `mirror:` id, so an `outputs:` entry that exists only to reach a text node is redundant (harmless — a widening). |
+| `reactive_compute :name, inputs: { title: :string, qty: :number }, outputs:` | **Typed** inputs: a `:string` reaches the JS reducer raw, a `:number` is coerced through `Number`, a `:boolean` is a checkbox's checked state. The array form (`inputs: %i[a b]`) stays all-numeric; the **permit-style** form (`inputs: [:qty, title: :string]`) mixes both — bare symbols default `:number`, a trailing hash types the exceptions. `outputs:` is the field allowlist; a reducer-result key also paints any owned `reactive_text` node by presence and any `mirror:` id, so an `outputs:` entry that exists only to reach a text node is redundant (harmless — a widening). |
 | `reactive_compute :name, ..., mirror: { sum: "#summary-sum" }` | **Cross-root text mirrors**: paint a compute value into declared, id-allowlisted nodes **outside** the reactive root (a recap in another tab pane) via `textContent` — no bespoke listener. See [Cross-root mirrors](#cross-root-mirrors-mirror--painting-a-recap-outside-the-root). |
 | `reactive_dirty` / `reactive_dirty warn_unsaved: true` / `reactive_dirty only: %i[...]` | **Dirty tracking**, declared once at the class level, against the DOM's own `defaultValue`/`defaultChecked`/`defaultSelected` — no client state. Marks changed fields + the root `data-reactive-dirty`; `warn_unsaved:` arms a `beforeunload`/`turbo:before-visit` guard; `only:` scopes tracking to named fields. Style with `[data-reactive-dirty]`. See [Dirty-field tracking](#dirty-field-tracking-reactive_dirty). |
 | `nested_update!(:assoc, attrs)` | Map a nested param onto `<assoc>_attributes` with id preservation; update the record. |
@@ -491,12 +491,55 @@ def view_template
 end
 ```
 
-> **One multipart caveat:** `FormData` can't carry an *empty* array or hash, so on
-> the multipart (file-present) path an empty `[]`/`{}` param is **omitted** and the
-> action's keyword default applies — it does **not** arrive as an explicit empty
-> collection the way it does over JSON. If you rely on sending `tags: []` to clear
-> a collection, send that action *without* a file (the JSON path). A non-empty
-> nested/array param rides along fine next to a file.
+> **Clearing a checkbox group next to a file.** When the reactive root holds a
+> file, the action goes out as `FormData`, and `FormData` has no way to write an
+> empty array. A group with values is fine: each value goes out as
+> `params[name][]`. A group with nothing ticked would simply be missing, so the
+> client lists its name in a separate field, `empty_groups[]`, and the endpoint
+> sets that param to `[]`. The action gets the same value it would get over JSON.
+>
+> This works for any param the action declares as an array, by its plain name or
+> with the component's `reactive_scope` in front. A `features[]` group is
+> announced as `features`, and a `todo[tags][]` group under `reactive_scope :todo`
+> as `todo[tags]`. Under a scope you write the group's name by hand, because
+> `reactive_field(:"tags[]")` gives `todo[tags[]]`, which isn't read as a group:
+>
+> ```ruby
+> input(type: "checkbox", name: "todo[tags][]", value: "ruby")   # reactive_scope :todo
+> ```
+>
+> The endpoint only fills a key the body didn't send, and only at the top level.
+> A group declared one level down (`params: { project: { features: [:string] } }`)
+> or inside nested attributes is left alone, and the action gets its keyword
+> default as before. With `verbose_errors` on, the log tells you when that happens.
+>
+> Other empty `[]` or `{}` params are still left out of a form body. If you rely
+> on `tags: []` to clear something that isn't a `[]` group, send that action
+> without a file.
+
+**Checkbox groups.** Controls sharing a name that ends in `[]` are collected
+as an **array of the chosen values** — a ticked box contributes its `value`, an
+unticked one nothing, a `<select multiple>` its selected options. Nothing ticked is
+an empty array, not a missing key, so an action can tell a cleared group from one
+that never rendered, over a form body as well (see above). Declare it as an
+array type:
+
+```ruby
+action :save, params: { features: [:string] }   # <input type="checkbox" name="features[]" value="news">
+```
+
+Three shapes keep their own meaning: a lone checkbox without `[]` stays the
+documented yes/no boolean; a radio group keeps its single checked value, `[]` or
+not; and a hidden input sharing a name with a checkbox is that box's **companion**
+(Rails' `check_box` emits one, carrying the `unchecked_value`) and contributes
+nothing. A hidden input *without* a same-named checkbox is an ordinary value — the
+usual shape for a list maintained by JS.
+
+The suffix is the only trigger, and it applies to a single control too: a lone
+`<input type="text" name="tags[]">` posts `["abc"]` where it used to post
+`"abc"`. Declare such a param as an array type (`tags: [:string]`) — against a
+flat `tags: :string` the array coerces to its literal `to_s`. If the `[]` was
+never meant as a list, drop it from the name.
 
 **Array & nested params.** Wrap a type in an array for an array param, or a hash
 schema in an array for Rails-style nested attributes — so one reactive action can
@@ -849,7 +892,10 @@ button(**on_client(:click, js
 ```
 
 - **`set_attr(to, name, value)` / `remove_attr(to, name)` / `toggle_attr(to, name)`**
-  mutate an attribute. The **attribute name is allowlisted, enforced twice** — at
+  mutate an attribute. `toggle_attr(to, name, on, off)` (#271) flips **between two
+  values** instead of toggling presence — `toggle_attr("#trigger", "aria-expanded",
+  "true", "false")`; an absent attribute becomes `on`, and one value or two equal
+  values raise at build time. The **attribute name is allowlisted, enforced twice** — at
   build time in Ruby (an offending name raises) and again in the client
   interpreter (a hand-built op is warned and skipped). Refused: **event handlers**
   (`on*` → XSS), **URL-bearing** names (`href`, `src`, `srcdoc`, `action`,
@@ -897,6 +943,14 @@ button(**on_client(:click, js
   (a broadcast that reads every subscriber's clipboard would be hostile). The
   op is async fire-and-forget — chained siblings apply immediately, never
   waiting for the read.
+- **`expanded:`** on `show`/`hide`/`toggle` (#271) keeps a disclosure trigger's
+  `aria-expanded` honest: `js.toggle("#menu", expanded: "#trigger")` writes the
+  op's **intended** state (`show` → `"true"`, `hide` → `"false"`, `toggle` → the
+  state after the flip: `"true"` when the target was hidden, `"false"` when it
+  was visible) onto the target — set before any transition runs. It resolves
+  with the op's own scoping (`:root`, a root-scoped selector, or document-wide
+  under `global: true`). Pair it with one disclosure target; with several, the
+  last one wins.
 - **`transition: { during:, from:, to: }`** on `show`/`hide`/`toggle` animates the
   visibility flip: `during`+`from` are applied, then `from`→`to` swaps on the next
   frame, and the helper classes are cleaned up on `animationend` (with a timeout
@@ -907,6 +961,32 @@ button(**on_client(:click, js
 modifiers: the dropdown above closes on any click outside the component, and
 window-bound triggers never `preventDefault`, so links elsewhere keep working.
 
+**Several bindings on one element (#271).** Each `on_client` call emits one
+self-describing **binding record** — its descriptor, flags, `confirm:` and ops —
+so two calls compose through `mix`. The descriptors token-join; the records
+space-join (spaces inside a record ride as `\u0020`); the client runs only the
+record whose descriptor matches the firing event (event type, key filter,
+window-boundness):
+
+```ruby
+div(**mix(reactive_root,
+          on_client(:click, js.hide("#menu", expanded: "#trigger"), outside: true),
+          on_client("keydown.esc", js.hide("#menu", expanded: "#trigger").focus("#trigger"))))
+# data-action="click@window->reactive#runOps keydown.esc->reactive#runOps"
+# data-reactive-ops-param='{"on":"click","window":true,"outside":true,"ops":[…]} {"on":"keydown.esc","ops":[…]}'
+```
+
+An outside guard or a `confirm:` belongs to its own binding only — it never
+gates a sibling. Two element-bound `:click` calls on the same `<button>` still
+collide on the forced `type="button"` (`mix` renders `type="button button"`):
+chain the ops into one call instead.
+
+**An accessible menu with no custom JS.** Pair the above with
+`reactive_listnav(focus: true)` on the `role="menu"` list — Arrow Down/Up rove
+real focus among `[role=menuitem]` (wrapping), Home/End jump to the edges — and
+the whole WAI-ARIA menu-button pattern is declared ops. See the
+[client-only ops example](https://phlex-reactive.zoolutions.llc/docs/example-client-ops).
+
 **The general autosubmit story.** With `submit` in the vocabulary, the classic
 `onchange="this.form.requestSubmit()"` filter form is one declared line — no
 bespoke controller, no reactive action, and Turbo Drive turns the resulting
@@ -1244,6 +1324,29 @@ setComputeReducer("preview", ({ title }) => ({
   **permit-style form** (`inputs: [:qty, title: :string]`) combines both in one
   declaration — bare symbols default to `:number`, a trailing hash types the
   exceptions.
+- **Checkboxes and radios read their checked state.** A checkbox's `.value` is a
+  constant, so a compute reads whether the box is ticked instead, coerced by the
+  declared type: `1`/`0` as a `:number` (and in the array form),
+  `"true"`/`"false"` as a `:string`, `true`/`false` as a **`:boolean`**. The
+  checkbox wins over the hidden companion Rails' `check_box` renders before it.
+  A radio group reads its checked radio's value (`""`, or `0` as a number, when
+  none is checked). A `:boolean` on any other control is `false` for `""`, `"0"`
+  and `"false"`.
+
+  ```ruby
+  reactive_compute :total, inputs: [:price, { gift_wrap: :boolean }], outputs: %i[total]
+  ```
+
+  ```js
+  setComputeReducer("total", ({ price, gift_wrap }) => ({ total: price + (gift_wrap ? 25 : 0) }))
+  ```
+
+  An **output** that resolves to a checkbox sets `checked` from the result's
+  truthiness, and one that resolves to a radio group checks the radio carrying
+  the result (a value no radio carries clears the group). Neither rewrites a
+  `value` attribute, so what the control submits is unchanged. A `[]`-named
+  checkbox *group* is not a compute input — compute values are scalars; declare
+  each box under its own name.
 - **`reactive_text(:name, initial)`** mirrors a value into a **text node** via
   `textContent` (XSS-safe by construction). Every reducer-result key paints any
   matching sink: an owned **field** if declared in `outputs:`, any owned
@@ -2569,6 +2672,44 @@ bug). It emits:
 3. an inert `reactive:token` refresh, so the container's signed token rolls
    forward and the list is not act-once-only.
 
+#### Honest pending markup: `pending_template` (opt-in)
+
+The markers dim a *live* row. When the pending state should be real markup — a
+"Queued" badge, a button that is genuinely gone rather than hidden by
+`pointer-events: none` — define `pending_template` on the row component (private
+is fine). `reply.pending` then also **replaces** each such row with it, just
+before marking it:
+
+```ruby
+class TransferRow < ApplicationComponent
+  include Phlex::Reactive::Streamable
+  include Phlex::Reactive::Component
+
+  def view_template
+    li(**mix(reactive_attrs, id:)) { span { @transfer.label }; button(**on(:retry)) { "Retry" } }
+  end
+
+  private
+
+  def pending_template
+    li(**mix(reactive_attrs, id:)) { span { @transfer.label }; span(class: "badge") { "Queued" } }
+  end
+end
+```
+
+A row without the hook is byte-identical to the marker-only reply.
+
+- **Keep the root's `id`.** The settle targets it; a `pending_template` without
+  `id="<the row's id>"` raises before anything is enqueued.
+- **Keep `reactive_attrs`** if the row carries its own token — the swapped row
+  signs the row class's real name, so its next action verifies as usual.
+- **Un-pending is the settle's job.** Markers are attributes any settle strips;
+  swapped markup is only undone by a settle that replaces (`s.replace`) or
+  removes (`s.remove`) the row. A flash-only settle, `finish: true`, or a failed job clears the markers
+  but leaves the pending markup in place.
+- It is a *template* method, unlike `deferred_placeholder` (which returns inner
+  content for a shell the gem owns): here the row's own root is swapped.
+
 | `reply.pending(...)` | |
 |---|---|
 | `records` | one record, an enumerable of records, or built Streamable components |
@@ -3222,8 +3363,10 @@ endpoint maps it to 403). Matchers: `have_reactive_replace`,
 refresh so a reply that would silently break the next click fails your test.
 
 **HTTP helpers** — `post_reactive_action(component_or_class, act, params:, payload:)`
-and `post_reactive_multipart(...)` POST a signed token to
-`Phlex::Reactive.action_path` exactly as the client does. **Token minting** —
+and `post_reactive_multipart(..., empty_groups: [])` POST a signed token to
+`Phlex::Reactive.action_path` exactly as the client does; `empty_groups:` lists
+the groups the client cleared by name, without the `[]`, the way a form body
+sends them. **Token minting** —
 `reactive_token_for(component_or_class, payload = {})`.
 
 > `verbose_errors` defaults ON in test (it changes only an error BODY, never a

data/app/controllers/phlex/reactive/actions_controller.rb

@@ -556,6 +556,7 @@ module Phlex
       def coerce_params(action_def, component_class: nil, action_name: nil)
         dropped = Phlex::Reactive.verbose_errors ? [] : nil
         raw = unwrap_scope(params.fetch(:params, {}), component_class)
+        raw = apply_empty_groups(raw, action_def.schema, component_class, dropped) if params[:empty_groups]
 
         coerced = action_def.schema.coerce(raw, dropped)
         log_dropped_params(dropped, action_def.params, component_class, action_name)
@@ -570,7 +571,7 @@ module Phlex
       # raw params pass through untouched (unscoped components + nested_attributes
       # shapes are unaffected).
       def unwrap_scope(raw, component_class)
-        scope = component_class.reactive_scope if component_class.respond_to?(:reactive_scope)
+        scope = reactive_scope_of(component_class)
         return raw unless scope
 
         # At the endpoint `raw` is ActionController::Parameters, so `raw[scope]` is
@@ -580,6 +581,68 @@ module Phlex
         nested.is_a?(Hash) || nested.is_a?(ActionController::Parameters) ? nested : raw
       end
 
+      # Issue #258: a form body cannot carry an empty array, so the client
+      # ANNOUNCES a cleared `[]` group — its key absent from params, its name in
+      # `empty_groups[]` beside token/act/params. Those names are written back as
+      # empty arrays, the value the JSON path sends outright. The README documents
+      # what the rule accepts and what it leaves alone.
+      #
+      # The key written is whatever `array_param` hands back, so it is always a
+      # key the DECLARATION holds — never the announced name, which is only ever
+      # compared. Runs AFTER unwrap_scope so the params root is the only target:
+      # no node is built to reach a group, hence no nested-attributes row.
+      def apply_empty_groups(raw, schema, component_class, dropped)
+        names = params[:empty_groups]
+        return raw unless names.is_a?(Array)
+        # `raw` is whatever arrived: a String from `params=x` in a query string
+        # normalises to {} in coerce, but writing into it would raise.
+        return raw unless raw.is_a?(Hash) || raw.is_a?(ActionController::Parameters)
+
+        scope = reactive_scope_of(component_class)
+        # Flat is enough — only the root is written — and it keeps the filled key
+        # off the request's own params object.
+        raw = raw.dup
+        names.each do
+          key = announced_key(it, schema, scope)
+          # Its OWN reason, not :undeclared: that one routes through the #16/#21
+          # shape hints, which would read `empty_groups` as a param and advise
+          # nesting the group under it. `dropped` is nil unless verbose_errors.
+          next dropped&.<<(["empty_groups #{it}", ANNOUNCED_UNDECLARED]) unless key
+
+          raw[key] = [] unless raw.key?(key)
+        end
+        raw
+      end
+
+      ANNOUNCED_UNDECLARED = :"undeclared — the action declares no array param by that name"
+      private_constant :ANNOUNCED_UNDECLARED
+
+      # The declared key an announced name resolves to, or nil — bare (`tags`) or
+      # carrying the component's scope (`todo[tags]`), the two shapes the client
+      # emits for one group. Anything else resolves to nothing, whatever its
+      # type: array_param only answers with a key it already holds.
+      def announced_key(name, schema, scope)
+        schema.array_param(unscoped_group_name(name.to_s, scope))
+      end
+
+      # `todo[tags]` => `tags` under `reactive_scope :todo`. One level off the
+      # front, never a walk — a deeper name (todo[a][tags]) keeps its remaining
+      # brackets and simply fails the lookup.
+      def unscoped_group_name(name, scope)
+        return name unless scope
+
+        prefix = "#{scope}["
+        return name unless name.start_with?(prefix) && name.end_with?("]")
+
+        name.delete_prefix(prefix).delete_suffix("]")
+      end
+
+      # Read the way unwrap_scope reads it — the peel and this strip have to
+      # agree on the scope or an announced name lands at the wrong depth.
+      def reactive_scope_of(component_class)
+        component_class.reactive_scope if component_class.respond_to?(:reactive_scope)
+      end
+
       # ---- verbose_errors dropped-param logging --------------------------
       # ParamSchema collects the dropped entries; the controller formats the ONE
       # warn line (with the #16/#21 shape hints). Everything below runs ONLY when
@@ -615,7 +678,7 @@ module Phlex
         segments = bracket_path(path)
         if segments.length > 1
           leaf = segments.last
-          return unless schema.key?(leaf.to_sym)
+          return unless declared_key?(schema, leaf)
 
           "schema declares :#{leaf} at top level; nested schemas look like " \
             "{ #{segments.first}: { #{leaf}: :string } }"
@@ -628,12 +691,18 @@ module Phlex
         end
       end
 
+      # A schema declares `name` whether it was written with a symbol or a
+      # string key; ParamSchema.compile keeps whichever the author used.
+      def declared_key?(schema, name)
+        schema.key?(name.to_sym) || schema.key?(name.to_s)
+      end
+
       # The first schema key whose nested hash (or array-of-hash element
       # schema) declares `name` one level down.
       def nested_declaration_of(name, schema)
         schema.find do |_key, type|
           inner = type.is_a?(Array) ? type.first : type
-          inner.is_a?(Hash) && inner.key?(name.to_sym)
+          inner.is_a?(Hash) && declared_key?(inner, name)
         end&.first
       end
 

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

@@ -28,13 +28,21 @@
 //            issue #104) arrive as the RAW string. `reactive_compute :x, inputs:
 //            { title: :string, qty: :number }` is what selects per-input types;
 //            `inputs: %i[a b]` stays all-numeric (backward compatible).
+//            A CHECKBOX arrives as its checked state, never its constant
+//            .value (issue #262): 1/0 untyped or :number, "true"/"false" as a
+//            :string, true/false as a :boolean. A radio group arrives as its
+//            checked radio's value ("" / 0 when none is checked).
 //   meta   — { changed }: the name (string) of the declared input the
 //            triggering event edited, or null (a direct recompute() call, or a
 //            target this root doesn't own / didn't declare as an input).
 //
 // OUTPUTS may be a form FIELD or a TEXT NODE (issue #104). An output whose name
 // matches an owned control writes its .value (+ the change-guarded input
-// dispatch below). An output with NO matching field writes textContent to every
+// dispatch below) — or, for a checkbox or a radio group, its CHECKED state
+// (issue #262): a truthy result ticks the box ("", "0", "false", 0 and false
+// untick it), and a radio group checks the radio carrying the result. Their
+// value attributes are never rewritten, so what they submit is unchanged.
+// An output with NO matching field writes textContent to every
 // owned [data-reactive-text="<name>"] node (reactive_text(:name)) — XSS-safe by
 // construction, change-guarded, NO input dispatch (a text node has no listener
 // contract). A declared INPUT also mirrors into its own text node on every