@morscherlab/mint-sdk 1.0.0-beta.1 → 1.0.0-beta.3

package/src/composables/useDebouncedWatch.ts

@@ -0,0 +1,119 @@
+import {
+  onScopeDispose,
+  ref,
+  watch,
+  type Ref,
+  type WatchOptions,
+  type WatchSource,
+  type WatchStopHandle,
+} from 'vue'
+
+export type DebouncedWatchCleanup = () => void
+export type DebouncedWatchSource<T> = WatchSource<T> | WatchSource<unknown>[] | (() => T)
+export type DebouncedWatchCallback<T> = (
+  value: T,
+  oldValue: T | undefined,
+  onCleanup: (cleanup: DebouncedWatchCleanup) => void,
+) => void | Promise<void>
+
+export interface UseDebouncedWatchOptions extends WatchOptions {
+  /** Debounce interval in milliseconds. */
+  delay?: number
+}
+
+export interface UseDebouncedWatchReturn {
+  /** Whether a callback is currently scheduled. */
+  isPending: Ref<boolean>
+  /** Cancel the pending callback without stopping the watcher. */
+  cancel: () => void
+  /** Run the pending callback immediately, if one is scheduled. */
+  flush: () => void
+  /** Stop the watcher and clear pending callbacks. */
+  stop: WatchStopHandle
+}
+
+/** Watch a Vue source with debounced callback execution and explicit cancel/flush controls. */
+export function useDebouncedWatch<T>(
+  source: DebouncedWatchSource<T>,
+  callback: DebouncedWatchCallback<T>,
+  options: UseDebouncedWatchOptions = {},
+): UseDebouncedWatchReturn {
+  const { delay = 300, ...watchOptions } = options
+  const isPending = ref(false)
+
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let hasLatestValue = false
+  let latestValue: T
+  let latestOldValue: T | undefined
+  let callbackCleanup: DebouncedWatchCleanup | null = null
+  let stopped = false
+
+  function clearTimer(): void {
+    if (timer) {
+      clearTimeout(timer)
+      timer = null
+    }
+    isPending.value = false
+  }
+
+  function runCallbackCleanup(): void {
+    if (!callbackCleanup) return
+    callbackCleanup()
+    callbackCleanup = null
+  }
+
+  function cancel(): void {
+    clearTimer()
+    hasLatestValue = false
+    latestOldValue = undefined
+  }
+
+  function flush(): void {
+    if (!hasLatestValue) return
+    const value = latestValue
+    const oldValue = latestOldValue
+    cancel()
+    runCallbackCleanup()
+    void callback(value, oldValue, (cleanup) => {
+      callbackCleanup = cleanup
+    })
+  }
+
+  function schedule(value: T, oldValue: T | undefined): void {
+    cancel()
+    hasLatestValue = true
+    latestValue = value
+    latestOldValue = oldValue
+    isPending.value = true
+    timer = setTimeout(flush, delay)
+  }
+
+  const stopWatch = watch(
+    source as WatchSource<unknown> | WatchSource<unknown>[],
+    (value, oldValue, onCleanup) => {
+      schedule(value as T, oldValue as T | undefined)
+      onCleanup(() => {
+        cancel()
+        runCallbackCleanup()
+      })
+    },
+    watchOptions,
+  )
+
+  function stop(): void {
+    if (stopped) return
+    stopped = true
+    stopWatch()
+    cancel()
+    runCallbackCleanup()
+  }
+
+  onScopeDispose(stop)
+
+  return {
+    isPending,
+    cancel,
+    flush,
+    stop,
+  }
+}

package/src/composables/useDropdownState.ts

