phlex-reactive 0.13.3 → 0.13.4

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

@@ -225,6 +225,16 @@ module Phlex
           "keydown.esc->reactive#listnavClose"
         ].freeze
 
+        # Roving-focus mode (issue #271): Enter/Space are the focused item's
+        # native activation and Escape is the caller's own on_client binding,
+        # so only the movement keys are bound.
+        LISTNAV_FOCUS_ACTIONS = [
+          "keydown.down->reactive#listnavNext",
+          "keydown.up->reactive#listnavPrev",
+          "keydown.home->reactive#listnavFirst",
+          "keydown.end->reactive#listnavLast"
+        ].freeze
+
         # Event modifiers (issue #80) — window:, once:, outside:, throttle: are
         # RESERVED keyword names on on() (no longer usable as free action params):
         #
@@ -376,6 +386,17 @@ module Phlex
         # Window-bound triggers are never preventDefault-ed by the client and skip
         # the forced type="button".
         #
+        # Issue #271: each call emits ONE self-describing binding record —
+        #   data-reactive-ops-param='{"on":"click","window":true,"outside":true,"ops":[…]}'
+        # carrying its own descriptor, flags and confirm, so several bindings on
+        # one element compose through mix: the data-action descriptors token-join,
+        # the records space-join (every literal space inside a record is written
+        # as \u0020, so the join is unambiguous), and the client runs only the
+        # record whose descriptor matches the firing event:
+        #   div(**mix(reactive_root,
+        #             on_client(:click, js.hide("#menu"), outside: true),
+        #             on_client("keydown.esc", js.hide("#menu"))))
+        #
         # 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
@@ -402,29 +423,21 @@ module Phlex
               "(change/input), or gate it behind a reducer's $ops / reactive_on_complete."
           end
           window_bound = window || outside
+          record = client_binding_record(event, ops, window_bound:, outside:, once:, confirm:)
           attrs = {
             data: {
               action: "#{event}#{"@window" if window_bound}->reactive#runOps#{":once" if once}",
-              reactive_ops_param: ops.to_json
+              # Space-free (issue #271): compact JSON has no structural
+              # whitespace, so every space is inside a string, where \u0020
+              # parses to the same string — and mix's space-join stays splittable.
+              reactive_ops_param: record.to_json.gsub(" ", '\u0020')
             }
           }
-          # STRING "true", not boolean — same Phlex valueless-attribute trap as
-          # on()'s flags above.
-          attrs[:data][:reactive_outside_param] = "true" if outside
-          attrs[:data][:reactive_window_param] = "true" if window_bound
           # Issue #228: mark a clipboard-reading trigger so the client can gate
           # its visibility on availability — on connect the controller sets
           # hidden = !navigator.clipboard.readText. Render the trigger `hidden`
           # for reveal-when-available (a dead paste button never shows).
           attrs[:data][:reactive_clipboard] = "true" if ops.ops.any? { |name, _| name == "paste_into" }
-          # Issue #178: confirm: gates the client-op chain behind the SAME
-          # overridable confirmResolver on(:action, confirm:) uses (#52/#55). Emits
-          # the identical data-reactive-confirm-param; the client's runOps prompts
-          # via confirmResolver BEFORE applying the ops (a falsy resolve cancels
-          # the chain), so a destructive client op gets the themed dialog with no
-          # round trip. Issue #179: a Hash confirm: is CONDITIONAL — same shared
-          # apply_confirm! branches String vs Hash for both on and on_client.
-          apply_confirm!(attrs[:data], confirm) if confirm
           attrs[:type] = "button" if event == "click" && !window_bound
           attrs
         end
@@ -678,13 +691,23 @@ module Phlex
         # Enter picks the highlighted one by clicking its own reactive trigger
         # (selection stays a signed action), Escape clears. Combine with other
         # attrs via mix so a caller's data-action token-joins, not clobbers.
-        def reactive_listnav(option_selector = "[role=option]")
-          {
-            data: {
-              action: LISTNAV_ACTIONS.join(" "),
-              reactive_listnav_option_param: filter_selector!(:selector, option_selector)
-            }
+        #
+        # `focus: true` (issue #271) is ROVING-FOCUS mode for a menu container:
+        # Arrow Down/Up move real focus among the items (wrapping), Home/End jump
+        # to the first/last; no highlight attr is written. The item selector
+        # defaults to [role=menuitem]. Enter/Space stay native activation and
+        # Escape is yours to bind (on_client("keydown.esc", ...) composes via mix):
+        #
+        #   ul(role: "menu", **mix(reactive_listnav(focus: true), data: { testid: "menu" }))
+        def reactive_listnav(option_selector = nil, focus: false)
+          option_selector ||= focus ? "[role=menuitem]" : "[role=option]"
+          data = {
+            action: (focus ? LISTNAV_FOCUS_ACTIONS : LISTNAV_ACTIONS).join(" "),
+            reactive_listnav_option_param: filter_selector!(:selector, option_selector)
           }
+          # STRING "true" — Phlex renders a boolean true as a valueless attribute.
+          data[:reactive_listnav_focus_param] = "true" if focus
+          { data: }
         end
 
         # Tag-chip input (issue #203) — the composed combobox/tags primitive.
@@ -1391,6 +1414,29 @@ module Phlex
         # Shared by on and on_client so both paths speak the same three forms. The
         # predicate is soft-validation UX, NOT authorization — a user can bypass it;
         # the action still hits the endpoint's real authorize/default-deny.
+        # One on_client binding record (issue #271). Flags and confirm live IN
+        # the record — never as element-wide params, which a sibling binding
+        # would inherit. Issue #178: confirm: gates the chain behind the SAME
+        # overridable confirmResolver on(:action, confirm:) uses (#52/#55); the
+        # client prompts BEFORE applying the ops. Issue #179: a Hash confirm: is
+        # CONDITIONAL, compiled by the shared compile_conditional_confirm.
+        def client_binding_record(event, ops, window_bound:, outside:, once:, confirm:)
+          record = { "on" => event }
+          record["window"] = true if window_bound
+          record["outside"] = true if outside
+          # A mix-ed regular sibling keeps calling runOps after Stimulus drops
+          # this binding's :once listener — the client skips a spent once record.
+          record["once"] = true if once
+          case confirm
+          when nil, false then nil
+          when String then record["confirm"] = confirm
+          when Hash then record["confirmWhen"] = compile_conditional_confirm(confirm)
+          else apply_confirm!({}, confirm) # raises the shared guided error
+          end
+          record["ops"] = ops.ops
+          record
+        end
+
         def apply_confirm!(data, confirm)
           case confirm
           when String

data/lib/phlex/reactive/engine.rb

@@ -112,6 +112,7 @@ module Phlex
       config.to_prepare do
         Phlex::Reactive::Streamable.reset_all_view_contexts!
         Phlex::Reactive.reset_stream_builder!
+        Phlex::Reactive::Pending::Markup.reset!
       end
 
       # Boot-time guard (issue #26): warn if the action path doesn't resolve to

data/lib/phlex/reactive/js.rb

@@ -110,17 +110,25 @@ module Phlex
       # the next frame `from`→`to` swaps, and the whole set is awaited via
       # `animationend` (with a setTimeout fallback so a non-animated element never
       # hangs the op chain). Omit it for the instant flip.
-
-      def show(to, global: false, transition: nil)
-        append("show", target_args(to, global:, transition:))
+      #
+      # `expanded:` (issue #271) — a disclosure trigger to keep honest: the
+      # client sets its aria-expanded from the op's INTENDED state (show →
+      # "true", hide → "false", toggle → the pre-flip hidden state), before any
+      # transition runs. Resolved with the op's own scoping (`:root` or a
+      # selector, document-wide under global: true). Pair it with ONE disclosure
+      # target — with several, the last one wins.
+      #   js.toggle("#menu", expanded: "#menu-trigger")
+
+      def show(to, global: false, transition: nil, expanded: nil)
+        append("show", target_args(to, global:, transition:, expanded:))
       end
 
-      def hide(to, global: false, transition: nil)
-        append("hide", target_args(to, global:, transition:))
+      def hide(to, global: false, transition: nil, expanded: nil)
+        append("hide", target_args(to, global:, transition:, expanded:))
       end
 
-      def toggle(to, global: false, transition: nil)
-        append("toggle", target_args(to, global:, transition:))
+      def toggle(to, global: false, transition: nil, expanded: nil)
+        append("toggle", target_args(to, global:, transition:, expanded:))
       end
 
       # --- Classes ---
@@ -143,6 +151,11 @@ module Phlex
       # The value is stringified (a Phlex-style flag rides as the string "true",
       # never a valueless attribute). The name is checked against the allowlist at
       # build time — an event-handler, URL-bearing, or style name raises here.
+      #
+      # toggle_attr(to, name, on, off) (issue #271) flips BETWEEN two values
+      # instead of toggling presence — current == on ? off : on, so an absent
+      # 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:))
@@ -152,8 +165,11 @@ module Phlex
         append("remove_attr", attr_args(to, name, global:))
       end
 
-      def toggle_attr(to, name, global: false)
-        append("toggle_attr", attr_args(to, name, global:))
+      def toggle_attr(to, name, *values, global: false)
+        args = attr_args(to, name, global:)
+        return append("toggle_attr", args) if values.empty?
+
+        append("toggle_attr", args.merge("values" => toggle_values(name, values)).freeze)
       end
 
       # --- Focus (issue #96) ---
@@ -290,13 +306,31 @@ module Phlex
         self.class.new([*@ops, [name, args].freeze].freeze)
       end
 
-      def target_args(to, global:, transition: nil)
+      def target_args(to, global:, transition: nil, expanded: nil)
         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?
         args.freeze
       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)
+        unless values.size == 2
+          raise ArgumentError,
+            "#{self.class}: toggle_attr(#{name.to_s.inspect}) takes no values (presence toggle) " \
+            "or two values to flip between, got #{values.size}: #{values.inspect}"
+        end
+
+        on, off = values.map(&:to_s)
+        if on == off
+          raise ArgumentError, "#{self.class}: toggle_attr(#{name.to_s.inspect}) values must differ, got #{on.inspect} twice"
+        end
+
+        [on, off].freeze
+      end
+
       # 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)

data/lib/phlex/reactive/pending/markup.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Pending
+      # The opt-in pending MARKUP hook (issue #249). The #248 markers dim a live
+      # row; some apps want the pending state to be honest markup instead — a
+      # real "Queued" badge, a button that is genuinely gone. A row component
+      # opts in by defining `pending_template` (private is fine), and
+      # reply.pending then ALSO replaces the row with that markup:
+      #
+      #   class TransferRow < ApplicationComponent
+      #     def view_template = li(id:, **reactive_attrs) { ...; button(**on(:retry)) { "Retry" } }
+      #
+      #     private
+      #
+      #     def pending_template = li(id:, **reactive_attrs) { ...; span(class: "badge") { "Queued" } }
+      #   end
+      #
+      # It is a TEMPLATE method, not a content method like `deferred_placeholder`
+      # (#165): there the gem owns the shell div and the component supplies what
+      # goes inside; here the row's own root is swapped, so the hook renders it.
+      #
+      # ## Why a subclass
+      #
+      # Phlex 2 compiles templates per class, so the swap cannot be a per-instance
+      # method. Each opted-in row class gets ONE memoized anonymous subclass whose
+      # view_template is the pending template. Two contracts make that safe:
+      #
+      #   * The variant's `.name` is the PARENT's. A row that includes Component
+      #     signs its class name into its token; an anonymous name cannot
+      #     constantize, so the row's next action would 400.
+      #   * The memo holds classes derived from reloadable ones, so the engine
+      #     resets it on Rails code reload (config.to_prepare), exactly like the
+      #     view-context and stream-builder memos.
+      #
+      # ## Un-pending is the settle's job
+      #
+      # The markers are attributes, so any settle can strip them. Swapped markup
+      # is not: only a settle that REPLACES or REMOVES the row puts it back. A
+      # flash-only settle, `finish: true` or a failed job clears the markers but
+      # leaves the pending markup in place.
+      module Markup
+        HOOK = :pending_template
+
+        # The root start tag of the rendered markup, walked quote-aware: Phlex
+        # double-quotes every attribute value and leaves `>` raw inside it
+        # (`data-action="click->reactive#dispatch"`), so the tag must not end at
+        # the first `>`.
+        ROOT_TAG = %r{\A\s*<[^\s>/]+(?:\s+[^\s=>/]+(?:="[^"]*")?)*}
+
+        # Keyed weakly on the row class, so a class Zeitwerk replaced is not
+        # pinned between resets. A WeakKeyMap, not a WeakMap: nothing else holds
+        # the variant, so a weak VALUE would let GC drop the memo.
+        @variants = ObjectSpace::WeakKeyMap.new
+        @mutex = Mutex.new
+
+        class << self
+          # The row's pending markup as HTML, or nil when the row has no hook
+          # (or the target is a bare DOM id String — there is no component to
+          # render). Rendered through the PARENT's render_component: the variant
+          # is never registered with Streamable, so this reuses the parent's
+          # memoized, reload-reset view context and its instrumentation name.
+          def render(row)
+            return nil unless row.is_a?(Phlex::Reactive::Streamable) && row.respond_to?(HOOK, true)
+
+            html = row.class.render_component(variant_instance(row))
+            assert_keeps_id!(row, html)
+            html
+          end
+
+          # The replace stream that swaps one row to its pending markup.
+          def stream(target_id, html)
+            Phlex::Reactive::Stream.wrap(
+              Phlex::Reactive.stream_builder.replace(target_id, html: html.html_safe),
+              action: "replace", target: target_id, renders_root: true
+            )
+          end
+
+          def variant_for(row_class)
+            @mutex.synchronize { @variants[row_class] ||= build_variant(row_class) }
+          end
+
+          # Called from the engine's config.to_prepare (Rails code reload).
+          def reset!
+            @mutex.synchronize { @variants = ObjectSpace::WeakKeyMap.new }
+          end
+
+          private
+
+          def build_variant(row_class)
+            Class.new(row_class) do
+              def self.name = superclass.name
+              def self.inspect = "#{superclass.name}(pending)"
+              def self.to_s = inspect
+
+              def view_template = pending_template
+            end
+          end
+
+          # A variant instance carrying the built row's state. allocate + copy
+          # rather than re-running initialize: the row may have been handed to
+          # reply.pending already built, with arguments the gem never saw.
+          def variant_instance(row)
+            variant = variant_for(row.class).allocate
+            row.instance_variables.each { variant.instance_variable_set(it, row.instance_variable_get(it)) }
+            variant
+          end
+
+          # A pending template that drops the row's id leaves the settle nothing
+          # to target: its replace/remove would miss and the row would say
+          # "Queued" forever. Fail at the action, before anything is enqueued.
+          # Only the ROOT start tag counts — the id on a data- attribute or a
+          # nested child is not a target the settle can swap (see ROOT_TAG).
+          def assert_keeps_id!(row, html)
+            root_tag = html[ROOT_TAG].to_s
+            return if root_tag.match?(/\sid="#{Regexp.escape(ERB::Util.html_escape(row.id))}"/)
+
+            raise Phlex::Reactive::Error,
+              "#{row.class.name}#pending_template must render the row's root with its id " \
+              "(id=\"#{row.id}\") — the settle targets that id to replace or remove the row. " \
+              "Render the root as in view_template, e.g. li(id:, **reactive_attrs) { ... }."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/pending.rb

@@ -92,8 +92,10 @@ module Phlex
       end
 
       # One recorded pending segment: the handle plus the DOM ids that were
-      # marked pending (the endpoint emits one marker stream per id).
-      Segment = Data.define(:handle, :target_ids)
+      # marked pending (the endpoint emits one marker stream per id), and — in
+      # step with target_ids — each row's pending markup (issue #249), nil for
+      # a row without the pending_template hook.
+      Segment = Data.define(:handle, :target_ids, :markup)
 
       # The attribute apps style. Set alongside aria-busy on every pending
       # target AND on the container, so one CSS rule covers both:
@@ -126,7 +128,8 @@ module Phlex
           # or re-queries, so a concurrent write could make the marked rows and
           # the enqueued jobs disagree.
           list = materialize(records)
-          targets = resolve_targets(container, list, collection)
+          rows = resolve_rows(container, list, collection)
+          targets = rows.map { it.is_a?(String) ? it : it.id }
 
           unless Phlex::Reactive.settle_capable?
             warn_no_lane
@@ -134,9 +137,12 @@ module Phlex
             return nil
           end
 
+          # Rendered BEFORE the enqueue, so a broken pending_template fails the
+          # action (and rolls it back) before any job exists.
+          markup = rows.map { Markup.render(it) }
           handle = build_handle(container, collection, targets, peers)
           with_handle(handle) { run_enqueue(list, job, args, enqueue, targets) }
-          Segment.new(handle:, target_ids: targets)
+          Segment.new(handle:, target_ids: targets, markup:)
         end
 
         # One record, or an enumerable of them, as an Array — never re-walked.
@@ -149,9 +155,13 @@ module Phlex
 
         # The wire streams for one segment, in apply order: the per-target
         # pending markers FIRST (so the UI stops lying immediately), then the
-        # single subscription directive.
+        # single subscription directive. A row with pending markup is replaced
+        # just before its marker, so the marker lands on the swapped node.
         def streams_for(segment)
-          streams = segment.target_ids.map { marker_stream(it) }
+          streams = segment.target_ids.each_with_index.flat_map do |id, index|
+            html = segment.markup[index]
+            html ? [Markup.stream(id, html), marker_stream(id)] : [marker_stream(id)]
+          end
           streams << marker_stream(segment.handle.anchor)
           streams << directive_stream(segment.handle)
           streams
@@ -162,24 +172,18 @@ module Phlex
         # exact id to tear the subscription down.
         def source_id(anchor) = "reactive-defer-src-#{anchor}"
 
-        # Resolve the DOM id a row component would render for `model`, WITHOUT
-        # rendering it (build is cheap — #id must be render-context-free, that
-        # is the Streamable#id contract).
-        def row_dom_id(definition, model)
-          return model if model.is_a?(String)
-
-          definition.item.send(:build, model, {}).id
-        end
-
         private
 
-        # Each pending target, as a DOM id. With `in:` the rows resolve through
-        # the collection declaration; without it every entry must already be a
-        # Streamable component (its own #id is the target).
-        def resolve_targets(container, list, collection)
+        # Each pending target, as a row component (its #id is the target, and
+        # it renders the pending markup when it has the hook) or a bare DOM id
+        # String. With `in:` the rows resolve through the collection declaration
+        # (build is cheap — #id must be render-context-free, the Streamable#id
+        # contract); without it every entry must already be a Streamable
+        # component.
+        def resolve_rows(container, list, collection)
           if collection
             definition = Phlex::Reactive::Collections.definition!(container, collection)
-            return list.map { row_dom_id(definition, it) }
+            return list.map { it.is_a?(String) ? it : definition.item.send(:build, it, {}) }
           end
 
           list.map do
@@ -190,7 +194,7 @@ module Phlex
                 "Streamable component instance (its #id is the target)"
             end
 
-            it.id
+            it
           end
         end
 

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.13.3"
+    VERSION = "0.13.4"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.13.3
+  version: 0.13.4
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -180,6 +180,7 @@ files:
 - lib/phlex/reactive/mcp/tools/find_tool.rb
 - lib/phlex/reactive/param_schema.rb
 - lib/phlex/reactive/pending.rb
+- lib/phlex/reactive/pending/markup.rb
 - lib/phlex/reactive/reply.rb
 - lib/phlex/reactive/response.rb
 - lib/phlex/reactive/settle.rb