@octanejs/window 0.0.1

package/src/components/grid/types.ts

@@ -0,0 +1,334 @@
+import type {
+	ComponentProps,
+	CSSProperties,
+	HTMLAttributes,
+	ReactElement,
+	ReactNode,
+	Ref,
+} from 'react';
+import type { TagNames } from '../../types.js';
+
+type ForbiddenKeys = 'ariaAttributes' | 'columnIndex' | 'rowIndex' | 'style';
+type ExcludeForbiddenKeys<Type> = {
+	[Key in keyof Type]: Key extends ForbiddenKeys ? never : Type[Key];
+};
+
+export type GridProps<CellProps extends object, TagName extends TagNames = 'div'> = Omit<
+	HTMLAttributes<HTMLDivElement>,
+	'onResize'
+> & {
+	/**
+	 * React component responsible for rendering a cell.
+	 *
+	 * This component will receive an `index` and `style` prop by default.
+	 * Additionally it will receive prop values passed to `cellProps`.
+	 *
+	 * ℹ️ The prop types for this component are exported as `CellComponentProps`
+	 */
+	cellComponent: (
+		props: {
+			ariaAttributes: {
+				'aria-colindex': number;
+				role: 'gridcell';
+			};
+			columnIndex: number;
+			rowIndex: number;
+			style: CSSProperties;
+		} & CellProps,
+	) => ReactElement | null;
+
+	/**
+	 * Additional props to be passed to the cell-rendering component.
+	 * Grid will automatically re-render cells when values in this object change.
+	 *
+	 * ⚠️ This object must not contain `ariaAttributes`, `columnIndex`, `rowIndex`, or `style` props.
+	 */
+	cellProps: ExcludeForbiddenKeys<CellProps>;
+
+	/**
+	 * Additional content to be rendered within the grid (above cells).
+	 * This property can be used to render things like overlays or tooltips.
+	 */
+	children?: ReactNode;
+
+	/**
+	 * CSS class name.
+	 */
+	className?: string;
+
+	/**
+	 * Number of columns to be rendered in the grid.
+	 */
+	columnCount: number;
+
+	/**
+	 * Grids use the column index as a `key` by default.
+	 * This prop can be used along with the `rowKey` prop to provide a custom `key` value.
+	 *
+	 * ℹ️ Custom keys can ensure better UX for sortable or filterable grids,
+	 * particularly if your cell 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.
+	 */
+	columnKey?: (args: { columnIndex: number; data: CellProps; rowIndex: number }) => React.Key;
+
+	/**
+	 * Column width; the following formats are supported:
+	 * - number of pixels (number)
+	 * - percentage of the grid's current width (string)
+	 * - function that returns the column width (in pixels) given an index and `cellProps`
+	 */
+	columnWidth: number | string | ((index: number, cellProps: CellProps) => number);
+
+	/**
+	 * Default height of grid for initial render.
+	 * This value is important for server rendering.
+	 */
+	defaultHeight?: number;
+
+	/**
+	 * Default width of grid for initial render.
+	 * This value is important for server rendering.
+	 */
+	defaultWidth?: number;
+
+	/**
+	 * Indicates the directionality of grid cells.
+	 *
+	 * ℹ️ See HTML `dir` [global attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/dir) for more information.
+	 */
+	dir?: 'ltr' | 'rtl';
+
+	/**
+	 * Imperative Grid API.
+	 *
+	 * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
+	 */
+	gridRef?: Ref<{
+		/**
+		 * Outermost HTML element for the grid if mounted and null (if not mounted.
+		 */
+		get element(): HTMLDivElement | null;
+
+		/**
+		 * Scrolls the grid so that the specified row and column are visible.
+		 *
+		 * @param behavior Determines whether scrolling is instant or animates smoothly
+		 * @param columnAlign Determines the horizontal alignment of the element within the list
+		 * @param columnIndex Index of the column to scroll to (0-based)
+		 * @param rowAlign Determines the vertical alignment of the element within the list
+		 * @param rowIndex Index of the row to scroll to (0-based)
+		 *
+		 * @throws RangeError if an invalid row or column index is provided
+		 */
+		scrollToCell(config: {
+			behavior?: 'auto' | 'instant' | 'smooth';
+			columnAlign?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+			columnIndex: number;
+			rowAlign?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+			rowIndex: number;
+		}): void;
+
+		/**
+		 * Scrolls the grid so that the specified column is visible.
+		 *
+		 * @param align Determines the horizontal alignment of the element within the list
+		 * @param behavior Determines whether scrolling is instant or animates smoothly
+		 * @param index Index of the column to scroll to (0-based)
+		 *
+		 * @throws RangeError if an invalid column index is provided
+		 */
+		scrollToColumn(config: {
+			align?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+			behavior?: 'auto' | 'instant' | 'smooth';
+			index: number;
+		}): void;
+
+		/**
+		 * Scrolls the grid 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 range of rendered cells changes.
+	 */
+	onCellsRendered?: (
+		visibleCells: {
+			columnStartIndex: number;
+			columnStopIndex: number;
+			rowStartIndex: number;
+			rowStopIndex: number;
+		},
+		allCells: {
+			columnStartIndex: number;
+			columnStopIndex: number;
+			rowStartIndex: number;
+			rowStopIndex: number;
+		},
+	) => void;
+
+	/**
+	 * Callback notified when the Grid's outermost HTMLElement resizes.
+	 * This may be used to (re)scroll a cell into view.
+	 */
+	onResize?: (
+		size: { height: number; width: number },
+		prevSize: { height: number; width: number },
+	) => void;
+
+	/**
+	 * How many additional rows/columns to render outside of the visible area.
+	 * This can reduce visual flickering near the edges of a grid when scrolling.
+	 */
+	overscanCount?: number;
+
+	/**
+	 * Number of rows to be rendered in the grid.
+	 */
+	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`
+	 */
+	rowHeight: number | string | ((index: number, cellProps: CellProps) => number);
+
+	/**
+	 * Grids use the row index as a `key` by default.
+	 * This prop can be used along with the `columnKey` prop to provide a custom `key` value.
+	 *
+	 * ℹ️ Custom keys can ensure better UX for sortable or filterable grids,
+	 * particularly if your cell 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?: (args: { data: CellProps; rowIndex: number }) => React.Key;
+
+	/**
+	 * Optional CSS properties.
+	 * The grid of cells will fill the height and width 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 CellComponent<CellProps extends object> = GridProps<CellProps>['cellComponent'];
+export type CellComponentProps<CellProps extends object = object> = ComponentProps<
+	CellComponent<CellProps>
+>;
+
+export type ScrollState = {
+	prevScrollTop: number;
+	scrollTop: number;
+};
+
+export type OnCellsRendered = NonNullable<GridProps<object>['onCellsRendered']>;
+
+export type CachedBounds = Map<
+	number,
+	{
+		height: number;
+		scrollTop: 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 `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
+ */
+export interface GridImperativeAPI {
+	/**
+	 * Outermost HTML element for the grid if mounted and null (if not mounted.
+	 */
+	get element(): HTMLDivElement | null;
+
+	/**
+	 * Scrolls the grid so that the specified row and column are visible.
+	 *
+	 * @param behavior Determines whether scrolling is instant or animates smoothly
+	 * @param columnAlign Determines the horizontal alignment of the element within the list
+	 * @param columnIndex Index of the column to scroll to (0-based)
+	 * @param rowAlign Determines the vertical alignment of the element within the list
+	 * @param rowIndex Index of the row to scroll to (0-based)
+	 *
+	 * @throws RangeError if an invalid row or column index is provided
+	 */
+	scrollToCell: ({
+		behavior,
+		columnAlign,
+		columnIndex,
+		rowAlign,
+		rowIndex,
+	}: {
+		behavior?: 'auto' | 'instant' | 'smooth';
+		columnAlign?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+		columnIndex: number;
+		rowAlign?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+		rowIndex: number;
+	}) => void;
+
+	/**
+	 * Scrolls the grid so that the specified column is visible.
+	 *
+	 * @param align Determines the horizontal alignment of the element within the list
+	 * @param behavior Determines whether scrolling is instant or animates smoothly
+	 * @param index Index of the column to scroll to (0-based)
+	 *
+	 * @throws RangeError if an invalid column index is provided
+	 */
+	scrollToColumn: ({
+		align,
+		behavior,
+		index,
+	}: {
+		align?: 'auto' | 'center' | 'end' | 'smart' | 'start';
+		behavior?: 'auto' | 'instant' | 'smooth';
+		index: number;
+	}) => void;
+
+	/**
+	 * Scrolls the grid 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/grid/useGridCallbackRef.ts

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

package/src/components/grid/useGridRef.ts

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

package/src/components/list/List.tsx

@@ -0,0 +1,216 @@
+/** @jsxImportSource octane */
+'use client';
+
+import { createElement, memo, useEffect, useImperativeHandle, useMemo, useState } from 'octane';
+import { useVirtualizer } from '../../core/useVirtualizer.js';
+import { useIsomorphicLayoutEffect } from '../../hooks/useIsomorphicLayoutEffect.js';
+import { useMemoizedObject } from '../../hooks/useMemoizedObject.js';
+import type { Align, TagNames } from '../../types.js';
+import { arePropsEqual } from '../../utils/arePropsEqual.js';
+import { isDynamicRowHeight as isDynamicRowHeightUtil } from './isDynamicRowHeight.js';
+import type { ListProps } from './types.js';
+
+export const DATA_ATTRIBUTE_LIST_INDEX = 'data-react-window-index';
+
+/**
+ * Renders data with many rows.
+ */
+export function List<RowProps extends object, TagName extends TagNames = 'div'>({
+	children,
+	className,
+	defaultHeight = 0,
+	listRef,
+	onResize,
+	onRowsRendered,
+	overscanCount = 3,
+	rowComponent: RowComponentProp,
+	rowCount,
+	rowHeight: rowHeightProp,
+	rowKey,
+	rowProps: rowPropsUnstable,
+	tagName = 'div' as TagName,
+	style,
+	...rest
+}: ListProps<RowProps, TagName>) {
+	const rowProps = useMemoizedObject(rowPropsUnstable);
+	const RowComponent = useMemo(
+		() => memo(RowComponentProp as any, arePropsEqual as any) as typeof RowComponentProp,
+		[RowComponentProp],
+	);
+
+	const [element, setElement] = useState<HTMLDivElement | null>(null);
+
+	const isDynamicRowHeight = isDynamicRowHeightUtil(rowHeightProp);
+
+	const rowHeight = useMemo(() => {
+		if (isDynamicRowHeight) {
+			return (index: number) => {
+				return rowHeightProp.getRowHeight(index) ?? rowHeightProp.getAverageRowHeight();
+			};
+		}
+
+		return rowHeightProp;
+	}, [isDynamicRowHeight, rowHeightProp]);
+
+	const {
+		getCellBounds,
+		getEstimatedSize,
+		scrollToIndex,
+		startIndexOverscan,
+		startIndexVisible,
+		stopIndexOverscan,
+		stopIndexVisible,
+	} = useVirtualizer({
+		containerElement: element,
+		containerStyle: style,
+		defaultContainerSize: defaultHeight,
+		direction: 'vertical',
+		itemCount: rowCount,
+		itemProps: rowProps,
+		itemSize: rowHeight,
+		onResize,
+		overscanCount,
+	});
+
+	useImperativeHandle(
+		listRef,
+		() => ({
+			get element() {
+				return element;
+			},
+
+			scrollToRow({
+				align = 'auto',
+				behavior = 'auto',
+				index,
+			}: {
+				align?: Align;
+				behavior?: ScrollBehavior;
+				index: number;
+			}) {
+				const top = scrollToIndex({
+					align,
+					containerScrollOffset: element?.scrollTop ?? 0,
+					index,
+				});
+
+				if (typeof element?.scrollTo === 'function') {
+					element.scrollTo({
+						behavior,
+						top,
+					});
+				}
+			},
+		}),
+		[element, scrollToIndex],
+	);
+
+	useIsomorphicLayoutEffect(() => {
+		if (!element) {
+			return;
+		}
+
+		const rows = Array.from(element.children).filter((item, index) => {
+			if (item.hasAttribute('aria-hidden')) {
+				// Ignore sizing element
+				return false;
+			}
+
+			const attribute = `${startIndexOverscan + index}`;
+			item.setAttribute(DATA_ATTRIBUTE_LIST_INDEX, attribute);
+
+			return true;
+		});
+
+		if (isDynamicRowHeight) {
+			return rowHeightProp.observeRowElements(rows);
+		}
+	}, [element, isDynamicRowHeight, rowHeightProp, startIndexOverscan, stopIndexOverscan]);
+
+	useEffect(() => {
+		if (startIndexOverscan >= 0 && stopIndexOverscan >= 0 && onRowsRendered) {
+			onRowsRendered(
+				{
+					startIndex: startIndexVisible,
+					stopIndex: stopIndexVisible,
+				},
+				{
+					startIndex: startIndexOverscan,
+					stopIndex: stopIndexOverscan,
+				},
+			);
+		}
+	}, [onRowsRendered, startIndexOverscan, startIndexVisible, stopIndexOverscan, stopIndexVisible]);
+
+	const rows = useMemo(() => {
+		const children: unknown[] = [];
+		if (rowCount > 0) {
+			for (let index = startIndexOverscan; index <= stopIndexOverscan; index++) {
+				const bounds = getCellBounds(index);
+
+				children.push(
+					<RowComponent
+						{...(rowProps as RowProps)}
+						ariaAttributes={{
+							'aria-posinset': index + 1,
+							'aria-setsize': rowCount,
+							role: 'listitem',
+						}}
+						key={rowKey ? rowKey(index, rowProps) : index}
+						index={index}
+						style={{
+							position: 'absolute',
+							left: 0,
+							transform: `translateY(${bounds.scrollOffset}px)`,
+							// In case of dynamic row heights, don't specify a height style
+							// otherwise a default/estimated height would mask the actual height
+							height: isDynamicRowHeight ? undefined : bounds.size,
+							width: '100%',
+						}}
+					/>,
+				);
+			}
+		}
+		return children;
+	}, [
+		RowComponent,
+		getCellBounds,
+		isDynamicRowHeight,
+		rowCount,
+		rowKey,
+		rowProps,
+		startIndexOverscan,
+		stopIndexOverscan,
+	]);
+
+	const sizingElement = (
+		<div
+			aria-hidden
+			style={{
+				height: getEstimatedSize(),
+				width: '100%',
+				zIndex: -1,
+			}}
+		></div>
+	);
+
+	return createElement(
+		tagName,
+		{
+			role: 'list',
+			...rest,
+			className,
+			ref: setElement,
+			style: {
+				position: 'relative',
+				maxHeight: '100%',
+				flexGrow: 1,
+				overflowY: 'auto',
+				...style,
+			},
+		},
+		rows,
+		children,
+		sizingElement,
+	);
+}

package/src/components/list/isDynamicRowHeight.ts

@@ -0,0 +1,10 @@
+import type { DynamicRowHeight } from './types.js';
+
+export function isDynamicRowHeight(value: unknown): value is DynamicRowHeight {
+	return (
+		value != null &&
+		typeof value === 'object' &&
+		'getAverageRowHeight' in value &&
+		typeof value.getAverageRowHeight === 'function'
+	);
+}