ropav 0.2.0 → 0.3.0

package/dist/utils/position.js

@@ -0,0 +1,306 @@
+//#region src/utils/position.ts
+var AXIS = {
+	bottom: "top",
+	left: "left",
+	right: "left",
+	top: "top"
+};
+var FLIPPED_DIRECTION = {
+	bottom: "top",
+	left: "right",
+	right: "left",
+	top: "bottom"
+};
+var CROSS_AXIS = {
+	left: "top",
+	top: "left"
+};
+var AXIS_SIZE = {
+	left: "width",
+	top: "height"
+};
+var TOTAL_SIZE = {
+	height: "totalHeight",
+	width: "totalWidth"
+};
+var clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+var getVisualViewport = () => typeof document === "undefined" ? null : window.visualViewport;
+/** Whether one node is the other, or contains it. */
+var nodeContains = (node, other) => Boolean(node && other && node.contains(other));
+var isWebKit = () => typeof navigator !== "undefined" && /AppleWebKit/.test(navigator.userAgent) && !/Chrome/.test(navigator.userAgent);
+/** The element's rectangle, ignoring any scale transform when asked. */
+var getRect = (node, ignoreScale) => {
+	let { height, width } = node.getBoundingClientRect();
+	const { left, top } = node.getBoundingClientRect();
+	if (ignoreScale && node instanceof HTMLElement) {
+		width = node.offsetWidth;
+		height = node.offsetHeight;
+	}
+	return {
+		height,
+		left,
+		top,
+		width
+	};
+};
+var getOffset = (node, ignoreScale, overrideRect) => {
+	const { height, left, top, width } = overrideRect ?? getRect(node, ignoreScale);
+	const { clientLeft, clientTop, scrollLeft, scrollTop } = document.documentElement;
+	return {
+		height,
+		left: left + scrollLeft - clientLeft,
+		top: top + scrollTop - clientTop,
+		width
+	};
+};
+var getPosition = (node, parent, ignoreScale, overrideRect) => {
+	const style = window.getComputedStyle(node);
+	let offset;
+	if (style.position === "fixed") offset = overrideRect ?? getRect(node, ignoreScale);
+	else {
+		offset = getOffset(node, ignoreScale, overrideRect);
+		const parentOffset = getOffset(parent, ignoreScale);
+		const parentStyle = window.getComputedStyle(parent);
+		parentOffset.top += (parseInt(parentStyle.borderTopWidth, 10) || 0) - parent.scrollTop;
+		parentOffset.left += (parseInt(parentStyle.borderLeftWidth, 10) || 0) - parent.scrollLeft;
+		offset.top -= parentOffset.top;
+		offset.left -= parentOffset.left;
+	}
+	offset.top -= parseInt(style.marginTop, 10) || 0;
+	offset.left -= parseInt(style.marginLeft, 10) || 0;
+	return offset;
+};
+/**
+* Whether the element establishes a containing block, which an absolutely positioned
+* descendant is placed relative to even when the element itself is not positioned.
+*/
+var isContainingBlock = (node) => {
+	const style = window.getComputedStyle(node);
+	return style.transform !== "none" || /transform|perspective/.test(style.willChange) || style.filter !== "none" || style.contain === "paint" || "backdropFilter" in style && style.backdropFilter !== "none";
+};
+/** The element an absolutely positioned overlay is placed relative to. */
+var getContainingBlock = (node) => {
+	let offsetParent = node.offsetParent;
+	if (offsetParent && offsetParent === document.body && window.getComputedStyle(offsetParent).position === "static" && !isContainingBlock(offsetParent)) offsetParent = document.documentElement;
+	if (offsetParent == null) {
+		let candidate = node.parentElement;
+		while (candidate && !isContainingBlock(candidate)) candidate = candidate.parentElement;
+		return candidate ?? document.documentElement;
+	}
+	return offsetParent;
+};
+var getContainerDimensions = (containerNode, visualViewport) => {
+	let width = 0;
+	let height = 0;
+	let totalWidth = 0;
+	let totalHeight = 0;
+	let top = 0;
+	let left = 0;
+	const scroll = {};
+	const isPinchZoomedIn = (visualViewport?.scale ?? 1) > 1;
+	if (containerNode.tagName === "BODY" || containerNode.tagName === "HTML") {
+		const documentElement = document.documentElement;
+		totalWidth = documentElement.clientWidth;
+		totalHeight = documentElement.clientHeight;
+		width = visualViewport?.width ?? totalWidth;
+		height = visualViewport?.height ?? totalHeight;
+		scroll.top = documentElement.scrollTop || containerNode.scrollTop;
+		scroll.left = documentElement.scrollLeft || containerNode.scrollLeft;
+		if (visualViewport) {
+			top = visualViewport.offsetTop;
+			left = visualViewport.offsetLeft;
+		}
+	} else {
+		({height, left, top, width} = getOffset(containerNode, false));
+		scroll.top = containerNode.scrollTop;
+		scroll.left = containerNode.scrollLeft;
+		totalWidth = width;
+		totalHeight = height;
+	}
+	if (isWebKit() && (containerNode.tagName === "BODY" || containerNode.tagName === "HTML") && isPinchZoomedIn) {
+		scroll.top = 0;
+		scroll.left = 0;
+		top = visualViewport?.pageTop ?? 0;
+		left = visualViewport?.pageLeft ?? 0;
+	}
+	return {
+		height,
+		left,
+		scroll,
+		top,
+		totalHeight,
+		totalWidth,
+		width
+	};
+};
+/** How far the overlay must shift along `axis` to stay inside the boundary. */
+var getDelta = (axis, offset, size, boundaryDimensions, containerDimensions, padding, containerOffsetWithBoundary) => {
+	const containerScroll = containerDimensions.scroll[axis] ?? 0;
+	const boundarySize = boundaryDimensions[AXIS_SIZE[axis]];
+	const boundaryScroll = boundaryDimensions.scroll[AXIS[axis]] ?? 0;
+	const boundaryStartEdge = containerOffsetWithBoundary[axis] + boundaryScroll + padding;
+	const boundaryEndEdge = containerOffsetWithBoundary[axis] + boundaryScroll + boundarySize - padding;
+	const startEdgeOffset = offset - containerScroll + boundaryScroll + containerOffsetWithBoundary[axis] - boundaryDimensions[AXIS[axis]];
+	const endEdgeOffset = startEdgeOffset + size;
+	if (startEdgeOffset < boundaryStartEdge) return boundaryStartEdge - startEdgeOffset;
+	if (endEdgeOffset > boundaryEndEdge) return Math.max(boundaryEndEdge - endEdgeOffset, boundaryStartEdge - startEdgeOffset);
+	return 0;
+};
+var getMargins = (node) => {
+	const style = window.getComputedStyle(node);
+	return {
+		bottom: parseInt(style.marginBottom, 10) || 0,
+		left: parseInt(style.marginLeft, 10) || 0,
+		right: parseInt(style.marginRight, 10) || 0,
+		top: parseInt(style.marginTop, 10) || 0
+	};
+};
+var PARSED_PLACEMENT_CACHE = {};
+var parsePlacement = (input) => {
+	const cached = PARSED_PLACEMENT_CACHE[input];
+	if (cached) return cached;
+	const [placement, rawCrossPlacement] = input.split(" ");
+	const axis = AXIS[placement] ?? "left";
+	const crossAxis = CROSS_AXIS[axis];
+	const parsed = {
+		axis,
+		crossAxis,
+		crossPlacement: rawCrossPlacement && AXIS[rawCrossPlacement] ? rawCrossPlacement : "center",
+		crossSize: AXIS_SIZE[crossAxis],
+		placement,
+		size: AXIS_SIZE[axis]
+	};
+	PARSED_PLACEMENT_CACHE[input] = parsed;
+	return parsed;
+};
+var computePosition = (childOffset, overlaySize, placementInfo, offset, crossOffset, isContainerPositioned, arrowSize, arrowBoundaryOffset, containerDimensions) => {
+	const { axis, crossAxis, crossPlacement, crossSize, placement, size } = placementInfo;
+	const position = {};
+	position[crossAxis] = childOffset[crossAxis] ?? 0;
+	if (crossPlacement === "center") position[crossAxis] += (childOffset[crossSize] - overlaySize[crossSize]) / 2;
+	else if (crossPlacement !== crossAxis) position[crossAxis] += childOffset[crossSize] - overlaySize[crossSize];
+	position[crossAxis] += crossOffset;
+	const minPosition = childOffset[crossAxis] - overlaySize[crossSize] + arrowSize + arrowBoundaryOffset;
+	const maxPosition = childOffset[crossAxis] + childOffset[crossSize] - arrowSize - arrowBoundaryOffset;
+	position[crossAxis] = clamp(position[crossAxis], minPosition, maxPosition);
+	if (placement === axis) position[FLIPPED_DIRECTION[axis]] = Math.floor((isContainerPositioned ? containerDimensions[size] : containerDimensions[TOTAL_SIZE[size]]) - childOffset[axis] + offset);
+	else position[axis] = Math.floor(childOffset[axis] + childOffset[size] + offset);
+	return position;
+};
+var getMaxHeight = (position, boundaryDimensions, containerOffsetWithBoundary, margins, padding, overlayHeight, heightGrowthDirection, containerDimensions, isContainerDescendentOfBoundary, visualViewport) => {
+	const overlayTop = (position.top != null ? position.top : containerDimensions[TOTAL_SIZE.height] - (position.bottom ?? 0) - overlayHeight) - (containerDimensions.scroll.top ?? 0);
+	const boundaryToContainerTransformOffset = isContainerDescendentOfBoundary ? containerOffsetWithBoundary.top : 0;
+	const viewportTop = visualViewport?.offsetTop ?? boundaryDimensions.top;
+	const viewportBottom = visualViewport ? visualViewport.offsetTop + visualViewport.height : boundaryDimensions.top + boundaryDimensions.height;
+	const boundingRect = {
+		bottom: Math.min(boundaryDimensions.top + boundaryDimensions.height + boundaryToContainerTransformOffset, viewportBottom),
+		top: Math.max(boundaryDimensions.top + boundaryToContainerTransformOffset, viewportTop + boundaryToContainerTransformOffset)
+	};
+	const reserved = (margins.top ?? 0) + (margins.bottom ?? 0) + padding;
+	return heightGrowthDirection !== "top" ? Math.max(0, boundingRect.bottom - overlayTop - reserved) : Math.max(0, overlayTop + overlayHeight - boundingRect.top - reserved);
+};
+/** How much room there is on the side the overlay wants to be on. */
+var getAvailableSpace = (boundaryDimensions, containerOffsetWithBoundary, childOffset, margins, padding, placementInfo, containerDimensions, isContainerDescendentOfBoundary) => {
+	const { axis, placement, size } = placementInfo;
+	const containerOffset = isContainerDescendentOfBoundary ? containerOffsetWithBoundary[axis] : 0;
+	if (placement === axis) return Math.max(0, childOffset[axis] - (containerDimensions.scroll[axis] ?? 0) - (boundaryDimensions[axis] + containerOffset) - (margins[axis] ?? 0) - (margins[FLIPPED_DIRECTION[axis]] ?? 0) - padding);
+	return Math.max(0, boundaryDimensions[size] + boundaryDimensions[axis] + containerOffset - childOffset[axis] - childOffset[size] + (containerDimensions.scroll[axis] ?? 0) - (margins[axis] ?? 0) - (margins[FLIPPED_DIRECTION[axis]] ?? 0) - padding);
+};
+/** @private Exported for tests, which drive the arithmetic without a real layout. */
+var calculatePositionInternal = (placementInput, childOffset, overlaySize, margins, padding, flip, boundaryDimensions, containerDimensions, containerOffsetWithBoundary, offset, crossOffset, isContainerPositioned, userSetMaxHeight, arrowSize, arrowBoundaryOffset, isContainerDescendentOfBoundary, visualViewport) => {
+	let placementInfo = parsePlacement(placementInput);
+	const { crossAxis, crossSize, size } = placementInfo;
+	let { crossPlacement, placement } = placementInfo;
+	let position = computePosition(childOffset, overlaySize, placementInfo, offset, crossOffset, isContainerPositioned, arrowSize, arrowBoundaryOffset, containerDimensions);
+	const space = getAvailableSpace(boundaryDimensions, containerOffsetWithBoundary, childOffset, margins, padding + offset, placementInfo, containerDimensions, isContainerDescendentOfBoundary);
+	if (flip && overlaySize[size] > space) {
+		const flippedPlacementInfo = parsePlacement(`${FLIPPED_DIRECTION[placement]} ${crossPlacement}`);
+		const flippedPosition = computePosition(childOffset, overlaySize, flippedPlacementInfo, offset, crossOffset, isContainerPositioned, arrowSize, arrowBoundaryOffset, containerDimensions);
+		if (getAvailableSpace(boundaryDimensions, containerOffsetWithBoundary, childOffset, margins, padding + offset, flippedPlacementInfo, containerDimensions, isContainerDescendentOfBoundary) > space) {
+			placementInfo = flippedPlacementInfo;
+			position = flippedPosition;
+		}
+	}
+	let heightGrowthDirection = "bottom";
+	if (placementInfo.axis === "top") {
+		if (placementInfo.placement === "top") heightGrowthDirection = "top";
+	} else if (placementInfo.crossAxis === "top") {
+		if (placementInfo.crossPlacement === "bottom") heightGrowthDirection = "top";
+	}
+	position[crossAxis] += getDelta(crossAxis, position[crossAxis], overlaySize[crossSize], boundaryDimensions, containerDimensions, padding, containerOffsetWithBoundary);
+	let maxHeight = getMaxHeight(position, boundaryDimensions, containerOffsetWithBoundary, margins, padding, overlaySize.height, heightGrowthDirection, containerDimensions, isContainerDescendentOfBoundary, visualViewport);
+	if (userSetMaxHeight && userSetMaxHeight < maxHeight) maxHeight = userSetMaxHeight;
+	overlaySize.height = Math.min(overlaySize.height, maxHeight);
+	position = computePosition(childOffset, overlaySize, placementInfo, offset, crossOffset, isContainerPositioned, arrowSize, arrowBoundaryOffset, containerDimensions);
+	position[crossAxis] += getDelta(crossAxis, position[crossAxis], overlaySize[crossSize], boundaryDimensions, containerDimensions, padding, containerOffsetWithBoundary);
+	const arrowPosition = {};
+	let origin = childOffset[crossAxis] - position[crossAxis] - (margins[AXIS[crossAxis]] ?? 0);
+	const preferredArrowPosition = origin + .5 * childOffset[crossSize];
+	const arrowMinPosition = arrowSize / 2 + arrowBoundaryOffset;
+	const overlayMargin = AXIS[crossAxis] === "left" ? (margins.left ?? 0) + (margins.right ?? 0) : (margins.top ?? 0) + (margins.bottom ?? 0);
+	const arrowMaxPosition = overlaySize[crossSize] - overlayMargin - arrowSize / 2 - arrowBoundaryOffset;
+	arrowPosition[crossAxis] = clamp(clamp(preferredArrowPosition, childOffset[crossAxis] + arrowSize / 2 - (position[crossAxis] + (margins[AXIS[crossAxis]] ?? 0)), childOffset[crossAxis] + childOffset[crossSize] - arrowSize / 2 - (position[crossAxis] + (margins[AXIS[crossAxis]] ?? 0))), arrowMinPosition, arrowMaxPosition);
+	({crossPlacement, placement} = placementInfo);
+	if (arrowSize) origin = arrowPosition[crossAxis];
+	else if (crossPlacement === "right") origin += childOffset[crossSize];
+	else if (crossPlacement === "center") origin += childOffset[crossSize] / 2;
+	const crossOrigin = placement === "left" || placement === "top" ? overlaySize[size] : 0;
+	return {
+		arrowOffsetLeft: arrowPosition.left,
+		arrowOffsetTop: arrowPosition.top,
+		maxHeight,
+		placement,
+		position,
+		triggerAnchorPoint: {
+			x: placement === "top" || placement === "bottom" ? origin : crossOrigin,
+			y: placement === "left" || placement === "right" ? origin : crossOrigin
+		}
+	};
+};
+/**
+* Where to put an overlay so it sits next to its trigger and stays inside the boundary.
+*
+* Measures the DOM, then hands the arithmetic to {@link calculatePositionInternal}.
+*/
+var calculatePosition = (options) => {
+	const { arrowBoundaryOffset = 0, arrowSize = 0, boundaryElement, crossOffset, maxHeight, offset, overlayNode, padding, placement, shouldFlip, targetNode, targetRect } = options;
+	const visualViewport = getVisualViewport();
+	const container = overlayNode instanceof HTMLElement ? getContainingBlock(overlayNode) : document.documentElement;
+	const isViewportContainer = container === document.documentElement;
+	const containerPositionStyle = window.getComputedStyle(container).position;
+	const isContainerPositioned = Boolean(containerPositionStyle) && containerPositionStyle !== "static";
+	const childOffset = isViewportContainer ? getOffset(targetNode, false, targetRect) : getPosition(targetNode, container, false, targetRect);
+	if (!isViewportContainer) {
+		const { marginLeft, marginTop } = window.getComputedStyle(targetNode);
+		childOffset.top += parseInt(marginTop, 10) || 0;
+		childOffset.left += parseInt(marginLeft, 10) || 0;
+	}
+	const overlaySize = getOffset(overlayNode, true);
+	const margins = getMargins(overlayNode);
+	overlaySize.width += (margins.left ?? 0) + (margins.right ?? 0);
+	overlaySize.height += (margins.top ?? 0) + (margins.bottom ?? 0);
+	const boundaryDimensions = getContainerDimensions(boundaryElement, visualViewport);
+	const containerDimensions = getContainerDimensions(container, visualViewport);
+	let containerOffsetWithBoundary;
+	const isBoundaryViewport = boundaryElement.tagName === "BODY" || boundaryElement.tagName === "HTML";
+	if (isBoundaryViewport && !isViewportContainer) {
+		const containerRect = getRect(container, false);
+		containerOffsetWithBoundary = {
+			height: 0,
+			left: -(containerRect.left - boundaryDimensions.left),
+			top: -(containerRect.top - boundaryDimensions.top),
+			width: 0
+		};
+	} else if (isBoundaryViewport && isViewportContainer) containerOffsetWithBoundary = {
+		height: 0,
+		left: 0,
+		top: 0,
+		width: 0
+	};
+	else containerOffsetWithBoundary = getPosition(boundaryElement, container, false);
+	return calculatePositionInternal(placement, childOffset, overlaySize, margins, padding, shouldFlip, boundaryDimensions, containerDimensions, containerOffsetWithBoundary, offset, crossOffset, isContainerPositioned, maxHeight, arrowSize, arrowBoundaryOffset, nodeContains(boundaryElement, container), visualViewport);
+};
+/** Resolves the logical `start`/`end` in a placement against the writing direction. */
+var translateRTL = (placement, direction) => direction === "rtl" ? placement.replace("start", "right").replace("end", "left") : placement.replace("start", "left").replace("end", "right");
+//#endregion
+export { calculatePosition, calculatePositionInternal, getRect, translateRTL };

