picocrank 1.26.0 → 1.27.0

package/vue/components/FormField.spec.js

@@ -0,0 +1,350 @@
+import { describe, expect, it } from 'vitest'
+import { mountFormField, flushControlState } from '../test/formTestUtils.js'
+
+describe('FormField', () => {
+	describe('labels and structure', () => {
+		it('renders a label associated with the control via for/id', () => {
+			const wrapper = mountFormField({
+				props: {
+					label: 'Email',
+					for: 'email',
+				},
+				slot: '<input id="email" type="email" />',
+			})
+
+			const label = wrapper.find('label[for="email"]')
+			expect(label.exists()).toBe(true)
+			expect(label.text()).toContain('Email')
+			expect(wrapper.find('#email').exists()).toBe(true)
+		})
+
+		it('renders a fake label when component-has-label is set', () => {
+			const wrapper = mountFormField({
+				props: {
+					label: 'Role',
+					componentHasLabel: true,
+				},
+				slot: '<div role="radiogroup">Options</div>',
+			})
+
+			expect(wrapper.find('label').exists()).toBe(false)
+			expect(wrapper.find('.fake-label').text()).toContain('Role')
+		})
+
+		it('skips the label when label-skip is set', () => {
+			const wrapper = mountFormField({
+				props: {
+					label: 'Username',
+					labelSkip: true,
+					for: 'username',
+				},
+				slot: '<input id="username" aria-label="Username" />',
+			})
+
+			expect(wrapper.find('label').exists()).toBe(false)
+			expect(wrapper.find('.fake-label').exists()).toBe(false)
+			expect(wrapper.find('.form-field-label-skip').exists()).toBe(true)
+		})
+
+		it('renders description below the control by default', () => {
+			const wrapper = mountFormField({
+				props: {
+					description: 'Helpful hint text.',
+				},
+			})
+
+			const description = wrapper.find('.form-field-description')
+			expect(description.exists()).toBe(true)
+			expect(description.text()).toBe('Helpful hint text.')
+		})
+
+		it('renders description above the control when description-above is set', () => {
+			const wrapper = mountFormField({
+				props: {
+					description: 'Shown first.',
+					descriptionAbove: true,
+				},
+			})
+
+			const metaBlocks = wrapper.findAll('.form-field-meta')
+			expect(metaBlocks).toHaveLength(1)
+			expect(metaBlocks[0].find('.form-field-description').text()).toBe('Shown first.')
+		})
+
+		it('renders a docs link when docs-url is provided', () => {
+			const wrapper = mountFormField({
+				props: {
+					docsUrl: 'https://example.com/docs',
+					docsUrlTitle: 'Read the docs',
+				},
+			})
+
+			const link = wrapper.find('.form-field-docs-link')
+			expect(link.attributes('href')).toBe('https://example.com/docs')
+			expect(link.attributes('target')).toBe('_blank')
+			expect(link.attributes('rel')).toBe('noopener noreferrer')
+			expect(link.text()).toBe('Read the docs')
+		})
+	})
+
+	describe('required indicator', () => {
+		it('shows a required asterisk when label-required is set', () => {
+			const wrapper = mountFormField({
+				props: {
+					labelRequired: true,
+				},
+			})
+
+			const marker = wrapper.find('.form-field-required')
+			expect(marker.exists()).toBe(true)
+			expect(marker.attributes('aria-hidden')).toBe('true')
+			expect(marker.text()).toBe('*')
+		})
+
+		it('shows a required asterisk when the slotted control is required', async () => {
+			const wrapper = mountFormField({
+				slot: '<input id="test-input" required />',
+			})
+
+			await flushControlState()
+
+			expect(wrapper.find('.form-field-required').exists()).toBe(true)
+		})
+	})
+
+	describe('error prop validation', () => {
+		it('shows a NotificationBlock when error is set', async () => {
+			const wrapper = mountFormField({
+				props: {
+					error: 'This field is required.',
+				},
+			})
+
+			await flushControlState()
+
+			const errorBlock = wrapper.find('.form-field-error')
+			expect(errorBlock.exists()).toBe(true)
+			expect(errorBlock.attributes('role')).toBe('alert')
+			expect(errorBlock.text()).toContain('This field is required.')
+		})
+
+		it('does not show an error block when error is empty', async () => {
+			const wrapper = mountFormField({
+				props: {
+					error: '',
+				},
+			})
+
+			await flushControlState()
+
+			expect(wrapper.find('.form-field-error').exists()).toBe(false)
+		})
+
+		it('marks the native control invalid when error is set', async () => {
+			const wrapper = mountFormField({
+				props: {
+					error: 'Invalid value.',
+				},
+			})
+
+			await flushControlState()
+
+			const input = wrapper.find('#test-input').element
+			expect(input.getAttribute('aria-invalid')).toBe('true')
+			expect(input.classList.contains('field-invalid')).toBe(true)
+			expect(input.validationMessage).toBe('Invalid value.')
+			expect(input.validity.customError).toBe(true)
+		})
+
+		it('links the control to the error via aria-describedby', async () => {
+			const wrapper = mountFormField({
+				props: {
+					error: 'Invalid value.',
+				},
+			})
+
+			await flushControlState()
+
+			const input = wrapper.find('#test-input').element
+			const errorId = wrapper.find('.form-field-error').attributes('id')
+			expect(input.getAttribute('aria-describedby')).toContain(errorId)
+		})
+
+		it('clears native invalid state when error is removed', async () => {
+			const wrapper = mountFormField({
+				props: {
+					error: 'Invalid value.',
+				},
+			})
+
+			await flushControlState()
+			await wrapper.setProps({ error: '' })
+			await flushControlState()
+
+			const input = wrapper.find('#test-input').element
+			expect(input.hasAttribute('aria-invalid')).toBe(false)
+			expect(input.classList.contains('field-invalid')).toBe(false)
+			expect(input.validationMessage).toBe('')
+		})
+
+		it('emits update:error when the user edits a field with an external error', async () => {
+			const wrapper = mountFormField({
+				props: {
+					error: 'Server rejected this value.',
+				},
+			})
+
+			await flushControlState()
+			await wrapper.find('#test-input').setValue('corrected')
+			await flushControlState()
+
+			expect(wrapper.emitted('update:error')).toContainEqual([''])
+		})
+
+		it('does not emit update:error on input when validate() supplies the error', async () => {
+			const wrapper = mountFormField({
+				props: {
+					validate: () => 'Always invalid.',
+					validateDeps: [],
+				},
+			})
+
+			await flushControlState()
+			await wrapper.find('#test-input').setValue('anything')
+			await flushControlState()
+
+			expect(wrapper.emitted('update:error')).toBeUndefined()
+		})
+	})
+
+	describe('validate function', () => {
+		it('shows an error from the validate callback', async () => {
+			const wrapper = mountFormField({
+				props: {
+					validate: () => 'Pick at least one option.',
+					validateDeps: [],
+				},
+			})
+
+			await flushControlState()
+
+			expect(wrapper.find('.form-field-error').text()).toContain('Pick at least one option.')
+		})
+
+		it('re-runs validate when validateDeps change', async () => {
+			const state = { value: 'a' }
+			const wrapper = mountFormField({
+				props: {
+					validateDeps: [state.value],
+					validate: () => (state.value === 'a' ? 'First value is invalid.' : ''),
+				},
+			})
+
+			await flushControlState()
+			expect(wrapper.find('.form-field-error').exists()).toBe(true)
+
+			state.value = 'b'
+			await wrapper.setProps({ validateDeps: ['b'] })
+			await flushControlState()
+			expect(wrapper.find('.form-field-error').exists()).toBe(false)
+		})
+
+		it('prefers the error prop over validate()', async () => {
+			const wrapper = mountFormField({
+				props: {
+					error: 'External error.',
+					validate: () => 'Validation error.',
+					validateDeps: [],
+				},
+			})
+
+			await flushControlState()
+
+			expect(wrapper.find('.form-field-error').text()).toContain('External error.')
+			expect(wrapper.find('.form-field-error').text()).not.toContain('Validation error.')
+		})
+
+		it('ignores non-string validate results', async () => {
+			const wrapper = mountFormField({
+				props: {
+					validate: () => false,
+					validateDeps: [],
+				},
+			})
+
+			await flushControlState()
+
+			expect(wrapper.find('.form-field-error').exists()).toBe(false)
+		})
+	})
+
+	describe('component-has-label controls', () => {
+		it('does not apply native validity to composite controls', async () => {
+			const wrapper = mountFormField({
+				props: {
+					componentHasLabel: true,
+					error: 'Group error.',
+				},
+				slot: '<input id="test-input" />',
+			})
+
+			await flushControlState()
+
+			const input = wrapper.find('#test-input').element
+			expect(input.validationMessage).toBe('')
+			expect(input.hasAttribute('aria-invalid')).toBe(false)
+		})
+	})
+
+	describe('lifecycle', () => {
+		it('clears native validity on unmount', async () => {
+			const wrapper = mountFormField({
+				props: {
+					error: 'Invalid value.',
+				},
+			})
+
+			await flushControlState()
+
+			const input = wrapper.find('#test-input').element
+			expect(input.validationMessage).toBe('Invalid value.')
+
+			wrapper.unmount()
+
+			expect(input.validationMessage).toBe('')
+			expect(input.hasAttribute('aria-invalid')).toBe(false)
+		})
+	})
+
+	describe('disabled state', () => {
+		it('applies disabled styling class to the label', () => {
+			const wrapper = mountFormField({
+				props: {
+					disabled: true,
+				},
+			})
+
+			expect(wrapper.find('label.disabled').exists()).toBe(true)
+		})
+	})
+})
+
+describe('FormField htmlFor alias', () => {
+		it('accepts htmlFor as an alias for for', async () => {
+			const wrapper = mountFormField({
+				props: {
+					label: 'Name',
+					htmlFor: 'name-field',
+					for: '',
+				},
+				slot: '<input id="name-field" />',
+			})
+
+		expect(wrapper.find('label[for="name-field"]').exists()).toBe(true)
+
+		await wrapper.setProps({ error: 'Required.' })
+		await flushControlState()
+
+		expect(wrapper.find('#name-field').element.getAttribute('aria-invalid')).toBe('true')
+	})
+})

