Add useProcessKey hook; update docs

README.md

@@ -47,6 +47,7 @@ This library has the following peer dependencies:
   - [useSetFocus()](#usesetfocus)
   - [useNodeEvents()](#usenodeevents-focusid-events-)
   - [useFocusHierarchy()](#usefocushierarchy)
+  - [useProcessKey()](#useprocesskey)
   - [useFocusStoreDangerously()](#usefocusstoredangerously)
 - [**Interfaces**](#interfaces)
   - [FocusNode](#focusnode)
@@ -314,6 +315,42 @@ export default function MyComponent() {
 }
 ```
 
+### `useProcessKey()`
+
+A [Hook](https://reactjs.org/docs/hooks-intro.html) that allows you to imperatively trigger LRUD key presses.
+
+```js
+import { useProcessKey } from '@please/lrud';
+
+function MyComponent() {
+  const processKey = useProcessKey();
+
+  useEffect(() => {
+    // Imperatively trigger a down key press
+    processKey.down();
+
+    // Imperatively trigger a back key press
+    processKey.select();
+
+    // ...same, for the back button.
+    processKey.back();
+  }, []);
+}
+```
+
+The full API is as follows.
+
+```ts
+interface ProcessKey {
+  select: () => void;
+  back: () => void;
+  down: () => void;
+  left: () => void;
+  right: () => void;
+  up: () => void;
+}
+```
+
 ### `useFocusStoreDangerously()`
 
 > ⚠️ Heads up! The FocusStore is an internal API. We strongly discourage you from accessing properties or calling
@@ -451,11 +488,13 @@ for advanced use cases that you may have.
 | `deleteNode`             | function | Deletes a focus node from the tree.                                    |
 | `setFocus`               | function | Imperatively assign focus to a particular focus node.                  |
 | `updateNode`             | function | Update an existing node. Used to, for example, set a node as disabled. |
-| `handleArrow`            | function | Call this to navigate based on an arrow key press.                     |
-| `handleSelect`           | function | Call this to cause the focus tree to respond to a "select" key press.  |
+| `processKey `            | object   | Contains methods to trigger key presses.                               |
+| `handleArrow`            | function | Updates store state after arrow key presses.                           |
+| `handleSelect`           | function | Updates store state after select button presses.                       |
 | `configurePointerEvents` | function | Enable or disable pointer events. Receives one argument, a `boolean`.  | 
 | `destroy`                | function | Call when disposing of the store. Cleans up event listeners.           |
 
+
 ### `FocusState`
 
 > ⚠️ Heads up! This is an internal API. We strongly discourage you from accessing this object directly in your application.

src/hooks/use-process-key.ts

@@ -0,0 +1,6 @@
+import useFocusStoreDangerously from './use-focus-store-dangerously';
+
+export default function useProcessKey() {
+  const focusStore = useFocusStoreDangerously();
+  return focusStore.processKey;
+}

src/index.ts

@@ -7,6 +7,7 @@ export { default as useFocusHierarchy } from './hooks/use-focus-hierarchy';
 export { default as useFocusStoreDangerously } from './hooks/use-focus-store-dangerously';
 export { default as useSetFocus } from './hooks/use-set-focus';
 export { default as useFocusEvents } from './hooks/use-focus-events';
+export { default as useProcessKey } from './hooks/use-process-key';
 
 const FocusRoot = FocusContext.FocusRoot;
 export { FocusRoot };