@octanejs/window 0.0.1

package/src/components/list/types.ts

@@ -0,0 +1,214 @@
+import type {
+	ComponentProps,
+	CSSProperties,
+	HTMLAttributes,
+	ReactElement,
+	ReactNode,
+	Ref,
+} from 'react';
+import type { TagNames } from '../../types.js';
+
+export type DynamicRowHeight = {
+	getAverageRowHeight(): number;
+	getRowHeight(index: number): number | undefined;
+	setRowHeight(index: number, size: number): void;
+	observeRowElements: (elements: Element[] | NodeListOf<Element>) => () => void;
+};
+
+type ForbiddenKeys = 'ariaAttributes' | 'index' | 'style';
+type ExcludeForbiddenKeys<Type> = {
+	[Key in keyof Type]: Key extends ForbiddenKeys ? never : Type[Key];
+};
+
+export type ListProps<RowProps extends object, TagName extends TagNames = 'div'> = Omit<
+	HTMLAttributes<HTMLDivElement>,
+	'onResize'
+> & {
+	/**
+	 * Additional content to be rendered within the list (above cells).
+	 * This property can be used to render things like overlays or tooltips.
+	 */
+	children?: ReactNode;
+
+	/**
+	 * CSS class name.
+	 */
+	className?: string;
+
+	/**
+	 * Default height of list for initial render.
+	 * This value is important for server rendering.
+	 */
+	defaultHeight?: number;
+
+	/**
+	 * Ref used to interact with this component's imperative API.
+	 *
+	 * This API has imperative methods for scrolling and a getter for the outermost DOM element.
+	 *
+	 * ℹ️ The `useListRef` and `useListCallbackRef` hooks are exported for convenience use in TypeScript projects.
+	 */
+	listRef?: Ref<{
+		/**
+		 * Outermost HTML element for the list if mounted and null (if not mounted.
+		 */
+		get element(): HTMLDivElement | null;
+
+		/**
+		 * Scrolls the list so that the specified row is visible.
+		 *
+		 * @param align Determines the vertical alignment of the element within the list
+		 * @param behavior Determines whether scrolling is instant or animates smoothly
+		 * @param index Index of the row to scroll to (0-based)
+		 *
+		 * @throws RangeError if an invalid row index is provided
+		 */
+		scrollToRow(config: {
+			align?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+			behavior?: 'auto' | 'instant' | 'smooth';
+			index: number;
+		}): void;
+	}>;
+
+	/**
+	 * Callback notified when the List's outermost HTMLElement resizes.
+	 * This may be used to (re)scroll a row into view.
+	 */
+	onResize?: (
+		size: { height: number; width: number },
+		prevSize: { height: number; width: number },
+	) => void;
+
+	/**
+	 * Callback notified when the range of visible rows changes.
+	 */
+	onRowsRendered?: (
+		visibleRows: { startIndex: number; stopIndex: number },
+		allRows: { startIndex: number; stopIndex: number },
+	) => void;
+
+	/**
+	 * How many additional rows to render outside of the visible area.
+	 * This can reduce visual flickering near the edges of a list when scrolling.
+	 */
+	overscanCount?: number;
+
+	/**
+	 * React component responsible for rendering a row.
+	 *
+	 * This component will receive an `index` and `style` prop by default.
+	 * Additionally it will receive prop values passed to `rowProps`.
+	 *
+	 * ℹ️ The prop types for this component are exported as `RowComponentProps`
+	 */
+	rowComponent: (
+		props: {
+			ariaAttributes: {
+				'aria-posinset': number;
+				'aria-setsize': number;
+				role: 'listitem';
+			};
+			index: number;
+			style: CSSProperties;
+		} & RowProps,
+	) => ReactElement | null;
+
+	/**
+	 * Number of items to be rendered in the list.
+	 */
+	rowCount: number;
+
+	/**
+	 * Row height; the following formats are supported:
+	 * - number of pixels (number)
+	 * - percentage of the grid's current height (string)
+	 * - function that returns the row height (in pixels) given an index and `cellProps`
+	 * - dynamic row height cache returned by the `useDynamicRowHeight` hook
+	 *
+	 * ⚠️ Dynamic row heights are not as efficient as predetermined sizes.
+	 * It's recommended to provide your own height values if they can be determined ahead of time.
+	 */
+	rowHeight: number | string | ((index: number, cellProps: RowProps) => number) | DynamicRowHeight;
+
+	/**
+	 * Lists use the row index as a `key` by default.
+	 * This prop can provide a custom `key` value.
+	 *
+	 * ℹ️ Custom keys can ensure better UX for sortable or filterable lists,
+	 * particularly if your row components are stateful.
+	 * Refer to the [React documentation](https://react.dev/learn/rendering-lists#keeping-list-items-in-order-with-key) for more info.
+	 *
+	 * ⚠️ This prop cannot be auto-memoized because it is called during render.
+	 * It is important to always `useCallback` for this prop; do not use an inline function.
+	 */
+	rowKey?: (index: number, data: RowProps) => React.Key;
+
+	/**
+	 * Additional props to be passed to the row-rendering component.
+	 * List will automatically re-render rows when values in this object change.
+	 *
+	 * ⚠️ This object must not contain `ariaAttributes`, `index`, or `style` props.
+	 */
+	rowProps: ExcludeForbiddenKeys<RowProps>;
+
+	/**
+	 * Optional CSS properties.
+	 * The list of rows will fill the height defined by this style.
+	 */
+	style?: CSSProperties;
+
+	/**
+	 * Can be used to override the root HTML element rendered by the List component.
+	 * The default value is "div", meaning that List renders an HTMLDivElement as its root.
+	 *
+	 * ⚠️ In most use cases the default ARIA roles are sufficient and this prop is not needed.
+	 */
+	tagName?: TagName;
+};
+
+export type RowComponent<RowProps extends object> = ListProps<RowProps>['rowComponent'];
+
+export type RowComponentProps<RowProps extends object = object> = ComponentProps<
+	RowComponent<RowProps>
+>;
+
+export type OnRowsRendered = NonNullable<ListProps<object>['onRowsRendered']>;
+
+export type CachedBounds = Map<
+	number,
+	{
+		height: number;
+		scrollTop: number;
+	}
+>;
+
+/**
+ * Imperative List API.
+ *
+ * ℹ️ The `useListRef` and `useListCallbackRef` hooks are exported for convenience use in TypeScript projects.
+ */
+export interface ListImperativeAPI {
+	/**
+	 * Outermost HTML element for the list if mounted and null (if not mounted.
+	 */
+	get element(): HTMLDivElement | null;
+
+	/**
+	 * Scrolls the list so that the specified row is visible.
+	 *
+	 * @param align Determines the vertical alignment of the element within the list
+	 * @param behavior Determines whether scrolling is instant or animates smoothly
+	 * @param index Index of the row to scroll to (0-based)
+	 *
+	 * @throws RangeError if an invalid row index is provided
+	 */
+	scrollToRow: ({
+		align,
+		behavior,
+		index,
+	}: {
+		align?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+		behavior?: 'auto' | 'instant' | 'smooth';
+		index: number;
+	}) => void;
+}

