@imjp/writenex-astro 0.1.0

package/src/client/hooks/useAutosave.ts

@@ -0,0 +1,241 @@
+/**
+ * @fileoverview Autosave hook for automatic content saving
+ *
+ * This hook provides automatic saving functionality with debouncing
+ * to prevent excessive API calls while ensuring content is saved
+ * regularly.
+ *
+ * ## Features:
+ * - Debounced saving (default 3 seconds)
+ * - Save status indicator
+ * - Error handling with retry
+ * - Pause/resume capability
+ * - Save on unmount option
+ *
+ * @module @writenex/astro/client/hooks/useAutosave
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Autosave status
+ */
+export type AutosaveStatus = "idle" | "pending" | "saving" | "saved" | "error";
+
+/**
+ * Options for useAutosave hook
+ */
+export interface UseAutosaveOptions {
+  /** Debounce delay in milliseconds (default: 3000) */
+  delay?: number;
+  /** Whether autosave is enabled (default: true) */
+  enabled?: boolean;
+  /** Save function to call */
+  onSave: () => Promise<boolean>;
+  /** Callback when save succeeds */
+  onSuccess?: () => void;
+  /** Callback when save fails */
+  onError?: (error: Error) => void;
+  /** Whether to save on component unmount (default: true) */
+  saveOnUnmount?: boolean;
+}
+
+/**
+ * Return value from useAutosave hook
+ */
+export interface UseAutosaveReturn {
+  /** Current autosave status */
+  status: AutosaveStatus;
+  /** Trigger a change that will schedule autosave */
+  triggerChange: () => void;
+  /** Force immediate save */
+  saveNow: () => Promise<void>;
+  /** Cancel pending autosave */
+  cancel: () => void;
+  /** Whether there are pending changes */
+  hasPendingChanges: boolean;
+  /** Last saved timestamp */
+  lastSaved: Date | null;
+}
+
+/**
+ * Hook for automatic content saving with debounce
+ *
+ * @param options - Autosave configuration options
+ * @returns Autosave controls and status
+ *
+ * @example
+ * ```tsx
+ * const { status, triggerChange, saveNow } = useAutosave({
+ *   delay: 3000,
+ *   enabled: true,
+ *   onSave: async () => {
+ *     const result = await api.save(content);
+ *     return result.success;
+ *   },
+ * });
+ *
+ * // Call triggerChange when content changes
+ * const handleChange = (newContent) => {
+ *   setContent(newContent);
+ *   triggerChange();
+ * };
+ * ```
+ */
+export function useAutosave(options: UseAutosaveOptions): UseAutosaveReturn {
+  const {
+    delay = 3000,
+    enabled = true,
+    onSave,
+    onSuccess,
+    onError,
+    saveOnUnmount = true,
+  } = options;
+
+  const [status, setStatus] = useState<AutosaveStatus>("idle");
+  const [lastSaved, setLastSaved] = useState<Date | null>(null);
+  const [hasPendingChanges, setHasPendingChanges] = useState(false);
+
+  // Refs for cleanup and tracking
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const isMountedRef = useRef(true);
+  const isSavingRef = useRef(false);
+
+  /**
+   * Clear the pending timeout
+   */
+  const clearPendingTimeout = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  }, []);
+
+  /**
+   * Perform the actual save operation
+   */
+  const performSave = useCallback(async () => {
+    if (isSavingRef.current) return;
+
+    isSavingRef.current = true;
+    setStatus("saving");
+
+    try {
+      const success = await onSave();
+
+      if (!isMountedRef.current) return;
+
+      if (success) {
+        setStatus("saved");
+        setHasPendingChanges(false);
+        setLastSaved(new Date());
+        onSuccess?.();
+
+        // Reset to idle after showing "saved" briefly
+        setTimeout(() => {
+          if (isMountedRef.current) {
+            setStatus("idle");
+          }
+        }, 2000);
+      } else {
+        setStatus("error");
+        onError?.(new Error("Save failed"));
+      }
+    } catch (err) {
+      if (!isMountedRef.current) return;
+
+      setStatus("error");
+      onError?.(err instanceof Error ? err : new Error("Save failed"));
+    } finally {
+      isSavingRef.current = false;
+    }
+  }, [onSave, onSuccess, onError]);
+
+  /**
+   * Schedule a save after the debounce delay
+   */
+  const scheduleSave = useCallback(() => {
+    clearPendingTimeout();
+
+    if (!enabled) return;
+
+    setStatus("pending");
+    setHasPendingChanges(true);
+
+    timeoutRef.current = setTimeout(() => {
+      performSave();
+    }, delay);
+  }, [enabled, delay, clearPendingTimeout, performSave]);
+
+  /**
+   * Trigger a change that will schedule autosave
+   */
+  const triggerChange = useCallback(() => {
+    if (!enabled) return;
+    scheduleSave();
+  }, [enabled, scheduleSave]);
+
+  /**
+   * Force immediate save
+   */
+  const saveNow = useCallback(async () => {
+    clearPendingTimeout();
+    await performSave();
+  }, [clearPendingTimeout, performSave]);
+
+  /**
+   * Cancel pending autosave
+   */
+  const cancel = useCallback(() => {
+    clearPendingTimeout();
+    setStatus("idle");
+  }, [clearPendingTimeout]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    isMountedRef.current = true;
+
+    return () => {
+      isMountedRef.current = false;
+      clearPendingTimeout();
+
+      // Save on unmount if enabled and there are pending changes
+      if (saveOnUnmount && hasPendingChanges && !isSavingRef.current) {
+        // Fire and forget - component is unmounting
+        onSave().catch(() => {
+          // Ignore errors on unmount
+        });
+      }
+    };
+  }, [clearPendingTimeout, saveOnUnmount, hasPendingChanges, onSave]);
+
+  return {
+    status,
+    triggerChange,
+    saveNow,
+    cancel,
+    hasPendingChanges,
+    lastSaved,
+  };
+}
+
+/**
+ * Format last saved time for display
+ *
+ * @param date - Last saved date
+ * @returns Formatted string like "Saved just now" or "Saved 2 min ago"
+ */
+export function formatLastSaved(date: Date | null): string {
+  if (!date) return "";
+
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+
+  if (diffSec < 10) return "Saved just now";
+  if (diffSec < 60) return `Saved ${diffSec}s ago`;
+  if (diffMin < 60) return `Saved ${diffMin}m ago`;
+
+  return `Saved at ${date.toLocaleTimeString()}`;
+}

