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

package/src/types/instrument.ts

@@ -0,0 +1,62 @@
+export type InstrumentState = 'idle' | 'running' | 'standby' | 'connected' | 'disconnected' | 'error'
+export type InstrumentAlertLevel = 'info' | 'warning' | 'critical'
+
+export interface SampleInfo {
+  file_name: string
+  sample_id?: string | null
+  sample_name?: string | null
+  vial_position?: string | null
+  injection_volume?: number | null
+}
+
+export interface SequenceProgress {
+  sequence_name?: string | null
+  current_sample: number
+  total_samples: number
+  elapsed_seconds?: number
+  estimated_remaining_seconds?: number | null
+  avg_sample_seconds?: number | null
+  current_sample_name?: string | null
+  current_method?: string | null
+  estimated_finish_time?: string | Date | null
+  sample_durations?: readonly number[]
+}
+
+export interface InstrumentStatus {
+  instrument_id: string
+  instrument_name?: string | null
+  monitor_id?: string | null
+  state: InstrumentState
+  active_method?: string | null
+  current_sample?: SampleInfo | null
+  sequence_progress?: SequenceProgress | null
+  timestamp?: string | Date
+  last_seen?: string | Date | null
+  connected?: boolean
+  sequence_file?: string | null
+  sequence_row_index?: number | null
+  current_raw_file?: string | null
+  method_elapsed_pct?: number | null
+}
+
+export interface InstrumentAlertBody {
+  source?: string | null
+  event?: string | null
+  detail: string
+  code?: number | null
+  raw_file?: string | null
+}
+
+export interface InstrumentAlert {
+  id?: string
+  event_key: string
+  instrument_id: string
+  instrument_name?: string | null
+  level: InstrumentAlertLevel
+  rule?: string
+  message?: string | null
+  body?: InstrumentAlertBody | null
+  context?: Record<string, unknown>
+  timestamp?: string | Date
+  acknowledged?: boolean
+}

package/src/types/jobs.ts

@@ -0,0 +1,70 @@
+/** Canonical lifecycle values emitted by the MINT Python SDK job contract. */
+export type JobStatus =
+  | 'awaiting_input'
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+export interface JobProgress {
+  current_file: number
+  total_files: number
+  current_filename: string | null
+  percent: number
+  message: string
+  stage: string
+}
+
+/** Normalized job state used by SDK job UI. */
+export interface JobState {
+  id: string
+  job_id: string
+  kind: string
+  name: string
+  definition_id: string | null
+  status: JobStatus
+  progress: JobProgress
+  queue_position: number
+  warnings: string[]
+  error: string | null
+  output_path: string | null
+  save_path: string | null
+  session_id: string | null
+  folders: string[]
+  folder_path: string | null
+  user_id: string | null
+  owner_user_id: string | null
+  experiment_id: string | null
+  extraction_result_id: string | null
+  metadata: Record<string, unknown>
+  created_at: string
+  started_at: string | null
+  completed_at: string | null
+  can_cancel: boolean
+  can_delete: boolean
+  result_status: 'none' | 'available' | 'expired'
+  result_expires_at: string | null
+}
+
+/** Backward-compatible transport shape accepted from pre-capability backends. */
+export type JobStateInput = Omit<
+  JobState,
+  'can_cancel' | 'can_delete' | 'definition_id' | 'result_status' | 'result_expires_at'
+> & {
+  can_cancel?: boolean | null
+  can_delete?: boolean | null
+  definition_id?: string | null
+  result_status?: 'none' | 'available' | 'expired'
+  result_expires_at?: string | null
+}
+
+export interface JobListPayload {
+  jobs: JobStateInput[]
+}
+
+export interface JobSnapshotPayload {
+  jobs: JobStateInput[]
+}
+
+export type JobStreamData = JobStateInput | JobSnapshotPayload

package/src/types/platform.ts

