phlex-reactive 0.15.3 → 0.15.4

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

@@ -17,6 +17,9 @@ module Phlex
         include Editable
         include MediaBinding
         include ImageFallbackBinding
+        include CountdownBinding
+        include FieldReferences
+        include ShowOptions
 
         # 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).
@@ -387,11 +390,7 @@ module Phlex
               "(declared: #{actions.keys.inspect})"
           end
 
-          if debounce && throttle
-            raise ArgumentError,
-              "on(#{action_name.inspect}) got both debounce: and throttle: — they are mutually " \
-              "exclusive (debounce is trailing-edge, throttle is leading-edge); pick one"
-          end
+          raise ArgumentError, both_waits_message("on(#{action_name.inspect})") if debounce && throttle
 
           # Guarded here, not inside: building the caller label allocates (on() is a hot path).
           shortcut = shortcut_for!("on(#{action_name.inspect})", shortcut, event:, window:, outside:) unless shortcut.nil?
@@ -468,6 +467,13 @@ module Phlex
         # no-op (no confirm, no preventDefault). Not Turbo-specific: any
         # CustomEvent whose detail carries a flag works.
         #
+        # Issue #393: `debounce:` (trailing edge) and `throttle:` (leading edge)
+        # wait the way on()'s do — non-negative Integer milliseconds, never both,
+        # on the same client timers (a blur flushes a pending debounce). once:
+        # still means one run, after the wait:
+        #   input(**on_client(:input, js.submit("#search"), debounce: 300))
+        #   div(**on_client(:scroll, js.add_class("#bar", "stuck"), window: true, throttle: 250))
+        #
         # Ops are EPHEMERAL UI: any server re-render of the component (an action
         # reply, a broadcast, a morph) rebuilds from server state and resets
         # whatever they toggled — by design (the LiveView JS-commands caveat). Use
@@ -477,7 +483,7 @@ module Phlex
         # accepted — a dead trigger should fail at render, not no-op in the
         # browser.
         def on_client(event, ops, window: false, once: false, outside: false, confirm: nil, detail: nil,
-                      shortcut: nil)
+                      shortcut: nil, debounce: nil, throttle: nil)
           unless ops.is_a?(Phlex::Reactive::JS)
             raise ArgumentError,
               "on_client expects a Phlex::Reactive::JS chain (e.g. js.toggle(\"#menu\")), " \
@@ -497,6 +503,7 @@ module Phlex
           shortcut = client_shortcut!(event, shortcut, window:, outside:)
           window_bound = window || outside || !shortcut.nil?
           record = client_binding_record(event, ops, window_bound:, outside:, once:, confirm:, detail:)
+          client_binding_wait!(record, event, debounce, throttle) unless debounce.nil? && throttle.nil?
           # The record's `on` stays the bare keydown: the client reads a key
           # filter from `on`, and `mod` is not a key.
           record["shortcut"] = shortcut.param if shortcut
@@ -674,13 +681,19 @@ module Phlex
           conditions = options.slice(*SHOW_CONDITION_KEYS)
           disable = options.delete(:disable)
           values_override = options.delete(:values)
-          attrs = options.except(*SHOW_CONDITION_KEYS)
+          after, clear, focus, scroll = options.values_at(:after, :clear, :focus, :scroll)
+          attrs = options.except(*SHOW_CONDITION_KEYS, *SHOW_OPTION_KEYS)
 
           groups = Phlex::Reactive::ShowConditions.normalize(**conditions)
+          reference_same_fields!(:reactive_show, groups)
           data = { reactive_show: { "any" => groups }.to_json }
           data[:reactive_show_disable] = "true" if disable
+          data.merge!(show_option_data(groups, after:, clear:, focus:, scroll:))
 
           result = mix({ data: }, attrs)
+          # after: — the server never saw a blur, so the section starts hidden.
+          return result.key?(:hidden) ? result : result.merge(hidden: true) unless after.nil?
+
           apply_first_paint_hidden(result, groups, values_override)
         end
 
@@ -1183,10 +1196,11 @@ module Phlex
           { data: { reactive_show_targets: normalized.to_json } }
         end
 
-        # Client-only localStorage draft over the fields this root OWNS (issue
-        # #239) — "don't make me start over". Spread on the ROOT (mix with
+        # Client-only browser-storage draft over the fields this root OWNS
+        # (issue #239) — "don't make me start over". Spread on the ROOT (mix with
         # reactive_root, like reactive_show_targets); the generic controller
-        # then writes every owned control's value to localStorage as the user
+        # then writes every owned control's value to the selected store
+        # (localStorage, or sessionStorage with `storage: :session`) as the user
         # types (debounced on `input`, immediate on `change`, flushed on
         # disconnect), restores the draft on the NEXT connect, and forgets it
         # when the owning form submits successfully (turbo:submit-end), when
@@ -1215,14 +1229,22 @@ module Phlex
         # control the server rendered BLANK, so a 422 re-render's submitted
         # values win over an older draft; `:always` lets the draft win.
         #
+        # `storage:` — `:local` (default) keeps the draft in localStorage,
+        # shared by every tab and outliving them; `:session` (issue #397) keeps
+        # it in sessionStorage: this tab only, restored on reload, gone when
+        # the tab closes (a tab opened from it with an opener, or duplicated,
+        # starts with the browser's one-time copy of the session store). A
+        # string of the same word is accepted. Each store is
+        # read on its own: a `:local` draft is never restored by `:session`.
+        #
         # Same posture as reactive_show: no token, no POST, no expression
         # surface. Stored values are plain user input replayed via
         # .value/.checked (never HTML) — a tampered draft can only fill what
-        # the user could type. PII sits in localStorage for `ttl`; the
-        # successful-submit clear and `ttl` are the shared-computer mitigation
-        # (see docs/security). ONE call per root — Phlex `mix` space-joins
+        # the user could type. PII sits in the selected store for `ttl`; the
+        # successful-submit clear, `ttl` and `storage: :session` are the
+        # shared-computer mitigation (see docs/security). ONE call per root — Phlex `mix` space-joins
         # duplicate string data values, so a second call would corrupt the JSON.
-        def reactive_persist(key:, ttl: 7.days, fields: nil, restore: :blank, debounce: 300)
+        def reactive_persist(key:, ttl: 7.days, fields: nil, restore: :blank, debounce: 300, storage: :local)
           payload = {
             "key" => validate_persist_key!(key),
             "ttl" => validate_persist_ttl!(ttl),
@@ -1230,6 +1252,7 @@ module Phlex
           }
           payload["restore"] = "always" if validate_persist_restore!(restore) == :always
           payload["fields"] = validate_persist_fields!(fields) if fields
+          payload["storage"] = "session" if validate_persist_storage!(storage) == :session
 
           { data: { reactive_persist: payload.to_json } }
         end
@@ -1266,6 +1289,16 @@ module Phlex
           raise ArgumentError, "reactive_persist restore: must be :blank or :always, got #{restore.inspect}"
         end
 
+        PERSIST_STORAGES = %w[local session].freeze
+        private_constant :PERSIST_STORAGES
+
+        def validate_persist_storage!(storage)
+          name = storage.to_s if storage.is_a?(Symbol) || storage.is_a?(String)
+          return name.to_sym if PERSIST_STORAGES.include?(name)
+
+          raise ArgumentError, "reactive_persist storage: must be :local or :session, got #{storage.inspect}"
+        end
+
         def validate_persist_fields!(fields)
           list = Array(fields)
           raise ArgumentError, "reactive_persist fields: needs at least one field name" if list.empty?
@@ -1379,6 +1412,10 @@ module Phlex
         # vocabulary; there are no predicate kwargs any more.
         SHOW_CONDITION_KEYS = %i[if if_any unless].freeze
 
+        # reactive_show's own keywords beyond disable:/values: (ShowOptions):
+        # the after: blur gate (#396) and the visibility transitions (#394).
+        SHOW_OPTION_KEYS = %i[after clear focus scroll].freeze
+
         # The removed 0.9.5 surface (issue #180 clean break): each of these
         # kwargs — and a positional field — now raises a GUIDED error printing
         # the if:/if_any:/unless: rewrite. Kept only to detect the legacy call
