@htlkg/components 0.0.2 → 0.0.4

package/src/composables/useWizard.ts

@@ -0,0 +1,448 @@
+/**
+ * Wizard Composable
+ *
+ * Manages multi-step form/wizard state with validation support.
+ * Integrates with Stepper component and JsonSchemaForm.
+ */
+
+import { ref, computed, type Ref, type ComputedRef, type Component } from 'vue';
+
+/**
+ * JSON Schema type for form validation
+ */
+export interface JsonSchema {
+	type: string;
+	properties?: Record<string, any>;
+	required?: string[];
+	title?: string;
+	description?: string;
+}
+
+/**
+ * Step definition for the wizard
+ */
+export interface WizardStep<T = any> {
+	/** Unique step identifier */
+	id: string;
+	/** Display label for the step */
+	label: string;
+	/** Optional description */
+	description?: string;
+	/** JSON Schema for JsonSchemaForm (optional) */
+	schema?: JsonSchema;
+	/** Custom validation function (optional) */
+	validate?: (data: T) => boolean | Promise<boolean>;
+	/** Icon component for the step (optional) */
+	icon?: Component;
+	/** Whether step can be skipped */
+	optional?: boolean;
+}
+
+/**
+ * Step status for Stepper component
+ */
+export type StepStatus = 'complete' | 'current' | 'upcoming' | 'error';
+
+/**
+ * Stepper-compatible step format
+ */
+export interface StepperStep {
+	id: string;
+	label: string;
+	status: StepStatus;
+	valid?: boolean;
+}
+
+/**
+ * Options for useWizard
+ */
+export interface UseWizardOptions<T extends Record<string, any>> {
+	/** Step definitions */
+	steps: WizardStep<T>[];
+	/** Initial form data */
+	initialData?: Partial<T>;
+	/** Callback when wizard completes */
+	onComplete?: (data: T) => void | Promise<void>;
+	/** Callback when step changes */
+	onStepChange?: (fromIndex: number, toIndex: number, data: T) => void;
+	/** Whether to validate before advancing */
+	validateOnNext?: boolean;
+	/** Whether to allow going back without validation */
+	allowBackWithoutValidation?: boolean;
+}
+
+/**
+ * Return type for useWizard
+ */
+export interface UseWizardReturn<T extends Record<string, any>> {
+	// State
+	currentStepIndex: Ref<number>;
+	currentStep: ComputedRef<WizardStep<T>>;
+	data: Ref<Partial<T>>;
+	isFirstStep: ComputedRef<boolean>;
+	isLastStep: ComputedRef<boolean>;
+	isCompleting: Ref<boolean>;
+	stepErrors: Ref<Record<string, string>>;
+
+	// For Stepper component
+	stepperSteps: ComputedRef<StepperStep[]>;
+
+	// Validation state
+	stepValidation: Ref<Record<string, boolean>>;
+	currentStepValid: ComputedRef<boolean>;
+	allStepsValid: ComputedRef<boolean>;
+
+	// Navigation
+	goToNext: () => Promise<boolean>;
+	goToPrevious: () => boolean;
+	goToStep: (index: number) => Promise<boolean>;
+	canGoToStep: (index: number) => boolean;
+
+	// Data management
+	updateData: (newData: Partial<T>) => void;
+	updateStepData: (stepId: string, stepData: Partial<T>) => void;
+	setStepValid: (stepId: string, valid: boolean) => void;
+	setStepError: (stepId: string, error: string | null) => void;
+	resetStep: (stepId: string) => void;
+	reset: () => void;
+
+	// Completion
+	complete: () => Promise<boolean>;
+
+	// Utilities
+	getStepIndex: (stepId: string) => number;
+	getStep: (stepId: string) => WizardStep<T> | undefined;
+	progress: ComputedRef<number>;
+}
+
+/**
+ * Creates a wizard composable for managing multi-step forms
+ *
+ * @example
+ * ```typescript
+ * const wizard = useWizard({
+ *   steps: [
+ *     { id: 'details', label: 'Details', schema: detailsSchema },
+ *     { id: 'audience', label: 'Audience', schema: audienceSchema },
+ *     { id: 'review', label: 'Review' },
+ *   ],
+ *   initialData: { name: '', audience: [] },
+ *   onComplete: async (data) => {
+ *     await createCampaign(data);
+ *   },
+ * });
+ *
+ * // In template
+ * <Stepper :steps="wizard.stepperSteps" v-model:currentStep="wizard.currentStepIndex" />
+ * <JsonSchemaForm
+ *   v-if="wizard.currentStep.schema"
+ *   :schema="wizard.currentStep.schema"
+ *   v-model="wizard.data"
+ * />
+ * <button @click="wizard.goToPrevious" :disabled="wizard.isFirstStep">Back</button>
+ * <button @click="wizard.goToNext" v-if="!wizard.isLastStep">Next</button>
+ * <button @click="wizard.complete" v-else :disabled="wizard.isCompleting">Complete</button>
+ * ```
+ */
+export function useWizard<T extends Record<string, any>>(
+	options: UseWizardOptions<T>
+): UseWizardReturn<T> {
+	const {
+		steps,
+		initialData = {} as Partial<T>,
+		onComplete,
+		onStepChange,
+		validateOnNext = true,
+		allowBackWithoutValidation = true,
+	} = options;
+
+	// Core state
+	const currentStepIndex = ref(0);
+	const data = ref<Partial<T>>({ ...initialData }) as Ref<Partial<T>>;
+	const isCompleting = ref(false);
+	const stepValidation = ref<Record<string, boolean>>({});
+	const stepErrors = ref<Record<string, string>>({});
+
+	// Computed: Current step
+	const currentStep = computed(() => steps[currentStepIndex.value]);
+
+	// Computed: Navigation flags
+	const isFirstStep = computed(() => currentStepIndex.value === 0);
+	const isLastStep = computed(() => currentStepIndex.value === steps.length - 1);
+
+	// Computed: Progress percentage
+	const progress = computed(() =>
+		Math.round(((currentStepIndex.value + 1) / steps.length) * 100)
+	);
+
+	// Computed: Current step validation status
+	const currentStepValid = computed(() => {
+		const step = currentStep.value;
+		if (!step) return false;
+		if (step.optional) return true;
+		return stepValidation.value[step.id] !== false;
+	});
+
+	// Computed: All required steps valid
+	const allStepsValid = computed(() => {
+		return steps.every(step => {
+			if (step.optional) return true;
+			return stepValidation.value[step.id] === true;
+		});
+	});
+
+	// Computed: Steps formatted for Stepper component
+	const stepperSteps = computed<StepperStep[]>(() =>
+		steps.map((step, index) => {
+			let status: StepStatus;
+
+			if (index < currentStepIndex.value) {
+				status = stepValidation.value[step.id] === false ? 'error' : 'complete';
+			} else if (index === currentStepIndex.value) {
+				status = 'current';
+			} else {
+				status = 'upcoming';
+			}
+
+			return {
+				id: step.id,
+				label: step.label,
+				status,
+				valid: stepValidation.value[step.id] ?? true,
+			};
+		})
+	);
+
+	// Utility: Get step index by ID
+	function getStepIndex(stepId: string): number {
+		return steps.findIndex(s => s.id === stepId);
+	}
+
+	// Utility: Get step by ID
+	function getStep(stepId: string): WizardStep<T> | undefined {
+		return steps.find(s => s.id === stepId);
+	}
+
+	// Validate a specific step
+	async function validateStep(stepIndex: number): Promise<boolean> {
+		const step = steps[stepIndex];
+		if (!step) return false;
+
+		// Optional steps are always valid
+		if (step.optional) {
+			stepValidation.value[step.id] = true;
+			return true;
+		}
+
+		// Custom validation function
+		if (step.validate) {
+			try {
+				const result = await step.validate(data.value as T);
+				stepValidation.value[step.id] = result;
+				if (!result) {
+					stepErrors.value[step.id] = 'Validation failed';
+				} else {
+					delete stepErrors.value[step.id];
+				}
+				return result;
+			} catch (error) {
+				stepValidation.value[step.id] = false;
+				stepErrors.value[step.id] = error instanceof Error ? error.message : 'Validation error';
+				return false;
+			}
+		}
+
+		// If no custom validation, check if step was marked valid
+		// Default to true if not explicitly set
+		if (stepValidation.value[step.id] === undefined) {
+			stepValidation.value[step.id] = true;
+		}
+
+		return stepValidation.value[step.id] !== false;
+	}
+
+	// Check if navigation to step is allowed
+	function canGoToStep(targetIndex: number): boolean {
+		if (targetIndex < 0 || targetIndex >= steps.length) return false;
+
+		// Can always go back if allowed
+		if (targetIndex < currentStepIndex.value && allowBackWithoutValidation) {
+			return true;
+		}
+
+		// For forward navigation, all previous steps must be valid
+		if (targetIndex > currentStepIndex.value && validateOnNext) {
+			for (let i = 0; i < targetIndex; i++) {
+				const step = steps[i];
+				if (!step.optional && stepValidation.value[step.id] === false) {
+					return false;
+				}
+			}
+		}
+
+		return true;
+	}
+
+	// Navigation: Go to next step
+	async function goToNext(): Promise<boolean> {
+		if (isLastStep.value) return false;
+
+		// Validate current step before advancing
+		if (validateOnNext) {
+			const isValid = await validateStep(currentStepIndex.value);
+			if (!isValid) return false;
+		}
+
+		const fromIndex = currentStepIndex.value;
+		currentStepIndex.value++;
+
+		onStepChange?.(fromIndex, currentStepIndex.value, data.value as T);
+		return true;
+	}
+
+	// Navigation: Go to previous step
+	function goToPrevious(): boolean {
+		if (isFirstStep.value) return false;
+
+		const fromIndex = currentStepIndex.value;
+		currentStepIndex.value--;
+
+		onStepChange?.(fromIndex, currentStepIndex.value, data.value as T);
+		return true;
+	}
+
+	// Navigation: Go to specific step
+	async function goToStep(targetIndex: number): Promise<boolean> {
+		if (!canGoToStep(targetIndex)) return false;
+
+		// If going forward, validate current step
+		if (targetIndex > currentStepIndex.value && validateOnNext) {
+			const isValid = await validateStep(currentStepIndex.value);
+			if (!isValid) return false;
+		}
+
+		const fromIndex = currentStepIndex.value;
+		currentStepIndex.value = targetIndex;
+
+		onStepChange?.(fromIndex, currentStepIndex.value, data.value as T);
+		return true;
+	}
+
+	// Data: Update wizard data
+	function updateData(newData: Partial<T>): void {
+		data.value = { ...data.value, ...newData };
+	}
+
+	// Data: Update data for a specific step
+	function updateStepData(stepId: string, stepData: Partial<T>): void {
+		updateData(stepData);
+		// Clear error when data is updated
+		delete stepErrors.value[stepId];
+	}
+
+	// Validation: Set step validation status
+	function setStepValid(stepId: string, valid: boolean): void {
+		stepValidation.value[stepId] = valid;
+		if (valid) {
+			delete stepErrors.value[stepId];
+		}
+	}
+
+	// Validation: Set step error
+	function setStepError(stepId: string, error: string | null): void {
+		if (error) {
+			stepErrors.value[stepId] = error;
+			stepValidation.value[stepId] = false;
+		} else {
+			delete stepErrors.value[stepId];
+		}
+	}
+
+	// Reset: Reset a specific step
+	function resetStep(stepId: string): void {
+		delete stepValidation.value[stepId];
+		delete stepErrors.value[stepId];
+	}
+
+	// Reset: Reset entire wizard
+	function reset(): void {
+		currentStepIndex.value = 0;
+		data.value = { ...initialData };
+		stepValidation.value = {};
+		stepErrors.value = {};
+		isCompleting.value = false;
+	}
+
+	// Complete: Validate all and trigger completion
+	async function complete(): Promise<boolean> {
+		if (isCompleting.value) return false;
+
+		isCompleting.value = true;
+
+		try {
+			// Validate all steps
+			for (let i = 0; i < steps.length; i++) {
+				const isValid = await validateStep(i);
+				if (!isValid && !steps[i].optional) {
+					// Navigate to failed step
+					currentStepIndex.value = i;
+					isCompleting.value = false;
+					return false;
+				}
+			}
+
+			// Call completion handler
+			if (onComplete) {
+				await onComplete(data.value as T);
+			}
+
+			return true;
+		} catch (error) {
+			console.error('[useWizard] Completion error:', error);
+			return false;
+		} finally {
+			isCompleting.value = false;
+		}
+	}
+
+	return {
+		// State
+		currentStepIndex,
+		currentStep,
+		data,
+		isFirstStep,
+		isLastStep,
+		isCompleting,
+		stepErrors,
+
+		// Stepper integration
+		stepperSteps,
+
+		// Validation
+		stepValidation,
+		currentStepValid,
+		allStepsValid,
+
+		// Navigation
+		goToNext,
+		goToPrevious,
+		goToStep,
+		canGoToStep,
+
+		// Data management
+		updateData,
+		updateStepData,
+		setStepValid,
+		setStepError,
+		resetStep,
+		reset,
+
+		// Completion
+		complete,
+
+		// Utilities
+		getStepIndex,
+		getStep,
+		progress,
+	};
+}