package/src/client/hooks/useFocusTrap.ts

@@ -0,0 +1,178 @@
+/**
+ * @fileoverview Focus trap hook for modal accessibility
+ *
+ * This hook provides focus containment within a container element,
+ * ensuring keyboard users cannot tab outside of modal dialogs.
+ * It handles Tab/Shift+Tab cycling at boundaries and supports
+ * focus restoration when the trap is deactivated.
+ *
+ * ## Features:
+ * - Focus containment within container
+ * - Tab and Shift+Tab cycling at boundaries
+ * - Escape key callback support
+ * - Automatic focus on first focusable element
+ * - Focus restoration to trigger element on close
+ *
+ * @module @writenex/astro/client/hooks/useFocusTrap
+ * @see {@link UseFocusTrapOptions} - Configuration options
+ */
+
+import { useCallback, useEffect, useRef } from "react";
+import {
+  getFocusableElements,
+  getFirstFocusable,
+  getLastFocusable,
+} from "../utils/focus";
+
+/**
+ * Options for useFocusTrap hook
+ */
+export interface UseFocusTrapOptions {
+  /** Whether the trap is active */
+  enabled: boolean;
+  /** Callback when escape is pressed */
+  onEscape?: () => void;
+  /** Element to restore focus to on close */
+  returnFocusTo?: HTMLElement | null;
+}
+
+/**
+ * Return value from useFocusTrap hook
+ */
+export interface UseFocusTrapReturn {
+  /** Ref to attach to the container element */
+  containerRef: React.RefObject<HTMLDivElement | null>;
+}
+
+/**
+ * Hook for trapping focus within a container element
+ *
+ * This hook is essential for modal accessibility, ensuring that keyboard
+ * users cannot accidentally tab outside of a modal dialog. It automatically
+ * moves focus to the first focusable element when enabled and restores
+ * focus to the trigger element when disabled.
+ *
+ * @param options - Focus trap configuration options
+ * @returns Object containing the container ref to attach to the trap element
+ *
+ * @example
+ * ```tsx
+ * function Modal({ isOpen, onClose }) {
+ *   const triggerRef = useRef<HTMLButtonElement>(null);
+ *   const { containerRef } = useFocusTrap({
+ *     enabled: isOpen,
+ *     onEscape: onClose,
+ *     returnFocusTo: triggerRef.current,
+ *   });
+ *
+ *   return (
+ *     <div ref={containerRef} role="dialog" aria-modal="true">
+ *       <button onClick={onClose}>Close</button>
+ *       <input type="text" />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useFocusTrap(options: UseFocusTrapOptions): UseFocusTrapReturn {
+  const { enabled, onEscape, returnFocusTo } = options;
+
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const previousActiveElementRef = useRef<HTMLElement | null>(null);
+
+  /**
+   * Handle keydown events for focus trapping
+   */
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (!enabled || !containerRef.current) return;
+
+      // Handle Escape key
+      if (event.key === "Escape" && onEscape) {
+        event.preventDefault();
+        onEscape();
+        return;
+      }
+
+      // Handle Tab key for focus cycling
+      if (event.key === "Tab") {
+        const focusableElements = getFocusableElements(containerRef.current);
+
+        if (focusableElements.length === 0) {
+          // No focusable elements, prevent tab from leaving
+          event.preventDefault();
+          return;
+        }
+
+        const firstFocusable = getFirstFocusable(containerRef.current);
+        const lastFocusable = getLastFocusable(containerRef.current);
+        const activeElement = document.activeElement as HTMLElement;
+
+        if (event.shiftKey) {
+          // Shift+Tab: cycle from first to last
+          if (activeElement === firstFocusable) {
+            event.preventDefault();
+            lastFocusable?.focus();
+          }
+        } else {
+          // Tab: cycle from last to first
+          if (activeElement === lastFocusable) {
+            event.preventDefault();
+            firstFocusable?.focus();
+          }
+        }
+      }
+    },
+    [enabled, onEscape]
+  );
+
+  // Set up focus trap when enabled
+  useEffect(() => {
+    if (!enabled) return;
+
+    // Store the currently focused element for restoration
+    previousActiveElementRef.current =
+      returnFocusTo || (document.activeElement as HTMLElement);
+
+    // Move focus to first focusable element in container
+    const container = containerRef.current;
+    if (container) {
+      // Use requestAnimationFrame to ensure DOM is ready
+      requestAnimationFrame(() => {
+        const firstFocusable = getFirstFocusable(container);
+        if (firstFocusable) {
+          firstFocusable.focus();
+        } else {
+          // If no focusable elements, focus the container itself
+          container.setAttribute("tabindex", "-1");
+          container.focus();
+        }
+      });
+    }
+
+    // Add keydown listener
+    document.addEventListener("keydown", handleKeyDown);
+
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [enabled, handleKeyDown, returnFocusTo]);
+
+  // Restore focus when trap is disabled
+  useEffect(() => {
+    if (enabled) return;
+
+    // Restore focus to the previous element
+    const elementToFocus = returnFocusTo || previousActiveElementRef.current;
+    if (elementToFocus && typeof elementToFocus.focus === "function") {
+      // Use requestAnimationFrame to ensure the modal is fully closed
+      requestAnimationFrame(() => {
+        elementToFocus.focus();
+      });
+    }
+  }, [enabled, returnFocusTo]);
+
+  return {
+    containerRef,
+  };
+}

