use-kbd 0.3.0 → 0.5.0

package/README.md

@@ -2,49 +2,42 @@
 
 [![npm version](https://img.shields.io/npm/v/use-kbd.svg)](https://www.npmjs.com/package/use-kbd)
 
-React library for keyboard-accessible web applications with:
+Keyboard shortcuts, navigation, omnibar for React apps.
 
-1. **Drop-in UI components** (`ShortcutsModal`, `Omnibar`, `SequenceModal`) at the App level
-2. **Minimal-boilerplate action registration** via `useAction` hook, colocated with handlers
-3. **CSS variables** for easy theming customization
+**[📖 Documentation & Demos →][kbd.rbw.sh]**
 
-Try "?" or "⌘-K" at:
-- [ctbk.dev]
-- [awair.runsascoded.com]
-
-## Inspiration
-- macOS (⌘-/) and GDrive (⌥-/) menu search
-- [Superhuman] omnibar
-- Android searchable settings
-- [Vimium] keyboard-driven browsing.
+Also in production at [ctbk.dev] and [awair.runsascoded.com].
 
+[kbd.rbw.sh]: https://kbd.rbw.sh
 [ctbk.dev]: https://ctbk.dev
 [awair.runsascoded.com]: https://awair.runsascoded.com
-[Superhuman]: https://superhuman.com
-[Vimium]: https://github.com/philc/vimium
 
 ## Quick Start
 
+```bash
+npm install use-kbd  # or: pnpm add use-kbd
+```
+
 ```tsx
-import { HotkeysProvider, ShortcutsModal, Omnibar, SequenceModal, useAction } from 'use-kbd'
+import { HotkeysProvider, ShortcutsModal, Omnibar, LookupModal, SequenceModal, useAction } from 'use-kbd'
 import 'use-kbd/styles.css'
 
 function App() {
   return (
     <HotkeysProvider>
-      {/* Your app content */}
       <Dashboard />
-      {/* Drop-in UI components */}
-      <ShortcutsModal />
-      <Omnibar />
-      <SequenceModal />
+      <ShortcutsModal />  {/* "?" modal: view/edit key-bindings */}
+      <Omnibar />         {/* "⌘K" omnibar: search and select actions */}
+      <LookupModal />     {/* "⌘⇧K": look up actions by key-binding */}
+      <SequenceModal />   {/* Inline display for key-sequences in progress */}
     </HotkeysProvider>
   )
 }
 
 function Dashboard() {
-  const { save, exportData } = useDocument()
+  const { save } = useDocument()  // Function to expose via hotkeys / omnibar
 
+  // Wrap function as "action", with keybinding(s) and omnibar keywords
   useAction('doc:save', {
     label: 'Save document',
     group: 'Document',
@@ -52,24 +45,20 @@ function Dashboard() {
     handler: save,
   })
 
-  useAction('doc:export', {
-    label: 'Export data',
-    group: 'Document',
-    defaultBindings: ['meta+e'],
-    handler: exportData,
-  })
-
   return <Editor />
 }
 ```
 
-Press `?` to see the shortcuts modal, or `⌘K` to open the omnibar.
+### Basic steps
 
-## Installation
-
-```bash
-pnpm add use-kbd
-```
+1. **Drop-in UI components**:
+   - `ShortcutsModal`: view/edit key-bindings
+   - `Omnibar`: search and select actions
+   - `LookupModal`: look up actions by key-binding
+   - `SequenceModal`: autocomplete multi-key sequences
+   - `ActionLink`: register links as actions
+2. **Register functions as "actions"** with `useAction`
+3. **Easy theming** with CSS variables
 
 ## Core Concepts
 
@@ -118,7 +107,7 @@ Wrap your app to enable the hotkeys system:
   storageKey: 'use-kbd',      // localStorage key for user overrides (default)
   modalTrigger: '?',          // Open shortcuts modal (default; false to disable)
   omnibarTrigger: 'meta+k',   // Open omnibar (default; false to disable)
-  sequenceTimeout: 1000,      // ms before sequence times out (default)
+  sequenceTimeout: Infinity,  // ms before sequence times out (default: no timeout)
 }}>
   {children}
 </HotkeysProvider>
@@ -211,6 +200,16 @@ const { isRecording, startRecording, display } = useRecordHotkey({
 
 Wraps `useHotkeys` with localStorage persistence and conflict detection.
 
+## Inspiration
+
+- macOS and GDrive menu search
+- [Superhuman] omnibar
+- [Vimium] keyboard-driven browsing
+- Android searchable settings
+
+[Superhuman]: https://superhuman.com
+[Vimium]: https://github.com/philc/vimium
+
 ## License
 
 MIT