@octanejs/aria 0.0.46 → 0.0.48

package/src/stately/virtualizer/ScrollAnchor.tsx

@@ -0,0 +1,338 @@
+/** @jsxImportSource octane */
+// Ported from adobe/react-spectrum@5ecb3333001313e83898cd07644227897e3bae1f (packages/react-stately/src/virtualizer/ScrollAnchor.ts).
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { Key } from '@react-types/shared';
+import { LayoutInfo } from './LayoutInfo';
+import { Rect, RectCorner } from './Rect';
+import { Size } from './Size';
+
+export type ScrollAnchorAxis = 'x' | 'y';
+export type ScrollAnchorEdge = 'start' | 'end';
+export interface ScrollAnchor {
+	key: Key;
+	corner: RectCorner;
+	offset: number;
+}
+
+export interface ScrollAnchorInfo {
+	/** Which edge of the content the viewport should stay anchored to. */
+	edge: 'start' | 'end';
+	/** Which axis `edge` refers to — 'y' for vertical lists, 'x' for horizontal. */
+	axis: 'x' | 'y';
+	/** Distance (px) from `edge` within which the viewport is considered "following" it. */
+	threshold: number;
+	/**
+	 * Optional classifier excluding structural/ephemeral layout infos (e.g. loaders) from being
+	 * selected as the anchor. Defaults to allowing any layoutInfo.
+	 */
+	isAnchorable?: (layoutInfo: LayoutInfo) => boolean;
+}
+
+/**
+ * Minimum overlap an item must have with the viewport, along the scroll axis,
+ * to be eligible as a scroll anchor. Without this, an item that only overlaps the viewport
+ * by a sliver (e.g. 1px, essentially scrolled out of view) can still "win" the anchor
+ * tie-break over a substantially visible item.
+ */
+const MIN_ANCHOR_OVERLAP = 4;
+
+function dimensionForAxis(axis: ScrollAnchorAxis): 'width' | 'height' {
+	return axis === 'x' ? 'width' : 'height';
+}
+
+/**
+ * Given a previously-captured anchor, computes the new viewport coordinate (along `axis`) needed
+ * to keep it at the same offset from the viewport's start.
+ */
+export function computeScrollAnchorTarget(
+	anchor: ScrollAnchor,
+	axis: ScrollAnchorAxis,
+	getLayoutInfo: (key: Key) => LayoutInfo | null,
+	visibleRect: Rect,
+	contentSize: Size,
+): number | null {
+	let finalInfo = getLayoutInfo(anchor.key);
+	if (!finalInfo) {
+		return null;
+	}
+	let adjustment = finalInfo.rect[anchor.corner][axis] - visibleRect[axis] - anchor.offset;
+	if (adjustment === 0) {
+		return null;
+	}
+	let target = visibleRect[axis] + adjustment;
+	let dimension = dimensionForAxis(axis);
+	let max = Math.max(0, contentSize[dimension] - visibleRect[dimension]);
+	let clamped = Math.max(0, Math.min(max, target));
+	return clamped !== visibleRect[axis] ? clamped : null;
+}
+
+/**
+ * Picks the item to anchor scroll to: the one nearest the top of the viewport when
+ * anchoring to 'end', or nearest the bottom when anchoring to 'start'. Callers can
+ * exclude certain items (like loaders) with `isAnchorable`.
+ */
+export function captureScrollAnchor(
+	edge: ScrollAnchorEdge,
+	axis: ScrollAnchorAxis,
+	visibleRect: Rect,
+	visibleLayoutInfos: Iterable<[Key, LayoutInfo]>,
+	isAnchorable: (layoutInfo: LayoutInfo) => boolean = () => true,
+): ScrollAnchor | null {
+	let dimension = dimensionForAxis(axis);
+	let best: ScrollAnchor | null = null;
+	for (let [key, layoutInfo] of visibleLayoutInfos) {
+		if (!layoutInfo || !isAnchorable(layoutInfo)) {
+			continue;
+		}
+		let overlap = layoutInfo.rect.intersection(visibleRect)[dimension];
+		if (layoutInfo.rect.area > 0 && overlap >= MIN_ANCHOR_OVERLAP) {
+			let corner = layoutInfo.rect.getCornerInRect(visibleRect) ?? 'topLeft';
+			let offset = layoutInfo.rect[corner][axis] - visibleRect[axis];
+			let isBetter = !best || (edge === 'end' ? offset < best.offset : offset > best.offset);
+			if (isBetter) {
+				best = { key, corner, offset };
+			}
+		}
+	}
+	return best;
+}
+
+/** Returns the viewport coordinate (along `axis`) that pins the viewport to `edge` of the content. */
+export function getEdgeSnapTarget(
+	edge: ScrollAnchorEdge,
+	axis: ScrollAnchorAxis,
+	contentSize: Size,
+	previousVisibleRect: Rect,
+): number {
+	if (edge === 'start') {
+		return 0;
+	}
+	let dimension = dimensionForAxis(axis);
+	return Math.max(0, contentSize[dimension] - previousVisibleRect[dimension]);
+}
+
+/**
+ * Whether the viewport is currently within `threshold` px of the anchored edge — used by
+ * Virtualizer to compute wasNearAnchorEdge generically, without any layout-specific state.
+ */
+export function isNearEdge(
+	visibleRect: Rect,
+	contentSize: Size,
+	edge: ScrollAnchorEdge,
+	axis: ScrollAnchorAxis,
+	threshold: number,
+): boolean {
+	if (edge === 'start') {
+		return visibleRect[axis] <= threshold;
+	}
+	let dimension = dimensionForAxis(axis);
+	let distanceFromEnd = contentSize[dimension] - (visibleRect[axis] + visibleRect[dimension]);
+	return distanceFromEnd <= threshold;
+}
+
+/**
+ * Works out the new scroll position after content changes. Tries to keep the anchor
+ * item where it was. If that doesn't apply, sticks the view to the edge instead, but
+ * only if the user was already near the edge and didn't just scroll away on their own.
+ */
+export function resolveScrollAdjustment(
+	edge: ScrollAnchorEdge,
+	axis: ScrollAnchorAxis,
+	anchor: ScrollAnchor | null,
+	wasNearAnchorEdge: boolean,
+	isScrolling: boolean,
+	itemSizeChanged: boolean,
+	contentSizeDelta: number,
+	getLayoutInfo: (key: Key) => LayoutInfo | null,
+	previousVisibleRect: Rect,
+	contentSize: Size,
+): Rect | null {
+	let withTarget = (target: number): Rect =>
+		axis === 'x'
+			? new Rect(
+					target,
+					previousVisibleRect.y,
+					previousVisibleRect.width,
+					previousVisibleRect.height,
+				)
+			: new Rect(
+					previousVisibleRect.x,
+					target,
+					previousVisibleRect.width,
+					previousVisibleRect.height,
+				);
+
+	if (anchor) {
+		let target = computeScrollAnchorTarget(
+			anchor,
+			axis,
+			getLayoutInfo,
+			previousVisibleRect,
+			contentSize,
+		);
+		if (target != null) {
+			return withTarget(target);
+		}
+	}
+
+	if (wasNearAnchorEdge && !isScrolling && (!itemSizeChanged || contentSizeDelta > 0)) {
+		let target = withTarget(getEdgeSnapTarget(edge, axis, contentSize, previousVisibleRect));
+		return target.equals(previousVisibleRect) ? null : target;
+	}
+
+	return null;
+}
+
+export interface ResolveAfterLayoutOptions {
+	anchorInfo: ScrollAnchorInfo | null;
+	/** The anchor captured by `captureBeforeLayout` before this pass's `layout.update()` ran. */
+	anchor: ScrollAnchor | null;
+	/** The full post-layout visible layout infos, i.e. `virtualizer.getVisibleLayoutInfos()`. */
+	postLayoutInfos: Map<Key, LayoutInfo>;
+	previousVisibleRect: Rect;
+	previousContentSize: Size;
+	contentSize: Size;
+	itemSizeChanged: boolean;
+	isScrolling: boolean;
+	getLayoutInfo: (key: Key) => LayoutInfo | null;
+}
+
+/**
+ * Tracks the cross-pass state needed to keep the viewport anchored to a layout's edge across
+ * relayouts.
+ */
+export class ScrollAnchorTracker {
+	private hasSnappedToEdge = false;
+	private hadEstimatedVisibleItems = false;
+	private wasNearAnchorEdge = false;
+
+	/** Resets all tracked state, e.g. when the virtualizer's layout instance changes. */
+	reset(): void {
+		this.hasSnappedToEdge = false;
+		this.hadEstimatedVisibleItems = false;
+		this.wasNearAnchorEdge = false;
+	}
+
+	/**
+	 * Captures the anchor from pre-layout view positions.
+	 */
+	captureBeforeLayout(
+		anchorInfo: ScrollAnchorInfo | null,
+		preLayoutInfos: Iterable<[Key, LayoutInfo]>,
+		visibleRect: Rect,
+	): ScrollAnchor | null {
+		if (!anchorInfo) {
+			return null;
+		}
+		return captureScrollAnchor(
+			anchorInfo.edge,
+			anchorInfo.axis,
+			visibleRect,
+			preLayoutInfos,
+			anchorInfo.isAnchorable,
+		);
+	}
+
+	/**
+	 * Runs the full post-layout decision: updates the tracked state for the next pass, and
+	 * returns the resolved scroll target, or null if nothing should change.
+	 */
+	resolveAfterLayout(options: ResolveAfterLayoutOptions): Rect | null {
+		let {
+			anchorInfo,
+			anchor,
+			postLayoutInfos,
+			previousVisibleRect,
+			previousContentSize,
+			contentSize,
+			itemSizeChanged,
+			isScrolling,
+			getLayoutInfo,
+		} = options;
+
+		if (!anchorInfo) {
+			return null;
+		}
+
+		// Read the previous pass's state into locals before any writes below overwrite it.
+		let wasSettlingLastPass = this.hadEstimatedVisibleItems;
+		let wasNearAnchorEdgeLastPass = this.wasNearAnchorEdge;
+
+		let hasEstimated = false;
+		for (let layoutInfo of postLayoutInfos.values()) {
+			if (layoutInfo.estimatedSize) {
+				hasEstimated = true;
+				break;
+			}
+		}
+		this.hadEstimatedVisibleItems = hasEstimated;
+		// Don't recheck "near edge?" mid-resize because it could look like a scroll that never happened.
+		// Reuse the answer from before the resizing started.
+		if (!wasSettlingLastPass) {
+			this.wasNearAnchorEdge = isNearEdge(
+				previousVisibleRect,
+				previousContentSize,
+				anchorInfo.edge,
+				anchorInfo.axis,
+				anchorInfo.threshold,
+			);
+		}
+
+		if (previousVisibleRect.area === 0) {
+			return null;
+		}
+
+		let dimension = anchorInfo.axis === 'x' ? 'width' : 'height';
+		let contentSizeDelta = contentSize[dimension] - previousContentSize[dimension];
+		let isFirstAnchoredLayout = !this.hasSnappedToEdge;
+		this.hasSnappedToEdge = true;
+
+		// Only modify scroll when content actually changed (or this is the first layout, which always snaps)
+		if (!(isFirstAnchoredLayout || contentSizeDelta !== 0 || itemSizeChanged)) {
+			return null;
+		}
+
+		let wasNearAnchorEdge =
+			isFirstAnchoredLayout ||
+			(wasSettlingLastPass && wasNearAnchorEdgeLastPass) ||
+			isNearEdge(
+				previousVisibleRect,
+				previousContentSize,
+				anchorInfo.edge,
+				anchorInfo.axis,
+				anchorInfo.threshold,
+			);
+		// A first-ever layout always snaps to the edge, even if the raw distance check says
+		// otherwise. Save that real decision here so later passes in this cascade reuse it.
+		if (!wasSettlingLastPass) {
+			this.wasNearAnchorEdge = wasNearAnchorEdge;
+		}
+		// Skip restoring to the captured anchor while still resizing because items above it are also still growing,
+		// and following it would fall short of the edge.
+		let effectiveAnchor =
+			isFirstAnchoredLayout || (wasSettlingLastPass && wasNearAnchorEdgeLastPass) ? null : anchor;
+		return resolveScrollAdjustment(
+			anchorInfo.edge,
+			anchorInfo.axis,
+			effectiveAnchor,
+			wasNearAnchorEdge,
+			isScrolling,
+			itemSizeChanged,
+			contentSizeDelta,
+			getLayoutInfo,
+			previousVisibleRect,
+			contentSize,
+		);
+	}
+}

