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

package/src/composables/useFocusTrap.ts

@@ -0,0 +1,91 @@
+import { nextTick, watch, type Ref } from 'vue'
+import { useEventListener } from './useEventListener'
+
+export interface UseFocusTrapOptions {
+  /** Ref to the trap's container element. Focusable elements are queried within it. */
+  containerRef: Ref<HTMLElement | null>
+  /** Reactive flag — the trap activates when this becomes `true` and releases when it becomes `false`. */
+  active: Ref<boolean>
+  /** Restore focus to the element that was focused before activation, when the trap releases. Default `true`. */
+  restoreFocus?: boolean
+}
+
+export interface UseFocusTrapReturn {
+  /** Focusable descendants of the container, in DOM order, excluding roving-tabindex (`tabindex="-1"`) elements. */
+  getFocusableElements: () => HTMLElement[]
+}
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(', ')
+
+/**
+ * Traps Tab focus within a container while `active` is true: Tab wraps from the last
+ * focusable element back to the first (and Shift+Tab from the first to the last), the
+ * first focusable element (or the container itself, if none) receives focus when the
+ * trap activates, and focus returns to whatever was focused beforehand when it releases.
+ * Used by BaseModal and WellEditPopupInternal.
+ */
+export function useFocusTrap(options: UseFocusTrapOptions): UseFocusTrapReturn {
+  const { containerRef, active } = options
+  const restoreFocus = options.restoreFocus ?? true
+  let previouslyFocused: HTMLElement | null = null
+
+  function getFocusableElements(): HTMLElement[] {
+    if (!containerRef.value) return []
+    // Roving tabindex (inactive tabs/rail items) stays out of the Tab cycle. Checking
+    // the attribute directly (rather than the `.tabIndex` IDL property) avoids relying
+    // on a browser/engine's default-tabindex computation for freshly-patched elements.
+    return Array.from(containerRef.value.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR))
+      .filter((el) => el.getAttribute('tabindex') !== '-1')
+  }
+
+  function handleKeydown(event: KeyboardEvent) {
+    if (event.key !== 'Tab' || !active.value || !containerRef.value) return
+
+    const focusable = getFocusableElements()
+    if (focusable.length === 0) {
+      event.preventDefault()
+      return
+    }
+
+    const first = focusable[0]
+    const last = focusable[focusable.length - 1]
+
+    if (event.shiftKey && document.activeElement === first) {
+      event.preventDefault()
+      last.focus()
+    } else if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault()
+      first.focus()
+    }
+  }
+
+  // `flush: 'sync'` so releasing the trap from `onBeforeUnmount` restores focus
+  // before the component's reactive scope is torn down — a batched (default
+  // 'pre') watcher would be scheduled but never flushed once that scope stops.
+  watch(active, async (isActive) => {
+    if (isActive) {
+      previouslyFocused = document.activeElement as HTMLElement | null
+      await nextTick()
+      const focusable = getFocusableElements()
+      if (focusable.length > 0) {
+        focusable[0].focus()
+      } else {
+        containerRef.value?.focus()
+      }
+    } else {
+      if (restoreFocus) previouslyFocused?.focus()
+      previouslyFocused = null
+    }
+  }, { flush: 'sync' })
+
+  useEventListener(() => document, 'keydown', handleKeydown)
+
+  return { getFocusableElements }
+}

package/src/composables/useGeneratedAnalysis.ts

@@ -8,9 +8,13 @@ import {
   type ShallowRef,
 } from 'vue'
 
-import type { PluginJobCenterSource } from './useJobsStatusTray'
+import type {
+  JobsStatusTrayAdapter,
+  PluginJobCenterSource,
+} from './useJobsStatusTray'
 import { useEventStream, type EventStreamMessage } from './useEventStream'
