@allternit/gizzi-code 1.0.0

package/src/hooks/useExitOnCtrlCD.js

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Exit handler hook for gizzi-code integration
+ * @module hooks/useExitOnCtrlCD
+ *
+ * Provides a React hook for handling exit key combinations (Ctrl+C and Ctrl+D).
+ * Commonly used for CLI applications to handle graceful shutdown or exit actions.
+ */
+import { useCallback } from 'react';
+import { useKeybinding } from './useKeybinding';
+/**
+ * Default confirmation message
+ * @constant {string}
+ */
+const DEFAULT_CONFIRM_MESSAGE = 'Are you sure you want to exit? (y/N): ';
+/**
+ * Default exit message
+ * @constant {string}
+ */
+const DEFAULT_EXIT_MESSAGE = 'Goodbye!';
+/**
+ * React hook for handling Ctrl+C and Ctrl+D exit combinations
+ *
+ * Registers keyboard shortcuts for common terminal exit commands and
+ * executes the provided callback when triggered. Supports optional
+ * confirmation before exit.
+ *
+ * @param {ExitHandler | UseExitOnCtrlCDOptions} handler - Exit callback or options object
+ * @example
+ * ```typescript
+ * // Simple usage with callback
+ * useExitOnCtrlCD(() => {
+ *   console.log('Exiting...');
+ *   process.exit(0);
+ * });
+ *
+ * // With options
+ * useExitOnCtrlCD({
+ *   onExit: () => saveAndQuit(),
+ *   enableCtrlC: true,
+ *   enableCtrlD: false,
+ *   exitMessage: '👋 See you later!',
+ *   confirmBeforeExit: true,
+ * });
+ * ```
+ */
+export function useExitOnCtrlCD(handler) {
+    // Normalize input to options object
+    const options = typeof handler === 'function' ? { onExit: handler } : handler;
+    const { onExit, enableCtrlC = true, enableCtrlD = true, enabled = true, exitMessage = DEFAULT_EXIT_MESSAGE, confirmBeforeExit = false, confirmMessage = DEFAULT_CONFIRM_MESSAGE, } = options;
+    const handleExit = useCallback(async (event) => {
+        // Handle confirmation if enabled
+        if (confirmBeforeExit) {
+            // Note: In a real CLI environment, you might use readline here
+            // For browser/React environments, this is a simplified version
+            const confirmed = typeof window !== 'undefined'
+                ? window.confirm(confirmMessage)
+                : true;
+            if (!confirmed) {
+                return;
+            }
+        }
+        // Show exit message
+        if (exitMessage && typeof console !== 'undefined') {
+            console.log(exitMessage);
+        }
+        // Execute exit handler
+        if (onExit) {
+            try {
+                const result = await onExit();
+                // Return false from handler to prevent default exit behavior
+                if (result === false && event) {
+                    event.preventDefault();
+                }
+            }
+            catch (error) {
+                console.error('Error during exit:', error);
+            }
+        }
+    }, [onExit, confirmBeforeExit, confirmMessage, exitMessage]);
+    // Wrap handler to match KeyHandler signature
+    const keyHandler = useCallback((event) => {
+        handleExit(event);
+    }, [handleExit]);
+    // Register Ctrl+C handler (SIGINT equivalent)
+    useKeybinding({ key: 'c', ctrl: true, preventDefault: true }, keyHandler, enabled && enableCtrlC);
+    // Register Ctrl+D handler (EOF/exit equivalent)
+    useKeybinding({ key: 'd', ctrl: true, preventDefault: true }, keyHandler, enabled && enableCtrlD);
+}
+/**
+ * Convenience hook for just Ctrl+C handling
+ *
+ * @param {ExitHandler} handler - Exit callback
+ * @param {boolean} [enabled=true] - Whether the handler is active
+ * @example
+ * ```typescript
+ * useExitOnCtrlC(() => {
+ *   console.log('Interrupted');
+ * });
+ * ```
+ */
+export function useExitOnCtrlC(handler, enabled = true) {
+    useExitOnCtrlCD({
+        onExit: handler,
+        enableCtrlC: true,
+        enableCtrlD: false,
+        enabled,
+    });
+}
+/**
+ * Convenience hook for just Ctrl+D handling
+ *
+ * @param {ExitHandler} handler - Exit callback
+ * @param {boolean} [enabled=true] - Whether the handler is active
+ * @example
+ * ```typescript
+ * useExitOnCtrlD(() => {
+ *   console.log('EOF received');
+ * });
+ * ```
+ */
+export function useExitOnCtrlD(handler, enabled = true) {
+    useExitOnCtrlCD({
+        onExit: handler,
+        enableCtrlC: false,
+        enableCtrlD: true,
+        enabled,
+    });
+}
+// Default export
+export default useExitOnCtrlCD;

