@leavepulse/ui 0.40.1 → 0.42.0

package/src/composables/useHotkeys.ts

@@ -1,4 +1,4 @@
-import { onBeforeUnmount, onMounted, type MaybeRefOrGetter, toValue } from "vue"
+import { computed, onBeforeUnmount, onMounted, shallowReactive, type MaybeRefOrGetter, toValue } from "vue"
 
 /*
  * One keydown listener over a registry of bindings, so a shortcut is declared
@@ -39,13 +39,43 @@ export interface HotkeyBinding {
    * something there — Escape, and the palette the user reaches from anywhere.
    */
   allowInInput?: boolean
+  /**
+   * How the key reference lists this binding while it is mounted. Bindings
+   * without it still work, they just stay out of `activeShortcuts`.
+   */
+  help?: HotkeyHelp
   /**
    * Returning `false` declines the key: the event keeps its default and the
    * search moves on. This is what lets a binding defer to a layer that owns the
    * key better than it does — Escape belongs to whichever overlay is on top,
-   * and swallowing it here would close all of them.
+   * and swallowing it here would close all of them. The event is passed for
+   * the checks only it can answer: where the focus is, whether an inner
+   * control already took the key.
+   */
+  handler: (event: KeyboardEvent) => void | boolean
+}
+
+export interface HotkeyHelp {
+  /** Section of the reference the entry goes under. */
+  group: string
+  label: string
+  /**
+   * 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 ("?").
    */
-  handler: () => void | boolean
+  combo?: string
+}
+
+export interface ShortcutEntry {
+  /** Rendered one <kbd> per "+"-separated key, so write it the way it reads. */
+  combo: string
+  label: string
+}
+
+export interface ShortcutGroup {
+  title: string
+  entries: ShortcutEntry[]
 }
 
 /**
@@ -112,6 +142,8 @@ function matches(event: KeyboardEvent, binding: HotkeyBinding): boolean {
  * formality.
  */
 export interface UseHotkeysOptions {
+  enabled?: MaybeRefOrGetter<boolean>
+  priority?: MaybeRefOrGetter<number>
   /**
    * Only act while the focus is inside this element.
    *
@@ -127,34 +159,124 @@ export interface UseHotkeysOptions {
   scope?: MaybeRefOrGetter<HTMLElement | null | undefined>
 }
 
+interface MountedHotkeys {
+  read: () => HotkeyBinding[]
+  scope: MaybeRefOrGetter<HTMLElement | null | undefined> | undefined
+  enabled: MaybeRefOrGetter<boolean> | undefined
+  priority: MaybeRefOrGetter<number> | undefined
+  order: number
+}
+
+const mounted = shallowReactive(new Set<MountedHotkeys>())
+let mountOrder = 0
+let listening = false
+
+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))
+}
+
+function onKeydown(event: KeyboardEvent) {
+  if (event.isComposing) return
+  const inTextEntry = isTextEntry(event.target)
+  const entries = [...mounted].sort(
+    (a, b) => Number(toValue(b.priority) || 0) - Number(toValue(a.priority) || 0) || b.order - a.order,
+  )
+  for (const entry of entries) {
+    if (toValue(entry.enabled) === false || !inScope(event.target, entry.scope)) continue
+    for (const binding of entry.read()) {
+      if (inTextEntry && !binding.allowInInput) continue
+      if (!matches(event, binding)) continue
+      if (binding.handler(event) === false) continue
+      event.preventDefault()
+      return
+    }
+  }
+}
+
 export function useHotkeys(
   bindings: MaybeRefOrGetter<HotkeyBinding[]>,
   options: UseHotkeysOptions = {},
 ) {
-  function inScope(target: EventTarget | null): boolean {
-    const el = toValue(options.scope)
-    if (!el) return true
-    const node = target instanceof Node ? target : null
-    // The element itself counts: a focusable canvas holds the focus without
-    // containing anything that could.
-    return !!node && (el === node || el.contains(node))
+  const entry: MountedHotkeys = {
+    read: () => toValue(bindings),
+    scope: options.scope,
+    enabled: options.enabled,
+    priority: options.priority,
+    order: ++mountOrder,
   }
+  onMounted(() => {
+    mounted.add(entry)
+    if (!listening) {
+      window.addEventListener("keydown", onKeydown)
+      listening = true
+    }
+  })
+  onBeforeUnmount(() => {
+    mounted.delete(entry)
+    if (!mounted.size && listening) {
+      window.removeEventListener("keydown", onKeydown)
+      listening = false
+    }
+  })
+}
 
-  function onKeydown(event: KeyboardEvent) {
-    if (event.isComposing) return
-    if (!inScope(event.target)) return
-    const inTextEntry = isTextEntry(event.target)
-    for (const binding of toValue(bindings)) {
-      if (inTextEntry && !binding.allowInInput) continue
-      if (!matches(event, binding)) continue
-      // Claimed only once the handler has run and not declined, so a binding
-      // that stands down leaves the key untouched for whoever handles it next.
-      if (binding.handler() === false) continue
-      event.preventDefault()
-      return
+const KEY_NAMES: Record<string, string> = {
+  escape: "Esc",
+  enter: "Enter",
+  backspace: "Backspace",
+  delete: "Delete",
+  tab: "Tab",
+  " ": "Space",
+  arrowup: "↑",
+  arrowdown: "↓",
+  arrowleft: "←",
+  arrowright: "→",
+}
+
+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("+")
+}
+
+/**
+ * The shortcuts that work right now, grouped for `LpShortcutsDialog`: every
+ * binding with `help` from every mounted `useHotkeys`. A screen that binds its
+ * own keys adds its section while it is open, so the reference never lists a
+ * key that does nothing here or misses one that does.
+ */
+export const activeShortcuts = computed<ShortcutGroup[]>(() => {
+  const groups = new Map<string, ShortcutEntry[]>()
+  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 })
+      groups.set(binding.help.group, entries)
     }
   }
