@octanejs/aria 0.0.1 → 0.0.4

package/src/overlays/useCloseOnScroll.ts

@@ -0,0 +1,75 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/overlays/useCloseOnScroll.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; the explicit dependency array is kept verbatim.
+//
+// NOTE: ported ahead of the rest of the overlays area because useOverlayTrigger (needed by
+// useMenuTrigger) shares its `onCloseMap` backward-compatibility channel.
+import { getEventTarget, nodeContains } from '../utils/shadowdom/DOMFunctions';
+import type { RefObject } from '@react-types/shared';
+import { useEffect } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+// This behavior moved from useOverlayTrigger to useOverlayPosition.
+// For backward compatibility, where useOverlayTrigger handled hiding the popover on close,
+// it sets a close function here mapped from the trigger element. This way we can avoid
+// forcing users to pass an onClose function to useOverlayPosition which could be considered
+// a breaking change.
+export const onCloseMap: WeakMap<Element, () => void> = new WeakMap();
+
+interface CloseOnScrollOptions {
+	triggerRef: RefObject<Element | null>;
+	isOpen?: boolean;
+	onClose?: (() => void) | null;
+}
+
+/** @private */
+export function useCloseOnScroll(opts: CloseOnScrollOptions): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useCloseOnScroll(opts: CloseOnScrollOptions, slot: symbol | undefined): void;
+export function useCloseOnScroll(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useCloseOnScroll');
+	const opts = user[0] as CloseOnScrollOptions;
+
+	let { triggerRef, isOpen, onClose } = opts;
+
+	useEffect(
+		() => {
+			if (!isOpen || onClose === null) {
+				return;
+			}
+
+			let onScroll = (e: Event) => {
+				// Ignore if scrolling an scrollable region outside the trigger's tree.
+				let target = getEventTarget(e);
+				// window is not a Node and doesn't have contain, but window contains everything
+				if (
+					!triggerRef.current ||
+					(target instanceof Node && !nodeContains(target, triggerRef.current))
+				) {
+					return;
+				}
+
+				// Ignore scroll events on any input or textarea as the cursor position can cause it to scroll
+				// such as in a combobox. Clicking the dropdown button places focus on the input, and if the
+				// text inside the input extends beyond the 'end', then it will scroll so the cursor is visible at the end.
+				if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+					return;
+				}
+
+				let onCloseHandler = onClose || onCloseMap.get(triggerRef.current);
+				if (onCloseHandler) {
+					onCloseHandler();
+				}
+			};
+
+			window.addEventListener('scroll', onScroll, true);
+			return () => {
+				window.removeEventListener('scroll', onScroll, true);
+			};
+		},
+		[isOpen, onClose, triggerRef],
+		subSlot(slot, 'scroll'),
+	);
+}

package/src/overlays/useModal.ts

