@morscherlab/mint-sdk 1.0.0-beta.2 → 1.0.0-beta.4

package/src/composables/useForm.ts

@@ -1,4 +1,4 @@
-import { ref, reactive, computed, watch, type Ref } from 'vue'
+import { ref, reactive, computed, toRaw, watch, type Ref } from 'vue'
 
 /**
  * Validation rule function type.
@@ -58,6 +58,8 @@ export interface UseFormReturn<T extends Record<string, unknown>> {
   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]
@@ -156,11 +158,13 @@ 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
-  const _initialValues = structuredClone(initialValues)
+  let _initialValues = structuredClone(cloneableInitialValues)
 
   // Reactive form data
-  const data = reactive(structuredClone(initialValues)) as T
+  const data = reactive(structuredClone(cloneableInitialValues)) as T
 
   // Field state - use simple Record types for better TS compatibility
   const errors = reactive<Record<string, string | null>>(
@@ -355,7 +359,27 @@ export function useForm<T extends Record<string, unknown>>(
   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(resetValues[key as keyof T])
+      ;(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
@@ -410,7 +434,28 @@ export function useForm<T extends Record<string, unknown>>(
     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

@@ -1,4 +1,4 @@
-import { ref, computed, watch } from 'vue'
+import { reactive, ref, computed, shallowRef, watch } from 'vue'
 import { useForm, type FieldRules, type UseFormReturn } from './useForm'
 import { getFieldRegistryEntry, getTypeDefault } from './formBuilderRegistry'
 import type {
@@ -7,6 +7,7 @@ import type {
   FormSectionSchema,
   FieldCondition,
   FieldValidation,
+  FormOptionInput,
   FormEnhancements,
   UseFormBuilderReturn,
 } from '../types/form-builder'
@@ -92,37 +93,15 @@ function convertValidation(v: FieldValidation): FieldRules {
   return rules
 }
 
-// ---------------------------------------------------------------------------
-// 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,
+function buildInitialValues<T extends Record<string, unknown>>(
+  fields: readonly FormFieldSchema[],
   initialData?: Partial<T>,
-  enhancements?: FormEnhancements<T>,
-): UseFormBuilderReturn<T> {
-  const fields = flattenFields(schema)
-  const sections = collectSections(schema)
-
-  // -- Build initial values --------------------------------------------------
+): Record<string, unknown> {
   const initialValues = {} as Record<string, unknown>
+
   for (const field of fields) {
     const key = field.name
-    if (initialData && key in initialData) {
+    if (initialData && hasOwnKey(initialData, key)) {
       initialValues[key] = (initialData as Record<string, unknown>)[key]
     } else if (field.defaultValue !== undefined) {
       initialValues[key] = field.defaultValue
@@ -131,14 +110,23 @@ export function useFormBuilder<T extends Record<string, unknown> = Record<string
     }
   }
 
-  // -- Build validation rules ------------------------------------------------
+  return initialValues
+}
+
+function buildRules<T extends Record<string, unknown>>(
+  fields: readonly FormFieldSchema[],
+  enhancements?: FormEnhancements<T>,
+): Partial<Record<string, FieldRules>> {
   const rules: Partial<Record<string, FieldRules>> = {}
+
   for (const field of fields) {
     const base: FieldRules = field.validation ? convertValidation(field.validation) : {}
     const enhancement = enhancements?.fields?.[field.name as keyof T]
 
-    // Wrap validators to skip hidden fields
-    const customValidators: Array<(value: unknown, formData: Record<string, unknown>) => string | undefined | null> = []
+    const customValidators: Array<(
+      value: unknown,
+      formData: Record<string, unknown>,
+    ) => string | undefined | null> = []
 
     if (enhancement?.validate) {
       const fn = enhancement.validate
@@ -149,14 +137,65 @@ export function useFormBuilder<T extends Record<string, unknown> = Record<string
       base.custom = customValidators
     }
 
-    // Wrap all rules to skip hidden fields
     if (Object.keys(base).length > 0) {
       rules[field.name] = base
     }
   }
 
+  return rules
+}
+
+function replaceArray<T>(target: T[], values: readonly T[]): void {
+  target.splice(0, target.length, ...values)
+}
+
+function replaceRecord<TValue>(
+  target: Partial<Record<string, TValue>>,
+  source: Partial<Record<string, TValue>>,
+): void {
+  for (const key of Object.keys(target)) {
+    delete target[key]
+  }
+  Object.assign(target, source)
+}
+
+function hasOwnKey(source: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(source, key)
+}
+
+// ---------------------------------------------------------------------------
+// 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(initialValues as T, rules as Partial<Record<keyof T, FieldRules>>)
+  const form = useForm(
+    buildInitialValues<T>(fields, initialData) as T,
+    rules as Partial<Record<keyof T, FieldRules>>,
+  )
 
   // -- Visibility ------------------------------------------------------------
   function isFieldVisible(name: string): boolean {
@@ -230,7 +269,7 @@ export function useFormBuilder<T extends Record<string, unknown> = Record<string
     return merged
   }
 
-  function getFieldOptions(name: string): { label: string; value: unknown }[] | undefined {
+  function getFieldOptions(name: string): FormOptionInput[] | undefined {
     const enhancement = enhancements?.fields?.[name as keyof T]
     if (enhancement?.options) {
       return enhancement.options(form.data as T)
@@ -238,7 +277,7 @@ export function useFormBuilder<T extends Record<string, unknown> = Record<string
 
     const field = fields.find((f) => f.name === name)
     if (field?.props?.options) {
-      return field.props.options as { label: string; value: unknown }[]
+      return field.props.options as FormOptionInput[]
     }
 
     return undefined
@@ -248,9 +287,9 @@ export function useFormBuilder<T extends Record<string, unknown> = Record<string
   const currentStep = ref(0)
 
   const isCurrentStepValid = computed(() => {
-    if (!schema.steps) return form.isValid.value
+    if (!currentSchema.value.steps) return form.isValid.value
 
-    const step = schema.steps[currentStep.value]
+    const step = currentSchema.value.steps[currentStep.value]
     if (!step) return true
 
     for (const section of step.sections) {
@@ -264,10 +303,10 @@ export function useFormBuilder<T extends Record<string, unknown> = Record<string
   })
 
   function goNext(): boolean {
-    if (!schema.steps) return false
+    if (!currentSchema.value.steps) return false
 
     // Touch and validate all visible fields in current step
-    const step = schema.steps[currentStep.value]
+    const step = currentSchema.value.steps[currentStep.value]
     if (!step) return false
 
     let valid = true
@@ -282,7 +321,7 @@ export function useFormBuilder<T extends Record<string, unknown> = Record<string
 
     if (!valid) return false
 
-    if (currentStep.value < schema.steps.length - 1) {
+    if (currentStep.value < currentSchema.value.steps.length - 1) {
       currentStep.value++
     }
     return true
@@ -295,8 +334,8 @@ export function useFormBuilder<T extends Record<string, unknown> = Record<string
   }
 
   function goToStep(index: number): void {
-    if (!schema.steps) return
-    if (index >= 0 && index < schema.steps.length) {
+    if (!currentSchema.value.steps) return
+    if (index >= 0 && index < currentSchema.value.steps.length) {
       currentStep.value = index
     }
   }
@@ -346,6 +385,17 @@ export function useFormBuilder<T extends Record<string, unknown> = Record<string
     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
@@ -379,5 +429,6 @@ export function useFormBuilder<T extends Record<string, unknown> = Record<string
     validate,
     reset,
     submit,
+    updateSchema,
   }
 }

package/src/composables/useGroupAssignment.ts

@@ -0,0 +1,148 @@
+import { computed, toValue, type ComputedRef, type Ref } from 'vue'
+import type { GroupItem } from '../types'
+
+export type GroupAssignmentZone = 'zone1' | 'zone2'
+
+export type GroupAssignmentSource<T> =
+  | T
+  | Ref<T>
+  | ComputedRef<T>
+  | (() => T)
+
+export interface GroupAssignmentState {
+  group1: string[]
+  group2: string[]
+}
+
+export interface UseGroupAssignmentOptions {
+  groups: GroupAssignmentSource<readonly GroupItem[]>
+  group1: GroupAssignmentSource<readonly string[]>
+  group2: GroupAssignmentSource<readonly string[]>
+  label1?: GroupAssignmentSource<string | null | undefined>
+  label2?: GroupAssignmentSource<string | null | undefined>
+  minPerGroup?: GroupAssignmentSource<number | null | undefined>
+}
+
+export interface UseGroupAssignmentReturn {
+  unassignedGroups: ComputedRef<GroupItem[]>
+  zone1Groups: ComputedRef<GroupItem[]>
+  zone2Groups: ComputedRef<GroupItem[]>
+  zone1Count: ComputedRef<number>
+  zone2Count: ComputedRef<number>
+  isValid: ComputedRef<boolean>
+  validationMessage: ComputedRef<string | null>
+  getZoneForGroup: (groupName: string) => GroupAssignmentZone | null
+  assignToZone: (groupName: string, zone: GroupAssignmentZone) => GroupAssignmentState
+  removeFromZone: (groupName: string, zone: GroupAssignmentZone) => GroupAssignmentState
+  clearAll: () => GroupAssignmentState
+}
+
+/** Shared two-zone group assignment model for control/treatment style workflows. */
+export function useGroupAssignment(options: UseGroupAssignmentOptions): UseGroupAssignmentReturn {
+  const groups = computed(() => [...toValue(options.groups)])
+  const group1 = computed(() => [...toValue(options.group1)])
+  const group2 = computed(() => [...toValue(options.group2)])
+  const label1 = computed(() => toValue(options.label1) || 'Control')
+  const label2 = computed(() => toValue(options.label2) || 'Treatment')
+  const minPerGroup = computed(() => normalizeMinimum(toValue(options.minPerGroup)))
+  const group1Set = computed(() => new Set(group1.value))
+  const group2Set = computed(() => new Set(group2.value))
+
+  const unassignedGroups = computed(() =>
+    groups.value.filter(group => !group1Set.value.has(group.name) && !group2Set.value.has(group.name))
+  )
+
+  const zone1Groups = computed(() =>
+    groups.value.filter(group => group1Set.value.has(group.name))
+  )
+
+  const zone2Groups = computed(() =>
+    groups.value.filter(group => group2Set.value.has(group.name))
+  )
+
+  const zone1Count = computed(() =>
+    zone1Groups.value.reduce((sum, group) => sum + group.count, 0)
+  )
+
+  const zone2Count = computed(() =>
+    zone2Groups.value.reduce((sum, group) => sum + group.count, 0)
+  )
+
+  const isValid = computed(() =>
+    group1.value.length >= minPerGroup.value &&
+    group2.value.length >= minPerGroup.value
+  )
+
+  const validationMessage = computed(() => {
+    if (isValid.value) return null
+    const missing1 = Math.max(0, minPerGroup.value - group1.value.length)
+    const missing2 = Math.max(0, minPerGroup.value - group2.value.length)
+    const parts: string[] = []
+    if (missing1 > 0) parts.push(`${missing1} more to ${label1.value}`)
+    if (missing2 > 0) parts.push(`${missing2} more to ${label2.value}`)
+    return `Add ${parts.join(' and ')}`
+  })
+
+  function getZoneForGroup(groupName: string): GroupAssignmentZone | null {
+    if (group1Set.value.has(groupName)) return 'zone1'
+    if (group2Set.value.has(groupName)) return 'zone2'
+    return null
+  }
+
+  function assignToZone(groupName: string, zone: GroupAssignmentZone): GroupAssignmentState {
+    const next = removeFromBoth(groupName)
+    if (zone === 'zone1') {
+      return {
+        group1: [...next.group1, groupName],
+        group2: next.group2,
+      }
+    }
+    return {
+      group1: next.group1,
+      group2: [...next.group2, groupName],
+    }
+  }
+
+  function removeFromZone(groupName: string, zone: GroupAssignmentZone): GroupAssignmentState {
+    if (zone === 'zone1') {
+      return {
+        group1: group1.value.filter(name => name !== groupName),
+        group2: group2.value,
+      }
+    }
+    return {
+      group1: group1.value,
+      group2: group2.value.filter(name => name !== groupName),
+    }
+  }
+
+  function clearAll(): GroupAssignmentState {
+    return { group1: [], group2: [] }
+  }
+
+  function removeFromBoth(groupName: string): GroupAssignmentState {
+    return {
+      group1: group1.value.filter(name => name !== groupName),
+      group2: group2.value.filter(name => name !== groupName),
+    }
+  }
+
+  return {
+    unassignedGroups,
+    zone1Groups,
+    zone2Groups,
+    zone1Count,
+    zone2Count,
+    isValid,
+    validationMessage,
+    getZoneForGroup,
+    assignToZone,
+    removeFromZone,
+    clearAll,
+  }
+}
+
+function normalizeMinimum(value: number | null | undefined): number {
+  if (value === null || value === undefined || !Number.isFinite(value)) return 1
+  return Math.max(0, Math.floor(value))
+}

