@octanejs/aria 0.0.1 → 0.0.3

package/src/stately/tabs/useTabListState.ts

@@ -0,0 +1,149 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/tabs/useTabListState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; upstream's intentionally dep-less useEffect becomes an explicit `null`
+// (run after every render).
+import type {
+	Collection,
+	CollectionBase,
+	CollectionStateBase,
+	Key,
+	Node,
+	SingleSelection,
+} from '@react-types/shared';
+import { useEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import {
+	type SingleSelectListState,
+	useSingleSelectListState,
+} from '../list/useSingleSelectListState';
+
+export interface TabListProps<T>
+	extends
+		CollectionBase<T>,
+		Omit<
+			SingleSelection,
+			'disallowEmptySelection' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange'
+		> {
+	/**
+	 * Whether the TabList is disabled.
+	 * Shows that a selection exists, but is not available in that circumstance.
+	 */
+	isDisabled?: boolean;
+	/** The currently selected key in the collection (controlled). */
+	selectedKey?: Key;
+	/** The initial selected keys in the collection (uncontrolled). */
+	defaultSelectedKey?: Key;
+	/** Handler that is called when the selection changes. */
+	onSelectionChange?: (key: Key) => void;
+}
+
+export interface TabListStateOptions<T>
+	extends Omit<TabListProps<T>, 'children'>, CollectionStateBase<T> {}
+
+export interface TabListState<T> extends SingleSelectListState<T> {
+	/** Whether the tab list is disabled. */
+	isDisabled: boolean;
+}
+
+/**
+ * Provides state management for a Tabs component. Tabs include a TabList which tracks
+ * which tab is currently selected and displays the content associated with that Tab in a TabPanel.
+ */
+export function useTabListState<T extends object>(props: TabListStateOptions<T>): TabListState<T>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTabListState<T extends object>(
+	props: TabListStateOptions<T>,
+	slot: symbol | undefined,
+): TabListState<T>;
+export function useTabListState(...args: any[]): TabListState<any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTabListState');
+	const props = user[0] as TabListStateOptions<any>;
+
+	let state = useSingleSelectListState<any>(
+		{
+			...props,
+			onSelectionChange: props.onSelectionChange
+				? (key: Key | null) => {
+						if (key != null) {
+							props.onSelectionChange?.(key);
+						}
+					}
+				: undefined,
+			suppressTextValueWarning: true,
+			defaultSelectedKey:
+				props.defaultSelectedKey ??
+				findDefaultSelectedKey(
+					props.collection,
+					props.disabledKeys ? new Set(props.disabledKeys) : new Set(),
+				) ??
+				undefined,
+		},
+		subSlot(slot, 'list'),
+	);
+
+	let { selectionManager, collection, selectedKey: currentSelectedKey } = state;
+
+	let lastSelectedKey = useRef(currentSelectedKey, subSlot(slot, 'lastSelected'));
+	useEffect(
+		() => {
+			// Ensure a tab is always selected (in case no selected key was specified or if selected item was deleted from collection)
+			let selectedKey = currentSelectedKey;
+			if (
+				props.selectedKey == null &&
+				(selectionManager.isEmpty || selectedKey == null || !collection.getItem(selectedKey))
+			) {
+				selectedKey = findDefaultSelectedKey(collection, state.disabledKeys);
+				if (selectedKey != null) {
+					// directly set selection because replace/toggle selection won't consider disabled keys
+					selectionManager.setSelectedKeys([selectedKey]);
+				}
+			}
+
+			// If the tablist doesn't have focus and the selected key changes or if there isn't a focused key yet, change focused key to the selected key if it exists.
+			if (
+				(selectedKey != null && selectionManager.focusedKey == null) ||
+				(!selectionManager.isFocused && selectedKey !== lastSelectedKey.current)
+			) {
+				selectionManager.setFocusedKey(selectedKey);
+			}
+			lastSelectedKey.current = selectedKey;
+		},
+		null,
+		subSlot(slot, 'ensureSelected'),
+	);
+
+	return {
+		...state,
+		isDisabled: props.isDisabled || false,
+	};
+}
+
+function findDefaultSelectedKey<T>(
+	collection: Collection<Node<T>> | undefined,
+	disabledKeys: Set<Key>,
+) {
+	let selectedKey: Key | null = null;
+	if (collection) {
+		selectedKey = collection.getFirstKey();
+		// loop over tabs until we find one that isn't disabled and select that
+		while (
+			selectedKey != null &&
+			(disabledKeys.has(selectedKey) || collection.getItem(selectedKey)?.props?.isDisabled) &&
+			selectedKey !== collection.getLastKey()
+		) {
+			selectedKey = collection.getKeyAfter(selectedKey);
+		}
+		// if this check is true, then every item is disabled, it makes more sense to default to the first key than the last
+		if (
+			selectedKey != null &&
+			(disabledKeys.has(selectedKey) || collection.getItem(selectedKey)?.props?.isDisabled) &&
+			selectedKey === collection.getLastKey()
+		) {
+			selectedKey = collection.getFirstKey();
+		}
+	}
+
+	return selectedKey;
+}

