@octanejs/window 0.0.1

package/src/core/useIsRtl.ts

@@ -0,0 +1,27 @@
+import { useLayoutEffect, useState } from 'octane';
+import type { HTMLAttributes } from 'react';
+import { getSlot, subSlot } from '../internal.js';
+import { isRtl } from '../utils/isRtl.js';
+
+export function useIsRtl(
+	element: HTMLElement | null,
+	dir: HTMLAttributes<HTMLElement>['dir'],
+	...rest: unknown[]
+) {
+	const slot = getSlot(rest);
+	const [value, setValue] = useState(dir === 'rtl', subSlot(slot, 'value'));
+
+	useLayoutEffect(
+		() => {
+			if (element) {
+				if (!dir) {
+					setValue(isRtl(element));
+				}
+			}
+		},
+		[dir, element],
+		subSlot(slot, 'effect'),
+	);
+
+	return value;
+}

package/src/core/useItemSize.ts

@@ -0,0 +1,33 @@
+import { assert } from '../utils/assert.js';
+import type { SizeFunction } from './types.js';
+
+export function useItemSize<Props extends object>({
+	containerSize,
+	itemSize: itemSizeProp,
+}: {
+	containerSize: number;
+	itemSize: number | string | SizeFunction<Props>;
+}) {
+	let itemSize: number | SizeFunction<Props>;
+	switch (typeof itemSizeProp) {
+		case 'string': {
+			assert(
+				itemSizeProp.endsWith('%'),
+				`Invalid item size: "${itemSizeProp}"; string values must be percentages (e.g. "100%")`,
+			);
+			assert(
+				containerSize !== undefined,
+				'Container size must be defined if a percentage item size is specified',
+			);
+
+			itemSize = (containerSize * parseInt(itemSizeProp)) / 100;
+			break;
+		}
+		default: {
+			itemSize = itemSizeProp;
+			break;
+		}
+	}
+
+	return itemSize;
+}

package/src/core/useVirtualizer.ts

