@djangocfg/ui-core 2.1.380 → 2.1.382

package/src/hooks/hotkey/formatHotkey.ts

@@ -0,0 +1,96 @@
+'use client';
+
+/**
+ * Human-readable hotkey formatter.
+ *
+ * Translates a `react-hotkeys-hook` combo string into the glyphs users
+ * expect to see in tooltips and cheat-sheets. Honours macOS conventions
+ * (⌘ ⌃ ⌥ ⇧) on Apple devices and falls back to text labels elsewhere.
+ *
+ * @example
+ * formatHotkey('mod+k')     // → '⌘K' on Mac, 'Ctrl+K' elsewhere
+ * formatHotkey('shift+/')   // → '⇧/'
+ * formatHotkey('escape')    // → 'Esc'
+ * formatHotkey('g t')       // → 'G then T' (chord)
+ */
+export function formatHotkey(combo: string, opts: { mac?: boolean } = {}): string {
+  const mac = opts.mac ?? detectMac();
+
+  // Chord: tokens separated by spaces.
+  if (combo.includes(' ')) {
+    return combo
+      .split(/\s+/)
+      .map((part) => formatHotkey(part, { mac }))
+      .join(' then ');
+  }
+
+  // Multiple alternatives via comma — show the first.
+  if (combo.includes(',')) {
+    const first = combo.split(',')[0]?.trim();
+    return first ? formatHotkey(first, { mac }) : combo;
+  }
+
+  return combo
+    .split('+')
+    .map((token) => token.trim().toLowerCase())
+    .filter(Boolean)
+    .map((token) => formatToken(token, mac))
+    .join(mac ? '' : '+');
+}
+
+function detectMac(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  // navigator.userAgentData is Chromium-only; fall back to platform sniff.
+  const ua = (navigator.userAgent || '').toLowerCase();
+  const platform = (navigator.platform || '').toLowerCase();
+  return /mac|iphone|ipad|ipod/.test(platform) || /mac os|macintosh/.test(ua);
+}
+
+function formatToken(token: string, mac: boolean): string {
+  switch (token) {
+    case 'mod':
+      return mac ? '⌘' : 'Ctrl';
+    case 'meta':
+    case 'cmd':
+    case 'command':
+      return mac ? '⌘' : 'Win';
+    case 'ctrl':
+    case 'control':
+      return mac ? '⌃' : 'Ctrl';
+    case 'alt':
+    case 'option':
+      return mac ? '⌥' : 'Alt';
+    case 'shift':
+      return mac ? '⇧' : 'Shift';
+    case 'escape':
+    case 'esc':
+      return 'Esc';
+    case 'enter':
+    case 'return':
+      return mac ? '⏎' : 'Enter';
+    case 'tab':
+      return mac ? '⇥' : 'Tab';
+    case 'space':
+      return mac ? 'Space' : 'Space';
+    case 'backspace':
+      return mac ? '⌫' : 'Backspace';
+    case 'delete':
+    case 'del':
+      return mac ? '⌦' : 'Del';
+    case 'arrowup':
+    case 'up':
+      return '↑';
+    case 'arrowdown':
+    case 'down':
+      return '↓';
+    case 'arrowleft':
+    case 'left':
+      return '←';
+    case 'arrowright':
+    case 'right':
+      return '→';
+    default:
+      if (token.length === 1) return token.toUpperCase();
+      return token.charAt(0).toUpperCase() + token.slice(1);
+  }
+}

package/src/hooks/hotkey/index.ts

@@ -2,3 +2,13 @@
 
 export { useHotkey, useHotkeysContext, HotkeysProvider, isHotkeyPressed } from './useHotkey';
 export type { UseHotkeyOptions, HotkeyCallback, Keys, HotkeyRefType } from './useHotkey';
+
+export { formatHotkey } from './formatHotkey';
+export { useHotkeyChord, type UseHotkeyChordOptions } from './useHotkeyChord';
+export {
+  useHotkeyHelp,
+  useRegisterHotkey,
+  getRegisteredHotkeys,
+  registerHotkey,
+  type RegisteredHotkey,
+} from './useHotkeyHelp';

package/src/hooks/hotkey/useHotkey.ts

@@ -1,26 +1,54 @@
 'use client';
 
+import { useEffect } from 'react';
 import { Options as HotkeysOptions, useHotkeys } from 'react-hotkeys-hook';
 import type { HotkeyCallback, Keys } from 'react-hotkeys-hook';
 
