modal_stack 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44bb2750129e5c72cb364e6fd217603b35e838cd2b42d8f7d55b93902cb1409c
-  data.tar.gz: 76aa67df55336d851d2c11ce06d00ab99fd1959bb4542331dba3b129ad3cacad
+  metadata.gz: a4ea30705b3d178cd2be1ad1a3b0a7b5487b40490b327d0e727b29e9e644f06f
+  data.tar.gz: '049b2eafb22af9cffd3ec3d454a23550dff04273cb23e4b96146a3716a62a383'
 SHA512:
-  metadata.gz: 64e9cb4d64f3cabb2d78b3b7f37aa608300008cbab3195fb1cc3f0c57f9b7492907577d0fe4db4415aaebc75a54226ab9114a632ce905864d8de96d8b078766e
-  data.tar.gz: 2f525716be7b232ada7ce0a3499c859707e6e61e5e4990ae6097b416e876e05f62e56d5d945ac5819aeb355a464811213fb6b9f1bd149ab4b849ff87d75c42ad
+  metadata.gz: da14584321b5c28cd93ecbc9dd260865313c5ccd62e17d7846a734c3da47b54e3f0ac20b703542cb14d8cc93fe3611c5de0d7e17c06900ecab92c554ae5c806f
+  data.tar.gz: 111ac685cf469d968fb71288cc13822d059e97212a01b098d3766ce0136990ac1b0db4384777a86245fb6923cb225fc62c23543979d79fe18efbc1d2b1e8dbfe

data/CHANGELOG.md

