phlex-reactive 0.10.0 → 0.11.0

data/lib/phlex/reactive.rb

@@ -279,6 +279,82 @@ module Phlex
         @param_types_frozen = false
       end
 
+      # Register (with a schema Hash) OR read (bare name) a NAMED param schema
+      # (issue #184) — a reusable, boot-declared schema so sibling components stop
+      # duplicating verbatim constants that drift. Follows the param_type contract:
+      # register in an INITIALIZER (the registry freezes after boot).
+      #
+      #   # config/initializers/phlex_reactive.rb
+      #   Phlex::Reactive.param_schema :todo, title: :string, done: :boolean
+      #   # then: action :save, params: :todo
+      #   # compose:  action :bulk, params: { **Phlex::Reactive.param_schema(:todo), note: :string }
+      #
+      # Reading an unknown name raises, listing the registered ones. The stored
+      # schema is frozen; the reader returns it (compose with ** for a new Hash).
+      def param_schema(name, schema = nil)
+        return fetch_param_schema(name) if schema.nil?
+
+        if param_schemas_frozen?
+          raise Error, "Phlex::Reactive.param_schema(#{name.inspect}) called after boot — the param-schema " \
+                       "registry is frozen once the app is initialized. Register named schemas in an " \
+                       "initializer (config/initializers/phlex_reactive.rb)."
+        end
+
+        param_schemas[name.to_sym] = deep_freeze_schema(schema.transform_keys(&:to_sym))
+      end
+
+      def param_schemas
+        @param_schemas ||= {}
+      end
+
+      def param_schema?(name)
+        param_schemas.key?(name.to_sym)
+      end
+
+      def freeze_param_schemas!
+        param_schemas.freeze
+        @param_schemas_frozen = true
+      end
+
+      def param_schemas_frozen?
+        @param_schemas_frozen ||= false
+      end
+
+      # Drop the named-schema registry and unfreeze it (tests only).
+      def reset_param_schemas!
+        @param_schemas = {}
+        @param_schemas_frozen = false
+      end
+
+      private
+
+      # Deep-freeze a registered schema so a nested Hash/Array (a nested-param
+      # schema like { address: { street: :string } }) can't be mutated through the
+      # memoized object fetch_param_schema returns — a top-level freeze alone leaves
+      # inner structures writable, poisoning the shared registry entry. Symbolizes
+      # nested keys too so composed-in nested schemas stay canonical.
+      def deep_freeze_schema(value)
+        case value
+        when Hash then value.to_h { |k, v| [k.to_sym, deep_freeze_schema(v)] }.freeze
+        when Array then value.map { deep_freeze_schema(it) }.freeze
+        else value
+        end
+      end
+
+      # Resolve a registered named schema, raising a guided error (listing the
+      # registered names) for an unknown one — the action macro calls this to turn
+      # `params: :todo` into the schema Hash.
+      def fetch_param_schema(name)
+        param_schemas.fetch(name.to_sym) do
+          known = param_schemas.keys.sort.join(", ")
+          raise ::ArgumentError,
+            "Phlex::Reactive.param_schema(#{name.inspect}) is not registered. " \
+            "Registered schemas: #{known.empty? ? "(none)" : known}."
+        end
+      end
+
+      public
+
       # Emit an `<event>.phlex_reactive` ActiveSupport::Notifications event around
       # a block, yielding the mutable payload so a rescue can finalize the outcome
       # (issue #107). ASN.instrument is cheap when nothing is subscribed (the hot
@@ -560,13 +636,29 @@ module Phlex
       # diagnostic still goes to the log.
       attr_accessor :error_flash
 
-      # Component class used to render STRING flash content (issue #77).
-      # Instantiated as flash_component.new(level:, content:) and rendered
-      # through the existing render path, replacing the built-in
-      # <div class="reactive-flash reactive-flash--{level}"> wrapper. Default
-      # nil (the built-in wrapper). Phlex component content passed to
+      # A CALLABLE that builds a flash component from STRING flash content (issue
+      # #182). Given (level, content), it returns a Phlex component the gem renders
+      # in place of the built-in <div class="reactive-flash reactive-flash--{level}">
+      # wrapper — so the APP owns the kwarg mapping (no hardcoded new(level:,
+      # content:) contract that collides with a real app's flash component):
+      #
+      #   Phlex::Reactive.flash_component = ->(level, content) { MyFlash.new(level:, message: content) }
+      #
+      # Default nil (the built-in wrapper). Phlex component content passed to
       # reply.flash always renders verbatim and bypasses this.
