@morscherlab/mint-sdk 1.4.0-beta.15 → 1.4.0-beta.17

package/src/__tests__/components/AppTopBarOnboarding.test.ts

@@ -0,0 +1,160 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { computed, defineComponent, h, nextTick } from 'vue'
+import { createPinia } from 'pinia'
+import AppTopBar from '../../components/AppTopBar.vue'
+import { provideOnboarding, type OnboardingDefinition } from '../../composables/useOnboarding'
+
+vi.mock('../../composables/usePlatform', () => ({
+  usePlatform: vi.fn(() => ({
+    integrated: computed(() => false),
+    isAdmin: computed(() => true),
+    can: () => true,
+    plugin: computed(() => undefined),
+    user: computed(() => undefined),
+    theme: computed(() => 'system' as const),
+    features: computed(() => undefined),
+  })),
+}))
+
+const definition: OnboardingDefinition = {
+  tours: [{
+    id: 'intro',
+    title: 'Top bar tour',
+    steps: [
+      { id: 'settings', anchor: 'topbar-settings', title: 'Settings live here', body: 'Theme and palette.' },
+      { id: 'help', anchor: 'topbar-help', title: 'Help', body: 'Replay tours.', advanceOn: 'click' },
+    ],
+  }],
+  checklist: [{ id: 'create', title: 'Create an experiment' }],
+}
+
+enableAutoUnmount(afterEach)
+
+function mountTopBar(onboarding?: OnboardingDefinition) {
+  return mount(defineComponent({
+    setup() {
+      if (onboarding) provideOnboarding(onboarding, { appId: 'test', userId: 1, autoStart: false })
+      return () => h(AppTopBar, { spec: { settings: { tabs: [] } } })
+    },
+  }), { global: { plugins: [createPinia()], stubs: { 'router-link': true } }, attachTo: document.body })
+}
+
+const card = () => document.querySelector('.mint-onboarding__card')
+
+describe('AppTopBar onboarding', () => {
+  beforeEach(() => localStorage.clear())
+
+  it.each([
+    [undefined, false],
+    [definition, true],
+  ])('should show the Help button and checklist chip when onboarding is %s', (onboarding, shown) => {
+    const wrapper = mountTopBar(onboarding)
+
+    expect(wrapper.find('[data-onboarding="topbar-help"]').exists()).toBe(shown)
+    expect(wrapper.find('.mint-onboarding-help__chip').exists()).toBe(shown)
+    if (shown) expect(wrapper.find('.mint-onboarding-help__chip').text()).toContain('0/1')
+  })
+
+  it('should run a tour picked in the Help panel and end it with Escape', async () => {
+    const wrapper = mountTopBar(definition)
+    await wrapper.get('[data-onboarding="topbar-help"]').trigger('click')
+    const tour = [...document.querySelectorAll<HTMLElement>('.mint-menu-item')].find((item) => item.textContent?.trim() === 'Top bar tour')!
+    tour.click()
+    await flushPromises()
+
+    expect(document.querySelector('.mint-onboarding-help__panel')).toBeNull()
+    expect(card()?.getAttribute('role')).toBe('dialog')
+    expect(card()?.textContent).toContain('Settings live here')
+    expect(card()?.textContent).toContain('Next')
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }))
+    await nextTick()
+
+    expect(card()).toBeNull()
+    expect(JSON.parse(localStorage.getItem('mint.onboarding.test.1')!)).toEqual(
+      expect.arrayContaining(['step:intro/settings', 'step:intro/help']),
+    )
+  })
+
+  it('should focus the card, not the Next button, when a step opens', async () => {
+    const wrapper = mountTopBar(definition)
+    await wrapper.get('[data-onboarding="topbar-help"]').trigger('click')
+    ;[...document.querySelectorAll<HTMLElement>('.mint-menu-item')].find((item) => item.textContent?.trim() === 'Top bar tour')!.click()
+    await flushPromises()
+
+    expect(document.activeElement).toBe(card())
+  })
+
+  it.each([
+    [{ key: 'Tab', shiftKey: true }, 'Next'],
+    [{ key: 'Tab', shiftKey: false }, ''],
+  ])('should keep %o from the focused card inside the card', async (init, label) => {
+    const wrapper = mountTopBar(definition)
+    await wrapper.get('[data-onboarding="topbar-help"]').trigger('click')
+    ;[...document.querySelectorAll<HTMLElement>('.mint-menu-item')].find((item) => item.textContent?.trim() === 'Top bar tour')!.click()
+    await flushPromises()
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { ...init, bubbles: true, cancelable: true }))
+
+    expect(card()!.contains(document.activeElement)).toBe(true)
+    expect((document.activeElement as HTMLElement).textContent?.trim()).toBe(label)
+  })
+
+  it('should leave Escape and Tab to a control outside the tour that has focus', async () => {
+    const wrapper = mountTopBar(definition)
+    await wrapper.get('[data-onboarding="topbar-help"]').trigger('click')
+    ;[...document.querySelectorAll<HTMLElement>('.mint-menu-item')].find((item) => item.textContent?.trim() === 'Top bar tour')!.click()
+    await flushPromises()
+    const input = document.body.appendChild(document.createElement('input'))
+    input.focus()
+
+    for (const key of ['Tab', 'Escape']) document.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }))
+    await nextTick()
+
+    expect(document.activeElement).toBe(input)
+    expect(card()).not.toBeNull()
+    input.remove()
+  })
+
+  it('should go to the next step when Enter is pressed on the focused card', async () => {
+    const wrapper = mountTopBar(definition)
+    await wrapper.get('[data-onboarding="topbar-help"]').trigger('click')
+    ;[...document.querySelectorAll<HTMLElement>('.mint-menu-item')].find((item) => item.textContent?.trim() === 'Top bar tour')!.click()
+    await flushPromises()
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }))
+    await flushPromises()
+
+    expect(card()?.textContent).toContain('Replay tours.')
+  })
+
+  it('should show no Next button on an advanceOn click step', async () => {
+    const wrapper = mountTopBar(definition)
+    await wrapper.get('[data-onboarding="topbar-help"]').trigger('click')
+    document.querySelector<HTMLElement>('.mint-menu-item')!.click()
+    await flushPromises()
+    ;(document.querySelector('.mint-onboarding__card .mint-button') as HTMLElement).click()
+    await flushPromises()
+
+    expect(card()?.textContent).toContain('Click the highlighted control.')
+    expect(card()?.textContent).not.toContain('Done')
+  })
+
+  it('should keep Tab on the anchor and the card on an advanceOn click step', async () => {
+    const wrapper = mountTopBar(definition)
+    await wrapper.get('[data-onboarding="topbar-help"]').trigger('click')
+    document.querySelector<HTMLElement>('.mint-menu-item')!.click()
+    await flushPromises()
+    ;(document.querySelector('.mint-onboarding__card .mint-button') as HTMLElement).click()
+    await flushPromises()
+    const anchor = document.querySelector<HTMLElement>('[data-onboarding="topbar-help"]')!
+    expect(document.activeElement).toBe(anchor)
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab' }))
+
+    expect(card()?.contains(document.activeElement)).toBe(true)
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', shiftKey: true }))
+    expect(document.activeElement).toBe(anchor)
+  })
+})

