phlex-reactive 0.14.4 → 0.15.0

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 presenceFeature from "phlex/reactive/features/presence"
 
 // phlex/reactive/runtime — the reactive controller WITHOUT its feature
 // modules (issue #275): the code both client entries share. It is not an
@@ -199,6 +200,7 @@ export function registerReactiveStreamRender() {
   if (typeof document === "undefined" || typeof document.addEventListener !== "function") return
   streamRenderRegistered = true
   document.addEventListener("turbo:before-stream-render", (event) => {
+    streamIntoRoots(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.
@@ -210,6 +212,39 @@ export function registerReactiveStreamRender() {
 // The names this registration had while it was two listeners.
 export { registerReactiveStreamRender as registerReactiveDismiss, registerReactiveStreamRender as registerReactiveEffects }
 
+// --- A stream into a connected root (issue #356) ---
+// A morph of a root makes it re-read its feature markers (#boundRootMorph); a
+// stream that renders INTO it — append, prepend or update of the root or a
+// child, before, after or replace of a child — fires neither a lifecycle nor
+// a morph of the root, so a marker it brings was never connected. The roots
+// a stream renders into are resolved here, before anything (effects, the opt-in
+// entry's hold) wraps Turbo's render; once that render has run, each one still
+// connected is told (STREAMED, not bubbling: an outer root's content is not
+// its own). The root re-runs its connected features' seeds and connects what
+// the new content needs, in both entries.
+const STREAMED = "reactive:streamed"
+
+function streamIntoRoots(event) {
+  const detail = event.detail
+  const render = detail?.render
+  const stream = detail?.newStream ?? event.target
+  const action = stream?.getAttribute?.("action")
+  const into = /^(append|prepend|update)$/.test(action)
+  if (typeof render !== "function" || !(into || /^(before|after|replace)$/.test(action))) return
+  const id = stream.getAttribute("target")
+  const selector = stream.getAttribute("targets")
+  const roots = new Set()
+  for (const target of id ? [document.getElementById(id)] : selector ? document.querySelectorAll(selector) : []) {
+    const root = (into ? target : target?.parentElement)?.closest?.('[data-controller~="reactive"]')
+    if (root) roots.add(root)
+  }
+  if (roots.size === 0) return
+  detail.render = async (el) => {
+    await render(el)
+    for (const root of roots) if (root.isConnected) root.dispatchEvent(new Event(STREAMED))
+  }
+}
+
 // 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.
@@ -237,6 +272,66 @@ export function __resetReactiveStreamRenderForTest() {
 //                            for the attribute AND the property. Nothing else
 //                            (a root's token, a field's class) is held.
 // data-reactive-morph-value on a field lets the morph write it while focused.
+// --- An engine without contenteditable="plaintext-only" (issue #355) ---
+// reactive_editable renders contenteditable="plaintext-only": the browser
+// itself then pastes plain text and inserts "\n" for Enter. An engine without
+// it reads the value as INVALID — the element is not editable, cannot even be
+// focused — so there every reactive editable is switched to "true" (and the
+// bindings feature does the plain-text paste itself). However it reaches the
+// page: present at load, appended by a stream into a root that is already
+// connected, loaded in a frame, written back by a morph of an unfocused
+// editable, or made reactive by a morph. One observer, only in such an engine; elsewhere the probe is all
+// that runs. Detected once per page.
+let plaintextOnly
+let plaintextObserver = null
+const PLAINTEXT_EDITABLE = "[data-reactive-editable][contenteditable=plaintext-only]"
+
+function plaintextSupported() {
+  if (plaintextOnly === undefined) {
+    try {
+      const probe = document.createElement("div")
+      probe.contentEditable = "plaintext-only"
+      plaintextOnly = probe.contentEditable === "plaintext-only"
+    } catch {
+      plaintextOnly = false
+    }
+  }
+  return plaintextOnly
+}
+
+function makeEditable(el) {
+  if (el.matches?.(PLAINTEXT_EDITABLE)) el.setAttribute("contenteditable", "true")
+  el.querySelectorAll?.(PLAINTEXT_EDITABLE).forEach(makeEditable)
+}
+
+export function registerReactivePlaintext() {
+  // (No element factory, no page to observe: never probe a stub document.)
+  if (plaintextObserver || typeof document === "undefined" || typeof document.createElement !== "function") return
+  if (plaintextSupported()) return
+  makeEditable(document)
+  plaintextObserver = new MutationObserver((records) => {
+    for (const record of records) {
+      if (record.type === "attributes") makeEditable(record.target)
+      else record.addedNodes.forEach(makeEditable)
+    }
+  })
+  plaintextObserver.observe(document.documentElement, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    // (a morph can also make an existing plaintext-only element reactive)
+    attributeFilter: ["contenteditable", "data-reactive-editable"],
+  })
+}
+
+// For tests: what the probe answers (undefined probes again), with no
+// observer installed.
+export function __setReactivePlaintextOnlyForTest(value) {
+  plaintextObserver?.disconnect()
+  plaintextObserver = null
+  plaintextOnly = value
+}
+
 let morphFocusRegistered = false
 
 //
@@ -244,8 +339,8 @@ let morphFocusRegistered = false
 // 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
+// stays as it is: the runtime switches it to "true" in an engine without
+// plaintext-only (registerReactivePlaintext, #355). 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 (
@@ -486,6 +581,7 @@ export function registerReactiveActions() {
   registerReactiveDefer()
   registerReactiveStreamRender()
   registerReactiveMorphFocus()
+  registerReactivePlaintext()
   registerReactiveOffline()
   registerReactiveDev()
 }
@@ -766,6 +862,13 @@ const CLIENT_OPS = Object.freeze({
     }
   },
 
+  // Write this tab's presence state (issue #358) through the root's
+  // presence_set action. The feature warns outside a reactive_presence root.
+  presence: (el, args) =>
+    __SPLIT__
+      ? withFeature("presence", (presence) => presence.set(el, args.state))
+      : presenceFeature.set(el, args.state),
+
   // Dispatch a bubbling CustomEvent (issue #96). RAW element.dispatchEvent — the
   // controller SHADOWS Stimulus's this.dispatch helper, so it must not be used.
   dispatch: (el, args) => {
@@ -963,6 +1066,23 @@ function keyFilterMatches(filter, event, keyMappings) {
   return typeof key === "string" && key.toLowerCase() === event.key.toLowerCase()
 }
 
+// Issue #357: a shortcut: ("mod+z", or { keys, inEditable }) is a window
+// 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.
+// (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
+// keydown through and this check, per record, picks the chord that fired.
+function shortcutApplies(spec, event, keyMappings) {
+  const target = event.target
+  if (spec?.inEditable !== true && (target?.isContentEditable || /^(input|textarea|select)$/.test(target?.localName)))
+    return false
+  const mod = /[Mm]ac|iP/.test(navigator.userAgentData?.platform ?? navigator.platform) ? "meta" : "ctrl"
+  return keyFilterMatches(shortcutKeys(spec).replace(/^mod\+/, `${mod}+`), event, keyMappings)
+}
+
 // Parse data-reactive-ops-param into binding records. Stimulus typecasts a
 // lone record to an object; several records stay a string (JSON.parse fails on
 // the join) and are split here. A LEGACY [[op, args]] list (array or JSON
@@ -1283,6 +1403,11 @@ function sortableNeeded(root) {
   return Boolean(root.matches?.(lists) || root.querySelector?.(lists))
 }
 
+// Presence (issue #358): the root is a reactive_presence roster.
+function presenceNeeded(root) {
+  return root.getAttribute?.("data-reactive-presence") != null
+}
+
 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.
@@ -1295,6 +1420,9 @@ const PRODUCTION_FEATURES = [
   ["compute", [computeNeeded, null, null, true]],
   // Nothing it does at connect is read by a request: it never gates.
   ["sortable", [sortableNeeded, 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]],
   [
     // Stream effects and dismissing flashes are document-level: the module
     // has no connect. A root that DECLARES an effect only gets it fetched
@@ -1458,7 +1586,7 @@ function featureTimeoutMs() {
 export function reactiveFeatureNames() {
   return __SPLIT__
     ? [...FEATURES.keys()]
-    : ["persist", "defer", "form", "bindings", "compute", "sortable", "effects", "hints", "devtools"]
+    : ["persist", "defer", "form", "bindings", "compute", "sortable", "presence", "effects", "hints", "devtools"]
 }
 
 export function __setReactiveFeatureForTest(name, needs, load, waiting, gates) {
@@ -1481,6 +1609,7 @@ export function __loadReactiveFeatureForTest(name) {
     bindings: bindingsFeature,
     compute: computeFeature,
     sortable: sortableFeature,
+    presence: presenceFeature,
     effects: effectsFeature,
     hints: hintsFeature,
     devtools: devtoolsFeature,
@@ -1534,6 +1663,7 @@ const FORM = 4
 const BINDINGS = 8
 const COMPUTE = 16
 const SORTABLE = 32
+const PRESENCE = 64
 
 // The default entry's features are part of this file: install them now, as
 // the opt-in entry does when one arrives.
@@ -1755,7 +1885,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 … SORTABLE —
+  // The default entry (issue #305): one bit per feature, PERSIST … PRESENCE —
   // asked for (its marker read true) and connected on this connection.
   #featuresAsked = 0
   #featuresOn = 0
@@ -1802,15 +1932,20 @@ export default class extends Controller {
     // 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.
+    // typed into it. And it hears a stream that rendered into the root
+    // (STREAMED, issue #356): the features already connected re-run their
+    // seeds first (a morph's own listeners do that for a morph), then what the
+    // new content needs connects.
     if (this.element.getAttribute?.("data-reactive-token-value") != null || deferNeeded(this.element)) {
       this.#boundRootMorph = (event) => {
         if (event.type === "focusin" ? !event.target.hasAttribute?.("data-reactive-editable") : event.target !== this.element) return
+        if (event.type === STREAMED) this.#reseed()
         if (__SPLIT__) this.#loadFeatures(true)
         else this.#connectFeaturesNow(true)
       }
       this.element.addEventListener?.("turbo:morph-element", this.#boundRootMorph)
       this.element.addEventListener?.("focusin", this.#boundRootMorph)
+      this.element.addEventListener?.(STREAMED, this.#boundRootMorph)
     }
 
     // Feature modules (issue #275): connect the ones that are here and START
@@ -1849,6 +1984,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(PRESENCE, "presence", presenceNeeded, (core) => presenceFeature.connect(this, core))
     }
   }
 
@@ -1886,6 +2022,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 & PRESENCE) this.#disconnectFeatureNow("presence", () => presenceFeature.disconnect(this, core))
     }
   }
 
@@ -2074,7 +2211,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).
+      // A reactive_editable's value and its last server-rendered text (#351),
+      // and whether the engine has contenteditable="plaintext-only" (#355).
+      plain: plaintextSupported,
       text: editableValue,
       served: serverText,
       // The confirm gate, as dispatch() runs it: the resolver inside the chain
@@ -2089,15 +2228,17 @@ export default class extends Controller {
 
   // Re-run the connect-time seeds that read field values, in connect() order
   // — for a feature that changed those values after connect() ran (the draft
-  // restore). Each is the same re-sync its feature runs after a morph; a root
-  // that did not opt into one skips it. on-complete re-ARMS without firing.
+  // restore), or content a stream rendered into the root (issue #356). Each is
+  // the same re-sync its feature runs after a morph; a root that did not opt
+  // into one skips it. on-complete re-ARMS without firing. Form and bindings
+  // also wire a binding whose gate reads true only now (a stream's content).
   #reseed() {
     if (!__SPLIT__) {
-      if (this.#featuresOn & FORM) formFeature.scan(this, this.#featureCore())
+      if (this.#featuresOn & FORM) formFeature.reseed(this)
       if (this.#featuresOn & BINDINGS) bindingsFeature.reseed(this)
       if (this.#featuresOn & COMPUTE) computeFeature.seed(this)
     } else {
-      this.#features.get("form")?.scan(this, this.#featureCore())
+      this.#features.get("form")?.reseed(this)
       this.#features.get("bindings")?.reseed(this)
       this.#features.get("compute")?.seed(this)
     }
@@ -2270,6 +2411,7 @@ export default class extends Controller {
     if (this.#boundRootMorph) {
       this.element.removeEventListener?.("turbo:morph-element", this.#boundRootMorph)
       this.element.removeEventListener?.("focusin", this.#boundRootMorph)
+      this.element.removeEventListener?.(STREAMED, this.#boundRootMorph)
     }
     // Early triggers (issue #273): a disconnected root records again.
     earlyState().connected.delete(this.element)
@@ -2296,9 +2438,13 @@ export default class extends Controller {
     // 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 } =
+    const { action, params, debounce, throttle, confirm, confirmWhen, outside, window: windowBound, optimistic, shortcut } =
       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
@@ -2345,7 +2491,11 @@ export default class extends Controller {
     // (which has no form-navigation default to lose) skips it and flips now, and
     // the failure revert snaps it back. A `change`-bound trigger is unaffected —
     // `change` isn't cancelable, so preventDefault was already a no-op there.
-    if (!windowBound && !this.#keepsNativeToggle(optimistic, target)) event.preventDefault()
+    //
+    // A shortcut (issue #357) IS prevented: its key filter has already narrowed
+    // the window binding to one chord the page claims (mod+s must not also open
+    // the browser's save dialog).
+    if ((shortcut != null || !windowBound) && !this.#keepsNativeToggle(optimistic, target)) event.preventDefault()
 
     // A reactive_lazy(on:) shell's trigger (issue #276) goes through the one
     // materialize entry point, which dedupes it against the observer, the
@@ -2484,6 +2634,10 @@ export default class extends Controller {
       // A detail miss (issue #346) is a complete no-op — checked before the
       // once record is spent, preventDefault and the confirm gate.
       if (!detailMatches(record, event)) continue
+      // So is a shortcut that is not this platform's twin or fired in an
+      // editable target (issue #357).
+      if (record.shortcut != null && !shortcutApplies(record.shortcut, event, this.application?.schema?.keyMappings))
+        continue
       if (onceBindingSpent(this, event, record)) continue
       this.#runBinding(record.legacy ? { ...params, ops: record.ops } : record, event, trigger)
     }
@@ -2491,7 +2645,7 @@ export default class extends Controller {
 
   // One on_client binding (issue #95): its outside guard, preventDefault rule,
   // confirm gate, then its ops — every flag read from the binding itself.
-  #runBinding({ ops, confirm, confirmWhen, outside, window: windowBound }, event, trigger) {
+  #runBinding({ ops, confirm, confirmWhen, outside, window: windowBound, shortcut }, event, trigger) {
     // Outside guard FIRST — identical semantics to dispatch() (issue #80): an
     // outside: trigger is a COMPLETE no-op for events inside this root, before
     // preventDefault and before any op runs.
@@ -2503,7 +2657,8 @@ export default class extends Controller {
     // would kill native clicks site-wide (issue #80 rationale). Runs BEFORE the
     // (possibly async) confirm gate below — a native default can't wait for a
     // pending dialog (same ordering as dispatch()).
-    if (!windowBound) event.preventDefault()
+    // A shortcut (issue #357) is prevented: it is one chord the page claims.
+    if (shortcut != null || !windowBound) event.preventDefault()
 
     // Resolve the effective confirm message — static string, or the conditional
     // Hash form (issue #179) evaluated over collected fields (a promise of it
@@ -3044,6 +3199,12 @@ export default class extends Controller {
         // already gets the action's HTTP response. Harmless without pgbus.
         const connectionId = this.#connectionId()
         if (connectionId) headers["X-Pgbus-Connection"] = connectionId
+        // A presence root's own connection (issue #358): the row its presence
+        // writes land on, whatever source comes first on the page.
+        const presence =
+          presenceNeeded(this.element) &&
+          document.getElementById(`reactive-presence-src-${this.element.id}`)?.getAttribute("connection-id")
+        if (presence) headers["X-Reactive-Presence"] = presence
 
         // ONLY `fetch` itself is the network boundary — offline, DNS, a reset
         // connection. Everything below this inner try (reading the body,

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

@@ -356,6 +356,11 @@ module Phlex
               raise ArgumentError, "#{self}: reactive_dormant takes true or false, got #{dormant.inspect}"
             end
 
+            # Issue #358: a dormant root never connects, so it could never join.
+            # A ClientBindings-only class has no presence declaration to refuse.
+            refuse_dormant_presence! if dormant && respond_to?(:reactive_presence_declaration) &&
+                                        reactive_presence_declaration
+
             Phlex::Reactive::Dormant.reject_visible_lazy!(self) if dormant
 
             Registry.write_scalar(self, :dormant, dormant)

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

@@ -127,6 +127,10 @@ module Phlex
              (on_complete = self.class.reactive_on_complete_attr)
             data[:reactive_on_complete] = on_complete
           end
+          # Presence (issue #358): the signed src of the roster's presence
+          # stream, from which the client mints its subscription. Only a class
+          # that declares reactive_presence has the method.
+          data.merge!(reactive_presence_data) if respond_to?(:reactive_presence_data)
           { data: }
         end
 
@@ -280,6 +284,17 @@ module Phlex
         # (trailing-edge) — passing both raises ArgumentError.
         #   div(**mix(reactive_root, on(:track, event: "scroll", window: true, throttle: 250)))
         #
+        # `shortcut:` (issue #357, also RESERVED) binds a page-level keyboard
+        # chord: a window keydown whose `mod` is meta on Apple platforms and
+        # ctrl elsewhere (rendered as a meta twin and a ctrl twin; the client
+        # runs the one for its platform). Unlike a plain window binding, the
+        # client prevents the chord's native default, and it skips the chord
+        # while focus is in an input, textarea, select or contenteditable
+        # (native text undo keeps working) unless the Hash form opts in. It
+        # decides event:, window: and outside:, so passing one raises.
+        #   span(**on(:undo, shortcut: "mod+z"))
+        #   span(**on(:close, shortcut: { keys: "esc", in_editable: true }))
+        #
         # `optimistic:` (issue #98) — a small, ALWAYS-REVERSIBLE vocabulary of
         # COSMETIC hints the client applies the instant the trigger fires and
         # REVERTS if the round trip fails, so a click/toggle gives instant feedback
@@ -324,9 +339,9 @@ module Phlex
         # busy_on for scoped indicators.
         #   button(**on(:save, busy: "Saving…")) { "Save" }
         #   button(**on(:destroy, confirm: "Sure?", busy: { add_class: "opacity-50" })) { "Delete" }
-        def on(action_name, event: "click", debounce: nil, throttle: nil, confirm: nil,
+        def on(action_name, event: nil, debounce: nil, throttle: nil, confirm: nil,
                window: false, once: false, outside: false, optimistic: nil, busy: nil,
-               **params)
+               shortcut: nil, **params)
           reject_removed_on_kwargs!(action_name, params)
           # A typo'd or forgotten action renders fine and only surfaces as an
           # opaque 403 at CLICK time (the endpoint's default-deny). Under
@@ -362,8 +377,11 @@ module Phlex
               "exclusive (debounce is trailing-edge, throttle is leading-edge); pick one"
           end
 
-          window_bound = window || outside
-          action = "#{event}#{"@window" if window_bound}->reactive#dispatch#{":once" if once}"
+          # Guarded here, not inside: building the caller label allocates (on() is a hot path).
+          shortcut = shortcut_for!("on(#{action_name.inspect})", shortcut, event:, window:, outside:) unless shortcut.nil?
+          event ||= "click"
+          window_bound = window || outside || !shortcut.nil?
+          action = trigger_descriptors(event, shortcut, window_bound, "dispatch", once)
           attrs = {
             data: {
               action:,
@@ -384,6 +402,9 @@ module Phlex
           # The client decides preventDefault behavior from event.params (never by
           # sniffing the descriptor), so EVERY window binding flags the param.
           attrs[:data][:reactive_window_param] = "true" if window_bound
+          # Issue #357: the client reads the shortcut to pick the twin for its
+          # platform, skip editable targets and prevent the chord.
+          attrs[:data][:reactive_shortcut_param] = shortcut_param_attr(shortcut) if shortcut
           # Force type="button" for click triggers so a bare button inside a <form>
           # can't submit it — EXCEPT when checked: :keep is declared: that hint's
           # whole point is to let a click-bound checkbox/radio flip natively, and a
@@ -406,7 +427,9 @@ module Phlex
         # modifiers (#80): outside-click-to-close a dropdown is
         #   div(**mix(reactive_root, on_client(:click, js.hide("#menu"), outside: true)))
         # Window-bound triggers are never preventDefault-ed by the client and skip
-        # the forced type="button".
+        # the forced type="button". `shortcut:` (issue #357) works as on()'s, on
+        # a bare :keydown only:
+        #   div(**mix(reactive_root, on_client(:keydown, js.toggle("#palette"), shortcut: "mod+k")))
         #
         # Issue #271: each call emits ONE self-describing binding record —
         #   data-reactive-ops-param='{"on":"click","window":true,"outside":true,"ops":[…]}'
@@ -437,7 +460,8 @@ module Phlex
         # Validation is loud: only a non-empty Phlex::Reactive::JS chain is
         # accepted — a dead trigger should fail at render, not no-op in the
         # browser.
-        def on_client(event, ops, window: false, once: false, outside: false, confirm: nil, detail: nil)
+        def on_client(event, ops, window: false, once: false, outside: false, confirm: nil, detail: nil,
+                      shortcut: nil)
           unless ops.is_a?(Phlex::Reactive::JS)
             raise ArgumentError,
               "on_client expects a Phlex::Reactive::JS chain (e.g. js.toggle(\"#menu\")), " \
@@ -454,11 +478,15 @@ module Phlex
               "submit event this trigger is bound to. Bind the submit op to another event " \
               "(change/input), or gate it behind a reducer's $ops / reactive_on_complete."
           end
-          window_bound = window || outside
+          shortcut = client_shortcut!(event, shortcut, window:, outside:)
+          window_bound = window || outside || !shortcut.nil?
           record = client_binding_record(event, ops, window_bound:, outside:, once:, confirm:, detail:)
+          # The record's `on` stays the bare keydown: the client reads a key
+          # filter from `on`, and `mod` is not a key.
+          record["shortcut"] = shortcut.param if shortcut
           attrs = {
             data: {
-              action: "#{event}#{"@window" if window_bound}->reactive#runOps#{":once" if once}",
+              action: trigger_descriptors(event, shortcut, window_bound, "runOps", once),
               # Space-free (issue #271): compact JSON has no structural
               # whitespace, so every space is inside a string, where \u0020
               # parses to the same string — and mix's space-join stays splittable.
@@ -1732,6 +1760,49 @@ module Phlex
             "on(#{action_name.inspect}) #{key}: was removed in issue #181 — use #{REMOVED_ON_KWARGS[key]}"
         end
 
+        # Issue #357: parse on()'s shortcut: (nil when absent). A shortcut
+        # decides the event, the window binding and the containment rule, so
+        # an explicit event:/window:/outside: next to it is a mistake.
+        def shortcut_for!(caller, shortcut, event:, window:, outside:)
+          { "event:" => event, "window:" => window, "outside:" => outside }.each do |name, value|
+            next unless value
+
+            raise ArgumentError,
+              "#{caller} got shortcut: with #{name} — a shortcut is always a window keydown " \
+              "binding; drop #{name}"
+          end
+          Phlex::Reactive::Shortcut.parse(shortcut)
+        end
+
+        # on_client's event is positional: with shortcut: it must be the bare
+        # keydown (the key filter comes from the shortcut).
+        def client_shortcut!(event, shortcut, window:, outside:)
+          return if shortcut.nil?
+
+          unless event == "keydown"
+            raise ArgumentError,
+              "on_client(#{event.inspect}) got shortcut: — bind it to :keydown " \
+              "(on_client(:keydown, ops, shortcut: \"mod+k\")); the key comes from the shortcut"
+          end
+          shortcut_for!("on_client(:keydown)", shortcut, event: nil, window:, outside:)
+        end
+
+        # 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).
+        def trigger_descriptors(event, shortcut, window_bound, method, once)
+          return "#{event}#{"@window" if window_bound}->reactive##{method}#{":once" if once}" unless shortcut
+
+          shortcut.filters.map { "keydown.#{it}@window->reactive##{method}#{":once" if once}" }.join(" ")
+        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)
+          param = shortcut.param
+          param.is_a?(Hash) ? param.to_json : param
+        end
+
         # Normalize + validate a pending-state hint (issue #181), returning its
         # JSON wire form. ONE vocabulary + ONE normalizer for both optimistic: (kind
         # :optimistic, reverts on FAILURE) and busy: (kind :busy, reverts on

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # The reactive_presence macro (issue #358). Not named `Presence`: this
+      # module is in every reactive component's constant lookup, where a bare
+      # noun would shadow a host app's kit component of that name (the #233
+      # rule). The behaviour it adds lives in Phlex::Reactive::Presence.
+      module PresenceDeclaration
+        extend ActiveSupport::Concern
+
+        # A presence name is the last part of the stream name, so it is one
+        # identifier: no colon (the stream-name separator), no spaces.
+        PRESENCE_NAME = /\A[a-z][a-z0-9_]*\z/
+
+        class_methods do
+          # Declare this component the roster of a presence stream:
+          # [record, :presence, name], or [*key, :presence, name] for a
+          # record-less component.
+          #
+          #   reactive_record :board
+          #   reactive_presence :viewers, state: { selected: :integer }, ttl: 45
+          #
+          # `state:` is each tab's ephemeral state, typed with the same table as
+          # action params; undeclared keys are dropped. `ttl:` is how many
+          # seconds a silent tab survives. Adds the presence_set action (what
+          # js.presence sends) and `presence` (the roster) to the component.
+          def reactive_presence(name, state: {}, ttl: Phlex::Reactive::Presence::DEFAULT_TTL, key: nil)
+            require_server_actions!(:reactive_presence)
+            declaration = build_presence_declaration(name, state, ttl, key)
+            refuse_dormant_presence! if reactive_dormant?
+            # The name's fit in pgbus's stream-name budget is configuration (the
+            # queue prefix), so it is refused here; the render re-checks it.
+            transport = Phlex::Reactive::Presence::Transport
+            if transport.wired? && !transport.fits?(declaration.name)
+              raise Phlex::Reactive::ConfigurationError, transport.over_budget_message(self, declaration.name)
+            end
+
+            # The generated action. Exempt from verify_authorized: the signed
+            # token already proves the actor rendered this root, and the write
+            # is typed, default-deny, ephemeral and lands only on the actor's own
+            # row (keyed by its secret SSE connection id). A component that needs
+            # a check defines authorize_presence_state!(**state); the action runs
+            # it first.
+            action :presence_set, params: declaration.state
+            skip_verify_authorized :presence_set
+            Registry.write_scalar(self, :presence, declaration)
+            include Phlex::Reactive::Presence::ComponentMethods
+
+            # Class load runs before a database exists: the signatures alone gate it.
+            transport.register_ttl(declaration.name, ttl) if transport.wired?
+            declaration
+          end
+
+          # The Phlex::Reactive::Presence::Declaration, or nil.
+          def reactive_presence_declaration
+            Registry.resolve_scalar(self, :presence, :reactive_presence_declaration)
+          end
+
+          # The presence stream name a roster of `record` subscribes to — what
+          # streams_authorize sees. For a strict per-record check at connect
+          # time: compare it with the key of each record the user may view.
+          # A record-less roster (key:) ignores `record`.
+          def reactive_presence_stream_name_for(record = nil)
+            declaration = reactive_presence_declaration
+            subject = declaration.key || [record]
+            Phlex::Reactive::Presence::Transport.stream_name([*subject, :presence, declaration.name])
+          end
+
+          private
+
+          def build_presence_declaration(name, state, ttl, key)
+            name = name.to_s
+            unless PRESENCE_NAME.match?(name)
+              raise ArgumentError,
+                "#{self.name}: reactive_presence name must be a lowercase identifier (it ends the stream " \
+                "name), got #{name.inspect}"
+            end
+            unless ttl.is_a?(Integer) && ttl.positive?
+              raise ArgumentError, "#{self.name}: reactive_presence ttl: must be a positive Integer (seconds), " \
+                                   "got #{ttl.inspect}"
+            end
+            refuse_ttl_within_heartbeat!(ttl)
+
+            state = state.transform_keys(&:to_sym)
+            if state.key?(Phlex::Reactive::Presence::NOTE_KEY.to_sym)
+              raise ArgumentError,
+                "#{self.name}: reactive_presence state key #{Phlex::Reactive::Presence::NOTE_KEY} is reserved"
+            end
+
+            Phlex::Reactive::Presence::Declaration.new(
+              name: name.to_sym, state: state.freeze, ttl:, key: key && Array(key).dup.freeze
+            )
+          end
+
+          # A ttl at or below the heartbeat would expire a live tab between two
+          # beats: its row would vanish and come back on the next one.
+          def refuse_ttl_within_heartbeat!(ttl)
+            heartbeat = Phlex::Reactive::Presence::Transport.heartbeat_interval
+            return if ttl > heartbeat
+
+            raise ArgumentError,
+              "#{name}: reactive_presence ttl: #{ttl} is at or below the transport's heartbeat interval " \
+              "(#{heartbeat} s), so a live tab would expire between two beats. Use more than #{heartbeat} " \
+              "(two missed beats is a good floor)."
+          end
+
+          def refuse_dormant_presence!
+            raise ArgumentError,
+              "#{name}: reactive_presence cannot be dormant — a dormant root never connects, so its tab " \
+              "would never join the stream. Drop reactive_dormant on this component."
+          end
+        end
+      end
+    end
+  end
+end