phlex-reactive 0.11.7 → 0.12.1

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

@@ -122,6 +122,72 @@ module Phlex
             Registry.resolve_scalar(self, :dirty, :reactive_dirty_config)
           end
 
+          # Effects (issue #215): declare how THIS component animates when a
+          # stream renders it — enter (append/prepend), exit (remove), update
+          # (replace/update, plain or morph). Refines the global
+          # Phlex::Reactive.effects set per hook (most specific wins); works
+          # standalone too — declaring on a component IS that component's
+          # opt-in, no global switch required.
+          #
+          #   reactive_effects enter: :slide, exit: :fade   # built-ins (shipped CSS)
+          #   reactive_effects update: false                # disable one hook
+          #   reactive_effects false                        # opt out entirely
+          #   reactive_effects enter: :random               # random built-in per application
+          #   reactive_effects enter: { during: %w[transition-all], from: %w[opacity-0],
+          #                             to: %w[opacity-100] }  # custom #186 legs
+          #
+          # Validated HERE (class load), not at render time — a typo'd effect
+          # name raises immediately. Stored as pre-compiled wire strings.
+          def reactive_effects(opt_out = nil, **hooks)
+            if opt_out == false
+              unless hooks.empty?
+                raise ArgumentError,
+                  "reactive_effects false opts the component out entirely — it takes no hooks " \
+                  "(got #{hooks.keys.inspect}); use per-hook false to disable one: update: false"
+              end
+              return Registry.write_scalar(self, :effects, false)
+            end
+            unless opt_out.nil?
+              raise ArgumentError,
+                "reactive_effects takes hook keywords (enter:/exit:/update:) or false — got #{opt_out.inspect}"
+            end
+            if hooks.empty?
+              raise ArgumentError,
+                "reactive_effects needs at least one hook (enter:/exit:/update:) or false to opt out"
+            end
+
+            Registry.write_scalar(self, :effects, Phlex::Reactive::Effects.normalize!(hooks))
+          end
+
+          # The raw declaration ({ hook => wire | false }, false for a full
+          # opt-out, or nil when undeclared), inherited through the Registry
+          # like every other scalar.
+          def reactive_effects_config
+            Registry.resolve_scalar(self, :effects, :reactive_effects_config)
+          end
+
+          # The RESOLVED root effect attrs (global ⊕ component, false hooks
+          # dropped): a frozen { reactive_effect_enter: "fade", … } fragment
+          # reactive_attrs merges into the root's data:, or nil when off.
+          # Memoized per class against BOTH inputs that can change the answer
+          # — the effects config generation (a Phlex::Reactive.effects= write)
+          # and the registry generation (any declaration) — as two integer
+          # compares, because reactive_attrs is the token-signing hot path.
+          # The race on a concurrent first call is benign (idempotent rebuild).
+          def reactive_effect_attrs
+            effects_gen = Phlex::Reactive.effects_generation
+            registry_gen = Registry.generation
+            if @reactive_effect_attrs_effects_gen == effects_gen &&
+               @reactive_effect_attrs_registry_gen == registry_gen
+              return @reactive_effect_attrs
+            end
+
+            @reactive_effect_attrs = Phlex::Reactive::Effects.root_attrs_for(self)
+            @reactive_effect_attrs_effects_gen = effects_gen
+            @reactive_effect_attrs_registry_gen = registry_gen
+            @reactive_effect_attrs
+          end
+
           # Opt into signed STATE for record-less components only.
           #   reactive_state :count, :open
           def reactive_state(*names)

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

@@ -91,6 +91,13 @@ module Phlex
           if self.class.respond_to?(:reactive_scope) && (scope = self.class.reactive_scope)
             data[:reactive_scope] = scope.to_s
           end
+          # Effects (issue #215): the resolved global ⊕ component hooks ride the
+          # root as data-reactive-effect-<hook> so the client's stream interceptor
+          # knows how to animate this component. nil when off — no keys, byte-
+          # stable wire. The fragment is a per-class memo (two integer compares).
+          if self.class.respond_to?(:reactive_effect_attrs) && (effects = self.class.reactive_effect_attrs)
+            data.merge!(effects)
+          end
           { data: }
         end
 