package/src/stately/toggle/useToggleGroupState.ts

@@ -0,0 +1,109 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/toggle/useToggleGroupState.ts).
+// Its import closure is confined to `useControlledState` + `@react-types/shared` (no
+// list/selection modules), so it lands in Phase 1. octane adaptations: public-hook slot
+// threading (splitSlot/subSlot) per the binding convention; explicit `Set<Key>` element
+// types on the default-set constructions (strict inference); explicit useMemo dep arrays
+// preserved exactly.
+import type { Key } from '@react-types/shared';
+import { useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { useControlledState } from '../utils/useControlledState';
+
+export interface ToggleGroupProps {
+	/**
+	 * Whether single or multiple selection is enabled.
+	 *
+	 * @default 'single'
+	 */
+	selectionMode?: 'single' | 'multiple';
+	/** Whether the collection allows empty selection. */
+	disallowEmptySelection?: boolean;
+	/** The currently selected keys in the collection (controlled). */
+	selectedKeys?: Iterable<Key>;
+	/** The initial selected keys in the collection (uncontrolled). */
+	defaultSelectedKeys?: Iterable<Key>;
+	/** Handler that is called when the selection changes. */
+	onSelectionChange?: (keys: Set<Key>) => void;
+	/** Whether all items are disabled. */
+	isDisabled?: boolean;
+}
+
+export interface ToggleGroupState {
+	/** Whether single or multiple selection is enabled. */
+	readonly selectionMode: 'single' | 'multiple';
+
+	/** Whether all items are disabled. */
+	readonly isDisabled: boolean;
+
+	/** A set of keys for items that are selected. */
+	readonly selectedKeys: Set<Key>;
+
+	/** Toggles the selected state for an item by its key. */
+	toggleKey(key: Key): void;
+
+	/** Sets whether the given key is selected. */
+	setSelected(key: Key, isSelected: boolean): void;
+
+	/** Replaces the set of selected keys. */
+	setSelectedKeys(keys: Set<Key>): void;
+}
+
+/**
+ * Manages state for a group of toggles.
+ * It supports both single and multiple selected items.
+ */
+export function useToggleGroupState(props: ToggleGroupProps): ToggleGroupState;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useToggleGroupState(
+	props: ToggleGroupProps,
+	slot: symbol | undefined,
+): ToggleGroupState;
+export function useToggleGroupState(...args: any[]): ToggleGroupState {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useToggleGroupState');
+	const props = user[0] as ToggleGroupProps;
+
+	let { selectionMode = 'single', disallowEmptySelection, isDisabled = false } = props;
+	let [selectedKeys, setSelectedKeys] = useControlledState(
+		useMemo(
+			() => (props.selectedKeys ? new Set(props.selectedKeys) : undefined),
+			[props.selectedKeys],
+			subSlot(slot, 'controlled'),
+		),
+		useMemo(
+			() => (props.defaultSelectedKeys ? new Set(props.defaultSelectedKeys) : new Set<Key>()),
+			[props.defaultSelectedKeys],
+			subSlot(slot, 'default'),
+		),
+		props.onSelectionChange,
+		subSlot(slot, 'keys'),
+	);
+
+	return {
+		selectionMode,
+		isDisabled,
+		selectedKeys,
+		setSelectedKeys,
+		toggleKey(key) {
+			let keys: Set<Key>;
+			if (selectionMode === 'multiple') {
+				keys = new Set(selectedKeys);
+				if (keys.has(key) && (!disallowEmptySelection || keys.size > 1)) {
+					keys.delete(key);
+				} else {
+					keys.add(key);
+				}
+			} else {
+				keys = new Set(selectedKeys.has(key) && !disallowEmptySelection ? [] : [key]);
+			}
+
+			setSelectedKeys(keys);
+		},
+		setSelected(key, isSelected) {
+			if (isSelected !== selectedKeys.has(key)) {
+				this.toggleKey(key);
+			}
+		},
+	};
+}

package/src/stately/toggle/useToggleState.ts

@@ -0,0 +1,100 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/toggle/useToggleState.ts).
+// octane adaptations: React's `ReactNode` children type → `any` (octane descriptors);
+// `FocusableProps` comes from the ported interactions area (type-only — upstream's
+// @react-types/shared version is typed over React synthetic events); public-hook slot
+// threading (splitSlot/subSlot) per the binding convention. The public value-level
+// `onChange` callback is unchanged (the onInput rule applies only to DOM wiring).
+import type { InputBase, Validation } from '@react-types/shared';
+import { useState } from 'octane';
+
+import type { FocusableProps } from '../../interactions/useFocusable';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { useControlledState } from '../utils/useControlledState';
+
+export interface ToggleStateOptions extends InputBase {
+	/**
+	 * Whether the element should be selected (uncontrolled).
+	 */
+	defaultSelected?: boolean;
+	/**
+	 * Whether the element should be selected (controlled).
+	 */
+	isSelected?: boolean;
+	/**
+	 * Handler that is called when the element's selection state changes.
+	 */
+	onChange?: (isSelected: boolean) => void;
+}
+
+export interface ToggleProps extends ToggleStateOptions, Validation<boolean>, FocusableProps {
+	/**
+	 * The label for the element.
+	 */
+	children?: any;
+	/**
+	 * The value of the input element, used when submitting an HTML form. See
+	 * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefvalue).
+	 */
+	value?: string;
+}
+
+export interface ToggleState {
+	/** Whether the toggle is selected. */
+	readonly isSelected: boolean;
+
+	/** Whether the toggle is selected by default. */
+	readonly defaultSelected: boolean;
+
+	/** Updates selection state. */
+	setSelected(isSelected: boolean): void;
+
+	/** Toggle the selection state. */
+	toggle(): void;
+}
+
+/**
+ * Provides state management for toggle components like checkboxes and switches.
+ */
+export function useToggleState(props?: ToggleStateOptions): ToggleState;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useToggleState(
+	props: ToggleStateOptions | undefined,
+	slot: symbol | undefined,
+): ToggleState;
+export function useToggleState(...args: any[]): ToggleState {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useToggleState');
+	const props = (user[0] as ToggleStateOptions | undefined) ?? {};
+
+	let { isReadOnly } = props;
+
+	// have to provide an empty function so useControlledState doesn't throw a fit
+	// can't use useControlledState's prop calling because we need the event object from the change
+	let [isSelected, setSelected] = useControlledState(
+		props.isSelected,
+		props.defaultSelected || false,
+		props.onChange,
+		subSlot(slot, 'selected'),
+	);
+	let [initialValue] = useState(isSelected, subSlot(slot, 'initial'));
+
+	function updateSelected(value: boolean) {
+		if (!isReadOnly) {
+			setSelected(value);
+		}
+	}
+
+	function toggleState() {
+		if (!isReadOnly) {
+			setSelected(!isSelected);
+		}
+	}
+
+	return {
+		isSelected,
+		defaultSelected: props.defaultSelected ?? initialValue,
+		setSelected: updateSelected,
+		toggle: toggleState,
+	};
+}

