@octanejs/aria 0.0.1 → 0.0.4

package/src/utils/useFormReset.ts

@@ -0,0 +1,54 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useFormReset.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; the explicit `[ref]` effect dep array is preserved exactly. The listener is
+// wired with native `addEventListener('reset')` exactly like upstream.
+import { useEffect } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useEffectEvent } from './useEffectEvent';
+
+type RefObject<T> = { current: T };
+
+export function useFormReset<T>(
+	ref: RefObject<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | null> | undefined,
+	initialValue: T,
+	onReset: (value: T) => void,
+): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useFormReset<T>(
+	ref: RefObject<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | null> | undefined,
+	initialValue: T,
+	onReset: (value: T) => void,
+	slot: symbol | undefined,
+): void;
+export function useFormReset(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useFormReset');
+	const ref = user[0] as
+		| { current: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | null }
+		| undefined;
+	const initialValue = user[1];
+	const onReset = user[2] as (value: any) => void;
+
+	let handleReset = useEffectEvent(
+		(e: Event) => {
+			if (onReset && !e.defaultPrevented) {
+				onReset(initialValue);
+			}
+		},
+		subSlot(slot, 'handler'),
+	);
+
+	useEffect(
+		() => {
+			let form = ref?.current?.form;
+
+			form?.addEventListener('reset', handleReset);
+			return () => {
+				form?.removeEventListener('reset', handleReset);
+			};
+		},
+		[ref],
+		subSlot(slot, 'listen'),
+	);
+}

package/src/utils/useId.ts

@@ -125,6 +125,11 @@ export function mergeIds(idA: string, idB: string): string {
  * @param depArray - When to recalculate if the id is in the DOM.
  */
 export function useSlotId(depArray?: ReadonlyArray<any>): string;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSlotId(
+	depArray: ReadonlyArray<any> | undefined,
+	slot: symbol | undefined,
+): string;
 export function useSlotId(...args: any[]): string {
 	const [user, slotArg] = splitSlot(args);
 	const slot = slotArg ?? S('useSlotId');

package/src/utils/useLabels.ts

@@ -0,0 +1,53 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useLabels.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; otherwise verbatim.
+import type { AriaLabelingProps, DOMProps } from '@react-types/shared';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useId } from './useId';
+
+/**
+ * Merges aria-label and aria-labelledby into aria-labelledby when both exist.
+ *
+ * @param props - Aria label props.
+ * @param defaultLabel - Default value for aria-label when not present.
+ */
+export function useLabels(
+	props: DOMProps & AriaLabelingProps,
+	defaultLabel?: string,
+): DOMProps & AriaLabelingProps;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useLabels(
+	props: DOMProps & AriaLabelingProps,
+	defaultLabel: string | undefined,
+	slot: symbol | undefined,
+): DOMProps & AriaLabelingProps;
+export function useLabels(...args: any[]): DOMProps & AriaLabelingProps {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useLabels');
+	const props = user[0] as DOMProps & AriaLabelingProps;
+	const defaultLabel = user[1] as string | undefined;
+
+	let { id, 'aria-label': label, 'aria-labelledby': labelledBy } = props;
+
+	// If there is both an aria-label and aria-labelledby,
+	// combine them by pointing to the element itself.
+	id = useId(id, subSlot(slot, 'id'));
+	if (labelledBy && label) {
+		let ids = new Set([id, ...labelledBy.trim().split(/\s+/)]);
+		labelledBy = [...ids].join(' ');
+	} else if (labelledBy) {
+		labelledBy = labelledBy.trim().split(/\s+/).join(' ');
+	}
+
+	// If no labels are provided, use the default
+	if (!label && !labelledBy && defaultLabel) {
+		label = defaultLabel;
+	}
+
+	return {
+		id,
+		'aria-label': label,
+		'aria-labelledby': labelledBy,
+	};
+}

package/src/utils/useResizeObserver.ts

@@ -0,0 +1,70 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useResizeObserver.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; the explicit `[ref, box]` dependency array is kept verbatim.
+import type { RefObject } from '@react-types/shared';
+import { useEffect } from 'octane';
+import { useEffectEvent } from './useEffectEvent';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+function hasResizeObserver() {
+	return typeof window.ResizeObserver !== 'undefined';
+}
+
+type useResizeObserverOptionsType<T> = {
+	ref: RefObject<T | undefined | null> | undefined;
+	box?: ResizeObserverBoxOptions;
+	onResize: () => void;
+};
+
+export function useResizeObserver<T extends Element>(
+	options: useResizeObserverOptionsType<T>,
+): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useResizeObserver<T extends Element>(
+	options: useResizeObserverOptionsType<T>,
+	slot: symbol | undefined,
+): void;
+export function useResizeObserver(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useResizeObserver');
+	const options = user[0] as useResizeObserverOptionsType<Element>;
+
+	// Only call onResize from inside the effect, otherwise we'll void our assumption that
+	// useEffectEvents are safe to pass in.
+	const { ref, box, onResize } = options;
+	let onResizeEvent = useEffectEvent(onResize, subSlot(slot, 'onResize'));
+
+	useEffect(
+		() => {
+			let element = ref?.current;
+			if (!element) {
+				return;
+			}
+
+			if (!hasResizeObserver()) {
+				window.addEventListener('resize', onResizeEvent, false);
+				return () => {
+					window.removeEventListener('resize', onResizeEvent, false);
+				};
+			} else {
+				const resizeObserverInstance = new window.ResizeObserver((entries) => {
+					if (!entries.length) {
+						return;
+					}
+
+					onResizeEvent();
+				});
+				resizeObserverInstance.observe(element, { box });
+
+				return () => {
+					if (element) {
+						resizeObserverInstance.unobserve(element);
+					}
+				};
+			}
+		},
+		[ref, box],
+		subSlot(slot, 'observe'),
+	);
+}

package/src/utils/useSlot.ts

@@ -0,0 +1,78 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useSlot.ts).
+// octane adaptations: React's `RefCallback` type is declared locally (octane refs are
+// React-19-style callback refs passed as props); public-hook slot threading
+// (splitSlot/subSlot) per the binding convention; the explicit `[]` dep arrays are
+// preserved exactly.
+import { useCallback, useRef, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useId } from './useId';
+import { useLayoutEffect } from './useLayoutEffect';
+
+type RefCallback<T> = (instance: T | null) => void;
+
+export function useSlot(initialState?: boolean | (() => boolean)): [RefCallback<any>, boolean];
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSlot(
+	initialState: boolean | (() => boolean) | undefined,
+	slot: symbol | undefined,
+): [RefCallback<any>, boolean];
+export function useSlot(...args: any[]): [RefCallback<any>, boolean] {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSlot');
+	const initialState = (user[0] as boolean | (() => boolean) | undefined) ?? true;
+
+	// Initial state is typically based on the parent having an aria-label or aria-labelledby.
+	// If it does, this value should be false so that we don't update the state and cause a rerender when we go through the layoutEffect
+	let [hasSlot, setHasSlot] = useState(initialState, subSlot(slot, 'hasSlot'));
+	let hasRun = useRef(false, subSlot(slot, 'hasRun'));
+
+	// A callback ref which will run when the slotted element mounts.
+	// This should happen before the useLayoutEffect below.
+	let ref = useCallback(
+		(el: any) => {
+			hasRun.current = true;
+			setHasSlot(!!el);
+		},
+		[],
+		subSlot(slot, 'ref'),
+	);
+
+	// If the callback hasn't been called, then reset to false.
+	useLayoutEffect(
+		() => {
+			if (!hasRun.current) {
+				setHasSlot(false);
+			}
+		},
+		[],
+		subSlot(slot, 'reset'),
+	);
+
+	return [ref, hasSlot];
+}
+
+interface SlotAria {
+	id: string | undefined;
+	ref: RefCallback<any>;
+}
+
+export function useSlotId2(initialState?: boolean | (() => boolean)): SlotAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSlotId2(
+	initialState: boolean | (() => boolean) | undefined,
+	slot: symbol | undefined,
+): SlotAria;
+export function useSlotId2(...args: any[]): SlotAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSlotId2');
+	const initialState = (user[0] as boolean | (() => boolean) | undefined) ?? true;
+
+	let id = useId(subSlot(slot, 'id'));
+	let [ref, hasSlot] = useSlot(initialState, subSlot(slot, 'slot'));
+
+	return {
+		id: hasSlot ? id : undefined,
+		ref,
+	};
+}

