pejay-ui 1.4.3 → 1.5.0

package/templates/form/{textarea.tsx → text-inputs/textarea.tsx}

@@ -1,5 +1,5 @@
 import React, { useState, useRef, useLayoutEffect } from "react";
-import { cn } from "@/utils/cn";
+import { cn } from "@/pejay-ui/utils/cn";
 
 /*
  * ============================================================================

package/templates/hotkeys/README.md

@@ -0,0 +1,134 @@
+# Hotkeys Overlay & Event Manager
+
+A general-purpose, dynamic keyboard shortcut manager for React. It automatically handles platform normalization (e.g. converting `ctrl` to `⌘` on macOS) and ignores triggers while typing in form fields by default. It also features a built-in help overlay (triggered by `Shift + ?`) that dynamically catalogs every hotkey currently active in your application tree.
+
+---
+
+## Installation & Setup
+
+1. Add the component via CLI:
+   ```bash
+   npx pejay-ui add hotkeys
+   ```
+
+2. Wrap your application layout inside `HotkeyProvider`:
+   ```tsx
+   import { HotkeyProvider } from "@/pejay-ui/hotkeys";
+
+   export default function App() {
+     return (
+       <HotkeyProvider>
+         <YourApp />
+       </HotkeyProvider>
+     );
+   }
+   ```
+
+---
+
+## Defining Your Own Key Combinations
+
+You register shortcuts inside any functional component using the `useHotkey` hook. The registration automatically cleans up (unmounts) when the hosting component unmounts.
+
+```tsx
+import { useHotkey } from "@/pejay-ui/hotkeys";
+
+export function SalesDashboard() {
+  useHotkey("ctrl+s", (event) => {
+    // 1. The callback initiates your action
+    console.log("Triggered custom dashboard save!");
+  }, {
+    category: "Dashboard Actions", // Visual category grouping in the help overlay
+    description: "Save dashboard layout"
+  });
+
+  return <div>Sales Dashboard</div>;
+}
+```
+
+---
+
+## Triggering Button Clicks via Hotkeys
+
+When connecting a hotkey to a button, you have two options depending on your setup:
+
+### Option A — Call the click handler directly (Recommended)
+Trigger the function logic directly without worrying about the DOM:
+
+```tsx
+import { useHotkey } from "@/pejay-ui/hotkeys";
+
+export function SaveDashboardPage() {
+  const handleSave = () => {
+    console.log("Saving dashboard data...");
+  };
+
+  // Directly call the handler function in the callback
+  useHotkey("ctrl+s", () => handleSave(), {
+    category: "Dashboard",
+    description: "Save dashboard data"
+  });
+
+  return <button onClick={handleSave}>Save Dashboard</button>;
+}
+```
+
+### Option B — Simulate a click on the DOM element (Using Refs)
+If you want to simulate a physical mouse-click on the button (to trigger hover/active CSS styles or native click propagation), use a React `ref`:
+
+```tsx
+import { useRef } from "react";
+import { useHotkey } from "@/pejay-ui/hotkeys";
+
+export function DashboardPage() {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  // Programmatically click the DOM element in the callback
+  useHotkey("ctrl+s", () => {
+    buttonRef.current?.click();
+  }, {
+    category: "Dashboard",
+    description: "Save dashboard data"
+  });
+
+  return <button ref={buttonRef} onClick={() => console.log("DOM Clicked!")}>Save Dashboard</button>;
+}
+```
+
+---
+
+## Hook API Reference
+
+### `useHotkey(keys, callback, options)`
+
+```ts
+function useHotkey(
+  keys: string,
+  callback: (event: KeyboardEvent) => void,
+  options?: UseHotkeyOptions
+)
+```
+
+### The `options` Object
+
+The 3rd parameter is an options object that configures how the hotkey behaves and how it displays inside the `Shift + ?` help overlay:
+
+| Property | Type | Default | Description |
+|:---|:---|:---|:---|
+| **`description`** | `string` | *raw keys* | The human-readable action label shown next to keys in the help dialog. E.g. `"Submit and save current form"`. |
+| **`category`** | `string` | `"General"` | Groups the shortcut under a specific visual header category in the help dialog. E.g. `"Form Actions"`. |
+| **`enabledInInputs`** | `boolean` | `false` | If `true`, the hotkey triggers even if the user is typing inside text inputs, textareas, or select dropdowns. E.g. set to `true` for global overlays like `Escape`. |
+| **`disabled`** | `boolean` | `false` | If `true`, the hotkey is temporarily deactivated. Useful for checking conditions like `disabled: !isFormDirty` or `disabled: isSubmitting`. |
+
+---
+
+## Supported Modifier Keys & Formats
+
+Specify your key combos in lowercase separated by `+`:
+
+| Format | Output (macOS) | Output (Windows/Linux) |
+|:---|:---|:---|
+| `ctrl+enter` | `⌘ + Enter` | `Ctrl + Enter` |
+| `alt+arrowleft` | `⌥ + ←` | `Alt + ←` |
+| `shift+n` | `⇧ + N` | `Shift + N` |
+| `escape` | `Esc` | `Esc` |

package/templates/hotkeys/components/HotkeyProvider.tsx

@@ -0,0 +1,78 @@
+import { createContext, useContext, useEffect, useState, type ReactNode } from "react";
+import { hotkeyRegistry } from "../core/registry";
+import { isTypingTarget, matchHotkey } from "../core/key-matcher";
+import { HotkeysHelpModal } from "./HotkeysHelpModal";
+
+interface HotkeyContextProps {
+  showHelp: () => void;
+  hideHelp: () => void;
+  isHelpOpen: boolean;
+}
+
+const HotkeyContext = createContext<HotkeyContextProps | undefined>(undefined);
+
+export function useHotkeyContext() {
+  const context = useContext(HotkeyContext);
+  if (!context) {
+    throw new Error("useHotkeyContext must be used within HotkeyProvider");
+  }
+  return context;
+}
+
+interface HotkeyProviderProps {
+  children: ReactNode;
+  /** Custom overlay triggers, e.g. custom key combination to open helper. Default is 'shift+?' */
+  helpTriggerKey?: string;
+  /** Disable the built-in help dialog overlay. Default: false. */
+  disableHelpOverlay?: boolean;
+}
+
+export function HotkeyProvider({
+  children,
+  helpTriggerKey = "shift+?",
+  disableHelpOverlay = false,
+}: HotkeyProviderProps) {
+  const [isHelpOpen, setIsHelpOpen] = useState(false);
+
+  const showHelp = () => setIsHelpOpen(true);
+  const hideHelp = () => setIsHelpOpen(false);
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const isTyping = isTypingTarget(event.target);
+
+      // Check help trigger first
+      if (!disableHelpOverlay && matchHotkey(event, helpTriggerKey)) {
+        if (isTyping) return;
+        event.preventDefault();
+        setIsHelpOpen((prev) => !prev);
+        return;
+      }
+
+      // Process active hotkeys in reverse order (newest registered / topmost takes priority)
+      const activeHotkeys = [...hotkeyRegistry.getActiveHotkeys()].reverse();
+      for (const config of activeHotkeys) {
+        if (matchHotkey(event, config.keys)) {
+          if (isTyping && !config.enabledInInputs) {
+            continue; // Skip because focused in input
+          }
+          event.preventDefault();
+          config.callback(event);
+          break; // Stop at first match
+        }
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [helpTriggerKey, disableHelpOverlay]);
+
+  return (
+    <HotkeyContext.Provider value={{ showHelp, hideHelp, isHelpOpen }}>
+      {children}
+      {!disableHelpOverlay && isHelpOpen && (
+        <HotkeysHelpModal close={hideHelp} />
+      )}
+    </HotkeyContext.Provider>
+  );
+}

