@morscherlab/mint-sdk 1.3.9 → 1.4.0-beta.1

package/src/components/WellPlate.story.vue

@@ -151,17 +151,19 @@ function initState() {
       <template #default="{ state }">
         <div style="padding: 2rem;">
           <WellPlate
+            v-model="selectedWells"
+            :spec="{
+              format: state.format,
+              selectionMode: state.selectionMode,
+              size: state.size,
+              wellShape: state.wellShape,
+              showLabels: state.showLabels,
+              showWellIds: state.showWellIds,
+              showLegend: state.showLegend,
+            }"
             :loading="state.loading"
             :error="state.error || null"
-            v-model="selectedWells"
-            :format="state.format"
             :wells="generateMockWells(state.format)"
-            :selection-mode="state.selectionMode"
-            :size="state.size"
-            :well-shape="state.wellShape"
-            :show-labels="state.showLabels"
-            :show-well-ids="state.showWellIds"
-            :show-legend="state.showLegend"
             :disabled="state.disabled"
             :readonly="state.readonly"
           />
@@ -207,12 +209,14 @@ function initState() {
     <Variant title="Heatmap">
       <div style="padding: 2rem;">
         <WellPlate
-          :format="96"
+          :spec="{
+            format: 96,
+            heatmap: { enabled: true, min: 0, max: 1, colorScale: 'viridis', showLegend: true },
+            selectionMode: 'none',
+            showLabels: true,
+            size: 'md',
+          }"
           :wells="heatmapWells"
-          :heatmap="{ enabled: true, min: 0, max: 1, colorScale: 'viridis', showLegend: true }"
-          selection-mode="none"
-          show-labels
-          size="md"
         />
       </div>
     </Variant>
@@ -220,15 +224,17 @@ function initState() {
     <Variant title="Heatmap QC Decorations">
       <div style="padding: 2rem;">
         <WellPlate
-          :format="96"
+          :spec="{
+            format: 96,
+            heatmap: { enabled: true, min: 0, max: 1, colorScale: 'viridis', showLegend: true },
+            wellClass: well => well.id === 'A1'
+              ? 'mint-well-plate__well--outlier'
+              : well.id === 'A2' ? 'mint-well-plate__well--conflict' : '',
+            selectionMode: 'none',
+            showLabels: true,
+            size: 'md',
+          }"
           :wells="heatmapWells"
-          :heatmap="{ enabled: true, min: 0, max: 1, colorScale: 'viridis', showLegend: true }"
-          :well-class="well => well.id === 'A1'
-            ? 'mint-well-plate__well--outlier'
-            : well.id === 'A2' ? 'mint-well-plate__well--conflict' : ''"
-          selection-mode="none"
-          show-labels
-          size="md"
         />
       </div>
     </Variant>
@@ -236,13 +242,15 @@ function initState() {
     <Variant title="6-Well Plate">
       <div style="padding: 2rem;">
         <WellPlate
-          :format="6"
+          :spec="{
+            format: 6,
+            selectionMode: 'multiple',
+            showLabels: true,
+            showLegend: true,
+            size: 'xl',
+            wellShape: 'circle',
+          }"
           :wells="mockWells6"
-          selection-mode="multiple"
-          show-labels
-          show-legend
-          size="xl"
-          well-shape="circle"
         />
       </div>
     </Variant>
@@ -251,11 +259,8 @@ function initState() {
       <div style="padding: 2rem;">
         <WellPlate
           v-model="rectSelected"
-          :format="96"
+          :spec="{ format: 96, selectionMode: 'rectangle', showLabels: true, size: 'md' }"
           :wells="mockWells96"
-          selection-mode="rectangle"
-          show-labels
-          size="md"
         />
         <p style="margin-top: 1rem; font-size: 0.875rem; color: var(--text-muted, #94a3b8);">
           Drag to select a rectangle of wells. Selected: {{ rectSelected.length }} wells
@@ -266,20 +271,22 @@ function initState() {
     <Variant title="Sample Types with Legend">
       <div style="padding: 2rem;">
         <WellPlate
-          :format="96"
+          :spec="{
+            format: 96,
+            selectionMode: 'none',
+            showLabels: true,
+            showLegend: true,
+            size: 'md',
+          }"
           :wells="mockWells96"
-          selection-mode="none"
-          show-labels
-          show-legend
-          size="md"
         />
       </div>
     </Variant>
 
     <Variant title="Marker Glyphs with IDs and Labels">
       <div style="padding: 2rem; display: flex; gap: 2rem;">
-        <WellPlate :format="6" :wells="markerWells" selection-mode="none" show-well-ids size="lg" />
-        <WellPlate :format="6" :wells="markerWells" selection-mode="none" show-well-labels size="lg" />
+        <WellPlate :spec="{ format: 6, selectionMode: 'none', showWellIds: true, size: 'lg' }" :wells="markerWells" />
+        <WellPlate :spec="{ format: 6, selectionMode: 'none', showWellLabels: true, size: 'lg' }" :wells="markerWells" />
       </div>
     </Variant>
 
@@ -289,14 +296,16 @@ function initState() {
           Column drugs (Cisplatin, Doxorubicin) and row drugs (Paclitaxel, Gemcitabine) with concentration gradients
         </h3>
         <WellPlate
-          :format="96"
+          :spec="{
+            format: 96,
+            columnConditions: doseColumnConditions,
+            rowConditions: doseRowConditions,
+            selectionMode: 'none',
+            showLabels: true,
+            showLegend: true,
+            size: 'md',
+          }"
           :wells="doseWells"
-          :column-conditions="doseColumnConditions"
-          :row-conditions="doseRowConditions"
-          selection-mode="none"
-          show-labels
-          show-legend
-          size="md"
         />
       </div>
     </Variant>
@@ -304,12 +313,14 @@ function initState() {
     <Variant title="Column Conditions Only">
       <div style="padding: 2rem;">
         <WellPlate
-          :format="96"
+          :spec="{
+            format: 96,
+            columnConditions: doseColumnConditions,
+            selectionMode: 'multiple',
+            showLabels: true,
+            size: 'md',
+          }"
           :wells="doseWells"
-          :column-conditions="doseColumnConditions"
-          selection-mode="multiple"
-          show-labels
-          size="md"
         />
       </div>
     </Variant>

package/src/components/WellPlate.vue

@@ -1,7 +1,8 @@
 <script setup lang="ts">
 /** Interactive 96/384-well plate grid with drag-to-select, heatmap overlays, per-well editing, and sample-color mapping. */
 import { computed } from 'vue'
-import type { WellPlateFormat, WellPlateSelectionMode, WellPlateSize, Well, HeatmapConfig, WellShape, WellEditField, WellEditData, WellLegendItem, ColumnCondition, RowCondition, WellSampleDropData, WellSampleDropParser, WellClassResolver, WellClassValue, WellStyleResolver } from '../types'
+import type { Well, WellEditField, WellEditData, WellSampleDropData, WellClassValue, WellPlateSpec } from '../types'
+import { applySpecDefaults } from '../composables/componentSpecs'
 import { useEventListener } from '../composables/useEventListener'
 import WellEditPopupInternal from './internal/WellEditPopupInternal.vue'
 import {
@@ -26,7 +27,6 @@ import {
 import { useWellPlateInteraction } from './WellPlate.interaction'
 import {
   sampleTint,
-  warnSampleTypeIndicatorDeprecated,
   wellBadge,
   wellClasses,
   wellLabel,
@@ -36,35 +36,14 @@ import { DEFAULT_WELL_LEGEND_ITEMS } from './WellPlate.legend'
 import DataStateInternal from './internal/DataStateInternal.vue'
 
 interface Props {
+  /** Structure built with defineWellPlate(). Optional: every option has a default. */
+  spec?: WellPlateSpec
+  /** Selected well ids. Bind with `v-model`. */
   modelValue?: string[]
-  format?: WellPlateFormat
+  /** Well data keyed by well id. */
   wells?: Record<string, Partial<Well>>
-  selectionMode?: WellPlateSelectionMode
-  showLabels?: boolean
-  showWellIds?: boolean
-  /**
-   * @deprecated No-op since MINT 1.3; removed in MINT 1.4. Wells show the 3a
-   * sample-type marker (shape per type, `Q` / `i` glyphs for QC / iQC) regardless.
-   */
-  showSampleTypeIndicator?: boolean
-  heatmap?: HeatmapConfig
-  sampleColors?: Record<string, string>
-  zoom?: number
   disabled?: boolean
   readonly?: boolean
-  size?: WellPlateSize
-  wellShape?: WellShape
-  showWellLabels?: boolean
-  showBadges?: boolean
-  editable?: boolean
-  editFields?: WellEditField[]
-  defaultInjectionVolume?: number
-  showLegend?: boolean
-  legendItems?: WellLegendItem[]
-  columnConditions?: ColumnCondition[]
-  rowConditions?: RowCondition[]
-  allowSampleDrop?: boolean
-  sampleDropParser?: WellSampleDropParser
   /** Replace the plate grid with a loading placeholder. */
   loading?: boolean
   /**
@@ -77,42 +56,37 @@ interface Props {
    * state only replaces the grid when this message is supplied and no wells
    * carry data.
    */
-  emptyMessage?: string
-  /** Add semantic classes to individual wells without overloading sample data. */
-  wellClass?: WellClassResolver
-  /** Add or override individual well styles after heatmap/sample styling. */
-  wellStyle?: WellStyleResolver
+  emptyText?: string
 }
 
 const props = withDefaults(defineProps<Props>(), {
+  spec: () => ({}),
   modelValue: () => [],
-  format: 96,
   wells: () => ({}),
+  disabled: false,
+  readonly: false,
+})
+
+const config = computed(() => applySpecDefaults({
+  format: 96,
   selectionMode: 'multiple',
   showLabels: true,
   showWellIds: false,
-  showSampleTypeIndicator: false,
-  heatmap: () => ({ enabled: false }),
-  sampleColors: () => ({}),
+  heatmap: { enabled: false },
+  sampleColors: {},
   zoom: 1,
-  disabled: false,
-  readonly: false,
   size: 'md',
   wellShape: 'rounded',
   showWellLabels: false,
   showBadges: false,
   editable: false,
-  editFields: () => ['label', 'sampleType', 'injectionVolume', 'injectionCount', 'customMethod'],
+  editFields: ['label', 'sampleType', 'injectionVolume', 'injectionCount', 'customMethod'],
   defaultInjectionVolume: 5,
   showLegend: false,
-  legendItems: undefined,
-  columnConditions: () => [],
-  rowConditions: () => [],
+  columnConditions: [],
+  rowConditions: [],
   allowSampleDrop: false,
-  sampleDropParser: undefined,
-})
-
-if (props.showSampleTypeIndicator) warnSampleTypeIndicatorDeprecated()
+}, props.spec))
 
 const emit = defineEmits<{
   'update:modelValue': [wellIds: string[]]
@@ -147,7 +121,7 @@ defineSlots<{
   empty?: () => unknown
 }>()
 
-const plateConfig = computed(() => PLATE_CONFIGS[props.format])
+const plateConfig = computed(() => PLATE_CONFIGS[config.value.format])
 
 const rowLabels = computed(() => createPlateRowLabels(plateConfig.value))
 
@@ -155,19 +129,19 @@ const colLabels = computed(() => createPlateColumnLabels(plateConfig.value))
 
 const wellGrid = computed(() => createWellGrid(plateConfig.value, rowLabels.value, props.wells))
 
-const sizeConfig = computed(() => WELL_PLATE_SIZE_CONFIGS[props.size])
+const sizeConfig = computed(() => WELL_PLATE_SIZE_CONFIGS[config.value.size])
 
-const isFillMode = computed(() => props.size === 'fill')
+const isFillMode = computed(() => config.value.size === 'fill')
 
-const activeLegendItems = computed(() => props.legendItems ?? DEFAULT_WELL_LEGEND_ITEMS)
+const activeLegendItems = computed(() => config.value.legendItems ?? DEFAULT_WELL_LEGEND_ITEMS)
 
 // --- Condition header helpers ---
 
-const hasColumnConditions = computed(() => props.columnConditions.length > 0)
-const hasRowConditions = computed(() => props.rowConditions.length > 0)
+const hasColumnConditions = computed(() => config.value.columnConditions.length > 0)
+const hasRowConditions = computed(() => config.value.rowConditions.length > 0)
 
-const colConditionMap = computed(() => createColumnConditionMap(props.columnConditions))
-const rowConditionMap = computed(() => createRowConditionMap(props.rowConditions))
+const colConditionMap = computed(() => createColumnConditionMap(config.value.columnConditions))
+const rowConditionMap = computed(() => createRowConditionMap(config.value.rowConditions))
 const colConditionSpans = computed(() => createColumnConditionSpans(colLabels.value, colConditionMap.value))
 const rowConditionSpans = computed(() => createRowConditionSpans(rowLabels.value, rowConditionMap.value))
 const rowConditionSpanByRow = computed(() => createRowConditionSpanByRow(rowConditionSpans.value))
@@ -200,12 +174,12 @@ const {
   moveAnnouncerStyle,
 } = useWellPlateInteraction({
   modelValue: () => props.modelValue,
-  selectionMode: () => props.selectionMode,
+  selectionMode: () => config.value.selectionMode,
   disabled: () => props.disabled,
   readonly: () => props.readonly,
-  editable: () => props.editable,
-  allowSampleDrop: () => props.allowSampleDrop,
-  sampleDropParser: () => props.sampleDropParser,
+  editable: () => config.value.editable,
+  allowSampleDrop: () => config.value.allowSampleDrop,
+  sampleDropParser: () => config.value.sampleDropParser,
   rowLabels: () => rowLabels.value,
   wellGrid: () => wellGrid.value,
   emitSelected: (wellIds) => {
@@ -223,8 +197,8 @@ const {
 
 function getWellClasses(well: Well): WellClassValue[] {
   const base = wellClasses(well, {
-    wellShape: props.wellShape,
-    selectionMode: props.selectionMode,
+    wellShape: config.value.wellShape,
+    selectionMode: config.value.selectionMode,
     selected: isSelected(well.id),
     dragOver: dragSelectedWells.value.has(well.id),
     hovered: hoveredWell.value === well.id,
@@ -233,27 +207,27 @@ function getWellClasses(well: Well): WellClassValue[] {
     dragSource: dragSourceWell.value === well.id,
     dragTarget: dragTargetWell.value === well.id,
   })
-  const custom = props.wellClass?.(well)
+  const custom = config.value.wellClass?.(well)
   return custom ? [base, custom] : [base]
 }
 
 function getWellStyle(well: Well): Record<string, string | number | undefined> {
   return {
     ...wellStyle(well, {
-      heatmap: props.heatmap,
-      sampleColors: props.sampleColors,
+      heatmap: config.value.heatmap,
+      sampleColors: config.value.sampleColors,
     }),
-    ...props.wellStyle?.(well),
+    ...config.value.wellStyle?.(well),
   }
 }
 
 function getWellLabel(well: Well): string | undefined {
-  return wellLabel(well, props.showWellLabels)
+  return wellLabel(well, config.value.showWellLabels)
 }
 
 // A group is otherwise shown by color alone; name it from the legend.
 function getWellGroupName(well: Well): string | undefined {
-  return well.group && (props.legendItems?.find(item => item.type === well.group)?.label ?? well.group)
+  return well.group && (config.value.legendItems?.find(item => item.type === well.group)?.label ?? well.group)
 }
 
 // Names the sample even when the cell is too small to draw it.
@@ -264,21 +238,21 @@ function getWellAriaLabel(well: Well): string {
 }
 
 function getWellBadge(well: Well): { text: string; color: string } | null {
-  return wellBadge(well, props.showBadges)
+  return wellBadge(well, config.value.showBadges)
 }
 
 useEventListener(() => document, 'mouseup', handleMouseUp)
 
 const containerStyle = computed(() =>
   isFillMode.value ? {} : {
-    transform: `scale(${props.zoom})`,
+    transform: `scale(${config.value.zoom})`,
     transformOrigin: 'top left',
   }
 )
 
-/** Empty state is opt-in: it needs an `emptyMessage` and a plate with no well data. */
+/** Empty state is opt-in: it needs an `emptyText` and a plate with no well data. */
 const showEmptyState = computed(() =>
-  Boolean(props.emptyMessage) && Object.keys(props.wells).length === 0,
+  Boolean(props.emptyText) && Object.keys(props.wells).length === 0,
 )
 
 const tableStyle = computed(() => ({
@@ -308,7 +282,7 @@ const tableStyle = computed(() => ({
 
     <div v-else-if="showEmptyState" class="mint-well-plate__state">
       <slot name="empty">
-        <DataStateInternal state="empty" :title="emptyMessage" />
+        <DataStateInternal state="empty" :title="emptyText" />
       </slot>
     </div>
 
@@ -317,7 +291,7 @@ const tableStyle = computed(() => ({
         <table
           class="mint-well-plate__table"
           role="grid"
-          :aria-label="`${props.format}-well plate`"
+          :aria-label="`${config.format}-well plate`"
           :style="tableStyle"
         >
         <!-- Column condition label row (drug name + unit) -->
@@ -345,7 +319,7 @@ const tableStyle = computed(() => ({
           </tr>
         </thead>
         <!-- Column headers (with concentration overlay when conditions present) -->
-        <thead v-if="props.showLabels">
+        <thead v-if="config.showLabels">
           <tr>
             <th :style="{ width: sizeConfig.headerWidth, height: sizeConfig.headerHeight }"></th>
             <!-- Spacer for row condition column in column header row -->
@@ -399,7 +373,7 @@ const tableStyle = computed(() => ({
             </template>
             <!-- Row header (with concentration overlay when conditions present) -->
             <td
-              v-if="props.showLabels"
+              v-if="config.showLabels"
               class="mint-well-plate__row-header"
               :style="{
                 width: sizeConfig.headerWidth,
@@ -433,7 +407,7 @@ const tableStyle = computed(() => ({
                 :aria-label="getWellAriaLabel(well)"
                 :aria-selected="isSelected(well.id)"
                 :aria-disabled="props.disabled || well.state === 'disabled'"
-                :draggable="props.selectionMode === 'drag' && !!well.sampleType"
+                :draggable="config.selectionMode === 'drag' && !!well.sampleType"
                 :class="getWellClasses(well)"
                 :style="{
                   width: isFillMode ? '100%' : sizeConfig.cellWidth,
@@ -470,7 +444,7 @@ const tableStyle = computed(() => ({
                 </span>
                 <!-- Well ID -->
                 <span
-                  v-else-if="props.showWellIds"
+                  v-else-if="config.showWellIds"
                   class="mint-well-plate__well-id"
                 >
                   {{ well.id }}
@@ -493,23 +467,23 @@ const tableStyle = computed(() => ({
 
         <!-- Heatmap legend (inside content wrapper to match table width) -->
         <div
-          v-if="props.heatmap?.enabled && props.heatmap.showLegend"
+          v-if="config.heatmap?.enabled && config.heatmap.showLegend"
           class="mint-well-plate__legend"
         >
-          <span class="mint-well-plate__legend-label">{{ props.heatmap.min ?? 0 }}</span>
+          <span class="mint-well-plate__legend-label">{{ config.heatmap.min ?? 0 }}</span>
           <div class="mint-well-plate__legend-bar">
             <div
-              v-for="(color, index) in (props.heatmap.colorScale === 'custom' && props.heatmap.customColors?.length ? props.heatmap.customColors : HEATMAP_COLORS[props.heatmap.colorScale || 'viridis'])"
+              v-for="(color, index) in (config.heatmap.colorScale === 'custom' && config.heatmap.customColors?.length ? config.heatmap.customColors : HEATMAP_COLORS[config.heatmap.colorScale || 'viridis'])"
               :key="index"
               class="mint-well-plate__legend-segment"
               :style="{ backgroundColor: color }"
             />
           </div>
-          <span class="mint-well-plate__legend-label">{{ props.heatmap.max ?? 1 }}</span>
+          <span class="mint-well-plate__legend-label">{{ config.heatmap.max ?? 1 }}</span>
         </div>
 
         <!-- Sample type legend bar -->
-        <div v-if="props.showLegend" class="mint-well-plate__sample-legend">
+        <div v-if="config.showLegend" class="mint-well-plate__sample-legend">
           <div
             v-for="item in activeLegendItems"
             :key="item.type"
@@ -526,13 +500,13 @@ const tableStyle = computed(() => ({
     </div>
 
     <!-- Edit popup -->
-    <template v-if="editable && editingWellId">
+    <template v-if="config.editable && editingWellId">
       <slot
         name="well-editor"
         :well-id="editingWellId"
         :well-data="wells[editingWellId]"
-        :edit-fields="editFields"
-        :default-injection-volume="defaultInjectionVolume"
+        :edit-fields="config.editFields"
+        :default-injection-volume="config.defaultInjectionVolume"
         :position="editPopupPosition"
         :save="handleEditSave"
         :clear="handleEditClear"
@@ -541,9 +515,9 @@ const tableStyle = computed(() => ({
         <WellEditPopupInternal
           :well-id="editingWellId"
           :well-data="wells[editingWellId]"
-          :edit-fields="editFields"
-          :default-injection-volume="defaultInjectionVolume"
-          :marker-colors="sampleColors"
+          :edit-fields="config.editFields"
+          :default-injection-volume="config.defaultInjectionVolume"
+          :marker-colors="config.sampleColors"
           :position="editPopupPosition"
           @save="handleEditSave"
           @clear="handleEditClear"