@octanejs/aria 0.0.1 → 0.0.3

package/src/stately/collections/CollectionBuilder.ts

@@ -0,0 +1,332 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/collections/CollectionBuilder.ts).
+// octane adaptations:
+// - React.isValidElement/Fragment/Children → octane's parity helpers over element
+//   DESCRIPTORS (value-position JSX). Descriptors carry .type/.props/.key like React
+//   elements, so the walk itself is verbatim.
+// - OCTANE DIVERGENCE: literal static JSX children are a compiled children BLOCK (a
+//   render function), which cannot be statically walked — the hooks-tier builder
+//   supports dynamic collections (`items` + render function) and descriptor arrays,
+//   and rejects children blocks with a descriptive error. The RAC tier does not have
+//   this limitation. Same divergence class as radix `Slot`.
+import type { CollectionBase, Key, Node } from '@react-types/shared';
+import { Children, Fragment, isChildrenBlock, isValidElement } from 'octane';
+import type { PartialNode } from './types';
+
+type CollectionElement<T> = any;
+
+interface CollectionBuilderState {
+	renderer?: (value: any) => any;
+}
+
+export class CollectionBuilder<T extends object> {
+	private context?: unknown;
+	private cache: WeakMap<T, Node<T>> = new WeakMap();
+
+	build(props: Partial<CollectionBase<T>>, context?: unknown): Iterable<Node<T>> {
+		this.context = context;
+		return iterable(() => this.iterateCollection(props as any));
+	}
+
+	private *iterateCollection(props: { children?: any; items?: Iterable<T> }): Generator<Node<T>> {
+		let { children, items } = props;
+
+		if (isChildrenBlock(children)) {
+			throw new Error(
+				'Static JSX children are not supported by hooks-tier octane collections: octane ' +
+					'compiles children-position JSX into a render block that cannot be statically ' +
+					'walked. Pass `items` with a render function returning <Item> descriptors, or an ' +
+					'array of <Item> descriptors.',
+			);
+		}
+
+		if (isValidElement(children) && (children as any).type === Fragment) {
+			yield* this.iterateCollection({
+				children: (children as any).props.children,
+				items,
+			});
+		} else if (typeof children === 'function') {
+			if (!items) {
+				throw new Error('props.children was a function but props.items is missing');
+			}
+
+			let index = 0;
+			for (let item of items) {
+				yield* this.getFullNode(
+					{
+						value: item,
+						index,
+					},
+					{ renderer: children },
+				);
+				index++;
+			}
+		} else {
+			let items: CollectionElement<T>[] = [];
+			Children.forEach(children, (child: any) => {
+				if (child) {
+					items.push(child);
+				}
+			});
+
+			let index = 0;
+			for (let item of items) {
+				let nodes = this.getFullNode(
+					{
+						element: item,
+						index: index,
+					},
+					{},
+				);
+
+				for (let node of nodes) {
+					index++;
+					yield node;
+				}
+			}
+		}
+	}
+
+	private getKey(
+		item: NonNullable<CollectionElement<T>>,
+		partialNode: PartialNode<T>,
+		state: CollectionBuilderState,
+		parentKey?: Key | null,
+	): Key {
+		if (item.key != null) {
+			return item.key;
+		}
+
+		if (partialNode.type === 'cell' && partialNode.key != null) {
+			return `${parentKey}${partialNode.key}`;
+		}
+
+		let v = partialNode.value as any;
+		if (v != null) {
+			let key = v.key ?? v.id;
+			if (key == null) {
+				throw new Error('No key found for item');
+			}
+
+			return key;
+		}
+
+		return parentKey ? `${parentKey}.${partialNode.index}` : `$.${partialNode.index}`;
+	}
+
+	private getChildState(state: CollectionBuilderState, partialNode: PartialNode<T>) {
+		return {
+			renderer: partialNode.renderer || state.renderer,
+		};
+	}
+
+	private *getFullNode(
+		partialNode: PartialNode<T> & { index: number },
+		state: CollectionBuilderState,
+		parentKey?: Key | null,
+		parentNode?: Node<T>,
+	): Generator<Node<T>> {
+		if (isValidElement(partialNode.element) && (partialNode.element as any).type === Fragment) {
+			let children: CollectionElement<T>[] = [];
+
+			Children.forEach((partialNode.element as any).props.children, (child: any) => {
+				children.push(child);
+			});
+
+			let index = partialNode.index ?? 0;
+
+			for (const child of children) {
+				yield* this.getFullNode(
+					{
+						element: child,
+						index: index++,
+					},
+					state,
+					parentKey,
+					parentNode,
+				);
+			}
+
+			return;
+		}
+
+		// If there's a value instead of an element on the node, and a parent renderer function is available,
+		// use it to render an element for the value.
+		let element = partialNode.element;
+		if (!element && partialNode.value && state && state.renderer) {
+			let cached = this.cache.get(partialNode.value);
+			if (cached && (!cached.shouldInvalidate || !cached.shouldInvalidate(this.context))) {
+				cached.index = partialNode.index;
+				cached.parentKey = parentNode ? parentNode.key : null;
+				yield cached;
+				return;
+			}
+
+			element = state.renderer(partialNode.value);
+		}
+
+		// If there's an element with a getCollectionNode function on its type, then it's a supported component.
+		// Call this function to get a partial node, and recursively build a full node from there.
+		if (isValidElement(element)) {
+			let type = (element as any).type as any;
+			if (typeof type !== 'function' && typeof type?.getCollectionNode !== 'function') {
+				let name = (element as any).type;
+				throw new Error(`Unknown element <${name}> in collection.`);
+			}
+
+			let childNodes = type.getCollectionNode((element as any).props, this.context) as Generator<
+				PartialNode<T>,
+				void,
+				Node<T>[]
+			>;
+			let index = partialNode.index ?? 0;
+			let result = childNodes.next();
+			while (!result.done && result.value) {
+				let childNode = result.value;
+
+				partialNode.index = index;
+
+				let nodeKey = childNode.key ?? null;
+				if (nodeKey == null) {
+					nodeKey = childNode.element
+						? null
+						: this.getKey(
+								element as NonNullable<CollectionElement<T>>,
+								partialNode,
+								state,
+								parentKey,
+							);
+				}
+
+				let nodes = this.getFullNode(
+					{
+						...childNode,
+						key: nodeKey,
+						index,
+						wrapper: compose(partialNode.wrapper, childNode.wrapper),
+					},
+					this.getChildState(state, childNode),
+					parentKey ? `${parentKey}${(element as any).key}` : (element as any).key,
+					parentNode,
+				);
+
+				let children = [...nodes];
+				for (let node of children) {
+					// Cache the node based on its value
+					node.value = childNode.value ?? partialNode.value ?? null;
+					if (node.value) {
+						this.cache.set(node.value, node);
+					}
+
+					// The partial node may have specified a type for the child in order to specify a constraint.
+					// Verify that the full node that was built recursively matches this type.
+					if (partialNode.type && node.type !== partialNode.type) {
+						throw new Error(
+							`Unsupported type <${capitalize(node.type)}> in <${capitalize(parentNode?.type ?? 'unknown parent type')}>. Only <${capitalize(partialNode.type)}> is supported.`,
+						);
+					}
+
+					index++;
+					yield node;
+				}
+
+				result = childNodes.next(children);
+			}
+
+			return;
+		}
+
+		// Ignore invalid elements
+		if (partialNode.key == null || partialNode.type == null) {
+			return;
+		}
+
+		// Create full node
+		let builder = this;
+		let node: Node<T> = {
+			type: partialNode.type,
+			props: partialNode.props,
+			key: partialNode.key,
+			parentKey: parentNode ? parentNode.key : null,
+			value: partialNode.value ?? null,
+			level: (parentNode?.level ?? 0) + (parentNode?.type === 'item' ? 1 : 0),
+			index: partialNode.index,
+			rendered: partialNode.rendered,
+			textValue: partialNode.textValue ?? '',
+			'aria-label': partialNode['aria-label'],
+			wrapper: partialNode.wrapper,
+			shouldInvalidate: partialNode.shouldInvalidate,
+			hasChildNodes: partialNode.hasChildNodes || false,
+			childNodes: iterable(function* () {
+				if (!partialNode.hasChildNodes || !partialNode.childNodes) {
+					return;
+				}
+
+				let index = 0;
+				for (let child of partialNode.childNodes()) {
+					// Ensure child keys are globally unique by prepending the parent node's key
+					if (child.key != null) {
+						// TODO: Remove this line entirely and enforce that users always provide unique keys.
+						// Currently this line will have issues when a parent has a key `a` and a child with key `bc`
+						// but another parent has key `ab` and its child has a key `c`. The combined keys would result in both
+						// children having a key of `abc`.
+						child.key = `${node.key}${child.key}`;
+					}
+
+					let nodes = builder.getFullNode(
+						{ ...child, index },
+						builder.getChildState(state, child),
+						node.key,
+						node,
+					);
+					for (let node of nodes) {
+						index++;
+						yield node;
+					}
+				}
+			}),
+		};
+
+		yield node;
+	}
+}
+
+// Wraps an iterator function as an iterable object, and caches the results.
+function iterable<T>(iterator: () => IterableIterator<Node<T>>): Iterable<Node<T>> {
+	let cache: Array<Node<T>> = [];
+	let iterable: null | IterableIterator<Node<T>> = null;
+	return {
+		*[Symbol.iterator]() {
+			for (let item of cache) {
+				yield item;
+			}
+
+			if (!iterable) {
+				iterable = iterator();
+			}
+
+			for (let item of iterable) {
+				cache.push(item);
+				yield item;
+			}
+		},
+	};
+}
+
+type Wrapper = (element: any) => any;
+function compose(outer: Wrapper | void, inner: Wrapper | void): Wrapper | undefined {
+	if (outer && inner) {
+		return (element) => outer(inner(element));
+	}
+
+	if (outer) {
+		return outer;
+	}
+
+	if (inner) {
+		return inner;
+	}
+}
+
+function capitalize(str: string) {
+	return str[0].toUpperCase() + str.slice(1);
+}

