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

package/src/components/FormBuilder.story.vue

@@ -0,0 +1,190 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import FormBuilder from './FormBuilder.vue'
+import { defineControlModel, defineControls } from '../composables/useControlSchema'
+
+type FormSize = 'sm' | 'md' | 'lg'
+
+const analysisModel = defineControlModel({
+  views: {
+    analysis: {
+      label: 'Analysis',
+      sections: {
+        parameters: {
+          label: 'Parameters',
+          description: 'Model and threshold controls',
+          columns: 2,
+          controls: {
+            threshold: {
+              type: 'number',
+              label: 'Threshold',
+              default: 0.05,
+              min: 0,
+              max: 1,
+              props: { step: 0.01 },
+            },
+            method: {
+              label: 'Method',
+              default: 'logistic',
+              options: ['linear', 'logistic', 'spline'],
+            },
+            normalize: {
+              label: 'Normalize intensities',
+              default: true,
+              type: 'toggle',
+            },
+          },
+        },
+        quality: {
+          label: 'Quality Control',
+          description: 'Result filters',
+          columns: 2,
+          controls: {
+            minPeakArea: {
+              type: 'number',
+              label: 'Min peak area',
+              default: 1000,
+              min: 0,
+            },
+            excludeOutliers: {
+              label: 'Exclude outliers',
+              default: true,
+              type: 'checkbox',
+            },
+          },
+        },
+      },
+    },
+  },
+})
+
+const compactControls = defineControls({
+  sampleName: {
+    label: 'Sample name',
+    default: 'Vehicle',
+    required: true,
+    section: 'sample',
+    sectionLabel: 'Sample',
+  },
+  concentration: {
+    type: 'number',
+    label: 'Concentration',
+    default: 10,
+    min: 0,
+    section: 'sample',
+  },
+  unit: {
+    label: 'Unit',
+    default: 'uM',
+    options: ['nM', 'uM', 'mM'],
+    section: 'sample',
+  },
+})
+
+const modelValues = ref<Record<string, unknown>>({})
+const controlValues = ref<Record<string, unknown>>({})
+
+function initState() {
+  return {
+    size: 'md' as FormSize,
+    showActions: true,
+    readonly: false,
+    disabled: false,
+  }
+}
+</script>
+
+<template>
+  <Story title="Forms/FormBuilder" :init-state="initState">
+    <Variant title="Model Driven">
+      <template #default="{ state }">
+        <div class="form-builder-story">
+          <div class="form-builder-story__surface">
+            <FormBuilder
+              v-model="modelValues"
+              :model="analysisModel"
+              :size="state.size"
+              :show-actions="state.showActions"
+              :readonly="state.readonly"
+              :disabled="state.disabled"
+            />
+          </div>
+          <pre class="form-builder-story__values">{{ JSON.stringify(modelValues, null, 2) }}</pre>
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstSelect
+          v-model="state.size"
+          title="Size"
+          :options="[
+            { label: 'Small', value: 'sm' },
+            { label: 'Medium', value: 'md' },
+            { label: 'Large', value: 'lg' },
+          ]"
+        />
+        <HstCheckbox v-model="state.showActions" title="Actions" />
+        <HstCheckbox v-model="state.readonly" title="Readonly" />
+        <HstCheckbox v-model="state.disabled" title="Disabled" />
+      </template>
+    </Variant>
+
+    <Variant title="Compact Controls">
+      <div class="form-builder-story">
+        <div class="form-builder-story__surface form-builder-story__surface--narrow">
+          <FormBuilder
+            v-model="controlValues"
+            :controls="compactControls"
+            :show-actions="false"
+          />
+        </div>
+        <pre class="form-builder-story__values">{{ JSON.stringify(controlValues, null, 2) }}</pre>
+      </div>
+    </Variant>
+  </Story>
+</template>
+
+<style scoped>
+.form-builder-story {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(14rem, 20rem);
+  gap: 1rem;
+  align-items: start;
+  padding: 2rem;
+  min-height: 640px;
+  background: var(--bg-secondary, #f8fafc);
+}
+
+.form-builder-story__surface {
+  min-width: 0;
+  padding: 1rem;
+  border: 1px solid var(--border-color, #e2e8f0);
+  border-radius: var(--radius-md, 0.5rem);
+  background: var(--bg-primary, #fff);
+}
+
+.form-builder-story__surface--narrow {
+  max-width: 34rem;
+}
+
+.form-builder-story__values {
+  min-width: 0;
+  margin: 0;
+  padding: 0.875rem;
+  border: 1px solid var(--border-color, #e2e8f0);
+  border-radius: var(--radius-md, 0.5rem);
+  background: var(--bg-tertiary, #f1f5f9);
+  color: var(--text-secondary, #475569);
+  font-family: var(--font-mono, monospace);
+  font-size: 0.75rem;
+  line-height: 1.5;
+  overflow: auto;
+}
+
+@media (max-width: 900px) {
+  .form-builder-story {
+    grid-template-columns: 1fr;
+    padding: 1rem;
+  }
+}
+</style>

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/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/MultiSelect.vue

@@ -1,11 +1,13 @@
 <script setup lang="ts">
 /** Lets users select multiple options from a checkbox list with optional selection cap. */
 import { computed } from 'vue'
-import type { MultiSelectOption, MultiSelectSize } from '../types'
+import type { MultiSelectOption, MultiSelectOptionInput, MultiSelectSize } from '../types'
+import { useListSelection } from '../composables/useListSelection'
+import { normalizeOptionInput } from '../utils/options'
 
 interface Props {
   modelValue: (string | number)[]
-  options: MultiSelectOption[]
+  options: MultiSelectOptionInput[]
   placeholder?: string
   disabled?: boolean
   maxSelections?: number
@@ -22,22 +24,25 @@ const emit = defineEmits<{
   'update:modelValue': [value: (string | number)[]]
 }>()
 
-const canSelectMore = computed(() => {
-  if (props.maxSelections === undefined) return true
-  return props.modelValue.length < props.maxSelections
+const normalizedOptions = computed<MultiSelectOption[]>(() => props.options.map(normalizeOptionInput))
+const optionSelection = useListSelection({
+  selected: () => props.modelValue,
+  items: normalizedOptions,
+  getValue: option => option.value,
+  disabled: () => props.disabled,
+  max: () => props.maxSelections,
 })
+const canSelectMore = optionSelection.canAddMore
 
 function isSelected(value: string | number): boolean {
-  return props.modelValue.includes(value)
+  return optionSelection.isSelected(value)
 }
 
 function toggleOption(option: MultiSelectOption) {
   if (props.disabled || option.disabled) return
 
-  if (isSelected(option.value)) {
-    emit('update:modelValue', props.modelValue.filter(v => v !== option.value))
-  } else if (canSelectMore.value) {
-    emit('update:modelValue', [...props.modelValue, option.value])
+  if (isSelected(option.value) || canSelectMore.value) {
+    emit('update:modelValue', optionSelection.toggleValue(option.value))
   }
 }
 
@@ -50,7 +55,7 @@ function handleKeydown(event: KeyboardEvent, option: MultiSelectOption) {
 
 const selectedLabels = computed(() => {
   return props.modelValue
-    .map(v => props.options.find(o => o.value === v)?.label)
+    .map(v => normalizedOptions.value.find(o => o.value === v)?.label)
     .filter(Boolean)
 })
 </script>
@@ -72,7 +77,7 @@ const selectedLabels = computed(() => {
 
     <div class="mint-multi-select__options" role="group">
       <button
-        v-for="option in options"
+        v-for="option in normalizedOptions"
         :key="String(option.value)"
         type="button"
         role="checkbox"

package/src/components/PlateMapEditor.vue

@@ -1,8 +1,9 @@
 <script setup lang="ts">
 /** Full plate-map design environment for 96/384-well plates with sample assignment, slot-color coding, undo/redo, and CSV/JSON import-export. */
-import { ref, computed, watch, onMounted, onUnmounted } from 'vue'
+import { ref, computed, watch } from 'vue'
 import type { PlateMapEditorState, WellPlateFormat, SampleType, Well } from '../types'
 import { useWellPlateEditor } from '../composables/useWellPlateEditor'
+import { useEventListener } from '../composables/useEventListener'
 import WellPlate from './WellPlate.vue'
 import SampleLegend from './SampleLegend.vue'
 
@@ -221,13 +222,7 @@ function handleKeyDown(event: KeyboardEvent) {
   }
 }
 
-onMounted(() => {
-  document.addEventListener('keydown', handleKeyDown)
-})
-
-onUnmounted(() => {
-  document.removeEventListener('keydown', handleKeyDown)
-})
+useEventListener(() => document, 'keydown', handleKeyDown)
 </script>
 
 <template>