@octanejs/base-ui 0.1.1

package/src/utils/field/LabelableProvider.ts

@@ -0,0 +1,108 @@
+// Ported from .base-ui/packages/react/src/internals/labelable-provider/LabelableProvider.tsx.
+// Provides the REAL LabelableContext (control-id registry, labelId, message ids for
+// aria-describedby) that Field parts read — overriding the inert default context.
+import { createElement, useCallback, useContext, useMemo, useState } from 'octane';
+
+import { S, subSlot } from '../../internal';
+import { useBaseUiId } from '../useBaseUiId';
+import { useRefWithInit } from '../useRefWithInit';
+import { useStableCallback } from '../useStableCallback';
+import { LabelableContext, type LabelableContextValue } from './LabelableContext';
+
+export interface LabelableProviderProps {
+	controlId?: string | null;
+	labelId?: string;
+	children?: any;
+}
+
+export function LabelableProvider(props: LabelableProviderProps): any {
+	const slot = S('LabelableProvider');
+	const defaultId = useBaseUiId(undefined, subSlot(slot, 'default'));
+	const initialControlId = props.controlId === undefined ? defaultId : props.controlId;
+
+	const [controlId, setControlIdState] = useState<string | null | undefined>(
+		initialControlId,
+		subSlot(slot, 'controlId'),
+	);
+	const [labelId, setLabelId] = useState<string | undefined>(
+		props.labelId,
+		subSlot(slot, 'labelId'),
+	);
+	const [messageIds, setMessageIds] = useState<string[]>([], subSlot(slot, 'messageIds'));
+
+	const registrationsRef = useRefWithInit<Map<symbol, string | null>>(
+		() => new Map(),
+		subSlot(slot, 'reg'),
+	);
+
+	const { messageIds: parentMessageIds } = useContext(LabelableContext);
+
+	const registerControlId = useStableCallback(
+		(source: symbol, nextId: string | null | undefined) => {
+			const registrations = registrationsRef.current;
+			if (nextId === undefined) {
+				registrations.delete(source);
+				return;
+			}
+			registrations.set(source, nextId);
+			setControlIdState((prev: string | null | undefined) => {
+				if (registrations.size === 0) {
+					return undefined;
+				}
+				let nextControlId: string | null | undefined;
+				for (const id of registrations.values()) {
+					if (prev !== undefined && id === prev) {
+						return prev;
+					}
+					if (nextControlId === undefined) {
+						nextControlId = id;
+					}
+				}
+				return nextControlId;
+			});
+		},
+		subSlot(slot, 'registerControlId'),
+	);
+
+	const getDescriptionProps = useCallback(
+		(externalProps: Record<string, any>) => {
+			const ids = externalProps['aria-describedby']
+				? externalProps['aria-describedby'].split(' ')
+				: [];
+			ids.push(...parentMessageIds, ...messageIds);
+			return {
+				...externalProps,
+				'aria-describedby': Array.from(new Set(ids)).join(' ') || undefined,
+			};
+		},
+		[parentMessageIds, messageIds],
+		subSlot(slot, 'getDesc'),
+	);
+
+	const contextValue: LabelableContextValue = useMemo(
+		() => ({
+			controlId,
+			registerControlId,
+			labelId,
+			setLabelId,
+			messageIds,
+			setMessageIds,
+			getDescriptionProps,
+		}),
+		[
+			controlId,
+			registerControlId,
+			labelId,
+			setLabelId,
+			messageIds,
+			setMessageIds,
+			getDescriptionProps,
+		],
+		subSlot(slot, 'ctx'),
+	);
+
+	return createElement(LabelableContext.Provider, {
+		value: contextValue,
+		children: props.children,
+	});
+}

package/src/utils/field/constants.ts

