@octanejs/aria 0.0.1 → 0.0.4

package/src/overlays/usePopover.ts

@@ -0,0 +1,170 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/overlays/usePopover.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/useOverlayPosition/usePreventScroll) 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, keepVisible } from './ariaHideOutside';
+import { AriaPositionProps, PlacementAxis, useOverlayPosition } from './useOverlayPosition';
+import type { RefObject } from '@react-types/shared';
+import { mergeProps } from '../utils/mergeProps';
+import type { OverlayTriggerState } from '../stately/overlays/useOverlayTriggerState';
+import { useEffect } from 'octane';
+import { useOverlay } from './useOverlay';
+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 AriaPopoverProps extends Omit<
+	AriaPositionProps,
+	'isOpen' | 'onClose' | 'targetRef' | 'overlayRef'
+> {
+	/**
+	 * The ref for the element which the popover positions itself with respect to.
+	 */
+	triggerRef: RefObject<Element | null>;
+	/**
+	 * The ref for the popover element.
+	 */
+	popoverRef: RefObject<Element | null>;
+	/** A ref for the popover arrow element. */
+	arrowRef?: RefObject<Element | null>;
+	/**
+	 * An optional ref for a group of popovers, e.g. submenus.
+	 * When provided, this element is used to detect outside interactions
+	 * and hiding elements from assistive technologies instead of the popoverRef.
+	 */
+	groupRef?: RefObject<Element | null>;
+	/**
+	 * Whether the popover is non-modal, i.e. elements outside the popover may be
+	 * interacted with by assistive technologies.
+	 *
+	 * Most popovers should not use this option as it may negatively impact the screen
+	 * reader experience. Only use with components such as combobox, which are designed
+	 * to handle this situation carefully.
+	 */
+	isNonModal?: boolean;
+	/**
+	 * Whether pressing the escape key to close the popover should be disabled.
+	 *
+	 * Most popovers should not use this option. When set to true, an alternative
+	 * way to close the popover with a keyboard must be provided.
+	 *
+	 * @default false
+	 */
+	isKeyboardDismissDisabled?: boolean;
+	/**
+	 * When user interacts with the argument element outside of the popover ref,
+	 * return true if onClose should be called. This gives you a chance to filter
+	 * out interaction with elements that should not dismiss the popover.
+	 * By default, onClose will always be called on interaction outside the popover ref.
+	 */
+	shouldCloseOnInteractOutside?: (element: Element) => boolean;
+}
+
+export interface PopoverAria {
+	/** Props for the popover element. */
+	popoverProps: DOMAttributes;
+	/** Props for the popover tip arrow if any. */
+	arrowProps: DOMAttributes;
+	/** Props to apply to the underlay element, if any. */
+	underlayProps: DOMAttributes;
+	/** Placement of the popover with respect to the trigger. */
+	placement: PlacementAxis | null;
+	/** The origin of the target in the overlay's coordinate system. Useful for animations. */
+	triggerAnchorPoint: { x: number; y: number } | null;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a popover component.
+ * A popover is an overlay element positioned relative to a trigger.
+ */
+export function usePopover(props: AriaPopoverProps, state: OverlayTriggerState): PopoverAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function usePopover(
+	props: AriaPopoverProps,
+	state: OverlayTriggerState,
+	slot: symbol | undefined,
+): PopoverAria;
+export function usePopover(...args: any[]): PopoverAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('usePopover');
+	const props = user[0] as AriaPopoverProps;
+	const state = user[1] as OverlayTriggerState;
+
+	let {
+		triggerRef,
+		popoverRef,
+		groupRef,
+		isNonModal,
+		isKeyboardDismissDisabled,
+		shouldCloseOnInteractOutside,
+		...otherProps
+	} = props;
+
+	let isSubmenu = (otherProps as any)['trigger'] === 'SubmenuTrigger';
+
+	let { overlayProps, underlayProps } = useOverlay(
+		{
+			isOpen: state.isOpen,
+			onClose: state.close,
+			shouldCloseOnBlur: true,
+			isDismissable: !isNonModal || isSubmenu,
+			isKeyboardDismissDisabled,
+			shouldCloseOnInteractOutside,
+		},
+		groupRef ?? popoverRef,
+		subSlot(slot, 'overlay'),
+	);
+
+	let {
+		overlayProps: positionProps,
+		arrowProps,
+		placement,
+		triggerAnchorPoint: origin,
+	} = useOverlayPosition(
+		{
+			...otherProps,
+			targetRef: triggerRef,
+			overlayRef: popoverRef,
+			isOpen: state.isOpen,
+			onClose: isNonModal && !isSubmenu ? state.close : null,
+		},
+		subSlot(slot, 'position'),
+	);
+
+	usePreventScroll(
+		{
+			isDisabled: isNonModal || !state.isOpen,
+		},
+		subSlot(slot, 'preventScroll'),
+	);
+
+	useEffect(
+		() => {
+			if (state.isOpen && popoverRef.current) {
+				if (isNonModal) {
+					return keepVisible(groupRef?.current ?? popoverRef.current);
+				} else {
+					return ariaHideOutside([groupRef?.current ?? popoverRef.current], {
+						shouldUseInert: true,
+					});
+				}
+			}
+		},
+		[isNonModal, state.isOpen, popoverRef, groupRef],
+		subSlot(slot, 'hideOutside'),
+	);
+
+	return {
+		popoverProps: mergeProps(overlayProps, positionProps),
+		arrowProps,
+		underlayProps,
+		placement,
+		triggerAnchorPoint: origin,
+	};
+}