package/src/stately/tooltip/useTooltipTriggerState.ts

@@ -0,0 +1,218 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/tooltip/useTooltipTriggerState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; the module-level warmup/cooldown timers and global tooltip registry are
+// ported verbatim; upstream's explicit useEffect dep arrays are kept verbatim with a
+// trailing subSlot.
+import { useEffect, useMemo, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import {
+	type OverlayTriggerProps,
+	useOverlayTriggerState,
+} from '../overlays/useOverlayTriggerState';
+
+export interface TooltipTriggerProps extends OverlayTriggerProps {
+	/**
+	 * Whether the tooltip should be disabled, independent from the trigger.
+	 */
+	isDisabled?: boolean;
+
+	/**
+	 * The delay time for the tooltip to show up. [See
+	 * guidelines](https://spectrum.adobe.com/page/tooltip/#Immediate-or-delayed-appearance).
+	 *
+	 * @default 1500
+	 */
+	delay?: number;
+
+	/**
+	 * The delay time for the tooltip to close. [See
+	 * guidelines](https://spectrum.adobe.com/page/tooltip/#Warmup-and-cooldown).
+	 *
+	 * @default 500
+	 */
+	closeDelay?: number;
+
+	/**
+	 * By default, opens for both focus and hover. Can be made to open only for focus.
+	 *
+	 * @default 'hover'
+	 */
+	trigger?: 'hover' | 'focus';
+
+	/**
+	 * Whether the tooltip should close when the trigger is pressed.
+	 *
+	 * @default true
+	 */
+	shouldCloseOnPress?: boolean;
+}
+
+const TOOLTIP_DELAY = 1500; // this seems to be a 1.5 second delay, check with design
+const TOOLTIP_COOLDOWN = 500;
+
+export interface TooltipTriggerState {
+	/** Whether the tooltip is currently showing. */
+	isOpen: boolean;
+	/**
+	 * Shows the tooltip. By default, the tooltip becomes visible after a delay
+	 * depending on a global warmup timer. The `immediate` option shows the
+	 * tooltip immediately instead.
+	 */
+	open(immediate?: boolean): void;
+	/** Hides the tooltip. */
+	close(immediate?: boolean): void;
+}
+
+// octane adaptation: loose index type (upstream's `{}`) so the cleanup's truthiness
+// check on a registry entry isn't flagged as an always-defined function.
+let tooltips: Record<string, any> = {};
+let tooltipId = 0;
+let globalWarmedUp = false;
+let globalWarmUpTimeout: ReturnType<typeof setTimeout> | null = null;
+let globalCooldownTimeout: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * Manages state for a tooltip trigger. Tracks whether the tooltip is open, and provides
+ * methods to toggle this state. Ensures only one tooltip is open at a time and controls
+ * the delay for showing a tooltip.
+ */
+export function useTooltipTriggerState(props?: TooltipTriggerProps): TooltipTriggerState;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTooltipTriggerState(
+	props: TooltipTriggerProps | undefined,
+	slot: symbol | undefined,
+): TooltipTriggerState;
+export function useTooltipTriggerState(...args: any[]): TooltipTriggerState {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTooltipTriggerState');
+	const props = (user[0] as TooltipTriggerProps) ?? {};
+
+	let { delay = TOOLTIP_DELAY, closeDelay = TOOLTIP_COOLDOWN } = props;
+	let { isOpen, open, close } = useOverlayTriggerState(props, subSlot(slot, 'overlay'));
+	let id = useMemo(() => `${++tooltipId}`, [], subSlot(slot, 'id'));
+	let closeTimeout = useRef<ReturnType<typeof setTimeout> | null>(
+		null,
+		subSlot(slot, 'closeTimeout'),
+	);
+	let closeCallback = useRef<() => void>(close, subSlot(slot, 'closeCallback'));
+
+	let ensureTooltipEntry = () => {
+		tooltips[id] = hideTooltip;
+	};
+
+	let closeOpenTooltips = () => {
+		for (let hideTooltipId in tooltips) {
+			if (hideTooltipId !== id) {
+				tooltips[hideTooltipId](true);
+				delete tooltips[hideTooltipId];
+			}
+		}
+	};
+
+	let showTooltip = () => {
+		if (closeTimeout.current) {
+			clearTimeout(closeTimeout.current);
+		}
+		closeTimeout.current = null;
+		closeOpenTooltips();
+		ensureTooltipEntry();
+		globalWarmedUp = true;
+		open();
+		if (globalWarmUpTimeout) {
+			clearTimeout(globalWarmUpTimeout);
+			globalWarmUpTimeout = null;
+		}
+		if (globalCooldownTimeout) {
+			clearTimeout(globalCooldownTimeout);
+			globalCooldownTimeout = null;
+		}
+	};
+
+	let hideTooltip = (immediate?: boolean) => {
+		if (immediate || closeDelay <= 0) {
+			if (closeTimeout.current) {
+				clearTimeout(closeTimeout.current);
+			}
+			closeTimeout.current = null;
+			closeCallback.current();
+		} else if (!closeTimeout.current) {
+			closeTimeout.current = setTimeout(() => {
+				closeTimeout.current = null;
+				closeCallback.current();
+			}, closeDelay);
+		}
+
+		if (globalWarmUpTimeout) {
+			clearTimeout(globalWarmUpTimeout);
+			globalWarmUpTimeout = null;
+		}
+		if (globalWarmedUp) {
+			if (globalCooldownTimeout) {
+				clearTimeout(globalCooldownTimeout);
+			}
+			globalCooldownTimeout = setTimeout(
+				() => {
+					delete tooltips[id];
+					globalCooldownTimeout = null;
+					globalWarmedUp = false;
+				},
+				Math.max(TOOLTIP_COOLDOWN, closeDelay),
+			);
+		}
+	};
+
+	let warmupTooltip = () => {
+		closeOpenTooltips();
+		ensureTooltipEntry();
+		if (!isOpen && !globalWarmedUp) {
+			if (globalWarmUpTimeout) {
+				clearTimeout(globalWarmUpTimeout);
+			}
+
+			globalWarmUpTimeout = setTimeout(() => {
+				globalWarmUpTimeout = null;
+				globalWarmedUp = true;
+				showTooltip();
+			}, delay);
+		} else if (!isOpen) {
+			showTooltip();
+		}
+	};
+
+	useEffect(
+		() => {
+			closeCallback.current = close;
+		},
+		[close],
+		subSlot(slot, 'closeCallback'),
+	);
+
+	useEffect(
+		() => {
+			return () => {
+				if (closeTimeout.current) {
+					clearTimeout(closeTimeout.current);
+				}
+				let tooltip = tooltips[id];
+				if (tooltip) {
+					delete tooltips[id];
+				}
+			};
+		},
+		[id],
+		subSlot(slot, 'cleanup'),
+	);
+
+	return {
+		isOpen,
+		open: (immediate) => {
+			if (!immediate && delay > 0 && !closeTimeout.current) {
+				warmupTooltip();
+			} else {
+				showTooltip();
+			}
+		},
+		close: hideTooltip,
+	};
+}

package/src/stately/tree/TreeCollection.ts

@@ -0,0 +1,92 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/tree/TreeCollection.ts).
+// Verbatim (no React surface).
+import type { Collection, Key, Node } from '@react-types/shared';
+
+export class TreeCollection<T> implements Collection<Node<T>> {
+	private keyMap: Map<Key, Node<T>> = new Map();
+	private iterable: Iterable<Node<T>>;
+	private firstKey: Key | null = null;
+	private lastKey: Key | null = null;
+
+	constructor(nodes: Iterable<Node<T>>, { expandedKeys }: { expandedKeys?: Set<Key> } = {}) {
+		this.iterable = nodes;
+		expandedKeys = expandedKeys || new Set();
+
+		let visit = (node: Node<T>) => {
+			this.keyMap.set(node.key, node);
+
+			if (node.childNodes && (node.type === 'section' || expandedKeys.has(node.key))) {
+				for (let child of node.childNodes) {
+					visit(child);
+				}
+			}
+		};
+
+		for (let node of nodes) {
+			visit(node);
+		}
+
+		let last: Node<T> | null = null;
+		let index = 0;
+		for (let [key, node] of this.keyMap) {
+			if (last) {
+				last.nextKey = key;
+				node.prevKey = last.key;
+			} else {
+				this.firstKey = key;
+				node.prevKey = undefined;
+			}
+
+			if (node.type === 'item') {
+				node.index = index++;
+			}
+
+			last = node;
+
+			// Set nextKey as undefined since this might be the last node
+			// If it isn't the last node, last.nextKey will properly set at start of new loop
+			last.nextKey = undefined;
+		}
+
+		this.lastKey = last?.key ?? null;
+	}
+
+	*[Symbol.iterator](): IterableIterator<Node<T>> {
+		yield* this.iterable;
+	}
+
+	get size(): number {
+		return this.keyMap.size;
+	}
+
+	getKeys(): IterableIterator<Key> {
+		return this.keyMap.keys();
+	}
+
+	getKeyBefore(key: Key): Key | null {
+		let node = this.keyMap.get(key);
+		return node ? (node.prevKey ?? null) : null;
+	}
+
+	getKeyAfter(key: Key): Key | null {
+		let node = this.keyMap.get(key);
+		return node ? (node.nextKey ?? null) : null;
+	}
+
+	getFirstKey(): Key | null {
+		return this.firstKey;
+	}
+
+	getLastKey(): Key | null {
+		return this.lastKey;
+	}
+
+	getItem(key: Key): Node<T> | null {
+		return this.keyMap.get(key) ?? null;
+	}
+
+	at(idx: number): Node<T> | null {
+		const keys = [...this.getKeys()];
+		return this.getItem(keys[idx]);
+	}
+}