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

package/src/composables/workspaceRecipes.ts

@@ -0,0 +1,267 @@
+import type { TopBarVariant } from '../types'
+import type { FormEnhancements } from '../types/form-builder'
+import type {
+  ControlModel,
+  ControlModelBinding,
+  ControlSchema,
+  ControlWorkspaceOptions,
+  UseControlWorkspaceReturn,
+} from './useControlSchema'
+import { mergeControlWorkspaceOptions, resolveControlModel } from './useControlSchema'
+
+/**
+ * Merges `initialValues`/external `modelValue`/`values` on top of a base
+ * `ControlWorkspaceOptions.initialValues`, matching the layering FormBuilder expects: base
+ * defaults, then caller-supplied initial values, then live external values win last. Shared by
+ * {@link controlWorkspaceProps} and {@link bioTemplatePresetWorkspaceProps} so both "generate a
+ * workspace from options, initialValues, and v-model" views merge options identically.
+ */
+export function resolveControlOptionsWithExternalValues<TOptions extends ControlWorkspaceOptions>(
+  base: TOptions,
+  initialValues: Record<string, unknown> | undefined,
+  externalValues: Record<string, unknown> | undefined,
+): TOptions {
+  if (initialValues === undefined && externalValues === undefined) return base
+
+  return {
+    ...base,
+    initialValues: {
+      ...(base.initialValues ?? {}),
+      ...(initialValues ?? {}),
+      ...(externalValues ?? {}),
+    },
+  }
+}
+
+export interface ControlWorkspaceModelProps {
+  model?: ControlModel | ControlModelBinding
+  controls?: ControlSchema
+  controlOptions?: ControlWorkspaceOptions
+  initialValues?: Record<string, unknown>
+  modelValue?: Record<string, unknown>
+  values?: Record<string, unknown>
+}
+
+export interface ResolvedControlWorkspaceModel {
+  /** `modelValue` if provided, else `values` — the single external v-model source of truth. */
+  externalValues: Record<string, unknown> | undefined
+  /** `model` resolved through `resolveControlModel()`, or undefined for a raw `controls` schema. */
+  resolvedModel: ControlModelBinding | undefined
+  /** `controls` if provided, else the resolved model's controls, else `{}`. */
+  resolvedControls: ControlSchema
+  /** `controlOptions` merged over the resolved model's own options, with initialValues/external values layered on top. */
+  resolvedControlOptions: ControlWorkspaceOptions
+}
+
+/**
+ * Resolves ControlWorkspaceView's `model`/`controls`/`controlOptions`/`initialValues`/
+ * `modelValue`/`values` props into the schema + options pair `useControlWorkspace()` needs.
+ * Pure and framework-free so callers wrap each field in their own `computed()`.
+ *
+ * @example Recommended
+ * ```ts
+ * const resolved = computed(() => controlWorkspaceProps(props))
+ * const resolvedControls = computed(() => resolved.value.resolvedControls)
+ * ```
+ */
+export function controlWorkspaceProps(props: ControlWorkspaceModelProps): ResolvedControlWorkspaceModel {
+  const externalValues = props.modelValue ?? props.values
+  const resolvedModel = resolveControlModel(props.model)
+  const resolvedControls: ControlSchema = props.controls ?? resolvedModel?.controls ?? {}
+  const baseControlOptions = mergeControlWorkspaceOptions(resolvedModel?.controlOptions, props.controlOptions)
+  const resolvedControlOptions = resolveControlOptionsWithExternalValues(
+    baseControlOptions,
+    props.initialValues,
+    externalValues,
+  )
+
+  return { externalValues, resolvedModel, resolvedControls, resolvedControlOptions }
+}
+
+export interface DoseDesignWorkspacePassthroughProps {
+  workspace?: UseControlWorkspaceReturn<ControlSchema>
+  controlOptions?: ControlWorkspaceOptions
+  initialValues?: Record<string, unknown>
+  modelValue?: Record<string, unknown>
+  values?: Record<string, unknown>
+  title?: string
+  subtitle?: string
+  topBarVariant?: TopBarVariant
+  sidebarWidth?: string
+  sidebarVariant?: 'default' | 'analysis'
+  responsiveSidebar?: boolean
+  sidebarPosition?: 'left' | 'right'
+  sidebarTitle?: string
+  sidebarSubtitle?: string
+  sidebarBadge?: string | number
+  floating?: boolean
+  dense?: boolean
+  showSettings?: boolean
+  showFormActions?: boolean
+  formEnhancements?: FormEnhancements<Record<string, unknown>>
+  formLoading?: boolean
+  formDisabled?: boolean
+  formReadonly?: boolean
+  formSize?: 'sm' | 'md' | 'lg'
+}
+
+/**
+ * Maps DoseDesignWorkspaceView's props straight through to the identically-named
+ * ControlWorkspaceView props it wraps — the ~25-key pass-through list that used to be spelled
+ * out attribute-by-attribute in the template. `model` is the caller's already-resolved dose
+ * design model, not the raw (possibly absent) `props.model`.
+ *
+ * @example Recommended
+ * ```vue
+ * <ControlWorkspaceView v-bind="doseDesignWorkspaceProps(props, resolvedModel)" />
+ * ```
+ */
+export function doseDesignWorkspaceProps(
+  props: DoseDesignWorkspacePassthroughProps,
+  model: ControlModel | ControlModelBinding,
+) {
+  return {
+    model,
+    workspace: props.workspace,
+    controlOptions: props.controlOptions,
+    initialValues: props.initialValues,
+    modelValue: props.modelValue,
+    values: props.values,
+    title: props.title,
+    subtitle: props.subtitle,
+    topBarVariant: props.topBarVariant,
+    sidebarWidth: props.sidebarWidth,
+    sidebarVariant: props.sidebarVariant,
+    responsiveSidebar: props.responsiveSidebar,
+    sidebarPosition: props.sidebarPosition,
+    sidebarTitle: props.sidebarTitle,
+    sidebarSubtitle: props.sidebarSubtitle,
+    sidebarBadge: props.sidebarBadge,
+    floating: props.floating,
+    dense: props.dense,
+    showSettings: props.showSettings,
+    showFormActions: props.showFormActions,
+    formEnhancements: props.formEnhancements,
+    formLoading: props.formLoading,
+    formDisabled: props.formDisabled,
+    formReadonly: props.formReadonly,
+    formSize: props.formSize,
+  }
+}
+
+export interface BioTemplateExperimentWorkspaceStatusProps {
+  status?: {
+    loading?: boolean
+    saving?: boolean
+    error?: string | null
+    hasExperiment?: boolean
+    currentExperimentId?: number
+    lastLoadedAt?: Date | null
+    lastSavedAt?: Date | null
+  }
+  loading?: boolean
+  error?: string | null
+  hasExperiment?: boolean
+  currentExperimentId?: number
+  lastLoadedAt?: Date | null
+  lastSavedAt?: Date | null
+}
+
+export interface ResolvedBioTemplateExperimentStatus {
+  loading: boolean
+  error: string | null | undefined
+  hasExperiment: boolean
+  currentExperimentId: number | undefined
+  lastLoadedAt: Date | null | undefined
+  lastSavedAt: Date | null | undefined
+}
+
+/**
+ * Merges BioTemplateExperimentWorkspaceView's grouped `status` prop over its individual
+ * `loading`/`error`/`hasExperiment`/... props: `status` wins whenever the corresponding field
+ * on it is set, otherwise the flat prop (or its default) is used. Centralizes the six
+ * independent fallback rules generated plugin pages rely on when they pass a request/experiment
+ * `status` object instead of wiring each field by hand.
+ */
+export function bioTemplateExperimentWorkspaceProps(
+  props: BioTemplateExperimentWorkspaceStatusProps,
+): ResolvedBioTemplateExperimentStatus {
+  const status = props.status
+  return {
+    loading: status?.loading !== undefined || status?.saving !== undefined
+      ? Boolean(status?.loading) || Boolean(status?.saving)
+      : Boolean(props.loading),
+    error: status?.error !== undefined ? status.error : props.error,
+    hasExperiment: status?.hasExperiment ?? props.hasExperiment ?? false,
+    currentExperimentId: status?.currentExperimentId ?? props.currentExperimentId,
+    lastLoadedAt: status?.lastLoadedAt !== undefined ? status.lastLoadedAt : props.lastLoadedAt,
+    lastSavedAt: status?.lastSavedAt !== undefined ? status.lastSavedAt : props.lastSavedAt,
+  }
+}
+
+export interface BioTemplatePackWorkspacePassthroughProps {
+  message?: string
+  dense?: boolean
+  readonly?: boolean
+  showStatus?: boolean
+  showTemplateSummary?: boolean
+  loadLabel?: string
+  resetLabel?: string
+  saveLabel?: string
+}
+
+/**
+ * Assembles the prop object BioTemplatePackWorkspaceView binds onto the
+ * BioTemplateExperimentWorkspaceView it wraps: its own display props passed straight through,
+ * plus the pack-derived `target`/`label`/`status`/`actions` computed by the caller.
+ */
+export function bioTemplatePackWorkspaceProps<TTarget, TStatus, TActions>(
+  props: BioTemplatePackWorkspacePassthroughProps,
+  derived: {
+    target: TTarget
+    label: string
+    status: TStatus
+    actions: TActions
+  },
+) {
+  return {
+    target: derived.target,
+    kind: 'collection' as const,
+    label: derived.label,
+    message: props.message,
+    status: derived.status,
+    actions: derived.actions,
+    dense: props.dense,
+    readonly: props.readonly,
+    showStatus: props.showStatus,
+    showTemplateSummary: props.showTemplateSummary,
+    loadLabel: props.loadLabel,
+    resetLabel: props.resetLabel,
+    saveLabel: props.saveLabel,
+  }
+}
+
+export interface BioTemplatePresetWorkspaceOptionsProps<TOptions extends ControlWorkspaceOptions> {
+  workspaceOptions?: TOptions
+  initialValues?: Record<string, unknown>
+  modelValue?: Record<string, unknown>
+  values?: Record<string, unknown>
+}
+
+/**
+ * Resolves BioTemplatePresetWorkspaceView's `workspaceOptions`/`initialValues`/`modelValue`/
+ * `values` props into the single options object `useBioTemplatePresetWorkspace()` needs,
+ * reusing the same base/initialValues/external-values layering as {@link controlWorkspaceProps}.
+ */
+export function bioTemplatePresetWorkspaceProps<TOptions extends ControlWorkspaceOptions>(
+  props: BioTemplatePresetWorkspaceOptionsProps<TOptions>,
+): { externalValues: Record<string, unknown> | undefined; resolvedWorkspaceOptions: TOptions } {
+  const externalValues = props.modelValue ?? props.values
+  const resolvedWorkspaceOptions = resolveControlOptionsWithExternalValues(
+    (props.workspaceOptions ?? {}) as TOptions,
+    props.initialValues,
+    externalValues,
+  )
+
+  return { externalValues, resolvedWorkspaceOptions }
+}

