docs: tweak doc comments and add content to README

README.md

@@ -1,3 +1,52 @@
 # @laserware/keytar
 
 Handle keyboard and mouse events in the browser.
+Check out the [documentation](https://laserware.github.io/keytar/) for the API.
+
+## Overview
+
+This library uses bitflags to check for mouse and keyboard event conditions.
+If you're interested in how I implemented it and the reasoning behind it, check out [this blog post I wrote](https://mikerourke.dev/blog/bitwisdom-keyboard-shortcuts/).
+
+Here's what this looks like in practice:
+
+```ts
+import { handleChords, Key, Modifier } from "@laserware/keytar";
+
+function handleKeyDown(event: KeyboardEvent): void {
+  const isShiftDown = (event: KeyboardEvent): boolean => {
+    return event.shiftKey;
+  };
+
+  const isCtrlDown = (event: KeyboardEvent): boolean => {
+    return event.ctrlKey;
+  };
+
+  handleChords(event, (handler) => {
+    handler
+      .on(Key.LetterE, () => {
+        // This is fired _only_ when the letter "E" is pressed.
+        // If Shift + E is pressed, this condition won't be hit.
+      })
+      .on(Modifier.Ctrl | Key.LetterK, () => {
+        // This is fired _only_ when Ctrl + K is pressed.
+      })
+      .on([Modifier.Ctrl | Key.LetterP, Modifier.Ctrl | Key.LetterQ], () => {
+        // This is fired _only_ when Ctrl + P _or_ Ctrl + Q is pressed.
+      })
+      // Pass a function reference that returns a boolean
+      // (first arg is the Event):
+      .when(isShiftDown, () => {
+        // This is fired whenever the Shift key is pressed.
+      })
+      // Call the function directly and return a boolean:
+      .when(isCtrlDown(event), () => {
+        // This is fired whenever the Ctrl key is pressed.
+      })
+      // Or just specify a boolean condition:
+      .when(event.altKey, () => {
+        // This is fired whenever the Alt key is pressed.
+      })
+  });
+}
+```

src/common.ts

@@ -19,7 +19,7 @@ export function stripToken(chord: Chord, token: Token): number {
 }
 
 /**
- * Returns true if the specified `chord` includes the specified `token`.
+ * Checks if the specified `chord` includes the specified `token`.
  *
  * @internal
  *
@@ -33,8 +33,8 @@ export function hasTokenInChord(chord: Chord, token: Token): boolean {
 }
 
 /**
- * Returns a valid key that can be used to look up the corresponding enum value
- * in the lookup table.
+ * Tries to find a valid key that can be used to look up the corresponding enum
+ * value in the lookup table.
  *
  * @internal
  *

src/getChordDisplay.ts

@@ -90,6 +90,8 @@ export function getChordDisplay(
 /**
  * Creates a Set with the {@linkcode Token} elements extracted from the specified `chord`.
  *
+ * @internal
+ *
  * @param chord Combination of {@linkcode Token} elements to extra into individual tokens.
  *
  * @returns A Set of unique tokens extracted from the specified `chord`.
@@ -133,6 +135,8 @@ function chordToTokens(chord: Chord): TokenSet {
  * Creates a Set with the tokens extracted from the specified keyboard or mouse
  * `event`.
  *
+ * @internal
+ *
  * @param event Keyboard or mouse event to extract tokens from.
  *
  * @returns A Set of unique tokens extracted from the specified `chord`.

src/handleChords.ts

@@ -32,7 +32,7 @@ export interface ChordHandler<E extends ChordedEvent> {
   /**
    * Fired when the specified chord or array of chords is pressed.
    *
-   * @param chords Single chord or array of chords that represent a combination of {@link Token}
+   * @param chords Single chord or array of chords that represent a combination of {@linkcode Token}
    *               elements that meet the conditions in the specified event.
    * @param listener Callback to fire if a chord match is found.
    */
@@ -66,7 +66,7 @@ export type ChordHandlerBuilder<E extends ChordedEvent> = (
  * @template E Keyboard or mouse event.
  *
  * @param event Keyboard or mouse event from an event listener.
- * @param chords Single chord or array of chords that represent a combination of {@link Token}
+ * @param chords Single chord or array of chords that represent a combination of {@linkcode Token}
  *               elements that meet the conditions in the specified event.
  * @param listener Callback to fire if a chord match is found.
  *
@@ -101,8 +101,9 @@ export function handleChords<E extends ChordedEvent>(
 ): void;
 
 /**
- * Fires the handlers that map to the specified combination of {@link Token} elements
- * or conditions for the specified keyboard or mouse event.
+ * Fires the handlers that map to the specified `builder` describing the
+ * combinations of {@linkcode Token} elements or conditions for the
+ * specified keyboard or mouse `event`.
  *
  * @template E Keyboard or mouse event.
  *

src/isChordPressed.ts

@@ -11,8 +11,8 @@ import {
 } from "./types.ts";
 
 /**
- * Checks if one of the specified {@linkcode Chord} combinations were pressed
- * based on the specified keyboard or mouse `event`.
+ * Checks if one of the specified `chords` combinations were pressed based on
+ * the specified keyboard or mouse `event`.
  *
  * @param event Keyboard or mouse event from an event listener.
  * @param chords Combination of {@linkcode Token} elements to check for from the event.

src/tables.ts

@@ -9,6 +9,12 @@ import {
   type KeyModifierState,
 } from "./types.ts";
 
+/**
+ * Table for looking up the {@linkcode Modifier} that corresponds to a modifier
+ * event property (e.g. `event.altKey`).
+ *
+ * @internal
+ */
 export const modifierByModifierStatusTable = new Map<
   KeyModifierState,
   Modifier
@@ -19,6 +25,14 @@ export const modifierByModifierStatusTable = new Map<
   ["shiftKey", Modifier.Shift],
 ]);
 
