跳转至

Popover component contract

Intent

Popover presents interactive, caller-supplied content in an anchored top-layer surface. The component owns the standard trigger-to-surface composition; usePopover exposes the same semantic lifecycle, focus containment, dismissal, and rendering contract for custom compositions.

This contract records the behavior present after PR #5373, the Popover target direction settled by Cindy Zhang on 2026-08-31, the focus/opening correction approved by Cindy Zhang on 2026-09-07, and the move of viewport fitting to the layer runtime decided by Cindy Zhang on 2026-10-03 (spec:AST-059). Public API signatures and release status remain unchanged. Consumer syntax and complete signatures remain owned by Popover.doc.mjs and usePopover.doc.mjs. The canonical popover target is the only broad Popover surface target.

DEC-4 below (pending owner review) adds one public concept: the surface padding rung, so a caller whose content owns its own edges can ask for a flush surface.

Compatibility and migration

  • Released default preserved: yes
  • presentation (DEC-6) defaults to popover, the released anchored surface; presentation="popover" is also the value that keeps it wherever a touch default would otherwise apply (architecture:public-component-api INV16, spec:AST-017 FR3, DEC-23).
  • Canonical target: popover owns the broad painted-surface contract for <Popover> and public usePopover compositions
  • Removed alias: 0.7.0 removes popover-surface; themes and CSS selectors migrate it to popover with astryx upgrade --from 0.6.3 --apply --path .
  • Composed components: component-specific surface targets such as selector-popup and multi-selector-popup remain authoritative refinements beside the broad canonical target
  • New hook consumers: a direct usePopover composition that needs its own theme reachability provides and documents an owned surfaceTarget

Current-state impact

  • The input hold starts on the first frame after the open; a touch landing within that frame reaches the page.
  • Popover has no viewport-rectangle anchor: it anchors to its trigger or to a button through anchorRef. A panel whose control moved into a More menu anchors to the More trigger through a usePopover composition whose triggerRef receives that trigger, so the trigger keeps its menu-button attributes (component:MoreMenu AR1). This is revisited once the headless context menu's open(at) (spec:AST-107 FR8) ships.

Ownership boundary