package/src/utils/useUpdateEffect.ts

@@ -0,0 +1,54 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useUpdateEffect.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; the explicit dependency arrays (including the caller-supplied one) are
+// preserved exactly.
+import { useEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useEffectEvent } from './useEffectEvent';
+
+type EffectCallback = () => void | (() => void);
+
+// Like useEffect, but only called for updates after the initial render.
+export function useUpdateEffect(cb: EffectCallback, dependencies: any[]): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useUpdateEffect(
+	cb: EffectCallback,
+	dependencies: any[],
+	slot: symbol | undefined,
+): void;
+export function useUpdateEffect(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useUpdateEffect');
+	const cb = user[0] as EffectCallback;
+	const dependencies = user[1] as any[];
+
+	const isInitialMount = useRef(true, subSlot(slot, 'initialMount'));
+	const lastDeps = useRef<any[] | null>(null, subSlot(slot, 'lastDeps'));
+	let cbEvent = useEffectEvent(cb, subSlot(slot, 'cb'));
+
+	useEffect(
+		() => {
+			isInitialMount.current = true;
+			return () => {
+				isInitialMount.current = false;
+			};
+		},
+		[],
+		subSlot(slot, 'mountFx'),
+	);
+
+	useEffect(
+		() => {
+			let prevDeps = lastDeps.current;
+			if (isInitialMount.current) {
+				isInitialMount.current = false;
+			} else if (!prevDeps || dependencies.some((dep, i) => !Object.is(dep, prevDeps[i]))) {
+				cbEvent();
+			}
+			lastDeps.current = dependencies;
+		},
+		dependencies,
+		subSlot(slot, 'updateFx'),
+	);
+}