+/**
+ * Table for looking up the {@linkcode MouseButton} that corresponds to the
+ * [`event.buttons` property](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/buttons)
+ * on a [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent)
+ * (represented by {@linkcode EventButton}).
+ *
+ * @internal
+ */
 export const mouseButtonByEventButtonTable = new Map<EventButton, MouseButton>([
   [EventButton.None, MouseButton.None],
   [EventButton.Left, MouseButton.Left],
@@ -28,6 +42,12 @@ export const mouseButtonByEventButtonTable = new Map<EventButton, MouseButton>([
   [EventButton.BrowserForward, MouseButton.BrowserForward],
 ]);
 
+/**
+ * Table for looking up the [`event.key` property](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
+ * value that corresponds to a {@linkcode Key} value.
+ *
+ * @internal
+ */
 export const eventKeyByKeyEnumTable = new Map<Key, string>([
   [Key.Backspace, "Backspace"],
   [Key.Tab, "Tab"],
@@ -111,6 +131,13 @@ export const eventKeyByKeyEnumTable = new Map<Key, string>([
   [Key.Quote, `"`],
 ]);
 
+/**
+ * Table for looking up the {@linkcode Key} value that corresponds to the
+ * [`event.key` property](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)
+ * value.
+ *
+ * @internal
+ */
 export const keyEnumByEventKeyTable = new Map<string, Key>([
   ["Backspace", Key.Backspace],
   ["Tab", Key.Tab],
@@ -194,6 +221,11 @@ export const keyEnumByEventKeyTable = new Map<string, Key>([
   [`"`, Key.Quote],
 ]);
 
+/**
+ * Table for looking up the display values that correspond to a {@linkcode Chord}.
+ *
+ * @internal
+ */
 export const tokensDisplayTable = new Map<Chord, string>([
   [MouseButton.Auxiliary, "Middle Click"],
   [MouseButton.BrowserBack, "Back Click"],

src/types.ts

@@ -26,6 +26,7 @@ export type Token = Key | Modifier | MouseButton;
  *
  * @example
  * const single = Key.LetterC;
+ *
  * const combination = Modifier.Alt | Key.Number2;
  */
 export type Chord = Token | number;