@morscherlab/mint-sdk 1.2.0-beta.7 → 1.2.0-beta.9

package/src/composables/useRackEditor.ts

@@ -1,5 +1,6 @@
 import { ref, computed, type Ref, type ComputedRef } from 'vue'
 import type { Rack, SlotPosition, WellPlateFormat, Well } from '../types'
+import { PLATE_CONFIGS, rowLabel as plateRowLabel } from '../components/WellPlate.geometry'
 
 export interface UseRackEditorOptions {
   defaultFormat?: WellPlateFormat
@@ -31,15 +32,6 @@ export interface UseRackEditorReturn {
 
 const SLOT_CYCLE: SlotPosition[] = ['R', 'G', 'B', 'Y']
 
-const PLATE_CONFIGS: 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 },
-}
 
 let globalIdCounter = 0
 
@@ -156,8 +148,7 @@ export function useRackEditor(
     let counter = 1
     for (let row = 0; row < config.rows; row++) {
       for (let col = 0; col < config.cols; col++) {
-        const rowLabel = String.fromCharCode(65 + row)
-        const wellId = `${rowLabel}${col + 1}`
+        const wellId = `${plateRowLabel(row)}${col + 1}`
         // Only fill empty wells
         if (!rack.wells[wellId]?.sampleType) {
           const paddedNum = String(counter).padStart(3, '0')

package/src/composables/useRequestSyncState.ts

@@ -1,10 +1,28 @@
 import { ref, type Ref } from 'vue'
+import { readErrorMessage as readSharedErrorMessage } from '../utils/errors'
 
 export type RequestSyncSuccessKind = 'load' | 'save' | 'run'
 
+/**
+ * The unit of work `run()` drives.
+ *
+ * It receives an `AbortSignal` that fires when the run is superseded by a
+ * newer `run()` or by `cancel()`. Zero-argument operations stay valid and
+ * simply ignore it.
+ */
+export type RequestSyncOperation<T> = (signal: AbortSignal) => Promise<T>
+
 export interface RequestSyncRunOptions {
   success?: RequestSyncSuccessKind
   errorMessage?: string
+  /**
+   * Abort the previously started run when this one starts. Default `true`;
+   * pass `false` to let overlapping runs finish their own work (the stale
+   * guard on shared state still applies either way).
+   */
+  abortPrevious?: boolean
+  /** Caller-owned signal; aborting it aborts this run's signal too. */
+  signal?: AbortSignal
 }
 
 export interface UseRequestSyncStateReturn {
@@ -30,8 +48,32 @@ export interface UseRequestSyncStateReturn {
   markSaved: (date?: Date) => void
   /** Mark the operation as successfully run. */
   markRun: (date?: Date) => void
-  /** Run a request with shared loading/error handling and optional sync marking. */
-  run: <T>(operation: () => Promise<T>, options?: RequestSyncRunOptions) => Promise<T>
+  /**
+   * Run a request with shared loading/error handling and optional sync marking.
+   *
+   * ## Stale-response semantics
+   *
+   * Every call takes a monotonically increasing token. Starting a run
+   * supersedes any run started before it, and a superseded run writes **no**
+   * shared state when it finally settles: it does not clear `loading`, does not
+   * set `error`, and does not move `lastLoadedAt` / `lastSavedAt` / `lastRunAt`.
+   * Only the newest run owns those.
+   *
+   * The caller's own promise is untouched by the guard — a superseded run still
+   * resolves with its value or rejects with its own error, exactly as the
+   * operation did. The guard never invents a rejection, so a caller awaiting
+   * `run()` never sees a "superseded" error it did not cause.
+   *
+   * The operation additionally receives an `AbortSignal` that fires when its
+   * run is superseded or `cancel()` is called, so an operation that forwards
+   * the signal (`fetch(url, { signal })`) stops work instead of racing.
+   */
+  run: <T>(operation: RequestSyncOperation<T>, options?: RequestSyncRunOptions) => Promise<T>
+  /**
+   * Abort the in-flight run and drop `loading`. The aborted run's completion
+   * is treated as stale and writes no state.
+   */
+  cancel: () => void
 }
 
 /** Shared loading/error/timestamp state for generated plugin request helpers. */
@@ -49,22 +91,7 @@ export function useRequestSyncState(
   }
 
   function readErrorMessage(value: unknown, fallback = defaultErrorMessage): 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
-    ) {
-      return (value as { message: string }).message
-    }
-    return fallback
+    return readSharedErrorMessage(value, fallback)
   }
 
   function setError(value: unknown, fallback?: string): string {
@@ -85,27 +112,69 @@ export function useRequestSyncState(
     lastRunAt.value = date
   }
 
+  // Monotonic token guarding every write to the shared loading/error/timestamp
+  // state. Overlapping runs settle in any order, and a superseded one must not
+  // clear a newer run's loading flag or overwrite its error.
+  let runToken = 0
+  let activeController: AbortController | null = null
+
+  function cancel(): void {
+    runToken += 1
+    activeController?.abort()
+    activeController = null
+    loading.value = false
+  }
+
   async function run<T>(
-    operation: () => Promise<T>,
+    operation: RequestSyncOperation<T>,
     options: RequestSyncRunOptions = {},
   ): Promise<T> {
+    if (options.abortPrevious !== false) {
+      activeController?.abort()
+    }
+
+    const token = (runToken += 1)
+    const controller = new AbortController()
+    activeController = controller
+
+    const callerSignal = options.signal
+    if (callerSignal) {
+      if (callerSignal.aborted) controller.abort(callerSignal.reason)
+      else callerSignal.addEventListener(
+        'abort',
+        () => controller.abort(callerSignal.reason),
+        { once: true },
+      )
+    }
+
+    const isCurrent = (): boolean => token === runToken
+
     loading.value = true
     clearError()
     try {
-      const response = await operation()
-      if (options.success === 'load') {
-        markLoaded()
-      } else if (options.success === 'save') {
-        markSaved()
-      } else if (options.success === 'run') {
-        markRun()
+      const response = await operation(controller.signal)
+      if (isCurrent()) {
+        if (options.success === 'load') {
+          markLoaded()
+        } else if (options.success === 'save') {
+          markSaved()
+        } else if (options.success === 'run') {
+          markRun()
+        }
       }
       return response
     } catch (err) {
-      setError(err, options.errorMessage)
+      if (isCurrent()) {
+        setError(err, options.errorMessage)
+      }
       throw err
     } finally {
-      loading.value = false
+      if (isCurrent()) {
+        loading.value = false
+      }
+      if (activeController === controller) {
+        activeController = null
+      }
     }
   }
 
@@ -122,5 +191,6 @@ export function useRequestSyncState(
     markSaved,
     markRun,
     run,
+    cancel,
   }
 }

package/src/composables/useResourceCrud.ts

@@ -1,4 +1,5 @@
 import { computed, ref, shallowRef, type ComputedRef, type Ref, type ShallowRef } from 'vue'
+import { readErrorMessage } from '../utils/errors'
 
 export type ResourceKey = string | number
 
@@ -232,18 +233,3 @@ function resolveKey<TItem, TKey extends ResourceKey>(
   }
   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/useScheduleDrag.ts

@@ -200,6 +200,42 @@ export function useScheduleDrag(options: UseScheduleDragOptions) {
     cleanup()
   }
 
+  /**
+   * Keyboard alternative to the pointer drag: shifts an event by one slot
+   * (`mode: 'move'`) or grows/shrinks its end by one slot (`mode: 'resize'`),
+   * staying inside the visible day. Returns whether the nudge was applied.
+   */
+  function nudgeEvent(
+    event: ScheduleEvent,
+    direction: -1 | 1,
+    mode: 'move' | 'resize' = 'move',
+  ): boolean {
+    if (options.readonly.value) return false
+    if (mode === 'move' && event.draggable === false) return false
+    if (mode === 'resize' && event.resizable === false) return false
+
+    const slotMin = options.slotDuration.value
+    const dayStart = options.dayStartHour.value * 60
+    const dayEnd = options.dayEndHour.value * 60
+    const start = dateToMinutes(new Date(event.start))
+    const end = dateToMinutes(new Date(event.end))
+
+    const nextStart = mode === 'move' ? start + direction * slotMin : start
+    const nextEnd = mode === 'move'
+      ? end + direction * slotMin
+      : Math.max(start + slotMin, end + direction * slotMin)
+
+    if (nextStart < dayStart || nextEnd > dayEnd || nextEnd <= nextStart) return false
+
+    const base = new Date(event.start)
+    const newStart = minutesToDate(base, nextStart)
+    const newEnd = minutesToDate(base, nextEnd)
+
+    if (mode === 'move') options.onMoveComplete?.(event, newStart, newEnd)
+    else options.onResizeComplete?.(event, newStart, newEnd)
+    return true
+  }
+
   function addListeners() {
     document.addEventListener('pointermove', onPointerMove)
     document.addEventListener('pointerup', onPointerUp)
@@ -221,6 +257,7 @@ export function useScheduleDrag(options: UseScheduleDragOptions) {
     startCreate,
     startMove,
     startResize,
+    nudgeEvent,
   }
 }
 

package/src/composables/useWellPainting.ts

@@ -1,5 +1,10 @@
 import { computed, ref, toValue, type ComputedRef, type Ref } from 'vue'
 import type { WellPlateFormat } from '../types'
+import {
+  PLATE_CONFIGS as PLATE_DIMENSIONS,
+  rowIndex as rowLabelToIndex,
+  rowLabel as indexToRowLabel,
+} from '../components/WellPlate.geometry'
 
 export type WellPlateSource<T> = T | Ref<T> | ComputedRef<T> | (() => T)
 
@@ -34,17 +39,6 @@ export interface UseWellPaintingReturn<TMode extends string = string, TPayload =
   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.
@@ -170,22 +164,4 @@ export function wellIdsInRectangle(
   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/useWellPlateEditor.ts

@@ -5,18 +5,8 @@ import type {
   SampleType,
   WellPlateFormat,
 } from '../types'
+import { SAMPLE_COLOR_SCALE as DEFAULT_PALETTE } from '../utils/color'
 
-const DEFAULT_PALETTE = [
-  '#3B82F6', // blue
-  '#10B981', // green
-  '#EF4444', // red
-  '#F59E0B', // amber
-  '#8B5CF6', // purple
-  '#F97316', // orange
-  '#06B6D4', // cyan
-  '#14B8A6', // teal
-  '#6B7280', // gray
-]
 
 const MAX_HISTORY = 50
 

package/src/permissions.ts

@@ -2,7 +2,6 @@ export const ADMIN_ROLE = 'admin'
 
 export const ADMIN_PANEL_PERMISSIONS = [
   'users.view',
-  'users.invite',
   'users.manage',
   'platform.configure',
   'platform.view_logs',
@@ -41,11 +40,36 @@ export interface AccessPolicy {
   plugin?: string
 }
 
+/**
+ * An object that carries an access rule.
+ *
+ * The nested `access` policy is the supported shape. The four flat fields are
+ * the pre-1.2 spelling of the same four `AccessPolicy` fields; they still work
+ * but are deprecated, and `normalizeAccessPolicy()` lets the nested policy win
+ * wherever both are given.
+ */
 export interface AccessControlled {
+  /** The access policy. Preferred over the flat fields below. */
   access?: AccessPolicy
+  /**
+   * @deprecated Since MINT 1.2; use `access.visibleFor` instead. The flat
+   * duplicate is removed in 1.3.
+   */
   visibleFor?: AccessAudienceInput
+  /**
+   * @deprecated Since MINT 1.2; use `access.requiresAdmin` instead. The flat
+   * duplicate is removed in 1.3.
+   */
   requiresAdmin?: boolean
+  /**
+   * @deprecated Since MINT 1.2; use `access.permissions` instead. The flat
+   * duplicate is removed in 1.3.
+   */
   permissions?: readonly string[]
+  /**
+   * @deprecated Since MINT 1.2; use `access.anyPermissions` instead. The flat
+   * duplicate is removed in 1.3.
+   */
   anyPermissions?: readonly string[]
 }
 
@@ -105,17 +129,32 @@ export function canAccessPlugin(
   return Array.isArray(access) && access.includes(pluginName)
 }
 
+/**
+ * Flatten an access rule — either shape, or a mix of both — into one policy.
+ *
+ * ## Precedence
+ *
+ * 1. A defined field on the nested `access` policy wins. It is the supported
+ *    spelling, so an object that carries both shapes is read as "the nested
+ *    policy, with the deprecated flat fields as leftovers".
+ * 2. Otherwise the flat field on the rule itself is used.
+ * 3. A field set to `undefined` on either side counts as unset and never
+ *    masks the other side.
+ *
+ * Only `AccessPolicy` fields the flat shape never had (`audience`,
+ * `requiresAuth`, `plugin`) can come from the nested policy alone; the four
+ * duplicated fields are the ones this ordering exists for.
+ */
 export function normalizeAccessPolicy(rule: AccessControlled | AccessPolicy | undefined): AccessPolicy {
   if (!rule) return {}
-  const { access: nested, ...direct } = rule as AccessPolicy & { access?: AccessPolicy }
-  return {
-    ...(nested ?? {}),
-    ...direct,
-    ...('visibleFor' in rule && rule.visibleFor !== undefined ? { visibleFor: rule.visibleFor } : {}),
-    ...('requiresAdmin' in rule && rule.requiresAdmin !== undefined ? { requiresAdmin: rule.requiresAdmin } : {}),
-    ...('permissions' in rule && rule.permissions !== undefined ? { permissions: rule.permissions } : {}),
-    ...('anyPermissions' in rule && rule.anyPermissions !== undefined ? { anyPermissions: rule.anyPermissions } : {}),
+  const { access: nested, ...flat } = rule as AccessPolicy & { access?: AccessPolicy }
+  const policy = { ...flat } as Record<string, unknown>
+
+  for (const [field, value] of Object.entries(nested ?? {})) {
+    if (value !== undefined) policy[field] = value
   }
+
+  return policy as AccessPolicy
 }
 
 export function canAccessByPolicy(

package/src/stores/experiment.ts

@@ -1,6 +1,7 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 import { useApi } from '../composables/useApi'
+import { readErrorMessage } from '../utils/errors'
 import type { ExperimentSummary, PlatformContext } from '../types'
 
 function getPlatformApiUrl(): string | undefined {
@@ -9,12 +10,6 @@ function getPlatformApiUrl(): string | undefined {
     ?.platformApiUrl
 }
 
-function readErrorMessage(value: unknown): string {
-  if (value instanceof Error && value.message) return value.message
-  if (typeof value === 'string' && value.trim()) return value
-  return 'Failed to load experiment'
-}
-
 /**
  * The single source of truth for the experiment a plugin is currently working on.
  *
@@ -89,7 +84,7 @@ export const useExperimentStore = defineStore('mint-experiment', () => {
     } catch (err) {
       if (token !== selectionToken) return null
       current.value = null
-      error.value = readErrorMessage(err)
+      error.value = readErrorMessage(err, 'Failed to load experiment')
       return null
     } finally {
       // Only the newest request owns the loading flag; otherwise a superseded

package/src/stores/index.ts

@@ -1,3 +1,11 @@
 export { useAuthStore } from './auth'
-export { useSettingsStore, colorPalettes, type SettingsState } from './settings'
+export {
+  useSettingsStore,
+  tryUseSettingsStore,
+  colorPalettes,
+  paletteCssVariables,
+  tableDensityToSize,
+  PALETTE_CSS_VARIABLES,
+  type SettingsState,
+} from './settings'
 export { useExperimentStore } from './experiment'

package/src/stores/settings.ts

@@ -1,4 +1,4 @@
-import { defineStore } from 'pinia'
+import { defineStore, getActivePinia } from 'pinia'
 import { ref, watch } from 'vue'
 import type { ThemeMode, ColorPalette, TableDensity } from '../types'
 
@@ -62,6 +62,46 @@ export const colorPalettes: Record<ColorPalette, { name: string; hues: [number,
   pastel: { name: 'Pastel', hues: [200, 340] },
 }
 
+/**
+ * Custom properties a non-default palette overrides on `<html>`.
+ *
+ * The saturation/lightness pairs are lifted from the canonical indigo/orange
+ * tokens in `styles/variables.css` so only the hue moves; the `default`
+ * palette writes nothing at all and the stylesheet values stand.
+ */
+export const PALETTE_CSS_VARIABLES = [
+  '--color-primary',
+  '--color-primary-hover',
+  '--color-primary-soft',
+  '--color-cta',
+  '--color-cta-hover',
+] as const
+
+/** Build the `<html>` custom-property overrides for a palette. */
+export function paletteCssVariables(palette: ColorPalette): Record<string, string> {
+  if (palette === 'default') return {}
+  const [primaryHue, accentHue] = colorPalettes[palette].hues
+  return {
+    '--color-primary': `hsl(${primaryHue} 84% 67%)`,
+    '--color-primary-hover': `hsl(${primaryHue} 75% 59%)`,
+    '--color-primary-soft': `hsl(${primaryHue} 84% 67% / 0.12)`,
+    '--color-cta': `hsl(${accentHue} 95% 53%)`,
+    '--color-cta-hover': `hsl(${accentHue} 90% 48%)`,
+  }
+}
+
+/** `DataFrame`-style size that each table density maps onto. */
+const DENSITY_TABLE_SIZE: Record<TableDensity, 'sm' | 'md' | 'lg'> = {
+  compact: 'sm',
+  normal: 'md',
+  comfortable: 'lg',
+}
+
+/** Map a table density onto the `size` prop shared by the SDK table components. */
+export function tableDensityToSize(density: TableDensity): 'sm' | 'md' | 'lg' {
+  return DENSITY_TABLE_SIZE[density]
+}
+
 function loadSettings(): SettingsState {
   try {
     const stored = localStorage.getItem(STORAGE_KEY)
@@ -152,6 +192,8 @@ export const useSettingsStore = defineStore('mint-settings', () => {
     tableDensity.value = loaded.tableDensity
 
     applyTheme()
+    applyPalette()
+    applyDensity()
   }
 
   function applyTheme() {
@@ -160,11 +202,36 @@ export const useSettingsStore = defineStore('mint-settings', () => {
     document.documentElement.classList.toggle('dark', dark)
   }
 
+  /**
+   * Write the selected palette's hues onto `<html>` as custom-property
+   * overrides. The `default` palette clears them so `styles/variables.css`
+   * keeps ownership of the brand colors.
+   */
+  function applyPalette() {
+    if (typeof document === 'undefined') return
+    const style = document.documentElement.style
+    const overrides = paletteCssVariables(colorPalette.value)
+    for (const name of PALETTE_CSS_VARIABLES) {
+      const value = overrides[name]
+      if (value) style.setProperty(name, value)
+      else style.removeProperty(name)
+    }
+  }
+
+  /** Mirror the table density onto `<html data-density>` for CSS consumers. */
+  function applyDensity() {
+    if (typeof document === 'undefined') return
+    document.documentElement.dataset.density = tableDensity.value
+  }
+
   watch(theme, () => {
     applyTheme()
     persistSettings()
   })
 
+  watch(colorPalette, applyPalette)
+  watch(tableDensity, applyDensity)
+
   if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
     window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (event) => {
       systemPrefersDark.value = event.matches
@@ -206,6 +273,11 @@ export const useSettingsStore = defineStore('mint-settings', () => {
     return colorPalettes[colorPalette.value].hues
   }
 
+  /** The `size` the SDK table components default to for the current density. */
+  function getTableSize(): 'sm' | 'md' | 'lg' {
+    return tableDensityToSize(tableDensity.value)
+  }
+
   function isDark(): boolean {
     return theme.value === 'system' ? systemPrefersDark.value : theme.value === 'dark'
   }
@@ -222,11 +294,31 @@ export const useSettingsStore = defineStore('mint-settings', () => {
     tableDensity,
     initialize,
     applyTheme,
+    applyPalette,
+    applyDensity,
     persistSettings,
     resetToDefaults,
     getPaletteHues,
+    getTableSize,
     isDark,
     getApiBaseUrl,
     getWsBaseUrl,
   }
 })
+
+/**
+ * Read the settings store without requiring Pinia to be installed.
+ *
+ * SDK components are mounted standalone (unit tests, Histoire stories, plugin
+ * previews) where no Pinia instance exists. They use this to pick up a user's
+ * preferences when the platform is running and fall back to their own defaults
+ * otherwise, instead of throwing.
+ */
+export function tryUseSettingsStore(): ReturnType<typeof useSettingsStore> | null {
+  if (!getActivePinia()) return null
+  try {
+    return useSettingsStore()
+  } catch {
+    return null
+  }
+}

package/src/styles/components/audit-trail.css

@@ -126,11 +126,11 @@
   margin-right: 0.125rem;
 }
 
-.mint-audit-trail__empty {
-  text-align: center;
-  padding: 2rem;
-  color: var(--text-muted);
-  font-size: 0.875rem;
+/* Empty / loading / error placeholder host (content comes from EmptyState) */
+.mint-audit-trail__state {
+  display: flex;
+  align-items: center;
+  justify-content: center;
 }
 
 /* Size variants */

package/src/styles/components/batch-progress-list.css

@@ -194,3 +194,10 @@
   background-color: var(--bg-hover);
   color: var(--text-primary);
 }
+
+/* Empty / loading / error placeholder host (content comes from EmptyState) */
+.mint-batch-progress__state {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}

package/src/styles/components/color-slider.css

@@ -61,7 +61,7 @@
   border-radius: 50%;
   background: white;
   cursor: pointer;
-  border: 2px solid var(--mint-primary, #6366f1);
+  border: 2px solid var(--color-primary);
   box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
   transition: transform 0.15s ease;
 }
@@ -80,7 +80,7 @@
   border-radius: 50%;
   background: white;
   cursor: pointer;
-  border: 2px solid var(--mint-primary, #6366f1);
+  border: 2px solid var(--color-primary);
   box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
   transition: transform 0.15s ease;
 }