phlex-reactive 0.9.5 → 0.11.0

data/lib/phlex/reactive/client_bindings.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The blessed CLIENT-ONLY include (issue #180). A view that only shows/hides
+    # (reactive_show), filters (reactive_filter), computes client-side
+    # (reactive_compute), or runs zero-round-trip ops (on_client/js) — with NO
+    # server actions and NO signed token — includes this instead of the full
+    # Phlex::Reactive::Component.
+    #
+    # Why it exists: including the full Component pulls in Streamable, whose
+    # class/instance methods (replace/update/append/prepend/remove,
+    # to_stream_*) collide by NAME with an app's own Turbo-stream concern — so
+    # adopters cherry-picked an internal module and hand-rolled a token-less root
+    # (and defined a dummy #id "never read at render" just to keep
+    # phlex_reactive:doctor quiet). ClientBindings is that missing seam, blessed:
+    #
+    #   class ExerciseFilter < ApplicationComponent
+    #     include Phlex::Reactive::ClientBindings
+    #
+    #     reactive_scope :form
+    #     def reactive_values = { role: @role }
+    #
+    #     def view_template
+    #       div(**reactive_root) do              # token-less: no #id required
+    #         select(name: "form[role]") { role_options }
+    #         div(**reactive_show(if: { role: "individual" })) { demographics }
+    #       end
+    #     end
+    #   end
+    #
+    # It includes the DECLARATION DSL and the view Helpers, but NOT Streamable
+    # (nothing to clobber) or Identity (no token). So a ClientBindings class never
+    # enters Streamable.registered_classes and is invisible to
+    # phlex_reactive:doctor's #id check — no dummy #id, no nag.
+    #
+    # The client-only DSL macros (reactive_scope, reactive_compute) work; the
+    # SERVER-ACTION macros (action, reactive_record, reactive_state) RAISE at
+    # class-definition time — without Identity they could only silently no-op
+    # (sign nothing, dispatch nowhere), so the guard fails loudly (the guard lives
+    # in Component::DSL#require_server_actions!, keyed on Identity presence).
+    #
+    # Helpers is token-tolerant (issue #180): reactive_attrs emits a token only
+    # when reactive_token is available, and reactive_root uses #id only when
+    # defined — so the client-only view helpers work with no Identity/Streamable.
+    #
+    # The full Component includes ClientBindings too (ONE implementation of the
+    # client-only surface), then layers Streamable + Identity on top — so a
+    # token-bearing reactive_root is a SUPERSET, not a fork.
+    module ClientBindings
+      extend ActiveSupport::Concern
+
+      include Component::DSL
+      include Component::Helpers
+    end
+  end
+end

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

@@ -29,10 +29,31 @@ module Phlex
         MIRROR_ID_SELECTOR = /\A#[A-Za-z_][\w-]*\z/
 
         class_methods do
+          # Guard the three SERVER-ACTION macros (issue #180). ClientBindings
+          # includes this DSL for its client-only macros (reactive_scope,
+          # reactive_compute) but does NOT include Identity/Streamable — so a
+          # signed token is never minted and no action endpoint dispatches to
+          # this class. Declaring action/reactive_record/reactive_state there
+          # would silently no-op (an action that can never fire, a record that
+          # signs nothing). Fail LOUDLY at class-definition time instead — the
+          # default-deny posture. Keyed on Identity presence: a full
+          # Phlex::Reactive::Component includes it (passes); a ClientBindings-only
+          # class does not (raises).
+          def require_server_actions!(macro)
+            return if include?(Phlex::Reactive::Component::Identity)
+
+            raise ArgumentError,
+              "#{self}: `#{macro}` needs the full Phlex::Reactive::Component — it signs a token / " \
+              "dispatches a server action, which Phlex::Reactive::ClientBindings deliberately omits " \
+              "(client-only: no token, no endpoint). Include Phlex::Reactive::Component for actions, " \
+              "or drop `#{macro}` and use the client-only helpers (reactive_show/filter/compute, on_client)."
+          end
+
           # Declare the ActiveRecord (GlobalID-able) record this component is
           # rebuilt from. The signed token carries its GlobalID; the server
           # re-finds it on each action. State lives in the DB.
           def reactive_record(name)
+            require_server_actions!(:reactive_record)
             Registry.write_scalar(self, :record_key, name.to_sym)
           end
 
@@ -44,9 +65,67 @@ module Phlex
             Registry.resolve_scalar(self, :record_key, :reactive_record_key)
           end
 
+          # Declare (with a name) OR read (bare) a form-field NAMESPACE for this
+          # component's bindings (issue #180). With `reactive_scope :form`,
+          # reactive_show / reactive_values use bare symbols (`:director`) and the
+          # client resolves the owned field as `[name="form[director]"]`; the root
+          # emits `data-reactive-scope="form"`. Bare `reactive_scope` reads the
+          # nearest declared scope up the ancestry (nil when none) — the
+          # dual-purpose form matching reactive_compute's getter/setter. A
+          # per-binding raw string field name still passes through unscoped.
+          def reactive_scope(name = nil)
+            return Registry.resolve_scalar(self, :scope, :reactive_scope) if name.nil?
+
+            scope = name.to_sym
+            # Issue #184: catch an action already declared with a schema nested under
+            # THIS scope key (the action-first declaration order) — the endpoint
+            # unwraps ONE scope level, so a schema pre-nested under it would be dead.
+            reactive_actions.each_value { assert_no_scope_double_nesting!(scope, it.params, it.name) }
+            Registry.write_scalar(self, :scope, scope)
+          end
+
+          # Raise a guided ArgumentError when a param schema is ALREADY nested under
+          # the scope key (issue #184): the endpoint peels one scope level, so
+          # params: { <scope>: { … } } would double-unwrap to nothing. Shared by both
+          # macros so neither declaration order can dodge the guard. A nested key that
+          # is NOT the scope (a real nested_attributes param) is fine.
+          def assert_no_scope_double_nesting!(scope, params, action_name)
+            return unless params.is_a?(Hash) && params[scope].is_a?(Hash)
+
+            raise ArgumentError,
+              "#{self}: action #{action_name.inspect} nests its schema under the reactive_scope " \
+              "key #{scope.inspect} (params: { #{scope}: { … } }). The endpoint unwraps one scope " \
+              "level already — declare the schema FLAT: params: { #{params[scope].keys.first || :field}: … }."
+          end
+
+          # Issue #184: ONE dirty-tracking declaration, class-level. Replaces
+          # reactive_root(track_dirty:, warn_unsaved:) + reactive_field(dirty:).
+          #
+          #   reactive_dirty                       # track every field via the root
+          #   reactive_dirty warn_unsaved: true    # + warn before navigating away
+          #   reactive_dirty only: %i[title]       # track only these fields (per-field)
+          #
+          # Stored as a frozen config the render helpers read; the emitted DOM is
+          # byte-identical to the old kwargs, so the client is unchanged. `only:`
+          # switches to per-field descriptors (no root-level input delegation);
+          # otherwise the root delegates for the whole subtree.
+          def reactive_dirty(warn_unsaved: false, only: nil)
+            Registry.write_scalar(self, :dirty, {
+              warn_unsaved: warn_unsaved ? true : false,
+              only: only && Array(only).map(&:to_sym).freeze
+            }.freeze)
+          end
+
+          # The resolved dirty config (or nil when reactive_dirty was never
+          # declared), inherited through the Registry like every other scalar.
+          def reactive_dirty_config
+            Registry.resolve_scalar(self, :dirty, :reactive_dirty_config)
+          end
+
           # Opt into signed STATE for record-less components only.
           #   reactive_state :count, :open
           def reactive_state(*names)
+            require_server_actions!(:reactive_state)
             Registry.append(self, :state_keys, names.map(&:to_sym))
           end
 
@@ -112,6 +191,14 @@ module Phlex
           # Array params accept BOTH a JSON array and a Rails-style index hash
           # ({ "0" => ..., "1" => ... }), so a fields_for collection works either way.
           def action(name, params: {})
+            require_server_actions!(:action)
+            # Issue #184: params: :symbol resolves a registered named schema.
+            params = Phlex::Reactive.param_schema(params) if params.is_a?(Symbol)
+            # If a scope is already declared, reject a schema nested under the scope
+            # key here (the scope-first declaration order). The action-first order is
+            # caught in reactive_scope.
+            scope = reactive_scope
+            assert_no_scope_double_nesting!(scope, params, name.to_sym) if scope
             Registry.write_entry(
               self, :actions, name.to_sym,
               Action.new(name: name.to_sym, params: params, schema: Phlex::Reactive::ParamSchema.compile(params))
@@ -127,12 +214,17 @@ module Phlex
             Registry.resolve_hash(self, :actions, :reactive_actions)
           end
 
+          # Issue #186: the fetch-one readers are removed — the plural
+          # reactive_actions hash IS the fetch-one. Guided errors name the rewrite.
           def reactive_action(name)
-            reactive_actions[name.to_sym]
+            raise NoMethodError,
+              "reactive_action(#{name.inspect}) was removed in issue #186 — use reactive_actions[#{name.inspect}]"
           end
 
           def reactive_action?(name)
-            reactive_actions.key?(name.to_sym)
+            raise NoMethodError,
+              "reactive_action?(#{name.inspect}) was removed in issue #186 — " \
+              "use reactive_actions.key?(#{name.inspect})"
           end
 
           # Opt out of the default-ON verify_authorized guard (issue #168).
@@ -181,9 +273,10 @@ module Phlex
           #     empty: ItemsEmptyComponent, # optional empty-state component
           #     size: -> { @record.items.size } # resolves the live size
           #
-          # An action then governs the reply with one call:
-          #   reply.append(:items, item)   # row append + count + clear empty-state
-          #   reply.remove(:items, id)     # row remove + count + restore empty-state
+          # An action then governs the reply with one call (the collection is
+          # named by the to:/from: keyword, issue #182):
+          #   reply.append(item, to: :items)   # row append + count + clear empty-state
+          #   reply.remove(id, from: :items)   # row remove + count + restore empty-state
           #
           # count/empty/size are optional: a list with just rows omits them and the
           # corresponding stream isn't emitted. See Phlex::Reactive::Reply and the
@@ -199,12 +292,17 @@ module Phlex
             Registry.resolve_hash(self, :collections, :reactive_collections)
           end
 
+          # Issue #186: use the plural reactive_collections hash directly.
           def reactive_collection_def(name)
-            reactive_collections[name.to_sym]
+            raise NoMethodError,
+              "reactive_collection_def(#{name.inspect}) was removed in issue #186 — " \
+              "use reactive_collections[#{name.inspect}]"
           end
 
           def reactive_collection?(name)
-            reactive_collections.key?(name.to_sym)
+            raise NoMethodError,
+              "reactive_collection?(#{name.inspect}) was removed in issue #186 — " \
+              "use reactive_collections.key?(#{name.inspect})"
           end
 
           # Declare a client-side computation, OR (called with just a name) read
@@ -262,17 +360,13 @@ module Phlex
           # the client interpreter re-checks the same shape).
           def reactive_compute(name, inputs: nil, outputs: nil, reducer: nil, mirror: nil)
             if inputs.nil? && outputs.nil?
-              # The bare form is the GETTER — a mirror: passed here would be
-              # silently dropped, so refuse it LOUDLY (declare-time validation,
-              # same posture as normalize_compute_mirror's selector check).
-              unless mirror.nil?
-                raise ArgumentError,
-                  "#{self}: reactive_compute(#{name.inspect}, mirror: ...) without inputs:/outputs: " \
-                  "is the getter form — the mirror would be silently dropped. Declare the mirror " \
-                  "alongside inputs:/outputs:."
-              end
-
-              return reactive_compute_def(name)
+              # Issue #186: the bare getter form is removed — reactive_compute is
+              # the SETTER now; read one compute via the plural hash. (Raising here
+              # keeps the getter/setter overload from silently misfiring.)
+              raise ArgumentError,
+                "reactive_compute(#{name.inspect}) getter was removed in issue #186 — " \
+                "use reactive_computes[#{name.inspect}]. reactive_compute is the declarative " \
+                "SETTER now: reactive_compute(:name, inputs:, outputs:)."
             end
 
             input_names, input_types = normalize_compute_inputs(inputs)
@@ -294,28 +388,59 @@ module Phlex
           # reactive_collection_def (issue #115). The bare reactive_compute(name)
           # getter above is a PERMANENT documented alias (it shipped in the same
           # minor series, #73); both stay, no deprecation.
+          # Issue #186: use the plural reactive_computes hash directly.
           def reactive_compute_def(name)
-            reactive_computes[name.to_sym]
+            raise NoMethodError,
+              "reactive_compute_def(#{name.inspect}) was removed in issue #186 — " \
+              "use reactive_computes[#{name.inspect}]"
           end
 
           def reactive_compute?(name)
-            reactive_computes.key?(name.to_sym)
+            raise NoMethodError,
+              "reactive_compute?(#{name.inspect}) was removed in issue #186 — " \
+              "use reactive_computes.key?(#{name.inspect})"
           end
 
-          # Split the `inputs:` argument into [ordered names, types-or-nil] (issue
-          # #104). A HASH ({ title: :string, qty: :number }) yields typed inputs —
-          # the ordered keys plus a symbolized name→type map. Anything else (an
-          # array, a bare symbol) is the UNTYPED form — ordered names and nil types,
-          # so the array-form wire stays byte-identical and the client keeps its
-          # numeric coercion. Named after the shape it normalizes.
+          # Split the `inputs:` argument into [ordered names, types-or-nil].
+          # THREE shapes, all degenerate cases of the issue-#183 PERMIT form
+          # (bare symbols default to :number; a trailing Hash types the exceptions):
+          #
+          #   * a pure Hash ({ title: :string, qty: :number }) — the issue-#104 typed
+          #     form. Ordered keys + a name→type map.
+          #   * a permit Array with a trailing Hash ([:qty, { title: :string }]) —
+          #     bare symbols typed :number, the Hash keys typed as declared. This is
+          #     the one form the issue-#183 docs show.
+          #   * a bare Array/symbol ([:price, :qty]) — the issue-#73 UNTYPED form.
+          #     nil types, so the array-form wire stays byte-identical and the client
+          #     keeps its numeric coercion.
+          #
+          # Named after the shape it normalizes.
           def normalize_compute_inputs(inputs)
-            if inputs.is_a?(Hash)
-              names = inputs.keys.map(&:to_sym)
-              types = inputs.transform_keys(&:to_sym).transform_values(&:to_sym)
-              [names, types]
-            else
-              [Array(inputs).map(&:to_sym), nil]
-            end
+            return normalize_typed_compute_inputs(inputs) if inputs.is_a?(Hash)
+
+            # dup before popping: Array(inputs) returns the SAME object for an array
+            # arg, so an unguarded pop would mutate (or FrozenError on) a shared or
+            # frozen inputs array the caller still holds.
+            list = Array(inputs).dup
+            trailing = list.last.is_a?(Hash) ? list.pop : nil
+            names = list.map(&:to_sym)
+
+            # No trailing type Hash → the untyped array form (nil types).
+            return [names, nil] if trailing.nil?
+
+            # Permit form: bare names default to :number; the trailing Hash types
+            # the exceptions. Declaration order is bare names, then the Hash keys.
+            typed = trailing.transform_keys(&:to_sym).transform_values(&:to_sym)
+            ordered = names + typed.keys
+            types = names.to_h { [it, :number] }.merge(typed)
+            [ordered, types]
+          end
+
+          # A pure Hash of name => type (issue #104): ordered keys + the type map.
+          def normalize_typed_compute_inputs(inputs)
+            names = inputs.keys.map(&:to_sym)
+            types = inputs.transform_keys(&:to_sym).transform_values(&:to_sym)
+            [names, types]
           end
 
           # Normalize `mirror:` to { name => [id selectors] } (nil passes