@octanejs/aria 0.0.1 → 0.0.3

package/src/tooltip/useTooltip.ts

@@ -0,0 +1,64 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/tooltip/useTooltip.ts).
+// octane adaptations:
+// - `DOMAttributes` is a local structural prop-bag alias (upstream's is typed over React's
+//   synthetic handlers).
+// - The `TooltipTriggerState` type is imported from the ported stately hook, not a bare
+//   `react-stately/...` specifier.
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention.
+import type { AriaLabelingProps, DOMProps } from '@react-types/shared';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { mergeProps } from '../utils/mergeProps';
+import type { TooltipTriggerState } from '../stately/tooltip/useTooltipTriggerState';
+import { useHover } from '../interactions/useHover';
+
+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 TooltipProps {
+	isOpen?: boolean;
+}
+
+export interface AriaTooltipProps extends TooltipProps, DOMProps, AriaLabelingProps {}
+
+export interface TooltipAria {
+	/**
+	 * Props for the tooltip element.
+	 */
+	tooltipProps: DOMAttributes;
+}
+
+/**
+ * Provides the accessibility implementation for a Tooltip component.
+ */
+export function useTooltip(props: AriaTooltipProps, state?: TooltipTriggerState): TooltipAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTooltip(
+	props: AriaTooltipProps,
+	state: TooltipTriggerState | undefined,
+	slot: symbol | undefined,
+): TooltipAria;
+export function useTooltip(...args: any[]): TooltipAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTooltip');
+	const props = user[0] as AriaTooltipProps;
+	const state = user[1] as TooltipTriggerState | undefined;
+
+	let domProps = filterDOMProps(props, { labelable: true });
+
+	let { hoverProps } = useHover(
+		{
+			onHoverStart: () => state?.open(true),
+			onHoverEnd: () => state?.close(),
+		},
+		subSlot(slot, 'hover'),
+	);
+
+	return {
+		tooltipProps: mergeProps(domProps, hoverProps, {
+			role: 'tooltip',
+		}),
+	};
+}

package/src/tooltip/useTooltipTrigger.ts

@@ -0,0 +1,187 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/tooltip/useTooltipTrigger.ts).
+// octane adaptations:
+// - `DOMAttributes` is a local structural prop-bag alias (upstream's is typed over React's
+//   synthetic handlers); the global keydown listener receives a native KeyboardEvent.
+// - `TooltipTriggerProps`/`TooltipTriggerState` are imported from the ported stately hook,
+//   not a bare `react-stately/...` specifier.
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention; the explicit
+//   useEffect dep array is kept verbatim with a trailing subSlot.
+import type { FocusableElement, RefObject } from '@react-types/shared';
+import { getInteractionModality, isFocusVisible } from '../interactions/useFocusVisible';
+import { mergeProps } from '../utils/mergeProps';
+import type {
+	TooltipTriggerProps,
+	TooltipTriggerState,
+} from '../stately/tooltip/useTooltipTriggerState';
+import { useEffect, useRef } from 'octane';
+import { useFocusable } from '../interactions/useFocusable';
+import { useHover } from '../interactions/useHover';
+import { useId } from '../utils/useId';
+
+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 TooltipTriggerAria {
+	/**
+	 * Props for the trigger element.
+	 */
+	triggerProps: DOMAttributes;
+
+	/**
+	 * Props for the overlay container element.
+	 */
+	tooltipProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a tooltip trigger, e.g. a button
+ * that shows a description when focused or hovered.
+ */
+export function useTooltipTrigger(
+	props: TooltipTriggerProps,
+	state: TooltipTriggerState,
+	ref: RefObject<FocusableElement | null>,
+): TooltipTriggerAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTooltipTrigger(
+	props: TooltipTriggerProps,
+	state: TooltipTriggerState,
+	ref: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): TooltipTriggerAria;
+export function useTooltipTrigger(...args: any[]): TooltipTriggerAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTooltipTrigger');
+	const props = user[0] as TooltipTriggerProps;
+	const state = user[1] as TooltipTriggerState;
+	const ref = user[2] as RefObject<FocusableElement | null>;
+
+	let { isDisabled, trigger, shouldCloseOnPress = true } = props;
+
+	let tooltipId = useId(subSlot(slot, 'id'));
+
+	let isHovered = useRef(false, subSlot(slot, 'isHovered'));
+	let isFocused = useRef(false, subSlot(slot, 'isFocused'));
+
+	let handleShow = () => {
+		if (isHovered.current || isFocused.current) {
+			state.open(isFocused.current);
+		}
+	};
+
+	let handleHide = (immediate?: boolean) => {
+		if (!isHovered.current && !isFocused.current) {
+			state.close(immediate);
+		}
+	};
+
+	useEffect(
+		() => {
+			let onKeyDown = (e: KeyboardEvent) => {
+				if (ref && ref.current) {
+					// Escape after clicking something can give it keyboard focus
+					// dismiss tooltip on esc key press
+					if (e.key === 'Escape') {
+						e.stopPropagation();
+						state.close(true);
+					}
+				}
+			};
+			if (state.isOpen) {
+				document.addEventListener('keydown', onKeyDown, true);
+				return () => {
+					document.removeEventListener('keydown', onKeyDown, true);
+				};
+			}
+		},
+		[ref, state],
+		subSlot(slot, 'keydown'),
+	);
+
+	let onHoverStart = () => {
+		if (trigger === 'focus') {
+			return;
+		}
+		// In chrome, if you hover a trigger, then another element obscures it, due to keyboard
+		// interactions for example, hover will end. When hover is restored after that element disappears,
+		// focus moves on for example, then the tooltip will reopen. We check the modality to know if the hover
+		// is the result of moving the mouse.
+		if (getInteractionModality() === 'pointer') {
+			isHovered.current = true;
+		} else {
+			isHovered.current = false;
+		}
+		handleShow();
+	};
+
+	let onHoverEnd = () => {
+		if (trigger === 'focus') {
+			return;
+		}
+		// no matter how the trigger is left, we should close the tooltip
+		isFocused.current = false;
+		isHovered.current = false;
+		handleHide();
+	};
+
+	let onPressStart = () => {
+		// if shouldCloseOnPress is false, we should not close the tooltip
+		if (!shouldCloseOnPress) {
+			return;
+		}
+		// no matter how the trigger is pressed, we should close the tooltip
+		isFocused.current = false;
+		isHovered.current = false;
+		handleHide(true);
+	};
+
+	let onFocus = () => {
+		let isVisible = isFocusVisible();
+		if (isVisible) {
+			isFocused.current = true;
+			handleShow();
+		}
+	};
+
+	let onBlur = () => {
+		isFocused.current = false;
+		isHovered.current = false;
+		handleHide(true);
+	};
+
+	let { hoverProps } = useHover(
+		{
+			isDisabled,
+			onHoverStart,
+			onHoverEnd,
+		},
+		subSlot(slot, 'hover'),
+	);
+
+	let { focusableProps } = useFocusable(
+		{
+			isDisabled,
+			onFocus,
+			onBlur,
+		},
+		ref,
+		subSlot(slot, 'focusable'),
+	);
+
+	return {
+		triggerProps: {
+			'aria-describedby': state.isOpen ? tooltipId : undefined,
+			...mergeProps(focusableProps, hoverProps, {
+				onPointerDown: onPressStart,
+				onKeyDown: onPressStart,
+			}),
+			tabIndex: undefined,
+		},
+		tooltipProps: {
+			id: tooltipId,
+		},
+	};
+}

package/src/utils/filterDOMProps.ts

