An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 3 kind: module id: module:DropdownMenu/useMenuHover authority: draft archive_reason: null superseded_by: null approved_by: null approved_at: null owners: [cixzhang] review_triggers: [behavior, interaction, accessibility] verified_by: [ packages/core/src/hooks/useMenuHover.test.tsx, packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx, packages/core/src/SideNav/SideNav.test.tsx, packages/core/src/TopNav/TopNavMenu.test.tsx, packages/core/src/TopNav/TopNavMegaMenu.test.tsx, ] parent_component: component:DropdownMenu references: [ architecture:layer-runtime, architecture:interaction-modality, module:DropdownMenu/useMenuPress,
]
useMenuHover module contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | None. useMenuHover is an internal shared hook; no consumer prop, export, or DOM contract of DropdownMenu, SideNav or TopNav changes. This record contracts behavior that already ships. |
| Behavior | A hover-capable pointer entering a trigger opens after showDelay and leaving closes a hover-opened surface after hideDelay; a pointer press on the trigger TOGGLES, except within clickGuardMs of a hover-open, where it confirms the surface instead. A surface opened by press has no such window. |
| End-user impact | A person whose cursor travels toward a row and clicks as the flyout appears under it keeps the flyout; the same person pressing the visibly open row a moment later closes it. A keyboard or touch user is unaffected: neither path has a hover phase and neither has a toggle. |
| Builder impact | None. clickGuardMs: 0 opts a surface out so every press toggles (SideNavItem does); showDelay: 0 opens on contact; ownsFocus: false leaves focus to the surface's own trap. |
| Compatibility/readiness | No behavior, API or default changes. Authority: draft — cixzhang settled the press-toggle rule and its guard exception on 2026-10-02 (DEC-1) and approves this record on its pull request. jsdom covers delays, the guard, focus and the invoker attribute; native light dismiss is browser-only. |
| Review checks | Reject a press that cannot close a surface the person can see is open; a guard armed by a press-open; a guard re-armed by re-entering an open trigger; hover as the only way to reach a surface; a hover-open that moves focus; a keyboard path that closes on its second activation. |
| Governing rules | architecture:interaction-modality INV2–INV4 (modality and focus ownership stay separate; one focus move has one indicator; every modality has an operable path and hover is never the only one); architecture:layer-runtime for the native invoker relationship and the synthetic-mouseenter note. |
This table is a review projection; the body below is authoritative.
Intent
Flyout menus on a desktop pointer are expected to follow the cursor: the surface
opens on hover intent rather than demanding a press, and closes when the pointer
goes elsewhere. useMenuHover is the one place that behavior is decided, so
sub-menus and nav flyouts do not each invent their own delays, their own guard,
and their own answer to "does a press close this?".
The behavior is shipped and has been for some time; what it has lacked is a record. An open proposal to delete part of it was reasonable precisely because nothing said the part mattered. This record contracts the hover-intent model — open, close, the press toggle, and the click guard — for every surface that mounts the hook.
It contracts the hover model only. The press model inside an open menu, menu anatomy, item semantics, directional keyboard navigation and layer dismissal stay with their own owners.
Compatibility and migration
- Released default preserved:
yes— this record describes currentmainand changes no runtime behavior, default, or signature - Compatibility class: documentation of shipped behavior; no API, default, or observable delta
- Migration decision: none required
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- Hover intent on a trigger: the delay before a hover opens a surface, and the delay before leaving the trigger or the surface closes one that hover opened.
- Whether a pointer press on the trigger opens, confirms, or closes — including the click guard and the window it runs for.
- Suppressing the synthetic
mouseentera closing panel fires when it stops covering a stationary pointer. - Standing down entirely on a pointer that cannot hover.
- Where focus goes on an open the hook performs, and returning it to the trigger on the hook's own close.
- The native invoker relationship (
popovertarget) for a trigger that sits outside an auto popover, and cancelling that invoker's default toggle so one handler decides.
Does not own / non-goals
- Aggregate menu anatomy, presentation resolution, item rendering and theming —
owned by
component:DropdownMenuand the owning nav components. - What a press does to a row INSIDE an open menu — owned by
module:DropdownMenu/useMenuPress. - Directional open and close keys (ArrowRight / ArrowLeft, and their RTL mirrors) — owned by the component that renders the trigger. The hook sees Enter and Space only, and only because the browser delivers them as a click.
- Typeahead and roving navigation within a surface — owned by
useListFocusanduseTypeahead. - Native light dismiss, Escape ordering across layers, and focus trapping —
owned by
architecture:layer-runtimeandfamily:overlay-dismissal. - Positioning, anchoring and collision behavior — owned by
useLayer. - Whether a surface exists at all for a given trigger: a consumer that passes
isEnabled: falsegets inert handlers and no hover behavior.
Public API and concepts
| Concept | Closed values or states | Meaning | Default | Owner | Stability |
|---|---|---|---|---|---|
| open provenance | hover-opened, pinned |
how the current open began; only a hover-opened surface closes on pointer leave, and only it arms the click guard |
from the event that opened | module:DropdownMenu/useMenuHover |
stable |
showDelay |
milliseconds, 0 opens on contact |
hover intent before opening | 150 |
module:DropdownMenu/useMenuHover |
stable |
hideDelay |
milliseconds | grace after leaving the trigger or the surface before a hover-opened surface closes | 200 |
module:DropdownMenu/useMenuHover |
stable |
clickGuardMs |
milliseconds, 0 opts out |
window after a hover-open in which a press confirms the surface instead of closing it | 500 |
module:DropdownMenu/useMenuHover |
stable |
| reopen suppression | fixed window after any close | a mouseenter arriving because the panel stopped covering a stationary pointer is ignored; a real pointer leave clears it early |
300 ms, not configurable |
module:DropdownMenu/useMenuHover |
stable |
| hover capability | (hover: hover) matches, or does not |
whether hover intent is read at all; a coarse pointer schedules nothing | from the media query | architecture:interaction-modality |
stable |
ownsFocus |
true, false |
whether the hook moves focus on a press or keyboard open, or leaves it to the surface's own trap | true |
module:DropdownMenu/useMenuHover |
stable |
popoverId |
a popup's DOM id, or absent | present makes the trigger the panel's native invoker, exempting it from light dismiss; the hook then cancels the invoker's own toggle | absent | architecture:layer-runtime |
stable |
| integration shape | full, or pointer-only | a consumer takes the whole model, or takes hover intent plus confirmHoverOpen and keeps its own press and keyboard handling |
full | module:DropdownMenu/useMenuHover |
stable |
Behavioral contract
| ID | Candidate invariant | Basis | Draft review state |
|---|---|---|---|
| FR1 | A hover-capable pointer entering an enabled trigger MUST open the surface after showDelay, and MUST NOT move focus: the pointer is driving. showDelay: 0 opens on contact. |
Current behavior; useMenuHover.test.tsx, SideNav.test.tsx |
settled |
| FR2 | Leaving the trigger or the surface MUST close a hover-opened surface after hideDelay; entering the surface MUST cancel a pending close. A pinned surface MUST NOT close on a pointer leave. |
Current behavior; useMenuHover.test.tsx, SideNav.test.tsx |
settled |
| FR3 | A pointer press on the trigger MUST toggle the surface: it opens a closed one and closes an open one. This is the default answer, and FR4 is its only exception. | DEC-1; useMenuHover.test.tsx, DropdownMenuSubMenu.test.tsx |
settled |
| FR4 | A press landing within clickGuardMs of a HOVER-open MUST confirm that surface instead of closing it, pinning it (FR2) and moving focus in where the hook owns focus. After the window, a press MUST close it. clickGuardMs: 0 opts out, making every press toggle. |
DEC-1; useMenuHover.test.tsx, DropdownMenuSubMenu.test.tsx |
settled |
| FR5 | The guard MUST key off the hover-open, never off the open. A surface opened by a press therefore has no window at all and the next press closes it immediately. This is the rule's intended consequence, not an edge case. | DEC-1; useMenuHover.test.tsx click-only and re-entry cases |
settled |
| FR6 | Re-entering the trigger of an already-open surface MUST NOT re-arm the guard and MUST NOT make the surface hover-opened again; otherwise the next deliberate press would confirm forever and the surface could never be dismissed by pointer. |
Current behavior; useMenuHover.test.tsx re-entry case |
settled |
| FR7 | For a fixed window after ANY close, a mouseenter on the trigger MUST NOT reopen the surface, because a panel positioned over its own trigger puts that trigger back under a stationary pointer. A real pointer leave MUST clear the window early, so a deliberate re-hover still opens. |
Current behavior; useMenuHover.test.tsx suppression and re-hover cases |
settled |
| FR8 | Where (hover: hover) does not match, mouseenter and mouseleave MUST schedule nothing — a tap's compatibility mouseenter must not leave a surface hanging open behind it — and the press path MUST behave exactly as it does with a hover-capable pointer. |
architecture:interaction-modality INV4; useMenuHover.test.tsx, SideNav.test.tsx |
settled |
| FR9 | Keyboard activation of the trigger MUST always open the surface and move focus into it, and MUST NEVER close it. The keyboard has no toggle; the toggle of FR3 is a pointer affordance and nothing mirrors it on keys. | Current behavior; useMenuHover.test.tsx keyboard suite |
settled |
| FR10 | Escape MUST close the surface and return focus to the trigger when focus was inside it. Directional open and close keys are the consuming component's, not this hook's. | family:overlay-dismissal; useMenuHover.test.tsx, DropdownMenuSubMenu.test.tsx |
settled |
| FR11 | When a popoverId is supplied, the trigger MUST carry popovertarget for that panel, and the hook MUST cancel the resulting invoker toggle so its own handler is the single decision point for FR3 and FR4. |
architecture:layer-runtime; useMenuHover.test.tsx invoker case |
verify |
| FR12 | A disabled integration MUST add no hover behavior to its trigger, and MUST NOT open a surface: a trigger disabled while a hover is in progress stays closed, whether it was disabled before the pointer arrived or during the delay that would have opened it. | Current behavior; SideNav.test.tsx collapsed/expanded cases |
verify |
Transformation and precedence order
- ORD1 — Press resolution. Keyboard activation (FR9) → surface closed, so open → within the guard window, so confirm (FR4) → otherwise close (FR3). The first matching branch decides; none of the later ones runs.
- ORD2 — Hover-enter resolution. No hover-capable pointer, so do nothing
(FR8) → inside the reopen-suppression window, so do nothing (FR7) → already
open, so abandon any pending close and change nothing else (FR6) →
otherwise the surface becomes
hover-openedaftershowDelay(FR1). - ORD3 — Provenance clearing. Any close, whatever caused it, clears
hover-openedand stamps the suppression window before the browser can hit-test the vanished panel; a confirm clearshover-openedwithout closing.
Performance and resources
- PR1 — No pending intent outlives what supersedes it. At most one open and one close are ever pending; a newer intent replaces the pending one rather than queueing behind it, and nothing pending survives the surface unmounting. A trigger left behind by a removed surface cannot open it.
- PR2 — Nothing is observed outside the trigger and its surface. Hover intent is read from the trigger and the surface alone, so a page with many triggers carries no document- or window-level cost per trigger.
Accessibility contract
- AR1 — A hover-open never moves focus. The pointer is driving, so focus
stays where the person left it; the surface is reachable with the same pointer
that opened it. This keeps modality and focus ownership separate
(
architecture:interaction-modalityINV2). - AR2 — A press or keyboard open moves focus in, synchronously. Where the
hook owns focus it focuses the first enabled item in the same tick, falling
back to the surface container when the surface is empty or still loading, so
keyboard ownership always leaves the trigger's list. A consumer whose surface
is a focus-trapped dialog rather than a menu passes
ownsFocus: falseand the trap owns focus instead. - AR3 — Closing returns focus to the trigger. When focus was inside the surface, the hook's own close returns it to the trigger, so Escape never strands a keyboard user on a vanished element.
- AR4 — Hover is an enhancement, never a requirement. Every surface this
hook opens MUST remain reachable and dismissible by press and by keyboard,
with no hover phase involved (
architecture:interaction-modalityINV4). A coarse pointer gets the press path unchanged (FR8). - AR5 — One highlight per focus move. The hook moves focus to exactly one
item and paints nothing itself; a surface that also highlights on hover keeps
that highlight and focus in one place (
architecture:interaction-modalityINV3).
Design relationships
| Anatomy or state | Design requirement | Representation authority | Module contract |
|---|---|---|---|
| open surface | No visual representation is introduced; the surface's own appearance is the owning component's | prescribed | FR1, FR3 |
| focused item | The existing focus highlight owned by the item components; this module only decides which item has it | prescribed | AR2, AR5 |
Parent and system relationships
component:DropdownMenuowns aggregate menu anatomy, presentation resolution and the item pipeline. This module is parented there because the repository's knowledge-path rules require a module record to live under a component root with an active component record and to be listed by it; of the three roots that consume the hook (DropdownMenu,SideNav,TopNav) onlyDropdownMenuhas one, and the sibling press model is already parented there on the same basis. The contract governs every consumer, not sub-menus alone.module:DropdownMenu/useMenuPressis the sibling press model and the boundary is exact: it decides what a press does to a row INSIDE an open menu; this record decides what a press on a TRIGGER does to the surface itself. Neither governs the other's surface.architecture:layer-runtimeowns the layer lifecycle, native light dismiss, and already records that this hook adds a real native invoker relationship for applicable auto popovers and suppresses the syntheticmouseentera closing panel produces. It also records that a control beside an open layer may temporarily gainpopovertargetduring a press and have its invoker toggle cancelled; FR11 is this hook's standing case of that relationship, not a second rule.architecture:interaction-modalityowns modality state and the invariants AR1, AR4 and AR5 project; this record adds no modality definition.family:overlay-dismissalowns Escape ordering across layers; unchanged here.SideNavandTopNavhave no component record yet. When either gains one, it names this module rather than restating the hover model.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation |
|---|---|---|---|
| FR1–FR2, FR5–FR7, FR9, FR10 | useMenuHover.test.tsx, driven through a real consumer rather than a synthetic harness |
hover-open, leave-close, immediate press, press well after the window, press-only toggle, trigger re-entry, panel-vanish enter | Removing the guard fails the immediate-press case; widening it to press-opens fails the re-entry and click-only cases |
| FR3–FR5 | DropdownMenuSubMenu.test.tsx hover/click-guard suite |
flyout hover-opened then pressed at once; flyout hover-opened then pressed after the window | A press that can never close a visibly open flyout fails the second case |
| FR1, FR2, FR8, FR12 | SideNav.test.tsx collapsed sub-menu hover-intent suite |
fine and coarse pointer, delay boundaries, unmount during a pending open, clickGuardMs: 0 consumer |
A coarse pointer that schedules a timer, or a disabled item that still hovers open, fails |
| FR9, AR1–AR3 | useMenuHover.test.tsx focus and keyboard suites |
hover-open leaves focus; press-open focuses the first item in the same tick; Enter on an open surface; Escape | A deferred (post-paint) focus fails; a keyboard activation that closes fails |
| FR11 | useMenuHover.test.tsx invoker case asserts the wiring; the behavior is browser-only |
trigger outside an auto popover | jsdom implements neither light dismiss nor invokers, so the attribute is asserted and the dismissal is not provable |
| AR4 | Press and keyboard paths in every suite above | every consumer, hover unavailable | A surface reachable only by hover fails architecture:interaction-modality INV4 |
Decision log
DEC-1 — A press toggles, except the one that follows a hover-open
Reference: module:DropdownMenu/useMenuHover/DEC-1
Decider: cixzhang, 2026-10-02
A press on a sub-menu row toggles the flyout, with one exception: a click landing immediately after a hover-open does not close it.
The hover and the click are one continuous motion, not two decisions. The person moves the cursor toward the row, the flyout opens under the cursor mid-travel, and the click they had already committed to lands on something that just appeared. The guard window recognises that the click was aimed at the closed row, so it confirms the surface rather than undoing it.
After the window, the situation is different: the person is pressing something they can see is open, and that is a second deliberate press. It should close it — "after waiting for a bit clicking the menu toggle again should close it", and "we should preserve that behavior".
This is why the guard keys off the hover-open and not off the open (FR5): a
surface the person opened by pressing was never the ambiguous case, so the next
press closes it with no window at all. A consumer whose surface does not appear
under the travelling cursor — one that opens beside the rail rather than over
the trigger — has no ambiguity to resolve and sets clickGuardMs: 0.
Open questions
OQ1 — One consumer resolves the press rules itself. (
checkable) Five of the six consumers take the whole model.DropdownMenuSubMenutakes hover intent alone and resolves FR3 and FR4 in its own press handling, so the rule exists in two places and the two can diverge. The owner's direction is to converge: every consumer should get FR3 and FR4 from one place. What a press does to a menu row that is also a menu item is the open part, because that row answers tomodule:DropdownMenu/useMenuPressas well; the behavior both shapes must produce is settled either way.OQ2 — Keyboard activation is not reliably distinguishable. (
checkable) FR9 requires a keyboard activation to open and never close, which depends on telling it apart from a pointer activation on the same trigger. A trigger that also hosts a model dispatching its own activations cannot be told apart by the signal the browser gives a keypress, so FR9's guarantee does not hold there. No shipped surface is affected, because the one row hosting both keeps its own press handling (OQ1) — but converging OQ1 makes this reachable, and the two should be settled together. What a dispatched activation should look like belongs tomodule:DropdownMenu/useMenuPress, not here.
Content boundary
This record does not duplicate the hook's signature or option defaults as authored in source, the owning components' anatomy, theming or item semantics, the press model inside an open menu, layer positioning and dismissal rules, or implementation steps. It links to their canonical owners.