Skip to content

fix(dashboard): a touch tap no longer reveals hover content and loses its click - #17366

Merged
iamwhatever merged 1 commit into
mainfrom
fix/15341-touch-hover-reveal-gate
Oct 6, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/15341-touch-hover-reveal-gate

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On iPhone, one tap on an issue-radar reference, a hover-intent trigger, a document-outline tick, or a collapsed nav-rail row acts on the first try.

On iOS a tap replays mouseover/mouseenter before Safari decides whether to send the click. If a handler on that replayed event shows new content, either at once or from a single-shot timer of 400ms or less, WebKit treats the tap as a hover and drops the click. The user then has to tap twice. #14798 fixed this for useInstantTip and the paste-token chip. Four more sites still reveal content from onMouseEnter with no pointer-type check:

  • RefLink: the issue-radar hover card opens on a 320ms timer.
  • useHoverIntent triggerProps: opens on a 320ms timer. Consumers are in App.tsx, ChatPage.tsx and metricsReadout.tsx.
  • MarkdownToc: the outline flyout expands synchronously over the clickable ticks.
  • useNavTip: the collapsed nav-rail label mounts synchronously.

Why it matters

Every touch user on iOS loses the first tap on these controls. That covers reference links in issue and PR bodies, the session flyout toggle, the focus-mode peeks, the metrics button, outline ticks in long documents, and nav-rail rows when the rail is collapsed on a tablet.

Not a goal

  • FeedbackPill's openOnTap usage warning. fix(website): keep touch taps from opening InstantTip hints #14798 kept it on purpose, and replacing it with visible text or a confirm step needs a product decision (see the issue thread).
  • Refactoring useInstantTip onto the new hook. It already has the gate, and moving it would be churn with no behaviour change.

What changed (motivation → approach → change)

Symptom: a tap on these anchors does nothing the first time on iOS. Root cause: each site reveals content from React's onMouseEnter, which also fires for a tap's compatibility replay, inside WebKit's content-change window.

Approach: this applies the rule useInstantTip already ships (TOUCH_REPLAY_WINDOW_MS). The hook records the pointer type from the anchor's own pointerenter/pointerdown/pointerup, and the reveal is skipped while a touch tap's replay window is open. The pointer type comes from the event, not from the device, so a mouse on a touch laptop or tablet still hovers. A keyboard focus that arrives after the window still opens where it does today. I picked the smallest change that matches the existing pattern: one shared hook instead of four copies of the same ref logic.

  • New website/src/hooks/useTouchReplay.ts: returns fromTouch() and pointerProps, and reuses TOUCH_REPLAY_WINDOW_MS from InstantTip.
  • RefLink: scheduleOpen (shared by onMouseEnter and onFocus) returns early for a tap's replay, and pointerProps goes on the anchor.
  • useHoverIntent: scheduleOpen('hover') returns early for a tap's replay, and triggerProps carries pointerProps. ArrowDown (scheduleOpen('keyboard')) and the surface's onMouseEnter: cancelClose are untouched, so a card that did open can still be reached.
  • MarkdownToc: open returns early for a tap's replay. The <nav> is pointer-events-none, so a native listener on it would never fire. pointerProps uses React's synthesized pointer events instead, and those do reach the nav from the ticks.
  • useNavTip: showTip returns early for a tap's replay. The hook returns pointerProps, and both consumers (App.tsx NavItem and appRail.tsx) spread it on the row.

Backwards compatibility

Compatible: mouse hover, keyboard focus and ArrowDown behave exactly as before. Only a touch tap's replayed enter (and the focus its mousedown gives, within the same window) stops revealing. useHoverIntent's triggerProps gains three pointer handlers, and no consumer sets its own pointer handlers on those triggers.

Removes nothing: no API, key or behaviour that a mouse or keyboard user reaches is removed; the hook only adds a touch-replay check before each reveal.

