@morscherlab/mint-sdk 1.0.0-rc.2 → 1.0.0-rc.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.5",
   "description": "MINT Platform SDK — Vue 3 components, composables, and types for plugin development. MINT = Mass-spec INtegrated Toolkit.",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/components/AppTopBar.navigation.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import {
+  currentItemIdFromLocation,
+  currentPagePath,
+  normalizeNavPath,
+  pageIdFromPath,
+  pluginNavItemToPageSelectorItem,
+} from '../../components/AppTopBar.navigation'
+
+describe('AppTopBar navigation helpers', () => {
+  it('normalizes blank, relative, and trailing-slash paths', () => {
+    expect(normalizeNavPath()).toBe('/')
+    expect(normalizeNavPath('results')).toBe('/results')
+    expect(normalizeNavPath('/results/')).toBe('/results')
+    expect(normalizeNavPath(' /analysis/run/ ')).toBe('/analysis/run')
+  })
+
+  it('derives stable page ids from paths', () => {
+    expect(pageIdFromPath('/', 'fallback')).toBe('dashboard')
+    expect(pageIdFromPath('/analysis/run', 'fallback')).toBe('analysis-run')
+    expect(pageIdFromPath('', 'fallback')).toBe('dashboard')
+  })
+
+  it('maps plugin nav items to page selector items with plugin fallbacks', () => {
+    expect(
+      pluginNavItemToPageSelectorItem(
+        { label: 'Results', path: 'results' },
+        1,
+        { pluginIcon: 'flask', pluginName: 'Assay Plugin' },
+      ),
+    ).toEqual({
+      id: 'results',
+      label: 'Results',
+      to: '/results',
+      icon: 'flask',
+      hint: 'Assay Plugin',
+    })
+  })
+
+  it('prefers explicit nav item id, icon, and description', () => {
+    expect(
+      pluginNavItemToPageSelectorItem(
+        {
+          id: 'custom',
+          label: 'Custom',
+          path: '/custom',
+          icon: 'sparkles',
+          description: 'Custom page',
+        },
+        0,
+        { pluginIcon: 'flask', pluginName: 'Assay Plugin' },
+      ),
+    ).toMatchObject({
+      id: 'custom',
+      icon: 'sparkles',
+      hint: 'Custom page',
+    })
+  })
+
+  it('matches current route-relative page ids for integrated plugins', () => {
+    const pages = [
+      { id: 'overview', to: '/' },
+      { id: 'results', to: '/results' },
+    ]
+
+    expect(currentPagePath('/plugins/assay', '/plugins/assay')).toBe('/')
+    expect(currentPagePath('/plugins/assay/results', '/plugins/assay')).toBe('/results')
+    expect(currentItemIdFromLocation(pages, '/plugins/assay/results', '/plugins/assay')).toBe('results')
+  })
+})

package/src/__tests__/components/DoseCalculatorVolumeField.test.ts

@@ -0,0 +1,53 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import DoseCalculatorVolumeField from '../../components/DoseCalculatorVolumeField.vue'
+
+describe('DoseCalculatorVolumeField', () => {
+  it('emits value updates while preserving the current unit', async () => {
+    const wrapper = mount(DoseCalculatorVolumeField, {
+      props: {
+        label: 'Final Volume',
+        modelValue: { value: 1, unit: 'mL' },
+        units: ['µL', 'mL', 'L'],
+      },
+    })
+
+    await wrapper.get('input').setValue('2.5')
+
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([
+      { value: 2.5, unit: 'mL' },
+    ])
+  })
+
+  it('emits unit updates while preserving the current value', async () => {
+    const wrapper = mount(DoseCalculatorVolumeField, {
+      props: {
+        label: 'Volume per Well',
+        modelValue: { value: 100, unit: 'µL' },
+        units: ['µL', 'mL', 'L'],
+      },
+    })
+
+    await wrapper.get('select').setValue('mL')
+
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([
+      { value: 100, unit: 'mL' },
+    ])
+  })
+
+  it('ignores non-numeric value input', async () => {
+    const wrapper = mount(DoseCalculatorVolumeField, {
+      props: {
+        label: 'Final Volume',
+        modelValue: { value: 1, unit: 'mL' },
+        units: ['µL', 'mL', 'L'],
+      },
+    })
+
+    const input = wrapper.get('input')
+    ;(input.element as HTMLInputElement).value = ''
+    await input.trigger('input')
+
+    expect(wrapper.emitted('update:modelValue')).toBeUndefined()
+  })
+})

