phlex-reactive 0.2.8 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b321b7411a892ec63333f9d85d988f7cf63609601386a03593efd736e88fb42
-  data.tar.gz: 00d40c394774eb54af634d328251f646a3fae1ac9bc0413ccbc89dd863608001
+  metadata.gz: a6b8ebca93e744e1c2fa3797de877cefc732db8a6cb950d95874c9e00e4dee76
+  data.tar.gz: 119b1373f8ade989791845fc9cf3206f7786eb97f6009faaabfadb1485c82b44
 SHA512:
-  metadata.gz: bd7a2129ec09c6b33a9f623f201037f5bc6639f7b097c95f521a6bf7ba4999b8dc8e11f53f2b922f5e617d0dfd8e2b0185cc5676e20f040a9caf97637d2d9438
-  data.tar.gz: b6e611eab9a2ab3f3d3a6afff9c4780061ba07321ddb5db89970e076facc9d7a374f7809fe8bc38958040c34303a42484eefe25109495bdfb2b6f894a597ae3e
+  metadata.gz: ee11a3bf0ac506cdbde2e97e9e47bad436a16050c0b150cd5340bbff9ae846586487bbf6a2bbf028ff20c44faa64f2e57953ddf15adcbafc82491d5e15a9f22f
+  data.tar.gz: 3bd5cd4a362ed18f59da8bf375474aa8beabd5cfdd0d62572d5fce043318c057b01afcf3942acaec30417dc16fd3b3d8d9e6ef9f7ec524f55cf411cc168b8003

data/CHANGELOG.md

@@ -8,6 +8,36 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Input/select param-binding helpers (issue #23).** `reactive_input(:value,
+  …)` and `reactive_select(:status, …) { … }` render a form control already bound
+  to an action param — no hand-written `name: "value"` magic string to forget
+  (which silently leaves the action with no params). `reactive_field(:param,
+  **attrs)` returns just the attribute hash to spread onto any control; an
+  explicit `name:` still wins as an escape hatch. The trigger stays on the
+  button, so focusing the field doesn't dispatch and collapse edit mode.
+- **`accepts_nested_attributes_for` helper (issue #24).** `nested_update!(:address,
+  address)` maps a declared nested param straight onto `<assoc>_attributes` and
+  carries the existing associated record's id, so `update_only:` matches it in
+  place instead of building a second `has_one` — replacing the per-editor
+  `*_attributes` + id-preservation boilerplate that was easy to get subtly wrong.
+  `nested_attributes(:address, address)` returns the id-merged hash without
+  updating, for combining with other attributes.
+- **`Response#also_update` / `#also_replace` (issue #25).** Re-render a companion
+  element alongside self without dropping to raw `turbo_stream_builder`:
+  `Response.replace(self).also_update("page_heading", html: @record.name)` adds an
+  update stream for an arbitrary DOM id (`html` is a string or a Phlex component,
+  rendered through the configured renderer), and `.also_replace(other_component)`
+  re-renders another Streamable component targeting its own `#id`. Both are
+  immutable and additive, so the self-replace still refreshes the signed token.
+- **Boot-time integration guards (issue #26).** Two silent first-run failures now
+  surface a clear warning. A host catch-all route (`match "*path", …`) that
+  shadows the engine's appended `POST /reactive/actions` (every reactive POST
+  404s) is detected at boot via a route-recognition check
+  (`Phlex::Reactive.action_route_ok?`), logging how to exempt the path. And when
+  `data-controller="reactive"` elements are on the page but no controller
+  connected — the `lazyLoadControllersFrom` case where the gem's controller was
+  never registered — the client runtime logs a console warning naming the fix.
+  The README gains an "Integration troubleshooting" section covering both.
 - **Nested & array param types (issue #16).** Action param schemas can now
   declare arrays and nested hashes, not just scalars: wrap a type in an array
   (`bank_account_ids: [:integer]`) for an array param, or wrap a hash schema in

data/README.md

@@ -124,7 +124,7 @@ Import and register it from your controllers entrypoint:
 
 ```js
 import { application } from "./application"
-import ReactiveController from "phlex-reactive/reactive_controller"
+import ReactiveController from "phlex/reactive/reactive_controller"
 application.register("reactive", ReactiveController)
 ```
 
@@ -137,6 +137,47 @@ gem; point your bundler at the gem path or copy it in. See
 and a Phlex `ApplicationComponent` base class. pgbus is optional but recommended
 for broadcasting.
 
+### Integration troubleshooting (silent "nothing happens")
+
+Two host-app setups make the first reactive component *silently do nothing* —
+components render, but no action ever fires, with no error pointing at the cause.
+The gem now logs a warning for each, but here are the fixes:
+
+**A catch-all route shadows `POST /reactive/actions`.** The engine appends its
+route *after* everything in your `config/routes.rb`, so a bottom-of-file
+catch-all wins and every reactive POST 404s:
+
+```ruby
+# config/routes.rb — a catch-all like this shadows the engine's appended route
+match "*path", to: "errors#not_found", via: :all
+```
+
+Exempt the reactive path from the catch-all (or set
+`Phlex::Reactive.action_path` to an unshadowed path):
+
+```ruby
+match "*path", to: "errors#not_found", via: :all,
+  constraints: ->(req) { !req.path.start_with?("/reactive/") }
+```
+
+At boot the gem warns (`[phlex-reactive] POST /reactive/actions does not resolve
+to phlex/reactive/actions …`) when the route is shadowed.
+
+**The `reactive` controller isn't registered (`lazyLoadControllersFrom` apps).**
+`lazyLoadControllersFrom("controllers", application)` only registers controllers
+under `app/javascript/controllers/`. The gem's controller lives outside that dir,
+so `data-controller="reactive"` does nothing until you register it explicitly:
+
+```js
+// app/javascript/controllers/index.js (or your Stimulus entrypoint)
+import ReactiveController from "phlex/reactive/reactive_controller"
+application.register("reactive", ReactiveController)
+```
+
+If reactive elements are on the page but the controller never connected, the
+runtime logs a console warning (`[phlex-reactive] found N element(s) with
+data-controller="reactive" but the reactive controller never connected …`).
+
 ---
 
 ## The mental model in one picture
@@ -269,6 +310,9 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_attrs` | Spread onto the root element: marks it reactive + carries the signed token. |
 | `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). |
