@leavepulse/ui 0.77.3 → 0.78.0

package/src/components/videoBackdrop.ts

@@ -3,6 +3,7 @@
  * so they can be tested without a media element.
  */
 
+import { clamp } from "../composables/clamp"
 import { splitTime } from "./timeSpan"
 
 /** The stretch of a clip that loops, and how long two passes overlap at the seam. */
@@ -29,16 +30,16 @@ export function planLoop(
   options: { start?: number; end?: number; crossfade?: number; minLength?: number } = {},
 ): LoopPlan {
   if (!Number.isFinite(duration) || duration <= 0) return { from: 0, to: 0, fade: 0 }
-  const clamp = (value: number) => Math.min(duration, Math.max(0, value))
-  let from = clamp(options.start ?? 0)
-  let to = clamp(options.end ?? duration)
+  const within = (value: number) => clamp(value, 0, duration)
+  let from = within(options.start ?? 0)
+  let to = within(options.end ?? duration)
   if (to < from) [from, to] = [to, from]
-  const minLength = Math.min(duration, Math.max(0, options.minLength ?? 0.5))
+  const minLength = clamp(options.minLength ?? 0.5, 0, duration)
   if (to - from < minLength) {
     to = Math.min(duration, from + minLength)
     from = Math.max(0, to - minLength)
   }
-  const fade = Math.min(Math.max(0, options.crossfade ?? 0), (to - from) / 2)
+  const fade = clamp(options.crossfade ?? 0, 0, (to - from) / 2)
   return { from, to, fade }
 }
 