package/src/hooks/useExitOnCtrlCD.ts

@@ -0,0 +1,202 @@
+/**
+ * @fileoverview Exit handler hook for gizzi-code integration
+ * @module hooks/useExitOnCtrlCD
+ *
+ * Provides a React hook for handling exit key combinations (Ctrl+C and Ctrl+D).
+ * Commonly used for CLI applications to handle graceful shutdown or exit actions.
+ */
+
+import { useCallback } from 'react';
+import { useKeybinding, type KeyHandler } from './useKeybinding';
+
+/**
+ * Exit handler callback type
+ * @typedef {Function} ExitHandler
+ */
+export type ExitHandler = () => void | boolean | Promise<void | boolean>;
+
+/**
+ * Options for the exit handler hook
+ * @interface UseExitOnCtrlCDOptions
+ */
+export interface UseExitOnCtrlCDOptions {
+  /** Callback function to execute when exit keys are pressed */
+  readonly onExit?: ExitHandler;
+  /** Whether Ctrl+C triggers exit (default: true) */
+  readonly enableCtrlC?: boolean;
+  /** Whether Ctrl+D triggers exit (default: true) */
+  readonly enableCtrlD?: boolean;
+  /** Whether the exit handler is active (default: true) */
+  readonly enabled?: boolean;
+  /** Custom message to display on exit (optional) */
+  readonly exitMessage?: string;
+  /** Whether to confirm before exit (default: false) */
+  readonly confirmBeforeExit?: boolean;
+  /** Custom confirmation message */
+  readonly confirmMessage?: string;
+}
+
+/**
+ * Default confirmation message
+ * @constant {string}
+ */
+const DEFAULT_CONFIRM_MESSAGE = 'Are you sure you want to exit? (y/N): ';
+
+/**
+ * Default exit message
+ * @constant {string}
+ */
+const DEFAULT_EXIT_MESSAGE = 'Goodbye!';
+
+/**
+ * React hook for handling Ctrl+C and Ctrl+D exit combinations
+ *
+ * Registers keyboard shortcuts for common terminal exit commands and
+ * executes the provided callback when triggered. Supports optional
+ * confirmation before exit.
+ *
+ * @param {ExitHandler | UseExitOnCtrlCDOptions} handler - Exit callback or options object
+ * @example
+ * ```typescript
+ * // Simple usage with callback
+ * useExitOnCtrlCD(() => {
+ *   console.log('Exiting...');
+ *   process.exit(0);
+ * });
+ *
+ * // With options
+ * useExitOnCtrlCD({
+ *   onExit: () => saveAndQuit(),
+ *   enableCtrlC: true,
+ *   enableCtrlD: false,
+ *   exitMessage: '👋 See you later!',
+ *   confirmBeforeExit: true,
+ * });
+ * ```
+ */
+export function useExitOnCtrlCD(
+  handler: ExitHandler | UseExitOnCtrlCDOptions
+): void {
+  // Normalize input to options object
+  const options: UseExitOnCtrlCDOptions =
+    typeof handler === 'function' ? { onExit: handler } : handler;
+
+  const {
+    onExit,
+    enableCtrlC = true,
+    enableCtrlD = true,
+    enabled = true,
+    exitMessage = DEFAULT_EXIT_MESSAGE,
+    confirmBeforeExit = false,
+    confirmMessage = DEFAULT_CONFIRM_MESSAGE,
+  } = options;
+
+  const handleExit = useCallback(
+    async (event?: KeyboardEvent): Promise<void> => {
+      // Handle confirmation if enabled
+      if (confirmBeforeExit) {
+        // Note: In a real CLI environment, you might use readline here
+        // For browser/React environments, this is a simplified version
+        const confirmed = typeof window !== 'undefined' 
+          ? window.confirm(confirmMessage)
+          : true;
+          
+        if (!confirmed) {
+          return;
+        }
+      }
+
+      // Show exit message
+      if (exitMessage && typeof console !== 'undefined') {
+        console.log(exitMessage);
+      }
+
+      // Execute exit handler
+      if (onExit) {
+        try {
+          const result = await onExit();
+          // Return false from handler to prevent default exit behavior
+          if (result === false && event) {
+            event.preventDefault();
+          }
+        } catch (error) {
+          console.error('Error during exit:', error);
+        }
+      }
+    },
+    [onExit, confirmBeforeExit, confirmMessage, exitMessage]
+  );
+
+  // Wrap handler to match KeyHandler signature
+  const keyHandler: KeyHandler = useCallback(
+    (event: KeyboardEvent) => {
+      handleExit(event);
+    },
+    [handleExit]
+  );
+
+  // Register Ctrl+C handler (SIGINT equivalent)
+  useKeybinding(
+    { key: 'c', ctrl: true, preventDefault: true },
+    keyHandler,
+    enabled && enableCtrlC
+  );
+
+  // Register Ctrl+D handler (EOF/exit equivalent)
+  useKeybinding(
+    { key: 'd', ctrl: true, preventDefault: true },
+    keyHandler,
+    enabled && enableCtrlD
+  );
+}
+
+/**
+ * Convenience hook for just Ctrl+C handling
+ *
+ * @param {ExitHandler} handler - Exit callback
+ * @param {boolean} [enabled=true] - Whether the handler is active
+ * @example
+ * ```typescript
+ * useExitOnCtrlC(() => {
+ *   console.log('Interrupted');
+ * });
+ * ```
+ */
+export function useExitOnCtrlC(
+  handler: ExitHandler,
+  enabled: boolean = true
+): void {
+  useExitOnCtrlCD({
+    onExit: handler,
+    enableCtrlC: true,
+    enableCtrlD: false,
+    enabled,
+  });
+}
+
+/**
+ * Convenience hook for just Ctrl+D handling
+ *
+ * @param {ExitHandler} handler - Exit callback
+ * @param {boolean} [enabled=true] - Whether the handler is active
+ * @example
+ * ```typescript
+ * useExitOnCtrlD(() => {
+ *   console.log('EOF received');
+ * });
+ * ```
+ */
+export function useExitOnCtrlD(
+  handler: ExitHandler,
+  enabled: boolean = true
+): void {
+  useExitOnCtrlCD({
+    onExit: handler,
+    enableCtrlC: false,
+    enableCtrlD: true,
+    enabled,
+  });
+}
+
+// Default export
+export default useExitOnCtrlCD;

