@morscherlab/mint-sdk 1.5.0-beta.6 → 1.5.0-beta.8

package/src/components/AppTopBar.story.vue

@@ -10,6 +10,7 @@ import type {
   PillNavItem,
   PageSelectorItem,
   PluginInfo,
+  TopBarAction,
   TopBarJob,
 } from '../types'
 
@@ -87,6 +88,17 @@ const samplePluginWithSubtitle: PluginInfo = {
   api_prefix: '/api/ms-planner',
 }
 
+// Page icons are Lucide names; plugin buttons come from spec.actions (two show, the rest in More).
+const sampleIconPages: PageSelectorItem[] = [
+  { id: 'monitor', label: 'Monitor', icon: 'activity' },
+  { id: 'planner', label: 'Planner', icon: 'calendar-days' },
+  { id: 'queue', label: 'Queue', icon: 'list-ordered' },
+]
+const sampleActions: TopBarAction[] = [
+  { id: 'status', label: 'Database ready', icon: 'database', dot: 'success', onSelect: () => {} },
+  { id: 'export', label: 'Export', icon: 'download', onSelect: () => {} },
+  { id: 'reindex', label: 'Reindex', onSelect: () => {} },
+]
 // The seed is module state: clear it when the variant unmounts.
 function seedIdentity({ app }: { app: App }) {
   providePluginIdentity({
@@ -109,7 +121,6 @@ function seedIdentity({ app }: { app: App }) {
         <AppTopBar
           :spec="{
             pills: samplePillNav.slice(1, 3),
-            themeToggle: true,
             homePath: '',
             standaloneLabel: false,
           }"
@@ -127,7 +138,7 @@ function seedIdentity({ app }: { app: App }) {
     <Variant title="Refresh · Workspace">
       <div style="padding: 2rem; background: var(--bg-primary); min-height: 22rem;">
         <AppTopBar
-          :spec="{ pills: samplePillNav, themeToggle: true, homePath: '' }"
+          :spec="{ pills: samplePillNav, homePath: '' }"
           :page-selector="samplePageSelector"
           current-page-selector-id="workspace"
           pill="workspace"
@@ -139,7 +150,7 @@ function seedIdentity({ app }: { app: App }) {
       <div style="padding: 2rem; background: var(--bg-primary); min-height: 12rem;">
         <ExperimentProvider>
           <AppTopBar
-            :spec="{ pills: samplePillNav, themeToggle: true, homePath: '' }"
+            :spec="{ pills: samplePillNav, homePath: '' }"
             :page-selector="samplePageSelector"
             current-page-selector-id="experiments"
             pill="experiments"
@@ -152,7 +163,7 @@ function seedIdentity({ app }: { app: App }) {
       <div style="padding: 2rem; background: var(--bg-primary); min-height: 12rem;">
         <ExperimentProvider :plugin="samplePlugin">
           <AppTopBar
-            :spec="{ pills: samplePillNav, themeToggle: true, homePath: '' }"
+            :spec="{ pills: samplePillNav, homePath: '' }"
             :page-selector="samplePluginPages"
             current-page-selector-id="peaks"
             pill="experiments"
@@ -168,7 +179,7 @@ function seedIdentity({ app }: { app: App }) {
           <AppTopBar
             v-for="row in runSlotJobs"
             :key="row.label"
-            :spec="{ themeToggle: true, homePath: '' }"
+            :spec="{ homePath: '' }"
             :page-selector="samplePluginPages"
             current-page-selector-id="peaks"
             :job="row.job"
@@ -193,7 +204,7 @@ function seedIdentity({ app }: { app: App }) {
         </div>
         <ExperimentProvider :plugin="samplePlugin" :save="false">
           <AppTopBar
-            :spec="{ themeToggle: true, homePath: '' }"
+            :spec="{ homePath: '' }"
             :page-selector="samplePluginPages"
             current-page-selector-id="peaks"
             :job="runSlotJobs[liveRow].job"
@@ -205,7 +216,7 @@ function seedIdentity({ app }: { app: App }) {
     <Variant title="Refresh · Admin">
       <div style="padding: 2rem; background: var(--bg-primary); min-height: 12rem;">
         <AppTopBar
-          :spec="{ pills: samplePillNav, themeToggle: true, homePath: '' }"
+          :spec="{ pills: samplePillNav, homePath: '' }"
           :page-selector="samplePageSelector"
           current-page-selector-id="admin"
           pill="admin"
@@ -217,7 +228,7 @@ function seedIdentity({ app }: { app: App }) {
       <div style="padding: 2rem; background: var(--bg-primary); min-height: 12rem;">
         <ExperimentProvider :preselect="false">
           <AppTopBar
-            :spec="{ pills: samplePillNav, themeToggle: true, homePath: '' }"
+            :spec="{ pills: samplePillNav, homePath: '' }"
             :page-selector="samplePageSelector"
             current-page-selector-id="workspace"
             pill="workspace"
@@ -232,7 +243,6 @@ function seedIdentity({ app }: { app: App }) {
         <AppTopBar
           :spec="{
             pills: samplePillNav.slice(1, 3),
-            themeToggle: true,
             homePath: '',
             standaloneLabel: false,
           }"
@@ -256,7 +266,6 @@ function seedIdentity({ app }: { app: App }) {
             :spec="{
               variant: state.variant,
               logo: state.showLogo,
-              themeToggle: state.showThemeToggle,
               homePath: state.homePath,
             }"
             :title="state.title"
@@ -274,7 +283,6 @@ function seedIdentity({ app }: { app: App }) {
           :options="variants.map(v => ({ label: v, value: v }))"
         />
         <HstCheckbox v-model="state.showLogo" title="Show Logo" />
-        <HstCheckbox v-model="state.showThemeToggle" title="Show Theme Toggle" />
         <HstText v-model="state.homePath" title="Home Path" />
       </template>
     </Variant>
@@ -282,7 +290,7 @@ function seedIdentity({ app }: { app: App }) {
     <Variant title="Base · Title + Subtitle">
       <div style="padding: 2rem;">
         <AppTopBar
-          :spec="{ themeToggle: true }"
+          :spec="{}"
           title="Dose-Response Analysis"
           subtitle="Experiment EXP-2024-001"
         />
@@ -306,7 +314,7 @@ function seedIdentity({ app }: { app: App }) {
     <Variant title="Navigation · Page selector">
       <div style="padding: 2rem;">
         <AppTopBar
-          :spec="{ themeToggle: true, homePath: '' }"
+          :spec="{ homePath: '' }"
           title="Results"
           :page-selector="samplePageSelector"
           current-page-selector-id="plugins"
@@ -354,11 +362,28 @@ function seedIdentity({ app }: { app: App }) {
       <div style="padding: 2rem;">
         <ExperimentProvider>
           <AppTopBar
-            :spec="{ themeToggle: true, homePath: '' }"
+            :spec="{ homePath: '' }"
             title="Analysis"
           />
         </ExperimentProvider>
       </div>
     </Variant>
+
+    <Variant title="Layout · Fixed tail and two rows">
+      <!-- The theme and settings buttons always close the bar. Below 1024px of bar width the
+           pills and the context group (experiment, plugin buttons) move to a second row. -->
+      <div style="padding: 2rem; background: var(--bg-primary); display: grid; gap: 1rem;">
+        <ExperimentProvider v-for="width in ['1360px', '1180px', '900px', '768px']" :key="width" :plugin="samplePlugin">
+          <div :style="{ width, maxWidth: '100%' }">
+            <AppTopBar
+              :spec="{ pills: samplePillNav.slice(0, 3), homePath: '', actions: sampleActions }"
+              :page-selector="sampleIconPages"
+              current-page-selector-id="monitor"
+              pill="workspace"
+            />
+          </div>
+        </ExperimentProvider>
+      </div>
+    </Variant>
   </Story>
 </template>

package/src/components/AppTopBar.vue

@@ -3,9 +3,15 @@
  * Full application top bar with brand logo, static plugin identity, page selector, centered pill nav, experiment popover, and an account slot.
  *
  * The `#icon` slot applies in standalone mode only; integrated branding comes from `Metadata.icon`.
+ *
+ * The order is fixed: identity or page selector, pills, the context group (standalone badge, run slot,
+ * onboarding, `spec.actions`), then the tail: theme toggle, settings, `#account`. Below 1024px of bar
+ * width the pills and the context group move to a second row. Inside a responsive AppLayout the bar
+ * holds the sidebar drawer button.
  */
 import { ref, computed, inject, defineAsyncComponent, onMounted, onBeforeUnmount, toValue, useSlots, watch, type Component } from 'vue'
 import type {
+  ActionMenuItem,
   PillNavOption,
   PillNavItem,
   PillNavItemInput,
@@ -13,7 +19,13 @@ import type {
   PageSelectorItemInput,
   PluginWorkspaceTopBarSpec,
   SettingsTab,
+  TopBarSettingsConfig,
 } from '../types/components'
+import { APP_LAYOUT_SIDEBAR_KEY } from '../composables/appLayoutSidebar'
+import { warnDeprecatedOnce } from '../utils/deprecation'
+import ActionMenu from './ActionMenu.vue'
+import BaseButton from './BaseButton.vue'
+import LucideIconInternal from './internal/LucideIconInternal.vue'
 import { normalizeItemInput } from '../utils/items'
 import { applySpecDefaults } from '../composables/componentSpecs'
 import ThemeToggle from './ThemeToggle.vue'
@@ -27,7 +39,8 @@ import { useOnboarding } from '../composables/useOnboarding'
 import { pluginIdentity } from '../composables/pluginIdentity'
 import { integrationHost } from '../utils/integrationHost'
 import { trackTopBarForToasts } from './AppTopBar.toastOffset'
-import { CircleAlert, CircleCheck, CircleX, ListChecks, LoaderCircle } from 'lucide-vue-next'
+import { trackTopBarCompact } from './AppTopBar.compact'
+import { CircleAlert, CircleCheck, CircleX, ListChecks, Ellipsis, LoaderCircle, Menu, X } from 'lucide-vue-next'
 import type { JobStatus, TopBarJob } from '../types/jobs'
 import type { Tone } from '../types/components'
 
@@ -67,12 +80,23 @@ const config = computed(() => applySpecDefaults({
   variant: 'card',
   homePath: '/',
   logo: true,
-  themeToggle: false,
-  settings: false,
   standaloneLabel: 'Standalone',
 }, props.spec))
-const settingsConfig = computed(() => toValue(config.value.settings) || undefined)
-const showSettings = computed(() => settingsConfig.value !== undefined)
+// The theme and settings buttons always close the bar; without settings the modal has only Appearance.
+const settingsConfig = computed<TopBarSettingsConfig>(() => toValue(config.value.settings) || {})
+
+/** Plugin buttons: two show, the rest fold into the More menu. */
+const MAX_VISIBLE_ACTIONS = 2
+const visibleActions = computed(() => (config.value.actions ?? []).slice(0, MAX_VISIBLE_ACTIONS))
+const overflowActions = computed(() => (config.value.actions ?? []).slice(MAX_VISIBLE_ACTIONS))
+const overflowMenuItems = computed<ActionMenuItem[]>(() =>
+  overflowActions.value.map(({ id, label, disabled, loading }) => ({ id, label, disabled: disabled || loading })),
+)
+function selectOverflowAction(item: ActionMenuItem) {
+  overflowActions.value.find(action => action.id === item.id)?.onSelect()
+}
+
+const drawer = inject(APP_LAYOUT_SIDEBAR_KEY, null)
 
 const SettingsModal = defineAsyncComponent(() => import('./SettingsModal.vue'))
 const ExperimentPopover = defineAsyncComponent(() => import('./ExperimentPopover.vue'))
@@ -90,10 +114,18 @@ const emit = defineEmits<{
 const settingsOpen = ref(false)
 const headerEl = ref<HTMLElement | null>(null)
 let untrackToastOffset: (() => void) | undefined
+// Labels give way to icons when the content does not fit (AppTopBar.compact.ts).
+const compact = ref(false)
+let compactTracker: ReturnType<typeof trackTopBarCompact> | undefined
 onMounted(() => {
-  if (headerEl.value) untrackToastOffset = trackTopBarForToasts(headerEl.value)
+  if (!headerEl.value) return
+  untrackToastOffset = trackTopBarForToasts(headerEl.value)
+  compactTracker = trackTopBarCompact(headerEl.value, compact)
+})
+onBeforeUnmount(() => {
+  untrackToastOffset?.()
+  compactTracker?.stop()
 })
-onBeforeUnmount(() => untrackToastOffset?.())
 const { integrated: isIntegrated, plugin } = usePlatform()
 const isStandalone = computed(() => !isIntegrated.value)
 const appExperiment = inject(APP_EXPERIMENT_KEY, null)
@@ -139,6 +171,19 @@ const JOB_ICONS: Record<JobStatus, Component> = {
 }
 
 const slots = useSlots()
+if (props.spec.themeToggle !== undefined) {
+  warnDeprecatedOnce('topbar.themeToggle', 'AppTopBar spec.themeToggle is ignored: the theme toggle always shows. Remove it; it is removed in 2.0.')
+}
+for (const name of ['nav', 'center', 'actions', 'page-selector-icon', 'page-selector-item-icon'] as const) {
+  if (slots[name]) {
+    warnDeprecatedOnce(
+      `topbar.slot.${name}`,
+      name.startsWith('page-selector')
+        ? `AppTopBar #${name} is deprecated: give the page an icon (a Lucide name). It is removed in 2.0.`
+        : `AppTopBar #${name} is deprecated${name === 'actions' ? ': use spec.actions' : ''}. It is removed in 2.0.`,
+    )
+  }
+}
 // Standalone: the seeded identity (providePluginIdentity) stands in for a missing icon and title.
 const pluginIcon = computed(() => plugin.value?.icon || (slots.logo ? undefined : pluginIdentity.icon))
 const seeded = computed(() => isStandalone.value && !props.title && !props.subtitle)
@@ -168,6 +213,28 @@ const pageSelectorPluginName = computed(() =>
 // Platforms before 1.4 send no subtitle; the description fills line 2.
 const identitySubtitle = computed(() => plugin.value?.subtitle || plugin.value?.description)
 const hasPillNav = computed(() => !!config.value.pills?.length)
+const showStandaloneBadge = computed(() => config.value.standaloneLabel !== false && isStandalone.value)
+const showRunSlot = computed(() => showExperiment.value || props.job !== undefined || runSlotJoined.value)
+/** The context group: standalone badge, run slot, onboarding and plugin buttons. Below 1024px it is row 2. */
+// New content can need (or free) the label room again. One source per fact, so a job's
+// changing progress label (a new job object each update) does not re-measure.
+watch(
+  [
+    () => config.value.actions?.map(action => action.label).join(),
+    () => props.job === undefined,
+    () => props.job === null,
+    showExperiment,
+    () => config.value.pills?.length,
+  ],
+  () => compactTracker?.reset(),
+)
+const hasContext = computed(() =>
+  showStandaloneBadge.value
+  || showRunSlot.value
+  || !!config.value.actions?.length
+  || !!slots.actions
+  || !!onboarding?.enabled.value,
+)
 const hasTitleGroup = computed(
   () =>
     !hasPageSelector.value &&
@@ -202,11 +269,24 @@ const normalizedSettingsTabs = computed<SettingsTab[]>(() =>
     :class="[
       'mint-topbar',
       `mint-topbar--${config.variant}`,
+      { 'mint-topbar--compact': compact },
     ]"
   >
-    <div class="mint-topbar__container">
+    <!-- Below 1024px of bar width a bar with pills or context stacks into two rows (CSS container query). -->
+    <div :class="['mint-topbar__container', { 'mint-topbar__container--stackable': hasPillNav || $slots.center || hasContext }]">
       <!-- Left: brand -->
       <div class="mint-topbar__start">
+        <!-- Sidebar drawer button of the surrounding AppLayout; CSS shows it with the drawer (< 1024px). -->
+        <button
+          v-if="drawer"
+          type="button"
+          class="mint-topbar__icon-btn mint-topbar__sidebar-toggle"
+          :aria-label="drawer.open.value ? drawer.closeLabel.value : drawer.openLabel.value"
+          :aria-expanded="drawer.open.value"
+          @click="drawer.toggle()"
+        >
+          <component :is="drawer.open.value ? X : Menu" class="mint-topbar__icon-btn-icon" aria-hidden="true" />
+        </button>
         <div class="mint-topbar__brand">
           <a
             v-if="config.homePath && (config.homePath.startsWith('http') || config.homePath.startsWith('/'))"
@@ -348,104 +428,157 @@ const normalizedSettingsTabs = computed<SettingsTab[]>(() =>
         </slot>
       </div>
 
-      <!-- Right section -->
+      <!-- Right section: the context group, then the fixed tail -->
       <div class="mint-topbar__right">
-        <span v-if="config.standaloneLabel !== false && isStandalone" class="mint-topbar__standalone-badge">
-          {{ config.standaloneLabel }}
-        </span>
+        <div v-if="hasContext" class="mint-topbar__context">
+          <span v-if="showStandaloneBadge" class="mint-topbar__standalone-badge">
+            {{ config.standaloneLabel }}
+          </span>
 
-        <!-- Run slot: while a job shows, its progress takes the place of the experiment name and Save:
-             [ EXP-0142 ▾ | job ]. The idle Jobs button stands apart. -->
-        <div
-          v-if="showExperiment || job !== undefined || runSlotJoined"
-          :class="['mint-topbar__run-slot', { 'mint-topbar__run-slot--joined': runSlotJoined }]"
-          data-onboarding="topbar-run"
-        >
-          <ExperimentPopover
-            v-if="showExperiment && appExperiment"
-            v-bind="job ? { ...appExperiment.popover.value, showSave: false } : appExperiment.popover.value"
-            @select="appExperiment.openModal()"
-            @save="appExperiment.handleSave()"
-            @detach="appExperiment.handleDetach()"
-          />
-          <!-- Status words only, so a moving percent does not repeat. -->
-          <span class="mint-topbar__job-status" aria-live="polite">{{ job ? JOB_STATUS_TEXT[job.status] : '' }}</span>
-          <!-- appear: the slot can mount together with its first job; before-enter then joins it. -->
-          <Transition
-            name="mint-topbar-job"
-            mode="out-in"
-            appear
-            @before-enter="syncRunSlotJoined"
-            @after-leave="syncRunSlotJoined"
+          <!-- Run slot: while a job shows, its progress takes the place of the experiment name and Save:
+               [ EXP-0142 ▾ | job ]. The idle Jobs button stands apart. -->
+          <div
+            v-if="showRunSlot"
+            :class="['mint-topbar__run-slot', { 'mint-topbar__run-slot--joined': runSlotJoined }]"
+            data-onboarding="topbar-run"
           >
-            <button
-              v-if="job"
-              key="run"
-              type="button"
-              :class="['mint-topbar__job', `mint-topbar__job--${JOB_TONES[job.status]}`]"
-              :title="jobName"
-              :aria-label="jobName"
-              :aria-expanded="jobsOpen"
-              :aria-controls="jobsPanelId"
-              @click="emit('job-click')"
+            <ExperimentPopover
+              v-if="showExperiment && appExperiment"
+              v-bind="job ? { ...appExperiment.popover.value, showSave: false } : appExperiment.popover.value"
+              @select="appExperiment.openModal()"
+              @save="appExperiment.handleSave()"
+              @detach="appExperiment.handleDetach()"
+            />
+            <!-- Status words only, so a moving percent does not repeat. -->
+            <span class="mint-topbar__job-status" aria-live="polite">{{ job ? JOB_STATUS_TEXT[job.status] : '' }}</span>
+            <!-- appear: the slot can mount together with its first job; before-enter then joins it. -->
+            <Transition
+              name="mint-topbar-job"
+              mode="out-in"
+              appear
+              @before-enter="syncRunSlotJoined"
+              @after-leave="syncRunSlotJoined"
             >
-              <component
-                :is="JOB_ICONS[job.status]"
-                :class="['mint-topbar__job-icon', { 'mint-topbar__job-icon--spin': job.status === 'running' || job.status === 'queued' }]"
-                :size="14"
-                aria-hidden="true"
-              />
-              <span v-if="jobPercent != null" class="mint-topbar__job-bar" aria-hidden="true">
-                <span :style="{ width: `${jobPercent}%` }" />
-              </span>
-            </button>
+              <button
+                v-if="job"
+                key="run"
+                type="button"
+                :class="['mint-topbar__job', `mint-topbar__job--${JOB_TONES[job.status]}`]"
+                :title="jobName"
+                :aria-label="jobName"
+                :aria-expanded="jobsOpen"
+                :aria-controls="jobsPanelId"
+                @click="emit('job-click')"
+              >
+                <component
+                  :is="JOB_ICONS[job.status]"
+                  :class="['mint-topbar__job-icon', { 'mint-topbar__job-icon--spin': job.status === 'running' || job.status === 'queued' }]"
+                  :size="14"
+                  aria-hidden="true"
+                />
+                <span v-if="jobPercent != null" class="mint-topbar__job-bar" aria-hidden="true">
+                  <span :style="{ width: `${jobPercent}%` }" />
+                </span>
+              </button>
+              <button
+                v-else-if="job === null"
+                key="idle"
+                type="button"
+                class="mint-topbar__job mint-topbar__job--idle"
+                :aria-label="jobsDone ? `Jobs, ${jobsDone} completed` : 'Jobs'"
+                title="Jobs"
+                :aria-expanded="jobsOpen"
+                :aria-controls="jobsPanelId"
+                @click="emit('job-click')"
+              >
+                <ListChecks class="mint-topbar__job-icon" :size="14" aria-hidden="true" />
+                <span class="mint-topbar__job-label">Jobs</span>
+                <span v-if="jobsDone" class="mint-topbar__job-count" aria-hidden="true">{{ jobsDone }}</span>
+              </button>
+            </Transition>
+          </div>
+
+          <!-- Onboarding: checklist chip, Help button and tour layer, when the app provides onboarding -->
+          <AppTopBarOnboardingInternal v-if="onboarding?.enabled.value" :state="onboarding" />
+
+          <!-- Plugin buttons: spec.actions (two, then More); the deprecated #actions slot is clipped to a fixed width -->
+          <template v-for="action in visibleActions" :key="action.id">
             <button
-              v-else-if="job === null"
-              key="idle"
+              v-if="action.icon"
               type="button"
-              class="mint-topbar__job mint-topbar__job--idle"
-              :aria-label="jobsDone ? `Jobs, ${jobsDone} completed` : undefined"
-              :aria-expanded="jobsOpen"
-              :aria-controls="jobsPanelId"
-              @click="emit('job-click')"
+              class="mint-topbar__icon-btn"
+              :aria-label="action.label"
+              :title="action.title ?? action.label"
+              :disabled="action.disabled || action.loading"
+              :aria-busy="action.loading || undefined"
+              :data-action="action.id"
+              @click="action.onSelect()"
             >
-              <ListChecks class="mint-topbar__job-icon" :size="14" aria-hidden="true" />
-              <span class="mint-topbar__job-label">Jobs</span>
-              <span v-if="jobsDone" class="mint-topbar__job-count" aria-hidden="true">{{ jobsDone }}</span>
+              <LoaderCircle v-if="action.loading" class="mint-topbar__icon-btn-icon mint-topbar__job-icon--spin" aria-hidden="true" />
+              <LucideIconInternal v-else :name="action.icon" :size="16" />
+              <span v-if="action.dot" :class="['mint-topbar__icon-btn-dot', `mint-topbar__icon-btn-dot--${action.dot}`]" aria-hidden="true" />
             </button>
-          </Transition>
+            <BaseButton
+              v-else
+              variant="secondary"
+              size="sm"
+              :title="action.title"
+              :loading="action.loading"
+              :disabled="action.disabled"
+              :data-action="action.id"
+              @click="action.onSelect()"
+            >
+              {{ action.label }}
+            </BaseButton>
+          </template>
+          <ActionMenu
+            v-if="overflowMenuItems.length"
+            label="More actions"
+            :items="overflowMenuItems"
+            @select="selectOverflowAction"
+          >
+            <template #trigger="{ open, toggle, keydown }">
+              <button
+                type="button"
+                class="mint-topbar__icon-btn"
+                aria-label="More actions"
+                title="More actions"
+                aria-haspopup="menu"
+                :aria-expanded="open"
+                @click="toggle"
+                @keydown="keydown"
+              >
+                <Ellipsis class="mint-topbar__icon-btn-icon" aria-hidden="true" />
+              </button>
+            </template>
+          </ActionMenu>
+          <span v-if="$slots.actions" class="mint-topbar__legacy-actions"><slot name="actions" /></span>
         </div>
 
-        <slot name="actions" />
+        <div class="mint-topbar__tail">
+          <ThemeToggle size="sm" />
 
-        <!-- Onboarding: checklist chip, Help button and tour layer, when the app provides onboarding -->
-        <AppTopBarOnboardingInternal v-if="onboarding?.enabled.value" :state="onboarding" />
-
-        <!-- Theme toggle -->
-        <ThemeToggle v-if="config.themeToggle" size="sm" />
-
-        <!-- Settings -->
-        <button
-          v-if="showSettings"
-          type="button"
-          class="mint-topbar__settings-btn"
-          aria-label="Open settings"
-          data-onboarding="topbar-settings"
-          @click="settingsOpen = true"
-        >
-          <svg class="mint-topbar__settings-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-            <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>
+          <button
+            type="button"
+            class="mint-topbar__settings-btn"
+            aria-label="Open settings"
+            data-onboarding="topbar-settings"
+            @click="settingsOpen = true"
+          >
+            <svg class="mint-topbar__settings-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+              <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>
 
-        <!-- Account: the host application renders its account controls here -->
-        <slot name="account" />
+          <!-- Account: the host application renders its account controls here -->
+          <slot name="account" />
+        </div>
       </div>
     </div>
   </header>
 
   <SettingsModal
-    v-if="showSettings && settingsOpen"
+    v-if="settingsOpen"
     v-model:open="settingsOpen"
     :title="settingsConfig?.title"
     :tabs="normalizedSettingsTabs"

package/src/components/BaseModal.vue

@@ -1,6 +1,18 @@
 <script lang="ts">
 /** Open modals, oldest first; shared by every BaseModal instance. */
 const openModals: object[] = []
+/** Body overflow from before the first modal opened, restored when the last one closes. */
+let bodyOverflowBeforeLock = ''
+
+/** Body scroll follows the stack: locked while any modal is open. */
+function syncBodyScrollLock(wasEmpty: boolean) {
+  if (wasEmpty && openModals.length > 0) {
+    bodyOverflowBeforeLock = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+  } else if (!wasEmpty && openModals.length === 0) {
+    document.body.style.overflow = bodyOverflowBeforeLock
+  }
+}
 </script>
 
 <script setup lang="ts">
@@ -95,16 +107,14 @@ const containerRef = ref<HTMLElement | null>(null)
 
 useFocusTrap({ containerRef, active: toRef(props, 'open') })
 
-watch(() => props.open, (isOpen) => {
-  document.body.style.overflow = isOpen ? 'hidden' : ''
-})
-
 // Every open modal listens on document, so only the most recently opened one answers Escape.
 const self = {}
 watch(() => props.open, (isOpen) => {
+  const wasEmpty = openModals.length === 0
   const index = openModals.indexOf(self)
   if (isOpen && index === -1) openModals.push(self)
   if (!isOpen && index !== -1) openModals.splice(index, 1)
+  syncBodyScrollLock(wasEmpty)
 }, { immediate: true })
 
 // A control inside the modal that handles Escape (an open select) prevents the default first.
@@ -130,9 +140,10 @@ function handleOverlayClick(event: MouseEvent) {
 useEventListener(() => document, 'keydown', handleEscapeKeydown)
 
 onUnmounted(() => {
-  document.body.style.overflow = ''
+  const wasEmpty = openModals.length === 0
   const index = openModals.indexOf(self)
   if (index !== -1) openModals.splice(index, 1)
+  syncBodyScrollLock(wasEmpty)
 })
 </script>
 

package/src/components/ExperimentPopover.story.vue

@@ -282,8 +282,8 @@ function initPlayground() {
         />
       </div>
       <div style="text-align: center; font-size: 0.75rem; color: var(--text-muted); padding: 0 1rem 1rem;">
-        Green surface with check icon. Success state auto-dismisses after 3s in the component itself; the story
-        just shows the moment.
+        Green surface with check icon. Success state lasts while saveSuccessMessage is set; the parent clears it
+        (useAppExperiment after 3s). The story just shows the moment.
       </div>
     </Variant>