@octanejs/aria 0.0.1

package/src/utils/useEvent.ts

@@ -0,0 +1,55 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useEvent.ts).
+import type { RefObject } from '@react-types/shared';
+import { useEffect } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useEffectEvent } from './useEffectEvent';
+
+export function useEvent<K extends keyof GlobalEventHandlersEventMap>(
+	ref: RefObject<EventTarget | null>,
+	event: K | (string & {}),
+	handler?: (this: Document, ev: GlobalEventHandlersEventMap[K]) => any,
+	options?: boolean | AddEventListenerOptions,
+): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg
+// (the optional `options` user arg, when present, comes before it).
+export function useEvent<K extends keyof GlobalEventHandlersEventMap>(
+	ref: RefObject<EventTarget | null>,
+	event: K | (string & {}),
+	handler: ((this: Document, ev: GlobalEventHandlersEventMap[K]) => any) | undefined,
+	slot: symbol | undefined,
+): void;
+export function useEvent<K extends keyof GlobalEventHandlersEventMap>(
+	ref: RefObject<EventTarget | null>,
+	event: K | (string & {}),
+	handler: ((this: Document, ev: GlobalEventHandlersEventMap[K]) => any) | undefined,
+	options: boolean | AddEventListenerOptions | undefined,
+	slot: symbol | undefined,
+): void;
+export function useEvent(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useEvent');
+	const ref = user[0] as { current: EventTarget | null };
+	const event = user[1] as string;
+	const handler = user[2] as EventListener | undefined;
+	const options = user[3] as boolean | AddEventListenerOptions | undefined;
+
+	let handleEvent = useEffectEvent(handler, subSlot(slot, 'handler'));
+	let isDisabled = handler == null;
+
+	useEffect(
+		() => {
+			if (isDisabled || !ref.current) {
+				return;
+			}
+
+			let element = ref.current;
+			element.addEventListener(event, handleEvent as EventListener, options);
+			return () => {
+				element.removeEventListener(event, handleEvent as EventListener, options);
+			};
+		},
+		[ref, event, options, isDisabled],
+		subSlot(slot, 'listen'),
+	);
+}

package/src/utils/useGlobalListeners.ts

