@morscherlab/mint-sdk 1.3.9 → 1.4.0-beta.1

package/src/composables/{useRequestSyncState.ts → useRequest.ts}

@@ -1,7 +1,7 @@
 import { ref, type Ref } from 'vue'
 import { readErrorMessage as readSharedErrorMessage } from '../utils/errors'
 
-export type RequestSyncSuccessKind = 'load' | 'save' | 'run'
+export type RequestKind = 'load' | 'save' | 'run'
 
 /**
  * The unit of work `run()` drives.
@@ -10,10 +10,11 @@ export type RequestSyncSuccessKind = 'load' | 'save' | 'run'
  * newer `run()` or by `cancel()`. Zero-argument operations stay valid and
  * simply ignore it.
  */
-export type RequestSyncOperation<T> = (signal: AbortSignal) => Promise<T>
+export type RequestOperation<T> = (signal: AbortSignal) => Promise<T>
 
-export interface RequestSyncRunOptions {
-  success?: RequestSyncSuccessKind
+export interface RequestRunOptions {
+  /** Which timestamp a successful run moves: `lastLoadedAt`, `lastSavedAt` or `lastRunAt`. */
+  kind?: RequestKind
   errorMessage?: string
   /**
    * Abort the previously started run when this one starts. Default `true`;
@@ -25,9 +26,9 @@ export interface RequestSyncRunOptions {
   signal?: AbortSignal
 }
 
-export interface UseRequestSyncStateReturn {
+export interface UseRequestReturn {
   /** Whether a request is in progress. */
-  loading: Ref<boolean>
+  isLoading: Ref<boolean>
   /** Message from the last failed request, or null. */
   error: Ref<string | null>
   /** Timestamp of the last successful load operation, or null. */
@@ -42,12 +43,6 @@ export interface UseRequestSyncStateReturn {
   readErrorMessage: (value: unknown, fallback?: string) => string
   /** Store and return a normalized error message. */
   setError: (value: unknown, fallback?: string) => string
-  /** Mark the resource as successfully loaded. */
-  markLoaded: (date?: Date) => void
-  /** Mark the resource as successfully saved. */
-  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.
    *
@@ -55,7 +50,7 @@ export interface UseRequestSyncStateReturn {
    *
    * 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
+   * shared state when it finally settles: it does not clear `isLoading`, does not
    * set `error`, and does not move `lastLoadedAt` / `lastSavedAt` / `lastRunAt`.
    * Only the newest run owns those.
    *
@@ -68,19 +63,19 @@ export interface UseRequestSyncStateReturn {
    * 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>
+  run: <T>(operation: RequestOperation<T>, options?: RequestRunOptions) => Promise<T>
   /**
-   * Abort the in-flight run and drop `loading`. The aborted run's completion
+   * Abort the in-flight run and drop `isLoading`. 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. */
-export function useRequestSyncState(
+/** Loading, error and timestamp state for one request at a time; `run()` drives it. */
+export function useRequest(
   defaultErrorMessage = 'Request failed.',
-): UseRequestSyncStateReturn {
-  const loading = ref(false)
+): UseRequestReturn {
+  const isLoading = ref(false)
   const error = ref<string | null>(null)
   const lastLoadedAt = ref<Date | null>(null)
   const lastSavedAt = ref<Date | null>(null)
@@ -100,18 +95,6 @@ export function useRequestSyncState(
     return message
   }
 
-  function markLoaded(date = new Date()): void {
-    lastLoadedAt.value = date
-  }
-
-  function markSaved(date = new Date()): void {
-    lastSavedAt.value = date
-  }
-
-  function markRun(date = new Date()): void {
-    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.
@@ -122,12 +105,12 @@ export function useRequestSyncState(
     runToken += 1
     activeController?.abort()
     activeController = null
-    loading.value = false
+    isLoading.value = false
   }
 
   async function run<T>(
-    operation: RequestSyncOperation<T>,
-    options: RequestSyncRunOptions = {},
+    operation: RequestOperation<T>,
+    options: RequestRunOptions = {},
   ): Promise<T> {
     if (options.abortPrevious !== false) {
       activeController?.abort()
@@ -149,18 +132,15 @@ export function useRequestSyncState(
 
     const isCurrent = (): boolean => token === runToken
 
-    loading.value = true
+    isLoading.value = true
     clearError()
     try {
       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()
-        }
+      if (isCurrent() && options.kind) {
+        const settledAt = new Date()
+        if (options.kind === 'load') lastLoadedAt.value = settledAt
+        else if (options.kind === 'save') lastSavedAt.value = settledAt
+        else lastRunAt.value = settledAt
       }
       return response
     } catch (err) {
@@ -170,7 +150,7 @@ export function useRequestSyncState(
       throw err
     } finally {
       if (isCurrent()) {
-        loading.value = false
+        isLoading.value = false
       }
       if (activeController === controller) {
         activeController = null
@@ -179,7 +159,7 @@ export function useRequestSyncState(
   }
 
   return {
-    loading,
+    isLoading,
     error,
     lastLoadedAt,
     lastSavedAt,
@@ -187,9 +167,6 @@ export function useRequestSyncState(
     clearError,
     readErrorMessage,
     setError,
-    markLoaded,
-    markSaved,
-    markRun,
     run,
     cancel,
   }

package/src/composables/useScheduleCalendarLayout.ts

@@ -5,7 +5,7 @@ import type {
   ScheduleBlockedSlot,
   ScheduleEventStatus,
 } from '../types/components'
-import { formatTime } from './useTimeUtils'
+import { formatTime } from '../utils/time'
 
 type ReadableRef<T> = Readonly<Ref<T>>
 

package/src/composables/useToast.ts

@@ -4,6 +4,9 @@ import type { Toast, ToastOptions } from '../types'
 const toasts = ref<Toast[]>([])
 let nextId = 0
 
+/** Options of `success()`, `error()`, `warning()` and `info()`: the message is the title. */
+type ToastMessageOptions = Omit<ToastOptions, 'title' | 'type'>
+
 /** Reactive global toast queue with success/error/warning/info variants and auto-dismiss timers. */
 export function useToast() {
   /** Push a structured toast. `progress: 'indeterminate'` is the in-progress form and never auto-dismisses. */
@@ -24,24 +27,24 @@ export function useToast() {
     return id
   }
 
-  function show(message: string, type: Toast['type'] = 'success', duration = 3500) {
-    push({ title: message, type, duration })
+  function notify(type: Toast['type'], duration: number, message: string, options: ToastMessageOptions = {}): number {
+    return push({ duration, ...options, title: message, type })
   }
 
-  function success(message: string, duration = 3500) {
-    show(message, 'success', duration)
+  function success(message: string, options?: ToastMessageOptions): number {
+    return notify('success', 3500, message, options)
   }
 
-  function error(message: string, duration = 5000) {
-    show(message, 'error', duration)
+  function error(message: string, options?: ToastMessageOptions): number {
+    return notify('error', 5000, message, options)
   }
 
-  function warning(message: string, duration = 4000) {
-    show(message, 'warning', duration)
+  function warning(message: string, options?: ToastMessageOptions): number {
+    return notify('warning', 4000, message, options)
   }
 
-  function info(message: string, duration = 3500) {
-    show(message, 'info', duration)
+  function info(message: string, options?: ToastMessageOptions): number {
+    return notify('info', 3500, message, options)
   }
 
   function dismiss(id: number) {
@@ -52,5 +55,5 @@ export function useToast() {
     toasts.value = []
   }
 
-  return { toasts, push, show, success, error, warning, info, dismiss, clear }
+  return { toasts, push, success, error, warning, info, dismiss, clear }
 }

package/src/composables/useVersionedSave.ts

@@ -0,0 +1,165 @@
+import { readonly, ref, toValue, watch, type MaybeRefOrGetter, type Ref } from 'vue'
+import { MintApiError } from '../apiErrors'
+import { useRealtime, type RealtimeEvent } from './useRealtime'
+
+/** A save the platform refused with 412 `<entity>.version_conflict`. */
+export interface VersionConflict {
+  /** The entity's current version from the 412 body; `null` when the body has none. */
+  version: number | null
+}
+
+/** Writes by other users that reached the open entity while the form held unsaved edits. */
+export interface StaleChange {
+  /** Display names of the writers, in order of arrival, without repeats. */
+  actors: readonly string[]
+  /** Labels of the changed fields, without repeats; empty when no event named them. */
+  fields: readonly string[]
+  /** ISO time of the latest write. */
+  at: string
+}
+
+export interface UseVersionedSaveOptions<T> {
+  /** The entity version the form was loaded at; sent as `If-Match: "v<version>"`. */
+  version: MaybeRefOrGetter<number | null | undefined>
+  /** Send the write. Pass `headers` on to the request. */
+  save: (headers: Record<string, string>) => Promise<T>
+  /**
+   * Refetch the entity and reset the form to it. The user's edits are discarded.
+   * Reject when no fresh record arrives: the form then keeps the edits and the conflict.
+   */
+  reload: () => unknown
+  /**
+   * The realtime topic of the open entity (`experiment:42`). `null` turns the
+   * stale banner off: pass it while the form is closed or the platform's
+   * `realtime` feature flag is off. A change of topic also clears `conflict`.
+   */
+  topic?: MaybeRefOrGetter<string | null | undefined>
+  /** True while the form holds unsaved edits. */
+  dirty?: MaybeRefOrGetter<boolean>
+  /** The display name of an event's `actor_id`; unknown users show as "Someone". */
+  userName?: (userId: string) => string | null | undefined
+  /** The label of an event field name; defaults to `end_date` → "End date". */
+  fieldLabel?: (field: string) => string
+}
+
+export interface UseVersionedSaveReturn<T> {
+  /** Save with `If-Match`. Resolves `undefined` on a 412: `conflict` is then set. Other errors reject. */
+  save: () => Promise<T | undefined>
+  /** Save again on top of the version the 412 reported. Resolves `undefined` on another 412. */
+  overwrite: () => Promise<T | undefined>
+  /** Run the `reload` option, then clear `conflict` and `stale`. Rejects, and keeps both, when the reload rejects. */
+  reload: () => Promise<void>
+  /** Close the conflict dialog and keep editing. */
+  dismissConflict: () => void
+  /** Hide the stale banner until the next write arrives. */
+  dismissStale: () => void
+  saving: Readonly<Ref<boolean>>
+  conflict: Readonly<Ref<VersionConflict | null>>
+  stale: Readonly<Ref<StaleChange | null>>
+}
+
+/** `end_date` → "End date". */
+export function fieldNameLabel(field: string): string {
+  const words = field.replace(/_/g, ' ').trim()
+  return words.charAt(0).toUpperCase() + words.slice(1)
+}
+
+function conflictVersion(cause: unknown): VersionConflict | null {
+  if (!(cause instanceof MintApiError) || cause.status !== 412) return null
+  const version = (cause.details as { version?: unknown } | null)?.version
+  return { version: typeof version === 'number' ? version : null }
+}
+
+function union(list: readonly string[], items: readonly string[]): string[] {
+  return [...new Set([...list, ...items])]
+}
+
+/**
+ * Optimistic-concurrency save for a form on a versioned entity (RFC #439).
+ *
+ * `save()` sends `If-Match` with the loaded version. A 412 sets `conflict`;
+ * show `VersionConflictDialog` for it, whose Reload calls `reload()` and
+ * whose Overwrite calls `overwrite()` (the same save, with the version from
+ * the 412). With a `topic`, a realtime write by someone else on the entity
+ * sets `stale` while the form is dirty (show `StaleFormBanner`); on a clean
+ * form it runs the `reload` option instead. Several writes merge into one
+ * `stale`.
+ *
+ * @example
+ * const versioned = useVersionedSave({
+ *   version: () => experiment.value?.version,
+ *   save: headers => api.patch(`/experiments/${id}`, payload(), { headers }),
+ *   reload: () => refetchAndResetForm(),
+ *   topic: () => (realtime && open.value ? `experiment:${id}` : null),
+ *   dirty: () => changeCount.value > 0,
+ * })
+ */
+export function useVersionedSave<T>(options: UseVersionedSaveOptions<T>): UseVersionedSaveReturn<T> {
+  const saving = ref(false)
+  const conflict = ref<VersionConflict | null>(null)
+  const stale = ref<StaleChange | null>(null)
+  const fieldLabel = options.fieldLabel ?? fieldNameLabel
+
+  async function send(version: number | null | undefined): Promise<T | undefined> {
+    saving.value = true
+    try {
+      const headers: Record<string, string> = version == null ? {} : { 'If-Match': `"v${version}"` }
+      const result = await options.save(headers)
+      conflict.value = null
+      stale.value = null
+      return result
+    } catch (cause) {
+      const refused = conflictVersion(cause)
+      if (!refused) throw cause
+      conflict.value = refused
+      return undefined
+    } finally {
+      saving.value = false
+    }
+  }
+
+  async function reload(): Promise<void> {
+    await options.reload()
+    conflict.value = null
+    stale.value = null
+  }
+
+  function onEvent(event: RealtimeEvent): void {
+    // A resync names no writer, and the user's own save echoes back while it runs.
+    if (event.type === 'resync' || saving.value || event.topic !== toValue(options.topic)) return
+    if (!toValue(options.dirty)) {
+      // A failed background refetch leaves a clean form as it is; the host reports its own faults.
+      reload().catch(() => {})
+      return
+    }
+    const actor = (event.actor_id && options.userName?.(event.actor_id)) || 'Someone'
+    const previous = stale.value
+    stale.value = {
+      actors: union(previous?.actors ?? [], [actor]),
+      fields: union(previous?.fields ?? [], (event.fields ?? []).map(fieldLabel)),
+      at: event.at ?? new Date().toISOString(),
+    }
+  }
+
+  useRealtime(() => {
+    const topic = toValue(options.topic)
+    return topic ? [topic] : []
+  }, onEvent)
+  // Another entity, or a closed form: the old writes and the old 412 no longer apply.
+  watch(() => toValue(options.topic), () => {
+    conflict.value = null
+    stale.value = null
+  })
+
+  return {
+    save: () => send(toValue(options.version)),
+    // Without a version in the 412, a save with no If-Match is the overwrite.
+    overwrite: () => send(conflict.value?.version),
+    reload,
+    dismissConflict: () => { conflict.value = null },
+    dismissStale: () => { stale.value = null },
+    saving: readonly(saving),
+    conflict: readonly(conflict),
+    stale: readonly(stale),
+  }
+}

package/src/data.ts

@@ -0,0 +1,130 @@
+// Experiment, artifact, file and job data components (`@morscherlab/mint-sdk/data`).
+
+// Experiment / analysis components
+export { default as ExperimentSelectorModal } from './components/ExperimentSelectorModal.vue'
+export { default as ArtifactSelectorModal } from './components/ArtifactSelectorModal.vue'
+export { default as ArtifactSaveDialog } from './components/ArtifactSaveDialog.vue'
+export { default as ExperimentPopover } from './components/ExperimentPopover.vue'
+export { default as ExperimentCodeBadge } from './components/ExperimentCodeBadge.vue'
+export { default as FilePicker } from './components/FilePicker.vue'
+
+// Workflow components
+export { default as AuditTrail } from './components/AuditTrail.vue'
+export { default as BatchProgressList } from './components/BatchProgressList.vue'
+export { default as JobsStatusTray } from './components/JobsStatusTray.vue'
+
+// Form components
+export { default as TagsInput } from './components/TagsInput.vue'
+export { default as SecretInput } from './components/SecretInput.vue'
+
+// Versioned save (RFC #439): the 412 conflict dialog and the stale-form banner
+export { default as VersionConflictDialog } from './components/VersionConflictDialog.vue'
+export { default as StaleFormBanner } from './components/StaleFormBanner.vue'
+export {
+  useVersionedSave,
+  fieldNameLabel,
+  type StaleChange,
+  type UseVersionedSaveOptions,
+  type UseVersionedSaveReturn,
+  type VersionConflict,
+} from './composables/useVersionedSave'
+
+// Experiment and artifact data
+export {
+  useExperimentData,
+  type UseExperimentDataOptions,
+  type UseExperimentDataReturn,
+} from './composables/useExperimentData'
+export {
+  useArtifacts,
+  ANALYSIS_FILE_ARTIFACT_SCHEMA,
+  type UseArtifactsOptions,
+  type UseArtifactsReturn,
+} from './composables/useArtifacts'
+export { experimentIdFromRoute } from './composables/experiment-utils'
+export * as experimentStatus from './utils/experimentStatus'
+export * as pluginSecret from './utils/pluginSecrets'
+export type { PluginSecretRef, PluginSecretState } from './utils/pluginSecrets'
+
+// Text import and search
+export {
+  parseDelimitedText,
+  type DelimitedTable,
+  type ParseDelimitedTextOptions,
+} from './composables/useFileImport'
+export {
+  candidateMatchesSearch,
+  normalizeSearchQuery,
+  useTextSearch,
+  type TextSearchCandidate,
+  type TextSearchSource,
+  type UseTextSearchOptions,
+  type UseTextSearchReturn,
+} from './composables/useTextSearch'
+
+// File picker adapters
+export {
+  usePlatformFilePickerAdapter,
+  encodePlatformPickerPath,
+  decodePlatformPickerPath,
+} from './composables/usePlatformFilePickerAdapter'
+export {
+  createFilePickerAdapter,
+  type FilePickerTransport,
+  type FilePickerAdapterOptions,
+} from './composables/createFilePickerAdapter'
+
+// Experiment, sample and file helpers
+export {
+  useExperimentSelector,
+  type UseExperimentSelectorOptions,
+  type UseExperimentSelectorReturn,
+} from './composables/useExperimentSelector'
+export {
+  useFileBrowser,
+  type UseFileBrowserOptions,
+  type UseFileBrowserReturn,
+} from './composables/useFileBrowser'
+export {
+  buildAnalysisArtifactTargetQuery,
+  parseAnalysisArtifactTarget,
+} from './composables/analysisArtifactTarget'
+export {
+  formatExperimentDate,
+  resolveExperimentCode,
+  datePresetToISO,
+  DATE_PRESET_OPTIONS,
+  SORT_OPTIONS,
+} from './composables/experiment-utils'
+export {
+  extractSampleNamesFromDesignData,
+  extractSampleOptionsFromDesignData,
+  unwrapExperimentDesignData,
+  type ExperimentDesignDataResponse,
+  type ExtractExperimentSamplesOptions,
+} from './composables/experimentDesignData'
+export {
+  useExperimentSamples,
+  type ExperimentDesignDataSource,
+  type ExperimentIdSource,
+  type UseExperimentSamplesOptions,
+  type UseExperimentSamplesReturn,
+} from './composables/useExperimentSamples'
+export {
+  useAppExperiment,
+  APP_EXPERIMENT_KEY,
+  type UseAppExperimentOptions,
+  type UseAppExperimentReturn,
+  type AppExperimentState,
+  type AppExperimentPopoverBinding,
+  type AppExperimentSelectorModalBinding,
+} from './composables/useAppExperiment'
+export {
+  detectDelimiter,
+  readFileAsText,
+  useFileImport,
+  validateImportFile,
+  type FileImportOptions,
+  type FileImportValidationOptions,
+  type UseFileImportReturn,
+} from './composables/useFileImport'