picocrank 1.26.0 → 1.27.0

package/vue/components/form-validation.spec.js

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest'
+import {
+	flushControlState,
+	MIN_COMMENTS_LENGTH,
+	mountLoginValidationForm,
+	mountValidationForm,
+} from '../test/formTestUtils.js'
+
+describe('form validation integration', () => {
+	it('blocks submit and surfaces native required validation for empty email', async () => {
+		const { wrapper, submitted } = mountValidationForm()
+
+		await wrapper.find('button[type="submit"]').trigger('click')
+		await flushControlState()
+
+		expect(submitted.value).toBe(false)
+		expect(wrapper.find('#email').element.validationMessage).not.toBe('')
+	})
+
+	it('shows computed email format errors as the user types', async () => {
+		const { wrapper } = mountValidationForm()
+
+		await wrapper.find('#email').setValue('not-an-email')
+		await flushControlState()
+
+		expect(wrapper.find('#email').element.getAttribute('aria-invalid')).toBe('true')
+		expect(wrapper.text()).toContain('Enter a valid email address.')
+	})
+
+	it('clears email errors when a valid address is entered', async () => {
+		const { wrapper } = mountValidationForm()
+
+		await wrapper.find('#email').setValue('not-an-email')
+		await flushControlState()
+		await wrapper.find('#email').setValue('user@example.com')
+		await flushControlState()
+
+		expect(wrapper.find('#email').element.hasAttribute('aria-invalid')).toBe(false)
+		expect(wrapper.findAll('.form-field-error')).toHaveLength(0)
+	})
+
+	it('shows comments length validation only when comments are non-empty', async () => {
+		const { wrapper } = mountValidationForm()
+
+		await wrapper.find('#email').setValue('user@example.com')
+		await wrapper.find('#comments').setValue('Too short')
+		await flushControlState()
+
+		expect(wrapper.text()).toContain(`Comments must be at least ${MIN_COMMENTS_LENGTH} characters.`)
+	})
+
+	it('allows submit when email is valid and comments are empty', async () => {
+		const { wrapper, submitted } = mountValidationForm()
+
+		await wrapper.find('#email').setValue('user@example.com')
+		await wrapper.find('button[type="submit"]').trigger('click')
+		await flushControlState()
+
+		expect(submitted.value).toBe(true)
+	})
+
+	it('blocks submit for conflicting accessibility selections via validate()', async () => {
+		const { wrapper, submitted, formData } = mountValidationForm()
+
+		await wrapper.find('#email').setValue('user@example.com')
+		formData.value.accessibility = ['high-contrast', 'low-contrast']
+		await flushControlState()
+
+		await wrapper.find('button[type="submit"]').trigger('click')
+		await flushControlState()
+
+		expect(submitted.value).toBe(false)
+		expect(wrapper.text()).toContain('High contrast and low contrast UI cannot both be selected.')
+	})
+
+	it('submits when accessibility selections are compatible', async () => {
+		const { wrapper, submitted, formData } = mountValidationForm()
+
+		await wrapper.find('#email').setValue('user@example.com')
+		formData.value.accessibility = ['high-contrast']
+		await flushControlState()
+
+		await wrapper.find('button[type="submit"]').trigger('click')
+		await flushControlState()
+
+		expect(submitted.value).toBe(true)
+	})
+})
+
+describe('Login-style server validation', () => {
+	it('maps password errors to the password field', async () => {
+		const { wrapper } = mountLoginValidationForm()
+
+		wrapper.vm.applyServerErrors({ password: 'Incorrect password.' })
+		await flushControlState()
+
+		expect(wrapper.find('#password').element.getAttribute('aria-invalid')).toBe('true')
+		expect(wrapper.text()).toContain('Incorrect password.')
+		expect(wrapper.find('.login-form-error').exists()).toBe(false)
+	})
+
+	it('maps server failures to a form-level NotificationBlock', async () => {
+		const { wrapper } = mountLoginValidationForm()
+
+		wrapper.vm.applyServerErrors({ form: 'Unable to reach authentication service.' })
+		await flushControlState()
+
+		expect(wrapper.find('.login-form-error').exists()).toBe(true)
+		expect(wrapper.find('.login-form-error').attributes('role')).toBe('alert')
+		expect(wrapper.text()).toContain('Unable to reach authentication service.')
+		expect(wrapper.find('#username').element.hasAttribute('aria-invalid')).toBe(false)
+	})
+
+	it('clears field errors when the user edits the control', async () => {
+		const { wrapper, passwordError } = mountLoginValidationForm()
+
+		wrapper.vm.applyServerErrors({ password: 'Incorrect password.' })
+		await flushControlState()
+
+		await wrapper.find('#password').setValue('new-secret')
+		await flushControlState()
+
+		expect(passwordError.value).toBe('')
+		expect(wrapper.find('#password').element.hasAttribute('aria-invalid')).toBe(false)
+	})
+})

