phlex-reactive 0.14.2 → 0.14.4

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

@@ -35,6 +35,7 @@ import * as effectsFeature from "phlex/reactive/features/effects"
 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"
 
 // phlex/reactive/runtime — the reactive controller WITHOUT its feature
 // modules (issue #275): the code both client entries share. It is not an
@@ -238,10 +239,18 @@ export function __resetReactiveStreamRenderForTest() {
 // data-reactive-morph-value on a field lets the morph write it while focused.
 let morphFocusRegistered = false
 
+//
+// A reactive_editable (issue #351) is held the same way, but its "value" is its
+// CHILDREN: a focused one keeps them (text and caret) while every attribute
+// still morphs — copied here from the render, then the element's morph is
+// cancelled (cancelling is all-or-nothing in Idiomorph). Its contenteditable
+// stays as it is: the bindings may have downgraded it for an engine without
+// plaintext-only. Every morph of an editable, held or not, records the
+// render's text as its SERVER TEXT (the Escape revert, the dirty baseline).
 function holdsTypedValue(el) {
   return (
     el === document.activeElement &&
-    (el.localName === "input" || el.localName === "textarea") &&
+    (el.localName === "input" || el.localName === "textarea" || el.hasAttribute("data-reactive-editable")) &&
     !el.hasAttribute("data-reactive-morph-value") &&
     !!el.closest('[data-controller~="reactive"]')
   )
@@ -254,11 +263,26 @@ export function registerReactiveMorphFocus() {
   document.addEventListener("turbo:before-morph-element", (event) => {
     const el = event.target
     const next = event.detail?.newElement // absent when Turbo asks before a removal
-    if (!next || event.defaultPrevented || el.localName !== "input" || !holdsTypedValue(el)) return
+    if (!next || event.defaultPrevented) return
+    if (el.hasAttribute?.("data-reactive-editable")) {
+      serverTexts.set(el, editableValue(next))
+      if (!holdsTypedValue(el)) return
+      for (const { name } of [...el.attributes]) {
+        if (!next.hasAttribute(name) && name !== "contenteditable") el.removeAttribute(name)
+      }
+      for (const { name, value } of next.attributes) {
+        if (name !== "contenteditable" && el.getAttribute(name) !== value) el.setAttribute(name, value)
+      }
+      return event.preventDefault()
+    }
+    if (el.localName !== "input" || !holdsTypedValue(el)) return
     const value = next.getAttribute("value")
     if (value == null) el.removeAttribute("value")
     else if (el.getAttribute("value") !== value) el.setAttribute("value", value)
   })
+  // An editable a morph never reached (a stream append) records its server
+  // text when first focused — before anything can be typed into it.
+  document.addEventListener("focusin", (event) => seedServerText(event.target))
   document.addEventListener("turbo:before-morph-attribute", (event) => {
     if (event.detail?.attributeName === "value" && holdsTypedValue(event.target)) event.preventDefault()
   })
@@ -623,6 +647,51 @@ export const EDITOR_SELECTOR =
   ":is(lexxy-editor, trix-editor, [contenteditable=''], [contenteditable=true], [contenteditable=plaintext-only])"
 export const EDITOR_TAGS = new Set(["lexxy-editor", "trix-editor"])
 
+// A reactive_editable's value (issue #351): its text with line breaks — a
+// <br> is one, a block element (the <div> a contenteditable=true Enter
+// inserts) starts and ends a line — "\r\n" normalised, ONE trailing newline
+// dropped (the <br> browsers keep at the end), and folded to spaces when the
+// field is single-line. Read from the DOM, not innerText: no layout, the same
+// on a detached render and under any white-space.
+export function editableValue(el) {
+  let text = ""
+  // A block's edge asks for a line break; the next text or <br> pays it,
+  // once, unless the text already ends in one.
+  let line = false
+  const add = (s) => {
+    if (line && text && !text.endsWith("\n")) text += "\n"
+    line = false
+    text += s
+  }
+  const walk = (node) => {
+    for (const child of node.childNodes) {
+      const block = /^(div|p|li)$/.test(child.localName)
+      if (block) line = true
+      if (child.nodeType === 3) child.data && add(child.data)
+      else if (child.localName === "br") add("\n")
+      else if (child.nodeType === 1) walk(child)
+      if (block) line = true
+    }
+  }
+  walk(el)
+  text = text.replace(/\r\n?/g, "\n").replace(/\n$/, "")
+  return el.getAttribute("data-reactive-editable") === "multi" ? text : text.replace(/\n/g, " ")
+}
+
+// element -> the text of its last server render (issue #351): what Escape
+// reverts to and what dirty tracking diffs against. Seeded when the root
+// connects (or on first focus) and advanced by every morph of the element.
+const serverTexts = new WeakMap()
+
+function seedServerText(el) {
+  if (el?.hasAttribute?.("data-reactive-editable") && !serverTexts.has(el)) serverTexts.set(el, editableValue(el))
+}
+
+export function serverText(el) {
+  seedServerText(el)
+  return serverTexts.get(el)
+}
+
 // A RICH editor (lexxy/trix) is only ready once its custom element upgraded —
 // Trix defines its elements in a setTimeout after load — and exposes the
 // string `value` accessor; reading it before that yields "", which is issue
@@ -1184,8 +1253,9 @@ 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 and
-// draft nested rows: a form's client-only bindings. The root declares one, or
+// issue #319) and their cross-root targets (#343), the tag-chip input, draft
+// nested rows and editable text's keys and paste (#351): 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) {
@@ -1195,7 +1265,7 @@ function bindingsNeeded(root) {
     ) ||
     (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-nested-json], [data-reactive-nested-list], [data-reactive-confirm-when-param], [data-reactive-enable], [data-reactive-select-all], [data-reactive-count], [data-reactive-editable]",
     ) != null
   )
 }
