@leavepulse/ui 0.56.0 → 0.57.0

package/src/components/LpTour.vue

@@ -0,0 +1,338 @@
+<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
+  if (typeof raw === "function") return raw()
+  if (typeof raw !== "string") return raw.isConnected ? raw : null
+  return hints.element(raw) ?? document.querySelector(raw)
+}
+
+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
+  await current.enter?.({ onLeave: (fn) => leaving.push(fn), onEnd: (fn) => cleanups.push(fn) })
+  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 leave() {
+  for (const cleanup of leaving.splice(0).reverse()) cleanup()
+}
+
+function end() {
+  token++
+  leave()
+  cancelAnimationFrame(frame)
+  frame = 0
+  target.value = null
+  box.value = null
+  for (const cleanup of cleanups.splice(0).reverse()) cleanup()
+}
+
+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) {

package/src/composables/useHints.ts

@@ -0,0 +1,151 @@
+import { shallowReactive, type Directive } from "vue"
+
+/*
+ * Which parts of the interface the user can see right now, and which ones they
+ * actually use — the ground truth a tour, a "new" badge or a nudge needs.
+ *
+ * The element carries its own id (`v-hint="'branches.remind'"`), so a tour is
+ * built from what is on screen, in whatever order the app wants: a button the
+ * user has no right to is not rendered, therefore not hinted, and nobody keeps
+ * a second list of steps that drifts away from the page.
+ *
+ * Three signals, all per id:
+ *   mounted — the element is in the DOM (reactive, for "is it here at all");
+ *   seen    — it stayed at least half on screen for SEEN_MS, once per mount,
+ *             so scrolling past a row of buttons does not count as seeing them;
+ *   used    — the user clicked it. Non-click use (a shortcut, a saved view) is
+ *             reported with `hints.use(id)`.
+ *
+ * The kit decides nothing beyond that. Whether to badge, explain or nudge is
+ * the app's call, made from these events.
+ */
+
+export type HintEvent = "seen" | "used" | "hover"
+type Listener = (id: string, el: HTMLElement) => void
+
+const SEEN_MS = 800
+const SEEN_RATIO = 0.5
+
+const mounted = shallowReactive(new Map<string, Set<HTMLElement>>())
+const listeners: Record<HintEvent, Set<Listener>> = { seen: new Set(), used: new Set(), hover: new Set() }
+const idOf = new WeakMap<HTMLElement, string>()
+const timers = new WeakMap<HTMLElement, ReturnType<typeof setTimeout>>()
+const seenOnce = new WeakSet<HTMLElement>()
+
+function emit(event: HintEvent, id: string, el: HTMLElement) {
+  for (const listener of listeners[event]) listener(id, el)
+}
+
+let observer: IntersectionObserver | null = null
+
+function watchSight(el: HTMLElement) {
+  if (typeof IntersectionObserver === "undefined") {
+    seenOnce.add(el)
+    emit("seen", idOf.get(el)!, el)
+    return
+  }
+  observer ??= new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        const target = entry.target as HTMLElement
+        const id = idOf.get(target)
+        if (!id || seenOnce.has(target)) continue
+        clearTimeout(timers.get(target))
+        if (entry.intersectionRatio >= SEEN_RATIO) {
+          timers.set(
+            target,
+            setTimeout(() => {
+              seenOnce.add(target)
+              observer?.unobserve(target)
+              emit("seen", id, target)
+            }, SEEN_MS),
+          )
+        }
+      }
+    },
+    { threshold: [0, SEEN_RATIO] },
+  )
+  observer.observe(el)
+}
+
+function onClick(event: Event) {
+  const el = event.currentTarget as HTMLElement
+  const id = idOf.get(el)
+  if (id) emit("used", id, el)
+}
+
+function onHover(event: Event) {
+  const el = event.currentTarget as HTMLElement
+  const id = idOf.get(el)
+  if (id) emit("hover", id, el)
+}
+
+function attach(el: HTMLElement, id: string) {
+  idOf.set(el, id)
+  el.dataset.hint = id
+  const set = mounted.get(id) ?? new Set<HTMLElement>()
+  set.add(el)
+  mounted.set(id, new Set(set))
+  el.addEventListener("click", onClick, { capture: true })
+  el.addEventListener("pointerenter", onHover)
+  el.addEventListener("focusin", onHover)
+  watchSight(el)
+}
+
+function detach(el: HTMLElement) {
+  const id = idOf.get(el)
+  if (!id) return
+  clearTimeout(timers.get(el))
+  observer?.unobserve(el)
+  el.removeEventListener("click", onClick, { capture: true })
+  el.removeEventListener("pointerenter", onHover)
+  el.removeEventListener("focusin", onHover)
+  const set = new Set(mounted.get(id))
+  set.delete(el)
+  if (set.size) mounted.set(id, set)
+  else mounted.delete(id)
+  idOf.delete(el)
+}
+
+/** `v-hint="'page.feature'"` on the element that represents a feature. */
+export const vHint: Directive<HTMLElement, string | null | undefined> = {
+  mounted(el, binding) {
+    if (binding.value) attach(el, binding.value)
+  },
+  updated(el, binding) {
+    if (binding.value === idOf.get(el)) return
+    detach(el)
+    if (binding.value) attach(el, binding.value)
+  },
+  beforeUnmount(el) {
+    detach(el)
+  },
+}
+
+export const hints = {
+  /** Ids of everything hinted that is in the DOM now. Reactive. */
+  ids(): string[] {
+    return [...mounted.keys()]
+  },
+  /** Whether an element with this id is in the DOM. Reactive. */
+  present(id: string): boolean {
+    return mounted.has(id)
+  },
+  /** The first connected element with this id that has a box, or null. */
+  element(id: string): HTMLElement | null {
+    for (const el of mounted.get(id) ?? []) {
+      if (el.isConnected && el.getClientRects().length) return el
+    }
+    return null
+  },
+  /** Subscribe to a signal; returns the unsubscribe. */
+  on(event: HintEvent, listener: Listener): () => void {
+    listeners[event].add(listener)
+    return () => listeners[event].delete(listener)
+  },
+  /** Report use that is not a click on the element. */
+  use(id: string): void {
+    const el = hints.element(id)
+    for (const listener of listeners.used) listener(id, el ?? document.body)
+  },
+}

package/src/composables/useMediaQuery.ts

@@ -0,0 +1,20 @@
+import { onBeforeUnmount, onMounted, ref, type Ref } from "vue"
+
+/*
+ * A media query as a ref. False until mounted, so the server and the hydrating
+ * client render the same thing and the client switches right after.
+ */
+export function useMediaQuery(query: string): Ref<boolean> {
+  const matches = ref(false)
+  let list: MediaQueryList | undefined
+  const update = () => {
+    matches.value = !!list?.matches
+  }
+  onMounted(() => {
+    list = window.matchMedia?.(query)
+    update()
+    list?.addEventListener("change", update)
+  })
+  onBeforeUnmount(() => list?.removeEventListener("change", update))
+  return matches
+}