state-hooks/README.md

Essential set of React Hooks for convenient state management.

# state-hooks

Essential set of [React Hooks] for convenient state management.

[react hooks]: https://reactjs.org/docs/hooks-intro.html

## Key features

Being part of the [@kripod/react-hooks] project, this package is:

- 🌳 **Bundler-friendly** with tree shaking support
- 📚 **Well-documented** and type-safe interfaces
- ⚛️ **Zero-config** server-side rendering capability
- 📦 **Self-contained**, free of runtime dependencies

[@kripod/react-hooks]: https://github.com/kripod/react-hooks

## Usage

After installing the package, import individual hooks as shown below:

```javascript
import { usePrevious, useUndoable } from 'state-hooks';
```

## Reference

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

#### Table of Contents

- [useChanging](#usechanging)
- [usePrevious](#useprevious)
- [useTimeline](#usetimeline)
- [useToggle](#usetoggle)
- [useUndoable](#useundoable)

### useChanging

Tracks whether a value has changed over a relatively given period of time.

#### Parameters

- `value` **T** Props, state or any other calculated value.
- `groupingIntervalMs` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Time interval, in milliseconds, to group a batch of changes by. (optional, default `150`)

#### Examples

```javascript
function Component() {
  const scrollCoords = useWindowScrollCoords();
  const isScrolling = useChanging(scrollCoords);
  // ...
}
```

Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` if the value has changed at least once over the given interval, or `false` otherwise.

### usePrevious

Tracks previous state of a value.

#### Parameters

- `value` **T** Props, state or any other calculated value.

#### Examples

```javascript
function Component() {
  const [count, setCount] = useState(0);
  const prevCount = usePrevious(count);
  // ...
  return `Now: ${count}, before: ${prevCount}`;
}
```

Returns **(T | [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))** Value from the previous render of the enclosing component.

### useTimeline

Records states of a value over time.

#### Parameters

- `value` **T** Props, state or any other calculated value.
- `maxLength` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Maximum amount of states to store at once. Should be an integer greater than 1. (optional, default `MAX_SMALL_INTEGER`)

#### Examples

```javascript
function Component() {
  const [count, setCount] = useState(0);
  const counts = useTimeline(count);
  // ...
  return `Now: ${count}, history: ${counts}`;
}
```

Returns **ReadonlyArray&lt;T>** Results of state updates in chronological order.

### useToggle

Wraps a state hook to add boolean toggle functionality.

#### Parameters

- `useStateResult` **\[[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean), React.Dispatch&lt;React.SetStateAction&lt;[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)>>]** Return value of a state hook.
  - `useStateResult.0` Current state.
  - `useStateResult.1` State updater function.

#### Examples

```javascript
function Component() {
  const [isPressed, setPressed, togglePressed] = useToggle(
    useState < boolean > false,
  );
  // ...
  return (
    <button type="button" aria-pressed={isPressed} onClick={togglePressed}>
      Toggle state
    </button>
  );
}
```

Returns **\[[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean), React.Dispatch&lt;React.SetStateAction&lt;[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)>>, function (): void]** State hook result extended with a `toggle` function.

### useUndoable

Wraps a state hook to add undo/redo functionality.

#### Parameters

- `useStateResult` **\[T, React.Dispatch&lt;React.SetStateAction&lt;T>>]** Return value of a state hook.
  - `useStateResult.0` Current state.
  - `useStateResult.1` State updater function.
- `maxDeltas` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Maximum amount of state differences to store at once. Should be a positive integer. (optional, default `MAX_SMALL_INTEGER`)

#### Examples

```javascript
function Component() {
  const [value, setValue, { undo, redo, past, future }] = useUndoable(
    useState(''),
  );
  // ...
  return (
    <>
      <button type="button" onClick={undo} disabled={past.length === 0}>
        Undo
      </button>
      <input value={value} onChange={(event) => setValue(event.target.value)} />
      <button type="button" onClick={redo} disabled={future.length === 0}>
        Redo
      </button>
    </>
  );
}
```

Returns **\[T, React.Dispatch&lt;React.SetStateAction&lt;T>>, {undo: function (): void, redo: function (): void, past: [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;T>, future: [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;T>, jump: function (delta: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)): void}]** State hook result extended with an object containing `undo`, `redo`, `past`, `future` and `jump`.