package/src/generated/schema.ts

@@ -0,0 +1,130 @@
+import type {
+  FormFieldSchema,
+  FormFieldType,
+  FormSchema,
+} from '../types/form-builder'
+import type {
+  GeneratedJsonSchema,
+  GeneratedJobDefinition,
+} from '../types/generated-ui'
+
+type GeneratedReference = 'path'
+
+interface ResolvedGeneratedField {
+  schema: GeneratedJsonSchema
+  reference?: GeneratedReference
+  hasDefault: boolean
+  defaultValue?: unknown
+}
+
+export function generatedJobFormSchema(definition: GeneratedJobDefinition): FormSchema & { sections: NonNullable<FormSchema['sections']> } {
+  const root = definition.input_schema
+  const required = new Set(root.required ?? [])
+  const fields = Object.entries(root.properties ?? {}).map(([name, schema]) =>
+    toFormField(name, resolveGeneratedField(root, schema), required.has(name)),
+  )
+  return {
+    sections: [{
+      id: definition.id,
+      title: definition.title,
+      description: definition.description || undefined,
+      columns: 1,
+      fields,
+    }],
+    submitLabel: 'Run analysis',
+  }
+}
+
+export function generatedJobDefaults(definition: GeneratedJobDefinition): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(definition.input_schema.properties ?? {})
+      .filter(([, schema]) => hasOwnDefault(schema))
+      .map(([name, schema]) => [name, structuredClone(schema.default)]),
+  )
+}
+
+export function normalizeGeneratedJobInput(
+  definition: GeneratedJobDefinition,
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  const normalized: Record<string, unknown> = {}
+  for (const [name, value] of Object.entries(values)) {
+    const field = definition.input_schema.properties?.[name]
+    if (!field) continue
+    normalized[name] = value
+  }
+  return normalized
+}
+
+function toFormField(
+  name: string,
+  resolved: ResolvedGeneratedField,
+  required: boolean,
+): FormFieldSchema {
+  const { schema, reference } = resolved
+  const validation: NonNullable<FormFieldSchema['validation']> = {}
+  if (required) validation.required = true
+  if (schema.minimum !== undefined) validation.min = schema.minimum
+  if (schema.maximum !== undefined) validation.max = schema.maximum
+  if (schema.minLength !== undefined) validation.minLength = schema.minLength
+  if (schema.maxLength !== undefined) validation.maxLength = schema.maxLength
+
+  const props: Record<string, unknown> = {}
+  if (schema.enum) props.options = [...schema.enum]
+  if (reference === 'path' && schema.type === 'array') props.multiple = true
+  return {
+    name,
+    label: schema.title || humanize(name),
+    type: fieldType(schema, reference),
+    defaultValue: resolved.hasDefault ? structuredClone(resolved.defaultValue) : undefined,
+    hint: schema.description,
+    validation,
+    props,
+  }
+}
+
+function resolveGeneratedField(
+  root: GeneratedJsonSchema,
+  field: GeneratedJsonSchema,
+): ResolvedGeneratedField {
+  const hasDefault = hasOwnDefault(field)
+  const candidate = field.anyOf?.find(item => item.type !== 'null')
+    ?? field.allOf?.[0]
+    ?? field
+  if (candidate.$ref) {
+    const referenceParts = candidate.$ref.split('/')
+    const key = referenceParts[referenceParts.length - 1]
+    const schema = key ? root.$defs?.[key] : undefined
+    if (!schema) throw new Error(`Generated field reference is missing: ${candidate.$ref}`)
+    return {
+      schema: { ...schema, title: field.title ?? schema.title },
+      reference: field['x-mint-component'] ?? schema['x-mint-component'],
+      hasDefault,
+      defaultValue: field.default,
+    }
+  }
+  return {
+    schema: candidate,
+    reference: field['x-mint-component'] ?? candidate['x-mint-component'],
+    hasDefault,
+    defaultValue: field.default,
+  }
+}
+
+function fieldType(schema: GeneratedJsonSchema, reference?: GeneratedReference): FormFieldType {
+  if (reference === 'path') return 'path'
+  if (schema.enum) return 'select'
+  const type = Array.isArray(schema.type) ? schema.type.find(value => value !== 'null') : schema.type
+  if (type === 'boolean') return 'toggle'
+  if (type === 'number' || type === 'integer') return 'number'
+  if (type === 'array') return 'tags'
+  return 'text'
+}
+
+function hasOwnDefault(schema: GeneratedJsonSchema): boolean {
+  return Object.prototype.hasOwnProperty.call(schema, 'default')
+}
+
+function humanize(value: string): string {
+  return value.replace(/[_-]+/g, ' ').replace(/^\w/, character => character.toUpperCase())
+}

