feat(popover): export Popover as a public compound component

.changeset/lucky-pandas-explore.md

@@ -0,0 +1,15 @@
+---
+"@commercetools/nimbus": minor
+---
+
+`Popover`: new compound component for interactive content anchored to a trigger
+— `Popover.Root`, `Popover.Trigger` and `Popover.Content`. Reach for it for
+filter panels, short edit forms and context-sensitive actions; `Tooltip` still
+covers plain hints, and `Dialog` covers flows that should block the page.
+
+Name `Popover.Content` with `aria-label` or `aria-labelledby` — a visible
+heading inside the popover does not name it.
+
+Beta. See the
+[Popover docs](https://nimbus-documentation.vercel.app/components/feedback/popover)
+for the full prop reference.

.changeset/wise-moons-listen.md

@@ -0,0 +1,10 @@
+---
+"@commercetools/nimbus": minor
+---
+
+`LocalizedField`: the info popover opened by the hint button now has an
+accessible name, so screen readers announce it instead of an unnamed dialog. It
+also matches the appearance of other popovers — one shadow rather than two
+stacked, no border or background tint of its own — and fades in and out like
+them. It no longer draws an outline around itself when opened, matching `Dialog`
+and `Drawer`.

openspec/changes/archive/2026-08-20-correct-popover-rendering-spec/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-20

openspec/changes/archive/2026-08-20-correct-popover-rendering-spec/proposal.md

@@ -0,0 +1,54 @@
+# Proposal: Correct the Popover Optimized Rendering requirement
+
+## Why
+
+Rewrite the `Optimized Rendering` requirement in the `nimbus-popover` capability
+so it describes observable Popover behavior instead of React Aria internals and
+a configuration option that does not exist.
+
+### Background
+
+`popover-compound-export` narrowed this capability from an eight-part
+aspirational surface to the three parts actually built, and corrected the
+requirements it touched. `Optimized Rendering` was not among them, so its
+`Scroll optimization` scenario still specifies two things the component cannot
+be held to:
+
+- **`SHALL use requestAnimationFrame for positioning updates`** — an assertion
+  about React Aria's internals. Nimbus neither implements nor tests it, and it
+  would silently become false if React Aria changed its scheduling.
+- **`MAY close popover on scroll if configured`** — there is no such option.
+  `Popover.Root` accepts `placement`, `offset`, `crossOffset`, `shouldFlip`,
+  `containerPadding`, `boundaryElement`, `isNonModal`,
+  `isKeyboardDismissDisabled`, `shouldCloseOnInteractOutside` and `triggerRef`,
+  and none of them dismisses on scroll. (At the time of this change those props
+  were accepted on `Popover.Content`; they moved to `Popover.Root` when it
+  became the compound's single configuration surface. The conclusion is
+  unaffected.)
+
+Both are the same class of inaccuracy as the `portalContainer` and
+`trigger="hover"` scenarios corrected in the previous change, and they were left
+behind only because that change's scope did not reach this requirement.
+
+## What Changes
+
+Keep both scenario names and restate their bodies against what the component
+actually does:
+
+- `Lazy mounting` is accurate and stays, worded against the overlay content
+  rather than "content in DOM".
+- `Scroll optimization` becomes a statement about the observable outcome — the
+  popover stays anchored to its trigger and within the viewport while the page
+  moves — and records that no scroll-dismissal option is exposed.
+
+## Scope
+
+- **In scope**: the `Optimized Rendering` requirement of `nimbus-popover`.
+- **Out of scope**: any implementation change. This corrects the specification
+  to match shipped behavior; no source file changes.
+
+## Impact
+
+- **Breaking changes**: None
+- **Migration required**: None
+- **Dependencies**: None

openspec/changes/archive/2026-08-20-correct-popover-rendering-spec/specs/nimbus-popover/spec.md

@@ -0,0 +1,20 @@
+## MODIFIED Requirements
+
+### Requirement: Optimized Rendering
+
+The component SHALL keep overlay content out of the DOM while closed, and SHALL
+stay anchored to its trigger while the page moves.
+
+#### Scenario: Lazy mounting
+
+- **WHEN** the popover is closed
+- **THEN** the overlay content SHALL NOT be mounted in the DOM
+- **AND** it SHALL mount when the popover opens
+- **AND** it SHALL unmount once the exit animation has finished
+
+#### Scenario: Scroll optimization
+
+- **WHEN** the page scrolls or the viewport resizes while the popover is open
+- **THEN** the popover SHALL remain anchored to its trigger
+- **AND** it SHALL stay within the viewport, flipping or shifting as needed
+- **AND** no scroll-dismissal option SHALL be exposed

openspec/changes/archive/2026-08-20-correct-popover-rendering-spec/tasks.md

@@ -0,0 +1,32 @@
+# Tasks: Correct the Popover Optimized Rendering requirement
+
+- [x] Task 1: Rewrite the `Optimized Rendering` requirement as a delta
+- [x] Task 2: Validate and archive
+
+---
+
+## Task 1: Rewrite the `Optimized Rendering` requirement as a delta
+
+**File:**
+`openspec/changes/correct-popover-rendering-spec/specs/nimbus-popover/spec.md`
+
+- Restate `Lazy mounting` against the overlay content.
+- Replace the `Scroll optimization` body: drop the `requestAnimationFrame`
+  claim and the non-existent scroll-dismissal option, and state the observable
+  anchoring behavior instead.
+- Keep both scenario names, since a MODIFIED requirement may not drop scenarios
+  the current spec still has.
+
+**Validation:**
+
+- `pnpm exec openspec validate correct-popover-rendering-spec --strict` clean
+
+## Task 2: Validate and archive
+
+- Archive so the delta applies to `openspec/specs/nimbus-popover/spec.md`.
+
+**Validation:**
+
+- `openspec/specs/nimbus-popover/spec.md` no longer mentions
+  `requestAnimationFrame` or closing on scroll
+- No source or test files change

openspec/changes/archive/2026-08-20-popover-compound-export/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-19