@octanejs/base-ui 0.1.50 → 0.1.52

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

@@ -0,0 +1,185 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { getCombinedFieldValidityData } from '../../field/utils/getCombinedFieldValidityData';
+import { useFormContext } from '../form-context/FormContext';
+import type { FieldValidityData } from '../../field/root/FieldRoot.tsrx';
+
+export interface FieldControlRegistration {
+	controlRef: React.RefObject<any>;
+	id: string | undefined;
+	name?: string | undefined;
+	getValue?: (() => unknown) | undefined;
+	value: unknown;
+}
+
+export function useFieldControlRegistration(params: UseFieldControlRegistrationParameters) {
+	const {
+		change,
+		commit,
+		invalid,
+		markedDirtyRef,
+		name,
+		setRegisteredFieldName,
+		registeredFieldIdRef,
+		setValidityData,
+		validityData,
+	} = params;
+
+	const { formRef } = useFormContext();
+
+	const activeFieldControlSourceRef = React.useRef<symbol | null>(null);
+	const registrationRef = React.useRef<FieldControlRegistration | null>(null);
+	const initialValueCapturedRef = React.useRef(false);
+
+	const getValueForForm = useStableCallback(() => {
+		const registration = registrationRef.current;
+		if (!registration) {
+			return undefined;
+		}
+
+		if (registration.getValue) {
+			return registration.getValue();
+		}
+
+		return registration.value;
+	});
+
+	function getRegistrationValue(registration: FieldControlRegistration) {
+		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));
+	});
+
+	function refreshRegistration() {
+		const registration = registrationRef.current;
+		if (!registration || !registration.id) {
+			return;
+		}
+
+		formRef.current.fields.set(registration.id, {
+			getValue: getValueForForm,
+			name: name ?? registration.name,
+			controlRef: registration.controlRef,
+			validityData: getCombinedFieldValidityData(validityData, invalid),
+			validate,
+		});
+	}
+
+	function deleteRegistration(id = registrationRef.current?.id) {
+		if (id) {
+			formRef.current.fields.delete(id);
+		}
+	}
+
+	// The baseline belongs to the field, not to a control instance: registration re-runs on every
+	// value change, and a control that unmounts and remounts (or is swapped for another one) comes
+	// back as a brand new registration. Capturing more than once would turn whichever value the
+	// control happens to hold at that point into the initial value, so a modified field would read
+	// pristine and its real initial value would read dirty. Consumers that want a fresh baseline
+	// remount or key `<Field.Root>` itself.
+	function captureInitialValue(registration: FieldControlRegistration) {
+		if (initialValueCapturedRef.current) {
+			return;
+		}
+
+		initialValueCapturedRef.current = true;
+		const initialValue = getRegistrationValue(registration);
+
+		setValidityData((prev) =>
+			prev.initialValue === initialValue ? prev : { ...prev, initialValue },
+		);
+	}
+
+	useIsoLayoutEffect(() => {
+		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,
+			validityData: getCombinedFieldValidityData(validityData, invalid),
+			validate,
+		});
+	}, [formRef, getValueForForm, invalid, name, setRegisteredFieldName, validate, validityData]);
+
+	useIsoLayoutEffect(() => {
+		const fields = formRef.current.fields;
+
+		return () => {
+			const id = registrationRef.current?.id;
+			if (id) {
+				fields.delete(id);
+			}
+		};
+	}, [formRef]);
+
+	const register = useStableCallback(
+		(source: symbol, registration: FieldControlRegistration | undefined) => {
+			if (!registration) {
+				if (activeFieldControlSourceRef.current === source) {
+					activeFieldControlSourceRef.current = null;
+					change(undefined, true);
+					deleteRegistration();
+					registrationRef.current = null;
+					setRegisteredFieldName(undefined);
+					registeredFieldIdRef.current = undefined;
+				}
+				return;
+			}
+
+			const previousId = registrationRef.current?.id;
+			const previousSource = activeFieldControlSourceRef.current;
+
+			// Drop work owned by a replaced control, but not on first registration.
+			if (previousSource && previousSource !== source) {
+				change(undefined, true);
+			}
+
+			activeFieldControlSourceRef.current = source;
+			registrationRef.current = registration;
+			if (!name) {
+				setRegisteredFieldName(registration.name);
+			}
+			registeredFieldIdRef.current = registration.id;
+
+			if (previousId && previousId !== registration.id) {
+				deleteRegistration(previousId);
+			}
+
+			captureInitialValue(registration);
+			refreshRegistration();
+		},
+	);
+
+	return [validate, register] as const;
+}
+
+export interface UseFieldControlRegistrationParameters {
+	change: (value: unknown, cancelPending?: boolean) => void;
+	commit: (value: unknown) => void;
+	invalid: boolean;
+	markedDirtyRef: React.RefObject<boolean>;
+	name: string | undefined;
+	setRegisteredFieldName: (name: string | undefined) => void;
+	registeredFieldIdRef: React.RefObject<string | undefined>;
+	setValidityData: React.Dispatch<React.SetStateAction<FieldValidityData>>;
+	validityData: FieldValidityData;
+}

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

