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

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

@@ -0,0 +1,107 @@
+import { computed, ref } from 'vue'
+import { describe, expect, it } from 'vitest'
+import { useAutoGroup } from '../../composables/useAutoGroup'
+import { useAutoGroupInputSources } from '../../composables/useAutoGroupInputSources'
+import type { WizardStep } from '../../types/components'
+
+function makeSources(options: {
+  samples?: string[]
+  experimentId?: number
+  designData?: Record<string, unknown>
+  apiGet?: (url: string) => Promise<Record<string, unknown>>
+} = {}) {
+  const autoGroup = useAutoGroup()
+  const currentStep = ref(0)
+  const dynamicSteps = ref<WizardStep[]>([
+    { id: 'input', label: 'Input' },
+    { id: 'fields', label: 'Fields' },
+    { id: 'preview', label: 'Preview' },
+  ])
+  const sources = useAutoGroupInputSources({
+    autoGroup,
+    samples: computed(() => options.samples ?? []),
+    experimentId: computed(() => options.experimentId),
+    designData: computed(() => options.designData),
+    currentStep,
+    dynamicSteps,
+    api: {
+      get: async <T>(url: string): Promise<T> => {
+        const value = options.apiGet
+          ? await options.apiGet(url)
+          : { data: undefined }
+        return value as T
+      },
+    },
+  })
+
+  return { autoGroup, currentStep, dynamicSteps, sources }
+}
+
+describe('useAutoGroupInputSources', () => {
+  it('initializes pasted sample input when samples are provided', async () => {
+    const { autoGroup, currentStep, sources } = makeSources({
+      samples: ['S1_Control', 'S2_Treated'],
+    })
+    currentStep.value = 2
+
+    await sources.initializeInputSources()
+
+    expect(currentStep.value).toBe(0)
+    expect(autoGroup.rawText.value).toBe('S1_Control\nS2_Treated')
+    expect(sources.csvFileName.value).toBe('')
+    expect(sources.experimentError.value).toBeNull()
+  })
+
+  it('loads experiment design data and advances to the fields step', async () => {
+    const { autoGroup, currentStep, sources } = makeSources({
+      designData: {
+        samples: [
+          { sample_name: 'S1', sample_type: 'sample', conditions: { Treatment: 'Control' } },
+          { sample_name: 'S2', sample_type: 'sample', conditions: { Treatment: 'Drug' } },
+        ],
+      },
+    })
+
+    await sources.initializeInputSources()
+
+    expect(autoGroup.inputMode.value).toBe('experiment')
+    expect(autoGroup.csvData.value?.rows).toHaveLength(2)
+    expect(sources.experimentFieldNames.value).toEqual(['Treatment', 'sample_type'])
+    expect(currentStep.value).toBe(1)
+    expect(sources.experimentLoading.value).toBe(false)
+  })
+
+  it('parses uploaded CSV files and can clear them back to paste mode', async () => {
+    const { autoGroup, sources } = makeSources()
+    const file = {
+      name: 'samples.csv',
+      text: async () => 'sample_name,Treatment\nS1,Control\nS2,Drug',
+    } as File
+
+    await sources.processFile(file)
+
+    expect(autoGroup.inputMode.value).toBe('csv')
+    expect(autoGroup.csvData.value?.rows).toHaveLength(2)
+    expect(sources.csvFileName.value).toBe('samples.csv')
+
+    sources.clearCsvFile()
+
+    expect(autoGroup.inputMode.value).toBe('paste')
+    expect(autoGroup.csvData.value).toBeNull()
+    expect(sources.csvFileName.value).toBe('')
+  })
+
+  it('surfaces API errors when experiment metadata cannot be fetched', async () => {
+    const { sources } = makeSources({
+      experimentId: 42,
+      apiGet: async () => {
+        throw new Error('offline')
+      },
+    })
+
+    await sources.initializeInputSources()
+
+    expect(sources.experimentLoading.value).toBe(false)
+    expect(sources.experimentError.value).toBe('offline')
+  })
+})

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

@@ -22,6 +22,8 @@ import {
   defineWellPlateDoseControlProps,
   getDefaultControlView,
   getControlDefaults,
+  isControlModelBinding,
+  resolveControlModel,
   useControlSchema,
   useControlWorkspace,
 } from '../../composables/useControlSchema'
@@ -376,6 +378,27 @@ describe('useControlSchema', () => {
     expect(workspace.getComponentBindingsById(model.componentBindings).plate.props.modelValue).toEqual(['A1', 'A2'])
   })
 
