@morscherlab/mint-sdk 1.0.0-beta.1 → 1.0.0-beta.3

package/src/components/ProtocolStepEditor.vue

@@ -1,7 +1,8 @@
 <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, onUnmounted } from 'vue'
+import { ref, computed, watch, onMounted } from 'vue'
 import type { ProtocolStep, ProtocolStepType, ProtocolStepStatus } from '../types'
+import { useDropdownState } from '../composables/useDropdownState'
 import {
   useProtocolTemplates,
   type StepTemplate,
@@ -38,7 +39,12 @@ const {
 
 // State
 const selectedTemplateId = ref<string | null>(null)
-const dropdownOpen = ref(false)
+const {
+  isOpen: templateDropdownOpen,
+  rootRef: templateDropdownRef,
+  close: closeTemplateDropdown,
+  toggle: toggleTemplateDropdown,
+} = useDropdownState()
 const stepName = ref('')
 const stepDescription = ref('')
 const stepDuration = ref<number | undefined>()
@@ -113,7 +119,7 @@ function initFromStep(step: ProtocolStep) {
 // Handle template selection
 function selectTemplate(template: StepTemplate) {
   selectedTemplateId.value = template.id
-  dropdownOpen.value = false
+  closeTemplateDropdown()
 
   // Reset to template defaults if creating new
   if (props.mode === 'create') {
@@ -185,14 +191,6 @@ function handleCancel() {
   emit('cancel')
 }
 
-// Close dropdown on click outside
-function handleClickOutside(event: MouseEvent) {
-  const target = event.target as HTMLElement
-  if (!target.closest('.mint-protocol-editor__template-dropdown')) {
-    dropdownOpen.value = false
-  }
-}
-
 // Format duration
 function formatDuration(minutes: number | undefined): string {
   if (minutes === undefined) return ''
@@ -202,10 +200,7 @@ function formatDuration(minutes: number | undefined): string {
   return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`
 }
 
-// Lifecycle
 onMounted(() => {
-  document.addEventListener('click', handleClickOutside)
-
   if (props.modelValue) {
     initFromStep(props.modelValue)
   } else if (availableTemplates.value.length > 0) {
@@ -213,10 +208,6 @@ onMounted(() => {
   }
 })
 
-onUnmounted(() => {
-  document.removeEventListener('click', handleClickOutside)
-})
-
 // Watch for external changes
 watch(
   () => props.modelValue,
@@ -250,11 +241,11 @@ watch(
       <!-- Template selector -->
       <div class="mint-protocol-editor__template-select">
         <label class="mint-protocol-editor__template-label">Template</label>
-        <div class="mint-protocol-editor__template-dropdown">
+        <div ref="templateDropdownRef" class="mint-protocol-editor__template-dropdown">
           <button
             type="button"
             class="mint-protocol-editor__template-btn"
-            @click.stop="dropdownOpen = !dropdownOpen"
+            @click="toggleTemplateDropdown"
           >
             <svg
               v-if="selectedTemplate"
@@ -276,7 +267,7 @@ watch(
             <svg
               :class="[
                 'mint-protocol-editor__template-arrow',
-                dropdownOpen ? 'mint-protocol-editor__template-arrow--open' : '',
+                templateDropdownOpen ? 'mint-protocol-editor__template-arrow--open' : '',
               ]"
               fill="none"
               stroke="currentColor"
@@ -286,7 +277,7 @@ watch(
             </svg>
           </button>
 
-          <div v-if="dropdownOpen" class="mint-protocol-editor__template-menu">
+          <div v-if="templateDropdownOpen" class="mint-protocol-editor__template-menu">
             <button
               v-for="template in availableTemplates"
               :key="template.id"

package/src/components/ReagentList.vue

@@ -2,6 +2,8 @@
 /** Sortable, searchable table of experiment reagents showing lot number, expiry, storage conditions, and stock level with low-stock warnings. */
 import { ref, computed } from 'vue'
 import type { ReagentColumn, Reagent } from '../types'
+import { useSortedItems } from '../composables/useSortedItems'
+import { useTextSearch } from '../composables/useTextSearch'
 
 interface Props {
   modelValue?: Reagent[]
@@ -50,43 +52,33 @@ const columnLabels: Record<ReagentColumn, string> = {
   supplier: 'Supplier',
 }
 
-// Computed
-const filteredReagents = computed(() => {
-  let result = [...(props.modelValue || [])]
-
-  // Filter by search query
-  if (searchQuery.value) {
-    const query = searchQuery.value.toLowerCase()
-    result = result.filter(
-      (r) =>
-        r.name.toLowerCase().includes(query) ||
-        r.catalogNumber?.toLowerCase().includes(query) ||
-        r.lotNumber?.toLowerCase().includes(query) ||
-        r.supplier?.toLowerCase().includes(query)
-    )
-  }
-
-  // Sort
-  if (sortColumn.value) {
-    const col = sortColumn.value
-    result.sort((a, b) => {
-      let aVal: string | number | null | undefined = getColumnValue(a, col) as string | number | null | undefined
-      let bVal: string | number | null | undefined = getColumnValue(b, col) as string | number | null | undefined
-
-      if (aVal === null || aVal === undefined) return 1
-      if (bVal === null || bVal === undefined) return -1
-
-      if (typeof aVal === 'string') aVal = aVal.toLowerCase()
-      if (typeof bVal === 'string') bVal = bVal.toLowerCase()
+const reagentSearch = useTextSearch({
+  items: () => props.modelValue || [],
+  query: searchQuery,
+  enabled: () => props.searchable,
+  getText: (reagent) => [
+    reagent.name,
+    reagent.catalogNumber,
+    reagent.lotNumber,
+    reagent.supplier,
+  ],
+})
 
-      if (aVal < bVal) return sortDirection.value === 'asc' ? -1 : 1
-      if (aVal > bVal) return sortDirection.value === 'asc' ? 1 : -1
-      return 0
-    })
+const reagentSort = computed(() => {
+  if (!sortColumn.value) return null
+  return {
+    key: sortColumn.value,
+    direction: sortDirection.value,
   }
+})
 
-  return result
+const sortedReagents = useSortedItems<Reagent, ReagentColumn>({
+  items: reagentSearch.filteredItems,
+  sort: reagentSort,
+  caseSensitive: false,
+  getValue: (reagent, column) => getColumnValue(reagent, column),
 })
+const filteredReagents = sortedReagents.sortedItems
 
 function getColumnValue(reagent: Reagent, column: ReagentColumn): unknown {
   switch (column) {

package/src/components/SampleHierarchyTree.vue

@@ -1,8 +1,8 @@
 <script setup lang="ts">
 /** Collapsible tree visualizing the biological sample hierarchy (study → experiment → plate → sample → cell line → passage → clone → treatment). */
-import { ref, watch, type VNode } from 'vue'
-import { h, Transition } from 'vue'
+import { h, Transition, type VNode } from 'vue'
 import type { TreeNodeType, BadgeVariant, TreeNode } from '../types'
+import { useExpansionSet } from '../composables/useExpansionSet'
 
 interface Props {
   nodes: TreeNode[]
@@ -28,9 +28,6 @@ const emit = defineEmits<{
   'collapse': [nodeId: string]
 }>()
 
-// Track expanded nodes
-const expandedIds = ref<Set<string>>(new Set(props.defaultExpandedIds))
-
 // Default icons by type (Lucide SVG paths - arrays to support multi-path icons)
 interface IconElement {
   tag: 'path' | 'circle' | 'rect'
@@ -100,30 +97,22 @@ function collectAllIds(nodes: TreeNode[]): string[] {
   return ids
 }
 
-// Watch for expandAll changes
-watch(
-  () => props.expandAll,
-  (shouldExpandAll) => {
-    if (shouldExpandAll) {
-      expandedIds.value = new Set(collectAllIds(props.nodes))
-    } else {
-      expandedIds.value = new Set(props.defaultExpandedIds)
-    }
-  },
-  { immediate: true }
-)
+const expansion = useExpansionSet({
+  defaultIds: () => props.defaultExpandedIds,
+  allIds: () => collectAllIds(props.nodes),
+  expandAll: () => props.expandAll,
+})
 
 function isExpanded(nodeId: string): boolean {
-  return expandedIds.value.has(nodeId)
+  return expansion.isExpanded(nodeId)
 }
 
 function toggleExpand(node: TreeNode) {
-  if (isExpanded(node.id)) {
-    expandedIds.value.delete(node.id)
-    emit('collapse', node.id)
-  } else {
-    expandedIds.value.add(node.id)
+  const expanded = expansion.toggle(node.id)
+  if (expanded) {
     emit('expand', node.id)
+  } else {
+    emit('collapse', node.id)
   }
 }
 

package/src/components/SampleSelector.vue

@@ -6,8 +6,11 @@ import BaseInput from './BaseInput.vue'
 import AutoGroupModal from './AutoGroupModal.vue'
 import type { SampleGroup } from '../types'
 import type { AutoGroupResult } from '../types/auto-group'
-import { deriveShade } from '../utils/color'
 import { DEFAULT_COLORS } from '../composables/useAutoGroup'
+import { useTextSearch } from '../composables/useTextSearch'
+import { useListSelection } from '../composables/useListSelection'
+import { useSampleGroups, type SampleMajorGroup } from '../composables/useSampleGroups'
+import { useExpansionSet } from '../composables/useExpansionSet'
 
 interface Props {
   samples: string[]
@@ -42,8 +45,8 @@ const showSmartGroupModal = ref(false)
 const newGroupName = ref('')
 const editingColor = ref<ColorEdit | null>(null)
 const colorPickerInput = ref<HTMLInputElement | null>(null)
-const expandedGroups = ref<Record<string, boolean>>({})
 const searchQuery = ref('')
+const groupExpansion = useExpansionSet()
 
 // Sample Drag State
 const draggingSample = ref<string | null>(null)
@@ -63,184 +66,102 @@ const internalGroups = computed({
   set: (value) => emit('update:groups', value),
 })
 
-interface DisplaySubGroup extends SampleGroup {
-  displayColor: string
-  // Pre-built `displayColor + alpha` strings hoisted out of the template so
-  // each render re-uses the same string reference instead of re-allocating.
-  displayBg: string
-  displayBorder: string
-}
-
-interface MajorGroup {
-  name: string
-  color: string
-  subGroups: DisplaySubGroup[]
-  allSamples: string[]
-}
-
-const hierarchicalGroups = computed<MajorGroup[]>(() => {
-  const groups = internalGroups.value
-  if (groups.length === 0) return []
-
-  // Detect separator: use '/' if any group name contains it, otherwise '_'
-  const separator = groups.some(g => g.name.includes('/')) ? '/' : '_'
-  const majorGroupMap: Record<string, SampleGroup[]> = {}
-
-  for (const group of groups) {
-    const parts = group.name.split(separator)
-    // Use first part as major group, or full name if no separator
-    const majorPrefix = parts.length > 1 ? parts[0] : group.name
-
-    if (!majorGroupMap[majorPrefix]) {
-      majorGroupMap[majorPrefix] = []
-    }
-    majorGroupMap[majorPrefix].push(group)
-  }
-
-  const result: MajorGroup[] = []
-
-  // Preserve insertion order from internalGroups so manual drag-reorder sticks.
-  for (const [majorName, subGroups] of Object.entries(majorGroupMap)) {
-    const allSamples = subGroups.flatMap(g => g.samples)
-    const color = subGroups[0]?.color || '#3B82F6'
-    const displaySubs: DisplaySubGroup[] = subGroups.map((sub, i) => {
-      const displayColor = deriveShade(color, i, subGroups.length)
-      return {
-        ...sub,
-        displayColor,
-        displayBg: displayColor + '20',
-        displayBorder: displayColor + '40',
-      }
-    })
-
-    result.push({ name: majorName, color, subGroups: displaySubs, allSamples })
-  }
-
-  return result
-})
-
-// Check if hierarchy is meaningful (major groups have multiple sub-groups)
-// If each major group only has 1 sub-group with same name, show flat view instead
-const showHierarchy = computed(() => {
-  const groups = hierarchicalGroups.value
-  if (groups.length === 0) return false
-
-  // Show hierarchy if any major group has multiple sub-groups
-  // OR if major group name differs from its sub-group name
-  return groups.some(major =>
-    major.subGroups.length > 1 ||
-    (major.subGroups.length === 1 && major.name !== major.subGroups[0].name)
-  )
+const sampleGroups = useSampleGroups({
+  samples: () => props.samples,
+  groups: internalGroups,
 })
+const hierarchicalGroups = sampleGroups.hierarchicalGroups
+const showHierarchy = sampleGroups.showHierarchy
 
 const groupingEnabled = computed(() => internalGroups.value.length > 0)
+const ungroupedSamples = sampleGroups.ungroupedSamples
 
-const ungroupedSamples = computed(() => {
-  const groupedSamples = new Set(
-    internalGroups.value.flatMap(g => g.samples)
-  )
-  return props.samples.filter(s => !groupedSamples.has(s))
+const sampleSearch = useTextSearch({
+  items: () => props.samples,
+  query: searchQuery,
+  getText: sample => sample,
 })
+const filteredSamples = sampleSearch.filteredItems
 
-const filteredSamples = computed(() => {
-  if (!searchQuery.value.trim()) return props.samples
-  const query = searchQuery.value.toLowerCase()
-  return props.samples.filter(s => s.toLowerCase().includes(query))
+const sampleSelection = useListSelection({
+  selected: () => props.modelValue,
+  items: () => props.samples,
 })
-
-
-// Selection state
-const isAllSelected = computed(() =>
-  props.samples.length > 0 && props.modelValue.length === props.samples.length
-)
+const isAllSelected = sampleSelection.isAllSelected
 
 // Toggle functions
 function toggleSelectAll() {
-  if (isAllSelected.value) {
-    emit('update:modelValue', [])
-  } else {
-    emit('update:modelValue', [...props.samples])
-  }
+  emit('update:modelValue', sampleSelection.toggleAll())
 }
 
 function toggleSample(sample: string) {
-  const newSelection = props.modelValue.includes(sample)
-    ? props.modelValue.filter(s => s !== sample)
-    : [...props.modelValue, sample]
-  emit('update:modelValue', newSelection)
+  emit('update:modelValue', sampleSelection.toggleValue(sample))
 }
 
 function toggleSamplesSelection(samples: string[]) {
-  const allSelected = samples.every(s => props.modelValue.includes(s))
-  const newSelection = allSelected
-    ? props.modelValue.filter(s => !samples.includes(s))
-    : [...props.modelValue, ...samples.filter(s => !props.modelValue.includes(s))]
-
-  emit('update:modelValue', newSelection)
+  emit('update:modelValue', sampleSelection.toggleValues(samples))
 }
 
 function toggleGroupSamples(groupName: string) {
-  const group = internalGroups.value.find(g => g.name === groupName)
+  const group = sampleGroups.findGroup(groupName)
   if (!group) return
   toggleSamplesSelection(group.samples)
 }
 
-function toggleMajorGroupSamples(majorGroup: MajorGroup) {
+function toggleMajorGroupSamples(majorGroup: SampleMajorGroup) {
   toggleSamplesSelection(majorGroup.allSamples)
 }
 
 // Selection state checks
 function isFullySelected(samples: string[]): boolean {
-  return samples.length > 0 && samples.every(s => props.modelValue.includes(s))
+  return sampleSelection.isFullySelected(samples)
 }
 
 function isPartiallySelected(samples: string[]): boolean {
-  if (samples.length === 0) return false
-  const selectedCount = samples.filter(s => props.modelValue.includes(s)).length
-  return selectedCount > 0 && selectedCount < samples.length
+  return sampleSelection.isPartiallySelected(samples)
 }
 
 function isGroupFullySelected(groupName: string): boolean {
-  const group = internalGroups.value.find(g => g.name === groupName)
+  const group = sampleGroups.findGroup(groupName)
   return group ? isFullySelected(group.samples) : false
 }
 
 function isGroupPartiallySelected(groupName: string): boolean {
-  const group = internalGroups.value.find(g => g.name === groupName)
+  const group = sampleGroups.findGroup(groupName)
   return group ? isPartiallySelected(group.samples) : false
 }
 
-function isMajorGroupFullySelected(majorGroup: MajorGroup): boolean {
+function isMajorGroupFullySelected(majorGroup: SampleMajorGroup): boolean {
   return isFullySelected(majorGroup.allSamples)
 }
 
-function isMajorGroupPartiallySelected(majorGroup: MajorGroup): boolean {
+function isMajorGroupPartiallySelected(majorGroup: SampleMajorGroup): boolean {
   return isPartiallySelected(majorGroup.allSamples)
 }
 
 // Expand/collapse
 function toggleGroupExpanded(groupName: string) {
-  expandedGroups.value[groupName] = !expandedGroups.value[groupName]
+  groupExpansion.toggle(groupName)
 }
 
 function isGroupExpanded(groupName: string): boolean {
-  return !!expandedGroups.value[groupName]
+  return groupExpansion.isExpanded(groupName)
 }
 
 function expandAllGroups() {
-  const expanded: Record<string, boolean> = {}
+  const expanded: string[] = []
   for (const major of hierarchicalGroups.value) {
-    expanded[`major:${major.name}`] = true
+    expanded.push(`major:${major.name}`)
     for (const sub of major.subGroups) {
-      expanded[sub.name] = true
+      expanded.push(sub.name)
     }
   }
-  expanded['__ungrouped__'] = true
-  expandedGroups.value = expanded
+  expanded.push('__ungrouped__')
+  groupExpansion.setExpanded(expanded)
 }
 
 function collapseAllGroups() {
-  expandedGroups.value = {}
+  groupExpansion.collapseAll()
 }
 
 // Smart group
@@ -254,7 +175,7 @@ function clearGroups() {
   internalGroups.value = []
 }
 
-function deleteMajorGroup(majorGroup: MajorGroup) {
+function deleteMajorGroup(majorGroup: SampleMajorGroup) {
   internalGroups.value = internalGroups.value.filter(
     g => !majorGroup.subGroups.some(sg => sg.name === g.name)
   )
@@ -452,7 +373,7 @@ function openColorPicker(groupName: string, event: Event) {
   colorPickerInput.value?.click()
 }
 
-function openMajorGroupColorPicker(majorGroup: MajorGroup, event: Event) {
+function openMajorGroupColorPicker(majorGroup: SampleMajorGroup, event: Event) {
   event.stopPropagation()
   editingColor.value = { kind: 'family', names: majorGroup.subGroups.map(sg => sg.name) }
   colorPickerInput.value?.click()
@@ -473,8 +394,7 @@ function handleColorChange(event: Event) {
 }
 
 function getGroupColor(groupName: string): string {
-  const group = internalGroups.value.find(g => g.name === groupName)
-  return group?.color || '#3B82F6'
+  return sampleGroups.getGroupColor(groupName)
 }
 
 const colorPickerSeed = computed(() => {

package/src/components/SegmentedControl.vue

@@ -1,10 +1,12 @@
 <script setup lang="ts">
 /** Renders a segmented button group for single-option selection, with simple or solid variants. */
-import type { SegmentedOption, SegmentedControlVariant, SegmentedControlSize } from '../types'
+import { computed } from 'vue'
+import type { SegmentedOption, SegmentedOptionInput, SegmentedControlVariant, SegmentedControlSize } from '../types'
+import { normalizeOptionInput } from '../utils/options'
 
 interface Props {
   modelValue: string | number
-  options: SegmentedOption[]
+  options: SegmentedOptionInput[]
   variant?: SegmentedControlVariant
   size?: SegmentedControlSize
   fullWidth?: boolean
@@ -22,6 +24,8 @@ const emit = defineEmits<{
   'update:modelValue': [value: string | number]
 }>()
 
+const normalizedOptions = computed<SegmentedOption[]>(() => props.options.map(normalizeOptionInput))
+
 function handleSelect(option: SegmentedOption) {
   if (props.disabled || option.disabled) return
   emit('update:modelValue', option.value)
@@ -47,7 +51,7 @@ function handleKeydown(event: KeyboardEvent, option: SegmentedOption) {
     role="radiogroup"
   >
     <button
-      v-for="option in options"
+      v-for="option in normalizedOptions"
       :key="String(option.value)"
       type="button"
       role="radio"

package/src/components/SettingsButton.story.vue

@@ -5,7 +5,7 @@ const sizes: ('sm' | 'md' | 'lg')[] = ['sm', 'md', 'lg']
 </script>
 
 <template>
-  <Story title="Action/SettingsButton">
+  <Story title="Action/Deprecated/SettingsButton">
     <Variant title="Playground">
       <template #default="{ state }">
         <div style="padding: 2rem; display: flex; align-items: center; justify-content: center;">

package/src/components/SettingsButton.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
-/** Gear icon button that toggles a dropdown panel for inline settings content, closing on outside click. */
-import { ref, onMounted, onUnmounted } from 'vue'
+/** @deprecated Use AppTopBar settingsConfig or SettingsModal instead. */
+import { useDropdownState } from '../composables/useDropdownState'
+import IconButton from './IconButton.vue'
 
 interface Props {
   size?: 'sm' | 'md' | 'lg'
@@ -14,41 +15,28 @@ const emit = defineEmits<{
   click: [event: MouseEvent]
 }>()
 
-const isOpen = ref(false)
-const dropdownRef = ref<HTMLElement | null>(null)
+const { isOpen, rootRef, toggle: toggleDropdown } = useDropdownState({
+  closeOnEscape: false,
+})
 
 function toggle(event: MouseEvent) {
-  isOpen.value = !isOpen.value
+  toggleDropdown()
   emit('click', event)
 }
-
-function handleClickOutside(event: MouseEvent) {
-  const target = event.target as Node
-  if (dropdownRef.value && !dropdownRef.value.contains(target)) {
-    isOpen.value = false
-  }
-}
-
-onMounted(() => {
-  document.addEventListener('click', handleClickOutside)
-})
-
-onUnmounted(() => {
-  document.removeEventListener('click', handleClickOutside)
-})
 </script>
 
 <template>
-  <div ref="dropdownRef" class="mint-settings-button">
-    <button
-      type="button"
-      :class="['mint-settings-button__trigger', `mint-settings-button__trigger--${size}`]"
-      aria-label="Settings"
+  <div ref="rootRef" class="mint-settings-button">
+    <IconButton
+      class="mint-settings-button__trigger"
+      label="Settings"
+      variant="ghost"
+      :size="size"
       @click.stop="toggle"
     >
       <!-- Settings/Gear icon -->
       <svg
-        :class="`mint-settings-button__icon--${size}`"
+        class="mint-settings-button__icon"
         viewBox="0 0 24 24"
         fill="none"
         stroke="currentColor"
@@ -58,7 +46,7 @@ onUnmounted(() => {
       >
         <path d="M9.671 4.136a2.34 2.34 0 0 1 4.659 0 2.34 2.34 0 0 0 3.319 1.915 2.34 2.34 0 0 1 2.33 4.033 2.34 2.34 0 0 0 0 3.831 2.34 2.34 0 0 1-2.33 4.033 2.34 2.34 0 0 0-3.319 1.915 2.34 2.34 0 0 1-4.659 0 2.34 2.34 0 0 0-3.32-1.915 2.34 2.34 0 0 1-2.33-4.033 2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915" /><circle cx="12" cy="12" r="3" />
       </svg>
-    </button>
+    </IconButton>
 
     <!-- Dropdown panel -->
     <div v-show="isOpen" class="mint-settings-dropdown">