@@ -0,0 +1,91 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useGlobalListeners.ts).
+import { useCallback, useEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export interface GlobalListeners {
+	addGlobalListener<K extends keyof WindowEventMap>(
+		el: Window,
+		type: K,
+		listener: (this: Document, ev: WindowEventMap[K]) => any,
+		options?: boolean | AddEventListenerOptions,
+	): void;
+	addGlobalListener<K extends keyof DocumentEventMap>(
+		el: EventTarget,
+		type: K,
+		listener: (this: Document, ev: DocumentEventMap[K]) => any,
+		options?: boolean | AddEventListenerOptions,
+	): void;
+	addGlobalListener(
+		el: EventTarget,
+		type: string,
+		listener: EventListenerOrEventListenerObject,
+		options?: boolean | AddEventListenerOptions,
+	): void;
+	removeGlobalListener<K extends keyof DocumentEventMap>(
+		el: EventTarget,
+		type: K,
+		listener: (this: Document, ev: DocumentEventMap[K]) => any,
+		options?: boolean | EventListenerOptions,
+	): void;
+	removeGlobalListener(
+		el: EventTarget,
+		type: string,
+		listener: EventListenerOrEventListenerObject,
+		options?: boolean | EventListenerOptions,
+	): void;
+	removeAllGlobalListeners(): void;
+}
+
+export function useGlobalListeners(): GlobalListeners;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useGlobalListeners(slot: symbol | undefined): GlobalListeners;
+export function useGlobalListeners(...args: any[]): GlobalListeners {
+	const [, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useGlobalListeners');
+
+	let globalListeners = useRef(new Map(), subSlot(slot, 'map'));
+	let addGlobalListener = useCallback(
+		(eventTarget: any, type: any, listener: any, options: any) => {
+			// Make sure we remove the listener after it is called with the `once` option.
+			let fn = options?.once
+				? (...args: any[]) => {
+						globalListeners.current.delete(listener);
+						listener(...args);
+					}
+				: listener;
+			globalListeners.current.set(listener, { type, eventTarget, fn, options });
+			eventTarget.addEventListener(type, fn, options);
+		},
+		[],
+		subSlot(slot, 'add'),
+	);
+	let removeGlobalListener = useCallback(
+		(eventTarget: any, type: any, listener: any, options: any) => {
+			let fn = globalListeners.current.get(listener)?.fn || listener;
+			eventTarget.removeEventListener(type, fn, options);
+			globalListeners.current.delete(listener);
+		},
+		[],
+		subSlot(slot, 'remove'),
+	);
+	let removeAllGlobalListeners = useCallback(
+		() => {
+			globalListeners.current.forEach((value: any, key: any) => {
+				removeGlobalListener(value.eventTarget, value.type, key, value.options);
+			});
+		},
+		[removeGlobalListener],
+		subSlot(slot, 'removeAll'),
+	);
+
+	useEffect(
+		() => {
+			return removeAllGlobalListeners;
+		},
+		[removeAllGlobalListeners],
+		subSlot(slot, 'teardown'),
+	);
+
+	return { addGlobalListener, removeGlobalListener, removeAllGlobalListeners } as GlobalListeners;
+}

package/src/utils/useId.ts

@@ -0,0 +1,150 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useId.ts).
+// The full id machinery ports as-is: `mergeIds` retroactively rewrites the id of every
+// registered `useId` consumer (via the `idsUpdaterMap` ref registry + the run-every-render
+// effect below), so two hooks that each generated an id converge on one after merging.
+import { useEffect, useRef, useState, useCallback } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useSSRSafeId } from '../ssr/SSRProvider';
+import { useLayoutEffect } from './useLayoutEffect';
+import { useValueEffect } from './useValueEffect';
+
+let canUseDOM = Boolean(
+	typeof window !== 'undefined' && window.document && window.document.createElement,
+);
+
+export let idsUpdaterMap: Map<string, { current: string | null }[]> = new Map();
+// This allows us to clean up the idsUpdaterMap when the id is no longer used.
+// Map is a strong reference, so unused ids wouldn't be cleaned up otherwise.
+// This can happen in suspended components where mount/unmount is not called.
+let registry: FinalizationRegistry<string> | undefined;
+if (typeof FinalizationRegistry !== 'undefined') {
+	registry = new FinalizationRegistry<string>((heldValue) => {
+		idsUpdaterMap.delete(heldValue);
+	});
+}
+
+/**
+ * If a default is not provided, generate an id.
+ *
+ * @param defaultId - Default component id.
+ */
+export function useId(defaultId?: string): string;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useId(slot: symbol | undefined): string;
+export function useId(defaultId: string | undefined, slot: symbol | undefined): string;
+export function useId(...args: any[]): string {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useId');
+	const defaultId = user[0] as string | undefined;
+
+	let [value, setValue] = useState(defaultId, subSlot(slot, 'value'));
+	let nextId = useRef<string | null>(null, subSlot(slot, 'nextId'));
+
+	let res = useSSRSafeId(value, subSlot(slot, 'ssrId'));
+	let cleanupRef = useRef(null, subSlot(slot, 'cleanupToken'));
+
+	if (registry) {
+		registry.register(cleanupRef, res);
+	}
+
+	if (canUseDOM) {
+		const cacheIdRef = idsUpdaterMap.get(res);
+		if (cacheIdRef && !cacheIdRef.includes(nextId)) {
+			cacheIdRef.push(nextId);
+		} else {
+			idsUpdaterMap.set(res, [nextId]);
+		}
+	}
+
+	useLayoutEffect(
+		() => {
+			let r = res;
+			return () => {
+				// In Suspense, the cleanup function may be not called
+				// when it is though, also remove it from the finalization registry.
+				if (registry) {
+					registry.unregister(cleanupRef);
+				}
+				idsUpdaterMap.delete(r);
+			};
+		},
+		[res],
+		subSlot(slot, 'unregister'),
+	);
+
+	// This cannot cause an infinite loop because the ref is always cleaned up.
+	useEffect(
+		() => {
+			let newId = nextId.current;
+			if (newId) {
+				setValue(newId);
+			}
+
+			return () => {
+				if (newId) {
+					nextId.current = null;
+				}
+			};
+		},
+		null,
+		subSlot(slot, 'apply'),
+	);
+
+	return res;
+}
+
+/**
+ * Merges two ids.
+ * Different ids will trigger a side-effect and re-render components hooked up with `useId`.
+ */
+export function mergeIds(idA: string, idB: string): string {
+	if (idA === idB) {
+		return idA;
+	}
+
+	let setIdsA = idsUpdaterMap.get(idA);
+	if (setIdsA) {
+		setIdsA.forEach((ref) => (ref.current = idB));
+		return idB;
+	}
+
+	let setIdsB = idsUpdaterMap.get(idB);
+	if (setIdsB) {
+		setIdsB.forEach((ref) => (ref.current = idA));
+		return idA;
+	}
+
+	return idB;
+}
+
+/**
+ * Used to generate an id, and after render, check if that id is rendered so we know
+ * if we can use it in places such as labelledby.
+ *
+ * @param depArray - When to recalculate if the id is in the DOM.
+ */
+export function useSlotId(depArray?: ReadonlyArray<any>): string;
+export function useSlotId(...args: any[]): string {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSlotId');
+	const depArray = (user[0] as ReadonlyArray<any> | undefined) ?? [];
+
+	let id = useId(subSlot(slot, 'id'));
+	let [resolvedId, setResolvedId] = useValueEffect(id, subSlot(slot, 'resolved'));
+	let updateId = useCallback(
+		() => {
+			setResolvedId(function* () {
+				yield id;
+
+				yield document.getElementById(id) ? id : undefined;
+			});
+		},
+		[id, setResolvedId],
+		subSlot(slot, 'update'),
+	);
+
+	useLayoutEffect(updateId, [id, updateId, ...depArray], subSlot(slot, 'run'));
+
+	return resolvedId as string;
+}

