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

package/src/composables/useListReorder.story.vue

@@ -0,0 +1,143 @@
+<script setup lang="ts">
+/** Demonstrates `useListReorder`: drag a row, or focus a handle and press Alt with the arrow keys. */
+import { ref } from 'vue'
+import { useListReorder } from './useListReorder'
+
+interface Step { id: string; name: string }
+
+const steps = ref<Step[]>([
+  { id: 's1', name: 'Thaw samples' },
+  { id: 's2', name: 'Quench metabolism' },
+  { id: 's3', name: 'Extract metabolites' },
+  { id: 's4', name: 'Dry down' },
+])
+
+const handles = new Map<string, HTMLElement>()
+
+function setHandle(id: string, el: Element | null) {
+  if (el instanceof HTMLElement) handles.set(id, el)
+  else handles.delete(id)
+}
+
+const {
+  draggingId,
+  dragOverId,
+  announcement,
+  announcerStyle,
+  onDragStart,
+  onDragOver,
+  onDragLeave,
+  onDrop,
+  onDragEnd,
+  onKeydown,
+} = useListReorder<Step>({
+  items: () => steps.value,
+  getId: (step) => step.id,
+  getLabel: (step) => step.name,
+  getElement: (id) => handles.get(id),
+  itemNoun: 'Step',
+  onReorder: ({ items }) => {
+    steps.value = items
+  },
+})
+
+function initState() {
+  return { showAnnouncement: true }
+}
+</script>
+
+<template>
+  <Story title="Composables/useListReorder">
+    <Variant title="Playground" :init-state="initState">
+      <template #default="{ state }">
+        <div style="padding: 2rem; max-width: 600px;">
+          <p class="mint-story-hint">
+            Drag a row, or focus its handle and press Alt with the up/down arrow keys.
+          </p>
+          <ul class="mint-story-list">
+            <li
+              v-for="(step, index) in steps"
+              :key="step.id"
+              class="mint-story-row"
+              :class="{
+                'mint-story-row--dragging': draggingId === step.id,
+                'mint-story-row--over': dragOverId === step.id,
+              }"
+              draggable="true"
+              @dragstart="onDragStart($event, step, index)"
+              @dragover="onDragOver($event, step, index)"
+              @dragleave="onDragLeave"
+              @drop="onDrop($event, step, index)"
+              @dragend="onDragEnd"
+            >
+              <button
+                :ref="(el) => setHandle(step.id, el as Element | null)"
+                type="button"
+                class="mint-story-handle"
+                :aria-label="`Reorder ${step.name}. Press Alt with the arrow keys to move it.`"
+                @keydown="onKeydown($event, step, index)"
+              >
+                ⠿
+              </button>
+              <span>{{ index + 1 }}. {{ step.name }}</span>
+            </li>
+          </ul>
+
+          <p v-if="state.showAnnouncement" class="mint-story-hint">
+            Live region: <em>{{ announcement || '—' }}</em>
+          </p>
+          <div role="status" aria-live="polite" :style="announcerStyle">{{ announcement }}</div>
+        </div>
+      </template>
+
+      <template #controls="{ state }">
+        <HstCheckbox v-model="state.showAnnouncement" title="Show live-region text" />
+      </template>
+    </Variant>
+  </Story>
+</template>
+
+<style scoped>
+.mint-story-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.mint-story-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--border-color);
+  border-radius: 0.5rem;
+  background: var(--bg-primary);
+  color: var(--text-primary);
+}
+
+.mint-story-row--dragging {
+  opacity: 0.5;
+}
+
+.mint-story-row--over {
+  border-color: var(--color-primary);
+}
+
+.mint-story-handle {
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--text-muted);
+  cursor: grab;
+  font-size: 1rem;
+}
+
+.mint-story-hint {
+  margin: 0 0 0.75rem;
+  color: var(--text-secondary);
+  font-size: 0.8125rem;
+}
+</style>

package/src/composables/useListReorder.ts

@@ -0,0 +1,242 @@
+import { nextTick, ref, type Ref } from 'vue'
+
+/** Inline style for a visually hidden `aria-live` region (no global utility class in the SDK). */
+export const REORDER_ANNOUNCER_STYLE = Object.freeze({
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: '0',
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  whiteSpace: 'nowrap',
+  border: '0',
+})
+
+export interface UseReorderAnnouncerReturn {
+  /** Bind to a polite live region's text content. */
+  announcement: Ref<string>
+  /** Publishes a message to the live region. */
+  announce: (message: string) => void
+  /** Bind to the live region's `style` so it stays visually hidden. */
+  announcerStyle: typeof REORDER_ANNOUNCER_STYLE
+}
+
+/**
+ * Screen-reader announcements for drag/keyboard move interactions. Bind
+ * `announcement` to a `role="status" aria-live="polite"` element styled with
+ * `announcerStyle`.
+ */
+export function useReorderAnnouncer(): UseReorderAnnouncerReturn {
+  const announcement = ref('')
+
+  function announce(message: string) {
+    // Re-announce identical consecutive messages by clearing first.
+    if (announcement.value === message) announcement.value = ''
+    void nextTick(() => {
+      announcement.value = message
+    })
+  }
+
+  return { announcement, announce, announcerStyle: REORDER_ANNOUNCER_STYLE }
+}
+
+export interface ListReorderMove<T> {
+  /** Index the item moved from, within `items()`. */
+  fromIndex: number
+  /** Index the item moved to, within `items()`. */
+  toIndex: number
+  /** The reordered array (a copy — `items()` is never mutated). */
+  items: T[]
+  /** Whether the move came from the keyboard or a pointer drag. */
+  source: 'keyboard' | 'drag'
+}
+
+export interface UseListReorderOptions<T> {
+  /** The list being reordered, in its canonical (not merely rendered) order. */
+  items: () => T[]
+  /** Stable id for an item; falls back to the render index when ids repeat. */
+  getId: (item: T, index: number) => string
+  /** Applies the move. The composable never mutates the source array. */
+  onReorder: (move: ListReorderMove<T>) => void
+  /** Human-readable name used in announcements. Defaults to the item's id. */
+  getLabel?: (item: T, index: number) => string
+  /** Blocks every reorder while it returns `true` (readonly / non-sortable lists). */
+  disabled?: () => boolean
+  /** Resolves the focusable element for an id so keyboard moves keep focus on the item. */
+  getElement?: (id: string) => HTMLElement | null | undefined
+  /** Noun used in announcements, e.g. `'Reagent'`. Default `'Item'`. */
+  itemNoun?: string
+}
+
+export interface UseListReorderReturn<T> {
+  /** Id of the item currently being dragged, or `null`. */
+  draggingId: Ref<string | null>
+  /** Id of the item the pointer is hovering as a drop target, or `null`. */
+  dragOverId: Ref<string | null>
+  isDragging: (id: string) => boolean
+  isDragOver: (id: string) => boolean
+  announcement: Ref<string>
+  announcerStyle: typeof REORDER_ANNOUNCER_STYLE
+  announce: (message: string) => void
+  /** Bind to the draggable element's `@dragstart`. */
+  onDragStart: (event: DragEvent, item: T, index: number) => void
+  /** Bind to `@dragover` — calls `preventDefault()` so the drop is accepted. */
+  onDragOver: (event: DragEvent, item: T, index: number) => void
+  /** Bind to `@dragleave`. */
+  onDragLeave: () => void
+  /** Bind to `@drop`. */
+  onDrop: (event: DragEvent, item: T, index: number) => void
+  /** Bind to `@dragend`. */
+  onDragEnd: () => void
+  /**
+   * Bind to the item's (or its drag handle's) `@keydown`: Alt+ArrowUp / Alt+ArrowLeft
+   * moves the item one position earlier, Alt+ArrowDown / Alt+ArrowRight one later.
+   */
+  onKeydown: (event: KeyboardEvent, item: T, index: number) => void
+  /** Moves an item between two indices of `items()` programmatically. */
+  move: (fromIndex: number, toIndex: number, source?: 'keyboard' | 'drag') => void
+}
+
+/** Pure helper: a copy of `items` with the entry at `from` moved to `to`. */
+export function reorderList<T>(items: T[], from: number, to: number): T[] {
+  const next = [...items]
+  const [moved] = next.splice(from, 1)
+  next.splice(to, 0, moved)
+  return next
+}
+
+/**
+ * Keyboard-accessible list reordering shared by the SDK's drag-to-reorder lists.
+ * It owns the HTML5 drag state, the drop-index maths, and an Alt+Arrow keyboard
+ * alternative that announces every move through a polite live region — so a
+ * reorder never depends on a pointer.
+ */
+export function useListReorder<T>(options: UseListReorderOptions<T>): UseListReorderReturn<T> {
+  const draggingId = ref<string | null>(null)
+  const dragOverId = ref<string | null>(null)
+  const { announcement, announce, announcerStyle } = useReorderAnnouncer()
+  const noun = options.itemNoun ?? 'Item'
+
+  function isDisabled(): boolean {
+    return options.disabled?.() === true
+  }
+
+  function idFor(item: T, index: number): string {
+    return options.getId(item, index)
+  }
+
+  /** Index within `items()`, resolved by id so filtered/sorted renders still map back. */
+  function indexOf(item: T, renderIndex: number): number {
+    const id = idFor(item, renderIndex)
+    const found = options.items().findIndex((candidate, index) => idFor(candidate, index) === id)
+    return found === -1 ? renderIndex : found
+  }
+
+  function labelFor(index: number): string {
+    const item = options.items()[index]
+    if (item === undefined) return noun
+    return options.getLabel?.(item, index) ?? idFor(item, index)
+  }
+
+  function clearDragState() {
+    draggingId.value = null
+    dragOverId.value = null
+  }
+
+  function move(fromIndex: number, toIndex: number, source: 'keyboard' | 'drag' = 'keyboard') {
+    if (isDisabled()) return
+    const items = options.items()
+    if (
+      fromIndex === toIndex ||
+      fromIndex < 0 ||
+      toIndex < 0 ||
+      fromIndex >= items.length ||
+      toIndex >= items.length
+    ) return
+
+    const movedId = idFor(items[fromIndex], fromIndex)
+    const label = labelFor(fromIndex)
+    options.onReorder({
+      fromIndex,
+      toIndex,
+      items: reorderList(items, fromIndex, toIndex),
+      source,
+    })
+    announce(`${label} moved to position ${toIndex + 1} of ${items.length}.`)
+    void nextTick(() => options.getElement?.(movedId)?.focus())
+  }
+
+  function onDragStart(event: DragEvent, item: T, index: number) {
+    if (isDisabled()) return
+    const id = idFor(item, index)
+    draggingId.value = id
+    if (event.dataTransfer) {
+      event.dataTransfer.effectAllowed = 'move'
+      event.dataTransfer.setData('text/plain', id)
+    }
+  }
+
+  function onDragOver(event: DragEvent, item: T, index: number) {
+    if (isDisabled() || draggingId.value === null) return
+    event.preventDefault()
+    if (event.dataTransfer) event.dataTransfer.dropEffect = 'move'
+    const id = idFor(item, index)
+    dragOverId.value = id === draggingId.value ? null : id
+  }
+
+  function onDragLeave() {
+    dragOverId.value = null
+  }
+
+  function onDrop(event: DragEvent, item: T, index: number) {
+    if (isDisabled() || draggingId.value === null) {
+      clearDragState()
+      return
+    }
+    event.preventDefault()
+
+    const items = options.items()
+    const fromIndex = items.findIndex((candidate, i) => idFor(candidate, i) === draggingId.value)
+    const toIndex = indexOf(item, index)
+    clearDragState()
+    if (fromIndex === -1) return
+    move(fromIndex, toIndex, 'drag')
+  }
+
+  function onDragEnd() {
+    clearDragState()
+  }
+
+  function onKeydown(event: KeyboardEvent, item: T, index: number) {
+    if (isDisabled() || !event.altKey) return
+    const direction =
+      event.key === 'ArrowUp' || event.key === 'ArrowLeft'
+        ? -1
+        : event.key === 'ArrowDown' || event.key === 'ArrowRight'
+          ? 1
+          : 0
+    if (direction === 0) return
+
+    event.preventDefault()
+    const fromIndex = indexOf(item, index)
+    move(fromIndex, fromIndex + direction, 'keyboard')
+  }
+
+  return {
+    draggingId,
+    dragOverId,
+    isDragging: (id: string) => draggingId.value === id,
+    isDragOver: (id: string) => dragOverId.value === id,
+    announcement,
+    announcerStyle,
+    announce,
+    onDragStart,
+    onDragOver,
+    onDragLeave,
+    onDrop,
+    onDragEnd,
+    onKeydown,
+    move,
+  }
+}

package/src/composables/useMenuKeyboard.ts

@@ -0,0 +1,90 @@
+import { nextTick } from 'vue'
+
+export interface UseMenuKeyboardOptions {
+  /** Returns the currently navigable items inside the open panel, in DOM order. */
+  items: () => HTMLElement[]
+  /** True while the panel is open. */
+  isOpen: () => boolean
+  /** Opens the panel. */
+  open: () => void
+  /** Closes the panel. When `returnFocus` is true, focus should return to the trigger. */
+  close: (returnFocus?: boolean) => void
+}
+
+export interface UseMenuKeyboardReturn {
+  /**
+   * Bind to the trigger's `@keydown`. ArrowDown/Enter/Space open the panel (when
+   * closed) and focus its first item; ArrowUp opens it focused on the last item.
+   */
+  handleTriggerKeydown: (event: KeyboardEvent) => void
+  /**
+   * Bind to the open panel's `@keydown`. ArrowUp/ArrowDown cycle focus with
+   * wraparound, Home/End jump to the first/last item, Escape closes and returns
+   * focus to the trigger, and Tab closes without moving focus.
+   */
+  handlePanelKeydown: (event: KeyboardEvent) => void
+}
+
+/**
+ * Shared keyboard contract for menu- and listbox-style disclosure panels (the
+ * WAI-ARIA menu button pattern). Used by ActionMenu, AppAvatarMenu and DropdownButton,
+ * each pairing it with `useDropdownState` for the disclosure state itself.
+ */
+export function useMenuKeyboard(options: UseMenuKeyboardOptions): UseMenuKeyboardReturn {
+  function focusItem(position: 'first' | 'last') {
+    void nextTick(() => {
+      const items = options.items()
+      const target = position === 'first' ? items[0] : items[items.length - 1]
+      target?.focus()
+    })
+  }
+
+  function handleTriggerKeydown(event: KeyboardEvent) {
+    if (options.isOpen()) return
+
+    if (event.key === 'ArrowDown' || event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      options.open()
+      focusItem('first')
+      return
+    }
+    if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      options.open()
+      focusItem('last')
+    }
+  }
+
+  function handlePanelKeydown(event: KeyboardEvent) {
+    const items = options.items()
+    const currentIndex = items.indexOf(document.activeElement as HTMLElement)
+
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      options.close(true)
+      return
+    }
+    if (event.key === 'Tab') {
+      options.close()
+      return
+    }
+    if (event.key === 'Home') {
+      event.preventDefault()
+      items[0]?.focus()
+      return
+    }
+    if (event.key === 'End') {
+      event.preventDefault()
+      items[items.length - 1]?.focus()
+      return
+    }
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+
+    event.preventDefault()
+    const direction = event.key === 'ArrowDown' ? 1 : -1
+    const nextIndex = (Math.max(currentIndex, 0) + direction + items.length) % items.length
+    items[nextIndex]?.focus()
+  }
+
+  return { handleTriggerKeydown, handlePanelKeydown }
+}