package/src/stately/collections/Item.ts

@@ -0,0 +1,78 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/collections/Item.ts).
+// octane adaptations: React.Children → octane Children (descriptor arrays); element
+// types → `any` descriptors. `<Item>` is a collection DESCRIPTOR component — it renders
+// nothing; CollectionBuilder walks it via the static `getCollectionNode` generator.
+import type { ItemProps } from '@react-types/shared';
+import { Children } from 'octane';
+import type { PartialNode } from './types';
+
+function Item<T>(props: ItemProps<T>): any {
+	return null;
+}
+
+Item.getCollectionNode = function* getCollectionNode<T>(
+	props: ItemProps<T>,
+	context: any,
+): Generator<PartialNode<T>> {
+	let { childItems, title, children } = props;
+
+	let rendered = props.title || props.children;
+	let textValue =
+		props.textValue || (typeof rendered === 'string' ? rendered : '') || props['aria-label'] || '';
+
+	// suppressTextValueWarning is used in components like Tabs, which don't have type to select support.
+	if (!textValue && !context?.suppressTextValueWarning && process.env.NODE_ENV !== 'production') {
+		console.warn(
+			'<Item> with non-plain text contents is unsupported by type to select for accessibility. Please add a `textValue` prop.',
+		);
+	}
+
+	yield {
+		type: 'item',
+		props: props,
+		rendered,
+		textValue,
+		'aria-label': props['aria-label'],
+		hasChildNodes: hasChildItems(props),
+		*childNodes() {
+			if (childItems) {
+				for (let child of childItems) {
+					yield {
+						type: 'item',
+						value: child,
+					};
+				}
+			} else if (title) {
+				let items: PartialNode<T>[] = [];
+				Children.forEach(children as any, (child: any) => {
+					items.push({
+						type: 'item',
+						element: child,
+					});
+				});
+
+				yield* items;
+			}
+		},
+	};
+};
+
+function hasChildItems<T>(props: ItemProps<T>) {
+	if (props.hasChildItems != null) {
+		return props.hasChildItems;
+	}
+
+	if (props.childItems) {
+		return true;
+	}
+
+	if (props.title && Children.count(props.children as any) > 0) {
+		return true;
+	}
+
+	return false;
+}
+
+// We don't want getCollectionNode to show up in the type definition
+let _Item = Item as unknown as <T>(props: ItemProps<T>) => any;
+export { _Item as Item };

