Skip to content

spec(popover): isModal keeps its released meaning, and usePopover takes tabBehavior (AST-116) - #13015

Draft
nynexman4464 wants to merge 6 commits into
mainfrom
nynexman4464/spec/ast-116-tab-behavior
Draft

nynexman4464 wants to merge 6 commits into
mainfrom
nynexman4464/spec/ast-116-tab-behavior

Conversation

@nynexman4464

@nynexman4464 nynexman4464 commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Stack: #11117 → #11121 → #13015

Top of the stack, on #11121; this PR's own change is its last commit: four records, no code. #11156 and #12891 are out of the stack until they are rebuilt on this record.

Exact decision needed

Whether isModal: false keeps its released meaning, and whether a popover that Tab passes through gets its own usePopover input:

  1. isModal sets aria-modal on a dialog popover and nothing else. Tab stays in the popover whether it is true or false, as released.
  2. tabBehavior: 'contain' | 'pageOrder' on usePopover only, default 'contain'. 'pageOrder' is the behavior spec:AST-116 gave to isModal: false: Tab follows the page, Escape applies only while focus is in the popover's scope, and there is no aria-modal. FR15 also states how such a popover closes, which the record did not say before:
    • a press outside closes it when hasLightDismiss is on;
    • a touch pan outside does not;
    • it stays open when another popover or a modal dialog opens without a press outside it;
    • hasEscapeDismiss: false turns its Escape off whatever hasLightDismiss says.
  3. Every sheet is the released modal sheet. The non-modal sheet goes: presentation is a Popover prop and tabBehavior is a hook input, so no sheet can have 'pageOrder'.

spec:AST-116 DEC-5 made isModal: false the switch for no Tab containment. No code for it has merged, so this record changes before any released behavior does.