+  return [...groups].map(([title, entries]) => ({ title, entries }))
+})
 
-  onMounted(() => window.addEventListener("keydown", onKeydown))
-  onBeforeUnmount(() => window.removeEventListener("keydown", onKeydown))
+/**
+ * Groups merged by title, entries kept once per combo: what a reference shows
+ * when it lists both its own entries and the live ones.
+ */
+export function mergeShortcutGroups(...lists: ShortcutGroup[][]): ShortcutGroup[] {
+  const groups = new Map<string, ShortcutEntry[]>()
+  for (const list of lists) {
+    for (const group of list) {
+      const entries = groups.get(group.title) ?? []
+      for (const entry of group.entries) {
+        if (!entries.some((e) => e.combo === entry.combo)) entries.push(entry)
+      }
+      groups.set(group.title, entries)
+    }
+  }
+  return [...groups].map(([title, entries]) => ({ title, entries }))
 }

package/src/index.ts

@@ -141,7 +141,6 @@ export { default as LpServiceNode } from "./components/LpServiceNode.vue"
 export type { ServiceNodeData } from "./components/LpServiceNode.vue"
 export { default as LpShift } from "./components/LpShift.vue"
 export { default as LpShortcutsDialog } from "./components/LpShortcutsDialog.vue"
-export type { ShortcutEntry, ShortcutGroup } from "./components/LpShortcutsDialog.vue"
 export { default as LpSidebar } from "./components/LpSidebar.vue"
 export type { SidebarItem, SidebarSection } from "./components/LpSidebar.vue"
 export { default as LpSkeleton } from "./components/LpSkeleton.vue"
@@ -228,8 +227,15 @@ export type { UiConfig } from "./theme/config"
 
 export { useClipboard } from "./composables/useClipboard"
 export type { CopyOptions, UseClipboard } from "./composables/useClipboard"
-export { useHotkeys, isAppleKeyboard, appleModifierLabel } from "./composables/useHotkeys"
-export type { HotkeyBinding } from "./composables/useHotkeys"
+export {
+  useHotkeys,
+  isAppleKeyboard,
+  appleModifierLabel,
+  activeShortcuts,
+  mergeShortcutGroups,
+} from "./composables/useHotkeys"
+export type { HotkeyBinding, HotkeyHelp, ShortcutEntry, ShortcutGroup } from "./composables/useHotkeys"
+export { provideGlass, useGlass } from "./composables/useGlass"
 export { useMergedClass, useMergedAttrs, mergeClass } from "./composables/useMergedClass"
 export { useInputFilter } from "./composables/useInputFilter"
 export type { UseInputFilterOptions } from "./composables/useInputFilter"