@@ -0,0 +1,80 @@
+// Ported from .base-ui/packages/react/src/internals/field-constants/constants.ts and the
+// FieldRootState/FieldValidityData types (field/root/FieldRoot). The default field state +
+// validity, plus the shared `fieldValidityMapping` (valid → data-valid / data-invalid; null →
+// no attribute) reused by every field-aware control's stateAttributesMapping.
+import type { StateAttributesMapping } from '../getStateAttributesProps';
+
+export type FormValidationMode = 'onSubmit' | 'onBlur' | 'onChange';
+
+export interface FieldRootState {
+	disabled: boolean;
+	touched: boolean;
+	dirty: boolean;
+	filled: boolean;
+	focused: boolean;
+	valid: boolean | null;
+}
+
+export interface FieldValidityState {
+	badInput: boolean;
+	customError: boolean;
+	patternMismatch: boolean;
+	rangeOverflow: boolean;
+	rangeUnderflow: boolean;
+	stepMismatch: boolean;
+	tooLong: boolean;
+	tooShort: boolean;
+	typeMismatch: boolean;
+	valid: boolean | null;
+	valueMissing: boolean;
+}
+
+export interface FieldValidityData {
+	state: FieldValidityState;
+	errors: string[];
+	error: string;
+	value: unknown;
+	initialValue: unknown;
+}
+
+export const DEFAULT_VALIDITY_STATE: FieldValidityState = {
+	badInput: false,
+	customError: false,
+	patternMismatch: false,
+	rangeOverflow: false,
+	rangeUnderflow: false,
+	stepMismatch: false,
+	tooLong: false,
+	tooShort: false,
+	typeMismatch: false,
+	valid: null,
+	valueMissing: false,
+};
+
+export const DEFAULT_FIELD_STATE_ATTRIBUTES: Pick<
+	FieldRootState,
+	'valid' | 'touched' | 'dirty' | 'filled' | 'focused'
+> = {
+	valid: null,
+	touched: false,
+	dirty: false,
+	filled: false,
+	focused: false,
+};
+
+export const DEFAULT_FIELD_ROOT_STATE: FieldRootState = {
+	disabled: false,
+	...DEFAULT_FIELD_STATE_ATTRIBUTES,
+};
+
+export const fieldValidityMapping: StateAttributesMapping<{ valid: boolean | null }> = {
+	valid(value: boolean | null): Record<string, string> | null {
+		if (value === null) {
+			return null;
+		}
+		if (value) {
+			return { 'data-valid': '' };
+		}
+		return { 'data-invalid': '' };
+	},
+};

package/src/utils/field/getCombinedFieldValidityData.ts

@@ -0,0 +1,16 @@
+// Ported from .base-ui/packages/react/src/field/utils/getCombinedFieldValidityData.ts.
+// Folds the external `invalid` flag into the field's stateful validity.
+import type { FieldValidityData } from './constants';
+
+export function getCombinedFieldValidityData(
+	validityData: FieldValidityData,
+	invalid: boolean | undefined,
+): FieldValidityData {
+	return {
+		...validityData,
+		state: {
+			...validityData.state,
+			valid: !invalid && validityData.state.valid,
+		},
+	};
+}

package/src/utils/field/useAriaLabelledBy.ts