package/dist/utils/story-assets.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Placeholder images for the stories.
+ *
+ * Every image a story shows is generated on demand by a public placeholder service rather than
+ * served from a bucket this repo owns, so a story stays runnable without an asset pipeline behind
+ * it. Each helper is a pure function of its seed — the same seed always resolves to the same
+ * image — which is what keeps a story stable between runs and a visual diff readable.
+ *
+ * Story-only, so it is deliberately not re-exported from `utils/index.ts`.
+ */
+/** A square portrait for `seed`, from pravatar.cc. */
+export declare const avatarSrc: (seed: number | string, size?: number) => string;
+/** A photo for `seed` at `width` × `height`, from picsum.photos. */
+export declare const photoSrc: (seed: string, width: number, height: number) => string;
+/** A scannable QR code carrying `data`, from api.qrserver.com. */
+export declare const qrCodeSrc: (data: string, size?: number) => string;
+/**
+ * One Iconify icon as an `<img>` source, for the places a story needs a URL rather than a component.
+ *
+ * `name` is `prefix:icon`. The default colour is the neutral grey that reads against both the light
+ * and the dark theme — an uncoloured Iconify SVG is black, which disappears in dark mode.
+ */
+export declare const iconSrc: (name: string, color?: string) => string;

package/dist/utils/text-value.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The text a collection item should be matched on when the caller gave no `textValue`.
+ *
+ * React derives this by walking the element tree it was handed and keeping the string
+ * children. That is not available here — inspecting children means rendering them — so the
+ * text is read back off the DOM instead, preferring an authored label when there is one.
+ *
+ * Read at match time rather than cached at mount, so an item whose text changes needs no
+ * re-registration and no `MutationObserver`.
+ */
+export declare const getCollectionTextValue: (element: HTMLElement | null | undefined) => string;

