@morscherlab/mint-sdk 1.0.0-beta.1 → 1.0.0-beta.3

package/src/components/FormBuilder.vue

@@ -2,43 +2,75 @@
 /**
  * Schema-driven form component that renders flat or multi-step wizard forms.
  *
- * Pass a `FormSchema` with either `sections` (flat) or `steps` (wizard).
+ * Pass a `FormSchema` with either `sections` (flat) or `steps` (wizard), or
+ * pass a compact `controls` schema for standard generated forms.
  * Use `v-model` for two-way binding of the form data; the `submit` event
  * carries only the data for currently-visible fields. Supply `enhancements`
  * for dynamic options, custom validators, a submit handler, and field-change
  * callbacks that cannot be expressed in JSON.
+ * Compact control schemas can be bound directly:
+ * `<FormBuilder :controls="controls" v-model="values" />`.
+ * Complete control models can also be bound directly:
+ * `<FormBuilder :model="workspaceModel" v-model="values" />`.
  *
- * Exposes `form`, `validate`, `reset`, `goNext`, `goBack`, `goToStep`, and
- * `builder` for imperative control via template refs.
+ * Exposes `form`, `validate`, `reset`, `updateSchema`, `goNext`, `goBack`,
+ * `goToStep`, and `builder` for imperative control via template refs.
  *
  * Slots:
  * - `field:<name>` — override a single field's input component
  * - `section:<id>` — replace an entire section body
  * - `section:<id>:after` — inject content after a section
- * - `actions` — replace the default FormActions bar
+ * - `actions` — replace the default FormActions bar when `showActions` is true
  */
 import { ref, computed, watch } from 'vue'
 import type { FormSchema, FormEnhancements, UseFormBuilderReturn } from '../types/form-builder'
 import type { WizardStep } from '../types'
+import {
+  controlsToFormSchema,
+  defineControlModel,
+  getControlDefaults,
+  mergeControlWorkspaceOptions,
+  type ControlModel,
+  type ControlModelBinding,
+  type ControlSchema,
+  type ControlWorkspaceOptions,
+} from '../composables/useControlSchema'
 import { useFormBuilder } from '../composables/useFormBuilder'
+import {
+  formSchemaFieldNames,
+  pickExistingRecordKeys,
+  recordValuesEqualForKeys,
+} from '../utils/formModelSync'
 import StepWizard from './StepWizard.vue'