package/src/stately/collections/Section.ts

@@ -0,0 +1,52 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/collections/Section.ts).
+// octane adaptations: React.Children → octane Children (descriptor arrays); element
+// types → `any` descriptors. Renders nothing; walked via static `getCollectionNode`.
+import type { SectionProps } from '@react-types/shared';
+import { Children } from 'octane';
+import type { PartialNode } from './types';
+
+function Section<T>(props: SectionProps<T>): any {
+	return null;
+}
+
+Section.getCollectionNode = function* getCollectionNode<T>(
+	props: SectionProps<T>,
+): Generator<PartialNode<T>> {
+	let { children, title, items } = props;
+	yield {
+		type: 'section',
+		props: props,
+		hasChildNodes: true,
+		rendered: title,
+		'aria-label': props['aria-label'],
+		*childNodes() {
+			if (typeof children === 'function') {
+				if (!items) {
+					throw new Error('props.children was a function but props.items is missing');
+				}
+
+				for (let item of items) {
+					yield {
+						type: 'item',
+						value: item,
+						renderer: children,
+					};
+				}
+			} else {
+				let items: PartialNode<T>[] = [];
+				Children.forEach(children as any, (child: any) => {
+					items.push({
+						type: 'item',
+						element: child,
+					});
+				});
+
+				yield* items;
+			}
+		},
+	};
+};
+
+// We don't want getCollectionNode to show up in the type definition
+let _Section = Section as unknown as <T>(props: SectionProps<T>) => any;
+export { _Section as Section };

