ChatSidebar with modal={false} still inert-hides and focus-traps the entire app

[einari]

Expected

<ChatSidebar modal={false} …> (the default — the prop's own documentation says "a chat lives next to the work, so it should not block it") should leave the rest of the application interactive while open: no focus trap, no scroll lock, and no inert applied outside the panel.

What happens instead

With modal={false}, opening the sidebar makes the entire rest of the page non-interactive — clicks, focus, and text selection are dead everywhere outside the panel until it closes. The backdrop styling is correct (pointer-events: none unless data-modal='true'), so the page looks non-modal, which makes the freeze surprising.

Cause

ChatSidebar (v4.1.0, dist/esm/Chat/ChatSidebar.js:65-68) always renders through react-aria-components' ModalOverlay/Modal. ModalOverlayInner calls useModalOverlay unconditionally whenever open (react-aria-components/dist/private/Modal.js:106-109), and that hook (react-aria/dist/private/overlays/useModalOverlay.js:24-43) unconditionally:

• runs ariaHideOutside([panel], { shouldUseInert: true }) — walks document.body and sets element.inert = true on every sibling of the panel (ariaHideOutside.js:35,41-49), which is the actual mechanism that freezes the app;
• traps Tab focus inside the panel (useOverlayFocusContain);
• locks body scroll (usePreventScroll).

The modal prop only affects backdrop paint/pointer-events and dismissal — it never reaches these react-aria side effects.

Smallest reproduction

const [open, setOpen] = useState(false);
<>
  <button onClick={() => setOpen(o => !o)}>Toggle chat</button>
  <ChatSidebar open={open} onClose={() => setOpen(false)} topics={[]} messages={[]} />
</>

Open the sidebar, then try to click the toggle button (or anything else on the page): every element outside the panel carries inert and ignores the click.

Why it matters

Any consumer following the component's documented default gets a modal in behavior while non-modal in appearance. In Stagehand this presents as "opening the chat blocks the whole app" (Cratis/Stagehand#748) despite the consumer passing nothing but the documented defaults — the failure is invisible in the consumer's own code, which makes it expensive to locate.

Direction (yours to decide)

When modal={false}, render the panel without the Modal/ModalOverlay primitives — a plain positioned element with the same classes/animations — reserving react-aria's overlay machinery for modal={true}. Stagehand is working around it by hand-rolling the slide-in and composing the unwrapped ChatTopicList/ChatConversation pieces.

[cratis-direct]

Investigation

Reproduced. I wrote a throwaway jsdom spec (Source/Chat/for_ChatSidebar/when_repro_246.ts, since deleted — working tree is clean) that mounts <ChatSidebar open modal={false}> next to a plain <button> on document.body. With the sidebar open:

OUTSIDE inert attr = null | aria-hidden = "true"
BODY CHILDREN: BUTTON[aria-hidden=true], DIV[aria-hidden=true], SPAN[aria-hidden=true],
               DIV.cratis-chat-sidebar__backdrop[aria-hidden=null], SPAN[aria-hidden=true]
BODY STYLE overflow = "hidden"

Every sibling of the sidebar's portal is hidden, and the page is scroll-locked. jsdom lacks inert, so ariaHideOutside takes its aria-hidden fallback (node_modules/react-aria/dist/private/overlays/ariaHideOutside.js:20,39,42) — in a real browser the same call sets element.inert = true, which is the freeze the reporter describes. Root cause confirmed exactly as reported: Source/Chat/ChatSidebar.tsx:379-414 always renders ModalOverlay/Modal, and useModalOverlay unconditionally runs usePreventScroll, useOverlayFocusContain and ariaHideOutside([panel], {shouldUseInert: true}) (react-aria/dist/private/overlays/useModalOverlay.js:24-43). modal only reaches isDismissable/isKeyboardDismissDisabled and the data-modal attribute the CSS paints from.

SUGGESTED-MODEL: sonnet

Plan — #246

Settled (do not redo)

• Reproduced and root-caused. Evidence above. modal never reaches react-aria's side effects; the data-modal CSS gate in ChatSidebar.css:11-19 is correct and needs no change.
• Baseline is green. npx vitest run Chat/for_ChatSidebar → 2 files / 15 tests pass. yarn install is required first (no node_modules in a fresh checkout); note the workspace has no vitest script — run npx vitest from Source/.
• Nothing today depends on the modal machinery in the non-modal path. Current rendered DOM is exactly:
  • backdrop: class="cratis-chat-sidebar__backdrop" data-cratis-part="backdrop" data-modal data-open data-selected data-rac + a style carrying only react-aria's --visual-viewport-* / --page-* variables, which ChatSidebar.css never reads
  • panel: class="cratis-chat-sidebar" data-cratis-part="root" data-position data-open data-selected data-rac style="width: …"
  • No role, no aria-modal, no tabIndex — so the non-modal branch loses no a11y attribute.
• react-aria 3.51.0 is already a direct dependency of Source (Source/package.json), and Overlay is public API (react-aria/dist/types/src/overlays/Overlay.d.ts) with exactly the needed knobs: portalContainer, disableFocusManagement, shouldContainFocus, isExiting. Its default is <FocusScope restoreFocus contain={false}> — restore-on-close without a trap, and no auto-focus-in, which is what a non-modal panel wants.
• useEnterAnimation/useExitAnimation are NOT public — they live at react-aria/private/utils/animation. Do not import them.
• No story, doc page, conformance test, or ChatSidebarForObservableQueries passes modal, so the blast radius is ChatSidebar.tsx + its specs. Source/types/parts.ts:45,388 already declares the open/selected state attributes on backdrop/root — the non-modal branch must keep emitting them.

The change

1. Extract the markup once. In Source/Chat/ChatSidebar.tsx, pull the backdrop <div> and panel <div> (with their pt spreads, classNames(...), data-cratis-part, data-modal, data-position, data-open, data-selected, style={{ width, ...pt?.root?.style }}) into a small local render helper taking { isEntering, isExiting }, so both branches emit byte-identical attributes apart from data-entering/data-exiting. Do not duplicate the JSX.

2. Branch on modal.

   • modal === true → unchanged ModalOverlay/Modal path (keeps inert, focus trap, scroll lock, isDismissable, Escape).
   • modal === false → <Overlay isExiting={isExiting}> from react-aria, rendering the same two divs directly. No shouldContainFocus. Keep default focus management (restore-on-close); only reach for disableFocusManagement if a spec shows FocusScope's tab-out handling misbehaving.

3. Local enter/exit animation. The CSS slide/fade is driven entirely by [data-entering] / [data-exiting] (ChatSidebar.css:21-27, 60-67, 84-92), so the non-modal branch must reproduce that contract or closing will pop instead of slide. Add a small internal hook (e.g. Source/Chat/useOverlayTransition.ts, ~40 lines, not exported from the barrel):

   • mounted while open || exiting;
   • entering true on first render, cleared when the panel element's animations settle;
   • on open → false, exiting true until they settle, then unmount;
   • jsdom guard: if 'getAnimations' in element is false, or getAnimations() is empty, end immediately — this is what makes the existing 400 ms wait in for_ChatSidebar/given/a_chat_sidebar_in_the_dom.ts still work. Mirror the shape of react-aria's useAnimation (Promise.allSettled(animations.map(a => a.finished))), driven off the panel ref (200 ms, the longer of the two).

4. Specs in Source/Chat/for_ChatSidebar/ using the existing given/a_chat_sidebar_in_the_dom.ts helper:

   • when_open_without_modality.ts — an element appended to document.body before render keeps aria-hidden === null and inert unset; document.documentElement.style.overflow is not 'hidden'; the panel and backdrop still carry data-cratis-part, data-open, data-position, data-modal="false" and the sidebar classes.
   • when_open_with_modality.ts — the regression guard for modal: outside content is hidden and scroll is locked, so the modal path is not silently broken.
   • when_closing_without_modality.ts — after open → false, data-exiting appears and the panel then unmounts (jsdom's no-animation path makes this immediate).

5. Docs. modal is currently undocumented outside the TSDoc (Documentation/Chat/** never mentions it). Add a short paragraph to Documentation/Chat/index.md stating the two modes explicitly — the whole cost of this bug was that the documented default and the actual behavior disagreed.

Quality gates

npx tsc -b and yarn lint clean; npx vitest run Chat green; ideally check the Playground story in Storybook (add a second modal story if cheap) to confirm the slide-in/out still animates in a real browser — the animation is the one thing jsdom cannot verify.

PR label

patch — a bug fix in shipped behavior of a published component, no public API change.

Needs a human decision (neither blocks starting)

1. Portal container. Dialogs/DialogImplementation.tsx:7,52,360 wraps its overlay in UNSAFE_PortalProvider getContainer={overlayEnvironment.getContainer} (Source/renderer/overlayEnvironment.ts). ChatSidebar does not, and portals to document.body today. Adopting the renderer overlay environment here would be consistent but is a behavior change beyond this bug — the plan above preserves today's document.body default. Say if you want it aligned in the same PR.
2. Non-modal a11y semantics. The panel has no role or accessible name in either mode. Now that the rest of the app stays exposed to assistive tech, a role="complementary" (or region) + aria-label on the panel would be a genuine improvement — but it changes the DOM contract of a stable part, so I have left it out. The issue carries an accessibility label, so it may be intended scope.

Suggested model for implementation: sonnet

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.