An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file bottomSheetStack.ts
* @input The DOM (dialog elements, document order) and the focus-return
* utilities
* @output The private bottom-sheet stack registry: host registration,
* open-order ranking, top-layer reconciliation, one view per host, the
* replace handoff, and the shared native show/hide and focus helpers
* @position Internal to BottomSheet, used by the standalone host in
* BottomSheet.tsx and by BottomSheetSwitcher. No public API reaches it.
*
* SYNC: When modified, update:
* - /packages/core/src/BottomSheet/BottomSheet.tsx
* - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
* - /packages/core/src/BottomSheet/BottomSheetStacking.test.tsx
* - /packages/core/src/BottomSheet/BottomSheetReplace.test.tsx
* - /packages/core/src/BottomSheet/BottomSheet.doc.mjs
* - /apps/storybook/stories/BottomSheetReplace.stories.tsx
*/
// Each modal sheet keeps its own native `<dialog>` and open state. The top
// layer already paints a later showModal() above an earlier one, and the
// later dialog blocks the earlier one. The browser does not know that the
// dialogs are sheets of one stack. So this registry decides which sheet is on
// top, how far each covered sheet recedes, and whose `::backdrop` is the one
// scrim. The hosts call it only from commit-phase effects.
//
// Order is open order. Each open cycle gets a rank: its batch (one React
// commit), then a sequence. Within one batch, document order decides, so a
// sheet comes before the sheets in its content. Effect order is child first,
// so the rank is read at compare time, after the whole commit registered.
//
// The top layer is reconciled, not trusted. Where the shown order differs
// from the rank order, the registry closes the dialogs from the first
// difference up and shows them again in rank order, inside the commit and
// before paint. Only the dialogs that must move up are shown again.
//
// A replace is one sheet closing and another opening in the same commit,
// where the closing sheet was the top open sheet and the last press or focus
// was inside it. The registry then runs the switcher's handoff on the two
// dialogs. The retained sheet is inert at once and lends its opener to the
// entering sheet. A covered sheet closing, a close in another update, or a
// change driven from outside the closing sheet is never a replace. Non-modal
// sheets replace each other too, but they never stack.
//
// The state lives on `globalThis`, under a key with the protocol version, so
// two copies of this module on one page share one stack. A copy on another
// version keeps its own stack. Each document is its own stack.
import {notifyTopLayerEntry} from '../Layer/modalOutlet';
import {focusForLastInput, returnFocusForLastInput} from '../utils/focusReturn';
import {realmValue} from '../utils/sharedRealm';
export interface BottomSheetStackView {
/** Another modal sheet is presented alongside this one. */
readonly isStacked: boolean;
/** This sheet is the open sheet that is on top. */
readonly isTop: boolean;
/** This sheet is open with at least one open sheet above it. */
readonly isCovered: boolean;
/** Open sheets above this one; drives how far the sheet recedes. */
readonly depth: number;
/** This sheet's `::backdrop` is the one visible scrim of the stack. */
readonly ownsScrim: boolean;
/**
* This sheet took the scrim over from a sheet below it that is still
* sliding out, so its backdrop must appear at once rather than fade in.
*/
readonly isScrimHandoff: boolean;
/**
* This sheet is covered and contains no presented sheet, so its whole
* dialog can be marked inert and hidden from assistive technology.
*/
readonly isBlocked: boolean;
/**
* This sheet is closing and an open sheet above it owns the scrim now, so
* its own backdrop must leave at once rather than fade: the dim is the
* other sheet's from this frame on, and two backdrops would double it.
*/
readonly isScrimTakenOver: boolean;
/**
* This closed sheet is being replaced by the sheet opened in the same
* update: it stays in place (`covered`), moves down to the entering sheet's
* top edge (`aligning`), or fades (`fading`), instead of sliding out.
*/
readonly replacedMotion: BottomSheetReplacedMotion | null;
/** How far down a replaced sheet moves to meet the entering sheet, in px. */
readonly alignmentOffset: number;
/** This open sheet is replacing the sheet that closed in the same update. */
readonly isReplacing: boolean;
}
export type BottomSheetReplacedMotion = 'covered' | 'aligning' | 'fading';
/** The motions a host's panel reports to the registry during a replace. */
export type BottomSheetReplaceMotion =
'entering' | 'aligning' | 'fading' | 'exiting';
export const BOTTOM_SHEET_STACK_DEFAULT_VIEW: BottomSheetStackView = {
isStacked: false,
isTop: false,
isCovered: false,
depth: 0,
ownsScrim: false,
isScrimHandoff: false,
isBlocked: false,
isScrimTakenOver: false,
replacedMotion: null,
alignmentOffset: 0,
isReplacing: false,
};
/**
* Why the registry moves focus into a sheet: it was shown on top (`open`), a
* close above it revealed it (`reveal`), or it is replacing the sheet the
* person was in (`replace`: focus follows the person from one step to the
* next, whatever the native host did with it).
*/
export type BottomSheetFocusReason = 'open' | 'reveal' | 'replace';
/** The sheets of one document's modal stack that close in the same update. */
interface ClosingGroup {
/** Bottom to top. */
members: Entry[];
/** Members whose dialogs have not left the top layer yet. */
pending: Set<Entry>;
/** The bottom-most member's return target, read when the group is sealed. */
returnTarget: HTMLElement | null;
/** Focus has been returned for this group. */
reported?: boolean;
}
export interface BottomSheetStackRegistration {
/** Stable identity of the host component instance. */
key: object;
/** The host's native dialog. */
getElement: () => HTMLDialogElement | null;
/**
* The element whose place in the tree orders this level against the other
* sheets of its commit, when it is not the dialog itself: a switcher flow
* is realized by whichever step dialog is active, so its flow wrapper — the
* one element that contains every step — stands for it, and a handoff
* cannot reorder the flow against a sheet opened in the same commit.
*/
getTreeAnchor?: () => Element | null;
/** Present the dialog modally (`showModal()`), capturing the opener first. */
show: () => void;
/** Take the dialog out of the top layer (`close()`) for a re-show. */
hide: () => void;
/** Move focus into the sheet: shown on top, or revealed by a close above. */
focus: (reason: BottomSheetFocusReason) => void;
/**
* Where focus returns when this sheet closes the stack: its explicit
* final-focus target, else the element that opened it. Read by the
* registry when several sheets close in one update.
*/
getReturnTarget?: () => HTMLElement | null;
/** Receive this host's view whenever it changes. */
onView: (view: BottomSheetStackView) => void;
/**
* What a host must supply to take part in a replace. A host without it (a
* switcher flow, which replaces its own steps) is never paired.
*/
replaceable?: BottomSheetReplaceable;
}
export interface BottomSheetReplaceable {
/** The host's visual panel, measured for the replace alignment. */
getPanel: () => HTMLElement | null;
/** The element focus returns to when the sheet closes the flow. */
getOpener: () => HTMLElement | null;
/** Adopt the replaced sheet's opener, so the flow closes back to it. */
setOpener: (opener: HTMLElement | null) => void;
/** The replace is over: this replaced sheet is hidden and its dialog closed. */
finish: () => void;
}
interface Rank {
batch: number;
seq: number;
}
interface ReplaceState {
/** The sheet that opened in the same update and now stands in for this one. */
replacer: Entry;
motion: BottomSheetReplacedMotion;
alignmentOffset: number;
isAlignmentComplete: boolean;
isEnteringComplete: boolean;
}
interface Entry extends BottomSheetStackRegistration {
rank: Rank;
isOpen: boolean;
/** The document whose top layer this sheet's dialog is in. */
doc: Document;
/**
* Modal sheets stack with each other; non-modal sheets (`hasScrim={false}`)
* form their own group per document: they never stack, recede or own a
* scrim, but they replace each other and keep their top-layer order.
*/
isModal: boolean;
view: BottomSheetStackView;
/** Set on a closed sheet while another sheet replaces it. */
replace: ReplaceState | null;
/** Set on an open sheet while it replaces the sheet that closed with it. */
replacing: Entry | null;
/**
* Reopened while it was being replaced: its panel is already in place, so
* when it replaces in turn its entrance is complete the moment it starts.
*/
isEnteringInPlace: boolean;
}
const ALIGNMENT_THRESHOLD_PX = 1;
/**
* The registry's state. One per JavaScript realm, shared by every copy of this
* module in it that speaks the same stack protocol version: two copies of
* the package on one page (two bundles, a dev server serving the same file
* under two URLs, a micro-frontend) must see one stack, or each would show
* its own sheets over the other's with two scrims and no order. The state
* lives on `globalThis` under a symbol that names the protocol version
* (STACK_PROTOCOL_VERSION), so a copy on another version finds no state of
* its own and keeps a stack of its own; the shape it carries is the guard
* against a key collision.
*/
interface StackState {
shape: number;
entries: Entry[];
// The order the presented entries were shown in, per group (one document's
// modal sheets, one document's non-modal sheets): each document has its
// own top layer, and the two groups never reorder each other.
shownOrder: WeakMap<Document, {modal: Entry[]; nonModal: Entry[]}>;
// Documents that have the press listeners, each with the function that
// removes them: one set per document, installed with the document's first
// registered sheet and removed when its last one leaves (the listeners
// feed this shared state, so a second copy must not add another set).
listenedDocuments: WeakMap<Document, () => void>;
// The open/close flips of the current batch (one commit); a replace pairs
// one of each. Cleared with the seal.
batchOpened: Entry[];
batchClosed: Entry[];
// The control the person acted from, for the batch's first flip: the
// target of the last pointer or key press in the document (recorded in the
// capture phase, so it is known whether or not the press moved focus — a
// non-modal sheet takes no focus, and some browsers do not focus a clicked
// button), else where focus was, read before any dialog of this commit is
// shown. A replace is recognised by it.
batchActor: Element | null;
// The target is held weakly: a press on an element that has since been
// removed and dropped must not keep it alive until the next press.
lastPress: WeakMap<Document, {target: WeakRef<Element>; at: number}>;
// Retained sheets whose replacer closed in this batch; dropped once the
// batch's pairing is known, unless the batch reopened them.
pendingDrops: Entry[];
// A replacer that still owes the move of focus into itself (done once its
// dialog is shown).
pendingReplaceFocus: Entry | null;
// The pair this batch made, and the opener the replacer had before it
// adopted the replaced sheet's: a later flip of the same commit (a third
// sheet closing or opening) makes the tally no longer one close and one
// open, and the pair is undone — the commit is then several sheets
// changing, which keep their own push and pop motion.
batchPair: {
replaced: Entry;
replacer: Entry;
replacerOpener: HTMLElement | null;
} | null;
// Modal sheets closing together in one update ("Close all"): focus returns
// once, from the bottom-most of them, after the last of them has left the
// top layer. Sealed from `batchClosed` when the batch ends.
closingTogether: Map<Entry, ClosingGroup>;
// Rank persists across a StrictMode replay (unregister and register in one
// synchronous pass) so the replay cannot promote a sheet. A rank marked
// closed is spent: the next open takes a new one.
rankByKey: WeakMap<
object,
Rank & {isClosed: boolean; detachedBatch: number | null}
>;
currentBatch: number;
nextSeq: number;
isBatchDirty: boolean;
isSealScheduled: boolean;
// The element a step present blurred while the person was in a sheet above
// the flow; the next top-layer reconcile lands focus on it again. Per
// document, within one commit.
focusToKeep: WeakMap<Document, HTMLElement>;
// Non-modal sheets presented by `show()` because a modal outside them was
// open, waiting to enter the top layer, with the watchers that look again
// (see deferTopLayerEntry).
deferredTopLayer: WeakMap<Document, DeferredTopLayer>;
}
interface DeferredTopLayer {
deferred: Map<HTMLDialogElement, HTMLElement | null>;
blockers: WeakSet<HTMLDialogElement>;
removals: MutationObserver | null;
/** Removes the document `close` listener; set while anything waits. */
stopListeningForClose: (() => void) | null;
}
/**
* The stack protocol version: the shape and meaning of Entry, the
* registration, the batch/seal protocol and the shared listeners. Copies of
* the package on one page share one stack per document when they speak the
* same protocol. The version is part of the document-global key, so a copy
* on another protocol keeps its own stack and never reads a shared state of
* the wrong shape. Bump it whenever any of those change.
*/
const STACK_PROTOCOL_VERSION = 8;
const STACK_STATE_KEY = Symbol.for(
`astryx.bottomSheetStack.v${STACK_PROTOCOL_VERSION}`,
);
const STACK_STATE_SHAPE = STACK_PROTOCOL_VERSION;
function createStackState(): StackState {
return {
shape: STACK_STATE_SHAPE,
entries: [],
shownOrder: new WeakMap(),
listenedDocuments: new WeakMap(),
batchOpened: [],
batchClosed: [],
batchActor: null,
batchPair: null,
lastPress: new WeakMap(),
pendingDrops: [],
pendingReplaceFocus: null,
closingTogether: new Map(),
rankByKey: new WeakMap(),
currentBatch: 0,
nextSeq: 0,
isBatchDirty: false,
isSealScheduled: false,
focusToKeep: new WeakMap(),
deferredTopLayer: new WeakMap(),
};
}
const state = realmValue(
STACK_STATE_KEY,
createStackState,
shared => (shared as StackState | null)?.shape === STACK_STATE_SHAPE,
);
function takeRank(): Rank {
state.isBatchDirty = true;
scheduleSeal();
return {batch: state.currentBatch, seq: state.nextSeq++};
}
function scheduleSeal(): void {
// Backstop for a commit whose hosts run no passive effect afterwards (a
// subtree React just hid). A later task is always a later batch.
if (state.isSealScheduled || typeof queueMicrotask !== 'function') {
return;
}
state.isSealScheduled = true;
queueMicrotask(() => {
state.isSealScheduled = false;
sealBottomSheetBatch();
});
}
/**
* End the current batch. Hosts call it from a passive effect, which React runs
* after every layout effect of the same commit and before the next commit;
* registrations on either side of it are therefore different open orders.
*/
export function sealBottomSheetBatch(): void {
flushPendingDrops();
sealClosingGroups();
if (state.isBatchDirty) {
state.currentBatch += 1;
state.isBatchDirty = false;
}
state.batchOpened = [];
state.batchClosed = [];
state.batchActor = null;
state.batchPair = null;
}
/**
* Two or more modal sheets of one stack closing in the same update with no
* sheet of that stack left open and nothing opening: "Close all". Each one
* would return focus on its own, at depth 0, to an opener that is either
* inside a dialog that is closing with it or on a page that is still inert
* behind the other modals — so none of them can. The group returns focus
* once instead, from its bottom-most sheet, after the last of its dialogs
* has left the top layer. A single sheet closing, a non-modal sheet, and a
* batch that also opens a sheet are not groups: their own close handles
* focus (the replace and the pop have their own rules).
*/
function sealClosingGroups(): void {
if (state.batchOpened.length > 0) {
return;
}
const closingModal = state.batchClosed.filter(
entry => entry.isModal && entry.replace == null && entry.replacing == null,
);
if (closingModal.length < 2) {
return;
}
const byDoc = new Map<Document, Entry[]>();
for (const entry of closingModal) {
const list = byDoc.get(entry.doc) ?? [];
list.push(entry);
byDoc.set(entry.doc, list);
}
for (const [doc, closing] of byDoc) {
if (closing.length < 2) {
continue;
}
const stack = sortedEntries(doc, true);
if (stack.some(entry => entry.isOpen)) {
// Sheets remain open beneath: the pops return into the revealed sheet
// through the ordinary close path.
continue;
}
const members = stack.filter(entry => closing.includes(entry));
const bottom = members[0];
const group: ClosingGroup = {
members,
pending: new Set(members),
returnTarget: bottom.getReturnTarget?.() ?? null,
};
for (const entry of members) {
state.closingTogether.set(entry, group);
}
}
}
/**
* Whether `key` closes as part of a "Close all" group. Its host then leaves
* the top layer without returning focus itself; the registry returns it
* once the whole group has left.
*/
export function isClosingTogether(key: object): boolean {
const entry = state.entries.find(candidate => candidate.key === key);
return entry != null && state.closingTogether.has(entry);
}
function completeClosingGroup(group: ClosingGroup): void {
if (group.pending.size > 0 || group.reported) {
return;
}
group.reported = true;
const target = group.returnTarget;
if (target != null && target.isConnected) {
returnFocusForLastInput(target);
}
}
/**
* A member of a "Close all" group has left the top layer. When it is the
* last one, focus returns to the group's target: the bottom-most sheet's
* final-focus target or opener, now that no modal dialog stands in the way.
*/
export function reportClosedTogether(key: object): void {
const entry = state.entries.find(candidate => candidate.key === key);
const group = entry == null ? undefined : state.closingTogether.get(entry);
if (entry == null || group == null) {
return;
}
leaveClosingGroup(entry, group);
}
function leaveClosingGroup(entry: Entry, group: ClosingGroup): void {
state.closingTogether.delete(entry);
group.pending.delete(entry);
completeClosingGroup(group);
}
/**
* Remember the last press in a document: a pointer down, a click (pointer,
* touch, keyboard activation or code: it is what runs the handler that flips
* the sheets) or a key down. One capture-phase listener per event per
* document, installed with the first sheet registered in it; the target is
* kept weakly.
*/
function listenForPresses(doc: Document): void {
if (state.listenedDocuments.has(doc)) {
return;
}
const record = (event: Event) => {
if (event.target instanceof Element) {
state.lastPress.set(doc, {
target: new WeakRef(event.target),
at: Date.now(),
});
}
};
doc.addEventListener('pointerdown', record, true);
doc.addEventListener('click', record, true);
doc.addEventListener('keydown', record, true);
state.listenedDocuments.set(doc, () => {
doc.removeEventListener('pointerdown', record, true);
doc.removeEventListener('click', record, true);
doc.removeEventListener('keydown', record, true);
state.lastPress.delete(doc);
});
}
/**
* The document's last registered sheet left. Nothing reads the press record
* now, so the listeners go. The next sheet to register in the document
* installs them again.
*/
function stopListeningForPresses(doc: Document): void {
if (state.entries.some(entry => entry.doc === doc)) {
return;
}
const remove = state.listenedDocuments.get(doc);
if (remove != null) {
state.listenedDocuments.delete(doc);
remove();
}
}
/**
* A press is the actor of a flip only while it is fresh: the handler a press
* runs flips the sheets within the same task, milliseconds later. A flip
* that arrives later (a step change after a save resolves) is not that
* press's doing, and reads focus instead. A press is also spent once the
* sheet it landed in has been replaced or has closed — its target sits in
* an inert or no longer presented dialog — or once a replace has consumed
* it: a step advanced by code shortly after a Submit press (a "Processing"
* interstitial) is then judged by where focus is, inside the step, and
* hands off as DEP-0015 promises.
*/
const PRESS_ACTOR_WINDOW_MS = 1000;
function actorFor(doc: Document, flipping: Entry): Element | null {
const press = state.lastPress.get(doc);
const target = press?.target.deref();
if (
press != null &&
target != null &&
target.isConnected &&
Date.now() - press.at <= PRESS_ACTOR_WINDOW_MS &&
!isPressSpent(target, flipping)
) {
return target;
}
return doc.activeElement;
}
/**
* A press is spent when the sheet it landed in was already closed or
* replaced before this flip — not the sheet this very flip is closing, which
* is the ordinary replace made from inside it.
*/
function isPressSpent(target: Element, flipping: Entry): boolean {
const owning = state.entries.find(entry => {
const element = entry.getElement();
return (
entry.doc === flipping.doc && element != null && element.contains(target)
);
});
if (owning == null || owning === flipping) {
return false;
}
return !owning.isOpen || owning.replace != null;
}
/** Record a flip of the current batch, and who acted if it is the first. */
function recordFlip(entry: Entry, flip: 'opened' | 'closed'): void {
if (state.batchOpened.length === 0 && state.batchClosed.length === 0) {
state.batchActor = actorFor(entry.doc, entry);
}
(flip === 'opened' ? state.batchOpened : state.batchClosed).push(entry);
}
function compareRank(a: Entry, b: Entry): number {
if (a.rank.batch !== b.rank.batch) {
return a.rank.batch - b.rank.batch;
}
// One commit: tree order. A dialog that precedes another in document order
// (including one that contains the other) is below it.
const aEl = a.getTreeAnchor?.() ?? a.getElement();
const bEl = b.getTreeAnchor?.() ?? b.getElement();
if (aEl != null && bEl != null && aEl !== bEl) {
const position = aEl.compareDocumentPosition(bEl);
if (position & Node.DOCUMENT_POSITION_FOLLOWING) {
return -1;
}
if (position & Node.DOCUMENT_POSITION_PRECEDING) {
return 1;
}
}
return a.rank.seq - b.rank.seq;
}
/** The sheets of one group (document + modality), bottom to top. */
function sortedEntries(doc: Document, isModal: boolean): Entry[] {
return state.entries
.filter(entry => entry.doc === doc && entry.isModal === isModal)
.sort(compareRank);
}
/** The sheets `entry` shares a group with, bottom to top. */
function groupOf(entry: Entry): Entry[] {
return sortedEntries(entry.doc, entry.isModal);
}
/** The shown order of one group, read from or written to the shared state. */
function getShownOrder(doc: Document, isModal: boolean): Entry[] {
const orders = state.shownOrder.get(doc);
if (orders == null) {
return [];
}
return isModal ? orders.modal : orders.nonModal;
}
function setShownOrder(doc: Document, isModal: boolean, order: Entry[]): void {
const orders = state.shownOrder.get(doc) ?? {modal: [], nonModal: []};
if (isModal) {
orders.modal = order;
} else {
orders.nonModal = order;
}
state.shownOrder.set(doc, orders);
}
function isSameView(a: BottomSheetStackView, b: BottomSheetStackView): boolean {
return (
a.isStacked === b.isStacked &&
a.isTop === b.isTop &&
a.isCovered === b.isCovered &&
a.depth === b.depth &&
a.ownsScrim === b.ownsScrim &&
a.isScrimHandoff === b.isScrimHandoff &&
a.isBlocked === b.isBlocked &&
a.isScrimTakenOver === b.isScrimTakenOver &&
a.replacedMotion === b.replacedMotion &&
a.alignmentOffset === b.alignmentOffset &&
a.isReplacing === b.isReplacing
);
}
function computeViews(order: Entry[], isModal: boolean): void {
const changed: Entry[] = [];
if (!isModal) {
// Non-modal sheets never stack: no recede, no scrim, no top-layer order
// against modal sheets. Their view carries only the replace a pair of
// them may be running.
for (const entry of order) {
const view: BottomSheetStackView = {
...BOTTOM_SHEET_STACK_DEFAULT_VIEW,
replacedMotion: entry.replace?.motion ?? null,
alignmentOffset: entry.replace?.alignmentOffset ?? 0,
isReplacing: entry.replacing != null,
};
if (!isSameView(entry.view, view)) {
entry.view = view;
changed.push(entry);
}
}
for (const entry of changed) {
entry.onView(entry.view);
}
return;
}
const openEntries = order.filter(entry => entry.isOpen);
const top = openEntries[openEntries.length - 1] ?? null;
// A replaced sheet keeps the scrim while it is retained; the sheet replacing
// it takes the scrim over, instantly, when the replaced sheet leaves.
const owner =
order.find(entry => entry.isOpen || entry.replace != null) ?? null;
order.forEach((entry, index) => {
let depth = 0;
for (let above = index + 1; above < order.length; above += 1) {
// The sheet replacing this one stands in its place, not above it.
if (order[above].isOpen && order[above] !== entry.replace?.replacer) {
depth += 1;
}
}
const isCovered = entry.isOpen && depth > 0;
const element = entry.getElement();
const containsPresented =
element != null &&
order.some(other => {
const otherElement = other.getElement();
return (
other !== entry &&
otherElement != null &&
element.contains(otherElement)
);
});
const ownsScrim = entry === owner;
const isScrimHandoff =
ownsScrim &&
entry.isOpen &&
order.slice(0, index).some(below => !below.isOpen);
const view: BottomSheetStackView = {
isStacked: order.length > 1,
isTop: entry === top,
isCovered,
depth,
ownsScrim,
isScrimHandoff,
isBlocked: isCovered && !containsPresented,
isScrimTakenOver: !entry.isOpen && owner != null && owner !== entry,
replacedMotion: entry.replace?.motion ?? null,
alignmentOffset: entry.replace?.alignmentOffset ?? 0,
isReplacing: entry.replacing != null,
};
if (!isSameView(entry.view, view)) {
entry.view = view;
changed.push(entry);
}
});
for (const entry of changed) {
entry.onView(entry.view);
}
}
/**
* Present a switcher step's dialog modally with no focus to return to.
* showModal() records the element focused at that moment and close() moves
* focus back to it, in Chromium and WebKit even when focus is in another
* dialog by then. For a step that element is the control that advanced the
* flow (Continue, Back) or the flow's opener, and the dialog closes a fade
* later, while the user is in the next step: the return would pull focus
* off the active panel with no user action. Blurring first leaves nothing
* recorded, so the close moves nothing; the entering step then focuses its
* own panel, and the switcher returns focus to the opener itself when the
* flow ends. The blur happens in the same task as the present, so no frame
* paints without focus.
*/
export function presentStepModally(dialog: HTMLDialogElement): void {
const doc = dialog.ownerDocument;
const focused = doc.activeElement;
if (focused instanceof HTMLElement && focused !== doc.body) {
// Focus in another open dialog that does not contain this step — a sheet
// stacked over the flow, with the person typing in it while code moves
// the flow on — is theirs to keep: the registry puts that sheet back on
// top right after this and lands focus on this element again.
const focusedDialog = focused.closest('dialog');
if (
focusedDialog != null &&
focusedDialog !== dialog &&
!focusedDialog.contains(dialog) &&
!dialog.contains(focusedDialog) &&
isSheetHostPresented(focusedDialog)
) {
state.focusToKeep.set(doc, focused);
}
focused.blur();
}
dialog.showModal();
}
/**
* Present a switcher dialog whose backdrop must start, and stay, clear: the
* opacity is set with the scrim transition pinned to 0s, the dialog is
* presented, and the pin is lifted only after a style flush has applied the
* clear backdrop, so no frame eases from a previous backdrop value.
*/
export function presentWithClearScrim(dialog: HTMLDialogElement): void {
dialog.style.setProperty('--_sheet-scrim-duration', '0s');
dialog.style.setProperty('--_sheet-scrim-opacity', '0');
presentStepModally(dialog);
if (typeof getComputedStyle === 'function') {
void getComputedStyle(dialog, '::backdrop').opacity;
}
dialog.style.removeProperty('--_sheet-scrim-duration');
}
/** The pending restore of a dialog's scrim transition; one per host. */
export interface BottomSheetScrimWrite {
frame: number | null;
}
/**
* Write a dialog's scrim opacity. A change while the dialog is up is a change
* of scrim owner, and lands with no transition at all: a `0.01s` duration
* still paints one frame at the old value, which reads as a dip or, with the
* old owner's backdrop still fading, as a doubled dim. The pin
* (`--_sheet-scrim-duration: 0s`, inline) stays for two animation frames
* (two nested `requestAnimationFrame`s: the first frame paints the new value,
* the second confirms it is on screen before the stylesheet's duration
* returns). Hosts cancel the pending restore with `cancelScrimWrite` when
* they unmount.
*/
export function writeScrimOpacity(
dialog: HTMLDialogElement | null,
opacity: '0' | '1',
pending: BottomSheetScrimWrite,
): void {
if (dialog == null) {
return;
}
if (
!dialog.open ||
dialog.style.getPropertyValue('--_sheet-scrim-opacity') === opacity
) {
dialog.style.setProperty('--_sheet-scrim-opacity', opacity);
return;
}
dialog.style.setProperty('--_sheet-scrim-duration', '0s');
dialog.style.setProperty('--_sheet-scrim-opacity', opacity);
cancelScrimWrite(pending);
pending.frame = requestAnimationFrame(() => {
pending.frame = requestAnimationFrame(() => {
pending.frame = null;
dialog.style.removeProperty('--_sheet-scrim-duration');
});
});
}
export function cancelScrimWrite(pending: BottomSheetScrimWrite): void {
if (pending.frame != null) {
cancelAnimationFrame(pending.frame);
pending.frame = null;
}
}
/**
* Whether a sheet's dialog is presented by the browser: as a modal dialog
* (`open`), as a manual popover (a non-modal sheet in the top layer), or by
* `show()` (a non-modal sheet below the Popover API support floor).
*/
export function isSheetHostPresented(
dialog: HTMLDialogElement | null,
): boolean {
if (dialog == null) {
return false;
}
if (dialog.open) {
return true;
}
try {
return dialog.matches(':popover-open');
} catch {
// jsdom and pre-Popover browsers do not recognise :popover-open.
return false;
}
}
/**
* Whether a modal dialog that does not contain `element` is open in its
* document. Such a modal makes everything outside it inert, so a non-modal
* sheet outside it must not paint above it.
*/
export function hasOpenModalOutside(element: Element): boolean {
return openModalsOutside(element).length > 0;
}
/** The open modal dialogs that do not contain `element`; see above. */
function openModalsOutside(element: Element): HTMLDialogElement[] {
const blockers: HTMLDialogElement[] = [];
for (const dialog of Array.from(
element.ownerDocument.querySelectorAll<HTMLDialogElement>('dialog[open]'),
)) {
if (dialog === element || dialog.contains(element)) {
continue;
}
// A modal on its way out blocks nothing any more: it is gone for this
// decision. A closing sheet keeps its dialog modal through the exit
// animation; it is inert and hidden then, unless focus was inside it at
// the close, so the registry's own record of the close counts too.
if (
dialog.hasAttribute('inert') ||
dialog.getAttribute('aria-hidden') === 'true' ||
state.entries.some(
entry => !entry.isOpen && entry.getElement() === dialog,
)
) {
continue;
}
if (isModalDialog(dialog)) {
blockers.push(dialog);
}
}
return blockers;
}
/**
* Non-modal sheets presented by `show()` because a modal outside them was
* open, waiting to enter the top layer once it has gone. Per document, with
* one `close` listener per document: any dialog closing is a reason to look
* again, and so is every sheet-stack update (a closing modal sheet turns
* inert before its dialog closes). An open modal removed from the document
* fires no `close` — a `{isEditing && <Dialog isOpen>}` that unmounts while
* open — so while anything waits, a mutation observer watches removals too
* and looks again when a removed subtree held one of the dialogs that caused
* a deferral. Those blockers are recorded at defer time: `:modal` is the
* mark that matters, and it leaves with the dialog's top-layer membership,
* so it cannot be read off a removed node (nor can `aria-modal`, which a
* `showModal()` host such as MobileNav or Lightbox does not set).
*/
function deferTopLayerEntry(
dialog: HTMLDialogElement,
panel: HTMLElement | null,
blockers: ReadonlyArray<HTMLDialogElement>,
): void {
const doc = dialog.ownerDocument;
let entry = state.deferredTopLayer.get(doc);
if (entry == null) {
entry = {
deferred: new Map(),
blockers: new WeakSet(),
removals: null,
stopListeningForClose: null,
};
state.deferredTopLayer.set(doc, entry);
}
if (entry.stopListeningForClose == null) {
// Installed with the first deferral and removed with the last promotion,
// like the observer below.
const onClose = () => {
promoteDeferredNonModal(doc);
};
doc.addEventListener('close', onClose, true);
entry.stopListeningForClose = () => {
doc.removeEventListener('close', onClose, true);
};
}
entry.deferred.set(dialog, panel);
for (const blocker of blockers) {
entry.blockers.add(blocker);
}
if (entry.removals == null && typeof MutationObserver === 'function') {
const {blockers: known} = entry;
const observer = new MutationObserver(records => {
if (records.some(record => removedABlocker(record, known))) {
promoteDeferredNonModal(doc);
}
});
observer.observe(doc, {childList: true, subtree: true});
entry.removals = observer;
}
}
function removedABlocker(
record: MutationRecord,
blockers: WeakSet<HTMLDialogElement>,
): boolean {
for (const node of Array.from(record.removedNodes)) {
if (!(node instanceof Element)) {
continue;
}
const dialogs =
node instanceof HTMLDialogElement
? [node]
: Array.from(node.querySelectorAll<HTMLDialogElement>('dialog'));
if (dialogs.some(dialog => blockers.has(dialog))) {
return true;
}
}
return false;
}
/**
* Move every waiting non-modal sheet whose outside modals have all gone into
* the top layer: it leaves `show()` and is presented again as a manual
* popover, announcing its entry so global hosts re-enter above it. Focus
* stays where it was.
*/
export function promoteDeferredNonModal(doc: Document): void {
const entry = state.deferredTopLayer.get(doc);
if (entry == null || entry.deferred.size === 0) {
return;
}
const {deferred} = entry;
for (const [dialog, panel] of Array.from(deferred)) {
if (!dialog.isConnected || !dialog.open) {
deferred.delete(dialog);
continue;
}
const blockers = openModalsOutside(dialog);
if (blockers.length > 0) {
// Still waiting, maybe on a modal that was not there at defer time (one
// Dialog replaced by another in a single update): it is a blocker now,
// and its removal must be a reason to look again too.
for (const blocker of blockers) {
entry.blockers.add(blocker);
}
continue;
}
deferred.delete(dialog);
const activeElement = doc.activeElement;
dialog.close();
showSheetHostNonModal(dialog, panel);
if (
doc.activeElement !== activeElement &&
activeElement instanceof HTMLElement &&
activeElement.isConnected
) {
activeElement.focus({preventScroll: true});
}
}
if (deferred.size === 0) {
releaseDeferralWatchers(entry);
}
}
function releaseDeferralWatchers(entry: DeferredTopLayer): void {
entry.removals?.disconnect();
entry.removals = null;
entry.stopListeningForClose?.();
entry.stopListeningForClose = null;
}
function isModalDialog(dialog: HTMLDialogElement): boolean {
// `:modal` is the browser's own answer (every browser with the Popover
// API has it). jsdom answers false to it for every dialog, so the modal
// hosts' own `aria-modal="true"` (Dialog, a scrim BottomSheet) decides
// there.
try {
if (dialog.matches(':modal')) {
return true;
}
} catch {
// An engine without :modal; fall through to the attribute.
}
return dialog.getAttribute('aria-modal') === 'true';
}
/**
* Present a non-modal sheet: in the top layer as a manual popover where the
* Popover API exists (Tier 2 and up), so later sheets order above earlier
* ones and no page-level z-index is needed; by `show()` below that floor.
* A manual popover has no light dismiss, no backdrop and no focus or scroll
* side effects, so the non-modal contract is otherwise unchanged.
*
* A non-modal sheet shown while a modal dialog that does not contain it is
* open (a modal sheet, a Dialog) is inert under that modal, so it is not put
* in the top layer — there it would paint above the modal while a press on
* it lands on the modal beneath — and is presented by `show()` instead, in
* page stacking order beneath the modal, with no page-level z-index; once
* the last such modal has gone it is presented again in the top layer
* (`promoteDeferredNonModal`). A non-modal sheet rendered inside the modal's
* content is not inert and enters the top layer at once.
*/
export function showSheetHostNonModal(
dialog: HTMLDialogElement,
panel: HTMLElement | null,
): void {
if (typeof dialog.showPopover !== 'function') {
dialog.show();
return;
}
const blockers = openModalsOutside(dialog);
if (blockers.length > 0) {
dialog.show();
deferTopLayerEntry(dialog, panel, blockers);
return;
}
// Both native paths run the engine's focusing steps, and engines differ.
// Chromium's `show()` lands on the first focusable area in tree order,
// the panel (`tabindex="-1"`, no focus ring), while its `showPopover()`
// skips such containers and lands on the first control; Firefox lands on
// the first control on both paths. The sheet must focus as it did with
// `show()` in the engine at hand, and no control may be focused and
// blurred on the way (a field validating on blur would show its error on
// open). So the popover's focusing steps are pointed at the panel first:
// `autofocus` on the panel for the duration of `showPopover()` makes it
// the steps' autofocus delegate in every engine, and the panel is where a
// container-focusing engine's `show()` lands. Where the engine's `show()`
// skips the container and lands on the first control, focus moves from
// the panel to that control once — a focus on the control, no blur.
const doc = dialog.ownerDocument;
const hadAutofocus = panel?.hasAttribute('autofocus') ?? false;
if (panel != null && !hadAutofocus) {
panel.setAttribute('autofocus', '');
}
try {
dialog.showPopover();
} finally {
if (panel != null && !hadAutofocus) {
panel.removeAttribute('autofocus');
}
}
// The sheet is now the newest top-layer entry: global hosts shown before
// it (the toast viewport) re-enter above it, as they do above a modal.
notifyTopLayerEntry();
if (
panel != null &&
doc.activeElement === panel &&
!nativeShowFocusesContainer(dialog)
) {
firstSequentiallyFocusable(panel)?.focus({preventScroll: true});
}
}
/**
* The first element inside `root`, in tree order, that sequential focus
* navigation reaches: focusable, with a tab index of zero or more, not
* disabled, not inert, and rendered. This is where an engine whose
* `show()` skips programmatically focusable containers lands.
*/
function firstSequentiallyFocusable(root: HTMLElement): HTMLElement | null {
const candidates = root.querySelectorAll<HTMLElement>(
'a[href], area[href], button, input, select, textarea, iframe, summary, [contenteditable]:not([contenteditable="false"]), [tabindex]',
);
for (const candidate of Array.from(candidates)) {
if (candidate === root || candidate.tabIndex < 0) {
continue;
}
if (
(candidate as HTMLButtonElement).disabled === true ||
candidate.closest('[inert]') != null ||
candidate.getAttribute('type') === 'hidden' ||
candidate.hidden ||
(typeof candidate.checkVisibility === 'function' &&
!candidate.checkVisibility())
) {
continue;
}
return candidate;
}
return null;
}
let showFocusesContainer: boolean | null = null;
/**
* Whether this engine's `dialog.show()` focusing steps land on a
* programmatically focusable container (`tabindex="-1"`) that comes before
* the first control — Chromium does, Firefox skips it. Measured once, on a
* throwaway non-modal dialog that is shown, read and removed inside one
* task (no paint); focus is put back where it was. The probe lives inside
* `host`, the sheet's own dialog, which is in the top layer and interactive
* at this point (a lone sheet, or one inside the open modal's content): a
* probe appended to the body could sit under an open modal's inertness,
* where `show()` moves no focus, and cache the wrong answer for the page.
*/
function nativeShowFocusesContainer(host: HTMLDialogElement): boolean {
if (showFocusesContainer != null) {
return showFocusesContainer;
}
const doc = host.ownerDocument;
const activeBefore = doc.activeElement;
const probe = doc.createElement('dialog');
probe.setAttribute('aria-hidden', 'true');
probe.style.cssText =
'position:fixed;inset:auto;opacity:0;pointer-events:none';
const container = doc.createElement('div');
container.tabIndex = -1;
const control = doc.createElement('button');
control.type = 'button';
container.appendChild(control);
probe.appendChild(container);
host.appendChild(probe);
try {
probe.show();
showFocusesContainer = doc.activeElement === container;
probe.close();
} catch {
showFocusesContainer = true;
} finally {
probe.remove();
if (
doc.activeElement !== activeBefore &&
activeBefore instanceof HTMLElement &&
activeBefore.isConnected
) {
activeBefore.focus({preventScroll: true});
}
}
return showFocusesContainer;
}
/** Leave the native host, whichever one presents the sheet. */
export function hideSheetHost(dialog: HTMLDialogElement): void {
const entry = state.deferredTopLayer.get(dialog.ownerDocument);
if (entry != null && entry.deferred.delete(dialog)) {
if (entry.deferred.size === 0) {
releaseDeferralWatchers(entry);
}
}
if (
dialog.hasAttribute('popover') &&
typeof dialog.hidePopover === 'function'
) {
try {
dialog.hidePopover();
} catch {
// Not showing as a popover (the show() fallback); nothing to hide here.
}
}
if (dialog.open) {
dialog.close();
}
}
/**
* Close a dialog without letting the browser move focus. `close()` returns
* focus to the element that was focused when `showModal()` ran; with another
* sheet still open on top, that would pull focus out of the sheet the person
* is using (a re-show that repairs the top-layer order, a covered sheet
* closing from code, a replaced sheet leaving). Focus stays where it is; the
* caller decides where it goes next, if anywhere.
*/
export function closeDialogKeepingFocus(
dialog: HTMLDialogElement | null,
): void {
if (dialog == null || !isSheetHostPresented(dialog)) {
return;
}
const doc = dialog.ownerDocument;
const activeElement = doc.activeElement;
hideSheetHost(dialog);
if (
doc.activeElement !== activeElement &&
activeElement instanceof HTMLElement &&
activeElement.isConnected
) {
activeElement.focus({preventScroll: true});
}
}
/**
* Pair the one close and the one open of this batch as a replace. A replace
* is a move the person makes from one sheet to the next, and that is what
* the conditions check:
*
* - exactly one sheet closed and exactly one opened in this update;
* - both are standalone sheets of one group — one document, both modal or
* both non-modal (a switcher flow replaces its own steps and is never
* paired);
* - the closing sheet was the top sheet of its stack once the opening sheet
* is set aside — a covered sheet closing while a sheet opens is a pop
* beneath a push;
* - neither dialog contains the other — a sheet in another's content closes
* with it, it does not replace it;
* - the interaction came from inside the closing sheet: the control the
* person last pressed (or, with no recent press, the element focused when
* this update's first flip arrived, before any dialog of the update was
* shown) is in its dialog, or nowhere (a control that left with the step).
* A close and an open driven from a control outside the closing sheet are
* two unrelated owners acting in one update, so the sheets keep their own
* openers and their own push and pop motion.
*
* The opening sheet then adopts the closing sheet's opener: its own opener
* is inside the sheet that is leaving, and the flow began where the closing
* sheet's did.
*/
function detectReplace(): void {
if (state.batchOpened.length !== 1 || state.batchClosed.length !== 1) {
// A pair made earlier in this commit, before a third flip arrived, is
// undone: the commit's final tally decides, and several sheets changing
// in one update keep their own push and pop motion.
undoBatchPair();
return;
}
const [replacer] = state.batchOpened;
const [replaced] = state.batchClosed;
if (state.batchPair != null && state.batchPair.replaced === replaced) {
return;
}
if (
replaced === replacer ||
replaced.replaceable == null ||
replacer.replaceable == null ||
replaced.doc !== replacer.doc ||
replaced.isModal !== replacer.isModal ||
replaced.replace?.replacer === replacer ||
!replacer.isOpen ||
replaced.isOpen
) {
return;
}
const replacedElement = replaced.getElement();
const replacerElement = replacer.getElement();
if (
replacedElement == null ||
replacerElement == null ||
replacedElement.contains(replacerElement) ||
replacerElement.contains(replacedElement)
) {
return;
}
const wasTop = !groupOf(replaced).some(
other =>
other !== replacer &&
other !== replaced &&
other.isOpen &&
compareRank(other, replaced) > 0,
);
if (!wasTop) {
return;
}
const actor = state.batchActor;
const actedFromReplaced =
actor == null ||
actor === replaced.doc.body ||
replacedElement.contains(actor);
if (!actedFromReplaced) {
return;
}
// A third sheet the closing sheet was itself replacing is dropped at once,
// the way a switcher drops a step that is left mid-handoff. The sheet it
// was replacing may instead be the one coming back now (a reversal): then
// the roles swap and nothing is dropped.
if (replaced.replacing != null && replaced.replacing !== replacer) {
finishReplace(replaced.replacing);
}
if (replaced.replace != null) {
replaced.replace.replacer.replacing = null;
}
if (replacer.replace != null) {
replacer.replace = null;
}
replaced.replace = {
replacer,
motion: 'covered',
alignmentOffset: 0,
isAlignmentComplete: false,
isEnteringComplete: false,
};
replacer.replacing = replaced;
state.batchPair = {
replaced,
replacer,
replacerOpener: replacer.replaceable.getOpener(),
};
// The press that made this replace is consumed by it.
state.lastPress.delete(replacer.doc);
replacer.replaceable.setOpener(replaced.replaceable.getOpener());
state.pendingReplaceFocus = replacer;
}
/**
* Undo the pair this batch made: the replaced sheet is an ordinary closing
* sheet again, the replacer an ordinary opening one with its own opener, and
* no focus is owed. Called when a later flip of the same commit changes the
* tally, before the commit paints.
*/
function undoBatchPair(): void {
const pair = state.batchPair;
if (pair == null) {
return;
}
state.batchPair = null;
const {replaced, replacer, replacerOpener} = pair;
if (replaced.replace?.replacer === replacer) {
replaced.replace = null;
}
if (replacer.replacing === replaced) {
replacer.replacing = null;
}
replacer.replaceable?.setOpener(replacerOpener);
if (state.pendingReplaceFocus === replacer) {
state.pendingReplaceFocus = null;
}
}
/**
* The person moves from the replaced step to the entering one, so focus
* does too, and it lands on the step's `data-autofocus` descendant when it
* has one. The dialog is shown by now, so the native focusing steps have
* run: a modal replacer's `showModal()` put focus on the entering panel, a
* non-modal replacer's `showPopover()` may have left it where it was (Safari;
* the replaced step is inert from this frame). Either way the placement runs
* after them — focus sitting on the panel, or anywhere that is not the
* `data-autofocus` descendant, is the native steps' doing, not the
* person's, so it does not count as placed. Only focus the person already
* moved to a control inside the entering step is left alone.
*/
function focusPendingReplacer(): void {
const replacer = state.pendingReplaceFocus;
if (replacer == null) {
return;
}
const element = replacer.getElement();
if (element == null || !isSheetHostPresented(element)) {
return;
}
state.pendingReplaceFocus = null;
replacer.focus('replace');
}
/**
* End a replace: the replaced sheet is hidden and its dialog closed; the
* views computed next hand the scrim to the sheet that replaced it, which
* takes it in the same frame. Focus stays where it is.
*/
function finishReplace(replaced: Entry): void {
const replace = replaced.replace;
if (replace == null) {
return;
}
const {replacer} = replace;
replaced.replace = null;
if (replacer.replacing === replaced) {
replacer.replacing = null;
}
replaced.hide();
replaced.replaceable?.finish();
}
/**
* The viewport top a panel rests at: its box without the translation it is
* still travelling under (an entering panel rises from below the viewport).
* Read from the panel itself, never from the element around it: a standalone
* sheet's panel sits directly in its dialog, which spans the viewport, so a
* parent's top is not where the panel rests.
*/
function restingTopOfPanel(panel: HTMLElement): number {
const top = panel.getBoundingClientRect().top;
const view = panel.ownerDocument.defaultView;
if (view == null || typeof view.DOMMatrixReadOnly !== 'function') {
return top;
}
const {transform} = view.getComputedStyle(panel);
if (transform === '' || transform === 'none') {
return top;
}
// A sheet panel only ever translates on the block axis (entrance, drag,
// alignment); its computed matrix's `m42` is that translation.
return top - new view.DOMMatrixReadOnly(transform).m42;
}
function alignmentOffsetForPanels(
enteringPanel: HTMLElement | null,
retainedPanel: HTMLElement | null,
): number {
if (enteringPanel == null || retainedPanel == null) {
return 0;
}
// The retained panel is at rest; the entering panel is measured where its
// entrance will leave it.
return Math.max(
0,
restingTopOfPanel(enteringPanel) -
retainedPanel.getBoundingClientRect().top,
);
}
/**
* A host's panel reports the start and end of its motions here. During a
* replace they drive the handoff: when the entering sheet starts to rise, a
* taller retained sheet starts moving down to its top edge; the retained
* sheet fades once both have finished; when the fade ends the replace is over.
*/
export function reportBottomSheetMotion(
key: object,
event: 'start' | 'complete',
motion: BottomSheetReplaceMotion,
): void {
const entry = state.entries.find(candidate => candidate.key === key);
if (entry == null) {
return;
}
if (motion === 'entering') {
const replaced = entry.replacing;
const replace = replaced?.replace ?? null;
if (replaced == null || replace == null || replace.replacer !== entry) {
return;
}
if (event === 'start') {
if (replace.motion !== 'covered') {
return;
}
const alignmentOffset = alignmentOffsetForPanels(
entry.replaceable?.getPanel() ?? null,
replaced.replaceable?.getPanel() ?? null,
);
if (alignmentOffset > ALIGNMENT_THRESHOLD_PX) {
replace.motion = 'aligning';
replace.alignmentOffset = alignmentOffset;
replace.isAlignmentComplete = false;
}
// A sheet that came back while fading is already where it belongs:
// its entrance is over as soon as it starts, like a switcher step's.
if (entry.isEnteringInPlace) {
entry.isEnteringInPlace = false;
replace.isEnteringComplete = true;
if (replace.motion !== 'aligning') {
replace.motion = 'fading';
}
} else if (replace.motion === 'covered') {
return;
}
} else {
replace.isEnteringComplete = true;
if (replace.motion === 'aligning' && !replace.isAlignmentComplete) {
return;
}
replace.motion = 'fading';
}
update(entry.doc, entry.isModal);
return;
}
const replace = entry.replace;
if (replace == null || event !== 'complete') {
return;
}
if (motion === 'aligning' && replace.motion === 'aligning') {
if (replace.isEnteringComplete) {
replace.motion = 'fading';
} else {
replace.isAlignmentComplete = true;
}
update(entry.doc, entry.isModal);
} else if (motion === 'fading' && replace.motion === 'fading') {
finishReplace(entry);
update(entry.doc, entry.isModal);
}
}
/**
* Make a document's top layer match the ranked order. The top layer is
* append-only, so a dialog can only move up, by closing and showing it again:
* the longest prefix of the wanted order that the shown order already
* contains, in order, is kept, and every dialog after it is re-shown in
* order (closing them from the top first). A deep link whose inner sheet
* registered first therefore re-shows inner and outer; a sheet that must
* rise above the sheets shown after it re-shows only itself, so a retained
* sheet beneath it keeps its backdrop and any motion in flight. Runs inside
* the commit, so a wrong intermediate order never paints. Focus moves into
* the top open sheet when anything was shown — unless the person was already
* in a sheet that is only re-shown to keep its place (a switcher flow it
* covers changed step from code, say): the element they were in, a field
* being typed in, is the dialog's focus delegate for that `showModal()` and
* is focused again right after it, so the keystrokes that follow still land
* there. The top layer is append-only, so the re-show has to close the dialog
* first and the field sees one blur and one focus; nothing shorter exists.
*/
function reconcileTopLayer(
doc: Document,
isModal: boolean,
order: Entry[],
): void {
const shownOrder = getShownOrder(doc, isModal);
const presentable = order.filter(entry => {
const element = entry.getElement();
return element != null && element.isConnected;
});
let kept = 0;
let cursor = 0;
while (kept < presentable.length) {
const next = shownOrder.indexOf(presentable[kept], cursor);
if (next === -1) {
break;
}
cursor = next + 1;
kept += 1;
}
const keptEntries = new Set(presentable.slice(0, kept));
const reshown = presentable.slice(kept);
const keptActive = activeElementToKeep(doc, reshown);
let didShow = false;
for (let index = shownOrder.length - 1; index >= 0; index -= 1) {
if (!keptEntries.has(shownOrder[index])) {
shownOrder[index].hide();
}
}
for (const entry of reshown) {
const delegate =
keptActive != null && entry.getElement()?.contains(keptActive)
? keptActive
: null;
// The native focusing steps follow an `autofocus` delegate, so the
// re-shown dialog lands on the element the person was in instead of its
// first focusable area; the attribute is the dialog's for this call only.
const hadAutofocus = delegate?.hasAttribute('autofocus') ?? false;
if (delegate != null && !hadAutofocus) {
delegate.setAttribute('autofocus', '');
}
entry.show();
if (delegate != null && !hadAutofocus) {
delegate.removeAttribute('autofocus');
}
didShow = true;
}
setShownOrder(doc, isModal, presentable);
if (!didShow) {
return;
}
// A dialog shown again (closed and re-shown to keep its place) went back
// into the top layer above everything shown before, a global host's
// popover hosted inside it included: that popover still reads as showing
// but paints beneath the dialog now. Hosts re-enter the top layer in
// place, as they do above a non-modal surface that just entered, so toasts
// raised in the re-shown sheet still paint above it. A first show needs
// none of this: the outlet it supplies moves the hosts.
if (reshown.some(entry => shownOrder.includes(entry))) {
notifyTopLayerEntry();
}
if (keptActive != null && keptActive.isConnected) {
if (doc.activeElement !== keptActive) {
keptActive.focus({preventScroll: true});
}
return;
}
const openEntries = presentable.filter(entry => entry.isOpen);
openEntries[openEntries.length - 1]?.focus('open');
}
/**
* The element to keep focused across a re-show: the document's active
* element when it is inside an open sheet that is about to be re-shown.
*/
function activeElementToKeep(
doc: Document,
reshown: ReadonlyArray<Entry>,
): HTMLElement | null {
const remembered = state.focusToKeep.get(doc);
state.focusToKeep.delete(doc);
const current = doc.activeElement;
const active =
remembered != null && remembered.isConnected
? remembered
: current instanceof HTMLElement && current !== doc.body
? current
: null;
if (active == null) {
return null;
}
for (const entry of reshown) {
const element = entry.getElement();
if (entry.isOpen && element != null && element.contains(active)) {
return active;
}
}
return null;
}
function update(doc: Document, isModal: boolean): void {
detectReplace();
// A drop can land as soon as the batch has both of its flips: the pairing
// is decided then, and anything left `replace`d is a retained sheet whose
// replacer left the flow.
if (state.batchOpened.length > 0 && state.batchClosed.length > 0) {
flushPendingDrops();
}
const order = sortedEntries(doc, isModal);
computeViews(order, isModal);
reconcileTopLayer(doc, isModal, order);
state.focusToKeep.delete(doc);
focusPendingReplacer();
promoteDeferredNonModal(doc);
}
/**
* Join the stack for as long as the sheet is presented. Call from a layout
* effect; the returned function leaves the stack (also from its cleanup).
* `isOpen` is the controlled open state; a presented sheet whose `isOpen` is
* false is sliding out and keeps its place without counting as a layer.
*/
export function registerBottomSheet(
registration: BottomSheetStackRegistration,
isOpen: boolean,
isModal: boolean = true,
): () => void {
const {key} = registration;
const remembered = state.rankByKey.get(key);
let rank: Rank;
if (
remembered != null &&
!remembered.isClosed &&
// A StrictMode replay unregisters and registers again in one synchronous
// pass, before any seal; the rank is kept so the replay cannot reorder.
// A sheet React hid (Suspense, Activity) and later revealed comes back in
// a later batch and re-presents on top, like a fresh open.
(remembered.detachedBatch == null ||
remembered.detachedBatch === state.currentBatch)
) {
rank = {batch: remembered.batch, seq: remembered.seq};
remembered.detachedBatch = null;
} else {
rank = takeRank();
state.rankByKey.set(key, {
...rank,
isClosed: !isOpen,
detachedBatch: null,
});
}
const doc = registration.getElement()?.ownerDocument ?? document;
listenForPresses(doc);
const entry: Entry = {
...registration,
rank,
isOpen,
doc,
isModal,
view: BOTTOM_SHEET_STACK_DEFAULT_VIEW,
replace: null,
replacing: null,
isEnteringInPlace: false,
};
state.entries.push(entry);
if (isOpen && rank.batch === state.currentBatch && state.isBatchDirty) {
recordFlip(entry, 'opened');
}
update(entry.doc, entry.isModal);
return () => {
const index = state.entries.indexOf(entry);
if (index === -1) {
return;
}
state.entries.splice(index, 1);
stopListeningForPresses(entry.doc);
setShownOrder(
entry.doc,
entry.isModal,
getShownOrder(entry.doc, entry.isModal).filter(shown => shown !== entry),
);
state.batchOpened = state.batchOpened.filter(other => other !== entry);
state.batchClosed = state.batchClosed.filter(other => other !== entry);
state.pendingDrops = state.pendingDrops.filter(other => other !== entry);
if (state.pendingReplaceFocus === entry) {
state.pendingReplaceFocus = null;
}
if (
state.batchPair?.replaced === entry ||
state.batchPair?.replacer === entry
) {
state.batchPair = null;
}
// A member of a "Close all" group leaving the registry has left for
// good: a host that unmounts mid-exit never sends its motion report, so
// leaving is its completion. Reported after `hide()` below, once its
// dialog is out of the top layer, so the return focus has nothing modal
// in its way; a host that still reports afterwards finds nothing to do.
const closingGroup = state.closingTogether.get(entry);
if (entry.replace != null) {
entry.replace.replacer.replacing = null;
entry.replace = null;
}
if (entry.replacing != null) {
// The sheet it was replacing is left as an ordinary closing sheet.
entry.replacing.replace = null;
entry.replacing = null;
}
// A sheet that leaves while its dialog is still open was hidden by React
// (Suspense, Activity) or is unmounting: a modal dialog with no box would
// keep blocking the page, so it leaves the top layer here.
entry.hide();
if (closingGroup != null) {
leaveClosingGroup(entry, closingGroup);
}
const current = state.rankByKey.get(key);
if (current != null) {
current.detachedBatch = state.currentBatch;
state.isBatchDirty = true;
scheduleSeal();
}
entry.view = BOTTOM_SHEET_STACK_DEFAULT_VIEW;
entry.onView(entry.view);
update(entry.doc, entry.isModal);
};
}
/**
* The dialog that realizes a level changed: a switcher flow handed off to a
* step with its own dialog, which its host presented on top of the top layer
* in this same commit. The level keeps its rank; the registry records the new
* dialog as the most recently shown and puts the sheets that belong above it
* back on top before paint. A level on its own, or already on top, is left
* alone.
*/
export function notifyBottomSheetHostChanged(key: object): void {
const entry = state.entries.find(candidate => candidate.key === key);
if (entry == null || !entry.isModal) {
return;
}
const element = entry.getElement();
if (element == null || !isSheetHostPresented(element)) {
return;
}
const shown = getShownOrder(entry.doc, true).filter(
shownEntry => shownEntry !== entry,
);
shown.push(entry);
setShownOrder(entry.doc, true, shown);
update(entry.doc, true);
}
/**
* Report the controlled open state of a registered sheet. Closing keeps the
* sheet's place while it slides out; reopening takes a new rank, so the sheet
* returns on top.
*/
export function setBottomSheetOpen(key: object, isOpen: boolean): void {
const entry = state.entries.find(candidate => candidate.key === key);
if (entry == null || entry.isOpen === isOpen) {
return;
}
entry.isOpen = isOpen;
const remembered = state.rankByKey.get(key);
if (isOpen) {
if (state.closingTogether.has(entry)) {
const group = state.closingTogether.get(entry);
state.closingTogether.delete(entry);
group?.pending.delete(entry);
}
entry.rank = takeRank();
state.rankByKey.set(key, {
...entry.rank,
isClosed: false,
detachedBatch: null,
});
recordFlip(entry, 'opened');
// Reopened while being replaced: it is a sheet again, not a fading one.
if (entry.replace != null) {
entry.replace.replacer.replacing = null;
entry.replace = null;
entry.isEnteringInPlace = true;
}
} else {
if (remembered != null) {
remembered.isClosed = true;
}
state.isBatchDirty = true;
scheduleSeal();
recordFlip(entry, 'closed');
entry.isEnteringInPlace = false;
// A replacing sheet that closes drops the sheet it was replacing, the way
// a switcher hides a retained step when the flow is left — unless that
// sheet is the one coming back in this same update (Continue pressed
// during a Back handoff), which `detectReplace` pairs as the reverse
// replace. The other flips of this commit may not have arrived yet, so
// the drop waits for the seal; a paired sheet is no longer `replace`d by
// then and is left alone.
if (entry.replacing != null) {
state.pendingDrops.push(entry.replacing);
}
}
update(entry.doc, entry.isModal);
}
/**
* Drop the retained sheets whose replacer closed in this batch and that no
* replace of this batch took back. Runs when the batch is sealed and, before
* that, whenever a pairing has been decided, so the drop lands in the same
* commit as the close that caused it.
*/
function flushPendingDrops(): void {
if (state.pendingDrops.length === 0) {
return;
}
const drops = state.pendingDrops;
state.pendingDrops = [];
for (const replaced of drops) {
const replacer = replaced.replace?.replacer;
if (replacer != null && !replacer.isOpen) {
finishReplace(replaced);
}
}
}
/**
* The open sheet directly beneath `key`: its dialog, and a way to move focus
* into it. Null when nothing open is beneath. A closing top sheet asks this
* to return focus into the sheet it reveals.
*/
export function getBottomSheetBeneath(
key: object,
): {element: HTMLDialogElement; focus: () => void} | null {
const own = state.entries.find(entry => entry.key === key);
if (own == null) {
return null;
}
const order = groupOf(own);
for (let below = order.indexOf(own) - 1; below >= 0; below -= 1) {
const entry = order[below];
const element = entry.getElement();
if (entry.isOpen && element != null) {
return {element, focus: () => entry.focus('reveal')};
}
}
return null;
}
// preventScroll on both: presenting a sheet must not scroll the page to reveal
// what it just focused. For an autofocused field that reveal is the mobile
// keyboard's, and it moves the document under a fixed sheet. useMobileKeyboard
// brings the field into view within the sheet instead.
/** A field in a sheet nested in this content belongs to that sheet. */
function focusFirstEligibleAutofocus(panel: HTMLElement): boolean {
const dialog = panel.closest('dialog');
for (const candidate of panel.querySelectorAll<HTMLElement>(
'[data-autofocus]',
)) {
if (
candidate.closest('dialog') !== dialog ||
candidate.closest('[inert]') != null ||
(typeof candidate.checkVisibility === 'function' &&
!candidate.checkVisibility())
) {
continue;
}
candidate.focus({preventScroll: true});
if (candidate.ownerDocument.activeElement === candidate) {
return true;
}
}
return false;
}
/**
* Move focus into a sheet panel. On `reveal`, and on `replace` once a control
* inside has focus, focus stays put. On `open` and on `replace` the
* native host has run its own focusing steps, which may land on the panel
* (`tabindex="-1"`, as Chromium's do) or on the first control (Firefox); an
* eligible `data-autofocus` descendant then takes focus first, modal or not.
* Without one, an `open` keeps the native landing and a `replace` focuses the
* entering panel. On `reveal` the panel itself takes focus, with a ring only
* after keyboard input.
*/
export function focusSheetPanel(
panel: HTMLElement | null,
reason: BottomSheetFocusReason,
isModal: boolean,
): void {
if (panel == null) {
return;
}
// A covered sheet takes no focus: its dialog is inert (the stack marks it
// so, and a modal above it blocks it in the browser anyway), so a step that
// enters beneath a sheet on top — a covered switcher flow changing step from
// code — leaves the person where they are, in the sheet on top.
const host = panel.closest('dialog');
if (
host != null &&
(host.hasAttribute('inert') || host.getAttribute('aria-hidden') === 'true')
) {
return;
}
// Focus already inside this sheet's own content stays put. Focus inside a
// sheet rendered within this content (a closing nested sheet) does not
// count: that sheet's dialog is leaving, and this one is being revealed.
// On an open, the native focusing steps have just run. What they focused
// is not the person's choice. An eligible `data-autofocus` field takes
// focus over it. On a replace, focus the steps left on the entering panel
// is not a placement either, but focus on a control inside it stays put.
const activeElement = panel.ownerDocument.activeElement;
const isInsidePanel =
activeElement != null &&
panel.contains(activeElement) &&
activeElement.closest('dialog') === panel.closest('dialog');
if (
isInsidePanel &&
(reason === 'reveal' || (reason === 'replace' && activeElement !== panel))
) {
return;
}
if (reason === 'reveal') {
focusForLastInput(panel);
return;
}
if (
(isInsidePanel && activeElement?.hasAttribute('data-autofocus') === true) ||
focusFirstEligibleAutofocus(panel)
) {
return;
}
if (!isInsidePanel && (isModal || reason === 'replace')) {
// A lone non-modal sheet takes no focus on open; the step replacing the
// one the person was in does, so the keyboard stays in the flow. Focus
// the native steps already put on the panel needs no second focus().
panel.focus({preventScroll: true});
}
}
/** Test-only: the presented sheets' dialogs, bottom to top, with their views. */
export function getBottomSheetStackForTests(
doc: Document = document,
isModal: boolean = true,
): ReadonlyArray<{
element: HTMLDialogElement | null;
isOpen: boolean;
view: BottomSheetStackView;
}> {
return sortedEntries(doc, isModal).map(entry => ({
element: entry.getElement(),
isOpen: entry.isOpen,
view: entry.view,
}));
}
/** Test-only: forget every sheet and start the batch counter over. */
export function resetBottomSheetStackForTests(): void {
showFocusesContainer = null;
// The press listeners go with the entries they served.
for (const entry of state.entries) {
const remove = state.listenedDocuments.get(entry.doc);
if (remove != null) {
state.listenedDocuments.delete(entry.doc);
remove();
}
}
state.entries.length = 0;
state.shownOrder = new WeakMap();
state.batchOpened = [];
state.batchClosed = [];
state.batchActor = null;
state.pendingDrops = [];
state.pendingReplaceFocus = null;
state.closingTogether = new Map();
state.currentBatch = 0;
state.nextSeq = 0;
state.isBatchDirty = false;
state.isSealScheduled = false;
state.focusToKeep = new WeakMap();
// Deferral watchers on the test document go with the deferrals they
// served (a WeakMap cannot be walked; the test document is the one place
// a test can have deferred into).
const deferral = state.deferredTopLayer.get(document);
if (deferral != null) {
releaseDeferralWatchers(deferral);
}
state.deferredTopLayer = new WeakMap();
}
/** Test-only: the shared state's key, shape and protocol version, for the two-copies tests. */
export const BOTTOM_SHEET_STACK_STATE_FOR_TESTS = {
key: STACK_STATE_KEY,
shape: STACK_STATE_SHAPE,
protocolVersion: STACK_PROTOCOL_VERSION,
keyFor: (version: number) =>
Symbol.for(`astryx.bottomSheetStack.v${version}`),
/** Whether the document has the press listeners installed. */
isListeningForPresses: (doc: Document) => state.listenedDocuments.has(doc),
};