phlex-reactive 0.9.1 → 0.9.2

data/lib/phlex/reactive/component/dsl.rb

@@ -20,6 +20,14 @@ module Phlex
       module DSL
         extend ActiveSupport::Concern
 
+        # A cross-root mirror target must be a single ID selector (issue #159)
+        # — "#" + a CSS identifier, nothing else. Not a class, not an attribute
+        # selector, not `*`, not a compound/descendant/list selector: a
+        # compromised reducer must not be able to scribble text across the
+        # page. The client interpreter enforces the SAME shape (two-sided
+        # default-deny, mirroring the attr allowlist posture).
+        MIRROR_ID_SELECTOR = /\A#[A-Za-z_][\w-]*\z/
+
         class_methods do
           # Declare the ActiveRecord (GlobalID-able) record this component is
           # rebuilt from. The signed token carries its GlobalID; the server
@@ -165,15 +173,45 @@ module Phlex
           #
           #   import { setComputeReducer } from "phlex/reactive/compute"
           #   setComputeReducer("payment_split", ({ allowance, cash, leasing, total }, { changed }) => ({ … }))
-          def reactive_compute(name, inputs: nil, outputs: nil, reducer: nil)
-            return reactive_compute_def(name) if inputs.nil? && outputs.nil?
+          #
+          # `mirror:` (issue #159) declares CROSS-ROOT text mirrors — the opt-in
+          # escape from root isolation (issue #15) for a derived value shown in a
+          # recap OUTSIDE the computing root (another tab pane, a sticky footer):
+          #
+          #   reactive_compute :split,
+          #     inputs:  %i[a b total],
+          #     outputs: %i[a b],
+          #     mirror:  { sum_a: "#sum_a", sum_total: ["#sum_total", "#footer-total"] }
+          #
+          # Each key is a compute name — a declared input (its identity mirror
+          # also paints cross-root) or a reducer-result key (an extra text-only
+          # output). Each value is one or more DOCUMENT-WIDE id selectors the
+          # value is painted into via textContent (XSS-safe, change-guarded,
+          # never innerHTML, never a field write). Id selectors ONLY — a class/
+          # attribute/compound selector raises here (declared, not arbitrary;
+          # the client interpreter re-checks the same shape).
+          def reactive_compute(name, inputs: nil, outputs: nil, reducer: nil, mirror: nil)
+            if inputs.nil? && outputs.nil?
+              # The bare form is the GETTER — a mirror: passed here would be
+              # silently dropped, so refuse it LOUDLY (declare-time validation,
+              # same posture as normalize_compute_mirror's selector check).
+              unless mirror.nil?
+                raise ArgumentError,
+                  "#{self}: reactive_compute(#{name.inspect}, mirror: ...) without inputs:/outputs: " \
+                  "is the getter form — the mirror would be silently dropped. Declare the mirror " \
+                  "alongside inputs:/outputs:."
+              end
+
+              return reactive_compute_def(name)
+            end
 
             input_names, input_types = normalize_compute_inputs(inputs)
             Registry.write_entry(
               self, :computes, name.to_sym,
               ComputeDefinition.new(
                 name: name.to_sym, inputs: input_names, input_types:,
-                outputs: Array(outputs).map(&:to_sym), reducer: (reducer || name).to_s
+                outputs: Array(outputs).map(&:to_sym), reducer: (reducer || name).to_s,
+                mirror: normalize_compute_mirror(mirror)
               )
             )
           end
@@ -210,6 +248,27 @@ module Phlex
             end
           end
 
