@morscherlab/mint-sdk 1.2.0-beta.8 → 1.2.0

package/src/composables/filePicker/usePickerSelection.ts

@@ -0,0 +1,259 @@
+import { computed, ref, shallowRef, watch } from 'vue'
+import type {
+  PickerCapability,
+  PickerExcluded,
+  PickerFile,
+  PickerNode,
+  PickerSelection,
+  PickerSelectionMode,
+} from '../../types/filePicker'
+import type { usePickerNavigation } from './usePickerNavigation'
+import { pickerExclusion } from './validation'
+
+type Navigation = ReturnType<typeof usePickerNavigation>
+export function usePickerSelection(
+  nav: Navigation,
+  mode: () => PickerSelectionMode,
+  capability: () => PickerCapability | undefined,
+  skipBlanks: () => boolean,
+) {
+  const keys = ref(new Set<string>())
+  const dropped = ref(new Set<string>())
+  const focusPath = shallowRef('')
+  const resolving = shallowRef(false)
+  const resolutionError = shallowRef('')
+  let anchor = ''
+  let generation = 0
+
+  function ancestorSelected(node: PickerNode, candidates = keys.value): boolean {
+    const seen = new Set<string>()
+    let parent = node.parentPath
+    while (parent && !seen.has(parent)) {
+      if (candidates.has(parent)) return true
+      seen.add(parent)
+      parent = nav.nodes.value.get(parent)?.parentPath
+    }
+    return false
+  }
+  function exclusion(node: PickerNode) {
+    if (!nav.isAllowed(node))
+      return { path: node.path, name: node.name, reason: 'forbidden' as const }
+    const own = pickerExclusion(node, capability(), skipBlanks())
+    if (own) return own
+    const seen = new Set<string>()
+    let parent = node.parentPath
+    while (parent && !seen.has(parent)) {
+      seen.add(parent)
+      const folder = nav.nodes.value.get(parent)
+      if (!folder) break
+      const inherited = pickerExclusion(folder, capability(), skipBlanks())
+      if (inherited) return { ...inherited, path: node.path, name: node.name }
+      parent = folder.parentPath
+    }
+    return null
+  }
+  function selected(node: PickerNode): boolean {
+    return (
+      !exclusion(node) &&
+      !dropped.value.has(node.path) &&
+      !ancestorSelected(node, dropped.value) &&
+      (keys.value.has(node.path) || (mode() === 'folder+files' && ancestorSelected(node)))
+    )
+  }
+  function selectable(node: PickerNode): boolean {
+    if (exclusion(node)) return false
+    return node.kind === 'folder'
+      ? mode() === 'folder' || mode() === 'folder+files'
+      : mode() !== 'folder'
+  }
+  function select(
+    node: PickerNode,
+    modifiers: { metaKey?: boolean; ctrlKey?: boolean; shiftKey?: boolean; toggle?: boolean } = {},
+  ) {
+    if (exclusion(node)) return
+    focusPath.value = node.path
+    if (!selectable(node)) return
+    const multi = mode() === 'multi-file' || mode() === 'folder+files'
+    // Multi modes behave like a checklist: a plain click (or Space) adds or
+    // removes one row, Shift extends a range, Ctrl/Cmd is accepted for habit.
+    const additive = multi && (modifiers.metaKey || modifiers.ctrlKey || modifiers.toggle)
+    if (multi && modifiers.shiftKey && anchor) {
+      const rows = nav.rows.value.map((row) => row.node)
+      const from = rows.findIndex((item) => item.path === anchor)
+      const to = rows.findIndex((item) => item.path === node.path)
+      if (from >= 0 && to >= 0) {
+        keys.value = new Set([
+          ...(additive ? keys.value : []),
+          ...rows
+            .slice(Math.min(from, to), Math.max(from, to) + 1)
+            .filter(selectable)
+            .map((item) => item.path),
+        ])
+        dropped.value.clear()
+        return
+      }
+    }
+    if (additive || (modifiers.toggle && (selected(node) || dropped.value.has(node.path)))) {
+      if (mode() === 'folder+files' && ancestorSelected(node)) {
+        if (dropped.value.has(node.path)) dropped.value.delete(node.path)
+        else dropped.value.add(node.path)
+      } else if (keys.value.has(node.path)) keys.value.delete(node.path)
+      else {
+        keys.value.add(node.path)
+        dropped.value.delete(node.path)
+      }
+    } else {
+      keys.value = new Set([node.path])
+      dropped.value.clear()
+    }
+    anchor = node.path
+  }
+  function reset(selection?: PickerSelection | null) {
+    ++generation
+    keys.value.clear()
+    dropped.value.clear()
+    resolving.value = false
+    resolutionError.value = ''
+    focusPath.value = ''
+    if (selection?.source === 'server') {
+      const files =
+        mode() === 'folder'
+          ? []
+          : mode() === 'single-file'
+            ? selection.files.slice(0, 1)
+            : selection.files
+      const folders =
+        mode() === 'folder'
+          ? selection.folders.slice(0, 1)
+          : mode() === 'folder+files'
+            ? selection.folders
+            : []
+      nav.register(files)
+      folders.forEach((path) => {
+        if (!nav.nodes.value.has(path))
+          nav.register([
+            { kind: 'folder', path, name: 'Selected folder', parentName: 'Selected location' },
+          ])
+        keys.value.add(path)
+      })
+      files.forEach((file) => keys.value.add(file.path))
+      selection.excluded
+        .filter((item) => item.reason === 'deselected')
+        .forEach((item) => dropped.value.add(item.path))
+    }
+  }
+  const roots = computed(() =>
+    [...keys.value]
+      .map((key) => nav.nodes.value.get(key))
+      .filter((node): node is PickerNode => !!node && !ancestorSelected(node) && nav.isAllowed(node)),
+  )
+  const chosen = computed(() => {
+    const files: PickerFile[] = []
+    const excluded: PickerExcluded[] = []
+    for (const node of nav.nodes.value.values()) {
+      if (!nav.isAllowed(node)) continue
+      if (!keys.value.has(node.path) && !ancestorSelected(node)) continue
+      const reason =
+        exclusion(node) ??
+        (dropped.value.has(node.path)
+          ? { path: node.path, name: node.name, reason: 'deselected' as const }
+          : null)
+      // A dropped folder excludes its descendants as well.
+      const droppedByParent = ancestorSelected(node, dropped.value)
+      if (reason || droppedByParent) {
+        if (node.kind === 'file' || reason?.reason === 'unreadable')
+          excluded.push(reason ?? { path: node.path, name: node.name, reason: 'deselected' })
+      } else if (node.kind === 'file') files.push(node)
+    }
+    return { files, excluded, bytes: files.reduce((total, node) => total + (node.bytes ?? 0), 0) }
+  })
+  async function resolve() {
+    const token = ++generation
+    resolving.value = true
+    resolutionError.value = ''
+    let count = 0
+    const seen = new Set<string>()
+    async function walk(node: PickerNode, ancestors: string[] = []): Promise<PickerFile[]> {
+      if (token !== generation) throw new DOMException('Cancelled', 'AbortError')
+      if (!nav.isAllowed(node)) return []
+      if (node.kind === 'file') return [node]
+      if (node.unavailableReason) return []
+      if (ancestors.includes(node.path))
+        throw new Error('The adapter returned a circular folder tree.')
+      if (seen.has(node.path)) return []
+      seen.add(node.path)
+      if (++count > 500 || ancestors.length > 30)
+        throw new Error('This selection is too large to validate. Choose a smaller folder.')
+      const children = await nav.loadChildren(node.path, ancestors)
+      const files: PickerFile[] = []
+      for (const child of children) files.push(...(await walk(child, [...ancestors, node.path])))
+      if (token !== generation) throw new DOMException('Cancelled', 'AbortError')
+      const formats: Record<string, number> = {}
+      files.forEach((file) => {
+        formats[file.format] = (formats[file.format] ?? 0) + 1
+      })
+      nav.register([
+        {
+          ...node,
+          fileCount: files.length,
+          bytes: files.reduce((sum, file) => sum + (file.bytes ?? 0), 0),
+          formats,
+        },
+      ])
+      return files
+    }
+    try {
+      for (const node of roots.value) await walk(node)
+      if (token === generation) {
+        // Resolved descendants inherit their folder, including restored selections.
+        for (const key of [...keys.value]) {
+          const node = nav.nodes.value.get(key)
+          if (node && ancestorSelected(node)) keys.value.delete(key)
+        }
+      }
+    } catch (cause) {
+      if (token === generation)
+        resolutionError.value =
+          cause instanceof Error ? cause.message : 'Could not validate the selection.'
+    } finally {
+      if (token === generation) resolving.value = false
+    }
+  }
+  const focused = computed(() => {
+    const node = nav.nodes.value.get(focusPath.value)
+    return node && nav.isAllowed(node) ? node : roots.value[roots.value.length - 1] ?? null
+  })
+  watch(
+    () => new Map([...nav.nodes.value].map(([path, node]) => [path, nav.isAllowed(node)])),
+    (allowed, previous) => {
+      if (keys.value.size && [...allowed].some(([path, value]) =>
+        previous.has(path) && value !== previous.get(path),
+      )) void resolve()
+    },
+  )
+  function folderProgress(node: PickerNode): string {
+    if (node.kind !== 'folder' || node.fileCount == null) return ''
+    const allowed = chosen.value.files.filter((file) =>
+      ancestorSelected(file, new Set([node.path])),
+    ).length
+    return `${selected(node) ? allowed : 0} / ${node.fileCount}`
+  }
+  return {
+    keys,
+    dropped,
+    focusPath,
+    resolving,
+    resolutionError,
+    roots,
+    chosen,
+    focused,
+    select,
+    selected,
+    selectable,
+    exclusion,
+    reset,
+    resolve,
+    folderProgress,
+    ancestorSelected,
+  }
+}