@@ -12,6 +12,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+## [0.3.0] - 2026-05-03
+
+### Added
+- **Prefetch cache + dedupe** in `Orchestrator`: fragments fetched for `push` / `replaceTop` are cached per URL (TTL 30 s) and concurrent prefetches for the same URL share a single in-flight request. Aborts pending requests on `closeAll` and on stack-mismatching `popstate`.
+- **Hover/focus prefetch** on `modal-stack-link`: links warm the cache on `pointerenter` / `focus` so the modal opens with no network latency on click. Opt out with `data-modal-stack-link-prefetch="false"`.
+- **`Orchestrator#prefetch(url)`** public method (and matching `ModalStackController#prefetch`) for warming the cache from app code.
+- **Request-scoped configuration** via `controller.modal_stack_config` (helper-method exposed). Rendering helpers now read configuration once per request instead of once per call.
+- **`:tailwind_v4` CSS preset** that chains on Tailwind v4 `@theme` tokens (`--color-*`, `--radius-*`, `--shadow-*`, `--ease-*`, `--container-*`), so the modal stack inherits the host project's Tailwind theme automatically. Fallbacks match the Tailwind v4 defaults so the preset still renders correctly when `@theme` isn't redefined (or when Tailwind v4 isn't installed).
+- **`:tailwind_v3` CSS preset** — the previous `:tailwind` preset, renamed for clarity. Static values aligned with Tailwind v3 defaults (Tailwind v3 doesn't expose tokens as CSS variables).
+- `Configuration::CSS_PROVIDER_ALIASES` constant for legacy `:tailwind` → `:tailwind_v3` normalization.
+- New tests: prefetch dedupe / cache hit / TTL / abort-on-closeAll / `prefetch` API; CSS-derived leave timeout; `:tailwind` alias normalization; generator default + alias mapping.
+
+### Changed
+- **Animation safety timeout** is now derived from the `--modal-stack-duration` CSS variable on the `<dialog>` (1.5× the declared duration, floored at 300 ms). Falls back to 600 ms when the variable is unset, so existing host CSS keeps working.
+- `BrowserRuntime#fetchFragment` accepts an `{ signal }` option to support `AbortController` cancellation.
+- **CSS preset perf overhaul**: removed animated blur from all four presets — animating `backdrop-filter: blur(2px)` on a fullscreen surface costs ~190 ms/frame on Hi-DPI displays (Retina, 4K), which collapsed modal animations to ~5 fps.
+  - The old `--modal-stack-backdrop-blur` variable (radius only) is replaced with `--modal-stack-backdrop-filter` (full filter expression). Default is `none`, which lets Chrome skip the filter pass entirely — `backdrop-filter: blur(0)` still allocated a filter layer, so a `0` radius wasn't actually free. Apps that want a blurred backdrop now opt in with `:root { --modal-stack-backdrop-filter: blur(8px); }` (any filter expression accepted, not just `blur()`).
+  - `backdrop-filter` is no longer in the backdrop's `transition` list — when the user opts in, the filter is applied statically when the dialog opens, so the cost is paid once and the per-frame compositor work disappears.
+  - `filter: blur(0.5px)` on inert (underlying) layers has been dropped — only `opacity: 0.5` remains. The blur was visually negligible on screen but forced an extra GPU layer per stacked modal.
+  - The `filter` property has been removed from the layer's `transition` list since nothing animates it any more.
+- **Backdrop fade now runs in parallel with the layer's leave animation** when closing the last modal (or `closeAll`). Previously the reducer emitted `[unmountTopLayer, …, closeDialog, …]` and the orchestrator awaited each command sequentially — `closeDialog` only fired after the layer's 220 ms `transitionend`, so the backdrop fade-out was perceived *after* the modal was gone (effective close time ≈ 440 ms). The reducer now emits `closeDialog` first; it's synchronous on the runtime, so the dialog's exit transition (opacity, backdrop background, `display`/`overlay` `allow-discrete`) starts immediately and runs alongside the layer's `[data-leaving]` transition. Total close time is now ≈ 220 ms. Fix applied to `pop`, `closeAll`, and the two `handlePopstate` branches that close the dialog.
+- **`config.css_provider` default** is now `:tailwind_v3` (was `:tailwind`). Existing apps with `config.css_provider = :tailwind` keep working — the alias is normalized to `:tailwind_v3` on assignment, with no rendered CSS change.
+- **Generator default `--css-provider`** is now `tailwind_v4` for new installs (was `tailwind`). Run `bin/rails g modal_stack:install --css-provider=tailwind_v3` to opt back in to the v3 preset, or pass the legacy `tailwind` flag — it's normalized to `tailwind_v3` in the generated initializer.
+- The `app/assets/stylesheets/modal_stack/tailwind.css` file has been renamed to `tailwind_v3.css`. Sprockets manifests written by previous installs that contain `//= link modal_stack/tailwind.css` need the line updated to `tailwind_v3.css` (or `tailwind_v4.css`). Importmap / jsbundling installs aren't affected — they don't reference the stylesheet by filename.
+- `INITIALIZER_VERSION` bumped to `0.3.0` because the generator template documents the new providers.
+
+## [0.2.0] - 2026-05-03
+
+### Added
+- **`max_depth` enforcement**: pushes past the cap are now intercepted by the reducer. The new `config.max_depth_strategy` (`:warn` default, `:raise`, `:silent`) controls behaviour. The cap can be disabled with `config.max_depth = nil`.
+- **`ModalStackDepthError`** JS class, thrown by `push()` under the `:raise` strategy. Exported from `state.js`.
+- **Scrollbar-width compensation**: `BrowserRuntime#lockScroll` now sets `--modal-stack-scrollbar-width` on `<html>` so the host CSS can offset fixed elements without layout shift. The CSS variable was already referenced by the Tailwind / Bootstrap / vanilla presets — this completes the wiring.
+- **`modal_stack:error` custom event**: malformed Turbo Stream payloads (bad `data-*`, fetch failures) no longer crash the page. The error is logged and re-emitted as a bubbling `CustomEvent` on the `<dialog>` so apps can surface UI feedback.
+- **JSDoc** on the JS public surface (`state.js`, `runtime.js`, `orchestrator.js`) — including `Layer`, `Stack`, `Command`, and `Transition` typedefs.
+- New tests: max_depth strategies, scrollbar-width compensation, missing-handler error message, default_dismissible/max_depth/max_depth_strategy validation, dialog tag wiring.
+
+### Changed
+- `Configuration#default_dismissible=` now raises `ArgumentError` on non-boolean values (was a silent `attr_accessor`).
+- `Configuration#max_depth=` now coerces strings, accepts `nil`, and rejects non-positive integers.
+- `Orchestrator` constructor accepts `maxDepth` + `maxDepthStrategy`. The Stimulus controller forwards them via `data-modal-stack-max-depth-value` / `data-modal-stack-max-depth-strategy-value`, which `modal_stack_dialog_tag` now emits from the gem's configuration.
+- The "runtime missing handler" error message now lists the runtime's known handlers and the current stack depth.
+- `INITIALIZER_VERSION` bumped to `0.2.0` because the generator template gained `config.max_depth_strategy`.
+
 ## [0.1.1] - 2026-05-02
 
 ### Added

data/README.md

@@ -9,9 +9,10 @@ browser back/forward support, and drive everything from imperative Turbo
 Stream actions (`modal_push`, `modal_pop`, `modal_replace`, `modal_close_all`).
 
 [![CI](https://github.com/Metalzoid/modal_stack/actions/workflows/main.yml/badge.svg)](https://github.com/Metalzoid/modal_stack/actions)
-[![Gem Version](https://badge.fury.io/rb/modal_stack.svg)](https://rubygems.org/gems/modal_stack)
-[![Ruby](https://img.shields.io/gem/ruby-version/modal_stack?label=ruby)](https://www.ruby-lang.org/)
-[![Rails](https://img.shields.io/gem/dv/modal_stack/railties?label=rails)](https://rubyonrails.org/)
+[![Gem Version](https://img.shields.io/gem/v/modal_stack.svg?label=gem)](https://rubygems.org/gems/modal_stack)
+[![Downloads](https://img.shields.io/gem/dt/modal_stack?label=downloads)](https://rubygems.org/gems/modal_stack)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![Rails](https://img.shields.io/badge/rails-7.2%20%7C%208.0%20%7C%208.1-CC0000?logo=rubyonrails&logoColor=white)](https://rubyonrails.org/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.txt)
 
 </div>
@@ -140,10 +141,11 @@ $ bin/rails g modal_stack:install --mode=sprockets   # legacy apps
 Pick the CSS preset that matches your stack:
 
 ```bash
-$ bin/rails g modal_stack:install --css-provider=tailwind   # default
-$ bin/rails g modal_stack:install --css-provider=bootstrap  # picks up Bootstrap 5 vars
-$ bin/rails g modal_stack:install --css-provider=vanilla    # framework-free
-$ bin/rails g modal_stack:install --css-provider=none       # bring your own CSS
+$ bin/rails g modal_stack:install --css-provider=tailwind_v4 # default — chains on Tailwind v4 @theme tokens
+$ bin/rails g modal_stack:install --css-provider=tailwind_v3 # static values aligned with Tailwind v3
+$ bin/rails g modal_stack:install --css-provider=bootstrap   # picks up Bootstrap 5 vars
+$ bin/rails g modal_stack:install --css-provider=vanilla     # framework-free
+$ bin/rails g modal_stack:install --css-provider=none        # bring your own CSS
 ```
 
 ### What the generator does
@@ -204,13 +206,14 @@ Everything lives in `config/initializers/modal_stack.rb`:
 ```ruby
 ModalStack.configure do |config|
   # ─── Presentation ─────────────────────────────────────────────────
-  config.css_provider     = :tailwind   # :tailwind | :bootstrap | :vanilla | :none
+  config.css_provider     = :tailwind_v4 # :tailwind_v3 | :tailwind_v4 | :bootstrap | :vanilla | :none
   config.default_variant  = :modal      # :modal | :drawer | :bottom_sheet | :confirmation
   config.default_size     = :md         # :sm | :md | :lg | :xl
   config.default_dismissible = true     # ESC + backdrop click close the layer
 
   # ─── Behavior ─────────────────────────────────────────────────────
-  config.max_depth              = 5     # hard cap on nested layers
+  config.max_depth              = 5     # hard cap on nested layers (nil to disable)
+  config.max_depth_strategy     = :warn # :warn | :raise | :silent
   config.respect_reduced_motion = true  # honor prefers-reduced-motion
   config.replace_turbo_confirm  = false # use modal_stack confirmations for data-turbo-confirm
 
@@ -393,8 +396,17 @@ The `<dialog>` itself is opened on first push, closed on last pop. Page
 scroll is locked while any layer is open (`<body data-modal-stack-locked>`)
 so the page beneath doesn't scroll under your finger on touch devices.
 
-`max_depth` (default `5`) is a hard ceiling — pushing past it raises a
-runtime error, on the assumption that you have a state-machine bug.
+`max_depth` (default `5`) is a hard ceiling on the number of stacked layers,
+on the assumption that going past it usually means you have a state-machine
+bug. The behaviour is controlled by `config.max_depth_strategy`:
+
+| Strategy   | Behaviour                                                            |
+| ---------- | -------------------------------------------------------------------- |
+| `:warn`    | (default) The push is dropped and `console.warn` logs a message.     |
+| `:raise`   | The JS runtime throws `ModalStackDepthError` (caught by the stream-action error boundary, see below). |
+| `:silent`  | The push is dropped without logging.                                 |
+
+Set `config.max_depth = nil` to disable the cap entirely.
 
 ---
 
@@ -410,13 +422,14 @@ ModalStack.reset_configuration!         # test-fixture helper
 
 | Attribute                    | Type    | Default                  | Description |
 | ---------------------------- | ------- | ------------------------ | ----------- |
-| `css_provider`               | Symbol  | `:tailwind`              | One of `:tailwind`, `:bootstrap`, `:vanilla`, `:none`. Determines which stylesheet `modal_stack_stylesheet_link_tag` resolves to. Validated. |
+| `css_provider`               | Symbol  | `:tailwind_v3`           | One of `:tailwind_v3`, `:tailwind_v4`, `:bootstrap`, `:vanilla`, `:none`. Determines which stylesheet `modal_stack_stylesheet_link_tag` resolves to. The legacy `:tailwind` is accepted and normalized to `:tailwind_v3`. New installs default to `:tailwind_v4`. Validated. |
 | `assets_mode`                | Symbol  | `:auto`                  | One of `:importmap`, `:jsbundling`, `:sprockets`, `:auto`. Used by the generator. Validated. |
 | `default_variant`            | Symbol  | `:modal`                 | `:modal`, `:drawer`, `:bottom_sheet`, or `:confirmation`. Validated. |
 | `default_size`               | Symbol  | `:md`                    | `:sm`, `:md`, `:lg`, `:xl`. Validated. |
 | `default_dismissible`        | Boolean | `true`                   | Default for `dismissible:` when omitted. |
 | `default_classes`            | Hash    | `{ ... }`                | Hash of extra CSS class strings keyed by `:modal_panel`, `:drawer_panel`, `:bottom_sheet_panel`, `:confirmation_panel`. Useful for adding utility classes on top of the chosen preset. |
-| `max_depth`                  | Integer | `5`                      | Hard cap on stack depth — pushing past it raises. |
+| `max_depth`                  | Integer | `5`                      | Hard cap on stack depth. Coerced from strings; set to `nil` to disable. Validated. |
+| `max_depth_strategy`         | Symbol  | `:warn`                  | One of `:warn`, `:raise`, `:silent`. See [Stack depth & inertness](#stack-depth--inertness). Validated. |
 | `request_header`             | String  | `"X-Modal-Stack-Request"` | HTTP header used by the JS runtime to signal stack-originated fetches. Read by `modal_stack_request?`. |
 | `dialog_id`                  | String  | `"modal-stack-root"`     | The id of the singleton `<dialog>`. Override only on name collision. |
 | `stack_root_data_attribute`  | String  | `"modal-stack"`          | The Stimulus `data-controller` value attached to the `<dialog>`. |
@@ -434,7 +447,7 @@ Injected into `ActionView::Base` by the engine — available in every view.
 | ------------------------------------------------- | ----------- |
 | `modal_link_to(name, options, html_options)`      | Renders a `link_to` wired to push a layer when clicked. Accepts the modal options (`as:`, `side:`, `size:`, `width:`, `height:`, `dismissible:`) on top of standard `link_to` arguments. Falls back to plain `link_to` for Hotwire Native requests. |
 | `modal_stack_container(size:, variant:, side:, width:, height:, dismissible:, html: {}) { ... }` | Wraps a panel view with the markup the JS runtime expects. Renders a `<div>` carrying the size/variant/dismissible/dimension data attributes. |
-| `modal_stack_stylesheet_link_tag(**options)`      | Emits `<link rel="stylesheet">` for the configured preset (`modal_stack/tailwind.css`, etc.). Returns an empty SafeBuffer when `css_provider = :none`. |
+| `modal_stack_stylesheet_link_tag(**options)`      | Emits `<link rel="stylesheet">` for the configured preset (`modal_stack/tailwind_v4.css`, etc.). Returns an empty SafeBuffer when `css_provider = :none`. |
 | `modal_stack_dialog_tag(**html_options)`          | Emits the singleton `<dialog id="modal-stack-root" data-controller="modal-stack">`. Drop just before `</body>`. |
 | `modal_stack_javascript_tag`                      | Reserved hook for layouts; currently a no-op (JS is loaded via your bundler / importmap). |
 
@@ -503,11 +516,11 @@ The package exports a small functional core + a browser adapter:
 import {
   // pure reducer — no IO, no DOM
   createStack, push, pop, replaceTop, closeAll, handlePopstate,
-  snapshot, restore, topLayer, VARIANTS,
+  snapshot, restore, topLayer, VARIANTS, ModalStackDepthError,
 
   // orchestrator + browser runtime
   Orchestrator, BrowserRuntime,
-  FRAGMENT_HEADER, SNAPSHOT_KEY,
+  FRAGMENT_HEADER, SNAPSHOT_KEY, SCROLLBAR_WIDTH_VAR,
 } from "modal_stack"
 
 import { install } from "modal_stack/install"
@@ -518,6 +531,39 @@ entry point your `application.js` calls. The reducer is
 side-effect-free and 100% covered; the browser adapter is the only
 file that touches `<dialog>`, `history`, `fetch`, and `sessionStorage`.
 
+The reducer's command type vocabulary (`mountLayer`, `morphTopLayer`,
+`unmountTopLayer`, `unmountAllLayers`, `showDialog`, `closeDialog`,
+`lockScroll`, `unlockScroll`, `inertLayer`, `pushHistory`,
+`replaceHistory`, `historyBack`, `rebuildFromSnapshot`, `persistSnapshot`,
+`clearSnapshot`) forms the contract between `state.js` and any runtime —
+swap in a custom adapter (e.g. for Hotwire Native) by implementing one
+method per command name.
+
+#### Custom events
+
+The `<dialog>` emits two `CustomEvent`s that bubble to `document`:
+
+| Event                  | `detail`                                    | Fired when |
+| ---------------------- | ------------------------------------------- | ---------- |
+| `modal_stack:ready`    | `{ stackId }`                               | The Stimulus controller has connected and the orchestrator is ready. |
+| `modal_stack:error`    | `{ action, error }`                         | A Turbo Stream action (`modal_push`/`modal_pop`/`modal_replace`/`modal_close_all`) threw or rejected. The page is not crashed; surface UI feedback in the listener. |
+
+```js
+document.addEventListener("modal_stack:error", (event) => {
+  const { action, error } = event.detail;
+  showFlash(`Modal action ${action} failed: ${error.message}`);
+});
+```
+
+#### Scrollbar-width compensation
+
+When the first layer is pushed, `BrowserRuntime#lockScroll` measures
+`window.innerWidth - documentElement.clientWidth` and writes the result
+to `--modal-stack-scrollbar-width` on `<html>`. The shipped CSS presets
+already consume the variable (`padding-right: var(--modal-stack-scrollbar-width, 0)`)
+so fixed elements don't jump rightward on lock. If you maintain custom
+CSS, compose your fixed-position rules against the same variable.
+
 ### Capybara helpers
 
 For system specs, opt in by requiring the RSpec entrypoint:
@@ -550,7 +596,7 @@ $ bin/rails g modal_stack:install [flags]
 | Flag                  | Type    | Default     | Values |
 | --------------------- | ------- | ----------- | ------ |
 | `--mode`              | String  | `auto`      | `auto`, `importmap`, `jsbundling`, `sprockets` |
-| `--css-provider`      | String  | `tailwind`  | `tailwind`, `bootstrap`, `vanilla`, `none` |
+| `--css-provider`      | String  | `tailwind_v4` | `tailwind_v3`, `tailwind_v4`, `bootstrap`, `vanilla`, `none` (legacy `tailwind` accepted, normalized to `tailwind_v3`) |
 | `--skip-layout`       | Boolean | `false`     | When set, doesn't inject the stylesheet/dialog helpers into `application.html.erb` |
 | `--skip-js`           | Boolean | `false`     | When set, skips the Importmap pin / package install / Stimulus install wiring |
 | `--skip-initializer`  | Boolean | `false`     | When set, doesn't generate `config/initializers/modal_stack.rb` |
@@ -569,17 +615,18 @@ safe.
 
 ## 🎨 CSS presets & theming
 
-Three opinionated stylesheets ship with the gem. Pick one with
+Four opinionated stylesheets ship with the gem. Pick one with
 `config.css_provider`:
 
-| Preset       | File                                       | Best for |
-| ------------ | ------------------------------------------ | -------- |
-| `:tailwind`  | `app/assets/stylesheets/modal_stack/tailwind.css`  | Tailwind apps — uses Tailwind tokens by default but overridable |
-| `:bootstrap` | `app/assets/stylesheets/modal_stack/bootstrap.css` | Picks up Bootstrap 5 CSS variables |
-| `:vanilla`   | `app/assets/stylesheets/modal_stack/vanilla.css`   | Framework-free, neutral defaults |
-| `:none`      | —                                          | Bring your own CSS |
+| Preset          | File                                                  | Best for |
+| --------------- | ----------------------------------------------------- | -------- |
+| `:tailwind_v4`  | `app/assets/stylesheets/modal_stack/tailwind_v4.css`  | Tailwind v4 apps — chains on `@theme` tokens (`--color-*`, `--radius-*`, `--shadow-*`, `--container-*`) so the modal picks up your theme automatically. Falls back to Tailwind defaults when `@theme` isn't redefined. |
+| `:tailwind_v3`  | `app/assets/stylesheets/modal_stack/tailwind_v3.css`  | Tailwind v3 apps — static values aligned with Tailwind v3 defaults (v3 doesn't expose tokens as CSS variables). Legacy `:tailwind` is accepted as an alias. |
+| `:bootstrap`    | `app/assets/stylesheets/modal_stack/bootstrap.css`    | Picks up Bootstrap 5 CSS variables |
+| `:vanilla`      | `app/assets/stylesheets/modal_stack/vanilla.css`      | Framework-free, neutral defaults |
+| `:none`         | —                                                     | Bring your own CSS |
 
-All three presets are driven by the same `--modal-stack-*` CSS variables.
+All presets are driven by the same `--modal-stack-*` CSS variables.
 Override on `:root` to retheme without touching the gem:
 
 ```css
@@ -676,7 +723,7 @@ modal_stack/
 ├── app/
 │   ├── assets/
 │   │   ├── javascripts/modal_stack.js  # pre-built importmap bundle (committed)
-│   │   └── stylesheets/modal_stack/    # tailwind / bootstrap / vanilla presets
+│   │   └── stylesheets/modal_stack/    # tailwind_v3 / tailwind_v4 / bootstrap / vanilla presets
 │   ├── javascript/modal_stack/         # ES module sources + bun tests
 │   │   ├── state.js                    # pure reducer (100% coverage)
 │   │   ├── orchestrator.js             # state → command translator