@funstack/ui 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/slider/slider-root.mjs

@@ -0,0 +1,582 @@
+"use client";
+import { createActionDetails } from "../internal/action-details.mjs";
+import { dataAttr } from "../internal/data-attr.mjs";
+import { transitionTypes } from "../internal/transition-types.mjs";
+import { useLatest } from "../internal/use-latest.mjs";
+import { useControllableAction } from "../internal/use-controllable-action.mjs";
+import { mergeTokenLists } from "../internal/merge-props.mjs";
+import { resolveStateValue, useRender } from "../internal/use-render.mjs";
+import { useDevWarning } from "../internal/use-dev-warning.mjs";
+import { FieldContext } from "../internal/field-context.mjs";
+import { useFieldControl, useFieldValueChange, useMergedRef } from "../internal/use-field-control.mjs";
+import { useActionTrigger } from "../internal/use-action-trigger.mjs";
+import { useNativeGroupReconciliation } from "../internal/use-native-group-reconciliation.mjs";
+import { SliderContext } from "./slider-context.mjs";
+import { clampToNeighbours, equalValues, isMaxReachable, isOnGrid, nearestThumb, percent, platformDefault, sanitize } from "./slider-arithmetic.mjs";
+import { addTransitionType, use, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/slider/slider-root.tsx
+const isDev = process.env.NODE_ENV !== "production";
+const STEP_TYPES = transitionTypes("slider", "change");
+const COMMIT_TYPES = transitionTypes("slider", "commit");
+function toArray(value) {
+	return typeof value === "number" ? [value] : value;
+}
+function shapeOf(value) {
+	if (value === void 0) return void 0;
+	return typeof value === "number" ? "number" : "array";
+}
+function replaceAt(values, index, value) {
+	return values.map((v, i) => i === index ? value : v);
+}
+/** Writes each registered input's `defaultValue` (the attribute a form reset restores). */
+function writeDefaults(registry, target) {
+	for (const [index, input] of registry) {
+		const entry = target[index];
+		if (entry !== void 0) input.defaultValue = String(entry);
+	}
+}
+/**
+* Owns the slider's state (design/components/slider.md 2): the committed value through
+* `useControllableAction` with `valueCommitAction` (once per gesture), each step through its own
+* transition (`valueChangeAction`), and the value a gesture has reached in the urgent lane
+* (`live`), which the thumbs show while a pointer is captured or anything is in flight. Also the
+* pointer gesture, the Thumb registry, mount reconciliation and form reset, and the geometry
+* custom properties `--slider-start`, `--slider-end` and `--slider-value-<i>`.
+*
+* Owned keys (conventions 1.2): `role` (`"group"` with several thumbs), `aria-labelledby` (the
+* Label's id while a Label is mounted and there are several thumbs; token-merged with the
+* consumer's), `data-pending`, `data-dragging`, `data-orientation`, `data-disabled`. The custom
+* properties are merged into `style`, where the consumer's entries win.
+*
+* Inside a `Field.Root` (design 9.4) the Root calls `useFieldControl`: with one thumb, Thumb 0's
+* input is the Field's labelable control; with several, the Root registers itself as the group
+* and also owns the Field label in `aria-labelledby`, the Field's `aria-describedby` and
+* `data-invalid`. `name` / `disabled` default from the Field.
+*/
+function SliderRootImpl(props) {
+	const { value, defaultValue, valueChangeAction, valueCommitAction, min = 0, max = 100, step: stepProp = 1, minStepsBetweenThumbs = 0, orientation = "horizontal", getAriaValueText, name: nameProp, form, disabled: disabledProp = false, className, style, children, render, ...rest } = props;
+	const stepValid = Number.isFinite(stepProp) && stepProp > 0;
+	const step = stepValid ? stepProp : 1;
+	const gap = Math.max(0, minStepsBetweenThumbs) * step;
+	const id = useId();
+	const labelId = `${id}-label`;
+	const [shape] = useState(() => shapeOf(value ?? defaultValue) ?? "number");
+	const fromArray = useCallback((values) => shape === "number" ? values[0] : values, [shape]);
+	const [live, setLive] = useState(null);
+	const [gestureThumb, setGestureThumb] = useState(null);
+	/**
+	* A step was taken and its gesture's commit has not been dispatched yet. Holds `live` on
+	* screen between a key's native `input` and `change` when no step transition runs (no
+	* `valueChangeAction`): otherwise react-dom restores the controlled input to the old value
+	* after `input`, and Firefox then fires no `change`.
+	*/
+	const [stepHeld, setStepHeld] = useState(false);
+	const [pendingThumb, setPendingThumb] = useState(null);
+	/** The value of the latest step, read by the commit in the same or a later event. */
+	const liveRef = useRef(null);
+	/** The shown value when the open gesture began; `null` when no gesture is open. */
+	const gestureStart = useRef(null);
+	const activeGesture = useRef(null);
+	const commitSeq = useRef(0);
+	const trackRef = useRef(null);
+	const runCommit = async (next, details) => {
+		const seq = ++commitSeq.current;
+		try {
+			await valueCommitAction?.(next, details);
+		} catch (error) {
+			if (value === void 0 && seq === commitSeq.current) {
+				await void 0;
+				stepTo(toArray(committedRef.current), null, "dismiss", void 0);
+			}
+			throw error;
+		}
+	};
+	const commitState = useControllableAction({
+		controlled: value,
+		defaultValue,
+		initialValue: platformDefault(min, max, step),
+		action: runCommit,
+		transitionTypes: () => COMMIT_TYPES,
+		warn: {
+			component: "Slider.Root",
+			prop: "value"
+		}
+	});
+	const { optimistic, committed, dispatch } = commitState;
+	const committedRef = useLatest(committed);
+	const { pending: stepPending, run: runStep } = useActionTrigger();
+	const optimisticValues = useMemo(() => toArray(optimistic), [optimistic]);
+	const shown = (gestureThumb !== null || stepHeld || stepPending || commitState.pending) && live !== null ? live : optimisticValues;
+	const pending = stepPending || commitState.pending;
+	const thumbCount = shown.length;
+	const field = useFieldControl({
+		labelable: thumbCount === 1,
+		name: nameProp,
+		disabled: disabledProp,
+		component: "Slider.Root"
+	});
+	const fieldName = use(FieldContext)?.name;
+	const name = field.name;
+	const disabled = field.disabled;
+	const fieldId = field.id;
+	const thumbId = useCallback((index) => index === 0 && fieldId !== void 0 ? fieldId : `${id}-thumb-${index}`, [id, fieldId]);
+	const rootRef = useMergedRef(void 0, thumbCount > 1 ? field.ref : void 0);
+	useDevWarning(field.inField && field.required, "Slider.Root: a range is never empty, so `required` on the enclosing Field.Root has no effect on the slider.");
+	/**
+	* The reason of the latest change the user or the platform made, consumed by the Field
+	* notification below: `"activate"` dismisses a shown server error, a rollback does not.
+	*/
+	const lastReason = useRef(null);
+	useFieldValueChange(optimisticValues.join("\0"), () => {
+		const edit = lastReason.current === "activate";
+		lastReason.current = null;
+		return edit;
+	});
+	const { "aria-labelledby": fieldLabelledBy, "aria-describedby": fieldDescribedBy, "aria-invalid": fieldInvalid, "data-invalid": fieldDataInvalid } = field.attributes;
+	const inField = field.inField;
+	const fieldRef = field.ref;
+	const fieldWiring = useMemo(() => {
+		if (!inField) return null;
+		const single = thumbCount === 1;
+		return {
+			inputRef: single ? fieldRef : void 0,
+			describedBy: single ? fieldDescribedBy : void 0,
+			invalid: fieldInvalid,
+			dataInvalid: fieldDataInvalid,
+			name: fieldName
+		};
+	}, [
+		inField,
+		fieldRef,
+		thumbCount,
+		fieldDescribedBy,
+		fieldInvalid,
+		fieldDataInvalid,
+		fieldName
+	]);
+	/** What the thumbs show, for handlers; also written by `stepTo` ahead of the render. */
+	const shownRef = useLatest(shown);
+	const latest = useLatest({
+		valueChangeAction,
+		fromArray,
+		runStep,
+		min,
+		max,
+		step,
+		gap,
+		orientation,
+		disabled
+	});
+	const stepTo = useCallback((next, thumb, reason, event) => {
+		if (equalValues(next, shownRef.current)) return false;
+		liveRef.current = next;
+		shownRef.current = next;
+		lastReason.current = reason;
+		setLive(next);
+		setPendingThumb(thumb);
+		if (reason !== "dismiss") setStepHeld(true);
+		const { valueChangeAction: action, fromArray: toValue, runStep: run } = latest.current;
+		if (action === void 0) return true;
+		run(() => {
+			for (const type of STEP_TYPES) addTransitionType(type);
+			return action?.(toValue(next), createActionDetails(event, {
+				reason,
+				thumb
+			}));
+		});
+		return true;
+	}, [latest, shownRef]);
+	const commitGesture = useCallback((thumb, reason, event) => {
+		const start = gestureStart.current;
+		gestureStart.current = null;
+		setStepHeld(false);
+		const next = liveRef.current;
+		if (start === null || next === null || equalValues(next, start)) return;
+		lastReason.current = reason;
+		setPendingThumb(thumb);
+		dispatch(latest.current.fromArray(next), createActionDetails(event, {
+			reason,
+			thumb
+		}));
+	}, [dispatch, latest]);
+	const [registry] = useState(() => /* @__PURE__ */ new Map());
+	const warnedDuplicate = useRef(false);
+	const warnedForm = useRef(false);
+	const registerThumb = useCallback((index, input) => {
+		const existing = registry.get(index);
+		if (isDev && existing !== void 0 && existing !== input && !warnedDuplicate.current) {
+			warnedDuplicate.current = true;
+			console.error(`Slider.Thumb: two Thumbs have \`index={${index}}\`. Each value needs exactly one Thumb; give every Thumb a distinct index.`);
+		}
+		if (isDev && !warnedForm.current) {
+			for (const other of registry.values()) if (other !== input && other.form !== input.form) {
+				warnedForm.current = true;
+				console.error("Slider.Thumb: the thumbs of one Slider belong to different forms (a Thumb's `form` prop). A form reset is followed through the first thumb's form only; keep every thumb in one form.");
+				break;
+			}
+		}
+		registry.set(index, input);
+		return () => {
+			if (registry.get(index) === input) registry.delete(index);
+		};
+	}, [registry]);
+	/** The first registered input: the form-associated element the reset subscription follows. */
+	const formElement = useMemo(() => ({
+		get current() {
+			let first = null;
+			let firstIndex = Number.POSITIVE_INFINITY;
+			for (const [index, input] of registry) if (index < firstIndex) {
+				firstIndex = index;
+				first = input;
+			}
+			return first;
+		},
+		set current(_ignored) {}
+	}), [registry]);
+	const [labelCount, setLabelCount] = useState(0);
+	const labelCountRef = useRef(0);
+	const registerLabel = useCallback(() => {
+		labelCountRef.current += 1;
+		setLabelCount((count) => count + 1);
+		return () => {
+			labelCountRef.current -= 1;
+			setLabelCount((count) => count - 1);
+		};
+	}, []);
+	const [mountValue] = useState(value);
+	const resetTarget = () => value !== void 0 ? toArray(mountValue ?? value) : toArray(defaultValue ?? platformDefault(min, max, step));
+	const readCurrent = () => shownRef.current.map((v, index) => {
+		const input = registry.get(index);
+		if (input === void 0) return v;
+		const read = Number(input.value);
+		return Number.isFinite(read) ? read : v;
+	});
+	const { onItemMounted } = useNativeGroupReconciliation({
+		element: formElement,
+		readCurrent,
+		readDefault: resetTarget,
+		base: () => shownRef.current,
+		equals: (a, b) => {
+			const reference = shownRef.current;
+			return equalValues(sanitize(a, reference, min, max, step, gap), sanitize(b, reference, min, max, step, gap));
+		},
+		onPlatformChange: (next, event) => {
+			if (next.length !== shownRef.current.length) return;
+			const before = shownRef.current;
+			gestureStart.current = before;
+			liveRef.current = before;
+			stepTo(next, null, "platform", event);
+			commitGesture(null, "platform", event);
+		},
+		onResetEvent: () => {
+			writeDefaults(registry, resetTarget());
+		}
+	});
+	const inputStep = useCallback((index, raw, event) => {
+		if (!Number.isFinite(raw)) return;
+		const before = shownRef.current;
+		if (index >= before.length) return;
+		if (stepTo(replaceAt(before, index, raw), index, "activate", event)) {
+			if (gestureStart.current === null) gestureStart.current = before;
+		}
+	}, [shownRef, stepTo]);
+	const inputCommit = useCallback((index, event) => {
+		if (activeGesture.current !== null) return;
+		commitGesture(index, "activate", event);
+	}, [commitGesture]);
+	const inputKeyDown = useCallback((index, event) => {
+		const { orientation: axis, disabled: off, min: lo, max: hi, step: inc, gap: g } = latest.current;
+		if (off) return;
+		if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
+		if (event.altKey || event.ctrlKey || event.metaKey) return;
+		let increaseKey;
+		if (axis === "vertical") increaseKey = "ArrowRight";
+		else {
+			const input = event.currentTarget;
+			if (input === null || getComputedStyle(input).direction !== "rtl") return;
+			increaseKey = "ArrowLeft";
+		}
+		event.preventDefault();
+		const before = shownRef.current;
+		const current = before[index];
+		if (current === void 0) return;
+		const delta = event.key === increaseKey ? inc : -inc;
+		const next = replaceAt(before, index, clampToNeighbours(before, index, current + delta, lo, hi, inc, g));
+		if (activeGesture.current !== null) {
+			stepTo(next, index, "activate", event);
+			return;
+		}
+		gestureStart.current = before;
+		liveRef.current = before;
+		stepTo(next, index, "activate", event);
+		commitGesture(index, "activate", event);
+	}, [
+		commitGesture,
+		latest,
+		shownRef,
+		stepTo
+	]);
+	const warnedNoTrack = useRef(false);
+	const beginGesture = useCallback((index, event, element) => {
+		const { disabled: off } = latest.current;
+		if (off || event.button !== 0 || activeGesture.current !== null) return;
+		const track = trackRef.current;
+		if (track === null) {
+			if (isDev && !warnedNoTrack.current) {
+				warnedNoTrack.current = true;
+				console.error("Slider.Thumb: a pointer press needs a Slider.Track to map the pointer to a value. Without a Track the slider is keyboard-only.");
+			}
+			return;
+		}
+		event.preventDefault();
+		const rtl = getComputedStyle(track).direction === "rtl";
+		const valueAt = (clientX, clientY) => {
+			const { min: lo, max: hi, orientation: axis } = latest.current;
+			const rect = (trackRef.current ?? track).getBoundingClientRect();
+			let fraction;
+			if (axis === "vertical") fraction = rect.height > 0 ? (rect.bottom - clientY) / rect.height : 0;
+			else {
+				fraction = rect.width > 0 ? (clientX - rect.left) / rect.width : 0;
+				if (rtl) fraction = 1 - fraction;
+			}
+			fraction = Math.min(1, Math.max(0, fraction));
+			return lo + fraction * (hi - lo);
+		};
+		const moveTo = (thumb, raw, cause) => {
+			const { min: lo, max: hi, step: inc, gap: g } = latest.current;
+			const before = shownRef.current;
+			if (thumb >= before.length) return;
+			stepTo(replaceAt(before, thumb, clampToNeighbours(before, thumb, raw, lo, hi, inc, g)), thumb, "activate", cause);
+		};
+		const start = valueAt(event.clientX, event.clientY);
+		const startValues = shownRef.current;
+		let tied = null;
+		if (index !== null) {
+			const at = startValues[index];
+			if (at !== void 0) {
+				let first = index;
+				let last = index;
+				while (first > 0 && equalValues([startValues[first - 1]], [at])) first -= 1;
+				while (last < startValues.length - 1 && equalValues([startValues[last + 1]], [at])) last += 1;
+				if (first !== last) tied = {
+					first,
+					last,
+					at
+				};
+			}
+		}
+		const resolveTie = (raw) => {
+			if (tied === null) return null;
+			if (raw > tied.at) return tied.last;
+			if (raw < tied.at) return tied.first;
+			return null;
+		};
+		/** The thumb the gesture moves; `null` while a press on stacked thumbs is undecided. */
+		let decided = index === null ? nearestThumb(startValues, start) : tied ? resolveTie(start) : index;
+		/** The thumb shown as dragging and focused meanwhile. */
+		let thumb = decided ?? index ?? 0;
+		const pointerId = event.pointerId;
+		try {
+			element.setPointerCapture(pointerId);
+		} catch {}
+		const decide = (raw) => {
+			if (decided !== null) return true;
+			decided = resolveTie(raw);
+			if (decided === null) return false;
+			if (decided !== thumb) {
+				thumb = decided;
+				setGestureThumb(thumb);
+				registry.get(thumb)?.focus({ focusVisible: false });
+			}
+			return true;
+		};
+		const follow = (pointerEvent) => {
+			const raw = valueAt(pointerEvent.clientX, pointerEvent.clientY);
+			if (decide(raw)) moveTo(thumb, raw, pointerEvent);
+		};
+		const onMove = (moveEvent) => {
+			if (moveEvent.pointerId !== pointerId) return;
+			follow(moveEvent);
+		};
+		const onEnd = (endEvent) => {
+			if (endEvent.pointerId !== pointerId) return;
+			detach();
+			if (endEvent.type === "pointerup") follow(endEvent);
+			activeGesture.current = null;
+			setGestureThumb(null);
+			commitGesture(thumb, "activate", endEvent);
+		};
+		const detach = () => {
+			element.removeEventListener("pointermove", onMove);
+			element.removeEventListener("pointerup", onEnd);
+			element.removeEventListener("pointercancel", onEnd);
+			element.removeEventListener("lostpointercapture", onEnd);
+		};
+		element.addEventListener("pointermove", onMove);
+		element.addEventListener("pointerup", onEnd);
+		element.addEventListener("pointercancel", onEnd);
+		element.addEventListener("lostpointercapture", onEnd);
+		activeGesture.current = {
+			pointerId,
+			detach
+		};
+		setGestureThumb(thumb);
+		gestureStart.current = shownRef.current;
+		liveRef.current = shownRef.current;
+		setLive(shownRef.current);
+		registry.get(thumb)?.focus({ focusVisible: false });
+		if (decided !== null) moveTo(thumb, start, event);
+	}, [
+		commitGesture,
+		latest,
+		registry,
+		shownRef,
+		stepTo
+	]);
+	useEffect(() => () => {
+		activeGesture.current?.detach();
+		activeGesture.current = null;
+	}, []);
+	useDevWarning(!stepValid, `Slider.Root: \`step\` must be a positive number (got ${String(stepProp)}); using 1.`);
+	useDevWarning(stepValid && !isMaxReachable(min, max, step), `Slider.Root: \`max\` (${max}) is not on the step grid from \`min\` (${min}) with \`step\` ${step}: it is unreachable, as on a native range. The last reachable value is the last step below \`max\`.`);
+	const given = value ?? defaultValue;
+	const givenValues = given === void 0 ? [] : toArray(given);
+	useDevWarning(givenValues.some((v) => !isOnGrid(v, min, max, step)), `Slider.Root: the ${value !== void 0 ? "`value`" : "`defaultValue`"} (${givenValues.join(", ")}) is off the step grid or outside \`min\` / \`max\`. It is rendered as given and the browser sanitises it; the first user step snaps it.`);
+	useDevWarning(givenValues.some((v, i) => i > 0 && v < givenValues[i - 1]), `Slider.Root: the values (${givenValues.join(", ")}) must be in ascending order; the thumbs would be rendered crossed.`);
+	const currentShape = shapeOf(given);
+	useDevWarning(currentShape !== void 0 && currentShape !== shape, "Slider.Root: the value changed shape between a number and an array after mount. The shape is fixed at mount; remount the Slider (a `key`) to change the number of thumbs.");
+	const unnamedGroup = shown.length > 1 && !inField && rest["aria-label"] === void 0 && rest["aria-labelledby"] === void 0;
+	const warnedGroupName = useRef(false);
+	useEffect(() => {
+		if (!isDev || warnedGroupName.current || !unnamedGroup || labelCountRef.current > 0) return;
+		warnedGroupName.current = true;
+		console.error("Slider.Root: a slider with several thumbs is a `group` and needs a name: render a Slider.Label, or pass `aria-label` / `aria-labelledby` to the Root.");
+	}, [unnamedGroup]);
+	const count = shown.length;
+	const percents = shown.map((v) => percent(v, min, max));
+	const geometry = {
+		"--slider-start": count > 1 ? `${percents[0] ?? 0}%` : "0%",
+		"--slider-end": `${percents[count - 1] ?? 0}%`
+	};
+	percents.forEach((p, index) => {
+		geometry[`--slider-value-${index}`] = `${p}%`;
+	});
+	const shownValue = fromArray(shown);
+	const dragging = gestureThumb !== null;
+	const state = useMemo(() => ({
+		value: shownValue,
+		values: shown,
+		pending,
+		dragging,
+		orientation,
+		disabled,
+		min,
+		max,
+		step
+	}), [
+		shownValue,
+		shown,
+		pending,
+		dragging,
+		orientation,
+		disabled,
+		min,
+		max,
+		step
+	]);
+	const context = useMemo(() => ({
+		state,
+		shown,
+		shownValue,
+		min,
+		max,
+		step,
+		gap,
+		orientation,
+		disabled,
+		pending,
+		draggingThumb: gestureThumb,
+		pendingThumb,
+		name,
+		form,
+		getAriaValueText,
+		labelId,
+		thumbId,
+		trackRef,
+		inputStep,
+		inputCommit,
+		inputKeyDown,
+		beginGesture,
+		registerThumb,
+		registerLabel,
+		onItemMounted,
+		field: fieldWiring
+	}), [
+		state,
+		shown,
+		shownValue,
+		min,
+		max,
+		step,
+		gap,
+		orientation,
+		disabled,
+		pending,
+		gestureThumb,
+		pendingThumb,
+		name,
+		form,
+		getAriaValueText,
+		labelId,
+		thumbId,
+		inputStep,
+		inputCommit,
+		inputKeyDown,
+		beginGesture,
+		registerThumb,
+		registerLabel,
+		onItemMounted,
+		fieldWiring
+	]);
+	const labelledBy = count > 1 ? mergeTokenLists(fieldLabelledBy, labelCount > 0 ? labelId : void 0) : "";
+	const libraryProps = {
+		role: count > 1 ? "group" : void 0,
+		...labelledBy !== "" ? { "aria-labelledby": labelledBy } : {},
+		...count > 1 && fieldDescribedBy !== void 0 ? { "aria-describedby": fieldDescribedBy } : {},
+		...inField ? { "data-invalid": fieldDataInvalid } : {},
+		"data-pending": dataAttr(pending),
+		"data-dragging": dataAttr(dragging),
+		"data-orientation": orientation,
+		"data-disabled": dataAttr(disabled)
+	};
+	const element = useRender({
+		defaultElement: "div",
+		render,
+		state,
+		className,
+		style: (s) => ({
+			...geometry,
+			...resolveStateValue(style, s)
+		}),
+		children,
+		props: rest,
+		libraryProps,
+		ref: rootRef
+	});
+	return /* @__PURE__ */ jsx(SliderContext, {
+		value: context,
+		children: element
+	});
+}
+SliderRootImpl.displayName = "SliderRoot";
+/**
+* `Slider.Root`. Overloaded so that the value's shape is inferred from `value` / `defaultValue`
+* as `number` or `readonly number[]` (an array literal would otherwise infer a mutable
+* `number[]`), and every action and state function receives that shape (design 3.1).
+*/
+const SliderRoot = SliderRootImpl;
+//#endregion
+export { SliderRoot };
+
+//# sourceMappingURL=slider-root.mjs.map