@@ -0,0 +1,121 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/filterDOMProps.ts).
+// Plain function (no hooks, no slot threading). The prop-name tables port verbatim: the
+// `on*` names in `globalEvents` are octane's NATIVE delegated event props, which use the
+// same casing as upstream's React names for these events.
+import type { AriaLabelingProps, DOMProps, LinkDOMProps } from '@react-types/shared';
+
+// octane adaptation: upstream's `GlobalDOMAttributes` from '@react-types/shared' is typed
+// over React synthetic-event handlers; octane props carry native handlers, so it becomes a
+// structural bag.
+type GlobalDOMAttributes = Record<string, any>;
+
+const DOMPropNames = new Set(['id']);
+
+const labelablePropNames = new Set([
+	'aria-label',
+	'aria-labelledby',
+	'aria-describedby',
+	'aria-details',
+]);
+
+// See LinkDOMProps in dom.d.ts.
+const linkPropNames = new Set([
+	'href',
+	'hrefLang',
+	'target',
+	'rel',
+	'download',
+	'ping',
+	'referrerPolicy',
+]);
+
+const globalAttrs = new Set(['dir', 'lang', 'hidden', 'inert', 'translate']);
+
+const globalEvents = new Set([
+	'onClick',
+	'onAuxClick',
+	'onContextMenu',
+	'onDoubleClick',
+	'onMouseDown',
+	'onMouseEnter',
+	'onMouseLeave',
+	'onMouseMove',
+	'onMouseOut',
+	'onMouseOver',
+	'onMouseUp',
+	'onTouchCancel',
+	'onTouchEnd',
+	'onTouchMove',
+	'onTouchStart',
+	'onPointerDown',
+	'onPointerMove',
+	'onPointerUp',
+	'onPointerCancel',
+	'onPointerEnter',
+	'onPointerLeave',
+	'onPointerOver',
+	'onPointerOut',
+	'onGotPointerCapture',
+	'onLostPointerCapture',
+	'onScroll',
+	'onWheel',
+	'onAnimationStart',
+	'onAnimationEnd',
+	'onAnimationIteration',
+	'onTransitionCancel',
+	'onTransitionEnd',
+	'onTransitionRun',
+	'onTransitionStart',
+]);
+
+interface Options {
+	/**
+	 * If labelling associated aria properties should be included in the filter.
+	 */
+	labelable?: boolean;
+	/** Whether the element is a link and should include DOM props for <a> elements. */
+	isLink?: boolean;
+	/** Whether to include global DOM attributes. */
+	global?: boolean;
+	/** Whether to include DOM events. */
+	events?: boolean;
+	/**
+	 * A Set of other property names that should be included in the filter.
+	 */
+	propNames?: Set<string>;
+}
+
+const propRe = /^(data-.*)$/;
+
+/**
+ * Filters out all props that aren't valid DOM props or defined via override prop obj.
+ *
+ * @param props - The component props to be filtered.
+ * @param opts - Props to override.
+ */
+export function filterDOMProps(
+	props: DOMProps & AriaLabelingProps & LinkDOMProps & GlobalDOMAttributes,
+	opts: Options = {},
+): DOMProps & AriaLabelingProps & GlobalDOMAttributes {
+	let { labelable, isLink, global, events = global, propNames } = opts;
+	let filteredProps: Record<string, any> = {};
+
+	for (const prop in props) {
+		if (
+			Object.prototype.hasOwnProperty.call(props, prop) &&
+			(DOMPropNames.has(prop) ||
+				(labelable && labelablePropNames.has(prop)) ||
+				(isLink && linkPropNames.has(prop)) ||
+				(global && globalAttrs.has(prop)) ||
+				(events &&
+					(globalEvents.has(prop) ||
+						(prop.endsWith('Capture') && globalEvents.has(prop.slice(0, -7))))) ||
+				propNames?.has(prop) ||
+				propRe.test(prop))
+		) {
+			filteredProps[prop] = (props as Record<string, any>)[prop];
+		}
+	}
+
+	return filteredProps;
+}

package/src/utils/getScrollParent.ts

@@ -0,0 +1,16 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/getScrollParent.ts).
+// octane adaptations: none (pure DOM walk); ports verbatim.
+import { isScrollable } from './isScrollable';
+
+export function getScrollParent(node: Element, checkForOverflow?: boolean): Element {
+	let scrollableNode: Element | null = node;
+	if (isScrollable(scrollableNode, checkForOverflow)) {
+		scrollableNode = scrollableNode.parentElement;
+	}
+
+	while (scrollableNode && !isScrollable(scrollableNode, checkForOverflow)) {
+		scrollableNode = scrollableNode.parentElement;
+	}
+
+	return scrollableNode || document.scrollingElement || document.documentElement;
+}

