@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.4

package/src/composables/useForm.ts

@@ -0,0 +1,279 @@
+import { ref, reactive, computed, toRaw, watch, type Ref } from 'vue'
+import { validateFieldValue, type FieldRules } from './useFormValidation'
+
+export type { FieldRules, ValidationRule } from './useFormValidation'
+
+/**
+ * Field validation rules configuration.
+ */
+export interface FieldState {
+  value: unknown
+  error: string | null
+  touched: boolean
+  dirty: boolean
+}
+
+/**
+ * Form state and methods.
+ */
+export interface UseFormReturn<T extends Record<string, unknown>> {
+  // Form data (reactive)
+  data: T
+
+  // Field errors
+  errors: Record<string, string | null>
+
+  // Field touched state
+  touched: Record<string, boolean>
+
+  // Field dirty state (value changed from initial)
+  dirty: Record<string, boolean>
+
+  // Overall form state
+  isValid: Ref<boolean>
+  isDirty: Ref<boolean>
+  isSubmitting: Ref<boolean>
+
+  // Methods
+  setFieldValue: <K extends keyof T>(field: K, value: T[K]) => void
+  setFieldError: (field: string, error: string | null) => void
+  setFieldTouched: (field: string, touched?: boolean) => void
+  validateField: (field: string) => boolean
+  validate: () => boolean
+  reset: (values?: Partial<T>) => void
+  /** Replace the full form state and treat the provided values as the new clean baseline. */
+  replaceState: (values: T) => void
+  handleSubmit: (onSubmit: (data: T) => Promise<void> | void) => (e?: Event) => Promise<void>
+  getFieldProps: <K extends keyof T>(field: K) => {
+    modelValue: T[K]
+    'onUpdate:modelValue': (value: T[K]) => void
+    onBlur: () => void
+    error: string | null
+  }
+}
+
+/**
+ * Form state management composable with validation.
+ *
+ * @param initialValues - Initial form values
+ * @param rules - Validation rules for each field
+ *
+ * @example
+ * ```typescript
+ * const { data, errors, isValid, handleSubmit, getFieldProps } = useForm(
+ *   { email: '', password: '' },
+ *   {
+ *     email: { required: true, email: true },
+ *     password: { required: true, minLength: 8 },
+ *   }
+ * )
+ *
+ * // In template
+ * <BaseInput v-bind="getFieldProps('email')" label="Email" />
+ * <BaseInput v-bind="getFieldProps('password')" type="password" label="Password" />
+ * <BaseButton @click="handleSubmit(onSubmit)" :disabled="!isValid">Submit</BaseButton>
+ * ```
+ */
+/** Reactive form state with field-level validation, dirty tracking, and submit handling. */
+export function useForm<T extends Record<string, unknown>>(
+  initialValues: T,
+  rules: Partial<Record<keyof T, FieldRules>> = {}
+): UseFormReturn<T> {
+  const cloneableInitialValues = deepToRaw(initialValues) as T
+
+  // Deep copy initial values so nested objects are not shared
+  let _initialValues = structuredClone(cloneableInitialValues)
+
+  // Reactive form data
+  const data = reactive(structuredClone(cloneableInitialValues)) as T
+
+  // Field state - use simple Record types for better TS compatibility
+  const errors = reactive<Record<string, string | null>>(
+    Object.keys(initialValues).reduce((acc, key) => {
+      acc[key] = null
+      return acc
+    }, {} as Record<string, string | null>)
+  )
+
+  const touched = reactive<Record<string, boolean>>(
+    Object.keys(initialValues).reduce((acc, key) => {
+      acc[key] = false
+      return acc
+    }, {} as Record<string, boolean>)
+  )
+
+  const dirty = reactive<Record<string, boolean>>(
+    Object.keys(initialValues).reduce((acc, key) => {
+      acc[key] = false
+      return acc
+    }, {} as Record<string, boolean>)
+  )
+
+  const isSubmitting = ref(false)
+
+  // Watch data changes to track dirty state
+  watch(
+    () => ({ ...data }),
+    (newData) => {
+      for (const key of Object.keys(newData)) {
+        dirty[key] = newData[key as keyof T] !== _initialValues[key as keyof T]
+      }
+    },
+    { deep: true }
+  )
+
+  // Validate a single field
+  function validateField(field: string): boolean {
+    const value = data[field as keyof T]
+    const fieldRules = rules[field as keyof T]
+    const error = validateFieldValue(value, fieldRules, data as Record<string, unknown>)
+    errors[field] = error
+    return error === null
+  }
+
+  // Validate all fields
+  function validate(): boolean {
+    let isAllValid = true
+    for (const field of Object.keys(data)) {
+      if (!validateField(field)) {
+        isAllValid = false
+      }
+    }
+    return isAllValid
+  }
+
+  // Computed overall validity
+  const isValid = computed(() => {
+    return Object.values(errors).every(error => error === null)
+  })
+
+  // Computed overall dirty state
+  const isDirty = computed(() => {
+    return Object.values(dirty).some(d => d)
+  })
+
+  // Set field value
+  function setFieldValue<K extends keyof T>(field: K, value: T[K]): void {
+    ;(data as Record<string, unknown>)[field as string] = value
+    if (touched[field as string]) {
+      validateField(field as string)
+    }
+  }
+
+  // Set field error
+  function setFieldError(field: string, error: string | null): void {
+    errors[field] = error
+  }
+
+  // Set field touched
+  function setFieldTouched(field: string, isTouched = true): void {
+    touched[field] = isTouched
+    if (isTouched) {
+      validateField(field)
+    }
+  }
+
+  // Reset form
+  function reset(values?: Partial<T>): void {
+    const resetValues = values ? { ..._initialValues, ...values } : _initialValues
+    for (const key of Object.keys(data)) {
+      ;(data as Record<string, unknown>)[key] = structuredClone(deepToRaw(resetValues[key as keyof T]))
+      errors[key] = null
+      touched[key] = false
+      dirty[key] = false
+    }
+  }
+
+  function replaceState(values: T): void {
+    const nextValues = structuredClone(deepToRaw(values)) as T
+    _initialValues = structuredClone(nextValues)
+
+    for (const key of Object.keys(data)) {
+      if (key in nextValues) continue
+      delete (data as Record<string, unknown>)[key]
+      delete errors[key]
+      delete touched[key]
+      delete dirty[key]
+    }
+
+    for (const key of Object.keys(nextValues)) {
+      ;(data as Record<string, unknown>)[key] = structuredClone(deepToRaw(nextValues[key as keyof T]))
+      errors[key] = null
+      touched[key] = false
+      dirty[key] = false
+    }
+  }
+
+  // Handle submit
+  function handleSubmit(onSubmit: (data: T) => Promise<void> | void) {
+    return async (e?: Event): Promise<void> => {
+      e?.preventDefault()
+
+      // Mark all fields as touched
+      for (const field of Object.keys(data)) {
+        touched[field] = true
+      }
+
+      if (!validate()) {
+        return
+      }
+
+      isSubmitting.value = true
+      try {
+        await onSubmit(data)
+      } finally {
+        isSubmitting.value = false
+      }
+    }
+  }
+
+  // Get props for a field (for v-bind)
+  function getFieldProps<K extends keyof T>(field: K) {
+    const fieldStr = field as string
+    return {
+      modelValue: data[field],
+      'onUpdate:modelValue': (value: T[K]) => setFieldValue(field, value),
+      onBlur: () => setFieldTouched(fieldStr),
+      error: touched[fieldStr] ? errors[fieldStr] : null,
+    }
+  }
+
+  return {
+    data,
+    errors,
+    touched,
+    dirty,
+    isValid,
+    isDirty,
+    isSubmitting,
+    setFieldValue,
+    setFieldError,
+    setFieldTouched,
+    validateField,
+    validate,
+    reset,
+    replaceState,
+    handleSubmit,
+    getFieldProps,
+  }
+}
+
+function deepToRaw(value: unknown): unknown {
+  const raw = toRaw(value)
+
+  if (Array.isArray(raw)) {
+    return raw.map(item => deepToRaw(item))
+  }
+
+  if (isPlainRecord(raw)) {
+    return Object.fromEntries(
+      Object.entries(raw).map(([key, item]) => [key, deepToRaw(item)])
+    )
+  }
+
+  return raw
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return Object.prototype.toString.call(value) === '[object Object]'
+}