+  it('normalizes raw and complete control models through one resolver', () => {
+    const rawModel = {
+      initialValues: { threshold: 0.1 },
+      controls: {
+        threshold: { type: 'number' as const, label: 'Threshold', default: 0.05 },
+      },
+    }
+
+    const binding = resolveControlModel(rawModel)
+
+    expect(isControlModelBinding(rawModel)).toBe(false)
+    expect(isControlModelBinding(binding)).toBe(true)
+    expect(binding?.controls.threshold).toMatchObject({
+      label: 'Threshold',
+      default: 0.05,
+    })
+    expect(binding?.controlOptions.initialValues).toEqual({ threshold: 0.1 })
+    expect(resolveControlModel(binding)).toBe(binding)
+    expect(resolveControlModel(undefined)).toBeUndefined()
+  })
+
   it('maps control values into named SDK component bindings', () => {
     const values = {
       threshold: 0.05,

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

@@ -0,0 +1,89 @@
+import { ref } from 'vue'
+import { describe, expect, it } from 'vitest'
+import type { ScheduleEvent, ScheduleView } from '../../types/components'
+import {
+  SCHEDULE_SLOT_HEIGHT,
+  getWeekStart,
+  parseScheduleModelDate,
+  useScheduleCalendarLayout,
+} from '../../composables/useScheduleCalendarLayout'
+
+function dateKey(date: Date): string {
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  return `${date.getFullYear()}-${month}-${day}`
+}
+
+function makeLayout(overrides: Partial<Parameters<typeof useScheduleCalendarLayout>[0]> = {}) {
+  const events: ScheduleEvent[] = [
+    {
+      id: 'run-1',
+      title: 'LCMS run',
+      start: '2024-05-15T07:00:00',
+      end: '2024-05-15T08:30:00',
+      status: 'in-progress',
+    },
+  ]
+
+  return useScheduleCalendarLayout({
+    currentView: ref<ScheduleView>('week'),
+    currentDate: ref(new Date('2024-05-15T12:00:00')),
+    now: ref(new Date('2024-05-15T07:30:00')),
+    events: ref(events),
+    blockedSlots: ref([
+      {
+        start: '2024-05-15T09:00:00',
+        end: '2024-05-15T09:30:00',
+        label: 'maintenance',
+      },
+    ]),
+    dayStartHour: ref(6),
+    dayEndHour: ref(10),
+    slotDuration: ref(30),
+    weekStartsOn: ref<0 | 1>(1),
+    locale: ref('en-US'),
+    showNowIndicator: ref(true),
+    slotHeight: ref(SCHEDULE_SLOT_HEIGHT),
+    ...overrides,
+  })
+}
+
+describe('useScheduleCalendarLayout', () => {
+  it('builds week ranges and time labels from calendar settings', () => {
+    const layout = makeLayout()
+
+    expect(layout.totalSlots.value).toBe(8)
+    expect(layout.timeLabels.value.slice(0, 3)).toEqual(['06:00', '06:30', '07:00'])
+    expect(dateKey(layout.visibleDays.value[0])).toBe('2024-05-13')
+    expect(dateKey(layout.visibleDays.value[6])).toBe('2024-05-19')
+  })
+
+  it('computes timed event, blocked slot, and now indicator styles', () => {
+    const layout = makeLayout()
+    const event = layout.getEventsForDate(new Date('2024-05-15T00:00:00'))[0]
+
+    expect(layout.getEventStyle(event, new Date('2024-05-15T00:00:00'))).toEqual({
+      top: '80px',
+      height: '120px',
+    })
+    expect(layout.getBlockedStyle(layout.getBlockedForDay(new Date('2024-05-15T00:00:00'))[0])).toEqual({
+      top: '240px',
+      height: '40px',
+    })
+    expect(layout.getNowIndicatorStyle()).toEqual({ top: '120px' })
+  })
+
+  it('builds month cells and weekday labels according to the week start', () => {
+    const layout = makeLayout({ currentView: ref<ScheduleView>('month') })
+
+    expect(layout.monthDays.value).toHaveLength(42)
+    expect(dateKey(layout.monthDays.value[0].date)).toBe('2024-04-29')
+    expect(layout.monthWeekdayLabels.value[0]).toBe('Mon')
+    expect(layout.headerTitle.value).toBe('May 2024')
+  })
+
+  it('parses model dates and honors alternate week starts', () => {
+    expect(parseScheduleModelDate('2024-05-15T00:00:00').getFullYear()).toBe(2024)
+    expect(dateKey(getWeekStart(new Date('2024-05-15T00:00:00'), 0))).toBe('2024-05-12')
+  })
+})

package/src/__tests__/docs/extractDocsComponents.test.ts

@@ -0,0 +1,142 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  extractComponent,
+  extractDeprecation,
+  parseComponentExports,
+} from '../../../scripts/extract-docs-components'
+
+const tempDirs: string[] = []
+
+function createTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'mint-docs-components-'))
+  tempDirs.push(dir)
+  return dir
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+describe('extract docs component helpers', () => {
+  it('parses grouped Vue component exports with JSDoc metadata', () => {
+    const dir = createTempDir()
+    const indexPath = join(dir, 'index.ts')
+    writeFileSync(indexPath, `
+// Base Components
+/** Primary action. */
+export { default as MintButton } from './Button.vue'
+
+// Scheduling / Booking Components
+/**
+ * @deprecated Prefer ScheduleCalendar.
+ */
+export { default as OldCalendar } from './OldCalendar.vue'
+
+// Custom Group
+export { default as SpecialThing } from './SpecialThing.vue'
+`)
+
+    expect(parseComponentExports(indexPath)).toEqual([
+      {
+        name: 'MintButton',
+        fileBase: 'Button',
+        group: 'base',
+        description: 'Primary action.',
+      },
+      {
+        name: 'OldCalendar',
+        fileBase: 'OldCalendar',
+        group: 'scheduling',
+        description: '@deprecated Prefer ScheduleCalendar.',
+        deprecated: true,
+        replacement: 'ScheduleCalendar',
+      },
+      {
+        name: 'SpecialThing',
+        fileBase: 'SpecialThing',
+        group: 'custom-group',
+      },
+    ])
+  })
+
+  it('extracts deprecation replacements from use/prefer prose', () => {
+    expect(extractDeprecation('@deprecated Use `NewThing()` instead.')).toEqual({
+      deprecated: true,
+      replacement: 'NewThing',
+    })
+    expect(extractDeprecation('Stable component.')).toEqual({})
+  })
+
+  it('extracts SFC props, emits, and slots from public components', () => {
+    const dir = createTempDir()
+    const componentPath = join(dir, 'src', 'components', 'FancyButton.vue')
+    mkdirSync(join(dir, 'src', 'components'), { recursive: true })
+    writeFileSync(componentPath, `
+<script setup lang="ts">
+/** Fancy button docs. */
+interface Props {
+  /** Visible label. */
+  label: string
+  variant?: 'primary' | 'secondary'
+}
+
+withDefaults(defineProps<Props>(), {
+  variant: 'primary',
+})
+
+defineEmits<{
+  'update:modelValue': [value: string]
+  click: []
+}>()
+
+defineSlots<{
+  default: () => unknown
+  suffix?: () => unknown
+}>()
+</script>
+
+<template>
+  <button>
+    <slot />
+    <slot name="suffix" />
+  </button>
+</template>
+`)
+
+    expect(extractComponent(componentPath, 'FancyButton', 'base', dir)).toMatchObject({
+      name: 'FancyButton',
+      kind: 'component',
+      group: 'base',
+      source: 'packages/sdk-frontend/src/components/FancyButton.vue',
+      description: 'Fancy button docs.',
+      props: [
+        {
+          name: 'label',
+          type: 'string',
+          required: true,
+          description: 'Visible label.',
+        },
+        {
+          name: 'variant',
+          type: "'primary' | 'secondary'",
+          required: false,
+          default: "'primary'",
+          description: '',
+        },
+      ],
+      emits: [
+        { name: 'update:modelValue', type: '(value: string) => void' },
+        { name: 'click', type: '() => void' },
+      ],
+      slots: [
+        { name: 'default', description: '' },
+        { name: 'suffix', description: '' },
+      ],
+    })
+  })
+})