package/src/__tests__/components/PlateMapEditorToolbarInternal.test.ts

@@ -0,0 +1,54 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it, vi } from 'vitest'
+import PlateMapEditorToolbarInternal from '../../components/internal/PlateMapEditorToolbarInternal.vue'
+import type { PlateMap } from '../../types'
+
+const plates: PlateMap[] = [
+  { id: 'plate-1', name: 'Plate 1', format: 96, wells: {} },
+  { id: 'plate-2', name: 'Plate 2', format: 96, wells: {} },
+]
+
+function mountToolbar(props = {}) {
+  return mount(PlateMapEditorToolbarInternal, {
+    props: {
+      plates,
+      activePlateId: 'plate-1',
+      plateWellCounts: { 'plate-1': 3, 'plate-2': 0 },
+      canAddPlate: true,
+      canUndo: false,
+      canRedo: true,
+      slotColorForPlate: vi.fn((_plateId: string, index: number) => (index === 0 ? '#ef4444' : '#22c55e')),
+      ...props,
+    },
+  })
+}
+
+describe('PlateMapEditorToolbarInternal', () => {
+  it('renders plate tabs, active state, and well counts', () => {
+    const wrapper = mountToolbar()
+
+    const tabs = wrapper.findAll('.mint-plate-editor__tab')
+    expect(tabs).toHaveLength(2)
+    expect(tabs[0].classes()).toContain('mint-plate-editor__tab--active')
+    expect(wrapper.find('.mint-plate-editor__tab-count').text()).toBe('3')
+    expect(wrapper.find('.mint-plate-editor__add-plate').exists()).toBe(true)
+  })
+
+  it('emits tab and action events', async () => {
+    const wrapper = mountToolbar()
+
+    await wrapper.findAll('.mint-plate-editor__tab')[1].trigger('click')
+    await wrapper.findAll('.mint-plate-editor__tab-remove')[0].trigger('click')
+    await wrapper.find('.mint-plate-editor__add-plate').trigger('click')
+    await wrapper.find('[title="Redo (Ctrl+Shift+Z)"]').trigger('click')
+    await wrapper.find('[title="Import"]').trigger('click')
+    await wrapper.find('[title="Export JSON"]').trigger('click')
+
+    expect(wrapper.emitted('select-plate')?.[0]).toEqual(['plate-2'])
+    expect(wrapper.emitted('remove-plate')?.[0]).toEqual(['plate-1'])
+    expect(wrapper.emitted('add-plate')).toHaveLength(1)
+    expect(wrapper.emitted('redo')).toHaveLength(1)
+    expect(wrapper.emitted('import')).toHaveLength(1)
+    expect(wrapper.emitted('export-json')).toHaveLength(1)
+  })
+})

package/src/__tests__/components/PluginWorkspaceView.controls.test.ts

