phlex-reactive 0.15.2 → 0.15.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dd7744e88ad5a6633b0bce1b77232cb143909f65daf878150eb1750389ccae2
-  data.tar.gz: 853207f674648c4aa58d48fdfcd39db5b58eb887f557958b4b9791049dcd5d9a
+  metadata.gz: bd638899f7bcd09bffdd26692f13bf1b8e22ec2e3ceadf614e337edd03459ed5
+  data.tar.gz: fefc53fbdf9f3e36405a2665c23fff709230405e944107e0d0ed946ee31de392
 SHA512:
-  metadata.gz: 36328a18b6289fba46a228b5864021645e9487dbf4164937c25c6eaef468bb22ee347e9774b30c74028e3ce9c6fd144aa57ba699a7b6f113279ee8b91b1bee3b
-  data.tar.gz: 9ce053b691b4c5ae42d0c149d01183ff7646a3985467bbeeb67c18f7eb2512acee6cf129d0bb726e2cff6825f0708bfbfc0874b1212f621731c3f4efe7dce2d9
+  metadata.gz: d9bbd2c39abf405afd5e68ce8ad231a62c75a9af578db96315bb716184107846a5d2fe031a58f968a2bf62fa25b9aeb9f82937276f8170324a9e43c1cc1f853d
+  data.tar.gz: 4981aaaa21ceba8bef392dae7d7beaf433ed8a0ac81de38931198a8ef1e0a3e75ed243592aefbf27965f81b593d2a3398404a2486759a3da073466a2928a04f9

data/CHANGELOG.md

