Skip to content

UN-4315 [FEAT] Add the v1 overlays: Drawer, Popover, HoverCard and Tooltip (P1-T08) - #2522

Open
kirtimanmishrazipstack wants to merge 10 commits into
mainfrom
UN-4315-v1-overlays
Open

kirtimanmishrazipstack wants to merge 10 commits into
mainfrom
UN-4315-v1-overlays

Conversation

@kirtimanmishrazipstack

@kirtimanmishrazipstack kirtimanmishrazipstack commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

What

  • Adds the drawer, popover, hover card and tooltip to the new (v1) frontend, and the parts the drawer and the dialogs (UN-4316) share:
    • Drawer: a right-hand panel, 480 or 640 wide, with a header and close button, titled sections and an action bar. Loading and error are its body content.
    • Popover: a small panel that can hold buttons and fields.
    • Hover card: a preview shown on hover or keyboard focus.
    • Tooltip: a short text label.
  • Toasts now sit above drawers and dialogs, so a toast one of them raises is visible and can be clicked.

Why

  • The design asks for one overlay behaviour (P1-T08 spec). The app shell, list pages and notifications inbox build on it.

How

  • Lives in frontend/src/v1/components/ui/overlay/, built on Radix.
  • The drawer traps focus. The popover takes focus without trapping it. The hover card and tooltip never take it. Escape closes each one.
  • Focus return (returnFocus.ts): when a drawer or dialog closes, focus goes back to what opened it. If that sat in a menu, submenu or popover that has closed, focus goes to the control that opened that, and failing that to the page control that last had focus. This covers search-menu and command-palette rows and confirms chained one after another.
  • The drawer leaves out Radix's Dialog.Overlay, which is what locks page scroll, and draws its own dim layer, so the page behind keeps scrolling.
  • Shared parts (parts.tsx): the dim layer, the header (with titleSize for confirms), the action bar, and the Escape and outside-click rules (a filled search box clears first; nothing closes while busy).
  • feedback/Toaster.tsx: the toast list moves from z-50 to z-1600, above every overlay (v0 pins Radix popper wrappers at 1500), and takes clicks while it holds a toast, so a click on an older toast never reaches the drawer under it.
  • A tooltip takes text only, so it can't hold anything interactive.

Can this PR break any existing features. If yes, please list possible items. If no, please explain why. (PS: Admins do not merge the PR without this section filled)

  • Low risk. The overlays are new and nothing uses them yet. The one change to existing code is the Toaster: toasts now sit above every v1 overlay, menus and the command palette included, and the toast list takes clicks while it shows toasts. The Toaster's own tests pass unchanged.

Database Migrations

  • None.

Env Config

  • None.

Relevant Docs

Related Issues or PRs

  • Jira UN-4315, epic UN-4257. UN-4316 (dialogs) builds on the shared parts. The shared component gallery comes with UN-4273.

Dependencies Versions

  • None.

Notes on Testing

  • Automated: every v1 check passes (types, lint, unit tests, seam, separation, bundle and build), 1,361 v1 tests. The overlay tests cover focus trap, focus return from every kind of opener, Escape, outside click, the busy state, toasts over a drawer, the hover delays, and an accessibility scan of every gallery entry. Each focus and toast fix was mutation-checked.
  • By hand in Brave, in Light, Dark and Unstract, on a temporary local page: every case in the table below.
  • Limits: while a drawer is open, the wheel scrolls the page as a whole, not a scroll area inside it. Focus lands on the page when the opener took no focus (a plain row) or was removed, and after a context-menu item; the README lists these.
  • Locally on Node 26, run test:v1 with NODE_OPTIONS=--no-experimental-webstorage.

For the designer:

  • The frames draw drawers 620 (A05, L07, L08) and 520 (C05) wide. The code uses the spec's 480 and 640.

Screenshots

Taken in Brave, light theme unless named.

