@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.4

package/src/__tests__/composables/useSelectionLimit.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { ref } from 'vue'
+import { useSelectionLimit } from '../../composables/useSelectionLimit'
+
+describe('useSelectionLimit', () => {
+  it('tracks unlimited selections', () => {
+    const count = ref(4)
+    const limit = useSelectionLimit({ count })
+
+    expect(limit.isLimited.value).toBe(false)
+    expect(limit.canAddMore.value).toBe(true)
+    expect(limit.remaining.value).toBeUndefined()
+    expect(limit.canAdd(100)).toBe(true)
+  })
+
+  it('tracks remaining capacity from reactive count and max values', () => {
+    const count = ref(1)
+    const max = ref<number | undefined>(3)
+    const limit = useSelectionLimit({ count, max })
+
+    expect(limit.isLimited.value).toBe(true)
+    expect(limit.remaining.value).toBe(2)
+    expect(limit.canAdd(2)).toBe(true)
+    expect(limit.canAdd(3)).toBe(false)
+
+    count.value = 3
+    expect(limit.canAddMore.value).toBe(false)
+    expect(limit.isAtLimit.value).toBe(true)
+
+    max.value = undefined
+    expect(limit.isLimited.value).toBe(false)
+    expect(limit.canAdd(3)).toBe(true)
+  })
+
+  it('can evaluate a candidate count without mutating the current count', () => {
+    const limit = useSelectionLimit({ count: 1, max: 3 })
+
+    expect(limit.canAdd(1, 2)).toBe(true)
+    expect(limit.canAdd(1, 3)).toBe(false)
+  })
+})

package/src/__tests__/composables/useSortedItems.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest'
+import { computed, ref } from 'vue'
+import {
+  compareSortValues,
+  useSortedItems,
+  type SortDescriptor,
+} from '../../composables/useSortedItems'
+
+describe('useSortedItems', () => {
+  const items = [
+    { name: 'Lactate', score: 2, supplier: 'Cayman' },
+    { name: 'Glucose', score: undefined, supplier: 'Sigma' },
+    { name: 'Pyruvate', score: 5, supplier: 'Thermo' },
+  ]
+
+  it('sorts by a reactive descriptor and keeps empty values last', () => {
+    const sort = ref<SortDescriptor<'score'>>({ key: 'score', direction: 'asc' })
+    const sorted = useSortedItems({
+      items,
+      sort,
+      getValue: (item, key) => item[key],
+    })
+
+    expect(sorted.sortedItems.value.map(item => item.name)).toEqual([
+      'Lactate',
+      'Pyruvate',
+      'Glucose',
+    ])
+
+    sort.value = { key: 'score', direction: 'desc' }
+    expect(sorted.sortedItems.value.map(item => item.name)).toEqual([
+      'Pyruvate',
+      'Lactate',
+      'Glucose',
+    ])
+  })
+
+  it('returns all items in original order when disabled', () => {
+    const enabled = ref(false)
+    const sorted = useSortedItems({
+      items: computed(() => items),
+      sort: { key: 'name', direction: 'asc' },
+      enabled,
+      getValue: item => item.name,
+    })
+
+    expect(sorted.sortedItems.value.map(item => item.name)).toEqual([
+      'Lactate',
+      'Glucose',
+      'Pyruvate',
+    ])
+
+    enabled.value = true
+    expect(sorted.sortedItems.value.map(item => item.name)).toEqual([
+      'Glucose',
+      'Lactate',
+      'Pyruvate',
+    ])
+  })
+
+  it('supports case-insensitive string comparison', () => {
+    const sorted = useSortedItems({
+      items: [
+        { name: 'beta' },
+        { name: 'Alpha' },
+        { name: 'gamma' },
+      ],
+      sort: { key: 'name', direction: 'asc' },
+      caseSensitive: false,
+      getValue: item => item.name,
+    })
+
+    expect(sorted.sortedItems.value.map(item => item.name)).toEqual([
+      'Alpha',
+      'beta',
+      'gamma',
+    ])
+  })
+
+  it('compares dates, numbers, strings, and empty values consistently', () => {
+    expect(compareSortValues(1, 2, 'asc')).toBeLessThan(0)
+    expect(compareSortValues(1, 2, 'desc')).toBeGreaterThan(0)
+    expect(compareSortValues(new Date('2026-01-01'), new Date('2026-02-01'))).toBeLessThan(0)
+    expect(compareSortValues(undefined, 2, 'asc')).toBeGreaterThan(0)
+    expect(compareSortValues(undefined, 2, 'desc')).toBeGreaterThan(0)
+  })
+})

