phlex-reactive 0.2.9 → 0.4.0

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

@@ -78,6 +78,19 @@ module Phlex
         return [redirect_stream(result.redirect_url)] if result.redirect?
 
         streams = result.streams
+
+        # Partial update (Response.streams / reply.streams, issue #30): the action
+        # re-rendered only PART of the component and opted out of the full-self
+        # replace. Append a tiny token-only stream so the signed token still rolls
+        # forward WITHOUT re-rendering (and clobbering) the live inputs. Skip it
+        # only if the caller already supplied THIS component's token (idempotent) —
+        # the dedupe is scoped to the actor's own target, NOT a global substring,
+        # so a partial reply that legitimately includes another reactive
+        # component's stream (which carries its OWN token) still refreshes ours.
+        if result.refresh_token? && !carries_token_for?(streams, result.token_component)
+          return [*streams, result.token_component.to_stream_token]
+        end
+
         # Guarantee the component's signed identity token is refreshed unless the
         # Response opted out (remove/redirect navigate away — handled above). The
         # client reads the next token from the response body (#extractToken), so
@@ -88,12 +101,23 @@ module Phlex
         # replace when a hand-built `with(...)` stream omits it. Idempotent: a
         # Response.replace(self)/update(self) already carries the token, so we
         # don't double the self-render.
-        if result.render_self? && streams.none? { |s| s.include?("data-reactive-token-value") }
+        if result.render_self? && streams.none? { it.include?("data-reactive-token-value") }
           streams = [component.to_stream_replace, *streams]
         end
         streams
       end
 
+      # True when one of `streams` already carries a fresh token TARGETING this
+      # component — i.e. the caller hand-built the actor's own token-bearing
+      # stream, so appending to_stream_token would double it. Scoped to the
+      # component's target id (not a global substring) so a sibling component's
+      # stream, which carries its OWN token for a DIFFERENT target, doesn't fool
+      # us into skipping this component's refresh.
+      def carries_token_for?(streams, component)
+        target = %(target="#{ERB::Util.html_escape(component.id)}")
+        streams.any? {  it.include?("data-reactive-token-value") && it.include?(target) }
+      end
+
       # A 200 turbo-stream carrying a namespaced custom action the client turns
       # into Turbo.visit — NOT an HTTP 3xx, which the client hard-bails on
       # (response.redirected). The matching client handler is registered in
@@ -102,9 +126,9 @@ module Phlex
         %(<turbo-stream action="reactive:visit" data-url="#{ERB::Util.html_escape(url)}"></turbo-stream>)
       end
 
-      def transaction_wrapper(&block)
+      def transaction_wrapper(&)
         if defined?(::ActiveRecord::Base)
-          ::ActiveRecord::Base.transaction(&block)
+          ::ActiveRecord::Base.transaction(&)
         else
           yield
         end
@@ -139,29 +163,60 @@ module Phlex
 
       # Coerce a value against a declared type. A type is one of:
       #   * a scalar symbol            (:string/:integer/:float/:boolean)
+      #   * :file                      — a multipart upload (issue #34)
       #   * a Hash schema              ({ id: :integer, ... })   — nested object
       #   * a one-element Array        ([:integer] / [{ ... }])  — array of that
       # Arrays accept both a real JSON array and a Rails-style index hash
       # ({ "0" => ..., "1" => ... }), so a fields_for collection works either way.
       def coerce(value, type)
-        if type.is_a?(Array)
+        case type
+        when Array
           coerce_array(value, type.first)
-        elsif type.is_a?(Hash)
+        when Hash
           coerce_hash(value, type)
+        when :file
+          coerce_file(value)
         else
           coerce_scalar(value, type)
         end
       end
 
+      # An uploaded file (issue #34) passes through UNTOUCHED — never .to_s'd,
+      # which would corrupt it into a string the action can't attach. Anything
+      # that isn't an uploaded file (a forged/malformed scalar, an empty input)
+      # returns DROP, so the method's keyword default applies — consistent with
+      # the #16 rule that a value that can't be coerced to its type is dropped,
+      # not fabricated. Duck-types on UploadedFile's interface (original_filename
+      # + a readable IO) rather than naming a class, so a Rack::Test upload, an
+      # ActionDispatch upload, and a Falcon multipart body all qualify.
+      def coerce_file(value)
+        uploaded_file?(value) ? value : DROP
+      end
+
+      def uploaded_file?(value)
+        value.respond_to?(:original_filename) && value.respond_to?(:read)
+      end
+
       # A real array (or Rails index hash) coerces element-wise. A malformed
       # present-but-non-array value returns DROP rather than [] — coercing a stray
       # scalar to an empty array would let a bad payload read as an explicit
       # "clear everything" on update!(declared_array:).
