phlex-reactive 0.15.0 → 0.15.2

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

@@ -15,6 +15,7 @@ module Phlex
         include Selection
         include Sortable
         include Editable
+        include MediaBinding
 
         # The acting client's SSE connection id during the current action (nil
         # outside an action, or when the client isn't subscribed to a stream).
@@ -31,6 +32,20 @@ module Phlex
           Phlex::Reactive.current_connection_id
         end
 
+        # The names of this action's posted fields that a morph held over a
+        # changed server value (issue #370): someone else changed the field
+        # while this user typed, and this tab kept the user's text. [] when
+        # nothing was held, and outside an action. Filtered to the action's
+        # declared params; a hint about what the user saw, never authorization.
+        #
+        #   def save(title: nil)
+        #     return conflict!(title) if reactive_held_fields.include?("title") && title != @note.title
+        #     @note.update!(title:)
+        #   end
+        def reactive_held_fields
+          Phlex::Reactive::HeldFields.current
+        end
+
         # Manually satisfy the verify_authorized guard (issue #168) for a bespoke
         # authorization check the interceptor can't see — a hand-rolled policy, a
         # feature flag, an ownership comparison that doesn't go through one of
@@ -1790,12 +1805,27 @@ module Phlex
         # The data-action descriptors of an on()/on_client trigger: one, or a
         # shortcut's meta and ctrl twins (space-joined, as mix joins them).
         # The common, shortcut-less path is ONE interpolation (on() is a hot path).
+        # A chord whose key Stimulus lacks (issue #366: delete, backspace) binds a
+        # bare window keydown: the client's shortcut check matches it alone.
         def trigger_descriptors(event, shortcut, window_bound, method, once)
           return "#{event}#{"@window" if window_bound}->reactive##{method}#{":once" if once}" unless shortcut
+          return bare_shortcut_descriptor(shortcut, method, once) unless shortcut.stimulus_filterable?
 
           shortcut.filters.map { "keydown.#{it}@window->reactive##{method}#{":once" if once}" }.join(" ")
         end
 
+        # Stimulus removes a `:once` listener after its FIRST event, and a bare
+        # keydown hears every key, so the first keypress of any kind would spend it.
+        def bare_shortcut_descriptor(shortcut, method, once)
+          if once
+            raise ArgumentError,
+              "shortcut: #{shortcut.keys.inspect} cannot take once: — its key is matched by the " \
+              "library, not Stimulus, so the first key pressed of any kind would spend the binding"
+          end
+
+          "keydown@window->reactive##{method}"
+        end
+
         # A Hash param is JSON (Stimulus's param reader parses it back into an
         # object); the String form stays a plain string.
         def shortcut_param_attr(shortcut)

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # A preview image that follows a field (issue #373), with no URL in the
+      # page's ops or attributes: the server renders every candidate <img>
+      # (hidden), and the binding copies the one whose key matches.
+      #
+      #   input(name: "code")
+      #   img(id: "logo", alt: "", **reactive_media(
+      #     from: :code, take: 3,
+      #     pool: { "007" => "#logo-007", "011" => "#logo-011" },
+      #     label: "#caption", blank_label: "Unknown"
+      #   ))
+      #   img(id: "logo-007", src: "/logos/007.svg", alt: "North", hidden: true)
+      #
+      # The field is read the way reactive_show reads one (owned fields, a
+      # radio group's checked value, reactive_scope applied). `take:` keeps the
+      # first n characters as the key; omit it to use the whole value. A pool
+      # value is a CSS SELECTOR for an <img> inside the root, never a URL: the
+      # client copies that element's src, srcset and alt the way
+      # js.copy_media does. A key, selector or element that misses clears the
+      # preview. `label:` names a node whose textContent becomes the chosen
+      # image's alt (`blank_label`, or "", on a miss). Client-only: no token,
+      # no round trip.
+      #
+      # Named MediaBinding, not Media: this module sits in every reactive
+      # component's ancestry, and a bare `Media` would shadow a host app's kit
+      # component of that name (issue #233).
+      module MediaBinding
+        def reactive_media(from:, pool: nil, take: nil, label: nil, blank_label: nil, **attrs)
+          wire = { "field" => media_field!(from) }
+          wire["take"] = media_take!(take) unless take.nil?
+          wire["pool"] = media_pool!(pool)
+          wire["label"] = media_selector!(:label, label) unless label.nil?
+          wire["blank"] = blank_label.to_s unless blank_label.nil?
+          mix({ data: { reactive_media: wire.to_json } }, attrs)
+        end
+
+        private
+
+        def media_field!(from)
+          name = from.to_s if from.is_a?(Symbol) || from.is_a?(String)
+          return name unless name.nil? || name.strip.empty?
+
+          raise ArgumentError, "reactive_media from: needs the field name to watch (e.g. from: :code), got #{from.inspect}"
+        end
+
+        def media_take!(take)
+          return take if take.is_a?(Integer) && take.positive?
+
+          raise ArgumentError, "reactive_media take: must be a positive Integer (or omitted for the whole value), " \
+                               "got #{take.inspect}"
+        end
+
+        def media_pool!(pool)
+          if pool.nil?
+            raise ArgumentError, "reactive_media needs pool: — a Hash of key => selector of a server-rendered <img> " \
+                                 "(e.g. pool: { \"007\" => \"#logo-007\" })"
+          end
+          unless pool.is_a?(Hash) && !pool.empty?
+            raise ArgumentError,
+              "reactive_media pool: must be a non-empty Hash of key => <img> selector, got #{pool.inspect}"
+          end
+
+          pool.to_h { |key, selector| [key.to_s, media_selector!(:pool, selector)] }
+        end
+
+        # A pool value or label: is a selector, never a URL — the client only
+        # ever passes it to querySelector.
+        def media_selector!(kind, selector)
+          if selector == JS::ROOT_SENTINEL
+            raise ArgumentError,
+              "reactive_media #{kind}: #{selector} names the whole root — pass the selector of an element inside it"
+          end
+          return selector if selector.is_a?(String) && !selector.strip.empty?
+
+          raise ArgumentError,
+            "reactive_media #{kind}: values are CSS selectors (e.g. \"#logo-007\"), got #{selector.inspect}"
+        end
+      end
+    end
+  end
+end

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) ---
@@ -186,6 +202,26 @@ module Phlex
         append("focus_first", target_args(to, global:))
       end
 