@@ -0,0 +1,83 @@
+import { ref, type Ref } from 'vue'
+import { useEventListener } from './useEventListener'
+
+export interface UseDropdownStateOptions {
+  closeOnOutsideClick?: boolean
+  closeOnEscape?: boolean
+  insideRefs?: Array<Ref<HTMLElement | null>>
+  onOpen?: () => void
+  onClose?: () => void
+}
+
+export interface UseDropdownStateReturn {
+  isOpen: Ref<boolean>
+  rootRef: Ref<HTMLElement | null>
+  open: () => void
+  close: () => void
+  toggle: () => void
+  handleClickOutside: (event: MouseEvent) => void
+  handleKeydown: (event: KeyboardEvent) => void
+}
+
+/** Shared disclosure state for dropdown-style SDK components. */
+export function useDropdownState(options: UseDropdownStateOptions = {}): UseDropdownStateReturn {
+  const isOpen = ref(false)
+  const rootRef = ref<HTMLElement | null>(null)
+  const closeOnOutsideClick = options.closeOnOutsideClick ?? true
+  const closeOnEscape = options.closeOnEscape ?? true
+
+  function open(): void {
+    if (isOpen.value) return
+    isOpen.value = true
+    options.onOpen?.()
+  }
+
+  function close(): void {
+    if (!isOpen.value) return
+    isOpen.value = false
+    options.onClose?.()
+  }
+
+  function toggle(): void {
+    if (isOpen.value) {
+      close()
+    } else {
+      open()
+    }
+  }
+
+  function handleClickOutside(event: MouseEvent): void {
+    if (!closeOnOutsideClick || !isOpen.value || !rootRef.value) return
+    const target = event.target
+    if (
+      target instanceof Node &&
+      !rootRef.value.contains(target) &&
+      !options.insideRefs?.some(ref => ref.value?.contains(target))
+    ) {
+      close()
+    }
+  }
+
+  function handleKeydown(event: KeyboardEvent): void {
+    if (closeOnEscape && event.key === 'Escape') {
+      close()
+    }
+  }
+
+  if (closeOnOutsideClick) {
+    useEventListener(() => document, 'click', handleClickOutside)
+  }
+  if (closeOnEscape) {
+    useEventListener(() => document, 'keydown', handleKeydown)
+  }
+
+  return {
+    isOpen,
+    rootRef,
+    open,
+    close,
+    toggle,
+    handleClickOutside,
+    handleKeydown,
+  }
+}

package/src/composables/useEventListener.ts

@@ -0,0 +1,111 @@
+import { isRef, onMounted, onUnmounted, watch, type Ref } from 'vue'
+
+export type EventTargetGetter<TTarget extends EventTarget = EventTarget> =
+  () => TTarget | null | undefined
+
+export type EventTargetLike<TTarget extends EventTarget = EventTarget> =
+  | TTarget
+  | Ref<TTarget | null | undefined>
+  | EventTargetGetter<TTarget>
+  | null
+  | undefined
+
+export type EventListenerEnabled = boolean | Ref<boolean>
+
+export interface UseEventListenerObjectOptions extends AddEventListenerOptions {
+  enabled?: EventListenerEnabled
+}
+
+export type UseEventListenerOptions = boolean | UseEventListenerObjectOptions
+export type EventListenerStop = () => void
+
+export type EventMapFor<TTarget extends EventTarget> =
+  TTarget extends Window
+    ? WindowEventMap
+    : TTarget extends Document
+      ? DocumentEventMap
+      : TTarget extends HTMLElement
+        ? HTMLElementEventMap
+        : Record<string, Event>
+
+export type EventFor<
+  TTarget extends EventTarget,
+  TType extends string,
+> = TType extends keyof EventMapFor<TTarget>
+  ? EventMapFor<TTarget>[TType]
+  : Event
+
+/** Bind a DOM event listener on mount, remove it on unmount, and rebind when a ref target changes. */
+export function useEventListener<
+  TTarget extends EventTarget = EventTarget,
+  TType extends string = string,
+>(
+  target: EventTargetLike<TTarget>,
+  type: TType,
+  listener: (event: EventFor<TTarget, TType>) => void,
+  options?: UseEventListenerOptions,
+): EventListenerStop {
+  let stopCurrent: EventListenerStop | undefined
+  let mounted = false
+
+  function stop(): void {
+    stopCurrent?.()
+    stopCurrent = undefined
+  }
+
+  function start(): void {
+    stop()
+    if (!mounted || !isEnabled(options)) return
+    const resolvedTarget = resolveEventTarget(target)
+    if (!resolvedTarget) return
+
+    const eventListener = listener as EventListener
+    const eventOptions = getEventOptions(options)
+    resolvedTarget.addEventListener(type, eventListener, eventOptions)
+    stopCurrent = () => {
+      resolvedTarget.removeEventListener(type, eventListener, eventOptions)
+    }
+  }
+
+  onMounted(() => {
+    mounted = true
+    start()
+  })
+
+  if (isRef(target)) {
+    watch(target, start, { flush: 'post' })
+  }
+  const enabled = getEnabledOption(options)
+  if (isRef(enabled)) {
+    watch(enabled, start, { flush: 'post' })
+  }
+
+  onUnmounted(() => {
+    mounted = false
+    stop()
+  })
+
+  return stop
+}
+
+function resolveEventTarget(target: EventTargetLike): EventTarget | null | undefined {
+  if (isRef(target)) return target.value
+  if (typeof target === 'function') return target()
+  return target
+}
+
+function getEnabledOption(options: UseEventListenerOptions | undefined): EventListenerEnabled | undefined {
+  return typeof options === 'object' ? options.enabled : undefined
+}
+
+function isEnabled(options: UseEventListenerOptions | undefined): boolean {
+  const enabled = getEnabledOption(options)
+  if (isRef(enabled)) return enabled.value
+  return enabled ?? true
+}
+
+function getEventOptions(options: UseEventListenerOptions | undefined): boolean | AddEventListenerOptions | undefined {
+  if (typeof options !== 'object') return options
+  const { enabled: _enabled, ...eventOptions } = options
+  return eventOptions
+}

