@vunset/vue 0.0.0-stage → 1.0.0-rc.2

package/dist/shared/use-gauge.d.ts

@@ -0,0 +1,69 @@
+import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
+export type GaugeRole = 'progressbar' | 'meter';
+export type GaugeStatus = 'indeterminate' | 'progressing' | 'complete';
+export declare const GAUGE_PERCENTAGE_VAR = "--gauge-percentage";
+export declare const GAUGE_VALUE_VAR = "--gauge-value";
+export declare const GAUGE_MIN_VAR = "--gauge-min";
+export declare const GAUGE_MAX_VAR = "--gauge-max";
+export interface GaugeState {
+    /** `indeterminate` with no value and `complete` at `max` (a progress bar only), `progressing` otherwise. */
+    status: GaugeStatus;
+    /**
+     * How far along the range the value is, 0–100; `null` while indeterminate.
+     * @attribute `--gauge-percentage` (a CSS variable, with a `%`)
+     */
+    percentage: number | null;
+    /**
+     * The value, kept inside the range; `null` while indeterminate.
+     * @attribute `--gauge-value` (a CSS variable)
+     */
+    value: number | null;
+    /**
+     * The lower end of the range.
+     * @attribute `--gauge-min` (a CSS variable)
+     */
+    min: number;
+    /**
+     * The upper end of the range.
+     * @attribute `--gauge-max` (a CSS variable)
+     */
+    max: number;
+    /**
+     * The value through `format`, as the value part shows it.
+     * @attribute none
+     */
+    formattedValue: string;
+}
+export interface UseGaugeOptions {
+    /** Decided by the root, not by the caller. See {@link GaugeRole}. */
+    role: GaugeRole;
+    /** `null` is indeterminate, which only a progress bar can be. */
+    value?: MaybeRefOrGetter<number | null | undefined>;
+    /** @default 0 */
+    min?: MaybeRefOrGetter<number | undefined>;
+    /** @default 100 */
+    max?: MaybeRefOrGetter<number | undefined>;
+    /** Passed to `Intl.NumberFormat`. Omit it and the number is used as-is. */
+    format?: MaybeRefOrGetter<Intl.NumberFormatOptions | undefined>;
+    /** Defaults to the runtime's locale. */
+    locale?: MaybeRefOrGetter<Intl.LocalesArgument | undefined>;
+    /**
+     * Replaces the text read out for the value. Receives the formatted value and
+     * the raw one — "3 of 7 steps" rather than "3".
+     */
+    getValueText?: (formattedValue: string, value: number | null) => string;
+}
+export interface UseGaugeReturn {
+    state: ComputedRef<GaugeState>;
+    /** Bind to the element that carries the role. */
+    rootProps: ComputedRef<Record<string, unknown>>;
+    /** Bind to the groove the fill runs along. */
+    trackProps: ComputedRef<Record<string, unknown>>;
+    /** Bind to the fill itself. Draws from the variables, never from a width set here. */
+    indicatorProps: ComputedRef<Record<string, unknown>>;
+    /** Bind to the visible readout. */
+    valueProps: ComputedRef<Record<string, unknown>>;
+    registerLabel: (id: string) => () => void;
+}
+export declare function useGauge(options: UseGaugeOptions): UseGaugeReturn;
+export declare const provideGaugeContext: (value: UseGaugeReturn) => UseGaugeReturn, useGaugeContext: () => UseGaugeReturn;

package/dist/shared/use-gauge.js

