@octanejs/base-ui 0.1.50 → 0.1.51

package/src/internals/composite/root/useCompositeRoot.ts

@@ -0,0 +1,378 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { isElementDisabled } from '@octanejs/base-ui-utils/isElementDisabled';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { useMergedRefs } from '@octanejs/base-ui-utils/useMergedRefs';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { EMPTY_ARRAY } from '@octanejs/base-ui-utils/empty';
+import type { TextDirection } from '../../direction-context/DirectionContext.tsrx';
+import {
+	COMPOSITE_KEYS,
+	ARROW_DOWN,
+	ARROW_LEFT,
+	ARROW_RIGHT,
+	ARROW_UP,
+	END,
+	HOME,
+	MODIFIER_KEYS,
+	findNonDisabledListIndex,
+	getMaxListIndex,
+	getMinListIndex,
+	isListIndexDisabled,
+	isIndexOutOfListBounds,
+	isNativeInput,
+	scrollIntoViewIfNeeded,
+	type ModifierKey,
+} from '../composite';
+import { ACTIVE_COMPOSITE_ITEM } from '../constants';
+import type { CompositeMetadata } from '../list/CompositeList.tsrx';
+import type { HTMLProps } from '../../types';
+import { getTarget } from '../../../floating-ui-react/utils';
+import type { CompositeGridNavigator } from './gridNavigation';
+
+export interface UseCompositeRootParameters {
+	orientation?: 'horizontal' | 'vertical' | 'both' | undefined;
+	grid?: CompositeGridNavigator | undefined;
+	loopFocus?: boolean | undefined;
+	onLoop?:
+		| ((
+				event: React.KeyboardEvent,
+				prevIndex: number,
+				nextIndex: number,
+				elementsRef: React.RefObject<Array<HTMLElement | null>>,
+		  ) => number)
+		| undefined;
+	highlightedIndex?: number | undefined;
+	onHighlightedIndexChange?: ((index: number) => void) | undefined;
+	direction: TextDirection;
+	rootRef?: React.Ref<Element> | undefined;
+	/**
+	 * When `true`, pressing the Home key moves focus to the first item,
+	 * and pressing the End key moves focus to the last item.
+	 * @default false
+	 */
+	enableHomeAndEndKeys?: boolean | undefined;
+	/**
+	 * When `true`, keypress events on Composite's navigation keys
+	 * be stopped with event.stopPropagation().
+	 * @default false
+	 */
+	stopEventPropagation?: boolean | undefined;
+	/**
+	 * Array of item indices to be considered disabled.
+	 * Used for composite items that are focusable when disabled.
+	 */
+	disabledIndices?: number[] | undefined;
+	/**
+	 * Array of [modifier key values](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values#modifier_keys) that should allow normal keyboard actions
+	 * when pressed. By default, all modifier keys prevent normal actions.
+	 * @default []
+	 */
+	modifierKeys?: ModifierKey[] | undefined;
+}
+
+export function useCompositeRoot(params: UseCompositeRootParameters) {
+	const {
+		loopFocus = true,
+		orientation = 'both',
+		grid,
+		onLoop,
+		direction,
+		highlightedIndex: externalHighlightedIndex,
+		onHighlightedIndexChange: externalSetHighlightedIndex,
+		rootRef: externalRef,
+		enableHomeAndEndKeys = false,
+		stopEventPropagation,
+		disabledIndices,
+		modifierKeys = EMPTY_ARRAY,
+	} = params;
+
+	const [internalHighlightedIndex, internalSetHighlightedIndex] = React.useState(0);
+	const isGrid = grid != null;
+
+	const rootRef = React.useRef<HTMLElement | null>(null);
+	const mergedRef = useMergedRefs(rootRef, externalRef);
+
+	const elementsRef = React.useRef<Array<HTMLElement | null>>([]);
+	const hasSetDefaultIndexRef = React.useRef(false);
+	const highlightedElementRef = React.useRef<HTMLElement | null>(null);
+
+	const highlightedIndex = externalHighlightedIndex ?? internalHighlightedIndex;
+	const onHighlightedIndexChange = useStableCallback((index, shouldScrollIntoView = false) => {
+		highlightedElementRef.current = elementsRef.current[index] ?? null;
+		(externalSetHighlightedIndex ?? internalSetHighlightedIndex)(index);
+		if (shouldScrollIntoView) {
+			const newActiveItem = elementsRef.current[index];
+			scrollIntoViewIfNeeded(rootRef.current, newActiveItem, direction, orientation);
+		}
+	});
+
+	const onMapChange = useStableCallback((map: Map<Element, CompositeMetadata<any>>) => {
+		if (map.size === 0) {
+			return;
+		}
+
+		if (hasSetDefaultIndexRef.current) {
+			const elements = elementsRef.current;
+			// Items added or removed around the highlighted one shift its index, so the tab stop would
+			// otherwise move to a different item and navigation would resume from the wrong position.
+			const nextIndex = elements.indexOf(highlightedElementRef.current);
+
+			if (nextIndex === -1) {
+				// A replacement at the same index can keep the tab stop. Otherwise move it to an
+				// eligible item so a missing, hidden, or disabled replacement does not take the
+				// composite out of the tab order.
+				const replacement = elements[highlightedIndex];
+				if (!replacement || isListIndexDisabled(elements, highlightedIndex, disabledIndices)) {
+					onHighlightedIndexChange(getFallbackIndex(elements, disabledIndices));
+				} else {
+					highlightedElementRef.current = replacement;
+				}
+			} else if (nextIndex !== highlightedIndex) {
+				onHighlightedIndexChange(nextIndex);
+			}
+			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;
+		// Set the default highlighted index of an arbitrary composite item. The map value carries
+		// the item's own index, which is not its position among the keys once a list mixes explicit
+		// and automatic indexes and leaves gaps.
+		const activeIndex = activeItem ? (map.get(activeItem)?.index ?? -1) : -1;
+
+		if (activeIndex !== -1) {
+			onHighlightedIndexChange(activeIndex);
+		} else if (isListIndexDisabled(sortedElements, highlightedIndex, disabledIndices)) {
+			// The default highlighted item is disabled, so it should not hold the single
+			// roving tab stop: a natively disabled element is removed from the tab order,
+			// and an aria-disabled one should not be the entry point. Move the tab stop
+			// to the first enabled item. If every item is disabled, keep the current
+			// highlighted index.
+			const firstEnabledIndex = findNonDisabledListIndex(sortedElements, { disabledIndices });
+			if (!isIndexOutOfListBounds(sortedElements, firstEnabledIndex)) {
+				onHighlightedIndexChange(firstEnabledIndex);
+			}
+		}
+
+		scrollIntoViewIfNeeded(rootRef.current, activeItem, direction, orientation);
+	});
+
+	useIsoLayoutEffect(() => {
+		// `disabledIndices` can resolve a render after the initial map population
+		// (e.g. Toolbar derives it from item metadata through a state update), so the
+		// default tab stop at index 0 may now point at a disabled item, leaving the
+		// composite without a reachable tab stop. Re-validate and move it to the first
+		// enabled item. Gated on `disabledIndices` being provided so composites that
+		// rely on the DOM disabled fallback keep their existing behavior.
+		if (
+			disabledIndices == null ||
+			externalHighlightedIndex != null ||
+			!hasSetDefaultIndexRef.current
+		) {
+			return;
+		}
+		const elements = elementsRef.current;
+		if (isListIndexDisabled(elements, highlightedIndex, disabledIndices)) {
+			const firstEnabledIndex = findNonDisabledListIndex(elements, { disabledIndices });
+			if (!isIndexOutOfListBounds(elements, firstEnabledIndex)) {
+				onHighlightedIndexChange(firstEnabledIndex);
+			}
+		}
+	}, [
+		disabledIndices,
+		externalHighlightedIndex,
+		highlightedIndex,
+		elementsRef,
+		onHighlightedIndexChange,
+	]);
+
+	const wrappedOnLoop = useStableCallback(
+		(event: React.KeyboardEvent, prevIndex: number, nextIndex: number) => {
+			if (!onLoop) {
+				return nextIndex;
+			}
+			return onLoop(event, prevIndex, nextIndex, elementsRef);
+		},
+	);
+
+	// Stable so that `relayKeyboardEvent` does not invalidate identity-sensitive
+	// consumers (the `CompositeRootContext` value and trigger data forwarding).
+	const onKeyDown = useStableCallback((event: React.KeyboardEvent) => {
+		const isHomeOrEnd = event.key === HOME || event.key === END;
+		if (!COMPOSITE_KEYS.has(event.key) || (!enableHomeAndEndKeys && isHomeOrEnd)) {
+			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 horizontalBackwardKey = isRtl ? ARROW_RIGHT : ARROW_LEFT;
+		const forwardKey = orientation === 'vertical' ? ARROW_DOWN : horizontalForwardKey;
+		const backwardKey = orientation === 'vertical' ? ARROW_UP : horizontalBackwardKey;
+
+		const target = getTarget(event);
+		if (target != null && isNativeInput(target) && !isElementDisabled(target)) {
+			const selectionStart = target.selectionStart;
+			const selectionEnd = target.selectionEnd;
+			const textContent = target.value;
+			// return to native textbox behavior when
+			// 1 - Shift is held to make a text selection, or if there already is a text selection
+			if (selectionStart == null || event.shiftKey || selectionStart !== selectionEnd) {
+				return;
+			}
+			// 2 - arrow-ing forward and not in the last position of the text
+			if (event.key !== backwardKey && selectionStart < textContent.length) {
+				return;
+			}
+			// 3 -arrow-ing backward and not in the first position of the text
+			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: wrappedOnLoop,
+				orientation,
+				rtl: isRtl,
+			});
+		}
+
+		const isForwardKey =
+			(orientation !== 'vertical' && event.key === horizontalForwardKey) ||
+			(orientation !== 'horizontal' && event.key === ARROW_DOWN);
+		const isBackwardKey =
+			(orientation !== 'vertical' && event.key === horizontalBackwardKey) ||
+			(orientation !== 'horizontal' && event.key === ARROW_UP);
+
+		if (enableHomeAndEndKeys) {
+			if (event.key === HOME) {
+				nextIndex = minIndex;
+			} else if (event.key === END) {
+				nextIndex = maxIndex;
+			}
+		}
+
+		if (nextIndex === highlightedIndex && (isForwardKey || isBackwardKey)) {
+			if (loopFocus && nextIndex === maxIndex && isForwardKey) {
+				nextIndex = minIndex;
+				if (onLoop) {
+					nextIndex = onLoop(event, highlightedIndex, nextIndex, elementsRef);
+				}
+			} else if (loopFocus && nextIndex === minIndex && isBackwardKey) {
+				nextIndex = maxIndex;
+				if (onLoop) {
+					nextIndex = onLoop(event, highlightedIndex, nextIndex, elementsRef);
+				}
+			} else {
+				nextIndex = findNonDisabledListIndex(elementsRef.current, {
+					startingIndex: nextIndex,
+					decrement: isBackwardKey,
+					disabledIndices,
+				});
+			}
+		}
+
+		if (nextIndex !== highlightedIndex && !isIndexOutOfListBounds(elementsRef.current, nextIndex)) {
+			if (stopEventPropagation) {
+				event.stopPropagation();
+			}
+
+			if (isGrid || isHomeOrEnd || isForwardKey || isBackwardKey) {
+				event.preventDefault();
+			}
+			onHighlightedIndexChange(nextIndex, true);
+
+			// Wait for FocusManager `returnFocus` to execute.
+			queueMicrotask(() => {
+				elementsRef.current[nextIndex]?.focus();
+			});
+		}
+	});
+
+	const props: HTMLProps = {
+		ref: mergedRef,
+		onFocus(event) {
+			const element = rootRef.current;
+			const target = getTarget(event);
+			if (!element || target == null || !isNativeInput(target)) {
+				return;
+			}
+			target.setSelectionRange(0, target.value.length);
+		},
+		onKeyDown,
+	};
+
+	return {
+		props,
+		highlightedIndex,
+		onHighlightedIndexChange,
+		elementsRef,
+		onMapChange,
+		relayKeyboardEvent: onKeyDown,
+	};
+}
+
+// Resolves the item that should hold the tab stop: the active item when it can take focus,
+// otherwise the first item that can. Falls back to index 0 so an all-disabled composite keeps the
+// index in range and regains a tab stop as soon as one of its items becomes focusable.
+function getFallbackIndex(elements: Array<HTMLElement | null>, disabledIndices?: number[]) {
+	let fallbackIndex = -1;
+
+	for (let index = 0; index < elements.length; index += 1) {
+		const element = elements[index];
+
+		if (!element || isListIndexDisabled(elements, index, disabledIndices)) {
+			continue;
+		}
+
+		if (element.hasAttribute(ACTIVE_COMPOSITE_ITEM)) {
+			return index;
+		}
+
+		if (fallbackIndex === -1) {
+			fallbackIndex = index;
+		}
+	}
+
+	return Math.max(fallbackIndex, 0);
+}
+
+function isModifierKeySet(event: React.KeyboardEvent, ignoredModifierKeys: ModifierKey[]) {
+	for (const key of MODIFIER_KEYS) {
+		if (ignoredModifierKeys.includes(key)) {
+			continue;
+		}
+		if (event.getModifierState(key)) {
+			return true;
+		}
+	}
+	return false;
+}

