@octanejs/base-ui 0.1.50 → 0.1.51

package/src/checkbox-group/CheckboxGroup.tsrx

@@ -0,0 +1,229 @@
+'use client';
+import * as React from 'octane';
+import { useControlled } from '@octanejs/base-ui-utils/useControlled';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { EMPTY_ARRAY } from '@octanejs/base-ui-utils/empty';
+import { areArraysEqual } from '@octanejs/base-ui-utils/areArraysEqual';
+import { useBaseUiId } from '../internals/useBaseUiId';
+import { useRenderElement } from '../internals/useRenderElement.tsrx';
+import { CheckboxGroupContext } from './CheckboxGroupContext';
+import type { FieldRootState } from '../field/root/FieldRoot.tsrx';
+import { isEligibleInput } from '../field/root/useFieldValidation';
+import { useFieldRootContext } from '../internals/field-root-context/FieldRootContext';
+import { useRegisterFieldControl } from '../internals/field-register-control/useRegisterFieldControl';
+import { useLabelableContext } from '../internals/labelable-provider/LabelableContext';
+import { useLabelableId } from '../internals/labelable-provider/useLabelableId';
+import type { BaseUIComponentProps } from '../internals/types';
+import { fieldValidityMapping } from '../internals/field-constants/constants';
+import { useCheckboxGroupParent } from './useCheckboxGroupParent';
+import type { BaseUIChangeEventDetails } from '../internals/createBaseUIEventDetails';
+import type { REASONS } from '../internals/reasons';
+import { useFormContext } from '../internals/form-context/FormContext';
+import { useValueChanged } from '../internals/useValueChanged';
+
+/**
+ * Provides a shared state to a series of checkboxes.
+ *
+ * Documentation: [Base UI Checkbox Group](https://base-ui.com/react/components/checkbox-group)
+ */
+export const CheckboxGroup = function CheckboxGroup(
+	componentPropsWithRef: React.PropsWithoutRef<CheckboxGroup.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const {
+		allValues,
+		className,
+		defaultValue: defaultValueProp,
+		disabled: disabledProp = false,
+		id: idProp,
+		onValueChange,
+		render,
+		value: externalValue,
+		style,
+		...elementProps
+	} = componentProps;
+
+	const {
+		disabled: fieldDisabled,
+		name: fieldName,
+		state: fieldState,
+		validation,
+		setFilled,
+		setDirty,
+		validityData,
+	} = useFieldRootContext();
+	const { labelId, registerControlId, getDescriptionProps } = useLabelableContext();
+	const { clearErrors, elementRef } = useFormContext();
+
+	const disabled = fieldDisabled || disabledProp;
+	const defaultValue = defaultValueProp ?? EMPTY_ARRAY;
+
+	const [value, setValueUnwrapped] = useControlled({
+		controlled: externalValue,
+		default: defaultValue,
+		name: 'CheckboxGroup',
+		state: 'value',
+	});
+
+	const setValue = useStableCallback(
+		(v: string[], eventDetails: CheckboxGroup.ChangeEventDetails) => {
+			onValueChange?.(v, eventDetails);
+
+			if (eventDetails.isCanceled) {
+				return;
+			}
+
+			setValueUnwrapped(v);
+		},
+	);
+
+	const parent = useCheckboxGroupParent({
+		allValues,
+		value,
+		onValueChange: setValue,
+	});
+
+	// The group is the field's control and takes its name from `aria-labelledby`, so `Field.Label`
+	// must not point `htmlFor` at one arbitrary checkbox inside the group.
+	useLabelableId({ id: null });
+
+	const id = useBaseUiId(idProp);
+	const getInputControl = validation.getInputControl;
+
+	const controlRef = React.useMemo<React.RefObject<HTMLElement | null>>(
+		() => ({
+			get current() {
+				return getInputControl();
+			},
+		}),
+		[getInputControl],
+	);
+
+	const getFormValue = useStableCallback(() => {
+		const formElement = elementRef.current;
+		if (!formElement) {
+			return value;
+		}
+
+		const successfulValues = new Set<string>();
+		for (const [input, registration] of validation.registeredInputs) {
+			if (
+				registration.value !== undefined &&
+				input.checked &&
+				isEligibleInput(input, formElement)
+			) {
+				successfulValues.add(registration.value);
+			}
+		}
+
+		return value.filter((inputValue) => successfulValues.has(inputValue));
+	});
+
+	useRegisterFieldControl(controlRef, id, value, getFormValue, !!fieldName && !disabled, fieldName);
+
+	useIsoLayoutEffect(() => {
+		setFilled(value.length > 0);
+	}, [value, setFilled]);
+
+	useValueChanged(value, () => {
+		if (fieldName) {
+			clearErrors(fieldName);
+		}
+
+		const initialValue = Array.isArray(validityData.initialValue)
+			? (validityData.initialValue as readonly string[])
+			: EMPTY_ARRAY;
+
+		setDirty(!areArraysEqual(value, initialValue));
+
+		validation.change(value);
+	});
+
+	const state: CheckboxGroupState = {
+		...fieldState,
+		disabled,
+	};
+
+	const contextValue: CheckboxGroupContext = React.useMemo(
+		() => ({
+			allValues,
+			value,
+			setValue,
+			parent,
+			disabled,
+			validation,
+			registerControlId,
+		}),
+		[allValues, value, setValue, parent, disabled, validation, registerControlId],
+	);
+
+	const element = useRenderElement('div', componentProps, {
+		state,
+		ref: forwardedRef,
+		props: [
+			{
+				id: idProp,
+				role: 'group',
+				'aria-labelledby': labelId,
+			},
+			elementProps,
+			getDescriptionProps,
+		],
+		stateAttributesMapping: fieldValidityMapping,
+	});
+
+	return (
+		<CheckboxGroupContext.Provider value={contextValue}>{element}</CheckboxGroupContext.Provider>
+	);
+};
+
+export interface CheckboxGroupState extends FieldRootState {
+	/**
+	 * Whether the component should ignore user interaction.
+	 */
+	disabled: boolean;
+}
+
+export interface CheckboxGroupProps extends BaseUIComponentProps<'div', CheckboxGroupState> {
+	/**
+	 * Names of the checkboxes in the group that should be ticked.
+	 *
+	 * To render an uncontrolled checkbox group, use the `defaultValue` prop instead.
+	 */
+	value?: string[] | undefined;
+	/**
+	 * Names of the checkboxes in the group that should be initially ticked.
+	 *
+	 * To render a controlled checkbox group, use the `value` prop instead.
+	 */
+	defaultValue?: string[] | undefined;
+	/**
+	 * Event handler called when a checkbox in the group is ticked or unticked.
+	 * Provides the new value as an argument.
+	 */
+	onValueChange?:
+		((value: string[], eventDetails: CheckboxGroupChangeEventDetails) => void) | undefined;
+	/**
+	 * Names of all checkboxes in the group. Use this when creating a parent checkbox.
+	 */
+	allValues?: string[] | undefined;
+	/**
+	 * Whether the component should ignore user interaction.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+}
+
+export type CheckboxGroupChangeEventReason = typeof REASONS.none;
+export type CheckboxGroupChangeEventDetails =
+	BaseUIChangeEventDetails<CheckboxGroup.ChangeEventReason>;
+
+export namespace CheckboxGroup {
+	export type State = CheckboxGroupState;
+	export type Props = CheckboxGroupProps;
+	export type ChangeEventReason = CheckboxGroupChangeEventReason;
+	export type ChangeEventDetails = CheckboxGroupChangeEventDetails;
+}

package/src/checkbox-group/CheckboxGroupContext.ts

@@ -0,0 +1,33 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import type { UseFieldValidationReturnValue } from '../field/root/useFieldValidation';
+import type { UseCheckboxGroupParentReturnValue } from './useCheckboxGroupParent';
+import type { BaseUIChangeEventDetails } from '../internals/createBaseUIEventDetails';
+import type { BaseUIEventReasons } from '../internals/reasons';
+import type { LabelableContext } from '../internals/labelable-provider/LabelableContext';
+
+export interface CheckboxGroupContext {
+	value: string[];
+	setValue: (
+		value: string[],
+		eventDetails: BaseUIChangeEventDetails<BaseUIEventReasons['none']>,
+	) => void;
+	allValues: string[] | undefined;
+	parent: UseCheckboxGroupParentReturnValue;
+	disabled: boolean;
+	validation: UseFieldValidationReturnValue;
+	/**
+	 * `registerControlId` of the labelable scope the group renders in. A checkbox seeing the same
+	 * function shares that scope, so the group, not the checkbox, is the field's control.
+	 */
+	registerControlId: LabelableContext['registerControlId'];
+}
+
+export const CheckboxGroupContext = React.createContext<CheckboxGroupContext | undefined>(
+	undefined,
+);
+
+export function useCheckboxGroupContext() {
+	return React.useContext(CheckboxGroupContext);
+}

package/src/checkbox-group/CheckboxGroupDataAttributes.ts

@@ -0,0 +1,4 @@
+/**
+ * Present when the checkbox group is disabled.
+ */
+export const disabled = 'data-disabled';

package/src/checkbox-group/index.ts

@@ -0,0 +1,2 @@
+export { CheckboxGroup } from './CheckboxGroup.tsrx';
+export type * from './CheckboxGroup.tsrx';

package/src/checkbox-group/useCheckboxGroupParent.ts

@@ -0,0 +1,176 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { EMPTY_ARRAY } from '@octanejs/base-ui-utils/empty';
+import type { BaseUIChangeEventDetails } from '../internals/createBaseUIEventDetails';
+import type { BaseUIEventReasons } from '../internals/reasons';
+
+export function useCheckboxGroupParent(
+	params: UseCheckboxGroupParentParameters,
+): UseCheckboxGroupParentReturnValue {
+	const { allValues = EMPTY_ARRAY, value, onValueChange: onValueChangeProp } = params;
+
+	const uncontrolledStateRef = React.useRef(value);
+	const disabledStatesRef = React.useRef(new Map<string, boolean>());
+
+	const [status, setStatus] = React.useState<'on' | 'off' | 'mixed'>('mixed');
+	// A `Map` rather than an object: checkbox values are consumer data, and a value like
+	// `constructor` would otherwise read straight off `Object.prototype`.
+	// Replace only the wrapper to rerender without cloning the growing registry.
+	const [childIdsState, setChildIdsState] = React.useState(() => ({
+		registry: new Map<string, readonly string[]>(),
+	}));
+
+	const checked = value.length === allValues.length;
+	const indeterminate = value.length !== allValues.length && value.length > 0;
+
+	const onValueChange = useStableCallback(onValueChangeProp);
+
+	const registerChildId = useStableCallback((childValue: string, childId: string) => {
+		const childIds = childIdsState.registry;
+		const ids = childIds.get(childValue);
+		if (!ids?.includes(childId)) {
+			childIds.set(childValue, ids ? ids.concat(childId) : [childId]);
+			setChildIdsState({ registry: childIds });
+		}
+
+		return () => {
+			const registeredIds = childIds.get(childValue);
+			if (!registeredIds?.includes(childId)) {
+				return;
+			}
+
+			const nextIds = registeredIds.filter((id) => id !== childId);
+			if (nextIds.length === 0) {
+				childIds.delete(childValue);
+			} else {
+				childIds.set(childValue, nextIds);
+			}
+			setChildIdsState({ registry: childIds });
+		};
+	});
+
+	const getParentProps: UseCheckboxGroupParentReturnValue['getParentProps'] = React.useCallback(
+		() => ({
+			indeterminate,
+			checked,
+			// Children report their own rendered id, so a custom `id` survives and no unmounted
+			// element is named.
+			'aria-controls':
+				allValues.flatMap((v) => childIdsState.registry.get(v) ?? EMPTY_ARRAY).join(' ') ||
+				undefined,
+			onCheckedChange(_, eventDetails) {
+				const uncontrolledState = uncontrolledStateRef.current;
+
+				// None except the disabled ones that are checked, which can't be changed.
+				const none = allValues.filter(
+					(v) => disabledStatesRef.current.get(v) && uncontrolledState.includes(v),
+				);
+				// "All" that are valid:
+				// - any that aren't disabled
+				// - disabled ones that are checked
+				const all = allValues.filter(
+					(v) => !disabledStatesRef.current.get(v) || uncontrolledState.includes(v),
+				);
+
+				const allOnOrOff =
+					uncontrolledState.length === all.length || uncontrolledState.length === 0;
+
+				if (allOnOrOff) {
+					if (value.length === all.length) {
+						onValueChange(none, eventDetails);
+					} else {
+						onValueChange(all, eventDetails);
+					}
+					return;
+				}
+
+				let nextStatus: 'on' | 'off' | 'mixed' = 'mixed';
+				let nextValue = uncontrolledState;
+
+				if (status === 'mixed') {
+					nextStatus = 'on';
+					nextValue = all;
+				} else if (status === 'on') {
+					nextStatus = 'off';
+					nextValue = none;
+				}
+
+				onValueChange(nextValue, eventDetails);
+
+				if (!eventDetails.isCanceled) {
+					setStatus(nextStatus);
+				}
+			},
+		}),
+		[allValues, checked, childIdsState, indeterminate, onValueChange, status, value.length],
+	);
+
+	const getChildProps: UseCheckboxGroupParentReturnValue['getChildProps'] = React.useCallback(
+		(childValue: string) => ({
+			checked: value.includes(childValue),
+			onCheckedChange(nextChecked, eventDetails) {
+				const newValue = value.slice();
+				if (nextChecked) {
+					newValue.push(childValue);
+				} else {
+					newValue.splice(newValue.indexOf(childValue), 1);
+				}
+
+				onValueChange(newValue, eventDetails);
+
+				if (!eventDetails.isCanceled) {
+					uncontrolledStateRef.current = newValue;
+					setStatus('mixed');
+				}
+			},
+		}),
+		[onValueChange, value],
+	);
+
+	return React.useMemo(
+		() => ({
+			getParentProps,
+			getChildProps,
+			registerChildId,
+			disabledStatesRef,
+		}),
+		[getParentProps, getChildProps, registerChildId],
+	);
+}
+
+export interface UseCheckboxGroupParentParameters {
+	allValues?: string[] | undefined;
+	value: string[];
+	onValueChange?:
+		| ((
+				value: string[],
+				eventDetails: BaseUIChangeEventDetails<BaseUIEventReasons['none']>,
+		  ) => void)
+		| undefined;
+}
+
+export interface UseCheckboxGroupParentReturnValue {
+	disabledStatesRef: React.RefObject<Map<string, boolean>>;
+	/**
+	 * Reports the `id` of the element a child checkbox exposes.
+	 */
+	registerChildId: (value: string, id: string) => () => void;
+	getParentProps: () => {
+		indeterminate: boolean;
+		checked: boolean;
+		'aria-controls': string | undefined;
+		onCheckedChange: (
+			checked: boolean,
+			eventDetails: BaseUIChangeEventDetails<BaseUIEventReasons['none']>,
+		) => void;
+	};
+	getChildProps: (value: string) => {
+		checked: boolean;
+		onCheckedChange: (
+			checked: boolean,
+			eventDetails: BaseUIChangeEventDetails<BaseUIEventReasons['none']>,
+		) => void;
+	};
+}

package/src/collapsible/index.parts.ts

@@ -0,0 +1,3 @@
+export { CollapsibleRoot as Root } from './root/CollapsibleRoot.tsrx';
+export { CollapsibleTrigger as Trigger } from './trigger/CollapsibleTrigger.tsrx';
+export { CollapsiblePanel as Panel } from './panel/CollapsiblePanel.tsrx';

package/src/collapsible/index.ts

@@ -0,0 +1,12 @@
+export * as Collapsible from './index.parts';
+
+export type * from './root/CollapsibleRoot.tsrx';
+export type * from './trigger/CollapsibleTrigger.tsrx';
+export type * from './panel/CollapsiblePanel.tsrx';
+
+// Retain the named runtime exports of the previous Octane binding.
+export {
+	Root as CollapsibleRoot,
+	Trigger as CollapsibleTrigger,
+	Panel as CollapsiblePanel,
+} from './index.parts';

package/src/collapsible/panel/CollapsiblePanel.tsrx

@@ -0,0 +1,168 @@
+'use client';
+import * as React from 'octane';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { warn } from '@octanejs/base-ui-utils/warn';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { resolveStyle } from '../../utils/resolveStyle';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import { useCollapsibleRootContext } from '../root/CollapsibleRootContext';
+import type { CollapsibleRootState } from '../root/CollapsibleRoot.tsrx';
+import { collapsibleStateAttributesMapping } from '../root/stateAttributesMapping';
+import { useCollapsiblePanel } from './useCollapsiblePanel';
+import * as CollapsiblePanelCssVars from './CollapsiblePanelCssVars';
+import type { TransitionStatus } from '../../internals/useTransitionStatus';
+
+/**
+ * A panel with the collapsible contents.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Collapsible](https://base-ui.com/react/components/collapsible)
+ */
+export const CollapsiblePanel = function CollapsiblePanel(
+	componentPropsWithRef: React.PropsWithoutRef<CollapsiblePanel.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const {
+		className,
+		hiddenUntilFound: hiddenUntilFoundProp,
+		keepMounted: keepMountedProp,
+		render,
+		id: idProp,
+		style,
+		...elementProps
+	} = componentProps;
+
+	/* istanbul ignore else -- `process.env.NODE_ENV` is a build-time constant under test */
+	if (process.env.NODE_ENV !== 'production') {
+		// eslint-disable-next-line react-hooks/rules-of-hooks
+		React.useEffect(() => {
+			if (hiddenUntilFoundProp && keepMountedProp === false) {
+				warn(
+					'The `keepMounted={false}` prop on `Collapsible.Panel` is ignored when `hiddenUntilFound` is enabled, since the panel must remain mounted while closed.',
+				);
+			}
+		}, [hiddenUntilFoundProp, keepMountedProp]);
+	}
+
+	const {
+		defaultPanelId,
+		mounted,
+		onOpenChange,
+		open,
+		setMounted,
+		setPanelIdState,
+		setOpen,
+		state,
+		transitionStatus,
+	} = useCollapsibleRootContext();
+
+	const hiddenUntilFound = hiddenUntilFoundProp ?? false;
+	const keepMounted = keepMountedProp ?? false;
+	const registeredId = idProp || undefined;
+	const id = registeredId ?? defaultPanelId;
+
+	useIsoLayoutEffect(() => {
+		setPanelIdState((currentId) => registeredId ?? (currentId === null ? undefined : currentId));
+		return () => {
+			setPanelIdState((currentId) => (currentId === registeredId ? null : currentId));
+		};
+	}, [registeredId, setPanelIdState]);
+
+	const {
+		height,
+		props,
+		ref,
+		shouldPreventOpenAnimation,
+		shouldRender,
+		transitionStatus: panelTransitionStatus,
+		width,
+	} = useCollapsiblePanel({
+		externalRef: forwardedRef,
+		hiddenUntilFound,
+		id,
+		keepMounted,
+		mounted,
+		onOpenChange,
+		open,
+		setMounted,
+		setOpen,
+		transitionStatus,
+	});
+
+	const panelState: CollapsiblePanelState = {
+		...state,
+		transitionStatus: panelTransitionStatus,
+	};
+
+	const resolvedStyle = resolveStyle(style, panelState);
+
+	const element = useRenderElement(
+		'div',
+		{
+			...componentProps,
+			style: undefined,
+		},
+		{
+			state: panelState,
+			ref,
+			props: [
+				props,
+				{
+					style: {
+						[CollapsiblePanelCssVars.collapsiblePanelHeight as string]:
+							height === undefined ? 'auto' : `${height}px`,
+						[CollapsiblePanelCssVars.collapsiblePanelWidth as string]:
+							width === undefined ? 'auto' : `${width}px`,
+					},
+				},
+				elementProps,
+				resolvedStyle ? { style: resolvedStyle } : undefined,
+				// Resolve the public `style` prop so temporary `animationName: 'none'`
+				// can still win after user's inline styles have been merged.
+				shouldPreventOpenAnimation ? { style: { animationName: 'none' } } : undefined,
+			],
+			stateAttributesMapping: collapsibleStateAttributesMapping,
+		},
+	);
+
+	if (!shouldRender) {
+		return null;
+	}
+
+	return element;
+};
+
+export interface CollapsiblePanelState extends CollapsibleRootState {
+	/**
+	 * The transition status of the component.
+	 */
+	transitionStatus: TransitionStatus;
+}
+
+export interface CollapsiblePanelProps extends BaseUIComponentProps<'div', CollapsiblePanelState> {
+	/**
+	 * Allows the browser's built-in page search to find and expand the panel contents.
+	 *
+	 * Overrides the `keepMounted` prop and uses `hidden="until-found"`
+	 * to hide the element without removing it from the DOM.
+	 *
+	 * @default false
+	 */
+	hiddenUntilFound?: boolean | undefined;
+	/**
+	 * Whether to keep the element in the DOM while the panel is hidden.
+	 * This prop is ignored when `hiddenUntilFound` is used.
+	 * @default false
+	 */
+	keepMounted?: boolean | undefined;
+}
+
+export namespace CollapsiblePanel {
+	export type State = CollapsiblePanelState;
+	export type Props = CollapsiblePanelProps;
+}
+
+// Bundlers replace this expression; keep the build constant local to this module.
+declare const process: { env: { NODE_ENV?: string } };

package/src/collapsible/panel/CollapsiblePanelCssVars.ts

@@ -0,0 +1,10 @@
+/**
+ * The collapsible panel's height.
+ * @type {number}
+ */
+export const collapsiblePanelHeight = '--collapsible-panel-height';
+/**
+ * The collapsible panel's width.
+ * @type {number}
+ */
+export const collapsiblePanelWidth = '--collapsible-panel-width';

package/src/collapsible/panel/CollapsiblePanelDataAttributes.ts

@@ -0,0 +1,18 @@
+import { TransitionStatusDataAttributes } from '../../internals/stateAttributesMapping';
+
+/**
+ * Present when the collapsible panel is open.
+ */
+export const open = 'data-open';
+/**
+ * Present when the collapsible panel is closed.
+ */
+export const closed = 'data-closed';
+/**
+ * Present when the panel begins animating in.
+ */
+export const startingStyle = TransitionStatusDataAttributes.startingStyle;
+/**
+ * Present when the panel is animating out.
+ */
+export const endingStyle = TransitionStatusDataAttributes.endingStyle;