@morscherlab/mint-sdk 1.0.0-rc.1 → 1.0.0-rc.4

package/src/composables/useControlWorkspace.ts

@@ -0,0 +1,207 @@
+import {
+  computed,
+  reactive,
+  ref,
+  watch,
+} from 'vue'
+import type {
+  PillNavItem,
+  TopBarSettingsConfig,
+} from '../types'
+import {
+  replaceRecord,
+} from './controlSchemaUtils'
+import {
+  mergeControlWorkspaceOptions,
+} from './controlWorkspaceOptions'
+import {
+  controlValuesToComponentBindings,
+  controlValuesToComponentBindingsById,
+  controlValuesToComponentProps,
+} from './controlComponentBindings'
+import {
+  useControlSchema,
+} from './useControlSchema'
+import type {
+  ControlComponentBinding,
+  ControlComponentBindingsById,
+  ControlComponentBindingsConfig,
+  ControlComponentPropsByIdMap,
+  ControlComponentPropsMap,
+  ControlModelBinding,
+  ControlSchema,
+  ControlValues,
+  ControlWorkspaceComponentBindings,
+  ControlWorkspaceFormBinding,
+  ControlWorkspaceOptions,
+  ControlWorkspacePillNavBinding,
+  ControlWorkspaceSidebarBinding,
+  ControlWorkspaceTopBarBinding,
+  ControlWorkspaceTopBarSettingsBinding,
+  UseControlWorkspaceReturn,
+} from './useControlSchema'
+
+/** Prepare shared reactive values plus AppTopBar/AppSidebar/FormBuilder bindings from one simple controls data model. */
+export function useControlWorkspace<TControls extends ControlSchema>(
+  controlsOrModel: TControls | (ControlModelBinding & { controls: TControls }),
+  options: ControlWorkspaceOptions = {},
+): UseControlWorkspaceReturn<TControls> {
+  const model = isControlModelBindingInput<TControls>(controlsOrModel) ? controlsOrModel : undefined
+  const controls: TControls = model ? model.controls : controlsOrModel as TControls
+  const workspaceOptions = model
+    ? mergeControlWorkspaceOptions(model.controlOptions, options)
+    : options
+  const { initialValues, topBarSettings, ...schemaOptions } = workspaceOptions
+  const schema = useControlSchema(controls, schemaOptions)
+  const activeView = ref(schema.defaultView)
+  const values = reactive({
+    ...schema.initialValues,
+    ...(initialValues ?? {}),
+  }) as ControlValues<TControls> & Record<string, unknown>
+
+  function setActiveView(viewId: string) {
+    syncActiveView(viewId)
+  }
+
+  function syncActiveView(viewId: string) {
+    if (!schema.viewIds.includes(viewId)) return
+    if (activeView.value !== viewId) activeView.value = viewId
+    if (sidebar.activeView !== viewId) sidebar.activeView = viewId
+    if (pillNav.currentItemId !== viewId) pillNav.currentItemId = viewId
+  }
+
+  function setValues(nextValues: Record<string, unknown>) {
+    Object.assign(values, nextValues)
+  }
+
+  function resetValues(nextValues: Record<string, unknown> = {}) {
+    replaceRecord(values, {
+      ...schema.initialValues,
+      ...nextValues,
+    })
+  }
+
+  function getComponentProps(
+    mapping?: ControlComponentPropsMap<ControlValues<TControls> & Record<string, unknown>>,
+  ): Record<string, unknown> {
+    return controlValuesToComponentProps(values, mapping)
+  }
+
+  function getComponentPropsById(
+    mappings?: ControlComponentPropsByIdMap<ControlValues<TControls> & Record<string, unknown>>,
+  ): Record<string, Record<string, unknown>> {
+    if (mappings === undefined) return {}
+
+    return Object.fromEntries(
+      Object.entries(mappings).map(([id, mapping]) => [
+        id,
+        controlValuesToComponentProps(values, mapping),
+      ]),
+    )
+  }
+
+  function getComponentBindings(
+    bindings?: ControlComponentBindingsConfig<ControlValues<TControls> & Record<string, unknown>>,
+  ): ControlComponentBinding[] {
+    return controlValuesToComponentBindings(values, bindings)
+  }
+
+  function getComponentBindingsById(
+    bindings?: ControlComponentBindingsConfig<ControlValues<TControls> & Record<string, unknown>>,
+  ): ControlComponentBindingsById {
+    return controlValuesToComponentBindingsById(values, bindings)
+  }
+
+  const componentProps = computed(() => (
+    model?.componentProps === undefined ? {} : getComponentProps(model.componentProps)
+  ))
+  const componentPropsById = computed(() => getComponentPropsById(model?.componentPropsById))
+  const componentBindings = computed(() => getComponentBindings(model?.componentBindings))
+  const componentBindingsById = computed(() => getComponentBindingsById(model?.componentBindings))
+  const form = {
+    ...schema.form,
+    modelValue: values,
+    'onUpdate:modelValue': setValues,
+  } as ControlWorkspaceFormBinding
+
+  const topBarSettingsConfig: TopBarSettingsConfig = {
+    ...schema.topBarSettingsConfig,
+    ...(topBarSettings ?? {}),
+    values,
+  }
+  const sidebar = reactive({
+    ...schema.sidebar,
+    activeView: activeView.value,
+    modelValue: values,
+    'onUpdate:modelValue': setValues,
+    values,
+    'onUpdate:values': setValues,
+  }) as ControlWorkspaceSidebarBinding
+  const pillNav = reactive({
+    items: schema.viewItems,
+    currentItemId: activeView.value,
+    onSelect: (item: PillNavItem) => setActiveView(item.id),
+  }) as ControlWorkspacePillNavBinding
+  const topBarSettingsBinding = {
+    showSettings: true,
+    settingsConfig: topBarSettingsConfig,
+    onSettingsValuesChange: setValues,
+  } as ControlWorkspaceTopBarSettingsBinding
+  const topBarProps = computed<ControlWorkspaceTopBarBinding>(() => ({
+    pillNav: pillNav.items,
+    currentPillId: pillNav.currentItemId,
+    onPillSelect: pillNav.onSelect,
+    ...topBarSettingsBinding,
+  }))
+  const bindings: ControlWorkspaceComponentBindings = {
+    form,
+    sidebar,
+    topBar: topBarProps,
+    topBarSettings: topBarSettingsBinding,
+    pillNav,
+    componentBindings,
+    componentBindingsById,
+    componentProps,
+    componentPropsById,
+  }
+
+  watch(activeView, syncActiveView, { flush: 'sync' })
+  watch(() => sidebar.activeView, syncActiveView, { flush: 'sync' })
+  watch(() => pillNav.currentItemId, syncActiveView, { flush: 'sync' })
+
+  return {
+    ...schema,
+    schema,
+    values,
+    activeView,
+    topBarSettingsConfig,
+    form,
+    sidebar,
+    topBar: topBarProps,
+    pillNav,
+    topBarSettings: topBarSettingsBinding,
+    bindings,
+    componentBindings,
+    componentBindingsById,
+    componentProps,
+    componentPropsById,
+    setActiveView,
+    setValues,
+    resetValues,
+    getComponentProps,
+    getComponentPropsById,
+    getComponentBindings,
+    getComponentBindingsById,
+  }
+}
+
+function isControlModelBindingInput<TControls extends ControlSchema>(
+  value: TControls | (ControlModelBinding & { controls: TControls }),
+): value is ControlModelBinding & { controls: TControls } {
+  return (
+    typeof value === 'object'
+    && value !== null
+    && 'controls' in value
+    && 'controlOptions' in value
+  )
+}

