BaseOverlay

Status: No dedicated documentation exists in design-system-docs (checked main + all open PRs, verified 2026-08-19). Unlike most components in this batch, this one has a real internal engineering doc in the source repo — content below marked "real source content" is copied/paraphrased from that file, not invented. Everything else is an explicit placeholder.

Source: DTSL/design-system → packages/primitives/BaseOverlay/ (package @dtsl/naos-primitives, exported as BaseOverlay, useBaseOverlay)

Real source content, from packages/primitives/BaseOverlay/overlay-baseoverlay-docs.md:

Headless overlay primitive for the Brevo Design System. Handles accessibility behavior (focus trap, inert, scroll lock, ESC dismiss, click-outside dismiss, focus restoration) so that consumers only write visual DOM and CSS. BaseOverlay portals children to document.body. When animate=true, it wraps children in an internal animated div — a scale-opacity fade by default, or a directional slide when animateFrom is set to 'left'/'right'/'top'/'bottom'.

Real "When To Use" table from the same source file:

Situation	Use
Building a new overlay type from scratch	BaseOverlay
Need full control over behavior flags	BaseOverlay
Standard dropdown or popover	PopupOverlay (Phase 2 — not yet built, per the doc)
Standard modal or drawer	DialogOverlay (Phase 3 — not yet built, per the doc)

Feature phases (real, from source doc): Phase 1 (current) = BaseOverlay component + useBaseOverlay hook, all behavior handled internally. Phase 2/3 (upcoming, not yet built) = PopupOverlay and DialogOverlay presets.

Component index exports (verbatim from index.js):

export { default } from './BaseOverlay'
export { default as BaseOverlay } from './BaseOverlay'

When NOT to Use

TODO — not covered by the source doc excerpt read. Needs confirming with the primitives team whether Popover/ModalDialog/Sidemodal (already built on some overlay mechanism) should be preferred over building directly on BaseOverlay for standard cases.

Decision Logic

Real, from source: if you need a standard dropdown/popover or modal/drawer, the source doc points to future PopupOverlay/DialogOverlay presets — which don't exist yet (Phase 2/3, unbuilt). Until those ship, teams needing those patterns should probably use existing composite components (Popover, ModalDialog, Sidemodal, DrawerPanel) rather than BaseOverlay directly — but this substitution isn't stated in the source doc and needs confirming with the team.

Accessibility

Real, from source: BaseOverlay explicitly handles focus trap, inert, scroll lock, ESC-to-dismiss, click-outside-to-dismiss, and focus restoration internally — these are genuine built-in behaviors, not guessed.

Common Mistakes

TODO — not covered by the source doc excerpt read. Needs UX/product/engineering input.