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

package/src/components/internal/AppTopBarOnboardingInternal.vue

@@ -0,0 +1,172 @@
+<script setup lang="ts">
+/**
+ * The top-bar onboarding controls: the "Getting started n/m" chip while the
+ * checklist is open, and the Help button with the checklist, tours and news.
+ */
+import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue'
+import { autoUpdate, computePosition, offset, shift } from '@floating-ui/dom'
+import { Check, CircleHelp, Play } from 'lucide-vue-next'
+import { useEventListener } from '../../composables/useEventListener'
+import type { OnboardingState } from '../../composables/useOnboarding'
+import OnboardingLayerInternal from './OnboardingLayerInternal.vue'
+
+const props = defineProps<{ state: OnboardingState }>()
+
+const root = ref<HTMLElement | null>(null)
+const helpButton = ref<HTMLElement | null>(null)
+const panel = ref<HTMLElement | null>(null)
+const panelPosition = ref({ x: 0, y: 0 })
+const open = ref(false)
+const hasContent = computed(() =>
+  props.state.tasks.value.length > 0 || props.state.tours.value.length > 0 || props.state.news.value.length > 0)
+const progress = computed(() => {
+  const total = props.state.tasks.value.length
+  return total ? Math.round((props.state.tasksDone.value / total) * 100) : 0
+})
+
+function toggle() {
+  open.value = !open.value
+  if (open.value) props.state.refresh()
+}
+
+// The panel goes to the body, as the top bar clips its overflow; it follows the button.
+let stopAutoUpdate: (() => void) | undefined
+watch(open, async (isOpen) => {
+  stopAutoUpdate?.()
+  stopAutoUpdate = undefined
+  if (!isOpen) return
+  await nextTick()
+  const button = helpButton.value
+  const floating = panel.value
+  if (!button || !floating || !open.value) return
+  stopAutoUpdate = autoUpdate(button, floating, async () => {
+    const { x, y } = await computePosition(button, floating, {
+      strategy: 'fixed',
+      placement: 'bottom-end',
+      middleware: [offset(8), shift({ padding: 8 })],
+    })
+    panelPosition.value = { x, y }
+  })
+})
+onBeforeUnmount(() => stopAutoUpdate?.())
+
+function run(action: () => void) {
+  open.value = false
+  action()
+}
+
+useEventListener(document, 'pointerdown', (event) => {
+  const target = event.target as Node
+  if (open.value && !root.value?.contains(target) && !panel.value?.contains(target)) open.value = false
+})
+useEventListener(document, 'keydown', (event) => {
+  if (open.value && event.key === 'Escape') open.value = false
+})
+</script>
+
+<template>
+  <div v-if="hasContent" ref="root" class="mint-onboarding-help">
+    <button
+      v-if="state.checklistVisible.value"
+      type="button"
+      class="mint-onboarding-help__chip"
+      :class="{ 'mint-onboarding-help__chip--open': open }"
+      data-onboarding="topbar-checklist"
+      :aria-expanded="open"
+      @click="toggle"
+    >
+      Getting started
+      <span class="mint-onboarding-help__count">{{ state.tasksDone.value }}/{{ state.tasks.value.length }}</span>
+      <span class="mint-onboarding-help__bar" aria-hidden="true"><span :style="{ width: `${progress}%` }" /></span>
+    </button>
+    <button
+      ref="helpButton"
+      type="button"
+      class="mint-topbar__settings-btn"
+      :class="{ 'mint-topbar__settings-btn--open': open }"
+      data-onboarding="topbar-help"
+      :aria-label="state.unseenNews.value ? `Help, ${state.unseenNews.value} new` : 'Help'"
+      :aria-expanded="open"
+      @click="toggle"
+    >
+      <CircleHelp class="mint-topbar__settings-icon" aria-hidden="true" />
+      <span v-if="state.unseenNews.value" class="mint-onboarding-help__badge" aria-hidden="true">{{ state.unseenNews.value }}</span>
+    </button>
+
+    <Teleport to="body">
+      <div
+        v-if="open"
+        ref="panel"
+        class="mint-popover mint-onboarding-help__panel"
+        role="dialog"
+        aria-label="Help"
+        :style="{ left: `${panelPosition.x}px`, top: `${panelPosition.y}px` }"
+      >
+        <template v-if="state.tasks.value.length">
+          <div class="mint-onboarding-help__header">
+            <span class="mint-onboarding-help__heading">Getting started</span>
+            <span class="mint-onboarding-help__count">{{ state.tasksDone.value }}/{{ state.tasks.value.length }}</span>
+          </div>
+          <div class="mint-onboarding-help__progress" aria-hidden="true"><span :style="{ width: `${progress}%` }" /></div>
+          <ul class="mint-onboarding-help__todos">
+            <li
+              v-for="task in state.tasks.value"
+              :key="task.id"
+              :class="['mint-onboarding-help__todo', { 'mint-onboarding-help__todo--done': task.done }]"
+            >
+              <span class="mint-onboarding-help__check" role="img" :aria-label="task.done ? 'Done' : 'Not done'">
+                <Check v-if="task.done" :size="10" :stroke-width="3" aria-hidden="true" />
+              </span>
+              <span class="mint-onboarding-help__todo-title">{{ task.title }}</span>
+              <button
+                v-if="task.action && !task.done"
+                type="button"
+                class="mint-onboarding-help__link"
+                @click="run(task.action.run)"
+              >
+                {{ task.action.label }}
+              </button>
+            </li>
+          </ul>
+          <button
+            v-if="state.tasksDone.value < state.tasks.value.length"
+            type="button"
+            class="mint-onboarding-help__link mint-onboarding-help__hide"
+            @click="state.setChecklistHidden(!state.checklistHidden.value)"
+          >
+            {{ state.checklistHidden.value ? 'Show checklist in the top bar' : 'Hide checklist from the top bar' }}
+          </button>
+        </template>
+
+        <template v-if="state.tours.value.length">
+          <div class="mint-onboarding-help__section">Tours</div>
+          <button
+            v-for="tour in state.tours.value"
+            :key="tour.id"
+            type="button"
+            class="mint-menu-item"
+            @click="run(() => state.startTour(tour.id))"
+          >
+            <Play class="mint-onboarding-help__icon" aria-hidden="true" />
+            {{ tour.title }}
+          </button>
+        </template>
+
+        <template v-if="state.news.value.length">
+          <div class="mint-onboarding-help__section">What's new</div>
+          <button
+            v-for="item in state.news.value"
+            :key="item.id"
+            type="button"
+            class="mint-menu-item"
+            @click="run(() => state.showNews(item.id))"
+          >
+            {{ item.title }}
+            <span v-if="item.unseen" class="mint-onboarding-help__new">New</span>
+          </button>
+        </template>
+      </div>
+    </Teleport>
+  </div>
+  <OnboardingLayerInternal :state="state" />
+</template>

