@octanejs/base-ui 0.1.49 → 0.1.51

package/src/slider/indicator/SliderIndicatorDataAttributes.ts

@@ -0,0 +1,33 @@
+/**
+ * Present while the user is dragging.
+ */
+export const dragging = 'data-dragging';
+/**
+ * Indicates the orientation of the slider.
+ * @type {'horizontal' | 'vertical'}
+ */
+export const orientation = 'data-orientation';
+/**
+ * Present when the slider is disabled.
+ */
+export const disabled = 'data-disabled';
+/**
+ * Present when the slider is in a valid state (when wrapped in Field.Root).
+ */
+export const valid = 'data-valid';
+/**
+ * Present when the slider is in an invalid state (when wrapped in Field.Root).
+ */
+export const invalid = 'data-invalid';
+/**
+ * Present when the slider has been touched (when wrapped in Field.Root).
+ */
+export const touched = 'data-touched';
+/**
+ * Present when the slider's value has changed (when wrapped in Field.Root).
+ */
+export const dirty = 'data-dirty';
+/**
+ * Present when the slider is focused (when wrapped in Field.Root).
+ */
+export const focused = 'data-focused';

package/src/slider/label/SliderLabel.tsrx

@@ -0,0 +1,71 @@
+'use client';
+import type * as React from 'octane';
+import { isHTMLElement } from '@floating-ui/utils/dom';
+import { ownerDocument } from '@octanejs/base-ui-utils/owner';
+import { focusElementWithVisible, useLabel } from '../../internals/labelable-provider/useLabel';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import type { SliderRoot } from '../root/SliderRoot.tsrx';
+import { useSliderRootContext } from '../root/SliderRootContext';
+import { sliderStateAttributesMapping } from '../root/stateAttributesMapping';
+
+/**
+ * An accessible label that is automatically associated with the slider thumbs.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Slider](https://base-ui.com/react/components/slider)
+ */
+export const SliderLabel = function SliderLabel(
+	componentPropsWithRef: React.PropsWithoutRef<SliderLabel.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, ...elementProps } = componentProps;
+	// Keep label id derived from the root and ignore runtime `id` overrides from untyped consumers.
+	const elementPropsWithoutId = elementProps as typeof elementProps & { id?: string | undefined };
+	delete elementPropsWithoutId.id;
+
+	const { state, setLabelId, controlRef, rootLabelId } = useSliderRootContext();
+
+	function focusControl(event: React.MouseEvent, controlId: string | undefined) {
+		if (controlId) {
+			const controlElement = ownerDocument(event.currentTarget).getElementById(controlId);
+			if (isHTMLElement(controlElement)) {
+				focusElementWithVisible(controlElement);
+				return;
+			}
+		}
+
+		const fallbackInputs = controlRef.current?.querySelectorAll('input[type="range"]');
+		const fallbackInput = fallbackInputs?.length === 1 ? fallbackInputs[0] : null;
+		if (isHTMLElement(fallbackInput)) {
+			focusElementWithVisible(fallbackInput);
+		}
+	}
+
+	const labelProps = useLabel({
+		id: rootLabelId,
+		setLabelId,
+		focusControl,
+	});
+
+	return useRenderElement('div', componentProps, {
+		ref: forwardedRef,
+		state,
+		props: [labelProps, elementProps],
+		stateAttributesMapping: sliderStateAttributesMapping,
+	});
+};
+
+export type SliderLabelState = SliderRoot.State;
+
+export interface SliderLabelProps extends Omit<
+	BaseUIComponentProps<'div', SliderLabel.State>,
+	'id'
+> {}
+
+export namespace SliderLabel {
+	export type State = SliderLabelState;
+	export type Props = SliderLabelProps;
+}

package/src/slider/root/SliderRoot.tsrx