package/src/__tests__/composables/useTemplateCollection.test.ts

@@ -0,0 +1,147 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mockGet = vi.fn()
+const mockPut = vi.fn()
+const mockDelete = vi.fn()
+const mockUseApi = vi.fn((_options?: unknown) => ({
+  get: mockGet,
+  put: mockPut,
+  delete: mockDelete,
+}))
+
+vi.mock('../../composables/useApi', () => ({
+  useApi: (options: unknown) => mockUseApi(options),
+}))
+
+import { useTemplateCollection } from '../../composables/useTemplateCollection'
+import {
+  createPlateMapTemplate,
+  createSampleSheetTemplate,
+  createTemplateCollection,
+  createWellPlateScreenCollection,
+} from '../../templates'
+import type { PlateMapTemplate, SampleSheetTemplate } from '../../templates'
+
+function setup(options?: Parameters<typeof useTemplateCollection>[0]) {
+  return useTemplateCollection(options)
+}
+
+describe('useTemplateCollection', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGet.mockResolvedValue({})
+    mockPut.mockResolvedValue({})
+    mockDelete.mockResolvedValue({})
+    delete (window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__
+    window.history.replaceState({}, '', '/')
+  })
+
+  it('initializes from a template collection envelope', () => {
+    const plate = createPlateMapTemplate({ samples: ['Control', 'Treatment'] })
+    const { templateIds, templates, metadata, hasTemplates, getTemplate, requireTemplate } = setup({
+      initial: createTemplateCollection([plate], { preset: 'unit-test' }),
+    })
+
+    expect(templateIds.value).toEqual(['plate-map'])
+    expect(Object.keys(templates.value)).toEqual(['plate-map'])
+    expect(metadata.value).toEqual({ preset: 'unit-test' })
+    expect(hasTemplates.value).toBe(true)
+    expect(getTemplate<PlateMapTemplate>('plate-map')?.data.samples[1].id).toBe('treatment')
+    expect(requireTemplate<PlateMapTemplate>('plate-map').template_id).toBe('plate-map')
+  })
+
+  it('applies, sets, removes, and resets local templates', () => {
+    const plate = createPlateMapTemplate({ samples: ['Control'] })
+    const sampleSheet = createSampleSheetTemplate({
+      samples: [{ sampleId: 'S001', name: 'Sample 1' }],
+    })
+    const { apply, setTemplate, removeTemplate, reset, templateIds, metadata } = setup({
+      initial: [plate],
+    })
+
+    setTemplate(sampleSheet)
+    expect(templateIds.value).toEqual(['plate-map', 'sample-sheet'])
+
+    expect(removeTemplate('plate-map')).toBe(true)
+    expect(templateIds.value).toEqual(['sample-sheet'])
+    expect(removeTemplate('missing')).toBe(false)
+
+    apply(createTemplateCollection([sampleSheet], { source: 'loaded' }))
+    expect(metadata.value).toEqual({ source: 'loaded' })
+
+    reset()
+    expect(templateIds.value).toEqual(['plate-map'])
+  })
+
+  it('uses fallback metadata only when the payload has none', () => {
+    const plate = createPlateMapTemplate({ samples: ['Control'] })
+    const { apply, metadata } = setup()
+
+    apply(createTemplateCollection([plate], { source: 'payload' }), { source: 'fallback' })
+    expect(metadata.value).toEqual({ source: 'payload' })
+
+    apply([plate], { source: 'fallback' })
+    expect(metadata.value).toEqual({ source: 'fallback' })
+  })
+
+  it('saves the local collection through experiment design_data', async () => {
+    const collection = createWellPlateScreenCollection({
+      samples: ['Control', 'Treatment'],
+      compounds: { Drug: [10, 1] },
+    })
+    const { save, lastSavedAt } = setup({ pluginId: 'p1', initial: collection })
+
+    const ok = await save(42)
+
+    expect(ok).toBe(true)
+    expect(lastSavedAt.value).toBeInstanceOf(Date)
+    expect(mockPut).toHaveBeenCalledWith('/experiments/42/data', {
+      plugin_id: 'p1',
+      data: collection,
+      schema_version: '1.0',
+    })
+  })
+
+  it('loads design_data into the local collection', async () => {
+    const sampleSheet = createSampleSheetTemplate({
+      samples: [
+        { sampleId: 'S001', name: 'Sample 1' },
+        { sampleId: 'S002', name: 'Sample 2' },
+      ],
+    })
+    mockGet.mockResolvedValueOnce(createTemplateCollection([sampleSheet], { source: 'api' }))
+    const { load, templateIds, metadata, requireTemplate, lastLoadedAt } = setup()
+
+    const loaded = await load(7)
+
+    expect(mockGet).toHaveBeenCalledWith('/experiments/7/data')
+    expect(loaded?.metadata).toEqual({ source: 'api' })
+    expect(templateIds.value).toEqual(['sample-sheet'])
+    expect(requireTemplate<SampleSheetTemplate>('sample-sheet').data.samples[1].sampleId).toBe(
+      'S002',
+    )
+    expect(metadata.value).toEqual({ source: 'api' })
+    expect(lastLoadedAt.value).toBeInstanceOf(Date)
+  })
+
+  it('saves the current URL experiment without route plumbing', async () => {
+    window.history.replaceState({}, '', '/plugins/template?experimentId=88')
+    const plate = createPlateMapTemplate({ samples: ['Control'] })
+    const { currentExperimentId, hasCurrentExperiment, saveCurrent } = setup({
+      pluginId: 'p1',
+      initial: [plate],
+    })
+
+    expect(currentExperimentId.value).toBe(88)
+    expect(hasCurrentExperiment.value).toBe(true)
+
+    const ok = await saveCurrent()
+
+    expect(ok).toBe(true)
+    expect(mockPut).toHaveBeenCalledWith('/experiments/88/data', {
+      plugin_id: 'p1',
+      data: createTemplateCollection([plate]),
+      schema_version: '1.0',
+    })
+  })
+})

