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

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

@@ -0,0 +1,326 @@
+import {
+  getCurrentInstance,
+  getCurrentScope,
+  onMounted,
+  onScopeDispose,
+  ref,
+  shallowRef,
+  type Ref,
+} from 'vue'
+import { tryUseSettingsStore } from '../stores/settings'
+
+export type EventStreamTransport = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>
+
+export interface EventStreamMessage<TData = string> {
+  event: string
+  data: TData
+  id?: string
+  retry?: number
+  raw: string
+}
+
+export interface EventStreamOptions<TData = string> {
+  transport?: EventStreamTransport
+  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
+  onOpen?: () => void
+  onMessage?: (message: EventStreamMessage<TData>) => void
+  onError?: (cause: unknown) => void
+  onClose?: (cause?: unknown) => void
+  errorLabel?: string
+}
+
+export interface UseEventStreamReturn<TData = string> {
+  isConnected: Ref<boolean>
+  isConnecting: Ref<boolean>
+  error: Ref<string | null>
+  lastMessage: Ref<EventStreamMessage<TData> | null>
+  lastEventId: Ref<string | null>
+  start: () => void
+  stop: () => void
+}
+
+interface ParsedEventStreamBlock<TData> {
+  message?: EventStreamMessage<TData>
+  id?: string
+  retry?: number
+}
+
+class EventStreamResponseError extends Error {
+  constructor(readonly response: Response, label: string) {
+    super(`${label} failed with HTTP ${response.status}`)
+    this.name = 'EventStreamResponseError'
+  }
+}
+
+/** Parse one complete SSE block without owning connection policy. */
+export function parseEventStreamBlock<TData>(
+  block: string,
+  parseJson: boolean,
+): ParsedEventStreamBlock<TData> | null {
+  let event = 'message'
+  let id: string | undefined
+  let retry: number | undefined
+  const dataLines: string[] = []
+
+  for (const line of block.split(/\r\n|\r|\n/)) {
+    if (!line || line.startsWith(':')) continue
+    const separator = line.indexOf(':')
+    const field = separator === -1 ? line : line.slice(0, separator)
+    const value = separator === -1
+      ? ''
+      : line.slice(separator + 1).replace(/^ /, '')
+
+    if (field === 'event') event = value || 'message'
+    if (field === 'data') dataLines.push(value)
+    if (field === 'id' && !value.includes('\0')) id = value
+    if (field === 'retry' && /^\d+$/.test(value)) retry = Number(value)
+  }
+
+  if (!dataLines.length && id === undefined && retry === undefined) return null
+  const data = dataLines.join('\n')
+  return {
+    message: dataLines.length
+      ? {
+          event,
+          data: (parseJson && data ? JSON.parse(data) : data) as TData,
+          id,
+          retry,
+          raw: block,
+        }
+      : undefined,
+    id,
+    retry,
+  }
+}
+
+/** Shared fetch-based SSE lifecycle with cancellation and reconnect safety. */
+export function useEventStream<TData = string>(
+  url: string | (() => string),
+  options: EventStreamOptions<TData> = {},
+): UseEventStreamReturn<TData> {
+  const isConnected = ref(false)
+  const isConnecting = ref(false)
+  const error = ref<string | null>(null)
+  const lastMessage = shallowRef<EventStreamMessage<TData> | null>(null)
+  const lastEventId = ref<string | null>(null)
+  let controller: AbortController | null = null
+  let reader: ReadableStreamDefaultReader<Uint8Array> | null = null
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  const settings = tryUseSettingsStore()
+  const reconnectEnabled = options.reconnect ?? settings?.wsAutoReconnect ?? true
+  let reconnectDelayMs = options.reconnectDelayMs ?? settings?.wsReconnectInterval ?? 2_000
+  let stopped = true
+  let generation = 0
+
+  function clearReconnectTimer(): void {
+    if (reconnectTimer === null) return
+    clearTimeout(reconnectTimer)
+    reconnectTimer = null
+  }
+
+  function ownsConnection(
+    connectionGeneration: number,
+    connectionController: AbortController,
+  ): boolean {
+    return !stopped
+      && generation === connectionGeneration
+      && controller === connectionController
+  }
+
+  function scheduleReconnect(connectionGeneration: number, cause?: unknown): void {
+    if (stopped || generation !== connectionGeneration) return
+    if (!reconnectEnabled || options.shouldReconnect?.(cause) === false) {
+      stopped = true
+      return
+    }
+    clearReconnectTimer()
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null
+      if (stopped || generation !== connectionGeneration) return
+      void connect(connectionGeneration)
+    }, reconnectDelayMs)
+  }
+
+  function dispatchBlock(
+    block: string,
+    connectionGeneration: number,
+    connectionController: AbortController,
+  ): void {
+    const parsed = parseEventStreamBlock<TData>(block, options.parseJson ?? false)
+    if (!parsed || !ownsConnection(connectionGeneration, connectionController)) return
+    if (parsed.id !== undefined) {
+      lastEventId.value = parsed.id
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+    }
+    if (parsed.retry !== undefined) reconnectDelayMs = parsed.retry
+    const message = parsed.message
+    if (!message || !ownsConnection(connectionGeneration, connectionController)) return
+    lastMessage.value = message
+    if (!ownsConnection(connectionGeneration, connectionController)) return
+    options.onMessage?.(message)
+  }
+
+  async function consume(
+    body: ReadableStream<Uint8Array>,
+    connectionGeneration: number,
+    connectionController: AbortController,
+  ): Promise<void> {
+    const connectionReader = body.getReader()
+    reader = connectionReader
+    const decoder = new TextDecoder()
+    let buffer = ''
+    try {
+      for (;;) {
+        const { value, done } = await connectionReader.read()
+        if (!ownsConnection(connectionGeneration, connectionController)) return
+        buffer += decoder.decode(value, { stream: !done })
+
+        let boundary = /(?:\r\n|\r|\n){2}/.exec(buffer)
+        while (boundary?.index !== undefined) {
+          const block = buffer.slice(0, boundary.index)
+          buffer = buffer.slice(boundary.index + boundary[0].length)
+          dispatchBlock(block, connectionGeneration, connectionController)
+          if (!ownsConnection(connectionGeneration, connectionController)) return
+          boundary = /(?:\r\n|\r|\n){2}/.exec(buffer)
+        }
+
+        if (!done) continue
+        if (buffer) dispatchBlock(buffer, connectionGeneration, connectionController)
+        return
+      }
+    } finally {
+      if (reader === connectionReader) reader = null
+      connectionReader.releaseLock()
+    }
+  }
+
+  async function connect(connectionGeneration: number): Promise<void> {
+    if (stopped || generation !== connectionGeneration) return
+    controller?.abort()
+    const connectionController = new AbortController()
+    controller = connectionController
+    isConnecting.value = true
+    if (!ownsConnection(connectionGeneration, connectionController)) return
+    error.value = null
+    if (!ownsConnection(connectionGeneration, connectionController)) return
+
+    let cause: unknown
+    try {
+      const headers = new Headers(options.headers)
+      headers.set('Accept', 'text/event-stream')
+      if (lastEventId.value && !headers.has('Last-Event-ID')) {
+        headers.set('Last-Event-ID', lastEventId.value)
+      }
+      const transport = options.transport ?? globalThis.fetch?.bind(globalThis)
+      if (!transport) throw new Error('[MINT SDK] fetch is required for event streams.')
+      const response = await transport(typeof url === 'function' ? url() : url, {
+        method: 'GET',
+        headers,
+        credentials: options.credentials ?? 'same-origin',
+        signal: connectionController.signal,
+      })
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+      if (!response.ok) {
+        throw new EventStreamResponseError(response, options.errorLabel ?? 'Event stream')
+      }
+      if (!response.body) {
+        throw new Error(`${options.errorLabel ?? 'Event stream'} response did not include a readable body.`)
+      }
+
+      isConnected.value = true
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+      isConnecting.value = false
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+      options.onOpen?.()
+      if (!ownsConnection(connectionGeneration, connectionController)) return
+      await consume(response.body, connectionGeneration, connectionController)
+    } catch (errorCause) {
+      cause = errorCause
+      if (
+        ownsConnection(connectionGeneration, connectionController)
+        && !isAbortError(errorCause)
+      ) {
+        error.value = errorCause instanceof Error
+          ? errorCause.message
+          : `${options.errorLabel ?? 'Event stream'} failed`
+        if (ownsConnection(connectionGeneration, connectionController)) {
+          options.onError?.(errorCause)
+        }
+      }
+    } finally {
+      if (ownsConnection(connectionGeneration, connectionController)) {
+        isConnecting.value = false
+        if (!ownsConnection(connectionGeneration, connectionController)) return
+        isConnected.value = false
+        if (!ownsConnection(connectionGeneration, connectionController)) return
+        controller = null
+        options.onClose?.(cause)
+        if (!stopped && generation === connectionGeneration) {
+          scheduleReconnect(connectionGeneration, cause)
+        }
+      }
+    }
+  }
+
+  function start(): void {
+    if (!stopped) return
+    stopped = false
+    clearReconnectTimer()
+    generation += 1
+    void connect(generation)
+  }
+
+  function stop(): void {
+    if (stopped) return
+    stopped = true
+    generation += 1
+    clearReconnectTimer()
+    controller?.abort()
+    controller = null
+    if (reader) void reader.cancel().catch(() => undefined)
+    reader = null
+    isConnecting.value = false
+    isConnected.value = false
+  }
+
+  const currentInstance = getCurrentInstance()
+  if (currentInstance && options.immediate !== false && typeof window === 'undefined') {
+    onMounted(start)
+  }
+  if (getCurrentScope()) onScopeDispose(stop)
+  if (options.immediate !== false && (typeof window !== 'undefined' || !currentInstance)) {
+    start()
+  }
+
+  return {
+    isConnected,
+    isConnecting,
+    error,
+    lastMessage,
+    lastEventId,
+    start,
+    stop,
+  }
+}
+
+function isAbortError(cause: unknown): boolean {
+  return cause instanceof DOMException && cause.name === 'AbortError'
+}

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 }
+}