package/src/utils/useLayoutEffect.ts

@@ -0,0 +1,7 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useLayoutEffect.ts).
+// Layout effects never run on the server; the document guard keeps server bundles
+// (where `octane` resolves to the server runtime) from scheduling one at all.
+import { useLayoutEffect as octaneUseLayoutEffect } from 'octane';
+
+export const useLayoutEffect: typeof octaneUseLayoutEffect =
+	typeof document !== 'undefined' ? octaneUseLayoutEffect : ((() => {}) as any);

package/src/utils/useObjectRef.ts

@@ -0,0 +1,88 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useObjectRef.ts).
+// React's `forwardRef` becomes octane's ref-as-prop; this hook adapts whatever ref shape a
+// caller passed (callback ref with optional cleanup, or object ref) into an object ref the
+// aria hooks can read, updating the original on assignment.
+import { useCallback, useMemo, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+type MutableRefObject<T> = { current: T };
+
+/**
+ * Offers an object ref for a given callback ref or an object ref. Especially
+ * helpful when passing forwarded refs to aria hooks.
+ *
+ * @param ref The original ref intended to be used.
+ * @returns An object ref that updates the given ref.
+ */
+export function useObjectRef<T>(
+	ref?: ((instance: T | null) => (() => void) | void) | MutableRefObject<T | null> | null,
+): MutableRefObject<T | null>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useObjectRef<T>(
+	ref:
+		| ((instance: T | null) => (() => void) | void)
+		| MutableRefObject<T | null>
+		| null
+		| undefined,
+	slot: symbol | undefined,
+): MutableRefObject<T | null>;
+export function useObjectRef(...args: any[]): any {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useObjectRef');
+	const ref = user[0] as
+		| ((instance: any) => (() => void) | void)
+		| MutableRefObject<any>
+		| null
+		| undefined;
+
+	const objRef: MutableRefObject<any> = useRef(null, subSlot(slot, 'obj'));
+	const cleanupRef: MutableRefObject<(() => void) | void> = useRef(
+		undefined,
+		subSlot(slot, 'cleanup'),
+	);
+
+	const refEffect = useCallback(
+		(instance: any) => {
+			if (typeof ref === 'function') {
+				const refCallback = ref;
+				const refCleanup = refCallback(instance);
+				return () => {
+					if (typeof refCleanup === 'function') {
+						refCleanup();
+					} else {
+						refCallback(null);
+					}
+				};
+			} else if (ref) {
+				ref.current = instance;
+				return () => {
+					ref.current = null;
+				};
+			}
+		},
+		[ref],
+		subSlot(slot, 'refEffect'),
+	);
+
+	return useMemo(
+		() => ({
+			get current() {
+				return objRef.current;
+			},
+			set current(value) {
+				objRef.current = value;
+				if (cleanupRef.current) {
+					cleanupRef.current();
+					cleanupRef.current = undefined;
+				}
+
+				if (value != null) {
+					cleanupRef.current = refEffect(value);
+				}
+			},
+		}),
+		[refEffect],
+		subSlot(slot, 'result'),
+	);
+}

package/src/utils/useSyncRef.ts

@@ -0,0 +1,39 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useSyncRef.ts).
+import type { RefObject } from '@react-types/shared';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useLayoutEffect } from './useLayoutEffect';
+
+interface ContextValue<T> {
+	ref?: { current: T | null };
+}
+
+// Syncs ref from context with ref passed to hook
+export function useSyncRef<T>(context?: ContextValue<T> | null, ref?: RefObject<T | null>): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSyncRef<T>(
+	context: ContextValue<T> | null | undefined,
+	ref: RefObject<T | null> | undefined,
+	slot: symbol | undefined,
+): void;
+export function useSyncRef(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSyncRef');
+	const context = user[0] as ContextValue<any> | null | undefined;
+	const ref = user[1] as { current: any } | undefined;
+
+	useLayoutEffect(
+		() => {
+			if (context && context.ref && ref) {
+				context.ref.current = ref.current;
+				return () => {
+					if (context.ref) {
+						context.ref.current = null;
+					}
+				};
+			}
+		},
+		null,
+		subSlot(slot, 'sync'),
+	);
+}

