@leavepulse/ui 0.77.2 → 0.78.0

package/src/composables/useCloseGuard.ts

@@ -8,7 +8,9 @@ import { useLabels } from "./useLpConfig"
  * - `true`: there is something unsaved. Closing asks "Discard changes?" through
  *   the kit's confirm, and leaving the page asks the browser's own question.
  * - a function: the app asks its own question (or saves first) and answers
- *   whether the window may close.
+ *   whether the window may close. It covers the window's own ways out only:
+ *   a browser cannot wait for it, so closing the tab or reloading goes
+ *   unguarded. Only `true` raises the browser's question.
  * - `false` / unset: nothing to lose, the window closes as always.
  *
  * Usually bound straight to a form's state: `:guard="form.dirty"`.
@@ -39,6 +41,13 @@ export function useCloseGuard(
   )
 
   let asking = false
+  /*
+   * Counts every open and close. An answer takes as long as the person does,
+   * and meanwhile the window can close another way and open again: a "yes"
+   * given about that earlier window must not close the new one.
+   */
+  let session = 0
+  watch(() => !!toValue(open), () => (session += 1), { flush: "sync" })
 
   /** Whether the window may close now. Asks at most once at a time. */
   async function allowClose(): Promise<boolean> {
@@ -46,16 +55,19 @@ export function useCloseGuard(
     if (!current) return true
     if (asking) return false
     asking = true
+    const mine = session
     try {
-      if (typeof current === "function") return await current()
-      return await confirm({
-        title: labels.value.title,
-        description: labels.value.description,
-        danger: true,
-        icon: "lucide:triangle-alert",
-        confirmLabel: labels.value.discard,
-        cancelLabel: labels.value.keep,
-      })
+      const allowed = await (typeof current === "function"
+        ? current()
+        : confirm({
+            title: labels.value.title,
+            description: labels.value.description,
+            danger: true,
+            icon: "lucide:triangle-alert",
+            confirmLabel: labels.value.discard,
+            cancelLabel: labels.value.keep,
+          }))
+      return allowed && mine === session
     } finally {
       asking = false
     }

package/src/composables/useCommands.ts

@@ -0,0 +1,123 @@
+import { computed, toValue, type MaybeRefOrGetter } from "vue"
+import type { Command } from "../components/LpCommandPalette.vue"
+import type { ContextMenuItemDef } from "../components/LpContextMenu.vue"
+import { parseCombo, useHotkeys, type HotkeyBinding, type ShortcutGroup, type UseHotkeysOptions } from "./useHotkeys"
+import { usePaletteCommands, type PaletteScope } from "./usePaletteCommands"
+
+/*
+ * One definition of an application command, read by every place that offers it.
+ *
+ * Without this an action is written three times: a `useHotkeys` binding, a
+ * palette command, a menu item, and the three drift. This adds no registry of
+ * its own: the palette's registry (`usePaletteCommands`) lists the command and
+ * the hotkey registry (`useHotkeys`) binds it and feeds `activeShortcuts`, so
+ * LpShortcutsDialog lists it while it is mounted. A menu takes `menuItems`.
+ *
+ *   const { menuItems } = useCommands(() => [{
+ *     id: "server/restart", label: "Restart", group: "Server",
+ *     shortcut: "Ctrl+R", disabled: !canRestart.value, run: restart,
+ *   }])
+ *
+ * The commands are read when asked for, so availability written as a plain
+ * expression in the getter stays live.
+ */
+export interface AppCommand {
+  /** Stable: the palette keeps recents and pins by it. */
+  id: string
+  label: string
+  /** Section in the palette and in the key reference. */
+  group?: string
+  description?: string
+  icon?: string
+  keywords?: string[]
+  /**
+   * Written as it reads: "Ctrl+K", "Shift+Alt+N", or spaces for a sequence,
+   * "G I". Binds the key and labels it in the palette, the menu and the reference.
+   */
+  shortcut?: string
+  /** Listed but not runnable: greyed in the palette and the menu, the key does nothing. */
+  disabled?: boolean
+  /** Gone everywhere, key included. For what this user or this page cannot do at all. */
+  hidden?: boolean
+  /** Marked as dangerous in a menu; the palette has no such mark. */
+  danger?: boolean
+  /** The key also works while a text field has focus. */
+  allowInInput?: boolean
+  /** The key also works while an overlay owns the keyboard. */
+  overLayers?: boolean
+  run: () => unknown | Promise<unknown>
+}
+
+const DEFAULT_GROUP = "Commands"
+
+const available = (commands: readonly AppCommand[]) => commands.filter((command) => !command.hidden)
+
+/** What the palette lists for a command. */
+export function commandToPalette(command: AppCommand): Command {
+  const { id, label, group, description, icon, keywords, shortcut, disabled, run } = command
+  return { id, label, group, description, icon, keywords, shortcut, disabled, onSelect: run }
+}
+
+/** What a menu shows for a command: LpContextMenu and LpDropdownMenu take these. */
+export function commandToMenuItem(command: AppCommand): ContextMenuItemDef {
+  const { label, icon, shortcut, disabled, danger, run } = command
+  return { label, icon, shortcut, disabled, danger, onSelect: () => void run() }
+}
+
+/** The binding for a command, or null when it has no key. */
+export function commandToHotkey(command: AppCommand): HotkeyBinding | null {
+  const shortcut = command.shortcut?.trim()
+  if (!shortcut) return null
+  const steps = shortcut.split(/\s+/).map(parseCombo)
+  const keys = steps.length > 1 ? { sequence: steps } : steps[0]
+  return {
+    ...keys,
+    allowInInput: command.allowInInput,
+    overLayers: command.overLayers,
+    help: { group: command.group ?? DEFAULT_GROUP, label: command.label, combo: shortcut },
+    // A disabled command leaves the key alone, for the page or the browser.
+    handler: () => {
+      if (command.disabled) return false
+      void command.run()
+    },
+  }
+}
+
+/** The key reference of these commands alone, in LpShortcutsDialog's shape. */
+export function commandShortcuts(commands: readonly AppCommand[]): ShortcutGroup[] {
+  const groups = new Map<string, ShortcutGroup["entries"]>()
+  for (const command of available(commands)) {
+    if (!command.shortcut) continue
+    const title = command.group ?? DEFAULT_GROUP
+    const entries = groups.get(title) ?? []
+    entries.push({ combo: command.shortcut, label: command.label })
+    groups.set(title, entries)
+  }
+  return [...groups].map(([title, entries]) => ({ title, entries }))
+}
+
+export interface UseCommandsOptions extends Pick<UseHotkeysOptions, "enabled" | "priority" | "scope"> {
+  /** The palette scope to list in. Defaults to the one this component sits in. */
+  palette?: PaletteScope
+}
+
+export function useCommands(commands: MaybeRefOrGetter<readonly AppCommand[]>, options: UseCommandsOptions = {}) {
+  const { palette, ...hotkeys } = options
+  const current = computed(() => available(toValue(commands)))
+
+  usePaletteCommands(() => current.value.map(commandToPalette), { scope: palette })
+  useHotkeys(() => current.value.flatMap((command) => commandToHotkey(command) ?? []), hotkeys)
+
+  return {
+    commands: current,
+    menuItems: computed(() => current.value.map(commandToMenuItem)),
+    shortcuts: computed(() => commandShortcuts(current.value)),
+    /** Runs a command by id, unless it is disabled or hidden. Returns whether it ran. */
+    run(id: string): boolean {
+      const command = current.value.find((candidate) => candidate.id === id)
+      if (!command || command.disabled) return false
+      void command.run()
+      return true
+    },
+  }
+}

package/src/composables/useField.ts

@@ -1,5 +1,6 @@
-import { computed, inject, onScopeDispose, provide, useId, type ComputedRef, type InjectionKey } from "vue"
+import { computed, inject, onScopeDispose, provide, useAttrs, useId, type ComputedRef, type InjectionKey } from "vue"
 import type { FieldNoticeOptions } from "./useFieldNotice"
+import { isElement } from "./useView"
 
 /*
  * What a form field tells the control inside it: the id its label points at,
@@ -39,6 +40,22 @@ export function fieldMessageId(id: string): string {
   return `${id}-message`
 }
 
+/**
+ * The `aria-describedby` of a control: the consumer's own ids, the field's and
+ * whatever the control adds, each once. A template's explicit binding replaces
+ * what `v-bind` passed, undefined included, so every control merges here
+ * instead of dropping the consumer's description.
+ */
+export function mergeDescribedBy(...ids: unknown[]): string | undefined {
+  const all = ids.flatMap((id) => (typeof id === "string" ? id.split(/\s+/) : [])).filter(Boolean)
+  return [...new Set(all)].join(" ") || undefined
+}
+
+/** Is a boolean attribute that arrived through `$attrs` on? The same test Vue renders it by. */
+export function isAttrOn(value: unknown): boolean {
+  return !!value || value === ""
+}
+
 export interface FieldControlState {
   /** The control wraps itself in its own LpFormField (it has a label, hint or error prop). */
   wrapped: boolean
@@ -98,7 +115,7 @@ export function useFieldControl(
  */
 export function focusLeft(event: FocusEvent): boolean {
   const next = event.relatedTarget
-  return !(next instanceof Node && (event.currentTarget as Node | null)?.contains(next))
+  return !(isElement(next) && (event.currentTarget as Node | null)?.contains(next))
 }
 
 /** Trigger and portalled content share a boundary for the control's public blur. */
@@ -125,3 +142,25 @@ export function useFieldBlur(blur: (event: FocusEvent) => void) {
   onScopeDispose(() => cancelPending?.())
   return { partId, onFocusOut }
 }
+
+/** What a control hands the FieldWrapper around it: its id, its texts, and the classes it takes from the app. */
+export function fieldWrapperBinds(
+  wrapped: boolean,
+  field: { id?: string },
+  props: { label?: string; hint?: string; error?: string; required?: boolean },
+  attrs: Record<string, unknown>,
+) {
+  const { label, hint, error, required } = props
+  return { wrapped, id: field.id, label, hint, error, required, class: attrs.class, style: attrs.style }
+}
+
+/** The state of a control that takes its id from the app and draws no wrapper of its own. */
+export function useAttrsField(state: () => { invalid?: boolean; disabled?: boolean }) {
+  const attrs = useAttrs()
+  const field = useFieldControl(() => ({
+    wrapped: false,
+    id: typeof attrs.id === "string" ? attrs.id : undefined,
+    ...state(),
+  }))
+  return { attrs, field }
+}

package/src/composables/useFitScale.ts

@@ -1,3 +1,4 @@
+import { nodeWindow } from "./realm"
 import { onBeforeUnmount, onMounted, ref, watch, type Ref } from "vue"
 
 /*
@@ -29,7 +30,9 @@ export function useFitScale(
   function observe() {
     observer?.disconnect()
     if (typeof ResizeObserver === "undefined") return
-    observer = new ResizeObserver(measure)
+    const el = box.value ?? content.value
+    if (!el) return measure()
+    observer = new (nodeWindow(el).ResizeObserver)(measure)
     if (box.value) observer.observe(box.value)
     if (content.value) observer.observe(content.value)
     measure()

package/src/composables/useFormDraft.ts

@@ -67,6 +67,12 @@ export interface UseFormDraftOptions<T> {
   maxAgeMs?: number
   /** Skip the write without tearing the composable out of the component. */
   disabled?: MaybeRefOrGetter<boolean>
+  /**
+   * Accept a stored value or reject it. The envelope's version follows the
+   * kit, not this form: a draft written before the form changed shape needs
+   * this to be turned away. A rejected draft reads as no draft.
+   */
+  validate?: (value: unknown) => value is T
 }
 
 export interface UseFormDraft<T> {
@@ -86,8 +92,13 @@ export interface UseFormDraft<T> {
    * what to do with each field, because only it knows the form's shape.
    */
   read: () => T | null
-  /** Forget the draft. Call after applying it, and after a successful save. */
-  discard: () => void
+  /**
+   * Forget the draft. Call after applying it, and after a successful save.
+   * With no argument it acts on the key as it is now; a callback that may
+   * outlive the subject (an awaited save) passes the key it started under, so
+   * it cannot delete the draft of whatever the form moved on to.
+   */
+  discard: (key?: string) => void
   /** Write now, ignoring `dirty` and a pending draft. For "save and come back to this later". */
   save: () => void
 }
@@ -128,19 +139,28 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
   const savedAt = ref<string | null>(null)
   const maxAge = options.maxAgeMs ?? WEEK_MS
 
+  function normalizeKey(key: unknown): string {
+    return String(key || "").trim()
+  }
+
   function currentKey(): string {
-    return String(toValue(options.key) || "").trim()
+    return normalizeKey(toValue(options.key))
   }
 
   // An envelope still worth offering, or null. No side effects: the key watcher
   // only looks, and `read` decides what to clear.
+  //
+  // Only this composable writes these, so a missing value or an unreadable
+  // stamp is damage rather than a draft of unknown age: offering it would make
+  // it immortal, since its age could never pass `maxAge`. A stamp from the
+  // future is measured the same way as one from the past, so a clock corrected
+  // by minutes keeps the draft and a stamp years ahead cannot outlive `maxAge`.
   function fresh(parsed: DraftEnvelope<T> | null): boolean {
-    if (!parsed || parsed.version !== ENVELOPE_VERSION) return false
-    if (maxAge <= 0) return true
-    // NaN when the stamp is unreadable, and NaN > maxAge is false — an
-    // unreadable stamp is treated as "no idea how old", which errs towards
-    // offering the draft rather than throwing away somebody's typing.
-    return !(Date.now() - Date.parse(parsed.savedAt) > maxAge)
+    if (!parsed || parsed.version !== ENVELOPE_VERSION || !("value" in Object(parsed))) return false
+    const stamp = typeof parsed.savedAt === "string" ? Date.parse(parsed.savedAt) : Number.NaN
+    if (Number.isNaN(stamp)) return false
+    if (options.validate && !options.validate(parsed.value)) return false
+    return maxAge <= 0 || Math.abs(Date.now() - stamp) <= maxAge
   }
 
   function read(): T | null {
@@ -178,11 +198,15 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
     )
   }
 
-  function discard() {
-    const key = currentKey()
-    hasDraft.value = false
-    savedAt.value = null
-    if (key) store.remove(key)
+  function discard(key?: string) {
+    const current = currentKey()
+    // Not a string when bound straight to an event: `@click="draft.discard"`.
+    const target = typeof key === "string" ? normalizeKey(key) : current
+    if (target === current) {
+      hasDraft.value = false
+      savedAt.value = null
+    }
+    if (target) store.remove(target)
   }
 
   function save() {

package/src/composables/useHintSystem.ts

@@ -2,6 +2,7 @@ import { computed, inject, onBeforeUnmount, provide, reactive, shallowRef, watch
 import type { HintNote } from "../components/LpHintLayer.vue"
 import type { TourContext, TourStep } from "../components/LpTour.vue"
 import { anyModalOpen } from "../components/modalDepth"
+import { isTextEntry } from "./textEntry"
 import { hints } from "./useHints"
 
 /*
@@ -355,8 +356,7 @@ export function hintSummary(
 }
 
 function typing(): boolean {
-  const el = document.activeElement
-  return el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || (el instanceof HTMLElement && el.isContentEditable)
+  return isTextEntry(document.activeElement, { inputType: () => true })
 }
 
 export function createHintSystem(options: HintSystemOptions) {

package/src/composables/useHotkeys.ts

@@ -9,6 +9,9 @@ import {
   type MaybeRefOrGetter,
 } from "vue"
 import { topModalElement } from "../components/modalDepth"
+import { isDev } from "./devWarn"
+import { isNode } from "./realm"
+import { isTextEntry } from "./textEntry"
 
 /*
  * One keydown listener over a registry of bindings, so a shortcut is declared
@@ -29,7 +32,9 @@ import { topModalElement } from "../components/modalDepth"
  *     except for the few that mean something in a field (Escape, a palette).
  *
  * Modifier note: Ctrl and Meta are one modifier here, since macOS binds ⌘ where
- * the rest bind Ctrl. Label the difference in the UI, not in the binding.
+ * the rest bind Ctrl. Label the difference in the UI, not in the binding. These
+ * are cross-platform commands, not a model of the keyboard: Ctrl+Meta+K apart
+ * from Ctrl+K cannot be written.
  *
  * Sequences ("g i", as on GitHub and Gmail) are bindings with `sequence`. A key
  * that starts a sequence is held while the next one is awaited: if it
@@ -162,31 +167,6 @@ export function appleModifierLabel(key: string, apple = isAppleKeyboard): string
   return key
 }
 
-const TEXT_INPUT_TYPES = new Set([
-  "text",
-  "search",
-  "email",
-  "number",
-  "password",
-  "tel",
-  "url",
-])
-
-/**
- * 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.
- */
-function isTextEntry(target: EventTarget | null): boolean {
-  if (!(target instanceof HTMLElement)) return false
-  if (target.isContentEditable) return true
-  if (target instanceof HTMLTextAreaElement) return true
-  if (target instanceof HTMLInputElement) {
-    return TEXT_INPUT_TYPES.has(target.type)
-  }
-  return false
-}
-
 const MODIFIER_KEYS = new Set(["control", "meta", "shift", "alt"])
 
 type KeyLike = Pick<KeyboardEvent, "key" | "code" | "ctrlKey" | "metaKey" | "shiftKey" | "altKey">
@@ -325,12 +305,13 @@ const mounted = state.mounted
 function inScope(target: EventTarget | null, scope: MountedHotkeys["scope"]): boolean {
   const el = toValue(scope)
   if (!el) return true
-  const node = target instanceof Node ? target : null
-  return !!node && (el === node || el.contains(node))
+  return isNode(target) && (el === target || el.contains(target))
 }
 
-function topLayer(): Element | null {
-  const layers = document.querySelectorAll("[data-dismissable-layer]")
+/* The layer on top in the document the key came from: a frame has its own. */
+function topLayer(origin: EventTarget | null): Element | null {
+  const doc = isNode(origin) ? (origin.ownerDocument ?? document) : document
+  const layers = doc.querySelectorAll("[data-dismissable-layer]")
   return layers[layers.length - 1] ?? null
 }
 
@@ -364,7 +345,7 @@ function snapshot(event: KeyboardEvent): KeyLike {
 
 function eligible(event: KeyboardEvent): HotkeyBinding[] {
   const inTextEntry = isTextEntry(event.target)
-  const blocker = event.key === "Escape" ? topLayer() : topModalElement()
+  const blocker = event.key === "Escape" ? topLayer(event.target) : topModalElement()
   const entries = [...mounted].sort(
     (a, b) => Number(toValue(b.priority) || 0) - Number(toValue(a.priority) || 0) || b.order - a.order,
   )
@@ -407,6 +388,9 @@ function flushHeld() {
 function onKeydown(event: KeyboardEvent) {
   if (event.isComposing || event.defaultPrevented) return
   if (pressed.length && MODIFIER_KEYS.has(event.key.toLowerCase())) return
+  // A key held down is one press: its auto-repeat must not end the wait, or
+  // complete a "g g" nobody typed.
+  if (pressed.length && event.repeat) return
   if (pressed.length && event.key === "Escape") {
     resetSequence()
   }
@@ -463,7 +447,7 @@ export function useHotkeys(
     order: ++state.order,
     host: () => {
       const el = instance?.vnode.el
-      return el instanceof Node ? el : null
+      return isNode(el) ? el : null
     },
   }
   onMounted(() => {
@@ -477,11 +461,13 @@ export function useHotkeys(
   })
   onBeforeUnmount(() => {
     mounted.delete(entry)
+    // What is held may be the handler of the component going away; a sequence
+    // waits for up to its timeout, and must not run into a dead component.
+    resetSequence()
     if (!mounted.size && state.listening) {
       window.removeEventListener("keydown", onKeydown)
       window.removeEventListener("blur", resetSequence)
       state.listening = false
-      resetSequence()
     }
   })
 }
@@ -576,21 +562,6 @@ export const hotkeyConflicts = computed<HotkeyConflict[]>(() =>
 
 const warned = new Set<string>()
 
-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, the warning simply stays off.
- */
-function isDev(): boolean {
-  try {
-    return process.env.NODE_ENV !== "production"
-  } catch {
-    return false
-  }
-}
-
 function warnConflicts() {
   if (!isDev()) return
   for (const conflict of hotkeyConflicts.value) {

package/src/composables/useInView.ts

@@ -1,3 +1,4 @@
+import { nodeWindow } from "./realm"
 import { onBeforeUnmount, ref, watch, type Ref } from "vue"
 
 /*
@@ -40,7 +41,7 @@ export function useInView(options: { rootMargin?: string; threshold?: number } =
       observer?.disconnect()
       observer = null
       if (!node || typeof IntersectionObserver === "undefined") return sync()
-      observer = new IntersectionObserver(
+      observer = new (nodeWindow(node).IntersectionObserver)(
         (entries) => {
           intersecting.value = entries.some((entry) => entry.isIntersecting)
           sync()

package/src/composables/useInputFilter.ts

@@ -1,4 +1,5 @@
 import { computed, type MaybeRefOrGetter, toValue } from "vue"
+import { isElement } from "./useView"
 
 /*
  * Cursor- and IME-safe input filtering + pattern validation for native <input>.
@@ -111,12 +112,14 @@ export function useInputFilter(options: UseInputFilterOptions = {}) {
   function sanitize(target: EventTarget | null): boolean {
     const re = restrict.value
     if (!re) return false
-    if (!(target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement)) return false
-    const { text, caret } = stripDisallowed(target.value, re, target.selectionStart ?? target.value.length)
-    if (text === target.value) return false
-    target.value = text
+    // By tag: a field of an LpFrame is no instance of this window's classes.
+    if (!isElement(target) || !["INPUT", "TEXTAREA"].includes(target.tagName)) return false
+    const field = target as HTMLInputElement | HTMLTextAreaElement
+    const { text, caret } = stripDisallowed(field.value, re, field.selectionStart ?? field.value.length)
+    if (text === field.value) return false
+    field.value = text
     try {
-      target.setSelectionRange(caret, caret)
+      field.setSelectionRange(caret, caret)
     } catch {
       // Input types without a selection (number, email) cannot place a caret.
     }

package/src/composables/useInputMask.ts

@@ -1,4 +1,5 @@
 import { computed, toValue, type MaybeRefOrGetter } from "vue"
+import { isElement } from "./useView"
 
 /*
  * Format-as-you-type for a native <input> without losing the caret.
@@ -193,6 +194,10 @@ export interface UseInputMaskOptions {
   onChange?: (masked: string, raw: string, complete: boolean) => void
 }
 
+/* By tag: a field of an LpFrame is no instance of this window's classes. */
+const isInput = (target: EventTarget | null): target is HTMLInputElement =>
+  isElement(target) && target.tagName === "INPUT"
+
 /**
  * Bind `onBeforeInput`, `onInput` and `onCompositionEnd` to the input, and show
  * `format(model).masked` as its value.
@@ -224,7 +229,7 @@ export function useInputMask(options: UseInputMaskOptions) {
   function onBeforeInput(event: InputEvent): void {
     const s = spec.value
     const el = event.target
-    if (!s || event.isComposing || !(el instanceof HTMLInputElement)) return
+    if (!s || event.isComposing || !isInput(el)) return
     const backward = event.inputType === "deleteContentBackward"
     if (!backward && event.inputType !== "deleteContentForward") return
     const start = el.selectionStart
@@ -242,12 +247,12 @@ export function useInputMask(options: UseInputMaskOptions) {
 
   /** Attach to `input`. Composition is left alone until it ends. */
   function onInput(event: Event): void {
-    if ((event as InputEvent).isComposing || !(event.target instanceof HTMLInputElement)) return
+    if ((event as InputEvent).isComposing || !isInput(event.target)) return
     reformat(event.target)
   }
 
   function onCompositionEnd(event: CompositionEvent): void {
-    if (event.target instanceof HTMLInputElement) reformat(event.target)
+    if (isInput(event.target)) reformat(event.target)
   }
 
   return { active: computed(() => !!spec.value), format, onBeforeInput, onInput, onCompositionEnd }