package/vue/examples/FormExample.vue

@@ -22,7 +22,7 @@
 				/>
 			</FormField>
 
-			<FormField label="Role" fake>
+			<FormField label="Role" component-has-label>
 				<RadioGroup
 					v-model="formData.role"
 					name="role"
@@ -30,7 +30,7 @@
 				/>
 			</FormField>
 
-			<FormField label="Term" fake>
+			<FormField label="Term" component-has-label>
 				<RadioGroup
 					v-model="formData.term"
 					name="term"
@@ -52,7 +52,8 @@
 
 			<FormField
 				label="Compensation"
-				fake
+				component-has-label
+				label-required
 				description-above
 				description="Select the incentive plan that applies to this role."
 				docs-url="https://github.com/jamesread/femtocrank"
@@ -68,11 +69,13 @@
 
 			<FormField
 				label="Accessibility requirements"
-				fake
+				component-has-label
 				description-above
 				description="Choose any accommodations needed for this role."
 				docs-url="https://www.w3.org/WAI/fundamentals/accessibility-intro/"
 				docs-url-title="Web accessibility introduction"
+				:validate="validateAccessibilityRequirements"
+				:validate-deps="[formData.accessibility]"
 			>
 				<CheckGroup
 					v-model="formData.accessibility"
@@ -84,6 +87,7 @@
 			<FormField
 				label="Email"
 				for="email"
+				:error="emailError"
 				description="We'll use this address for account notifications only."
 				docs-url="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email"
 				docs-url-title="HTML email input reference"
@@ -149,7 +153,7 @@
 				/>
 			</FormField>
 
-			<FormField label="Newsletters" fake>
+			<FormField label="Newsletters" component-has-label>
 				<div>
 					<label>
 						<input 
@@ -174,7 +178,8 @@
 			<FormField
 				label="Comments"
 				for="comments"
-				description="Optional feedback or notes about this submission."
+				:error="commentsError"
+				description="Optional feedback or notes about this submission (minimum 50 characters when provided)."
 			>
 				<textarea
 					id="comments"
