@morscherlab/mint-sdk 1.0.0-alpha.2

package/src/components/FormActions.vue

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+/**
+ * Action bar rendered at the bottom of a FormBuilder.
+ *
+ * Supports two modes:
+ * - Flat form: shows an optional Cancel button and a Submit button.
+ * - Wizard (`isWizard=true`): shows Back / Next on intermediate steps and
+ *   Submit only on the last step. Back is hidden on the first step.
+ *
+ * The `canProceed` prop gates the primary action (Next or Submit) to prevent
+ * advancing when the current step has validation errors.
+ */
+import BaseButton from './BaseButton.vue'
+
+interface Props {
+  isWizard?: boolean
+  isFirst?: boolean
+  isLast?: boolean
+  canProceed?: boolean
+  loading?: boolean
+  disabled?: boolean
+  submitLabel?: string
+  cancelLabel?: string
+  showCancel?: boolean
+}
+
+withDefaults(defineProps<Props>(), {
+  isWizard: false,
+  isFirst: true,
+  isLast: true,
+  canProceed: true,
+  loading: false,
+  disabled: false,
+  submitLabel: 'Submit',
+  cancelLabel: 'Cancel',
+  showCancel: false,
+})
+
+const emit = defineEmits<{
+  submit: []
+  cancel: []
+  back: []
+  next: []
+}>()
+</script>
+
+<template>
+  <div class="mld-form-actions">
+    <BaseButton
+      v-if="showCancel"
+      variant="ghost"
+      :disabled="loading || disabled"
+      @click="emit('cancel')"
+    >
+      {{ cancelLabel }}
+    </BaseButton>
+
+    <div style="flex: 1" />
+
+    <BaseButton
+      v-if="isWizard && !isFirst"
+      variant="secondary"
+      :disabled="loading || disabled"
+      @click="emit('back')"
+    >
+      Back
+    </BaseButton>
+
+    <BaseButton
+      v-if="isWizard && !isLast"
+      variant="primary"
+      :disabled="!canProceed || loading || disabled"
+      @click="emit('next')"
+    >
+      Next
+    </BaseButton>
+
+    <BaseButton
+      v-if="!isWizard || isLast"
+      variant="primary"
+      :loading="loading"
+      :disabled="!canProceed || loading || disabled"
+      @click="emit('submit')"
+    >
+      {{ submitLabel }}
+    </BaseButton>
+  </div>
+</template>
+
+<style>
+@import '../styles/components/form-builder.css';
+</style>

package/src/components/FormBuilder.vue