@@ -0,0 +1,99 @@
+import { createContext } from "./context.js";
+import { computed, ref, toValue } from "vue";
+//#region src/shared/use-gauge.ts
+var GAUGE_PERCENTAGE_VAR = "--gauge-percentage";
+var GAUGE_VALUE_VAR = "--gauge-value";
+var GAUGE_MIN_VAR = "--gauge-min";
+var GAUGE_MAX_VAR = "--gauge-max";
+function useGauge(options) {
+	const min = () => toValue(options.min) ?? 0;
+	const max = () => toValue(options.max) ?? 100;
+	const labelId = ref();
+	const state = computed(() => {
+		const lower = min();
+		const upper = max();
+		const raw = toValue(options.value);
+		const indeterminate = raw == null || !Number.isFinite(raw);
+		if (indeterminate && options.role === "progressbar") return {
+			status: "indeterminate",
+			percentage: null,
+			value: null,
+			min: lower,
+			max: upper,
+			formattedValue: ""
+		};
+		const value = clamp(indeterminate ? lower : raw, lower, upper);
+		const span = upper - lower;
+		const percentage = span > 0 ? (value - lower) / span * 100 : 0;
+		return {
+			status: options.role === "progressbar" && value === upper ? "complete" : "progressing",
+			percentage,
+			value,
+			min: lower,
+			max: upper,
+			formattedValue: format(value, toValue(options.format), toValue(options.locale))
+		};
+	});
+	const valueText = computed(() => {
+		const current = state.value;
+		const fallback = current.status === "indeterminate" ? "indeterminate" : current.formattedValue;
+		return options.getValueText?.(current.formattedValue, current.value) ?? fallback;
+	});
+	const rootProps = computed(() => {
+		const current = state.value;
+		return {
+			"data-part": "gauge",
+			"data-status": current.status,
+			role: options.role,
+			"aria-valuemin": current.min,
+			"aria-valuemax": current.max,
+			"aria-valuenow": current.value ?? void 0,
+			"aria-valuetext": valueText.value,
+			"aria-labelledby": labelId.value,
+			style: {
+				...current.percentage === null ? null : {
+					[GAUGE_PERCENTAGE_VAR]: `${current.percentage}%`,
+					[GAUGE_VALUE_VAR]: current.value
+				},
+				[GAUGE_MIN_VAR]: current.min,
+				[GAUGE_MAX_VAR]: current.max
+			}
+		};
+	});
+	const trackProps = computed(() => ({
+		"data-part": "track",
+		"data-status": state.value.status
+	}));
+	const indicatorProps = computed(() => ({
+		"data-part": "indicator",
+		"data-status": state.value.status
+	}));
+	const valueProps = computed(() => ({
+		"data-part": "value",
+		"aria-hidden": true
+	}));
+	function registerLabel(id) {
+		labelId.value = id;
+		return () => {
+			if (labelId.value === id) labelId.value = void 0;
+		};
+	}
+	return {
+		state,
+		rootProps,
+		trackProps,
+		indicatorProps,
+		valueProps,
+		registerLabel
+	};
+}
+function clamp(value, lower, upper) {
+	return Math.min(Math.max(value, lower), upper);
+}
+function format(value, options, locale) {
+	if (!options) return String(value);
+	return new Intl.NumberFormat(locale, options).format(value);
+}
+var { provideContext: provideGaugeContext, useContext: useGaugeContext } = createContext("Gauge");
+//#endregion
+export { GAUGE_MAX_VAR, GAUGE_MIN_VAR, GAUGE_PERCENTAGE_VAR, GAUGE_VALUE_VAR, provideGaugeContext, useGauge, useGaugeContext };

package/dist/shared/use-inert-background.d.ts

@@ -0,0 +1,3 @@
+import { type MaybeRefOrGetter, type Ref } from 'vue';
+/** Hides everything outside a modal surface from assistive technology. */
+export declare function useInertBackground(enabled: MaybeRefOrGetter<boolean>, container: Ref<HTMLElement | null>): void;

package/dist/shared/use-inert-background.js

@@ -0,0 +1,37 @@
+import { getCurrentInstance, onMounted, onScopeDispose, toValue, watch } from "vue";
+//#region src/shared/use-inert-background.ts
+/** Hides everything outside a modal surface from assistive technology. */
+function useInertBackground(enabled, container) {
+	let touched = [];
+	function release() {
+		for (const { element, hadInert, previousAriaHidden } of touched) {
+			if (!hadInert) element.removeAttribute("inert");
+			if (previousAriaHidden === null) element.removeAttribute("aria-hidden");
+			else element.setAttribute("aria-hidden", previousAriaHidden);
+		}
+		touched = [];
+	}
+	function acquire() {
+		if (typeof document === "undefined" || touched.length > 0) return;
+		const surface = container.value;
+		for (const child of Array.from(document.body.children)) {
+			if (!(child instanceof HTMLElement)) continue;
+			if (surface && child.contains(surface)) continue;
+			touched.push({
+				element: child,
+				hadInert: child.hasAttribute("inert"),
+				previousAriaHidden: child.getAttribute("aria-hidden")
+			});
+			child.setAttribute("inert", "");
+			child.setAttribute("aria-hidden", "true");
+		}
+	}
+	watch(() => toValue(enabled), (on) => on || release(), { flush: "pre" });
+	watch(() => toValue(enabled), (on) => on && acquire(), { flush: "post" });
+	if (getCurrentInstance()) onMounted(() => {
+		if (toValue(enabled)) acquire();
+	});
+	onScopeDispose(release);
+}
+//#endregion
+export { useInertBackground };

package/dist/shared/use-input.d.ts

