phlex-reactive 0.1.0

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

@@ -0,0 +1,149 @@
+import { Controller } from "@hotwired/stimulus"
+
+// The ONE generic controller behind every reactive Phlex component. It
+// 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.
+//
+// Wire format (client -> server), POST <action path>, turbo-stream Accept:
+//   { token: "<signed identity>", act: "<action>", params: {...} }
+// (`act`, not `action`: `action` is a reserved Rails routing param.)
+// The token is a MessageVerifier-signed { component, gid } — NO state is sent.
+// 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
+// stream transport (pgbus SSE / Action Cable) via the Streamable
+// .broadcast_* methods — so a click and a background broadcast converge on
+// one re-render unit.
+//
+// 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.
+export default class extends Controller {
+  static values = {
+    token: String, // signed identity token (component + record gid/state)
+  }
+
+  #tokenCache // freshest token, threaded synchronously across queued requests
+
+  // Serialize requests per component. Each round trip rewrites the signed
+  // token in the DOM (state lives in the token, not the client). If events
+  // fire faster than round trips complete, concurrent requests would all read
+  // the SAME stale token and clobber each other (last-write-wins). Chaining on
+  // a per-controller promise makes each dispatch wait for the previous one, so
+  // it always uses the freshest token.
+  dispatch(event) {
+    this.queue = (this.queue ?? Promise.resolve()).then(() => this.#perform(event))
+    return this.queue
+  }
+
+  async #perform(event) {
+    const { action, params } = event.params
+    if (!action) return
+
+    // Stop native behavior (button submit / form navigation): the reactive
+    // round trip replaces it.
+    event.preventDefault()
+
+    // 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) },
+    })
+
+    this.element.setAttribute("aria-busy", "true")
+
+    try {
+      const response = await fetch(this.#actionPath(), {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "text/vnd.turbo-stream.html",
+          "X-CSRF-Token": this.#csrfToken(),
+        },
+        body,
+        credentials: "same-origin",
+      })
+
+      if (response.redirected) {
+        console.error("[phlex-reactive] action was redirected (auth/CSRF?) — no update applied")
+        return
+      }
+      if (!response.ok) {
+        console.error(`[phlex-reactive] action failed: HTTP ${response.status}`, await response.text())
+        return
+      }
+
+      const contentType = response.headers.get("Content-Type") || ""
+      if (!contentType.includes("turbo-stream")) {
+        console.error(`[phlex-reactive] expected a turbo-stream, got "${contentType}" — no update applied`)
+        return
+      }
+
+      const html = await response.text()
+      // 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.
+      window.Turbo.renderStreamMessage(html)
+    } catch (error) {
+      console.error("[phlex-reactive] action error", error)
+    } finally {
+      this.element.removeAttribute("aria-busy")
+    }
+  }
+
+  get #currentToken() {
+    return this.#tokenCache ?? this.tokenValue
+  }
+
+  set #currentToken(value) {
+    this.#tokenCache = value
+  }
+
+  #extractToken(html) {
+    const match = html.match(/data-reactive-token-value="([^"]+)"/)
+    return match?.[1]
+  }
+
+  #collectFields() {
+    const fields = {}
+    this.element.querySelectorAll("input[name], select[name], textarea[name]").forEach((field) => {
+      if (field.type === "checkbox") {
+        fields[field.name] = field.checked
+      } else if (field.type === "radio") {
+        if (field.checked) fields[field.name] = field.value
+      } else {
+        fields[field.name] = field.value
+      }
+    })
+    return fields
+  }
+
+  #parseParams(raw) {
+    if (!raw) return {}
+    try {
+      return typeof raw === "string" ? JSON.parse(raw) : raw
+    } catch {
+      return {}
+    }
+  }
+
+  #actionPath() {
+    return (
+      document.querySelector('meta[name="phlex-reactive-action-path"]')?.content ||
+      "/reactive/actions"
+    )
+  }
+
+  #csrfToken() {
+    return document.querySelector('meta[name="csrf-token"]')?.content ?? ""
+  }
+}