package/src/utils/getScrollParents.ts

@@ -0,0 +1,20 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/getScrollParents.ts).
+// Verbatim (no React surface).
+import { isScrollable } from './isScrollable';
+
+export function getScrollParents(node: Element, checkForOverflow?: boolean): Element[] {
+	let parentElements: Element[] = [];
+	let root = document.scrollingElement || document.documentElement;
+
+	while (node) {
+		if (isScrollable(node, checkForOverflow)) {
+			parentElements.push(node);
+		}
+		if (node === root) {
+			break;
+		}
+		node = node.parentElement as Element;
+	}
+
+	return parentElements;
+}

package/src/utils/keyboard.ts

@@ -0,0 +1,38 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/keyboard.tsx).
+// Verbatim (no React surface); the upstream file carries a .tsx extension but contains no JSX.
+import { isMac } from './platform';
+
+interface Event {
+	altKey: boolean;
+	ctrlKey: boolean;
+	metaKey: boolean;
+}
+
+export function isCtrlKeyPressed(e: Event): boolean {
+	if (isMac()) {
+		return e.metaKey;
+	}
+
+	return e.ctrlKey;
+}
+
+// HTML input types that do not cause the software keyboard to appear.
+const nonTextInputTypes = new Set([
+	'checkbox',
+	'radio',
+	'range',
+	'color',
+	'file',
+	'image',
+	'button',
+	'submit',
+	'reset',
+]);
+
+export function willOpenKeyboard(target: Element): boolean {
+	return (
+		(target instanceof HTMLInputElement && !nonTextInputTypes.has(target.type)) ||
+		target instanceof HTMLTextAreaElement ||
+		(target instanceof HTMLElement && target.isContentEditable)
+	);
+}

package/src/utils/scrollIntoView.ts

