@octanejs/base-ui 0.1.1

package/src/utils/field/useFieldValidation.ts

@@ -0,0 +1,311 @@
+// Ported from .base-ui/packages/react/src/field/root/useFieldValidation.ts. The field's
+// validation state machine: runs native constraint validation + a custom `validate` fn on
+// commit/change (debounced), tracks a registry of inputs (for checkbox groups), and produces
+// `getValidationProps` (aria-invalid + aria-describedby). Framework-agnostic logic; octane
+// hooks are slot-threaded.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useCallback, useMemo, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { mergeProps } from '../mergeProps';
+import { useTimeout } from '../useTimeout';
+import { useRefWithInit } from '../useRefWithInit';
+import { useStableCallback } from '../useStableCallback';
+import { DEFAULT_VALIDITY_STATE, type FieldValidityData, type FieldRootState } from './constants';
+import { getCombinedFieldValidityData } from './getCombinedFieldValidityData';
+import { useFormContext } from './FormContext';
+import { useLabelableContext } from './LabelableContext';
+
+const validityKeys = Object.keys(DEFAULT_VALIDITY_STATE) as Array<keyof ValidityState>;
+
+function isOnlyValueMissing(state: Record<string, boolean> | undefined): boolean {
+	if (!state || state.valid || !state.valueMissing) {
+		return false;
+	}
+	let onlyValueMissing = false;
+	for (const key of validityKeys) {
+		if (key === 'valid') {
+			continue;
+		}
+		if (key === 'valueMissing') {
+			onlyValueMissing = state[key];
+		} else if (state[key]) {
+			onlyValueMissing = false;
+		}
+	}
+	return onlyValueMissing;
+}
+
+function findRepresentativeInput(inputs: Set<HTMLInputElement>): HTMLInputElement | null {
+	let fallback: HTMLInputElement | null = null;
+	for (const input of inputs) {
+		if (input.disabled) {
+			continue;
+		}
+		if (!input.validity.valid) {
+			return input;
+		}
+		fallback ??= input;
+	}
+	return fallback;
+}
+
+function clearCustomValidity(element: HTMLInputElement, inputs: Set<HTMLInputElement>): void {
+	let didClearElement = false;
+	for (const input of inputs) {
+		input.setCustomValidity('');
+		didClearElement ||= input === element;
+	}
+	if (!didClearElement) {
+		element.setCustomValidity('');
+	}
+}
+
+export interface UseFieldValidationParameters {
+	setValidityData: (data: FieldValidityData) => void;
+	validate: (value: unknown, formValues: Record<string, unknown>) => any;
+	validityData: FieldValidityData;
+	validationDebounceTime: number;
+	invalid: boolean;
+	markedDirtyRef: { current: boolean };
+	state: FieldRootState;
+	shouldValidateOnChange: () => boolean;
+	getRegisteredFieldId: () => string | undefined;
+}
+
+export function useFieldValidation(...args: any[]): any {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useFieldValidation');
+	const params = user[0] as UseFieldValidationParameters;
+	const { formRef } = useFormContext();
+	const {
+		setValidityData,
+		validate,
+		validityData,
+		validationDebounceTime,
+		invalid,
+		markedDirtyRef,
+		state,
+		shouldValidateOnChange,
+		getRegisteredFieldId,
+	} = params;
+
+	const { controlId, getDescriptionProps } = useLabelableContext();
+
+	const timeout = useTimeout(subSlot(slot, 'timeout'));
+	const inputRef = useRef<HTMLInputElement | null>(null, subSlot(slot, 'inputRef'));
+	const registeredInputs = useRefWithInit<Set<HTMLInputElement>>(
+		() => new Set(),
+		subSlot(slot, 'registered'),
+	).current;
+	const validationCommitIdRef = useRef(0, subSlot(slot, 'commitId'));
+
+	const registerInput = useCallback(
+		(element: HTMLInputElement | null) => {
+			if (!element) {
+				return undefined;
+			}
+			registeredInputs.add(element);
+			return () => {
+				registeredInputs.delete(element);
+			};
+		},
+		[registeredInputs],
+		subSlot(slot, 'registerInput'),
+	);
+
+	const commit = useStableCallback(
+		async (value: unknown, revalidate = false) => {
+			const element = findRepresentativeInput(registeredInputs) ?? inputRef.current;
+			if (!element) {
+				return;
+			}
+
+			validationCommitIdRef.current += 1;
+			const validationCommitId = validationCommitIdRef.current;
+
+			function updateRegisteredFieldValidity(
+				nextValidityData: FieldValidityData,
+				externalInvalid = invalid,
+			): void {
+				const fieldId = getRegisteredFieldId() ?? controlId;
+				if (fieldId == null) {
+					return;
+				}
+				const currentFieldData = formRef.current.fields.get(fieldId);
+				if (!currentFieldData) {
+					return;
+				}
+				const validityDataWithFormErrors = getCombinedFieldValidityData(
+					nextValidityData,
+					externalInvalid,
+				);
+				formRef.current.fields.set(fieldId, {
+					...currentFieldData,
+					validityData: validityDataWithFormErrors,
+				});
+			}
+
+			if (revalidate) {
+				if (state.valid !== false) {
+					return;
+				}
+				const currentNativeValidity = element.validity;
+				if (!currentNativeValidity.valueMissing) {
+					const nextValidityData: FieldValidityData = {
+						value,
+						state: { ...DEFAULT_VALIDITY_STATE, valid: true },
+						error: '',
+						errors: [],
+						initialValue: validityData.initialValue,
+					};
+					clearCustomValidity(element, registeredInputs);
+					updateRegisteredFieldValidity(nextValidityData, false);
+					setValidityData(nextValidityData);
+					return;
+				}
+				const currentNativeValidityObject = validityKeys.reduce(
+					(acc, key) => {
+						acc[key] = currentNativeValidity[key];
+						return acc;
+					},
+					{} as Record<string, boolean>,
+				);
+				if (
+					!currentNativeValidityObject.valid &&
+					!isOnlyValueMissing(currentNativeValidityObject)
+				) {
+					return;
+				}
+			}
+
+			function getState(el: HTMLInputElement): Record<string, boolean> {
+				const computedState = validityKeys.reduce(
+					(acc, key) => {
+						acc[key] = el.validity[key];
+						return acc;
+					},
+					{} as Record<string, boolean>,
+				);
+				let hasOnlyValueMissingError = false;
+				for (const key of validityKeys) {
+					if (key === 'valid') {
+						continue;
+					}
+					if (key === 'valueMissing' && computedState[key]) {
+						hasOnlyValueMissingError = true;
+					} else if (computedState[key]) {
+						return computedState;
+					}
+				}
+				if (hasOnlyValueMissingError && !markedDirtyRef.current) {
+					computedState.valid = true;
+					computedState.valueMissing = false;
+				}
+				return computedState;
+			}
+
+			timeout.clear();
+
+			let result: null | string | string[] = null;
+			let validationErrors: string[] = [];
+			const nextState = getState(element);
+			let defaultValidationMessage: string | undefined;
+			const isValidatingOnChange = shouldValidateOnChange();
+
+			if (element.validationMessage && !isValidatingOnChange) {
+				defaultValidationMessage = element.validationMessage;
+				validationErrors = [element.validationMessage];
+			} else {
+				const formValues = Array.from(formRef.current.fields.values()).reduce(
+					(acc: Record<string, unknown>, field: any) => {
+						if (field.name) {
+							acc[field.name] = field.getValue();
+						}
+						return acc;
+					},
+					{} as Record<string, unknown>,
+				);
+				const resultOrPromise = validate(value, formValues);
+				if (
+					typeof resultOrPromise === 'object' &&
+					resultOrPromise !== null &&
+					'then' in resultOrPromise
+				) {
+					result = await resultOrPromise;
+					if (validationCommitId !== validationCommitIdRef.current) {
+						return;
+					}
+				} else {
+					result = resultOrPromise;
+				}
+
+				if (result !== null) {
+					nextState.valid = false;
+					nextState.customError = true;
+					if (Array.isArray(result)) {
+						validationErrors = result;
+						element.setCustomValidity(result.join('\n'));
+					} else if (result) {
+						validationErrors = [result];
+						element.setCustomValidity(result);
+					}
+				} else if (isValidatingOnChange) {
+					clearCustomValidity(element, registeredInputs);
+					nextState.customError = false;
+					if (element.validationMessage) {
+						defaultValidationMessage = element.validationMessage;
+						validationErrors = [element.validationMessage];
+					} else if (element.validity.valid && !nextState.valid) {
+						nextState.valid = true;
+					}
+				}
+			}
+
+			const nextValidityData: FieldValidityData = {
+				value,
+				state: nextState as any,
+				error: defaultValidationMessage ?? (Array.isArray(result) ? result[0] : (result ?? '')),
+				errors: validationErrors,
+				initialValue: validityData.initialValue,
+			};
+
+			updateRegisteredFieldValidity(nextValidityData);
+			setValidityData(nextValidityData);
+		},
+		subSlot(slot, 'commit'),
+	);
+
+	const change = useStableCallback(
+		(value: unknown) => {
+			timeout.clear();
+			const validateOnChange = shouldValidateOnChange();
+			if (validateOnChange && value !== '' && validationDebounceTime) {
+				validationCommitIdRef.current += 1;
+				timeout.start(validationDebounceTime, () => {
+					commit(value);
+				});
+			} else {
+				commit(value, !validateOnChange);
+			}
+		},
+		subSlot(slot, 'change'),
+	);
+
+	const getValidationProps = useCallback(
+		(disabled: boolean, externalProps: Record<string, any> = {}) =>
+			mergeProps(
+				getDescriptionProps(externalProps),
+				state.valid === false && !state.disabled && !disabled ? { 'aria-invalid': true } : {},
+			),
+		[getDescriptionProps, state.disabled, state.valid],
+		subSlot(slot, 'getValidationProps'),
+	);
+
+	return useMemo(
+		() => ({ getValidationProps, inputRef, registerInput, commit, change }),
+		[getValidationProps, registerInput, commit, change],
+		subSlot(slot, 'return'),
+	);
+}

