phlex-reactive 0.9.5 → 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
@@ -73,16 +73,24 @@ module Phlex
         # signed identity token. Spread onto the root:
         #   div(id:, **reactive_attrs) { ... }
         def reactive_attrs
-          data = {
-            controller: "reactive",
-            reactive_token_value: reactive_token
-          }
+          data = { controller: "reactive" }
+          # A CLIENT-ONLY component (Phlex::Reactive::ClientBindings, issue #180)
+          # has no Identity, so no token — the root is tokenless (show/filter/
+          # compute need no signed round trip). reactive_token is private, so the
+          # include-private `respond_to?` mirrors to_stream_token's guard.
+          data[:reactive_token_value] = reactive_token if respond_to?(:reactive_token, true)
           # Client debug mode (issue #108): stamp the flag so the generic controller
           # console.groups every dispatch. STRING "true", not boolean — Phlex renders
           # a boolean-true attr VALUELESS, which getAttribute reads as "" (falsy in
           # JS), so the client's attr check would never fire (the on()/warn_unsaved
           # precedent). Off by default → no key, no string, zero client surface.
           data[:reactive_debug] = "true" if Phlex::Reactive.debug
+          # Field-name scope (issue #180): the client prefixes bare binding field
+          # names with `scope[...]`. Omitted entirely when undeclared — byte-stable
+          # wire for unscoped components.
+          if self.class.respond_to?(:reactive_scope) && (scope = self.class.reactive_scope)
+            data[:reactive_scope] = scope.to_s
+          end
           { data: }
         end
 
@@ -102,26 +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)
-          root_id = overrides.delete(:id) || id
-          track_dirty = overrides.delete(:track_dirty)
-          warn_unsaved = overrides.delete(:warn_unsaved)
-
-          attrs = mix({ **reactive_attrs }, overrides, { id: root_id })
-          attrs = mix(attrs, { data: { action: "input->reactive#trackDirty" } }) if track_dirty
-          attrs = mix(attrs, { data: { reactive_warn_unsaved: "true" } }) if warn_unsaved
+          # 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)
+          # 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?
+          # 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")) { ... }
@@ -155,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
@@ -225,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 —
@@ -285,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:,
@@ -295,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"
@@ -341,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\")), " \
@@ -361,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
@@ -375,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
@@ -413,65 +485,82 @@ 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
 
-        # 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.
-        # 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 }
+        # 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
+        # if:/if_any:/unless: condition with where-style values, and the generic
+        # controller toggles `hidden` from the fields' CURRENT values on every
+        # input/change — no round trip, no token, no bespoke Stimulus controller.
+        #
+        # THE VALUE LANGUAGE (Phlex::Reactive::ShowConditions):
+        #   Hash    = AND (multiple keys ANDed)          if: { a: "x", b: "y" }
+        #   Array   = membership                          if: { size: %w[l xl] }
+        #   Range   = threshold (10.. / ..10 / ...10 / 10..20)  if: { qty: 10.. }
+        #   true/false = checkbox checked-state           if: { gift: true }
+        #   nil     = blank                               if: { note: nil }
+        #   unless: = negation (composes with if:/if_any:)
+        #
+        #   div(**reactive_show(unless: { mode: "off" }))          { "details" }
+        #   div(**reactive_show(if: { size: %w[l xl] }))           { "surcharge" }
+        #   div(**reactive_show(if: { qty: 10.. }))                { "bulk note" }
+        #   # OR-of-AND — director OR (shareholder AND role == "individual"):
+        #   div(**reactive_show(if_any: [
+        #     { director: true },
+        #     { shareholder: true, role: "individual" }
         #   ]))
-        #   # 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.
+        #
+        # There is no expression surface — every term is a declared literal, so
+        # the same default-deny posture as before. Everything normalizes to ONE
+        # DNF wire attr (data-reactive-show='{"any":[[term,…],…]}').
+        #
+        # FIRST PAINT is computed for you: declare reactive_values (an instance
+        # method returning { field => value }) and every binding whose fields are
+        # all provided renders the correct initial `hidden:` server-side — no
+        # per-section mirror method, no flash. An explicit `hidden:` always wins;
+        # a per-call `values:` override merges over reactive_values.
+        #
+        # `disable: true` disables the section's OWNED controls while it is hidden
+        # so a switched-away value never submits. `reactive_scope :form` lets
+        # bindings use bare field symbols ([name="form[field]"] on the client).
+        #
+        # Scope: presentational only, strictly less powerful than the js ops — it
+        # reads owned fields (#15 ownership) and toggles `hidden` (+ optionally
+        # `disabled`) on owned elements. Extra attrs deep-merge over the binding
+        # (mix), like reactive_field.
         def reactive_show(field = nil, **options)
