An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file useScheduleViewPopover.ts
* @input The dialog name for the open trigger's key, or for no open trigger,
* and where focus goes when the open trigger stops being painted
* @output One view-owned Popover with its open key, trigger props, the press
* model that lets one gesture switch triggers, a switch of the open content
* inside the popover, and a close when the open trigger is no longer painted
* @position Internal hook for Schedule views that own a popover (the month
* view's popover, component:Schedule FR17, FR20); not exported
*/
import {
useCallback,
useEffect,
useRef,
useState,
type MouseEvent as ReactMouseEvent,
type PointerEvent as ReactPointerEvent,
} from 'react';
import {layerAnimations} from '@astryxdesign/core/Layer';
import {usePopover, type UsePopoverReturn} from '@astryxdesign/core/Popover';
const TRIGGER_ATTRIBUTE = 'data-schedule-popover-trigger';
export interface ScheduleViewPopover {
/** The view's one popover. Render it with `popover.render(content, …)`. */
readonly popover: UsePopoverReturn;
/** Key of the trigger whose popover is open, or null. */
readonly openKey: string | null;
/** Spread on an element that contains every trigger. */
readonly containerProps: {
onPointerDownCapture: (event: ReactPointerEvent<HTMLElement>) => void;
onKeyDownCapture: () => void;
};
/**
* Props of one trigger button. Calling it also marks the trigger as painted
* this render; the popover closes when its trigger was not. A trigger may
* own open keys it did not open itself (`ownsOpenKey`): content switched to
* from inside its popover keeps it expanded and painted.
*/
getTriggerProps: (
key: string,
ownsOpenKey?: (openKey: string) => boolean,
) => {
'aria-haspopup': 'dialog';
'aria-expanded': boolean;
'aria-controls': string;
[TRIGGER_ATTRIBUTE]: string;
onClick: (event: ReactMouseEvent<HTMLButtonElement>) => void;
};
/**
* Shows `key`'s content in the open popover, in the same gesture, and moves
* focus into it. The popover keeps its trigger, so focus returns there.
*/
switchTo: (key: string) => void;
}
const FALLBACK_CLOSE = '[data-astryx-popover-fallback-close]';
const FOCUSABLE =
'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
/**
* One popover for a view, opened from any of its trigger buttons. The popover
* is the system's standard Popover: a modal dialog named by `dialogLabelFor`
* of the open key, auto-focus, a hidden fallback close, Escape and light
* dismiss, focus return, and the standard surface and padding. While nothing
* is open the dialog is not shown, but it still carries a name, so the view
* never mounts an unnamed dialog.
*/
export function useScheduleViewPopover(
dialogLabelFor: (key: string | null) => string,
onTriggerLost?: (key: string) => void,
): ScheduleViewPopover {
const [openKey, setOpenKey] = useState<string | null>(null);
const popover = usePopover({
dialogLabel: dialogLabelFor(openKey),
// Popover's own defaults, spelled out where the hook's differ.
padding: 3,
surfaceTarget: 'popover',
// The entrance runs on the surface: an anchored layer lays out again on
// each frame its own style animates.
xstyle: layerAnimations.below,
onHide: useCallback(() => {
setOpenKey(null);
}, []),
});
// A pointer press on a trigger while the popover is open would close it by
// the browser's light dismiss before the click arrives, and the layer then
// absorbs a show() from that same press. So the press itself decides: a
// press on another trigger closes the popover here, ahead of the browser,
// and the click that follows opens the pressed trigger; a press on the open
// trigger is remembered so its click ends closed, whichever of the two
// closed it. A key press starts a new gesture and forgets the press.
const openKeyAtPressRef = useRef<string | null>(null);
const onPointerDownCapture = (event: ReactPointerEvent<HTMLElement>) => {
const target = event.target as Element | null;
const pressedKey =
target
?.closest(`[${TRIGGER_ATTRIBUTE}]`)
?.getAttribute(TRIGGER_ATTRIBUTE) ?? null;
openKeyAtPressRef.current = pressedKey == null ? null : openKey;
if (
pressedKey != null &&
openKey != null &&
pressedKey !== openKey &&
popover.isOpen
) {
popover.hide();
}
};
const onKeyDownCapture = () => {
openKeyAtPressRef.current = null;
};
const toggle = (key: string, button: HTMLButtonElement) => {
const openAtPress = openKeyAtPressRef.current;
openKeyAtPressRef.current = null;
if (openAtPress === key || (openKey === key && popover.isOpen)) {
if (popover.isOpen) {
popover.hide();
}
return;
}
setOpenKey(key);
popover.triggerRef(button);
popover.show();
};
// Content switched to inside an open popover takes focus once it renders,
// the way the popover's own auto-focus does when it opens.
const focusSwitchedContentRef = useRef(false);
const switchTo = (key: string) => {
if (!popover.isOpen) {
return;
}
focusSwitchedContentRef.current = true;
setOpenKey(key);
};
useEffect(() => {
if (!focusSwitchedContentRef.current) {
return;
}
focusSwitchedContentRef.current = false;
const frame = requestAnimationFrame(() => {
const content = popover.contentRef.current;
if (content == null) {
return;
}
const first = Array.from(
content.querySelectorAll<HTMLElement>(FOCUSABLE),
).find(element => element.closest(FALLBACK_CLOSE) == null);
(first ?? content).focus();
});
return () => cancelAnimationFrame(frame);
}, [openKey, popover.contentRef]);
// Triggers painted this render; the popover may stay open only for one of
// them. When its trigger is gone, focus — inside the popover, or dropped
// to the page with the trigger — has nowhere to return to, so the view
// decides where it lands.
const paintedKeys = new Set<string>();
useEffect(() => {
if (openKey != null && !paintedKeys.has(openKey)) {
const content = popover.contentRef.current;
const active = document.activeElement;
const hadFocus =
active == null ||
active === document.body ||
(content?.contains(active) ?? false);
popover.hide();
setOpenKey(null);
if (hadFocus) {
onTriggerLost?.(openKey);
}
}
});
return {
popover,
openKey,
containerProps: {onPointerDownCapture, onKeyDownCapture},
getTriggerProps: (key, ownsOpenKey) => {
paintedKeys.add(key);
const ownsOpen =
openKey != null && openKey !== key && (ownsOpenKey?.(openKey) ?? false);
if (ownsOpen) {
paintedKeys.add(openKey);
}
return {
'aria-haspopup': 'dialog',
'aria-expanded': popover.isOpen && (openKey === key || ownsOpen),
'aria-controls': popover.id,
[TRIGGER_ATTRIBUTE]: key,
onClick: event => toggle(key, event.currentTarget),
};
},
switchTo,
};
}