phlex-reactive 0.9.3 → 0.9.5

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

@@ -28,6 +28,23 @@ module Phlex
           Phlex::Reactive.current_connection_id
         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
+        # Phlex::Reactive.authorization_methods:
+        #
+        #   def publish
+        #     raise NotAllowed unless @post.author == Current.user
+        #     mark_authorized!
+        #     @post.update!(published: true)
+        #   end
+        #
+        # Call it only AFTER your check passes — it asserts "I have authorized
+        # this action." A no-op when verify_authorized is off.
+        def mark_authorized!
+          Phlex::Reactive::Authorization.mark!
+        end
+
         # Subject-bound reply builder — the preferred way to control an action's
         # reply. `reply.replace.flash(:error, msg)` reads cleaner than
         # `Phlex::Reactive::Response.replace(self).flash(:error, msg)`: the
@@ -424,27 +441,152 @@ module Phlex
         # after a morph; render the initial `hidden:` yourself (from the same
         # server state that renders the field) to avoid a first-paint flash.
         # Extra attrs deep-merge over the binding (mix), like reactive_field.
-        def reactive_show(field, **options)
-          predicates = options.slice(*SHOW_PREDICATE_KEYS)
-          attrs = options.except(*SHOW_PREDICATE_KEYS)
-          unless predicates.size == 1
+        # Compound forms (issue #176 part A) — visibility that depends on MORE
+        # THAN ONE field, or a threshold, staying inside the eval-free literal
+        # contract. `all:`/`any:` fold a list of per-field terms (each the same
+        # equals:/not:/in:/gte:/gt:/lte:/lt: vocabulary) with one fixed
+        # connective; the compound has no single controlling field, so it
+        # serializes as ONE JSON attr (data-reactive-show) like
+        # reactive_show_targets rather than the flat data-reactive-show-* attrs:
+        #
+        #   # visible while type == "individual" AND country != "domestic"
+        #   div(**reactive_show(all: [
+        #     { field: :type,    equals: "individual" },
+        #     { field: :country, not:    "domestic" }
+        #   ]))
+        #   # visible while director OR shareholder is checked
+        #   div(**reactive_show(any: [
+        #     { field: :director,    equals: true },
+        #     { field: :shareholder, equals: true }
+        #   ]))
+        #   # a numeric threshold, single field or as a compound term
+        #   div(**reactive_show(:quantity, gte: 10))            # visible while qty >= 10
+        #   div(**reactive_show(all: [{ field: :amount, gte: 5000 }, ...]))
+        #
+        # `all:`/`any:` are additive and mutually exclusive with the single-field
+        # form and with each other — enforced loudly at render, like the
+        # one-predicate rule. A single-field `all:` with one term degrades to the
+        # flat form's behaviour client-side.
+        def reactive_show(field = nil, **options)
+          connectives = options.slice(*SHOW_CONNECTIVE_KEYS)
+          return reactive_show_compound(field, connectives, options) if connectives.any?
+
+          reactive_show_single(field, options)
+        end
+
+        # Client-side option filtering for the searchable combobox (issue #163)
+        # — the "preload + type to narrow" half of #72's keyboard nav, entirely
+        # client-side. Spread onto the ROOT (mix with reactive_root); it names
+        # the input whose value drives the filter and the option elements to
+        # show/hide, and the generic controller toggles `hidden` on every
+        # keystroke by substring-matching each option's haystack — no round
+        # trip, no token, no bespoke per-feature controller:
+        #
+        #   div(**mix(reactive_root, reactive_filter(
+        #     input:  "#exercise-search",
+        #     option: "[role=option]",
+        #     group:  "[data-filter-group]",   # optional: collapse empty group headers
+        #     empty:  "#no-matches"            # optional: reveal when 0 match
+        #   ))) { … }
+        #
+        # Each option's haystack is its `data-reactive-filter-text` attribute
+        # (server-rendered — pack in synonyms/categories), falling back to the
+        # option's own text. Matching is a case-folded substring test — a
+        # DECLARED literal match, never an expression (no eval surface, the
+        # reactive_show posture). `group:` hides any group element whose every
+        # contained option is hidden; `empty:` reveals the no-matches node when
+        # 0 options are visible. The client seeds at connect and re-syncs after
+        # a morph; selectors resolve WITHIN this root only (#15 ownership).
+        #
+        # Filtering composes with reactive_listnav (Arrow/Enter/Escape skip
+        # hidden options) and each option's own on(:select, …) trigger —
+        # selection still round-trips as a signed action; only FILTERING is
+        # local. Blank selectors raise: a dead binding must fail at render.
+        def reactive_filter(input:, option:, group: nil, empty: nil)
+          data = {
+            reactive_filter_input: filter_selector!(:input, input),
+            reactive_filter_option: filter_selector!(:option, option)
+          }
+          data[:reactive_filter_group] = filter_selector!(:group, group) if group
+          data[:reactive_filter_empty] = filter_selector!(:empty, empty) if empty
+
+          { data: }
+        end
+
+        # STANDALONE combobox keyboard navigation (issue #163) — the same
+        # Arrow/Enter/Escape wiring `on(…, listnav:)` appends, without the
+        # dispatch descriptor. A preload-and-filter combobox input fires NO
+        # action (filtering is pure client), so it can't carry on(); spread
+        # this onto the input instead:
+        #
+        #   input(id: "search", type: "search", **reactive_listnav("[role=option]"))
+        #
+        # Arrow keys move the client-side highlight among the (visible) options,
+        # 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)
+          {
+            data: {
+              action: LISTNAV_ACTIONS.join(" "),
+              reactive_listnav_option_param: filter_selector!(:selector, option_selector)
+            }
+          }
+        end
+
+        # CROSS-ROOT value-conditional visibility (issue #164) — the visibility
+        # parallel to reactive_compute's `mirror:` (#159). A plain reactive_show
+        # is root-scoped by design (#15), so it can't express "this control
+        # drives elements ELSEWHERE on the page" — a nav tab, a panel in another
+        # tab pane, a sidebar note. reactive_show_targets is the declared,
+        # id-allowlisted escape: the component that OWNS the field declares
+        # which outside ids it governs. Spread it on the ROOT (mix alongside
+        # reactive_root — the client reads it off the controller element):
+        #
+        #   div(**mix(reactive_root, reactive_show_targets(:mode,
+        #     "#advanced-tab"   => { equals: "advanced" },
+        #     "#advanced-panel" => { equals: "advanced" },
+        #     "#basic-note"     => { not: "advanced" })))
+        #
+        # Same posture as mirror: — opt-in and declared, never implicit (a plain
+        # reactive_show stays root-isolated); targets are SINGLE ID SELECTORS
+        # only, enforced here at declare time AND warn-and-skipped by the client
+        # interpreter (two-sided default-deny); the predicate is the same
+        # literal-only reactive_show vocabulary (exactly one of equals:/not:/
+        # in:, no expressions); and the toggle is `hidden` only — no innerHTML,
+        # no attribute freedom. The FIELD read stays owned (#15): you can only
+        # drive outside visibility from a field this root owns. A target id not
+        # on the page is silently skipped (an unrendered tab pane is normal).
+        #
+        # ONE call per root. Phlex `mix` space-joins duplicate STRING data
+        # values, so a second call's JSON would concatenate into an unparseable
+        # attr and the client would drop BOTH maps (it warns when that
+        # happens). Several fields therefore go in ONE call via the hash form:
+        #
+        #   reactive_show_targets(mode: { "#advanced-tab" => { equals: "advanced" } },
+        #                         kind: { "#premium-note" => { not: "basic" } })
+        def reactive_show_targets(field, targets = nil)
+          field_maps = targets.nil? ? field : { field => targets }
+          unless field_maps.is_a?(Hash) && field_maps.any?
             raise ArgumentError,
