@ramstack/alpinegear-typegrab 1.4.0

package/README.md

@@ -0,0 +1,77 @@
+# @ramstack/alpinegear-typegrab
+
+[![NPM](https://img.shields.io/npm/v/@ramstack/alpinegear-typegrab)](https://www.npmjs.com/package/@ramstack/alpinegear-typegrab)
+[![MIT](https://img.shields.io/github/license/rameel/ramstack.alpinegear.js)](https://github.com/rameel/ramstack.alpinegear.js/blob/main/LICENSE)
+
+`@ramstack/alpinegear-typegrab` is a lightweight plugin for [Alpine.js](https://alpinejs.dev/) that provides the `x-typegrab` directive.
+
+The directive automatically focuses an element when the user starts typing **any printable, non-whitespace character**,
+as long as no editable element is currently focused. This is useful for search inputs, command palettes,
+and similar UX patterns where typing should immediately direct input to a specific field.
+
+## How it works
+
+* Listens globally to the `keydown` event.
+* Triggers only for **printable, non-whitespace characters**.
+* Ignores events with `Ctrl`, `Alt`, or `Meta` modifiers.
+* Does nothing if the active element is `input`, `textarea`, or an element with `contenteditable`.
+* Focuses the element marked with `x-typegrab`.
+
+## Installation
+
+### Using CDN
+
+```html
+<!-- alpine.js plugin -->
+<script src="https://cdn.jsdelivr.net/npm/@ramstack/alpinegear-typegrab@1/alpinegear-typegrab.min.js" defer></script>
+
+<!-- alpine.js -->
+<script src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js" defer></script>
+```
+
+### Using NPM
+
+```bash
+npm install --save @ramstack/alpinegear-typegrab
+```
+
+```js
+import Alpine from "alpinejs";
+import Typegrab from "@ramstack/alpinegear-typegrab";
+
+Alpine.plugin(Typegrab);
+Alpine.start();
+```
+
+## Usage
+
+```html
+<input
+  type="search"
+  placeholder="Type to search..."
+  x-typegrab
+/>
+```
+
+When the user presses any printable character key (excluding whitespace) while no other editable element is focused,
+this input will automatically receive focus.
+
+## Notes
+
+* The directive does not cancel or modify the original keyboard event.
+* The target element must be focusable.
+* Focus will not be stolen from active editable elements.
+
+## Source code
+
+You can find the source code for this plugin on GitHub:
+https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/typegrab
+
+## Contributions
+
+Bug reports and contributions are welcome.
+
+## License
+
+This package is released as open source under the **MIT License**.
+See the [LICENSE](https://github.com/rameel/ramstack.alpinegear.js/blob/main/LICENSE) file for more details.

package/alpinegear-typegrab.esm.js

@@ -0,0 +1,34 @@
+const listen = (target, type, listener, options) => {
+    target.addEventListener(type, listener, options);
+    return () => target.removeEventListener(type, listener, options);
+};
+
+const matches = (el, selector) => el.matches(selector);
+
+const is_active_element_editable = () => {
+    const el = document.activeElement;
+    if (el === document.body || !el) {
+        return false;
+    }
+
+    return matches(el, "input")
+        || matches(el, "textarea")
+        || el.isContentEditable;
+};
+
+const is_printable_key_pressed = ({ key, metaKey, ctrlKey, altKey }) =>
+    !metaKey && !ctrlKey && !altKey && /^[^\p{M}\p{Z}\p{C}]$/u.test(key);
+
+function plugin({ directive }) {
+    directive("typegrab", (el, _, { cleanup }) => {
+        cleanup(
+            listen(document, "keydown", e => {
+                if (!is_active_element_editable() && is_printable_key_pressed(e)) {
+                    el.focus();
+                }
+            }, { passive: true })
+        );
+    });
+}
+
+export { plugin as typegrab };

package/alpinegear-typegrab.esm.min.js

@@ -0,0 +1 @@
+const e=(e,t)=>e.matches(t);function t({directive:t}){t("typegrab",(t,n,{cleanup:a})=>{var o,c,r;a(((o=document).addEventListener("keydown",c=n=>{!(()=>{const t=document.activeElement;return!(t===document.body||!t)&&(e(t,"input")||e(t,"textarea")||t.isContentEditable)})()&&(({key:e,metaKey:t,ctrlKey:n,altKey:a})=>!t&&!n&&!a&&/^[^\p{M}\p{Z}\p{C}]$/u.test(e))(n)&&t.focus()},r={passive:!0}),()=>o.removeEventListener("keydown",c,r)))})}export{t as typegrab};

package/alpinegear-typegrab.js

@@ -0,0 +1,39 @@
+(function () {
+    'use strict';
+
+    const listen = (target, type, listener, options) => {
+        target.addEventListener(type, listener, options);
+        return () => target.removeEventListener(type, listener, options);
+    };
+
+    const matches = (el, selector) => el.matches(selector);
+
+    const is_active_element_editable = () => {
+        const el = document.activeElement;
+        if (el === document.body || !el) {
+            return false;
+        }
+
+        return matches(el, "input")
+            || matches(el, "textarea")
+            || el.isContentEditable;
+    };
+
+    const is_printable_key_pressed = ({ key, metaKey, ctrlKey, altKey }) =>
+        !metaKey && !ctrlKey && !altKey && /^[^\p{M}\p{Z}\p{C}]$/u.test(key);
+
+    function plugin({ directive }) {
+        directive("typegrab", (el, _, { cleanup }) => {
+            cleanup(
+                listen(document, "keydown", e => {
+                    if (!is_active_element_editable() && is_printable_key_pressed(e)) {
+                        el.focus();
+                    }
+                }, { passive: true })
+            );
+        });
+    }
+
+    document.addEventListener("alpine:init", () => { Alpine.plugin(plugin); });
+
+})();

package/alpinegear-typegrab.min.js

@@ -0,0 +1 @@
+!function(){"use strict";const e=(e,t)=>e.matches(t);function t({directive:t}){t("typegrab",(t,n,{cleanup:i})=>{var c,a,o;i(((c=document).addEventListener("keydown",a=n=>{!(()=>{const t=document.activeElement;return!(t===document.body||!t)&&(e(t,"input")||e(t,"textarea")||t.isContentEditable)})()&&(({key:e,metaKey:t,ctrlKey:n,altKey:i})=>!t&&!n&&!i&&/^[^\p{M}\p{Z}\p{C}]$/u.test(e))(n)&&t.focus()},o={passive:!0}),()=>c.removeEventListener("keydown",a,o)))})}document.addEventListener("alpine:init",()=>{Alpine.plugin(t)})}();

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@ramstack/alpinegear-typegrab",
+  "version": "1.4.0",
+  "description": "@ramstack/alpinegear-typegrab provides the x-typegrab Alpine.js directive, which automatically focuses an element when the user starts typing and no editable element is active.",
+  "author": "Rameel Burhan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rameel/ramstack.alpinegear.js.git",
+    "directory": "src/plugins/typegrab"
+  },
+  "keywords": [
+    "alpine.js",
+    "alpinejs",
+    "alpinejs-directive",
+    "alpinejs-plugin",
+    "keyboard",
+    "focus",
+    "ux"
+  ],
+  "main": "alpinegear-typegrab.js",
+  "module": "alpinegear-typegrab.esm.js"
+}