@@ -0,0 +1,224 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/overlays/useModal.tsx).
+// octane adaptations: `.tsx` → `.ts`, JSX → `createElement`; `ReactDOM.createPortal` →
+// octane's `createPortal(children, container)` (see aria memory octane-portal-as-value);
+// the plain-`.ts` components use the S()/subSlot component-slot convention with a stable
+// `{ value, children }` Provider descriptor shape; `useContext` is context-identity keyed so
+// it needs no slot threading; `useModal` is a public hook with slot threading and keeps its
+// explicit dependency array verbatim; React's ReactNode/JSX/AriaAttributes types → `any`
+// (a minimal structural DOMAttributes alias replaces upstream's synthetic-handler prop bag).
+import {
+	createContext,
+	createElement,
+	createPortal,
+	useContext,
+	useEffect,
+	useMemo,
+	useState,
+} from 'octane';
+import { useIsSSR } from '../ssr/SSRProvider';
+import { useUNSAFE_PortalContext } from './PortalProvider';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+// octane adaptation: minimal structural prop bag (upstream drags React's synthetic handler
+// and aria attribute types along).
+type DOMAttributes = Record<string, any>;
+
+export interface ModalProviderProps extends DOMAttributes {
+	children: any;
+}
+
+interface ModalContext {
+	parent: ModalContext | null;
+	modalCount: number;
+	addModal: () => void;
+	removeModal: () => void;
+}
+
+const Context = createContext<ModalContext | null>(null);
+
+/**
+ * Each ModalProvider tracks how many modals are open in its subtree. On mount, the modals trigger
+ * `addModal` to increment the count, and trigger `removeModal` on unmount to decrement it. This is
+ * done recursively so that all parent providers are incremented and decremented. If the modal count
+ * is greater than zero, we add `aria-hidden` to this provider to hide its subtree from screen
+ * readers. This is done using context in order to account for things like portals, which can
+ * cause the component tree and the DOM tree to differ significantly in structure.
+ */
+export function ModalProvider(props: ModalProviderProps): any {
+	const slot = S('ModalProvider');
+	let { children } = props;
+	let parent = useContext(Context);
+	let [modalCount, setModalCount] = useState(0, subSlot(slot, 'count'));
+	let context = useMemo(
+		() => ({
+			parent,
+			modalCount,
+			addModal() {
+				setModalCount((count) => count + 1);
+				if (parent) {
+					parent.addModal();
+				}
+			},
+			removeModal() {
+				setModalCount((count) => count - 1);
+				if (parent) {
+					parent.removeModal();
+				}
+			},
+		}),
+		[parent, modalCount],
+		subSlot(slot, 'context'),
+	);
+
+	return createElement(Context.Provider, { value: context, children });
+}
+
+export interface ModalProviderAria {
+	/** Props to be spread on the container element. */
+	modalProviderProps: DOMAttributes;
+}
+
+/**
+ * Used to determine if the tree should be aria-hidden based on how many
+ * modals are open.
+ */
+export function useModalProvider(): ModalProviderAria {
+	let context = useContext(Context);
+	return {
+		modalProviderProps: {
+			'aria-hidden': context && context.modalCount > 0 ? true : undefined,
+		},
+	};
+}
+
+/**
+ * Creates a root node that will be aria-hidden if there are other modals open.
+ */
+function OverlayContainerDOM(props: ModalProviderProps): any {
+	let { modalProviderProps } = useModalProvider();
+	return createElement('div', { 'data-overlay-container': true, ...props, ...modalProviderProps });
+}
+
+/**
+ * An OverlayProvider acts as a container for the top-level application.
+ * Any application that uses modal dialogs or other overlays should
+ * be wrapped in a `<OverlayProvider>`. This is used to ensure that
+ * the main content of the application is hidden from screen readers
+ * if a modal or other overlay is opened. Only the top-most modal or
+ * overlay should be accessible at once.
+ */
+export function OverlayProvider(props: ModalProviderProps): any {
+	return createElement(ModalProvider, {
+		children: createElement(OverlayContainerDOM, { ...props }),
+	});
+}
+
+export interface OverlayContainerProps extends ModalProviderProps {
+	/**
+	 * The container element in which the overlay portal will be placed.
+	 *
+	 * @deprecated - Use a parent UNSAFE_PortalProvider to set your portal container instead.
+	 * @default document.body
+	 */
+	portalContainer?: Element;
+}
+
+/**
+ * A container for overlays like modals and popovers. Renders the overlay
+ * into a Portal which is placed at the end of the document body.
+ * Also ensures that the overlay is hidden from screen readers if a
+ * nested modal is opened. Only the top-most modal or overlay should
+ * be accessible at once.
+ */
+export function OverlayContainer(props: OverlayContainerProps): any {
+	const slot = S('OverlayContainer');
+	let isSSR = useIsSSR(subSlot(slot, 'ssr'));
+	let { portalContainer = isSSR ? null : document.body, ...rest } = props;
+	let { getContainer } = useUNSAFE_PortalContext();
+	if (!props.portalContainer && getContainer) {
+		portalContainer = getContainer();
+	}
+
+	useEffect(
+		() => {
+			if (portalContainer?.closest('[data-overlay-container]')) {
+				throw new Error(
+					'An OverlayContainer must not be inside another container. Please change the portalContainer prop.',
+				);
+			}
+		},
+		[portalContainer],
+		subSlot(slot, 'nested'),
+	);
+
+	if (!portalContainer) {
+		return null;
+	}
+
+	let contents = createElement(OverlayProvider, { ...rest });
+	return createPortal(contents, portalContainer);
+}
+
+interface ModalAriaProps extends DOMAttributes {
+	/** Data attribute marks the dom node as a modal for the aria-modal-polyfill. */
+	'data-ismodal': boolean;
+}
+
+export interface AriaModalOptions {
+	isDisabled?: boolean;
+}
+
+export interface ModalAria {
+	/** Props for the modal content element. */
+	modalProps: ModalAriaProps;
+}
+
+/**
+ * Hides content outside the current `<OverlayContainer>` from screen readers
+ * on mount and restores it on unmount. Typically used by modal dialogs and
+ * other types of overlays to ensure that only the top-most modal is
+ * accessible at once.
+ */
+export function useModal(options?: AriaModalOptions): ModalAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useModal(
+	options: AriaModalOptions | undefined,
+	slot: symbol | undefined,
+): ModalAria;
+export function useModal(...args: any[]): ModalAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useModal');
+	const options = user[0] as AriaModalOptions | undefined;
+
+	// Add aria-hidden to all parent providers on mount, and restore on unmount.
+	let context = useContext(Context);
+	if (!context) {
+		throw new Error('Modal is not contained within a provider');
+	}
+
+	useEffect(
+		() => {
+			if (options?.isDisabled || !context || !context.parent) {
+				return;
+			}
+
+			// The immediate context is from the provider containing this modal, so we only
+			// want to trigger aria-hidden on its parents not on the modal provider itself.
+			context.parent.addModal();
+			return () => {
+				if (context && context.parent) {
+					context.parent.removeModal();
+				}
+			};
+		},
+		[context, context.parent, options?.isDisabled],
+		subSlot(slot, 'modal'),
+	);
+
+	return {
+		modalProps: {
+			'data-ismodal': !options?.isDisabled,
+		},
+	};
+}