Tests

  • website/src/test/touchTapReveal.test.tsx (new):
    • useHoverIntent: a replayed touch tap runs the trigger's click and never opens the surface. A mouse pointer still opens after HOVER_OPEN_MS, and ArrowDown still opens right after a tap.
    • useNavTip: a tap runs the row's click and mounts no label. A mouse enter still mounts it, and keyboard focus after the replay window still mounts it.
    • MarkdownToc: a tap on a tick runs its click (the tick lights) and the flyout stays collapsed. A mouse enter still expands it.
  • website/src/test/IssueRadarRefSheet.test.tsx: a tap opens the reference and the hover card never mounts, including at the point where WebKit waits out the replay timer. A mouse pointer still opens the card after 320ms.
  • Each tap test replays pointer events, then mouseenter, then click. I checked that all four tap tests fail with the gate disabled (fromTouch forced to false) and pass with it on.
  • I also ran the existing useHoverIntent.test.ts, cursorAway.relay.test.ts and focusChrome.fullscreenReserve.test.ts: 88 tests across the five files pass. eslint and tsc -p tsconfig.app.json are clean.
  • .github/coverage-baselines/frontend.txt: dropped the MarkdownToc.tsx entry, because the new tests lift it to 82.8%, above the 80% floor (Coverage Gate asked for the removal).

Manual verification

Not run on a real iPhone. The jsdom tests replay the event order a tap produces. On-device confirmation would mean one tap on each of these controls in iOS Safari.

Screenshots / video

Why no screenshot: Nothing renders differently; the change only stops a touch tap's replayed mouseenter from opening content, which a still image cannot show.

Related Issues

Fixes #15341

Pattern harvest

Rule candidate: lint
Pattern: a React onMouseEnter handler that reveals content (state set or a timer of 400ms or less) without a touch-pointer gate costs the tap its click on iOS. A lint rule could flag onMouseEnter on an element that has an onClick or interactive children unless it goes through useTouchReplay/useInstantTip.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable): N/A, in-code comments only
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@chenmingwei23
chenmingwei23 requested a review from a team as a code owner October 6, 2026 11:51
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 6, 2026
@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of a4822b5fbb413ecb104ab6b39eaedf88e61a1f85 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Verify on a real iOS device that one tap on each control acts at once. The author did not run it on a device, and the jsdom tests only replay the event order.

[UX-REVIEWED] a4822b5

Description read

[DESCRIPTION-READ] da81338d25f099bc94bd5ffb30c1dbf715211c46e33e09b8fe369327b4027087

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of a4822b5fbb413ecb104ab6b39eaedf88e61a1f85 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The touch-replay rule now exists twice (useInstantTip and the new useTouchReplay), and the fix covers only four of about 55 onMouseEnter sites.

Not justified as shipped

  • Item 6 — duplicate of website/src/components/InstantTip.tsx:262: the new hook copies useInstantTip's inline touchUntilRef / notePointer logic. The description says "Refactoring useInstantTip onto the new hook" is a non-goal, so two spellings of one rule must now be kept in sync.
    Subtraction: export the existing pointer-type logic from InstantTip.tsx and have useTouchReplay reuse it, or have useInstantTip call the new hook. Either way the logic ends up in one place.
    Clears when: only one definition of the pointer-type window logic remains (today there are 2: InstantTip.tsx:262 and useTouchReplay.ts:27).
  • Item 7 — symptom-level: "Four more sites still reveal content from onMouseEnter", but I counted 55 onMouseEnter= occurrences across 37 .tsx files. I did not check which of them reveal content. Examples are McpInfoButton.tsx, SessionFlyout.tsx, PanelCard.tsx and ChatPanel.tsx. The description does not say how the four sites were chosen or what is left.
    Clears when: the description states why only these four sites qualify, or the other revealing sites are listed as deferred.

What this change ships

Inventory (7 items) — 5 justified