package/src/__tests__/composables/useTextSearch.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest'
+import { computed, ref } from 'vue'
+import {
+  candidateMatchesSearch,
+  normalizeSearchQuery,
+  useTextSearch,
+} from '../../composables/useTextSearch'
+
+describe('useTextSearch', () => {
+  const items = [
+    { name: 'Glucose', catalogNumber: 'G-7528', supplier: 'Sigma' },
+    { name: 'Lactate', catalogNumber: 'L-1250', supplier: 'Cayman' },
+    { name: 'Pyruvate', catalogNumber: 'P-2256', supplier: 'Thermo' },
+  ]
+
+  it('normalizes whitespace and case', () => {
+    expect(normalizeSearchQuery('  GLU  ')).toBe('glu')
+    expect(normalizeSearchQuery(undefined)).toBe('')
+  })
+
+  it('filters by multiple candidate values', () => {
+    const query = ref('cay')
+    const search = useTextSearch({
+      items,
+      query,
+      getText: item => [item.name, item.catalogNumber, item.supplier],
+    })
+
+    expect(search.filteredItems.value.map(item => item.name)).toEqual(['Lactate'])
+
+    query.value = ' p-2256 '
+    expect(search.filteredItems.value.map(item => item.name)).toEqual(['Pyruvate'])
+  })
+
+  it('returns all items when disabled', () => {
+    const enabled = ref(false)
+    const search = useTextSearch({
+      items: computed(() => items),
+      query: 'sigma',
+      enabled,
+      getText: item => item.supplier,
+    })
+
+    expect(search.filteredItems.value).toHaveLength(3)
+
+    enabled.value = true
+    expect(search.filteredItems.value.map(item => item.name)).toEqual(['Glucose'])
+  })
+
+  it('matches empty queries and ignores nullish candidates', () => {
+    expect(candidateMatchesSearch([null, undefined, 'Alpha'], '')).toBe(true)
+    expect(candidateMatchesSearch([null, undefined, 'Alpha'], 'alp')).toBe(true)
+    expect(candidateMatchesSearch([null, undefined], 'alp')).toBe(false)
+  })
+})

