Merge pull request #25 from shunjizhan/v5

upgrade to V5

Author: shunjizhan

CHANGELOG.md

@@ -0,0 +1,4 @@
+## 5.0.0 (2021.6.3)
+- restruct internal state management using `use-tree-state` hook
+- separate css file
+- interface change: `onNameClick(defaultOnClick, nodeData)` => `onNameClick({ defaultOnClick, nodeData })`

README.md

@@ -1,9 +1,12 @@
 # React Folder Tree
-A versatile and customizable react treeview library. It supports:
-- ✅ customize icons
-- ✅ customize event handlers
-- ✅ inline add, modify, and delete tree nodes
-- ✅ checkbox with half check (indeterminate check)
+A versatile and customizable react treeview library. Features:
+✅ custom icons  
+✅ custom event handlers  
+✅ inline add, modify, and delete tree nodes  
+✅ checkbox with half check (indeterminate check)  
+✅ read-only mode
+
+It uses [use-tree-state](https://www.npmjs.com/package/use-tree-state) hook internally for convenient state management.
 ### Quick Preview
 ![folder-tree-demo](/assets/folder-tree-demo.gif)
 
@@ -20,9 +23,10 @@ $ npm install react-folder-tree --save
 ### 🌀 basic tree
 ```tsx
 import FolderTree, { testData } from 'react-folder-tree';
+import 'react-folder-tree/dist/style.css';
 
 const BasicTree = () => {
-  const onTreeStateChange = state => console.log('tree state: ', state);
+  const onTreeStateChange = (state, event) => console.log(state, event);
 
   return (
     <FolderTree
@@ -34,20 +38,26 @@ const BasicTree = () => {
 ```
 
 ### 🌀 custom initial state
-tree state is an object that looks like:
+Initial tree state is an object that describes a nested tree node structure, which looks like:
 ```jsx
 {
-  // reserved keys
-  name: 'Goku',   
+  // reserved keys, can customize initial value
+  name: 'root node',  
   checked (optional): 0 (unchecked, default) | 0.5 (half checked) | 1(checked),
-  isOpen (optional): false (default) | true,
+  isOpen (optional): true (default) | false,
   children (optional): [array of treenode],
 
-  // not reserved
-  key1 (optional): 'what ever data you need',
-  url (optional): 'url of this node for example',
+  // internal keys, don't customize plz
+  path: [],    // path is an array of indexes to this node from root node
+  _id: 0,
+
+  // not reserved, can carry any extra info about this node
+  nickname (optional): 'pikachu',
+  url (optional): 'url of this node',
 }
 ```
+`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'`.
+
 This example shows how to render a tree with custom initial state
 ```tsx
 const treeState = {
@@ -93,6 +103,15 @@ const CustomInitState = () => (
 />
 ```
 
+### 🌀 read only?
+we can use it as a classical view-only tree
+```jsx
+<FolderTree
+  data={ treeState }
+  showCheckbox={ false }    // hiding checkbox is not required but recommended for better UX
+  readOnly                  // <== here!!
+/>
+```
 ---
 ## Advanced Usage
 ### 🔥 sync tree state
@@ -102,7 +121,7 @@ This example shows how to download all selected files.
 ```jsx
 const SuperApp = () => {
   const [treeState, setTreeState] = useState(initState);
-  const onTreeStateChange = state => setTreeState(state);
+  const onTreeStateChange = (state, event) => setTreeState(state);
 
   const onDownload = () => downloadAllSelected(treeState);
 
@@ -167,10 +186,25 @@ const BitcoinApp = () => {
 };
 ```
 
-### 🔥 disable icons
-This usage is a subset of custom icons. For example, to hide `FileIcon` we can simply pass in a dummy custom icon, so nothing will be rendered.
+### 🔥 hide icons / disable interaction
+This usage is a subset of custom icons.
+
+For example, if we want to disable editing, we can hide `EditIcon` by passing in a dummy custom icon, so nothing will be rendered.
 ```tsx
-const FileIcon = (...args) => null;
+const EditIcon = (...args) => null;
+```
+
+A little more complex but more flexible way is to have extra node data, say `editable`, then build a custom icon that utilize this data
+```ts
+const EditIcon = ({ onClick: defaultOnClick, nodeData }) => {
+  const { editable } = nodeData;
+
+  // if this node is editable, render an EditIcon, otherwise render air
+  return editable ? (<FaEdit onClick={ defaultOnClick } />) : null;
+
+  // or render a 'not editable' icon
+  return editable ? (<FaEdit onClick={ defaultOnClick } />) : (<DontEdit />));
+};
 ```
 
 ### 🔥 custom `onClick` for node names
@@ -182,7 +216,7 @@ const dataWithUrl = {
   // ...
 };
 
-const onNameClick = (defaultOnClick, nodeData) => {
+const onNameClick = ({ defaultOnClick, nodeData }) => {
   defaultOnClick();
 
   const {
@@ -209,13 +243,14 @@ const Downloader = () => (
 | prop              | description                             | type     | options                                        |
 |-------------------|-----------------------------------------|----------|------------------------------------------------|
 | data              | initial tree state data (required)      | object   | N/A                                            |
-| onChange          | callback when tree state changes        | function | console.log (default)                          |
 | initCheckedStatus | initial check status of all nodes       | string   | 'unchecked' (default) \| 'checked' \| 'custom' |
-| initOpenStatus    | initial open status of all treenodes    | string   | 'open' (default) \| 'close' \| 'custom'        |
+| initOpenStatus    | initial open status of all treenodes    | string   | 'open' (default) \| 'closed' \| 'custom'        |
 | iconComponents    | custom icon components                  | object   | ant design icons (default)                     |
+| onChange          | callback when tree state changes        | function | console.log (default)                          |
+| onNameClick       | callback when click treenode name       | function | open treenode inline toolbox (default)         |
 | indentPixels      | ident pixels of 1x level treenode       | number   | 30 (default)                                   |
 | showCheckbox      | show check box?                         | bool     | true (default) | false                         |
-| onNameClick       | callback when click treenode name      | function | open treenode inline toolbox (default)         |
+| readOnly          | readOnly mode? can't click/check node   | bool     | false (default) | true                       |
 
 ---
 ## Bugs? Questions? Contributions?

config/webpack.config.js

@@ -31,14 +31,6 @@ module.exports = {
           loader: 'babel-loader',
         },
       },
-      {
-        test: /\.html$/,
-        use: [
-          {
-            loader: 'html-loader',
-          },
-        ],
-      },
       {
         test: /\.scss$/,
         use: [
@@ -51,6 +43,7 @@ module.exports = {
   },
   plugins: [
     // generates an HTML file by injecting automatically all our generated bundles.
+    // any css result will be automagically included as a <link>
     new HtmlWebPackPlugin({
       template: path.resolve(__dirname, '../public/index.html'),
       favicon: path.resolve(__dirname, '../public/pokeball.ico'),

config/webpack.prod.config.js

@@ -1,5 +1,6 @@
 const path = require('path');
 const CleanTerminalPlugin = require('clean-terminal-webpack-plugin');
+const MiniCssExtractPlugin = require('mini-css-extract-plugin');
 const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');
 
 module.exports = {
@@ -32,16 +33,17 @@ module.exports = {
       {
         test: /\.scss$/,
         use: [
-          'style-loader',   // creates style nodes from JS strings
-          'css-loader',     // translates CSS into CommonJS
-          'sass-loader',    // compiles Sass to CSS, using Node Sass by default
+          MiniCssExtractPlugin.loader,  // generate a separate style.css
+          'css-loader',                 // translates CSS into CommonJS
+          'sass-loader',                // compiles Sass to CSS, using Node Sass by default
         ],
       },
     ],
   },
   plugins: [
     // clear terminal in each build
     new CleanTerminalPlugin(),
+    new MiniCssExtractPlugin({ filename: 'style.css' }),
     // new BundleAnalyzerPlugin(),
   ],
   externals: {

package.json

@@ -4,7 +4,8 @@
   "description": "customizable react folder tree library",
   "main": "dist/react-folder-tree.bundle.js",
   "files": [
-    "dist/react-folder-tree.bundle.js"
+    "dist/react-folder-tree.bundle.js",
+    "dist/style.css"
   ],
   "author": "Shunji Zhan <[email protected]>",
   "keywords": [
@@ -63,6 +64,7 @@
     "@babel/plugin-proposal-optional-chaining": "^7.12.7",
     "@babel/preset-env": "^7.11.5",
     "@babel/preset-react": "^7.10.4",
+    "@wojtekmaj/enzyme-adapter-react-17": "^0.6.1",
     "babel-eslint": "^10.1.0",
     "babel-loader": "^8.1.0",
     "clean-terminal-webpack-plugin": "^3.0.0",
@@ -81,7 +83,10 @@
     "identity-obj-proxy": "^3.0.0",
     "jest": "^26.6.3",
     "lint-staged": "^10.5.1",
+    "mini-css-extract-plugin": "^1.6.0",
     "node-sass": "^5.0.0",
+    "react": "^16.8.0 || ^17",
+    "react-dom": "^16.8.0 || ^17",
     "sass-loader": "^10.1.0",
     "style-loader": "^2.0.0",
     "webpack": "^5.1.0",
@@ -90,11 +95,12 @@
     "webpack-dev-server": "^3.11.0"
   },
   "peerDependencies": {
-    "react": "^16.13.1",
-    "react-dom": "^16.13.1"
+    "react": "^16.8.0 || ^17",
+    "react-dom": "^16.8.0 || ^17"
   },
   "dependencies": {
     "prop-types": "^15.7.2",
-    "react-icons": "^4.1.0"
+    "react-icons": "^4.1.0",
+    "use-tree-state": "^1.0.0"
   }
 }