Initial work on documenting events

docs/api.md

@@ -124,3 +124,12 @@ getByText(
 Queries for test instance `stdout` results with the given text (and it also accepts a TextMatch). 
 
 These options are all standard for text matching. To learn more, see our [Queries page](./queries.md).
+
+## `fireEvent`
+
+```javascript
+fireEvent(instance: TestInstace, event: Event)
+```
+
+> While `fireEvent` isn't usually returned on `render` in, say, `React Testing Library`, we're able to do
+> so because of our differences in implementation with upstream. See our [Differences](./differences.md) doc for more.

docs/differences.md

@@ -1,4 +1,4 @@
-# Differences Between `@testing-library/dom` and `cli-testing-library`
+# Differences Between `cli-testing-library` & Testing Library
 
 While we clearly take inspiration from [`DOM Testing Library`](https://github.com/testing-library/dom-testing-library)
 and [`React Testing Library`](https://github.com/testing-library/react-testing-library),
@@ -43,22 +43,31 @@ While we would be happy to reconsider, there are once again
 
 # Events
 
-Another area where we diverge from the DOM is in our event system (as implemented via `fireEvent`).
+Another area where we diverge from the DOM is in our event system (as implemented via `fireEvent` and `userEvent`).
 
-Despite our APIs naming indicating an actual event system (complete with bubbling and more, like the DOM),
+Despite our APIs' naming indicating an actual event system (complete with bubbling and more, like the DOM),
 the CLI has no such concept.
 
 This means that, while `fireEvent` in the `DOM Testing Library` has the ability to inherent from all
 baked-into-browser events, we must hard-code a list of "events" and actions a user may take.
 
 We try our best to implement ones that make sense:
 
-- `fireEvent.up()` for keyboard up
-- `fireEvent.type(str)` to write code into stdin
+- `fireEvent.write({value: str})` to write `str` into stdin
 - `fireEvent.sigkill()` to send a [sigkill](https://en.wikipedia.org/wiki/Signal_(IPC)#SIGKILL) to the process
+- `fireEvent.sigint()` to send a [sigint](https://en.wikipedia.org/wiki/Signal_(IPC)#SIGINT) to the process
 
-But there are avenues where this diverges from upstream. [We have an open list of questions about how we can
-make our events align more with upstream](https://github.com/crutchcorn/cli-testing-library/issues/2)
+There is a missing API for that might make sense in `keypress`. It's unclear what this behavior would do that `write` wouldn't
+be able to.
+
+There's also the API of `userEvent` that allows us to implement a fairly similar `keyboard` event
+[to upstream](https://testing-library.com/docs/ecosystem-user-event/#keyboardtext-options). However, there are a few differences
+here as well:
+
+1) `userEvent` can be bound to the `render` output. This is due to limitations of not having a `screen` API. It's unclear how
+    this would work in practice, due to a lack of the `window` API.
+2) `userEvent.keyboard` does not support modifier keys. It's only key-presses, no holding. This is because of API 
+    differences that would require us to figure out a manual binding system for every single key using ANSI AFAIK.
 
 # Matchers
 

docs/fire-event.md

@@ -0,0 +1,31 @@
+# Firing Events
+
+> **Note**
+>
+> Most projects have a few use cases for `fireEvent`, but the majority of the time you should probably use [`userEvent`](./user-event).
+
+## `fireEvent`
+
+```typescript
+fireEvent(instance: TestInstance, event: EventString, eventProperties?: Object)
+```
+
+Fire CLI events.
+
+```javascript
+fireEvent(
+  getByText(instance, 'Username:'),
+  'write',
+  {value: 'crutchcorn'}
+)
+```
+
+## `fireEvent[eventName]`
+
+```typescript
+fireEvent[eventName](instance: TestInstance, eventProperties?: Object)
+```
+
+Convenience methods for firing CLI events. Check out
+[src/event-map.js](https://github.com/crutchcorn/cli-testing-library/blob/main/src/event-map.js)
+for a full list as well as default `eventProperties`.