@@ -0,0 +1,214 @@
+<script setup lang="ts">
+/**
+ * Schema-driven form component that renders flat or multi-step wizard forms.
+ *
+ * Pass a `FormSchema` with either `sections` (flat) or `steps` (wizard).
+ * 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.
+ *
+ * Exposes `form`, `validate`, `reset`, `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
+ */
+import { ref, computed, watch } from 'vue'
+import type { FormSchema, FormEnhancements, UseFormBuilderReturn } from '../types/form-builder'
+import type { WizardStep } from '../types'
+import { useFormBuilder } from '../composables/useFormBuilder'
+import StepWizard from './StepWizard.vue'
+import FormSection from './FormSection.vue'
+import FormActions from './FormActions.vue'
+
+interface Props {
+  schema: FormSchema
+  modelValue?: Record<string, unknown>
+  enhancements?: FormEnhancements<Record<string, unknown>>
+  loading?: boolean
+  disabled?: boolean
+  size?: 'sm' | 'md' | 'lg'
+  readonly?: boolean
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  loading: false,
+  disabled: false,
+  readonly: false,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [data: Record<string, unknown>]
+  submit: [data: Record<string, unknown>]
+  cancel: []
+}>()
+
+const builder = useFormBuilder(
+  props.schema,
+  props.modelValue,
+  props.enhancements,
+)
+
+// Sync modelValue changes back to parent
+watch(
+  () => ({ ...builder.form.data }),
+  (data) => emit('update:modelValue', data as Record<string, unknown>),
+  { deep: true },
+)
+
+// Wizard support
+const isWizard = computed(() => !!props.schema.steps)
+const wizardRef = ref<InstanceType<typeof StepWizard> | null>(null)
+
+const wizardSteps = computed<WizardStep[]>(() => {
+  if (!props.schema.steps) return []
+  return props.schema.steps.map((step) => ({
+    id: step.id,
+    label: step.label,
+    description: step.description,
+    icon: step.icon,
+    optional: step.optional,
+  }))
+})
+
+// Sync step validation state with StepWizard
+watch(
+  () => builder.isCurrentStepValid.value,
+  (valid) => {
+    wizardRef.value?.setStepValid(builder.currentStep.value, valid)
+  },
+)
+
+function handleNext() {
+  const success = builder.goNext()
+  if (success) {
+    wizardRef.value?.setStepValid(builder.currentStep.value - 1, true)
+  }
+}
+
+async function handleSubmit() {
+  await builder.submit()
+  const formData = builder.form.data as Record<string, unknown>
+  const visibleData = Object.fromEntries(
+    builder.fields
+      .filter((f) => builder.isFieldVisible(f.name))
+      .map((f) => [f.name, formData[f.name]]),
+  )
+  emit('submit', visibleData)
+}
+
+function handleCancel() {
+  emit('cancel')
+}
+
+defineExpose({
+  form: builder.form,
+  validate: builder.validate,
+  reset: builder.reset,
+  goNext: builder.goNext,
+  goBack: builder.goBack,
+  goToStep: builder.goToStep,
+  builder,
+})
+</script>
+
+<template>
+  <div :class="['mld-form-builder', size ? `mld-form-builder--${size}` : '']">
+    <!-- Wizard mode -->
+    <template v-if="isWizard && schema.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}`]>
+          <div class="mld-form-builder__step">
+            <template v-for="section in step.sections" :key="section.id">
+              <FormSection
+                v-if="builder.isSectionVisible(section.id)"
+                :section="section"
+                :builder="(builder as UseFormBuilderReturn<Record<string, unknown>>)"
+              >
+                <!-- Forward field slots -->
+                <template v-for="field in section.fields" :key="field.name" #[`field:${field.name}`]="slotProps">
+                  <slot :name="`field:${field.name}`" v-bind="slotProps" />
+                </template>
+                <!-- Forward section slots -->
+                <template #[`section:${section.id}`]="slotProps">
+                  <slot :name="`section:${section.id}`" v-bind="slotProps" />
+                </template>
+                <template #[`section:${section.id}:after`]="slotProps">
+                  <slot :name="`section:${section.id}:after`" v-bind="slotProps" />
+                </template>
+              </FormSection>
+            </template>
+          </div>
+        </template>
+
+        <template #navigation="{ isFirst, isLast }">
+          <slot name="actions" :form="builder.form" :builder="builder">
+            <FormActions
+              is-wizard
+              :is-first="isFirst"
+              :is-last="isLast"
+              :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"
+              @next="handleNext"
+              @back="builder.goBack"
+              @submit="handleSubmit"
+              @cancel="handleCancel"
+            />
+          </slot>
+        </template>
+      </StepWizard>
+    </template>
+
+    <!-- Flat mode -->
+    <template v-else-if="schema.sections">
+      <template v-for="section in schema.sections" :key="section.id">
+        <FormSection
+          v-if="builder.isSectionVisible(section.id)"
+          :section="section"
+          :builder="(builder as UseFormBuilderReturn<Record<string, unknown>>)"
+        >
+          <!-- Forward field slots -->
+          <template v-for="field in section.fields" :key="field.name" #[`field:${field.name}`]="slotProps">
+            <slot :name="`field:${field.name}`" v-bind="slotProps" />
+          </template>
+          <!-- Forward section slots -->
+          <template #[`section:${section.id}`]="slotProps">
+            <slot :name="`section:${section.id}`" v-bind="slotProps" />
+          </template>
+          <template #[`section:${section.id}:after`]="slotProps">
+            <slot :name="`section:${section.id}:after`" v-bind="slotProps" />
+          </template>
+        </FormSection>
+      </template>
+
+      <slot 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="handleSubmit"
+          @cancel="handleCancel"
+        />
+      </slot>
+    </template>
+  </div>
+</template>
+
+<style>
+@import '../styles/components/form-builder.css';
+</style>

package/src/components/FormField.story.vue

