phlex-reactive 0.15.5 → 0.16.1

data/app/javascript/phlex/reactive/runtime.js

@@ -36,6 +36,7 @@ import * as devtoolsFeature from "phlex/reactive/features/devtools"
 import * as hintsFeature from "phlex/reactive/features/hints"
 import * as deferFeature from "phlex/reactive/features/defer"
 import * as sortableFeature from "phlex/reactive/features/sortable"
+import * as dragFeature from "phlex/reactive/features/drag"
 import * as presenceFeature from "phlex/reactive/features/presence"
 import * as countdownFeature from "phlex/reactive/features/countdown"
 
@@ -735,8 +736,9 @@ export function registerReactiveMorphFocus() {
 // through later morphs while focused, like `value`), a bubbling reactive:held
 // { name, theirs } is dispatched, and the root's next action sends the names as
 // X-Reactive-Held. The root's own reply never marks (it answers exactly those
-// values), and once applied the root holds nothing. A morph of the field while
-// unfocused writes the server's value and drops the mark with it.
+// values), and once applied the root holds nothing — unless it refused them
+// (X-Reactive-Refused, issue #413): then the marks it names stay. A morph of
+// the field while unfocused writes the server's value and drops the mark with it.
 const HELD = "data-reactive-held"
 const ROOT = '[data-controller~="reactive"]'
 let replyRoot = null
@@ -781,18 +783,35 @@ function heldHeader(root) {
   return JSON.stringify(names).replace(/[\u007f-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`)
 }
 
-function releaseHeld(root) {
-  for (const el of root.querySelectorAll(`[${HELD}]`)) if (el.closest(ROOT) === root) el.removeAttribute(HELD)
+// `keep`: true keeps every mark, a list keeps the marks of those names.
+function releaseHeld(root, keep) {
+  if (keep === true) return
+  for (const el of root.querySelectorAll(`[${HELD}]`)) {
+    if (el.closest(ROOT) === root && !keep?.includes(el.getAttribute("name"))) el.removeAttribute(HELD)
+  }
+}
+
+// What a reply refused (issue #413): "*" keeps every mark, a JSON list the
+// marks of those names. Anything else reads as a plain reply.
+function refusedHeader(response) {
+  const raw = response.headers.get("X-Reactive-Refused")
+  if (raw === "*") return true
+  try {
+    const names = JSON.parse(raw)
+    return Array.isArray(names) ? names : null
+  } catch {
+    return null
+  }
 }
 
 // Hand a root's own reply to Turbo: while its streams render nothing in the
-// root is marked, and once they have the root holds nothing. Turbo announces
-// each stream synchronously inside renderStreamMessage (streamOwnReply wraps
-// its render, innermost); a reply none of whose streams rendered releases now.
-// An error reply (release false) never marks either, but releases nothing: the
-// server refused those values rather than answering them.
-function renderOwnReply(root, html, release = true) {
-  const own = { root, streams: 0, release }
+// root is marked, and once they have the root holds nothing but what `keep`
+// names. Turbo announces each stream synchronously inside renderStreamMessage
+// (streamOwnReply wraps its render, innermost); a reply none of whose streams
+// rendered releases now. An error reply (keep true) never marks either, but
+// releases nothing: the server refused those values rather than answering them.
+function renderOwnReply(root, html, keep = null) {
+  const own = { root, streams: 0, keep }
   const previous = replyRoot
   replyRoot = own
   try {
@@ -800,7 +819,7 @@ function renderOwnReply(root, html, release = true) {
   } finally {
     replyRoot = previous
   }
-  if (release && own.streams === 0) releaseHeld(root)
+  if (own.streams === 0) releaseHeld(root, keep)
 }
 
 function streamOwnReply(event) {
@@ -817,7 +836,7 @@ function streamOwnReply(event) {
       const left = replying.get(own.root) - 1
       if (left) replying.set(own.root, left)
       else replying.delete(own.root)
-      if (own.release) releaseHeld(own.root)
+      releaseHeld(own.root, own.keep)
     }
   }
 }
@@ -2060,18 +2079,18 @@ function formNeeded(root) {
 // Show bindings and cross-root show targets, completion bindings, option
 // filtering, the bulk-selection group bindings (enable, select-all, count —
 // issue #319) and their cross-root targets (#343), the tag-chip input, draft
-// nested rows, editable text's keys and paste (#351) and media previews
-// (#373): a form's client-only bindings. The root declares one, or
-// owns an element that does. (The probes the connect-time gates ran before
-// the split, unchanged.)
+// nested rows, editable text's keys and paste (#351), media previews
+// (#373) and fields fed into CSS custom properties (#417): a form's
+// client-only bindings. The root declares one, or owns an element that does.
+// (The probes the connect-time gates ran before the split, unchanged.)
 function bindingsNeeded(root) {
   return (
-    ["show-targets", "group-targets", "on-complete", "filter-input", "tags-field"].some(
+    ["show-targets", "group-targets", "on-complete", "filter-input", "tags-field", "css-vars"].some(
       (marker) => root.getAttribute?.(`data-reactive-${marker}`) != null,
     ) ||
     (root.querySelectorAll?.("[data-reactive-show-field], [data-reactive-show]") ?? []).length > 0 ||
     root.querySelector?.(
-      "[data-reactive-nested-json], [data-reactive-nested-list], [data-reactive-confirm-when-param], [data-reactive-enable], [data-reactive-select-all], [data-reactive-count], [data-reactive-editable], [data-reactive-media]",
+      "[data-reactive-nested-json], [data-reactive-nested-list], [data-reactive-confirm-when-param], [data-reactive-enable], [data-reactive-select-all], [data-reactive-count], [data-reactive-editable], [data-reactive-media], [data-reactive-css-vars]",
     ) != null
   )
 }
@@ -2089,6 +2108,14 @@ function sortableNeeded(root) {
   return Boolean(root.matches?.(lists) || root.querySelector?.(lists))
 }
 
+// Draggable regions (issue #416): the root is, or holds, a frame, a box or a
+// point. (A nested root's frame loads the module for its parent too; the
+// module then checks ownership before it drags anything.)
+function dragNeeded(root) {
+  const marks = "[data-reactive-frame],[data-reactive-box],[data-reactive-point]"
+  return Boolean(root.matches?.(marks) || root.querySelector?.(marks))
+}
+
 // Presence (issue #358): the root is a reactive_presence roster.
 function presenceNeeded(root) {
   return root.getAttribute?.("data-reactive-presence") != null
@@ -2111,6 +2138,8 @@ const PRODUCTION_FEATURES = [
   ["compute", [computeNeeded, null, null, true]],
   // Nothing it does at connect is read by a request: it never gates.
   ["sortable", [sortableNeeded, null]],
+  // A drag writes fields only when the user drags: it never gates.
+  ["drag", [dragNeeded, null]],
   // Its announce is a request of its own; nothing it does at connect is read
   // by another request: it never gates.
   ["presence", [presenceNeeded, null]],
@@ -2279,7 +2308,7 @@ function featureTimeoutMs() {
 export function reactiveFeatureNames() {
   return __SPLIT__
     ? [...FEATURES.keys()]
-    : ["persist", "defer", "form", "bindings", "compute", "sortable", "presence", "countdown", "effects", "hints", "devtools"]
+    : ["persist", "defer", "form", "bindings", "compute", "sortable", "drag", "presence", "countdown", "effects", "hints", "devtools"]
 }
 
 export function __setReactiveFeatureForTest(name, needs, load, waiting, gates) {
@@ -2302,6 +2331,7 @@ export function __loadReactiveFeatureForTest(name) {
     bindings: bindingsFeature,
     compute: computeFeature,
     sortable: sortableFeature,
+    drag: dragFeature,
     presence: presenceFeature,
     countdown: countdownFeature,
     effects: effectsFeature,
@@ -2359,6 +2389,7 @@ const COMPUTE = 16
 const SORTABLE = 32
 const PRESENCE = 64
 const COUNTDOWN = 128
+const DRAG = 256
 
 // The default entry's features are part of this file: install them now, as
 // the opt-in entry does when one arrives.
@@ -2687,6 +2718,7 @@ export default class extends Controller {
       this.#connectFeatureNow(BINDINGS, "bindings", bindingsNeeded, (core) => bindingsFeature.connect(this, core, morphed))
       this.#connectFeatureNow(COMPUTE, "compute", computeNeeded, (core) => computeFeature.connect(this, core, morphed))
       this.#connectFeatureNow(SORTABLE, "sortable", sortableNeeded, (core) => sortableFeature.connect(this, core))
+      this.#connectFeatureNow(DRAG, "drag", dragNeeded, (core) => dragFeature.connect(this, core))
       this.#connectFeatureNow(PRESENCE, "presence", presenceNeeded, (core) => presenceFeature.connect(this, core))
       this.#connectFeatureNow(COUNTDOWN, "countdown", countdownNeeded, (core) => countdownFeature.connect(this, core))
     }
@@ -2726,6 +2758,7 @@ export default class extends Controller {
       if (on & BINDINGS) this.#disconnectFeatureNow("bindings", () => bindingsFeature.disconnect(this, core))
       if (on & COMPUTE) this.#disconnectFeatureNow("compute", () => computeFeature.disconnect(this, core))
       if (on & SORTABLE) this.#disconnectFeatureNow("sortable", () => sortableFeature.disconnect(this, core))
+      if (on & DRAG) this.#disconnectFeatureNow("drag", () => dragFeature.disconnect(this, core))
       if (on & PRESENCE) this.#disconnectFeatureNow("presence", () => presenceFeature.disconnect(this, core))
       if (on & COUNTDOWN) this.#disconnectFeatureNow("countdown", () => countdownFeature.disconnect(this, core))
     }
@@ -4096,7 +4129,7 @@ export default class extends Controller {
             if (__SPLIT__) this.#devtools((devtools) => devtools.recordBody(debug, errorBody, fresh))
             else devtoolsFeature.recordBody(debug, errorBody, fresh)
           }
-          renderOwnReply(this.element, errorBody, false)
+          renderOwnReply(this.element, errorBody, true)
         }
         this.#markError("http")
         this.#emitError(action, params, allParams, { kind: "http", status: response.status, body: errorBody })
@@ -4128,8 +4161,9 @@ export default class extends Controller {
       // outerHTML swap (focus on the replaced subtree is lost); a method="morph"
       // replace (Response.morph) or an update morphs in place, preserving the
       // focused input + caret on unchanged nodes — see issue #28. As the root's
-      // own reply, it clears what the root held (issue #370).
-      renderOwnReply(this.element, html)
+      // own reply, it clears what the root held (issue #370), but what it
+      // refused (issue #413).
+      renderOwnReply(this.element, html, refusedHeader(response))
       // Debug-only (issue #181): the morph may apply a microtask later, so check
       // the resurrected-hide case AFTER it lands. Off the debug path, resurrect is
       // null — zero cost.

data/lib/generators/phlex/reactive/install/templates/phlex_reactive.rb.erb

@@ -9,7 +9,8 @@
 # Phlex::Reactive.base_controller_name = "ApplicationController"
 
 # Render components with your app's view context (helpers, Current, etc.).
-# Phlex::Reactive.renderer = ApplicationController
+# By name, so it follows code reloading in development.
+# Phlex::Reactive.renderer = "ApplicationController"
 
 # Render your authorization library's error as 403 from a reactive action.
 # Phlex::Reactive.authorization_errors = [Pundit::NotAuthorizedError]

data/lib/phlex/reactive/apm/subscriber.rb

@@ -19,6 +19,11 @@ module Phlex
         # adapter can subscribe to them itself) — the action IS the transaction.
         EVENTS = /\A(?:action|defer)\.phlex_reactive\z/
 
+        # The one subscription and its adapter, class ivars on purpose and
+        # safe: install/uninstall run at boot, from the engine's
+        # after_initialize on the main Ractor (APM.attach!), and between
+        # examples in a test suite; the request path never touches them.
+        # rubocop:disable-next ThreadSafety/ClassInstanceVariable
         class << self
           # Install a single bus subscription for `adapter`. Idempotent for the
           # SAME adapter: a repeat call is a no-op. A DIFFERENT adapter replaces

data/lib/phlex/reactive/apm.rb

@@ -41,7 +41,7 @@ module Phlex
           # Memoize the instance PER SYMBOL so repeated detect/attach! calls return
           # the SAME object — Subscriber.install keys idempotency on adapter
           # identity (equal?), so a fresh klass.new each time would double-subscribe.
-          return (built_in_instances[apm] ||= klass.new) if klass.available?
+          return built_in_instances.fetch(apm) { klass.new } if klass.available?
 
           warn_and_nil("apm = #{apm.inspect} set but #{apm} is not loaded — no-op. " \
                        "Require the SDK (or remove the setting).")
@@ -68,17 +68,16 @@ module Phlex
         def reset!
           Subscriber.uninstall
           Phlex::Reactive.resolved_apm_adapter = nil
-          @built_in_instances = nil
+          built_in_instances.clear
         end
 
         private
 
         # Symbol => memoized built-in adapter instance. One instance per flavour for
         # the life of the process (cleared only by reset! in tests), so detect is
-        # identity-stable and attach! stays idempotent.
-        def built_in_instances
-          @built_in_instances ||= {}
-        end
+        # identity-stable and attach! stays idempotent. Per-Ractor state
+        # (Phlex::Reactive::Store), not a module ivar (zoolutions/phlex-reactive#364).
+        def built_in_instances = Phlex::Reactive::Store.table(:phlex_reactive_apm_adapters)
 
         def warn_and_nil(message)
           logger = Phlex::Reactive.send(:default_logger)

data/lib/phlex/reactive/authorization.rb

@@ -25,6 +25,10 @@ module Phlex
       MODULE_PREPEND = ::Module.instance_method(:prepend)
       private_constant :MODULE_PREPEND
 
+      # The per-Ractor lock (Phlex::Reactive::Store) the lazy instrument! path
+      # holds: one per Ractor, never shared across Ractors.
+      INSTRUMENT_LOCK_KEY = :phlex_reactive_authorization_instrument_lock
+
       class << self
         # Open a fresh tracking window, run the block, and restore the previous
         # cell — exactly the with_connection_id save/restore shape, so nesting is
@@ -73,14 +77,36 @@ module Phlex
         # a Zeitwerk reload's fresh class re-instruments naturally and a repeated
         # call in one process is a no-op. Re-reads authorization_methods each first
         # call, so an initializer that widened the list is honored.
+        #
+        # When the app eager-loads, the engine instruments every component class
+        # at boot (instrument_all!, zoolutions/phlex-reactive#364), so the
+        # endpoint's call is a bare "already instrumented" read and a request
+        # never mutates a class. The lazy path (development, or a class defined
+        # after boot) holds a lock across the check and the prepend, so two
+        # threads first-calling it for one class prepend ONE interceptor.
         def instrument!(component_class)
-          return if component_class.instance_variable_get(:@reactive_authorization_instrumented)
+          return if instrumented?(component_class)
 
-          names = Phlex::Reactive.authorization_methods.select do
-            component_class.method_defined?(it) || component_class.private_method_defined?(it)
+          Phlex::Reactive::Store.fetch(INSTRUMENT_LOCK_KEY) { Mutex.new }.synchronize do
+            next if instrumented?(component_class)
+
+            names = Phlex::Reactive.authorization_methods.select do
+              component_class.method_defined?(it) || component_class.private_method_defined?(it)
+            end
+            MODULE_PREPEND.bind_call(component_class, interceptor_for(names)) if names.any?
+            component_class.instance_variable_set(:@reactive_authorization_instrumented, true)
           end
-          MODULE_PREPEND.bind_call(component_class, interceptor_for(names)) if names.any?
-          component_class.instance_variable_set(:@reactive_authorization_instrumented, true)
+        end
+
+        # Instrument every reactive component class among `classes` (the
+        # engine passes Streamable.registered_classes at boot, after eager
+        # loading). Plain Streamable classes have no actions to guard.
+        def instrument_all!(classes)
+          classes.each { instrument!(it) if it.include?(Phlex::Reactive::Component) }
+        end
+
+        def instrumented?(component_class)
+          component_class.instance_variable_get(:@reactive_authorization_instrumented) ? true : false
         end
 
         private

data/lib/phlex/reactive/client_bindings.rb

@@ -52,6 +52,25 @@ module Phlex
 
       include Component::DSL
       include Component::Helpers
+
+      # Tracked so the engine warms every class with the DSL at boot, a
+      # client-only one too (zoolutions/phlex-reactive#364). A subclass
+      # inherits the module rather than including it, so `included` never
+      # fires for it.
+      included do
+        Phlex::Reactive::Component::Registry.track(self)
+      end
+
+      class_methods do
+        def inherited(subclass)
+          super
+          Phlex::Reactive::Component::Registry.track(subclass)
+        end
+      end
+
+      # ActiveSupport::Concern's bookkeeping on this module, sealed now that
+      # the body has loaded (zoolutions/phlex-reactive#364).
+      Phlex::Reactive::Shareable.seal_concern(self)
     end
   end
 end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # Fields that feed CSS custom properties on an element (issue #417): a
+      # preview that follows a control, with no request.
+      #
+      #   div(**mix(reactive_root(id: "light"), reactive_css_vars(to: "#sample", vars: {
+      #     "--light" => "light",                       # field name -> custom property
+      #     "--turn"  => { field: "turn", unit: "deg" } # with a unit from UNITS
+      #   }))) do
+      #     input(type: "range", name: "light", min: "0.5", max: "1.5", step: "0.01", value: "1")
+      #     img(id: "sample", alt: "", style: "--light: 1; filter: brightness(var(--light, 1))")
+      #   end
+      #
+      # The client reads each field the way reactive_show does (owned fields, a
+      # radio group's checked value, reactive_scope applied; a checkbox gives 1
+      # or 0), parses it as a finite number and writes
+      # style.setProperty(name, number + unit) on every `to:` element. Anything
+      # else (empty, text, NaN) removes the property, so the author's var()
+      # fallback applies. No string from a field ever reaches CSS: the wire
+      # carries names and units, never a value. It runs on connect, on the
+      # fields' input/change, and after a morph. First paint is the author's:
+      # render the same properties inline.
+      #
+      # `to:` resolves like a client op's: inside the root (nested roots
+      # excluded), `:root` for the root itself, document-wide with
+      # `global: true`; an Array names several. The attribute goes on the root
+      # or on any element inside it; `to:` is resolved from the root either way.
+      # Client-only: no token, no round trip, no broadcast.
+      module CssVarsBinding
+        # Prefixed: this module sits in every reactive component's ancestry, so
+        # a bare NAME or UNITS would shadow a host app's top-level constant.
+        CSS_VAR_NAME = /\A--[a-z0-9-]+\z/i
+        CSS_VAR_UNITS = ["", "px", "%", "deg", "turn", "ms", "s", "em", "rem", "fr"].freeze
+        private_constant :CSS_VAR_NAME, :CSS_VAR_UNITS
+
+        def reactive_css_vars(to:, vars:, global: false, **attrs)
+          wire = { "to" => css_vars_targets!(to), "vars" => css_vars_map!(vars) }
+          wire["global"] = true if global
+          mix({ data: { reactive_css_vars: wire.to_json } }, attrs)
+        end
+
+        private
+
+        def css_vars_targets!(to)
+          targets = Array(to)
+          if targets.empty? || targets.any? { !it.equal?(:root) && (!it.is_a?(String) || it.strip.empty?) }
+            raise ArgumentError, "reactive_css_vars to: takes :root, a CSS selector String (e.g. \"#sample\") " \
+                                 "or an Array of them, got #{to.inspect}"
+          end
+
+          targets.map { JS.normalize_target(it) }
+        end
+
+        def css_vars_map!(vars)
+          unless vars.is_a?(Hash) && !vars.empty?
+            raise ArgumentError, "reactive_css_vars vars: takes a non-empty Hash of custom property => field " \
+                                 "(e.g. vars: { \"--light\" => \"light\" }), got #{vars.inspect}"
+          end
+
+          vars.each_with_object({}) do |(name, spec), map|
+            name = css_var_name!(name)
+            raise ArgumentError, "reactive_css_vars vars: names #{name} twice" if map.key?(name)
+
+            map[name] = css_var_spec!(name, spec)
+          end
+        end
+
+        def css_var_name!(name)
+          string = name.to_s if name.is_a?(String) || name.is_a?(Symbol)
+          return string if string&.match?(CSS_VAR_NAME)
+
+          raise ArgumentError, "reactive_css_vars vars: #{name.inspect} is not a custom property name: it starts " \
+                               "with -- and holds only letters, digits and dashes (e.g. \"--light\")"
+        end
+
+        def css_var_spec!(name, spec)
+          return { "field" => css_var_field!(name, spec) } unless spec.is_a?(Hash)
+
+          unknown = spec.keys - %i[field unit]
+          unless unknown.empty?
+            raise ArgumentError, "reactive_css_vars vars: #{name} takes only field: and unit:, got #{unknown.inspect}"
+          end
+
+          wire = { "field" => css_var_field!(name, spec.fetch(:field, nil)) }
+          unit = css_var_unit!(name, spec.fetch(:unit, ""))
+          wire["unit"] = unit unless unit.empty?
+          wire
+        end
+
+        # The client reads the field through a [name="…"] selector, which a
+        # double quote, backslash or control character would break (the
+        # verbatim_name_selector! rule).
+        def css_var_field!(name, field)
+          string = field.to_s if field.is_a?(String) || field.is_a?(Symbol)
+          if string&.match?(/["\\\x00-\x1f]/)
+            raise ArgumentError, "reactive_css_vars vars: #{name} field can't contain a double quote, backslash, " \
+                                 "or control character (it is read through a [name=\"…\"] selector), got #{field.inspect}"
+          end
+          return string unless string.nil? || string.strip.empty?
+
+          raise ArgumentError, "reactive_css_vars vars: #{name} needs the field name to read " \
+                               "(e.g. \"#{name}\" => \"light\" or { field: \"light\", unit: \"px\" }), got #{field.inspect}"
+        end
+
+        def css_var_unit!(name, unit)
+          string = unit.to_s if unit.is_a?(String) || unit.is_a?(Symbol)
+          return string if CSS_VAR_UNITS.include?(string)
+
+          raise ArgumentError, "reactive_css_vars vars: #{name} unit: must be one of " \
+                               "#{CSS_VAR_UNITS.map(&:inspect).join(", ")}, got #{unit.inspect}"
+        end
+      end
+    end
+  end
+end