-              "reactive_show(#{field.inspect}) needs exactly one predicate — equals:, not:, or " \
-              "in: — got #{predicates.keys.inspect}"
+              "reactive_show_targets needs at least one target " \
+              "(:field, \"#id\" => { equals:/not:/in: ... }), got #{field_maps.inspect}"
           end
 
-          key, value = predicates.first
-          data = { reactive_show_field: field.to_s }
-          if key == :in
-            list = Array(value).map(&:to_s)
-            raise ArgumentError, "reactive_show(#{field.inspect}) in: needs at least one value" if list.empty?
+          normalized = field_maps.to_h do |name, map|
+            # Catch the forgotten-field-name misuse — reactive_show_targets(
+            # "#id" => {…}) — before the per-target validation turns it into a
+            # baffling "predicate" error.
+            if name.to_s.start_with?("#")
+              raise ArgumentError,
+                "reactive_show_targets: #{name.inspect} looks like a target selector, not a field " \
+                "name — call reactive_show_targets(:field, #{name.inspect} => { ... })"
+            end
 
-            data[:reactive_show_in] = list.to_json
-          else
-            data[:"reactive_show_#{key}"] = value.to_s
+            [name.to_s, normalize_show_target_map(name, map)]
           end
 
-          mix({ data: }, attrs)
+          { data: { reactive_show_targets: normalized.to_json } }
         end
 
         # Scoped busy indicator (issue #99). Marks an element so the generic