@@ -0,0 +1,610 @@
+'use client';
+import * as React from 'octane';
+import { ownerDocument } from '@octanejs/base-ui-utils/owner';
+import { useControlled } from '@octanejs/base-ui-utils/useControlled';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { warn } from '@octanejs/base-ui-utils/warn';
+import { clamp } from '@octanejs/base-ui-utils/clamp';
+import { areArraysEqual } from '@octanejs/base-ui-utils/areArraysEqual';
+import type { BaseUIComponentProps, Orientation } from '../../internals/types';
+import {
+	createChangeEventDetails,
+	createGenericEventDetails,
+	type BaseUIChangeEventDetails,
+	type BaseUIGenericEventDetails,
+} from '../../internals/createBaseUIEventDetails';
+import { useValueChanged } from '../../internals/useValueChanged';
+import { useBaseUiId } from '../../internals/useBaseUiId';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import { activeElement, contains } from '../../floating-ui-react/utils';
+import {
+	CompositeList,
+	type CompositeMetadata,
+} from '../../internals/composite/list/CompositeList.tsrx';
+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 { useFormContext } from '../../internals/form-context/FormContext';
+import { useLabelableContext } from '../../internals/labelable-provider/LabelableContext';
+import { resolveAriaLabelledBy, getDefaultLabelId } from '../../utils/resolveAriaLabelledBy';
+import { asc } from '../utils/asc';
+import { getSliderValue } from '../utils/getSliderValue';
+import { validateMinimumDistance } from '../utils/validateMinimumDistance';
+import type { ThumbMetadata } from '../thumb/SliderThumb.tsrx';
+import { sliderStateAttributesMapping } from './stateAttributesMapping';
+import { SliderRootContext } from './SliderRootContext';
+import { REASONS } from '../../internals/reasons';
+
+function areValuesEqual(
+	newValue: number | readonly number[],
+	oldValue: number | readonly number[],
+) {
+	return (
+		newValue === oldValue ||
+		(Array.isArray(newValue) && Array.isArray(oldValue) && areArraysEqual(newValue, oldValue))
+	);
+}
+
+/**
+ * Groups all parts of the slider.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Slider](https://base-ui.com/react/components/slider)
+ */
+export const SliderRoot = function SliderRoot<Value extends number | readonly number[]>(
+	componentPropsWithRef: React.PropsWithoutRef<SliderRoot.Props<Value>> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const {
+		'aria-labelledby': ariaLabelledByProp,
+		className,
+		defaultValue,
+		disabled: disabledProp = false,
+		id: idProp,
+		format,
+		largeStep = 10,
+		locale,
+		render,
+		max = 100,
+		min = 0,
+		minStepsBetweenValues = 0,
+		form,
+		name: nameProp,
+		onValueChange: onValueChangeProp,
+		onValueCommitted: onValueCommittedProp,
+		orientation = 'horizontal',
+		step = 1,
+		thumbCollisionBehavior = 'push',
+		thumbAlignment = 'center',
+		value: valueProp,
+		style,
+		...elementProps
+	} = componentProps;
+
+	const id = useBaseUiId(idProp);
+	const defaultLabelId = getDefaultLabelId(id);
+	const onValueChange = useStableCallback(
+		onValueChangeProp as (
+			value: number | number[],
+			eventDetails: SliderRoot.ChangeEventDetails,
+		) => void,
+	);
+	const onValueCommitted = useStableCallback(
+		onValueCommittedProp as (
+			value: number | readonly number[],
+			eventDetails: SliderRoot.CommitEventDetails,
+		) => void,
+	);
+
+	const { clearErrors } = useFormContext();
+	const {
+		state: fieldState,
+		disabled: fieldDisabled,
+		name: fieldName,
+		setTouched,
+		setDirty,
+		validityData,
+		validation,
+	} = useFieldRootContext();
+	const { labelId: fieldLabelId } = useLabelableContext();
+	const [labelId, setLabelId] = React.useState<string | undefined>();
+
+	const ariaLabelledby = ariaLabelledByProp ?? resolveAriaLabelledBy(fieldLabelId, labelId);
+	const disabled = fieldDisabled || disabledProp;
+	const name = fieldName ?? nameProp;
+
+	// The internal value is potentially unsorted, e.g. to support frozen arrays
+	// https://github.com/mui/material-ui/pull/28472
+	const [valueUnwrapped, setValueUnwrapped] = useControlled({
+		controlled: valueProp,
+		default: defaultValue ?? min,
+		name: 'Slider',
+	});
+
+	const sliderRef = React.useRef<HTMLElement | null>(null);
+	const controlRef = React.useRef<HTMLElement | null>(null);
+	const thumbRefs = React.useRef<(HTMLElement | null)[]>([]);
+	// The px distance between the pointer and the center of a pressed thumb.
+	const pressedThumbCenterOffsetRef = React.useRef<number | null>(null);
+	// The index of the pressed thumb, or the closest thumb if the `Control` was pressed.
+	// This is updated on pointerdown, which is sooner than the `active/activeIndex`
+	// state which is updated later when the nested `input` receives focus.
+	const pressedThumbIndexRef = React.useRef(-1);
+	// The values when the current drag interaction started.
+	const pressedValuesRef = React.useRef<readonly number[] | null>(null);
+	const lastChangeReasonRef = React.useRef<SliderRoot.ChangeEventReason>(REASONS.none);
+
+	// We can't use the :active browser pseudo-classes.
+	// - The active state isn't triggered when clicking on the rail.
+	// - The active state isn't transferred when inversing a range slider.
+	const [active, setActiveState] = React.useState(-1);
+	const [lastUsedThumbIndex, setLastUsedThumbIndex] = React.useState(-1);
+	const [dragging, setDragging] = React.useState(false);
+	const [thumbMap, setThumbMap] = React.useState(
+		() => new Map<Node, CompositeMetadata<ThumbMetadata>>(),
+	);
+	const [indicatorPosition, setIndicatorPosition] = React.useState<(number | undefined)[]>([
+		undefined,
+		undefined,
+	]);
+
+	const setActive = useStableCallback((value: number) => {
+		setActiveState(value);
+
+		if (value !== -1) {
+			setLastUsedThumbIndex(value);
+		}
+	});
+
+	const registerFieldControlRef = useStableCallback((element: HTMLElement | null) => {
+		if (element) {
+			controlRef.current = element;
+		}
+	});
+
+	const range = Array.isArray(valueUnwrapped);
+
+	const values = React.useMemo(() => {
+		if (!range) {
+			return [clamp(valueUnwrapped as number, min, max)];
+		}
+		return valueUnwrapped.map((value) => clamp(value, min, max)).sort(asc);
+	}, [max, min, range, valueUnwrapped]);
+
+	const fieldValue = range ? values : values[0];
+
+	useRegisterFieldControl(validation.inputRef, id, fieldValue, undefined, !disabled, nameProp);
+
+	useValueChanged(fieldValue, () => {
+		clearErrors(name);
+
+		validation.change(fieldValue);
+
+		const initialValue = validityData.initialValue as number | readonly number[] | undefined;
+		let isDirty: boolean;
+		if (Array.isArray(fieldValue) && Array.isArray(initialValue)) {
+			isDirty = !areArraysEqual(fieldValue, initialValue);
+		} else {
+			isDirty = fieldValue !== initialValue;
+		}
+		setDirty(isDirty);
+	});
+
+	const setValue = useStableCallback(
+		(newValue: number | number[], details: SliderRoot.ChangeEventDetails) => {
+			if (Number.isNaN(newValue) || areValuesEqual(newValue, valueUnwrapped)) {
+				return false;
+			}
+
+			// Redefine target to allow name and value to be read.
+			// This allows seamless integration with the most popular form libraries.
+			// https://github.com/mui/material-ui/issues/13485#issuecomment-676048492
+			// Clone the event to not override `target` of the original event.
+			const nativeEvent = details.event;
+			const EventConstructor = nativeEvent.constructor as typeof Event;
+			const clonedEvent = new EventConstructor(nativeEvent.type, nativeEvent);
+
+			Object.defineProperty(clonedEvent, 'target', {
+				writable: true,
+				value: { value: newValue, name },
+			});
+
+			details.event = clonedEvent;
+
+			onValueChange(newValue, details);
+
+			if (details.isCanceled) {
+				return false;
+			}
+
+			lastChangeReasonRef.current = details.reason;
+
+			setValueUnwrapped(newValue as Value);
+
+			return true;
+		},
+	);
+
+	const handleInputChange = useStableCallback(
+		(valueInput: number, index: number, event: React.KeyboardEvent | React.ChangeEvent) => {
+			const newValue = getSliderValue(valueInput, index, min, max, range, values);
+
+			if (validateMinimumDistance(newValue, step, minStepsBetweenValues)) {
+				const reason = 'key' in event ? REASONS.keyboard : REASONS.inputChange;
+				const applied = setValue(
+					newValue,
+					createChangeEventDetails(reason, event, undefined, {
+						activeThumbIndex: index,
+					}),
+				);
+				setTouched(true);
+
+				if (applied) {
+					onValueCommitted(newValue, createGenericEventDetails(reason, event));
+				}
+			}
+		},
+	);
+
+	/* istanbul ignore else -- `process.env.NODE_ENV` is a build-time constant under test */
+	if (process.env.NODE_ENV !== 'production') {
+		if (min >= max) {
+			warn('Slider `max` must be greater than `min`.');
+		}
+	}
+
+	useIsoLayoutEffect(() => {
+		if (!disabled) {
+			return;
+		}
+
+		const activeEl = activeElement(ownerDocument(sliderRef.current));
+		if (contains(sliderRef.current, activeEl)) {
+			// This is necessary because Firefox and Safari will keep focus
+			// on a disabled element:
+			// https://codesandbox.io/p/sandbox/mui-pr-22247-forked-h151h?file=/src/App.js
+			(activeEl as HTMLElement).blur();
+		}
+
+		if (active !== -1) {
+			setActive(-1);
+		}
+	}, [active, disabled, setActive]);
+
+	const state: SliderRootState = React.useMemo(
+		() => ({
+			...fieldState,
+			activeThumbIndex: active,
+			disabled,
+			dragging,
+			orientation,
+			max,
+			min,
+			minStepsBetweenValues,
+			step,
+			values,
+		}),
+		[
+			fieldState,
+			active,
+			disabled,
+			dragging,
+			max,
+			min,
+			minStepsBetweenValues,
+			orientation,
+			step,
+			values,
+		],
+	);
+
+	const contextValue: SliderRootContext = React.useMemo(
+		() => ({
+			active,
+			controlRef,
+			disabled,
+			dragging,
+			validation,
+			format,
+			handleInputChange,
+			indicatorPosition,
+			inset: thumbAlignment !== 'center',
+			labelId: ariaLabelledby,
+			rootLabelId: defaultLabelId,
+			largeStep,
+			lastUsedThumbIndex,
+			lastChangeReasonRef,
+			form,
+			locale,
+			max,
+			min,
+			minStepsBetweenValues,
+			name,
+			onValueCommitted,
+			orientation,
+			pressedThumbCenterOffsetRef,
+			pressedThumbIndexRef,
+			pressedValuesRef,
+			registerFieldControlRef,
+			renderBeforeHydration: thumbAlignment === 'edge',
+			setActive,
+			setDragging,
+			setIndicatorPosition,
+			setLabelId,
+			setValue,
+			state,
+			step,
+			thumbCollisionBehavior,
+			thumbMap,
+			thumbRefs,
+			values,
+		}),
+		[
+			active,
+			ariaLabelledby,
+			defaultLabelId,
+			disabled,
+			dragging,
+			validation,
+			format,
+			handleInputChange,
+			indicatorPosition,
+			largeStep,
+			lastUsedThumbIndex,
+			form,
+			locale,
+			max,
+			min,
+			minStepsBetweenValues,
+			name,
+			onValueCommitted,
+			orientation,
+			registerFieldControlRef,
+			setActive,
+			setValue,
+			state,
+			step,
+			thumbCollisionBehavior,
+			thumbAlignment,
+			thumbMap,
+			values,
+		],
+	);
+
+	const element = useRenderElement('div', componentProps, {
+		state,
+		ref: [forwardedRef, sliderRef],
+		props: [
+			{
+				'aria-labelledby': ariaLabelledby,
+				id,
+				role: 'group',
+			},
+			elementProps,
+			(props) => validation.getValidationProps(disabled, props),
+		],
+		stateAttributesMapping: sliderStateAttributesMapping,
+	});
+
+	return (
+		<SliderRootContext.Provider value={contextValue}>
+			<CompositeList elementsRef={thumbRefs} onMapChange={setThumbMap}>
+				{element}
+			</CompositeList>
+		</SliderRootContext.Provider>
+	);
+};
+
+export interface SliderRootState extends FieldRootState {
+	/**
+	 * The index of the active thumb.
+	 */
+	activeThumbIndex: number;
+	/**
+	 * Whether the component should ignore user interaction.
+	 */
+	disabled: boolean;
+	/**
+	 * Whether the thumb is currently being dragged.
+	 */
+	dragging: boolean;
+	/**
+	 * The maximum value.
+	 */
+	max: number;
+	/**
+	 * The minimum value.
+	 */
+	min: number;
+	/**
+	 * The minimum steps between values in a range slider.
+	 * @default 0
+	 */
+	minStepsBetweenValues: number;
+	/**
+	 * The component orientation.
+	 */
+	orientation: Orientation;
+	/**
+	 * The step increment of the slider when incrementing or decrementing. It will snap
+	 * to multiples of this value. Decimal values are supported.
+	 * @default 1
+	 */
+	step: number;
+	/**
+	 * The raw number value of the slider.
+	 */
+	values: readonly number[];
+}
+
+export interface SliderRootProps<
+	Value extends number | readonly number[] = number | readonly number[],
+> extends BaseUIComponentProps<'div', SliderRootState> {
+	/**
+	 * The uncontrolled value of the slider when it's initially rendered.
+	 *
+	 * To render a controlled slider, use the `value` prop instead.
+	 */
+	defaultValue?: Value | undefined;
+	/**
+	 * Whether the slider should ignore user interaction.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+	/**
+	 * Options to format the value.
+	 */
+	format?: Intl.NumberFormatOptions | undefined;
+	/**
+	 * The locale used by `Intl.NumberFormat` when formatting the value.
+	 * Defaults to the user's runtime locale.
+	 */
+	locale?: Intl.LocalesArgument | undefined;
+	/**
+	 * The maximum allowed value of the slider.
+	 * Should not be equal to min.
+	 * @default 100
+	 */
+	max?: number | undefined;
+	/**
+	 * The minimum allowed value of the slider.
+	 * Should not be equal to max.
+	 * @default 0
+	 */
+	min?: number | undefined;
+	/**
+	 * The minimum steps between values in a range slider.
+	 * @default 0
+	 */
+	minStepsBetweenValues?: number | undefined;
+	/**
+	 * Identifies the field when a form is submitted.
+	 */
+	name?: string | undefined;
+	/**
+	 * Identifies the form that owns the slider inputs.
+	 * Useful when the slider is rendered outside the form.
+	 */
+	form?: string | undefined;
+	/**
+	 * The component orientation.
+	 * @default 'horizontal'
+	 */
+	orientation?: Orientation | undefined;
+	/**
+	 * The granularity with which the slider can step through values. (A "discrete" slider.)
+	 * The `min` prop serves as the origin for the valid values.
+	 * We recommend (max - min) to be evenly divisible by the step.
+	 * @default 1
+	 */
+	step?: number | undefined;
+	/**
+	 * The granularity with which the slider can step through values when using Page Up/Page Down or Shift + Arrow Up/Arrow Down.
+	 * @default 10
+	 */
+	largeStep?: number | undefined;
+	/**
+	 * How the thumb(s) are aligned relative to `Slider.Control` when the value is at `min` or `max`:
+	 * - `center`: The center of the thumb is aligned with the control edge
+	 * - `edge`: The thumb is inset within the control such that its edge is aligned with the control edge
+	 * - `edge-client-only`: Same as `edge` but renders after React hydration on the client, reducing bundle size in return
+	 * @default 'center'
+	 */
+	thumbAlignment?: 'center' | 'edge' | 'edge-client-only' | undefined;
+	/**
+	 * Controls how thumbs behave when they collide during pointer interactions.
+	 *
+	 * - `'push'` (default): Thumbs push each other without restoring their previous positions when dragged back.
+	 * - `'swap'`: Thumbs swap places when dragged past each other.
+	 * - `'none'`: Thumbs cannot move past each other; excess movement is ignored.
+	 *
+	 * @default 'push'
+	 */
+	thumbCollisionBehavior?: 'push' | 'swap' | 'none' | undefined;
+	/**
+	 * The value of the slider.
+	 * For range sliders, provide an array with one value per thumb.
+	 */
+	value?: Value | undefined;
+	/**
+	 * Callback function that is fired when the slider's value changed.
+	 * Receives the new value as the first argument; the originating event is
+	 * available as `eventDetails.event`. The value is also reflected on
+	 * `eventDetails.event.target.value` for form integration.
+	 *
+	 * The `eventDetails.reason` indicates what triggered the change:
+	 *
+	 * - `'input-change'` when the hidden range input emits a change event (for example, via form integration)
+	 * - `'track-press'` when the control track is pressed
+	 * - `'drag'` while dragging a thumb
+	 * - `'keyboard'` for keyboard input
+	 * - `'none'` when the change is triggered without a specific interaction
+	 */
+	onValueChange?:
+		| ((
+				value: Value extends number ? number : Value,
+				eventDetails: SliderRoot.ChangeEventDetails,
+		  ) => void)
+		| undefined;
+	/**
+	 * Callback function that is fired when a value change is committed.
+	 * Does not fire if the value did not change, or if the change was canceled.
+	 * **Warning**: This is a generic event, not a change event.
+	 *
+	 * The `eventDetails.reason` indicates what triggered the commit:
+	 *
+	 * - `'drag'` while dragging a thumb
+	 * - `'track-press'` when the control track is pressed
+	 * - `'keyboard'` for keyboard input
+	 * - `'input-change'` when the hidden range input emits a change event (for example, via form integration)
+	 * - `'none'` when the commit occurs without a specific interaction
+	 */
+	onValueCommitted?:
+		| ((
+				value: Value extends number ? number : Value,
+				eventDetails: SliderRoot.CommitEventDetails,
+		  ) => void)
+		| undefined;
+}
+
+export interface SliderRootChangeEventCustomProperties {
+	/**
+	 * The index of the active thumb at the time of the change.
+	 */
+	activeThumbIndex: number;
+}
+
+export type SliderRootChangeEventReason =
+	| typeof REASONS.inputChange
+	| typeof REASONS.trackPress
+	| typeof REASONS.drag
+	| typeof REASONS.keyboard
+	| typeof REASONS.none;
+export type SliderRootChangeEventDetails = BaseUIChangeEventDetails<
+	SliderRoot.ChangeEventReason,
+	SliderRootChangeEventCustomProperties
+>;
+
+export type SliderRootCommitEventReason =
+	| typeof REASONS.inputChange
+	| typeof REASONS.trackPress
+	| typeof REASONS.drag
+	| typeof REASONS.keyboard
+	| typeof REASONS.none;
+export type SliderRootCommitEventDetails = BaseUIGenericEventDetails<SliderRoot.CommitEventReason>;
+
+export namespace SliderRoot {
+	export type State = SliderRootState;
+	export type Props<Value extends number | readonly number[] = number | readonly number[]> =
+		SliderRootProps<Value>;
+	export type ChangeEventReason = SliderRootChangeEventReason;
+	export type ChangeEventDetails = SliderRootChangeEventDetails;
+	export type CommitEventReason = SliderRootCommitEventReason;
+	export type CommitEventDetails = SliderRootCommitEventDetails;
+}
+
+// Bundlers replace this expression; keep the build constant local to this module.
+declare const process: { env: { NODE_ENV?: string } };