phlex-reactive 0.14.4 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e80c9d7f2587b324d3bd1658fbe09f93dd45d8fb9ed2dd300f302ac9577c3bc
-  data.tar.gz: cfd7d489f859f5c591e8d6a391d9c04b2b4b1906ee9d0067ced14539f8f3d2b3
+  metadata.gz: eeebc2783f571e3e3fcc0847318ebef76050954e0e56a99f627e8e5654467133
+  data.tar.gz: 974cc0de7e79babb8834bf41a10001e69a087bda3daf6a87122cae7654e128cb
 SHA512:
-  metadata.gz: 79b0d752c36664dc374c69944d127556732864b3a8582ff68ae29d76ca70ad18289d60a375d99671697f91e5609f27e6cc4b7718240dc9fc632ac2425ecae671
-  data.tar.gz: 0d19985aa77283b419e815e35691c626f4646356fc04282f5441b4f434b2b15c6a052ade40b1bde8442bead4eb3b3f1900a15cb937dfe9132a9af2b0b16cb57b
+  metadata.gz: f95657cd231a4e711d6300fae52cbefacb42f34d5803f98073366710855a7c5906e795844800c55e8a6ee2b089224809bacb739c0c90f1a89c97c23851c2c7e7
+  data.tar.gz: 0b47dacc177e41d086e045ec842879358c68d4ec298615c1fcb6e23fc8cdb8b53ce5db96fa4fe2424b1fdaa381870fd29ce6f50b1ac70b7375790590e1eae793

data/CHANGELOG.md

