@octanejs/aria 0.0.46 → 0.0.47

package/src/datepicker/useDatePickerGroup.tsx

@@ -1,12 +1,13 @@
 /** @jsxImportSource octane */
-// Ported from adobe/react-spectrum@1c84a49a1faf50b571c84e00bcf9c60b22ddd03e (packages/react-aria/src/datepicker/useDatePickerGroup.ts).
+// Ported from adobe/react-spectrum@5ecb3333001313e83898cd07644227897e3bae1f (packages/react-aria/src/datepicker/useDatePickerGroup.ts).
 import { createFocusManager, getFocusableTreeWalker } from '../focus/FocusScope';
 import { DateFieldState } from '../upstream-exports/react-stately/useDateFieldState';
 import { DatePickerState } from '../upstream-exports/react-stately/useDatePickerState';
 import { DateRangePickerState } from '../upstream-exports/react-stately/useDateRangePickerState';
-import { DOMAttributes, FocusableElement, KeyboardEvent, RefObject } from '@react-types/shared';
-import { getEventTarget, nodeContains } from '../utils/shadowdom/DOMFunctions';
+import { DOMAttributes, FocusableElement, RefObject } from '@react-types/shared';
+import { getEventTarget } from '../utils/shadowdom/DOMFunctions';
 import { mergeProps } from '../utils/mergeProps';
+import { useKeyboard } from '../interactions/useKeyboard';
 import { useLocale } from '../i18n/I18nProvider';
 import { useMemo } from '../compat/react';
 import { usePress } from '../interactions/usePress';
@@ -17,59 +18,68 @@ export function useDatePickerGroup(
 	disableArrowNavigation?: boolean,
 ): DOMAttributes<FocusableElement> {
 	let { direction } = useLocale();
+	// oxlint-disable-next-line react/react-compiler
 	let focusManager = useMemo(() => createFocusManager(ref), [ref]);
 
-	// Open the popover on alt + arrow down
-	let onKeyDown = (e: KeyboardEvent) => {
-		if (!nodeContains(e.currentTarget, getEventTarget(e as unknown as Event) as Element)) {
-			return;
-		}
-
-		if (e.altKey && (e.key === 'ArrowDown' || e.key === 'ArrowUp') && 'setOpen' in state) {
-			e.preventDefault();
-			e.stopPropagation();
-			state.setOpen(true);
-		}
-
-		if (disableArrowNavigation) {
-			return;
-		}
-
-		switch (e.key) {
-			case 'ArrowLeft':
-				e.preventDefault();
-				e.stopPropagation();
+	let { keyboardProps } = useKeyboard({
+		shortcuts: {
+			'Alt+ArrowDown': () => {
+				if ('setOpen' in state) {
+					state.setOpen(true);
+					return;
+				}
+				return false;
+			},
+			'Alt+ArrowUp': () => {
+				if ('setOpen' in state) {
+					state.setOpen(true);
+					return;
+				}
+				return false;
+			},
+			ArrowLeft: (e) => {
+				if (disableArrowNavigation) {
+					return false;
+				}
 				if (direction === 'rtl') {
 					if (ref.current) {
-						let target = getEventTarget(e as unknown as Event) as FocusableElement;
+						let target = getEventTarget(e) as FocusableElement;
 						let prev = findNextSegment(ref.current, target.getBoundingClientRect().left, -1);
 
 						if (prev) {
 							prev.focus();
+							return;
 						}
 					}
 				} else {
 					focusManager.focusPrevious();
+					return;
+				}
+				return false;
+			},
+			ArrowRight: (e) => {
+				if (disableArrowNavigation) {
+					return false;
 				}
-				break;
-			case 'ArrowRight':
-				e.preventDefault();
-				e.stopPropagation();
 				if (direction === 'rtl') {
 					if (ref.current) {
-						let target = getEventTarget(e as unknown as Event) as FocusableElement;
+						let target = getEventTarget(e) as FocusableElement;
 						let next = findNextSegment(ref.current, target.getBoundingClientRect().left, 1);
 
 						if (next) {
 							next.focus();
+							return;
 						}
 					}
 				} else {
 					focusManager.focusNext();
+					return;
 				}
-				break;
-		}
-	};
+				return false;
+			},
+		},
+		allowRepeats: true,
+	});
 
 	// Focus the first placeholder segment from the end on mouse down/touch up in the field.
 	let focusLast = () => {
@@ -125,7 +135,8 @@ export function useDatePickerGroup(
 		},
 	});
 