package/src/utils/useUpdateLayoutEffect.ts

@@ -0,0 +1,58 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useUpdateLayoutEffect.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; explicit dependency arrays are kept verbatim (they retain React's exact
+// behavior in octane).
+import { useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useLayoutEffect } from './useLayoutEffect';
+
+// React's EffectCallback shape (octane does not export the type alias).
+type EffectCallback = () => void | (() => void);
+
+// Like useLayoutEffect, but only called for updates after the initial render.
+export function useUpdateLayoutEffect(effect: EffectCallback, dependencies: any[]): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useUpdateLayoutEffect(
+	effect: EffectCallback,
+	dependencies: any[],
+	slot: symbol | undefined,
+): void;
+export function useUpdateLayoutEffect(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useUpdateLayoutEffect');
+	const effect = user[0] as EffectCallback;
+	const dependencies = user[1] as any[];
+
+	const isInitialMount = useRef(true, subSlot(slot, 'initial'));
+	const lastDeps = useRef<any[] | null>(null, subSlot(slot, 'lastDeps'));
+
+	useLayoutEffect(
+		() => {
+			isInitialMount.current = true;
+			return () => {
+				isInitialMount.current = false;
+			};
+		},
+		[],
+		subSlot(slot, 'mountFlag'),
+	);
+
+	useLayoutEffect(
+		() => {
+			if (isInitialMount.current) {
+				isInitialMount.current = false;
+			} else if (
+				!lastDeps.current ||
+				// NOTE: `lastDeps[i]` (not `.current[i]`) is upstream's exact expression — kept verbatim.
+				dependencies.some((dep, i) => !Object.is(dep, (lastDeps as any)[i]))
+			) {
+				effect();
+			}
+			lastDeps.current = dependencies;
+			// eslint-disable-next-line react-hooks/exhaustive-deps
+		},
+		dependencies,
+		subSlot(slot, 'update'),
+	);
+}

package/src/visually-hidden/VisuallyHidden.ts

@@ -0,0 +1,100 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/visually-hidden/VisuallyHidden.tsx).
+// octane adaptations: the component is built with `createElement` (elementType may be a
+// tag string or an octane component); React's CSSProperties → a structural style object;
+// public-hook slot threading.
+import type { DOMAttributes } from '@react-types/shared';
+import { createElement, useMemo, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { mergeProps } from '../utils/mergeProps';
+import { useFocusWithin } from '../interactions/useFocusWithin';
+
+export interface VisuallyHiddenProps extends DOMAttributes {
+	/** The content to visually hide. */
+	children?: any;
+
+	/**
+	 * The element type for the container.
+	 *
+	 * @default 'div'
+	 */
+	elementType?: string | ((props: any) => any);
+
+	/** Whether the element should become visible on focus, for example skip links. */
+	isFocusable?: boolean;
+
+	style?: Record<string, any>;
+}
+
+const styles: Record<string, any> = {
+	border: 0,
+	clip: 'rect(0 0 0 0)',
+	clipPath: 'inset(50%)',
+	height: '1px',
+	margin: '-1px',
+	overflow: 'hidden',
+	padding: 0,
+	position: 'absolute',
+	width: '1px',
+	whiteSpace: 'nowrap',
+};
+
+export interface VisuallyHiddenAria {
+	visuallyHiddenProps: DOMAttributes;
+}
+
+export function useVisuallyHidden(props?: VisuallyHiddenProps): VisuallyHiddenAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useVisuallyHidden(
+	props: VisuallyHiddenProps | undefined,
+	slot: symbol | undefined,
+): VisuallyHiddenAria;
+export function useVisuallyHidden(...args: any[]): VisuallyHiddenAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useVisuallyHidden');
+	const props = (user[0] as VisuallyHiddenProps | undefined) ?? {};
+
+	let { style, isFocusable } = props;
+
+	let [isFocused, setFocused] = useState(false, subSlot(slot, 'focused'));
+	let { focusWithinProps } = useFocusWithin(
+		{
+			isDisabled: !isFocusable,
+			onFocusWithinChange: (val: boolean) => setFocused(val),
+		},
+		subSlot(slot, 'focusWithin'),
+	);
+
+	// If focused, don't hide the element.
+	let combinedStyles = useMemo(
+		() => {
+			if (isFocused) {
+				return style;
+			} else if (style) {
+				return { ...styles, ...style };
+			} else {
+				return styles;
+			}
+		},
+		[isFocused],
+		subSlot(slot, 'styles'),
+	);
+
+	return {
+		visuallyHiddenProps: {
+			...focusWithinProps,
+			style: combinedStyles,
+		} as DOMAttributes,
+	};
+}
+
+export function VisuallyHidden(props: VisuallyHiddenProps): any {
+	let { children, elementType: Element = 'div', isFocusable, style, ...otherProps } = props;
+	let { visuallyHiddenProps } = useVisuallyHidden(props, S('VisuallyHidden'));
+
+	return createElement(
+		Element as any,
+		mergeProps(otherProps, visuallyHiddenProps as any),
+		children,
+	);
+}