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

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

@@ -0,0 +1,93 @@
+import { effectScope, nextTick, ref } from 'vue'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useDebouncedWatch } from '../../composables/useDebouncedWatch'
+
+describe('useDebouncedWatch', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('debounces source changes and runs the latest callback value', async () => {
+    const query = ref('')
+    const calls: string[] = []
+
+    const watcher = useDebouncedWatch(query, value => {
+      calls.push(value)
+    }, { delay: 200 })
+
+    query.value = 'glu'
+    await nextTick()
+    query.value = 'glucose'
+    await nextTick()
+
+    expect(watcher.isPending.value).toBe(true)
+    vi.advanceTimersByTime(199)
+    expect(calls).toEqual([])
+
+    vi.advanceTimersByTime(1)
+    expect(calls).toEqual(['glucose'])
+    expect(watcher.isPending.value).toBe(false)
+  })
+
+  it('can cancel and flush pending callbacks without stopping the watcher', async () => {
+    const query = ref('')
+    const calls: string[] = []
+    const watcher = useDebouncedWatch(query, value => {
+      calls.push(value)
+    })
+
+    query.value = 'first'
+    await nextTick()
+    watcher.cancel()
+    vi.runAllTimers()
+    expect(calls).toEqual([])
+
+    query.value = 'second'
+    await nextTick()
+    watcher.flush()
+    expect(calls).toEqual(['second'])
+  })
+
+  it('runs callback cleanup when stopped or invalidated', async () => {
+    const query = ref('')
+    const cleanup = vi.fn()
+    const watcher = useDebouncedWatch(query, (_value, _oldValue, onCleanup) => {
+      onCleanup(cleanup)
+    }, { delay: 100 })
+
+    query.value = 'first'
+    await nextTick()
+    vi.advanceTimersByTime(100)
+
+    query.value = 'second'
+    await nextTick()
+    expect(cleanup).toHaveBeenCalledTimes(1)
+
+    vi.advanceTimersByTime(100)
+    watcher.stop()
+    expect(cleanup).toHaveBeenCalledTimes(2)
+  })
+
+  it('clears pending callbacks when the current effect scope disposes', async () => {
+    const query = ref('')
+    const calls: string[] = []
+    const scope = effectScope()
+
+    scope.run(() => {
+      useDebouncedWatch(query, value => {
+        calls.push(value)
+      })
+    })
+
+    query.value = 'pending'
+    await nextTick()
+    scope.stop()
+    vi.runAllTimers()
+
+    expect(calls).toEqual([])
+  })
+})

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

@@ -0,0 +1,95 @@
+import { mount } from '@vue/test-utils'
+import { defineComponent, nextTick } from 'vue'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  useDropdownState,
+  type UseDropdownStateOptions,
+  type UseDropdownStateReturn,
+} from '../../composables/useDropdownState'
+
+function mountHarness(options: UseDropdownStateOptions = {}) {
+  let state: UseDropdownStateReturn | undefined
+  const wrapper = mount(defineComponent({
+    setup() {
+      state = useDropdownState(options)
+      return state
+    },
+    template: '<div ref="rootRef" class="dropdown-root"><button class="inside">Inside</button></div>',
+  }), { attachTo: document.body })
+
+  if (!state) {
+    throw new Error('Dropdown harness did not initialize.')
+  }
+
+  return { wrapper, state }
+}
+
+describe('useDropdownState', () => {
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  it('opens, closes, and toggles with callbacks only on state changes', () => {
+    const onOpen = vi.fn()
+    const onClose = vi.fn()
+    const { wrapper, state } = mountHarness({ onOpen, onClose })
+
+    state.open()
+    state.open()
+    expect(state.isOpen.value).toBe(true)
+    expect(onOpen).toHaveBeenCalledTimes(1)
+
+    state.toggle()
+    state.close()
+    expect(state.isOpen.value).toBe(false)
+    expect(onClose).toHaveBeenCalledTimes(1)
+
+    state.toggle()
+    expect(state.isOpen.value).toBe(true)
+    expect(onOpen).toHaveBeenCalledTimes(2)
+
+    wrapper.unmount()
+  })
+
+  it('closes on outside click but keeps inside clicks open', async () => {
+    const { wrapper, state } = mountHarness()
+
+    state.open()
+    await nextTick()
+    await wrapper.find('.inside').trigger('click')
+    await nextTick()
+    expect(state.isOpen.value).toBe(true)
+
+    document.body.click()
+    await nextTick()
+    expect(state.isOpen.value).toBe(false)
+
+    wrapper.unmount()
+  })
+
+  it('closes on Escape by default', async () => {
+    const { wrapper, state } = mountHarness()
+
+    state.open()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }))
+    await nextTick()
+
+    expect(state.isOpen.value).toBe(false)
+    wrapper.unmount()
+  })
+
+  it('can opt out of outside-click and Escape closing', async () => {
+    const { wrapper, state } = mountHarness({
+      closeOnOutsideClick: false,
+      closeOnEscape: false,
+    })
+
+    state.open()
+    document.body.click()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }))
+    await nextTick()
+
+    expect(state.isOpen.value).toBe(true)
+    wrapper.unmount()
+  })
+})

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

