@leavepulse/ui 0.40.1 → 0.41.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: () => void | boolean
+  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 ("?").
+   */
+  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[]
 }
 
 /**
@@ -149,12 +179,83 @@ export function useHotkeys(
       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
+      if (binding.handler(event) === false) continue
       event.preventDefault()
       return
     }
   }
 
-  onMounted(() => window.addEventListener("keydown", onKeydown))
-  onBeforeUnmount(() => window.removeEventListener("keydown", onKeydown))
+  const read = () => toValue(bindings)
+  onMounted(() => {
+    window.addEventListener("keydown", onKeydown)
+    mounted.add(read)
+  })
+  onBeforeUnmount(() => {
+    window.removeEventListener("keydown", onKeydown)
+    mounted.delete(read)
+  })
+}
+
+/*
+ * Every mounted binding list, in mount order. The lists are getters, so the
+ * reference below follows the state behind them too: a binding that only
+ * exists while a mode is on shows up and goes away with that mode.
+ */
+const mounted = shallowReactive(new Set<() => HotkeyBinding[]>())
+
+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 read of mounted) {
+    for (const binding of 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 }))
+})
+
+/**
+ * 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"