@acvl/frontend-components 0.0.52 → 0.0.53

package/dist/cjs/types/src/components/v1/lib/hooks/index.d.ts

@@ -1,3 +1,4 @@
 export { useHasPermission } from './users';
 export { useAPI } from './api';
 export { useNavigation } from './navigation';
+export { useKeyboardShortcut, type KeyboardShortcut } from './useKeyboardShortcut';

package/dist/cjs/types/src/components/v1/lib/hooks/useKeyboardShortcut.d.ts

@@ -0,0 +1,42 @@
+export interface KeyboardShortcut {
+    /** Tecla objetivo. Se compara con `event.key` sin distinguir mayúsculas (p. ej. "f", "e", "Escape"). */
+    key: string;
+    /** Requiere Ctrl. Si se omite, la tecla Ctrl debe estar ausente. */
+    ctrl?: boolean;
+    /** Requiere Shift. Si se omite, la tecla Shift debe estar ausente. */
+    shift?: boolean;
+    /** Requiere Alt. Si se omite, la tecla Alt debe estar ausente. */
+    alt?: boolean;
+    /** Requiere Meta/Cmd. Si se omite, la tecla Meta debe estar ausente. */
+    meta?: boolean;
+    /**
+     * No dispara el atajo mientras el foco está en un campo editable
+     * (`input`, `textarea`, `select` o `contentEditable`). Evita que atajos de
+     * una sola letra (p. ej. `Shift+F`) se traguen la tecla al escribir.
+     * Por defecto `true`.
+     */
+    ignoreWhenTyping?: boolean;
+    /** Llama a `event.preventDefault()` al coincidir. Por defecto `true`. */
+    preventDefault?: boolean;
+    /** Permite desactivar el atajo sin desmontar el componente. Por defecto `true`. */
+    enabled?: boolean;
+}
+/**
+ * Registra un atajo de teclado global (listener en `document`) y ejecuta
+ * `handler` cuando la combinación coincide.
+ *
+ * - Compara la tecla sin distinguir mayúsculas y exige el estado exacto de los
+ *   modificadores, de modo que `Ctrl+E` y `Ctrl+Shift+E` no colisionan entre sí.
+ * - Por defecto ignora el atajo mientras se escribe en un campo editable.
+ * - `handler` se lee siempre en su versión más reciente, así que no hace falta
+ *   memoizarlo con `useCallback` en el componente que lo usa.
+ *
+ * Llama al hook varias veces para registrar varios atajos en un mismo componente.
+ *
+ * @example
+ * useKeyboardShortcut({ key: "f", shift: true }, () => setFullScreen((p) => !p));
+ * useKeyboardShortcut({ key: "e", ctrl: true }, () => navigate("editar"));
+ * useKeyboardShortcut({ key: "Escape", shift: true, enabled: edit }, cancelEdit);
+ */
+export declare function useKeyboardShortcut(shortcut: KeyboardShortcut, handler: (event: KeyboardEvent) => void): void;
+export default useKeyboardShortcut;