+| `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. |
 
 Param types: `:string` (default), `:integer`, `:float`, `:boolean`. Anything not
 in the schema is dropped before reaching your method.
@@ -337,6 +381,47 @@ div(**mix(reactive_attrs, id:, class: "card")) { ... }
 button(**on(:increment), data: { testid: "inc" }) { "+" }
 ```
 
+**Binding inputs to action params (drop the magic `name:`).** A field's value
+travels with an action only if its `name` equals the param. Hand-writing
+`name: "value"` on every input is easy to forget — the action then silently gets
+nothing. `reactive_input`/`reactive_select` emit the binding for you (the trigger
+stays on the button, so focusing the field doesn't dispatch and collapse edit
+mode):
+
+```ruby
+action :save, params: { value: :string, status: :string }
+
+def view_template
+  span(id:, **reactive_attrs) do
+    reactive_input(:value, value: @record.name)            # <input name="value" …>
+    reactive_select(:status) do                            # <select name="status">…</select>
+      %w[open closed].each { |s| option(value: s, selected: s == @record.status) { s } }
+    end
+    button(**mix(on(:save), data: { testid: "save" })) { "Save" }
+  end
+end
+```
+
+`reactive_field(:value, **attrs)` returns just the attribute hash if you'd rather
+spread it onto a control yourself. An explicit `name:` still wins (escape hatch).
+
+**Editing an associated record (`accepts_nested_attributes_for`).** `nested_update!`
+maps a declared nested param straight onto `<assoc>_attributes` and carries the
+existing record's id, so `update_only:` matches it in place instead of building a
+second `has_one` (the boilerplate that's easy to get subtly wrong):
+
+```ruby
+# Account has_one :address; accepts_nested_attributes_for :address, update_only: true
+action :save, params: { address: { street: :string, city: :string } }
+
+def save(address:)
+  nested_update!(:address, address)   # update!(address_attributes: address.merge(id: @account.address&.id))
+end
+```
+
+`nested_attributes(:address, address)` returns the id-merged hash without
+updating, if you need to combine it with other attributes.
+
 ### `Phlex::Reactive::Response` — controlling the action's reply
 
 By default an action re-renders its component in place. **Return** a
@@ -359,18 +444,29 @@ end
 def approve   = (@row.approve!; Response.remove(self))          # drop the element
 def publish   = (@article.publish!; Response.redirect(article_url(@article)))  # slug changed → Turbo.visit
 def add(item:) = Response.replace(self).stream(Totals.update(@order))           # multi-stream
+
+# Re-render a COMPANION element (a heading mirroring the edited name) alongside self:
+def rename(value:) = (@account.update!(name: value); Response.replace(self).also_update("page_heading", html: @account.name))
 ```
 
 | Builder | Reply |
 |---|---|
 | `Response.replace(self)` / `.update(self)` | re-render in place (explicit default) |
-| `.flash(level, content, target: …)` | append a flash; `content` is a string or Phlex component (off-request — no Rails `flash`); target defaults to `Phlex::Reactive.flash_target` (`"flash"`) |
+| `.also_update(target, html:)` | also re-render a companion element by DOM id; `html` is a plain string (escaped) or a Phlex component |
+| `.also_replace(component)` | also re-render another Streamable component, targeting its own `#id` |
+| `.flash(level, content, target: …)` | append a flash; `content` is a plain string (escaped) or a Phlex component (off-request — no Rails `flash`); target defaults to `Phlex::Reactive.flash_target` (`"flash"`) |
 | `Response.remove(self)` | remove the element (backed by `Streamable#to_stream_remove`) |
 | `Response.redirect(url)` | client-side `Turbo.visit` (pass a `*_url`); rides a `reactive:visit` turbo-stream, not an HTTP 3xx |
 | `Response.with(*streams)` / `#stream(*more)` | multi-stream |
 
-`.flash`/`.stream` are additive on a self-replace, so the component's signed
-token always refreshes.
+`.flash`/`.stream`/`.also_*` are additive on a self-replace, so the component's
+signed token always refreshes.
+
+> **`html:`/`content` escaping.** A plain string is **HTML-escaped** by Turbo, so
+> `html: @account.name` is safe even for user-supplied values. To emit intentional
+> markup, pass a **Phlex component** (`html: Heading.new(name: @record.name)`) —
+> rendered and auto-escaped through the renderer — or an `html_safe` string for
+> raw HTML you control.
 
 ### Configuration (`config/initializers/phlex_reactive.rb`)
 

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

@@ -36,6 +36,49 @@ if (typeof window !== "undefined") {
   else document.addEventListener("turbo:load", registerReactiveVisit, { once: true })
 }
 
+// --- Registration guard (issue #26 part 2) -------------------------------
+// In a `lazyLoadControllersFrom("controllers", application)` app, only
+// controllers under app/javascript/controllers/ are registered. This module
+// lives outside that dir, so importing it isn't enough — `data-controller=
+// "reactive"` does NOTHING until the host runs application.register("reactive",
+// ...). The failure is silent: components render, but no action ever fires.
+//
+// We can't warn from connect() in that case (connect never runs). Instead, once
+// the page is ready, if reactive elements exist but no controller has connected,
+// the controller wasn't registered — so we warn, pointing at the fix.
+let reactiveConnected = false
+
+export function checkReactiveRegistration() {
+  if (reactiveConnected) return
+  if (typeof document === "undefined") return
+  const els = document.querySelectorAll('[data-controller~="reactive"]')
+  if (!els || els.length === 0) return
+  console.warn(
+    "[phlex-reactive] found " + els.length + ' element(s) with data-controller="reactive" ' +
+      "but the reactive controller never connected. It is loaded but not registered — " +
+      'add `application.register("reactive", ReactiveController)` (importmap) or import it ' +
+      "into app/javascript/controllers/ for lazyLoadControllersFrom apps. See the README."
+  )
+}
+
+// Test seams (no-ops in production usage).
+export function __resetReactiveRegistrationForTest() {
+  reactiveConnected = false
+}
+export function __markReactiveConnectedForTest() {
+  reactiveConnected = true
+}
+
+if (typeof window !== "undefined" && typeof document !== "undefined") {
+  // Defer past initial controller connection (a microtask/tick after ready).
+  const scheduleCheck = () => setTimeout(checkReactiveRegistration, 0)
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", scheduleCheck, { once: true })
+  } else {
+    scheduleCheck()
+  }
+}
+
 // Register this controller eagerly (not lazily) so a click immediately after
 // page load is never missed. The phlex-reactive engine auto-pins it with
 // preload: true for importmap apps; see the README for esbuild/webpack.