@@ -0,0 +1,156 @@
+import { nextTick, ref } from 'vue'
+import { describe, expect, it, vi } from 'vitest'
+import { defineDoseDesignControlModel } from '../../composables/useControlSchema'
+import { usePluginWorkspaceControls } from '../../components/PluginWorkspaceView.controls'
+import type {
+  ControlComponentBindingsConfig,
+  ControlComponentPropsByIdMap,
+  ControlComponentPropsMap,
+  ControlSchema,
+} from '../../composables/useControlSchema'
+
+interface CreateControlsOptions {
+  controls?: ControlSchema
+  modelValue?: () => Record<string, unknown> | undefined
+  values?: () => Record<string, unknown> | undefined
+  componentProps?: () => ControlComponentPropsMap | undefined
+  componentPropsById?: () => ControlComponentPropsByIdMap | undefined
+  componentBindings?: () => ControlComponentBindingsConfig | undefined
+  emitValues?: (values: Record<string, unknown>) => void
+}
+
+function createControls({
+  controls,
+  modelValue,
+  values,
+  componentProps,
+  componentPropsById,
+  componentBindings,
+  emitValues = vi.fn(),
+}: CreateControlsOptions = {}) {
+  return usePluginWorkspaceControls({
+    model: () => undefined,
+    controls: () => controls,
+    controlOptions: () => ({}),
+    modelValue: modelValue ?? (() => undefined),
+    values: values ?? (() => undefined),
+    componentBindings: componentBindings ?? (() => undefined),
+    componentProps: componentProps ?? (() => undefined),
+    componentPropsById: componentPropsById ?? (() => undefined),
+    emitValues,
+  })
+}
+
+describe('PluginWorkspaceView control state helpers', () => {
+  it('merges control defaults with external values and resyncs when values change', async () => {
+    const externalValues = ref<Record<string, unknown> | undefined>({ threshold: 0.2 })
+    const state = createControls({
+      controls: {
+        threshold: { label: 'Threshold', default: 0.05 },
+        mode: { label: 'Mode', default: 'fast' },
+      },
+      modelValue: () => externalValues.value,
+    })
+
+    expect(state.internalControlValues).toEqual({
+      threshold: 0.2,
+      mode: 'fast',
+    })
+
+    externalValues.value = { threshold: 0.8 }
+    await nextTick()
+
+    expect(state.internalControlValues).toEqual({
+      threshold: 0.8,
+      mode: 'fast',
+    })
+  })
+
+  it('emits updates from sidebar form values without dropping generated defaults', () => {
+    const emitValues = vi.fn()
+    const state = createControls({
+      controls: {
+        threshold: { label: 'Threshold', default: 0.05 },
+        mode: { label: 'Mode', default: 'fast' },
+      },
+      emitValues,
+    })
+
+    state.handleControlValuesUpdate({ threshold: 0.4 })
+
+    expect(state.internalControlValues).toEqual({
+      threshold: 0.4,
+      mode: 'fast',
+    })
+    expect(emitValues).toHaveBeenCalledWith({
+      threshold: 0.4,
+      mode: 'fast',
+    })
+  })
+
+  it('derives component props and bindings from one internal value model', () => {
+    const state = createControls({
+      controls: {
+        threshold: { label: 'Threshold', default: 0.05 },
+        mode: { label: 'Mode', default: 'fast' },
+      },
+      componentProps: () => ['threshold'],
+      componentPropsById: () => ({
+        chart: ['threshold', 'mode'],
+      }),
+      componentBindings: () => ({
+        chart: {
+          component: 'ChartContainer',
+          props: ['threshold'],
+        },
+      }),
+    })
+
+    expect(state.resolvedComponentProps.value).toEqual({ threshold: 0.05 })
+    expect(state.resolvedComponentPropsById.value).toEqual({
+      chart: { threshold: 0.05, mode: 'fast' },
+    })
+    expect(state.resolvedComponentBindingsById.value.chart).toMatchObject({
+      component: 'ChartContainer',
+      props: { threshold: 0.05 },
+    })
+  })
+
+  it('uses compact control model navigation and binding defaults', () => {
+    const model = defineDoseDesignControlModel({
+      selectedWells: ['A1', 'A2'],
+      includeMolecularWeight: true,
+    })
+    const state = usePluginWorkspaceControls({
+      model: () => model,
+      controls: () => undefined,
+      controlOptions: () => ({}),
+      modelValue: () => ({
+        selectedWells: ['C1'],
+        plateFormat: 384,
+        doseMode: 'dilution',
+        disabled: true,
+        molecularWeight: 450,
+      }),
+      values: () => undefined,
+      componentBindings: () => undefined,
+      componentProps: () => undefined,
+      componentPropsById: () => undefined,
+      emitValues: vi.fn(),
+    })
+
+    expect(state.generatedPillNav.value.map(item => item.id)).toEqual(['design'])
+    expect(state.generatedDefaultView.value).toBe('design')
+    expect(state.resolvedComponentBindingsById.value.plate.props).toMatchObject({
+      modelValue: ['C1'],
+      format: 384,
+      disabled: true,
+    })
+    expect(state.resolvedComponentPropsById.value.dose).toMatchObject({
+      mode: 'dilution',
+      targetWells: ['C1'],
+      disabled: true,
+      molecularWeight: 450,
+    })
+  })
+})