-          connectives = options.slice(*SHOW_CONNECTIVE_KEYS)
-          return reactive_show_compound(field, connectives, options) if connectives.any?
+          reject_legacy_show_surface!(field, options)
+
+          conditions = options.slice(*SHOW_CONDITION_KEYS)
+          disable = options.delete(:disable)
+          values_override = options.delete(:values)
+          attrs = options.except(*SHOW_CONDITION_KEYS)
+
+          groups = Phlex::Reactive::ShowConditions.normalize(**conditions)
+          data = { reactive_show: { "any" => groups }.to_json }
+          data[:reactive_show_disable] = "true" if disable
 
-          reactive_show_single(field, options)
+          result = mix({ data: }, attrs)
+          apply_first_paint_hidden(result, groups, values_override)
         end
 
         # Client-side option filtering for the searchable combobox (issue #163)
@@ -482,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
@@ -502,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
 
@@ -525,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(" "),
@@ -544,33 +650,35 @@ module Phlex
         # 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" })))
+        #     "#advanced-tab"   => "advanced",          # equals
+        #     "#advanced-panel" => "advanced",
+        #     "#premium-note"   => %w[gold platinum]))) # membership
         #
         # 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).
+        # interpreter (two-sided default-deny); the value uses the same where-
+        # style conditions vocabulary (scalar/Array/Range, 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). A target value is positive-only (no
+        # per-target unless:) — express "not X" as a membership Array over the
+        # remaining options.
         #
         # 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" } })
+        #   reactive_show_targets(mode: { "#advanced-tab" => "advanced" },
+        #                         kind: { "#premium-note" => %w[gold platinum] })
         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}"
+              "(:field, \"#id\" => value), got #{field_maps.inspect}"
           end
 
           normalized = field_maps.to_h do |name, map|
@@ -599,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
@@ -643,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
@@ -675,40 +791,17 @@ module Phlex
           reactive_record_for_nested.update!(**nested_attributes(association, attrs), **extra)
         end
 
-        # 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
-        # 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
+        # The conditions-language kwargs (issue #180): if:/if_any:/unless: —
+        # compiled by Phlex::Reactive::ShowConditions into the DNF wire. The ONE
+        # vocabulary; there are no predicate kwargs any more.
+        SHOW_CONDITION_KEYS = %i[if if_any unless].freeze
+
+        # The removed 0.9.5 surface (issue #180 clean break): each of these
+        # kwargs — and a positional field — now raises a GUIDED error printing
+        # the if:/if_any:/unless: rewrite. Kept only to detect the legacy call
+        # shape; nothing here reaches the wire.
+        LEGACY_SHOW_PREDICATE_KEYS = %i[equals not in gte gt lte lt].freeze
+        LEGACY_SHOW_CONNECTIVE_KEYS = %i[all any].freeze
 
         private
 
@@ -726,154 +819,157 @@ module Phlex
           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.
+        # 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/
+        # Range) that compiles to ONE DNF group (terms ANDed). 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}"
+              "(\"#id\" => value), got #{targets.inspect}"
           end
 
-          targets.to_h do |selector, predicate|
+          targets.to_h do |selector, value|
             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
+            if value.is_a?(Hash)
+              raise ArgumentError,
+                "reactive_show_targets(#{field.inspect}) target #{selector.inspect}: the { equals: ... } " \
+                "predicate form was removed — pass a bare value (#{selector.inspect} => \"advanced\", " \
+                "=> %w[a b] for a set, => 10.. for a threshold)"
+            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}"
+            # A target compiles to ONE group: the field-vs-value condition.
+            groups = Phlex::Reactive::ShowConditions.normalize(if: { field => value })
+            [selector, groups.first]
           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)
+        # Reject the removed 0.9.5 reactive_show surface (issue #180 clean break)
+        # with a GUIDED error printing the if:/if_any:/unless: rewrite. A
+        # positional field, a predicate kwarg (equals:/not:/in:/gte:/…), or a
+        # connective (all:/any:) all land here before any conditions parsing.
+        def reject_legacy_show_surface!(field, options)
+          unless field.nil?
             raise ArgumentError,
