Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
b7db0cf
docs(overlay-manager): add overlay manager design spec
ispashkov Nov 17, 2026
ea65839
docs(overlay-manager): add the implementation plans
ispashkov Nov 17, 2026
d4505ae
feat(overlay-manager): add defineOverlay and the overlay types
ispashkov Nov 17, 2026
5bcc0ab
test(overlay-manager): check declaration emit across modules
ispashkov Nov 17, 2026
5e35fb4
fix(overlay-manager): reject instead of throwing when a loader throws…
ispashkov Nov 17, 2026
d6c48e0
feat(overlay-manager): add the overlay store
ispashkov Nov 17, 2026
cbe27d8
feat(overlay-manager): add OverlayProvider and useOverlay
ispashkov Nov 17, 2026
7242313
fix(overlay-manager): detach the store only on a real unmount
ispashkov Nov 17, 2026
d03c371
test(overlay-manager): let zag track the exit before ending its anima…
ispashkov Nov 17, 2026
919e2c8
feat(overlay-manager): close overlays when closeOnChange changes
ispashkov Nov 17, 2026
6c1e010
test(overlay-manager): mark the StrictMode closeOnChange test as a sm…
ispashkov Nov 17, 2026
9e17a06
feat(overlay-manager): stories, usage docs, e2e and Claude Design omi…
ispashkov Nov 17, 2026
26de930
docs(overlay-manager): tick the Overview page off in the coverage tra…
ispashkov Nov 17, 2026
e4a96b5
docs(overlay-manager): park the menu-item focus finding and two skill…
ispashkov Nov 17, 2026
0dd5fdb
docs(overlay-manager): guidelines, MCP aliases and test-id notes
ispashkov Nov 17, 2026
ccaf79f
docs(overlay-manager): show the error toast in the managed confirmati…
ispashkov Nov 17, 2026
1275034
fix(overlay-manager): keep overlays through StrictMode replays; never…
ispashkov Nov 17, 2026
ad3261b
docs(overlay-manager): whose context overlays read, observed focus, S…
ispashkov Nov 17, 2026
25bc6b2
docs(overlay-manager): JSDoc for the controller types and closeOnChan…
ispashkov Nov 17, 2026
4c98157
docs(overlay-manager): managed confirmation snippets that compile whe…
ispashkov Nov 17, 2026
4c6cfcf
test(overlay-manager): pin declaration emit and the exact missing-pro…
ispashkov Nov 17, 2026
017ebb2
test(overlay-manager): say why the StrictMode reveal test leaves the …
ispashkov Nov 17, 2026
56a2108
docs: remove vestiges of the overlay manager build
ispashkov Nov 18, 2026
003f0cc
πŸ–ΌοΈ Update screenshots
github-actions[bot] Nov 18, 2026
c00c188
fix(overlay-manager): return focus to the opener when a confirm close…
ispashkov Nov 18, 2026
d7b9b09
fix(overlay-manager): a nested provider reports through the enclosing…
ispashkov Nov 18, 2026
1f62e91
fix(overlay-manager): catch components without controller or with a k…
ispashkov Nov 18, 2026
ef3f0c7
fix(overlay-manager): open() resolves undefined when reading the payl…
ispashkov Nov 18, 2026
274f544
fix(overlay-manager): release the scroll lock when an Activity hides …
ispashkov Nov 18, 2026
641551c
test(overlay-manager): pin the settle-table rows the suite left out
ispashkov Nov 18, 2026
58989f3
docs(overlay-manager): close the gaps the spec review found
ispashkov Nov 18, 2026
11f88c2
docs(overlay-manager): an Activity hide detaches the store too
ispashkov Nov 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .claude/skills/storybook-docs/REFINEMENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,3 +55,5 @@ Keep the two parking lots distinct, because mixing them loses things:
| 2026-08-25 | SimpleCharts | A curly-to-straight apostrophe inside a single-quoted TS string broke the file; it surfaced only as `Unable to index …` in Storybook, and Biome's `check` missed it. | Typecheck after every file, not per batch. | βœ… Folded (step 5) |
| 2026-09-30 | FileUpload | Step 5 gave no headless URL, and `pnpm typecheck` is a no-op for story files. | Overview id is `<title-kebab>--overview`; typecheck with `tsc -p tsconfig.storybook.json --noEmit`. | βœ… Folded (step 5) |
| 2026-09-30 | Avatar | `references/reference-systems.md` was stale: Pajamas fetched fine with plain `WebFetch`, and Carbon ships no avatar. | Pajamas marked intermittent; Carbon's missing avatar named. | βœ… Folded (`references/reference-systems.md`) |
| 2026-11-17 | OverlayManager | A hook-only provider has no Figma node, no Code Connect file and no peer in the roster: none of the six systems that fetched documents an imperative or promise-based manager (Primer's `useConfirm` is only a sidebar link), and every dialog example is driven by local state. Steps 2 and 3 had nothing to return. EUI's modal page 404'd on three guessed URLs, so the roster's `eui.elastic.co/docs/components/...` shape is too loose. | Say in step 2 that a component with no `{Name}.figma.ts` and no visual surface skips Figma in one line; put EUI's real modal path in `references/reference-systems.md`. | πŸ…ΏοΈ Parked |
| 2026-11-17 | OverlayManager | The annotation scan flags a `<Text data-testid='result'>Result: …</Text>` line that echoes the value a story awaited. It is demo output, not a label naming what you are looking at, but the skill only sorts hits into labels and content. | Name output readouts as content: leave them, and keep them plain text (no solid colour) so they stay quieter than the specimen. | πŸ…ΏοΈ Parked |
2 changes: 2 additions & 0 deletions docs/e2e-test-rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,8 @@ These rules apply when writing or modifying any E2E test file (`*.e2e.ts`) in th
- Locate elements by `data-testid` (`page.getByTestId(...)`); compound components cascade it to sub-components (`{base}--{slot}`) β€” see [`test-id-pattern.md`](./test-id-pattern.md)
- `getByRole` is fine for accessibility assertions (role, accessible name)
- Never use `data-slot` β€” it is a styling hook. Existing `[data-slot=…]` locators are legacy; migrate them when you touch the file
- A managed overlay (OverlayManager) keeps its content mounted while it animates out, and two instances of one definition can stack, so its test id can match twice: `await expect(content).toBeHidden()` before reopening, or target the open instance (`.and(page.locator('[data-state="open"]'))`, or `.last()` for the top of a stack).
- To assert where focus returns after a dialog opened from a menu item, hover the item and let a frame pass before the click: an item picked in its highlight frame sends focus to `body` (see `storybook-docs-findings.md`).

## Full Example

Expand Down
5 changes: 3 additions & 2 deletions docs/storybook-docs-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
> [`storybook-docs` skill](../.claude/skills/storybook-docs/SKILL.md); problems found along
> the way go in [findings](./storybook-docs-findings.md).

> **Last updated:** 2026-10-22, against main at v3.3.0. **98 of 119 pages are written**; 21 are left (see the ☐ rows).
> **Last updated:** 2026-10-22, against main at v3.3.0. **99 of 120 pages are written**; 21 are left (see the ☐ rows).

## How to use this

Expand Down Expand Up @@ -39,7 +39,7 @@ The first pass is done; the ☐ rows are components that arrived after it. The t

## Snapshot

- **98 written to the standard Β· 21 left**, across 119 story pages. `Table` has grown a story without a sentence (`InlineCellEditing`) since it was levelled.
- **99 written to the standard Β· 21 left**, across 120 story pages. `Table` has grown a story without a sentence (`InlineCellEditing`) since it was levelled.
- Levelling was usually cutting, not filling β€” and often correcting. Five pages
claimed behaviour their own code contradicted: `Slider`, `Dialog`,
`CodeSnippet` (its `Sizes` story labelled the wrong default), `BarList`
Expand Down Expand Up @@ -152,6 +152,7 @@ The first pass is done; the ☐ rows are components that arrived after it. The t
| βœ… | Overlay/FeedbackPulse | 2 | 2 | `components/FeedbackPulse/FeedbackPulse.stories.tsx` |
| ☐ | Overlay/HoverCard | 8 | 8 | `components/HoverCard/HoverCard.stories.tsx` |
| βœ… | Overlay/OverflowTooltip | 7 | 7 | `components/OverflowTooltip/OverflowTooltip.stories.tsx` |
| βœ… | Overlay/OverlayManager | 4 | 4 | `components/OverlayManager/OverlayManager.stories.tsx` |
| βœ… | Overlay/Popover | 4 | 4 | `components/Popover/Popover.stories.tsx` |
| βœ… | Overlay/Tooltip | 4 | 4 | `components/Tooltip/Tooltip.stories.tsx` |
| βœ… | Overlay/Tour | 5 | 5 | `components/Tour/Tour.stories.tsx` |
Expand Down
27 changes: 27 additions & 0 deletions docs/storybook-docs-findings.md
Original file line number Diff line number Diff line change
Expand Up @@ -1243,3 +1243,30 @@ Not findings β€” decisions worth remembering so they are not rediscovered.
`data-testid`.
- **Found while** β€” reviewing `Stepper` (WDS-148).
- **Status** β€” Open (documented)

### Dialog opened from a menu item: focus lands on `body` when the item is picked in its highlight frame

- **What** β€” When a `DropdownMenuItem` opens a `Dialog` and the item is picked in the same frame as
its highlight, closing the dialog leaves focus on `body` instead of returning it to the menu
trigger. Picked a frame or more after its highlight, as a person does, focus returns to the
trigger.
- **Evidence** β€” Reproduced in Storybook on Chromium through automated clicks (a click with no
earlier hover): `Patterns/Confirmation dialogs` β†’ `Default` (a controlled `Dialog` opened from a
row's menu item) and `Overlay/OverlayManager` β†’ `From Menu Item` (the same dialog opened through
`useOverlay`) both end with `document.activeElement` on `BODY` after Escape. A jsdom probe of the
same menu and dialogs returns focus to the trigger after a hover, a frame, then a click (or
ArrowDown, a frame, then Enter), managed and controlled alike, and ends on `body` when the click
or Enter comes in the highlight's frame. Not yet checked in a browser at human speed.
- **Cause** β€” Moving the highlight schedules zag menu's `focusMenu` frame (`menu.machine.mjs`), and
closing the menu does not cancel it. In the same frame, the menu first focuses its trigger, the
stale frame pulls focus back into the closing menu content, the dialog's focus trap records that
content as its return target, and the content unmounts.
- **Why it matters** β€” Automated tests that pick a menu item without a hover see focus on `body`,
and so would a keyboard user who presses ArrowDown and Enter within one frame. The overlay
manager does not cause it.
- **Suggested action** β€” Report upstream: zag's menu should drop its `focusMenu` frame once the
menu has left the open state. Until then, an e2e focus assertion needs a hover and a frame before
the click. Do not capture `document.activeElement` in the overlay manager's `open()`: from a menu
item it is the menu content.
- **Found while** β€” documenting `OverlayManager`; cause found in the 2026-11-18 spec review.
- **Status** β€” Open (upstream).
Loading
Loading