package/src/utils/useValueEffect.ts

@@ -0,0 +1,81 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useValueEffect.ts).
+import { useCallback, useRef, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useLayoutEffect } from './useLayoutEffect';
+
+type SetValueAction<S> = (prev: S) => Generator<any, void, unknown>;
+type Dispatch<A> = (action: A) => void;
+
+// This hook works like `useState`, but when setting the value, you pass a generator function
+// that can yield multiple values. Each yielded value updates the state and waits for the next
+// layout effect, then continues the generator. This allows sequential updates to state to be
+// written linearly.
+export function useValueEffect<S>(defaultValue: S | (() => S)): [S, Dispatch<SetValueAction<S>>];
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useValueEffect<S>(
+	defaultValue: S | (() => S),
+	slot: symbol | undefined,
+): [S, Dispatch<SetValueAction<S>>];
+export function useValueEffect(...args: any[]): any {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useValueEffect');
+	const defaultValue = user[0];
+
+	let [value, setValue] = useState(defaultValue, subSlot(slot, 'value'));
+	// Keep an up to date copy of value in a ref so we can access the current value in the generator.
+	// This allows us to maintain a stable queue function.
+	let currValue = useRef(value, subSlot(slot, 'curr'));
+	let effect = useRef<Generator<any> | null>(null, subSlot(slot, 'effect'));
+
+	// Store the function in a ref so we can always access the current version
+	// which has the proper `value` in scope.
+	let nextRef = useRef(
+		() => {
+			if (!effect.current) {
+				return;
+			}
+			// Run the generator to the next yield.
+			let newValue = effect.current.next();
+
+			// If the generator is done, reset the effect.
+			if (newValue.done) {
+				effect.current = null;
+				return;
+			}
+
+			// If the value is the same as the current value,
+			// then continue to the next yield. Otherwise,
+			// set the value in state and wait for the next layout effect.
+			if (currValue.current === newValue.value) {
+				nextRef.current();
+			} else {
+				setValue(newValue.value);
+			}
+		},
+		subSlot(slot, 'next'),
+	);
+
+	useLayoutEffect(
+		() => {
+			currValue.current = value;
+			// If there is an effect currently running, continue to the next yield.
+			if (effect.current) {
+				nextRef.current();
+			}
+		},
+		null,
+		subSlot(slot, 'advance'),
+	);
+
+	let queue = useCallback(
+		(fn: any) => {
+			effect.current = fn(currValue.current);
+			nextRef.current();
+		},
+		[nextRef],
+		subSlot(slot, 'queue'),
+	);
+
+	return [value, queue];
+}