@@ -8,6 +8,49 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Presence — `reactive_presence`, `presence`, `js.presence` (#358).** A
+  roster component declares the presence stream it shows
+  (`reactive_presence :viewers, state: { selected: :integer }, ttl: 45`) and
+  reads it with `presence`: one peer per browser tab (`seat`, `member_id`,
+  `metadata`, `state`), grouped by person with `members`, filtered with
+  `where(selected: id)`. Tabs join on SSE connect, leave on disconnect and
+  expire after `ttl:` seconds of silence; each change re-renders the roster for
+  every viewer (one coalesced morph). Each tab's declared state is set with
+  `js.presence(**state)` (through the generated `presence_set` action, typed,
+  default-deny, and exempt from `verify_authorized` unless the component defines
+  `authorize_presence_state!`) or `presence.set(**state)` from an action. The
+  client marks this tab's element `data-reactive-presence-me` and the same
+  person's other elements `data-reactive-presence-same-member`, and fires
+  `reactive:presence` with the seats that joined and left. A new `presence`
+  feature module (1.3 KB gzipped): the default client bundles it (+992 B), the
+  split client fetches it only for a page with a presence root (+100 B in the
+  core). Needs pgbus 0.18.1 or later; without it a presence root raises
+  `Phlex::Reactive::ConfigurationError` at render. Create the table with
+  `rails g pgbus:add_presence` (or upgrade it with
+  `rails g pgbus:add_presence_seats`), return each viewer's identity from
+  `config.streams_authorize` (with none, pgbus joins the connection to no
+  roster), and run an ActiveJob adapter (joins, leaves and expiries render in
+  `PresenceRenderJob`). A closed tab leaves within about a second.
+  `ttl:` must be above pgbus's `streams_heartbeat_interval` (15 s by default). `js.presence` is refused on a broadcast, like `focus`. `reactive_presence_stream_name_for(record)` on the class gives a record's stream name, for a per-record check in `streams_authorize`. Docs: "Presence".
+
+- **`shortcut:` on `on()` and `on_client(:keydown, …)` — page-level keyboard
+  shortcuts (#357).** `on(:undo, shortcut: "mod+z")` binds a window keydown
+  where `mod` is ⌘ on Apple platforms and Ctrl elsewhere (rendered as a meta
+  twin and a ctrl twin; the client runs its platform's, the other is a no-op).
+  The shortcut does nothing while focus is in an `input`, `textarea`, `select`
+  or anything `contenteditable`, so native text undo keeps working
+  (`shortcut: { keys: "esc", in_editable: true }` opts in), and a matching
+  chord is `preventDefault`-ed before any `confirm:` dialog, also when pressed
+  before the controller connects (`phlex/reactive/early`). `shortcut:` with
+  `event:`, `window:` or `outside:`, a key outside Stimulus's default key map,
+  or an `on_client` event other than `:keydown` raises `ArgumentError` at
+  render. The inspector shows `keydown@window shortcut=mod+z`. `early.min.js`
+  grows 195 B gzipped (1,491 B); the default client 177 B.
+  **Compatibility:** `shortcut` is now a reserved keyword on `on(...)` and no
+  longer passes through as an action param. `event: "keydown.meta+z", window:
+  true` without `shortcut:` behaves exactly as before (never prevented, no
+  editable guard).
+
 - **Sortable lists — `reactive_sortable`, `reactive_sortable_source`,
   `reactive_sortable_item` (#350).** Rows drag to reorder a list with a mouse,
   a finger (a 200 ms press) or the keyboard (Space picks up, arrows move,
@@ -58,6 +101,33 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **A stream that renders into a connected root wires what its content needs
+  (#356).** A root read its feature markers only at connect and after a morph
+  of itself, so a `reactive_show` target, select-all/count group, filter,
+  nested list, dirty field or paste trigger that an `append`, `prepend`,
+  `update`, `before`, `after` or child `replace` brought into it stayed dead
+  until the root reconnected. Now, once such a stream has rendered, the root
+  re-runs the seeds of the features it has (a new show target takes the
+  field's current value) and connects any feature its new content needs, in
+  both clients; bindings and form also wire a binding whose gate reads true
+  only then. As after a morph, this covers a root with an action token or a
+  lazy shell; a tokenless, client-only root does not re-read. On the split
+  client the stream's render waits for the module the content needs, as it
+  already did for an incoming root, so the content lands wired; the wait is
+  capped at 1 s, after which Turbo renders and the root connects the module
+  when it arrives. A draft
+  restore no longer marks fields `data-reactive-dirty` on a root that never
+  opted into dirty tracking (one that only gates a paste trigger).
+- **An editable is editable in an engine without `contenteditable="plaintext-only"`,
+  however it reaches the page (#355).** Such an engine reads the server's
+  `plaintext-only` as invalid, so the element cannot even be focused. The
+  bindings feature switched it to `"true"` only when it connected, or after a
+  morph of the root, which left an editable that a stream appended, a frame
+  loaded or an unfocused morph rewrote uneditable. The runtime now does the
+  switch with one observer, installed only in such an engine (elsewhere the
+  probe is all that runs). Bundle: default +157 B gzip, split core +241 B,
+  `features/bindings` -138 B.
+
 - **A `checked:`-only `reactive_show_targets` entry hides at zero boxes
   (#348).** `"#bulk-bar" => { if: { "ids[]" => { checked: 1.. } } }` was left
   visible once the owning root held no box of the group (the last ticked row

data/README.md

@@ -118,7 +118,7 @@ instead, import `phlex/reactive/early` eagerly (the engine pins it with
 import "phlex/reactive/early"
 ```
 
-It gzips to under 1.3 KB and has no Stimulus import. A trigger (`on(...)` or
+It gzips to under 1.5 KB and has no Stimulus import. A trigger (`on(...)` or
 `on_client(...)`) that fires before the controller connects — a click while a
 lazily loaded controller is still downloading, a custom event dispatched as soon
 as the page is interactive — is queued, its native default is stopped exactly
@@ -162,6 +162,11 @@ Good to know:
   root until it disconnects — keep its trigger element stable across replies
   (a reply that morphs the root but swaps that element leaves the hotkey
   dead until the next disconnect), or bind the hotkey without `once:`.
+- A `shortcut:` (below) is the exception to "never prevented": the chord the
+  page claims is prevented before connect too (so `mod+s` cannot open the
+  browser's save dialog in the first moments), and a chord pressed inside a
+  field the user is typing in, or the other platform's `mod` twin, is neither
+  queued nor prevented.
 - Not captured, so still lost before connect: `outside:` triggers (an outside
   click before connect has nothing to close, and recording it would wake a
   dormant dropdown on every click); key filters beyond Stimulus's default key
@@ -936,6 +941,46 @@ div(**mix(reactive_root, on(:track, event: "scroll", window: true, throttle: 500
 These four (like `debounce:`/`confirm:`/`listnav:`) are **reserved keyword
 names** on `on(...)` — no longer usable as free action params.
 
+**Page-level shortcuts — `shortcut:`.** Undo, redo, save and a command palette
+bind with one keyword on `on(...)` or `on_client(:keydown, …)`:
+
+```ruby
+div(**mix(reactive_root, on_client(:keydown, js.toggle("#palette"), shortcut: "mod+k"))) do
+  span(**on(:undo, shortcut: "mod+z"))         # one reactive action per element
+  span(**on(:redo, shortcut: "mod+shift+z"))
+  textarea(name: "notes")
+end
+```
+
+A shortcut is a window `keydown` binding with three rules a plain
+`event: "keydown.meta+z", window: true` does not have:
+
+- **`mod` is ⌘ on Apple platforms and Ctrl elsewhere.** The helper renders a
+  meta twin and a ctrl twin; the client runs the one for its platform (from
+  `navigator.userAgentData.platform`, else `navigator.platform`), and the other
+  is a complete no-op, so Ctrl+Z on a Mac stays the browser's. A chord without
+  `mod` (`"esc"`, `"alt+n"`) renders one descriptor.
+- **Typing is left alone.** With focus in an `input`, `textarea`, `select` or
+  anything `contenteditable` (including `reactive_editable`), the shortcut does
+  nothing and the browser's own handling (text undo) runs. Opt in with the Hash
+  form: `shortcut: { keys: "esc", in_editable: true }`.
+- **The chord is prevented.** A matching shortcut calls `preventDefault`
+  synchronously, before any `confirm:` dialog, so `mod+s` does not also open
+  the save dialog. (Other window bindings are still never prevented.)
+
+`shortcut:` decides the event and the window binding: passing it with
+`event:`, `window:` or `outside:` raises `ArgumentError`, as does a key outside
+Stimulus's default key map (a letter, a digit, `enter`, `tab`, `esc`, `space`,
+the arrows, `home`, `end`, `page_up`, `page_down`; bind a custom `keyMappings`
+key with `event:` and `window:`). On `on_client` the event must be `:keydown`.
+`shortcut` is now a **reserved keyword** on `on(...)`.
+
+`once: true` on a shortcut unbinds the Stimulus descriptor after its first
+firing, and a press inside a field counts: the guard leaves the chord to the
+browser, but the `:once` listener is already spent. Keep `once:` off a
+shortcut that can be pressed while the user types, or pair it with
+`in_editable: true`.
+
 ### Optimistic visual hints (`optimistic:`)
 
 Every reactive action waits a full round trip for its visual change — and it's
@@ -1405,6 +1450,11 @@ free as an ordinary action-param name (`on(:switch, key: "pgbus")` still passes
 > trigger to its own element (the field saves on Enter; a Cancel button — or the
 > field's own blur — handles Escape), as above.
 
+A page-level chord (undo on ⌘Z/Ctrl+Z, save on `mod+s`) is a `shortcut:`
+rather than `event:` with `window: true`: it resolves `mod` per platform,
+leaves fields the user is typing in alone and prevents the chord (see
+*Page-level shortcuts* above).
+
 ### Value-conditional visibility (`reactive_show`)
 
 `on_client` covers the *unconditional* client-only interactions; the last gap
@@ -1698,6 +1748,146 @@ list; a reply that morphs the list puts the rows in the server's order.
 
 Full guide: [Sortable lists](https://phlex-reactive.zoolutions.llc/docs/sortable-lists).
 
+### Presence (`reactive_presence`)
+
+Who is viewing a stream, one entry per browser tab, each tab with a small
+declared state (the item it has selected), on a roster component that
+re-renders itself in every viewer's tab when a tab joins, leaves, goes silent
+or changes its state. No controller code, no Stimulus controller.
+
+```ruby
+class Boards::Viewers < Phlex::HTML
+  include Phlex::Reactive::Component
+
+  reactive_record :board
+  reactive_presence :viewers, state: { selected: :integer }, ttl: 45
+
+  def initialize(board:) = @board = board
+
+  def view_template
+    div(**reactive_root) do
+      presence.members.each do |member|                 # one per person
+        span(**reactive_presence_member(member)) { member.metadata["name"] }
+      end
+      @board.cards.each do |card|
+        li(**on_client(:click, js.presence(selected: card.id))) do
+          plain card.title
+          presence.where(selected: card.id).each do |peer| # who is on this card
+            span(**reactive_presence_peer(peer), class: "dot")
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+- **The stream** is `[record, :presence, name]` (a record-less roster passes
+  `key: ["lobby"]`), named `"<16-char digest of the record (or the key: value)>:presence:<name>"`,
+  so any model name and id fit pgbus's stream-name budget (41 chars with the
+  default queue prefix). That leaves 15 characters for the presence name; a
+  longer one raises `Phlex::Reactive::ConfigurationError` at render. The root
+  subscribes to it by itself: the client mints a
+  `<pgbus-stream-source>` from the root's signed src, so the page must load the
+  pgbus client element (`import "pgbus/stream_source_element"`, which any
+  `pgbus_stream_from` on the page already does).
+- **`presence`** is the roster as this render reads it: `peers` (one per tab:
+  `seat`, `member_id`, `metadata`, `state`, `joined_at`), `members` (grouped by
+  person: `id`, `metadata`, `seats`, `state`), `where(**state)`, `count`,
+  `empty?`, and in an action `me` and `set(**state)`.
+- **State** is declared like action params; undeclared keys are dropped.
+  `js.presence(selected: 7)` sends it from the browser through the generated
+  `presence_set` action; `presence.set(selected: 7)` writes it from an action of
+  your own. Either way only this tab's row changes and the other viewers get a
+  morph. The generated action replies `reply.morph` for the actor; an action of
+  your own must return `reply.morph` itself.
+- **A state-backed roster** (`reactive_state`): its state is stored on each
+  seat row in `pgbus_presence_members` (in the note the re-render reads), and
+  the roster renders as one piece of markup under one id for every viewer. So
+  its `reactive_state` must be the same for every viewer; per-viewer state
+  belongs in presence state (`state:`).
+- **Authorization**: `presence_set` skips `verify_authorized`. The signed token
+  proves the actor rendered this root, and the write is typed, ephemeral, and
+  lands only on the actor's own row, keyed by its SSE connection id, which
+  only that tab knows. To check the value (the card must belong to the board),
+  define `authorize_presence_state!(**state)` and raise; it runs first. That hook
+  guards only the generated `presence_set`: an action of your own that calls
+  `presence.set` authorizes its state itself. The client also sends `presence_set` with no state on every connect (the
+  announce): that writes no value, so the hook is not called for it.
+- **`presence.me`** is the acting tab, and during an action it stays the actor
+  while the roster renders for the other viewers too. Never branch the shared
+  output on it; the client's `-me` marks are per tab. (Likewise
+  `reactive_connection_id` is the first `<pgbus-stream-source>` on the page, so
+  one loaded later, ahead of it in the DOM, can change it; presence writes use
+  their own connection and are unaffected.)
+- **"Me"**: the roster renders once for everyone, so the client marks this
+  tab's element `data-reactive-presence-me` and the same person's other
+  elements `data-reactive-presence-same-member` after every morph. Style them.
+  Both need this tab's `reactive_presence_peer` element on the roster: a roster
+  of members only has none, so nothing is marked.
+- **Events**: `reactive:presence` fires on the root with
+  `{ joined: [seat…], left: [seat…], me: seat }` when a morph changes who is
+  there; a replayed frame that changes nothing fires nothing. The root names
+  the seats its render saw (`data-reactive-presence-roster`), so this works for
+  a roster that renders people, not tabs.
+- **Leaving**: a closed tab leaves within about a second (pgbus watches each
+  SSE socket for the browser closing it). A tab that crashes or loses its
+  network, so nothing closes the socket cleanly, leaves on the next failed
+  heartbeat write (`streams_heartbeat_interval`, 15 s by default) or expires
+  after `ttl:` seconds. A reconnect keeps the tab's seat id and re-sends its
+  state, but pgbus drops the row on the disconnect, so unless the reconnect
+  lands within one coalesce window (150 ms) peers see that seat leave and
+  join again (`reactive:presence` reports both). A row that expires while its
+  socket stays open (the tab missed its beats) is re-joined by the heartbeat
+  without its state, until the tab's next `js.presence`. `ttl:` must be above the
+  transport's heartbeat interval, or a live tab would expire between two
+  beats: `reactive_presence` raises otherwise.
+- **Transport**: needs pgbus 0.18.1 or later (presence keyed by SSE
+  connection, `pgbus:connected` only after the tab's seat joined,
+  `config.streams_authorize`). Create the table with
+  `rails g pgbus:add_presence`, or upgrade an older one with
+  `rails g pgbus:add_presence_seats`. `ttl:` (45 by default) is written into
+  pgbus's `streams_presence_ttl` under the stream's pattern. Action Cable has
+  no connection identity: rendering a presence root without it raises
+  `Phlex::Reactive::ConfigurationError`. Every other component is unaffected.
+- **Identity**: pgbus takes each tab's person from what
+  `config.streams_authorize` returns for the stream. `nil` or `false` answers
+  403; `true` authorizes with no identity, and pgbus joins such a connection
+  to no roster (the tab then warns in the console that it never appeared).
+  Per-record authorization already happens at render: the signed src is
+  minted only into a roster root your app chose to render for this user.
+  `streams_authorize` is the revocation layer (the signed name proves pgbus
+  minted it, not that this viewer may still read it: a removed member keeps a
+  working name until the secret rotates). For a strict per-record check at
+  connect time, compare `stream_name` with the presence key of each record the
+  user may view (or give a record-less roster a `key:` with a prefix you can
+  parse):
+
+  ```ruby
+  # config/initializers/pgbus.rb
+  Pgbus.configure do |config|
+    config.streams_authorize = ->(env, stream_name) {
+      user = env["warden"]&.user
+      next unless user&.active?
+      next unless user.may_stream?(stream_name) # keep your app's own check for every stream
+
+      if stream_name.end_with?(":presence:viewers")
+        next unless user.boards.any? { Boards::Viewers.reactive_presence_stream_name_for(it) == stream_name }
+      end
+      { id: user.id, metadata: { name: user.name } }
+    }
+  end
+  ```
+
+  A presence stream's name is a digest (`"<16 hex>:presence:<name>"`), so the
+  record cannot be read back from it: `reactive_presence_stream_name_for`
+  computes it from the record. A User works too (pgbus reads its `#id`); shape
+  the member from it with
+  `config.streams_presence_member = ->(user) { { id: user.id, metadata: { name: user.name } } }`.
+- **Jobs**: a join, a leave and an expiry re-render the roster in
+  `Phlex::Reactive::PresenceRenderJob` (on `defer_job_queue`), so the app needs
+  an ActiveJob adapter that runs jobs. A state change renders in the action.
+
 ### Client-only drafts (`reactive_persist`)
 
 "Don't make me start over": a public application form, a multi-step wizard,

data/app/controllers/phlex/reactive/actions_controller.rb

@@ -347,24 +347,34 @@ module Phlex
       # Phlex::Reactive::Response survives to response_streams.
       def run_action(component, action_def, coerced)
         Phlex::Reactive.with_connection_id(request.headers["X-Pgbus-Connection"]) do
-          with_around_actions(component, action_def, coerced) do
-            transaction_wrapper do
-              # verify_authorized (issue #168): open the tracking window, run the
-              # action, then verify INSIDE the transaction so an unverified action
-              # rolls its mutation back (fail-closed). with_tracking is a bare
-              # yield's-worth of overhead; verify! is a no-op when the feature is
-              # off / the action is skipped / something marked. The interceptor
-              # (create_action's instrument!) marks the window on a real
-              # authorization call.
-              Phlex::Reactive::Authorization.with_tracking do
-                result = if coerced.any?
-                           component.public_send(action_def.name, **coerced)
-                         else
-                           component.public_send(action_def.name)
-                         end
-                Phlex::Reactive::Authorization.verify!(component.class, action_def)
-                result
-              end
+          # Issue #358: a presence root also sends its presence connection, the
+          # row a presence write lands on.
+          Phlex::Reactive::Presence.with_connection_id(request.headers[Phlex::Reactive::Presence::HEADER]) do
+            run_action_wrapped(component, action_def, coerced)
+          end
+        end
+      end
+
+      # The action inside the around_action stack, the transaction and the
+      # verify_authorized window (see run_action).
+      def run_action_wrapped(component, action_def, coerced)
+        with_around_actions(component, action_def, coerced) do
+          transaction_wrapper do
+            # verify_authorized (issue #168): open the tracking window, run the
+            # action, then verify INSIDE the transaction so an unverified action
+            # rolls its mutation back (fail-closed). with_tracking is a bare
+            # yield's-worth of overhead; verify! is a no-op when the feature is
+            # off / the action is skipped / something marked. The interceptor
+            # (create_action's instrument!) marks the window on a real
+            # authorization call.
+            Phlex::Reactive::Authorization.with_tracking do
+              result = if coerced.any?
+                         component.public_send(action_def.name, **coerced)
+                       else
+                         component.public_send(action_def.name)
+                       end
+              Phlex::Reactive::Authorization.verify!(component.class, action_def)
+              result
             end
           end
         end

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

@@ -27,6 +27,7 @@ registerReactiveFeatureLoader("form", () => import("phlex/reactive/features/form
 registerReactiveFeatureLoader("bindings", () => import("phlex/reactive/features/bindings"))
 registerReactiveFeatureLoader("compute", () => import("phlex/reactive/features/compute"), waitingForEdit)
 registerReactiveFeatureLoader("sortable", () => import("phlex/reactive/features/sortable"))
+registerReactiveFeatureLoader("presence", () => import("phlex/reactive/features/presence"))
 registerReactiveFeatureLoader("effects", () => import("phlex/reactive/features/effects"))
 registerReactiveFeatureLoader("hints", () => import("phlex/reactive/features/hints"))
 registerReactiveFeatureLoader("devtools", () => import("phlex/reactive/features/devtools"))
@@ -146,7 +147,9 @@ onReactiveStreamWithoutEffects((event, loadedEffects) => {
 
 // The reactive roots a stream is about to put on the page: the roots in its
 // template (the template's own root element included), and the content
-// itself when it brings an editable.
+// itself — read as part of the root already on the page it renders into,
+// which re-reads its markers once the render has run (issue #356; an editable
+// it brings, #351). Held for the module, the new content lands wired.
 function incomingRoots(streamEl) {
   const content = streamEl?.querySelector?.("template")?.content
   if (!content) return []
@@ -154,10 +157,7 @@ function incomingRoots(streamEl) {
   for (const child of content.children ?? []) {
     if (child.matches?.('[data-controller~="reactive"]') && !roots.includes(child)) roots.unshift(child)
   }
-  // An editable appended into a root already on the page (issue #351): that
-  // root loads the bindings module when the editable is first focused, so
-  // start the import now — the module is then here before anything is typed.
-  if (content.querySelector?.("[data-reactive-editable]")) roots.push(content)
+  roots.push(content)
   return roots
 }