package/dist/utils/text-value.js

@@ -0,0 +1,36 @@
+//#region src/utils/text-value.ts
+/**
+* Parts whose text is decoration or secondary, and so must not feed typeahead.
+*
+* Without this list, typing `b` in a list of people would match the email address in a
+* description before it matched anyone's name, and a removable tag would match its close
+* button's label.
+*/
+var EXCLUDED_FROM_TEXT_VALUE = [
+	"[aria-hidden=\"true\"]",
+	"[data-slot=\"description\"]",
+	"[data-slot=\"list-box-item-indicator\"]",
+	"[data-slot=\"menu-item-indicator\"]",
+	"[data-slot=\"submenu-indicator\"]",
+	"[data-slot=\"tag-remove-button\"]",
+	"svg"
+].join(",");
+/**
+* The text a collection item should be matched on when the caller gave no `textValue`.
+*
+* React derives this by walking the element tree it was handed and keeping the string
+* children. That is not available here — inspecting children means rendering them — so the
+* text is read back off the DOM instead, preferring an authored label when there is one.
+*
+* Read at match time rather than cached at mount, so an item whose text changes needs no
+* re-registration and no `MutationObserver`.
+*/
+var getCollectionTextValue = (element) => {
+	if (!element) return "";
+	return [...(element.querySelector("[data-slot=\"label\"]") ?? element).childNodes].filter((node) => {
+		if (node.nodeType !== Node.ELEMENT_NODE && node.nodeType !== Node.TEXT_NODE) return false;
+		return !(node instanceof Element && node.matches(EXCLUDED_FROM_TEXT_VALUE));
+	}).map((node) => node.textContent ?? "").join("").replace(/\s+/g, " ").trim();
+};
+//#endregion
+export { getCollectionTextValue };