@@ -0,0 +1,178 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/scrollIntoView.ts).
+// Verbatim (no React surface), including the NODE_ENV === 'test' direct-assignment branch
+// (jsdom has no scrollTo implementation).
+import { getScrollParents } from './getScrollParents';
+import { isIOS } from './platform';
+
+interface ScrollIntoViewOpts {
+	/** The position to align items along the block axis in. */
+	block?: ScrollLogicalPosition;
+	/** The position to align items along the inline axis in. */
+	inline?: ScrollLogicalPosition;
+}
+
+interface ScrollIntoViewportOpts {
+	/** The optional containing element of the target to be centered in the viewport. */
+	containingElement?: Element | null;
+}
+
+/**
+ * Scrolls `scrollView` so that `element` is visible.
+ * Similar to `element.scrollIntoView({block: 'nearest'})` (not supported in Edge),
+ * but doesn't affect parents above `scrollView`.
+ */
+export function scrollIntoView(
+	scrollView: HTMLElement,
+	element: HTMLElement,
+	opts: ScrollIntoViewOpts = {},
+): void {
+	let { block = 'nearest', inline = 'nearest' } = opts;
+
+	if (scrollView === element) {
+		return;
+	}
+
+	let y = scrollView.scrollTop;
+	let x = scrollView.scrollLeft;
+
+	let target = element.getBoundingClientRect();
+	let view = scrollView.getBoundingClientRect();
+	let itemStyle = window.getComputedStyle(element);
+	let viewStyle = window.getComputedStyle(scrollView);
+	let root = document.scrollingElement || document.documentElement;
+	let isRoot = scrollView === root;
+
+	let viewTop = scrollView === root ? 0 : view.top;
+	let viewBottom = scrollView === root ? scrollView.clientHeight : view.bottom;
+	let viewLeft = scrollView === root ? 0 : view.left;
+	let viewRight = scrollView === root ? scrollView.clientWidth : view.right;
+
+	let scrollMarginTop = parseFloat(itemStyle.scrollMarginTop) || 0;
+	let scrollMarginBottom = parseFloat(itemStyle.scrollMarginBottom) || 0;
+	let scrollMarginLeft = parseFloat(itemStyle.scrollMarginLeft) || 0;
+	let scrollMarginRight = parseFloat(itemStyle.scrollMarginRight) || 0;
+
+	let scrollPaddingTop = parseFloat(viewStyle.scrollPaddingTop) || 0;
+	let scrollPaddingBottom = parseFloat(viewStyle.scrollPaddingBottom) || 0;
+	let scrollPaddingLeft = parseFloat(viewStyle.scrollPaddingLeft) || 0;
+	let scrollPaddingRight = parseFloat(viewStyle.scrollPaddingRight) || 0;
+
+	let borderTopWidth = parseFloat(viewStyle.borderTopWidth) || 0;
+	let borderBottomWidth = parseFloat(viewStyle.borderBottomWidth) || 0;
+	let borderLeftWidth = parseFloat(viewStyle.borderLeftWidth) || 0;
+	let borderRightWidth = parseFloat(viewStyle.borderRightWidth) || 0;
+
+	let scrollAreaTop = target.top - scrollMarginTop;
+	let scrollAreaBottom = target.bottom + scrollMarginBottom;
+	let scrollAreaLeft = target.left - scrollMarginLeft;
+	let scrollAreaRight = target.right + scrollMarginRight;
+
+	let scrollBarOffsetX = scrollView === root ? 0 : borderLeftWidth + borderRightWidth;
+	let scrollBarOffsetY = scrollView === root ? 0 : borderTopWidth + borderBottomWidth;
+	let scrollBarWidth =
+		scrollView === root ? 0 : scrollView.offsetWidth - scrollView.clientWidth - scrollBarOffsetX;
+	let scrollBarHeight =
+		scrollView === root ? 0 : scrollView.offsetHeight - scrollView.clientHeight - scrollBarOffsetY;
+
+	let scrollPortTop = viewTop + (isRoot ? 0 : borderTopWidth) + scrollPaddingTop;
+	let scrollPortBottom =
+		viewBottom - (isRoot ? 0 : borderBottomWidth) - scrollPaddingBottom - scrollBarHeight;
+	let scrollPortLeft = viewLeft + (isRoot ? 0 : borderLeftWidth) + scrollPaddingLeft;
+	let scrollPortRight = viewRight - (isRoot ? 0 : borderRightWidth) - scrollPaddingRight;
+
+	// IOS always positions the scrollbar on the right ¯\_(ツ)_/¯
+	if (viewStyle.direction === 'rtl' && !isIOS()) {
+		scrollPortLeft += scrollBarWidth;
+	} else {
+		scrollPortRight -= scrollBarWidth;
+	}
+
+	let shouldScrollBlock = scrollAreaTop < scrollPortTop || scrollAreaBottom > scrollPortBottom;
+	let shouldScrollInline = scrollAreaLeft < scrollPortLeft || scrollAreaRight > scrollPortRight;
+
+	if (shouldScrollBlock && block === 'start') {
+		y += scrollAreaTop - scrollPortTop;
+	} else if (shouldScrollBlock && block === 'center') {
+		y += (scrollAreaTop + scrollAreaBottom) / 2 - (scrollPortTop + scrollPortBottom) / 2;
+	} else if (shouldScrollBlock && block === 'end') {
+		y += scrollAreaBottom - scrollPortBottom;
+	} else if (shouldScrollBlock && block === 'nearest') {
+		let start = scrollAreaTop - scrollPortTop;
+		let end = scrollAreaBottom - scrollPortBottom;
+		y += Math.abs(start) <= Math.abs(end) ? start : end;
+	}
+
+	if (shouldScrollInline && inline === 'start') {
+		x += scrollAreaLeft - scrollPortLeft;
+	} else if (shouldScrollInline && inline === 'center') {
+		x += (scrollAreaLeft + scrollAreaRight) / 2 - (scrollPortLeft + scrollPortRight) / 2;
+	} else if (shouldScrollInline && inline === 'end') {
+		x += scrollAreaRight - scrollPortRight;
+	} else if (shouldScrollInline && inline === 'nearest') {
+		let start = scrollAreaLeft - scrollPortLeft;
+		let end = scrollAreaRight - scrollPortRight;
+		x += Math.abs(start) <= Math.abs(end) ? start : end;
+	}
+
+	if (process.env.NODE_ENV === 'test') {
+		scrollView.scrollLeft = x;
+		scrollView.scrollTop = y;
+		return;
+	}
+
+	scrollView.scrollTo({ left: x, top: y });
+}
+
+/**
+ * Scrolls the `targetElement` so it is visible in the viewport. Accepts an optional
+ * `opts.containingElement` that will be centered in the viewport prior to scrolling the
+ * targetElement into view. If scrolling is prevented on the body (e.g. targetElement is in a
+ * popover), this will only scroll the scroll parents of the targetElement up to but not including
+ * the body itself.
+ */
+export function scrollIntoViewport(
+	targetElement: Element | null,
+	opts: ScrollIntoViewportOpts = {},
+): void {
+	let { containingElement } = opts;
+	if (targetElement && targetElement.isConnected) {
+		let root = document.scrollingElement || document.documentElement;
+		let isScrollPrevented = window.getComputedStyle(root).overflow === 'hidden';
+		if (!isScrollPrevented) {
+			let { left: originalLeft, top: originalTop } = targetElement.getBoundingClientRect();
+
+			// use scrollIntoView({block: 'nearest'}) instead of .focus to check if the element is fully in view or not since .focus()
+			// won't cause a scroll if the element is already focused and doesn't behave consistently when an element is partially out of view horizontally vs vertically
+			targetElement?.scrollIntoView?.({ block: 'nearest' });
+			let { left: newLeft, top: newTop } = targetElement.getBoundingClientRect();
+			// Account for sub pixel differences from rounding
+			if (Math.abs(originalLeft - newLeft) > 1 || Math.abs(originalTop - newTop) > 1) {
+				containingElement?.scrollIntoView?.({ block: 'center', inline: 'center' });
+				targetElement.scrollIntoView?.({ block: 'nearest' });
+			}
+		} else {
+			let { left: originalLeft, top: originalTop } = targetElement.getBoundingClientRect();
+
+			// If scrolling is prevented, we don't want to scroll the body since it might move the overlay partially offscreen and the user can't scroll it back into view.
+			let scrollParents = getScrollParents(targetElement, true);
+			for (let scrollParent of scrollParents) {
+				scrollIntoView(scrollParent as HTMLElement, targetElement as HTMLElement);
+			}
+			let { left: newLeft, top: newTop } = targetElement.getBoundingClientRect();
+			// Account for sub pixel differences from rounding
+			if (Math.abs(originalLeft - newLeft) > 1 || Math.abs(originalTop - newTop) > 1) {
+				scrollParents = containingElement ? getScrollParents(containingElement, true) : [];
+				// scroll containing element into view first, then rescroll target element into view like the non chrome flow above
+				for (let scrollParent of scrollParents) {
+					scrollIntoView(scrollParent as HTMLElement, containingElement as HTMLElement, {
+						block: 'center',
+						inline: 'center',
+					});
+				}
+				for (let scrollParent of getScrollParents(targetElement, true)) {
+					scrollIntoView(scrollParent as HTMLElement, targetElement as HTMLElement);
+				}
+			}
+		}
+	}
+}

package/src/utils/useDeepMemo.ts

@@ -0,0 +1,30 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/utils/useDeepMemo.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; otherwise verbatim.
+import { useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export function useDeepMemo<T>(value: T, isEqual: (a: T, b: T) => boolean): T;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useDeepMemo<T>(
+	value: T,
+	isEqual: (a: T, b: T) => boolean,
+	slot: symbol | undefined,
+): T;
+export function useDeepMemo(...args: any[]): any {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useDeepMemo');
+	let value = user[0];
+	const isEqual = user[1] as (a: any, b: any) => boolean;
+
+	// Using a ref during render is ok here because it's only an optimization – both values are equivalent.
+	// If a render is thrown away, it'll still work the same no matter if the next render is the same or not.
+	let lastValue = useRef<any>(null, subSlot(slot, 'last'));
+	if (value && lastValue.current && isEqual(value, lastValue.current)) {
+		value = lastValue.current;
+	}
+
+	lastValue.current = value;
+	return value;
+}