@@ -0,0 +1,269 @@
+import { useCallback, useLayoutEffect, useRef, useState } from 'octane';
+import type { CSSProperties } from 'react';
+import { useIsomorphicLayoutEffect } from '../hooks/useIsomorphicLayoutEffect.js';
+import { useResizeObserver } from '../hooks/useResizeObserver.js';
+import { useStableCallback } from '../hooks/useStableCallback.js';
+import { getSlot, subSlot } from '../internal.js';
+import type { Align } from '../types.js';
+import { adjustScrollOffsetForRtl } from '../utils/adjustScrollOffsetForRtl.js';
+import { shallowCompare } from '../utils/shallowCompare.js';
+import { getEstimatedSize as getEstimatedSizeUtil } from './getEstimatedSize.js';
+import { getOffsetForIndex } from './getOffsetForIndex.js';
+import { getStartStopIndices as getStartStopIndicesUtil } from './getStartStopIndices.js';
+import type { Direction, SizeFunction } from './types.js';
+import { useCachedBounds } from './useCachedBounds.js';
+import { useItemSize } from './useItemSize.js';
+
+export function useVirtualizer<Props extends object>(
+	{
+		containerElement,
+		containerStyle,
+		defaultContainerSize = 0,
+		direction,
+		isRtl = false,
+		itemCount,
+		itemProps,
+		itemSize: itemSizeProp,
+		onResize,
+		overscanCount,
+	}: {
+		containerElement: HTMLElement | null;
+		containerStyle?: CSSProperties;
+		defaultContainerSize?: number;
+		direction: Direction;
+		isRtl?: boolean;
+		itemCount: number;
+		itemProps: Props;
+		itemSize: number | string | SizeFunction<Props>;
+		onResize:
+			| ((
+					size: { height: number; width: number },
+					prevSize: { height: number; width: number },
+			  ) => void)
+			| undefined;
+		overscanCount: number;
+	},
+	...rest: unknown[]
+) {
+	const slot = getSlot(rest);
+	const { height = defaultContainerSize, width = defaultContainerSize } = useResizeObserver(
+		{
+			defaultHeight: direction === 'vertical' ? defaultContainerSize : undefined,
+			defaultWidth: direction === 'horizontal' ? defaultContainerSize : undefined,
+			element: containerElement,
+			mode: direction === 'vertical' ? 'only-height' : 'only-width',
+			style: containerStyle,
+		},
+		subSlot(slot, 'resize-observer'),
+	);
+
+	const prevSizeRef = useRef<{ height: number; width: number }>(
+		{
+			height: 0,
+			width: 0,
+		},
+		subSlot(slot, 'previous-size'),
+	);
+
+	const containerSize = direction === 'vertical' ? height : width;
+
+	const itemSize = useItemSize({ containerSize, itemSize: itemSizeProp });
+
+	useLayoutEffect(
+		() => {
+			if (typeof onResize === 'function') {
+				const prevSize = prevSizeRef.current;
+
+				if (prevSize.height !== height || prevSize.width !== width) {
+					onResize({ height, width }, { ...prevSize });
+
+					prevSize.height = height;
+					prevSize.width = width;
+				}
+			}
+		},
+		[height, onResize, width],
+		subSlot(slot, 'on-resize'),
+	);
+
+	const cachedBounds = useCachedBounds(
+		{
+			itemCount,
+			itemProps,
+			itemSize,
+		},
+		subSlot(slot, 'cached-bounds'),
+	);
+
+	const getCellBounds = useCallback(
+		(index: number) => cachedBounds.get(index),
+		[cachedBounds],
+		subSlot(slot, 'cell-bounds'),
+	);
+
+	const [indices, setIndices] = useState<{
+		startIndexVisible: number;
+		stopIndexVisible: number;
+		startIndexOverscan: number;
+		stopIndexOverscan: number;
+	}>(
+		() =>
+			getStartStopIndicesUtil({
+				cachedBounds,
+				// TODO Potentially support a defaultScrollOffset prop?
+				containerScrollOffset: 0,
+				containerSize,
+				itemCount,
+				overscanCount,
+			}),
+		subSlot(slot, 'indices'),
+	);
+
+	// Guard against temporarily invalid indices that may occur when item count decreases
+	// Cached bounds object will be re-created and a second render will restore things
+	const { startIndexVisible, startIndexOverscan, stopIndexVisible, stopIndexOverscan } = {
+		startIndexVisible: Math.min(itemCount - 1, indices.startIndexVisible),
+		startIndexOverscan: Math.min(itemCount - 1, indices.startIndexOverscan),
+		stopIndexVisible: Math.min(itemCount - 1, indices.stopIndexVisible),
+		stopIndexOverscan: Math.min(itemCount - 1, indices.stopIndexOverscan),
+	};
+
+	const getEstimatedSize = useCallback(
+		() =>
+			getEstimatedSizeUtil({
+				cachedBounds,
+				itemCount,
+				itemSize,
+			}),
+		[cachedBounds, itemCount, itemSize],
+		subSlot(slot, 'estimated-size'),
+	);
+
+	const getStartStopIndices = useCallback(
+		(scrollOffset: number) => {
+			const containerScrollOffset = adjustScrollOffsetForRtl({
+				containerElement,
+				direction,
+				isRtl,
+				scrollOffset,
+			});
+
+			return getStartStopIndicesUtil({
+				cachedBounds,
+				containerScrollOffset,
+				containerSize,
+				itemCount,
+				overscanCount,
+			});
+		},
+		[cachedBounds, containerElement, containerSize, direction, isRtl, itemCount, overscanCount],
+		subSlot(slot, 'start-stop'),
+	);
+
+	useIsomorphicLayoutEffect(
+		() => {
+			const scrollOffset =
+				(direction === 'vertical' ? containerElement?.scrollTop : containerElement?.scrollLeft) ??
+				0;
+
+			setIndices(getStartStopIndices(scrollOffset));
+		},
+		[containerElement, direction, getStartStopIndices],
+		subSlot(slot, 'initial-scroll'),
+	);
+
+	useIsomorphicLayoutEffect(
+		() => {
+			if (!containerElement) {
+				return;
+			}
+
+			const onScroll = () => {
+				setIndices((prev) => {
+					const { scrollLeft, scrollTop } = containerElement;
+
+					const scrollOffset = adjustScrollOffsetForRtl({
+						containerElement,
+						direction,
+						isRtl,
+						scrollOffset: direction === 'vertical' ? scrollTop : scrollLeft,
+					});
+
+					const next = getStartStopIndicesUtil({
+						cachedBounds,
+						containerScrollOffset: scrollOffset,
+						containerSize,
+						itemCount,
+						overscanCount,
+					});
+
+					if (shallowCompare(next, prev)) {
+						return prev;
+					}
+
+					return next;
+				});
+			};
+
+			containerElement.addEventListener('scroll', onScroll);
+
+			return () => {
+				containerElement.removeEventListener('scroll', onScroll);
+			};
+		},
+		[cachedBounds, containerElement, containerSize, direction, itemCount, overscanCount],
+		subSlot(slot, 'scroll-listener'),
+	);
+
+	const scrollToIndex = useStableCallback(
+		({
+			align = 'auto',
+			containerScrollOffset,
+			index,
+		}: {
+			align?: Align;
+			containerScrollOffset: number;
+			index: number;
+		}) => {
+			let scrollOffset = getOffsetForIndex({
+				align,
+				cachedBounds,
+				containerScrollOffset,
+				containerSize,
+				index,
+				itemCount,
+				itemSize,
+			});
+
+			if (containerElement) {
+				scrollOffset = adjustScrollOffsetForRtl({
+					containerElement,
+					direction,
+					isRtl,
+					scrollOffset,
+				});
+
+				if (typeof containerElement.scrollTo !== 'function') {
+					// Special case for environments like jsdom that don't implement scrollTo
+					const next = getStartStopIndices(scrollOffset);
+					if (!shallowCompare(indices, next)) {
+						setIndices(next);
+					}
+				}
+
+				return scrollOffset;
+			}
+		},
+		subSlot(slot, 'scroll-to-index'),
+	);
+
+	return {
+		getCellBounds,
+		getEstimatedSize,
+		scrollToIndex,
+		startIndexOverscan,
+		startIndexVisible,
+		stopIndexOverscan,
+		stopIndexVisible,
+	};
+}