package/src/composables/useExpansionSet.ts

@@ -0,0 +1,117 @@
+import { computed, ref, toValue, watch, type ComputedRef, type Ref } from 'vue'
+
+export type ExpansionSetSource<T> =
+  | T
+  | Ref<T>
+  | ComputedRef<T>
+  | (() => T)
+
+export interface UseExpansionSetOptions {
+  defaultIds?: ExpansionSetSource<readonly string[] | null | undefined>
+  allIds?: ExpansionSetSource<readonly string[] | null | undefined>
+  expandAll?: ExpansionSetSource<boolean | null | undefined>
+}
+
+export interface UseExpansionSetReturn {
+  expandedIds: Ref<Set<string>>
+  expandedList: ComputedRef<string[]>
+  isExpanded: (id: string) => boolean
+  expand: (id: string) => void
+  collapse: (id: string) => void
+  toggle: (id: string) => boolean
+  expandMany: (ids: readonly string[]) => void
+  setExpanded: (ids: readonly string[]) => void
+  collapseAll: () => void
+  reset: () => void
+}
+
+/** Shared expansion state for trees, grouped selectors, and disclosure lists. */
+export function useExpansionSet(options: UseExpansionSetOptions = {}): UseExpansionSetReturn {
+  const expandedIds = ref(new Set(normalizeIds(toValue(options.defaultIds))))
+  const expandedList = computed(() => [...expandedIds.value])
+
+  if (options.expandAll !== undefined) {
+    watch(
+      () => toValue(options.expandAll),
+      (shouldExpandAll) => {
+        if (shouldExpandAll === undefined || shouldExpandAll === null) return
+        if (shouldExpandAll) {
+          setExpanded(normalizeIds(toValue(options.allIds)))
+        } else {
+          reset()
+        }
+      },
+      { immediate: true },
+    )
+  }
+
+  if (options.allIds !== undefined) {
+    watch(
+      () => normalizeIds(toValue(options.allIds)),
+      (ids) => {
+        if (toValue(options.expandAll)) {
+          setExpanded(ids)
+        }
+      },
+    )
+  }
+
+  function isExpanded(id: string): boolean {
+    return expandedIds.value.has(id)
+  }
+
+  function expand(id: string) {
+    if (expandedIds.value.has(id)) return
+    expandedIds.value = new Set([...expandedIds.value, id])
+  }
+
+  function collapse(id: string) {
+    if (!expandedIds.value.has(id)) return
+    const next = new Set(expandedIds.value)
+    next.delete(id)
+    expandedIds.value = next
+  }
+
+  function toggle(id: string): boolean {
+    if (expandedIds.value.has(id)) {
+      collapse(id)
+      return false
+    }
+    expand(id)
+    return true
+  }
+
+  function expandMany(ids: readonly string[]) {
+    expandedIds.value = new Set([...expandedIds.value, ...normalizeIds(ids)])
+  }
+
+  function setExpanded(ids: readonly string[]) {
+    expandedIds.value = new Set(normalizeIds(ids))
+  }
+
+  function collapseAll() {
+    expandedIds.value = new Set()
+  }
+
+  function reset() {
+    setExpanded(normalizeIds(toValue(options.defaultIds)))
+  }
+
+  return {
+    expandedIds,
+    expandedList,
+    isExpanded,
+    expand,
+    collapse,
+    toggle,
+    expandMany,
+    setExpanded,
+    collapseAll,
+    reset,
+  }
+}
+
+function normalizeIds(ids: readonly string[] | null | undefined): string[] {
+  if (!ids) return []
+  return [...new Set(ids.filter(Boolean))]
+}