package/src/__tests__/composables/useTheme.test.ts

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { nextTick } from 'vue'
+import { createPinia, setActivePinia } from 'pinia'
+import { useTheme } from '../../composables/useTheme'
+import { useSettingsStore } from '../../stores/settings'
+
+function mockMatchMedia(initialMatches = false) {
+  let matches = initialMatches
+  let changeListener: ((event: MediaQueryListEvent) => void) | undefined
+
+  const mediaQuery = {
+    get matches() {
+      return matches
+    },
+    media: '(prefers-color-scheme: dark)',
+    onchange: null,
+    addEventListener: vi.fn((_event: 'change', listener: (event: MediaQueryListEvent) => void) => {
+      changeListener = listener
+    }),
+    removeEventListener: vi.fn(),
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  } as unknown as MediaQueryList
+
+  Object.defineProperty(window, 'matchMedia', {
+    configurable: true,
+    writable: true,
+    value: vi.fn(() => mediaQuery),
+  })
+
+  return {
+    mediaQuery,
+    setMatches(value: boolean) {
+      matches = value
+      changeListener?.({ matches: value } as MediaQueryListEvent)
+    },
+  }
+}
+
+describe('useTheme', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.restoreAllMocks()
+    const storage: Record<string, string> = {}
+    vi.stubGlobal('localStorage', {
+      getItem: vi.fn((key: string) => storage[key] ?? null),
+      setItem: vi.fn((key: string, value: string) => { storage[key] = value }),
+      removeItem: vi.fn((key: string) => { delete storage[key] }),
+      clear: vi.fn(() => {
+        for (const key of Object.keys(storage)) delete storage[key]
+      }),
+    })
+    document.documentElement.classList.remove('dark')
+  })
+
+  it('reads system color scheme from the settings store reactively', async () => {
+    const system = mockMatchMedia(true)
+    const settings = useSettingsStore()
+    const { isDark } = useTheme()
+
+    expect(settings.theme).toBe('system')
+    expect(settings.systemPrefersDark).toBe(true)
+    expect(isDark.value).toBe(true)
+    expect(document.documentElement.classList.contains('dark')).toBe(true)
+
+    system.setMatches(false)
+    await nextTick()
+
+    expect(settings.systemPrefersDark).toBe(false)
+    expect(isDark.value).toBe(false)
+    expect(document.documentElement.classList.contains('dark')).toBe(false)
+  })
+
+  it('keeps explicit light and dark choices independent from system changes', async () => {
+    const system = mockMatchMedia(true)
+    const { isDark, setTheme } = useTheme()
+
+    setTheme('light')
+    await nextTick()
+    expect(isDark.value).toBe(false)
+
+    system.setMatches(false)
+    await nextTick()
+    expect(isDark.value).toBe(false)
+
+    setTheme('dark')
+    await nextTick()
+    expect(isDark.value).toBe(true)
+  })
+})

package/src/__tests__/composables/useTimeUtils.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import {
+  findNearestTimeSlotIndex,
+  formatTimeSlot,
+  fromMinutes,
+  generateTimeSlots,
+  toMinutes,
+  useTimeUtils,
+} from '../../composables/useTimeUtils'
+
+describe('useTimeUtils', () => {
+  it('formats HH:MM slots for shared picker display', () => {
+    expect(formatTimeSlot('00:00')).toBe('00:00')
+    expect(formatTimeSlot('14:30', '12h')).toBe('2:30 PM')
+  })
+
+  it('converts between HH:MM strings and minute offsets', () => {
+    expect(toMinutes('09:45')).toBe(585)
+    expect(fromMinutes(585)).toBe('09:45')
+  })
+
+  it('finds the nearest slot index for scroll and highlight behavior', () => {
+    const slots = generateTimeSlots('09:00', '10:00', 15)
+
+    expect(findNearestTimeSlotIndex('09:37', slots)).toBe(2)
+    expect(findNearestTimeSlotIndex('08:00', [])).toBe(-1)
+  })
+
+  it('exposes the shared slot helpers from the composable facade', () => {
+    const utils = useTimeUtils()
+
+    expect(utils.formatTimeSlot('23:15', '12h')).toBe('11:15 PM')
+    expect(utils.findNearestTimeSlotIndex('10:20', ['10:00', '10:30'])).toBe(1)
+  })
+})