package/src/overlays/useModalOverlay.ts

@@ -0,0 +1,103 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/overlays/useModalOverlay.ts).
+// octane adaptations: `DOMAttributes` is a local structural prop-bag alias; public-hook slot
+// threading (splitSlot/subSlot) per the binding convention — the composed ported hooks
+// (useOverlay/usePreventScroll/useOverlayFocusContain) each receive a derived sub-slot; the
+// explicit dependency array is kept verbatim; `OverlayTriggerState` from the ported stately
+// overlays state; element types → `any`.
+import { ariaHideOutside } from './ariaHideOutside';
+import { AriaOverlayProps, useOverlay } from './useOverlay';
+import type { RefObject } from '@react-types/shared';
+import { mergeProps } from '../utils/mergeProps';
+import type { OverlayTriggerState } from '../stately/overlays/useOverlayTriggerState';
+import { useEffect } from 'octane';
+import { useOverlayFocusContain } from './Overlay';
+import { usePreventScroll } from './usePreventScroll';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+// octane adaptation: minimal structural DOMAttributes (upstream's drags React's synthetic
+// handler types along).
+type DOMAttributes = Record<string, any>;
+
+export interface AriaModalOverlayProps extends Pick<
+	AriaOverlayProps,
+	'shouldCloseOnInteractOutside'
+> {
+	/**
+	 * Whether to close the modal when the user interacts outside it.
+	 *
+	 * @default false
+	 */
+	isDismissable?: boolean;
+	/**
+	 * Whether pressing the escape key to close the modal should be disabled.
+	 *
+	 * @default false
+	 */
+	isKeyboardDismissDisabled?: boolean;
+}
+
+export interface ModalOverlayAria {
+	/** Props for the modal element. */
+	modalProps: DOMAttributes;
+	/** Props for the underlay element. */
+	underlayProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a modal component.
+ * A modal is an overlay element which blocks interaction with elements outside it.
+ */
+export function useModalOverlay(
+	props: AriaModalOverlayProps,
+	state: OverlayTriggerState,
+	ref: RefObject<HTMLElement | null>,
+): ModalOverlayAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useModalOverlay(
+	props: AriaModalOverlayProps,
+	state: OverlayTriggerState,
+	ref: RefObject<HTMLElement | null>,
+	slot: symbol | undefined,
+): ModalOverlayAria;
+export function useModalOverlay(...args: any[]): ModalOverlayAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useModalOverlay');
+	const props = user[0] as AriaModalOverlayProps;
+	const state = user[1] as OverlayTriggerState;
+	const ref = user[2] as RefObject<HTMLElement | null>;
+
+	let { overlayProps, underlayProps } = useOverlay(
+		{
+			...props,
+			isOpen: state.isOpen,
+			onClose: state.close,
+		},
+		ref,
+		subSlot(slot, 'overlay'),
+	);
+
+	usePreventScroll(
+		{
+			isDisabled: !state.isOpen,
+		},
+		subSlot(slot, 'preventScroll'),
+	);
+
+	useOverlayFocusContain(subSlot(slot, 'focusContain'));
+
+	useEffect(
+		() => {
+			if (state.isOpen && ref.current) {
+				return ariaHideOutside([ref.current], { shouldUseInert: true });
+			}
+		},
+		[state.isOpen, ref],
+		subSlot(slot, 'hideOutside'),
+	);
+
+	return {
+		modalProps: mergeProps(overlayProps),
+		underlayProps,
+	};
+}