package/src/client/hooks/useKeyboardShortcuts.ts

@@ -0,0 +1,203 @@
+/**
+ * @fileoverview Keyboard shortcuts hook for Writenex editor
+ *
+ * This hook provides centralized keyboard shortcut handling with
+ * support for common editor operations.
+ *
+ * ## Shortcuts:
+ * - Alt + N: New content
+ * - Ctrl/Cmd + S: Save
+ * - Ctrl/Cmd + P: Preview
+ * - Ctrl/Cmd + /: Toggle shortcuts help
+ * - Escape: Close modals/panels
+ *
+ * @module @writenex/astro/client/hooks/useKeyboardShortcuts
+ */
+
+import { useCallback, useEffect, useState } from "react";
+
+/**
+ * Shortcut definition
+ */
+export interface ShortcutDefinition {
+  /** Unique key for the shortcut */
+  key: string;
+  /** Display label */
+  label: string;
+  /** Keyboard key to press */
+  keys: string;
+  /** Whether Ctrl/Cmd is required */
+  ctrl?: boolean;
+  /** Whether Shift is required */
+  shift?: boolean;
+  /** Whether Alt is required */
+  alt?: boolean;
+  /** Handler function */
+  handler: () => void;
+  /** Whether the shortcut is enabled */
+  enabled?: boolean;
+}
+
+/**
+ * Options for useKeyboardShortcuts hook
+ */
+export interface UseKeyboardShortcutsOptions {
+  /** Shortcuts to register */
+  shortcuts: ShortcutDefinition[];
+  /** Whether shortcuts are globally enabled */
+  enabled?: boolean;
+}
+
+/**
+ * Return value from useKeyboardShortcuts hook
+ */
+export interface UseKeyboardShortcutsReturn {
+  /** Whether shortcuts help modal is open */
+  showHelp: boolean;
+  /** Toggle shortcuts help modal */
+  toggleHelp: () => void;
+  /** Close shortcuts help modal */
+  closeHelp: () => void;
+  /** List of registered shortcuts for display */
+  shortcuts: ShortcutDefinition[];
+}
+
+/**
+ * Check if event target is an input element
+ */
+function isInputElement(target: EventTarget | null): boolean {
+  if (!target || !(target instanceof HTMLElement)) return false;
+
+  const tagName = target.tagName.toLowerCase();
+  if (tagName === "input" || tagName === "textarea" || tagName === "select") {
+    return true;
+  }
+
+  // Check for contenteditable
+  if (target.isContentEditable) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Format shortcut keys for display
+ */
+export function formatShortcut(shortcut: ShortcutDefinition): string {
+  const parts: string[] = [];
+
+  // Use Cmd on Mac, Ctrl on others
+  const isMac =
+    typeof navigator !== "undefined" &&
+    /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+
+  if (shortcut.ctrl) {
+    parts.push(isMac ? "⌘" : "Ctrl");
+  }
+  if (shortcut.shift) {
+    parts.push(isMac ? "⇧" : "Shift");
+  }
+  if (shortcut.alt) {
+    parts.push(isMac ? "⌥" : "Alt");
+  }
+
+  // Format the key
+  let keyDisplay = shortcut.keys.toUpperCase();
+  if (keyDisplay === "ESCAPE") keyDisplay = "Esc";
+  if (keyDisplay === "ARROWUP") keyDisplay = "↑";
+  if (keyDisplay === "ARROWDOWN") keyDisplay = "↓";
+  if (keyDisplay === "ARROWLEFT") keyDisplay = "←";
+  if (keyDisplay === "ARROWRIGHT") keyDisplay = "→";
+
+  parts.push(keyDisplay);
+
+  return parts.join(isMac ? "" : "+");
+}
+
+/**
+ * Hook for managing keyboard shortcuts
+ *
+ * @param options - Shortcut configuration
+ * @returns Shortcut controls and help modal state
+ *
+ * @example
+ * ```tsx
+ * const { showHelp, toggleHelp, shortcuts } = useKeyboardShortcuts({
+ *   shortcuts: [
+ *     { key: 'save', label: 'Save', keys: 's', ctrl: true, handler: handleSave },
+ *     { key: 'new', label: 'New', keys: 'n', alt: true, handler: handleNew },
+ *   ],
+ * });
+ * ```
+ */
+export function useKeyboardShortcuts(
+  options: UseKeyboardShortcutsOptions
+): UseKeyboardShortcutsReturn {
+  const { shortcuts, enabled = true } = options;
+  const [showHelp, setShowHelp] = useState(false);
+
+  const toggleHelp = useCallback(() => {
+    setShowHelp((prev) => !prev);
+  }, []);
+
+  const closeHelp = useCallback(() => {
+    setShowHelp(false);
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      // Check for help shortcut first (Ctrl + /)
+      if ((e.ctrlKey || e.metaKey) && e.key === "/") {
+        e.preventDefault();
+        toggleHelp();
+        return;
+      }
+
+      // Close help on Escape
+      if (e.key === "Escape" && showHelp) {
+        e.preventDefault();
+        closeHelp();
+        return;
+      }
+
+      // Find matching shortcut
+      for (const shortcut of shortcuts) {
+        if (shortcut.enabled === false) continue;
+
+        const keyMatch = e.key.toLowerCase() === shortcut.keys.toLowerCase();
+        const ctrlMatch = shortcut.ctrl
+          ? e.ctrlKey || e.metaKey
+          : !(e.ctrlKey || e.metaKey);
+        const shiftMatch = shortcut.shift ? e.shiftKey : !e.shiftKey;
+        const altMatch = shortcut.alt ? e.altKey : !e.altKey;
+
+        if (keyMatch && ctrlMatch && shiftMatch && altMatch) {
+          // Allow some shortcuts even in input fields
+          const allowInInput =
+            shortcut.key === "save" || shortcut.key === "escape";
+
+          if (!allowInInput && isInputElement(e.target)) {
+            continue;
+          }
+
+          e.preventDefault();
+          shortcut.handler();
+          return;
+        }
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [enabled, shortcuts, showHelp, toggleHelp, closeHelp]);
+
+  return {
+    showHelp,
+    toggleHelp,
+    closeHelp,
+    shortcuts,
+  };
+}