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

package/src/__tests__/components/WellPlate.conditions.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import type { ColumnCondition, RowCondition } from '../../types'
+import {
+  createColumnConditionMap,
+  createColumnConditionSpans,
+  createRowConditionMap,
+  createRowConditionSpanByRow,
+  createRowConditionSpans,
+} from '../../components/WellPlate.conditions'
+
+const columnCondition: ColumnCondition = {
+  label: 'Drug A',
+  color: '#10b981',
+  concentrations: [1, 10],
+  cols: [2, 3],
+  unit: 'uM',
+}
+
+const rowCondition: RowCondition = {
+  label: 'Drug B',
+  color: '#6366f1',
+  concentrations: [0.1, 1],
+  rows: ['B', 'C'],
+}
+
+describe('WellPlate condition helpers', () => {
+  it('maps column and row labels to their condition index', () => {
+    expect(createColumnConditionMap([columnCondition]).get(3)).toEqual({
+      condition: columnCondition,
+      indexInGroup: 1,
+    })
+    expect(createRowConditionMap([rowCondition]).get('C')).toEqual({
+      condition: rowCondition,
+      indexInGroup: 1,
+    })
+  })
+
+  it('creates column spans with gaps around condition groups', () => {
+    const spans = createColumnConditionSpans(
+      [1, 2, 3, 4],
+      createColumnConditionMap([columnCondition]),
+    )
+
+    expect(spans).toEqual([
+      { gap: true, colspan: 1 },
+      { condition: columnCondition, colspan: 2 },
+      { gap: true, colspan: 1 },
+    ])
+  })
+
+  it('creates row spans and indexes them by starting row', () => {
+    const spans = createRowConditionSpans(
+      ['A', 'B', 'C', 'D'],
+      createRowConditionMap([rowCondition]),
+    )
+
+    expect(spans).toEqual([
+      { gap: true, rowspan: 1, startRow: 0 },
+      { condition: rowCondition, rowspan: 2, startRow: 1 },
+      { gap: true, rowspan: 1, startRow: 3 },
+    ])
+    expect(createRowConditionSpanByRow(spans).get(1)).toEqual({
+      condition: rowCondition,
+      rowspan: 2,
+      startRow: 1,
+    })
+  })
+})

package/src/__tests__/components/WellPlate.geometry.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+import {
+  createPlateColumnLabels,
+  createPlateRowLabels,
+  createWellGrid,
+  getRectangleWellIds,
+  PLATE_CONFIGS,
+  WELL_PLATE_SIZE_CONFIGS,
+} from '../../components/WellPlate.geometry'
+
+describe('WellPlate geometry helpers', () => {
+  it('exposes supported plate dimensions and size presets', () => {
+    expect(PLATE_CONFIGS[96]).toEqual({ rows: 8, cols: 12 })
+    expect(PLATE_CONFIGS[384]).toEqual({ rows: 16, cols: 24 })
+    expect(WELL_PLATE_SIZE_CONFIGS.fill.cellWidth).toBe('100%')
+  })
+
+  it('creates row and column labels from a plate config', () => {
+    const config = PLATE_CONFIGS[24]
+
+    expect(createPlateRowLabels(config)).toEqual(['A', 'B', 'C', 'D'])
+    expect(createPlateColumnLabels(config)).toEqual([1, 2, 3, 4, 5, 6])
+  })
+
+  it('creates a well grid with partial well data merged into defaults', () => {
+    const config = PLATE_CONFIGS[6]
+    const rows = createPlateRowLabels(config)
+    const grid = createWellGrid(config, rows, {
+      A1: { state: 'filled', sampleType: 'qc', value: 42, metadata: { label: 'QC 1' } },
+    })
+
+    expect(grid[0][0]).toEqual({
+      id: 'A1',
+      row: 0,
+      col: 0,
+      state: 'filled',
+      sampleType: 'qc',
+      value: 42,
+      metadata: { label: 'QC 1' },
+    })
+    expect(grid[1][2]).toMatchObject({ id: 'B3', row: 1, col: 2, state: 'empty' })
+  })
+
+  it('creates rectangle well ids independent of drag direction', () => {
+    expect(Array.from(getRectangleWellIds({ row: 1, col: 2 }, { row: 0, col: 0 }, ['A', 'B']))).toEqual([
+      'A1',
+      'A2',
+      'A3',
+      'B1',
+      'B2',
+      'B3',
+    ])
+  })
+})