package/src/hooks/useKeybinding.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Keybinding hook for gizzi-code integration
+ * @module hooks/useKeybinding
+ *
+ * Provides a React hook for registering keyboard shortcuts and key combinations.
+ * Supports modifier keys (Ctrl, Alt, Shift, Meta) and automatic cleanup on unmount.
+ */
+/**
+ * Key combination configuration
+ * @interface KeybindingConfig
+ */
+export interface KeybindingConfig {
+    /** The main key (e.g., 'c', 'Enter', 'Escape') */
+    readonly key: string;
+    /** Require Ctrl key to be pressed */
+    readonly ctrl?: boolean;
+    /** Require Alt/Option key to be pressed */
+    readonly alt?: boolean;
+    /** Require Shift key to be pressed */
+    readonly shift?: boolean;
+    /** Require Meta/Command key to be pressed */
+    readonly meta?: boolean;
+    /** Prevent default browser behavior */
+    readonly preventDefault?: boolean;
+    /** Stop event propagation */
+    readonly stopPropagation?: boolean;
+}
+/**
+ * Parses a keybinding string into a config object
+ *
+ * @param {string} keybinding - Keybinding string (e.g., "Ctrl+C", "Escape", "Ctrl+Shift+A")
+ * @returns {KeybindingConfig} Parsed keybinding configuration
+ * @example
+ * ```typescript
+ * parseKeybinding("Ctrl+C"); // { key: 'c', ctrl: true }
+ * parseKeybinding("Escape"); // { key: 'escape' }
+ * parseKeybinding("Ctrl+Shift+A"); // { key: 'a', ctrl: true, shift: true }
+ * ```
+ */
+export declare function parseKeybinding(keybinding: string): KeybindingConfig;
+/**
+ * Key event handler type
+ * @typedef {Function} KeyHandler
+ */
+export type KeyHandler = (event: KeyboardEvent) => void | boolean;
+/**
+ * React hook for registering keyboard shortcuts
+ *
+ * Registers a keyboard shortcut that triggers the provided handler when pressed.
+ * Automatically cleans up the event listener when the component unmounts or
+ * when the keybinding changes.
+ *
+ * @param {string | KeybindingConfig} key - Key combination (e.g., "Ctrl+C") or config object
+ * @param {KeyHandler} handler - Function to call when keybinding is triggered
+ * @param {boolean} [enabled=true] - Whether the keybinding is active
+ * @example
+ * ```typescript
+ * // Using string keybinding
+ * useKeybinding('Ctrl+C', () => {
+ *   console.log('Copy!');
+ * });
+ *
+ * // Using config object
+ * useKeybinding({ key: 'k', ctrl: true }, (e) => {
+ *   e.preventDefault();
+ *   console.log('Ctrl+K pressed');
+ * });
+ *
+ * // With conditional enabling
+ * useKeybinding('Escape', handleClose, isModalOpen);
+ * ```
+ */
+export declare function useKeybinding(key: string | KeybindingConfig, handler: KeyHandler, enabled?: boolean): void;
+/**
+ * Hook for registering multiple keybindings at once
+ *
+ * @param {Array<[string | KeybindingConfig, KeyHandler]>} bindings - Array of [keybinding, handler] tuples
+ * @param {boolean} [enabled=true] - Whether all keybindings are active
+ * @example
+ * ```typescript
+ * useKeybindings([
+ *   ['Ctrl+C', handleCopy],
+ *   ['Ctrl+V', handlePaste],
+ *   ['Escape', handleClose],
+ * ]);
+ * ```
+ */
+export declare function useKeybindings(bindings: Array<[string | KeybindingConfig, KeyHandler]>, enabled?: boolean): void;
+export default useKeybinding;

