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

package/src/composables/useBioTemplateWorkspace.ts

@@ -21,16 +21,12 @@ import {
 } from './useBioTemplateControls'
 import {
   useBioTemplateComponents,
-  type BioTemplateComponentBinding,
-  type BioTemplateComponentBindingsById,
-  type BioTemplateComponentImport,
-  type BioTemplateComponentPropsByComponent,
-  type BioTemplateComponentPropsBinding,
-  type BioTemplateComponentPropsById,
-  type BioTemplateComponentSnippet,
-  type BioTemplateComponentUsage,
   type UseBioTemplateComponentsReturn,
 } from './useBioTemplateComponents'
+import {
+  flattenWorkspaceComponentBindings,
+  type BioTemplateWorkspaceComponentBindings,
+} from './flattenWorkspaceBindings'
 
 export type BioTemplateWorkspaceTarget = BioTemplateControlTarget
 
@@ -38,24 +34,16 @@ export interface BioTemplateRendererBinding {
   target: BioTemplateEnvelope<unknown> | TemplateCollectionEnvelope
 }
 
-export interface BioTemplateWorkspaceBindings {
+export interface BioTemplateWorkspaceBindings extends BioTemplateWorkspaceComponentBindings {
   renderer: BioTemplateRendererBinding | null
   form: ControlWorkspaceFormBinding
   sidebar: ControlWorkspaceSidebarBinding
   topBar: UseControlWorkspaceReturn<BioTemplateControlSchema>['bindings']['topBar']
   topBarSettings: ControlWorkspaceTopBarSettingsBinding
   pillNav: ControlWorkspacePillNavBinding
-  componentBindings: BioTemplateComponentBinding[]
-  componentBindingsById: BioTemplateComponentBindingsById
-  componentProps: BioTemplateComponentPropsBinding[]
-  componentPropsById: BioTemplateComponentPropsById
-  componentPropsByComponent: BioTemplateComponentPropsByComponent
-  componentSnippets: BioTemplateComponentSnippet[]
-  componentUsage: BioTemplateComponentUsage | null
-  getComponentProps: UseBioTemplateComponentsReturn['getComponentProps']
 }
 
-export interface UseBioTemplateWorkspaceReturn {
+export interface UseBioTemplateWorkspaceReturn extends BioTemplateWorkspaceComponentBindings {
   target: BioTemplateWorkspaceTarget
   controls: UseControlSchemaReturn<BioTemplateControlSchema>
   workspace: UseControlWorkspaceReturn<BioTemplateControlSchema>
@@ -70,15 +58,6 @@ export interface UseBioTemplateWorkspaceReturn {
   topBarSettings: ControlWorkspaceTopBarSettingsBinding
   bindings: BioTemplateWorkspaceBindings
   renderer: BioTemplateRendererBinding | null
-  componentBindings: BioTemplateComponentBinding[]
-  componentBindingsById: BioTemplateComponentBindingsById
-  componentImports: BioTemplateComponentImport[]
-  componentProps: BioTemplateComponentPropsBinding[]
-  componentPropsById: BioTemplateComponentPropsById
-  componentPropsByComponent: BioTemplateComponentPropsByComponent
-  componentSnippets: BioTemplateComponentSnippet[]
-  componentUsage: BioTemplateComponentUsage | null
-  getComponentProps: UseBioTemplateComponentsReturn['getComponentProps']
 }
 
 /** One-stop wiring for BioTemplateRenderer, FormBuilder, AppSidebar, and template-aware SDK components. */
@@ -90,21 +69,25 @@ export function useBioTemplateWorkspace(
   const workspace = useControlWorkspace(controls.controls, options)
   const components = useBioTemplateComponents(target)
   const renderer = isTemplateObjectTarget(target) ? { target } : null
-  const bindings: BioTemplateWorkspaceBindings = {
-    renderer,
-    form: workspace.bindings.form,
-    sidebar: workspace.bindings.sidebar,
-    topBar: workspace.bindings.topBar,
-    topBarSettings: workspace.bindings.topBarSettings,
-    pillNav: workspace.bindings.pillNav,
+  const componentBindings = flattenWorkspaceComponentBindings({
     componentBindings: components.bindings,
     componentBindingsById: components.componentBindingsById,
+    componentImports: components.imports,
     componentProps: components.componentProps,
     componentPropsById: components.componentPropsById,
     componentPropsByComponent: components.componentPropsByComponent,
     componentSnippets: components.snippets,
     componentUsage: components.usage,
     getComponentProps: components.getComponentProps,
+  })
+  const bindings: BioTemplateWorkspaceBindings = {
+    renderer,
+    form: workspace.bindings.form,
+    sidebar: workspace.bindings.sidebar,
+    topBar: workspace.bindings.topBar,
+    topBarSettings: workspace.bindings.topBarSettings,
+    pillNav: workspace.bindings.pillNav,
+    ...componentBindings,
   }
 
   return {
@@ -122,15 +105,7 @@ export function useBioTemplateWorkspace(
     topBarSettings: workspace.topBarSettings,
     bindings,
     renderer,
-    componentBindings: components.bindings,
-    componentBindingsById: components.componentBindingsById,
-    componentImports: components.imports,
-    componentProps: components.componentProps,
-    componentPropsById: components.componentPropsById,
-    componentPropsByComponent: components.componentPropsByComponent,
-    componentSnippets: components.snippets,
-    componentUsage: components.usage,
-    getComponentProps: components.getComponentProps,
+    ...componentBindings,
   }
 }
 

package/src/composables/useCommandHistory.ts

@@ -31,7 +31,11 @@ export interface UseCommandHistoryReturn<TCommand extends CommandHistoryCommand
   clear: () => void
 }
 
-/** Generic command-stack state for plugin editors with undo/redo controls. */
+/**
+ * Generic command-stack state for plugin editors with undo/redo controls.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; keep command stacks plugin-local.
+ */
 export function useCommandHistory<TCommand extends CommandHistoryCommand = CommandHistoryCommand>(
   options: UseCommandHistoryOptions = {},
 ): UseCommandHistoryReturn<TCommand> {

package/src/composables/useDropdownState.ts

@@ -1,10 +1,18 @@
-import { ref, type Ref } from 'vue'
+import { nextTick, ref, type Ref } from 'vue'
 import { useEventListener } from './useEventListener'
 
 export interface UseDropdownStateOptions {
   closeOnOutsideClick?: boolean
   closeOnEscape?: boolean
+  /** Close the panel when the page scrolls or the viewport resizes. Default `false`. */
+  closeOnScroll?: boolean
   insideRefs?: Array<Ref<HTMLElement | null>>
+  /**
+   * Element focus returns to when the panel closes with `close(true)` (Escape).
+   * Pass one when the trigger lives outside `rootRef`; otherwise bind the
+   * returned `triggerRef` to the trigger element.
+   */
+  triggerRef?: Ref<HTMLElement | null>
   onOpen?: () => void
   onClose?: () => void
 }
@@ -12,19 +20,29 @@ export interface UseDropdownStateOptions {
 export interface UseDropdownStateReturn {
   isOpen: Ref<boolean>
   rootRef: Ref<HTMLElement | null>
+  /** Bind to the trigger element so Escape can return focus to it. */
+  triggerRef: Ref<HTMLElement | null>
   open: () => void
-  close: () => void
+  /** Closes the panel; `returnFocus` moves focus back to `triggerRef`. */
+  close: (returnFocus?: boolean) => void
   toggle: () => void
   handleClickOutside: (event: MouseEvent) => void
   handleKeydown: (event: KeyboardEvent) => void
 }
 
-/** Shared disclosure state for dropdown-style SDK components. */
+/**
+ * Shared disclosure state for dropdown-style SDK components: open/close state,
+ * outside-click and Escape closing, optional scroll/resize closing, and focus
+ * return to the trigger. `close(returnFocus)` mirrors `useMenuKeyboard`'s
+ * contract, so the two compose directly.
+ */
 export function useDropdownState(options: UseDropdownStateOptions = {}): UseDropdownStateReturn {
   const isOpen = ref(false)
   const rootRef = ref<HTMLElement | null>(null)
+  const triggerRef = options.triggerRef ?? ref<HTMLElement | null>(null)
   const closeOnOutsideClick = options.closeOnOutsideClick ?? true
   const closeOnEscape = options.closeOnEscape ?? true
+  const closeOnScroll = options.closeOnScroll ?? false
 
   function open(): void {
     if (isOpen.value) return
@@ -32,10 +50,13 @@ export function useDropdownState(options: UseDropdownStateOptions = {}): UseDrop
     options.onOpen?.()
   }
 
-  function close(): void {
+  function close(returnFocus = false): void {
     if (!isOpen.value) return
     isOpen.value = false
     options.onClose?.()
+    if (returnFocus) {
+      void nextTick(() => triggerRef.value?.focus())
+    }
   }
 
   function toggle(): void {
@@ -60,20 +81,29 @@ export function useDropdownState(options: UseDropdownStateOptions = {}): UseDrop
 
   function handleKeydown(event: KeyboardEvent): void {
     if (closeOnEscape && event.key === 'Escape') {
-      close()
+      close(true)
     }
   }
 
+  function handleViewportChange(): void {
+    if (isOpen.value) close()
+  }
+
   if (closeOnOutsideClick) {
     useEventListener(() => document, 'click', handleClickOutside)
   }
   if (closeOnEscape) {
     useEventListener(() => document, 'keydown', handleKeydown)
   }
+  if (closeOnScroll) {
+    useEventListener(() => window, 'scroll', handleViewportChange, true)
+    useEventListener(() => window, 'resize', handleViewportChange)
+  }
 
   return {
     isOpen,
     rootRef,
+    triggerRef,
     open,
     close,
     toggle,

package/src/composables/useEventStream.ts

@@ -7,6 +7,7 @@ import {
   shallowRef,
   type Ref,
 } from 'vue'
+import { tryUseSettingsStore } from '../stores/settings'
 
 export type EventStreamTransport = (
   input: RequestInfo | URL,
@@ -26,7 +27,16 @@ export interface EventStreamOptions<TData = string> {
   headers?: HeadersInit
   credentials?: RequestCredentials
   immediate?: boolean
+  /**
+   * Reconnect after a dropped stream. Left unset, it follows the platform's
+   * `wsAutoReconnect` setting, defaulting to `true` without a settings store.
+   */
   reconnect?: boolean
+  /**
+   * Delay before the first reconnect attempt. Left unset, it follows the
+   * platform's `wsReconnectInterval` setting, defaulting to 2000 ms without a
+   * settings store. A server-sent `retry:` field still overrides it.
+   */
   reconnectDelayMs?: number
   parseJson?: boolean
   shouldReconnect?: (cause?: unknown) => boolean
@@ -114,7 +124,9 @@ export function useEventStream<TData = string>(
   let controller: AbortController | null = null
   let reader: ReadableStreamDefaultReader<Uint8Array> | null = null
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null
-  let reconnectDelayMs = options.reconnectDelayMs ?? 2_000
+  const settings = tryUseSettingsStore()
+  const reconnectEnabled = options.reconnect ?? settings?.wsAutoReconnect ?? true
+  let reconnectDelayMs = options.reconnectDelayMs ?? settings?.wsReconnectInterval ?? 2_000
   let stopped = true
   let generation = 0
 
@@ -135,7 +147,7 @@ export function useEventStream<TData = string>(
 
   function scheduleReconnect(connectionGeneration: number, cause?: unknown): void {
     if (stopped || generation !== connectionGeneration) return
-    if (options.reconnect === false || options.shouldReconnect?.(cause) === false) {
+    if (!reconnectEnabled || options.shouldReconnect?.(cause) === false) {
       stopped = true
       return
     }

package/src/composables/useFileImport.ts

@@ -1,4 +1,5 @@
 import { ref, shallowRef, type Ref, type ShallowRef } from 'vue'
+import { readErrorMessage } from '../utils/errors'
 
 export interface DelimitedTable {
   columns: string[]
@@ -63,7 +64,7 @@ export function useFileImport<TResult = string>(
       result.value = parsed
       return parsed
     } catch (err) {
-      const message = readErrorMessage(err)
+      const message = readErrorMessage(err, 'Failed to import file.')
       error.value = message
       throw err
     } finally {
@@ -223,9 +224,3 @@ function formatBytes(bytes: number): string {
   if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
   return `${Math.round(bytes / (1024 * 1024))} MB`
 }
-
-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 import file.'
-}

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,12 @@ 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 type {
   GeneratedAnalysisJob,
   GeneratedAnalysisJobInput,
@@ -102,11 +105,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
@@ -468,12 +472,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 +529,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 +566,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)
@@ -910,7 +914,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 +926,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 +976,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 +1004,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 {
@@ -1065,6 +1076,7 @@ function createPluginJobs(
     pause,
     resume,
     dispose,
+    jobsAdapter,
   }
 }