package/src/__tests__/components/WellPlate.interaction.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  nextClickedWellSelection,
+  useWellPlateInteraction,
+} from '../../components/WellPlate.interaction'
+import type { Well, WellPlateSelectionMode } from '../../types'
+
+function well(overrides: Partial<Well> = {}): Well {
+  return {
+    id: 'A1',
+    row: 0,
+    col: 0,
+    state: 'empty',
+    ...overrides,
+  }
+}
+
+function mouseEvent(overrides: Partial<MouseEvent> = {}): MouseEvent {
+  return {
+    preventDefault: vi.fn(),
+    button: 0,
+    shiftKey: false,
+    metaKey: false,
+    ctrlKey: false,
+    currentTarget: {
+      getBoundingClientRect: () => ({ right: 10, top: 20 }),
+    },
+    ...overrides,
+  } as unknown as MouseEvent
+}
+
+function dragEvent(data: Record<string, string> = {}): DragEvent {
+  return {
+    preventDefault: vi.fn(),
+    dataTransfer: {
+      effectAllowed: '',
+      dropEffect: '',
+      getData: (format: string) => data[format] ?? '',
+      setData: vi.fn(),
+    },
+  } as unknown as DragEvent
+}
+
+function createInteraction(overrides: Partial<Parameters<typeof useWellPlateInteraction>[0]> = {}) {
+  const emitted: Record<string, unknown[]> = {}
+  const selected = { value: [] as string[] }
+  const selectionMode = { value: 'multiple' as WellPlateSelectionMode }
+  const rows = ['A', 'B']
+  const grid = [
+    [well({ id: 'A1', row: 0, col: 0 }), well({ id: 'A2', row: 0, col: 1 })],
+    [well({ id: 'B1', row: 1, col: 0 }), well({ id: 'B2', row: 1, col: 1 })],
+  ]
+
+  const interaction = useWellPlateInteraction({
+    modelValue: () => selected.value,
+    selectionMode: () => selectionMode.value,
+    disabled: () => false,
+    readonly: () => false,
+    editable: () => false,
+    allowSampleDrop: () => false,
+    sampleDropParser: () => undefined,
+    rowLabels: () => rows,
+    wellGrid: () => grid,
+    emitSelected: (wellIds) => {
+      emitted.selected = [...(emitted.selected ?? []), wellIds]
+      selected.value = wellIds
+    },
+    emitWellClick: (wellId, event) => {
+      emitted.click = [...(emitted.click ?? []), [wellId, event]]
+    },
+    emitWellHover: (wellId, event) => {
+      emitted.hover = [...(emitted.hover ?? []), [wellId, event]]
+    },
+    emitContextMenu: (wellId, event) => {
+      emitted.context = [...(emitted.context ?? []), [wellId, event]]
+    },
+    emitWellMove: (sourceWellId, targetWellId) => {
+      emitted.move = [...(emitted.move ?? []), [sourceWellId, targetWellId]]
+    },
+    emitWellEdit: (wellId, data) => {
+      emitted.edit = [...(emitted.edit ?? []), [wellId, data]]
+    },
+    emitWellClear: (wellId) => {
+      emitted.clear = [...(emitted.clear ?? []), wellId]
+    },
+    emitSampleDrop: (wellId, data, event) => {
+      emitted.drop = [...(emitted.drop ?? []), [wellId, data, event]]
+    },
+    ...overrides,
+  })
+
+  return { emitted, grid, interaction, selected, selectionMode }
+}
+
+describe('WellPlate interaction helpers', () => {
+  it('calculates clicked well selection for single and multi-select modes', () => {
+    expect(nextClickedWellSelection([], 'A1', 'single', mouseEvent())).toEqual(['A1'])
+    expect(nextClickedWellSelection(['A1'], 'A1', 'single', mouseEvent())).toEqual([])
+    expect(nextClickedWellSelection(['A1'], 'A2', 'multiple', mouseEvent({ shiftKey: true }))).toEqual(['A1', 'A2'])
+    expect(nextClickedWellSelection(['A1', 'A2'], 'A1', 'multiple', mouseEvent({ ctrlKey: true }))).toEqual(['A2'])
+    expect(nextClickedWellSelection(['A1'], 'A1', 'multiple', mouseEvent())).toEqual([])
+  })
+
+  it('emits click selection changes and opens editor instead when editable', () => {
+    const { emitted, grid, interaction } = createInteraction()
+
+    interaction.handleWellClick(grid[0][0], mouseEvent())
+
+    expect(emitted.click?.[0]).toEqual(['A1', expect.anything()])
+    expect(emitted.selected?.[0]).toEqual(['A1'])
+
+    const editable = createInteraction({ editable: () => true })
+    editable.interaction.handleWellClick(grid[0][1], mouseEvent())
+
+    expect(editable.interaction.editingWellId.value).toBe('A2')
+    expect(editable.interaction.editPopupPosition.value).toEqual({ x: 18, y: 20 })
+    expect(editable.emitted.selected).toBeUndefined()
+  })
+
+  it('tracks rectangle drag selection and emits on mouseup', () => {
+    const { emitted, grid, interaction, selectionMode } = createInteraction()
+    selectionMode.value = 'rectangle'
+
+    interaction.handleWellMouseDown(grid[0][0], mouseEvent())
+    interaction.handleWellMouseEnter(grid[1][1], mouseEvent())
+
+    expect(Array.from(interaction.dragSelectedWells.value)).toEqual(['A1', 'A2', 'B1', 'B2'])
+
+    interaction.handleMouseUp()
+
+    expect(emitted.selected?.[0]).toEqual(['A1', 'A2', 'B1', 'B2'])
+    expect(interaction.isDragging.value).toBe(false)
+  })
+
+  it('moves wells in drag mode and resets drag state', () => {
+    const { emitted, grid, interaction, selectionMode } = createInteraction()
+    selectionMode.value = 'drag'
+
+    interaction.handleDragStart({ ...grid[0][0], sampleType: 'sample' }, dragEvent())
+    interaction.handleDrop(grid[1][1], dragEvent())
+
+    expect(emitted.move?.[0]).toEqual(['A1', 'B2'])
+    expect(interaction.dragSourceWell.value).toBeNull()
+    expect(interaction.dragTargetWell.value).toBeNull()
+  })
+
+  it('parses dropped samples when sample drop is enabled', () => {
+    const { emitted, grid, interaction } = createInteraction({ allowSampleDrop: () => true })
+
+    interaction.handleDrop(grid[0][0], dragEvent({ 'text/plain': 'Sample A' }))
+
+    expect(emitted.drop?.[0]).toEqual([
+      'A1',
+      { sampleName: 'Sample A', label: 'Sample A', raw: 'Sample A' },
+      expect.anything(),
+    ])
+  })
+
+  it('handles keyboard clear and select all shortcuts', () => {
+    const { emitted, interaction, selected } = createInteraction()
+    selected.value = ['A1']
+
+    interaction.handleKeyDown(new KeyboardEvent('keydown', { key: 'Escape' }))
+    interaction.handleKeyDown(new KeyboardEvent('keydown', { key: 'a', metaKey: true }))
+
+    expect(emitted.selected).toEqual([
+      [],
+      ['A1', 'A2', 'B1', 'B2'],
+    ])
+  })
+})