# Case Screenshot
01 Drawer 480, focus on Close 01  Drawer 480, focus on Close
02 Drawer 640 with a logo 02  Drawer 640 with a logo
03 Drawer loading, error and busy 03  Drawer loading, error and busy
04 Page behind scrolls while the drawer is open 04  Page behind scrolls while the drawer is open
05 Escape clears a filled search box first 05  Escape clears a filled search box first
06 Toast raised from a drawer shows above it 06  Toast raised from a drawer shows above it
07 Focus back on the opener (menu, submenu, popover, search menu, command palette, chained confirms) 07  Focus back on the opener (menu, submenu, popover, search menu, command palette, chained confirms)
08 Popover with rows, popover with a search box 08  Popover with rows, popover with a search box
09 Hover card and tooltip 09  Hover card and tooltip
10 Dark and Unstract themes 10  Dark and Unstract themes

Checklist

I have read and understood the Contribution Guidelines.

🤖 Generated with Claude Code

The dim layer, header with close button, footer action bar, Escape and
outside-click rules, and focus return that the drawer and the dialogs
(UN-4316) share.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…oltip

The right-hand drawer (480 or 640, sections, action bar), popover, hover
card and tooltip, built on Radix and the shared overlay parts, with a
gallery, markup snapshot, accessibility scan and READMEs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kirtimanmishrazipstack kirtimanmishrazipstack added the main-only Stays on main: not backported to a release line label Nov 20, 2026
titleSize "page" (default) or "section" for confirm dialogs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@kirtimanmishrazipstack kirtimanmishrazipstack left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Standardized review (unstract review-deep v2.3.9): INITIAL, head 8efcef576

Verdict: REQUEST CHANGES

Summary: Critical: 0 · High: 2 · Medium: 6 · Low: 5 · Lenses run: 19/19

Overlay suite: 51/51 pass (vitest scoped to components/ui/overlay). The pinned biome check 2.3.13 (check-only) on the changed files: exit 0. Findings marked VERIFIED were reproduced with throwaway tests in a scratch copy; nothing in the branch was changed.

Findings (inline):

  1. [High] A toast raised while a drawer is open is hidden under it; Escape closes the hidden toast.
  2. [High] Focus drops to <body> after a drawer opened from a submenu or context-menu item closes.
  3. [Medium] A busy popover still closes on a trigger click.
  4. [Medium] The toast-click guard is never reached by a real toast; its test uses a fake one.
  5. [Medium] The gallery's loading and error drawer entries render the loaded body.
  6. [Medium] Drawer's own return-focus wiring is untested.
  7. [Medium] useReturnFocus(open) forces each overlay to keep private open state; UN-4316 already forked it.
  8. [Medium] Exported prop types accept asChild, forceMount and an empty title.
  9. [Low] Doc overclaims.
  10. [Low] A Tooltip provider per tooltip turns off skip-delay.
  11. [Low] Tooltip drops props from an asChild parent.
  12. [Low] Two prop-forwarding paths are untested.
  13. [Low] Hover-delay tests tie the fake clock to wall time.

Lens checklist

  1. Spec & intent: See findings #2, #3, #5
  2. Architectural fit & precedent: See findings #7, #10
  3. Correctness & edge cases: See findings #1, #2, #3, #4, #11
  4. Security: Clean (no endpoint, no HTML sink, tooltip content is text only)
  5. Data integrity & migrations: N/A (no data write, schema or migration)
  6. Concurrency: Clean
  7. API & contract compatibility: See findings #8 (consumer searched: the UN-4316 dialogs worktree imports the shared parts; no other consumers)
  8. Reliability & resilience: N/A (no external call, timeout, retry or queue)
  9. Performance & cost: Clean
  10. Observability: N/A (no log, metric or error-reporting path)
  11. Operational safety: Clean (no page uses the components yet)
  12. LLM/agent-specific: N/A
  13. Testing: See findings #4, #5, #6, #12, #13
  14. Dependencies & build: Clean (no manifest change)
  15. Code quality: Clean (pinned biome check and check-v1 pass)
  16. Doc & comment accuracy: See findings #2, #3, #4, #9
  17. Cross-document rule consistency: Clean (branch current with base; every repo-wide restatement of these rules agrees)
  18. On-prem deployment experience: N/A (no chart, values file, on-prem path or doc)
  19. Scaling & workload lifecycle: N/A