@@ -8,12 +8,200 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **A server deadline counted down on the client — `reactive_countdown(until:, format: :ms, waiting:, done:)` (#400).**
+  `span(**reactive_countdown(until: deadline.iso8601, waiting: "#wait", done: "#done")) { "2:00" }`
+  puts the deadline on the element; the client paints the time left from
+  `Date.now` at connect and on each second boundary (unpadded minutes, a colon,
+  padded seconds; `textContent` only), and re-reads it when a hidden tab is
+  shown, so a woken tab jumps to the real value. At zero, or with `until:`
+  already past on connect (no timer starts), the text is `0:00`,
+  `data-reactive-countdown-state` is `done`, `waiting:` hides, `done:` shows and
+  the element dispatches `reactive:countdown-done` once per deadline: a morph
+  or replace that keeps `until:` repaints the done state without a second
+  event, one that changes it counts down again ("once" is remembered per
+  root, countdown id or position, and deadline for the life of the document). Timers are cleared on
+  disconnect. No request and no frame reload: the event is the hook. The server
+  renders the initial text and visibility. `format:` other than `:ms`, an
+  `until:` that is not an ISO8601 date-time with a zone (or a `Time`), and a
+  `waiting:`/`done:` that is not a non-blank selector (or is `@root`) raise at
+  render. Client: a new `countdown` feature module (966 B gzipped); +653 B in
+  the default bundle, +31 B in the split core. Docs: "Counting down to a server
+  deadline" on the client-ops example.
+
+- **`js.blur(to, global: false)` (#399).** Blurs `document.activeElement` when
+  it is the target or sits inside it, so
+  `on_client("keydown.esc", js.blur("#menu"))` ends a menu's `:focus-within`;
+  focus elsewhere is left alone, and a missing target is skipped (warned
+  under `verbose_errors`/debug). Actor-only like `focus`: `broadcast_to(js:)`
+  refuses it. Client: +41 B gzipped in the default bundle, +39 B in the
+  split core.
+
+- **`on_client` takes `debounce:` and `throttle:` like `on` (#393).**
+  `input(**on_client(:input, js.submit("#search"), debounce: 300))` runs the
+  ops once, 300 ms after the last `input` of a burst; `throttle: 250` runs on
+  the first event and drops the rest until 250 ms have passed. Non-negative
+  Integer milliseconds; both at once raise at render with `on`'s message, and
+  a negative or non-Integer value raises too. The wait rides on the binding
+  record, so mixed bindings keep their own, and the client runs it on the
+  timers `on` uses (a blur flushes a pending debounce, except on a
+  window-bound binding; disconnect clears it). `once:` still means one run,
+  after the wait. `on` is unchanged. Client: +150 B gzipped in the default
+  bundle, +127 B in the split core. Docs: "Waiting: debounce: and throttle:"
+  on the client-ops example.
+
+- **`reactive_image_fallback(wrap:)` hides the box around a broken image
+  (#392).** `img(**reactive_image_fallback(hide: false, wrap: "#badge"))` hides
+  `#badge` (a selector inside the root, like `show_alt:`) on `error` and marks
+  the hide `data-reactive-wrap-hidden`, the mark `preview_file`'s `wrap:` uses.
+  Recovery (any later `src` that loads, `copy_media`, `reactive_media`,
+  `preview_file`) shows it again only when it carries that mark, so a wrapper
+  the author hid stays hidden; a morph that keeps the broken `src` hides it
+  again. The wrapper may hold the `img`: its text is never written. `hide:
+  true` without `wrap:` still hides only the `img`. A `wrap:` that matches
+  nothing warns and is skipped (the `img` fallback still runs); a `wrap:` that
+  is not a non-blank String, or is `@root`, raises at render. Client: +45 B
+  gzipped in the default bundle, +51 B in the split core.
+
+- **`js.preview_file` hides its frame and refuses a file by size or type —
+  `wrap:`, `max_bytes:`, `accept:` (#391).** `wrap: "#photo-frame"` shows that
+  element when an image is painted and hides it when the preview clears. The
+  hide is marked `data-reactive-wrap-hidden`; only a wrapper carrying the mark
+  is shown again, so a wrapper the author hid stays hidden (render the mark
+  with `hidden` to start hidden). The wrapper's text is never written. A
+  `wrap:` that is not on the page warns and is skipped. `max_bytes:` (a
+  positive Integer) refuses a larger file before `URL.createObjectURL` runs;
+  `accept: true` reads the input's `accept` attribute (extensions, MIME types,
+  `type/*`), a String is the list for this op, and omitted keeps the `image/*`
+  rule. Only an image is painted: a listed non-image (a PDF) clears the preview
+  and hides `wrap:` without a rejection. A refused file clears the `img` and the name, hides `wrap:`, and
+  dispatches `reactive:file-rejected` (bubbling) on the input with
+  `detail.reason` `"type"` or `"size"` and `detail.file`. A non-image file
+  under today's rule now dispatches it too. The op never clears `input.files`
+  and never calls `setCustomValidity`. The op still carries no URL, and
+  `broadcast_to(js:)` still refuses it. Client: +351 B gzipped in the default
+  bundle, +336 B in the split core.
+
+- **Clear, focus and scroll when `reactive_show` changes visibility — `clear:`, `focus:`, `scroll:` (#394).**
+  `div(**reactive_show(if: { kind: "other" }, clear: :notes, focus: "#notes", scroll: true))`.
+  When the section goes from visible to hidden, each `clear:` field (one
+  owned, scope-aware name or an Array) gets `js.set_value`'s write — `.value`
+  becomes `""` and one bubbling `input` is dispatched per field that changed;
+  a checkbox or radio is unchecked. (A file input is rejected at render.) When it goes from
+  hidden to visible, the first element inside the root matching `focus:` is
+  focused and `scroll: true` calls `scrollIntoView` on the section. None of it
+  runs on first paint, so a value the server rendered into a hidden section
+  stays. The previous visibility is kept on the root's controller (absent on
+  connect, kept by a morph — so a `morph: true` reply that flips the predicate
+  runs it, while a plain replace reconnects the root and counts as first
+  paint). The work runs after the show pass, so the `input`
+  a clear dispatches re-syncs from fresh values. A `clear:` name the render
+  never produced, or one that names a file input, raises at render; so does a
+  `focus:` that is not a non-empty String or a `scroll:` that is not a
+  boolean. Without these keywords, a binding behaves as before (`hidden`, and
+  `disable:` if given). The
+  feature handle gains `setValue` (the runtime's `set_value` write). Client:
+  +282 B gzipped in the default bundle, +10 B in the split core.
+
+- **A digit format, and a hint that waits for blur — `{ digits: 10, starts_with: "9" }`, `after: :blur` (#396).**
+  `digits:` (a non-negative Integer or an Integer Range, counted in
+  codepoints) holds while every character is ASCII `0-9` and the count fits;
+  `starts_with:` adds a prefix that must itself be a String of digits, so the
+  term cannot become a pattern. One wire term carries `digits_eq` (or
+  `digits_gte`/`digits_lte`/`digits_lt`) plus `prefix`, and `"negate" => true`
+  under `unless:`. `reactive_show(…, after: :blur)` keeps the section hidden
+  until the condition's one field has fired `blur` once since connect
+  (`after: :code` names it when the condition has several); after that, every
+  `input` updates it at once. The touched flag lives on the root's controller:
+  a morph keeps it, a full navigation drops it. First paint is hidden unless an
+  explicit `hidden:` says otherwise. A
+  `starts_with:` that is not a String of digits, a malformed `digits:`, an
+  `after:` that is not a field of the condition, or one the render never
+  produced, raises at render. Client: +232 B gzipped in the default bundle.
+  Docs: "A digit format, and only after blur" on the client-ops example.
+
+- **Compare two fields in a show condition — `{ same: :email, case: :fold }` (#395).**
+  `button(**reactive_enable(if: { confirm_email: { same: :email, case: :fold } }))`
+  enables the button only while the two values are equal (an empty pair is
+  equal); `reactive_show(unless: { … })` shows a hint while they differ. Both
+  sides are read as strings; `case: :fold` lowercases ASCII `A-Z` only, with
+  the same explicit replace in Ruby and the client, so a non-ASCII case
+  difference stays unequal. The wire term is
+  `{ "field", "same", "fold"? }`, plus `"negate" => true` under `unless:`. The
+  `same:` name is scope-aware and must name a field the render produces: the
+  check runs when the outermost Phlex render finishes and raises
+  `ArgumentError` for an unknown name. A `case:` other than `:fold` raises at
+  render. First paint needs both fields in `reactive_values`. Works in
+  `reactive_show`, `reactive_enable`, the `"#id" => { if: … }` form of
+  `reactive_show_targets`, `reactive_on_complete` and a conditional
+  `confirm:` (only the first two check the name at render). Client: +103 B gzipped
+  in the default bundle. Docs: "Compare two fields" on the client-ops example.
+
+- **Nested checkbox groups — `reactive_select_all(group, under: "a.b")` (#398).**
+  A header with `under: "library"` owns the boxes of the name whose
+  `data-reactive-group` is `library` or below it (`library.books`; whole
+  segments, so never `libraryx`). It ticks or unticks them, dispatching
+  `input` + `change` on each one it flips, and is checked / indeterminate /
+  unchecked from them, so a parent follows its nested headers. Every leaf still
+  posts under the one name; headers have no `name` and never post;
+  `reactive_count` and `reactive_enable` keep counting the leaves. A nested
+  reactive root's boxes stay that root's own (#15). `reactive_select_all`
+  without `under:` renders the same attrs as before and still flips every box
+  of the name. A blank `under:`, or one with an empty or space-padded segment, raises at
+  render. Client: +76 B gzipped in the default bundle (+66 B in
+  `features/bindings`, the split core unchanged). Docs: "Bulk selection" on
+  the client-ops example; demo at `/nested_selection` in the dummy app.
+
+- **`reactive_media(when:)` tests the whole field (#390).** `when:` is a
+  Regexp the client tests against the whole field value before the pool
+  lookup, while the pool key stays the `take:` prefix: with `take: 3,
+  when: /\A\d{3,24}\z/`, `007bad` is pending (no pool lookup, never
+  `blank_label`: the default clears the preview and label, `pending: :keep`
+  leaves them as they are; either way `data-reactive-media-state="pending"`) and
+  `007123` hits `"007"`. It compiles with the same rules as `match:` (a
+  refused regexp raises at render, naming `when:`). `match:` still tests the
+  key only; omit `when:` and nothing changes. Client: +25 B gzipped default
+  bundle, +22 B bindings module, core unchanged.
+
+- **A tab-only draft — `reactive_persist(storage: :session)` (#397).** The
+  draft lives in `sessionStorage` instead of `localStorage`: a reload in the
+  same tab restores it, another tab never sees it (a tab opened from it with
+  an opener, or duplicated, starts with the browser's one-time copy),
+  closing the tab drops it.
+  Same key, same skipped controls, same `restore:`, and every read, write,
+  `ttl` expiry, successful-submit clear and `persist_state`/`persist_clear`
+  op goes to that store only — a `:local` draft is never restored by
+  `:session`, and a missing `sessionStorage` is "no draft", never a fallback
+  to `localStorage`. `storage: :local` (the default) keeps today's behavior
+  and today's wire byte-for-byte; `"local"`/`"session"` strings are accepted,
+  anything else raises at render. Client: +27 B gzipped in the default
+  bundle, +20 B in the persist module; the split core unchanged.
+
+- **An image fallback that recovers — `reactive_image_fallback(hide: true, show_alt: nil)` (#383).**
+  `img(**reactive_image_fallback)` marks an `<img>` whose `src` fails with
+  `data-reactive-image-state="error"` and hides it; `show_alt: "#bank-name"`
+  also writes its `alt` (as `textContent`) into that node inside the root and
+  shows it; `hide: false` only sets the state, for CSS. `load` sets
+  `"loaded"`. A later `src` tries again: `copy_media`, `reactive_media` and
+  `preview_file` clear the error as they write the `src`, any `src` that loads
+  clears it, and a morph that changes the `src` lets the browser retry (one
+  that keeps it keeps the state). Removing the `src` is not an error. Only the
+  `hidden` the fallback added is ever removed. Composes with `reactive_media`
+  (`reactive_media(…, **reactive_image_fallback)`). The client listens once on
+  the document in the capture phase (`error`/`load` do not bubble) and reads
+  images that failed before it registered; nothing runs per root at connect.
+  No URL in any argument; `set_attr` still refuses `src`/`srcset`. `hide:`
+  that is not a boolean, or a `show_alt:` that is not a non-blank String (or
+  is `@root`), raises at render; a String that is not a valid CSS selector is
+  ignored by the client. Client: +597 B gzipped in the default bundle,
+  +550 B in the split core. Docs: "An image that falls back, and recovers" on
+  the client-ops example.
+
 - **Media previews — `js.copy_media` and `reactive_media` (#373).**
   `js.copy_media("#logo", from: "#logo-007")` copies `src`, `srcset` and `alt`
   from an `<img>` the server rendered onto a preview `<img>`; the URL is read
   from the live source element and is never an op argument, so `set_attr`
-  still refuses `src` (#96). A missing source, a non-`<img>` source or one
-  without `src` clears the target; a target that is not an `<img>` (an
+  still refuses `src` (#96). A missing source or a non-`<img>` source clears
+  the target (an `<img>` source without `src` keeps its `alt`, #381); a target that is not an `<img>` (an
   `iframe`, `script`, `object`, `embed`, `frame`) is warned about and skipped;
   the same URL twice is not written again. `img(**reactive_media(from: :code,
   take: 3, pool: { "007" => "#logo-007" }, label: "#caption", blank_label:
@@ -215,6 +403,48 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **`reactive_media` waits for `take` characters before calling a key a miss
+  (#380).** A value shorter than `take:` sliced to a short key, missed the
+  pool and wrote `blank_label` while the user was still typing. It is now
+  *pending*: `blank_label` only names a full-length key that misses. New
+  options: `match:` (a Regexp, anchored to the whole key; a key it rejects is
+  pending too) and `pending: :clear` (default: clear the preview, empty the
+  label) or `:keep` (leave both alone). The preview carries
+  `data-reactive-media-state="pending|hit|miss"`, so a row can hide itself
+  with CSS. `match:` reaches the browser as a JS pattern: its `\A`/`\z`
+  anchors are dropped (a trailing `\Z` becomes `\n?`), and what JS reads
+  differently raises at render (options, escapes such as `\h`/`\p{…}`/`\s`/
+  `\u{…}`, POSIX and nested classes, `&&`, `(?i)`/`(?>…)`, characters above
+  U+FFFF). **Behaviour change:** with `take:`, a short value now leaves the
+  label empty instead of writing `blank_label`. Without `take:` or `match:`
+  nothing changes. Client: +160 B gzipped in the default bundle (+152 B on
+  top of #381/#382), +152 B in the bindings module, the split core unchanged. Docs: "Media
+  previews" on the client-ops example.
+
+- **A pool `<img>` with an `alt` and no `src` keeps its name (#381).**
+  `js.copy_media` and `reactive_media` treated a source `<img>` without `src`
+  as a clear: the preview's `alt` was emptied and `label:` got `blank_label`,
+  so a known entry with no logo file lost its name. Such a source is now a hit
+  without an image: the target's `src` and `srcset` are removed, its `alt` is
+  set, and `label:` gets that `alt`. Only a pool miss, a selector that matches
+  nothing, or a source that is not an `<img>` clears. Client: +1 B gzipped in
+  the default bundle, −2 B in the split core; the bindings module is
+  unchanged.
+
+- **`js.preview_file` follows an app's upload validation (#382).** A preview
+  ran once, on `change`, so a file the app then rejected (cleared with
+  `input.value = ""`, no new `change`) stayed on screen. Two pieces fix it.
+  `js.preview_file(…, valid: true)` treats an input whose `validity.valid` is
+  false (`setCustomValidity`, `required`) as empty: it never gets a preview,
+  and one it had is cleared and its URL revoked. And `reactive:file-changed`
+  is the documented event for "the app changed this input's files without a
+  `change` event": bind the op to it as well,
+  `mix(on_client(:change, op), on_client("reactive:file-changed", op))`, and
+  the app dispatches it after it clears or invalidates the field. That works
+  whichever `change` listener runs first. Without `valid:` the op behaves as
+  before. Client: +22 B gzipped in the default bundle, +34 B in the split
+  core (on top of #381). Docs: "Preview a chosen image" on the client-ops example.
+
 - **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,
@@ -251,6 +481,43 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   first paint already were. A target with any value term keeps the skip when
   none of its fields is owned.
 
+### Performance
+
+- **Guarded and persisted forms connect in linear time.** Each `warn_unsaved`
+  root added its own `beforeunload` / `turbo:before-visit` pair on `window`,
+  and each persisted root its own `turbo:submit-end` listener on `document`.
+  A browser scans a target's listeners on every add and remove, so connecting
+  and disconnecting N of them was quadratic. One shared listener per window or
+  document now serves them all, added with the first root and removed with
+  the last; behaviour is unchanged (live dirty count, one prompt per visit,
+  #298). Headless Chromium, insert + connect: 4,000 guarded roots ~306 ->
+  ~227 ms, 4,000 persisted roots ~280 -> ~230 ms. +194 B gzipped in the
+  default bundle (110 B for the guard, 84 B for persist).
+- **A record-backed token no longer builds a GlobalID URI.** For a record
+  whose `to_gid` is GlobalID's own and whose id is an Integer, the gid is
+  built directly as `gid://<app>/<Class>/<id>` (byte-identical, pinned by
+  `identity_gid_spec.rb`); anything else still calls `to_gid`. The token goes
+  from ~11.4 µs and 54 objects to ~5.2 µs and 20 (in-place A/B).
+- **`rake bench:browser`.** Connect, disconnect and a heap soak for the
+  shipped client in headless Chromium. The happy-dom connect bench is
+  engine-relative and missed the quadratic above; this is the one to trust.
+- **The doctor's authorization check is linear, not quadratic.** It rebuilt
+  the Inspector's whole component list (a Prism scan per action) once for
+  every component. It now reads it once: `doctor.checks` over the dummy app's
+  90 components drops from 1,337 ms to 55 ms, and an app with a few hundred
+  components no longer waits tens of seconds on `rake phlex_reactive:doctor`.
+- **`on()` checks for removed keywords without building arrays.** Every
+  trigger ran `params.keys & REMOVED_ON_KWARGS.keys`. It now returns at once
+  when there are no extra keywords. `on(:increment)` allocates 5 objects
+  instead of 8; a 7-trigger component's `render_component` 118 instead of 136
+  (~5% faster in an in-place A/B, a method-level win that shows on broadcast
+  fan-out, not request latency).
+- **The request bench measures production, not a file watcher.** The dummy
+  app's test env left code reloading on, so every request globbed `app/`:
+  `rake bench:request` read ~1.7-2.0 ms and 1,272 objects per state-backed
+  action, against ~0.30-0.35 ms and 824 objects with it off (same machine,
+  interleaved). Test-env only; the gem is unchanged.
+
 ## [0.14.1] - 2026-10-07
 
 ### Added

data/README.md

@@ -302,6 +302,7 @@ imports one the first time a root on the page needs it:
 | `phlex/reactive/features/bindings` (`reactive_show`, show targets, `reactive_on_complete`, `reactive_filter`, `reactive_tags`, nested rows, the conditional `confirm:`) | 5.4 KB | inside the one file | fetched when a root declares one of them, or holds a trigger with a conditional confirm |
 | `phlex/reactive/features/compute` (`reactive_compute`, `reactive_text`) | 2.1 KB | inside the one file | fetched when a root carries a compute binding |
 | `phlex/reactive/features/sortable` (`reactive_sortable` drag and drop) | 3.1 KB | inside the one file | fetched when a root is or holds a sortable or source list |
+| `phlex/reactive/features/countdown` (`reactive_countdown`) | 1.0 KB | inside the one file | fetched when a root is or holds a countdown |
 | `phlex/reactive/features/hints` (`optimistic:`, `busy:`) | 1.0 KB | inside the one file | fetched when a root holds a trigger that declares a hint |
 | `phlex/reactive/features/devtools` (the latency simulator, the zero-target warnings, the debug trace) | 1.6 KB | inside the one file | fetched with the core on a page that carries `<meta name="phlex-reactive-env" content="development">` or while a delay is stored for the tab; at connect for a root in debug mode; otherwise the first time a verbose root has something to warn about. In production with none of these, never |
 | `phlex/reactive/early` | 1.2 KB | on every page, if you import it | the same |
@@ -683,18 +684,20 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `on(:save, loading: { disable: true, class: "opacity-50", text: "…" })` | Full loading form: `disable:`, a loading `class:` (on the trigger or a `to:` target), a `text:` swap. Reverts on settle. |
 | `busy_on(:save)` | Mark any element so it carries `data-reactive-busy` **only while `save` is in flight** — a spinner styled with pure CSS, zero Ruby. See [Loading states](#declarative-loading-states-loading--disable_with). |
 | `on(:action, once: true)` | Fire at most once, then unbind (Stimulus's native `:once`). |
-| `on_client(:click, js.toggle("#menu"))` | **Client-only** trigger: applies declared DOM ops with ZERO round trip — no token, no POST, ever. Takes the same `window:`/`once:`/`outside:` modifiers, plus `detail:` (run only when `event.detail` carries the listed values). See [Client-only ops](#client-only-ops-on_client--js--zero-round-trips). |
-| `js` | The immutable op builder behind `on_client`: `show`/`hide`/`toggle` (the `hidden` attribute, with an optional `transition:` and `expanded:`), `add_class`/`remove_class`/`toggle_class`, `set_attr`/`remove_attr`/`toggle_attr` (allowlisted names; `toggle_attr` also flips between two values), `focus`/`focus_first`, `show_modal`/`close_dialog` (a real modal `<dialog>`), `copy_media` (copy `src`/`srcset`/`alt` from a server-rendered `<img>`, no URL argument), `text` (set `textContent` — XSS-safe), `set_value` (set a field's live `.value` and dispatch `input`), `dispatch`, `submit` (requestSubmit the target's own form, optionally through a `submitter:`), `paste_into` (read the clipboard into a field, gesture-gated), `preview_file` (paint a chosen image file onto an `img` through an object URL the client makes and revokes), `check_group` (tick or untick a checkbox group, then re-sync its bindings), and `persist_state`/`persist_clear` (the `reactive_persist` draft) — chainable. `keep: true` on the visibility, class and attr ops makes their result survive a morph. |
+| `on_client(:click, js.toggle("#menu"))` | **Client-only** trigger: applies declared DOM ops with ZERO round trip — no token, no POST, ever. Takes the same `window:`/`once:`/`outside:` modifiers and `debounce:`/`throttle:` waits (ms) as `on`, plus `detail:` (run only when `event.detail` carries the listed values). See [Client-only ops](#client-only-ops-on_client--js--zero-round-trips). |
+| `js` | The immutable op builder behind `on_client`: `show`/`hide`/`toggle` (the `hidden` attribute, with an optional `transition:` and `expanded:`), `add_class`/`remove_class`/`toggle_class`, `set_attr`/`remove_attr`/`toggle_attr` (allowlisted names; `toggle_attr` also flips between two values), `focus`/`focus_first`/`blur`, `show_modal`/`close_dialog` (a real modal `<dialog>`), `copy_media` (copy `src`/`srcset`/`alt` from a server-rendered `<img>`, no URL argument), `text` (set `textContent` — XSS-safe), `set_value` (set a field's live `.value` and dispatch `input`), `dispatch`, `submit` (requestSubmit the target's own form, optionally through a `submitter:`), `paste_into` (read the clipboard into a field, gesture-gated), `preview_file` (paint a chosen image file onto an `img` through an object URL the client makes and revokes), `check_group` (tick or untick a checkbox group, then re-sync its bindings), and `persist_state`/`persist_clear` (the `reactive_persist` draft) — chainable. `keep: true` on the visibility, class and attr ops makes their result survive a morph. |
 | `reactive_field(:param, **attrs)` | The attribute hash that binds a control to an action param (no magic `name:`) — spread onto any control: `input(**reactive_field(:value, value: @record.name))`, `select(**reactive_field(:status)) { … }`. |
 | `reactive_editable(:name, multiline: false, placeholder: nil, on_enter: nil, on_escape: :revert, spellcheck: true)` | A plain-text **editable element** as a field (issue #351): `h3(**reactive_editable(:title)) { @card.title }`. Its text travels under the scope-aware `name`: with `multiline: true` its line breaks are sent as `\n`; a single-line field (the default) folds them to spaces; a morph keeps the focused element's text and caret (attributes still morph); paste is plain text; Enter runs `on_enter:` (a single-line field swallows it); Escape reverts. `reactive_dirty` and `reactive_persist` treat it like an input. See the [Editable text](https://phlex-reactive.zoolutions.llc/docs/editable-text) page. |
 | `reactive_text(:name, initial)` | Mirror a compute output (or a declared input) into a **text node** — a live preview heading, a character counter, `"Hello, {name}"` — via `textContent` (XSS-safe). The text sibling of `reactive_field`; carries no `name`, so it's never POSTed. See [Client-side computes](#client-side-computes-reactive_compute--reactive_text). |
-| `reactive_show(if:/if_any:/unless:)` | **Value-conditional visibility** (the `x-show`/`data-show` case): spread onto the element to show/hide — it toggles `hidden` from the fields' **current values**, client-only, zero round trip. One conditions language: a **Hash is an AND**, an **Array is membership**, a **Range is a threshold**, `if_any:` is OR-of-AND, `unless:` negates. `reactive_values` computes first paint; `disable:` disables a hidden section's controls. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
-| `reactive_media(from:, pool:, take:, label:, blank_label:)` | A preview `<img>` that **follows a field** (#373): the field's value (its first `take:` characters, or all of it) is a key into `pool`, whose values are **selectors** for `<img>` elements the server rendered — never URLs. A hit copies that image's `src`/`srcset`/`alt` like `js.copy_media`; a miss clears the preview. `label:` gets the `alt` (or `blank_label`) as `textContent`. See [Media previews](https://phlex-reactive.zoolutions.llc/docs/example-client-ops). |
+| `reactive_show(if:/if_any:/unless:)` | **Value-conditional visibility** (the `x-show`/`data-show` case): spread onto the element to show/hide — it toggles `hidden` from the fields' **current values**, client-only, zero round trip. One conditions language: a **Hash is an AND**, an **Array is membership**, a **Range is a threshold**, `if_any:` is OR-of-AND, `unless:` negates. `reactive_values` computes first paint; `disable:` disables a hidden section's controls; `{ same: :email }` compares two fields, `{ digits: 10 }` checks a digit format, `after: :blur` waits for the field's first blur, and `clear:`/`focus:`/`scroll:` run when the section changes visibility. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
+| `reactive_media(from:, pool:, take:, match:, when:, pending:, label:, blank_label:)` | A preview `<img>` that **follows a field** (#373): the field's value (its first `take:` characters, or all of it) is a key into `pool`, whose values are **selectors** for `<img>` elements the server rendered — never URLs. A hit copies that image's `src`/`srcset`/`alt` like `js.copy_media` (a pool `<img>` with an `alt` and no `src` is a hit without an image, #381); a miss clears the preview. `label:` gets the `alt` (or `blank_label`) as `textContent`. Below `take:` characters, or while `match:` (a JavaScript-compatible Regexp over the whole key) rejects the key, the binding is **pending** (#380) — never `blank_label` (Regexp options or Ruby-only syntax raise at render); `when:` (same rules) tests the **whole field** before the pool lookup while the key stays the prefix, so `take: 3, when: /\A\d{3,24}\z/` keeps `007bad` pending (#390); `pending: :clear` (default) clears the preview and label, `:keep` leaves them. The preview's `data-reactive-media-state` reads `pending`/`hit`/`miss`, so CSS can hide its row. See [Media previews](https://phlex-reactive.zoolutions.llc/docs/example-client-ops). |
+| `reactive_image_fallback(hide: true, show_alt: nil, wrap: nil)` | An `<img>` that **falls back and recovers** (#383): on `error` it gets `data-reactive-image-state="error"`; `hide:` (default `true`) also hides it, and `show_alt:`, independently, writes its `alt` into that node and shows it; `wrap:` (#392) hides the box around it (marked `data-reactive-wrap-hidden`, shown again only when it carries that mark, its text never written); `load` sets `"loaded"`. A later `src` (from `copy_media`, `reactive_media`, `preview_file`, a morph, or any `src` that loads) shows it again; removing the `src` is not an error. Composes with `reactive_media(…, **reactive_image_fallback)`. See [Client-only ops](https://phlex-reactive.zoolutions.llc/docs/example-client-ops). |
+| `reactive_countdown(until:, format: :ms, waiting:, done:)` | A server **deadline counted down** on the client (#400): `until:` is an ISO8601 date-time with a zone (or a `Time`); the text is the time left from `Date.now` (`1:30`), as `textContent`, once a second and again when a hidden tab is shown. At zero (or already past on connect) it reads `0:00`, `data-reactive-countdown-state="done"`, `waiting:` hides, `done:` shows and `reactive:countdown-done` fires **once per deadline** (a morph that keeps `until:` does not fire again; a new `until:` restarts). The server renders the first text and visibility. No request, no frame reload. See [Client-only ops](https://phlex-reactive.zoolutions.llc/docs/example-client-ops). |
 | `reactive_enable(if:/if_any:/unless:)` | The sibling of `reactive_show` that flips the element's **own `disabled`** (a button, a fieldset) instead of `hidden` — same conditions, same `reactive_values` first paint. `button(**reactive_enable(if: { "ids[]" => { checked: 1.. } }))`. See [Bulk selection](#bulk-selection-reactive_select_all-reactive_count-reactive_enable). |
-| `reactive_select_all("ids[]")` / `reactive_count("ids[]")` | A checkbox **group**'s header box (ticks/unticks every owned box; shows checked / indeterminate / unchecked) and its ticked count as text — re-synced on every change and when rows are appended or removed. See [Bulk selection](#bulk-selection-reactive_select_all-reactive_count-reactive_enable). |
+| `reactive_select_all("ids[]")` / `reactive_count("ids[]")` | A checkbox **group**'s header box (ticks/unticks every owned box; shows checked / indeterminate / unchecked) and its ticked count as text — re-synced on every change and when rows are appended or removed. `under: "a.b"` makes a nested header over the leaves whose `data-reactive-group` is in that path. See [Bulk selection](#bulk-selection-reactive_select_all-reactive_count-reactive_enable). |
 | `reactive_group_targets("ids[]", count: "#c", enable: { "#b" => 1.. })` | Spread on the root that **owns** a checkbox group: drives a count and an enable on outside, id-allowlisted elements (a bulk bar the page renders). `reactive_group_target_attrs` gives that outside markup its first paint. See [A bulk bar outside the list's root](#a-bulk-bar-outside-the-lists-root-reactive_group_targets). |
 | `reactive_show_targets(:field, "#id" => value)` | **Cross-root visibility**: the component that owns the field declares which **outside**, id-allowlisted elements it governs (a nav tab, a panel in another pane) — the visibility parallel of `mirror:`. Spread on the **root** via `mix(reactive_root, …)`, **once per root** — several fields go in one call via the hash form. The value uses the same `where`-style vocabulary (`"advanced"`, `%w[a b]`, `10..`); a `"#id"` **key** takes a full conditions Hash for a **multi-field** predicate (`"#warn" => { if: { type: "trade", price: ..0 } }`). Id selectors only (raise at render + client warn-skip); toggles `hidden` only. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
-| `reactive_persist(key:, ttl: 7.days)` | **Client-only drafts**: spread on the **root** (once) and the generic controller keeps a `localStorage` draft of every **owned** control — debounced write on `input`, immediate on `change`, flushed on disconnect, restored into **blank** controls on the next connect (`restore: :always` lets the draft win), cleared by a successful Turbo submit / `ttl` / `js.persist_clear`. Never hidden/file/password; `reactive_persist_skip` opts a control out; `fields:` narrows. See [Client-only drafts](#client-only-drafts-reactive_persist). |
+| `reactive_persist(key:, ttl: 7.days)` | **Client-only drafts**: spread on the **root** (once) and the generic controller keeps a `localStorage` draft of every **owned** control — debounced write on `input`, immediate on `change`, flushed on disconnect, restored into **blank** controls on the next connect (`restore: :always` lets the draft win), cleared by a successful Turbo submit / `ttl` / `js.persist_clear`. Never hidden/file/password; `reactive_persist_skip` opts a control out; `fields:` narrows; `storage: :session` keeps the draft in this tab's `sessionStorage` instead. See [Client-only drafts](#client-only-drafts-reactive_persist). |
 | `js.persist_state(step: 2)` / `js.persist_clear` | The draft ops (actor-only): merge a flat state bag into the draft (restored as `data-reactive-persist-state` + the `reactive:persist-restored` event) / forget the draft. |
 | `reactive_filter(:field, option: nil, group: nil, empty: nil)` | **Client-side option filtering** for a preloaded combobox: spread onto the root and name the **field** that drives it — `reactive_filter(:q)` compiles `:q` to `[name="q"]` (scope-aware) and typing shows/hides the options by their `data-reactive-filter-text` haystack, **zero round trips**. `option:` defaults to `[role=option]`; optional `group:` collapses an all-hidden group header; `empty:` reveals a no-matches node. `input:` is the escape hatch — a raw CSS selector for a **name-less** driving input (`input: "#tags_query"`), the form-builder case. See [Client-side option filtering](#client-side-option-filtering-reactive_filter). |
 | `reactive_listnav("[role=option]")` | The **standalone** combobox keyboard wiring (Arrow/Enter/Escape) for an input that fires **no action** — the preload-and-filter case. Same behavior as `on(…, listnav:)`, minus the POST. `reactive_listnav(focus: true)` is the **roving-focus** variant for a `role="menu"` container: Arrow Down/Up move real focus among `[role=menuitem]` (wrapping), Home/End jump to the edges; Enter/Space stay native and Escape is yours to bind. |
@@ -1267,13 +1270,18 @@ button(**on_client(:click, js
   `from` `<img>` onto the `to` `<img>` — how a preview shows an image the server
   already rendered while `src` stays refused. Both are elements (`:root` or a
   selector); the URL is read from the live source element, never passed. A
-  missing source, a non-`<img>` source or one without `src` clears the target;
-  a non-`<img>` target is warned about and skipped; an attribute that already
+  missing source or a non-`<img>` source clears the target; an `<img>` source
+  without `src` removes the target's `src`/`srcset` and copies its `alt` (#381),
+  so an entry with no image keeps its name; a non-`<img>` target is warned about and skipped; an attribute that already
   holds the copied value is not rewritten, so the same image twice does not
   reload. Allowed in a broadcast (it only reads the subscriber's own page).
 - **`focus(to)`** focuses the first match; **`focus_first(to)`** focuses the first
   focusable descendant of the match (e.g. the first menuitem inside an opened
   menu).
+- **`blur(to)`** (#399) blurs the focused element when it is the match or sits
+  inside it, so Escape ends a menu's `:focus-within`
+  (`on_client("keydown.esc", js.blur("#menu"))`); focus elsewhere on the page is
+  left alone. Actor-only like focus: refused in broadcasts.
 - **`show_modal(to)`** / **`close_dialog(to)`** (#365) call
   `HTMLDialogElement#showModal()` / `#close()`: the top layer, a focus trap,
   `::backdrop`, Escape to close and focus back on the opener — all the
@@ -1339,13 +1347,14 @@ button(**on_client(:click, js
   (a broadcast that reads every subscriber's clipboard would be hostile). The
   op is async fire-and-forget — chained siblings apply immediately, never
   waiting for the read.
-- **`preview_file(to, into:, name: nil, global: false)`** (#375; `global: true`
+- **`preview_file(to, into:, name: nil, global: false, valid: false, wrap: nil, max_bytes: nil, accept: nil)`** (#375; `global: true`
   resolves `to`, `into:` and `name:` document-wide, for an `img` outside the
   root) paints the file a file input
   holds onto an `img` **before any upload**:
   `input(type: "file", id: "photo-file", accept: "image/*", **on_client(:change,
   js.preview_file("#photo-file", into: "#photo", name: "#photo-name")))`. On
-  `change` the client takes the input's first `image/*` file, makes an object
+  `change` the client takes the input's first `image/*` file (the default list;
+  an explicit `accept:` below replaces it), makes an object
   URL from it (`URL.createObjectURL`), sets it as the `img`'s `src`, and puts
   `file.name` in the `name:` node's `textContent`. An empty selection or a
   non-image file removes the `src` and clears the name. The op carries **no
@@ -1356,6 +1365,25 @@ button(**on_client(:click, js
   and revokes it on a re-pick, a clear, and when the `img` leaves the page or a
   morph strips its `src` — a server re-render resets the preview like any other
   op. **Actor-only**: refused in `broadcast_to(js:)`.
+  **Upload validation (#382):** `valid: true` treats an input whose
+  `validity.valid` is false (`setCustomValidity`, `required`) as empty, so a
+  rejected file never gets a preview. An app that clears the input itself
+  (`input.value = ""` fires no `change`) dispatches `reactive:file-changed` on
+  it; bind the op to that event too and the preview, the name and the URL are
+  cleared: `op = js.preview_file("#photo-file", into: "#photo", valid: true)`,
+  `input(type: "file", id: "photo-file", **mix(on_client(:change, op),
+  on_client("reactive:file-changed", op)))`.
+  **Frame, size and type (#391):** `wrap: "#photo-frame"` shows that element
+  when an image is painted and hides it when the preview clears (marked
+  `data-reactive-wrap-hidden`; only a wrapper carrying the mark is shown again,
+  and its text is never written). `max_bytes: 2_000_000` refuses a larger file
+  before any object URL exists; `accept: true` reads the input's `accept`
+  attribute (a String is the list itself; omitted keeps `image/*`). Only an
+  image is painted: a listed file that is not `image/*` (a PDF) clears the
+  preview and hides `wrap:` without a rejection. A refused
+  file clears the preview, hides `wrap:` and dispatches `reactive:file-rejected`
+  on the input with `detail.reason` `"type"` or `"size"`; `input.files` and the
+  validity are left alone.
 - **`expanded:`** on `show`/`hide`/`toggle` (#271) keeps a disclosure trigger's
   `aria-expanded` honest: `js.toggle("#menu", expanded: "#trigger")` writes the
   op's **intended** state (`show` → `"true"`, `hide` → `"false"`, `toggle` → the
@@ -1567,6 +1595,15 @@ end
   blank field has length 0. **`{ checked: … }` counts the ticked boxes of a
   checkbox group** — `{ "ids[]" => { checked: 1.. } }` (see
   [Bulk selection](#bulk-selection-reactive_select_all-reactive_count-reactive_enable)).
+  **`{ same: :email }` compares the field with another owned field**
+  (`{ confirm_email: { same: :email, case: :fold } }`); `case: :fold`
+  lowercases ASCII `A-Z` only, on the server and in the client, and a `same:`
+  name no element of the render carries raises at render.
+  **`{ digits: 10, starts_with: "9" }` is a closed digit format** — ASCII
+  `0-9` only, an exact count or an Integer Range (`digits: 9..11`), an
+  optional digit prefix. Pair it with **`after: :blur`** (or `after: :code`
+  for a multi-field condition) to keep a soft hint hidden until the field has
+  blurred once.
   `unless:` **negates** and composes with `if:`.
   Never an expression — every term is a declared literal, so there is no eval
   surface. A blank/non-numeric value fails a numeric term **closed** (hidden).
@@ -1583,6 +1620,16 @@ end
   symbols while the client resolves `[name="form[field]"]`.
 - **`disable: true`** disables a hidden section's own controls so a
   switched-away value never submits (the stale-value fix).
+- **`clear:`, `focus:`, `scroll:`** run when the section **changes**
+  visibility, never on first paint: going hidden, `clear: :notes` (or an Array)
+  empties those fields with `js.set_value`'s write and dispatches `input` per
+  field that changed (a checkbox unchecks); going visible, `focus: "#notes"`
+  focuses the first match inside the root and `scroll: true` scrolls the
+  section into view. A `clear:` name the render never produced, or a file
+  input, raises when the outermost render completes (a fragment render, or
+  one that calls `flush`, is not checked). These run on a controller that
+  saw the previous visibility: a `morph: true` reply that flips it runs them,
+  a plain replace reconnects the root and counts as first paint.
 - **Field reads follow the collection rules**: a checkbox compares its *checked*
   state; a radio group reads the **checked** radio's value; everything else
   reads `.value`. Ownership is the usual rule — a nested reactive component's
@@ -1693,6 +1740,26 @@ end
   flips, so computes, shows and completions re-run. Its own state follows the
   group: **checked** when all are ticked, **indeterminate** when some are,
   unchecked when none are. Give the header no `name` (it would post).
+- **Nested groups — `reactive_select_all(group, under: "library.books")`**
+  (#398). A tree of headers over leaves that still post as **one** array. Each
+  leaf names the path of its nearest parent with `data-reactive-group`; a
+  header with `under:` owns the boxes of the name whose group is that path or
+  below it (`library` owns `library` and `library.books`, never `libraryx`).
+  The header ticks or unticks those leaves (with `input` + `change` on each one
+  it flips) and is checked / indeterminate / unchecked from them, so a parent
+  follows its nested headers. The header without `under:` is still every box
+  of the name. Headers have no `name`, so they never post, and
+  `reactive_count` / `reactive_enable` keep counting the leaves. A blank
+  `under:`, an empty segment (`"a..b"`), or a space-padded segment
+  (`"a .b"`) raises at render.
+
+  ```ruby
+  input(type: "checkbox", **reactive_select_all("perms[]"))                         # everything
+  input(type: "checkbox", **reactive_select_all("perms[]", under: "library"))       # a branch
+  input(type: "checkbox", name: "perms[]", value: "notes", data: { reactive_group: "library" })
+  input(type: "checkbox", **reactive_select_all("perms[]", under: "library.books")) # a sub-branch
+  input(type: "checkbox", name: "perms[]", value: "view", data: { reactive_group: "library.books" })
+  ```
 - **`reactive_count(group)`** — writes the ticked count via `textContent`
   (change-guarded). Seed the first paint in its block.
 - **`{ checked: n }` / `{ checked: 1.. }`** — a term in the shared conditions
@@ -2014,6 +2081,16 @@ wire attr: `data-reactive-persist='{"key":"village-apply","ttl":604800,"debounce
 - **`restore: :blank`** (default) — a draft value lands only in a control the
   server rendered **blank**, so a 422 re-render's submitted values beat an
   older draft. `restore: :always` lets the draft win.
+- **`storage: :local`** (default) — the draft lives in `localStorage`: every
+  tab of the origin sees it, and it outlives them until `ttl`.
+  `storage: :session` (#397) keeps it in `sessionStorage` instead: the same tab
+  restores it on reload, another tab never sees it, and closing the tab drops
+  it. (A tab opened FROM this one with an opener — `window.open`, a link
+  without `noopener` — or a duplicated tab starts with a copy of the
+  browser's session store, draft included: a one-time snapshot, after which
+  the two tabs' drafts are separate.) Same key, same exclusions, same `restore:`, same clears. The two stores
+  are read separately — a `:local` draft is never restored by `:session`.
+  `"local"` / `"session"` strings are accepted; anything else raises at render.
 - **Clear** — a successful `turbo:submit-end` of the form that contains the
   root, `ttl` expiry (checked on read; default `7.days`), or `js.persist_clear`.
   A successful *reactive* action does **not** clear on its own — chain
@@ -2058,8 +2135,10 @@ are replayed via `.value`/`.checked`/`.selected`, a bare contenteditable via
 `textContent`, and a rich editor through its own `value` setter (the same
 sanitizing import a paste takes). A tampered draft can only produce what the
 user could type or paste into that field. PII sits in this
-browser's `localStorage` for `ttl`; the submit-clear and `ttl` are the
-shared-computer mitigation. `persist_state`/`persist_clear` are **actor-only**
+browser's `localStorage` (or, with `storage: :session`, this tab's
+`sessionStorage`) for `ttl`; the submit-clear, `ttl` and
+`storage: :session` (the draft goes with the tab) are the shared-computer
+mitigation. `persist_state`/`persist_clear` are **actor-only**
 ops (refused by `broadcast_to(js:)`). See the [security page](docs/security.md).
 
 ### Client-side computes (`reactive_compute` + `reactive_text`)
@@ -3124,7 +3203,7 @@ Notifications::Badge.broadcast_to(user, :alerts,
   js: js.add_class("#bell", "has-unread"), exclude: reactive_connection_id)
 ```
 
-`broadcast_to` with `js:` **refuses the actor-only ops** (`focus`/`focus_first`/
+`broadcast_to` with `js:` **refuses the actor-only ops** (`focus`/`focus_first`/`blur`/
 `show_modal`/`close_dialog`/`submit`/`paste_into`/`preview_file`/`persist_state`/`persist_clear`/`check_group`/`set_value` raise
 `ArgumentError`): broadcasting focus (or a modal) would steal it in every subscriber's tab, a
 broadcast submit would force-submit every subscriber's form, and a broadcast

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

@@ -28,6 +28,7 @@ registerReactiveFeatureLoader("bindings", () => import("phlex/reactive/features/
 registerReactiveFeatureLoader("compute", () => import("phlex/reactive/features/compute"), waitingForEdit)
 registerReactiveFeatureLoader("sortable", () => import("phlex/reactive/features/sortable"))
 registerReactiveFeatureLoader("presence", () => import("phlex/reactive/features/presence"))
+registerReactiveFeatureLoader("countdown", () => import("phlex/reactive/features/countdown"))
 registerReactiveFeatureLoader("effects", () => import("phlex/reactive/features/effects"))
 registerReactiveFeatureLoader("hints", () => import("phlex/reactive/features/hints"))
 registerReactiveFeatureLoader("devtools", () => import("phlex/reactive/features/devtools"))