package/src/generated-ui/main.ts

@@ -0,0 +1,21 @@
+import { createPinia } from 'pinia'
+import { createApp, h } from 'vue'
+
+import GeneratedPluginView from '../components/GeneratedPluginView.vue'
+import '../styles/index.css'
+
+function generatedApiBase(location: Location): string {
+  const pluginPath = new URL('.', location.href).pathname.replace(/\/$/, '')
+  return `/api${pluginPath}`
+}
+
+const app = createApp({
+  name: 'MintGeneratedUiApp',
+  render: () => h(GeneratedPluginView, {
+    baseUrl: generatedApiBase(window.location),
+    showStandaloneLabel: true,
+  }),
+})
+
+app.use(createPinia())
+app.mount('#app')

package/src/histoire.setup.ts

@@ -0,0 +1,17 @@
+import { defineSetupVue3 } from '@histoire/plugin-vue'
+import { createPinia } from 'pinia'
+import './styles/index.css'
+
+export const setupVue3 = defineSetupVue3(({ app }) => {
+  app.use(createPinia())
+
+  // Sync Histoire dark mode toggle to html.dark class (drives CSS variables)
+  if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+    const mq = window.matchMedia('(prefers-color-scheme: dark)')
+    const sync = (dark: boolean) => {
+      document.documentElement.classList.toggle('dark', dark)
+    }
+    sync(mq.matches)
+    mq.addEventListener('change', (e) => sync(e.matches))
+  }
+})

