@morscherlab/mint-sdk 1.2.0-beta.3 → 1.2.0-beta.4

package/src/components/SmartGroup.types.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared prop and payload types for the Smart Group — Full View components
+ * (`SmartGroupModal` shell + `SmartGroupFieldRecipe` auto mode +
+ * `SmartGroupManual` manual mode).
+ */
+import type {
+  FieldRecipeGroup,
+  QcRoute,
+  SmartGroupField,
+  SmartGroupSampleRecord,
+} from './SmartGroupFieldRecipe.groups'
+import type { ManualSample } from './SmartGroupManual.cohorts'
+
+export type SmartGroupMode = 'auto' | 'manual'
+
+/** A colour swatch in the manual assignment bar. */
+export interface ManualPaletteEntry {
+  /** CSS colour value (e.g. a `var(--grp-*)` reference). */
+  c: string
+  /** Human-readable swatch key for the `aria-label`. */
+  k: string
+}
+
+/** Initial cohort assignment for a sample, keyed by sample name. */
+export interface SmartGroupSeed {
+  group?: string
+  sub?: string
+  sub2?: string
+  color?: string
+}
+
+/** The QC summary chip shown in the rail when QC is not mixed into groups. */
+export interface FieldRecipeQcChip {
+  name: string
+  count: number
+}
+
+export interface SmartGroupFieldRecipeProps {
+  /** Sample records behind the experiment (one row per real sample). */
+  samples?: SmartGroupSampleRecord[]
+  /** Candidate grouping fields with role + value preview. */
+  fields?: SmartGroupField[]
+  /** Experiment code shown in the header; omitted from the subtitle when empty. */
+  experimentLabel?: string
+  /** Sample count shown in the header (real + QC). */
+  headerCount?: number
+  /** Which fields start switched on; defaults to every non-replicate field. */
+  initialOn?: boolean[]
+  /** Initial QC routing. */
+  initialRoute?: QcRoute
+  /** Group colours, cycled in group order. */
+  palette?: string[]
+  /** Colour used for the QC pool. */
+  qcColor?: string
+
+  // ── Controlled mode (driven by AutoGroupModal over the useAutoGroup engine).
+  // When these are provided the component renders the supplied data and emits
+  // events instead of running its own fixture grouping logic.
+  /** Controls the field toggles; when set, clicking a toggle emits `toggle`. */
+  enabled?: boolean[]
+  /**
+   * Per-card 1-based hierarchy layer (1 = the sample selector's major group),
+   * `null` for cards not grouped by. When set, reorder clicks emit `move`.
+   */
+  layers?: (number | null)[]
+  /** Pre-computed resulting groups; when set, the rail renders these directly. */
+  groups?: FieldRecipeGroup[]
+  /** QC summary chip to show in the rail; `null` hides it (e.g. when mixed). */
+  qcChip?: FieldRecipeQcChip | null
+  /** Controlled QC routing; when set, changing the select emits `update:route`. */
+  route?: QcRoute
+  /** QC sample count for the footer hint; defaults to `headerCount - samples`. */
+  qcCount?: number
+  /** Whether the template-download menu items are enabled (default `true`). */
+  canDownloadTemplate?: boolean
+  /** Show a loading state in the main body (e.g. while experiment data loads). */
+  loading?: boolean
+}
+
+export interface FieldRecipeApplyPayload {
+  groups: FieldRecipeGroup[]
+  route: QcRoute
+  sampleTotal: number
+  activeFactors: string[]
+}
+
+export interface SmartGroupManualProps {
+  /** Flat list of sample names to group. */
+  sampleNames?: string[]
+  /** Initial assignments keyed by sample name. */
+  seed?: Record<string, SmartGroupSeed>
+  /** Colour swatches offered in the assignment bar. */
+  palette?: ManualPaletteEntry[]
+}
+
+export interface ManualDonePayload {
+  samples: ManualSample[]
+}

package/src/components/SmartGroupFieldRecipe.groups.ts

@@ -0,0 +1,109 @@
+/**
+ * Pure grouping logic for SmartGroupFieldRecipe (the "auto" / Field Recipe mode).
+ *
+ * Mirrors the design prototype's live grouping engine: groups are formed by
+ * joining the values of whichever fields are switched on, in field order.
+ * Kept framework-free so it is unit-testable in isolation from the component.
+ */
+
+/** A field/factor the user can group by. */
+export interface SmartGroupField {
+  /** Column key as it appears in each sample record. */
+  key: string
+  /** Display role, e.g. `Factor` or `Replicate`. */
+  role: string
+  /** Comma-separated preview of the field's distinct values. */
+  vals: string
+  /** Whether this field is a replicate dimension (grouping by it shatters groups). */
+  rep: boolean
+}
+
+/** A single sample as a flat key → value record. */
+export type SmartGroupSampleRecord = Record<string, string>
+
+/** A resolved group in the live preview rail. */
+export interface FieldRecipeGroup {
+  name: string
+  count: number
+  color: string
+}
+
+/** How QC samples are routed relative to the biological groups. */
+export type QcRoute = 'Overlay only' | 'Exclude' | 'Mix into groups'
+
+/** Kind of inline summary callout to render. */
+export type FieldRecipeSummaryKind = 'mute' | 'warn' | 'info'
+
+export interface FieldRecipeSummary {
+  kind: FieldRecipeSummaryKind
+  /** Number of base (non-QC) groups the current toggles produce. */
+  groupCount: number
+}
+
+/**
+ * Build the ordered group list from whichever fields are switched on.
+ * Returns an empty list when no field is active. `layerOrder` (field indices
+ * in layer order) overrides the default field-order joining of the group name.
+ */
+export function computeFieldGroups(
+  samples: SmartGroupSampleRecord[],
+  fields: SmartGroupField[],
+  on: boolean[],
+  palette: string[],
+  layerOrder?: readonly number[],
+): FieldRecipeGroup[] {
+  const keys = layerOrder
+    ? layerOrder.filter(i => on[i]).map(i => fields[i].key)
+    : fields.filter((_, i) => on[i]).map(field => field.key)
+  if (keys.length === 0) return []
+
+  const order: string[] = []
+  const counts = new Map<string, number>()
+  for (const sample of samples) {
+    const name = keys.map(key => sample[key]).join('_')
+    if (!counts.has(name)) {
+      counts.set(name, 0)
+      order.push(name)
+    }
+    counts.set(name, (counts.get(name) ?? 0) + 1)
+  }
+
+  return order.map((name, index) => ({
+    name,
+    count: counts.get(name) ?? 0,
+    color: palette[index % palette.length],
+  }))
+}
+
+/**
+ * Append the QC pool group when QC is mixed into the biological groups.
+ * `Overlay only` and `Exclude` leave the group list untouched.
+ */
+export function appendQcGroup(
+  groups: FieldRecipeGroup[],
+  route: QcRoute,
+  qcColor: string,
+  qcCount = 3,
+): FieldRecipeGroup[] {
+  if (route === 'Mix into groups') {
+    return [...groups, { name: 'QC_Pool', count: qcCount, color: qcColor }]
+  }
+  return groups
+}
+
+/** Total samples the grouping applies to: QC is dropped only when excluded. */
+export function sampleTotalFor(route: QcRoute, realCount = 9, qcCount = 3): number {
+  return route === 'Exclude' ? realCount : realCount + qcCount
+}
+
+/** Decide which inline summary callout the Field Recipe should show. */
+export function fieldRecipeSummary(input: {
+  activeFactors: string[]
+  repOn: boolean
+  baseGroups: FieldRecipeGroup[]
+}): FieldRecipeSummary {
+  const groupCount = input.baseGroups.length
+  if (input.activeFactors.length === 0) return { kind: 'mute', groupCount }
+  if (input.repOn) return { kind: 'warn', groupCount }
+  return { kind: 'info', groupCount }
+}

package/src/components/SmartGroupFieldRecipe.story.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import SmartGroupFieldRecipe from './SmartGroupFieldRecipe.vue'
+import type { FieldRecipeApplyPayload } from './SmartGroup.types'
+</script>
+
+<template>
+  <Story title="Lab/SmartGroupFieldRecipe">
+    <Variant title="Playground" :init-state="() => ({ log: '' })">
+      <template #default="{ state }">
+        <div class="sg-story">
+          <div class="sg-story__stage">
+            <SmartGroupFieldRecipe
+              @apply="(r: FieldRecipeApplyPayload) => (state.log = `${r.groups.length} groups · ${r.route} · ${r.sampleTotal} samples`)"
+              @manual="state.log = 'switch to manual grouping'"
+              @cancel="state.log = 'cancelled'"
+              @close="state.log = 'closed'"
+              @csv-file="(f: File) => (state.log = `csv selected: ${f.name}`)"
+              @download-template="state.log = 'download blank template'"
+              @download-prefilled="state.log = 'download pre-filled template'"
+            />
+          </div>
+          <p v-if="state.log" class="sg-story__log">{{ state.log }}</p>
+        </div>
+      </template>
+    </Variant>
+
+    <Variant title="Replicate singleton trap">
+      <template #default>
+        <div class="sg-story">
+          <div class="sg-story__stage">
+            <SmartGroupFieldRecipe :initial-on="[true, true, true]" />
+          </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>