Owns

  • The standard trigger or referenced-anchor composition, the painted Popover surface, the canonical broad popover theme target for that surface, and the slot that renders caller-supplied content inside it.
  • The public usePopover semantic contract: visibility operations, trigger bindings, surface rendering, dialog semantics, focus containment, and lifecycle notifications.
  • Popover-specific focus destination selection, the preferred size (an explicit width, else the trigger's minimum width), conditional internal scrolling, and the measurement lifecycle needed to support them.
  • The current fallback close control appended by the hook.

Does not own / non-goals

  • Trigger presentation and caller content presentation — caller-owned.
  • Component-specific surface refinement targets — owned and documented by the composed component; Popover supplies only the shared baseline target contract.
  • Generic top-layer hosting, native popover lifecycle reconciliation, anchor positioning, portal/context selection, and same-gesture reopen protection — owned by architecture:layer-runtime.
  • The viewport inset — the gutter and safe-area insets, the size caps, the fallback order including the slide and its anchor-visibility condition, and the app-declared inset — owned by architecture:layer-runtime through spec:AST-059. Popover clamps its own preferred size with the runtime's cap and adds nothing of its own.
  • Shared Escape and platform-close ordering — owned by family:overlay-dismissal.
  • The shared focus-trap algorithm outside Popover-specific destination choice — owned by useFocusTrap.
  • Hover previews and brief helper text — owned by HoverCard and Tooltip.

Public surface and package boundary

The installable root package and @astryxdesign/core/Popover subpath expose the full Popover public surface. The backward-compatible Layer entry point re-exports Popover, usePopover, UsePopoverOptions, UsePopoverReturn, and PopoverProps; PopoverTriggerRenderProps is exposed through the Popover package surface, not the Layer entry point. There is no installable Popover/usePopover implementation subpath.

Public concepts

Concept Closed values or states Meaning Availability Default Owner Stability Invalid or unsupported behavior
Trigger composition Wrapped trigger, render-prop trigger, or referenced anchor Supplies the anchor and the control that opens or closes the standard component Popover Wrapped trigger when children are supplied component:Popover Current public behavior A referenced or wrapped anchor without a button or button role warns in development and receives no trigger handler; it does not throw.
Visibility ownership Uncontrolled or externally controlled Chooses whether Popover stores visibility or synchronizes to caller state Popover Uncontrolled component:Popover Current public behavior Controlled changes are synchronized through show/hide; dismissal requests are reported to the caller rather than redefining the external source of truth.
Popup semantics Dialog or neutral wrapper Exposes dialog semantics or lets child menu/listbox semantics own the popup Popover and hook Dialog component:Popover Current public behavior A dialog without a label warns in development. Neutral mode omits dialog role and modal semantics.
Focus entry Automatic or caller-preserved Focuses genuine caller content, falls back to the labeled dialog surface when none exists, or preserves current focus Popover and hook Automatic component:Popover Current public behavior The injected fallback close control is excluded from initial-focus candidates and reveals only when reached sequentially.
Dismissal Outside/Escape enabled or disabled within native constraints Controls light dismiss and explicit Escape participation Popover and hook Both enabled component:Popover; family:overlay-dismissal owns Escape/platform-close ordering Current public behavior Disabling Escape alone cannot override the native Escape behavior of an auto popover; explicit-dismiss behavior requires light dismiss to be disabled too.
Presentation popover, bottom-sheet, or adaptive Chooses the surface that holds the content: anchored, a BottomSheet, or a BottomSheet on a compact touch screen Popover popover component:Popover; component:BottomSheet owns the sheet Decided (DEC-6) —
Surface treatment Default surface or caller-owned treatment Applies the shared painted surface and optional consumer styling Popover and hook Default surface component:Popover Current public behavior Custom styling does not change lifecycle, focus, or dismissal semantics.
Surface padding A spacing-scale step, 0 through 10 Sets the inset the painted surface keeps around caller content; 0 is a flush surface for content that owns its own edges Popover and hook Popover: step 3; hook: none component:Popover Pending owner review (DEC-4) The rung lands on the painted surface, so a theme's padding on the popover target replaces it rather than nesting; consumer xstyle merges after it.
Surface target ownership Shared baseline or component-specific refinement Assigns popover as the broad surface owner and lets a composed component add its own target on that same element Popover and hook popover baseline; no component-specific refinement component:Popover; the composed component owns its refinement target Current compatibility contract popover-surface is compatibility output, not a new target for consumers or a second anatomy owner.
Placement and preferred size Logical placement/alignment plus preferred width Positions the anchor surface and states the size Popover prefers; the layer runtime fits it to the viewport Popover and hook renderer Below/start; Popover matches trigger minimum width when no width is supplied component:Popover for the preference; architecture:layer-runtime for the fit Current public behavior An explicit width renders at its size up to the viewport minus gutters; it is never shrunk to the room beside the trigger (spec:AST-059 FR2).

Public usePopover semantic inputs

Consumer syntax, exact names, and types remain in usePopover.doc.mjs; this table owns their semantic effect.

Input concept Default Effect and lifetime Invalid or unsupported behavior
Show and hide notifications Absent Fire after the hook updates its visibility for an imperative or reconciled browser transition. They remain active for the mounted hook instance. No callback is fired when no transition occurs. Callers own any focus return they add in a hide notification.
Surface styling No consumer override Merges consumer StyleX, class, and inline styles onto the painted surface for every rendered lifetime. Styling cannot move ownership to the positioned outer layer; positioning styles belong to the renderer's layer props.
Light and Escape dismissal Enabled Escape dismissal registers through the focus trap when enabled; outside light dismiss uses native popover="auto" and is not shared-stack coordinated. Escape disablement is only complete when native light dismiss is also disabled.
Automatic focus Enabled Focuses the first genuine caller content control for each accepted opening unless that opening requests preservation; a dialog with none falls back to its surface. The injected fallback close control is never an initial-focus candidate.
Fallback close control and label Included; “Close popover” Appends an end-of-trap close control for each rendered surface. When omitted, the hook does not synthesize another close affordance.
Popup role, label, and modality Dialog, modal, no implicit label Stamps semantics on the painted surface for its rendered lifetime. Neutral role suppresses dialog and modal semantics. Missing dialog label warns in development rather than throwing.
Default surface Enabled Applies the shared background, radius, and elevation treatment while rendered. Turning it off delegates painting to caller content but does not turn usePopover into a different lifecycle primitive.
Surface padding None Applies one spacing-scale rung on every edge of the painted surface while rendered. Popover passes its own default of 3; a direct hook composition paints no padding unless it asks for a rung. The rung is not a container-protocol enrollment: the surface publishes no edge geometry to its content.
Optional component surface target No component-specific refinement Adds a component-owned refinement target beside the canonical popover target on the same rendered surface. New direct hook consumers provide and document one only when they need distinct theme reachability. surfaceTarget does not create another surface or owner. Do not pass or depend on deprecated popover-surface.

Public usePopover semantic outputs

Output concept Meaning and lifetime
Trigger binding While the popover shows or animates out, the attached trigger is its anchor; ARIA trigger state tracks the current role and open state; a stable anchor identifier supports advanced composition. Detaching removes the anchor.
Visibility operations show, hide, and toggle are the canonical operations for the mounted hook instance. Public signatures remain unchanged, and every opening path inherits same-gesture reopen protection.
Open state Reflects the hook's reconciled visibility. Browser-initiated close is observed on the queued native toggle event, so DOM visibility may lead React state briefly.
Surface binding A content ref identifies the focus-trap surface while mounted.
Renderer Produces the positioned layer and painted surface around caller content, including focus containment and the optional fallback close control. The renderer must remain in the React tree for the surface to exist.
Surface identifier A stable identifier connects the trigger's control relationship to the rendered surface for the hook instance.

Side effects and lifetime

  • While the popover is shown, and until its exit animations end, the attached trigger carries the CSS anchor name used by the Layer runtime (architecture:layer-runtime INV18). Detaching the trigger removes it.
  • Every opening path applies same-gesture reopen protection before changing visibility. A rejected opening does not invoke onShow.
  • Successful visibility operations call the browser popover methods when available, update hook state, and invoke the corresponding lifecycle notification. Native close events reconcile back into that same state model.
  • The default context layer keeps its mounted host while closed after initial resolution; open state, not host existence, controls visibility. Lazy mounting remains a Layer-level option rather than a separate Popover contract.
  • Popover component trigger handlers and ARIA state exist only while the trigger is mounted and enabled. Disabling Popover ignores its trigger interaction; it does not disable the caller's trigger element.

Behavioral and layout contract

ID Invariant Basis Acceptance and implementation state
FR1 Popover and public usePopover expose one visibility lifecycle with canonical show, hide, and toggle operations. Every opening path inherits same-gesture reopen protection without changing public signatures. Current public package surface, architecture:layer-runtime/INV7, and owner approval on 2026-09-07 Accepted; implemented and covered by focused Popover-family tests
FR2 Popover derives semantic focus entry identically across activation modalities: first genuine caller content in document order, tab stops before members that hold tabindex="-1", then labeled dialog-surface fallback. The injected close control is excluded. Shared interaction modality controls focus indication, not destination. PR #5373, architecture:interaction-modality, and owner approval on 2026-09-07 Accepted; implemented and covered by Popover focus tests
FR3 Retired. Viewport and safe-area capping is the layer runtime's (spec:AST-059 FR2, FR3); Popover clamps its preferred size with the runtime's cap and caps its painted surface with the same definition. spec:AST-059, owner direction 2026-10-03 Retired; see architecture:layer-runtime INV11 and the Core/Layer viewport-inset stories
FR4 Popover enables internal scrolling only after measured overflow exceeds the current tolerance. Fitting content does not become a scroll container. PR #5373 and current tests Verified current behavior
FR5 Overflow signals while open coalesce into at most one measurement per animation frame, and Popover owns no measurement observers while closed. PR #5373 and current tests Verified current resource behavior
FR6 Component anatomy contains the caller trigger and content, one painted Popover surface, and the optional fallback close control. Popover owns no Header, Body, or separate shared-hook surface part. Current source, docs target inventory, and tests Accepted anatomy; stale consumer anatomy corrected by this contract
FR7 The painted surface has one broad canonical target, popover; composed components may add one authoritative component-specific refinement target. Owner direction on 2026-08-31 plus current target inventory Accepted canonical contract; covered by focused target tests
FR8 The surface padding is one spacing-scale rung applied on the painted surface. Popover defaults to step 3 (the released inset); 0 paints a flush surface; a direct usePopover composition paints none unless it asks for a rung. The rung sits where a theme's padding on the popover target replaces it. PR #6683 and its Popover tests; architecture:container-padding/INV8 (padding alone does not enroll) Pending owner review (DEC-4); implemented and covered by the Popover surface-padding suite
FR9 Under a finger, Popover grows from its trigger on --duration-medium-min, the Storybook step nearest iOS's 206 ms growth, with --ease-entrance (spec:AST-094 FR45), and shrinks back on the theme's exit duration and easing. A touch while it grows is ignored (FR35). Dismissal and a mouse's entrance are unchanged. spec:AST-094 FR31, FR35 Implemented
FR10 Under forced colors, the painted surface keeps a visible edge, a 1 px system-colour (CanvasText) border, so it stays apart from the page when forced colors drop its shadow (spec:AST-020 FR1, WCAG 2.2 SC 1.4.11). Every surface usePopover paints, DropdownMenu's included, does the same; the ContextMenu surface and DropdownMenuSubMenu flyouts paint their own surface and keep the same border. Outside forced colors the edge sets no border width, style or colour, so each surface keeps its own border or a caller's. spec:AST-020 FR1; component:Dialog FR9 Implemented

Allowed variation

  • AV1 — Trigger composition. Wrapped, render-prop, and referenced-anchor modes may attach the same semantic trigger behavior without changing the surface contract.
  • AV2 — Popup semantics. Dialog mode may focus the dialog container; role-neutral popups let their child role and content focus model remain exposed.
  • AV3 — Surface treatment. The hook may omit its default paint, change the surface padding rung, or add a component-owned refinement target while preserving the canonical popover ownership, lifecycle, focus containment, and dismissal model.
  • AV4 — Placement. Logical placement, alignment, and preferred width may change geometry without changing the overflow precedence below; the fit against the viewport is the layer runtime's.

Representative focus and dismissal states

State Required invariant Allowed variation
Pointer or touch activation of dialog Popover Initial focus enters the first genuine content control, with dialog-surface fallback when none exists. Shared modality-aware indication suppresses keyboard-only rings after pointer input. The trigger and content may vary.
Keyboard or AT-style activation of dialog Popover Initial focus enters the first genuine content control, with dialog-surface fallback when none exists. The eligible destination paints the shared keyboard focus indication. Activation with absent or zero event detail follows this path. Named AT announcement remains unverified.
Read-only dialog With no genuine caller control, the dialog surface receives initial focus. The injected fallback close control remains hidden and reachable by Tab but is never selected initially. Caller content may contain no tabbable control.
Neutral-role popup The neutral wrapper is not selected as a dialog focus target; automatic entry prefers genuine content focus, or callers may disable autofocus for trigger-retained patterns. Child menu, listbox, or other semantics own their focus model.
Automatic focus disabled Opening does not move focus. May be persistent configuration or a one-opening show preference.
Controlled open External open state invokes the no-activation opening path: first genuine content control, then dialog-container fallback. The caller remains the visibility source of truth.
Tab or Shift+Tab inside the open popup Focus moves to the next or previous tabbable descendant and wraps at either end, so it stays inside the popup, modal or not. It wraps with or without Alt (Option); Tab chorded with Ctrl or Meta passes through to the browser. A role-neutral menu closes on Tab and a listbox keeps focus in its input, as their own records state.
Tab or Shift+Tab from outside the open popup The popup does not capture it: focus moves to the next or previous control in the page's own order, as if the popup were not there. The browser's order, which places an anchored popup after its trigger, may still lead into it.
Tab from a focused container Focus enters the first tabbable descendant. If none exists, focus remains inside.
Shift+Tab from a focused container Focus enters the last tabbable descendant. If none exists, focus remains inside.
Escape The topmost eligible Popover closes according to shared dismissal policy. Explicit-dismiss surfaces may disable both light and Escape dismissal.
Close after focus entered the popup Focus returns to the trigger when removal would otherwise strand focus. A caller may additionally own focus return through its hide notification.

Transformation and precedence order

  • ORD1 — Visibility operation. toggle selects the existing show or hide transition; it is not a second lifecycle. Every opening path applies same- gesture protection before visibility changes. Public show retains its existing one-opening skipAutoFocus preference; otherwise Popover derives genuine content focus and its safe surface fallback.
  • ORD2 — Preferred inline size. An explicit width wins over trigger matching. Without explicit width, Popover prefers trigger minimum width. Either preferred size is clamped by the layer runtime's viewport cap (spec:AST-059 FR7); neither is capped to the room beside the trigger.
  • ORD3 — Retired. The viewport fit — gutters, caps, flips, and the slide — is the layer runtime's (spec:AST-059 FR1–FR5). Popover's painted surface reads the runtime's cap so overflow state is evaluated against the same bound the layer applies.
  • ORD4 — Conditional scroll. Measured overflow greater than 1 px enables internal scrolling and overscroll containment; fitting content leaves both disabled.

Performance and resources

  • PR1 — Open-only observation. Resize, mutation, captured resource-load, window-resize, and visual-viewport-resize observation exists only while the Popover component is open; cleanup disconnects listeners and observers and cancels pending work.
  • PR2 — One measurement per frame. Repeated signals while a measurement is pending coalesce into one animation-frame callback.
  • PR3 — Stable state update. Measurement updates overflow state only when the overflow boolean changes.
  • PR4 — Touch presentation frames. On a page with no other frame work, the touch growth and shrink do no Layout or Paint per frame. Known platform cost: in Chromium, a page with its own requestAnimationFrame loop makes an anchored, animating layer lay out and paint every frame.
  • PR5 — The touch growth's first frames. Under a finger, the growth starts at opacity 0.001 rather than 0, since Chromium skips drawing a layer at exactly 0. The first frame then shows its content, and no 8-bit pixel differs from transparent.

Accessibility contract

  • AR1 — Trigger relationship. The trigger exposes expanded state, the popup relationship, and a role-appropriate popup type while mounted.
  • AR2 — Dialog naming. Dialog mode requires a caller-provided accessible label and places dialog/modal semantics on the painted surface. Missing naming warns in development but does not synthesize a label.
  • AR3 — Focus containment and indication. Every Popover is a focus region, modal or not (DEC-9). Automatic entry and Tab/Shift+Tab behavior follow the matrix above: containment holds focus that is inside the popup, and a Tab that starts outside it is never redirected into it. isModal changes only the modal semantics. A trapped surface with no tabbable descendant does not let focus escape. Eligible focus destinations use the shared modality-aware focus indication rather than changing semantic focus placement to suppress pointer outlines.
  • AR4 — Focus return. Dismissal returns focus to the trigger when focus had entered the closing Popover and would otherwise be lost.
  • AR5 — Evidence boundary. Current automated tests establish DOM roles, ARIA state, focus movement, and focus return. The Storybook manual-AT story is a fixture, not a recorded result. PR #5373 records no named NVDA + Chrome or VoiceOver + Safari announcement result, so this contract makes no AT announcement claim.

Design relationships

Anatomy or state Design requirement Representation authority Hierarchy role Component contract
Trigger element Supplies or references the control and anchor without becoming Popover-owned presentation. Caller content Supporting FR6, AR1
Popover surface Paints the component surface, owns the canonical popover target, and carries scroll, focus, and dialog behavior. Current source and owner DEC-2 Prominent FR2, FR4–FR7, AR2–AR4
Touch sheet Holds the same content in place of the surface when presentation resolves to bottom-sheet; paints BottomSheet's bottom-sheet target. component:BottomSheet Prominent DEC-6, AR1, AR4
Popover content Renders caller-supplied interaction or information inside the surface. Caller content Prominent FR2, FR6
Fallback close control Provides an end-of-trap close affordance without becoming the initial focus destination. component:Button Supporting FR2, AR3

Theming anatomy

{
  "Trigger element": {
    "none": {
      "reason": "intentional: The trigger is caller-owned and receives no Popover theming target."
    }
  },
  "Popover surface": {"target": "popover"},
  "Touch sheet": {
    "delegatesTo": {"owner": "component:BottomSheet", "target": "bottom-sheet"}
  },
  "Popover content": {
    "none": {
      "reason": "intentional: Caller-supplied content is caller-owned; normal CSS may inherit from the surface, but Popover provides no content target."
    }
  },
  "Fallback close control": {
    "delegatesTo": {"owner": "component:Button", "target": "button"}
  }
}

Popover surface and Touch sheet are alternative presentations of the same content, not simultaneous anatomy.

Any element the open touch sheet renders beyond the anchored popover under a fine pointer is part of BottomSheet's frame, with its job in component:BottomSheet's element jobs, within the open-layer allowance of spec:AST-017 FR60 (DEC-29). Popover adds only its fallback close control to the sheet, as the Button itself.

Every public usePopover painted surface belongs to the broad popover target. A composed component may add its own authoritative refinement target, such as selector-popup or multi-selector-popup, on that same element. New direct hook consumers that need distinct theme reachability provide and document an owned surfaceTarget.

Family and system relationships

  • architecture:public-component-api owns installable reachability and the distinction between public package API and source-level implementation seams.
  • architecture:layer-runtime owns the shared host, native popover lifecycle, anchor geometry, the viewport inset (spec:AST-059), portal/context behavior, and same-gesture dismissal guard; Popover owns its preferred size, overflow, and focus composition above that runtime.
  • architecture:interaction-modality owns shared modality classification and focus-indicator visibility. Popover owns semantic focus entry and fallback; pointer input does not select a different destination merely to hide an outline.
  • architecture:component-theming-surface owns anatomy qualification and target placement. popover is the one broad target on the painted surface. Caller content adds no target, the fallback close control delegates to Button's target, and composed components own any additional surface refinement target.
  • family:overlay-dismissal owns topmost Escape and platform-close ordering. Popover participates through the shared layer owner while retaining its local focus, outside-dismiss, and open-state behavior.

Verification map

Contract Verification Representative states Mutation or failure expectation Audit section
Public boundary, FR1 Popover.test.tsx compile-time public-surface assertions plus package/barrel inspection Unchanged public signatures and same-gesture rejection across Popover-family openings A public type changes or a same-gesture request reaches visibility state. audit:Popover/api
FR2, AR2–AR4 Popover.test.tsx focus/role suites and useFocusTrap.test.tsx container-entry suites Pointer, keyboard/AT-style, read-only, neutral role, no autofocus, controlled, Tab/Shift+Tab, Escape, focus return Changing semantic destination by modality, selecting fallback close initially, losing shared indication, or allowing focus escape fails assertions. audit:Popover/accessibility
FR2, user activation Popover.test.tsx "focuses the first content control within the click that opens it" and "keeps focus that onShow moves inside the popover"; real Chromium with mobile (touch) emulation A tap or click opens a popover whose content is mounted: initial focus lands within that event (iOS raises its on-screen keyboard only for a focus made while the tap is handled); focus that onShow or a press placed inside is kept Initial focus that waits for a later frame, or a frame that moves focus already inside the popover, fails assertions. audit:Popover/accessibility
AR3, DEC-9 useFocusTrap.test.tsx and Popover.test.tsx focus-region suites Modal and non-modal; Tab and Shift+Tab inside the popup and from a control outside it A Tab outside that the popup pulls into itself, or a Tab inside that leaves it, fails assertions. audit:Popover/accessibility
ORD2, FR4 Popover.test.tsx sizing/overflow suites; Popover.stories.tsx match-trigger and overflow scenarios; geometry under Core/Layer viewport-inset stories Explicit width clamped to the viewport, trigger matching, fitting and overflowing content Reversing width precedence, capping to the span beside the trigger, or always enabling scroll fails emitted-style or overflow assertions. audit:Popover/layout
FR8 Popover.test.tsx surface-padding suite Default rung, 0, an explicit rung, a direct hook composition with and without a rung A default other than step 3, a rung landing on a box inside the surface, or the hook painting a rung it was not given fails the suite. audit:Popover/theming
FR9 spec:AST-094 verification for FR31 and FR35 Under a finger: open, close, a touch during growth; a mouse A Popover that does not grow from and shrink into its trigger, a changed dismissal, or a changed mouse path fails. audit:Popover/behavior
FR10 OverlayEdges.forcedColors.a11y.chromium.spec.ts (Chromium, forcedColors: 'active'); usePopover.forcedColorsEdge.test.tsx (the surface sets no border width or style outside forced colors) Popover, DropdownMenu, a DropdownMenu submenu flyout, ContextMenu, and a modal Dialog and AlertDialog open; a fullscreen Dialog; the same with forced colors off A surface with no visible border in forced colors, a fullscreen Dialog gaining an edge or overflowing the viewport, or any border added outside forced colors fails. audit:Popover/accessibility
PR4 spec:AST-094 verification for FR5 The touch growth and shrink in a Chromium trace, on a page with no other frame work A Layout or a Paint during either motion on such a page audit:Popover/resources
PR5 PopoverTouchMotion.interaction.browser.spec.ts "the growth shows its content from its first frames", from the compositor's record of each frame it presents (Chromium) A tap that opens the popover; a tap outside while it grows A growth whose first opacity keyframe is 0 presents a frame without the popover's content among its first five audit:Popover/resources
FR5 Popover.test.tsx scheduling and observer-lifecycle suites Closed, opened, repeated signals, cleanup Constructing observers while closed or measuring more than once per pending frame fails lifecycle assertions. audit:Popover/resources
FR6, FR7 and theming anatomy Popover.test.tsx, Popover.doc.mjs, usePopover.doc.mjs, astryx theme targets Popover --json, and scripts/check-knowledge.mjs One real surface with canonical popover plus composed-component refinements A fake anatomy part, missing canonical output, or an active target without a real owner fails review or validation. audit:Popover/theming
AR5 Popover.stories.tsx manual-AT fixture and PR #5373 test record Read-only dialog manual-AT fixture; no recorded NVDA/VoiceOver announcement result A fixture without recorded AT/browser observations cannot be cited as announcement proof. audit:Popover/at-evidence
Presentation (DEC-6, DEC-8) PopoverPresentation.test.tsx Default on a phone, adaptive on a phone and a desktop, forced sheet, close, controlled, dismissal mapping A sheet on a default phone popover, an anchored popover where the sheet is asked for, or a trigger state that ignores the sheet fails. audit:Popover/api

Decision log

DEC-1 — One canonical visibility operation model

Reference: component:Popover/DEC-1

Decider: Cindy Zhang, 2026-08-31

Showing, hiding, and toggling are one visibility lifecycle. Every opening path inherits same-gesture reopen protection. Popover derives semantic focus entry; public show({skipAutoFocus: true}) remains the existing escape for a custom composition that owns focus outside the Popover. Public signatures are unchanged.

Rejected: making interaction modality a focus-destination option. Modality owns focus indication, while Popover owns semantic focus placement.

DEC-2 — One canonical Popover surface target

Reference: component:Popover/DEC-2

Decider: Cindy Zhang, 2026-08-31

popover is the broad canonical theming baseline automatically owned by every painted surface created by <Popover> or public usePopover. The temporary popover-surface compatibility name is removed in 0.7.0 under architecture:component-theming-surface; existing themes migrate that key and selector to popover.

Composed components keep authoritative refinement targets such as selector-popup and multi-selector-popup. Optional surfaceTarget adds that owned refinement on the same surface; it does not replace the broad popover baseline. New direct hook consumers that need distinct reachability provide and document an owned target.

Rejected: treating popover and popover-surface as two durable sibling targets, or inventing a “Shared hook surface” anatomy part to satisfy inventory coverage. Both make one painted element look like two design concepts and preserve an accidental implementation name as permanent public structure.

DEC-3 — Focus indication does not change semantic focus placement

Reference: component:Popover/DEC-3

Decider: Cindy Zhang, 2026-09-07

Popover uses one content-first semantic focus policy across pointer, keyboard, and assistive-technology activation. The shared interaction-modality system owns whether the eligible destination paints a keyboard focus indicator. The injected fallback close control is excluded from initial focus and reveals only when reached through sequential keyboard navigation; a labeled dialog surface is the fallback when caller content has no genuine control.

Every Popover-family opening inherits same-gesture reopen protection through the visibility lifecycle. Public API signatures remain unchanged.

Rejected: moving focus to the dialog surface on every pointer opening solely to avoid a keyboard-looking outline. That mixes visual modality with semantic focus placement and bypasses the shared focus-indication owner.

DEC-6 — Presentation: the anchored popover, a sheet, or adaptive

Reference: component:Popover/DEC-6

Decider: cixzhang, 2026-10-25

Popover takes presentation with the vocabulary the menus already use: popover, bottom-sheet, or adaptive. popover is the default and the released anchored surface. bottom-sheet presents the content in a BottomSheet. adaptive chooses exactly as the menus do: the sheet under spec:AST-094 FR13's touch rule, with compact governed by spec:AST-012 FR9, and the anchored popover elsewhere.

DEC-8 — The sheet Popover presents: label, size, dismissal and loading

Reference: component:Popover/DEC-8

Decider: cixzhang, 2026-10-25

In a sheet, Popover's content is labeled by its label, or by the trigger's text when it has none, so the dialog always has a name. The sheet always light-dismisses: a tap outside it or a swipe down closes it, whatever hasLightDismiss says, so a finger always has a way out. Its fallback close stays hidden, as in an anchored popover. Everything else follows Popover's existing props. The sheet of DEC-6 is a modal BottomSheet at the sheet's tall height and inset by Popover's padding, below the grab bar's band at the top (component:BottomSheet, Content area inset); xstyle, className and style style its panel, and placement, alignment and width do not apply. The surface is chosen when the popover opens and stays until it closes, and the trigger's expanded state and controlled element follow whichever surface is open. The sheet loads on demand, so pages whose popovers stay anchored do not load it.

DEC-9 — A Popover is a focus region, modal or not

Reference: component:Popover/DEC-9

Decider: cixzhang, 2026-10-26

A Popover is a focus region like a dialog's. While focus is inside it, Tab and Shift+Tab cycle through its controls, and a dismissal closes it and returns focus to the trigger (AR4). It leaves the rest of the page's focus order alone: a Tab pressed outside it moves to the next control in the page and is never pulled into the popup, and a non-modal Popover leaves the page interactive. This holds for modal and non-modal popovers alike. A role-neutral popup keeps its child role's own Tab model, so a menu still closes on Tab and a listbox's focus stays in its input.

Rejected: no Tab containment for non-modal popovers, which would let focus fall out of an open popup into the page behind it.

Verification gaps

These implementation and evidence items remain required follow-up, but they do not block acceptance of the semantic contract above.

  • VG1 — Real browser behavior. Unit tests assert emitted sizing styles and synthetic dimensions, not rendered viewport layout. Rendered viewport geometry is covered by the Core/Layer viewport-inset stories under the story play guard; native popover light dismiss, top-layer ordering, rendered focus behavior, and focus-indicator modality still require real Chromium/WebKit evidence when changed.
  • VG2 — AT announcement. The current story provides manual instructions, but named NVDA + Chrome and VoiceOver + Safari results are absent. No announcement outcome is claimed.

Open questions

None. DEC-1 settles the visibility model, DEC-2 settles canonical target ownership, DEC-3 settles semantic focus versus modality-aware indication, and DEC-9 settles focus containment for modal and non-modal popovers. The remaining items are verification work, not human API questions.

Content boundary

This file does not duplicate consumer signatures, prop tables, examples, implementation steps, shared layer algorithms, or family dismissal rules. It links to their owners and records only Popover-specific semantics, boundaries, and invariants.

DEC-4 — Surface padding is a spacing-scale rung on the painted surface

Reference: component:Popover/DEC-4

Decider: pending owner review (proposed in PR #6683)

The surface padding becomes a public concept: Popover takes padding on the shared spacing scale (0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10, the same shape Card, Stack, LayoutContent and LayoutPanel use), defaulting to the released step 3; usePopover takes the same option and paints no padding unless given one, which is the hook's released behavior. 0 is a flush surface for content that owns its own edges — a list of rows whose hover paint reaches the edge, a header row with a bottom rule.

The rung is applied on the painted surface, not on a wrapper inside it, so a theme's padding on the popover target keeps replacing it instead of nesting (the placement DEC-2 already fixed for the surface). This does not enroll Popover in the container padding protocol: the surface publishes no edge geometry to its content (architecture:container-padding/INV8).

Rejected: a 'none' string beside the rungs. The nearest existing vocabulary spells the flush case as 0 on the numeric scale, and a second spelling of the same value would leave two ways to write one state. Also rejected: moving the padding onto an inner content wrapper a consumer class can replace — that turns the released theming placement back into a nested box.

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx