@morscherlab/mint-sdk 1.0.44 → 1.0.46

package/src/components/SmartGroupFieldRecipe.vue

@@ -0,0 +1,427 @@
+<script lang="ts">
+/**
+ * SmartGroupFieldRecipe — the "auto" mode of the Smart Group modal.
+ *
+ * MINT parses the structure of sample names into candidate fields; the user
+ * switches on the factors that define their groups. A live preview rail
+ * reflects the resulting groups, an inline summary explains what will happen
+ * (including the replicate "singleton trap"), and a QC routing control decides
+ * how quality-control samples are handled. Grouping maths live in the tested
+ * `./SmartGroupFieldRecipe.groups` module.
+ *
+ * The reference-fixture defaults live in this module-scope `<script>` block
+ * because `defineProps` default factories are hoisted and cannot reference
+ * bindings declared inside `<script setup>`.
+ */
+import type { SmartGroupField, SmartGroupSampleRecord } from './SmartGroupFieldRecipe.groups'
+
+const FR_BASE = [
+  { Condition: 'Control', Dose: 'Vehicle' },
+  { Condition: 'Treatment', Dose: 'Low' },
+  { Condition: 'Treatment', Dose: 'High' },
+]
+const DEFAULT_SAMPLES: SmartGroupSampleRecord[] = FR_BASE.flatMap(base =>
+  [1, 2, 3].map(rep => ({ ...base, Replicate: `Rep${rep}` })),
+)
+const DEFAULT_FIELDS: SmartGroupField[] = [
+  { key: 'Condition', role: 'Factor', vals: 'Control, Treatment', rep: false },
+  { key: 'Dose', role: 'Factor', vals: 'Vehicle, Low, High', rep: false },
+  { key: 'Replicate', role: 'Replicate', vals: 'Rep1, Rep2, Rep3', rep: true },
+]
+const DEFAULT_PALETTE = ['var(--grp-1)', 'var(--grp-2)', 'var(--grp-3)', 'var(--grp-4)', 'var(--grp-5)']
+</script>
+
+<script setup lang="ts">
+import { computed, h, ref, type FunctionalComponent } from 'vue'
+import {
+  appendQcGroup,
+  computeFieldGroups,
+  fieldRecipeSummary,
+  sampleTotalFor,
+  type QcRoute,
+} from './SmartGroupFieldRecipe.groups'
+import { useDropdownState } from '../composables/useDropdownState'
+import BaseButton from './BaseButton.vue'
+import LoadingSpinner from './LoadingSpinner.vue'
+import type { FieldRecipeApplyPayload, SmartGroupFieldRecipeProps } from './SmartGroup.types'
+
+const props = withDefaults(defineProps<SmartGroupFieldRecipeProps>(), {
+  samples: () => DEFAULT_SAMPLES,
+  fields: () => DEFAULT_FIELDS,
+  experimentLabel: 'EXP-014',
+  headerCount: 12,
+  initialRoute: 'Overlay only',
+  palette: () => DEFAULT_PALETTE,
+  qcColor: 'var(--grp-qc)',
+  canDownloadTemplate: true,
+  loading: false,
+})
+
+const emit = defineEmits<{
+  apply: [payload: FieldRecipeApplyPayload]
+  cancel: []
+  manual: []
+  close: []
+  /** Controlled mode: a field toggle was clicked (card index). */
+  toggle: [index: number]
+  /** Controlled mode: the QC routing select changed. */
+  'update:route': [route: QcRoute]
+  /** A CSV/TSV file was chosen (upload button) or dropped; parent parses it. */
+  'csv-file': [file: File]
+  /** Download a blank metadata template (parent calls the engine). */
+  'download-template': []
+  /** Download a pre-filled metadata template (parent calls the engine). */
+  'download-prefilled': []
+}>()
+
+/** Tiny stroke-icon helper sharing the design's path data. */
+const Icon: FunctionalComponent<{ d: string; size?: number }> = iconProps =>
+  h(
+    'svg',
+    {
+      width: iconProps.size ?? 16,
+      height: iconProps.size ?? 16,
+      viewBox: '0 0 24 24',
+      fill: 'none',
+      stroke: 'currentColor',
+      'stroke-width': 2,
+      'stroke-linecap': 'round',
+      'stroke-linejoin': 'round',
+    },
+    [h('path', { d: iconProps.d })],
+  )
+const ICON = {
+  bolt: 'M13 10V3L4 14h7v7l9-11h-7z',
+  info: 'M12 16v-4M12 8h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z',
+  warn: 'M12 9v4M12 17h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z',
+  check: 'M20 6L9 17l-5-5',
+  close: 'M6 18L18 6M6 6l12 12',
+  upload: 'M21 15v4a2 2 0 01-2 2H5a2 2 0 01-2-2v-4M17 8l-5-5-5 5M12 3v12',
+  download: 'M21 15v4a2 2 0 01-2 2H5a2 2 0 01-2-2v-4M7 10l5 5 5-5M12 15V3',
+  chev: 'M6 9l6 6 6-6',
+}
+
+const MAX_BAR = 44
+
+// CSV upload (presentational): the component only surfaces the control and
+// emits the chosen/dropped File; AutoGroupModal parses it into the engine.
+const fileInput = ref<HTMLInputElement | null>(null)
+const dragOver = ref(false)
+let dragDepth = 0
+
+function isCsvLike(file: File): boolean {
+  return /\.(csv|tsv)$/i.test(file.name)
+    || file.type === 'text/csv'
+    || file.type === 'text/tab-separated-values'
+}
+function pickCsv() {
+  fileInput.value?.click()
+}
+function onFileChange(event: Event) {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0]
+  if (file) emit('csv-file', file)
+  input.value = '' // allow re-selecting the same file
+}
+function onDragEnter() {
+  dragDepth += 1
+  dragOver.value = true
+}
+function onDragLeave() {
+  dragDepth = Math.max(0, dragDepth - 1)
+  if (dragDepth === 0) dragOver.value = false
+}
+function onDrop(event: DragEvent) {
+  dragDepth = 0
+  dragOver.value = false
+  const file = event.dataTransfer?.files?.[0]
+  if (file && isCsvLike(file)) emit('csv-file', file)
+}
+
+// CSV action menu — reuses the SDK's dropdown state (outside-click / Escape
+// close) but renders a compact action menu in the .fr-* styling, since the
+// items are actions (upload / download), not a persistent value selection.
+const { isOpen: csvMenuOpen, rootRef: csvMenuRoot, close: closeCsvMenu, toggle: toggleCsvMenu } =
+  useDropdownState()
+
+function chooseUpload() {
+  closeCsvMenu()
+  pickCsv()
+}
+function chooseDownloadTemplate() {
+  if (!props.canDownloadTemplate) return
+  closeCsvMenu()
+  emit('download-template')
+}
+function chooseDownloadPrefilled() {
+  if (!props.canDownloadTemplate) return
+  closeCsvMenu()
+  emit('download-prefilled')
+}
+
+// Uncontrolled fallback state (used by the standalone story). In controlled
+// mode AutoGroupModal supplies `enabled` / `groups` / `route` + `qcChip` and the
+// `toggle` / `update:route` events drive the engine instead of this local state.
+const onInner = ref<boolean[]>(props.initialOn ? [...props.initialOn] : props.fields.map(field => !field.rep))
+const routeInner = ref<QcRoute>(props.initialRoute)
+
+const controlledEnabled = computed(() => props.enabled !== undefined)
+const controlledRoute = computed(() => props.route !== undefined)
+
+const on = computed(() => props.enabled ?? onInner.value)
+const currentRoute = computed(() => props.route ?? routeInner.value)
+
+const computedBase = computed(() => computeFieldGroups(props.samples, props.fields, on.value, props.palette))
+const baseGroups = computed(() => props.groups ?? computedBase.value)
+const groups = computed(() => props.groups ?? appendQcGroup(computedBase.value, currentRoute.value, props.qcColor))
+const activeFactors = computed(() => props.fields.filter((_, i) => on.value[i]).map(field => field.key))
+const counts = computed(() => baseGroups.value.map(group => group.count))
+const uniform = computed(() => counts.value.length > 0 && counts.value.every(count => count === counts.value[0]))
+const repField = computed(() => props.fields.find(field => field.rep))
+const repOn = computed(() => props.fields.some((field, i) => field.rep && on.value[i]))
+const repRange = computed(() => {
+  const parts = (repField.value?.vals ?? '').split(',').map(part => part.trim()).filter(Boolean)
+  if (parts.length === 0) return ''
+  return parts.length > 1 ? `${parts[0]}–${parts[parts.length - 1]}` : parts[0]
+})
+
+const summary = computed(() =>
+  fieldRecipeSummary({ activeFactors: activeFactors.value, repOn: repOn.value, baseGroups: baseGroups.value }),
+)
+const groupedSampleTotal = computed(() => groups.value.reduce((sum, group) => sum + group.count, 0))
+const maxCount = computed(() => Math.max(...groups.value.map(group => group.count), 1))
+const qcCount = computed(() => props.qcCount ?? Math.max(0, props.headerCount - props.samples.length))
+const realCount = computed(() => Math.max(0, props.headerCount - qcCount.value))
+const sampleTotal = computed(() => sampleTotalFor(currentRoute.value, realCount.value, qcCount.value))
+const qcChip = computed(() =>
+  props.qcChip !== undefined
+    ? props.qcChip
+    : currentRoute.value !== 'Mix into groups'
+      ? { name: 'QC_Pool', count: qcCount.value }
+      : null,
+)
+const footHint = computed(() =>
+  currentRoute.value === 'Exclude'
+    ? ` · ${qcCount.value} QC excluded`
+    : currentRoute.value === 'Mix into groups'
+      ? ' · QC mixed in'
+      : ` · ${qcCount.value} QC overlaid`,
+)
+
+function toggle(index: number) {
+  if (controlledEnabled.value) {
+    emit('toggle', index)
+    return
+  }
+  onInner.value = onInner.value.map((value, i) => (i === index ? !value : value))
+}
+
+function onRouteChange(value: QcRoute) {
+  if (controlledRoute.value) {
+    emit('update:route', value)
+    return
+  }
+  routeInner.value = value
+}
+
+function onApply() {
+  if (activeFactors.value.length === 0) return
+  emit('apply', {
+    groups: groups.value,
+    route: currentRoute.value,
+    sampleTotal: sampleTotal.value,
+    activeFactors: activeFactors.value,
+  })
+}
+</script>
+
+<template>
+  <div class="sg-modal fr">
+    <!-- header -->
+    <div class="sg-head">
+      <Icon :d="ICON.bolt" :size="18" />
+      <span class="sg-head__title">Group samples</span>
+      <span class="sg-head__sub">· {{ headerCount }} samples<template v-if="experimentLabel"> from {{ experimentLabel }}</template></span>
+      <div class="sg-head__spacer" />
+      <div ref="csvMenuRoot" class="fr-csv">
+        <button
+          type="button"
+          class="fr-upload"
+          aria-haspopup="menu"
+          :aria-expanded="csvMenuOpen"
+          @click="toggleCsvMenu"
+        >
+          <Icon :d="ICON.upload" :size="14" /> CSV <Icon :d="ICON.chev" :size="13" />
+        </button>
+        <div v-if="csvMenuOpen" class="fr-csv-menu" role="menu">
+          <button type="button" class="fr-csv-item" role="menuitem" @click="chooseUpload">
+            <Icon :d="ICON.upload" :size="14" /> Upload CSV
+          </button>
+          <button
+            type="button"
+            class="fr-csv-item"
+            role="menuitem"
+            :disabled="!canDownloadTemplate"
+            :aria-disabled="!canDownloadTemplate"
+            :title="canDownloadTemplate ? undefined : 'Load samples first'"
+            @click="chooseDownloadTemplate"
+          >
+            <Icon :d="ICON.download" :size="14" /> Download template
+          </button>
+          <button
+            type="button"
+            class="fr-csv-item"
+            role="menuitem"
+            :disabled="!canDownloadTemplate"
+            :aria-disabled="!canDownloadTemplate"
+            :title="canDownloadTemplate ? undefined : 'Load samples first'"
+            @click="chooseDownloadPrefilled"
+          >
+            <Icon :d="ICON.download" :size="14" /> Download pre-filled
+          </button>
+        </div>
+        <input
+          ref="fileInput"
+          type="file"
+          accept=".csv,.tsv,text/csv,text/tab-separated-values"
+          hidden
+          @change="onFileChange"
+        />
+      </div>
+      <div class="sg-mode" role="tablist" aria-label="Grouping mode">
+        <button type="button" class="sg-mode__btn sg-mode__btn--on" role="tab" :aria-selected="true">Auto</button>
+        <button type="button" class="sg-mode__btn" role="tab" :aria-selected="false" @click="emit('manual')">Manual</button>
+      </div>
+      <button class="sg-head__close" aria-label="Close" @click="emit('close')">
+        <Icon :d="ICON.close" :size="16" />
+      </button>
+    </div>
+
+    <div class="sg-body">
+      <!-- main -->
+      <div
+        class="sg-body__main"
+        @dragenter.prevent="onDragEnter"
+        @dragover.prevent
+        @dragleave.prevent="onDragLeave"
+        @drop.prevent="onDrop"
+      >
+        <div v-if="dragOver" class="fr-dropzone">
+          <Icon :d="ICON.upload" :size="22" />
+          <span>Drop CSV to load samples</span>
+        </div>
+        <div v-if="loading" class="fr-loading">
+          <LoadingSpinner size="md" label="Loading experiment metadata" />
+          <span>Loading experiment metadata…</span>
+        </div>
+        <div class="sg-lead">
+          <span class="sg-lead__q">Group by which fields?</span>
+          <span class="sg-lead__hint">
+            MINT read the structure of your sample names. Switch on the factors that define your groups —
+            replicate fields are detected and left off.
+          </span>
+        </div>
+
+        <div class="sg-recipe">
+          <div
+            v-for="(field, i) in fields"
+            :key="field.key"
+            class="sg-field"
+            :class="{ 'sg-field--on': on[i], 'fr-field--warn': field.rep && on[i] }"
+          >
+            <div class="fr-field__head">
+              <span class="sg-field__name">{{ field.key }}</span>
+              <span class="sg-field__role" :class="{ 'sg-field__role--rep': field.rep }">{{ field.role }}</span>
+            </div>
+            <button
+              class="sg-switch fr-switch"
+              :class="{ on: on[i] }"
+              role="switch"
+              :aria-checked="on[i]"
+              :aria-label="'Group by ' + field.key"
+              @click="toggle(i)"
+            />
+            <div class="sg-field__vals">{{ field.vals }}</div>
+          </div>
+        </div>
+
+        <!-- inline plain-english summary -->
+        <div v-if="summary.kind === 'mute'" class="sg-summary fr-summary--mute">
+          <span class="sg-summary__icon"><Icon :d="ICON.info" :size="16" /></span>
+          <span>Turn on at least one field to form groups.</span>
+        </div>
+        <div v-else-if="summary.kind === 'warn'" class="sg-summary sg-summary--warn">
+          <span class="sg-summary__icon"><Icon :d="ICON.warn" :size="16" /></span>
+          <span>
+            Including <b>{{ repField?.key ?? 'Replicate' }}</b> makes every sample unique —
+            <b>{{ baseGroups.length }} groups of 1</b>. Turn it off to keep <code>{{ repRange }}</code> together.
+          </span>
+        </div>
+        <div v-else class="sg-summary">
+          <span class="sg-summary__icon"><Icon :d="ICON.info" :size="16" /></span>
+          <span>
+            Grouping by <b>{{ activeFactors.join(' × ') }}</b> →
+            <b>{{ baseGroups.length }} groups<template v-if="uniform"> of {{ counts[0] }}</template></b>.
+            Replicates kept together.
+          </span>
+        </div>
+      </div>
+
+      <!-- rail -->
+      <div class="sg-body__side">
+        <div class="sg-preview__head">
+          Resulting groups
+          <span class="sg-preview__count">{{ groups.length }} groups · {{ groupedSampleTotal }} samples</span>
+        </div>
+        <div class="sg-grouplist">
+          <div v-if="groups.length === 0" class="fr-empty">No groups yet — pick a field to start.</div>
+          <div v-for="group in groups" v-else :key="group.name" class="sg-group">
+            <span class="sg-dot" :style="{ background: group.color }" />
+            <span class="sg-group__name">{{ group.name }}</span>
+            <span
+              class="sg-group__bar"
+              :style="{ width: (MAX_BAR * group.count) / maxCount + 'px', '--g': group.color }"
+            />
+            <span class="sg-group__count">{{ group.count }}</span>
+          </div>
+        </div>
+
+        <div class="sg-qc">
+          <div class="sg-qc__head">
+            <span class="sg-qc__title">Quality control</span>
+            <select
+              class="sg-qc__route"
+              :value="currentRoute"
+              @change="onRouteChange(($event.target as HTMLSelectElement).value as QcRoute)"
+            >
+              <option>Overlay only</option>
+              <option>Exclude</option>
+              <option>Mix into groups</option>
+            </select>
+          </div>
+          <span
+            v-if="qcChip"
+            class="sg-qc__chip"
+            :class="{ 'fr-qc__chip--off': currentRoute === 'Exclude' }"
+          >
+            <span class="sg-dot" :style="{ background: qcColor }" />{{ qcChip.name }} ×{{ qcChip.count }}
+          </span>
+        </div>
+      </div>
+    </div>
+
+    <div class="sg-foot">
+      <span class="sg-foot__hint">Applies to {{ sampleTotal }} samples{{ footHint }}</span>
+      <div class="sg-foot__spacer" />
+      <BaseButton variant="ghost" size="sm" @click="emit('cancel')">Cancel</BaseButton>
+      <BaseButton variant="primary" size="sm" :disabled="activeFactors.length === 0" @click="onApply">
+        <template #icon-left><Icon :d="ICON.check" :size="15" /></template>
+        Apply grouping
+      </BaseButton>
+    </div>
+  </div>
+</template>
+
+<style>
+@import '../styles/components/smart-group.css';
+</style>

package/src/components/SmartGroupManual.cohorts.ts

@@ -0,0 +1,112 @@
+/**
+ * Pure cohort logic for SmartGroupManual (the "manual" grouping mode).
+ *
+ * Mirrors the design prototype's selection-first model: a flat list of samples,
+ * each optionally assigned to a group / subgroup / sub-subgroup, derived into a
+ * three-level cohort tree for the right rail. Framework-free for unit testing.
+ */
+
+/** A sample with its (optional) manual cohort assignment. */
+export interface ManualSample {
+  name: string
+  group: string | null
+  sub: string | null
+  sub2: string | null
+  color: string | null
+}
+
+/** Which slice of the sample list is shown. */
+export type ManualFilter = 'all' | 'unassigned' | 'assigned'
+
+/** A sample paired with its index in the source list (so the UI can toggle it). */
+export interface ManualMatch {
+  sample: ManualSample
+  index: number
+}
+
+/** Second-level subgroup node: a sub-subgroup name → count map. */
+export interface CohortSubNode {
+  total: number
+  subs2: Map<string, number>
+}
+
+/** Top-level cohort node: colour, total, and its subgroups. */
+export interface CohortNode {
+  color: string | null
+  total: number
+  subs: Map<string, CohortSubNode>
+}
+
+/** The assignment values applied to a selection. */
+export interface CohortAssignment {
+  grp: string
+  sub: string
+  sub2: string
+  color: string
+}
+
+/**
+ * Build the group → subgroup → sub-subgroup tree from assigned samples.
+ * Unassigned samples are ignored. Missing sub/sub2 values collapse to `—`.
+ */
+export function buildCohortTree(samples: ManualSample[]): Map<string, CohortNode> {
+  const groups = new Map<string, CohortNode>()
+  for (const sample of samples) {
+    if (!sample.group) continue
+    if (!groups.has(sample.group)) {
+      groups.set(sample.group, { color: sample.color, total: 0, subs: new Map() })
+    }
+    const node = groups.get(sample.group)!
+    node.total++
+
+    const subKey = sample.sub || '—'
+    if (!node.subs.has(subKey)) {
+      node.subs.set(subKey, { total: 0, subs2: new Map() })
+    }
+    const subNode = node.subs.get(subKey)!
+    subNode.total++
+
+    const sub2Key = sample.sub2 || '—'
+    subNode.subs2.set(sub2Key, (subNode.subs2.get(sub2Key) ?? 0) + 1)
+  }
+  return groups
+}
+
+/** Filter the sample list by a case-insensitive name query and assignment state. */
+export function filterSamples(
+  samples: ManualSample[],
+  query: string,
+  filter: ManualFilter,
+): ManualMatch[] {
+  const q = query.trim().toLowerCase()
+  return samples
+    .map((sample, index) => ({ sample, index }))
+    .filter(({ sample }) => {
+      if (q && !sample.name.toLowerCase().includes(q)) return false
+      if (filter === 'unassigned') return !sample.group
+      if (filter === 'assigned') return !!sample.group
+      return true
+    })
+}
+
+/**
+ * Apply a cohort assignment to the selected sample indices, returning a new list.
+ * Blank subgroup / sub-subgroup values become `null`.
+ */
+export function assignSamples(
+  samples: ManualSample[],
+  selected: ReadonlySet<number>,
+  assignment: CohortAssignment,
+): ManualSample[] {
+  return samples.map((sample, index) =>
+    selected.has(index)
+      ? {
+          ...sample,
+          group: assignment.grp.trim(),
+          sub: assignment.sub.trim() || null,
+          sub2: assignment.sub2.trim() || null,
+          color: assignment.color,
+        }
+      : sample,
+  )
+}

package/src/components/SmartGroupManual.story.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+import SmartGroupManual from './SmartGroupManual.vue'
+import type { ManualDonePayload } from './SmartGroup.types'
+</script>
+
+<template>
+  <Story title="Lab/SmartGroupManual">
+    <Variant title="Playground" :init-state="() => ({ log: '' })">
+      <template #default="{ state }">
+        <div class="sg-story">
+          <div class="sg-story__stage">
+            <SmartGroupManual
+              @done="(r: ManualDonePayload) => (state.log = `${r.samples.filter(s => s.group).length} of ${r.samples.length} grouped`)"
+              @auto="state.log = 'back to smart grouping'"
+              @cancel="state.log = 'cancelled'"
+              @close="state.log = 'closed'"
+            />
+          </div>
+          <p v-if="state.log" class="sg-story__log">{{ state.log }}</p>
+        </div>
+      </template>
+    </Variant>
+
+    <Variant title="Empty (nothing seeded)">
+      <template #default>
+        <div class="sg-story">
+          <div class="sg-story__stage">
+            <SmartGroupManual :seed="{}" />
+          </div>
+        </div>
+      </template>
+    </Variant>
+  </Story>
+</template>
+
+<style scoped>
+.sg-story {
+  padding: 2rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  align-items: flex-start;
+}
+.sg-story__stage {
+  width: 980px;
+  height: 640px;
+  max-width: 100%;
+}
+.sg-story__log {
+  margin: 0;
+  font-family: 'Fira Code', monospace;
+  font-size: 0.8125rem;
+  color: var(--text-secondary, #64748b);
+}
+</style>