@morscherlab/mint-sdk 1.0.44 → 1.0.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morscherlab/mint-sdk",
-  "version": "1.0.44",
+  "version": "1.0.46",
   "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/AutoGroupModal.adapter.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from 'vitest'
+import {
+  candidateColumnIndices,
+  engineFieldsToCards,
+  engineGroupsToRail,
+  engineToQcRoute,
+  manualSamplesToResult,
+  qcRouteToEngine,
+  roleLabel,
+  seedFromGroups,
+} from '../../components/AutoGroupModal.adapter'
+import type { ColumnInfo } from '../../types/auto-group'
+import type { SampleGroup } from '../../types'
+import type { ManualSample } from '../../components/SmartGroupManual.cohorts'
+
+function col(partial: Partial<ColumnInfo> & { index: number }): ColumnInfo {
+  return {
+    name: `c${partial.index}`,
+    sourceIndices: [partial.index],
+    uniqueValues: [],
+    cardinality: 0,
+    ...partial,
+  }
+}
+
+describe('roleLabel', () => {
+  it('should map known roles to their display label', () => {
+    expect(roleLabel('factor')).toBe('Factor')
+    expect(roleLabel('replicate')).toBe('Replicate')
+    expect(roleLabel('run-order')).toBe('Run')
+  })
+
+  it('should default to Factor when the role is undefined', () => {
+    expect(roleLabel(undefined)).toBe('Factor')
+  })
+})
+
+describe('candidateColumnIndices', () => {
+  it('should include factors and replicates and drop constants/ignore', () => {
+    const columns = [
+      col({ index: 0, role: 'factor' }),
+      col({ index: 1, role: 'constant' }),
+      col({ index: 2, role: 'replicate' }),
+      col({ index: 3, role: 'ignore' }),
+    ]
+    expect(candidateColumnIndices(columns, new Set())).toEqual([0, 2])
+  })
+
+  it('should also include a non-factor column already enabled in groupBy', () => {
+    const columns = [
+      col({ index: 0, role: 'factor' }),
+      col({ index: 1, role: 'numeric' }),
+    ]
+    expect(candidateColumnIndices(columns, new Set([1]))).toEqual([0, 1])
+  })
+})
+
+describe('engineFieldsToCards', () => {
+  it('should build cards with role label, joined values, rep flag, and aligned enabled state', () => {
+    const columns = [
+      col({ index: 0, name: 'Condition', role: 'factor', uniqueValues: ['Control', 'Treatment'] }),
+      col({ index: 1, name: 'Replicate', role: 'replicate', uniqueValues: ['Rep1', 'Rep2'] }),
+    ]
+    const { fields, enabled } = engineFieldsToCards(columns, new Set([0]))
+    expect(fields).toEqual([
+      { key: 'Condition', role: 'Factor', vals: 'Control, Treatment', rep: false },
+      { key: 'Replicate', role: 'Replicate', vals: 'Rep1, Rep2', rep: true },
+    ])
+    expect(enabled).toEqual([true, false])
+  })
+
+  it('should prefer displayName over name when present', () => {
+    const columns = [col({ index: 0, name: 'c0', displayName: 'Dose', role: 'factor', uniqueValues: ['Low'] })]
+    expect(engineFieldsToCards(columns, new Set()).fields[0].key).toBe('Dose')
+  })
+})
+
+describe('engineGroupsToRail', () => {
+  it('should map groups to {name, count, color} using sample length', () => {
+    const groups: SampleGroup[] = [{ name: 'Control', color: '#111', samples: ['a', 'b'] }]
+    expect(engineGroupsToRail(groups)).toEqual([{ name: 'Control', count: 2, color: '#111' }])
+  })
+})
+
+describe('QC route mapping', () => {
+  it('should round-trip between Field Recipe labels and engine routing', () => {
+    expect(qcRouteToEngine('Overlay only')).toBe('overlay')
+    expect(qcRouteToEngine('Exclude')).toBe('exclude')
+    expect(qcRouteToEngine('Mix into groups')).toBe('mix')
+    expect(engineToQcRoute('overlay')).toBe('Overlay only')
+    expect(engineToQcRoute('exclude')).toBe('Exclude')
+    expect(engineToQcRoute('mix')).toBe('Mix into groups')
+  })
+})
+
+describe('seedFromGroups', () => {
+  it('should split a hierarchical group name into group/sub/sub2 per sample', () => {
+    const groups: SampleGroup[] = [
+      { name: 'Responder/Day 7/Batch 1', color: '#0EA5A4', samples: ['s1'] },
+      { name: 'Control', color: '#3B82F6', samples: ['s2', 's3'] },
+    ]
+    expect(seedFromGroups(groups)).toEqual({
+      s1: { group: 'Responder', sub: 'Day 7', sub2: 'Batch 1', color: '#0EA5A4' },
+      s2: { group: 'Control', sub: undefined, sub2: undefined, color: '#3B82F6' },
+      s3: { group: 'Control', sub: undefined, sub2: undefined, color: '#3B82F6' },
+    })
+  })
+})
+
+describe('manualSamplesToResult', () => {
+  function sample(name: string, group: string | null, sub: string | null = null, color = 'var(--grp-1)'): ManualSample {
+    return { name, group, sub, sub2: null, color: group ? color : null }
+  }
+
+  it('should build a hierarchical group name and wrap as an AutoGroupResult', () => {
+    const samples: ManualSample[] = [
+      { name: 'S1', group: 'Treatment', sub: 'Baseline', sub2: null, color: 'var(--grp-1)' },
+      sample('S2', null),
+    ]
+    const result = manualSamplesToResult(samples)
+    expect(result.groups).toHaveLength(1)
+    expect(result.groups[0]).toMatchObject({ name: 'Treatment/Baseline', samples: ['S1'] })
+    expect(result.experimentalGroups).toEqual(result.groups)
+    expect(result.qcGroups).toEqual([])
+  })
+
+  it('should round-trip a 4-segment group name through seedFromGroups without losing segments', () => {
+    const groups: SampleGroup[] = [{ name: 'a/b/c/d', color: '#123456', samples: ['s1'] }]
+    const seeded = seedFromGroups(groups).s1
+    const samples: ManualSample[] = [
+      {
+        name: 's1',
+        group: seeded.group ?? null,
+        sub: seeded.sub ?? null,
+        sub2: seeded.sub2 ?? null,
+        color: seeded.color ?? null,
+      },
+    ]
+    // No baseGroups, so the name is reconstructed purely from the seeded levels.
+    const result = manualSamplesToResult(samples, [])
+    expect(result.groups).toHaveLength(1)
+    expect(result.groups[0]).toMatchObject({ name: 'a/b/c/d', samples: ['s1'] })
+  })
+
+  it('should preserve base group order and colour, leaving emptied groups in place', () => {
+    const samples: ManualSample[] = [sample('S1', 'Treatment'), sample('S2', null)]
+    const base: SampleGroup[] = [
+      { name: 'Control', color: '#3B82F6', samples: ['S1'] },
+      { name: 'Treatment', color: '#10B981', samples: [] },
+    ]
+    expect(manualSamplesToResult(samples, base).groups).toEqual([
+      { name: 'Control', color: '#3B82F6', samples: [] },
+      { name: 'Treatment', color: '#10B981', samples: ['S1'] },
+    ])
+  })
+
+  it('should keep a base group colour when samples are added to it', () => {
+    const samples: ManualSample[] = [sample('S1', 'Control', null, '#10B981'), sample('S2', 'Control', null, '#10B981')]
+    const base: SampleGroup[] = [{ name: 'Control', color: '#10B981', samples: ['S1'] }]
+    expect(manualSamplesToResult(samples, base).groups).toEqual([
+      { name: 'Control', color: '#10B981', samples: ['S1', 'S2'] },
+    ])
+  })
+})

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