@@ -0,0 +1,132 @@
+<script setup lang="ts">
+import FormField from './FormField.vue'
+import BaseInput from './BaseInput.vue'
+import BaseTextarea from './BaseTextarea.vue'
+</script>
+
+<template>
+  <Story title="Layout/FormField">
+    <Variant title="Playground">
+      <template #default="{ state }">
+        <div style="padding: 2rem; max-width: 400px; margin: 0 auto;">
+          <FormField
+            :label="state.label"
+            :error="state.showError ? state.error : undefined"
+            :hint="state.showHint ? state.hint : undefined"
+            :required="state.required"
+            :html-for="state.htmlFor"
+          >
+            <input
+              :id="state.htmlFor"
+              type="text"
+              placeholder="Enter value..."
+              style="width: 100%; padding: 0.5rem 0.75rem; border: 1px solid var(--border-color, #e2e8f0); border-radius: 0.375rem; font-size: 0.875rem; background: var(--bg-primary, #fff); color: var(--text-primary, #1e293b); box-sizing: border-box;"
+            />
+          </FormField>
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstText v-model="state.label" title="Label" />
+        <HstCheckbox v-model="state.required" title="Required" />
+        <HstCheckbox v-model="state.showError" title="Show Error" />
+        <HstText v-model="state.error" title="Error Message" />
+        <HstCheckbox v-model="state.showHint" title="Show Hint" />
+        <HstText v-model="state.hint" title="Hint Text" />
+        <HstText v-model="state.htmlFor" title="HTML For" />
+      </template>
+    </Variant>
+
+    <Variant title="With Label">
+      <div style="padding: 2rem; max-width: 400px; margin: 0 auto;">
+        <FormField label="Sample Name" html-for="sample-name">
+          <input
+            id="sample-name"
+            type="text"
+            placeholder="e.g., SAMPLE-001"
+            style="width: 100%; padding: 0.5rem 0.75rem; border: 1px solid var(--border-color, #e2e8f0); border-radius: 0.375rem; font-size: 0.875rem; background: var(--bg-primary, #fff); color: var(--text-primary, #1e293b); box-sizing: border-box;"
+          />
+        </FormField>
+      </div>
+    </Variant>
+
+    <Variant title="Required Field">
+      <div style="padding: 2rem; max-width: 400px; margin: 0 auto;">
+        <FormField label="Experiment ID" :required="true" html-for="exp-id">
+          <input
+            id="exp-id"
+            type="text"
+            placeholder="Required field"
+            style="width: 100%; padding: 0.5rem 0.75rem; border: 1px solid var(--border-color, #e2e8f0); border-radius: 0.375rem; font-size: 0.875rem; background: var(--bg-primary, #fff); color: var(--text-primary, #1e293b); box-sizing: border-box;"
+          />
+        </FormField>
+      </div>
+    </Variant>
+
+    <Variant title="With Hint">
+      <div style="padding: 2rem; max-width: 400px; margin: 0 auto;">
+        <FormField label="Concentration" hint="Enter value in micromolar (uM)" html-for="conc">
+          <input
+            id="conc"
+            type="number"
+            placeholder="0.00"
+            style="width: 100%; padding: 0.5rem 0.75rem; border: 1px solid var(--border-color, #e2e8f0); border-radius: 0.375rem; font-size: 0.875rem; background: var(--bg-primary, #fff); color: var(--text-primary, #1e293b); box-sizing: border-box;"
+          />
+        </FormField>
+      </div>
+    </Variant>
+
+    <Variant title="With Error">
+      <div style="padding: 2rem; max-width: 400px; margin: 0 auto;">
+        <FormField label="Plate Barcode" error="Barcode format is invalid. Expected: PLT-XXXX-XXXX" html-for="barcode">
+          <input
+            id="barcode"
+            type="text"
+            value="invalid"
+            style="width: 100%; padding: 0.5rem 0.75rem; border: 1px solid #ef4444; border-radius: 0.375rem; font-size: 0.875rem; background: var(--bg-primary, #fff); color: var(--text-primary, #1e293b); box-sizing: border-box;"
+          />
+        </FormField>
+      </div>
+    </Variant>
+
+    <Variant title="Form Example">
+      <div style="padding: 2rem; max-width: 400px; margin: 0 auto; display: flex; flex-direction: column; gap: 1rem;">
+        <FormField label="Experiment Name" :required="true" html-for="form-name">
+          <input
+            id="form-name"
+            type="text"
+            placeholder="Enter experiment name"
+            style="width: 100%; padding: 0.5rem 0.75rem; border: 1px solid var(--border-color, #e2e8f0); border-radius: 0.375rem; font-size: 0.875rem; background: var(--bg-primary, #fff); color: var(--text-primary, #1e293b); box-sizing: border-box;"
+          />
+        </FormField>
+        <FormField label="Description" hint="Optional description for this experiment" html-for="form-desc">
+          <textarea
+            id="form-desc"
+            placeholder="Describe the experiment..."
+            rows="3"
+            style="width: 100%; padding: 0.5rem 0.75rem; border: 1px solid var(--border-color, #e2e8f0); border-radius: 0.375rem; font-size: 0.875rem; background: var(--bg-primary, #fff); color: var(--text-primary, #1e293b); resize: vertical; box-sizing: border-box;"
+          />
+        </FormField>
+        <FormField label="Plate Count" :required="true" error="Must be between 1 and 50" html-for="form-count">
+          <input
+            id="form-count"
+            type="number"
+            value="100"
+            style="width: 100%; padding: 0.5rem 0.75rem; border: 1px solid #ef4444; border-radius: 0.375rem; font-size: 0.875rem; background: var(--bg-primary, #fff); color: var(--text-primary, #1e293b); box-sizing: border-box;"
+          />
+        </FormField>
+      </div>
+    </Variant>
+
+    <Variant title="With required / optional badges">
+      <div style="padding: 2rem; max-width: 420px; display: flex; flex-direction: column; gap: 1rem;">
+        <FormField label="Experiment name" required>
+          <BaseInput model-value="Dose-response screen · Oncology" />
+        </FormField>
+        <FormField label="Notes" :show-optional="true" hint="Add any context future you will thank present you for.">
+          <BaseTextarea model-value="" placeholder="Anything worth remembering…" />
+        </FormField>
+      </div>
+    </Variant>
+  </Story>
+</template>

