@morscherlab/mint-sdk 1.2.10 → 1.3.0-beta.10

package/src/types/componentLabTypes.ts

@@ -2,7 +2,7 @@
 export type WellPlateFormat = 6 | 12 | 24 | 48 | 54 | 96 | 384
 export type WellState = 'empty' | 'filled' | 'selected' | 'disabled'
 export type WellPlateSelectionMode = 'none' | 'single' | 'multiple' | 'rectangle' | 'drag'
-export type WellPlateSize = 'sm' | 'md' | 'lg' | 'xl' | 'fill'
+export type WellPlateSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'fill'
 export type WellShape = 'circle' | 'rounded'
 
 export interface Well {
@@ -11,6 +11,8 @@ export interface Well {
   col: number
   state: WellState
   sampleType?: string
+  /** Group id (PlateEditor `groups`); colors the well, while `sampleType` sets its marker shape. */
+  group?: string
   value?: number
   metadata?: Record<string, unknown>
 }
@@ -56,7 +58,7 @@ export interface WellEditData {
 // Fields shown in the edit popup
 export type WellEditField = 'label' | 'sampleType' | 'injectionVolume' | 'injectionCount' | 'customMethod'
 
-// External sample drop payloads for WellPlate / RackEditor
+// External sample drop payloads for WellPlate / PlateEditor
 export interface WellSampleDropData {
   id?: string
   sampleName?: string
@@ -102,7 +104,7 @@ export interface RowCondition extends PlateCondition {
   rows: string[]
 }
 
-// Rack for RackEditor
+// Rack for PlateEditor
 export interface Rack {
   id: string
   name: string
@@ -112,18 +114,14 @@ export interface Rack {
   wells: Record<string, Partial<Well>>
 }
 
-export interface RackSampleDropContext {
-  rack: Rack
-  rackId: string
-  wellId: string
-  event: DragEvent
+/** PlateEditor `clearConfirm`: text and variant of the Clear confirmation; unset fields keep the defaults. */
+export interface PlateEditorClearConfirm {
+  title?: string
+  message?: string
+  confirmLabel?: string
+  variant?: 'danger' | 'warning' | 'info'
 }
 
-export type RackSampleDropMapper = (
-  data: WellSampleDropData,
-  context: RackSampleDropContext
-) => WellEditData | null | undefined
-
 // Sample Legend types
 export interface SampleType {
   id: string
@@ -162,6 +160,11 @@ export interface ProtocolStep {
   status: ProtocolStepStatus
   parameters?: Record<string, unknown>
   order: number
+  /**
+   * Percent complete, 0–100. ExperimentTimeline shows it as a 2px bar and a
+   * mono percent on the `in_progress` step only; out-of-range values clamp.
+   */
+  progress?: number
 }
 
 // Sample Selector types

package/src/types/componentWorkflowTypes.ts

@@ -59,6 +59,13 @@ export interface BatchSummary {
 // TimePicker types
 export type TimePickerFormat = '12h' | '24h'
 
+/**
+ * Marks a time slot ("HH:mm") unavailable. Return `false`/nothing for an
+ * available slot, `true` to disable it, or a string to disable it and show
+ * that string inline as the reason (e.g. "Booked · HPLC-02").
+ */
+export type TimeSlotDisabledFn = (time: string) => boolean | string | null | undefined
+
 export interface TimeRange {
   start: string  // "HH:mm"
   end: string    // "HH:mm"
@@ -186,5 +193,27 @@ export type FitState = 'idle' | 'running' | 'completed' | 'error'
 export interface FitResultSummary {
   label: string
   value: string | number
+  /** Icon of a verdict row: success = check, warning = triangle, error = filled circle. Values are never colored. */
   variant?: 'default' | 'success' | 'warning' | 'error'
+  /** Show the result as a verdict (icon + "label value") below the parameter table instead of as a table row. */
+  verdict?: boolean
+  /** Unit shown in mono after the parameter name, never transformed (e.g. `'nM'`). */
+  unit?: string
+  /** Preformatted 95% confidence interval (e.g. `'512 – 778'`). The CI column shows when any row has one. */
+  ci?: string
+}
+
+/** One fitted series in a multi-series FitPanel. */
+export interface FitSeries {
+  label: string
+  /** Group color token, `var(--mint-sample-1)` … `var(--mint-sample-8)`. Defaults to the series' position in that palette. */
+  color?: string
+  results: FitResultSummary[]
+}
+
+/** Header labels of the FitPanel parameter table. */
+export interface FitColumnLabels {
+  parameter?: string
+  value?: string
+  ci?: string
 }

package/src/types/components.ts

@@ -13,6 +13,8 @@ interface ActionMenuItemBase {
   label: string
   disabled?: boolean
   danger?: boolean
+  /** Set on every item to make the menu a single choice (`menuitemradio`); true marks the current one. */
+  checked?: boolean
 }
 
 export type ActionMenuItem =
@@ -23,6 +25,8 @@ export type ActionMenuItem =
   | (ActionMenuItemBase & {
       href: string
       target?: '_self' | '_blank' | '_parent' | '_top'
+      /** Links navigate; only buttons can be single-choice items. */
+      checked?: never
     })
 
 // Input types
@@ -47,6 +51,12 @@ export interface ModalTab {
   icon?: string | string[]
   /** Rail only — second line under the label; also shown as the pane subtitle. */
   description?: string
+  /**
+   * Rail only — heading of the section this tab belongs to. A heading (and a
+   * divider after the first section) renders wherever the section changes, so
+   * keep tabs of one section adjacent.
+   */
+  section?: string
   disabled?: boolean
 }
 
@@ -201,6 +211,8 @@ export interface TopBarSettingsConfig {
   title?: string
   tabs?: SettingsTabInput[]
   showAppearance?: boolean
+  /** List Appearance before the other tabs and open on it. */
+  appearanceFirst?: boolean
   size?: 'md' | 'lg' | 'xl'
   layout?: SettingsModalLayout
   /** Schema-driven config — when set, fields auto-render via SDK form components. */
@@ -229,6 +241,8 @@ export interface PillNavItem {
   to?: string
   href?: string
   disabled?: boolean
+  /** Shows a small error-colored dot after the label (e.g. an unacknowledged critical alert). */
+  dot?: boolean
   children?: PillNavOption[]
 }
 
@@ -249,23 +263,6 @@ export interface PageSelectorItem {
 
 export type PageSelectorItemInput = PageSelectorItem | string
 
-// TopBar plugin switcher info
-export interface PluginSwitcherPlugin {
-  id: string
-  label: string
-  color?: string
-  version?: string
-  to?: string
-  href?: string
-}
-
-export interface PluginSwitcherInfo {
-  current: PluginSwitcherPlugin
-  plugins?: PluginSwitcherPlugin[]
-  installHref?: string
-  installTo?: string
-}
-
 // Avatar/account menu items
 export interface AccountMenuItem {
   id: string
@@ -302,8 +299,7 @@ export type {
   ColumnCondition,
   RowCondition,
   Rack,
-  RackSampleDropContext,
-  RackSampleDropMapper,
+  PlateEditorClearConfirm,
   SampleType,
   PlateMap,
   PlateMapEditorState,
@@ -328,10 +324,21 @@ export interface SegmentedOption {
   label: string
   description?: string
   disabled?: boolean
+  /** Color token for a swatch before the label, e.g. a group color `var(--mint-sample-2)`. */
+  color?: string
 }
 
 export type SegmentedOptionInput = SegmentedOption | OptionPrimitive
 
+/** One series in the ChartContainer header legend. */
+export interface ChartLegendItem {
+  label: string
+  /** Swatch color, e.g. a group token `var(--mint-sample-1)` or a resolved color. */
+  color: string
+  /** Series is toggled off (rendered dimmed, `aria-pressed="false"`). */
+  hidden?: boolean
+}
+
 export type SegmentedControlVariant = 'simple' | 'card'
 export type SegmentedControlSize = 'sm' | 'md' | 'lg'
 
@@ -422,6 +429,18 @@ export interface DataFrameColumn<T = Record<string, unknown>> {
   ellipsis?: boolean
   /** Custom formatter for cell values */
   formatter?: (value: unknown, row: T, index: number) => string
+  /**
+   * Unit shown after the header label in its own mono element, never case-transformed
+   * (`'µM'`, `'mL'`, `'m/z'`). Keep it out of `label`.
+   */
+  unit?: string
+  /**
+   * `'number'` renders cells right-aligned in mono with tabular figures (an explicit
+   * `align` still wins). Default `'text'`.
+   */
+  type?: 'text' | 'number'
+  /** Decimal places for numeric cell values (`toFixed`). Ignored when `formatter` is set. */
+  precision?: number
 }
 
 /** Pagination state for table data */
@@ -445,7 +464,6 @@ export type DividerSpacing = 'sm' | 'md' | 'lg'
 export type StatusType = 'success' | 'warning' | 'error' | 'info' | 'muted'
 
 // ProgressBar types
-export type ProgressVariant = 'rail' | 'segmented'
 export type ProgressColor = 'primary' | 'success' | 'warning' | 'error' | 'info'
 export type ProgressSize = 'sm' | 'md' | 'lg'
 
@@ -484,6 +502,8 @@ export interface SettingsTab extends AccessControlled {
   description?: string
   /** Optional monospace meta shown right of the tab label — a count, "2 unsaved", etc. */
   meta?: string
+  /** Rail section heading for this tab when Appearance is shown; defaults to "Plugin". */
+  section?: string
 }
 
 export type SettingsTabInput = SettingsTab | string
@@ -532,6 +552,7 @@ export type {
   BatchItem,
   BatchSummary,
   TimePickerFormat,
+  TimeSlotDisabledFn,
   TimeRange,
   ScheduleView,
   ScheduleEventStatus,
@@ -554,4 +575,6 @@ export type {
   ExperimentFilters,
   FitState,
   FitResultSummary,
+  FitSeries,
+  FitColumnLabels,
 } from './componentWorkflowTypes'

package/src/types/fileBrowserTypes.ts

@@ -83,3 +83,18 @@ export interface FileBrowserLocation {
   mount_id: string
   path: string
 }
+
+/** Several directory levels in one response, parents before children. */
+export interface FileDirectoryTree {
+  listings?: FileDirectoryListing[]
+  /** True when the server's entry budget stopped before the requested depth. */
+  truncated?: boolean
+}
+
+/** Entries whose name contains a query, below one directory. */
+export interface FileSearchResult {
+  entries?: FileEntry[]
+  searched_directories?: number
+  /** True when a directory, result or time budget ended the search early. */
+  truncated?: boolean
+}

package/src/types/filePicker.ts

@@ -1,6 +1,10 @@
 /** Sources are supplied by the host; the SDK never infers a host filesystem path. */
 export type PickerSource = 'server' | 'localFile'
 export type PickerSelectionMode = 'single-file' | 'multi-file' | 'folder' | 'folder+files'
+/** `list` shows one folder at a time (the default); `tree` adds disclosure triangles. */
+export type PickerView = 'list' | 'tree'
+/** Row order inside each folder; folders always come before files. */
+export type PickerSort = 'newest' | 'oldest' | 'name' | 'name-desc'
 
 interface PickerNodeBase {
   path: string
@@ -8,6 +12,8 @@ interface PickerNodeBase {
   parentPath?: string | null
   parentName?: string
   bytes?: number | null
+  /** ISO timestamp of the last change, shown in the list and the preview. */
+  modifiedAt?: string | null
   /** An explicit adapter failure makes a row inert, including its disclosure. */
   unavailableReason?: string
 }
@@ -35,7 +41,19 @@ export interface PickerRequest {
    */
   refresh?: true
 }
+/** What a search found before a server or walk limit stopped it. */
+export interface PickerSearchResult {
+  nodes: PickerNode[]
+  truncated: boolean
+}
 export interface PickerAdapter {
+  /**
+   * `listRoot()` returns mount points. FilePicker then shows them as header
+   * sources and opens the first reachable one instead of listing the root.
+   */
+  mounts?: boolean
+  /** The path of the mount holding `path`, so an initial folder inside a mount can name it. */
+  mountOf?(path: string): string | undefined
   /** Discard cached and pending results on close, source changes, or refresh. */
   invalidate?(): void
   listRoot(request?: PickerRequest): Promise<PickerNode[]>
@@ -44,7 +62,7 @@ export interface PickerAdapter {
     query: string,
     scope: { path: string; recursive: boolean },
     request?: PickerRequest,
-  ): Promise<PickerNode[]>
+  ): Promise<PickerNode[] | PickerSearchResult>
 }
 export interface PickerCapability {
   /** Case-insensitive suffixes, including compound extensions such as mzML.gz. */

package/src/types/generated-ui.ts

@@ -44,6 +44,21 @@ export interface PluginJobPathInput {
   signal?: AbortSignal
 }
 
+/**
+ * An existing file-backed analysis artifact chosen for a `Path` field. Only
+ * the database ids reach the plugin; it resolves, re-authorizes, and copies
+ * the file into job staging when the job is submitted.
+ */
+export interface PluginJobArtifactPathInput {
+  kind: 'artifact-path'
+  experimentId: number
+  artifactId: number
+  name: string
+  signal?: AbortSignal
+}
+
+export type PluginJobPathSelection = PluginJobPathInput | PluginJobArtifactPathInput
+
 export interface PluginJobPathUpload {
   token: string
   kind: 'file' | 'directory'

package/src/types/index.ts

@@ -35,8 +35,6 @@ export type {
   PillNavItemInput,
   PageSelectorItem,
   PageSelectorItemInput,
-  PluginSwitcherPlugin,
-  PluginSwitcherInfo,
   AccountMenuItem,
   // Well Plate types
   WellPlateFormat,
@@ -63,8 +61,7 @@ export type {
   ColumnCondition,
   RowCondition,
   Rack,
-  RackSampleDropContext,
-  RackSampleDropMapper,
+  PlateEditorClearConfirm,
   // Sample Legend types
   SampleType,
   // Plate Map Editor types
@@ -81,6 +78,7 @@ export type {
   // SegmentedControl types
   SegmentedOption,
   SegmentedOptionInput,
+  ChartLegendItem,
   SegmentedControlVariant,
   SegmentedControlSize,
   // MultiSelect types
@@ -108,7 +106,6 @@ export type {
   // StatusIndicator types
   StatusType,
   // ProgressBar types
-  ProgressVariant,
   ProgressSize,
   // Avatar types
   AvatarSize,
@@ -147,6 +144,7 @@ export type {
   BatchSummary,
   // TimePicker types
   TimePickerFormat,
+  TimeSlotDisabledFn,
   TimeRange,
   // Schedule types
   ScheduleView,
@@ -176,6 +174,8 @@ export type {
   // FitPanel types
   FitState,
   FitResultSummary,
+  FitSeries,
+  FitColumnLabels,
   // ReagentList types
   StorageCondition,
   ReagentColumn,
@@ -218,9 +218,11 @@ export type {
   FileBrowserLocation,
   FileBrowserSortKey,
   FileDirectoryListing,
+  FileDirectoryTree,
   FileEntry,
   FileEntryKind,
   FilePathCrumb,
+  FileSearchResult,
   FileSelection,
   ServerMount,
 } from './fileBrowserTypes'
@@ -237,10 +239,14 @@ export type {
 
 export type {
   InstrumentAlert,
-  InstrumentAlertBody,
   InstrumentAlertLevel,
+  InstrumentAlertList,
+  InstrumentBadgeState,
+  InstrumentLiveProgress,
+  InstrumentLiveStatus,
   InstrumentState,
   InstrumentStatus,
+  InstrumentStatusReporter,
   SampleInfo,
   SampleInfo as InstrumentSampleInfo,
   SequenceProgress,
@@ -292,11 +298,6 @@ export type {
 export type {
   AuthConfig,
   UserInfo,
-  LoginResponse,
-  TokenVerifyResponse,
-  RegisterRequest,
-  UpdateProfileRequest,
-  CredentialInfo,
 } from './auth'
 
 // Platform types

package/src/types/instrument.ts

@@ -22,6 +22,7 @@ export interface SequenceProgress {
   sample_durations?: readonly number[]
 }
 
+/** @deprecated Scheduled for removal in MINT 1.4; instrument monitor types move to the mld-ms plugins. */
 export interface InstrumentStatus {
   instrument_id: string
   instrument_name?: string | null
@@ -39,24 +40,55 @@ export interface InstrumentStatus {
   method_elapsed_pct?: number | null
 }
 
-export interface InstrumentAlertBody {
-  source?: string | null
-  event?: string | null
-  detail: string
-  code?: number | null
-  raw_file?: string | null
+/** A state the platform derives for an instrument: its reported state, `never` (no report yet) or `inactive`. */
+export type InstrumentBadgeState = InstrumentState | 'never' | 'inactive'
+
+/** Sequence progress in a live status report; `sample_durations` covers the current sequence only. */
+export type InstrumentLiveProgress = SequenceProgress & {
+  elapsed_seconds: number
+  sample_durations: number[]
+}
+
+/** The plugin that reported a live status, resolved from the plugin registry at read time. */
+export interface InstrumentStatusReporter {
+  name: string
+  display_name: string
+  route_prefix: string
+  serves_instrument_alerts: boolean
 }
 
+/** Latest live snapshot the platform holds for one instrument (`InstrumentRecord.live_status`). */
+export interface InstrumentLiveStatus {
+  instrument_id: string
+  /** `disconnected` once `last_seen` is older than 60 s. */
+  state: InstrumentState
+  active_method?: string | null
+  current_sample?: SampleInfo | null
+  sequence_progress?: InstrumentLiveProgress | null
+  has_unacknowledged_alerts: boolean
+  has_unacknowledged_critical: boolean
+  /** Server receive time of the latest report (ISO 8601). */
+  last_seen: string
+  /** When the state last changed (ISO 8601). */
+  state_since: string
+  reported_by: string
+  /** Null when the reporting plugin is not loaded. */
+  reporter: InstrumentStatusReporter | null
+}
+
+/** An alert served by the reporting plugin at `{route_prefix}/api/instruments/{id}/alerts`. */
 export interface InstrumentAlert {
-  id?: string
-  event_key: string
+  id: 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
+  message: string
+  timestamp: string
+  acknowledged: boolean
+  acknowledged_by?: string | null
+  acknowledged_at?: string | null
+}
+
+export interface InstrumentAlertList {
+  alerts: InstrumentAlert[]
+  total: number
 }

package/src/types/platform.ts

@@ -4,6 +4,8 @@ import type { RoleInfo } from '../permissions'
 export interface PluginInfo {
   id: string
   name: string
+  /** Name to show in the UI; the platform falls back to the plugin ID. Absent before MINT 1.3. */
+  display_name?: string
   version: string
   plugin_type?: string
   description?: string

package/src/utils/color.ts

@@ -36,7 +36,22 @@ export const SAMPLE_COLOR_SCALE: readonly string[] = [
 ]
 
 /**
- * Slot-position colors shared by `PlateMapEditor` and `RackEditor`.
+ * Group palette as CSS tokens (3a): groups always take `--mint-sample-1` …
+ * `--mint-sample-8`; the 9th (gray) stays out of the group cycle.
+ */
+export const SAMPLE_GROUP_TOKENS: readonly string[] = [
+  'var(--mint-sample-1)',
+  'var(--mint-sample-2)',
+  'var(--mint-sample-3)',
+  'var(--mint-sample-4)',
+  'var(--mint-sample-5)',
+  'var(--mint-sample-6)',
+  'var(--mint-sample-7)',
+  'var(--mint-sample-8)',
+]
+
+/**
+ * Slot-position colors (R/G/B/Y rack positions).
  * Mirrors `--mint-slot-r`, `--mint-slot-g`, `--mint-slot-b`, `--mint-slot-y`.
  */
 export const SLOT_COLORS: Record<SlotPosition, string> = {

package/src/utils/formModelSync.ts

@@ -37,7 +37,7 @@ export function formSchemaFieldNames(schema: FormSchema): string[] {
   return sections.flatMap(section => section.fields.map(field => field.name))
 }
 
-function valuesEqual(left: unknown, right: unknown): boolean {
+export 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]))

package/src/utils/plotlyTemplate.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared Plotly look (SDK control refresh 9a), resolved from the MINT tokens.
+ *
+ * Plotly cannot read `var(--…)`, so the tokens are resolved to computed values
+ * at call time; call it again after a theme change. PlotlyChart applies it by
+ * default. For a raw Plotly chart use `{ template: mintPlotlyTemplate() }`.
+ */
+import type { LayoutAxis, Template } from 'plotly.js-dist-min'
+
+import { SAMPLE_COLOR_SCALE, SAMPLE_GROUP_TOKENS } from './color'
+
+/** Resolve tokens from `element` (default: `<html>`), falling back to `<html>` for detached elements. */
+export function mintPlotlyTemplate(element?: Element): Template {
+  const root = getComputedStyle(document.documentElement)
+  const own = element ? getComputedStyle(element) : root
+  const token = (name: string): string | undefined =>
+    own.getPropertyValue(name).trim() || root.getPropertyValue(name).trim() || undefined
+
+  const axis: Partial<LayoutAxis> = {
+    gridcolor: token('--border-light'),
+    linecolor: token('--border-color'),
+    zerolinecolor: token('--border-color'),
+    tickfont: { family: token('--font-mono'), size: 11, color: token('--text-secondary') },
+  }
+  const font = { family: token('--font-sans'), size: 12, color: token('--text-primary') }
+
+  return {
+    layout: {
+      paper_bgcolor: 'rgba(0,0,0,0)',
+      plot_bgcolor: 'rgba(0,0,0,0)',
+      // Group tokens (`var(--…)` stripped to the property name); the hex scale covers pages without the SDK CSS.
+      colorway: SAMPLE_GROUP_TOKENS.map((ref, index) => token(ref.slice(4, -1)) ?? SAMPLE_COLOR_SCALE[index]),
+      font,
+      xaxis: { ...axis, showline: true },
+      yaxis: axis,
+      hoverlabel: { bgcolor: token('--bg-card'), bordercolor: token('--border-color'), font },
+    },
+  }
+}