@octanejs/aria 0.0.4 → 0.0.6

package/src/stately/index.ts

@@ -116,3 +116,46 @@ export type { NumberFieldState, NumberFieldStateOptions } from './numberfield/us
 // slider
 export { useSliderState } from './slider/useSliderState';
 export type { SliderState, SliderStateOptions } from './slider/useSliderState';
+
+// grid — mirrors the @react-stately/grid shim surface.
+export { useGridState } from './grid/useGridState';
+export { GridCollection } from './grid/GridCollection';
+export type { GridStateOptions, GridState } from './grid/useGridState';
+export type { IGridCollection, GridNode, GridRow } from './grid/GridCollection';
+
+// table — mirrors the @react-stately/table shim surface (Section is already
+// exported from the collections section above).
+export { useTableState, UNSTABLE_useFilteredTableState } from './table/useTableState';
+export { useTableColumnResizeState } from './table/useTableColumnResizeState';
+export { UNSTABLE_useTreeGridState } from './table/useTreeGridState';
+export { TableHeader } from './table/TableHeader';
+export { TableBody } from './table/TableBody';
+export { Column } from './table/Column';
+export { Row } from './table/Row';
+export { Cell } from './table/Cell';
+export { TableCollection, buildHeaderRows } from './table/TableCollection';
+export { TableColumnLayout } from './table/TableColumnLayout';
+export type {
+	TableProps,
+	TableState,
+	TableStateProps,
+	CollectionBuilderContext,
+} from './table/useTableState';
+export type {
+	TableColumnResizeState,
+	TableColumnResizeStateProps,
+} from './table/useTableColumnResizeState';
+export type { TreeGridState, TreeGridStateProps } from './table/useTreeGridState';
+export type {
+	ColumnProps,
+	ColumnSize,
+	ColumnDynamicSize,
+	ColumnStaticSize,
+	ColumnElement,
+	ColumnRenderer,
+} from './table/Column';
+export type { TableHeaderProps } from './table/TableHeader';
+export type { TableBodyProps } from './table/TableBody';
+export type { RowProps, RowElement } from './table/Row';
+export type { CellProps, CellElement, CellRenderer } from './table/Cell';
+export type { ITableCollection } from './table/TableCollection';

package/src/stately/table/Cell.ts

@@ -0,0 +1,49 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/table/Cell.ts).
+// octane adaptations: React element types → `any` (octane element descriptors). `<Cell>` is
+// a collection DESCRIPTOR component — it renders nothing; CollectionBuilder walks it via
+// the static `getCollectionNode` generator.
+import type { Key } from '@react-types/shared';
+import type { PartialNode } from '../collections/types';
+
+export interface CellProps {
+	/** The contents of the cell. */
+	children: any;
+	/** A string representation of the cell's contents, used for features like typeahead. */
+	textValue?: string;
+	/** Indicates how many columns the data cell spans. */
+	colSpan?: number;
+}
+
+export type CellElement = any;
+export type CellRenderer = (columnKey: Key) => CellElement;
+
+function Cell(props: CellProps): any {
+	return null;
+}
+
+Cell.getCollectionNode = function* getCollectionNode<T>(
+	props: CellProps,
+): Generator<PartialNode<T>> {
+	let { children } = props;
+
+	let textValue =
+		props.textValue ||
+		(typeof children === 'string' ? children : '') ||
+		(props as any)['aria-label'] ||
+		'';
+	yield {
+		type: 'cell',
+		props: props,
+		rendered: children,
+		textValue,
+		'aria-label': (props as any)['aria-label'],
+		hasChildNodes: false,
+	};
+};
+
+/**
+ * A Cell represents the value of a single Column within a Table Row.
+ */
+// We don't want getCollectionNode to show up in the type definition
+let _Cell = Cell as unknown as (props: CellProps) => any;
+export { _Cell as Cell };

package/src/stately/table/Column.ts

