@joknoll/svelte-attach-key 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @joknoll/svelte-attach-key
+
+Svelte 5 attachments for wiring keyboard shortcuts to DOM elements.
+
+## Installation
+
+```
+npm install @joknoll/svelte-attach-key
+```
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { hotkey, pressed, formatHint } from "@joknoll/svelte-attach-key";
+</script>
+
+<button
+  {@attach hotkey("mod+k")}
+  onclick={() => console.log("opened")}
+>
+  Open command menu
+</button>
+```
+
+`hotkey("mod+k")` sets `aria-keyshortcuts="mod+k"` on the element automatically. `pressed()` reads it back to know which key to watch.
+
+Pass alternative shortcuts as an array — either key triggers the element:
+
+```svelte
+<button
+  title={formatHint(["j", "arrowdown"])}
+  {@attach hotkey(["j", "arrowdown"])}
+>
+  Move down
+</button>
+```
+
+Attach a callback instead of relying on `click`:
+
+```svelte
+<button {@attach hotkey("mod+s", (e) => save())}>Save</button>
+```
+
+Conditional attachment:
+
+```svelte
+<button {@attach enabled && hotkey("k")}>Press K</button>
+```
+
+## API
+
+### `hotkey(keys, onTrigger?, options?)`
+
+Triggers `onTrigger` (or `node.click()`) when a matching key is pressed. Sets `aria-keyshortcuts` on the element and restores the prior value on cleanup.
+
+| Parameter                 | Type                                            | Default        |
+| ------------------------- | ----------------------------------------------- | -------------- |
+| `keys`                    | `string \| string[]`                            | required       |
+| `onTrigger`               | `(e: KeyboardEvent, node: HTMLElement) => void` | `node.click()` |
+| `options.preventDefault`  | `boolean`                                       | `true`         |
+| `options.stopPropagation` | `boolean`                                       | `false`        |
+| `options.ignoreInputs`    | `boolean`                                       | `true`         |
+| `options.ignoreRepeat`    | `boolean`                                       | `true`         |
+
+Shortcut strings: `k`, `ctrl+s`, `shift+space`, `mod+/`. `mod` resolves to `⌘` on Mac and `Ctrl` elsewhere.
+
+### `pressed(keys?, className?)`
+
+Adds `className` while a matching key is held, removes it on keyup. If `keys` is omitted, reads from `aria-keyshortcuts` (set by `hotkey`).
+
+| Parameter   | Type                 | Default                   |
+| ----------- | -------------------- | ------------------------- |
+| `keys`      | `string \| string[]` | reads `aria-keyshortcuts` |
+| `className` | `string`             | `"is-pressed"`            |
+
+### `formatHint(keys)`
+
+Formats a shortcut for display. `mod+s` → `⌘ S` on Mac, `Ctrl + S` on PC.
+
+```ts
+formatHint("mod+s"); // "⌘ S" / "Ctrl + S"
+formatHint(["j", "down"]); // "J / Down"
+```
+
+### `addTransform(fn)`
+
+Registers a transform applied before parsing and formatting. Returns a remover function.
+
+```ts
+const remove = addTransform((s) => s.replaceAll("primary", "mod"));
+```
+
+### `likelyWithKeyboard()`
+
+Returns `true` when the primary pointer is not coarse (i.e. likely has a keyboard). Use to conditionally render shortcut hints.
+
+## Notes
+
+- Shortcuts are global by default (fire regardless of which element has focus).
+- Inputs, textareas, selects, and `contenteditable` are ignored by default.
+- Add `data-keyshortcuts-ignore` to a container to suppress shortcuts while focus is inside that subtree.

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { Attachment } from "svelte/attachments";
+
+//#region src/attachments.d.ts
+interface HotkeyOptions {
+  preventDefault?: boolean;
+  stopPropagation?: boolean;
+  ignoreInputs?: boolean;
+  ignoreRepeat?: boolean;
+}
+type HotkeyTrigger = (e: KeyboardEvent, node: HTMLElement) => void;
+/**
+ * Attachment that fires `onTrigger` (or `node.click()`) when one of `keys` is pressed.
+ * Sets `aria-keyshortcuts` on the element and restores the prior value on cleanup.
+ *
+ * @example
+ * ```svelte
+ * <button {@attach hotkey("mod+s", save)}>Save</button>
+ * ```
+ */
+declare function hotkey(keys: string | string[], onTrigger?: HotkeyTrigger, options?: HotkeyOptions): Attachment<HTMLElement>;
+/**
+ * Attachment that adds `className` while one of `keys` is held, removes it on keyup.
+ * If `keys` is omitted, reads the shortcut from `aria-keyshortcuts` (set by `hotkey`).
+ *
+ * @example
+ * ```svelte
+ * <button {@attach hotkey("mod+s", save)} {@attach pressed("mod+s")}>Save</button>
+ * ```
+ */
+declare function pressed(keys?: string | string[], className?: string): Attachment<HTMLElement>;
+//#endregion
+//#region src/hint.d.ts
+/**
+ * Format a shortcut string (or array of alternatives) into a human-readable hint.
+ *
+ * @example
+ * formatHint("mod+s")         // → "⌘ S" on Mac, "Ctrl + S" on PC
+ * formatHint(["j", "down"])   // → "J / Down"
+ */
+declare function formatHint(shortcut: string | string[]): string;
+/** Returns true when the primary pointing device is likely a mouse/trackpad (not touch-only). SSR-safe. */
+declare function likelyWithKeyboard(): boolean;
+//#endregion
+//#region src/dispatcher.d.ts
+type Transform = (shortcut: string) => string;
+declare function addTransform(fn: Transform): () => void;
+//#endregion
+export { type HotkeyOptions, type HotkeyTrigger, addTransform, formatHint, hotkey, likelyWithKeyboard, pressed };

package/dist/index.js

@@ -0,0 +1 @@
+import{on as e}from"svelte/events";const t={esc:`escape`,return:`enter`,del:`delete`,space:` `,up:`arrowup`,down:`arrowdown`,left:`arrowleft`,right:`arrowright`,option:`alt`,command:`meta`,win:`meta`,plus:`+`},n=new Set([`ctrl`,`shift`,`alt`,`meta`,`cmd`,`mod`]),r=typeof navigator<`u`&&/Mac|iPod|iPhone|iPad/.test(navigator.userAgent);function i(e){let n=e.toLowerCase();return t[n]??n}function a(e){let t=e.split(`+`).map(e=>i(e.trim())).filter(Boolean),a={key:``,ctrl:!1,shift:!1,alt:!1,meta:!1};for(let e of t){if(!n.has(e)){a.key=e;continue}e===`ctrl`?a.ctrl=!0:e===`shift`?a.shift=!0:e===`alt`?a.alt=!0:e===`meta`||e===`cmd`?a.meta=!0:e===`mod`&&(r?a.meta=!0:a.ctrl=!0)}return a}function o(e){return e.trim().split(/\s+/).filter(Boolean).map(a)}function s(e){return Array.isArray(e)?e.join(` `):e}function c(e,t){return i(e.key)===t.key&&e.ctrlKey===t.ctrl&&e.shiftKey===t.shift&&e.altKey===t.alt&&e.metaKey===t.meta}const l=new Set([`INPUT`,`TEXTAREA`,`SELECT`]),u=new Set,d=[];let f=null;const p=e=>{let t=e.target;return!!t&&(l.has(t.tagName)||t.isContentEditable)},m=e=>{let t=e.target.parentElement;for(;t;){if(t.hasAttribute(`data-keyshortcuts-ignore`))return document.activeElement!==t;t=t.parentElement}return!1},h=e=>{let t;for(let n of u)n.ignoreRepeat&&e.repeat||n.ignoreInputs&&p(e)||(t??=m(e),!t&&n.shortcuts.some(t=>c(e,t))&&n.handler(e))};function g(t){return u.size===0&&(f=e(window,`keydown`,h)),u.add(t),()=>{u.delete(t),u.size===0&&f&&(f(),f=null)}}function _(e){return d.push(e),()=>{let t=d.indexOf(e);t!==-1&&d.splice(t,1)}}function v(e){return d.reduce((e,t)=>t(e),e)}function y(e){return o(v(e))}function b(e,t,n){return r=>{let{preventDefault:i=!0,stopPropagation:a=!1,ignoreInputs:o=!0,ignoreRepeat:c=!0}=n??{},l=s(e),u=r.getAttribute(`aria-keyshortcuts`);r.setAttribute(`aria-keyshortcuts`,l);let d=g({shortcuts:y(l),handler:e=>{i&&e.preventDefault(),a&&e.stopPropagation(),t?t(e,r):r.click()},ignoreInputs:o,ignoreRepeat:c});return()=>{d(),u===null?r.removeAttribute(`aria-keyshortcuts`):r.setAttribute(`aria-keyshortcuts`,u)}}}function x(t,n=`is-pressed`){return r=>{let i=t===void 0?r.getAttribute(`aria-keyshortcuts`)??``:s(t);if(!i)return;let a=y(i),o=!1,l=()=>{o=!1,r.classList.remove(n)},u=g({shortcuts:a,handler:()=>{o=!0,r.classList.add(n)},ignoreInputs:!0,ignoreRepeat:!0}),d=e(window,`keyup`,e=>{o&&a.some(t=>c(e,t))&&l()}),f=e(window,`blur`,l);return()=>{u(),d(),f(),l()}}}const S={ctrl:[`⌃`,`Ctrl`],shift:[`⇧`,`Shift`],alt:[`⌥`,`Alt`],meta:[`⌘`,`Win`]},C={" ":`Space`,arrowup:`Up`,arrowdown:`Down`,arrowleft:`Left`,arrowright:`Right`,escape:`Esc`,enter:`Enter`,delete:`Delete`,backspace:`Backspace`,tab:`Tab`,home:`Home`,end:`End`,pageup:`PageUp`,pagedown:`PageDown`},w=typeof window<`u`?matchMedia(`(pointer: coarse)`):null;function T(e){return y(s(e)).map(e=>{let t=[];for(let n of[`ctrl`,`shift`,`alt`,`meta`])e[n]&&t.push(S[n][+!r]);let n=e.key;return t.push(C[n]??(n.length===1?n.toUpperCase():n)),t.join(r?` `:` + `)}).join(` / `)}function E(){return w?!w.matches:!1}export{_ as addTransform,T as formatHint,b as hotkey,E as likelyWithKeyboard,x as pressed};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@joknoll/svelte-attach-key",
+  "version": "0.1.0",
+  "description": "A Svelte attachment for binding keyboard shortcuts to DOM elements.",
+  "keywords": [
+    "attachment",
+    "hotkey",
+    "key",
+    "keymap",
+    "svelte",
+    "svelte5"
+  ],
+  "homepage": "https://github.com/joknoll/svelte-attach/tree/main/packages/key#readme",
+  "bugs": {
+    "url": "https://github.com/joknoll/svelte-attach/issues"
+  },
+  "license": "MIT",
+  "author": "joknoll",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joknoll/svelte-attach.git",
+    "directory": "packages/key"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "bumpp": "^11.1.0",
+    "svelte": "^5.55.0",
+    "typescript": "^6.0.3",
+    "vite-plus": "latest"
+  },
+  "peerDependencies": {
+    "svelte": ">=5.55.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test --passWithNoTests",
+    "check": "vp check"
+  }
+}