package/src/utils/field/useLabel.ts

@@ -0,0 +1,95 @@
+// Ported from .base-ui/packages/react/src/internals/labelable-provider/useLabel.ts. Produces
+// a native <label>'s props (`htmlFor` = the control id, `onMouseDown` to avoid text-selection /
+// focus the control) or a non-native label's click/pointer props. octane: native events.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { S, splitSlot, subSlot } from '../../internal';
+import { getTarget } from '../composite/list-utils';
+import { ownerDocument } from '../owner';
+import { useRegisteredLabelId } from '../useRegisteredLabelId';
+import { useStableCallback } from '../useStableCallback';
+import { useLabelableContext } from './LabelableContext';
+
+export interface UseLabelParameters {
+	id?: string;
+	fallbackControlId?: string | null;
+	native?: boolean;
+	setLabelId?: (nextLabelId: string | undefined) => void;
+	focusControl?: (event: any, controlId: string | null | undefined) => void;
+}
+
+function isHTMLElement(el: unknown): el is HTMLElement {
+	return el != null && el instanceof HTMLElement;
+}
+
+export function focusElementWithVisible(element: HTMLElement): void {
+	(element as any).focus({ focusVisible: true });
+}
+
+export function useLabel(...args: any[]): Record<string, any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useLabel');
+	const {
+		id: idProp,
+		fallbackControlId,
+		native = false,
+		setLabelId: setLabelIdProp,
+		focusControl: focusControlProp,
+	} = (user[0] as UseLabelParameters) ?? {};
+
+	const { controlId: contextControlId, setLabelId: setContextLabelId } = useLabelableContext();
+
+	const syncLabelId = useStableCallback(
+		(nextLabelId: string | undefined) => {
+			setContextLabelId(nextLabelId);
+			setLabelIdProp?.(nextLabelId);
+		},
+		subSlot(slot, 'sync'),
+	);
+
+	const id = useRegisteredLabelId(idProp, syncLabelId, subSlot(slot, 'id'));
+
+	const resolvedControlId = contextControlId ?? fallbackControlId;
+
+	function focusControl(event: any): void {
+		if (focusControlProp) {
+			focusControlProp(event, resolvedControlId);
+			return;
+		}
+		if (!resolvedControlId) {
+			return;
+		}
+		const controlElement = ownerDocument(event.currentTarget).getElementById(resolvedControlId);
+		if (isHTMLElement(controlElement)) {
+			focusElementWithVisible(controlElement);
+		}
+	}
+
+	function handleInteraction(event: any): void {
+		const target = getTarget(event) as HTMLElement | null;
+		if (target?.closest('button,input,select,textarea')) {
+			return;
+		}
+		if (!event.defaultPrevented && event.detail > 1) {
+			event.preventDefault();
+		}
+		if (native) {
+			return;
+		}
+		focusControl(event);
+	}
+
+	return native
+		? {
+				id,
+				htmlFor: resolvedControlId ?? undefined,
+				onMouseDown: handleInteraction,
+			}
+		: {
+				id,
+				onClick: handleInteraction,
+				onPointerDown(event: any) {
+					event.preventDefault();
+				},
+			};
+}

package/src/utils/field/useLabelableId.ts

@@ -0,0 +1,99 @@
+// Ported from .base-ui/packages/react/src/internals/labelable-provider/useLabelableId.ts.
+// Resolves a control's id and registers it with the LabelableProvider (noop when standalone —
+// `registerControlId === NOOP` — where it simply returns a generated id).
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useEffect, useLayoutEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { NOOP } from '../noop';
+import { useBaseUiId } from '../useBaseUiId';
+import { useRefWithInit } from '../useRefWithInit';
+import { useStableCallback } from '../useStableCallback';
+import { useLabelableContext } from './LabelableContext';
+
+export interface UseLabelableIdParameters {
+	id?: string;
+	implicit?: boolean;
+	controlRef?: { current: HTMLElement | null };
+}
+
+function isElement(el: unknown): el is Element {
+	return el != null && el instanceof Element;
+}
+
+export function useLabelableId(...args: any[]): string | undefined {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useLabelableId');
+	const { id, implicit = false, controlRef } = (user[0] as UseLabelableIdParameters) ?? {};
+
+	const { controlId, registerControlId } = useLabelableContext();
+
+	const defaultId = useBaseUiId(id, subSlot(slot, 'def'));
+	const controlIdForEffect = implicit ? controlId : undefined;
+
+	const controlSourceRef = useRefWithInit<symbol>(
+		() => Symbol('labelable-control'),
+		subSlot(slot, 'src'),
+	);
+	const hasRegisteredRef = useRef(false, subSlot(slot, 'has'));
+	const hadExplicitIdRef = useRef(id != null, subSlot(slot, 'had'));
+
+	const unregisterControlId = useStableCallback(
+		() => {
+			if (!hasRegisteredRef.current || registerControlId === NOOP) {
+				return;
+			}
+			hasRegisteredRef.current = false;
+			registerControlId(controlSourceRef.current, undefined);
+		},
+		subSlot(slot, 'unreg'),
+	);
+
+	useLayoutEffect(
+		() => {
+			if (registerControlId === NOOP) {
+				return undefined;
+			}
+			let nextId: string | null | undefined;
+			if (implicit) {
+				const elem = controlRef?.current;
+				if (isElement(elem) && elem.closest('label') != null) {
+					nextId = id ?? null;
+				} else {
+					nextId = controlIdForEffect ?? defaultId;
+				}
+			} else if (id != null) {
+				hadExplicitIdRef.current = true;
+				nextId = id;
+			} else if (hadExplicitIdRef.current) {
+				nextId = defaultId;
+			} else {
+				unregisterControlId();
+				return undefined;
+			}
+			if (nextId === undefined) {
+				unregisterControlId();
+				return undefined;
+			}
+			hasRegisteredRef.current = true;
+			registerControlId(controlSourceRef.current, nextId);
+			return undefined;
+		},
+		[
+			id,
+			controlRef,
+			controlIdForEffect,
+			registerControlId,
+			implicit,
+			defaultId,
+			controlSourceRef,
+			unregisterControlId,
+		],
+		subSlot(slot, 'e:reg'),
+	);
+
+	useEffect(() => unregisterControlId, [unregisterControlId], subSlot(slot, 'e:cleanup'));
+
+	return controlId ?? defaultId;
+}

