Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/layer-focus-return.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[fix] Popover and DropdownMenu, in their popover presentation, and Dialog move focus as they close only when the close would strand it (WCAG 2.2 SC 2.4.3, Focus Order). Focus that used to fall to the page body when the opener was gone now goes, in order, to the element focused when the layer opened, its trigger, the control that names the layer in `aria-controls`, the component's own stand-in (a typeahead's input), the anchor or the first control inside it, the opener's former place in its group, the nearest surviving ancestor, the layer that opened this one, then the page's `main` region. A released behavior also changes: a DropdownMenu no longer focuses its trigger at close when focus never entered the menu. The `useFocusTrap` hook shares the trap that Popover uses, so it returns focus the same way. A Drawer keeps its own return at close and gets the shared one only when it is removed while open. There is no option to turn focus return off. To send focus somewhere specific, focus it in `onOpenChange` (Popover, DropdownMenu) or in `usePopover`'s `onHide`; for a Dialog, focus it after the dialog has closed, since the page outside an open dialog is inert. A Popover or DropdownMenu returns focus before the browser's own restore, so its trigger gets a focus ring only after keyboard input.

@nynexman4464
7 changes: 7 additions & 0 deletions .changeset/popover-anchor.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[feat] `usePopover` takes an `anchorRef`: a ref to the element the popover sits on when it is not the control that opens it. Any element with a CSS box works (an HTML element such as a card or a table cell, or an `<svg>` element; a shape inside an `<svg>` warns in development). The trigger keeps its toggle and ARIA, and the anchor gets neither. The ref is read when the popover opens, on each render of your component, and on each `show()`, so a popover with `hasLightDismiss: false` moves between rows without closing when you set `anchorRef.current` and call `show()`. With light dismiss on, the press on the other row closes the popover first, and `show()` opens it again on the new element. A `show()` before the ref holds an element waits, and opens when the ref is next read and holds one. A composition with an anchor and no trigger opens through `show()`. The `Popover` component and its own `anchorRef` are unchanged.

@nynexman4464
77 changes: 77 additions & 0 deletions apps/storybook/stories/LayerFocusReturn.stories.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
* @file LayerFocusReturn.stories.tsx
* @input DropdownMenu, Dialog, Popover and Button from @astryxdesign/core
* @output A story whose controlled menu closes in the commit that opens a
* Dialog from its row, so the row is gone when the Dialog closes. A story
* whose Popover trigger remounts while the popover is open
* @position Fixture for Layer/__tests__/LayerFocusReturn.interaction.browser.spec.ts
*/

import {useState} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
import {DropdownMenu, DropdownMenuItem} from '@astryxdesign/core/DropdownMenu';
import {Dialog} from '@astryxdesign/core/Dialog';
import {Popover} from '@astryxdesign/core/Popover';
import {Button} from '@astryxdesign/core/Button';

const meta: Meta = {
title: 'Core/Layer Focus Return',
tags: ['no-visual'],
parameters: {layout: 'padded'},
};
export default meta;

type Story = StoryObj;

function MenuThenDialogFixture() {
const [isMenuOpen, setIsMenuOpen] = useState(false);
const [isDialogOpen, setIsDialogOpen] = useState(false);
return (
<>
<DropdownMenu
button={{label: 'Actions'}}
isMenuOpen={isMenuOpen}
onOpenChange={setIsMenuOpen}>
<DropdownMenuItem
label="Rename"
onClick={() => setIsDialogOpen(true)}
/>
</DropdownMenu>
<Dialog
isOpen={isDialogOpen}
onOpenChange={setIsDialogOpen}
aria-label="Rename">
<Button label="Done" onClick={() => setIsDialogOpen(false)} />
</Dialog>
</>
);
}

/** A controlled menu whose row opens a Dialog as the menu closes. */
export const MenuThenDialog: Story = {
render: () => <MenuThenDialogFixture />,
};

