Components: Generate Popover

Summary

Generate Popover with its canonical contract, implementation, tests, stories, platform validation, and explicit package export, establishing the overlay foundation for the largest blocked component wave. This task owns the unresolved anchoring, overlay-host, light-dismiss, focus-return, and platform-positioning contract rather than deferring it to consumers.

Observed. popover is entry popover in the canonical catalog and has no
implementation in packages/agentic/components. Upstream describes it as: Floating surface presenting structured, optionally interactive content anchored to a trigger element. Single type, runtime positioning, a content swap slot, an optional arrow, and light-dismiss behavior.

Goal

Generate the popover component in
packages/agentic/components/src/components against the
canonical Fluent Flex spec, with the colocated coverage, stories, and platform
validation the package requires, and export it explicitly from
src/index.ts.

Stage

Stage 2 (beta). Wave 2 - overlay and popover stack.

Why it matters

Observed. The canonical catalog has 50 components and the agentic library has
generated 18. popover is one of the 32 in the gap, enumerated in
the missing-components index.

Inferred. It belongs to the overlay stack, which is the largest single cluster of blocked components. Delivering the cluster converts a broad "not implementable" state into ordinary component work.

Observed current state

Canonical spec and source

Field	Value
Canonical spec	plugins/components/skills/popover/SKILL.md with usage.md, web/tokens.yaml, web/accessibility.md, and web/interaction.md, at x3-design/fluent-design @ d334acf
Upstream tier	atom
Upstream catalog key	popover in component-map.yaml
Local staged spec	packages/agentic/components/specs/popover - SPEC.md, usage.md, interaction.md, accessibility.md, tokens.yaml, blockers.md
Local implementation	None. No src/components/popover directory exists

Closest existing FURN or V1 implementation

• packages/native/Callout - The standalone native-backed floating surface: Callout.tsx, Callout.types.ts, CalloutNativeComponent.ts, and Callout.stories.tsx. It is already a declared dependency of packages/agentic/components and appears in the Storybook smoke set as primitives-callout--default.
• packages/experimental/Popover - Popover.tsx and Popover.types.ts - a thin JavaScript surface, not a full overlay host.

Note on platform canon. Where a legacy package has platform-specific files, the
desktop path (.win32, .windows, .macos, or the unsuffixed cross-platform file)
is the compatibility reference. .ios, .android, and .mobile variants are not
treated as the cross-platform canonical implementation.

Local dependencies

• No generated agentic component is required as a direct dependency.

Known blockers

Observed (blockers.md, blocker class B in the index).

Four blockers were recorded: anchoring and edge-aware positioning need a dedicated anchor, measurement, and overlay strategy; light dismiss and the focus lifecycle need an overlay host; the accessibility contract is dialog-like and needs trigger coupling (aria-controls, aria-expanded, aria-haspopup); and the component is shared overlay infrastructure that several other authored components expect, with no existing implementation in the package to extend.

Reassessment.

Fully valid. Nothing in the package has changed to address overlay infrastructure. Inferred: this is the single highest-leverage missing component - it is the keystone for combobox, dialog, dropdown, menu, teaching-popover, toast, tooltip, and, through those, for breadcrumb, info-label, menu-button, and split-button.

Scope

• Ingest or promote the spec into the component directory in the generated shape
  (SPEC.md plus a spec/ folder), per
  spec-ingestion-and-generation.md.
• Establish the public contract first: variants, slots, native props, accessibility,
  interaction states, and platform behavior.
• Implement the required file structure from
  src/components/AGENTS.md:
  popover.types.ts, popover.styles.ts, use*.ts, use*Styles.ts, render*.tsx, and
  the assembly module with a displayName.
• Style from Flex tokens first and record genuine token gaps rather than substituting
  unrelated values.
• Export the component, its public types, and the state, style, and render stages
  explicitly from src/index.ts under component-qualified unstable names.
• Decide the overlay strategy first, because every wave 2 component inherits it: React Native Modal, an app-level overlay host with a portal-style API, or the native Callout.
• Note that @fluentui-react-native/callout is already a declared dependency of the agentic package, listed under furn.knip.ignoreDependencies because nothing imports it. Inferred: it was added in anticipation of exactly this work, which makes the native path the path of least resistance - at the cost of a native dependency in a package whose source boundary is otherwise React Native, design, and framework-base.
• Define the trigger-coupling contract that replaces aria-controls, aria-expanded, and aria-haspopup.
• Define the focus lifecycle: focus moves in on open, is trapped or not per type, and returns to the trigger on close.

Out of scope

• Changing the contract of an existing generated component, unless this task explicitly
  calls for it above; raise it as its own item.
