phlex-reactive 0.10.0 → 0.11.0

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

@@ -47,7 +47,7 @@ module Phlex
 
         # 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
+        # `reply.replace.flash(:error, msg)`: the
         # component is the implicit subject (no `self` to thread) and there's no
         # constant to qualify (reply is a method, so a namespaced component needs
         # no `Response = …` alias). It returns the same immutable Response the
@@ -110,31 +110,49 @@ module Phlex
         # (an explicit override wins as a clean replace, not a `mix` string-concat —
         # mix would join two String ids into "default override").
         #
-        # `track_dirty:`/`warn_unsaved:` (issue #103) are CONSUMED here — deleted
-        # from overrides BEFORE the mix — because reactive_root treats every leftover
-        # kwarg as a literal HTML attribute override (only :id is special-cased), so
-        # an unconsumed `track_dirty: true` would render a bogus `track-dirty="true"`
-        # attribute. track_dirty mixes the trackDirty descriptor onto the root's
-        # data-action (mix token-joins, so a caller's own data-action survives);
-        # warn_unsaved emits the marker the client reads to arm the navigate-away
-        # guard (STRING "true" — a boolean-true attr renders valueless, which the
-        # client's param reader sees as "" → falsy).
+        # Dirty tracking (issue #103, #184) is now a CLASS-LEVEL reactive_dirty
+        # declaration, not a reactive_root kwarg. reactive_root reads
+        # self.class.reactive_dirty_config and emits the SAME DOM as before: the
+        # trackDirty descriptor on the root's data-action (mix token-joins, so a
+        # caller's own data-action survives) UNLESS `only:` scoped tracking to named
+        # fields, and — for warn_unsaved: true — the navigate-away marker (STRING
+        # "true", since a boolean-true attr renders valueless → "" → falsy client-
+        # side). The removed track_dirty:/warn_unsaved: kwargs raise a guided error.
         def reactive_root(**overrides)
           # A CLIENT-ONLY component (ClientBindings, issue #180) needs no #id —
           # there's no token to self-match by id. Use an explicit override, else
           # #id when the component defines one, else nothing (no id attr).
+          reject_removed_dirty_kwargs!(overrides)
           root_id = overrides.delete(:id)
           root_id = id if root_id.nil? && respond_to?(:id)
-          track_dirty = overrides.delete(:track_dirty)
-          warn_unsaved = overrides.delete(:warn_unsaved)
+          # Issue #183: bind a client-side compute AT THE ROOT — the descriptors +
+          # the recompute delegation ride here so no field needs per-field wiring.
+          # nil (the conditional-binding collapse) emits nothing.
+          compute = overrides.delete(:compute)
+          # Issue #184: dirty tracking is a class-level reactive_dirty declaration.
+          dirty = self.class.reactive_dirty_config if self.class.respond_to?(:reactive_dirty_config)
 
           attrs = mix({ **reactive_attrs }, overrides)
           attrs = mix(attrs, { id: root_id }) unless root_id.nil?
-          attrs = mix(attrs, { data: { action: "input->reactive#trackDirty" } }) if track_dirty
-          attrs = mix(attrs, { data: { reactive_warn_unsaved: "true" } }) if warn_unsaved
+          # Root-level delegation tracks the whole subtree UNLESS only: scoped it to
+          # named fields (those carry their own descriptor via reactive_field).
+          attrs = mix(attrs, { data: { action: "input->reactive#trackDirty" } }) if dirty && dirty[:only].nil?
+          attrs = mix(attrs, { data: { reactive_warn_unsaved: "true" } }) if dirty&.dig(:warn_unsaved)
+          attrs = mix(attrs, compute_binding(compute)) if compute
           attrs
         end
 
+        # Issue #184: track_dirty:/warn_unsaved: on reactive_root are removed in
+        # favor of the class-level reactive_dirty macro. Guided error naming it.
+        def reject_removed_dirty_kwargs!(overrides)
+          removed = overrides.keys & %i[track_dirty warn_unsaved]
+          return if removed.empty?
+
+          raise ArgumentError,
+            "reactive_root(#{removed.first}:) was removed in issue #184 — declare " \
+            "`reactive_dirty warn_unsaved: true` (class-level) instead."
+        end
+
         # Attributes for an element that triggers an action.
         #   button(**on(:toggle)) { "○" }
         #   form(**on(:save, event: "submit")) { ... }
