@getdom/studio 0.1.0

package/src/pages/forms/field/useField.js

@@ -0,0 +1,343 @@
+import { computed, inject, onBeforeUnmount, ref, unref, useId, watch } from 'vue';
+import { compileValidators, normalizeValidatorResult, requiredValidator } from './validators.js';
+
+export const formFieldProviderKey = Symbol('domStudio.formFieldProvider');
+export const fieldDisplayProviderKey = Symbol('domStudio.fieldDisplayProvider');
+
+function providerValue(provider, name) {
+	if (!provider || !name) return undefined;
+	if (typeof provider.getValue === 'function') return unref(provider.getValue(name));
+	const values = provider.values || provider.data;
+	if (!values) return undefined;
+	return unref(values)?.[name];
+}
+
+function setProviderValue(provider, name, value) {
+	if (!provider || !name) return;
+	if (typeof provider.setValue === 'function') {
+		provider.setValue(name, value);
+		return;
+	}
+	const values = unref(provider.values || provider.data);
+	if (values && typeof values === 'object') values[name] = value;
+}
+
+function providerState(provider, name) {
+	if (!provider || !name) return {};
+	if (typeof provider.getFieldState === 'function') return unref(provider.getFieldState(name)) || {};
+	const states = unref(provider.fieldStates || provider.states);
+	return states?.[name] || {};
+}
+
+function setProviderState(provider, name, patch) {
+	if (!provider || !name) return;
+	if (typeof provider.setFieldState === 'function') {
+		provider.setFieldState(name, patch);
+		return;
+	}
+	const states = unref(provider.fieldStates || provider.states);
+	if (states && typeof states === 'object') {
+		states[name] = {
+			...(states[name] || {}),
+			...patch,
+		};
+	}
+}
+
+function providerPath(provider, name) {
+	if (!provider || !name) return name || '';
+	if (typeof provider.getFieldPath === 'function') return unref(provider.getFieldPath(name));
+	return name;
+}
+
+function providerHtmlName(provider, name) {
+	if (!provider || !name) return name || '';
+	if (typeof provider.getHtmlName === 'function') return unref(provider.getHtmlName(name));
+	return name;
+}
+
+function htmlIdFromPath(path) {
+	return String(path || '')
+		.split('.')
+		.filter(Boolean)
+		.join('_')
+		.replace(/[^A-Za-z0-9_]+/g, '_')
+		.replace(/^_+|_+$/g, '');
+}
+
+function providerHtmlId(provider, name) {
+	if (!provider || !name) return htmlIdFromPath(name);
+	if (typeof provider.getHtmlId === 'function') return unref(provider.getHtmlId(name));
+	return htmlIdFromPath(name);
+}
+
+export function normalizeErrors(errors) {
+	const value = unref(errors);
+	if (!value) return [];
+	if (typeof value === 'string') return value ? [value] : [];
+	if (Array.isArray(value)) {
+		return value
+			.flatMap((error) => normalizeErrors(error))
+			.filter(Boolean);
+	}
+	if (typeof value === 'object') {
+		if (value.message) return [value.message];
+		return Object.values(value)
+			.flatMap((error) => normalizeErrors(error))
+			.filter(Boolean);
+	}
+	return [];
+}
+
+export function useField(props, emit, options = {}) {
+	const injectedProvider = inject(formFieldProviderKey, null);
+	const injectedDisplayProvider = inject(fieldDisplayProviderKey, null);
+	const provider = options.register === false ? null : injectedProvider;
+	const displayProvider = options.register === false || options.display === false ? null : injectedDisplayProvider;
+	const displayRegistrationKey = Symbol(options.idPrefix || 'domStudio.fieldDisplayRegistration');
+	const generatedId = `${options.idPrefix || 'dom-field'}-${useId()}`;
+	const focused = ref(false);
+	const touchedState = ref(false);
+	const dirty = ref(false);
+	const validating = ref(false);
+	const internalValue = ref(props.modelValue);
+	const localErrors = ref([]);
+	let validationRun = 0;
+
+	const name = computed(() => props.name || props.id || generatedId);
+	const path = computed(() => providerPath(provider, name.value));
+	const htmlName = computed(() => providerHtmlName(provider, name.value));
+	const htmlId = computed(() => props.id || providerHtmlId(provider, name.value) || htmlIdFromPath(path.value) || generatedId);
+	const id = htmlId;
+	const descriptionId = computed(() => (props.description ? `${id.value}-description` : ''));
+	const errorId = computed(() => (errors.value.length ? `${id.value}-error` : ''));
+	const describedBy = computed(() => [descriptionId.value, errorId.value].filter(Boolean).join(' '));
+	const value = computed(() => {
+		const provided = providerValue(provider, name.value);
+		return provided !== undefined ? provided : internalValue.value;
+	});
+	const providerFieldState = computed(() => providerState(provider, name.value));
+	const errors = computed(() => [
+		...normalizeErrors(props.errors),
+		...normalizeErrors(providerFieldState.value.errors),
+		...normalizeErrors(localErrors.value),
+	]);
+	const invalid = computed(() => Boolean(props.invalid || providerFieldState.value.invalid || errors.value.length));
+	const interaction = computed(() => (
+		providerFieldState.value.interaction
+		|| (providerFieldState.value.focused ? 'focused' : providerFieldState.value.touched ? 'blurred' : '')
+		|| (focused.value ? 'focused' : touchedState.value ? 'blurred' : 'untouched')
+	));
+	const modification = computed(() => providerFieldState.value.modification || (providerFieldState.value.dirty || dirty.value ? 'changed' : 'clean'));
+	const validation = computed(() => {
+		if (validating.value || providerFieldState.value.validating) return 'validating';
+		if (invalid.value) return 'invalid';
+		if (providerFieldState.value.valid) return 'valid';
+		if (providerFieldState.value.validation && providerFieldState.value.validation !== 'unknown') {
+			return providerFieldState.value.validation;
+		}
+		if (providerFieldState.value.validation === 'unknown') return 'unknown';
+		if (
+			'invalid' in providerFieldState.value
+			|| 'errors' in providerFieldState.value
+			|| 'validating' in providerFieldState.value
+			|| localErrors.value.length
+		) return 'valid';
+		return 'unknown';
+	});
+	const valid = computed(() => validation.value === 'valid');
+	const touched = computed(() => interaction.value !== 'untouched');
+	const visible = computed(() => props.visible !== false && providerFieldState.value.visible !== false);
+	const disabled = computed(() => Boolean(props.disabled || providerFieldState.value.disabled));
+	const readOnly = computed(() => Boolean(props.readOnly || providerFieldState.value.readOnly));
+
+	const fieldAttrs = computed(() => ({
+		label: props.label,
+		description: props.description,
+		htmlFor: id.value,
+		descriptionId: descriptionId.value,
+		errorId: errorId.value,
+		invalid: invalid.value,
+		required: props.required,
+		errors: errors.value,
+		visible: visible.value,
+	}));
+
+	/**
+	 * This helps decorate the input with the relevant html attributes.
+	 */
+	const inputAttrs = computed(() => ({
+		id: id.value,
+		name: htmlName.value,
+		value: value.value,
+		placeholder: props.placeholder,
+		disabled: disabled.value || undefined,
+		readonly: readOnly.value || undefined,
+		required: props.required || undefined,
+		'aria-invalid': invalid.value || undefined,
+		'aria-describedby': describedBy.value || undefined,
+		'aria-errormessage': errorId.value || undefined,
+		'data-invalid': invalid.value ? '' : undefined,
+	}));
+
+	if (displayProvider?.registerField) {
+		displayProvider.registerField(displayRegistrationKey, {
+			id,
+			name,
+			path,
+			htmlName,
+			htmlId,
+			descriptionId,
+			errorId,
+			describedBy,
+			value,
+			errors,
+			invalid,
+			interaction,
+			modification,
+			validation,
+			valid,
+			focused,
+			touched,
+			dirty,
+			validating,
+			visible,
+			disabled,
+			readOnly,
+			fieldAttrs,
+			inputAttrs,
+		});
+	}
+
+	watch(() => props.modelValue, (nextValue) => {
+		internalValue.value = nextValue;
+	});
+
+	watch(value, () => {
+		if (!props.validateOnBlur) validate();
+	});
+
+	onBeforeUnmount(() => {
+		if (name.value && provider?.unregisterField) provider.unregisterField(name.value);
+		if (displayProvider?.unregisterField) displayProvider.unregisterField(displayRegistrationKey);
+	});
+
+	function setFieldState(patch) {
+		setProviderState(provider, name.value, patch);
+	}
+
+	function setValue(nextValue) {
+		internalValue.value = nextValue;
+		setProviderValue(provider, name.value, nextValue);
+		emit?.('update:modelValue', nextValue);
+		dirty.value = true;
+		setFieldState({ modification: 'changed', dirty: true, value: nextValue });
+	}
+
+	function onInput(nextValue) {
+		setValue(nextValue);
+	}
+
+	function onFocus(event) {
+		focused.value = true;
+		setFieldState({ interaction: 'focused', focused: true, touched: true });
+		emit?.('focus', event);
+	}
+
+	async function onBlur(event) {
+		focused.value = false;
+		touchedState.value = true;
+		setFieldState({ interaction: 'blurred', focused: false, touched: true });
+		emit?.('blur', event);
+		if (props.validateOnBlur) await validate();
+	}
+
+	async function validate(extraContext = {}) {
+		const currentRun = ++validationRun;
+		const nextErrors = [];
+		const validators = compileValidators([
+			...(props.required ? [requiredValidator] : []),
+			...(props.validators || []),
+		]);
+		validating.value = true;
+		setFieldState({ validation: 'validating', validating: true });
+		for (const validator of validators) {
+			const validateFn = typeof validator === 'function' ? validator : validator.validate;
+			if (!validateFn) continue;
+			const result = await validateFn(value.value, {
+				id: id.value,
+				name: name.value,
+				path: path.value,
+				htmlName: htmlName.value,
+				htmlId: htmlId.value,
+				props,
+				provider,
+				...extraContext,
+			});
+			const normalized = normalizeValidatorResult(result, validator);
+			if (normalized) nextErrors.push(normalized);
+		}
+		if (currentRun === validationRun) {
+			localErrors.value = provider ? [] : nextErrors;
+			validating.value = false;
+			setFieldState({
+				errors: nextErrors,
+				invalid: nextErrors.length > 0,
+				validation: nextErrors.length > 0 ? 'invalid' : 'valid',
+				validating: false,
+			});
+		}
+		return nextErrors.length === 0;
+	}
+
+	watch(name, (nextName, previousName) => {
+		if (previousName && provider?.unregisterField) provider.unregisterField(previousName);
+		if (nextName && provider?.registerField) {
+			provider.registerField({
+				id: id.value,
+				name: nextName,
+				path: path.value,
+				htmlName: htmlName.value,
+				htmlId: htmlId.value,
+				label: props.label,
+				required: props.required,
+				initialValue: internalValue.value,
+				validators: props.validators,
+				validate,
+			});
+		}
+	}, { immediate: true });
+
+	return {
+		id,
+		name,
+		path,
+		htmlName,
+		htmlId,
+		descriptionId,
+		errorId,
+		describedBy,
+		value,
+		errors,
+		invalid,
+		interaction,
+		modification,
+		validation,
+		valid,
+		focused,
+		touched,
+		dirty,
+		validating,
+		visible,
+		disabled,
+		readOnly,
+		fieldAttrs,
+		inputAttrs,
+		setFieldState,
+		setValue,
+		onInput,
+		onFocus,
+		onBlur,
+		validate,
+	};
+}

