phlex-reactive 0.15.0 → 0.15.1

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

@@ -201,6 +201,7 @@ export function registerReactiveStreamRender() {
   streamRenderRegistered = true
   document.addEventListener("turbo:before-stream-render", (event) => {
     streamIntoRoots(event)
+    streamModals(event)
     // The opt-in entry sees every stream (it may hold one for a module the
     // incoming content needs); with no entry hook, a loaded effects module
     // wraps the stream directly — in the default entry, always.
@@ -245,6 +246,116 @@ function streamIntoRoots(event) {
   }
 }
 
+// --- Modal dialogs (issue #365) ---
+// show_modal / close_dialog reach the browser's own modal dialog: the top
+// layer, the focus trap, ::backdrop, Escape and focus restored to the opener.
+// A dialog the SERVER renders open with data-reactive-modal becomes modal as
+// soon as the client sees it: at a root's connect (a full page, a replaced
+// root), after a morph of a root or of the page, and after a stream whose
+// content holds a dialog. Duck-typed on tagName (the submitFormFor precedent:
+// fake-node and test friendly).
+function isDialog(el) {
+  return el?.tagName === "DIALOG" && typeof el.showModal === "function"
+}
+
+// `:modal` is the only way to tell a modal dialog from one opened with the
+// `open` attribute. An engine that does not know the pseudo-class throws a
+// SyntaxError; it then counts as not modal (show_modal reopens it modally).
+function isModal(dialog) {
+  try {
+    return dialog.matches(":modal")
+  } catch {
+    return false
+  }
+}
+
+function showModal(el) {
+  if (!isDialog(el)) {
+    // Said where a zero-target op is (issue #237): under verbose_errors or debug.
+    if (el?.closest?.('[data-reactive-verbose="true"], [data-reactive-debug="true"]')) {
+      console.warn(`[phlex-reactive] show_modal targets a <dialog>, not <${el.localName}> — skipped`)
+    }
+    return
+  }
+  if (!el.isConnected || isModal(el)) return
+  // showModal() throws on a dialog already open non-modally: close it first,
+  // in the same task, so nothing paints in between.
+  if (el.open) el.close()
+  el.showModal()
+}
+
+function closeDialog(el) {
+  if (isDialog(el) && el.open) el.close()
+}
+
+// Make every open dialog[data-reactive-modal] in `scope` modal — `scope` itself
+// too, for a root that is the dialog.
+function upgradeModals(scope) {
+  const sel = "dialog[data-reactive-modal]"
+  const dialogs = [...(scope?.querySelectorAll?.(sel) ?? [])]
+  if (scope?.matches?.(sel)) dialogs.push(scope)
+  for (const dialog of dialogs) {
+    if (dialog.open && !isModal(dialog)) showModal(dialog)
+  }
+}
+
+// After a stream whose content holds a dialog has rendered, upgrade the page's
+// marked dialogs. Document-wide: a replace's target is gone by then.
+function streamModals(event) {
+  const detail = event.detail
+  const render = detail?.render
+  const stream = detail?.newStream ?? event.target
+  if (typeof render !== "function" || !stream?.querySelector?.("template")?.content?.querySelector?.("dialog")) return
+  detail.render = async (el) => {
+    await render(el)
+    upgradeModals(document)
+  }
+}
+
+let modalsRegistered = false
+
+export function registerReactiveModals() {
+  if (modalsRegistered) return
+  if (typeof document === "undefined" || typeof document.addEventListener !== "function") return
+  modalsRegistered = true
+  // A morph of a root (a reply or broadcast morph, a page refresh) may have
+  // inserted an open marked dialog or opened one; a page morph covers dialogs
+  // outside any root.
+  document.addEventListener("turbo:morph-element", (event) => {
+    if (event.target?.matches?.('[data-controller~="reactive"]')) upgradeModals(event.target)
+  })
+  document.addEventListener("turbo:morph", () => upgradeModals(document))
+  // A morph that removes `open` from a modal dialog (the server now renders it
+  // closed): close() it instead, which leaves the top layer, ends the page's
+  // inertness and restores focus. Removing the attribute alone left all that
+  // in place under the older spec text, and close() is a no-op once `open` is
+  // gone — so the removal is cancelled and close() removes it. Idiomorph asks
+  // "remove" for EVERY attribute of the old element, kept or not, and that ask
+  // carries no new element: whether `open` is really leaving is read from the
+  // element morph's new render, which comes first.
+  const closing = new WeakSet()
+  document.addEventListener("turbo:before-morph-element", (event) => {
+    const el = event.target
+    const next = event.detail?.newElement
+    if (!isDialog(el) || !next) return
+    if (next.hasAttribute?.("open")) closing.delete(el)
+    else closing.add(el)
+  })
+  document.addEventListener("turbo:before-morph-attribute", (event) => {
+    const el = event.target
+    const detail = event.detail
+    if (detail?.attributeName !== "open" || detail.mutationType !== "remove") return
+    if (!closing.has(el) || !el.open || !isModal(el)) return
+    closing.delete(el)
+    event.preventDefault()
+    el.close()
+  })
+}
+
+export function __resetReactiveModalsForTest() {
+  modalsRegistered = false
+}
+
 // For the opt-in entry: what to do with a stream before its render — hold it
 // for a module the incoming content needs. `handle(event, effects)` gets the
 // loaded effects module (or undefined) and wraps the stream with it itself.
@@ -581,6 +692,7 @@ export function registerReactiveActions() {
   registerReactiveDefer()
   registerReactiveStreamRender()
   registerReactiveMorphFocus()
+  registerReactiveModals()
   registerReactivePlaintext()
   registerReactiveOffline()
   registerReactiveDev()
@@ -838,6 +950,11 @@ const CLIENT_OPS = Object.freeze({
   focus: (el) => el.focus?.(),
   focus_first: (el) => firstFocusable(el)?.focus?.(),
 
+  // Modal dialog ops (issue #365): HTMLDialogElement#showModal / #close.
+  // ACTOR-ONLY like focus (BROADCAST_REFUSED_OPS server-side).
+  show_modal: (el) => showModal(el),
+  close_dialog: (el) => closeDialog(el),
+
   // Text op (issue #159): set textContent — XSS-safe by construction (never
   // innerHTML), strictly less powerful than set_attr. Change-guarded like
   // #mirrorText. With global: true it is the cross-root text escape: paint a
@@ -1025,9 +1142,13 @@ function parseOps(raw) {
 // record(s) whose descriptor matches the firing event: event.type, the key
 // filter, and window-boundness.
 
-// Stimulus's default keyMappings (letters and digits map to themselves). A
+// Stimulus's default keyMappings (letters and digits map to themselves), plus
+// delete and backspace (issue #366): Stimulus lacks those two, so a shortcut
+// naming one binds a bare keydown and only shortcutApplies matches it. A
 // custom Stimulus schema is not mirrored — an unknown filter never matches.
 const KEY_FILTER_MAP = Object.freeze({
+  backspace: "Backspace",
+  delete: "Delete",
   enter: "Enter",
   tab: "Tab",
   esc: "Escape",
@@ -1070,7 +1191,9 @@ function keyFilterMatches(filter, event, keyMappings) {
 // keydown whose `mod` is meta on Apple platforms and ctrl elsewhere. Ruby
 // renders a meta twin and a ctrl twin; Stimulus filters the key, and this
 // decides whether the twin that fired is this platform's and whether the
-// target is one the user is typing in. Either miss is a complete no-op.
+// target is one the user is typing in. Either miss is a complete no-op. A
+// delete/backspace chord (issue #366) has no twins and no Stimulus filter:
+// its bare keydown hears every key, and this check alone picks the chord.
 // (Stimulus typecasts a digit shortcut, "1", to a number: hence String().)
 const shortcutKeys = (spec) => (spec && typeof spec === "object" ? spec.keys : String(spec))
 // A shortcut record keeps a bare `on: "keydown"`, so bindingMatches lets every
@@ -1965,6 +2088,9 @@ export default class extends Controller {
     if (__SPLIT__) this.#loadFeatures()
     else this.#connectFeaturesNow()
 
+    // A dialog the server rendered open with data-reactive-modal (issue #365).
+    upgradeModals(this.element)
+
     // LAST, after every feature above is wired: a replayed trigger must find
     // the controller exactly as a live event after connect would.
     this.#announceConnected()
@@ -2432,19 +2558,22 @@ export default class extends Controller {
   // a per-controller promise makes each dispatch wait for the previous one, so
   // it always uses the freshest token.
   dispatch(event) {
+    // A shortcut (issue #357) that is the other platform's twin, or pressed
+    // in a field the user is typing in, is a complete no-op: the native
+    // default (text undo) proceeds and nothing is announced. Checked FIRST: a
+    // delete/backspace shortcut (issue #366) binds a bare window keydown, so
+    // every key the user presses lands here.
+    const shortcut = event.params?.shortcut
+    if (shortcut != null && !shortcutApplies(shortcut, event, this.application?.schema?.keyMappings)) return
     // A :once trigger already replayed on connect (issue #273) is spent.
     if (earlyOnceSwallows(event, "dispatch", this.application?.schema?.keyMappings, this.element)) return
     // `window` (renamed: never shadow the global) and `outside` are the event-
     // modifier params (issue #80). The client decides preventDefault behavior
     // from event.params — set by the Ruby on() — never by sniffing the
     // Stimulus descriptor.
-    const { action, params, debounce, throttle, confirm, confirmWhen, outside, window: windowBound, optimistic, shortcut } =
+    const { action, params, debounce, throttle, confirm, confirmWhen, outside, window: windowBound, optimistic } =
       event.params
     if (!action) return
-    // A shortcut (issue #357) that is the other platform's twin, or pressed
-    // in a field the user is typing in, is a complete no-op: the native
-    // default (text undo) proceeds and nothing is announced.
-    if (shortcut != null && !shortcutApplies(shortcut, event, this.application?.schema?.keyMappings)) return
 
     // The pending-state hint (issue #181): data-reactive-busy-param. During a
     // deploy overlap a page rendered by the PREVIOUS gem still emits the old
@@ -2600,6 +2729,12 @@ export default class extends Controller {
   // the component resets whatever they toggled (by design — a signed action
   // owns state that must survive re-renders).
   runOps(event) {
+    // A lone shortcut record (Stimulus typecasts it to an object) whose chord
+    // did not fire bails before any bookkeeping: a delete/backspace shortcut
+    // (issue #366) binds a bare window keydown that hears every key. Several
+    // records are checked one by one below.
+    const lone = event.params?.ops
+    if (lone?.shortcut != null && !shortcutApplies(lone.shortcut, event, this.application?.schema?.keyMappings)) return
     if (earlyOnceSwallows(event, "runOps", this.application?.schema?.keyMappings, this.element)) return
     if (bindingsAlreadyRan(event, this)) return
     const params = event.params ?? {}

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

@@ -1790,12 +1790,27 @@ module Phlex
         # The data-action descriptors of an on()/on_client trigger: one, or a
         # shortcut's meta and ctrl twins (space-joined, as mix joins them).
         # The common, shortcut-less path is ONE interpolation (on() is a hot path).
+        # A chord whose key Stimulus lacks (issue #366: delete, backspace) binds a
+        # bare window keydown: the client's shortcut check matches it alone.
         def trigger_descriptors(event, shortcut, window_bound, method, once)
           return "#{event}#{"@window" if window_bound}->reactive##{method}#{":once" if once}" unless shortcut
+          return bare_shortcut_descriptor(shortcut, method, once) unless shortcut.stimulus_filterable?
 
           shortcut.filters.map { "keydown.#{it}@window->reactive##{method}#{":once" if once}" }.join(" ")
         end
 
+        # Stimulus removes a `:once` listener after its FIRST event, and a bare
+        # keydown hears every key, so the first keypress of any kind would spend it.
+        def bare_shortcut_descriptor(shortcut, method, once)
+          if once
+            raise ArgumentError,
+              "shortcut: #{shortcut.keys.inspect} cannot take once: — its key is matched by the " \
+              "library, not Stimulus, so the first key pressed of any kind would spend the binding"
+          end
+
+          "keydown@window->reactive##{method}"
+        end
+
         # A Hash param is JSON (Stimulus's param reader parses it back into an
         # object); the String form stays a plain string.
         def shortcut_param_attr(shortcut)

data/lib/phlex/reactive/js.rb

@@ -186,6 +186,26 @@ module Phlex
         append("focus_first", target_args(to, global:))
       end
 
+      # --- Modal dialogs (issue #365) ---
+      #
+      # show_modal(to)   — HTMLDialogElement#showModal(): the top layer, a
+      #                    focus trap, ::backdrop, Escape to close and focus
+      #                    restored to the opener, all the browser's own. A
+      #                    dialog already open NON-modally is closed and
+      #                    reopened as a modal; one already modal is left as is.
+      # close_dialog(to) — HTMLDialogElement#close() (a closed one is left as is).
+      # A target that is not a <dialog> is skipped. Both ACTOR-ONLY like focus:
+      # opening a modal steals focus, so a broadcast refuses them — a
+      # broadcaster renders the dialog open with data: { reactive_modal: true }.
+
+      def show_modal(to, global: false)
+        append("show_modal", target_args(to, global:))
+      end
+
+      def close_dialog(to, global: false)
+        append("close_dialog", target_args(to, global:))
+      end
+
       # --- Submit (issue #226) ---
       #
       # submit(to = :root) — requestSubmit() the TARGET'S OWN form: the target

data/lib/phlex/reactive/shortcut.rb

@@ -13,17 +13,24 @@ module Phlex
     # exactly), so a `mod` chord renders TWO descriptors, a meta twin and a ctrl
     # twin, and the client runs only the twin for its platform. Stimulus keeps
     # the key filtering; the client adds the platform check, the editable-target
-    # guard and preventDefault.
+    # guard and preventDefault. The exception is a key Stimulus's default map
+    # lacks (delete, backspace — issue #366): it binds a bare window keydown,
+    # no twins, and the client matches the whole chord.
     #
     # Validation is loud, at render: Stimulus reports an unknown key token by
     # throwing at keypress time, which is too late to notice.
     class Shortcut
       MODIFIERS = %w[mod meta ctrl alt shift].freeze
       # Stimulus's default keyMappings: the named keys plus a-z and 0-9.
-      NAMED_KEYS = %w[enter tab esc space up down left right home end page_up page_down].freeze
+      STIMULUS_KEYS = %w[enter tab esc space up down left right home end page_up page_down].freeze
+      # Keys Stimulus's default map lacks (issue #366): a key filter naming one
+      # makes Stimulus throw at keypress, so such a chord renders a bare
+      # `keydown@window` and the client alone matches it.
+      LIBRARY_KEYS = %w[delete backspace].freeze
+      NAMED_KEYS = (STIMULUS_KEYS + LIBRARY_KEYS).freeze
       HASH_KEYS = %i[keys in_editable].freeze
 
-      private_constant :MODIFIERS, :NAMED_KEYS, :HASH_KEYS
+      private_constant :MODIFIERS, :STIMULUS_KEYS, :LIBRARY_KEYS, :NAMED_KEYS, :HASH_KEYS
 
       attr_reader :keys
 
@@ -61,6 +68,11 @@ module Phlex
         freeze
       end
 
+      # False for a chord whose key Stimulus's default map lacks (delete,
+      # backspace): it binds without a key filter and without twins — the
+      # client's shortcut check matches the key and picks the platform's `mod`.
+      def stimulus_filterable? = !LIBRARY_KEYS.include?(@keys.split("+").last)
+
       # The Stimulus key filters to bind: the meta and ctrl twins for a `mod`
       # chord, else the chord itself.
       def filters
@@ -95,8 +107,9 @@ module Phlex
 
         raise ArgumentError,
           "shortcut: #{source.inspect} has an unknown key #{key.first.inspect} — use a letter, a digit, " \
-          "or one of #{NAMED_KEYS.join(", ")} (Stimulus's default key map; custom keyMappings are not " \
-          "known on the server, bind those with event: and window: instead)"
+          "or one of #{NAMED_KEYS.join(", ")} (Stimulus's default key map, plus delete and backspace, " \
+          "which the library matches itself; custom keyMappings are not known on the server, bind " \
+          "those with event: and window: instead)"
       end
 
       def known_key?(key) = NAMED_KEYS.include?(key) || key.match?(/\A[a-z0-9]\z/)

data/lib/phlex/reactive/streamable.rb

@@ -38,11 +38,14 @@ module Phlex
       # (issue #226) would force-submit every subscriber's form; paste_into
       # (issue #228) would read every subscriber's clipboard; check_group
       # (issue #342) would tick or clear every subscriber's selection; presence
-      # (issue #358) would write every subscriber's presence state. They
+      # (issue #358) would write every subscriber's presence state; show_modal
+      # and close_dialog (issue #365) would open or close a modal, and move
+      # focus, on every screen at once. They
       # belong to the actor's own reply (reply.js) or gesture (on_client / a
       # reducer's $ops), never a broadcast. Names mirror Phlex::Reactive::JS's verbs.
       BROADCAST_REFUSED_OPS = %w[
         focus focus_first submit paste_into persist_state persist_clear check_group presence
+        show_modal close_dialog
       ].freeze
 
       # The broadcast_to verb kwargs (issue #185) → their Turbo stream action.
@@ -197,7 +200,9 @@ module Phlex
               "steals it in every subscriber's tab; broadcasting submit force-submits every " \
               "subscriber's form; broadcasting paste_into reads every subscriber's clipboard; " \
               "broadcasting check_group ticks or clears every subscriber's selection; " \
-              "broadcasting presence writes every subscriber's presence state. " \
+              "broadcasting presence writes every subscriber's presence state; " \
+              "broadcasting show_modal or close_dialog opens or closes a modal (and moves focus) on " \
+              "every screen — render the dialog open or closed, with data: { reactive_modal: true }, instead." \
               "These are actor concerns (reply.js / on_client / $ops)."
           end
 

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.15.0"
+    VERSION = "0.15.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.15.1
 platform: ruby
 authors:
 - Mikael Henriksson