-import FormSection from './FormSection.vue'
+import FormSectionRenderer from './internal/FormSectionRenderer.vue'
 import FormActions from './FormActions.vue'
 
 interface Props {
-  schema: FormSchema
+  /** Full form or wizard schema. Takes precedence when `controls` is also provided. */
+  schema?: FormSchema
+  /** Model returned by defineControlModel(), or a raw nested ControlModel for one-step form generation. */
+  model?: ControlModel | ControlModelBinding
+  /** Compact control schema used to generate a flat FormSchema. */
+  controls?: ControlSchema
+  /** Options passed to compact control schema generation, including shared initialValues. */
+  controlOptions?: ControlWorkspaceOptions
   modelValue?: Record<string, unknown>
   enhancements?: FormEnhancements<Record<string, unknown>>
   loading?: boolean
   disabled?: boolean
   size?: 'sm' | 'md' | 'lg'
   readonly?: boolean
+  /** Show the default or slotted form actions. */
+  showActions?: boolean
 }
 
 const props = withDefaults(defineProps<Props>(), {
+  model: undefined,
+  controlOptions: () => ({}),
   loading: false,
   disabled: false,
   readonly: false,
+  showActions: true,
 })
 
 const emit = defineEmits<{
@@ -47,12 +79,68 @@ const emit = defineEmits<{
   cancel: []
 }>()
 
+const resolvedModel = computed<ControlModelBinding | undefined>(() => {
+  if (props.model === undefined) return undefined
+  return isControlModelBinding(props.model) ? props.model : defineControlModel(props.model)
+})
+
+const resolvedControls = computed<ControlSchema | undefined>(() =>
+  props.controls ?? resolvedModel.value?.controls,
+)
+
+const resolvedControlOptions = computed<ControlWorkspaceOptions>(() =>
+  mergeControlWorkspaceOptions(resolvedModel.value?.controlOptions ?? {}, props.controlOptions)
+)
+
+const resolvedSchema = computed<FormSchema>(() => {
+  if (props.schema) return props.schema
+  if (resolvedControls.value) return controlsToFormSchema(resolvedControls.value, resolvedControlOptions.value)
+  return { sections: [] }
+})
+
+const resolvedModelValue = computed<Record<string, unknown>>(() => ({
+  ...(resolvedControls.value ? getControlDefaults(resolvedControls.value) : {}),
+  ...(resolvedControlOptions.value.initialValues ?? {}),
+  ...(props.modelValue ?? {}),
+}))
+
 const builder = useFormBuilder(
-  props.schema,
-  props.modelValue,
+  resolvedSchema.value,
+  resolvedModelValue.value,
   props.enhancements,
 )
 
+// Sync schema/control changes into the internal builder so generated forms stay coherent.
+watch(
+  resolvedSchema,
+  (schema) => {
+    const fieldNames = formSchemaFieldNames(schema)
+    const schemaValues = pickExistingRecordKeys(resolvedModelValue.value, fieldNames)
+    const existingValues = pickExistingRecordKeys(
+      builder.form.data as Record<string, unknown>,
+      fieldNames,
+    )
+    const nextValues = props.modelValue === undefined
+      ? { ...schemaValues, ...existingValues }
+      : schemaValues
+
+    builder.updateSchema(schema, nextValues)
+  },
+  { deep: true },
+)
+
+// Sync external modelValue changes into the internal form without resetting on no-op echo updates.
+watch(
+  () => props.modelValue,
+  () => {
+    const data = resolvedModelValue.value
+    const fieldNames = builderFieldNames()
+    if (recordValuesEqualForKeys(data, builder.form.data as Record<string, unknown>, fieldNames)) return
+    builder.reset(pickExistingRecordKeys(data, fieldNames))
+  },
+  { deep: true },
+)
+
 // Sync modelValue changes back to parent
 watch(
   () => ({ ...builder.form.data }),
@@ -61,12 +149,12 @@ watch(
 )
 
 // Wizard support
-const isWizard = computed(() => !!props.schema.steps)
+const isWizard = computed(() => !!resolvedSchema.value.steps)
 const wizardRef = ref<InstanceType<typeof StepWizard> | null>(null)
 
 const wizardSteps = computed<WizardStep[]>(() => {
-  if (!props.schema.steps) return []
-  return props.schema.steps.map((step) => ({
+  if (!resolvedSchema.value.steps) return []
+  return resolvedSchema.value.steps.map((step) => ({
     id: step.id,
     label: step.label,
     description: step.description,
@@ -105,10 +193,19 @@ function handleCancel() {
   emit('cancel')
 }
 
+function builderFieldNames(): string[] {
+  return builder.fields.map(field => field.name)
+}
+
+function isControlModelBinding(model: ControlModel | ControlModelBinding): model is ControlModelBinding {
+  return 'controls' in model && 'controlOptions' in model
+}
+
 defineExpose({
   form: builder.form,
   validate: builder.validate,
   reset: builder.reset,
+  updateSchema: builder.updateSchema,
   goNext: builder.goNext,
   goBack: builder.goBack,
   goToStep: builder.goToStep,
@@ -119,17 +216,17 @@ defineExpose({
 <template>
   <div :class="['mint-form-builder', size ? `mint-form-builder--${size}` : '']">
     <!-- Wizard mode -->
-    <template v-if="isWizard && schema.steps">
+    <template v-if="isWizard && resolvedSchema.steps">
       <StepWizard
         ref="wizardRef"
         :steps="wizardSteps"
         :model-value="builder.currentStep.value"
         @update:model-value="builder.goToStep($event)"
       >
-        <template v-for="step in schema.steps" :key="step.id" #[`step-${step.id}`]>
+        <template v-for="step in resolvedSchema.steps" :key="step.id" #[`step-${step.id}`]>
           <div class="mint-form-builder__step">
             <template v-for="section in step.sections" :key="section.id">
-              <FormSection
+              <FormSectionRenderer
                 v-if="builder.isSectionVisible(section.id)"
                 :section="section"
                 :builder="(builder as UseFormBuilderReturn<Record<string, unknown>>)"
@@ -145,12 +242,12 @@ defineExpose({
                 <template #[`section:${section.id}:after`]="slotProps">
                   <slot :name="`section:${section.id}:after`" v-bind="slotProps" />
                 </template>
-              </FormSection>
+              </FormSectionRenderer>
             </template>
           </div>
         </template>
 
-        <template #navigation="{ isFirst, isLast }">
+        <template v-if="showActions" #navigation="{ isFirst, isLast }">
           <slot name="actions" :form="builder.form" :builder="builder">
             <FormActions
               is-wizard
@@ -159,9 +256,9 @@ defineExpose({
               :can-proceed="builder.isCurrentStepValid.value"
               :loading="loading || builder.form.isSubmitting.value"
               :disabled="disabled"
-              :submit-label="schema.submitLabel ?? 'Submit'"
-              :cancel-label="schema.cancelLabel ?? 'Cancel'"
-              :show-cancel="schema.showCancel ?? false"
+              :submit-label="resolvedSchema.submitLabel ?? 'Submit'"
+              :cancel-label="resolvedSchema.cancelLabel ?? 'Cancel'"
+              :show-cancel="resolvedSchema.showCancel ?? false"
               @next="handleNext"
               @back="builder.goBack"
               @submit="handleSubmit"
@@ -173,9 +270,9 @@ defineExpose({
     </template>
 
     <!-- Flat mode -->
-    <template v-else-if="schema.sections">
-      <template v-for="section in schema.sections" :key="section.id">
-        <FormSection
+    <template v-else-if="resolvedSchema.sections">
+      <template v-for="section in resolvedSchema.sections" :key="section.id">
+        <FormSectionRenderer
           v-if="builder.isSectionVisible(section.id)"
           :section="section"
           :builder="(builder as UseFormBuilderReturn<Record<string, unknown>>)"
@@ -191,16 +288,16 @@ defineExpose({
           <template #[`section:${section.id}:after`]="slotProps">
             <slot :name="`section:${section.id}:after`" v-bind="slotProps" />
           </template>
-        </FormSection>
+        </FormSectionRenderer>
       </template>
 
-      <slot name="actions" :form="builder.form" :builder="builder">
+      <slot v-if="showActions" name="actions" :form="builder.form" :builder="builder">
         <FormActions
           :loading="loading || builder.form.isSubmitting.value"
           :disabled="disabled"
-          :submit-label="schema.submitLabel ?? 'Submit'"
-          :cancel-label="schema.cancelLabel ?? 'Cancel'"
-          :show-cancel="schema.showCancel ?? false"
+          :submit-label="resolvedSchema.submitLabel ?? 'Submit'"
+          :cancel-label="resolvedSchema.cancelLabel ?? 'Cancel'"
+          :show-cancel="resolvedSchema.showCancel ?? false"
           @submit="handleSubmit"
           @cancel="handleCancel"
         />

package/src/components/FormFieldRenderer.vue

@@ -1,17 +1,12 @@
 <script setup lang="ts">
 /**
- * Renders a single form field inside a FormField wrapper.
+ * @deprecated Use FormBuilder with schema/controls and field slots instead.
  *
- * Resolves the SDK component for the field type from the registry, shows
- * validation errors only after the field has been touched, and handles the
- * FileUploader's event-based upload pattern via `handleUpload`. Consumers can
- * override rendering via the `field:<name>` slot.
+ * Compatibility wrapper around the internal FormBuilder field renderer.
  */
-import { computed } from 'vue'
 import type { FormFieldSchema } from '../types/form-builder'
 import type { UseFormReturn } from '../composables/useForm'
-import { getFieldRegistryEntry } from '../composables/formBuilderRegistry'
-import FormField from './FormField.vue'
+import FormFieldRendererInternal from './internal/FormFieldRendererInternal.vue'
 
 interface Props {
   field: FormFieldSchema
@@ -21,38 +16,20 @@ interface Props {
 
 const props = defineProps<Props>()
 
-const entry = computed(() => getFieldRegistryEntry(props.field.type))
-
-const errorMessage = computed(() => {
-  const name = props.field.name
-  return props.form.touched[name] ? props.form.errors[name] : null
-})
-
-function handleUpload(files: File[]) {
-  props.form.setFieldValue(props.field.name, files)
-}
+defineSlots<{
+  '`field:${field.name}`'?: (props: Record<string, unknown>) => unknown
+  [name: string]: ((props: Record<string, unknown>) => unknown) | undefined
+}>()
 </script>
 
 <template>
-  <FormField
-    :label="field.label"
-    :error="errorMessage ?? undefined"
-    :hint="field.hint"
-    :required="!!field.validation?.required"
-    :html-for="field.name"
+  <FormFieldRendererInternal
+    :field="props.field"
+    :resolved-props="props.resolvedProps"
+    :form="props.form"
   >
-    <slot :name="`field:${field.name}`" :field="field" :form="form" :field-props="form.getFieldProps(field.name)">
-      <component
-        :is="entry.component"
-        v-if="entry.vModel"
-        v-bind="resolvedProps"
-      />
-      <component
-        :is="entry.component"
-        v-else
-        v-bind="resolvedProps"
-        @upload="handleUpload"
-      />
-    </slot>
-  </FormField>
+    <template #[`field:${props.field.name}`]="slotProps">
+      <slot :name="`field:${props.field.name}`" v-bind="slotProps" />
+    </template>
+  </FormFieldRendererInternal>
 </template>

package/src/components/FormSection.vue

@@ -1,18 +1,11 @@
 <script setup lang="ts">
 /**
- * Renders a single `FormSectionSchema` inside a FormBuilder.
+ * @deprecated Use FormBuilder with schema/controls and section slots instead.
  *
- * Filters out hidden fields before rendering, applies the section's column
- * grid and per-field `colSpan`, and switches between a collapsible
- * (`CollapsibleCard`) and a static layout based on `section.collapsible`.
- * The entire section is hidden when all its fields are hidden. Consumers can
- * replace the section body via `section:<id>` or inject content after it via
- * `section:<id>:after`, and override individual fields via `field:<name>`.
+ * Compatibility wrapper around the internal FormBuilder section renderer.
  */
-import { computed } from 'vue'
 import type { FormSectionSchema, UseFormBuilderReturn } from '../types/form-builder'
-import CollapsibleCard from './CollapsibleCard.vue'
-import FormFieldRenderer from './FormFieldRenderer.vue'
+import FormSectionRenderer from './internal/FormSectionRenderer.vue'
 
 interface Props {
   section: FormSectionSchema
@@ -21,70 +14,24 @@ interface Props {
 
 const props = defineProps<Props>()
 
-const visibleFields = computed(() =>
-  props.section.fields.filter((f) => props.builder.isFieldVisible(f.name)),
-)
-
-const gridStyle = computed(() => ({
-  gridTemplateColumns: `repeat(${props.section.columns ?? 1}, 1fr)`,
-}))
+defineSlots<{
+  '`section:${section.id}`'?: (props: Record<string, unknown>) => unknown
+  '`field:${field.name}`'?: (props: Record<string, unknown>) => unknown
+  '`section:${section.id}:after`'?: (props: Record<string, unknown>) => unknown
+  [name: string]: ((props: Record<string, unknown>) => unknown) | undefined
+}>()
 </script>
 
 <template>
-  <div v-if="visibleFields.length > 0" class="mint-form-section">
-    <slot :name="`section:${section.id}`" :section="section" :form="builder.form">
-      <!-- Collapsible variant -->
-      <CollapsibleCard
-        v-if="section.collapsible"
-        :title="section.title"
-        :subtitle="section.description"
-        :default-open="section.defaultOpen ?? true"
-      >
-        <div class="mint-form-section__grid" :style="gridStyle">
-          <div
-            v-for="field in visibleFields"
-            :key="field.name"
-            :style="field.colSpan ? { gridColumn: `span ${field.colSpan}` } : undefined"
-          >
-            <slot :name="`field:${field.name}`" :field="field" :form="builder.form" :field-props="builder.form.getFieldProps(field.name)">
-              <FormFieldRenderer
-                :field="field"
-                :resolved-props="builder.getResolvedFieldProps(field)"
-                :form="builder.form"
-              />
-            </slot>
-          </div>
-        </div>
-      </CollapsibleCard>
-
-      <!-- Static variant -->
-      <div v-else class="mint-form-section--static">
-        <div v-if="section.title || section.description" class="mint-form-section__header">
-          <h3 v-if="section.title" class="mint-form-section__title">{{ section.title }}</h3>
-          <p v-if="section.description" class="mint-form-section__description">{{ section.description }}</p>
-        </div>
-        <div class="mint-form-section__grid" :style="gridStyle">
-          <div
-            v-for="field in visibleFields"
-            :key="field.name"
-            :style="field.colSpan ? { gridColumn: `span ${field.colSpan}` } : undefined"
-          >
-            <slot :name="`field:${field.name}`" :field="field" :form="builder.form" :field-props="builder.form.getFieldProps(field.name)">
-              <FormFieldRenderer
-                :field="field"
-                :resolved-props="builder.getResolvedFieldProps(field)"
-                :form="builder.form"
-              />
-            </slot>
-          </div>
-        </div>
-      </div>
-    </slot>
-
-    <slot :name="`section:${section.id}:after`" :form="builder.form" />
-  </div>
+  <FormSectionRenderer :section="props.section" :builder="props.builder">
+    <template #[`section:${props.section.id}`]="slotProps">
+      <slot :name="`section:${props.section.id}`" v-bind="slotProps" />
+    </template>
+    <template v-for="field in props.section.fields" :key="field.name" #[`field:${field.name}`]="slotProps">
+      <slot :name="`field:${field.name}`" v-bind="slotProps" />
+    </template>
+    <template #[`section:${props.section.id}:after`]="slotProps">
+      <slot :name="`section:${props.section.id}:after`" v-bind="slotProps" />
+    </template>
+  </FormSectionRenderer>
 </template>
-
-<style>
-@import '../styles/components/form-builder.css';
-</style>

package/src/components/GroupAssigner.vue

@@ -1,7 +1,8 @@
 <script setup lang="ts">
 /** Drag-and-drop two-zone assigner for splitting sample groups into control and treatment arms. */
-import { computed, ref } from 'vue'
+import { ref } from 'vue'
 import type { GroupItem } from '../types'
+import { useGroupAssignment, type GroupAssignmentState, type GroupAssignmentZone } from '../composables/useGroupAssignment'
 
 interface Props {
   groups: GroupItem[]
@@ -30,42 +31,15 @@ const emit = defineEmits<{
 const dragOverZone = ref<'zone1' | 'zone2' | null>(null)
 const draggingGroup = ref<string | null>(null)
 
-const unassignedGroups = computed(() =>
-  props.groups.filter(
-    g => !props.group1.includes(g.name) && !props.group2.includes(g.name)
-  )
-)
-
-const zone1Groups = computed(() =>
-  props.groups.filter(g => props.group1.includes(g.name))
-)
-
-const zone2Groups = computed(() =>
-  props.groups.filter(g => props.group2.includes(g.name))
-)
-
-const zone1Count = computed(() =>
-  zone1Groups.value.reduce((sum, g) => sum + g.count, 0)
-)
-
-const zone2Count = computed(() =>
-  zone2Groups.value.reduce((sum, g) => sum + g.count, 0)
-)
-
-const isValid = computed(() =>
-  props.group1.length >= props.minPerGroup &&
-  props.group2.length >= props.minPerGroup
-)
-
-const validationMessage = computed(() => {
-  if (isValid.value) return null
-  const missing1 = Math.max(0, props.minPerGroup - props.group1.length)
-  const missing2 = Math.max(0, props.minPerGroup - props.group2.length)
-  const parts: string[] = []
-  if (missing1 > 0) parts.push(`${missing1} more to ${props.label1}`)
-  if (missing2 > 0) parts.push(`${missing2} more to ${props.label2}`)
-  return `Add ${parts.join(' and ')}`
+const assignment = useGroupAssignment({
+  groups: () => props.groups,
+  group1: () => props.group1,
+  group2: () => props.group2,
+  label1: () => props.label1,
+  label2: () => props.label2,
+  minPerGroup: () => props.minPerGroup,
 })
+const { unassignedGroups, zone1Groups, zone2Groups, zone1Count, zone2Count, validationMessage } = assignment
 
 function handleDragStart(event: DragEvent, groupName: string) {
   draggingGroup.value = groupName
@@ -78,7 +52,7 @@ function handleDragEnd() {
   dragOverZone.value = null
 }
 
-function handleDragOver(event: DragEvent, zone: 'zone1' | 'zone2') {
+function handleDragOver(event: DragEvent, zone: GroupAssignmentZone) {
   event.preventDefault()
   event.dataTransfer!.dropEffect = 'move'
   dragOverZone.value = zone
@@ -88,7 +62,7 @@ function handleDragLeave() {
   dragOverZone.value = null
 }
 
-function handleDrop(event: DragEvent, zone: 'zone1' | 'zone2') {
+function handleDrop(event: DragEvent, zone: GroupAssignmentZone) {
   event.preventDefault()
   dragOverZone.value = null
 
@@ -98,32 +72,26 @@ function handleDrop(event: DragEvent, zone: 'zone1' | 'zone2') {
   assignToZone(groupName, zone)
 }
 
-function assignToZone(groupName: string, zone: 'zone1' | 'zone2') {
-  // Remove from both zones first
-  const newGroup1 = props.group1.filter(n => n !== groupName)
-  const newGroup2 = props.group2.filter(n => n !== groupName)
-
-  // Add to target zone
-  if (zone === 'zone1') {
-    emit('update:group1', [...newGroup1, groupName])
-    emit('update:group2', newGroup2)
-  } else {
-    emit('update:group1', newGroup1)
-    emit('update:group2', [...newGroup2, groupName])
-  }
+function assignToZone(groupName: string, zone: GroupAssignmentZone) {
+  emitAssignment(assignment.assignToZone(groupName, zone))
 }
 
-function removeFromZone(groupName: string, zone: 'zone1' | 'zone2') {
+function removeFromZone(groupName: string, zone: GroupAssignmentZone) {
+  const state = assignment.removeFromZone(groupName, zone)
   if (zone === 'zone1') {
-    emit('update:group1', props.group1.filter(n => n !== groupName))
+    emit('update:group1', state.group1)
   } else {
-    emit('update:group2', props.group2.filter(n => n !== groupName))
+    emit('update:group2', state.group2)
   }
 }
 
 function clearAll() {
-  emit('update:group1', [])
-  emit('update:group2', [])
+  emitAssignment(assignment.clearAll())
+}
+
+function emitAssignment(state: GroupAssignmentState) {
+  emit('update:group1', state.group1)
+  emit('update:group2', state.group2)
 }
 </script>
 

package/src/components/GroupingModal.story.vue

@@ -12,8 +12,8 @@ const isOpen = ref(false)
 </script>
 
 <template>
-  <Story title="Lab/GroupingModal">
-    <Variant title="Playground">
+  <Story title="Lab/Deprecated/GroupingModal">
+    <Variant title="Compatibility Preview">
       <div style="padding: 2rem;">
         <button
           type="button"
@@ -27,7 +27,7 @@ const isOpen = ref(false)
           "
           @click="isOpen = true"
         >
-          Open Grouping Modal
+          Open Legacy Grouping Modal
         </button>
         <GroupingModal
           :open="isOpen"