An open source design system that's fully customizable and agent ready
TypeScript
spec(useMenuHover): contract hover-intent open, close, and the click guard (#6900)
Cindy Zhanga374e5c9ec4a
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.spec.md b/packages/core/src/DropdownMenu/DropdownMenu.spec.mdindex 488addd58c..47b0a4c8e2 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.spec.md+++ b/packages/core/src/DropdownMenu/DropdownMenu.spec.md@@ -21,7 +21,7 @@ verified_by:packages/core/src/Icon/Icon.test.tsx,scripts/check-knowledge.mjs,]-modules: [module:DropdownMenu/useMenuPress]+modules: [module:DropdownMenu/useMenuPress, module:DropdownMenu/useMenuHover]families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/DropdownMenu/modules/useMenuHover.spec.md b/packages/core/src/DropdownMenu/modules/useMenuHover.spec.mdnew file mode 100644index 0000000000..6a687ae818--- /dev/null+++ b/packages/core/src/DropdownMenu/modules/useMenuHover.spec.md@@ -0,0 +1,283 @@+---+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 current `main` and+ 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 `mouseenter` a 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:DropdownMenu` and 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 `useListFocus`+ and `useTypeahead`.+- Native light dismiss, Escape ordering across layers, and focus trapping —+ owned by `architecture:layer-runtime` and `family: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: false` gets 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-opened` after `showDelay` (FR1).+- **ORD3 — Provenance clearing.** Any close, whatever caused it, clears+ `hover-opened` and stamps the suppression window before the browser can+ hit-test the vanished panel; a confirm clears `hover-opened` without 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-modality` INV2).+- **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: false` and 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-modality` INV4). 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-modality`+ INV3).++## 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:DropdownMenu` owns 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`) only `DropdownMenu`+ has 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/useMenuPress` is 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-runtime` owns 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 synthetic `mouseenter` a closing+ panel produces. It also records that a control beside an open layer may+ temporarily gain `popovertarget` during a press and have its invoker toggle+ cancelled; FR11 is this hook's standing case of that relationship, not a+ second rule.+- `architecture:interaction-modality` owns modality state and the invariants+ AR1, AR4 and AR5 project; this record adds no modality definition.+- `family:overlay-dismissal` owns Escape ordering across layers; unchanged here.+- `SideNav` and `TopNav` have 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. `DropdownMenuSubMenu` takes 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 to `module:DropdownMenu/useMenuPress` as 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 to `module: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.