@morscherlab/mint-sdk 1.2.0-beta.2 → 1.2.0-beta.20

package/src/components/WellPlate.geometry.ts

@@ -37,8 +37,67 @@ export const WELL_PLATE_SIZE_CONFIGS: Record<WellPlateSize, WellPlateSizeConfig>
   fill: { cellWidth: '100%', cellHeight: '32px', headerWidth: '32px', headerHeight: '24px', fontSize: '0.75rem', gap: '2px' },
 }
 
+/**
+ * Spreadsheet-style row label for a zero-based row index: A…Z, then AA, AB, …
+ *
+ * This is the single row-label generator for the SDK — plate grids, rack
+ * grids, well-id parsing and the template builders all go through it.
+ */
+export function rowLabel(index: number): string {
+  let label = ''
+  let current = index
+  for (;;) {
+    label = String.fromCharCode(65 + (current % 26)) + label
+    current = Math.floor(current / 26) - 1
+    if (current < 0) return label
+  }
+}
+
+/** Inverse of {@link rowLabel}: 'A' → 0, 'Z' → 25, 'AA' → 26. */
+export function rowIndex(label: string): number {
+  return [...label].reduce((value, char) => value * 26 + char.charCodeAt(0) - 64, 0) - 1
+}
+
 export function createPlateRowLabels(config: WellPlateConfig): string[] {
-  return Array.from({ length: config.rows }, (_, index) => String.fromCharCode(65 + index))
+  return Array.from({ length: config.rows }, (_, index) => rowLabel(index))
+}
+
+function plateConfigOrThrow(format: number): WellPlateConfig {
+  const config = PLATE_CONFIGS[format as WellPlateFormat]
+  if (!config) throw new Error(`Unsupported plate format '${format}'.`)
+  return config
+}
+
+/** Every well id of a plate, row-major (A1, A2, … B1, …). */
+export function wellIdsForFormat(format: number): string[] {
+  const { rows, cols } = plateConfigOrThrow(format)
+  return Array.from({ length: rows }, (_, row) =>
+    Array.from({ length: cols }, (_col, col) => `${rowLabel(row)}${col + 1}`)
+  ).flat()
+}
+
+/** Throw unless `wellId` names a well that exists on a `format`-well plate. */
+export function assertWellInFormat(wellId: string, format: number): void {
+  const { rows, cols } = plateConfigOrThrow(format)
+  const match = /^([A-Z]+)([1-9][0-9]*)$/.exec(wellId.toUpperCase())
+  if (!match) {
+    throw new Error(`Invalid well id '${wellId}'.`)
+  }
+  const row = rowIndex(match[1])
+  const col = Number(match[2]) - 1
+  if (row < 0 || col < 0 || row >= rows || col >= cols) {
+    throw new Error(`Well '${wellId}' is outside a ${format}-well plate.`)
+  }
+}
+
+/** Coerce an unknown value to a supported plate format, else `fallback`. */
+export function readPlateFormat(value: unknown, fallback: WellPlateFormat): WellPlateFormat {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number(value)
+      : Number.NaN
+  return parsed in PLATE_CONFIGS ? (parsed as WellPlateFormat) : fallback
 }
 
 export function createPlateColumnLabels(config: WellPlateConfig): number[] {

package/src/components/WellPlate.interaction.ts

@@ -11,6 +11,7 @@ import {
   type WellPlateCoordinate,
 } from './WellPlate.geometry'
 import { parseDroppedSampleTransfer } from './WellPlate.sampleDrop'
+import { useReorderAnnouncer } from '../composables/useListReorder'
 
 export interface WellPlateInteractionOptions {
   modelValue: () => string[]
@@ -64,6 +65,7 @@ export function useWellPlateInteraction(options: WellPlateInteractionOptions) {
   const hoveredWell = ref<string | null>(null)
   const editingWellId = ref<string | null>(null)
   const editPopupPosition = ref({ x: 0, y: 0 })
+  const { announcement, announce, announcerStyle } = useReorderAnnouncer()
 
   const selectedWellSet = computed(() => new Set(options.modelValue()))
 
@@ -215,6 +217,45 @@ export function useWellPlateInteraction(options: WellPlateInteractionOptions) {
     dragTargetWell.value = null
   }
 
+  // Keyboard alternative to the well-to-well drag. The plate is a 2D grid, not a
+  // list, so it cannot use `useListReorder`'s index maths: instead Alt+Enter (or
+  // Alt+Space) picks a filled well up, the same chord on another well drops it
+  // there, and Escape cancels. Every step is announced politely.
+  function handleWellMoveKeydown(well: Well, event: KeyboardEvent) {
+    if (options.disabled() || options.readonly() || options.selectionMode() !== 'drag') return
+
+    if (event.key === 'Escape' && dragSourceWell.value) {
+      event.preventDefault()
+      announce(`Move cancelled. ${dragSourceWell.value} stays in place.`)
+      dragSourceWell.value = null
+      dragTargetWell.value = null
+      return
+    }
+
+    if (!event.altKey || (event.key !== 'Enter' && event.key !== ' ')) return
+    event.preventDefault()
+
+    const source = dragSourceWell.value
+    if (!source) {
+      if (!well.sampleType) {
+        announce(`Well ${well.id} is empty and cannot be moved.`)
+        return
+      }
+      dragSourceWell.value = well.id
+      announce(`Well ${well.id} picked up. Move to another well and press Alt and Enter to drop it.`)
+      return
+    }
+
+    if (source !== well.id) {
+      options.emitWellMove(source, well.id)
+      announce(`Well ${source} moved to ${well.id}.`)
+    } else {
+      announce(`Move cancelled. ${source} stays in place.`)
+    }
+    dragSourceWell.value = null
+    dragTargetWell.value = null
+  }
+
   function parseDroppedSample(event: DragEvent, wellId: string): WellSampleDropData | null {
     const customParser = options.sampleDropParser()
     if (customParser) return customParser(event, { wellId, event }) ?? null
@@ -267,6 +308,9 @@ export function useWellPlateInteraction(options: WellPlateInteractionOptions) {
     handleDragLeave,
     handleDrop,
     handleDragEnd,
+    handleWellMoveKeydown,
     handleKeyDown,
+    moveAnnouncement: announcement,
+    moveAnnouncerStyle: announcerStyle,
   }
 }

package/src/components/WellPlate.story.vue

@@ -121,6 +121,8 @@ const doseWells = generateDoseWells()
 
 function initState() {
   return {
+    loading: false,
+    error: '',
     format: 96 as WellPlateFormat,
     selectionMode: 'multiple' as WellPlateSelectionMode,
     size: 'md' as WellPlateSize,
@@ -141,6 +143,8 @@ function initState() {
       <template #default="{ state }">
         <div style="padding: 2rem;">
           <WellPlate
+            :loading="state.loading"
+            :error="state.error || null"
             v-model="selectedWells"
             :format="state.format"
             :wells="generateMockWells(state.format)"
@@ -161,6 +165,10 @@ function initState() {
       </template>
 
       <template #controls="{ state }">
+
+        <HstCheckbox v-model="state.loading" title="Loading" />
+
+        <HstText v-model="state.error" title="Error Message" />
         <HstSelect
           v-model="state.format"
           title="Format"

package/src/components/WellPlate.vue

@@ -32,6 +32,7 @@ import {
   wellStyle,
 } from './WellPlate.rendering'
 import { DEFAULT_WELL_LEGEND_ITEMS } from './WellPlate.legend'
+import DataStateInternal from './internal/DataStateInternal.vue'
 
 interface Props {
   modelValue?: string[]
@@ -59,6 +60,19 @@ interface Props {
   rowConditions?: RowCondition[]
   allowSampleDrop?: boolean
   sampleDropParser?: WellSampleDropParser
+  /** Replace the plate grid with a loading placeholder. */
+  loading?: boolean
+  /**
+   * Error message. When set, the plate grid is replaced by an error state.
+   * `null`/`undefined` renders normally.
+   */
+  error?: string | null
+  /**
+   * Opt-in empty-state headline. A blank plate is meaningful, so the empty
+   * state only replaces the grid when this message is supplied and no wells
+   * carry data.
+   */
+  emptyMessage?: string
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -114,6 +128,12 @@ interface WellEditorSlotProps {
 
 defineSlots<{
   'well-editor'?: (props: WellEditorSlotProps) => unknown
+  /** Replaces the default loading placeholder. */
+  loading?: () => unknown
+  /** Replaces the default error placeholder. */
+  error?: (props: { error: string }) => unknown
+  /** Replaces the default empty placeholder. */
+  empty?: () => unknown
 }>()
 
 const plateRef = ref<HTMLElement | null>(null)
@@ -166,7 +186,10 @@ const {
   handleDragLeave,
   handleDrop,
   handleDragEnd,
+  handleWellMoveKeydown,
   handleKeyDown,
+  moveAnnouncement,
+  moveAnnouncerStyle,
 } = useWellPlateInteraction({
   modelValue: () => props.modelValue,
   selectionMode: () => props.selectionMode,
@@ -233,6 +256,11 @@ const containerStyle = computed(() =>
   }
 )
 
+/** Empty state is opt-in: it needs an `emptyMessage` and a plate with no well data. */
+const showEmptyState = computed(() =>
+  Boolean(props.emptyMessage) && Object.keys(props.wells).length === 0,
+)
+
 const tableStyle = computed(() => ({
   borderCollapse: 'separate' as const,
   borderSpacing: sizeConfig.value.gap,
@@ -246,7 +274,25 @@ const tableStyle = computed(() => ({
     :class="['mint-well-plate', isFillMode ? 'mint-well-plate--fill' : 'mint-well-plate--inline']"
     :style="containerStyle"
   >
-    <div class="mint-well-plate__scroll">
+    <div v-if="error" class="mint-well-plate__state">
+      <slot name="error" :error="error">
+        <DataStateInternal state="error" :title="error" />
+      </slot>
+    </div>
+
+    <div v-else-if="loading" class="mint-well-plate__state">
+      <slot name="loading">
+        <DataStateInternal state="loading" loading-label="Loading plate" />
+      </slot>
+    </div>
+
+    <div v-else-if="showEmptyState" class="mint-well-plate__state">
+      <slot name="empty">
+        <DataStateInternal state="empty" :title="emptyMessage" />
+      </slot>
+    </div>
+
+    <div v-else class="mint-well-plate__scroll">
       <div class="mint-well-plate__content">
         <table
           ref="tableRef"
@@ -390,8 +436,9 @@ const tableStyle = computed(() => ({
                 @dragleave="handleDragLeave"
                 @drop="handleDrop(well, $event)"
                 @dragend="handleDragEnd"
-                @keydown.enter="handleWellClick(well, $event as unknown as MouseEvent)"
-                @keydown.space.prevent="handleWellClick(well, $event as unknown as MouseEvent)"
+                @keydown="handleWellMoveKeydown(well, $event)"
+                @keydown.enter.exact="handleWellClick(well, $event as unknown as MouseEvent)"
+                @keydown.space.exact.prevent="handleWellClick(well, $event as unknown as MouseEvent)"
               >
                 <!-- Well label text (from metadata.label) -->
                 <span
@@ -489,9 +536,8 @@ const tableStyle = computed(() => ({
         />
       </slot>
     </template>
+
+    <!-- Keyboard well-move announcements for screen readers -->
+    <div role="status" aria-live="polite" :style="moveAnnouncerStyle">{{ moveAnnouncement }}</div>
   </div>
 </template>
-
-<style>
-@import '../styles/components/well-plate.css';
-</style>

package/src/components/fileBrowserPresentation.ts

@@ -0,0 +1,39 @@
+import type { FileEntry } from '../types/fileBrowserTypes'
+
+export const FILE_BROWSER_ICONS = {
+  disk: 'M4 5h16v14H4zM8 9h.01M4 12h16',
+  folder: 'M4 7h6l2 2h8v10H4z',
+  file: 'M14 3v5h5M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z',
+}
+
+export function formatCount(value: number): string {
+  // Thin spaces group digits without the comma/period ambiguity across locales.
+  return value.toLocaleString('en-US').replace(/,/g, ' ')
+}
+
+export function formatSize(entry: FileEntry): string {
+  if (entry.kind === 'directory') {
+    return entry.child_count === null || entry.child_count === undefined
+      ? '—'
+      : `${entry.child_count} item${entry.child_count === 1 ? '' : 's'}`
+  }
+  return formatBytes(entry.size_bytes ?? null)
+}
+
+export function formatBytes(bytes: number | null): string {
+  if (bytes === null) return '—'
+  const units = ['B', 'KB', 'MB', 'GB', 'TB']
+  let value = bytes
+  let unit = 0
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024
+    unit += 1
+  }
+  const rounded = value >= 100 || unit === 0 ? Math.round(value) : Number(value.toFixed(1))
+  return `${rounded} ${units[unit]}`
+}
+
+export function entryType(entry: FileEntry): string {
+  if (entry.kind === 'directory') return 'Folder'
+  return entry.extension ? entry.extension.replace('.', '').toUpperCase() : 'File'
+}

package/src/components/index.ts

@@ -7,12 +7,14 @@ export { default as BaseCheckbox } from './BaseCheckbox.vue'
 export { default as BaseToggle } from './BaseToggle.vue'
 export { default as BaseRadioGroup } from './BaseRadioGroup.vue'
 export { default as BaseSlider } from './BaseSlider.vue'
+/** Range slider with a gradient color track and color-coded value badge for threshold visualization. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `BaseSlider` instead. */
 export { default as ColorSlider } from './ColorSlider.vue'
 export { default as BaseTabs } from './BaseTabs.vue'
 export { default as BaseModal } from './BaseModal.vue'
 export { default as SegmentedControl } from './SegmentedControl.vue'
 export { default as MultiSelect } from './MultiSelect.vue'
 export { default as BasePill } from './BasePill.vue'
+/** Button that opens a dropdown menu for selecting one option from a list. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `ActionMenu` instead. */
 export { default as DropdownButton } from './DropdownButton.vue'
 export { default as Calendar } from './Calendar.vue'
 export { default as DataFrame } from './DataFrame.vue'
@@ -22,6 +24,7 @@ export { default as FormField } from './FormField.vue'
 export { default as DatePicker } from './DatePicker.vue'
 export { default as TimePicker } from './TimePicker.vue'
 export { default as TagsInput } from './TagsInput.vue'
+export { default as SecretInput } from './SecretInput.vue'
 export { default as NumberInput } from './NumberInput.vue'
 export { default as FileUploader } from './FileUploader.vue'
 
@@ -96,12 +99,17 @@ export { default as SampleHierarchyTree } from './SampleHierarchyTree.vue'
 export { default as ProtocolStepEditor } from './ProtocolStepEditor.vue'
 
 // Scientific display components
+export { default as PlotlyChart } from './PlotlyChart.vue'
 export { default as ScientificNumber } from './ScientificNumber.vue'
+/** Renders a chemical formula string (H₂O, C₆H₁₂O₆, Ca(OH)₂) with typographically correct subscripts and superscripts for charges. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; no platform replacement is planned. */
 export { default as ChemicalFormula } from './ChemicalFormula.vue'
 export { default as SequenceProgressBar } from './SequenceProgressBar.vue'
+/** Filterable instrument alert/event list keyed by each alert's required stable event_key. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; instrument UI moves to the mld-ms plugins. */
 export { default as InstrumentAlertLog } from './InstrumentAlertLog.vue'
 export { default as InstrumentStateBadge } from './InstrumentStateBadge.vue'
+/** Compact card for live instrument monitor status, sample, method, sequence progress, and ETA. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; instrument UI moves to the mld-ms plugins. */
 export { default as InstrumentStatusCard } from './InstrumentStatusCard.vue'
+/** Table for Xcalibur-compatible LCMS sequence rows with optional reorder/remove/duplicate controls. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; instrument UI moves to the mld-ms plugins. */
 export { default as LcmsSequenceTable } from './LcmsSequenceTable.vue'
 
 // Scientific input components
@@ -125,15 +133,21 @@ export { default as ExperimentCodeBadge } from './ExperimentCodeBadge.vue'
 
 // Scheduling / booking components
 export { default as DateTimePicker } from './DateTimePicker.vue'
+/** Paired start/end time pickers that validate range order and display computed duration. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `TimePicker` instead. */
 export { default as TimeRangeInput } from './TimeRangeInput.vue'
 export { default as ScheduleCalendar } from './ScheduleCalendar.vue'
+/** Card displaying a lab resource with availability status, specs, tags, and a book action. @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; no platform replacement is planned. */
 export { default as ResourceCard } from './ResourceCard.vue'
 export { default as SectionCard } from './SectionCard.vue'
 
 // Experiment / analysis components
 export { default as ExperimentSelectorModal } from './ExperimentSelectorModal.vue'
 export { default as ArtifactSelectorModal } from './ArtifactSelectorModal.vue'
+/** Modal picker over the read-only server mounts, recording paths rather than copying data. */
+export { default as FileBrowserModal } from './FileBrowserModal.vue'
 export { default as GeneratedPathInput } from './GeneratedPathInput.vue'
 export { default as ArtifactSaveDialog } from './ArtifactSaveDialog.vue'
 export { default as ExperimentPopover } from './ExperimentPopover.vue'
 export { default as FitPanel } from './FitPanel.vue'
+
+export { default as FilePicker } from './FilePicker.vue'

package/src/components/internal/AppTopBarPageSelectorInternal.vue

@@ -24,7 +24,7 @@ const emit = defineEmits<{
   select: [page: PageSelectorItem]
 }>()
 
-const { isOpen, rootRef, close, toggle } = useDropdownState()
+const { isOpen, rootRef, triggerRef, close, toggle } = useDropdownState()
 const normalizedPages = computed<PageSelectorItem[]>(() => props.pages.map(normalizeItemInput))
 
 const current = computed<PageSelectorItem | undefined>(() =>
@@ -45,6 +45,7 @@ function handleSelect(page: PageSelectorItem) {
 <template>
   <div ref="rootRef" class="mint-page-selector" :style="{ minWidth }">
     <button
+      ref="triggerRef"
       type="button"
       class="mint-page-selector__trigger"
       :class="{ 'mint-page-selector__trigger--open': isOpen }"
@@ -121,7 +122,3 @@ function handleSelect(page: PageSelectorItem) {
     </div>
   </div>
 </template>
-
-<style>
-@import '../../styles/components/app-page-selector.css';
-</style>

package/src/components/internal/AppTopBarPillNavInternal.vue

@@ -188,7 +188,3 @@ useEventListener(() => document, 'click', handleClickOutside)
     </div>
   </nav>
 </template>
-
-<style>
-@import '../../styles/components/app-pill-nav.css';
-</style>

package/src/components/internal/DataStateInternal.vue

@@ -0,0 +1,74 @@
+<script setup lang="ts">
+/**
+ * Shared loading / error / empty presentation for the SDK data components.
+ *
+ * Internal: not exported from the package entrypoints. Data components render
+ * this instead of hand-rolling their own placeholder markup so that the
+ * loading, error and empty states look the same everywhere.
+ */
+import { computed } from 'vue'
+import EmptyState from '../EmptyState.vue'
+import LoadingSpinner from '../LoadingSpinner.vue'
+
+/** Single-path warning triangle used for the error state. */
+const ERROR_ICON_PATH
+  = 'M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z'
+  + 'M12 9v4M12 17h.01'
+
+interface Props {
+  /** Which of the three placeholder states to render. */
+  state: 'loading' | 'error' | 'empty'
+  /** Headline for the empty/error state. */
+  title?: string
+  /** Supporting copy for the empty/error state. */
+  description?: string
+  /** Custom `<path d>` for the empty state icon (the error state has its own). */
+  iconPath?: string
+  /** Placeholder scale; also drives the loading spinner size. */
+  size?: 'sm' | 'md' | 'lg'
+  /** `EmptyState` layout variant. */
+  variant?: 'illustrated' | 'inline'
+  /** Accessible label (and visible caption) for the loading state. */
+  loadingLabel?: string
+  /** Optional call-to-action rendered under the empty/error copy. */
+  actionLabel?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  size: 'md',
+  variant: 'illustrated',
+  loadingLabel: 'Loading',
+})
+
+const emit = defineEmits<{
+  action: []
+}>()
+
+const spinnerSize = computed(() => (props.size === 'sm' ? 'sm' : props.size === 'lg' ? 'lg' : 'md'))
+</script>
+
+<template>
+  <div
+    :class="['mint-data-state', `mint-data-state--${state}`, `mint-data-state--${size}`]"
+    :data-state="state"
+  >
+    <template v-if="state === 'loading'">
+      <LoadingSpinner :size="spinnerSize" :label="loadingLabel" />
+      <p class="mint-data-state__loading-text" aria-hidden="true">{{ loadingLabel }}</p>
+    </template>
+    <EmptyState
+      v-else
+      :title="title"
+      :description="description"
+      :icon-path="state === 'error' ? ERROR_ICON_PATH : iconPath"
+      :color="state === 'error' ? 'error' : 'muted'"
+      :size="size"
+      :variant="variant"
+      :action-label="actionLabel"
+      @action="emit('action')"
+    >
+      <slot />
+    </EmptyState>
+  </div>
+</template>
+

package/src/components/internal/FileBrowserDialogInternal.vue

@@ -0,0 +1,75 @@
+<script setup lang="ts">
+import { onBeforeUnmount, onMounted, shallowRef, watch } from 'vue'
+import type { ModalSize } from '../../types'
+import { useFocusTrap } from '../../composables/useFocusTrap'
+import IconButton from '../IconButton.vue'
+
+const props = defineProps<{ open: boolean; label: string; size: ModalSize; variant?: 'picker' }>()
+const emit = defineEmits<{ close: [] }>()
+const containerRef = shallowRef<HTMLElement | null>(null)
+const active = shallowRef(false)
+useFocusTrap({ containerRef, active })
+
+// Activate after mounting so an initially open picker traps focus too.
+onMounted(() => {
+  active.value = props.open
+})
+watch(
+  () => props.open,
+  (open) => {
+    active.value = open
+  },
+)
+watch(
+  active,
+  (open, _, onCleanup) => {
+    if (!open) return
+    const overflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    onCleanup(() => {
+      document.body.style.overflow = overflow
+    })
+  },
+  { flush: 'sync' },
+)
+onBeforeUnmount(() => {
+  active.value = false
+})
+</script>
+
+<template>
+  <Teleport to="body">
+    <div v-if="open" class="mint-file-browser-overlay">
+      <section
+        ref="containerRef"
+        class="mint-file-browser-dialog"
+        :class="[
+          `mint-file-browser-dialog--${size}`,
+          variant === 'picker' ? 'mint-picker-dialog' : '',
+        ]"
+        role="dialog"
+        aria-modal="true"
+        :aria-label="label"
+        tabindex="-1"
+        @keydown.esc.stop.prevent="emit('close')"
+      >
+        <header class="mint-file-browser-dialog__header">
+          <slot name="header" />
+          <IconButton size="sm" label="Close modal" @click="emit('close')">
+            <svg
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              aria-hidden="true"
+            >
+              <path d="M6 6l12 12M18 6L6 18" />
+            </svg>
+          </IconButton>
+        </header>
+        <slot />
+        <footer class="mint-file-browser-dialog__footer"><slot name="footer" /></footer>
+      </section>
+    </div>
+  </Teleport>
+</template>