package/src/overlays/useOverlay.ts

@@ -0,0 +1,199 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/overlays/useOverlay.ts).
+// octane adaptations: `DOMAttributes` is a local structural prop-bag alias (upstream's is typed
+// over React's synthetic handlers); handlers receive NATIVE DOM events (no synthetic layer), so
+// `e.nativeEvent.isComposing` → `e.isComposing`; public-hook slot threading (splitSlot/subSlot)
+// per the binding convention; the explicit `[isOpen, ref]` dependency array is kept verbatim.
+import type { RefObject } from '@react-types/shared';
+import { getEventTarget } from '../utils/shadowdom/DOMFunctions';
+import { isElementInChildOfActiveScope } from '../focus/FocusScope';
+import { useEffect, useRef } from 'octane';
+import { useFocusWithin } from '../interactions/useFocusWithin';
+import { useInteractOutside } from '../interactions/useInteractOutside';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+// octane adaptation: minimal structural DOMAttributes (upstream's drags React's synthetic
+// handler types along).
+type DOMAttributes = Record<string, any>;
+
+export interface AriaOverlayProps {
+	/** Whether the overlay is currently open. */
+	isOpen?: boolean;
+
+	/** Handler that is called when the overlay should close. */
+	onClose?: () => void;
+
+	/**
+	 * Whether to close the overlay when the user interacts outside it.
+	 *
+	 * @default false
+	 */
+	isDismissable?: boolean;
+
+	/** Whether the overlay should close when focus is lost or moves outside it. */
+	shouldCloseOnBlur?: boolean;
+
+	/**
+	 * Whether pressing the escape key to close the overlay should be disabled.
+	 *
+	 * @default false
+	 */
+	isKeyboardDismissDisabled?: boolean;
+
+	/**
+	 * When user interacts with the argument element outside of the overlay ref,
+	 * return true if onClose should be called.  This gives you a chance to filter
+	 * out interaction with elements that should not dismiss the overlay.
+	 * By default, onClose will always be called on interaction outside the overlay ref.
+	 */
+	shouldCloseOnInteractOutside?: (element: Element) => boolean;
+}
+
+export interface OverlayAria {
+	/** Props to apply to the overlay container element. */
+	overlayProps: DOMAttributes;
+	/** Props to apply to the underlay element, if any. */
+	underlayProps: DOMAttributes;
+}
+
+const visibleOverlays: RefObject<Element | null>[] = [];
+
+/**
+ * Provides the behavior for overlays such as dialogs, popovers, and menus.
+ * Hides the overlay when the user interacts outside it, when the Escape key is pressed,
+ * or optionally, on blur. Only the top-most overlay will close at once.
+ */
+export function useOverlay(props: AriaOverlayProps, ref: RefObject<Element | null>): OverlayAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useOverlay(
+	props: AriaOverlayProps,
+	ref: RefObject<Element | null>,
+	slot: symbol | undefined,
+): OverlayAria;
+export function useOverlay(...args: any[]): OverlayAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useOverlay');
+	const props = user[0] as AriaOverlayProps;
+	const ref = user[1] as RefObject<Element | null>;
+
+	let {
+		onClose,
+		shouldCloseOnBlur,
+		isOpen,
+		isDismissable = false,
+		isKeyboardDismissDisabled = false,
+		shouldCloseOnInteractOutside,
+	} = props;
+
+	let lastVisibleOverlay = useRef<RefObject<Element | null> | undefined>(
+		undefined,
+		subSlot(slot, 'lastVisible'),
+	);
+
+	// Add the overlay ref to the stack of visible overlays on mount, and remove on unmount.
+	useEffect(
+		() => {
+			if (isOpen && !visibleOverlays.includes(ref)) {
+				visibleOverlays.push(ref);
+				return () => {
+					let index = visibleOverlays.indexOf(ref);
+					if (index >= 0) {
+						visibleOverlays.splice(index, 1);
+					}
+				};
+			}
+		},
+		[isOpen, ref],
+		subSlot(slot, 'stack'),
+	);
+
+	// Only hide the overlay when it is the topmost visible overlay in the stack
+	let onHide = () => {
+		if (visibleOverlays[visibleOverlays.length - 1] === ref && onClose) {
+			onClose();
+		}
+	};
+
+	let onInteractOutsideStart = (e: PointerEvent) => {
+		const topMostOverlay = visibleOverlays[visibleOverlays.length - 1];
+		lastVisibleOverlay.current = topMostOverlay;
+		if (
+			!shouldCloseOnInteractOutside ||
+			shouldCloseOnInteractOutside(getEventTarget(e) as Element)
+		) {
+			if (topMostOverlay === ref) {
+				e.stopPropagation();
+			}
+		}
+	};
+
+	let onInteractOutside = (e: PointerEvent) => {
+		if (
+			!shouldCloseOnInteractOutside ||
+			shouldCloseOnInteractOutside(getEventTarget(e) as Element)
+		) {
+			if (visibleOverlays[visibleOverlays.length - 1] === ref) {
+				e.stopPropagation();
+			}
+			if (lastVisibleOverlay.current === ref) {
+				onHide();
+			}
+		}
+		lastVisibleOverlay.current = undefined;
+	};
+
+	// Handle the escape key
+	let onKeyDown = (e: KeyboardEvent) => {
+		if (e.key === 'Escape' && !isKeyboardDismissDisabled && !e.isComposing) {
+			e.stopPropagation();
+			e.preventDefault();
+			onHide();
+		}
+	};
+
+	// Handle clicking outside the overlay to close it
+	useInteractOutside(
+		{
+			ref,
+			onInteractOutside: isDismissable && isOpen ? onInteractOutside : undefined,
+			onInteractOutsideStart,
+		},
+		subSlot(slot, 'interactOutside'),
+	);
+
+	let { focusWithinProps } = useFocusWithin(
+		{
+			isDisabled: !shouldCloseOnBlur,
+			onBlurWithin: (e) => {
+				// Do not close if relatedTarget is null, which means focus is lost to the body.
+				// That can happen when switching tabs, or due to a VoiceOver/Chrome bug with Control+Option+Arrow navigation.
+				// Clicking on the body to close the overlay should already be handled by useInteractOutside.
+				// https://github.com/adobe/react-spectrum/issues/4130
+				// https://github.com/adobe/react-spectrum/issues/4922
+				//
+				// If focus is moving into a child focus scope (e.g. menu inside a dialog),
+				// do not close the outer overlay. At this point, the active scope should
+				// still be the outer overlay, since blur events run before focus.
+				if (!e.relatedTarget || isElementInChildOfActiveScope(e.relatedTarget as Element)) {
+					return;
+				}
+
+				if (
+					!shouldCloseOnInteractOutside ||
+					shouldCloseOnInteractOutside(e.relatedTarget as Element)
+				) {
+					onClose?.();
+				}
+			},
+		},
+		subSlot(slot, 'focusWithin'),
+	);
+
+	return {
+		overlayProps: {
+			onKeyDown,
+			...focusWithinProps,
+		},
+		underlayProps: {},
+	};
+}