Skip to content

feat(overlay)!: use native dialog and popover for dialogs and tooltips - #33

Merged
antfu merged 5 commits into
mainfrom
feat/native-overlays
Nov 18, 2026
Merged

antfu merged 5 commits into
mainfrom
feat/native-overlays

Conversation

@antfubot

@antfubot antfubot commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

The dialogs (OverlayModal, OverlayDrawer, OverlayConfirm) and tooltips (OverlayTooltip, v-tooltip) now use browser features instead of JS libraries. Before, the dialogs used reka-ui's Dialog (JS focus trap, Teleport, usePortalTarget) and the tooltips used vue-afloat (floating-ui + Teleport).

Dialogs are native <dialog>s opened with showModal(). The browser provides the top layer, the focus trap, the inert page and Esc-to-close.

  • Triggers and close buttons use invoker commands (commandfor + command="show-modal" | "close"). Where those are missing, a click fallback is wired.
  • closedby="any" closes the dialog on a backdrop click, with a small JS fallback. OverlayConfirm is a role="alertdialog" with closedby="closerequest", so Esc cancels it but a backdrop click doesn't.
  • Enter/exit animations are CSS only: @starting-style plus display/overlay transitions with allow-discrete.
  • Shared logic lives in useNativeDialog (composables/dialog.ts).

Tooltips are [popover] elements placed by CSS anchor positioning (position-area + position-try-fallbacks to flip at viewport edges).

  • They use popover="hint" where supported, and manual plus our own Esc handling elsewhere.
  • JS only wires hover/focus/click and the show/hide delays, until interestfor ships outside Chromium.
  • The tooltip stays open while hovered and closes on Esc (WCAG 1.4.13).
  • v-tooltip is our own small directive now. It appends the tooltip to the trigger's root node (the document body or the enclosing shadow root) and copies the dark/light scheme class.
  • Shared logic lives in bindTooltip / vTooltip (composables/tooltip.ts).

Because the top layer renders in place, these overlays no longer teleport. They can't escape a shadow root and need no z-index layers.

Why not depend on ui-sdk: @ui-sdk/core 0.1.0-beta.6 uses popover="manual" only to reach the top layer, then implements focus trap, inert and positioning in JS. It never calls showModal() and doesn't use anchor positioning. It is also a beta, 11 MB unpacked, and would overlap with reka-ui.

Browser floor

From MDN browser-compat-data 8.1.9 (Chrome / Firefox / Safari):

Feature Support Without it
<dialog>.showModal(), popover="manual", @starting-style 117 / 129 / 17.5 -
invoker commands (commandfor) 135 / 144 / 26.2 click fallback
CSS anchor positioning 125 / 147 / 26 tooltip is unpositioned
closedby 134 / 141 / 27.3 JS backdrop-click fallback
popover="hint" 151 / 153 / 27.3 manual + own Esc handling

Change map

Area Before After
OverlayModal / OverlayDrawer / OverlayConfirm reka Dialog / AlertDialog + Teleport native <dialog> via useNativeDialog
OverlayTooltip, v-tooltip in ActionIconButton / DisplayFilePath / DisplayDate vue-afloat native popover via bindTooltip / vTooltip
Styles vue-afloat.css, dialog keyframes in reka-ui.css tooltip.css (token @apply), dialog.css (transitions, ::backdrop, scroll lock)
Dependencies optional peer vue-afloat removed
z-index layers z-modal-*, z-drawer-*, z-tooltip in the example configs removed (the top layer sits above all z-index)

Breaking changes

  • OverlayModal, OverlayDrawer and OverlayConfirm drop the to prop. They render in place.
  • @antfu/design/styles/vue-afloat.css is gone. Import styles/tooltip.css and styles/dialog.css instead (styles.css already includes both).
  • OverlayTooltip's placement is now typed as TooltipPlacement (top, bottom-start, ...) instead of string.
  • The vue-afloat peer dependency is removed.