package/vue/components/FormField.vue

@@ -1,39 +1,51 @@
 <template>
-	<label v-if="!fake" :for="controlId" :class="{ disabled }">{{ label }}</label>
-	<span v-else class="fake-label" :class="{ disabled }">{{ label }}</span>
-	<div v-if="hasFieldMeta" class="form-field-control">
-		<template v-if="descriptionAbove">
-			<div v-if="description || docsUrl" class="form-field-meta">
-				<p v-if="description" class="subtle form-field-description">{{ description }}</p>
-				<a
-					v-if="docsUrl"
-					class="form-field-docs-link"
-					:href="docsUrl"
-					target="_blank"
-					rel="noopener noreferrer"
-				>{{ docsLinkTitle }}</a>
-			</div>
-			<slot />
-		</template>
-		<template v-else>
-			<slot />
-			<div v-if="description || docsUrl" class="form-field-meta">
-				<p v-if="description" class="subtle form-field-description">{{ description }}</p>
-				<a
-					v-if="docsUrl"
-					class="form-field-docs-link"
-					:href="docsUrl"
-					target="_blank"
-					rel="noopener noreferrer"
-				>{{ docsLinkTitle }}</a>
-			</div>
-		</template>
+	<label v-if="showLabel && !componentHasLabel" :for="controlId" :class="{ disabled }">
+		<span class="form-field-label-text">{{ label }}</span><span v-if="showRequiredLabel" class="form-field-required" aria-hidden="true">*</span>
+	</label>
+	<span v-else-if="showLabel" class="fake-label" :class="{ disabled }">
+		<span class="form-field-label-text">{{ label }}</span><span v-if="showRequiredLabel" class="form-field-required" aria-hidden="true">*</span>
+	</span>
+	<div
+		ref="fieldControlRef"
+		class="form-field-control"
+		:class="{ 'form-field-label-skip': labelSkip }"
+	>
+		<div v-if="descriptionAbove && hasFieldMeta" class="form-field-meta">
+			<p v-if="description" class="subtle form-field-description">{{ description }}</p>
+			<a
+				v-if="docsUrl"
+				class="form-field-docs-link"
+				:href="docsUrl"
+				target="_blank"
+				rel="noopener noreferrer"
+			>{{ docsLinkTitle }}</a>
+		</div>
+		<slot />
+		<NotificationBlock
+			v-if="fieldError"
+			:id="errorId"
+			class="form-field-error"
+			type="bad"
+			label="Error"
+			:message="fieldError"
+			role="alert"
+		/>
+		<div v-if="!descriptionAbove && hasFieldMeta" class="form-field-meta">
+			<p v-if="description" class="subtle form-field-description">{{ description }}</p>
+			<a
+				v-if="docsUrl"
+				class="form-field-docs-link"
+				:href="docsUrl"
+				target="_blank"
+				rel="noopener noreferrer"
+			>{{ docsLinkTitle }}</a>
+		</div>
 	</div>