package/src/composables/filePicker/validation.ts

@@ -0,0 +1,41 @@
+import type { PickerCapability, PickerExcluded, PickerNode } from '../../types/filePicker'
+
+export function normalizePickerFormat(format: string): string {
+  return format.trim().replace(/^\./, '').toLowerCase()
+}
+
+export function pickerExclusion(
+  node: PickerNode,
+  capability?: PickerCapability,
+  skipBlanks = false,
+): PickerExcluded | null {
+  const base = { path: node.path, name: node.name }
+  if (node.unavailableReason) return { ...base, reason: 'unreadable' }
+  if (skipBlanks && capability?.isBlank?.(node)) return { ...base, reason: 'blank' }
+  if (node.kind === 'folder') return null
+  const formats = capability?.formats.map(normalizePickerFormat) ?? []
+  if (formats.length && !formats.some((format) => node.name.toLowerCase().endsWith(`.${format}`))) {
+    return { ...base, reason: 'unsupported' }
+  }
+  if (capability?.maxBytes != null && node.bytes != null && node.bytes > capability.maxBytes) {
+    return { ...base, reason: 'tooLarge' }
+  }
+  return null
+}
+
+export function pickerReason(excluded: PickerExcluded | null, node?: PickerNode): string {
+  if (!excluded) return ''
+  return {
+    unsupported: 'This format is not supported by this source.',
+    tooLarge: 'This file exceeds the size limit for this source.',
+    blank: 'Skipped by the blank-file rule.',
+    unreadable: node?.unavailableReason || 'This item cannot be read.',
+    deselected: 'Removed from the selection.',
+    forbidden: 'This item is not permitted by the system filter.',
+  }[excluded.reason]
+}
+
+export function pickerFormat(name: string): string {
+  const compound = /\.(mzml|mzxml)\.gz$/i.exec(name)
+  return compound ? `${compound[1]}.gz` : name.includes('.') ? name.split('.').pop()! : ''
+}

