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

package/src/composables/useChemicalFormula.ts

@@ -0,0 +1,275 @@
+// Types
+export interface ParsedElement {
+  symbol: string
+  count: number
+}
+
+export interface FormulaParseResult {
+  elements: Record<string, number>
+  valid: boolean
+  error?: string
+}
+
+export type FormulaPartType = 'element' | 'subscript' | 'superscript' | 'paren' | 'dot' | 'charge'
+
+export interface FormulaPart {
+  type: FormulaPartType
+  text: string
+}
+
+// ~30 common elements with atomic weights
+export const ATOMIC_WEIGHTS: Record<string, number> = {
+  H: 1.008, He: 4.003, Li: 6.941, Be: 9.012, B: 10.81,
+  C: 12.011, N: 14.007, O: 15.999, F: 18.998, Ne: 20.180,
+  Na: 22.990, Mg: 24.305, Al: 26.982, Si: 28.086, P: 30.974,
+  S: 32.065, Cl: 35.453, Ar: 39.948, K: 39.098, Ca: 40.078,
+  Mn: 54.938, Fe: 55.845, Co: 58.933, Ni: 58.693, Cu: 63.546,
+  Zn: 65.38, Br: 79.904, Ag: 107.868, I: 126.904, Au: 196.967,
+}
+
+function parseFormulaSegment(formula: string): FormulaParseResult {
+  const elements: Record<string, number> = {}
+  const stack: Record<string, number>[] = [{}]
+  let i = 0
+
+  while (i < formula.length) {
+    const ch = formula[i]
+
+    if (ch === '(') {
+      stack.push({})
+      i++
+    } else if (ch === ')') {
+      if (stack.length < 2) {
+        return { elements: {}, valid: false, error: 'Unmatched closing parenthesis' }
+      }
+      i++
+      // Read multiplier after closing paren
+      let numStr = ''
+      while (i < formula.length && /\d/.test(formula[i])) {
+        numStr += formula[i]
+        i++
+      }
+      const multiplier = numStr ? parseInt(numStr, 10) : 1
+      const top = stack.pop()!
+      const current = stack[stack.length - 1]
+      for (const [el, count] of Object.entries(top)) {
+        current[el] = (current[el] || 0) + count * multiplier
+      }
+    } else if (/[A-Z]/.test(ch)) {
+      // Element symbol: uppercase letter optionally followed by lowercase
+      let symbol = ch
+      i++
+      while (i < formula.length && /[a-z]/.test(formula[i])) {
+        symbol += formula[i]
+        i++
+      }
+      // Validate element
+      if (!(symbol in ATOMIC_WEIGHTS)) {
+        return { elements: {}, valid: false, error: `Unknown element: ${symbol}` }
+      }
+      // Read count
+      let numStr = ''
+      while (i < formula.length && /\d/.test(formula[i])) {
+        numStr += formula[i]
+        i++
+      }
+      const count = numStr ? parseInt(numStr, 10) : 1
+      const current = stack[stack.length - 1]
+      current[symbol] = (current[symbol] || 0) + count
+    } else {
+      return { elements: {}, valid: false, error: `Unexpected character: ${ch}` }
+    }
+  }
+
+  if (stack.length !== 1) {
+    return { elements: {}, valid: false, error: 'Unmatched opening parenthesis' }
+  }
+
+  Object.assign(elements, stack[0])
+  return { elements, valid: true }
+}
+
+/** Parses and renders chemical formulas, computes molecular weight, and generates rich-text formula parts. */
+export function useChemicalFormula() {
+  function parseFormula(formula: string): FormulaParseResult {
+    const trimmed = formula.trim()
+    if (!trimmed) {
+      return { elements: {}, valid: false, error: 'Empty formula' }
+    }
+
+    // Split on hydrate separator (· or .)
+    const parts = trimmed.split(/[·.]/)
+    const combined: Record<string, number> = {}
+
+    for (const part of parts) {
+      const segment = part.trim()
+      if (!segment) continue
+
+      // Check for leading coefficient (e.g., 5H2O)
+      let coefficient = 1
+      let formulaStr = segment
+      const coeffMatch = segment.match(/^(\d+)([A-Z].*)$/)
+      if (coeffMatch) {
+        coefficient = parseInt(coeffMatch[1], 10)
+        formulaStr = coeffMatch[2]
+      }
+
+      const result = parseFormulaSegment(formulaStr)
+      if (!result.valid) {
+        return result
+      }
+
+      for (const [el, count] of Object.entries(result.elements)) {
+        combined[el] = (combined[el] || 0) + count * coefficient
+      }
+    }
+
+    return { elements: combined, valid: true }
+  }
+
+  function calculateMW(elements: Record<string, number>): number {
+    let mw = 0
+    for (const [el, count] of Object.entries(elements)) {
+      const weight = ATOMIC_WEIGHTS[el]
+      if (weight !== undefined) {
+        mw += weight * count
+      }
+    }
+    return Math.round(mw * 1000) / 1000
+  }
+
+  function renderFormulaParts(formula: string): FormulaPart[] {
+    const parts: FormulaPart[] = []
+    const trimmed = formula.trim()
+    let i = 0
+
+    while (i < trimmed.length) {
+      const ch = trimmed[i]
+
+      // Hydrate dot separator
+      if (ch === '·' || (ch === '.' && i > 0 && /\d/.test(trimmed[i - 1]) && i + 1 < trimmed.length && /\d/.test(trimmed[i + 1]))) {
+        // Disambiguate: '.' as hydrate separator only if followed by a digit then uppercase
+        // For simplicity, treat '·' always as dot
+        if (ch === '·') {
+          parts.push({ type: 'dot', text: '·' })
+          i++
+          continue
+        }
+      }
+
+      // Parentheses
+      if (ch === '(' || ch === ')') {
+        parts.push({ type: 'paren', text: ch })
+        i++
+        // After ')' check for subscript number
+        if (ch === ')' && i < trimmed.length && /\d/.test(trimmed[i])) {
+          let numStr = ''
+          while (i < trimmed.length && /\d/.test(trimmed[i])) {
+            numStr += trimmed[i]
+            i++
+          }
+          parts.push({ type: 'subscript', text: numStr })
+        }
+        continue
+      }
+
+      // Charge notation: ^2+, ^2-, 2+, 2- at end, or +, -
+      if (ch === '^') {
+        i++
+        let chargeStr = ''
+        while (i < trimmed.length && /[\d+\-]/.test(trimmed[i])) {
+          chargeStr += trimmed[i]
+          i++
+        }
+        if (chargeStr) {
+          parts.push({ type: 'charge', text: chargeStr })
+        }
+        continue
+      }
+
+      // Element symbol: uppercase followed by optional lowercase
+      if (/[A-Z]/.test(ch)) {
+        let symbol = ch
+        i++
+        while (i < trimmed.length && /[a-z]/.test(trimmed[i])) {
+          symbol += trimmed[i]
+          i++
+        }
+        parts.push({ type: 'element', text: symbol })
+
+        // Check for subscript number after element
+        if (i < trimmed.length && /\d/.test(trimmed[i])) {
+          let numStr = ''
+          while (i < trimmed.length && /\d/.test(trimmed[i])) {
+            numStr += trimmed[i]
+            i++
+          }
+          parts.push({ type: 'subscript', text: numStr })
+
+          // Check for charge after subscript (e.g., Fe2+ or SO4^2-)
+          if (i < trimmed.length && (trimmed[i] === '+' || trimmed[i] === '-')) {
+            parts.push({ type: 'charge', text: numStr + trimmed[i] })
+            // Remove the subscript we just added since it's actually part of charge
+            // Actually, for cases like Fe2+, the 2+ is the charge, not a subscript
+            // But for H2O the 2 is a subscript. We need context.
+            // Simplification: if followed by +/-, treat trailing digits as part of charge
+            parts.splice(parts.length - 2, 1) // Remove the subscript
+            i++
+            continue
+          }
+        }
+        continue
+      }
+
+      // Leading digit (hydrate coefficient like 5H2O)
+      if (/\d/.test(ch)) {
+        let numStr = ''
+        while (i < trimmed.length && /\d/.test(trimmed[i])) {
+          numStr += trimmed[i]
+          i++
+        }
+        // Could be a subscript or coefficient depending on context
+        // If next char is uppercase, it's a coefficient (render as element-like text)
+        // If at end or followed by +/-, it's a charge component
+        if (i < trimmed.length && (trimmed[i] === '+' || trimmed[i] === '-')) {
+          parts.push({ type: 'charge', text: numStr + trimmed[i] })
+          i++
+        } else {
+          parts.push({ type: 'subscript', text: numStr })
+        }
+        continue
+      }
+
+      // Standalone + or - (charge)
+      if (ch === '+' || ch === '-') {
+        parts.push({ type: 'charge', text: ch })
+        i++
+        continue
+      }
+
+      // Dot as hydrate separator
+      if (ch === '.') {
+        parts.push({ type: 'dot', text: '·' })
+        i++
+        continue
+      }
+
+      // Skip whitespace
+      if (/\s/.test(ch)) {
+        i++
+        continue
+      }
+
+      // Unknown character, skip
+      i++
+    }
+
+    return parts
+  }
+
+  return {
+    parseFormula,
+    calculateMW,
+    renderFormulaParts,
+  }
+}