package/src/__tests__/components/WellPlate.legend.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_WELL_LEGEND_ITEMS } from '../../components/WellPlate.legend'
+
+describe('WellPlate legend helpers', () => {
+  it('keeps default sample legend item order stable', () => {
+    expect(DEFAULT_WELL_LEGEND_ITEMS.map(item => item.type)).toEqual([
+      'sample',
+      'blank',
+      'qc',
+      'iqc',
+    ])
+  })
+})

package/src/__tests__/components/WellPlate.rendering.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest'
+import {
+  sampleTypeIndicator,
+  wellBadge,
+  wellClasses,
+  wellLabel,
+  wellStyle,
+} from '../../components/WellPlate.rendering'
+import type { Well } from '../../types'
+
+function well(overrides: Partial<Well> = {}): Well {
+  return {
+    id: 'A1',
+    row: 0,
+    col: 0,
+    state: 'empty',
+    ...overrides,
+  }
+}
+
+describe('WellPlate rendering helpers', () => {
+  it('derives well classes from selection and drag priority', () => {
+    expect(wellClasses(well({ sampleType: 'sample' }), {
+      wellShape: 'circle',
+      selectionMode: 'drag',
+      selected: true,
+      dragOver: false,
+      hovered: false,
+      disabled: false,
+      readonly: false,
+      dragSource: false,
+      dragTarget: true,
+    })).toEqual([
+      'mint-well-plate__well',
+      'mint-well-plate__well--circle',
+      'mint-well-plate__well--draggable',
+      'mint-well-plate__well--drag-target',
+    ])
+  })
+
+  it('suppresses hover styling when readonly and includes disabled/filled states', () => {
+    expect(wellClasses(well({ state: 'filled' }), {
+      wellShape: 'rounded',
+      selectionMode: 'multiple',
+      selected: false,
+      dragOver: false,
+      hovered: true,
+      disabled: true,
+      readonly: true,
+      dragSource: false,
+      dragTarget: false,
+    })).toEqual([
+      'mint-well-plate__well',
+      'mint-well-plate__well--rounded',
+      'mint-well-plate__well--disabled',
+      'mint-well-plate__well--filled',
+    ])
+  })
+
+  it('prefers heatmap and custom sample colors before defaults', () => {
+    expect(wellStyle(well({ value: 0.5 }), {
+      heatmap: { enabled: true, colorScale: 'viridis', min: 0, max: 1 },
+      sampleColors: {},
+    })).toEqual({
+      backgroundColor: expect.any(String),
+      border: '1px solid transparent',
+    })
+
+    expect(wellStyle(well({ sampleType: 'treated' }), {
+      heatmap: { enabled: false },
+      sampleColors: { treated: '#123456' },
+    })).toEqual({
+      backgroundColor: '#12345626',
+      border: '1px solid #12345666',
+    })
+
+    expect(wellStyle(well({ sampleType: 'qc' }), {
+      heatmap: { enabled: false },
+      sampleColors: {},
+    })).toEqual({
+      backgroundColor: 'rgba(139, 92, 246, 0.15)',
+      border: '1px solid rgba(139, 92, 246, 0.4)',
+    })
+  })
+
+  it('falls back to empty or filled well styles', () => {
+    expect(wellStyle(well(), {
+      heatmap: { enabled: false },
+      sampleColors: {},
+    })).toEqual({
+      backgroundColor: 'var(--bg-tertiary)',
+      border: '1px dashed var(--border-color)',
+    })
+
+    expect(wellStyle(well({ state: 'filled' }), {
+      heatmap: { enabled: false },
+      sampleColors: {},
+    })).toEqual({
+      backgroundColor: 'var(--bg-tertiary)',
+      border: '1px solid var(--border-color)',
+    })
+  })
+
+  it('formats indicators, labels, and badges for optional overlays', () => {
+    expect(sampleTypeIndicator(well({ sampleType: 'qc' }), true)).toBe('Q')
+    expect(sampleTypeIndicator(well({ sampleType: 'treated' }), true)).toBe('T')
+    expect(sampleTypeIndicator(well({ sampleType: 'treated' }), false)).toBeNull()
+
+    expect(wellLabel(well({ metadata: { label: 'Dose A' } }), true)).toBe('Dose A')
+    expect(wellLabel(well({ metadata: { label: 'Dose A' } }), false)).toBeUndefined()
+
+    expect(wellBadge(well({ metadata: { injectionCount: 3 } }), true)).toEqual({
+      text: '3',
+      color: '#6366f1',
+    })
+    expect(wellBadge(well({ metadata: { customMethod: 'LCMS-2' } }), true)).toEqual({
+      text: '+',
+      color: '#ec4899',
+    })
+    expect(wellBadge(well({ metadata: { injectionCount: 1 } }), true)).toBeNull()
+  })
+})

