phlex-reactive 0.2.9 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6b8ebca93e744e1c2fa3797de877cefc732db8a6cb950d95874c9e00e4dee76
-  data.tar.gz: 119b1373f8ade989791845fc9cf3206f7786eb97f6009faaabfadb1485c82b44
+  metadata.gz: 7232501319d17c45c8907195117f5af59d8b7a4ff9c8d5efb2c0c8248350041e
+  data.tar.gz: 783cd0758a5a51cead67f6f1ea2c8bf23245f62e49a38ea0831328b68b9d0b2c
 SHA512:
-  metadata.gz: ee11a3bf0ac506cdbde2e97e9e47bad436a16050c0b150cd5340bbff9ae846586487bbf6a2bbf028ff20c44faa64f2e57953ddf15adcbafc82491d5e15a9f22f
-  data.tar.gz: 3bd5cd4a362ed18f59da8bf375474aa8beabd5cfdd0d62572d5fce043318c057b01afcf3942acaec30417dc16fd3b3d8d9e6ef9f7ec524f55cf411cc168b8003
+  metadata.gz: a673a7253c99e7b6fccb5228014a47d2918cda2995de79afdb6545adb89a8af8ab99812569455bc7f206c12d7c7efb710ff90d628d767da012ba5deb690e5ab7
+  data.tar.gz: cf68ac7ff60925c73aa0de543665b60d85d8254bada63a40c1786a6a3e7ee3bfceaad123c91daf2f7fec18de8aab04ab61d2ee165b5e0ad241b451ce60c24769

data/CHANGELOG.md

