@remcostoeten/use-shortcut 1.3.0 → 2.0.1

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.1] - 2026-03-11
+
+### Fixed
+
+- Re-exported `useShortcutMap`, `registerShortcutMap`, `createShortcutGroup`, and `useShortcutGroup` from the public package entrypoint.
+- Re-exported shortcut map and shortcut group types from the public package entrypoint.
+
+### Changed
+
+- Updated the README to document the public shortcut map API.
+
+## [2.0.0] - 2026-03-04
+
+### Changed
+
+- Removed non-React public entry points (`createShortcut`, `createShortcutMap`) to focus package API on React-first usage.
+
 ## [1.3.0] - 2026-02-28
 
 ### Added

package/README.md

@@ -1,331 +1,89 @@
 # @remcostoeten/use-shortcut
 
-[![npm version](https://img.shields.io/npm/v/@remcostoeten/use-shortcut.svg)](https://www.npmjs.com/package/@remcostoeten/use-shortcut)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+WIP keyboard shortcut library for React with a chainable API.
 
-Chainable keyboard shortcuts for React with **perfect TypeScript intellisense**.
+## Status
 
-[**View Live Demo & Playground**](https://use-shortcuts.vercel.app)
+- Focus right now: runtime architecture and DX refinement
+- Documentation scope: feature/status overview only (full API docs will be expanded later)
 
-```tsx
-const $ = useShortcut()
-
-// Chainable, typesafe, platform-aware
-$.cmd.shift.key("s").on(() => save())
-$.mod.key("k").on(() => search())
-$.key("/").except("typing").on(() => focusSearch())
-```
-
-## Features
-
-- **Chainable API** - Fluent, readable shortcut definitions
-- **Sequences/chords** - Multi-step bindings like `$.key("g").then("d")`
-- **Named scopes** - Activate/deactivate shortcut contexts (`editor`, `navigation`, etc.)
-- **Conflict detection** - Detect exact and sequence-prefix overlaps
-- **Shortcut maps** - Register many shortcuts at once with `useShortcutMap()`
-- **Recording mode** - Capture the next key combo for custom keybind UIs
-- **Priorities** - Deterministic ordering for overlapping shortcuts
-- **Groups** - Register multiple shortcuts and unbind them together
-- **Event filtering** - Global event guard via `eventFilter`
-- **Perfect TypeScript** - Intellisense at every step
-- **Cross-platform** - `mod` = ⌘ on Mac, Ctrl on Windows/Linux
-- **Context-aware** - Skip shortcuts in inputs with `.except()`
-- **Zero dependencies** - Only React as peer dependency
-- **Tiny** - ~3KB gzipped
-
-## Installation
-
-### npm/pnpm/bun
-
-```bash
-npm install @remcostoeten/use-shortcut
-pnpm add @remcostoeten/use-shortcut
-bun add @remcostoeten/use-shortcut
-```
-
-### Copy-paste (shadcn-style)
-
-```bash
-npx @remcostoeten/use-shortcut init
-# or
-bunx @remcostoeten/use-shortcut init
-```
-
-This copies the source files directly into your project at `hooks/use-shortcut/`.
-
-### App Architecture Scaffold (React/Next)
-
-Generate a scalable, reusable shortcut architecture with typed registry, scopes, provider state/actions, and persistent user bindings:
-
-```bash
-# Next.js-oriented scaffold (default)
-npx @remcostoeten/use-shortcut scaffold
-
-# React scaffold
-npx @remcostoeten/use-shortcut scaffold --framework react
-
-# Custom location
-npx @remcostoeten/use-shortcut scaffold --target src --dir shortcuts
-```
-
-Generated structure:
-
-```txt
-src/shortcuts/
-  index.ts
-  provider.tsx
-  registry.ts
-  runtime.ts
-  scopes.ts
-  storage.ts
-  types.ts
-  README.md
-```
-
-Architecture docs:
-- Human guide: [`docs/app-architecture.md`](./docs/app-architecture.md)
-- LLM guide: [`docs/app-architecture.llm.md`](./docs/app-architecture.llm.md)
-
-## Quick Start
-
-```tsx
-"use client"
-
-import { useShortcut } from "@remcostoeten/use-shortcut"
-
-export function App() {
-  const $ = useShortcut()
-
-  $.cmd.key("s").on(() => {
-    console.log("Save!")
-  })
-
-  $.mod.key("k").on(() => {
-    console.log("Search!")
-  })
-
-  return <div>Press ⌘+S or ⌘+K</div>
-}
-```
-
-## API
-
-### Modifiers
-
-Chain modifiers before calling `.key()`:
-
-```tsx
-$.ctrl.key("s")           // Ctrl+S
-$.shift.key("enter")      // Shift+Enter
-$.alt.key("n")            // Alt+N
-$.cmd.key("k")            // ⌘+K (Mac) or Ctrl+K (Windows)
-$.mod.key("k")            // Cross-platform: ⌘ on Mac, Ctrl on Windows/Linux
-
-// Multiple modifiers
-$.ctrl.shift.key("p")     // Ctrl+Shift+P
-$.cmd.shift.alt.key("a")  // ⌘+Shift+Alt+A
-```
-
-### Keys
-
-Supports all standard keys:
-
-```tsx
-// Letters
-$.mod.key("s")            // a-z
-
-// Numbers
-$.mod.key("1")            // 0-9
-
-// Function keys
-$.key("f1")               // f1-f12
-
-// Special keys
-$.key("escape")           // escape, enter, space, tab
-$.key("backspace")        // backspace, delete
-$.mod.key("up")           // up, down, left, right
-$.key("home")             // home, end, pageup, pagedown
-
-// Symbols
-$.mod.key("slash")        // slash, backslash, comma, period
-$.mod.key("/")            // Also works with actual symbol
-```
-
-### Exception Handling
-
-Skip shortcuts in certain contexts:
+## Implemented Features
 
-```tsx
-// Built-in presets
-$.key("/").except("input").on(handler)     // Skip in <input>, <textarea>, <select>
-$.key("/").except("editable").on(handler)  // Skip in contenteditable
-$.key("/").except("typing").on(handler)    // Skip in any text input
-$.key("escape").except("modal").on(handler) // Skip when modal is open
-$.key("enter").except("disabled").on(handler) // Skip on disabled elements
-
-// Multiple presets
-$.key("/").except(["input", "modal"]).on(handler)
-
-// Custom predicate
-$.key("k").except((e) => {
-  return e.target.classList.contains("no-shortcuts")
-}).on(handler)
-```
-
-### Handler Options
-
-```tsx
-$.mod.key("s").on(save, {
-  preventDefault: true,    // Prevent browser default (default: true)
-  stopPropagation: false,  // Stop event bubbling (default: false)
-  delay: 100,              // Delay before firing (ms)
-  description: "Save doc", // For accessibility
-  disabled: false,         // Temporarily disable
-})
-```
-
-### Result Object
+- Chainable shortcut builder: `$.mod.key("k").on(handler)`
+- Bulk shortcut maps: `useShortcutMap()` and `registerShortcutMap()`
+- Modifier support: `ctrl`, `shift`, `alt`, `cmd`, `mod`
+- Sequence support: `$.key("g").then("d")`
+- Scope-aware shortcuts:
+  - Register with `.in("editor")`
+  - Runtime controls: `setScopes`, `enableScope`, `disableScope`, `getScopes`, `isScopeActive`
+- Exception predicates/presets with `.except(...)`
+- Recording mode: `$.record({ timeoutMs })`
+- Conflict detection (`exact`, `sequence-prefix`)
+- Priority ordering and `stopOnMatch`
+- Global guard/filter support via `eventFilter`
+- React entry point:
+  - `useShortcut`
+  - `useShortcutMap`
+  - `useShortcutGroup`
 
-`.on()` returns a result object:
+## API Intention (Consumer-Facing)
 
-```tsx
-const save = $.mod.key("s").on(handleSave)
+- `useShortcut(options?)`
+  - Main React hook. Use this for the chainable API (`$.mod.key("s").on(...)`).
+- `useShortcutMap(shortcutMap, options?)`
+  - React-safe bulk registration for render paths where a declarative object is cleaner than multiple `.on()` calls.
+- `registerShortcutMap(builder, shortcutMap)`
+  - Imperative bulk registration helper when you already have a `useShortcut()` builder.
 
-save.display    // "⌘S" on Mac, "Ctrl+S" on Windows
-save.combo      // "cmd+s"
-save.isEnabled  // true/false
-save.enable()   // Enable the shortcut
-save.disable()  // Disable the shortcut
-save.unbind()   // Remove the shortcut
-save.trigger()  // Programmatically trigger
-```
+Internal helpers follow underscore naming (for example `_createShortcutBuilder`, `_canonicalizeParsed`) and are not re-exported from `src/index.ts`.
 
-### Sequences / Chords
-
-```tsx
-// GitHub-style: press g, then d
-$.key("g").then("d").on(() => goToDashboard())
-
-// Steps can include modifiers too
-$.key("g").then("shift+d").on(() => openDebug())
-```
-
-### Named Scopes
-
-```tsx
-const $ = useShortcut({ activeScopes: "navigation" })
-
-$.in("navigation").key("g").then("d").on(() => goToDashboard())
-$.in("editor").mod.key("s").on(() => saveFile())
-
-$.setScopes("editor")        // enable editor scope only
-$.enableScope("navigation")  // add a second active scope
-$.disableScope("editor")     // remove one scope
-$.getScopes()                // ["navigation"]
-```
-
-### Shortcut Maps
+## Shortcut Map Example
 
 ```tsx
 import { useShortcutMap } from "@remcostoeten/use-shortcut"
 
-useShortcutMap({
-  save: { keys: "mod+s", handler: () => save() },
-  undo: { keys: "mod+z", handler: () => undo() },
-  dashboard: { keys: ["g", "d"], handler: () => goToDashboard() },
-})
-```
-
-### Recording Mode
-
-```tsx
-const combo = await $.record({ timeoutMs: 5000 })
-// e.g. "ctrl+k" or "cmd+k"
-```
-
-### Shortcut Groups
-
-```tsx
-import { createShortcutGroup } from "@remcostoeten/use-shortcut"
-
-const group = createShortcutGroup()
-
-group.add($.mod.key("k").on(openPalette))
-group.add($.mod.key("p").on(openSearch))
-
-// Later, cleanup all at once
-group.unbindAll()
-```
-
-### Hook Options
-
-```tsx
-const $ = useShortcut({
-  debug: true,           // Log all shortcuts to console
-  delay: 0,              // Global delay for all shortcuts
-  ignoreInputs: true,    // Ignore in form elements (default: true)
-  disabled: false,       // Disable all shortcuts
-  eventType: "keydown",  // or "keyup"
-  target: window,        // Custom event target
-  activeScopes: "editor", // Active named scopes
-  sequenceTimeout: 800,   // ms to complete sequence
-  conflictWarnings: true, // Warn on overlaps
-  onConflict: (conflict) => {
-    console.warn(conflict)
-  },
-  eventFilter: (event) => !event.isComposing,
-})
-```
-
-### Handler Options (Advanced)
-
-```tsx
-$.mod.key("k").on(openPalette, {
-  priority: 10,      // higher runs first
-  stopOnMatch: true, // prevent lower priority handlers from running
-})
-```
-
-## Vanilla JS (Non-React)
-
-```tsx
-import { createShortcut } from "@remcostoeten/use-shortcut"
-
-const $ = createShortcut()
-
-const save = $.mod.key("s").on(() => {
-  console.log("Saved!")
-})
-
-// Clean up when done
-save.unbind()
+function App() {
+  useShortcutMap(
+    {
+      openPalette: {
+        keys: "mod+k",
+        handler: () => openPalette(),
+        options: { preventDefault: true },
+      },
+      closePalette: {
+        keys: "escape",
+        handler: () => closePalette(),
+      },
+      toggleSidebar: {
+        keys: "g then s",
+        handler: () => toggleSidebar(),
+      },
+    },
+    { ignoreInputs: false },
+  )
+
+  return <div>Shortcuts ready</div>
+}
 ```
 
-## Display Formatting
-
-```tsx
-import { formatShortcut } from "@remcostoeten/use-shortcut"
+If you already have a builder from `useShortcut()`, you can bulk register with `registerShortcutMap($, shortcutMap)` and unbind the returned handles on cleanup.
 
-formatShortcut("cmd+s")        // "⌘S" on Mac, "Ctrl+S" on Windows
-formatShortcut("ctrl+shift+p") // "⌃⇧P" on Mac, "Ctrl+Shift+P" on Windows
-```
+## Architecture Notes
 
-## TypeScript
+- Core runtime lives in `src/builder.ts`
+- Parsing/formatting are isolated in `src/parser.ts` and `src/formatter.ts`
+- React bindings and map helpers live in `src/hook.ts`
+- Type contracts live in `src/types.ts`
+- CLI scaffold/copy commands live under `cli/`
 
-Full type definitions with intellisense:
+## Development
 
-```tsx
-import type {
-  ShortcutBuilder,
-  ShortcutResult,
-  ShortcutHandler,
-  HandlerOptions,
-  ActionKey,
-  ModifierName,
-} from "@remcostoeten/use-shortcut"
+```bash
+bun run typecheck
+bun run test
+bun run build
 ```
 
 ## License
 
-MIT © Remco Stoeten
+MIT