ropav 0.2.0 → 0.3.0

package/dist/composables/use-number-field.js

@@ -0,0 +1,371 @@
+import { useId as useId$1 } from "./use-id.js";
+import { isAndroid, isIOS, isIPhone } from "../utils/platform.js";
+import { useFieldIds } from "./use-field-ids.js";
+import { useLocale } from "./use-locale.js";
+import { useFormReset } from "./use-form-reset.js";
+import { announce } from "../utils/live-announcer.js";
+import { setFormValue } from "../utils/form-value.js";
+import { useNumberFieldState } from "./use-number-field-state.js";
+import { useFormattedTextField } from "./use-formatted-text-field.js";
+import { useScrollWheel } from "./use-scroll-wheel.js";
+import { useSpinButton } from "./use-spin-button.js";
+import { computed, nextTick, shallowRef, toValue, watch } from "vue";
+import { NumberFormatter } from "@internationalized/number";
+//#region src/composables/use-number-field.ts
+/** A number input kept off-document, used only to borrow the browser's range validation. */
+var rangeProbe = null;
+/**
+* Behaviour and accessibility for a number field, ported from React Aria's
+* `packages/react-aria/src/numberfield/useNumberField.ts` (react-aria 3.51.0).
+*
+* The visible control is a plain text input, not `type="number"`: a number input cannot hold a
+* currency symbol, a percent sign or grouping separators, and the field's whole point is that it
+* can. Everything a number input would have given for free is put back by hand — the spin button
+* semantics, the software keyboard choice, and range validation, which is borrowed from a real
+* number input kept off-document so the browser's own message is what the user reads.
+*
+* @example
+* ```ts
+* const field = useNumberField({value: () => props.value, step: () => props.step});
+* ```
+*/
+var useNumberField = (options = {}) => {
+	const element = shallowRef(null);
+	const registerElement = (next) => {
+		element.value = next;
+	};
+	const state = options.state ?? useNumberFieldState(options);
+	const inputId = useId$1(() => toValue(options.id));
+	const incrementId = useId$1();
+	const decrementId = useId$1();
+	const isDisabled = computed(() => Boolean(toValue(options.isDisabled)));
+	const isReadOnly = computed(() => Boolean(toValue(options.isReadOnly)));
+	const isRequired = computed(() => Boolean(toValue(options.isRequired)));
+	const isInvalid = computed(() => state.displayValidation.value.isInvalid);
+	const { context: fieldIds, describedBy, labelId } = useFieldIds({
+		labelFor: inputId,
+		slots: [
+			"label",
+			"description",
+			"errorMessage"
+		]
+	});
+	const formatOptions = computed(() => toValue(options.formatOptions));
+	const resolvedLocale = useLocale();
+	const locale = computed(() => toValue(options.locale) ?? resolvedLocale.value.locale);
+	/**
+	* How the value is read out, which is not always how it is written.
+	*
+	* Accounting notation writes a negative amount in brackets, and a screen reader has no way to
+	* say that. The announced text drops the notation so the minus sign is there to be read.
+	*/
+	const textValue = computed(() => {
+		if (Number.isNaN(state.numberValue.value)) return "";
+		return new NumberFormatter(locale.value, {
+			...formatOptions.value,
+			currencySign: void 0
+		}).format(state.numberValue.value);
+	});
+	const spin = useSpinButton({
+		isDisabled,
+		isReadOnly,
+		isRequired,
+		maxValue: state.maxValue,
+		minValue: state.minValue,
+		onDecrement: state.decrement,
+		onDecrementToMin: state.decrementToMin,
+		onIncrement: state.increment,
+		onIncrementToMax: state.incrementToMax,
+		textValue,
+		value: state.numberValue
+	});
+	const reassert = () => {
+		setFormValue(element.value, state.inputValue.value);
+	};
+	watch([element, state.inputValue], reassert, {
+		flush: "post",
+		immediate: true
+	});
+	/**
+	* Normalise the text and say what it became.
+	*
+	* The announcement is conditional on the text actually changing, which is what keeps a screen
+	* reader from repeating the same amount every time focus leaves the field.
+	*/
+	const commitAndAnnounce = () => {
+		const before = element.value?.value ?? "";
+		state.commit();
+		reassert();
+		const after = element.value?.value ?? "";
+		if (after !== before) announce(after);
+	};
+	const isFocusWithinState = shallowRef(false);
+	const isFocusWithin = computed(() => isFocusWithinState.value);
+	const onFocusin = () => {
+		if (isDisabled.value) return;
+		isFocusWithinState.value = true;
+	};
+	const onFocusout = (event) => {
+		const currentTarget = event.currentTarget;
+		const next = event.relatedTarget;
+		if (currentTarget && next && currentTarget.contains(next)) return;
+		isFocusWithinState.value = false;
+	};
+	/**
+	* The wheel steps the value, but only while focus is inside and only for a mostly-vertical
+	* gesture: a trackpad reports both axes at once, and a sideways scroll past the field is not
+	* someone asking to change the number.
+	*/
+	useScrollWheel(element, {
+		isDisabled: () => Boolean(toValue(options.isWheelDisabled)) || isDisabled.value || isReadOnly.value || !isFocusWithin.value,
+		onScroll: ({ deltaX, deltaY }) => {
+			if (Math.abs(deltaY) <= Math.abs(deltaX)) return;
+			if (deltaY > 0) state.increment();
+			else if (deltaY < 0) state.decrement();
+		}
+	});
+	useFormattedTextField(element, {
+		setInputValue: state.setInputValue,
+		validate: state.validate
+	});
+	useFormReset(element, () => state.defaultNumberValue.value, (value) => {
+		state.setNumberValue(value);
+		nextTick(reassert);
+	});
+	/**
+	* Range validation borrowed from a real number input.
+	*
+	* The point is the message: a browser writes "Value must be less than or equal to 10" in the
+	* user's own language, and reimplementing that would mean shipping translations for something
+	* the platform already has. A detached `type="number"` input is given the same min, max, step
+	* and value, and its verdict is merged with the visible input's own.
+	*
+	* Only under `"validate"` commit behaviour — under `"snap"` the value is pulled into range on
+	* commit, so there is nothing out of range left to complain about.
+	*/
+	watch([
+		element,
+		() => toValue(options.commitBehavior),
+		state.minValue,
+		state.maxValue,
+		() => toValue(options.step),
+		state.numberValue,
+		state.inputValue
+	], () => {
+		const input = element.value;
+		if (toValue(options.commitBehavior) !== "validate") return;
+		if (state.realtimeValidation.value.isInvalid) return;
+		if (!input || input.disabled) return;
+		if (!rangeProbe && typeof document !== "undefined") {
+			rangeProbe = document.createElement("input");
+			rangeProbe.type = "number";
+		}
+		if (!rangeProbe) return;
+		const min = state.minValue.value;
+		const max = state.maxValue.value;
+		const step = toValue(options.step);
+		const value = state.numberValue.value;
+		rangeProbe.min = min != null && !Number.isNaN(min) ? String(min) : "";
+		rangeProbe.max = max != null && !Number.isNaN(max) ? String(max) : "";
+		rangeProbe.step = step != null && !Number.isNaN(step) ? String(step) : "";
+		rangeProbe.value = value != null && !Number.isNaN(value) ? String(value) : "";
+		const valid = input.validity.valid && rangeProbe.validity.valid;
+		const message = input.validationMessage || rangeProbe.validationMessage;
+		state.updateValidation({
+			isInvalid: !valid,
+			validationDetails: {
+				badInput: input.validity.badInput,
+				customError: input.validity.customError,
+				patternMismatch: input.validity.patternMismatch,
+				rangeOverflow: rangeProbe.validity.rangeOverflow,
+				rangeUnderflow: rangeProbe.validity.rangeUnderflow,
+				stepMismatch: rangeProbe.validity.stepMismatch,
+				tooLong: input.validity.tooLong,
+				tooShort: input.validity.tooShort,
+				typeMismatch: input.validity.typeMismatch,
+				valid,
+				valueMissing: input.validity.valueMissing
+			},
+			validationErrors: message ? [message] : []
+		});
+		if (state.validationBehavior.value === "native" && !rangeProbe.validity.valid) input.setCustomValidity(rangeProbe.validationMessage);
+	}, {
+		flush: "post",
+		immediate: true
+	});
+	/**
+	* Which software keyboard a touch device offers.
+	*
+	* There is no way to ask for "a number pad with both a minus and a decimal point"; each
+	* platform leaves out something different, so the mode is chosen by what the field actually
+	* needs. An iPhone has no minus in either numeric or decimal, so a field that accepts negative
+	* numbers has to fall back to the full keyboard.
+	*/
+	const inputMode = computed(() => {
+		const hasDecimals = (new NumberFormatter(locale.value, formatOptions.value).resolvedOptions().maximumFractionDigits ?? 0) > 0;
+		const min = state.minValue.value;
+		const hasNegative = min === void 0 || Number.isNaN(min) || min < 0;
+		if (isIPhone()) {
+			if (hasNegative) return "text";
+			if (hasDecimals) return "decimal";
+			return "numeric";
+		}
+		if (isAndroid()) {
+			if (hasNegative) return "numeric";
+			if (hasDecimals) return "decimal";
+		}
+		return "numeric";
+	});
+	const onInput = (event) => {
+		const input = event.target;
+		if (!input) return;
+		if (state.validate(input.value)) {
+			state.setInputValue(input.value);
+			return;
+		}
+		reassert();
+	};
+	const onKeydown = (event) => {
+		if (!isDisabled.value && !isReadOnly.value && event.key === "Enter") {
+			state.commit();
+			reassert();
+			state.commitValidation();
+		}
+		spin.onKeydown(event);
+		options.onKeydown?.(event);
+	};
+	const onKeyup = (event) => {
+		options.onKeyup?.(event);
+	};
+	const onFocus = (event) => {
+		spin.onFocus();
+		onFocusin();
+		options.onFocusChange?.(true);
+	};
+	const onBlur = (event) => {
+		spin.onBlur();
+		commitAndAnnounce();
+		options.onFocusChange?.(false);
+	};
+	/**
+	* Paste is handled only when it replaces the whole field.
+	*
+	* Anything else would mean working out what the pasted text does to the string around it, and
+	* where the caret ends up in the result — which is where this kind of code goes wrong. A
+	* partial paste is left to `beforeinput`, which already refuses what cannot be a number.
+	*/
+	const onPaste = (event) => {
+		const input = event.target;
+		if (!input) return;
+		if ((input.selectionEnd ?? -1) - (input.selectionStart ?? 0) !== input.value.length) return;
+		event.preventDefault();
+		state.commit(event.clipboardData?.getData("text/plain")?.trim() ?? "");
+		reassert();
+	};
+	const fieldLabel = computed(() => toValue(options.ariaLabel) ?? "");
+	/**
+	* What the stepper buttons point at for their name.
+	*
+	* With a name of its own the field puts it straight into the button's label, which leaves a
+	* translator free to word "Increase X" however the language wants. Only when the name lives in
+	* another element does the button fall back to a chain of ids.
+	*/
+	const stepperLabelledby = computed(() => {
+		if (fieldLabel.value) return void 0;
+		return labelId.value ?? toValue(options.ariaLabelledby);
+	});
+	const stepperAttrs = (kind, ownId, override) => computed(() => {
+		const verb = kind === "increment" ? "Increase" : "Decrease";
+		const custom = override();
+		const chain = stepperLabelledby.value;
+		const all = {
+			"aria-controls": inputId.value,
+			"aria-label": custom ?? (fieldLabel.value ? verb + " " + fieldLabel.value : verb),
+			"aria-labelledby": chain && !custom ? ownId.value + " " + chain : void 0,
+			id: chain && !custom ? ownId.value : void 0,
+			tabindex: -1
+		};
+		for (const key of Object.keys(all)) if (all[key] === void 0) delete all[key];
+		return all;
+	});
+	const increment = {
+		attrs: stepperAttrs("increment", incrementId, () => toValue(options.incrementAriaLabel)),
+		handlers: spin.increment,
+		isDisabled: computed(() => !state.canIncrement.value)
+	};
+	const decrement = {
+		attrs: stepperAttrs("decrement", decrementId, () => toValue(options.decrementAriaLabel)),
+		handlers: spin.decrement,
+		isDisabled: computed(() => !state.canDecrement.value)
+	};
+	const isNativeBehavior = computed(() => state.validationBehavior.value === "native");
+	const resolvedLabelledby = computed(() => {
+		const own = [labelId.value, toValue(options.ariaLabelledby)].filter(Boolean).join(" ");
+		if (!own) return void 0;
+		return toValue(options.ariaLabel) ? [inputId.value, own].join(" ") : own;
+	});
+	const resolvedDescribedby = computed(() => {
+		const ids = [describedBy.value, toValue(options.ariaDescribedby)].filter(Boolean);
+		return ids.length > 0 ? ids.join(" ") : void 0;
+	});
+	const attrs = computed(() => {
+		const all = {
+			"aria-describedby": resolvedDescribedby.value,
+			"aria-disabled": isDisabled.value || void 0,
+			"aria-invalid": isInvalid.value || void 0,
+			"aria-label": toValue(options.ariaLabel),
+			"aria-labelledby": resolvedLabelledby.value,
+			"aria-readonly": isReadOnly.value || void 0,
+			"aria-required": isRequired.value && !isNativeBehavior.value || void 0,
+			"aria-roledescription": isIOS() ? void 0 : "Number field",
+			autocomplete: "off",
+			autocorrect: "off",
+			disabled: isDisabled.value || void 0,
+			id: inputId.value,
+			inputmode: inputMode.value,
+			readonly: isReadOnly.value || void 0,
+			required: isRequired.value && isNativeBehavior.value || void 0,
+			spellcheck: "false",
+			tabindex: isDisabled.value ? void 0 : 0,
+			type: "text",
+			value: state.inputValue.value
+		};
+		for (const key of Object.keys(all)) if (all[key] === void 0) delete all[key];
+		return all;
+	});
+	const groupAttrs = computed(() => {
+		const all = {
+			"aria-disabled": isDisabled.value || void 0,
+			"aria-invalid": isInvalid.value || void 0,
+			role: "group"
+		};
+		for (const key of Object.keys(all)) if (all[key] === void 0) delete all[key];
+		return all;
+	});
+	return {
+		attrs,
+		decrement,
+		element: computed(() => element.value),
+		fieldIds,
+		groupAttrs,
+		increment,
+		isDisabled,
+		isFocusWithin,
+		isInvalid,
+		isReadOnly,
+		isRequired,
+		onBlur,
+		onFocus,
+		onFocusin,
+		onFocusout,
+		onInput,
+		onKeydown,
+		onKeyup,
+		onPaste,
+		reassert,
+		registerElement,
+		state
+	};
+};
+//#endregion
+export { useNumberField };

