@morscherlab/mint-sdk 1.0.13 → 1.0.14

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

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  coordinateToWellId,
+  useWellPainting,
+  wellIdToCoordinate,
+  wellIdsInRectangle,
+} from '../../composables/useWellPainting'
+
+describe('useWellPainting', () => {
+  it('converts well coordinates and computes rectangle selections', () => {
+    expect(wellIdToCoordinate('B2')).toEqual({ row: 1, col: 1 })
+    expect(coordinateToWellId({ row: 0, col: 0 })).toBe('A1')
+    expect(wellIdsInRectangle({ row: 0, col: 0 }, { row: 1, col: 1 }, 96)).toEqual([
+      'A1',
+      'A2',
+      'B1',
+      'B2',
+    ])
+  })
+
+  it('emits rectangle selections in select mode', () => {
+    const completed: string[][] = []
+    const painting = useWellPainting({
+      format: 96,
+      initialMode: 'select',
+      onComplete: result => completed.push(result.wellIds),
+    })
+
+    painting.onWellMouseDown('A1')
+    painting.onWellMouseMove('B2')
+    expect(painting.previewWellIds.value).toEqual(['A1', 'A2', 'B1', 'B2'])
+    painting.onWellMouseUp()
+
+    expect(completed).toEqual([['A1', 'A2', 'B1', 'B2']])
+  })
+
+  it('tracks paint trails for non-select modes', () => {
+    const completed: { mode: string; wells: string[] }[] = []
+    const painting = useWellPainting({
+      format: 96,
+      initialMode: 'paint',
+      onComplete: result => completed.push({ mode: result.mode, wells: result.wellIds }),
+    })
+
+    painting.onWellMouseDown('A1')
+    painting.onWellMouseMove('A3')
+    painting.onWellMouseUp()
+
+    expect(completed).toEqual([{ mode: 'paint', wells: ['A1', 'A3'] }])
+  })
+})

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

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  createColumnConditions,
+  createRowConditions,
+  createWellPlateWells,
+} from '../../composables/useWellPlateAdapter'
+
+describe('well plate adapter helpers', () => {
+  it('maps domain entries to WellPlate wells', () => {
+    const wells = createWellPlateWells(
+      [{ id: 'B3', type: 'sample', signal: 42 }],
+      {
+        getWellId: entry => entry.id,
+        getSampleType: entry => entry.type,
+        getValue: entry => entry.signal,
+        getMetadata: () => ({ source: 'analysis' }),
+      },
+    )
+
+    expect(wells.B3).toEqual({
+      id: 'B3',
+      row: 1,
+      col: 2,
+      state: 'filled',
+      sampleType: 'sample',
+      value: 42,
+      metadata: { source: 'analysis' },
+    })
+  })
+
+  it('builds row and column condition spans from axis entries', () => {
+    const entry = {
+      label: 'Drug A',
+      color: '#123456',
+      start: 2,
+      unit: 'uM',
+      concentrations: [{ value: 1, replicates: 2 }, { value: 10 }],
+    }
+
+    expect(createColumnConditions([entry])[0]).toMatchObject({
+      cols: [2, 3, 4],
+      concentrations: [1, 1, 10],
+    })
+    expect(createRowConditions([{ ...entry, start: 'B' }])[0]).toMatchObject({
+      rows: ['B', 'C', 'D'],
+      concentrations: [1, 1, 10],
+    })
+  })
+})

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

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+
+import { runWellPlateValidation, useWellPlateValidation } from '../../composables/useWellPlateValidation'
+
+describe('well plate validation helpers', () => {
+  it('runs rule-driven validation', () => {
+    const warnings = runWellPlateValidation(
+      { assigned: 0 },
+      [
+        {
+          type: 'empty',
+          severity: 'warning',
+          validate: context => context.assigned === 0 && 'No wells assigned',
+        },
+      ],
+    )
+
+    expect(warnings).toEqual([
+      { type: 'empty', severity: 'warning', message: 'No wells assigned' },
+    ])
+  })
+
+  it('derives blocking state and counts', () => {
+    const validation = useWellPlateValidation({
+      context: { overlaps: ['A1'] },
+      rules: [
+        {
+          type: 'overlap',
+          severity: 'error',
+          validate: context => ({
+            message: `${context.overlaps.length} overlap`,
+            affectedWells: context.overlaps,
+          }),
+        },
+      ],
+    })
+
+    expect(validation.hasBlockingIssues.value).toBe(true)
+    expect(validation.errorCount.value).toBe(1)
+    expect(validation.warningCount.value).toBe(1)
+  })
+})