package/src/__tests__/docs/extractDocsExports.test.ts

@@ -0,0 +1,77 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  parseNamedExports,
+  parseNamedExportSpecs,
+  resolveLocalExportPath,
+  resolveNamedExportPath,
+} from '../../../scripts/extract-docs-exports'
+
+const tempDirs: string[] = []
+
+function createTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'mint-docs-exports-'))
+  tempDirs.push(dir)
+  return dir
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+describe('extract docs export helpers', () => {
+  it('parses aliased named export specs and skips invalid entries', () => {
+    expect(parseNamedExportSpecs(`
+      type LocalType as PublicType,
+      InternalName as PublicName,
+      default,
+      invalid-name,
+      // ignored
+    `)).toEqual([
+      { localName: 'LocalType', exportedName: 'PublicType' },
+      { localName: 'InternalName', exportedName: 'PublicName' },
+    ])
+  })
+
+  it('resolves local export paths across files and directory indexes', () => {
+    const dir = createTempDir()
+    const indexPath = join(dir, 'index.ts')
+    const featureDir = join(dir, 'feature')
+    writeFileSync(indexPath, '')
+    writeFileSync(join(dir, 'direct.ts'), 'export const Direct = 1')
+    writeFileSync(join(dir, 'component.vue'), '<template />')
+    mkdirSync(featureDir)
+    writeFileSync(join(featureDir, 'index.ts'), 'export const Nested = 1')
+
+    expect(resolveLocalExportPath(indexPath, './direct')).toBe(join(dir, 'direct.ts'))
+    expect(resolveLocalExportPath(indexPath, './component')).toBe(join(dir, 'component.vue'))
+    expect(resolveLocalExportPath(indexPath, './feature')).toBe(join(featureDir, 'index.ts'))
+    expect(resolveLocalExportPath(indexPath, 'vue')).toBeNull()
+  })
+
+  it('collects and resolves named exports through re-export chains', () => {
+    const dir = createTempDir()
+    const indexPath = join(dir, 'index.ts')
+    const nestedPath = join(dir, 'nested.ts')
+    const leafPath = join(dir, 'leaf.ts')
+    const starPath = join(dir, 'star.ts')
+    writeFileSync(indexPath, `
+      export { Leaf as PublicLeaf } from './nested'
+      export * from './leaf'
+    `)
+    writeFileSync(nestedPath, "export { InternalLeaf as Leaf } from './leaf'")
+    writeFileSync(leafPath, "export const InternalLeaf = 1\nexport { StarExport } from './star'")
+    writeFileSync(starPath, 'export const StarExport = 2')
+
+    expect(parseNamedExports(indexPath)).toEqual([
+      { name: 'PublicLeaf' },
+      { name: 'StarExport' },
+    ])
+    expect(resolveNamedExportPath(indexPath, 'PublicLeaf')).toBe(leafPath)
+    expect(resolveNamedExportPath(indexPath, 'StarExport')).toBe(starPath)
+  })
+})

