@leavepulse/ui 0.68.0 → 0.70.0

package/src/composables/pseudoLocale.ts

@@ -0,0 +1,105 @@
+/*
+ * Pseudo-localisation: English text made to look like a translation, so a
+ * screen can be checked for translation problems before any translation exists.
+ *
+ *   "Save changes" → "[Šååṽéé çĥååñĝééš]"
+ *
+ * What each part catches:
+ *
+ * - Accents. A string that still reads as plain ASCII on a pseudo screen was
+ *   never routed through the label system: it is hard-coded and would stay
+ *   English in every language.
+ * - Length. Translations run longer than English, German and Finnish by a
+ *   third and more. Vowels are stretched by `expand`, so a label that only fits
+ *   in English overflows, wraps or truncates right here.
+ * - Brackets. A clipped end bracket is truncation that would otherwise go
+ *   unnoticed; a bracket in the middle of a sentence is two strings glued
+ *   together, which no language with a different word order can translate.
+ *
+ * Placeholders (`{name}`, `{{ name }}`, `%s`, `%1$d`), tags and entities are
+ * left exactly as they are: they are code the label is filled through, and an
+ * accented `{ñåmé}` would no longer be replaced.
+ */
+
+export interface PseudoOptions {
+  /**
+   * Extra length as a share of the text's letters: 0.35 adds about a third.
+   * Spread over the vowels, so the text grows the way a longer word does
+   * rather than gaining a tail that wraps somewhere convenient.
+   */
+  expand?: number
+  /**
+   * Markers around the whole string. `true` uses square brackets, a pair of
+   * strings picks others, `false` drops them.
+   */
+  brackets?: boolean | readonly [string, string]
+}
+
+const ACCENTED: Record<string, string> = {
+  a: "å", b: "ƀ", c: "ç", d: "ð", e: "é", f: "ƒ", g: "ĝ", h: "ĥ", i: "î", j: "ĵ", k: "ķ", l: "ļ", m: "ɱ",
+  n: "ñ", o: "ö", p: "þ", q: "ǫ", r: "ŕ", s: "š", t: "ţ", u: "û", v: "ṽ", w: "ŵ", x: "ẋ", y: "ý", z: "ž",
+  A: "Å", B: "Ɓ", C: "Ç", D: "Ð", E: "É", F: "Ƒ", G: "Ĝ", H: "Ĥ", I: "Î", J: "Ĵ", K: "Ķ", L: "Ļ", M: "Ṁ",
+  N: "Ñ", O: "Ö", P: "Þ", Q: "Ǫ", R: "Ŕ", S: "Š", T: "Ţ", U: "Û", V: "Ṽ", W: "Ŵ", X: "Ẋ", Y: "Ý", Z: "Ž",
+}
+
+const VOWEL = /[aeiouyAEIOUY]/
+
+/*
+ * Everything that is code rather than text. Order matters only in that the
+ * double-brace form must be tried before the single one, or `{{ x }}` would
+ * be read as `{` + `{ x }` + `}`.
+ */
+const PROTECTED = /\{\{[^}]*\}\}|\{[^{}]*\}|%(?:\d+\$)?[-+ 0#]*\d*(?:\.\d+)?[sdifoxXeEgGc%]|<[^>]+>|&[a-zA-Z#0-9]+;/g
+
+/** English text made to look translated and longer; see the module comment. */
+export function pseudoLocalize(text: string, options: PseudoOptions = {}): string {
+  if (!text.trim()) return text
+  const expand = Math.max(0, options.expand ?? 0.35)
+  const brackets = options.brackets ?? true
+  const [open, close] = brackets === true ? ["[", "]"] : brackets === false ? ["", ""] : brackets
+
+  // Split into text runs and protected runs, keeping both.
+  const runs: { text: string; code: boolean }[] = []
+  let last = 0
+  for (const match of text.matchAll(PROTECTED)) {
+    const at = match.index ?? 0
+    if (at > last) runs.push({ text: text.slice(last, at), code: false })
+    runs.push({ text: match[0], code: true })
+    last = at + match[0].length
+  }
+  if (last < text.length) runs.push({ text: text.slice(last), code: false })
+
+  const letters = runs.reduce((n, run) => (run.code ? n : n + (run.text.match(/[a-zA-Z]/g)?.length ?? 0)), 0)
+  const vowels = runs.reduce((n, run) => (run.code ? n : n + (run.text.match(/[aeiouyAEIOUY]/g)?.length ?? 0)), 0)
+  let extra = Math.round(letters * expand)
+
+  /*
+   * Every vowel repeats `per` more times, and the first `rest` once more on
+   * top, so the growth is spread over the whole string instead of piling up
+   * in its first word.
+   */
+  const per = vowels ? Math.floor(extra / vowels) : 0
+  let rest = vowels ? extra % vowels : 0
+  if (vowels) extra = 0
+
+  const out = runs
+    .map((run) => {
+      if (run.code) return run.text
+      let s = ""
+      for (const ch of run.text) {
+        const mapped = ACCENTED[ch] ?? ch
+        s += mapped
+        if (VOWEL.test(ch)) {
+          const times = per + (rest > 0 ? 1 : 0)
+          if (rest > 0) rest--
+          s += mapped.toLowerCase().repeat(times)
+        }
+      }
+      return s
+    })
+    .join("")
+
+  // No vowels to stretch (an abbreviation, a code): the length goes at the end.
+  const tail = extra > 0 ? "·".repeat(extra) : ""
+  return `${open}${out}${tail}${close}`
+}

package/src/composables/scroll.ts

@@ -17,7 +17,7 @@ export interface ScrollParentOptions {
 /** 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
+    if (node === node.ownerDocument.body || node === node.ownerDocument.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
@@ -40,9 +40,12 @@ export function scrollToElement(
   { block = "nearest", behavior = "auto", margin = 0 }: ScrollToElementOptions = {},
 ): void {
   if (!el) return
-  const box = scrollParent(el) ?? (document.scrollingElement as HTMLElement | null)
+  // The element's own document and window: inside an LpFrame they are the frame's.
+  const doc = el.ownerDocument
+  const win = doc.defaultView ?? window
+  const box = scrollParent(el) ?? (doc.scrollingElement as HTMLElement | null)
   if (!box) return
-  const outer = box === document.scrollingElement ? new DOMRect(0, 0, window.innerWidth, window.innerHeight) : box.getBoundingClientRect()
+  const outer = box === doc.scrollingElement ? new DOMRect(0, 0, win.innerWidth, win.innerHeight) : box.getBoundingClientRect()
   const inner = el.getBoundingClientRect()
   const top = inner.top - outer.top + box.scrollTop
   let target = box.scrollTop

package/src/composables/useClipboard.ts

@@ -70,6 +70,23 @@ function writeLegacy(text: string): boolean {
   return ok
 }
 
+/*
+ * A blob (an image, mostly) goes through `clipboard.write`. There is no old
+ * command to fall back on here: the copy command only knows the selection,
+ * and an image cannot be selected into a text field. Browsers take a narrow
+ * set of types (PNG reliably, text/html and text/plain), so the caller
+ * converts first; a type the browser refuses fails like any other refusal.
+ */
+async function writeBlob(blob: Blob): Promise<boolean> {
+  if (typeof navigator === "undefined" || !navigator.clipboard?.write || typeof ClipboardItem === "undefined") return false
+  try {
+    await navigator.clipboard.write([new ClipboardItem({ [blob.type || "image/png"]: blob })])
+    return true
+  } catch {
+    return false
+  }
+}
+
 /** How long `copied` stays true — long enough to read, short enough to not linger. */
 const COPIED_MS = 1400
 
@@ -102,8 +119,11 @@ export interface UseClipboard {
    * Writes `text` to the clipboard. Resolves true on success, false when the
    * clipboard was unavailable or refused — it never rejects, so `await copy(x)`
    * is safe to call bare from an event handler.
+   *
+   * A `Blob` is written as itself under its own type (an image as a PNG blob),
+   * for "copy image" next to "copy link".
    */
-  copy: (text: string, options?: CopyOptions) => Promise<boolean>
+  copy: (data: string | Blob, options?: CopyOptions) => Promise<boolean>
 }
 
 /**
@@ -125,10 +145,12 @@ export function useClipboard(): UseClipboard {
   const { success, error } = useToast()
   let timer: ReturnType<typeof setTimeout> | undefined
 
-  async function copy(text: string, options: CopyOptions = {}): Promise<boolean> {
+  async function copy(data: string | Blob, options: CopyOptions = {}): Promise<boolean> {
     const { toast = false, errorToast = false } = options
     try {
-      if (!(await writeAsync(text)) && !writeLegacy(text)) throw new Error("clipboard unavailable")
+      const written =
+        typeof data === "string" ? (await writeAsync(data)) || writeLegacy(data) : await writeBlob(data)
+      if (!written) throw new Error("clipboard unavailable")
 
       copied.value = true
       clearTimeout(timer)

package/src/composables/useField.ts

@@ -81,3 +81,15 @@ export function useFieldControl(
     }
   })
 }
+
+/**
+ * Whether a focusout leaves the whole control, not just moves between its own
+ * parts (a trigger and a clear button, the segments of a time field, an input
+ * and its stepper). Composite controls emit their `blur` only then: focus
+ * events do not bubble, so a consumer's `@blur` on the wrapper never fired, and
+ * `useForm().field()` could not mark such a field touched.
+ */
+export function focusLeft(event: FocusEvent): boolean {
+  const next = event.relatedTarget
+  return !(next instanceof Node && (event.currentTarget as Node | null)?.contains(next))
+}

package/src/composables/useForm.ts

@@ -120,6 +120,9 @@ export function useForm<T extends object>(options: UseFormOptions<T>): UseForm<T
   const submitting = ref(false)
   const submitCount = ref(0)
   const runs = new Map<keyof T | "form", number>()
+  // What the form-level check set last, so its next run can take back what no
+  // longer holds without touching an error a field rule set on the same key.
+  const fromForm = new Map<keyof T | "form", string>()
   const baseVersion = ref(0)
 
   const keys = (): (keyof T)[] => Object.keys(plain()) as (keyof T)[]
@@ -160,11 +163,15 @@ export function useForm<T extends object>(options: UseFormOptions<T>): UseForm<T
     runs.set("form", run)
     const found = (await options.validate(plain())) ?? {}
     if (runs.get("form") !== run) return true
+    for (const [name, text] of fromForm) if (errors[name] === text) delete errors[name]
+    fromForm.clear()
     let ok = true
     for (const [name, text] of Object.entries(found) as [keyof T | "form", string | undefined][]) {
       if (!text) continue
       ok = false
-      if (!errors[name]) errors[name] = text
+      if (errors[name]) continue
+      errors[name] = text
+      fromForm.set(name, text)
     }
     return ok
   }
@@ -173,7 +180,6 @@ export function useForm<T extends object>(options: UseFormOptions<T>): UseForm<T
     validating.value = true
     try {
       if (name !== undefined) return await runField(name)
-      if (errors.form) delete errors.form
       const fields = await Promise.all(keys().map(runField))
       const form = await runForm()
       return fields.every(Boolean) && form && !Object.values(external).some(Boolean)
@@ -200,6 +206,7 @@ export function useForm<T extends object>(options: UseFormOptions<T>): UseForm<T
     for (const k of Object.keys(external)) delete external[k as keyof T]
     for (const k of Object.keys(touched)) delete touched[k as keyof T]
     runs.clear()
+    fromForm.clear()
     submitCount.value = 0
   }
 
@@ -231,18 +238,27 @@ export function useForm<T extends object>(options: UseFormOptions<T>): UseForm<T
     { deep: true },
   )
 
