@morscherlab/mint-sdk 1.0.51 → 1.0.52

package/src/__tests__/utils/jobs.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  normalizeJobPercent,
+  normalizeJobState,
+  resolveJobCapabilities,
+} from '../../jobs'
+import type { JobStateInput, JobStatus } from '../../types/jobs'
+
+const legacyCapabilities: Record<JobStatus, [boolean, boolean]> = {
+  awaiting_input: [false, false],
+  queued: [true, false],
+  running: [true, false],
+  completed: [false, true],
+  failed: [false, true],
+  cancelled: [false, true],
+}
+
+function job(status: JobStatus): JobStateInput {
+  return {
+    id: status,
+    job_id: status,
+    kind: 'analysis',
+    name: status,
+    status,
+    progress: {
+      current_file: 0,
+      total_files: 0,
+      current_filename: null,
+      percent: 0,
+      message: '',
+      stage: status,
+    },
+    queue_position: 0,
+    warnings: [],
+    error: null,
+    output_path: null,
+    save_path: null,
+    session_id: null,
+    folders: [],
+    folder_path: null,
+    user_id: '1',
+    owner_user_id: '1',
+    experiment_id: null,
+    extraction_result_id: null,
+    metadata: {},
+    created_at: '2026-07-14T10:00:00+00:00',
+    started_at: null,
+    completed_at: null,
+  }
+}
+
+describe('job capability normalization', () => {
+  it.each(Object.entries(legacyCapabilities))(
+    'infers legacy capabilities for %s',
+    (status, expected) => {
+      const capabilities = resolveJobCapabilities({ status: status as JobStatus })
+
+      expect([capabilities.can_cancel, capabilities.can_delete]).toEqual(expected)
+    },
+  )
+
+  it('keeps explicit capabilities authoritative', () => {
+    const capabilities = resolveJobCapabilities({
+      status: 'running',
+      can_cancel: false,
+      can_delete: true,
+    })
+
+    expect(capabilities).toEqual({ can_cancel: false, can_delete: true })
+  })
+
+  it('fails closed for an unknown legacy status', () => {
+    const capabilities = resolveJobCapabilities({ status: 'custom-status' })
+
+    expect(capabilities).toEqual({ can_cancel: false, can_delete: false })
+  })
+
+  it('normalizes without mutating the transport input', () => {
+    const input = job('awaiting_input')
+
+    normalizeJobState(input)
+
+    expect('can_cancel' in input).toBe(false)
+  })
+
+  it.each([
+    [Number.NaN, 0],
+    [Number.POSITIVE_INFINITY, 0],
+    [-1, 0],
+    [101, 100],
+  ])('clamps unsafe progress value %s', (value, expected) => {
+    expect(normalizeJobPercent(value)).toBe(expected)
+  })
+})

package/src/components/JobsStatusTray.story.vue