+      #
+      # An ELEMENT that coerces to DROP (e.g. a non-file in a [:file] array, a
+      # forged/mixed payload) is rejected from the result — the same rule
+      # coerce_hash applies to a dropped value, so the internal DROP sentinel
+      # never leaks into the action. A genuinely empty input array stays [] (an
+      # explicit empty collection), but an array whose every element drops
+      # returns DROP, so the keyword default applies rather than handing the
+      # action a surprise [].
       def coerce_array(value, element_type)
         values = array_values(value)
         return DROP if values.nil?
+        return [] if values.empty?
 
-        values.map { |element| coerce(element, element_type) }
+        coerced = values.map { coerce(it, element_type) }
+        coerced.reject! { it.equal?(DROP) }
+        coerced.empty? ? DROP : coerced
       end
 
       # Keep declared keys only (drop undeclared — no mass assignment), recursing
@@ -195,9 +250,9 @@ module Phlex
       def array_values(value)
         return value.to_a if value.is_a?(Array)
 
-        if value.respond_to?(:to_unsafe_h) || value.is_a?(Hash)
-          to_param_hash(value).sort_by { |k, _| k.to_i }.map(&:last)
-        end
+        return unless value.respond_to?(:to_unsafe_h) || value.is_a?(Hash)
+
+        to_param_hash(value).sort_by { |k, _| k.to_i }.map(&:last)
       end
 
       # Unwrap ActionController::Parameters (or a plain Hash) to a string-keyed
@@ -234,13 +289,19 @@ module Phlex
         end
       end
 
+      # Matches each bracket segment in "items_attributes][0][qty]" — the part
+      # after the first "[". Hoisted to a frozen constant so coercing a bracketed
+      # key doesn't recompile the pattern per key on every request.
+      BRACKET_SEGMENT = /[^\[\]]+/
+      private_constant :BRACKET_SEGMENT
+
       # "invoice[items_attributes][0][qty]" => ["invoice", "items_attributes",
       # "0", "qty"]. A key with no brackets is a single-element path.
       def bracket_path(key)
         return [key] unless key.include?("[")
 
         head, rest = key.split("[", 2)
-        [head, *rest.scan(/[^\[\]]+/)]
+        [head, *rest.scan(BRACKET_SEGMENT)]
       end
 
       # Walk/create nested hashes along `path`, then merge `value` at the leaf so
@@ -270,7 +331,7 @@ module Phlex
       # already gates this; defense in depth against constant injection.
       def resolve_component(name)
         klass = name.to_s.safe_constantize
-        unless klass&.respond_to?(:reactive_action?) && klass.include?(Phlex::Reactive::Component)
+        unless klass.respond_to?(:reactive_action?) && klass.include?(Phlex::Reactive::Component)
           raise Phlex::Reactive::InvalidToken
         end
 

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

@@ -4,12 +4,16 @@ import { Controller } from "@hotwired/stimulus"
 // replaces the per-feature Stimulus controllers you'd otherwise hand-write
 // for interactive components. A component declares its actions in Ruby (via
 // Phlex::Reactive::Component); this controller binds DOM events to a single
-// HTTP round trip and lets Turbo morph the re-rendered component back in.
+// HTTP round trip and lets Turbo apply the re-rendered component back in
+// (replace by default; method="morph" — Response.morph — preserves focus).
 //
 // Wire format (client -> server), POST <action path>, turbo-stream Accept:
-//   { token: "<signed identity>", act: "<action>", params: {...} }
+//   { token: "<signed identity>", act: "<action>", params: {...} }   (JSON)
 // (`act`, not `action`: `action` is a reserved Rails routing param.)
 // The token is a MessageVerifier-signed { component, gid } — NO state is sent.