package/dist/composables/use-number-formatter.d.ts

@@ -0,0 +1,10 @@
+import type { NumberFormatOptions } from "@internationalized/number";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+/**
+ * An `Intl.NumberFormat` for the locale that applies here, ported from React Aria's
+ * `packages/react-aria/src/i18n/useNumberFormatter.ts` (react-aria 3.51.0).
+ *
+ * `@internationalized/number`'s `NumberFormatter` rather than `Intl` directly: it carries the
+ * `signDisplay` and `style: "unit"` fallbacks for engines that lack them.
+ */
+export declare const useNumberFormatter: (options?: MaybeRefOrGetter<NumberFormatOptions | undefined>) => ComputedRef<Intl.NumberFormat>;

package/dist/composables/use-number-formatter.js

@@ -0,0 +1,17 @@
+import { useLocale } from "./use-locale.js";
+import { computed, toValue } from "vue";
+import { NumberFormatter } from "@internationalized/number";
+//#region src/composables/use-number-formatter.ts
+/**
+* An `Intl.NumberFormat` for the locale that applies here, ported from React Aria's
+* `packages/react-aria/src/i18n/useNumberFormatter.ts` (react-aria 3.51.0).
+*
+* `@internationalized/number`'s `NumberFormatter` rather than `Intl` directly: it carries the
+* `signDisplay` and `style: "unit"` fallbacks for engines that lack them.
+*/
+var useNumberFormatter = (options) => {
+	const locale = useLocale();
+	return computed(() => new NumberFormatter(locale.value.locale, toValue(options) ?? {}));
+};
+//#endregion
+export { useNumberFormatter };