@@ -812,4 +812,104 @@ describe('DataFrame', () => {
       expect(wrapper.emitted('row-click')).toBeUndefined()
     })
   })
+
+  describe('row deletion', () => {
+    it('should not show an actions column by default', () => {
+      const wrapper = mount(DataFrame, {
+        props: { data: mockData, columns: mockColumns },
+      })
+      expect(wrapper.find('.mint-dataframe__td--actions').exists()).toBe(false)
+    })
+
+    it('should show a delete button per row when deletable', () => {
+      const wrapper = mount(DataFrame, {
+        props: { data: mockData, columns: mockColumns, deletable: true },
+      })
+      expect(wrapper.find('.mint-dataframe__th--actions').exists()).toBe(true)
+      expect(wrapper.findAll('.mint-dataframe__delete-btn')).toHaveLength(mockData.length)
+    })
+
+    it('should emit delete-row with the row and index', async () => {
+      const wrapper = mount(DataFrame, {
+        props: { data: mockData, columns: mockColumns, deletable: true },
+      })
+      await wrapper.findAll('.mint-dataframe__delete-btn')[1].trigger('click')
+
+      expect(wrapper.emitted('delete-row')).toHaveLength(1)
+      const [row, index] = wrapper.emitted('delete-row')?.[0] as [Record<string, unknown>, number]
+      expect(row.name).toBe('Bob')
+      expect(index).toBe(1)
+    })
+
+    it('should not emit row-click when the delete button is clicked', async () => {
+      const wrapper = mount(DataFrame, {
+        props: { data: mockData, columns: mockColumns, deletable: true },
+      })
+      await wrapper.find('.mint-dataframe__delete-btn').trigger('click')
+      expect(wrapper.emitted('row-click')).toBeUndefined()
+    })
+
+    it('should use a custom delete label', () => {
+      const wrapper = mount(DataFrame, {
+        props: { data: mockData, columns: mockColumns, deletable: true, deleteLabel: 'Remove' },
+      })
+      expect(wrapper.find('.mint-dataframe__delete-btn').attributes('aria-label')).toBe('Remove')
+    })
+  })
+
+  describe('column resizing', () => {
+    it('should not show resize handles by default', () => {
+      const wrapper = mount(DataFrame, {
+        props: { data: mockData, columns: mockColumns },
+      })
+      expect(wrapper.find('.mint-dataframe__resize-handle').exists()).toBe(false)
+    })
+
+    it('should show a resize handle per column when resizable', () => {
+      const wrapper = mount(DataFrame, {
+        props: { data: mockData, columns: mockColumns, resizable: true },
+      })
+      expect(wrapper.findAll('.mint-dataframe__resize-handle')).toHaveLength(mockColumns.length)
+    })
+
+    it('should emit update:columnWidths while dragging a handle', async () => {
+      const wrapper = mount(DataFrame, {
+        props: { data: mockData, columns: mockColumns, resizable: true },
+      })
+      const handle = wrapper.findAll('.mint-dataframe__resize-handle')[0]
+      await handle.trigger('mousedown', { clientX: 100 })
+      window.dispatchEvent(new MouseEvent('mousemove', { clientX: 220 }))
+      window.dispatchEvent(new MouseEvent('mouseup'))
+
+      const events = wrapper.emitted('update:columnWidths')
+      expect(events).toBeTruthy()
+      const widths = events?.[events.length - 1]?.[0] as Record<string, number>
+      expect(widths.name).toBeGreaterThanOrEqual(48) // MIN_COL_WIDTH floor
+    })
+
+    it('should honor controlled columnWidths', () => {
+      const wrapper = mount(DataFrame, {
+        props: {
+          data: mockData,
+          columns: mockColumns,
+          resizable: true,
+          columnWidths: { name: 321 },
+        },
+      })
+      const header = wrapper.find('.mint-dataframe__th')
+      expect(header.attributes('style')).toContain('width: 321px')
+    })
+
+    it('should not trigger sort when the resize handle is clicked', async () => {
+      const wrapper = mount(DataFrame, {
+        props: {
+          data: mockData,
+          columns: [{ key: 'name', label: 'Name', sortable: true }],
+          resizable: true,
+        },
+      })
+      await wrapper.find('.mint-dataframe__resize-handle').trigger('click')
+      expect(wrapper.emitted('update:sort')).toBeUndefined()
+    })
+  })
 })

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