package/src/__tests__/components/PluginWorkspaceView.navigation.test.ts

@@ -0,0 +1,102 @@
+import { ref } from 'vue'
+import { describe, expect, it } from 'vitest'
+import type {
+  PageSelectorItem,
+  PageSelectorItemInput,
+  PillNavItem,
+  PillNavItemInput,
+} from '../../types'
+import { usePluginWorkspaceNavigation } from '../../components/PluginWorkspaceView.navigation'
+
+function makeNavigation(overrides: {
+  activeView?: string
+  defaultActiveView?: string
+  currentPillId?: string
+  currentPageSelectorId?: string
+  pillNav?: PillNavItemInput[]
+  pageSelector?: PageSelectorItemInput[]
+  panelIds?: string[]
+  generatedPillNav?: PillNavItem[]
+  generatedDefaultView?: string
+} = {}) {
+  const activeView = ref(overrides.activeView)
+  const defaultActiveView = ref(overrides.defaultActiveView)
+  const currentPillId = ref(overrides.currentPillId)
+  const currentPageSelectorId = ref(overrides.currentPageSelectorId)
+  const pillNav = ref(overrides.pillNav)
+  const pageSelector = ref(overrides.pageSelector)
+  const panelIds = ref(overrides.panelIds ?? [])
+  const generatedPillNav = ref<PillNavItem[]>(overrides.generatedPillNav ?? [])
+  const generatedDefaultView = ref(overrides.generatedDefaultView ?? '')
+  const emitted = {
+    activeView: [] as string[],
+    page: [] as PageSelectorItem[],
+    pill: [] as PillNavItem[],
+  }
+
+  const navigation = usePluginWorkspaceNavigation({
+    activeView: () => activeView.value,
+    defaultActiveView: () => defaultActiveView.value,
+    currentPillId: () => currentPillId.value,
+    currentPageSelectorId: () => currentPageSelectorId.value,
+    pillNav: () => pillNav.value,
+    pageSelector: () => pageSelector.value,
+    panelIds: () => panelIds.value,
+    generatedPillNav,
+    generatedDefaultView,
+    emitActiveView: viewId => emitted.activeView.push(viewId),
+    emitPageSelectorSelect: page => emitted.page.push(page),
+    emitPillSelect: item => emitted.pill.push(item),
+  })
+
+  return { navigation, emitted, activeView, pillNav, generatedPillNav }
+}
+
+describe('usePluginWorkspaceNavigation', () => {
+  it('derives the initial view from explicit pill nav and syncs pill selection', () => {
+    const data = { id: 'data', label: 'Data' }
+    const results = { id: 'results', label: 'Results' }
+    const { navigation, emitted } = makeNavigation({
+      pillNav: [data, results],
+      panelIds: ['fallback'],
+    })
+
+    expect(navigation.resolvedPillNav.value).toEqual([data, results])
+    expect(navigation.resolvedActiveView.value).toBe('data')
+
+    navigation.handlePillSelect(results)
+
+    expect(navigation.resolvedActiveView.value).toBe('results')
+    expect(emitted.activeView).toEqual(['results'])
+    expect(emitted.pill).toEqual([results])
+  })
+
+  it('emits page selector changes while keeping controlled active view stable', () => {
+    const overview = { id: 'overview', label: 'Overview' }
+    const { navigation, emitted } = makeNavigation({
+      activeView: 'controlled',
+      pageSelector: [overview],
+      generatedDefaultView: 'generated',
+    })
+
+    navigation.handlePageSelectorSelect(overview)
+
+    expect(navigation.resolvedActiveView.value).toBe('controlled')
+    expect(navigation.resolvedCurrentPageSelectorId.value).toBe('controlled')
+    expect(emitted.activeView).toEqual(['overview'])
+    expect(emitted.page).toEqual([overview])
+  })
+
+  it('uses generated navigation when explicit pill nav is absent', () => {
+    const generated = { id: 'design', label: 'Design' }
+    const { navigation } = makeNavigation({
+      generatedPillNav: [generated],
+      generatedDefaultView: 'design',
+      pageSelector: ['page-fallback'],
+    })
+
+    expect(navigation.resolvedPillNav.value).toEqual([generated])
+    expect(navigation.firstConfiguredViewId.value).toBe('design')
+    expect(navigation.resolvedCurrentPillId.value).toBe('design')
+  })
+})

