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

package/src/templates/componentBindings.ts

@@ -0,0 +1,615 @@
+import type { WellLegendItem } from '../types'
+import {
+  extractTemplateCollection,
+  getTemplateData,
+} from './builders'
+import {
+  toDoseConditions,
+  toDoseLayoutState,
+  toPlateMapEditorState,
+  toProtocolSteps,
+  toQpcrWellPlateWells,
+  toReagentListItems,
+  toSampleOptions,
+  toTemplateDataFrame,
+  toTimeCourseSteps,
+  toWellPlateWells,
+} from './adapters'
+import {
+  getBioTemplateInfo,
+} from './catalog'
+import {
+  getBioTemplatePresetInfo,
+} from './presets'
+import {
+  getBioTemplatePackInfo,
+} from './packs'
+import type {
+  BioTemplateEnvelope,
+  DataFrameTemplate,
+  DoseResponseTemplate,
+  PlateMapTemplate,
+  QpcrPlateTemplate,
+  ReagentListTemplate,
+  SampleSheetTemplate,
+  TemplateCollectionEnvelope,
+  TemplateId,
+  TemplatePackId,
+  TemplatePresetId,
+  TimeCourseTemplate,
+  ProtocolStepsTemplate,
+} from './types'
+
+export type BioTemplateComponentTarget =
+  | TemplateId
+  | TemplatePackId
+  | TemplatePresetId
+  | string
+  | BioTemplateEnvelope<unknown>
+  | TemplateCollectionEnvelope
+
+export interface BioTemplateComponentBinding {
+  id: string
+  template_id: TemplateId
+  component: string
+  adapters: readonly string[]
+  props: readonly string[]
+  description: string
+  importPath: '@morscherlab/mint-sdk'
+}
+
+export interface BioTemplateComponentPropsBinding extends BioTemplateComponentBinding {
+  propsObject: Record<string, unknown>
+}
+
+export type BioTemplateComponentPropsById = Record<string, Record<string, unknown>>
+export type BioTemplateComponentPropsByComponent = Record<string, Record<string, unknown>[]>
+
+export interface BioTemplateComponentPropsLookupOptions {
+  templateId?: TemplateId
+  id?: string
+}
+
+export interface BioTemplateComponentImport {
+  importPath: BioTemplateComponentBinding['importPath']
+  components: string[]
+  statement: string
+}
+
+export interface BioTemplateComponentSnippet extends BioTemplateComponentBinding {
+  propsName: string
+  propsExpression: string
+  template: string
+}
+
+export interface BioTemplateComponentSnippetOptions {
+  propsVariable?: string
+}
+
+export interface BioTemplateComponentUsageOptions extends BioTemplateComponentSnippetOptions {
+  targetExpression?: string
+  targetPropName?: string
+}
+
+export interface BioTemplateComponentUsage {
+  imports: BioTemplateComponentImport[]
+  componentProps: BioTemplateComponentPropsBinding[]
+  snippets: BioTemplateComponentSnippet[]
+  propsDeclarations: string[]
+  scriptSetup: string
+  template: string
+  sfc: string
+}
+
+const templateComponentBindings = {
+  'plate-map': [
+    binding('plate-map', 'PlateMapEditor', ['toPlateMapEditorState'], ['modelValue', 'format', 'samples'], 'Edit plate layouts from plate-map template data.'),
+    binding('plate-map', 'WellPlate', ['toWellPlateWells'], ['format', 'wells', 'sampleColors', 'legendItems'], 'Render the active plate as a well grid.'),
+  ],
+  'sample-sheet': [
+    binding('sample-sheet', 'DataFrame', ['toTemplateDataFrame'], ['data', 'columns', 'rowKey'], 'Render sample metadata as a sortable table.'),
+    binding('sample-sheet', 'SampleSelector', ['toSampleOptions'], ['samples', 'modelValue'], 'Select samples from sample-sheet records.'),
+  ],
+  'sample-prep': [
+    binding('sample-prep', 'DataFrame', ['toTemplateDataFrame'], ['data', 'columns', 'rowKey'], 'Render preparation steps as a table.'),
+  ],
+  'dose-response': [
+    binding('dose-response', 'DoseCalculator', ['toDoseConditions'], ['mode', 'targetWells'], 'Configure serial dilution and apply concentrations to wells.'),
+    binding('dose-response', 'WellPlate', ['toDoseLayoutState'], ['format', 'wells', 'sampleColors', 'legendItems'], 'Render the optional dose-response plate layout.'),
+  ],
+  'calibration-curve': [
+    binding('calibration-curve', 'DataFrame', ['toTemplateDataFrame'], ['data', 'columns', 'rowKey'], 'Render standards, QC, blanks, and response values.'),
+  ],
+  'time-course': [
+    binding('time-course', 'ExperimentTimeline', ['toTimeCourseSteps'], ['modelValue', 'orientation'], 'Render time points as an ordered timeline.'),
+    binding('time-course', 'DataFrame', ['toTemplateDataFrame'], ['data', 'columns', 'rowKey'], 'Render longitudinal samples as a table.'),
+  ],
+  'protocol-steps': [
+    binding('protocol-steps', 'ExperimentTimeline', ['toProtocolSteps'], ['modelValue', 'orientation', 'editable'], 'Render protocol steps as an editable timeline.'),
+    binding('protocol-steps', 'DataFrame', ['toTemplateDataFrame'], ['data', 'columns', 'rowKey'], 'Render protocol steps as a table.'),
+  ],
+  'assay-matrix': [
+    binding('assay-matrix', 'DataFrame', ['toTemplateDataFrame'], ['data', 'columns', 'rowKey'], 'Render sample-by-feature measurements.'),
+  ],
+  'reagent-list': [
+    binding('reagent-list', 'ReagentList', ['toReagentListItems'], ['modelValue'], 'Render reagents with lot, storage, and stock metadata.'),
+    binding('reagent-list', 'DataFrame', ['toTemplateDataFrame'], ['data', 'columns', 'rowKey'], 'Render reagents as a table.'),
+  ],
+  'flow-cytometry-panel': [
+    binding('flow-cytometry-panel', 'DataFrame', ['toTemplateDataFrame'], ['data', 'columns', 'rowKey'], 'Render markers, fluorophores, detectors, and controls.'),
+  ],
+  'instrument-run': [
+    binding('instrument-run', 'DataFrame', ['toTemplateDataFrame'], ['data', 'columns', 'rowKey'], 'Render acquisition queues, methods, QC, and run status.'),
+  ],
+  'qpcr-plate': [
+    binding('qpcr-plate', 'WellPlate', ['toQpcrWellPlateWells'], ['format', 'wells', 'sampleColors', 'legendItems'], 'Render qPCR reactions on a well plate.'),
+    binding('qpcr-plate', 'DataFrame', ['toTemplateDataFrame'], ['data', 'columns', 'rowKey'], 'Render qPCR reactions, targets, controls, and Cq values.'),
+  ],
+} satisfies Record<TemplateId, readonly BioTemplateComponentBinding[]>
+
+export function listBioTemplateComponentBindings(): Record<TemplateId, BioTemplateComponentBinding[]> {
+  return cloneBindingMap(templateComponentBindings)
+}
+
+export function getBioTemplateComponentBindings(
+  target: BioTemplateComponentTarget
+): BioTemplateComponentBinding[] {
+  const templateIds = resolveComponentTemplateIds(target)
+  return templateIds.flatMap(templateId => cloneBindings(templateComponentBindings[templateId]))
+}
+
+export function toBioTemplateComponentProps(
+  target: BioTemplateEnvelope<unknown> | TemplateCollectionEnvelope
+): BioTemplateComponentPropsBinding[] {
+  if (isTemplateEnvelope(target)) {
+    return propsForTemplate(target)
+  }
+
+  const collection = extractTemplateCollection(target)
+  return Object.values(collection).flatMap(template => propsForTemplate(template))
+}
+
+/** Return component props keyed by stable binding id for direct `v-bind="componentPropsById[id]"` use. */
+export function toBioTemplateComponentPropsById(
+  target: BioTemplateEnvelope<unknown> | TemplateCollectionEnvelope,
+): BioTemplateComponentPropsById {
+  return Object.fromEntries(
+    toBioTemplateComponentProps(target).map(binding => [binding.id, binding.propsObject]),
+  )
+}
+
+/** Return component props grouped by SDK component name for direct WellPlate/DoseCalculator binding. */
+export function toBioTemplateComponentPropsByComponent(
+  target: BioTemplateEnvelope<unknown> | TemplateCollectionEnvelope,
+): BioTemplateComponentPropsByComponent {
+  const grouped: BioTemplateComponentPropsByComponent = {}
+  for (const binding of toBioTemplateComponentProps(target)) {
+    const props = grouped[binding.component] ?? []
+    props.push(binding.propsObject)
+    grouped[binding.component] = props
+  }
+  return grouped
+}
+
+/** Return the first props object for an SDK component, optionally restricted by template id or binding id. */
+export function getBioTemplateComponentProps(
+  target: BioTemplateEnvelope<unknown> | TemplateCollectionEnvelope,
+  component: string,
+  options: BioTemplateComponentPropsLookupOptions = {},
+): Record<string, unknown> | undefined {
+  return toBioTemplateComponentProps(target).find((binding) => {
+    if (binding.component !== component) return false
+    if (options.id !== undefined && binding.id !== options.id) return false
+    if (options.templateId !== undefined && binding.template_id !== options.templateId) return false
+    return true
+  })?.propsObject
+}
+
+export function toBioTemplateComponentImports(
+  target: BioTemplateComponentTarget
+): BioTemplateComponentImport[] {
+  const groups = new Map<BioTemplateComponentBinding['importPath'], string[]>()
+
+  for (const binding of getBioTemplateComponentBindings(target)) {
+    const components = groups.get(binding.importPath) ?? []
+    if (!components.includes(binding.component)) components.push(binding.component)
+    groups.set(binding.importPath, components)
+  }
+
+  return Array.from(groups.entries()).map(([importPath, components]) => ({
+    importPath,
+    components,
+    statement: `import { ${components.join(', ')} } from '${importPath}'`,
+  }))
+}
+
+export function toBioTemplateComponentSnippets(
+  target: BioTemplateEnvelope<unknown> | TemplateCollectionEnvelope,
+  options: BioTemplateComponentSnippetOptions = {}
+): BioTemplateComponentSnippet[] {
+  const propsVariable = options.propsVariable ?? 'componentProps'
+  const usedNames = new Map<string, number>()
+
+  return toBioTemplateComponentProps(target).map((binding, index) => {
+    const propsName = uniquePropsName(binding, usedNames)
+    const propsExpression = `${propsVariable}[${index}].propsObject`
+    return {
+      ...cloneBinding(binding),
+      propsName,
+      propsExpression,
+      template: `<${binding.component} v-bind="${propsExpression}" />`,
+    }
+  })
+}
+
+export function toBioTemplateComponentUsage(
+  target: BioTemplateEnvelope<unknown> | TemplateCollectionEnvelope,
+  options: BioTemplateComponentUsageOptions = {}
+): BioTemplateComponentUsage {
+  const propsVariable = options.propsVariable ?? 'componentProps'
+  const usesGeneratedTargetProp = options.targetExpression === undefined
+  const targetPropName = options.targetPropName ?? 'templateCollection'
+  const targetExpression = options.targetExpression ?? `props.${targetPropName}`
+  const componentProps = toBioTemplateComponentProps(target)
+  const snippets = toBioTemplateComponentSnippets(target, { propsVariable }).map(snippet => ({
+    ...snippet,
+    propsExpression: snippet.propsName,
+    template: `<${snippet.component} v-bind="${snippet.propsName}" />`,
+  }))
+  const propsDeclarations = snippets.map(
+    (snippet, index) => `const ${snippet.propsName} = ${propsVariable}[${index}].propsObject`
+  )
+  const setupLines = [
+    ...(usesGeneratedTargetProp
+      ? [`const props = defineProps<{ ${targetPropName}: BioTemplateEnvelope<unknown> | TemplateCollectionEnvelope }>()`]
+      : []),
+    `const ${propsVariable} = toBioTemplateComponentProps(${targetExpression})`,
+    ...propsDeclarations,
+  ]
+  const imports = toBioTemplateComponentImports(target)
+  const template = snippets.map(snippet => snippet.template).join('\n')
+
+  return {
+    imports,
+    componentProps,
+    snippets,
+    propsDeclarations,
+    scriptSetup: setupLines.join('\n'),
+    template,
+    sfc: toVueSfc(imports, setupLines, template, usesGeneratedTargetProp),
+  }
+}
+
+function propsForTemplate(template: BioTemplateEnvelope<unknown>): BioTemplateComponentPropsBinding[] {
+  switch (template.template_id) {
+    case 'plate-map':
+      return plateMapProps(template as PlateMapTemplate)
+    case 'sample-sheet':
+      return [
+        dataFrameProps(template as DataFrameTemplate),
+        sampleSelectorProps(template as SampleSheetTemplate),
+      ]
+    case 'sample-prep':
+    case 'calibration-curve':
+    case 'assay-matrix':
+    case 'flow-cytometry-panel':
+    case 'instrument-run':
+      return [dataFrameProps(template as DataFrameTemplate)]
+    case 'dose-response':
+      return doseResponseProps(template as DoseResponseTemplate)
+    case 'time-course':
+      return [
+        timelineProps(template as TimeCourseTemplate, toTimeCourseSteps(template as TimeCourseTemplate)),
+        dataFrameProps(template as DataFrameTemplate),
+      ]
+    case 'protocol-steps':
+      return [
+        timelineProps(template as ProtocolStepsTemplate, toProtocolSteps(template as ProtocolStepsTemplate), true),
+        dataFrameProps(template as DataFrameTemplate),
+      ]
+    case 'reagent-list':
+      return [
+        reagentListProps(template as ReagentListTemplate),
+        dataFrameProps(template as DataFrameTemplate),
+      ]
+    case 'qpcr-plate':
+      return qpcrPlateProps(template as QpcrPlateTemplate)
+    default:
+      return []
+  }
+}
+
+function plateMapProps(template: PlateMapTemplate): BioTemplateComponentPropsBinding[] {
+  const state = toPlateMapEditorState(template)
+  const plate = activePlateFromState(state)
+  return [
+    propsBinding('plate-map', 'PlateMapEditor', {
+      modelValue: state,
+      format: plate.format,
+      samples: state.samples,
+    }),
+    propsBinding('plate-map', 'WellPlate', {
+      format: plate.format,
+      wells: toWellPlateWells(template),
+      sampleColors: sampleColorsFromPlateState(state),
+      legendItems: legendItemsFromPlateState(state),
+      showLegend: true,
+      showSampleTypeIndicator: true,
+    }),
+  ]
+}
+
+function doseResponseProps(template: DoseResponseTemplate): BioTemplateComponentPropsBinding[] {
+  const conditions = toDoseConditions(template)
+  const layout = toDoseLayoutState(template)
+  const targetWells = layout ? Object.keys(activePlateFromState(layout).wells) : []
+  const props = [
+    propsBinding('dose-response', 'DoseCalculator', {
+      mode: 'serial',
+      targetWells,
+      disabled: conditions.length === 0,
+    }),
+  ]
+
+  if (layout) {
+    const plate = activePlateFromState(layout)
+    props.push(propsBinding('dose-response', 'WellPlate', {
+      format: plate.format,
+      wells: plate.wells,
+      sampleColors: sampleColorsFromPlateState(layout),
+      legendItems: conditions.map(condition => ({
+        type: condition.label,
+        label: condition.label,
+        color: condition.color,
+      })),
+      showLegend: true,
+      showSampleTypeIndicator: true,
+    }))
+  }
+
+  return props
+}
+
+function qpcrPlateProps(template: QpcrPlateTemplate): BioTemplateComponentPropsBinding[] {
+  const data = getTemplateData(template, 'qpcr-plate')
+  const frame = dataFrameProps(template)
+  return [
+    propsBinding('qpcr-plate', 'WellPlate', {
+      format: data.format,
+      wells: toQpcrWellPlateWells(template),
+      sampleColors: Object.fromEntries(data.samples.map((sample, index) => [sample.sampleId, colorForIndex(index)])),
+      legendItems: data.samples.map((sample, index): WellLegendItem => ({
+        type: sample.sampleId,
+        label: sample.name ?? sample.sampleId,
+        color: colorForIndex(index),
+      })),
+      showLegend: true,
+      showSampleTypeIndicator: true,
+    }),
+    frame,
+  ]
+}
+
+function dataFrameProps(template: DataFrameTemplate): BioTemplateComponentPropsBinding {
+  const frame = toTemplateDataFrame(template)
+  return propsBinding(template.template_id as TemplateId, 'DataFrame', {
+    ...frame,
+    searchable: true,
+    sortable: true,
+    size: 'sm',
+  })
+}
+
+function sampleSelectorProps(template: SampleSheetTemplate): BioTemplateComponentPropsBinding {
+  const options = toSampleOptions(template)
+  return propsBinding('sample-sheet', 'SampleSelector', {
+    samples: options.map(option => option.label),
+    modelValue: [],
+  })
+}
+
+function timelineProps(
+  template: TimeCourseTemplate | ProtocolStepsTemplate,
+  steps: unknown[],
+  editable = false
+): BioTemplateComponentPropsBinding {
+  return propsBinding(template.template_id as TemplateId, 'ExperimentTimeline', {
+    modelValue: steps,
+    orientation: 'vertical',
+    editable,
+  })
+}
+
+function reagentListProps(template: ReagentListTemplate): BioTemplateComponentPropsBinding {
+  return propsBinding('reagent-list', 'ReagentList', {
+    modelValue: toReagentListItems(template),
+    searchable: true,
+    sortable: true,
+  })
+}
+
+function propsBinding(
+  templateId: TemplateId,
+  component: string,
+  propsObject: Record<string, unknown>
+): BioTemplateComponentPropsBinding {
+  const matched = templateComponentBindings[templateId].find(binding => binding.component === component)
+  if (!matched) {
+    throw new Error(`No component binding registered for '${templateId}' and '${component}'.`)
+  }
+  return {
+    ...cloneBinding(matched),
+    propsObject,
+  }
+}
+
+function resolveComponentTemplateIds(target: BioTemplateComponentTarget): TemplateId[] {
+  if (typeof target === 'string') {
+    const preset = getBioTemplatePresetInfo(target)
+    if (preset) return [...preset.templates]
+    const pack = getBioTemplatePackInfo(target)
+    if (pack) return [...pack.templates]
+    const template = getBioTemplateInfo(target)
+    return template ? [template.template_id] : []
+  }
+
+  if (isTemplateEnvelope(target)) {
+    const template = getBioTemplateInfo(target.template_id)
+    return template ? [template.template_id] : []
+  }
+
+  const presetName = collectionPresetName(target)
+  if (presetName) {
+    const preset = getBioTemplatePresetInfo(presetName)
+    if (preset) return [...preset.templates]
+  }
+
+  const packName = collectionPackName(target)
+  if (packName) {
+    const pack = getBioTemplatePackInfo(packName)
+    if (pack) return [...pack.templates]
+  }
+
+  return Object.keys(extractTemplateCollection(target))
+    .map(templateId => getBioTemplateInfo(templateId)?.template_id)
+    .filter((templateId): templateId is TemplateId => templateId !== undefined)
+}
+
+function binding(
+  templateId: TemplateId,
+  component: string,
+  adapters: readonly string[],
+  props: readonly string[],
+  description: string
+): BioTemplateComponentBinding {
+  return {
+    id: `${templateId}:${component}`,
+    template_id: templateId,
+    component,
+    adapters,
+    props,
+    description,
+    importPath: '@morscherlab/mint-sdk',
+  }
+}
+
+function activePlateFromState(state: ReturnType<typeof toPlateMapEditorState>) {
+  return state.plates.find(plate => plate.id === state.activePlateId) ?? state.plates[0]
+}
+
+function sampleColorsFromPlateState(state: ReturnType<typeof toPlateMapEditorState>): Record<string, string> {
+  return Object.fromEntries(
+    state.samples
+      .filter(sample => sample.color)
+      .map(sample => [sample.id, sample.color as string])
+  )
+}
+
+function legendItemsFromPlateState(state: ReturnType<typeof toPlateMapEditorState>): WellLegendItem[] {
+  return state.samples.map((sample, index) => ({
+    type: sample.id,
+    label: sample.name,
+    color: sample.color ?? colorForIndex(index),
+  }))
+}
+
+function colorForIndex(index: number): string {
+  const colors = ['#3B82F6', '#10B981', '#EF4444', '#F59E0B', '#8B5CF6', '#F97316', '#06B6D4', '#14B8A6']
+  return colors[index % colors.length]
+}
+
+function cloneBindingMap<TName extends string>(
+  bindings: Record<TName, readonly BioTemplateComponentBinding[]>
+): Record<TName, BioTemplateComponentBinding[]> {
+  const result = {} as Record<TName, BioTemplateComponentBinding[]>
+  for (const name of Object.keys(bindings) as TName[]) {
+    result[name] = cloneBindings(bindings[name])
+  }
+  return result
+}
+
+function cloneBindings(bindings: readonly BioTemplateComponentBinding[]): BioTemplateComponentBinding[] {
+  return bindings.map(cloneBinding)
+}
+
+function cloneBinding(binding: BioTemplateComponentBinding): BioTemplateComponentBinding {
+  return {
+    ...binding,
+    adapters: [...binding.adapters],
+    props: [...binding.props],
+  }
+}
+
+function uniquePropsName(
+  binding: BioTemplateComponentBinding,
+  usedNames: Map<string, number>
+): string {
+  const base = toCamelIdentifier(`${binding.template_id} ${binding.component} props`)
+  const count = usedNames.get(base) ?? 0
+  usedNames.set(base, count + 1)
+  return count === 0 ? base : `${base}${count + 1}`
+}
+
+function toCamelIdentifier(value: string): string {
+  const words = value
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+
+  if (words.length === 0) return 'componentProps'
+
+  return words
+    .map((word, index) => {
+      const lower = word.toLowerCase()
+      return index === 0 ? lower : lower.charAt(0).toUpperCase() + lower.slice(1)
+    })
+    .join('')
+}
+
+function toVueSfc(
+  imports: BioTemplateComponentImport[],
+  setupLines: string[],
+  template: string,
+  includeTargetTypeImport: boolean
+): string {
+  const importLines = [
+    ...imports.map(item => item.statement),
+    "import { toBioTemplateComponentProps } from '@morscherlab/mint-sdk/templates'",
+    ...(includeTargetTypeImport
+      ? ["import type { BioTemplateEnvelope, TemplateCollectionEnvelope } from '@morscherlab/mint-sdk/templates'"]
+      : []),
+  ]
+  const templateLines = template
+    ? template.split('\n').map(line => `  ${line}`).join('\n')
+    : ''
+
+  return [
+    '<script setup lang="ts">',
+    ...importLines,
+    '',
+    ...setupLines,
+    '</script>',
+    '',
+    '<template>',
+    templateLines,
+    '</template>',
+  ].join('\n')
+}
+
+function isTemplateEnvelope(value: unknown): value is BioTemplateEnvelope<unknown> {
+  return isRecord(value) && typeof value.template_id === 'string' && 'data' in value
+}
+
+function collectionPresetName(value: unknown): string | undefined {
+  if (!isRecord(value) || !isRecord(value.metadata)) return undefined
+  return typeof value.metadata.preset === 'string' ? value.metadata.preset : undefined
+}
+
+function collectionPackName(value: unknown): string | undefined {
+  if (!isRecord(value) || !isRecord(value.metadata)) return undefined
+  return typeof value.metadata.pack === 'string' ? value.metadata.pack : undefined
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}