README.md

Use Tree State

A super-light and customizable React hook to manage tree state like never before ✨✨

An example package that uses this hook internally: react-folder-tree

Features

✅ built in CRUD handlers: add, modify, delete tree nodes with 1 line of code
✅ custom handlers: define any custom state transition for your need
✅ half check: auto calculate new checked status for all nodes
✅ onChange: listen to state change and events

Usage

🌀 install

$ yarn add use-tree-state
$ npm install use-tree-state --save

🌀 initialization

import useTreeState, { testData } from 'use-tree-state';

const TreeApp = () => {
  const { treeState } = useTreeState({ data: testData });

  return (<Tree state={ treeState } />);
};

🌀 custom initialization

Initial tree state is an object that describes a nested tree node structure, which looks like:

{
  // reserved keys, can customize initial value
  name: 'root node',  
  checked (optional): 0 (unchecked, default) | 0.5 (half checked) | 1(checked),
  isOpen (optional): true (default) | false,
  children (optional): [array of treenode],

  // internal key (auto generated), plz don't include it in the initial data
  _id: 0,

  // all other keys are not reserved, can carry any extra info about this node
  nickname (optional): 'pikachu',
  url (optional): 'www.pokemon.com',
  ...
}

checked and isOpen status could be auto initialized by props initCheckedStatus and initOpenStatus. We can also provide data with custom checked and isOpen status, and set initCheckedStatus and initOpenStatus to 'custom'.

Example:

const { treeState } = useTreeState({
  data: testData,
  options: {
    initCheckedStatus: 'checked',   // 'unchecked' (default) | 'checked' | 'custom'
    initOpenStatus: 'open',         // 'open' (default) | 'closed' | 'custom'
  }
});

🌀 update tree state

There are a couple built in tree state reducers that can update tree state conveniently.

Note that these reducers are slightly different than redux reducers. These are more like wrapped reducers which are functions that

f(path: array<int>, ...args) => update state internally
or
fByProp(propName: string, targetValue: any, ...args) => update state internally

For more details please refer to Built-in Reducers section.

const TreeApp = () => {
  const { treeState, reducers } = useTreeState({ data: testData });
  const {
    // update state using node's path to find target
    checkNode,
    toggleOpen,
    renameNode,
    deleteNode,
    addNode,

    // update state using any node's property to find target
    checkNodeByProp,
    toggleOpenByProp,
    renameNodeByProp,
    deleteNodeByProp,
    addNodeByProp,
  } = reducers;

  const check_first_node = () => checkNode([0]);
  const check_node_whos_name_is_Goku = () => checkNodeByProp('name', 'Goku');

  const open_first_node = () => toggleOpen([0], 1);
  const open_node_whos_url_is_www = () => toggleOpenByProp('url', 'www', 1);
  const close_node_whos_num_is_123 = () => toggleOpenByProp('num', 123, 0);

  const rename_third_node_to_pikachu = () => renameNode([2], 'pikachu');
  const rename_snorlax_node_to_pikachu = () => renameNode('name', 'snorlax', 'pikachu');

  const remove_fourth_node = () => deleteNode([3]);
  const remove_unnecessary_node = () => deleteNodeByProp('necessary', false);

  const add_leaf_node_in_root_node = () => addNode([], false);
  const add_parent_node_in_Pokemon_node = () => addNodeByProp('type', 'Pokemon', true);

  return (...);
};

🌀 onChange listener

we can pass in an onChange(newState: tree-state-obj, event: obj) to the hook to listen for state change event.

const handleStateChange = (newState, event) => {
  const { type, path, params } = event;

  console.log('last event: ', { type, path, params });
  console.log('state changed to: ', newState);
};

const { treeState } = useTreeState({
  data: testData,
  onChange: handleStateChange,      // <== here!!
});

Built-in Reducers

There are two types of built in reducers (or call it handlers if you prefer) that differ in how they find target node to operate on.

1) find target node by path

• reducers.checkNode
• reducers.toggleOpen
• reducers.renameNode
• reducers.deleteNode
• reducers.addNode

their format is f(path: array<int>, ...args) => update state internally, where path is an array of indexes from root to the target node.

An example that shows each node and corresponding path

const treeState = {
  name: 'root',         // path = []
  children: [
    { name: 'node_0' }    // path = [0]
    { name: 'node_1' }    // path = [1]
    {
      name: 'node_2',     // path = [2]
      children: [
        { name: 'node_2_0' },   // path = [2, 0]
        { name: 'node_2_1' },   // path = [2, 1]
      ],
    }
  ],
};

2) find target node by property (can be any property in tree node data)

• reducers.checkNodeByProp
• reducers.toggleOpenByProp
• reducers.renameNodeByProp
• reducers.deleteNodeByProp
• reducers.addNodeByProp

their format is fByProp(propName: string, targetValue: any, ...args) => update state internally

🌀 reducers details

• checkNode(path: array<int>, checked: 1 | 0)

