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

package/src/composables/filePicker/usePickerNavigation.ts

@@ -0,0 +1,220 @@
+import { computed, onScopeDispose, ref, shallowRef } from 'vue'
+import type {
+  PickerAdapter,
+  PickerNode,
+  PickerRequest,
+  PickerTreeRow,
+} from '../../types/filePicker'
+
+export function usePickerNavigation(
+  adapter: () => PickerAdapter,
+  request: () => PickerRequest,
+  systemFilter: (node: PickerNode) => boolean = () => true,
+) {
+  const path = shallowRef('')
+  const trail = ref<{ path: string; label: string }[]>([])
+  const entries = shallowRef<PickerNode[]>([])
+  const nodes = ref(new Map<string, PickerNode>())
+  const children = shallowRef(new Map<string, PickerNode[]>())
+  const expanded = ref(new Set<string>())
+  const expanding = ref(new Set<string>())
+  const expansionErrors = ref(new Map<string, string>())
+  const loading = shallowRef(false)
+  const error = shallowRef('')
+  let epoch = 0
+  let navigation = 0
+  let controller: AbortController | undefined
+  const pending = new Map<string, Promise<PickerNode[]>>()
+  const childControllers = new Set<AbortController>()
+
+  function isAllowed(node: PickerNode): boolean {
+    const seen = new Set<string>()
+    let current: PickerNode | undefined = node
+    while (current && !seen.has(current.path)) {
+      if (!systemFilter(current)) return false
+      seen.add(current.path)
+      current = current.parentPath ? nodes.value.get(current.parentPath) : undefined
+    }
+    return true
+  }
+
+  function register(items: PickerNode[], parent?: string) {
+    for (const item of items)
+      nodes.value.set(item.path, {
+        ...item,
+        parentPath:
+          item.parentPath !== undefined
+            ? item.parentPath
+            : parent !== undefined
+              ? parent || null
+              : (nodes.value.get(item.path)?.parentPath ?? null),
+      })
+  }
+  function invalidate() {
+    ++epoch
+    ++navigation
+    controller?.abort()
+    childControllers.forEach((item) => item.abort())
+    childControllers.clear()
+    pending.clear()
+    children.value = new Map()
+    expanding.value.clear()
+    expansionErrors.value.clear()
+  }
+  function clear() {
+    invalidate()
+    nodes.value.clear()
+    expanded.value.clear()
+    expanding.value.clear()
+    expansionErrors.value.clear()
+    entries.value = []
+    loading.value = false
+    error.value = ''
+  }
+  async function loadChildren(
+    folder: string,
+    ancestors: string[] = [],
+    refresh = false,
+  ): Promise<PickerNode[]> {
+    if (ancestors.includes(folder)) throw new Error('The adapter returned a circular folder tree.')
+    const cached = children.value.get(folder)
+    if (cached) return cached
+    const existing = pending.get(folder)
+    if (existing) return existing
+    const token = epoch
+    const abort = new AbortController()
+    childControllers.add(abort)
+    const task = adapter()
+      .listChildren(folder, { ...request(), ...(refresh && { refresh }), signal: abort.signal })
+      .then((items) => {
+        if (token !== epoch) throw new DOMException('Cancelled', 'AbortError')
+        const retained = new Set(items.map((item) => item.path))
+        function remove(path: string, seen = new Set<string>()) {
+          if (seen.has(path) || path === folder) return
+          seen.add(path)
+          for (const node of nodes.value.values())
+            if (node.parentPath === path) remove(node.path, seen)
+          nodes.value.delete(path)
+          children.value.delete(path)
+        }
+        for (const node of nodes.value.values())
+          if (node.parentPath === folder && !retained.has(node.path)) remove(node.path)
+        register(items, folder)
+        children.value = new Map(children.value).set(folder, items)
+        return items
+      })
+      .finally(() => {
+        childControllers.delete(abort)
+        if (token === epoch) pending.delete(folder)
+      })
+    pending.set(folder, task)
+    return task
+  }
+  async function load(query = '', recursive = false, refresh = false) {
+    const token = ++navigation
+    controller?.abort()
+    controller = new AbortController()
+    const options = { ...request(), ...(refresh && { refresh }), signal: controller.signal }
+    loading.value = true
+    error.value = ''
+    entries.value = []
+    try {
+      const items = query.trim()
+        ? await adapter().search(query.trim(), { path: path.value, recursive }, options)
+        : path.value
+          ? await loadChildren(path.value, [], refresh)
+          : await adapter().listRoot(options)
+      if (token !== navigation) return
+      register(items, query.trim() ? undefined : path.value)
+      entries.value = items
+    } catch (cause) {
+      if (token === navigation)
+        error.value = cause instanceof Error ? cause.message : 'Could not read this location.'
+    } finally {
+      if (token === navigation) loading.value = false
+    }
+  }
+  async function expand(node: PickerNode) {
+    if (node.kind !== 'folder' || node.unavailableReason || !isAllowed(node)) return
+    if (expanded.value.has(node.path)) {
+      expanded.value.delete(node.path)
+      return
+    }
+    expanded.value.add(node.path)
+    expanding.value.add(node.path)
+    expansionErrors.value.delete(node.path)
+    const token = epoch
+    try {
+      await loadChildren(node.path)
+    } catch (cause) {
+      if (token === epoch)
+        expansionErrors.value.set(
+          node.path,
+          cause instanceof Error ? cause.message : 'Could not read this folder.',
+        )
+    } finally {
+      if (token === epoch) expanding.value.delete(node.path)
+    }
+  }
+  function enter(node: PickerNode) {
+    if (node.kind !== 'folder' || node.unavailableReason || !isAllowed(node)) return
+    const index = trail.value.findIndex((crumb) => crumb.path === node.path)
+    trail.value =
+      index >= 0
+        ? trail.value.slice(0, index + 1)
+        : [...trail.value, { path: node.path, label: node.name }]
+    path.value = node.path
+  }
+  function up(target?: string) {
+    const index =
+      target !== undefined
+        ? trail.value.findIndex((crumb) => crumb.path === target)
+        : trail.value.length - 2
+    trail.value = index < 0 ? [] : trail.value.slice(0, index + 1)
+    path.value = trail.value[trail.value.length - 1]?.path ?? ''
+  }
+  const rows = computed(() => {
+    const result: PickerTreeRow[] = []
+    function visit(items: PickerNode[], depth: number, ancestors: Set<string>) {
+      for (const item of items) {
+        if (ancestors.has(item.path) || depth > 30) continue
+        const node = nodes.value.get(item.path) ?? item
+        if (!isAllowed(node)) continue
+        result.push({
+          node,
+          depth,
+          expanded: expanded.value.has(item.path),
+          loading: expanding.value.has(item.path),
+          error: expansionErrors.value.get(item.path),
+        })
+        if (expanded.value.has(item.path))
+          visit(children.value.get(item.path) ?? [], depth + 1, new Set([...ancestors, item.path]))
+      }
+    }
+    visit(entries.value, 0, new Set())
+    return result
+  })
+  onScopeDispose(clear)
+  return {
+    path,
+    trail,
+    entries,
+    nodes,
+    children,
+    expanded,
+    expanding,
+    expansionErrors,
+    loading,
+    error,
+    rows,
+    isAllowed,
+    clear,
+    invalidate,
+    register,
+    loadChildren,
+    load,
+    expand,
+    enter,
+    up,
+  }
+}

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,
@@ -564,3 +569,5 @@ export {
   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