Skip to content

feat(overlay-manager): open the same Dialog or Drawer from anywhere - #514

Open
ispashkov wants to merge 32 commits into
mainfrom
feat/modal-manager
Open

ispashkov wants to merge 32 commits into
mainfrom
feat/modal-manager

Conversation

@ispashkov

@ispashkov ispashkov commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Builds on #513 (merged, v4.20.0), which added onExitComplete to Drawer and Dialog.

What

@wallarm-org/design-system/OverlayManager lets an app describe a Dialog or Drawer once and open it from any component with one await. defineOverlay(loader) describes it, one OverlayProvider per app renders it, and useOverlay(definition).open(payload) resolves with what the overlay passes to controller.close, or undefined when it is dismissed. The overlay's code loads on first open or on preload(), its exit animation plays, and its payload stays intact until the exit ends.

// DeleteUserDialog.tsx: the overlay gets its payload props plus `controller`
import { Button } from '@wallarm-org/design-system/Button';
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
} from '@wallarm-org/design-system/Dialog';
import type { OverlayProps } from '@wallarm-org/design-system/OverlayManager';

interface DeleteUserDialogProps extends OverlayProps<boolean> {
  userName: string;
}

export const DeleteUserDialog = ({ userName, controller }: DeleteUserDialogProps) => {
  const handleConfirm = () => controller.close(true);

  return (
    <Dialog {...controller.rootProps} width={400}>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Delete user?</DialogTitle>
          <DialogDescription>
            This permanently deletes {userName} and all their access. You can't undo this.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose asChild>
            <Button variant='ghost' color='neutral'>Cancel</Button>
          </DialogClose>
          <Button color='destructive' onClick={handleConfirm}>Delete user</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
};

// overlays.ts: importing it loads no dialog code
import { defineOverlay } from '@wallarm-org/design-system/OverlayManager';

export const DeleteUserOverlay = defineOverlay(() =>
  import('./DeleteUserDialog').then(m => m.DeleteUserDialog),
);

// routes/__root.tsx: one provider per app and per remote, around everything the root route renders
import { Outlet, useMatches } from '@tanstack/react-router';
import { AppShell } from '@wallarm-org/design-system/AppShell';
import { OverlayProvider } from '@wallarm-org/design-system/OverlayManager';

export const RootRoute = () => {
  // The leaf match's pathname, not its id: a match id also changes with the route's loaderDeps.
  const pathname = useMatches({ select: matches => matches.at(-1)?.pathname });
  return (
    <OverlayProvider closeOnChange={pathname}>
      <AppShell>
        <Outlet />
      </AppShell>
    </OverlayProvider>
  );
};

// DeleteUserButton.tsx: any component below the provider
import { Button } from '@wallarm-org/design-system/Button';
import { useOverlay } from '@wallarm-org/design-system/OverlayManager';
import { DeleteUserOverlay } from './overlays';

export const DeleteUserButton = ({ userName, onDeleted }: { userName: string; onDeleted: () => void }) => {
  const deleteUserOverlay = useOverlay(DeleteUserOverlay);

  const handleClick = async () => {
    const deleted = await deleteUserOverlay.open({ userName }); // boolean | undefined
    if (deleted) onDeleted();
  };

  return <Button onClick={handleClick}>Delete</Button>;
};

Exports defineOverlay, OverlayProvider, useOverlay and the types OverlayProps, OverlayController, OverlayRootProps, OverlayDefinition, OverlayProviderProps, OverlayCloseKey, UseOverlayReturn and OverlayOpenArgs, plus OverlayPayload and OverlayResult for typing callbacks (from a props type or from typeof SomeOverlay).

Additive and subpath-only, like Dialog: no breaking change, no migration.

Why

In core-frontend every call site wires its own open state: the same overlay is mounted from up to 14 files, pages pass open and target state through XxxDialogs containers, and 13 drawers keep a "last value" latch so their content does not blank while they animate out (11 of them are URL-driven detail drawers, which stay router-owned; they can now reset in #513's onExitComplete instead). Across core-frontend, rules-frontend and the legacy console, teams have hand-written the same promise-returning hook 8+ times. With the manager, any component opens the one shared definition without lifting state, and the overlay's code stays out of the page chunk until its first open.

How it works

  • One store per provider. Each OverlayProvider owns its overlays and renders them after its children. Nothing lives at DS module scope, so stories, tests and remotes with their own provider stay isolated. useOverlay uses the nearest provider and throws outside one.
  • Lazy, cached code. The loader runs on the first open() or on definition.preload(), and the definition caches it. A failed load clears the cache, so the next open() retries. Nothing shows while the code loads.
  • Boundaries per instance. Each overlay renders inside its own Suspense and error boundary, above its root. One that suspends or throws affects only itself and never reaches a Suspense boundary above the provider.
  • Exit animation. close(result) or a dismissal settles the promise at once. The instance stays mounted, payload unchanged, until its root's onExitComplete (added to Drawer and Dialog in feat(drawer): forward onExitComplete on Drawer and Dialog #513), and is dropped 1 s after closing at the latest.
  • Stacking. Overlays of one provider stack in the order they appear: open order, unless an earlier one's code is still loading. An overlay can open another above it. A second open() of the same definition replaces the first, as a double click would, until the store has inserted it: while its code loads, or for a call in the same synchronous code or a microtask or two later even with the code cached. After that, every open() is a new instance.
  • Context. Overlays read the context above the provider (query client, router, SDK), not the opener's. They keep the payload they were opened with and outlive an opener that unmounts, such as a menu item.
  • closeOnChange. When the key changes, overlays opened before it close with their exit animation, and those still loading resolve undefined and never show. Overlays opened after it, for example from the new page's mount effect, stay. Two edge cases: a key that goes from undefined to its first value counts as a change, so pass the key from the first render; and an open() that runs in that commit before the provider's layout effect (a descendant's layout effect, a ref callback) closes with the rest.
  • React replays. Open overlays survive StrictMode effect replays and a Suspense boundary above the provider re-suspending. A real unmount of the provider, or an <Activity> above it hiding, settles them undefined and drops them; after an <Activity> reveal the store drops them only once their roots have started, so the body scroll lock is released.
  • Focus. When a caller awaits an overlay and then closes the one below it (if (await confirm.open()) controller.close()), the store notifies React before it settles, so the top close commits first and focus unwinds to the original opener, as with nested overlays.
  • Settling. For an overlay that renders its one root as documented, open() never rejects and settles exactly once: with the close value, or undefined on dismissal, a closeOnChange change, a provider unmount, a load or render error, a payload that throws when read, or a second open() of the same definition that replaces it before it shows. Errors go to onError; a provider without one reports through the enclosing provider's, and the outermost falls back to reportError.

Decisions

  • A provider per app plus a hook, not Chakra's viewport per definition. One mount per app, and definitions are plain objects a library can export; a viewport per definition must be mounted exactly once, or nothing opens or it renders twice.
  • No module-level store and no global open(). Under sharedDesignSystem every container on the same DS version shares the module, so a remote's overlay could render inside the host's providers (wrong query client, wrong router).
  • Subpath only, not in the root barrel. Under sharedDesignSystem a root import and a subpath import can load two copies, and the hook would not find the provider.
  • One nested controller prop ({ rootProps, close }). overlay would clash with Drawer's backdrop prop, and flat props would clash with payload keys such as open.
  • open() never rejects. Call sites stay if (await x.open()), and the app reports failures in one place, onError. The cost: a caller cannot tell a failed load from a dismissal.
  • The promise settles when closing starts, not after the exit. Chained flows such as if (await confirm.open()) await next.open() feel instant.
  • Nothing is shown while the code loads. No loading shell in v1; preload() on hover or focus covers heavy overlays.
  • closeOnChange takes a primitive key, checked before the new page's mount useEffects run (its layout effects run first and are swept). A fresh object literal cannot close everything on every render, and overlays the new page opens on arrival survive.
  • A forced close cannot be vetoed. A closeOnChange change or a provider unmount closes a guarded overlay too, as navigation unmounts a page today; guard route changes with the router's blocker.
  • A router-owned drawer mounts its own OverlayProvider in DrawerContent, instead of a new option. Overlays opened through it are React descendants, so they close with the drawer and keep cascade-dismiss and push-back.
  • The loader returns the component, never React.lazy. React.lazy keeps a failed chunk forever, which defeats retry; the types reject a direct React.lazy (one wrapped in memo or an HOC still compiles).
  • Props are checked after inference. defineOverlay takes a rest argument that a valid component leaves empty, so a component with no props, only optional ones, or a key prop fails to compile. A constraint on the props let the first two through, as a definition that could never close.
  • A remote without its own provider falls through to the host's. For now that is a documented rule, one provider per app and per remote; a guard (OverlayScope) is a follow-up.
  • Scope: in-memory overlays inside one app. URL-driven drawers stay router-owned and keep their deep links and Back. No opening across remotes or from outside React, no close(id) from the opener, and no confirm() presets, so buttons stay consumer-composed.

Known limitations

New with this PR

  • An overlay that breaks the one-root contract (renders no root, or unmounts it while open) leaves its open() pending until closeOnChange changes or the provider unmounts.
  • <Activity mode="hidden"> above the provider drops its open overlays without an exit animation and settles them undefined (documented in usage.md).
  • When React hides and shows an opener again, it re-runs the opener's mount effect, and a second copy stacks if the first is still mounted: under StrictMode in development on a Suspense reveal, and in production for a useLayoutEffect opener on a Suspense reveal or any effect opener inside <Activity>. usage.md shows a once-per-mount ref guard.
  • An open() that runs between the provider's unmount commit and its deferred detach still fetches the overlay's code if it is not cached, then resolves undefined; nothing renders.
  • Two open() calls of one definition synchronously or a microtask or two apart count as a double click even when its code is cached: the second replaces the first, which resolves undefined. StrictMode's doubled mount effect relies on this.
  • While an inner overlay's code loads nothing is on screen, so Escape can close the outer overlay, and the inner one then shows on its own. usage.md says to preload inner definitions when the outer overlay mounts, as the edit drawer story does, or to open them through a nested provider.
  • An overlay that suspends above its root against the contract is already inserted while it suspends, so a second click stacks another instance.
  • A Suspense boundary above that re-suspends during an exit can stall the exit; the overlay then goes at the 1 s fallback. A plain Drawer stays stuck in that case, which predates this PR (zag).
  • An onError that throws, and an error thrown while an overlay unmounts, are not caught: they reach the error boundary above the provider.
  • A definition annotated by hand with a wider type compiles and loses its payload checks: with OverlayDefinition<Record<string, unknown>, unknown> its open() accepts any payload or none, and with OverlayDefinition<object, unknown> it takes none, so a required one can be left out.

Pre-existing, not caused by the manager

  • When a DropdownMenuItem opens a Dialog and the item is picked in the same frame as its highlight, as automated clicks do, focus lands on body after the dialog closes, managed or not; at human speed it returns to the trigger (jsdom probe). zag's menu does not cancel its focus frame on close; logged with the cause in docs/storybook-docs-findings.md.
  • The MCP search-alias tests in budget.test.ts skip in CI: they need dist/metadata, and the quality job runs tests before the build. They pass locally.
  • Under StrictMode, a plain Dialog can leave the body scroll lock on after a Suspense boundary above it hides and reveals it.
  • A Dialog mounted open by a synchronous update whose content throws in a mount effect leaves the body scroll lock on (zag/Ark).
  • MCP get_component OverlayManager shows no related guideline: a guideline's components can list only exported names (OverlayProvider), and the lookup compares them with the entry name (OverlayManager).
  • Storybook renders without StrictMode, so the stories do not exercise it; the unit tests do.
  • The design-system typecheck covers none of its unit test files: on main no config in the script includes *.test.*, and tsconfig.unit.json, which does, is not in the script. This PR adds only the OverlayManager type tests; its other test files were checked locally with tsconfig.unit.json.
Minor docs, story and test follow-ups (new)

Docs, stories and MCP

  • usage.md's "Define an overlay" snippet imports only OverlayProps; a copy needs FC, the Dialog parts and useToast added.
  • usage.md points to docs/storybook-docs-findings.md by its repo path, which MCP readers outside the repo cannot open.
  • Both delete snippets keep controller.close(true) inside the try with the mutation, so a throwing close would show the failure toast.
  • The failure toasts do not follow the <Action> failed — <cause> pattern of feedback-toasts.md: "Couldn't delete the user" in both delete snippets, and "Couldn't open this dialog" in usage.md's set-up.
  • The test-id-pattern.md row's Why column describes a test hazard (ids repeat during an exit) instead of why it is an exception: open() has no call-site JSX, so no id can cascade from the caller.
  • The website page and Storybook's code panel show only the opener; the overlay half is in usage.md (MCP) and in the confirmation-dialogs guideline (website).
  • Stacked Overlays and Unsaved Changes Guard share one story body; the stack and the guard live in the story-only EditUserDrawer, and usage.md describes the guard's pending flag in prose only.
  • The story's unsaved-changes guard has 2 footer buttons, where the confirmation-dialogs Copy table lists 3.
  • No modal manager search alias: it would tie with Dialog.
  • The store's fail JSDoc does not say that an unknown id is ignored.

Tests

  • defineOverlay's sync-throw test checks preload() and the retry, not that load() itself rejects.
  • No test calls preload() and open() while the chunk is still loading.
  • Store notifications from fail, the closeOnChange sweep and detach are not asserted.
  • No store test for a late load rejection after a replace, sweep or detach staying unreported, for fail then close, for a NaN key, or for the key surviving a detach and attach.
  • The closeOnChange tests never query their page-a/page-b ids, and no test combines "the old overlay closes" with "the new page's mount-effect overlay survives".
  • The deferred-promise setup is repeated in four tests of OverlayManager.test.tsx.
  • Of the new search aliases, only dialog manager has a test that fails without it; drawer manager, which would otherwise tie with Drawer, has none.

Also

  • Usage doc. OverlayManager/docs/usage.md: set-up, defining an overlay, opening it, nesting and limits. MCP serves it as the docs/usage section of get_component; the Storybook Overview names defineOverlay, useOverlay, OverlayProps and the root-route provider.
  • Guidelines. layering.md: a managed overlay renders beside the app, so it stacks above its opener but neither scales it back nor closes with it; OverlayProvider joins its front matter. confirmation-dialogs.md: the managed alternative to one open state per dialog, a tsx example of the dialog, its definition, the root-route provider and an opener (body and footer left as a comment), and OverlayProvider in its front matter. rules.md is unchanged: it has no room under its 2000-character cap, and a root import of these names fails to compile anyway.
  • MCP. Search aliases dialog manager, drawer manager, overlay provider, use overlay and define overlay. budget.test.ts checks that useOverlay, defineOverlay, OverlayProvider and dialog manager find OverlayManager first, and that overlay still finds the Overlay backdrop.
  • Claude Design. OverlayManager joins CLAUDE_DESIGN.internal: no guide and no preview. build-docs.ts swaps its PROVIDERS set for a NO_GUIDE map that keeps a reason per component, and lists the OverlayManager story file as having no guide; build-docs.test.ts asserts both README lines. The exported README gives the reason: a hook-only API, and canvas scripts cannot run hooks (render Dialog or Drawer with open there). The code still ships in the canvas bundle; it uses no React 19-only APIs.
  • gen-ui. OverlayManager is excluded in coverage.test.ts as a provider.
  • Type tests. New tsconfig.typetest.json checks the misuse cases in OverlayManager.types.test.ts (@ts-expect-error), imported from the public entry so every type it names is pinned as exported, and a two-module declaration-emit fixture (declaration: true). The design-system typecheck script now runs it.
  • Test ids and e2e rules. A row in docs/test-id-pattern.md and a bullet in docs/e2e-test-rules.md: a closing managed overlay stays mounted while it animates out, so a reopen can briefly match its test id twice. Wait for the closing content to hide. The e2e rules also say to hover a menu item and let a frame pass before asserting where focus returns.
  • Stories and e2e. Overlay/OverlayManager: Confirm Dialog, From Menu Item, Stacked Overlays and Unsaved Changes Guard, closed by default, with the provider in meta.decorators. OverlayManager.e2e.ts has 9 tests, 2 of them screenshots. The exit animation and a drawer closed from outside taking its managed dialog along are unit tests instead: a 150 ms window would be flaky in e2e, and Storybook has no URL-driven drawer.
  • Storybook docs. docs/storybook-docs-coverage.md: the OverlayManager row, 4 of 4 stories (99 of 120 pages). docs/storybook-docs-findings.md: a new open finding with its cause, focus on body after a Dialog opened from a menu item picked in its highlight frame. Two storybook-docs skill refinements in its REFINEMENTS.md.
  • Design doc. docs/superpowers/specs/2026-11-17-overlay-manager-design.md. Its as-built note lists where the build differs from it: no rules.md line, two e2e cases moved to unit tests, the StrictMode cleanup test runs with a Dialog only, the double-click window, onError inheritance, the props check, the stuck-exit checks, and focus after a menu item.

Spec review

A claim-by-claim review of the spec against the code (806 claims, with probe tests) found these, now fixed here:

  • Focus after a chained close went to body: if (await confirm.open()) controller.close(), the stories' delete and unsaved-changes flows, landed both closes in one commit. Fixed by notifying before settling.
  • A nested provider's errors skipped the app's onError. It now inherits the enclosing handler.
  • Types: components without controller (no props, optional props only) or with a key prop compiled; OverlayOpenArgs was not exported; OverlayPayload/OverlayResult rejected a definition type; a payload union with a member that needs no keys was required.
  • A payload that throws when read made open() reject and cancelled the open it was meant to replace.
  • An <Activity> hide and reveal left the body scroll lock on.
  • Docs: the TanStack key (id carries loaderDeps), Suspense inside the content, the success toast inside the overlay, effect re-runs on reveals, transitions, nested-provider keying, preloading inner overlays, stacking order, the 1 s fallback, and the corrected facts in the spec.

Test plan

  • Rstest, full design-system suite on 58989f3, the last code change (11f88c2 changes comments only): 326 files passed (2 skipped), 4086 tests passed (37 skipped). One retry, under parallel load, in a FileUpload test this PR does not touch
  • OverlayManager folder on the final head: 66/66, no retries; the new focus and <Activity> tests passed 5 runs in a row on their own
  • pnpm lint (it skips packages/mcp and packages/gen-ui, which have no lint script) and pnpm typecheck across the repo; the design-system typecheck script ends with tsc -p tsconfig.typetest.json (the type tests). tsc -p tsconfig.unit.json reports nothing in OverlayManager's test files
  • compiler:audit: no OverlayManager bailouts
  • Build: dist/components/OverlayManager/index.js and index.d.ts; no OverlayManager stories, tests or fixtures in dist
  • MCP test:run (206 passed, including the real-metadata budget.test.ts cases, which need the build and are skipped in CI), Claude Design test:export (129 passed), gen-ui coverage (3 passed), website build and check:build (generates overlay-manager.mdx)
  • All 4 stories checked interactively in Storybook during development (Chromium, driven through Playwright MCP, not the e2e suite)
  • Baselines for the 2 new screenshot tests regenerated by [update-screenshots] (003f0cc, only those 2 PNGs)
  • CI green on the final head 11f88c2 (run 44350474173). Four e2e tests passed on a retry: Drawer.e2e.ts:297, whose fix is in fix(drawer): fire onExitComplete when overlay turns off mid-fade #517, and the Escape tests of HoverCard, OverflowList and Popover, which this PR does not touch (HoverCard's also flakes on main)

🤖 Generated with Claude Code

@ipwallarm
ipwallarm added this pull request to stack #515 November 18, 2026 11:21
Base automatically changed from feat/drawer-exit-complete to main November 18, 2026 11:30
ispashkov and others added 24 commits November 18, 2026 15:30
Design for opening the same Dialog or Drawer from anywhere in an app,
with lazy-loaded overlay code: one OverlayProvider per app, store-free
defineOverlay definitions and a useOverlay hook. onExitComplete on
Drawer and Dialog ships first, as a separate feat branch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Public types for overlay definitions (OverlayProps, OverlayController,
OverlayPayload, OverlayResult), a lazy defineOverlay whose loader is cached
per definition, and a typetest tsconfig wired into the typecheck script.
Records OverlayManager as a provider in the gen-ui coverage decisions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The single-file fixture kept the props interface next to the defineOverlay
call, where the emitted .d.ts can always name it, so it passed even with a
plain Omit. Move the props and the component to HiddenDialog.fixture.tsx so
the check fails with TS4023 when the definition type needs the interface.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… synchronously

A non-async loader that threw escaped load() and preload() as a synchronous
exception, breaking the invariant that open() and preload() never throw or
reject. Calling the loader inside new Promise keeps it synchronous and turns
a throw into a rejection, which clears the cache so the next call retries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A framework-free store, created per provider, that owns every overlay instance.
Each open() promise settles exactly once: on close, failure, a closeOnChange
sweep or detach. A loading open stays out of the snapshot until its code
arrives, and a closed instance is dropped on its exit signal or after
REMOVE_FALLBACK_MS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tion

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The provider hands closeOnChange to the store in a layout effect, so a new page's
mount useEffect in the same commit opens its overlays after the sweep. The store
ignores a key it already holds, so a StrictMode replay or a Suspense reveal that
re-runs the effect closes nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…oke test

StrictMode's replay detaches the store before it re-runs the layout effect, so the
test cannot catch a missing same-key guard. Say so above it and point at the tests
that do pin the guard.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ssion

Four stories under Overlay/OverlayManager (confirm dialog, from a menu item, stacked
overlays, unsaved-changes guard) open real overlays from stories/: a confirm dialog, an
edit drawer and an unsaved-changes guard. docs/usage.md covers set up, the overlay
contract, opening, nesting and limits, including the two closeOnChange edges: a layout
effect that opens in the commit of a key change is swept, and a key that goes from
undefined to its first value counts as a change.

The manager is a hook-only, app-level API, so Claude Design gets no guide and no preview
for it: it joins CLAUDE_DESIGN.internal, build-docs maps it to a reason in NO_GUIDE and
lists its story file as not synced. OverlayProvider, defineOverlay and useOverlay still
reach window.WallarmDS through the bundle, as ThemeProvider does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…cker

The page leads with what the manager does and ends on a plain controlled Dialog as the
alternative, and each of the four stories carries one sentence. Checked against the code
and the rendered stories in Storybook. None of the six reference systems that fetched
documents an imperative manager, and each drives its dialog from local state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… refinements

A dialog opened from a menu item ends with focus on body, with or without the manager, so
the usage doc says that and the findings file records the gap. Two one-line rows record
friction with the storybook-docs skill on a hook-only component.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Layering says a managed overlay stacks above but neither scales its parent back nor closes
with it, and where a drawer mounts its own OverlayProvider. Confirmation dialogs gain a
Managed confirmation rule with one delete example and list OverlayProvider.
MCP search gets five aliases (dialog manager, drawer manager, overlay provider, use overlay,
define overlay), so the four new queries rank OverlayManager first through an alias; three
of them already did through its description, and only dialog manager lost to Dialog.
The test-id and e2e docs note that two instances of one definition can briefly share an id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…on snippet

The snippet's comment said a failure keeps the dialog open and shows an error toast, but
handleConfirm had no catch, so a rejected mutation escaped as an unhandled rejection and
no toast showed. It now mirrors docs/usage.md: close on success, error toast on failure.
The change is inside the code fence, so the prose word count stays at 979.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… reject a sync loader throw

The provider's passive cleanup now calls store.release, which detaches one microtask later
unless attach runs first. StrictMode replays that cleanup on mount and when a Suspense
boundary above reveals the provider again, then re-runs the attach layout effect in the same
tick, so only a real unmount settles and drops the overlays. Before, the replay on a reveal
dropped every open overlay in development, and an open() from a child's layout effect met a
detached store.

store.open now starts the load inside the promise chain, so a loader that throws
synchronously, or a definition with no load (one not made by defineOverlay, such as a mock),
resolves undefined and reports through onError instead of rejecting.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…trictMode mount opens

usage.md now says that an overlay reads the context above OverlayProvider, not the opener's,
and where page data goes instead. The focus bullet keeps only what was observed (Chrome,
Safari, the menu-item case tracked in docs/storybook-docs-findings.md). The dismissal guard
reads "not while a request is pending or the form is dirty", and the mount-effect bullet tells
readers to ignore the first StrictMode run's undefined result.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ge's edge cases

OverlayRootProps, OverlayController.rootProps and .close, and OverlayProps.controller get short
JSDoc, which flows to MCP, the website and Claude Design. closeOnChange's JSDoc adds the two edge
cases usage.md documents: an undefined key that gets its first value counts as a change, and an
open() from a descendant's layout effect in the same commit as a change is closed with the rest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n copied

The guideline fence ended with useOverlay called at module scope, a top-level await, and the
name deleteUser reused for the overlay after naming the mutation. It now opens the dialog from
a handler inside a DeleteUserButton component, through deleteUserOverlay. The DialogContent
placeholder in both the guideline and usage.md failed tsc (TS2741, children missing); it now
renders the title and names loading={deleteUser.isPending} on the confirm button in its
comment. Fence-only: the guideline's prose stays at 979 of 1000 words.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…vider message

tsconfig.typetest.json sets declaration itself, so the TS4023 fixture no longer passes
vacuously if base.json ever drops it. The missing-provider test matches the message with an
anchored regex: a message with a trailing period now fails it, while the old substring
matcher passed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…scroll lock alone

After the fix the managed drawer releases the lock on close; the comment no longer claims the
test itself leaks it, only that a plain Dialog can after a Suspense hide and reveal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Delete the two completed implementation plans; the spec stays.
- Spec: mark it implemented and note the four places where the build
  differs from it, fix three paths, and drop the note about Jira keys.
- layering.md: list OverlayProvider in the front matter, since the new
  managed-overlay rule is about it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

This PR is included in version 4.20.0-rc-feat-modal-manager.1

ispashkov and others added 2 commits November 18, 2026 20:22
…s its drawer

close() settled the open() promise before it notified React, so a caller
that awaits a confirm and then closes the drawer below it, as in
`if (await confirm.open()) controller.close()`, landed both closes in one
commit. The traps then unwound bottom-up and focus fell to body. Notify
first and settle after, in close() and in the closeOnChange sweep: the top
overlay's close commits first, as with nested overlays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… onError

The documented nested provider inside a router-owned drawer's content takes
no onError, so its overlays' loader and render errors went to reportError
instead of the app's handler. A provider without onError now reports
through the enclosing provider's handler, and only the outermost one falls
back to reportError.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ispashkov and others added 6 commits November 18, 2026 20:25
…ey prop

defineOverlay constrained its inferred props, and when inference found no
props TS fell back to the constraint: a component with no props, or only
optional ones (a legacy dialog with `title?`), compiled as a definition
that takes no payload and can never close through the manager. The props
are now checked after inference, through a rest argument that a valid
component leaves empty, which also rejects a `key` prop React would take.

Also from the review:
- export OverlayOpenArgs, which UseOverlayReturn's signature uses, so a
  generic adapter over useOverlay can emit declarations;
- OverlayPayload and OverlayResult take a definition type too;
- a payload union with a member that needs no keys makes the payload
  optional.

The type test now imports from the public entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…oad throws

open() copied the payload inside the promise executor, after the replace
loop. A payload that throws when read (a revoked proxy, a throwing getter)
made open() reject, against its never-reject contract, and had already
cancelled the still-loading open it was meant to replace. Copy it first; on
a throw, report through onError and resolve undefined, replacing nothing.

Also pin that a replace leaves another definition's loading open alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…and reveals

An <Activity mode="hidden"> above the provider runs its passive cleanup,
so the store detaches and settles its overlays. detach also emptied the
snapshot, and on the reveal useSyncExternalStore saw the change and
unmounted the revived roots before zag had started them. zag's queued start
then locked body scroll with no cleanup left to release it. detach now
keeps the snapshot, and the re-attach drops the settled instances a
microtask later, after the roots started, so their unmount releases the
lock. The overlays are still dropped, as documented.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- a user dismissal, by Escape or DialogClose, resolves undefined and still
  plays the exit animation;
- an overlay that never renders its root stays pending until closeOnChange
  changes, and is dropped by the fallback;
- defineOverlay loads nothing until a load or preload;
- after a failed load, the next open() runs the loader again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
usage.md and the guidelines, from a claim-by-claim review of the spec:
- key closeOnChange on the leaf match's pathname, not its id, which
  carries loaderDeps and changes with a search param on the same page;
- code that suspends inside an overlay needs its own Suspense below the
  title;
- the success toast lives in the overlay, since a forced close resolves
  open() with undefined;
- an opening effect re-runs on a Suspense or Activity reveal in production
  too, so open on arrival once per mount with a ref;
- await open() outside transitions and form actions;
- close with a plain value, pass a plain-object payload;
- a nested provider keys on the value that drives the drawer, inherits
  onError, and also suits a Drawer that opens a Drawer;
- inner overlays are preloaded when the outer one mounts (the edit drawer
  story does it), so a dismissal during their load leaves no orphan;
- stacking follows load order, the 1 s fallback, the Activity limit, and
  errors that escape the per-instance boundary;
- focus from a menu item returns to the trigger except when the item is
  picked in its highlight frame, a zag menu issue now recorded with its
  cause in docs/storybook-docs-findings.md.

The spec's false facts are corrected (zag 1.45, Drawer->Drawer pairs in
core-frontend, the error-boundary scope) and its as-built note lists the
new deviations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The release JSDoc and the provider's comment said only a real unmount
detaches; an <Activity> hide runs the same passive cleanup. Also say why
OverlayPayload is a conditional type: declaration emit then expands it
instead of naming the props interface.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

This PR is included in version 4.20.0-rc-feat-modal-manager.2

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant