phlex-reactive 0.16.0 → 0.16.2

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/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

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

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+# DRAG_MESSAGES_JSON is built with Hash#to_json while this file loads.
+require "json"
+
+module Phlex
+  module Reactive
+    module Component
+      # Draggable regions (issue #416): a box that moves and resizes inside a
+      # frame, or a point that moves inside it, with the result in fields as
+      # fractions of the frame — 0..1 on each axis, so a resize, a responsive
+      # layout or a morph changes nothing about them.
+      #
+      #   div(**mix(reactive_frame, class: "relative")) do
+      #     img(src: @photo.url, alt: "", class: "block w-full")
+      #     div(**reactive_box(fields: { x: "crop[x]", y: "crop[y]", width: "crop[width]", height: "crop[height]" },
+      #                        value: @crop.to_h, aspect: "crop[aspect]")) do
+      #       %i[nw n ne e se s sw w].each { span(**reactive_box_handle(it)) }
+      #       span(**reactive_point(fields: { x: "focus[x]", y: "focus[y]" }, value: @focus.to_h, within: "[data-reactive-box]"))
+      #     end
+      #   end
+      #
+      # The box, its handles and the point render their position as inline
+      # percentages, so the first paint is right with no JavaScript and a
+      # re-render with new values moves them. The frame's padding box is the
+      # coordinate space; the frame must be positioned (relative or absolute),
+      # which the helper leaves to the author. Style the look with classes, and
+      # add any inline style AFTER the helper's: mix(reactive_box(...), style: "…").
+      #
+      # The client (features/drag.js) drags them with a mouse, a pen or a
+      # finger, and the keyboard: arrows move 1% (Shift: 10%), Alt+arrows
+      # resize from the bottom-right corner or from the focused handle, Escape
+      # puts the drag back, each step announced in the words of `messages:`.
+      # The fields get `input` as the box moves and one `change` on release.
+      # `action:` is sent once on release through the root's pipeline; without
+      # it the binding is client-only and works on a ClientBindings root.
+      module Drag
+        # The announcement words, {x}, {y}, {width} and {height} filled in by
+        # the client as whole percents. Override any of them with messages:.
+        DRAG_MESSAGES = {
+          moved: "Moved to {x}%, {y}%",
+          resized: "Resized to {width}% by {height}%",
+          cancelled: "Cancelled"
+        }.freeze
+
+        # Where each handle sits on the box (left, top) and the cursor it shows.
+        DRAG_HANDLES = {
+          nw: ["0%", "0%", "nwse"], n: ["50%", "0%", "ns"], ne: ["100%", "0%", "nesw"], e: ["100%", "50%", "ew"],
+          se: ["100%", "100%", "nwse"], s: ["50%", "100%", "ns"], sw: ["0%", "100%", "nesw"], w: ["0%", "50%", "ew"]
+        }.freeze
+
+        BOX_KEYS = %i[x y width height].freeze
+        POINT_KEYS = %i[x y].freeze
+        # A ratio written as a String: "16:9", "1.5".
+        RATIO_STRING = /\A\s*\d*\.?\d+\s*(:\s*\d*\.?\d+\s*)?\z/
+        # A box may end at the frame's edge as the fields round it: x and width
+        # rounded apart to 4 decimals can sum to 1.0001 (0.45545 + 0.54455).
+        EDGE_SLACK = 1e-4 + 1e-9
+
+        # The coordinate space: its padding box is 0..1 on each axis.
+        def reactive_frame = { data: { reactive_frame: true } }
+
+        # A box that moves and resizes inside the frame.
+        #
+        #   fields:    { x:, y:, width:, height: } — the names of the fields that hold it
+        #   value:     { x:, y:, width:, height: } — where it is, fractions of the frame
+        #   aspect:    a Numeric ratio (16/9r), or the name of a field holding one
+        #              ("16:9", "1.5", or "" for free), read at drag start
+        #   min:       the smallest width/height, a fraction of the frame
+        #   action:    sent once on release, with x/y/width/height params
+        #   busy:      on(busy:)'s vocabulary, applied while that action is pending
+        #   messages:  the live-region words, merged over DRAG_MESSAGES
+        def reactive_box(fields:, value:, aspect: nil, min: 0.05, action: nil, busy: nil, messages: nil)
+          fields = drag_fields!(:reactive_box, fields, BOX_KEYS)
+          value = drag_value!(:reactive_box, value, BOX_KEYS)
+          drag_inside_frame!(value)
+          data = { reactive_box: fields.to_json, reactive_box_min: drag_min!(min) }
+          drag_aspect!(aspect, data) unless aspect.nil?
+          drag_action!(:reactive_box, action, busy, data)
+          data[:reactive_box_messages] = drag_messages!(:reactive_box, messages)
+          style = "position: absolute; box-sizing: border-box; left: #{drag_percent(value[:x])}; " \
+                  "top: #{drag_percent(value[:y])}; width: #{drag_percent(value[:width])}; " \
+                  "height: #{drag_percent(value[:height])}; touch-action: none; cursor: move;"
+          { tabindex: 0, style:, data: }
+        end
+
+        # An edge or corner of the box (inside it) to resize from: nw n ne e se s sw w.
+        def reactive_box_handle(edge)
+          left, top, cursor = DRAG_HANDLES.fetch(edge.to_s.to_sym) do
+            raise ArgumentError,
+              "reactive_box_handle got an unknown edge #{edge.inspect} — one of " \
+              "#{DRAG_HANDLES.keys.map(&:inspect).join(", ")}"
+          end
+          { tabindex: -1,
+            style: "position: absolute; left: #{left}; top: #{top}; translate: -50% -50%; touch-action: none; " \
+                   "cursor: #{cursor}-resize;",
+            data: { reactive_box_handle: edge.to_s } }
+        end
+
+        # A point (its centre) that moves inside the frame — or, with within:,
+        # inside the element it sits in that matches the selector (a box): its
+        # fractions are then of that element, and it moves with it.
+        def reactive_point(fields:, value:, within: nil, action: nil, busy: nil, messages: nil)
+          fields = drag_fields!(:reactive_point, fields, POINT_KEYS)
+          value = drag_value!(:reactive_point, value, POINT_KEYS)
+          data = { reactive_point: fields.to_json }
+          data[:reactive_point_within] = drag_within!(within) unless within.nil?
+          drag_action!(:reactive_point, action, busy, data)
+          data[:reactive_point_messages] = drag_messages!(:reactive_point, messages)
+          style = "position: absolute; left: #{drag_percent(value[:x])}; top: #{drag_percent(value[:y])}; " \
+                  "translate: -50% -50%; touch-action: none; cursor: move;"
+          { tabindex: 0, style:, data: }
+        end
+
+        private
+
+        # A fraction as a percentage with at most 2 decimals, rounded as the
+        # client rounds (Math.round(v * 1e4) / 100): 0.1 -> "10%".
+        def drag_percent(fraction) = "#{((fraction * 10_000).round / 100.0).to_s.delete_suffix(".0")}%"
+
+        def drag_fields!(helper, fields, keys)
+          example = "fields: { #{keys.map { "#{it}: \"region[#{it}]\"" }.join(", ")} }"
+          raise ArgumentError, "#{helper} fields: must be a Hash, e.g. #{example}" unless fields.is_a?(Hash)
+
+          fields = fields.transform_keys { it.to_s.to_sym }
+          drag_keys!(helper, :fields, fields, keys, example)
+          fields.each do |key, name|
+            next if (name.is_a?(String) || name.is_a?(Symbol)) && !name.to_s.strip.empty?
+
+            raise ArgumentError, "#{helper} fields: #{key} needs a field name, got #{name.inspect}"
+          end
+          fields.slice(*keys).transform_values(&:to_s)
+        end
+
+        def drag_keys!(helper, option, hash, keys, example)
+          missing = keys - hash.keys
+          unless missing.empty?
+            raise ArgumentError,
+              "#{helper} #{option}: is missing #{missing.map(&:inspect).join(", ")} — e.g. #{example}"
+          end
+
+          unknown = hash.keys - keys
+          return if unknown.empty?
+
+          raise ArgumentError,
+            "#{helper} got an unknown #{option}: key #{unknown.first.inspect} — it takes #{keys.map(&:inspect).join(", ")}"
+        end
+
+        def drag_value!(helper, value, keys)
+          raise ArgumentError, "#{helper} value: must be a Hash of fractions, got #{value.inspect}" unless value.is_a?(Hash)
+
+          value = value.transform_keys { it.to_s.to_sym }
+          drag_keys!(helper, :value, value, keys, "value: { #{keys.map { "#{it}: 0.5" }.join(", ")} }")
+          value.each do |key, number|
+            next if number.is_a?(Numeric) && number.real? && number.between?(0, 1)
+
+            raise ArgumentError, "#{helper} value: #{key} must be a number from 0 to 1 (a fraction), got #{number.inspect}"
+          end
+          value
+        end
+
+        def drag_inside_frame!(value)
+          %i[width height].each do
+            raise ArgumentError, "reactive_box value: #{it} must be greater than 0" unless value[it].positive?
+          end
+          { x: :width, y: :height }.each do |at, size|
+            sum = value[at] + value[size]
+            next if sum <= 1 + EDGE_SLACK
+
+            raise ArgumentError,
+              "reactive_box value: #{at} + #{size} is #{sum.round(4)} — the box must stay inside the frame (at most 1)"
+          end
+        end
+
+        def drag_min!(min)
+          # (A Float: a Rational would render as "1/10", which the browser cannot read.)
+          return min.to_f if min.is_a?(Numeric) && min.real? && min.positive? && min <= 1
+
+          raise ArgumentError,
+            "reactive_box min: must be a fraction of the frame above 0 and at most 1 (e.g. 0.05), got #{min.inspect}"
+        end
+
+        def drag_aspect!(aspect, data)
+          if aspect.is_a?(Numeric) && aspect.real? && aspect.positive? && aspect.finite?
+            data[:reactive_box_ratio] = aspect.to_f
+          elsif aspect.is_a?(String) && aspect.match?(RATIO_STRING)
+            raise ArgumentError,
+              "reactive_box aspect: #{aspect.inspect} is a ratio, not a field name — pass 16/9r or 1.5 " \
+              "(a Numeric), or the name of a field whose value is \"16:9\""
+          elsif (aspect.is_a?(String) || aspect.is_a?(Symbol)) && !aspect.to_s.strip.empty?
+            data[:reactive_box_aspect] = aspect.to_s
+          else
+            raise ArgumentError,
+              "reactive_box aspect: must be a positive Numeric (16/9r) or the name of a field holding the ratio, " \
+              "got #{aspect.inspect}"
+          end
+        end
+
+        def drag_within!(within)
+          return within if within.is_a?(String) && !within.strip.empty?
+
+          raise ArgumentError,
+            "reactive_point within: needs a CSS selector matching the element the point sits inside, " \
+            "e.g. \"[data-reactive-box]\", got #{within.inspect}"
+        end
+
+        def drag_action!(helper, action, busy, data)
+          if action.nil?
+            raise ArgumentError, "#{helper} busy: needs an action: — it is applied while that action is pending" if busy
+
+            return
+          end
+
+          drag_requires_component!(helper)
+          name = drag_action_name!(helper, action)
+          data[:"#{helper}_action"] = name
+          data[:"#{helper}_busy"] = pending_hint_json(busy, name, :busy) if busy
+        end
+
+        def drag_requires_component!(helper)
+          return if self.class.include?(Phlex::Reactive::Component::Identity)
+
+          raise ArgumentError,
+            "#{helper} action: needs the full Phlex::Reactive::Component — a release calls a server action, " \
+            "which Phlex::Reactive::ClientBindings has no token for. Without action: the fields alone hold it."
+        end
+
+        # The on() courtesy (issue #105): an undeclared action fails at render
+        # under verbose_errors, not as a 403 on release.
+        def drag_action_name!(helper, action)
+          if action.to_s.strip.empty?
+            raise ArgumentError, "#{helper} action: needs the name of a declared action, got #{action.inspect}"
+          end
+
+          if Phlex::Reactive.verbose_errors &&
+             (actions = self.class.reactive_actions).any? && !actions.key?(action.to_sym)
+            raise Phlex::Reactive::Error,
+              "#{self.class} has no declared action #{action.to_sym.inspect} (declared: #{actions.keys.inspect})"
+          end
+
+          action.to_s
+        end
+
+        def drag_messages!(helper, messages)
+          return DRAG_MESSAGES_JSON if messages.nil?
+          raise ArgumentError, "#{helper} messages: must be a Hash, got #{messages.inspect}" unless messages.is_a?(Hash)
+
+          unknown = messages.keys.map { it.to_s.to_sym } - DRAG_MESSAGES.keys
+          unless unknown.empty?
+            raise ArgumentError,
+              "#{helper} got an unknown messages: key #{unknown.first.inspect} — " \
+              "supported: #{DRAG_MESSAGES.keys.map(&:inspect).join(", ")}"
+          end
+
+          messages.each do |name, words|
+            unless words.is_a?(String)
+              raise ArgumentError,
+                "#{helper} messages: #{name} must be a String, got #{words.inspect}"
+            end
+          end
+
+          DRAG_MESSAGES.merge(messages.transform_keys { it.to_s.to_sym }).to_json
+        end
+
+        DRAG_MESSAGES_JSON = DRAG_MESSAGES.to_json
+        private_constant :DRAG_MESSAGES_JSON, :DRAG_HANDLES, :BOX_KEYS, :POINT_KEYS, :RATIO_STRING, :EDGE_SLACK
+      end
+    end
+  end
+end

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

@@ -311,6 +311,9 @@ module Phlex
 
             # Issue #184: params: :symbol resolves a registered named schema.
             params = Phlex::Reactive.param_schema(params) if params.is_a?(Symbol)
+            # A deep-frozen copy, shared with the compiled schema below: the
+            # definition stays readable from a non-main Ractor once warmed.
+            params = Phlex::Reactive::Shareable.share(params)
             # 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.

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

@@ -14,10 +14,12 @@ module Phlex
         extend ActiveSupport::Concern
         include Selection
         include Sortable
+        include Drag
         include Editable
         include MediaBinding
         include ImageFallbackBinding
         include CountdownBinding
+        include CssVarsBinding
         include FieldReferences
         include ShowOptions
 
@@ -42,8 +44,10 @@ module Phlex
         # nothing was held, and outside an action. Filtered to the action's
         # declared params; a hint about what the user saw, never authorization.
         #
+        #   action :save, params: { title: :string }   # only declared fields are reported
+        #
         #   def save(title: nil)
-        #     return conflict!(title) if reactive_held_fields.include?("title") && title != @note.title
+        #     return reply.morph.refused("title") if reactive_held_fields.include?("title") && title != @note.title
         #     @note.update!(title:)
         #   end
         def reactive_held_fields