package/src/components/list/useDynamicRowHeight.ts

@@ -0,0 +1,170 @@
+import { useCallback, useEffect, useMemo, useState } from 'octane';
+import { useStableCallback } from '../../hooks/useStableCallback.js';
+import { getSlot, subSlot } from '../../internal.js';
+import { assert } from '../../utils/assert.js';
+import { DATA_ATTRIBUTE_LIST_INDEX } from './List.js';
+import type { DynamicRowHeight } from './types.js';
+
+export function useDynamicRowHeight(options: {
+	defaultRowHeight: number;
+	key?: string | number;
+}): DynamicRowHeight;
+export function useDynamicRowHeight(
+	{
+		defaultRowHeight,
+		key,
+	}: {
+		defaultRowHeight: number;
+		key?: string | number;
+	},
+	...rest: unknown[]
+): DynamicRowHeight {
+	const slot = getSlot(rest);
+	const [state, setState] = useState<{
+		key: string | number | undefined;
+		map: Map<number, number>;
+	}>(
+		{
+			key,
+			map: new Map(),
+		},
+		subSlot(slot, 'state'),
+	);
+
+	if (state.key !== key) {
+		setState({
+			key,
+			map: new Map(),
+		});
+	}
+
+	const { map } = state;
+
+	const getAverageRowHeight = useCallback(
+		() => {
+			let totalHeight = 0;
+
+			map.forEach((height) => {
+				totalHeight += height;
+			});
+
+			if (totalHeight === 0) {
+				return defaultRowHeight;
+			}
+
+			return totalHeight / map.size;
+		},
+		[defaultRowHeight, map],
+		subSlot(slot, 'average'),
+	);
+
+	const getRowHeight = useCallback(
+		(index: number) => {
+			const measuredHeight = map.get(index);
+			if (measuredHeight !== undefined) {
+				return measuredHeight;
+			}
+
+			// Temporarily store default height in the cache map to avoid scroll jumps if rowProps change
+			// Else rowProps changes can impact the average height, and cause rows to shift up or down within the list
+			// see github.com/bvaughn/react-window/issues/863
+			map.set(index, defaultRowHeight);
+
+			return defaultRowHeight;
+		},
+		[defaultRowHeight, map],
+		subSlot(slot, 'height'),
+	);
+
+	const setRowHeight = useCallback(
+		(index: number, size: number) => {
+			setState((prevState) => {
+				if (prevState.map.get(index) === size) {
+					return prevState;
+				}
+
+				const clonedMap = new Map(prevState.map);
+				clonedMap.set(index, size);
+
+				return {
+					...prevState,
+					map: clonedMap,
+				};
+			});
+		},
+		[],
+		subSlot(slot, 'set-height'),
+	);
+
+	const resizeObserverCallback = useStableCallback(
+		(entries: ResizeObserverEntry[]) => {
+			if (entries.length === 0) {
+				return;
+			}
+
+			entries.forEach((entry) => {
+				const { borderBoxSize, target } = entry;
+
+				const attribute = target.getAttribute(DATA_ATTRIBUTE_LIST_INDEX);
+				assert(attribute !== null, `Invalid ${DATA_ATTRIBUTE_LIST_INDEX} attribute value`);
+
+				const index = parseInt(attribute);
+
+				const { blockSize: height } = borderBoxSize[0];
+				if (!height) {
+					// Ignore heights that have not yet been measured (e.g. <img> elements that have not yet loaded)
+					return;
+				}
+
+				setRowHeight(index, height);
+			});
+		},
+		subSlot(slot, 'resize-callback'),
+	);
+
+	const [resizeObserver] = useState(
+		() => {
+			if (typeof ResizeObserver !== 'undefined') {
+				return new ResizeObserver(resizeObserverCallback);
+			}
+		},
+		subSlot(slot, 'resize-observer'),
+	);
+
+	useEffect(
+		() => {
+			if (resizeObserver) {
+				return () => {
+					resizeObserver.disconnect();
+				};
+			}
+		},
+		[resizeObserver],
+		subSlot(slot, 'cleanup'),
+	);
+
+	const observeRowElements = useCallback(
+		(elements: Element[] | NodeListOf<Element>) => {
+			if (resizeObserver) {
+				elements.forEach((element) => resizeObserver.observe(element));
+				return () => {
+					elements.forEach((element) => resizeObserver.unobserve(element));
+				};
+			}
+			return () => {};
+		},
+		[resizeObserver],
+		subSlot(slot, 'observe-elements'),
+	);
+
+	return useMemo<DynamicRowHeight>(
+		() => ({
+			getAverageRowHeight,
+			getRowHeight,
+			setRowHeight,
+			observeRowElements,
+		}),
+		[getAverageRowHeight, getRowHeight, setRowHeight, observeRowElements],
+		subSlot(slot, 'result'),
+	);
+}