+// When the root holds a chosen <input type="file">, the SAME payload is sent as
+// multipart FormData instead (token/act flat, params bracketed, files appended)
+// so an upload reaches the action (issue #34) — only the encoding differs.
 // The response is a <turbo-stream> that replaces the component by its id.
 //
 // Server -> client live updates use the SAME element id, pushed over the
@@ -31,9 +35,38 @@ export function registerReactiveVisit() {
     if (url) window.Turbo.visit(url, { action: "advance" })
   }
 }
+
+// Custom turbo-stream action: a TOKEN-ONLY refresh (issue #30). A partial
+// update (Response.streams / reply.streams) re-renders only PART of a component
+// — so there's no full-self replace to carry the next signed token. The server
+// instead emits `<turbo-stream action="reactive:token" target="<id>"
+// data-reactive-token-value="<fresh>">`. #perform's #extractToken already reads
+// the token out of the response body for the NEXT queued request; this handler
+// keeps the DOM in sync too, writing the attribute onto the root element so the
+// `tokenValue` fallback stays fresh. It's a pure attribute set — no node is
+// replaced — so a focused <input> + caret survive (the whole point: update a
+// total cell without tearing down the field the user is typing in).
+export function registerReactiveToken() {
+  const actions = window.Turbo?.StreamActions
+  if (!actions || actions["reactive:token"]) return
+  actions["reactive:token"] = function () {
+    const token = this.getAttribute("data-reactive-token-value")
+    const target = this.getAttribute("target")
+    if (!token || !target) return
+    const el = document.getElementById(target)
+    // Stimulus reads the token via the `token` value -> data-reactive-token-value.
+    if (el) el.setAttribute("data-reactive-token-value", token)
+  }
+}
+
+export function registerReactiveActions() {
+  registerReactiveVisit()
+  registerReactiveToken()
+}
+
 if (typeof window !== "undefined") {
-  if (window.Turbo) registerReactiveVisit()
-  else document.addEventListener("turbo:load", registerReactiveVisit, { once: true })
+  if (window.Turbo) registerReactiveActions()
+  else document.addEventListener("turbo:load", registerReactiveActions, { once: true })
 }
 
 // --- Registration guard (issue #26 part 2) -------------------------------