-import { normalizeJobState } from '../jobs'
+import { isActiveJobStatus, normalizeJobState } from '../jobs'
+import { MintApiError, mintApiErrorFromResponse } from '../apiErrors'
 import type {
   GeneratedAnalysisJob,
   GeneratedAnalysisJobInput,
@@ -102,11 +106,12 @@ export interface UsePluginJobsReturn extends PluginJobCenterSource {
   pause: () => void
   resume: () => void
   dispose: () => void
+  /** @deprecated Pass the runtime itself to SDK job UI as its source. */
+  jobsAdapter: JobsStatusTrayAdapter
 }
 
 export type UseGeneratedAnalysisReturn = UsePluginJobsReturn
 
-const ACTIVE_STATUSES = new Set(['awaiting_input', 'queued', 'running'])
 const AUTH_TOKEN_KEY = 'mint-auth-token'
 const SESSION_NOT_FOUND_DETAIL = 'Session not found'
 const MAX_RESULT_CACHE_ENTRIES = 32
@@ -125,16 +130,6 @@ type PluginJobStreamData = GeneratedAnalysisJobInput | {
   jobs: GeneratedAnalysisJobInput[]
 }
 
-class GeneratedAnalysisRequestError extends Error {
-  constructor(
-    readonly status: number,
-    readonly detail: unknown,
-  ) {
-    super(typeof detail === 'string' ? detail : `Request failed (${status})`)
-    this.name = 'GeneratedAnalysisRequestError'
-  }
-}
-
 export function createGeneratedAnalysisTransport(
   options: GeneratedAnalysisTransportOptions = {},
 ): GeneratedAnalysisTransport {
@@ -468,12 +463,12 @@ function createPluginJobs(
       .then((payload) => {
         if (disposed) return jobs.value
         if (revision !== jobsRevision) {
-          if (jobs.value.some(job => ACTIVE_STATUSES.has(job.status))) schedulePoll()
+          if (jobs.value.some(job => isActiveJobStatus(job.status))) schedulePoll()
           return jobs.value
         }
         replaceJobs(payload.jobs)
         error.value = null
-        if (!paused && !jobStream.isConnected.value && jobs.value.some(job => ACTIVE_STATUSES.has(job.status))) {
+        if (!paused && !jobStream.isConnected.value && jobs.value.some(job => isActiveJobStatus(job.status))) {
           schedulePoll()
         }
         return jobs.value
@@ -525,7 +520,7 @@ function createPluginJobs(
     const current = typeof job === 'string'
       ? jobs.value.find(candidate => candidate.job_id === jobId)
       : jobs.value.find(candidate => candidate.job_id === jobId) ?? job
-    if (current && !ACTIVE_STATUSES.has(current.status)) {
+    if (current && !isActiveJobStatus(current.status)) {
       return terminalWaitResult(current, options.rejectOnFailure === true)
     }
     if (paused) return Promise.reject(new Error('Plugin jobs runtime is paused'))
@@ -562,7 +557,7 @@ function createPluginJobs(
   }
 
   function settleJobWaiters(job: GeneratedAnalysisJob): void {
-    if (ACTIVE_STATUSES.has(job.status)) return
+    if (isActiveJobStatus(job.status)) return
     const waiting = jobWaiters.get(job.job_id)
     if (!waiting) return
     jobWaiters.delete(job.job_id)
@@ -834,7 +829,7 @@ function createPluginJobs(
     job: GeneratedAnalysisJob,
     cause: unknown,
   ): void {
-    if (cause instanceof GeneratedAnalysisRequestError) {
+    if (cause instanceof MintApiError) {
       if (cause.status === 404 || cause.status === 410) {
         discardCachedResult(job.job_id)
         jobs.value = jobs.value.map(candidate => (
@@ -910,7 +905,7 @@ function createPluginJobs(
         await refreshJobs()
       } catch (cause) {
         error.value = errorMessage(cause, 'Failed to refresh analysis jobs')
-        if (jobs.value.some(job => ACTIVE_STATUSES.has(job.status))) schedulePoll()
+        if (jobs.value.some(job => isActiveJobStatus(job.status))) schedulePoll()
       }
     }, pollInterval)
   }
@@ -922,7 +917,7 @@ function createPluginJobs(
   }
 
   function schedulePollForActiveJobs(): void {
-    if (jobs.value.some(job => ACTIVE_STATUSES.has(job.status))) schedulePoll()
+    if (jobs.value.some(job => isActiveJobStatus(job.status))) schedulePoll()
   }
 
   function applyJobStreamMessage(message: EventStreamMessage<PluginJobStreamData>): void {
@@ -972,6 +967,13 @@ function createPluginJobs(
     return payload.deleted
   }
 
+  const jobsAdapter: JobsStatusTrayAdapter = {
+    listJobs: async () => ({ jobs: await refreshJobs() }),
+    cancelJob: async job => cancelJob(job as GeneratedAnalysisJob),
+    deleteJob: async job => deleteJob(job as GeneratedAnalysisJob),
+    clearFinishedJobs: async () => clearFinishedJobs(),
+  }
+
   function pause(): void {
     if (disposed || paused) return
     paused = true
@@ -993,7 +995,7 @@ function createPluginJobs(
       scheduleManagedDownloadRefresh(jobId, managedDownloadRefreshDelay(result))
     }
     if (streamEnabled) jobStream.start()
-    else if (jobs.value.some(job => ACTIVE_STATUSES.has(job.status))) schedulePoll()
+    else if (jobs.value.some(job => isActiveJobStatus(job.status))) schedulePoll()
   }
 
   function dispose(): void {
@@ -1026,8 +1028,10 @@ function createPluginJobs(
       },
     })
     if (!response.ok) {
-      const payload = await response.json().catch(() => null) as { detail?: unknown } | null
-      throw new GeneratedAnalysisRequestError(response.status, payload?.detail)
+      const payload: unknown = await response.json().catch(() => null)
+      throw mintApiErrorFromResponse(response.status, payload, {
+        requestId: response.headers.get('X-Request-ID'),
+      })
     }
     return await response.json() as T
   }
@@ -1065,6 +1069,7 @@ function createPluginJobs(
     pause,
     resume,
     dispose,
+    jobsAdapter,
   }
 }
 
@@ -1165,20 +1170,20 @@ function createGeneratedSessionStorage(candidate?: Storage): GeneratedSessionSto
 }
 
 function isSessionNotFoundError(error: unknown): boolean {
-  return error instanceof GeneratedAnalysisRequestError
+  return error instanceof MintApiError
     && error.status === 404
-    && error.detail === SESSION_NOT_FOUND_DETAIL
+    && (error.detail === SESSION_NOT_FOUND_DETAIL || error.message === SESSION_NOT_FOUND_DETAIL)
 }
 
 function isRetryableResultError(error: unknown): boolean {
-  return !(error instanceof GeneratedAnalysisRequestError)
+  return !(error instanceof MintApiError)
     || error.status === 409
     || error.status === 429
     || error.status >= 500
 }
 
 function isRetryableJobLookupError(error: unknown): boolean {
-  return !(error instanceof GeneratedAnalysisRequestError)
+  return !(error instanceof MintApiError)
     || error.status === 408
     || error.status === 429
     || error.status >= 500

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)
+}