package/src/utils/field/useRegisterFieldControl.ts

@@ -0,0 +1,41 @@
+// Ported from .base-ui/packages/react/src/internals/field-register-control/useRegisterFieldControl.ts.
+// Registers a control with the enclosing <Field.Root> (noop when standalone).
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useLayoutEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { useFieldRootContext } from './FieldRootContext';
+
+export function useRegisterFieldControl(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useRegisterFieldControl');
+	const controlRef = user[0];
+	const id = user[1];
+	const value = user[2];
+	const getFormValueOverride = user[3];
+	const enabled = (user[4] as boolean | undefined) ?? true;
+	const name = user[5];
+
+	const { registerFieldControl } = useFieldRootContext();
+	const sourceRef = useRef<symbol | null>(null, subSlot(slot, 'src'));
+	if (!sourceRef.current) {
+		sourceRef.current = Symbol();
+	}
+
+	useLayoutEffect(
+		() => {
+			const source = sourceRef.current;
+			if (!source || !enabled) {
+				return undefined;
+			}
+			const registration = { controlRef, getValue: getFormValueOverride, id, name, value };
+			registerFieldControl(source, registration);
+			return () => {
+				registerFieldControl(source, undefined);
+			};
+		},
+		[controlRef, enabled, getFormValueOverride, id, name, registerFieldControl, value],
+		subSlot(slot, 'e:reg'),
+	);
+}

package/src/utils/formatNumber.ts

@@ -0,0 +1,44 @@
+// Ported from .base-ui/packages/react/src/utils/formatNumber.ts. Pure `Intl.NumberFormat`
+// wrapper with a memoized formatter cache — framework-agnostic, so it ports verbatim.
+import { stringifyLocale } from './stringifyLocale';
+
+export const cache = new Map<string, Intl.NumberFormat>();
+
+export function getFormatter(
+	locale?: Intl.LocalesArgument,
+	options?: Intl.NumberFormatOptions,
+): Intl.NumberFormat {
+	const optionsString = JSON.stringify({ locale: stringifyLocale(locale), options });
+	const cachedFormatter = cache.get(optionsString);
+	if (cachedFormatter) {
+		return cachedFormatter;
+	}
+	const formatter = new Intl.NumberFormat(locale, options);
+	cache.set(optionsString, formatter);
+	return formatter;
+}
+
+export function formatNumber(
+	value: number | null,
+	locale?: Intl.LocalesArgument,
+	options?: Intl.NumberFormatOptions,
+): string {
+	if (value == null) {
+		return '';
+	}
+	return getFormatter(locale, options).format(value);
+}
+
+export function formatNumberValue(
+	value: number | null,
+	locale?: Intl.LocalesArgument,
+	format?: Intl.NumberFormatOptions,
+): string {
+	if (value == null) {
+		return '';
+	}
+	if (!format) {
+		return formatNumber(value / 100, locale, { style: 'percent' });
+	}
+	return formatNumber(value, locale, format);
+}

package/src/utils/getDefaultFormSubmitter.ts