-	return mergeProps(pressProps, { onKeyDown });
+	// oxlint-disable-next-line react/react-compiler
+	return mergeProps(pressProps, keyboardProps);
 }
 
 function findNextSegment(group: Element, fromX: number, direction: number) {

package/src/datepicker/useDateSegment.tsx

@@ -1,5 +1,5 @@
 /** @jsxImportSource octane */
-// Ported from adobe/react-spectrum@1c84a49a1faf50b571c84e00bcf9c60b22ddd03e (packages/react-aria/src/datepicker/useDateSegment.ts).
+// Ported from adobe/react-spectrum@5ecb3333001313e83898cd07644227897e3bae1f (packages/react-aria/src/datepicker/useDateSegment.ts).
 /*
  * Copyright 2020 Adobe. All rights reserved.
  * This file is licensed to you under the Apache License, Version 2.0 (the "License");
@@ -17,7 +17,7 @@ import { DateFieldState, DateSegment } from '../upstream-exports/react-stately/u
 import { getActiveElement, nodeContains } from '../utils/shadowdom/DOMFunctions';
 import { getScrollParent } from '../utils/getScrollParent';
 import { hookData } from './useDateField';
-import { isIOS, isMac } from '../utils/platform';
+import { isIOS } from '../utils/platform';
 import { mergeProps } from '../utils/mergeProps';
 import { NumberParser } from '@internationalized/number';
 import React, { CSSProperties, useMemo, useRef } from '../compat/react';
@@ -28,6 +28,7 @@ import { useDisplayNames } from './useDisplayNames';
 import { useEvent } from '../utils/useEvent';
 import { useFilter } from '../i18n/useFilter';
 import { useId } from '../utils/useId';
+import { useKeyboard } from '../interactions/useKeyboard';
 import { useLabels } from '../utils/useLabels';
 import { useLayoutEffect } from '../utils/useLayoutEffect';
 import { useLocale } from '../i18n/I18nProvider';
@@ -127,28 +128,21 @@ export function useDateSegment(
 		}
 	};
 
-	let onKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
-		// Firefox does not fire selectstart for Ctrl/Cmd + A
-		// https://bugzilla.mozilla.org/show_bug.cgi?id=1742153
-		if (e.key === 'a' && (isMac() ? e.metaKey : e.ctrlKey)) {
-			e.preventDefault();
-		}
-
-		if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) {
-			return;
-		}
-
-		switch (e.key) {
-			case 'Backspace':
-			case 'Delete': {
-				// Safari on iOS does not fire beforeinput for the backspace key because the cursor is at the start.
-				e.preventDefault();
-				e.stopPropagation();
+	let { keyboardProps } = useKeyboard({
+		shortcuts: {
+			Backspace: () => {
 				backspace();
-				break;
-			}
-		}
-	};
+			},
+			Delete: () => {
+				backspace();
+			},
+			'Mod+a': () => {
+				// Firefox does not fire selectstart for Ctrl/Cmd + A
+				// https://bugzilla.mozilla.org/show_bug.cgi?id=1742153
+			},
+		},
+		allowRepeats: true,
+	});
 
 	// Safari dayPeriod option doesn't work...
 	let { startsWith } = useFilter({ sensitivity: 'base' });
@@ -273,7 +267,13 @@ export function useDateSegment(
 		// Otherwise, when tapping on a segment in Android Chrome and then entering text,
 		// composition events will be fired that break the DOM structure and crash the page.
 		let selection = window.getSelection();
-		if (selection?.anchorNode && nodeContains(ref.current, selection?.anchorNode)) {
+		// Only collapse while focused, otherwise a stale anchor left in the segment (e.g. on Firefox)
+		// steals focus back into it on selectionchange. See #10259.
+		if (
+			selection?.anchorNode &&
+			nodeContains(ref.current, selection?.anchorNode) &&
+			getActiveElement() === ref.current
+		) {
 			selection.collapse(ref.current);
 		}
 	});
@@ -393,32 +393,33 @@ export function useDateSegment(
 	}
 
 	return {
+		// oxlint-disable-next-line react/react-compiler
 		segmentProps: mergeProps(spinButtonProps, labelProps, {
 			id,
 			...touchPropOverrides,
+			...keyboardProps,
 			'aria-invalid': state.isInvalid ? 'true' : undefined,
 			'aria-describedby': ariaDescribedBy,
 			'aria-readonly': state.isReadOnly || !segment.isEditable ? 'true' : undefined,
 			'data-placeholder': segment.isPlaceholder || undefined,
 			contentEditable: isEditable,
 			suppressContentEditableWarning: isEditable,
-			spellCheck: isEditable ? 'false' : undefined,
+			spellCheck: isEditable ? ('false' as const) : undefined,
 			autoCorrect: isEditable ? 'off' : undefined,
-			// Octane uses the modern DOM property name regardless of its package version.
+			// Capitalization was changed in React 17...
 			enterKeyHint: isEditable ? 'next' : undefined,
 			inputMode:
 				state.isDisabled || segment.type === 'dayPeriod' || segment.type === 'era' || !isEditable
 					? undefined
-					: 'numeric',
+					: ('numeric' as const),
 			tabIndex: state.isDisabled ? undefined : 0,
-			onKeyDown,
 			onFocus,
 			style: segmentStyle,
 			// Prevent pointer events from reaching useDatePickerGroup, and allow native browser behavior to focus the segment.
-			onPointerDown(e: React.PointerEvent<HTMLDivElement>) {
+			onPointerDown(e: PointerEvent) {
 				e.stopPropagation();
 			},
-			onMouseDown(e: React.MouseEvent<HTMLDivElement>) {
+			onMouseDown(e: MouseEvent) {
 				e.stopPropagation();
 			},
 		}),

package/src/dialog/useDialog.ts

@@ -34,6 +34,7 @@ export interface DialogAria {
 
 	/** Props for the dialog title element. */
 	titleProps: DOMAttributes;
+	contentProps: DOMAttributes;
 }
 
 /**
@@ -60,6 +61,9 @@ export function useDialog(...args: any[]): DialogAria {
 	let titleId: string | undefined = useSlotId(undefined, subSlot(slot, 'title'));
 	titleId = props['aria-label'] ? undefined : titleId;
 
+	let contentId: string | undefined = useSlotId();
+	contentId = role === 'alertdialog' && !props['aria-describedby'] ? contentId : undefined;
+
 	let isRefocusing = useRef(false, subSlot(slot, 'refocusing'));
 
 	// Focus the dialog itself on mount, unless a child element is already focused.
@@ -125,12 +129,14 @@ export function useDialog(...args: any[]): DialogAria {
 	// See https://bugs.webkit.org/show_bug.cgi?id=211934.
 	// useModal sets aria-hidden on all elements outside the dialog, so the dialog will behave as a modal
 	// even without aria-modal on the dialog itself.
+	let ariaDescribedby = props['aria-describedby'] ?? contentId;
 	return {
 		dialogProps: {
 			...filterDOMProps(props, { labelable: true }),
 			role,
 			tabIndex: -1,
-			'aria-labelledby': props['aria-labelledby'] || titleId,
+			'aria-labelledby': props['aria-labelledby'] ?? titleId,
+			'aria-describedby': ariaDescribedby,
 			// Prevent blur events from reaching useOverlay, which may cause
 			// popovers to close. Since focus is contained within the dialog,
 			// we don't want this to occur due to the above useEffect.
@@ -140,6 +146,7 @@ export function useDialog(...args: any[]): DialogAria {
 				}
 			},
 		},
+		contentProps: { id: contentId },
 		titleProps: {
 			id: titleId,
 		},

package/src/dnd/DragManager.tsx

@@ -532,8 +532,12 @@ class DragSession {
 
 		let minDistance = Infinity;
 		let nearest = -1;
+		let ancestor = -1;
 		for (let i = 0; i < this.validDropTargets.length; i++) {
 			let dropTarget = this.validDropTargets[i];
+			if (ancestor < 0 && nodeContains(dropTarget.element, this.dragTarget.element)) {
+				ancestor = i;
+			}
 			let rect = dropTarget.element.getBoundingClientRect();
 			let dx = rect.left - dragTargetRect.left;
 			let dy = rect.top - dragTargetRect.top;
@@ -544,7 +548,7 @@ class DragSession {
 			}
 		}
 
-		return nearest;
+		return ancestor >= 0 ? ancestor : nearest;
 	}
 
 	setCurrentDropTarget(dropTarget: DropTarget | null, item?: DroppableItem): void {

package/src/dnd/useDrag.tsx

@@ -1,4 +1,5 @@
 /** @jsxImportSource octane */