package/dist/utils/top-layer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Content that sits above the page's layers without belonging to any of them.
+ *
+ * A toast region is rendered outside every overlay, yet it is not *outside* them in the sense
+ * either of them cares about: it must stay readable to assistive technology when a modal opens,
+ * and pressing something in it must not dismiss the overlay it happens to be drawn over. Marking
+ * the element is what lets both those rules be written once. React Aria spells the same marker
+ * `data-react-aria-top-layer`.
+ */
+export declare const TOP_LAYER_ATTRIBUTE = "data-ropav-top-layer";
+export declare const TOP_LAYER_SELECTOR = "[data-ropav-top-layer]";
+/** Whether an element sits inside a top layer, and so is exempt from both rules above. */
+export declare const isInTopLayer: (element: Element) => boolean;

package/dist/utils/top-layer.js

@@ -0,0 +1,16 @@
+//#region src/utils/top-layer.ts
+/**
+* Content that sits above the page's layers without belonging to any of them.
+*
+* A toast region is rendered outside every overlay, yet it is not *outside* them in the sense
+* either of them cares about: it must stay readable to assistive technology when a modal opens,
+* and pressing something in it must not dismiss the overlay it happens to be drawn over. Marking
+* the element is what lets both those rules be written once. React Aria spells the same marker
+* `data-react-aria-top-layer`.
+*/
+var TOP_LAYER_ATTRIBUTE = "data-ropav-top-layer";
+var TOP_LAYER_SELECTOR = `[${TOP_LAYER_ATTRIBUTE}]`;
+/** Whether an element sits inside a top layer, and so is exempt from both rules above. */
+var isInTopLayer = (element) => element.closest(TOP_LAYER_SELECTOR) != null;
+//#endregion
+export { TOP_LAYER_ATTRIBUTE, TOP_LAYER_SELECTOR, isInTopLayer };

