phlex-reactive 0.9.2 → 0.9.4

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
@@ -399,6 +416,162 @@ module Phlex
           span(**mix({ data: { reactive_text: name.to_s } }, attrs)) { initial }
         end
 
+        # Value-conditional visibility (issue #161) — the x-show / data-show /
+        # wire:show equivalent, entirely client-side. Spread onto the element to
+        # show/hide; it declares which OWNED field controls it plus ONE literal
+        # predicate, and the generic controller toggles the `hidden` attribute
+        # from the field's CURRENT value on every input/change — no round trip,
+        # no token, no bespoke Stimulus controller:
+        #
+        #   div(**reactive_show(:mode, not: "off"))        { "details" }
+        #   div(**reactive_show(:kind, equals: "premium")) { "premium panel" }
+        #   div(**reactive_show(:size, in: %w[l xl]))      { "surcharge note" }
+        #   div(**reactive_show(:gift, equals: true))      { "gift message" }
+        #
+        # Exactly one predicate — equals:, not:, or in: (a list) — and every
+        # value is STRINGIFIED for a literal match against the field's value
+        # (a checkbox compares its checked state as "true"/"false", so
+        # `equals: true` is the checkbox form; a radio group reads the checked
+        # radio's value). This is a DECLARED LITERAL MATCH, never an expression
+        # — there is no eval surface (default-deny, like the op vocabulary).
+        #
+        # Scope: presentational only, strictly less powerful than the js ops —
+        # it reads an owned field (#15 ownership) and toggles `hidden` on an
+        # owned element. The client seeds visibility at connect and reconciles
+        # 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
+            raise ArgumentError,
+              "reactive_show(#{field.inspect}) needs exactly one predicate — equals:, not:, or " \
+              "in: — got #{predicates.keys.inspect}"
+          end
+
+          key, value = normalize_show_predicate(predicates, "reactive_show(#{field.inspect})").first
+          data = { reactive_show_field: field.to_s }
+          data[:"reactive_show_#{key}"] = key == "in" ? value.to_json : value
+
+          mix({ data: }, attrs)
+        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_targets needs at least one target " \
+              "(:field, \"#id\" => { equals:/not:/in: ... }), got #{field_maps.inspect}"
+          end
+
+          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
+
+            [name.to_s, normalize_show_target_map(name, map)]
+          end
+
+          { data: { reactive_show_targets: normalized.to_json } }
+        end
+
         # Scoped busy indicator (issue #99). Marks an element so the generic
         # controller toggles `data-reactive-busy` on it ONLY while `action` is in
         # flight — the scoped sibling of the always-on `data-reactive-busy` the
@@ -485,6 +658,13 @@ 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 optimistic-hint class ops (issue #98): the cosmetic class
         # vocabulary the client applies instantly and reverts on failure. Enforced
         # at build time in optimistic_hint_json (default-deny — a dead hint fails
@@ -494,6 +674,66 @@ 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 literal show predicate (issues #161/#164) and
+        # return its wire form — { "equals" => "v" } / { "not" => "v" } /
+        # { "in" => ["a", …] } (a real array: reactive_show JSON-encodes it into
+        # its own attr; the reactive_show_targets map embeds it directly).
+        # Shared by both helpers 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:, or in: — " \
+              "got #{predicates.keys.inspect}"
+          end
+
+          key, value = predicates.first
+          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
+
         # 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