phlex-reactive 0.15.1 → 0.15.2

data/lib/phlex/reactive/held_fields.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The fields a morph held over a changed server value (issue #370).
+    #
+    # Since #338 a morph keeps the value of the field being typed in and writes
+    # the render's value as the field's default. When that render differs from
+    # the old default, someone else changed the field while the user typed.
+    # The client marks such a field and the root's next action request names it
+    # in the X-Reactive-Held header (a JSON array of field names). Inside the
+    # action, `reactive_held_fields` returns those names, so the app can refuse
+    # or merge instead of silently overwriting the other change:
+    #
+    #   def save(title: nil)
+    #     authorize!(@note, to: :update?)
+    #     return conflict! if reactive_held_fields.include?("title") && title != @note.title
+    #     ...
+    #
+    # The header is UNTRUSTED input, like every request field: it carries names
+    # only, never values, and is read as data — capped in bytes, count and
+    # length, non-strings dropped, and filtered to the names the running action
+    # declares as params (matched on the base name, so `title[en]` counts for a
+    # declared `title`). A name the action can't receive can't be overwritten
+    # by it. Malformed input reads as nothing held; it never fails a request.
+    # It is a hint about what the user saw, not authorization.
+    module HeldFields
+      HEADER = "X-Reactive-Held"
+
+      # A raw header longer than this is ignored unparsed.
+      MAX_BYTES = 4_096
+      # At most this many names are read …
+      MAX_NAMES = 64
+      # … each at most this long.
+      MAX_NAME_LENGTH = 128
+
+      EMPTY = [].freeze
+
+      class << self
+        # The held field names during the current action ([] outside one).
+        def current
+          Thread.current[:phlex_reactive_held_fields] || EMPTY
+        end
+
+        # Expose `names` for the block, restoring the previous list after.
+        def with(names)
+          previous = Thread.current[:phlex_reactive_held_fields]
+          Thread.current[:phlex_reactive_held_fields] = names
+          yield
+        ensure
+          Thread.current[:phlex_reactive_held_fields] = previous
+        end
+
+        # The header's names that `action_def` declares, frozen; [] for
+        # anything absent, oversized or malformed.
+        def parse(raw, action_def)
+          return EMPTY if raw.nil? || raw.empty? || raw.bytesize > MAX_BYTES
+
+          names = JSON.parse(raw)
+          names.is_a?(Array) ? filter(names, action_def) : EMPTY
+        rescue JSON::ParserError
+          EMPTY
+        end
+
+        # Keep the strings among `names` that `action_def` declares as params.
+        def filter(names, action_def)
+          declared = declared_names(action_def)
+          return EMPTY if declared.empty?
+
+          names.first(MAX_NAMES).select do
+            it.is_a?(String) && it.length <= MAX_NAME_LENGTH && declared.include?(base_name(it))
+          end.uniq.freeze
+        end
+
+        private
+
+        def declared_names(action_def)
+          params = action_def.params
+          params.is_a?(Hash) ? params.keys.map(&:to_s) : EMPTY
+        end
+
+        # "title" for "title", "title[]" and "title[en]".
+        def base_name(name) = name.split("[", 2).first
+      end
+    end
+  end
+end

data/lib/phlex/reactive/js.rb

@@ -11,10 +11,15 @@ module Phlex
     #   # -> data-reactive-ops-param='[["toggle",{"to":"#menu"}]]'
     #
     # These are declarative DOM OPERATIONS, not state: nothing is shipped back
-    # to the server, nothing is trusted from the client, and any server
+    # to the server, nothing is trusted from the client, and a server
     # re-render of the component resets whatever they toggled (the LiveView
-    # JS-commands caveat — by design; use a signed action for state that must
-    # survive re-renders).
+    # JS-commands caveat; use a signed action for state the server must know).
+    # The exception is `keep: true` (issue #369) on the class, visibility and
+    # attribute ops: the client records what the op did to each target, and a
+    # MORPH of that element re-applies it, so a selection or an expanded row
+    # survives another viewer's broadcast. An element a stream REPLACES is a
+    # new element and starts clean. Kept state belongs to one tab, so
+    # broadcast_to(js:) refuses the flag.
     #
     # Targets: a CSS selector string is resolved WITHIN the component's root by
     # default (nested reactive roots excluded, issue #15 semantics); `:root`
@@ -38,10 +43,13 @@ module Phlex
       #   * the URL set     — href/src/srcdoc/action/formaction/xlink:href can carry
       #                       a `javascript:` payload; setting them from client ops
       #                       is a navigation/injection surface, not a UI toggle.
+      #                       srcset (issue #373) is a URL list that picks what an
+      #                       <img> loads: copy_media copies it from a server-rendered
+      #                       image instead.
       #   * style           — inline CSS injection; use classes (add_class/...).
       # The INTENDED surface is class ops plus boolean/state attributes:
       #   hidden, disabled, open, selected, aria-*, data-*.
-      URL_BEARING_ATTRS = %w[href src srcdoc action formaction xlink:href].freeze
+      URL_BEARING_ATTRS = %w[href src srcset srcdoc action formaction xlink:href].freeze
       EVENT_HANDLER_ATTR = /\Aon/i
 
       # The attr ops whose args carry a "name" the allowlist must gate. Used to
@@ -118,31 +126,39 @@ module Phlex
       # selector, document-wide under global: true). Pair it with ONE disclosure
       # target — with several, the last one wins.
       #   js.toggle("#menu", expanded: "#menu-trigger")
+      #
+      # `keep:` (issue #369) — on show/hide/toggle, the class ops and the attr
+      # ops: a morph of the target re-applies the op's result (the class on or
+      # off, `hidden`, the attribute's value or its absence) instead of the
+      # server render's. The latest kept op on an element and a class or
+      # attribute wins, so "clear all, then select one" works:
+      #   js.remove_class(".item", "selected", keep: true).add_class("#item-2", "selected", keep: true)
+      # With `expanded:`, the trigger's aria-expanded is kept too.
 
-      def show(to, global: false, transition: nil, expanded: nil)
-        append("show", target_args(to, global:, transition:, expanded:))
+      def show(to, global: false, transition: nil, expanded: nil, keep: false)
+        append("show", target_args(to, global:, transition:, expanded:, keep:))
       end
 
-      def hide(to, global: false, transition: nil, expanded: nil)
-        append("hide", target_args(to, global:, transition:, expanded:))
+      def hide(to, global: false, transition: nil, expanded: nil, keep: false)
+        append("hide", target_args(to, global:, transition:, expanded:, keep:))
       end
 
-      def toggle(to, global: false, transition: nil, expanded: nil)
-        append("toggle", target_args(to, global:, transition:, expanded:))
+      def toggle(to, global: false, transition: nil, expanded: nil, keep: false)
+        append("toggle", target_args(to, global:, transition:, expanded:, keep:))
       end
 
       # --- Classes ---
 
-      def add_class(to, *classes, global: false)
-        append("add_class", class_args(to, classes, global:))
+      def add_class(to, *classes, global: false, keep: false)
+        append("add_class", class_args(to, classes, global:, keep:))
       end
 
-      def remove_class(to, *classes, global: false)
-        append("remove_class", class_args(to, classes, global:))
+      def remove_class(to, *classes, global: false, keep: false)
+        append("remove_class", class_args(to, classes, global:, keep:))
       end
 
-      def toggle_class(to, *classes, global: false)
-        append("toggle_class", class_args(to, classes, global:))
+      def toggle_class(to, *classes, global: false, keep: false)
+        append("toggle_class", class_args(to, classes, global:, keep:))
       end
 
       # --- Attributes (issue #96) — allowlisted names only ---
@@ -157,19 +173,19 @@ module Phlex
       # attribute becomes `on`. For aria-expanded/aria-pressed/data-state:
       #   js.toggle_attr("#trigger", "aria-expanded", "true", "false")
 
-      def set_attr(to, name, value, global: false)
-        append("set_attr", attr_args(to, name, global:, value:))
+      def set_attr(to, name, value, global: false, keep: false)
+        append("set_attr", attr_args(to, name, global:, keep:, value:))
       end
 
-      def remove_attr(to, name, global: false)
-        append("remove_attr", attr_args(to, name, global:))
+      def remove_attr(to, name, global: false, keep: false)
+        append("remove_attr", attr_args(to, name, global:, keep:))
       end
 
-      def toggle_attr(to, name, *values, global: false)
-        args = attr_args(to, name, global:)
+      def toggle_attr(to, name, *values, global: false, keep: false)
+        args = attr_args(to, name, global:, keep:)
         return append("toggle_attr", args) if values.empty?
 
-        append("toggle_attr", args.merge("values" => toggle_values(name, values)).freeze)
+        append("toggle_attr", with_keep(args.except("keep").merge("values" => toggle_values(name, values)), keep))
       end
 
       # --- Focus (issue #96) ---
@@ -256,7 +272,7 @@ module Phlex
       # element (the two passes would fight over the same attribute).
 
       def paste_into(to, global: false)
-        if to == :root
+        if [:root, ROOT_SENTINEL].include?(to)
           raise ArgumentError,
             "#{self.class}: paste_into targets a field, not the component root — " \
             "pass the input's CSS selector (e.g. js.paste_into(\"[name=code]\"))"
@@ -265,6 +281,36 @@ module Phlex
         append("paste_into", target_args(to, global:))
       end
 
+      # --- Preview a chosen file (issue #375) ---
+      #
+      # preview_file(to, into:, name: nil) — on the file input's change, paint
+      # the first chosen IMAGE file onto the `into:` img through an object URL
+      # the client creates itself (URL.createObjectURL) and revokes on the next
+      # choice, on a clear, and when the img leaves the page. The op carries NO
+      # URL — there is no parameter for one, and the client never reads a `url`
+      # key — so the `src` refusal of set_attr (issue #96) stays whole. `to` is
+      # an input[type=file] (an explicit :root is refused); `into:` must
+      # resolve to an <img> (anything else warns and is skipped in the
+      # browser); `name:` optionally names a node that gets file.name as
+      # textContent. An empty selection or a non-image file clears the preview.
+      # ACTOR-ONLY like paste_into: refused in broadcast_to(js:) — a broadcast
+      # that read every subscriber's file input would be hostile.
+      #   input(type: "file", id: "photo-file", accept: "image/*",
+      #     **on_client(:change, js.preview_file("#photo-file", into: "#photo", name: "#photo-name")))
+
+      def preview_file(to, into:, name: nil, global: false)
+        if [:root, ROOT_SENTINEL].include?(to)
+          raise ArgumentError,
+            "#{self.class}: preview_file reads a file input, not the component root — " \
+            "pass the input's CSS selector (e.g. js.preview_file(\"#photo-file\", into: \"#photo\"))"
+        end
+
+        args = { "to" => normalize_target(to), "into" => preview_selector(:into, into) }
+        args["name"] = preview_selector(:name, name) unless name.nil?
+        args["global"] = true if global
+        append("preview_file", args.freeze)
+      end
+
       # --- Text content (issue #159) ---
       #
       # text(to, value) — set the target's textContent (stringified; nil clears).
@@ -279,6 +325,56 @@ module Phlex
         append("text", args.freeze)
       end
 
+      # --- Copy a server-rendered image (issue #373) ---
+      #
+      # copy_media(to, from:) — copy src, srcset and alt from the `from` <img>
+      # onto the `to` <img>. Both are ELEMENTS (:root or a CSS selector,
+      # resolved with the op's own scoping, global: included): the URL is read
+      # off the live source element in the browser and is never an argument,
+      # so the set_attr refusal of src (issue #96) stays. A missing source, a
+      # non-<img> source or one without src clears the target's src, srcset
+      # and alt; a target that is not an <img> is skipped. The same URL twice
+      # is not written again (no reload). Broadcast-safe: it only reads
+      # elements already in the subscriber's document.
+      #   button(**on_client(:click, js.copy_media("#logo", from: "#logo-007"))) { "North" }
+
+      def copy_media(to, from:, global: false)
+        source = normalize_target(from)
+        raise ArgumentError, "#{self.class}: copy_media from: needs a CSS selector, got an empty string" if source.empty?
+
+        args = { "to" => normalize_target(to), "from" => source }
+        args["global"] = true if global
+        append("copy_media", args.freeze)
+      end
+
+      # --- A field's live value (issue #374) ---
+      #
+      # set_value(to, value) — assign the target field's IDL `.value` (never
+      # the attribute: that is set_attr, and a field the user typed in does not
+      # follow it), then dispatch a bubbling `input` when the value changed, so
+      # reducers and reactive_show see it as typed — the set-value contract
+      # paste_into uses (issue #183). Never `change`, never focus (chain
+      # js.focus for that), never parsed as HTML. The value is stringified; nil
+      # and "" clear the field. The target is an input, textarea or select:
+      # :root is refused loudly like paste_into, and anything else (a
+      # contenteditable — reactive_editable writes those — a non-field, a
+      # non-empty value for a file input) warns and skips in the browser.
+      # ACTOR-ONLY like paste_into: a broadcast that overwrote every
+      # subscriber's field would be hostile (BROADCAST_REFUSED_OPS).
+      #   button(**on_client(:click, js.set_value("#notes", "Thanks"))) { "Thanks" }
+
+      def set_value(to, value, global: false)
+        if [:root, ROOT_SENTINEL].include?(to)
+          raise ArgumentError,
+            "#{self.class}: set_value targets a field, not the component root — " \
+            "pass the field's CSS selector (e.g. js.set_value(\"#notes\", \"Thanks\"))"
+        end
+
+        args = { "to" => normalize_target(to), "value" => value.to_s }
+        args["global"] = true if global
+        append("set_value", args.freeze)
+      end
+
       # --- Tick or untick a checkbox group (issue #342) ---
       #
       # check_group(group, checked = true) — set every OWNED box of the group
@@ -395,14 +491,31 @@ module Phlex
         self.class.new([*@ops, [name, args].freeze].freeze)
       end
 
-      def target_args(to, global:, transition: nil, expanded: nil)
+      def target_args(to, global:, transition: nil, expanded: nil, keep: false)
         args = { "to" => normalize_target(to) }
         args["global"] = true if global
         args["transition"] = normalize_transition(transition) if transition
         args["expanded"] = normalize_target(expanded) unless expanded.nil?
+        with_keep(args, keep)
+      end
+
+      # keep: (issue #369) rides LAST and only when true, so an op without it
+      # serializes byte-identically to before.
+      def with_keep(args, keep)
+        args["keep"] = true if keep
         args.freeze
       end
 
+      # preview_file's into:/name: — a non-empty CSS selector String, never
+      # :root or its "@root" sentinel (the root is a container, not the img —
+      # and a name: on it would replace the whole component with a file name).
+      def preview_selector(key, selector)
+        return selector if selector.is_a?(String) && !selector.strip.empty? && selector != ROOT_SENTINEL
+
+        raise ArgumentError,
+          "#{self.class}: preview_file #{key}: must be a CSS selector string, got #{selector.inspect}"
+      end
+
       # The [on, off] pair of a two-value toggle_attr, stringified. Loud on a
       # half-specified pair or one that could never change anything.
       def toggle_values(name, values)
@@ -422,13 +535,13 @@ module Phlex
 
       # An attr op's args: the target, the allowlisted name, an optional
       # (stringified) value. The name is validated LOUDLY at build time.
-      def attr_args(to, name, global:, value: :__none)
+      def attr_args(to, name, global:, keep: false, value: :__none)
         name = name.to_s
         assert_allowed_attr(name)
         args = { "to" => normalize_target(to), "name" => name }
         args["value"] = value.to_s unless value == :__none
         args["global"] = true if global
-        args.freeze
+        with_keep(args, keep)
       end
 
       # Build-time attr-name allowlist for the instance builder — delegates to the
@@ -456,14 +569,14 @@ module Phlex
         [transition[:during], transition[:from], transition[:to]].map(&:to_s).freeze
       end
 
-      def class_args(to, classes, global:)
+      def class_args(to, classes, global:, keep: false)
         if classes.empty?
           raise ArgumentError, "#{self.class}: a class op needs at least one class (got none for #{to.inspect})"
         end
 
         args = { "to" => normalize_target(to), "classes" => classes.map(&:to_s).freeze }
         args["global"] = true if global
-        args.freeze
+        with_keep(args, keep)
       end
 
       # Instance-side alias for the class method (used by the op builder). See

data/lib/phlex/reactive/streamable.rb

@@ -40,13 +40,21 @@ module Phlex
       # (issue #342) would tick or clear every subscriber's selection; presence
       # (issue #358) would write every subscriber's presence state; show_modal
       # and close_dialog (issue #365) would open or close a modal, and move
-      # focus, on every screen at once. They
+      # focus, on every screen at once; set_value (issue #374) would overwrite
+      # every subscriber's field; preview_file (issue #375) would read every
+      # subscriber's file input. They
       # belong to the actor's own reply (reply.js) or gesture (on_client / a
       # reducer's $ops), never a broadcast. Names mirror Phlex::Reactive::JS's verbs.
       BROADCAST_REFUSED_OPS = %w[
         focus focus_first submit paste_into persist_state persist_clear check_group presence
         show_modal close_dialog
+        preview_file
+        set_value
       ].freeze
+      # Refused as a FLAG, on any op (issue #369): keep: records client state in
+      # the tab that ran the op, so a broadcast carrying it would plant that
+      # state in every subscriber's tab. The op itself broadcasts fine without it.
+      BROADCAST_REFUSED_ARG = "keep"
 
       # The broadcast_to verb kwargs (issue #185) → their Turbo stream action.
       # SELF-TARGETING verbs derive the target from the component's #id (require a
@@ -201,14 +209,30 @@ module Phlex
               "subscriber's form; broadcasting paste_into reads every subscriber's clipboard; " \
               "broadcasting check_group ticks or clears every subscriber's selection; " \
               "broadcasting presence writes every subscriber's presence state; " \
+              "broadcasting set_value overwrites every subscriber's field (render the value instead); " \
               "broadcasting show_modal or close_dialog opens or closes a modal (and moves focus) on " \
-              "every screen — render the dialog open or closed, with data: { reactive_modal: true }, instead." \
+              "every screen — render the dialog open or closed, with data: { reactive_modal: true }, instead. " \
+              "Broadcasting preview_file reads every subscriber's chosen file onto their page. " \
               "These are actor concerns (reply.js / on_client / $ops)."
           end
+          refuse_kept_broadcast_ops!(pairs)
 
           Phlex::Reactive::Response.js_ops_json(ops)
         end
 
+        # keep: (issue #369) is per-tab client state: refuse the flag on any op.
+        def refuse_kept_broadcast_ops!(pairs)
+          kept = pairs.filter_map do |name, args|
+            name.to_s if args.is_a?(::Hash) && (args[BROADCAST_REFUSED_ARG] || args[BROADCAST_REFUSED_ARG.to_sym])
+          end
+          return if kept.empty?
+
+          raise ArgumentError,
+            "broadcast_to(js:) refuses keep: (on #{kept.uniq.join(", ")}) — kept state belongs to the tab " \
+            "that ran the op; broadcasting it would plant it in every subscriber's tab. Drop keep: from the " \
+            "broadcast, or render the state on the server."
+        end
+
         # Render a built component to HTML for a broadcast, ALWAYS instrumented
         # (issue #185): a Streamable renders through its own render_component (which
         # fires render.phlex_reactive); a plain component renders through the module

data/lib/phlex/reactive/test_helpers.rb

@@ -93,14 +93,23 @@ module Phlex
       #      after_commit broadcasts behave.
       #   5. authorization — a registered authorization error RAISES (the endpoint
       #      maps it to 403; a unit test asserts the real exception).
-      def run_reactive(component, action, **params)
+      #
+      # `held:` stands in for the X-Reactive-Held header (issue #370): the field
+      # names a morph held over a changed server value, filtered to the action's
+      # declared params exactly as the endpoint filters them, and returned by
+      # reactive_held_fields inside the action. `held` is therefore reserved
+      # here: an action param literally named `held` can't be passed through.
+      #
+      #   run_reactive(form, :save, held: ["title"], title: "Draft by B")
+      def run_reactive(component, action, held: [], **params)
         klass = component.class
         action_def = klass.reactive_actions[action.to_sym] || raise_undeclared(klass, action)
 
         rebuilt = rebuild_from_identity(component, klass)
         coerced = action_def.schema.coerce(stringify_params(params))
 
-        returned = run_reactive_action(rebuilt, action_def, coerced)
+        held_fields = Phlex::Reactive::HeldFields.parse(Array(held).map(&:to_s).to_json, action_def)
+        returned = Phlex::Reactive::HeldFields.with(held_fields) { run_reactive_action(rebuilt, action_def, coerced) }
         Result.new(returned:, component: rebuilt)
       end
 

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.15.1"
+    VERSION = "0.15.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.15.2
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -198,6 +198,7 @@ files:
 - lib/phlex/reactive/component/helpers.rb
 - lib/phlex/reactive/component/identity.rb
 - lib/phlex/reactive/component/lazy.rb
+- lib/phlex/reactive/component/media_binding.rb
 - lib/phlex/reactive/component/presence_declaration.rb
 - lib/phlex/reactive/component/registry.rb
 - lib/phlex/reactive/component/selection.rb
@@ -210,6 +211,7 @@ files:
 - lib/phlex/reactive/effects.rb
 - lib/phlex/reactive/engine.rb
 - lib/phlex/reactive/fragment.rb
+- lib/phlex/reactive/held_fields.rb
 - lib/phlex/reactive/inspector.rb
 - lib/phlex/reactive/inspector/report.rb
 - lib/phlex/reactive/js.rb