package/src/__tests__/components/WellPlate.sampleDrop.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import {
+  createTextDroppedSample,
+  normalizeDroppedSample,
+  parseDroppedSampleTransfer,
+} from '../../components/WellPlate.sampleDrop'
+
+function createTransfer(data: Record<string, string>) {
+  return {
+    getData(format: string) {
+      return data[format] ?? ''
+    },
+  }
+}
+
+describe('WellPlate sample drop helpers', () => {
+  it('normalizes JSON sample payloads', () => {
+    const raw = {
+      id: 'sample-1',
+      sample_name: 'Sample 1',
+      sample_type: 'qc',
+      injection_volume: 5,
+      injection_count: 2,
+      custom_method: 'fast',
+      metadata: { batch: 'A' },
+    }
+
+    expect(normalizeDroppedSample(raw)).toEqual({
+      id: 'sample-1',
+      sampleName: 'Sample 1',
+      label: 'Sample 1',
+      sampleType: 'qc',
+      injectionVolume: 5,
+      injectionCount: 2,
+      customMethod: 'fast',
+      metadata: { batch: 'A' },
+      raw,
+    })
+  })
+
+  it('parses JSON payloads before text fallback', () => {
+    const transfer = createTransfer({
+      'application/json': JSON.stringify({ name: 'From JSON' }),
+      'text/plain': 'From Text',
+    })
+
+    expect(parseDroppedSampleTransfer(transfer)).toMatchObject({
+      sampleName: 'From JSON',
+      label: 'From JSON',
+    })
+  })
+
+  it('creates a text sample when no JSON payload exists', () => {
+    expect(createTextDroppedSample('  Sample A  ')).toEqual({
+      sampleName: 'Sample A',
+      label: 'Sample A',
+      raw: 'Sample A',
+    })
+    expect(parseDroppedSampleTransfer(createTransfer({ 'text/plain': 'Sample B' }))).toMatchObject({
+      sampleName: 'Sample B',
+      label: 'Sample B',
+    })
+  })
+
+  it('rejects invalid or empty payloads', () => {
+    expect(normalizeDroppedSample({ metadata: { batch: 'A' } })).toBeNull()
+    expect(createTextDroppedSample('   ')).toBeNull()
+    expect(parseDroppedSampleTransfer(createTransfer({ 'application/json': '{' }))).toBeNull()
+  })
+})

