phlex-reactive 0.10.0 → 0.11.0

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

@@ -76,7 +76,50 @@ module Phlex
           def reactive_scope(name = nil)
             return Registry.resolve_scalar(self, :scope, :reactive_scope) if name.nil?
 
-            Registry.write_scalar(self, :scope, name.to_sym)
+            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.
@@ -149,6 +192,13 @@ module Phlex
           # ({ "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))
@@ -164,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).
@@ -218,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
@@ -236,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
@@ -299,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)
@@ -331,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