package/src/__tests__/composables/useOnboarding.test.ts

@@ -0,0 +1,317 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, h, nextTick, ref } from 'vue'
+import { mount, type VueWrapper } from '@vue/test-utils'
+import {
+  ANCHOR_WAIT_MS,
+  provideOnboarding,
+  type OnboardingDefinition,
+  type OnboardingState,
+  type ProvideOnboardingOptions,
+} from '../../composables/useOnboarding'
+
+const KEY = 'mint.onboarding.app.7'
+
+const definition: OnboardingDefinition = {
+  tours: [
+    {
+      id: 'intro',
+      title: 'Intro',
+      steps: [
+        { id: 'a', anchor: 'a', title: 'A', body: '' },
+        { id: 'b', anchor: 'b', title: 'B', body: '' },
+      ],
+    },
+    { id: 'list', title: 'List', route: 'experiments', steps: [{ id: 'new', anchor: 'new', title: 'New', body: '' }] },
+  ],
+  checklist: [{ id: 'create', title: 'Create' }],
+  whatsNew: [{ id: 'jobs', anchor: 'a', title: 'Jobs', body: '' }],
+}
+
+let wrapper: VueWrapper | undefined
+
+function addAnchor(id: string) {
+  const element = document.createElement('button')
+  element.dataset.onboarding = id
+  document.body.append(element)
+  return element
+}
+
+function setup(options: Partial<ProvideOnboardingOptions> = {}, def = definition): OnboardingState {
+  let state!: OnboardingState
+  wrapper = mount(defineComponent({
+    setup() {
+      state = provideOnboarding(def, { appId: 'app', userId: 7, ...options })
+      return () => h('div')
+    },
+  }))
+  return state
+}
+
+async function flush() {
+  await vi.advanceTimersByTimeAsync(0)
+  await nextTick()
+}
+
+const stored = () => JSON.parse(localStorage.getItem(KEY) ?? 'null') as string[] | null
+
+describe('provideOnboarding', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    localStorage.clear()
+    addAnchor('a')
+    addAnchor('b')
+  })
+
+  afterEach(() => {
+    wrapper?.unmount()
+    document.body.innerHTML = ''
+    vi.useRealTimers()
+  })
+
+  it('should start the first tour of the route and mark each shown step as seen', async () => {
+    const state = setup()
+    await flush()
+
+    expect(state.active.value?.step.id).toBe('a')
+    state.next()
+    await flush()
+
+    expect(state.active.value?.step.id).toBe('b')
+    expect(stored()).toEqual(expect.arrayContaining(['step:intro/a', 'step:intro/b']))
+  })
+
+  it('should mark the existing news as seen on the first run only', async () => {
+    const first = setup({ autoStart: false })
+    expect(first.unseenNews.value).toBe(0)
+    wrapper?.unmount()
+
+    const later = setup({ autoStart: false }, { ...definition, whatsNew: [...definition.whatsNew!, { id: 'pins', anchor: 'b', title: 'Pins', body: '' }] })
+
+    expect(later.news.value.map((item) => item.unseen)).toEqual([false, true])
+  })
+
+  it('should show a returning user only the steps with new ids', async () => {
+    localStorage.setItem(KEY, JSON.stringify(['step:intro/a']))
+    const state = setup()
+    await flush()
+
+    expect(state.active.value).toMatchObject({ step: { id: 'b' }, index: 0, count: 1 })
+  })
+
+  it('should mark every step seen on dismiss and not start the tour again', async () => {
+    const state = setup()
+    await flush()
+    state.dismiss()
+    wrapper?.unmount()
+
+    const again = setup()
+    await flush()
+
+    expect(stored()).toEqual(expect.arrayContaining(['step:intro/a', 'step:intro/b']))
+    expect(again.active.value).toBeNull()
+  })
+
+  it('should skip a step whose anchor does not appear in time and keep it unseen', async () => {
+    document.querySelector('[data-onboarding="a"]')!.remove()
+    const state = setup()
+    await flush()
+    expect(state.active.value).toBeNull()
+
+    await vi.advanceTimersByTimeAsync(ANCHOR_WAIT_MS)
+    await nextTick()
+
+    expect(state.active.value?.step.id).toBe('b')
+    expect(stored()).not.toContain('step:intro/a')
+  })
+
+  it('should leave a missing anchor out of the count and skip it at once after Next', async () => {
+    const state = setup({}, { tours: [{ id: 't', title: 'T', steps: [
+      { id: 'a', anchor: 'a', title: 'A', body: '' },
+      { id: 'gone', anchor: 'gone', title: 'Gone', body: '' },
+      { id: 'b', anchor: 'b', title: 'B', body: '' },
+    ] }] })
+    await flush()
+    expect(state.active.value).toMatchObject({ step: { id: 'a' }, index: 0, count: 2 })
+
+    state.next()
+    await flush()
+
+    expect(state.active.value).toMatchObject({ step: { id: 'b' }, index: 1, count: 2 })
+  })
+
+  it('should still show a later step whose anchor renders after the tour started', async () => {
+    const state = setup({}, { tours: [{ id: 't', title: 'T', steps: [
+      { id: 'a', anchor: 'a', title: 'A', body: '' },
+      { id: 'late', anchor: 'late', title: 'Late', body: '' },
+      { id: 'b', anchor: 'b', title: 'B', body: '' },
+    ] }] })
+    await flush()
+    expect(state.active.value).toMatchObject({ step: { id: 'a' }, count: 2 })
+
+    addAnchor('late')
+    state.next()
+    await flush()
+
+    expect(state.active.value).toMatchObject({ step: { id: 'late' }, index: 1, count: 3 })
+  })
+
+  it('should keep the position and count in step after Back when a shown anchor went away', async () => {
+    addAnchor('c')
+    const state = setup({}, { tours: [{ id: 't', title: 'T', steps: [
+      { id: 'a', anchor: 'a', title: 'A', body: '' },
+      { id: 'b', anchor: 'b', title: 'B', body: '' },
+      { id: 'c', anchor: 'c', title: 'C', body: '' },
+    ] }] })
+    await flush()
+    state.next()
+    await flush()
+    state.next()
+    await flush()
+    document.querySelector('[data-onboarding="b"]')!.remove()
+
+    state.back()
+    await flush()
+    expect(state.active.value).toMatchObject({ step: { id: 'a' }, index: 0, count: 2 })
+    state.next()
+    await flush()
+
+    expect(state.active.value).toMatchObject({ step: { id: 'c' }, index: 1, count: 2 })
+  })
+
+  it('should show a step whose anchor appears while it waits', async () => {
+    document.querySelector('[data-onboarding="a"]')!.remove()
+    const state = setup()
+    await flush()
+
+    addAnchor('a')
+    await flush()
+
+    expect(state.active.value?.step.id).toBe('a')
+  })
+
+  it('should wait for an open modal to close before it starts a tour', async () => {
+    const modal = document.createElement('div')
+    modal.setAttribute('aria-modal', 'true')
+    document.body.append(modal)
+    const state = setup()
+    await flush()
+    expect(state.active.value).toBeNull()
+
+    modal.remove()
+    await flush()
+
+    expect(state.active.value?.step.id).toBe('a')
+  })
+
+  it('should drop a pending auto-start when the user ends a tour picked by hand', async () => {
+    const modal = document.createElement('div')
+    modal.setAttribute('aria-modal', 'true')
+    document.body.append(modal)
+    const state = setup({}, { tours: [
+      definition.tours![0],
+      { id: 'more', title: 'More', steps: [{ id: 'b', anchor: 'b', title: 'B', body: '' }] },
+    ] })
+    await flush()
+    state.startTour('intro')
+    await flush()
+    state.dismiss()
+
+    modal.remove()
+    await flush()
+
+    expect(state.active.value).toBeNull()
+  })
+
+  it('should start the tour of a route when the app reaches that route', async () => {
+    localStorage.setItem(KEY, JSON.stringify(['step:intro/a', 'step:intro/b']))
+    addAnchor('new')
+    const route = ref('home')
+    const state = setup({ route })
+    await flush()
+    expect(state.tours.value.map((tour) => tour.id)).toEqual(['intro'])
+    expect(state.active.value).toBeNull()
+
+    route.value = 'experiments'
+    await flush()
+
+    expect(state.active.value?.step.id).toBe('new')
+  })
+
+  it.each([
+    ['finishes', (state: OnboardingState) => { state.next(); return flush().then(() => state.next()) }, 'new'],
+    ['is dismissed', (state: OnboardingState) => state.dismiss(), undefined],
+  ])('should start the next tour of the page only when the first %s', async (_, end, next) => {
+    addAnchor('new')
+    const state = setup({ route: 'experiments' })
+    await flush()
+    expect(state.active.value?.step.id).toBe('a')
+
+    await end(state)
+    await flush()
+
+    expect(state.active.value?.step.id).toBe(next)
+  })
+
+  it('should leave out a step that is not available', async () => {
+    const state = setup({}, { tours: [{ id: 't', title: 'T', steps: [
+      { id: 'a', anchor: 'a', title: 'A', body: '', available: () => false },
+      { id: 'b', anchor: 'b', title: 'B', body: '' },
+    ] }] })
+    await flush()
+
+    expect(state.active.value).toMatchObject({ step: { id: 'b' }, count: 1 })
+  })
+
+  it('should keep the keys another tab stored when it writes', () => {
+    const state = setup({ autoStart: false })
+    localStorage.setItem(KEY, JSON.stringify([...stored()!, 'task:create']))
+
+    state.setChecklistHidden(true)
+
+    expect(stored()).toEqual(expect.arrayContaining(['task:create', 'hide:checklist']))
+  })
+
+  it('should move on when the anchor of an advanceOn click step is clicked', async () => {
+    const state = setup({}, { tours: [{ id: 't', title: 'T', steps: [
+      { id: 'a', anchor: 'a', title: 'A', body: '', advanceOn: 'click' },
+      { id: 'b', anchor: 'b', title: 'B', body: '' },
+    ] }] })
+    await flush()
+
+    document.querySelector<HTMLElement>('[data-onboarding="a"]')!.click()
+    await flush()
+
+    expect(state.active.value?.step.id).toBe('b')
+  })
+
+  it('should keep a task done after its predicate turns false', async () => {
+    const created = ref(true)
+    const state = setup({ autoStart: false }, { checklist: [{ id: 'create', title: 'Create', done: () => created.value }] })
+    created.value = false
+    state.refresh()
+    await nextTick()
+
+    expect(state.tasks.value[0].done).toBe(true)
+    expect(state.checklistVisible.value).toBe(false)
+  })
+
+  it.each([
+    ['complete', (state: OnboardingState) => state.complete('create'), false],
+    ['hide', (state: OnboardingState) => state.setChecklistHidden(true), false],
+    ['nothing', () => {}, true],
+  ])('should show the checklist chip after %s: %s', (_, act, visible) => {
+    const state = setup({ autoStart: false })
+    act(state)
+
+    expect(state.checklistVisible.value).toBe(visible)
+  })
+
+  it('should stay off without a user', async () => {
+    const state = setup({ userId: null })
+    await flush()
+
+    expect(state.enabled.value).toBe(false)
+    expect(state.active.value).toBeNull()
+    expect(localStorage.length).toBe(0)
+  })
+})

package/src/__tests__/styles/v2AuditRules.test.ts

@@ -20,6 +20,14 @@ function rule(text: string, selector: string): string {
 const rem = (value: string): number => Number(value.replace('rem', '')) * 16
 
 describe('v2 audit style rules', () => {
+  it('should stop the page bounce in a tab vertically and in a PWA on both axes', () => {
+    const variables = css('variables.css')
+    expect(rule(variables, 'html,\nbody')).toMatch(/overscroll-behavior-y:\s*none/)
+    expect(variables).toMatch(
+      /@media \(display-mode: standalone\)\s*\{\s*html,\s*body\s*\{\s*overscroll-behavior:\s*none;\s*\}/,
+    )
+  })
+
   it('should keep the outermost cards at least 16px from the window edge', () => {
     const inset = /--mint-page-inset:\s*([\d.]+rem)/.exec(css('variables.css'))?.[1] ?? '0rem'
     expect(rem(inset)).toBeGreaterThanOrEqual(16)

package/src/components/AppTopBar.onboarding.story.vue

@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import { defineComponent, h, ref } from 'vue'
+import AppTopBar from './AppTopBar.vue'
+import BaseButton from './BaseButton.vue'
+import { defineOnboarding, provideOnboarding, useOnboarding } from '../composables/useOnboarding'
+import type { PillNavItem } from '../types'
+
+const pills: PillNavItem[] = [
+  { id: 'home', label: 'Home' },
+  { id: 'experiments', label: 'Experiments' },
+  { id: 'instruments', label: 'Instruments' },
+]
+
+const onboarding = defineOnboarding({
+  tours: [
+    {
+      id: 'intro',
+      title: 'The top bar',
+      steps: [
+        { id: 'pages', anchor: 'topbar-pills', title: 'Move between pages', body: 'Home, Experiments and Instruments are one click away on every page.' },
+        { id: 'new', anchor: 'story-new', title: 'Create an experiment', body: 'Click New experiment to go on.', placement: 'bottom-start', advanceOn: 'click' },
+        { id: 'help', anchor: 'topbar-help', title: 'Help', body: 'Open the checklist, play a tour again, or see what is new.', placement: 'bottom-end' },
+      ],
+    },
+  ],
+  checklist: [
+    { id: 'create', title: 'Create an experiment', action: { label: 'Open', run: () => {} } },
+    { id: 'project', title: 'Create a project', action: { label: 'Open', run: () => {} } },
+    { id: 'theme', title: 'Pick a theme' },
+  ],
+  whatsNew: [
+    { id: 'settings', anchor: 'topbar-settings', title: 'Palettes in Settings', body: 'Pick an accent color in Settings → Appearance.', placement: 'bottom-end' },
+  ],
+})
+
+// The stories are returning users with no state yet, so the news shows too.
+const OnboardingProvider = defineComponent({
+  props: { appId: { type: String, required: true }, news: Boolean },
+  setup(props, { slots }) {
+    const key = `mint.onboarding.${props.appId}.local`
+    if (props.news && localStorage.getItem(key) === null) localStorage.setItem(key, '["task:theme"]')
+    provideOnboarding(onboarding, { appId: props.appId, userId: 'local' })
+    return () => slots.default?.()
+  },
+})
+
+const PageBody = defineComponent({
+  setup() {
+    const state = useOnboarding()
+    return () => h('div', { style: 'padding: 1.5rem; display: flex; gap: 0.5rem' }, [
+      h(BaseButton, { 'data-onboarding': 'story-new', onClick: () => state?.complete('create') }, () => 'New experiment'),
+      h(BaseButton, { variant: 'secondary', onClick: () => { localStorage.clear(); location.reload() } }, () => 'Reset onboarding'),
+    ])
+  },
+})
+
+const pill = ref('home')
+</script>
+
+<template>
+  <Story title="Layout/AppTopBar/Onboarding" :layout="{ type: 'single', iframe: true }">
+    <Variant title="Tour, checklist and news">
+      <OnboardingProvider app-id="story-onboarding" news>
+        <AppTopBar v-model:pill="pill" :spec="{ pills, settings: { tabs: [] }, standaloneLabel: false }" title="MINT" />
+        <PageBody />
+      </OnboardingProvider>
+    </Variant>
+  </Story>
+</template>

package/src/components/AppTopBar.vue

@@ -19,9 +19,11 @@ 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'
@@ -87,6 +89,7 @@ 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,
@@ -295,9 +298,10 @@ const normalizedSettingsTabs = computed<SettingsTab[]>(() =>
         </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" />
+        <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"
@@ -324,7 +328,7 @@ const normalizedSettingsTabs = computed<SettingsTab[]>(() =>
       </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"
@@ -347,6 +351,7 @@ const normalizedSettingsTabs = computed<SettingsTab[]>(() =>
         <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"
@@ -399,6 +404,9 @@ const normalizedSettingsTabs = computed<SettingsTab[]>(() =>
 
         <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" />
 
@@ -408,6 +416,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">