package/src/__tests__/docs/extractDocsParsing.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest'
+import {
+  cleanJsdoc,
+  cleanJsdocSummary,
+  extractBalancedBraces,
+  extractBalancedParens,
+  extractTrailingJsdoc,
+  findMatchingClose,
+  splitTopLevel,
+} from '../../../scripts/extract-docs-parsing'
+
+describe('extract docs parsing helpers', () => {
+  it('extracts balanced braces after whitespace-insensitive markers', () => {
+    const source = `
+      withDefaults(
+        defineProps<Props>(),
+        {
+          alpha: { nested: true },
+          beta: () => ({ value: 1 }),
+        }
+      )
+    `
+
+    expect(extractBalancedBraces(source, 'withDefaults(defineProps<Props>(),')).toContain(
+      'alpha: { nested: true }',
+    )
+  })
+
+  it('splits only top-level delimiters', () => {
+    expect(splitTopLevel('alpha, beta<{ one: string, two: number }>, gamma()', ',')).toEqual([
+      'alpha',
+      ' beta<{ one: string, two: number }>',
+      ' gamma()',
+    ])
+  })
+
+  it('finds matching close brackets and paren content with nested groups', () => {
+    const source = 'fn(alpha, nested(beta, gamma), delta)'
+    const openIdx = source.indexOf('(')
+
+    expect(findMatchingClose(source, openIdx, '(', ')')).toBe(source.length - openIdx - 1)
+    expect(extractBalancedParens(source, 0)).toBe('alpha, nested(beta, gamma), delta')
+  })
+
+  it('cleans JSDoc blocks and summaries', () => {
+    const comment = `
+      /**
+       * Primary summary.
+       *
+       * More details.
+       */
+    `
+
+    expect(cleanJsdoc(comment)).toBe('Primary summary.\nMore details.')
+    expect(cleanJsdocSummary(comment)).toBe('Primary summary.')
+  })
+
+  it('extracts only the trailing JSDoc closest to a declaration', () => {
+    const source = `
+      /** Earlier. */
+      const a = 1
+
+      /** Selected. */
+      export function useThing() {}
+    `
+
+    expect(extractTrailingJsdoc(source, source.indexOf('export function'))).toContain('Selected.')
+  })
+})

