@morscherlab/mint-sdk 1.4.0-beta.9 → 1.4.1

package/src/composables/useOnboarding.ts

@@ -0,0 +1,465 @@
+import {
+  computed,
+  inject,
+  onScopeDispose,
+  provide,
+  ref,
+  shallowRef,
+  toValue,
+  watch,
+  type ComputedRef,
+  type InjectionKey,
+  type MaybeRefOrGetter,
+  type ShallowRef,
+} from 'vue'
+import type { Placement } from '@floating-ui/dom'
+import { usePlatform } from './usePlatform'
+
+/** One card of a tour. It points at the element with `data-onboarding="<anchor>"`. */
+export interface OnboardingStep {
+  /** Stable id. A returning user sees only steps whose id is new. */
+  id: string
+  /** `data-onboarding` value of the element the step points at. */
+  anchor: string
+  title: string
+  body: string
+  /** Side of the anchor for the card. Default `bottom`. */
+  placement?: Placement
+  /** `'click'`: the highlighted element takes clicks, and a click moves the tour to the next step. */
+  advanceOn?: 'click'
+  /** Leave the step out while this returns false, e.g. without the permission its control needs. */
+  available?: () => boolean
+}
+
+export interface OnboardingTour {
+  id: string
+  /** Name in the Help menu. */
+  title: string
+  /** Start only while the app's route is this value. Omit it for elements on every page, such as the top bar. */
+  route?: string
+  steps: OnboardingStep[]
+}
+
+export interface OnboardingTask {
+  id: string
+  title: string
+  /** Leave the task out while this returns false, e.g. without the permission it needs. */
+  available?: () => boolean
+  /** The task is done when this returns true. The coordinator checks it at start, on a route change and when the Help menu opens. */
+  done?: () => boolean
+  /** The link at the end of the task row. */
+  action?: { label: string; run: () => void }
+}
+
+/** A new feature. A dot marks its element until the user opens it. */
+export interface OnboardingNews {
+  id: string
+  anchor: string
+  title: string
+  body: string
+  placement?: Placement
+}
+
+export interface OnboardingDefinition {
+  tours?: OnboardingTour[]
+  /** The "Getting started" checklist. */
+  checklist?: OnboardingTask[]
+  whatsNew?: OnboardingNews[]
+}
+
+export interface ProvideOnboardingOptions {
+  /** Storage namespace, e.g. `platform` or the plugin name. */
+  appId: string
+  /** The signed-in user. `null` turns onboarding off (no user yet). Default: the platform user; `local` standalone or with auth off. */
+  userId?: MaybeRefOrGetter<string | number | null | undefined>
+  /** The current route, matched against `OnboardingTour.route`. */
+  route?: MaybeRefOrGetter<string | null | undefined>
+  /** Start unseen tours on their own. Default `true`. */
+  autoStart?: boolean
+}
+
+/** The step on screen and the element it points at. */
+export interface OnboardingActiveStep {
+  step: OnboardingStep
+  element: HTMLElement
+  /** Position among the steps of this run, and their count. */
+  index: number
+  count: number
+  /** A what's-new card, not a tour step. */
+  news: boolean
+}
+
+export interface OnboardingState {
+  definition: OnboardingDefinition
+  /** False until a user is known. */
+  enabled: ComputedRef<boolean>
+  active: ShallowRef<OnboardingActiveStep | null>
+  /** Tours that can run on the current route. */
+  tours: ComputedRef<OnboardingTour[]>
+  /** The available tasks. */
+  tasks: ComputedRef<Array<Omit<OnboardingTask, 'done'> & { done: boolean }>>
+  tasksDone: ComputedRef<number>
+  /** The checklist chip shows while a task is open and the user did not hide it. */
+  checklistVisible: ComputedRef<boolean>
+  checklistHidden: ComputedRef<boolean>
+  news: ComputedRef<Array<OnboardingNews & { unseen: boolean }>>
+  unseenNews: ComputedRef<number>
+  startTour: (id: string) => void
+  showNews: (id: string) => void
+  next: () => void
+  back: () => void
+  /** End the run (× or Esc). Every step of the tour counts as seen. */
+  dismiss: () => void
+  complete: (taskId: string) => void
+  setChecklistHidden: (hidden: boolean) => void
+  /** Run the task predicates again. */
+  refresh: () => void
+}
+
+export const ONBOARDING_KEY: InjectionKey<OnboardingState> = Symbol('mint-onboarding')
+
+/** Wait this long for the missing anchor of a run's first step, or of the step after a click step; then skip it. */
+export const ANCHOR_WAIT_MS = 2000
+
+const HIDE_CHECKLIST = 'hide:checklist'
+const stepKey = (tour: OnboardingTour, step: OnboardingStep) => `step:${tour.id}/${step.id}`
+const anchorSelector = (anchor: string) => `[data-onboarding="${CSS.escape(anchor)}"]`
+
+/** Types a definition, so it can live in its own file. */
+export function defineOnboarding(definition: OnboardingDefinition): OnboardingDefinition {
+  return definition
+}
+
+function readSeen(key: string): string[] | null {
+  try {
+    const raw = globalThis.localStorage?.getItem(key)
+    const parsed: unknown = raw ? JSON.parse(raw) : null
+    return Array.isArray(parsed) ? parsed.filter((item): item is string => typeof item === 'string') : null
+  } catch {
+    return null
+  }
+}
+
+function writeSeen(key: string, seen: Set<string>) {
+  try {
+    globalThis.localStorage?.setItem(key, JSON.stringify([...seen]))
+  } catch {
+    // Private windows and full storage: the state lasts until reload.
+  }
+}
+
+/** Resolves with the element once it is in the document, or null after `timeout` or when `signal` aborts. */
+function waitForElement(selector: string, timeout: number, signal: AbortSignal): Promise<HTMLElement | null> {
+  const found = document.querySelector<HTMLElement>(selector)
+  if (found) return Promise.resolve(found)
+  return new Promise((resolve) => {
+    const observer = new MutationObserver(() => {
+      const element = document.querySelector<HTMLElement>(selector)
+      if (element) finish(element)
+    })
+    const timer = setTimeout(() => finish(null), timeout)
+    const onAbort = () => finish(null)
+    function finish(element: HTMLElement | null) {
+      observer.disconnect()
+      clearTimeout(timer)
+      signal.removeEventListener('abort', onAbort)
+      resolve(element)
+    }
+    signal.addEventListener('abort', onAbort)
+    observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-onboarding'] })
+  })
+}
+
+// Any open modal except the tour card itself.
+const MODAL_SELECTOR = '[aria-modal="true"]:not(.mint-onboarding__card)'
+
+/** Resolves true once no modal is open, or false when `signal` aborts first. */
+function waitForNoModal(signal: AbortSignal): Promise<boolean> {
+  if (!document.querySelector(MODAL_SELECTOR)) return Promise.resolve(true)
+  return new Promise((resolve) => {
+    const observer = new MutationObserver(() => {
+      if (!document.querySelector(MODAL_SELECTOR)) finish(true)
+    })
+    const onAbort = () => finish(false)
+    function finish(closed: boolean) {
+      observer.disconnect()
+      signal.removeEventListener('abort', onAbort)
+      resolve(closed)
+    }
+    signal.addEventListener('abort', onAbort)
+    observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['aria-modal'] })
+  })
+}
+
+/**
+ * Creates the app's onboarding coordinator and provides it to `AppTopBar`, which then
+ * shows the Help button, the checklist chip and the tour layer. Call it once, in the
+ * root component. It shows one item at a time and waits for open modals.
+ *
+ * ```ts
+ * provideOnboarding(onboarding, { appId: 'leaf' })
+ * ```
+ */
+export function provideOnboarding(definition: OnboardingDefinition, options: ProvideOnboardingOptions): OnboardingState {
+  const { user, isAdmin } = usePlatform()
+  const userId = computed(() => {
+    // With no user, isAdmin is true only standalone or with auth off.
+    const fallback = isAdmin.value ? 'local' : null
+    const value = options.userId === undefined ? (user.value?.id ?? fallback) : toValue(options.userId)
+    return value == null ? null : String(value)
+  })
+  const route = computed(() => toValue(options.route) ?? undefined)
+  const storageKey = computed(() => userId.value === null ? null : `mint.onboarding.${options.appId}.${userId.value}`)
+  const enabled = computed(() => storageKey.value !== null)
+
+  const seen = ref(new Set<string>())
+  // Bumped by refresh(): the predicates read app state that Vue may not track.
+  const tick = ref(0)
+  const active = shallowRef<OnboardingActiveStep | null>(null)
+  let run: { tour: OnboardingTour | null; steps: OnboardingStep[]; index: number; shown: Set<number> } | null = null
+  let runId = 0
+  let stepWait: AbortController | undefined
+  let detachClick: (() => void) | undefined
+
+  /** Applies `update` to the stored state merged with this tab's, so tabs do not drop each other's keys. */
+  function persist(update: (keys: Set<string>) => void) {
+    const key = storageKey.value
+    if (!key) return
+    const merged = new Set([...(readSeen(key) ?? []), ...seen.value])
+    update(merged)
+    seen.value = merged
+    writeSeen(key, merged)
+  }
+
+  function markSeen(...keys: string[]) {
+    if (keys.every((key) => seen.value.has(key))) return
+    persist((set) => keys.forEach((key) => set.add(key)))
+  }
+
+  // Another tab changed the state.
+  function onStorage(event: StorageEvent) {
+    if (event.key && event.key === storageKey.value) seen.value = new Set(readSeen(event.key) ?? [])
+  }
+  window.addEventListener('storage', onStorage)
+
+  watch(storageKey, (key) => {
+    stop()
+    if (!key) {
+      seen.value = new Set()
+      return
+    }
+    const stored = readSeen(key)
+    seen.value = new Set(stored ?? [])
+    // First run: the tours introduce today's features, so today's news counts as seen.
+    if (stored === null) {
+      for (const item of definition.whatsNew ?? []) seen.value.add(`news:${item.id}`)
+      writeSeen(key, seen.value)
+    }
+  }, { immediate: true })
+
+  const tours = computed(() => (definition.tours ?? []).filter((tour) => !tour.route || tour.route === route.value))
+
+  const tasks = computed(() => {
+    void tick.value
+    return (definition.checklist ?? []).filter((task) => task.available?.() ?? true).map((task) => ({
+      ...task,
+      done: seen.value.has(`task:${task.id}`) || !!task.done?.(),
+    }))
+  })
+  // Done stays done, also when a predicate later returns false.
+  watch(tasks, (list) => markSeen(...list.filter((task) => task.done).map((task) => `task:${task.id}`)), { immediate: true })
+  const tasksDone = computed(() => tasks.value.filter((task) => task.done).length)
+  const checklistHidden = computed(() => seen.value.has(HIDE_CHECKLIST))
+  const checklistVisible = computed(() =>
+    enabled.value && tasks.value.length > 0 && tasksDone.value < tasks.value.length && !checklistHidden.value)
+
+  const news = computed(() => (definition.whatsNew ?? []).map((item) => ({ ...item, unseen: !seen.value.has(`news:${item.id}`) })))
+  const unseenNews = computed(() => enabled.value ? news.value.filter((item) => item.unseen).length : 0)
+
+  function stop() {
+    runId += 1
+    stepWait?.abort()
+    run = null
+    detachClick?.()
+    detachClick = undefined
+    active.value = null
+  }
+
+  /**
+   * Shows the first step at or after `from` whose anchor is there. Only the first step of
+   * the run and the step after a click step wait for theirs (the page or a menu can still
+   * be opening); after Next a missing anchor is skipped at once. Skipped steps stay unseen.
+   */
+  /**
+   * The later steps the page can still show: the anchor is on the page now, or
+   * a click step that can show opens it. The count grows if an anchor renders later.
+   */
+  function laterSteps(steps: OnboardingStep[], from: number) {
+    let count = 0
+    let previous = true
+    for (let at = from + 1; at < steps.length; at += 1) {
+      previous = (previous && steps[at - 1].advanceOn === 'click') || !!document.querySelector(anchorSelector(steps[at].anchor))
+      if (previous) count += 1
+    }
+    return count
+  }
+
+  async function showFrom(from: number) {
+    if (!run) return
+    const id = ++runId
+    stepWait?.abort()
+    const wait = new AbortController()
+    stepWait = wait
+    detachClick?.()
+    detachClick = undefined
+    const waitFirst = from === 0 || run.steps[from - 1].advanceOn === 'click'
+    for (let index = from; index < run.steps.length; index += 1) {
+      const step = run.steps[index]
+      const timeout = index === from && waitFirst ? ANCHOR_WAIT_MS : 0
+      const element = await waitForElement(anchorSelector(step.anchor), timeout, wait.signal)
+      if (id !== runId) return
+      if (!element) {
+        // Debug level: a missing anchor is normal, e.g. an admin-only button for a member.
+        console.debug(`[mint-onboarding] No element with data-onboarding="${step.anchor}"; step "${step.id}" skipped.`)
+        continue
+      }
+      run.index = index
+      markSeen(run.tour ? stepKey(run.tour, step) : `news:${step.id}`)
+      if (step.advanceOn === 'click') {
+        const onClick = () => next()
+        element.addEventListener('click', onClick)
+        detachClick = () => element.removeEventListener('click', onClick)
+      }
+      run.shown.add(index)
+      // Earlier steps count as the later ones do: shown, and still on the page.
+      const steps = run.steps
+      const position = [...run.shown].filter((at) => at < index && !!document.querySelector(anchorSelector(steps[at].anchor))).length
+      active.value = { step, element, index: position, count: position + 1 + laterSteps(run.steps, index), news: !run.tour }
+      return
+    }
+    // A finished tour hands over to the next one; × does not (dismiss stops the run first).
+    const finished = !!run.tour
+    stop()
+    if (finished && options.autoStart !== false) void autoStart()
+  }
+
+  function begin(tour: OnboardingTour | null, steps: OnboardingStep[]) {
+    if (!enabled.value || steps.length === 0) return
+    stop()
+    run = { tour, steps, index: 0, shown: new Set() }
+    void showFrom(0)
+  }
+
+  function startTour(id: string) {
+    const tour = tours.value.find((item) => item.id === id)
+    if (!tour) return
+    autoStartAbort?.abort()
+    begin(tour, availableSteps(tour))
+  }
+
+  function showNews(id: string) {
+    const item = definition.whatsNew?.find((entry) => entry.id === id)
+    if (!item) return
+    autoStartAbort?.abort()
+    begin(null, [item])
+  }
+
+  function next() {
+    if (run) void showFrom(run.index + 1)
+  }
+
+  function back() {
+    if (!run) return
+    // Back goes only to steps whose element is still on the page; it does not wait.
+    for (let index = run.index - 1; index >= 0; index -= 1) {
+      if (document.querySelector(anchorSelector(run.steps[index].anchor))) {
+        void showFrom(index)
+        return
+      }
+    }
+  }
+
+  function dismiss() {
+    autoStartAbort?.abort()
+    const tour = run?.tour
+    if (tour) markSeen(...tour.steps.map((step) => stepKey(tour, step)))
+    stop()
+  }
+
+  function complete(taskId: string) {
+    markSeen(`task:${taskId}`)
+  }
+
+  function setChecklistHidden(hidden: boolean) {
+    if (!storageKey.value) return
+    if (hidden) markSeen(HIDE_CHECKLIST)
+    else persist((set) => set.delete(HIDE_CHECKLIST))
+  }
+
+  function refresh() {
+    tick.value += 1
+  }
+
+  const availableSteps = (tour: OnboardingTour) => tour.steps.filter((step) => step.available?.() ?? true)
+
+  // Tours started on this page; a tour with skipped steps does not start again until the page changes.
+  const tried = new Set<string>()
+  let autoStartAbort: AbortController | undefined
+  async function autoStart() {
+    autoStartAbort?.abort()
+    const controller = new AbortController()
+    autoStartAbort = controller
+    if (!(await waitForNoModal(controller.signal)) || run || !enabled.value) return
+    for (const tour of tours.value) {
+      if (tried.has(tour.id)) continue
+      const unseen = availableSteps(tour).filter((step) => !seen.value.has(stepKey(tour, step)))
+      if (unseen.length) {
+        tried.add(tour.id)
+        begin(tour, unseen)
+        return
+      }
+    }
+  }
+
+  // A new page ends the run: its elements are gone. Its unseen steps start again.
+  watch([route, storageKey], () => {
+    stop()
+    tried.clear()
+    refresh()
+    if (options.autoStart !== false) void autoStart()
+  }, { immediate: true })
+
+  onScopeDispose(() => {
+    autoStartAbort?.abort()
+    window.removeEventListener('storage', onStorage)
+    stop()
+  })
+
+  const state: OnboardingState = {
+    definition,
+    enabled,
+    active,
+    tours,
+    tasks,
+    tasksDone,
+    checklistVisible,
+    checklistHidden,
+    news,
+    unseenNews,
+    startTour,
+    showNews,
+    next,
+    back,
+    dismiss,
+    complete,
+    setChecklistHidden,
+    refresh,
+  }
+  provide(ONBOARDING_KEY, state)
+  return state
+}
+
+/** The app's onboarding coordinator, e.g. to call `complete(taskId)`. Null when the app provides none. */
+export function useOnboarding(): OnboardingState | null {
+  return inject(ONBOARDING_KEY, null)
+}