+import { isIOS, isWebKit } from '../utils/platform';
 // Ported from adobe/react-spectrum@1c84a49a1faf50b571c84e00bcf9c60b22ddd03e (packages/react-aria/src/dnd/useDrag.ts).
 /*
  * Copyright 2020 Adobe. All rights reserved.
@@ -368,7 +369,7 @@ export function useDrag(options: DragOptions): DragResult {
 				modalityOnPointerDown.current = isVirtualPointerEvent(e) ? 'virtual' : e.pointerType;
 
 				// Try to detect virtual drag passthrough gestures.
-				if (e.width < 1 && e.height < 1) {
+				if (e.width < 1 && e.height < 1 && isIOS() && isWebKit()) {
 					// iOS VoiceOver.
 					modalityOnPointerDown.current = 'virtual';
 				} else {

package/src/focus/FocusScope.ts

@@ -462,7 +462,7 @@ function useFocusContainment(
 					// If a focus event occurs outside the active scope (e.g. user tabs from browser location bar),
 					// restore focus to the previously focused node or the first tabbable element in the active scope.
 					if (focusedNode.current) {
-						focusedNode.current.focus();
+						focusElement(focusedNode.current);
 					} else if (activeScope && activeScope.current) {
 						focusFirstInScope(activeScope.current);
 					}
@@ -496,7 +496,7 @@ function useFocusContainment(
 						let target = getEventTarget(e) as FocusableElement;
 						if (target && target.isConnected) {
 							focusedNode.current = target;
-							focusedNode.current?.focus();
+							focusElement(focusedNode.current);
 						} else if (activeScope.current) {
 							focusFirstInScope(activeScope.current);
 						}

package/src/grid/useGrid.ts

@@ -85,6 +85,7 @@ export interface GridProps extends DOMProps, AriaLabelingProps {
 	escapeKeyBehavior?: 'clearSelection' | 'none';
 	/** Whether selection should occur on press up instead of press down. */
 	shouldSelectOnPressUp?: boolean;