-              "#{context} #{key}: needs a number (an ordered comparison against a literal), " \
-              "got #{value.inspect}"
+              "reactive_show no longer takes a positional field — the conditions language is " \
+              "keyword-only: reactive_show(if: { #{field}: <value> }) (a Range is a threshold, " \
+              "an Array is a set, unless: negates). See the 0.10 upgrade notes."
           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?
+          if (pred = options.keys & LEGACY_SHOW_PREDICATE_KEYS).any?
             raise ArgumentError,
-              "reactive_show needs a field (reactive_show(:mode, equals: …)) or a compound " \
-              "connective (reactive_show(all: [...]) / any:) — got neither"
+              "reactive_show(#{pred.first}: ...) was removed — use the conditions language: " \
+              "reactive_show(if: { field: value }). equals:/not: → if:/unless:, in: → an Array value, " \
+              "gte:/gt:/lte:/lt: → a Range value (10.., ..10, ...10)."
           end
-
-          predicates = options.slice(*SHOW_PREDICATE_KEYS)
-          attrs = options.except(*SHOW_PREDICATE_KEYS)
-          unless predicates.size == 1
+          if (conn = options.keys & LEGACY_SHOW_CONNECTIVE_KEYS).any?
+            replacement = conn.first == :all ? "if: { … }" : "if_any: [{ … }, { … }]"
             raise ArgumentError,
-              "reactive_show(#{field.inspect}) needs exactly one predicate — equals:, not:, in:, " \
-              "or gte:/gt:/lte:/lt: — got #{predicates.keys.inspect}"
+              "reactive_show(#{conn.first}: [...]) was removed — use #{replacement}. " \
+              "all: → if: (one AND group); any: → if_any: (OR of AND groups). Terms are now " \
+              "field => value pairs, not { field:, equals: } hashes."
           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
+        # Compute the first-paint `hidden:` from reactive_values (issue #180) so
+        # the author never restates the predicate as a Ruby mirror method. Fires
+        # only when EVERY field the binding references is provided (by
+        # reactive_values, merged under a per-call `values:` override); otherwise
+        # the attrs are returned untouched. An explicit `hidden:` in the caller's
+        # attrs always wins (it survives the mix, so this is a no-op then).
+        def apply_first_paint_hidden(attrs, groups, values_override)
+          return attrs if attrs.key?(:hidden)
 
-          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
+          provided = show_values(values_override)
+          return attrs if provided.nil?
 
-          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
+          referenced = Phlex::Reactive::ShowConditions.fields(groups)
+          return attrs unless referenced.all? { provided.key?(it) }
 
-          normalized = terms.map { normalize_show_term(connective, it) }
-          mix({ data: { reactive_show: { connective.to_s => normalized }.to_json } }, attrs)
+          visible = Phlex::Reactive::ShowConditions.match?(groups, provided)
+          attrs.merge(hidden: !visible)
         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
+        # The { field => current-string-value } map the first-paint evaluator
+        # reads: reactive_values (if the component declares it) merged under a
+        # per-call values: override, both stringified the way the client reads a
+        # field (checkbox → "true"/"false", nil → ""). nil when neither source
+        # exists — first paint then no-ops (no flash guarantee is the author's,
+        # exactly as before).
+        def show_values(values_override)
+          base = respond_to?(:reactive_values) ? reactive_values : nil
+          return nil if base.nil? && values_override.nil?
+
+          merged = {}
+          merged.merge!(base) if base
+          merged.merge!(values_override) if values_override
+          merged.to_h { |name, value| [name.to_s, show_value_string(value)] }
+        end
 
-          field = term[:field]
-          predicate = normalize_show_predicate(term.except(:field), "#{context} (field #{field.inspect})")
-          { "field" => field.to_s }.merge(predicate)
+        # Stringify a reactive_values entry the way the client's #showFieldValue
+        # reports the live field: a boolean is the checkbox checked-state string,
+        # nil is blank, everything else is to_s.
+        def show_value_string(value)
+          case value
+          when true then "true"
+          when false then "false"
+          when nil then ""
+          else value.to_s
+          end
         end
 
         # True when the hint declares checked: :keep — the click-bound
@@ -887,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