package/src/pages/forms/field/validators.js

@@ -0,0 +1,364 @@
+export function createValidator(name, validate, message = 'This field is invalid.', options = {}) {
+	return {
+		...options,
+		name,
+		message,
+		validate,
+	};
+}
+
+const validatorRegistry = new Map();
+
+function valueFromProps(props = {}, names = ['value']) {
+	for (const name of names) {
+		if (props[name] !== undefined) return props[name];
+	}
+	return undefined;
+}
+
+function isEmptyValue(value) {
+	if (Array.isArray(value)) return value.length === 0;
+	return value === undefined || value === null || value === '';
+}
+
+function validatorProps(record = {}) {
+	return {
+		...(record.props || {}),
+		...(record.options || {}),
+		...Object.fromEntries(Object.entries(record).filter(([key]) => ![
+			'name',
+			'rule',
+			'type',
+			'validator',
+			'validate',
+			'message',
+			'props',
+			'options',
+		].includes(key))),
+	};
+}
+
+export function defineValidator(definition) {
+	if (!definition?.name || typeof definition.validate !== 'function') return null;
+	const {
+		name,
+		validate,
+		message,
+		...metadata
+	} = definition;
+	const validator = createValidator(name, validate, message, metadata);
+	validatorRegistry.set(definition.name, validator);
+	return validator;
+}
+
+export function getValidator(name) {
+	return validatorRegistry.get(name) || null;
+}
+
+export function listValidators() {
+	return Array.from(validatorRegistry.values());
+}
+
+export function compileValidator(validator) {
+	if (!validator) return null;
+	if (typeof validator === 'function') return createValidator(validator.name || 'validator', validator);
+	if (typeof validator === 'string') return getValidator(validator);
+	if (typeof validator !== 'object') return null;
+	if (typeof validator.validate === 'function') return validator;
+
+	const name = validator.name || validator.rule || validator.type || validator.validator;
+	const registered = getValidator(name);
+	if (!registered) return null;
+	const props = validatorProps(validator);
+
+	return createValidator(
+		name,
+		async (value, context = {}) => {
+			const result = await registered.validate(value, {
+				...context,
+				props,
+				validator,
+			});
+			if (result !== true && result !== undefined && result !== null && validator.message) {
+				return validator.message;
+			}
+			return result;
+		},
+		validator.message || registered.message,
+	);
+}
+
+export function compileValidators(validators = []) {
+	return validators.map((validator) => compileValidator(validator)).filter(Boolean);
+}
+
+export function normalizeValidatorResult(result, validator) {
+	if (result === true || result === undefined || result === null) {
+		return null;
+	}
+	if (typeof result === 'string') {
+		return {
+			name: validator.name || 'validator',
+			message: result,
+		};
+	}
+	if (typeof result === 'object') {
+		if (result.valid === true) return null;
+		return {
+			name: result.name || result.code || validator.name || 'validator',
+			message: result.message || validator.message || 'This field is invalid.',
+			code: result.code,
+			meta: result.meta,
+		};
+	}
+	return {
+		name: validator.name || 'validator',
+		message: validator.message || 'This field is invalid.',
+	};
+}
+
+export const requiredValidator = defineValidator({
+	name: 'required',
+	label: 'Required',
+	description: 'Requires a non-empty value.',
+	message: 'This field is required.',
+	validate(value) {
+		if (Array.isArray(value)) return value.length > 0;
+		return value !== undefined && value !== null && String(value).trim() !== '';
+	},
+});
+
+export const emailValidator = defineValidator({
+	name: 'email',
+	label: 'Email',
+	description: 'Requires an email address.',
+	message: 'Enter a valid email address.',
+	validate(value) {
+		if (!value) return true;
+		return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(value));
+	},
+});
+
+export const urlValidator = defineValidator({
+	name: 'url',
+	label: 'URL',
+	description: 'Requires an HTTP or HTTPS URL.',
+	message: 'Enter a valid URL.',
+	validate(value) {
+		if (!value) return true;
+		try {
+			const url = new URL(String(value));
+			return ['http:', 'https:'].includes(url.protocol);
+		} catch {
+			return false;
+		}
+	},
+});
+
+export const minLengthValidator = defineValidator({
+	name: 'minLength',
+	label: 'Minimum length',
+	description: 'Requires text to be at least this many characters.',
+	props: {
+		min: {
+			type: Number,
+			default: 2,
+			_edit: { label: 'Minimum', description: 'Minimum number of characters.' },
+		},
+	},
+	message: 'This field is too short.',
+	validate(value, { props = {} } = {}) {
+		if (isEmptyValue(value)) return true;
+		const min = Number(valueFromProps(props, ['min', 'value', 'length']));
+		if (!Number.isFinite(min)) return true;
+		return String(value).length >= min || `Use at least ${min} characters.`;
+	},
+});
+
+export const maxLengthValidator = defineValidator({
+	name: 'maxLength',
+	label: 'Maximum length',
+	description: 'Requires text to be no longer than this many characters.',
+	props: {
+		max: {
+			type: Number,
+			default: 120,
+			_edit: { label: 'Maximum', description: 'Maximum number of characters.' },
+		},
+	},
+	message: 'This field is too long.',
+	validate(value, { props = {} } = {}) {
+		if (isEmptyValue(value)) return true;
+		const max = Number(valueFromProps(props, ['max', 'value', 'length']));
+		if (!Number.isFinite(max)) return true;
+		return String(value).length <= max || `Use ${max} characters or fewer.`;
+	},
+});
+
+export const lengthValidator = defineValidator({
+	name: 'length',
+	label: 'Exact length',
+	description: 'Requires text to have exactly this many characters.',
+	props: {
+		length: {
+			type: Number,
+			default: 8,
+			_edit: { label: 'Length', description: 'Exact number of characters.' },
+		},
+	},
+	message: 'This field has the wrong length.',
+	validate(value, { props = {} } = {}) {
+		if (isEmptyValue(value)) return true;
+		const length = Number(valueFromProps(props, ['length', 'value']));
+		if (!Number.isFinite(length)) return true;
+		return String(value).length === length || `Use exactly ${length} characters.`;
+	},
+});
+
+export const patternValidator = defineValidator({
+	name: 'pattern',
+	label: 'Pattern',
+	description: 'Requires text to match a regular expression.',
+	props: {
+		pattern: {
+			type: String,
+			default: '',
+			_edit: { label: 'Pattern', description: 'Regular expression pattern.' },
+		},
+		flags: {
+			type: String,
+			default: '',
+			_edit: { label: 'Flags', description: 'Optional regular expression flags.' },
+		},
+	},
+	message: 'This field does not match the required pattern.',
+	validate(value, { props = {} } = {}) {
+		if (isEmptyValue(value)) return true;
+		const pattern = valueFromProps(props, ['pattern', 'regex', 'value']);
+		if (!pattern) return true;
+		const flags = props.flags || '';
+		try {
+			return new RegExp(pattern, flags).test(String(value));
+		} catch {
+			return true;
+		}
+	},
+});
+
+export const minValidator = defineValidator({
+	name: 'min',
+	label: 'Minimum value',
+	description: 'Requires a number to be at least this value.',
+	props: {
+		min: {
+			type: Number,
+			default: 0,
+			_edit: { label: 'Minimum', description: 'Minimum numeric value.' },
+		},
+	},
+	message: 'This field is too small.',
+	validate(value, { props = {} } = {}) {
+		if (isEmptyValue(value)) return true;
+		const min = Number(valueFromProps(props, ['min', 'value']));
+		if (!Number.isFinite(min)) return true;
+		return Number(value) >= min || `Use a value of ${min} or greater.`;
+	},
+});
+
+export const maxValidator = defineValidator({
+	name: 'max',
+	label: 'Maximum value',
+	description: 'Requires a number to be at most this value.',
+	props: {
+		max: {
+			type: Number,
+			default: 100,
+			_edit: { label: 'Maximum', description: 'Maximum numeric value.' },
+		},
+	},
+	message: 'This field is too large.',
+	validate(value, { props = {} } = {}) {
+		if (isEmptyValue(value)) return true;
+		const max = Number(valueFromProps(props, ['max', 'value']));
+		if (!Number.isFinite(max)) return true;
+		return Number(value) <= max || `Use a value of ${max} or less.`;
+	},
+});
+
+export const betweenValidator = defineValidator({
+	name: 'between',
+	label: 'Between',
+	description: 'Requires a number to stay inside a range.',
+	props: {
+		min: {
+			type: Number,
+			default: 0,
+			_edit: { label: 'Minimum', description: 'Minimum numeric value.' },
+		},
+		max: {
+			type: Number,
+			default: 100,
+			_edit: { label: 'Maximum', description: 'Maximum numeric value.' },
+		},
+	},
+	message: 'This field is outside the allowed range.',
+	validate(value, { props = {} } = {}) {
+		if (isEmptyValue(value)) return true;
+		const min = Number(valueFromProps(props, ['min', 'from']));
+		const max = Number(valueFromProps(props, ['max', 'to']));
+		const number = Number(value);
+		if (!Number.isFinite(number)) return false;
+		if (Number.isFinite(min) && number < min) return `Use a value of ${min} or greater.`;
+		if (Number.isFinite(max) && number > max) return `Use a value of ${max} or less.`;
+		return true;
+	},
+});
+
+export const numberValidator = defineValidator({
+	name: 'number',
+	label: 'Number',
+	description: 'Requires a numeric value.',
+	message: 'Use a number.',
+	validate(value) {
+		if (isEmptyValue(value)) return true;
+		return Number.isFinite(Number(value));
+	},
+});
+
+export const integerValidator = defineValidator({
+	name: 'integer',
+	label: 'Integer',
+	description: 'Requires a whole number.',
+	message: 'Use a whole number.',
+	validate(value) {
+		if (isEmptyValue(value)) return true;
+		return Number.isInteger(Number(value));
+	},
+});
+
+export const oneOfValidator = defineValidator({
+	name: 'oneOf',
+	label: 'One of',
+	description: 'Requires the value to match an allowed list.',
+	props: {
+		values: {
+			type: Array,
+			default: () => [],
+			_edit: {
+				component: 'DomJsonInput',
+				label: 'Values',
+				description: 'Allowed values.',
+				props: { rows: 4 },
+			},
+		},
+	},
+	message: 'Choose one of the allowed values.',
+	validate(value, { props = {} } = {}) {
+		if (isEmptyValue(value)) return true;
+		const values = valueFromProps(props, ['values', 'options', 'value']) || [];
+		const allowed = Array.isArray(values) ? values.map((item) => (
+			item && typeof item === 'object' && 'value' in item ? item.value : item
+		)) : [];
+		return allowed.includes(value);
+	},
+});