package/src/composables/useListSelection.ts

@@ -0,0 +1,158 @@
+import { computed, toValue, type ComputedRef, type Ref } from 'vue'
+import { useSelectionLimit, type SelectionLimitSource } from './useSelectionLimit'
+
+export type ListSelectionValue = string | number
+
+export type ListSelectionSource<T> =
+  | T
+  | Ref<T>
+  | ComputedRef<T>
+  | (() => T)
+
+export type WidenListSelectionValue<TValue extends ListSelectionValue> =
+  TValue extends string ? string : TValue extends number ? number : TValue
+
+export interface UseListSelectionOptions<
+  TItem,
+  TValue extends ListSelectionValue = ListSelectionValue,
+> {
+  selected: ListSelectionSource<readonly TValue[]>
+  items?: ListSelectionSource<readonly TItem[]>
+  getValue?: (item: TItem) => TValue
+  disabled?: ListSelectionSource<boolean | null | undefined>
+  max?: SelectionLimitSource<number | null | undefined>
+}
+
+export interface UseListSelectionReturn<TValue extends ListSelectionValue = ListSelectionValue> {
+  selectedValues: ComputedRef<TValue[]>
+  selectedSet: ComputedRef<Set<TValue>>
+  itemValues: ComputedRef<TValue[]>
+  selectedCount: ComputedRef<number>
+  itemCount: ComputedRef<number>
+  isAllSelected: ComputedRef<boolean>
+  isLimited: ComputedRef<boolean>
+  isAtLimit: ComputedRef<boolean>
+  canAddMore: ComputedRef<boolean>
+  remaining: ComputedRef<number | undefined>
+  isSelected: (value: TValue) => boolean
+  isFullySelected: (values: readonly TValue[]) => boolean
+  isPartiallySelected: (values: readonly TValue[]) => boolean
+  selectValues: (values: readonly TValue[]) => TValue[]
+  toggleValue: (value: TValue) => TValue[]
+  toggleValues: (values: readonly TValue[]) => TValue[]
+  selectAll: () => TValue[]
+  toggleAll: () => TValue[]
+  clear: () => TValue[]
+}
+
+/** Shared list-selection state for checkbox lists, sample selectors, and chip selectors. */
+export function useListSelection<
+  TItem = ListSelectionValue,
+  TValue extends ListSelectionValue = TItem extends ListSelectionValue ? TItem : ListSelectionValue,
+>(options: UseListSelectionOptions<TItem, TValue>): UseListSelectionReturn<WidenListSelectionValue<TValue>> {
+  type ResolvedValue = WidenListSelectionValue<TValue>
+
+  const disabled = computed(() => toValue(options.disabled) ?? false)
+  const selectedValues = computed<ResolvedValue[]>(() => [...toValue(options.selected)] as ResolvedValue[])
+  const selectedSet = computed(() => new Set(selectedValues.value))
+  const itemValues = computed<ResolvedValue[]>(() => {
+    const items = toValue(options.items) ?? []
+    return items.map(item => getItemValue(item, options.getValue) as ResolvedValue)
+  })
+
+  const selectedCount = computed(() => selectedValues.value.length)
+  const itemCount = computed(() => itemValues.value.length)
+  const isAllSelected = computed(() => (
+    itemValues.value.length > 0 && itemValues.value.every(value => selectedSet.value.has(value))
+  ))
+  const selectionLimit = useSelectionLimit({
+    count: selectedCount,
+    max: options.max,
+  })
+
+  function isSelected(value: ResolvedValue): boolean {
+    return selectedSet.value.has(value)
+  }
+
+  function isFullySelected(values: readonly ResolvedValue[]): boolean {
+    return values.length > 0 && values.every(value => selectedSet.value.has(value))
+  }
+
+  function isPartiallySelected(values: readonly ResolvedValue[]): boolean {
+    if (values.length === 0) return false
+    const selected = values.filter(value => selectedSet.value.has(value)).length
+    return selected > 0 && selected < values.length
+  }
+
+  function selectValues(values: readonly ResolvedValue[]): ResolvedValue[] {
+    if (disabled.value) return selectedValues.value
+    const missing = uniqueValues(values).filter(value => !selectedSet.value.has(value))
+    if (!selectionLimit.canAdd(missing.length)) return selectedValues.value
+    return [...selectedValues.value, ...missing]
+  }
+
+  function toggleValue(value: ResolvedValue): ResolvedValue[] {
+    if (disabled.value) return selectedValues.value
+    if (selectedSet.value.has(value)) {
+      return selectedValues.value.filter(selected => selected !== value)
+    }
+    if (!selectionLimit.canAddMore.value) return selectedValues.value
+    return [...selectedValues.value, value]
+  }
+
+  function toggleValues(values: readonly ResolvedValue[]): ResolvedValue[] {
+    if (disabled.value) return selectedValues.value
+    const unique = uniqueValues(values)
+    if (isFullySelected(unique)) {
+      const remove = new Set(unique)
+      return selectedValues.value.filter(value => !remove.has(value))
+    }
+    return selectValues(unique)
+  }
+
+  function selectAll(): ResolvedValue[] {
+    return selectValues(itemValues.value)
+  }
+
+  function toggleAll(): ResolvedValue[] {
+    if (isAllSelected.value) return clear()
+    return selectAll()
+  }
+
+  function clear(): ResolvedValue[] {
+    return disabled.value ? selectedValues.value : []
+  }
+
+  return {
+    selectedValues,
+    selectedSet,
+    itemValues,
+    selectedCount,
+    itemCount,
+    isAllSelected,
+    isLimited: selectionLimit.isLimited,
+    isAtLimit: selectionLimit.isAtLimit,
+    canAddMore: selectionLimit.canAddMore,
+    remaining: selectionLimit.remaining,
+    isSelected,
+    isFullySelected,
+    isPartiallySelected,
+    selectValues,
+    toggleValue,
+    toggleValues,
+    selectAll,
+    toggleAll,
+    clear,
+  }
+}
+
+function getItemValue<TItem, TValue extends ListSelectionValue>(
+  item: TItem,
+  getValue: ((item: TItem) => TValue) | undefined,
+): TValue {
+  return getValue ? getValue(item) : item as unknown as TValue
+}
+
+function uniqueValues<TValue extends ListSelectionValue>(values: readonly TValue[]): TValue[] {
+  return [...new Set(values)]
+}