@@ -533,12 +675,33 @@ module Phlex
           reactive_record_for_nested.update!(**nested_attributes(association, attrs), **extra)
         end
 
-        # The declared reactive_show predicates (issue #161): a literal match on
-        # the controlling field's current value. Exactly one per binding —
-        # enforced loudly at render (a dead binding must not no-op in the
-        # browser). `not`/`in` are Ruby keywords, so they arrive via **options
-        # rather than named kwargs.
-        SHOW_PREDICATE_KEYS = %i[equals not in].freeze
+        # The declared reactive_show predicates: a literal match on the
+        # controlling field's current value. Exactly one per binding — enforced
+        # loudly at render (a dead binding must not no-op in the browser).
+        # `not`/`in` are Ruby keywords, so they arrive via **options rather than
+        # named kwargs. Issue #161 shipped the string-literal trio; issue #176
+        # adds the numeric-threshold quartet below.
+        SHOW_LITERAL_KEYS = %i[equals not in].freeze
+
+        # The numeric-threshold predicates (issue #176 part B): gte/gt/lte/lt
+        # compare the field value coerced to a Number against a literal number.
+        # Still a declared literal — the RHS is a number baked into the
+        # attribute, never an expression — the only new capability is ordered
+        # comparison. The RHS must be an actual Numeric in Ruby (stricter, so a
+        # typo like gte: "10" fails at render, not silently in the browser).
+        SHOW_NUMERIC_KEYS = %i[gte gt lte lt].freeze
+
+        # Every predicate key a reactive_show / reactive_show_targets binding may
+        # declare — the literal trio plus the numeric quartet. Exactly one of
+        # these decides a single binding; a compound term declares one too.
+        SHOW_PREDICATE_KEYS = (SHOW_LITERAL_KEYS + SHOW_NUMERIC_KEYS).freeze
+
+        # The compound connectives (issue #176 part A): fold a list of per-field
+        # literal/numeric terms with ONE fixed keyword. Not an expression surface
+        # — the connective is one of two fixed keywords, each term is the same
+        # declared predicate vocabulary. Mutually exclusive with a single field
+        # and with each other (enforced loudly at render).
+        SHOW_CONNECTIVE_KEYS = %i[all any].freeze
 
         # The declared optimistic-hint class ops (issue #98): the cosmetic class
         # vocabulary the client applies instantly and reverts on failure. Enforced
@@ -549,6 +712,170 @@ module Phlex
 
         private
 
