phlex-reactive 0.4.7 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a9dfa70408b2db2a88337edfc41963ead03b74cd83d919888b9e3b9bbf5eb99
-  data.tar.gz: 3adb9e76db58f23fd80ebbbc9cb50b08768bbf3473ee5f83375d89b781eda454
+  metadata.gz: 2858c45de31c08fa46914064af8c8177e0cecf507c7e908dc4239858f5c078b6
+  data.tar.gz: 540758b5f0c04562edfe8a41719b129c863fe5079475a6cd114818804d4c337f
 SHA512:
-  metadata.gz: 3011d097ec4280eaac80d94d914287d9604a3413615875ac719100065ef20d694ac4025e2695483d782f0c99e5803027dc5d717d38a922f4d404f40d67d513d9
-  data.tar.gz: 35b1ec519c60fa7c2a4655b80ad2717d8eca2eb84f71f262ec67ca618b83582acbef81980ceb6125addfb6b47dc9dc5f732170291a507dd2246b1986ddb1097c
+  metadata.gz: 052426b076385bc6c23c04e9a5b9c0d15106c514ea7b7c640e4e407cd0517e8910b005038d62156121a43125babbc402806a7a7544b14be76da7b50993c3ab3e
+  data.tar.gz: 10ec149142e82a0e3627d060fea0ed267bcc8ff42f0799fbe22ae95d12119ff4a4f500eb6e6ad6ec05591adfb93dd5530b37a044949b614acdcac60fc589d74a

data/CHANGELOG.md

