feat(logic): document createHover

src/prose/logic/factories/hover.md

@@ -0,0 +1,85 @@
+---
+title: hover
+source: createHover.ts
+tests: browser/createHover.test.ts
+publish: true
+order: 1
+---
+
+`createHover` is a [factory](/docs/logic/factories-overview) that returns [`Recognizeable` effects](/docs/logic/classes/recognizeable#effect-workflow) for recognizing hover.
+
+A **hover** starts with a `mouseover` event, and is denied by a `mouseout` event.
+
+While the mouse is still over the target element, `createHover` continuously recognizes the gesture at a rate of 60fps. The gesture is recognized when the mouse has been over the element for a minimum duration, which is configurable.
+
+
+:::
+## Create hover
+:::
+
+Call `createHover` with these parameters to create your `mouseover` and `mouseout` effects:
+
+::: ariaLabel="createHover parameters" classes="wide-4"
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `options` | Object | no | Options to customize the behavior of the `mouseover` and `mouseout` effects. See the [Options](#options) section for more guidance. |
+:::
+
+
+:::
+### Options
+:::
+
+::: ariaLabel="createHover options" classes="wide-4"
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `minDuration` | number | `0` | The minimum millisecond duration of the hover, in milliseconds. |
+| `onOver` | Function | `undefined` | <p>A function that is called when the mouse is over the target element.</p><p>`onOver` receives the [`hover` hook API](#hook-api) as its only parameter.</p> |
+| `onOut` | Function | `undefined` | <p>A function that is called when the mouse leaves the target.</p><p>`onOut` receives the [`hover` hook API](#hook-api) as its only parameter.</p> |
+:::
+
+
+:::
+#### Hook API
+:::
+
+The hook API is an object that is passed to the `onOver` and `onOut` options as their only parameter. It contains the following properties:
+
+::: ariaLabel="`hover` hook API" classes="wide-4"
+| Property | Type | Description |
+| --- | --- | --- |
+| `status` | string | The status of the sequence. One of `recognized`, `denied`, or `recognizing`. |
+| `metadata` | Object | Metadata about the sequence. See the [Metadata](#metadata) section for more guidance. |
+| `sequence` | Array | The sequence of events that have occurred so far. |
+:::
+
+
+:::
+## Metadata
+:::
+
+Your created hover effects store data in the `Recognizeable` instance's `metadata` property.
+
+Hover metadata includes all [pointer metadata](/docs/logic/factories/recognizeable-effects-overview#pointer-metadata).
+
+
+:::
+## Using with `Listenable`
+:::
+
+The easiest way to use `createHover` with [`Listenable`](/docs/logic/classes/listenable) is to use the `Hover` class, which is a very minimal [subclass of `Listenable`](/docs/logic/factories/recognizeable-overview#listenable-subclasses) that handles configuration for you.
+
+Here's an example of how to use `Hover` to nicely combine `createHover` with `Listenable`:
+
+:::
+```ts
+import { Hover } from '@baleada/logic'
+
+const hover = new Hover([hoverOptions])
+
+hover.listen(() => {
+  console.log(hover.metadata.duration)
+})
+```
+:::
+

src/prose/logic/factories/mousepress.md

@@ -8,7 +8,7 @@ order: 1
 
 `createMousepress` is a [factory](/docs/logic/factories-overview) that returns [`Recognizeable` effects](/docs/logic/classes/recognizeable#effect-workflow) for recognizing mouse presses.
 
-A **mouse press** starts with a `mousedown` event, and is denied by a `mouseup` or `mouseleave` event.
+A **mouse press** starts with a `mousedown` event, and is denied by a `mouseup` or `mouseout` event.
 
 While the mouse is still down, `createMousepress` continuously recognizes the gesture at a rate of 60fps. The gesture is recognized when the mouse has been down for a minimum duration and has moved a minimum distance, both of which are configurable.
 
@@ -17,12 +17,12 @@ While the mouse is still down, `createMousepress` continuously recognizes the ge
 ## Create mousepress
 :::
 
-Call `createMousepress` with these parameters to create your `mousedown`, `mouseleave`, and `mouseup` effects:
+Call `createMousepress` with these parameters to create your `mousedown`, `mouseout`, and `mouseup` effects:
 
 ::: ariaLabel="createMousepress parameters" classes="wide-4"
 | Parameter | Type | Required | Description |
 | --- | --- | --- | --- |
-| `options` | Object | no | Options to customize the behavior of the `mousedown`, `mouseleave`, and `mouseup` effects. See the [Options](#options) section for more guidance. |
+| `options` | Object | no | Options to customize the behavior of the `mousedown`, `mouseout`, and `mouseup` effects. See the [Options](#options) section for more guidance. |
 :::
 
 
@@ -37,7 +37,7 @@ Call `createMousepress` with these parameters to create your `mousedown`, `mouse
 | `minDistance` | number | `0` | The minimum pixel distance the mouse must move. |
 | `onDown` | Function | `undefined` | <p>A function that is called when the mouse is pressed down.</p><p>`onDown` receives the [`mousepress` hook API](#hook-api) as its only parameter.</p> |
 | `onMove` | Function | `undefined` | <p>A function that is called when the mouse moves.</p><p>`onMove` receives the [`mousepress` hook API](#hook-api) as its only parameter.</p> |
-| `onLeave` | Function | `undefined` | <p>A function that is called when the mouse leaves the target.</p><p>`onLeave` receives the [`mousepress` hook API](#hook-api) as its only parameter.</p> |
+| `onOut` | Function | `undefined` | <p>A function that is called when the mouse leaves the target.</p><p>`onOut` receives the [`mousepress` hook API](#hook-api) as its only parameter.</p> |
 | `onUp` | Function | `undefined` | <p>A function that is called when the mouse is released.</p><p>`onUp` receives the [`mousepress` hook API](#hook-api) as its only parameter.</p> |
 :::
 
@@ -46,7 +46,7 @@ Call `createMousepress` with these parameters to create your `mousedown`, `mouse
 #### Hook API
 :::
 
-The hook API is an object that is passed to the `onDown`, `onMove`, `onLeave`, and `onUp` options as their only parameter. It contains the following properties:
+The hook API is an object that is passed to the `onDown`, `onMove`, `onOut`, and `onUp` options as their only parameter. It contains the following properties:
 
 ::: ariaLabel="`mousepress` hook API" classes="wide-4"
 | Property | Type | Description |

src/prose/logic/factories/mouserelease.md

@@ -8,7 +8,7 @@ order: 1
 
 `createMouserelease` is a [factory](/docs/logic/factories-overview) that returns [`Recognizeable` effects](/docs/logic/classes/recognizeable#effect-workflow) for recognizing mouse releases.
 
-A **mouse release** is a sequence of a `mousedown` and a `mouseup`, and allows for `mousemove` in between those events, but denies the event on `mouseleave`.
+A **mouse release** is a sequence of a `mousedown` and a `mouseup`, and allows for `mousemove` in between those events, but denies the event on `mouseout`.
 
 `createMouserelease` attempts to recognize the gesture when `mouseup` fires. The gesture is recognized at on `mouseup` if the mouse has been down for a minimum duration and has moved a minimum distance, both of which are configurable.
 
@@ -17,12 +17,12 @@ A **mouse release** is a sequence of a `mousedown` and a `mouseup`, and allows f
 ## Create mouserelease
 :::
 
-Call `createMouserelease` with these parameters to create your `mousedown`, `mouseleave`, and `mouseup` effects:
+Call `createMouserelease` with these parameters to create your `mousedown`, `mouseout`, and `mouseup` effects:
 
 ::: ariaLabel="createMouserelease parameters" classes="wide-4"
 | Parameter | Type | Required | Description |
 | --- | --- | --- | --- |
-| `options` | Object | no | Options to customize the behavior of the `mousedown`, `mouseleave`, and `mouseup` effects. See the [Options](#options) section for more guidance. |
+| `options` | Object | no | Options to customize the behavior of the `mousedown`, `mouseout`, and `mouseup` effects. See the [Options](#options) section for more guidance. |
 :::
 
 
@@ -38,7 +38,7 @@ Call `createMouserelease` with these parameters to create your `mousedown`, `mou
 | `minVelocity` | number | `0` | The minimum pixel velocity the mouse must move. |
 | `onDown` | Function | `undefined` | <p>A function that is called when the mouse is pressed down.</p><p>`onDown` receives the [`mouserelease` hook API](#hook-api) as its only parameter.</p> |
 | `onMove` | Function | `undefined` | <p>A function that is called when the mouse moves.</p><p>`onMove` receives the [`mouserelease` hook API](#hook-api) as its only parameter.</p> |
-| `onLeave` | Function | `undefined` | <p>A function that is called when the mouse leaves the target.</p><p>`onLeave` receives the [`mouserelease` hook API](#hook-api) as its only parameter.</p> |
+| `onOut` | Function | `undefined` | <p>A function that is called when the mouse leaves the target.</p><p>`onOut` receives the [`mouserelease` hook API](#hook-api) as its only parameter.</p> |
 | `onUp` | Function | `undefined` | <p>A function that is called when the mouse is released.</p><p>`onUp` receives the [`mouserelease` hook API](#hook-api) as its only parameter.</p> |
 :::
 
@@ -47,7 +47,7 @@ Call `createMouserelease` with these parameters to create your `mousedown`, `mou
 #### Hook API
 :::
 
-The hook API is an object that is passed to the `onDown`, `onMove`, `onLeave`, and `onUp` options as their only parameter. It contains the following properties:
+The hook API is an object that is passed to the `onDown`, `onMove`, `onOut`, and `onUp` options as their only parameter. It contains the following properties:
 
 ::: ariaLabel="`mouserelease` hook API" classes="wide-4"
 | Property | Type | Description |