@@ -0,0 +1,116 @@
+import { mount } from '@vue/test-utils'
+import { defineComponent, nextTick, ref, type Ref } from 'vue'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  useEventListener,
+  type EventListenerStop,
+} from '../../composables/useEventListener'
+
+describe('useEventListener', () => {
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  it('binds on mount and removes the listener on unmount', async () => {
+    const listener = vi.fn()
+    const wrapper = mount(defineComponent({
+      setup() {
+        useEventListener(() => document, 'click', listener)
+      },
+      template: '<div />',
+    }))
+
+    document.body.click()
+    await nextTick()
+    expect(listener).toHaveBeenCalledTimes(1)
+
+    wrapper.unmount()
+    document.body.click()
+    await nextTick()
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  it('returns a stop function for manual cleanup', async () => {
+    const listener = vi.fn()
+    let stop: EventListenerStop | undefined
+    const wrapper = mount(defineComponent({
+      setup() {
+        stop = useEventListener(() => document, 'keydown', listener)
+      },
+      template: '<div />',
+    }))
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'A' }))
+    await nextTick()
+    expect(listener).toHaveBeenCalledTimes(1)
+
+    stop?.()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'B' }))
+    await nextTick()
+    expect(listener).toHaveBeenCalledTimes(1)
+
+    wrapper.unmount()
+  })
+
+  it('moves listeners when a ref target changes', async () => {
+    const listener = vi.fn()
+    const first = document.createElement('button')
+    const second = document.createElement('button')
+    let target: Ref<HTMLElement | null> | undefined
+
+    const wrapper = mount(defineComponent({
+      setup() {
+        target = ref(first)
+        useEventListener(target, 'click', listener)
+      },
+      template: '<div />',
+    }))
+
+    first.click()
+    await nextTick()
+    expect(listener).toHaveBeenCalledTimes(1)
+
+    if (!target) throw new Error('Target ref did not initialize.')
+    target.value = second
+    await nextTick()
+
+    first.click()
+    second.click()
+    await nextTick()
+    expect(listener).toHaveBeenCalledTimes(2)
+
+    wrapper.unmount()
+    second.click()
+    await nextTick()
+    expect(listener).toHaveBeenCalledTimes(2)
+  })
+
+  it('binds and removes listeners from a reactive enabled option', async () => {
+    const enabled = ref(false)
+    const listener = vi.fn()
+    const wrapper = mount(defineComponent({
+      setup() {
+        useEventListener(() => document, 'click', listener, { enabled })
+      },
+      template: '<div />',
+    }))
+
+    document.body.click()
+    await nextTick()
+    expect(listener).not.toHaveBeenCalled()
+
+    enabled.value = true
+    await nextTick()
+    document.body.click()
+    await nextTick()
+    expect(listener).toHaveBeenCalledTimes(1)
+
+    enabled.value = false
+    await nextTick()
+    document.body.click()
+    await nextTick()
+    expect(listener).toHaveBeenCalledTimes(1)
+
+    wrapper.unmount()
+  })
+})

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

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import { nextTick, ref } from 'vue'
+import { useExpansionSet } from '../../composables/useExpansionSet'
+
+describe('useExpansionSet', () => {
+  it('tracks expanded ids without mutating defaults', () => {
+    const defaults = ['study', 'plate', 'plate']
+    const expansion = useExpansionSet({ defaultIds: defaults })
+
+    expect(expansion.expandedList.value).toEqual(['study', 'plate'])
+    expect(expansion.isExpanded('study')).toBe(true)
+    expect(expansion.toggle('study')).toBe(false)
+    expect(expansion.isExpanded('study')).toBe(false)
+    expect(expansion.toggle('sample')).toBe(true)
+    expect(expansion.expandedList.value).toEqual(['plate', 'sample'])
+
+    expansion.reset()
+    expect(expansion.expandedList.value).toEqual(['study', 'plate'])
+    expect(defaults).toEqual(['study', 'plate', 'plate'])
+  })
+
+  it('supports bulk expansion and collapse helpers', () => {
+    const expansion = useExpansionSet()
+
+    expansion.expand('study')
+    expansion.expandMany(['plate', 'sample', 'plate'])
+    expect(expansion.expandedList.value).toEqual(['study', 'plate', 'sample'])
+
+    expansion.collapse('plate')
+    expect(expansion.expandedList.value).toEqual(['study', 'sample'])
+
+    expansion.setExpanded(['treatment'])
+    expect(expansion.expandedList.value).toEqual(['treatment'])
+
+    expansion.collapseAll()
+    expect(expansion.expandedList.value).toEqual([])
+  })
+
+  it('reacts to expand-all and all-id sources', async () => {
+    const expandAll = ref(false)
+    const allIds = ref(['study', 'plate'])
+    const expansion = useExpansionSet({
+      defaultIds: ['study'],
+      allIds,
+      expandAll,
+    })
+
+    expect(expansion.expandedList.value).toEqual(['study'])
+
+    expandAll.value = true
+    await nextTick()
+    expect(expansion.expandedList.value).toEqual(['study', 'plate'])
+
+    allIds.value = ['study', 'plate', 'sample']
+    await nextTick()
+    expect(expansion.expandedList.value).toEqual(['study', 'plate', 'sample'])
+
+    expandAll.value = false
+    await nextTick()
+    expect(expansion.expandedList.value).toEqual(['study'])
+  })
+})

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