@@ -47,6 +90,12 @@ export default class extends Controller {
   #tokenCache // freshest token, threaded synchronously across queued requests
   #debounceTimers = new Map() // trigger element -> { timer, flush } pending dispatch
 
+  // Mark that a reactive controller actually connected, so the registration
+  // guard above knows the controller was registered (issue #26 part 2).
+  connect() {
+    reactiveConnected = true
+  }
+
   // Tear down any pending debounce timers when the controller leaves the DOM
   // (Turbo morph/navigation removes the element). Otherwise a timer that hasn't
   // fired yet would later call #enqueue on a disconnected controller — a round

data/lib/phlex/reactive/component.rb

@@ -206,8 +206,72 @@ module Phlex
         attrs
       end
 
+      # Bind a form control's `name` to an action param so its value travels with
+      # the action — instead of hand-writing the magic `name: "value"` on every
+      # input and silently getting no params when you forget it (issue #23).
+      # Returns a Phlex attributes hash to spread onto any control:
+      #   input(**reactive_field(:value, value: @record.name))
+      #   select(**reactive_field(:status)) { ... }
+      # Extra attrs merge over the binding; an explicit name: still wins (escape
+      # hatch). The trigger (on(:save)) stays on the button, not the field — so
+      # focusing the input doesn't dispatch and collapse edit mode.
+      def reactive_field(param, **attrs)
+        {name: param.to_s, **attrs}
+      end
+
+      # Render an <input> already bound to an action param (issue #23). Sugar for
+      # input(**reactive_field(param, **attrs)); the value/type/etc. pass through.
+      #   reactive_input(:value, value: @record.name, type: "text")
+      def reactive_input(param, **attrs)
+        input(**reactive_field(param, **attrs))
+      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:
+      #   reactive_select(:status) { @statuses.each { |s| option(value: s, selected: s == @record.status) { s } } }
+      def reactive_select(param, **attrs, &block)
+        select(**reactive_field(param, **attrs), &block)
+      end
+
+      # Map a declared nested param onto Rails' <assoc>_attributes, carrying the
+      # existing associated record's id so accepts_nested_attributes_for matches
+      # it IN PLACE instead of building a second one (issue #24). Returns the
+      # update hash; pass it to update!:
+      #   def save(address:) = nested_update!(:address, address)
+      # The id is only added when the association already exists, so the first
+      # save (no associated record yet) creates one cleanly. The given attrs are
+      # not mutated.
+      def nested_attributes(association, attrs)
+        merged = attrs.dup
+        existing = reactive_record_for_nested.public_send(association)
+        merged[:id] = existing.id if existing
+
+        {"#{association}_attributes": merged}
+      end
+
+      # Map a nested param onto <assoc>_attributes (with id preservation) AND
+      # apply it to the component's record in one call (issue #24). Extra keyword
+      # attributes update alongside the association.
+      #   def save(address:, name:) = nested_update!(:address, address, name:)
+      def nested_update!(association, attrs, **extra)
+        reactive_record_for_nested.update!(**nested_attributes(association, attrs), **extra)
+      end
+
       private
 
+      # The component's record, for the nested-attributes helpers. Requires a
+      # declared reactive_record (the nested helper only makes sense for a
+      # record-backed component).
+      def reactive_record_for_nested
+        key = self.class.reactive_record_key
+        unless key
+          raise Error, "#{self.class} must declare `reactive_record` to use nested_update!/nested_attributes"
+        end
+
+        instance_variable_get(:"@#{key}")
+      end
+
       # Signed identity payload: the class name plus whichever identity pieces
       # the component declares — a record GlobalID (`gid`), signed state (`s`),
       # or both. Keeping them in ONE MessageVerifier payload makes the state

data/lib/phlex/reactive/engine.rb

@@ -40,6 +40,15 @@ module Phlex
           )
         end
       end