package/src/__tests__/components/PluginWorkspaceView.shell.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import {
+  getPluginWorkspaceSidebarSlotNames,
+  getPluginWorkspaceTopBarSlotNames,
+  hasPluginWorkspaceSidebarSurface,
+} from '../../components/PluginWorkspaceView.shell'
+
+describe('PluginWorkspaceView shell helpers', () => {
+  it('selects forwarded topbar and sidebar slots by key without depending on Vue slot return types', () => {
+    const slots: Readonly<Record<string, unknown>> = {
+      default: undefined,
+      actions: undefined,
+      'settings-tab-analysis': undefined,
+      header: undefined,
+      'section-import': undefined,
+      unrelated: undefined,
+    }
+
+    expect(getPluginWorkspaceTopBarSlotNames(slots)).toEqual([
+      'actions',
+      'settings-tab-analysis',
+    ])
+    expect(getPluginWorkspaceSidebarSlotNames(slots)).toEqual([
+      'header',
+      'section-import',
+    ])
+  })
+
+  it('keeps the sidebar surface hidden when all sidebar inputs are empty', () => {
+    expect(hasPluginWorkspaceSidebarSurface({
+      showSidebar: true,
+      panels: {},
+      forms: {},
+      model: undefined,
+      controls: undefined,
+      showSidebarWhenEmpty: false,
+      hasSidebarSlot: false,
+      sidebarSlotCount: 0,
+    })).toBe(false)
+  })
+})

package/src/__tests__/components/ProtocolStep.presentation.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  PROTOCOL_STEP_TYPE_COLORS,
+  PROTOCOL_STEP_TYPE_ICONS,
+  formatProtocolDuration,
+} from '../../components/ProtocolStep.presentation'
+
+describe('ProtocolStep presentation helpers', () => {
+  it('formats protocol durations for editor and timeline displays', () => {
+    expect(formatProtocolDuration(undefined)).toBe('')
+    expect(formatProtocolDuration(15)).toBe('15m')
+    expect(formatProtocolDuration(60)).toBe('1h')
+    expect(formatProtocolDuration(95)).toBe('1h 35m')
+  })
+
+  it('keeps icons and colors available for every protocol step type', () => {
+    expect(Object.keys(PROTOCOL_STEP_TYPE_ICONS).sort()).toEqual([
+      'addition',
+      'centrifuge',
+      'custom',
+      'incubation',
+      'measurement',
+      'mix',
+      'transfer',
+      'wash',
+    ])
+    expect(PROTOCOL_STEP_TYPE_COLORS.measurement).toBe('#8B5CF6')
+    expect(PROTOCOL_STEP_TYPE_ICONS.custom).toContain('M10.325')
+  })
+})

