@getdom/studio 0.1.0

package/src/pages/forms/field/DomField.vue

@@ -0,0 +1,267 @@
+<script setup>
+import { computed, inject, provide, reactive, unref, useAttrs } from 'vue';
+import { fieldLayoutProviderKey } from './fieldLayout.js';
+import { fieldDisplayProviderKey, normalizeErrors } from './useField.js';
+
+defineOptions({
+	inheritAttrs: false,
+	__doc: {
+		name: 'Field',
+		tag: '<DomField>',
+		description: 'Shared form chrome for labels, required markers, descriptions, errors, and custom controls.',
+		slots: [
+			{ name: '(default)', payload: '{ invalid, errors, htmlFor, errorId, fields, fieldAttrs }', description: 'The form control or custom interactive content.' },
+			{ name: 'label', payload: '{ label, required, htmlFor, invalid, errors, fields, fieldAttrs }', description: 'Replace the default label while keeping field layout.' },
+			{ name: 'errors', payload: '{ errors, errorId, invalid, fields, fieldAttrs }', description: 'Replace the default error list.' },
+			{ name: 'description', payload: '{ description, descriptionId, fields, fieldAttrs }', description: 'Replace the default helper text.' },
+		],
+	},
+});
+
+// Field chrome shared by every form input: a small upper label, the control,
+// and a description below. All form components in the library wrap their
+// control in <DomField> so they pick up consistent labelling out of the box.
+//
+// <DomField label="Email" description="We'll never share it.">
+//   <input … />
+// </DomField>
+const props = defineProps({
+	label: {
+		type: String,
+		default: '',
+		_edit: { description: 'Small label shown above the control.' },
+	},
+	description: {
+		type: String,
+		default: '',
+		_edit: { description: 'Helper text shown below the control.' },
+	},
+	htmlFor: {
+		type: String,
+		default: '',
+		_edit: { description: 'ID of the control the label should target.' },
+	},
+	descriptionId: {
+		type: String,
+		default: '',
+	},
+	errorId: {
+		type: String,
+		default: '',
+	},
+	invalid: {
+		type: Boolean,
+		default: false,
+		_edit: { description: 'Mark the field invalid and expose data-invalid for styling.' },
+	},
+	errors: {
+		type: [Array, Object, String],
+		default: () => [],
+		_edit: { component: 'DomJsonInput', description: 'Validation errors to show below the control.' },
+	},
+	required: {
+		type: Boolean,
+		default: false,
+		_edit: { description: 'Show a required marker next to the label.' },
+	},
+	visible: {
+		type: Boolean,
+		default: true,
+		_edit: { description: 'Show or hide the field wrapper.' },
+	},
+	chrome: {
+		type: [String, Boolean],
+		default: 'field',
+		_edit: { options: ['field', false], description: 'Render the field wrapper, or false to provide state without rendering chrome.' },
+	},
+	fieldLayout: {
+		type: [Object, Function, String],
+		default: null,
+		_edit: { description: 'Optional component used to render this field layout.' },
+	},
+});
+
+const attrs = useAttrs();
+const providedFieldLayout = inject(fieldLayoutProviderKey, null);
+const registeredFields = reactive(new Map());
+
+provide(fieldDisplayProviderKey, {
+	registerField(key, field) {
+		registeredFields.set(key, field);
+	},
+	unregisterField(key) {
+		registeredFields.delete(key);
+	},
+});
+
+const uniqueErrors = (errors) => {
+	const seen = new Set();
+	return errors.filter((error) => {
+		const key = String(error);
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+};
+const unrefOr = (value, fallback = undefined) => {
+	const resolved = unref(value);
+	return resolved === undefined ? fallback : resolved;
+};
+const fieldAttrsFromRegistration = (field) => unrefOr(field?.fieldAttrs, {}) || {};
+const fieldValue = (field, key) => {
+	if (!field) return undefined;
+	if (key in field) return unrefOr(field[key]);
+	return unrefOr(fieldAttrsFromRegistration(field)[key]);
+};
+const fieldVisible = (field) => fieldValue(field, 'visible') !== false;
+const fieldErrors = (field) => normalizeErrors(fieldValue(field, 'errors'));
+const fieldInvalid = (field) => Boolean(fieldValue(field, 'invalid') || fieldErrors(field).length);
+const hasInvalidAttr = computed(() => (
+	attrs['data-invalid'] === ''
+	|| attrs['data-invalid'] === true
+	|| attrs['data-invalid'] === 'true'
+));
+const fields = computed(() => Array.from(registeredFields.values()));
+const visibleFields = computed(() => fields.value.filter(fieldVisible));
+const firstField = computed(() => visibleFields.value[0] || fields.value[0] || null);
+const firstFieldAttrs = computed(() => fieldAttrsFromRegistration(firstField.value));
+const hasChrome = computed(() => props.chrome !== false && props.chrome !== 'none');
+const resolvedFieldLayout = computed(() => props.fieldLayout || unref(providedFieldLayout) || null);
+const errorMessages = computed(() => uniqueErrors([
+	...normalizeErrors(props.errors),
+	...visibleFields.value.flatMap(fieldErrors),
+]));
+const resolvedHtmlFor = computed(() => (
+	props.htmlFor
+	|| firstFieldAttrs.value.htmlFor
+	|| fieldValue(firstField.value, 'htmlId')
+	|| fieldValue(firstField.value, 'id')
+	|| ''
+));
+const resolvedErrorId = computed(() => (
+	props.errorId
+	|| firstFieldAttrs.value.errorId
+	|| (errorMessages.value.length && resolvedHtmlFor.value ? `${resolvedHtmlFor.value}-error` : '')
+));
+const resolvedDescription = computed(() => props.description || firstFieldAttrs.value.description || '');
+const resolvedDescriptionId = computed(() => (
+	props.descriptionId
+	|| firstFieldAttrs.value.descriptionId
+	|| (resolvedDescription.value && resolvedHtmlFor.value ? `${resolvedHtmlFor.value}-description` : '')
+));
+const resolvedLabel = computed(() => props.label || firstFieldAttrs.value.label || '');
+const resolvedRequired = computed(() => Boolean(
+	props.required
+	|| firstFieldAttrs.value.required
+	|| visibleFields.value.some((field) => fieldValue(field, 'required'))
+));
+const isInvalid = computed(() => (
+	props.invalid
+	|| errorMessages.value.length > 0
+	|| hasInvalidAttr.value
+	|| visibleFields.value.some(fieldInvalid)
+));
+const isVisible = computed(() => (
+	props.visible !== false
+	&& (!fields.value.length || visibleFields.value.length > 0)
+));
+const fieldAttrs = computed(() => ({
+	label: resolvedLabel.value,
+	description: resolvedDescription.value,
+	htmlFor: resolvedHtmlFor.value,
+	descriptionId: resolvedDescriptionId.value,
+	errorId: resolvedErrorId.value,
+	invalid: isInvalid.value,
+	required: resolvedRequired.value,
+	errors: errorMessages.value,
+	visible: isVisible.value,
+}));
+const slotProps = computed(() => ({
+	...fieldAttrs.value,
+	fields: visibleFields.value,
+	fieldAttrs: fieldAttrs.value,
+}));
+
+provide(fieldLayoutProviderKey, resolvedFieldLayout);
+</script>
+
+<template>
+	<template v-if="isVisible">
+		<slot v-if="!hasChrome" v-bind="slotProps" />
+		<component
+			:is="resolvedFieldLayout"
+			v-else-if="resolvedFieldLayout"
+			v-bind="{ ...attrs, ...slotProps }"
+			:data-invalid="isInvalid ? '' : undefined"
+		>
+			<template #label="layoutSlotProps">
+				<slot name="label" v-bind="{ ...slotProps, ...layoutSlotProps }">
+					<component
+						:is="resolvedHtmlFor ? 'label' : 'p'"
+						v-if="resolvedLabel"
+						v-bind="resolvedHtmlFor ? { for: resolvedHtmlFor } : {}"
+						class="block text-[11px] font-medium uppercase tracking-wider text-muted-fg"
+					>
+						{{ resolvedLabel }}
+						<span v-if="resolvedRequired" class="text-destructive">*</span>
+					</component>
+				</slot>
+			</template>
+			<template #default="layoutSlotProps">
+				<slot v-bind="{ ...slotProps, ...layoutSlotProps }" />
+			</template>
+			<template #errors="layoutSlotProps">
+				<slot name="errors" v-bind="{ ...slotProps, ...layoutSlotProps }">
+					<p
+						v-for="(error, index) in errorMessages"
+						:key="`${error}-${index}`"
+						:id="index === 0 ? resolvedErrorId : undefined"
+						class="text-[11px] leading-snug text-destructive"
+					>
+						{{ error }}
+					</p>
+				</slot>
+			</template>
+			<template #description="layoutSlotProps">
+				<slot name="description" v-bind="{ ...slotProps, ...layoutSlotProps }">
+					<p
+						v-if="resolvedDescription"
+						:id="resolvedDescriptionId || undefined"
+						class="text-[11px] leading-snug text-muted-fg"
+					>{{ resolvedDescription }}</p>
+				</slot>
+			</template>
+		</component>
+		<div v-else v-bind="attrs" class="space-y-1.5 w-full" :data-invalid="isInvalid ? '' : undefined">
+			<slot name="label" v-bind="slotProps">
+				<component
+					:is="resolvedHtmlFor ? 'label' : 'p'"
+					v-if="resolvedLabel"
+					v-bind="resolvedHtmlFor ? { for: resolvedHtmlFor } : {}"
+					class="block text-[11px] font-medium uppercase tracking-wider text-muted-fg"
+				>
+					{{ resolvedLabel }}
+					<span v-if="resolvedRequired" class="text-destructive">*</span>
+				</component>
+			</slot>
+			<slot v-bind="slotProps" />
+			<slot name="errors" v-bind="slotProps">
+				<p
+					v-for="(error, index) in errorMessages"
+					:key="`${error}-${index}`"
+					:id="index === 0 ? resolvedErrorId : undefined"
+					class="text-[11px] leading-snug text-destructive"
+				>
+					{{ error }}
+				</p>
+			</slot>
+			<slot name="description" v-bind="slotProps">
+				<p
+					v-if="resolvedDescription"
+					:id="resolvedDescriptionId || undefined"
+					class="text-[11px] leading-snug text-muted-fg"
+				>{{ resolvedDescription }}</p>
+			</slot>
+		</div>
+	</template>
+</template>

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

@@ -0,0 +1 @@
+export const fieldLayoutProviderKey = Symbol('domStudio.fieldLayoutProvider');

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

@@ -0,0 +1,114 @@
+export const FIELD_PROPS_GROUP = 'Field props';
+
+/**
+ * Adds the shared field prop group metadata to a field prop definition.
+ *
+ * @param {Record<string, unknown>} definition Vue prop definition.
+ * @returns {Record<string, unknown>} Field prop definition with editor metadata.
+ */
+function fieldProp(definition) {
+	return {
+		...definition,
+		_edit: {
+			group: FIELD_PROPS_GROUP,
+			...(definition._edit || {}),
+		},
+	};
+}
+
+export const fieldProps = {
+	modelValue: fieldProp({
+		default: '',
+		_edit: { description: 'Current field value.' },
+	}),
+	id: fieldProp({
+		type: String,
+		default: '',
+		_edit: { description: 'Optional ID override. By default parent forms derive the input ID from the field path using underscores.' },
+	}),
+	name: fieldProp({
+		type: String,
+		default: '',
+		_edit: { description: 'Local field name. Parent forms derive the full field path and native HTML name from the form hierarchy.' },
+	}),
+	label: fieldProp({
+		type: String,
+		default: '',
+		_edit: { description: 'Visible field label.' },
+	}),
+	description: fieldProp({
+		type: String,
+		default: '',
+		_edit: { description: 'Optional helper copy below the field.' },
+	}),
+	placeholder: fieldProp({
+		type: String,
+		default: '',
+		_edit: { description: 'Placeholder shown when the control is empty.' },
+	}),
+	required: fieldProp({
+		type: Boolean,
+		default: false,
+		_edit: { description: 'Mark the field as required.' },
+	}),
+	disabled: fieldProp({
+		type: Boolean,
+		default: false,
+		_edit: { description: 'Disable field interaction.' },
+	}),
+	readOnly: fieldProp({
+		type: Boolean,
+		default: false,
+		_edit: { description: 'Show the value but prevent editing.' },
+	}),
+	invalid: fieldProp({
+		type: Boolean,
+		default: false,
+		_edit: { description: 'Mark the field invalid.' },
+	}),
+	errors: fieldProp({
+		type: [Array, Object, String],
+		default: () => [],
+		_edit: { 
+			component: 'DomJsonListInput', 
+			description: 'Validation errors for this field.', 
+			schema: [
+				{
+					"key": "name",
+					"label": "Name",
+					"placeholder": "Validation name"
+				},
+				{
+					"key": "message",
+					"label": "Message",
+					"placeholder": "Error message"
+				},
+			]
+		}
+	}),
+	visible: fieldProp({
+		type: Boolean,
+		default: true,
+		_edit: { description: 'Show or hide the field.' },
+	}),
+	validators: fieldProp({
+		type: Array,
+		default: () => [],
+		_edit: {
+			component: 'DomValidatorInput',
+			description: 'Validators attached to this field. Use functions in Vue code, or serializable records such as { name: "minLength", props: { min: 2 } } in generated schemas.',
+		},
+	}),
+	validateOnBlur: fieldProp({
+		type: Boolean,
+		default: true,
+		_edit: { description: 'Run validators when the field loses focus.' },
+	}),
+	chrome: fieldProp({
+		type: [String, Boolean],
+		default: 'field',
+		_edit: { options: ['field', 'none', false], description: 'Render default field chrome, or hide chrome while keeping form state wiring.' },
+	}),
+};
+
+export const fieldPropNames = Object.keys(fieldProps);

package/src/pages/forms/field/layouts/DomGridFieldLayout.vue

@@ -0,0 +1,38 @@
+<script setup>
+import { useAttrs } from 'vue';
+
+defineOptions({
+	inheritAttrs: false,
+});
+
+defineProps({
+	label: { type: String, default: '' },
+	htmlFor: { type: String, default: '' },
+	description: { type: String, default: '' },
+	descriptionId: { type: String, default: '' },
+	errorId: { type: String, default: '' },
+	invalid: { type: Boolean, default: false },
+	errors: { type: Array, default: () => [] },
+	required: { type: Boolean, default: false },
+	visible: { type: Boolean, default: true },
+	fields: { type: Array, default: () => [] },
+	fieldAttrs: { type: Object, default: () => ({}) },
+});
+
+const attrs = useAttrs();
+</script>
+
+<template>
+	<div
+		v-bind="attrs"
+		class="min-w-0 space-y-1"
+		:data-invalid="invalid ? '' : undefined"
+	>
+		<label v-if="label" :for="htmlFor || undefined" class="sr-only">
+			{{ label }}<span v-if="required"> required</span>
+		</label>
+		<slot />
+		<slot name="errors" :errors="errors" :error-id="errorId" :invalid="invalid" />
+		<slot name="description" :description="description" :description-id="descriptionId" />
+	</div>
+</template>