refactor(overlay): extract generic overlay coordination; drop dom-dialog - #29
Merged
Conversation
The layer stack, assistive-tech containment, exit window, and initial focus were never dialog-specific — only their names were. Extract them so the whole overlay family (drawer, alert-dialog, popover, menu, combobox) builds on one implementation: - @dunky.dev/overlay (core/utils) — the agnostic half: a stack of open layers and the topmost rule (deepest nesting, open order breaking ties). No DOM, no framework, so a future native substrate reuses it. - @dunky.dev/dom-overlay — the DOM realization on top: the stack wired to aria-hidden/inert containment, hideExitingLayer/watchExitAnimation, and getInitialFocus. @dunky.dev/dom-dialog is removed (never released); @dunky.dev/react-dialog now consumes @dunky.dev/dom-overlay (registerDialog/isTopmostDialog become registerLayer/isTopmostLayer). Public API and behavior unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
5 tasks
The prose bullets leaked function names and DOM mechanism literals that drift from the code. Keep the names in the Usage example; describe behavior above it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The overlay family — dialog, drawer, alert-dialog, popover, menu, combobox — shares one coordination problem: when overlays stack, which layer is topmost? The topmost owns Escape, the focus trap, and (when modal) assistive-tech containment. That behavior lived inside
@dunky.dev/dom-dialog, named as if it were dialog-specific — but nothing about it is. This extracts it so every upcoming overlay primitive builds on one implementation instead of growing its own.Two new packages, split along the one seam that actually matters — agnostic decision vs. host effect:
@dunky.dev/overlay(core/utils/overlay) — the agnostic half: a stack of open layers and the rule for which is topmost (deepest nesting, open order breaking ties). No DOM, no framework. A future native substrate reuses it unchanged; only the containment/effects get rewritten per host.@dunky.dev/dom-overlay— the DOM realization on top of the kernel: the layer stack wired toaria-hidden+inertcontainment, the exit window (hideExitingLayer/watchExitAnimation), and initial focus (getInitialFocus).@dunky.dev/dom-dialogis removed — it was never released (no CHANGELOG, still0.0.0), so this is a clean deletion, not a breaking change to consumers.Supersedes #16, which extracted along different lines against a since-reworked dialog and had gone stale (conflicting, built on
src/utils/stack.tsthat no longer exists).Changes
@dunky.dev/overlay—createLayerStack+topmost/isTopmost, generic over the layer payload.@dunky.dev/dom-overlay—registerLayer/isTopmostLayer(containment sync on stack change),getInitialFocus,watchExitAnimation,hideExitingLayer.@dunky.dev/react-dialogconsumes@dunky.dev/dom-overlay(registerDialog→registerLayer,isTopmostDialog→isTopmostLayer). Public API and behavior unchanged.@dunky.dev/dom-dialogand its never-released changeset; repointed the exit-animation changeset to@dunky.dev/dom-overlay.tsconfig.json,tsdown.config.ts, lockfile) and a changeset.Kept deliberately simple: depth-based topmost as today (no speculative path/interact-outside), containment behavior byte-for-byte preserved.
dom-focus-trapis untouched.Test plan
pnpm test:ci— 135 tests, 11 files, all passingpnpm typecheckpnpm lintpnpm format:checkpnpm build— publint clean for all packages, including the two new ones🤖 Generated with Claude Code