package/src/__tests__/components/ProtocolStepEditor.state.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest'
+import type { ProtocolStep } from '../../types'
+import type { StepTemplate } from '../../composables/useProtocolTemplates'
+import {
+  buildCustomProtocolTemplate,
+  buildProtocolPreviewParams,
+  buildProtocolStepEditorState,
+  buildProtocolStepPreview,
+  buildProtocolTemplateDefaults,
+} from '../../components/ProtocolStepEditor.state'
+
+const template: StepTemplate = {
+  id: 'builtin-incubation',
+  type: 'incubation',
+  name: 'Incubation',
+  description: 'Hold samples under controlled conditions',
+  defaultDuration: 60,
+  parameters: [
+    {
+      key: 'temperature',
+      label: 'Temperature',
+      type: 'temperature',
+      unit: 'C',
+      default: 37,
+      required: true,
+    },
+    {
+      key: 'notes',
+      label: 'Notes',
+      type: 'text',
+    },
+  ],
+  isBuiltIn: true,
+}
+
+describe('ProtocolStepEditor state helpers', () => {
+  it('builds editor defaults from template parameter defaults', () => {
+    expect(buildProtocolTemplateDefaults(template)).toEqual({
+      name: 'Incubation',
+      description: 'Hold samples under controlled conditions',
+      duration: 60,
+      parameters: {
+        temperature: 37,
+      },
+    })
+  })
+
+  it('initializes editor fields from an existing step', () => {
+    const step: ProtocolStep = {
+      id: 'step-1',
+      type: 'incubation',
+      name: 'Overnight incubation',
+      description: 'Long run',
+      duration: 720,
+      status: 'in_progress',
+      parameters: {
+        temperature: 4,
+      },
+      order: 3,
+    }
+
+    const state = buildProtocolStepEditorState(step, (type) => (
+      type === 'incubation' ? template : undefined
+    ))
+
+    expect(state).toEqual({
+      selectedTemplateId: 'builtin-incubation',
+      fields: {
+        name: 'Overnight incubation',
+        description: 'Long run',
+        duration: 720,
+        parameters: {
+          temperature: 4,
+        },
+      },
+    })
+  })
+
+  it('preserves source step metadata when building a preview', () => {
+    const preview = buildProtocolStepPreview(
+      template,
+      {
+        name: '',
+        description: 'Preview description',
+        parameters: {
+          temperature: 25,
+        },
+      },
+      {
+        id: 'step-2',
+        type: 'incubation',
+        name: 'Source',
+        status: 'completed',
+        order: 5,
+      }
+    )
+
+    expect(preview).toEqual({
+      id: 'step-2',
+      type: 'incubation',
+      name: 'Incubation',
+      description: 'Preview description',
+      duration: 60,
+      status: 'completed',
+      parameters: {
+        temperature: 25,
+      },
+      order: 5,
+    })
+  })
+
+  it('formats only populated preview parameters', () => {
+    const formatted = buildProtocolPreviewParams(
+      template,
+      {
+        temperature: 37,
+        notes: '',
+      },
+      (value, parameter) => `${parameter.label}: ${value}`
+    )
+
+    expect(formatted).toBe('Temperature: 37')
+  })
+
+  it('creates a custom template from the current editor fields', () => {
+    expect(
+      buildCustomProtocolTemplate(
+        template,
+        {
+          name: 'Cold incubation',
+          description: 'Cold room workflow',
+          duration: 120,
+          parameters: {
+            temperature: 4,
+            notes: 'keep covered',
+          },
+        },
+        'custom-fixed'
+      )
+    ).toEqual({
+      id: 'custom-fixed',
+      type: 'incubation',
+      name: 'Cold incubation',
+      description: 'Cold room workflow',
+      defaultDuration: 120,
+      parameters: [
+        {
+          key: 'temperature',
+          label: 'Temperature',
+          type: 'temperature',
+          unit: 'C',
+          default: 4,
+          required: true,
+        },
+        {
+          key: 'notes',
+          label: 'Notes',
+          type: 'text',
+          default: 'keep covered',
+        },
+      ],
+      isBuiltIn: false,
+    })
+  })
+})