@@ -1514,6 +1551,27 @@ module Phlex
           record
         end
 
+        # Issue #393: the one message on() and on_client() raise when given both
+        # waits. Built only on that error path (on() is a hot path).
+        def both_waits_message(label)
+          "#{label} got both debounce: and throttle: — they are mutually exclusive " \
+            "(debounce is trailing-edge, throttle is leading-edge); pick one"
+        end
+
+        # Issue #393: on_client's debounce:/throttle: ride on the binding record,
+        # validated loud at render (non-negative Integer ms, never both).
+        def client_binding_wait!(record, event, debounce, throttle)
+          label = "on_client(#{event.inspect})"
+          raise ArgumentError, both_waits_message(label) if debounce && throttle
+
+          key, ms = debounce.nil? ? ["throttle", throttle] : ["debounce", debounce]
+          unless ms.is_a?(Integer) && !ms.negative?
+            raise ArgumentError, "#{label} #{key}: must be a non-negative Integer (ms), got #{ms.inspect}"
+          end
+
+          record[key] = ms
+        end
+
         # Issue #346: validate + stringify on_client's detail: filter. Loud at
         # render, like the other on_client validations — a dead filter fails
         # here, never silently in the browser.

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

@@ -21,11 +21,24 @@ module Phlex
       #
       #   img(**reactive_media(from: :rib, pool: POOL, **reactive_image_fallback))
       #
+      #
+      # wrap: (issue #392) names the box around the img (a CSS selector inside
+      # the root, like show_alt:). On error the client hides it and marks the
+      # hide as its own (data-reactive-wrap-hidden); recovery shows it again
+      # only when that mark is there, so a wrapper the author hid stays
+      # hidden. The wrapper may hold the img: its text is never written.
+      # hide: false with wrap: hides the wrapper only.
+      #
+      #   span(id: "badge", class: "rounded-full p-1") do
+      #     img(id: "logo", alt: "", **reactive_image_fallback(hide: false, wrap: "#badge"))
+      #   end
+      #
       # Named ImageFallbackBinding for the reason MediaBinding is (issue #233).
       module ImageFallbackBinding
-        def reactive_image_fallback(hide: true, show_alt: nil, **attrs)
+        def reactive_image_fallback(hide: true, show_alt: nil, wrap: nil, **attrs)
           wire = { "hide" => image_fallback_hide!(hide) }
-          wire["alt"] = image_fallback_alt!(show_alt) unless show_alt.nil?
+          wire["alt"] = image_fallback_selector!(:show_alt, show_alt, "#bank-name") unless show_alt.nil?
+          wire["wrap"] = image_fallback_selector!(:wrap, wrap, "#badge") unless wrap.nil?
           mix({ data: { reactive_image_fallback: wire.to_json } }, attrs)
         end
 
@@ -38,15 +51,15 @@ module Phlex
         end
 
         # A selector the client passes to querySelector, never a URL.
-        def image_fallback_alt!(selector)
+        def image_fallback_selector!(key, selector, example)
           if selector == JS::ROOT_SENTINEL
             raise ArgumentError,
-              "reactive_image_fallback show_alt: #{selector} names the whole root — pass the selector of a node inside it"
+              "reactive_image_fallback #{key}: #{selector} names the whole root — pass the selector of a node inside it"
           end
           return selector if selector.is_a?(String) && !selector.strip.empty?
 
           raise ArgumentError,
-            "reactive_image_fallback show_alt: must be a CSS selector (e.g. \"#bank-name\"), got #{selector.inspect}"
+            "reactive_image_fallback #{key}: must be a CSS selector (e.g. \"#{example}\"), got #{selector.inspect}"
         end
       end
     end

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

@@ -34,14 +34,22 @@ module Phlex
       # alone. The preview's data-reactive-media-state reads pending, hit or
       # miss, so a row can hide itself with CSS until there is an answer.
       #
+      # `when:` (a Regexp, anchored to the WHOLE field value, issue #390) is
+      # tested before the pool lookup while the key stays the `take` prefix: a
+      # value it rejects is pending too ("007bad" never hits "007"). It follows
+      # match:'s MediaPattern rules; match: still tests the key only.
+      #
       # 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, match: nil, pending: :clear, label: nil, blank_label: nil, **attrs)
+        def reactive_media(from:, pool: nil, take: nil, match: nil, when: nil, pending: :clear, label: nil,
+                           blank_label: nil, **attrs)
+          whole = binding.local_variable_get(:when)
           wire = { "field" => media_field!(from) }
           wire["take"] = media_take!(take) unless take.nil?
           wire["match"] = MediaPattern.to_js(match) unless match.nil?
+          wire["when"] = MediaPattern.to_js(whole, :when) unless whole.nil?
           wire["pending"] = "keep" if media_pending!(pending) == "keep"
           wire["pool"] = media_pool!(pool)
           wire["label"] = media_selector!(:label, label) unless label.nil?

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

@@ -3,9 +3,9 @@
 module Phlex
   module Reactive
     module Component
-      # reactive_media's match: (issue #380) — a Ruby Regexp as the JavaScript
-      # source the client anchors as ^(?:…)$ and compiles without flags. The
-      # source is tokenized (an escape is one token, so an escaped backslash is
+      # reactive_media's match: (issue #380) and when: (issue #390) — a Ruby
+      # Regexp as the JavaScript source the client anchors as ^(?:…)$ and
+      # compiles without flags. Errors name the keyword. The source is tokenized (an escape is one token, so an escaped backslash is
       # never mistaken for one): a leading \A and a trailing \z/\Z are dropped,
       # and anything JavaScript would read differently raises at render rather
       # than matching silently wrong in the browser.
@@ -19,59 +19,59 @@ module Phlex
 
         module_function
 
-        def to_js(match)
+        def to_js(match, name = :match)
           unless match.is_a?(Regexp)
             raise ArgumentError,
-              "reactive_media match: must be a Regexp (e.g. /\\A\\d{3}\\z/), got #{match.inspect}"
+              "reactive_media #{name}: must be a Regexp (e.g. /\\A\\d{3}\\z/), got #{match.inspect}"
           end
 
           unless match.options.nobits?(OPTIONS)
-            refuse!(match,
+            refuse!(name, match,
               "has options (i, m, x) the client would read differently — drop them")
           end
 
           tokens = match.source.scan(/\\.|./m)
           tokens.shift if tokens.first == "\\A"
           final = tokens.pop if %w[\z \Z].include?(tokens.last)
-          check!(tokens, match)
+          check!(tokens, match, name)
           # Ruby's \Z also matches before one final newline.
           final == "\\Z" ? "#{tokens.join}\\n?" : tokens.join
         end
 
-        def check!(tokens, match)
+        def check!(tokens, match, name)
           in_class = false
           tokens.each_with_index do |token, i|
             if RUBY_ONLY_ESCAPES.include?(token)
-              refuse!(match,
+              refuse!(name, match,
                 "uses #{token}, which is Ruby-only (JavaScript reads it differently)")
             end
-            refuse!(match, "has a character above U+FFFF (the client pattern has no u flag)") if token.ord > 0xFFFF
+            refuse!(name, match, "has a character above U+FFFF (the client pattern has no u flag)") if token.ord > 0xFFFF
             if token == "\\u" && tokens[i + 1] == "{"
-              refuse!(match,
+              refuse!(name, match,
                 "uses \\u{…}, which JavaScript without the u flag reads as a repeated u")
             end
             if in_class
               in_class = false if token == "]"
-              class_syntax!(tokens, i, match)
+              class_syntax!(tokens, i, match, name)
             elsif token == "["
               in_class = true
             elsif token == "(" && tokens[i + 1] == "?" && !SHARED_GROUPS.include?(tokens[i + 2])
-              refuse!(match, "uses (?#{tokens[i + 2]}…), a group JavaScript does not read the same way")
+              refuse!(name, match, "uses (?#{tokens[i + 2]}…), a group JavaScript does not read the same way")
             end
           end
         end
 
         # A [ inside a class (a nested class or a POSIX [:digit:]) and && (an
         # intersection) are Ruby-only: JavaScript reads them as literals.
-        def class_syntax!(tokens, index, match)
+        def class_syntax!(tokens, index, match, name)
           token = tokens[index]
           return unless token == "[" || (token == "&" && tokens[index + 1] == "&")
 
-          refuse!(match, "has a nested character class, a POSIX [:class:] or && — JavaScript reads them literally")
+          refuse!(name, match, "has a nested character class, a POSIX [:class:] or && — JavaScript reads them literally")
         end
 
-        def refuse!(match, why)
-          raise ArgumentError, "reactive_media match: #{match.inspect} #{why}"
+        def refuse!(name, match, why)
+          raise ArgumentError, "reactive_media #{name}: #{match.inspect} #{why}"
         end
       end
     end

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

@@ -34,6 +34,7 @@ module Phlex
           attrs = options.except(*Helpers::SHOW_CONDITION_KEYS)
 
           groups = Phlex::Reactive::ShowConditions.normalize(**conditions)
+          reference_same_fields!(:reactive_enable, groups)
           result = mix({ data: { reactive_enable: { "any" => groups }.to_json } }, attrs)
           return result if result.key?(:disabled)
 
@@ -46,8 +47,21 @@ module Phlex
         # flips, so computes, shows and counts re-run); its own checked /
         # indeterminate state follows the group. Give the header NO `name` —
         # it would post, and count as a member.
-        def reactive_select_all(group, **attrs)
-          mix({ data: { reactive_select_all: selection_group!(:reactive_select_all, group) } }, attrs)
+        #
+        # Nested groups (issue #398): under: "library.books" is a GROUP PATH.
+        # The header then owns only the boxes of the name whose
+        # data-reactive-group is that path or below it ("library.books.view"),
+        # so every leaf still posts under ONE name while a tree of headers
+        # ticks, unticks and goes indeterminate per branch. A header with no
+        # under: is the whole name, as before.
+        #
+        #   input(type: "checkbox", **reactive_select_all("perms[]"))                    # everything
+        #   input(type: "checkbox", **reactive_select_all("perms[]", under: "library"))  # a branch
+        #   input(type: "checkbox", name: "perms[]", value: "books", data: { reactive_group: "library" })
+        def reactive_select_all(group, under: nil, **attrs)
+          data = { reactive_select_all: selection_group!(:reactive_select_all, group) }
+          data[:reactive_select_all_under] = selection_path!(group, under) unless under.nil?
+          mix({ data: }, attrs)
         end
 
         # A text binding that shows how many owned boxes of the group are
@@ -176,6 +190,14 @@ module Phlex
           { "any" => Phlex::Reactive::ShowConditions.normalize(**conditions) }
         end
 
+        def selection_path!(group, under)
+          path = under.to_s
+          return path unless path.strip.empty? || path.split(".", -1).any? { it.empty? || it != it.strip }
+
+          raise ArgumentError, "reactive_select_all(#{group.to_s.inspect}) under: needs a group path like " \
+                               "\"library\" or \"library.books\" (no empty or space-padded segment), got #{under.inspect}"
+        end
+
         def selection_group!(helper, group)
           name = group.to_s
           return name unless name.strip.empty?

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # The reactive_show keywords beyond the condition itself.
+      #
+      # after: (issue #396) — keep the section hidden until the named field has
+      # fired `blur` once since connect. `after: :blur` names the condition's
+      # one field; a condition over several fields names it: `after: :code`.
+      # The client keeps the touched flag on the root's controller, so a morph
+      # keeps it and a full navigation (a new controller) drops it. The server
+      # cannot have seen a blur, so first paint is hidden.
+      #
+      # clear:, focus:, scroll: (issue #394) — work the client does when the
+      # section CHANGES visibility, never on first paint. Going hidden, each
+      # clear: field (owned, scope-aware) is emptied with js.set_value's write
+      # (a checkbox or radio is unchecked; a file input is rejected at render) and a bubbling
+      # `input` is dispatched per field that changed. Going visible, the first
+      # element inside the root matching focus: is focused, and scroll: true
+      # scrolls the section into view. clear: names are checked at render: an
+      # unknown one, or a file input, raises.
+      module ShowOptions
+        private
+
+        # The wire data for a reactive_show's options, merged into its data:.
+        def show_option_data(groups, after:, clear:, focus:, scroll:)
+          data = {}
+          data[:reactive_show_after] = show_after_field!(groups, after) unless after.nil?
+          data[:reactive_show_clear] = show_clear_fields!(clear).to_json unless clear.nil?
+          data[:reactive_show_focus] = show_focus!(focus) unless focus.nil?
+          data[:reactive_show_scroll] = "true" if show_scroll!(scroll)
+          data
+        end
+
+        def show_clear_fields!(clear)
+          names = Array(clear).map do
+            name = it.to_s if it.is_a?(Symbol) || it.is_a?(String)
+            next name unless name.nil? || name.strip.empty?
+
+            raise ArgumentError,
+              "reactive_show clear: takes a field name or an Array of them, got #{clear.inspect}"
+          end
+          raise ArgumentError, "reactive_show clear: needs at least one field name, got #{clear.inspect}" if names.empty?
+
+          reference_fields!(:reactive_show, :clear, names.uniq, no_file: true)
+          names.uniq
+        end
+
+        def show_focus!(focus)
+          return focus if focus.is_a?(String) && !focus.strip.empty?
+
+          raise ArgumentError,
+            "reactive_show focus: takes a non-empty CSS selector inside the root (e.g. \"#notes\"), got #{focus.inspect}"
+        end
+
+        def show_scroll!(scroll)
+          return scroll if [nil, true, false].include?(scroll)
+
+          raise ArgumentError, "reactive_show scroll: takes true or false, got #{scroll.inspect}"
+        end
+
+        def show_after_field!(groups, after)
+          fields = Phlex::Reactive::ShowConditions.fields(groups)
+          unless after.is_a?(Symbol) || after.is_a?(String)
+            raise ArgumentError,
+              "reactive_show after: takes :blur or the name of the condition's field to wait for, got #{after.inspect}"
+          end
+
+          name = after == :blur ? show_after_single!(fields) : after.to_s
+          unless fields.include?(name)
+            raise ArgumentError,
+              "reactive_show after: #{after.inspect} is not a field of this condition " \
+              "(it names #{fields.map(&:to_sym).inspect})"
+          end
+
+          reference_fields!(:reactive_show, :after, [name])
+          name
+        end
+
+        def show_after_single!(fields)
+          return fields.first if fields.size == 1
+
+          raise ArgumentError,
+            "reactive_show after: :blur needs a condition over one field — this one names " \
+            "#{fields.map(&:to_sym).inspect}; pass the field to wait for (after: #{fields.first.to_sym.inspect})"
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/engine.rb

@@ -20,10 +20,10 @@ module Phlex
       # build script (scripts/build_client.js), the core's own table and the
       # default entry name the same features —
       # spec/phlex/engine_client_pin_spec.rb fails when they disagree.
-      CLIENT_FEATURES = %w[persist defer form bindings compute sortable presence effects hints devtools].freeze
+      CLIENT_FEATURES = %w[persist defer form bindings compute sortable presence countdown effects hints devtools].freeze
       # (Gzipped, bun zlib level 9, KB = 1,024 B: the default file 30.9 KB; the core 14.3 KB;
       # persist 3.1, defer 2.9, form 1.1, bindings 6.5, compute 2.0, sortable
-      # 3.1, presence 1.3, effects 1.7, hints 0.9, devtools 1.5 KB. spec/javascript/bundle_budget.test.js
+      # 3.1, presence 1.3, countdown 0.9, effects 1.7, hints 0.9, devtools 1.5 KB. spec/javascript/bundle_budget.test.js
       # is the source of truth and holds a ratchet on each.)
 
       # Mount POST /reactive/actions -> Phlex::Reactive::ActionsController#create

data/lib/phlex/reactive/js.rb

@@ -193,6 +193,9 @@ module Phlex
       # focus(to)        — focus the FIRST match of the selector.
       # focus_first(to)  — focus the first FOCUSABLE DESCENDANT of the match
       #                    (e.g. focus the first menuitem inside an opened menu).
+      # blur(to)         — blur the focused element when it IS the match or sits
+      #                    inside it (issue #399): Escape ends a menu's
+      #                    :focus-within. Focus elsewhere is left alone.
 
       def focus(to, global: false)
         append("focus", target_args(to, global:))
@@ -202,6 +205,10 @@ module Phlex
         append("focus_first", target_args(to, global:))
       end
 
+      def blur(to, global: false)
+        append("blur", target_args(to, global:))
+      end
+
       # --- Modal dialogs (issue #365) ---
       #
       # show_modal(to)   — HTMLDialogElement#showModal(): the top layer, a
@@ -306,8 +313,24 @@ module Phlex
       #   op = js.preview_file("#photo-file", into: "#photo", valid: true)
       #   input(type: "file", id: "photo-file",
       #     **mix(on_client(:change, op), on_client("reactive:file-changed", op)))
-
-      def preview_file(to, into:, name: nil, global: false, valid: false)
+      #
+      # The box and the refusals (issue #391): `wrap:` is a CSS selector the
+      # client shows when it paints an image and hides when the preview clears
+      # (it shows again only a wrapper it hid itself, never one the author
+      # hid, and never writes its text). `max_bytes:` (a positive Integer)
+      # refuses a larger file before any object URL exists. `accept: true`
+      # reads the input's own accept attribute (extensions, MIME types,
+      # type/*); a String is that list for this op; omitted keeps the image/*
+      # rule. Only an image is painted: a listed non-image (a PDF) clears the
+      # preview and hides `wrap:`, unrefused. A refused file clears the img,
+      # hides `wrap:` and dispatches
+      # `reactive:file-rejected` on the input (detail.reason "type" | "size").
+      # The op never clears input.files nor sets a custom validity message.
+      #   input(type: "file", id: "photo-file", accept: "image/png,image/jpeg",
+      #     **on_client(:change, js.preview_file("#photo-file", into: "#photo",
+      #       wrap: "#photo-frame", max_bytes: 2_000_000, accept: true)))
+
+      def preview_file(to, into:, name: nil, global: false, valid: false, wrap: nil, max_bytes: nil, accept: nil)
         if [:root, ROOT_SENTINEL].include?(to)
           raise ArgumentError,
             "#{self.class}: preview_file reads a file input, not the component root — " \
@@ -318,6 +341,9 @@ module Phlex
         args["name"] = preview_selector(:name, name) unless name.nil?
         args["global"] = true if global
         args["valid"] = true if valid
+        args["wrap"] = preview_selector(:wrap, wrap) unless wrap.nil?
+        args["max_bytes"] = preview_max_bytes(max_bytes) unless max_bytes.nil?
+        args["accept"] = preview_accept(accept) unless accept.nil? || accept == false
         append("preview_file", args.freeze)
       end
 
@@ -527,6 +553,22 @@ module Phlex
           "#{self.class}: preview_file #{key}: must be a CSS selector string, got #{selector.inspect}"
       end
 
+      def preview_max_bytes(bytes)
+        return bytes if bytes.is_a?(Integer) && bytes.positive?
+
+        raise ArgumentError,
+          "#{self.class}: preview_file max_bytes: must be a positive Integer, got #{bytes.inspect}"
+      end
+
+      # true reads the input's accept attribute; a String is the list itself.
+      def preview_accept(accept)
+        return accept if accept == true || (accept.is_a?(String) && !accept.strip.empty?)
+
+        raise ArgumentError,
+          "#{self.class}: preview_file accept: must be true or an accept list " \
+          "(e.g. \"image/png,.jpg\"), got #{accept.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)