package/src/components/list/useListCallbackRef.ts

@@ -0,0 +1,16 @@
+import { useState } from 'octane';
+import { getPublicArgument, getSlot, subSlot } from '../../internal.js';
+import type { ListImperativeAPI } from './types.js';
+
+/**
+ * Convenience hook to return a properly typed ref callback for the List component.
+ *
+ * Use this hook when you need to share the ref with another component or hook.
+ */
+export const useListCallbackRef = ((...args: unknown[]) => {
+	const slot = getSlot(args);
+	const initialValue = getPublicArgument(args, 0) as
+		ListImperativeAPI | null | (() => ListImperativeAPI | null) | undefined;
+	const [value, setValue] = useState(initialValue, subSlot(slot, 'list-callback-ref'));
+	return [value, setValue];
+}) as unknown as typeof import('react').useState<ListImperativeAPI | null>;

package/src/components/list/useListRef.ts

@@ -0,0 +1,12 @@
+import { useRef } from 'octane';
+import { getPublicArgument, getSlot, subSlot } from '../../internal.js';
+import type { ListImperativeAPI } from './types.js';
+
+/**
+ * Convenience hook to return a properly typed ref for the List component.
+ */
+export const useListRef = ((...args: unknown[]) => {
+	const slot = getSlot(args);
+	const initialValue = getPublicArgument(args, 0) as ListImperativeAPI | null | undefined;
+	return useRef(initialValue, subSlot(slot, 'list-ref'));
+}) as typeof import('react').useRef<ListImperativeAPI>;