+	keyboardNavigationBehavior?: 'arrow' | 'tab';
 }
 
 export interface GridAria {
@@ -130,6 +131,7 @@ export function useGrid(...args: any[]): GridAria {
 		onRowAction,
 		onCellAction,
 		escapeKeyBehavior = 'clearSelection',
+		keyboardNavigationBehavior = 'arrow',
 		shouldSelectOnPressUp,
 	} = props;
 	let { selectionManager: manager } = state;
@@ -185,6 +187,7 @@ export function useGrid(...args: any[]): GridAria {
 	gridMap.set(state, {
 		keyboardDelegate: delegate,
 		actions: { onRowAction, onCellAction },
+		keyboardNavigationBehavior,
 		shouldSelectOnPressUp,
 	});
 

package/src/grid/{useGridCell.ts → useGridCell.tsx}

@@ -1,14 +1,19 @@
-// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/grid/useGridCell.ts).
-// octane adaptations:
-// - Handlers receive NATIVE events (there is no synthetic layer): keydown handlers take
-//   the native KeyboardEvent, and the ArrowUp/ArrowDown/edge re-dispatch builds
-//   `new KeyboardEvent(e.type, e)` — upstream's `e.nativeEvent` IS the event here.
-//   `onKeyDownCapture` maps to the capture phase natively in octane, matching
-//   upstream's React capture prop.
-// - `GridState`/`IGridCollection`/`GridNode` come from the ported stately grid hooks;
-//   `DOMAttributes` is a local structural prop-bag alias.
-// - Public-hook slot threading (splitSlot/subSlot).
-import type { FocusableElement, Key, RefObject } from '@react-types/shared';
+/** @jsxImportSource octane */
+type DOMAttributes = Record<string, any>;
+// Ported from adobe/react-spectrum@5ecb3333001313e83898cd07644227897e3bae1f (packages/react-aria/src/grid/useGridCell.ts).
+/*
+ * Copyright 2020 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 { FocusableElement, Key, RefObject } from '@react-types/shared';
 import { focusSafely } from '../interactions/focusSafely';
 import {
 	getActiveElement,
@@ -17,23 +22,21 @@ import {
 	nodeContains,
 } from '../utils/shadowdom/DOMFunctions';
 import { getFocusableTreeWalker } from '../focus/FocusScope';
+import { getOwnerDocument } from '../utils/domHelpers';
 import { getScrollParent } from '../utils/getScrollParent';
-import type { IGridCollection as GridCollection, GridNode } from '../stately/grid/GridCollection';
+import {
+	IGridCollection as GridCollection,
+	GridNode,
+} from '../upstream-exports/react-stately/private/grid/GridCollection';
 import { gridMap } from './utils';
-import type { GridState } from '../stately/grid/useGridState';
+import { GridState } from '../upstream-exports/react-stately/private/grid/useGridState';
 import { isFocusVisible } from '../interactions/useFocusVisible';
 import { mergeProps } from '../utils/mergeProps';
-import { useRef } from 'octane';
+import { KeyboardEvent as ReactKeyboardEvent, useRef } from '../compat/react';
 import { scrollIntoViewport } from '../utils/scrollIntoView';
 import { useLocale } from '../i18n/I18nProvider';
 import { useSelectableItem } from '../selection/useSelectableItem';
 
-import { S, splitSlot, subSlot } from '../internal';
-
-// octane adaptation: minimal structural DOMAttributes (upstream's drags React's synthetic
-// handler types along).
-type DOMAttributes = Record<string, any>;
-
 export interface GridCellProps {
 	/**
 	 * An object representing the grid cell. Contains all the relevant information that makes up the
@@ -44,9 +47,16 @@ export interface GridCellProps {
 	isVirtualized?: boolean;
 	/**
 	 * Whether the cell or its first focusable child element should be focused when the grid cell is
-	 * focused.
+	 * 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 collection 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;
 	/** Whether selection should occur on press up instead of press down. */
 	shouldSelectOnPressUp?: boolean;
 	/** Indicates how many columns the data cell spans. */
@@ -77,32 +87,28 @@ export function useGridCell<T, C extends GridCollection<T>>(
 	props: GridCellProps,
 	state: GridState<T, C>,
 	ref: RefObject<FocusableElement | null>,
-): GridCellAria;
-// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
-export function useGridCell<T, C extends GridCollection<T>>(
-	props: GridCellProps,
-	state: GridState<T, C>,
-	ref: RefObject<FocusableElement | null>,
-	slot: symbol | undefined,
-): GridCellAria;
-export function useGridCell(...args: any[]): GridCellAria {
-	const [user, slotArg] = splitSlot(args);
-	const slot = slotArg ?? S('useGridCell');
-	const props = user[0] as GridCellProps;
-	const state = user[1] as GridState<any, GridCollection<any>>;
-	const ref = user[2] as RefObject<FocusableElement | null>;
-
-	let { node, isVirtualized, focusMode = 'child', shouldSelectOnPressUp, onAction } = props;
+	_slot?: symbol,
+): GridCellAria {
+	let {
+		node,
+		isVirtualized,
+		focusMode: focusModeProp,
+		allowsArrowNavigation,
+		shouldSelectOnPressUp,
+		onAction,
+	} = props;
 
-	let { direction } = useLocale(subSlot(slot, 'locale'));
+	let { direction } = useLocale();
 	let {
 		keyboardDelegate,
 		actions: { onCellAction },
+		keyboardNavigationBehavior,
 	} = gridMap.get(state)!;
+	let focusMode = focusModeProp ?? (keyboardNavigationBehavior === 'tab' ? 'cell' : 'child');
 
 	// We need to track the key of the item at the time it was last focused so that we force
 	// focus to go to the item when the DOM node is reused for a different item in a virtualizer.
-	let keyWhenFocused = useRef<Key | null>(null, subSlot(slot, 'keyWhenFocused'));
+	let keyWhenFocused = useRef<Key | null>(null);
 
 	// Handles focusing the cell. If there is a focusable child,
 	// it is focused, otherwise the cell itself is focused.
@@ -111,7 +117,10 @@ export function useGridCell(...args: any[]): GridCellAria {
 			let treeWalker = getFocusableTreeWalker(ref.current);
 			if (focusMode === 'child') {
 				// If focus is already on a focusable child within the cell, early return so we don't shift focus
-				if (isFocusWithin(ref.current) && ref.current !== getActiveElement()) {
+				if (
+					isFocusWithin(ref.current) &&
+					ref.current !== getActiveElement(getOwnerDocument(ref.current))
+				) {
 					return;
 				}
 
@@ -134,24 +143,21 @@ export function useGridCell(...args: any[]): GridCellAria {
 		}
 	};
 
-	let { itemProps, isPressed } = useSelectableItem(
-		{
-			selectionManager: state.selectionManager,
-			key: node.key,
-			ref,
-			isVirtualized,
-			focus,
-			shouldSelectOnPressUp,
-			onAction: onCellAction ? () => onCellAction(node.key) : onAction,
-			isDisabled: state.collection.size === 0,
-		},
-		subSlot(slot, 'selectableItem'),
-	);
+	let { itemProps, isPressed } = useSelectableItem({
+		selectionManager: state.selectionManager,
+		key: node.key,
+		ref,
+		isVirtualized,
+		focus,
+		shouldSelectOnPressUp,
+		onAction: onCellAction ? () => onCellAction(node.key) : onAction,
+		isDisabled: state.collection.size === 0,
+	});
 
-	let onKeyDownCapture = (e: KeyboardEvent) => {
-		let activeElement = getActiveElement();
+	let onKeyDownCapture = (e: ReactKeyboardEvent) => {
+		let activeElement = getActiveElement(getOwnerDocument(ref.current));
 		if (
-			!nodeContains(e.currentTarget as Element, getEventTarget(e) as Element) ||
+			!nodeContains(e.currentTarget as Node, getEventTarget(e) as Element) ||
 			state.isKeyboardNavigationDisabled ||
 			!ref.current ||
 			!activeElement
@@ -191,7 +197,6 @@ export function useGridCell(...args: any[]): GridCellAria {
 						// We prevent the capturing event from reaching children of the cell, e.g. pickers.
 						// We want arrow keys to navigate to the next cell instead. We need to re-dispatch
 						// the event from a higher parent so it still bubbles and gets handled by useSelectableCollection.
-						// octane adaptation: the native event IS `e.nativeEvent`.
 						ref.current.parentElement?.dispatchEvent(new KeyboardEvent(e.type, e));
 						break;
 					}
@@ -232,7 +237,6 @@ export function useGridCell(...args: any[]): GridCellAria {
 						// We prevent the capturing event from reaching children of the cell, e.g. pickers.
 						// We want arrow keys to navigate to the next cell instead. We need to re-dispatch
 						// the event from a higher parent so it still bubbles and gets handled by useSelectableCollection.
-						// octane adaptation: the native event IS `e.nativeEvent`.
 						ref.current.parentElement?.dispatchEvent(new KeyboardEvent(e.type, e));
 						break;
 					}
@@ -260,13 +264,47 @@ export function useGridCell(...args: any[]): GridCellAria {
 				if (!e.altKey && nodeContains(ref.current, getEventTarget(e) as Element)) {
 					e.stopPropagation();
 					e.preventDefault();
-					// octane adaptation: the native event IS `e.nativeEvent`.
 					ref.current.parentElement?.dispatchEvent(new KeyboardEvent(e.type, e));
 				}
 				break;
 		}
 	};
 
+	let onKeyDown = (e: ReactKeyboardEvent) => {
+		let activeElement = getActiveElement(getOwnerDocument(ref.current));
+		if (
+			!nodeContains(e.currentTarget as Node, getEventTarget(e) as Element) ||
+			state.isKeyboardNavigationDisabled ||
+			!ref.current ||
+			!activeElement
+		) {
+			return;
+		}
+
+		if (keyboardNavigationBehavior === 'tab') {
+			if (getEventTarget(e) !== ref.current && e.key !== 'Tab') {
+				e.stopPropagation();
+				return;
+			}
+		}
+
+		switch (e.key) {
+			case 'Tab': {
+				if (keyboardNavigationBehavior === 'tab') {
+					// If there is another focusable element within this item, stop propagation so the tab key
+					// is handled by the browser and not by useSelectableCollection (which would take us out of the list).
+					let walker = getFocusableTreeWalker(ref.current, { tabbable: true });
+					walker.currentNode = activeElement;
+					let next = e.shiftKey ? walker.previousNode() : walker.nextNode();
+
+					if (next) {
+						e.stopPropagation();
+					}
+				}
+			}
+		}
+	};
+
 	// Grid cells can have focusable elements inside them. In this case, focus should
 	// be marshalled to that element rather than focusing the cell itself.
 	let onFocus = (e: FocusEvent) => {
@@ -284,22 +322,41 @@ export function useGridCell(...args: any[]): GridCellAria {
 			return;
 		}
 
-		// If the cell itself is focused, wait a frame so that focus finishes propagatating
+		// if focus goes back to cell from child, make sure we don't refocus the cell if we are in focusMode=child
+		// since that would be a focus trap
+		if (
+			focusMode === 'child' &&
+			e.relatedTarget &&
+			nodeContains(ref.current, e.relatedTarget as Element)
+		) {
+			return;
+		}
+
+		// If the cell itself is focused, wait a frame so that focus finishes propagating
 		// up to the tree, and move focus to a focusable child if possible.
 		requestAnimationFrame(() => {
-			if (focusMode === 'child' && getActiveElement() === ref.current) {
+			if (
+				focusMode === 'child' &&
+				getActiveElement(getOwnerDocument(ref.current)) === ref.current
+			) {
 				focus();
 			}
 		});
 	};
 
+	// oxlint-disable-next-line react/react-compiler
 	let gridCellProps: DOMAttributes = mergeProps(itemProps, {
 		role: 'gridcell',
-		onKeyDownCapture,
+		onKeyDownCapture:
+			keyboardNavigationBehavior !== 'tab' || allowsArrowNavigation ? onKeyDownCapture : undefined,
+		onKeyDown: keyboardNavigationBehavior === 'tab' ? onKeyDown : undefined,
 		'aria-colspan': node.colSpan,
 		'aria-colindex': node.colIndex != null ? node.colIndex + 1 : undefined, // aria-colindex is 1-based
 		colSpan: isVirtualized ? undefined : node.colSpan,
 		onFocus,
+		// make sure shift tabbing from a child of a cell doesnt move focus back to cell if focusMode="child" and in tab nav
+		// consistent with arrow nav and focusMode="child" since you can't go back to the cell there either
+		...(focusMode === 'child' && keyboardNavigationBehavior === 'tab' ? { tabIndex: -1 } : {}),
 	});
 
 	if (isVirtualized) {
@@ -315,8 +372,8 @@ export function useGridCell(...args: any[]): GridCellAria {
 		gridCellProps.tabIndex != null &&
 		gridCellProps.onPointerDown == null
 	) {
-		gridCellProps.onPointerDown = (e: PointerEvent) => {
-			let el = e.currentTarget as Element;
+		gridCellProps.onPointerDown = (e: import('octane').PointerEvent<HTMLElement>) => {
+			let el = e.currentTarget;
 			let tabindex = el.getAttribute('tabindex');
 			el.removeAttribute('tabindex');
 			requestAnimationFrame(() => {