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

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/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'