+import { registerHotkey } from './useHotkeyHelp';
+
 /** Ref type for hotkey target element */
 export type HotkeyRefType<T> = T | null;
 
 /**
- * Options for the useHotkey hook
+ * Options for the useHotkey hook.
+ *
+ * Most of the time you only need `{ inInput }` or nothing — sensible
+ * defaults are derived from the key combo (see below).
  */
 export interface UseHotkeyOptions extends Omit<HotkeysOptions, 'enabled'> {
   /** Whether the hotkey is enabled (default: true) */
   enabled?: boolean;
-  /** Scope for the hotkey - useful for context-specific shortcuts */
+  /** Scope for the hotkey — useful for context-specific shortcuts */
   scope?: string;
   /** Only trigger when focus is within a specific element */
   scopes?: string[];
   /** Prevent default browser behavior */
   preventDefault?: boolean;
-  /** Enable in input fields and textareas */
+  /**
+   * Whether the shortcut should also fire when focus is inside an input,
+   * textarea, select, or contenteditable element.
+   *
+   * Default policy (when not specified):
+   *   - Modifier-bearing combos (`cmd+*`, `ctrl+*`, `alt+*`, `shift+*`)
+   *     → `true`. Global app shortcuts (⌘K, Ctrl+S, ⌘/) must work no
+   *     matter where the user is.
+   *   - `escape` → `true`. Escape semantics (blur / close) are universal.
+   *   - Bare single-character keys (`/`, `?`, `j`, …) → `false`. They
+   *     would otherwise eat keystrokes the user is typing into inputs.
+   *   - Function keys, arrows, etc. → `false`.
+   *
+   * Pass `true` or `false` explicitly to override.
+   */
+  inInput?: boolean;
+  /**
+   * @deprecated Use `inInput` instead. Forwarded to react-hotkeys-hook
+   * when explicitly set; otherwise derived from `inInput` / policy.
+   */
   enableOnFormTags?: boolean | readonly ('input' | 'textarea' | 'select')[];
-  /** Enable when contentEditable element is focused */
+  /**
+   * @deprecated Use `inInput` instead. Same forwarding rules as
+   * `enableOnFormTags`.
+   */
   enableOnContentEditable?: boolean;
   /** Split key for multiple hotkey combinations (default: ',') */
   splitKey?: string;
@@ -32,40 +60,24 @@ export interface UseHotkeyOptions extends Omit<HotkeysOptions, 'enabled'> {
 }
 
 /**
- * Simple wrapper hook for react-hotkeys-hook
- *
- * @example
- * // Single key
- * useHotkey('escape', () => closeModal());
+ * Wrapper around react-hotkeys-hook with an opinionated `inInput` policy.
  *
  * @example
- * // Key combination
- * useHotkey('ctrl+s', (e) => {
- *   e.preventDefault();
- *   saveDocument();
- * });
+ * // ⌘K palette — works everywhere, including inside text fields
+ * useHotkey('mod+k', openPalette);
  *
  * @example
- * // Multiple keys (any of them will trigger)
- * useHotkey(['ArrowLeft', '['], () => goToPrevious());
- * useHotkey(['ArrowRight', ']'], () => goToNext());
+ * // `/` focuses search — auto-disabled inside text fields so typing
+ * // a `/` into a textarea doesn't yank focus away
+ * useHotkey('/', focusSearch);
  *
  * @example
- * // With options
- * useHotkey('/', () => focusSearch(), {
- *   preventDefault: true,
- *   enableOnFormTags: false,
- *   description: 'Focus search input'
- * });
+ * // Escape — defaults to fire in text fields too (blur / close pattern)
+ * useHotkey('escape', closeModal);
  *
  * @example
- * // Scoped hotkeys
- * useHotkey('delete', () => deleteItem(), { scopes: ['list-view'] });
- *
- * @param keys - Hotkey or array of hotkeys (e.g., 'ctrl+s', 'ArrowLeft', ['[', 'ArrowLeft'])
- * @param callback - Function to call when hotkey is pressed
- * @param options - Configuration options
- * @returns Ref callback to attach to element for scoped hotkeys
+ * // Explicit opt-in for a bare key inside inputs
+ * useHotkey('?', openHelp, { inInput: true });
  */
 export function useHotkey<T extends HTMLElement = HTMLElement>(
   keys: Keys,
@@ -74,13 +86,35 @@ export function useHotkey<T extends HTMLElement = HTMLElement>(
 ): (instance: HotkeyRefType<T>) => void {
   const {
     enabled = true,
-    preventDefault = false,
-    enableOnFormTags = false,
-    enableOnContentEditable = false,
-    description: _description,
+    preventDefault: explicitPreventDefault,
+    inInput,
+    enableOnFormTags: explicitFormTags,
+    enableOnContentEditable: explicitContentEditable,
+    description,
+    scope,
     ...restOptions
   } = options;
 
+  const policyAllowsInInput = resolveInInput(keys, inInput);
+  // Smart default — modifier combos preventDefault by default
+  // (cmd+s, cmd+k, etc. would otherwise fall through to the browser).
+  const preventDefault = explicitPreventDefault ?? hasModifier(keys);
+
+  // Register in the cheat-sheet help registry when described.
+  useEffect(() => {
+    if (!description) return;
+    return registerHotkey({
+      combo: normalizeKeys(keys).join(','),
+      description,
+      scope,
+    });
+  }, [keys, description, scope]);
+
+  const enableOnFormTags =
+    explicitFormTags !== undefined ? explicitFormTags : policyAllowsInInput;
+  const enableOnContentEditable =
+    explicitContentEditable !== undefined ? explicitContentEditable : policyAllowsInInput;
+
   return useHotkeys<T>(
     keys,
     (event, handler) => {
@@ -98,6 +132,44 @@ export function useHotkey<T extends HTMLElement = HTMLElement>(
   );
 }
 
+/**
+ * Decide whether a given key combo should fire when focus is inside a
+ * text input. Honours the caller's explicit `inInput` first, otherwise
+ * applies the policy described on `UseHotkeyOptions.inInput`.
+ */
+function resolveInInput(keys: Keys, explicit?: boolean): boolean {
+  if (explicit !== undefined) return explicit;
+
+  const list = normalizeKeys(keys);
+  // If ANY of the listed combos qualifies as "input-safe", treat the
+  // whole binding as input-safe — the caller declared them as
+  // alternatives, so the more permissive policy wins.
+  return list.some(isInputSafeByPolicy);
+}
+
+function normalizeKeys(keys: Keys): string[] {
+  if (Array.isArray(keys)) return keys.map((k) => String(k).toLowerCase());
+  return [String(keys).toLowerCase()];
+}
+
+const ESCAPE_ALIASES = new Set(['escape', 'esc']);
+const MODIFIER_ALIASES = ['mod+', 'meta+', 'cmd+', 'ctrl+', 'control+', 'alt+', 'option+', 'shift+'];
+
+function isInputSafeByPolicy(combo: string): boolean {
+  if (ESCAPE_ALIASES.has(combo)) return true;
+  return MODIFIER_ALIASES.some((mod) => combo.startsWith(mod));
+}
+
+/**
+ * Does the combo include a modifier key? Used to default `preventDefault`
+ * so global app shortcuts (⌘S, ⌘K, …) never fall through to the browser.
+ */
+function hasModifier(keys: Keys): boolean {
+  return normalizeKeys(keys).some((combo) =>
+    MODIFIER_ALIASES.some((mod) => combo.startsWith(mod)),
+  );
+}
+
 // Re-export useful utilities from react-hotkeys-hook
 export { useHotkeysContext, HotkeysProvider, isHotkeyPressed } from 'react-hotkeys-hook';
 

package/src/hooks/hotkey/useHotkeyChord.ts

@@ -0,0 +1,96 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+export interface UseHotkeyChordOptions {
+  /** Whether the chord is active. @default true */
+  enabled?: boolean;
+  /** Max delay between consecutive keys, in ms. @default 800 */
+  window?: number;
+  /**
+   * Fire even when focus is inside an input / textarea / contenteditable.
+   * @default false — chord sequences shouldn't hijack typing
+   */
+  enableOnFormTags?: boolean;
+  /** Prevent default browser behaviour on each key. @default false */
+  preventDefault?: boolean;
+}
+
+const FORM_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
+
+function isEditableTarget(el: EventTarget | null): boolean {
+  if (!(el instanceof HTMLElement)) return false;
+  if (FORM_TAGS.has(el.tagName)) return true;
+  if (el.isContentEditable) return true;
+  return false;
+}
+
+/**
+ * Linear-style chord shortcuts — fire `callback` when the user presses
+ * a sequence of bare keys within a time window.
+ *
+ * @example
+ * ```tsx
+ * useHotkeyChord(['g', 't'], () => navigate('/tasks'));
+ * useHotkeyChord(['g', 'i'], () => navigate('/inbox'), { window: 1200 });
+ * ```
+ *
+ * Each step is a single bare key (no modifiers). Pressing any
+ * non-sequence key resets progress, so partially-typed sequences don't
+ * fire accidentally.
+ */
+export function useHotkeyChord(
+  keys: readonly string[],
+  callback: (event: KeyboardEvent) => void,
+  options: UseHotkeyChordOptions = {},
+): void {
+  const { enabled = true, window: chordWindow = 800, enableOnFormTags = false, preventDefault = false } = options;
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!enabled) return;
+    if (typeof window === 'undefined') return;
+    if (!keys.length) return;
+
+    const sequence = keys.map((k) => k.toLowerCase());
+    let progress = 0;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const reset = () => {
+      progress = 0;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    };
+
+    const onKey = (e: KeyboardEvent) => {
+      if (!enableOnFormTags && isEditableTarget(e.target)) return;
+      // Chords don't carry modifiers.
+      if (e.metaKey || e.ctrlKey || e.altKey) return reset();
+
+      const expected = sequence[progress];
+      if (!expected) return;
+      const pressed = e.key.toLowerCase();
+      if (pressed !== expected) return reset();
+
+      if (preventDefault) e.preventDefault();
+      progress++;
+      if (progress >= sequence.length) {
+        callbackRef.current(e);
+        reset();
+        return;
+      }
+
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(reset, chordWindow);
+    };
+
+    window.addEventListener('keydown', onKey);
+    return () => {
+      window.removeEventListener('keydown', onKey);
+      if (timer) clearTimeout(timer);
+    };
+  }, [keys.join('|'), enabled, chordWindow, enableOnFormTags, preventDefault]);
+}

package/src/hooks/hotkey/useHotkeyHelp.ts

@@ -0,0 +1,68 @@
+'use client';
+
+import { useEffect, useSyncExternalStore } from 'react';
+
+/**
+ * Module-level store of every hotkey that registered itself with a
+ * `description`. Lets you render a `?` cheat-sheet without prop-drilling.
+ */
+export interface RegisteredHotkey {
+  /** Key combo (raw string passed to `useHotkey` — format with `formatHotkey()` for display). */
+  combo: string;
+  /** Human-readable purpose. */
+  description: string;
+  /** Optional scope label for grouping (e.g. `'chat'`, `'global'`). */
+  scope?: string;
+}
+
+const registry = new Map<symbol, RegisteredHotkey>();
+const listeners = new Set<() => void>();
+
+function notify() {
+  for (const cb of listeners) cb();
+}
+
+/**
+ * Register a hotkey entry while a component is mounted. Internal —
+ * called by `useHotkey` when a `description` is provided.
+ */
+export function registerHotkey(entry: RegisteredHotkey): () => void {
+  const key = Symbol(entry.combo);
+  registry.set(key, entry);
+  notify();
+  return () => {
+    registry.delete(key);
+    notify();
+  };
+}
+
+/** Read the live list of registered hotkeys. SSR-safe. */
+export function useHotkeyHelp(): RegisteredHotkey[] {
+  return useSyncExternalStore(
+    (cb) => {
+      listeners.add(cb);
+      return () => {
+        listeners.delete(cb);
+      };
+    },
+    () => Array.from(registry.values()),
+    () => [],
+  );
+}
+
+/** Imperative read for non-React consumers (debug panels, etc.). */
+export function getRegisteredHotkeys(): RegisteredHotkey[] {
+  return Array.from(registry.values());
+}
+
+/**
+ * Hook variant — call alongside `useHotkey` when the binding lives
+ * outside the hook (e.g. raw `window.addEventListener` consumers that
+ * still want to appear in the cheat sheet).
+ */
+export function useRegisterHotkey(entry: RegisteredHotkey | null): void {
+  useEffect(() => {
+    if (!entry) return;
+    return registerHotkey(entry);
+  }, [entry?.combo, entry?.description, entry?.scope]);
+}

package/src/hooks/index.ts

@@ -19,6 +19,7 @@ export * from './theme';
 export * from './time';
 export * from './events';
 export * from './hotkey';
+export * from './audio';
 export * from './debug';
 
 // ----------------------------------------------------------------------------