@@ -0,0 +1,121 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/table/Column.ts).
+// octane adaptations: React.Children → octane Children (descriptor arrays); React element
+// types → `any` descriptors. Renders nothing; walked via static `getCollectionNode`.
+import { Children } from 'octane';
+
+import type { CollectionBuilderContext } from './useTableState';
+import type { GridNode } from '../grid/GridCollection';
+import type { PartialNode } from '../collections/types';
+
+/** Widths that result in a constant pixel value for the same Table width. */
+export type ColumnStaticSize = number | `${number}` | `${number}%`; // match regex: /^(\d+)(?=%$)/
+/**
+ * Widths that change size in relation to the remaining space and in ratio to other dynamic columns.
+ * All numbers must be integers and greater than 0.
+ * FR units take up remaining, if any, space in the table.
+ */
+export type ColumnDynamicSize = `${number}fr`; // match regex: /^(\d+)(?=fr$)/
+/** All possible sizes a column can be assigned. */
+export type ColumnSize = ColumnStaticSize | ColumnDynamicSize;
+
+export type ColumnElement<T> = any;
+export type ColumnRenderer<T> = (item: T) => ColumnElement<T>;
+export interface ColumnProps<T> {
+	/** Rendered contents of the column if `children` contains child columns. */
+	title?: any;
+	/** Static child columns or content to render as the column header. */
+	children: any;
+	/** A list of child columns used when dynamically rendering nested child columns. */
+	childColumns?: T[];
+	/** The width of the column. */
+	width?: ColumnSize | null;
+	/** The minimum width of the column. */
+	minWidth?: ColumnStaticSize | null;
+	/** The maximum width of the column. */
+	maxWidth?: ColumnStaticSize | null;
+	/** The default width of the column. */
+	defaultWidth?: ColumnSize | null;
+	/** Whether the column allows resizing. */
+	allowsResizing?: boolean;
+	/** Whether the column allows sorting. */
+	allowsSorting?: boolean;
+	/**
+	 * Whether a column is a [row header](https://www.w3.org/TR/wai-aria-1.1/#rowheader) and should be
+	 * announced by assistive technology during row navigation.
+	 */
+	isRowHeader?: boolean;
+	/** A string representation of the column's contents, used for accessibility announcements. */
+	textValue?: string;
+}
+
+function Column<T>(props: ColumnProps<T>): any {
+	return null;
+}
+
+Column.getCollectionNode = function* getCollectionNode<T>(
+	props: ColumnProps<T>,
+	context: CollectionBuilderContext<T>,
+): Generator<PartialNode<T>, void, GridNode<T>[]> {
+	let { title, children, childColumns } = props;
+
+	let rendered = title || children;
+	let textValue =
+		props.textValue ||
+		(typeof rendered === 'string' ? rendered : '') ||
+		(props as any)['aria-label'];
+
+	let fullNodes = yield {
+		type: 'column',
+		hasChildNodes: !!childColumns || (!!title && Children.count(children) > 0),
+		rendered,
+		textValue,
+		props,
+		*childNodes() {
+			if (childColumns) {
+				for (let child of childColumns) {
+					yield {
+						type: 'column',
+						value: child,
+					};
+				}
+			} else if (title) {
+				let childColumns: PartialNode<T>[] = [];
+				Children.forEach(children, (child: any) => {
+					childColumns.push({
+						type: 'column',
+						element: child,
+					});
+				});
+
+				yield* childColumns;
+			}
+		},
+		shouldInvalidate(newContext: CollectionBuilderContext<T>) {
+			// This is a bit of a hack, but it works.
+			// If this method is called, then there's a cached version of this node available.
+			// But, we need to keep the list of columns in the new context up to date.
+			updateContext(newContext);
+			return false;
+		},
+	};
+
+	let updateContext = (context: CollectionBuilderContext<T>) => {
+		// register leaf columns on the context so that <Row> can access them
+		for (let node of fullNodes) {
+			if (!node.hasChildNodes) {
+				context.columns.push(node);
+			}
+		}
+	};
+
+	updateContext(context);
+};
+
+/**
+ * A Column represents a field of each item within a Table. Columns may also contain nested
+ * Column elements to represent column groups. Nested columns can be statically defined as
+ * children, or dynamically generated using a function based on the `childColumns` prop.
+ */
+// We don't want getCollectionNode to show up in the type definition
+let _Column = Column as unknown as <T>(props: ColumnProps<T>) => any;
+export { _Column as Column };

package/src/stately/table/Row.ts

