@solid-primitives/keyboard 2.0.0-next.1 → 2.0.0-next.2

package/README.md

@@ -156,6 +156,7 @@ Creates a keyboard shortcut observer. The provided callback will be called when
 - `options` — additional configuration:
   - `preventDefault` — call `e.preventDefault()` on the keyboard event, when the specified key is pressed. _(Defaults to `true`)_
   - `requireReset` — If `true`, the shortcut will only be triggered once until all of the keys stop being pressed. Disabled by default.
+  - `ignoreWithinInputs` — If `true`, the shortcut is ignored while focus is on an `input`, `textarea`, `select`, or `contenteditable` element, so it doesn't interrupt typing. Disabled by default.
 
 ```tsx
 import { createShortcut } from "@solid-primitives/keyboard";
@@ -175,6 +176,17 @@ When `preventDefault` is `true`, `e.preventDefault()` will be called not only on
 
 E.g. when listening for `Control + Shift + A`, all three keydown events will be prevented.
 
+### Ignoring shortcuts while typing
+
+Single, unmodified-key shortcuts (e.g. `["S"]`) conflict with typing — pressing "s" in a text field would both type the character and trigger the shortcut. Set `ignoreWithinInputs: true` to skip the shortcut entirely while focus is on a form control or `contenteditable` element:
+
+```tsx
+// won't fire while the user is typing in a text field
+createShortcut(["S"], () => console.log("S was pressed"), { ignoreWithinInputs: true });
+```
+
+Combos that include a modifier (e.g. `Control + S`) don't have this problem, since the modifier itself prevents a character from being typed — `ignoreWithinInputs` is usually unnecessary for those.
+
 ## `createKeyDown`
 
 Listens for a `keydown` event for a specific key on a document. Useful for global keyboard handlers that need to respond to a single key without setting up a full shortcut.

package/dist/index.d.ts

@@ -131,17 +131,25 @@ export declare function createKeyHold(key: KbdKey, options?: {
  * @param options The options for the shortcut.
  * - `preventDefault` — Controls if the keydown event should have its default action prevented. Enabled by default.
  * - `requireReset` — If `true`, the shortcut will only be triggered once until all of the keys stop being pressed. Disabled by default.
+ * - `ignoreWithinInputs` — If `true`, the shortcut is ignored while focus is on an `input`, `textarea`, `select`,
+ *   or `contenteditable` element, so typing isn't interrupted. Disabled by default — enable it for shortcuts
+ *   made of plain, unmodified keys (e.g. a single letter); combos like `Control+S` are usually fine either way,
+ *   since the modifier prevents a character from being typed.
  *
  * @example
  * ```ts
  * createShortcut(["CONTROL", "SHIFT", "C"], () => {
  *    console.log("Ctrl+Shift+C was pressed");
  * });
+ *
+ * // won't fire while typing in a text field
+ * createShortcut(["S"], () => console.log("S was pressed"), { ignoreWithinInputs: true });
  * ```
  */
 export declare function createShortcut(keys: KbdKey[], callback: (event: KeyboardEvent | null) => void, options?: {
     preventDefault?: boolean;
     requireReset?: boolean;
+    ignoreWithinInputs?: boolean;
 }): void;
 export interface CreateKeyDownOptions {
     /** Whether the listener should be inactive. */

package/dist/index.js

@@ -11,6 +11,19 @@ function equalsKeyHoldSequence(sequence, model) {
     }
     return true;
 }
+/** Is the event target an editable form control, or inside a `contenteditable` element? */
+function isEditableTarget(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    switch (target.tagName) {
+        case "INPUT":
+        case "TEXTAREA":
+        case "SELECT":
+            return true;
+        default:
+            return target.isContentEditable;
+    }
+}
 /**
  * Provides a signal with the last keydown event.
  *
@@ -244,12 +257,19 @@ export function createKeyHold(key, options = {}) {
  * @param options The options for the shortcut.
  * - `preventDefault` — Controls if the keydown event should have its default action prevented. Enabled by default.
  * - `requireReset` — If `true`, the shortcut will only be triggered once until all of the keys stop being pressed. Disabled by default.
+ * - `ignoreWithinInputs` — If `true`, the shortcut is ignored while focus is on an `input`, `textarea`, `select`,
+ *   or `contenteditable` element, so typing isn't interrupted. Disabled by default — enable it for shortcuts
+ *   made of plain, unmodified keys (e.g. a single letter); combos like `Control+S` are usually fine either way,
+ *   since the modifier prevents a character from being typed.
  *
  * @example
  * ```ts
  * createShortcut(["CONTROL", "SHIFT", "C"], () => {
  *    console.log("Ctrl+Shift+C was pressed");
  * });
+ *
+ * // won't fire while typing in a text field
+ * createShortcut(["S"], () => console.log("S was pressed"), { ignoreWithinInputs: true });
  * ```
  */
 export function createShortcut(keys, callback, options = {}) {
@@ -257,7 +277,7 @@ export function createShortcut(keys, callback, options = {}) {
         return;
     }
     keys = keys.map(key => key.toUpperCase());
-    const { preventDefault = true, requireReset = false } = options;
+    const { preventDefault = true, requireReset = false, ignoreWithinInputs = false } = options;
     // Track pressed keys and sequence locally with plain JS state rather than
     // reactive signals. A signal reads from event listeners return
     // the pre-batch committed value, so synchronous shortcut checking requires
@@ -273,6 +293,8 @@ export function createShortcut(keys, callback, options = {}) {
     makeEventListener(window, "keydown", (e) => {
         if (e.repeat || typeof e.key !== "string")
             return;
+        if (ignoreWithinInputs && isEditableTarget(e.target))
+            return;
         const key = e.key.toUpperCase();
         if (!pressedKeys.includes(key)) {
             const newKeys = [...pressedKeys];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solid-primitives/keyboard",
-  "version": "2.0.0-next.1",
+  "version": "2.0.0-next.2",
   "description": "A library of reactive promitives helping handling user's keyboard input.",
   "author": "Damian Tarnwski <gthetarnav@gmail.com>",
   "contributors": [],