package/src/constants.ts

@@ -0,0 +1,3 @@
+export const EMPTY_ARRAY: unknown[] = [];
+export const EMPTY_OBJECT = {};
+export const NOOP_FUNCTION = () => {};

package/src/core/createCachedBounds.ts

@@ -0,0 +1,65 @@
+import { assert } from '../utils/assert.js';
+import type { Bounds, CachedBounds, SizeFunction } from './types.js';
+
+export function createCachedBounds<Props extends object>({
+	itemCount,
+	itemProps,
+	itemSize,
+}: {
+	itemCount: number;
+	itemProps: Props;
+	itemSize: number | SizeFunction<Props>;
+}): CachedBounds {
+	const cache = new Map<number, Bounds>();
+
+	return {
+		get(index: number) {
+			assert(index < itemCount, `Invalid index ${index}`);
+
+			while (cache.size - 1 < index) {
+				const currentIndex = cache.size;
+
+				let size: number;
+				switch (typeof itemSize) {
+					case 'function': {
+						size = itemSize(currentIndex, itemProps);
+						break;
+					}
+					case 'number': {
+						size = itemSize;
+						break;
+					}
+				}
+
+				if (currentIndex === 0) {
+					cache.set(currentIndex, {
+						size,
+						scrollOffset: 0,
+					});
+				} else {
+					const previousRowBounds = cache.get(currentIndex - 1);
+					assert(
+						previousRowBounds !== undefined,
+						`Unexpected bounds cache miss for index ${index}`,
+					);
+
+					cache.set(currentIndex, {
+						scrollOffset: previousRowBounds.scrollOffset + previousRowBounds.size,
+						size,
+					});
+				}
+			}
+
+			const bounds = cache.get(index);
+			assert(bounds !== undefined, `Unexpected bounds cache miss for index ${index}`);
+
+			return bounds;
+		},
+		set(index: number, bounds: Bounds) {
+			cache.set(index, bounds);
+		},
+		get size() {
+			return cache.size;
+		},
+	};
+}

package/src/core/getEstimatedSize.ts

@@ -0,0 +1,25 @@
+import type { CachedBounds, SizeFunction } from './types.js';
+import { assert } from '../utils/assert.js';
+
+export function getEstimatedSize<Props extends object>({
+	cachedBounds,
+	itemCount,
+	itemSize,
+}: {
+	cachedBounds: CachedBounds;
+	itemCount: number;
+	itemSize: number | SizeFunction<Props>;
+}) {
+	if (itemCount === 0) {
+		return 0;
+	} else if (typeof itemSize === 'number') {
+		return itemCount * itemSize;
+	} else {
+		const bounds = cachedBounds.get(cachedBounds.size === 0 ? 0 : cachedBounds.size - 1);
+		assert(bounds !== undefined, 'Unexpected bounds cache miss');
+
+		const averageItemSize = (bounds.scrollOffset + bounds.size) / cachedBounds.size;
+
+		return itemCount * averageItemSize;
+	}
+}

package/src/core/getOffsetForIndex.ts

@@ -0,0 +1,75 @@
+import type { Align } from '../types.js';
+import { getEstimatedSize } from './getEstimatedSize.js';
+import type { CachedBounds, SizeFunction } from './types.js';
+
+export function getOffsetForIndex<Props extends object>({
+	align,
+	cachedBounds,
+	index,
+	itemCount,
+	itemSize,
+	containerScrollOffset,
+	containerSize,
+}: {
+	align: Align;
+	cachedBounds: CachedBounds;
+	index: number;
+	itemCount: number;
+	itemSize: number | SizeFunction<Props>;
+	containerScrollOffset: number;
+	containerSize: number;
+}) {
+	if (index < 0 || index >= itemCount) {
+		throw RangeError(`Invalid index specified: ${index}`, {
+			cause: `Index ${index} is not within the range of 0 - ${itemCount - 1}`,
+		});
+	}
+
+	const estimatedTotalSize = getEstimatedSize({
+		cachedBounds,
+		itemCount,
+		itemSize,
+	});
+
+	const bounds = cachedBounds.get(index);
+	const maxOffset = Math.max(0, Math.min(estimatedTotalSize - containerSize, bounds.scrollOffset));
+	const minOffset = Math.max(0, bounds.scrollOffset - containerSize + bounds.size);
+
+	if (align === 'smart') {
+		if (containerScrollOffset >= minOffset && containerScrollOffset <= maxOffset) {
+			align = 'auto';
+		} else {
+			align = 'center';
+		}
+	}
+
+	switch (align) {
+		case 'start': {
+			return maxOffset;
+		}
+		case 'end': {
+			return minOffset;
+		}
+		case 'center': {
+			if (bounds.scrollOffset <= containerSize / 2) {
+				// Too near the beginning to center-align
+				return 0;
+			} else if (bounds.scrollOffset + bounds.size / 2 >= estimatedTotalSize - containerSize / 2) {
+				// Too near the end to center-align
+				return estimatedTotalSize - containerSize;
+			} else {
+				return bounds.scrollOffset + bounds.size / 2 - containerSize / 2;
+			}
+		}
+		case 'auto':
+		default: {
+			if (containerScrollOffset >= minOffset && containerScrollOffset <= maxOffset) {
+				return containerScrollOffset;
+			} else if (containerScrollOffset < minOffset) {
+				return minOffset;
+			} else {
+				return maxOffset;
+			}
+		}
+	}
+}