@@ -9,6 +9,7 @@
  * - table_data / tableData
  * - summary_data validation (must have a `metadata` key)
  * - load / refresh / error paths
+ * - lastLoadedAt tracks successful syncs
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -47,11 +48,13 @@ describe('useExperimentData', () => {
     const hook = useExperimentData()
 
     expect(hook.isLoading.value).toBe(false)
+    expect(hook.lastLoadedAt.value).toBeNull()
     const p = hook.fetch(42)
     expect(hook.isLoading.value).toBe(true)
     await p
     expect(hook.isLoading.value).toBe(false)
     expect(hook.data.value).toEqual({ tree_data: [{ id: 'a', label: 'A' }] })
+    expect(hook.lastLoadedAt.value).toBeInstanceOf(Date)
     expect(recordedUrls[0]).toBe('/experiments/42/data')
   })
 
@@ -113,6 +116,7 @@ describe('useExperimentData', () => {
     expect(hook.error.value).toBe('boom')
     expect(hook.data.value).toBeNull()
     expect(hook.isLoading.value).toBe(false)
+    expect(hook.lastLoadedAt.value).toBeNull()
   })
 
   it('apiBaseUrl option is honoured', async () => {

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

@@ -7,13 +7,14 @@ import { describe, it, expect, vi, beforeEach } 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: () => ({
-    get: mockGet,
-    put: mockPut,
-    delete: mockDelete,
-  }),
+  useApi: (options: unknown) => mockUseApi(options),
 }))
 
 import { useExperimentSave } from '../../composables/useExperimentSave'
