@octanejs/aria 0.0.1 → 0.0.3

package/src/dialog/useDialog.ts

@@ -0,0 +1,147 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/dialog/useDialog.ts).
+// octane adaptations: `DOMAttributes` is a local structural prop-bag alias (upstream's is typed
+// over React's synthetic handlers); the onBlur handler receives a NATIVE DOM FocusEvent (no
+// synthetic layer); `useEffect`/`useRef` import from 'octane'; the dep-less dev-warning
+// `useEffect` gets an explicit `null` dep arg (the explicit `[ref]` dep array is kept verbatim);
+// public-hook slot threading (splitSlot/subSlot) per the binding convention — sibling ported
+// hooks (useSlotId, useOverlayFocusContain) receive a derived sub-slot as their trailing arg.
+import type { AriaLabelingProps, DOMProps, FocusableElement, RefObject } from '@react-types/shared';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { focusSafely } from '../interactions/focusSafely';
+import { getActiveElement, isFocusWithin } from '../utils/shadowdom/DOMFunctions';
+import { useEffect, useRef } from 'octane';
+import { useOverlayFocusContain } from '../overlays/Overlay';
+import { useSlotId } from '../utils/useId';
+
+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 AriaDialogProps extends DOMProps, AriaLabelingProps {
+	/**
+	 * The accessibility role for the dialog.
+	 *
+	 * @default 'dialog'
+	 */
+	role?: 'dialog' | 'alertdialog';
+}
+
+export interface DialogAria {
+	/** Props for the dialog container element. */
+	dialogProps: DOMAttributes;
+
+	/** Props for the dialog title element. */
+	titleProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a dialog component.
+ * A dialog is an overlay shown above other content in an application.
+ */
+export function useDialog(
+	props: AriaDialogProps,
+	ref: RefObject<FocusableElement | null>,
+): DialogAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useDialog(
+	props: AriaDialogProps,
+	ref: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): DialogAria;
+export function useDialog(...args: any[]): DialogAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useDialog');
+	const props = user[0] as AriaDialogProps;
+	const ref = user[1] as RefObject<FocusableElement | null>;
+
+	let { role = 'dialog' } = props;
+	let titleId: string | undefined = useSlotId(undefined, subSlot(slot, 'title'));
+	titleId = props['aria-label'] ? undefined : titleId;
+
+	let isRefocusing = useRef(false, subSlot(slot, 'refocusing'));
+
+	// Focus the dialog itself on mount, unless a child element is already focused.
+	useEffect(
+		() => {
+			if (ref.current && !isFocusWithin(ref.current)) {
+				focusSafely(ref.current);
+
+				// Safari on iOS does not move the VoiceOver cursor to the dialog
+				// or announce that it has opened until it has rendered. A workaround
+				// is to wait for half a second, then blur and re-focus the dialog.
+				let timeout = setTimeout(() => {
+					// Check that the dialog is still focused, or focused was lost to the body.
+					if (getActiveElement() === ref.current || getActiveElement() === document.body) {
+						isRefocusing.current = true;
+						if (ref.current) {
+							ref.current.blur();
+							focusSafely(ref.current);
+						}
+						isRefocusing.current = false;
+					}
+				}, 500);
+
+				return () => {
+					clearTimeout(timeout);
+				};
+			}
+		},
+		[ref],
+		subSlot(slot, 'autofocus'),
+	);
+
+	useOverlayFocusContain(subSlot(slot, 'focusContain'));
+
+	// Warn in dev mode if the dialog has no accessible title.
+	// This catches a common mistake where useDialog and useOverlayTriggerState
+	// are used in the same component, causing the title element to not be
+	// in the DOM when useSlotId queries for it.
+	// Check the DOM element directly since aria-labelledby may be added by
+	// wrapper components (e.g. RAC Dialog uses trigger ID as a fallback).
+	let hasWarned = useRef(false, subSlot(slot, 'warned'));
+	useEffect(
+		() => {
+			if (process.env.NODE_ENV !== 'production' && !hasWarned.current && ref.current) {
+				let el = ref.current;
+				let hasAriaLabel = el.hasAttribute('aria-label');
+				let hasAriaLabelledby = el.hasAttribute('aria-labelledby');
+				if (!hasAriaLabel && !hasAriaLabelledby) {
+					console.warn(
+						'A dialog must have a title for accessibility. ' +
+							'Either provide an aria-label or aria-labelledby prop, or render a heading element inside the dialog.',
+					);
+					hasWarned.current = true;
+				}
+			}
+		},
+		null,
+		subSlot(slot, 'warn'),
+	);
+
+	// We do not use aria-modal due to a Safari bug which forces the first focusable element to be focused
+	// on mount when inside an iframe, no matter which element we programmatically focus.
+	// See https://bugs.webkit.org/show_bug.cgi?id=211934.
+	// useModal sets aria-hidden on all elements outside the dialog, so the dialog will behave as a modal
+	// even without aria-modal on the dialog itself.
+	return {
+		dialogProps: {
+			...filterDOMProps(props, { labelable: true }),
+			role,
+			tabIndex: -1,
+			'aria-labelledby': props['aria-labelledby'] || titleId,
+			// Prevent blur events from reaching useOverlay, which may cause
+			// popovers to close. Since focus is contained within the dialog,
+			// we don't want this to occur due to the above useEffect.
+			onBlur: (e: any) => {
+				if (isRefocusing.current) {
+					e.stopPropagation();
+				}
+			},
+		},
+		titleProps: {
+			id: titleId,
+		},
+	};
+}