package/src/core/getStartStopIndices.ts

@@ -0,0 +1,68 @@
+import type { CachedBounds } from './types.js';
+
+export function getStartStopIndices({
+	cachedBounds,
+	containerScrollOffset,
+	containerSize,
+	itemCount,
+	overscanCount,
+}: {
+	cachedBounds: CachedBounds;
+	containerScrollOffset: number;
+	containerSize: number;
+	itemCount: number;
+	overscanCount: number;
+}): {
+	startIndexVisible: number;
+	stopIndexVisible: number;
+	startIndexOverscan: number;
+	stopIndexOverscan: number;
+} {
+	const maxIndex = itemCount - 1;
+
+	let startIndexVisible = 0;
+	let stopIndexVisible = -1;
+	let startIndexOverscan = 0;
+	let stopIndexOverscan = -1;
+	let currentIndex = 0;
+
+	while (currentIndex < maxIndex) {
+		const bounds = cachedBounds.get(currentIndex);
+
+		if (bounds.scrollOffset + bounds.size > containerScrollOffset) {
+			break;
+		}
+
+		currentIndex++;
+	}
+
+	startIndexVisible = currentIndex;
+	startIndexOverscan = Math.max(0, startIndexVisible - overscanCount);
+
+	while (currentIndex < maxIndex) {
+		const bounds = cachedBounds.get(currentIndex);
+
+		if (bounds.scrollOffset + bounds.size >= containerScrollOffset + containerSize) {
+			break;
+		}
+
+		currentIndex++;
+	}
+
+	stopIndexVisible = Math.min(maxIndex, currentIndex);
+	stopIndexOverscan = Math.min(itemCount - 1, stopIndexVisible + overscanCount);
+
+	if (startIndexVisible < 0) {
+		startIndexVisible = 0;
+		stopIndexVisible = -1;
+		startIndexOverscan = 0;
+		stopIndexOverscan = -1;
+	}
+
+	return {
+		startIndexVisible,
+		stopIndexVisible,
+		startIndexOverscan,
+		stopIndexOverscan,
+	};
+}

package/src/core/types.ts

@@ -0,0 +1,14 @@
+export type Bounds = {
+	size: number;
+	scrollOffset: number;
+};
+
+export type CachedBounds = {
+	get(index: number): Bounds;
+	set(index: number, bounds: Bounds): void;
+	size: number;
+};
+
+export type Direction = 'horizontal' | 'vertical';
+
+export type SizeFunction<Props extends object> = (index: number, props: Props) => number;

package/src/core/useCachedBounds.ts

@@ -0,0 +1,29 @@
+import { useMemo } from 'octane';
+import { getSlot, subSlot } from '../internal.js';
+import { createCachedBounds } from './createCachedBounds.js';
+import type { CachedBounds, SizeFunction } from './types.js';
+
+export function useCachedBounds<Props extends object>(
+	{
+		itemCount,
+		itemProps,
+		itemSize,
+	}: {
+		itemCount: number;
+		itemProps: Props;
+		itemSize: number | SizeFunction<Props>;
+	},
+	...rest: unknown[]
+): CachedBounds {
+	const slot = getSlot(rest);
+	return useMemo(
+		() =>
+			createCachedBounds({
+				itemCount,
+				itemProps,
+				itemSize,
+			}),
+		[itemCount, itemProps, itemSize],
+		subSlot(slot, 'bounds'),
+	);
+}