@@ -36,6 +37,8 @@ describe('useExperimentSave', () => {
     mockGet.mockResolvedValue({})
     mockPut.mockResolvedValue({})
     mockDelete.mockResolvedValue({})
+    delete (window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__
+    window.history.replaceState({}, '', '/')
   })
 
   // -------------------------------------------------------------------------
@@ -137,6 +140,179 @@ describe('useExperimentSave', () => {
       const ok = await saveDesign(1, { x: 1 })
       expect(ok).toBe(false)
     })
+
+    it('should default pluginId and apiBaseUrl from injected platform context', async () => {
+      ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+        isIntegrated: true,
+        theme: 'light',
+        platformApiUrl: '/api',
+        plugin: {
+          id: 'platform-plugin',
+          name: 'Platform Plugin',
+          version: '1.0.0',
+          route_prefix: '/platform-plugin',
+          api_prefix: '/api/platform-plugin',
+        },
+      }
+
+      const { saveDesign } = setup()
+      await saveDesign(1, { x: 1 })
+
+      expect(mockUseApi).toHaveBeenCalledWith({ baseUrl: '/api' })
+      expect(mockPut).toHaveBeenCalledWith('/experiments/1/data', {
+        plugin_id: 'platform-plugin',
+        data: { x: 1 },
+        schema_version: '1.0',
+      })
+    })
+  })
+
+  // -------------------------------------------------------------------------
+  // saveTemplatePreset
+  // -------------------------------------------------------------------------
+
+  describe('saveTemplatePreset', () => {
+    it('should create a preset collection and save it as design data', async () => {
+      const { saveTemplatePreset } = setup({ pluginId: 'p1' })
+
+      const ok = await saveTemplatePreset(42, 'wellplate', {
+        samples: ['Control', 'Treatment'],
+        compounds: { 'Drug A': [10, 1] },
+      })
+
+      expect(ok).toBe(true)
+      expect(mockPut).toHaveBeenCalledOnce()
+      const body = mockPut.mock.calls[0][1]
+      expect(mockPut.mock.calls[0][0]).toBe('/experiments/42/data')
+      expect(body.plugin_id).toBe('p1')
+      expect(body.data.metadata.preset).toBe('wellplate-screen')
+      expect(Object.keys(body.data.templates)).toEqual(['plate-map', 'sample-sheet', 'dose-response'])
+      expect(body.data.templates['plate-map'].data.samples[1].id).toBe('treatment')
+    })
+
+    it('should resolve preset aliases', async () => {
+      const { saveTemplatePreset } = setup({ pluginId: 'p1' })
+
+      await saveTemplatePreset(42, 'gene expression', {
+        samples: ['Control'],
+        targets: ['ACTB'],
+      })
+
+      const body = mockPut.mock.calls[0][1]
+      expect(body.data.metadata.preset).toBe('qpcr-expression')
+      expect(Object.keys(body.data.templates)).toEqual(['sample-sheet', 'qpcr-plate'])
+    })
+
+    it('should return false when pluginId is missing', async () => {
+      const { saveTemplatePreset, error } = setup()
+
+      const ok = await saveTemplatePreset(42, 'lcms', { samples: ['S001'] })
+
+      expect(ok).toBe(false)
+      expect(error.value).toBe('pluginId is required for saveDesign')
+      expect(mockPut).not.toHaveBeenCalled()
+    })
+  })
+
+  // -------------------------------------------------------------------------
+  // current experiment shortcuts
+  // -------------------------------------------------------------------------
+
+  describe('current experiment shortcuts', () => {
+    it('should expose current experiment id from platform injection', async () => {
+      ;(window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__ = {
+        isIntegrated: true,
+        theme: 'light',
+        plugin: {
+          id: 'p1',
+          name: 'Plugin',
+          version: '1.0.0',
+          route_prefix: '/plugin',
+          api_prefix: '/api/plugin',
+        },
+        currentExperiment: { id: 77 },
+      }
+
+      const { currentExperimentId, hasCurrentExperiment, requireCurrentExperimentId } = setup()
+
+      expect(currentExperimentId.value).toBe(77)
+      expect(hasCurrentExperiment.value).toBe(true)
+      expect(requireCurrentExperimentId()).toBe(77)
+    })
+
+    it('should expose current experiment id from URL query and path', () => {
+      window.history.replaceState({}, '', '/analysis?experimentId=42')
+      expect(setup().currentExperimentId.value).toBe(42)
+
+      window.history.replaceState({}, '', '/experiments/43/analysis')
+      expect(setup().currentExperimentId.value).toBe(43)
+    })
+
+    it('should save design for the current experiment', async () => {
+      window.history.replaceState({}, '', '/analysis?experimentId=42')
+      const { saveCurrentDesign } = setup({ pluginId: 'p1' })
+
+      const ok = await saveCurrentDesign({ layout: 'grid' })
+
+      expect(ok).toBe(true)
+      expect(mockPut).toHaveBeenCalledWith('/experiments/42/data', {
+        plugin_id: 'p1',
+        data: { layout: 'grid' },
+        schema_version: '1.0',
+      })
+    })
+
+    it('should save a template preset for the current experiment', async () => {
+      window.history.replaceState({}, '', '/experiments/42/template')
+      const { saveCurrentTemplatePreset } = setup({ pluginId: 'p1' })
+
+      const ok = await saveCurrentTemplatePreset('wellplate', {
+        samples: ['Control', 'Treatment'],
+        compounds: { 'Drug A': [10, 1] },
+      })
+
+      expect(ok).toBe(true)
+      expect(mockPut.mock.calls[0][0]).toBe('/experiments/42/data')
+      expect(mockPut.mock.calls[0][1].data.metadata.preset).toBe('wellplate-screen')
+    })
+
+    it('should save analysis for the current experiment', async () => {
+      window.history.replaceState({}, '', '/analysis?experiment_id=44')
+      const { saveCurrentAnalysis } = setup({ pluginId: 'p1' })
+
+      const ok = await saveCurrentAnalysis({ score: 0.95 })
+
+      expect(ok).toBe(true)
+      expect(mockPut).toHaveBeenCalledWith('/experiments/44/results/p1', {
+        result: { score: 0.95 },
+      })
+    })
+
+    it('should load and delete current experiment data', async () => {
+      window.history.replaceState({}, '', '/experiments/45/template')
+      mockGet.mockResolvedValueOnce({ design: { plate: 'A' } })
+      const {
+        loadCurrentDesign,
+        deleteCurrentAnalysis,
+      } = setup({ pluginId: 'p1' })
+
+      await expect(loadCurrentDesign()).resolves.toEqual({ design: { plate: 'A' } })
+      await expect(deleteCurrentAnalysis()).resolves.toBe(true)
+
+      expect(mockGet).toHaveBeenCalledWith('/experiments/45/data')
+      expect(mockDelete).toHaveBeenCalledWith('/experiments/45/results/p1')
+    })
+
+    it('should return false when current experiment is missing', async () => {
+      const { saveCurrentTemplatePreset, error, requireCurrentExperimentId } = setup({ pluginId: 'p1' })
+
+      expect(() => requireCurrentExperimentId()).toThrow('[MINT SDK] No current experiment is selected.')
+      const ok = await saveCurrentTemplatePreset('lcms', { samples: ['S001'] })
+
+      expect(ok).toBe(false)
+      expect(error.value).toBe('No current experiment is selected for saveTemplatePreset')
+      expect(mockPut).not.toHaveBeenCalled()
+    })
   })
 
   // -------------------------------------------------------------------------
@@ -251,10 +427,27 @@ describe('useExperimentSave', () => {
 
     it('should return null on error', async () => {
       mockGet.mockRejectedValueOnce(new Error('not found'))
-      const { loadDesign } = setup()
+      const { loadDesign, error } = setup()
 
       const result = await loadDesign(999)
       expect(result).toBeNull()
+      expect(error.value).toBe('not found')
+    })
+
+    it('should set isLoading and lastLoadedAt during the call', async () => {
+      let resolveGet!: (v: unknown) => void
+      mockGet.mockImplementationOnce(() => new Promise((r) => { resolveGet = r }))
+
+      const { loadDesign, isLoading, lastLoadedAt } = setup()
+      expect(isLoading.value).toBe(false)
+
+      const promise = loadDesign(42)
+      expect(isLoading.value).toBe(true)
+
+      resolveGet({ data: { key: 'value' } })
+      await promise
+      expect(isLoading.value).toBe(false)
+      expect(lastLoadedAt.value).toBeInstanceOf(Date)
     })
   })
 
@@ -290,9 +483,10 @@ describe('useExperimentSave', () => {
     })
 
     it('should return null when pluginId not set', async () => {
-      const { loadAnalysis } = setup()
+      const { loadAnalysis, error } = setup()
       const result = await loadAnalysis(1)
       expect(result).toBeNull()
+      expect(error.value).toBe('pluginId is required for loadAnalysis')
     })
   })
 
@@ -339,9 +533,10 @@ describe('useExperimentSave', () => {
     })
 
     it('should return false when pluginId not set', async () => {
-      const { deleteAnalysis } = setup()
+      const { deleteAnalysis, error } = setup()
       const ok = await deleteAnalysis(1)
       expect(ok).toBe(false)
+      expect(error.value).toBe('pluginId is required for deleteAnalysis')
     })
   })
 })