package/src/components/internal/OnboardingLayerInternal.vue

@@ -0,0 +1,173 @@
+<script setup lang="ts">
+/**
+ * The tour layer: a scrim with a hole over the anchor, the step card, and the
+ * what's-new dots. AppTopBar renders it when the app provides onboarding.
+ */
+import { computed, nextTick, onBeforeUnmount, ref, useId, watch } from 'vue'
+import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom'
+import { X } from 'lucide-vue-next'
+import BaseButton from '../BaseButton.vue'
+import { useEventListener } from '../../composables/useEventListener'
+import type { OnboardingState } from '../../composables/useOnboarding'
+
+const props = defineProps<{ state: OnboardingState }>()
+
+// Space between the anchor and the edge of the hole.
+const HOLE_PAD = 4
+
+const active = computed(() => props.state.active.value)
+const card = ref<HTMLElement | null>(null)
+const hole = ref<DOMRect | null>(null)
+const cardPosition = ref({ x: 0, y: 0 })
+const titleId = useId()
+let stopAutoUpdate: (() => void) | undefined
+
+async function position() {
+  const current = active.value
+  if (!current || !card.value) return
+  hole.value = current.element.getBoundingClientRect()
+  const { x, y } = await computePosition(current.element, card.value, {
+    strategy: 'fixed',
+    placement: current.step.placement ?? 'bottom',
+    middleware: [offset(12), flip(), shift({ padding: 12 })],
+  })
+  // The step may have changed while the position was computed.
+  if (active.value === current) cardPosition.value = { x, y }
+}
+
+// Focus goes back where it was when the run ends.
+let returnFocus: HTMLElement | null = null
+watch(active, async (current, previous) => {
+  stopAutoUpdate?.()
+  stopAutoUpdate = undefined
+  hole.value = null
+  if (current && !previous) returnFocus = document.activeElement as HTMLElement | null
+  if (!current) {
+    if (returnFocus?.isConnected) returnFocus.focus()
+    returnFocus = null
+    return
+  }
+  await nextTick()
+  if (!card.value || active.value !== current) return
+  current.element.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+  stopAutoUpdate = autoUpdate(current.element, card.value, () => void position())
+  // A click step: the keyboard user presses the control itself.
+  if (current.step.advanceOn === 'click') current.element.focus()
+  // Otherwise the card itself: no focus ring on load, and Tab reaches Back and Next.
+  else card.value.focus()
+}, { immediate: true })
+onBeforeUnmount(() => stopAutoUpdate?.())
+
+// The layer is its own focus trap: Tab cycles over the card's buttons (and the
+// anchor on a click step), never the page behind; from the card itself Tab goes
+// to the first stop and Shift+Tab to the last.
+useEventListener(document, 'keydown', (event) => {
+  const current = active.value
+  if (!current || !card.value) return
+  // Keys belong to the tour only while focus is on its card, its anchor, or nowhere.
+  const focused = document.activeElement
+  if (focused && focused !== document.body && !card.value.contains(focused) && focused !== current.element) return
+  const onCard = focused === card.value
+  if (event.key === 'Escape') {
+    event.stopPropagation()
+    props.state.dismiss()
+  } else if (event.key === 'Tab') {
+    const buttons = [...card.value.querySelectorAll<HTMLElement>('button')]
+    const stops = current.step.advanceOn === 'click' ? [current.element, ...buttons] : buttons
+    const at = stops.indexOf(document.activeElement as HTMLElement)
+    const target = at === -1 ? (event.shiftKey ? stops.length - 1 : 0) : (at + (event.shiftKey ? -1 : 1) + stops.length) % stops.length
+    event.preventDefault()
+    stops[target].focus()
+  } else if (event.key === 'Enter' && onCard && current.step.advanceOn !== 'click') {
+    event.preventDefault()
+    props.state.next()
+  }
+}, { capture: true })
+
+const holeStyle = computed(() => hole.value && {
+  left: `${hole.value.left - HOLE_PAD}px`,
+  top: `${hole.value.top - HOLE_PAD}px`,
+  width: `${hole.value.width + 2 * HOLE_PAD}px`,
+  height: `${hole.value.height + 2 * HOLE_PAD}px`,
+})
+// advanceOn 'click': cut the hole out of the click blocker, so the anchor takes the click.
+const blockerStyle = computed(() => {
+  const rect = hole.value
+  if (!rect || active.value?.step.advanceOn !== 'click') return undefined
+  const [x, y, w, h] = [rect.left - HOLE_PAD, rect.top - HOLE_PAD, rect.width + 2 * HOLE_PAD, rect.height + 2 * HOLE_PAD]
+  return { clipPath: `path(evenodd, 'M0 0H${window.innerWidth}V${window.innerHeight}H0Z M${x} ${y}h${w}v${h}h${-w}Z')` }
+})
+const isLast = computed(() => !!active.value && active.value.index === active.value.count - 1)
+const nextLabel = computed(() => active.value?.news ? 'Got it' : isLast.value ? 'Done' : 'Next')
+
+// What's-new dots: one on each element with unseen news, hidden while a card shows.
+const dots = ref<Array<{ id: string; title: string; x: number; y: number }>>([])
+let frame = 0
+function placeDots() {
+  cancelAnimationFrame(frame)
+  frame = requestAnimationFrame(() => {
+    dots.value = active.value ? [] : props.state.news.value.flatMap((item) => {
+      if (!item.unseen) return []
+      const element = document.querySelector(`[data-onboarding="${CSS.escape(item.anchor)}"]`)
+      if (!element) return []
+      const rect = element.getBoundingClientRect()
+      return rect.width ? [{ id: item.id, title: item.title, x: rect.right, y: rect.top }] : []
+    })
+  })
+}
+const observer = new MutationObserver(placeDots)
+watch(() => props.state.unseenNews.value > 0, (watching) => {
+  observer.disconnect()
+  if (watching) observer.observe(document.body, { childList: true, subtree: true })
+  placeDots()
+}, { immediate: true })
+watch(active, placeDots)
+useEventListener(window, 'resize', placeDots)
+useEventListener(window, 'scroll', placeDots, { capture: true, passive: true })
+onBeforeUnmount(() => {
+  observer.disconnect()
+  cancelAnimationFrame(frame)
+})
+</script>
+
+<template>
+  <Teleport to="body">
+    <button
+      v-for="dot in dots"
+      :key="dot.id"
+      type="button"
+      class="mint-onboarding__dot"
+      :style="{ left: `${dot.x}px`, top: `${dot.y}px` }"
+      :aria-label="`New: ${dot.title}`"
+      @click="state.showNews(dot.id)"
+    />
+    <div v-if="active" class="mint-onboarding">
+      <div class="mint-onboarding__blocker" :style="blockerStyle" />
+      <div v-if="holeStyle" class="mint-onboarding__hole" :style="holeStyle" />
+      <div
+        ref="card"
+        class="mint-onboarding__card"
+        role="dialog"
+        aria-modal="true"
+        :aria-labelledby="titleId"
+        tabindex="-1"
+        :style="{ left: `${cardPosition.x}px`, top: `${cardPosition.y}px` }"
+      >
+        <button type="button" class="mint-onboarding__close" :aria-label="active.news ? 'Close' : 'Close tour'" @click="state.dismiss()">
+          <X :size="14" aria-hidden="true" />
+        </button>
+        <span v-if="active.count > 1" class="mint-onboarding__count">
+          <span aria-hidden="true">{{ active.index + 1 }} / {{ active.count }}</span>
+          <span class="mint-onboarding__sr">Step {{ active.index + 1 }} of {{ active.count }}</span>
+        </span>
+        <p :id="titleId" class="mint-onboarding__title">{{ active.step.title }}</p>
+        <p class="mint-onboarding__body">{{ active.step.body }}</p>
+        <div class="mint-onboarding__footer">
+          <span v-if="active.step.advanceOn === 'click'" class="mint-onboarding__hint">Click the highlighted control.</span>
+          <BaseButton v-if="active.index > 0" variant="ghost" size="sm" @click="state.back()">Back</BaseButton>
+          <BaseButton v-if="active.step.advanceOn !== 'click'" size="sm" @click="state.next()">{{ nextLabel }}</BaseButton>
+        </div>
+      </div>
+    </div>
+  </Teleport>
+</template>