@@ -222,13 +227,39 @@
 </template>
 
 <script setup>
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import Section from '../components/Section.vue'
 import FormLayout from '../components/FormLayout.vue'
 import FormField from '../components/FormField.vue'
 import RadioGroup from '../components/RadioGroup.vue'
 import CheckGroup from '../components/CheckGroup.vue'
 
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+const MIN_COMMENTS_LENGTH = 50
+
+function createDefaultFormData() {
+	return {
+		name: '',
+		role: '',
+		term: '',
+		salary: '0',
+		compensation: 'sales-target-incentive',
+		accessibility: ['screen-reader', 'high-contrast'],
+		email: 'not-an-email',
+		isAdmin: false,
+		website: '',
+		favouriteFood: '',
+		favouriteColour: '#dee3e7',
+		favouriteNumber: 50,
+		newsletter1: false,
+		newsletter2: false,
+		comments: 'Too short.',
+		readonlyText: 'This is a readonly textarea.',
+		disabledText: 'This is a disabled textarea.',
+		datetime: '',
+	}
+}
+
 // From femtocrank/tests/simple.html — Role (default), Term (boolean), Compensation (list)
 const roleOptions = [
 	{ label: 'Sales', value: 'sales' },
@@ -251,36 +282,52 @@ const accessibilityOptions = [
 	{ label: 'Screen reader support', value: 'screen-reader' },
 	{ label: 'Keyboard navigation', value: 'keyboard-navigation' },
 	{ label: 'High contrast', value: 'high-contrast' },
+	{ label: 'Low contrast UI', value: 'low-contrast' },
 	{ label: 'Captions / transcripts', value: 'captions' },
 ]
 
-const formData = ref({
-	name: '',
-	role: '',
-	term: '',
-	salary: '0',
-	compensation: '',
-	accessibility: [],
-	email: '',
-	isAdmin: false,
-	website: '',
-	favouriteFood: '',
-	favouriteColour: '#dee3e7',
-	favouriteNumber: 50,
-	newsletter1: false,
-	newsletter2: false,
-	comments: '',
-	readonlyText: 'This is a readonly textarea.',
-	disabledText: 'This is a disabled textarea.',
-	datetime: ''
+function validateAccessibilityRequirements() {
+	const selected = formData.value.accessibility
+	if (selected.includes('high-contrast') && selected.includes('low-contrast')) {
+		return 'High contrast and low contrast UI cannot both be selected.'
+	}
+	return ''
+}
+
+const formData = ref(createDefaultFormData())
+
+const emailError = computed(() => {
+	const email = formData.value.email.trim()
+	if (!email) {
+		return 'Email is required.'
+	}
+	if (!EMAIL_PATTERN.test(email)) {
+		return 'Enter a valid email address.'
+	}
+	return ''
+})
+
+const commentsError = computed(() => {
+	const comments = formData.value.comments.trim()
+	if (comments.length > 0 && comments.length < MIN_COMMENTS_LENGTH) {
+		return `Comments must be at least ${MIN_COMMENTS_LENGTH} characters.`
+	}
+	return ''
 })
 
 const submitted = ref(false)
 
-function handleSubmit() {
+function handleSubmit(event) {
+	if (!event.target.reportValidity()) {
+		return
+	}
+
+	if (validateAccessibilityRequirements()) {
+		return
+	}
+
 	submitted.value = true
 	console.log('Form submitted:', formData.value)
-	// In a real application, you would send this data to a server
 	alert('Form submitted! Check the console and the form result below.')
 }
 
@@ -290,26 +337,7 @@ function handleCancel() {
 }
 
 function resetForm() {
-	formData.value = {
-		name: '',
-		role: '',
-		term: '',
-		salary: '0',
-		compensation: '',
-		accessibility: [],
-		email: '',
-		isAdmin: false,
-		website: '',
-		favouriteFood: '',
-		favouriteColour: '#dee3e7',
-		favouriteNumber: 50,
-		newsletter1: false,
-		newsletter2: false,
-		comments: '',
-		readonlyText: 'This is a readonly textarea.',
-		disabledText: 'This is a disabled textarea.',
-		datetime: ''
-	}
+	formData.value = createDefaultFormData()
 	submitted.value = false
 }
 </script>

package/vue/examples/Login.vue

@@ -1,6 +1,7 @@
 <template>
 	<Section title="Login" classes="">
-		<Login 
+		<Login
+			ref="loginRef"
 			@local-login="handleLocalLogin"
 			@oauth-login="handleOAuthLogin"
 			@tab-change="onTabChange"
@@ -9,9 +10,12 @@
 </template>
 
 <script setup>
+import { ref } from 'vue';
 import Section from '../components/Section.vue';
 import Login from '../components/Login.vue';
 
+const loginRef = ref(null);
+
 // Handle local login
 function handleLocalLogin(credentials) {
 	console.log('Local login attempt:', {
@@ -41,6 +45,7 @@ function handleLocalLogin(credentials) {
 
 	// Placeholder success
 	alert(`Local login would authenticate: ${credentials.username}`);
+	loginRef.value?.setLocalLoginLoading(false);
 }
 
 // Handle OAuth login

package/vue/examples/LoginExample.vue

@@ -1,6 +1,33 @@
 <template>
-	<Section title="Login Example" subtitle="A reusable login form component with local and OAuth2 authentication">
-		<Login 
+	<Section title="Simple login" subtitle="Username and password only" classes="narrow">
+		<Login ref="simpleLoginRef" local-only @local-login="handleSimpleLocalLogin" />
+	</Section>
+
+	<Section
+		title="Simulated server response"
+		subtitle="Choose what the server returns when you submit the simple login form above"
+		classes="narrow"
+	>
+		<FormField label="Response" component-has-label description="Field errors appear on username or password; server and network errors appear below the form.">
+			<RadioGroup
+				v-model="simulatedResponse"
+				name="login-sim-response"
+				variant="list"
+				:options="simulatedResponseOptions"
+			/>
+		</FormField>
+
+		<FormField label="Timing" component-has-label>
+			<label class="simulate-delay-label">
+				<input v-model="simulateDelay" type="checkbox" />
+				<span>Simulate slow response (1.5s)</span>
+			</label>
+		</FormField>
+	</Section>
+
+	<Section title="Login example" subtitle="Local, OAuth2, and custom authentication tabs" classes="narrow">
+		<Login
+			ref="fullLoginRef"
 			:oauth-providers="oauthProviders"
 			:custom-tabs="customTabs"
 			@local-login="handleLocalLogin"
@@ -56,6 +83,67 @@
 import { ref } from 'vue';
 import Section from '../components/Section.vue';
 import Login from '../components/Login.vue';
+import FormField from '../components/FormField.vue';
+import RadioGroup from '../components/RadioGroup.vue';
+
+const simpleLoginRef = ref(null);
+const fullLoginRef = ref(null);
+const simulatedResponse = ref('success');
+const simulateDelay = ref(false);
+
+const simulatedResponseOptions = [
+	{ value: 'success', label: 'Success' },
+	{ value: 'wrong-password', label: 'Wrong password' },
+	{ value: 'username-not-found', label: 'Username not found' },
+	{ value: 'account-locked', label: 'Account locked' },
+	{ value: 'server-error', label: 'Server error (500)' },
+	{ value: 'network-error', label: 'Network unavailable' },
+];
+
+const simulatedResponseMessages = {
+	'wrong-password': 'Incorrect password.',
+	'username-not-found': 'No account found for that username.',
+	'account-locked': 'This account is locked. Contact support.',
+	'server-error': 'Sign-in failed. Please try again later.',
+	'network-error': 'Could not reach the server. Check your connection.',
+};
+
+const SIMULATED_DELAY_MS = 1500;
+
+function resolveSimulatedLoginErrors(responseKey) {
+	const message = simulatedResponseMessages[responseKey];
+	if (!message) {
+		return null;
+	}
+	if (responseKey === 'wrong-password') {
+		return { password: message };
+	}
+	if (responseKey === 'username-not-found') {
+		return { username: message };
+	}
+	return { form: message };
+}
+
+async function handleSimpleLocalLogin(credentials) {
+	try {
+		if (simulateDelay.value) {
+			await new Promise((resolve) => setTimeout(resolve, SIMULATED_DELAY_MS));
+		}
+
+		const errors = resolveSimulatedLoginErrors(simulatedResponse.value);
+		if (errors) {
+			simpleLoginRef.value?.setLocalLoginErrors(errors);
+			return;
+		}
+
+		simpleLoginRef.value?.resetLocalForm();
+		alert(`Signed in as ${credentials.username}`);
+	} catch {
+		simpleLoginRef.value?.setLocalLoginErrors({
+			form: 'Sign-in failed. Please try again later.',
+		});
+	}
+}
 
 // Custom tabs configuration
 const customTabs = ref([
@@ -151,6 +239,7 @@ function handleLocalLogin(credentials) {
 
 	// Placeholder success
 	alert(`Local login would authenticate: ${credentials.username}`);
+	fullLoginRef.value?.setLocalLoginLoading(false);
 }
 
 // Handle OAuth login
@@ -220,6 +309,13 @@ function handleSSOLogin(provider) {
 </script>
 
 <style scoped>
+.simulate-delay-label {
+	display: flex;
+	align-items: center;
+	gap: 0.5em;
+	cursor: pointer;
+}
+
 .magic-link-form,
 .sso-providers {
 	display: flex;

package/vue/examples/PageStructure.vue

@@ -11,7 +11,7 @@
 
 	<Section title="Header" subtitle="Branding, search, and top navigation">
 		<FormLayout @submit.prevent>
-			<FormField label="Logo and title" fake>
+			<FormField label="Logo and title" component-has-label>
 				<RadioGroup
 					name="ps-branding"
 					variant="boolean"
@@ -22,7 +22,7 @@
 				/>
 			</FormField>
 
-			<FormField label="QuickSearch" fake>
+			<FormField label="QuickSearch" component-has-label>
 				<RadioGroup
 					name="ps-quicksearch"
 					variant="boolean"
@@ -33,7 +33,7 @@
 				/>
 			</FormField>
 
-			<FormField label="Dummy background search" fake :disabled="!quickSearchEnabled">
+			<FormField label="Dummy background search" component-has-label :disabled="!quickSearchEnabled">
 				<div>
 					<RadioGroup
 						name="ps-dummy-search"
@@ -51,7 +51,7 @@
 				</div>
 			</FormField>
 
-			<FormField label="Dark/Light mode button" fake>
+			<FormField label="Dark/Light mode button" component-has-label>
 				<RadioGroup
 					name="ps-theme-toggle"
 					variant="boolean"
@@ -62,7 +62,7 @@
 				/>
 			</FormField>
 
-			<FormField label="Theme switcher" fake>
+			<FormField label="Theme switcher" component-has-label>
 				<RadioGroup
 					name="ps-theme-switcher"
 					variant="boolean"
@@ -73,7 +73,7 @@
 				/>
 			</FormField>
 
-			<FormField label="Top bar" fake>
+			<FormField label="Top bar" component-has-label>
 				<div>
 					<RadioGroup
 						name="ps-topbar"
@@ -92,7 +92,7 @@
 				</div>
 			</FormField>
 
-			<FormField label="Breadcrumbs" fake>
+			<FormField label="Breadcrumbs" component-has-label>
 				<RadioGroup
 					name="ps-breadcrumbs"
 					variant="boolean"
@@ -107,7 +107,7 @@
 
 	<Section title="Sidebar" subtitle="Primary navigation panel">
 		<FormLayout @submit.prevent>
-			<FormField label="Sidebar navigation" fake>
+			<FormField label="Sidebar navigation" component-has-label>
 				<div>
 					<RadioGroup
 						name="ps-sidebar"
@@ -124,7 +124,7 @@
 				</div>
 			</FormField>
 
-			<FormField label="Example link states" fake>
+			<FormField label="Example link states" component-has-label>
 				<div>
 					<RadioGroup
 						name="ps-example-links"

package/vue/examples/TableExample.vue

@@ -50,7 +50,7 @@
 		</template>
 
 		<FormLayout>
-			<FormField label="Data" fake description="Connect or disconnect row data for the table above. Saved column layouts persist in localStorage for this table.">
+			<FormField label="Data" component-has-label description="Connect or disconnect row data for the table above. Saved column layouts persist in localStorage for this table.">
 				<RadioGroup
 					v-model="dataConnected"
 					name="table-data-connection"
@@ -61,7 +61,7 @@
 
 			<FormField
 				label="Wide table"
-				fake
+				component-has-label
 				description="Adds extra columns (email, department, role, status) to the table."
 			>
 				<label>
@@ -70,7 +70,7 @@
 				</label>
 			</FormField>
 
-			<FormField label="Features" fake description="Toggle core table behaviour.">
+			<FormField label="Features" component-has-label description="Toggle core table behaviour.">
 				<CheckGroup
 					v-model="enabledFeatures"
 					name="table-features"
@@ -80,7 +80,7 @@
 
 			<FormField
 				label="Responsive layout"
-				fake
+				component-has-label
 				description="Column priorities hide lower-priority columns as the table narrows. Horizontal scroll keeps every column visible with optional sticky leading columns. Browser layout leaves column sizing to the viewport."
 			>
 				<RadioGroup
@@ -93,7 +93,7 @@
 			<FormField
 				v-if="layout === 'scroll'"
 				label="Sticky columns"
-				fake
+				component-has-label
 				description="Pin the first columns while scrolling horizontally."
 			>
 				<RadioGroup