@morscherlab/mint-sdk 1.4.0-beta.2 → 1.4.0-beta.21

package/src/components/AppTopBar.vue

@@ -1,6 +1,10 @@
 <script setup lang="ts">
-/** Full application top bar with brand logo, static plugin identity, page selector, centered pill nav, experiment popover, and an account slot. */
-import { ref, computed, inject, defineAsyncComponent, onMounted, onBeforeUnmount, toValue, watch } from 'vue'
+/**
+ * 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`.
+ */
+import { ref, computed, inject, defineAsyncComponent, onMounted, onBeforeUnmount, toValue, useSlots, watch, type Component } from 'vue'
 import type {
   PillNavOption,
   PillNavItem,
@@ -15,11 +19,17 @@ import { applySpecDefaults } from '../composables/componentSpecs'
 import ThemeToggle from './ThemeToggle.vue'
 import AppTopBarPageSelectorInternal from './internal/AppTopBarPageSelectorInternal.vue'
 import AppTopBarPillNavInternal from './internal/AppTopBarPillNavInternal.vue'
+import AppTopBarOnboardingInternal from './internal/AppTopBarOnboardingInternal.vue'
 import PluginIcon from './PluginIcon.vue'
 import { usePlatform } from '../composables/usePlatform'
 import { APP_EXPERIMENT_KEY } from '../composables/useAppExperiment'
+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 type { JobStatus, TopBarJob } from '../types/jobs'
+import type { Tone } from '../types/components'
 
 interface Props {
   /** App or plugin title shown in the left title group when no page selector is present. */
@@ -34,10 +44,23 @@ interface Props {
   pageSelector?: PageSelectorItemInput[]
   /** Active id of the platform page selector. */
   currentPageSelectorId?: string
+  /**
+   * The viewer's own job, joined to the experiment chip. Omit it for no jobs control;
+   * `null` shows the idle Jobs button. Both emit `job-click`.
+   */
+  job?: TopBarJob | null
+  /** Completed jobs, shown as a small count on the idle Jobs button. Hidden when 0. */
+  jobsDone?: number
+  /** Whether the jobs panel is open; `aria-expanded` of the job control. */
+  jobsOpen?: boolean
+  /** DOM id of the jobs panel; `aria-controls` of the job control. */
+  jobsPanelId?: string
 }
 
 const props = withDefaults(defineProps<Props>(), {
   spec: () => ({}),
+  // No boolean cast: without a jobs panel the control has no aria-expanded.
+  jobsOpen: undefined,
 })
 
 const config = computed(() => applySpecDefaults({
@@ -61,6 +84,7 @@ const emit = defineEmits<{
   'pill-select': [item: PillNavItem]
   'pill-option-select': [option: PillNavOption, item: PillNavItem]
   'settings-values-change': [data: Record<string, unknown>]
+  'job-click': []
 }>()
 
 const settingsOpen = ref(false)
@@ -73,14 +97,53 @@ onBeforeUnmount(() => untrackToastOffset?.())
 const { integrated: isIntegrated, plugin } = usePlatform()
 const isStandalone = computed(() => !isIntegrated.value)
 const appExperiment = inject(APP_EXPERIMENT_KEY, null)
+const onboarding = useOnboarding()
 const canBindExperiment = computed(() => plugin.value?.plugin_type !== 'static')
+const showExperiment = computed(() => !!appExperiment && !isStandalone.value && canBindExperiment.value)
+// The border joins only once the job is on screen and stays until it has left,
+// so the name and the job never show at the same time.
+const runSlotJoined = ref(!!props.job)
+const JOB_STATUS_TEXT: Record<JobStatus, string> = {
+  queued: 'Job queued',
+  running: 'Job running',
+  awaiting_input: 'Job needs input',
+  completed: 'Job completed',
+  failed: 'Job failed',
+  cancelled: 'Job cancelled',
+}
+const jobPercent = computed(() =>
+  props.job?.percent == null ? null : Math.min(100, Math.max(0, Math.round(props.job.percent))),
+)
+const jobName = computed(() => props.job
+  ? (jobPercent.value != null ? `${props.job.label} ${jobPercent.value}%` : props.job.label)
+  : undefined)
+function syncRunSlotJoined() {
+  runSlotJoined.value = !!props.job
+}
 
-const pluginIcon = computed(() => {
-  const currentPlugin = plugin.value
-  return currentPlugin?.icon
-    ? { icon: currentPlugin.icon, color: currentPlugin.color }
-    : null
-})
+const JOB_TONES: Record<JobStatus, Tone> = {
+  queued: 'primary',
+  running: 'primary',
+  awaiting_input: 'warning',
+  completed: 'success',
+  failed: 'error',
+  cancelled: 'neutral',
+}
+const JOB_ICONS: Record<JobStatus, Component> = {
+  queued: LoaderCircle,
+  running: LoaderCircle,
+  awaiting_input: CircleAlert,
+  completed: CircleCheck,
+  failed: CircleX,
+  cancelled: CircleX,
+}
+
+const slots = useSlots()
+// 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)
+const titleText = computed(() => props.title || (seeded.value ? pluginIdentity.name : undefined))
+const subtitleText = computed(() => props.subtitle || (seeded.value ? pluginIdentity.subtitle : undefined))
 
 const hasPlatformPageSelector = computed(() =>
   props.pageSelector === undefined && (plugin.value?.nav_items?.length ?? 0) > 1,
@@ -98,20 +161,26 @@ watch(platformPageSelectorEl, (element, _previous, onCleanup) => {
 const identityName = computed(() =>
   isIntegrated.value && !hasPageSelector.value ? plugin.value?.display_name || plugin.value?.name : undefined,
 )
+/** The page selector crumb reads "<plugin> / <page>". */
+const pageSelectorPluginName = computed(() =>
+  isIntegrated.value ? plugin.value?.display_name || plugin.value?.name : props.title || pluginIdentity.name,
+)
+// 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 hasTitleGroup = computed(
   () =>
     !hasPageSelector.value &&
     !identityName.value &&
-    !!props.title &&
-    !!props.subtitle
+    !!titleText.value &&
+    !!subtitleText.value
 )
 const hasTitleOnly = computed(
   () =>
     !hasPageSelector.value &&
     !identityName.value &&
     !hasTitleGroup.value &&
-    !!props.title,
+    !!titleText.value,
 )
 const normalizedPageSelector = computed<PageSelectorItem[]>(() =>
   props.pageSelector?.map(normalizeItemInput) ?? [],
@@ -137,138 +206,137 @@ const normalizedSettingsTabs = computed<SettingsTab[]>(() =>
   >
     <div class="mint-topbar__container">
       <!-- Left: brand -->
-      <div class="mint-topbar__brand">
-        <a
-          v-if="config.homePath && (config.homePath.startsWith('http') || config.homePath.startsWith('/'))"
-          :href="config.homePath"
-          class="mint-topbar-home-link"
-        >
-          <span v-if="isIntegrated || $slots.icon || $slots.logo || pluginIcon || config.logo" class="mint-topbar__identity">
-            <PluginIcon
-              v-if="isIntegrated"
-              class="mint-topbar__plugin-icon"
-              :icon="plugin?.icon"
-              :color="plugin?.color"
-              size="topbar"
-              variant="solid"
-            />
-            <slot v-else name="icon">
+      <div class="mint-topbar__start">
+        <div class="mint-topbar__brand">
+          <a
+            v-if="config.homePath && (config.homePath.startsWith('http') || config.homePath.startsWith('/'))"
+            :href="config.homePath"
+            class="mint-topbar-home-link"
+          >
+            <span v-if="isIntegrated || $slots.icon || $slots.logo || pluginIcon || config.logo" class="mint-topbar__identity">
               <PluginIcon
-                v-if="pluginIcon"
+                v-if="isIntegrated"
                 class="mint-topbar__plugin-icon"
-                :icon="pluginIcon.icon"
-                :color="pluginIcon.color"
+                :icon="plugin?.icon"
                 size="topbar"
                 variant="solid"
               />
-              <slot v-else name="logo">
-                <div v-if="config.logo" class="mint-topbar__logo">
-                  <div class="mint-topbar__logo-icon">
-                    <span class="mint-topbar__logo-text">M</span>
+              <slot v-else name="icon">
+                <PluginIcon
+                  v-if="pluginIcon"
+                  class="mint-topbar__plugin-icon"
+                  :icon="pluginIcon"
+                  size="topbar"
+                  variant="solid"
+                />
+                <slot v-else name="logo">
+                  <div v-if="config.logo" class="mint-topbar__logo">
+                    <div class="mint-topbar__logo-icon">
+                      <span class="mint-topbar__logo-text">M</span>
+                    </div>
                   </div>
-                </div>
+                </slot>
               </slot>
-            </slot>
-          </span>
-        </a>
-        <router-link
-          v-else-if="config.homePath"
-          :to="config.homePath"
-          class="mint-topbar-home-link"
-        >
-          <span v-if="isIntegrated || $slots.icon || $slots.logo || pluginIcon || config.logo" class="mint-topbar__identity">
-            <PluginIcon
-              v-if="isIntegrated"
-              class="mint-topbar__plugin-icon"
-              :icon="plugin?.icon"
-              :color="plugin?.color"
-              size="topbar"
-              variant="solid"
-            />
-            <slot v-else name="icon">
+            </span>
+          </a>
+          <router-link
+            v-else-if="config.homePath"
+            :to="config.homePath"
+            class="mint-topbar-home-link"
+          >
+            <span v-if="isIntegrated || $slots.icon || $slots.logo || pluginIcon || config.logo" class="mint-topbar__identity">
               <PluginIcon
-                v-if="pluginIcon"
+                v-if="isIntegrated"
                 class="mint-topbar__plugin-icon"
-                :icon="pluginIcon.icon"
-                :color="pluginIcon.color"
+                :icon="plugin?.icon"
                 size="topbar"
                 variant="solid"
               />
-              <slot v-else name="logo">
-                <div v-if="config.logo" class="mint-topbar__logo">
-                  <div class="mint-topbar__logo-icon">
-                    <span class="mint-topbar__logo-text">M</span>
+              <slot v-else name="icon">
+                <PluginIcon
+                  v-if="pluginIcon"
+                  class="mint-topbar__plugin-icon"
+                  :icon="pluginIcon"
+                  size="topbar"
+                  variant="solid"
+                />
+                <slot v-else name="logo">
+                  <div v-if="config.logo" class="mint-topbar__logo">
+                    <div class="mint-topbar__logo-icon">
+                      <span class="mint-topbar__logo-text">M</span>
+                    </div>
                   </div>
-                </div>
+                </slot>
               </slot>
-            </slot>
-          </span>
-        </router-link>
-        <template v-else>
-          <span v-if="isIntegrated || $slots.icon || $slots.logo || pluginIcon || config.logo" class="mint-topbar__identity">
-            <PluginIcon
-              v-if="isIntegrated"
-              class="mint-topbar__plugin-icon"
-              :icon="plugin?.icon"
-              :color="plugin?.color"
-              size="topbar"
-              variant="solid"
-            />
-            <slot v-else name="icon">
+            </span>
+          </router-link>
+          <template v-else>
+            <span v-if="isIntegrated || $slots.icon || $slots.logo || pluginIcon || config.logo" class="mint-topbar__identity">
               <PluginIcon
-                v-if="pluginIcon"
+                v-if="isIntegrated"
                 class="mint-topbar__plugin-icon"
-                :icon="pluginIcon.icon"
-                :color="pluginIcon.color"
+                :icon="plugin?.icon"
                 size="topbar"
                 variant="solid"
               />
-              <slot v-else name="logo">
-                <div v-if="config.logo" class="mint-topbar__logo">
-                  <div class="mint-topbar__logo-icon">
-                    <span class="mint-topbar__logo-text">M</span>
+              <slot v-else name="icon">
+                <PluginIcon
+                  v-if="pluginIcon"
+                  class="mint-topbar__plugin-icon"
+                  :icon="pluginIcon"
+                  size="topbar"
+                  variant="solid"
+                />
+                <slot v-else name="logo">
+                  <div v-if="config.logo" class="mint-topbar__logo">
+                    <div class="mint-topbar__logo-icon">
+                      <span class="mint-topbar__logo-text">M</span>
+                    </div>
                   </div>
-                </div>
+                </slot>
               </slot>
-            </slot>
-          </span>
-        </template>
-      </div>
+            </span>
+          </template>
+        </div>
 
-      <!-- Left: static plugin identity (not a control) -->
-      <span v-if="identityName" class="mint-topbar__plugin-identity">
-        <span class="mint-topbar__plugin-name">{{ identityName }}</span>
-      </span>
+        <!-- Left: static plugin identity (not a control) -->
+        <span v-if="identityName" class="mint-topbar__plugin-identity">
+          <span class="mint-topbar__plugin-name">{{ identityName }}</span>
+          <span v-if="identitySubtitle" class="mint-topbar__plugin-subtitle">{{ identitySubtitle }}</span>
+        </span>
 
-      <!-- Left: page selector (the platform integration script renders the nav_items one) -->
-      <span v-if="hasPlatformPageSelector" ref="platformPageSelectorEl" class="mint-topbar__platform-page-selector" />
-      <AppTopBarPageSelectorInternal
-        v-else-if="hasPropPageSelector"
-        :pages="normalizedPageSelector"
-        :current-page-id="currentPageSelectorId"
-        @select="emit('page-selector-select', $event)"
-      >
-        <template v-if="$slots['page-selector-icon']" #icon="slotProps">
-          <slot name="page-selector-icon" v-bind="slotProps" />
-        </template>
-        <template v-if="$slots['page-selector-item-icon']" #item-icon="slotProps">
-          <slot name="page-selector-item-icon" v-bind="slotProps" />
-        </template>
-      </AppTopBarPageSelectorInternal>
+        <!-- Left: page selector (the platform integration script renders the nav_items one) -->
+        <span v-if="hasPlatformPageSelector" ref="platformPageSelectorEl" class="mint-topbar__platform-page-selector" data-onboarding="topbar-page-selector" />
+        <AppTopBarPageSelectorInternal
+          v-else-if="hasPropPageSelector"
+          data-onboarding="topbar-page-selector"
+          :pages="normalizedPageSelector"
+          :current-page-id="currentPageSelectorId"
+          :plugin-name="pageSelectorPluginName"
+          @select="emit('page-selector-select', $event)"
+        >
+          <template v-if="$slots['page-selector-icon']" #icon="slotProps">
+            <slot name="page-selector-icon" v-bind="slotProps" />
+          </template>
+          <template v-if="$slots['page-selector-item-icon']" #item-icon="slotProps">
+            <slot name="page-selector-item-icon" v-bind="slotProps" />
+          </template>
+        </AppTopBarPageSelectorInternal>
 
-      <!-- Left: title -->
-      <div v-if="hasTitleGroup" class="mint-topbar-title-group">
-        <span class="mint-topbar-title">{{ title }}</span>
-        <span class="mint-topbar-subtitle">{{ subtitle }}</span>
-      </div>
+        <!-- Left: title -->
+        <div v-if="hasTitleGroup" class="mint-topbar-title-group">
+          <span class="mint-topbar-title">{{ titleText }}</span>
+          <span class="mint-topbar-subtitle">{{ subtitleText }}</span>
+        </div>
 
-      <span v-else-if="hasTitleOnly" class="mint-topbar__title-only">{{ title }}</span>
+        <span v-else-if="hasTitleOnly" class="mint-topbar__title-only">{{ titleText }}</span>
 
-      <!-- Nav slot (inline, after brand/selector) -->
-      <slot name="nav" />
+        <!-- Nav slot (inline, after brand/selector) -->
+        <slot name="nav" />
+      </div>
 
       <!-- Center: pill nav -->
-      <div v-if="hasPillNav || $slots.center" class="mint-topbar__center">
+      <div v-if="hasPillNav || $slots.center" class="mint-topbar__center" data-onboarding="topbar-pills">
         <slot name="center">
           <AppTopBarPillNavInternal
             v-if="hasPillNav"
@@ -286,16 +354,73 @@ const normalizedSettingsTabs = computed<SettingsTab[]>(() =>
           {{ config.standaloneLabel }}
         </span>
 
-        <ExperimentPopover
-          v-if="appExperiment && !isStandalone && canBindExperiment"
-          v-bind="appExperiment.popover.value"
-          @select="appExperiment.openModal()"
-          @save="appExperiment.handleSave()"
-          @detach="appExperiment.handleDetach()"
-        />
+        <!-- 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"
+          >
+            <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` : undefined"
+              :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>
 
         <slot name="actions" />
 
+        <!-- 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" />
 
@@ -305,6 +430,7 @@ const normalizedSettingsTabs = computed<SettingsTab[]>(() =>
           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">

package/src/components/ArtifactSaveDialog.story.vue

@@ -6,6 +6,7 @@ import {
   type AnalysisArtifactDetail,
   type ArtifactSaveDialogPayload,
 } from '../types/analysisArtifactTypes'
+import type { ExperimentSummary } from '../types'
 
 // -- Mock JSON result a plugin would hand the dialog --
 const mockResult: Record<string, unknown> = {
@@ -47,6 +48,19 @@ const existingJsonArtifact: AnalysisArtifactDetail = {
   result: mockResult,
 }
 
+// -- Experiment shown in the strip at the top of the dialog --
+const mockExperiment: ExperimentSummary = {
+  id: 42,
+  experiment_code: 'EXP-042',
+  name: 'Doxorubicin dose response, HeLa',
+  status: 'ongoing',
+  experiment_type: 'dose_response',
+  created_at: '2026-07-01T09:00:00Z',
+  updated_at: '2026-07-02T14:00:00Z',
+  has_design_data: true,
+}
+const changeCount = ref(0)
+
 // -- Mock handlers standing in for a generated plugin-client call --
 const lastPayload = ref<ArtifactSaveDialogPayload | null>(null)
 
@@ -103,10 +117,15 @@ const isOpenError = ref(false)
             v-if="lastPayload"
             style="margin-top: 1rem; padding: 0.75rem 1rem; background: var(--bg-secondary, #f8fafc); border: 1px solid var(--border-color, #e2e8f0); border-radius: 6px; font-size: 0.75rem; overflow-x: auto;"
           >{{ formatPayload(lastPayload) }}</pre>
+          <p v-if="changeCount" style="margin-top: 0.5rem; font-size: 0.75rem;">
+            change-experiment emitted {{ changeCount }}×
+          </p>
 
           <ArtifactSaveDialog
             v-model:open="isOpenFile"
             :experiment-id="42"
+            :experiment="mockExperiment"
+            @change-experiment="changeCount++"
             :mode="state.mode"
             :result="mockResult"
             :default-artifact-key="state.defaultArtifactKey"
@@ -190,6 +209,8 @@ const isOpenError = ref(false)
         <ArtifactSaveDialog
           v-model:open="isOpenUpdateFile"
           :experiment-id="42"
+          :experiment="mockExperiment"
+          @change-experiment="changeCount++"
           :existing-artifact="existingFileArtifact"
           accept=".pdf"
           :save-handler="saveHandler"
@@ -237,6 +258,8 @@ const isOpenError = ref(false)
         <ArtifactSaveDialog
           v-model:open="isOpenUpdateJson"
           :experiment-id="42"
+          :experiment="mockExperiment"
+          @change-experiment="changeCount++"
           :existing-artifact="existingJsonArtifact"
           :result="mockResult"
           :save-handler="saveHandler"