+
+      # Boot-time guard (issue #26): warn if the action path doesn't resolve to
+      # the gem controller. Runs after_initialize so the host's full route set
+      # (including a bottom-of-file catch-all that would shadow our appended
+      # route) is drawn. Turns the opaque "every reactive POST 404s" failure into
+      # a one-line log pointing at the cause. No-op when the route is fine.
+      config.after_initialize do
+        Phlex::Reactive.warn_unless_action_route_mounted!
+      end
     end
   end
 end

data/lib/phlex/reactive/response.rb

@@ -12,6 +12,7 @@ module Phlex
     #
     #   Response.replace(self)                          # re-render in place (the default, explicit)
     #   Response.replace(self).flash(:error, msg)       # surface a validation error
+    #   Response.replace(self).also_update("heading", html: @record.name)  # + a companion element
     #   Response.remove(self)                           # drop the element (e.g. moderation queue)
     #   Response.redirect(article_url(@article))        # slug changed -> Turbo.visit the new URL
     #   Response.replace(self).stream(Totals.update(@order))  # multi-stream
@@ -44,8 +45,27 @@ module Phlex
         # supplied by the caller because the render context is off-request
         # (there is no Rails `flash`).
         def flash_stream(_level, content, target:)
-          html = content.is_a?(::Phlex::SGML) ? Phlex::Reactive.render(content) : content.to_s
-          Phlex::Reactive.flash_builder.append(target, html: html)
+          Phlex::Reactive.flash_builder.append(target, html: render_html(content))
+        end
+
+        # Build a turbo-stream that updates an arbitrary target id with `content`
+        # (a Phlex component instance or an HTML string). Used by #also_update to
+        # re-render a companion element that isn't itself a Streamable component.
+        def update_stream(target, content)
+          Phlex::Reactive.flash_builder.update(target, html: render_html(content))
+        end
+
+        # Resolve `content` to the HTML for a turbo-stream's `html:`. Two forms,
+        # both SAFE against injection by default:
+        #   * a Phlex component instance — rendered through the configured
+        #     renderer, which auto-escapes interpolated values.
+        #   * any other value — coerced with to_s and handed to Turbo's
+        #     TagBuilder, which HTML-ESCAPES a plain String. So a model value
+        #     (`html: @record.name`) cannot inject markup. To emit intentional
+        #     raw HTML, pass an `html_safe` String (Turbo leaves those verbatim)
+        #     or a Phlex component. Same contract as the pre-existing flash_stream.
+        def render_html(content)
+          content.is_a?(::Phlex::SGML) ? Phlex::Reactive.render(content) : content.to_s
         end
       end
 