package/src/hooks/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,10 @@
+import { useEffect, useLayoutEffect } from 'octane';
+
+export function useIsomorphicLayoutEffect(
+	effect: () => void | (() => void),
+	dependencies: unknown[] | undefined,
+	slot?: symbol,
+): void {
+	const hook = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+	hook(effect, dependencies, slot);
+}

package/src/hooks/useMemoizedObject.ts

@@ -0,0 +1,14 @@
+import { useMemo } from 'octane';
+import { getSlot, subSlot } from '../internal.js';
+
+export function useMemoizedObject<Type extends object>(
+	unstableObject: Type,
+	...rest: unknown[]
+): Type {
+	const slot = getSlot(rest);
+	return useMemo(
+		() => unstableObject,
+		Object.values(unstableObject),
+		subSlot(slot, 'memoized-object'),
+	);
+}

package/src/hooks/useResizeObserver.ts

@@ -0,0 +1,98 @@
+import { useMemo, useState } from 'octane';
+import type { CSSProperties } from 'react';
+import { getSlot, subSlot } from '../internal.js';
+import { parseNumericStyleValue } from '../utils/parseNumericStyleValue.js';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect.js';
+
+export function useResizeObserver(
+	{
+		box,
+		defaultHeight,
+		defaultWidth,
+		disabled: disabledProp,
+		element,
+		mode,
+		style,
+	}: {
+		box?: ResizeObserverBoxOptions;
+		defaultHeight?: number;
+		defaultWidth?: number;
+		disabled?: boolean;
+		element: HTMLElement | null;
+		mode?: 'only-height' | 'only-width';
+		style: CSSProperties | undefined;
+	},
+	...rest: unknown[]
+) {
+	const slot = getSlot(rest);
+	const { styleHeight, styleWidth } = useMemo(
+		() => ({
+			styleHeight: parseNumericStyleValue(style?.height),
+			styleWidth: parseNumericStyleValue(style?.width),
+		}),
+		[style?.height, style?.width],
+		subSlot(slot, 'styles'),
+	);
+
+	const [state, setState] = useState<{
+		height: number | undefined;
+		width: number | undefined;
+	}>(
+		{
+			height: defaultHeight,
+			width: defaultWidth,
+		},
+		subSlot(slot, 'state'),
+	);
+
+	const disabled =
+		disabledProp ||
+		(mode === 'only-height' && styleHeight !== undefined) ||
+		(mode === 'only-width' && styleWidth !== undefined) ||
+		(styleHeight !== undefined && styleWidth !== undefined);
+
+	useIsomorphicLayoutEffect(
+		() => {
+			if (element === null || disabled) {
+				return;
+			}
+
+			const resizeObserver = new ResizeObserver((entries) => {
+				for (const entry of entries) {
+					const { contentRect, target } = entry;
+					if (element === target) {
+						setState((prevState) => {
+							if (
+								prevState.height === contentRect.height &&
+								prevState.width === contentRect.width
+							) {
+								return prevState;
+							}
+
+							return {
+								height: contentRect.height,
+								width: contentRect.width,
+							};
+						});
+					}
+				}
+			});
+			resizeObserver.observe(element, { box });
+
+			return () => {
+				resizeObserver?.unobserve(element);
+			};
+		},
+		[box, disabled, element, styleHeight, styleWidth],
+		subSlot(slot, 'observer'),
+	);
+
+	return useMemo(
+		() => ({
+			height: styleHeight ?? state.height,
+			width: styleWidth ?? state.width,
+		}),
+		[state, styleHeight, styleWidth],
+		subSlot(slot, 'result'),
+	);
+}