package/src/hooks/useKeybinding.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Keybinding hook for gizzi-code integration
+ * @module hooks/useKeybinding
+ *
+ * Provides a React hook for registering keyboard shortcuts and key combinations.
+ * Supports modifier keys (Ctrl, Alt, Shift, Meta) and automatic cleanup on unmount.
+ */
+import { useEffect, useCallback, useRef } from 'react';
+/**
+ * Normalized key combination string for comparison
+ * @param {KeybindingConfig} config - Keybinding configuration
+ * @returns {string} Normalized key combination string
+ */
+function normalizeKeyCombo(config) {
+    const parts = [];
+    if (config.ctrl)
+        parts.push('ctrl');
+    if (config.alt)
+        parts.push('alt');
+    if (config.shift)
+        parts.push('shift');
+    if (config.meta)
+        parts.push('meta');
+    parts.push(config.key.toLowerCase());
+    return parts.join('+');
+}
+/**
+ * Parses a keybinding string into a config object
+ *
+ * @param {string} keybinding - Keybinding string (e.g., "Ctrl+C", "Escape", "Ctrl+Shift+A")
+ * @returns {KeybindingConfig} Parsed keybinding configuration
+ * @example
+ * ```typescript
+ * parseKeybinding("Ctrl+C"); // { key: 'c', ctrl: true }
+ * parseKeybinding("Escape"); // { key: 'escape' }
+ * parseKeybinding("Ctrl+Shift+A"); // { key: 'a', ctrl: true, shift: true }
+ * ```
+ */
+export function parseKeybinding(keybinding) {
+    const parts = keybinding.split('+').map((p) => p.trim().toLowerCase());
+    const config = {
+        key: '',
+        ctrl: false,
+        alt: false,
+        shift: false,
+        meta: false,
+    };
+    for (const part of parts) {
+        switch (part) {
+            case 'ctrl':
+            case 'control':
+                config.ctrl = true;
+                break;
+            case 'alt':
+            case 'option':
+                config.alt = true;
+                break;
+            case 'shift':
+                config.shift = true;
+                break;
+            case 'meta':
+            case 'cmd':
+            case 'command':
+            case 'win':
+            case 'windows':
+                config.meta = true;
+                break;
+            default:
+                config.key = part;
+                break;
+        }
+    }
+    return config;
+}
+/**
+ * React hook for registering keyboard shortcuts
+ *
+ * Registers a keyboard shortcut that triggers the provided handler when pressed.
+ * Automatically cleans up the event listener when the component unmounts or
+ * when the keybinding changes.
+ *
+ * @param {string | KeybindingConfig} key - Key combination (e.g., "Ctrl+C") or config object
+ * @param {KeyHandler} handler - Function to call when keybinding is triggered
+ * @param {boolean} [enabled=true] - Whether the keybinding is active
+ * @example
+ * ```typescript
+ * // Using string keybinding
+ * useKeybinding('Ctrl+C', () => {
+ *   console.log('Copy!');
+ * });
+ *
+ * // Using config object
+ * useKeybinding({ key: 'k', ctrl: true }, (e) => {
+ *   e.preventDefault();
+ *   console.log('Ctrl+K pressed');
+ * });
+ *
+ * // With conditional enabling
+ * useKeybinding('Escape', handleClose, isModalOpen);
+ * ```
+ */
+export function useKeybinding(key, handler, enabled = true) {
+    const config = typeof key === 'string' ? parseKeybinding(key) : key;
+    const expectedCombo = normalizeKeyCombo(config);
+    const handlerRef = useRef(handler);
+    // Keep handler reference up to date without re-registering
+    useEffect(() => {
+        handlerRef.current = handler;
+    }, [handler]);
+    const handleKeyDown = useCallback((event) => {
+        // Check if this key event matches our expected combination
+        const actualCombo = normalizeKeyCombo({
+            key: event.key,
+            ctrl: event.ctrlKey,
+            alt: event.altKey,
+            shift: event.shiftKey,
+            meta: event.metaKey,
+        });
+        if (actualCombo === expectedCombo) {
+            if (config.preventDefault) {
+                event.preventDefault();
+            }
+            if (config.stopPropagation) {
+                event.stopPropagation();
+            }
+            const result = handlerRef.current(event);
+            // Allow handler to prevent default by returning false
+            if (result === false) {
+                event.preventDefault();
+            }
+        }
+    }, [config, expectedCombo]);
+    useEffect(() => {
+        if (!enabled || typeof window === 'undefined') {
+            return;
+        }
+        window.addEventListener('keydown', handleKeyDown);
+        return () => {
+            window.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [enabled, handleKeyDown]);
+}
+/**
+ * Hook for registering multiple keybindings at once
+ *
+ * @param {Array<[string | KeybindingConfig, KeyHandler]>} bindings - Array of [keybinding, handler] tuples
+ * @param {boolean} [enabled=true] - Whether all keybindings are active
+ * @example
+ * ```typescript
+ * useKeybindings([
+ *   ['Ctrl+C', handleCopy],
+ *   ['Ctrl+V', handlePaste],
+ *   ['Escape', handleClose],
+ * ]);
+ * ```
+ */
+export function useKeybindings(bindings, enabled = true) {
+    bindings.forEach(([key, handler]) => {
+        useKeybinding(key, handler, enabled);
+    });
+}
+// Default export
+export default useKeybinding;