@@ -168,14 +186,10 @@ module Phlex
         #   input(**on(:add, event: "keydown.enter"))      # Enter submits
         #   button(**on(:cancel, event: "keydown.esc"))     # Escape cancels
         #
-        # `listnav:` (a CSS selector for the option elements) adds keyboard list
-        # navigation to a search/combobox trigger (issue #72). It appends Stimulus
-        # keyboard filters to the SAME element's data-action so Arrow Up/Down move a
-        # client-side highlight among the options, Enter picks the highlighted one
-        # (clicking its own reactive trigger — so selection stays a signed action),
-        # and Escape clears — all with NO server round trip for the highlight (the
-        # controller's listnav* handlers, like #recompute). Omit it for no nav.
-        #   input(**on(:search, event: "input", debounce: 300, listnav: "[role=option]"))
+        # Combobox keyboard navigation is the standalone reactive_listnav (issue
+        # #181 removed the `on(…, listnav:)` kwarg — it duplicated reactive_listnav
+        # while skipping its blank-selector validation). Compose it via mix:
+        #   input(**mix(on(:search, event: "input", debounce: 300), reactive_listnav))
         # The verbatim JSON for an empty explicit-params payload. The common
         # trigger (on(:increment), no params) hits this on EVERY render — skipping
         # params.to_json (which re-serializes {} to the same "{}" each time) avoids
@@ -238,30 +252,31 @@ module Phlex
         #   input(type: "checkbox", checked: @todo.done,
         #     **mix(on(:toggle, event: "change", optimistic: { checked: :keep }), name: "done"))
         #   button(**on(:destroy, confirm: "Delete?", optimistic: { hide: true, to: :root })) { "Delete" }
-        # `loading:` / `disable_with:` (issue #99) — declarative per-trigger loading
-        # states, Livewire's wire:loading + phx-disable-with without a Stimulus
-        # controller. The moment the request is ENQUEUED (covering the queue wait,
-        # not just the fetch), the trigger gets `data-reactive-busy="<action>"`, an
-        # optional loading class, an optional disabled + text swap; all revert in a
-        # guarded finally. `loading:` is a hash:
+        # `busy:` (issue #181) — declarative per-trigger pending states, Livewire's
+        # wire:loading + phx-disable-with without a Stimulus controller. It shares
+        # optimistic:'s key vocabulary and normalizer; the ONLY difference is the
+        # lifecycle: a busy: hint applies the moment the request is ENQUEUED
+        # (covering the queue wait, not just the fetch) and reverts on SETTLE (any
+        # completion), where optimistic: reverts only on FAILURE. `busy:` is a
+        # String or a Hash:
+        #   * "Saving…"             — String shorthand for { disable: true, text: … }
         #   * disable: true         — disable the trigger while pending
-        #   * class: "…" / [ … ]    — a loading class string/array on the trigger
-        #                             (or a `to:` selector scoped to the root)
-        #   * text: "Saving…"       — swap the trigger's textContent while pending
-        #   * to: :root / "sel"     — target the class/text at the root or a selector
-        # `disable_with: "Saving…"` is the shorthand for
-        # `{ disable: true, text: "Saving…" }` and merges over an explicit `loading:`
-        # (its text/disable win). Both become RESERVED on() kwargs (CHANGELOG note,
-        # like #80's four and #98's optimistic:) — no longer free action-param names.
-        # The trigger/root also always carry `data-reactive-busy` for the whole
-        # pending window regardless of these hints, so an app styles a spinner with
-        # `[data-reactive-busy] .spinner { display: block }` and zero Ruby; see
+        #   * add_class:/remove_class:/toggle_class: "…" / [ … ] — class op on the
+        #                             trigger (or a `to:` selector scoped to the root)
+        #   * hide:/show: true      — hide/show the target while pending
+        #   * text: "Saving…"       — swap the trigger's innerHTML while pending
+        #   * to: :root / "sel"     — target the ops at the root or a selector
+        # checked: :keep is optimistic-ONLY (a native flip has no settle-revert
+        # meaning). The trigger/root also always carry `data-reactive-busy` for the
+        # whole pending window regardless of these hints, so an app styles a spinner
+        # with `[data-reactive-busy] .spinner { display: block }` and zero Ruby; see
         # busy_on for scoped indicators.