@@ -0,0 +1,132 @@
+import type { RoleInfo } from '../permissions'
+
+// Plugin information provided by the platform
+export interface PluginInfo {
+  id: string
+  name: string
+  version: string
+  plugin_type?: string
+  description?: string
+  icon?: string
+  color?: string
+  route_prefix: string
+  api_prefix: string
+  /** Settings route selected by the platform for this plugin runtime. */
+  settings_api?: 'plugin' | 'platform'
+  /** Content identity of the HTML that booted this integrated plugin tab. */
+  frontend_revision?: string
+  nav_items?: PluginNavItem[]
+  settings?: PluginSettings
+}
+
+// Plugin navigation item
+export interface PluginNavItem {
+  id?: string
+  label: string
+  path: string
+  icon?: string
+  description?: string
+  requiresAuth?: boolean
+  requiresAdmin?: boolean
+  requiresFeature?: string
+  children?: PluginNavItem[]
+}
+
+// Plugin settings schema
+export interface PluginSettings {
+  [key: string]: PluginSettingField
+}
+
+export interface PluginSettingField {
+  type: 'string' | 'number' | 'boolean' | 'select' | 'multiselect'
+  label: string
+  description?: string
+  default?: unknown
+  options?: Array<{ value: string; label: string }>
+  validation?: {
+    required?: boolean
+    min?: number
+    max?: number
+    pattern?: string
+  }
+}
+
+// Minimal user representation used across experiment payloads and
+// the injected platform context.  shortname is a short attribution
+// code (initials) used e.g. in generated filenames.
+export interface UserSummary {
+  id: number
+  username: string
+  shortname?: string
+  first_name?: string
+  last_name?: string
+}
+
+// Platform context - available to plugins when running under MINT Platform
+export interface PlatformContext {
+  // Is running under the MINT Platform
+  isIntegrated: boolean
+
+  // Plugin info (only available when integrated)
+  plugin?: PluginInfo
+
+  // Platform API base URL
+  platformApiUrl?: string
+
+  // Platform origin for message validation
+  // Used to verify postMessage sources and targets
+  platformOrigin?: string
+
+  // Current user info (if authenticated)
+  user?: {
+    id: number
+    username: string
+    role: string
+    role_obj?: RoleInfo | null
+    roleObj?: RoleInfo | null
+    shortname?: string
+  }
+
+  // Theme preference
+  theme: 'light' | 'dark' | 'system'
+
+  // Allowed experiment types for this plugin (from admin config)
+  allowedExperimentTypes?: string[] | null
+
+  // Features enabled in platform
+  features?: {
+    admin?: boolean
+    experiments?: boolean
+    samples?: boolean
+    passkey?: boolean
+    multiUser?: boolean
+  }
+}
+
+// Configuration options for usePlatformContext
+export interface PlatformContextOptions {
+  // Allowed origins for postMessage communication
+  // If not specified, derives from platformApiUrl or uses same-origin only
+  allowedOrigins?: string[]
+
+  // Whether to allow messages from any origin (UNSAFE - only for development)
+  // Default: false
+  allowAnyOrigin?: boolean
+}
+
+// Platform event types for communication between plugin and platform
+export type PlatformEventType =
+  | 'mint:theme-changed'
+  | 'mint:user-changed'
+  | 'mint:navigate'
+  | 'mint:notification'
+
+export interface PlatformEvent<T = unknown> {
+  type: PlatformEventType
+  payload: T
+}
+
+// Settings state types
+export type ThemeMode = 'light' | 'dark' | 'system'
+export type ColorPalette = 'default' | 'colorblind' | 'viridis' | 'pastel'
+export type TableDensity = 'compact' | 'normal' | 'comfortable'

package/src/utils/color.ts