package/src/index.ts

@@ -0,0 +1,83 @@
+// Styles (import to ensure bundling)
+import './styles/index.css'
+
+// Vue Plugin for global component registration
+export { MINTSdk, default } from './install'
+
+// Components
+export * from './components'
+
+// Composables
+export * from './composables'
+// Resolve names shared by composables and templates so root exports stay unambiguous.
+export {
+  getBioTemplateComponentProps,
+  toBioTemplateComponentPropsByComponent,
+  type ControlDefinition,
+} from './composables'
+
+// Stores
+export * from './stores'
+
+// Permissions
+export * from './permissions'
+
+// Instrument monitoring
+export * from './instrument'
+
+// Job state helpers
+export * from './jobs'
+
+// Experimental generated analysis workspace
+export * from './generated/schema'
+
+// LCMS sequence helpers
+export * from './lcms'
+
+// Utils
+export {
+  hexToHsl,
+  hslToHex,
+  deriveShade,
+  type Hsl,
+} from './utils/color'
+export {
+  PLUGIN_SECRET_FORMAT_KEY,
+  PLUGIN_SECRET_FORMAT_REF,
+  PLUGIN_SECRET_REF_KEY,
+  clearPluginSecret,
+  isPluginSecretLocked,
+  isPluginSecretRef,
+  keepPluginSecret,
+  pluginSecretId,
+  pluginSecretLabel,
+  pluginSecretState,
+  setPluginSecret,
+  usesPluginSecretReferences,
+  type PluginSecretRef,
+  type PluginSecretState,
+} from './utils/pluginSecrets'
+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'
+
+// Types
+export type * from './types'

package/src/install.ts

@@ -0,0 +1,39 @@
+import * as components from './components'
+
+type ComponentRegistryApp = {
+  component: (name: string, component: any) => unknown
+}
+
+export interface MINTSdkPlugin {
+  install(app: ComponentRegistryApp): void
+}
+
+/**
+ * Vue plugin that registers all MINT SDK components globally.
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from 'vue'
+ * import { MINTSdk } from '@morscherlab/mint-sdk'
+ * import '@morscherlab/mint-sdk/styles'
+ *
+ * const app = createApp(App)
+ * app.use(MINTSdk)
+ * ```
+ */
+export const MINTSdk: MINTSdkPlugin = {
+  install(app) {
+    for (const [name, component] of Object.entries(components)) {
+      // Check if it's a valid Vue component (has setup, render, or template)
+      if (
+        component &&
+        typeof component === 'object' &&
+        ('setup' in component || 'render' in component || '__name' in component)
+      ) {
+        app.component(name, component)
+      }
+    }
+  },
+}
+
+export default MINTSdk

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))
+}