-        #   button(**on(:save, disable_with: "Saving…")) { "Save" }
-        #   button(**on(:destroy, confirm: "Sure?", loading: { class: "opacity-50" })) { "Delete" }
-        def on(action_name, event: "click", debounce: nil, throttle: nil, confirm: nil, listnav: nil,
-               window: false, once: false, outside: false, optimistic: nil, loading: nil, disable_with: nil,
+        #   button(**on(:save, busy: "Saving…")) { "Save" }
+        #   button(**on(:destroy, confirm: "Sure?", busy: { add_class: "opacity-50" })) { "Delete" }
+        def on(action_name, event: "click", debounce: nil, throttle: nil, confirm: nil,
+               window: false, once: false, outside: false, optimistic: nil, busy: nil,
                **params)
+          reject_removed_on_kwargs!(action_name, params)
           # A typo'd or forgotten action renders fine and only surfaces as an
           # opaque 403 at CLICK time (the endpoint's default-deny). Under
           # verbose_errors (dev + test), fail loudly at RENDER time instead —
@@ -298,7 +313,6 @@ module Phlex
 
           window_bound = window || outside
           action = "#{event}#{"@window" if window_bound}->reactive#dispatch#{":once" if once}"
-          action = "#{action} #{LISTNAV_ACTIONS.join(" ")}" if listnav
           attrs = {
             data: {
               action:,
@@ -308,12 +322,9 @@ module Phlex
           }
           attrs[:data][:reactive_debounce_param] = debounce if debounce
           attrs[:data][:reactive_throttle_param] = throttle if throttle
-          attrs[:data][:reactive_confirm_param] = confirm if confirm
-          attrs[:data][:reactive_listnav_option_param] = listnav if listnav
-          attrs[:data][:reactive_optimistic_param] = optimistic_hint_json(optimistic, action_name) if optimistic
-          if (loading_hint = loading_hint_json(loading, disable_with, action_name))
-            attrs[:data][:reactive_loading_param] = loading_hint
-          end
+          apply_confirm!(attrs[:data], confirm) if confirm
+          attrs[:data][:reactive_optimistic_param] = pending_hint_json(optimistic, action_name, :optimistic) if optimistic
+          attrs[:data][:reactive_busy_param] = pending_hint_json(busy, action_name, :busy) if busy
           # STRING "true", not boolean: Phlex renders a `true` attribute VALUELESS
           # (data-reactive-outside-param), which Stimulus's param reader sees as ""
           # — falsy in JS, so the guard silently never fires. The explicit ="true"
@@ -354,7 +365,7 @@ module Phlex
         # Validation is loud: only a non-empty Phlex::Reactive::JS chain is
         # 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)
+        def on_client(event, ops, window: false, once: false, outside: false, confirm: nil)
           unless ops.is_a?(Phlex::Reactive::JS)
             raise ArgumentError,
               "on_client expects a Phlex::Reactive::JS chain (e.g. js.toggle(\"#menu\")), " \
@@ -374,6 +385,14 @@ module Phlex
           # on()'s flags above.
           attrs[:data][:reactive_outside_param] = "true" if outside
           attrs[:data][:reactive_window_param] = "true" if window_bound
+          # 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
@@ -388,27 +407,67 @@ module Phlex
         # hatch). The trigger (on(:save)) stays on the button, not the field — so
         # focusing the input doesn't dispatch and collapse edit mode.
         #
-        # `dirty: true` (issue #103) wires the field to the generic controller's
-        # trackDirty action, so a change re-scans this reactive root's owned fields
-        # and marks the changed ones `data-reactive-dirty` (and the root with a
-        # count). NO client state is shipped — the baseline is the DOM's own
-        # `defaultValue`/`defaultChecked`/`defaultSelected`, i.e. the attributes from
-        # the last server render; dirty = current ≠ default. It deep-merges the
-        # descriptor via mix, so a caller's own data-action is token-joined, not
-        # clobbered (CLAUDE.md Never-Do #8 — combining with other data:/on() still
-        # needs mix at the call site).
-        def reactive_field(param, dirty: false, **attrs)
-          binding_attrs = { name: param.to_s, **attrs }
-          return binding_attrs unless dirty
+        # Dirty tracking is class-level now (issue #184): the per-field `dirty:`
+        # kwarg is REMOVED (reject_removed_field_dirty! raises a guided error). A
+        # field carries the trackDirty descriptor only when `reactive_dirty only:`
+        # names it (field_dirty_tracked?) — otherwise the root delegates for the
+        # whole subtree via reactive_root. The client behavior is unchanged (issue
+        # #103): a change re-scans this root's owned fields and marks the changed
+        # ones `data-reactive-dirty` (the root gets a count); NO client state ships —
+        # the baseline is the DOM's own `defaultValue`/`defaultChecked`/
+        # `defaultSelected` from the last server render (dirty = current ≠ default).
+        # The descriptor deep-merges via mix, so a caller's own data-action is
+        # token-joined, not clobbered (CLAUDE.md Never-Do #8).
+        def reactive_field(param, **attrs)
+          # Issue #184: the removed dirty: kwarg lands in **attrs — catch it and
+          # print the reactive_dirty rewrite.
+          reject_removed_field_dirty!(attrs)
+          # Under reactive_scope, emit the SCOPED wire name (name="invoice[date]")
+          # so the POST arrives bracketed (the endpoint unwraps one level) AND the
+          # field matches the client show/compute resolvers, which already query
+          # [name="scope[x]"]. An explicit name: in attrs still wins via the spread
+          # (a third-party wire name, never re-scoped) — the escape hatch.
+          binding_attrs = { name: scoped_field_name(param), **attrs }
+          # Per-field dirty descriptor when reactive_dirty only: names this field
+          # (issue #184) — otherwise the root delegates for the whole subtree.
+          return binding_attrs unless field_dirty_tracked?(param)
 
           mix(binding_attrs, { data: { action: "input->reactive#trackDirty" } })
         end
 
-        # Render an <input> already bound to an action param (issue #23). Sugar for
-        # input(**reactive_field(param, **attrs)); the value/type/etc. pass through.
-        #   reactive_input(:value, value: @record.name, type: "text")
-        def reactive_input(param, **attrs)
-          input(**reactive_field(param, **attrs))
+        # The removed reactive_field(dirty:) kwarg (issue #184) — now a guided error.
+        def reject_removed_field_dirty!(attrs)
+          return unless attrs.key?(:dirty)
+
+          raise ArgumentError,
+            "reactive_field(dirty:) was removed in issue #184 — declare " \
+            "`reactive_dirty only: %i[...]` (class-level) instead."
+        end
+
+        # True when reactive_dirty only: names this field, so it carries its own
+        # trackDirty descriptor (issue #184).
+        def field_dirty_tracked?(param)
+          return false unless self.class.respond_to?(:reactive_dirty_config)
+
+          only = self.class.reactive_dirty_config&.dig(:only)
+          only&.include?(param.to_sym) || false
+        end
+
+        # The wire name for a bare field param: `scope[param]` when the component
+        # declares reactive_scope, else the bare param. Read self.class.reactive_scope
+        # the way reactive_attrs does (helpers.rb) so scoped + unscoped stay aligned.
+        def scoped_field_name(param)
+          scope = self.class.reactive_scope if self.class.respond_to?(:reactive_scope)
+          scope ? "#{scope}[#{param}]" : param.to_s
+        end
+
+        # REMOVED in issue #184 — one binding helper (reactive_field); the element
+        # is the caller's: input(**reactive_field(:value, value: @record.name)).
+        # Raises a guided error printing that rewrite.
+        def reactive_input(param, **)
+          raise ArgumentError,
+            "reactive_input was removed in issue #184 — use " \
+            "input(**reactive_field(#{param.inspect}, …)) (one binding helper; the element is yours)."
         end
 
         # Mirror a compute output (or a declared input) into a TEXT NODE — a live
@@ -426,9 +485,26 @@ module Phlex
         # reducer would, or a morph repaints stale text (same reconcile contract
         # reactive_compute documents). Extra attrs merge over the binding.
         def reactive_text(name, initial = nil, **attrs)
+          # Issue #183: with no explicit initial, seed the first paint from
+          # reactive_values (Phase A) when the component declares it and covers this
+          # name — so the server render matches what the reducer would paint (the
+          # same no-flash reconcile contract reactive_show's first paint uses).
+          initial = reactive_text_seed(name) if initial.nil?
           span(**mix({ data: { reactive_text: name.to_s } }, attrs)) { initial }
         end
 
+        # The reactive_values first-paint seed for a reactive_text name, stringified
+        # the way the client reports a field (via show_value_string), or nil when
+        # the component declares no reactive_values or doesn't cover the name.
+        def reactive_text_seed(name)
+          return nil unless respond_to?(:reactive_values)
+
+          values = reactive_values
+          return nil unless values.is_a?(Hash) && values.key?(name.to_sym)
+
+          show_value_string(values[name.to_sym])
+        end
+
         # Value-conditional visibility (issue #180) — the x-show / data-show /
         # wire:show equivalent, entirely client-side, in ONE Ruby-native
         # conditions language. Spread onto the element to show/hide; declare an
@@ -495,12 +571,15 @@ module Phlex
         # 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
-        #   ))) { … }
+        # Issue #186: name the FIELD that drives the filter — reactive_filter(:q)
+        # compiles :q to [name="q"] (scope-aware) and defaults option to the
+        # [role=option] convention. group:/empty: stay opt-in; any selector kwarg
+        # overrides a convention:
+        #
+        #   div(**mix(reactive_root, reactive_filter(:q, empty: "#no-matches"))) do
+        #     input(name: "q", type: "search", **reactive_listnav)  # listnav → [role=option]
+        #     …
+        #   end
         #
         # Each option's haystack is its `data-reactive-filter-text` attribute
         # (server-rendered — pack in synonyms/categories), falling back to the
@@ -515,11 +594,25 @@ module Phlex
         # 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)
+        def reactive_filter(field = nil, input: :__removed, option: nil, group: nil, empty: nil)
+          # Issue #186: the four-selector kwarg form is removed — name the FIELD that
+          # drives the filter instead. A leftover input: means the old call shape.
+          unless input == :__removed
+            raise ArgumentError,
+              "reactive_filter(input:) was removed in issue #186 — name the driving field: " \
+              "reactive_filter(:q) (compiles to [name=\"q\"], scope-aware; option defaults to [role=option])."
+          end
+          raise ArgumentError, "reactive_filter needs a field name — reactive_filter(:q)" if field.nil?
+
           data = {
-            reactive_filter_input: filter_selector!(:input, input),
-            reactive_filter_option: filter_selector!(:option, option)
+            # Compile the field to a scoped [name="…"] selector (same scope convention
+            # reactive_field uses, so the filter input aligns with its own field).
+            reactive_filter_input: %([name="#{scoped_field_name(field)}"]),
+            # option defaults to the [role=option] convention; a kwarg overrides it.
+            reactive_filter_option: option ? filter_selector!(:option, option) : "[role=option]"
           }
+          # group/empty stay OPT-IN (no convention default — a default would change the
+          # byte-stable wire and always-emit an attribute the client would then query).
           data[:reactive_filter_group] = filter_selector!(:group, group) if group
           data[:reactive_filter_empty] = filter_selector!(:empty, empty) if empty
 
@@ -538,7 +631,7 @@ 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)
+        def reactive_listnav(option_selector = "[role=option]")
           {
             data: {
               action: LISTNAV_ACTIONS.join(" "),
@@ -614,20 +707,27 @@ module Phlex
           { data: { reactive_busy_on: action.to_s } }
         end
 
-        # Data attributes declaring a client-side compute for the root element.
-        # Spread ALONGSIDE reactive_root so the generic controller can find the
-        # reducer and the named input/output fields inside this root:
-        #   div(**mix(reactive_root, reactive_compute_attrs(:payment_split))) { … }
-        #
-        # It emits the reducer key plus the input/output field names as JSON so the
-        # client runs the reducer on `input`, writes the outputs with no round trip,
-        # then the debounced POST reconciles from the server reply. Raises for an
-        # undeclared compute — a silent no-op would leave the field wiring dead.
+        # REMOVED in issue #183 — the compute binding moved to
+        # reactive_root(compute: :name), which emits the descriptors AND the
+        # recompute delegation at the root, so no field carries per-field wiring:
+        #   div(**reactive_root(compute: :payment_split)) { … }
+        # This helper now raises a guided ArgumentError printing that rewrite.
         def reactive_compute_attrs(name)
-          definition = self.class.reactive_compute_def(name)
+          raise ArgumentError,
+            "reactive_compute_attrs(#{name.inspect}) was removed in issue #183 — " \
+            "pass reactive_root(compute: #{name.inspect}) instead (bind + listen at the root)"
+        end
+
+        # The root's compute descriptors + the recompute delegation (issue #183).
+        # Emits the same data-reactive-compute-* attrs as before PLUS the
+        # input->reactive#recompute action, all on the root element. Raises for an
+        # undeclared name (fail fast, not a silent no-op).
+        def compute_binding(name)
+          definition = self.class.reactive_computes[name.to_sym]
           raise Error, "#{self.class} has no reactive_compute #{name.inspect}" unless definition
 
           data = {
+            action: "input->reactive#recompute",
             reactive_compute_reducer_param: definition.reducer,
             reactive_compute_inputs_param: compute_inputs_param(definition),
             reactive_compute_outputs_param: definition.outputs.map(&:to_s).to_json
@@ -658,12 +758,13 @@ module Phlex
           definition.inputs.to_h { [it.to_s, types[it].to_s] }.to_json
         end
 
-        # Render a <select> bound to an action param (issue #23). The options block
-        # is the element's content, so the awkward FormBuilder positional split
-        # (where name: lands after the options/html-options args) goes away:
-        #   reactive_select(:status) { @statuses.each { |s| option(value: s, selected: s == @record.status) { s } } }
-        def reactive_select(param, **attrs, &)
-          select(**reactive_field(param, **attrs), &)
+        # REMOVED in issue #184 — one binding helper (reactive_field); the element
+        # is the caller's: select(**reactive_field(:status)) { status_options }.
+        # Raises a guided error printing that rewrite.
+        def reactive_select(param, **, &)
+          raise ArgumentError,
+            "reactive_select was removed in issue #184 — use " \
+            "select(**reactive_field(#{param.inspect})) { … } (one binding helper; the element is yours)."
         end
 
         # Map a declared nested param onto Rails' <assoc>_attributes, carrying the
@@ -702,13 +803,6 @@ module Phlex
         LEGACY_SHOW_PREDICATE_KEYS = %i[equals not in gte gt lte lt].freeze
         LEGACY_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
-        # at build time in optimistic_hint_json (default-deny — a dead hint fails
-        # at render, not silently in the browser). Each carries a class string or
-        # array; hide/checked are flags with a fixed shape.
-        OPTIMISTIC_CLASS_OPS = %w[toggle_class add_class remove_class].freeze
-
         private
 
         # A reactive_filter/reactive_listnav selector, validated non-blank and
@@ -725,6 +819,53 @@ module Phlex
           selector
         end
 
+        # Issue #179: apply a confirm: gate to a trigger's data hash. A String is
+        # the static #52/#55 form (data-reactive-confirm-param, unchanged). A Hash
+        # is the CONDITIONAL form (data-reactive-confirm-when-param, JSON) — warn
+        # only when field values look suspect:
+        #   { when: { total: 0 }, message: }  — reactive_show conditions language
+        #     (scalar=equals, Range=threshold, Array=set); prompts when it MATCHES.
+        #   { predicate: "name", message: }   — a JS fn registered with
+        #     setConfirmPredicate, evaluated over collected fields (multi-field logic).
+        # 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.
+        def apply_confirm!(data, confirm)
+          case confirm
+          when String
+            data[:reactive_confirm_param] = confirm
+          when Hash
+            data[:reactive_confirm_when_param] = compile_conditional_confirm(confirm).to_json
+          else
+            raise ArgumentError,
+              "confirm: takes a String (static) or a Hash ({ when: {…}, message: } / " \
+              "{ predicate: \"name\", message: }), got #{confirm.class}"
+          end
+        end
+
+        # Validate + compile a Hash confirm: into its wire payload. Exactly one of
+        # when:/predicate:, message: required — a dead binding fails loudly at
+        # render (the reactive_show posture), never silently in the browser.
+        def compile_conditional_confirm(confirm)
+          message = confirm[:message]
+          has_when = confirm.key?(:when)
+          has_predicate = confirm.key?(:predicate)
+
+          if has_when == has_predicate
+            raise ArgumentError,
+              "confirm: needs exactly one of when: (a conditions hash) or predicate: " \
+              "(a registered name), not both/neither — got #{confirm.except(:message).inspect}"
+          end
+          raise ArgumentError, "confirm: Hash needs a message: to show when it fires" if message.nil?
+
+          if has_predicate
+            { "predicate" => confirm[:predicate].to_s, "message" => message }
+          else
+            groups = Phlex::Reactive::ShowConditions.normalize(if: confirm[:when])
+            { "groups" => { "any" => groups }, "message" => message }
+          end
+        end
+
         # Normalize + validate ONE field's target map (issue #180): each key a
         # single id selector (loud raise — the declare-time half of the two-sided
         # default-deny), each value a where-style condition value (scalar/Array/
@@ -842,89 +983,90 @@ module Phlex
           value.to_s == "keep"
         end
 
-        # Normalize + validate the optimistic hint hash, returning its JSON wire
-        # form (data-reactive-optimistic-param). `to: :root` becomes the same
-        # "@root" sentinel the js op builder uses so the client resolves it
-        # uniformly. Unknown keys, a bad `checked:` value, or a non-hash raise —
-        # a hint that can't apply must fail loudly at render.
-        def optimistic_hint_json(optimistic, action_name)
-          unless optimistic.is_a?(Hash)
-            raise ArgumentError,
-              "on(#{action_name.inspect}) optimistic: must be a Hash of visual hints " \
-              "(e.g. { checked: :keep } or { hide: true, to: :root }), got #{optimistic.class}"
-          end
-
-          hint = {}
-          optimistic.each do |key, value|
-            case key.to_s
-            when *OPTIMISTIC_CLASS_OPS
-              hint[key.to_s] = Array(value).map(&:to_s)
-            when "hide"
-              hint["hide"] = value ? true : false
-            when "checked"
-              unless value.to_s == "keep"
-                raise ArgumentError,
-                  "on(#{action_name.inspect}) optimistic checked: only supports :keep " \
-                  "(flip the native control, revert on failure), got #{value.inspect}"
-              end
-              hint["checked"] = "keep"
-            when "to"
-              hint["to"] = value == :root ? Phlex::Reactive::JS::ROOT_SENTINEL : value.to_s
-            else
-              raise ArgumentError,
-                "on(#{action_name.inspect}) got an unknown optimistic hint #{key.inspect} — " \
-                "supported: toggle_class/add_class/remove_class, checked: :keep, hide: true, to:"
-            end
-          end
-
-          hint.to_json
+        # The removed on() pending-state kwargs (issue #181). loading:/disable_with:
+        # collapsed into busy:; listnav: into the standalone reactive_listnav.
+        # They now land in **params, so catch them there and raise a guided error
+        # showing the rewrite — a clean break (pre-1.0), not a silent shim that
+        # would ship a stale call to the browser wrong.
+        REMOVED_ON_KWARGS = {
+          disable_with: 'busy: "…" (String shorthand for { disable: true, text: "…" })',
+          loading: "busy: { disable:, add_class:, text:, to: } (same keys as optimistic:)",
+          listnav: "reactive_listnav — mix(on(:search, event: \"input\"), reactive_listnav)"
+        }.freeze
+
+        # The unified pending-state hint vocabulary (issue #181): the js.* op names
+        # shared by optimistic: and busy:, plus disable:/to:. checked: :keep is
+        # optimistic-ONLY (a native control flip has no settle-revert meaning).
+        PENDING_CLASS_OPS = %w[toggle_class add_class remove_class].freeze
+
+        private_constant :REMOVED_ON_KWARGS, :PENDING_CLASS_OPS
+
+        def reject_removed_on_kwargs!(action_name, params)
+          removed = params.keys & REMOVED_ON_KWARGS.keys
+          return if removed.empty?
+
+          key = removed.first
+          raise ArgumentError,
+            "on(#{action_name.inspect}) #{key}: was removed in issue #181 — use #{REMOVED_ON_KWARGS[key]}"
         end
 
-        # Normalize + validate the loading hint (issue #99), returning its JSON wire
-        # form (data-reactive-loading-param) or nil when neither loading: nor
-        # disable_with: is given (the bare on() hot path stays untouched).
-        # disable_with: "Saving…" expands to { disable: true, text: … } and MERGES
-        # over an explicit loading: hash — its text/disable win. `to: :root` becomes
-        # the "@root" sentinel the js op builder uses so the client resolves targets
-        # uniformly. An unknown key or a non-hash loading: raises — a dead hint must
-        # fail loudly at render, not silently in the browser (default-deny).
-        def loading_hint_json(loading, disable_with, action_name)
-          return nil if loading.nil? && disable_with.nil?
-
-          source = loading || {}
+        # Normalize + validate a pending-state hint (issue #181), returning its
+        # JSON wire form. ONE vocabulary + ONE normalizer for both optimistic: (kind
+        # :optimistic, reverts on FAILURE) and busy: (kind :busy, reverts on
+        # SETTLE); they differ only in client lifecycle, not in shape. The String
+        # shorthand `busy: "Saving…"` expands to { disable: true, text: … }. `to:`
+        # resolves through the SAME JS.normalize_target the js op builder uses (a
+        # :root sentinel or a verbatim CSS selector). checked: :keep is accepted
+        # only for :optimistic. An unknown key, a bad value, or the wrong type
+        # raises — a dead hint fails loudly at render, never silently on the client.
+        def pending_hint_json(source, action_name, kind)
+          source = { disable: true, text: source } if kind == :busy && source.is_a?(String)
           unless source.is_a?(Hash)
             raise ArgumentError,
-              "on(#{action_name.inspect}) loading: must be a Hash of loading hints " \
-              "(e.g. { disable: true, class: \"opacity-50\", text: \"Saving…\" }), got #{loading.class}"
+              "on(#{action_name.inspect}) #{kind}: must be a #{"String or " if kind == :busy}Hash of visual " \
+              "hints (e.g. { disable: true, text: \"Saving…\" }), got #{source.class}"
           end
 
           hint = {}
           source.each do |key, value|
             case key.to_s
-            when "class"
-              hint["class"] = Array(value).map(&:to_s)
-            when "disable"
-              hint["disable"] = value ? true : false
+            when *PENDING_CLASS_OPS
+              hint[key.to_s] = Array(value).map(&:to_s)
+            when "hide", "show", "disable"
+              hint[key.to_s] = value ? true : false
             when "text"
               hint["text"] = value.to_s
             when "to"
-              hint["to"] = value == :root ? Phlex::Reactive::JS::ROOT_SENTINEL : value.to_s
+              hint["to"] = Phlex::Reactive::JS.normalize_target(value)
+            when "checked"
+              hint["checked"] = pending_checked!(value, action_name, kind)
             else
               raise ArgumentError,
-                "on(#{action_name.inspect}) got an unknown loading hint #{key.inspect} — " \
-                "supported: disable:, class:, text:, to:"
+                "on(#{action_name.inspect}) got an unknown #{kind} hint #{key.inspect} — supported: " \
+                "add_class/remove_class/toggle_class, hide:, show:, disable:, text:, to:" \
+                "#{", checked: :keep" if kind == :optimistic}"
             end
           end
 
-          # disable_with: "Saving…" ≡ { disable: true, text: … }, applied AFTER the
-          # explicit loading: hash so it wins on both keys (the shorthand is the
-          # more specific intent when a caller passes both).
-          if disable_with
-            hint["disable"] = true
-            hint["text"] = disable_with.to_s
+          hint.to_json
+        end
+
+        # checked: :keep flips a native checkbox/radio and reverts on failure — it
+        # only makes sense for optimistic: (a settle-revert busy: hint has no native
+        # control to keep). Reject it for :busy, and reject any value but :keep.
+        def pending_checked!(value, action_name, kind)
+          if kind != :optimistic
+            raise ArgumentError,
+              "on(#{action_name.inspect}) #{kind}: does not support checked: — the native-control " \
+              "flip is an optimistic-only hint (it reverts on failure, not on settle)"
+          end
+          unless value.to_s == "keep"
+            raise ArgumentError,
+              "on(#{action_name.inspect}) optimistic checked: only supports :keep " \
+              "(flip the native control, revert on failure), got #{value.inspect}"
           end
 
-          hint.to_json
+          "keep"
         end
 
         # The component's record, for the nested-attributes helpers. Requires a