package/dist/utils/virtualizer-collection.d.ts

@@ -0,0 +1,77 @@
+import type { VirtualizerCollection, VirtualizerNodeType } from "./virtualizer-layout";
+import type { VirtualizerKey } from "./virtualizer-layout-info";
+/**
+ * Building a collection out of data rather than out of the DOM.
+ *
+ * React Aria renders a collection's children into a hidden tree and reads the result back, so the
+ * parent knows every node before the first paint. Rendering is what creates DOM here, so there is
+ * no pass to read back — and a registry of the items that did render cannot answer for a
+ * virtualized collection, where all but a window of them are absent. The nodes are built from the
+ * data instead, which is the only source that knows about an item nobody has scrolled to yet.
+ */
+export interface CreateListCollectionOptions<T> {
+    items: readonly T[];
+    /** Defaults to the item's own `id`, then `key`, then its index. */
+    getKey?: (item: T, index: number) => VirtualizerKey;
+    /** Text the item is matched on by typeahead, for items that have not rendered. */
+    getTextValue?: (item: T) => string | undefined;
+    isDisabled?: (item: T) => boolean;
+    /** The node type to build. `"item"` for a list, `"row"` for a table body. */
+    type?: VirtualizerNodeType;
+}
+/** The key an item carries itself, matching what a caller would pass as `id`. */
+export declare const defaultItemKey: (item: unknown, index: number) => VirtualizerKey;
+/** A flat collection of sibling nodes, which is what a list or a table body is. */
+export declare const createListCollection: <T>(options: CreateListCollectionOptions<T>) => VirtualizerCollection;
+export interface VirtualizerTableCollection extends VirtualizerCollection {
+    /** The key of the `header` node, which the table's own header looks its geometry up by. */
+    headerKey: VirtualizerKey;
+    /** The key of the single `headerrow` node the columns are laid out inside. */
+    headerRowKey: VirtualizerKey;
+    /** The key of the `rowgroup` node the rows are laid out inside. */
+    bodyKey: VirtualizerKey;
+    /** The key of the `loader` node, or `null` when the table has no loading sentinel. */
+    loaderKey: VirtualizerKey | null;
+    /** The columns, in order. A cell's position among them is what pairs it with a width. */
+    columnKeys: VirtualizerKey[];
+    /** The key of the cell where a row and a column meet. */
+    cellKey: (rowKey: VirtualizerKey, columnKey: VirtualizerKey) => VirtualizerKey;
+    /**
+     * The same nodes seen as a flat list of rows.
+     *
+     * This is what `useCollection` takes as its source: selection, arrow navigation and typeahead
+     * are one-dimensional, and handing them the whole table would have them walking over the header
+     * and every cell. The loader is not one of these either — nothing navigates onto a sentinel.
+     */
+    rows: VirtualizerCollection;
+}
+export interface CreateTableCollectionOptions<T> {
+    items: readonly T[];
+    /** The columns that are rendered, in order. */
+    columnKeys: readonly VirtualizerKey[];
+    /** Defaults to the item's own `id`, then `key`, then its index. */
+    getKey?: (item: T, index: number) => VirtualizerKey;
+    /** Text a row is matched on by typeahead, for rows that have not rendered. */
+    getTextValue?: (item: T) => string | undefined;
+    isDisabled?: (item: T) => boolean;
+    /** Whether a loading sentinel sits after the last row. */
+    hasLoader?: boolean;
+    /**
+     * Prefix for the keys of the nodes a table has but the data never names — the header, its row,
+     * the body and the loader. Pass something scoped to the table, so two tables on a page cannot
+     * describe each other's geometry.
+     */
+    idPrefix: string;
+}
+/**
+ * The two-dimensional collection a table layout walks: a header holding one row of columns, and a
+ * body holding a row per item with a cell per column.
+ *
+ * React Aria gets this shape from its hidden render pass, where every cell a row rendered is a
+ * node of the collection. There is no such pass here, so the cells are **derived**: a virtualized
+ * table renders one cell per column, so the cell where row `r` meets column `c` is known without
+ * anyone having rendered it. That is what lets the layout place a row that is nowhere in the DOM.
+ *
+ * Consequently a `colSpan` is not expressible — every cell is exactly one column wide.
+ */
+export declare const createTableCollection: <T>(options: CreateTableCollectionOptions<T>) => VirtualizerTableCollection;

