@stratal/inertia-modal 0.0.27 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,298 @@
+# @stratal/inertia-modal
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [99e36c5]
+- Updated dependencies [df54f36]
+  - @stratal/inertia@0.1.1
+  - stratal@0.1.1
+  - @stratal/testing@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- a753e55: Stack modal routes above one another with the stack held by the browser, server-render modal levels, and make the prop helpers work inside `ctx.modal()`.
+
+  ### Nested stacks
+  - A level nests when its `base` names the modal route below it; otherwise it starts a fresh stack. Each level owns its URL — path and query string — so a direct visit or refresh renders the whole chain, and closing a level lands where it was opened from, with the query it was opened under.
+  - A level keeps a stable identity while it stays open at the same URL, so a refresh, or a level opening above it, does not remount it and lose in-progress form state.
+  - Opening a sheet is one request that renders one component. The page behind it is rendered only for a direct visit or a refresh — the one case with nothing already on screen — so a sheet reached by a redirect no longer costs a second render of the page beneath it.
+  - `<ModalLink>` opens a sheet and carries the visit options that keep the page behind it in place.
+  - `useModal()` gives you `modal`, `depth`, `isTop`, `close()`, `closeAll()`, `refresh()`, `reload()` and `visit()`, and browser Back closes exactly one level. `refresh()` takes `router.get`'s options, `reload()` takes `router.reload`'s, and `close()`/`closeAll()` take `router.visit`'s, so a caller can time the visit it started rather than the next one to finish. All are properties holding closures, so destructuring one is safe.
+  - `refresh(query)` re-reads the open level under a refined query — applying a filter, a sort, or a code the server prices. The level is recognised by its own URL, so a refinement never reads as a second sheet of the same route opening.
+  - `isModalBackground(ctx)` tells a route it is being rendered as the page beneath a modal, so a route that answers clients with a redirect can render instead. Without it that redirect is followed back to the modal and surfaces as `ModalBaseCycleError`, which is added here and thrown when a `base` chain leads back to a route already in it. A client cannot make `isModalBackground` answer true.
+
+  ### Closing a level
+  - Closing lands on the page or the level the sheet was opened from, which stays mounted — so regions that were showing content keep showing it instead of falling back to a placeholder, and the page keeps the props it holds. That landing costs one request.
+  - Where a level closes to is decided once, when it opens, and travels with the level, so a refresh of the sheet no longer loses the query the list beneath was filtered by. A level lands on the page, never on another level that is still open: a visit made from a sheet sends that sheet as its `Referer`, so the two could previously aim at each other and no amount of closing ever reached the page.
+  - Closing repeatedly unwinds the whole stack rather than reopening the level that just closed, and dismissing a whole stack lands the same way as closing the outermost level.
+  - The first browser Back after closing lands where the close already landed, so it appears to do nothing.
+  - Rows a level had already loaded survive a close instead of restarting from the first page, and the level below is handed back under the identity it already had — so its scroll metadata and merge target stay at the path its mounted components read.
+
+  ### Prop helpers, scroll and SSR
+  - `defer`, `merge`, `once` and `scroll` now work inside `ctx.modal()`. A level was previously built from the raw argument and never run through prop resolution, so none of them had any effect; all four now behave in a sheet exactly as they do on a page.
+
+    ```typescript
+    return ctx.modal(
+      "Parent/Index",
+      {
+        items: ctx.scroll(
+          () =>
+            db.$cursor.item.findMany({
+              cursor,
+              take: 20,
+              orderBy: [{ updatedAt: "desc" }, { id: "desc" }],
+            }),
+          { matchOn: "id" },
+        ),
+      },
+      { base: "/parent" },
+    );
+    ```
+
+  - `<Deferred>` and `<InfiniteScroll>` re-exported from `@stratal/inertia-modal/react` resolve `data` against the modal they render in, so the same JSX works in a sheet and on a page and no caller composes the wire path itself.
+  - A partial reload that names nothing about the level leaves it alone, so the client keeps what it holds and the level's outstanding `defer()` props are not advertised a second time — re-announcing them made the client fetch each one again for every reload the surrounding page made. A partial reload naming a level's props resolves just those.
+  - **Modal levels now server-render.** `<Modal />` previously initialised its stack as empty state and filled it in two effects, so no level ever appeared in server-rendered HTML; levels now resolve before the tree renders and reach first paint. The open stack is also held outside the page component, so a background-page remount no longer destroys every open sheet.
+  - Pass `createInertiaApp`'s `resolve` through `withModals()` in both the client and SSR entries. There is no bootstrap step to run before hydrating and no provider to wrap the tree in.
+
+    ```tsx
+    createInertiaApp({
+      resolve: withModals((name) => pages[`./pages/${name}.tsx`]()),
+      setup: ({ el, App, props }) => hydrateRoot(el, <App {...props} />),
+    });
+    ```
+
+  - This makes first-paint modal content _possible_; it does not make every modal's markup appear. A level whose content renders inside a Radix `Portal` still will not appear in server HTML, since `createPortal` is an inherently client-side DOM operation. If you want a level's content in first paint, that level has to render without a Portal.
+  - Render a modal route's background page client-only when that page is excluded from SSR through `ssrExclude`. A direct visit or refresh of such a modal route previously failed with `Page not found` and a 500.
+  - Keep a sheet on screen while the level replacing it loads, rather than leaving the screen with no sheet for as long as the component takes to arrive.
+
+  ### Testing
+
+  Import `@stratal/inertia-modal/testing` alongside `@stratal/inertia/testing`. Eight assertions, chainable like the Inertia family, plus two readers:
+
+  ```typescript
+  await response.assertModalComponents(["Parent/Index", "Parent/Edit"]);
+  await response.assertModalProp("item.id", "42");
+
+  const level = await response.modalLevel<{ items: Item[] }>();
+  expect(level.props.items).toHaveLength(1);
+  ```
+
+  - `assertModal(callback?)` / `assertNoModal()`, `assertModalComponent(component, depth?)`, `assertModalComponents(components)`, `assertModalCount(count)`, `assertModalDepth(depth)`, `assertModalProp(path, expected, depth?)`, `assertModalOnly()`, plus `modalLevel<TProps>(depth?)` and `modalLevels<TProps>()`.
+  - `assertModalBase()` and `assertModalClose()` assert what a level sits over and where closing it lands — a wrong close target is otherwise invisible until someone taps Close and does not arrive.
+  - Not one of them names a payload field, so a later payload change costs you nothing. Only a direct visit or a refresh reports what sits beneath, so the whole-stack assertions fail on any other response rather than reporting `1`.
+  - `resetModalState()` empties everything the package holds outside the React tree, so a test runner sharing the module across tests does not carry one test's open sheet into the next.
+  - `modalPropPath(prop)` is exported for a test naming a level's prop path.
+
+  ### Fixes
+  - `ctx.seo()` on a modal route now reaches the page. A level's metadata is written to the prop the client head-sync reads and injected into the document head on a direct visit, so the sheet's own title and description apply while its URL is the address. It was previously discarded outright, and a direct visit rendered no SEO tags at all. A level that never calls `ctx.seo()` leaves the background page's metadata untouched.
+  - A modal route answers with the flash the request carries, instead of an empty one. A submission that flashed its result and redirected into a sheet — a purchase outcome, a confirmation — previously lost it outright.
+  - Fix `<InfiniteScroll>` inside a level requesting the same page over and over without adding rows, and silently stopping after a sheet opened over it is closed. A scroll fetch is now recognised as the level it came from asking for the next page of its own prop, and a scrolled level keeps the URL it was opened under so neither the close target nor a later refresh drifts a page at a time.
+  - Leaving a level that holds an `<InfiniteScroll>` no longer throws about a missing scroll prop. The subscription now ends with the level, however the level was left — closing it, the back button, a link elsewhere — and a level still open keeps the rows it had loaded.
+  - A level is recognised under either spelling of its path, so an app appending a trailing slash no longer draws a second copy of a sheet it already has open.
+  - Leave an open level alone when a response is not addressed to it. A partial reload for a prop of the page _beneath_ a modal — a poller, a `defer()` prop of that page — was answered with the level attached and carrying no props, and the client seated that empty level back on the chain, so the sheet lost every prop it held and a level reading one as it renders went blank with an uncaught `TypeError`.
+  - Errors this package raises — a failed background fetch, a `base` chain that cycles — now read as English sentences rather than raw message keys. The `modal.*` keys are exported, so an app running i18n can translate or override any of them. A `base` answering `2xx` with a body that is not a page reports a 502 carrying the parse failure as its `cause`.
+  - Keep server-only code out of the `@stratal/inertia-modal/react` entry, so pages hydrate in development. The entry reached request handling that runs on `node:async_hooks`; a production build dropped it as unused, but a development build shipped it to the browser where it cannot resolve, so no page rendering `Modal` hydrated.
+  - Keep the render of the page beneath a modal inside the isolate that issued it, rather than forwarding it to a response-cache gateway where the background marker means nothing — which refused a base page that answers with a redirect, and could store that render under the visitor's own cache key.
+
+  ### Breaking Changes
+  - **`ctx.inertiaModal(component, props, { baseURL })` is replaced by `ctx.modal(component, props, { base })`.** Rename the call and the option at every call site, including modal routes whose background is another modal route — there is no separate call for those.
+  - **`MODAL_VISIT` and `MODAL_REFRESH` are removed.** Replace `<Link {...MODAL_VISIT}>` with `<ModalLink>`, and a `MODAL_REFRESH` visit with `refresh()` from `useModal()`.
+  - **`useModal().redirect()` is renamed to `close()`.** Update `const { redirect } = useModal()` to `const { close } = useModal()`, and any `onClick={redirect}` to `onClick={close}`.
+  - **`useModal()` no longer returns `show` or `props`.** Read `modal` instead: it is `undefined` outside a modal, and carries the level's `props`.
+  - **`useModalPropPath` is removed.** A level's props sit at a fixed path, so `reload({ only: ['items'] })` from `useModal()` names them by bare name.
+  - **`prepareModalComponents`, `rememberModalComponents`, `clearModalComponents` and `ModalComponentsContext` are removed.** Pass `resolve` through `withModals()` instead. A test suite that called `clearModalComponents` between tests wants `resetModalState()`.
+  - **`modalPropPath` moves to `@stratal/inertia-modal/testing`** and takes only a prop name.
+  - **`ModalNestingLimitError`, `ModalPayloadMismatchError` and `ModalRequestHeaderError` are removed**, along with every modal request header. Nothing about the stack travels to the server any more.
+  - **A response carries one modal, at `page.props.modal`**, addressed at `modal.props.<name>` with no key in the path; the keyed and positional containers are both gone, and `ModalData.nativeBack` with them. No runtime code outside the package reads the payload, so this affects only tests asserting on it directly — move those onto the assertions above rather than onto the new field names:
+
+    ```diff
+    -expect(body.props.modal.stack[0].component).toBe('Parent/Edit')
+    -expect(body.props.modal.stack[0].props.item.id).toBe(target.id)
+    +await response.assertModalComponents(['Parent/Edit'])
+    +await response.assertModalProp('item.id', target.id)
+    ```
+
+  - **Modal levels now server-render**, where they were previously always drawn in after hydration. A consumer relying on client-only mounting inside a level — a `useLayoutEffect` that assumed it would never run on the server, say — should read this as a behaviour change, not a fix.
+
+### Patch Changes
+
+- Updated dependencies [a753e55]
+- Updated dependencies [a753e55]
+- Updated dependencies [a753e55]
+  - stratal@0.1.0
+  - @stratal/inertia@0.1.0
+  - @stratal/testing@0.1.0
+
+## 0.0.27
+
+### Patch Changes
+
+- Updated dependencies [41a9140]
+  - stratal@0.0.27
+  - @stratal/inertia@0.0.27
+
+## 0.0.26
+
+### Patch Changes
+
+- Updated dependencies [ab95f52]
+- Updated dependencies [ab95f52]
+- Updated dependencies [bb6d3b9]
+  - stratal@0.0.26
+  - @stratal/inertia@0.0.26
+
+## 0.0.25
+
+### Patch Changes
+
+- Updated dependencies [e93db60]
+- Updated dependencies [e93db60]
+  - stratal@0.0.25
+  - @stratal/inertia@0.0.25
+
+## 0.0.24
+
+### Patch Changes
+
+- Updated dependencies [10cf223]
+  - @stratal/inertia@0.0.24
+  - stratal@0.0.24
+
+## 0.0.23
+
+### Patch Changes
+
+- Updated dependencies [13b0e8d]
+- Updated dependencies [13b0e8d]
+- Updated dependencies [13b0e8d]
+- Updated dependencies [13b0e8d]
+- Updated dependencies [13b0e8d]
+- Updated dependencies [13b0e8d]
+- Updated dependencies [13b0e8d]
+- Updated dependencies [13b0e8d]
+- Updated dependencies [13b0e8d]
+- Updated dependencies [13b0e8d]
+- Updated dependencies [13b0e8d]
+- Updated dependencies [be813bc]
+  - stratal@0.0.23
+  - @stratal/inertia@0.0.23
+
+## 0.0.22
+
+### Patch Changes
+
+- 4b273ea: Add `nativeBack` support to modal navigation and eagerly resolve deferred props in background page fetches
+  - `useModal().redirect()` now uses `history.back()` instead of a server round-trip when the modal was loaded via a partial reload, providing instant close behavior.
+  - Background page fetches send `x-inertia-resolve-deferred: true` to ensure deferred props are included in the response.
+
+- 1658945: Fix modal component re-rendering by tracking component path instead of nonce
+- Updated dependencies [1658945]
+- Updated dependencies [1658945]
+- Updated dependencies [4b273ea]
+- Updated dependencies [4b273ea]
+  - @stratal/inertia@0.0.22
+  - stratal@0.0.22
+
+## 0.0.21
+
+### Patch Changes
+
+- 3489cfd: Preserve query string and forwarded headers on modal background requests
+  - The background page request now keeps the referer URL's query string, so opening a modal no longer resets the parent list view's filter/pagination state to defaults.
+  - `x-forwarded-proto`, `x-forwarded-host`, `x-forwarded-for`, `x-forwarded-port`, `x-real-ip`, `accept-language`, and `user-agent` are forwarded from the original request when present. Middleware that reconstructs the canonical request URL (e.g. apps whose `appUrl` is derived from forwarded headers) now sees the same protocol/host as the original request, fixing background fetches that previously appeared unauthenticated because Better Auth's secure-cookie prefix was resolved against the wrong base URL.
+
+- Updated dependencies [3489cfd]
+- Updated dependencies [3489cfd]
+- Updated dependencies [3489cfd]
+- Updated dependencies [3489cfd]
+  - stratal@0.0.21
+  - @stratal/inertia@0.0.21
+
+## 0.0.20
+
+### Patch Changes
+
+- f8c61e1: Loosen peer dependency ranges for broader compatibility
+
+  Peer dependencies (`@inertiajs/core`, `@inertiajs/react`, `hono`, `react`, `reflect-metadata`, `stratal`) now use `>=` ranges instead of pinned `^` ranges, so apps can adopt newer majors of these packages without waiting for a coordinated bump.
+
+- Updated dependencies [f8c61e1]
+- Updated dependencies [f8c61e1]
+- Updated dependencies [f8c61e1]
+- Updated dependencies [f8c61e1]
+- Updated dependencies [f8c61e1]
+- Updated dependencies [f8c61e1]
+- Updated dependencies [f8c61e1]
+- Updated dependencies [f8c61e1]
+- Updated dependencies [f8c61e1]
+  - stratal@0.0.20
+  - @stratal/inertia@0.0.20
+
+## 0.0.19
+
+### Patch Changes
+
+- 5d26c24: Rearchitect i18n module augmentation to a per-module keyed registry (breaking change)
+
+  **Why:** Multiple modules augmenting `AppMessages` with a shared top-level parent (e.g., `errors.auth`, `errors.uploads`, `errors.branding`) collided with TypeScript error **TS2717** ("Subsequent property declarations must have the same type"). Interface merging adds new properties across declarations but requires same-named properties to have structurally identical types — it does not deep-merge nested shapes.
+
+  **What changed:**
+  - Replaced the single augmentable `AppMessages` interface with an `AppMessageNamespaces` keyed registry. Each module declares its own distinct top-level key (Laravel-style package namespacing). Because each declaration adds a different property, interface merging accepts them all.
+  - `AppMessages` is now derived: `{ [K in keyof AppMessageNamespaces]: AppMessageNamespaces[K] }`.
+  - Access keys are unchanged dot-notation — `i18n.t('auth.errors.invalidCredentials')` — so no custom resolver is needed.
+
+  **Migration:**
+
+  Before:
+
+  ```ts
+  declare module "stratal/i18n" {
+    interface AppMessages {
+      errors: { uploads: { notFound: string } };
+    }
+  }
+  ```
+
+  After:
+
+  ```ts
+  declare module "stratal/i18n" {
+    interface AppMessageNamespaces {
+      uploads: { errors: { notFound: string } };
+    }
+  }
+  ```
+
+  **Framework package moves:**
+  - All `errors.auth.*` keys (previously split between `stratal` core and `@stratal/framework`) now live in the auth module as `auth.errors.*`. `errors.auth.org.*` → `auth.org.*`. The `errors.auth.*` namespace has been removed from `stratal`'s core messages.
+  - `@stratal/framework`'s `DatabaseModule` now registers its `database.*` validation messages via `I18nModule.registerMessages` (previously the messages file existed but was never wired up).
+  - `@stratal/inertia-modal`'s `errors.modal.*` key moved to `modal.errors.*`.
+
+  **Callsite updates required in downstream apps:**
+
+  ```ts
+  // Before
+  new ApplicationError('errors.auth.invalidCredentials', ...)
+  i18n.t('errors.auth.org.organizationNotFound')
+
+  // After
+  new ApplicationError('auth.errors.invalidCredentials', ...)
+  i18n.t('auth.org.organizationNotFound')
+  ```
+
+  No runtime API change: `I18nModule.registerMessages(messages)` keeps its existing signature, and deep-merge behavior is unchanged. Locale-only contributions that override core's built-in `errors.*` / `common.*` / etc. continue to work.
+
+- Updated dependencies [3b16f5b]
+- Updated dependencies [5d26c24]
+- Updated dependencies [5d26c24]
+- Updated dependencies [3b16f5b]
+- Updated dependencies [3b16f5b]
+- Updated dependencies [5d26c24]
+- Updated dependencies [5d26c24]
+- Updated dependencies [3b16f5b]
+  - stratal@0.0.19
+  - @stratal/inertia@0.0.19

