@leavepulse/ui 0.56.0 → 0.58.0

package/src/components/LpTableOfContents.vue

@@ -12,6 +12,7 @@
 import { Motion } from "motion-v"
 import { computed, onBeforeUnmount, onMounted, ref, useId, watch } from "vue"
 import { useLabels } from "../composables/useLpConfig"
+import { scrollParent } from "../composables/scroll"
 import { usePillTransition } from "../composables/usePillTransition"
 
 export interface TocLink {
@@ -113,24 +114,11 @@ function unfreeze() {
   safetyTimer = null
 }
 
-/*
- * The element that actually scrolls to the heading. Inside an app shell that is
- * a scroll region, not the window, and watching window.scrollY there saw no
- * movement and unfroze on the first frame.
- */
-function scrollerOf(el: HTMLElement): HTMLElement | null {
-  for (let node = el.parentElement; node; node = node.parentElement) {
-    const { overflowY } = getComputedStyle(node)
-    if (/(auto|scroll|overlay)/.test(overflowY) && node.scrollHeight > node.clientHeight) return node
-  }
-  return null
-}
-
 function suppressSpyUntilScrollEnds(target: HTMLElement) {
   spySuppressed = true
   if (rafId != null) cancelAnimationFrame(rafId)
   if (safetyTimer != null) clearTimeout(safetyTimer)
-  const scroller = scrollerOf(target)
+  const scroller = scrollParent(target)
   const position = () => (scroller ? scroller.scrollTop : window.scrollY)
   let last = position()
   const tick = () => {

package/src/components/LpTooltip.vue

@@ -42,6 +42,7 @@ import {
   type SpringState,
 } from "../composables/usePillTransition"
 import { PANEL_SURFACE, TOOLTIP_ANIM } from "./dropdown"
+import { prefersReducedMotion } from "../composables/easing"
 
 const props = withDefaults(
   defineProps<{
@@ -116,9 +117,6 @@ const shared = injectTooltipProviderContext(null)
  */
 const PassThrough: FunctionalComponent = (_, { slots }) => slots.default?.()
 
-const reducedMotion = () =>
-  typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
-
 const target = { x: 0, y: 0 }
 const offset = ref({ x: 0, y: 0 })
 
@@ -174,7 +172,7 @@ const onPointerMove = (e: PointerEvent) => {
   const dir = props.side === "bottom" ? -1 : 1
   target.y = e.clientY - (rect.top + rect.height / 2) + half * dir
   // Without motion the tip goes straight to the reading instead of trailing.
-  if (reducedMotion()) {
+  if (prefersReducedMotion()) {
     offset.value = { x: target.x, y: target.y }
     return
   }

package/src/components/LpTour.vue

@@ -0,0 +1,358 @@
+<script lang="ts">
+export interface TourContext {
+  /** Undo something when this step is left, in either direction (close the menu it opened). */
+  onLeave(cleanup: () => void): void
+  /** Undo something when the tour ends, for what several steps share (a dialog they all live in). */
+  onEnd(cleanup: () => void): void
+}
+
+export interface TourStep {
+  /**
+   * What to point at: a `v-hint` id, a CSS selector, an element or a getter.
+   * Left out, the step is a centred card with nothing highlighted (an intro).
+   * A target that never appears is skipped, so a step for a control the user
+   * cannot see costs nothing.
+   */
+  target?: string | Element | (() => Element | null)
+  title: string
+  text?: string
+  /** A shortcut for the same action, shown as keycaps ("Ctrl+K"). */
+  keys?: string
+  side?: "top" | "right" | "bottom" | "left"
+  /**
+   * Ask the user to press the highlighted control themselves; the tour moves
+   * on when they do. Doing it beats reading about it.
+   */
+  try?: boolean
+  /** With `try`, a "do it for me" button runs this instead. */
+  perform?: () => void | Promise<void>
+  /** Runs before the step shows: open the dialog or tab its target lives in. */
+  enter?: (context: TourContext) => void | Promise<void>
+}
+</script>
+
+<script setup lang="ts">
+/*
+ * A guided walk over the real interface: the target is lit through a dim
+ * scrim, a card beside it says what it is, and the user steps through with the
+ * buttons or the arrow keys.
+ *
+ * The scrim is four panels around a hole rather than a mask, so the target
+ * stays clickable (a `try` step waits for exactly that click) and the hole can
+ * glide between targets on any engine, WebKitGTK included. The card is a reka
+ * popover anchored to the hole, so flipping and sliding to stay on screen is
+ * floating-ui's job; on a phone it becomes a sheet at the bottom instead.
+ *
+ * Whatever a step opens through `enter` it undoes through `onLeave` (gone when
+ * the step is) or `onEnd` (shared by the steps after it), and the tour runs
+ * those however it ends: finished, closed, Escape, or unmounted by a route
+ * change. A tour must leave the page as it found it.
+ */
+import { PopoverAnchor, PopoverContent, PopoverPortal, PopoverRoot } from "reka-ui"
+import { computed, nextTick, onBeforeUnmount, ref, shallowRef, watch } from "vue"
+import { prefersReducedMotion } from "../composables/easing"
+import { hints } from "../composables/useHints"
+import { useHotkeys } from "../composables/useHotkeys"
+import { useLabels } from "../composables/useLpConfig"
+import { useMediaQuery } from "../composables/useMediaQuery"
+import { scrollToElement } from "../composables/scroll"
+import { PANEL_SURFACE } from "./dropdown"
+import TourCard from "./TourCard.vue"
+import type { Box } from "../composables/spatialNav"
+import { holeOf, panelsAround } from "./tour"
+
+const props = withDefaults(
+  defineProps<{
+    steps: TourStep[]
+    /** Room around the target inside the lit hole, px. */
+    padding?: number
+    labels?: Partial<typeof DEFAULT_LABELS>
+  }>(),
+  { padding: 6 },
+)
+
+const emit = defineEmits<{
+  /** The last step was passed. */
+  (e: "finish"): void
+  /** Closed early, on this step index. */
+  (e: "dismiss", index: number): void
+}>()
+
+const open = defineModel<boolean>("open", { default: false })
+const index = defineModel<number>("step", { default: 0 })
+
+const DEFAULT_LABELS = {
+  next: "Next",
+  back: "Back",
+  done: "Done",
+  close: "Close tour",
+  progress: "{n} of {total}",
+  perform: "Do it for me",
+  tryIt: "Try it: press the highlighted control.",
+}
+const labels = useLabels("tour", DEFAULT_LABELS, () => props.labels)
+
+const WAIT_MS = 800
+const TRY_SETTLE_MS = 120
+
+const wide = useMediaQuery("(min-width: 640px)")
+const step = computed<TourStep | undefined>(() => props.steps[index.value])
+const target = shallowRef<Element | null>(null)
+const box = ref<Box | null>(null)
+const viewport = ref({ width: 0, height: 0 })
+const ready = ref(false)
+const cleanups: (() => void)[] = []
+const leaving: (() => void)[] = []
+let frame = 0
+let token = 0
+let direction = 1
+
+const hole = computed(() => (box.value ? holeOf(box.value, props.padding, viewport.value) : null))
+const panels = computed(() =>
+  hole.value
+    ? panelsAround(hole.value, viewport.value)
+    : [{ x: 0, y: 0, width: viewport.value.width, height: viewport.value.height }],
+)
+const reference = {
+  getBoundingClientRect: () => {
+    const h = hole.value
+    return h ? new DOMRect(h.x, h.y, h.width, h.height) : new DOMRect(viewport.value.width / 2, viewport.value.height / 2, 0, 0)
+  },
+}
+const last = computed(() => index.value >= props.steps.length - 1)
+const progress = computed(() => labels.value.progress.replace("{n}", String(index.value + 1)).replace("{total}", String(props.steps.length)))
+const smooth = () => !prefersReducedMotion()
+
+function resolve(raw: TourStep["target"]): Element | null {
+  if (!raw) return null
+  try {
+    if (typeof raw === "function") return raw()
+    if (typeof raw !== "string") return raw.isConnected ? raw : null
+    return hints.element(raw) ?? document.querySelector(raw)
+  } catch {
+    return null
+  }
+}
+
+function waitFor(raw: TourStep["target"], mine: number): Promise<Element | null> {
+  const started = performance.now()
+  return new Promise((done) => {
+    const tick = () => {
+      if (mine !== token) return done(null)
+      const el = resolve(raw)
+      if (el && el.getClientRects().length) return done(el)
+      if (performance.now() - started > WAIT_MS) return done(null)
+      requestAnimationFrame(tick)
+    }
+    tick()
+  })
+}
+
+function measure() {
+  viewport.value = { width: window.innerWidth, height: window.innerHeight }
+  const el = target.value
+  if (!el || !el.isConnected) {
+    box.value = null
+    return
+  }
+  const r = el.getBoundingClientRect()
+  const prev = box.value
+  if (!prev || prev.x !== r.x || prev.y !== r.y || prev.width !== r.width || prev.height !== r.height) {
+    box.value = { x: r.x, y: r.y, width: r.width, height: r.height }
+  }
+}
+
+function track() {
+  measure()
+  frame = requestAnimationFrame(track)
+}
+
+async function show(): Promise<void> {
+  const mine = ++token
+  ready.value = false
+  leave()
+  const current = step.value
+  if (!current) return
+  try {
+    await current.enter?.({ onLeave: (fn) => leaving.push(fn), onEnd: (fn) => cleanups.push(fn) })
+  } catch (error) {
+    console.warn("[LpTour] step skipped, its enter() failed:", error)
+    if (mine === token) skip()
+    return
+  }
+  if (mine !== token) return
+  if (!current.target) {
+    target.value = null
+    measure()
+    ready.value = true
+    return
+  }
+  const el = current.enter ? await waitFor(current.target, mine) : resolve(current.target)
+  if (mine !== token) return
+  if (!el || !el.getClientRects().length) return skip()
+  target.value = el
+  scrollToElement(el, { block: wide.value ? "nearest" : "center", behavior: smooth() ? "smooth" : "auto", margin: 48 })
+  await nextTick()
+  measure()
+  ready.value = true
+}
+
+function skip(): Promise<void> | void {
+  const nextIndex = index.value + direction
+  if (nextIndex < 0 || nextIndex >= props.steps.length) return direction > 0 ? finish() : show()
+  index.value = nextIndex
+}
+
+function next(): void {
+  direction = 1
+  if (last.value) return finish()
+  index.value += 1
+}
+
+function back() {
+  if (index.value === 0) return
+  direction = -1
+  index.value -= 1
+}
+
+function forward() {
+  if (!step.value?.try) next()
+}
+
+async function perform() {
+  await step.value?.perform?.()
+  setTimeout(next, TRY_SETTLE_MS)
+}
+
+function runAll(list: (() => void)[]) {
+  for (const cleanup of list.splice(0).reverse()) {
+    try {
+      cleanup()
+    } catch (error) {
+      console.warn("[LpTour] cleanup failed:", error)
+    }
+  }
+}
+
+function leave() {
+  runAll(leaving)
+}
+
+function end() {
+  token++
+  leave()
+  cancelAnimationFrame(frame)
+  frame = 0
+  target.value = null
+  box.value = null
+  runAll(cleanups)
+}
+
+function finish(): void {
+  open.value = false
+  emit("finish")
+}
+
+function dismiss() {
+  const at = index.value
+  open.value = false
+  emit("dismiss", at)
+}
+
+function onTargetClick(event: Event) {
+  if (!step.value?.try || !target.value) return
+  if (event.target instanceof Node && target.value.contains(event.target)) setTimeout(next, TRY_SETTLE_MS)
+}
+
+watch(
+  open,
+  (value) => {
+    if (value) {
+      direction = 1
+      document.addEventListener("click", onTargetClick, true)
+      frame ||= requestAnimationFrame(track)
+      void show()
+    } else {
+      document.removeEventListener("click", onTargetClick, true)
+      end()
+    }
+  },
+  { immediate: true },
+)
+
+watch(index, () => {
+  if (open.value) void show()
+})
+
+onBeforeUnmount(() => {
+  document.removeEventListener("click", onTargetClick, true)
+  if (open.value) end()
+})
+
+useHotkeys(
+  () => [
+    { key: "Escape", handler: dismiss, overLayers: true, allowInInput: true },
+    { key: "ArrowRight", handler: forward, overLayers: true },
+    { key: "Enter", handler: forward, overLayers: true },
+    { key: "ArrowLeft", handler: back, overLayers: true },
+  ],
+  { enabled: open, priority: 100 },
+)
+
+const CARD = `${PANEL_SURFACE} rounded-card w-80 max-w-[calc(100vw-24px)] p-4 text-sm text-ink outline-none`
+</script>
+
+<template>
+  <Teleport to="body">
+    <div v-if="open" class="lp-tour pointer-events-none fixed inset-0 z-(--z-tour)" @pointerdown.stop>
+      <div
+        v-for="(panel, i) in panels"
+        :key="i"
+        class="lp-scrim pointer-events-auto absolute left-0 top-0 transition-[transform,width,height] duration-[var(--duration-medium)] ease-[var(--ease-emphasized)] motion-reduce:transition-none"
+        :style="{ transform: `translate(${panel.x}px, ${panel.y}px)`, width: `${panel.width}px`, height: `${panel.height}px` }"
+      />
+      <div
+        v-if="hole"
+        class="absolute left-0 top-0 rounded-control ring-2 ring-brand transition-[transform,width,height] duration-[var(--duration-medium)] ease-[var(--ease-emphasized)] motion-reduce:transition-none"
+        :class="step?.try ? 'pointer-events-none animate-pulse' : 'pointer-events-auto'"
+        :style="{ transform: `translate(${hole.x}px, ${hole.y}px)`, width: `${hole.width}px`, height: `${hole.height}px` }"
+      />
+    </div>
+
+    <PopoverRoot v-if="open && wide" :open="ready">
+      <PopoverAnchor :reference="reference" />
+      <PopoverPortal>
+        <PopoverContent
+          :side="step?.side ?? 'bottom'"
+          :side-offset="12"
+          :collision-padding="12"
+          update-position-strategy="always"
+          :trap-focus="false"
+          :class="[CARD, 'z-[calc(var(--z-tour)+1)] data-[state=open]:animate-[popover-in_var(--duration-medium)_var(--ease-emphasized)] motion-reduce:animate-none']"
+          role="dialog"
+          :aria-label="step?.title"
+          @pointerdown.stop
+          @interact-outside.prevent
+          @escape-key-down.prevent
+          @focus-outside.prevent
+        >
+          <slot name="card" :step="step" :index="index" :next="next" :back="back" :dismiss="dismiss">
+            <TourCard :step="step" :index="index" :last="last" :progress="progress" :labels="labels" @next="next" @back="back" @perform="perform" @dismiss="dismiss" />
+          </slot>
+        </PopoverContent>
+      </PopoverPortal>
+    </PopoverRoot>
+
+    <div
+      v-if="open && !wide && ready"
+      :class="[CARD, 'pointer-events-auto fixed inset-x-3 bottom-3 z-[calc(var(--z-tour)+1)] w-auto animate-[rise-in_var(--duration-medium)_var(--ease-emphasized)] motion-reduce:animate-none']"
+      role="dialog"
+      :aria-label="step?.title"
+      @pointerdown.stop
+    >
+      <slot name="card" :step="step" :index="index" :next="next" :back="back" :dismiss="dismiss">
+            <TourCard :step="step" :index="index" :last="last" :progress="progress" :labels="labels" @next="next" @back="back" @perform="perform" @dismiss="dismiss" />
+          </slot>
+    </div>
+  </Teleport>
+</template>

package/src/components/TourCard.vue

@@ -0,0 +1,41 @@
+<script setup lang="ts">
+import type { TourStep } from "./LpTour.vue"
+import LpButton from "./LpButton.vue"
+import LpIcon from "./LpIcon.vue"
+import LpKeys from "./LpKeys.vue"
+
+defineProps<{
+  step: TourStep | undefined
+  index: number
+  last: boolean
+  progress: string
+  labels: { next: string; back: string; done: string; close: string; perform: string; tryIt: string }
+}>()
+
+defineEmits<{
+  (e: "next"): void
+  (e: "back"): void
+  (e: "perform"): void
+  (e: "dismiss"): void
+}>()
+</script>
+
+<template>
+  <div class="flex items-start justify-between gap-3">
+    <p class="font-medium" aria-live="polite">{{ step?.title }}</p>
+    <button type="button" class="text-muted hover:text-ink" :aria-label="labels.close" @click="$emit('dismiss')">
+      <LpIcon name="lucide:x" class="size-4" />
+    </button>
+  </div>
+  <p v-if="step?.text" class="mt-1.5 text-muted">{{ step.text }}</p>
+  <LpKeys v-if="step?.keys" :combo="step.keys" size="sm" class="mt-2" />
+  <p v-if="step?.try" class="mt-2 text-xs text-brand">{{ labels.tryIt }}</p>
+  <div class="mt-4 flex items-center justify-between gap-2">
+    <span class="text-xs tabular-nums text-muted">{{ progress }}</span>
+    <div class="flex gap-2">
+      <LpButton v-if="index > 0" size="sm" variant="ghost" @click="$emit('back')">{{ labels.back }}</LpButton>
+      <LpButton v-if="step?.try && step.perform" size="sm" variant="outline" @click="$emit('perform')">{{ labels.perform }}</LpButton>
+      <LpButton size="sm" :variant="step?.try ? 'ghost' : undefined" @click="$emit('next')">{{ last ? labels.done : labels.next }}</LpButton>
+    </div>
+  </div>
+</template>

package/src/components/tour.ts

@@ -0,0 +1,57 @@
+/*
+ * Geometry for LpTour, kept out of the component so it can be tested without a
+ * DOM: where the spotlight hole goes and what the dim panels around it cover.
+ * Placing the step card is reka's popper (floating-ui), anchored to the hole.
+ */
+
+import type { Box } from "../composables/spatialNav"
+
+type Size = { width: number; height: number }
+
+/** The hole around a target: padded, then clipped to the viewport so a tall
+ * target never pushes the dim panels off-screen. */
+export function holeOf(target: Box, padding: number, viewport: Size): Box {
+  const x = Math.max(0, target.x - padding)
+  const y = Math.max(0, target.y - padding)
+  const right = Math.min(viewport.width, target.x + target.width + padding)
+  const bottom = Math.min(viewport.height, target.y + target.height + padding)
+  return { x, y, width: Math.max(0, right - x), height: Math.max(0, bottom - y) }
+}
+
+/** The four dim panels around a hole: top, bottom, left, right. */
+export function panelsAround(hole: Box, viewport: Size): Box[] {
+  const bottom = hole.y + hole.height
+  return [
+    { x: 0, y: 0, width: viewport.width, height: hole.y },
+    { x: 0, y: bottom, width: viewport.width, height: Math.max(0, viewport.height - bottom) },
+    { x: 0, y: hole.y, width: hole.x, height: hole.height },
+    { x: hole.x + hole.width, y: hole.y, width: Math.max(0, viewport.width - hole.x - hole.width), height: hole.height },
+  ]
+}
+
+/**
+ * Open the context menu of an element as a right-click would, at its centre.
+ * Lets a tour step show a row's menu without the user hunting for it; the menu
+ * itself is whatever the app already wires to that element.
+ *
+ * Returns the way to close it again: a press outside the menu, which every
+ * dismissable layer honours. Not Escape — that key also closes whatever is on
+ * top, a tour included, and would end the walk instead of the menu.
+ */
+export function openContextMenu(el: Element): () => void {
+  const box = el.getBoundingClientRect()
+  el.dispatchEvent(
+    new MouseEvent("contextmenu", {
+      bubbles: true,
+      cancelable: true,
+      button: 2,
+      clientX: box.left + box.width / 2,
+      clientY: box.top + box.height / 2,
+    }),
+  )
+  return () => {
+    const outside = { bubbles: true, cancelable: true, clientX: 0, clientY: 0 }
+    document.body.dispatchEvent(new PointerEvent("pointerdown", outside))
+    document.body.dispatchEvent(new PointerEvent("pointerup", outside))
+  }
+}

package/src/composables/scroll.ts

@@ -0,0 +1,54 @@
+/*
+ * The element that actually scrolls, and scrolling it to show a child. Inside an
+ * app shell that is a scroll region, not the window, and `scrollIntoView` moves
+ * every scrollable ancestor at once, including `overflow: hidden` wrappers that
+ * then sit shifted with no way back for the user.
+ */
+
+const SCROLLS = /(auto|scroll|overlay)/
+
+export interface ScrollParentOptions {
+  /** Which overflow counts: vertical (default), horizontal, or either. */
+  axis?: "y" | "x" | "both"
+  /** Start the search at the element itself rather than its parent. */
+  self?: boolean
+}
+
+/** The nearest ancestor that scrolls along `axis` and has something to scroll, or null. */
+export function scrollParent(el: Element | null | undefined, { axis = "y", self = false }: ScrollParentOptions = {}): HTMLElement | null {
+  for (let node = self ? (el as HTMLElement | null | undefined) : el?.parentElement; node; node = node.parentElement) {
+    if (node === document.body || node === document.documentElement) return null
+    const style = getComputedStyle(node)
+    const y = axis !== "x" && SCROLLS.test(style.overflowY) && node.scrollHeight > node.clientHeight
+    const x = axis !== "y" && SCROLLS.test(style.overflowX) && node.scrollWidth > node.clientWidth
+    if (y || x) return node
+  }
+  return null
+}
+
+export interface ScrollToElementOptions {
+  /** `nearest` scrolls only when the element is out of view. */
+  block?: "nearest" | "center" | "start"
+  behavior?: ScrollBehavior
+  /** Room kept between the element and the scroller's edge. */
+  margin?: number
+}
+
+/** Scroll the nearest scroller, and only it, so that `el` is in view. */
+export function scrollToElement(
+  el: Element | null | undefined,
+  { block = "nearest", behavior = "auto", margin = 0 }: ScrollToElementOptions = {},
+): void {
+  if (!el) return
+  const box = scrollParent(el) ?? (document.scrollingElement as HTMLElement | null)
+  if (!box) return
+  const outer = box === document.scrollingElement ? new DOMRect(0, 0, window.innerWidth, window.innerHeight) : box.getBoundingClientRect()
+  const inner = el.getBoundingClientRect()
+  const top = inner.top - outer.top + box.scrollTop
+  let target = box.scrollTop
+  if (block === "start") target = top - margin
+  else if (block === "center") target = top - (box.clientHeight - inner.height) / 2
+  else if (inner.top < outer.top + margin) target = top - margin
+  else if (inner.bottom > outer.bottom - margin) target = top - box.clientHeight + inner.height + margin
+  if (target !== box.scrollTop) box.scrollTo({ top: target, behavior })
+}

package/src/composables/useGamepadNav.ts

@@ -1,5 +1,6 @@
 import { onBeforeUnmount, onMounted, ref, type MaybeRefOrGetter, toValue } from "vue"
 import { focusableIn, nextInDirection, type Direction } from "./spatialNav"
+import { scrollParent } from "./scroll"
 
 /*
  * A game controller driving the interface: the D-pad and the left stick move
@@ -124,13 +125,7 @@ export function useGamepadNav(options: UseGamepadNavOptions = {}) {
   }
 
   function scrollBy(dx: number, dy: number) {
-    let element = document.activeElement as HTMLElement | null
-    while (element && element !== document.body) {
-      const style = getComputedStyle(element)
-      if (/(auto|scroll)/.test(style.overflowY + style.overflowX) && element.scrollHeight > element.clientHeight) break
-      element = element.parentElement
-    }
-    ;(element && element !== document.body ? element : document.scrollingElement)?.scrollBy(dx, dy)
+    ;(scrollParent(document.activeElement, { axis: "both", self: true }) ?? document.scrollingElement)?.scrollBy(dx, dy)
   }
 
   function poll(now: number) {