@@ -1205,6 +1275,14 @@ function computeNeeded(root) {
   return root.getAttribute?.("data-reactive-compute-inputs-param") != null
 }
 
+// Sortable lists (issue #350): the root is, or holds, a sortable list or a
+// source list. (A nested root's list loads the module for its parent too; the
+// module then checks ownership before it picks a row up.)
+function sortableNeeded(root) {
+  const lists = "[data-reactive-sortable],[data-reactive-sortable-source]"
+  return Boolean(root.matches?.(lists) || root.querySelector?.(lists))
+}
+
 const PRODUCTION_FEATURES = [
   // (Its `waiting` hook is the opt-in entry's: core.js.) The draft restore
   // writes what a request reads, so it gates.
@@ -1215,6 +1293,8 @@ const PRODUCTION_FEATURES = [
   ["bindings", [bindingsNeeded, null, null, true]],
   // The seed writes output fields a request collects, so it gates.
   ["compute", [computeNeeded, null, null, true]],
+  // Nothing it does at connect is read by a request: it never gates.
+  ["sortable", [sortableNeeded, null]],
   [
     // Stream effects and dismissing flashes are document-level: the module
     // has no connect. A root that DECLARES an effect only gets it fetched
@@ -1378,7 +1458,7 @@ function featureTimeoutMs() {
 export function reactiveFeatureNames() {
   return __SPLIT__
     ? [...FEATURES.keys()]
-    : ["persist", "defer", "form", "bindings", "compute", "effects", "hints", "devtools"]
+    : ["persist", "defer", "form", "bindings", "compute", "sortable", "effects", "hints", "devtools"]
 }
 
 export function __setReactiveFeatureForTest(name, needs, load, waiting, gates) {
@@ -1400,6 +1480,7 @@ export function __loadReactiveFeatureForTest(name) {
     form: formFeature,
     bindings: bindingsFeature,
     compute: computeFeature,
+    sortable: sortableFeature,
     effects: effectsFeature,
     hints: hintsFeature,
     devtools: devtoolsFeature,
@@ -1440,6 +1521,9 @@ const FEATURE_SHARED = {
   enter: enterReactiveActivity,
   exit: exitReactiveActivity,
   count: countReactiveRequest,
+  // The editable collector and server text (issue #351), for the draft.
+  text: editableValue,
+  served: serverText,
   waiting: new WeakMap(),
 }
 
@@ -1449,6 +1533,7 @@ const DEFER = 2
 const FORM = 4
 const BINDINGS = 8
 const COMPUTE = 16
+const SORTABLE = 32
 
 // The default entry's features are part of this file: install them now, as
 // the opt-in entry does when one arrives.
@@ -1670,7 +1755,7 @@ export default class extends Controller {
   #featureTurns = new Map() // name -> settles once that feature has had its turn to connect
   #featureEpoch = 0
   #featureHandle // the `core` handle features receive, built on first use
-  // The default entry (issue #305): one bit per feature, PERSIST … COMPUTE —
+  // The default entry (issue #305): one bit per feature, PERSIST … SORTABLE —
   // asked for (its marker read true) and connected on this connection.
   #featuresAsked = 0
   #featuresOn = 0
@@ -1714,13 +1799,18 @@ export default class extends Controller {
     // without any marker, before and after the morph, a few attribute reads and
     // never an import. (turbo:morph-element BUBBLES: only a morph of the root
     // itself counts.) A tokenless, client-only root has no such listener.
+    // The same listener hears an editable being focused (issue #351): a stream
+    // can append a root's first reactive_editable without morphing the root,
+    // and its keys and paste need the bindings feature before anything is
+    // typed into it.
     if (this.element.getAttribute?.("data-reactive-token-value") != null || deferNeeded(this.element)) {
       this.#boundRootMorph = (event) => {
-        if (event.target !== this.element) return
+        if (event.type === "focusin" ? !event.target.hasAttribute?.("data-reactive-editable") : event.target !== this.element) return
         if (__SPLIT__) this.#loadFeatures(true)
         else this.#connectFeaturesNow(true)
       }
       this.element.addEventListener?.("turbo:morph-element", this.#boundRootMorph)
+      this.element.addEventListener?.("focusin", this.#boundRootMorph)
     }
 
     // Feature modules (issue #275): connect the ones that are here and START
@@ -1731,6 +1821,10 @@ export default class extends Controller {
     // re-runs the seeds itself (#reseed). Never awaited — connect() must reach
     // the drain at the end in the same task (issue #274: an await before it
     // runs a waking click twice).
+    // The editables' server texts (issue #351), before a draft restore
+    // writes into them.
+    this.element.querySelectorAll?.("[data-reactive-editable]").forEach(seedServerText)
+
     this.#featureEpoch++
     this.featuresReady = FEATURES_READY
     if (__SPLIT__) this.#loadFeatures()
@@ -1754,6 +1848,7 @@ export default class extends Controller {
       this.#connectFeatureNow(FORM, "form", formNeeded, (core) => formFeature.connect(this, core, morphed))
       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))
     }
   }
 
@@ -1790,6 +1885,7 @@ export default class extends Controller {
       if (on & FORM) this.#disconnectFeatureNow("form", () => formFeature.disconnect(this, core))
       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))
     }
   }
 
@@ -1957,7 +2053,9 @@ export default class extends Controller {
     this.#featureHandle ??= {
       emit: (name, detail, options) => this.#emit(name, detail, options),
       reseed: () => this.#reseed(),
-      proceed: (target, action, params) => this.#proceed(target, action, params),
+      // Resolves with the reply's HTML once the request has applied, or with
+      // nothing when it failed or was vetoed. `busy` is on(busy:)'s hint.
+      proceed: (target, action, params, busy) => this.#proceed(target, action, params, 0, 0, null, busy),
       forgetToken: () => {
         this.#tokenCache = undefined
       },
@@ -1976,6 +2074,9 @@ export default class extends Controller {
         ),
       listnavOptions: (event) => this.#listnavOptions(event),
       collectFields: () => this.#collectFields(),
+      // A reactive_editable's value and its last server-rendered text (#351).
+      text: editableValue,
+      served: serverText,
       // The confirm gate, as dispatch() runs it: the resolver inside the chain
       // (a synchronous throw is a cancel), never a rejection out.
       confirm: (message, context) =>
@@ -2168,6 +2269,7 @@ export default class extends Controller {
     this.#clearAllThrottles()
     if (this.#boundRootMorph) {
       this.element.removeEventListener?.("turbo:morph-element", this.#boundRootMorph)
+      this.element.removeEventListener?.("focusin", this.#boundRootMorph)
     }
     // Early triggers (issue #273): a disconnected root records again.
     earlyState().connected.delete(this.element)
@@ -3068,6 +3170,9 @@ export default class extends Controller {
       // complete a tick later. Apps needing post-morph timing listen to Turbo's
       // own events; this one is for "the action round trip succeeded".
       this.#emit("reactive:applied", { action, params: allParams, html })
+      // What core.proceed resolves with: a feature can tell a reply that
+      // applied from a failure (every other exit returns nothing).
+      return html
     } catch (error) {
       // The server already processed this action successfully (we're past the
       // fetch) — a throw here is a CLIENT-side apply failure (a malformed
@@ -3290,7 +3395,9 @@ export default class extends Controller {
         // property — only the attribute — so read getAttribute, not el.name.
         const name = el.getAttribute("name")
         if (!name) return
-        const own = el.value ?? el.textContent ?? el.innerHTML ?? ""
+        const own = el.getAttribute("data-reactive-editable") != null
+          ? editableValue(el)
+          : (el.value ?? el.textContent ?? el.innerHTML ?? "")
         // A `[]` name is a group here too: the editor APPENDS its value
         // instead of replacing the slot. Assigning a scalar posted
         // `{"notes[]": "<p>x</p>"}` while the draft snapshot pushed the same

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # Editable text (issue #351): a contenteditable element as a first-class,
+      # PLAIN-TEXT field — an inline title, a card label, a note edited where
+      # it is shown.
+      #
+      #   h3(**reactive_editable(:title, placeholder: "Untitled")) { @card.title }
+      #   p(**reactive_editable(:summary, multiline: true)) { @card.summary }
+      #   h3(**mix(reactive_editable(:title), on(:rename, event: "input", debounce: 300))) { @card.title }
+      #
+      # The element is the caller's; this renders its attributes. The client
+      # then gives it what an input gets:
+      #   * collect — its text, line breaks as "\n" (a single-line field folds
+      #     them to spaces), posted under the (scope-aware) param name;
+      #   * a morph while it is focused keeps its text and caret (attributes
+      #     still morph); unfocused, the server's text wins;
+      #   * paste and drop insert plain text; Enter runs on_enter: (a
+      #     single-line field swallows it by default); Escape reverts;
+      #   * reactive_dirty and reactive_persist treat it like an input.
+      #
+      # Plain text only — a rich editor (Lexxy, Trix) is collected by `.value`.
+      # The placeholder is CSS's to draw:
+      #   [data-reactive-placeholder]:empty::before { content: attr(data-reactive-placeholder) }
+      module Editable
+        # on_enter: a Phlex::Reactive::JS chain (run on Enter, root-scoped like
+        # on_client) or :submit (request-submit the form the field is in).
+        # on_escape: :revert (restore the last server-rendered text and blur)
+        # or nil. spellcheck: false renders spellcheck="false".
+        def reactive_editable(name, multiline: false, placeholder: nil, on_enter: nil, on_escape: :revert,
+                              spellcheck: true, **attrs)
+          raise ArgumentError, "reactive_editable needs a param name (e.g. reactive_editable(:title))" if name.to_s.empty?
+
+          data = { reactive_editable: multiline ? "multi" : "single" }
+          data[:reactive_editable_enter] = editable_enter(on_enter) unless on_enter.nil?
+          data[:reactive_editable_escape] = editable_escape(on_escape) unless on_escape.nil?
+          aria = { multiline: multiline ? "true" : "false" }
+          if placeholder
+            aria[:placeholder] = placeholder
+            data[:reactive_placeholder] = placeholder
+          end
+          binding = { name: scoped_field_name(name), contenteditable: "plaintext-only", role: "textbox", aria:, data: }
+          binding[:spellcheck] = "false" unless spellcheck
+          # Named by `reactive_dirty only:` → its own trackDirty descriptor, as
+          # reactive_field does (issue #184).
+          data[:action] = "input->reactive#trackDirty" if field_dirty_tracked?(name)
+          # An explicit scalar (name:, role:, …) REPLACES the binding's, as
+          # reactive_field's escape hatch does — mix would space-join two
+          # strings. data:/aria: hashes deep-merge.
+          mix(binding.reject { |key, _| attrs.key?(key) && !attrs[key].is_a?(Hash) }, attrs)
+        end
+
+        private
+
+        def editable_enter(on_enter)
+          return "submit" if on_enter == :submit
+
+          unless on_enter.is_a?(Phlex::Reactive::JS)
+            raise ArgumentError,
+              "reactive_editable on_enter: takes a Phlex::Reactive::JS chain (e.g. js.focus(\"#next\")) " \
+              "or :submit, got #{on_enter.inspect}"
+          end
+          raise ArgumentError, "reactive_editable on_enter: got a JS chain with no ops — a dead Enter" if on_enter.empty?
+
+          on_enter.ops.to_json
+        end
+
+        def editable_escape(on_escape)
+          return "revert" if on_escape == :revert
+
+          raise ArgumentError, "reactive_editable on_escape: takes :revert or nil, got #{on_escape.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -13,6 +13,8 @@ module Phlex
       module Helpers
         extend ActiveSupport::Concern
         include Selection
+        include Sortable
+        include Editable
 
         # The acting client's SSE connection id during the current action (nil
         # outside an action, or when the client isn't subscribed to a stream).

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

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # Sortable lists (issue #350): drag rows to reorder a list, or drag a row
+      # in from another list, and ONE declared action receives the row and its
+      # new position — through the normal action pipeline (the signed token,
+      # the request queue, busy:, the reply).
+      #
+      #   ul(**mix(reactive_root, reactive_sortable(:move, handle: "[data-drag-handle]"))) do
+      #     @list.tasks.each do |task|
+      #       li(id: dom_id(task), **reactive_sortable_item(task.id)) do
+      #         span(data: { drag_handle: true }) { "⠿" }
+      #         plain task.title
+      #       end
+      #     end
+      #   end
+      #
+      # On drop the client sends the action with these params (declare the
+      # ones you want; default-deny drops the rest):
+      #
+      #   item      the dragged row's key (reactive_sortable_item(key))
+      #   position  its 0-based index in the target list after the drop
+      #   after     the key of the row it now follows, nil when it is first
+      #   from      "self" for a reorder, else the name of the list it came from
+      #
+      # The row moves in the DOM at once and moves back when the action fails
+      # (or its reply does not render the list). Rows can be dragged with a
+      # mouse, a pen or a finger (a 200 ms press), and with the keyboard: a
+      # focused row picks up on Space/Enter, moves with the arrow keys, drops
+      # on Space/Enter and goes back on Escape, each step announced through a
+      # live region in the words of `messages:`.
+      #
+      # The drag itself is the client's sortable feature module
+      # (features/sortable.js); a page without a sortable loads none of it on
+      # the split client.
+      module Sortable
+        # The announcement words, {position} and {count} filled in by the
+        # client. Override any of them (a translation) with messages:.
+        SORTABLE_MESSAGES = {
+          picked: "Picked up item {position} of {count}",
+          moved: "Moved to position {position} of {count}",
+          dropped: "Dropped",
+          cancelled: "Cancelled"
+        }.freeze
+
+        # The params the client fills in on drop: a static params: may not set them.
+        SORTABLE_DROP_PARAMS = %i[item position after from].freeze
+
+        # A sortable list. `action` is called on drop.
+        #
+        #   group:     links lists (drag between them) and sources to targets
+        #   handle:    a CSS selector, resolved inside each row; only it starts a
+        #              pointer drag. Without it the whole row drags.
+        #   name:      what a row dragged OUT of this list into another reports
+        #              as `from` (and what that list's from: map keys on)
+        #   from:      a drag-in calls another action: from: { "templates" => :insert }
+        #   params:    static params sent with every drop (e.g. the lane a list is)
+        #   disabled:  refuse every drag from or into this list
+        #   busy:      on(busy:)'s vocabulary, applied to the list while pending
+        #   messages:  the live-region words, merged over SORTABLE_MESSAGES
+        def reactive_sortable(action, group: nil, handle: nil, name: nil, from: nil, params: nil,
+                              disabled: false, busy: nil, messages: nil)
+          sortable_requires_component!
+          action = sortable_action!(action)
+          data = { reactive_sortable: action }
+          data[:reactive_sortable_group] = sortable_name!(:group, group) unless group.nil?
+          data[:reactive_sortable_handle] = sortable_handle!(handle) unless handle.nil?
+          data[:reactive_sortable_name] = sortable_list_name!(name) unless name.nil?
+          data[:reactive_sortable_from] = sortable_from!(from) unless from.nil?
+          data[:reactive_sortable_params] = sortable_params!(params) unless params.nil?
+          data[:reactive_sortable_disabled] = "true" if disabled
+          data[:reactive_sortable_busy] = pending_hint_json(busy, action, :busy) if busy
+          data[:reactive_sortable_messages] = sortable_messages!(messages)
+          { data: }
+        end
+
+        # A list whose rows are COPIED into any sortable of the same group,
+        # never moved. The target's action (or its from: mapping for `name`)
+        # decides what lands, and its reply renders the new row. Needs no
+        # token: it works on a ClientBindings root.
+        def reactive_sortable_source(group:, name: "source")
+          { data: { reactive_sortable_source: sortable_list_name!(name),
+                    reactive_sortable_group: sortable_name!(:group, group) } }
+        end
+
+        # A row and its key — a String or an Integer, sent as-is (JSON-typed).
+        # The row is focusable, for the keyboard model (unless disabled).
+        def reactive_sortable_item(key, disabled: false)
+          unless (key.is_a?(String) && !key.strip.empty?) || key.is_a?(Integer)
+            raise ArgumentError,
+              "reactive_sortable_item key must be a String or an Integer (the row's id), got #{key.inspect}"
+          end
+
+          data = { reactive_sortable_item: key.to_json }
+          # A disabled row cannot be picked up, so it stays out of the tab order.
+          return { data: data.merge(reactive_sortable_disabled: "true") } if disabled
+
+          { tabindex: 0, data: }
+        end
+
+        private
+
+        def sortable_requires_component!
+          return if self.class.include?(Phlex::Reactive::Component::Identity)
+
+          raise ArgumentError,
+            "reactive_sortable needs the full Phlex::Reactive::Component — a drop calls a server action, " \
+            "which Phlex::Reactive::ClientBindings has no token for. A copy-only list on a client-only " \
+            "root is reactive_sortable_source(group:)."
+        end
+
+        # The on() courtesy (issue #105): an undeclared action fails at render
+        # under verbose_errors, not as a 403 at drop time.
+        def sortable_action!(action)
+          if action.nil? || action.to_s.strip.empty?
+            raise ArgumentError, "reactive_sortable needs an action to call on drop, e.g. reactive_sortable(:move)"
+          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 sortable_name!(option, value)
+          unless (value.is_a?(String) || value.is_a?(Symbol)) && !value.to_s.strip.empty?
+            raise ArgumentError, "reactive_sortable #{option}: needs a name (a String or Symbol), got #{value.inspect}"
+          end
+
+          value.to_s
+        end
+
+        # "self" is what a reorder within one list reports as `from`.
+        def sortable_list_name!(value)
+          name = sortable_name!(:name, value)
+          if name == "self"
+            raise ArgumentError,
+              'reactive_sortable name: "self" is reserved — it is the `from` of a reorder within one list'
+          end
+
+          name
+        end
+
+        def sortable_handle!(handle)
+          selector = handle.to_s
+          if handle == true || handle == false || selector.strip.empty?
+            raise ArgumentError,
+              "reactive_sortable handle: needs a CSS selector resolved inside each row " \
+              "(e.g. \"[data-drag-handle]\"), got #{handle.inspect}"
+          end
+
+          selector
+        end
+
+        def sortable_from!(from)
+          valid = from.is_a?(Hash) && from.any? && from.keys.all? { !it.to_s.strip.empty? }
+          unless valid
+            raise ArgumentError,
+              "reactive_sortable from: maps a source list's name to the action a drag-in from it calls, " \
+              "e.g. from: { \"templates\" => :insert }, got #{from.inspect}"
+          end
+
+          from.to_h { |list, action| [sortable_list_name!(list), sortable_action!(action)] }.to_json
+        end
+
+        def sortable_params!(params)
+          raise ArgumentError, "reactive_sortable params: must be a Hash, got #{params.inspect}" unless params.is_a?(Hash)
+
+          taken = params.keys.map(&:to_sym) & SORTABLE_DROP_PARAMS
+          unless taken.empty?
+            raise ArgumentError,
+              "reactive_sortable params: cannot set #{taken.first.inspect} — the client fills in " \
+              "#{SORTABLE_DROP_PARAMS.map(&:inspect).join(", ")} on drop"
+          end
+
+          params.to_json
+        end
+
+        def sortable_messages!(messages)
+          return SORTABLE_MESSAGES_JSON if messages.nil?
+          unless messages.is_a?(Hash)
+            raise ArgumentError,
+              "reactive_sortable messages: must be a Hash, got #{messages.inspect}"
+          end
+
+          unknown = messages.keys.map { it.to_s.to_sym } - SORTABLE_MESSAGES.keys
+          unless unknown.empty?
+            raise ArgumentError,
+              "reactive_sortable got an unknown messages: key #{unknown.first.inspect} — " \
+              "supported: #{SORTABLE_MESSAGES.keys.map(&:inspect).join(", ")}"
+          end
+
+          messages.each do |name, words|
+            next if words.is_a?(String)
+
+            raise ArgumentError, "reactive_sortable messages: #{name} must be a String, got #{words.inspect}"
+          end
+
+          SORTABLE_MESSAGES.merge(messages.transform_keys { it.to_s.to_sym }).to_json
+        end
+
+        SORTABLE_MESSAGES_JSON = SORTABLE_MESSAGES.to_json
+        private_constant :SORTABLE_MESSAGES_JSON, :SORTABLE_DROP_PARAMS
+      end
+    end
+  end
+end

data/lib/phlex/reactive/engine.rb

@@ -20,10 +20,10 @@ module Phlex
       # build script (scripts/build_client.js), the core's own table and the
       # default entry name the same features —
       # spec/phlex/engine_client_pin_spec.rb fails when they disagree.
-      CLIENT_FEATURES = %w[persist defer form bindings compute effects hints devtools].freeze
-      # (Gzipped, bun zlib level 9: the default file 26.1 KB; the core 12.4 KB;
-      # persist 3.2, defer 2.8, form 1.0, bindings 5.4, compute 2.1, effects
-      # 1.7, hints 1.0, devtools 1.6 KB. spec/javascript/bundle_budget.test.js
+      CLIENT_FEATURES = %w[persist defer form bindings compute sortable effects hints devtools].freeze
+      # (Gzipped, bun zlib level 9: the default file 28.9 KB; the core 13.5 KB;
+      # persist 3.1, defer 3.0, form 1.0, bindings 6.2, compute 2.1, sortable
+      # 3.1, effects 1.7, hints 1.0, devtools 1.6 KB. spec/javascript/bundle_budget.test.js
       # is the source of truth and holds a ratchet on each.)
 
       # Mount POST /reactive/actions -> Phlex::Reactive::ActionsController#create

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.14.2"
+    VERSION = "0.14.4"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.14.2
+  version: 0.14.4
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -158,6 +158,9 @@ files:
 - app/javascript/phlex/reactive/features/persist.js
 - app/javascript/phlex/reactive/features/persist.min.js
 - app/javascript/phlex/reactive/features/persist.min.js.map
+- app/javascript/phlex/reactive/features/sortable.js
+- app/javascript/phlex/reactive/features/sortable.min.js
+- app/javascript/phlex/reactive/features/sortable.min.js.map
 - app/javascript/phlex/reactive/inspect.js
 - app/javascript/phlex/reactive/inspect.min.js
 - app/javascript/phlex/reactive/inspect.min.js.map
@@ -188,11 +191,13 @@ files:
 - lib/phlex/reactive/collections.rb
 - lib/phlex/reactive/component.rb
 - lib/phlex/reactive/component/dsl.rb
+- lib/phlex/reactive/component/editable.rb
 - lib/phlex/reactive/component/helpers.rb
 - lib/phlex/reactive/component/identity.rb
 - lib/phlex/reactive/component/lazy.rb
 - lib/phlex/reactive/component/registry.rb
 - lib/phlex/reactive/component/selection.rb
+- lib/phlex/reactive/component/sortable.rb
 - lib/phlex/reactive/defer.rb
 - lib/phlex/reactive/deferred_render_job.rb
 - lib/phlex/reactive/doctor.rb