package/src/composables/useOptimisticMutation.ts

@@ -1,4 +1,5 @@
 import { computed, ref, shallowRef, type ComputedRef, type Ref, type ShallowRef } from 'vue'
+import { readErrorMessage } from '../utils/errors'
 
 export interface OptimisticMutationContext<TVariables, TSnapshot> {
   variables: TVariables
@@ -32,7 +33,11 @@ export interface UseOptimisticMutationReturn<TVariables, TData, TSnapshot = unkn
   reset: () => void
 }
 
-/** Run async mutations with optional optimistic local updates and rollback. */
+/**
+ * Run async mutations with optional optimistic local updates and rollback.
+ *
+ * @deprecated Unused by the MINT platform and scheduled for removal in MINT 1.3; use `useRequestSyncState()` instead.
+ */
 export function useOptimisticMutation<TVariables, TData, TSnapshot = unknown>(
   options: UseOptimisticMutationOptions<TVariables, TData, TSnapshot>,
 ): UseOptimisticMutationReturn<TVariables, TData, TSnapshot> {
@@ -90,18 +95,3 @@ export function useOptimisticMutation<TVariables, TData, TSnapshot = unknown>(
     reset,
   }
 }
-
-function readErrorMessage(value: unknown): string {
-  if (value instanceof Error && value.message) return value.message
-  if (typeof value === 'string' && value.trim()) return value
-  if (
-    typeof value === 'object'
-    && value !== null
-    && 'message' in value
-    && typeof (value as { message?: unknown }).message === 'string'
-    && (value as { message: string }).message.trim()
-  ) {
-    return (value as { message: string }).message
-  }
-  return 'Request failed.'
-}