function RemountedTriggerFixture() {
const [generation, setGeneration] = useState(0);
return (
<Popover
label="Filter"
hasLightDismiss={false}
content={
<Button
label="Apply"
onClick={() => setGeneration(current => current + 1)}
/>
}>
<Button key={generation} label={`Filter ${generation}`} />
</Popover>
);
}

/** A Popover whose trigger is replaced by a new element while it is open. */
export const RemountedTrigger: Story = {
render: () => <RemountedTriggerFixture />,
};
101 changes: 101 additions & 0 deletions apps/storybook/stories/PopoverAnchorRef.stories.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
* @file PopoverAnchorRef.stories.tsx
* @input usePopover, Button and TextInput from @astryxdesign/core
* @output A story with one popover shared by three table rows. Each row's
* edit button sets `anchorRef` to that row's value cell and calls `show()`.
* A button removes and restores row B's value cell, and a button inside
* the popover removes it. A counter shows how often the popover reported a
* show and a hide
* @position Fixture for Popover/__tests__/PopoverAnchor.interaction.browser.spec.ts
*/

import {useRef, useState} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
import {usePopover} from '@astryxdesign/core/Popover';
import {Button} from '@astryxdesign/core/Button';
import {TextInput} from '@astryxdesign/core/TextInput';

const meta: Meta = {
title: 'Core/Popover Anchor Ref',
tags: ['no-visual'],
parameters: {layout: 'padded'},
};
export default meta;

type Story = StoryObj;

const ROWS = ['A', 'B', 'C'];

function RowEditor() {
const anchorRef = useRef<Element | null>(null);
const [isRowBShown, setIsRowBShown] = useState(true);
const [value, setValue] = useState('');
const [counts, setCounts] = useState({shows: 0, hides: 0});
const popover = usePopover({
anchorRef,
dialogLabel: 'Edit value',
hasLightDismiss: false,
onShow: () => setCounts(c => ({...c, shows: c.shows + 1})),
onHide: () => setCounts(c => ({...c, hides: c.hides + 1})),
});
const {show} = popover;
return (
<div>
<table>
<tbody>
{ROWS.map(row => (
<tr key={row}>
{row === 'B' && !isRowBShown ? (
<td key="removed" />
) : (
<td
key="value"
data-cell={row}
style={{padding: 8, minWidth: 160}}>
Value {row}
</td>
)}
<td style={{padding: 8}}>
<Button
label={`Edit row ${row}`}
onClick={() => {
anchorRef.current = document.querySelector(
`[data-cell="${row}"]`,
);
show();
}}
/>
</td>
</tr>
))}
</tbody>
</table>
{/* Far enough below the table that the open popover never covers it. */}
<div style={{marginBlockStart: 240}}>
<Button
label={isRowBShown ? 'Remove row B value' : 'Restore row B value'}
onClick={() => setIsRowBShown(isShown => !isShown)}
/>
<output data-testid="counts">
shows {counts.shows}, hides {counts.hides}
</output>
</div>
{popover.render(
<>
<TextInput label="Value" value={value} onChange={setValue} />
<Button
label="Delete value B"
onClick={() => setIsRowBShown(false)}
/>
</>,
)}
</div>
);
}

/** One popover that moves between rows; no outside press closes it. */
export const Rows: Story = {
render: () => <RowEditor />,
};
19 changes: 11 additions & 8 deletions docs/families/overlay-dismissal.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,17 +178,18 @@ this record's current membership snapshot must be updated with it.
- **FR2 — One request affects one surface.** An unclaimed Escape press is routed
to exactly one topmost registered present member. That member either invokes
its dismissal callback or blocks the request; the request does not continue
to a member behind it. A non-modal Popover is present for Escape only while
to a member behind it. A `usePopover` popover with
`tabBehavior: 'pageOrder'` is present for Escape only while
focus is inside it, or on or inside its anchor or trigger (`spec:AST-116`
FR15); otherwise
the press goes to the member beneath it, or to the page when none is. A
Tour step without a backdrop follows the non-modal Popover's rule, and a
Tour step without a backdrop follows that rule, and a
step with a backdrop takes Escape as a modal layer does (`spec:AST-119`
FR14).
- **FR3 — Platform close requests use the same topmost rule.** A member receiving
a browser or platform close request closes only when it is the topmost
registered present member. A request aimed at a lower member is declined.
Presence follows FR2, so a non-modal Popover that is not present does not
Presence follows FR2, so a `'pageOrder'` popover that is not present does not
take the request, and it goes to the member beneath it.
- **FR4 — Available nesting signals outrank host placement.** When a member
provides `LayerDepthProvider`, React-tree depth orders its descendant layers
Expand Down Expand Up @@ -254,11 +255,13 @@ this record's current membership snapshot must be updated with it.
layer returns it, or else on the host itself. The rule is the same for a
mouse, a pen, and a finger.