+        # A reactive_filter/reactive_listnav selector, validated non-blank and
+        # stringified (issue #163). A blank selector is a dead binding — the
+        # client would silently match nothing — so it fails loudly at render,
+        # like reactive_show's predicate validation.
+        def filter_selector!(name, value)
+          selector = value.to_s
+          if selector.strip.empty?
+            raise ArgumentError,
+              "reactive_filter/reactive_listnav #{name}: needs a CSS selector, got #{value.inspect}"
+          end
+
+          selector
+        end
+
+        # Normalize + validate ONE field's target map (issue #164): each key a
+        # single id selector (loud raise — the declare-time half of the
+        # two-sided default-deny), each value one literal predicate. Shared by
+        # both reactive_show_targets call forms.
+        def normalize_show_target_map(field, targets)
+          unless targets.is_a?(Hash) && targets.any?
+            raise ArgumentError,
+              "reactive_show_targets(#{field.inspect}) needs at least one target " \
+              "(\"#id\" => { equals:/not:/in: ... }), got #{targets.inspect}"
+          end
+
+          targets.to_h do |selector, predicate|
+            selector = selector.to_s
+            unless selector.match?(DSL::MIRROR_ID_SELECTOR)
+              raise ArgumentError,
+                "reactive_show_targets(#{field.inspect}) target #{selector.inspect} must be a single " \
+                "ID selector (\"#id\") — cross-root visibility is id-allowlisted, like mirror: (#159)"
+            end
+
+            context = "reactive_show_targets(#{field.inspect}) target #{selector.inspect}"
+            [selector, normalize_show_predicate(predicate.is_a?(Hash) ? predicate : {}, context)]
+          end
+        end
+
+        # Validate ONE declared show predicate (issues #161/#164/#176) and
+        # return its wire form — { "equals" => "v" } / { "not" => "v" } /
+        # { "in" => ["a", …] } / { "gte" => 10 } (a numeric RHS stays a real
+        # Number so the wire carries a JSON number, not a string). reactive_show
+        # JSON-encodes an in: array into its own attr; the reactive_show_targets
+        # map and a compound term embed the predicate directly. Shared by every
+        # helper so the vocabulary and the loud validation can never drift.
+        # `context` names the call site in the error.
+        def normalize_show_predicate(predicates, context)
+          unless predicates.size == 1 && SHOW_PREDICATE_KEYS.include?(predicates.keys.first)
+            raise ArgumentError,
+              "#{context} needs exactly one predicate — equals:, not:, in:, or " \
+              "gte:/gt:/lte:/lt: — got #{predicates.keys.inspect}"
+          end
+
+          key, value = predicates.first
+          return normalize_show_numeric(key, value, context) if SHOW_NUMERIC_KEYS.include?(key)
+          return { key.to_s => value.to_s } unless key == :in
+
+          list = Array(value).map(&:to_s)
+          raise ArgumentError, "#{context} in: needs at least one value" if list.empty?
+
+          { "in" => list }
+        end
+
+        # Validate a numeric threshold predicate (issue #176 part B): the RHS
+        # must be an actual Numeric (a String "10" is a typo caught here, not a
+        # silent NaN in the browser). It rides the wire as a JSON number so the
+        # client compares Number(value) against it directly.
+        def normalize_show_numeric(key, value, context)
+          unless value.is_a?(Numeric)
+            raise ArgumentError,
+              "#{context} #{key}: needs a number (an ordered comparison against a literal), " \
+              "got #{value.inspect}"
+          end
+
+          { key.to_s => value }
+        end
+
+        # The single-field reactive_show form (issue #161, extended for numeric
+        # thresholds in #176): one owned field + one predicate → flat
+        # data-reactive-show-* attrs. An in: list JSON-encodes into its own attr;
+        # a numeric threshold or a literal stringifies into the flat attr and the
+        # client Number()-coerces the numeric case back on read.
+        def reactive_show_single(field, options)
+          if field.nil?
+            raise ArgumentError,
+              "reactive_show needs a field (reactive_show(:mode, equals: …)) or a compound " \
+              "connective (reactive_show(all: [...]) / any:) — got neither"
+          end
+
+          predicates = options.slice(*SHOW_PREDICATE_KEYS)
+          attrs = options.except(*SHOW_PREDICATE_KEYS)
+          unless predicates.size == 1
+            raise ArgumentError,
+              "reactive_show(#{field.inspect}) needs exactly one predicate — equals:, not:, in:, " \
+              "or gte:/gt:/lte:/lt: — got #{predicates.keys.inspect}"
+          end
+
+          key, value = normalize_show_predicate(predicates, "reactive_show(#{field.inspect})").first
+          data = { reactive_show_field: field.to_s }
+          # in: → JSON array; a numeric threshold or a literal → the value as-is.
+          # Phlex stringifies it into the flat attr; the client re-reads via
+          # getAttribute (always a string) and Number()-coerces the numeric case.
+          data[:"reactive_show_#{key}"] = key == "in" ? value.to_json : value.to_s
+
+          mix({ data: }, attrs)
+        end
+
+        # The compound reactive_show form (issue #176 part A): `all:`/`any:` fold
+        # a list of per-field terms with one fixed connective, serialized as one
+        # JSON attr (data-reactive-show). A field alongside a connective, or two
+        # connectives, is a contradiction — raise. Each term is validated through
+        # the SAME predicate normalizer, so a term's vocabulary never drifts from
+        # the single-field form.
+        def reactive_show_compound(field, connectives, options)
+          unless field.nil?
+            raise ArgumentError,
+              "reactive_show got a field AND all:/any: — the compound and single-field forms are " \
+              "mutually exclusive; use one flat binding OR a compound list, not both"
+          end
+          unless connectives.size == 1
+            raise ArgumentError,
+              "reactive_show needs exactly one of all:/any: (one fixed connective), " \
+              "got #{connectives.keys.inspect}"
+          end
+
+          connective, terms = connectives.first
+          # A top-level predicate alongside a connective (reactive_show(all: [...],
+          # equals: "x")) is a misuse — predicates belong INSIDE terms. Catch it
+          # loudly at render rather than leaking `equals="x"` as a bogus HTML attr
+          # (the mix at the tail treats every leftover kwarg as a literal
+          # attribute). Same default-deny posture as the single-field path.
+          if (stray = options.slice(*SHOW_PREDICATE_KEYS)).any?
+            raise ArgumentError,
+              "reactive_show #{connective}: got a top-level predicate #{stray.keys.inspect} — " \
+              "predicates belong INSIDE each term ({ field: …, #{stray.keys.first}: … }), not beside the connective"
+          end
+
+          attrs = options.except(*SHOW_CONNECTIVE_KEYS)
+          unless terms.is_a?(Array) && terms.any?
+            raise ArgumentError,
+              "reactive_show #{connective}: needs at least one term " \
+              "({ field: …, equals:/not:/in:/gte:/… }), got #{terms.inspect}"
+          end
+
+          normalized = terms.map { normalize_show_term(connective, it) }
+          mix({ data: { reactive_show: { connective.to_s => normalized }.to_json } }, attrs)
+        end
+
+        # Normalize + validate ONE compound term (issue #176 part A): a Hash with
+        # a :field and exactly one predicate. The predicate goes through the
+        # shared normalizer; the field is stringified into the term. Returns
+        # { "field" => name, <predicate> } so the wire is uniform with the
+        # reactive_show_targets embedded-predicate shape.
+        def normalize_show_term(connective, term)
+          context = "reactive_show #{connective}: term"
+          unless term.is_a?(Hash) && term.key?(:field)
+            raise ArgumentError, "#{context} — each term needs a field (got #{term.inspect})"
+          end
+
+          field = term[:field]
+          predicate = normalize_show_predicate(term.except(:field), "#{context} (field #{field.inspect})")
+          { "field" => field.to_s }.merge(predicate)
+        end
+
         # True when the hint declares checked: :keep — the click-bound
         # checkbox/radio case that must SKIP the forced type="button" so the native
         # control (and its native flip) survives (issue #98). Accepts symbol or

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