package/src/composables/useCommandHistory.ts

@@ -0,0 +1,117 @@
+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.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; keep command stacks plugin-local.
+ */
+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/useConcentrationUnits.ts

@@ -0,0 +1,246 @@
+import { computed, type ComputedRef } from 'vue'
+
+// Concentration unit types
+export type MolarityUnit = 'pM' | 'nM' | 'µM' | 'mM' | 'M'
+export type MassVolumeUnit = 'pg/mL' | 'ng/mL' | 'µg/mL' | 'mg/mL' | 'g/mL'
+export type PercentageUnit = '% v/v' | '% w/v' | '% w/w'
+export type ConcentrationUnit = MolarityUnit | MassVolumeUnit | PercentageUnit | string
+
+export interface ConcentrationValue {
+  value: number
+  unit: ConcentrationUnit
+}
+
+export interface UnitCategory {
+  label: string
+  units: ConcentrationUnit[]
+}
+
+export interface UseConcentrationUnitsReturn {
+  unitCategories: ComputedRef<UnitCategory[]>
+  molarityUnits: MolarityUnit[]
+  massVolumeUnits: MassVolumeUnit[]
+  percentageUnits: PercentageUnit[]
+  convert: (value: number, from: ConcentrationUnit, to: ConcentrationUnit, mw?: number) => number | null
+  formatWithUnit: (concentration: ConcentrationValue, precision?: number) => string
+  parseConcentration: (input: string) => ConcentrationValue | null
+  getBaseUnit: (unit: ConcentrationUnit) => ConcentrationUnit
+  getConversionHint: (concentration: ConcentrationValue) => string | null
+  isMolarity: (unit: ConcentrationUnit) => boolean
+  isMassVolume: (unit: ConcentrationUnit) => boolean
+  isPercentage: (unit: ConcentrationUnit) => boolean
+}
+
+// Conversion factors to base unit (M for molarity, g/mL for mass/volume)
+const MOLARITY_FACTORS: Record<MolarityUnit, number> = {
+  'pM': 1e-12,
+  'nM': 1e-9,
+  'µM': 1e-6,
+  'mM': 1e-3,
+  'M': 1,
+}
+
+const MASS_VOLUME_FACTORS: Record<MassVolumeUnit, number> = {
+  'pg/mL': 1e-12,
+  'ng/mL': 1e-9,
+  'µg/mL': 1e-6,
+  'mg/mL': 1e-3,
+  'g/mL': 1,
+}
+
+// Percentage conversion factors (for potential future use)
+// const PERCENTAGE_FACTORS: Record<PercentageUnit, number> = {
+//   '% v/v': 0.01,
+//   '% w/v': 0.01,
+//   '% w/w': 0.01,
+// }
+
+const MOLARITY_UNITS: MolarityUnit[] = ['pM', 'nM', 'µM', 'mM', 'M']
+const MASS_VOLUME_UNITS: MassVolumeUnit[] = ['pg/mL', 'ng/mL', 'µg/mL', 'mg/mL', 'g/mL']
+const PERCENTAGE_UNITS: PercentageUnit[] = ['% v/v', '% w/v', '% w/w']
+
+/** Converts between molarity, mass/volume, and percentage concentration units with formatting helpers. */
+export function useConcentrationUnits(): UseConcentrationUnitsReturn {
+  const unitCategories = computed<UnitCategory[]>(() => [
+    { label: 'Molarity', units: MOLARITY_UNITS },
+    { label: 'Mass/Volume', units: MASS_VOLUME_UNITS },
+    { label: 'Percentage', units: PERCENTAGE_UNITS },
+  ])
+
+  function isMolarity(unit: ConcentrationUnit): unit is MolarityUnit {
+    return MOLARITY_UNITS.includes(unit as MolarityUnit)
+  }
+
+  function isMassVolume(unit: ConcentrationUnit): unit is MassVolumeUnit {
+    return MASS_VOLUME_UNITS.includes(unit as MassVolumeUnit)
+  }
+
+  function isPercentage(unit: ConcentrationUnit): unit is PercentageUnit {
+    return PERCENTAGE_UNITS.includes(unit as PercentageUnit)
+  }
+
+  function getBaseUnit(unit: ConcentrationUnit): ConcentrationUnit {
+    if (isMolarity(unit)) return 'M'
+    if (isMassVolume(unit)) return 'g/mL'
+    if (isPercentage(unit)) return '% w/v'
+    return unit
+  }
+
+  function convert(
+    value: number,
+    from: ConcentrationUnit,
+    to: ConcentrationUnit,
+    mw?: number
+  ): number | null {
+    if (from === to) return value
+    if (value === 0) return 0
+
+    // Same category conversion
+    if (isMolarity(from) && isMolarity(to)) {
+      const baseValue = value * MOLARITY_FACTORS[from]
+      return baseValue / MOLARITY_FACTORS[to]
+    }
+
+    if (isMassVolume(from) && isMassVolume(to)) {
+      const baseValue = value * MASS_VOLUME_FACTORS[from]
+      return baseValue / MASS_VOLUME_FACTORS[to]
+    }
+
+    if (isPercentage(from) && isPercentage(to)) {
+      // Percentage conversions within same category are direct
+      return value
+    }
+
+    // Cross-category conversion (requires molecular weight)
+    if (mw && mw > 0) {
+      // Molarity to Mass/Volume
+      if (isMolarity(from) && isMassVolume(to)) {
+        // Convert to M, then to g/mL using MW, then to target unit
+        const molarConc = value * MOLARITY_FACTORS[from]
+        const massConc = molarConc * mw // g/mL (MW in g/mol, concentration in mol/L = g/L)
+        return massConc / MASS_VOLUME_FACTORS[to]
+      }
+
+      // Mass/Volume to Molarity
+      if (isMassVolume(from) && isMolarity(to)) {
+        // Convert to g/mL, then to M using MW, then to target unit
+        const massConc = value * MASS_VOLUME_FACTORS[from]
+        const molarConc = massConc / mw // M (g/mL / g/mol = mol/L)
+        return molarConc / MOLARITY_FACTORS[to]
+      }
+    }
+
+    return null // Cannot convert without MW or between incompatible units
+  }
+
+  function formatWithUnit(concentration: ConcentrationValue, precision: number = 3): string {
+    const { value, unit } = concentration
+    if (value === 0) return `0 ${unit}`
+
+    // Use appropriate precision based on value magnitude
+    let formattedValue: string
+    if (Math.abs(value) >= 1000) {
+      formattedValue = value.toExponential(precision - 1)
+    } else if (Math.abs(value) < 0.001) {
+      formattedValue = value.toExponential(precision - 1)
+    } else {
+      formattedValue = value.toPrecision(precision)
+    }
+
+    // Remove trailing zeros after decimal point
+    formattedValue = formattedValue.replace(/\.?0+$/, '')
+    formattedValue = formattedValue.replace(/\.?0+e/, 'e')
+
+    return `${formattedValue} ${unit}`
+  }
+
+  function parseConcentration(input: string): ConcentrationValue | null {
+    const trimmed = input.trim()
+    if (!trimmed) return null
+
+    // Match number followed by optional unit
+    const match = trimmed.match(/^([-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)\s*(.*)$/)
+    if (!match) return null
+
+    const value = parseFloat(match[1])
+    if (isNaN(value)) return null
+
+    let unit = match[2].trim()
+    if (!unit) {
+      return null // Unit is required
+    }
+
+    // Normalize common variations
+    unit = unit
+      .replace(/uM/i, 'µM')
+      .replace(/um/i, 'µM')
+      .replace(/ug\/ml/i, 'µg/mL')
+      .replace(/ng\/ml/i, 'ng/mL')
+      .replace(/mg\/ml/i, 'mg/mL')
+      .replace(/pg\/ml/i, 'pg/mL')
+      .replace(/g\/ml/i, 'g/mL')
+
+    return { value, unit }
+  }
+
+  function getConversionHint(concentration: ConcentrationValue): string | null {
+    const { value, unit } = concentration
+    if (value === 0) return null
+
+    // Find adjacent unit for conversion hint
+    if (isMolarity(unit)) {
+      const index = MOLARITY_UNITS.indexOf(unit)
+      // If value is large, suggest next higher unit
+      if (value >= 1000 && index < MOLARITY_UNITS.length - 1) {
+        const nextUnit = MOLARITY_UNITS[index + 1]
+        const converted = convert(value, unit, nextUnit)
+        if (converted !== null) {
+          return formatWithUnit({ value: converted, unit: nextUnit })
+        }
+      }
+      // If value is small, suggest next lower unit
+      if (value < 1 && index > 0) {
+        const prevUnit = MOLARITY_UNITS[index - 1]
+        const converted = convert(value, unit, prevUnit)
+        if (converted !== null) {
+          return formatWithUnit({ value: converted, unit: prevUnit })
+        }
+      }
+    }
+
+    if (isMassVolume(unit)) {
+      const index = MASS_VOLUME_UNITS.indexOf(unit)
+      if (value >= 1000 && index < MASS_VOLUME_UNITS.length - 1) {
+        const nextUnit = MASS_VOLUME_UNITS[index + 1]
+        const converted = convert(value, unit, nextUnit)
+        if (converted !== null) {
+          return formatWithUnit({ value: converted, unit: nextUnit })
+        }
+      }
+      if (value < 1 && index > 0) {
+        const prevUnit = MASS_VOLUME_UNITS[index - 1]
+        const converted = convert(value, unit, prevUnit)
+        if (converted !== null) {
+          return formatWithUnit({ value: converted, unit: prevUnit })
+        }
+      }
+    }
+
+    return null
+  }
+
+  return {
+    unitCategories,
+    molarityUnits: MOLARITY_UNITS,
+    massVolumeUnits: MASS_VOLUME_UNITS,
+    percentageUnits: PERCENTAGE_UNITS,
+    convert,
+    formatWithUnit,
+    parseConcentration,
+    getBaseUnit,
+    getConversionHint,
+    isMolarity,
+    isMassVolume,
+    isPercentage,
+  }
+}