@@ -897,8 +904,23 @@ module Phlex
         # A row's remove trigger — client-only. Draft rows leave the DOM;
         # persisted rows (a hidden [_destroy] input present) are marked and
         # hidden instead, so Rails destroys them on save.
-        def reactive_nested_remove
-          { type: "button", data: { action: "click->reactive#nestedRemove" } }
+        #
+        # CONFIRM (issue #218). Removing a row can be a real loss (line items
+        # with entered amounts), so this trigger accepts the SAME confirm: the
+        # other triggers (on/on_client) do — routed through the shared
+        # apply_confirm!, so the client gates the remove behind the overridable
+        # confirmResolver (the styled-modal seam, #52/#55/#178). A String is
+        # the static message; a Hash is the CONDITIONAL form (#179) — prompt
+        # only when { when: … } matches or a { predicate: … } fires. Per-row
+        # messages come for free: the app builds a different string per row at
+        # render time. No confirm: → the plain immediate-remove fast path,
+        # unchanged.
+        #
+        #   button(**reactive_nested_remove(confirm: "Really delete #{row.name}?")) { "×" }
+        def reactive_nested_remove(confirm: nil)
+          data = { action: "click->reactive#nestedRemove" }
+          apply_confirm!(data, confirm) if confirm
+          { type: "button", data: }
         end
 
         # CROSS-ROOT value-conditional visibility (issue #164) — the visibility

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

@@ -57,6 +57,8 @@ module Phlex
           dirty: :@reactive_own_dirty,
           # Deferred reply segments — reactive_lazy (issue #165).
           lazy: :@reactive_own_lazy,
+          # Enter/exit/update effects — reactive_effects (issue #215).
+          effects: :@reactive_own_effects,
           # verify_authorized opt-out (issue #168): a scalar bare flag (skip the
           # WHOLE component) plus a list of named actions.
           skip_all: :@reactive_own_skip_all,

