@morscherlab/mint-sdk 1.0.0-alpha.2

package/src/composables/useAppExperiment.ts

@@ -0,0 +1,159 @@
+import {
+  ref,
+  computed,
+  readonly,
+  provide,
+  toValue,
+  onScopeDispose,
+  type Ref,
+  type ComputedRef,
+  type InjectionKey,
+} from 'vue'
+import type { ExperimentSummary, ExperimentStatus } from '../types'
+
+export interface UseAppExperimentOptions {
+  onSelect?: (experiment: ExperimentSummary) => void | Promise<void>
+  onSave?: () => string | null | Promise<string | null>
+  onDetach?: () => void
+  saveDisabled?: Ref<boolean> | ComputedRef<boolean>
+  saveDisabledMessage?: string | Ref<string | undefined> | ComputedRef<string | undefined>
+}
+
+export interface UseAppExperimentReturn {
+  set: (experiment: Pick<ExperimentSummary, 'id' | 'name' | 'status' | 'experiment_code'>) => void
+  clear: () => void
+  experimentName: Readonly<Ref<string | undefined>>
+  experimentCode: Readonly<Ref<string | undefined>>
+  experimentId: Readonly<Ref<number | null>>
+}
+
+export interface AppExperimentState {
+  experimentName: Ref<string | undefined>
+  experimentCode: Ref<string | undefined>
+  experimentStatus: Ref<ExperimentStatus | undefined>
+  experimentId: Ref<number | null>
+  showModal: Ref<boolean>
+  saveLoading: Ref<boolean>
+  saveSuccessMessage: Ref<string | undefined>
+  showSave: Ref<boolean>
+  showDetach: ComputedRef<boolean>
+  closeModal: () => void
+  saveDisabled: ComputedRef<boolean>
+  saveDisabledMessage: ComputedRef<string | undefined>
+  openModal: () => void
+  handleSelect: (experiment: ExperimentSummary) => void
+  handleSave: () => Promise<void>
+  handleDetach: () => void
+}
+
+export const APP_EXPERIMENT_KEY: InjectionKey<AppExperimentState> = Symbol('app-experiment')
+
+/** Manages the active experiment selection, save flow, and detach action for a plugin's app shell. */
+export function useAppExperiment(options: UseAppExperimentOptions = {}): UseAppExperimentReturn {
+  const experimentName = ref<string | undefined>()
+  const experimentCode = ref<string | undefined>()
+  const experimentStatus = ref<ExperimentStatus | undefined>()
+  const experimentId = ref<number | null>(null)
+  const showModal = ref(false)
+  const saveLoading = ref(false)
+  const saveSuccessMessage = ref<string | undefined>()
+
+  let successTimer: ReturnType<typeof setTimeout> | null = null
+
+  const showSave = ref(!!options.onSave)
+  const showDetach = computed(() => experimentId.value !== null)
+  const saveDisabled = computed(() => toValue(options.saveDisabled) ?? false)
+  const saveDisabledMessage = computed(() => toValue(options.saveDisabledMessage))
+
+  function set(experiment: Pick<ExperimentSummary, 'id' | 'name' | 'status' | 'experiment_code'>) {
+    experimentId.value = experiment.id
+    experimentName.value = experiment.name
+    // Fallback: if no explicit experiment_code, derive `EXP-${id}` so the
+    // topbar always has a compact identifier to show instead of the long
+    // name. Matches the `EXP-${id}` format used elsewhere (e.g., queue
+    // cards in mld-ms-planner). Callers with the real code should pass it
+    // via `experiment_code` to keep the topbar chip in sync with the
+    // formal code shown in the popover panel.
+    experimentCode.value = experiment.experiment_code ?? (
+      experiment.id != null ? `EXP-${experiment.id}` : undefined
+    )
+    experimentStatus.value = experiment.status
+  }
+
+  function clear() {
+    experimentId.value = null
+    experimentName.value = undefined
+    experimentCode.value = undefined
+    experimentStatus.value = undefined
+  }
+
+  function openModal() {
+    showModal.value = true
+  }
+
+  function closeModal() {
+    showModal.value = false
+  }
+
+  function handleSelect(experiment: ExperimentSummary) {
+    set(experiment)
+    showModal.value = false
+    options.onSelect?.(experiment)
+  }
+
+  async function handleSave() {
+    if (!options.onSave || saveLoading.value) return
+    saveLoading.value = true
+    try {
+      const message = await options.onSave()
+      if (message) {
+        saveSuccessMessage.value = message
+        if (successTimer) clearTimeout(successTimer)
+        successTimer = setTimeout(() => {
+          saveSuccessMessage.value = undefined
+          successTimer = null
+        }, 3000)
+      }
+    } finally {
+      saveLoading.value = false
+    }
+  }
+
+  function handleDetach() {
+    clear()
+    options.onDetach?.()
+  }
+
+  onScopeDispose(() => {
+    if (successTimer) clearTimeout(successTimer)
+  })
+
+  const state: AppExperimentState = {
+    experimentName,
+    experimentCode,
+    experimentStatus,
+    experimentId,
+    showModal,
+    saveLoading,
+    saveSuccessMessage,
+    showSave,
+    showDetach,
+    saveDisabled,
+    saveDisabledMessage,
+    openModal,
+    closeModal,
+    handleSelect,
+    handleSave,
+    handleDetach,
+  }
+
+  provide(APP_EXPERIMENT_KEY, state)
+
+  return {
+    set,
+    clear,
+    experimentName: readonly(experimentName),
+    experimentCode: readonly(experimentCode),
+    experimentId: readonly(experimentId),
+  }
+}

package/src/composables/useAsync.ts

@@ -0,0 +1,323 @@
+import { ref, computed, type Ref, type ComputedRef } from 'vue'
+
+/**
+ * Error type for async operations.
+ */
+export interface AsyncError {
+  message: string
+  code?: string
+  details?: Record<string, unknown>
+  originalError?: unknown
+}
+
+/**
+ * State of an async operation.
+ */
+export type AsyncState = 'idle' | 'loading' | 'success' | 'error'
+
+/**
+ * Return type for useAsync composable.
+ */
+export interface UseAsyncReturn<T> {
+  // Data
+  data: Ref<T | null>
+  error: Ref<AsyncError | null>
+
+  // State
+  state: Ref<AsyncState>
+  isIdle: ComputedRef<boolean>
+  isLoading: ComputedRef<boolean>
+  isSuccess: ComputedRef<boolean>
+  isError: ComputedRef<boolean>
+
+  // Methods
+  execute: (...args: unknown[]) => Promise<T | null>
+  reset: () => void
+  setData: (data: T | null) => void
+  setError: (error: AsyncError | null) => void
+}
+
+/**
+ * Options for useAsync.
+ */
+export interface UseAsyncOptions<T> {
+  // Initial data value
+  initialData?: T | null
+
+  // Whether to run immediately on creation
+  immediate?: boolean
+
+  // Arguments for immediate execution
+  immediateArgs?: unknown[]
+
+  // Transform error into AsyncError
+  transformError?: (error: unknown) => AsyncError
+
+  // Called on success
+  onSuccess?: (data: T) => void
+
+  // Called on error
+  onError?: (error: AsyncError) => void
+
+  // Reset data on new execution
+  resetOnExecute?: boolean
+}
+
+/**
+ * Default error transformer.
+ */
+function defaultTransformError(error: unknown): AsyncError {
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+      originalError: error,
+    }
+  }
+
+  if (typeof error === 'object' && error !== null) {
+    const errorObj = error as Record<string, unknown>
+
+    // Handle Axios-like errors
+    if ('response' in errorObj && errorObj.response) {
+      const response = errorObj.response as Record<string, unknown>
+      const data = response.data as Record<string, unknown> | undefined
+
+      return {
+        message: (data?.detail as string) || (data?.message as string) || 'Request failed',
+        code: String(response.status),
+        details: data,
+        originalError: error,
+      }
+    }
+
+    // Handle generic error objects
+    return {
+      message: (errorObj.message as string) || 'Unknown error',
+      code: errorObj.code as string | undefined,
+      details: errorObj,
+      originalError: error,
+    }
+  }
+
+  return {
+    message: String(error),
+    originalError: error,
+  }
+}
+
+/**
+ * Composable for managing async operation state.
+ *
+ * Provides standardized loading, error, and success state management
+ * for any async function.
+ *
+ * @param asyncFn - The async function to wrap
+ * @param options - Configuration options
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const { data, isLoading, error, execute } = useAsync(
+ *   async (id: string) => {
+ *     const response = await api.get(`/users/${id}`)
+ *     return response.data
+ *   }
+ * )
+ *
+ * // Execute the function
+ * await execute('user-123')
+ *
+ * // In template
+ * <div v-if="isLoading">Loading...</div>
+ * <div v-else-if="error">{{ error.message }}</div>
+ * <div v-else-if="data">{{ data.name }}</div>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With options
+ * const { data, execute } = useAsync(
+ *   fetchUser,
+ *   {
+ *     immediate: true,
+ *     immediateArgs: ['default-user'],
+ *     onSuccess: (user) => console.log('Fetched:', user.name),
+ *     onError: (error) => toast.error(error.message),
+ *   }
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Form submission
+ * const { isLoading, error, execute: submit } = useAsync(
+ *   async (formData: FormData) => {
+ *     await api.post('/submit', formData)
+ *   },
+ *   {
+ *     onSuccess: () => {
+ *       toast.success('Submitted!')
+ *       router.push('/success')
+ *     },
+ *   }
+ * )
+ *
+ * const handleSubmit = () => submit(new FormData(formRef.value))
+ * ```
+ */
+/** Wraps an async function with reactive loading, error, and success state plus optional auto-execute. */
+export function useAsync<T>(
+  asyncFn: (...args: unknown[]) => Promise<T>,
+  options: UseAsyncOptions<T> = {}
+): UseAsyncReturn<T> {
+  const {
+    initialData = null,
+    immediate = false,
+    immediateArgs = [],
+    transformError = defaultTransformError,
+    onSuccess,
+    onError,
+    resetOnExecute = false,
+  } = options
+
+  // State
+  const data = ref<T | null>(initialData) as Ref<T | null>
+  const error = ref<AsyncError | null>(null)
+  const state = ref<AsyncState>('idle')
+
+  // Computed state helpers
+  const isIdle = computed(() => state.value === 'idle')
+  const isLoading = computed(() => state.value === 'loading')
+  const isSuccess = computed(() => state.value === 'success')
+  const isError = computed(() => state.value === 'error')
+
+  // Execute the async function
+  async function execute(...args: unknown[]): Promise<T | null> {
+    state.value = 'loading'
+    error.value = null
+
+    if (resetOnExecute) {
+      data.value = null
+    }
+
+    try {
+      const result = await asyncFn(...args)
+      data.value = result
+      state.value = 'success'
+      onSuccess?.(result)
+      return result
+    } catch (e) {
+      const asyncError = transformError(e)
+      error.value = asyncError
+      state.value = 'error'
+      onError?.(asyncError)
+      return null
+    }
+  }
+
+  // Reset to initial state
+  function reset(): void {
+    data.value = initialData
+    error.value = null
+    state.value = 'idle'
+  }
+
+  // Manual data setter
+  function setData(newData: T | null): void {
+    data.value = newData
+    if (newData !== null) {
+      state.value = 'success'
+      error.value = null
+    }
+  }
+
+  // Manual error setter
+  function setError(newError: AsyncError | null): void {
+    error.value = newError
+    if (newError !== null) {
+      state.value = 'error'
+    }
+  }
+
+  // Execute immediately if requested
+  if (immediate) {
+    execute(...immediateArgs)
+  }
+
+  return {
+    data,
+    error,
+    state,
+    isIdle,
+    isLoading,
+    isSuccess,
+    isError,
+    execute,
+    reset,
+    setData,
+    setError,
+  }
+}
+
+/**
+ * Create a batch of async operations that can be executed in parallel.
+ *
+ * @example
+ * ```typescript
+ * const { results, isLoading, execute } = useAsyncBatch([
+ *   () => fetchUser(userId),
+ *   () => fetchPosts(userId),
+ *   () => fetchComments(userId),
+ * ])
+ *
+ * await execute()
+ * // results.value = [user, posts, comments]
+ * ```
+ */
+export function useAsyncBatch<T extends readonly (() => Promise<unknown>)[]>(
+  asyncFns: T
+): {
+  results: Ref<{ [K in keyof T]: Awaited<ReturnType<T[K]>> | null }>
+  errors: Ref<(AsyncError | null)[]>
+  isLoading: Ref<boolean>
+  execute: () => Promise<void>
+  reset: () => void
+} {
+  type Results = { [K in keyof T]: Awaited<ReturnType<T[K]>> | null }
+
+  const results = ref<Results>(asyncFns.map(() => null) as unknown as Results) as Ref<Results>
+  const errors = ref<(AsyncError | null)[]>(asyncFns.map(() => null))
+  const isLoading = ref(false)
+
+  async function execute(): Promise<void> {
+    isLoading.value = true
+    errors.value = asyncFns.map(() => null)
+
+    const promises = asyncFns.map(async (fn, index) => {
+      try {
+        const result = await fn()
+        ;(results.value as unknown[])[index] = result
+      } catch (e) {
+        errors.value[index] = defaultTransformError(e)
+        ;(results.value as unknown[])[index] = null
+      }
+    })
+
+    await Promise.all(promises)
+    isLoading.value = false
+  }
+
+  function reset(): void {
+    results.value = asyncFns.map(() => null) as unknown as Results
+    errors.value = asyncFns.map(() => null)
+    isLoading.value = false
+  }
+
+  return {
+    results,
+    errors,
+    isLoading,
+    execute,
+    reset,
+  }
+}