package/src/overlays/usePreventScroll.ts

@@ -0,0 +1,316 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/overlays/usePreventScroll.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; the explicit `[isDisabled]` dependency array is kept verbatim; `setStyle`'s
+// string-indexed style access stays `any` (untyped in upstream too). The module-level
+// counter/restore state and the mobile-Safari branch are ported verbatim.
+import { chain } from '../utils/chain';
+
+import { getActiveElement, getEventTarget } from '../utils/shadowdom/DOMFunctions';
+import { getNonce } from '../utils/getNonce';
+import { getScrollParent } from '../utils/getScrollParent';
+import { isIOS } from '../utils/platform';
+import { isScrollable } from '../utils/isScrollable';
+import { useLayoutEffect } from '../utils/useLayoutEffect';
+import { willOpenKeyboard } from '../utils/keyboard';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+interface PreventScrollOptions {
+	/** Whether the scroll lock is disabled. */
+	isDisabled?: boolean;
+}
+
+const visualViewport = typeof document !== 'undefined' && window.visualViewport;
+
+// The number of active usePreventScroll calls. Used to determine whether to revert back to the original page style/scroll position
+let preventScrollCount = 0;
+let restore: () => void;
+
+/**
+ * Prevents scrolling on the document body on mount, and
+ * restores it on unmount. Also ensures that content does not
+ * shift due to the scrollbars disappearing.
+ */
+export function usePreventScroll(options?: PreventScrollOptions): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function usePreventScroll(
+	options: PreventScrollOptions | undefined,
+	slot: symbol | undefined,
+): void;
+export function usePreventScroll(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('usePreventScroll');
+	const options = (user[0] as PreventScrollOptions | undefined) ?? {};
+
+	let { isDisabled } = options;
+
+	useLayoutEffect(
+		() => {
+			if (isDisabled) {
+				return;
+			}
+
+			preventScrollCount++;
+			if (preventScrollCount === 1) {
+				if (isIOS()) {
+					restore = preventScrollMobileSafari();
+				} else {
+					restore = preventScrollStandard();
+				}
+			}
+
+			return () => {
+				preventScrollCount--;
+				if (preventScrollCount === 0) {
+					restore();
+				}
+			};
+		},
+		[isDisabled],
+		subSlot(slot, 'preventScroll'),
+	);
+}
+
+// For most browsers, all we need to do is set `overflow: hidden` on the root element, and
+// add some padding to prevent the page from shifting when the scrollbar is hidden.
+function preventScrollStandard() {
+	let scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+	return chain(
+		scrollbarWidth > 0 &&
+			// Use scrollbar-gutter when supported because it also works for fixed positioned elements.
+			('scrollbarGutter' in document.documentElement.style
+				? setStyle(document.documentElement, 'scrollbarGutter', 'stable')
+				: setStyle(document.documentElement, 'paddingRight', `${scrollbarWidth}px`)),
+		setStyle(document.documentElement, 'overflow', 'hidden'),
+	);
+}
+
+// Mobile Safari is a whole different beast. Even with overflow: hidden,
+// it still scrolls the page in many situations:
+//
+// 1. When the bottom toolbar and address bar are collapsed, page scrolling is always allowed.
+// 2. When the keyboard is visible, the viewport does not resize. Instead, the keyboard covers part of
+//    it, so it becomes scrollable.
+// 3. When tapping on an input, the page always scrolls so that the input is centered in the visual viewport.
+//    This may cause even fixed position elements to scroll off the screen.
+// 4. When using the next/previous buttons in the keyboard to navigate between inputs, the whole page always
+//    scrolls, even if the input is inside a nested scrollable element that could be scrolled instead.
+//
+// In order to work around these cases, and prevent scrolling without jankiness, we do a few things:
+//
+// 1. Prevent default on `touchmove` events that are not in a scrollable element. This prevents touch scrolling
+//    on the window.
+// 2. Set `overscroll-behavior: contain` on nested scrollable regions so they do not scroll the page when at
+//    the top or bottom. Work around a bug where this does not work when the element does not actually overflow
+//    by preventing default in a `touchmove` event. This is best effort: we can't prevent default when pinch
+//    zooming or when an element contains text selection, which may allow scrolling in some cases.
+// 3. Prevent default on `touchend` events on input elements and handle focusing the element ourselves.
+// 4. When focus moves to an input, create an off screen input and focus that temporarily. This prevents
+//    Safari from scrolling the page. After a small delay, focus the real input and scroll it into view
+//    ourselves, without scrolling the whole page.
+function preventScrollMobileSafari() {
+	// Set overflow hidden so scrollIntoViewport() (useSelectableCollection) sees isScrollPrevented and
+	// scrolls only scroll parents instead of calling native scrollIntoView() which moves the window.
+	let restoreOverflow = setStyle(document.documentElement, 'overflow', 'hidden');
+
+	let scrollable: Element;
+	let allowTouchMove = false;
+	let onTouchStart = (e: TouchEvent) => {
+		// Store the nearest scrollable parent element from the element that the user touched.
+		let target = getEventTarget(e) as Element;
+		scrollable = isScrollable(target) ? target : getScrollParent(target, true);
+		allowTouchMove = false;
+
+		// If the target is selected, don't preventDefault in touchmove to allow user to adjust selection.
+		let selection = target.ownerDocument.defaultView!.getSelection();
+		if (selection && !selection.isCollapsed && selection.containsNode(target, true)) {
+			allowTouchMove = true;
+		}
+
+		// If this is a range input, allow touch move to allow user to adjust the slider value
+		if (e.composedPath().some((el) => el instanceof HTMLInputElement && el.type === 'range')) {
+			allowTouchMove = true;
+		}
+
+		// If this is a focused input element with a selected range, allow user to drag the selection handles.
+		if (
+			'selectionStart' in target &&
+			'selectionEnd' in target &&
+			((target as any).selectionStart as number) < ((target as any).selectionEnd as number) &&
+			target.ownerDocument.activeElement === target
+		) {
+			allowTouchMove = true;
+		}
+	};
+
+	// Prevent scrolling up when at the top and scrolling down when at the bottom
+	// of a nested scrollable area, otherwise mobile Safari will start scrolling
+	// the window instead.
+	// This must be applied before the touchstart event as of iOS 26, so inject it as a <style> element.
+	let style = document.createElement('style');
+	let nonce = getNonce();
+	if (nonce) {
+		style.nonce = nonce;
+	}
+	style.textContent = `
+@layer {
+  * {
+    overscroll-behavior: contain;
+  }
+}`.trim();
+	document.head.prepend(style);
+
+	let onTouchMove = (e: TouchEvent) => {
+		// Allow pinch-zooming.
+		if (e.touches.length === 2 || allowTouchMove) {
+			return;
+		}
+
+		// Prevent scrolling the window.
+		if (!scrollable || scrollable === document.documentElement || scrollable === document.body) {
+			e.preventDefault();
+			return;
+		}
+
+		// overscroll-behavior should prevent scroll chaining, but currently does not
+		// if the element doesn't actually overflow. https://bugs.webkit.org/show_bug.cgi?id=243452
+		// This checks that both the width and height do not overflow, otherwise we might
+		// block horizontal scrolling too. In that case, adding `touch-action: pan-x` to
+		// the element will prevent vertical page scrolling. We can't add that automatically
+		// because it must be set before the touchstart event.
+		if (
+			scrollable.scrollHeight === scrollable.clientHeight &&
+			scrollable.scrollWidth === scrollable.clientWidth
+		) {
+			e.preventDefault();
+		}
+	};
+
+	let onBlur = (e: FocusEvent) => {
+		let target = getEventTarget(e) as HTMLElement;
+		let relatedTarget = e.relatedTarget as HTMLElement | null;
+		if (relatedTarget && willOpenKeyboard(relatedTarget)) {
+			// Focus without scrolling the whole page, and then scroll into view manually.
+			relatedTarget.focus({ preventScroll: true });
+			scrollIntoViewWhenReady(relatedTarget, willOpenKeyboard(target));
+		} else if (!relatedTarget) {
+			// When tapping the Done button on the keyboard, focus moves to the body.
+			// FocusScope will then restore focus back to the input. Later when tapping
+			// the same input again, it is already focused, so no blur event will fire,
+			// resulting in the flow above never running and Safari's native scrolling occurring.
+			// Instead, move focus to the parent focusable element (e.g. the dialog).
+			let focusable = target.parentElement?.closest('[tabindex]') as HTMLElement | null;
+			focusable?.focus({ preventScroll: true });
+		}
+	};
+
+	// Override programmatic focus to scroll into view without scrolling the whole page.
+	let focus = HTMLElement.prototype.focus;
+	HTMLElement.prototype.focus = function (opts) {
+		// Track whether the keyboard was already visible before.
+		let activeElement = getActiveElement();
+		let wasKeyboardVisible = activeElement != null && willOpenKeyboard(activeElement);
+
+		// Focus the element without scrolling the page.
+		focus.call(this, { ...opts, preventScroll: true });
+
+		if (!opts || !opts.preventScroll) {
+			scrollIntoViewWhenReady(this, wasKeyboardVisible);
+		}
+	};
+
+	let removeEvents = chain(
+		addEvent(document, 'touchstart', onTouchStart, { passive: false, capture: true }),
+		addEvent(document, 'touchmove', onTouchMove, { passive: false, capture: true }),
+		addEvent(document, 'blur', onBlur, true),
+	);
+
+	return () => {
+		restoreOverflow();
+		removeEvents();
+		style.remove();
+		HTMLElement.prototype.focus = focus;
+	};
+}
+
+// Sets a CSS property on an element, and returns a function to revert it to the previous value.
+function setStyle(element: HTMLElement, style: string, value: string) {
+	let cur = (element.style as any)[style];
+	(element.style as any)[style] = value;
+
+	return () => {
+		(element.style as any)[style] = cur;
+	};
+}
+
+// Adds an event listener to an element, and returns a function to remove it.
+function addEvent<K extends keyof GlobalEventHandlersEventMap>(
+	target: Document | Window,
+	event: K,
+	handler: (this: Document | Window, ev: GlobalEventHandlersEventMap[K]) => any,
+	options?: boolean | AddEventListenerOptions,
+) {
+	// internal function, so it's ok to ignore the difficult to fix type error
+	// @ts-ignore
+	target.addEventListener(event, handler, options);
+	return () => {
+		// @ts-ignore
+		target.removeEventListener(event, handler, options);
+	};
+}
+
+function scrollIntoViewWhenReady(target: Element, wasKeyboardVisible: boolean) {
+	if (wasKeyboardVisible || !visualViewport) {
+		// If the keyboard was already visible, scroll the target into view immediately.
+		scrollIntoView(target);
+	} else {
+		// Otherwise, wait for the visual viewport to resize before scrolling so we can
+		// measure the correct position to scroll to.
+		visualViewport.addEventListener('resize', () => scrollIntoView(target), { once: true });
+	}
+}
+
+function scrollIntoView(target: Element) {
+	let root = document.scrollingElement || document.documentElement;
+	let nextTarget: Element | null = target;
+	while (nextTarget && nextTarget !== root) {
+		// Find the parent scrollable element and adjust the scroll position if the target is not already in view.
+		let scrollable = getScrollParent(nextTarget);
+		if (
+			scrollable !== document.documentElement &&
+			scrollable !== document.body &&
+			scrollable !== nextTarget
+		) {
+			let scrollableRect = scrollable.getBoundingClientRect();
+			let targetRect = nextTarget.getBoundingClientRect();
+			if (
+				targetRect.top < scrollableRect.top ||
+				targetRect.bottom > scrollableRect.top + nextTarget.clientHeight
+			) {
+				let bottom = scrollableRect.bottom;
+				if (visualViewport) {
+					bottom = Math.min(bottom, visualViewport.offsetTop + visualViewport.height);
+				}
+
+				// Center within the viewport.
+				let adjustment =
+					targetRect.top -
+					scrollableRect.top -
+					((bottom - scrollableRect.top) / 2 - targetRect.height / 2);
+				scrollable.scrollTo({
+					// Clamp to the valid range to prevent over-scrolling.
+					top: Math.max(
+						0,
+						Math.min(
+							scrollable.scrollHeight - scrollable.clientHeight,
+							scrollable.scrollTop + adjustment,
+						),
+					),
+					behavior: 'smooth',
+				});
+			}
+		}
+
+		nextTarget = scrollable.parentElement;
+	}
+}