@@ -0,0 +1,120 @@
+<script setup lang="ts">
+import JobsStatusTray from './JobsStatusTray.vue'
+import type { JobStateInput, JobStatus } from '../types/jobs'
+
+function job(
+  status: JobStatus,
+  id: string,
+  overrides: Partial<JobStateInput> = {},
+): JobStateInput {
+  return {
+    id,
+    job_id: id,
+    kind: 'analysis',
+    name: `LC-MS analysis ${id}`,
+    status,
+    progress: {
+      current_file: status === 'running' ? 3 : 0,
+      total_files: status === 'running' ? 8 : 0,
+      current_filename: status === 'running' ? 'sample_03.raw' : null,
+      percent: status === 'running' ? 37.5 : 0,
+      message: status === 'awaiting_input' ? 'Select a reference library to continue' : '',
+      stage: status,
+    },
+    queue_position: status === 'queued' ? 2 : 0,
+    warnings: [],
+    error: status === 'failed' ? 'Reference peaks were not detected' : null,
+    output_path: null,
+    save_path: null,
+    session_id: null,
+    folders: [],
+    folder_path: null,
+    user_id: 'researcher-1',
+    owner_user_id: 'researcher-1',
+    experiment_id: 'EXP-042',
+    extraction_result_id: null,
+    metadata: {},
+    created_at: '2026-07-14T10:00:00+00:00',
+    started_at: status === 'running' ? '2026-07-14T10:01:00+00:00' : null,
+    completed_at: ['completed', 'failed', 'cancelled'].includes(status)
+      ? '2026-07-14T10:08:00+00:00'
+      : null,
+    ...overrides,
+  }
+}
+
+const mixedJobs = [
+  job('awaiting_input', 'J-104'),
+  job('running', 'J-103'),
+  job('queued', 'J-102'),
+  job('completed', 'J-101'),
+  job('failed', 'J-100'),
+]
+const explicitActionJobs = [
+  job('awaiting_input', 'J-201', { can_cancel: true }),
+  job('completed', 'J-200', { can_delete: false }),
+]
+const adapter = {
+  cancelJob: async () => undefined,
+  deleteJob: async () => true,
+}
+
+function initState() {
+  return {
+    title: 'Analysis jobs',
+    jobs: mixedJobs,
+  }
+}
+</script>
+
+<template>
+  <Story title="Workflow/JobsStatusTray">
+    <Variant title="Playground" :init-state="initState">
+      <template #default="{ state }">
+        <div style="padding: 2rem; min-height: 520px;">
+          <JobsStatusTray
+            :title="state.title"
+            :jobs="state.jobs"
+            :adapter="adapter"
+            :load-on-mount="false"
+            :teleport-to="false"
+          />
+        </div>
+      </template>
+      <template #controls="{ state }">
+        <HstText v-model="state.title" title="Title" />
+      </template>
+    </Variant>
+
+    <Variant title="Awaiting input">
+      <div style="padding: 2rem; min-height: 520px;">
+        <JobsStatusTray
+          :jobs="[job('awaiting_input', 'J-301')]"
+          :load-on-mount="false"
+          :teleport-to="false"
+        />
+      </div>
+    </Variant>
+
+    <Variant title="Explicit actions">
+      <div style="padding: 2rem; min-height: 520px;">
+        <JobsStatusTray
+          :jobs="explicitActionJobs"
+          :adapter="adapter"
+          :load-on-mount="false"
+          :teleport-to="false"
+        />
+      </div>
+    </Variant>
+
+    <Variant title="Empty">
+      <div style="padding: 2rem; min-height: 520px;">
+        <JobsStatusTray
+          :jobs="[]"
+          :load-on-mount="false"
+          :teleport-to="false"
+        />
+      </div>
+    </Variant>
+  </Story>
+</template>

package/src/components/JobsStatusTray.vue

