@leavepulse/ui 0.44.0 → 0.45.1

package/src/composables/useForm.ts

@@ -0,0 +1,314 @@
+import {
+  computed,
+  reactive,
+  ref,
+  toRaw,
+  toValue,
+  watch,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+  type Ref,
+  type UnwrapRef,
+} from "vue"
+
+/*
+ * Form state that every form ends up writing by hand: the values, which
+ * fields were touched, whether anything differs from what was loaded, the
+ * errors, and a submit that cannot run twice.
+ *
+ * Errors are computed for every field but shown only once a field was touched
+ * (blurred, or edited after a blur) or a submit was attempted, so nobody is
+ * told off for a field they have not reached yet.
+ *
+ * `dirty` is the same signal useFormDraft asks for, so the two pair directly:
+ *
+ * ```ts
+ * const form = useForm({ initial: () => record.value, rules: { email: required } })
+ * const draft = useFormDraft({ key: () => `draft:${id}`, value: () => form.values, dirty: form.dirty })
+ * function restore() { form.setValues(draft.read() ?? {}); draft.discard() }
+ * const save = form.handleSubmit(async (values) => { await api.save(values); draft.discard() })
+ * ```
+ *
+ * A reactive `initial` (a record that loads after mount) is adopted while the
+ * form is untouched, and becomes the new baseline for `dirty`; once the user
+ * has changed something, a reload of the record no longer overwrites it.
+ */
+
+export type FormErrorMessage = string | null | undefined | void | false
+export type FieldRule<V, T> = (value: V, values: T) => FormErrorMessage | Promise<FormErrorMessage>
+export type FormRules<T> = { [K in keyof T]?: FieldRule<T[K], T> | FieldRule<T[K], T>[] }
+export type FormErrors<T> = Partial<Record<keyof T | "form", string>>
+
+export interface UseFormOptions<T extends object> {
+  initial: MaybeRefOrGetter<T>
+  rules?: FormRules<T>
+  /** Cross-field checks; return messages by field, or under `form` for the whole form. */
+  validate?: (values: T) => FormErrors<T> | void | Promise<FormErrors<T> | void>
+}
+
+export interface FieldBinding<V> {
+  modelValue: V
+  "onUpdate:modelValue": (value: V) => void
+  onBlur: () => void
+  error: string | undefined
+  invalid: boolean
+}
+
+export interface UseForm<T extends object> {
+  values: UnwrapRef<T>
+  /** Errors as currently computed, shown or not. */
+  errors: ComputedRef<FormErrors<T>>
+  /** Errors the user should see now. */
+  visibleErrors: ComputedRef<FormErrors<T>>
+  touched: Partial<Record<keyof T, boolean>>
+  dirty: ComputedRef<boolean>
+  valid: ComputedRef<boolean>
+  validating: Ref<boolean>
+  submitting: Ref<boolean>
+  submitCount: Ref<number>
+  isDirty: (name: keyof T) => boolean
+  /** Props for a kit control: `<LpInput v-bind="form.field('email')" />`. */
+  field: <K extends keyof T>(name: K) => FieldBinding<T[K]>
+  set: <K extends keyof T>(name: K, value: T[K]) => void
+  setValues: (values: Partial<T>) => void
+  touch: (name: keyof T) => void
+  /** Run the checks for one field, or all of them; resolves to whether it passed. */
+  validate: (name?: keyof T) => Promise<boolean>
+  /** Errors from elsewhere, a server reply most often. Cleared field by field on edit. */
+  setErrors: (errors: FormErrors<T>) => void
+  /** Back to `values` (or the current initial), which also become the new baseline. */
+  reset: (values?: T) => void
+  /**
+   * Wrap the submit handler: touches everything, validates, and calls `fn`
+   * only when valid and not already submitting. A successful `fn` makes the
+   * submitted values the new baseline.
+   */
+  handleSubmit: (fn: (values: T) => unknown) => (event?: Event) => Promise<void>
+}
+
+function clone<T>(value: T): T {
+  try {
+    return structuredClone(toRaw(value))
+  } catch {
+    return JSON.parse(JSON.stringify(value)) as T
+  }
+}
+
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime()
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  const ka = Object.keys(a)
+  const kb = Object.keys(b)
+  if (ka.length !== kb.length) return false
+  return ka.every((k) => deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]))
+}
+
+function message(result: FormErrorMessage): string | undefined {
+  return typeof result === "string" && result ? result : undefined
+}
+
+export function useForm<T extends object>(options: UseFormOptions<T>): UseForm<T> {
+  let baseline = clone(toValue(options.initial))
+  const values = reactive(clone(baseline)) as UnwrapRef<T>
+  const plain = () => values as unknown as T
+  const errors = reactive<FormErrors<T>>({}) as FormErrors<T>
+  const external = reactive<FormErrors<T>>({}) as FormErrors<T>
+  const touched = reactive<Partial<Record<keyof T, boolean>>>({}) as Partial<Record<keyof T, boolean>>
+  const validating = ref(false)
+  const submitting = ref(false)
+  const submitCount = ref(0)
+  const runs = new Map<keyof T | "form", number>()
+  const baseVersion = ref(0)
+
+  const keys = (): (keyof T)[] => Object.keys(plain()) as (keyof T)[]
+
+  const dirty = computed(() => {
+    void baseVersion.value
+    return !deepEqual(plain(), baseline)
+  })
+
+  function isDirty(name: keyof T): boolean {
+    void baseVersion.value
+    return !deepEqual(plain()[name], baseline[name])
+  }
+
+  async function checkField(name: keyof T): Promise<string | undefined> {
+    const rule = options.rules?.[name]
+    const list = (Array.isArray(rule) ? rule : rule ? [rule] : []) as FieldRule<unknown, T>[]
+    for (const r of list) {
+      const found = message(await r(plain()[name], plain()))
+      if (found) return found
+    }
+    return undefined
+  }
+
+  async function runField(name: keyof T): Promise<boolean> {
+    const run = (runs.get(name) ?? 0) + 1
+    runs.set(name, run)
+    const found = await checkField(name)
+    if (runs.get(name) !== run) return !errors[name]
+    if (found) errors[name] = found
+    else delete errors[name]
+    return !found && !external[name]
+  }
+
+  async function runForm(): Promise<boolean> {
+    if (!options.validate) return true
+    const run = (runs.get("form") ?? 0) + 1
+    runs.set("form", run)
+    const found = (await options.validate(plain())) ?? {}
+    if (runs.get("form") !== run) return true
+    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
+    }
+    return ok
+  }
+
+  async function validate(name?: keyof T): Promise<boolean> {
+    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)
+    } finally {
+      validating.value = false
+    }
+  }
+
+  function touch(name: keyof T): void {
+    touched[name] = true
+    void validate(name)
+  }
+
+  function set<K extends keyof T>(name: K, value: T[K]): void {
+    ;(values as unknown as T)[name] = value
+  }
+
+  function setValues(next: Partial<T>): void {
+    for (const [k, v] of Object.entries(next) as [keyof T, T[keyof T]][]) set(k, v)
+  }
+
+  function clearState(): void {
+    for (const k of Object.keys(errors)) delete errors[k as keyof 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()
+    submitCount.value = 0
+  }
+
+  function adopt(next: T): void {
+    baseline = clone(next)
+    const target = values as unknown as Record<string, unknown>
+    for (const k of Object.keys(target)) if (!(k in (baseline as object))) delete target[k]
+    Object.assign(target, clone(baseline))
+    baseVersion.value++
+  }
+
+  function reset(next?: T): void {
+    adopt(next ?? toValue(options.initial))
+    clearState()
+  }
+
+  function setErrors(next: FormErrors<T>): void {
+    for (const [k, v] of Object.entries(next) as [keyof T | "form", string | undefined][]) {
+      if (v) external[k] = v
+      else delete external[k]
+    }
+  }
+
+  watch(
+    () => toValue(options.initial),
+    (next) => {
+      if (!dirty.value && !deepEqual(next, baseline)) adopt(next)
+    },
+    { deep: true },
+  )
+
+  // An edit re-checks a field already touched, and drops an external error on it.
+  let snapshot = clone(plain())
+  watch(
+    plain,
+    () => {
+      const now = clone(plain())
+      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)
+      }
+      snapshot = now
+    },
+    { deep: true },
+  )
+
+  const merged = computed<FormErrors<T>>(() => ({ ...errors, ...external }))
+  const visibleErrors = computed<FormErrors<T>>(() => {
+    const all = merged.value
+    if (submitCount.value) return all
+    const shown: FormErrors<T> = {}
+    for (const [k, v] of Object.entries(all) as [keyof T, string][]) {
+      if (touched[k] || external[k]) shown[k] = v
+    }
+    return shown
+  })
+  const valid = computed(() => !Object.values(merged.value).some(Boolean))
+
+  function field<K extends keyof T>(name: K): FieldBinding<T[K]> {
+    const error = visibleErrors.value[name]
+    return {
+      modelValue: (values as unknown as T)[name],
+      "onUpdate:modelValue": (value: T[K]) => set(name, value),
+      onBlur: () => touch(name),
+      error,
+      invalid: !!error,
+    }
+  }
+
+  function handleSubmit(fn: (values: T) => unknown) {
+    return async (event?: Event) => {
+      event?.preventDefault()
+      if (submitting.value) return
+      submitting.value = true
+      try {
+        submitCount.value++
+        for (const name of keys()) touched[name] = true
+        if (!(await validate())) return
+        const submitted = clone(plain())
+        await fn(submitted)
+        if (deepEqual(plain(), submitted)) {
+          baseline = submitted
+          baseVersion.value++
+        }
+      } finally {
+        submitting.value = false
+      }
+    }
+  }
+
+  return {
+    values,
+    errors: merged,
+    visibleErrors,
+    touched,
+    dirty,
+    valid,
+    validating,
+    submitting,
+    submitCount,
+    isDirty,
+    field,
+    set,
+    setValues,
+    touch,
+    validate,
+    setErrors,
+    reset,
+    handleSubmit,
+  }
+}