package/src/__tests__/composables/useWellPainting.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  coordinateToWellId,
+  useWellPainting,
+  wellIdToCoordinate,
+  wellIdsInRectangle,
+} from '../../composables/useWellPainting'
+
+describe('useWellPainting', () => {
+  it('converts well coordinates and computes rectangle selections', () => {
+    expect(wellIdToCoordinate('B2')).toEqual({ row: 1, col: 1 })
+    expect(coordinateToWellId({ row: 0, col: 0 })).toBe('A1')
+    expect(wellIdsInRectangle({ row: 0, col: 0 }, { row: 1, col: 1 }, 96)).toEqual([
+      'A1',
+      'A2',
+      'B1',
+      'B2',
+    ])
+  })
+
+  it('emits rectangle selections in select mode', () => {
+    const completed: string[][] = []
+    const painting = useWellPainting({
+      format: 96,
+      initialMode: 'select',
+      onComplete: result => completed.push(result.wellIds),
+    })
+
+    painting.onWellMouseDown('A1')
+    painting.onWellMouseMove('B2')
+    expect(painting.previewWellIds.value).toEqual(['A1', 'A2', 'B1', 'B2'])
+    painting.onWellMouseUp()
+
+    expect(completed).toEqual([['A1', 'A2', 'B1', 'B2']])
+  })
+
+  it('tracks paint trails for non-select modes', () => {
+    const completed: { mode: string; wells: string[] }[] = []
+    const painting = useWellPainting({
+      format: 96,
+      initialMode: 'paint',
+      onComplete: result => completed.push({ mode: result.mode, wells: result.wellIds }),
+    })
+
+    painting.onWellMouseDown('A1')
+    painting.onWellMouseMove('A3')
+    painting.onWellMouseUp()
+
+    expect(completed).toEqual([{ mode: 'paint', wells: ['A1', 'A3'] }])
+  })
+})

package/src/__tests__/composables/useWellPlateAdapter.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  createColumnConditions,
+  createRowConditions,
+  createWellPlateWells,
+} from '../../composables/useWellPlateAdapter'
+
+describe('well plate adapter helpers', () => {
+  it('maps domain entries to WellPlate wells', () => {
+    const wells = createWellPlateWells(
+      [{ id: 'B3', type: 'sample', signal: 42 }],
+      {
+        getWellId: entry => entry.id,
+        getSampleType: entry => entry.type,
+        getValue: entry => entry.signal,
+        getMetadata: () => ({ source: 'analysis' }),
+      },
+    )
+
+    expect(wells.B3).toEqual({
+      id: 'B3',
+      row: 1,
+      col: 2,
+      state: 'filled',
+      sampleType: 'sample',
+      value: 42,
+      metadata: { source: 'analysis' },
+    })
+  })
+
+  it('builds row and column condition spans from axis entries', () => {
+    const entry = {
+      label: 'Drug A',
+      color: '#123456',
+      start: 2,
+      unit: 'uM',
+      concentrations: [{ value: 1, replicates: 2 }, { value: 10 }],
+    }
+
+    expect(createColumnConditions([entry])[0]).toMatchObject({
+      cols: [2, 3, 4],
+      concentrations: [1, 1, 10],
+    })
+    expect(createRowConditions([{ ...entry, start: 'B' }])[0]).toMatchObject({
+      rows: ['B', 'C', 'D'],
+      concentrations: [1, 1, 10],
+    })
+  })
+})

package/src/__tests__/composables/useWellPlateValidation.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+
+import { runWellPlateValidation, useWellPlateValidation } from '../../composables/useWellPlateValidation'
+
+describe('well plate validation helpers', () => {
+  it('runs rule-driven validation', () => {
+    const warnings = runWellPlateValidation(
+      { assigned: 0 },
+      [
+        {
+          type: 'empty',
+          severity: 'warning',
+          validate: context => context.assigned === 0 && 'No wells assigned',
+        },
+      ],
+    )
+
+    expect(warnings).toEqual([
+      { type: 'empty', severity: 'warning', message: 'No wells assigned' },
+    ])
+  })
+
+  it('derives blocking state and counts', () => {
+    const validation = useWellPlateValidation({
+      context: { overlaps: ['A1'] },
+      rules: [
+        {
+          type: 'overlap',
+          severity: 'error',
+          validate: context => ({
+            message: `${context.overlaps.length} overlap`,
+            affectedWells: context.overlaps,
+          }),
+        },
+      ],
+    })
+
+    expect(validation.hasBlockingIssues.value).toBe(true)
+    expect(validation.errorCount.value).toBe(1)
+    expect(validation.warningCount.value).toBe(1)
+  })
+})