package/dist/composables/use-overlay-position.d.ts

@@ -0,0 +1,81 @@
+import type { Placement, PlacementAxis } from "../utils/position";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseOverlayPositionOptions {
+    /** The element the overlay is positioned against. */
+    targetRef: MaybeRefOrGetter<Element | null | undefined>;
+    /** The overlay itself. */
+    overlayRef: MaybeRefOrGetter<HTMLElement | null | undefined>;
+    /**
+     * A scrollable region inside the overlay, if it is not the overlay itself. Used to keep the
+     * focused item where it was when the overlay is repositioned.
+     */
+    scrollRef?: MaybeRefOrGetter<HTMLElement | null | undefined>;
+    /** @default "bottom" */
+    placement?: MaybeRefOrGetter<Placement | undefined>;
+    /** @default 12 */
+    containerPadding?: MaybeRefOrGetter<number | undefined>;
+    /** @default 0 */
+    offset?: MaybeRefOrGetter<number | undefined>;
+    /** @default 0 */
+    crossOffset?: MaybeRefOrGetter<number | undefined>;
+    /** @default true */
+    shouldFlip?: MaybeRefOrGetter<boolean | undefined>;
+    /** @default document.body */
+    boundaryElement?: MaybeRefOrGetter<Element | null | undefined>;
+    /**
+     * The arrow pointing at the trigger, if the overlay has one.
+     *
+     * Reported rather than measured from a size option, because the arrow is styled by the
+     * stylesheet and only it knows how big it is. Its width reserves room on the cross axis, so
+     * the overlay never sits so far along its trigger that the arrow would point past the edge.
+     */
+    arrowRef?: MaybeRefOrGetter<Element | null | undefined>;
+    /** Overrides the measured arrow width, for a caller that knows it up front. */
+    arrowSize?: MaybeRefOrGetter<number | undefined>;
+    /** Distance kept between the arrow and the corner of the overlay. @default 0 */
+    arrowBoundaryOffset?: MaybeRefOrGetter<number | undefined>;
+    isOpen?: MaybeRefOrGetter<boolean | undefined>;
+    maxHeight?: MaybeRefOrGetter<number | undefined>;
+    /** Called when a scroll makes the position untrustworthy. */
+    onClose?: (() => void) | null;
+}
+export interface UseOverlayPositionReturn {
+    /** Inline style for the overlay: its resolved position, stacking and height cap. */
+    overlayStyle: ComputedRef<Record<string, string>>;
+    /** The side the overlay ended up on, for the stylesheet to key its entry animation on. */
+    placement: ComputedRef<PlacementAxis | null>;
+    /**
+     * Inline style for the arrow: where along the overlay's edge it sits.
+     *
+     * Empty until the first measurement, so the arrow stays where its own stylesheet put it
+     * rather than jumping in from a corner.
+     */
+    arrowStyle: ComputedRef<Record<string, string>>;
+    /** Recompute the position, for a caller that changed something this cannot observe. */
+    updatePosition: () => void;
+}
+/**
+ * Position an overlay next to its trigger and keep it there, ported from React Aria's
+ * `useOverlayPosition`.
+ *
+ * The position is written straight to the element's inline style as well as being returned,
+ * which looks redundant but is not: a render pass would land a frame late, and for one frame
+ * the overlay would be visible at the wrong place — long enough to see as a jump, and long
+ * enough for an auto-focused item to scroll the page to the wrong spot.
+ *
+ * The height cap is reset before every measurement. Otherwise a previous, smaller cap would
+ * still be in force while the overlay is measured, and a menu whose items register a tick after
+ * it opens would be measured at the wrong height and never recover.
+ *
+ * @example
+ * ```ts
+ * const {overlayStyle, placement} = useOverlayPosition({
+ *   isOpen: () => state.isOpen.value,
+ *   offset: 8,
+ *   overlayRef: popoverElement,
+ *   placement: "bottom start",
+ *   targetRef: triggerElement,
+ * });
+ * ```
+ */
+export declare const useOverlayPosition: (options: UseOverlayPositionOptions) => UseOverlayPositionReturn;