@morscherlab/mint-sdk 1.3.11 → 1.4.0-beta.10

package/src/{composables → components/internal}/useAutoGroup.ts

@@ -8,13 +8,12 @@ import type {
   InputMode,
   MergeSuggestion,
   NumericBinning,
-  OutlierAction,
   OutlierInfo,
   ParsedCsvData,
   SampleClass,
   SchemaFingerprint,
   ValueOps,
-} from '../types/auto-group'
+} from '../../types/auto-group'
 import {
   GROUPING_FIELD_ROLES,
   buildClassSchema,
@@ -33,9 +32,7 @@ import {
   type ExperimentHeader,
   type TemplateOptions,
 } from './autoGroup'
-import { unwrapExperimentDesignData } from './experimentDesignData'
-
-export { DEFAULT_COLORS } from './autoGroup'
+import { unwrapExperimentDesignData } from '../../composables/experimentDesignData'
 
 const STRUCTURED_MISSING_GROUP = 'Outlier'
 
@@ -45,24 +42,11 @@ interface LoadExperimentDataOptions {
   samples?: readonly string[]
 }
 
-let deprecationWarned = false
-let outlierDeprecationWarned = false
-function warnDeprecated(api: string) {
-  if (deprecationWarned) return
-  if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') return
-  console.warn(
-    `[useAutoGroup] ${api} is deprecated; use the new class-first API (setClassDisposition / toggleGroupBy / setValueOps).`,
-  )
-  deprecationWarned = true
-}
-
 // Re-export `parseCSV` for callers that imported it from this file.
 export { parseCSV } from './autoGroup/csv-shim'
 
 /**
- * Sample-grouping engine behind `AutoGroupModal`.
- *
- * @deprecated Scheduled for removal in MINT 1.4; no SDK replacement.
+ * Sample-grouping engine behind `AutoGroupModalInternal`. Private to `SampleSelector`.
  */
 export function useAutoGroup() {
   const inputMode = ref<InputMode>('paste')
@@ -533,40 +517,6 @@ export function useAutoGroup() {
     () => groups.value.length > 1 && groups.value.every(g => g.samples.length === 1),
   )
 
-  function setOutlierAction(_: number, __: OutlierAction) {
-    if (!outlierDeprecationWarned) {
-      if (typeof process === 'undefined' || process.env?.NODE_ENV !== 'production') {
-        console.warn(
-          `[useAutoGroup] setOutlierAction is deprecated AND inactive in the class-first redesign. ` +
-          `Use setClassDisposition('iqc' | 'eqc' | …, 'group' | 'overlay' | 'exclude') instead.`,
-        )
-        outlierDeprecationWarned = true
-      }
-    }
-  }
-
-  function setAllOutlierActions(__: OutlierAction) {
-    if (!outlierDeprecationWarned) {
-      if (typeof process === 'undefined' || process.env?.NODE_ENV !== 'production') {
-        console.warn(
-          `[useAutoGroup] setAllOutlierActions is deprecated AND inactive in the class-first redesign. ` +
-          `Use setClassDisposition('iqc' | 'eqc' | …, 'group' | 'overlay' | 'exclude') instead.`,
-        )
-        outlierDeprecationWarned = true
-      }
-    }
-  }
-
-  function toggleField(index: number) {
-    warnDeprecated('toggleField')
-    if (activeClassKey.value) toggleGroupBy(activeClassKey.value, index)
-  }
-
-  function renameField(index: number, name: string) {
-    warnDeprecated('renameField')
-    if (activeClassKey.value) setColumnName(activeClassKey.value, index, name)
-  }
-
   function loadExperimentData(
     rawData: Record<string, unknown>,
     options: LoadExperimentDataOptions = {},
@@ -610,15 +560,11 @@ export function useAutoGroup() {
     mergeColumns, loadFingerprint,
     // Actions
     parseInput, downloadTemplate, composeTemplateForTest, loadExperimentData, reset,
-    // Deprecated shims
-    setOutlierAction, setAllOutlierActions, toggleField, renameField,
   }
 }
 
 /**
  * Reads experiment `design_data` samples into the `useAutoGroup` CSV shape.
- *
- * @deprecated Scheduled for removal in MINT 1.4 together with `useAutoGroup`.
  */
 export function extractSamplesFromDesignData(
   rawData: Record<string, unknown>,

package/src/composables/componentSpecs.ts

@@ -0,0 +1,62 @@
+// `define<ComponentName>` spec builders (spec R14, 3.2). Each one is a typed
+// identity: the component applies the defaults, so `:spec` stays optional.
+import type { DataFrameSpec, PlateEditorSpec, PluginWorkspaceViewSpec, WellPlateSpec } from '../types'
+
+/** A spec whose defaulted keys are no longer optional. */
+export type ResolvedSpec<S, D> = Omit<S, keyof D> & { [K in keyof D]-?: K extends keyof S ? Exclude<S[K], undefined> : never }
+
+/** Spread `spec` over `defaults`, skipping keys set to `undefined` (as prop defaults do). */
+export function applySpecDefaults<S extends object, D extends { [K in keyof S]?: S[K] }>(
+  defaults: D,
+  spec: S | undefined,
+): ResolvedSpec<S, D> {
+  const result: Record<string, unknown> = { ...defaults }
+  for (const [key, value] of Object.entries(spec ?? {})) {
+    if (value !== undefined) result[key] = value
+  }
+  return result as ResolvedSpec<S, D>
+}
+
+/**
+ * Build the `:spec` of a PluginWorkspaceView: title, top bar, sidebar, experiment save.
+ *
+ * @example Recommended
+ * ```ts
+ * const workspace = definePluginWorkspaceView({
+ *   title: 'DRP Analysis',
+ *   topBar: { pills: pillNav, settings: () => (canConfigure.value ? settingsConfig : false) },
+ *   sidebar: { title: 'Parameters', controls: defineControlModel({ controls }) },
+ *   experiment: true,
+ *   save: { handler: saveDesign, disabled: saveBlocked, reason: saveBlockedReason },
+ * })
+ * ```
+ */
+export function definePluginWorkspaceView(spec: PluginWorkspaceViewSpec): PluginWorkspaceViewSpec {
+  return spec
+}
+
+/**
+ * Build the `:spec` of a DataFrame: columns, row key, paging, search, selection.
+ *
+ * @example Recommended
+ * ```ts
+ * const table = defineDataFrame({
+ *   columns: [{ key: 'sample', label: 'Sample', sortable: true }],
+ *   rowKey: 'id',
+ *   pagination: { pageSize: 25 },
+ * })
+ * ```
+ */
+export function defineDataFrame(spec: DataFrameSpec): DataFrameSpec {
+  return spec
+}
+
+/** Build the `:spec` of a WellPlate: format, selection mode, display options, heatmap, well editor. */
+export function defineWellPlate(spec: WellPlateSpec): WellPlateSpec {
+  return spec
+}
+
+/** Build the `:spec` of a PlateEditor: formats, slots, groups, inspector, import/export, clear, fill series. */
+export function definePlateEditor(spec: PlateEditorSpec): PlateEditorSpec {
+  return spec
+}

package/src/composables/controlComponentBindings.ts

@@ -73,6 +73,13 @@ function normalizeControlComponentBindingConfigs<TValues extends Record<string,
   }))
 }
 
+/** Map control values onto component props (`props`) and component bindings (`list`, `byId`). */
+export const controlBindings = {
+  props: controlValuesToComponentProps,
+  list: controlValuesToComponentBindings,
+  byId: controlValuesToComponentBindingsById,
+}
+
 function uniqueComponentBindingId(id: string, usedIds: Map<string, number>): string {
   const count = usedIds.get(id) ?? 0
   usedIds.set(id, count + 1)

package/src/composables/controlSchemaAdapters.ts

@@ -52,12 +52,15 @@ export function controlsToFormSchema(
 
   return {
     sections,
-    submitLabel: options.submitLabel,
-    cancelLabel: options.cancelLabel,
-    showCancel: options.showCancel,
+    ...controlFormActions(options.actions),
   }
 }
 
+function controlFormActions(actions: ControlSchemaOptions['actions']): Omit<ControlFormSchema, 'sections'> {
+  if (!actions) return {}
+  return { actions: true, ...(actions === true ? {} : actions) }
+}
+
 /** Convert controls into AppSidebar panels grouped by view and section. */
 export function controlsToSidebarPanels(
   controls: ControlSchema,
@@ -124,12 +127,11 @@ export function controlsToSettingsSchema(
 export function controlsToTopBarSettingsConfig(
   controls: ControlSchema,
   options: ControlSchemaOptions = {},
-  config: Omit<TopBarSettingsConfig, 'schema' | 'controls' | 'controlOptions'> = {},
+  config: Omit<TopBarSettingsConfig, 'spec'> = {},
 ): TopBarSettingsConfig {
   return {
     ...config,
-    controls,
-    controlOptions: options,
+    spec: { controls, controlOptions: options },
   }
 }
 
@@ -141,7 +143,7 @@ export function controlsToViewIds(
   return controlsToViewItems(controls, options).map(item => item.id)
 }
 
-/** Return AppTopBar pillNav-compatible view items for switching generated control sidebars. */
+/** Return AppTopBar `spec.pills` view items for switching generated control sidebars. */
 export function controlsToViewItems(
   controls: ControlSchema,
   options: ControlSchemaOptions = {},
@@ -170,6 +172,7 @@ export function controlsToSectionFormSchema(
     sections: schema.sections
       .filter(section => section.id === sectionId)
       .map(section => ({ ...section, title: '', description: undefined })),
+    actions: schema.actions,
     submitLabel: schema.submitLabel,
     cancelLabel: schema.cancelLabel,
     showCancel: schema.showCancel,
@@ -186,6 +189,7 @@ export function controlsToSectionFormSchemas(
   for (const section of schema.sections) {
     schemas[section.id] = {
       sections: [{ ...section, title: '', description: undefined }],
+      actions: schema.actions,
       submitLabel: schema.submitLabel,
       cancelLabel: schema.cancelLabel,
       showCancel: schema.showCancel,
@@ -193,3 +197,37 @@ export function controlsToSectionFormSchemas(
   }
   return schemas
 }
+
+const CONTROL_TARGETS = {
+  form: controlsToFormSchema,
+  sectionForm: controlsToSectionFormSchema,
+  sectionForms: controlsToSectionFormSchemas,
+  settings: controlsToSettingsSchema,
+  sidebarPanels: controlsToSidebarPanels,
+  topBarSettings: controlsToTopBarSettingsConfig,
+  viewIds: controlsToViewIds,
+  viewItems: controlsToViewItems,
+} as const
+
+/** What `controlsTo()` can build from a control schema. */
+export type ControlsTarget = keyof typeof CONTROL_TARGETS
+
+/**
+ * Build one target shape from a control schema: a FormBuilder schema (`form`,
+ * `sectionForm`, `sectionForms`), a settings modal schema (`settings`), sidebar
+ * panels (`sidebarPanels`), a top-bar settings config (`topBarSettings`) or the
+ * view list (`viewIds`, `viewItems`).
+ *
+ * @example
+ * ```ts
+ * const schema = controlsTo('form', controls)
+ * const section = controlsTo('sectionForm', controls, 'analysis')
+ * ```
+ */
+export function controlsTo<T extends ControlsTarget>(
+  target: T,
+  ...args: Parameters<(typeof CONTROL_TARGETS)[T]>
+): ReturnType<(typeof CONTROL_TARGETS)[T]> {
+  const build = CONTROL_TARGETS[target] as (...values: unknown[]) => ReturnType<(typeof CONTROL_TARGETS)[T]>
+  return build(...args)
+}

package/src/composables/controlSchemaDoseDesign.ts

@@ -10,7 +10,7 @@ import type {
   WellPlateControlPropsOptions,
   WellPlateDoseControlPropsOptions,
 } from './controlSchemaTypes'
-import type { WellConcentration } from './useDoseCalculator'
+import type { WellConcentration } from '../utils/dose'
 import {
   defineControlModel,
 } from './controlSchemaModel'
@@ -27,15 +27,19 @@ export function defineWellPlateControlProps<TValues extends Record<string, unkno
     ? undefined
     : options.onUpdateModelValue ?? updateControlValueSource(selectedWells)
 
+  const format = options.format ?? sourceKey<TValues>('plateFormat')
+  const showLegend = options.showLegend
+
   return compactComponentPropsMap<TValues>({
     modelValue: selectedWells,
     'onUpdate:modelValue': onUpdateModelValue,
-    format: options.format ?? sourceKey<TValues>('plateFormat'),
+    spec: (values: TValues) => ({
+      format: readSource(values, format),
+      showLegend: showLegend === undefined ? undefined : readSource(values, showLegend),
+    }),
     wells: options.wells ?? sourceKey<TValues>('wells'),
     disabled: options.disabled ?? sourceKey<TValues>('disabled'),
     readonly: options.readonly ?? sourceKey<TValues>('readonly'),
-    showLegend: options.showLegend,
-    showSampleTypeIndicator: options.showSampleTypeIndicator,
   })
 }
 
@@ -87,7 +91,7 @@ export function defineWellPlateDoseComponentBindings<TValues extends Record<stri
 }
 
 /**
- * Return a complete ControlWorkspaceView model for WellPlate + DoseCalculator dose design.
+ * Return a complete PluginWorkspaceView sidebar model for WellPlate + DoseCalculator dose design.
  *
  * @example Recommended
  * ```ts
@@ -168,6 +172,13 @@ function compactComponentPropsMap<TValues extends Record<string, unknown>>(
   )
 }
 
+function readSource<TValues extends Record<string, unknown>>(
+  values: TValues,
+  source: ControlComponentPropSource<TValues>,
+): unknown {
+  return typeof source === 'function' ? source(values) : values[source]
+}
+
 function sourceKey<TValues extends Record<string, unknown>>(key: string): keyof TValues & string {
   return key as keyof TValues & string
 }

package/src/composables/controlSchemaModel.ts

@@ -34,7 +34,7 @@ export function resolveControlModel(
 }
 
 /**
- * Create a complete workspace component binding from a simple controls data model for ControlWorkspaceView, generated forms, and sidebars.
+ * Create a complete control model binding for FormBuilder, SettingsModal and the PluginWorkspaceView sidebar from a simple controls data model.
  *
  * @example Recommended
  * ```ts

package/src/composables/controlSchemaTypes.ts

@@ -4,23 +4,24 @@ import type {
 } from 'vue'
 import type {
   PillNavItem,
-  SidebarBadgeTone,
   SidebarToolSection,
   SidebarToolSectionAction,
   SelectOption,
   SettingsModalSchema,
   TopBarSettingsConfig,
+  Tone,
 } from '../types'
 import type { AccessPolicy } from '../permissions'
 import type {
   FieldCondition,
   FieldValidation,
+  FormEnhancements,
   FormFieldSchema,
   FormFieldType,
   FormSchema,
   FormSectionSchema,
 } from '../types/form-builder'
-import type { WellConcentration } from './useDoseCalculator'
+import type { WellConcentration } from '../utils/dose'
 
 export type ControlOptionValue = string | number | boolean
 export type ControlOption = ControlOptionValue | SelectOption<unknown>
@@ -38,7 +39,7 @@ export interface ControlSectionConfig {
   iconColor?: string
   iconBg?: string
   badge?: string | number
-  badgeTone?: SidebarBadgeTone
+  badgeTone?: Tone
   actions?: SidebarToolSectionAction[]
   columns?: 1 | 2 | 3
   condition?: FieldCondition
@@ -107,6 +108,12 @@ export interface ControlSchemaOptions {
   sectionLabel?: string
   sections?: Record<string, ControlSectionConfig>
   columns?: 1 | 2 | 3
+  /** Submit / cancel bar of the generated form; unset or `false` hides it. */
+  actions?: boolean | ControlFormActions
+}
+
+/** Labels of the generated form's submit / cancel bar. */
+export interface ControlFormActions {
   submitLabel?: string
   cancelLabel?: string
   showCancel?: boolean
@@ -114,7 +121,9 @@ export interface ControlSchemaOptions {
 
 export interface ControlWorkspaceOptions extends ControlSchemaOptions {
   initialValues?: Record<string, unknown>
-  topBarSettings?: Omit<TopBarSettingsConfig, 'schema' | 'controls' | 'controlOptions' | 'values'>
+  /** Validators, dynamic options, a submit handler and field callbacks that JSON cannot express. */
+  enhancements?: FormEnhancements<Record<string, unknown>>
+  topBarSettings?: Omit<TopBarSettingsConfig, 'spec' | 'values'>
 }
 
 export interface ControlModelSectionConfig extends ControlSectionConfig {
@@ -138,7 +147,7 @@ export interface ControlModel extends Omit<ControlWorkspaceOptions, 'sections' |
   componentBindings?: ControlComponentBindingsConfig
   /** Alias for componentBindings in raw control models. */
   components?: ControlComponentBindingsConfig
-  /** Optional ControlWorkspaceView componentProps mapping returned with the generated controls/options. */
+  /** Optional componentProps mapping returned with the generated controls/options. */
   componentProps?: ControlComponentPropsMap
   /** Optional named componentProps mappings returned for multiple SDK components. */
   componentPropsById?: ControlComponentPropsByIdMap
@@ -152,25 +161,28 @@ export interface ControlModelBinding {
   componentPropsById?: ControlComponentPropsByIdMap
 }
 
+/** AppSidebar props (`v-bind`) for the generated sections and forms. */
 export interface ControlSidebarBinding {
-  panels: Record<string, SidebarToolSection[]>
-  forms: Record<string, ControlFormSchema>
-  viewIds: string[]
-  viewItems: PillNavItem[]
-  defaultView: string
+  spec: {
+    panels: Record<string, SidebarToolSection[]>
+    forms: Record<string, ControlFormSchema>
+  }
+  activeView: string
 }
 
+/** FormBuilder props (`v-bind`) for the generated form. */
 export interface ControlFormBinding {
-  schema: ControlFormSchema
+  spec: ControlModelBinding
 }
 
+/** SettingsModal props (`v-bind`) for the generated settings. */
 export interface ControlSettingsBinding {
-  schema: SettingsModalSchema
+  spec: SettingsModalSchema
 }
 
+/** AppTopBar props (`v-bind`) for the generated settings button. */
 export interface ControlTopBarSettingsBinding {
-  showSettings: true
-  settingsConfig: TopBarSettingsConfig
+  spec: { settings: TopBarSettingsConfig }
 }
 
 export interface ControlWorkspaceFormBinding extends ControlFormBinding {
@@ -179,9 +191,6 @@ export interface ControlWorkspaceFormBinding extends ControlFormBinding {
 }
 
 export interface ControlWorkspaceSidebarBinding extends ControlSidebarBinding {
-  activeView: string
-  modelValue: Record<string, unknown>
-  'onUpdate:modelValue': (values: Record<string, unknown>) => void
   values: Record<string, unknown>
   'onUpdate:values': (values: Record<string, unknown>) => void
 }
@@ -196,10 +205,12 @@ export interface ControlWorkspacePillNavBinding {
   onSelect: (item: PillNavItem) => void
 }
 
-export interface ControlWorkspaceTopBarBinding extends ControlWorkspaceTopBarSettingsBinding {
-  pillNav: PillNavItem[]
-  currentPillId: string
+/** AppTopBar props (`v-bind`) for the generated view pills and settings button. */
+export interface ControlWorkspaceTopBarBinding {
+  spec: { pills: PillNavItem[]; settings: TopBarSettingsConfig }
+  pill: string
   onPillSelect: (item: PillNavItem) => void
+  onSettingsValuesChange: (values: Record<string, unknown>) => void
 }
 
 export type ControlWorkspaceAppTopBarPillBinding = ControlWorkspaceTopBarBinding
@@ -257,8 +268,6 @@ export interface WellPlateControlPropsOptions<TValues extends Record<string, unk
   disabled?: ControlComponentPropSource<TValues>
   readonly?: ControlComponentPropSource<TValues>
   showLegend?: ControlComponentPropSource<TValues>
-  /** @deprecated WellPlate `showSampleTypeIndicator` is a no-op since MINT 1.3; removed in MINT 1.4. */
-  showSampleTypeIndicator?: ControlComponentPropSource<TValues>
   /** Listener for WellPlate v-model updates. Set false to keep generated props one-way. */
   onUpdateModelValue?: ((values: TValues) => (wellIds: string[]) => void) | false
 }