Intent: on iPhone, one tap on four hover-reveal controls should act on the first try. This is a FIX (Fixes #15341).

  1. A tap on an issue-radar reference no longer opens the hover card — justified
  2. A tap on a useHoverIntent trigger no longer opens its surface — justified
  3. A tap on a document-outline tick no longer expands the flyout — justified
  4. A tap on a collapsed nav-rail row no longer mounts the label — justified
  5. useHoverIntent triggerProps gains three pointer handlers — justified
  6. New useTouchReplay hook, duplicating useInstantTip's inline logic — duplicate of website/src/components/InstantTip.tsx
  7. Only four of the many onMouseEnter reveal sites are covered — symptom-level

[FIRST-PRINCIPLES-REVIEWED] a4822b5

Description read

[DESCRIPTION-READ] 4654749841b2904342383f468db0dc498f7b75c42d7b7ea0d37742f6f8b40962

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

Design-level review of a4822b5fbb413ecb104ab6b39eaedf88e61a1f85 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The fix's only claimed effect, restoring the first tap on iOS, was never confirmed on a device, and the jsdom tests can't show it.

Watch

Not verified on iOS: the description says "Not run on a real iPhone". The jsdom tests replay a hand-written event order, and nothing checks that WebKit sends pointerType: 'touch' on the anchor's own pointerenter/pointerdown/pointerup before the replayed mouseenter. MarkdownToc is the weakest case. It records pointer events on a pointer-events-none <nav> and relies on bubbling from the ticks. If a pointer event arrives after the replayed enter, or never reaches the <nav>, the flyout still expands and the tap is still lost, with no failing test. This is reversible.
Clears when: the description records one tap on each of the four controls (RefLink, a useHoverIntent trigger, a MarkdownToc tick, a collapsed nav row) in iOS Safari or a simulator, with the results.

[DESIGN-REVIEWED] a4822b5

Description read

[DESCRIPTION-READ] f6817a39989c5ba805ef0d06657f439a9383459d0e17c8e7c36f120cdd630ecf

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed a4822b5fbb413ecb104ab6b39eaedf88e61a1f85 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] a4822b5

Verdict parsed from the review's SHA-scoped output markers for commit a4822b5fbb413ecb104ab6b39eaedf88e61a1f85.

False positive or not applicable? A repository writer can comment:
/ai-review override fable a4822b5fbb413ecb104ab6b39eaedf88e61a1f85: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of a4822b5fbb413ecb104ab6b39eaedf88e61a1f85 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a4822b5

False positive or not applicable? A repository writer can comment:
/ai-review override gpt a4822b5fbb413ecb104ab6b39eaedf88e61a1f85: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 6, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/15341-touch-hover-reveal-gate branch from c65e3a4 to b91738f Compare October 6, 2026 12:41
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 6, 2026
… its click

On iOS a tap replays mouseenter before Safari decides to send the click,
and content that appears from that replay (at once, or from a timer of
400ms or less) makes WebKit read the tap as a hover and drop the click.
Four sites revealed from onMouseEnter with no pointer-type check:
RefLink's hover card, useHoverIntent's trigger, MarkdownToc's flyout and
the collapsed nav rail's useNavTip label.

Add useTouchReplay, the rule useInstantTip already applies: record the
pointer type from the anchor's own pointer events and skip the reveal for
a touch tap's replay window. A mouse on a touch device still hovers, and
keyboard focus after the window still opens. MarkdownToc records on the
nav through React's synthesized pointer events, because the nav itself is
pointer-events-none. useHoverIntent gates only the trigger's hover open;
the surface's cancel-close and the ArrowDown opener are unchanged.

FeedbackPill's openOnTap is left as is: it is a deliberate choice that
needs a product decision.

Fixes #15341
@chenmingwei23
chenmingwei23 force-pushed the fix/15341-touch-hover-reveal-gate branch from b91738f to a4822b5 Compare October 6, 2026 14:51
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 6, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a small, well-scoped fix. It moves the TOUCH_REPLAY_WINDOW_MS rule that useInstantTip already ships into useTouchReplay and applies it to the four sites that reveal content. Mouse hover, keyboard focus and ArrowDown are left as they were. I checked that pointer type is read per event, not per device, so a mouse on a touch laptop still hovers. The tap tests replay the pointer events, then the mouse events, then the click, and the description says they fail with the gate disabled, which is the right proof. Two non-blocking follow-ups: useInstantTip still has its own copy of the touchUntilRef/notePointer logic, so one should call the other to keep a single definition. And one tap on each control in iOS Safari would confirm the event ordering jsdom can't model, especially for MarkdownToc, where the pointer events bubble up to a pointer-events-none nav. No security surface is touched, and CI is green.

@iamwhatever
iamwhatever merged commit b8433c7 into main Oct 6, 2026
108 of 112 checks passed
@iamwhatever
iamwhatever deleted the fix/15341-touch-hover-reveal-gate branch October 6, 2026 16:41
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 6, 2026
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.

iOS: three more onMouseEnter reveals cost the tap's click

2 participants