@@ -0,0 +1,385 @@
+<script setup lang="ts">
+/** Floating, adapter-driven job status tray for plugin and platform workflows. */
+import { computed, nextTick, ref, toRef, useId } from 'vue'
+
+import {
+  jobStatusLabel,
+  normalizeJobPercent,
+} from '../jobs'
+import {
+  useJobsStatusTray,
+  type JobsStatusTrayAdapter,
+} from '../composables/useJobsStatusTray'
+import type { UsePluginEventStreamReturn } from '../composables/usePluginClient'
+import type {
+  JobState,
+  JobStateInput,
+  JobStreamData,
+} from '../types/jobs'
+
+interface Props {
+  jobs?: readonly JobStateInput[]
+  adapter?: JobsStatusTrayAdapter
+  eventStream?: UsePluginEventStreamReturn<JobStreamData>
+  loadOnMount?: boolean
+  title?: string
+  teleportTo?: string | HTMLElement | false
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  loadOnMount: true,
+  title: 'Analysis jobs',
+  teleportTo: 'body',
+})
+
+const emit = defineEmits<{
+  select: [job: JobState]
+  error: [message: string]
+}>()
+
+const panelId = `mint-jobs-tray-${useId().replace(/:/g, '')}`
+const titleId = `${panelId}-title`
+const triggerRef = ref<HTMLButtonElement | null>(null)
+const panelRef = ref<HTMLElement | null>(null)
+const teleportTarget = computed(() => props.teleportTo || 'body')
+const tray = useJobsStatusTray({
+  jobs: toRef(props, 'jobs'),
+  adapter: toRef(props, 'adapter'),
+  eventStream: toRef(props, 'eventStream'),
+  loadOnMount: props.loadOnMount,
+})
+const canClear = computed(() => (
+  tray.deletableJobs.value.length > 0
+  && Boolean(props.adapter?.clearFinishedJobs || props.adapter?.deleteJob)
+))
+
+async function openTray(): Promise<void> {
+  tray.open()
+  await nextTick()
+  panelRef.value?.focus()
+}
+
+async function closeTray(): Promise<void> {
+  tray.close()
+  await nextTick()
+  triggerRef.value?.focus()
+}
+
+async function toggleTray(): Promise<void> {
+  if (tray.isOpen.value) await closeTray()
+  else await openTray()
+}
+
+function onPanelKeydown(event: KeyboardEvent): void {
+  if (event.key === 'Escape') {
+    void closeTray()
+    return
+  }
+  if (event.key !== 'Tab' || !panelRef.value) return
+  const focusable = Array.from(panelRef.value.querySelectorAll<HTMLElement>(
+    'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+  ))
+  if (focusable.length === 0) {
+    event.preventDefault()
+    panelRef.value.focus()
+    return
+  }
+  const first = focusable[0]
+  const last = focusable[focusable.length - 1]
+  const activeElement = document.activeElement as HTMLElement | null
+  if (!activeElement || !focusable.includes(activeElement)) {
+    event.preventDefault()
+    if (event.shiftKey) last?.focus()
+    else first?.focus()
+  } else if (event.shiftKey && activeElement === first) {
+    event.preventDefault()
+    last?.focus()
+  } else if (!event.shiftKey && activeElement === last) {
+    event.preventDefault()
+    first?.focus()
+  }
+}
+
+function progressText(job: JobState): string {
+  if (job.status === 'awaiting_input') {
+    return job.progress.message || 'Waiting for external input'
+  }
+  if (job.status === 'queued' && job.queue_position > 0) {
+    return `Queue position ${job.queue_position}`
+  }
+  return job.progress.message || job.progress.stage || jobStatusLabel(job.status)
+}
+
+function formatTimestamp(value: string | null): string {
+  if (!value) return ''
+  const date = new Date(value)
+  return Number.isNaN(date.getTime())
+    ? ''
+    : new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' }).format(date)
+}
+
+function statusClass(job: JobState): string {
+  return `mint-jobs-tray__status--${job.status.replace('_', '-')}`
+}
+
+async function cancelJob(job: JobState): Promise<void> {
+  const succeeded = await tray.cancelJob(job)
+  if (!succeeded && tray.error.value) emit('error', tray.error.value)
+}
+
+async function deleteJob(job: JobState): Promise<void> {
+  const succeeded = await tray.deleteJob(job)
+  if (!succeeded && tray.error.value) emit('error', tray.error.value)
+}
+
+async function clearFinished(): Promise<void> {
+  const succeeded = await tray.clearFinished()
+  if (!succeeded && tray.error.value) emit('error', tray.error.value)
+}
+</script>
+
+<template>
+  <Teleport :to="teleportTarget" :disabled="teleportTo === false">
+    <div class="mint-jobs-tray">
+      <button
+        ref="triggerRef"
+        type="button"
+        class="mint-jobs-tray__trigger"
+        aria-haspopup="dialog"
+        :aria-expanded="tray.isOpen.value"
+        :aria-controls="panelId"
+        @click="toggleTray"
+      >
+        <svg
+          class="mint-jobs-tray__trigger-icon"
+          :class="{ 'mint-jobs-tray__trigger-icon--active': tray.activeJobs.value.length > 0 }"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          aria-hidden="true"
+        >
+          <path d="M9 5H7a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2h-2" />
+          <path d="M9 5a3 3 0 0 1 6 0v2H9V5Z" />
+        </svg>
+        <span class="mint-jobs-tray__trigger-label">
+          {{ tray.featuredJob.value ? jobStatusLabel(tray.featuredJob.value.status) : 'Jobs' }}
+        </span>
+        <span
+          v-if="tray.activeJobs.value.length > 0"
+          class="mint-jobs-tray__count"
+          aria-live="polite"
+        >
+          {{ tray.activeJobs.value.length }}
+        </span>
+      </button>
+
+      <Transition name="mint-jobs-tray-fade">
+        <div
+          v-if="tray.isOpen.value"
+          class="mint-jobs-tray__backdrop"
+          aria-hidden="true"
+          @click="closeTray"
+        />
+      </Transition>
+
+      <Transition name="mint-jobs-tray-slide">
+        <section
+          v-if="tray.isOpen.value"
+          :id="panelId"
+          ref="panelRef"
+          class="mint-jobs-tray__panel"
+          role="dialog"
+          aria-modal="true"
+          :aria-labelledby="titleId"
+          tabindex="-1"
+          @keydown="onPanelKeydown"
+        >
+          <header class="mint-jobs-tray__header">
+            <div>
+              <h2 :id="titleId" class="mint-jobs-tray__title">{{ title }}</h2>
+              <p class="mint-jobs-tray__subtitle">{{ tray.jobs.value.length }} total</p>
+            </div>
+            <div class="mint-jobs-tray__header-actions">
+              <button
+                v-if="adapter?.listJobs"
+                type="button"
+                class="mint-jobs-tray__icon-button"
+                aria-label="Refresh jobs"
+                :disabled="tray.isLoading.value"
+                @click="tray.refresh"
+              >
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" aria-hidden="true">
+                  <path d="M20 6v5h-5M4 18v-5h5" />
+                  <path d="M18.4 9A7 7 0 0 0 6.1 6.1L4 8m2 7a7 7 0 0 0 11.9 2.9L20 16" />
+                </svg>
+              </button>
+              <button
+                type="button"
+                class="mint-jobs-tray__icon-button"
+                aria-label="Close jobs"
+                @click="closeTray"
+              >
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" aria-hidden="true">
+                  <path d="m6 6 12 12M18 6 6 18" />
+                </svg>
+              </button>
+            </div>
+          </header>
+
+          <div class="mint-jobs-tray__tabs" role="tablist" aria-label="Job groups">
+            <button
+              type="button"
+              role="tab"
+              data-tab="active"
+              class="mint-jobs-tray__tab"
+              :class="{ 'mint-jobs-tray__tab--active': tray.activeTab.value === 'active' }"
+              :aria-selected="tray.activeTab.value === 'active'"
+              @click="tray.activeTab.value = 'active'"
+            >
+              Active
+              <span class="mint-jobs-tray__tab-count">{{ tray.activeJobs.value.length }}</span>
+            </button>
+            <button
+              type="button"
+              role="tab"
+              data-tab="history"
+              class="mint-jobs-tray__tab"
+              :class="{ 'mint-jobs-tray__tab--active': tray.activeTab.value === 'history' }"
+              :aria-selected="tray.activeTab.value === 'history'"
+              @click="tray.activeTab.value = 'history'"
+            >
+              History
+              <span class="mint-jobs-tray__tab-count">{{ tray.historyJobs.value.length }}</span>
+            </button>
+          </div>
+
+          <p v-if="tray.error.value" class="mint-jobs-tray__error" role="alert">
+            {{ tray.error.value }}
+          </p>
+
+          <div class="mint-jobs-tray__body">
+            <template v-if="tray.activeTab.value === 'active'">
+              <p v-if="tray.activeJobs.value.length === 0" class="mint-jobs-tray__empty">
+                No active jobs
+              </p>
+              <article
+                v-for="job in tray.activeJobs.value"
+                :key="job.job_id"
+                class="mint-jobs-tray__job mint-jobs-tray__job--active"
+              >
+                <div class="mint-jobs-tray__job-heading">
+                  <div class="mint-jobs-tray__job-identity">
+                    <button
+                      type="button"
+                      class="mint-jobs-tray__job-select"
+                      @click="emit('select', job)"
+                    >
+                      {{ job.name }}
+                    </button>
+                    <span class="mint-jobs-tray__kind">{{ job.kind }}</span>
+                  </div>
+                  <span class="mint-jobs-tray__status" :class="statusClass(job)">
+                    {{ jobStatusLabel(job.status) }}
+                  </span>
+                </div>
+                <div
+                  v-if="job.status === 'running'"
+                  class="mint-jobs-tray__progress"
+                  role="progressbar"
+                  aria-label="Job progress"
+                  aria-valuemin="0"
+                  aria-valuemax="100"
+                  :aria-valuenow="normalizeJobPercent(job.progress.percent)"
+                >
+                  <span :style="{ width: `${normalizeJobPercent(job.progress.percent)}%` }" />
+                </div>
+                <div class="mint-jobs-tray__job-footer">
+                  <span>{{ progressText(job) }}</span>
+                  <div class="mint-jobs-tray__job-actions">
+                    <button
+                      v-if="job.can_cancel && adapter?.cancelJob"
+                      type="button"
+                      class="mint-jobs-tray__action mint-jobs-tray__action--danger"
+                      aria-label="Cancel job"
+                      :disabled="tray.isPending(job)"
+                      @click="cancelJob(job)"
+                    >
+                      Cancel
+                    </button>
+                    <button
+                      v-if="job.can_delete && adapter?.deleteJob"
+                      type="button"
+                      class="mint-jobs-tray__icon-button mint-jobs-tray__icon-button--danger"
+                      aria-label="Delete job"
+                      :disabled="tray.isPending(job)"
+                      @click="deleteJob(job)"
+                    >
+                      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" aria-hidden="true">
+                        <path d="M4 7h16M9 7V4h6v3m-8 0 1 13h8l1-13M10 11v5M14 11v5" />
+                      </svg>
+                    </button>
+                  </div>
+                </div>
+              </article>
+            </template>
+
+            <template v-else>
+              <div v-if="canClear" class="mint-jobs-tray__clear-row">
+                <button
+                  type="button"
+                  class="mint-jobs-tray__action mint-jobs-tray__action--danger"
+                  @click="clearFinished"
+                >
+                  Clear finished
+                </button>
+              </div>
+              <p v-if="tray.historyJobs.value.length === 0" class="mint-jobs-tray__empty">
+                No job history
+              </p>
+              <article
+                v-for="job in tray.historyJobs.value"
+                :key="job.job_id"
+                class="mint-jobs-tray__job"
+              >
+                <div class="mint-jobs-tray__job-heading">
+                  <div class="mint-jobs-tray__job-identity">
+                    <button
+                      type="button"
+                      class="mint-jobs-tray__job-select"
+                      @click="emit('select', job)"
+                    >
+                      {{ job.name }}
+                    </button>
+                    <span class="mint-jobs-tray__kind">{{ job.kind }}</span>
+                  </div>
+                  <span class="mint-jobs-tray__status" :class="statusClass(job)">
+                    {{ jobStatusLabel(job.status) }}
+                  </span>
+                </div>
+                <div class="mint-jobs-tray__job-footer">
+                  <span>{{ formatTimestamp(job.completed_at || job.created_at) }}</span>
+                  <button
+                    v-if="job.can_delete && adapter?.deleteJob"
+                    type="button"
+                    class="mint-jobs-tray__icon-button mint-jobs-tray__icon-button--danger"
+                    aria-label="Delete job"
+                    :disabled="tray.isPending(job)"
+                    @click="deleteJob(job)"
+                  >
+                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" aria-hidden="true">
+                      <path d="M4 7h16M9 7V4h6v3m-8 0 1 13h8l1-13M10 11v5M14 11v5" />
+                    </svg>
+                  </button>
+                </div>
+              </article>
+            </template>
+          </div>
+        </section>
+      </Transition>
+    </div>
+  </Teleport>
+</template>
+
+<style>
+@import '../styles/components/jobs-status-tray.css';
+</style>

package/src/components/index.ts

@@ -108,6 +108,7 @@ export { default as UnitInput } from './UnitInput.vue'
 export { default as StepWizard } from './StepWizard.vue'
 export { default as AuditTrail } from './AuditTrail.vue'
 export { default as BatchProgressList } from './BatchProgressList.vue'
+export { default as JobsStatusTray } from './JobsStatusTray.vue'
 
 // Form builder components
 export { default as FormBuilder } from './FormBuilder.vue'

package/src/composables/index.ts

@@ -468,3 +468,11 @@ export {
   type UsePluginSettingsOptions,
   type UsePluginSettingsReturn,
 } from './usePluginClient'
+export {
+  useJobsStatusTray,
+  type JobsStatusTrayAdapter,
+  type JobsStatusTrayTab,
+  type JobStreamMessage,
+  type UseJobsStatusTrayOptions,
+  type UseJobsStatusTrayReturn,
+} from './useJobsStatusTray'