@@ -0,0 +1,64 @@
+import { type ComputedRef, type MaybeRefOrGetter, type Ref, type WritableComputedRef } from 'vue';
+import { type FieldFilter } from './input-filter';
+export type { FieldFilter };
+export interface InputState {
+    /** Whether it ignores interaction. */
+    disabled: boolean;
+    /** Whether the value can be read and selected but not edited. */
+    readOnly: boolean;
+    /** Whether a value is needed before the form submits. */
+    required: boolean;
+    /** Whether the value is invalid. */
+    invalid: boolean;
+    /** Whether it holds a non-empty value. */
+    filled: boolean;
+    /** Whether it has focus. */
+    focused: boolean;
+}
+export interface UseInputOptions {
+    /** The value. Supplying it makes the input controlled. */
+    value?: MaybeRefOrGetter<string | number | null | undefined>;
+    /** The initial value while uncontrolled. */
+    defaultValue?: MaybeRefOrGetter<string | number | undefined>;
+    disabled?: MaybeRefOrGetter<boolean>;
+    readOnly?: MaybeRefOrGetter<boolean>;
+    required?: MaybeRefOrGetter<boolean>;
+    /** Whether the value is invalid. Also read from a surrounding field. */
+    invalid?: MaybeRefOrGetter<boolean>;
+    /** The element id. Falls back to the surrounding field's, then a generated one. */
+    id?: MaybeRefOrGetter<string | undefined>;
+    name?: MaybeRefOrGetter<string | undefined>;
+    type?: MaybeRefOrGetter<string | undefined>;
+    /** Shortest acceptable value. Marks validity; it cannot block typing, since every value passes through being too short. */
+    minLength?: MaybeRefOrGetter<number | undefined>;
+    /** Longest acceptable value. Enforced while typing — no amount of further typing makes an over-long value acceptable. */
+    maxLength?: MaybeRefOrGetter<number | undefined>;
+    /** Smallest acceptable number. Marks validity, and rules out a leading minus when it is not negative. */
+    min?: MaybeRefOrGetter<number | string | undefined>;
+    /** Largest acceptable number. Marks validity; typing has to pass through smaller numbers to reach it. */
+    max?: MaybeRefOrGetter<number | string | undefined>;
+    /** Granularity of an acceptable number. Marks validity. */
+    step?: MaybeRefOrGetter<number | string | undefined>;
+    pattern?: MaybeRefOrGetter<string | undefined>;
+    /** What may be typed, tested against every **intermediate** value. `type="number"` supplies one automatically. */
+    filter?: MaybeRefOrGetter<FieldFilter | undefined>;
+    /** Rewrites the typed text once it's committed, on `change`: blur, or Enter in an input. */
+    transform?: MaybeRefOrGetter<((value: string) => string) | undefined>;
+    /** Called on every write, including programmatic ones. */
+    onChange?: (value: string) => void;
+}
+export interface UseInputReturn {
+    /** The value. Writable — assign to it to set the input programmatically. */
+    value: WritableComputedRef<string>;
+    state: ComputedRef<InputState>;
+    /** Bind to the `<input>` or `<textarea>`. */
+    controlProps: ComputedRef<Record<string, unknown>>;
+    /** The element, once mounted. */
+    controlRef: Ref<HTMLElement | null>;
+    /** Whether `next` is a value the control may hold while being typed. */
+    accepts: (next: string) => boolean;
+    /** Moves focus to the control. */
+    focus: () => void;
+}
+export declare function useInput(options?: UseInputOptions): UseInputReturn;
+export declare const provideInputContext: (value: UseInputReturn) => UseInputReturn, useInputContext: () => UseInputReturn;

package/dist/shared/use-input.js