+      # --- Modal dialogs (issue #365) ---
+      #
+      # show_modal(to)   — HTMLDialogElement#showModal(): the top layer, a
+      #                    focus trap, ::backdrop, Escape to close and focus
+      #                    restored to the opener, all the browser's own. A
+      #                    dialog already open NON-modally is closed and
+      #                    reopened as a modal; one already modal is left as is.
+      # close_dialog(to) — HTMLDialogElement#close() (a closed one is left as is).
+      # A target that is not a <dialog> is skipped. Both ACTOR-ONLY like focus:
+      # opening a modal steals focus, so a broadcast refuses them — a
+      # broadcaster renders the dialog open with data: { reactive_modal: true }.
+
+      def show_modal(to, global: false)
+        append("show_modal", target_args(to, global:))
+      end
+
+      def close_dialog(to, global: false)
+        append("close_dialog", target_args(to, global:))
+      end
+
       # --- Submit (issue #226) ---
       #
       # submit(to = :root) — requestSubmit() the TARGET'S OWN form: the target
@@ -236,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]\"))"
@@ -245,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).
@@ -259,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
@@ -375,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)
@@ -402,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
@@ -436,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/shortcut.rb

@@ -13,17 +13,24 @@ module Phlex
     # exactly), so a `mod` chord renders TWO descriptors, a meta twin and a ctrl
     # twin, and the client runs only the twin for its platform. Stimulus keeps
     # the key filtering; the client adds the platform check, the editable-target
-    # guard and preventDefault.
+    # guard and preventDefault. The exception is a key Stimulus's default map
+    # lacks (delete, backspace — issue #366): it binds a bare window keydown,
+    # no twins, and the client matches the whole chord.
     #
     # Validation is loud, at render: Stimulus reports an unknown key token by
     # throwing at keypress time, which is too late to notice.
     class Shortcut
       MODIFIERS = %w[mod meta ctrl alt shift].freeze
       # Stimulus's default keyMappings: the named keys plus a-z and 0-9.
-      NAMED_KEYS = %w[enter tab esc space up down left right home end page_up page_down].freeze
+      STIMULUS_KEYS = %w[enter tab esc space up down left right home end page_up page_down].freeze
+      # Keys Stimulus's default map lacks (issue #366): a key filter naming one
+      # makes Stimulus throw at keypress, so such a chord renders a bare
+      # `keydown@window` and the client alone matches it.
+      LIBRARY_KEYS = %w[delete backspace].freeze
+      NAMED_KEYS = (STIMULUS_KEYS + LIBRARY_KEYS).freeze
       HASH_KEYS = %i[keys in_editable].freeze
 
-      private_constant :MODIFIERS, :NAMED_KEYS, :HASH_KEYS
+      private_constant :MODIFIERS, :STIMULUS_KEYS, :LIBRARY_KEYS, :NAMED_KEYS, :HASH_KEYS
 
       attr_reader :keys
 
@@ -61,6 +68,11 @@ module Phlex
         freeze
       end
 
+      # False for a chord whose key Stimulus's default map lacks (delete,
+      # backspace): it binds without a key filter and without twins — the
+      # client's shortcut check matches the key and picks the platform's `mod`.
+      def stimulus_filterable? = !LIBRARY_KEYS.include?(@keys.split("+").last)
+
       # The Stimulus key filters to bind: the meta and ctrl twins for a `mod`
       # chord, else the chord itself.
       def filters
@@ -95,8 +107,9 @@ module Phlex
 
         raise ArgumentError,
           "shortcut: #{source.inspect} has an unknown key #{key.first.inspect} — use a letter, a digit, " \
-          "or one of #{NAMED_KEYS.join(", ")} (Stimulus's default key map; custom keyMappings are not " \
-          "known on the server, bind those with event: and window: instead)"
+          "or one of #{NAMED_KEYS.join(", ")} (Stimulus's default key map, plus delete and backspace, " \
+          "which the library matches itself; custom keyMappings are not known on the server, bind " \
+          "those with event: and window: instead)"
       end
 
       def known_key?(key) = NAMED_KEYS.include?(key) || key.match?(/\A[a-z0-9]\z/)

data/lib/phlex/reactive/streamable.rb

@@ -38,12 +38,23 @@ module Phlex
       # (issue #226) would force-submit every subscriber's form; paste_into
       # (issue #228) would read every subscriber's clipboard; check_group
       # (issue #342) would tick or clear every subscriber's selection; presence
-      # (issue #358) would write every subscriber's presence state. They
+      # (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; 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
@@ -197,13 +208,31 @@ module Phlex
               "steals it in every subscriber's tab; broadcasting submit force-submits every " \
               "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 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. " \
+              "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