Repository navigation
spec(popover): isModal keeps its released meaning, and usePopover takes tabBehavior (AST-116) - #13015
Draft
nynexman4464 wants to merge 6 commits into
Draft
nynexman4464 wants to merge 6 commits into
nynexman4464 wants to merge 6 commits into
Conversation
…pec:AST-116 FR1–FR3, FR5, FR6)
…sentation) and Dialog that never strands focus (spec:AST-116 FR17–FR21, AR1)
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
AI review status for this pull request.
|
This was referenced Nov 19, 2026
Contributor
PR Analysis Report
Generated by PR Enrichment workflow | View current CI run |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stack: #11117 → #11121 → #13015
Exact decision needed
Whether
isModal: falsekeeps its released meaning, and whether a popover that Tab passes through gets its ownusePopoverinput:isModalsetsaria-modalon a dialog popover and nothing else. Tab stays in the popover whether it istrueorfalse, as released.tabBehavior: 'contain' | 'pageOrder'onusePopoveronly, default'contain'.'pageOrder'is the behaviorspec:AST-116gave toisModal: false: Tab follows the page, Escape applies only while focus is in the popover's scope, and there is noaria-modal. FR15 also states how such a popover closes, which the record did not say before:hasLightDismissis on;hasEscapeDismiss: falseturns its Escape off whateverhasLightDismisssays.presentationis a Popover prop andtabBehavioris a hook input, so no sheet can have'pageOrder'.spec:AST-116DEC-5 madeisModal: falsethe switch for no Tab containment. No code for it has merged, so this record changes before any released behavior does.Existing authority searched
component:PopoverDEC-9 (current; decided bycixzhang, who owns that record): "A Popover is a focus region, modal or not", with "no Tab containment for non-modal popovers" rejected.spec:AST-116DEC-5 superseded it forisModal: false. DEC-11 keeps DEC-9's rejection for everyisModalvalue and makes one exception, a'pageOrder'popover.component:PopoverDEC-8 (current; alsocixzhang's): the sheet is modal and always light-dismisses. FR16 superseded it forisModal: false. It governs every sheet again, and its amendment line goes.spec:AST-116FR12–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-apiINV2 and INV3: a prop that chooses how a component responds to input is a<thing>Behaviorclosed union (INV2), and a new behavior prop defaults to the shipped behavior (INV3).tabBehaviorfollows 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-dismissalFR2 and FR3: the Escape presence exception, keyed on'pageOrder'in place of "non-modal".spec:AST-119FR14 and DEC-6: a tour step without a backdrop is the'pageOrder'popover. FR14 says so, and DEC-6 gains an amendment line.usePopoverruns its focus region whenever the popover is open, andisModalonly setsaria-modalon a dialog popover.presentationexists on Popover and not onusePopover.tabBehavior,isModal, focus trap and Tab containment:Decision
Decider:
nynexman4464(DEC-11), an engineering owner. See the record. In short:isModal(Popover andusePopover, defaulttrue): withtruea dialog popover carriesaria-modal; withfalseit carries none. Tab is contained either way.tabBehavior(usePopoveronly, default'contain'):'contain': Tab and Shift+Tab cycle inside the open popover.'pageOrder': the popover contains nothing and never carriesaria-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: truewith'pageOrder'is a type error and a development warning. WithisModalunset, a'pageOrder'popover is not modal.This decision changes no released caller. FR22's focus-return change is not part of this pull request.
Rejected alternatives
isModal: falseas the switch for no containment (DEC-5 as written): it changes every released caller ofisModal: false.isModal(the shape of Base UI'smodal: boolean | 'trap-focus'): the cleanest end state, but it deprecates a released prop and needs a codemod.hasFocusTrapboolean: INV2 asks for a behavior prop, and a default-on boolean that callers turn off reads as a double negative.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
usePopoverforisModal;usePopoverfortabBehavior. Out of scope:tabBehavioron the Popover component (spec:AST-116DEC-8 keeps composition inputs on the hook).aria-modalat all.Evidence and implementation relationship
isModal={false}orisModal: false. Their comments state the intent: keep the dialog role and the focus trap, and droparia-modalbecause the page stays usable.modal="trap-focus"traps focus and leaves the page interactive, and Fluent hastrapFocusapart from its modal type.isModalplus one candidate, no documentation) said whatisModal={false}does, then wrote options for a tour step, a filter editor and a full modal. 24 runs over seven conditions:isModalalone: both runs saidisModal={false}lets Tab leave, and both said the filter editor "cannot be expressed".tabBehavior: 'contain' | 'pageOrder': 5 of 5 runs wrote all three option sets correctly, and 4 of 5 readisModalas thearia-modalswitch.hasFocusTrap: 5 of 5 wrote the option sets correctly, and 1 of 5 readisModalas thearia-modalswitch.tabBehavior: 'contain' | 'pageOrder'first.usePopovergainstabBehavior; 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
isModal: falseis and which callers rely on it, in the present tense. TheAmended:lines state which decision governs what, as the records' other amendment lines do: two are added (spec:AST-116DEC-5,spec:AST-119DEC-6), one is rewritten (component:PopoverDEC-9), andcomponent:PopoverDEC-8's is removed because it is no longer true.component:Popoverkeeps 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.component:Popoverkeeps the earlier ones named under R3.usePopoverhas notabBehavior), FR15 ("no popover scopes Escape to its focus") and FR16 (a sheet returns focus through BottomSheet's own return).component:Popover's AR3 gap andfamily:overlay-dismissal's FR2 and FR3 gap follow them.Scope
Components: usePopover, Popover, Tour
Validation
pnpm check:knowledge: passes ("Knowledge templates and records are aligned").prettier --check. Cell widths changed, so Prettier realigned four tables: Verification inspec:AST-116, and Public concepts, PublicusePopoversemantic inputs and Representative focus and dismissal states incomponent:Popover. Hide whitespace to read the diff.git diff --check: clean.