• Building shared infrastructure owned by another task: overlay hosting
  (popover), roving focus (focus-zone.md), spec
  ingestion (spec-ingestion-and-generation.md),
  or the coverage contract (component-test-strategy.md).
• Migrating any legacy FURN consumer onto this component.
• Mobile platform support; the applicable upstream companion is web, retargeted to
  React Native for Windows and macOS.

Deliverables

• src/components/popover/ implementing the full required file structure.
• SPEC.md and a spec/ companion folder with provenance recording the upstream path,
  SHA, and ingestion date.
• Colocated popover.test.tsx, popover.types.test.ts, and popover.stories.tsx.
• Snapshot coverage where the visual contract is state-dependent, or a recorded
  exemption.
• Explicit exports from src/index.ts, with src/index.test.ts updated.
• A changeset, per the repository's version management rules.
• A recorded readiness level with its supporting evidence.

Required coverage, stories, and platform validation

Runtime and type coverage:

• Open and closed, controlled and uncontrolled.
• Each positioning direction, plus the edge-flip behavior.
• Arrow present and absent, and arrow inset within the container radius.
• Light dismiss on outside press and on Escape.
• Focus returns to the trigger on close.
• Trigger accessibility state reflects open and closed.
• User style and handler forwarding, and that user styles are applied after component
  styles.
• Compile-time slot acceptance and any mutually exclusive props.

Stories: a typed Meta titled Components/Popover, an args-driven Default, a
grouped Overview when the contract has several axes, one focused story per variant
axis, and an interactive story for each stateful axis. Self-driving axes expose
default<State> as the control; externally driven selection is owned by the story with
React.useState. Identity-changing axes are not exposed as controls.

Platform validation: the component's stories render and behave correctly on macOS
and on React Native Windows Fabric through apps/storybook,
including hover, pressed, disabled, focus, optional-slot, and constrained-content
scenarios. Add a stable root testID if the component joins the automated smoke set.

Acceptance criteria

• src/components/popover exists with the required file structure and a displayName.
• Every variant axis in the component's SPEC.md is implemented, or a deviation is recorded in the spec.
• The component styles from Flex tokens, with any genuine token gap recorded rather than approximated.
• Focus feedback renders through FocusVisual; no outline* props and no React Native Windows native focus visuals are introduced.
• State precedence is explicit: disabled wins over pressed, which wins over hovered.
• Every stateful axis is classified as self-driving or externally driven, and both paths are covered.
• Runtime, type, and story coverage satisfy the package coverage contract.
• The component, its public types, and its pipeline stages are exported explicitly from src/index.ts, and src/index.test.ts covers them.
• The component's stories render on macOS and on React Native Windows Fabric.
• yarn workspace @fluentui-react-native/components format, lint, build, and test pass, and the Storybook bundle succeeds for both desktop platforms.
• A readiness level is recorded with its supporting evidence.
• A changeset is included.

Dependencies and ordering

• Gated by component-test-strategy.md: the component must satisfy the coverage contract on arrival rather than being retrofitted.
• Gated by readiness-model.md: the target readiness level must be stated before the work starts.
• Consumes the Infrastructure workstream (storybook-e2e.md) for automated macOS and Windows Fabric validation; until it lands, platform validation is manual.

Risks and open decisions

1. The overlay strategy decision determines whether the agentic package acquires a native dependency, which conflicts with its documented source boundary in src/AGENTS.md. This is the central open decision of wave 2.
2. Edge-aware positioning requires measurement, which on React Native is asynchronous and can produce a visible first-frame jump. The mitigation must be part of the contract.
3. Windows Fabric and macOS differ in how an overlay interacts with window bounds and with focus; both need on-device validation before the dependent components are built.

Evidence and references

• Upstream spec: plugins/components/skills/popover/SKILL.md and
  components-index/SKILL.md
  at x3-design/fluent-design @ d334acf.
• Local staged spec and blocker record: packages/agentic/components/specs/popover.
• Canonical implementations to follow: src/components/button
  for a styled higher-order component and src/primitives/icon
  for a primitive.
• Authoring rules: src/components/AGENTS.md and the
  agentic component authoring skill.
• Workstream context: Components README and
  the missing-components index.

Sources retrieved 2026-08-20.

Start with packages/agentic/components/specs/popover/SPEC.md, interaction.md, accessibility.md, blockers.md, and src/components/AGENTS.md; compare the native Callout and experimental Popover implementations. Then inspect the existing component tests, stories, src/index.ts, and src/index.test.ts patterns. Done means the required component structure, contract, coverage, stories, platform validation, exports, changeset, and readiness evidence are present.