@morscherlab/mint-sdk 1.0.0-alpha.2

package/src/composables/useExperimentSelector.ts

@@ -0,0 +1,292 @@
+import { ref, reactive, computed, watch, onScopeDispose, type Ref, type ComputedRef } from 'vue'
+import { useApi } from './useApi'
+import { datePresetToISO } from './experiment-utils'
+import type {
+  ExperimentSummary,
+  ExperimentListResponse,
+  ExperimentFilters,
+  ExperimentTypeOption,
+  ExperimentSortField,
+  PlatformContext,
+  SelectOption,
+} from '../types'
+
+function getPlatformContext(): PlatformContext | undefined {
+  if (typeof window === 'undefined') return undefined
+  return (window as unknown as { __MINT_PLATFORM__?: PlatformContext }).__MINT_PLATFORM__
+}
+
+function getPlatformApiUrl(): string | undefined {
+  return getPlatformContext()?.platformApiUrl
+}
+
+export interface UseExperimentSelectorOptions {
+  experimentType?: string
+  apiBaseUrl?: string
+  limit?: number
+  immediate?: boolean
+}
+
+export interface UseExperimentSelectorReturn {
+  experiments: Ref<ExperimentSummary[]>
+  total: Ref<number>
+  selectedExperiment: Ref<ExperimentSummary | null>
+  filters: ExperimentFilters
+  isLoading: Ref<boolean>
+  error: Ref<string | null>
+  page: Ref<number>
+  hasMore: ComputedRef<boolean>
+  // Sort
+  sortKey: Ref<string>
+  // Filter options
+  experimentTypes: Ref<ExperimentTypeOption[]>
+  projects: Ref<SelectOption<string>[]>
+  // Grouped view
+  groupedByProject: ComputedRef<[string, ExperimentSummary[]][]>
+  // Methods
+  fetch: () => Promise<void>
+  loadMore: () => Promise<void>
+  reset: () => void
+  select: (experiment: ExperimentSummary) => void
+  clear: () => void
+  fetchFilterOptions: () => Promise<void>
+}
+
+/** Fetches a paginated, filtered experiment list from the platform API for picker and selector UIs. */
+export function useExperimentSelector(
+  options: UseExperimentSelectorOptions = {},
+): UseExperimentSelectorReturn {
+  const { limit = 100, immediate = false, experimentType, apiBaseUrl } = options
+  const platformBase = apiBaseUrl ?? getPlatformApiUrl()
+  const api = useApi()
+
+  const experiments = ref<ExperimentSummary[]>([])
+  const total = ref(0)
+  const selectedExperiment = ref<ExperimentSummary | null>(null)
+  const isLoading = ref(false)
+  const error = ref<string | null>(null)
+  const page = ref(0)
+
+  // Sort: combined key like "created_at:desc"
+  const sortKey = ref<string>('created_at:desc')
+
+  // Filter option data (fetched once, cached)
+  const experimentTypes = ref<ExperimentTypeOption[]>([])
+  const projects = ref<SelectOption<string>[]>([])
+  let filterOptionsFetched = false
+
+  const hasMore = computed(() => experiments.value.length < total.value)
+
+  const filters: ExperimentFilters = reactive({
+    search: undefined,
+    status: undefined,
+    project: undefined,
+    experimentType: undefined,
+    datePreset: undefined,
+  })
+
+  function parseSortKey(): { sortBy: ExperimentSortField; sortOrder: 'asc' | 'desc' } {
+    const [field, order] = sortKey.value.split(':')
+    return {
+      sortBy: (field || 'created_at') as ExperimentSortField,
+      sortOrder: (order || 'desc') as 'asc' | 'desc',
+    }
+  }
+
+  async function fetchExperiments(): Promise<void> {
+    isLoading.value = true
+    error.value = null
+    try {
+      const params = new URLSearchParams()
+      // Priority: explicit option > platform context (single type) > filter dropdown > no filter
+      const allowedTypes = getPlatformContext()?.allowedExperimentTypes
+      const effectiveType = experimentType
+        ?? (allowedTypes?.length === 1 ? allowedTypes[0] : undefined)
+        ?? filters.experimentType
+        ?? undefined
+      if (effectiveType) params.set('experiment_type', effectiveType)
+      if (filters.status) params.set('status', filters.status)
+      if (filters.search) params.set('search', filters.search)
+      if (filters.project) params.set('project', filters.project)
+
+      // Sort params
+      const { sortBy, sortOrder } = parseSortKey()
+      params.set('sort_by', sortBy)
+      params.set('sort_order', sortOrder)
+
+      // Date preset → created_after
+      if (filters.datePreset) {
+        params.set('created_after', datePresetToISO(filters.datePreset))
+      }
+
+      params.set('limit', String(limit))
+      params.set('skip', String(page.value * limit))
+
+      const query = params.toString()
+      const base = platformBase ?? ''
+      const url = `${base}/experiments${query ? `?${query}` : ''}`
+      const data = await api.get<ExperimentListResponse>(url)
+
+      // Client-side filter for multiple allowed types (backend only supports single type)
+      let filtered = data.experiments
+      if (!effectiveType && allowedTypes && allowedTypes.length > 1) {
+        const typeSet = new Set(allowedTypes)
+        filtered = filtered.filter(e => typeSet.has(e.experiment_type))
+      }
+
+      if (page.value === 0) {
+        experiments.value = filtered
+      } else {
+        experiments.value = [...experiments.value, ...filtered]
+      }
+      // When client-side filtering is active (multiple allowedTypes), we can't
+      // use data.total since it counts all types. Check if server has more pages.
+      if (!effectiveType && allowedTypes && allowedTypes.length > 1) {
+        if (data.experiments.length < limit) {
+          // Server returned less than a full page — no more data
+          total.value = experiments.value.length
+        } else {
+          // Might be more pages on the server
+          total.value = experiments.value.length + 1
+        }
+      } else {
+        total.value = data.total
+      }
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to fetch experiments'
+      if (page.value === 0) {
+        experiments.value = []
+        total.value = 0
+      }
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  async function fetchFilterOptions(): Promise<void> {
+    if (filterOptionsFetched) return
+    filterOptionsFetched = true
+
+    const base = platformBase ?? ''
+    const [typesRes, projectsRes] = await Promise.allSettled([
+      api.get<Array<{ value: string; label: string; color?: string }>>(`${base}/experiments/experiment-types`),
+      api.get<{ projects: Array<{ id: number; name: string }>; total: number }>(`${base}/projects`),
+    ])
+
+    if (typesRes.status === 'fulfilled' && Array.isArray(typesRes.value)) {
+      experimentTypes.value = typesRes.value.map(t => ({
+        value: t.value,
+        label: t.label,
+        color: t.color,
+      }))
+    }
+
+    if (projectsRes.status === 'fulfilled' && projectsRes.value?.projects && Array.isArray(projectsRes.value.projects)) {
+      projects.value = projectsRes.value.projects.map(p => ({
+        value: p.name,
+        label: p.name,
+      }))
+    }
+  }
+
+  async function loadMore(): Promise<void> {
+    if (!hasMore.value || isLoading.value) return
+    page.value++
+    await fetchExperiments()
+  }
+
+  function reset(): void {
+    page.value = 0
+    experiments.value = []
+    total.value = 0
+    fetchExperiments()
+  }
+
+  function select(experiment: ExperimentSummary): void {
+    selectedExperiment.value = experiment
+  }
+
+  function clear(): void {
+    selectedExperiment.value = null
+    filters.search = undefined
+    filters.status = undefined
+    filters.project = undefined
+    filters.experimentType = undefined
+    filters.datePreset = undefined
+    sortKey.value = 'created_at:desc'
+    page.value = 0
+  }
+
+  // Group experiments by project (client-side)
+  const groupedByProject = computed<[string, ExperimentSummary[]][]>(() => {
+    const groups = new Map<string, ExperimentSummary[]>()
+    for (const exp of experiments.value) {
+      const key = exp.project_name ?? exp.project ?? 'No project'
+      const list = groups.get(key)
+      if (list) {
+        list.push(exp)
+      } else {
+        groups.set(key, [exp])
+      }
+    }
+    // Sort alphabetically, "No project" last
+    return [...groups.entries()].sort(([a], [b]) => {
+      if (a === 'No project') return 1
+      if (b === 'No project') return -1
+      return a.localeCompare(b)
+    })
+  })
+
+  // Debounced watch on search filter
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+  watch(
+    () => filters.search,
+    () => {
+      if (debounceTimer) clearTimeout(debounceTimer)
+      debounceTimer = setTimeout(() => {
+        page.value = 0
+        fetchExperiments()
+      }, 300)
+    },
+  )
+
+  // Immediate watch on discrete filters and sort (cancel any pending search debounce)
+  watch(
+    () => [filters.status, filters.project, filters.experimentType, filters.datePreset, sortKey.value],
+    () => {
+      if (debounceTimer) clearTimeout(debounceTimer)
+      debounceTimer = null
+      page.value = 0
+      fetchExperiments()
+    },
+  )
+
+  onScopeDispose(() => {
+    if (debounceTimer) clearTimeout(debounceTimer)
+  })
+
+  if (immediate) {
+    fetchExperiments()
+  }
+
+  return {
+    experiments,
+    total,
+    selectedExperiment,
+    filters,
+    isLoading,
+    error,
+    page,
+    hasMore,
+    sortKey,
+    experimentTypes,
+    projects,
+    groupedByProject,
+    fetch: fetchExperiments,
+    loadMore,
+    reset,
+    select,
+    clear,
+    fetchFilterOptions,
+  }
+}

package/src/composables/useForm.ts

@@ -0,0 +1,416 @@
+import { ref, reactive, computed, watch, type Ref } from 'vue'
+
+/**
+ * Validation rule function type.
+ * Returns error message string if invalid, undefined/null if valid.
+ */
+export type ValidationRule<T = unknown> = (value: T, formData: Record<string, unknown>) => string | undefined | null
+
+/**
+ * Field validation rules configuration.
+ */
+export interface FieldRules<T = unknown> {
+  required?: boolean | string
+  minLength?: number | { value: number; message: string }
+  maxLength?: number | { value: number; message: string }
+  min?: number | { value: number; message: string }
+  max?: number | { value: number; message: string }
+  pattern?: RegExp | { value: RegExp; message: string }
+  email?: boolean | string
+  custom?: ValidationRule<T> | ValidationRule<T>[]
+}
+
+/**
+ * Field validation rules configuration.
+ */
+export interface FieldState {
+  value: unknown
+  error: string | null
+  touched: boolean
+  dirty: boolean
+}
+
+/**
+ * Form state and methods.
+ */
+export interface UseFormReturn<T extends Record<string, unknown>> {
+  // Form data (reactive)
+  data: T
+
+  // Field errors
+  errors: Record<string, string | null>
+
+  // Field touched state
+  touched: Record<string, boolean>
+
+  // Field dirty state (value changed from initial)
+  dirty: Record<string, boolean>
+
+  // Overall form state
+  isValid: Ref<boolean>
+  isDirty: Ref<boolean>
+  isSubmitting: Ref<boolean>
+
+  // Methods
+  setFieldValue: <K extends keyof T>(field: K, value: T[K]) => void
+  setFieldError: (field: string, error: string | null) => void
+  setFieldTouched: (field: string, touched?: boolean) => void
+  validateField: (field: string) => boolean
+  validate: () => boolean
+  reset: (values?: Partial<T>) => void
+  handleSubmit: (onSubmit: (data: T) => Promise<void> | void) => (e?: Event) => Promise<void>
+  getFieldProps: <K extends keyof T>(field: K) => {
+    modelValue: T[K]
+    'onUpdate:modelValue': (value: T[K]) => void
+    onBlur: () => void
+    error: string | null
+  }
+}
+
+// Built-in validators
+const validators = {
+  required: (value: unknown, message = 'This field is required'): string | null => {
+    if (value === null || value === undefined || value === '') {
+      return message
+    }
+    if (Array.isArray(value) && value.length === 0) {
+      return message
+    }
+    return null
+  },
+
+  minLength: (value: unknown, min: number, message?: string): string | null => {
+    if (typeof value !== 'string') return null
+    if (value.length < min) {
+      return message || `Must be at least ${min} characters`
+    }
+    return null
+  },
+
+  maxLength: (value: unknown, max: number, message?: string): string | null => {
+    if (typeof value !== 'string') return null
+    if (value.length > max) {
+      return message || `Must be at most ${max} characters`
+    }
+    return null
+  },
+
+  min: (value: unknown, min: number, message?: string): string | null => {
+    if (typeof value !== 'number') return null
+    if (value < min) {
+      return message || `Must be at least ${min}`
+    }
+    return null
+  },
+
+  max: (value: unknown, max: number, message?: string): string | null => {
+    if (typeof value !== 'number') return null
+    if (value > max) {
+      return message || `Must be at most ${max}`
+    }
+    return null
+  },
+
+  pattern: (value: unknown, pattern: RegExp, message?: string): string | null => {
+    if (typeof value !== 'string') return null
+    if (!pattern.test(value)) {
+      return message || 'Invalid format'
+    }
+    return null
+  },
+
+  email: (value: unknown, message = 'Invalid email address'): string | null => {
+    if (typeof value !== 'string' || !value) return null
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+    if (!emailRegex.test(value)) {
+      return message
+    }
+    return null
+  },
+}
+
+/**
+ * Form state management composable with validation.
+ *
+ * @param initialValues - Initial form values
+ * @param rules - Validation rules for each field
+ *
+ * @example
+ * ```typescript
+ * const { data, errors, isValid, handleSubmit, getFieldProps } = useForm(
+ *   { email: '', password: '' },
+ *   {
+ *     email: { required: true, email: true },
+ *     password: { required: true, minLength: 8 },
+ *   }
+ * )
+ *
+ * // In template
+ * <BaseInput v-bind="getFieldProps('email')" label="Email" />
+ * <BaseInput v-bind="getFieldProps('password')" type="password" label="Password" />
+ * <BaseButton @click="handleSubmit(onSubmit)" :disabled="!isValid">Submit</BaseButton>
+ * ```
+ */
+/** Reactive form state with field-level validation, dirty tracking, and submit handling. */
+export function useForm<T extends Record<string, unknown>>(
+  initialValues: T,
+  rules: Partial<Record<keyof T, FieldRules>> = {}
+): UseFormReturn<T> {
+  // Deep copy initial values so nested objects are not shared
+  const _initialValues = structuredClone(initialValues)
+
+  // Reactive form data
+  const data = reactive(structuredClone(initialValues)) as T
+
+  // Field state - use simple Record types for better TS compatibility
+  const errors = reactive<Record<string, string | null>>(
+    Object.keys(initialValues).reduce((acc, key) => {
+      acc[key] = null
+      return acc
+    }, {} as Record<string, string | null>)
+  )
+
+  const touched = reactive<Record<string, boolean>>(
+    Object.keys(initialValues).reduce((acc, key) => {
+      acc[key] = false
+      return acc
+    }, {} as Record<string, boolean>)
+  )
+
+  const dirty = reactive<Record<string, boolean>>(
+    Object.keys(initialValues).reduce((acc, key) => {
+      acc[key] = false
+      return acc
+    }, {} as Record<string, boolean>)
+  )
+
+  const isSubmitting = ref(false)
+
+  // Watch data changes to track dirty state
+  watch(
+    () => ({ ...data }),
+    (newData) => {
+      for (const key of Object.keys(newData)) {
+        dirty[key] = newData[key as keyof T] !== _initialValues[key as keyof T]
+      }
+    },
+    { deep: true }
+  )
+
+  // Validate a single field
+  function validateField(field: string): boolean {
+    const value = data[field as keyof T]
+    const fieldRules = rules[field as keyof T]
+
+    if (!fieldRules) {
+      errors[field] = null
+      return true
+    }
+
+    // Check required
+    if (fieldRules.required) {
+      const message = typeof fieldRules.required === 'string' ? fieldRules.required : undefined
+      const error = validators.required(value, message)
+      if (error) {
+        errors[field] = error
+        return false
+      }
+    }
+
+    // Skip other validations if empty and not required
+    if (value === null || value === undefined || value === '') {
+      errors[field] = null
+      return true
+    }
+
+    // Check minLength
+    if (fieldRules.minLength !== undefined) {
+      const config = typeof fieldRules.minLength === 'number'
+        ? { value: fieldRules.minLength, message: undefined }
+        : fieldRules.minLength
+      const error = validators.minLength(value, config.value, config.message)
+      if (error) {
+        errors[field] = error
+        return false
+      }
+    }
+
+    // Check maxLength
+    if (fieldRules.maxLength !== undefined) {
+      const config = typeof fieldRules.maxLength === 'number'
+        ? { value: fieldRules.maxLength, message: undefined }
+        : fieldRules.maxLength
+      const error = validators.maxLength(value, config.value, config.message)
+      if (error) {
+        errors[field] = error
+        return false
+      }
+    }
+
+    // Check min
+    if (fieldRules.min !== undefined) {
+      const config = typeof fieldRules.min === 'number'
+        ? { value: fieldRules.min, message: undefined }
+        : fieldRules.min
+      const error = validators.min(value, config.value, config.message)
+      if (error) {
+        errors[field] = error
+        return false
+      }
+    }
+
+    // Check max
+    if (fieldRules.max !== undefined) {
+      const config = typeof fieldRules.max === 'number'
+        ? { value: fieldRules.max, message: undefined }
+        : fieldRules.max
+      const error = validators.max(value, config.value, config.message)
+      if (error) {
+        errors[field] = error
+        return false
+      }
+    }
+
+    // Check pattern
+    if (fieldRules.pattern !== undefined) {
+      const config = fieldRules.pattern instanceof RegExp
+        ? { value: fieldRules.pattern, message: undefined }
+        : fieldRules.pattern
+      const error = validators.pattern(value, config.value, config.message)
+      if (error) {
+        errors[field] = error
+        return false
+      }
+    }
+
+    // Check email
+    if (fieldRules.email) {
+      const message = typeof fieldRules.email === 'string' ? fieldRules.email : undefined
+      const error = validators.email(value, message)
+      if (error) {
+        errors[field] = error
+        return false
+      }
+    }
+
+    // Check custom validators
+    if (fieldRules.custom) {
+      const customRules = Array.isArray(fieldRules.custom) ? fieldRules.custom : [fieldRules.custom]
+      for (const rule of customRules) {
+        const error = rule(value, data as Record<string, unknown>)
+        if (error) {
+          errors[field] = error
+          return false
+        }
+      }
+    }
+
+    errors[field] = null
+    return true
+  }
+
+  // Validate all fields
+  function validate(): boolean {
+    let isAllValid = true
+    for (const field of Object.keys(data)) {
+      if (!validateField(field)) {
+        isAllValid = false
+      }
+    }
+    return isAllValid
+  }
+
+  // Computed overall validity
+  const isValid = computed(() => {
+    return Object.values(errors).every(error => error === null)
+  })
+
+  // Computed overall dirty state
+  const isDirty = computed(() => {
+    return Object.values(dirty).some(d => d)
+  })
+
+  // Set field value
+  function setFieldValue<K extends keyof T>(field: K, value: T[K]): void {
+    ;(data as Record<string, unknown>)[field as string] = value
+    if (touched[field as string]) {
+      validateField(field as string)
+    }
+  }
+
+  // Set field error
+  function setFieldError(field: string, error: string | null): void {
+    errors[field] = error
+  }
+
+  // Set field touched
+  function setFieldTouched(field: string, isTouched = true): void {
+    touched[field] = isTouched
+    if (isTouched) {
+      validateField(field)
+    }
+  }
+
+  // Reset form
+  function reset(values?: Partial<T>): void {
+    const resetValues = values ? { ..._initialValues, ...values } : _initialValues
+    for (const key of Object.keys(data)) {
+      ;(data as Record<string, unknown>)[key] = structuredClone(resetValues[key as keyof T])
+      errors[key] = null
+      touched[key] = false
+      dirty[key] = false
+    }
+  }
+
+  // Handle submit
+  function handleSubmit(onSubmit: (data: T) => Promise<void> | void) {
+    return async (e?: Event): Promise<void> => {
+      e?.preventDefault()
+
+      // Mark all fields as touched
+      for (const field of Object.keys(data)) {
+        touched[field] = true
+      }
+
+      if (!validate()) {
+        return
+      }
+
+      isSubmitting.value = true
+      try {
+        await onSubmit(data)
+      } finally {
+        isSubmitting.value = false
+      }
+    }
+  }
+
+  // Get props for a field (for v-bind)
+  function getFieldProps<K extends keyof T>(field: K) {
+    const fieldStr = field as string
+    return {
+      modelValue: data[field],
+      'onUpdate:modelValue': (value: T[K]) => setFieldValue(field, value),
+      onBlur: () => setFieldTouched(fieldStr),
+      error: touched[fieldStr] ? errors[fieldStr] : null,
+    }
+  }
+
+  return {
+    data,
+    errors,
+    touched,
+    dirty,
+    isValid,
+    isDirty,
+    isSubmitting,
+    setFieldValue,
+    setFieldError,
+    setFieldTouched,
+    validateField,
+    validate,
+    reset,
+    handleSubmit,
+    getFieldProps,
+  }
+}