package/src/stately/collections/getChildNodes.ts

@@ -0,0 +1,94 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/collections/getChildNodes.ts).
+// Verbatim (no React surface).
+import type { Collection, Node } from '@react-types/shared';
+
+export function getChildNodes<T>(
+	node: Node<T>,
+	collection: Collection<Node<T>>,
+): Iterable<Node<T>> {
+	// New API: call collection.getChildren with the node key.
+	if (typeof collection.getChildren === 'function') {
+		return collection.getChildren(node.key);
+	}
+
+	// Old API: access childNodes directly.
+	return node.childNodes;
+}
+
+export function getFirstItem<T>(iterable: Iterable<T>): T | undefined {
+	return getNthItem(iterable, 0);
+}
+
+export function getNthItem<T>(iterable: Iterable<T>, index: number): T | undefined {
+	if (index < 0) {
+		return undefined;
+	}
+
+	let i = 0;
+	for (let item of iterable) {
+		if (i === index) {
+			return item;
+		}
+
+		i++;
+	}
+}
+
+export function getLastItem<T>(iterable: Iterable<T>): T | undefined {
+	let lastItem: T | undefined = undefined;
+	for (let value of iterable) {
+		lastItem = value;
+	}
+
+	return lastItem;
+}
+
+export function compareNodeOrder<T>(
+	collection: Collection<Node<T>>,
+	a: Node<T>,
+	b: Node<T>,
+): number {
+	// If the two nodes have the same parent, compare their indices.
+	if (a.parentKey === b.parentKey) {
+		return a.index - b.index;
+	}
+
+	// Otherwise, collect all of the ancestors from each node, and find the first one that doesn't match starting from the root.
+	// Include the base nodes in case we are comparing nodes of different levels so that we can compare the higher node to the lower level node's
+	// ancestor of the same level
+	let aAncestors = [...getAncestors(collection, a), a];
+	let bAncestors = [...getAncestors(collection, b), b];
+	let firstNonMatchingAncestor = aAncestors
+		.slice(0, bAncestors.length)
+		.findIndex((a, i) => a !== bAncestors[i]);
+	if (firstNonMatchingAncestor !== -1) {
+		// Compare the indices of two children within the common ancestor.
+		a = aAncestors[firstNonMatchingAncestor];
+		b = bAncestors[firstNonMatchingAncestor];
+		return a.index - b.index;
+	}
+
+	// If there isn't a non matching ancestor, we might be in a case where one of the nodes is the ancestor of the other.
+	if (aAncestors.findIndex((node) => node === b) >= 0) {
+		return 1;
+	} else if (bAncestors.findIndex((node) => node === a) >= 0) {
+		return -1;
+	}
+
+	// 🤷
+	return -1;
+}
+
+function getAncestors<T>(collection: Collection<Node<T>>, node: Node<T>): Node<T>[] {
+	let parents: Node<T>[] = [];
+
+	let currNode: Node<T> | null = node;
+	while (currNode?.parentKey != null) {
+		currNode = collection.getItem(currNode.parentKey);
+		if (currNode) {
+			parents.unshift(currNode);
+		}
+	}
+
+	return parents;
+}

