@octanejs/aria 0.0.1 → 0.0.3

package/src/overlays/Overlay.ts

@@ -0,0 +1,106 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/overlays/Overlay.tsx).
+// octane adaptations: `.tsx` → `.ts`, JSX → `createElement`; `ReactDOM.createPortal` →
+// octane's `createPortal(children, container)` (see aria memory octane-portal-as-value);
+// the plain-`.ts` `Overlay` component uses the S()/subSlot component-slot convention; the
+// Provider descriptor keeps a stable `{ value, children }` shape; React's ReactNode/JSX/Context
+// types → `any`; `useOverlayFocusContain` gets public-hook slot threading.
+import { ClearPressResponder } from '../interactions/PressResponder';
+import { FocusScope } from '../focus/FocusScope';
+import { createContext, createElement, createPortal, useContext, useMemo, useState } from 'octane';
+import { useIsSSR } from '../ssr/SSRProvider';
+import { useLayoutEffect } from '../utils/useLayoutEffect';
+import { useUNSAFE_PortalContext } from './PortalProvider';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export interface OverlayProps {
+	/**
+	 * The container element in which the overlay portal will be placed.
+	 *
+	 * @default document.body
+	 */
+	portalContainer?: Element;
+	/** The overlay to render in the portal. */
+	children: any;
+	/**
+	 * Disables default focus management for the overlay, including containment and restoration.
+	 * This option should be used very carefully. When focus management is disabled, you must
+	 * implement focus containment and restoration to ensure the overlay is keyboard accessible.
+	 */
+	disableFocusManagement?: boolean;
+	/**
+	 * Whether to contain focus within the overlay.
+	 */
+	shouldContainFocus?: boolean;
+	/**
+	 * Whether the overlay is currently performing an exit animation. When true,
+	 * focus is allowed to move outside.
+	 */
+	isExiting?: boolean;
+}
+
+interface OverlayContextValue {
+	contain: boolean;
+	setContain: (value: boolean | ((prev: boolean) => boolean)) => void;
+}
+
+export const OverlayContext = createContext<OverlayContextValue | null>(null);
+
+/**
+ * A container which renders an overlay such as a popover or modal in a portal,
+ * and provides a focus scope for the child elements.
+ */
+export function Overlay(props: OverlayProps): any {
+	const slot = S('Overlay');
+	let isSSR = useIsSSR(subSlot(slot, 'ssr'));
+	let { portalContainer = isSSR ? null : document.body, isExiting } = props;
+	let [contain, setContain] = useState(false, subSlot(slot, 'contain'));
+	let contextValue = useMemo(
+		() => ({ contain, setContain }),
+		[contain, setContain],
+		subSlot(slot, 'context'),
+	);
+
+	let { getContainer } = useUNSAFE_PortalContext();
+	if (!props.portalContainer && getContainer) {
+		portalContainer = getContainer();
+	}
+
+	if (!portalContainer) {
+		return null;
+	}
+
+	let contents = props.children;
+	if (!props.disableFocusManagement) {
+		contents = createElement(FocusScope, {
+			restoreFocus: true,
+			contain: (props.shouldContainFocus || contain) && !isExiting,
+			children: contents,
+		});
+	}
+
+	contents = createElement(OverlayContext.Provider, {
+		value: contextValue as OverlayContextValue,
+		children: createElement(ClearPressResponder, { children: contents }),
+	});
+
+	return createPortal(contents, portalContainer);
+}
+
+/** @private */
+export function useOverlayFocusContain(): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useOverlayFocusContain(slot: symbol | undefined): void;
+export function useOverlayFocusContain(...args: any[]): void {
+	const [, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useOverlayFocusContain');
+	let ctx = useContext(OverlayContext);
+	let setContain = ctx?.setContain;
+	useLayoutEffect(
+		() => {
+			setContain?.(true);
+		},
+		[setContain],
+		subSlot(slot, 'contain'),
+	);
+}

package/src/overlays/PortalProvider.ts

@@ -0,0 +1,37 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/overlays/PortalProvider.tsx).
+// octane adaptations: `.tsx` → `.ts`, JSX → `createElement` with a stable `{ value, children }`
+// Provider descriptor shape; React's `ReactNode`/`JSX.Element`/`React.Context` types → `any`;
+// `useContext` is context-identity keyed, so it needs no slot threading.
+import { createContext, createElement, useContext } from 'octane';
+
+export interface PortalProviderProps {
+	/** Should return the element where we should portal to. Can clear the context by passing null. */
+	getContainer?: (() => HTMLElement | null) | null;
+	/**
+	 * The content of the PortalProvider. Should contain all children that want to portal their
+	 * overlays to the element returned by the provided `getContainer()`.
+	 */
+	children: any;
+}
+
+export interface PortalProviderContextValue extends Omit<PortalProviderProps, 'children'> {}
+
+export const PortalContext = createContext<PortalProviderContextValue>({});
+
+/**
+ * Sets the portal container for all overlay elements rendered by its children.
+ */
+export function UNSAFE_PortalProvider(props: PortalProviderProps): any {
+	let { getContainer } = props;
+	let { getContainer: ctxGetContainer } = useUNSAFE_PortalContext();
+	return createElement(PortalContext.Provider, {
+		value: {
+			getContainer: getContainer === null ? undefined : (getContainer ?? ctxGetContainer),
+		},
+		children: props.children,
+	});
+}
+
+export function useUNSAFE_PortalContext(): PortalProviderContextValue {
+	return useContext(PortalContext) ?? {};
+}