@@ -0,0 +1,47 @@
+/** @jsxImportSource octane */
+'use client';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useRefWithInit } from '@octanejs/base-ui-utils/useRefWithInit';
+import { useFieldRootContext } from '../field-root-context/FieldRootContext';
+import type { FieldControlRegistration } from './useFieldControlRegistration';
+
+export function useRegisterFieldControl(
+	controlRef: FieldControlRegistration['controlRef'],
+	id: FieldControlRegistration['id'],
+	value: FieldControlRegistration['value'],
+	getFormValueOverride?: FieldControlRegistration['getValue'],
+	enabled = true,
+	name?: FieldControlRegistration['name'],
+) {
+	const { registerFieldControl } = useFieldRootContext();
+	const sourceRef = useRefWithInit(() => Symbol());
+
+	// Re-register without unregistering first: re-registration with the same id updates the
+	// form's fields Map entry in place, while a delete + re-add would move the field to the
+	// end of the Map every time its value changes.
+	useIsoLayoutEffect(() => {
+		const source = sourceRef.current;
+
+		if (!enabled) {
+			registerFieldControl(source, undefined);
+			return;
+		}
+
+		const registration: FieldControlRegistration = {
+			controlRef,
+			getValue: getFormValueOverride,
+			id,
+			name,
+			value,
+		};
+
+		registerFieldControl(source, registration);
+	}, [controlRef, enabled, getFormValueOverride, id, name, registerFieldControl, sourceRef, value]);
+
+	useIsoLayoutEffect(() => {
+		const source = sourceRef.current;
+		return () => {
+			registerFieldControl(source, undefined);
+		};
+	}, [registerFieldControl, sourceRef]);
+}

package/src/internals/field-root-context/FieldRootContext.ts

