react-changes

React-Changes

React-Changes is a versatile and easy-to-use state management library built for React applications. It provides an intuitive way to manage complex state with a useChange hook. This custom hook enables interaction with the global state either in a named or unnamed manner, providing flexibility for handling simple as well as complex data sets, like multi-page forms or deeply nested properties. The library also offers versioning and playback of global state changes.

Features

• useChange Hook: A custom React hook that provides useState-like functionality for global state. It can be used in a named manner (ideal for deeply nested state properties or complex data sets) or an unnamed manner. Both modes return a pair: an array with the current state value and a function to update that value.

• Versioning: The library keeps track of every change made to the global state, enabling users to undo and redo changes, inspect the history of state changes, or seek to a specific version of state.

• Playback: The library allows users to playback the history of state changes, which can be helpful for debugging or understanding user interactions.

Installation

You can install React-Changes using npm or yarn.

npm install react-changes

yarn add react-changes

Usage

First, wrap your application in the Changes (GlobalStateProvider) component.

import { Changes } from "react-changes";

function App() {
  return (
    <Changes>
      <YourComponent />
    </Changes>
  );
}

Named usage

To manage complex or nested state properties, or group related properties together, use the useChange hook in its named manner:

import { useChange } from "react-changes";

function YourComponent() {
  const [value, setValue] = useChange("group.property", "default value");

  // To update the value
  setValue("new value");

  // ...
}

Unnamed usage

If you don't need to manage deeply nested state or group related properties together, you can use the useChange hook in its unnamed manner:

import { useChange } from "react-changes";

function YourComponent() {
  const [value, setValue] = useChange("default value");

  // To update the value
  setValue("new value");

  // ...
}

In this case, the hook automatically assigns a unique, memoized string as the path to your state value.

To access the control actions for the global state, use the useChangeControls hook.

import { useChangeControls } from "react-changes";

function YourComponent() {
  const { undo, redo, play, stop, clear, versions, seek } = useChangeControls();

  // ...
}

To display buttons for controlling the global state, use the PlayerControls component.

import { PlayerControls } from "react-changes";

function YourComponent() {
  // ...
  return (
    <div>
      {/* Your component code... */}
      <PlayerControls />
    </div>
  );
}

Debugging

For debugging, you can enable the debug prop in the Changes (GlobalStateProvider) component. This will expose the global state context to the window object.

<Changes debug>{/* Your components */}</Changes>

You can then access the global state context in your browser's JavaScript console with window.gs.

Future Improvements

The library is still under development. In the future, we aim to:

• Improve typescript support for better type safety
• Enhance the versioning