package/dist/utils/virtualizer-collection.js

@@ -0,0 +1,153 @@
+//#region src/utils/virtualizer-collection.ts
+/** The key an item carries itself, matching what a caller would pass as `id`. */
+var defaultItemKey = (item, index) => {
+	if (item && typeof item === "object") {
+		const candidate = item.id ?? item.key;
+		if (typeof candidate === "string" || typeof candidate === "number") return candidate;
+	}
+	return index;
+};
+/** A flat collection of sibling nodes, which is what a list or a table body is. */
+var createListCollection = (options) => {
+	const { getKey = defaultItemKey, getTextValue, isDisabled, items, type = "item" } = options;
+	const nodes = /* @__PURE__ */ new Map();
+	const keys = [];
+	items.forEach((item, index) => {
+		const key = getKey(item, index);
+		keys.push(key);
+		nodes.set(key, {
+			childKeys: [],
+			content: item,
+			index,
+			isDisabled: isDisabled?.(item) ?? false,
+			key,
+			parentKey: null,
+			textValue: getTextValue?.(item),
+			type
+		});
+	});
+	return {
+		getChildNodes: () => [],
+		getNode: (key) => nodes.get(key),
+		itemCount: keys.length,
+		keys,
+		rootKeys: keys
+	};
+};
+/**
+* The two-dimensional collection a table layout walks: a header holding one row of columns, and a
+* body holding a row per item with a cell per column.
+*
+* React Aria gets this shape from its hidden render pass, where every cell a row rendered is a
+* node of the collection. There is no such pass here, so the cells are **derived**: a virtualized
+* table renders one cell per column, so the cell where row `r` meets column `c` is known without
+* anyone having rendered it. That is what lets the layout place a row that is nowhere in the DOM.
+*
+* Consequently a `colSpan` is not expressible — every cell is exactly one column wide.
+*/
+var createTableCollection = (options) => {
+	const { columnKeys: columns, getKey = defaultItemKey, getTextValue, hasLoader, idPrefix, isDisabled, items } = options;
+	const headerKey = `${idPrefix}-header`;
+	const headerRowKey = `${idPrefix}-headerrow`;
+	const bodyKey = `${idPrefix}-body`;
+	const loaderKey = hasLoader ? `${idPrefix}-loader` : null;
+	const cellKey = (rowKey, columnKey) => `${rowKey}:${columnKey}`;
+	const columnKeys = [...columns];
+	const rowKeys = [];
+	const bodyChildKeys = [];
+	const nodes = /* @__PURE__ */ new Map();
+	const keys = [];
+	const add = (node) => {
+		nodes.set(node.key, node);
+		keys.push(node.key);
+	};
+	add({
+		childKeys: [headerRowKey],
+		index: 0,
+		key: headerKey,
+		parentKey: null,
+		type: "header"
+	});
+	add({
+		childKeys: columnKeys,
+		index: 0,
+		key: headerRowKey,
+		parentKey: headerKey,
+		type: "headerrow"
+	});
+	columnKeys.forEach((key, index) => {
+		add({
+			childKeys: [],
+			index,
+			key,
+			parentKey: headerRowKey,
+			type: "column"
+		});
+	});
+	add({
+		childKeys: bodyChildKeys,
+		index: 1,
+		key: bodyKey,
+		parentKey: null,
+		type: "rowgroup"
+	});
+	items.forEach((item, index) => {
+		const rowKey = getKey(item, index);
+		const cellKeys = columnKeys.map((columnKey) => cellKey(rowKey, columnKey));
+		rowKeys.push(rowKey);
+		bodyChildKeys.push(rowKey);
+		add({
+			childKeys: cellKeys,
+			content: item,
+			index,
+			isDisabled: isDisabled?.(item) ?? false,
+			key: rowKey,
+			parentKey: bodyKey,
+			textValue: getTextValue?.(item),
+			type: "row"
+		});
+		cellKeys.forEach((key, columnIndex) => {
+			add({
+				childKeys: [],
+				index: columnIndex,
+				key,
+				parentKey: rowKey,
+				type: "cell"
+			});
+		});
+	});
+	if (loaderKey != null) {
+		bodyChildKeys.push(loaderKey);
+		add({
+			childKeys: [],
+			index: items.length,
+			key: loaderKey,
+			parentKey: bodyKey,
+			type: "loader"
+		});
+	}
+	const getNode = (key) => nodes.get(key);
+	const getChildNodes = (key) => (nodes.get(key)?.childKeys ?? []).map((childKey) => nodes.get(childKey)).filter((node) => node != null);
+	return {
+		bodyKey,
+		cellKey,
+		columnKeys,
+		getChildNodes,
+		getNode,
+		headerKey,
+		headerRowKey,
+		itemCount: items.length,
+		keys,
+		loaderKey,
+		rootKeys: [headerKey, bodyKey],
+		rows: {
+			getChildNodes: () => [],
+			getNode,
+			itemCount: items.length,
+			keys: rowKeys,
+			rootKeys: rowKeys
+		}
+	};
+};
+//#endregion
+export { createListCollection, createTableCollection, defaultItemKey };