Not checked

  • Real-browser paint and hit-testing for #1 and #4. Page order, stacking classes and Escape were checked in happy-dom.
  • The global coverage threshold. Only the overlay folder's suite ran.

Open questions for the author

  • Should toasts always sit above, and stay clickable over, an open drawer or dialog? The fix for #1 and #4 depends on it.
  • Is a drawer meant to open from RowContextMenu, submenu items or a popover button? If not, should the README list them as cases where focus is not returned?
  • Will list-page rows be focusable? README.md:36-38 says focus goes "back to that row", which holds only for a row that takes focus.

Assumptions

  • The Toaster stays mounted once at the v1 root into #v1-portal, ahead of any drawer.

Toasts sit above drawers and dialogs; focus returns through submenus and
popovers; the drawer passes its open state straight to Radix; content and
title props reject values that break; Tooltip forwards a parent's props;
the gallery's loading and error drawers show their own bodies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When one overlay closes and the next opens in the same task, keep the
first opener and ignore the late close, so focus goes back to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kirtimanmishrazipstack

Copy link
Copy Markdown
Contributor Author

Answers to the review summary and Sonar (the thread fixes are in 13bd958):

  • Toasts over an open drawer or dialog: yes. The toast layer now sits above overlays, and a toast raised from one is visible and clickable. Escape closes the newest toast first.
  • Drawers opened from submenus, popovers and context menus: a submenu or popover opener now gets focus back at the control that opened it. A context-menu item has no such control, and the README says so.
  • Focusable rows: the README no longer promises a row. Focus goes back to the control that opened the drawer.
  • Sonar's two new issues (gallery helper props not read-only): fixed in 1aaea3a.
  • Also in this round: 377e48b keeps focus return working when one overlay closes and the next opens in the same task, as chained confirms do (asked for by the dialogs ticket, UN-4316).
  • Tested: all v1 checks pass (1,353 v1 tests). Each new guard was broken on purpose and its test failed. No browser check this round.

@kirtimanmishrazipstack kirtimanmishrazipstack left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Standardized review (unstract review-deep v2.3.9): FOLLOWUP, head 1aaea3a5c

Verdict: REQUEST CHANGES

Summary: Critical: 0 · High: 2 · Medium: 2 · Low: 4 · Lenses run: 19/19

The counts are what is still open after this round: new findings 1-5, plus what is left of prior #2 (High), #9 (Low) and #12 (Low).

Prior context fetched: followup-fetch.sh exit 0. Since-boundary: 8efcef576 (the INITIAL review). Commits reviewed since: 13bd95816, 377e48b24, 1aaea3a5c.

Scope change: YES. Focus return was redesigned: the opener is now resolved at open time by walking menu and popover layers. 377e48b also adds new close-and-reopen behaviour. Re-scanned the 15 files changed since 8efcef576 under all 19 lenses.

Overlay suite: 61/61 pass (vitest on components/ui/overlay; no outside service needed). Pinned biome check 2.3.13, check-only, on the 14 changed source files: exit 0. The fixes were checked by mutation in a scratch copy; the branch was not changed.