package/src/composables/useHotkeys.ts

@@ -30,11 +30,30 @@ import { topModalElement } from "../components/modalDepth"
  *
  * 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.
@@ -44,6 +63,16 @@ 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.
@@ -82,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 {
@@ -155,7 +189,10 @@ function isTextEntry(target: EventTarget | null): boolean {
 
 const MODIFIER_KEYS = new Set(["control", "meta", "shift", "alt"])
 
-export function matchesHotkey(event: KeyboardEvent, binding: HotkeyBinding): boolean {
+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
   const wantsCtrl = Boolean(binding.ctrl) || key === "control" || key === "meta"
@@ -173,6 +210,31 @@ export function matchesHotkey(event: KeyboardEvent, binding: HotkeyBinding): boo
   )
 }
 
+/** 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.
  *
@@ -240,13 +302,35 @@ function insideOf(entry: MountedHotkeys, layer: Element): boolean {
   return !!node && layer.contains(node)
 }
 
-function onKeydown(event: KeyboardEvent) {
-  if (event.isComposing || event.defaultPrevented) return
+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)
@@ -254,12 +338,78 @@ function onKeydown(event: KeyboardEvent) {
       if (inTextEntry && !binding.allowInInput) continue
       if (event.repeat && binding.repeat === false) continue
       if (covered && !binding.overLayers) continue
-      if (!matchesHotkey(event, binding)) continue
-      if (binding.handler(event) === false) 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(
@@ -280,8 +430,10 @@ export function useHotkeys(
   }
   onMounted(() => {
     mounted.add(entry)
+    warnConflicts()
     if (!state.listening) {
       window.addEventListener("keydown", onKeydown)
+      window.addEventListener("blur", resetSequence)
       state.listening = true
     }
   })
@@ -289,7 +441,9 @@ export function useHotkeys(
     mounted.delete(entry)
     if (!mounted.size && state.listening) {
       window.removeEventListener("keydown", onKeydown)
+      window.removeEventListener("blur", resetSequence)
       state.listening = false
+      resetSequence()
     }
   })
 }
@@ -307,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.",
+    )
+  }
 }
 
 /**
@@ -321,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)
     }
   }