package/README.md

@@ -0,0 +1,223 @@
+# @stratal/inertia-modal
+
+Backend-driven modal pages for [Stratal](https://stratal.dev) Inertia apps. A modal route is a real route, so direct visits, refreshes and back/forward navigation all work.
+
+[![npm version](https://img.shields.io/npm/v/@stratal/inertia-modal)](https://www.npmjs.com/package/@stratal/inertia-modal)
+[![CI](https://github.com/strataljs/stratal/actions/workflows/ci.yml/badge.svg)](https://github.com/strataljs/stratal/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/strataljs/stratal/badge)](https://securityscorecards.dev/viewer/?uri=github.com/strataljs/stratal)
+[![Known Vulnerabilities](https://snyk.io/test/github/strataljs/stratal/badge.svg)](https://snyk.io/test/github/strataljs/stratal)
+[![npm downloads](https://img.shields.io/npm/dm/@stratal/inertia-modal)](https://www.npmjs.com/package/@stratal/inertia-modal)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/strataljs/stratal/pulls)
+[![GitHub stars](https://img.shields.io/github/stars/strataljs/stratal?style=social)](https://github.com/strataljs/stratal)
+
+## How it works
+
+The server renders **one modal per response** and the browser holds the stack. Opening a sheet is one request that renders one component; the page beneath is rendered only for a direct visit or a refresh — the one case with nothing already on screen.
+
+- **Permalinkable** — a modal URL can be shared, bookmarked and refreshed
+- **Stackable** — a modal opened from inside another appears above it, with the one below still mounted
+- **Headless** — `<Modal />` renders your components; bring your own dialog, sheet or drawer
+- **Typed page props** — `usePage().props.modal` is typed, no cast
+- **Test assertions** — `assertModalComponent()`, `assertModalProp()` and more
+
+## Installation
+
+Requires `@stratal/inertia` already configured.
+
+```bash
+npm install @stratal/inertia-modal
+# or
+yarn add @stratal/inertia-modal
+```
+
+## Setup
+
+Add `ModalModule` to your root module. It needs no configuration and registers its own i18n messages.
+
+```typescript
+import { Module } from 'stratal/module'
+import { InertiaModule } from '@stratal/inertia'
+import { ModalModule } from '@stratal/inertia-modal'
+
+@Module({
+  imports: [
+    InertiaModule.forRoot({ rootView: 'app' }),
+    ModalModule,
+  ],
+})
+export class AppModule {}
+```
+
+## Render a modal route
+
+Use `ctx.modal(component, props, { base })` in any controller. `base` is what sits *beneath* this level — a page route, or another modal route.
+
+```typescript
+import { Controller, Get, type RouterContext } from 'stratal/router'
+import { object, string } from 'zod/mini'
+
+@Controller('/parent')
+export class ParentController {
+  @Get('/:id/edit', { params: object({ id: string() }) })
+  async edit(ctx: RouterContext) {
+    const item = await this.service.find(ctx.param('id'))
+    return ctx.modal('Parent/Edit', { item }, { base: '/parent' })
+  }
+}
+```
+
+On an in-app visit to `/parent/42/edit` the current page stays mounted and `Parent/Edit` is drawn over it. On a direct visit, the framework follows `base` in-process until it reaches a route that is not a modal, and renders that as the page.
+
+Write `base` as a route that always renders for anyone who can reach the modal route — it is the guaranteed background. A `base` that cannot be rendered raises `ModalBackgroundFetchError`.
+
+## Frontend setup
+
+Pass `createInertiaApp`'s `resolve` through `withModals()` in **both** entries, and place `<Modal />` once in your layout. `withModals()` resolves every open level's component ahead of the render, so `setup` only hydrates.
+
+```tsx
+// src/inertia/app.tsx — client entry
+import { createInertiaApp } from '@inertiajs/react'
+import { hydrateRoot } from 'react-dom/client'
+import { withModals } from '@stratal/inertia-modal/react'
+
+const pages = import.meta.glob('./pages/**/*.tsx')
+
+const resolve = async (name: string) => {
+  const page = await pages[`./pages/${name}.tsx`]?.()
+  if (!page) throw new Error(`Page not found: ${name}`)
+  return page
+}
+
+createInertiaApp({
+  resolve: withModals(resolve),
+  setup: ({ el, App, props }) => hydrateRoot(el, <App {...props} />),
+})
+```
+
+```tsx
+// src/inertia/ssr.tsx — SSR entry
+import { createInertiaSsrApp } from '@stratal/inertia/ssr'
+import { withModals } from '@stratal/inertia-modal/react'
+
+export const { render } = createInertiaSsrApp({
+  resolve: withModals(resolve),
+})
+```
+
+```tsx
+// src/inertia/layouts/dashboard-layout.tsx
+import { Modal } from '@stratal/inertia-modal/react'
+
+export function DashboardLayout({ children }) {
+  return (
+    <>
+      <Sidebar />
+      <main>{children}</main>
+      <Modal />
+    </>
+  )
+}
+```
+
+> A level rendered inside a portal cannot server-render. `createPortal` is client-only, so a level whose content sits in a Radix `DialogPortal` / `SheetPortal` is absent from the server HTML however the entries are wired. Render it outside a portal if its content must be in first paint.
+
+## Open a sheet
+
+`<ModalLink>` carries the visit options that keep the page beneath mounted, in place, and un-refetched.
+
+```tsx
+import { ModalLink } from '@stratal/inertia-modal/react'
+
+<ModalLink href={`/parent/${item.id}/edit`}>Edit</ModalLink>
+<ModalLink href={`/parent/${item.id}/edit`} prefetch>Edit</ModalLink>
+```
+
+## Inside a modal
+
+`useModal()` gives the current level and the ways to act on it:
+
+```tsx
+import { useModal } from '@stratal/inertia-modal/react'
+
+function EditSheet() {
+  const { modal, depth, isTop, close, closeAll, refresh, reload, visit } = useModal()
+
+  return (
+    <Dialog open onOpenChange={(open) => { if (!open) close() }}>
+      <button onClick={() => refresh({ sort: 'name' })}>Sort by name</button>
+      <button onClick={() => reload({ only: ['items'] })}>Refresh items</button>
+      <button onClick={() => visit(`/parent/${modal.props.item.id}/delete`)}>Delete</button>
+    </Dialog>
+  )
+}
+```
+
+| Member | Description |
+|---|---|
+| `modal` | This level's data, or `undefined` outside a modal |
+| `depth` | How deep this level sits; the outermost is `0` |
+| `isTop` | Whether this is the level the reader is looking at |
+| `close()` | Close this level and land where it was opened from |
+| `closeAll()` | Close every open level |
+| `refresh(query?)` | Re-read this level under a refined query |
+| `reload(options?)` | Fetch some of this level's props again, named in the level's own terms |
+| `visit(href, options?)` | Open a modal route from code |
+
+Closing is always an explicit visit, never `history.back()` — a cached history entry would rewind the whole page, not just the modal.
+
+## Deferred and infinite-scroll props
+
+A level's props are nested under one page prop, so Inertia's own `<Deferred>` and `<InfiniteScroll>` cannot address them by name. Import these instead and the same JSX works inside a sheet and on a page:
+
+```tsx
+import { Deferred, InfiniteScroll } from '@stratal/inertia-modal/react'
+
+<Deferred data="stats" fallback={<Spinner />}>
+  <Stats />
+</Deferred>
+
+<InfiniteScroll data="items">
+  {items.data.map((item) => <Row key={item.id} item={item} />)}
+</InfiniteScroll>
+```
+
+## Testing
+
+```typescript
+// vitest.setup.ts
+import '@stratal/inertia-modal/testing'  // augments TestResponse with modal assertions
+import { resetModalState } from '@stratal/inertia-modal/react'
+
+afterEach(() => resetModalState())
+```
+
+```typescript
+const response = await module.http.get('/parent/42/edit').send()
+
+await response.assertModalComponent('Parent/Edit')
+await response.assertModalBase('/parent')
+await response.assertModalProp('item.id', '42')
+await response.assertModalCount(1)
+```
+
+Available assertions: `assertModal`, `assertNoModal`, `assertModalComponent`, `assertModalComponents`, `assertModalBase`, `assertModalClose`, `assertModalCount`, `assertModalDepth`, `assertModalProp`, `assertModalOnly`.
+
+`resetModalState()` clears the three stores that deliberately outlive a render — the open stack, the page a level grafts onto, and the resolved components. Call it between tests.
+
+## Documentation
+
+Full guides and examples are available at **[stratal.dev](https://stratal.dev)**.
+
+## Support the project
+
+If Stratal is useful to you, **[star the repository](https://github.com/strataljs/stratal)** — it is the simplest way to help others find it.
+
+## Maintainer
+
+Built and maintained by **Temitayo Fadojutimi** — [@adesege_](https://x.com/adesege_).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,46 +1,109 @@
+import { a as ModalData, i as MODAL_PROP, n as MODAL_DOCUMENT_HEADER, r as MODAL_MARKER_HEADER, t as MODAL_BENEATH_PROP } from "./wire-CbwmWkPr.mjs";
+import "./page-props-BCEWEw3V.mjs";
 import { OnInitialize } from "stratal/module";
 import { RouterContext } from "stratal/router";
+import { HttpException } from "stratal/errors";
+import "@stratal/inertia";
+import { Page } from "@inertiajs/core";
 //#region src/modal.module.d.ts
-declare class ModalModule implements OnInitialize {
+export declare class ModalModule implements OnInitialize {
   onInitialize(): void;
 }
 //#endregion
 //#region src/tokens.d.ts
-declare const MODAL_TOKENS: {
+export declare const MODAL_TOKENS: {
   readonly ModalService: symbol;
+  /**
+   * How the page beneath a modal is fetched on a document request. Override it to dispatch through
+   * something other than the app in process.
+   */
+  readonly BackgroundDispatcher: symbol;
 };
 //#endregion
-//#region src/services/modal.service.d.ts
-interface ModalData {
-  component: string;
-  props: Record<string, unknown>;
-  baseURL: string;
-  redirectURL: string;
-  key: string;
-  nativeBack: boolean;
+//#region src/i18n/en.d.ts
+export declare const modalMessages: {
+  readonly en: {
+    readonly errors: {
+      readonly backgroundFetchFailed: 'Failed to load background page for modal';
+      readonly baseCycle: 'The modal base chain leads back to {url}';
+    };
+  };
+};
+declare module 'stratal/i18n' {
+  interface AppMessageNamespaces {
+    modal: typeof modalMessages['en'];
+  }
 }
+//#endregion
+//#region src/server/background.d.ts
+interface ModalBackgroundDispatcher {
+  fetch(request: Request, ctx: RouterContext): Promise<Response>;
+}
+/**
+ * Whether this request is the background render issued for the page beneath a modal.
+ *
+ * A route that answers a client with a redirect still has to render when it is the `base` of a
+ * modal that client may open — otherwise the redirect is followed back to the modal and the chain
+ * reports a cycle.
+ *
+ * A dispatcher that leaves the isolate answers `false` on the far side, which is the safe
+ * direction: the route gates as it would for a client rather than opening for one.
+ *
+ * @example
+ * ```typescript
+ * if (isModalBackground(ctx)) return next()
+ * ```
+ */
+export declare function isModalBackground(ctx: RouterContext): boolean;
+//#endregion
+//#region src/server/modal.service.d.ts
 interface ModalRenderOptions {
-  baseURL: string;
+  /** What sits beneath this level: a page route, or another modal route. */
+  base: string;
+}
+//#endregion
+//#region src/errors/modal-background-fetch.error.d.ts
+/**
+ * Thrown when the sub-request for the page beneath a modal answers with something the chain cannot
+ * be built from — a non-2xx, a redirect, an empty body, a body that is not a page, or a level of a
+ * shape this build cannot read.
+ *
+ * `cause` carries the parse failure where there was one. The status this reports is a property of
+ * the exchange, not of the reason, so every one of those answers the caller identically; a `base`
+ * pointing at a route that does not render a page is still a mistake someone has to find, and the
+ * reason is the only thing that says which mistake it was.
+ *
+ * HTTP Status: 502 Bad Gateway — this service acted as a proxy and the upstream answered
+ * unexpectedly.
+ */
+export declare class ModalBackgroundFetchError extends HttpException {
+  constructor(cause?: unknown);
+}
+//#endregion
+//#region src/errors/modal-base-cycle.error.d.ts
+/**
+ * Raised when a route's `base` chain leads back to a route already in it.
+ *
+ * Assembling the chain costs one sub-request per level, so a cycle would otherwise run until the
+ * runtime's sub-request budget is exhausted and surface as an opaque failure.
+ */
+export declare class ModalBaseCycleError extends HttpException {
+  constructor(url: string);
 }
 //#endregion
 //#region src/augment/router-context.d.ts
 declare module 'stratal/router' {
   interface RouterContext {
     /**
-     * Renders a modal page component over a background page.
-     *
-     * The background page at `options.baseURL` is always rendered as the main
-     * Inertia page. The given `component` and `props` are embedded in the
-     * background page's `modal` prop and rendered as an overlay by the
-     * client-side `<Modal>` component.
+     * Renders `component` as a modal over whatever the client already has mounted.
      *
-     * Handles direct URL visits by fetching the background page in-process.
-     * Handles partial reloads (e.g., cascading selects) when `only: ['modal']`
-     * is requested.
+     * `options.base` declares what sits beneath this level — a page route, or another modal route.
+     * On a document request that chain is followed and rendered, so a modal URL stays a permalink;
+     * on an Inertia visit only this level is sent, and the client grafts it onto the page it holds.
      */
-    inertiaModal(component: string, props: Record<string, unknown>, options: ModalRenderOptions): Promise<Response>;
+    modal(component: string, props: Record<string, unknown>, options: ModalRenderOptions): Promise<Response>;
   }
 }
 //#endregion
-export { MODAL_TOKENS, type ModalData, ModalModule, type ModalRenderOptions };
+export { MODAL_BENEATH_PROP, MODAL_DOCUMENT_HEADER, MODAL_MARKER_HEADER, MODAL_PROP, type ModalBackgroundDispatcher, type ModalData, type ModalRenderOptions };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/modal.module.ts","../src/tokens.ts","../src/services/modal.service.ts","../src/augment/router-context.ts"],"mappings":";;;cAWa,WAAA,YAAuB,YAAY;EAC9C,YAAY;AAAA;;;cCZD,YAAA;EAAA,SAEH,YAAA;AAAA;;;UCKO,SAAA;EACf,SAAA;EACA,KAAA,EAAO,MAAM;EACb,OAAA;EACA,WAAA;EACA,GAAA;EACA,UAAA;AAAA;AAAA,UAGe,kBAAA;EACf,OAAO;AAAA;;;;YCZG,aAAA;IHMC;;;;AACC;;;;ACZd;;;;IEkBI,YAAA,CACE,SAAA,UACA,KAAA,EAAO,MAAA,mBACP,OAAA,EAAS,kBAAA,GACR,OAAA,CAAQ,QAAA;EAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/modal.module.ts","../src/tokens.ts","../src/i18n/en.ts","../src/server/background.ts","../src/server/modal.service.ts","../src/errors/modal-background-fetch.error.ts","../src/errors/modal-base-cycle.error.ts","../src/augment/router-context.ts"],"mappings":";;;;;;;;qBAwBa,uBAAuB;EAClC;;;;qBCzBW;WACX;;;;;WAKA;;;;qBCNW;WACX;aACE;eACE;eACA;;;;;YAMM;IACR,cAAc;;;;;UCOD;EACf,MAAM,SAAS,SAAS,KAAK,gBAAgB,QAAQ;;;;;;;;;;;;;;;;;wBAmCvC,kBAAkB,KAAK;;;UC7BtB;;EAEf;;;;;;;;;;;;;;;;;qBCXW,kCAAkC;EAC7C,YAAY;;;;;;;;;;qBCRD,4BAA4B;EACvC,YAAY;;;;;YCLF;;;;;;;;IAQR,MACE,mBACA,OAAO,yBACP,SAAS,qBACR,QAAQ"}