package/src/composables/useExperimentData.ts

@@ -1,5 +1,6 @@
 import { ref, computed, type Ref, type ComputedRef } from 'vue'
 import { useApi } from './useApi'
+import { useRequestSyncState } from './useRequestSyncState'
 import type { TreeNode, SummaryData } from '../types'
 
 export interface UseExperimentDataOptions {
@@ -8,13 +9,23 @@ export interface UseExperimentDataOptions {
 }
 
 export interface UseExperimentDataReturn {
+  /** Raw experiment data payload from `/experiments/{id}/data`, or null. */
   data: Ref<Record<string, unknown> | null>
+  /** Hierarchy tree rows normalised from `tree_data` or `treeData`. */
   treeData: ComputedRef<TreeNode[]>
+  /** Table rows normalised from `table_data` or `tableData`. */
   tableData: ComputedRef<Record<string, unknown>[]>
+  /** Summary payload normalised from `summary_data` or `summaryData`, or null. */
   summaryData: ComputedRef<SummaryData | null>
+  /** Whether experiment data is currently loading. */
   isLoading: Ref<boolean>
+  /** Error message from the last failed fetch, or null. */
   error: Ref<string | null>
+  /** Timestamp of the last successful experiment data fetch, or null. */
+  lastLoadedAt: Ref<Date | null>
+  /** Fetch experiment data for an experiment id. */
   fetch: (experimentId: number) => Promise<void>
+  /** Refetch the most recently fetched experiment id. */
   refresh: () => Promise<void>
 }
 
@@ -25,8 +36,10 @@ export function useExperimentData(
   const api = useApi({ baseUrl: options.apiBaseUrl })
 
   const data = ref<Record<string, unknown> | null>(null)
-  const isLoading = ref(false)
-  const error = ref<string | null>(null)
+  const request = useRequestSyncState('Failed to fetch experiment data')
+  const isLoading = request.loading
+  const error = request.error
+  const lastLoadedAt = request.lastLoadedAt
   let lastExperimentId: number | null = null
 
   const treeData = computed<TreeNode[]>(() => {
@@ -52,18 +65,13 @@ export function useExperimentData(
 
   async function fetchData(experimentId: number): Promise<void> {
     lastExperimentId = experimentId
-    isLoading.value = true
-    error.value = null
     try {
-      const result = await api.get<Record<string, unknown>>(
-        `/experiments/${experimentId}/data`,
+      data.value = await request.run(
+        () => api.get<Record<string, unknown>>(`/experiments/${experimentId}/data`),
+        { success: 'load', errorMessage: 'Failed to fetch experiment data' },
       )
-      data.value = result
-    } catch (e) {
-      error.value = e instanceof Error ? e.message : 'Failed to fetch experiment data'
+    } catch {
       data.value = null
-    } finally {
-      isLoading.value = false
     }
   }
 
@@ -80,6 +88,7 @@ export function useExperimentData(
     summaryData,
     isLoading,
     error,
+    lastLoadedAt,
     fetch: fetchData,
     refresh,
   }