@@ -8,6 +8,47 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`reply.streams` — partial update with a token-only refresh (issue #30).**
+  `reply.streams(Totals.update(@item))` emits **exactly** the streams you pass —
+  no forced full-self replace — so an action can re-render only part of a
+  component (one total cell, one sub-region) while the rest of the DOM, including
+  a sibling `<input>` the user is mid-typing in, is left untouched. The signed
+  identity token still rolls forward: the endpoint appends a tiny
+  `<turbo-stream action="reactive:token">` (new `Streamable#to_stream_token`) that
+  carries the fresh `data-reactive-token-value` and is applied by an inert client
+  action — a pure attribute write on the root, so the focused field + caret
+  survive. This unblocks spreadsheet-like per-field grid editing that the old
+  "every reply re-renders the whole component" behavior made unusable (you had to
+  reach for `data-turbo-permanent`). `Response.streams(self, *)` is the underlying
+  builder; `reply.streams(*)` is the bound form. Backed by a new `render_self:
+  false` + `token_component` path in the endpoint — the legacy full-self-replace
+  refresh (`reply.replace` / `reply.with`) is unchanged.
+
+- **`reply` — the action-reply builder.** Control an action's reply with
+  `reply.replace` / `reply.morph` / `reply.update` / `reply.remove` /
+  `reply.redirect(url)` / `reply.with(*)`, chaining `.flash` / `.stream` /
+  `.also_update` / `.also_replace` as before. `reply` is a subject-bound facade on
+  the component, so the two warts of the old form disappear: no `self` to thread
+  (`reply.morph`, not `Response.morph(self)`) and no constant to qualify — a
+  namespaced component no longer needs a per-file `Response = …` alias, because
+  `reply` is a method resolved on the component, not a lexical constant. It
+  returns the same immutable value object the endpoint reads, so the return-value
+  contract, immutability, and chaining are unchanged. `Phlex::Reactive::Response`
+  remains fully functional but is now an internal detail — `reply` is the
+  documented surface.
+
+- **Morph response — focus-preserving re-render (issue #28).**
+  `reply.morph` (and the opt-in `reply.replace(morph: true)`)
+  re-renders a component in place via Turbo 8's bundled Idiomorph
+  (`<turbo-stream action="replace" method="morph">`) instead of an outerHTML
+  swap. The focused `<input>` and its caret survive the save, making per-field
+  reactive editing — a "spreadsheet" grid where a debounced save fires while the
+  user is still typing/tabbing — actually viable. Backed by the new
+  `Streamable#to_stream_morph` primitive and a `morph:` flag on the
+  `.replace` / `.broadcast_replace_to` class builders and `#also_replace`
+  (live cross-tab updates can morph too). The default everywhere stays the plain
+  replace (no `method="morph"` attribute), so existing components are unchanged.
+  No new dependency — Idiomorph ships with `turbo-rails >= 2.0`.
 - **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

data/README.md

@@ -191,8 +191,8 @@ data-controller="reactive" but the reactive controller never connected …`).
    │                                          rebuild component (record from DB)
    │                                          run the whitelisted action
    │                                          re-render → <turbo-stream replace id>   (default; an action
-   │                                          may return a Response — see "Controlling the action's reply")
-   └──────── Turbo morphs it in ◀───────────────────────────────┘
+   │                                          may return reply.<verb> — see "Controlling the action's reply")
+   └──────── Turbo applies it in ◀──────────────────────────────┘
 
    ...and for OTHER tabs/users:
    model change → Component.broadcast_replace_to(stream) → pgbus SSE → same morph
@@ -292,11 +292,11 @@ The cross-tab chat in ~60 lines of Ruby (and zero JS) is the showcase — see
 | Method | Use |
 |---|---|
 | `#id` (you implement) | Stable DOM id == Turbo Stream target. Must match the root element's `id`. |
-| `.replace(model = nil, **opts)` | `<turbo-stream action=replace target=id>` of a freshly built component |
+| `.replace(model = nil, morph: false, **opts)` | `<turbo-stream action=replace target=id>` of a freshly built component; `morph: true` adds `method="morph"` |
 | `.update` / `.append(target:)` / `.prepend(target:)` / `.remove` | The other Turbo Stream actions |
-| `.broadcast_replace_to(*streamables, model:)` | Broadcast a replace over the stream transport (pgbus SSE / Action Cable) |
+| `.broadcast_replace_to(*streamables, model:, morph: false)` | Broadcast a replace over the stream transport (pgbus SSE / Action Cable); `morph: true` morphs in place |
 | `.broadcast_append_to(*streamables, target:, model:)` / `_update_` / `_prepend_` / `_remove_` | The broadcast variants |
-| `#to_stream_replace` / `#to_stream_update` / `#to_stream_remove` | Stream the *already-built* instance (used internally after an action / by `Response`) |
+| `#to_stream_replace` / `#to_stream_morph` / `#to_stream_update` / `#to_stream_remove` | Stream the *already-built* instance (used internally after an action / by `reply`); `#to_stream_morph` morphs in place |
 
 Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 
@@ -313,6 +313,7 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `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. |
+| `reply.replace` / `.morph` / `.update` / `.remove` / `.redirect(url)` / `.with(*)` | Return from an action to control the reply (flash, remove, redirect, multi-stream). See [Controlling the action's reply](#reply--controlling-the-actions-reply). |
 
 Param types: `:string` (default), `:integer`, `:float`, `:boolean`. Anything not
 in the schema is dropped before reaching your method.
@@ -422,46 +423,68 @@ 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
+### `reply` — controlling the action's reply
 
-By default an action re-renders its component in place. **Return** a
-`Phlex::Reactive::Response` to do more (it governs only the actor's HTTP reply —
-cross-tab updates still use `broadcast_*_to(..., exclude: reactive_connection_id)`).
-Returning anything else keeps the default, so existing actions are unaffected.
+By default an action re-renders its component in place. To do more, **return**
+`reply.<verb>` — a subject-bound builder available in every component. It governs
+only the actor's HTTP reply (cross-tab updates still use
+`broadcast_*_to(..., exclude: reactive_connection_id)`). Returning anything else
+keeps the default, so existing actions are unaffected.
 
-The snippets below alias the constant for brevity (`Response.replace(self)` won't
-resolve to `Phlex::Reactive::Response` inside a namespaced component — fully
-qualify it, or add the alias shown):
+`reply` reads cleanly: the component is the implicit subject (no `self` to
+thread) and there's no constant to qualify (it's a method, so a namespaced
+component needs no alias):
 
 ```ruby
-Response = Phlex::Reactive::Response # or qualify each call below
-
 def rename(title:)
-  return Response.replace(self).flash(:error, @todo.errors.full_messages.to_sentence) unless @todo.update(title:)
-  Response.replace(self)
+  return reply.replace.flash(:error, @todo.errors.full_messages.to_sentence) unless @todo.update(title:)
+  reply.replace
 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
+def approve   = (@row.approve!; reply.remove)          # drop the element
+def publish   = (@article.publish!; reply.redirect(article_url(@article)))  # slug changed → Turbo.visit
+def add(item:) = reply.replace.stream(Totals.update(@order))               # multi-stream
+
+# Per-field reactive editing (a "spreadsheet" grid): a debounced save fires
+# while the user is still typing/tabbing. Morph in place so the focused <input>
+# and its in-progress value survive the re-render (issue #28). Note the action is
+# named `update`, yet `reply.morph` is unambiguous — the verb is on `reply`:
+def update(name:) = (@row.update!(name:); reply.morph)
 
 # 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))
+def rename(value:) = (@account.update!(name: value); reply.replace.also_update("page_heading", html: @account.name))
+
+# Update ONLY part of the component (issue #30): re-stream just the total cell,
+# NOT the whole row. reply.streams emits exactly your streams plus a tiny
+# token-only refresh — no full-self replace — so a sibling <input> the user is
+# mid-typing in is never torn down. The signed token still rolls forward.
+def update(quantity:, price:) = (@item.update!(quantity:, price:); reply.streams(Totals.update(@item)))
 ```
 
 | Builder | Reply |
 |---|---|
-| `Response.replace(self)` / `.update(self)` | re-render in place (explicit default) |
+| `reply.replace` / `reply.update` | re-render in place (default; `replace` is an outerHTML swap, `update` morphs inner HTML) |
+| `reply.morph` / `reply.replace(morph: true)` | re-render in place via Idiomorph (`method="morph"`) — preserves the focused `<input>` + caret; for per-field reactive editing (issue #28) |
 | `.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` |
+| `.also_replace(component, morph: false)` | also re-render another Streamable component, targeting its own `#id`; `morph: true` morphs it in place |
 | `.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 |
+| `reply.remove` | remove the element (backed by `Streamable#to_stream_remove`) |
+| `reply.redirect(url)` | client-side `Turbo.visit` (pass a `*_url`); rides a `reactive:visit` turbo-stream, not an HTTP 3xx |
+| `reply.streams(*streams)` | **partial update** — emit exactly these streams (no full-self replace) + a tiny token-only refresh, so live inputs survive; for per-field grid editing (issue #30) |
+| `reply.with(*streams)` / `#stream(*more)` | multi-stream (self re-render still injected for the token) |
 
 `.flash`/`.stream`/`.also_*` are additive on a self-replace, so the component's
-signed token always refreshes.
-
+signed token always refreshes. **`reply.streams`** is the exception that proves
+the rule: it deliberately skips the full-self replace (so your hand-built streams
+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.
+
+> **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
+> the preferred surface; treat `Response` as an internal detail.
+> **`html:`/`content` escaping.** A plain string is **HTML-escaped** by Turbo, so
 > **`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)`) —

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
@@ -94,6 +107,17 @@ module Phlex
         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? { |s| s.include?("data-reactive-token-value") && s.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

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

@@ -4,7 +4,8 @@ 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: {...} }
@@ -31,9 +32,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) -------------------------------
@@ -222,8 +252,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)

data/lib/phlex/reactive/component.rb

@@ -5,8 +5,10 @@ module Phlex
     # Component turns a self-contained Phlex component into a Livewire-style
     # reactive unit: declare actions in Ruby, and the generic `reactive`
     # Stimulus controller wires clicks/inputs to an HTTP round trip that
-    # re-renders the component and morphs it back into the DOM. No per-feature
-    # Stimulus controllers, no hand-picked Turbo targets.
+    # re-renders the component and applies it back into the DOM (a plain replace
+    # by default; return Response.morph(self) to morph in place and keep the
+    # focused input — issue #28). No per-feature Stimulus controllers, no
+    # hand-picked Turbo targets.
     #
     # Include alongside Phlex::Reactive::Streamable (which provides #id and the
     # re-render machinery).
@@ -167,6 +169,22 @@ module Phlex
         Phlex::Reactive.current_connection_id
       end
 
+      # Subject-bound reply builder — the preferred way to control an action's
+      # reply. `reply.replace.flash(:error, msg)` reads cleaner than
+      # `Phlex::Reactive::Response.replace(self).flash(:error, msg)`: the
+      # component is the implicit subject (no `self` to thread) and there's no
+      # constant to qualify (reply is a method, so a namespaced component needs
+      # no `Response = …` alias). It returns the same immutable Response the
+      # endpoint reads, so chaining and the legacy return-value contract are
+      # unchanged. See Phlex::Reactive::Reply.
+      #
+      #   def archive       = reply.remove
+      #   def go_home       = reply.redirect("/todos")
+      #   def update(name:) = (@account.update!(name:); reply.morph)
+      def reply
+        Phlex::Reactive::Reply.new(self)
+      end
+
       # Root-element attributes: marks the element reactive and carries the
       # signed identity token. Spread onto the root:
       #   div(id:, **reactive_attrs) { ... }

data/lib/phlex/reactive/reply.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # A component-bound facade over Response — the surface an action body uses to
+    # control its reply. Component#reply returns one, so an action writes
+    #
+    #   reply.replace.flash(:error, msg)
+    #
+    # instead of
+    #
+    #   Phlex::Reactive::Response.replace(self).flash(:error, msg)
+    #
+    # Two warts disappear: there is no constant to qualify (reply is a method,
+    # resolved on the component — so a namespaced component needs no
+    # `Response = …` alias) and no `self` to thread (the component is bound).
+    #
+    # Reply is NOT a Response and does NOT subclass one: each verb forwards to
+    # the Response class method, supplying the bound component as the subject, and
+    # returns the real, frozen Response value the endpoint already honors. So
+    # immutability, chaining (.flash/.stream/.also_update/.also_replace), and
+    # render_self? are inherited untouched — and there is no "verb after a chained
+    # Response" asymmetry, because the chain is plain Response all the way down.
+    #
+    # Response remains the public value object (it's what the endpoint reads); it
+    # is simply an internal detail you rarely name directly now.
+    class Reply
+      def initialize(component)
+        @component = component
+      end
+
+      # Self-targeting builders — the bound component is supplied implicitly.
+
+      # Re-render in place. `morph: true` morphs the subtree (preserves the
+      # focused input + caret) instead of an outerHTML swap — see #morph.
+      def replace(morph: false)
+        Response.replace(@component, morph:)
+      end
+
+      # Re-render in place via Idiomorph (method="morph") — keeps focus + caret.
+      def morph
+        Response.morph(@component)
+      end
+
+      # Morph only inner HTML (preserves the root element + its token attr).
+      def update
+        Response.update(@component)
+      end
+
+      # Remove the component's element from the DOM (render_self false).
+      def remove
+        Response.remove(@component)
+      end
+
+      # Subject-free builders — pass straight through so they read naturally.
+
+      # Client-side full navigation (Turbo.visit). Pass a *_url.
+      def redirect(url)
+        Response.redirect(url)
+      end
+
+      # Escape hatch / multi-stream root: zero or more raw turbo-stream strings.
+      def with(*strings)
+        Response.with(*strings)
+      end
+
+      # Self-targeting again: emit exactly these streams with a TOKEN-ONLY refresh
+      # (issue #30) — partial/per-field update, NO full-self replace, so the
+      # component's live inputs survive. The bound component supplies the token.
+      def streams(*strings)
+        Response.streams(@component, *strings)
+      end
+    end
+  end
+end

data/lib/phlex/reactive/response.rb

@@ -17,11 +17,23 @@ module Phlex
     #   Response.redirect(article_url(@article))        # slug changed -> Turbo.visit the new URL
     #   Response.replace(self).stream(Totals.update(@order))  # multi-stream
     class Response
-      attr_reader :streams, :redirect_url
+      attr_reader :streams, :redirect_url, :token_component
 
       class << self
         # Re-render the component in place (explicit form of today's default).
-        def replace(component) = new(streams: [component.to_stream_replace])
+        # `morph: true` morphs the subtree (preserves the focused input + caret)
+        # instead of an outerHTML swap — see .morph (issue #28).
+        def replace(component, morph: false)
+          new(streams: [morph ? component.to_stream_morph : component.to_stream_replace])
+        end
+
+        # Re-render the component in place via Idiomorph (issue #28). Emits
+        # `<turbo-stream action="replace" method="morph">`, so Turbo 8 morphs the
+        # subtree — the focused <input> + caret survive the save. Use this for
+        # per-field reactive editing (a "spreadsheet" grid where a debounced save
+        # fires while the user is still typing/tabbing). The morphed root still
+        # carries the fresh signed token, so the next action verifies.
+        def morph(component) = new(streams: [component.to_stream_morph])
 
         # Morph only inner HTML (preserves the root element + its token attr).
         def update(component) = new(streams: [component.to_stream_update])
@@ -39,6 +51,22 @@ module Phlex
         # Escape hatch / multi-stream root: zero or more raw turbo-stream strings.
         def with(*strings) = new(streams: strings.flatten)
 
+        # Partial / per-field update with a TOKEN-ONLY refresh (issue #30). Emits
+        # EXACTLY the given streams — no forced full-self replace — but binds
+        # `component` so the endpoint appends its tiny `to_stream_token` stream.
+        # So the signed token rolls forward (the next action verifies) while the
+        # component's own live inputs are never torn down: ideal for a
+        # spreadsheet-like grid where a debounced save re-streams only a total
+        # cell and the user is still typing in a sibling field.
+        #
+        #   Response.streams(self, Totals.update(@invoice))   # update only the totals
+        #
+        # render_self is false (we do NOT inject the full replace); the token is
+        # refreshed by the bound component's token stream instead.
+        def streams(component, *strings)
+          new(streams: strings.flatten, render_self: false, token_component: component)
+        end
+
         # Build a flash turbo-stream that appends `content` into a host-app
         # container. `content` is a Phlex component instance (rendered through
         # the configured renderer so t()/url_for work) or a ready HTML string —
@@ -73,10 +101,16 @@ module Phlex
       # GUARANTEES the component's own replace is present so its
       # data-reactive-token-value refreshes (the client extracts the next token
       # from the response HTML). remove/redirect set it false (nothing stays).
-      def initialize(streams: [], redirect_url: nil, render_self: true)
+      #
+      # token_component: set by .streams (issue #30) — a partial update that opts
+      # OUT of the full-self replace but still needs the token refreshed. The
+      # endpoint appends this component's tiny to_stream_token instead, so the
+      # token rolls forward without re-rendering (and clobbering) the children.
+      def initialize(streams: [], redirect_url: nil, render_self: true, token_component: nil)
         @streams = streams.freeze
         @redirect_url = redirect_url
         @render_self = render_self
+        @token_component = token_component
         freeze
       end
 
@@ -86,7 +120,8 @@ module Phlex
         self.class.new(
           streams: @streams + more.flatten,
           redirect_url: @redirect_url,
-          render_self: @render_self
+          render_self: @render_self,
+          token_component: @token_component
         )
       end
 
@@ -113,12 +148,19 @@ module Phlex
       # 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)
+      # `morph: true` morphs the companion in place (issue #28) — use it when the
+      # companion also holds focusable inputs that must survive the re-render.
+      def also_replace(component, morph: false)
+        stream(morph ? component.to_stream_morph : component.to_stream_replace)
       end
 
       def redirect? = !@redirect_url.nil?
       def render_self? = @render_self
+
+      # True when a partial update (.streams) opted out of the full-self replace
+      # but still needs the token rolled forward — the endpoint appends the bound
+      # component's tiny token-only stream (issue #30).
+      def refresh_token? = !@token_component.nil?
     end
   end
 end

data/lib/phlex/reactive/streamable.rb

@@ -64,9 +64,13 @@ module Phlex
           renderer.render(component, layout: false)
         end
 
-        def replace(model = nil, **options)
+        # `morph: true` emits `<turbo-stream action="replace" method="morph">` so
+        # Turbo 8's bundled Idiomorph morphs the subtree in place — preserving a
+        # focused <input> + caret — instead of an outerHTML swap (issue #28).
+        # Default (morph: false) is the unchanged plain replace.
+        def replace(model = nil, morph: false, **options)
           component = build(model, options)
-          turbo_stream_builder.replace(component.id, html: render_component(component))
+          turbo_stream_builder.replace(component.id, html: render_component(component), **morph_method(morph))
         end
 
         def update(model = nil, **options)
@@ -103,11 +107,15 @@ module Phlex
         # connection id — pass it to suppress the actor's own echo (the actor
         # already got the action's HTTP response). With Action Cable these are
         # ignored; with pgbus they reach the dispatcher. See docs/broadcasting.
-        def broadcast_replace_to(*streamables, model: nil, exclude: nil, visible_to: nil, **options)
+        # `morph: true` makes the live cross-tab update morph in place (issue #28),
+        # so a peer tab keeps its focus/caret on the morphed row. The broadcast
+        # path takes EXTRA <turbo-stream> attributes via `attributes:` (not the
+        # TagBuilder's `method:` kwarg), so the morph flag rides there.
+        def broadcast_replace_to(*streamables, model: nil, exclude: nil, visible_to: nil, morph: false, **options)
           component = build(model, options)
           ::Turbo::StreamsChannel.broadcast_replace_to(
             *streamables, target: component.id, html: render_component(component),
-            **broadcast_transport_opts(exclude:, visible_to:)
+            **morph_attributes(morph), **broadcast_transport_opts(exclude:, visible_to:)
           )
         end
 
@@ -149,6 +157,20 @@ module Phlex
           new(**(model ? component_args(model, options) : options))
         end
 
+        # The TagBuilder (the .replace class builder + to_stream_morph) takes
+        # `method: :morph` to emit the `method="morph"` attribute. Pass it ONLY
+        # when morphing, so the default call produces today's plain replace.
+        def morph_method(morph)
+          morph ? {method: :morph} : {}
+        end
+
+        # The BROADCAST path renders extra <turbo-stream> attributes through
+        # `attributes:` (it has no `method:` kwarg — that would fall into the
+        # render args and be dropped). Same wire result: method="morph".
+        def morph_attributes(morph)
+          morph ? {attributes: {method: "morph"}} : {}
+        end
+
         # Only include transport opts that were actually given, so on Action
         # Cable (which doesn't accept them) the common no-opts call is unchanged.
         def broadcast_transport_opts(exclude:, visible_to:)
@@ -184,10 +206,38 @@ module Phlex
         self.class.turbo_stream_builder.replace(id, html: self.class.render_component(self))
       end
 
+      # Render THIS instance as a MORPHING replace (issue #28):
+      # `<turbo-stream action="replace" method="morph">`. Turbo 8's bundled
+      # Idiomorph morphs the subtree in place — preserving the focused <input> +
+      # caret across the re-render — while still carrying the root's fresh
+      # data-reactive-token-value (so the signed token refreshes). Used by
+      # Response.morph / Response.replace(self, morph: true).
+      def to_stream_morph
+        self.class.turbo_stream_builder.replace(id, html: self.class.render_component(self), method: :morph)
+      end
+
       def to_stream_update
         self.class.turbo_stream_builder.update(id, html: self.class.render_component(self))
       end
 
+      # Render a TOKEN-ONLY refresh stream (issue #30): a tiny
+      # `<turbo-stream action="reactive:token">` carrying the component's fresh
+      # signed token, with NO rendered body. It lets an action update only PART
+      # of a component (its own hand-built streams) while still rolling the
+      # signed identity token forward — the client reads the next token from this
+      # attribute (#extractToken) and an inert client action writes it onto the
+      # root (a pure attribute set, so a focused <input> + caret survive). Unlike
+      # to_stream_replace, it does NOT re-render the children, so a live input
+      # the user is typing into is never torn down. Used by Response.streams.
+      #
+      # The component carries its token via Component#reactive_token; a Streamable
+      # that isn't a Component (no token) simply has nothing to refresh — guarded
+      # by respond_to? so the primitive stays usable on a bare Streamable.
+      def to_stream_token
+        token = respond_to?(:reactive_token) ? reactive_token : nil
+        %(<turbo-stream action="reactive:token" target="#{ERB::Util.html_escape(id)}" data-reactive-token-value="#{ERB::Util.html_escape(token)}"></turbo-stream>)
+      end
+
       # Render THIS instance as a remove stream. The component already knows its
       # own #id, so no record/class reconstruction is needed (works for record-
       # and state-backed components alike). Used by Response.remove.

data/lib/phlex/reactive/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.3.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -129,6 +129,7 @@ files:
 - lib/phlex/reactive.rb
 - lib/phlex/reactive/component.rb
 - lib/phlex/reactive/engine.rb
+- lib/phlex/reactive/reply.rb
 - lib/phlex/reactive/response.rb
 - lib/phlex/reactive/streamable.rb
 - lib/phlex/reactive/version.rb