package/templates/hotkeys/components/HotkeysHelpModal.tsx

@@ -0,0 +1,102 @@
+import { useEffect, useState } from "react";
+import { hotkeyRegistry } from "../core/registry";
+import { formatKeyCombo } from "../core/key-matcher";
+import type { HotkeyConfig } from "../core/types";
+
+interface HotkeysHelpModalProps {
+  close: () => void;
+}
+
+export function HotkeysHelpModal({ close }: HotkeysHelpModalProps) {
+  const [shortcuts, setShortcuts] = useState<HotkeyConfig[]>([]);
+
+  useEffect(() => {
+    // Esc key to close this modal directly
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        close();
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [close]);
+
+  useEffect(() => {
+    return hotkeyRegistry.subscribe((list) => {
+      setShortcuts(list);
+    });
+  }, []);
+
+  // Group hotkeys by category
+  const grouped = shortcuts.reduce<Record<string, HotkeyConfig[]>>((acc, item) => {
+    const cat = item.category || "General";
+    if (!acc[cat]) acc[cat] = [];
+    acc[cat].push(item);
+    return acc;
+  }, {});
+
+  return (
+    <div
+      className="fixed inset-0 z-[9990] flex items-center justify-center p-4 bg-slate-900/60 backdrop-blur-sm"
+      onClick={close}
+    >
+      <div
+        className="w-full max-w-lg bg-white rounded-2xl shadow-2xl overflow-hidden border border-slate-100 flex flex-col max-h-[85vh]"
+        onClick={(e) => e.stopPropagation()}
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between px-6 py-4 border-b border-slate-100 bg-slate-50/50">
+          <div>
+            <h2 className="text-lg font-bold text-slate-800">Keyboard Shortcuts</h2>
+            <p className="text-xs text-slate-500 mt-0.5">Quick access shortcuts available on this page</p>
+          </div>
+          <button
+            onClick={close}
+            className="p-1.5 hover:bg-slate-100 rounded-lg text-slate-400 hover:text-slate-600 transition-colors"
+          >
+            <svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+            </svg>
+          </button>
+        </div>
+
+        {/* Shortcuts List */}
+        <div className="p-6 overflow-y-auto space-y-6 flex-1 min-h-0">
+          {Object.keys(grouped).length === 0 ? (
+            <p className="text-center text-sm text-slate-400">No active shortcuts registered.</p>
+          ) : (
+            Object.entries(grouped).map(([category, items]) => (
+              <div key={category} className="space-y-3">
+                <h3 className="text-xs font-bold text-slate-400 uppercase tracking-wider">{category}</h3>
+                <div className="space-y-2">
+                  {items.map((item, idx) => (
+                    <div
+                      key={idx}
+                      className="flex items-center justify-between text-sm py-1.5 border-b border-slate-50 last:border-0"
+                    >
+                      <span className="text-slate-600 font-medium">{item.description}</span>
+                      <kbd className="px-2.5 py-1 bg-slate-100 border border-slate-200 rounded-lg shadow-sm text-xs font-semibold text-slate-700 font-mono tracking-wide">
+                        {formatKeyCombo(item.keys)}
+                      </kbd>
+                    </div>
+                  ))}
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+
+        {/* Footer */}
+        <div className="px-6 py-3 bg-slate-50 border-t border-slate-100 flex justify-end">
+          <button
+            onClick={close}
+            className="px-4 py-2 bg-slate-800 hover:bg-slate-900 text-white text-sm font-semibold rounded-xl transition-all shadow-sm"
+          >
+            Close Dialog
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/templates/hotkeys/core/key-matcher.ts

@@ -0,0 +1,106 @@
+export function isMacPlatform() {
+  if (typeof navigator === "undefined") return false;
+  return /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+}
+
+export function formatKeyCombo(keys: string): string {
+  const parts = keys.toLowerCase().split("+");
+  const isMac = isMacPlatform();
+
+  return parts
+    .map((part) => {
+      switch (part) {
+        case "ctrl":
+          return isMac ? "⌘" : "Ctrl";
+        case "alt":
+          return isMac ? "⌥" : "Alt";
+        case "shift":
+          return isMac ? "⇧" : "Shift";
+        case "meta":
+          return isMac ? "⌘" : "Win";
+        case "enter":
+          return "Enter";
+        case "escape":
+          return "Esc";
+        case "arrowleft":
+          return "←";
+        case "arrowright":
+          return "→";
+        case "arrowup":
+          return "↑";
+        case "arrowdown":
+          return "↓";
+        default:
+          return part.charAt(0).toUpperCase() + part.slice(1);
+      }
+    })
+    .join(" + ");
+}
+
+export function isTypingTarget(target: EventTarget | null) {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+
+  const tag = target.tagName;
+  if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
+
+  return Boolean(target.closest("[data-overlay-popover]"));
+}
+
+export function matchHotkey(event: KeyboardEvent, combo: string): boolean {
+  const parts = combo.toLowerCase().split("+");
+  const isMac = isMacPlatform();
+
+  let requiredCtrl = false;
+  let requiredAlt = false;
+  let requiredShift = false;
+  let requiredMeta = false;
+  let targetKey: string | null = null;
+
+  for (const part of parts) {
+    if (part === "ctrl") {
+      if (isMac) {
+        requiredMeta = true; // Use Meta (⌘) instead of Control on Mac by default
+      } else {
+        requiredCtrl = true;
+      }
+    } else if (part === "mod") {
+      if (isMac) {
+        requiredMeta = true;
+      } else {
+        requiredCtrl = true;
+      }
+    } else if (part === "alt") {
+      requiredAlt = true;
+    } else if (part === "shift") {
+      requiredShift = true;
+    } else if (part === "meta") {
+      requiredMeta = true;
+    } else {
+      targetKey = part;
+    }
+  }
+
+  // Check modifiers
+  const ctrlMatch = event.ctrlKey === requiredCtrl;
+  const altMatch = event.altKey === requiredAlt;
+  const shiftMatch = event.shiftKey === requiredShift;
+  const metaMatch = event.metaKey === requiredMeta;
+
+  if (!ctrlMatch || !altMatch || !shiftMatch || !metaMatch) {
+    return false;
+  }
+
+  if (!targetKey) return false;
+
+  const eventKey = event.key.toLowerCase();
+
+  // Normalize simple keys
+  if (targetKey === "esc") targetKey = "escape";
+  if (targetKey === "up") targetKey = "arrowup";
+  if (targetKey === "down") targetKey = "arrowdown";
+  if (targetKey === "left") targetKey = "arrowleft";
+  if (targetKey === "right") targetKey = "arrowright";
+
+  return eventKey === targetKey;
+}

package/templates/hotkeys/core/registry.ts

@@ -0,0 +1,39 @@
+import type { HotkeyConfig } from "./types";
+
+type Listener = (hotkeys: HotkeyConfig[]) => void;
+
+class HotkeyRegistry {
+  private hotkeys: Map<string, HotkeyConfig> = new Map();
+  private listeners: Set<Listener> = new Set();
+
+  register(id: string, config: HotkeyConfig) {
+    this.hotkeys.set(id, config);
+    this.notify();
+  }
+
+  unregister(id: string) {
+    if (this.hotkeys.delete(id)) {
+      this.notify();
+    }
+  }
+
+  getActiveHotkeys(): HotkeyConfig[] {
+    return Array.from(this.hotkeys.values());
+  }
+
+  subscribe(listener: Listener) {
+    this.listeners.add(listener);
+    // Initial call
+    listener(this.getActiveHotkeys());
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private notify() {
+    const list = this.getActiveHotkeys();
+    this.listeners.forEach((listener) => listener(list));
+  }
+}
+
+export const hotkeyRegistry = new HotkeyRegistry();

package/templates/hotkeys/core/types.ts

@@ -0,0 +1,15 @@
+export interface HotkeyConfig {
+  /**
+   * The key combination string, e.g., 'ctrl+enter', 'escape', 'alt+arrowleft', 'shift+?'.
+   * Separate keys with '+'. Case-insensitive.
+   */
+  keys: string;
+  /** Description of what this shortcut does. */
+  description: string;
+  /** Section/Category group to display this hotkey under in the help dialog. */
+  category?: string;
+  /** The action to execute when key combination matches. */
+  callback: (event: KeyboardEvent) => void;
+  /** If true, the hotkey will still trigger even if focusing an input, textarea, or contentEditable element. Default: false. */
+  enabledInInputs?: boolean;
+}

package/templates/hotkeys/hooks/useHotkey.ts

@@ -0,0 +1,43 @@
+import { useEffect, useRef } from "react";
+import { hotkeyRegistry } from "../core/registry";
+import type { HotkeyConfig } from "../core/types";
+
+interface UseHotkeyOptions {
+  category?: string;
+  description?: string;
+  enabledInInputs?: boolean;
+  disabled?: boolean;
+}
+
+export function useHotkey(
+  keys: string,
+  callback: (event: KeyboardEvent) => void,
+  options: UseHotkeyOptions = {},
+) {
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  const disabled = Boolean(options.disabled);
+  const category = options.category;
+  const description = options.description;
+  const enabledInInputs = options.enabledInInputs;
+
+  useEffect(() => {
+    if (disabled) return;
+
+    const id = crypto.randomUUID();
+    const config: HotkeyConfig = {
+      keys,
+      description: description || keys,
+      category,
+      enabledInInputs,
+      callback: (e) => callbackRef.current(e),
+    };
+
+    hotkeyRegistry.register(id, config);
+
+    return () => {
+      hotkeyRegistry.unregister(id);
+    };
+  }, [keys, disabled, category, description, enabledInInputs]);
+}

package/templates/hotkeys/index.ts

@@ -0,0 +1,6 @@
+export * from "./core/types";
+export * from "./core/registry";
+export * from "./core/key-matcher";
+export * from "./hooks/useHotkey";
+export * from "./components/HotkeyProvider";
+export * from "./components/HotkeysHelpModal";

package/templates/layouts/lv1/app-layout.tsx

@@ -1,6 +1,6 @@
 import { useState, useLayoutEffect, useEffect } from "react";
 import { Menu, PanelLeftOpen, PanelRightOpen, X } from "lucide-react";
-import { cn } from "@/utils/cn";
+import { cn } from "@/pejay-ui/utils/cn";
 import { MenuSection, SidebarMenu } from "./sidebar-menu";
 
 

package/templates/layouts/lv1/sidebar-menu.tsx

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import { cn } from "@/utils/cn";
+import { cn } from "@/pejay-ui/utils/cn";
 
 // ============================================================================
 // Types