diff --git a/README.md b/README.md index 23fe94d..958d6a7 100644 --- a/README.md +++ b/README.md @@ -8,56 +8,23 @@ React Tree is a straight forward component that allows a user to display and man ## Optional Themes Two optional themes are supported when using React Tree: -- Basic tree: using @emotion/core. -- Material tree: based on the basic tree logic, using Material-UI components - https://github.com/kenshoo/react-tree/blob/master/packages/material_tree/README.md + #### Basic tree + Includes all the logic, based on @emotion/core - [README](https://github.com/kenshoo/react-tree/blob/master/packages/core/README.md) -Both options support component customization. - -Examples - https://github.com/kenshoo/react-tree/blob/master/packages/docs/stories/core.stories.js - - ## Basic tree -

- +

- ### Installation - - **Installation using npm:** - ``` - npm install @kenshooui/react-tree --save - ``` - **Installation using Yarn:** - -``` - yarn add @kenshooui/react-tree -``` - - ### How to use - + #### Material tree + Based on the basic tree logic, using Material-UI components - [README](https://github.com/kenshoo/react-tree/blob/master/packages/material_tree/README.md) -```jsx -import ReactTree from "@kenshooui/react-tree"; +

+ +

-const structure = [ - ["Profiles", "Performance", "Clicks"], - ["Profiles", "Performance", "Imp"], - ["Profiles", "Attribute", "Agency"], - ["Profiles", "Attribute", "Progress"], - ["Profiles", "Attribute", "Create Date"], - ["Campaigns", "Performance", "Clicks"], - ["Campaigns", "Performance", "Cost"], - ["Campaigns", "Performance", "CTR"], - ["Campaigns", "Attribute", "campaign name"], - ["Ad Groups", "Attribute", "Ad Group Name"] -]; +Both options support component customization. - [examples](https://github.com/kenshoo/react-tree/blob/master/packages/docs/stories/core.stories.js) - {}} -/>; -``` +
### Props @@ -85,156 +52,6 @@ const structure = [
-### Customization - -#### Styling - -The basic tree gets "styles" object property. -
-If the "styles" object is empty, the basic tree will use the default styles. -
-The "styles" object can override any of the following: - - container - tree container - - header - tree header. Displays tree title or item's parents - - headerBackIcon - back icon - - item - a single item from the hierarchical tree. - - highlight - the style of the searched (highlighted) letters of an item - - searchItemInitial: the style of the basic ("not searched") letters of an item - - parents - the style of parents sub-title on search - - items - items list container - - noResults - displayed when there are no found items -- noResultsIcon - the icon displayed when there are no found items -- noResultsText - the massage displayed when there are no found items - - input - search input -- searchInput - the icon of the search input - - clearInput - the icon of the search input "clear" button - - forwardIcon - the icon that is part of the item component. Displayed when the item has children. - - selectedItem - the style of the selectedItem item - - inputWrapper - the style of input wrapper - -
- -#### Renderers - -You can replace the renderers of the following components: - -
- -**Container** - -Use the `treeContainerRenderer` to replace the default component. - -Each treeContainer receives the following props: - -`containerRef` - Holds a reference to the tree container component - -`children` - Holds all sub components (like header, input, items, etc..) - -`getStyles` - Gets relevant styles - -`styles` - Enables using customized styles - -
- -**Header** - -Use the `headerRenderer` to replace the default component. - -Each header receives the following props: - -`headerRef` - Holds a reference to the header component - -`parents` - Holds the parents of the current level. -
-For example for the following structure: ["Profiles", "Performance", "Clicks"] -- In the first level the parents are: [""] -- In the second level the parents are: ["Profile"] -- In the third level the parents are: ["Profile, "Performance"] - - -`onClick` - Triggers the back event on click - -`title` - The title of the header. Displayed on the first level. - -`getStyles` - Gets relevant styles - -`styles` - Enables using customized styles - -`backIconRenderer` - Use the `backIconRenderer` to replace the default back button component. - -
- -**Input** - -Use the `inputRenderer` to replace the default component. - -Each header receives the following props: - -`inputRef` - Holds a reference to the input component - -`searchTerm` - Holds the searched value - -`onInputChange` - Triggers set searchTerm event on change - -`getStyles` - Gets relevant styles - -`styles` - Enables using customized styles - -`inputIconRenderer` - Use the `inputIconRenderer` to replace the default input icon component. - -`clearIconRenderer` - Use the `clearIconRenderer` to replace the default clear input icon component. - -
- -**Items** - -Use the `itemsRenderer` to replace the default component. - -Each header receives the following props: - -`getStyles` - Gets relevant styles - -`styles` - Enables using customized styles - -`children` - All items - -
- -**Item** - -Use the `itemRenderer` to replace the default component - -Each header receives the following props: - -`getStyles` - Gets relevant styles - -`styles` - Enables using customized styles - -`searchTerm` - Holds the searched value - -`item` - Represents an item from the given structure - -`onClick` - Is called when clicking on an item - -`forwardIconRenderer` - Use the `forwardIconRenderer` to replace the default forward icon component - -`selectedItem` - Represents the current selected item. Is relevant when markSelectedItem = true - -
- -**No Results** - -Use the `noResultsRenderer` to replace the default component. - -`getStyles` - Gets relevant styles - -`styles` - Enables using customized styles - -`text` - Displayed when there are no results - -`noResultsIconRenderer` - Use the `noResultsIconRenderer` to replace the default no results warning icon component. - - ## How to Contribute #### Setting up development environment @@ -246,4 +63,4 @@ Use the `noResultsRenderer` to replace the default component. ## Credit -Styling patterns were taken from react-select - https://github.com/JedWatson/react-select/blob/master/README.md +Styling patterns were taken from react-select - [README](https://github.com/JedWatson/react-select/blob/master/README.md) diff --git a/packages/core/README.md b/packages/core/README.md new file mode 100644 index 0000000..0f217e8 --- /dev/null +++ b/packages/core/README.md @@ -0,0 +1,203 @@ +# React Tree + +React Tree is a straight forward component that allows a user to display and manage a hierarchical structure of items in a clear and comfortable way. + +The basic tree is built using @emotion/core, and supports both styling and component renderers customizations. + +[Examples](https://github.com/kenshoo/react-tree/blob/master/packages/docs/stories/core.stories.js) + + +

+ +

+ + ### Installation + + **Installation using npm:** + ``` + npm install @kenshooui/react-tree --save + ``` + **Installation using Yarn:** + +``` + yarn add @kenshooui/react-tree +``` + + ### How to use + + +```jsx +import ReactTree from "@kenshooui/react-tree"; + +const structure = [ + ["Profiles", "Performance", "Clicks"], + ["Profiles", "Performance", "Imp"], + ["Profiles", "Attribute", "Agency"], + ["Profiles", "Attribute", "Progress"], + ["Profiles", "Attribute", "Create Date"], + ["Campaigns", "Performance", "Clicks"], + ["Campaigns", "Performance", "Cost"], + ["Campaigns", "Performance", "CTR"], + ["Campaigns", "Attribute", "campaign name"], + ["Ad Groups", "Attribute", "Ad Group Name"] +]; + + {}} +/>; +``` + +### Props +Can be found - [here](https://github.com/kenshoo/react-tree#props) +
+ +### Customization + +#### Styling + +The basic tree gets "styles" object property. +
+If the "styles" object is empty, the basic tree will use the default styles. +
+The "styles" object can override any of the following: + - container - tree container + - header - tree header. Displays tree title or item's parents + - headerBackIcon - back icon + - item - a single item from the hierarchical tree. + - highlight - the style of the searched (highlighted) letters of an item + - searchItemInitial: the style of the basic ("not searched") letters of an item + - parents - the style of parents sub-title on search + - items - items list container + - noResults - displayed when there are no found items +- noResultsIcon - the icon displayed when there are no found items +- noResultsText - the massage displayed when there are no found items + - input - search input +- searchInput - the icon of the search input + - clearInput - the icon of the search input "clear" button + - forwardIcon - the icon that is part of the item component. Displayed when the item has children. + - selectedItem - the style of the selectedItem item + - inputWrapper - the style of input wrapper + +
+ +#### Renderers + +You can replace the renderers of the following components: + +
+ +**Container** + +Use the `treeContainerRenderer` to replace the default component. + +Each treeContainer receives the following props: + +`containerRef` - Holds a reference to the tree container component + +`children` - Holds all sub components (like header, input, items, etc..) + +`getStyles` - Gets relevant styles + +`styles` - Enables using customized styles + +
+ +**Header** + +Use the `headerRenderer` to replace the default component. + +Each header receives the following props: + +`headerRef` - Holds a reference to the header component + +`parents` - Holds the parents of the current level. +
+For example for the following structure: ["Profiles", "Performance", "Clicks"] +- In the first level the parents are: [""] +- In the second level the parents are: ["Profile"] +- In the third level the parents are: ["Profile, "Performance"] + + +`onClick` - Triggers the back event on click + +`title` - The title of the header. Displayed on the first level. + +`getStyles` - Gets relevant styles + +`styles` - Enables using customized styles + +`backIconRenderer` - Use the `backIconRenderer` to replace the default back button component. + +
+ +**Input** + +Use the `inputRenderer` to replace the default component. + +Each header receives the following props: + +`inputRef` - Holds a reference to the input component + +`searchTerm` - Holds the searched value + +`onInputChange` - Triggers set searchTerm event on change + +`getStyles` - Gets relevant styles + +`styles` - Enables using customized styles + +`inputIconRenderer` - Use the `inputIconRenderer` to replace the default input icon component. + +`clearIconRenderer` - Use the `clearIconRenderer` to replace the default clear input icon component. + +
+ +**Items** + +Use the `itemsRenderer` to replace the default component. + +Each header receives the following props: + +`getStyles` - Gets relevant styles + +`styles` - Enables using customized styles + +`children` - All items + +
+ +**Item** + +Use the `itemRenderer` to replace the default component + +Each header receives the following props: + +`getStyles` - Gets relevant styles + +`styles` - Enables using customized styles + +`searchTerm` - Holds the searched value + +`item` - Represents an item from the given structure + +`onClick` - Is called when clicking on an item + +`forwardIconRenderer` - Use the `forwardIconRenderer` to replace the default forward icon component + +`selectedItem` - Represents the current selected item. Is relevant when markSelectedItem = true + +
+ +**No Results** + +Use the `noResultsRenderer` to replace the default component. + +`getStyles` - Gets relevant styles + +`styles` - Enables using customized styles + +`text` - Displayed when there are no results + +`noResultsIconRenderer` - Use the `noResultsIconRenderer` to replace the default no results warning icon component. diff --git a/packages/core/core-tree-demo.gif b/packages/core/core-tree-demo.gif new file mode 100644 index 0000000..d5ca970 Binary files /dev/null and b/packages/core/core-tree-demo.gif differ diff --git a/packages/core/src/tree.js b/packages/core/src/tree.js index 249af39..daa76a0 100644 --- a/packages/core/src/tree.js +++ b/packages/core/src/tree.js @@ -26,6 +26,7 @@ const Tree = props => { width, height, styles, + className, noResultsText = "No matching results", headerRenderer: Header = HeaderDefault, backIconRenderer, diff --git a/packages/material_tree/README.md b/packages/material_tree/README.md index 93dc8c4..bf29afd 100644 --- a/packages/material_tree/README.md +++ b/packages/material_tree/README.md @@ -7,34 +7,26 @@ a user to display and manage a hierarchical structure of items using Material

- +

### Installation - Since Material Rree is based on React Tree logic, you need to install both react-tree and material-tree. + Since Material Rree is based on React Tree< logic, you need to install both @kenshooui/react-tree and @kenshooui/material-tree. - In addition, dependencies to material-ui icons and core components are needed if they don't exist in your project. + Dependencies to @material-ui/core and @material-ui/icons are needed only if they don't exist in your project. **Installation using npm:** ``` - npm install @kenshooui/material-tree --save + npm install --save @kenshooui/react-tree @kenshooui/material-tree - npm install @kenshooui/react-tree --save - - npm install @material-ui/core --save - - npm install @material-ui/icons --save + npm install --save @material-ui/core @material-ui/icons ``` **Installation using Yarn:** ``` - yarn add @kenshooui/material-tree - - yarn add @kenshooui/react-tree + yarn add @kenshooui/material-tree @kenshooui/react-tree - yarn add @material-ui/core - - yarn add @material-ui/icons + yarn add @material-ui/core @material-ui/icons ``` ### How to use @@ -64,29 +56,7 @@ const structure = [ ``` ### Props - -| Name | Type | Default | Description | -| :------------------ | :---------- | :--------------------- | :-------------------------------------------------------------- | -| `structure` | `Array` | `[]` | `Component input - array of leaves along with their ancestors` | -| `title` | `String` | `""` | `Title to be displayed on root mode` | -| `onSelect` | `Func` | `() => {}` | `callback when clicking a leaf` | -| `styles` | `Object` | | `Optional - enables customized styles` | -| `width` | `number` | `230 ` | `The width of the tree component` | -| `height` | `number` | `300 ` | `The height of the tree component` | -| `noResultsText` | `String` | `No matching results` | `The message the is displayed when having no results on searching` | -| `noResultsRenderer` | `Component` | `no_results.js` | `Component to replace the default NoResults component. Renders when having no results on searching` | -| `noResultsIconRenderer`| `Component` | `Warning icon` | `Component to replace the default NoResultsIcon component.` | -| `headerRenderer` | `Component` | `header.js` | `Component to replace the default Header component.` | -| `backIconRenderer` | `Component` | `ChevronLeft icon` | `Component to replace the default BackIcon component. ` | -| `inputRenderer` | `Component` | `input.js️` | `Component to replace the default Input component. ` | -| `inputIconRenderer` | `Component` | `Search icon` | `Component to replace the default InputIcon component. ` | -| `clearIconRenderer` | `Component` | `Clear icon` | `Component to replace the default CleaseIcon component. ` | -| `itemRenderer` | `Component` | `item.js️` | `Component to replace the default Item component. ` | -| `itemsRenderer` | `Component` | `items.js` | `Component to replace the default Items component. ` | -| `forwardIconRenderer` | `Component` | `ChevronRight icon` | `Component to replace the default ForwardIcon component. ` | -| `treeContainerRenderer`| `Component` | `tree_container.js` | `Component to replace the default TreeContainer component. ` | -| `markSelectedItem` | `boolean` | `false` | `Toggle to mark selected item. ` | - +Can be found - [here](https://github.com/kenshoo/react-tree#props)
### Customization @@ -194,13 +164,3 @@ Use the `noResultsRenderer` to replace the default component. `height` - The height of the items list `noResultsIconRenderer` - Use the `noResultsIconRenderer` to replace the default no results warning icon component. - - -## How to Contribute - -#### Setting up development environment - -1. Fork the repository and create your branch from `master`. -2. Install the project: `yarn install` -3. Run tests: `yarn test` or `yarn test:watch` -4. Run dev environment: `yarn storybook` and head to [https://localhost:6006](https://localhost:6006) diff --git a/react-tree-demo.gif b/react-tree-demo.gif new file mode 100644 index 0000000..eba6cfa Binary files /dev/null and b/react-tree-demo.gif differ