@octanejs/base-ui 0.1.1

package/src/utils/CheckboxGroupContext.ts

@@ -0,0 +1,30 @@
+// Ported from .base-ui/packages/react/src/checkbox-group/CheckboxGroupContext.ts. Provided by
+// a <CheckboxGroup>; `useCheckboxGroupContext()` returns undefined for a standalone checkbox.
+// The full CheckboxGroup + parent-checkbox machinery lands with CheckboxGroup — the `parent`
+// surface is typed loosely here.
+import { createContext, useContext } from 'octane';
+
+import type { FieldValidation } from './field/FieldRootContext';
+
+export interface CheckboxGroupContextValue {
+	value: string[] | undefined;
+	defaultValue: string[] | undefined;
+	setValue: (value: string[], eventDetails: any) => void;
+	allValues: string[] | undefined;
+	parent: any;
+	disabled: boolean;
+	validation: FieldValidation;
+	registerControlRef: (element: HTMLButtonElement | null) => void;
+}
+
+export const CheckboxGroupContext = createContext<CheckboxGroupContextValue | undefined>(undefined);
+
+export function useCheckboxGroupContext(optional = true): CheckboxGroupContextValue | undefined {
+	const context = useContext(CheckboxGroupContext);
+	if (context === undefined && !optional) {
+		throw new Error(
+			'Base UI: CheckboxGroupContext is missing. CheckboxGroup parts must be placed within <CheckboxGroup>.',
+		);
+	}
+	return context;
+}

package/src/utils/CompositeRootContext.ts

@@ -0,0 +1,27 @@
+// Ported from .base-ui/packages/react/src/internals/composite/root/CompositeRootContext.ts.
+// The composite (roving-focus) root context. Only the pieces the current components read
+// are typed; the full surface lands with the composite navigation system (ToggleGroup /
+// Toolbar / menus). Standalone button-likes call `useCompositeRootContext(true)`, which
+// returns undefined when there's no <Composite.Root> ancestor.
+import { createContext, useContext } from 'octane';
+
+export interface CompositeRootContextValue {
+	highlightedIndex: number;
+	onHighlightedIndexChange: (index: number, shouldScrollIntoView?: boolean) => void;
+	highlightItemOnHover: boolean;
+	relayKeyboardEvent: (event: KeyboardEvent) => void;
+}
+
+export const CompositeRootContext = createContext<CompositeRootContextValue | undefined>(undefined);
+
+export function useCompositeRootContext(optional: true): CompositeRootContextValue | undefined;
+export function useCompositeRootContext(optional?: false): CompositeRootContextValue;
+export function useCompositeRootContext(optional = false): CompositeRootContextValue | undefined {
+	const context = useContext(CompositeRootContext);
+	if (context === undefined && !optional) {
+		throw new Error(
+			'Base UI: CompositeRootContext is missing. Composite parts must be placed within <Composite.Root>.',
+		);
+	}
+	return context;
+}

package/src/utils/DirectionContext.ts

@@ -0,0 +1,15 @@
+// Ported from .base-ui/packages/react/src/direction-context/DirectionContext.tsx. Reading
+// direction ('ltr' | 'rtl'); `useDirection()` reads the nearest provider, defaulting to
+// 'ltr'. (Base UI's `DirectionProvider` is a Phase-later public part; only the context +
+// hook are needed by the composite system now.)
+import { createContext, useContext } from 'octane';
+
+import type { TextDirection } from './composite/keys';
+
+export type { TextDirection };
+
+export const DirectionContext = createContext<TextDirection | undefined>(undefined);
+
+export function useDirection(): TextDirection {
+	return useContext(DirectionContext) ?? 'ltr';
+}

package/src/utils/RadioGroupContext.ts