package/src/__tests__/composables/autoGroup/classify.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest'
+import { detectClass } from '../../../composables/autoGroup/classify'
+
+describe('detectClass', () => {
+  it('detects IQC and EQC by exact vocab match', () => {
+    const result = detectClass(
+      [
+        ['exp281', 'SAM_SAH', 'Tissues', 'IQC', '003'],
+        ['exp281', 'SAM_SAH', 'Tissues', 'IQC', '056'],
+        ['exp280', 'Experiment', 'EQC', '002'],
+      ],
+      {},
+    )
+    const iqc = result.find(c => c.kind === 'iqc')
+    const eqc = result.find(c => c.kind === 'eqc')
+    expect(iqc?.members).toEqual([0, 1])
+    expect(eqc?.members).toEqual([2])
+  })
+
+  it('detects Biological with subKind from matrix vocab', () => {
+    const result = detectClass(
+      [
+        ['exp281', 'SAM_SAH', 'Tissues', 'Kidney', 'M10', '085'],
+        ['exp281', 'SAM_SAH', 'Tissues', 'Liver', 'M10', '047'],
+        ['exp280', 'Experiment', 'Plasma', 'M10', '031'],
+      ],
+      {},
+    )
+    const tissues = result.find(c => c.kind === 'biological' && c.subKind === 'Tissues')
+    const plasma = result.find(c => c.kind === 'biological' && c.subKind === 'Plasma')
+    expect(tissues?.members).toEqual([0, 1])
+    expect(plasma?.members).toEqual([2])
+  })
+
+  it('classifies SAHStandard, SAMstandard, ExtractionS, STD1 as Standard (not Biological)', () => {
+    const result = detectClass(
+      [
+        ['exp281', 'SAM_SAH', 'SAHStandard', '5nM', '002'],
+        ['exp281', 'SAM_SAH', 'SAMstandard', '5nM', '001'],
+        ['exp281', 'SAM_SAH', 'Tissues', 'ExtractionS', '00B'],
+        ['exp', 'STD1', 'inject'],
+      ],
+      {},
+    )
+    const std = result.find(c => c.kind === 'standard')
+    expect(std?.members.sort()).toEqual([0, 1, 2, 3])
+  })
+
+  it('classifies SpikeIn and Stock', () => {
+    const result = detectClass(
+      [
+        ['exp280', 'SK', 'ESwithSpikeIn', '02'],
+        ['exp280', 'SK', 'ESwithSpikeIn', '1to100', 'Stock', '05'],
+      ],
+      {},
+    )
+    // SpikeIn matches first, so both go to spike-in (first match wins).
+    const spike = result.find(c => c.kind === 'spike-in')
+    expect(spike?.members.sort()).toEqual([0, 1])
+  })
+
+  it('classifies samples with no recognized vocab as Unknown', () => {
+    const result = detectClass([['foo', 'bar', 'baz']], {})
+    expect(result[0].kind).toBe('unknown')
+    expect(result[0].members).toEqual([0])
+  })
+
+  it('records classTagPositions for the position(s) that matched vocab', () => {
+    const result = detectClass(
+      [['exp281', 'SAM_SAH', 'Tissues', 'Kidney', 'M10', '085']],
+      {},
+    )
+    const tissues = result.find(c => c.kind === 'biological')
+    // Tissues at position 2 (class tag) and Kidney at position 3 (matrix tag).
+    expect(tissues?.classTagPositions).toContain(2)
+    expect(tissues?.classTagPositions).toContain(3)
+  })
+
+  it('honors sample_type hint short-circuit', () => {
+    const result = detectClass(
+      [['weird', 'name', 'with', 'no', 'vocab']],
+      { sampleTypeHints: ['qc'] },
+    )
+    expect(result[0].kind).toBe('iqc')
+  })
+
+  it('does not classify bare A1/M10/QC1/STD1 as Biological', () => {
+    // Names that only contain a `[A-Z]+\d+` token without matrix vocab must fall to Unknown,
+    // not Biological — prevents misclassifying calibration/QC labels.
+    const result = detectClass([['exp', 'foo', 'A1']], {})
+    expect(result[0].kind).toBe('unknown')
+  })
+
+  it('Biological requires an accompanying matrix vocab token', () => {
+    const result = detectClass([['exp', 'Plasma', 'M10']], {})
+    expect(result[0].kind).toBe('biological')
+    expect(result[0].subKind).toBe('Plasma')
+  })
+
+  it('first-match-wins between SpikeIn and Stock when both tokens appear', () => {
+    const result = detectClass(
+      [['exp', 'SK', 'ESwithSpikeIn', '1to100', 'Stock', '05']],
+      {},
+    )
+    expect(result[0].kind).toBe('spike-in')
+  })
+})