diff --git a/docs/extensions/history.mdx b/docs/extensions/history.mdx new file mode 100644 index 0000000000..6704211e9d --- /dev/null +++ b/docs/extensions/history.mdx @@ -0,0 +1,110 @@ +--- +title: Hitory +description: A Jōtai utility package for advanced state history management +nav: 4.03 +keywords: history, undo, redo, jotai +--- + +[jotai-history](https://github.com/jotaijs/jotai-history) is a utility package for advanced state history management. + +## install + +``` +npm i jotai-history +``` + +## withHistory + +### Signature + +```ts +declare function withHistory(targetAtom: Atom, limit: number): Atom +``` + +This function creates an atom that keeps a history of states for a given `targetAtom`. The `limit` parameter determines the maximum number of history states to keep. +This is useful for tracking the changes over time. + +The history atom tracks changes to the `targetAtom` and maintains a list of previous states up to the specified `limit`. When the `targetAtom` changes, its new state is added to the history. + +### Usage + +```jsx +import { atom, useAtomValue, useSetAtom } from 'jotai' +import { withHistory } from 'jotai-history' + +const countAtom = atom(0) +const countWithPrevious = withHistory(countAtom, 2) + +function CountComponent() { + const [count, previousCount] = useAtomValue(countWithPrevious) + const setCount = useSetAtom(countAtom) + + return ( + <> +

Count: {count}

+

Previous Count: {previousCount}

+ + + ) +} +``` + +## withUndo + +### Signature + +```ts +type Undoable = { + undo: () => void + redo: () => void + canUndo: boolean + canRedo: boolean +} +declare function withUndo( + targetAtom: WritableAtom, + limit: number, +): Atom +``` + +`withHistory` provides undo and redo capabilities for an atom. It keeps track of the value history of `targetAtom` and provides methods to move back and forth through that history. + +The returned object includes: + +- `undo`: A function to revert to the previous state. +- `redo`: A function to advance to the next state. +- `canUndo`: A boolean indicating if it's possible to undo. +- `canRedo`: A boolean indicating if it's possible to redo. + +### Usage + +```jsx +import { atom, useAtom, useAtomValue } from 'jotai' +import { withUndo } from 'jotai-history' + +const counterAtom = atom(0) +const undoCounterAtom = withUndo(counterAtom, 5) + +function CounterComponent() { + const { undo, redo, canUndo, canRedo } = useAtomValue(undoCounterAtom) + const [value, setValue] = useAtom(counterAtom) + + return ( + <> +

Count: {value}

+ + + + + ) +} +``` + + + +## Memory Management + +⚠️ Since `withHistory` and `withUndo` keeps a history of states, it's important to manage memory by setting a reasonable `limit`. Excessive history can lead to memory bloat, especially in applications with frequent state updates.