package/src/internals/constants.ts

@@ -0,0 +1,41 @@
+import type * as React from 'octane';
+
+export const TYPEAHEAD_RESET_MS = 500;
+export const PATIENT_CLICK_THRESHOLD = 500;
+export const DISABLED_TRANSITIONS_STYLE = { style: { transition: 'none' } };
+
+export const CLICK_TRIGGER_IDENTIFIER = 'data-base-ui-click-trigger';
+export const BASE_UI_SWIPE_IGNORE_ATTRIBUTE = 'data-base-ui-swipe-ignore';
+export const LEGACY_SWIPE_IGNORE_ATTRIBUTE = 'data-swipe-ignore';
+
+export const BASE_UI_SWIPE_IGNORE_SELECTOR = `[${BASE_UI_SWIPE_IGNORE_ATTRIBUTE}]`;
+export const LEGACY_SWIPE_IGNORE_SELECTOR = `[${LEGACY_SWIPE_IGNORE_ATTRIBUTE}]`;
+
+/**
+ * Used for dropdowns that usually strictly prefer top/bottom placements and
+ * use `var(--available-height)` to limit their height.
+ */
+export const DROPDOWN_COLLISION_AVOIDANCE = {
+	fallbackAxisSide: 'none',
+} as const;
+
+/**
+ * Used by regular popups that usually aren't scrollable and are allowed to
+ * freely flip to any axis of placement.
+ */
+export const POPUP_COLLISION_AVOIDANCE = {
+	fallbackAxisSide: 'end',
+} as const;
+
+/**
+ * Special visually hidden styles for the aria-owns owner element to ensure owned element
+ * accessibility in iOS/Safari/VoiceControl.
+ * The owner element is an empty span, so most of the common visually hidden styles are not needed.
+ * @see https://github.com/floating-ui/floating-ui/issues/3403
+ */
+export const ownerVisuallyHidden: React.CSSProperties = {
+	clipPath: 'inset(50%)',
+	position: 'fixed',
+	top: 0,
+	left: 0,
+};

