CORE-2949: Add BannerRegion, a Banner that announces itself

[OpenStaxClaude]

Jira: CORE-2949 — follows up on CORE-2947, where the question came up of whether the live region should be built into Banner itself.

What this is

Banner renders a plain styled <div> with no role or aria-live. A caller that wants a banner announced has to build its own live region and know a non-obvious rule to get it right: the region has to already be in the accessibility tree before the banner appears. Today exactly one call site in the org does that — the wrapper #533 just added in assignments. This moves that wrapper into the library so the constraint is written down where the next person will look for it.

Why not aria-live on Banner

Every call site uses the shape {messages.length ? <Banner …/> : null}. If Banner carried the role itself, the region and its content would enter the DOM in the same tick and AT would read that as initial state rather than a change — Chrome + NVDA usually announces it anyway, Safari + VoiceOver reliably does not. It would look right in review, pass snapshot tests, and silently fail for a subset of users, while removing the incentive for callers to wrap it properly.

So the conditional moves inside the library, behind a container that is always rendered. This mirrors ToastContainer (src/components/ToastContainer.tsx:37), where the container is the live region and the individual toasts render into it — Banner was the only announcement-shaped component here without a container equivalent.

Deliberate choices

• role="status" for every severity. The obvious mapping — error → role="alert" — would make a banner rendered on page load interrupt whatever the user was doing. Severity describes how loud the banner looks, not how urgently it needs to reach someone. If a caller turns up that genuinely needs assertive, add an explicit opt-in prop then.
• Plain Banner is unchanged apart from a doc comment, and stays the right choice for a banner that is already on the page when it loads. Use BannerRegion when something the user or the app did causes the banner to appear or change, such as a failed request. Steady-state information inside a live region announces itself again on every remount, for a change the user never made.
• Messages present on the first render are not announced. A region mounted with its content puts both into the page together, which assistive technology reads as initial state. That is deliberate: those messages are page content, read in order, and announcing them on every load would repeat something the user did nothing to cause. It is also what assignments' hand-written wrapper does for its first batch of warnings. Callers keep the region mounted and change messages, as the doc comment says. A test pins that the banner is in the first render's output rather than added after an effect.
• A one-rule stylesheet. The wrapper has to stay layout-neutral, because callers drop it into existing flex and grid containers. A bare, always-rendered div is not: empty, it is still a flex or grid item, which doubled a 20px gap to 40px in Chrome and took a grid cell. So while it is empty (:empty) it is position: absolute, which takes it out of layout but not out of the accessibility tree. display: contents also fixes the layout, but has a history of dropping elements from the accessibility tree in Safari, which is where this component matters most. With a banner in it the wrapper is an ordinary block, and className styles it.

Tests

The Banner specs are snapshot-based, but a snapshot can't express the property that matters. The spec asserts the region exists while there is nothing to announce, and that the element holding the banner afterwards is the same element — the case AT misses is a region that arrives together with its content. A test checks the wrapper is :empty until there is something to announce, since the layout rule depends on it; a story, InAFlexContainer, shows the region in a flex row with a gap. The stories are there for checking with a real screen reader. ComparedWithBanner shows the same message appearing in a plain Banner and in a BannerRegion side by side. The existing Banner stories are static, so each banner is already on the page when it loads; they now carry captions saying so, and the Error story notes that an error like it normally comes from a failed request and belongs in a BannerRegion.

Draft, because

The version bump and ./scripts/publish.bash are a human step, and nothing consumes this yet. Once it's released, CORE-2949 covers replacing the hand-written wrapper in assignments' SelectScopeContent with it and auditing the remaining call sites.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation follows established live-region behavior and includes focused tests and usage documentation.

Review effort: Balanced
Findings: None