@@ -0,0 +1,86 @@
+// Ported from .base-ui/packages/react/src/internals/labelable-provider/useAriaLabelledBy.ts.
+// Resolves a control's `aria-labelledby`: an explicit value, else the Field label id, else a
+// fallback discovered from a wrapping/sibling native <label>. The effect runs after every
+// commit so DOM label association changes are reflected.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useLayoutEffect, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { useBaseUiId } from '../useBaseUiId';
+
+type LabelSource = HTMLElement & { labels?: NodeListOf<HTMLLabelElement> | null };
+
+export function useAriaLabelledBy(...args: any[]): string | undefined {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useAriaLabelledBy');
+	const explicitAriaLabelledBy = user[0] as string | undefined;
+	const labelId = user[1] as string | undefined;
+	const labelSourceRef = user[2] as { current: LabelSource | null };
+	const enableFallback = (user[3] as boolean | undefined) ?? true;
+	const labelSourceId = user[4] as string | undefined;
+
+	const [fallbackAriaLabelledBy, setFallbackAriaLabelledBy] = useState<string | undefined>(
+		undefined,
+		subSlot(slot, 'fb'),
+	);
+
+	const generatedLabelId = useBaseUiId(
+		labelSourceId ? `${labelSourceId}-label` : undefined,
+		subSlot(slot, 'gen'),
+	);
+	const ariaLabelledBy = explicitAriaLabelledBy ?? labelId ?? fallbackAriaLabelledBy;
+
+	// No deps → runs after every commit (DOM label association can change without prop/state
+	// deps changing).
+	useLayoutEffect(
+		() => {
+			const nextAriaLabelledBy =
+				explicitAriaLabelledBy || labelId || !enableFallback
+					? undefined
+					: getAriaLabelledBy(labelSourceRef.current, generatedLabelId);
+			if (fallbackAriaLabelledBy !== nextAriaLabelledBy) {
+				setFallbackAriaLabelledBy(nextAriaLabelledBy);
+			}
+		},
+		undefined,
+		subSlot(slot, 'e:fallback'),
+	);
+
+	return ariaLabelledBy;
+}
+
+function getAriaLabelledBy(
+	labelSource: LabelSource | null | undefined,
+	generatedLabelId: string | undefined,
+): string | undefined {
+	const label = findAssociatedLabel(labelSource);
+	if (!label) {
+		return undefined;
+	}
+	if (!label.id && generatedLabelId) {
+		label.id = generatedLabelId;
+	}
+	return label.id || undefined;
+}
+
+function findAssociatedLabel(
+	labelSource: LabelSource | null | undefined,
+): HTMLLabelElement | undefined {
+	if (!labelSource) {
+		return undefined;
+	}
+	const parent = labelSource.parentElement;
+	if (parent && parent.tagName === 'LABEL') {
+		return parent as HTMLLabelElement;
+	}
+	const controlId = labelSource.id;
+	if (controlId) {
+		const nextSibling = labelSource.nextElementSibling as HTMLLabelElement | null;
+		if (nextSibling && nextSibling.htmlFor === controlId) {
+			return nextSibling;
+		}
+	}
+	const labels = labelSource.labels;
+	return labels ? (labels[0] as HTMLLabelElement | undefined) : undefined;
+}

package/src/utils/field/useFieldControlRegistration.ts