@@ -0,0 +1,19 @@
+// Ported verbatim from .base-ui/packages/utils/src/getDefaultFormSubmitter.ts. Returns the
+// button a browser would use for implicit (Enter-key) form submission.
+export type DefaultFormSubmitter = HTMLButtonElement | HTMLInputElement;
+
+export function getDefaultFormSubmitter(form: HTMLFormElement | null): DefaultFormSubmitter | null {
+	if (!form) {
+		return null;
+	}
+	for (const candidate of Array.from(form.elements)) {
+		const tagName = candidate.tagName;
+		if (tagName === 'BUTTON' || tagName === 'INPUT') {
+			const button = candidate as HTMLButtonElement | HTMLInputElement;
+			if (button.type === 'submit') {
+				return button;
+			}
+		}
+	}
+	return null;
+}

package/src/utils/getElementRef.ts

@@ -0,0 +1,13 @@
+// octane analogue of @base-ui/utils/getReactElementRef
+// (.base-ui/packages/utils/src/getReactElementRef.ts). octane is ref-as-prop
+// (React-19 shape), so a descriptor's ref lives in `props.ref`. Returns null for
+// a non-element (function render prop, text, null).
+import { isValidElement } from 'octane';
+
+export function getElementRef(element: unknown): any {
+	if (!isValidElement(element)) {
+		return null;
+	}
+	const props = (element as any).props as { ref?: any } | undefined;
+	return props?.ref ?? null;
+}

package/src/utils/getStateAttributesProps.ts

@@ -0,0 +1,34 @@
+// Ported from .base-ui/packages/react/src/utils/getStateAttributesProps.ts.
+// Turns a component's `state` object into `data-*` attributes: `true` → `data-key=""`,
+// any other truthy value → `data-key="<value>"`, falsy → omitted. A `customMapping`
+// entry overrides the default for a given state key.
+export type StateAttributesMapping<State> = {
+	[Property in keyof State]?: (state: State[Property]) => Record<string, string> | null;
+};
+
+export function getStateAttributesProps<State extends Record<string, any>>(
+	state: State,
+	customMapping?: StateAttributesMapping<State>,
+): Record<string, string> {
+	const props: Record<string, string> = {};
+
+	for (const key in state) {
+		const value = state[key];
+
+		if (customMapping?.hasOwnProperty(key)) {
+			const customProps = customMapping[key]!(value);
+			if (customProps != null) {
+				Object.assign(props, customProps);
+			}
+			continue;
+		}
+
+		if (value === true) {
+			props[`data-${key.toLowerCase()}`] = '';
+		} else if (value) {
+			props[`data-${key.toLowerCase()}`] = value.toString();
+		}
+	}
+
+	return props;
+}

package/src/utils/matchesFocusVisible.ts

@@ -0,0 +1,16 @@
+// Ported from .base-ui/packages/react/src/floating-ui-react/utils/element.ts (matchesFocusVisible).
+// jsdom doesn't match `:focus-visible` reliably (it stays matched while `:focus` is set), so —
+// exactly as Base UI does — return `true` under jsdom to avoid the focus-restore dance. Both the
+// octane and React trees run in the SAME jsdom in the differential rig, so this must agree.
+const isJSDOM = typeof navigator !== 'undefined' && /jsdom/i.test(navigator.userAgent);
+
+export function matchesFocusVisible(element: Element | null): boolean {
+	if (!element || isJSDOM) {
+		return true;
+	}
+	try {
+		return element.matches(':focus-visible');
+	} catch {
+		return true;
+	}
+}

package/src/utils/mergeObjects.ts

@@ -0,0 +1,18 @@
+// Ported from @base-ui/utils/mergeObjects
+// (.base-ui/packages/utils/src/mergeObjects.ts). Shallow object merge that
+// avoids allocating when only one side is present.
+export function mergeObjects<A extends object | undefined, B extends object | undefined>(
+	a: A,
+	b: B,
+): A | B | (A & B) | undefined {
+	if (a && !b) {
+		return a;
+	}
+	if (!a && b) {
+		return b;
+	}
+	if (a || b) {
+		return { ...a, ...b } as A & B;
+	}
+	return undefined;
+}