FR2 and FR3 gap: Escape and platform close requests reach a non-modal Popover through
the shared stack and native auto light dismiss wherever focus is
(`spec:AST-116` FR15 gap).
FR2 and FR3 gap: no popover has `tabBehavior: 'pageOrder'`, so Escape and
platform close requests reach a Popover through the shared stack and native
auto light dismiss wherever focus is (`spec:AST-116` FR12 and FR15 gaps).
FR2 gap: a Lab TourStep without a backdrop ends the tour on Escape wherever
focus is (`spec:AST-119` FR14 gap).
FR9 gap: a Popover's focus return to a control is a plain focus, which can
scroll the control into view.

## Allowed component variation

Expand All @@ -282,7 +285,7 @@ focus is (`spec:AST-119` FR14 gap).
| Member and state | Shared invariant | Deliberate variation |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Dialog inside Dialog | Inner dialog handles the first request | Dialog supplies native modality and focus behavior |
| Popover inside Dialog | A modal Popover, or a non-modal one holding focus, handles the first Escape | Popover supplies anchoring, portal placement, and focus policy |
| Popover inside Dialog | A `'contain'` popover, or a `'pageOrder'` one holding focus, handles the first Escape | Popover supplies anchoring, portal placement, and focus policy |
| Tour step without a backdrop | Takes Escape only while focus is in its callout, or on or inside its anchor (`spec:AST-119` FR14) | Escape ends the tour with `'escape'`; the step has no outside dismissal |
| Tour step with a backdrop | Handles Escape as a modal layer does (`spec:AST-119` FR14) | A press outside the callout ends the tour with `'backdrop'` |
| Registered descendant inside CommandPalette | Descendant handles the first Escape | CommandPalette inherits Dialog's shared stack participation |
Expand All @@ -293,7 +296,7 @@ focus is (`spec:AST-119` FR14 gap).
| Two unrelated registered surfaces | Later active-cycle registration is topmost | Neither surface is treated as nested |
| Platform close request sent to a lower Dialog | Lower Dialog stays open | The platform targets a host; the shared check decides whether it may close |
| Popover in an iframe, Dialog in the page | Request goes to its own document's top member | The app renders into the second document through a portal |
| Popover inside Dialog in an iframe | A modal Popover, or a non-modal one holding focus, handles the iframe's first request | Both register their own elements, so they rank in the iframe's order |
| Popover inside Dialog in an iframe | A `'contain'` popover, or a `'pageOrder'` one holding focus, handles the iframe's first request | Both register their own elements, so they rank in the iframe's order |
| Tooltip or HoverCard inside Dialog, in iframe | An open HoverCard handles the first Escape there; over an unpinned Tooltip, the Dialog takes it; a pinned Tooltip takes it first | An unpinned Tooltip never wins or blocks Escape against another member; a pinned Tooltip takes it first (`spec:AST-003` FR4, DEC-6) |
| ContextMenu in a Picture-in-Picture window | Escape closes it; focus returns to its opener there | The menu opens where the person pressed (FR8, FR9) |
| BottomSheet or Lightbox in a Picture-in-Picture window | Escape closes it; focus returns to its return target there | The surface covers that window (FR8, FR9) |
Expand Down
Loading