phlex-reactive 0.12.4 → 0.12.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 735a21537bb98a3b89ba46f21fe40630ee413191e5509db2fe7895172e6b92b7
-  data.tar.gz: 2110972a68b3ff0c336255afe15674167d9012201ebe80479a5c84fff922e682
+  metadata.gz: 7a9ece1128621af6ad4b9b8e249c1005bcfd063e0aa70235800292f156ac4419
+  data.tar.gz: f8613e2ec77fb55d1f9b5b0b30719382ef5e52c2a34d1ff6bcc29f9a017bafc7
 SHA512:
-  metadata.gz: 7f6c98822ac5eabbcfdd39b6bdbbbd50176e6d4d5735b5eb0189321ac26e0b559ccc7f8ec60c9394492e23e53eb7e77b79c89c0298f1c962b2115961f8cbfc48
-  data.tar.gz: 4b7dc6d779d5f250592387b3cb9615b4d9d37a5994c0b03e3b83ad1e740251e9875b06735b79a02e304ba0fe53b659220950c47906d0805d0128e81b84231966
+  metadata.gz: 19130860688333ec585f3da94ff25be2f8fc8c3fd103c023c98d4ac528921d7b02a7362448b864f81b435d35fc8946e0a3be7ba41f70f57751b115ed09b9a394
+  data.tar.gz: a6efc22b0270eb3e1f4cc7732cc1394acd40dd80de81b12a1dd792df9d2e3952bf5070872e21884cdcc9a5c91211791e74fc31e81f2f25cc1116587446a636c3

data/CHANGELOG.md

@@ -8,6 +8,41 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`reactive_persist` — client-only localStorage drafts (#239).** "Don't make
+  me start over": spread `reactive_persist(key:, ttl: 7.days)` on a root and
+  the generic controller keeps a `localStorage` draft of every **owned**
+  control — a debounced write on `input`, immediate on `change`, flushed on
+  disconnect — and restores it on the next connect, **first** among the
+  client bindings so `reactive_show` / `reactive_on_complete` (armed, never
+  fired) / `reactive_filter` / a compute root read the restored values on
+  first paint with no synthetic events. A draft lands only in controls the
+  server rendered blank (`restore: :always` lets it win); a morph is never
+  re-restored. Cleared by a successful `turbo:submit-end` of the containing
+  form, `ttl` expiry, or the new actor-only `js.persist_clear` op;
+  `js.persist_state(step: 2)` merges a flat state bag into the draft (restored
+  as `data-reactive-persist-state` + the `reactive:persist-restored` event).
+  `hidden`/`file`/`password`/`submit` controls, `reactive_persist_skip`
+  markers, nested roots and rich-text editors are never persisted; `fields:`
+  narrows the set. Storage failures are silent (a `console.info` under
+  `Phlex::Reactive.debug`). Works from `ClientBindings` (no token, no POST).
+
+- **Dev-mode warning when a client op resolves zero targets (#237).** A client
+  op that matches nothing is indistinguishable from a working no-op, and the
+  three documented scoping traps — the nested-root ownership filter, a selector
+  that matches the component's own root (root-scoped resolution never includes
+  the root itself), and the op stream's default target scope — all present
+  exactly that way. Now `verbose_errors` (on by default in dev/test) reaches
+  the client as `data-reactive-verbose="true"` on reactive roots and on
+  server-emitted `reactive:js` streams, and under that gate (or full
+  `debug` mode) the interpreter `console.warn`s once per unique
+  (op, selector, scope) naming the op, the selector, and the scoping root —
+  plus the documented escape (`to: :root` / `global: true`) as a hint when the
+  element exists in the DOM but sits outside the op's scope. Covers `on_client`
+  ops, reducer `$ops`, `reply…js(...)` / `broadcast_js_to` streams (including a
+  stream whose `target` root id has left the DOM), and busy/optimistic hint
+  targets. Production (flag off) renders no attribute and stays byte-identical
+  and silent; resolution behavior itself is unchanged everywhere.
+
 - **`js.paste_into(selector)` — the clipboard-source trigger (#228).** A field
   whose real `<input>` is visually hidden (an OTP cell UI painted by a
   `reactive_compute` reducer) has no mouse-reachable paste path: right-click →
@@ -315,6 +350,53 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **`Component::Action` renamed `ActionDefinition` — it shadowed a host kit
+  component named `Action` under dev autoloading (#233).** The mixin sits in
+  every reactive component's ancestry, so its bare `Action` constant satisfied
+  Phlex::Kit's LazyLoader `const_get` check with the wrong class: the kit's
+  real `Action` component never autoloaded and the call fell through to
+  `NoMethodError` — intermittently (any unrelated load of the kit class masks
+  it until the next reload) and only under lazy autoloading, so an
+  eager-loaded test suite stays green. The rename matches its siblings
+  (`ComputeDefinition`, `OnCompleteDefinition`, `CollectionDefinition`) and
+  removes the constant entirely — **deliberately no alias**, since any
+  `Action` constant in the ancestry re-creates the shadowing. Breaking only
+  for code referencing the internal
+  `Phlex::Reactive::Component::Action` Data class directly; the `action :name`
+  DSL and `reactive_actions` registry are unchanged. A regression spec guards
+  the whole component ancestry against `:Action` coming back.
+
+- **Multipart path corrupted/dropped fields with Rails-bracketed names (#231).**
+  `#buildFormData` wrapped every collected field/file name verbatim as
+  `params[<name>]`, so `blog_post[summary]` went out as the Rack-unparseable
+  `params[blog_post[summary]]` — the scalar arrived as `{"]" => value}` (and a
+  writer stringified that hash into the record, with a 200), and a `:file` under
+  a bracketed name (`blog_post[image]`) never reached its schema key (silent
+  drop). It only fired when a file input was populated — the JSON path expands
+  the same names server-side — which is why flat-named forms never caught it.
+  The client now bracket-expands the field **name** into wire segments
+  (`params[blog_post][summary]`, `params[blog_post][image]`, and
+  `params[photos][]` for a `multiple` picker named `photos[]`), mirroring the
+  server's `bracket_path` exactly, so a multipart body and a JSON body coerce
+  identically for the same fields. Flat names are byte-identical to before.
+
+- **Reply-rendered components now generate absolute URLs with the REQUESTING
+  host, not the process default (#232).** Actor replies (`reply.replace`,
+  `reply.streams(...)`, the implicit replace) render through the memoized
+  off-request view context, whose `url_options` were process defaults — so any
+  absolute URL helper (`image_tag` on an Active Storage attachment being the
+  everyday case) rendered the wrong host on a multi-host app: a broken image
+  after every save, healed by the next full page load. The action endpoint now
+  threads the request's protocol/host/port into the reply render (the
+  `ActiveStorage::SetCurrent` move) via a thread-local the memoized context
+  merges per call — the context is never rebuilt, so the render memoization
+  win is untouched (allocations byte-identical, throughput flat within noise).
+  The defer **pull** endpoint gets the same treatment (it is an actor request).
+  **Broadcasts are unchanged by design** — there is no request and subscribers
+  can be on different hosts, so a broadcast fired *inside* an action explicitly
+  clears the actor's url_options around its render; "URLs in broadcast-rendered
+  components must be host-relative" is now documented in the Broadcasting guide.
+
 - **`rake bench` ran the removed `broadcast_replace_to` API and exited 1.**
   `benchmark/micro/broadcast.rb` migrated to the #185 spellings
   (`broadcast_to(*key, replace:)` / `broadcast_to(each:, replace:)`); the

data/README.md

@@ -385,11 +385,13 @@ 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), and `paste_into` (read the clipboard into a field, gesture-gated) — chainable. |
+| `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. |
 | `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). |
 | `reactive_show_targets(:field, "#id" => value)` | **Cross-root visibility**: the component that owns the field declares which **outside**, id-allowlisted elements it governs (a nav tab, a panel in another pane) — the visibility parallel of `mirror:`. Spread on the **root** via `mix(reactive_root, …)`, **once per root** — several fields go in one call via the hash form. The value uses the same `where`-style vocabulary (`"advanced"`, `%w[a b]`, `10..`); a `"#id"` **key** takes a full conditions Hash for a **multi-field** predicate (`"#warn" => { if: { type: "trade", price: ..0 } }`). Id selectors only (raise at render + client warn-skip); toggles `hidden` only. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
+| `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_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). |
@@ -458,7 +460,10 @@ a populated `<input type="file">`, the client sends the action as multipart
 `FormData` (instead of JSON) — `token` + `act` as fields, scalar params as fields,
 any nested/array params bracket-expanded into `params[key][sub]` /
 `params[key][index]` fields (the same Rails-form shape, so a JSON body and a
-multipart body coerce identically — #39), and the file(s) appended; the endpoint
+multipart body coerce identically — #39), and the file(s) appended. A
+Rails-bracketed field **name** (`blog_post[summary]`, `blog_post[image]`)
+expands the same way — `params[blog_post][summary]`, never the unparseable
+`params[blog_post[summary]]` (#231). The endpoint
 coerces `:file` to the `ActionDispatch::Http::UploadedFile`, passed through
 untouched. A non-file value sent to a `:file` param is dropped (the keyword
 default applies — never a fabricated file). Token threading and the
@@ -822,6 +827,14 @@ field collection); `:root` targets the root element itself; `global: true` on
 an op escapes to the whole document. An op name the client doesn't recognize
 logs a warning and is skipped — the rest of the chain still applies.
 
+In development and test (`verbose_errors`), an op whose selector resolves to
+**zero elements** also warns once per unique (op, selector, scope) — with a
+targeted hint when the element exists but sits outside the op's scope: "use
+`to: :root`" when the selector matches the component's own root (root-scoped
+resolution never includes the root itself), or "use `global: true`" when it
+matches only inside a nested reactive root or elsewhere in the document.
+Production stays silent — a zero-match no-op is legitimate there.
+
 **Attributes, focus, dispatch, and transitions.** Beyond visibility and classes,
 the same chain covers the rest of the client-only vocabulary:
 
@@ -1092,6 +1105,82 @@ field; a missing owned field reads as blank — fail-closed). Every referenced
 field must be owned by the declaring root; a target whose fields are all
 unowned is left alone, like the single-field skip.
 
+### Client-only drafts (`reactive_persist`)
+
+"Don't make me start over": a public application form, a multi-step wizard,
+a long comment box — the user types, navigates away, comes back, and expects
+their draft. Nothing the server needs until submit, no signed-in user to
+autosave for. `reactive_persist` (#239) is the `reactive_show`-shaped answer:
+a **declared, client-only** binding over the fields the root **owns**, no
+token, no POST, no expression surface — the generic controller keeps a
+`localStorage` draft and every hand-rolled "local save" Stimulus controller
+goes away.
+
+```ruby
+class ApplicationForm < ApplicationComponent
+  include Phlex::Reactive::ClientBindings     # or the full Component
+  reactive_scope :apply
+
+  def view_template
+    form(action: "/applications", method: "post") do
+      div(**mix(reactive_root(id: "apply"), reactive_persist(key: "village-apply", ttl: 7.days))) do
+        input(**reactive_field(:name))                              # persisted
+        textarea(**reactive_field(:bio))                            # persisted
+        input(name: "fuckery", **reactive_persist_skip)             # honeypot — never
+        input(type: "hidden", name: "apply[tz]")                    # hidden — never (default)
+        button(**on_client(:click, js.persist_state(step: 2))) { "Next" }
+        button(**on_client(:click, js.persist_clear)) { "Discard draft" }
+        button(type: "submit") { "Apply" }
+      end
+    end
+  end
+end
+```
+
+Spread it on the **root** (`mix` with `reactive_root`), **once per root**. One
+wire attr: `data-reactive-persist='{"key":"village-apply","ttl":604800,"debounce":300}'`.
+
+- **Write** — on `input` (trailing-edge debounce, `debounce:` ms, default 300)
+  and immediately on `change`; a pending write is **flushed on disconnect**, so
+  a fast Turbo navigation never loses the last keystrokes. The snapshot is a
+  full pass over the owned controls: radios store the checked value, checkboxes
+  the checked state, `<select multiple>` an array, everything else `.value`.
+- **Restore** — on connect, **first** among the client bindings, so a
+  `reactive_show` section, `reactive_on_complete` (armed, never fired),
+  `reactive_filter` and a `reactive_compute` root all read the restored values
+  on first paint — no synthetic events. A morph or broadcast re-render is
+  server truth and is **never** re-restored.
+- **`restore: :blank`** (default) — a draft value lands only in a control the
+  server rendered **blank**, so a 422 re-render's submitted values beat an
+  older draft. `restore: :always` lets the draft win.
+- **Clear** — a successful `turbo:submit-end` of the form that contains the
+  root, `ttl` expiry (checked on read; default `7.days`), or `js.persist_clear`.
+  A successful *reactive* action does **not** clear on its own — chain
+  `reply.js(js.persist_clear)` from the action when it should.
+- **`fields:`** narrows the set to declared names (scope-aware symbols):
+  `reactive_persist(key: "k", fields: %i[name bio])`.
+- **Never persisted**: `type=hidden/file/password/submit/button/reset/image`,
+  anything carrying `reactive_persist_skip`, a nested reactive root's controls,
+  and rich-text/`contenteditable` editors (they aren't `input/select/textarea`).
+  `autocomplete="off"` is **not** an implicit skip — a wizard often sets it
+  form-wide. **Honeypots must opt out** (`reactive_persist_skip`) or sit outside
+  the root: an invisible-captcha text input looks like any other field.
+- **State bag** — `js.persist_state(step: 2)` merges a flat hash of scalars
+  into the same draft (a wizard's current step). On restore the root carries
+  `data-reactive-persist-state='{"step":2}'` and dispatches a bubbling
+  `reactive:persist-restored` event (`detail: { key, fields, state }`) — the
+  hook for your own wizard controller to jump to the saved step.
+- **Storage failures are silent** — a private window, a quota error or blocked
+  storage degrades to "no draft". Under `Phlex::Reactive.debug` the controller
+  prints one `console.info` naming the failure so a dev sees why nothing came
+  back.
+
+Threat model: values are replayed via `.value`/`.checked` only (never HTML) — a
+tampered draft can only fill what the user could type. PII sits in this
+browser's `localStorage` for `ttl`; the submit-clear and `ttl` are the
+shared-computer mitigation. `persist_state`/`persist_clear` are **actor-only**
+ops (refused by `broadcast_to(js:)`). See the [security page](docs/security.md).
+
 ### Client-side computes (`reactive_compute` + `reactive_text`)
 
 Some math should feel instant with **no round trip** — a NEW, unsaved record's
@@ -2600,6 +2689,19 @@ helper — a child row rendering a trigger for its container's action) is skippe
 `on_client` triggers are never checked (they aren't declared actions). The
 server's default-deny stays the security boundary — this is a dev-time courtesy.
 
+The flag reaches the **client** too: reactive roots (and server-emitted
+`reactive:js` streams) carry `data-reactive-verbose="true"` when it is on, and
+the client op interpreter uses that gate to `console.warn` when a client op —
+`on_client`, a reducer's `$ops`, `reply…js(...)`, `broadcast_js_to`, or a
+busy/optimistic hint — resolves **zero targets**. The warning names the op, the
+selector, and the scoping root, dedupes per unique case per page, and hints the
+documented escape (`to: :root` / `global: true`) when the element exists but
+was filtered out by root scoping or the nested-root ownership rule — the trap
+where the element is right there in the DOM, just outside the op's scope. A
+`reactive:js` stream whose `target` root id has left the DOM warns the same
+way instead of silently dropping its ops. Production (flag off) renders no
+attribute and stays byte-identical and silent.
+
 See [docs/security.md](https://phlex-reactive.zoolutions.llc/docs/security) for the threat model and a checklist.
 
 ---

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

@@ -39,9 +39,17 @@ module Phlex
         # #165 security), so the defer endpoint accepts them ONLY back from this
         # same actor. The defer token is built in response_streams (inside this
         # block via the Defer builder), so the binding must be established here.
-        Phlex::Reactive.with_defer_binding(Phlex::Reactive.defer_binding_for(request)) do
-          Phlex::Reactive.instrument("action", event) do
-            create_action(event)
+        # Thread the ACTOR's url_options (protocol/host/port) into the reply
+        # render (issue #232): the reply renders through the memoized
+        # off-request view context, whose process-default url_options emit the
+        # wrong host for absolute URL helpers on a multi-host app. Broadcasts
+        # fired inside the action are exempted at their render (see
+        # Streamable.broadcast_component) — subscribers can be on other hosts.
+        Phlex::Reactive.with_url_options(Phlex::Reactive.url_options_for(request)) do
+          Phlex::Reactive.with_defer_binding(Phlex::Reactive.defer_binding_for(request)) do
+            Phlex::Reactive.instrument("action", event) do
+              create_action(event)
+            end
           end
         end
       end
@@ -62,9 +70,14 @@ module Phlex
         # so a leaked token can't be exchanged here for this actor's render (and
         # its embedded fresh identity token). Unbound requests (no session) are
         # unchanged.
-        Phlex::Reactive.with_defer_binding(Phlex::Reactive.defer_binding_for(request)) do
-          Phlex::Reactive.instrument("defer", event) do
-            deferred_action(event)
+        # The defer PULL is an actor request too (issue #232) — its render gets
+        # the same request-derived url_options as the action reply. The PUSH
+        # lane (job → SSE) has no request and stays on process defaults.
+        Phlex::Reactive.with_url_options(Phlex::Reactive.url_options_for(request)) do
+          Phlex::Reactive.with_defer_binding(Phlex::Reactive.defer_binding_for(request)) do
+            Phlex::Reactive.instrument("defer", event) do
+              deferred_action(event)
+            end
           end
         end
       end