@morscherlab/mint-sdk 1.0.0-alpha.2

package/src/types/form-builder.ts

@@ -0,0 +1,197 @@
+import type { FieldRules } from '../composables/useForm'
+
+// ---------------------------------------------------------------------------
+// Field types
+// ---------------------------------------------------------------------------
+
+/** All supported field types that map to SDK components. */
+export type FormFieldType =
+  | 'text'
+  | 'email'
+  | 'password'
+  | 'number'
+  | 'tel'
+  | 'url'
+  | 'search'
+  | 'textarea'
+  | 'select'
+  | 'multiselect'
+  | 'checkbox'
+  | 'toggle'
+  | 'radio'
+  | 'slider'
+  | 'tags'
+  | 'date'
+  | 'time'
+  | 'datetime'
+  | 'file'
+  | 'formula'
+  | 'sequence'
+  | 'molecule'
+  | 'concentration'
+  | 'unit'
+
+// ---------------------------------------------------------------------------
+// Conditions (JSON-serializable)
+// ---------------------------------------------------------------------------
+
+export type FieldCondition =
+  | { field: string; eq: unknown }
+  | { field: string; neq: unknown }
+  | { field: string; gt: number }
+  | { field: string; lt: number }
+  | { field: string; gte: number }
+  | { field: string; lte: number }
+  | { field: string; in: unknown[] }
+  | { field: string; notIn: unknown[] }
+  | { field: string; truthy: true }
+  | { field: string; falsy: true }
+  | { field: string; contains: string }
+  | { and: FieldCondition[] }
+  | { or: FieldCondition[] }
+  | { not: FieldCondition }
+
+// ---------------------------------------------------------------------------
+// Validation (JSON-safe subset of FieldRules)
+// ---------------------------------------------------------------------------
+
+export interface FieldValidation {
+  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 as a string (converted to RegExp at runtime). */
+  pattern?: string | { value: string; message: string }
+  email?: boolean | string
+}
+
+// ---------------------------------------------------------------------------
+// Field schema
+// ---------------------------------------------------------------------------
+
+export interface FormFieldSchema {
+  name: string
+  label: string
+  type: FormFieldType
+  defaultValue?: unknown
+  placeholder?: string
+  hint?: string
+  size?: 'sm' | 'md' | 'lg'
+  disabled?: boolean
+  readonly?: boolean
+  validation?: FieldValidation
+  condition?: FieldCondition
+  /** Grid column span (1-3). Defaults to 1. */
+  colSpan?: number
+  /** Extra props passed directly to the underlying component. */
+  props?: Record<string, unknown>
+}
+
+// ---------------------------------------------------------------------------
+// Section schema
+// ---------------------------------------------------------------------------
+
+export interface FormSectionSchema {
+  id: string
+  title: string
+  description?: string
+  collapsible?: boolean
+  defaultOpen?: boolean
+  /** Number of grid columns (1-3). Defaults to 1. */
+  columns?: 1 | 2 | 3
+  fields: FormFieldSchema[]
+  condition?: FieldCondition
+}
+
+// ---------------------------------------------------------------------------
+// Wizard step schema
+// ---------------------------------------------------------------------------
+
+export interface FormStepSchema {
+  id: string
+  label: string
+  description?: string
+  icon?: string
+  optional?: boolean
+  sections: FormSectionSchema[]
+}
+
+// ---------------------------------------------------------------------------
+// Top-level form schema
+// ---------------------------------------------------------------------------
+
+export type FormSchema =
+  | {
+      sections: FormSectionSchema[]
+      steps?: never
+      submitLabel?: string
+      cancelLabel?: string
+      showCancel?: boolean
+    }
+  | {
+      sections?: never
+      steps: FormStepSchema[]
+      submitLabel?: string
+      cancelLabel?: string
+      showCancel?: boolean
+    }
+
+// ---------------------------------------------------------------------------
+// Enhancements (TS-only, NOT JSON-serializable)
+// ---------------------------------------------------------------------------
+
+export interface FieldEnhancement<T extends Record<string, unknown> = Record<string, unknown>> {
+  /** Custom validator appended to the field's rules. */
+  validate?: (value: unknown, data: T) => string | undefined | null
+  /** Dynamic visibility (overrides schema condition if both present). */
+  visible?: (data: T) => boolean
+  /** Dynamic options for select/multiselect/radio fields. */
+  options?: (data: T) => { label: string; value: unknown }[]
+  /** Dynamic extra props merged into the component. */
+  props?: (data: T) => Record<string, unknown>
+}
+
+export interface FormEnhancements<T extends Record<string, unknown> = Record<string, unknown>> {
+  /** Per-field enhancements keyed by field name. */
+  fields?: Partial<Record<keyof T, FieldEnhancement<T>>>
+  /** Called on successful submit. */
+  onSubmit?: (data: T) => Promise<void> | void
+  /** Transform data before submit (return transformed copy). */
+  transform?: (data: T) => T | Record<string, unknown>
+  /** Called when any field value changes. */
+  onFieldChange?: (field: keyof T, value: unknown, data: T) => void
+}
+
+// ---------------------------------------------------------------------------
+// useFormBuilder return type
+// ---------------------------------------------------------------------------
+
+export interface UseFormBuilderReturn<T extends Record<string, unknown>> {
+  /** Underlying useForm return. */
+  form: import('../composables/useForm').UseFormReturn<T>
+  /** Validation rules derived from schema + enhancements. */
+  rules: Partial<Record<keyof T, FieldRules>>
+  /** Whether a field is currently visible. */
+  isFieldVisible: (name: string) => boolean
+  /** Whether a section is currently visible. */
+  isSectionVisible: (id: string) => boolean
+  /** All flattened field schemas. */
+  fields: FormFieldSchema[]
+  /** Resolve final component props for a field. */
+  getResolvedFieldProps: (field: FormFieldSchema) => Record<string, unknown>
+  /** Get options for a select/radio/multiselect field. */
+  getFieldOptions: (name: string) => { label: string; value: unknown }[] | undefined
+
+  // Wizard-specific
+  currentStep: import('vue').Ref<number>
+  isCurrentStepValid: import('vue').ComputedRef<boolean>
+  goNext: () => boolean
+  goBack: () => void
+  goToStep: (index: number) => void
+
+  // Actions
+  validate: () => boolean
+  reset: (values?: Partial<T>) => void
+  submit: () => Promise<void>
+}