package/src/hooks/useStableCallback.ts

@@ -0,0 +1,39 @@
+import { useCallback, useRef } from 'octane';
+import { getSlot, subSlot } from '../internal.js';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect.js';
+
+// Forked from useEventCallback (usehooks-ts)
+export function useStableCallback<Args extends unknown[], Return>(
+	fn: (...args: Args) => Return,
+	...rest: unknown[]
+): (...args: Args) => Return;
+export function useStableCallback<Args extends unknown[], Return>(
+	fn: ((...args: Args) => Return) | undefined,
+	...rest: unknown[]
+): ((...args: Args) => Return) | undefined;
+export function useStableCallback<Args extends unknown[], Return>(
+	fn: ((...args: Args) => Return) | undefined,
+	...rest: unknown[]
+): ((...args: Args) => Return) | undefined {
+	const slot = getSlot(rest);
+	const ref = useRef<typeof fn>(
+		() => {
+			throw new Error('Cannot call an event handler while rendering.');
+		},
+		subSlot(slot, 'ref'),
+	);
+
+	useIsomorphicLayoutEffect(
+		() => {
+			ref.current = fn;
+		},
+		[fn],
+		subSlot(slot, 'effect'),
+	);
+
+	return useCallback(
+		(...args: Args) => ref.current?.(...args),
+		[ref],
+		subSlot(slot, 'callback'),
+	) as (...args: Args) => Return;
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { Grid } from './components/grid/Grid.js';
+export {
+	type CellComponentProps,
+	type GridImperativeAPI,
+	type GridProps,
+} from './components/grid/types.js';
+export { useGridCallbackRef } from './components/grid/useGridCallbackRef.js';
+export { useGridRef } from './components/grid/useGridRef.js';
+export { List } from './components/list/List.js';
+export {
+	type DynamicRowHeight,
+	type ListImperativeAPI,
+	type ListProps,
+	type RowComponentProps,
+} from './components/list/types.js';
+export { useDynamicRowHeight } from './components/list/useDynamicRowHeight.js';
+export { useListCallbackRef } from './components/list/useListCallbackRef.js';
+export { useListRef } from './components/list/useListRef.js';
+export { type Align } from './types.js';
+export { getScrollbarSize } from './utils/getScrollbarSize.js';

package/src/internal.ts

@@ -0,0 +1,37 @@
+// Octane appends a compiler-owned hook slot to public hook calls. Binding
+// internals derive stable child slots so composed hooks and sibling
+// virtualizers never share state.
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareTagCache = new Map<string, symbol>();
+
+export function getSlot(args: unknown[]): symbol | undefined {
+	const slot = args.at(-1);
+	return typeof slot === 'symbol' ? slot : undefined;
+}
+
+export function getPublicArgument(args: unknown[], index: number): unknown {
+	const publicLength = getSlot(args) === undefined ? args.length : args.length - 1;
+	return index < publicLength ? args[index] : undefined;
+}
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) {
+			bare = Symbol.for(`@octanejs/window:${tag}`);
+			bareTagCache.set(tag, bare);
+		}
+		return bare;
+	}
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) {
+		byTag = new Map();
+		subSlotCache.set(slot, byTag);
+	}
+	let child = byTag.get(tag);
+	if (child === undefined) {
+		child = Symbol.for(`${slot.description ?? ''}:${tag}`);
+		byTag.set(tag, child);
+	}
+	return child;
+}

package/src/types.ts