package/src/composables/useFormBuilder.ts

@@ -0,0 +1,292 @@
+import { reactive, ref, computed, shallowRef, watch } from 'vue'
+import { useForm, type FieldRules, type UseFormReturn } from './useForm'
+import { getFieldRegistryEntry } from './formBuilderRegistry'
+import {
+  buildInitialValues,
+  buildRules,
+  collectSections,
+  evaluateCondition,
+  flattenFields,
+  replaceArray,
+  replaceRecord,
+} from './formBuilderSchema'
+import type {
+  FormSchema,
+  FormFieldSchema,
+  FormSectionSchema,
+  FormOptionInput,
+  FormEnhancements,
+  UseFormBuilderReturn,
+} from '../types/form-builder'
+
+export { evaluateCondition } from './formBuilderSchema'
+
+// ---------------------------------------------------------------------------
+// useFormBuilder
+// ---------------------------------------------------------------------------
+
+/**
+ * Drive a `FormSchema` as reactive form state.
+ *
+ * Builds initial values from schema defaults and `initialData`, derives
+ * validation rules from `FieldValidation` descriptors and enhancement
+ * validators, evaluates `FieldCondition` expressions for field/section
+ * visibility, and wires wizard step navigation when `schema.steps` is set.
+ *
+ * @param schema - Declarative form or wizard schema.
+ * @param initialData - Values that override schema defaults.
+ * @param enhancements - TypeScript-only callbacks (dynamic options, validators,
+ *   submit handler, transform, field-change watcher).
+ */
+/** Drives a declarative FormSchema as reactive state with conditional fields, wizard steps, and validation. */
+export function useFormBuilder<T extends Record<string, unknown> = Record<string, unknown>>(
+  schema: FormSchema,
+  initialData?: Partial<T>,
+  enhancements?: FormEnhancements<T>,
+): UseFormBuilderReturn<T> {
+  const currentSchema = shallowRef(schema)
+  const fields = reactive<FormFieldSchema[]>(flattenFields(schema))
+  const sections = reactive<FormSectionSchema[]>(collectSections(schema))
+  const rules = reactive<Partial<Record<string, FieldRules>>>(buildRules(fields, enhancements))
+
+  // -- Create form -----------------------------------------------------------
+  const form = useForm(
+    buildInitialValues<T>(fields, initialData) as T,
+    rules as Partial<Record<keyof T, FieldRules>>,
+  )
+
+  // -- Visibility ------------------------------------------------------------
+  function isFieldVisible(name: string): boolean {
+    const enhancement = enhancements?.fields?.[name as keyof T]
+    if (enhancement?.visible) {
+      return enhancement.visible(form.data as T)
+    }
+
+    const field = fields.find((f) => f.name === name)
+    if (field?.condition) {
+      return evaluateCondition(field.condition, form.data as Record<string, unknown>)
+    }
+
+    return true
+  }
+
+  function isSectionVisible(id: string): boolean {
+    const section = sections.find((s) => s.id === id)
+    if (section?.condition) {
+      return evaluateCondition(section.condition, form.data as Record<string, unknown>)
+    }
+    return true
+  }
+
+  // -- Resolved field props --------------------------------------------------
+  function getResolvedFieldProps(field: FormFieldSchema): Record<string, unknown> {
+    const entry = getFieldRegistryEntry(field.type)
+    const formProps = form.getFieldProps(field.name as keyof T)
+
+    const merged: Record<string, unknown> = {
+      ...entry.defaults,
+      ...(field.props ?? {}),
+    }
+
+    // Dynamic enhancement props
+    const enhancement = enhancements?.fields?.[field.name as keyof T]
+    if (enhancement?.props) {
+      Object.assign(merged, enhancement.props(form.data as T))
+    }
+
+    // Dynamic options
+    const options = getFieldOptions(field.name)
+    if (options) {
+      merged.options = options
+    }
+
+    // Form field bindings
+    if (entry.vModel) {
+      merged.modelValue = formProps.modelValue
+      merged['onUpdate:modelValue'] = formProps['onUpdate:modelValue']
+    }
+    merged.onBlur = formProps.onBlur
+
+    // Error as boolean for components that use boolean error prop
+    const errorMsg = formProps.error
+    if (errorMsg) {
+      merged.error = true
+    }
+
+    // Schema-level props
+    if (field.placeholder) merged.placeholder = field.placeholder
+    if (field.size) merged.size = field.size
+    if (field.disabled) merged.disabled = true
+    if (field.readonly) merged.readonly = true
+
+    // Radio group needs a name prop
+    if (field.type === 'radio' && !merged.name) {
+      merged.name = field.name
+    }
+
+    return merged
+  }
+
+  function getFieldOptions(name: string): FormOptionInput[] | undefined {
+    const enhancement = enhancements?.fields?.[name as keyof T]
+    if (enhancement?.options) {
+      return enhancement.options(form.data as T)
+    }
+
+    const field = fields.find((f) => f.name === name)
+    if (field?.props?.options) {
+      return field.props.options as FormOptionInput[]
+    }
+
+    return undefined
+  }
+
+  // -- Wizard state ----------------------------------------------------------
+  const currentStep = ref(0)
+
+  const isCurrentStepValid = computed(() => {
+    if (!currentSchema.value.steps) return form.isValid.value
+
+    const step = currentSchema.value.steps[currentStep.value]
+    if (!step) return true
+
+    for (const section of step.sections) {
+      if (!isSectionVisible(section.id)) continue
+      for (const field of section.fields) {
+        if (!isFieldVisible(field.name)) continue
+        if (!form.validateField(field.name)) return false
+      }
+    }
+    return true
+  })
+
+  function goNext(): boolean {
+    if (!currentSchema.value.steps) return false
+
+    // Touch and validate all visible fields in current step
+    const step = currentSchema.value.steps[currentStep.value]
+    if (!step) return false
+
+    let valid = true
+    for (const section of step.sections) {
+      if (!isSectionVisible(section.id)) continue
+      for (const field of section.fields) {
+        if (!isFieldVisible(field.name)) continue
+        form.setFieldTouched(field.name, true)
+        if (!form.validateField(field.name)) valid = false
+      }
+    }
+
+    if (!valid) return false
+
+    if (currentStep.value < currentSchema.value.steps.length - 1) {
+      currentStep.value++
+    }
+    return true
+  }
+
+  function goBack(): void {
+    if (currentStep.value > 0) {
+      currentStep.value--
+    }
+  }
+
+  function goToStep(index: number): void {
+    if (!currentSchema.value.steps) return
+    if (index >= 0 && index < currentSchema.value.steps.length) {
+      currentStep.value = index
+    }
+  }
+
+  // -- Validate (skip hidden fields) -----------------------------------------
+  function validate(): boolean {
+    let allValid = true
+    for (const field of fields) {
+      if (!isFieldVisible(field.name)) continue
+      form.setFieldTouched(field.name, true)
+      if (!form.validateField(field.name)) {
+        allValid = false
+      }
+    }
+    return allValid
+  }
+
+  // -- Submit ----------------------------------------------------------------
+  async function submit(): Promise<void> {
+    if (!validate()) return
+
+    // Build submission data excluding hidden fields
+    let submitData = {} as Record<string, unknown>
+    for (const field of fields) {
+      if (isFieldVisible(field.name)) {
+        submitData[field.name] = (form.data as Record<string, unknown>)[field.name]
+      }
+    }
+
+    if (enhancements?.transform) {
+      submitData = enhancements.transform(submitData as T) as Record<string, unknown>
+    }
+
+    if (enhancements?.onSubmit) {
+      form.isSubmitting.value = true
+      try {
+        await enhancements.onSubmit(submitData as T)
+      } finally {
+        form.isSubmitting.value = false
+      }
+    }
+  }
+
+  // -- Reset -----------------------------------------------------------------
+  function reset(values?: Partial<T>): void {
+    form.reset(values)
+    currentStep.value = 0
+  }
+
+  function updateSchema(nextSchema: FormSchema, nextData?: Partial<T>): void {
+    currentSchema.value = nextSchema
+
+    const nextFields = flattenFields(nextSchema)
+    replaceArray(fields, nextFields)
+    replaceArray(sections, collectSections(nextSchema))
+    replaceRecord(rules, buildRules(nextFields, enhancements))
+    form.replaceState(buildInitialValues<T>(nextFields, nextData) as T)
+    currentStep.value = 0
+  }
+
+  // -- onFieldChange wiring --------------------------------------------------
+  if (enhancements?.onFieldChange) {
+    const callback = enhancements.onFieldChange
+    watch(
+      () => ({ ...(form.data as Record<string, unknown>) }),
+      (newData, oldData) => {
+        if (!oldData) return
+        for (const key of Object.keys(newData)) {
+          if (newData[key] !== oldData[key]) {
+            callback(key as keyof T, newData[key], newData as T)
+          }
+        }
+      },
+      { deep: true },
+    )
+  }
+
+  return {
+    form: form as UseFormReturn<T>,
+    rules: rules as Partial<Record<keyof T, FieldRules>>,
+    isFieldVisible,
+    isSectionVisible,
+    fields,
+    getResolvedFieldProps,
+    getFieldOptions,
+    currentStep,
+    isCurrentStepValid,
+    goNext,
+    goBack,
+    goToStep,
+    validate,
+    reset,
+    submit,
+    updateSchema,
+  }
+}