@@ -55,7 +56,7 @@ export function seamReached(plan: LoopPlan, time: number): boolean {
  */
 export function seamProgress(plan: LoopPlan, incomingTime: number): number {
   if (plan.fade <= 0) return 1
-  return Math.min(1, Math.max(0, (incomingTime - plan.from) / plan.fade))
+  return clamp((incomingTime - plan.from) / plan.fade, 0, 1)
 }
 
 /** Whether the whole clip loops with nothing cut and no overlap, which the media element does natively. */

package/src/composables/clamp.ts

@@ -0,0 +1,2 @@
+/** `value` held between `min` and `max`. When they cross, `max` wins. */
+export const clamp = (value: number, min: number, max: number): number => Math.min(max, Math.max(min, value))

package/src/composables/devWarn.ts

@@ -0,0 +1,19 @@
+declare const process: { env: { NODE_ENV?: string } }
+
+/*
+ * Written as the literal `process.env.NODE_ENV` so the consumer's bundler
+ * replaces it (Vite and webpack both do for dependencies); where nothing
+ * replaces it and no `process` exists, warnings simply stay off.
+ */
+export function isDev(): boolean {
+  try {
+    return process.env.NODE_ENV !== "production"
+  } catch {
+    return false
+  }
+}
+
+/** A warning for the developer only. */
+export function devWarn(message: string): void {
+  if (isDev()) console.warn(`[@leavepulse/ui] ${message}`)
+}

package/src/composables/easing.ts

@@ -28,10 +28,33 @@
  * A plain function, not a reactive composable: it is read at the moment an
  * animation starts, and a component that also needs to RE-RENDER when the
  * setting changes mid-session should use `usePrefersReducedMotion`.
+ *
+ * Which one to use: a one-off animation reads this as it starts; anything that
+ * keeps running (a loop, a spring, a video) follows the reactive one or the
+ * media query's own change event, so it stops without a new action; a CSS
+ * transition uses `prefers-reduced-motion` in CSS.
+ *
+ * `win` is the window to ask, for a caller inside an LpFrame.
  */
-export const prefersReducedMotion = (): boolean =>
-  typeof window !== "undefined" &&
-  (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false)
+export const prefersReducedMotion = (win?: Window): boolean => {
+  const target = win ?? (typeof window === "undefined" ? undefined : window)
+  return target?.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false
+}
+
+/*
+ * Where a motion token is read from. A scoped theme (LpThemeProvider) or an
+ * LpFrame declares its tokens on its own element or document, so a caller with
+ * an element at hand passes it; without one it is the page's root.
+ */
+type TokenScope = Element | Document
+
+function readToken(name: string, scope?: TokenScope): string | null {
+  if (typeof window === "undefined") return null
+  const el = scope ? ("documentElement" in scope ? scope.documentElement : scope) : document.documentElement
+  const view = el.ownerDocument?.defaultView ?? window
+  if (!view.getComputedStyle) return null
+  return view.getComputedStyle(el).getPropertyValue(`--${name}`).trim()
+}
 
 /**
  * A motion token's value, for an API that cannot take a `var()`.
@@ -47,20 +70,21 @@ export const prefersReducedMotion = (): boolean =>
 export const easingToken = (
   name: "ease-emphasized" | "ease-travel" | "ease-settle",
   fallback = "cubic-bezier(0.2, 0, 0, 1)",
-): string => {
-  if (typeof window === "undefined" || !window.getComputedStyle) return fallback
-  const value = getComputedStyle(document.documentElement).getPropertyValue(`--${name}`).trim()
-  return value || fallback
-}
+  scope?: TokenScope,
+): string => readToken(name, scope) || fallback
 
 /**
  * A duration token in milliseconds, for an animation or a timer driven in
  * script. Same reasoning as `easingToken`: a typed-out 220 would not follow a
  * theme that retunes the token.
  */
-export const durationToken = (name: "duration-fast" | "duration-medium", fallback = 220): number => {
-  if (typeof window === "undefined" || !window.getComputedStyle) return fallback
-  const raw = getComputedStyle(document.documentElement).getPropertyValue(`--${name}`).trim()
+export const durationToken = (
+  name: "duration-fast" | "duration-medium",
+  fallback = 220,
+  scope?: TokenScope,
+): number => {
+  const raw = readToken(name, scope)
+  if (raw === null) return fallback
   const ms = Number.parseFloat(raw)
   return Number.isFinite(ms) ? (raw.endsWith("ms") || !raw.endsWith("s") ? ms : ms * 1000) : fallback
 }
@@ -156,8 +180,9 @@ export const cubicBezier = (x1: number, y1: number, x2: number, y2: number) => {
  */
 export const tokenEase = (
   name: "ease-emphasized" | "ease-travel" | "ease-settle",
+  scope?: TokenScope,
 ): ((t: number) => number) => {
-  const match = /cubic-bezier\(([^)]+)\)/.exec(easingToken(name))
+  const match = /cubic-bezier\(([^)]+)\)/.exec(easingToken(name, undefined, scope))
   const n = match?.[1].split(",").map((p) => Number.parseFloat(p))
   return n && n.length === 4 && n.every(Number.isFinite)
     ? cubicBezier(n[0], n[1], n[2], n[3])

package/src/composables/overlayHistory.ts

@@ -40,6 +40,8 @@
 
 const KEY = "__lpOverlay"
 const SETTLE_MS = 300
+/* Far longer than a traversal takes: past it, the step the kit asked for is not coming. */
+const STEP_TIMEOUT_MS = 1500
 
 export interface HistoryEntry {
   /** Back left this entry: undo what it recorded (close the overlay, restore the tab). */
@@ -91,6 +93,8 @@ interface EngineState {
   serial: number
   internal: boolean
   settle: number
+  /** Timer that gives up on `silent` pops the browser never delivers. */
+  stalled: number
 }
 
 const STATE_KEY = Symbol.for("@leavepulse/ui:overlay-history")
@@ -111,6 +115,7 @@ const fresh: EngineState = {
   serial: 0,
   internal: false,
   settle: 0,
+  stalled: 0,
 }
 const s = (g[STATE_KEY] ??= fresh)
 
@@ -142,10 +147,25 @@ function own<T>(run: () => T): T {
 function silentGo(delta: number) {
   if (delta === 0) return
   s.silent++
+  window.clearTimeout(s.stalled)
+  s.stalled = window.setTimeout(abandonSteps, STEP_TIMEOUT_MS)
   mute()
   own(() => history.go(delta))
 }
 
+/*
+ * `go` reports nothing: with no entry to go to, or a traversal the browser
+ * dropped, no pop ever comes. Left waiting, the engine would swallow the user's
+ * next Back, hold every push in `waiting` and keep the router muted for good.
+ */
+function abandonSteps() {
+  s.silent = 0
+  s.keep = null
+  s.href = location.href
+  flushWaiting()
+  mute()
+}
+
 /* Pushes wait for a pop the kit started: a push between `go` and its arrival would land on the wrong entry. */
 function whenSettled(run: () => void) {
   if (s.silent > 0) s.waiting.push(run)
@@ -182,6 +202,7 @@ function handlePop(event: PopStateEvent) {
   s.href = location.href
   if (s.silent > 0) {
     s.silent--
+    if (s.silent === 0) window.clearTimeout(s.stalled)
     const keep = s.silent === 0 ? s.keep : null
     if (s.silent === 0) s.keep = null
     if (keep && keep.href !== location.href) restore(keep, event)
@@ -322,6 +343,9 @@ export function setHistoryRouter(router: HistoryRouter | null): void {
   if (s.router && s.router !== router) s.router.listening = true
   s.router = router
   if (typeof window === "undefined") return
+  // Now, not at the first overlay: a page reloaded on a kit entry mutes the
+  // router below, and only the engine's listeners ever switch it back on.
+  install()
   // After the router's own listener, which it added when it was created.
   window.removeEventListener("popstate", afterPop)
   window.addEventListener("popstate", afterPop)

package/src/composables/pointerDrag.ts

@@ -0,0 +1,54 @@
+import { nodeWindow } from "./useView"
+
+export interface PointerDragHandlers {
+  move: (event: PointerEvent) => void
+  /** `completed` is false for a cancelled or lost pointer: nothing should be committed. */
+  end: (completed: boolean) => void
+  /** Hold this cursor over the whole page for the drag, the way a resize grip wants. */
+  cursor?: string
+}
+
+/**
+ * Follow a pointer from the handle it pressed until it lets go, however that
+ * ends: release, a cancelled touch, a lost capture or the returned stop. The
+ * end runs once. Everything happens on the handle, which holds the capture, so
+ * it works inside an LpFrame, and the body's text selection is off meanwhile,
+ * in the handle's own window, and put back as it was.
+ */
+export function startPointerDrag(event: PointerEvent, handlers: PointerDragHandlers): () => void {
+  const handle = event.currentTarget as HTMLElement
+  const body = nodeWindow(handle).document.body.style
+  const { userSelect, cursor } = body
+  let active = true
+
+  const finish = (completed: boolean) => {
+    if (!active) return
+    active = false
+    handle.removeEventListener("pointermove", onMove)
+    handle.removeEventListener("pointerup", onUp)
+    handle.removeEventListener("pointercancel", onCancel)
+    handle.removeEventListener("lostpointercapture", onCancel)
+    body.userSelect = userSelect
+    body.cursor = cursor
+    handlers.end(completed)
+  }
+  function onMove(ev: PointerEvent) {
+    if (ev.pointerId === event.pointerId) handlers.move(ev)
+  }
+  function onUp(ev: PointerEvent) {
+    if (ev.pointerId === event.pointerId) finish(true)
+  }
+  function onCancel(ev: PointerEvent) {
+    if (ev.pointerId === event.pointerId) finish(false)
+  }
+
+  event.preventDefault()
+  body.userSelect = "none"
+  if (handlers.cursor) body.cursor = handlers.cursor
+  handle.setPointerCapture(event.pointerId)
+  handle.addEventListener("pointermove", onMove)
+  handle.addEventListener("pointerup", onUp)
+  handle.addEventListener("pointercancel", onCancel)
+  handle.addEventListener("lostpointercapture", onCancel)
+  return () => finish(false)
+}

package/src/composables/propCheck.ts

@@ -0,0 +1,90 @@
+import type { ComponentPublicInstance, Plugin } from "vue"
+
+/*
+ * Development check for a misspelt prop on a kit component.
+ *
+ * A prop a component does not declare falls through as an attribute with no
+ * error, and vue-tsc's own `checkUnknownProps` cannot tell that apart from the
+ * `id`, `title` or `aria-*` an app rightly passes through. Here the attribute
+ * is checked against the element it would land on, so `<LpTooltip text>` is
+ * reported and `<LpInput autocomplete>` is not.
+ *
+ * Install it in development only:
+ *
+ *   if (import.meta.env.DEV) app.use(lpPropCheck)
+ *
+ * The Nuxt module does that on its own. Attributes of a third-party library
+ * that nothing here can know go in `ignore`.
+ */
+export interface PropCheckOptions {
+  /** Attributes that are not a mistake: exact names or patterns. */
+  ignore?: (string | RegExp)[]
+  /** Where a report goes. Defaults to console.warn. */
+  warn?: (message: string) => void
+}
+
+const KIT_COMPONENT = /^Lp[A-Z]/
+const ALWAYS_ALLOWED = /^(data-|aria-|on[A-Z])/
+const GLOBAL_ATTRIBUTES = new Set([
+  "accesskey", "class", "contenteditable", "dir", "draggable", "enterkeyhint", "for", "hidden",
+  "id", "inert", "inputmode", "is", "key", "lang", "nonce", "popover", "ref", "role", "slot",
+  "spellcheck", "style", "tabindex", "title", "translate",
+])
+/* Where a component with `inheritAttrs: false` hands its attributes on to. */
+const FORWARD_TARGETS = "input, textarea, select, button, a, img, form, label"
+
+const propertiesByTag = new Map<string, Set<string>>()
+
+function propertiesOf(el: Element): Set<string> {
+  let known = propertiesByTag.get(el.tagName)
+  if (!known) {
+    known = new Set<string>()
+    for (const name in el) known.add(name.toLowerCase())
+    propertiesByTag.set(el.tagName, known)
+  }
+  return known
+}
+
+const normalized = (name: string) => name.replaceAll("-", "").toLowerCase()
+
+/** The attributes no element under this component could take. */
+export function unknownAttributes(
+  attributes: string[],
+  elements: Element[],
+  ignore: PropCheckOptions["ignore"] = [],
+): string[] {
+  return attributes.filter((name) => {
+    if (ALWAYS_ALLOWED.test(name) || GLOBAL_ATTRIBUTES.has(name.toLowerCase())) return false
+    if (ignore.some((rule) => (typeof rule === "string" ? rule === name : rule.test(name)))) return false
+    const key = normalized(name)
+    return !elements.some((el) => propertiesOf(el).has(key))
+  })
+}
+
+function renderedElements(instance: ComponentPublicInstance): Element[] {
+  const root = instance.$el as Node | null
+  if (root?.nodeType !== 1) return []
+  const el = root as Element
+  return [el, ...el.querySelectorAll(FORWARD_TARGETS)]
+}
+
+export const lpPropCheck: Plugin<[PropCheckOptions?]> = {
+  install(app, options = {}) {
+    const warn = options.warn ?? ((message: string) => console.warn(message))
+    const reported = new Set<string>()
+    app.mixin({
+      mounted(this: ComponentPublicInstance) {
+        const name = this.$options.__name
+        if (!name || !KIT_COMPONENT.test(name)) return
+        const attributes = Object.keys(this.$attrs)
+        if (!attributes.length) return
+        for (const attribute of unknownAttributes(attributes, renderedElements(this), options.ignore)) {
+          const id = `${name}:${attribute}`
+          if (reported.has(id)) continue
+          reported.add(id)
+          warn(`[@leavepulse/ui] <${name}> has no prop "${attribute}". Props: ${Object.keys(this.$props).join(", ")}`)
+        }
+      },
+    })
+  },
+}

package/src/composables/realm.ts

@@ -0,0 +1,25 @@
+/*
+ * `instanceof Element` is false for a node of an LpFrame: each window has its
+ * own classes. These go by what the node is, and what it belongs to.
+ */
+export function isNode(value: unknown): value is Node {
+  return typeof (value as Node | null | undefined)?.nodeType === "number"
+}
+
+export function isElement(value: unknown): value is Element {
+  return (value as Node | null | undefined)?.nodeType === 1
+}
+
+export function isInputElement(value: unknown): value is HTMLInputElement {
+  return isElement(value) && value.tagName === "INPUT"
+}
+
+export function isHTMLElement(value: unknown): value is HTMLElement {
+  return isElement(value) && "style" in value
+}
+
+/** The window a node lives in, with that realm's constructors (`MouseEvent`, `ResizeObserver`). */
+export function nodeWindow(node: Node): Window & typeof globalThis {
+  const doc = node.nodeType === 9 ? (node as Document) : node.ownerDocument
+  return (doc?.defaultView ?? globalThis) as Window & typeof globalThis
+}

package/src/composables/scroll.ts

@@ -1,3 +1,5 @@
+import { nodeWindow } from "./useView"
+
 /*
  * 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
@@ -18,7 +20,7 @@ export interface ScrollParentOptions {
 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 === node.ownerDocument.body || node === node.ownerDocument.documentElement) return null
-    const style = getComputedStyle(node)
+    const style = nodeWindow(node).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
@@ -48,7 +50,7 @@ export interface ScrollToElementOptions {
 /** Scroll the nearest scroller, and only it, so that `el` is in view. */
 /** The element's own `scroll-margin-top`, the gap it asks to keep above it when scrolled to. */
 export function scrollMarginTop(el: Element): number {
-  return Number.parseFloat(getComputedStyle(el).scrollMarginTop) || 0
+  return Number.parseFloat(nodeWindow(el).getComputedStyle(el).scrollMarginTop) || 0
 }
 
 export function scrollToElement(

package/src/composables/scrollMemory.ts

@@ -1,10 +1,14 @@
+import { nodeWindow } from "./realm"
 import { nextTick, onBeforeUnmount, onMounted, watch } from "vue"
 import { scrollMarginTop } from "./scroll"
 
 /*
- * Where a page lands when the shell's own scroll region changes page. The
- * region is not the window, so a router's scrollBehavior never reaches it, and
- * the shell has to answer the questions a browser answers for a plain site:
+ * Where a page lands when the shell changes page. In its own scroll region a
+ * router's scrollBehavior never reaches the page, and the shell has to answer
+ * the questions a browser answers for a plain site. When the document scrolls
+ * (the viewport is the document's scrollingElement) it answers them the same
+ * way, so a router without a scrollBehavior behaves as one with it, and one
+ * with it lands in the same place:
  *
  *  - back and forward return to where the page was left;
  *  - an address with a hash lands on that anchor, and stays on it while the
@@ -22,20 +26,56 @@ import { scrollMarginTop } from "./scroll"
 const SETTLE_MS = 1500
 const DIALOG_WAIT_MS = 2000
 const SETTLE_STOP = ["wheel", "touchstart", "keydown", "pointerdown"] as const
+/* Addresses remembered; a long session over /devices/:id must not grow forever. */
+const MAX_POSITIONS = 200
 
 const positions = new Map<string, number>()
 
-function addressKey(): string {
-  return `${location.pathname}${location.search}`
+/** Records a position, dropping the address visited longest ago past `limit`. */
+export function rememberPosition(store: Map<string, number>, key: string, top: number, limit = MAX_POSITIONS): void {
+  store.delete(key)
+  store.set(key, top)
+  if (store.size > limit) store.delete(store.keys().next().value as string)
+}
+
+/** The element id a hash names. A malformed escape ("#%E0%A4%A") is taken as written. */
+/* The document's own scroller: its box moves with the scroll, the window's does not. */
+function isDocument(view: Element): boolean {
+  return view === view.ownerDocument.scrollingElement
+}
+
+function frameTop(view: Element): number {
+  return isDocument(view) ? 0 : view.getBoundingClientRect().top
+}
+
+export function hashTargetId(value: string): string {
+  const id = value.replace(/^#/, "")
+  try {
+    return decodeURIComponent(id)
+  } catch {
+    return id
+  }
+}
+
+function addressKey(scope: string): string {
+  return `${scope}${location.pathname}${location.search}`
 }
 
 export function useScrollMemory(
   viewport: () => HTMLElement | null | undefined,
   path: () => string | undefined,
   hash: () => string | undefined,
+  /** Sets a second region's positions apart from the first's on the same address. */
+  scope = "",
+  /**
+   * What covers the top of the viewport (a sticky header), in px: an anchor
+   * lands below it. Not scroll-padding-top on the document, which also makes
+   * the browser scroll the page whenever a control in that header takes focus.
+   */
+  covered: () => number = () => 0,
 ): void {
   if (typeof window === "undefined") return
-  let current = addressKey()
+  let current = addressKey(scope)
   let shown = path()
   let travelled = false
   let stopHold: (() => void) | undefined
@@ -48,15 +88,14 @@ export function useScrollMemory(
 
   function anchor(value: string | undefined): HTMLElement | null {
     if (!value || value === "#") return null
-    const id = decodeURIComponent(value.replace(/^#/, ""))
-    return document.getElementById(id)
+    return document.getElementById(hashTargetId(value))
   }
 
   function reach(value: string | undefined, behavior: ScrollBehavior): boolean {
     const view = viewport()
     const target = anchor(value)
     if (!view || !target || !view.contains(target)) return false
-    const top = target.getBoundingClientRect().top - view.getBoundingClientRect().top + view.scrollTop - scrollMarginTop(target)
+    const top = target.getBoundingClientRect().top - frameTop(view) + view.scrollTop - scrollMarginTop(target) - covered()
     view.scrollTo({ top: Math.max(0, top), behavior })
     return true
   }
@@ -65,10 +104,10 @@ export function useScrollMemory(
   function hold(land: () => void) {
     stopHold?.()
     const view = viewport()
-    const content = view?.firstElementChild
+    const content = view && (isDocument(view) ? view.ownerDocument.body : view.firstElementChild)
     land()
     if (!content) return
-    const watcher = new ResizeObserver(land)
+    const watcher = new (nodeWindow(content).ResizeObserver)(land)
     const timer = window.setTimeout(() => stop(), SETTLE_MS)
     const stop = () => {
       watcher.disconnect()
@@ -84,7 +123,7 @@ export function useScrollMemory(
   function arrive() {
     const back = travelled
     travelled = false
-    current = addressKey()
+    current = addressKey(scope)
     shown = path()
     const view = viewport()
     if (!view) return
@@ -108,7 +147,9 @@ export function useScrollMemory(
     const mine = ++pending
     const tick = () => {
       if (mine !== pending) return
-      const locked = document.querySelector('[role="dialog"]') || getComputedStyle(document.body).overflow === "hidden"
+      // The document the shell scrolls in: a dialog of the page is not one of a frame's.
+      const doc = viewport()?.ownerDocument ?? document
+      const locked = doc.querySelector('[role="dialog"]') || nodeWindow(doc).getComputedStyle(doc.body).overflow === "hidden"
       if (locked && performance.now() - since < DIALOG_WAIT_MS) requestAnimationFrame(tick)
       else run()
     }
@@ -119,7 +160,7 @@ export function useScrollMemory(
     path,
     () => {
       const view = viewport()
-      if (view) positions.set(current, view.scrollTop)
+      if (view) rememberPosition(positions, current, view.scrollTop)
       void nextTick(() => requestAnimationFrame(arrive))
     },
     { flush: "pre" },
@@ -140,6 +181,7 @@ export function useScrollMemory(
 
   onBeforeUnmount(() => {
     stopHold?.()
+    pending += 1
     window.removeEventListener("popstate", onPop)
   })
 }

package/src/composables/spatialNav.ts

@@ -1,3 +1,4 @@
+import { nodeWindow } from "./realm"
 /*
  * Moving focus by direction rather than by document order: what a D-pad, a
  * stick or a TV remote needs, where "next" means "the thing to the right", not
@@ -113,7 +114,7 @@ export function focusableIn(root: ParentNode): HTMLElement[] {
     if (element.getAttribute("tabindex") === "-1" && !element.matches(ROVING_ITEMS)) return false
     const rect = element.getBoundingClientRect()
     if (rect.width === 0 || rect.height === 0) return false
-    const style = getComputedStyle(element)
+    const style = nodeWindow(element).getComputedStyle(element)
     return style.visibility !== "hidden" && style.display !== "none"
   })
 }

package/src/composables/textEntry.ts

@@ -0,0 +1,33 @@
+import { isElement, isHTMLElement } from "./realm"
+
+const TYPED_INPUTS = new Set(["text", "search", "email", "number", "password", "tel", "url"])
+
+/** Where text can be typed, for a target that may sit inside one. */
+export const TEXT_FIELD_SELECTOR = "input, textarea, [contenteditable]"
+
+export interface TextEntryOptions {
+  /** Which `<input>` types count. Defaults to the ones that take typed text. */
+  inputType?: (type: string) => boolean
+  /** A `<select>` counts too: it keeps letters and arrows for itself. */
+  select?: boolean
+}
+
+/**
+ * Whether the event lands in something the user is typing into. Checked off the
+ * event target rather than `document.activeElement` so it stays right inside a
+ * dialog's focus trap, and by tag rather than class so a field of an LpFrame
+ * counts too.
+ */
+export function isTextEntry(target: EventTarget | null, options: TextEntryOptions = {}): boolean {
+  if (!isHTMLElement(target)) return false
+  if (target.isContentEditable || target.tagName === "TEXTAREA") return true
+  if (options.select && target.tagName === "SELECT") return true
+  if (target.tagName !== "INPUT") return false
+  const { type } = target as HTMLInputElement
+  return options.inputType ? options.inputType(type) : TYPED_INPUTS.has(type)
+}
+
+/** Whether the target is, or sits inside, what the selector names. */
+export function inTextField(target: EventTarget | null, selector = TEXT_FIELD_SELECTOR): boolean {
+  return isElement(target) && !!target.closest(selector)
+}

package/src/composables/useAsyncTask.ts

@@ -8,6 +8,12 @@ import { getCurrentScope, onScopeDispose, ref } from "vue"
  * fresher one, and a response landing after the control moved on. The token
  * guards both — the abort signal only asks the consumer to stop, it cannot
  * promise they did.
+ *
+ * What is guarded is `apply` and `fail`, not the task: whatever it does past
+ * the point it honours the signal (a cache write after the fetch) still runs,
+ * and an error from a superseded run is dropped unseen. It is also one slot:
+ * a new `run` replaces the last, and `pending` speaks for the latest only, so
+ * independent requests each need their own `useAsyncTask`.
  */
 export function useAsyncTask<T>() {
   const pending = ref(false)

package/src/composables/useChartSync.ts

@@ -0,0 +1,52 @@
+import { computed, onScopeDispose, shallowRef, toValue, type MaybeRefOrGetter, type ShallowRef } from "vue"
+
+/*
+ * One crosshair across charts of the same period: the x label hovered in one is
+ * marked in the others. Matched by label rather than by index, because two
+ * charts can hold different points or different windows of the same timeline.
+ *
+ * Pinned to a global symbol so a barrel and a deep import share the groups.
+ */
+interface Hovered {
+  owner: symbol
+  label: string
+}
+
+const SYNC_KEY = Symbol.for("@leavepulse/ui:chart-sync")
+type GlobalWithSync = typeof globalThis & { [SYNC_KEY]?: Map<string, ShallowRef<Hovered | null>> }
+const groups = ((globalThis as GlobalWithSync)[SYNC_KEY] ??= new Map())
+
+function groupOf(name: string): ShallowRef<Hovered | null> {
+  let group = groups.get(name)
+  if (!group) {
+    group = shallowRef<Hovered | null>(null)
+    groups.set(name, group)
+  }
+  return group
+}
+
+export function useChartSync(group: MaybeRefOrGetter<string | undefined>) {
+  const owner = Symbol("chart")
+  const shared = computed(() => {
+    const name = toValue(group)
+    return name ? groupOf(name) : null
+  })
+
+  /** The label another chart of the group is hovering. */
+  const peerLabel = computed(() => {
+    const hovered = shared.value?.value
+    return hovered && hovered.owner !== owner ? hovered.label : null
+  })
+
+  /** Tell the group what this chart hovers; null when the pointer left. */
+  function publish(label: string | null) {
+    const target = shared.value
+    if (!target) return
+    if (label != null) target.value = { owner, label }
+    else if (target.value?.owner === owner) target.value = null
+  }
+
+  onScopeDispose(() => publish(null))
+
+  return { peerLabel, publish }
+}