package/src/stately/collections/getItemCount.ts

@@ -0,0 +1,29 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/collections/getItemCount.ts).
+// Verbatim (no React surface).
+import type { Collection, Node } from '@react-types/shared';
+import { getChildNodes } from './getChildNodes';
+
+const cache = new WeakMap<Iterable<unknown>, number>();
+
+export function getItemCount<T>(collection: Collection<Node<T>>): number {
+	let count = cache.get(collection);
+	if (count != null) {
+		return count;
+	}
+
+	// TS isn't smart enough to know we've ensured count is a number, so use a new variable
+	let counter = 0;
+	let countItems = (items: Iterable<Node<T>>) => {
+		for (let item of items) {
+			if (item.type === 'section') {
+				countItems(getChildNodes(item, collection));
+			} else if (item.type === 'item') {
+				counter++;
+			}
+		}
+	};
+
+	countItems(collection);
+	cache.set(collection, counter);
+	return counter;
+}

package/src/stately/collections/types.ts

@@ -0,0 +1,20 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/collections/types.ts).
+// octane adaptations: React element types → `any` (octane element descriptors).
+import type { Key } from '@react-types/shared';
+
+export interface PartialNode<T> {
+	type?: string;
+	key?: Key | null;
+	value?: T;
+	element?: any;
+	wrapper?: (element: any) => any;
+	rendered?: any;
+	textValue?: string;
+	'aria-label'?: string;
+	index?: number;
+	renderer?: (item: T) => any;
+	hasChildNodes?: boolean;
+	childNodes?: () => IterableIterator<PartialNode<T>>;
+	props?: any;
+	shouldInvalidate?: (context: any) => boolean;
+}

package/src/stately/collections/useCollection.ts

@@ -0,0 +1,54 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/collections/useCollection.ts).
+// octane adaptations: React element types → `any` descriptors; public-hook slot
+// threading; explicit dependency arrays kept verbatim.
+import type { Collection, CollectionStateBase, Node } from '@react-types/shared';
+import { useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { CollectionBuilder } from './CollectionBuilder';
+
+interface CollectionOptions<T, C extends Collection<Node<T>>> extends Omit<
+	CollectionStateBase<T, C>,
+	'children'
+> {
+	children?: any;
+}
+
+type CollectionFactory<T, C extends Collection<Node<T>>> = (node: Iterable<Node<T>>) => C;
+
+export function useCollection<
+	T extends object,
+	C extends Collection<Node<T>> = Collection<Node<T>>,
+>(props: CollectionOptions<T, C>, factory: CollectionFactory<T, C>, context?: unknown): C;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useCollection<
+	T extends object,
+	C extends Collection<Node<T>> = Collection<Node<T>>,
+>(
+	props: CollectionOptions<T, C>,
+	factory: CollectionFactory<T, C>,
+	context: unknown,
+	slot: symbol | undefined,
+): C;
+export function useCollection(...args: any[]): any {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useCollection');
+	const props = user[0] as CollectionOptions<any, any>;
+	const factory = user[1] as CollectionFactory<any, any>;
+	const context = user[2];
+
+	let builder = useMemo(() => new CollectionBuilder<any>(), [], subSlot(slot, 'builder'));
+	let { children, items, collection } = props as any;
+	let result = useMemo(
+		() => {
+			if (collection) {
+				return collection;
+			}
+			let nodes = builder.build({ children, items }, context);
+			return factory(nodes);
+		},
+		[builder, children, items, collection, context, factory],
+		subSlot(slot, 'collection'),
+	);
+	return result;
+}