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

package/src/composables/useFileBrowser.ts

@@ -0,0 +1,314 @@
+import {
+  computed,
+  getCurrentScope,
+  onScopeDispose,
+  ref,
+  shallowRef,
+  toValue,
+  watch,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+
+import type {
+  FileBrowserSortKey,
+  FileDirectoryListing,
+  FileEntry,
+  FilePathCrumb,
+  FileSelection,
+  ServerMount,
+} from '../types/fileBrowserTypes'
+import { useApi } from './useApi'
+import { getInjectedPlatformContext } from './platformContextHelpers'
+import { useRequestSyncState } from './useRequestSyncState'
+
+export interface UseFileBrowserOptions {
+  /** Extensions the caller cares about; entries are flagged, never removed. */
+  typeRules?: MaybeRefOrGetter<string[] | undefined>
+  /** Mount to open first; defaults to the first available one. */
+  initialMountId?: MaybeRefOrGetter<string | undefined>
+  /** Override the platform API base URL (standalone plugin dev). */
+  apiBaseUrl?: string
+}
+
+export interface UseFileBrowserReturn {
+  /** Every configured mount, offline ones included. */
+  mounts: Ref<ServerMount[]>
+  /** Mount the current listing belongs to. */
+  mountId: Ref<string>
+  /** Mount-relative path of the current listing. */
+  path: Ref<string>
+  /** Parent path, or null at a mount root. */
+  parent: Ref<string | null>
+  entries: Ref<FileEntry[]>
+  breadcrumbs: Ref<FilePathCrumb[]>
+  /** Directory size before any search filter. */
+  totalCount: Ref<number | null>
+  /** How many entries satisfy the type rules. */
+  matchCount: Ref<number | null>
+  /** How many rows this listing carries, after search and any cap. */
+  shownCount: Ref<number | null>
+  /** True when the server capped the listing. */
+  truncated: Ref<boolean>
+  search: Ref<string>
+  sort: Ref<FileBrowserSortKey>
+  /** Controlled selection, ready to bind to FileBrowserModal. */
+  selected: Ref<FileSelection[]>
+  isLoading: ComputedRef<boolean>
+  error: Ref<string | null>
+  /** Load the mount list and open the first available mount. */
+  init: () => Promise<void>
+  /** Open a directory, or a mount root when path is empty. */
+  navigate: (location: { mount_id: string; path: string }) => Promise<void>
+  /** Re-read the current directory. */
+  refresh: () => Promise<void>
+  /** Take the directory currently being viewed as the input. */
+  selectCurrentFolder: () => void
+  clear: () => void
+}
+
+/**
+ * Drives FileBrowserModal against the platform's `/api/filesystem` routes.
+ *
+ * Requires the `filesystem.browse` permission and a deployment that declares
+ * mounts; with none configured the routes are absent and `mounts` stays empty.
+ */
+export function useFileBrowser(options: UseFileBrowserOptions = {}): UseFileBrowserReturn {
+  const injectedContext = getInjectedPlatformContext()
+  const api = useApi({ baseUrl: options.apiBaseUrl ?? injectedContext?.platformApiUrl })
+  const sync = useRequestSyncState('Could not read the server mounts.')
+
+  const mounts = ref<ServerMount[]>([])
+  const mountId = shallowRef('')
+  const path = shallowRef('')
+  const parent = ref<string | null>(null)
+  const entries = ref<FileEntry[]>([])
+  const breadcrumbs = ref<FilePathCrumb[]>([])
+  const totalCount = ref<number | null>(null)
+  const matchCount = ref<number | null>(null)
+  const shownCount = ref<number | null>(null)
+  const truncated = ref(false)
+  const search = shallowRef('')
+  const sort = shallowRef<FileBrowserSortKey>('name')
+  const selected = ref<FileSelection[]>([])
+
+  const mountsLoading = shallowRef(false)
+  const listingLoading = shallowRef(false)
+  const listingReady = shallowRef(false)
+  const isLoading = computed(() => mountsLoading.value || listingLoading.value)
+  let listToken = 0
+  let mountsToken = 0
+  let disposed = false
+  let listingController: AbortController | undefined
+  let mountsController: AbortController | undefined
+  let searchTimer: ReturnType<typeof setTimeout> | undefined
+
+  function resetListing(): void {
+    listingReady.value = false
+    entries.value = []
+    breadcrumbs.value = []
+    parent.value = null
+    totalCount.value = null
+    matchCount.value = null
+    shownCount.value = null
+    truncated.value = false
+  }
+
+  function typeRuleParams(): string {
+    const rules = toValue(options.typeRules) ?? []
+    return rules.map((rule) => `&type_rules=${encodeURIComponent(rule)}`).join('')
+  }
+
+  /** Prefer the API's own `detail` over axios's "Request failed with status N". */
+  function describe(cause: unknown, fallback: string): string {
+    const detail = (cause as { response?: { data?: { detail?: unknown } } })?.response?.data?.detail
+    return typeof detail === 'string' && detail ? detail : sync.readErrorMessage(cause, fallback)
+  }
+
+  function fail(cause: unknown, fallback: string): void {
+    sync.setError(new Error(describe(cause, fallback)), fallback)
+  }
+
+  function statusOf(cause: unknown): number | undefined {
+    return (cause as { response?: { status?: number } })?.response?.status
+  }
+
+  async function loadMounts(): Promise<boolean> {
+    const token = ++mountsToken
+    mountsController?.abort()
+    mountsController = new AbortController()
+    mountsLoading.value = true
+    try {
+      const data = await api.get<{ mounts: ServerMount[] }>('/filesystem/mounts', {
+        signal: mountsController.signal,
+      })
+      if (disposed || token !== mountsToken) return false
+      mounts.value = data.mounts ?? []
+      sync.clearError()
+      sync.markLoaded()
+      return true
+    } catch (cause) {
+      if (disposed || token !== mountsToken) return false
+      // The platform only registers these routes once mounts are configured, so
+      // a 404 means "none declared" — an empty sidebar, not a failure.
+      if (statusOf(cause) === 404) {
+        mounts.value = []
+        sync.clearError()
+        sync.markLoaded()
+        return true
+      }
+      mounts.value = []
+      fail(cause, 'Could not read the server mounts.')
+      return false
+    } finally {
+      if (token === mountsToken) mountsLoading.value = false
+    }
+  }
+
+  async function navigate(location: { mount_id: string; path: string }): Promise<void> {
+    if (disposed || !location.mount_id) return
+    clearTimeout(searchTimer)
+    const token = ++listToken
+    listingController?.abort()
+    listingController = new AbortController()
+    listingLoading.value = true
+    mountId.value = location.mount_id
+    path.value = location.path
+    resetListing()
+    sync.clearError()
+    try {
+      const query =
+        `mount_id=${encodeURIComponent(location.mount_id)}` +
+        `&path=${encodeURIComponent(location.path)}` +
+        `&sort=${sort.value}` +
+        (search.value ? `&search=${encodeURIComponent(search.value)}` : '') +
+        typeRuleParams()
+      const listing = await api.get<FileDirectoryListing>(`/filesystem/browse?${query}`, {
+        signal: listingController.signal,
+      })
+      if (disposed || token !== listToken) return
+      mountId.value = listing.mount_id
+      path.value = listing.path
+      parent.value = listing.parent ?? null
+      entries.value = listing.entries ?? []
+      breadcrumbs.value = listing.breadcrumbs ?? []
+      totalCount.value = listing.total_count ?? null
+      matchCount.value = listing.match_count ?? null
+      shownCount.value = listing.shown_count ?? listing.entries?.length ?? null
+      truncated.value = listing.truncated ?? false
+      listingReady.value = true
+      sync.clearError()
+      sync.markLoaded()
+    } catch (cause) {
+      if (disposed || token !== listToken) return
+      entries.value = []
+      fail(cause, 'Could not read that folder.')
+    } finally {
+      if (token === listToken) listingLoading.value = false
+    }
+  }
+
+  async function init(): Promise<void> {
+    if (disposed) return
+    const navigationToken = listToken
+    if (!(await loadMounts()) || disposed || navigationToken !== listToken) return
+    const preferred = toValue(options.initialMountId)
+    // An offline mount is not navigable, so a remembered preference for one
+    // falls through to the first reachable mount instead of opening on an error.
+    const reachable = (mount: ServerMount): boolean => mount.available !== false
+    const target =
+      mounts.value.find((mount) => mount.id === preferred && reachable(mount)) ??
+      mounts.value.find(reachable)
+    if (target) await navigate({ mount_id: target.id, path: '' })
+    else {
+      mountId.value = ''
+      path.value = ''
+      resetListing()
+    }
+  }
+
+  async function refresh(): Promise<void> {
+    if (disposed) return
+    if (mountId.value) await navigate({ mount_id: mountId.value, path: path.value })
+    else await init()
+  }
+
+  function selectCurrentFolder(): void {
+    if (!mountId.value || !listingReady.value || isLoading.value || sync.error.value) return
+    const crumb = breadcrumbs.value[breadcrumbs.value.length - 1]
+    const key = JSON.stringify([mountId.value, path.value])
+    if (selected.value.some((item) => JSON.stringify([item.mount_id, item.path]) === key)) return
+    selected.value = [
+      ...selected.value,
+      {
+        mount_id: mountId.value,
+        path: path.value,
+        name: crumb?.label ?? path.value,
+        kind: 'directory',
+        child_count: totalCount.value,
+      },
+    ]
+  }
+
+  function clear(): void {
+    selected.value = []
+  }
+
+  // Both controls are server-side, so they only take effect on a re-fetch.
+  // Without these watchers the search box and sort button look live but are
+  // inert until the user happens to navigate.
+  watch(search, () => {
+    if (!mountId.value) return
+    clearTimeout(searchTimer)
+    // Debounced: search changes on every keystroke.
+    searchTimer = setTimeout(() => {
+      void refresh()
+    }, 250)
+  })
+
+  watch(sort, () => {
+    if (mountId.value) void refresh()
+  })
+
+  watch(
+    () => toValue(options.typeRules),
+    () => {
+      if (mountId.value) void refresh()
+    },
+    { deep: true },
+  )
+
+  if (getCurrentScope())
+    onScopeDispose(() => {
+      disposed = true
+      ++listToken
+      ++mountsToken
+      clearTimeout(searchTimer)
+      listingController?.abort()
+      mountsController?.abort()
+    })
+
+  return {
+    mounts,
+    mountId,
+    path,
+    parent,
+    entries,
+    breadcrumbs,
+    totalCount,
+    matchCount,
+    shownCount,
+    truncated,
+    search,
+    sort,
+    selected,
+    isLoading,
+    error: sync.error,
+    init,
+    navigate,
+    refresh,
+    selectCurrentFolder,
+    clear,
+  }
+}

package/src/composables/useFilePicker.ts

@@ -0,0 +1,366 @@
+import { computed, nextTick, onScopeDispose, ref, shallowRef, toRaw, watch } from 'vue'
+import type {
+  PickerAdapter,
+  PickerCapabilities,
+  PickerNode,
+  PickerSelection,
+  PickerSelectionMode,
+  PickerSource,
+} from '../types/filePicker'
+import { usePickerNavigation } from './filePicker/usePickerNavigation'
+import { usePickerSelection } from './filePicker/usePickerSelection'
+import { localFilesAdapter } from './filePicker/localFiles'
+
+interface PickerStateProps {
+  open: boolean
+  adapter: PickerAdapter
+  selectionMode: PickerSelectionMode
+  sources: PickerSource[]
+  capabilities: PickerCapabilities
+  initialPath: string
+  initialSelection: PickerSelection | null
+  systemFilter?: (node: PickerNode, source: PickerSource) => boolean
+}
+type PickerEmit = {
+  (event: 'update:open', value: boolean): void
+  (event: 'select', value: PickerSelection): void
+  (event: 'cancel'): void
+}
+
+/** Internal orchestration; public consumers use FilePicker's props and events. */
+export function useFilePicker(props: PickerStateProps, emit: PickerEmit) {
+  const sourceNames: Record<PickerSource, string> = {
+    server: 'Server',
+    localFile: 'Local files',
+  }
+  const sourceIcons: Record<PickerSource, string> = {
+    server: 'M4 6h16v5H4zM4 13h16v5H4zM7 8.5h.01M7 15.5h.01',
+    localFile: 'M4 17h16M6 5h12v9H6z',
+  }
+  const allowedSources = computed(() => [...new Set(props.sources)])
+  const source = shallowRef<PickerSource>(
+    allowedSources.value.includes(props.initialSelection?.source as PickerSource)
+      ? props.initialSelection!.source
+      : (allowedSources.value[0] ?? 'server'),
+  )
+  const query = shallowRef('')
+  const recursive = shallowRef(false)
+  const skipBlanks = shallowRef(false)
+  const reviewing = shallowRef(false)
+  const localFiles = shallowRef<File[]>([])
+  const localPaths = new WeakMap<File, string>()
+  const localAdapter = computed(() =>
+    localFilesAdapter(localFiles.value, localFiles.value.map((file) => localPaths.get(toRaw(file)))),
+  )
+  const nav = usePickerNavigation(
+    () => (source.value === 'localFile' ? localAdapter.value : props.adapter),
+    () => ({ source: source.value }),
+    (node) => props.systemFilter?.(node, source.value) !== false,
+  )
+  const capability = computed(() => props.capabilities[source.value])
+  const selection = usePickerSelection(
+    nav,
+    () => props.selectionMode,
+    () => capability.value,
+    () => skipBlanks.value,
+  )
+  const { path, trail, loading, error, rows } = nav
+  const { roots, chosen, focused, resolving, resolutionError } = selection
+  const previewNode = computed(() => {
+    const node = focused.value
+    if (!node || node.kind !== 'folder' || !selection.selected(node) || resolving.value) return node
+    const files = chosen.value.files.filter((file) =>
+      selection.ancestorSelected(file, new Set([node.path])),
+    )
+    const formats: Record<string, number> = {}
+    files.forEach((file) => {
+      formats[file.format] = (formats[file.format] ?? 0) + 1
+    })
+    return {
+      ...node,
+      bytes: files.reduce((sum, file) => sum + (file.bytes ?? 0), 0),
+      fileCount: files.length,
+      formats,
+    }
+  })
+
+  const searchArea = ref<HTMLElement | null>(null)
+  const confirmLabel = computed(
+    () =>
+      ({
+        'single-file': 'Use file',
+        'multi-file': 'Use files',
+        folder: 'Use folder',
+        'folder+files': 'Use selection',
+      })[props.selectionMode],
+  )
+  const folderCount = computed(() => roots.value.filter((node) => node.kind === 'folder').length)
+  const canConfirm = computed(
+    () =>
+      allowedSources.value.includes(source.value) &&
+      roots.value.length > 0 &&
+      chosen.value.files.length > 0 &&
+      !resolving.value &&
+      !loading.value &&
+      !error.value &&
+      !resolutionError.value,
+  )
+  let lastConfirmed: PickerSelection | null = null
+  let initialized = false
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let openGeneration = 0
+  const remembered = new Map<
+    PickerSource,
+    { path: string; trail: { path: string; label: string }[] }
+  >()
+
+  const knownFolders = new Map<PickerSource, PickerNode[]>()
+  function rememberFolders() {
+    knownFolders.set(
+      source.value,
+      [...nav.nodes.value.values()].filter((node) => node.kind === 'folder'),
+    )
+  }
+  function currentSeed() {
+    return props.initialSelection ?? lastConfirmed
+  }
+  async function restore() {
+    const token = ++openGeneration
+    const seed = currentSeed()
+    nav.register(knownFolders.get(source.value) ?? [])
+    selection.reset(seed?.source === source.value ? seed : null)
+    reviewing.value = false
+    if (!allowedSources.value.includes(source.value)) return
+    if (seed?.source === 'localFile' && source.value === 'localFile') {
+      seed.files.forEach((file, index) => {
+        if (seed.relativePaths?.[index]) localPaths.set(toRaw(file), seed.relativePaths[index]!)
+      })
+      localFiles.value = seed.files
+    }
+    await nav.load(query.value, recursive.value)
+    if (token !== openGeneration || !props.open) return
+    if (seed?.source === 'localFile' && source.value === 'localFile') {
+      // Restored local File objects are already the confirmed subset.
+      await selectLocalFiles()
+    }
+    if (selection.keys.value.size) await selection.resolve()
+  }
+  watch(
+    () => props.open,
+    (open) => {
+      clearTimeout(timer)
+      if (open) {
+        if (!initialized) {
+          path.value = props.initialPath
+          if (path.value) trail.value = [{ path: path.value, label: 'Current folder' }]
+          initialized = true
+        }
+        const seed = currentSeed()
+        if (seed && allowedSources.value.includes(seed.source) && seed.source !== source.value)
+          void switchSource(seed.source)
+        else void restore()
+      } else {
+        ++openGeneration
+        rememberFolders()
+        selection.reset()
+        nav.clear()
+      }
+    },
+    { immediate: true },
+  )
+  watch([query, recursive], () => {
+    clearTimeout(timer)
+    if (props.open)
+      timer = setTimeout(() => {
+        void nav.load(query.value, recursive.value)
+      }, 200)
+  })
+  watch(
+    () => [...selection.keys.value],
+    () => {
+      if (props.open) void selection.resolve()
+    },
+  )
+  watch(
+    () => props.selectionMode,
+    () => {
+      if (props.open) void restore()
+    },
+  )
+  watch(allowedSources, (sources) => {
+    if (!sources.includes(source.value) && sources[0]) void switchSource(sources[0])
+  })
+  onScopeDispose(() => {
+    ++openGeneration
+    clearTimeout(timer)
+    selection.reset()
+  })
+
+  async function switchSource(next: PickerSource) {
+    if (next === source.value || !allowedSources.value.includes(next)) return
+    rememberFolders()
+    remembered.set(source.value, { path: path.value, trail: [...trail.value] })
+    clearTimeout(timer)
+    nav.clear()
+    source.value = next
+    query.value = ''
+    path.value = remembered.get(next)?.path ?? ''
+    trail.value = remembered.get(next)?.trail ?? []
+    await restore()
+  }
+  function selectNode(node: PickerNode, event: MouseEvent | KeyboardEvent) {
+    // The second click in a double-click only opens the row; it must not toggle twice.
+    if (event.type === 'click' && event.detail > 1) return
+    selection.select(node, {
+      ...{ metaKey: event.metaKey, ctrlKey: event.ctrlKey, shiftKey: event.shiftKey },
+      toggle: event.type === 'click' || (event instanceof KeyboardEvent && event.key === ' '),
+    })
+  }
+  async function enter(node: PickerNode) {
+    const token = openGeneration
+    if (selection.exclusion(node)) return
+    if (node.kind === 'file') {
+      if (props.selectionMode === 'single-file') {
+        selection.select(node)
+        await nextTick()
+        await selection.resolve()
+        if (token === openGeneration && props.open) confirm()
+      }
+      return
+    }
+    clearTimeout(timer)
+    query.value = ''
+    nav.enter(node)
+    await nav.load()
+  }
+  async function up(target?: string) {
+    query.value = ''
+    clearTimeout(timer)
+    nav.up(target)
+    await nav.load()
+  }
+  async function refresh() {
+    nav.invalidate()
+    await nav.load(query.value, recursive.value, true)
+    if (selection.keys.value.size) await selection.resolve()
+  }
+  function selectParent(node: PickerNode) {
+    if (!node.parentPath) return
+    const parent = nav.nodes.value.get(node.parentPath) ?? {
+      kind: 'folder' as const,
+      path: node.parentPath,
+      name: node.parentName ?? 'Containing folder',
+    }
+    nav.register([parent])
+    selection.select(parent)
+  }
+  async function chooseLocal(files: File[], _rootName?: string, relativePaths?: string[]) {
+    const token = openGeneration
+    if (!files.length || !props.open || source.value !== 'localFile') return
+    files.forEach((file, index) => {
+      if (relativePaths?.[index]) localPaths.set(toRaw(file), relativePaths[index]!)
+    })
+    localFiles.value = files
+    clearTimeout(timer)
+    nav.clear()
+    selection.reset()
+    path.value = ''
+    trail.value = []
+    query.value = ''
+    await nav.load()
+    if (token !== openGeneration || !props.open || source.value !== 'localFile') return
+    await selectLocalFiles()
+  }
+  async function selectLocalFiles() {
+    const token = openGeneration
+    const items = props.selectionMode === 'single-file' || props.selectionMode === 'multi-file'
+      ? await localAdapter.value.search('', { path: '', recursive: true })
+      : nav.entries.value
+    if (token !== openGeneration || !props.open || source.value !== 'localFile') return
+    nav.register(items)
+    const candidates = items.filter((node) => selection.selectable(node))
+    for (const node of props.selectionMode === 'single-file' || props.selectionMode === 'folder'
+      ? candidates.slice(0, 1)
+      : candidates)
+      selection.select(node, { ctrlKey: true })
+  }
+  function cancel() {
+    emit('cancel')
+    emit('update:open', false)
+  }
+  function confirm() {
+    if (!canConfirm.value) return
+    const result: PickerSelection =
+      source.value === 'localFile'
+        ? {
+            source: 'localFile',
+            files: chosen.value.files.flatMap((node) => (node.file ? [toRaw(node.file)] : [])),
+          }
+        : {
+            source: 'server',
+            folders: roots.value.filter((node) => node.kind === 'folder').map((node) => node.path),
+            files: [...chosen.value.files],
+            excluded: [...chosen.value.excluded],
+          }
+    if (result.source === 'localFile') {
+      const relativePaths = result.files.map((file) =>
+        localPaths.get(file) || file.webkitRelativePath || file.name,
+      )
+      if (relativePaths.some((path, index) =>
+        path !== (result.files[index]!.webkitRelativePath || result.files[index]!.name),
+      )) result.relativePaths = relativePaths
+    }
+    lastConfirmed = result
+    emit('select', result)
+    emit('update:open', false)
+  }
+  function keyboard(event: KeyboardEvent) {
+    if (
+      event.key !== '/' ||
+      event.target instanceof HTMLInputElement ||
+      event.target instanceof HTMLTextAreaElement
+    )
+      return
+    event.preventDefault()
+    searchArea.value?.querySelector('input')?.focus()
+  }
+
+  return {
+    previewNode,
+    sourceNames,
+    sourceIcons,
+    allowedSources,
+    source,
+    query,
+    recursive,
+    skipBlanks,
+    reviewing,
+    nav,
+    selection,
+    capability,
+    path,
+    trail,
+    loading,
+    error,
+    rows,
+    roots,
+    chosen,
+    focused,
+    resolving,
+    resolutionError,
+    searchArea,
+    confirmLabel,
+    folderCount,
+    canConfirm,
+    switchSource,
+    selectNode,
+    enter,
+    up,
+    refresh,
+    selectParent,
+    chooseLocal,
+    cancel,
+    confirm,
+    keyboard,
+  }
+}