@@ -0,0 +1,5 @@
+import type { JSX } from 'react';
+
+export type Align = 'auto' | 'center' | 'end' | 'smart' | 'start';
+
+export type TagNames = keyof JSX.IntrinsicElements;

package/src/utils/adjustScrollOffsetForRtl.ts

@@ -0,0 +1,35 @@
+import type { Direction } from '../core/types.js';
+import { getRTLOffsetType } from './getRTLOffsetType.js';
+
+export function adjustScrollOffsetForRtl({
+	containerElement,
+	direction,
+	isRtl,
+	scrollOffset,
+}: {
+	containerElement: HTMLElement | null;
+	direction: Direction;
+	isRtl: boolean;
+	scrollOffset: number;
+}) {
+	// TRICKY According to the spec, scrollLeft should be negative for RTL aligned elements.
+	// This is not the case for all browsers though (e.g. Chrome reports values as positive, measured relative to the left).
+	// So we need to determine which browser behavior we're dealing with, and mimic it.
+	if (direction === 'horizontal') {
+		if (isRtl) {
+			switch (getRTLOffsetType()) {
+				case 'negative': {
+					return -scrollOffset;
+				}
+				case 'positive-descending': {
+					if (containerElement) {
+						const { clientWidth, scrollLeft, scrollWidth } = containerElement;
+						return scrollWidth - clientWidth - scrollLeft;
+					}
+					break;
+				}
+			}
+		}
+	}
+	return scrollOffset;
+}

package/src/utils/areArraysEqual.ts

@@ -0,0 +1,13 @@
+export function areArraysEqual(a: unknown[], b: unknown[]) {
+	if (a.length !== b.length) {
+		return false;
+	}
+
+	for (let index = 0; index < a.length; index++) {
+		if (!Object.is(a[index], b[index])) {
+			return false;
+		}
+	}
+
+	return true;
+}

package/src/utils/arePropsEqual.ts

@@ -0,0 +1,19 @@
+import type { CSSProperties } from 'react';
+import { shallowCompare } from './shallowCompare.js';
+
+// Custom comparison function for React.memo()
+// It knows to compare individual style props and ignore the wrapper object.
+// See https://react.dev/reference/react/memo#memo
+export function arePropsEqual(
+	prevProps: { ariaAttributes: object; style: CSSProperties },
+	nextProps: { ariaAttributes: object; style: CSSProperties },
+): boolean {
+	const { ariaAttributes: prevAriaAttributes, style: prevStyle, ...prevRest } = prevProps;
+	const { ariaAttributes: nextAriaAttributes, style: nextStyle, ...nextRest } = nextProps;
+
+	return (
+		shallowCompare(prevAriaAttributes, nextAriaAttributes) &&
+		shallowCompare(prevStyle, nextStyle) &&
+		shallowCompare(prevRest, nextRest)
+	);
+}

package/src/utils/assert.ts

@@ -0,0 +1,10 @@
+export function assert(
+	expectedCondition: unknown,
+	message: string = 'Assertion error',
+): asserts expectedCondition {
+	if (!expectedCondition) {
+		console.error(message);
+
+		throw Error(message);
+	}
+}

package/src/utils/colors/getContrastColor.ts

@@ -0,0 +1,47 @@
+export function getContrastColor(hex: string) {
+	switch (hex.length) {
+		case 3: {
+			hex =
+				hex.charAt(0) +
+				hex.charAt(0) +
+				hex.charAt(1) +
+				hex.charAt(1) +
+				hex.charAt(2) +
+				hex.charAt(2);
+			break;
+		}
+		case 4: {
+			hex =
+				hex.charAt(1) +
+				hex.charAt(1) +
+				hex.charAt(2) +
+				hex.charAt(2) +
+				hex.charAt(3) +
+				hex.charAt(3);
+			break;
+		}
+		case 6: {
+			break;
+		}
+		case 7: {
+			hex = hex.substring(1);
+			break;
+		}
+		default: {
+			throw Error(`Invalid hex value: "${hex}"`);
+		}
+	}
+
+	const rgb = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+	if (!rgb) {
+		throw Error(`Invalid hex value: "${hex}"`);
+	}
+
+	const red = parseInt(rgb[1], 16);
+	const green = parseInt(rgb[2], 16);
+	const blue = parseInt(rgb[3], 16);
+
+	const brightness = 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+
+	return brightness >= 128 ? 'black' : 'white';
+}