@@ -0,0 +1,143 @@
+import { dataAttrs } from "./data-attrs.js";
+import { useControlled } from "./use-controlled.js";
+import { createContext } from "./context.js";
+import { useFieldValue, useOptionalFieldContext } from "./use-field.js";
+import { NON_NEGATIVE_NUMERIC, NUMERIC, insertedText, outOfRange, prospectiveValue, toFilterPredicate } from "./input-filter.js";
+import { computed, onScopeDispose, ref, toValue, useId, watch } from "vue";
+//#region src/shared/use-input.ts
+function useInput(options = {}) {
+	const field = useOptionalFieldContext();
+	const generatedId = useId();
+	const controlEl = ref(null);
+	const disabled = () => (toValue(options.disabled) ?? false) || (field?.state.value.disabled ?? false);
+	const readOnly = () => (toValue(options.readOnly) ?? false) || (field?.state.value.readOnly ?? false);
+	const required = () => (toValue(options.required) ?? false) || (field?.required() ?? false);
+	const numeric = () => toValue(options.type) === "number";
+	const outsideLimits = () => numeric() && outOfRange(value.value, {
+		min: toValue(options.min),
+		max: toValue(options.max),
+		step: toValue(options.step)
+	});
+	const invalid = () => (toValue(options.invalid) ?? false) || (field?.state.value.invalid ?? false) || outsideLimits();
+	const normalize = (raw) => raw == null ? void 0 : String(raw);
+	const value = useControlled({
+		value: () => normalize(toValue(options.value)),
+		defaultValue: () => normalize(toValue(options.defaultValue)) ?? "",
+		prop: "modelValue",
+		empty: "",
+		onChange: options.onChange,
+		name: "useInput",
+		label: "value"
+	});
+	const focused = ref(false);
+	const state = computed(() => ({
+		disabled: disabled(),
+		readOnly: readOnly(),
+		required: required(),
+		invalid: invalid(),
+		filled: value.value !== "",
+		focused: focused.value
+	}));
+	watch(() => value.value, (next) => field?.setFilled(next !== ""), { immediate: true });
+	watch(outsideLimits, (next) => field?.setControlInvalid(next), { immediate: true });
+	onScopeDispose(() => field?.setControlInvalid(false));
+	useFieldValue(field, () => value.value);
+	watch(controlEl, (element) => field?.setControl(element), { immediate: true });
+	const hooks = computed(() => dataAttrs(state.value));
+	const controlId = computed(() => toValue(options.id) ?? field?.controlId.value ?? generatedId);
+	function resolveFilter() {
+		const custom = toValue(options.filter);
+		if (custom !== void 0) return toFilterPredicate(custom);
+		if (!numeric()) return null;
+		const minimum = Number(toValue(options.min));
+		const expression = toValue(options.min) !== void 0 && Number.isFinite(minimum) && minimum >= 0 ? NON_NEGATIVE_NUMERIC : NUMERIC;
+		return (next) => expression.test(next);
+	}
+	function accepts(next) {
+		const limit = toValue(options.maxLength);
+		if (limit !== void 0 && next.length > limit) return false;
+		const predicate = resolveFilter();
+		return !predicate || predicate(next, value.value);
+	}
+	function restore(element) {
+		element.value = value.value;
+		try {
+			element.setSelectionRange(element.value.length, element.value.length);
+		} catch {}
+	}
+	let composing = false;
+	function handleInput(event) {
+		const el = event.target;
+		value.value = el.value;
+		if (el.value !== value.value) el.value = value.value;
+	}
+	return {
+		value,
+		state,
+		controlProps: computed(() => ({
+			...hooks.value,
+			id: controlId.value,
+			name: toValue(options.name) ?? field?.name(),
+			disabled: disabled(),
+			readonly: readOnly() || void 0,
+			"aria-required": required() || void 0,
+			value: value.value,
+			type: numeric() ? "text" : toValue(options.type),
+			inputmode: numeric() ? "decimal" : void 0,
+			minlength: toValue(options.minLength),
+			maxlength: toValue(options.maxLength),
+			min: toValue(options.min),
+			max: toValue(options.max),
+			step: toValue(options.step),
+			pattern: toValue(options.pattern),
+			"aria-invalid": invalid() || void 0,
+			"aria-describedby": field?.describedBy.value,
+			"aria-labelledby": field?.labelledBy.value,
+			ref: (el) => {
+				controlEl.value = el ?? null;
+			},
+			onCompositionstart() {
+				composing = true;
+			},
+			onCompositionend(event) {
+				composing = false;
+				handleInput(event);
+			},
+			onBeforeinput(event) {
+				if (!event.inputType?.startsWith("insert")) return;
+				const element = event.target;
+				const inserted = insertedText(event);
+				if (inserted === null) return;
+				if (!accepts(prospectiveValue(element, inserted) ?? element.value + inserted)) event.preventDefault();
+			},
+			onInput(event) {
+				if (composing) return;
+				const element = event.target;
+				if (event.inputType?.startsWith("insert") && !accepts(element.value)) {
+					restore(element);
+					return;
+				}
+				handleInput(event);
+			},
+			onChange(event) {
+				const transform = toValue(options.transform);
+				if (transform) value.value = transform(event.target.value);
+			},
+			onFocus() {
+				focused.value = true;
+				field?.setFocused(true);
+			},
+			onBlur() {
+				focused.value = false;
+				field?.setFocused(false);
+				field?.setTouched(true);
+			}
+		})),
+		controlRef: controlEl,
+		accepts,
+		focus: () => controlEl.value?.focus()
+	};
+}
+var { provideContext: provideInputContext, useContext: useInputContext } = createContext("Input");
+//#endregion
+export { provideInputContext, useInput };