Existing authority searched

  • component:Popover DEC-9 (current; decided by cixzhang, who owns that record): "A Popover is a focus region, modal or not", with "no Tab containment for non-modal popovers" rejected. spec:AST-116 DEC-5 superseded it for isModal: false. DEC-11 keeps DEC-9's rejection for every isModal value and makes one exception, a 'pageOrder' popover.
  • component:Popover DEC-8 (current; also cixzhang's): the sheet is modal and always light-dismisses. FR16 superseded it for isModal: false. It governs every sheet again, and its amendment line goes.
  • spec:AST-116 FR12–FR16, FR22 and DEC-5: the claims this PR changes. DEC-5 rejected a separate focus-region input; DEC-11 adopts a separate input, and DEC-5's new amendment line says so.
  • architecture:public-component-api INV2 and INV3: a prop that chooses how a component responds to input is a <thing>Behavior closed union (INV2), and a new behavior prop defaults to the shipped behavior (INV3). tabBehavior follows both. INV2 lists pointer and touch words that a behavior prop's name must not hold; a key name is not among them, and the Tab key is this prop's subject on every device with a keyboard.
  • family:overlay-dismissal FR2 and FR3: the Escape presence exception, keyed on 'pageOrder' in place of "non-modal".
  • spec:AST-119 FR14 and DEC-6: a tour step without a backdrop is the 'pageOrder' popover. FR14 says so, and DEC-6 gains an amendment line.
  • Code: usePopover runs its focus region whenever the popover is open, and isModal only sets aria-modal on a dialog popover. presentation exists on Popover and not on usePopover.
  • Open PRs searched for tabBehavior, isModal, focus trap and Tab containment:

Decision

Decider: nynexman4464 (DEC-11), an engineering owner. See the record. In short:

  • isModal (Popover and usePopover, default true): with true a dialog popover carries aria-modal; with false it carries none. Tab is contained either way.
  • tabBehavior (usePopover only, default 'contain'):
    • 'contain': Tab and Shift+Tab cycle inside the open popover.
    • 'pageOrder': the popover contains nothing and never carries aria-modal. Its controls come after its trigger in the page's Tab order, or after its anchor when it has no trigger. Escape closes it only while focus is inside it, or on or inside its anchor or trigger. It closes as item 2 above lists.
  • isModal: true with 'pageOrder' is a type error and a development warning. With isModal unset, a 'pageOrder' popover is not modal.
  • FR22 names one released change (the shared focus return) where it named three.

This decision changes no released caller. FR22's focus-return change is not part of this pull request.

Rejected alternatives

  • isModal: false as the switch for no containment (DEC-5 as written): it changes every released caller of isModal: false.
  • One three-value modality input in place of isModal (the shape of Base UI's modal: boolean | 'trap-focus'): the cleanest end state, but it deprecates a released prop and needs a codemod.
  • A hasFocusTrap boolean: INV2 asks for a behavior prop, and a default-on boolean that callers turn off reads as a double negative.
  • Other names and values, each tried in the reading test below: focusScope: 'popover' | 'page', isInPageTabOrder, keyboardBehavior: 'contain' | 'inline', and 'afterAnchor' as the second value. None read better, and 'afterAnchor' is wrong for a popover whose trigger is not its anchor.

Claim scope and non-goals

Popover and usePopover for isModal; usePopover for tabBehavior. Out of scope:

  • tabBehavior on the Popover component (spec:AST-116 DEC-8 keeps composition inputs on the hook).
  • A third value, such as one that closes the popup on Tab.
  • Whether a default Popover should carry aria-modal at all.
  • The focus-return rule (FR17–FR21) and the anchor (FR1–FR9), which this PR does not change.

Evidence and implementation relationship

  • Released use. A survey of one large product codebase found about 450 call sites, in about 180 apps and libraries, that set isModal={false} or isModal: false. Their comments state the intent: keep the dialog role and the focus trap, and drop aria-modal because the page stays usable.
  • Platform practice supports both surfaces. Windows documents that light-dismiss flyouts "trap keyboard and gamepad focus inside their transient UI until dismissed" without being modal. The HTML Popover API's popovers are "always non-modal", and Tab moves on in page order.
  • Other libraries separate the two axes in the same way: Base UI's modal="trap-focus" traps focus and leaves the page interactive, and Fluent has trapFocus apart from its modal type.
  • Name reading test. A reader that saw only the option names, types and defaults (isModal plus one candidate, no documentation) said what isModal={false} does, then wrote options for a tour step, a filter editor and a full modal. 24 runs over seven conditions:
    • isModal alone: both runs said isModal={false} lets Tab leave, and both said the filter editor "cannot be expressed".
    • With tabBehavior: 'contain' | 'pageOrder': 5 of 5 runs wrote all three option sets correctly, and 4 of 5 read isModal as the aria-modal switch.
    • With hasFocusTrap: 5 of 5 wrote the option sets correctly, and 1 of 5 read isModal as the aria-modal switch.
    • Three separate rankings of eight candidates each put tabBehavior: 'contain' | 'pageOrder' first.
  • Implementation: feat(Popover): isModal decides whether the popover holds Tab (AST-116 FR12–FR16, AR4) #11156 is reworked to this record. usePopover gains tabBehavior; PowerSearch's token editor and the rich text link form keep their released Tab cycle; the non-modal sheet is removed. feat(Tour): Tour moves from Lab to Core with steps as data and an app-owned active step (AST-119) #12891 (Tour) uses 'pageOrder' for a step without a backdrop.

Writing rubric results

  • R1 narration: none added. DEC-11 states what isModal: false is and which callers rely on it, in the present tense. The Amended: lines state which decision governs what, as the records' other amendment lines do: two are added (spec:AST-116 DEC-5, spec:AST-119 DEC-6), one is rewritten (component:Popover DEC-9), and component:Popover DEC-8's is removed because it is no longer true.
  • R2 research in the record: none. The caller survey, the platform and library notes and the reading test are in this description only.
  • R3 evidence naming a change: none added. The FR12–FR16 verification row names tests and states. component:Popover keeps earlier pull request references that this change does not touch: in Basis and verification cells, in its Intent, in AR5 and on DEC-4's Decider line.
  • R4 rejected alternatives over one line or outside a decision: three, in one sentence inside DEC-11. DEC-5 keeps its one.
  • R5 pull request or issue references remaining: none added. component:Popover keeps the earlier ones named under R3.
  • R6 ruled open questions still listing options: none. OQ1 is unchanged and unruled.
  • R7 project status: none added. Three gap lines are restated as today's observable mismatch: FR12 (usePopover has no tabBehavior), FR15 ("no popover scopes Escape to its focus") and FR16 (a sheet returns focus through BottomSheet's own return). component:Popover's AR3 gap and family:overlay-dismissal's FR2 and FR3 gap follow them.

Scope

Components: usePopover, Popover, Tour

  • This PR contains specification records only.
  • It records observable behavior and preserves equivalent internal implementations.
  • Any named internal mechanism is intentionally public, names its dependent caller/system, and explains why an equivalent implementation would not satisfy the contract.
  • Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
  • It records one intentional durable decision, not a rescue for a separable tagalong.
  • The canonical knowledge owner, affected current claims, and overlapping open work are named; any ownership collision is resolved or called out for human decision.
  • Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
  • Public text and artifacts contain no internal Meta context.

Validation

  • pnpm check:knowledge: passes ("Knowledge templates and records are aligned").
  • Prettier: the four records pass prettier --check. Cell widths changed, so Prettier realigned four tables: Verification in spec:AST-116, and Public concepts, Public usePopover semantic inputs and Representative focus and dismissal states in component:Popover. Hide whitespace to read the diff.
  • git diff --check: clean.
  • Not covered: no code changes here, so no test proves the new text. The gap lines say what Core does today.

@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Building Building Preview Nov 19, 2026 9:43pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 19, 2026
@astracat-bot

astracat-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🔄 In progress (for maintainers only) Nov 19, 2026, 9:45 PM UTC

@github-actions

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot. needs:spec-owner-review Current knowledge records await owner approval

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant