@octanejs/base-ui 0.1.1

package/src/utils/composite/useCompositeRoot.ts

@@ -0,0 +1,346 @@
+// Ported from .base-ui/packages/react/src/internals/composite/root/useCompositeRoot.ts.
+// The composite roving-focus engine: owns `highlightedIndex`, wires arrow/Home/End keyboard
+// navigation over `elementsRef`, and sets the default tab stop from the item marked
+// `data-composite-item-active` (or the first enabled item). octane adaptations: events are
+// NATIVE (no `.nativeEvent`), so handlers read the event directly; grid navigation is via a
+// caller-supplied `grid` navigator (unused by ToggleGroup).
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useLayoutEffect, useRef, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { useStableCallback } from '../useStableCallback';
+import { useComposedRefs } from '../composeRefs';
+import {
+	ACTIVE_COMPOSITE_ITEM,
+	ARROW_DOWN,
+	ARROW_KEYS,
+	ARROW_LEFT,
+	ARROW_RIGHT,
+	ARROW_UP,
+	COMPOSITE_KEYS,
+	END,
+	HOME,
+	HORIZONTAL_KEYS,
+	HORIZONTAL_KEYS_WITH_EXTRA_KEYS,
+	MODIFIER_KEYS,
+	VERTICAL_KEYS,
+	VERTICAL_KEYS_WITH_EXTRA_KEYS,
+	isElementDisabled,
+	isNativeInput,
+	scrollIntoViewIfNeeded,
+	type ModifierKey,
+	type TextDirection,
+} from './keys';
+import {
+	findNonDisabledListIndex,
+	getMaxListIndex,
+	getMinListIndex,
+	getTarget,
+	isIndexOutOfListBounds,
+	isListIndexDisabled,
+} from './list-utils';
+import type { CompositeMetadata } from './CompositeList';
+
+export interface UseCompositeRootParameters {
+	orientation?: 'horizontal' | 'vertical' | 'both';
+	grid?: ((params: any) => number) | undefined;
+	loopFocus?: boolean;
+	onLoop?:
+		| ((
+				event: any,
+				prevIndex: number,
+				nextIndex: number,
+				elementsRef: { current: Array<HTMLElement | null> },
+		  ) => number)
+		| undefined;
+	highlightedIndex?: number;
+	onHighlightedIndexChange?: (index: number) => void;
+	direction: TextDirection;
+	rootRef?: any;
+	enableHomeAndEndKeys?: boolean;
+	stopEventPropagation?: boolean;
+	disabledIndices?: number[];
+	modifierKeys?: ModifierKey[];
+}
+
+const EMPTY_ARRAY: never[] = [];
+
+function isModifierKeySet(event: any, ignoredModifierKeys: ModifierKey[]): boolean {
+	for (const key of MODIFIER_KEYS.values()) {
+		if (ignoredModifierKeys.includes(key)) {
+			continue;
+		}
+		if (event.getModifierState(key)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+export function useCompositeRoot(...args: any[]): {
+	props: Record<string, any>;
+	highlightedIndex: number;
+	onHighlightedIndexChange: (index: number, shouldScrollIntoView?: boolean) => void;
+	elementsRef: { current: Array<HTMLElement | null> };
+	disabledIndices: number[] | undefined;
+	onMapChange: (map: Map<Element, CompositeMetadata<any>>) => void;
+	relayKeyboardEvent: (event: any) => void;
+} {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useCompositeRoot');
+	const params = user[0] as UseCompositeRootParameters;
+	const {
+		loopFocus = true,
+		orientation = 'both',
+		grid,
+		onLoop,
+		direction,
+		highlightedIndex: externalHighlightedIndex,
+		onHighlightedIndexChange: externalSetHighlightedIndex,
+		rootRef: externalRef,
+		enableHomeAndEndKeys = false,
+		stopEventPropagation = false,
+		disabledIndices,
+		modifierKeys = EMPTY_ARRAY,
+	} = params;
+
+	const [internalHighlightedIndex, internalSetHighlightedIndex] = useState(0, subSlot(slot, 'hi'));
+	const isGrid = grid != null;
+
+	const rootRef = useRef<HTMLElement | null>(null, subSlot(slot, 'root'));
+	const mergedRef = useComposedRefs(rootRef, externalRef, subSlot(slot, 'merged'));
+
+	const elementsRef = useRef<Array<HTMLElement | null>>([], subSlot(slot, 'els'));
+	const hasSetDefaultIndexRef = useRef(false, subSlot(slot, 'hasSet'));
+
+	const highlightedIndex = externalHighlightedIndex ?? internalHighlightedIndex;
+	const onHighlightedIndexChange = useStableCallback(
+		(index: number, shouldScrollIntoView = false) => {
+			(externalSetHighlightedIndex ?? internalSetHighlightedIndex)(index);
+			if (shouldScrollIntoView) {
+				const newActiveItem = elementsRef.current[index];
+				scrollIntoViewIfNeeded(rootRef.current, newActiveItem, direction, orientation);
+			}
+		},
+		subSlot(slot, 'ohic'),
+	);
+
+	const onMapChange = useStableCallback(
+		(map: Map<Element, CompositeMetadata<any>>) => {
+			if (map.size === 0 || hasSetDefaultIndexRef.current) {
+				return;
+			}
+			hasSetDefaultIndexRef.current = true;
+			const sortedElements = Array.from(map.keys()) as Array<HTMLElement | null>;
+			const activeItem =
+				sortedElements.find((compositeElement) =>
+					compositeElement?.hasAttribute(ACTIVE_COMPOSITE_ITEM),
+				) ?? null;
+			const activeIndex = activeItem ? sortedElements.indexOf(activeItem) : -1;
+
+			if (activeIndex !== -1) {
+				onHighlightedIndexChange(activeIndex);
+			} else if (
+				isListIndexDisabled({ current: sortedElements }, highlightedIndex, disabledIndices)
+			) {
+				const firstEnabledIndex = findNonDisabledListIndex(
+					{ current: sortedElements },
+					{ disabledIndices },
+				);
+				if (!isIndexOutOfListBounds({ current: sortedElements }, firstEnabledIndex)) {
+					onHighlightedIndexChange(firstEnabledIndex);
+				}
+			}
+
+			scrollIntoViewIfNeeded(rootRef.current, activeItem, direction, orientation);
+		},
+		subSlot(slot, 'omc'),
+	);
+
+	useLayoutEffect(
+		() => {
+			if (
+				disabledIndices == null ||
+				externalHighlightedIndex != null ||
+				!hasSetDefaultIndexRef.current
+			) {
+				return;
+			}
+			const elements = elementsRef.current;
+			if (isListIndexDisabled(elementsRef, highlightedIndex, disabledIndices)) {
+				const firstEnabledIndex = findNonDisabledListIndex(elementsRef, { disabledIndices });
+				if (!isIndexOutOfListBounds({ current: elements }, firstEnabledIndex)) {
+					onHighlightedIndexChange(firstEnabledIndex);
+				}
+			}
+		},
+		[
+			disabledIndices,
+			externalHighlightedIndex,
+			highlightedIndex,
+			elementsRef,
+			onHighlightedIndexChange,
+		],
+		subSlot(slot, 'e:validate'),
+	);
+
+	const onKeyDown = useStableCallback(
+		(event: any) => {
+			const RELEVANT_KEYS = enableHomeAndEndKeys ? COMPOSITE_KEYS : ARROW_KEYS;
+			if (!RELEVANT_KEYS.has(event.key)) {
+				return;
+			}
+			if (isModifierKeySet(event, modifierKeys)) {
+				return;
+			}
+
+			const element = rootRef.current;
+			if (!element) {
+				return;
+			}
+
+			const isRtl = direction === 'rtl';
+			const horizontalForwardKey = isRtl ? ARROW_LEFT : ARROW_RIGHT;
+			const forwardKey = {
+				horizontal: horizontalForwardKey,
+				vertical: ARROW_DOWN,
+				both: horizontalForwardKey,
+			}[orientation];
+			const horizontalBackwardKey = isRtl ? ARROW_RIGHT : ARROW_LEFT;
+			const backwardKey = {
+				horizontal: horizontalBackwardKey,
+				vertical: ARROW_UP,
+				both: horizontalBackwardKey,
+			}[orientation];
+
+			// octane: the handler already receives the native event.
+			const target = getTarget(event);
+			if (target != null && isNativeInput(target) && !isElementDisabled(target as HTMLElement)) {
+				const input = target as HTMLInputElement;
+				const selectionStart = input.selectionStart;
+				const selectionEnd = input.selectionEnd;
+				const textContent = input.value ?? '';
+				if (selectionStart == null || event.shiftKey || selectionStart !== selectionEnd) {
+					return;
+				}
+				if (event.key !== backwardKey && selectionStart < textContent.length) {
+					return;
+				}
+				if (event.key !== forwardKey && selectionStart > 0) {
+					return;
+				}
+			}
+
+			let nextIndex = highlightedIndex;
+			const minIndex = getMinListIndex(elementsRef, disabledIndices);
+			const maxIndex = getMaxListIndex(elementsRef, disabledIndices);
+
+			if (grid != null) {
+				nextIndex = grid({
+					disabledIndices,
+					elementsRef,
+					event,
+					highlightedIndex,
+					loopFocus,
+					maxIndex,
+					minIndex,
+					onLoop: (e: any, prev: number, next: number) =>
+						onLoop ? onLoop(e, prev, next, elementsRef) : next,
+					orientation,
+					rtl: isRtl,
+				});
+			}
+
+			const forwardKeys = {
+				horizontal: [horizontalForwardKey],
+				vertical: [ARROW_DOWN],
+				both: [horizontalForwardKey, ARROW_DOWN],
+			}[orientation];
+			const backwardKeys = {
+				horizontal: [horizontalBackwardKey],
+				vertical: [ARROW_UP],
+				both: [horizontalBackwardKey, ARROW_UP],
+			}[orientation];
+
+			const preventedKeys = isGrid
+				? RELEVANT_KEYS
+				: {
+						horizontal: enableHomeAndEndKeys ? HORIZONTAL_KEYS_WITH_EXTRA_KEYS : HORIZONTAL_KEYS,
+						vertical: enableHomeAndEndKeys ? VERTICAL_KEYS_WITH_EXTRA_KEYS : VERTICAL_KEYS,
+						both: RELEVANT_KEYS,
+					}[orientation];
+
+			if (enableHomeAndEndKeys) {
+				if (event.key === HOME) {
+					nextIndex = minIndex;
+				} else if (event.key === END) {
+					nextIndex = maxIndex;
+				}
+			}
+
+			if (
+				nextIndex === highlightedIndex &&
+				(forwardKeys.includes(event.key) || backwardKeys.includes(event.key))
+			) {
+				if (loopFocus && nextIndex === maxIndex && forwardKeys.includes(event.key)) {
+					nextIndex = minIndex;
+					if (onLoop) {
+						nextIndex = onLoop(event, highlightedIndex, nextIndex, elementsRef);
+					}
+				} else if (loopFocus && nextIndex === minIndex && backwardKeys.includes(event.key)) {
+					nextIndex = maxIndex;
+					if (onLoop) {
+						nextIndex = onLoop(event, highlightedIndex, nextIndex, elementsRef);
+					}
+				} else {
+					nextIndex = findNonDisabledListIndex(elementsRef, {
+						startingIndex: nextIndex,
+						decrement: backwardKeys.includes(event.key),
+						disabledIndices,
+					});
+				}
+			}
+
+			if (nextIndex !== highlightedIndex && !isIndexOutOfListBounds(elementsRef, nextIndex)) {
+				if (stopEventPropagation) {
+					event.stopPropagation();
+				}
+				if (preventedKeys.has(event.key)) {
+					event.preventDefault();
+				}
+				onHighlightedIndexChange(nextIndex, true);
+
+				// Wait for FocusManager `returnFocus` to execute.
+				queueMicrotask(() => {
+					elementsRef.current[nextIndex]?.focus();
+				});
+			}
+		},
+		subSlot(slot, 'okd'),
+	);
+
+	const props: Record<string, any> = {
+		ref: mergedRef,
+		onFocus(event: any) {
+			const element = rootRef.current;
+			const target = getTarget(event);
+			if (!element || target == null || !isNativeInput(target)) {
+				return;
+			}
+			const input = target as HTMLInputElement;
+			input.setSelectionRange(0, input.value.length ?? 0);
+		},
+		onKeyDown,
+	};
+
+	return {
+		props,
+		highlightedIndex,
+		onHighlightedIndexChange,
+		elementsRef,
+		disabledIndices,
+		onMapChange,
+		relayKeyboardEvent: onKeyDown,
+	};
+}

package/src/utils/contains.ts

@@ -0,0 +1,22 @@
+// Vendored from @floating-ui/react's `contains` (octane's @octanejs/floating-ui has the same
+// helper internally but doesn't export it). True when `child` is `parent` or inside it,
+// crossing shadow boundaries.
+export function contains(parent?: Element | null, child?: Element | null): boolean {
+	if (!parent || !child) {
+		return false;
+	}
+	if (parent.contains(child)) {
+		return true;
+	}
+	const rootNode = child.getRootNode?.();
+	if (rootNode && (rootNode as ShadowRoot).host) {
+		let next: Node | null = child;
+		while (next) {
+			if (next === parent) {
+				return true;
+			}
+			next = (next as any).parentNode || (next as ShadowRoot).host;
+		}
+	}
+	return false;
+}

package/src/utils/createChangeEventDetails.ts

@@ -0,0 +1,81 @@
+// Ported from .base-ui/packages/react/src/internals/createBaseUIEventDetails.ts +
+// reason-parts.ts. `createChangeEventDetails(reason, event, trigger)` builds the details
+// object Base UI passes to `onXChange` callbacks — a cancelable, propagation-controllable
+// wrapper around the originating event. octane dispatches NATIVE events (no synthetic
+// `.nativeEvent`), so callers pass the native event directly.
+//
+// REASONS: only the reason strings the current components use are listed; more are added
+// as components land (they are just string constants).
+export const REASONS = {
+	none: 'none',
+	triggerPress: 'trigger-press',
+	itemPress: 'item-press',
+	keyboard: 'keyboard',
+	pointer: 'pointer',
+	inputChange: 'input-change',
+	inputClear: 'input-clear',
+	inputBlur: 'input-blur',
+	inputPaste: 'input-paste',
+	incrementPress: 'increment-press',
+	decrementPress: 'decrement-press',
+	wheel: 'wheel',
+	scrub: 'scrub',
+	trackPress: 'track-press',
+	drag: 'drag',
+} as const;
+
+export type BaseUIEventReason = (typeof REASONS)[keyof typeof REASONS];
+
+export interface BaseUIChangeEventDetails<Reason extends string = string> {
+	reason: Reason;
+	event: Event;
+	cancel: () => void;
+	allowPropagation: () => void;
+	readonly isCanceled: boolean;
+	readonly isPropagationAllowed: boolean;
+	trigger: Element | undefined;
+	[key: string]: any;
+}
+
+export function createChangeEventDetails<Reason extends string = string>(
+	reason: Reason,
+	event?: Event,
+	trigger?: HTMLElement,
+	customProperties?: Record<string, any>,
+): BaseUIChangeEventDetails<Reason> {
+	let canceled = false;
+	let allowPropagation = false;
+	const details: BaseUIChangeEventDetails<Reason> = {
+		reason,
+		event: event ?? new Event('base-ui'),
+		cancel() {
+			canceled = true;
+		},
+		allowPropagation() {
+			allowPropagation = true;
+		},
+		get isCanceled() {
+			return canceled;
+		},
+		get isPropagationAllowed() {
+			return allowPropagation;
+		},
+		trigger,
+		...customProperties,
+	};
+	return details;
+}
+
+// Ported from createBaseUIEventDetails.ts (createGenericEventDetails): a non-cancelable details
+// object for "committed"/generic callbacks (e.g. Slider's `onValueCommitted`).
+export function createGenericEventDetails<Reason extends string = string>(
+	reason: Reason,
+	event?: Event,
+	customProperties?: Record<string, any>,
+): { reason: Reason; event: Event; [key: string]: any } {
+	return {
+		reason,
+		event: event ?? new Event('base-ui'),
+		...customProperties,
+	};
+}

package/src/utils/field/FieldItemContext.ts

@@ -0,0 +1,13 @@
+// Ported from .base-ui/packages/react/src/field/item/FieldItemContext.ts. A <Field.Item>
+// (a labelled row inside a group) can disable its control; standalone reads the default.
+import { createContext, useContext } from 'octane';
+
+export interface FieldItemContextValue {
+	disabled: boolean;
+}
+
+export const FieldItemContext = createContext<FieldItemContextValue>({ disabled: false });
+
+export function useFieldItemContext(): FieldItemContextValue {
+	return useContext(FieldItemContext);
+}

package/src/utils/field/FieldRootContext.ts

@@ -0,0 +1,98 @@
+// Ported from .base-ui/packages/react/src/internals/field-root-context/FieldRootContext.ts.
+// A <Field.Root> provides validity/touched/dirty/etc. state + a validation object; standalone
+// controls read `DEFAULT_FIELD_ROOT_CONTEXT` (inert validation, noop setters). `useFieldRootContext`
+// detects "no provider" via `setValidityData === NOOP`.
+import { createContext, useContext } from 'octane';
+
+import { NOOP } from '../noop';
+import {
+	DEFAULT_FIELD_ROOT_STATE,
+	DEFAULT_FIELD_STATE_ATTRIBUTES,
+	DEFAULT_VALIDITY_STATE,
+	type FieldRootState,
+	type FieldValidityData,
+	type FormValidationMode,
+} from './constants';
+
+export interface FieldValidation {
+	getValidationProps: (disabled: boolean, props?: Record<string, any>) => Record<string, any>;
+	inputRef: { current: HTMLInputElement | null };
+	registerInput: (...args: any[]) => void;
+	commit: (value: unknown) => Promise<void>;
+	change: (value: unknown) => void;
+}
+
+export interface FieldRootContextValue {
+	invalid: boolean | undefined;
+	name: string | undefined;
+	validityData: FieldValidityData;
+	setValidityData: (next: any) => void;
+	disabled: boolean | undefined;
+	touched: boolean;
+	setTouched: (next: any) => void;
+	dirty: boolean;
+	setDirty: (next: any) => void;
+	filled: boolean;
+	setFilled: (next: any) => void;
+	focused: boolean;
+	setFocused: (next: any) => void;
+	validate: (
+		value: unknown,
+		formValues: Record<string, unknown>,
+	) => string | string[] | null | Promise<string | string[] | null>;
+	validationMode: FormValidationMode;
+	validationDebounceTime: number;
+	shouldValidateOnChange: () => boolean;
+	state: FieldRootState;
+	markedDirtyRef: { current: boolean };
+	registerFieldControl: (source: symbol, registration: any) => void;
+	validation: FieldValidation;
+}
+
+export const DEFAULT_FIELD_ROOT_CONTEXT: FieldRootContextValue = {
+	invalid: undefined,
+	name: undefined,
+	validityData: {
+		state: DEFAULT_VALIDITY_STATE,
+		errors: [],
+		error: '',
+		value: '',
+		initialValue: null,
+	},
+	setValidityData: NOOP,
+	disabled: undefined,
+	touched: DEFAULT_FIELD_STATE_ATTRIBUTES.touched,
+	setTouched: NOOP,
+	dirty: DEFAULT_FIELD_STATE_ATTRIBUTES.dirty,
+	setDirty: NOOP,
+	filled: DEFAULT_FIELD_STATE_ATTRIBUTES.filled,
+	setFilled: NOOP,
+	focused: DEFAULT_FIELD_STATE_ATTRIBUTES.focused,
+	setFocused: NOOP,
+	validate: () => null,
+	validationMode: 'onSubmit',
+	validationDebounceTime: 0,
+	shouldValidateOnChange: () => false,
+	state: DEFAULT_FIELD_ROOT_STATE,
+	markedDirtyRef: { current: false },
+	registerFieldControl: NOOP,
+	validation: {
+		getValidationProps: (_disabled: boolean, props: Record<string, any> = {}) => props,
+		inputRef: { current: null },
+		registerInput: NOOP,
+		commit: async () => {},
+		change: NOOP,
+	},
+};
+
+export const FieldRootContext = createContext<FieldRootContextValue>(DEFAULT_FIELD_ROOT_CONTEXT);
+
+export function useFieldRootContext(optional = true): FieldRootContextValue {
+	const context = useContext(FieldRootContext);
+	if (context.setValidityData === NOOP && !optional) {
+		throw new Error(
+			'Base UI: FieldRootContext is missing. Field parts must be placed within <Field.Root>.',
+		);
+	}
+	return context;
+}

package/src/utils/field/FormContext.ts

@@ -0,0 +1,37 @@
+// Ported from .base-ui/packages/react/src/internals/form-context/FormContext.ts. A <Form>
+// provides error state + a field registry; standalone controls read the default (no errors,
+// noop clearErrors).
+import { createContext, useContext } from 'octane';
+
+import { NOOP } from '../noop';
+import type { FieldValidityData, FormValidationMode } from './constants';
+
+export type Errors = Record<string, string | string[]>;
+
+export interface FormFieldEntry {
+	name: string | undefined;
+	validate: () => void;
+	validityData: FieldValidityData;
+	controlRef: { current: HTMLElement | null };
+	getValue: () => unknown;
+}
+
+export interface FormContextValue {
+	errors: Errors;
+	clearErrors: (name: string | undefined) => void;
+	formRef: { current: { fields: Map<string, FormFieldEntry> } };
+	validationMode: FormValidationMode;
+	submitAttemptedRef: { current: boolean };
+}
+
+export const FormContext = createContext<FormContextValue>({
+	formRef: { current: { fields: new Map() } },
+	errors: {},
+	clearErrors: NOOP,
+	validationMode: 'onSubmit',
+	submitAttemptedRef: { current: false },
+});
+
+export function useFormContext(): FormContextValue {
+	return useContext(FormContext);
+}

package/src/utils/field/LabelableContext.ts

@@ -0,0 +1,32 @@
+// Ported from .base-ui/packages/react/src/internals/labelable-provider/LabelableContext.ts.
+// Associates a labelable element with an accessible name/description. Standalone controls read
+// the default (no label association; `registerControlId === NOOP` marks "no provider").
+import { createContext, useContext } from 'octane';
+
+import { NOOP } from '../noop';
+
+export interface LabelableContextValue {
+	controlId: string | null | undefined;
+	registerControlId: (source: symbol, id: string | null | undefined) => void;
+	labelId: string | undefined;
+	setLabelId: (
+		next: string | undefined | ((prev: string | undefined) => string | undefined),
+	) => void;
+	messageIds: string[];
+	setMessageIds: (next: string[] | ((prev: string[]) => string[])) => void;
+	getDescriptionProps: (externalProps: Record<string, any>) => Record<string, any>;
+}
+
+export const LabelableContext = createContext<LabelableContextValue>({
+	controlId: undefined,
+	registerControlId: NOOP,
+	labelId: undefined,
+	setLabelId: NOOP,
+	messageIds: [],
+	setMessageIds: NOOP,
+	getDescriptionProps: (externalProps: Record<string, any>) => externalProps,
+});
+
+export function useLabelableContext(): LabelableContextValue {
+	return useContext(LabelableContext);
+}