package/src/disclosure/useDisclosure.ts

@@ -0,0 +1,180 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/disclosure/useDisclosure.ts).
+// octane adaptations: `flushSync` from 'octane'; React's HTMLAttributes → structural
+// prop bag; public-hook slot threading.
+import type { PressEvent, RefObject } from '@react-types/shared';
+import { flushSync, useCallback, useEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import type { AriaButtonProps } from '../button/useButton';
+import type { DisclosureState } from '../stately/disclosure/useDisclosureState';
+import { useEvent } from '../utils/useEvent';
+import { useId } from '../utils/useId';
+import { useIsSSR } from '../ssr/SSRProvider';
+import { useLayoutEffect } from '../utils/useLayoutEffect';
+
+export interface AriaDisclosureProps {
+	/** Whether the disclosure is disabled. */
+	isDisabled?: boolean;
+	/** Handler that is called when the disclosure's expanded state changes. */
+	onExpandedChange?: (isExpanded: boolean) => void;
+	/** Whether the disclosure is expanded (controlled). */
+	isExpanded?: boolean;
+	/** Whether the disclosure is expanded by default (uncontrolled). */
+	defaultExpanded?: boolean;
+}
+
+export interface DisclosureAria {
+	/** Props for the disclosure button. */
+	buttonProps: AriaButtonProps;
+	/** Props for the disclosure panel. */
+	panelProps: Record<string, any>;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a disclosure component.
+ */
+export function useDisclosure(
+	props: AriaDisclosureProps,
+	state: DisclosureState,
+	ref: RefObject<HTMLElement | null>,
+): DisclosureAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useDisclosure(
+	props: AriaDisclosureProps,
+	state: DisclosureState,
+	ref: RefObject<HTMLElement | null>,
+	slot: symbol | undefined,
+): DisclosureAria;
+export function useDisclosure(...args: any[]): DisclosureAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useDisclosure');
+	const props = user[0] as AriaDisclosureProps;
+	const state = user[1] as DisclosureState;
+	const ref = user[2] as RefObject<HTMLElement | null>;
+
+	let { isDisabled } = props;
+	let triggerId = useId(subSlot(slot, 'triggerId'));
+	let panelId = useId(subSlot(slot, 'panelId'));
+	let isSSR = useIsSSR(subSlot(slot, 'ssr'));
+
+	let raf = useRef<number | null>(null, subSlot(slot, 'raf'));
+
+	let handleBeforeMatch = useCallback(
+		() => {
+			// Wait a frame to revert browser's removal of hidden attribute
+			raf.current = requestAnimationFrame(() => {
+				if (ref.current) {
+					ref.current.setAttribute('hidden', 'until-found');
+				}
+			});
+			// Force sync state update
+			flushSync(() => {
+				state.toggle();
+			});
+		},
+		[ref, state],
+		subSlot(slot, 'beforeMatch'),
+	);
+
+	useEvent(ref, 'beforematch', handleBeforeMatch, subSlot(slot, 'beforeMatchEvent'));
+
+	let isExpandedRef = useRef<boolean | null>(null, subSlot(slot, 'wasExpanded'));
+	useLayoutEffect(
+		() => {
+			// Cancel any pending RAF to prevent stale updates
+			if (raf.current) {
+				cancelAnimationFrame(raf.current);
+			}
+			if (ref.current && !isSSR) {
+				let panel = ref.current;
+
+				if (isExpandedRef.current == null || typeof panel.getAnimations !== 'function') {
+					// On initial render (and in tests), set attributes without animation.
+					if (state.isExpanded) {
+						panel.removeAttribute('hidden');
+						panel.style.setProperty('--disclosure-panel-width', 'auto');
+						panel.style.setProperty('--disclosure-panel-height', 'auto');
+					} else {
+						panel.setAttribute('hidden', 'until-found');
+						panel.style.setProperty('--disclosure-panel-width', '0px');
+						panel.style.setProperty('--disclosure-panel-height', '0px');
+					}
+				} else if (state.isExpanded !== isExpandedRef.current) {
+					if (state.isExpanded) {
+						panel.removeAttribute('hidden');
+
+						// Set the width and height as pixels so they can be animated.
+						panel.style.setProperty('--disclosure-panel-width', panel.scrollWidth + 'px');
+						panel.style.setProperty('--disclosure-panel-height', panel.scrollHeight + 'px');
+
+						Promise.all(panel.getAnimations().map((a) => a.finished))
+							.then(() => {
+								// After the animations complete, switch back to auto so the content can resize.
+								panel.style.setProperty('--disclosure-panel-width', 'auto');
+								panel.style.setProperty('--disclosure-panel-height', 'auto');
+							})
+							.catch(() => {});
+					} else {
+						panel.style.setProperty('--disclosure-panel-width', panel.scrollWidth + 'px');
+						panel.style.setProperty('--disclosure-panel-height', panel.scrollHeight + 'px');
+
+						// Force style re-calculation to trigger animations.
+						window.getComputedStyle(panel).height;
+
+						// Animate to zero size.
+						panel.style.setProperty('--disclosure-panel-width', '0px');
+						panel.style.setProperty('--disclosure-panel-height', '0px');
+
+						// Wait for animations to apply the hidden attribute.
+						Promise.all(panel.getAnimations().map((a) => a.finished))
+							.then(() => panel.setAttribute('hidden', 'until-found'))
+							.catch(() => {});
+					}
+				}
+
+				isExpandedRef.current = state.isExpanded;
+			}
+		},
+		[isDisabled, ref, state.isExpanded, isSSR],
+		subSlot(slot, 'panelSync'),
+	);
+
+	useEffect(
+		() => {
+			return () => {
+				if (raf.current) {
+					cancelAnimationFrame(raf.current);
+				}
+			};
+		},
+		[],
+		subSlot(slot, 'rafCleanup'),
+	);
+
+	return {
+		buttonProps: {
+			id: triggerId,
+			'aria-expanded': state.isExpanded,
+			'aria-controls': panelId,
+			onPress: (e: PressEvent) => {
+				if (!isDisabled && e.pointerType !== 'keyboard') {
+					state.toggle();
+				}
+			},
+			isDisabled,
+			onPressStart(e: PressEvent) {
+				if (e.pointerType === 'keyboard' && !isDisabled) {
+					state.toggle();
+				}
+			},
+		},
+		panelProps: {
+			id: panelId,
+			// This can be overridden at the panel element level.
+			role: 'group',
+			'aria-labelledby': triggerId,
+			'aria-hidden': !state.isExpanded,
+			hidden: isSSR ? !state.isExpanded : undefined,
+		},
+	};
+}

package/src/focus/FocusRing.ts

@@ -0,0 +1,69 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/focus/FocusRing.tsx).
+// octane adaptations:
+// - Built with octane's `Children`/`cloneElement` over element DESCRIPTORS (prop-position
+//   JSX / createElement results); a single-element array unwraps before `Children.only`,
+//   per the binding's children convention (see interactions/useFocusable.ts Focusable).
+// - `React.ReactElement` types → `any` (octane descriptors); component slot via S().
+// - `clsx` stays (upstream dependency); the merged `className` composes through
+//   `mergeProps` exactly like upstream.
+
+import clsx from 'clsx';
+import { Children, cloneElement } from 'octane';
+
+import { S, subSlot } from '../internal';
+import { mergeProps } from '../utils/mergeProps';
+import { useFocusRing } from './useFocusRing';
+
+export interface FocusRingProps {
+	/** Child element to apply CSS classes to. */
+	children: any;
+	/** CSS class to apply when the element is focused. */
+	focusClass?: string;
+	/** CSS class to apply when the element has keyboard focus. */
+	focusRingClass?: string;
+	/**
+	 * Whether to show the focus ring when something
+	 * inside the container element has focus (true), or
+	 * only if the container itself has focus (false).
+	 *
+	 * @default false
+	 */
+	within?: boolean;
+	/** Whether the element is a text input. */
+	isTextInput?: boolean;
+	/** Whether the element will be auto focused. */
+	autoFocus?: boolean;
+}
+
+/**
+ * A utility component that applies a CSS class when an element has keyboard focus.
+ * Focus rings are visible only when the user is interacting with a keyboard,
+ * not with a mouse, touch, or other input methods.
+ */
+export function FocusRing(props: FocusRingProps): any {
+	const slot = S('FocusRing');
+	let { children, focusClass, focusRingClass } = props;
+	let { isFocused, isFocusVisible, focusProps } = useFocusRing(props, subSlot(slot, 'ring'));
+
+	// octane adaptation: children arrive as descriptors; a single-element array unwraps
+	// (octane convention — see interactions/useFocusable.ts Focusable).
+	let target: any = children;
+	if (Array.isArray(children)) {
+		const arr = Children.toArray(children);
+		if (arr.length === 1) {
+			target = arr[0];
+		}
+	}
+	let child: any = Children.only(target);
+
+	return cloneElement(
+		child,
+		mergeProps(child.props as any, {
+			...focusProps,
+			className: clsx({
+				[focusClass || '']: isFocused,
+				[focusRingClass || '']: isFocusVisible,
+			}),
+		}),
+	);
+}