@@ -89,6 +122,7 @@ export default class extends Controller {
 
   #tokenCache // freshest token, threaded synchronously across queued requests
   #debounceTimers = new Map() // trigger element -> { timer, flush } pending dispatch
+  #actionPathCache // page-stable action path, resolved once per controller
 
   // Mark that a reactive controller actually connected, so the registration
   // guard above knows the controller was registered (issue #26 part 2).
@@ -172,24 +206,34 @@ export default class extends Controller {
 
   async #perform(action, params) {
     // Auto-collect named field values inside this component so a button-
-    // triggered action still receives sibling inputs (Livewire-style).
-    // Explicit params (data-reactive-params-param) win over collected fields.
-    const fieldParams = this.#collectFields()
-
-    const body = JSON.stringify({
-      token: this.#currentToken,
-      act: action,
-      params: { ...fieldParams, ...this.#parseParams(params) },
-    })
+    // triggered action still receives sibling inputs (Livewire-style), plus any
+    // chosen file inputs in the SAME walk. Explicit params
+    // (data-reactive-params-param) win over collected fields.
+    const { fields, files } = this.#collectFields()
+    const allParams = { ...fields, ...this.#parseParams(params) }
+    const token = this.#currentToken
+
+    // File/multipart path (issue #34): if THIS root has a populated
+    // <input type="file">, the action can't be JSON (JSON.stringify drops the
+    // File). Send FormData instead — token + act + scalar params as fields, each
+    // chosen file appended. The morph/token machinery downstream is identical;
+    // only the request ENCODING differs when files are present.
+    const multipart = files.length > 0
+    const body = multipart
+      ? this.#buildFormData(token, action, allParams, files)
+      : JSON.stringify({ token, act: action, params: allParams })
 
     this.element.setAttribute("aria-busy", "true")
 
     try {
       const headers = {
-        "Content-Type": "application/json",
         Accept: "text/vnd.turbo-stream.html",
         "X-CSRF-Token": this.#csrfToken(),
       }
+      // For JSON we declare the content type; for multipart we must NOT — the
+      // browser sets `multipart/form-data; boundary=…` itself, and overriding it
+      // would strip the boundary and corrupt the body server-side.
+      if (!multipart) headers["Content-Type"] = "application/json"
       // Send the pgbus SSE connection id (if subscribed) so the server can
       // exclude this connection from its own broadcast echo — the actor
       // already gets the action's HTTP response. Harmless without pgbus.
@@ -222,8 +266,10 @@ export default class extends Controller {
       // Capture the new token from the response synchronously, so the next
       // queued request uses it without waiting for the async DOM morph.
       this.#currentToken = this.#extractToken(html) ?? this.#currentToken
-      // Turbo applies the <turbo-stream> ops (replace/morph by id), preserving
-      // focus/scroll/listeners on unchanged nodes.
+      // Turbo applies the <turbo-stream> ops by id. A plain replace is an
+      // outerHTML swap (focus on the replaced subtree is lost); a method="morph"
+      // replace (Response.morph) or an update morphs in place, preserving the
+      // focused input + caret on unchanged nodes — see issue #28.
       window.Turbo.renderStreamMessage(html)
     } catch (error) {
       console.error("[phlex-reactive] action error", error)
@@ -255,12 +301,22 @@ export default class extends Controller {
     return el.closest('[data-controller~="reactive"]') === this.element
   }
 
+  // One walk over THIS root's named controls (not a nested reactive root's),
+  // returning both the scalar `fields` and any chosen `files`. A file input's
+  // `.value` is the useless "C:\fakepath\…" string, never a scalar — so its
+  // chosen files are collected separately (honoring `multiple`) and it adds no
+  // phantom blank value (issue #34). An empty `files` keeps the JSON path.
   #collectFields() {
     const fields = {}
-    // Standard form controls owned by THIS root (not a nested reactive root).
+    const files = []
     this.element.querySelectorAll("input[name], select[name], textarea[name]").forEach((field) => {
       if (!this.#ownsField(field)) return
-      if (field.type === "checkbox") {
+      if (field.type === "file") {
+        // Carry the input's `multiple` flag so #buildFormData keeps the array
+        // shape (params[name][]) even when the user picked exactly one file —
+        // otherwise a [:file] schema would see a lone scalar upload and drop it.
+        for (const file of field.files ?? []) files.push({ name: field.name, file, multiple: field.multiple })
+      } else if (field.type === "checkbox") {
         fields[field.name] = field.checked
       } else if (field.type === "radio") {
         if (field.checked) fields[field.name] = field.value
@@ -288,7 +344,71 @@ export default class extends Controller {
           fields[name] = el.value ?? el.textContent ?? el.innerHTML ?? ""
         }
       })
-    return fields
+    return { fields, files }
+  }
+
+  // Build the multipart body (issue #34). `token`/`act` are flat fields the
+  // endpoint reads from params[:token]/params[:act]; scalar params nest under
+  // params[<key>] (Rails parses the bracket into params[:params]); each file is
+  // appended under params[<name>] (single) — a second file with the same name
+  // (a `multiple` picker, several inputs sharing a name) is sent as
+  // params[<name>][] so Rails coerces it to an array for a [:file] schema.
+  #buildFormData(token, action, params, files) {
+    const fd = new FormData()
+    fd.append("token", token)
+    fd.append("act", action)
+    for (const [key, value] of Object.entries(params)) {
+      this.#appendField(fd, `params[${key}]`, value)
+    }
+    const multiNames = this.#multiFileNames(files)
+    for (const { name, file, multiple } of files) {
+      // params[name][] when the input is `multiple` (array shape even for one
+      // file) OR the name repeats across inputs; otherwise a lone scalar file.
+      const asArray = multiple || multiNames.has(name)
+      const key = asArray ? `params[${name}][]` : `params[${name}]`
+      fd.append(key, file, file.name)
+    }
+    return fd
+  }
+
+  // Append a param leaf to FormData under its bracketed key. FormData carries
+  // only strings, so a NON-scalar param (a nested object or an array) is
+  // bracket-EXPANDED into params[key][sub] / params[key][index][...] fields —
+  // the SAME Rails-form shape the server's expand_bracket_keys / array_values
+  // already parse, so a JSON body and a multipart body coerce identically
+  // (issue #39). Previously a non-scalar was JSON.stringify'd into one
+  // params[key]='<json>' field, which the server received as an un-decodable
+  // String leaf and DROPPED (nested hash -> {}, array -> key removed).
+  //
+  // Arrays use NUMERIC indices (params[key][0], params[key][1]) — required for
+  // an array-of-hash so each element's sub-keys stay grouped and the server's
+  // index-hash sort rebuilds order; params[key][] would collapse them. A scalar
+  // (string/number/boolean) is one string field, mirroring the JSON wire shape
+  // (the server's :boolean/:integer casts read "true"/"42"). null/undefined is
+  // an empty field. An EMPTY array/object emits NOTHING — FormData can't carry
+  // []/{}, so the key is omitted and the action's keyword default applies (this
+  // differs from the JSON path, where an explicit [] coerces to an empty array).
+  #appendField(fd, key, value) {
+    if (value == null) {
+      fd.append(key, "")
+    } else if (Array.isArray(value)) {
+      value.forEach((element, index) => this.#appendField(fd, `${key}[${index}]`, element))
+    } else if (typeof value === "object") {
+      for (const [subKey, subValue] of Object.entries(value)) {
+        this.#appendField(fd, `${key}[${subKey}]`, subValue)
+      }
+    } else {
+      fd.append(key, String(value))
+    }
+  }
+
+  // Names that appear more than once across the chosen files (a `multiple`
+  // picker, or several file inputs sharing a name) — those go to params[name][]
+  // so the server sees an array; a lone file stays params[name].
+  #multiFileNames(files) {
+    const counts = new Map()
+    for (const { name } of files) counts.set(name, (counts.get(name) ?? 0) + 1)
+    return new Set([...counts].filter(([, n]) => n > 1).map(([name]) => name))
   }
 
   #parseParams(raw) {
@@ -300,13 +420,21 @@ export default class extends Controller {
     }
   }
 
+  // The action path comes from a <meta> tag that is fixed for the page's life,
+  // so resolve it once per controller and cache it — avoids a querySelector on
+  // every dispatch (this runs on the request hot path, once per click/keystroke
+  // round trip). Cached on the instance, so a fresh connect() (after a Turbo
+  // navigation swaps the element) re-reads it.
   #actionPath() {
-    return (
+    return (this.#actionPathCache ??=
       document.querySelector('meta[name="phlex-reactive-action-path"]')?.content ||
-      "/reactive/actions"
-    )
+      "/reactive/actions")
   }
 
+  // CSRF token and connection id are read LIVE (not cached) on purpose: Rails
+  // can rotate the CSRF token, and the pgbus connection id changes on an SSE
+  // reconnect — caching either would send a stale value. A single querySelector
+  // per request is cheap next to the round trip itself.
   #csrfToken() {
     return document.querySelector('meta[name="csrf-token"]')?.content ?? ""
   }

data/lib/generators/phlex/reactive/install/install_generator.rb

@@ -29,8 +29,8 @@ module Phlex
           index = stimulus_index_path
 
           unless index
-            say_status :skip, "no Stimulus controllers entrypoint found — register manually:\n" \
-                              "    #{IMPORT_LINE}\n    #{REGISTER_LINE}", :yellow
+            say_status :skip, "no Stimulus controllers entrypoint found — register manually:\n    " \
+                              "#{IMPORT_LINE}\n    #{REGISTER_LINE}", :yellow
             return
           end
 
@@ -44,9 +44,9 @@ module Phlex
           end
 
           # Fallback: if the standard import line wasn't found, append both lines.
-          unless File.read(index).include?(REGISTER_LINE)
-            append_to_file index, "\n#{IMPORT_LINE}\n#{REGISTER_LINE}\n"
-          end
+          return if File.read(index).include?(REGISTER_LINE)
+
+          append_to_file index, "\n#{IMPORT_LINE}\n#{REGISTER_LINE}\n"
         end
 
         def show_post_install
@@ -69,7 +69,7 @@ module Phlex
           %w[
             app/javascript/controllers/index.js
             app/javascript/controllers/application.js
-          ].map { |p| File.join(destination_root, p) }.find { |p| File.exist?(p) }
+          ].map { File.join(destination_root, it) }.find { File.exist?(it) }
         end
 
         def relative(path)