@leavepulse/ui 0.43.4 → 0.45.0

package/src/composables/useHotkeys.ts

@@ -1,4 +1,14 @@
-import { computed, onBeforeUnmount, onMounted, shallowReactive, type MaybeRefOrGetter, toValue } from "vue"
+import {
+  computed,
+  getCurrentInstance,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  shallowReactive,
+  toValue,
+  type MaybeRefOrGetter,
+} from "vue"
+import { topModalElement } from "../components/modalDepth"
 
 /*
  * One keydown listener over a registry of bindings, so a shortcut is declared
@@ -20,11 +30,30 @@ import { computed, onBeforeUnmount, onMounted, shallowReactive, type MaybeRefOrG
  *
  * 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.
+ *
+ * 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
+ * continues a sequence, the sequence runs; if not, or after the timeout, the
+ * single-key binding on the held key (if any) runs, and the new key is handled
+ * as a fresh press. A key that starts no sequence runs at once, so sequences
+ * cost nothing to the bindings they do not collide with.
  */
 
-export interface HotkeyBinding {
-  /** Layout-produced key, compared case-insensitively ("l", "f2", "escape"). */
+/** One key of a sequence: a bare key ("g") or a full chord. */
+export interface HotkeyStep {
   key: string
+  code?: string
+  ctrl?: boolean
+  shift?: boolean
+  alt?: boolean
+}
+
+export interface HotkeyBinding {
+  /**
+   * Layout-produced key, compared case-insensitively ("l", "f2", "escape").
+   * Required unless the binding is a `sequence`.
+   */
+  key?: string
   /**
    * Physical key position ("KeyL", "F2", "Digit1"). Matches on its own, which
    * is what makes non-Latin layouts work.
@@ -34,11 +63,31 @@ export interface HotkeyBinding {
   ctrl?: boolean
   shift?: boolean
   alt?: boolean
+  /**
+   * Keys pressed one after another: `"g i"`, or steps for chords and physical
+   * positions (`[{ key: "g", code: "KeyG" }, { key: "i", code: "KeyI" }]`).
+   * The string form splits on spaces, so a Space step needs the array form.
+   */
+  sequence?: string | (string | HotkeyStep)[]
+  /** How long a sequence waits for its next key, in ms. Default 1000. */
+  timeout?: number
+  /** Extra condition checked on every press; `false` leaves the key alone. */
+  when?: (event: KeyboardEvent) => boolean
   /**
    * Runs even while a text field has focus. Only for shortcuts that mean
    * something there — Escape, and the palette the user reaches from anywhere.
    */
   allowInInput?: boolean
+  /**
+   * Runs even while an overlay owns the keyboard. By default a binding declared
+   * outside the topmost modal stays quiet while that modal is open, and an
+   * Escape binding declared outside the topmost dismissable layer (dialog,
+   * popover, menu) leaves Escape to that layer, so a page-level shortcut can
+   * neither act behind a dialog nor stop the dialog from closing.
+   */
+  overLayers?: boolean
+  /** Set `false` to ignore auto-repeat while the key is held. */
+  repeat?: boolean
   /**
    * How the key reference lists this binding while it is mounted. Bindings
    * without it still work, they just stay out of `activeShortcuts`.
@@ -62,15 +111,20 @@ export interface HotkeyHelp {
   /**
    * Written the way it reads, "+"-separated. Defaults to one built from the
    * binding; set it where the binding is not the whole story, such as the
-   * second key of a chord ("G+D") or a key that needs Shift to type ("?").
+   * key that needs Shift to type ("?"). Sequences read with spaces: "G I".
    */
   combo?: string
 }
 
 export interface ShortcutEntry {
-  /** Rendered one <kbd> per "+"-separated key, so write it the way it reads. */
+  /**
+   * Rendered one <kbd> per "+"-separated key, so write it the way it reads.
+   * Spaces separate the steps of a sequence ("G I", "Ctrl+K Ctrl+S").
+   */
   combo: string
   label: string
+  /** Another mounted binding answers the same keys at the same priority. */
+  conflict?: boolean
 }
 
 export interface ShortcutGroup {
@@ -87,12 +141,22 @@ export const isAppleKeyboard =
   typeof navigator !== "undefined"
   && /Mac|iPhone|iPad|iPod/.test(navigator.platform || "")
 
+/**
+ * `isAppleKeyboard` for render paths: false until mounted, so the server and
+ * the hydrating client print the same label and the client switches after.
+ */
+export function useAppleKeyboard() {
+  const apple = ref(false)
+  onMounted(() => (apple.value = isAppleKeyboard))
+  return apple
+}
+
 /**
  * The symbol to print for a modifier on this platform. Bindings treat Ctrl and
  * Meta as one modifier, so only the label may differ — never the binding.
  */
-export function appleModifierLabel(key: string): string {
-  if (!isAppleKeyboard) return key
+export function appleModifierLabel(key: string, apple = isAppleKeyboard): string {
+  if (!apple) return key
   if (key === "Ctrl") return "⌘"
   if (key === "Alt") return "⌥"
   return key
@@ -123,17 +187,54 @@ function isTextEntry(target: EventTarget | null): boolean {
   return false
 }
 
-function matches(event: KeyboardEvent, binding: HotkeyBinding): boolean {
+const MODIFIER_KEYS = new Set(["control", "meta", "shift", "alt"])
+
+type KeyLike = Pick<KeyboardEvent, "key" | "code" | "ctrlKey" | "metaKey" | "shiftKey" | "altKey">
+
+export function matchesHotkey(event: KeyLike, binding: HotkeyBinding | HotkeyStep): boolean {
+  if (binding.key === undefined) return false
+  const key = binding.key.toLowerCase()
   const ctrlHeld = event.ctrlKey || event.metaKey
-  if (ctrlHeld !== Boolean(binding.ctrl)) return false
-  if (event.shiftKey !== Boolean(binding.shift)) return false
-  if (event.altKey !== Boolean(binding.alt)) return false
+  const wantsCtrl = Boolean(binding.ctrl) || key === "control" || key === "meta"
+  if (ctrlHeld !== wantsCtrl) return false
+  // Shift is part of typing a symbol on most layouts ("?", "+"), so a binding
+  // on a symbol that does not mention Shift accepts it either way.
+  const symbol = key.length === 1 && key.toLowerCase() === key.toUpperCase()
+  const shiftFree = key === "shift" || (binding.shift === undefined && symbol)
+  if (!shiftFree && event.shiftKey !== Boolean(binding.shift)) return false
+  if (key !== "alt" && event.altKey !== Boolean(binding.alt)) return false
+  if (MODIFIER_KEYS.has(key)) return event.key.toLowerCase() === key
   return (
-    event.key.toLowerCase() === binding.key.toLowerCase()
+    event.key.toLowerCase() === key
     || (binding.code !== undefined && event.code === binding.code)
   )
 }
 
+/** The keys a binding waits for, in order: one step for a plain binding. */
+export function hotkeySteps(binding: HotkeyBinding): HotkeyStep[] {
+  const raw = binding.sequence
+  if (raw === undefined) {
+    if (binding.key === undefined) return []
+    const { key, code, ctrl, shift, alt } = binding
+    return [{ key, code, ctrl, shift, alt }]
+  }
+  const list = typeof raw === "string" ? raw.trim().split(/\s+/) : raw
+  return list.map((step) => (typeof step === "string" ? { key: step } : step))
+}
+
+/**
+ * Where a run of presses stands against a binding: "full" when they spell it
+ * out, "prefix" when more keys would, otherwise null.
+ */
+export function sequenceProgress(presses: KeyLike[], binding: HotkeyBinding): "full" | "prefix" | null {
+  const steps = hotkeySteps(binding)
+  if (!steps.length || presses.length > steps.length) return null
+  for (let i = 0; i < presses.length; i++) {
+    if (!matchesHotkey(presses[i]!, steps[i]!)) return null
+  }
+  return presses.length === steps.length ? "full" : "prefix"
+}
+
 /**
  * Bind a list of hotkeys for as long as the calling component is mounted.
  *
@@ -165,11 +266,23 @@ interface MountedHotkeys {
   enabled: MaybeRefOrGetter<boolean> | undefined
   priority: MaybeRefOrGetter<number> | undefined
   order: number
+  /** Where the declaring component sits in the DOM, for the overlay check. */
+  host: () => Node | null
 }
 
-const mounted = shallowReactive(new Set<MountedHotkeys>())
-let mountOrder = 0
-let listening = false
+// Pinned to a global symbol for the same reason as the toast queue: a barrel
+// and a deep import must not end up with two registries and two listeners.
+const STATE_KEY = Symbol.for("@leavepulse/ui:hotkeys")
+type GlobalWithHotkeys = typeof globalThis & {
+  [STATE_KEY]?: { mounted: Set<MountedHotkeys>; order: number; listening: boolean }
+}
+const g = globalThis as GlobalWithHotkeys
+const state = (g[STATE_KEY] ??= {
+  mounted: shallowReactive(new Set<MountedHotkeys>()),
+  order: 0,
+  listening: false,
+})
+const mounted = state.mounted
 
 function inScope(target: EventTarget | null, scope: MountedHotkeys["scope"]): boolean {
   const el = toValue(scope)
@@ -178,47 +291,159 @@ function inScope(target: EventTarget | null, scope: MountedHotkeys["scope"]): bo
   return !!node && (el === node || el.contains(node))
 }
 
-function onKeydown(event: KeyboardEvent) {
-  if (event.isComposing) return
+function topLayer(): Element | null {
+  const layers = document.querySelectorAll("[data-dismissable-layer]")
+  return layers[layers.length - 1] ?? null
+}
+
+function insideOf(entry: MountedHotkeys, layer: Element): boolean {
+  const scope = toValue(entry.scope)
+  const node = scope ?? entry.host()
+  return !!node && layer.contains(node)
+}
+
+interface Candidate {
+  binding: HotkeyBinding
+  event: KeyboardEvent
+}
+
+const DEFAULT_TIMEOUT = 1000
+const pressed: KeyLike[] = []
+let held: Candidate[] = []
+let holdTimer: ReturnType<typeof setTimeout> | undefined
+const pendingKeys = ref<string[]>([])
+
+/**
+ * The keys of a sequence typed so far ("G" after the first key of "g i"),
+ * empty when nothing is pending. For a "G…" hint while the next key is awaited.
+ */
+export const pendingHotkey = computed(() => pendingKeys.value)
+
+function snapshot(event: KeyboardEvent): KeyLike {
+  const { key, code, ctrlKey, metaKey, shiftKey, altKey } = event
+  return { key, code, ctrlKey, metaKey, shiftKey, altKey }
+}
+
+function eligible(event: KeyboardEvent): HotkeyBinding[] {
   const inTextEntry = isTextEntry(event.target)
+  const blocker = event.key === "Escape" ? topLayer() : topModalElement()
   const entries = [...mounted].sort(
     (a, b) => Number(toValue(b.priority) || 0) - Number(toValue(a.priority) || 0) || b.order - a.order,
   )
+  const out: HotkeyBinding[] = []
   for (const entry of entries) {
     if (toValue(entry.enabled) === false || !inScope(event.target, entry.scope)) continue
+    const covered = !!blocker && !insideOf(entry, blocker)
     for (const binding of entry.read()) {
       if (inTextEntry && !binding.allowInInput) continue
-      if (!matches(event, binding)) continue
-      if (binding.handler(event) === false) continue
+      if (event.repeat && binding.repeat === false) continue
+      if (covered && !binding.overLayers) continue
+      if (binding.when && !binding.when(event)) continue
+      out.push(binding)
+    }
+  }
+  return out
+}
+
+function run(candidates: Candidate[]): boolean {
+  for (const { binding, event } of candidates) {
+    if (binding.handler(event) !== false) return true
+  }
+  return false
+}
+
+function resetSequence() {
+  clearTimeout(holdTimer)
+  holdTimer = undefined
+  pressed.length = 0
+  held = []
+  pendingKeys.value = []
+}
+
+function flushHeld() {
+  const waiting = held
+  resetSequence()
+  run(waiting)
+}
+
+function onKeydown(event: KeyboardEvent) {
+  if (event.isComposing || event.defaultPrevented) return
+  if (pressed.length && MODIFIER_KEYS.has(event.key.toLowerCase())) return
+  if (pressed.length && event.key === "Escape") {
+    resetSequence()
+  }
+  const presses = [...pressed, snapshot(event)]
+  const bindings = eligible(event)
+  const full: Candidate[] = []
+  let waitFor = 0
+  for (const binding of bindings) {
+    const progress = sequenceProgress(presses, binding)
+    if (progress === "full") full.push({ binding, event })
+    else if (progress === "prefix") waitFor = Math.max(waitFor, binding.timeout ?? DEFAULT_TIMEOUT)
+  }
+  if (waitFor) {
+    clearTimeout(holdTimer)
+    pressed.push(snapshot(event))
+    held = full
+    pendingKeys.value = pressed.map(pressLabel)
+    holdTimer = setTimeout(flushHeld, waitFor)
+    event.preventDefault()
+    return
+  }
+  if (full.length) {
+    resetSequence()
+    if (run(full)) {
       event.preventDefault()
       return
     }
   }
+  if (pressed.length) {
+    flushHeld()
+    onKeydown(event)
+  }
+}
+
+function pressLabel(press: KeyLike): string {
+  return chordOf({
+    key: press.key,
+    ctrl: press.ctrlKey || press.metaKey,
+    alt: press.altKey,
+    shift: press.shiftKey && press.key.length !== 1,
+  })
 }
 
 export function useHotkeys(
   bindings: MaybeRefOrGetter<HotkeyBinding[]>,
   options: UseHotkeysOptions = {},
 ) {
+  const instance = getCurrentInstance()
   const entry: MountedHotkeys = {
     read: () => toValue(bindings),
     scope: options.scope,
     enabled: options.enabled,
     priority: options.priority,
-    order: ++mountOrder,
+    order: ++state.order,
+    host: () => {
+      const el = instance?.vnode.el
+      return el instanceof Node ? el : null
+    },
   }
   onMounted(() => {
     mounted.add(entry)
-    if (!listening) {
+    warnConflicts()
+    if (!state.listening) {
       window.addEventListener("keydown", onKeydown)
-      listening = true
+      window.addEventListener("blur", resetSequence)
+      state.listening = true
     }
   })
   onBeforeUnmount(() => {
     mounted.delete(entry)
-    if (!mounted.size && listening) {
+    if (!mounted.size && state.listening) {
       window.removeEventListener("keydown", onKeydown)
-      listening = false
+      window.removeEventListener("blur", resetSequence)
+      state.listening = false
+      resetSequence()
     }
   })
 }
@@ -236,10 +461,110 @@ const KEY_NAMES: Record<string, string> = {
   arrowright: "→",
 }
 
+function chordOf(step: HotkeyStep): string {
+  const key = step.key.toLowerCase()
+  const name = KEY_NAMES[key] ?? (key.length === 1 || /^f\d+$/.test(key) ? key.toUpperCase() : step.key)
+  return [step.ctrl && "Ctrl", step.alt && "Alt", step.shift && "Shift", name].filter(Boolean).join("+")
+}
+
 function comboOf(binding: HotkeyBinding): string {
-  const key = binding.key.toLowerCase()
-  const name = KEY_NAMES[key] ?? (key.length === 1 || /^f\d+$/.test(key) ? key.toUpperCase() : binding.key)
-  return [binding.ctrl && "Ctrl", binding.alt && "Alt", binding.shift && "Shift", name].filter(Boolean).join("+")
+  return hotkeySteps(binding).map(chordOf).join(" ")
+}
+
+/** Identity of the keys a binding answers, for telling two of them apart. */
+function signatureOf(binding: HotkeyBinding): string {
+  return hotkeySteps(binding)
+    .map((step) => {
+      const key = step.key.toLowerCase()
+      const symbol = key.length === 1 && key === key.toUpperCase()
+      const shift = step.shift === undefined && symbol ? "*" : String(Boolean(step.shift))
+      return `${Boolean(step.ctrl)}:${Boolean(step.alt)}:${shift}:${key}`
+    })
+    .join(" ")
+}
+
+export interface HotkeyConflict {
+  /** The keys both answer, written as in the shortcut reference. */
+  combo: string
+  /** `help` labels of the clashing bindings; unlabelled ones are omitted. */
+  labels: string[]
+  priority: number
+}
+
+/**
+ * Pure part of `hotkeyConflicts`: bindings from different `useHotkeys` calls
+ * answering the same keys at the same priority within the same scope. Within
+ * one call a repeat is deliberate (the first may decline), and a binding with
+ * `when` is conditional by design, so neither counts.
+ */
+export function findHotkeyConflicts(
+  groups: { bindings: HotkeyBinding[]; priority: number; scope: unknown }[],
+): HotkeyConflict[] {
+  const scopeIds = new Map<unknown, number>()
+  const seen = new Map<string, { combo: string; labels: string[]; owners: Set<number>; priority: number }>()
+  groups.forEach((group, owner) => {
+    if (!scopeIds.has(group.scope)) scopeIds.set(group.scope, scopeIds.size)
+    for (const binding of group.bindings) {
+      if (binding.when || !hotkeySteps(binding).length) continue
+      const id = `${group.priority}|${scopeIds.get(group.scope)}|${signatureOf(binding)}`
+      const slot = seen.get(id) ?? {
+        combo: binding.help?.combo ?? comboOf(binding),
+        labels: [],
+        owners: new Set<number>(),
+        priority: group.priority,
+      }
+      slot.owners.add(owner)
+      if (binding.help && !slot.labels.includes(binding.help.label)) slot.labels.push(binding.help.label)
+      seen.set(id, slot)
+    }
+  })
+  return [...seen.values()]
+    .filter((slot) => slot.owners.size > 1)
+    .map(({ combo, labels, priority }) => ({ combo, labels, priority }))
+}
+
+/** Bindings among the mounted ones that answer the same keys. */
+export const hotkeyConflicts = computed<HotkeyConflict[]>(() =>
+  findHotkeyConflicts(
+    [...mounted]
+      .filter((entry) => toValue(entry.enabled) !== false)
+      .map((entry) => ({
+        bindings: entry.read(),
+        priority: Number(toValue(entry.priority) || 0),
+        scope: toValue(entry.scope) ?? null,
+      })),
+  ),
+)
+
+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) {
+    const id = `${conflict.priority}|${conflict.combo}`
+    if (warned.has(id)) continue
+    warned.add(id)
+    console.warn(
+      `[@leavepulse/ui] ${conflict.combo} is bound more than once at priority ${conflict.priority}`
+        + (conflict.labels.length ? ` (${conflict.labels.join(", ")})` : "")
+        + "; only the most recently mounted one runs unless it declines.",
+    )
+  }
 }
 
 /**
@@ -250,13 +575,15 @@ function comboOf(binding: HotkeyBinding): string {
  */
 export const activeShortcuts = computed<ShortcutGroup[]>(() => {
   const groups = new Map<string, ShortcutEntry[]>()
+  const clashing = new Set(hotkeyConflicts.value.map((c) => c.combo))
   for (const entry of mounted) {
     if (toValue(entry.enabled) === false) continue
     for (const binding of entry.read()) {
       if (!binding.help) continue
       const combo = binding.help.combo ?? comboOf(binding)
       const entries = groups.get(binding.help.group) ?? []
-      if (!entries.some((e) => e.combo === combo)) entries.push({ combo, label: binding.help.label })
+      const conflict = clashing.has(combo) || undefined
+      if (!entries.some((e) => e.combo === combo)) entries.push({ combo, label: binding.help.label, conflict })
       groups.set(binding.help.group, entries)
     }
   }

package/src/composables/useInputFilter.ts

@@ -18,6 +18,12 @@ import { computed, type MaybeRefOrGetter, toValue } from "vue"
  *
  * A bare string pattern is treated as a full-string match (anchored), mirroring
  * the native HTML `pattern` attribute.
+ *
+ * Composition cannot be vetoed (its `beforeinput` is not cancelable), and on
+ * Android most keyboards compose ordinary typing, so `beforeinput` alone left
+ * `restrict` doing nothing there. `onInput` and `onCompositionEnd` clean up
+ * whatever got through — composed text, a drop, an autocorrect replacement —
+ * keeping the caret where it was. Bind `onInput` BEFORE reading the value.
  */
 
 export interface UseInputFilterOptions {
@@ -27,31 +33,57 @@ export interface UseInputFilterOptions {
   pattern?: MaybeRefOrGetter<RegExp | string | undefined>
 }
 
-function toAnchored(p: RegExp | string): RegExp {
-  if (p instanceof RegExp) {
-    // Re-anchor so `pattern` validates the whole string, like HTML's attribute.
-    const src = p.source.replace(/^\^/, "").replace(/\$$/, "")
-    return new RegExp(`^(?:${src})$`, p.flags.replace(/[gy]/g, ""))
-  }
+/**
+ * Anchor a pattern to the whole string, like HTML's `pattern` attribute. The
+ * source is wrapped, never edited: anchors the caller wrote stay valid inside
+ * the group, while trimming a trailing `$` broke an escaped `\$` into an
+ * unterminated group.
+ */
+export function anchorPattern(p: RegExp | string): RegExp {
+  if (p instanceof RegExp) return new RegExp(`^(?:${p.source})$`, p.flags.replace(/[gy]/g, ""))
   return new RegExp(`^(?:${p})$`)
 }
 
+// Strip g/y so lastIndex can't leak state across .test() calls.
+function charTester(charRe: RegExp): (ch: string) => boolean {
+  const re = new RegExp(charRe.source, charRe.flags.replace(/[gy]/g, ""))
+  return (ch) => re.test(ch)
+}
+
 /** Does a string contain only restrict-allowed characters? */
 function allAllowed(text: string, charRe: RegExp): boolean {
-  // Strip g/y so lastIndex can't leak state across .test() calls, then reuse
-  // the one instance per char (tested by code point, so surrogate pairs hold).
-  const re = new RegExp(charRe.source, charRe.flags.replace(/[gy]/g, ""))
+  const ok = charTester(charRe)
+  // By code point, so surrogate pairs hold.
   for (const ch of text) {
-    if (!re.test(ch)) return false
+    if (!ok(ch)) return false
   }
   return true
 }
 
+/**
+ * `text` with every disallowed character removed, and where `caret` lands once
+ * the characters before it that were removed are gone.
+ */
+export function stripDisallowed(text: string, charRe: RegExp, caret = text.length): { text: string; caret: number } {
+  const ok = charTester(charRe)
+  let kept = ""
+  let at = 0
+  let offset = 0
+  for (const ch of text) {
+    if (ok(ch)) {
+      kept += ch
+      if (offset < caret) at += ch.length
+    }
+    offset += ch.length
+  }
+  return { text: kept, caret: at }
+}
+
 export function useInputFilter(options: UseInputFilterOptions = {}) {
   const restrict = computed(() => toValue(options.restrict))
   const patternRe = computed(() => {
     const p = toValue(options.pattern)
-    return p === undefined ? undefined : toAnchored(p)
+    return p === undefined ? undefined : anchorPattern(p)
   })
 
   /** True when a non-empty value fails `pattern`. Empty is treated as valid. */
@@ -68,12 +100,43 @@ export function useInputFilter(options: UseInputFilterOptions = {}) {
   function onBeforeInput(event: InputEvent): void {
     const re = restrict.value
     if (!re || event.isComposing) return
-    // Deletions / formatting carry no data to validate; let them through.
-    const data = event.data
+    // A drop or a replacement carries its text in dataTransfer, not data.
+    // Deletions / formatting carry neither; let them through.
+    const data = event.data ?? event.dataTransfer?.getData("text") ?? null
     if (data == null) return
     if (!allAllowed(data, re)) event.preventDefault()
   }
 
+  // Remove what slipped past `beforeinput`; true when the value changed.
+  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
+    try {
+      target.setSelectionRange(caret, caret)
+    } catch {
+      // Input types without a selection (number, email) cannot place a caret.
+    }
+    return true
+  }
+
+  /** Attach to `input`, ahead of whatever reads the value. */
+  function onInput(event: Event): void {
+    if ((event as InputEvent).isComposing) return
+    sanitize(event.target)
+  }
+
+  /**
+   * Attach to `compositionend`. Some browsers fire the last `input` before
+   * this, so a cleaned value is announced with a fresh `input` event.
+   */
+  function onCompositionEnd(event: CompositionEvent): void {
+    if (sanitize(event.target)) event.target?.dispatchEvent(new Event("input", { bubbles: true }))
+  }
+
   /**
    * Attach to `paste`. Veto the paste if any pasted char is disallowed, rather
    * than silently dropping part of it — partial pastes confuse more than help.
@@ -85,5 +148,5 @@ export function useInputFilter(options: UseInputFilterOptions = {}) {
     if (text && !allAllowed(text, re)) event.preventDefault()
   }
 
-  return { isInvalid, onBeforeInput, onPaste, patternRe, restrict }
+  return { isInvalid, onBeforeInput, onInput, onCompositionEnd, onPaste, patternRe, restrict }
 }