@@ -0,0 +1,179 @@
+// Ported from .base-ui/packages/react/src/internals/field-register-control/useFieldControlRegistration.ts.
+// Registers the field's control with the enclosing <Form> (so submit-time validation + focus
+// work) and exposes an imperative `validate`.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useLayoutEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { getCombinedFieldValidityData } from './getCombinedFieldValidityData';
+import { useFormContext } from './FormContext';
+import { useStableCallback } from '../useStableCallback';
+import type { FieldValidityData } from './constants';
+
+export interface FieldControlRegistration {
+	controlRef: { current: any };
+	id: string | undefined;
+	name?: string;
+	getValue?: () => unknown;
+	value: unknown;
+}
+
+export interface UseFieldControlRegistrationParameters {
+	commit: (value: unknown) => void;
+	invalid: boolean;
+	markedDirtyRef: { current: boolean };
+	name: string | undefined;
+	setRegisteredFieldName: (name: string | undefined) => void;
+	setRegisteredFieldId: (id: string | undefined) => void;
+	setValidityData: (
+		next: FieldValidityData | ((prev: FieldValidityData) => FieldValidityData),
+	) => void;
+	validityData: FieldValidityData;
+}
+
+export function useFieldControlRegistration(...args: any[]): readonly [() => void, any] {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useFieldControlRegistration');
+	const {
+		commit,
+		invalid,
+		markedDirtyRef,
+		name,
+		setRegisteredFieldName,
+		setRegisteredFieldId,
+		setValidityData,
+		validityData,
+	} = user[0] as UseFieldControlRegistrationParameters;
+
+	const { formRef } = useFormContext();
+
+	const activeFieldControlSourceRef = useRef<symbol | null>(null, subSlot(slot, 'active'));
+	const registrationRef = useRef<FieldControlRegistration | null>(null, subSlot(slot, 'reg'));
+	const fallbackControlRef = useRef<any>(null, subSlot(slot, 'fallback'));
+
+	const getValueForForm = useStableCallback(
+		() => {
+			const registration = registrationRef.current;
+			if (!registration) {
+				return undefined;
+			}
+			if (registration.getValue) {
+				return registration.getValue();
+			}
+			return registration.value;
+		},
+		subSlot(slot, 'getValue'),
+	);
+
+	function getRegistrationValue(registration: FieldControlRegistration): unknown {
+		return registration.value === undefined ? getValueForForm() : registration.value;
+	}
+
+	const validate = useStableCallback(
+		() => {
+			const registration = registrationRef.current;
+			markedDirtyRef.current = true;
+			if (!registration) {
+				commit(validityData.value);
+				return;
+			}
+			commit(getRegistrationValue(registration));
+		},
+		subSlot(slot, 'validate'),
+	);
+
+	function refreshRegistration(): void {
+		const registration = registrationRef.current;
+		if (!registration || !registration.id) {
+			return;
+		}
+		formRef.current.fields.set(registration.id, {
+			getValue: getValueForForm,
+			name: name ?? registration.name,
+			controlRef: registration.controlRef ?? fallbackControlRef,
+			validityData: getCombinedFieldValidityData(validityData, invalid),
+			validate,
+		});
+	}
+
+	function deleteRegistration(id = registrationRef.current?.id): void {
+		if (id) {
+			formRef.current.fields.delete(id);
+		}
+	}
+
+	function syncInitialValue(): void {
+		const registration = registrationRef.current;
+		if (!registration) {
+			return;
+		}
+		const initialValue = getRegistrationValue(registration);
+		if (validityData.initialValue === null && initialValue !== null) {
+			setValidityData((prev) => ({ ...prev, initialValue }));
+		}
+	}
+
+	useLayoutEffect(
+		() => {
+			const registration = registrationRef.current;
+			if (!registration || !registration.id) {
+				return;
+			}
+			setRegisteredFieldName(name ? undefined : registration.name);
+			formRef.current.fields.set(registration.id, {
+				getValue: getValueForForm,
+				name: name ?? registration.name,
+				controlRef: registration.controlRef ?? fallbackControlRef,
+				validityData: getCombinedFieldValidityData(validityData, invalid),
+				validate,
+			});
+		},
+		[formRef, getValueForForm, invalid, name, setRegisteredFieldName, validate, validityData],
+		subSlot(slot, 'e:register'),
+	);
+
+	useLayoutEffect(
+		() => {
+			const fields = formRef.current.fields;
+			return () => {
+				const id = registrationRef.current?.id;
+				if (id) {
+					fields.delete(id);
+				}
+			};
+		},
+		[formRef],
+		subSlot(slot, 'e:cleanup'),
+	);
+
+	const register = useStableCallback(
+		(source: symbol, registration: FieldControlRegistration | undefined) => {
+			if (!registration) {
+				if (activeFieldControlSourceRef.current === source) {
+					activeFieldControlSourceRef.current = null;
+					deleteRegistration();
+					registrationRef.current = null;
+					setRegisteredFieldName(undefined);
+					setRegisteredFieldId(undefined);
+				}
+				return;
+			}
+			const previousId = registrationRef.current?.id;
+			activeFieldControlSourceRef.current = source;
+			registrationRef.current = registration;
+			if (!name) {
+				setRegisteredFieldName(registration.name);
+			}
+			setRegisteredFieldId(registration.id);
+			if (previousId && previousId !== registration.id) {
+				deleteRegistration(previousId);
+			}
+			syncInitialValue();
+			refreshRegistration();
+		},
+		subSlot(slot, 'register'),
+	);
+
+	return [validate, register] as const;
+}