package/src/stately/virtualizer/Virtualizer.tsx

@@ -26,6 +26,7 @@ import { LayoutInfo } from './LayoutInfo';
 import { OverscanManager } from './OverscanManager';
 import { Point } from './Point';
 import { Rect } from './Rect';
+import { ScrollAnchor, ScrollAnchorTracker } from './ScrollAnchor';
 import { Size } from './Size';
 
 interface VirtualizerOptions<T extends object, V> {
@@ -78,6 +79,7 @@ export class Virtualizer<T extends object, V> {
 	private _invalidationContext: InvalidationContext;
 	private _overscanManager: OverscanManager;
 
+	private _scrollAnchor: ScrollAnchorTracker;
 	constructor(options: VirtualizerOptions<T, V>) {
 		this.delegate = options.delegate;
 		this.collection = options.collection;
@@ -92,6 +94,7 @@ export class Virtualizer<T extends object, V> {
 		this._isScrolling = false;
 		this._invalidationContext = {};
 		this._overscanManager = new OverscanManager();
+		this._scrollAnchor = new ScrollAnchorTracker();
 	}
 
 	/** Returns whether the given key, or an ancestor, is persisted. */
@@ -175,11 +178,50 @@ export class Virtualizer<T extends object, V> {
 
 	private relayout(context: InvalidationContext = {}) {
 		// Update the layout
+		let anchorInfo = this.layout.UNSTABLE_getScrollAnchorInfo?.(context.layoutOptions) ?? null;
+
+		// Capture scroll anchor from current (pre-layout) view positions.
+		// On first render _visibleViews is empty so no anchor will be found.
+		let anchor: ScrollAnchor | null = null;
+		if (anchorInfo) {
+			let preLayoutInfos: [Key, LayoutInfo][] = [];
+			for (let [key, view] of this._visibleViews) {
+				let layoutInfo = this.layout.getLayoutInfo(key) ?? view.layoutInfo;
+				if (layoutInfo) {
+					preLayoutInfos.push([key, layoutInfo]);
+				}
+			}
+			anchor = this._scrollAnchor.captureBeforeLayout(anchorInfo, preLayoutInfos, this.visibleRect);
+		}
+
+		let previousContentSize = this.contentSize;
+		let previousVisibleRect = this.visibleRect;
 		this.layout.update(context);
-		(this as Mutable<this>).contentSize = this.layout.getContentSize();
+
+		let rawContentSize = this.layout.getContentSize();
+		(this as Mutable<this>).contentSize = new Size(rawContentSize.width, rawContentSize.height);
+
+		let target = this._scrollAnchor.resolveAfterLayout({
+			anchorInfo,
+			anchor,
+			postLayoutInfos: anchorInfo ? this.getVisibleLayoutInfos() : new Map(),
+			previousVisibleRect,
+			previousContentSize,
+			contentSize: this.contentSize,
+			itemSizeChanged: context.itemSizeChanged ?? false,
+			isScrolling: this._isScrolling,
+			getLayoutInfo: (key: Key) => this.layout.getLayoutInfo(key),
+		});
 
 		// Constrain scroll position.
 		// If the content changed, scroll to the top.
+		if (target) {
+			// Queues a new render cycle. Return early to skip updateSubviews — running it now
+			// would position views against the old visibleRect, causing a flash before the
+			// incoming relayout corrects them.
+			this.delegate.setVisibleRect(target);
+			return;
+		}
 		let visibleRect = this.visibleRect;
 		let contentOffsetX = context.contentChanged ? 0 : visibleRect.x;
 		let contentOffsetY = context.contentChanged ? 0 : visibleRect.y;
@@ -289,6 +331,8 @@ export class Virtualizer<T extends object, V> {
 		let needsLayout = false;
 		let offsetChanged = false;
 		let sizeChanged = false;
+		let widthChanged = false;
+		let heightChanged = false;
 		let itemSizeChanged = false;
 		let layoutOptionsChanged = false;
 		let needsUpdate = false;
@@ -305,6 +349,7 @@ export class Virtualizer<T extends object, V> {
 
 			opts.layout.virtualizer = this;
 			mutableThis.layout = opts.layout;
+			this._scrollAnchor.reset();
 			needsLayout = true;
 		}
 
@@ -335,6 +380,8 @@ export class Virtualizer<T extends object, V> {
 			if (shouldInvalidate) {
 				offsetChanged = !opts.visibleRect.pointEquals(this.visibleRect);
 				sizeChanged = !this.size.equals(opts.size);
+				widthChanged = this.size.width !== opts.size.width;
+				heightChanged = this.size.height !== opts.size.height;
 				needsLayout = true;
 			} else {
 				needsUpdate = true;
@@ -347,6 +394,8 @@ export class Virtualizer<T extends object, V> {
 		if (opts.invalidationContext !== this._invalidationContext) {
 			if (opts.invalidationContext) {
 				sizeChanged ||= opts.invalidationContext.sizeChanged || false;
+				widthChanged ||= opts.invalidationContext.widthChanged || false;
+				heightChanged ||= opts.invalidationContext.heightChanged || false;
 				offsetChanged ||= opts.invalidationContext.offsetChanged || false;
 				itemSizeChanged ||= opts.invalidationContext.itemSizeChanged || false;
 				layoutOptionsChanged ||=
@@ -374,6 +423,8 @@ export class Virtualizer<T extends object, V> {
 			this.relayout({
 				offsetChanged,
 				sizeChanged,
+				widthChanged,
+				heightChanged,
 				itemSizeChanged,
 				layoutOptionsChanged,
 				layoutOptions: this._invalidationContext.layoutOptions,

package/src/stately/virtualizer/types.tsx

@@ -21,6 +21,8 @@ export interface InvalidationContext<O = any> {
 	contentChanged?: boolean;
 	offsetChanged?: boolean;
 	sizeChanged?: boolean;
+	widthChanged?: boolean;
+	heightChanged?: boolean;
 	itemSizeChanged?: boolean;
 	layoutOptionsChanged?: boolean;
 	layoutOptions?: O;

package/src/table/useTableCell.ts

@@ -32,6 +32,18 @@ export interface AriaTableCellProps {
 	 * @deprecated
 	 */
 	onAction?: () => void;
+	/**
+	 * Whether the cell or its first focusable child element should be focused when the cell is
+	 * focused. Defaults to 'child' in arrow keyboard navigation mode and 'cell' in
+	 * tab keyboard navigation mode.
+	 */
+	focusMode?: 'child' | 'cell';
+	/**
+	 * Whether the cell should support arrow key navigation even when the containing table uses
+	 * tab keyboard navigation.Allows users to navigate between rows and cells with arrow keys while
+	 * focus is on an interactive child element within the cell.
+	 */
+	allowsArrowNavigation?: boolean;
 }
 
 export interface TableCellAria {

package/src/table/useTableColumnHeader.ts

@@ -38,6 +38,13 @@ export interface AriaTableColumnHeaderProps<T> {
 	 * virtual scroller.
 	 */
 	isVirtualized?: boolean;
+	focusMode?: 'child' | 'cell';
+	/**
+	 * Whether the column header should support arrow key navigation even when the containing table
+	 * uses tab keyboard navigation. Allows users to navigate between columns with arrow keys while
+	 * focus is on an interactive child element within the cell.
+	 */
+	allowsArrowNavigation?: boolean;
 }
 
 export interface TableColumnHeaderAria {
@@ -77,7 +84,7 @@ export function useTableColumnHeader(...args: any[]): TableColumnHeaderAria {
 	let allowsSorting = node.props.allowsSorting;
 	// if there are no focusable children, the column header will focus the cell
 	let { gridCellProps } = useGridCell(
-		{ ...props, focusMode: 'child' },
+		{ focusMode: 'child', ...props },
 		state,
 		ref,
 		subSlot(slot, 'gridCell'),