data/lib/phlex/reactive/component.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # 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.
+    #
+    # Include alongside Phlex::Reactive::Streamable (which provides #id and the
+    # re-render machinery).
+    #
+    # === Security model (the decisive design choice) ===
+    # We do NOT ship component STATE to the browser (no snapshot). The DOM
+    # carries a signed IDENTITY:
+    #
+    #   * Record-backed (the common case): reactive_record :todo signs the
+    #     record's GlobalID. The server re-finds it via GlobalID — the client
+    #     can neither forge the component class nor swap the record. State =
+    #     the database.
+    #   * State-backed (record-less, e.g. a counter): reactive_state :count
+    #     signs the listed instance variables. Use only when there is genuinely
+    #     no record to re-find.
+    #
+    # Actions are DEFAULT-DENY: only methods declared with `action :name` may be
+    # invoked. The signature proves the token is ours, NOT that this user may
+    # act — your action must still authorize the record. Action params pass
+    # through a declared schema; nothing else reaches the method.
+    #
+    # Usage (record-backed):
+    #   class Todos::Item < ApplicationComponent
+    #     include Phlex::Reactive::Streamable
+    #     include Phlex::Reactive::Component
+    #
+    #     reactive_record :todo
+    #     action :toggle
+    #     action :rename, params: { title: :string }
+    #
+    #     def initialize(todo:) = @todo = todo
+    #     def id = dom_id(@todo)
+    #
+    #     def toggle  = (authorize!(@todo, :update?); @todo.toggle!(:done))
+    #     def rename(title:) = (authorize!(@todo, :update?); @todo.update!(title:))
+    #
+    #     def view_template
+    #       li(id:, **reactive_attrs) do
+    #         button(**on(:toggle)) { @todo.done? ? "✓" : "○" }
+    #         span { @todo.title }
+    #       end
+    #     end
+    #   end
+    module Component
+      extend ActiveSupport::Concern
+
+      # A declared, client-invokable action and its param schema.
+      Action = Data.define(:name, :params)
+
+      class_methods do
+        # Declare the ActiveRecord (GlobalID-able) record this component is
+        # rebuilt from. The signed token carries its GlobalID; the server
+        # re-finds it on each action. State lives in the DB.
+        def reactive_record(name)
+          @reactive_record_key = name.to_sym
+        end
+
+        def reactive_record_key
+          return @reactive_record_key if defined?(@reactive_record_key)
+
+          superclass.respond_to?(:reactive_record_key) ? superclass.reactive_record_key : nil
+        end
+
+        # Opt into signed STATE for record-less components only.
+        #   reactive_state :count, :open
+        def reactive_state(*names)
+          reactive_state_keys.concat(names.map(&:to_sym))
+        end
+
+        def reactive_state_keys
+          @reactive_state_keys ||= (superclass.respond_to?(:reactive_state_keys) ? superclass.reactive_state_keys.dup : [])
+        end
+
+        # Declare a client-invokable action with an optional param schema.
+        #   action :increment
+        #   action :rename, params: { title: :string }
+        # Param types: :string (default), :integer, :float, :boolean.
+        def action(name, params: {})
+          reactive_actions[name.to_sym] = Action.new(name: name.to_sym, params: params)
+        end
+
+        def reactive_actions
+          @reactive_actions ||= (superclass.respond_to?(:reactive_actions) ? superclass.reactive_actions.dup : {})
+        end
+
+        def reactive_action(name)
+          reactive_actions[name.to_sym]
+        end
+
+        def reactive_action?(name)
+          reactive_actions.key?(name.to_sym)
+        end
+
+        # Rebuild a component instance from a verified identity payload. Called
+        # by the action endpoint after the token signature is verified.
+        def from_identity(payload)
+          if reactive_record_key
+            record = GlobalID::Locator.locate(payload.fetch("gid"))
+            raise(ActiveRecord::RecordNotFound, "reactive record missing") unless record
+
+            new(reactive_record_key => record)
+          else
+            state = payload.fetch("s", {})
+            kwargs = reactive_state_keys.to_h { |k| [k, state[k.to_s]] }.compact
+            new(**kwargs)
+          end
+        end
+      end
+
+      # Root-element attributes: marks the element reactive and carries the
+      # signed identity token. Spread onto the root:
+      #   div(id:, **reactive_attrs) { ... }
+      def reactive_attrs
+        {
+          data: {
+            controller: "reactive",
+            reactive_token_value: reactive_token
+          }
+        }
+      end
+
+      # Attributes for an element that triggers an action.
+      #   button(**on(:toggle)) { "○" }
+      #   form(**on(:save, event: "submit")) { ... }
+      #
+      # Extra keyword args become explicit params merged over collected form
+      # fields. For click triggers we force type="button" so a bare button
+      # inside a <form> can't submit it and cause a full-page navigation.
+      def on(action_name, event: "click", **params)
+        attrs = {
+          data: {
+            action: "#{event}->reactive#dispatch",
+            reactive_action_param: action_name.to_s,
+            reactive_params_param: params.to_json
+          }
+        }
+        attrs[:type] = "button" if event == "click"
+        attrs
+      end
+
+      private
+
+      # Signed { c, gid } (record-backed) or { c, s } (state-backed).
+      def reactive_token
+        payload =
+          if self.class.reactive_record_key
+            record = instance_variable_get(:"@#{self.class.reactive_record_key}")
+            { "c" => self.class.name, "gid" => record.to_gid.to_s }
+          else
+            state = self.class.reactive_state_keys.to_h do |k|
+              [k.to_s, instance_variable_get(:"@#{k}").as_json]
+            end
+            { "c" => self.class.name, "s" => state }
+          end
+
+        Phlex::Reactive.sign(payload)
+      end
+    end
+  end
+end

