@keybindy/react 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 PRASSamin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# @keybindy/react
+
+@keybindy/react is the official React integration for the [Keybindy](https://www.npmjs.com/package/@keybindy/core) keyboard shortcut system. Built on top of `@keybindy/core`, this package brings powerful and scoped keyboard bindings to your React applications — with components and hooks tailored to React’s architecture.
+
+[![npm version](https://badge.fury.io/js/@keybindy%2Freact.svg)](https://www.npmjs.com/package/@keybindy/react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🧠 What is @keybindy/react?
+
+While `@keybindy/core` gives you the underlying logic to register and manage shortcuts in any JavaScript environment, **@keybindy/react** wraps it in a React-friendly API with scoped context, declarative components, and hooks for full control.
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @keybindy/react
+
+# yarn
+yarn add @keybindy/react
+
+# bun
+bun add @keybindy/react
+```
+
+---
+
+## Usage
+
+#### `<Keybindy />` component
+
+The core declarative component. Register all your scoped or global shortcuts with ease.
+
+| Prop              | Type                 | Default     | Description                                                    |
+| ----------------- | -------------------- | ----------- | -------------------------------------------------------------- |
+| `logs`            | `boolean`            | `false`     | Whether to enable debug logs in the console.                   |
+| `onShortcutFired` | `fn(info: Shortcut)` | `undefined` | Optional callback to handle shortcut firing events.            |
+| `disabled`        | `boolean`            | `false`     | Whether to disable all shortcuts within the component's scope. |
+| `scope`           | `string`             | `global`    | The scope to apply the shortcuts to.                           |
+| `shortcuts`       | `Shortcut[]`         | `[]`        | Array of shortcut objects to register.                         |
+| `children`        | `React.ReactNode`    | `undefined` | The content to render inside the component.                    |
+
+##### Example
+
+```ts
+import { Keybindy } from '@keybindy/react';
+
+<Keybindy
+  scope="global"
+  shortcuts={[
+    {
+      keys: ['A'],
+      handler: () => console.log('A pressed'),
+      options: {
+        preventDefault: true,
+      },
+    },
+    {
+      keys: ['O', 'P'],
+      handler: () => setIsOpen(true),
+      options: {
+        sequenceDelay: 1000,
+        sequential: true,
+        preventDefault: true,
+      },
+    },
+    {
+      keys: ['R'],
+      handler: () => window.open('https://react.dev', '_blank'),
+      options: {
+        preventDefault: true,
+      },
+    },
+  ]}
+/>;
+```
+
+#### `<ShortcutLabel />` component
+
+A lightweight UI component to render visually styled shortcut hints.
+
+| Prop        | Type                                           | Default     | Description                                    |
+| ----------- | ---------------------------------------------- | ----------- | ---------------------------------------------- |
+| `keys`      | `Keys`                                         | `[]`        | The key combination(s) to display.             |
+| `renderKey` | `fn(key: string, index: number, keys: Keys[])` | `undefined` | Custom renderer for each key badge or segment. |
+
+##### Example
+
+```ts
+import { ShortcutLabel } from '@keybindy/react';
+
+<ShortcutLabel
+  keys={['ctrl', 'alt', 'delete']}
+  renderKey={(key, i, all) => (
+    <>
+      <span style={{ color: '#00eaff' }}>{key.toUpperCase()}</span>
+      {i < all.length - 1 && <span style={{ opacity: 0.5 }}> + </span>}
+    </>
+  )}
+/>;
+```
+
+#### `useKeybindy` Hook
+
+A powerful hook that gives you full control over the shortcut system via the ShortcutManager under the hood. Best for dynamic or advanced use cases.
+
+##### Available methods
+
+| Method                                                                | Description                                  |
+| --------------------------------------------------------------------- | -------------------------------------------- |
+| [`register()`](https://github.com/keybindy/core#register)             | Register a shortcut                          |
+| [`unregister()`](https://github.com/keybindy/core#unregister)         | Unregister a shortcut                        |
+| [`enable()`](https://github.com/keybindy/core#enable--disable--toggle)                 | Enable a specific shortcut                   |
+| [`disable()`](https://github.com/keybindy/core#enable--disable--toggle)               | Disable a specific shortcut                  |
+| [`toggle()`](https://github.com/keybindy/core#enable--disable--toggle)                 | Toggle a shortcut on/off                     |
+| [`enableAll()`](https://github.com/keybindy/core#enableall--disableall)           | Enable all shortcuts (global or scoped)      |
+| [`disableAll()`](https://github.com/keybindy/core#enableall--disableall)         | Disable all shortcuts (global or scoped)     |
+| [`setScope()`](https://github.com/keybindy/core#setactivescope)       | Set the active scope                         |
+| [`resetScope()`](https://github.com/keybindy/core#resetScope)         | Reset to default scope                       |
+| [`getScopes()`](https://github.com/keybindy/core#getScopes)           | Get all defined scopes                       |
+| [`getActiveScope()`](https://github.com/keybindy/core#getActiveScope) | Get the current active scope                 |
+| [`popScope()`](https://github.com/keybindy/core#popScope)             | Remove the top scope from the scope stack    |
+| [`pushScope()`](https://github.com/keybindy/core#pushScope)           | Push a new scope onto the scope stack        |
+| [`getCheatSheet()`](https://github.com/keybindy/core#getCheatsheet)   | Retrieve all shortcuts (optionally by scope) |
+| [`onTyping()`](https://github.com/keybindy/core#onTyping)             | Listen to every key press                    |
+| [`destroy()`](https://github.com/keybindy/core#destroy)               | Tear down the current manager instance       |
+| [`clear()`](https://github.com/keybindy/core#clear)                   | Unregister all shortcuts                     |
+| [`getScopeInfo()`](https://github.com/keybindy/core#getScopeInfo)     | Retrieve metadata about a specific scope     |
+| [`isScopeActive()`](https://github.com/keybindy/core#isScopeActive)   | Check if a scope is currently active         |
+
+> _All methods mirror `@keybindy/core` with a React-friendly API._
+
+##### Example
+
+```ts
+import { useKeybindy } from '@keybindy/react';
+
+const { register, unregister, setScope, getCheatSheet } = useKeybindy();
+
+React.useEffect(() => {
+  register(
+    ['ctrl', 'k'],
+    () => {
+      console.log('Shortcut fired!');
+    },
+    {
+      scope: 'editor',
+      preventDefault: true,
+    }
+  );
+
+  return () => {
+    unregister(['ctrl', 'k'], 'editor');
+  };
+}, []);
+```
+
+---
+
+## Reference
+
+If you're looking for more detailed implementation logic and architecture, check out the [@keybindy/core](https://www.npmjs.com/package/@keybindy/core) documentation for an in-depth look at how shortcut handling works under the hood.
+
+---
+
+## 🧩 Want More?
+
+This package is part of the Keybindy Ecosystem:
+
+| Package                                                        | Description                                                                      |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| [`@keybindy/core`](https://npmjs.com/package/@keybindy/core)   | The core JavaScript library. Framework-agnostic, fully typed, and tree-shakable. |
+| [`@keybindy/react`](https://npmjs.com/package/@keybindy/react) | React bindings with hooks and components for easy integration.                   |
+| _Coming Soon_                                                  | Stay tuned!                                                                      |
+
+---
+
+## Contributing
+
+PRs, issues, and ideas are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+If you're adding a new framework integration (like Vue or Svelte), feel free to open a draft PR — we'd love to collaborate.
+
+---
+
+> _Might be new in the shortcut game, but Keybindy’s here to change the frame — fast, flexible, and ready to claim. 🎯_

package/dist/Keybindy.d.ts

@@ -0,0 +1,87 @@
+import React from 'react';
+import type { Keys, Shortcut as ShortcutType, ShortcutHandler, ShortcutOptions } from '@keybindy/core';
+/**
+ * Represents a keyboard shortcut definition.
+ */
+type ShortcutDefinition = {
+    /**
+     * The key combination(s) to listen for.
+     * Can be a single array of keys or an array of key combinations.
+     */
+    keys: Keys[] | Keys[][];
+    /**
+     * Callback function to invoke when the shortcut is triggered.
+     */
+    handler: ShortcutHandler;
+    /**
+     * Optional configuration, including scope and other metadata.
+     */
+    options?: Omit<ShortcutOptions, 'scope'>;
+};
+/**
+ * Props for the `<Keybindy />` component.
+ */
+type KeybindyProps = {
+    /**
+     * The scope under which the shortcuts should be active.
+     * This allows managing different contexts for shortcuts.
+     */
+    scope: string;
+    /**
+     * Array of shortcut definitions to register for this scope.
+     */
+    shortcuts?: ShortcutDefinition[];
+    /**
+     * Whether the shortcuts should be disabled for this scope.
+     * Defaults to `false`.
+     */
+    disabled?: boolean;
+    /**
+     * Callback function that will be called when a shortcut is fired.
+     * Receives the fired shortcut info as an argument.
+     */
+    onShortcutFired?: (info: ShortcutType) => void;
+    /**
+     * Whether to enable debug logs in the console.
+     */
+    logs?: boolean;
+    /**
+     * The content that will be rendered inside the Shortcut component.
+     */
+    children: React.ReactNode;
+};
+/**
+ * `<Keybindy />` is a React component that registers keyboard shortcuts within a given scope. It allows
+ * users to define custom shortcuts and their associated handlers, while managing scope-based shortcut behavior.
+ * The component listens for keyboard events and triggers the registered handler when the corresponding keys are pressed.
+ * It also provides an optional callback (`onShortcutFired`) to notify users when a shortcut is triggered.
+ *
+ * @component
+ *
+ * @example
+ * // Basic usage
+ * <Keybindy scope="global" shortcuts={[{ keys: ['ctrl', 's'], handler: saveDocument }]} >
+ *   <div>Content with shortcuts</div>
+ * </Keybindy>
+ *
+ * @example
+ * // With custom callback for onShortcutFired
+ * <Keybindy
+ *   scope="editor"
+ *   shortcuts={[{ keys: ['ctrl', 'e'], handler: editDocument }]}
+ *   onShortcutFired={(info) => console.log('Shortcut fired:', info)}
+ * >
+ *   <div>Editor with shortcuts</div>
+ * </Keybindy>
+ *
+ * @param {ShortcutProps} props - Props for the Shortcut component.
+ * @param {string} props.scope - The scope under which the shortcuts should be active.
+ * @param {ShortcutDefinition[]} [props.shortcuts] - An array of shortcut definitions, each containing keys, handler, and options.
+ * @param {boolean} [props.disabled=false] - Whether the shortcuts should be disabled for this scope.
+ * @param {(info: Shortcut) => void} [props.onShortcutFired] - Optional callback triggered when a shortcut is fired, providing the shortcut info.
+ * @param {React.ReactNode} props.children - The children to be rendered inside the component, which can contain any JSX elements.
+ *
+ * @returns {JSX.Element} The rendered component with registered shortcuts within the provided scope.
+ */
+export declare const Keybindy: React.FC<KeybindyProps>;
+export {};

package/dist/Keybindy.js

@@ -0,0 +1,74 @@
+import { jsx, Fragment } from 'react/jsx-runtime';
+import React from 'react';
+import { useKeybindy } from './useKeybindy.js';
+
+/**
+ * `<Keybindy />` is a React component that registers keyboard shortcuts within a given scope. It allows
+ * users to define custom shortcuts and their associated handlers, while managing scope-based shortcut behavior.
+ * The component listens for keyboard events and triggers the registered handler when the corresponding keys are pressed.
+ * It also provides an optional callback (`onShortcutFired`) to notify users when a shortcut is triggered.
+ *
+ * @component
+ *
+ * @example
+ * // Basic usage
+ * <Keybindy scope="global" shortcuts={[{ keys: ['ctrl', 's'], handler: saveDocument }]} >
+ *   <div>Content with shortcuts</div>
+ * </Keybindy>
+ *
+ * @example
+ * // With custom callback for onShortcutFired
+ * <Keybindy
+ *   scope="editor"
+ *   shortcuts={[{ keys: ['ctrl', 'e'], handler: editDocument }]}
+ *   onShortcutFired={(info) => console.log('Shortcut fired:', info)}
+ * >
+ *   <div>Editor with shortcuts</div>
+ * </Keybindy>
+ *
+ * @param {ShortcutProps} props - Props for the Shortcut component.
+ * @param {string} props.scope - The scope under which the shortcuts should be active.
+ * @param {ShortcutDefinition[]} [props.shortcuts] - An array of shortcut definitions, each containing keys, handler, and options.
+ * @param {boolean} [props.disabled=false] - Whether the shortcuts should be disabled for this scope.
+ * @param {(info: Shortcut) => void} [props.onShortcutFired] - Optional callback triggered when a shortcut is fired, providing the shortcut info.
+ * @param {React.ReactNode} props.children - The children to be rendered inside the component, which can contain any JSX elements.
+ *
+ * @returns {JSX.Element} The rendered component with registered shortcuts within the provided scope.
+ */
+const Keybindy = ({ scope, shortcuts = [], children, disabled, onShortcutFired, logs = false, }) => {
+    const { register, unregister, manager, pushScope, popScope, getScopes, setScope } = useKeybindy({
+        onShortcutFired,
+        logs,
+    });
+    const prevScope = React.useRef(null);
+    React.useEffect(() => {
+        prevScope.current = manager.getActiveScope();
+        // Add scope if doesn't exist
+        if (!getScopes()?.includes(scope)) {
+            pushScope(scope);
+        }
+        // Set this scope as active
+        setScope(scope);
+        // Register all shortcuts for this scope
+        shortcuts.forEach(({ keys, handler, options }) => {
+            register(keys, handler, { ...options, scope });
+        });
+        if (disabled) {
+            manager.disableAll(scope);
+        }
+        return () => {
+            shortcuts.forEach(({ keys }) => {
+                if (Array.isArray(keys[0])) {
+                    keys.forEach(key => unregister(key, scope));
+                }
+                else {
+                    unregister(keys, scope);
+                }
+            });
+            popScope();
+        };
+    }, [scope, JSON.stringify(shortcuts)]);
+    return jsx(Fragment, { children: children });
+};
+
+export { Keybindy };

package/dist/ShortcutLabel.d.ts

@@ -0,0 +1,57 @@
+import type { Keys } from '@keybindy/core';
+import React from 'react';
+interface ShortcutLabelProps extends React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> {
+    /**
+     * Array of keys to display
+     */
+    keys: Omit<Keys, 'Ctrl (Left)' | 'Ctrl (Right)' | 'Shift (Left)' | 'Shift (Right)' | 'Alt (Left)' | 'Alt (Right)' | 'Meta (Left)' | 'Meta (Right)'>[];
+    /**
+     * Custom render function for each key
+     */
+    renderKey?: (
+    /**
+     * The key to render
+     */
+    key: string, 
+    /**
+     * The index of the key in the array
+     */
+    index: number, 
+    /**
+     * All keys in the array
+     */
+    allKeys: string[]) => React.ReactNode;
+}
+/**
+ * `<ShortcutLabel />` is a utility React component that visually renders a keyboard shortcut label.
+ *
+ * It accepts an array of keys (e.g. `["Ctrl", "S"]`) and renders a styled label using platform-aware
+ * symbols (⌘ for Mac, Ctrl for others). Users can also provide a custom render function to override
+ * the default display logic for advanced layouts or custom themes.
+ *
+ * @component
+ *
+ * @example
+ * // Default usage
+ * <ShortcutLabel keys={['ctrl', 's']} />
+ *
+ * @example
+ * // With custom renderKey
+ * <ShortcutLabel
+ *   keys={['ctrl', 'alt', 'delete']}
+ *   renderKey={(key, i, all) => (
+ *     <>
+ *       <span style={{ color: '#00eaff' }}>{key.toUpperCase()}</span>
+ *       {i < all.length - 1 && <span style={{ opacity: 0.5 }}> + </span>}
+ *     </>
+ *   )}
+ * />
+ *
+ * @param {ShortcutLabelProps} props - Props for the ShortcutLabel component
+ * @param {string[]} props.keys - The list of keys to display.
+ * @param {Function} [props.renderKey] - Optional custom render function for full control over how each key appears.
+ *
+ * @returns {JSX.Element} Rendered shortcut label
+ */
+export declare const ShortcutLabel: ({ keys, renderKey, style, ...props }: ShortcutLabelProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/ShortcutLabel.js

@@ -0,0 +1,69 @@
+import { jsx } from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * `<ShortcutLabel />` is a utility React component that visually renders a keyboard shortcut label.
+ *
+ * It accepts an array of keys (e.g. `["Ctrl", "S"]`) and renders a styled label using platform-aware
+ * symbols (⌘ for Mac, Ctrl for others). Users can also provide a custom render function to override
+ * the default display logic for advanced layouts or custom themes.
+ *
+ * @component
+ *
+ * @example
+ * // Default usage
+ * <ShortcutLabel keys={['ctrl', 's']} />
+ *
+ * @example
+ * // With custom renderKey
+ * <ShortcutLabel
+ *   keys={['ctrl', 'alt', 'delete']}
+ *   renderKey={(key, i, all) => (
+ *     <>
+ *       <span style={{ color: '#00eaff' }}>{key.toUpperCase()}</span>
+ *       {i < all.length - 1 && <span style={{ opacity: 0.5 }}> + </span>}
+ *     </>
+ *   )}
+ * />
+ *
+ * @param {ShortcutLabelProps} props - Props for the ShortcutLabel component
+ * @param {string[]} props.keys - The list of keys to display.
+ * @param {Function} [props.renderKey] - Optional custom render function for full control over how each key appears.
+ *
+ * @returns {JSX.Element} Rendered shortcut label
+ */
+const ShortcutLabel = ({ keys, renderKey, style, ...props }) => {
+    const isMac = typeof navigator !== 'undefined' && /Mac/.test(navigator.userAgent);
+    const defaultRenderKey = (key) => {
+        switch (key.toLowerCase()) {
+            case 'meta':
+                return isMac ? '⌘' : 'Ctrl';
+            case 'ctrl':
+                return 'Ctrl';
+            case 'shift':
+                return '⇧';
+            case 'alt':
+                return isMac ? '⌥' : 'Alt';
+            case 'enter':
+                return '↵';
+            default:
+                return key.toUpperCase();
+        }
+    };
+    const rendered = renderKey
+        ? keys.map((key, i) => (jsx(React.Fragment, { children: renderKey(key, i, keys) }, i)))
+        : defaultRenderKey
+            ? [keys.map(key => defaultRenderKey(key)).join(' + ')]
+            : [];
+    return (jsx("kbd", { style: {
+            fontFamily: 'monospace',
+            padding: '2.5px 5px',
+            border: '1px solid #cccccc2f',
+            backgroundColor: '#2e2e2e',
+            borderRadius: '4px',
+            userSelect: 'none',
+            ...style,
+        }, ...props, children: rendered }));
+};
+
+export { ShortcutLabel };

package/dist/index.d.ts

@@ -0,0 +1,216 @@
+import React from 'react';
+import ShortcutManager, { Keys, ShortcutHandler, ShortcutOptions, Shortcut } from '@keybindy/core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Represents a keyboard shortcut definition.
+ */
+type ShortcutDefinition = {
+    /**
+     * The key combination(s) to listen for.
+     * Can be a single array of keys or an array of key combinations.
+     */
+    keys: Keys[] | Keys[][];
+    /**
+     * Callback function to invoke when the shortcut is triggered.
+     */
+    handler: ShortcutHandler;
+    /**
+     * Optional configuration, including scope and other metadata.
+     */
+    options?: Omit<ShortcutOptions, 'scope'>;
+};
+/**
+ * Props for the `<Keybindy />` component.
+ */
+type KeybindyProps = {
+    /**
+     * The scope under which the shortcuts should be active.
+     * This allows managing different contexts for shortcuts.
+     */
+    scope: string;
+    /**
+     * Array of shortcut definitions to register for this scope.
+     */
+    shortcuts?: ShortcutDefinition[];
+    /**
+     * Whether the shortcuts should be disabled for this scope.
+     * Defaults to `false`.
+     */
+    disabled?: boolean;
+    /**
+     * Callback function that will be called when a shortcut is fired.
+     * Receives the fired shortcut info as an argument.
+     */
+    onShortcutFired?: (info: Shortcut) => void;
+    /**
+     * Whether to enable debug logs in the console.
+     */
+    logs?: boolean;
+    /**
+     * The content that will be rendered inside the Shortcut component.
+     */
+    children: React.ReactNode;
+};
+/**
+ * `<Keybindy />` is a React component that registers keyboard shortcuts within a given scope. It allows
+ * users to define custom shortcuts and their associated handlers, while managing scope-based shortcut behavior.
+ * The component listens for keyboard events and triggers the registered handler when the corresponding keys are pressed.
+ * It also provides an optional callback (`onShortcutFired`) to notify users when a shortcut is triggered.
+ *
+ * @component
+ *
+ * @example
+ * // Basic usage
+ * <Keybindy scope="global" shortcuts={[{ keys: ['ctrl', 's'], handler: saveDocument }]} >
+ *   <div>Content with shortcuts</div>
+ * </Keybindy>
+ *
+ * @example
+ * // With custom callback for onShortcutFired
+ * <Keybindy
+ *   scope="editor"
+ *   shortcuts={[{ keys: ['ctrl', 'e'], handler: editDocument }]}
+ *   onShortcutFired={(info) => console.log('Shortcut fired:', info)}
+ * >
+ *   <div>Editor with shortcuts</div>
+ * </Keybindy>
+ *
+ * @param {ShortcutProps} props - Props for the Shortcut component.
+ * @param {string} props.scope - The scope under which the shortcuts should be active.
+ * @param {ShortcutDefinition[]} [props.shortcuts] - An array of shortcut definitions, each containing keys, handler, and options.
+ * @param {boolean} [props.disabled=false] - Whether the shortcuts should be disabled for this scope.
+ * @param {(info: Shortcut) => void} [props.onShortcutFired] - Optional callback triggered when a shortcut is fired, providing the shortcut info.
+ * @param {React.ReactNode} props.children - The children to be rendered inside the component, which can contain any JSX elements.
+ *
+ * @returns {JSX.Element} The rendered component with registered shortcuts within the provided scope.
+ */
+declare const Keybindy: React.FC<KeybindyProps>;
+
+interface ShortcutLabelProps extends React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> {
+    /**
+     * Array of keys to display
+     */
+    keys: Omit<Keys, 'Ctrl (Left)' | 'Ctrl (Right)' | 'Shift (Left)' | 'Shift (Right)' | 'Alt (Left)' | 'Alt (Right)' | 'Meta (Left)' | 'Meta (Right)'>[];
+    /**
+     * Custom render function for each key
+     */
+    renderKey?: (
+    /**
+     * The key to render
+     */
+    key: string, 
+    /**
+     * The index of the key in the array
+     */
+    index: number, 
+    /**
+     * All keys in the array
+     */
+    allKeys: string[]) => React.ReactNode;
+}
+/**
+ * `<ShortcutLabel />` is a utility React component that visually renders a keyboard shortcut label.
+ *
+ * It accepts an array of keys (e.g. `["Ctrl", "S"]`) and renders a styled label using platform-aware
+ * symbols (⌘ for Mac, Ctrl for others). Users can also provide a custom render function to override
+ * the default display logic for advanced layouts or custom themes.
+ *
+ * @component
+ *
+ * @example
+ * // Default usage
+ * <ShortcutLabel keys={['ctrl', 's']} />
+ *
+ * @example
+ * // With custom renderKey
+ * <ShortcutLabel
+ *   keys={['ctrl', 'alt', 'delete']}
+ *   renderKey={(key, i, all) => (
+ *     <>
+ *       <span style={{ color: '#00eaff' }}>{key.toUpperCase()}</span>
+ *       {i < all.length - 1 && <span style={{ opacity: 0.5 }}> + </span>}
+ *     </>
+ *   )}
+ * />
+ *
+ * @param {ShortcutLabelProps} props - Props for the ShortcutLabel component
+ * @param {string[]} props.keys - The list of keys to display.
+ * @param {Function} [props.renderKey] - Optional custom render function for full control over how each key appears.
+ *
+ * @returns {JSX.Element} Rendered shortcut label
+ */
+declare const ShortcutLabel: ({ keys, renderKey, style, ...props }: ShortcutLabelProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * React hook to manage keyboard shortcuts using a shared instance of `ShortcutManager`.
+ * Automatically cleans up shortcuts registered by the component on unmount.
+ *
+ * @param {Object} config - Configuration object.
+ * @param {boolean} [config.logs=false] - Whether to enable debug logs in the console.
+ *
+ * @returns {Object} Object containing shortcut management methods.
+ *
+ * @example
+ * const {
+ *   register,
+ *   setScope,
+ *   getCheatSheet,
+ * } = useKeybindy({ logs: true });
+ *
+ * useEffect(() => {
+ *   register(['ctrl', 's'], () => save(), {
+ *     scope: 'editor',
+ *     data: { description: 'Save document' }
+ *   });
+ *   setScope('editor');
+ * }, []);
+ */
+declare function useKeybindy({ logs, onShortcutFired, }?: {
+    logs?: boolean;
+    onShortcutFired?: (info: Shortcut) => void;
+}): {
+    register: (keys: Keys[] | Keys[][], handler: ShortcutHandler, options?: ShortcutOptions) => void;
+    unregister: (keys: Keys[], scope?: string) => void;
+    enable: (keys: Keys[], scope?: string) => void;
+    disable: (keys: Keys[], scope?: string) => void;
+    toggle: (keys: Keys[], scope?: string) => void;
+    setScope: (scope: string) => void;
+    getCheatSheet: (scope?: string) => {
+        keys: string[];
+    }[] | undefined;
+    destroy: () => void;
+    getScopeInfo: (scope?: string) => {
+        shortcuts: {
+            keys: string[];
+            id: string;
+            enabled: boolean;
+            data?: Record<string, string>;
+        }[];
+        isActive?: boolean;
+    } | Record<string, {
+        shortcuts: {
+            keys: string[];
+            id: string;
+            enabled: boolean;
+            data?: Record<string, string>;
+        }[];
+        isActive?: boolean;
+    }> | undefined;
+    getActiveScope: () => string | undefined;
+    popScope: () => void;
+    pushScope: (scope: string) => void;
+    resetScope: () => void;
+    getScopes: () => string[] | undefined;
+    isScopeActive: (scope: string) => boolean | undefined;
+    onTyping: (callback: (payload: {
+        key: string;
+        event: KeyboardEvent;
+    }) => void) => void;
+    enableAll: (scope?: string) => void;
+    clear: () => void;
+    disableAll: (scope?: string) => void;
+    manager: ShortcutManager;
+};
+
+export { Keybindy, ShortcutLabel, useKeybindy };

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Keybindy } from './Keybindy.js';
+export { ShortcutLabel } from './ShortcutLabel.js';
+export { useKeybindy } from './useKeybindy.js';

package/dist/useKeybindy.d.ts

@@ -0,0 +1,72 @@
+import ShortcutManager from '@keybindy/core';
+import type { Keys, Shortcut, ShortcutHandler, ShortcutOptions } from '@keybindy/core';
+/**
+ * React hook to manage keyboard shortcuts using a shared instance of `ShortcutManager`.
+ * Automatically cleans up shortcuts registered by the component on unmount.
+ *
+ * @param {Object} config - Configuration object.
+ * @param {boolean} [config.logs=false] - Whether to enable debug logs in the console.
+ *
+ * @returns {Object} Object containing shortcut management methods.
+ *
+ * @example
+ * const {
+ *   register,
+ *   setScope,
+ *   getCheatSheet,
+ * } = useKeybindy({ logs: true });
+ *
+ * useEffect(() => {
+ *   register(['ctrl', 's'], () => save(), {
+ *     scope: 'editor',
+ *     data: { description: 'Save document' }
+ *   });
+ *   setScope('editor');
+ * }, []);
+ */
+export declare function useKeybindy({ logs, onShortcutFired, }?: {
+    logs?: boolean;
+    onShortcutFired?: (info: Shortcut) => void;
+}): {
+    register: (keys: Keys[] | Keys[][], handler: ShortcutHandler, options?: ShortcutOptions) => void;
+    unregister: (keys: Keys[], scope?: string) => void;
+    enable: (keys: Keys[], scope?: string) => void;
+    disable: (keys: Keys[], scope?: string) => void;
+    toggle: (keys: Keys[], scope?: string) => void;
+    setScope: (scope: string) => void;
+    getCheatSheet: (scope?: string) => {
+        keys: string[];
+    }[] | undefined;
+    destroy: () => void;
+    getScopeInfo: (scope?: string) => {
+        shortcuts: {
+            keys: string[];
+            id: string;
+            enabled: boolean;
+            data?: Record<string, string>;
+        }[];
+        isActive?: boolean;
+    } | Record<string, {
+        shortcuts: {
+            keys: string[];
+            id: string;
+            enabled: boolean;
+            data?: Record<string, string>;
+        }[];
+        isActive?: boolean;
+    }> | undefined;
+    getActiveScope: () => string | undefined;
+    popScope: () => void;
+    pushScope: (scope: string) => void;
+    resetScope: () => void;
+    getScopes: () => string[] | undefined;
+    isScopeActive: (scope: string) => boolean | undefined;
+    onTyping: (callback: (payload: {
+        key: string;
+        event: KeyboardEvent;
+    }) => void) => void;
+    enableAll: (scope?: string) => void;
+    clear: () => void;
+    disableAll: (scope?: string) => void;
+    manager: ShortcutManager;
+};

package/dist/useKeybindy.js

@@ -0,0 +1,253 @@
+import React from 'react';
+import ShortcutManager from '@keybindy/core';
+
+let sharedInstance = null;
+/**
+ * React hook to manage keyboard shortcuts using a shared instance of `ShortcutManager`.
+ * Automatically cleans up shortcuts registered by the component on unmount.
+ *
+ * @param {Object} config - Configuration object.
+ * @param {boolean} [config.logs=false] - Whether to enable debug logs in the console.
+ *
+ * @returns {Object} Object containing shortcut management methods.
+ *
+ * @example
+ * const {
+ *   register,
+ *   setScope,
+ *   getCheatSheet,
+ * } = useKeybindy({ logs: true });
+ *
+ * useEffect(() => {
+ *   register(['ctrl', 's'], () => save(), {
+ *     scope: 'editor',
+ *     data: { description: 'Save document' }
+ *   });
+ *   setScope('editor');
+ * }, []);
+ */
+function useKeybindy({ logs = false, onShortcutFired, } = {}) {
+    const managerRef = React.useRef(null);
+    const registeredIds = React.useRef(new Set());
+    if (!sharedInstance) {
+        sharedInstance = new ShortcutManager(onShortcutFired);
+    }
+    if (!managerRef.current) {
+        managerRef.current = sharedInstance;
+        managerRef.current.start();
+    }
+    const log = (...args) => {
+        if (logs)
+            console.log('[Keybindy]', ...args);
+    };
+    const warn = (...args) => {
+        if (logs)
+            console.warn('[Keybindy]', ...args);
+    };
+    /**
+     * Registers a new keyboard shortcut.
+     *
+     * @param {Keys[] | Keys[][]} keys - Key combination(s) to listen for.
+     * @param {ShortcutHandler} handler - Callback function to invoke when shortcut is triggered.
+     * @param {ShortcutOptions} [options] - Optional configuration, including scope and metadata.
+     */
+    const register = React.useCallback((keys, handler, options) => {
+        if (keys.length === 0) {
+            warn('No keys provided to register');
+            return;
+        }
+        const id = options?.data?.id;
+        if (id)
+            registeredIds.current.add(id);
+        log('Registered:', id ?? keys);
+        managerRef.current?.register(keys, handler, options);
+    }, []);
+    /**
+     * Unregisters a previously registered keyboard shortcut.
+     *
+     * @param {Keys[]} keys - Key combination to unregister.
+     * @param {string} [scope] - Optional scope for more targeted unregistration.
+     */
+    const unregister = React.useCallback((keys, scope) => {
+        if (keys.length === 0) {
+            warn('No keys provided to unregister');
+            return;
+        }
+        managerRef.current?.unregister(keys, scope);
+        log('Unregistered:', keys);
+    }, []);
+    /**
+     * Enables a previously disabled shortcut.
+     *
+     * @param {Keys[]} keys - Key combination to enable.
+     * @param {string} [scope] - Optional scope to target a specific set.
+     */
+    const enable = React.useCallback((keys, scope) => {
+        if (keys.length === 0) {
+            warn('No keys provided to enable');
+            return;
+        }
+        managerRef.current?.enable(keys, scope);
+        log('Enabled:', keys);
+    }, []);
+    /**
+     * Disables a shortcut so it no longer triggers its handler.
+     *
+     * @param {Keys[]} keys - Key combination to disable.
+     * @param {string} [scope] - Optional scope to target a specific set.
+     */
+    const disable = React.useCallback((keys, scope) => {
+        if (keys.length === 0) {
+            warn('No keys provided to disable');
+            return;
+        }
+        managerRef.current?.disable(keys, scope);
+        log('Disabled:', keys);
+    }, []);
+    /**
+     * Toggles a shortcut between enabled and disabled.
+     *
+     * @param {Keys[]} keys - Key combination to toggle.
+     * @param {string} [scope] - Optional scope to target a specific set.
+     */
+    const toggle = React.useCallback((keys, scope) => {
+        if (keys.length === 0) {
+            warn('No keys provided to toggle');
+            return;
+        }
+        managerRef.current?.toggle(keys, scope);
+        log('Toggled:', keys);
+    }, []);
+    /**
+     * Returns a list of shortcuts registered in a given scope.
+     *
+     * @param {string} [scope] - The scope to query. Defaults to the active scope.
+     * @returns {Array} List of shortcut definitions.
+     */
+    const getCheatSheet = React.useCallback((scope) => {
+        return managerRef.current?.getCheatSheet(scope);
+    }, []);
+    /**
+     * Returns the currently active scope.
+     * @returns {string} The active scope.
+     */
+    const getActiveScope = React.useCallback(() => {
+        return managerRef.current?.getActiveScope();
+    }, []);
+    /**
+     * Disables all shortcuts in the specified scope or all scopes if no scope is provided.
+     * @param scope - The scope to disable shortcuts in.
+     */
+    const disableAll = React.useCallback((scope) => {
+        managerRef.current?.disableAll(scope);
+        log(`Disabled all shortcuts${scope ? ` in scope "${scope}"` : ''}`);
+    }, []);
+    /**
+     * Enables all shortcuts in the specified scope or all scopes if no scope is provided.
+     * @param scope - The scope to enable shortcuts in.
+     */
+    const enableAll = React.useCallback((scope) => {
+        managerRef.current?.enableAll(scope);
+        log(`Enabled all shortcuts${scope ? ` in scope "${scope}"` : ''}`);
+    }, []);
+    /**
+     * Sets the currently active shortcut scope.
+     *
+     * @param {string} scope - The scope name to set as active.
+     */
+    const setScope = React.useCallback((scope) => {
+        managerRef.current?.setActiveScope(scope);
+        log('Scope set to:', scope);
+    }, []);
+    /**
+     * Resets the scope stack to the default state.
+     */
+    const resetScope = React.useCallback(() => {
+        managerRef.current?.resetScope();
+        log('Reset scope');
+    }, []);
+    /**
+     * Returns all scopes in the stack.
+     * @returns An array of scopes.
+     */
+    const getScopes = React.useCallback(() => {
+        return managerRef.current?.getScopes();
+    }, []);
+    /**
+     * Checks if the given scope is active.
+     * @param scope - The scope to check.
+     * @returns `true` if the scope is active, `false` otherwise.
+     */
+    const isScopeActive = React.useCallback((scope) => {
+        return managerRef.current?.isScopeActive(scope);
+    }, []);
+    /**
+     * Registers a callback to be called when a key is typed.
+     * @param callback - The callback function to be called.
+     */
+    const onTyping = React.useCallback((callback) => {
+        managerRef.current?.onTyping(callback);
+    }, []);
+    /**
+     * Pops the last scope from the scope stack.
+     */
+    const popScope = React.useCallback(() => {
+        managerRef.current?.popScope();
+        log('Popped scope, active scope is:', managerRef.current?.getActiveScope());
+    }, []);
+    /**
+     * Pushes a new scope onto the scope stack.
+     * @param scope - The scope to push.
+     */
+    const pushScope = React.useCallback((scope) => {
+        managerRef.current?.pushScope(scope);
+        log('Pushed scope:', scope);
+    }, []);
+    /**
+     * Returns internal information about the registered scopes and shortcuts.
+     *
+     * @param {string} [scope] - Optional scope to filter results.
+     * @returns {Object} Scope information.
+     */
+    const getScopeInfo = React.useCallback((scope) => {
+        return managerRef.current?.getScopesInfo(scope);
+    }, []);
+    /**
+     * Destroys the instance of `ShortcutManager`.
+     * This should be called explicitly when you no longer need the manager.
+     */
+    const destroy = () => {
+        managerRef.current?.destroy();
+    };
+    /**
+     * Clears the internal state, removing all pressed keys and event listeners.
+     * This does not unregister shortcuts.
+     */
+    const clear = () => {
+        managerRef.current?.clear();
+    };
+    return {
+        register,
+        unregister,
+        enable,
+        disable,
+        toggle,
+        setScope,
+        getCheatSheet,
+        destroy,
+        getScopeInfo,
+        getActiveScope,
+        popScope,
+        pushScope,
+        resetScope,
+        getScopes,
+        isScopeActive,
+        onTyping,
+        enableAll,
+        clear,
+        disableAll,
+        manager: managerRef.current,
+    };
+}
+
+export { useKeybindy };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@keybindy/react",
+  "version": "1.0.0",
+  "description": "Keybindy for React: Simple, scoped keyboard shortcuts that require little setup. designed to smoothly blend in with your React applications, allowing for robust keybinding functionality without the overhead.",
+  "author": {
+    "name": "PRASSamin",
+    "url": "https://github.com/prasssamin"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keybindy/react.git"
+  },
+  "homepage": "https://github.com/keybindy/react",
+  "bugs": {
+    "url": "https://github.com/keybindy/react/issues"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.map",
+    "package.json",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "keywords": [
+    "keyboard",
+    "shortcut",
+    "hotkeys",
+    "keybind",
+    "keybinding",
+    "shortcut-manager",
+    "react",
+    "shortcut-engine"
+  ],
+  "scripts": {
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "publish": "npm publish --access public",
+    "prebuild": "rm -rf dist",
+    "build": "rollup -c"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/bun": "latest",
+    "@types/react": "^19.1.2",
+    "prettier": "^3.5.3",
+    "rollup-plugin-dts": "^6.2.1",
+    "tslib": "^2.8.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@keybindy/core": "^1.0.0",
+    "react": "^19.1.0"
+  }
+}