package/src/progress/useProgressBar.ts

@@ -0,0 +1,115 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/progress/useProgressBar.ts).
+// octane adaptations: ReactNode → any (octane renderables); public-hook slot threading.
+import type { AriaLabelingProps, DOMAttributes, DOMProps } from '@react-types/shared';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { clamp } from '../stately/utils/number';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { mergeProps } from '../utils/mergeProps';
+import { useLabel } from '../label/useLabel';
+import { useNumberFormatter } from '../i18n/useNumberFormatter';
+
+export interface ProgressBarBaseProps {
+	/**
+	 * The current value (controlled).
+	 *
+	 * @default 0
+	 */
+	value?: number;
+	/**
+	 * The smallest value allowed for the input.
+	 *
+	 * @default 0
+	 */
+	minValue?: number;
+	/**
+	 * The largest value allowed for the input.
+	 *
+	 * @default 100
+	 */
+	maxValue?: number;
+	/** The content to display as the label. */
+	label?: any;
+	/**
+	 * The display format of the value label.
+	 *
+	 * @default { style: 'percent' }
+	 */
+	formatOptions?: Intl.NumberFormatOptions;
+	/** The content to display as the value's label (e.g. 1 of 4). */
+	valueLabel?: any;
+}
+
+export interface AriaProgressBarBaseProps
+	extends ProgressBarBaseProps, DOMProps, AriaLabelingProps {}
+
+export interface ProgressBarProps extends ProgressBarBaseProps {
+	/**
+	 * Whether presentation is indeterminate when progress isn't known.
+	 */
+	isIndeterminate?: boolean;
+}
+
+export interface AriaProgressBarProps extends ProgressBarProps, DOMProps, AriaLabelingProps {}
+
+export interface ProgressBarAria {
+	/** Props for the progress bar container element. */
+	progressBarProps: DOMAttributes;
+	/** Props for the progress bar's visual label element (if any). */
+	labelProps: DOMAttributes;
+}
+
+export function useProgressBar(props: AriaProgressBarProps): ProgressBarAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useProgressBar(
+	props: AriaProgressBarProps,
+	slot: symbol | undefined,
+): ProgressBarAria;
+export function useProgressBar(...args: any[]): ProgressBarAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useProgressBar');
+	const props = user[0] as AriaProgressBarProps;
+
+	let {
+		value = 0,
+		minValue = 0,
+		maxValue = 100,
+		valueLabel,
+		isIndeterminate,
+		formatOptions = {
+			style: 'percent',
+		},
+	} = props;
+
+	let domProps = filterDOMProps(props, { labelable: true });
+	let { labelProps, fieldProps } = useLabel(
+		{
+			...props,
+			// Progress bar is not an HTML input element so it
+			// shouldn't be labeled by a <label> element.
+			labelElementType: 'span',
+		},
+		subSlot(slot, 'label'),
+	);
+
+	value = clamp(value, minValue, maxValue);
+	let percentage = (value - minValue) / (maxValue - minValue);
+	let formatter = useNumberFormatter(formatOptions, subSlot(slot, 'formatter'));
+
+	if (!isIndeterminate && !valueLabel) {
+		let valueToFormat = formatOptions.style === 'percent' ? percentage : value;
+		valueLabel = formatter.format(valueToFormat);
+	}
+
+	return {
+		progressBarProps: mergeProps(domProps, {
+			...fieldProps,
+			'aria-valuenow': isIndeterminate ? undefined : value,
+			'aria-valuemin': minValue,
+			'aria-valuemax': maxValue,
+			'aria-valuetext': isIndeterminate ? undefined : (valueLabel as string),
+			role: 'progressbar',
+		}),
+		labelProps,
+	};
+}