-  // An edit re-checks a field already touched, and drops an external error on it.
+  // An edit re-checks a field already touched, drops an external error on it,
+  // and runs the form-level check again once it has run: a cross-field error
+  // ("passwords differ") must clear when either field is fixed.
+  async function recheck(names: (keyof T)[]): Promise<void> {
+    await Promise.all(names.map((name) => validate(name)))
+    if (fromForm.size || submitCount.value) await runForm()
+  }
+
   let snapshot = clone(plain())
   watch(
     plain,
     () => {
       const now = clone(plain())
+      const changed: (keyof T)[] = []
       for (const name of Object.keys(now) as (keyof T)[]) {
         if (deepEqual(now[name], snapshot[name])) continue
         if (external[name]) delete external[name]
-        if (touched[name] || submitCount.value) void validate(name)
+        if (touched[name] || submitCount.value) changed.push(name)
       }
       snapshot = now
+      if (changed.length) void recheck(changed)
     },
     { deep: true },
   )
@@ -278,8 +294,13 @@ export function useForm<T extends object>(options: UseFormOptions<T>): UseForm<T
       try {
         submitCount.value++
         for (const name of keys()) touched[name] = true
-        if (!(await validate())) return
-        const submitted = clone(plain())
+        // The values that passed are the values sent: an edit made while an
+        // async rule was running is checked again before anything goes out.
+        let submitted: T
+        do {
+          submitted = clone(plain())
+          if (!(await validate())) return
+        } while (!deepEqual(plain(), submitted))
         await fn(submitted)
         if (deepEqual(plain(), submitted)) {
           baseline = submitted

package/src/composables/useHintSystem.ts

@@ -249,6 +249,8 @@ export interface HintTiming {
   freshLimit: number
   nudgeAgain: number
   flush: number
+  /** How long a news item opened from a feed waits for its page and feature, ms. */
+  newsWait: number
 }
 
 export interface HintSystemOptions {
@@ -278,6 +280,7 @@ const DEFAULT_TIMING: HintTiming = {
   freshLimit: 3,
   nudgeAgain: 7 * DAY,
   flush: 2000,
+  newsWait: 8000,
 }
 
 /** Records in localStorage: for anonymous sessions and apps without a server. */
@@ -509,6 +512,41 @@ export function createHintSystem(options: HintSystemOptions) {
     for (const n of unread(page)) record(newsKey(n.id), { state: "explained" })
   }
 
+  // A news item opened from a feed elsewhere (a notification bell): the app
+  // navigates, and the change is shown as soon as its page is up and the thing
+  // (or its sample) is there to point at. Waiting is bounded: an item whose
+  // feature never appears is only marked read.
+  let pendingNews: (() => void) | null = null
+
+  function showNews(id: string): void {
+    const item = news.find((n) => n.id === id)
+    if (!item) return
+    record(newsKey(item.id), { state: "explained" })
+    const feature = item.feature
+    if (!feature) return
+    pendingNews?.()
+    let done = false
+    let stopWatch: WatchStopHandle | undefined
+    const finish = () => {
+      done = true
+      clearTimeout(timer)
+      stopWatch?.()
+      if (pendingNews === finish) pendingNews = null
+    }
+    const timer = setTimeout(finish, timing.newsWait)
+    pendingNews = finish
+    stopWatch = watch(
+      () => state.page === item.page && showable(feature) && !state.tour.open,
+      (ready) => {
+        if (!ready || done) return
+        finish()
+        startTour(item.page, [feature])
+      },
+      { immediate: true },
+    )
+    if (done) stopWatch()
+  }
+
   function considerOffer(): void {
     const page = state.page
     const ready = state.loaded && !state.tour.open && !state.offer && !anyModalOpen() && !typing()
@@ -651,6 +689,8 @@ export function createHintSystem(options: HintSystemOptions) {
     },
     unreadNews: (page?: string) => unread(page),
     readNews,
+    /** Open one news item from a feed: mark it read and show its feature once the app is on its page. */
+    showNews,
     pageTitle: (page: string) => pages[page]?.title ?? page,
     readFresh(id: string): void {
       record(featureKey(id), { state: "explained" })

package/src/composables/useHints.ts

@@ -111,15 +111,26 @@ function detach(el: HTMLElement) {
   idOf.delete(el)
 }
 
+// Inside an LpHintExample the mark names a part of the sample instead: the
+// app drops its real component with made-up data into the sample, and the
+// component's own marks tell the tour where each step points, without
+// counting the sample as the real thing.
+function mark(el: HTMLElement, id: string | null | undefined) {
+  if (!id) return
+  if (el.closest("[data-lp-hint-example]")) el.dataset.lpHintPart = id
+  else attach(el, id)
+}
+
 /** `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)
+    mark(el, binding.value)
   },
   updated(el, binding) {
-    if (binding.value === idOf.get(el)) return
+    if (binding.value === (idOf.get(el) ?? el.dataset.lpHintPart)) return
     detach(el)
-    if (binding.value) attach(el, binding.value)
+    delete el.dataset.lpHintPart
+    mark(el, binding.value)
   },
   beforeUnmount(el) {
     detach(el)

package/src/composables/useInView.ts

@@ -0,0 +1,61 @@
+import { onBeforeUnmount, ref, watch, type Ref } from "vue"
+
+/*
+ * "Is this element on screen RIGHT NOW, in a tab someone is looking at?"
+ *
+ * useReveal answers a one-way question (has it ever been seen) for entrances.
+ * A looping effect needs the live answer: a sheen sweeping text below the fold
+ * or a typewriter cycling in a background tab spends frames and battery on
+ * nothing, and on a dashboard of them that adds up. So this flips both ways,
+ * and the loop pauses while it is false.
+ *
+ * Without IntersectionObserver (old WebKitGTK, tests) the element counts as on
+ * screen: better a loop that runs than one that never starts.
+ */
+export interface UseInView {
+  /** Attach to the element to watch. */
+  el: Ref<Element | null>
+  /** On screen and the page visible. */
+  inView: Ref<boolean>
+}
+
+export function useInView(options: { rootMargin?: string; threshold?: number } = {}): UseInView {
+  const el = ref<Element | null>(null)
+  const intersecting = ref(typeof IntersectionObserver === "undefined")
+  const pageVisible = ref(typeof document === "undefined" || document.visibilityState === "visible")
+  const inView = ref(false)
+  let observer: IntersectionObserver | null = null
+
+  const sync = () => (inView.value = intersecting.value && pageVisible.value)
+  const onVisibility = () => {
+    pageVisible.value = document.visibilityState === "visible"
+    sync()
+  }
+
+  if (typeof document !== "undefined") document.addEventListener("visibilitychange", onVisibility)
+
+  watch(
+    el,
+    (node) => {
+      observer?.disconnect()
+      observer = null
+      if (!node || typeof IntersectionObserver === "undefined") return sync()
+      observer = new IntersectionObserver(
+        (entries) => {
+          intersecting.value = entries.some((entry) => entry.isIntersecting)
+          sync()
+        },
+        { rootMargin: options.rootMargin ?? "0px", threshold: options.threshold ?? 0 },
+      )
+      observer.observe(node)
+    },
+    { immediate: true, flush: "post" },
+  )
+
+  onBeforeUnmount(() => {
+    observer?.disconnect()
+    if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisibility)
+  })
+
+  return { el, inView }
+}

package/src/composables/useLoadingGate.ts

@@ -0,0 +1,63 @@
+import { onScopeDispose, ref, toValue, watch, type MaybeRefOrGetter, type Ref } from "vue"
+
+/*
+ * "Should a loading indicator be on screen right now?" — which is not the same
+ * question as "is something loading?".
+ *
+ * Shown the moment work starts, a spinner flashes for 80 ms on every fast
+ * request: the page blinks, and blinking reads as instability rather than
+ * speed. Hidden the moment work ends, one that did appear can vanish a frame
+ * after it arrived — the same blink from the other side. So the indicator
+ * waits `delay` before appearing (most loads finish inside it and show
+ * nothing), and once up it stays at least `minVisible`, long enough to be seen
+ * as a deliberate state rather than a glitch.
+ *
+ * LpLoader runs on this; it is exported for anything else that gates a
+ * placeholder the same way (a skeleton, a dimmed table).
+ */
+
+export interface LoadingGateOptions {
+  /** Ms of loading before the indicator appears. */
+  delay?: MaybeRefOrGetter<number>
+  /** Ms the indicator stays once shown, even if loading ends sooner. */
+  minVisible?: MaybeRefOrGetter<number>
+}
+
+export function useLoadingGate(
+  active: MaybeRefOrGetter<boolean>,
+  options: LoadingGateOptions = {},
+): Ref<boolean> {
+  const shown = ref(false)
+  let shownAt = 0
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  const clear = () => {
+    if (timer !== undefined) clearTimeout(timer)
+    timer = undefined
+  }
+
+  const show = () => {
+    clear()
+    shown.value = true
+    shownAt = Date.now()
+  }
+
+  const settle = (on: boolean) => {
+    clear()
+    if (on) {
+      if (shown.value) return
+      const wait = Math.max(0, toValue(options.delay) ?? 0)
+      if (wait === 0) show()
+      else timer = setTimeout(show, wait)
+      return
+    }
+    if (!shown.value) return
+    const left = Math.max(0, toValue(options.minVisible) ?? 0) - (Date.now() - shownAt)
+    if (left <= 0) shown.value = false
+    else timer = setTimeout(() => { timer = undefined; shown.value = false }, left)
+  }
+
+  watch(() => !!toValue(active), settle, { immediate: true })
+  onScopeDispose(clear)
+  return shown
+}

package/src/composables/useLpConfig.ts

@@ -9,6 +9,7 @@ import {
   type InjectionKey,
   type MaybeRefOrGetter,
 } from "vue"
+import { pseudoLocalize, type PseudoOptions } from "./pseudoLocale"
 
 /*
  * App-wide kit configuration, said once at the root instead of on every call
@@ -33,6 +34,15 @@ export interface LpConfig {
    * desktop shell can hand in its own store. See `usePersisted`.
    */
   storage?: KitStorage
+  /**
+   * Show every kit label pseudo-localised ("Next" → "[Ñééẋţ]"): accented,
+   * about a third longer, and bracketed. A development switch for checking a
+   * screen before any translation exists: plain English left on it is text
+   * that never went through the labels, and anything clipped or overflowing
+   * will be in a real language too. `true` uses the defaults; an object tunes
+   * them (see `pseudoLocalize`).
+   */
+  pseudoLocale?: boolean | PseudoOptions
 }
 
 /**
@@ -82,6 +92,7 @@ export function mergeConfig(outer: LpConfig, inner: LpConfig): LpConfig {
     ...inner,
     linkComponent: inner.linkComponent ?? outer.linkComponent,
     storage: inner.storage ?? outer.storage,
+    pseudoLocale: inner.pseudoLocale ?? outer.pseudoLocale,
     labels,
   }
 }
@@ -101,7 +112,15 @@ export function useLabels<T extends LabelScope>(
   own?: () => Partial<T> | undefined,
 ): ComputedRef<T> {
   const config = useLpConfig()
-  return computed(() => ({ ...defaults, ...config.value.labels?.[scope], ...own?.() }) as T)
+  return computed(() => {
+    const labels = { ...defaults, ...config.value.labels?.[scope], ...own?.() } as T
+    const pseudo = config.value.pseudoLocale
+    if (!pseudo) return labels
+    const options = pseudo === true ? undefined : pseudo
+    return Object.fromEntries(
+      Object.entries(labels).map(([key, text]) => [key, typeof text === "string" ? pseudoLocalize(text, options) : text]),
+    ) as T
+  })
 }
 
 /** The link component to render for an internal destination. */

package/src/composables/useMediaQuery.ts

@@ -1,17 +1,21 @@
 import { onBeforeUnmount, onMounted, ref, type Ref } from "vue"
+import { useView, viewWindow } from "./useView"
 
 /*
  * 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.
+ * client render the same thing and the client switches right after. Asked of
+ * the window the component renders in, so inside an LpFrame narrowed to a
+ * phone a width query answers for the phone.
  */
 export function useMediaQuery(query: string): Ref<boolean> {
+  const view = useView()
   const matches = ref(false)
   let list: MediaQueryList | undefined
   const update = () => {
     matches.value = !!list?.matches
   }
   onMounted(() => {
-    list = window.matchMedia?.(query)
+    list = viewWindow(view.value).matchMedia?.(query)
     update()
     list?.addEventListener("change", update)
   })

package/src/composables/useNow.ts

@@ -0,0 +1,84 @@
+import { onScopeDispose, ref, toValue, watch, type MaybeRefOrGetter, type Ref } from "vue"
+
+/*
+ * The current time, as a ref that ticks only while something shows it.
+ *
+ * A clock on screen (a running job's elapsed time, a countdown) needs `now`
+ * once per visible change and not otherwise. Two things go wrong with the
+ * obvious `setInterval(1000)`:
+ *
+ *   - drift: an interval started mid-second shows each value late by that
+ *     fraction, and timers fire late under load, so the display slips further
+ *     behind the real time the longer it runs. Here every tick is scheduled
+ *     for the moment the display next changes (`nextIn`), read from the clock,
+ *     so a late tick corrects itself on the next one;
+ *   - background tabs: a hidden page gets its timers throttled to once a
+ *     minute or worse, then shows a stale value for a frame on return. Here the
+ *     ticking stops while the tab is hidden (nothing is looking) and `now` is
+ *     re-read the moment it is visible again.
+ *
+ * Time itself never pauses — it is always read from Date.now() — so a
+ * countdown that was hidden for ten minutes comes back ten minutes on.
+ */
+export interface UseNowOptions {
+  /**
+   * Ms from `now` until the next tick. Defaults to the next wall-clock
+   * second, which is when an elapsed "1m 12s" changes.
+   */
+  nextIn?: (now: number) => number
+  /**
+   * Re-read the clock and reschedule whenever this changes. For a `nextIn`
+   * that depends on more than the time: a relative date that was "last month"
+   * sleeps an hour, and if it is replaced by a date a few seconds old, the
+   * wait it scheduled for the old one would leave "now" on screen for an hour.
+   */
+  restartOn?: MaybeRefOrGetter<unknown>
+}
+
+export function useNow(
+  active: MaybeRefOrGetter<boolean> = true,
+  options: UseNowOptions = {},
+): Ref<number> {
+  const now = ref(Date.now())
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const hasDocument = typeof document !== "undefined"
+
+  const stop = () => {
+    if (timer !== undefined) clearTimeout(timer)
+    timer = undefined
+  }
+
+  const delay = (at: number) => {
+    const next = options.nextIn ? options.nextIn(at) : 1000 - (at % 1000)
+    // Never zero, never negative: a tick that lands on the boundary would
+    // otherwise reschedule itself in a tight loop.
+    return Math.max(16, Number.isFinite(next) ? next : 1000)
+  }
+
+  const tick = () => {
+    stop()
+    now.value = Date.now()
+    if (!toValue(active) || (hasDocument && document.hidden)) return
+    // Waking a hair after the boundary rather than before it: a tick that
+    // fires 2 ms early would read the old value and show it for another second.
+    timer = setTimeout(tick, delay(now.value) + 4)
+  }
+
+  const onVisibility = () => {
+    if (document.hidden) stop()
+    else tick()
+  }
+
+  watch(() => !!toValue(active), (on) => (on ? tick() : stop()), { immediate: true })
+  if (options.restartOn !== undefined) {
+    watch(() => toValue(options.restartOn), () => {
+      if (toValue(active)) tick()
+    })
+  }
+  if (hasDocument) document.addEventListener("visibilitychange", onVisibility)
+  onScopeDispose(() => {
+    stop()
+    if (hasDocument) document.removeEventListener("visibilitychange", onVisibility)
+  })
+  return now
+}