@@ -8,6 +8,76 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Combobox keyboard navigation — `on(:search, …, listnav: "[role=option]")` (#72).**
+  A search/combobox trigger can now declare client-side list navigation: Arrow
+  Up/Down move a highlight among the option elements IN-BROWSER (no round trip),
+  Enter picks the highlighted option by clicking its own `on(:select)` trigger
+  (so the selection stays a normal signed reactive action), and Escape clears —
+  all without a bespoke Stimulus controller. `listnav:` appends Stimulus's native
+  keyboard filters (`keydown.down/up/enter/esc->reactive#listnav*`) to the input's
+  `data-action` and marks the option selector; the generic controller's `listnav*`
+  handlers own the ephemeral highlight (a `data-reactive-highlighted` attribute,
+  never shipped as trusted state), mirroring `#recompute`. Only the highlight is
+  client-side — selection is still a default-deny, signed action. No new client
+  module (the handlers live in the existing controller); covered by unit (JS),
+  request, and real-browser system specs green under Puma AND Falcon.
+
+- **Keyboard triggers on `on(...)` via `event:` — Enter-to-submit /
+  Escape-to-cancel with no client JavaScript.** `event:` is interpolated straight
+  into the Stimulus action descriptor, so **Stimulus's native keyboard filters
+  just work**: `on(:add, event: "keydown.enter")` emits
+  `keydown.enter->reactive#dispatch` and the action fires only on Enter, not on
+  every keypress. `event: "keydown.esc"` gives Escape-to-cancel. No new option to
+  learn (it's Stimulus's own filter syntax), no client change, no vendored-client
+  re-sync — and, deliberately, **no reserved `key:` keyword**, so `key` stays a
+  normal action-param name (`on(:switch, key: "pgbus")` keeps passing `key`
+  through as a param — no backward-incompatibility). Because a keyboard trigger
+  isn't a click, it does not get the `type="button"` a click trigger does. One
+  action per element still holds — bind Enter-save and Escape-cancel to separate
+  elements. README documents it under "Keyboard triggers".
+- **`reactive_compute` — client-side data bindings (no round trip).** A component
+  can now declare a client-side computation that recomputes derived fields
+  IN-BROWSER on `input`, with NO server round trip — the "instant" half of a
+  new/unpersisted-record UX that previously required a hand-written Stimulus
+  controller (e.g. an order calculator that rebalances a payment split as you
+  type). Declare the binding in Ruby and register the matching reducer once in JS:
+
+  ```ruby
+  reactive_compute :payment_split,
+    inputs:  %i[allowance cash leasing total],   # fields the reducer reads
+    outputs: %i[allowance cash leasing]          # fields it writes (no POST)
+  # in the view: div(**mix(reactive_root, reactive_compute_attrs(:payment_split)))
+  # on the edited field: data-action="input->reactive#recompute"
+  ```
+
+  ```js
+  import { setComputeReducer } from "phlex/reactive/compute"
+  setComputeReducer("payment_split", ({ allowance, cash, leasing, total }) => ({
+    allowance, leasing, cash: total - allowance - leasing,
+  }))
+  ```
+
+  The generic controller runs the named reducer on `input`, writes only the
+  declared outputs (leaving the edited field + caret alone), and fires `input` on
+  each field it sets so a chained summary repaints — matching the server's
+  `set_value` + `dispatch("input")` contract. A missing/unregistered reducer is a
+  no-op (a page never breaks because a binding wasn't wired up). When the same
+  component ALSO carries `on(...)` (a persisted record, or a draft you sync), that
+  debounced POST still fires and the server reply reconciles — so `reactive_compute`
+  is the optimistic client paint, the server round trip is the source of truth.
+  One math contract, two execution sites. New client module
+  `phlex/reactive/compute` (auto-pinned by the engine like `confirm`).
+
+- **Draft (unpersisted-record) tokens — `reactive_record` no longer crashes on a
+  `new_record?`.** A record-backed component may now render an UNSAVED record (an
+  order the user is building before it's saved). `reactive_token` omits the `gid`
+  when the record isn't persisted (`to_gid` would raise `MissingModelIdError`) and
+  relies on the declared `reactive_state` as the draft seed, so the token still
+  signs cleanly and the client controller mounts. The draft is driven client-side
+  (`reactive_compute`) until it's saved; once persisted, a re-render signs the
+  `gid` as before. Combined with `reactive_compute`, this is the "persisted → server,
+  new → in-browser" split as a first-class capability instead of a hand-rolled one.
+
 - **Overridable / async confirm resolver — reuse your themed dialog (#55).**
   Follow-up to #52. The `confirm:` gate was hardcoded to the synchronous,
   browser-native `window.confirm`, so a reactive trigger was the one interaction
@@ -55,6 +125,41 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   server coercion (request specs), the FormData wire shape (bun unit tests), and a
   real browser upload under Puma + Falcon (system spec).
 
+### Documentation
+
+- **The auto-collected-params contract, spelled out (#64, #65, #66, #67).** Four
+  gaps surfaced from building one model-scoped form (numeric fields that rebalance
+  live). No behavior changed — the README now documents what the code already
+  does:
+  - **#67** — a **flat** param schema silently drops **bracketed** field names.
+    Because the endpoint expands `invoice[date]` to `{ "invoice" => { … } }`
+    *before* matching the schema, a flat `{ date: … }` matches nothing and the
+    action gets keyword defaults with no error. The "Model-scoped form fields"
+    section now warns to nest the schema under the model key to match the names.
+  - **#65** — auto-collected sibling fields are read **at dispatch time**, not
+    from a pre-event snapshot: a `change`/`input` trigger sees its own new value
+    and every peer's current DOM value. Documented in a new "Auto-collected
+    sibling fields — the read contract" subsection.
+  - **#66** — reactive collection **includes `disabled` fields**, deliberately
+    unlike a native `<form>` submit, so a read-only computed field (a synced
+    `total`) reaches the action. Documented as intentional, with the `readonly`
+    vs `disabled` guidance for form-submit parity.
+  - **#64** — a `reactive_record` action can use the record for **identity +
+    authorization only** and compute over live, unsaved params, returning
+    `reply.streams(...)` to stream a partial update with **no persist and no
+    broadcast**. Documented as a first-class "record-authorized, transient-state
+    action" pattern in the `reply` section.
+
+  The demo app (`docs/`) gains a **live payment-split rebalancer** example — three
+  amounts that always sum to a total, editing one rebalances the peers — that
+  makes #64–#67 browsable (model-scoped bracketed params, a disabled computed
+  field the action still reads, siblings collected at dispatch, transient compute
+  with no persist/broadcast). The **todo** and **inline-edit** examples gain
+  Enter-to-add / Enter-to-save / Escape-to-cancel via the new `key:` filter,
+  covered by request specs and a real-browser (Playwright) Enter-keypress test.
+  Combobox keyboard navigation is tracked separately (#72) for the
+  minimal-client-seam work.
+
 ### Changed
 
 - **Linter: Standard → RuboCop.** The gem now lints with RuboCop (all new cops

data/README.md

@@ -2,13 +2,13 @@
 
 [![CI](https://github.com/mhenrixon/phlex-reactive/actions/workflows/main.yml/badge.svg)](https://github.com/mhenrixon/phlex-reactive/actions/workflows/main.yml)
 [![Gem Version](https://img.shields.io/gem/v/phlex-reactive)](https://rubygems.org/gems/phlex-reactive)
-[![Docs](https://img.shields.io/badge/docs-mhenrixon.github.io-blue)](https://mhenrixon.github.io/phlex-reactive)
+[![Docs](https://img.shields.io/badge/docs-phlex--reactive.zoolutions.llc-blue)](https://phlex-reactive.zoolutions.llc)
 
 **Reactive [Phlex](https://www.phlex.fun) components for Rails — Livewire-style
 actions and live cross-tab updates, without writing Stimulus controllers or
 hand-picking Turbo Stream targets.**
 
-📖 **[Full documentation](https://mhenrixon.github.io/phlex-reactive)**
+📖 **[Full documentation](https://phlex-reactive.zoolutions.llc)**
 
 ```ruby
 class Counter < ApplicationComponent
@@ -130,7 +130,7 @@ application.register("reactive", ReactiveController)
 
 The JS ships at `app/javascript/phlex/reactive/reactive_controller.js` in the
 gem; point your bundler at the gem path or copy it in. See
-[docs/installation.md](docs/installation.md).
+[docs/installation.md](https://phlex-reactive.zoolutions.llc/docs/installation).
 </details>
 
 **Requirements:** Rails 7.1+, Phlex 2 (`phlex-rails`), Turbo 8+ (for morphing),
@@ -265,7 +265,7 @@ action. Keep state small and JSON-serializable.
 reactive_state :count, :step       # signed; rebuilt on each action
 ```
 
-The [inline edit example](docs/examples/inline_edit.md) combines both: a
+The [inline edit example](https://phlex-reactive.zoolutions.llc/docs/example-inline-edit) combines both: a
 `reactive_record :record` plus `reactive_state :attribute, :editing`.
 
 ---
@@ -274,14 +274,15 @@ The [inline edit example](docs/examples/inline_edit.md) combines both: a
 
 | Example | What it shows |
 |---|---|
-| [Counter](docs/examples/counter.md) | State-backed, the smallest reactive component |
-| [Cross-tab chat](docs/examples/chat.md) | Record-backed action **+ pgbus broadcast** → live sync across tabs/browsers |
-| [Live todo list](docs/examples/todo_list.md) | Per-row components, add/toggle/rename/delete, broadcast on change |
-| [Inline edit](docs/examples/inline_edit.md) | Show ↔ edit mode toggle, replacing a Stimulus controller + 3 routes |
-| [Notifications / badges](docs/examples/notifications.md) | Pure broadcast (no client action) — a job pushes a re-render |
+| [Counter](https://phlex-reactive.zoolutions.llc/docs/example-counter) | State-backed, the smallest reactive component |
+| [Payment split](https://phlex-reactive.zoolutions.llc/docs/example-payment-split) | Live sum-to-total rebalancer — nested bracketed params, a disabled computed field, auto-collected siblings (#64–#67) |
+| [Cross-tab chat](https://phlex-reactive.zoolutions.llc/docs/example-chat) | Record-backed action **+ pgbus broadcast** → live sync across tabs/browsers |
+| [Live todo list](https://phlex-reactive.zoolutions.llc/docs/example-todo-list) | Per-row components, add/toggle/rename/delete, Enter-to-add, broadcast on change |
+| [Inline edit](https://phlex-reactive.zoolutions.llc/docs/example-inline-edit) | Show ↔ edit mode toggle, replacing a Stimulus controller + 3 routes |
+| [Notifications / badges](https://phlex-reactive.zoolutions.llc/docs/example-notifications) | Pure broadcast (no client action) — a job pushes a re-render |
 
 The cross-tab chat in ~60 lines of Ruby (and zero JS) is the showcase — see
-[docs/examples/chat.md](docs/examples/chat.md).
+[docs/examples/chat.md](https://phlex-reactive.zoolutions.llc/docs/example-chat).
 
 ---
 
@@ -311,7 +312,9 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_attrs` | Marks an element reactive + carries the signed token (no `id`). Spread alongside `id:` on the **same** element: `div(id:, **reactive_attrs)`. Prefer `reactive_root`, which can't split them. |
 | `on(:action, event: "click", **params)` | Spread onto a trigger element. Adds `type=button` for clicks. |
 | `on(:action, event: "input", debounce: 300)` | Coalesce rapid events into one round trip after a quiet period (live-as-you-type). |
+| `on(:action, event: "keydown.enter")` | Fire only on a specific key — Enter-to-submit / Escape-to-cancel — via Stimulus's native keyboard filter (`event:` passes straight through). See [Keyboard triggers](#keyboard-triggers-enter-to-submit--escape-to-cancel). |
 | `on(:action, confirm: "Sure?")` | Gate a destructive trigger behind a confirmation. Defaults to `window.confirm`; override the dialog with [`setConfirmResolver`](#custom-confirmation-dialogs-setconfirmresolver). |
+| `on(:search, listnav: "[role=option]")` | Add combobox keyboard navigation — Arrow keys move a client-side highlight, Enter picks (clicks the option's own trigger), Escape clears. See [Combobox keyboard navigation](#combobox-keyboard-navigation-listnav). |
 | `reactive_input(:param, **attrs)` / `reactive_select(:param, **attrs)` | Render a control already bound to an action param (no magic `name:`). |
 | `reactive_field(:param, **attrs)` | The attribute hash behind the above — spread onto any control. |
 | `nested_update!(:assoc, attrs)` | Map a nested param onto `<assoc>_attributes` with id preservation; update the record. |
@@ -395,6 +398,16 @@ action :save, params: {invoice: {date: :string, status: :string}}
 # client posts { "invoice[date]": "…", "invoice[status]": "…" }  → save(invoice: { date:, status: })
 ```
 
+> **A flat schema silently drops bracketed names (issue #67).** The schema must
+> mirror the field *names*, not the conceptual params. Because the endpoint
+> expands `invoice[date]` to `{ "invoice" => { "date" => … } }` **before**
+> matching the schema, a flat `params: { date: :string }` matches nothing — the
+> top-level key is now `invoice`, not `date`. There is no error: the action just
+> receives its keyword defaults (`date` never set). If your inputs are named
+> `invoice[…]` (any `Form(model:)`-style form), nest the schema under `invoice:`
+> to match. When in doubt, read a field's real `name` attribute and shape the
+> schema to it.
+
 **Nested reactive components compose.** A reactive component rendered inside
 another is its own root — field collection stops at nested
 `data-controller="reactive"` roots, so an outer action collects only *its own*
@@ -413,6 +426,90 @@ Omit `debounce:` for the immediate-dispatch default.
 input(**mix(on(:update, event: "input", debounce: 300), name: "quantity", value: @item.quantity))
 ```
 
+**Auto-collected sibling fields — the read contract.** A reactive action doesn't
+just receive its own trigger's value: the client gathers **every named control**
+in the reactive root (`input[name]`, `select[name]`, `textarea[name]`, and named
+rich-text/`contenteditable` editors) and merges them under the action's params,
+so one action reads the whole form. Explicit `on(:act, x: …)` params win over a
+collected field of the same name; collection stops at nested reactive roots (see
+*Nested reactive components compose* above). Two things worth pinning down:
+
+- **Timing — params reflect the DOM at dispatch, not a pre-event snapshot
+  (issue #65).** Field values are read when the request is sent (after the
+  debounce quiet period, if any), so a `change`/`input` trigger sees **its own
+  field's new value and every peer's current value.** There is no capture of the
+  values as they were *before* the interaction — if your computation needs a
+  peer's prior value (e.g. a spill-back that folds an overflow into the edited
+  field), that peer's current DOM value *is* the prior value only because nothing
+  else has changed it yet. Read at dispatch time, trust the current DOM.
+- **Disabled fields ARE collected (issue #66) — deliberately different from a
+  native form.** A `<form>` submit omits `disabled` controls; reactive collection
+  does **not** check `disabled`, so a disabled field that carries a
+  computed/display value (a read-only `total` the client keeps in sync) reaches
+  the action. This is intentional — it's what makes "read a computed disabled
+  field" work. If you need form-submit parity (drop the disabled value), give the
+  control no `name`, or make it `readonly` instead of `disabled` when you *do*
+  want it collected by both paths.
+
+**Keyboard triggers (Enter-to-submit / Escape-to-cancel).** `event:` is
+interpolated straight into the Stimulus action descriptor, so any Stimulus event
+string works — including its **native keyboard filters**. Pass `event:
+"keydown.enter"` to fire only on Enter, `event: "keydown.esc"` for Escape — the
+classic "Enter adds the row", "Escape cancels the edit" interactions. The action
+runs *only* on that key, not on every keypress — no client JavaScript, no
+`event.key` check of your own, and no new option to learn (it's Stimulus's own
+[keyboard-filter syntax](https://stimulus.hotwired.dev/reference/actions#keyboardevent-filter)):
+
+```ruby
+# Enter in the composer adds the todo (same action as the Add button).
+input(**mix(on(:add, event: "keydown.enter"), name: "title", placeholder: "New todo…"))
+
+# Inline editor: Enter on the field saves; a separate control cancels on Escape.
+input(**mix(on(:save, event: "keydown.enter"), name: "title", value: @todo.title))
+button(**on(:cancel, event: "keydown.esc")) { "Cancel" }
+```
+
+The filter tokens are Stimulus's (`enter`, `esc`, `space`, `up`, `down`, a bare
+letter, …). Because a keyboard trigger isn't a click, it does **not** get the
+`type="button"` a click trigger does. Folding the key into `event:` keeps `key`
+free as an ordinary action-param name (`on(:switch, key: "pgbus")` still passes
+`key` through as a param).
+
+> **One action per element.** Each trigger element carries a single reactive
+> action (its `data-reactive-action-param`), so you can't put `on(:save, event:
+> "keydown.enter")` *and* `on(:cancel, event: "keydown.esc")` on the **same**
+> input — the second would overwrite the first's action name. Bind each key
+> trigger to its own element (the field saves on Enter; a Cancel button — or the
+> field's own blur — handles Escape), as above.
+
+### Combobox keyboard navigation (`listnav:`)
+
+A searchable list needs Arrow keys to move a highlight, Enter to pick, Escape to
+close — interactions that are *ephemeral client UI state* (a highlight per
+keystroke would be absurd as a server round trip). Pass `listnav:` (a CSS
+selector for the option elements) to a search trigger and the generic controller
+handles all of it client-side, with no bespoke Stimulus controller:
+
+```ruby
+# The search input: debounced live search + keyboard list navigation.
+input(**mix(
+  on(:search, event: "input", debounce: 200, listnav: "[role=option]"),
+  name: "query", value: @query
+))
+
+# Each option is BOTH a listnav target (role=option) and its own reactive
+# select trigger — Enter just clicks the highlighted one.
+button(**mix(on(:select, name: opt), role: "option")) { opt }
+```
+
+`listnav:` appends Stimulus's native keyboard filters
+(`keydown.down/up/enter/esc`) to the input's `data-action`. Arrow Up/Down move a
+`data-reactive-highlighted` marker among the options **with no round trip**;
+Enter **clicks the highlighted option** — so selection runs through its normal
+`on(:select)` reactive action (signed, default-deny, authorized like any other);
+Escape clears the highlight. Only the highlight is client-side — the selection
+stays a real signed action, and the highlight is never shipped as trusted state.
+
 **Combining `on(...)` / `reactive_attrs` with your own attributes.** Both return
 a hash that includes a `data:` key. Spreading them *and* passing another `data:`
 (or `class:`, `id:`) would clobber it — use Phlex's `mix` to deep-merge. For the
@@ -567,6 +664,40 @@ update only the targets you name) and refreshes the token via a tiny inert
 `reactive:token` stream instead — the token rolls forward without re-rendering
 (and clobbering) the component's live inputs.
 
+#### Record-authorized, transient-state actions (issue #64)
+
+A `reactive_record` component isn't obligated to persist or broadcast — the
+record can be there purely for **identity + authorization** while the action's
+real job is to recompute **live, unsaved form values** the user is mid-edit. The
+record is re-located and instantiated on each action (`from_identity`), never
+auto-saved and never auto-broadcast; persistence and cross-tab broadcast are both
+opt-in (you call `record.update!` / `broadcast_*_to` yourself). Pair that with
+`reply.streams` and you get a first-class "authorize via the row, compute over
+the params, stream a partial update, touch neither the DB nor peer tabs" action:
+
+```ruby
+class Invoice::PaymentFields < ApplicationComponent
+  include Phlex::Reactive::Streamable
+  include Phlex::Reactive::Component
+
+  reactive_record :invoice   # identity + authorization ONLY — not persisted here
+  action :rebalance, params: { invoice: { field_a: :integer, field_b: :integer,
+                                          field_c: :integer, total: :integer } }
+
+  def rebalance(invoice:)
+    authorize! @invoice, :update?          # the token proves identity, not permission
+    result = recompute(invoice)            # pure computation over the collected params
+    reply.streams(*set_value_streams(result))  # NO persist, NO broadcast
+  end
+end
+```
+
+This is deliberate, not a misuse: `reply.streams` is exactly the reply for "emit
+these targeted updates, roll the token forward, and leave everything else — the
+DB, the other tabs, the sibling inputs the user is typing in — untouched."
+Broadcasting is deliberately omitted so peer tabs with their own in-flight edits
+aren't clobbered. Authorize the record as always — identity is never permission.
+
 > **Under the hood.** `reply.<verb>` returns a `Phlex::Reactive::Response` — the
 > immutable value object the endpoint reads. You can build one directly
 > (`Phlex::Reactive::Response.replace(self)`) and it still works, but `reply` is
@@ -696,7 +827,7 @@ real, so read this once.
   but if you have *public* reactive components, ensure the action path isn't
   force-redirected to a login page for logged-out users.
 
-See [docs/security.md](docs/security.md) for the threat model and a checklist.
+See [docs/security.md](https://phlex-reactive.zoolutions.llc/docs/security) for the threat model and a checklist.
 
 ---
 
@@ -800,24 +931,24 @@ end
   replayed, not lost.
 - **No Redis, no Action Cable.**
 
-See [docs/broadcasting.md](docs/broadcasting.md) and
-[docs/transport-pgbus.md](docs/transport-pgbus.md).
+See [docs/broadcasting.md](https://phlex-reactive.zoolutions.llc/docs/broadcasting) and
+[docs/transport-pgbus.md](https://phlex-reactive.zoolutions.llc/docs/transport-pgbus).
 
 ---
 
 ## Documentation
 
-- [Installation & bundler setups](docs/installation.md)
-- [Mental model & architecture](docs/architecture.md)
-- [Security & threat model](docs/security.md)
-- [Broadcasting & live updates](docs/broadcasting.md)
-- [Transport: pgbus vs Action Cable](docs/transport-pgbus.md)
-- [Testing reactive components](docs/testing.md)
-- [Performance & benchmarking](docs/performance.md)
-- Examples: [counter](docs/examples/counter.md) ·
-  [chat](docs/examples/chat.md) · [todo list](docs/examples/todo_list.md) ·
-  [inline edit](docs/examples/inline_edit.md) ·
-  [notifications](docs/examples/notifications.md)
+- [Installation & bundler setups](https://phlex-reactive.zoolutions.llc/docs/installation)
+- [Mental model & architecture](https://phlex-reactive.zoolutions.llc/docs/architecture)
+- [Security & threat model](https://phlex-reactive.zoolutions.llc/docs/security)
+- [Broadcasting & live updates](https://phlex-reactive.zoolutions.llc/docs/broadcasting)
+- [Transport: pgbus vs Action Cable](https://phlex-reactive.zoolutions.llc/docs/transport-pgbus)
+- [Testing reactive components](https://phlex-reactive.zoolutions.llc/docs/testing)
+- [Performance & benchmarking](https://phlex-reactive.zoolutions.llc/docs/performance)
+- Examples: [counter](https://phlex-reactive.zoolutions.llc/docs/example-counter) ·
+  [chat](https://phlex-reactive.zoolutions.llc/docs/example-chat) · [todo list](https://phlex-reactive.zoolutions.llc/docs/example-todo-list) ·
+  [inline edit](https://phlex-reactive.zoolutions.llc/docs/example-inline-edit) ·
+  [notifications](https://phlex-reactive.zoolutions.llc/docs/example-notifications)
 
 ## Credits & prior art
 

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

@@ -0,0 +1,48 @@
+// The client-side compute (data-binding) registry — the "instant" half of the
+// new/unpersisted-record UX.
+//
+// A record-backed reactive component round-trips every change to the server
+// (the signed identity re-finds the record; the server re-renders). A NEW,
+// unpersisted record has no such server truth to re-render against on every
+// keystroke — the classic answer is a bespoke Stimulus controller doing the math
+// in the browser (carlqvist's new_order_controller.js). This registry lets that
+// math be a DECLARED part of the component instead: `reactive_compute :name,
+// inputs:, outputs:` (Ruby) names a reducer registered here, and the generic
+// reactive controller runs it on `input` — writing the outputs with NO round
+// trip. When the component ALSO carries on(...) (a persisted record, or a draft
+// you sync), the debounced POST reconciles from the authoritative server reply.
+//
+// The seam mirrors confirm.js: a settable registry with a lookup the controller
+// calls. Register once at boot:
+//
+//   import { setComputeReducer } from "phlex/reactive/compute"
+//   setComputeReducer("payment_split", ({ allowance, cash, leasing, total }) => ({
+//     allowance, leasing, cash: total - allowance - leasing,
+//   }))
+//
+// The reducer receives a plain object of { inputName: Number } and returns a
+// plain object of { outputName: value } — only the outputs it names are written,
+// so it can leave the edited field (and its caret) untouched. Returning the SAME
+// value it read is a no-op write; the controller still fires `input` on any field
+// it sets so a chained summary repaints, matching the server's set_value +
+// dispatch("input") contract.
+
+const reducers = new Map()
+
+// Register (or replace) the reducer for `key`. `fn` is
+// (values: Record<string, number>) => Record<string, unknown>.
+export function setComputeReducer(key, fn) {
+  reducers.set(key, fn)
+}
+
+// Look up a registered reducer; undefined when none — the controller then makes
+// #recompute a no-op rather than throwing (a missing reducer must not break the
+// page; it just means no client-side binding for that root).
+export function computeReducer(key) {
+  return reducers.get(key)
+}
+
+// Test seam: clear the registry so a reducer registered in one test can't leak.
+export function __resetComputeRegistryForTest() {
+  reducers.clear()
+}

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

@@ -10,6 +10,9 @@ import { Controller } from "@hotwired/stimulus"
 // bundlers/bun resolve it the same way they already resolve
 // "phlex/reactive/reactive_controller" (see tsconfig.json paths for the tests).
 import { confirmResolver } from "phlex/reactive/confirm"
+// Client-side computes (data bindings): the reducer registry behind
+// reactive_compute. Bare specifier for the same import-map reason as confirm.
+import { computeReducer } from "phlex/reactive/compute"
 
 // The ONE generic controller behind every reactive Phlex component. It
 // replaces the per-feature Stimulus controllers you'd otherwise hand-write
@@ -219,6 +222,131 @@ export default class extends Controller {
       })
   }
 
+  // Client-side compute (data binding). Wired by reactive_compute: an `input`
+  // trigger (input->reactive#recompute) runs a REGISTERED JS reducer over the
+  // named input fields and writes the named output fields WITH NO ROUND TRIP —
+  // the "instant" half of the new/unpersisted-record UX. If the field ALSO
+  // carries on(...) (a persisted record, or a synced draft), that debounced POST
+  // still fires and the server reply reconciles; recompute just paints first.
+  //
+  // Reads inputs/outputs/reducer from the root's data-reactive-compute-* attrs
+  // (set once by reactive_compute_attrs). A missing/unregistered reducer is a
+  // no-op — a page must never break because a binding wasn't wired up.
+  recompute() {
+    const key = this.element.getAttribute("data-reactive-compute-reducer-param")
+    if (!key) return
+    const reduce = computeReducer(key)
+    if (!reduce) return
+
+    const inputs = this.#parseComputeList("data-reactive-compute-inputs-param")
+    const outputs = this.#parseComputeList("data-reactive-compute-outputs-param")
+
+    const values = {}
+    for (const name of inputs) values[name] = this.#numericFieldValue(name)
+
+    const result = reduce(values) || {}
+    for (const name of outputs) {
+      if (!(name in result)) continue
+      const field = this.#ownedField(name)
+      // Setting .value fires the field's own `input` listeners (a chained summary
+      // repaint), matching the server's set_value + dispatch("input") contract.
+      if (field) field.value = result[name]
+    }
+  }
+
+  // Client-side list navigation (combobox keyboard nav, issue #72). Wired by
+  // on(:search, …, listnav: "[role=option]"), which appends keyboard filters to
+  // the input's data-action (keydown.down/up/enter/esc->reactive#listnav*) and
+  // sets data-reactive-listnav-option-param. Arrow keys move a highlight among
+  // the options WITH NO ROUND TRIP; Enter picks the highlighted option by
+  // 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.
+  listnavNext(event) {
+    this.#moveHighlight(event, +1)
+  }
+
+  listnavPrev(event) {
+    this.#moveHighlight(event, -1)
+  }
+
+  // Enter: activate the highlighted option (fires its reactive select). No-op if
+  // nothing is highlighted, and in that case DON'T preventDefault — Enter falls
+  // through (there's no selection to make).
+  listnavPick(event) {
+    const options = this.#listnavOptions(event)
+    const current = options.findIndex((el) => el.hasAttribute("data-reactive-highlighted"))
+    if (current < 0) return
+    event.preventDefault()
+    options[current].click()
+  }
+
+  listnavClose(event) {
+    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) {
+    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
+
+    for (const el of options) el.removeAttribute("data-reactive-highlighted")
+    const chosen = options[next]
+    chosen.setAttribute("data-reactive-highlighted", "true")
+    chosen.scrollIntoView?.({ block: "nearest" })
+  }
+
+  // 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
+  // event; the options are still scoped to this controller's root. Empty when
+  // unset. Falls back to the root for a directly-invoked call (unit tests).
+  #listnavOptions(event) {
+    const trigger = event?.currentTarget ?? event?.target ?? this.element
+    const selector =
+      trigger.getAttribute?.("data-reactive-listnav-option-param") ??
+      this.element.getAttribute("data-reactive-listnav-option-param")
+    if (!selector) return []
+    const nodes = this.element.querySelectorAll(selector)
+    return Array.from(nodes).filter((el) => this.#ownsField(el))
+  }
+
+  // Parse a JSON string list from a root data attr; [] on absence/parse error so
+  // a malformed binding degrades to "no fields" rather than throwing on input.
+  #parseComputeList(attr) {
+    const raw = this.element.getAttribute(attr)
+    if (!raw) return []
+    try {
+      const list = JSON.parse(raw)
+      return Array.isArray(list) ? list : []
+    } catch {
+      return []
+    }
+  }
+
+  // The first named control owned by THIS root (skips nested reactive roots,
+  // issue #15) — used by recompute to read inputs and write outputs.
+  #ownedField(name) {
+    const nodes = this.element.querySelectorAll(`[name="${name}"]`)
+    for (const el of nodes) if (this.#ownsField(el)) return el
+    return null
+  }
+
+  // A field's value as a Number, treating blank/absent/NaN as 0 — mirroring the
+  // nanToZero coercion the hand-written calculators use, so a reducer never sees
+  // "" or NaN for an empty field.
+  #numericFieldValue(name) {
+    const field = this.#ownedField(name)
+    const n = Number(field?.value)
+    return Number.isFinite(n) ? n : 0
+  }
+
   // Enqueue the action — debounced if a debounce window is set, else immediately.
   // Split out of dispatch so both the no-confirm fast path and the post-confirm
   // microtask share one place (issue #55). `target` is captured up front because

data/lib/phlex/reactive/component.rb

@@ -62,6 +62,13 @@ module Phlex
       # A declared, client-invokable action and its param schema.
       Action = Data.define(:name, :params)
 
+      # A declared client-side computation (data binding). `inputs`/`outputs` are
+      # the action-param names of the fields the reducer reads/writes; `reducer`
+      # is the key a JS function is registered under (Reactive.compute(key, fn)).
+      # The generic controller runs the reducer on `input` — writing outputs with
+      # NO round trip — then the debounced POST reconciles from the server reply.
+      ComputeDefinition = Data.define(:name, :inputs, :outputs, :reducer)
+
       # A declared add/remove-row collection (issue #35): the list contract tied
       # into one unit — the per-row item component, the container DOM id rows
       # live in, an optional companion count id, an optional empty-state
@@ -175,6 +182,36 @@ module Phlex
           reactive_collections.key?(name.to_sym)
         end
 
+        # Declare a client-side computation, OR (called with just a name) read
+        # one back. Dual-purpose so a component reads `reactive_compute :split,
+        # inputs: …, outputs: …` and the endpoint/helpers read
+        # `reactive_compute(:split)` — mirroring how `on`/`reactive_field` keep a
+        # tight surface. `reducer:` defaults to the compute name.
+        #
+        #   reactive_compute :payment_split,
+        #     inputs: %i[allowance cash leasing total],  # fields the JS reducer reads
+        #     outputs: %i[allowance cash leasing]        # fields it writes (no round trip)
+        #
+        # Register the matching JS once at boot:
+        #   import { setComputeReducer } from "phlex/reactive/compute"
+        #   setComputeReducer("payment_split", ({ allowance, cash, leasing, total }) => ({ … }))
+        def reactive_compute(name, inputs: nil, outputs: nil, reducer: nil)
+          return reactive_computes[name.to_sym] if inputs.nil? && outputs.nil?
+
+          reactive_computes[name.to_sym] = ComputeDefinition.new(
+            name: name.to_sym, inputs: Array(inputs).map(&:to_sym),
+            outputs: Array(outputs).map(&:to_sym), reducer: (reducer || name).to_s
+          )
+        end
+
+        def reactive_computes
+          @reactive_computes ||= superclass.respond_to?(:reactive_computes) ? superclass.reactive_computes.dup : {}
+        end
+
+        def reactive_compute?(name)
+          reactive_computes.key?(name.to_sym)
+        end
+
         # The record's instance-variable symbol (e.g. :@todo), computed once.
         # reactive_token reads it on every render; interpolating :"@#{key}" each
         # time would allocate a symbol per render. Nil when record-less. Memoized
@@ -313,22 +350,53 @@ module Phlex
       # enqueue/debounce if the user declines (and prevents the native default so
       # a `submit` trigger can't navigate on cancel). Omit it for no prompt.
       #   button(**on(:destroy, confirm: "Really delete this item?")) { "Delete" }
+      #
+      # `event:` is interpolated verbatim into the Stimulus action descriptor
+      # (`#{event}->reactive#dispatch`), so any Stimulus event string works —
+      # including its native KEYBOARD FILTERS. Pass `event: "keydown.enter"` for
+      # Enter-to-submit or `event: "keydown.esc"` for Escape-to-cancel, and the
+      # action fires only on that key — no separate option, no client code, and
+      # `key` stays free as an ordinary action-param name (on(:switch, key: …)):
+      #   input(**on(:add, event: "keydown.enter"))      # Enter submits
+      #   button(**on(:cancel, event: "keydown.esc"))     # Escape cancels
+      #
+      # `listnav:` (a CSS selector for the option elements) adds keyboard list
+      # navigation to a search/combobox trigger (issue #72). It appends Stimulus
+      # keyboard filters to the SAME element's data-action so Arrow Up/Down move a
+      # client-side highlight among the options, Enter picks the highlighted one
+      # (clicking its own reactive trigger — so selection stays a signed action),
+      # and Escape clears — all with NO server round trip for the highlight (the
+      # controller's listnav* handlers, like #recompute). Omit it for no nav.
+      #   input(**on(:search, event: "input", debounce: 300, listnav: "[role=option]"))
       # The verbatim JSON for an empty explicit-params payload. The common
       # trigger (on(:increment), no params) hits this on EVERY render — skipping
       # params.to_json (which re-serializes {} to the same "{}" each time) avoids
       # a per-render allocation while keeping the wire format byte-identical.
       EMPTY_PARAMS_JSON = "{}"
 
-      def on(action_name, event: "click", debounce: nil, confirm: nil, **params)
+      # The keyboard filters appended to a listnav trigger's data-action. Each is
+      # a client-only handler (no POST) except Enter, which clicks the highlighted
+      # option's own reactive trigger. Stimulus binds these natively.
+      LISTNAV_ACTIONS = [
+        "keydown.down->reactive#listnavNext",
+        "keydown.up->reactive#listnavPrev",
+        "keydown.enter->reactive#listnavPick",
+        "keydown.esc->reactive#listnavClose"
+      ].freeze
+
+      def on(action_name, event: "click", debounce: nil, confirm: nil, listnav: nil, **params)
+        action = "#{event}->reactive#dispatch"
+        action = "#{action} #{LISTNAV_ACTIONS.join(" ")}" if listnav
         attrs = {
           data: {
-            action: "#{event}->reactive#dispatch",
+            action:,
             reactive_action_param: action_name.to_s,
             reactive_params_param: params.empty? ? EMPTY_PARAMS_JSON : params.to_json
           }
         }
         attrs[:data][:reactive_debounce_param] = debounce if debounce
         attrs[:data][:reactive_confirm_param] = confirm if confirm
+        attrs[:data][:reactive_listnav_option_param] = listnav if listnav
         attrs[:type] = "button" if event == "click"
         attrs
       end
@@ -353,6 +421,28 @@ module Phlex
         input(**reactive_field(param, **attrs))
       end
 
+      # Data attributes declaring a client-side compute for the root element.
+      # Spread ALONGSIDE reactive_root so the generic controller can find the
+      # reducer and the named input/output fields inside this root:
+      #   div(**mix(reactive_root, reactive_compute_attrs(:payment_split))) { … }
+      #
+      # It emits the reducer key plus the input/output field names as JSON so the
+      # client runs the reducer on `input`, writes the outputs with no round trip,
+      # then the debounced POST reconciles from the server reply. Raises for an
+      # undeclared compute — a silent no-op would leave the field wiring dead.
+      def reactive_compute_attrs(name)
+        definition = self.class.reactive_compute(name)
+        raise Error, "#{self.class} has no reactive_compute #{name.inspect}" unless definition
+
+        {
+          data: {
+            reactive_compute_reducer_param: definition.reducer,
+            reactive_compute_inputs_param: definition.inputs.map(&:to_s).to_json,
+            reactive_compute_outputs_param: definition.outputs.map(&:to_s).to_json
+          }
+        }
+      end
+
       # Render a <select> bound to an action param (issue #23). The options block
       # is the element's content, so the awkward FormBuilder positional split
       # (where name: lands after the options/html-options args) goes away:
@@ -403,12 +493,23 @@ module Phlex
       # (e.g. which column an inline_edit may write) tamper-proof alongside the
       # record. Record-only ({c, gid}) and state-only ({c, s}) shapes are
       # unchanged.
+      #
+      # A record that is NOT YET PERSISTED (new_record?) has no id → no GlobalID
+      # (to_gid raises MissingModelIdError). A record-backed component may render
+      # such a draft (an unsaved order the user is building): we OMIT gid and rely
+      # on the declared state (reactive_state) as the draft seed, so the token
+      # still signs cleanly and the client controller mounts. The draft is then
+      # driven client-side (reactive_compute) until it's saved; once persisted, a
+      # re-render signs the gid as usual. If the record is unsaved AND no state is
+      # declared, the token carries just {c} — enough to mount, but with no
+      # identity to round-trip, so declare reactive_state for a draft you sync.
       def reactive_token
         klass = self.class
         payload = { "c" => klass.name }
 
         if (record_ivar = klass.reactive_record_ivar)
-          payload["gid"] = instance_variable_get(record_ivar).to_gid.to_s
+          record = instance_variable_get(record_ivar)
+          payload["gid"] = record.to_gid.to_s unless record.respond_to?(:persisted?) && !record.persisted?
         end
 
         state_ivars = klass.reactive_state_ivars

data/lib/phlex/reactive/engine.rb

@@ -27,6 +27,7 @@ module Phlex
           it.config.assets.precompile += %w[
             phlex/reactive/reactive_controller.js
             phlex/reactive/confirm.js
+            phlex/reactive/compute.js
           ]
         end
       end
@@ -54,6 +55,16 @@ module Phlex
             to: "phlex/reactive/confirm.js",
             preload: true
           )
+          # The client-side compute (data-binding) registry behind
+          # reactive_compute. reactive_controller.js imports it by this bare
+          # specifier (same import-map rationale as confirm above), and an app
+          # registers reducers via `import { setComputeReducer } from
+          # "phlex/reactive/compute"` — both resolve through this pin.
+          it.importmap.pin(
+            "phlex/reactive/compute",
+            to: "phlex/reactive/compute.js",
+            preload: true
+          )
         end
       end
 

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.4.7"
+    VERSION = "0.4.8"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.4.7
+  version: 0.4.8
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -117,6 +117,7 @@ files:
 - LICENSE.txt
 - README.md
 - app/controllers/phlex/reactive/actions_controller.rb
+- app/javascript/phlex/reactive/compute.js
 - app/javascript/phlex/reactive/confirm.js
 - app/javascript/phlex/reactive/reactive_controller.js
 - lib/generators/phlex/reactive/component/USAGE