• checkNodeByProp(propName: string, targetValue: any, checked: 1 | 0)

Set checked property of the target node, 1 for 'checked', 0 for 'unchecked'.

It will also update checked status for all other nodes:

• if we (un)checked a parent node, all children nodes will also be (un)checked
• if some (but not all) of a node's children are checked, this node becomes half check (internally set checked = 0.5)

• toggleOpen(path: array<int>, isOpen: bool)

• toggleOpenByProp(propName: string, targetValue: any, isOpen: bool)

Set the open status isOpen for the target node. isOpen: false usually means in UI we shouldn't see it's children.

This only works for parent nodes, which are the nodes that has children property.

• renameNode(path: array<int>, newName: string)

• renameNodeByProp(propName: string, targetValue: any, newName: string)

You know what it is.

• deleteNode(path: array<int>)

• deleteNodeByProp(propName: string, targetValue: any)

Delete the target node. If target node is a parent, all of it's children will also be removed.

• addNode(path: array<int>, hasChildren: bool)

• addNodeByProp(propName: string, targetValue: any, hasChildren: bool)

Add a node as a children of target node. hasChildren: true means this new node is a parent node, otherwise it is a leaf node.

This only works for parent nodes.

• setTreeState(newState: tree-state-object)

Instead of 'update' the tree state, this will set whole tree state directly. Didn't test this method, but leave this api anyways, so use with cautions! And plz open an issue if it doesn't work : )

Custom Reducers

There are two ways to build custom state transition functions. We provide an util to help find the target node: findTargetNode(root: tree-state-obj, path: array<int>) .

🌀 method 1: wrap custom reducers (recommended)

We can build any custom reducers of format

myReducer(root: tree-state-obj, path: array<int> | null, ...params): tree-state-obj

and pass it to the hook constructor. Hook will then expose a wrapped version of it, and we can use it like

reducers.myReducer(path: array<int> | null, ...params)

to update the treeState.

import useTreeState, {
  testData,
  findTargetNode,
} from 'use-tree-state';

// this app demos how to build a custom reducer that rename a node to 'pikachu'
const TreeApp = () => {
  // our custom reducer
  const renameToPikachuNTimes = (root, path, n) => {
    const targetNode = findTargetNode(root, path);
    targetNode.name = 'pika'.repeat(n);

    return { ...root };
  };

  const { treeState, reducers } = useTreeState({
    data: testData,
    customReducers: {
      renameToPikachuNTimes,  // pass in and hook will wrap it
    },
  });

  const renameFirstNodeToPikaPikaPika = () => {
    // use the wrapped custom reducer
    reducers.renameToPikachuNTimes([0], 3);
  }

  return (<>
    <button onClick={ renameFirstNodeToPikaPikaPika }>
      pika pika
    </button>

    <Tree state={ treeState } />
  </>);

};

🌀 method 2: set tree state from outside

const TreeApp = () => {
  const { treeState, reducers } = useTreeState({ data: testData });
  const { setTreeState } = reducers;

  // our custom reducer to set tree state directly
  const renameToPikachuNTimes = (root, path, n) => {
    // treeState is a ref to the internal state, plz don't alter it directly
    const newState = deepClone(root); 

    const targetNode = findTargetNode(newState, path);
    targetNode.name = 'pika'.repeat(n);

    setTreeState(newState);
  };

  const renameFirstNodeToPikaPikaPika = () => {
    renameToPikachuNTimes(treeState, [0], 3);
  }

  return (<>
    <button onClick={ renameFirstNodeToPikaPikaPika }>
      pika pika
    </button>

    <Tree state={ treeState } />
  </>);
};

🌀 find node by any node property

⚡️live exmaple

Other than the built-in reducers that CRUD by prop, we can build more general reducers that do anything by prop, with the help of these two adapters:

• findTargetPathByProp(root: tree-state-obj, propName: string, targetValue: string): array<int>
• findAllTargetPathByProp(root: tree-state-obj, propName: string, targetValue: string): array<array<int>>

For example, let's rewrite renameNodeByProp in a more custom way

import { findTargetPathByProp } from 'use-tree-state';

// our custom reducer, note that we omit the `path` param as _ since we don't need it
const renameNodeByTargetName = (root, _, targetName, newName) => {
  // only need this one extra line to find path first
  // if 'name' is not unique, we can find all nodes by `findAllTargetPathByProp`
  const path = findTargetPathByProp(root, 'name', targetName);    // <== here!!!

  // then everything else is just the same
  const targetNode = findTargetNode(root, path);
  targetNode.name = newName;

  return { ...root };
};

// ......

// then we can use it like
reducers.renameNodeByTargetName(null, 'snorlax', 'pikachu');

Side Notes We chose to use path to find target node as the primary interface because:

• path is always unique
• this is the fastest way to find a target node
• we can dynamically general path in <Tree /> component, which perfectly matches such interface (example)

Bugs? Questions? Contributions?

Feel free to open an issue, or create a pull request!