data/lib/phlex/reactive/engine.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Phlex
+  module Reactive
+    # Rails engine: mounts the action endpoint, makes the client runtime
+    # available to the asset pipeline, and auto-pins it for importmap apps so
+    # `phlex-reactive` works with zero manual wiring on a standard Rails+Phlex
+    # app. (Configurable — see config/ options on Phlex::Reactive.)
+    class Engine < ::Rails::Engine
+      isolate_namespace Phlex::Reactive
+
+      # Mount POST /reactive/actions -> Phlex::Reactive::ActionsController#create.
+      # Apps can change the path with Phlex::Reactive.action_path before boot.
+      initializer "phlex_reactive.routes" do |app|
+        app.routes.append do
+          post Phlex::Reactive.action_path, to: "phlex/reactive/actions#create", as: :phlex_reactive_action
+        end
+      end
+
+      # Make reactive_controller.js available to Propshaft/Sprockets so it can
+      # be included via the asset pipeline or pinned in importmap.
+      initializer "phlex_reactive.assets" do |app|
+        if app.config.respond_to?(:assets)
+          app.config.assets.paths << root.join("app/javascript").to_s
+          app.config.assets.precompile += %w[phlex/reactive/reactive_controller.js]
+        end
+      end
+
+      # Auto-pin the client controller for importmap apps so it loads without
+      # manual configuration. Apps that don't use importmap include it via the
+      # asset pipeline instead (see README).
+      initializer "phlex_reactive.importmap", after: "importmap" do |app|
+        if defined?(::Importmap::Map) && app.respond_to?(:importmap)
+          app.importmap.pin(
+            "phlex/reactive/reactive_controller",
+            to: "phlex/reactive/reactive_controller.js",
+            preload: true
+          )
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/streamable.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # Streamable gives a self-contained Phlex component the ability to render
+    # ITSELF as a Turbo Stream and to broadcast itself over a stream. Every
+    # streamable component must implement `#id` returning a stable DOM id —
+    # that id is the Turbo Stream target, so you never hand-pick targets.
+    #
+    # Class methods (use in controllers):
+    #   render turbo_stream: Counter.replace(counter)
+    #   render turbo_stream: [Row.append(target: "items", model: @item),
+    #                         Totals.update(@order)]
+    #
+    # Broadcast methods (use in models/jobs/actions):
+    #   Counter.broadcast_replace_to(counter, model: counter)
+    #   Row.broadcast_append_to(@list, target: "items", model: @item)
+    #
+    # Convention: the `id` you set on the root element in `view_template` must
+    # equal what `#id` returns, so replace/broadcast_replace target it.
+    #
+    # NOTE: we intentionally do NOT include Turbo::Streams::ActionHelper — it
+    # pulls in ActionView::Helpers::TagHelper, which overrides Phlex's internal
+    # `tag` method and breaks rendering. We use Turbo::Streams::TagBuilder
+    # directly instead.
+    module Streamable
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # The keyword the positional model maps to in `initialize`. Convention:
+        # demodulized, underscored class name (Invoice -> :invoice,
+        # InvoiceItem -> :invoice_item). Override when it differs.
+        def model_param_name
+          name.demodulize.underscore.to_sym
+        end
+
+        def component_args(model, options)
+          { model_param_name => model }.merge(options)
+        end
+
+        def turbo_stream_builder
+          ::Turbo::Streams::TagBuilder.new(renderer)
+        end
+
+        # Render a component to HTML with a full Rails view context. Routing
+        # through the controller renderer keeps dom_id/url_for/t() working
+        # during a re-render or broadcast.
+        def render_component(component)
+          renderer.render(component, layout: false)
+        end
+
+        def replace(model = nil, **options)
+          component = build(model, options)
+          turbo_stream_builder.replace(component.id, html: render_component(component))
+        end
+
+        def update(model = nil, **options)
+          component = build(model, options)
+          turbo_stream_builder.update(component.id, html: render_component(component))
+        end
+
+        def append(target:, model: nil, **options)
+          component = build(model, options)
+          turbo_stream_builder.append(target, html: render_component(component))
+        end
+
+        def prepend(target:, model: nil, **options)
+          component = build(model, options)
+          turbo_stream_builder.prepend(target, html: render_component(component))
+        end
+
+        def remove(model = nil, **options)
+          component = build(model, options)
+          turbo_stream_builder.remove(component.id)
+        end
+
+        # --- Broadcasts (server -> client over the stream transport) ---
+        # With pgbus installed, Turbo::StreamsChannel broadcasts route over
+        # Postgres SSE instead of Action Cable, transactionally.
+        #
+        # Pass RAW key parts as *streamables (e.g. broadcast_append_to(@list, :items))
+        # or (model, :symbol). Do NOT pass a pre-built stream key string — the
+        # broadcaster builds the key itself, and double-keying can trip the
+        # transport's separator guard.
+
+        def broadcast_replace_to(*streamables, model: nil, **options)
+          component = build(model, options)
+          ::Turbo::StreamsChannel.broadcast_replace_to(
+            *streamables, target: component.id, html: render_component(component)
+          )
+        end
+
+        def broadcast_update_to(*streamables, model: nil, **options)
+          component = build(model, options)
+          ::Turbo::StreamsChannel.broadcast_update_to(
+            *streamables, target: component.id, html: render_component(component)
+          )
+        end
+
+        def broadcast_append_to(*streamables, target:, model: nil, **options)
+          component = build(model, options)
+          ::Turbo::StreamsChannel.broadcast_append_to(
+            *streamables, target:, html: render_component(component)
+          )
+        end
+
+        def broadcast_prepend_to(*streamables, target:, model: nil, **options)
+          component = build(model, options)
+          ::Turbo::StreamsChannel.broadcast_prepend_to(
+            *streamables, target:, html: render_component(component)
+          )
+        end
+
+        def broadcast_remove_to(*streamables, model: nil, **options)
+          component = build(model, options)
+          ::Turbo::StreamsChannel.broadcast_remove_to(*streamables, target: component.id)
+        end
+
+        private
+
+        def build(model, options)
+          new(**(model ? component_args(model, options) : options))
+        end
+
+        def renderer
+          Phlex::Reactive.renderer
+        end
+      end
+
+      # Required: the stable DOM id used as the Turbo Stream target. It MUST
+      # match the id set on the component's root element in `view_template`.
+      def id
+        raise NotImplementedError, "#{self.class} must implement #id for Turbo Stream targeting"
+      end
+
+      # Render THIS already-built instance as a replace stream (used by the
+      # reactive action endpoint after an action mutated state).
+      def to_stream_replace
+        self.class.turbo_stream_builder.replace(id, html: self.class.render_component(self))
+      end
+
+      def to_stream_update
+        self.class.turbo_stream_builder.update(id, html: self.class.render_component(self))
+      end
+    end
+  end
+end