data/lib/phlex/reactive/effects.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The effects vocabulary (issue #215): animate a component's ENTER
+    # (append/prepend), EXIT (remove), and UPDATE (replace/update, plain or
+    # morph) when a Turbo Stream renders. Strictly OPT-IN at three levels,
+    # most specific wins:
+    #
+    #   Phlex::Reactive.effects = true                    # global default set
+    #   reactive_effects enter: :slide, update: false     # per component
+    #   reply.remove(effect: :shake)                      # per call
+    #
+    # An effect value is a BUILT-IN name (:fade/:slide/:scale/:highlight/
+    # :shake — shipped as CSS in app/assets/stylesheets/phlex/reactive/
+    # effects.css), :random (the client picks a built-in per application),
+    # false (disable the hook), or custom NAMED LEGS { during:, from:, to: }
+    # — the issue #186 class-list vocabulary, compiled to the same
+    # [during, from, to] wire array the client's runTransition consumes.
+    #
+    # This module owns normalization (declare-time validation — a typo'd
+    # effect raises at class load / config time, not at click time) and the
+    # WIRE forms:
+    #   * root attrs:  data-reactive-effect-enter="fade" (emitted by
+    #     reactive_attrs; resolved global ⊕ component)
+    #   * per call:    data-reactive-effect="shake" on the <turbo-stream>
+    #     element itself ("off" suppresses; beats the root attrs)
+    # Values are either a name or the legs JSON array — the client
+    # distinguishes by the leading "[".
+    module Effects
+      HOOKS = %i[enter exit update].freeze
+      BUILT_INS = %w[fade slide scale highlight shake].freeze
+      RANDOM = "random"
+      OFF = "off"
+      LEG_KEYS = %i[during from to].freeze
+
+      # The `effects = true` sugar — pre-normalized wire strings.
+      DEFAULTS = { enter: "fade", exit: "fade", update: "highlight" }.freeze
+
+      class << self
+        # Normalize the Phlex::Reactive.effects= value: nil/false → off (nil),
+        # true → the default set, a Hash → validated per-hook wire strings.
+        def normalize_config(value)
+          case value
+          when nil, false then nil
+          when true then DEFAULTS
+          when Hash then normalize!(value)
+          else
+            raise ArgumentError,
+              "Phlex::Reactive.effects takes nil/false (off), true (the default set), or a " \
+              "{ enter:/exit:/update: } hash — got #{value.inspect}"
+          end
+        end
+
+        # Validate + compile a per-hook declaration hash to its stored form:
+        # { hook => wire-string | false }. `false` survives normalization so a
+        # component-level `update: false` can OVERRIDE a global update effect
+        # at resolve time (the merge keeps it; attr emission skips it).
+        def normalize!(hooks)
+          hooks.each_with_object({}) do |(hook, value), out|
+            key = hook.to_sym
+            unless HOOKS.include?(key)
+              raise ArgumentError,
+                "unknown effects hook #{hook.inspect} — valid hooks: #{HOOKS.join(", ")}"
+            end
+            out[key] = value == false ? false : wire_value(value)
+          end.freeze
+        end
+
+        # The RESOLVED root attrs for a component class: global ⊕ component
+        # (Hash#merge — the component's per-hook values win), false hooks
+        # dropped at emission (they exist to cancel a global hook), the whole
+        # thing nil when everything is off. `reactive_effects false` opts the
+        # class out regardless of the global set. Returns a frozen
+        # { reactive_effect_<hook>: wire } fragment ready for data.merge!.
+        def root_attrs_for(klass)
+          component = klass.respond_to?(:reactive_effects_config) ? klass.reactive_effects_config : nil
+          return nil if component == false
+
+          global = Phlex::Reactive.effects
+          resolved =
+            if global && component then global.merge(component)
+            else global || component
+            end
+          return nil if resolved.nil? || resolved.empty?
+
+          attrs = {}
+          resolved.each do |hook, wire|
+            attrs[:"reactive_effect_#{hook}"] = wire unless wire == false
+          end
+          attrs.empty? ? nil : attrs.freeze
+        end
+
+        # Stamp a built turbo-stream tag with the PER-CALL effect override:
+        # `data-reactive-effect` on the <turbo-stream> element itself (it beats
+        # the root-declared attrs on the client; "off" suppresses them). String
+        # injection into the opening tag — turbo-rails' TagBuilder only takes
+        # `method:` as a tag attribute, and hand-built escaped attrs are the
+        # to_stream_token precedent. `.sub` hits the FIRST "<turbo-stream",
+        # which is always the opening tag (template content is escaped or
+        # nested later). nil = not given → the input passes through UNTOUCHED
+        # (byte-identical wire). Value validated + escaped — a legs JSON's
+        # quotes land as &quot;.
+        def annotate(html, effect)
+          return html if effect.nil?
+
+          attr = %( data-reactive-effect="#{ERB::Util.html_escape(wire_value(effect))}")
+          html.to_s.sub("<turbo-stream", "<turbo-stream#{attr}").html_safe
+        end
+
+        # ONE effect value → its wire string: a built-in/random name, "off"
+        # (per-call suppression), or the legs JSON array.
+        def wire_value(value)
+          case value
+          when false then OFF
+          when Symbol, String then named_wire(value.to_s)
+          when Hash then legs_wire(value)
+          when Array then raise_positional_legs(value)
+          else
+            raise ArgumentError,
+              "effect must be a built-in (#{BUILT_INS.join(", ")}), :random, false, or " \
+              "{ during:, from:, to: } legs — got #{value.inspect}"
+          end
+        end
+
+        private
+
+        def named_wire(name)
+          return name if name == RANDOM || BUILT_INS.include?(name)
+
+          raise ArgumentError,
+            "unknown effect #{name.inspect} — built-ins: #{BUILT_INS.join(", ")}, :random, " \
+            "or { during:, from:, to: } legs"
+        end
+
+        # Named legs (issue #186 vocabulary) → the [during, from, to] wire
+        # array runTransition consumes. Class lists may be a String or an
+        # Array of strings. A SINGLE blank leg is legitimate (an element whose
+        # own CSS carries the `transition` property needs no during: utilities
+        # — the same tolerance js.rb's normalize_transition gives), but ALL
+        # legs blank is a dead effect with nothing to animate — fail loudly,
+        # like the empty-ops-chain guard in js_ops_json.
+        def legs_wire(legs)
+          unless LEG_KEYS.all? { legs.key?(it) }
+            raise ArgumentError,
+              "effect legs must name during:, from:, to: class lists — got #{legs.inspect}"
+          end
+
+          compiled = LEG_KEYS.map { Array(legs[it]).join(" ") }
+          if compiled.all? { it.strip.empty? }
+            raise ArgumentError,
+              "effect legs are all blank — a dead effect with no classes to animate; got #{legs.inspect}"
+          end
+
+          JSON.generate(compiled)
+        end
+
+        # The old positional triple — reject with the named-legs rewrite, the
+        # same guidance js.rb's normalize_transition gives (issue #186).
+        def raise_positional_legs(value)
+          d, f, t = value
+          raise ArgumentError,
+            "effect legs take named keys (issue #186 vocabulary) — " \
+            "{ during: #{d.inspect}, from: #{f.inspect}, to: #{t.inspect} }"
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/engine.rb

@@ -30,6 +30,10 @@ module Phlex
       initializer "phlex_reactive.assets" do
         if it.config.respond_to?(:assets)
           it.config.assets.paths << root.join("app/javascript").to_s
+          # The opt-in effects stylesheet (issue #215): built-in enter/exit/
+          # update animations, linked by the app with
+          # stylesheet_link_tag "phlex/reactive/effects".
+          it.config.assets.paths << root.join("app/assets/stylesheets").to_s
           it.config.assets.precompile += %w[
             phlex/reactive/reactive_controller.min.js
             phlex/reactive/reactive_controller.min.js.map
@@ -41,6 +45,7 @@ module Phlex
             phlex/reactive/compute.min.js.map
             phlex/reactive/inspect.min.js
             phlex/reactive/inspect.min.js.map
+            phlex/reactive/effects.css
           ]
         end
       end

data/lib/phlex/reactive/reply.rb

@@ -29,20 +29,23 @@ module Phlex
 
       # Re-render in place. `morph: true` morphs the subtree (preserves the
       # focused input + caret) instead of an outerHTML swap — see #morph.
-      def replace(morph: false)
-        Response.build_replace(@component, morph:)
+      # `effect:` (issue #215) — the per-call effect override for this one
+      # stream (a built-in name, :random, false to suppress, or #186 legs);
+      # same kwarg on every verb below.
+      def replace(morph: false, effect: nil)
+        Response.build_replace(@component, morph:, effect:)
       end
 
       # Re-render in place via Idiomorph (method="morph") — keeps focus + caret.
-      def morph
-        Response.build_morph(@component)
+      def morph(effect: nil)
+        Response.build_morph(@component, effect:)
       end
 
       # Update only inner HTML (preserves the root element + its token attr).
       # `morph: true` morphs the inner HTML in place (issue #113) so a
       # cross-tab/per-field update keeps a focused input's caret.
-      def update(morph: false)
-        Response.build_update(@component, morph:)
+      def update(morph: false, effect: nil)
+        Response.build_update(@component, morph:, effect:)
       end
 
       # Reactive collections (issue #35) — add/remove a row in a declared
@@ -59,12 +62,14 @@ module Phlex
       # Extra kwargs (issue #186) thread to the row component's new(model:, **row_kwargs)
       # — e.g. reply.append(item, to: :items, autofocus: true) → ItemRow.new(item:,
       # autofocus: true). Additive: a no-kwarg call is byte-identical to before.
-      def append(model = UNSET_ARG, legacy_model = UNSET_ARG, to: UNSET_ARG, **row_kwargs)
-        collection_build!(:build_collection_append, :append, model, legacy_model, to, row_kwargs)
+      # `effect:` (issue #215) is reserved as the row's per-call effect — it is
+      # NOT forwarded to the row component's init like the other row_kwargs.
+      def append(model = UNSET_ARG, legacy_model = UNSET_ARG, to: UNSET_ARG, effect: nil, **row_kwargs)
+        collection_build!(:build_collection_append, :append, model, legacy_model, to, effect, row_kwargs)
       end
 
-      def prepend(model = UNSET_ARG, legacy_model = UNSET_ARG, to: UNSET_ARG, **row_kwargs)
-        collection_build!(:build_collection_prepend, :prepend, model, legacy_model, to, row_kwargs)
+      def prepend(model = UNSET_ARG, legacy_model = UNSET_ARG, to: UNSET_ARG, effect: nil, **row_kwargs)
+        collection_build!(:build_collection_prepend, :prepend, model, legacy_model, to, effect, row_kwargs)
       end
 
       # Two forms, dispatched on the PRESENCE of `from:` (issue #182 — no sentinel
@@ -74,17 +79,17 @@ module Phlex
       #
       #   reply.remove                       # remove the bound component's element
       #   reply.remove(model, from: :items)  # remove a collection row
-      def remove(model = UNSET_ARG, legacy_model = UNSET_ARG, from: UNSET_ARG)
+      def remove(model = UNSET_ARG, legacy_model = UNSET_ARG, from: UNSET_ARG, effect: nil)
         reject_legacy_form!(:remove, model, legacy_model)
         # Bare `reply.remove` (no positional, no from:) removes self.
-        return Response.build_remove(@component) if from.equal?(UNSET_ARG) && model.equal?(UNSET_ARG)
+        return Response.build_remove(@component, effect:) if from.equal?(UNSET_ARG) && model.equal?(UNSET_ARG)
 
         if from.equal?(UNSET_ARG)
           raise ArgumentError,
             "reply.remove(model, …) needs a source collection — reply.remove(model, from: :name)"
         end
         reject_symbol_first!(:remove, model, :from, from)
-        Response.build_collection_remove(@component, from, resolve_row_arg(model))
+        Response.build_collection_remove(@component, from, resolve_row_arg(model), effect:)
       end
 
       # Subject-free builders — pass straight through so they read naturally.
@@ -136,7 +141,7 @@ module Phlex
       # Shared append/prepend build: catch the old two-positional form, require the
       # `to:` keyword, reject a Symbol-first model, then delegate to the Response
       # builder (name first, model second — its internal order).
-      def collection_build!(builder, verb, model, legacy_model, to, row_kwargs)
+      def collection_build!(builder, verb, model, legacy_model, to, effect, row_kwargs)
         # Old form `reply.append(:name, model)` passes a SECOND positional — the
         # arity would just error, so intercept it with the guided rewrite.
         reject_legacy_form!(verb, model, legacy_model)
@@ -145,7 +150,7 @@ module Phlex
             "reply.#{verb} needs a target collection — reply.#{verb}(model, to: :name)"
         end
         reject_symbol_first!(verb, model, :to, to)
-        Response.public_send(builder, @component, to, resolve_row_arg(model), **row_kwargs)
+        Response.public_send(builder, @component, to, resolve_row_arg(model), effect:, **row_kwargs)
       end
 
       # The pre-#182 call `reply.<verb>(:name, model)` — a Symbol name first, the

data/lib/phlex/reactive/response.rb

@@ -58,8 +58,10 @@ module Phlex
         # Re-render the component in place (explicit form of today's default).
         # `morph: true` morphs the subtree (preserves the focused input + caret)
         # instead of an outerHTML swap — see .build_morph (issue #28).
-        def build_replace(component, morph: false)
-          new(streams: [component.to_stream_replace(morph:)],
+        # `effect:` (issue #215) stamps the per-call effect override on the
+        # emitted stream — same on every self-targeting builder below.
+        def build_replace(component, morph: false, effect: nil)
+          new(streams: [component.to_stream_replace(morph:, effect:)],
             subject_component: component)
         end
 
@@ -69,19 +71,23 @@ module Phlex
         # per-field reactive editing (a "spreadsheet" grid where a debounced save
         # fires while the user is still typing/tabbing). The morphed root still
         # carries the fresh signed token, so the next action verifies.
-        def build_morph(component) = new(streams: [component.to_stream_replace(morph: true)], subject_component: component)
+        def build_morph(component, effect: nil)
+          new(streams: [component.to_stream_replace(morph: true, effect:)], subject_component: component)
+        end
 
         # Update only inner HTML (preserves the root element + its token attr).
         # `morph: true` morphs the inner HTML in place (issue #113) instead of
         # replacing it, so a cross-tab update keeps a peer's focus/caret.
-        def build_update(component, morph: false)
-          new(streams: [component.to_stream_update(morph:)], subject_component: component)
+        def build_update(component, morph: false, effect: nil)
+          new(streams: [component.to_stream_update(morph:, effect:)], subject_component: component)
         end
 
         # Remove the component's element from the DOM. Uses the instance
         # to_stream_remove (the component already knows its own #id — no
         # class-builder reconstruction; works for record- and state-backed).
-        def build_remove(component) = new(streams: [component.to_stream_remove], render_self: false)
+        def build_remove(component, effect: nil)
+          new(streams: [component.to_stream_remove(effect:)], render_self: false)
+        end
 
         # Client-side full navigation (Turbo.visit). Use when the current URL
         # is dead (slug rename) or the outcome belongs on another page. Pass a
@@ -110,21 +116,24 @@ module Phlex
         # container owns the add/remove trigger, so the endpoint appends its inert
         # `reactive:token` stream (the same #30 machinery reply.streams uses) to roll
         # the token forward without re-rendering the rows.
-        def build_collection_append(component, name, model, **row_kwargs)
+        # `effect:` (issue #215) stamps the ROW stream only — the count
+        # companion and the empty-state toggle are bookkeeping, not the thing
+        # entering/leaving.
+        def build_collection_append(component, name, model, effect: nil, **row_kwargs)
           definition = collection_def!(component, name)
-          new(streams: collection_add_streams(definition, component, model, :append, row_kwargs),
+          new(streams: collection_add_streams(definition, component, model, :append, row_kwargs, effect:),
             render_self: false, token_component: component)
         end
 
-        def build_collection_prepend(component, name, model, **row_kwargs)
+        def build_collection_prepend(component, name, model, effect: nil, **row_kwargs)
           definition = collection_def!(component, name)
-          new(streams: collection_add_streams(definition, component, model, :prepend, row_kwargs),
+          new(streams: collection_add_streams(definition, component, model, :prepend, row_kwargs, effect:),
             render_self: false, token_component: component)
         end
 
-        def build_collection_remove(component, name, model)
+        def build_collection_remove(component, name, model, effect: nil)
           definition = collection_def!(component, name)
-          new(streams: collection_remove_streams(definition, component, model),
+          new(streams: collection_remove_streams(definition, component, model, effect:),
             render_self: false, token_component: component)
         end
 
@@ -141,10 +150,10 @@ module Phlex
         # Row add (append/prepend) + count + empty-state clear. The empty-state is
         # removed only when the list just crossed 0->1 (size == 1) — appending to
         # an already-populated list leaves it untouched.
-        def collection_add_streams(definition, component, model, action, row_kwargs = {})
+        def collection_add_streams(definition, component, model, action, row_kwargs = {}, effect: nil)
           # row_kwargs (issue #186) thread to the row component's init via the class
           # stream builder's **options passthrough (ItemRow.new(model:, **row_kwargs)).
-          streams = [definition.item.public_send(action, target: definition.container, model:, **row_kwargs)]
+          streams = [definition.item.public_send(action, target: definition.container, model:, effect:, **row_kwargs)]
           append_count_stream(streams, definition, component)
 
           size = definition.size_for(component)
@@ -154,8 +163,8 @@ module Phlex
 
         # Row remove + count + empty-state restore. The empty-state is appended
         # back into the container only when the list just emptied (size == 0).
-        def collection_remove_streams(definition, component, model)
-          streams = [collection_row_remove(definition, model)]
+        def collection_remove_streams(definition, component, model, effect: nil)
+          streams = [collection_row_remove(definition, model, effect)]
           append_count_stream(streams, definition, component)
 
           size = definition.size_for(component)
@@ -170,11 +179,11 @@ module Phlex
 
         # Remove the row by its DOM id. Accepts the record (so dom_id is derived)
         # or an already-built dom-id string (e.g. the value the row used as #id).
-        def collection_row_remove(definition, model)
+        def collection_row_remove(definition, model, effect = nil)
           if model.is_a?(String)
-            Phlex::Reactive.stream_builder.remove(model)
+            Phlex::Reactive::Effects.annotate(Phlex::Reactive.stream_builder.remove(model), effect)
           else
-            definition.item.remove(model)
+            definition.item.remove(model, effect:)
           end
         end