@@ -1,10 +1,20 @@
-import { mount } from '@vue/test-utils'
+import { flushPromises, mount } from '@vue/test-utils'
 import { createPinia } from 'pinia'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import AutoGroupModal from '../../components/AutoGroupModal.vue'
 import SampleSelector from '../../components/SampleSelector.vue'
+import SmartGroupFieldRecipe from '../../components/SmartGroupFieldRecipe.vue'
 import type { AutoGroupResult, SampleGroup } from '../../types'
 
+// Wait for the FileReader-backed CSV read (a macrotask, not a microtask) plus
+// the ensuing reactive renders to settle.
+async function settle() {
+  for (let i = 0; i < 3; i++) {
+    await new Promise(resolve => setTimeout(resolve, 0))
+    await flushPromises()
+  }
+}
+
 describe('SampleSelector', () => {
   it('uses shared list selection for select-all and individual sample toggles', async () => {
     const wrapper = mount(SampleSelector, {
@@ -89,6 +99,30 @@ describe('SampleSelector', () => {
     expect(wrapper.findAll('.mint-sample-selector__flat-name').map(item => item.text())).toEqual(['S1', 'S2'])
   })
 
+  it('merges smart and manual grouping into one launcher', async () => {
+    const wrapper = mount(SampleSelector, {
+      props: {
+        samples: ['S1', 'S2'],
+        modelValue: [],
+        groups: [],
+      },
+      global: {
+        stubs: {
+          AutoGroupModal: true,
+        },
+      },
+    })
+
+    const labels = wrapper.findAll('.mint-sample-selector__actions-row .mint-sample-selector__action-label')
+    expect(labels.map(label => label.text())).toEqual(['Grouping'])
+    expect(wrapper.findAll('.mint-sample-selector__actions-row > .mint-sample-selector__action-btn')).toHaveLength(2)
+
+    await wrapper.findAllComponents({ name: 'BaseButton' })[0].trigger('click')
+
+    const modal = wrapper.findComponent({ name: 'AutoGroupModal' })
+    expect(modal.props('initialMode')).toBe('auto')
+  })
+
   it('opens the grouping modal in manual mode', async () => {
     const wrapper = mount(SampleSelector, {
       props: {
@@ -104,6 +138,9 @@ describe('SampleSelector', () => {
       },
     })
 
+    const labels = wrapper.findAll('.mint-sample-selector__actions-row .mint-sample-selector__action-label')
+    expect(labels.map(label => label.text())).toEqual(['Grouping'])
+
     await wrapper.findAllComponents({ name: 'BaseButton' })[0].trigger('click')
 
     const modal = wrapper.findComponent({ name: 'AutoGroupModal' })
@@ -129,18 +166,22 @@ describe('AutoGroupModal manual workflow', () => {
       },
     })
 
-    await wrapper.findAll('.mint-auto-group__manual-sample input')[0].trigger('change')
-    const fields = wrapper.findAll('.mint-auto-group__manual-field input')
+    await wrapper.findAll('.mg2-row')[0].trigger('click')
+    const fields = wrapper.findAll('.mg2-bar .mg2-combo input')
     await fields[0].setValue('Treatment')
     await fields[1].setValue('Baseline')
-    await wrapper.find('.mint-auto-group__manual-assign').trigger('click')
-    await wrapper.find('.mint-auto-group__nav--manual .mint-button--primary').trigger('click')
+    await wrapper.find('.mg2-bar .sg-btn--primary').trigger('click')
+    await wrapper.find('.sg-foot .mint-button--primary').trigger('click')
 
     const result = wrapper.emitted('apply')?.at(-1)?.[0] as AutoGroupResult
     expect(result.groups).toHaveLength(1)
     expect(result.groups[0]).toMatchObject({
       name: 'Treatment/Baseline',
       samples: ['S1'],
+      // A newly-created manual cohort must carry a concrete hex colour (the
+      // first SAMPLE_GROUP_COLOR_OPTIONS swatch), not a `var(--grp-*)` string
+      // that breaks SampleSelector's hex8 tint concatenation.
+      color: '#3B82F6',
     })
   })
 
@@ -163,11 +204,10 @@ describe('AutoGroupModal manual workflow', () => {
       },
     })
 
-    await wrapper.find('.mint-auto-group__manual-filter input').setValue(false)
-    await wrapper.findAll('.mint-auto-group__manual-sample input')[0].trigger('change')
-    await wrapper.findAll('.mint-auto-group__manual-chip')[1].trigger('click')
-    await wrapper.find('.mint-auto-group__manual-assign').trigger('click')
-    await wrapper.find('.mint-auto-group__nav--manual .mint-button--primary').trigger('click')
+    await wrapper.findAll('.mg2-row')[0].trigger('click')
+    await wrapper.findAll('.mg2-bar .mg2-combo input')[0].setValue('Treatment')
+    await wrapper.find('.mg2-bar .sg-btn--primary').trigger('click')
+    await wrapper.find('.sg-foot .mint-button--primary').trigger('click')
 
     const result = wrapper.emitted('apply')?.at(-1)?.[0] as AutoGroupResult
     expect(result.groups).toEqual([
@@ -194,11 +234,10 @@ describe('AutoGroupModal manual workflow', () => {
       },
     })
 
-    await wrapper.findAll('.mint-auto-group__manual-sample input')[0].trigger('change')
-    const fields = wrapper.findAll('.mint-auto-group__manual-field input')
-    await fields[0].setValue('Control')
-    await wrapper.find('.mint-auto-group__manual-assign').trigger('click')
-    await wrapper.find('.mint-auto-group__nav--manual .mint-button--primary').trigger('click')
+    await wrapper.findAll('.mg2-row')[1].trigger('click')
+    await wrapper.findAll('.mg2-bar .mg2-combo input')[0].setValue('Control')
+    await wrapper.find('.mg2-bar .sg-btn--primary').trigger('click')
+    await wrapper.find('.sg-foot .mint-button--primary').trigger('click')
 
     const result = wrapper.emitted('apply')?.at(-1)?.[0] as AutoGroupResult
     expect(result.groups).toEqual([
@@ -237,3 +276,124 @@ describe('SampleSelector — QC overlay regression', () => {
     expect(allSamples).toContain('iqc1')
   })
 })
+
+describe('AutoGroupModal CSV upload', () => {
+  it('loads an uploaded CSV into the engine so samples reach both auto and manual modes', async () => {
+    const wrapper = mount(AutoGroupModal, {
+      props: { modelValue: true, samples: [], groups: [] },
+      global: {
+        plugins: [createPinia()],
+        stubs: { Teleport: true },
+      },
+    })
+
+    const csv = 'sample_name,Condition\nS1,Control\nS2,Control\nS3,Treatment\n'
+    const file = new File([csv], 'samples.csv', { type: 'text/csv' })
+    wrapper.findComponent(SmartGroupFieldRecipe).vm.$emit('csv-file', file)
+    await settle()
+
+    // Auto mode: the CSV populated the engine's field cards + grouped all 3 samples.
+    const recipe = wrapper.findComponent(SmartGroupFieldRecipe)
+    expect((recipe.props('fields') as unknown[]).length).toBeGreaterThan(0)
+    const rail = recipe.props('groups') as Array<{ count: number }>
+    expect(rail.reduce((acc, g) => acc + g.count, 0)).toBe(3)
+
+    // Manual mode: the CSV sample names populate the manual list (sourced from
+    // the engine, not props.samples — which is empty here).
+    recipe.vm.$emit('manual')
+    await flushPromises()
+    const names = wrapper.findAll('.mg2-row__name').map(n => n.text())
+    expect(names).toEqual(['S1', 'S2', 'S3'])
+  })
+
+  it('surfaces an error (without throwing) for an empty/header-only CSV, then loads a valid one', async () => {
+    const wrapper = mount(AutoGroupModal, {
+      props: { modelValue: true, samples: [], groups: [] },
+      global: { plugins: [createPinia()], stubs: { Teleport: true } },
+    })
+    const recipe = wrapper.findComponent(SmartGroupFieldRecipe)
+
+    // Header-only CSV → parseCSV throws; onCsvFile must catch + surface the error.
+    recipe.vm.$emit('csv-file', new File(['sample_name\n'], 'bad.csv', { type: 'text/csv' }))
+    await settle()
+    expect(wrapper.find('.sg-host__error').exists()).toBe(true)
+    // Engine left un-mutated: no groups loaded from the bad file.
+    expect((recipe.props('groups') as unknown[]).length).toBe(0)
+
+    // A subsequent valid CSV clears the error and loads.
+    recipe.vm.$emit(
+      'csv-file',
+      new File(['sample_name,Condition\nS1,Control\nS2,Treatment\n'], 'good.csv', { type: 'text/csv' }),
+    )
+    await settle()
+    expect(wrapper.find('.sg-host__error').exists()).toBe(false)
+    const rail = recipe.props('groups') as Array<{ count: number }>
+    expect(rail.reduce((acc, g) => acc + g.count, 0)).toBe(2)
+  })
+})
+
+describe('SmartGroupFieldRecipe CSV menu', () => {
+  it('emits download-template from its menu item', async () => {
+    const wrapper = mount(SmartGroupFieldRecipe)
+    await wrapper.find('.fr-upload').trigger('click')
+    const items = wrapper.findAll('.fr-csv-item')
+    expect(items).toHaveLength(3)
+    await items[1].trigger('click')
+    expect(wrapper.emitted('download-template')).toHaveLength(1)
+  })
+
+  it('emits download-prefilled from its menu item', async () => {
+    const wrapper = mount(SmartGroupFieldRecipe)
+    await wrapper.find('.fr-upload').trigger('click')
+    await wrapper.findAll('.fr-csv-item')[2].trigger('click')
+    expect(wrapper.emitted('download-prefilled')).toHaveLength(1)
+  })
+
+  it('disables the download items (and emits nothing) when canDownloadTemplate is false', async () => {
+    const wrapper = mount(SmartGroupFieldRecipe, { props: { canDownloadTemplate: false } })
+    await wrapper.find('.fr-upload').trigger('click')
+    const items = wrapper.findAll('.fr-csv-item')
+    expect(items[1].attributes('disabled')).toBeDefined()
+    expect(items[2].attributes('disabled')).toBeDefined()
+    await items[1].trigger('click')
+    expect(wrapper.emitted('download-template')).toBeUndefined()
+  })
+})
+
+describe('AutoGroupModal template download wiring', () => {
+  it('maps the menu actions to engine downloadTemplate (blank vs prefilled)', async () => {
+    const blobs: Blob[] = []
+    const origCreate = URL.createObjectURL
+    const origRevoke = URL.revokeObjectURL
+    URL.createObjectURL = vi.fn((b: Blob) => {
+      blobs.push(b)
+      return 'blob:mock'
+    }) as typeof URL.createObjectURL
+    URL.revokeObjectURL = vi.fn() as typeof URL.revokeObjectURL
+    const clickSpy = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
+    try {
+      const wrapper = mount(AutoGroupModal, {
+        props: { modelValue: true, samples: ['Ctrl_R1', 'Ctrl_R2', 'Drug_R1', 'Drug_R2'], groups: [] },
+        global: { plugins: [createPinia()], stubs: { Teleport: true } },
+      })
+      const recipe = wrapper.findComponent(SmartGroupFieldRecipe)
+      recipe.vm.$emit('download-template')
+      await flushPromises()
+      recipe.vm.$emit('download-prefilled')
+      await flushPromises()
+
+      expect(blobs).toHaveLength(2)
+      const blankText = await blobs[0].text()
+      const prefilledText = await blobs[1].text()
+      // download-template → blank mode: the canonical generic DEFAULT_BLANK_HEADERS.
+      // download-prefilled → prefilled mode: a different, detected-column header.
+      expect(blankText.split('\n')[0]).toBe('sample_name,group,class,replicate,notes')
+      expect(prefilledText.split('\n')[0]).not.toBe(blankText.split('\n')[0])
+      expect(blankText).not.toBe(prefilledText)
+    } finally {
+      URL.createObjectURL = origCreate
+      URL.revokeObjectURL = origRevoke
+      clickSpy.mockRestore()
+    }
+  })
+})

package/src/__tests__/components/SmartGroupFieldRecipe.groups.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import {
+  appendQcGroup,
+  computeFieldGroups,
+  fieldRecipeSummary,
+  sampleTotalFor,
+  type SmartGroupField,
+  type SmartGroupSampleRecord,
+} from '../../components/SmartGroupFieldRecipe.groups'
+
+const FIELDS: SmartGroupField[] = [
+  { key: 'Condition', role: 'Factor', vals: 'Control, Treatment', rep: false },
+  { key: 'Dose', role: 'Factor', vals: 'Vehicle, Low, High', rep: false },
+  { key: 'Replicate', role: 'Replicate', vals: 'Rep1, Rep2, Rep3', rep: true },
+]
+
+const BASE = [
+  { Condition: 'Control', Dose: 'Vehicle' },
+  { Condition: 'Treatment', Dose: 'Low' },
+  { Condition: 'Treatment', Dose: 'High' },
+]
+const SAMPLES: SmartGroupSampleRecord[] = BASE.flatMap(base =>
+  [1, 2, 3].map(rep => ({ ...base, Replicate: `Rep${rep}` })),
+)
+
+const PALETTE = ['c1', 'c2', 'c3', 'c4', 'c5']
+
+describe('computeFieldGroups', () => {
+  it('should form three groups of three when grouping by Condition and Dose', () => {
+    const groups = computeFieldGroups(SAMPLES, FIELDS, [true, true, false], PALETTE)
+    expect(groups.map(g => g.name)).toEqual(['Control_Vehicle', 'Treatment_Low', 'Treatment_High'])
+    expect(groups.map(g => g.count)).toEqual([3, 3, 3])
+  })
+
+  it('should shatter into nine singleton groups when Replicate is included', () => {
+    const groups = computeFieldGroups(SAMPLES, FIELDS, [true, true, true], PALETTE)
+    expect(groups).toHaveLength(9)
+    expect(groups.every(g => g.count === 1)).toBe(true)
+  })
+
+  it('should return no groups when no field is active', () => {
+    expect(computeFieldGroups(SAMPLES, FIELDS, [false, false, false], PALETTE)).toEqual([])
+  })
+
+  it('should collapse to Condition only when just the first field is active', () => {
+    const groups = computeFieldGroups(SAMPLES, FIELDS, [true, false, false], PALETTE)
+    expect(groups.map(g => g.name)).toEqual(['Control', 'Treatment'])
+    expect(groups.map(g => g.count)).toEqual([3, 6])
+  })
+
+  it('should cycle colours through the palette in group order', () => {
+    const groups = computeFieldGroups(SAMPLES, FIELDS, [true, true, false], PALETTE)
+    expect(groups.map(g => g.color)).toEqual(['c1', 'c2', 'c3'])
+  })
+})
+
+describe('appendQcGroup', () => {
+  const base = computeFieldGroups(SAMPLES, FIELDS, [true, true, false], PALETTE)
+
+  it('should append a QC_Pool group of three when QC is mixed into groups', () => {
+    const result = appendQcGroup(base, 'Mix into groups', 'qc')
+    expect(result).toHaveLength(base.length + 1)
+    expect(result.at(-1)).toEqual({ name: 'QC_Pool', count: 3, color: 'qc' })
+  })
+
+  it('should leave groups untouched when QC overlays or is excluded', () => {
+    expect(appendQcGroup(base, 'Overlay only', 'qc')).toEqual(base)
+    expect(appendQcGroup(base, 'Exclude', 'qc')).toEqual(base)
+  })
+})
+
+describe('sampleTotalFor', () => {
+  it('should drop the QC pool only when QC is excluded', () => {
+    expect(sampleTotalFor('Exclude')).toBe(9)
+    expect(sampleTotalFor('Overlay only')).toBe(12)
+    expect(sampleTotalFor('Mix into groups')).toBe(12)
+  })
+})
+
+describe('fieldRecipeSummary', () => {
+  const baseGroups = computeFieldGroups(SAMPLES, FIELDS, [true, true, false], PALETTE)
+
+  it('should be muted when no factor is active', () => {
+    expect(fieldRecipeSummary({ activeFactors: [], repOn: false, baseGroups: [] }).kind).toBe('mute')
+  })
+
+  it('should warn when a replicate field is switched on', () => {
+    expect(fieldRecipeSummary({ activeFactors: ['Replicate'], repOn: true, baseGroups }).kind).toBe('warn')
+  })
+
+  it('should inform when grouping by factors only', () => {
+    expect(
+      fieldRecipeSummary({ activeFactors: ['Condition', 'Dose'], repOn: false, baseGroups }).kind,
+    ).toBe('info')
+  })
+})