@morscherlab/mint-sdk 1.0.13 → 1.0.15

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.'
+}

package/src/composables/useResourceCrud.ts

@@ -0,0 +1,245 @@
+import { computed, ref, shallowRef, type ComputedRef, type Ref, type ShallowRef } from 'vue'
+
+export type ResourceKey = string | number
+
+export interface ResourceCrudAdapter<TItem, TCreate = Partial<TItem>, TUpdate = Partial<TItem>, TKey extends ResourceKey = ResourceKey> {
+  list: () => Promise<TItem[]>
+  create?: (payload: TCreate) => Promise<TItem>
+  update?: (key: TKey, payload: TUpdate) => Promise<TItem>
+  remove?: (key: TKey) => Promise<void>
+}
+
+export interface UseResourceCrudOptions<
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+> {
+  adapter: ResourceCrudAdapter<TItem, TCreate, TUpdate, TKey>
+  initialItems?: readonly TItem[]
+  getKey?: (item: TItem) => TKey
+  readErrorMessage?: (error: unknown) => string
+}
+
+export interface UseResourceCrudReturn<TItem, TCreate, TUpdate, TKey extends ResourceKey> {
+  items: Ref<TItem[]>
+  loading: ShallowRef<boolean>
+  saving: ShallowRef<boolean>
+  deleting: ShallowRef<boolean>
+  error: Ref<string | null>
+  isBusy: ComputedRef<boolean>
+  load: () => Promise<TItem[]>
+  createItem: (payload: TCreate) => Promise<TItem>
+  updateItem: (key: TKey, payload: TUpdate) => Promise<TItem>
+  deleteItem: (keyOrItem: TKey | TItem) => Promise<void>
+  setItems: (items: readonly TItem[]) => void
+  upsertLocal: (item: TItem) => void
+  removeLocal: (keyOrItem: TKey | TItem) => void
+  clearError: () => void
+}
+
+/** Common list/create/update/delete state wrapper for generated plugin clients. */
+export function useResourceCrud<
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+>(
+  options: UseResourceCrudOptions<TItem, TCreate, TUpdate, TKey>,
+): UseResourceCrudReturn<TItem, TCreate, TUpdate, TKey> {
+  const items = ref<TItem[]>([...(options.initialItems ?? [])]) as Ref<TItem[]>
+  const loading = shallowRef(false)
+  const saving = shallowRef(false)
+  const deleting = shallowRef(false)
+  const error = ref<string | null>(null)
+  const isBusy = computed(() => loading.value || saving.value || deleting.value)
+
+  const readMessage = options.readErrorMessage ?? readErrorMessage
+  const getKey = options.getKey ?? defaultGetKey<TKey, TItem>
+
+  function clearError(): void {
+    error.value = null
+  }
+
+  function setError(err: unknown): void {
+    error.value = readMessage(err)
+  }
+
+  function setItems(nextItems: readonly TItem[]): void {
+    items.value = [...nextItems]
+  }
+
+  function upsertLocal(item: TItem): void {
+    const key = getKey(item)
+    const index = items.value.findIndex(existing => getKey(existing) === key)
+    if (index === -1) {
+      items.value = [...items.value, item]
+      return
+    }
+    items.value = [
+      ...items.value.slice(0, index),
+      item,
+      ...items.value.slice(index + 1),
+    ]
+  }
+
+  function removeLocal(keyOrItem: TKey | TItem): void {
+    const key = resolveKey(keyOrItem, getKey)
+    items.value = items.value.filter(item => getKey(item) !== key)
+  }
+
+  async function load(): Promise<TItem[]> {
+    loading.value = true
+    clearError()
+    try {
+      const result = await options.adapter.list()
+      setItems(result)
+      return result
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function createItem(payload: TCreate): Promise<TItem> {
+    if (!options.adapter.create) {
+      throw new Error('[MINT SDK] Resource adapter does not implement create().')
+    }
+    saving.value = true
+    clearError()
+    try {
+      const result = await options.adapter.create(payload)
+      upsertLocal(result)
+      return result
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      saving.value = false
+    }
+  }
+
+  async function updateItem(key: TKey, payload: TUpdate): Promise<TItem> {
+    if (!options.adapter.update) {
+      throw new Error('[MINT SDK] Resource adapter does not implement update().')
+    }
+    saving.value = true
+    clearError()
+    try {
+      const result = await options.adapter.update(key, payload)
+      upsertLocal(result)
+      return result
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      saving.value = false
+    }
+  }
+
+  async function deleteItem(keyOrItem: TKey | TItem): Promise<void> {
+    if (!options.adapter.remove) {
+      throw new Error('[MINT SDK] Resource adapter does not implement remove().')
+    }
+    const key = resolveKey(keyOrItem, getKey)
+    deleting.value = true
+    clearError()
+    try {
+      await options.adapter.remove(key)
+      removeLocal(key)
+    } catch (err) {
+      setError(err)
+      throw err
+    } finally {
+      deleting.value = false
+    }
+  }
+
+  return {
+    items,
+    loading,
+    saving,
+    deleting,
+    error,
+    isBusy,
+    load,
+    createItem,
+    updateItem,
+    deleteItem,
+    setItems,
+    upsertLocal,
+    removeLocal,
+    clearError,
+  }
+}
+
+export interface PluginResourceClientOptions<
+  TClient,
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+> {
+  client: TClient
+  list: (client: TClient) => Promise<TItem[]>
+  create?: (client: TClient, payload: TCreate) => Promise<TItem>
+  update?: (client: TClient, key: TKey, payload: TUpdate) => Promise<TItem>
+  remove?: (client: TClient, key: TKey) => Promise<void>
+}
+
+export function createPluginResourceClient<
+  TClient,
+  TItem,
+  TCreate = Partial<TItem>,
+  TUpdate = Partial<TItem>,
+  TKey extends ResourceKey = ResourceKey,
+>(
+  options: PluginResourceClientOptions<TClient, TItem, TCreate, TUpdate, TKey>,
+): ResourceCrudAdapter<TItem, TCreate, TUpdate, TKey> {
+  return {
+    list: () => options.list(options.client),
+    create: options.create
+      ? payload => options.create!(options.client, payload)
+      : undefined,
+    update: options.update
+      ? (key, payload) => options.update!(options.client, key, payload)
+      : undefined,
+    remove: options.remove
+      ? key => options.remove!(options.client, key)
+      : undefined,
+  }
+}
+
+function defaultGetKey<TKey extends ResourceKey, TItem>(item: TItem): TKey {
+  if (item && typeof item === 'object' && 'id' in item) {
+    return (item as { id: ResourceKey }).id as TKey
+  }
+  throw new Error('[MINT SDK] Resource items need an id field or a getKey option.')
+}
+
+function resolveKey<TItem, TKey extends ResourceKey>(
+  keyOrItem: TKey | TItem,
+  getKey: (item: TItem) => TKey,
+): TKey {
+  if (typeof keyOrItem === 'string' || typeof keyOrItem === 'number') {
+    return keyOrItem as TKey
+  }
+  return getKey(keyOrItem as TItem)
+}
+
+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.'
+}

package/src/composables/useWellPainting.ts

@@ -0,0 +1,187 @@
+import { computed, ref, toValue, type ComputedRef, type Ref } from 'vue'
+import type { WellPlateFormat } from '../types'
+
+export type WellPlateSource<T> = T | Ref<T> | ComputedRef<T> | (() => T)
+
+export interface WellCoordinate {
+  row: number
+  col: number
+}
+
+export interface WellPaintResult<TMode extends string = string, TPayload = unknown> {
+  wellIds: string[]
+  mode: TMode
+  payload?: TPayload
+}
+
+export interface UseWellPaintingOptions<TMode extends string = string, TPayload = unknown> {
+  format: WellPlateSource<WellPlateFormat>
+  initialMode?: TMode
+  initialPayload?: TPayload
+  onComplete?: (result: WellPaintResult<TMode, TPayload>) => void
+}
+
+export interface UseWellPaintingReturn<TMode extends string = string, TPayload = unknown> {
+  activeMode: Ref<TMode>
+  activePayload: Ref<TPayload | undefined>
+  isDragging: Ref<boolean>
+  previewWellIds: ComputedRef<string[]>
+  setMode: (mode: TMode, payload?: TPayload) => void
+  setPayload: (payload: TPayload | undefined) => void
+  onWellMouseDown: (wellId: string) => void
+  onWellMouseMove: (wellId: string) => void
+  onWellMouseUp: () => void
+  cancel: () => void
+}
+
+const ROW_LABELS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+
+const PLATE_DIMENSIONS: Record<WellPlateFormat, { rows: number; cols: number }> = {
+  6: { rows: 2, cols: 3 },
+  12: { rows: 3, cols: 4 },
+  24: { rows: 4, cols: 6 },
+  48: { rows: 6, cols: 8 },
+  54: { rows: 6, cols: 9 },
+  96: { rows: 8, cols: 12 },
+  384: { rows: 16, cols: 24 },
+}
+
+/** Pointer painting/rectangle selection state for WellPlate-based editors. */
+export function useWellPainting<TMode extends string = string, TPayload = unknown>(
+  options: UseWellPaintingOptions<TMode, TPayload>,
+): UseWellPaintingReturn<TMode, TPayload> {
+  const activeMode = ref<TMode>(options.initialMode ?? 'select' as TMode) as Ref<TMode>
+  const activePayload = ref<TPayload | undefined>(options.initialPayload) as Ref<TPayload | undefined>
+  const isDragging = ref(false)
+  const dragStart = ref<WellCoordinate | null>(null)
+  const dragEnd = ref<WellCoordinate | null>(null)
+  const paintTrail = ref<Set<string>>(new Set())
+
+  const previewWellIds = computed(() => {
+    if (!isDragging.value) return []
+    if (activeMode.value === 'select') {
+      if (!dragStart.value || !dragEnd.value) return []
+      return wellIdsInRectangle(dragStart.value, dragEnd.value, toValue(options.format))
+    }
+    return [...paintTrail.value]
+  })
+
+  function setMode(mode: TMode, payload?: TPayload): void {
+    activeMode.value = mode
+    activePayload.value = payload
+  }
+
+  function setPayload(payload: TPayload | undefined): void {
+    activePayload.value = payload
+  }
+
+  function onWellMouseDown(wellId: string): void {
+    const coord = wellIdToCoordinate(wellId)
+    if (!coord) return
+    isDragging.value = true
+    dragStart.value = coord
+    dragEnd.value = coord
+    paintTrail.value = new Set([wellId])
+  }
+
+  function onWellMouseMove(wellId: string): void {
+    if (!isDragging.value) return
+    const coord = wellIdToCoordinate(wellId)
+    if (!coord) return
+    dragEnd.value = coord
+    if (activeMode.value !== 'select') {
+      paintTrail.value = new Set([...paintTrail.value, wellId])
+    }
+  }
+
+  function onWellMouseUp(): void {
+    if (!isDragging.value) return
+    const wellIds = previewWellIds.value
+    isDragging.value = false
+    if (wellIds.length > 0) {
+      options.onComplete?.({
+        wellIds,
+        mode: activeMode.value,
+        payload: activePayload.value,
+      })
+    }
+    clearDragState()
+  }
+
+  function cancel(): void {
+    isDragging.value = false
+    clearDragState()
+  }
+
+  function clearDragState(): void {
+    dragStart.value = null
+    dragEnd.value = null
+    paintTrail.value = new Set()
+  }
+
+  return {
+    activeMode,
+    activePayload,
+    isDragging,
+    previewWellIds,
+    setMode,
+    setPayload,
+    onWellMouseDown,
+    onWellMouseMove,
+    onWellMouseUp,
+    cancel,
+  }
+}
+
+export function wellIdToCoordinate(wellId: string): WellCoordinate | null {
+  const match = /^([A-Z]+)(\d+)$/i.exec(wellId.trim())
+  if (!match) return null
+  return {
+    row: rowLabelToIndex(match[1].toUpperCase()),
+    col: Number(match[2]) - 1,
+  }
+}
+
+export function coordinateToWellId(coord: WellCoordinate): string {
+  return `${indexToRowLabel(coord.row)}${coord.col + 1}`
+}
+
+export function wellIdsInRectangle(
+  start: WellCoordinate,
+  end: WellCoordinate,
+  format: WellPlateFormat,
+): string[] {
+  const dimensions = PLATE_DIMENSIONS[format]
+  const minRow = Math.max(0, Math.min(start.row, end.row))
+  const maxRow = Math.min(dimensions.rows - 1, Math.max(start.row, end.row))
+  const minCol = Math.max(0, Math.min(start.col, end.col))
+  const maxCol = Math.min(dimensions.cols - 1, Math.max(start.col, end.col))
+  const ids: string[] = []
+
+  for (let row = minRow; row <= maxRow; row++) {
+    for (let col = minCol; col <= maxCol; col++) {
+      ids.push(coordinateToWellId({ row, col }))
+    }
+  }
+  return ids
+}
+
+function rowLabelToIndex(label: string): number {
+  let result = 0
+  for (const char of label) {
+    result = result * 26 + (char.charCodeAt(0) - 64)
+  }
+  return result - 1
+}
+
+function indexToRowLabel(index: number): string {
+  if (index < ROW_LABELS.length) return ROW_LABELS[index]
+  let value = index + 1
+  let label = ''
+  while (value > 0) {
+    value--
+    label = ROW_LABELS[value % 26] + label
+    value = Math.floor(value / 26)
+  }
+  return label
+}

package/src/composables/useWellPlateAdapter.ts

@@ -0,0 +1,147 @@
+import { computed, toValue, type ComputedRef, type Ref } from 'vue'
+import type { ColumnCondition, RowCondition, Well } from '../types'
+
+export type WellPlateAdapterSource<T> =
+  | T
+  | Ref<T>
+  | ComputedRef<T>
+  | (() => T)
+
+export interface WellPlateEntry {
+  wellId: string
+  state?: Well['state']
+  sampleType?: string
+  value?: number
+  metadata?: Record<string, unknown>
+}
+
+export interface WellPlateAdapterOptions<TEntry> {
+  entries: WellPlateAdapterSource<readonly TEntry[]>
+  getWellId: (entry: TEntry) => string
+  getState?: (entry: TEntry) => Well['state'] | undefined
+  getSampleType?: (entry: TEntry) => string | undefined
+  getValue?: (entry: TEntry) => number | undefined
+  getMetadata?: (entry: TEntry) => Record<string, unknown> | undefined
+}
+
+export interface UseWellPlateAdapterReturn {
+  wells: ComputedRef<Record<string, Partial<Well>>>
+}
+
+/** Convert domain rows into WellPlate's wells prop without hand-written adapters. */
+export function useWellPlateAdapter<TEntry>(
+  options: WellPlateAdapterOptions<TEntry>,
+): UseWellPlateAdapterReturn {
+  const wells = computed(() => createWellPlateWells(toValue(options.entries), options))
+  return { wells }
+}
+
+export function createWellPlateWells<TEntry>(
+  entries: readonly TEntry[],
+  options: Omit<WellPlateAdapterOptions<TEntry>, 'entries'>,
+): Record<string, Partial<Well>> {
+  return Object.fromEntries(entries.map((entry) => {
+    const wellId = options.getWellId(entry)
+    const coord = parseWellId(wellId)
+    const well: Partial<Well> = {
+      id: wellId,
+      row: coord.row,
+      col: coord.col,
+      state: options.getState?.(entry) ?? 'filled',
+      sampleType: options.getSampleType?.(entry),
+      value: options.getValue?.(entry),
+      metadata: options.getMetadata?.(entry),
+    }
+    return [wellId, well]
+  }))
+}
+
+export interface AxisConditionEntry {
+  label: string
+  color: string
+  start: string | number
+  concentrations: readonly { value: number; replicates?: number }[]
+  unit?: string
+}
+
+export function createColumnConditions(entries: readonly AxisConditionEntry[]): ColumnCondition[] {
+  return entries.map((entry) => {
+    const startCol = typeof entry.start === 'number'
+      ? entry.start
+      : Number.parseInt(entry.start, 10)
+    const cols: number[] = []
+    const concentrations: number[] = []
+
+    for (const concentration of entry.concentrations) {
+      const replicates = concentration.replicates ?? 1
+      for (let index = 0; index < replicates; index++) {
+        cols.push(startCol + cols.length)
+        concentrations.push(concentration.value)
+      }
+    }
+
+    return {
+      label: entry.label,
+      color: entry.color,
+      unit: entry.unit,
+      cols,
+      concentrations,
+    }
+  })
+}
+
+export function createRowConditions(entries: readonly AxisConditionEntry[]): RowCondition[] {
+  return entries.map((entry) => {
+    const startRow = typeof entry.start === 'number'
+      ? entry.start
+      : rowLabelToIndex(entry.start)
+    const rows: string[] = []
+    const concentrations: number[] = []
+
+    for (const concentration of entry.concentrations) {
+      const replicates = concentration.replicates ?? 1
+      for (let index = 0; index < replicates; index++) {
+        rows.push(indexToRowLabel(startRow + rows.length))
+        concentrations.push(concentration.value)
+      }
+    }
+
+    return {
+      label: entry.label,
+      color: entry.color,
+      unit: entry.unit,
+      rows,
+      concentrations,
+    }
+  })
+}
+
+function parseWellId(wellId: string): { row: number; col: number } {
+  const match = /^([A-Z]+)(\d+)$/i.exec(wellId.trim())
+  if (!match) {
+    throw new Error(`[MINT SDK] Invalid well id "${wellId}".`)
+  }
+  return {
+    row: rowLabelToIndex(match[1].toUpperCase()),
+    col: Number(match[2]) - 1,
+  }
+}
+
+function rowLabelToIndex(label: string): number {
+  let result = 0
+  for (const char of label.toUpperCase()) {
+    result = result * 26 + (char.charCodeAt(0) - 64)
+  }
+  return result - 1
+}
+
+function indexToRowLabel(index: number): string {
+  let value = index + 1
+  let label = ''
+  while (value > 0) {
+    value--
+    label = String.fromCharCode(65 + (value % 26)) + label
+    value = Math.floor(value / 26)
+  }
+  return label
+}