Prior findings status

  • #1 [High] A toast raised while a drawer is open was hidden under it → RESOLVED. The viewport is ui:z-60 (feedback/Toaster.tsx:137), pinned by Drawer.test.tsx:189; the Escape order is tested at :197-204. The z-60 change opens a different gap: new finding 2.

  • #2 [High] Focus dropped to <body> after a drawer opened from a submenu or context-menu item → PARTIALLY RESOLVED. Fixed for Radix DropdownMenu and submenu items and for an uncontrolled popover that closes itself (tests parts.test.tsx:268, :296 fail against the old hook). Still open: the chain is read in a layout effect, after the commit. Any opener whose layer closes in the same commit that opens the drawer leaves nothing to return to, and focus lands on <body>. Sites:

    • a controlled Popover whose button runs setOpen(false); setDrawerOpen(true), because Radix drops the trigger's aria-controls in that commit (react-popover dist L92);
    • a SearchMenu row (menu/SearchMenu.tsx:77-81, a controlled popover that does the same);
    • a CommandPalette row (menu/CommandPalette.tsx:76-80, a dialog with no trigger);
    • chained confirms built from two overlay instances.

    README.md:41-44 and :106-108 promise a return in these cases. With three or more sites the fix is structural, for example recording the focused element on focusin before the open. Or narrow the README to the openers that work. VERIFIED by probes in happy-dom (searchmenu, palette, controlled-popover all end on <body>).

  • #3 [Medium] A busy popover still closed on a trigger click → RESOLVED (docs narrowed: README.md:61-62, Popover.tsx:44).

  • #4 [Medium] The toast-click guard was unreachable → RESOLVED (the guard is gone; Radix wraps the toast viewport in DismissableLayer.Branch).

  • #5 [Medium] The gallery's loading and error entries rendered the loaded body → RESOLVED (overlay.gallery.tsx:85; the snapshot now holds both states).

  • #6 [Medium] Drawer return-focus wiring was untested → RESOLVED (Drawer.test.tsx:157 fails with useReturnFocus(false)).

  • #7 [Medium] useReturnFocus(open) forced private open state → RESOLVED (Drawer.tsx:52-66 passes straight to Radix; useOpenState is gone). The hook change in 377e48b introduced new finding 1.

  • #8 [Medium] Exported prop types accepted asChild, forceMount and an empty title → RESOLVED (Popover.tsx:36-46, HoverCard.tsx:34-37, title: string; the @ts-expect-error lines were confirmed against the un-Omitted types). The HoverCard test gap is in new finding 5.

  • #9 [Low] Doc overclaims → PARTIALLY RESOLVED. Still open: README.md:3-4 says "the parts every overlay shares", against :93-94; and README.md:97-100 leaves out OverlayHeader's className, so v1/README.md:150 "lists every prop" still does not hold.

  • #10 [Low] A Tooltip provider per tooltip turns off skip-delay → WAIVED. I accept the author's reasoning here: the approved plan chose it, README.md:88 documents it, and an app-root provider belongs with UN-4274. #2522 (comment)

  • #11 [Low] Tooltip dropped props from an asChild parent → RESOLVED (Tooltip.tsx:39 spreads the rest, including ref). The ref half is not pinned by a test: new finding 5.

  • #12 [Low] Two prop-forwarding paths untested → PARTIALLY RESOLVED. The Escape half is pinned (Popover.test.tsx:107). A caller's onInteractOutside is still untested: removing it at Popover.tsx:69, or own.onInteractOutside?.() at parts.tsx:140, leaves 61/61 green.

  • #13 [Low] Hover-delay tests tied the fake clock to wall time → RESOLVED (HoverCard.test.tsx:45, Tooltip.test.tsx:42).

New findings (inline)

  1. [High] A controlled drawer removed from the page while open returns focus to <body> (regression from 377e48b).
  2. [Medium] A toast already showing when a drawer opens paints above it but takes no clicks; a click passes through to the drawer.
  3. [Medium] The toast-in-drawer test switches off the only check behind its "clickable" claim.
  4. [Low] "Two exceptions" leaves out an opener that takes no focus on click.
  5. [Low] Four test names or comments claim more than the test pins.