package/src/composables/useExperimentData.ts

@@ -1,7 +1,12 @@
-import { ref, computed, type Ref, type ComputedRef } from 'vue'
-import { useApi } from './useApi'
+import { shallowRef, computed, type Ref, type ComputedRef } from 'vue'
+import { useApi, type UseApiReturn } from './useApi'
 import { useRequestSyncState } from './useRequestSyncState'
-import type { TreeNode, SummaryData } from '../types'
+import {
+  extractSampleNamesFromDesignData,
+  extractSampleOptionsFromDesignData,
+  unwrapExperimentDesignData,
+} from './experimentDesignData'
+import type { TreeNode, SummaryData, SelectOption } from '../types'
 
 export interface UseExperimentDataOptions {
   apiBaseUrl?: string
@@ -9,8 +14,14 @@ export interface UseExperimentDataOptions {
 }
 
 export interface UseExperimentDataReturn {
-  /** Raw experiment data payload from `/experiments/{id}/data`, or null. */
+  /** Raw experiment data response from `/experiments/{id}/data`, or null. */
   data: Ref<Record<string, unknown> | null>
+  /** Plugin-defined design_data payload unwrapped from platform response shapes, or null. */
+  designData: ComputedRef<Record<string, unknown> | null>
+  /** Sample values extracted from design_data for SampleSelector-style components. */
+  sampleNames: ComputedRef<string[]>
+  /** Sample options extracted from design_data for select/dropdown components. */
+  sampleOptions: ComputedRef<SelectOption<string>[]>
   /** Hierarchy tree rows normalised from `tree_data` or `treeData`. */
   treeData: ComputedRef<TreeNode[]>
   /** Table rows normalised from `table_data` or `tableData`. */
@@ -24,54 +35,74 @@ export interface UseExperimentDataReturn {
   /** Timestamp of the last successful experiment data fetch, or null. */
   lastLoadedAt: Ref<Date | null>
   /** Fetch experiment data for an experiment id. */
-  fetch: (experimentId: number) => Promise<void>
+  fetch: (experimentId: number) => Promise<Record<string, unknown> | null>
   /** Refetch the most recently fetched experiment id. */
   refresh: () => Promise<void>
+  /** Clear local experiment data and current fetch target. */
+  clear: () => void
 }
 
 /** Fetches and normalises experiment output data (tree, table, summary) from the platform API. */
 export function useExperimentData(
   options: UseExperimentDataOptions = {},
 ): UseExperimentDataReturn {
-  const api = useApi({ baseUrl: options.apiBaseUrl })
-
-  const data = ref<Record<string, unknown> | null>(null)
+  const data = shallowRef<Record<string, unknown> | null>(null)
   const request = useRequestSyncState('Failed to fetch experiment data')
   const isLoading = request.loading
   const error = request.error
   const lastLoadedAt = request.lastLoadedAt
   let lastExperimentId: number | null = null
+  let api: UseApiReturn | null = null
+
+  function getApi(): UseApiReturn {
+    api ??= useApi({ baseUrl: options.apiBaseUrl })
+    return api
+  }
+
+  const designData = computed<Record<string, unknown> | null>(() =>
+    unwrapExperimentDesignData(data.value),
+  )
+
+  const sampleNames = computed<string[]>(() =>
+    extractSampleNamesFromDesignData(designData.value),
+  )
+
+  const sampleOptions = computed<SelectOption<string>[]>(() =>
+    extractSampleOptionsFromDesignData(designData.value),
+  )
 
   const treeData = computed<TreeNode[]>(() => {
-    if (!data.value) return []
-    const tree = data.value.tree_data ?? data.value.treeData
+    if (!designData.value) return []
+    const tree = designData.value.tree_data ?? designData.value.treeData
     return Array.isArray(tree) ? tree as TreeNode[] : []
   })
 
   const tableData = computed<Record<string, unknown>[]>(() => {
-    if (!data.value) return []
-    const table = data.value.table_data ?? data.value.tableData
+    if (!designData.value) return []
+    const table = designData.value.table_data ?? designData.value.tableData
     return Array.isArray(table) ? table as Record<string, unknown>[] : []
   })
 
   const summaryData = computed<SummaryData | null>(() => {
-    if (!data.value) return null
-    const summary = data.value.summary_data ?? data.value.summaryData
+    if (!designData.value) return null
+    const summary = designData.value.summary_data ?? designData.value.summaryData
     if (summary && typeof summary === 'object' && 'metadata' in (summary as Record<string, unknown>)) {
       return summary as SummaryData
     }
     return null
   })
 
-  async function fetchData(experimentId: number): Promise<void> {
+  async function fetchData(experimentId: number): Promise<Record<string, unknown> | null> {
     lastExperimentId = experimentId
     try {
       data.value = await request.run(
-        () => api.get<Record<string, unknown>>(`/experiments/${experimentId}/data`),
+        () => getApi().get<Record<string, unknown>>(`/experiments/${experimentId}/data`),
         { success: 'load', errorMessage: 'Failed to fetch experiment data' },
       )
+      return data.value
     } catch {
       data.value = null
+      return null
     }
   }
 
@@ -81,8 +112,17 @@ export function useExperimentData(
     }
   }
 
+  function clear(): void {
+    data.value = null
+    lastExperimentId = null
+    request.clearError()
+  }
+
   return {
     data,
+    designData,
+    sampleNames,
+    sampleOptions,
     treeData,
     tableData,
     summaryData,
@@ -91,5 +131,6 @@ export function useExperimentData(
     lastLoadedAt,
     fetch: fetchData,
     refresh,
+    clear,
   }
 }

package/src/composables/useExperimentSamples.ts

@@ -0,0 +1,142 @@
+import {
+  computed,
+  inject,
+  toValue,
+  watch,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+import type { SelectOption } from '../types'
+import { APP_EXPERIMENT_KEY } from './useAppExperiment'
+import {
+  extractSampleNamesFromDesignData,
+  extractSampleOptionsFromDesignData,
+  unwrapExperimentDesignData,
+  type ExtractExperimentSamplesOptions,
+} from './experimentDesignData'
+import { parseExperimentId } from './platformContextHelpers'
+import { useExperimentData } from './useExperimentData'
+
+export type ExperimentIdSource = MaybeRefOrGetter<number | string | null | undefined>
+export type ExperimentDesignDataSource = MaybeRefOrGetter<Record<string, unknown> | null | undefined>
+
+export interface UseExperimentSamplesOptions extends ExtractExperimentSamplesOptions {
+  /** Experiment id to load from `/experiments/{id}/data`; defaults to provided AppExperiment context. */
+  experimentId?: ExperimentIdSource
+  /** Pre-fetched design_data or full platform design-data response. */
+  designData?: ExperimentDesignDataSource
+  /** API base URL override for platform calls. */
+  apiBaseUrl?: string
+  /** Auto-load when an experiment id becomes available. Defaults to true. */
+  immediate?: boolean
+  /** Enable or disable automatic loading while keeping derived samples reactive. Defaults to true. */
+  enabled?: MaybeRefOrGetter<boolean>
+  /** Use `useAppExperiment` provided state when `experimentId` is not set. Defaults to true. */
+  syncAppExperiment?: boolean
+}
+
+export interface UseExperimentSamplesReturn {
+  /** Experiment id currently used for automatic sample loading. */
+  experimentId: ComputedRef<number | undefined>
+  /** Raw `/experiments/{id}/data` response when loaded through the platform API. */
+  data: Ref<Record<string, unknown> | null>
+  /** Plugin-defined design_data payload from props or platform response. */
+  designData: ComputedRef<Record<string, unknown> | null>
+  /** SampleSelector-compatible string values extracted from design_data. */
+  samples: ComputedRef<string[]>
+  /** Select/dropdown-friendly sample options extracted from design_data. */
+  sampleOptions: ComputedRef<SelectOption<string>[]>
+  isLoading: Ref<boolean>
+  error: Ref<string | null>
+  lastLoadedAt: Ref<Date | null>
+  /** Fetch samples for a specific experiment id, defaulting to the resolved id. */
+  fetch: (experimentId?: number | string | null) => Promise<Record<string, unknown> | null>
+  /** Refetch the current experiment id. */
+  refresh: () => Promise<void>
+  /** Clear fetched platform data. */
+  clear: () => void
+}
+
+/** Loads experiment design_data and derives samples for SampleSelector-style UIs. */
+export function useExperimentSamples(
+  options: UseExperimentSamplesOptions = {},
+): UseExperimentSamplesReturn {
+  const appExperiment = options.syncAppExperiment === false
+    ? undefined
+    : inject(APP_EXPERIMENT_KEY, undefined)
+  const experimentData = useExperimentData({ apiBaseUrl: options.apiBaseUrl })
+
+  const experimentId = computed<number | undefined>(() => {
+    const explicitId = parseExperimentId(toValue(options.experimentId))
+    return explicitId ?? parseExperimentId(appExperiment?.experimentId.value)
+  })
+
+  const explicitDesignData = computed<Record<string, unknown> | null>(() =>
+    unwrapExperimentDesignData(toValue(options.designData) ?? null),
+  )
+
+  const designData = computed<Record<string, unknown> | null>(() =>
+    explicitDesignData.value ?? experimentData.designData.value,
+  )
+
+  const extractOptions = computed<ExtractExperimentSamplesOptions>(() => ({
+    includeControls: options.includeControls,
+  }))
+
+  const samples = computed<string[]>(() =>
+    extractSampleNamesFromDesignData(designData.value, extractOptions.value),
+  )
+
+  const sampleOptions = computed<SelectOption<string>[]>(() =>
+    extractSampleOptionsFromDesignData(designData.value, extractOptions.value),
+  )
+
+  const enabled = computed(() => toValue(options.enabled) ?? true)
+
+  async function fetchSamples(
+    id: number | string | null | undefined = experimentId.value,
+  ): Promise<Record<string, unknown> | null> {
+    const parsedId = parseExperimentId(id)
+    if (parsedId === undefined) {
+      experimentData.clear()
+      return null
+    }
+    return experimentData.fetch(parsedId)
+  }
+
+  watch(
+    () => ({
+      designData: explicitDesignData.value,
+      enabled: enabled.value,
+      experimentId: experimentId.value,
+    }),
+    ({ designData: currentDesignData, enabled: isEnabled, experimentId: currentExperimentId }) => {
+      if (options.immediate === false || !isEnabled) return
+      if (currentDesignData) {
+        experimentData.clear()
+        return
+      }
+      if (currentExperimentId === undefined) {
+        experimentData.clear()
+        return
+      }
+      void experimentData.fetch(currentExperimentId)
+    },
+    { immediate: options.immediate !== false },
+  )
+
+  return {
+    experimentId,
+    data: experimentData.data,
+    designData,
+    samples,
+    sampleOptions,
+    isLoading: experimentData.isLoading,
+    error: experimentData.error,
+    lastLoadedAt: experimentData.lastLoadedAt,
+    fetch: fetchSamples,
+    refresh: experimentData.refresh,
+    clear: experimentData.clear,
+  }
+}

package/src/index.ts

@@ -19,6 +19,15 @@ export {
 // Stores
 export * from './stores'
 
+// Permissions
+export * from './permissions'
+
+// Instrument monitoring
+export * from './instrument'
+
+// LCMS sequence helpers
+export * from './lcms'
+
 // Utils
 export {
   hexToHsl,
@@ -26,6 +35,24 @@ export {
   deriveShade,
   type Hsl,
 } from './utils/color'
+export {
+  LCMS_DEFAULT_CONTROL_POSITIONS,
+  createLcmsControlWellEditData,
+  getLcmsDefaultControlWellId,
+  lcmsPlateCellsToRack,
+  lcmsPlateCellsToRacks,
+  lcmsPlateTypeToRackFormat,
+  lcmsWellId,
+  parseLcmsWellId,
+  rackFormatToLcmsPlateType,
+  rackToLcmsPlateCells,
+  racksToLcmsPlateCells,
+  type LcmsControlSampleType,
+  type LcmsPlateCell,
+  type LcmsPlateCellsToRackOptions,
+  type LcmsPlateCellsToRacksOptions,
+  type LcmsPlateType,
+} from './utils/rack'
 
 // Biology data templates
 export * from './templates'

package/src/instrument.ts

@@ -0,0 +1,90 @@
+import type { SequenceProgress } from './types'
+
+export function sequenceProgressPercent(progress: SequenceProgress | null | undefined): number {
+  if (!progress || progress.total_samples <= 0) return 0
+  return Math.round(clamp((progress.current_sample / progress.total_samples) * 100, 0, 100))
+}
+
+export function sequenceSamplesRemaining(progress: SequenceProgress | null | undefined): number {
+  if (!progress) return 0
+  return Math.max(0, progress.total_samples - progress.current_sample)
+}
+
+export function estimateSequenceRemainingSeconds(
+  progress: SequenceProgress | null | undefined,
+): number | null {
+  if (!progress) return null
+  const samplesLeft = sequenceSamplesRemaining(progress)
+  if (samplesLeft <= 0) return 0
+
+  const explicit = progress.estimated_remaining_seconds
+  if (typeof explicit === 'number' && explicit > 0) return explicit
+
+  const avg = progress.avg_sample_seconds ?? average(progress.sample_durations)
+  if (typeof avg === 'number' && avg > 0) return samplesLeft * avg
+
+  const elapsed = progress.elapsed_seconds ?? 0
+  if (elapsed > 0 && progress.current_sample > 0) {
+    return (elapsed / progress.current_sample) * samplesLeft
+  }
+
+  return null
+}
+
+export function estimateSequenceFinishDate(
+  progress: SequenceProgress | null | undefined,
+  now = new Date(),
+): Date | null {
+  if (!progress) return null
+
+  const explicit = coerceDate(progress.estimated_finish_time)
+  if (explicit) return explicit
+
+  const remaining = estimateSequenceRemainingSeconds(progress)
+  if (remaining == null || remaining <= 0) return null
+  return new Date(now.getTime() + remaining * 1000)
+}
+
+export function formatSequenceRemaining(progress: SequenceProgress | null | undefined): string | null {
+  const remaining = estimateSequenceRemainingSeconds(progress)
+  if (remaining == null || remaining <= 0) return null
+
+  const minutes = remaining / 60
+  if (minutes < 1) return `${Math.round(remaining)}s left`
+  if (minutes < 60) return `~${Math.round(minutes)}m left`
+
+  const hours = Math.floor(minutes / 60)
+  const mins = Math.round(minutes % 60)
+  return mins > 0 ? `~${hours}h ${mins}m left` : `~${hours}h left`
+}
+
+export function formatSequenceEta(
+  progress: SequenceProgress | null | undefined,
+  locale?: Intl.LocalesArgument,
+  options: Intl.DateTimeFormatOptions = {},
+): string | null {
+  const finish = estimateSequenceFinishDate(progress)
+  if (!finish) return null
+  return finish.toLocaleTimeString(locale, {
+    hour: '2-digit',
+    minute: '2-digit',
+    ...options,
+  })
+}
+
+function average(values: readonly number[] | undefined): number | null {
+  if (!values?.length) return null
+  const usable = values.filter(value => Number.isFinite(value) && value >= 0)
+  if (usable.length === 0) return null
+  return usable.reduce((sum, value) => sum + value, 0) / usable.length
+}
+
+function coerceDate(value: string | Date | null | undefined): Date | null {
+  if (!value) return null
+  const date = value instanceof Date ? value : new Date(value)
+  return Number.isNaN(date.getTime()) ? null : date
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value))
+}