Skip to content

Commit a8bb716

Browse files
liatgoliorheber
liatgo
and
liorheber
authored
Update README file (#147)
* Update README file * changes after review + pass styles + allow icon renderers in material tree Co-authored-by: Lior Heber <lior.heber@kenshoo.com>
1 parent ee4fd71 commit a8bb716

File tree

12 files changed

+561
-22
lines changed

12 files changed

+561
-22
lines changed

‎README.md

+216-9
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,39 @@
1-
# React Tress
1+
# React Tree
22

33
[![Build Status](https://travis-ci.org/kenshoo/react-tree.svg?branch=master)](https://travis-ci.org/kenshoo/react-tree)
44
[![Test Coverage](https://api.codeclimate.com/v1/badges/7b44acc9042c5ee410a8/test_coverage)](https://codeclimate.com/github/kenshoo/react-tree/test_coverage)
55

6-
Code usage:
6+
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.
77

8+
## Optional Themes
9+
10+
Two optional themes are supported when using React Tree:
11+
- Basic tree: using @emotion/core.
12+
- 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
813

14+
Both options support component customization.
15+
16+
Examples - https://github.com/kenshoo/react-tree/blob/master/packages/docs/stories/core.stories.js
17+
18+
## Basic tree
19+
20+
<p align="center">
21+
<img src="core-tree-demo.gif?raw=true" width="400" />
22+
</p>
23+
24+
### Installation
25+
26+
**Installation using npm:**
27+
```
28+
npm install @kenshooui/react-tree --save
29+
```
30+
**Installation using Yarn:**
31+
32+
```
33+
yarn add @kenshooui/react-tree
34+
```
35+
36+
### How to use
937
<!-- example -->
1038

1139
```jsx
@@ -31,12 +59,191 @@ const structure = [
3159
/>;
3260
```
3361

34-
## Props
62+
### Props
63+
64+
| Name | Type | Default | Description |
65+
| :------------------ | :---------- | :--------------------- | :-------------------------------------------------------------- |
66+
| `structure` | `Array` | `[]` | `Component input - array of leaves along with their ancestors` |
67+
| `title` | `String` | `""` | `Title to be displayed on root mode` |
68+
| `onSelect` | `Func` | `() => {}` | `callback when clicking a leaf` |
69+
| `styles` | `Object` | | `Optional - enables customized styles` |
70+
| `width` | `number` | `230 ` | `The width of the tree component` |
71+
| `height` | `number` | `300 ` | `The height of the tree component` |
72+
| `noResultsText` | `String` | `No matching results` | `The message to be displayed when having no results on searching` |
73+
| `noResultsRenderer` | `Component` | `no_matching_items.js` | `Component to replace the default NoResults component. ` |
74+
| `noResultsIconRenderer`| `Component` | | `Component to replace the default NoResultsIcon component.` |
75+
| `headerRenderer` | `Component` | `header.js` | `Component to replace the default Header component.` |
76+
| `backIconRenderer` | `Component` | | `Component to replace the default BackIcon component. ` |
77+
| `inputRenderer` | `Component` | `input.js️` | `Component to replace the default Input component. ` |
78+
| `inputIconRenderer` | `Component` | | `Component to replace the default InputIcon component. ` |
79+
| `clearIconRenderer` | `Component` | | `Component to replace the default CleaseIcon component. ` |
80+
| `itemRenderer` | `Component` | `item.js️` | `Component to replace the default Item component. ` |
81+
| `itemsRenderer` | `Component` | `items.js` | `Component to replace the default Items component. ` |
82+
| `forwardIconRenderer` | `Component` | | `Component to replace the default ForwardIcon component. ` |
83+
| `treeContainerRenderer`| `Component` | `tree_container.js` | `Component to replace the default TreeContainer component. ` |
84+
| `markSelectedItem` | `boolean` | `false` | `Toggle to mark selected item. ` |
85+
86+
<br/>
87+
88+
### Customization
89+
90+
#### Styling
91+
92+
The basic tree gets "styles" object property.
93+
<br/>
94+
If the "styles" object is empty, the basic tree will use the default styles.
95+
<br/>
96+
The "styles" object can override any of the following:
97+
- container - tree container
98+
- header - tree header. Displays tree title or item's parents
99+
- headerBackIcon - back icon
100+
- item - a single item from the hierarchical tree.
101+
- highlight - the style of the searched (highlighted) letters of an item
102+
- searchItemInitial: the style of the basic ("not searched") letters of an item
103+
- parents - the style of parents sub-title on search
104+
- items - items list container
105+
- noResults - displayed when there are no found items
106+
- noResultsIcon - the icon displayed when there are no found items
107+
- noResultsText - the massage displayed when there are no found items
108+
- input - search input
109+
- searchInput - the icon of the search input
110+
- clearInput - the icon of the search input "clear" button
111+
- forwardIcon - the icon that is part of the item component. Displayed when the item has children.
112+
- selectedItem - the style of the selectedItem item
113+
- inputWrapper - the style of input wrapper
114+
115+
<br/>
116+
117+
#### Renderers
118+
119+
You can replace the renderers of the following components:
120+
121+
<br/>
122+
123+
**Container**
124+
125+
Use the `treeContainerRenderer` to replace the default component.
126+
127+
Each treeContainer receives the following props:
128+
129+
`containerRef` - Holds a reference to the tree container component
130+
131+
`children` - Holds all sub components (like header, input, items, etc..)
132+
133+
`getStyles` - Gets relevant styles
134+
135+
`styles` - Enables using customized styles
136+
137+
<br/>
138+
139+
**Header**
140+
141+
Use the `headerRenderer` to replace the default component.
142+
143+
Each header receives the following props:
144+
145+
`headerRef` - Holds a reference to the header component
146+
147+
`parents` - Holds the parents of the current level.
148+
<br/>
149+
For example for the following structure: ["Profiles", "Performance", "Clicks"]
150+
- In the first level the parents are: [""]
151+
- In the second level the parents are: ["Profile"]
152+
- In the third level the parents are: ["Profile, "Performance"]
153+
154+
155+
`onClick` - Triggers the back event on click
156+
157+
`title` - The title of the header. Displayed on the first level.
158+
159+
`getStyles` - Gets relevant styles
160+
161+
`styles` - Enables using customized styles
162+
163+
`backIconRenderer` - Use the `backIconRenderer` to replace the default back button component.
164+
165+
<br/>
166+
167+
**Input**
168+
169+
Use the `inputRenderer` to replace the default component.
170+
171+
Each header receives the following props:
172+
173+
`inputRef` - Holds a reference to the input component
174+
175+
`searchTerm` - Holds the searched value
176+
177+
`onInputChange` - Triggers set searchTerm event on change
178+
179+
`getStyles` - Gets relevant styles
180+
181+
`styles` - Enables using customized styles
182+
183+
`inputIconRenderer` - Use the `inputIconRenderer` to replace the default input icon component.
184+
185+
`clearIconRenderer` - Use the `clearIconRenderer` to replace the default clear input icon component.
186+
187+
<br/>
188+
189+
**Items**
190+
191+
Use the `itemsRenderer` to replace the default component.
192+
193+
Each header receives the following props:
194+
195+
`getStyles` - Gets relevant styles
196+
197+
`styles` - Enables using customized styles
198+
199+
`children` - All items
200+
201+
<br/>
202+
203+
**Item**
204+
205+
Use the `itemRenderer` to replace the default component
206+
207+
Each header receives the following props:
208+
209+
`getStyles` - Gets relevant styles
210+
211+
`styles` - Enables using customized styles
212+
213+
`searchTerm` - Holds the searched value
214+
215+
`item` - Represents an item from the given structure
216+
217+
`onClick` - Is called when clicking on an item
218+
219+
`forwardIconRenderer` - Use the `forwardIconRenderer` to replace the default forward icon component
220+
221+
`selectedItem` - Represents the current selected item. Is relevant when markSelectedItem = true
222+
223+
<br/>
224+
225+
**No Results**
226+
227+
Use the `noResultsRenderer` to replace the default component.
228+
229+
`getStyles` - Gets relevant styles
230+
231+
`styles` - Enables using customized styles
232+
233+
`text` - Displayed when there are no results
234+
235+
`noResultsIconRenderer` - Use the `noResultsIconRenderer` to replace the default no results warning icon component.
236+
237+
238+
## How to Contribute
239+
240+
#### Setting up development environment
241+
242+
1. Fork the repository and create your branch from `master`.
243+
2. Install the project: `yarn install`
244+
3. Run tests: `yarn test` or `yarn test:watch`
245+
4. Run dev environment: `yarn storybook` and head to [https://localhost:6006](https://localhost:6006)
35246

36-
| Name | Type | Default | Description |
37-
| :------------------ | :-------- | :--------------------- | :-------------------------------------------------------------- |
38-
| `structure` | `Array` | `[]` | `Component input - array of leaves along with their ancestors` |
39-
| `title` | `String` | `` | `Title to be displayed on root mode` |
40-
| `onSelect` | `Func` | `` | `callback when clicking a leaf` |
41-
| `NoResultsRenderer` | `` | `no_matching_items.js` | `renderer when having no results on searching` |
247+
## Credit
42248

249+
Styling patterns were taken from react-select - https://github.com/JedWatson/react-select/blob/master/README.md

‎core-tree-demo.gif

360 KB
Loading

‎packages/core/src/tree.js

+6-1
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ const Tree = props => {
2525
onSelect,
2626
width,
2727
height,
28+
styles,
2829
noResultsText = "No matching results",
2930
headerRenderer: Header = HeaderDefault,
3031
backIconRenderer,
@@ -66,6 +67,7 @@ const Tree = props => {
6667
<TreeContainer
6768
containerRef={containerRef}
6869
getStyles={getStyles}
70+
styles={styles}
6971
width={(width || DEFAULT_WIDTH) + PIXEL_SUFFIX}
7072
height={(height || DEFAULT_HEIGHT) + PIXEL_SUFFIX}
7173
>
@@ -75,18 +77,20 @@ const Tree = props => {
7577
title={title}
7678
onClick={onBackClick}
7779
getStyles={getStyles}
80+
styles={styles}
7881
backIconRenderer={backIconRenderer}
7982
>
8083
{title}
8184
</Header>
8285
<Input
8386
inputRef={inputRef}
8487
getStyles={getStyles}
88+
styles={styles}
8589
searchTerm={searchTerm}
8690
onInputChange={onInputChange}
8791
inputIconRenderer={inputIconRenderer}
8892
/>
89-
<Items getStyles={getStyles} height={itemsHeight}>
93+
<Items styles={styles} getStyles={getStyles} height={itemsHeight}>
9094
{leaves &&
9195
leaves.length > 0 &&
9296
leaves.map(item => (
@@ -104,6 +108,7 @@ const Tree = props => {
104108
height={itemsHeight}
105109
text={noResultsText}
106110
getStyles={getStyles}
111+
styles={styles}
107112
noResultsIconRenderer={noResultsIconRenderer}
108113
/>
109114
)}

‎packages/docs/stories/core.stories.js

+39-2
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,12 @@ import React from "react";
22
import Tree from "@kenshooui/react-tree";
33
import MaterialTree from "@kenshooui/material-tree";
44
import makeStyles from "@material-ui/core/styles/makeStyles";
5+
import {
6+
CustomForwardIcon,
7+
CustomHeader,
8+
CustomSearchIcon,
9+
customStyles
10+
} from "./custom_renderers";
511

612
const useStyles = makeStyles({
713
wrapper: {
@@ -57,13 +63,33 @@ export const Basic = () => {
5763
return (
5864
<div className={classes.wrapper}>
5965
<div className={classes.item}>
60-
<div className={classes.title}>Default Dimensions</div>
66+
<div className={classes.title}>Default Tree</div>
6167
<Tree
6268
structure={structure}
6369
title={"Choose an item"}
6470
onSelect={item => alert(item)}
6571
/>
6672
</div>
73+
<div className={classes.item}>
74+
<div className={classes.title}>Custom Renderers</div>
75+
<Tree
76+
structure={structure}
77+
title={"Choose an item"}
78+
onSelect={item => alert(item)}
79+
headerRenderer={CustomHeader}
80+
forwardIconRenderer={CustomForwardIcon}
81+
inputIconRenderer={CustomSearchIcon}
82+
/>
83+
</div>
84+
<div className={classes.item}>
85+
<div className={classes.title}>Custom Styles</div>
86+
<Tree
87+
structure={structure}
88+
title={"Choose an item"}
89+
onSelect={item => alert(item)}
90+
styles={customStyles}
91+
/>
92+
</div>
6793
<div className={classes.item}>
6894
<div className={classes.title}>Custom Dimensions</div>
6995
<Tree
@@ -83,11 +109,22 @@ export const MaterialTheme = () => {
83109
return (
84110
<div className={classes.wrapper}>
85111
<div className={classes.item}>
86-
<div className={classes.title}>Default Dimensions</div>
112+
<div className={classes.title}>Default Tree</div>
113+
<MaterialTree
114+
structure={structure}
115+
title={"Choose an item"}
116+
onSelect={item => alert(item)}
117+
/>
118+
</div>
119+
<div className={classes.item}>
120+
<div className={classes.title}>Custom Renderers</div>
87121
<MaterialTree
88122
structure={structure}
89123
title={"Choose an item"}
90124
onSelect={item => alert(item)}
125+
headerRenderer={CustomHeader}
126+
forwardIconRenderer={CustomForwardIcon}
127+
inputIconRenderer={CustomSearchIcon}
91128
/>
92129
</div>
93130
<div className={classes.item}>

0 commit comments

Comments
 (0)