package/src/composables/index.ts

@@ -174,6 +174,11 @@ export {
   type UseAnalysisArtifactsOptions,
   type UseAnalysisArtifactsReturn,
 } from './useAnalysisArtifacts'
+export {
+  useFileBrowser,
+  type UseFileBrowserOptions,
+  type UseFileBrowserReturn,
+} from './useFileBrowser'
 export {
   buildAnalysisArtifactTargetQuery,
   parseAnalysisArtifactTarget,
@@ -549,8 +554,20 @@ export {
   type UseRovingFocusOptions,
   type UseRovingFocusReturn,
 } from './useRovingFocus'
+export {
+  reorderList,
+  useListReorder,
+  useReorderAnnouncer,
+  REORDER_ANNOUNCER_STYLE,
+  type ListReorderMove,
+  type UseListReorderOptions,
+  type UseListReorderReturn,
+  type UseReorderAnnouncerReturn,
+} from './useListReorder'
 export {
   useMenuKeyboard,
   type UseMenuKeyboardOptions,
   type UseMenuKeyboardReturn,
 } from './useMenuKeyboard'
+
+export { usePlatformFilePickerAdapter, encodePlatformPickerPath, decodePlatformPickerPath } from './usePlatformFilePickerAdapter'

package/src/composables/useApi.ts

@@ -1,6 +1,7 @@
 import axios, { type AxiosInstance, type AxiosRequestConfig, type InternalAxiosRequestConfig } from 'axios'
 import { useSettingsStore } from '../stores/settings'
 import { useAuthStore } from '../stores/auth'
+import { MintApiError, mintApiErrorFromResponse } from '../apiErrors'
 
 let apiClientInstance: AxiosInstance | null = null
 let interceptorAttached = false
@@ -8,11 +9,13 @@ let interceptorAttached = false
 interface MintAxiosRequestConfig extends AxiosRequestConfig {
   _mintSkipAuth?: boolean
   _mintAuthToken?: string
+  _mintTypedErrors?: boolean
 }
 
 interface MintInternalAxiosRequestConfig extends InternalAxiosRequestConfig {
   _mintSkipAuth?: boolean
   _mintAuthToken?: string
+  _mintTypedErrors?: boolean
 }
 
 type MutableHeaders = Record<string, unknown> & {
@@ -103,14 +106,27 @@ function getAuthorizationHeader(headers: AxiosRequestConfig['headers']): unknown
   return key ? bag[key] : undefined
 }
 
-/** Raised when an authenticated SDK request is rejected because the login is no longer valid. */
-export class AuthenticationRequiredError extends Error {
-  readonly code = 'AUTHENTICATION_REQUIRED'
-  readonly status = 401
-
-  constructor(readonly cause?: unknown) {
-    super('Authentication required. Please sign in again.')
-    this.name = 'AuthenticationRequiredError'
+/**
+ * Raised when an authenticated SDK request is rejected because the login is no
+ * longer valid. It is also a `MintApiError` (status 401), so typed-error callers
+ * and `instanceof AuthenticationRequiredError` callers both recognise it.
+ */
+export class AuthenticationRequiredError extends MintApiError {
+  override readonly name: string = 'AuthenticationRequiredError'
+  declare readonly code: 'AUTHENTICATION_REQUIRED'
+  declare readonly status: 401
+
+  constructor(cause?: unknown, envelope?: MintApiError) {
+    super(
+      'Authentication required. Please sign in again.',
+      'AUTHENTICATION_REQUIRED',
+      401,
+      envelope?.requestId ?? null,
+      envelope?.details ?? null,
+      envelope?.detail,
+      envelope?.body ?? null,
+      cause,
+    )
   }
 }
 
@@ -118,12 +134,13 @@ export class AuthenticationRequiredError extends Error {
 export function authenticationRequiredError(
   cause: unknown,
   rejectedToken?: string,
+  envelope?: MintApiError,
 ): AuthenticationRequiredError {
   const currentAuthStore = useAuthStore()
   if (rejectedToken && currentAuthStore.token === rejectedToken) {
     currentAuthStore.clearToken()
   }
-  return new AuthenticationRequiredError(cause)
+  return new AuthenticationRequiredError(cause, envelope)
 }
 
 function getApiClient(): AxiosInstance {
@@ -141,6 +158,8 @@ export interface ApiClientOptions {
   baseUrl?: string
   timeout?: number
   withAuth?: boolean
+  /** Normalize failed responses into MintApiError. Generated clients enable this by default. */
+  typedErrors?: boolean
 }
 
 export interface UseApiReturn {
@@ -187,11 +206,35 @@ export function useApi(options: ApiClientOptions = {}): UseApiReturn {
     })
     apiClient.interceptors.response.use(
       (response) => response,
-      (error: unknown) => {
-        if (axios.isAxiosError(error) && error.response?.status === 401) {
+      async (error: unknown) => {
+        if (axios.isAxiosError(error) && error.response) {
           const request = error.config as MintInternalAxiosRequestConfig | undefined
-          if (request?._mintSkipAuth !== true) {
-            return Promise.reject(authenticationRequiredError(error, request?._mintAuthToken))
+          if (request?._mintTypedErrors) {
+            let payload: unknown = error.response.data
+            if (payload instanceof Blob) {
+              try {
+                payload = JSON.parse(await payload.text())
+              } catch {
+                // Keep non-JSON download errors available as the original body.
+              }
+            }
+            const typed = mintApiErrorFromResponse(
+              error.response.status,
+              payload,
+              {
+                requestId: String(error.response.headers?.['x-request-id'] ?? '') || null,
+                cause: error,
+              },
+            )
+            if (error.response.status === 401 && request._mintSkipAuth !== true) {
+              return Promise.reject(authenticationRequiredError(error, request._mintAuthToken, typed))
+            }
+            return Promise.reject(typed)
+          }
+          if (error.response.status === 401) {
+            if (request?._mintSkipAuth !== true) {
+              return Promise.reject(authenticationRequiredError(error, request?._mintAuthToken))
+            }
           }
         }
         return Promise.reject(error)
@@ -213,6 +256,7 @@ export function useApi(options: ApiClientOptions = {}): UseApiReturn {
     const base: MintAxiosRequestConfig = {
       baseURL: getBaseUrl(),
       timeout: options.timeout ?? settingsStore.requestTimeout,
+      _mintTypedErrors: options.typedErrors,
       ...config,
     }
     // Strip auth header if explicitly disabled

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
     }