@@ -0,0 +1,79 @@
+/** @jsxImportSource octane */
+import { mergeProps } from '../../merge-props';
+import type { WithBaseUIEvent } from '../types';
+('use client');
+import * as React from 'octane';
+import { EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import { NOOP } from '../noop';
+import { DEFAULT_FIELD_ROOT_STATE, DEFAULT_VALIDITY_STATE } from '../field-constants/constants';
+import type { FieldValidityData, FieldRootState } from '../../field/root/FieldRoot.tsrx';
+import type { Form } from '../../form';
+import type { UseFieldValidationReturnValue } from '../../field/root/useFieldValidation';
+import type { HTMLProps } from '../types';
+import type { FieldControlRegistration } from '../field-register-control/useFieldControlRegistration';
+
+export interface FieldRootContext {
+	invalid: boolean | undefined;
+	name: string | undefined;
+	validityData: FieldValidityData;
+	setValidityData: React.Dispatch<React.SetStateAction<FieldValidityData>>;
+	disabled: boolean | undefined;
+	setTouched: React.Dispatch<React.SetStateAction<boolean>>;
+	setDirty: React.Dispatch<React.SetStateAction<boolean>>;
+	setFilled: React.Dispatch<React.SetStateAction<boolean>>;
+	setFocused: React.Dispatch<React.SetStateAction<boolean>>;
+	validationMode: Form.ValidationMode;
+	shouldValidateOnChange: () => boolean;
+	state: FieldRootState;
+	registerFieldControl: (
+		source: symbol,
+		registration: FieldControlRegistration | undefined,
+	) => void;
+	validation: UseFieldValidationReturnValue;
+}
+
+export const DEFAULT_FIELD_ROOT_CONTEXT: FieldRootContext = {
+	invalid: undefined,
+	name: undefined,
+	validityData: {
+		state: DEFAULT_VALIDITY_STATE,
+		errors: [],
+		error: '',
+		value: '',
+		initialValue: null,
+	},
+	setValidityData: NOOP,
+	disabled: undefined,
+	setTouched: NOOP,
+	setDirty: NOOP,
+	setFilled: NOOP,
+	setFocused: NOOP,
+	validationMode: 'onSubmit',
+	shouldValidateOnChange: () => false,
+	state: DEFAULT_FIELD_ROOT_STATE,
+	registerFieldControl: NOOP,
+	validation: {
+		getValidationProps: (_disabled: boolean, props: WithBaseUIEvent<HTMLProps> = EMPTY_OBJECT) =>
+			mergeProps(undefined, props),
+		inputRef: { current: null },
+		registeredInputs: new Map(),
+		registerInput: NOOP,
+		getInputControl: () => null,
+		commit: async () => {},
+		change: NOOP,
+	},
+};
+
+export const FieldRootContext = React.createContext<FieldRootContext>(DEFAULT_FIELD_ROOT_CONTEXT);
+
+export function useFieldRootContext(optional = true) {
+	const context = React.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/internals/field-root-context/index.ts

@@ -0,0 +1,2 @@
+export { FieldRootContext, useFieldRootContext } from './FieldRootContext';
+export type { FieldRootContext as FieldRootContextType } from './FieldRootContext';

package/src/internals/filter.ts

@@ -0,0 +1,82 @@
+import { stringifyLocale } from '@octanejs/base-ui-utils/stringifyLocale';
+import { stringifyAsLabel } from './resolveValueLabel.tsrx';
+
+const filterCache = new Map<string, Filter>();
+
+export function getFilter(options: GetFilterParameters = {}): Filter {
+	const mergedOptions: Intl.CollatorOptions = {
+		usage: 'search',
+		sensitivity: 'base',
+		ignorePunctuation: true,
+		...options,
+	};
+
+	const cacheKey = `${stringifyLocale(options.locale)}|${JSON.stringify(mergedOptions)}`;
+	const cachedFilter = filterCache.get(cacheKey);
+
+	if (cachedFilter) {
+		return cachedFilter;
+	}
+
+	const collator = new Intl.Collator(options.locale, mergedOptions);
+
+	const filter: Filter = {
+		contains<Item>(item: Item, query: string, itemToString?: (item: Item) => string) {
+			if (!query) {
+				return true;
+			}
+
+			const itemString = stringifyAsLabel(item, itemToString);
+
+			for (let i = 0; i <= itemString.length - query.length; i += 1) {
+				if (collator.compare(itemString.slice(i, i + query.length), query) === 0) {
+					return true;
+				}
+			}
+
+			return false;
+		},
+		startsWith<Item>(item: Item, query: string, itemToString?: (item: Item) => string) {
+			if (!query) {
+				return true;
+			}
+
+			const itemString = stringifyAsLabel(item, itemToString);
+
+			return collator.compare(itemString.slice(0, query.length), query) === 0;
+		},
+		endsWith<Item>(item: Item, query: string, itemToString?: (item: Item) => string) {
+			if (!query) {
+				return true;
+			}
+
+			const itemString = stringifyAsLabel(item, itemToString);
+			const queryLength = query.length;
+
+			return (
+				itemString.length >= queryLength &&
+				collator.compare(itemString.slice(itemString.length - queryLength), query) === 0
+			);
+		},
+	};
+
+	filterCache.set(cacheKey, filter);
+	return filter;
+}
+
+export interface GetFilterParameters extends Intl.CollatorOptions {
+	/**
+	 * The locale to use for string comparison.
+	 * Defaults to the user's runtime locale.
+	 */
+	locale?: Intl.LocalesArgument | undefined;
+}
+
+export interface Filter {
+	/** Returns whether the item matches the query anywhere. */
+	contains: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
+	/** Returns whether the item starts with the query. */
+	startsWith: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
+	/** Returns whether the item ends with the query. */
+	endsWith: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
+}

package/src/internals/form-context/FormContext.ts

@@ -0,0 +1,51 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import type { FieldValidityData } from '../../field/root/FieldRoot.tsrx';
+import { NOOP } from '../noop';
+import type { Form } from '../../form/Form.tsrx';
+
+export type Errors = Record<string, string | string[]>;
+
+export interface FormContext {
+	errors: Errors;
+	clearErrors: (name: string | undefined) => void;
+	elementRef: React.RefObject<HTMLFormElement | null>;
+	formRef: React.RefObject<{
+		fields: Map<
+			string,
+			{
+				name: string | undefined;
+				/**
+				 * After this returns, the field registry entry reflects the latest synchronous
+				 * validity verdict. Async validators do not block submit.
+				 */
+				validate: () => void;
+				validityData: FieldValidityData;
+				controlRef: React.RefObject<HTMLElement | null>;
+				getValue: () => unknown;
+			}
+		>;
+	}>;
+	validationMode: Form.ValidationMode;
+	submitCountRef: React.RefObject<number>;
+}
+
+export const FormContext = React.createContext<FormContext>({
+	elementRef: { current: null },
+	formRef: {
+		current: {
+			fields: new Map(),
+		},
+	},
+	errors: {},
+	clearErrors: NOOP,
+	validationMode: 'onSubmit',
+	submitCountRef: {
+		current: 0,
+	},
+});
+
+export function useFormContext() {
+	return React.useContext(FormContext);
+}

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

@@ -0,0 +1,2 @@
+export { FormContext, useFormContext } from './FormContext';
+export type { Errors } from './FormContext';

package/src/internals/getDisabledMountTransitionStyles.ts

@@ -0,0 +1,10 @@
+import type * as React from 'octane';
+import { EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import { DISABLED_TRANSITIONS_STYLE } from './constants';
+import type { TransitionStatus } from './useTransitionStatus';
+
+export function getDisabledMountTransitionStyles(transitionStatus: TransitionStatus): {
+	style?: React.CSSProperties | undefined;
+} {
+	return transitionStatus === 'starting' ? DISABLED_TRANSITIONS_STYLE : EMPTY_OBJECT;
+}

package/src/internals/getStateAttributesProps.ts

@@ -0,0 +1,32 @@
+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>,
+) {
+	const props: Record<string, string> = {};
+
+	/* eslint-disable-next-line guard-for-in */
+	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/internals/itemEquality.ts

@@ -0,0 +1,134 @@
+import { areArraysEqual } from '@octanejs/base-ui-utils/areArraysEqual';
+
+export type ItemEqualityComparer<Item = any, Value = Item> = (
+	itemValue: Item,
+	selectedValue: Value,
+) => boolean;
+
+// Compared by identity in `findSelectionIndex`; don't wrap it.
+export const defaultItemEquality: ItemEqualityComparer = (itemValue, selectedValue) =>
+	Object.is(itemValue, selectedValue);
+
+export function compareItemEquality<Item, Value>(
+	itemValue: Item,
+	selectedValue: Value,
+	comparer: ItemEqualityComparer<Item, Value>,
+): boolean {
+	if (itemValue == null || selectedValue == null) {
+		return Object.is(itemValue, selectedValue);
+	}
+	return comparer(itemValue, selectedValue);
+}
+
+export function isSelectedValueDirty(
+	currentValue: unknown,
+	initialValue: unknown,
+	comparer: ItemEqualityComparer,
+): boolean {
+	if (Array.isArray(currentValue) && Array.isArray(initialValue)) {
+		return !areArraysEqual(currentValue, initialValue, (itemValue, initialItemValue) =>
+			compareItemEquality(itemValue, initialItemValue, comparer),
+		);
+	}
+
+	return currentValue !== initialValue;
+}
+
+export function selectedValueIncludes<Item, Value>(
+	selectedValues: readonly Item[] | undefined | null,
+	itemValue: Value,
+	comparer: ItemEqualityComparer<Value, Item>,
+): boolean {
+	if (!selectedValues) {
+		return false;
+	}
+	return selectedValues.some((selectedValue) => {
+		if (selectedValue === undefined) {
+			return false;
+		}
+		return compareItemEquality(itemValue, selectedValue, comparer);
+	});
+}
+
+export function findItemIndex<Item, Value>(
+	itemValues: readonly Item[] | undefined | null,
+	selectedValue: Value,
+	comparer: ItemEqualityComparer<Item, Value>,
+): number {
+	if (!itemValues) {
+		return -1;
+	}
+	return itemValues.findIndex((itemValue) => {
+		if (itemValue === undefined) {
+			return false;
+		}
+		return compareItemEquality(itemValue, selectedValue, comparer);
+	});
+}
+
+// The default comparer is `Object.is`, so the values can be indexed instead of rescanned
+// for every item. A custom comparer may match values that don't hash alike.
+function createSelectionMatcher<Item, Value>(
+	selectedValues: readonly Value[],
+	comparer: ItemEqualityComparer<Item, Value>,
+): (itemValue: Item) => boolean {
+	if (comparer !== defaultItemEquality) {
+		return (itemValue) => selectedValueIncludes(selectedValues, itemValue, comparer);
+	}
+	const index = new Set<unknown>(selectedValues);
+	index.delete(undefined);
+	// `Set` treats +0 and -0 as equal; `Object.is` does not.
+	return (itemValue) =>
+		index.has(itemValue) &&
+		(itemValue !== 0 || selectedValues.some((v) => Object.is(itemValue, v)));
+}
+
+export function findSelectionIndex<Item, Value>(
+	itemValues: readonly Item[],
+	selectedValue: Value | readonly Value[] | null | undefined,
+	comparer: ItemEqualityComparer<Item, Value>,
+	multiple: boolean,
+): number | null {
+	// Only treat the value as a list in multiple mode: an array can itself be a valid
+	// single-select value.
+	const index =
+		multiple && Array.isArray(selectedValue)
+			? // Anchor to the first selected item in rendered order so the index does not depend
+				// on the order in which the values were added to the array.
+				itemValues.findIndex(createSelectionMatcher(selectedValue, comparer))
+			: findItemIndex(itemValues, selectedValue as Value, comparer);
+	return index === -1 ? null : index;
+}
+
+/** Resolves the first selected index as items register or change. */
+export function resolveSelectedIndex<Item, Value>(
+	index: number,
+	itemValue: Item,
+	registry: readonly Item[],
+	selectedValues: readonly Value[],
+	comparer: ItemEqualityComparer<Item, Value>,
+	currentIndex: number | null,
+): number | null {
+	if (selectedValueIncludes(selectedValues, itemValue, comparer)) {
+		// A later item only takes over once the current anchor stops being selected.
+		return currentIndex != null &&
+			index > currentIndex &&
+			selectedValueIncludes(selectedValues, registry[currentIndex], comparer)
+			? currentIndex
+			: index;
+	}
+	// The holder re-elects the anchor once it stops being selected.
+	return index === currentIndex
+		? findSelectionIndex(registry, selectedValues, comparer, true)
+		: currentIndex;
+}
+
+export function removeItem<Item, Value>(
+	selectedValues: readonly Item[],
+	itemValue: Value,
+	comparer: ItemEqualityComparer<Value, Item>,
+): Item[] {
+	return selectedValues.filter(
+		(selectedValue) => !compareItemEquality(itemValue, selectedValue, comparer),
+	);
+}

package/src/internals/labelable-provider/LabelableContext.ts

@@ -0,0 +1,49 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { NOOP } from '../noop';
+import type { HTMLProps } from '../types';
+
+export interface LabelableContext {
+	/**
+	 * The `id` of the labelable element.
+	 * When `null` the label omits `htmlFor`, either because the association is implicit or
+	 * because the control takes its name from `aria-labelledby`.
+	 */
+	controlId: string | null | undefined;
+	registerControlId: (source: symbol, id: string | null | undefined) => void;
+	resetControlId: () => void;
+	/**
+	 * The `id` of the label.
+	 */
+	labelId: string | undefined;
+	setLabelId: React.Dispatch<React.SetStateAction<string | undefined>>;
+	/**
+	 * An array of `id`s of elements that provide an accessible description.
+	 */
+	messageIds: string[];
+	setMessageIds: React.Dispatch<React.SetStateAction<string[]>>;
+	getDescriptionProps: <Props extends { 'aria-describedby'?: string }>(
+		externalProps: Props,
+	) => Omit<Props, 'aria-describedby'> & { 'aria-describedby'?: string };
+}
+
+/**
+ * A context for providing [labelable elements](https://html.spec.whatwg.org/multipage/forms.html#category-label)\
+ * with an accessible name (label) and description.
+ */
+export const LabelableContext = React.createContext<LabelableContext>({
+	controlId: undefined,
+	registerControlId: NOOP,
+	resetControlId: NOOP,
+	labelId: undefined,
+	setLabelId: NOOP,
+	messageIds: [],
+	setMessageIds: NOOP,
+	getDescriptionProps: <Props extends { 'aria-describedby'?: string }>(externalProps: Props) =>
+		externalProps,
+});
+
+export function useLabelableContext() {
+	return React.useContext(LabelableContext);
+}