-	<slot v-else />
 </template>
 
 <script setup>
-import { computed } from 'vue'
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, useId, watch } from 'vue'
+import NotificationBlock from './NotificationBlock.vue'
 
 const props = defineProps({
 	label: {
@@ -64,7 +76,15 @@ const props = defineProps({
 		type: String,
 		default: '',
 	},
-	fake: {
+	componentHasLabel: {
+		type: Boolean,
+		default: false,
+	},
+	labelSkip: {
+		type: Boolean,
+		default: false,
+	},
+	labelRequired: {
 		type: Boolean,
 		default: false,
 	},
@@ -72,11 +92,186 @@ const props = defineProps({
 		type: Boolean,
 		default: false,
 	},
+	error: {
+		type: String,
+		default: '',
+	},
+	validate: {
+		type: Function,
+		default: null,
+	},
+	validateDeps: {
+		type: Array,
+		default: () => [],
+	},
 })
 
+const emit = defineEmits(['update:error'])
+
 const controlId = computed(() => props.htmlFor || props.for)
+const showLabel = computed(() => !props.labelSkip)
 const hasFieldMeta = computed(() => Boolean(props.description || props.docsUrl))
 const docsLinkTitle = computed(() => props.docsUrlTitle || props.docsUrl)
+const errorId = useId()
+const FIELD_INVALID_CLASS = 'field-invalid'
+const fieldControlRef = ref(null)
+const controlRequired = ref(false)
+let boundControl = null
+
+function onControlInput() {
+	if (props.error.trim()) {
+		emit('update:error', '')
+	}
+}
+
+function bindControlListeners() {
+	unbindControlListeners()
+	const element = getControlElement()
+	if (!element) {
+		return
+	}
+	element.addEventListener('input', onControlInput)
+	element.addEventListener('change', onControlInput)
+	boundControl = element
+}
+
+function unbindControlListeners() {
+	if (!boundControl) {
+		return
+	}
+	boundControl.removeEventListener('input', onControlInput)
+	boundControl.removeEventListener('change', onControlInput)
+	boundControl = null
+}
+
+const showRequiredLabel = computed(() => props.labelRequired || controlRequired.value)
+
+const fieldError = computed(() => {
+	// Re-run when parent passes reactive deps (e.g. v-model values).
+	void props.validateDeps
+
+	if (props.error.trim()) {
+		return props.error.trim()
+	}
+	if (typeof props.validate === 'function') {
+		const result = props.validate()
+		return typeof result === 'string' ? result.trim() : ''
+	}
+	return ''
+})
+
+function getControlElement() {
+	if (!controlId.value) {
+		return null
+	}
+	return document.getElementById(controlId.value)
+}
+
+function syncRequiredState() {
+	const linkedControl = getControlElement()
+	if (linkedControl) {
+		controlRequired.value = linkedControl.required === true
+		return
+	}
+
+	const container = fieldControlRef.value
+	controlRequired.value = Boolean(
+		container?.querySelector('input[required], select[required], textarea[required]'),
+	)
+}
+
+function syncControlState() {
+	syncNativeValidity()
+	syncRequiredState()
+}
+
+function syncNativeValidity() {
+	const element = getControlElement()
+	const canUseNativeValidity = Boolean(
+		controlId.value
+		&& !props.componentHasLabel
+		&& element
+		&& typeof element.setCustomValidity === 'function',
+	)
+
+	if (!canUseNativeValidity) {
+		clearNativeFieldState(element)
+		return
+	}
+
+	element.setCustomValidity(fieldError.value || '')
+	if (fieldError.value) {
+		element.setAttribute('aria-invalid', 'true')
+		element.classList.add(FIELD_INVALID_CLASS)
+		setErrorDescribedBy(element)
+	} else {
+		element.removeAttribute('aria-invalid')
+		element.classList.remove(FIELD_INVALID_CLASS)
+		removeErrorDescribedBy(element)
+	}
+}
+
+function clearNativeFieldState(element) {
+	if (!element) {
+		return
+	}
+	if (typeof element.setCustomValidity === 'function') {
+		element.setCustomValidity('')
+	}
+	element.removeAttribute('aria-invalid')
+	element.classList.remove(FIELD_INVALID_CLASS)
+	removeErrorDescribedBy(element)
+}
+
+function setErrorDescribedBy(element) {
+	const existing = element.getAttribute('aria-describedby')
+	const ids = existing ? existing.split(/\s+/).filter(Boolean) : []
+	if (!ids.includes(errorId)) {
+		ids.push(errorId)
+	}
+	element.setAttribute('aria-describedby', ids.join(' '))
+}
+
+function removeErrorDescribedBy(element) {
+	const existing = element.getAttribute('aria-describedby')
+	if (!existing) {
+		return
+	}
+	const ids = existing.split(/\s+/).filter((id) => id !== errorId)
+	if (ids.length > 0) {
+		element.setAttribute('aria-describedby', ids.join(' '))
+	} else {
+		element.removeAttribute('aria-describedby')
+	}
+}
+
+watch(
+	() => [fieldError.value, controlId.value, props.componentHasLabel],
+	() => {
+		nextTick(syncControlState)
+	},
+	{ flush: 'post' },
+)
+
+watch(
+	controlId,
+	() => {
+		nextTick(bindControlListeners)
+	},
+)
+
+onMounted(() => {
+	nextTick(() => {
+		syncControlState()
+		bindControlListeners()
+	})
+})
+
+onBeforeUnmount(() => {
+	const element = boundControl || getControlElement()
+	unbindControlListeners()
+	clearNativeFieldState(element)
+})
 </script>
 
 <style scoped>
@@ -107,4 +302,13 @@ label.disabled,
 	font-size: 0.9em;
 	align-self: flex-start;
 }
+
+.form-field-control :deep(.form-field-error) {
+	font-size: 0.9em;
+}
+
+.form-field-required {
+	color: var(--form-field-required-fg);
+	margin-left: 0.15em;
+}
 </style>

package/vue/components/FormLayout.spec.js

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from 'vitest'
+import { mount } from '@vue/test-utils'
+import FormLayout from './FormLayout.vue'
+
+describe('FormLayout', () => {
+	it('renders a form element with default slot content', () => {
+		const wrapper = mount(FormLayout, {
+			attachTo: document.body,
+			slots: {
+				default: '<input id="name" />',
+			},
+		})
+
+		expect(wrapper.element.tagName).toBe('FORM')
+		expect(wrapper.find('#name').exists()).toBe(true)
+	})
+
+	it('does not render an actions fieldset when the actions slot is empty', () => {
+		const wrapper = mount(FormLayout, {
+			slots: {
+				default: '<input id="name" />',
+			},
+		})
+
+		expect(wrapper.find('fieldset').exists()).toBe(false)
+	})
+
+	it('renders an actions fieldset when the actions slot is provided', () => {
+		const wrapper = mount(FormLayout, {
+			slots: {
+				default: '<input id="name" />',
+				actions: '<button type="submit">Save</button>',
+			},
+		})
+
+		const fieldset = wrapper.find('fieldset')
+		expect(fieldset.exists()).toBe(true)
+		expect(fieldset.find('button[type="submit"]').exists()).toBe(true)
+	})
+
+	it('forwards submit events from the native form', async () => {
+		const onSubmit = vi.fn((event) => event.preventDefault())
+		const wrapper = mount(FormLayout, {
+			attrs: {
+				onSubmit,
+			},
+			slots: {
+				default: '<button type="submit">Save</button>',
+			},
+		})
+
+		await wrapper.find('form').trigger('submit')
+
+		expect(onSubmit).toHaveBeenCalledTimes(1)
+	})
+})