package/src/components/PluginWorkspaceView.vue

@@ -37,10 +37,10 @@ const props = withDefaults(defineProps<PluginWorkspaceViewProps>(), {
   pluginSwitcher: undefined,
   pillNav: undefined,
   currentPillId: undefined,
-  showThemeToggle: false,
-  showSettings: false,
+  showThemeToggle: true,
+  showSettings: true,
   settingsConfig: undefined,
-  showStandaloneLabel: true,
+  showStandaloneLabel: false,
   standaloneLabel: 'Standalone',
   accountMenu: undefined,
   showNotifications: false,

package/src/composables/index.ts

@@ -191,6 +191,41 @@ export {
   type RequestSyncSuccessKind,
   type UseRequestSyncStateReturn,
 } from './useRequestSyncState'
+export {
+  useCommandHistory,
+  type CommandHistoryCommand,
+  type CommandHistoryExecuteOptions,
+  type CommandHistoryResult,
+  type UseCommandHistoryOptions,
+  type UseCommandHistoryReturn,
+} from './useCommandHistory'
+export {
+  useOptimisticMutation,
+  type OptimisticMutationContext,
+  type UseOptimisticMutationOptions,
+  type UseOptimisticMutationReturn,
+} from './useOptimisticMutation'
+export {
+  createPluginResourceClient,
+  useResourceCrud,
+  type PluginResourceClientOptions,
+  type ResourceCrudAdapter,
+  type ResourceKey,
+  type UseResourceCrudOptions,
+  type UseResourceCrudReturn,
+} from './useResourceCrud'
+export {
+  detectDelimiter,
+  parseDelimitedText,
+  readFileAsText,
+  useFileImport,
+  validateImportFile,
+  type DelimitedTable,
+  type FileImportOptions,
+  type FileImportValidationOptions,
+  type ParseDelimitedTextOptions,
+  type UseFileImportReturn,
+} from './useFileImport'
 export {
   useSelectionLimit,
   type SelectionLimitSource,
@@ -248,6 +283,38 @@ export {
   type UseTextSearchOptions,
   type UseTextSearchReturn,
 } from './useTextSearch'
+export {
+  coordinateToWellId,
+  useWellPainting,
+  wellIdToCoordinate,
+  wellIdsInRectangle,
+  type UseWellPaintingOptions,
+  type UseWellPaintingReturn,
+  type WellCoordinate,
+  type WellPaintResult,
+  type WellPlateSource,
+} from './useWellPainting'
+export {
+  createColumnConditions,
+  createRowConditions,
+  createWellPlateWells,
+  useWellPlateAdapter,
+  type AxisConditionEntry,
+  type UseWellPlateAdapterReturn,
+  type WellPlateAdapterOptions,
+  type WellPlateAdapterSource,
+  type WellPlateEntry,
+} from './useWellPlateAdapter'
+export {
+  runWellPlateValidation,
+  useWellPlateValidation,
+  type UseWellPlateValidationOptions,
+  type UseWellPlateValidationReturn,
+  type WellPlateValidationRule,
+  type WellPlateValidationSeverity,
+  type WellPlateValidationSource,
+  type WellPlateValidationWarning,
+} from './useWellPlateValidation'
 export {
   controlsToFormSchema,
   controlsToSectionFormSchema,

package/src/composables/useCommandHistory.ts

@@ -0,0 +1,113 @@
+import { computed, ref, type ComputedRef, type Ref } from 'vue'
+
+export type CommandHistoryResult = void | Promise<void>
+
+export interface CommandHistoryCommand {
+  execute: () => CommandHistoryResult
+  undo: () => CommandHistoryResult
+  redo?: () => CommandHistoryResult
+  description?: string
+}
+
+export interface CommandHistoryExecuteOptions {
+  skipExecute?: boolean
+}
+
+export interface UseCommandHistoryOptions {
+  maxDepth?: number
+}
+
+export interface UseCommandHistoryReturn<TCommand extends CommandHistoryCommand = CommandHistoryCommand> {
+  undoStack: Ref<TCommand[]>
+  redoStack: Ref<TCommand[]>
+  canUndo: ComputedRef<boolean>
+  canRedo: ComputedRef<boolean>
+  undoDescription: ComputedRef<string>
+  redoDescription: ComputedRef<string>
+  execute: (command: TCommand, options?: CommandHistoryExecuteOptions) => CommandHistoryResult
+  push: (command: TCommand) => void
+  undo: () => CommandHistoryResult
+  redo: () => CommandHistoryResult
+  clear: () => void
+}
+
+/** Generic command-stack state for plugin editors with undo/redo controls. */
+export function useCommandHistory<TCommand extends CommandHistoryCommand = CommandHistoryCommand>(
+  options: UseCommandHistoryOptions = {},
+): UseCommandHistoryReturn<TCommand> {
+  const maxDepth = Math.max(1, options.maxDepth ?? 50)
+  const undoStack = ref<TCommand[]>([]) as Ref<TCommand[]>
+  const redoStack = ref<TCommand[]>([]) as Ref<TCommand[]>
+
+  const canUndo = computed(() => undoStack.value.length > 0)
+  const canRedo = computed(() => redoStack.value.length > 0)
+  const undoDescription = computed(() => undoStack.value[undoStack.value.length - 1]?.description ?? '')
+  const redoDescription = computed(() => redoStack.value[redoStack.value.length - 1]?.description ?? '')
+
+  function push(command: TCommand): void {
+    undoStack.value = [...undoStack.value.slice(-(maxDepth - 1)), command]
+    redoStack.value = []
+  }
+
+  function execute(
+    command: TCommand,
+    executeOptions: CommandHistoryExecuteOptions = {},
+  ): CommandHistoryResult {
+    if (executeOptions.skipExecute) {
+      push(command)
+      return
+    }
+
+    return afterMaybePromise(command.execute(), () => push(command))
+  }
+
+  function undo(): CommandHistoryResult {
+    const command = undoStack.value[undoStack.value.length - 1]
+    if (!command) return
+
+    return afterMaybePromise(command.undo(), () => {
+      undoStack.value = undoStack.value.slice(0, -1)
+      redoStack.value = [...redoStack.value, command]
+    })
+  }
+
+  function redo(): CommandHistoryResult {
+    const command = redoStack.value[redoStack.value.length - 1]
+    if (!command) return
+
+    return afterMaybePromise((command.redo ?? command.execute)(), () => {
+      redoStack.value = redoStack.value.slice(0, -1)
+      undoStack.value = [...undoStack.value.slice(-(maxDepth - 1)), command]
+    })
+  }
+
+  function clear(): void {
+    undoStack.value = []
+    redoStack.value = []
+  }
+
+  return {
+    undoStack,
+    redoStack,
+    canUndo,
+    canRedo,
+    undoDescription,
+    redoDescription,
+    execute,
+    push,
+    undo,
+    redo,
+    clear,
+  }
+}
+
+function afterMaybePromise(result: CommandHistoryResult, callback: () => void): CommandHistoryResult {
+  if (isPromiseLike(result)) {
+    return result.then(callback)
+  }
+  callback()
+}
+
+function isPromiseLike(value: unknown): value is Promise<void> {
+  return !!value && typeof (value as { then?: unknown }).then === 'function'
+}

package/src/composables/useFileImport.ts

@@ -0,0 +1,231 @@
+import { ref, shallowRef, type Ref, type ShallowRef } from 'vue'
+
+export interface DelimitedTable {
+  columns: string[]
+  rows: Record<string, string>[]
+  rawRows: string[][]
+  delimiter: string
+}
+
+export interface ParseDelimitedTextOptions {
+  delimiter?: string
+  headers?: readonly string[]
+  hasHeaderRow?: boolean
+  trim?: boolean
+}
+
+export interface FileImportValidationOptions {
+  accept?: string | readonly string[]
+  maxSizeBytes?: number
+}
+
+export interface FileImportOptions<TResult = string> extends FileImportValidationOptions {
+  encoding?: string
+  parse?: (text: string, file: File) => TResult | Promise<TResult>
+}
+
+export interface UseFileImportReturn<TResult> {
+  loading: ShallowRef<boolean>
+  error: Ref<string | null>
+  fileName: Ref<string>
+  result: Ref<TResult | null>
+  importFile: (file: File) => Promise<TResult>
+  clear: () => void
+}
+
+/** Stateful file reader for plugin import flows with shared validation and error handling. */
+export function useFileImport<TResult = string>(
+  options: FileImportOptions<TResult> = {},
+): UseFileImportReturn<TResult> {
+  const loading = shallowRef(false)
+  const error = ref<string | null>(null)
+  const fileName = ref('')
+  const result = ref<TResult | null>(null) as Ref<TResult | null>
+
+  function clear(): void {
+    loading.value = false
+    error.value = null
+    fileName.value = ''
+    result.value = null
+  }
+
+  async function importFile(file: File): Promise<TResult> {
+    loading.value = true
+    error.value = null
+    fileName.value = file.name
+
+    try {
+      validateImportFile(file, options)
+      const text = await readFileAsText(file, options.encoding)
+      const parsed = options.parse
+        ? await options.parse(text, file)
+        : text as TResult
+      result.value = parsed
+      return parsed
+    } catch (err) {
+      const message = readErrorMessage(err)
+      error.value = message
+      throw err
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return {
+    loading,
+    error,
+    fileName,
+    result,
+    importFile,
+    clear,
+  }
+}
+
+export function validateImportFile(file: File, options: FileImportValidationOptions = {}): void {
+  if (options.maxSizeBytes !== undefined && file.size > options.maxSizeBytes) {
+    throw new Error(`File is too large. Maximum size is ${formatBytes(options.maxSizeBytes)}.`)
+  }
+
+  const accept = normalizeAccept(options.accept)
+  if (accept.length === 0) return
+
+  const name = file.name.toLowerCase()
+  const type = file.type.toLowerCase()
+  const matches = accept.some((entry) => {
+    if (entry.startsWith('.')) return name.endsWith(entry)
+    if (entry.endsWith('/*')) return type.startsWith(entry.slice(0, -1))
+    return type === entry
+  })
+
+  if (!matches) {
+    throw new Error(`Unsupported file type. Expected ${accept.join(', ')}.`)
+  }
+}
+
+export function readFileAsText(file: File, encoding?: string): Promise<string> {
+  if (typeof FileReader === 'undefined' && typeof file.text === 'function') {
+    return file.text()
+  }
+
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onload = () => resolve(String(reader.result ?? ''))
+    reader.onerror = () => reject(reader.error ?? new Error('Failed to read file.'))
+    reader.readAsText(file, encoding)
+  })
+}
+
+export function parseDelimitedText(
+  text: string,
+  options: ParseDelimitedTextOptions = {},
+): DelimitedTable {
+  const trim = options.trim ?? true
+  const delimiter = options.delimiter ?? detectDelimiter(text)
+  const rawRows = parseDelimitedRows(text, delimiter)
+    .filter(row => row.some(cell => cell.trim().length > 0))
+    .map(row => trim ? row.map(cell => cell.trim()) : row)
+
+  const hasHeaderRow = options.hasHeaderRow ?? !options.headers
+  const columns = options.headers
+    ? [...options.headers]
+    : hasHeaderRow
+      ? rawRows[0] ?? []
+      : createColumnNames(maxRowLength(rawRows))
+
+  const dataRows = hasHeaderRow && !options.headers ? rawRows.slice(1) : rawRows
+  const rows = dataRows.map(row => Object.fromEntries(
+    columns.map((column, index) => [column, row[index] ?? '']),
+  ))
+
+  return {
+    columns,
+    rows,
+    rawRows,
+    delimiter,
+  }
+}
+
+export function detectDelimiter(text: string): string {
+  const firstLine = text.split(/\r?\n/, 1)[0] ?? ''
+  const commaCount = countChar(firstLine, ',')
+  const tabCount = countChar(firstLine, '\t')
+  const semicolonCount = countChar(firstLine, ';')
+  if (tabCount > commaCount && tabCount >= semicolonCount) return '\t'
+  if (semicolonCount > commaCount) return ';'
+  return ','
+}
+
+function parseDelimitedRows(text: string, delimiter: string): string[][] {
+  const rows: string[][] = []
+  let row: string[] = []
+  let field = ''
+  let quoted = false
+
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index]
+    const next = text[index + 1]
+
+    if (char === '"') {
+      if (quoted && next === '"') {
+        field += '"'
+        index++
+      } else {
+        quoted = !quoted
+      }
+      continue
+    }
+
+    if (!quoted && char === delimiter) {
+      row.push(field)
+      field = ''
+      continue
+    }
+
+    if (!quoted && (char === '\n' || char === '\r')) {
+      if (char === '\r' && next === '\n') index++
+      row.push(field)
+      rows.push(row)
+      row = []
+      field = ''
+      continue
+    }
+
+    field += char
+  }
+
+  row.push(field)
+  rows.push(row)
+  return rows
+}
+
+function normalizeAccept(accept: string | readonly string[] | undefined): string[] {
+  if (!accept) return []
+  const entries = typeof accept === 'string' ? accept.split(',') : [...accept]
+  return entries
+    .map((entry: string) => entry.trim().toLowerCase())
+    .filter(Boolean)
+}
+
+function createColumnNames(count: number): string[] {
+  return Array.from({ length: count }, (_, index) => `column_${index + 1}`)
+}
+
+function maxRowLength(rows: readonly string[][]): number {
+  return rows.reduce((max, row) => Math.max(max, row.length), 0)
+}
+
+function countChar(value: string, char: string): number {
+  return [...value].filter(candidate => candidate === char).length
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
+  return `${Math.round(bytes / (1024 * 1024))} MB`
+}
+
+function readErrorMessage(value: unknown): string {
+  if (value instanceof Error && value.message) return value.message
+  if (typeof value === 'string' && value.trim()) return value
+  return 'Failed to import file.'
+}

package/src/composables/useOptimisticMutation.ts

@@ -0,0 +1,107 @@
+import { computed, ref, shallowRef, type ComputedRef, type Ref, type ShallowRef } from 'vue'
+
+export interface OptimisticMutationContext<TVariables, TSnapshot> {
+  variables: TVariables
+  snapshot: TSnapshot | undefined
+}
+
+export interface UseOptimisticMutationOptions<TVariables, TData, TSnapshot = unknown> {
+  mutation: (variables: TVariables) => Promise<TData>
+  snapshot?: (variables: TVariables) => TSnapshot
+  apply?: (variables: TVariables, snapshot: TSnapshot | undefined) => void
+  commit?: (data: TData, context: OptimisticMutationContext<TVariables, TSnapshot>) => void
+  rollback?: (
+    snapshot: TSnapshot | undefined,
+    variables: TVariables,
+    error: unknown,
+  ) => void
+  onSuccess?: (data: TData, context: OptimisticMutationContext<TVariables, TSnapshot>) => void
+  onError?: (error: unknown, context: OptimisticMutationContext<TVariables, TSnapshot>) => void
+  onSettled?: (context: OptimisticMutationContext<TVariables, TSnapshot>) => void
+  readErrorMessage?: (error: unknown) => string
+}
+
+export interface UseOptimisticMutationReturn<TVariables, TData, TSnapshot = unknown> {
+  loading: ShallowRef<boolean>
+  error: Ref<string | null>
+  data: Ref<TData | null>
+  lastSnapshot: Ref<TSnapshot | undefined>
+  isIdle: ComputedRef<boolean>
+  run: (variables: TVariables) => Promise<TData>
+  clearError: () => void
+  reset: () => void
+}
+
+/** Run async mutations with optional optimistic local updates and rollback. */
+export function useOptimisticMutation<TVariables, TData, TSnapshot = unknown>(
+  options: UseOptimisticMutationOptions<TVariables, TData, TSnapshot>,
+): UseOptimisticMutationReturn<TVariables, TData, TSnapshot> {
+  const loading = shallowRef(false)
+  const error = ref<string | null>(null)
+  const data = ref<TData | null>(null) as Ref<TData | null>
+  const lastSnapshot = ref<TSnapshot | undefined>(undefined) as Ref<TSnapshot | undefined>
+  const isIdle = computed(() => !loading.value && data.value === null && error.value === null)
+
+  function clearError(): void {
+    error.value = null
+  }
+
+  function reset(): void {
+    loading.value = false
+    error.value = null
+    data.value = null
+    lastSnapshot.value = undefined
+  }
+
+  async function run(variables: TVariables): Promise<TData> {
+    const snapshot = options.snapshot?.(variables)
+    const context: OptimisticMutationContext<TVariables, TSnapshot> = { variables, snapshot }
+
+    loading.value = true
+    error.value = null
+    lastSnapshot.value = snapshot
+    options.apply?.(variables, snapshot)
+
+    try {
+      const result = await options.mutation(variables)
+      data.value = result
+      options.commit?.(result, context)
+      options.onSuccess?.(result, context)
+      return result
+    } catch (err) {
+      options.rollback?.(snapshot, variables, err)
+      error.value = options.readErrorMessage?.(err) ?? readErrorMessage(err)
+      options.onError?.(err, context)
+      throw err
+    } finally {
+      loading.value = false
+      options.onSettled?.(context)
+    }
+  }
+
+  return {
+    loading,
+    error,
+    data,
+    lastSnapshot,
+    isIdle,
+    run,
+    clearError,
+    reset,
+  }
+}
+
+function readErrorMessage(value: unknown): string {
+  if (value instanceof Error && value.message) return value.message
+  if (typeof value === 'string' && value.trim()) return value
+  if (
+    typeof value === 'object'
+    && value !== null
+    && 'message' in value
+    && typeof (value as { message?: unknown }).message === 'string'
+    && (value as { message: string }).message.trim()
+  ) {
+    return (value as { message: string }).message
+  }
+  return 'Request failed.'
+}