package/src/internals/createBaseUIEventDetails.ts

@@ -0,0 +1,166 @@
+import { EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import { REASONS } from './reasons';
+
+interface ReasonToEventMap {
+	[REASONS.none]: Event;
+
+	[REASONS.triggerPress]: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent;
+	[REASONS.triggerHover]: MouseEvent;
+	[REASONS.triggerFocus]: FocusEvent;
+
+	[REASONS.outsidePress]: MouseEvent | PointerEvent | TouchEvent;
+	[REASONS.itemPress]: MouseEvent | KeyboardEvent | PointerEvent;
+	[REASONS.closePress]: MouseEvent | KeyboardEvent | PointerEvent;
+	[REASONS.linkPress]: MouseEvent | PointerEvent;
+	[REASONS.clearPress]: PointerEvent | MouseEvent | KeyboardEvent;
+	[REASONS.chipRemovePress]: PointerEvent | MouseEvent | KeyboardEvent;
+	[REASONS.trackPress]: PointerEvent | MouseEvent | TouchEvent;
+	[REASONS.incrementPress]: PointerEvent | MouseEvent | TouchEvent;
+	[REASONS.decrementPress]: PointerEvent | MouseEvent | TouchEvent;
+
+	[REASONS.inputChange]: InputEvent | Event;
+	[REASONS.inputClear]: InputEvent | FocusEvent | Event;
+	[REASONS.inputBlur]: FocusEvent;
+	[REASONS.inputPaste]: ClipboardEvent;
+	[REASONS.inputPress]: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent;
+
+	[REASONS.focusOut]: FocusEvent | KeyboardEvent;
+	[REASONS.escapeKey]: KeyboardEvent;
+	[REASONS.closeWatcher]: Event;
+	[REASONS.listNavigation]: KeyboardEvent;
+	[REASONS.keyboard]: KeyboardEvent;
+
+	[REASONS.pointer]: PointerEvent;
+	[REASONS.drag]: PointerEvent | TouchEvent;
+	[REASONS.swipe]: PointerEvent | TouchEvent;
+	[REASONS.wheel]: WheelEvent;
+	[REASONS.scrub]: PointerEvent;
+
+	[REASONS.cancelOpen]: MouseEvent;
+	[REASONS.siblingOpen]: Event;
+	[REASONS.disabled]: Event;
+	[REASONS.missing]: Event;
+	[REASONS.initial]: Event;
+	[REASONS.imperativeAction]: Event;
+
+	[REASONS.windowResize]: UIEvent;
+}
+
+/**
+ * Maps a change `reason` string to the corresponding native event type.
+ */
+export type ReasonToEvent<Reason extends string> = Reason extends keyof ReasonToEventMap
+	? ReasonToEventMap[Reason]
+	: Event;
+
+type BaseUIChangeEventDetail<Reason extends string, CustomProperties extends object> = {
+	/**
+	 * The reason for the event.
+	 */
+	reason: Reason;
+	/**
+	 * The native event associated with the custom event.
+	 */
+	event: ReasonToEvent<Reason>;
+	/**
+	 * Cancels Base UI from handling the event.
+	 */
+	cancel: () => void;
+	/**
+	 * Allows the event to propagate in cases where Base UI will stop the propagation.
+	 */
+	allowPropagation: () => void;
+	/**
+	 * Indicates whether the event has been canceled.
+	 */
+	isCanceled: boolean;
+	/**
+	 * Indicates whether the event is allowed to propagate.
+	 */
+	isPropagationAllowed: boolean;
+	/**
+	 * The element that triggered the event, if applicable.
+	 */
+	trigger: Element | undefined;
+} & CustomProperties;
+
+/**
+ * Details of custom change events emitted by Base UI components.
+ */
+export type BaseUIChangeEventDetails<
+	Reason extends string,
+	CustomProperties extends object = {},
+> = Reason extends string ? BaseUIChangeEventDetail<Reason, CustomProperties> & {} : never;
+
+/**
+ * Details of custom generic events emitted by Base UI components.
+ */
+type BaseUIGenericEventDetail<Reason extends string, CustomProperties extends object> = {
+	/**
+	 * The reason for the event.
+	 */
+	reason: Reason;
+	/**
+	 * The native event associated with the custom event.
+	 */
+	event: ReasonToEvent<Reason>;
+} & CustomProperties;
+
+export type BaseUIGenericEventDetails<
+	Reason extends string,
+	CustomProperties extends object = {},
+> = Reason extends string ? BaseUIGenericEventDetail<Reason, CustomProperties> & {} : never;
+
+/**
+ * Creates a Base UI event details object with the given reason and utilities
+ * for preventing Base UI's internal event handling.
+ */
+export function createChangeEventDetails<
+	Reason extends string,
+	CustomProperties extends object = {},
+>(
+	reason: Reason,
+	event?: ReasonToEvent<Reason>,
+	trigger?: Element,
+	customProperties?: CustomProperties,
+): BaseUIChangeEventDetails<Reason, CustomProperties> {
+	let canceled = false;
+	let allowPropagation = false;
+	const custom = customProperties ?? (EMPTY_OBJECT as CustomProperties);
+	const details: BaseUIChangeEventDetail<Reason, CustomProperties> = {
+		reason,
+		event: (event ?? new Event('base-ui')) as ReasonToEvent<Reason>,
+		cancel() {
+			canceled = true;
+		},
+		allowPropagation() {
+			allowPropagation = true;
+		},
+		get isCanceled() {
+			return canceled;
+		},
+		get isPropagationAllowed() {
+			return allowPropagation;
+		},
+		trigger,
+		...custom,
+	};
+	return details as BaseUIChangeEventDetails<Reason, CustomProperties>;
+}
+
+export function createGenericEventDetails<
+	Reason extends keyof ReasonToEventMap,
+	CustomProperties extends object = {},
+>(
+	reason: Reason,
+	event?: ReasonToEvent<Reason>,
+	customProperties?: CustomProperties,
+): BaseUIGenericEventDetails<Reason, CustomProperties> {
+	const custom = customProperties ?? (EMPTY_OBJECT as CustomProperties);
+	const details: BaseUIGenericEventDetail<Reason, CustomProperties> = {
+		reason,
+		event: (event ?? new Event('base-ui')) as ReasonToEvent<Reason>,
+		...custom,
+	};
+	return details as BaseUIGenericEventDetails<Reason, CustomProperties>;
+}

package/src/internals/csp-context/CSPContext.tsrx

@@ -0,0 +1,17 @@
+'use client';
+import * as React from 'octane';
+
+export interface CSPContextValue {
+	nonce?: string | undefined;
+	disableStyleElements?: boolean | undefined;
+}
+
+export const CSPContext = React.createContext<CSPContextValue | undefined>(undefined);
+
+const DEFAULT_CSP_CONTEXT_VALUE: CSPContextValue = {
+	disableStyleElements: false,
+};
+
+export function useCSPContext(): CSPContextValue {
+	return React.useContext(CSPContext) ?? DEFAULT_CSP_CONTEXT_VALUE;
+}

package/src/internals/csp-context/index.ts

@@ -0,0 +1,2 @@
+export { CSPContext, useCSPContext } from './CSPContext.tsrx';
+export type { CSPContextValue } from './CSPContext.tsrx';

package/src/internals/direction-context/DirectionContext.tsrx

@@ -0,0 +1,16 @@
+'use client';
+import * as React from 'octane';
+
+export type TextDirection = 'ltr' | 'rtl';
+
+export type DirectionContext = {
+	direction: TextDirection;
+};
+
+export const DirectionContext = React.createContext<DirectionContext | undefined>(undefined);
+
+export function useDirection() {
+	const context = React.useContext(DirectionContext);
+
+	return context?.direction ?? 'ltr';
+}

package/src/internals/direction-context/index.ts

@@ -0,0 +1,5 @@
+export { DirectionContext, useDirection } from './DirectionContext.tsrx';
+export type {
+	TextDirection,
+	DirectionContext as DirectionContextType,
+} from './DirectionContext.tsrx';

package/src/internals/field-constants/constants.ts

@@ -0,0 +1,44 @@
+import * as FieldControlDataAttributes from '../../field/control/FieldControlDataAttributes';
+import type { FieldRootState } from '../../field/root/FieldRoot.tsrx';
+
+export const DEFAULT_VALIDITY_STATE = {
+	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 = {
+	valid(value: boolean | null): Record<string, string> | null {
+		if (value === null) {
+			return null;
+		}
+		if (value) {
+			return { [FieldControlDataAttributes.valid]: '' };
+		}
+		return { [FieldControlDataAttributes.invalid]: '' };
+	},
+};

package/src/internals/field-constants/index.ts

@@ -0,0 +1,6 @@
+export {
+	DEFAULT_VALIDITY_STATE,
+	DEFAULT_FIELD_STATE_ATTRIBUTES,
+	DEFAULT_FIELD_ROOT_STATE,
+	fieldValidityMapping,
+} from './constants';

package/src/internals/field-register-control/index.ts

@@ -0,0 +1,6 @@
+export { useRegisterFieldControl } from './useRegisterFieldControl';
+export { useFieldControlRegistration } from './useFieldControlRegistration';
+export type {
+	FieldControlRegistration,
+	UseFieldControlRegistrationParameters,
+} from './useFieldControlRegistration';