@@ -76,6 +96,27 @@ module Phlex
         stream(self.class.flash_stream(level, content, target:))
       end
 
+      # Also re-render a COMPANION element alongside self — a page heading, a
+      # summary card, a badge that recomputes from the saved value (issue #25).
+      # `target` is the sibling element's DOM id. `html` is either:
+      #   * a plain String — HTML-ESCAPED by Turbo, so a model value is safe:
+      #       Response.replace(self).also_update("page_heading", html: @record.name)
+      #   * a Phlex component — rendered + auto-escaped through the renderer (use
+      #     this when the companion has its own markup), or an `html_safe` String
+      #     for intentional raw HTML.
+      # Returns a NEW Response (immutable). The common "re-render self + N
+      # siblings" case no longer needs raw turbo_stream_builder.
+      def also_update(target, html:)
+        stream(self.class.update_stream(target, html))
+      end
+
+      # Like #also_update, but renders ANOTHER Streamable component and replaces
+      # it by its own #id — for a companion that is itself a component.
+      #   Response.replace(self).also_replace(SummaryCard.new(order: @order))
+      def also_replace(component)
+        stream(component.to_stream_replace)
+      end
+
       def redirect? = !@redirect_url.nil?
       def render_self? = @render_self
     end

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.2.8"
+    VERSION = "0.2.9"
   end
 end