+          # Normalize `mirror:` to { name => [id selectors] } (nil passes
+          # through — no mirror declared). Each value may be one selector or a
+          # list; every selector is validated LOUDLY at declare time against
+          # MIRROR_ID_SELECTOR (id selectors only).
+          def normalize_compute_mirror(mirror)
+            return nil if mirror.nil?
+
+            mirror.to_h do |name, selectors|
+              list = Array(selectors).map(&:to_s)
+              list.each do
+                next if it.match?(MIRROR_ID_SELECTOR)
+
+                raise ArgumentError,
+                  "#{self}: mirror target #{it.inspect} for #{name.inspect} must be a single " \
+                  "id selector (\"#some-id\") — cross-root text mirrors are declared, allowlisted " \
+                  "targets, never arbitrary selectors"
+              end
+              [name.to_sym, list.freeze]
+            end.freeze
+          end
+
           # Rebuild a component instance from a verified identity payload. Called
           # by the action endpoint after the token signature is verified.
           #

data/lib/phlex/reactive/component/helpers.rb

@@ -422,13 +422,23 @@ module Phlex
           definition = self.class.reactive_compute_def(name)
           raise Error, "#{self.class} has no reactive_compute #{name.inspect}" unless definition
 
-          {
-            data: {
-              reactive_compute_reducer_param: definition.reducer,
-              reactive_compute_inputs_param: compute_inputs_param(definition),
-              reactive_compute_outputs_param: definition.outputs.map(&:to_s).to_json
-            }
+          data = {
+            reactive_compute_reducer_param: definition.reducer,
+            reactive_compute_inputs_param: compute_inputs_param(definition),
+            reactive_compute_outputs_param: definition.outputs.map(&:to_s).to_json
           }
+          # Declared cross-root text mirrors (issue #159) ride as a JSON object of
+          # name → [id selectors]; omitted entirely when undeclared so the shipped
+          # wire stays byte-identical.
+          data[:reactive_compute_mirror_param] = compute_mirror_param(definition) if definition.mirror
+
+          { data: }
+        end
+
+        # The mirror param wire (issue #159): { "sum_a" => ["#sum_a"], … } — the
+        # values are ALWAYS arrays so the client parses one uniform shape.
+        def compute_mirror_param(definition)
+          definition.mirror.transform_keys(&:to_s).to_json
         end
 
         # The inputs param wire (issue #104). Untyped (array form) → a JSON ARRAY of

data/lib/phlex/reactive/component.rb

@@ -86,7 +86,12 @@ module Phlex
       # { name => type } hash for the typed HASH form (:string reads the field
       # value raw, :number coerces). `inputs` stays the ordered name list either
       # way, so iteration order is preserved and the array-form wire is unchanged.
-      ComputeDefinition = Data.define(:name, :inputs, :outputs, :reducer, :input_types)
+      #
+      # `mirror` (issue #159) is nil when undeclared, else a { name => [id
+      # selectors] } map — DECLARED cross-root text mirrors, validated to id
+      # selectors only at declare time (the server half of the two-sided
+      # default-deny; the client interpreter re-checks the shape).
+      ComputeDefinition = Data.define(:name, :inputs, :outputs, :reducer, :input_types, :mirror)
 
       # A declared add/remove-row collection (issue #35): the list contract tied
       # into one unit — the per-row item component, the container DOM id rows

data/lib/phlex/reactive/js.rb

@@ -157,6 +157,20 @@ module Phlex
         append("focus_first", target_args(to, global:))
       end
 
+      # --- Text content (issue #159) ---
+      #
+      # text(to, value) — set the target's textContent (stringified; nil clears).
+      # XSS-safe by construction: textContent only, NEVER innerHTML — strictly
+      # less powerful than set_attr. Pair with `global: true` to paint a value
+      # into a node OUTSIDE the component's root (the cross-root text escape,
+      # e.g. a read-only recap in another tab pane).
+
+      def text(to, value, global: false)
+        args = { "to" => normalize_target(to), "value" => value.to_s }
+        args["global"] = true if global
+        append("text", args.freeze)
+      end
+
       # --- Dispatch a bubbling CustomEvent (issue #96) ---
       #
       # dispatch(name, to: nil, detail: {}) — emit a bubbling CustomEvent so other

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.9.1"
+    VERSION = "0.9.2"
   end
 end

metadata

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