@morscherlab/mint-sdk 1.2.0-beta.1 → 1.2.0-beta.11

package/src/composables/useJobsStatusTray.ts

@@ -5,6 +5,7 @@ import {
   ref,
   shallowRef,
   toValue,
+  watch,
   type ComputedRef,
   type MaybeRefOrGetter,
   type Ref,
@@ -16,7 +17,12 @@ import type {
   JobListPayload,
   JobState,
   JobStateInput,
+  JobStreamData,
 } from '../types/jobs'
+import type {
+  PluginEventStreamMessage,
+  UsePluginEventStreamReturn,
+} from './usePluginClient'
 
 export type JobsStatusTrayTab = 'active' | 'history'
 
@@ -140,11 +146,32 @@ function duplicatePluginJobId(jobId: string): Error {
   return new Error(`Duplicate plugin job id across combined sources: ${jobId}`)
 }
 
+/** @deprecated Prefer a {@link PluginJobCenterSource}. */
+export interface JobsStatusTrayAdapter {
+  listJobs?: () => Promise<JobListPayload | readonly JobStateInput[]>
+  cancelJob?: (job: JobState) => Promise<JobStateInput | void>
+  deleteJob?: (job: JobState) => Promise<boolean | void>
+  clearFinishedJobs?: (jobs: readonly JobState[]) => Promise<number | void>
+}
+
 export interface UsePluginJobCenterOptions {
   source?: MaybeRefOrGetter<PluginJobCenterSource | undefined>
+  /** @deprecated Pass a source with its canonical jobs ref. */
+  jobs?: MaybeRefOrGetter<readonly JobStateInput[] | undefined>
+  /** @deprecated Pass source actions instead. */
+  adapter?: MaybeRefOrGetter<JobsStatusTrayAdapter | undefined>
+  /** @deprecated Event handling belongs to the source runtime. */
+  eventStream?: MaybeRefOrGetter<UsePluginEventStreamReturn<JobStreamData> | undefined>
   loadOnMount?: boolean
 }
 
+export interface UseJobsStatusTrayOptions extends UsePluginJobCenterOptions {}
+
+export interface JobStreamMessage {
+  event: string
+  data: JobStreamData
+}
+
 export interface UsePluginJobCenterReturn {
   jobs: ComputedRef<JobState[]>
   activeJobs: ComputedRef<JobState[]>
@@ -164,12 +191,30 @@ export interface UsePluginJobCenterReturn {
   close: () => void
   toggle: () => void
   refresh: () => Promise<boolean>
+  applyStreamMessage: (message: JobStreamMessage) => void
   cancelJob: (job: JobState) => Promise<boolean>
   deleteJob: (job: JobState) => Promise<boolean>
   clearFinished: () => Promise<boolean>
   isPending: (job: JobState) => boolean
 }
 
+export type UseJobsStatusTrayReturn = UsePluginJobCenterReturn
+
+interface LegacyJobsOverride {
+  readonly input: readonly JobStateInput[] | undefined
+  readonly jobs: JobState[]
+}
+
+function responseJobs(
+  response: JobListPayload | readonly JobStateInput[],
+): readonly JobStateInput[] {
+  return 'jobs' in response ? response.jobs : response
+}
+
+function isSnapshotPayload(data: JobStreamData): data is { jobs: JobStateInput[] } {
+  return 'jobs' in data && Array.isArray(data.jobs)
+}
+
 function errorMessage(error: unknown, fallback: string): string {
   return error instanceof Error ? error.message : fallback
 }
@@ -183,30 +228,84 @@ function errorMessage(error: unknown, fallback: string): string {
 export function usePluginJobCenter(
   options: UsePluginJobCenterOptions = {},
 ): UsePluginJobCenterReturn {
+  const legacyOverride = shallowRef<LegacyJobsOverride | null>(null)
   const isOpen = ref(false)
   const activeTab = ref<JobsStatusTrayTab>('active')
   const isLoading = ref(false)
   const error = shallowRef<string | null>(null)
   const pendingJobIds = ref(new Set<string>())
+  const jobRevisions = new Map<string, number>()
+  let stateRevision = 0
   let requestGeneration = 0
   let active = true
   const source = computed(() => toValue(options.source))
+  const adapter = computed(() => toValue(options.adapter))
 
-  const jobs = computed<JobState[]>(() => (
-    source.value ? [...toValue(source.value.jobs)].map(normalizeJobState) : []
-  ))
+  const jobs = computed<JobState[]>(() => {
+    const currentSource = source.value
+    if (currentSource) {
+      return [...toValue(currentSource.jobs)].map(normalizeJobState)
+    }
+    const input = toValue(options.jobs)
+    const override = legacyOverride.value
+    if (override && override.input === input) return override.jobs
+    return input ? [...input].map(normalizeJobState) : []
+  })
   const activeJobs = computed(() => jobs.value.filter(job => isActiveJobStatus(job.status)))
   const historyJobs = computed(() => jobs.value.filter(job => !isActiveJobStatus(job.status)))
   const deletableJobs = computed(() => historyJobs.value.filter(job => job.can_delete))
   const featuredJob = computed(() => activeJobs.value[0] ?? historyJobs.value[0] ?? null)
-  const canRefresh = computed(() => Boolean(source.value?.refreshJobs))
-  const canCancel = computed(() => Boolean(source.value?.cancelJob))
-  const canDelete = computed(() => Boolean(source.value?.deleteJob))
+  const canRefresh = computed(() => Boolean(source.value?.refreshJobs || adapter.value?.listJobs))
+  const canCancel = computed(() => Boolean(source.value?.cancelJob || adapter.value?.cancelJob))
+  const canDelete = computed(() => Boolean(source.value?.deleteJob || adapter.value?.deleteJob))
   const canClearFinished = computed(() => Boolean(
     source.value?.clearFinishedJobs
     || source.value?.deleteJob
+    || adapter.value?.clearFinishedJobs
+    || adapter.value?.deleteJob,
   ))
 
+  function bumpJobRevision(jobId: string): void {
+    jobRevisions.set(jobId, (jobRevisions.get(jobId) ?? 0) + 1)
+  }
+
+  function replaceLegacyJobs(nextJobs: readonly JobStateInput[]): void {
+    const normalized = nextJobs.map(normalizeJobState)
+    const touchedJobIds = new Set([
+      ...jobs.value.map(job => job.job_id),
+      ...normalized.map(job => job.job_id),
+    ])
+    touchedJobIds.forEach(bumpJobRevision)
+    legacyOverride.value = {
+      input: toValue(options.jobs),
+      jobs: normalized,
+    }
+    stateRevision += 1
+  }
+
+  function upsertLegacyJob(nextJob: JobStateInput): void {
+    const normalized = normalizeJobState(nextJob)
+    const existingIndex = jobs.value.findIndex(job => job.job_id === normalized.job_id)
+    const nextJobs = [...jobs.value]
+    if (existingIndex === -1) nextJobs.unshift(normalized)
+    else nextJobs[existingIndex] = normalized
+    legacyOverride.value = {
+      input: toValue(options.jobs),
+      jobs: nextJobs,
+    }
+    bumpJobRevision(normalized.job_id)
+    stateRevision += 1
+  }
+
+  function removeLegacyJobs(jobIds: Set<string>): void {
+    legacyOverride.value = {
+      input: toValue(options.jobs),
+      jobs: jobs.value.filter(job => !jobIds.has(job.job_id)),
+    }
+    jobIds.forEach(bumpJobRevision)
+    stateRevision += 1
+  }
+
   function setPending(jobId: string, pending: boolean): void {
     const next = new Set(pendingJobIds.value)
     if (pending) next.add(jobId)
@@ -214,15 +313,35 @@ export function usePluginJobCenter(
     pendingJobIds.value = next
   }
 
+  function applyStreamMessage(message: JobStreamMessage): void {
+    if (!active || source.value) return
+    if (message.event === 'snapshot' && isSnapshotPayload(message.data)) {
+      replaceLegacyJobs(message.data.jobs)
+      return
+    }
+    if (
+      (message.event === 'job' || message.event === 'terminal')
+      && !isSnapshotPayload(message.data)
+    ) {
+      upsertLegacyJob(message.data)
+    }
+  }
+
   async function refresh(): Promise<boolean> {
-    const refreshJobs = source.value?.refreshJobs
-    if (!refreshJobs) return false
+    const currentSource = source.value
+    const listJobs = currentSource?.refreshJobs ?? adapter.value?.listJobs
+    if (!listJobs) return false
     const generation = ++requestGeneration
+    const revision = stateRevision
     isLoading.value = true
     error.value = null
     try {
-      await refreshJobs()
-      return active && generation === requestGeneration
+      const response = await listJobs()
+      if (!active || generation !== requestGeneration || revision !== stateRevision) {
+        return false
+      }
+      if (!currentSource && response) replaceLegacyJobs(responseJobs(response))
+      return true
     } catch (cause) {
       if (active && generation === requestGeneration) {
         error.value = errorMessage(cause, 'Failed to load jobs')
@@ -235,14 +354,23 @@ export function usePluginJobCenter(
 
   async function cancelJob(job: JobState): Promise<boolean> {
     const sourceCancel = source.value?.cancelJob
-    if (!job.can_cancel || !sourceCancel || pendingJobIds.value.has(job.job_id)) {
+    const adapterCancel = adapter.value?.cancelJob
+    if (!job.can_cancel || (!sourceCancel && !adapterCancel) || pendingJobIds.value.has(job.job_id)) {
       return false
     }
+    const revision = jobRevisions.get(job.job_id) ?? 0
     setPending(job.job_id, true)
     error.value = null
     try {
-      await sourceCancel(job.job_id)
-      return active
+      const updated = sourceCancel
+        ? await sourceCancel(job.job_id)
+        : await adapterCancel!(job)
+      if (!active) return false
+      if (!sourceCancel && revision === (jobRevisions.get(job.job_id) ?? 0)) {
+        if (updated) upsertLegacyJob(updated)
+        else await refresh()
+      }
+      return true
     } catch (cause) {
       if (active) error.value = errorMessage(cause, 'Failed to cancel job')
       return false
@@ -253,14 +381,22 @@ export function usePluginJobCenter(
 
   async function deleteJob(job: JobState): Promise<boolean> {
     const sourceDelete = source.value?.deleteJob
-    if (!job.can_delete || !sourceDelete || pendingJobIds.value.has(job.job_id)) {
+    const adapterDelete = adapter.value?.deleteJob
+    if (!job.can_delete || (!sourceDelete && !adapterDelete) || pendingJobIds.value.has(job.job_id)) {
       return false
     }
     setPending(job.job_id, true)
     error.value = null
     try {
-      const deleted = await sourceDelete(job.job_id)
-      return active && deleted !== false
+      const deleted = sourceDelete
+        ? await sourceDelete(job.job_id)
+        : await adapterDelete!(job)
+      if (!active) return false
+      if (!sourceDelete) {
+        if (deleted === false) await refresh()
+        else removeLegacyJobs(new Set([job.job_id]))
+      }
+      return deleted !== false
     } catch (cause) {
       if (active) error.value = errorMessage(cause, 'Failed to delete job')
       return false
@@ -284,13 +420,36 @@ export function usePluginJobCenter(
         const results = await Promise.all(targets.map(job => deleteJob(job)))
         return results.every(Boolean)
       }
-      return false
+      const currentAdapter = adapter.value
+      if (currentAdapter?.clearFinishedJobs) {
+        const deleted = await currentAdapter.clearFinishedJobs(targets)
+        if (!active) return false
+        if (typeof deleted === 'number' && deleted !== targets.length) {
+          await refresh()
+          return false
+        }
+        removeLegacyJobs(new Set(targets.map(job => job.job_id)))
+        return true
+      }
+      if (!currentAdapter?.deleteJob) return false
+      const results = await Promise.all(targets.map(job => deleteJob(job)))
+      return results.every(Boolean)
     } catch (cause) {
       if (active) error.value = errorMessage(cause, 'Failed to clear jobs')
       return false
     }
   }
 
+  if (options.eventStream !== undefined) {
+    watch(
+      () => toValue(options.eventStream)?.lastMessage.value ?? null,
+      (message: PluginEventStreamMessage<JobStreamData> | null) => {
+        if (message) applyStreamMessage(message)
+      },
+      { immediate: true },
+    )
+  }
+
   onMounted(() => {
     if (options.loadOnMount !== false) void refresh()
   })
@@ -318,9 +477,17 @@ export function usePluginJobCenter(
     close: () => { isOpen.value = false },
     toggle: () => { isOpen.value = !isOpen.value },
     refresh,
+    applyStreamMessage,
     cancelJob,
     deleteJob,
     clearFinished,
     isPending: job => pendingJobIds.value.has(job.job_id),
   }
 }
+
+/** @deprecated Use `usePluginJobCenter()` for the plugin job-center controller. */
+export function useJobsStatusTray(
+  options: UseJobsStatusTrayOptions = {},
+): UseJobsStatusTrayReturn {
+  return usePluginJobCenter(options)
+}

package/src/composables/useListReorder.story.vue

@@ -0,0 +1,143 @@
+<script setup lang="ts">
+/** Demonstrates `useListReorder`: drag a row, or focus a handle and press Alt with the arrow keys. */
+import { ref } from 'vue'
+import { useListReorder } from './useListReorder'
+
+interface Step { id: string; name: string }
+
+const steps = ref<Step[]>([
+  { id: 's1', name: 'Thaw samples' },
+  { id: 's2', name: 'Quench metabolism' },
+  { id: 's3', name: 'Extract metabolites' },
+  { id: 's4', name: 'Dry down' },
+])
+
+const handles = new Map<string, HTMLElement>()
+
+function setHandle(id: string, el: Element | null) {
+  if (el instanceof HTMLElement) handles.set(id, el)
+  else handles.delete(id)
+}
+
+const {
+  draggingId,
+  dragOverId,
+  announcement,
+  announcerStyle,
+  onDragStart,
+  onDragOver,
+  onDragLeave,
+  onDrop,
+  onDragEnd,
+  onKeydown,
+} = useListReorder<Step>({
+  items: () => steps.value,
+  getId: (step) => step.id,
+  getLabel: (step) => step.name,
+  getElement: (id) => handles.get(id),
+  itemNoun: 'Step',
+  onReorder: ({ items }) => {
+    steps.value = items
+  },
+})
+
+function initState() {
+  return { showAnnouncement: true }
+}
+</script>
+
+<template>
+  <Story title="Composables/useListReorder">
+    <Variant title="Playground" :init-state="initState">
+      <template #default="{ state }">
+        <div style="padding: 2rem; max-width: 600px;">
+          <p class="mint-story-hint">
+            Drag a row, or focus its handle and press Alt with the up/down arrow keys.
+          </p>
+          <ul class="mint-story-list">
+            <li
+              v-for="(step, index) in steps"
+              :key="step.id"
+              class="mint-story-row"
+              :class="{
+                'mint-story-row--dragging': draggingId === step.id,
+                'mint-story-row--over': dragOverId === step.id,
+              }"
+              draggable="true"
+              @dragstart="onDragStart($event, step, index)"
+              @dragover="onDragOver($event, step, index)"
+              @dragleave="onDragLeave"
+              @drop="onDrop($event, step, index)"
+              @dragend="onDragEnd"
+            >
+              <button
+                :ref="(el) => setHandle(step.id, el as Element | null)"
+                type="button"
+                class="mint-story-handle"
+                :aria-label="`Reorder ${step.name}. Press Alt with the arrow keys to move it.`"
+                @keydown="onKeydown($event, step, index)"
+              >
+                ⠿
+              </button>
+              <span>{{ index + 1 }}. {{ step.name }}</span>
+            </li>
+          </ul>
+
+          <p v-if="state.showAnnouncement" class="mint-story-hint">
+            Live region: <em>{{ announcement || '—' }}</em>
+          </p>
+          <div role="status" aria-live="polite" :style="announcerStyle">{{ announcement }}</div>
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstCheckbox v-model="state.showAnnouncement" title="Show live-region text" />
+      </template>
+    </Variant>
+  </Story>
+</template>
+
+<style scoped>
+.mint-story-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.mint-story-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--border-color);
+  border-radius: 0.5rem;
+  background: var(--bg-primary);
+  color: var(--text-primary);
+}
+
+.mint-story-row--dragging {
+  opacity: 0.5;
+}
+
+.mint-story-row--over {
+  border-color: var(--color-primary);
+}
+
+.mint-story-handle {
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--text-muted);
+  cursor: grab;
+  font-size: 1rem;
+}
+
+.mint-story-hint {
+  margin: 0 0 0.75rem;
+  color: var(--text-secondary);
+  font-size: 0.8125rem;
+}
+</style>