vitalif
/
react-toolbox
1
0
Fork 0
Code Issues Pull Requests Releases 12 Wiki Activity

Update docs

old
Javi Velasco 2016-06-03 22:24:26 +02:00
parent c356a2be5a
commit 115e839086
3 changed files with 220 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

145
README.md
View File

@ -12,28 +12,122 @@ React Toolbox is a set of [React](http://facebook.github.io/react/) components t
React Toolbox can be installed as an [npm package](https://www.npmjs.org/package/react-toolbox):
```
```bash
npm install --save react-toolbox
```
## Usage
## Prerequisites
Although there are other ways to use React Toolbox, the recommended way is to create a webpack workflow with [babel-loader](https://github.com/babel/babel-loader), [css-loader](https://github.com/webpack/css-loader) and [sass-loader](https://github.com/jtangelder/sass-loader). A good starting point is [React Hot Webpack Boilerplate](https://github.com/gaearon/react-hot-boilerplate).
React Toolbox uses [CSS Modules](https://github.com/css-modules/css-modules) and [SASS](http://sass-lang.com/) to provide default stylesheets. If you want to import components bundled with stylesheets, your module bundler should be able to require SASS modules. You can use whatever module bundler you want as long as it can require SASS files from `node_modules`, but we recommend [webpack](). If you are experiencing require errors, make sure your configuration satisfies the requirements.
Once you have the workflow ready, you can just require and use the components:
Of course this is a set of React components so you should be familiar with [React](). If you are willing to customize your components via themes, you may want to take a look to [react-css-themr]() which is used to make styling easier.
```jsx
## Basic usage
The minimal example requires a `Button` bundled with styles:
```
import React from 'react';
import Button from 'react-toolbox/lib/button';
import ReactDOM from 'react-dom';
import { Button } from 'react-toolbox/lib/button';
const CustomButton = () => (
<Button label="Hello world" raised accent />
ReactDOM.render(
<Button label="Hello World!" />,
document.getElementById('app')
);
export default CustomButton;
```
The previous code creates a React button component based on React Toolbox button. It's important to notice that requiring a module from the exposed root of the package will also import the **SASS** of the component.
Take into account that any required style will be bundled in the final CSS so you probably would want to require components one by one instead of requiring directly from the root index.
## Importing components
First let's take a look on how the components are structured in the project. The [components](https://github.com/react-toolbox/react-toolbox/tree/dev/components) folder contains a folder for each component or set of related components. For example, the `app_bar`:
```
|- /app_bar
|---- AppBar.js
|---- _config.scss
|---- index.js
|---- readme.md
|---- theme.scss
```
There you can see a component definition file, a readme, an index file, a theme stylesheet and a configuration file holding the SASS variables to configure the stylesheet. Depending on whether you want the styles to be directly bundled or not, you can import components in two different ways:
- **Bundled component**: the component requires the corresponding `theme.scss` for you so it will be included in the final bundle. Also, the local classnames will be injected in the component automatically. To import a bundled component you have to require from the `index.js` file. For example: `import {AppBar} from 'react-toolbox/lib/app_bar'`.
- **Raw component**: the component is required alone, without any CSS. In this case you are responsible from providing a theme. To import a raw component you have to require directly from the component definition. For example: `import AppBar from 'react-toolbox/lib/app_bar/AppBar'`.
## Customization
Since you can import raw components and then inject a theme via props or context, you can use whatever you want to provide styles. We give you some SASS stylesheets but you can configure them at import time or even port them to CSS Next or whatever. Furthermore, you can provide extra theming classes that will be mixed in the component so you can even target DOM elements in subcomponents from a parent. Let's see some examples.
### Customization via SASS Loader
Every component in React Toolbox has a `_config.scss` partial and [some parent partials](https://github.com/react-toolbox/react-toolbox/tree/dev/components) defining configuration variables that are used in each `theme.scss`. Since all variables are defined as `!default`, you can prepend variable overrides with a custom `theme.scss` file to each SASS stylesheet required in the project.
If you are importing bundled components, you can use something like [sass-loader](https://github.com/jtangelder/sass-loader) to prepend your custom configuration files to every sass stylesheet by using the `data` option. For example, in your webpack config:
```js
sassLoader: {
data: '@import "' + path.resolve(__dirname, 'theme/_theme.scss') + '";'
}
```
### Customization via Theme Property
Every component in React Toolbox have a **classname API** that can be browsed from the documentation. Also, they accept a `theme` property intended to provide a [CSS Module import object](https://github.com/css-modules/css-modules) that will be used by the component to assign local classnames to its DOM nodes.
React Toolbox uses [react-css-themr](github.com/javivelasco/react-css-themr) to make theming easier. Feel free to take a look to the documentation to learn how you can use themes for the components. For example, imagine you want to create a green success button whose icons are red:
```
// SuccessButton.js
import { Button } from 'react-toolbox/lib/button';
import successTheme from './success-theme.scss';
const SuccessButton = (props) => (
<Button theme={successButtonTheme} {...props} />
);
export default SuccessButton;
```
```
// success-theme.scss
.primary {
background: green;
}
.icon {
color: red
}
```
The given classes will be added to the component and, since they are defined *after* the original CSS they would take priority. Note that you can also boost priority by assigning a `className`. Check more examples at [react-css-themr](www.github.com/javivelasco/react-css-themr) documentation.
### Customization via Theme Context
Alternatively, you can provide CSS Modules object to React Toolbox components using context. This is useful in case you want to create a custom theme without creating wrappers for each raw component. To use this customization you need to install react-css-themr and then use the **theme keys** specified in each component documentation. For example:
```
import React from 'react';
import ReactDOM from 'react-dom';
import { ThemeProvider } from 'react-css-themr';
import Button from 'react-toolbox/lib/button/Button';
import App from './App.js';
const theme = {
RTButton: require('./theme/button-style')
};
const ThemedApp = (children) => (
<ThemeProvider theme={theme}>
<App />
</ThemeProvider>
)
ReactDOM.render(<ThemedApp />, document.getElementById('app'));
```
## Roboto Font and Material Design Icons
@ -41,35 +135,6 @@ React Toolbox assumes that you are importing [Roboto Font](https://www.google.co
In order to import the fonts for you, we'd need to include them in the CSS which is considered a bad practice. If you are not including them in your app, go to the linked sites and follow the instructions.
## Customization
Since React Toolbox styles are written in CSS, it's pretty easy to customize your components. We have several ways:
### Via React Toolbox Loader
Thanks to the power of SASS, all components in React Toolbox are configured from a variables file. The best way to customize your build is to create a custom configuration SASS file overriding configuration variables like colors or sizes.
With [toolbox-loader](https://github.com/react-toolbox/toolbox-loader) you can tell webpack where your configuration file is and it will prepend your config to each SASS build. This will result in your customized CSS for React Toolbox Components. For now you can browse the configuration files and override what you want.
### Via `className` property
Generally each component will have a `className` prop so you can pass the class name you want to keep in the root node of the resulting markup. All markup is styled with the lowest specificity level so you can just nest one level in your CSS and the result will be applied. Consider this example:
```jsx
const CustomButton = () => (
<Button className='customized' label='Custom button' />
);
```
If you browse the resulting markup you will see *data attributes* like `data-react-toolbox="label"` so you can avoid directly styling tag names. You can now write your CSS:
```css
.customized > [data-react-toolbox="label"] {
color: green;
font-weight: bold;
}
```
## TypeScript
A TypeScript definition file `react-toolbox.d.ts` is available. It is referenced in `package.json` and should be picked up by the TypeScript compiler when importing from the npm package.

151
docs/app/components/layout/install/install.md
View File

@ -1,65 +1,130 @@
# Installation, usage and customization
React Toolbox is a set of [React](http://facebook.github.io/react/) components that implement [Google's Material Design specification](https://www.google.com/design/spec/material-design/introduction.html). It's powered by [CSS Modules](https://github.com/css-modules/css-modules) and harmoniously integrates with your [Webpack](http://webpack.github.io/) workflow. You can take a tour through our documentation website and try the components live!
React Toolbox is a set of [React](http://facebook.github.io/react/) components that implement [Google's Material Design specification](https://www.google.com/design/spec/material-design/introduction.html). It's powered by [CSS Modules](https://github.com/css-modules/css-modules) and harmoniously integrates with your [webpack](http://webpack.github.io/) workflow. You can take a tour through our documentation website and try the components live!
## Installation
React Toolbox can be installed as an [npm package](https://www.npmjs.org/package/react-toolbox);
React Toolbox can be installed as an [npm package](https://www.npmjs.org/package/react-toolbox):
```
```bash
npm install --save react-toolbox
```
## Usage
## Prerequisites
Although there are other ways to use React Toolbox, the recommended way is to create a Webpack workflow with [Babel Loader](https://github.com/babel/babel-loader), [CSS Loader](https://github.com/webpack/css-loader) and [SASS Loader](https://github.com/jtangelder/sass-loader). A good starting point is [React Hot Webpack Boilerplate](https://github.com/gaearon/react-hot-boilerplate).
React Toolbox uses [CSS Modules](https://github.com/css-modules/css-modules) and [SASS](http://sass-lang.com/) to provide default stylesheets. If you want to import components bundled with stylesheets, your module bundler should be able to require SASS modules. You can use whatever module bundler you want as long as it can require SASS files from `node_modules`, but we recommend [webpack](). If you are experiencing require errors, make sure your configuration satisfies the requirements.
Once you have the workflow ready, you can just require and use the components:
Of course this is a set of React components so you should be familiar with [React](). If you are willing to customize your components via themes, you may want to take a look to [react-css-themr]() which is used to make styling easier.
```jsx
## Basic usage
The minimal example requires a `Button` bundled with styles:
```
import React from 'react';
import Button from 'react-toolbox/lib/button';
import ReactDOM from 'react-dom';
import { Button } from 'react-toolbox/lib/button';
const CustomButton = () => (
<Button label="Hello world" raised accent />
ReactDOM.render(
<Button label="Hello World!" />,
document.getElementById('app')
);
export default CustomButton;
```
The previous code creates a React button component based on React toolbox button. It's important to notice that requiring a module from the exposed root of the package will import the **SASS** of the component.
Take into account that any required style will be bundled in the final CSS so you probably would want to require components one by one instead of requiring directly from the root index.
## Importing components
First let's take a look on how the components are structured in the project. The [components](https://github.com/react-toolbox/react-toolbox/tree/dev/components) folder contains a folder for each component or set of related components. For example, the `app_bar`:
```
|- /app_bar
|---- AppBar.js
|---- _config.scss
|---- index.js
|---- readme.md
|---- theme.scss
```
There you can see a component definition file, a readme, an index file, a theme stylesheet and a configuration file holding the SASS variables to configure the stylesheet. Depending on whether you want the styles to be directly bundled or not, you can import components in two different ways:
- **Bundled component**: the component requires the corresponding `theme.scss` for you so it will be included in the final bundle. Also, the local classnames will be injected in the component automatically. To import a bundled component you have to require from the `index.js` file. For example: `import {AppBar} from 'react-toolbox/lib/app_bar'`.
- **Raw component**: the component is required alone, without any CSS. In this case you are responsible from providing a theme. To import a raw component you have to require directly from the component definition. For example: `import AppBar from 'react-toolbox/lib/app_bar/AppBar'`.
## Customization
Since you can import raw components and then inject a theme via props or context, you can use whatever you want to provide styles. We give you some SASS stylesheets but you can configure them at import time or even port them to CSS Next or whatever. Furthermore, you can provide extra theming classes that will be mixed in the component so you can even target DOM elements in subcomponents from a parent. Let's see some examples.
### Customization via SASS Loader
Every component in React Toolbox has a `_config.scss` partial and [some parent partials](https://github.com/react-toolbox/react-toolbox/tree/dev/components) defining configuration variables that are used in each `theme.scss`. Since all variables are defined as `!default`, you can prepend variable overrides with a custom `theme.scss` file to each SASS stylesheet required in the project.
If you are importing bundled components, you can use something like [sass-loader](https://github.com/jtangelder/sass-loader) to prepend your custom configuration files to every sass stylesheet by using the `data` option. For example, in your webpack config:
```js
sassLoader: {
data: '@import "' + path.resolve(__dirname, 'theme/_theme.scss') + '";'
}
```
### Customization via Theme Property
Every component in React Toolbox have a **classname API** that can be browsed from the documentation. Also, they accept a `theme` property intended to provide a [CSS Module import object](https://github.com/css-modules/css-modules) that will be used by the component to assign local classnames to its DOM nodes.
React Toolbox uses [react-css-themr](github.com/javivelasco/react-css-themr) to make theming easier. Feel free to take a look to the documentation to learn how you can use themes for the components. For example, imagine you want to create a green success button whose icons are red:
```
// SuccessButton.js
import { Button } from 'react-toolbox/lib/button';
import successTheme from './success-theme.scss';
const SuccessButton = (props) => (
<Button theme={successButtonTheme} {...props} />
);
export default SuccessButton;
```
```
// success-theme.scss
.primary {
background: green;
}
.icon {
color: red
}
```
The given classes will be added to the component and, since they are defined *after* the original CSS they would take priority. Note that you can also boost priority by assigning a `className`. Check more examples at [react-css-themr](www.github.com/javivelasco/react-css-themr) documentation.
### Customization via Theme Context
Alternatively, you can provide CSS Modules object to React Toolbox components using context. This is useful in case you want to create a custom theme without creating wrappers for each raw component. To use this customization you need to install react-css-themr and then use the **theme keys** specified in each component documentation. For example:
```
import React from 'react';
import ReactDOM from 'react-dom';
import { ThemeProvider } from 'react-css-themr';
import Button from 'react-toolbox/lib/button/Button';
import App from './App.js';
const theme = {
RTButton: require('./theme/button-style')
};
const ThemedApp = (children) => (
<ThemeProvider theme={theme}>
<App />
</ThemeProvider>
)
ReactDOM.render(<ThemedApp />, document.getElementById('app'));
```
## Roboto Font and Material Design Icons
React Toolbox assumes that you are importing [Roboto Font](https://www.google.com/fonts/specimen/Roboto) and [Material Design Icons](https://www.google.com/design/icons/).
In order to import the fonts for you, we'd need to include them in the CSS which is considered a bad practice. If you are not including them in your app to the linked sites and follow the instructions.
## Customization
Since React Toolbox styles are written in CSS it's pretty easy to customize your components. We have several ways:
### Via React Toolbox Loader
Thanks to the power of SASS, all components in React Toolbox are configured from a variables file. The best way to customize your build is to create a custom configuration SASS file overriding configuration variables like colors or sizes.
With [toolbox-loader](https://github.com/react-toolbox/toolbox-loader) you can tell webpack where your configuration file is and it will prepend your config to each SASS build. This will result in your customized CSS for React Toolbox Components. For now you can browse the configuration files and override what you want.
### Via `className` property
Generally each component will have a `className` prop so that you can apply a class name to the root node of the resulting markup. All markup is styled with the lowest specificity level so you can just nest one level in your CSS and the result will be applied. Consider this example:
```jsx
const CustomButton = () => (
<Button className='customized' label='Custom button' />
);
```
If you browse the resulting markup you will see *data attributes* like `data-role="label"` which can be used to style components without using tag name selectors. You can now write your CSS:
```css
.customized > [data-react-toolbox="label"] {
color: green;
font-weight: bold;
}
```
In order to import the fonts for you, we'd need to include them in the CSS which is considered a bad practice. If you are not including them in your app, go to the linked sites and follow the instructions.

18
docs/app/index.js
View File

@ -1,21 +1,17 @@
import React from 'react';
import ReactDOM from 'react-dom';
import { ThemeProvider } from 'react-css-themr';
import { Router, Route, useRouterHistory } from 'react-router';
import createHashHistory from 'history/lib/createHashHistory';
import theme from './theme/theme.js';
import Home from './components/layout/home';
import Install from './components/layout/install';
import Main from './components/layout/main';
ReactDOM.render((
<ThemeProvider theme={theme}>
<Router history={useRouterHistory(createHashHistory)({ queryKey: false })}>
<Route path="/" component={Home} />
<Route path="/install" component={Install} />
<Route path="/components" component={Main}>
<Route path=":component" />
</Route>
</Router>
</ThemeProvider>
<Router history={useRouterHistory(createHashHistory)({ queryKey: false })}>
<Route path="/" component={Home} />
<Route path="/install" component={Install} />
<Route path="/components" component={Main}>
<Route path=":component" />
</Route>
</Router>
), document.getElementById('app'));