package/src/types/index.ts

@@ -0,0 +1,207 @@
+// Component types
+export type {
+  ContainerDirection,
+  ButtonVariant,
+  ButtonSize,
+  InputType,
+  ModalSize,
+  ModalVariant,
+  AlertType,
+  Toast,
+  TabItem,
+  SelectOption,
+  RadioOption,
+  FormFieldProps,
+  SidebarToolSection,
+  CollapsibleState,
+  TopBarVariant,
+  TopBarPage,
+  TopBarTab,
+  TopBarTabOption,
+  TopBarSettingsConfig,
+  PillNavItem,
+  PageSelectorItem,
+  PluginSwitcherPlugin,
+  PluginSwitcherInfo,
+  AccountMenuItem,
+  // Well Plate types
+  WellPlateFormat,
+  WellState,
+  WellPlateSelectionMode,
+  WellPlateSize,
+  WellShape,
+  Well,
+  HeatmapColorScale,
+  HeatmapConfig,
+  // Well Plate editing types
+  SlotPosition,
+  WellExtendedData,
+  WellEditData,
+  WellEditField,
+  WellLegendItem,
+  PlateCondition,
+  ColumnCondition,
+  RowCondition,
+  Rack,
+  // Sample Legend types
+  SampleType,
+  // Plate Map Editor types
+  PlateMap,
+  PlateMapEditorState,
+  // Experiment Timeline types
+  ProtocolStepType,
+  ProtocolStepStatus,
+  ProtocolStep,
+  // Sample management types
+  SampleGroup,
+  GroupItem,
+  FileUploaderMode,
+  // SegmentedControl types
+  SegmentedOption,
+  SegmentedControlVariant,
+  SegmentedControlSize,
+  // MultiSelect types
+  MultiSelectOption,
+  MultiSelectSize,
+  // Pill types
+  PillVariant,
+  PillColor,
+  PillSize,
+  // Calendar types
+  CalendarSelectionMode,
+  CalendarMarker,
+  CalendarDayContext,
+  // DataFrame types
+  SortDirection,
+  SortState,
+  DataFrameColumn,
+  PaginationState,
+  // LoadingSpinner types
+  SpinnerSize,
+  SpinnerVariant,
+  // Divider types
+  DividerSpacing,
+  // StatusIndicator types
+  StatusType,
+  // ProgressBar types
+  ProgressVariant,
+  ProgressSize,
+  // Avatar types
+  AvatarSize,
+  // EmptyState types
+  EmptyStateColor,
+  EmptyStateSize,
+  // Breadcrumb types
+  BreadcrumbItem,
+  // Tooltip types
+  TooltipPosition,
+  // ConfirmDialog types
+  ConfirmVariant,
+  // SettingsModal types
+  SettingsTab,
+  // ScientificNumber types
+  NumberNotation,
+  // UnitInput types
+  UnitOption,
+  // StepWizard types
+  WizardStep,
+  WizardStepState,
+  // AuditTrail types
+  AuditEntryType,
+  AuditEntry,
+  // BatchProgressList types
+  BatchItemStatus,
+  BatchItem,
+  BatchSummary,
+  // TimePicker types
+  TimePickerFormat,
+  TimeRange,
+  // Schedule types
+  ScheduleView,
+  ScheduleEventStatus,
+  ScheduleEvent,
+  ScheduleBlockedSlot,
+  ScheduleSlotContext,
+  ScheduleEventCreateContext,
+  ScheduleEventUpdateContext,
+  // Summary data types
+  SummarySectionItem,
+  SummarySection,
+  SummaryData,
+  // Resource types
+  ResourceStatus,
+  ResourceSpec,
+  // MoleculeInput types
+  MoleculeData,
+  // Experiment selector types
+  ExperimentStatus,
+  DatePreset,
+  ExperimentSortField,
+  ExperimentTypeOption,
+  ExperimentSummary,
+  ExperimentListResponse,
+  ExperimentFilters,
+  // FitPanel types
+  FitState,
+  FitResultSummary,
+  // ReagentList types
+  StorageCondition,
+  ReagentColumn,
+  Reagent,
+  // SampleHierarchyTree types
+  TreeNodeType,
+  BadgeVariant,
+  TreeNode,
+} from './components'
+
+// FormBuilder types
+export type {
+  FormFieldType,
+  FieldCondition,
+  FieldValidation,
+  FormFieldSchema,
+  FormSectionSchema,
+  FormStepSchema,
+  FormSchema,
+  FieldEnhancement,
+  FormEnhancements,
+  UseFormBuilderReturn,
+} from './form-builder'
+
+// Auto-group types
+export type {
+  OutlierAction,
+  InputMode,
+  OutlierInfo,
+  ColumnInfo,
+  MetadataRow,
+  AutoGroupResult,
+  ParsedCsvData,
+} from './auto-group'
+
+// Auth types
+export type {
+  AuthConfig,
+  UserInfo,
+  LoginResponse,
+  TokenVerifyResponse,
+  RegisterRequest,
+  UpdateProfileRequest,
+  CredentialInfo,
+} from './auth'
+
+// Platform types
+export type {
+  PluginInfo,
+  PluginNavItem,
+  PluginSettings,
+  PluginSettingField,
+  PlatformContext,
+  PlatformContextOptions,
+  PlatformEventType,
+  PlatformEvent,
+  ThemeMode,
+  ColorPalette,
+  TableDensity,
+  UserSummary,
+} from './platform'

package/src/types/platform.ts

@@ -0,0 +1,116 @@
+// Plugin information provided by the platform
+export interface PluginInfo {
+  id: string
+  name: string
+  version: string
+  description?: string
+  icon?: string
+  route_prefix: string
+  api_prefix: string
+  nav_items?: PluginNavItem[]
+  settings?: PluginSettings
+}
+
+// Plugin navigation item
+export interface PluginNavItem {
+  id: string
+  label: string
+  path: string
+  icon?: string
+  children?: PluginNavItem[]
+}
+
+// Plugin settings schema
+export interface PluginSettings {
+  [key: string]: PluginSettingField
+}
+
+export interface PluginSettingField {
+  type: 'string' | 'number' | 'boolean' | 'select' | 'multiselect'
+  label: string
+  description?: string
+  default?: unknown
+  options?: Array<{ value: string; label: string }>
+  validation?: {
+    required?: boolean
+    min?: number
+    max?: number
+    pattern?: string
+  }
+}
+
+// Minimal user representation used across experiment payloads and
+// the injected platform context.  shortname is a short attribution
+// code (initials) used e.g. in generated filenames.
+export interface UserSummary {
+  id: number
+  username: string
+  shortname?: string
+  first_name?: string
+  last_name?: string
+}
+
+// Platform context - available to plugins when running under MLD Platform
+export interface PlatformContext {
+  // Is running under the MLD Platform
+  isIntegrated: boolean
+
+  // Plugin info (only available when integrated)
+  plugin?: PluginInfo
+
+  // Platform API base URL
+  platformApiUrl?: string
+
+  // Platform origin for message validation
+  // Used to verify postMessage sources and targets
+  platformOrigin?: string
+
+  // Current user info (if authenticated)
+  user?: {
+    id: string
+    username: string
+    role: string
+    shortname?: string
+  }
+
+  // Theme preference
+  theme: 'light' | 'dark' | 'system'
+
+  // Allowed experiment types for this plugin (from admin config)
+  allowedExperimentTypes?: string[] | null
+
+  // Features enabled in platform
+  features?: {
+    experiments?: boolean
+    passkey?: boolean
+    multiUser?: boolean
+  }
+}
+
+// Configuration options for usePlatformContext
+export interface PlatformContextOptions {
+  // Allowed origins for postMessage communication
+  // If not specified, derives from platformApiUrl or uses same-origin only
+  allowedOrigins?: string[]
+
+  // Whether to allow messages from any origin (UNSAFE - only for development)
+  // Default: false
+  allowAnyOrigin?: boolean
+}
+
+// Platform event types for communication between plugin and platform
+export type PlatformEventType =
+  | 'mld:theme-changed'
+  | 'mld:user-changed'
+  | 'mld:navigate'
+  | 'mld:notification'
+
+export interface PlatformEvent<T = unknown> {
+  type: PlatformEventType
+  payload: T
+}
+
+// Settings state types
+export type ThemeMode = 'light' | 'dark' | 'system'
+export type ColorPalette = 'default' | 'colorblind' | 'viridis' | 'pastel'
+export type TableDensity = 'compact' | 'normal' | 'comfortable'

package/src/utils/color.ts

@@ -0,0 +1,96 @@
+/**
+ * Color utilities for deriving same-hue-family shades.
+ *
+ * Used by SampleSelector and other group/legend UIs where a parent color
+ * needs to seed a gradient of related shades for its children.
+ */
+
+export interface Hsl {
+  h: number // 0–360
+  s: number // 0–100
+  l: number // 0–100
+}
+
+const HEX_RE = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i
+
+function clamp(n: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, n))
+}
+
+export function hexToHsl(hex: string): Hsl {
+  const match = HEX_RE.exec(hex.trim())
+  if (!match) return { h: 0, s: 0, l: 50 }
+
+  let raw = match[1]
+  if (raw.length === 3) raw = raw.split('').map(c => c + c).join('')
+
+  const r = parseInt(raw.slice(0, 2), 16) / 255
+  const g = parseInt(raw.slice(2, 4), 16) / 255
+  const b = parseInt(raw.slice(4, 6), 16) / 255
+
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  const delta = max - min
+
+  let h = 0
+  if (delta !== 0) {
+    if (max === r) h = ((g - b) / delta) % 6
+    else if (max === g) h = (b - r) / delta + 2
+    else h = (r - g) / delta + 4
+  }
+  h = (h * 60 + 360) % 360
+
+  const l = (max + min) / 2
+  const s = delta === 0 ? 0 : delta / (1 - Math.abs(2 * l - 1))
+
+  return { h, s: s * 100, l: l * 100 }
+}
+
+export function hslToHex(h: number, s: number, l: number): string {
+  const sNorm = clamp(s, 0, 100) / 100
+  const lNorm = clamp(l, 0, 100) / 100
+  const hNorm = ((h % 360) + 360) % 360
+
+  const c = (1 - Math.abs(2 * lNorm - 1)) * sNorm
+  const x = c * (1 - Math.abs(((hNorm / 60) % 2) - 1))
+  const m = lNorm - c / 2
+
+  let r = 0, g = 0, b = 0
+  if (hNorm < 60) [r, g, b] = [c, x, 0]
+  else if (hNorm < 120) [r, g, b] = [x, c, 0]
+  else if (hNorm < 180) [r, g, b] = [0, c, x]
+  else if (hNorm < 240) [r, g, b] = [0, x, c]
+  else if (hNorm < 300) [r, g, b] = [x, 0, c]
+  else [r, g, b] = [c, 0, x]
+
+  const toHex = (n: number) => Math.round((n + m) * 255).toString(16).padStart(2, '0')
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`
+}
+
+/**
+ * Derive a same-hue-family shade of `parentHex` for child at `index` of `total`.
+ *
+ * Lightness is distributed evenly within [35, 75] so all children remain
+ * readable on light/dark backgrounds. Hue and saturation are inherited from
+ * the parent. With `total <= 1`, returns the parent unchanged.
+ *
+ * Children are ordered light → dark by index, so index 0 is the brightest
+ * sibling and index `total - 1` is the darkest.
+ */
+export function deriveShade(parentHex: string, index: number, total: number): string {
+  if (total <= 1) return parentHex
+  const { h, s, l } = hexToHsl(parentHex)
+
+  const L_MIN = 35
+  const L_MAX = 75
+  const spread = Math.min(L_MAX - L_MIN, 40)
+  const center = clamp(l, L_MIN + spread / 2, L_MAX - spread / 2)
+
+  const top = center + spread / 2
+  const bot = center - spread / 2
+  const t = total === 1 ? 0.5 : index / (total - 1)
+  const childL = top - t * (top - bot)
+
+  const childS = clamp(s, 35, 100)
+  return hslToHex(h, childS, childL)
+}