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

package/src/components/SettingsModal.vue

@@ -2,8 +2,9 @@
 /**
  * Tabbed settings modal with three usage modes:
  *
- *   1. Schema-driven (recommended) — pass `schema` + `v-model:values`. Each
- *      group becomes a tab; fields auto-render via the SDK's FormFieldRenderer
+ *   1. Schema-driven (recommended) — pass `schema`, compact `controls`, or a
+ *      complete `defineControlModel()` result plus `v-model:values`. Each
+ *      group/section becomes a tab; fields auto-render via the SDK form field
  *      registry (text, select, number, toggle, molecule, concentration, …).
  *      Conditional visibility, validation, and dynamic options come for free.
  *
@@ -19,20 +20,37 @@
  */
 import { ref, computed, watch } from 'vue'
 import BaseModal from './BaseModal.vue'
-import FormFieldRenderer from './FormFieldRenderer.vue'
+import FormFieldRendererInternal from './internal/FormFieldRendererInternal.vue'
 import { useFormBuilder } from '../composables/useFormBuilder'
+import {
+  controlsToSettingsSchema,
+  defineControlModel,
+  mergeControlWorkspaceOptions,
+  type ControlModel,
+  type ControlModelBinding,
+  type ControlSchema,
+  type ControlWorkspaceOptions,
+} from '../composables/useControlSchema'
 import { useSettingsStore, colorPalettes } from '../stores/settings'
+import {
+  formSchemaFieldNames,
+  pickExistingRecordKeys,
+  pickRecordKeys,
+  recordValuesEqualForKeys,
+} from '../utils/formModelSync'
 import type {
   ThemeMode,
   ColorPalette,
   TableDensity,
   SettingsTab,
+  SettingsTabInput,
   SettingsModalLayout,
   SettingsModalSchema,
   FormSchema,
   FormSectionSchema,
   FormEnhancements,
 } from '../types'
+import { normalizeItemInput } from '../utils/items'
 
 // Map our settings groups onto the form-builder's flat-section shape.
 // `title: ''` because the rail/pane header already shows the group name.
@@ -52,13 +70,19 @@ interface Props {
   modelValue: boolean
   title?: string
   /** Manual tab descriptors. Ignored when `schema` is set (groups become tabs). */
-  tabs?: SettingsTab[]
+  tabs?: SettingsTabInput[]
   showAppearance?: boolean
   size?: 'md' | 'lg' | 'xl'
   layout?: SettingsModalLayout
   /** Declarative schema — fields auto-render via SDK form components. */
   schema?: SettingsModalSchema
-  /** Two-way bound values when `schema` is set. */
+  /** Model returned by defineControlModel(), or a raw nested ControlModel for one-step settings generation. */
+  model?: ControlModel | ControlModelBinding
+  /** Compact controls model — converted to `schema` when `schema` is not set. */
+  controls?: ControlSchema
+  /** Conversion options for `controls`, such as section labels, columns, and shared initialValues. */
+  controlOptions?: ControlWorkspaceOptions
+  /** Two-way bound values when `schema`, `model`, or `controls` is set. */
   values?: Record<string, unknown>
   /** Optional dynamic enhancements (validators, dynamic options, callbacks). */
   enhancements?: FormEnhancements<Record<string, unknown>>
@@ -70,6 +94,7 @@ const props = withDefaults(defineProps<Props>(), {
   showAppearance: true,
   size: 'lg',
   layout: 'horizontal',
+  model: undefined,
 })
 
 const emit = defineEmits<{
@@ -95,35 +120,93 @@ const uid = `mint-settings-${Math.random().toString(36).slice(2, 9)}`
 const tabId = (id: string) => `${uid}-tab-${id}`
 const panelId = (id: string) => `${uid}-panel-${id}`
 
-// `props.schema` is read once at setup. Pass a stable schema object (declare it
-// at module scope, not inside a render function) — the form-builder is not
-// re-initialized when the prop changes. To swap schemas, key the modal:
-// `<SettingsModal :key="schemaId" :schema="schemaA" />`.
-const builder = props.schema
-  ? useFormBuilder(buildFlatSchema(props.schema), props.values, props.enhancements)
-  : null
-
-if (builder) {
-  watch(
-    () => ({ ...builder.form.data }),
-    (data) => emit('update:values', data as Record<string, unknown>),
-    { deep: true },
-  )
-}
+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 settingsSchema = computed<SettingsModalSchema | undefined>(() =>
+  props.schema ?? (
+    resolvedControls.value
+      ? controlsToSettingsSchema(resolvedControls.value, resolvedControlOptions.value)
+      : undefined
+  ),
+)
+const isSchemaDriven = computed(() => !!settingsSchema.value)
+const resolvedValues = computed<Record<string, unknown>>(() => ({
+  ...(resolvedControlOptions.value.initialValues ?? {}),
+  ...(props.values ?? {}),
+}))
+
+// Schema-driven mode keeps one form-builder instance and syncs schema changes
+// into it, so callers can swap groups/fields without remounting the modal.
+const builder = useFormBuilder(
+  settingsSchema.value ? buildFlatSchema(settingsSchema.value) : { sections: [] },
+  resolvedValues.value,
+  props.enhancements,
+)
+
+watch(
+  () => settingsSchema.value,
+  (schema) => {
+    if (!schema) {
+      builder.updateSchema({ sections: [] }, {})
+      return
+    }
+
+    const flatSchema = buildFlatSchema(schema)
+    const fieldNames = formSchemaFieldNames(flatSchema)
+    const sourceValues = props.values === undefined
+      ? {
+          ...resolvedValues.value,
+          ...(builder.form.data as Record<string, unknown>),
+        }
+      : resolvedValues.value
+
+    builder.updateSchema(flatSchema, pickExistingRecordKeys(sourceValues ?? {}, fieldNames))
+  },
+  { deep: true },
+)
+
+watch(
+  () => ({ ...resolvedValues.value }),
+  (data) => {
+    if (!settingsSchema.value) return
+    const fieldNames = builderFieldNames()
+    if (recordValuesEqualForKeys(data, builder.form.data as Record<string, unknown>, fieldNames)) return
+    builder.reset(pickRecordKeys(data, fieldNames))
+  },
+  { deep: true },
+)
+
+watch(
+  () => ({ ...builder.form.data }),
+  (data) => {
+    if (settingsSchema.value) emit('update:values', data as Record<string, unknown>)
+  },
+  { deep: true },
+)
 
 // Schema groups whose `condition` evaluates false against the current data are
 // dropped from the rail entirely — same semantics as section visibility in
 // FormBuilder. Manual `tabs` have no condition mechanism, so they pass through.
 const visibleSchemaGroups = computed(() =>
-  builder && props.schema
-    ? props.schema.groups.filter((g) => builder.isSectionVisible(g.id))
+  settingsSchema.value
+    ? settingsSchema.value.groups.filter((g) => builder.isSectionVisible(g.id))
     : [],
 )
 
+const manualTabs = computed<SettingsTab[]>(() => props.tabs.map(normalizeItemInput))
+
 const allTabs = computed<SettingsTab[]>(() => {
-  const base: SettingsTab[] = props.schema
+  const base: SettingsTab[] = settingsSchema.value
     ? visibleSchemaGroups.value.map((g) => ({ id: g.id, label: g.label, icon: g.icon, description: g.description }))
-    : props.tabs
+    : manualTabs.value
   return props.showAppearance ? [...base, APPEARANCE_TAB] : base
 })
 
@@ -145,7 +228,7 @@ const activeGroup = computed(() =>
 )
 
 const activeGroupVisibleFields = computed(() => {
-  if (!activeGroup.value || !builder) return []
+  if (!activeGroup.value) return []
   return activeGroup.value.fields.filter((f) => builder.isFieldVisible(f.name))
 })
 
@@ -165,6 +248,14 @@ function handleClose() {
   emit('update:modelValue', false)
   emit('close')
 }
+
+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
+}
 </script>
 
 <template>
@@ -243,7 +334,7 @@ function handleClose() {
 
         <div :class="isVertical ? 'mint-settings-modal__pane-body' : null">
           <div
-            v-if="schema && builder && activeGroup"
+            v-if="isSchemaDriven && activeGroup"
             class="mint-settings-modal__group-grid"
             :style="{ '--mint-settings-cols': activeGroup.columns ?? 1 }"
           >
@@ -255,7 +346,7 @@ function handleClose() {
                   :form="builder.form"
                   :field-props="builder.form.getFieldProps(field.name)"
                 >
-                  <FormFieldRenderer
+                  <FormFieldRendererInternal
                     :field="field"
                     :resolved-props="builder.getResolvedFieldProps(field)"
                     :form="builder.form"
@@ -265,8 +356,8 @@ function handleClose() {
             </template>
           </div>
 
-          <template v-else-if="!builder">
-            <template v-for="tab in tabs" :key="tab.id">
+          <template v-else-if="!isSchemaDriven">
+            <template v-for="tab in manualTabs" :key="tab.id">
               <div v-show="activeTab === tab.id">
                 <slot :name="`tab-${tab.id}`" />
               </div>

package/src/components/TagsInput.vue

@@ -1,6 +1,8 @@
 <script setup lang="ts">
 /** Lets users type and add tags with autocomplete suggestions, categories, and a max-tag cap. */
 import { ref, computed } from 'vue'
+import { useSelectionLimit } from '../composables/useSelectionLimit'
+import { useDropdownState } from '../composables/useDropdownState'
 
 interface TagSuggestion {
   value: string
@@ -43,13 +45,23 @@ const emit = defineEmits<{
 
 const inputValue = ref('')
 const inputRef = ref<HTMLInputElement>()
-const dropdownOpen = ref(false)
 const highlightedIndex = ref(-1)
+const {
+  isOpen: dropdownOpen,
+  rootRef,
+  open: openDropdown,
+  close: closeDropdown,
+} = useDropdownState({
+  onClose: () => {
+    highlightedIndex.value = -1
+  },
+})
 
-const canAddMore = computed(() => {
-  if (props.maxTags === undefined) return true
-  return props.modelValue.length < props.maxTags
+const selectionLimit = useSelectionLimit({
+  count: () => props.modelValue.length,
+  max: () => props.maxTags,
 })
+const canAddMore = selectionLimit.canAddMore
 
 const normalizedSuggestions = computed<TagSuggestion[]>(() => {
   return props.suggestions.map(s => typeof s === 'string' ? { value: s } : s)
@@ -73,7 +85,7 @@ function categoryFor(tag: string): TagCategory | undefined {
 function addTag(value: string) {
   const trimmed = value.trim()
   if (!trimmed) return
-  if (!canAddMore.value) return
+  if (!selectionLimit.canAdd()) return
 
   // If a category is active and user didn't already type a prefix, prepend it
   let final = trimmed
@@ -85,8 +97,7 @@ function addTag(value: string) {
 
   emit('update:modelValue', [...props.modelValue, final])
   inputValue.value = ''
-  dropdownOpen.value = false
-  highlightedIndex.value = -1
+  closeDropdown()
 }
 
 function removeTag(index: number) {
@@ -100,7 +111,7 @@ function handleKeydown(event: KeyboardEvent) {
   if (event.key === 'ArrowDown' && filteredSuggestions.value.length) {
     event.preventDefault()
     highlightedIndex.value = Math.min(highlightedIndex.value + 1, filteredSuggestions.value.length - 1)
-    dropdownOpen.value = true
+    openDropdown()
     return
   }
   if (event.key === 'ArrowUp' && filteredSuggestions.value.length) {
@@ -118,8 +129,7 @@ function handleKeydown(event: KeyboardEvent) {
     return
   }
   if (event.key === 'Escape') {
-    dropdownOpen.value = false
-    highlightedIndex.value = -1
+    closeDropdown()
     return
   }
   if (event.key === 'Backspace' && !inputValue.value && props.modelValue.length > 0) {
@@ -128,13 +138,13 @@ function handleKeydown(event: KeyboardEvent) {
 }
 
 function handleFocus() {
-  if (filteredSuggestions.value.length) dropdownOpen.value = true
+  if (filteredSuggestions.value.length) openDropdown()
 }
 
 function handleBlur() {
   // Delay so a click on a suggestion fires first
   setTimeout(() => {
-    dropdownOpen.value = false
+    closeDropdown()
   }, 120)
 }
 
@@ -147,7 +157,7 @@ function handlePaste(event: ClipboardEvent) {
   const newTags = [...props.modelValue]
 
   for (const tag of tags) {
-    if (!canAddMore.value) break
+    if (!selectionLimit.canAdd(1, newTags.length)) break
     if (!props.allowDuplicates && newTags.includes(tag)) continue
     newTags.push(tag)
   }
@@ -164,13 +174,18 @@ function setCategory(prefix: string) {
 }
 
 function onInputEvent() {
-  dropdownOpen.value = filteredSuggestions.value.length > 0
+  if (filteredSuggestions.value.length > 0) {
+    openDropdown()
+  } else {
+    closeDropdown()
+  }
   highlightedIndex.value = -1
 }
 </script>
 
 <template>
   <div
+    ref="rootRef"
     :class="[
       'mint-tags-input',
       `mint-tags-input--${size}`,

package/src/components/ThemeToggle.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 /** Icon button that toggles between light and dark mode, swapping sun/moon icons to reflect the active theme. */
 import { useTheme } from '../composables/useTheme'
+import IconButton from './IconButton.vue'
 
 interface Props {
   size?: 'sm' | 'md' | 'lg'
@@ -14,16 +15,17 @@ const { isDark, toggleTheme } = useTheme()
 </script>
 
 <template>
-  <button
-    type="button"
-    :class="['mint-theme-toggle', `mint-theme-toggle--${size}`]"
-    :aria-label="isDark ? 'Switch to light mode' : 'Switch to dark mode'"
+  <IconButton
+    class="mint-theme-toggle"
+    variant="ghost"
+    :size="size"
+    :label="isDark ? 'Switch to light mode' : 'Switch to dark mode'"
     @click="toggleTheme"
   >
     <!-- Lucide sun -->
     <svg
       v-if="isDark"
-      :class="`mint-theme-toggle__icon--${size}`"
+      class="mint-theme-toggle__icon"
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
@@ -36,7 +38,7 @@ const { isDark, toggleTheme } = useTheme()
     <!-- Lucide moon -->
     <svg
       v-else
-      :class="`mint-theme-toggle__icon--${size}`"
+      class="mint-theme-toggle__icon"
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
@@ -46,7 +48,7 @@ const { isDark, toggleTheme } = useTheme()
     >
       <path d="M20.985 12.486a9 9 0 1 1-9.473-9.472c.405-.022.617.46.402.803a6 6 0 0 0 8.268 8.268c.344-.215.825-.004.803.401" />
     </svg>
-  </button>
+  </IconButton>
 </template>
 
 <style>

package/src/components/TimePicker.vue

@@ -1,7 +1,13 @@
 <script setup lang="ts">
 /** Input that opens a scrollable time-slot dropdown in 12h or 24h format, with min/max range. */
-import { ref, computed, watch, nextTick, onMounted, onUnmounted } from 'vue'
-import { generateTimeSlots, formatTime, parseTime, compareTime } from '../composables/useTimeUtils'
+import { ref, computed, watch, nextTick } from 'vue'
+import { useDropdownState } from '../composables/useDropdownState'
+import {
+  compareTime,
+  findNearestTimeSlotIndex,
+  formatTimeSlot,
+  generateTimeSlots,
+} from '../composables/useTimeUtils'
 
 interface Props {
   modelValue?: string
@@ -30,10 +36,9 @@ const emit = defineEmits<{
   'update:modelValue': [value: string | undefined]
 }>()
 
-const isOpen = ref(false)
-const containerRef = ref<HTMLDivElement>()
-const listRef = ref<HTMLUListElement>()
+const listRef = ref<HTMLUListElement | null>(null)
 const highlightedIndex = ref(-1)
+const { isOpen, rootRef, open, close, toggle } = useDropdownState()
 
 const slots = computed(() => {
   const start = props.min ?? '00:00'
@@ -43,8 +48,7 @@ const slots = computed(() => {
 
 const displayValue = computed(() => {
   if (!props.modelValue) return ''
-  const { hour, minute } = parseTime(props.modelValue)
-  return formatTime(hour, minute, props.format)
+  return formatTimeSlot(props.modelValue, props.format)
 })
 
 function isSlotDisabled(slot: string): boolean {
@@ -56,23 +60,17 @@ function isSlotDisabled(slot: string): boolean {
 function selectSlot(slot: string) {
   if (isSlotDisabled(slot) || props.disabled) return
   emit('update:modelValue', slot)
-  isOpen.value = false
+  close()
 }
 
 function clear() {
   emit('update:modelValue', undefined)
-  isOpen.value = false
+  close()
 }
 
 function toggleDropdown() {
   if (props.disabled) return
-  isOpen.value = !isOpen.value
-}
-
-function handleClickOutside(event: MouseEvent) {
-  if (containerRef.value && !containerRef.value.contains(event.target as Node)) {
-    isOpen.value = false
-  }
+  toggle()
 }
 
 function scrollToActiveSlot() {
@@ -95,26 +93,14 @@ function scrollToActiveSlot() {
 }
 
 function findNearestSlotIndex(time: string): number {
-  if (slots.value.length === 0) return -1
-  let bestIndex = 0
-  let bestDiff = Infinity
-  for (let i = 0; i < slots.value.length; i++) {
-    const { hour: h1, minute: m1 } = parseTime(slots.value[i])
-    const { hour: h2, minute: m2 } = parseTime(time)
-    const minuteDiff = Math.abs((h1 * 60 + m1) - (h2 * 60 + m2))
-    if (minuteDiff < bestDiff) {
-      bestDiff = minuteDiff
-      bestIndex = i
-    }
-  }
-  return bestIndex
+  return findNearestTimeSlotIndex(time, slots.value)
 }
 
 function handleKeydown(event: KeyboardEvent) {
   if (!isOpen.value) {
     if (event.key === 'Enter' || event.key === ' ' || event.key === 'ArrowDown') {
       event.preventDefault()
-      isOpen.value = true
+      open()
       return
     }
     return
@@ -150,7 +136,7 @@ function handleKeydown(event: KeyboardEvent) {
     }
     case 'Escape': {
       event.preventDefault()
-      isOpen.value = false
+      close()
       break
     }
   }
@@ -180,18 +166,10 @@ watch(isOpen, (open) => {
     highlightedIndex.value = -1
   }
 })
-
-onMounted(() => {
-  document.addEventListener('click', handleClickOutside)
-})
-
-onUnmounted(() => {
-  document.removeEventListener('click', handleClickOutside)
-})
 </script>
 
 <template>
-  <div ref="containerRef" class="mint-time-picker" @keydown="handleKeydown">
+  <div ref="rootRef" class="mint-time-picker" @keydown="handleKeydown">
     <div class="mint-time-picker__input-wrapper">
       <input
         type="text"
@@ -260,7 +238,7 @@ onUnmounted(() => {
             ]"
             @click="selectSlot(slot)"
           >
-            {{ formatTime(parseTime(slot).hour, parseTime(slot).minute, format) }}
+            {{ formatTimeSlot(slot, format) }}
           </li>
         </ul>
       </div>

package/src/components/Tooltip.vue

@@ -2,6 +2,7 @@
 /** Floating tooltip using @floating-ui with auto-flip, delay, optional keyboard shortcut badge, and body Teleport. */
 import { ref, onBeforeUnmount, nextTick } from 'vue'
 import { computePosition, flip, offset, shift, type Placement } from '@floating-ui/dom'
+import { useEventListener } from '../composables/useEventListener'
 
 interface Props {
   text: string
@@ -42,22 +43,18 @@ async function updatePosition() {
   actualPlacement.value = placement
 }
 
-function addListeners() {
-  window.addEventListener('scroll', updatePosition, { passive: true, capture: true })
-  window.addEventListener('resize', updatePosition)
-}
-
-function removeListeners() {
-  window.removeEventListener('scroll', updatePosition, { capture: true })
-  window.removeEventListener('resize', updatePosition)
-}
+useEventListener(() => window, 'scroll', updatePosition, {
+  passive: true,
+  capture: true,
+  enabled: visible,
+})
+useEventListener(() => window, 'resize', updatePosition, { enabled: visible })
 
 async function show() {
   timeoutId = setTimeout(async () => {
     visible.value = true
     await nextTick()
     await updatePosition()
-    addListeners()
   }, props.delay)
 }
 
@@ -65,12 +62,10 @@ function hide() {
   clearTimeout(timeoutId)
   timeoutId = undefined
   visible.value = false
-  removeListeners()
 }
 
 onBeforeUnmount(() => {
   clearTimeout(timeoutId)
-  removeListeners()
 })
 
 function resolvedMaxWidth(value: string | number | undefined): string | undefined {

package/src/components/WellPlate.vue

@@ -1,8 +1,9 @@
 <script setup lang="ts">
 /** Interactive 96/384-well plate grid with drag-to-select, heatmap overlays, per-well editing, and sample-color mapping. */
-import { ref, computed, onMounted, onUnmounted } from 'vue'
+import { ref, computed } from 'vue'
 import type { WellPlateFormat, WellPlateSelectionMode, WellPlateSize, Well, HeatmapConfig, WellShape, WellEditField, WellEditData, WellLegendItem, ColumnCondition, RowCondition } from '../types'
-import WellEditPopup from './WellEditPopup.vue'
+import { useEventListener } from '../composables/useEventListener'
+import WellEditPopupInternal from './internal/WellEditPopupInternal.vue'
 
 interface Props {
   modelValue?: string[]
@@ -562,15 +563,8 @@ function handleKeyDown(event: KeyboardEvent) {
   }
 }
 
-onMounted(() => {
-  document.addEventListener('mouseup', handleMouseUp)
-  document.addEventListener('keydown', handleKeyDown)
-})
-
-onUnmounted(() => {
-  document.removeEventListener('mouseup', handleMouseUp)
-  document.removeEventListener('keydown', handleKeyDown)
-})
+useEventListener(() => document, 'mouseup', handleMouseUp)
+useEventListener(() => document, 'keydown', handleKeyDown)
 
 const containerStyle = computed(() =>
   isFillMode.value ? {} : {
@@ -811,7 +805,7 @@ const tableStyle = computed(() => ({
     </div>
 
     <!-- Edit popup -->
-    <WellEditPopup
+    <WellEditPopupInternal
       v-if="editable && editingWellId"
       :well-id="editingWellId"
       :well-data="wells[editingWellId]"