@octanejs/aria 0.0.1 → 0.0.4

package/src/stately/selection/useMultipleSelectionState.ts

@@ -0,0 +1,178 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/selection/useMultipleSelectionState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; explicit dependency arrays are kept verbatim (they retain React's exact
+// behavior in octane).
+import type {
+	DisabledBehavior,
+	FocusStrategy,
+	Key,
+	MultipleSelection,
+	SelectionBehavior,
+	SelectionMode,
+} from '@react-types/shared';
+import { useEffect, useMemo, useRef, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import type { MultipleSelectionState } from './types';
+import { Selection } from './Selection';
+import { useControlledState } from '../utils/useControlledState';
+
+function equalSets(setA: any, setB: any): boolean {
+	if (setA.size !== setB.size) {
+		return false;
+	}
+
+	for (let item of setA) {
+		if (!setB.has(item)) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+export interface MultipleSelectionStateProps extends MultipleSelection {
+	/**
+	 * How multiple selection should behave in the collection.
+	 *
+	 * @default 'toggle'
+	 */
+	selectionBehavior?: SelectionBehavior;
+	/** Whether onSelectionChange should fire even if the new set of keys is the same as the last. */
+	allowDuplicateSelectionEvents?: boolean;
+	/**
+	 * Whether `disabledKeys` applies to all interactions, or only selection.
+	 *
+	 * @default 'all'
+	 */
+	disabledBehavior?: DisabledBehavior;
+}
+
+/**
+ * Manages state for multiple selection and focus in a collection.
+ */
+export function useMultipleSelectionState(
+	props: MultipleSelectionStateProps,
+): MultipleSelectionState;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useMultipleSelectionState(
+	props: MultipleSelectionStateProps,
+	slot: symbol | undefined,
+): MultipleSelectionState;
+export function useMultipleSelectionState(...args: any[]): MultipleSelectionState {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useMultipleSelectionState');
+	const props = user[0] as MultipleSelectionStateProps;
+
+	let {
+		selectionMode = 'none' as SelectionMode,
+		disallowEmptySelection = false,
+		allowDuplicateSelectionEvents,
+		selectionBehavior: selectionBehaviorProp = 'toggle',
+		disabledBehavior = 'all',
+	} = props;
+
+	// We want synchronous updates to `isFocused` and `focusedKey` after their setters are called.
+	// But we also need to trigger a react re-render. So, we have both a ref (sync) and state (async).
+	let isFocusedRef = useRef(false, subSlot(slot, 'focusedRef'));
+	let [, setFocused] = useState(false, subSlot(slot, 'focused'));
+	let focusedKeyRef = useRef<Key | null>(null, subSlot(slot, 'focusedKeyRef'));
+	let childFocusStrategyRef = useRef<FocusStrategy | null>(null, subSlot(slot, 'childFocus'));
+	let [, setFocusedKey] = useState<Key | null>(null, subSlot(slot, 'focusedKey'));
+	let selectedKeysProp = useMemo(
+		() => convertSelection(props.selectedKeys),
+		[props.selectedKeys],
+		subSlot(slot, 'selectedProp'),
+	);
+	let defaultSelectedKeys = useMemo(
+		() => convertSelection(props.defaultSelectedKeys, new Selection()),
+		[props.defaultSelectedKeys],
+		subSlot(slot, 'defaultSelected'),
+	);
+	let [selectedKeys, setSelectedKeys] = useControlledState(
+		selectedKeysProp,
+		defaultSelectedKeys!,
+		props.onSelectionChange,
+		subSlot(slot, 'selected'),
+	);
+	let disabledKeysProp = useMemo(
+		() => (props.disabledKeys ? new Set(props.disabledKeys) : new Set<Key>()),
+		[props.disabledKeys],
+		subSlot(slot, 'disabled'),
+	);
+	let [selectionBehavior, setSelectionBehavior] = useState(
+		selectionBehaviorProp,
+		subSlot(slot, 'behavior'),
+	);
+
+	// If the selectionBehavior prop is set to replace, but the current state is toggle (e.g. due to long press
+	// to enter selection mode on touch), and the selection becomes empty, reset the selection behavior.
+	if (
+		selectionBehaviorProp === 'replace' &&
+		selectionBehavior === 'toggle' &&
+		typeof selectedKeys === 'object' &&
+		selectedKeys.size === 0
+	) {
+		setSelectionBehavior('replace');
+	}
+
+	// If the selectionBehavior prop changes, update the state as well.
+	let lastSelectionBehavior = useRef(selectionBehaviorProp, subSlot(slot, 'lastBehavior'));
+	useEffect(
+		() => {
+			if (selectionBehaviorProp !== lastSelectionBehavior.current) {
+				setSelectionBehavior(selectionBehaviorProp);
+				lastSelectionBehavior.current = selectionBehaviorProp;
+			}
+		},
+		[selectionBehaviorProp],
+		subSlot(slot, 'behaviorSync'),
+	);
+
+	return {
+		selectionMode,
+		disallowEmptySelection,
+		selectionBehavior,
+		setSelectionBehavior,
+		get isFocused() {
+			return isFocusedRef.current;
+		},
+		setFocused(f) {
+			isFocusedRef.current = f;
+			setFocused(f);
+		},
+		get focusedKey() {
+			return focusedKeyRef.current;
+		},
+		get childFocusStrategy() {
+			return childFocusStrategyRef.current;
+		},
+		setFocusedKey(k, childFocusStrategy = 'first') {
+			focusedKeyRef.current = k;
+			childFocusStrategyRef.current = childFocusStrategy;
+			setFocusedKey(k);
+		},
+		selectedKeys,
+		setSelectedKeys(keys) {
+			if (allowDuplicateSelectionEvents || !equalSets(keys, selectedKeys)) {
+				// `keys` is contextually the shared Selection type ('all' | Set<Key>) while the
+				// controlled tuple is inferred over the local Selection class; the runtime value
+				// is always accepted, so narrow the type at the verbatim call.
+				setSelectedKeys(keys as 'all' | Selection);
+			}
+		},
+		disabledKeys: disabledKeysProp,
+		disabledBehavior,
+	};
+}
+
+function convertSelection(
+	selection: 'all' | Iterable<Key> | null | undefined,
+	defaultValue?: Selection,
+): 'all' | Selection | undefined {
+	if (!selection) {
+		return defaultValue;
+	}
+
+	return selection === 'all' ? 'all' : new Selection(selection);
+}

package/src/stately/slider/useSliderState.ts

@@ -0,0 +1,458 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/slider/useSliderState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; public value-level callbacks (onChange/onChangeEnd) are unchanged (the
+// onInput rule applies only to DOM wiring); upstream's untyped `createOnChange` params
+// are typed `any`; explicit dependency arrays are kept verbatim (they retain React's
+// exact behavior in octane).
+import { clamp, snapValueToStep } from '../utils/number';
+
+import type { LabelableProps, Orientation, RangeInputBase, ValueBase } from '@react-types/shared';
+import { useCallback, useMemo, useRef, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { useControlledState } from '../utils/useControlledState';
+
+export interface SliderProps<T = number | number[]>
+	extends RangeInputBase<number>, ValueBase<T>, LabelableProps {
+	/**
+	 * The orientation of the Slider.
+	 *
+	 * @default 'horizontal'
+	 */
+	orientation?: Orientation;
+	/** Whether the whole Slider is disabled. */
+	isDisabled?: boolean;
+	/** Fired when the slider stops moving, due to being let go. */
+	onChangeEnd?: (value: T) => void;
+	// These are duplicated from ValueBase to define defaults for the docs.
+	/**
+	 * The slider's minimum value.
+	 *
+	 * @default 0
+	 */
+	minValue?: number;
+	/**
+	 * The slider's maximum value.
+	 *
+	 * @default 100
+	 */
+	maxValue?: number;
+	/**
+	 * The slider's step value.
+	 *
+	 * @default 1
+	 */
+	step?: number;
+}
+
+export interface SliderState {
+	/**
+	 * Values managed by the slider by thumb index.
+	 */
+	readonly values: number[];
+	/**
+	 * The default values for each thumb.
+	 */
+	readonly defaultValues: number[];
+	/**
+	 * Get the value for the specified thumb.
+	 *
+	 * @param index
+	 */
+	getThumbValue(index: number): number;
+
+	/**
+	 * Sets the value for the specified thumb.
+	 * The actual value set will be clamped and rounded according to min/max/step.
+	 *
+	 * @param index
+	 * @param value
+	 */
+	setThumbValue(index: number, value: number): void;
+
+	/**
+	 * Sets value for the specified thumb by percent offset (between 0 and 1).
+	 *
+	 * @param index
+	 * @param percent
+	 */
+	setThumbPercent(index: number, percent: number): void;
+
+	/**
+	 * Whether the specific thumb is being dragged.
+	 *
+	 * @param index
+	 */
+	isThumbDragging(index: number): boolean;
+	/**
+	 * Set is dragging on the specified thumb.
+	 *
+	 * @param index
+	 * @param dragging
+	 */
+	setThumbDragging(index: number, dragging: boolean): void;
+
+	/**
+	 * Currently-focused thumb index.
+	 */
+	readonly focusedThumb: number | undefined;
+	/**
+	 * Set focused true on specified thumb. This will remove focus from
+	 * any thumb that had it before.
+	 *
+	 * @param index
+	 */
+	setFocusedThumb(index: number | undefined): void;
+
+	/**
+	 * Returns the specified thumb's value as a percentage from 0 to 1.
+	 *
+	 * @param index
+	 */
+	getThumbPercent(index: number): number;
+
+	/**
+	 * Returns the value as a percent between the min and max of the slider.
+	 *
+	 * @param index
+	 */
+	getValuePercent(value: number): number;
+
+	/**
+	 * Returns the string label for the specified thumb's value, per props.formatOptions.
+	 *
+	 * @param index
+	 */
+	getThumbValueLabel(index: number): string;
+
+	/**
+	 * Returns the string label for the value, per props.formatOptions.
+	 *
+	 * @param value
+	 */
+	getFormattedValue(value?: number | number[]): string;
+
+	/**
+	 * Returns the min allowed value for the specified thumb.
+	 *
+	 * @param index
+	 */
+	getThumbMinValue(index: number): number;
+
+	/**
+	 * Returns the max allowed value for the specified thumb.
+	 *
+	 * @param index
+	 */
+	getThumbMaxValue(index: number): number;
+
+	/**
+	 * Converts a percent along track (between 0 and 1) to the corresponding value.
+	 *
+	 * @param percent
+	 */
+	getPercentValue(percent: number): number;
+
+	/**
+	 * Returns if the specified thumb is editable.
+	 *
+	 * @param index
+	 */
+	isThumbEditable(index: number): boolean;
+
+	/**
+	 * Set the specified thumb's editable state.
+	 *
+	 * @param index
+	 * @param editable
+	 */
+	setThumbEditable(index: number, editable: boolean): void;
+
+	/**
+	 * Increments the value of the thumb by the step or page amount.
+	 */
+	incrementThumb(index: number, stepSize?: number): void;
+	/**
+	 * Decrements the value of the thumb by the step or page amount.
+	 */
+	decrementThumb(index: number, stepSize?: number): void;
+
+	/**
+	 * The step amount for the slider.
+	 */
+	readonly step: number;
+
+	/**
+	 * The page size for the slider, used to do a bigger step.
+	 */
+	readonly pageSize: number;
+
+	/** The orientation of the slider. */
+	readonly orientation: Orientation;
+
+	/** Whether the slider is disabled. */
+	readonly isDisabled: boolean;
+}
+
+const DEFAULT_MIN_VALUE = 0;
+const DEFAULT_MAX_VALUE = 100;
+const DEFAULT_STEP_VALUE = 1;
+
+export interface SliderStateOptions<T> extends SliderProps<T> {
+	numberFormatter: Intl.NumberFormat;
+}
+
+/**
+ * Provides state management for a slider component. Stores values for all thumbs,
+ * formats values for localization, and provides methods to update the position
+ * of any thumbs.
+ *
+ * @param props
+ */
+export function useSliderState<T extends number | number[]>(
+	props: SliderStateOptions<T>,
+): SliderState;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSliderState<T extends number | number[]>(
+	props: SliderStateOptions<T>,
+	slot: symbol | undefined,
+): SliderState;
+export function useSliderState(...args: any[]): SliderState {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSliderState');
+	const props = user[0] as SliderStateOptions<any>;
+
+	const {
+		isDisabled = false,
+		minValue = DEFAULT_MIN_VALUE,
+		maxValue = DEFAULT_MAX_VALUE,
+		numberFormatter: formatter,
+		step = DEFAULT_STEP_VALUE,
+		orientation = 'horizontal',
+	} = props;
+
+	// Page step should be at least equal to step and always a multiple of the step.
+	let pageSize = useMemo(
+		() => {
+			let calcPageSize = (maxValue - minValue) / 10;
+			calcPageSize = snapValueToStep(calcPageSize, 0, calcPageSize + step, step);
+			return Math.max(calcPageSize, step);
+		},
+		[step, maxValue, minValue],
+		subSlot(slot, 'pageSize'),
+	);
+
+	let restrictValues = useCallback(
+		(values: number[] | undefined) =>
+			values?.map((val, idx) => {
+				let min = idx === 0 ? minValue : values[idx - 1];
+				let max = idx === values.length - 1 ? maxValue : values[idx + 1];
+				return snapValueToStep(val, min, max, step);
+			}),
+		[minValue, maxValue, step],
+		subSlot(slot, 'restrict'),
+	);
+
+	let value = useMemo(
+		() => restrictValues(convertValue(props.value)),
+		[props.value, restrictValues],
+		subSlot(slot, 'value'),
+	);
+	let defaultValue = useMemo(
+		() => restrictValues(convertValue(props.defaultValue) ?? [minValue])!,
+		[props.defaultValue, minValue, restrictValues],
+		subSlot(slot, 'defaultValue'),
+	);
+	let onChange = createOnChange(props.value, props.defaultValue, props.onChange);
+	let onChangeEnd = createOnChange(props.value, props.defaultValue, props.onChangeEnd);
+
+	const [values, setValuesState] = useControlledState<number[]>(
+		value,
+		defaultValue,
+		onChange,
+		subSlot(slot, 'values'),
+	);
+	let [initialValues] = useState(values, subSlot(slot, 'initial'));
+	const [isDraggings, setDraggingsState] = useState<boolean[]>(
+		new Array(values.length).fill(false),
+		subSlot(slot, 'draggings'),
+	);
+	const isEditablesRef = useRef<boolean[]>(
+		new Array(values.length).fill(true),
+		subSlot(slot, 'editables'),
+	);
+	const [focusedIndex, setFocusedIndex] = useState<number | undefined>(
+		undefined,
+		subSlot(slot, 'focusedIndex'),
+	);
+
+	const valuesRef = useRef<number[]>(values, subSlot(slot, 'valuesRef'));
+	const isDraggingsRef = useRef<boolean[]>(isDraggings, subSlot(slot, 'draggingsRef'));
+
+	let setValues = (values: number[]) => {
+		valuesRef.current = values;
+		setValuesState(values);
+	};
+
+	let setDraggings = (draggings: boolean[]) => {
+		isDraggingsRef.current = draggings;
+		setDraggingsState(draggings);
+	};
+
+	function getValuePercent(value: number) {
+		return (value - minValue) / (maxValue - minValue);
+	}
+
+	function getThumbMinValue(index: number) {
+		return index === 0 ? minValue : values[index - 1];
+	}
+	function getThumbMaxValue(index: number) {
+		return index === values.length - 1 ? maxValue : values[index + 1];
+	}
+
+	function isThumbEditable(index: number) {
+		return isEditablesRef.current[index];
+	}
+
+	function setThumbEditable(index: number, editable: boolean) {
+		isEditablesRef.current[index] = editable;
+	}
+
+	function updateValue(index: number, value: number) {
+		if (isDisabled || !isThumbEditable(index)) {
+			return;
+		}
+		const thisMin = getThumbMinValue(index);
+		const thisMax = getThumbMaxValue(index);
+
+		// Round value to multiple of step, clamp value between min and max
+		value = snapValueToStep(value, thisMin, thisMax, step);
+		let newValues = replaceIndex(valuesRef.current, index, value);
+		setValues(newValues);
+	}
+
+	function updateDragging(index: number, dragging: boolean) {
+		if (isDisabled || !isThumbEditable(index)) {
+			return;
+		}
+		if (dragging) {
+			valuesRef.current = values;
+		}
+
+		const wasDragging = isDraggingsRef.current[index];
+		isDraggingsRef.current = replaceIndex(isDraggingsRef.current, index, dragging);
+		setDraggings(isDraggingsRef.current);
+
+		// Call onChangeEnd if no handles are dragging.
+		if (onChangeEnd && wasDragging && !isDraggingsRef.current.some(Boolean)) {
+			onChangeEnd(valuesRef.current);
+		}
+	}
+
+	let listFormatRef = useRef<Intl.ListFormat | null>(null, subSlot(slot, 'listFormat'));
+
+	function getFormattedValue(valueParam: number | number[] = values) {
+		if (typeof valueParam === 'number') {
+			valueParam = [valueParam];
+		}
+
+		switch (valueParam.length) {
+			case 0:
+				return '';
+			case 1:
+				return formatter.format(valueParam[0]);
+			case 2:
+				return formatter.formatRange(valueParam[0], valueParam[1]);
+			default: {
+				let formatted = valueParam.map((value) => formatter.format(value));
+				let listFormat = listFormatRef.current;
+				if (
+					!listFormat ||
+					listFormat.resolvedOptions().locale !== formatter.resolvedOptions().locale
+				) {
+					listFormat = listFormatRef.current = new Intl.ListFormat(
+						formatter.resolvedOptions().locale,
+						{ type: 'unit' },
+					);
+				}
+				return listFormat.format(formatted);
+			}
+		}
+	}
+
+	function setThumbPercent(index: number, percent: number) {
+		updateValue(index, getPercentValue(percent));
+	}
+
+	function getRoundedValue(value: number) {
+		return Math.round((value - minValue) / step) * step + minValue;
+	}
+
+	function getPercentValue(percent: number) {
+		const val = percent * (maxValue - minValue) + minValue;
+		return clamp(getRoundedValue(val), minValue, maxValue);
+	}
+
+	function incrementThumb(index: number, stepSize: number = 1) {
+		let s = Math.max(stepSize, step);
+		updateValue(index, snapValueToStep(values[index] + s, minValue, maxValue, step));
+	}
+
+	function decrementThumb(index: number, stepSize: number = 1) {
+		let s = Math.max(stepSize, step);
+		updateValue(index, snapValueToStep(values[index] - s, minValue, maxValue, step));
+	}
+
+	return {
+		values: values,
+		defaultValues: props.defaultValue !== undefined ? defaultValue : initialValues,
+		getThumbValue: (index: number) => values[index],
+		setThumbValue: updateValue,
+		setThumbPercent,
+		isThumbDragging: (index: number) => isDraggings[index],
+		setThumbDragging: updateDragging,
+		focusedThumb: focusedIndex,
+		setFocusedThumb: setFocusedIndex,
+		getThumbPercent: (index: number) => getValuePercent(values[index]),
+		getValuePercent,
+		getThumbValueLabel: (index: number) => getFormattedValue(values[index]),
+		getFormattedValue,
+		getThumbMinValue,
+		getThumbMaxValue,
+		getPercentValue,
+		isThumbEditable,
+		setThumbEditable,
+		incrementThumb,
+		decrementThumb,
+		step,
+		pageSize,
+		orientation,
+		isDisabled,
+	};
+}
+
+function replaceIndex<T>(array: T[], index: number, value: T) {
+	if (array[index] === value) {
+		return array;
+	}
+
+	return [...array.slice(0, index), value, ...array.slice(index + 1)];
+}
+
+function convertValue(value?: number | number[]) {
+	if (value == null) {
+		return undefined;
+	}
+
+	return Array.isArray(value) ? value : [value];
+}
+
+function createOnChange(value: any, defaultValue: any, onChange: any) {
+	return (newValue: number[]) => {
+		if (typeof value === 'number' || typeof defaultValue === 'number') {
+			onChange?.(newValue[0]);
+		} else {
+			onChange?.(newValue);
+		}
+	};
+}