package/src/composables/usePlatformFilePickerAdapter.ts

@@ -0,0 +1,104 @@
+import type { PickerAdapter, PickerNode, PickerRequest } from '../types/filePicker'
+import type { FileDirectoryListing, ServerMount } from '../types/fileBrowserTypes'
+import { useApi } from './useApi'
+import { getInjectedPlatformContext } from './platformContextHelpers'
+import { pickerFormat } from './filePicker/validation'
+
+/** Opaque picker identity; decode before passing a selection to a mount-scoped API. */
+export function encodePlatformPickerPath(mountId: string, path = ''): string {
+  return JSON.stringify([mountId, path])
+}
+export function decodePlatformPickerPath(path: string): { mountId: string; path: string } {
+  const decoded: unknown = JSON.parse(path)
+  if (
+    !Array.isArray(decoded) ||
+    decoded.length !== 2 ||
+    !decoded.every((item) => typeof item === 'string') ||
+    !decoded[0]
+  ) {
+    throw new Error('Invalid platform picker path.')
+  }
+  return { mountId: decoded[0], path: decoded[1] }
+}
+
+/** Adapt the authenticated MINT mount API without exposing absolute host paths. */
+export function usePlatformFilePickerAdapter(options: { apiBaseUrl?: string } = {}): PickerAdapter {
+  const api = useApi({
+    baseUrl: options.apiBaseUrl ?? getInjectedPlatformContext()?.platformApiUrl,
+  })
+  const mountLabels = new Map<string, string>()
+  async function listRoot(request?: PickerRequest): Promise<PickerNode[]> {
+    try {
+      const { mounts } = await api.get<{ mounts: ServerMount[] }>('/filesystem/mounts', {
+        signal: request?.signal,
+      })
+      return mounts.map((mount) => {
+        mountLabels.set(mount.id, mount.label)
+        return {
+          kind: 'folder',
+          path: encodePlatformPickerPath(mount.id),
+          name: mount.label,
+          parentPath: null,
+          parentName: 'Server mounts',
+          unavailableReason: mount.available === false ? 'This mount is offline.' : undefined,
+        }
+      })
+    } catch (cause) {
+      if ((cause as { response?: { status?: number } }).response?.status === 404) return []
+      throw cause
+    }
+  }
+  async function listChildren(path: string, request?: PickerRequest): Promise<PickerNode[]> {
+    const location = decodePlatformPickerPath(path)
+    const query = new URLSearchParams({ mount_id: location.mountId, path: location.path })
+    const listing = await api.get<FileDirectoryListing>(`/filesystem/browse?${query}`, {
+      signal: request?.signal,
+    })
+    if (listing.truncated)
+      throw new Error(
+        'This directory exceeds the server listing limit. Choose a smaller data directory.',
+      )
+    return (listing.entries ?? []).map(
+      (entry) =>
+        ({
+          kind: entry.kind === 'directory' ? 'folder' : 'file',
+          path: encodePlatformPickerPath(location.mountId, entry.path),
+          parentPath: path,
+          parentName: `${mountLabels.get(location.mountId) ?? location.mountId}${location.path ? ` / ${location.path}` : ''}`,
+          name: entry.name,
+          bytes: entry.size_bytes,
+          ...(entry.kind === 'directory'
+            ? { hasChildren: entry.child_count !== 0 }
+            : { format: pickerFormat(entry.name) }),
+        }) as PickerNode,
+    )
+  }
+  return {
+    listRoot,
+    listChildren,
+    async search(query, scope, request) {
+      const matches: PickerNode[] = []
+      const queue = [scope.path]
+      const visited = new Set<string>()
+      while (queue.length) {
+        request?.signal?.throwIfAborted()
+        const path = queue.shift()!
+        if (visited.has(path)) continue
+        visited.add(path)
+        if (visited.size > 500)
+          throw new Error(
+            'Search reached its folder limit. Search a smaller location or turn off Subfolders.',
+          )
+        const nodes = path ? await listChildren(path, request) : await listRoot(request)
+        for (const node of nodes) {
+          if (node.name.toLowerCase().includes(query.toLowerCase())) matches.push(node)
+          if (scope.recursive && node.kind === 'folder' && !node.unavailableReason)
+            queue.push(node.path)
+        }
+        if (matches.length > 10000)
+          throw new Error('Too many search results. Use a more specific search.')
+      }
+      return matches
+    },
+  }
+}