-      attr_accessor :flash_component
+      attr_reader :flash_component
+
+      # Reject a bare Class (the pre-#182 contract) with the exact lambda rewrite —
+      # the gem no longer guesses the component's kwargs.
+      def flash_component=(callable)
+        if callable.is_a?(Class)
+          raise ArgumentError,
+            "Phlex::Reactive.flash_component is now a callable (issue #182) — " \
+            "flash_component = ->(level, content) { #{callable}.new(level:, content:) }"
+        end
+
+        @flash_component = callable
+      end
 
       # Render a Phlex component to HTML with a full (off-request) view context.
       # Uses phlex-rails' #render_in against the memoized view context — a direct
@@ -581,10 +673,36 @@ module Phlex
         Phlex::Reactive::Defer.with_real_render { component.render_in(off_request_view_context) }
       end
 
+      # Module-level broadcast (issue #185) — the same broadcast_to as the class
+      # form, for a BUILT component payload, so a NON-Streamable target (a count
+      # badge, any plain Phlex component) broadcasts WITHOUT hand-rolling the raw
+      # channel + render, and IS instrumented:
+      #
+      #   Phlex::Reactive.broadcast_to(@list, :todos, update: TodoCount.new(list: @list), target: "todos-count")
+      #   Phlex::Reactive.broadcast_to(user, :alerts, replace: NotificationsBadge.new(user:))
+      #
+      # Container verbs (update:/append:/prepend:) take any component; self-targeting
+      # verbs (replace:/remove:) require a Streamable payload (its #id is the target)
+      # — a plain component gets a guided error steering to update:. Shares the one
+      # broadcast implementation with the class-level form.
+      def broadcast_to(*streamables, morph: false, target: nil, exclude: nil, visible_to: nil, each: nil, **verb)
+        name, payload = Phlex::Reactive::Streamable.extract_module_broadcast_verb(verb)
+        component = name == :js ? nil : payload
+        keys = each ? each.map { Array(it) } : [streamables]
+        # The owner is the payload's class when Streamable (for js ops + instrument),
+        # else Streamable itself (a plain component still instruments via the shared
+        # path). A nil payload (a bare state-backed default) isn't supported here —
+        # the module form is for BUILT component payloads.
+        owner = payload.is_a?(Phlex::Reactive::Streamable) ? payload.class : Phlex::Reactive::Streamable
+        Phlex::Reactive::Streamable.broadcast_component(
+          owner, name, payload, component, keys, morph:, target:, exclude:, visible_to:
+        )
+      end
+
       # A Turbo::Streams::TagBuilder bound to an off-request view context, used
       # to build standalone streams not tied to a specific component's id — a
       # Response flash append, a reactive_collection row removal, a count
-      # companion update, an also_update companion. Cached PER THREAD alongside
+      # companion update, an also() companion. Cached PER THREAD alongside
       # the context it's bound to (see off_request_view_context for why
       # per-thread). Renamed from flash_builder (issue #113): the builder does
       # far more than flashes, so the name misled. flash_builder stays a
@@ -615,11 +733,18 @@ module Phlex
         @off_request_view_context_generation = off_request_view_context_generation + 1
       end
 
-      # Permanent aliases for the pre-#113 names. Kept forever (no deprecation)
-      # so the engine's to_prepare hook and any app code calling the old names
-      # keep working unchanged.
-      alias flash_builder stream_builder
-      alias reset_flash_builder! reset_stream_builder!
+      # Issue #182: the pre-#113 aliases are removed (they contradicted the
+      # clean-break rule — two names for one thing). Each raises a guided error
+      # naming the real method. The engine (to_prepare) already uses the new names.
+      def flash_builder
+        raise NoMethodError,
+          "Phlex::Reactive.flash_builder was removed in issue #182 — use stream_builder"
+      end
+
+      def reset_flash_builder!
+        raise NoMethodError,
+          "Phlex::Reactive.reset_flash_builder! was removed in issue #182 — use reset_stream_builder!"
+      end
 
       def off_request_view_context_generation
         @off_request_view_context_generation ||= 0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -123,6 +123,9 @@ files:
 - app/javascript/phlex/reactive/confirm.js
 - app/javascript/phlex/reactive/confirm.min.js
 - app/javascript/phlex/reactive/confirm.min.js.map
+- app/javascript/phlex/reactive/confirm_predicate.js
+- app/javascript/phlex/reactive/confirm_predicate.min.js
+- app/javascript/phlex/reactive/confirm_predicate.min.js.map
 - app/javascript/phlex/reactive/inspect.js
 - app/javascript/phlex/reactive/inspect.min.js
 - app/javascript/phlex/reactive/inspect.min.js.map