data/lib/phlex/reactive/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    VERSION = "0.1.0"
+  end
+end

data/lib/phlex/reactive.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "globalid"
+
+module Phlex
+  # phlex-reactive: reactive Phlex components for Rails.
+  #
+  # Two cooperating mixins, one client runtime, one endpoint:
+  #
+  #   * Phlex::Reactive::Streamable — gives a component a stable `id` and class
+  #     methods to render itself as a Turbo Stream (`.replace`, `.append`, ...)
+  #     and to broadcast itself (`.broadcast_replace_to`, ...). The server->client
+  #     half (controller responses + background broadcasts).
+  #
+  #   * Phlex::Reactive::Component — declares client-invokable `action`s and
+  #     emits a signed identity token + the wiring the generic `reactive`
+  #     Stimulus controller needs. The client->server half (clicks, form input).
+  #
+  # Both halves converge on ONE re-render unit: the component, targeted by its
+  # `id`. See the README for the mental model and examples.
+  module Reactive
+    class Error < StandardError; end
+
+    # Raised when a signed identity token fails verification (tampered, expired,
+    # or signed with a different key).
+    class InvalidToken < Error; end
+
+    # Purpose string bound into every identity token's signature so a token
+    # minted for phlex-reactive can't be replayed against another verifier use.
+    IDENTITY_PURPOSE = "phlex-reactive/identity"
+
+    class << self
+      # The message verifier used to sign/verify component identity tokens.
+      # Defaults to a purpose-scoped verifier derived from secret_key_base.
+      # Override to use a dedicated key.
+      attr_writer :verifier
+
+      # The controller class used to render components with a full Rails view
+      # context (url helpers, CSRF, i18n) during re-renders and broadcasts.
+      # Defaults to ActionController::Base. Set to your ApplicationController if
+      # components rely on app-level helpers or Current attributes.
+      attr_writer :renderer
+
+      # The controller the reactive ActionsController inherits from, given as a
+      # String (resolved lazily to avoid load-order issues). Defaults to
+      # "ActionController::Base"; set to "ApplicationController" to inherit your
+      # app's auth/CSRF/Current. If you do, ensure the action path isn't
+      # force-redirected for logged-out users when you have public components.
+      attr_writer :base_controller_name
+
+      # Exception classes the action endpoint renders as 403. Append your
+      # authorization library's error (Pundit::NotAuthorizedError,
+      # ActionPolicy::Unauthorized, ...).
+      attr_accessor :authorization_errors
+
+      # The path the action endpoint is mounted at. Default "/reactive/actions".
+      # Set before boot if it collides with an app route. The client runtime
+      # reads it from a <meta name="phlex-reactive-action-path"> tag if present,
+      # falling back to this default.
+      attr_writer :action_path
+
+      def action_path
+        @action_path ||= "/reactive/actions"
+      end
+
+      def verifier
+        @verifier ||= default_verifier
+      end
+
+      def renderer
+        @renderer ||= defined?(::ActionController::Base) ? ::ActionController::Base : nil
+      end
+
+      def base_controller_name
+        @base_controller_name ||= "ActionController::Base"
+      end
+
+      def base_controller
+        base_controller_name.constantize
+      end
+
+      # Returns the verified payload hash, or nil if the token is invalid.
+      def verify(token)
+        verifier.verified(token, purpose: IDENTITY_PURPOSE)
+      end
+
+      # Signs a payload hash into an identity token.
+      def sign(payload)
+        verifier.generate(payload, purpose: IDENTITY_PURPOSE)
+      end
+
+      private
+
+      def default_verifier
+        unless defined?(::Rails) && ::Rails.application
+          raise Error, "Phlex::Reactive.verifier is unset and Rails.application is unavailable; " \
+                       "set Phlex::Reactive.verifier = ActiveSupport::MessageVerifier.new(secret)"
+        end
+
+        ::Rails.application.message_verifier(IDENTITY_PURPOSE)
+      end
+    end
+
+    self.authorization_errors = []
+  end
+end
+
+loader = Zeitwerk::Loader.new
+loader.tag = "phlex-reactive"
+loader.push_dir(File.expand_path("..", __dir__))
+loader.ignore("#{__dir__}/../phlex-reactive.rb")
+loader.do_not_eager_load("#{__dir__}/reactive/engine.rb")
+loader.setup
+
+require "phlex/reactive/engine" if defined?(::Rails::Engine)

data/lib/phlex-reactive.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Allow `require "phlex-reactive"` (gem name) as well as `require "phlex/reactive"`.
+require_relative "phlex/reactive"