package/src/composables/usePluginWorkspace.ts

@@ -120,7 +120,7 @@ export function usePluginWorkspace(options: UsePluginWorkspaceOptions): UsePlugi
       sidebarToggleLabel: sidebar.toggleLabel ?? 'Open workspace sidebar',
       sidebarCloseLabel: sidebar.closeLabel ?? 'Close workspace sidebar',
       hasSidebarSurface: hasSidebarSurface.value,
-      title: props.spec?.title ?? 'Workspace',
+      title: props.spec?.title,
       subtitle: props.spec?.subtitle,
       topBar: topBarSpec.value === false
         ? false

package/src/data.ts

@@ -122,6 +122,7 @@ export {
 export {
   detectDelimiter,
   readFileAsText,
+  readTableFileAsCsv,
   useFileImport,
   validateImportFile,
   type FileImportOptions,

package/src/runtime.ts

@@ -77,7 +77,8 @@ export {
   combinePluginJobSources,
   useJobCenter,
   type CombinedPluginJobCenterSource,
-  type JobsStatusTrayTab,
+  type JobRowOverride,
+  type JobRowView,
   type PluginJobCenterSource,
   type UseJobCenterOptions,
   type UseJobCenterReturn,

package/src/shell.ts

@@ -101,3 +101,20 @@ export {
   type UsePluginWorkspaceOptions,
   type UsePluginWorkspaceReturn,
 } from './composables/usePluginWorkspace'
+
+// Onboarding: tours, the Getting started checklist and what's-new hints
+export {
+  ANCHOR_WAIT_MS,
+  defineOnboarding,
+  provideOnboarding,
+  useOnboarding,
+  ONBOARDING_KEY,
+  type OnboardingActiveStep,
+  type OnboardingDefinition,
+  type OnboardingNews,
+  type OnboardingState,
+  type OnboardingStep,
+  type OnboardingTask,
+  type OnboardingTour,
+  type ProvideOnboardingOptions,
+} from './composables/useOnboarding'

package/src/stores/index.ts

@@ -3,9 +3,7 @@ export {
   useSettingsStore,
   tryUseSettingsStore,
   colorPalettes,
-  paletteCssVariables,
   tableDensityToSize,
-  PALETTE_CSS_VARIABLES,
   type SettingsState,
 } from './settings'
 export { useExperimentStore } from './experiment'

package/src/stores/settings.ts

@@ -55,39 +55,24 @@ const defaultSettings: SettingsState = {
   tableDensity: 'normal',
 }
 
-export const colorPalettes: Record<ColorPalette, { name: string; hues: [number, number] }> = {
-  default: { name: 'Default (Cyan-Pink)', hues: [180, 320] },
-  colorblind: { name: 'Colorblind-friendly', hues: [45, 260] },
-  viridis: { name: 'Viridis', hues: [280, 80] },
-  pastel: { name: 'Pastel', hues: [200, 340] },
-}
-
 /**
- * Custom properties a non-default palette overrides on `<html>`.
- *
- * The saturation/lightness pairs are lifted from the original indigo/orange
- * tokens in `styles/variables.css` so only the hue moves; the `default`
- * palette writes nothing at all and the stylesheet values stand.
+ * Accent palettes. `styles/variables.css` holds each palette's light and dark
+ * tokens under `[data-palette]`; the store only writes the attribute.
  */
-export const PALETTE_CSS_VARIABLES = [
-  '--color-primary',
-  '--color-primary-hover',
-  '--color-primary-soft',
-  '--color-cta',
-  '--color-cta-hover',
-] as const
-
-/** Build the `<html>` custom-property overrides for a palette. */
-export function paletteCssVariables(palette: ColorPalette): Record<string, string> {
-  if (palette === 'default') return {}
-  const [primaryHue, accentHue] = colorPalettes[palette].hues
-  return {
-    '--color-primary': `hsl(${primaryHue} 84% 67%)`,
-    '--color-primary-hover': `hsl(${primaryHue} 75% 59%)`,
-    '--color-primary-soft': `hsl(${primaryHue} 84% 67% / 0.12)`,
-    '--color-cta': `hsl(${accentHue} 95% 53%)`,
-    '--color-cta-hover': `hsl(${accentHue} 90% 48%)`,
-  }
+export const colorPalettes: Record<ColorPalette, { name: string }> = {
+  default: { name: 'Teal' },
+  colorblind: { name: 'Colour-blind safe' },
+  purple: { name: 'Purple' },
+  ocean: { name: 'Ocean' },
+  forest: { name: 'Forest' },
+}
+
+/** Pre-v2 palette ids and the palette that replaces each one. */
+const RETIRED_PALETTES: Record<string, ColorPalette> = { viridis: 'purple', pastel: 'default' }
+
+function knownPalette(value: unknown): ColorPalette {
+  if (typeof value === 'string' && value in colorPalettes) return value as ColorPalette
+  return (typeof value === 'string' && RETIRED_PALETTES[value]) || 'default'
 }
 
 /** `DataFrame`-style size that each table density maps onto. */
@@ -107,13 +92,13 @@ function loadSettings(): SettingsState {
     const stored = localStorage.getItem(STORAGE_KEY)
     if (stored) {
       const parsed = JSON.parse(stored)
-      return { ...defaultSettings, ...parsed }
+      return { ...defaultSettings, ...parsed, colorPalette: knownPalette(parsed.colorPalette) }
     }
 
     const legacyStored = localStorage.getItem(LEGACY_STORAGE_KEY)
     if (legacyStored) {
       const parsed = JSON.parse(legacyStored)
-      const migrated = { ...defaultSettings, ...parsed }
+      const migrated = { ...defaultSettings, ...parsed, colorPalette: knownPalette(parsed.colorPalette) }
       localStorage.setItem(STORAGE_KEY, JSON.stringify(migrated))
       localStorage.removeItem(LEGACY_STORAGE_KEY)
       return migrated
@@ -202,20 +187,10 @@ export const useSettingsStore = defineStore('mint-settings', () => {
     document.documentElement.classList.toggle('dark', dark)
   }
 
-  /**
-   * Write the selected palette's hues onto `<html>` as custom-property
-   * overrides. The `default` palette clears them so `styles/variables.css`
-   * keeps ownership of the brand colors.
-   */
+  /** Mirror the palette onto `<html data-palette>`; `styles/variables.css` maps it to tokens. */
   function applyPalette() {
     if (typeof document === 'undefined') return
-    const style = document.documentElement.style
-    const overrides = paletteCssVariables(colorPalette.value)
-    for (const name of PALETTE_CSS_VARIABLES) {
-      const value = overrides[name]
-      if (value) style.setProperty(name, value)
-      else style.removeProperty(name)
-    }
+    document.documentElement.dataset.palette = colorPalette.value
   }
 
   /** Mirror the table density onto `<html data-density>` for CSS consumers. */
@@ -269,10 +244,6 @@ export const useSettingsStore = defineStore('mint-settings', () => {
     tableDensity.value = defaultSettings.tableDensity
   }
 
-  function getPaletteHues(): [number, number] {
-    return colorPalettes[colorPalette.value].hues
-  }
-
   /** The `size` the SDK table components default to for the current density. */
   function getTableSize(): 'sm' | 'md' | 'lg' {
     return tableDensityToSize(tableDensity.value)
@@ -298,7 +269,6 @@ export const useSettingsStore = defineStore('mint-settings', () => {
     applyDensity,
     persistSettings,
     resetToDefaults,
-    getPaletteHues,
     getTableSize,
     isDark,
     getApiBaseUrl,

package/src/styles/components/action-menu.css

@@ -9,7 +9,7 @@
 
 .mint-action-menu__panel {
   position: fixed;
-  z-index: 1000;
+  z-index: var(--mint-z-popover);
   min-width: 10rem;
   max-width: min(18rem, calc(100vw - 1rem));
 }

package/src/styles/components/app-layout.css

@@ -60,10 +60,11 @@
 }
 
 /* Floating variant: all sections appear as separate cards on a background,
-   spaced by the density gutter (8px, 12px comfortable). */
+   16px from the window edge and spaced by the density gutter (8px, 12px
+   comfortable). */
 .mint-layout--floating {
   background-color: var(--bg-primary);
-  padding: var(--mint-gutter);
+  padding: var(--mint-page-inset);
   gap: var(--mint-gutter);
 }
 
@@ -123,8 +124,10 @@
     transform: translateX(calc(100% + 1rem));
   }
 
+  /* `none`, not translateX(0): any transform makes the sidebar the containing
+     block of its fixed dropdown panels, and its overflow would clip them. */
   .mint-layout--responsive-sidebar.mint-layout--sidebar-open .mint-layout__sidebar {
-    transform: translateX(0);
+    transform: none;
   }
 
   .mint-layout--responsive-sidebar .mint-layout__sidebar-toggle {