Visual changes

The look is meant to stay the same. Captured from Storybook on main and on this branch, in the same Chromium 158:

Before (main) After
Modal before modal after modal
Drawer (left) before drawer after drawer
v-tooltip, dark before tooltip after tooltip

The tooltip text is slightly smaller now, because it uses the token text-sm instead of vue-afloat's inherited size.

Boundaries and risks

Invariant Failure mode Protection Evidence
Overlays stay inside a shadow root styles lost outside the root top layer renders in place; v-tooltip appends to the root node portal.test.ts "native dialogs render in place", overlays.test.ts "stays inside an enclosing shadow root", ShadowRoot story checked in Chromium
v-model:open stays in sync Esc / backdrop / command="close" close without updating the model every close path ends in the dialog's close event, which sets open = false overlays.test.ts; Esc and backdrop checked in Chromium
Alert dialogs need a decision a backdrop click dismisses Confirm closedby="closerequest", no JS fallback wired overlays.test.ts; backdrop click checked in Chromium (stays open)
Page scroll is locked behind a modal the page scrolls behind the dialog light DOM: :root:has(...:modal) { overflow: hidden }; inside a shadow root (where :has() can't see): a counted JS lock in useNativeDialog measured overflow: hidden while open in both the Modal and ShadowRoot stories; overlays.test.ts covers nested dialogs and unmount-while-open

Known gaps (not blocking):

  • Firefox below 147 has no anchor positioning. There, tooltips show but aren't placed next to the trigger.
  • The tooltip uses aria-describedby. When the tooltip repeats an aria-label (e.g. ActionIconButton with the same label and tooltip), screen readers hear it twice.

User prompts

Claude Code (Opus 5.5) in Paseo.

  • Asked to use the latest browser features for dialog and tooltip instead of custom implementations, and whether to depend on ui-sdk.
  • Chose "baseline + small JS" as the browser floor, and a separate PR from main (independent of #32).

Verification

  • pnpm -F @antfu/design exec vitest run: 189 passed (new test/overlays.test.ts, reworked portal.test.ts and styles.test.ts)
  • pnpm run typecheck, pnpm run lint: clean
  • pnpm -F @antfu/design run docs:gen: idempotent over the committed docs
  • storybook build: succeeded
  • Manual checks in Chromium 158 (which supports command, closedby, popover="hint" and anchor positioning):
    • Modal: centered; :modal; focus moves inside; Esc and backdrop close it; a click inside doesn't; scroll lock toggles.
    • Confirm: opens through native commandfor with no JS handler; Cancel gets focus; a backdrop click is ignored; Esc closes it.
    • Drawer: all sides and the custom width are correct; the exit transition plays for about 220 ms before display: none.
    • Tooltip: 6 px above the trigger and centered; flips below near the top edge; v-tooltip picks up the dark scheme.
    • ShadowRoot story: the modal opens inside the shadow root with dark tokens; page overflow goes visible -> hidden -> visible across open and Esc.
    • No console errors.
  • Not verified: Firefox and Safari (no local browsers), and the click/closedby fallbacks in a real browser (they're only covered in happy-dom).

Written by Claude Code. The human set the direction (native features, no ui-sdk dependency, baseline + small JS) and hasn't reviewed the diff yet, so the reviewer is the first human to look.

OverlayModal, OverlayDrawer and OverlayConfirm are native <dialog>s opened
with showModal(). OverlayTooltip and v-tooltip are native popovers placed by
CSS anchor positioning. vue-afloat is no longer a dependency.

BREAKING CHANGE: the dialogs drop their `to` prop (they render in place in
the top layer), `styles/vue-afloat.css` is replaced by `styles/tooltip.css`
and `styles/dialog.css`, and the vue-afloat peer dependency is removed.
@antfu
antfu merged commit 0d63ec3 into main Nov 18, 2026
5 checks passed
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.

2 participants