phlex-reactive 0.10.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42d923475e8b2eb3ea48a0ef076358a10dbfd7760c34709dc54af5910805ad01
-  data.tar.gz: a6822d8caa3e24dc863284f7bb6eafde39bc69562d4c5d14504b99e489c1e302
+  metadata.gz: 4cfa5e7304bbb131fae2403858494732b6c560c305e920d76bfaa64deed8dca0
+  data.tar.gz: 8ba95cb7f00ce3d7b643a4385ddfceb69f992d6ce9b947e3eb31f4af9d3ab8e6
 SHA512:
-  metadata.gz: 234bcb0ca3b36e91f8f53cbbb2dd31f86f03b5a1043911e13652f3b4c2d31fe882b883035c4ab8ba2e2fc8a0f0755ac6302f2bf6d04c09d93aa2d659cd69e358
-  data.tar.gz: b63a02ff87733de83ad39dbea2f9754ef62fbfc79d7cf8f1d4a98e22891dae50e215bbca11b5faecefe9a454a2b0794c3fbbf870ee4da2ca8ec025aea69185b7
+  metadata.gz: 0f8a010d359dba2455e83a1986749e3fe2c6107092246729d3fe68db56db056617df3fc0e521d112166733462f16e3890162a120a7c9662a05d8486488512975
+  data.tar.gz: 23206611a3db2be0ea53876d0600c34c89db673d0fc5bdf6f8908ac346ef04b3a92ab8538384fa9c587ab41cd81ae96dd7e2fa8acf095c941a6c1982f5574ac0

data/CHANGELOG.md

@@ -8,6 +8,223 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **A freshly-rendered `reactive_compute` root now self-seeds its derived fields on connect (#199).**
+  Before, a compute root computed nothing until the first user `input` — a fresh render
+  (or a server validation-error re-render that replaced the body) left every derived
+  output and cross-root `mirror:` node blank until you typed. Apps worked around it by
+  dispatching a synthetic seed `input` on connect, but the compute root is a distinct
+  Stimulus controller that may connect a frame later, so the seed raced its own wiring —
+  the reported symptom being a PARTIAL apply (an early output painted; a later output
+  and the mirror stayed blank). Now `connect()` runs ONE full `recompute()` after the
+  controller is fully connected, so the whole single-pass write set (batch outputs →
+  paint text sinks + cross-root mirrors → dispatch) runs synchronously and every
+  declared output, text sink, and mirror paints from a single reducer result — no user
+  interaction, no round trip. It re-seeds on `turbo:morph-element` (the show/filter/dirty
+  precedent) and is idempotent (change-guarded writes make a re-seed a no-op, so an app
+  still dispatching a synthetic input is harmless). The seed is gated on a new
+  `data-reactive-compute-seed` marker emitted by `reactive_root(compute:)`; a non-compute
+  root pays one attribute read and never seeds. The seed passes no event, so
+  `meta.changed` is `null` — the correct "no field edited yet" semantics, so a convergent
+  reducer's default branch computes the full settled set.
+
+- **Scoped form fields no longer silently drop their params — the #67 footgun is fixed (#184).**
+  Under `reactive_scope`, `reactive_field(:date)` now emits the scoped wire name
+  (`name="invoice[date]"`), so the POST arrives bracketed — and the endpoint unwraps
+  exactly ONE scope level before schema matching, so a FLAT schema
+  (`params: { date: :string }`) matches. Previously a scoped field either POSTed a bare
+  name (misaligned with the `reactive_show`/`reactive_compute` resolvers, which already
+  query `[name="scope[x]"]`) or forced a hand-written bracketed name + a hand-nested
+  schema that Rails' bracket-expansion silently dropped. The client's `meta.changed`
+  resolver (`#changedComputeField`) is now scope-aware too, so a scoped compute
+  component's reducer still sees the bare declared name.
+
+- **`reactive_compute` output order no longer silently corrupts values (#183).**
+  Each output write used to dispatch an `input` event **mid-loop**, re-entering the
+  reducer synchronously from a **half-written DOM** — so a wrong `outputs:` order
+  could commit wrong values (a real money-corruption class), settling only if the
+  reducer was convergent in exactly the declared order. The client now runs the
+  reducer **once** from one pre-write input snapshot, writes all changed outputs as
+  a **batch**, paints text/mirror sinks from the settled values, then dispatches the
+  `input` events — each self-marked so the root skips re-running its own reducer
+  while other listeners (chained repaint, dirty tracking, `reactive_show`, sibling
+  roots) still fire. Declared output order is no longer semantics. Covered by a JS
+  order-independence test (declare outputs in the historically-wrong order — values
+  stay correct) and a self-re-entry-suppression test.
+
+### Changed
+
+- **BREAKING: small sharp knives — the last 0.11 API-clarity pass (#186).**
+  Four independent edges honed, one contract frozen:
+  - **`reactive_filter` speaks fields, not selectors.** `reactive_filter(:q)` names the
+    driving FIELD and compiles it to `[name="q"]` (scope-aware, like `reactive_field`
+    from #184); `option:` defaults to `[role=option]`. The old
+    `reactive_filter(input: "#search", …)` selector form raises a guided error. The
+    client wire is byte-identical (it still receives selectors) — this is a server-only
+    compile, no client change. `group:`/`empty:` stay opt-in (emit only when passed).
+  - **`transition:` takes named legs.** `js.toggle("#x", transition: { during:, from:, to: })`
+    replaces the positional `transition: [during, from, to]` array (which raises with the
+    caller's values slotted into the named form). Compiles to the same wire array — zero
+    client change.
+  - **BREAKING: one registry reader — the plural frozen hash IS the fetch-one.** The seven
+    singular getters (`reactive_action`, `reactive_action?`, `reactive_collection_def`,
+    `reactive_collection?`, `reactive_compute_def`, `reactive_compute?`, and the bare
+    `reactive_compute(:name)` GETTER form) are removed — each raises a guided error naming
+    the hash form (`reactive_actions[:name]`, `reactive_actions.key?(:name)`,
+    `reactive_computes[:name]`, `reactive_collections[:name]`). The resolved registries now
+    come back FROZEN — they are the memoized dispatch table, so mutation raises `FrozenError`
+    and can never corrupt default-deny. The `reactive_compute :name, inputs:, outputs:`
+    SETTER is unchanged.
+  - **`reply.append`/`reply.prepend` accept row kwargs (non-breaking).** Extra kwargs
+    (`reply.append(item, to: :items, autofocus: true)`) now thread through to the row
+    component's initializer (`ItemRow.new(item:, autofocus: true)`). Additive — no-kwarg
+    calls are unchanged.
+  - **`defer.phlex_reactive` joins the frozen instrumentation contract (non-breaking).**
+    The deferred-render endpoint's `ActiveSupport::Notifications` event now has a
+    request-spec contract test driving all five outcomes (`ok`/`no_content`/`invalid_token`/
+    `not_found`/`unauthorized`), freezing its `{ component:, outcome: }` payload shape (a
+    rename fails CI, like `action`/`render`/`broadcast`). Documented in the README
+    instrumentation table and the observability section of the performance docs page.
+
+- **BREAKING: one `broadcast_to` — verbs as kwargs, components as payloads (#185).**
+  The 11 `broadcast_*_to` / `broadcast_*_to_each` methods collapse into ONE
+  `broadcast_to` where the verb is a kwarg and its value is the payload:
+
+  ```ruby
+  # before                                          # after
+  Item.broadcast_replace_to(@list, :todos,          Item.broadcast_to(@list, :todos,
+    model: @todo, morph: true)                        replace: @todo, morph: true)
+  Row.broadcast_append_to(@list, target: t,         Row.broadcast_to(@list, append: item, target: t)
+    model: item)
+  Counter.broadcast_replace_to_each(keys,           Counter.broadcast_to(each: keys, replace: counter)
+    model: counter)
+  Badge.broadcast_js_to(user, :alerts, ops)         Badge.broadcast_to(user, :alerts, js: ops)
+  ```
+
+  A Hash payload is the component's init kwargs verbatim (`update: { room:, author: }`),
+  killing the old `**options` collision (a component with an init kwarg named
+  `target`/`morph`/`exclude` is broadcastable again). Payloads can be BUILT
+  components, and the new module-level `Phlex::Reactive.broadcast_to(@list, :todos,
+  update: TodoCount.new(...), target: "todos-count")` broadcasts a NON-Streamable
+  component (a count badge) — instrumented — without hand-rolling the raw channel +
+  render. Self-targeting verbs (`replace:`/`remove:`) require a Streamable payload
+  (its `#id` is the target); container verbs (`update:`/`append:`/`prepend:`) take any
+  component. Every removed method raises a guided error printing the `broadcast_to`
+  rewrite. `exclude:`/`visible_to:` still thread to pgbus through the capability-gated
+  thread-local path — unchanged (verified against pgbus 0.11.0).
+
+- **BREAKING: `to_stream_morph` is removed — morph is a kwarg (#185).**
+  Use `to_stream_replace(morph: true)` (byte-identical wire). `reply.morph` /
+  `reply.replace(morph: true)` are unchanged.
+
+- **BREAKING: forms & fields — scope everywhere, one dirty declaration, named schemas (#184).**
+  - **`reactive_scope` extends to `reactive_field` and the param unwrap:** a scoped
+    field emits `name="scope[field]"` and the endpoint peels one scope level, so the
+    schema stays flat. A schema nested under the scope key raises a guided
+    `ArgumentError` from BOTH the `action` macro and `reactive_scope` (either
+    declaration order).
+  - **One dirty declaration — `reactive_dirty`:** `reactive_dirty warn_unsaved: true`
+    (class-level) and `reactive_dirty only: %i[title]` replace
+    `reactive_root(track_dirty:, warn_unsaved:)` + `reactive_field(dirty:)`. The
+    removed kwargs raise guided errors; the emitted DOM is unchanged (zero client
+    change).
+  - **Named param schemas — `Phlex::Reactive.param_schema`:** register a reusable
+    schema in an initializer (`param_schema :todo, title: :string, …`) and resolve it
+    with `action :save, params: :todo`, or compose with `{ **param_schema(:todo), … }`.
+    Frozen after boot (the `param_type` precedent); an unknown name lists the
+    registered ones. `params:` still takes a Hash.
+  - **One binding helper:** `reactive_input` / `reactive_select` are removed — use
+    `input(**reactive_field(…))` / `select(**reactive_field(…)) { … }` /
+    `textarea(**reactive_field(…))`. The stubs raise the rewrite.
+
+- **BREAKING: `reactive_compute` is scope-aware, root-bound, and permit-shaped (#183).**
+  - **Bind + listen at the root:** `reactive_root(compute: :name)` emits the compute
+    descriptors AND the `input->reactive#recompute` delegation, so fields carry
+    ZERO per-field wiring. Conditional binding collapses to one expression
+    (`reactive_root(compute: (:split unless @order.persisted?))`; `nil` = no binding).
+    `reactive_compute_attrs(...)` raises a guided error naming the new form.
+  - **Scope-resolved names:** under `reactive_scope :order`, a bare compute input/
+    output `cash` resolves as `[name="order[cash]"]` client-side (the same
+    convention `reactive_show`/`reactive_field` use); a bracketed literal passes
+    through unscoped.
+  - **Permit-style inputs:** `inputs: [:qty, title: :string]` — bare symbols default
+    to `:number`, a trailing Hash types the exceptions. The old array form
+    (`%i[a b]`) and hash form (`{ a: :number }`) are degenerate cases (zero shim,
+    byte-identical wire).
+  - **Sinks declare themselves:** every reducer result key paints into any matching
+    sink — an owned field iff in `outputs:` (the allowlist), any owned
+    `reactive_text` node by presence, any declared `mirror:` id. An `outputs:` entry
+    that existed only to reach a text node is now redundant (old declarations keep
+    working). `reactive_text(:name)` with no explicit initial seeds its first paint
+    from `reactive_values` when covered.
+
+- **BREAKING: `reply` is the only door — the `Response` class verbs are removed (#182).**
+  `Phlex::Reactive::Response.replace(self)` / `.morph` / `.update` / `.remove` /
+  `.redirect` / `.with` / `.streams` (and the collection class methods) are removed
+  as public entry points — each raises a guided `ArgumentError` naming the
+  `reply.<verb>` rewrite. Actions return `reply.<verb>` (the subject-bound door added
+  earlier); the immutable `Response` value object and its instance chain
+  (`.flash`/`.stream`/`.also`/`.js`/`.defer`) are unchanged, so the endpoint reads it
+  exactly as before. One concept, one entry point.
+
+- **BREAKING: reactive-collection replies read as Ruby — `to:`/`from:` keywords (#182).**
+  The collection name moved from a leading Symbol to a keyword, and the `UNSET`
+  sentinel that overloaded `reply.remove` is gone (dispatch keys on `from:`'s
+  presence):
+
+  | Before (removed) | After |
+  |---|---|
+  | `reply.append(:items, item)` | `reply.append(item, to: :items)` |
+  | `reply.prepend(:items, item)` | `reply.prepend(item, to: :items)` |
+  | `reply.remove(:items, id)` | `reply.remove(id, from: :items)` |
+  | `reply.remove` (bare) | `reply.remove` — unchanged (removes self) |
+
+  A Symbol in the model position (the old shape) raises a guided rewrite.
+
+- **BREAKING: one flash contract — `flash_component` is a callable (#182).**
+  `Phlex::Reactive.flash_component` is now a lambda the app owns, so the gem no
+  longer guesses your component's kwargs (the old hardcoded `new(level:, content:)`
+  collided with real flash components):
+
+  ```ruby
+  # before: Phlex::Reactive.flash_component = MyFlash   (gem calls MyFlash.new(level:, content:))
+  # after:
+  Phlex::Reactive.flash_component = ->(level, content) { MyFlash.new(level:, message: content) }
+  ```
+
+  Assigning a Class raises a guided error printing the one-line lambda. The internal
+  flash builders (`flash_stream`/`flash_html`/`default_flash_html`) are now private.
+
+- **BREAKING: `also_update` / `also_replace` collapse into one `.also` (#182).**
+  The lying `html:` kwarg (it accepted components too) and the per-companion method
+  choice are gone:
+
+  ```ruby
+  # before
+  reply.replace.also_update("page_heading", html: @account.name)
+  reply.replace.also_replace(SummaryCard.new(account: @account), morph: true)
+  # after
+  reply.replace.also(page_heading: @account.name)                        # target => content
+  reply.replace.also(SummaryCard.new(account: @account), morph: true)    # a component at its own id
+  ```
+
+  String content is HTML-escaped, component content rendered — the escaping contract
+  is verbatim. `also_update`/`also_replace` raise guided rewrites.
+
+- **BREAKING: the `flash_builder` / `reset_flash_builder!` aliases are removed (#182).**
+  They were "permanent aliases" for `stream_builder` / `reset_stream_builder!` that
+  contradicted the clean-break rule. Each old name now raises a guided `NoMethodError`
+  naming the real method.
+
+### Fixed
+
+- **A pending-state text swap no longer destroys a composite trigger's icon (#181).**
+  The former `disable_with:`/`loading:` text swap wrote `trigger.textContent`, which
+  **flattens every child node** — a `<button><svg/> Save</button>` lost its icon the
+  instant the request enqueued, and it never came back on restore. `busy:`'s swap now
+  reads and restores `innerHTML`, so an icon-plus-label trigger round-trips intact.
+  Covered by a new composite-trigger browser assertion and a JS child-preservation
+  unit test.
+
 - **`exclude:`/`visible_to:` now actually reach pgbus — actor-echo suppression works over SSE (#187).**
   `broadcast_*_to`/`broadcast_*_to_each` passed `exclude:`/`visible_to:` as keyword
   arguments to `Turbo::StreamsChannel.broadcast_*_to`, but turbo-rails swallows
@@ -21,6 +238,32 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Conditional confirm — warn only when the values look suspect (#179).**
+  `confirm:` now takes a Hash for soft-validation-before-submit, so the dialog fires
+  ONLY when the field values are wrong — instead of a hand-written submit handler that
+  inspects fields and calls `confirm()` itself. Two forms, both evaluated client-side
+  over the same collected fields `reactive_compute` reads:
+  - **Declarative** — `confirm: { when: { total: 0 }, message: "Total is 0 — continue?" }`.
+    `when:` reuses `reactive_show`'s conditions language verbatim: a scalar is equals,
+    a `Range` is a threshold (`qty: 100..`), an `Array` is membership. Zero JS. The
+    dialog fires when the condition MATCHES; a clean value submits silently.
+  - **Named predicate** — `confirm: { predicate: "end_before_start", message: "…" }` for
+    multi-field logic the single-field form can't express. Register a pure function at
+    boot (`setConfirmPredicate("end_before_start", ({ starts_at, ends_at }) => ends_at < starts_at)`),
+    the twin of `setComputeReducer`. An unregistered name warns and proceeds without a
+    dialog. Works on `on(...)` AND `on_client(...)`. The predicate is soft-validation UX,
+    **not authorization** — a user can bypass it and the action still hits the endpoint's
+    real authorize/default-deny; never let it stand in for a server-side check.
+
+- **`confirm:` on `on_client(...)` — themed confirmation for zero-round-trip client ops (#178).**
+  The client-op path gains the SAME overridable `confirmResolver` gate `on(:action, confirm:)`
+  has (#52/#55). A destructive-feeling client op (clear a draft, reset a form) gets the
+  app's themed dialog with one line and no round trip:
+  `button(**on_client(:click, js.text("#draft", ""), confirm: "Discard this draft?"))`.
+  The gate lives in the user-gesture path (`runOps`), never in the shared op applier — a
+  server-pushed `reactive:js` op stream must not prompt. `setConfirmResolver` now themes
+  both paths at once.
+
 - **CI transport verification matrix — the browser suite runs on Action Cable AND pgbus (#187).**
   The system job is now `server × transport` (Puma/Falcon × cable/pgbus). The pgbus
   cells add a plain `postgres:18` (pgbus vendors the PGMQ schema via its own
@@ -34,6 +277,28 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **BREAKING: ONE pending-state vocabulary — `busy:` replaces `loading:` / `disable_with:` (#181).**
+  A trigger's declarative pending affordance is now a single `on(…, busy:)` kwarg
+  that shares `optimistic:`'s key vocabulary and normalizer — the only difference
+  is the lifecycle (`busy:` reverts on **settle**, `optimistic:` on **failure**).
+  `busy:` takes a **String shorthand** (`busy: "Saving…"` ≡ `{ disable: true, text:
+  "Saving…" }`) or a **Hash** with the same keys as `optimistic:`
+  (`add_class:`/`remove_class:`/`toggle_class:`/`hide:`/`show:`/`disable:`/`text:`/`to:`).
+  The removed `loading:` (with its odd `class:` key), `disable_with:`, and the
+  `on(…, listnav:)` kwarg each raise a **guided `ArgumentError`** printing the exact
+  rewrite. Combobox keyboard nav is now the standalone `reactive_listnav` (composed
+  via `mix`), which defaults its option selector to `[role=option]`. Migration:
+
+  | Before (removed) | After |
+  |---|---|
+  | `on(:save, disable_with: "Saving…")` | `on(:save, busy: "Saving…")` |
+  | `on(:save, loading: { disable: true, class: "opacity-50", text: "Saving…" })` | `on(:save, busy: { disable: true, add_class: "opacity-50", text: "Saving…" })` |
+  | `on(:search, event: "input", listnav: "[role=option]")` | `mix(on(:search, event: "input"), reactive_listnav)` |
+
+  The wire attribute is renamed `data-reactive-loading-param` → `data-reactive-busy-param`;
+  the client keeps a **read shim** for the old attribute for one minor so an
+  in-flight page rendered by the previous gem across a deploy keeps its affordance.
+
 - **BREAKING: `reactive_show` speaks ONE conditions language — `if:`/`if_any:`/`unless:` (#180).**
   The four accreted dialects (the positional-field predicate kwargs
   `equals:`/`not:`/`in:`/`gte:`/`gt:`/`lte:`/`lt:`, the `all:`/`any:` term