package/src/overlays/ariaHideOutside.ts

@@ -0,0 +1,299 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/overlays/ariaHideOutside.ts).
+// octane adaptations: `shadowDOM` flag imported from the ported `../stately/flags` (upstream
+// reads it from `react-stately/private/flags/flags`). No hooks here — a plain DOM utility, so
+// no slot threading. Module-level ref-count map and observer stack are ported verbatim.
+import { createShadowTreeWalker } from '../utils/shadowdom/ShadowTreeWalker';
+
+import { getOwnerDocument, getOwnerWindow } from '../utils/domHelpers';
+import { nodeContains } from '../utils/shadowdom/DOMFunctions';
+import { shadowDOM } from '../stately/flags';
+
+const supportsInert = typeof HTMLElement !== 'undefined' && 'inert' in HTMLElement.prototype;
+
+function isAlwaysVisibleNode(node: HTMLElement | SVGElement): boolean {
+	return node.dataset.liveAnnouncer === 'true' || node.dataset.reactAriaTopLayer !== undefined;
+}
+
+interface AriaHideOutsideOptions {
+	root?: Element;
+	shouldUseInert?: boolean;
+}
+
+// Keeps a ref count of all hidden elements. Added to when hiding an element, and
+// subtracted from when showing it again. When it reaches zero, aria-hidden is removed.
+let refCountMap = new WeakMap<Element, number>();
+interface ObserverWrapper {
+	visibleNodes: Set<Element>;
+	hiddenNodes: Set<Element>;
+	observe: () => void;
+	disconnect: () => void;
+}
+let observerStack: Array<ObserverWrapper> = [];
+
+/**
+ * Hides all elements in the DOM outside the given targets from screen readers using aria-hidden,
+ * and returns a function to revert these changes. In addition, changes to the DOM are watched
+ * and new elements outside the targets are automatically hidden.
+ *
+ * @param targets - The elements that should remain visible.
+ * @param root - Nothing will be hidden above this element.
+ * @returns - A function to restore all hidden elements.
+ */
+export function ariaHideOutside(targets: Element[], options?: AriaHideOutsideOptions | Element) {
+	let windowObj = getOwnerWindow(targets?.[0]);
+	let opts = options instanceof windowObj.Element ? { root: options } : options;
+	let root = opts?.root ?? document.body;
+	let shouldUseInert = opts?.shouldUseInert && supportsInert;
+	let visibleNodes = new Set<Element>(targets);
+	let hiddenNodes = new Set<Element>();
+
+	let getHidden = (element: Element) => {
+		return shouldUseInert && element instanceof windowObj.HTMLElement
+			? element.inert
+			: element.getAttribute('aria-hidden') === 'true';
+	};
+
+	let setHidden = (element: Element, hidden: boolean) => {
+		if (shouldUseInert && element instanceof windowObj.HTMLElement) {
+			element.inert = hidden;
+		} else if (hidden) {
+			element.setAttribute('aria-hidden', 'true');
+		} else {
+			element.removeAttribute('aria-hidden');
+			if (element instanceof windowObj.HTMLElement) {
+				// We only ever call setHidden with hidden = false when the nodeCount is 1 aka
+				// we are trying to make the element visible to screen readers again, so remove inert as well
+				element.inert = false;
+			}
+		}
+	};
+
+	let shadowRootsToWatch = new Set<ShadowRoot>();
+	if (shadowDOM()) {
+		// find all shadow roots that are ancestors of the targets
+		// traverse upwards until the root is reached
+		for (let target of targets) {
+			let node = target;
+			while (node && node !== root) {
+				let root = node.getRootNode();
+				if ('shadowRoot' in root) {
+					shadowRootsToWatch.add(root.shadowRoot as ShadowRoot);
+				}
+				node = root.parentNode as Element;
+			}
+		}
+	}
+
+	let walk = (root: Element) => {
+		// Keep live announcer and top layer elements (e.g. toasts) visible.
+		for (let element of root.querySelectorAll(
+			'[data-live-announcer], [data-react-aria-top-layer]',
+		)) {
+			visibleNodes.add(element);
+		}
+
+		let acceptNode = (node: Element) => {
+			// Skip this node and its children if it is one of the target nodes, or a live announcer.
+			// Also skip children of already hidden nodes, as aria-hidden is recursive. An exception is
+			// made for elements with role="row" since VoiceOver on iOS has issues hiding elements with role="row".
+			// For that case we want to hide the cells inside as well (https://bugs.webkit.org/show_bug.cgi?id=222623).
+			if (
+				hiddenNodes.has(node) ||
+				visibleNodes.has(node) ||
+				(node.parentElement &&
+					hiddenNodes.has(node.parentElement) &&
+					node.parentElement.getAttribute('role') !== 'row')
+			) {
+				return NodeFilter.FILTER_REJECT;
+			}
+
+			// Skip this node but continue to children if one of the targets is inside the node.
+			for (let target of visibleNodes) {
+				if (nodeContains(node, target)) {
+					return NodeFilter.FILTER_SKIP;
+				}
+			}
+
+			return NodeFilter.FILTER_ACCEPT;
+		};
+
+		let walker = createShadowTreeWalker(getOwnerDocument(root), root, NodeFilter.SHOW_ELEMENT, {
+			acceptNode,
+		});
+
+		// TreeWalker does not include the root.
+		let acceptRoot = acceptNode(root);
+		if (acceptRoot === NodeFilter.FILTER_ACCEPT) {
+			hide(root);
+		}
+
+		if (acceptRoot !== NodeFilter.FILTER_REJECT) {
+			let node = walker.nextNode() as Element;
+			while (node != null) {
+				hide(node);
+				node = walker.nextNode() as Element;
+			}
+		}
+	};
+
+	let hide = (node: Element) => {
+		let refCount = refCountMap.get(node) ?? 0;
+
+		// If already aria-hidden, and the ref count is zero, then this element
+		// was already hidden and there's nothing for us to do.
+		if (getHidden(node) && refCount === 0) {
+			return;
+		}
+
+		if (refCount === 0) {
+			setHidden(node, true);
+		}
+
+		hiddenNodes.add(node);
+		refCountMap.set(node, refCount + 1);
+	};
+
+	// If there is already a MutationObserver listening from a previous call,
+	// disconnect it so the new on takes over.
+	if (observerStack.length) {
+		observerStack[observerStack.length - 1].disconnect();
+	}
+
+	walk(root);
+
+	let observer = new MutationObserver((changes) => {
+		for (let change of changes) {
+			if (change.type !== 'childList') {
+				continue;
+			}
+
+			// If the parent element of the added nodes is not within one of the targets,
+			// and not already inside a hidden node, hide all of the new children.
+			if (
+				change.target.isConnected &&
+				![...visibleNodes, ...hiddenNodes].some((node) => nodeContains(node, change.target))
+			) {
+				for (let node of change.addedNodes) {
+					if (
+						(node instanceof HTMLElement || node instanceof SVGElement) &&
+						isAlwaysVisibleNode(node)
+					) {
+						visibleNodes.add(node);
+					} else if (node instanceof Element) {
+						walk(node);
+					}
+				}
+			}
+
+			if (shadowDOM()) {
+				// if any of the observed shadow roots were removed, stop observing them
+				for (let shadowRoot of shadowRootsToWatch) {
+					if (!shadowRoot.isConnected) {
+						observer.disconnect();
+						break;
+					}
+				}
+			}
+		}
+	});
+
+	observer.observe(root, { childList: true, subtree: true });
+	let shadowObservers = new Set<MutationObserver>();
+	if (shadowDOM()) {
+		for (let shadowRoot of shadowRootsToWatch) {
+			// Disconnect single target instead of all https://github.com/whatwg/dom/issues/126
+			let shadowObserver = new MutationObserver((changes) => {
+				for (let change of changes) {
+					if (change.type !== 'childList') {
+						continue;
+					}
+
+					// If the parent element of the added nodes is not within one of the targets,
+					// and not already inside a hidden node, hide all of the new children.
+					if (
+						change.target.isConnected &&
+						![...visibleNodes, ...hiddenNodes].some((node) => nodeContains(node, change.target))
+					) {
+						for (let node of change.addedNodes) {
+							if (
+								(node instanceof HTMLElement || node instanceof SVGElement) &&
+								isAlwaysVisibleNode(node)
+							) {
+								visibleNodes.add(node);
+							} else if (node instanceof Element) {
+								walk(node);
+							}
+						}
+					}
+
+					if (shadowDOM()) {
+						// if any of the observed shadow roots were removed, stop observing them
+						for (let shadowRoot of shadowRootsToWatch) {
+							if (!shadowRoot.isConnected) {
+								observer.disconnect();
+								break;
+							}
+						}
+					}
+				}
+			});
+			shadowObserver.observe(shadowRoot, { childList: true, subtree: true });
+			shadowObservers.add(shadowObserver);
+		}
+	}
+
+	let observerWrapper: ObserverWrapper = {
+		visibleNodes,
+		hiddenNodes,
+		observe() {
+			observer.observe(root, { childList: true, subtree: true });
+		},
+		disconnect() {
+			observer.disconnect();
+		},
+	};
+
+	observerStack.push(observerWrapper);
+
+	return (): void => {
+		observer.disconnect();
+		if (shadowDOM()) {
+			for (let shadowObserver of shadowObservers) {
+				shadowObserver.disconnect();
+			}
+		}
+
+		for (let node of hiddenNodes) {
+			let count = refCountMap.get(node);
+			if (count == null) {
+				continue;
+			}
+			if (count === 1) {
+				setHidden(node, false);
+				refCountMap.delete(node);
+			} else {
+				refCountMap.set(node, count - 1);
+			}
+		}
+
+		// Remove this observer from the stack, and start the previous one.
+		if (observerWrapper === observerStack[observerStack.length - 1]) {
+			observerStack.pop();
+			if (observerStack.length) {
+				observerStack[observerStack.length - 1].observe();
+			}
+		} else {
+			observerStack.splice(observerStack.indexOf(observerWrapper), 1);
+		}
+	};
+}
+
+export function keepVisible(element: Element): (() => void) | undefined {
+	let observer = observerStack[observerStack.length - 1];
+	if (observer && !observer.visibleNodes.has(element)) {
+		observer.visibleNodes.add(element);
+		return () => {
+			observer.visibleNodes.delete(element);
+		};
+	}
+}