@@ -0,0 +1,96 @@
+/**
+ * Color utilities for deriving same-hue-family shades.
+ *
+ * Used by SampleSelector and other group/legend UIs where a parent color
+ * needs to seed a gradient of related shades for its children.
+ */
+
+export interface Hsl {
+  h: number // 0–360
+  s: number // 0–100
+  l: number // 0–100
+}
+
+const HEX_RE = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i
+
+function clamp(n: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, n))
+}
+
+export function hexToHsl(hex: string): Hsl {
+  const match = HEX_RE.exec(hex.trim())
+  if (!match) return { h: 0, s: 0, l: 50 }
+
+  let raw = match[1]
+  if (raw.length === 3) raw = raw.split('').map(c => c + c).join('')
+
+  const r = parseInt(raw.slice(0, 2), 16) / 255
+  const g = parseInt(raw.slice(2, 4), 16) / 255
+  const b = parseInt(raw.slice(4, 6), 16) / 255
+
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  const delta = max - min
+
+  let h = 0
+  if (delta !== 0) {
+    if (max === r) h = ((g - b) / delta) % 6
+    else if (max === g) h = (b - r) / delta + 2
+    else h = (r - g) / delta + 4
+  }
+  h = (h * 60 + 360) % 360
+
+  const l = (max + min) / 2
+  const s = delta === 0 ? 0 : delta / (1 - Math.abs(2 * l - 1))
+
+  return { h, s: s * 100, l: l * 100 }
+}
+
+export function hslToHex(h: number, s: number, l: number): string {
+  const sNorm = clamp(s, 0, 100) / 100
+  const lNorm = clamp(l, 0, 100) / 100
+  const hNorm = ((h % 360) + 360) % 360
+
+  const c = (1 - Math.abs(2 * lNorm - 1)) * sNorm
+  const x = c * (1 - Math.abs(((hNorm / 60) % 2) - 1))
+  const m = lNorm - c / 2
+
+  let r = 0, g = 0, b = 0
+  if (hNorm < 60) [r, g, b] = [c, x, 0]
+  else if (hNorm < 120) [r, g, b] = [x, c, 0]
+  else if (hNorm < 180) [r, g, b] = [0, c, x]
+  else if (hNorm < 240) [r, g, b] = [0, x, c]
+  else if (hNorm < 300) [r, g, b] = [x, 0, c]
+  else [r, g, b] = [c, 0, x]
+
+  const toHex = (n: number) => Math.round((n + m) * 255).toString(16).padStart(2, '0')
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`
+}
+
+/**
+ * Derive a same-hue-family shade of `parentHex` for child at `index` of `total`.
+ *
+ * Lightness is distributed evenly within [35, 75] so all children remain
+ * readable on light/dark backgrounds. Hue and saturation are inherited from
+ * the parent. With `total <= 1`, returns the parent unchanged.
+ *
+ * Children are ordered light → dark by index, so index 0 is the brightest
+ * sibling and index `total - 1` is the darkest.
+ */
+export function deriveShade(parentHex: string, index: number, total: number): string {
+  if (total <= 1) return parentHex
+  const { h, s, l } = hexToHsl(parentHex)
+
+  const L_MIN = 35
+  const L_MAX = 75
+  const spread = Math.min(L_MAX - L_MIN, 40)
+  const center = clamp(l, L_MIN + spread / 2, L_MAX - spread / 2)
+
+  const top = center + spread / 2
+  const bot = center - spread / 2
+  const t = total === 1 ? 0.5 : index / (total - 1)
+  const childL = top - t * (top - bot)
+
+  const childS = clamp(s, 35, 100)
+  return hslToHex(h, childS, childL)
+}

package/src/utils/formModelSync.ts

@@ -0,0 +1,50 @@
+import type { FormSchema } from '../types/form-builder'
+import { isRecord } from './records'
+
+export function recordValuesEqualForKeys(
+  left: Record<string, unknown>,
+  right: Record<string, unknown>,
+  keys: readonly string[],
+): boolean {
+  for (const key of keys) {
+    if (!valuesEqual(left[key], right[key])) return false
+  }
+  return true
+}
+
+export function pickRecordKeys(
+  source: Record<string, unknown>,
+  keys: readonly string[],
+): Record<string, unknown> {
+  return Object.fromEntries(keys.map(key => [key, source[key]]))
+}
+
+export function pickExistingRecordKeys(
+  source: Record<string, unknown>,
+  keys: readonly string[],
+): Record<string, unknown> {
+  return Object.fromEntries(
+    keys
+      .filter(key => Object.prototype.hasOwnProperty.call(source, key))
+      .map(key => [key, source[key]]),
+  )
+}
+
+export function formSchemaFieldNames(schema: FormSchema): string[] {
+  const sections = schema.steps
+    ? schema.steps.flatMap(step => step.sections)
+    : schema.sections
+  return sections.flatMap(section => section.fields.map(field => field.name))
+}
+
+function valuesEqual(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((item, index) => valuesEqual(item, right[index]))
+  }
+  if (isRecord(left) && isRecord(right)) {
+    return recordValuesEqualForKeys(left, right, [...new Set([...Object.keys(left), ...Object.keys(right)])])
+  }
+  return false
+}
+

package/src/utils/items.ts

@@ -0,0 +1,28 @@
+export type ItemWithLabel = {
+  label: string
+}
+
+export type ItemWithId = ItemWithLabel & {
+  id: string
+}
+
+export function normalizeItemInput<TItem extends ItemWithId>(
+  item: TItem | string,
+): TItem {
+  if (typeof item === 'object') return item
+
+  return {
+    id: item,
+    label: item,
+  } as TItem
+}
+
+export function normalizeLabelItemInput<TItem extends ItemWithLabel>(
+  item: TItem | string,
+): TItem {
+  if (typeof item === 'object') return item
+
+  return {
+    label: item,
+  } as TItem
+}

package/src/utils/options.ts

@@ -0,0 +1,23 @@
+export type OptionLike<TValue extends string | number> = {
+  value: TValue
+  label: string
+}
+
+export function normalizeOptionInput<
+  TValue extends string | number,
+  TOption extends OptionLike<TValue>,
+>(option: TOption | TValue): TOption {
+  if (typeof option === 'object') return option
+
+  return {
+    value: option,
+    label: String(option),
+  } as TOption
+}
+
+export function findOptionByDomValue<
+  TValue extends string | number,
+  TOption extends OptionLike<TValue>,
+>(options: TOption[], value: string): TOption | undefined {
+  return options.find(option => String(option.value) === value)
+}

package/src/utils/pluginIcon.ts

@@ -0,0 +1,188 @@
+import { isRecord } from './records'
+export type PluginIconFormat = 'path' | 'data-url' | 'asset-url' | 'structured' | 'fallback'
+
+export interface StructuredPluginIconStop {
+  offset: string
+  color: string
+  opacity?: number
+}
+
+export interface StructuredPluginIconBackground {
+  fill: string
+  radius: number
+}
+
+export interface StructuredPluginIconPath {
+  d: string
+  fill?: string
+  stroke?: string
+  strokeWidth?: number
+  opacity?: number
+}
+
+export interface StructuredPluginIcon {
+  type: 'mint-icon'
+  viewBox: string
+  background?: StructuredPluginIconBackground
+  gradient?: {
+    type: 'linear'
+    angle: number
+    stops: StructuredPluginIconStop[]
+  }
+  paths: StructuredPluginIconPath[]
+}
+
+export interface DetectedPluginIcon {
+  format: PluginIconFormat
+  value: string | StructuredPluginIcon
+}
+
+// MINT canonical plugin placeholder — page-with-corner-fold glyph.
+export const PLUGIN_ICON_FALLBACK_PATH = 'M14 7v4a1 1 0 0 0 1 1h4M5 3h9l5 5v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2z'
+
+const PATH_REGEX = /^[Mm][\s,\d\-.]/
+const RASTER_DATA_URL_REGEX = /^data:image\/(png|jpeg|jpg|gif|webp);/
+const SAME_ORIGIN_ASSET_URL_REGEX = /^\/(?!\/)[^\s?#]+\.(?:svg|png|jpe?g|gif|webp)(?:[?#].*)?$/i
+const VIEW_BOX_REGEX = /^-?\d+(?:\.\d+)?\s+-?\d+(?:\.\d+)?\s+\d+(?:\.\d+)?\s+\d+(?:\.\d+)?$/
+const COLOR_REGEX = /^(#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})|currentColor|white|black|none)$/i
+const MAX_STRUCTURED_ICON_LENGTH = 8000
+const MAX_PATHS = 8
+const MAX_STOPS = 8
+
+export function normalizePluginIconSource(icon?: string): string {
+  return (icon ?? '').replace(/^[\s]+/, '')
+}
+
+export function detectPluginIcon(icon?: string): DetectedPluginIcon {
+  const raw = normalizePluginIconSource(icon)
+  if (!raw) return { format: 'fallback', value: PLUGIN_ICON_FALLBACK_PATH }
+  const structured = parseStructuredPluginIcon(raw)
+  if (structured) return { format: 'structured', value: structured }
+  if (PATH_REGEX.test(raw)) return { format: 'path', value: raw }
+  if (RASTER_DATA_URL_REGEX.test(raw)) return { format: 'data-url', value: raw }
+  if (raw.startsWith('https://') || SAME_ORIGIN_ASSET_URL_REGEX.test(raw)) {
+    return { format: 'asset-url', value: raw }
+  }
+  return { format: 'fallback', value: PLUGIN_ICON_FALLBACK_PATH }
+}
+
+export function isPluginIconFormat(icon?: string): boolean {
+  const raw = normalizePluginIconSource(icon)
+  return !!raw && detectPluginIcon(raw).format !== 'fallback'
+}
+
+function parseStructuredPluginIcon(raw: string): StructuredPluginIcon | undefined {
+  if (!raw.startsWith('{') || raw.length > MAX_STRUCTURED_ICON_LENGTH) return undefined
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+
+  if (!isRecord(parsed) || parsed.type !== 'mint-icon') return undefined
+
+  const viewBox = typeof parsed.viewBox === 'string' && VIEW_BOX_REGEX.test(parsed.viewBox)
+    ? parsed.viewBox
+    : '0 0 24 24'
+
+  const paths = parseStructuredPaths(parsed.paths)
+  if (!paths.length) return undefined
+
+  const gradient = parseStructuredGradient(parsed.gradient)
+  const background = parseStructuredBackground(parsed.background, gradient)
+
+  return {
+    type: 'mint-icon',
+    viewBox,
+    ...(background ? { background } : {}),
+    ...(gradient ? { gradient } : {}),
+    paths,
+  }
+}
+
+function parseStructuredPaths(value: unknown): StructuredPluginIconPath[] {
+  if (!Array.isArray(value)) return []
+
+  return value.slice(0, MAX_PATHS).flatMap((item) => {
+    if (!isRecord(item) || typeof item.d !== 'string' || !item.d.trim()) return []
+    const path: StructuredPluginIconPath = { d: item.d.slice(0, 2000) }
+    if (isSafeColor(item.fill)) path.fill = item.fill
+    if (isSafeColor(item.stroke)) path.stroke = item.stroke
+    if (isFiniteNumber(item.strokeWidth, 0, 24)) path.strokeWidth = item.strokeWidth
+    if (isFiniteNumber(item.opacity, 0, 1)) path.opacity = item.opacity
+    return [path]
+  })
+}
+
+function parseStructuredGradient(value: unknown): StructuredPluginIcon['gradient'] | undefined {
+  if (!isRecord(value) || value.type !== 'linear') return undefined
+
+  const stops = parseStructuredStops(value.stops)
+  if (stops.length < 2 && isSafeColor(value.from) && isSafeColor(value.to)) {
+    stops.push(
+      { offset: '0%', color: value.from },
+      { offset: '100%', color: value.to },
+    )
+  }
+  if (stops.length < 2) return undefined
+
+  return {
+    type: 'linear',
+    angle: isFiniteNumber(value.angle, 0, 360) ? value.angle : 135,
+    stops,
+  }
+}
+
+function parseStructuredStops(value: unknown): StructuredPluginIconStop[] {
+  if (!Array.isArray(value)) return []
+
+  return value.slice(0, MAX_STOPS).flatMap((item) => {
+    if (!isRecord(item) || !isSafeColor(item.color)) return []
+
+    const offset = parseOffset(item.offset)
+    if (!offset) return []
+
+    return [{
+      offset,
+      color: item.color,
+      ...(isFiniteNumber(item.opacity, 0, 1) ? { opacity: item.opacity } : {}),
+    }]
+  })
+}
+
+function parseStructuredBackground(
+  value: unknown,
+  gradient: StructuredPluginIcon['gradient'] | undefined,
+): StructuredPluginIconBackground | undefined {
+  if (!isRecord(value)) return undefined
+
+  const fill = value.fill === 'gradient' && gradient
+    ? 'gradient'
+    : isSafeColor(value.fill)
+      ? value.fill
+      : undefined
+  if (!fill) return undefined
+
+  return {
+    fill,
+    radius: isFiniteNumber(value.radius, 0, 12) ? value.radius : 5,
+  }
+}
+
+function parseOffset(value: unknown): string | undefined {
+  if (isFiniteNumber(value, 0, 1)) return String(value)
+  if (typeof value !== 'string') return undefined
+  if (/^(?:100|(?:[1-9]?\d)(?:\.\d+)?)%$/.test(value)) return value
+  return undefined
+}
+
+
+function isSafeColor(value: unknown): value is string {
+  return typeof value === 'string' && COLOR_REGEX.test(value)
+}
+
+function isFiniteNumber(value: unknown, min: number, max: number): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= min && value <= max
+}