package/src/__tests__/docs/extractDocsTemplates.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+import { bioTemplateCatalog } from '../../../src/templates/catalog'
+import { bioTemplatePacks } from '../../../src/templates/packs'
+import { bioTemplatePresets } from '../../../src/templates/presets'
+import {
+  extractTemplatePacks,
+  extractTemplatePresets,
+  extractTemplates,
+} from '../../../scripts/extract-docs-templates'
+
+describe('extract docs template helpers', () => {
+  it('maps catalog templates into docs manifest entries', () => {
+    const entry = bioTemplateCatalog[0]!
+    const template = extractTemplates()[0]!
+
+    expect(extractTemplates()).toHaveLength(bioTemplateCatalog.length)
+    expect(template).toMatchObject({
+      name: entry.name,
+      kind: 'template',
+      group: entry.category,
+      source: 'packages/sdk-frontend/src/templates/catalog.ts',
+      description: entry.purpose,
+      template_id: entry.template_id,
+      template_version: entry.template_version,
+      add_command: entry.add_command,
+    })
+  })
+
+  it('maps curated presets and packs into docs manifest entries', () => {
+    const presetEntry = bioTemplatePresets[0]!
+    const preset = extractTemplatePresets()[0]!
+    const packEntry = bioTemplatePacks[0]!
+    const pack = extractTemplatePacks()[0]!
+
+    expect(extractTemplatePresets()).toHaveLength(bioTemplatePresets.length)
+    expect(preset).toMatchObject({
+      name: presetEntry.name,
+      kind: 'template-preset',
+      group: presetEntry.category,
+      source: 'packages/sdk-frontend/src/templates/presets.ts',
+      templates: presetEntry.templates,
+    })
+    expect(extractTemplatePacks()).toHaveLength(bioTemplatePacks.length)
+    expect(pack).toMatchObject({
+      name: packEntry.name,
+      kind: 'template-pack',
+      group: packEntry.category,
+      source: 'packages/sdk-frontend/src/templates/packs.ts',
+      add_command: packEntry.add_command,
+      init_command: packEntry.init_command,
+      docs_command: packEntry.docs_command,
+    })
+  })
+})

package/src/__tests__/docs/extractDocsTheme.test.ts

@@ -0,0 +1,89 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  extractCssVariables,
+  extractTailwindPreset,
+} from '../../../scripts/extract-docs-theme'
+
+const tempDirs: string[] = []
+
+function createTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'mint-docs-theme-'))
+  tempDirs.push(dir)
+  return dir
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+describe('extract docs theme helpers', () => {
+  it('groups CSS variables by root comment sections', () => {
+    const dir = createTempDir()
+    const cssPath = join(dir, 'variables.css')
+    writeFileSync(cssPath, `
+:root {
+  --spacing-sm: 0.5rem;
+  /* Background colors */
+  --bg-default: #ffffff;
+  --bg-muted: var(--mint-50);
+}
+`)
+
+    expect(extractCssVariables(cssPath)).toEqual({
+      General: [
+        { name: '--spacing-sm', value: '0.5rem' },
+      ],
+      'Background colors': [
+        { name: '--bg-default', value: '#ffffff' },
+        { name: '--bg-muted', value: 'var(--mint-50)' },
+      ],
+    })
+  })
+
+  it('extracts Tailwind color groups and font families', () => {
+    const dir = createTempDir()
+    const presetPath = join(dir, 'tailwind.preset.ts')
+    writeFileSync(presetPath, `
+export default {
+  theme: {
+    extend: {
+      colors: {
+        mint: {
+          50: "#f0fdfa",
+          600: "#0d9488",
+        },
+        bg: {
+          canvas: "var(--bg-default)",
+        },
+      },
+      fontFamily: {
+        sans: ['Inter', 'sans-serif'],
+        mono: ["JetBrains Mono", "monospace"],
+      },
+    },
+  },
+}
+`)
+
+    expect(extractTailwindPreset(presetPath)).toMatchObject({
+      colors: {
+        mint: {
+          50: '#f0fdfa',
+          600: '#0d9488',
+        },
+        bg: {
+          canvas: 'var(--bg-default)',
+        },
+      },
+      fontFamily: {
+        sans: 'Inter',
+        mono: 'JetBrains Mono',
+      },
+    })
+  })
+})

package/src/__tests__/docs/frontendDocsCatalog.test.ts

@@ -114,7 +114,7 @@ function parseDeprecatedComponentExports(): Record<string, string> {
 }
 
 function parseDocumentedComposableExports(): string[] {
-  const scriptContent = readFileSync(join(SDK_ROOT, 'scripts', 'extract-docs.ts'), 'utf8')
+  const scriptContent = readFileSync(join(SDK_ROOT, 'scripts', 'extract-docs-composables.ts'), 'utf8')
   const helperNames = new Set(
     [...(scriptContent.match(
       /const DOCUMENTED_COMPOSABLE_EXPORTS = new Set\(\[([\s\S]*?)\]\);/,