data/lib/phlex/reactive.rb

@@ -133,8 +133,62 @@ module Phlex
         Thread.current[:phlex_reactive_connection_id] = previous
       end
 
+      # The controller a correctly-mounted action path resolves to. Used by the
+      # route guard below.
+      ACTIONS_CONTROLLER = "phlex/reactive/actions"
+
+      # True when a POST to `path` resolves to the gem's ActionsController. A host
+      # catch-all route (match "*path", ...) appended above the engine's route
+      # SHADOWS it, so every reactive POST 404s and none of the controller runs —
+      # the opaque "is the endpoint even mounted?" failure (issue #26). A false
+      # here is the signal. Returns false (not raise) when nothing matches.
+      def action_route_ok?(path = action_path)
+        return false unless defined?(::Rails) && ::Rails.application
+
+        # At after_initialize (when the boot guard runs) the host's routes may not
+        # be drawn yet, so recognize_path would see an incomplete set and report a
+        # false shadow. Force-load routes first (idempotent — no-op if already
+        # loaded), so the check is correct whether it runs at boot or at runtime.
+        ensure_routes_loaded
+        recognized = ::Rails.application.routes.recognize_path(path, method: :post)
+        recognized[:controller] == ACTIONS_CONTROLLER
+      rescue ActionController::RoutingError, ActiveRecord::RecordNotFound
+        false
+      end
+
+      # Log a clear warning (once, at boot) when the action path doesn't resolve
+      # to the gem controller — pointing at the catch-all shadow rather than
+      # leaving an adopter to guess. Called from the engine's after_initialize.
+      def warn_unless_action_route_mounted!(path: action_path, logger: default_logger)
+        return if action_route_ok?(path)
+        return unless logger
+
+        logger.warn(
+          "[phlex-reactive] POST #{path} does not resolve to #{ACTIONS_CONTROLLER}. " \
+          "A host catch-all route (e.g. match \"*path\", ...) likely shadows it, so reactive " \
+          "actions will 404. Exempt #{path.sub(%r{\A/}, "")} from the catch-all, or set " \
+          "Phlex::Reactive.action_path to an unshadowed path. See the README integration section."
+        )
+      end
+
       private
 
+      # Materialize the route set if it hasn't been drawn yet (the engine appends
+      # POST /reactive/actions when routes are drawn, which may be after the boot
+      # guard's after_initialize). Idempotent; tolerant of older Rails.
+      def ensure_routes_loaded
+        reloader = ::Rails.application.routes_reloader
+        if reloader.respond_to?(:execute_unless_loaded)
+          reloader.execute_unless_loaded
+        elsif ::Rails.application.respond_to?(:reload_routes_unless_loaded)
+          ::Rails.application.reload_routes_unless_loaded
+        end
+      end
+
+      def default_logger
+        ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
+      end
+
       def default_verifier
         unless defined?(::Rails) && ::Rails.application
           raise Error, "Phlex::Reactive.verifier is unset and Rails.application is unavailable; " \

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.2.9
 platform: ruby
 authors:
 - Mikael Henriksson