Lens checklist

  1. Spec & intent: See findings #1, prior #2 (the README promises focus return in cases that land on <body>). No PR-title convention is stated in a tracked repo file, so the title item does not apply.
  2. Architectural fit & precedent: Clean (prior #7 fixed; the UN-4316 dialog reuses the shared hook instead of forking it)
  3. Correctness & edge cases: See findings #1, #2, prior #2
  4. Security: Clean (no endpoint, HTML sink, storage or network call; tooltip content is text only)
  5. Data integrity & migrations: N/A (no data write, schema or migration)
  6. Concurrency: See findings #1 (the late-close guard's timing assumption misreads an unmount)
  7. API & contract compatibility: See findings #1 (consumer searched: UN-4316 dialog/Dialog.tsx:173 calls useReturnFocus(state.open), whose signature is unchanged; no other in-repo consumer)
  8. Reliability & resilience: N/A (no external call, timeout, retry or queue)
  9. Performance & cost: Clean
  10. Observability: N/A (no log, metric or error-reporting path)
  11. Operational safety: Clean (no page uses the components yet)
  12. LLM/agent-specific: N/A (no model, prompt or agent path)
  13. Testing: See findings #3, #5, prior #12
  14. Dependencies & build: Clean (no manifest or lockfile change)
  15. Code quality: Clean (pinned biome check 2.3.13 check-only exit 0 on the changed files)
  16. Doc & comment accuracy: See findings #4, #5, prior #2, prior #9
  17. Cross-document rule consistency: Clean (branch current with origin/main; the merge-result sweep's hits outside the overlay folder are in this diff and agree)
  18. On-prem deployment experience: N/A (no chart, values file, on-prem path or doc)
  19. Scaling & workload lifecycle: N/A (no worker, autoscaling or lifecycle config)

Lenses 4-8, 11, 12, 14, 15, 17-19 were assessed by the orchestrator; the rest came from the dispatched agents and were re-checked here.

Security deep-dive: not triggered (no attack-surface trigger in the diff). Boundary sweep: not triggered (no outbound client, endpoint, log line or error path).

Not checked

  • Real-browser paint, hit-testing and Safari focus-on-click for finding 2, finding 4 and the prior #2 residual. All probes ran in happy-dom.
  • The global v1 coverage threshold. Only the overlay folder's suite ran.

Open questions for the author

  • While a drawer is open, Radix marks the toast region aria-hidden and the focus trap pulls F8 focus back, so a Retry or Undo on a toast raised from a drawer is mouse-only. Is that acceptable, or should drawer flows avoid toast actions?
  • When a drawer action removes the opener (for example, deletes the row that opened it), focus lands on <body>. Should the hook take a fallback target, or should the README list it?

Assumptions

  • The Toaster stays mounted once at the v1 root into #v1-portal, ahead of any drawer.
  • UN-4316's chained confirms reuse one dialog instance (ConfirmHost.tsx:23), so the two-instance case affects only overlays built some other way.

Focus return falls back to the page control that last had focus and
survives an overlay unmounting while open; an older toast over a drawer
no longer passes clicks through; tests pin the outside-click handler,
the tooltip ref and both omitted content props.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kirtimanmishrazipstack

Copy link
Copy Markdown
Contributor Author

Answers to the follow-up review's open questions (the thread fixes are in 8b2467b):

  • Toast actions while a drawer is open: inside a drawer, Retry or Undo belongs in the drawer (an InlineAlert, which is already the spec's error state), not only on a toast. A modal hides toasts from keyboard and screen-reader users. The README now says so (README.md:24-29). No code change.
  • A drawer action that removes its opener (deleting the row that opened it): the README lists it as a case where focus lands on the page, and the page that removes the opener moves focus itself, for example to the list heading. A fallback target in the hook would only move the guess, and the page knows where focus should go.
  • Chained confirms across two overlays: now covered as well (parts.test.tsx:338), so the single ConfirmHost instance is no longer assumed.
  • Tested: all v1 checks pass (1,359 v1 tests). Each new fix was broken on purpose and its test failed. No browser check this round.

Alert dialogs count as overlay layers, so a confirm's button is never
taken for the page control, and a removed control never replaces a
live opener.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kirtimanmishrazipstack
kirtimanmishrazipstack marked this pull request as ready for review November 22, 2026 07:22
@greptile-apps

greptile-apps Bot commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

via Greptile

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; the previous notification-layer issue is fixed.

Summary

Adds v1 drawers, popovers, hover cards and tooltips, plus shared overlay parts.

  • A drawer shows record details in a right-side panel while the page keeps scrolling.
  • A popover opens a small named panel that can hold controls.
  • A hover card shows a preview when someone hovers over or focuses its trigger.
  • A tooltip gives a control a short text hint on hover or focus.
  • Toasts sit above overlays and keep clicks on the toast list.
  • The v1 overlay gallery shows examples of all four overlay components.

Reviews (2) · Last reviewed commit: "UN-4315 [FEAT] Keep toasts above popover..." · Reviewed by Greptile

v0 pins every Radix popper wrapper at z-index 1500, so the toast list
moves from z-60 to z-1600 to stay above every overlay.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

Frontend Lint Report (Biome)

✅ All checks passed! No linting or formatting issues found.

@sonarqubecloud

Copy link
Copy Markdown

@github-actions

Copy link
Copy Markdown
Contributor

Unstract test results

Per-group results

Status Group Tier Passed Failed Errors Skipped Duration (s)
⚪ e2e-agent-kv e2e 0 0 0 1 0.1
✅ e2e-api-deployment e2e 3 0 0 0 16.2
✅ e2e-coowners e2e 1 0 0 0 1.5
✅ e2e-etl e2e 1 0 0 0 18.4
✅ e2e-login e2e 2 0 0 0 1.2
✅ e2e-prompt-studio e2e 1 0 0 0 13.6
✅ e2e-smoke e2e 2 0 0 0 2.4
✅ e2e-workflow e2e 1 0 0 0 11.9
✅ frontend-v1-e2e e2e 53 0 0 1 68.5
❌ ui e2e 0 1 0 0 0.0
TOTAL 64 1 0 2 133.9

Critical paths

⚠️ Critical paths not yet covered

  • workflow-execution-fan-out — Multi-file workflow execution fans out to file-processing workers and rejoins. (declared coverage: no groups declared)
💤 Covered, but not exercised in this build
  • adapter-register-llm — Register and validate an LLM adapter. (covered by integration-backend; no result reported in this build)
  • workflow-author — Create a workflow; its source+destination endpoints materialise and are configurable. (covered by integration-backend; no result reported in this build)
  • api-deployment-provision — Deploying a workflow as an API mints a usable key and a resolvable endpoint. (covered by integration-backend; no result reported in this build)
  • api-deployment-auth — Unauthenticated or mis-scoped API-deployment calls are rejected before dispatch. (covered by integration-backend; no result reported in this build)
  • mcp-server-auth — Unauthenticated or mis-scoped hosted-MCP calls are rejected before any tool runs. (covered by integration-backend; no result reported in this build)
  • mcp-platform-auth — The org-scoped MCP endpoint stays behind the platform-API-key middleware; unauthenticated or mis-scoped calls reach no tool. (covered by integration-backend; no result reported in this build)
  • platform-key-whoami — A platform API key resolves its own organisation over the org-less whoami endpoint; the org comes from the key row, not the URL. (covered by integration-backend; no result reported in this build)
  • prompt-studio-author — Create a Prompt Studio project and add a prompt to it. (covered by integration-backend; no result reported in this build)
  • connector-register-test — Connector credentials are validated against the live system and stored encrypted. (covered by integration-backend; no result reported in this build)
  • usage-aggregate-read — Per-run token usage aggregates correctly and stays scoped to its organization. (covered by integration-backend; no result reported in this build)
✅ Covered critical paths
  • auth-login — covered by e2e-login
  • co-owner-manage — covered by e2e-coowners
  • workflow-create-execute — covered by e2e-workflow
  • api-deployment-run — covered by e2e-api-deployment
  • prompt-studio-fetch-response — covered by e2e-prompt-studio
  • pipeline-etl-execute — covered by e2e-etl
  • usage-token-tracking — covered by e2e-api-deployment
  • callback-result-delivery — covered by e2e-api-deployment

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

main-only Stays on main: not backported to a release line

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant