@morscherlab/mint-sdk 1.2.10 → 1.3.0-beta.10

package/src/components/SettingsModal.vue

@@ -15,8 +15,15 @@
  *   3. Appearance only — `showAppearance` (default true) renders the built-in
  *      theme / palette / table-density tab. Works alongside both modes above.
  *
- * Layout: `horizontal` (underline tabs, default) or `vertical` (sidebar rail
- * with optional icons + descriptions, recommended for 5+ groups).
+ * Layout: omitted (default) renders a sidebar rail split into "Plugin" and
+ * "Personal" (Appearance) sections when there are more than three groups, and
+ * stacks every group on one page otherwise. `vertical` always uses the rail;
+ * `horizontal` keeps the underline tab strip.
+ *
+ * Schema-driven settings also get a search across groups (label + hint), a
+ * modified-from-default marker with a per-row reset for every field with a
+ * non-null `defaultValue` (every `controls`/`model` field gets one), and a "Restore group defaults" action. Changes
+ * apply immediately; the default footer says so and closes with "Done".
  *
  * @example Recommended
  * ```vue
@@ -25,7 +32,11 @@
  */
 import { ref, computed, watch } from 'vue'
 import BaseModal from './BaseModal.vue'
+import BaseButton from './BaseButton.vue'
+import BaseInput from './BaseInput.vue'
+import SegmentedControl from './SegmentedControl.vue'
 import FormFieldRendererInternal from './internal/FormFieldRendererInternal.vue'
+import SettingsPaneHeadInternal from './internal/SettingsPaneHeadInternal.vue'
 import { useFormBuilder } from '../composables/useFormBuilder'
 import {
   controlsToSettingsSchema,
@@ -45,6 +56,7 @@ import {
   pickExistingRecordKeys,
   pickRecordKeys,
   recordValuesEqualForKeys,
+  valuesEqual,
 } from '../utils/formModelSync'
 import type {
   ThemeMode,
@@ -52,15 +64,18 @@ import type {
   TableDensity,
   ModalLayout,
   ModalTab,
+  SettingsGroup,
   SettingsTab,
   SettingsTabInput,
   SettingsModalLayout,
   SettingsModalSchema,
   SettingsUserType,
   FormEnhancements,
+  FormFieldSchema,
 } from '../types'
 import type { AccessControlled, PermissionUser } from '../permissions'
 import {
+  APPEARANCE_TAB,
   APPEARANCE_TAB_ID,
   buildFlatSettingsSchema,
   buildSettingsTabs,
@@ -75,6 +90,8 @@ interface Props {
   /** Manual tab descriptors. Ignored when `schema` is set (groups become tabs). */
   tabs?: SettingsTabInput[]
   showAppearance?: boolean
+  /** List Appearance before the other tabs and open on it. */
+  appearanceFirst?: boolean
   size?: 'md' | 'lg' | 'xl'
   layout?: SettingsModalLayout
   /** Declarative schema — fields auto-render via SDK form components. */
@@ -98,7 +115,7 @@ const props = withDefaults(defineProps<Props>(), {
   tabs: () => [],
   showAppearance: true,
   size: 'lg',
-  layout: 'horizontal',
+  layout: undefined,
   model: undefined,
 })
 
@@ -112,8 +129,6 @@ const settings = useSettingsStore()
 const auth = useAuthStore()
 const { user: platformUser } = usePlatformContext()
 
-const isVertical = computed(() => props.layout === 'vertical')
-
 const resolvedModel = computed<ControlModelBinding | undefined>(() => {
   return resolveControlModel(props.model)
 })
@@ -190,9 +205,14 @@ watch(
   { deep: true },
 )
 
+// Changes apply immediately; the footer confirms it once the user changed something.
+const applied = ref(false)
+
 watch(
   () => ({ ...builder.form.data }),
   (data) => {
+    // A reset to the parent's values (async load, schema swap) is not a user change.
+    if (!recordValuesEqualForKeys(data, resolvedValues.value, builderFieldNames())) applied.value = true
     if (settingsSchema.value) {
       emit('update:values', {
         ...resolvedValues.value,
@@ -220,28 +240,58 @@ const allTabs = computed<SettingsTab[]>(() => {
   const base: SettingsTab[] = settingsSchema.value
     ? visibleSchemaGroups.value.map(settingsGroupToTab)
     : manualTabs.value
-  return buildSettingsTabs(base, props.showAppearance)
+  return buildSettingsTabs(base, props.showAppearance, props.appearanceFirst)
 })
 
 const activeTab = ref(allTabs.value[0]?.id || APPEARANCE_TAB_ID)
 
+/** Above this many plugin groups the default layout switches from one stacked page to the rail. */
+const STACKED_GROUP_LIMIT = 3
+
 // BaseModal owns the tab chrome: 'vertical' keeps its public name and maps to
 // the shell rail; horizontal maps to the shell strip (plain when single-tab).
 const baseLayout = computed<ModalLayout>(() => {
-  if (isVertical.value) return 'rail'
-  return allTabs.value.length > 1 ? 'tabs' : 'plain'
+  if (props.layout === 'vertical') return 'rail'
+  if (props.layout === 'horizontal') return allTabs.value.length > 1 ? 'tabs' : 'plain'
+  const pluginTabCount = settingsSchema.value ? visibleSchemaGroups.value.length : manualTabs.value.length
+  return pluginTabCount > STACKED_GROUP_LIMIT ? 'rail' : 'plain'
 })
+const isRail = computed(() => baseLayout.value === 'rail')
+const isStacked = computed(() => baseLayout.value === 'plain')
+
+const query = ref('')
+const searchTerm = computed(() => query.value.trim().toLowerCase())
+const isSearching = computed(() => isSchemaDriven.value && searchTerm.value !== '')
 
 const modalTabs = computed<ModalTab[]>(() =>
-  allTabs.value.map((tab) => ({
-    id: tab.id,
-    label: tab.label,
-    icon: tab.icon,
-    description: tab.description,
-    meta: tab.meta,
-  })),
+  allTabs.value.map((tab) => {
+    const group = visibleSchemaGroups.value.find((g) => g.id === tab.id)
+    const modified = group ? modifiedCount(group) : 0
+    return {
+      id: tab.id,
+      label: tab.label,
+      icon: tab.icon,
+      description: tab.description,
+      meta: group ? (modified ? String(modified) : undefined) : tab.meta,
+      // Sections only split plugin groups from Appearance; without it there is nothing to split.
+      section: props.showAppearance ? (tab.id === APPEARANCE_TAB_ID ? 'Personal' : tab.section ?? 'Plugin') : undefined,
+    }
+  }),
 )
 
+function selectTab(id: string) {
+  activeTab.value = id
+  query.value = ''
+}
+
+function handleSearchKeydown(event: KeyboardEvent) {
+  // First Escape clears the search; the next one closes the modal.
+  if (event.key === 'Escape' && query.value) {
+    event.stopPropagation()
+    query.value = ''
+  }
+}
+
 // If the active tab vanishes (group hidden by condition), drop back to the first available.
 watch(allTabs, (tabs) => {
   if (!tabs.some((t) => t.id === activeTab.value)) {
@@ -253,15 +303,91 @@ const activeGroup = computed(() =>
   visibleSchemaGroups.value.find((g) => g.id === activeTab.value),
 )
 
-const activeGroupVisibleFields = computed(() => {
-  if (!activeGroup.value) return []
-  return activeGroup.value.fields.filter((f) => builder.isFieldVisible(f.name))
+function visibleFields(group: SettingsGroup): FormFieldSchema[] {
+  return group.fields.filter((f) => builder.isFieldVisible(f.name))
+}
+
+/**
+ * Modified = differs from the field's own `defaultValue`. A field without one, or with a `null`
+ * default (a secret, or an optional setting), never is: restoring `null` would clear a stored value.
+ */
+function isModified(field: FormFieldSchema): boolean {
+  return field.defaultValue != null
+    && !valuesEqual((builder.form.data as Record<string, unknown>)[field.name], field.defaultValue)
+}
+
+function modifiedCount(group: SettingsGroup): number {
+  return visibleFields(group).filter(isModified).length
+}
+
+function resetField(field: FormFieldSchema) {
+  builder.form.setFieldValue(field.name, field.defaultValue)
+}
+
+function restoreGroup(group: SettingsGroup | undefined) {
+  if (group) visibleFields(group).filter(isModified).forEach(resetField)
+}
+
+function isBooleanField(field: FormFieldSchema): boolean {
+  return field.type === 'checkbox' || field.type === 'toggle'
+}
+
+/** Booleans are always toggles inside settings rows; their hint is printed under the row, not in a tooltip. */
+function settingsField(field: FormFieldSchema): FormFieldSchema {
+  return isBooleanField(field) ? { ...field, type: 'toggle', hint: undefined } : field
+}
+
+interface SettingsRow {
+  field: FormFieldSchema
+  group: SettingsGroup
+}
+
+const searchResults = computed<SettingsRow[]>(() => {
+  if (!isSearching.value) return []
+  return visibleSchemaGroups.value.flatMap((group) =>
+    visibleFields(group)
+      .filter((field) => [field.label, field.hint, group.label].join(' ').toLowerCase().includes(searchTerm.value))
+      .map((field) => ({ field, group })),
+  )
 })
 
-const themeOptions: { value: ThemeMode; label: string }[] = [
-  { value: 'light', label: 'Light' },
-  { value: 'dark', label: 'Dark' },
-  { value: 'system', label: 'System' },
+const resultCount = computed(() =>
+  `${searchResults.value.length} result${searchResults.value.length === 1 ? '' : 's'}`,
+)
+
+/** What the pane renders: one list of search hits, every group (stacked) or the active group. */
+const paneSections = computed<{ key: string; group?: SettingsGroup; rows: SettingsRow[] }[]>(() => {
+  if (isSearching.value) {
+    return searchResults.value.length ? [{ key: 'search', rows: searchResults.value }] : []
+  }
+  const groups = isStacked.value
+    ? visibleSchemaGroups.value
+    : activeGroup.value ? [activeGroup.value] : []
+  return groups.map((group) => ({
+    key: group.id,
+    group,
+    rows: visibleFields(group).map((field) => ({ field, group })),
+  }))
+})
+
+const themeOptions: { value: ThemeMode; label: string; halves: ('light' | 'dark')[] }[] = [
+  { value: 'light', label: 'Light', halves: ['light'] },
+  { value: 'dark', label: 'Dark', halves: ['dark'] },
+  { value: 'system', label: 'System', halves: ['light', 'dark'] },
+]
+
+/** Five stops along the palette's primary → accent hue arc (shortest way round), as in the board. */
+function paletteSwatches(key: ColorPalette): string[] {
+  const [from, to] = colorPalettes[key].hues
+  const span = ((to - from + 540) % 360) - 180
+  const tone = key === 'pastel' ? '60% 72%' : '65% 48%'
+  return Array.from({ length: 5 }, (_, i) => `hsl(${Math.round(from + (span * i) / 4)} ${tone})`)
+}
+
+const densityPreviewRows = [
+  ['S-0012', '2.41', '12.5'],
+  ['S-0013', '7.90', '3.25'],
+  ['S-0014', '10.60', '0.80'],
 ]
 
 const densityOptions: { value: TableDensity; label: string }[] = [
@@ -270,6 +396,11 @@ const densityOptions: { value: TableDensity; label: string }[] = [
   { value: 'comfortable', label: 'Comfortable' },
 ]
 
+watch(
+  () => [settings.theme, settings.colorPalette, settings.tableDensity],
+  () => { applied.value = true },
+)
+
 function handleClose() {
   emit('update:modelValue', false)
   emit('close')
@@ -282,7 +413,7 @@ function builderFieldNames(): string[] {
 function canShowForCurrentUser(item: AccessControlled): boolean {
   return canAccessByPolicy(
     currentAccessUser.value,
-    item,
+    item.access,
     isAccessUserAuthenticated.value,
   )
 }
@@ -295,101 +426,229 @@ function canShowForCurrentUser(item: AccessControlled): boolean {
     :size="size"
     :layout="baseLayout"
     :tabs="modalTabs"
-    :active-tab="activeTab"
-    @update:active-tab="activeTab = $event"
+    :active-tab="isSearching ? '' : activeTab"
+    @update:active-tab="selectTab"
     @update:model-value="emit('update:modelValue', $event)"
     @close="handleClose"
   >
+    <template #header>
+      <div class="mint-settings-modal__header">
+        <h3 class="mint-modal__title">{{ title }}</h3>
+        <div v-if="isSchemaDriven" class="mint-settings-modal__search">
+          <svg class="mint-settings-modal__search-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true">
+            <circle cx="7" cy="7" r="4.5" /><path d="M10.5 10.5L14 14" />
+          </svg>
+          <BaseInput
+            :model-value="query"
+            type="search"
+            size="sm"
+            placeholder="Search settings"
+            aria-label="Search settings"
+            @update:model-value="query = String($event ?? '')"
+            @keydown="handleSearchKeydown"
+          />
+        </div>
+      </div>
+    </template>
+
+    <template v-if="isRail && isSchemaDriven" #pane-header="{ tab }">
+      <SettingsPaneHeadInternal v-if="isSearching" title="Search results" :count="resultCount" />
+      <SettingsPaneHeadInternal
+        v-else
+        :title="tab?.label ?? ''"
+        :description="tab?.description"
+        :modified-count="activeGroup ? modifiedCount(activeGroup) : undefined"
+        @restore="restoreGroup(activeGroup)"
+      />
+    </template>
+
     <!-- Body: the active pane only — tab strip / rail / footer are BaseModal's shell. -->
-    <div class="mint-settings-modal">
-      <div
-        v-if="isSchemaDriven && activeGroup"
-        class="mint-settings-modal__group-grid"
-        :style="{ '--mint-settings-cols': activeGroup.columns ?? 1 }"
-      >
-        <template v-for="field in activeGroupVisibleFields" :key="field.name">
-          <div :style="field.colSpan ? { gridColumn: `span ${field.colSpan}` } : undefined">
-            <slot
-              :name="`field:${field.name}`"
-              :field="field"
-              :form="builder.form"
-              :field-props="builder.form.getFieldProps(field.name)"
+    <div :class="['mint-settings-modal', { 'mint-settings-modal--schema': isSchemaDriven }]">
+      <template v-if="isSchemaDriven">
+        <SettingsPaneHeadInternal v-if="isSearching && !isRail" title="Search results" :count="resultCount" />
+        <section v-for="section in paneSections" :key="section.key" class="mint-settings-modal__group">
+          <SettingsPaneHeadInternal
+            v-if="section.group && !isRail"
+            :title="section.group.label"
+            :description="section.group.description"
+            :modified-count="modifiedCount(section.group)"
+            @restore="restoreGroup(section.group)"
+          />
+          <div
+            class="mint-settings-modal__group-grid"
+            :style="{ '--mint-settings-cols': section.group?.columns ?? 1 }"
+          >
+            <div
+              v-for="row in section.rows"
+              :key="row.field.name"
+              :class="['mint-settings-modal__row', { 'mint-settings-modal__row--modified': isModified(row.field) }]"
+              :style="row.field.colSpan ? { gridColumn: `span ${row.field.colSpan}` } : undefined"
             >
-              <FormFieldRendererInternal
-                :field="field"
-                :resolved-props="builder.getResolvedFieldProps(field)"
-                :form="builder.form"
-              />
-            </slot>
+              <span v-if="!section.group" class="mint-settings-modal__row-group">{{ row.group.label }}</span>
+              <div class="mint-settings-modal__row-field">
+                <slot
+                  :name="`field:${row.field.name}`"
+                  :field="row.field"
+                  :form="builder.form"
+                  :field-props="builder.form.getFieldProps(row.field.name)"
+                >
+                  <FormFieldRendererInternal
+                    :field="settingsField(row.field)"
+                    :resolved-props="builder.getResolvedFieldProps(settingsField(row.field))"
+                    :form="builder.form"
+                  />
+                </slot>
+                <p v-if="isBooleanField(row.field) && row.field.hint" class="mint-settings-modal__row-hint">
+                  {{ row.field.hint }}
+                </p>
+                <button
+                  v-if="isModified(row.field)"
+                  type="button"
+                  class="mint-settings-modal__reset"
+                  title="Restore default"
+                  :aria-label="`Restore default for ${row.field.label}`"
+                  @click="resetField(row.field)"
+                >
+                  <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                    <path d="M3 8a5 5 0 1 0 1.5-3.5M3 3v2.5h2.5" />
+                  </svg>
+                </button>
+              </div>
+            </div>
           </div>
-        </template>
-      </div>
+        </section>
+        <p v-if="isSearching && searchResults.length === 0" class="mint-settings-modal__empty">
+          No settings match "{{ query.trim() }}"
+        </p>
+      </template>
 
-      <template v-else-if="!isSchemaDriven">
-        <template v-for="tab in manualTabs" :key="tab.id">
-          <div v-show="activeTab === tab.id">
-            <slot :name="`tab-${tab.id}`" />
-          </div>
-        </template>
+      <template v-else>
+        <section
+          v-for="tab in manualTabs"
+          v-show="isStacked || activeTab === tab.id"
+          :key="tab.id"
+          class="mint-settings-modal__group"
+        >
+          <SettingsPaneHeadInternal v-if="isStacked" :title="tab.label" :description="tab.description" />
+          <slot :name="`tab-${tab.id}`" />
+        </section>
       </template>
 
-      <div v-if="showAppearance" v-show="activeTab === APPEARANCE_TAB_ID">
-        <div class="mint-settings-modal__section">
-          <div class="mint-settings-modal__section-label">Theme</div>
-          <div class="mint-settings-modal__option-group">
+      <section
+        v-if="showAppearance"
+        v-show="!isSearching && (isStacked || activeTab === APPEARANCE_TAB_ID)"
+        class="mint-settings-modal__group mint-settings-modal__appearance"
+      >
+        <SettingsPaneHeadInternal
+          v-if="isStacked"
+          :title="APPEARANCE_TAB.label"
+          :description="APPEARANCE_TAB.description"
+        />
+
+        <div class="mint-settings-modal__setting">
+          <div class="mint-settings-modal__setting-text">
+            <span class="mint-settings-modal__setting-label">Theme</span>
+            <span class="mint-settings-modal__setting-hint">Applies to this browser only</span>
+          </div>
+          <div class="mint-settings-modal__themes">
             <button
               v-for="opt in themeOptions"
               :key="opt.value"
               type="button"
-              :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.theme === opt.value }]"
+              :aria-pressed="settings.theme === opt.value"
+              :class="['mint-settings-modal__theme', { 'mint-settings-modal__theme--active': settings.theme === opt.value }]"
               @click="settings.theme = opt.value"
             >
-              {{ opt.label }}
+              <span class="mint-settings-modal__theme-preview" aria-hidden="true">
+                <span
+                  v-for="half in opt.halves"
+                  :key="half"
+                  :class="['mint-settings-modal__theme-half', `mint-settings-modal__theme-half--${half}`]"
+                >
+                  <span class="mint-settings-modal__theme-line" />
+                  <span class="mint-settings-modal__theme-card" />
+                </span>
+              </span>
+              <span class="mint-settings-modal__theme-label">
+                <span class="mint-settings-modal__theme-radio" aria-hidden="true" />
+                {{ opt.label }}
+              </span>
             </button>
           </div>
         </div>
 
-        <div class="mint-settings-modal__section">
-          <div class="mint-settings-modal__section-label">Color Palette</div>
-          <div class="mint-settings-modal__option-group">
+        <div class="mint-settings-modal__setting">
+          <div class="mint-settings-modal__setting-text">
+            <span class="mint-settings-modal__setting-label">Color palette</span>
+            <span class="mint-settings-modal__setting-hint">Primary and accent hues across the interface</span>
+          </div>
+          <div class="mint-settings-modal__palettes">
             <button
               v-for="(palette, key) in colorPalettes"
               :key="key"
               type="button"
-              :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.colorPalette === key }]"
+              :aria-pressed="settings.colorPalette === key"
+              :class="['mint-settings-modal__palette', { 'mint-settings-modal__palette--active': settings.colorPalette === key }]"
               @click="settings.colorPalette = key as ColorPalette"
             >
-              {{ palette.name }}
+              <span class="mint-settings-modal__swatches" aria-hidden="true">
+                <span
+                  v-for="color in paletteSwatches(key as ColorPalette)"
+                  :key="color"
+                  class="mint-settings-modal__swatch"
+                  :style="{ backgroundColor: color }"
+                />
+              </span>
+              <span class="mint-settings-modal__palette-name">{{ palette.name }}</span>
+              <svg class="mint-settings-modal__palette-check" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                <path d="M3.5 8.5l3 3 6-7" />
+              </svg>
             </button>
           </div>
         </div>
 
-        <div class="mint-settings-modal__section">
-          <div class="mint-settings-modal__section-label">Table Density</div>
-          <div class="mint-settings-modal__option-group">
-            <button
-              v-for="opt in densityOptions"
-              :key="opt.value"
-              type="button"
-              :class="['mint-settings-modal__option-btn', { 'mint-settings-modal__option-btn--active': settings.tableDensity === opt.value }]"
-              @click="settings.tableDensity = opt.value"
-            >
-              {{ opt.label }}
-            </button>
+        <div class="mint-settings-modal__setting mint-settings-modal__setting--inline">
+          <div class="mint-settings-modal__setting-text">
+            <span class="mint-settings-modal__setting-label">Table density</span>
+            <span class="mint-settings-modal__setting-hint">Adjusts row height in data tables</span>
+          </div>
+          <SegmentedControl
+            :model-value="settings.tableDensity"
+            :options="densityOptions"
+            size="sm"
+            @update:model-value="settings.tableDensity = $event as TableDensity"
+          />
+          <div
+            :class="['mint-settings-modal__density-preview', `mint-settings-modal__density-preview--${settings.tableDensity}`]"
+            aria-hidden="true"
+          >
+            <div class="mint-settings-modal__density-row mint-settings-modal__density-row--head">
+              <span>Sample</span><span>RT</span><span>IC50</span>
+            </div>
+            <div v-for="cells in densityPreviewRows" :key="cells[0]" class="mint-settings-modal__density-row">
+              <span>{{ cells[0] }}</span><span>{{ cells[1] }}</span><span>{{ cells[2] }}</span>
+            </div>
           </div>
-          <p class="mint-settings-modal__note">Adjusts row height in data tables.</p>
         </div>
 
         <slot name="appearance" />
-      </div>
+      </section>
     </div>
 
-    <template v-if="$slots.footer" #footer>
+    <template #footer>
       <slot
         name="footer"
         :values="builder.form.data"
         :close="handleClose"
-      />
+      >
+        <span class="mint-settings-modal__status" role="status">
+          <svg v-if="applied" class="mint-settings-modal__status-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <path d="M3.5 8.5l3 3 6-7" />
+          </svg>
+          {{ applied ? 'Applied · changes take effect immediately' : 'Changes take effect immediately' }}
+        </span>
+        <BaseButton class="mint-settings-modal__done" variant="primary" @click="handleClose">Done</BaseButton>
+      </slot>
     </template>
   </BaseModal>
 </template>

package/src/components/Skeleton.vue

@@ -28,41 +28,12 @@ const style = computed(() => {
   return s
 })
 
-const classes = computed(() => {
-  const base = ['bg-bg-hover']
-
-  switch (props.variant) {
-    case 'circular':
-      base.push('rounded-full')
-      if (!props.width && !props.height) {
-        base.push('w-10 h-10')
-      }
-      break
-    case 'rectangular':
-      base.push('rounded-none')
-      if (!props.height) base.push('h-24')
-      break
-    case 'rounded':
-      base.push('rounded-mint')
-      if (!props.height) base.push('h-24')
-      break
-    default:
-      base.push('rounded')
-      if (!props.height) base.push('h-4')
-      if (!props.width) base.push('w-full')
-  }
-
-  switch (props.animation) {
-    case 'pulse':
-      base.push('animate-pulse')
-      break
-    case 'wave':
-      base.push('skeleton-wave')
-      break
-  }
-
-  return base
-})
+const classes = computed(() => [
+  'mint-skeleton',
+  `mint-skeleton--${props.variant}`,
+  // pulse and wave both breathe (3e); the shimmer is gone.
+  props.animation === 'none' ? '' : 'skeleton-wave',
+])
 </script>
 
 <template>

package/src/components/SmartGroup.types.ts

@@ -15,7 +15,7 @@ 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). */
+  /** CSS colour value (e.g. `var(--mint-sample-1)`). */
   c: string
   /** Human-readable swatch key for the `aria-label`. */
   k: string
@@ -50,7 +50,7 @@ export interface SmartGroupFieldRecipeProps {
   initialRoute?: QcRoute
   /** Group colours, cycled in group order. */
   palette?: string[]
-  /** Colour used for the QC pool. */
+  /** Colour of the QC pool's count bar. The QC dot is always the neutral QC marker (3a). */
   qcColor?: string
 
   // ── Controlled mode (driven by AutoGroupModal over the useAutoGroup engine).

package/src/components/SmartGroupFieldRecipe.groups.ts

@@ -28,6 +28,9 @@ export interface FieldRecipeGroup {
   color: string
 }
 
+/** Name of the QC pool group appended by `appendQcGroup`. */
+export const QC_POOL_NAME = 'QC_Pool'
+
 /** How QC samples are routed relative to the biological groups. */
 export type QcRoute = 'Overlay only' | 'Exclude' | 'Mix into groups'
 
@@ -86,7 +89,7 @@ export function appendQcGroup(
   qcCount = 3,
 ): FieldRecipeGroup[] {
   if (route === 'Mix into groups') {
-    return [...groups, { name: 'QC_Pool', count: qcCount, color: qcColor }]
+    return [...groups, { name: QC_POOL_NAME, count: qcCount, color: qcColor }]
   }
   return groups
 }