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

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

@@ -0,0 +1,47 @@
+import { mount } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import ThemeToggle from '../../components/ThemeToggle.vue'
+
+describe('ThemeToggle', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.restoreAllMocks()
+    vi.stubGlobal('localStorage', {
+      getItem: vi.fn(() => null),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+      clear: vi.fn(),
+    })
+    Object.defineProperty(window, 'matchMedia', {
+      configurable: true,
+      writable: true,
+      value: vi.fn(() => ({
+        matches: false,
+        media: '(prefers-color-scheme: dark)',
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      })),
+    })
+  })
+
+  it('renders through IconButton while preserving the public theme-toggle class', async () => {
+    const wrapper = mount(ThemeToggle, {
+      props: { size: 'sm' },
+    })
+
+    const button = wrapper.find('button')
+    expect(button.classes()).toContain('mint-theme-toggle')
+    expect(button.classes()).toContain('mint-icon-button')
+    expect(button.classes()).toContain('mint-icon-button--sm')
+    expect(button.attributes('aria-label')).toBe('Switch to dark mode')
+
+    await button.trigger('click')
+
+    expect(button.attributes('aria-label')).toBe('Switch to light mode')
+  })
+})

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

@@ -0,0 +1,38 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import TimePicker from '../../components/TimePicker.vue'
+
+describe('TimePicker', () => {
+  it('opens from keyboard disclosure shortcuts', async () => {
+    const wrapper = mount(TimePicker)
+
+    await wrapper.get('.mint-time-picker').trigger('keydown', { key: 'ArrowDown' })
+
+    expect(wrapper.find('.mint-time-picker__dropdown').exists()).toBe(true)
+  })
+
+  it('uses shared dropdown state for Escape and outside-click close behavior', async () => {
+    const wrapper = mount(TimePicker, {
+      props: {
+        modelValue: '14:30',
+      },
+      attachTo: document.body,
+    })
+
+    await wrapper.get('input').trigger('click')
+    expect(wrapper.find('.mint-time-picker__dropdown').exists()).toBe(true)
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }))
+    await wrapper.vm.$nextTick()
+    expect(wrapper.find('.mint-time-picker__dropdown').exists()).toBe(false)
+
+    await wrapper.get('input').trigger('click')
+    expect(wrapper.find('.mint-time-picker__dropdown').exists()).toBe(true)
+
+    document.body.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    await wrapper.vm.$nextTick()
+    expect(wrapper.find('.mint-time-picker__dropdown').exists()).toBe(false)
+
+    wrapper.unmount()
+  })
+})

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

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import {
+  conditionGradientStyle,
+  formatConcentration,
+  getHeatmapColor,
+  HEATMAP_COLORS,
+} from '../../components/WellPlate.colors'
+
+describe('WellPlate color helpers', () => {
+  it('formats concentrations for compact condition headers', () => {
+    expect(formatConcentration(1000)).toBe('1k')
+    expect(formatConcentration(0.001)).toBe('1e-3')
+    expect(formatConcentration(12.5)).toBe('12.5')
+  })
+
+  it('creates readable condition gradient styles', () => {
+    expect(conditionGradientStyle('#000000', 10, [0, 10])).toEqual({
+      backgroundColor: 'rgba(0, 0, 0, 0.75)',
+      color: '#ffffff',
+    })
+  })
+
+  it('resolves configured heatmap palette colors', () => {
+    expect(getHeatmapColor({ enabled: false }, 1)).toBeNull()
+    expect(getHeatmapColor({ enabled: true, min: 0, max: 100 }, 0)).toBe(HEATMAP_COLORS.viridis[0])
+    expect(getHeatmapColor({ enabled: true, colorScale: 'custom', customColors: ['#111', '#222'] }, 1)).toBe('#222')
+  })
+})

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/analysisArtifactTarget.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import {
+  buildAnalysisArtifactTargetQuery,
+  parseAnalysisArtifactTarget,
+} from '../../composables/analysisArtifactTarget'
+import {
+  currentExperimentIdFromUrl,
+  resolveCurrentPluginId,
+} from '../../composables/platformContextHelpers'
+
+describe('analysis artifact target', () => {
+  afterEach(() => {
+    delete (window as unknown as { __MINT_PLATFORM__?: unknown }).__MINT_PLATFORM__
+    vi.unstubAllGlobals()
+  })
+
+  it('should resolve the canonical injected plugin id', () => {
+    ;(window as unknown as { __MINT_PLATFORM__: unknown }).__MINT_PLATFORM__ = {
+      isIntegrated: true,
+      plugin: { id: 'LEAF', name: 'Leaf UI' },
+      theme: 'system',
+    }
+
+    expect(resolveCurrentPluginId()).toBe('LEAF')
+  })
+
+  it('should tolerate a host that provides a partial location object', () => {
+    vi.stubGlobal('window', {
+      location: { search: '' },
+    })
+
+    expect(currentExperimentIdFromUrl()).toBeUndefined()
+  })
+
+  it('should build the canonical readable query when an artifact id hint is present', () => {
+    const query = buildAnalysisArtifactTargetQuery({
+      experimentId: 66,
+      artifactPluginId: 'LEAF',
+      artifactKey: 'exp316_260703_ys_rna_ide_scr',
+      artifactId: 206,
+    })
+
+    expect(query.toString()).toBe(
+      'experiment_id=66&artifact_plugin_id=LEAF'
+      + '&artifact_key=exp316_260703_ys_rna_ide_scr&artifact_id=206',
+    )
+  })
+
+  it('should parse the canonical identity without requiring an artifact id hint', () => {
+    const target = parseAnalysisArtifactTarget(new URLSearchParams(
+      'experiment_id=66&artifact_plugin_id=LEAF&artifact_key=result',
+    ))
+
+    expect(target).toEqual({
+      experimentId: 66,
+      artifactPluginId: 'LEAF',
+      artifactKey: 'result',
+    })
+  })
+
+  it('should reject an incomplete target instead of guessing another artifact', () => {
+    const target = parseAnalysisArtifactTarget(new URLSearchParams(
+      'experiment_id=66&artifact_key=result',
+    ))
+
+    expect(target).toBeNull()
+  })
+
+  it('should reject non-positive numeric identifiers', () => {
+    const target = parseAnalysisArtifactTarget(new URLSearchParams(
+      'experiment_id=0&artifact_plugin_id=LEAF&artifact_key=result&artifact_id=-1',
+    ))
+
+    expect(target).toBeNull()
+  })
+})