package/src/components/FormField.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+/** Wraps a form control with a label, optional hint text, and validation error display. */
+import { computed } from 'vue'
+
+interface Props {
+  label?: string
+  error?: string
+  hint?: string
+  required?: boolean
+  showOptional?: boolean
+  htmlFor?: string
+  fieldId?: string
+}
+
+const props = defineProps<Props>()
+
+const errorId = computed(() =>
+  props.error && props.fieldId ? `${props.fieldId}-error` : undefined
+)
+
+const hintId = computed(() =>
+  !props.error && props.hint && props.fieldId ? `${props.fieldId}-hint` : undefined
+)
+
+const describedBy = computed(() => errorId.value ?? hintId.value)
+</script>
+
+<template>
+  <div class="mld-form-field">
+    <div v-if="label" class="mld-form-field__label-row">
+      <label
+        :for="htmlFor"
+        class="mld-form-field__label"
+      >
+        {{ label }}
+        <span v-if="required" class="mld-form-field__required" aria-hidden="true">*</span>
+      </label>
+      <span
+        v-if="!required && showOptional"
+        class="mld-form-field__optional"
+      >
+        optional
+      </span>
+    </div>
+
+    <slot :described-by="describedBy" />
+
+    <p v-if="error" :id="errorId" class="mld-form-field__error" role="alert">
+      {{ error }}
+    </p>
+    <p v-else-if="hint" :id="hintId" class="mld-form-field__hint">
+      {{ hint }}
+    </p>
+  </div>
+</template>
+
+<style>
+@import '../styles/components/form-field.css';
+</style>

package/src/components/FormFieldRenderer.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+/**
+ * Renders a single form field inside a FormField wrapper.
+ *
+ * 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.
+ */
+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'
+
+interface Props {
+  field: FormFieldSchema
+  resolvedProps: Record<string, unknown>
+  form: UseFormReturn<Record<string, unknown>>
+}
+
+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)
+}
+</script>
+
+<template>
+  <FormField
+    :label="field.label"
+    :error="errorMessage ?? undefined"
+    :hint="field.hint"
+    :required="!!field.validation?.required"
+    :html-for="field.name"
+  >
+    <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>

package/src/components/FormSection.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+/**
+ * Renders a single `FormSectionSchema` inside a FormBuilder.
+ *
+ * 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>`.
+ */
+import { computed } from 'vue'
+import type { FormSectionSchema, UseFormBuilderReturn } from '../types/form-builder'
+import CollapsibleCard from './CollapsibleCard.vue'
+import FormFieldRenderer from './FormFieldRenderer.vue'
+
+interface Props {
+  section: FormSectionSchema
+  builder: UseFormBuilderReturn<Record<string, unknown>>
+}
+
+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)`,
+}))
+</script>
+
+<template>
+  <div v-if="visibleFields.length > 0" class="mld-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="mld-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="mld-form-section--static">
+        <div v-if="section.title || section.description" class="mld-form-section__header">
+          <h3 v-if="section.title" class="mld-form-section__title">{{ section.title }}</h3>
+          <p v-if="section.description" class="mld-form-section__description">{{ section.description }}</p>
+        </div>
+        <div class="mld-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>
+</template>
+
+<style>
+@import '../styles/components/form-builder.css';
+</style>