@@ -0,0 +1,27 @@
+// Ported from .base-ui/packages/react/src/radio-group/RadioGroupContext.ts. Provided by a
+// <RadioGroup>; a standalone <Radio.Root> reads undefined and self-manages `checked`.
+import { createContext, useContext } from 'octane';
+
+import type { FieldValidation } from './field/FieldRootContext';
+
+export interface RadioGroupContextValue<Value = any> {
+	disabled: boolean | undefined;
+	readOnly: boolean | undefined;
+	required: boolean | undefined;
+	form: string | undefined;
+	name: string | undefined;
+	checkedValue: Value | undefined;
+	setCheckedValue: (value: Value, eventDetails: any) => void;
+	touched: boolean;
+	setTouched: (next: boolean | ((prev: boolean) => boolean)) => void;
+	validation?: FieldValidation | undefined;
+	registerControlRef: (element: HTMLElement | null, disabled?: boolean) => void;
+	registerInputRef: (element: HTMLInputElement | null) => void;
+	[key: string]: any;
+}
+
+export const RadioGroupContext = createContext<RadioGroupContextValue | undefined>(undefined);
+
+export function useRadioGroupContext(): RadioGroupContextValue | undefined {
+	return useContext(RadioGroupContext);
+}

package/src/utils/ToggleGroupContext.ts

@@ -0,0 +1,33 @@
+// Ported from .base-ui/packages/react/src/toggle-group/ToggleGroupContext.ts. The context
+// a <ToggleGroup> provides to its child <Toggle>s. `useToggleGroupContext()` defaults to
+// optional (returns undefined when a Toggle is standalone). ToggleGroup itself lands in a
+// later Phase-1 step; this context is the shared contract.
+import { createContext, useContext } from 'octane';
+
+import type { BaseUIChangeEventDetails } from './createChangeEventDetails';
+
+export interface ToggleGroupContextValue<Value = any> {
+	value: readonly Value[];
+	setGroupValue: (
+		newValue: Value,
+		nextPressed: boolean,
+		eventDetails: BaseUIChangeEventDetails,
+	) => void;
+	disabled: boolean;
+	orientation: 'horizontal' | 'vertical';
+	isValueInitialized: boolean;
+}
+
+export const ToggleGroupContext = createContext<ToggleGroupContextValue | undefined>(undefined);
+
+export function useToggleGroupContext<Value = any>(
+	optional = true,
+): ToggleGroupContextValue<Value> | undefined {
+	const context = useContext(ToggleGroupContext) as ToggleGroupContextValue<Value> | undefined;
+	if (context === undefined && !optional) {
+		throw new Error(
+			'Base UI: ToggleGroupContext is missing. ToggleGroup parts must be placed within <ToggleGroup>.',
+		);
+	}
+	return context;
+}

package/src/utils/addEventListener.ts

@@ -0,0 +1,13 @@
+// Ported from .base-ui/packages/utils/src/addEventListener.ts. Adds a listener, returns a
+// cleanup that removes it.
+export function addEventListener(
+	target: { addEventListener: any; removeEventListener: any },
+	type: string,
+	listener: EventListenerOrEventListenerObject,
+	options?: boolean | AddEventListenerOptions,
+): () => void {
+	target.addEventListener(type, listener, options);
+	return () => {
+		target.removeEventListener(type, listener, options);
+	};
+}

package/src/utils/areArraysEqual.ts

@@ -0,0 +1,11 @@
+// Ported verbatim from .base-ui/packages/react/src/internals/areArraysEqual.ts.
+export function areArraysEqual<Item>(
+	array1: ReadonlyArray<Item>,
+	array2: ReadonlyArray<Item>,
+	itemComparer: (a: Item, b: Item) => boolean = (a, b) => a === b,
+): boolean {
+	return (
+		array1.length === array2.length &&
+		array1.every((value, index) => itemComparer(value, array2[index]))
+	);
+}

package/src/utils/clamp.ts

@@ -0,0 +1,8 @@
+// Ported verbatim from .base-ui/packages/react/src/internals/clamp.ts.
+export function clamp(
+	val: number,
+	min: number = Number.MIN_SAFE_INTEGER,
+	max: number = Number.MAX_SAFE_INTEGER,
+): number {
+	return Math.max(min, Math.min(val, max));
+}

package/src/utils/composeRefs.ts

@@ -0,0 +1,53 @@
+// Ported from @radix-ui/react-compose-refs. Merges multiple refs (objects or callbacks,
+// incl. React-19 cleanup-returning callback refs) into one callback ref. octane is
+// ref-as-prop, so these compose the `ref` values a Slot/Primitive threads onto a child.
+import { useCallback } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+type PossibleRef<T> = ((instance: T | null) => void | (() => void)) | { current: T | null } | null;
+
+function setRef<T>(ref: PossibleRef<T>, value: T | null): void | (() => void) {
+	if (typeof ref === 'function') {
+		return ref(value);
+	} else if (ref !== null && ref !== undefined) {
+		ref.current = value;
+	}
+}
+
+/**
+ * Compose multiple refs into a single callback ref. Honors cleanup functions returned by
+ * callback refs (React 19 semantics); falls back to calling refs with `null` on unmount.
+ */
+export function composeRefs<T>(...refs: PossibleRef<T>[]): (node: T | null) => void | (() => void) {
+	return (node: T | null) => {
+		let hasCleanup = false;
+		const cleanups = refs.map((ref) => {
+			const cleanup = setRef(ref, node);
+			if (!hasCleanup && typeof cleanup === 'function') {
+				hasCleanup = true;
+			}
+			return cleanup;
+		});
+		if (hasCleanup) {
+			return () => {
+				for (let i = 0; i < cleanups.length; i++) {
+					const cleanup = cleanups[i];
+					if (typeof cleanup === 'function') {
+						cleanup();
+					} else {
+						setRef(refs[i], null);
+					}
+				}
+			};
+		}
+	};
+}
+
+/** Hook version — a stable composed callback ref over the given refs. */
+export function useComposedRefs<T>(...args: any[]): (node: T | null) => void | (() => void) {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useComposedRefs');
+	const refs = user as PossibleRef<T>[];
+	return useCallback(composeRefs(...refs), refs, subSlot(slot, 'cb'));
+}

package/src/utils/composite/CompositeItem.ts

@@ -0,0 +1,56 @@
+// Ported from .base-ui/packages/react/src/internals/composite/item/CompositeItem.tsx.
+// Renders a composite item, merging the roving-focus props (tabIndex/onFocus/onMouseMove)
+// UNDER the caller's own props, and composing the caller's refs with the composite ref.
+import { S, subSlot } from '../../internal';
+import { useRenderElement } from '../useRenderElement';
+import type { StateAttributesMapping } from '../getStateAttributesProps';
+import { useCompositeItem } from './useCompositeItem';
+
+const EMPTY_ARRAY: never[] = [];
+const EMPTY_OBJECT: Record<string, never> = {};
+
+export interface CompositeItemProps<Metadata, State extends Record<string, any>> {
+	render?: any;
+	className?: any;
+	style?: any;
+	children?: any;
+	metadata?: Metadata;
+	refs?: any[];
+	props?: Array<Record<string, any> | (() => Record<string, any>)>;
+	state?: State;
+	stateAttributesMapping?: StateAttributesMapping<State>;
+	tag?: string;
+	[key: string]: any;
+}
+
+export function CompositeItem<Metadata, State extends Record<string, any>>(
+	componentProps: CompositeItemProps<Metadata, State>,
+): any {
+	const slot = S('CompositeItem');
+	const {
+		render,
+		className,
+		style,
+		state = EMPTY_OBJECT as State,
+		props = EMPTY_ARRAY,
+		refs = EMPTY_ARRAY,
+		metadata,
+		stateAttributesMapping,
+		tag = 'div',
+		...elementProps
+	} = componentProps;
+
+	const { compositeProps, compositeRef } = useCompositeItem({ metadata }, subSlot(slot, 'item'));
+
+	return useRenderElement(
+		tag,
+		{ render, className, style },
+		{
+			state,
+			ref: [...refs, compositeRef],
+			props: [compositeProps, ...props, elementProps],
+			stateAttributesMapping,
+		},
+		subSlot(slot, 're'),
+	);
+}

package/src/utils/composite/CompositeList.ts

@@ -0,0 +1,190 @@
+// Ported from .base-ui/packages/react/src/internals/composite/list/CompositeList.tsx.
+// Registers composite items in a stable Map, sorts them by document position to assign each
+// a DOM-order `index`, and notifies subscribers (`onMapChange` / `subscribeMapChange`) plus
+// keeps `elementsRef` sized. A MutationObserver re-sorts when the DOM reorders. Rendered by
+// CompositeRoot as `<CompositeListContext.Provider>{children}</Provider>`.
+import { createElement, useLayoutEffect, useMemo, useRef, useState } from 'octane';
+
+import { S, subSlot } from '../../internal';
+import { useStableCallback } from '../useStableCallback';
+import { useRefWithInit } from '../useRefWithInit';
+import { CompositeListContext } from './CompositeListContext';
+
+export type CompositeMetadata<CustomMetadata> = {
+	index?: number | null | undefined;
+} & CustomMetadata;
+
+export interface CompositeListProps<Metadata> {
+	children: any;
+	elementsRef: { current: Array<HTMLElement | null> };
+	labelsRef?: { current: Array<string | null> } | undefined;
+	onMapChange?: (newMap: Map<Element, CompositeMetadata<Metadata> | null>) => void;
+}
+
+function createMap<Metadata>(): Map<Element, CompositeMetadata<Metadata> | null> {
+	return new Map();
+}
+
+function createListeners(): Set<Function> {
+	return new Set();
+}
+
+function sortByDocumentPosition(a: Element, b: Element): number {
+	const position = a.compareDocumentPosition(b);
+	if (
+		position & Node.DOCUMENT_POSITION_FOLLOWING ||
+		position & Node.DOCUMENT_POSITION_CONTAINED_BY
+	) {
+		return -1;
+	}
+	if (position & Node.DOCUMENT_POSITION_PRECEDING || position & Node.DOCUMENT_POSITION_CONTAINS) {
+		return 1;
+	}
+	return 0;
+}
+
+export function CompositeList<Metadata>(props: CompositeListProps<Metadata>): any {
+	const slot = S('CompositeList');
+	const { children, elementsRef, labelsRef, onMapChange: onMapChangeProp } = props;
+
+	const onMapChange = useStableCallback(onMapChangeProp, subSlot(slot, 'omc'));
+
+	const nextIndexRef = useRef(0, subSlot(slot, 'nextIdx'));
+	const listeners = useRefWithInit<Set<Function>>(
+		createListeners,
+		subSlot(slot, 'listeners'),
+	).current;
+
+	const map = useRefWithInit<Map<Element, CompositeMetadata<Metadata> | null>>(
+		createMap,
+		subSlot(slot, 'map'),
+	).current;
+	const [mapTick, setMapTick] = useState(0, subSlot(slot, 'tick'));
+	const lastTickRef = useRef(mapTick, subSlot(slot, 'lastTick'));
+
+	const register = useStableCallback(
+		(node: Element, metadata: Metadata) => {
+			map.set(node, (metadata ?? null) as CompositeMetadata<Metadata> | null);
+			lastTickRef.current += 1;
+			setMapTick(lastTickRef.current);
+		},
+		subSlot(slot, 'reg'),
+	);
+
+	const unregister = useStableCallback(
+		(node: Element) => {
+			map.delete(node);
+			lastTickRef.current += 1;
+			setMapTick(lastTickRef.current);
+		},
+		subSlot(slot, 'unreg'),
+	);
+
+	const sortedMap = useMemo(
+		() => {
+			const newMap = new Map<Element, CompositeMetadata<Metadata>>();
+			const sortedNodes = Array.from(map.keys())
+				.filter((node) => node.isConnected)
+				.sort(sortByDocumentPosition);
+			sortedNodes.forEach((node, index) => {
+				const metadata = map.get(node) ?? ({} as CompositeMetadata<Metadata>);
+				newMap.set(node, { ...metadata, index });
+			});
+			return newMap;
+		},
+		[map, mapTick],
+		subSlot(slot, 'sorted'),
+	);
+
+	useLayoutEffect(
+		() => {
+			if (typeof MutationObserver !== 'function' || sortedMap.size === 0) {
+				return undefined;
+			}
+			const mutationObserver = new MutationObserver((entries) => {
+				const diff = new Set<Node>();
+				const updateDiff = (node: Node) => (diff.has(node) ? diff.delete(node) : diff.add(node));
+				entries.forEach((entry) => {
+					entry.removedNodes.forEach(updateDiff);
+					entry.addedNodes.forEach(updateDiff);
+				});
+				if (diff.size === 0) {
+					lastTickRef.current += 1;
+					setMapTick(lastTickRef.current);
+				}
+			});
+			sortedMap.forEach((_, node) => {
+				if (node.parentElement) {
+					mutationObserver.observe(node.parentElement, { childList: true });
+				}
+			});
+			return () => {
+				mutationObserver.disconnect();
+			};
+		},
+		[sortedMap],
+		subSlot(slot, 'e:mo'),
+	);
+
+	useLayoutEffect(
+		() => {
+			const shouldUpdateLengths = lastTickRef.current === mapTick;
+			if (shouldUpdateLengths) {
+				if (elementsRef.current.length !== sortedMap.size) {
+					elementsRef.current.length = sortedMap.size;
+				}
+				if (labelsRef && labelsRef.current.length !== sortedMap.size) {
+					labelsRef.current.length = sortedMap.size;
+				}
+				nextIndexRef.current = sortedMap.size;
+			}
+			onMapChange(sortedMap);
+		},
+		[onMapChange, sortedMap, elementsRef, labelsRef, mapTick],
+		subSlot(slot, 'e:len'),
+	);
+
+	useLayoutEffect(
+		() => () => {
+			elementsRef.current = [];
+		},
+		[elementsRef],
+		subSlot(slot, 'e:cleanEl'),
+	);
+
+	useLayoutEffect(
+		() => () => {
+			if (labelsRef) {
+				labelsRef.current = [];
+			}
+		},
+		[labelsRef],
+		subSlot(slot, 'e:cleanLbl'),
+	);
+
+	const subscribeMapChange = useStableCallback(
+		(fn: (map: Map<Element, any>) => void) => {
+			listeners.add(fn);
+			return () => {
+				listeners.delete(fn);
+			};
+		},
+		subSlot(slot, 'sub'),
+	);
+
+	useLayoutEffect(
+		() => {
+			listeners.forEach((l) => (l as (m: any) => void)(sortedMap));
+		},
+		[listeners, sortedMap],
+		subSlot(slot, 'e:notify'),
+	);
+
+	const contextValue = useMemo(
+		() => ({ register, unregister, subscribeMapChange, elementsRef, labelsRef, nextIndexRef }),
+		[register, unregister, subscribeMapChange, elementsRef, labelsRef, nextIndexRef],
+		subSlot(slot, 'ctx'),
+	);
+
+	return createElement(CompositeListContext.Provider, { value: contextValue, children });
+}

package/src/utils/composite/CompositeListContext.ts

@@ -0,0 +1,23 @@
+// Ported from .base-ui/packages/react/src/internals/composite/list/CompositeListContext.ts.
+import { createContext, useContext } from 'octane';
+
+export interface CompositeListContextValue<Metadata> {
+	register: (node: Element, metadata: Metadata) => void;
+	unregister: (node: Element) => void;
+	subscribeMapChange: (fn: (map: Map<Element, Metadata | null>) => void) => () => void;
+	elementsRef: { current: Array<HTMLElement | null> };
+	labelsRef?: { current: Array<string | null> } | undefined;
+	nextIndexRef: { current: number };
+}
+
+export const CompositeListContext = createContext<CompositeListContextValue<any>>({
+	register: () => {},
+	unregister: () => {},
+	subscribeMapChange: () => () => {},
+	elementsRef: { current: [] },
+	nextIndexRef: { current: 0 },
+});
+
+export function useCompositeListContext(): CompositeListContextValue<any> {
+	return useContext(CompositeListContext);
+}

package/src/utils/composite/CompositeRoot.ts

@@ -0,0 +1,132 @@
+// Ported from .base-ui/packages/react/src/internals/composite/root/CompositeRoot.tsx.
+// Wraps a composite in the roving-focus engine (useCompositeRoot) + the item registry
+// (CompositeList), and provides CompositeRootContext to the items.
+import { createElement, useMemo } from 'octane';
+
+import { S, subSlot } from '../../internal';
+import { useRenderElement } from '../useRenderElement';
+import type { StateAttributesMapping } from '../getStateAttributesProps';
+import { useDirection } from '../DirectionContext';
+import { CompositeRootContext } from '../CompositeRootContext';
+import { CompositeList, type CompositeMetadata } from './CompositeList';
+import { useCompositeRoot } from './useCompositeRoot';
+import type { ModifierKey } from './keys';
+
+const EMPTY_ARRAY: never[] = [];
+const EMPTY_OBJECT: Record<string, never> = {};
+
+export interface CompositeRootProps<Metadata, State extends Record<string, any>> {
+	render?: any;
+	className?: any;
+	style?: any;
+	refs?: any[];
+	props?: Array<Record<string, any> | (() => Record<string, any>)>;
+	state?: State;
+	stateAttributesMapping?: StateAttributesMapping<State>;
+	highlightedIndex?: number;
+	onHighlightedIndexChange?: (index: number) => void;
+	orientation?: 'horizontal' | 'vertical' | 'both';
+	grid?: ((params: any) => number) | undefined;
+	loopFocus?: boolean;
+	onLoop?: any;
+	enableHomeAndEndKeys?: boolean;
+	onMapChange?: (newMap: Map<Element, CompositeMetadata<Metadata> | null>) => void;
+	stopEventPropagation?: boolean;
+	rootRef?: any;
+	disabledIndices?: number[];
+	modifierKeys?: ModifierKey[];
+	highlightItemOnHover?: boolean;
+	tag?: string;
+	[key: string]: any;
+}
+
+export function CompositeRoot<Metadata extends {}, State extends Record<string, any>>(
+	componentProps: CompositeRootProps<Metadata, State>,
+): any {
+	const slot = S('CompositeRoot');
+	const {
+		render,
+		className,
+		style,
+		refs = EMPTY_ARRAY,
+		props = EMPTY_ARRAY,
+		state = EMPTY_OBJECT as State,
+		stateAttributesMapping,
+		highlightedIndex: highlightedIndexProp,
+		onHighlightedIndexChange: onHighlightedIndexChangeProp,
+		orientation,
+		grid,
+		loopFocus,
+		onLoop,
+		enableHomeAndEndKeys,
+		onMapChange: onMapChangeProp,
+		stopEventPropagation = true,
+		rootRef,
+		disabledIndices,
+		modifierKeys,
+		highlightItemOnHover = false,
+		tag = 'div',
+		...elementProps
+	} = componentProps;
+
+	const direction = useDirection();
+
+	const {
+		props: defaultProps,
+		highlightedIndex,
+		onHighlightedIndexChange,
+		elementsRef,
+		onMapChange: onMapChangeUnwrapped,
+		relayKeyboardEvent,
+	} = useCompositeRoot(
+		{
+			grid,
+			loopFocus,
+			onLoop,
+			orientation,
+			highlightedIndex: highlightedIndexProp,
+			onHighlightedIndexChange: onHighlightedIndexChangeProp,
+			rootRef,
+			stopEventPropagation,
+			enableHomeAndEndKeys,
+			direction,
+			disabledIndices,
+			modifierKeys,
+		},
+		subSlot(slot, 'root'),
+	);
+
+	const element = useRenderElement(
+		tag,
+		{ render, className, style },
+		{
+			state,
+			ref: refs,
+			props: [defaultProps, ...props, elementProps],
+			stateAttributesMapping,
+		},
+		subSlot(slot, 're'),
+	);
+
+	const contextValue = useMemo(
+		() => ({
+			highlightedIndex,
+			onHighlightedIndexChange,
+			highlightItemOnHover,
+			relayKeyboardEvent,
+		}),
+		[highlightedIndex, onHighlightedIndexChange, highlightItemOnHover, relayKeyboardEvent],
+		subSlot(slot, 'ctx'),
+	);
+
+	const list = createElement(CompositeList, {
+		elementsRef,
+		onMapChange: (newMap: any) => {
+			onMapChangeProp?.(newMap);
+			onMapChangeUnwrapped(newMap);
+		},
+		children: element,
+	});
+
+	return createElement(CompositeRootContext.Provider, { value: contextValue, children: list });
+}