@octanejs/base-ui 0.1.50 → 0.1.52

package/src/checkbox/root/CheckboxRoot.tsrx

@@ -0,0 +1,516 @@
+'use client';
+import * as React from 'octane';
+import { EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import { useControlled } from '@octanejs/base-ui-utils/useControlled';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useMergedRefs } from '@octanejs/base-ui-utils/useMergedRefs';
+import { visuallyHidden, visuallyHiddenInput } from '@octanejs/base-ui-utils/visuallyHidden';
+import { ownerWindow } from '@octanejs/base-ui-utils/owner';
+import { getDefaultFormSubmitter } from '@octanejs/base-ui-utils/getDefaultFormSubmitter';
+import { getCheckboxStateAttributesMapping } from '../utils/getCheckboxStateAttributesMapping';
+import { dispatchClickWithModifiers } from '../../utils/dispatchClickWithModifiers';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import { useBaseUiId } from '../../internals/useBaseUiId';
+import type {
+	BaseUIComponentProps,
+	BaseUIEvent,
+	NonNativeButtonProps,
+} from '../../internals/types';
+import { mergeProps } from '../../merge-props';
+import { useButton } from '../../internals/use-button/useButton';
+import type { FieldRootState } from '../../field/root/FieldRoot.tsrx';
+import { useFieldRootContext } from '../../internals/field-root-context/FieldRootContext';
+import { useRegisterFieldControl } from '../../internals/field-register-control/useRegisterFieldControl';
+import { useFieldItemContext } from '../../field/item/FieldItemContext';
+import { useFormContext } from '../../internals/form-context/FormContext';
+import { useLabelableContext } from '../../internals/labelable-provider/LabelableContext';
+import { useAriaLabelledBy } from '../../internals/labelable-provider/useAriaLabelledBy';
+import { useLabelableId } from '../../internals/labelable-provider/useLabelableId';
+import { useCheckboxGroupContext } from '../../checkbox-group/CheckboxGroupContext';
+import { CheckboxRootContext } from './CheckboxRootContext';
+import {
+	type BaseUIChangeEventDetails,
+	createChangeEventDetails,
+} from '../../internals/createBaseUIEventDetails';
+import { REASONS } from '../../internals/reasons';
+import { useValueChanged } from '../../internals/useValueChanged';
+
+export const PARENT_CHECKBOX = 'data-parent';
+
+/**
+ * Represents the checkbox itself.
+ * Renders a `<span>` element and a hidden `<input>` beside.
+ *
+ * Documentation: [Base UI Checkbox](https://base-ui.com/react/components/checkbox)
+ */
+export const CheckboxRoot = function CheckboxRoot(
+	componentPropsWithRef: React.PropsWithoutRef<CheckboxRoot.Props> & {
+		ref?: React.Ref<HTMLElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const {
+		checked: checkedProp,
+		className,
+		defaultChecked = false,
+		'aria-labelledby': ariaLabelledByProp,
+		disabled: disabledProp = false,
+		form,
+		id: idProp,
+		indeterminate = false,
+		inputRef: inputRefProp,
+		name: nameProp,
+		onCheckedChange,
+		parent = false,
+		readOnly = false,
+		render,
+		required = false,
+		uncheckedValue,
+		value: valueProp,
+		nativeButton = false,
+		style,
+		...elementProps
+	} = componentProps;
+
+	const { clearErrors } = useFormContext();
+	const {
+		disabled: rootDisabled,
+		name: fieldName,
+		setDirty,
+		setFilled,
+		setFocused,
+		setTouched,
+		state: fieldState,
+		validationMode,
+		validityData,
+		validation: localValidation,
+	} = useFieldRootContext();
+	const fieldItemContext = useFieldItemContext();
+	const { labelId, registerControlId, getDescriptionProps } = useLabelableContext();
+
+	const groupContext = useCheckboxGroupContext();
+	const parentContext = groupContext?.allValues === undefined ? undefined : groupContext.parent;
+	const isGroupedWithParent = parentContext !== undefined;
+
+	const disabled =
+		rootDisabled || fieldItemContext.disabled || groupContext?.disabled || disabledProp;
+	const name = fieldName ?? nameProp;
+	const value = valueProp ?? name;
+
+	const id = useBaseUiId();
+
+	// A `CheckboxGroup` is the field's control and takes its name from `aria-labelledby`, so the
+	// checkboxes sharing its labelable scope must not claim the field's control id: they would all
+	// render that one id and collide. A `Field.Item` opens a scope the checkbox does own.
+	const ownsControlId = groupContext?.registerControlId !== registerControlId;
+
+	// `|| undefined` rather than `??`: an empty `id` falls back to the scope's control id.
+	const controlId = useLabelableId({ id: idProp || undefined, enabled: ownsControlId });
+
+	const rootId = nativeButton ? controlId : id;
+
+	let groupProps: Partial<Omit<CheckboxRoot.Props, 'className'>> = {};
+	if (isGroupedWithParent) {
+		if (parent) {
+			groupProps = parentContext.getParentProps();
+		} else if (value !== undefined) {
+			groupProps = parentContext.getChildProps(value);
+		}
+	}
+
+	const {
+		checked: groupChecked = checkedProp,
+		indeterminate: groupIndeterminate = indeterminate,
+		onCheckedChange: groupOnChange,
+		...otherGroupProps
+	} = groupProps;
+
+	const groupValue = groupContext?.value;
+
+	const controlRef = React.useRef<HTMLButtonElement | null>(null);
+
+	const { getButtonProps, buttonRef } = useButton({
+		disabled,
+		native: nativeButton,
+	});
+
+	const validation = groupContext?.validation ?? localValidation;
+
+	const [checked, setCheckedState] = useControlled({
+		controlled:
+			value !== undefined && groupValue !== undefined && !parent
+				? groupValue.includes(value)
+				: groupChecked,
+		default: defaultChecked,
+		name: 'Checkbox',
+		state: 'checked',
+	});
+
+	const computedChecked = isGroupedWithParent ? Boolean(groupChecked) : checked;
+	const computedIndeterminate = isGroupedWithParent
+		? groupIndeterminate || indeterminate
+		: indeterminate;
+
+	useRegisterFieldControl(controlRef, id, checked, undefined, !groupContext && !disabled, nameProp);
+
+	const registerChildId = parentContext?.registerChildId;
+
+	const inputRef = React.useRef<HTMLInputElement | null>(null);
+	const registerFieldInput = validation.registerInput;
+	const registeredInputValue = groupContext ? value : undefined;
+	const registerInput = React.useCallback(
+		(element: HTMLInputElement) =>
+			registerFieldInput(element, { controlRef, value: registeredInputValue }),
+		[registerFieldInput, registeredInputValue],
+	);
+	const mergedInputRef = useMergedRefs(inputRefProp, inputRef, parent ? undefined : registerInput);
+	const ariaLabelledBy = useAriaLabelledBy(
+		ariaLabelledByProp,
+		labelId,
+		inputRef,
+		!nativeButton,
+		controlId,
+	);
+
+	useIsoLayoutEffect(() => {
+		if (inputRef.current) {
+			// Re-assert on `checked` changes too: clicking the input natively resets `indeterminate`.
+			inputRef.current.indeterminate = computedIndeterminate;
+		}
+		// Inside a group, the group derives the filled state from its value.
+		if (!groupContext) {
+			setFilled(checked);
+		}
+	}, [checked, computedIndeterminate, groupContext, setFilled]);
+
+	useValueChanged(checked, () => {
+		if (groupContext) {
+			return;
+		}
+
+		clearErrors(name);
+		setDirty(checked !== validityData.initialValue);
+
+		validation.change(checked);
+	});
+
+	const inputProps = mergeProps<'input'>(
+		{
+			checked,
+			disabled,
+			form,
+			// parent checkboxes unset `name` to be excluded from form submission
+			name: parent ? undefined : name,
+			// Set `id` to stop Chrome warning about an unassociated input.
+			// When using a native button, the `id` is applied to the button instead.
+			id: nativeButton ? undefined : controlId,
+			required,
+			ref: mergedInputRef,
+			style: name ? visuallyHiddenInput : visuallyHidden,
+			tabIndex: -1,
+			type: 'checkbox',
+			'aria-hidden': true,
+			onChange(event) {
+				// Workaround for https://github.com/react/react/issues/9023
+				if (event.defaultPrevented) {
+					return;
+				}
+
+				if (readOnly) {
+					event.preventDefault();
+					return;
+				}
+
+				const nextChecked = event.currentTarget.checked;
+				const details = createChangeEventDetails(REASONS.none, event);
+
+				onCheckedChange?.(nextChecked, details);
+
+				if (details.isCanceled) {
+					return;
+				}
+
+				groupOnChange?.(nextChecked, details);
+
+				if (details.isCanceled) {
+					return;
+				}
+
+				setCheckedState(nextChecked);
+
+				if (value !== undefined && groupContext !== undefined && !parent && !isGroupedWithParent) {
+					const nextGroupValue = nextChecked
+						? [...groupContext.value, value]
+						: groupContext.value.filter((item) => item !== value);
+
+					groupContext.setValue(nextGroupValue, details);
+				}
+			},
+			onClick(event) {
+				// The click dispatched from the root's `onClick` is an implementation detail
+				// and must not reach ancestors, which already receive the original click.
+				event.stopPropagation();
+			},
+			onFocus() {
+				controlRef.current?.focus();
+			},
+		},
+		// React <19 sets an empty value if `undefined` is passed explicitly
+		// To avoid this, we only set the value if it's defined
+		valueProp !== undefined
+			? { value: (groupContext ? checked && valueProp : valueProp) || '' }
+			: EMPTY_OBJECT,
+		getDescriptionProps,
+		(props) => validation.getValidationProps(disabled, props),
+	);
+
+	React.useEffect(() => {
+		if (!parentContext || value === undefined) {
+			return undefined;
+		}
+
+		const disabledStates = parentContext.disabledStatesRef.current;
+		disabledStates.set(value, disabled);
+
+		return () => {
+			disabledStates.delete(value);
+		};
+	}, [parentContext, disabled, value]);
+
+	const state: CheckboxRootState = React.useMemo(
+		() => ({
+			...fieldState,
+			checked: computedChecked,
+			disabled,
+			readOnly,
+			required,
+			indeterminate: computedIndeterminate,
+		}),
+		[fieldState, computedChecked, disabled, readOnly, required, computedIndeterminate],
+	);
+
+	const stateAttributesMapping = getCheckboxStateAttributesMapping(state);
+
+	const element = useRenderElement('span', componentProps, {
+		state,
+		ref: [buttonRef, controlRef, forwardedRef],
+		props: [
+			{
+				id: rootId,
+				role: 'checkbox',
+				'aria-checked': computedIndeterminate ? 'mixed' : computedChecked,
+				'aria-readonly': readOnly || undefined,
+				'aria-required': required || undefined,
+				'aria-labelledby': ariaLabelledBy,
+				[PARENT_CHECKBOX as string]: parent ? '' : undefined,
+				onFocus() {
+					if (!disabled) {
+						setFocused(true);
+					}
+				},
+				onBlur() {
+					const inputEl = inputRef.current;
+					if (!inputEl) {
+						return;
+					}
+
+					setTouched(true);
+					setFocused(false);
+
+					if (validationMode === 'onBlur') {
+						validation.commit(groupContext ? groupValue : inputEl.checked);
+					}
+				},
+				onKeyDown(event: BaseUIEvent<React.KeyboardEvent>) {
+					if (event.key !== 'Enter') {
+						return;
+					}
+
+					// Let consumer `preventDefault()` handlers opt out while defensively stopping
+					// any remaining Base UI Enter handling from treating the checkbox as a button.
+					event.preventBaseUIHandler();
+
+					if (event.defaultPrevented) {
+						return;
+					}
+
+					const formToSubmit = inputRef.current?.form ?? null;
+					const currentTarget = event.currentTarget;
+					const originalPreventDefault = event.preventDefault;
+					let preventDefaultCalledAfterPropagation = false;
+
+					event.preventDefault = () => {
+						preventDefaultCalledAfterPropagation = true;
+						originalPreventDefault.call(event);
+					};
+					// Cancel native checkbox/button activation. The same native event
+					// reaches ancestors with defaultPrevented set; another preventDefault
+					// call during propagation also opts out of implicit form submission.
+					originalPreventDefault.call(event);
+
+					ownerWindow(currentTarget).queueMicrotask(() => {
+						event.preventDefault = originalPreventDefault;
+
+						if (!preventDefaultCalledAfterPropagation) {
+							getDefaultFormSubmitter(formToSubmit)?.click();
+						}
+					});
+				},
+				onClick(event: React.MouseEvent) {
+					if (readOnly || disabled) {
+						return;
+					}
+
+					event.preventDefault();
+
+					const input = inputRef.current;
+					if (!input) {
+						return;
+					}
+
+					dispatchClickWithModifiers(input, event);
+				},
+			},
+			elementProps,
+			otherGroupProps,
+			getButtonProps,
+			getDescriptionProps,
+			(props) => validation.getValidationProps(disabled, props),
+		],
+		stateAttributesMapping,
+	});
+
+	// `useRenderElement` always returns an element here, so the cast only narrows `props`.
+	const renderedId = (element as React.ReactElement<{ id?: string | undefined }>).props.id;
+	useIsoLayoutEffect(() => {
+		if (!registerChildId || parent || value === undefined || renderedId === undefined) {
+			return undefined;
+		}
+
+		return registerChildId(value, renderedId);
+	}, [registerChildId, parent, value, renderedId]);
+
+	return (
+		<CheckboxRootContext.Provider value={state}>
+			{element}
+			{!checked && !groupContext && name && !parent && uncheckedValue !== undefined && (
+				<input type="hidden" form={form} name={name} value={uncheckedValue} disabled={disabled} />
+			)}
+			<input {...inputProps} suppressHydrationWarning />
+		</CheckboxRootContext.Provider>
+	);
+};
+
+export interface CheckboxRootState extends FieldRootState {
+	/**
+	 * Whether the checkbox is currently ticked.
+	 */
+	checked: boolean;
+	/**
+	 * Whether the component should ignore user interaction.
+	 */
+	disabled: boolean;
+	/**
+	 * Whether the user should be unable to tick or untick the checkbox.
+	 */
+	readOnly: boolean;
+	/**
+	 * Whether the user must tick the checkbox before submitting a form.
+	 */
+	required: boolean;
+	/**
+	 * Whether the checkbox is in a mixed state: neither ticked, nor unticked.
+	 */
+	indeterminate: boolean;
+}
+
+export interface CheckboxRootProps
+	extends
+		NonNativeButtonProps,
+		Omit<BaseUIComponentProps<'span', CheckboxRootState>, 'onChange' | 'value'> {
+	/**
+	 * The id of the input element.
+	 */
+	id?: string | undefined;
+	/**
+	 * Identifies the field when a form is submitted.
+	 * @default undefined
+	 */
+	name?: string | undefined;
+	/**
+	 * Identifies the form that owns the hidden input.
+	 * Useful when the checkbox is rendered outside the form.
+	 */
+	form?: string | undefined;
+	/**
+	 * Whether the checkbox is currently ticked.
+	 *
+	 * To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
+	 * @default undefined
+	 */
+	checked?: boolean | undefined;
+	/**
+	 * Whether the checkbox is initially ticked.
+	 *
+	 * To render a controlled checkbox, use the `checked` prop instead.
+	 * @default false
+	 */
+	defaultChecked?: boolean | undefined;
+	/**
+	 * Whether the component should ignore user interaction.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+	/**
+	 * Event handler called when the checkbox is ticked or unticked.
+	 */
+	onCheckedChange?:
+		((checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => void) | undefined;
+	/**
+	 * Whether the user should be unable to tick or untick the checkbox.
+	 * @default false
+	 */
+	readOnly?: boolean | undefined;
+	/**
+	 * Whether the user must tick the checkbox before submitting a form.
+	 * @default false
+	 */
+	required?: boolean | undefined;
+	/**
+	 * Whether the checkbox is in a mixed state: neither ticked, nor unticked.
+	 * @default false
+	 */
+	indeterminate?: boolean | undefined;
+	/**
+	 * A ref to access the hidden `<input>` element.
+	 */
+	inputRef?: React.Ref<HTMLInputElement> | undefined;
+	/**
+	 * Whether the checkbox controls a group of child checkboxes.
+	 *
+	 * Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group).
+	 * @default false
+	 */
+	parent?: boolean | undefined;
+	/**
+	 * The value submitted with the form when the checkbox is unchecked.
+	 * By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
+	 */
+	uncheckedValue?: string | undefined;
+	/**
+	 * The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.
+	 * When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".
+	 */
+	value?: string | undefined;
+}
+
+export type CheckboxRootChangeEventReason = typeof REASONS.none;
+export type CheckboxRootChangeEventDetails =
+	BaseUIChangeEventDetails<CheckboxRoot.ChangeEventReason>;
+
+export namespace CheckboxRoot {
+	export type State = CheckboxRootState;
+	export type Props = CheckboxRootProps;
+	export type ChangeEventReason = CheckboxRootChangeEventReason;
+	export type ChangeEventDetails = CheckboxRootChangeEventDetails;
+}

package/src/checkbox/root/CheckboxRootContext.ts

@@ -0,0 +1,19 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import type { CheckboxRootState } from './CheckboxRoot.tsrx';
+
+export type CheckboxRootContext = CheckboxRootState;
+
+export const CheckboxRootContext = React.createContext<CheckboxRootContext | undefined>(undefined);
+
+export function useCheckboxRootContext() {
+	const context = React.useContext(CheckboxRootContext);
+	if (context === undefined) {
+		throw new Error(
+			'Base UI: CheckboxRootContext is missing. Checkbox parts must be placed within <Checkbox.Root>.',
+		);
+	}
+
+	return context;
+}

package/src/checkbox/root/CheckboxRootDataAttributes.ts

@@ -0,0 +1,48 @@
+/**
+ * Present when the checkbox is checked.
+ */
+export const checked = 'data-checked';
+/**
+ * Present when the checkbox is not checked.
+ */
+export const unchecked = 'data-unchecked';
+/**
+ * Present when the checkbox is in an indeterminate state.
+ */
+export const indeterminate = 'data-indeterminate';
+/**
+ * Present when the checkbox is disabled.
+ */
+export const disabled = 'data-disabled';
+/**
+ * Present when the checkbox is readonly.
+ */
+export const readonly = 'data-readonly';
+/**
+ * Present when the checkbox is required.
+ */
+export const required = 'data-required';
+/**
+ * Present when the checkbox is in a valid state (when wrapped in Field.Root).
+ */
+export const valid = 'data-valid';
+/**
+ * Present when the checkbox is in an invalid state (when wrapped in Field.Root).
+ */
+export const invalid = 'data-invalid';
+/**
+ * Present when the checkbox has been touched (when wrapped in Field.Root).
+ */
+export const touched = 'data-touched';
+/**
+ * Present when the checkbox's value has changed (when wrapped in Field.Root).
+ */
+export const dirty = 'data-dirty';
+/**
+ * Present when the checkbox is checked (when wrapped in Field.Root).
+ */
+export const filled = 'data-filled';
+/**
+ * Present when the checkbox is focused (when wrapped in Field.Root).
+ */
+export const focused = 'data-focused';

package/src/checkbox/utils/getCheckboxStateAttributesMapping.ts

@@ -0,0 +1,24 @@
+import type { StateAttributesMapping } from '../../internals/getStateAttributesProps';
+import type { CheckboxRootState } from '../root/CheckboxRoot.tsrx';
+import { fieldValidityMapping } from '../../internals/field-constants/constants';
+import * as CheckboxRootDataAttributes from '../root/CheckboxRootDataAttributes';
+
+export function getCheckboxStateAttributesMapping(
+	state: CheckboxRootState,
+): StateAttributesMapping<CheckboxRootState> {
+	return {
+		checked(value): Record<string, string> {
+			if (state.indeterminate) {
+				// `data-indeterminate` is already handled by the `indeterminate` prop.
+				return {};
+			}
+
+			if (value) {
+				return { [CheckboxRootDataAttributes.checked]: '' };
+			}
+
+			return { [CheckboxRootDataAttributes.unchecked]: '' };
+		},
+		...fieldValidityMapping,
+	};
+}