@@ -55,6 +55,15 @@ module Phlex
         # declared, the token carries just {c} — enough to mount, but with no
         # identity to round-trip, so declare reactive_state for a draft you sync.
         def reactive_token
+          Phlex::Reactive.sign(reactive_identity_payload)
+        end
+
+        # The UNSIGNED identity payload — extracted from reactive_token (issue
+        # #165) so the defer machinery mints its purpose-scoped defer tokens
+        # from the exact same shape and the two token families can never drift.
+        # Still THE hot path (reactive_token calls it on every render); the
+        # split adds one method dispatch, verified flat by the token bench.
+        def reactive_identity_payload
           klass = self.class
           payload = { "c" => klass.name }
 
@@ -75,7 +84,7 @@ module Phlex
             payload["s"] = state
           end
 
-          Phlex::Reactive.sign(payload)
+          payload
         end
 
         # A record's gid is signable unless it is an unsaved AR-like draft

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # Lazy initial mount (issue #165): a `reactive_lazy` component's FIRST
+      # (page-embedded) render emits a placeholder SHELL — the root id, the
+      # generic controller, the pending markers, and a defer token ON the root
+      # — and the client fetches the real content through the same defer
+      # machinery on connect (the Livewire #[Lazy] shape).
+      #
+      # Lazy applies ONLY to the initial mount. Every render that goes through
+      # the reactive machinery — an action reply's self-replace, a broadcast,
+      # the defer endpoint/job, the class stream builders — runs inside
+      # Defer.with_real_render, so it renders the REAL template. Anything else
+      # would make an action on a lazy component cost two round trips.
+      module Lazy
+        extend ActiveSupport::Concern
+
+        private
+
+        # Phlex 2's render hook: the template runs inside the block. Overridden
+        # (not yield-then-decorate) so the lazy shell can REPLACE the template
+        # entirely on the initial mount. A component's own around_template
+        # override composes via normal method lookup as long as it calls super.
+        def around_template(&)
+          klass = self.class
+          if klass.respond_to?(:reactive_lazy?) && klass.reactive_lazy? && !Phlex::Reactive::Defer.real_render?
+            render_defer_shell
+          else
+            super
+          end
+        end
+
+        # The shell: owns the component's id (the arrival replaces it by that
+        # id), mounts the generic controller, and carries the defer token as a
+        # ROOT attribute — the controller's connect() probes it and enters the
+        # same module-level fetch path a reply directive uses. Pending markers
+        # + the .reactive-defer-placeholder class are the CSS hooks.
+        def render_defer_shell
+          public_send(
+            self.class.reactive_lazy_tag,
+            id:,
+            class: "reactive-defer-placeholder",
+            aria: { busy: "true" },
+            data: {
+              controller: "reactive",
+              reactive_defer_pending: "true",
+              # UNBOUND (issue #165 security): a lazy shell renders during the
+              # page render — on a fresh visit the session doesn't exist yet, so
+              # the token can't be actor-bound (it would 400 at the endpoint,
+              # which by then IS bound). It lives in the actor's own page (a
+              # small leak surface); the TTL + `authorize!` are its bound. Only
+              # reply.defer tokens (in action responses that can transit proxies)
+              # are actor-bound.
+              reactive_defer_token: Phlex::Reactive.sign_defer(reactive_identity_payload, unbound: true)
+            }
+          ) { render_deferred_placeholder_content }
+        end
+
+        # Same content contract as reply.defer's placeholder: true — the
+        # component's deferred_placeholder returns a Phlex component instance
+        # (rendered), an html_safe String (raw), or a plain String (escaped
+        # text — data, not markup). No method / nil → the empty shell.
+        def render_deferred_placeholder_content
+          return unless respond_to?(:deferred_placeholder, true)
+
+          value = send(:deferred_placeholder)
+          case value
+          when nil then nil
+          when ::Phlex::SGML then render(value)
+          else
+            value.html_safe? ? raw(value) : plain(value.to_s)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -50,7 +50,13 @@ module Phlex
           state_keys: :@reactive_own_state_keys,
           collections: :@reactive_own_collections,
           computes: :@reactive_own_computes,
-          record_key: :@reactive_own_record_key
+          record_key: :@reactive_own_record_key,
+          # Deferred reply segments — reactive_lazy (issue #165).
+          lazy: :@reactive_own_lazy,
+          # verify_authorized opt-out (issue #168): a scalar bare flag (skip the
+          # WHOLE component) plus a list of named actions.
+          skip_all: :@reactive_own_skip_all,
+          skip_actions: :@reactive_own_skip_actions
         }.freeze
 
         # The identity-side hot-path memos swept by bump! (see the contract

data/lib/phlex/reactive/component.rb

@@ -114,6 +114,7 @@ module Phlex
       include DSL
       include Identity
       include Helpers
+      include Lazy
     end
   end
 end