@morscherlab/mint-sdk 1.0.0-rc.2 → 1.0.0-rc.5

package/src/components/ProtocolStepEditor.vue

@@ -1,14 +1,25 @@
 <script setup lang="ts">
 /** Form for creating or editing a single protocol step (incubation, wash, addition, centrifuge, etc.) with template picker, typed parameters, and duration. */
 import { ref, computed, watch, onMounted } from 'vue'
-import type { ProtocolStep, ProtocolStepType, ProtocolStepStatus } from '../types'
+import type { ProtocolStep } from '../types'
 import { useDropdownState } from '../composables/useDropdownState'
 import {
   useProtocolTemplates,
   type StepTemplate,
 } from '../composables/useProtocolTemplates'
-import ConcentrationInput from './ConcentrationInput.vue'
-import type { ConcentrationValue } from '../composables/useConcentrationUnits'
+import {
+  PROTOCOL_STEP_TYPE_ICONS as stepTypeIcons,
+  formatProtocolDuration as formatDuration,
+} from './ProtocolStep.presentation'
+import ProtocolStepParameterField from './ProtocolStepParameterField.vue'
+import {
+  buildCustomProtocolTemplate,
+  buildProtocolPreviewParams,
+  buildProtocolStepEditorState,
+  buildProtocolStepPreview,
+  buildProtocolTemplateDefaults,
+  type ProtocolStepEditorFields,
+} from './ProtocolStepEditor.state'
 
 interface Props {
   modelValue?: ProtocolStep
@@ -69,51 +80,41 @@ const selectedTemplate = computed(() => {
   return availableTemplates.value.find((t) => t.id === selectedTemplateId.value) || null
 })
 
-// Step type icons (same as ExperimentTimeline)
-const stepTypeIcons: Record<ProtocolStepType, string> = {
-  incubation: 'M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z',
-  wash: 'M5 3v4M3 5h4M6 17v4m-2-2h4m5-16l2.286 6.857L21 12l-5.714 2.143L13 21l-2.286-6.857L5 12l5.714-2.143L13 3z',
-  addition: 'M12 9v3m0 0v3m0-3h3m-3 0H9m12 0a9 9 0 11-18 0 9 9 0 0118 0z',
-  measurement: 'M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z',
-  transfer: 'M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4',
-  centrifuge: 'M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15',
-  mix: 'M14.752 11.168l-3.197-2.132A1 1 0 0010 9.87v4.263a1 1 0 001.555.832l3.197-2.132a1 1 0 000-1.664z',
-  custom: 'M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z',
-}
-
 // Preview computed
 const previewStep = computed<ProtocolStep | null>(() => {
   if (!selectedTemplate.value) return null
-  return {
-    id: props.modelValue?.id || 'preview',
-    type: selectedTemplate.value.type,
-    name: stepName.value || selectedTemplate.value.name,
-    description: stepDescription.value,
-    duration: stepDuration.value ?? selectedTemplate.value.defaultDuration,
-    status: (props.modelValue?.status || 'pending') as ProtocolStepStatus,
-    parameters: { ...parameters.value },
-    order: props.modelValue?.order || 0,
-  }
+  return buildProtocolStepPreview(selectedTemplate.value, editorFields(), props.modelValue)
 })
 
 const previewParams = computed(() => {
   if (!selectedTemplate.value || !previewStep.value) return ''
-  return selectedTemplate.value.parameters
-    .filter((p) => parameters.value[p.key] !== undefined && parameters.value[p.key] !== '')
-    .map((p) => formatParameterValue(parameters.value[p.key], p))
-    .join(', ')
+  return buildProtocolPreviewParams(
+    selectedTemplate.value,
+    parameters.value,
+    formatParameterValue
+  )
 })
 
-// Initialize from modelValue
-function initFromStep(step: ProtocolStep) {
-  const template = getTemplateByType(step.type)
-  if (template) {
-    selectedTemplateId.value = template.id
+function editorFields(): ProtocolStepEditorFields {
+  return {
+    name: stepName.value,
+    description: stepDescription.value,
+    duration: stepDuration.value,
+    parameters: parameters.value,
   }
-  stepName.value = step.name
-  stepDescription.value = step.description || ''
-  stepDuration.value = step.duration
-  parameters.value = { ...(step.parameters || {}) }
+}
+
+function applyEditorFields(fields: ProtocolStepEditorFields) {
+  stepName.value = fields.name
+  stepDescription.value = fields.description
+  stepDuration.value = fields.duration
+  parameters.value = { ...fields.parameters }
+}
+
+function initFromStep(step: ProtocolStep) {
+  const state = buildProtocolStepEditorState(step, getTemplateByType)
+  selectedTemplateId.value = state.selectedTemplateId
+  applyEditorFields(state.fields)
 }
 
 // Handle template selection
@@ -123,16 +124,7 @@ function selectTemplate(template: StepTemplate) {
 
   // Reset to template defaults if creating new
   if (props.mode === 'create') {
-    stepName.value = template.name
-    stepDescription.value = template.description || ''
-    stepDuration.value = template.defaultDuration
-
-    parameters.value = {}
-    for (const param of template.parameters) {
-      if (param.default !== undefined) {
-        parameters.value[param.key] = param.default
-      }
-    }
+    applyEditorFields(buildProtocolTemplateDefaults(template))
   }
 }
 
@@ -145,14 +137,6 @@ function handleParamChange(key: string, value: unknown) {
   }
 }
 
-// Handle concentration change
-function handleConcentrationChange(key: string, value: ConcentrationValue | undefined) {
-  parameters.value[key] = value
-  if (validationErrors.value[key]) {
-    delete validationErrors.value[key]
-  }
-}
-
 // Validate and save
 function handleSave() {
   if (!selectedTemplate.value || !previewStep.value) return
@@ -169,21 +153,7 @@ function handleSave() {
 // Save as template
 function handleSaveTemplate() {
   if (!selectedTemplate.value) return
-
-  const newTemplate: StepTemplate = {
-    id: `custom-${Date.now()}`,
-    type: selectedTemplate.value.type,
-    name: stepName.value || selectedTemplate.value.name,
-    description: stepDescription.value,
-    defaultDuration: stepDuration.value,
-    parameters: selectedTemplate.value.parameters.map((p) => ({
-      ...p,
-      default: parameters.value[p.key],
-    })),
-    isBuiltIn: false,
-  }
-
-  emit('save-template', newTemplate)
+  emit('save-template', buildCustomProtocolTemplate(selectedTemplate.value, editorFields()))
 }
 
 // Handle cancel
@@ -191,15 +161,6 @@ function handleCancel() {
   emit('cancel')
 }
 
-// Format duration
-function formatDuration(minutes: number | undefined): string {
-  if (minutes === undefined) return ''
-  if (minutes < 60) return `${minutes}m`
-  const hours = Math.floor(minutes / 60)
-  const mins = minutes % 60
-  return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`
-}
-
 onMounted(() => {
   if (props.modelValue) {
     initFromStep(props.modelValue)
@@ -335,106 +296,14 @@ watch(
 
       <!-- Dynamic parameters -->
       <template v-if="selectedTemplate">
-        <div
-          v-for="(param, index) in selectedTemplate.parameters"
+        <ProtocolStepParameterField
+          v-for="param in selectedTemplate.parameters"
           :key="param.key"
-          :class="[
-            'mint-protocol-editor__field',
-            index % 2 === 0 && selectedTemplate.parameters[index + 1]
-              ? ''
-              : '',
-          ]"
-        >
-          <label
-            :class="[
-              'mint-protocol-editor__field-label',
-              param.required ? 'mint-protocol-editor__field-label--required' : '',
-            ]"
-          >
-            {{ param.label }}
-          </label>
-
-          <!-- Number input with unit -->
-          <div
-            v-if="param.type === 'number' || param.type === 'temperature' || param.type === 'duration'"
-            class="mint-protocol-editor__input-unit"
-          >
-            <input
-              type="number"
-              :value="parameters[param.key]"
-              :min="param.min"
-              :max="param.max"
-              :placeholder="param.placeholder || `Enter ${param.label.toLowerCase()}`"
-              :class="[
-                'mint-protocol-editor__input',
-                validationErrors[param.key] ? 'mint-protocol-editor__input--error' : '',
-              ]"
-              @input="handleParamChange(param.key, ($event.target as HTMLInputElement).valueAsNumber)"
-            />
-            <span v-if="param.unit" class="mint-protocol-editor__unit-suffix">
-              {{ param.unit }}
-            </span>
-          </div>
-
-          <!-- Text input -->
-          <input
-            v-else-if="param.type === 'text'"
-            type="text"
-            :value="parameters[param.key]"
-            :placeholder="param.placeholder || `Enter ${param.label.toLowerCase()}`"
-            :class="[
-              'mint-protocol-editor__input',
-              validationErrors[param.key] ? 'mint-protocol-editor__input--error' : '',
-            ]"
-            @input="handleParamChange(param.key, ($event.target as HTMLInputElement).value)"
-          />
-
-          <!-- Select -->
-          <select
-            v-else-if="param.type === 'select'"
-            :value="parameters[param.key]"
-            :class="[
-              'mint-protocol-editor__select',
-              validationErrors[param.key] ? 'mint-protocol-editor__input--error' : '',
-            ]"
-            @change="handleParamChange(param.key, ($event.target as HTMLSelectElement).value)"
-          >
-            <option value="" disabled>Select {{ param.label.toLowerCase() }}</option>
-            <option
-              v-for="option in param.options"
-              :key="option.value"
-              :value="option.value"
-            >
-              {{ option.label }}
-            </option>
-          </select>
-
-          <!-- Concentration input -->
-          <ConcentrationInput
-            v-else-if="param.type === 'concentration'"
-            :model-value="parameters[param.key] as ConcentrationValue | undefined"
-            :error="!!validationErrors[param.key]"
-            size="md"
-            @update:model-value="handleConcentrationChange(param.key, $event)"
-          />
-
-          <!-- Reagent input (text for now) -->
-          <input
-            v-else-if="param.type === 'reagent'"
-            type="text"
-            :value="parameters[param.key]"
-            :placeholder="param.placeholder || 'Enter reagent name'"
-            :class="[
-              'mint-protocol-editor__input',
-              validationErrors[param.key] ? 'mint-protocol-editor__input--error' : '',
-            ]"
-            @input="handleParamChange(param.key, ($event.target as HTMLInputElement).value)"
-          />
-
-          <span v-if="validationErrors[param.key]" class="mint-protocol-editor__field-error">
-            {{ validationErrors[param.key] }}
-          </span>
-        </div>
+          :parameter="param"
+          :model-value="parameters[param.key]"
+          :error="validationErrors[param.key]"
+          @update:model-value="handleParamChange(param.key, $event)"
+        />
       </template>
 
       <!-- Description -->

package/src/components/ProtocolStepParameterField.vue

@@ -0,0 +1,134 @@
+<script setup lang="ts">
+/** Renders one typed parameter control for ProtocolStepEditor. */
+import { computed } from 'vue'
+import type { ParameterDefinition } from '../composables/useProtocolTemplates'
+import type { ConcentrationValue } from '../composables/useConcentrationUnits'
+import ConcentrationInput from './ConcentrationInput.vue'
+
+interface Props {
+  parameter: ParameterDefinition
+  modelValue?: unknown
+  error?: string
+}
+
+const props = defineProps<Props>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: unknown]
+}>()
+
+const scalarValue = computed(() => (
+  props.modelValue as string | number | undefined
+))
+
+const concentrationValue = computed(() => (
+  props.modelValue as ConcentrationValue | undefined
+))
+
+const hasError = computed(() => !!props.error)
+
+function handleNumberInput(event: Event) {
+  emit('update:modelValue', (event.target as HTMLInputElement).valueAsNumber)
+}
+
+function handleTextInput(event: Event) {
+  emit('update:modelValue', (event.target as HTMLInputElement).value)
+}
+
+function handleSelectChange(event: Event) {
+  emit('update:modelValue', (event.target as HTMLSelectElement).value)
+}
+
+function handleConcentrationChange(value: ConcentrationValue | undefined) {
+  emit('update:modelValue', value)
+}
+</script>
+
+<template>
+  <div class="mint-protocol-editor__field">
+    <label
+      :class="[
+        'mint-protocol-editor__field-label',
+        parameter.required ? 'mint-protocol-editor__field-label--required' : '',
+      ]"
+    >
+      {{ parameter.label }}
+    </label>
+
+    <div
+      v-if="parameter.type === 'number' || parameter.type === 'temperature' || parameter.type === 'duration'"
+      class="mint-protocol-editor__input-unit"
+    >
+      <input
+        type="number"
+        :value="scalarValue"
+        :min="parameter.min"
+        :max="parameter.max"
+        :placeholder="parameter.placeholder || `Enter ${parameter.label.toLowerCase()}`"
+        :class="[
+          'mint-protocol-editor__input',
+          hasError ? 'mint-protocol-editor__input--error' : '',
+        ]"
+        @input="handleNumberInput"
+      />
+      <span v-if="parameter.unit" class="mint-protocol-editor__unit-suffix">
+        {{ parameter.unit }}
+      </span>
+    </div>
+
+    <input
+      v-else-if="parameter.type === 'text'"
+      type="text"
+      :value="scalarValue"
+      :placeholder="parameter.placeholder || `Enter ${parameter.label.toLowerCase()}`"
+      :class="[
+        'mint-protocol-editor__input',
+        hasError ? 'mint-protocol-editor__input--error' : '',
+      ]"
+      @input="handleTextInput"
+    />
+
+    <select
+      v-else-if="parameter.type === 'select'"
+      :value="scalarValue"
+      :class="[
+        'mint-protocol-editor__select',
+        hasError ? 'mint-protocol-editor__input--error' : '',
+      ]"
+      @change="handleSelectChange"
+    >
+      <option value="" disabled>Select {{ parameter.label.toLowerCase() }}</option>
+      <option
+        v-for="option in parameter.options"
+        :key="option.value"
+        :value="option.value"
+      >
+        {{ option.label }}
+      </option>
+    </select>
+
+    <ConcentrationInput
+      v-else-if="parameter.type === 'concentration'"
+      :model-value="concentrationValue"
+      :error="hasError"
+      size="md"
+      @update:model-value="handleConcentrationChange"
+    />
+
+    <input
+      v-else-if="parameter.type === 'reagent'"
+      type="text"
+      :value="scalarValue"
+      :placeholder="parameter.placeholder || 'Enter reagent name'"
+      :class="[
+        'mint-protocol-editor__input',
+        hasError ? 'mint-protocol-editor__input--error' : '',
+      ]"
+      @input="handleTextInput"
+    />
+
+    <span v-if="error" class="mint-protocol-editor__field-error">
+      {{ error }}
+    </span>
+  </div>
+</template>

package/src/components/ReagentList.presentation.ts

@@ -0,0 +1,105 @@
+import type { Reagent, ReagentColumn } from '../types'
+
+export const REAGENT_COLUMN_LABELS: Record<ReagentColumn, string> = {
+  name: 'Name',
+  catalog: 'Catalog #',
+  lot: 'Lot #',
+  expiry: 'Expiry',
+  storage: 'Storage',
+  location: 'Location',
+  stock: 'Stock',
+  supplier: 'Supplier',
+}
+
+export interface ReagentRowClassOptions {
+  lowStockThreshold: number
+  draggedId?: string | null
+  dragOverId?: string | null
+  now?: Date
+}
+
+export function getReagentColumnValue(reagent: Reagent, column: ReagentColumn): unknown {
+  switch (column) {
+    case 'name':
+      return reagent.name
+    case 'catalog':
+      return reagent.catalogNumber
+    case 'lot':
+      return reagent.lotNumber
+    case 'expiry':
+      return reagent.expiryDate ? new Date(reagent.expiryDate).getTime() : null
+    case 'storage':
+      return reagent.storageCondition
+    case 'location':
+      return reagent.location
+    case 'stock':
+      return reagent.stockLevel
+    case 'supplier':
+      return reagent.supplier
+    default:
+      return null
+  }
+}
+
+export function isReagentExpired(reagent: Reagent, now = new Date()): boolean {
+  if (!reagent.expiryDate) return false
+  const expiry = new Date(reagent.expiryDate)
+  return expiry < now
+}
+
+export function isReagentExpiringSoon(
+  reagent: Reagent,
+  daysThreshold = 30,
+  now = new Date()
+): boolean {
+  if (!reagent.expiryDate) return false
+  const expiry = new Date(reagent.expiryDate)
+  const daysUntilExpiry = (expiry.getTime() - now.getTime()) / (1000 * 60 * 60 * 24)
+  return daysUntilExpiry > 0 && daysUntilExpiry <= daysThreshold
+}
+
+export function isReagentLowStock(reagent: Reagent, lowStockThreshold: number): boolean {
+  if (reagent.stockLevel === undefined) return false
+  return reagent.stockLevel <= lowStockThreshold
+}
+
+export function formatReagentExpiryDate(date: Date | string | undefined): string {
+  if (!date) return '-'
+  const parsed = new Date(date)
+  return parsed.toLocaleDateString('en-US', { year: 'numeric', month: 'short' })
+}
+
+export function getReagentStockLevel(reagent: Reagent): number {
+  return reagent.stockLevel ?? 0
+}
+
+export function getReagentStockFillClass(level: number): string {
+  if (level >= 50) return 'mint-reagent-list__stock-fill--good'
+  if (level >= 20) return 'mint-reagent-list__stock-fill--warning'
+  return 'mint-reagent-list__stock-fill--low'
+}
+
+export function getReagentRowClasses(
+  reagent: Reagent,
+  options: ReagentRowClassOptions
+): string[] {
+  const classes: string[] = ['mint-reagent-list__row']
+
+  if (isReagentExpired(reagent, options.now)) {
+    classes.push('mint-reagent-list__row--expired')
+  } else if (isReagentExpiringSoon(reagent, 30, options.now)) {
+    classes.push('mint-reagent-list__row--expiring-soon')
+  }
+
+  if (isReagentLowStock(reagent, options.lowStockThreshold)) {
+    classes.push('mint-reagent-list__row--low-stock')
+  }
+  if (options.draggedId === reagent.id) {
+    classes.push('mint-reagent-list__row--dragging')
+  }
+  if (options.dragOverId === reagent.id) {
+    classes.push('mint-reagent-list__row--drag-over')
+  }
+
+  return classes
+}

package/src/components/ReagentList.vue

@@ -4,6 +4,16 @@ import { ref, computed } from 'vue'
 import type { ReagentColumn, Reagent } from '../types'
 import { useSortedItems } from '../composables/useSortedItems'
 import { useTextSearch } from '../composables/useTextSearch'
+import {
+  REAGENT_COLUMN_LABELS as columnLabels,
+  formatReagentExpiryDate as formatExpiryDate,
+  getReagentColumnValue,
+  getReagentRowClasses,
+  getReagentStockFillClass as getStockFillClass,
+  getReagentStockLevel as getStockLevel,
+  isReagentExpired as isExpired,
+  isReagentExpiringSoon as isExpiringSoon,
+} from './ReagentList.presentation'
 
 interface Props {
   modelValue?: Reagent[]
@@ -40,18 +50,6 @@ const sortDirection = ref<'asc' | 'desc'>('asc')
 const draggedId = ref<string | null>(null)
 const dragOverId = ref<string | null>(null)
 
-// Column configuration
-const columnLabels: Record<ReagentColumn, string> = {
-  name: 'Name',
-  catalog: 'Catalog #',
-  lot: 'Lot #',
-  expiry: 'Expiry',
-  storage: 'Storage',
-  location: 'Location',
-  stock: 'Stock',
-  supplier: 'Supplier',
-}
-
 const reagentSearch = useTextSearch({
   items: () => props.modelValue || [],
   query: searchQuery,
@@ -76,77 +74,16 @@ const sortedReagents = useSortedItems<Reagent, ReagentColumn>({
   items: reagentSearch.filteredItems,
   sort: reagentSort,
   caseSensitive: false,
-  getValue: (reagent, column) => getColumnValue(reagent, column),
+  getValue: (reagent, column) => getReagentColumnValue(reagent, column),
 })
 const filteredReagents = sortedReagents.sortedItems
 
-function getColumnValue(reagent: Reagent, column: ReagentColumn): unknown {
-  switch (column) {
-    case 'name':
-      return reagent.name
-    case 'catalog':
-      return reagent.catalogNumber
-    case 'lot':
-      return reagent.lotNumber
-    case 'expiry':
-      return reagent.expiryDate ? new Date(reagent.expiryDate).getTime() : null
-    case 'storage':
-      return reagent.storageCondition
-    case 'location':
-      return reagent.location
-    case 'stock':
-      return reagent.stockLevel
-    case 'supplier':
-      return reagent.supplier
-    default:
-      return null
-  }
-}
-
-// Helpers
-function isExpired(reagent: Reagent): boolean {
-  if (!reagent.expiryDate) return false
-  const expiry = new Date(reagent.expiryDate)
-  return expiry < new Date()
-}
-
-function isExpiringSoon(reagent: Reagent, daysThreshold = 30): boolean {
-  if (!reagent.expiryDate) return false
-  const expiry = new Date(reagent.expiryDate)
-  const now = new Date()
-  const daysUntilExpiry = (expiry.getTime() - now.getTime()) / (1000 * 60 * 60 * 24)
-  return daysUntilExpiry > 0 && daysUntilExpiry <= daysThreshold
-}
-
-function isLowStock(reagent: Reagent): boolean {
-  if (reagent.stockLevel === undefined) return false
-  return reagent.stockLevel <= props.lowStockThreshold
-}
-
-function formatExpiryDate(date: Date | string | undefined): string {
-  if (!date) return '-'
-  const d = new Date(date)
-  return d.toLocaleDateString('en-US', { year: 'numeric', month: 'short' })
-}
-
-function getStockLevel(reagent: Reagent): number {
-  return reagent.stockLevel ?? 0
-}
-
-function getStockFillClass(level: number): string {
-  if (level >= 50) return 'mint-reagent-list__stock-fill--good'
-  if (level >= 20) return 'mint-reagent-list__stock-fill--warning'
-  return 'mint-reagent-list__stock-fill--low'
-}
-
 function getRowClass(reagent: Reagent): string[] {
-  const classes: string[] = ['mint-reagent-list__row']
-  if (isExpired(reagent)) classes.push('mint-reagent-list__row--expired')
-  else if (isExpiringSoon(reagent)) classes.push('mint-reagent-list__row--expiring-soon')
-  if (isLowStock(reagent)) classes.push('mint-reagent-list__row--low-stock')
-  if (draggedId.value === reagent.id) classes.push('mint-reagent-list__row--dragging')
-  if (dragOverId.value === reagent.id) classes.push('mint-reagent-list__row--drag-over')
-  return classes
+  return getReagentRowClasses(reagent, {
+    lowStockThreshold: props.lowStockThreshold,
+    draggedId: draggedId.value,
+    dragOverId: dragOverId.value,
+  })
 }
 
 // Actions

package/src/components/SampleSelector.colors.ts

@@ -0,0 +1,43 @@
+import { DEFAULT_COLORS } from '../composables/useAutoGroup'
+import type { SampleGroup } from '../types'
+
+export type ColorEdit =
+  | { kind: 'single'; name: string }
+  | { kind: 'family'; names: string[] }
+
+export const DEFAULT_COLOR_PICKER_SEED = '#3B82F6'
+
+export function applySampleGroupColorEdit(
+  groups: SampleGroup[],
+  edit: ColorEdit,
+  color: string,
+): SampleGroup[] {
+  const targets = edit.kind === 'family' ? new Set(edit.names) : new Set([edit.name])
+  return groups.map(group =>
+    targets.has(group.name) ? { ...group, color } : group,
+  )
+}
+
+export function getSampleGroupColorEditSeed(
+  edit: ColorEdit | null,
+  getGroupColor: (groupName: string) => string,
+): string {
+  if (!edit) return DEFAULT_COLOR_PICKER_SEED
+  return getGroupColor(edit.kind === 'family' ? edit.names[0] : edit.name)
+}
+
+export function pickUnusedSampleGroupColor(groups: SampleGroup[]): string {
+  const usedColors = new Set(groups.map(group => group.color))
+  return DEFAULT_COLORS.find(color => !usedColors.has(color)) || DEFAULT_COLORS[0]
+}
+
+export function createSampleGroup(name: string, existingGroups: SampleGroup[]): SampleGroup | null {
+  const trimmedName = name.trim()
+  if (!trimmedName) return null
+
+  return {
+    name: trimmedName,
+    color: pickUnusedSampleGroupColor(existingGroups),
+    samples: [],
+  }
+}