phlex-reactive 0.9.1 → 0.9.3

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

@@ -399,6 +399,54 @@ module Phlex
           span(**mix({ data: { reactive_text: name.to_s } }, attrs)) { initial }
         end
 
+        # Value-conditional visibility (issue #161) — the x-show / data-show /
+        # wire:show equivalent, entirely client-side. Spread onto the element to
+        # show/hide; it declares which OWNED field controls it plus ONE literal
+        # predicate, and the generic controller toggles the `hidden` attribute
+        # from the field's CURRENT value on every input/change — no round trip,
+        # no token, no bespoke Stimulus controller:
+        #
+        #   div(**reactive_show(:mode, not: "off"))        { "details" }
+        #   div(**reactive_show(:kind, equals: "premium")) { "premium panel" }
+        #   div(**reactive_show(:size, in: %w[l xl]))      { "surcharge note" }
+        #   div(**reactive_show(:gift, equals: true))      { "gift message" }
+        #
+        # Exactly one predicate — equals:, not:, or in: (a list) — and every
+        # value is STRINGIFIED for a literal match against the field's value
+        # (a checkbox compares its checked state as "true"/"false", so
+        # `equals: true` is the checkbox form; a radio group reads the checked
+        # radio's value). This is a DECLARED LITERAL MATCH, never an expression
+        # — there is no eval surface (default-deny, like the op vocabulary).
+        #
+        # Scope: presentational only, strictly less powerful than the js ops —
+        # it reads an owned field (#15 ownership) and toggles `hidden` on an
+        # owned element. The client seeds visibility at connect and reconciles
+        # after a morph; render the initial `hidden:` yourself (from the same
+        # server state that renders the field) to avoid a first-paint flash.
+        # Extra attrs deep-merge over the binding (mix), like reactive_field.
+        def reactive_show(field, **options)
+          predicates = options.slice(*SHOW_PREDICATE_KEYS)
+          attrs = options.except(*SHOW_PREDICATE_KEYS)
+          unless predicates.size == 1
+            raise ArgumentError,
+              "reactive_show(#{field.inspect}) needs exactly one predicate — equals:, not:, or " \
+              "in: — got #{predicates.keys.inspect}"
+          end
+
+          key, value = predicates.first
+          data = { reactive_show_field: field.to_s }
+          if key == :in
+            list = Array(value).map(&:to_s)
+            raise ArgumentError, "reactive_show(#{field.inspect}) in: needs at least one value" if list.empty?
+
+            data[:reactive_show_in] = list.to_json
+          else
+            data[:"reactive_show_#{key}"] = value.to_s
+          end
+
+          mix({ data: }, attrs)
+        end
+
         # Scoped busy indicator (issue #99). Marks an element so the generic
         # controller toggles `data-reactive-busy` on it ONLY while `action` is in
         # flight — the scoped sibling of the always-on `data-reactive-busy` the
@@ -422,13 +470,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
@@ -475,6 +533,13 @@ module Phlex
           reactive_record_for_nested.update!(**nested_attributes(association, attrs), **extra)
         end
 
+        # The declared reactive_show predicates (issue #161): a literal match on
+        # the controlling field's current value. Exactly one per binding —
+        # enforced loudly at render (a dead binding must not no-op in the
+        # browser). `not`/`in` are Ruby keywords, so they arrive via **options
+        # rather than named kwargs.
+        SHOW_PREDICATE_KEYS = %i[equals not in].freeze
+
         # The declared optimistic-hint class ops (issue #98): the cosmetic class
         # vocabulary the client applies instantly and reverts on failure. Enforced
         # at build time in optimistic_hint_json (default-deny — a dead hint fails

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.3"
   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.3
 platform: ruby
 authors:
 - Mikael Henriksson