@@ -0,0 +1,145 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/table/Row.ts).
+// octane adaptations: React.Children → octane Children (descriptor arrays); React element
+// types → `any` descriptors. Renders nothing; walked via static `getCollectionNode`.
+// The `node.type === Row` check compares against the INTERNAL function identity, which is
+// what descriptor `.type` carries for `<Row>` used at a value position.
+import type { LinkDOMProps } from '@react-types/shared';
+import { Children } from 'octane';
+
+import type { CellElement, CellRenderer } from './Cell';
+import type { CollectionBuilderContext } from './useTableState';
+import type { PartialNode } from '../collections/types';
+
+export type RowElement<T> = any;
+export interface RowProps<T> extends LinkDOMProps {
+	/**
+	 * A list of child item objects used when dynamically rendering row children. Requires the feature
+	 * flag to be enabled along with UNSTABLE_allowsExpandableRows, see
+	 * https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows.
+	 *
+	 * @private
+	 * @version alpha
+	 */
+	UNSTABLE_childItems?: Iterable<T>;
+	// TODO: update when async loading is supported for expandable rows
+	// /** Whether this row has children, even if not loaded yet. */
+	// hasChildItems?: boolean,
+	/** Rendered contents of the row or row child items. */
+	children: CellElement | CellElement[] | CellRenderer;
+	/** A string representation of the row's contents, used for features like typeahead. */
+	textValue?: string; // ???
+}
+
+function Row<T>(props: RowProps<T>): any {
+	return null;
+}
+
+Row.getCollectionNode = function* getCollectionNode<T>(
+	props: RowProps<T>,
+	context: CollectionBuilderContext<T>,
+): Generator<PartialNode<T>> {
+	let { children, textValue, UNSTABLE_childItems } = props;
+
+	yield {
+		type: 'item',
+		props: props,
+		textValue,
+		'aria-label': (props as any)['aria-label'],
+		hasChildNodes: true,
+		*childNodes() {
+			// Process cells first
+			if (context.showDragButtons) {
+				yield {
+					type: 'cell',
+					key: 'header-drag', // this is combined with the row key by CollectionBuilder
+					props: {
+						isDragButtonCell: true,
+					},
+				};
+			}
+
+			if (context.showSelectionCheckboxes && context.selectionMode !== 'none') {
+				yield {
+					type: 'cell',
+					key: 'header', // this is combined with the row key by CollectionBuilder
+					props: {
+						isSelectionCell: true,
+					},
+				};
+			}
+
+			if (typeof children === 'function') {
+				for (let column of context.columns) {
+					yield {
+						type: 'cell',
+						element: children(column.key),
+						key: column.key, // this is combined with the row key by CollectionBuilder
+					};
+				}
+
+				if (UNSTABLE_childItems) {
+					for (let child of UNSTABLE_childItems) {
+						// Note: in order to reuse the render function of TableBody for our child rows, we just need to yield a type and a value here. CollectionBuilder will then look up
+						// the parent renderer and use that to build the full node of this child row, using the value provided here to generate the cells
+						yield {
+							type: 'item',
+							value: child,
+						};
+					}
+				}
+			} else {
+				let cells: PartialNode<T>[] = [];
+				let childRows: PartialNode<T>[] = [];
+				let columnCount = 0;
+				Children.forEach(children, (node: any) => {
+					if (node.type === Row) {
+						if (cells.length < context.columns.length) {
+							throw new Error(
+								"All of a Row's child Cells must be positioned before any child Rows.",
+							);
+						}
+
+						childRows.push({
+							type: 'item',
+							element: node,
+						});
+					} else {
+						cells.push({
+							type: 'cell',
+							element: node,
+						});
+						columnCount += node.props.colSpan ?? 1;
+					}
+				});
+
+				if (columnCount !== context.columns.length) {
+					throw new Error(
+						`Cell count must match column count. Found ${columnCount} cells and ${context.columns.length} columns.`,
+					);
+				}
+
+				yield* cells;
+				yield* childRows;
+			}
+		},
+		shouldInvalidate(newContext: CollectionBuilderContext<T>) {
+			// Invalidate all rows if the columns changed.
+			return (
+				newContext.columns.length !== context.columns.length ||
+				newContext.columns.some((c, i) => c.key !== context.columns[i].key) ||
+				newContext.showSelectionCheckboxes !== context.showSelectionCheckboxes ||
+				newContext.showDragButtons !== context.showDragButtons ||
+				newContext.selectionMode !== context.selectionMode
+			);
+		},
+	};
+};
+
+/**
+ * A Row represents a single item in a Table and contains Cell elements for each column.
+ * Cells can be statically defined as children, or generated dynamically using a function
+ * based on the columns defined in the TableHeader.
+ */
+// We don't want getCollectionNode to show up in the type definition
+let _Row = Row as unknown as <T>(props: RowProps<T>) => any;
+export { _Row as Row };

package/src/stately/table/TableBody.ts

@@ -0,0 +1,66 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/table/TableBody.ts).
+// octane adaptations: React.Children → octane Children (descriptor arrays); React element
+// types → `any` descriptors. Renders nothing; walked via static `getCollectionNode`.
+import type { AsyncLoadable, LoadingState } from '@react-types/shared';
+import { Children } from 'octane';
+
+import type { PartialNode } from '../collections/types';
+import type { RowElement } from './Row';
+
+export interface TableBodyProps<T> extends Omit<AsyncLoadable, 'isLoading'> {
+	/** The contents of the table body. Supports static items or a function for dynamic rendering. */
+	children: RowElement<T> | RowElement<T>[] | ((item: T) => RowElement<T>);
+	/** A list of row objects in the table body used when dynamically rendering rows. */
+	items?: Iterable<T>;
+	/** The current loading state of the table. */
+	loadingState?: LoadingState;
+}
+
+function TableBody<T>(props: TableBodyProps<T>): any {
+	return null;
+}
+
+TableBody.getCollectionNode = function* getCollectionNode<T>(
+	props: TableBodyProps<T>,
+): Generator<PartialNode<T>> {
+	let { children, items } = props;
+	yield {
+		type: 'body',
+		hasChildNodes: true,
+		props,
+		*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, (item: any) => {
+					items.push({
+						type: 'item',
+						element: item,
+					});
+				});
+
+				yield* items;
+			}
+		},
+	};
+};
+
+/**
+ * A TableBody is a container for the Row elements of a Table. Rows can be statically defined as
+ * children, or generated dynamically using a function based on the data passed to the `items`
+ * prop.
+ */
+// We don't want getCollectionNode to show up in the type definition
+let _TableBody = TableBody as unknown as <T>(props: TableBodyProps<T>) => any;
+export { _TableBody as TableBody };