Skip to content

Commit e54a1bd

Browse files
author
Administrator
committed
readme
1 parent 9f1f919 commit e54a1bd

File tree

2 files changed

+89
-326
lines changed

2 files changed

+89
-326
lines changed

‎README.md‎

Lines changed: 56 additions & 268 deletions
Original file line numberDiff line numberDiff line change
@@ -1,300 +1,88 @@
1-
# React Component Library
1+
### React Component Library - code4bones react UI
22

3-
[![Build status](https://badge.buildkite.com/90ff98db996bb137c5be1bdce666c4b1ce68a25b17af0a6a04.svg?branch=master)](https://buildkite.com/harvey/react-component-library)
4-
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
3+
### Components
4+
5+
| Component| Description |
6+
| ------------ | ------------ |
7+
| TreeMenu | Navigation Menu Tree |
58

6-
This project skeleton was created to help people get started with creating their own React component library using:
79

8-
- [Rollup](https://github.com/rollup/rollup)
9-
- [Sass](https://sass-lang.com/)
10-
- [TypeScript](https://www.typescriptlang.org/)
10+
# react-c4b-ui
1111

12-
It also features:
1312

14-
- [Storybook](https://storybook.js.org/) to help you create and show off your components
15-
- [Jest](https://jestjs.io/) and [React Testing Library](https://github.com/testing-library/react-testing-library) enabling testing of the components
13+
![](https://img.shields.io/github/downloads/code4bones/react-c4b-ui/treemenu/total) ![](https://img.shields.io/github/watchers/code4bones/react-c4b-ui) ![](https://img.shields.io/github/forks/code4bones/react-c4b-ui) ![](https://img.shields.io/github/tag/code4bones/react-c4b-ui) ![](https://img.shields.io/github/release/code4bones/react-c4b-ui) ![](https://img.shields.io/github/issues/code4bones/react-c4b-ui)
1614

17-
[**Read my blog post about why and how I created this project skeleton ▸**](https://blog.harveydelaney.com/creating-your-own-react-component-library/)
15+
###Links
1816

19-
[Check out this CodeSandbox to see the component library in action ▸](https://codesandbox.io/s/harvey-component-library-example-y2b60)
17+
[Change log](https://github.com/code4bones/react-c4b-ui/wiki/Change-Log "Change log")
2018

21-
## Development
19+
### Install
2220

23-
### Testing
2421

25-
```
26-
npm run test
27-
```
28-
29-
### Building
30-
31-
```
32-
npm run build
33-
```
34-
35-
### Storybook
36-
37-
To run a live-reload Storybook server on your local machine:
38-
39-
```
40-
npm run storybook
41-
```
42-
43-
To export your Storybook as static files:
44-
45-
```
46-
npm run storybook:export
47-
```
48-
49-
You can then serve the files under `storybook-static` using S3, GitHub pages, Express etc. I've hosted this library at: https://www.harveydelaney.com/react-component-library
50-
51-
### Generating New Components
52-
53-
I've included a handy NodeJS util file under `util` called `create-component.js`. Instead of copy pasting components to create a new component, you can instead run this command to generate all the files you need to start building out a new component. To use it:
54-
55-
```
56-
npm run generate YourComponentName
57-
```
58-
59-
This will generate:
60-
61-
```
62-
/src
63-
/YourComponentName
64-
YourComponentName.tsx
65-
YourComponentName.stories.tsx
66-
YourComponentName.test.tsx
67-
YourComponentName.types.ts
68-
YourComponentName.scss
69-
```
70-
71-
The default templates for each file can be modified under `util/templates`.
72-
73-
Don't forget to add the component to your `index.ts` exports if you want the library to export the component!
74-
75-
### Installing Component Library Locally
76-
77-
Let's say you have another project (`test-app`) on your machine that you want to try installing the component library into without having to first publish the component library. In the `test-app` directory, you can run:
78-
79-
```
80-
npm i --save ../react-component-library
81-
```
82-
83-
which will install the local component library as a dependency in `test-app`. It'll then appear as a dependency in `package.json` like:
84-
85-
```
86-
...
87-
"dependencies": {
88-
...
89-
"react-component-library": "file:../react-component-library",
90-
...
91-
},
92-
...
93-
```
94-
95-
Your components can then be imported and used in that project.
96-
97-
**NOTE**: After installing the component library locally, you may run into:
98-
99-
```
100-
Invalid hook call. Hooks can only be called inside of the body of a function component. This could happen for one of the following reasons:
101-
102-
You might have mismatching versions of React and the renderer (such as React DOM)
103-
You might be breaking the Rules of Hooks
104-
You might have more than one copy of React in the same app See for tips about how to debug and fix this problem.
105-
```
106-
107-
This is the most commonly encountered problem people face when installing the library locally. This is most likely due to the third reason: `You might have more than one copy of React in the app`.
108-
109-
Normally when a library is published, dev dependencies are excluded. However, when the library is symlinked, all local dev depdendencies are persisted in the libraries `node_modules` (includes React). Your bundler may see two versions of React, one in the consuming app and one in the symlinked library. The solution is to have the component library use the React version in the consuming app. So from your component library folder, run:
110-
111-
```
112-
npm link ../test-app/node_modules/react
113-
```
114-
115-
**OR**, if you are using Webpack in app you can follow [this GitHub comment](https://github.com/facebook/react/issues/13991#issuecomment-435587809).
116-
117-
Read more about this issue [here](https://reactjs.org/warnings/invalid-hook-call-warning.html).
118-
119-
## Publishing
120-
121-
### Hosting via NPM
122-
123-
First, make sure you have an NPM account and are [logged into NPM using the `npm login` command.](https://docs.npmjs.com/creating-a-new-npm-user-account)
124-
125-
Then update the `name` field in `package.json` to reflect your NPM package name in your private or public NPM registry. Then run:
126-
127-
```
128-
npm publish
129-
```
130-
131-
The `"prepublishOnly": "npm run build"` script in `package.json` will execute before publish occurs, ensuring the `build/` directory and the compiled component library exist.
132-
133-
### Hosting via GitHub
134-
135-
I recommend you host the component library using NPM. However, if you don't want to use NPM, you can use GitHub to host it instead.
22+
`$ npm install react-c4b-ui`
13623

137-
You'll need to remove `build/` from `.gitignore`, build the component library (`npm run build`), add, commit and push the contents of `build`. [See this branch for an example.](https://github.com/HarveyD/react-component-library/tree/host-via-github)
24+
#### Initial usage
13825

139-
You can then install your library into other projects by running:
140-
141-
```
142-
npm i --save git+https://github.com/HarveyD/react-component-library.git#branch-name
143-
```
144-
145-
OR
146-
147-
```
148-
npm i --save github:harveyd/react-component-library#branch-name
149-
```
150-
151-
## Usage
152-
153-
Let's say you created a public NPM package called `harvey-component-library` with the `TestComponent` component created in this repository.
154-
155-
Usage of the component (after the library installed as a dependency into another project) will be:
156-
157-
```TSX
158-
import React from "react";
159-
import { TestComponent } from "harvey-component-library";
160-
161-
const App = () => (
162-
<div className="app-container">
163-
<h1>Hello I'm consuming the component library</h1>
164-
<TestComponent theme="primary" />
165-
</div>
166-
);
167-
168-
export default App;
169-
```
170-
171-
[Check out this Code Sandbox for a live example.](https://codesandbox.io/s/harvey-component-library-example-y2b60?file=/src/App.js)
172-
173-
### Using Component Library SASS Variables
174-
175-
I've found that it's helpful to export SASS variables to projects consuming the library. As such, I've added the `rollup-plugin-copy` NPM package and used it to copy the [`src/typography.scss`](src/typography.scss) and [`variables.scss`](src/variables.scss) into the `build` directory as part of the Rollup bundle process. This allows you to use these variables in your projects consuming the component library.
176-
177-
For example, let's say you installed `harvey-component-library` into your project. To use the exported variables/mixins, in a SASS file you would do the following:
178-
179-
```Sass
180-
@import '~harvey-component-library/build/typography';
181-
182-
.example-container {
183-
@include heading;
184-
185-
color: $harvey-white;
186-
}
187-
```
188-
189-
## Additional Help
190-
191-
### Dark Mode
192-
193-
The example component `TestComponent` respects the user's dark mode operating system preferences and renders the component in the appropriate theme.
194-
195-
This is achieved by using the media query: `@media (prefers-color-scheme: dark)` in combination with CSS variables. The colours that change depending on dark mode preference can be found in [`src/variables.scss`](src/variables.scss). Example usage of these variables can be found within [`src/TestComponent/TestComponent.scss`](src/TestComponent/TestComponent.scss).
196-
197-
Read https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme for more details.
198-
199-
### Using Alternatives to Sass
200-
201-
#### Less or Stylus
202-
203-
The Rollup plugin `rollup-plugin-postcss` supports Sass, Less and Stylus:
204-
205-
- For Stylus, install stylus: `yarn add stylus --dev`
206-
- For Less, install less: `yarn add less --dev`
207-
208-
You can then remove `node-sass` from your dependencies.
209-
210-
#### CSS Modules
211-
212-
If you want to use CSS Modules, update `postcss` in `rollup-config.js` to:
213-
214-
```
215-
postcss({
216-
modules: true
217-
})
218-
```
219-
220-
#### Styled Components
26+
```tsx
22127

222-
If you want to use [`styled-components`](https://styled-components.com/), the changes required are a bit more involved. As such, I've created a branch where I've got `styled-components` working in this component library, [check it out here](https://github.com/HarveyD/react-component-library/tree/styled-components).
28+
const ITEMS : TreeMenuItem[] = [{ ... }]
22329

224-
### Component Code Splitting
30+
const ref = createRef<TreeMenuActions>();
22531

226-
Code splitting of your components is not supported by default.
22732

228-
[Read this section of my blog post](https://blog.harveydelaney.com/creating-your-own-react-component-library/#introducing-code-splitting-optional-) to find out how and why you would enable code splitting of your components. In summary, code splitting enables users to import components in isolation like:
33+
<TreeMenu
34+
ref={ref}
35+
items={ITEMS}
36+
onClick={onClick}
37+
/>
22938

23039
```
231-
import TestComponent from 'harvey-component-library/build/TestComponent';
232-
```
233-
234-
This can reduce the bundle size for projects using older (CJS) module formats.
23540

236-
You can check out [this branch](https://github.com/HarveyD/react-component-library/tree/code-splitting) or [this commit](https://github.com/HarveyD/react-component-library/commit/94631be5a871f3b39dbc3e9bd3e75a8ae5b3b759) to see what changes are neccesary to implement it.
41+
### Properties
23742

238-
Please note, there's an issue with code splitting and using `rollup-plugin-postcss`. I recommend using `rollup-plugin-sass` instead alongside code splitting.
43+
| Propery name | Description | Signature
44+
| ------------- | ------------------------------ | ---- |
45+
| `items[]` | tree menu items array | `TreeMenuItem`[] |
46+
| `re` | handle to TreeMenu methods | `TreeMenuActions` |
47+
| `onClick` | item click handler | onClick?:(item:TreeMenuItem) => void|
48+
| `onToggle` | collapse / expand | onToggle?:(id?:string,collapsed?:boolean) => void;|
49+
| `initialCollapsed` | initial tree state | boolean |
50+
| `initialSelected` | initial selected item | item's `id` : string|
51+
| `renderBadge` | item click handler | (item:TreeMenuItem) => React.ReactElement|
52+
| `renderIcon` | Left side element of item | onClick?:(item:TreeMenuItem) => void|
53+
| `renderGroupState` | Group indicator | onClick?:(item:TreeMenuItem) => void|
54+
| `renderBadge` | Right side element of item | onClick?:(item:TreeMenuItem) => void|
55+
| `theme` | theme override class name | `dark`, `light`, custom name |
56+
| `classPrefix` | container global prefix | string |
57+
| `enableRotate` | Rotate collapse / expand | boolean |
23958

240-
### Supporting Image Imports
24159

242-
Add the following library to your component library [@rollup/plugin-image](https://github.com/rollup/plugins/tree/master/packages/image):
243-
244-
```
245-
npm i -D @rollup/plugin-image
246-
```
247-
248-
Then add it to `rollup-config.js`:
249-
250-
```
251-
...
252-
plugins:[
253-
...,
254-
image(),
255-
...
256-
]
257-
...
258-
```
259-
260-
You can then import and render images in your components like:
60+
`TreeMenuItem`
26161

26262
```tsx
263-
import logo from "./rollup.png";
63+
id:string;
64+
title:string | React.ReactElement;
65+
info?:string | React.ReactElement;
66+
icon?:React.ReactElement;
67+
badge?:string | React.ReactElement;
68+
disabled?:boolean;
69+
unselectable?:boolean;
70+
titleClass?:string;
71+
infoClass?:string;
72+
style?:React.CSSProperties;
73+
infoStyle?:React.CSSProperties;
26474

265-
export const ImageComponent = () => (
266-
<div>
267-
<img src={logo} />
268-
</div>
269-
);
27075
```
27176

272-
### Supporting JSON Imports
273-
274-
Add the following library to your component library [@rollup/plugin-json](https://github.com/rollup/plugins/tree/master/packages/json):
275-
77+
`TreeMenuActions` ( use `ref` )
27678
```
277-
npm i -D @rollup/plugin-json
278-
```
279-
280-
Then add it to `rollup-config.js`:
79+
enable:(id:string,disable?:boolean) => void;
80+
getItem:(id:string) => TreeMenuItem | null;
81+
collapse:(id:string,collapsed?:boolean) => void;
82+
select:(id:string) => void;
28183
28284
```
283-
...
284-
plugins:[
285-
...,
286-
json(),
287-
...
288-
]
289-
...
290-
```
291-
292-
You can then import and use JSON as ES6 Modules:
29385

294-
```tsx
295-
import data from "./some-data.json";
296-
297-
export const JsonDataComponent = () => <div>{data.description}</div>;
298-
```
86+
### Sample
29987

300-
Checkout the [official Rollup plugin list](https://github.com/rollup/plugins) for additional helpful plugins.
88+
Sample available via storybook `yarn storybook`

0 commit comments

Comments
 (0)