Skip to content
This repository was archived by the owner on Jun 20, 2022. It is now read-only.

Commit 7ad7b4c

Browse files
gregbergegregberge
committed
feat: various
- Improve documentation - Add gutter support in `Row` - Support "baseRef" and "component" everywhere - Add Typography component BREAKING CHANGE: Remove default variant on buttons BREAKING CHANGE: `controlFocusBoxShadow` is now a mixin
1 parent cc59485 commit 7ad7b4c

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

58 files changed

+2457
-981
lines changed

‎README.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,15 @@ Smooth UI is an open source components library built with [React](https://reactj
2727

2828
It is focused on developer experience and accessibility. With Smooth UI, it is easy to design beautiful websites and applications.
2929

30-
## MIT
30+
## [Docs](https://smooth-ui.smooth-code.com/)
31+
32+
**See the documentation at [styled-components.com/docs](https://smooth-ui.smooth-code.com/)** for more information about using Smooth UI!
33+
34+
## License
35+
36+
Licensed under the MIT License, Copyright © 2018-present Smooth Code.
37+
38+
See [LICENSE](./LICENSE) for more information.
3139

3240
[build-badge]: https://img.shields.io/travis/smooth-code/smooth-ui.svg?style=flat-square
3341
[build]: https://travis-ci.org/smooth-code/smooth-ui

‎docs/ExtendingStyles.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
Using Smooth UI, you have three choices to extend the style of a component.
2+
3+
### Global extend using theme
4+
5+
Smooth UI uses [Styled Components theming feature](https://www.styled-components.com/docs/advanced#theming). It means you can customize it by creating your own theme.
6+
7+
You can find all theme values in [the default theme](https://github.com/smooth-code/smooth-ui/blob/master/src/theme/defaultTheme.js).
8+
9+
An example of custom theme usage:
10+
11+
```jsx static
12+
import React from 'react'
13+
import { render } from 'react-dom'
14+
import { defaultTheme } from 'smooth-ui'
15+
import { ThemeProvider } from 'styled-components'
16+
17+
const theme = {
18+
...defaultTheme,
19+
primary: 'blue',
20+
}
21+
22+
render(
23+
<ThemeProvider theme={theme}>
24+
<Button variant="primary">Blue primary button</Button>
25+
</ThemeProvider>,
26+
document.getElementById('root'),
27+
)
28+
```
29+
30+
### Local extend using `.extend`
31+
32+
Every Smooth UI components expose a method `.extend`. It has the same effect as [the original `.extend` of Styled Components](https://www.styled-components.com/docs/api#extend). You can use it to override any CSS property of the original component. It creates a new component and doesn't affect other components.
33+
34+
An example of a `BorderedButton` extended from a `Button`:
35+
36+
```js
37+
const BorderedButton = Button.extend`
38+
border: 2px solid black;
39+
40+
&:hover {
41+
border-color: blue;
42+
}
43+
`
44+
;<BorderedButton variant="primary">A button with border!</BorderedButton>
45+
```
46+
47+
#### Extend components deeply
48+
49+
Some components are more complex than a `Button`. The `Switch` for an example is a component that includes several elements: a container, a ball... All of these elements have their own classes. To extend it, just use the browser inspector, pick the class and override it 👌.
50+
51+
An example of a custom `Switch` with a black ball 🎱.
52+
53+
```js
54+
const BlackBallSwitch = Switch.extend`
55+
.sui-switch-ball {
56+
background-color: black !important;
57+
}
58+
`
59+
;<BlackBallSwitch />
60+
```
61+
62+
### Local override using `style`
63+
64+
Inline styles are still a good approach for a lot of use-cases. It can be used for very specific changes that don't need media queries or auto-prefixer. All components supports inline style using `style` property.
65+
66+
An example of inline style to change the `padding` of a button.
67+
68+
```js
69+
<Button variant="primary" style={{ padding: 20 }}>
70+
Button with big padding
71+
</Button>
72+
```

src/FormGroup.md renamed to docs/Forms.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
1-
`FormGroup` creates easy form layout.
1+
Smooth UI has no built-in form system.
2+
3+
Smooth UI provides component to simplify the form layouting but it doesn't provide a complete form system. We recommends using [React Final Form](https://github.com/final-form/react-final-form) if you need one.
4+
5+
### Create simple layout using `FormGroup`
6+
7+
Using `FormGroup` component and `control` property on controls like `Input` gives you a clean form layout.
28

39
```js
4-
<div>
510
<FormGroup>
611
<Label htmlFor="form-group-input-name">Name</Label>
712
<Input control id="form-group-input-name" />
@@ -10,15 +15,13 @@
1015
<Label htmlFor="form-group-input-firstname">Firstname</Label>
1116
<Input control id="form-group-input-firstname" />
1217
</FormGroup>
13-
</div>
1418
```
1519

1620
### Validation
1721

18-
You can set validation using `valid` props.
22+
You can set validation using `valid` property and `ControlFeedback`.
1923

2024
```js
21-
<div>
2225
<FormGroup>
2326
<Label htmlFor="form-group-input-valid">Name</Label>
2427
<Input control valid id="form-group-input-valid" />
@@ -29,5 +32,4 @@ You can set validation using `valid` props.
2932
<Input control valid={false} id="form-group-input-invalid" />
3033
<ControlFeedback valid={false}>It is required.</ControlFeedback>
3134
</FormGroup>
32-
</div>
3335
```

‎docs/GettingStarted.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
There is no required setup for Smooth UI, it exposes ready to use components.
2+
3+
This example will display a button on your page.
4+
5+
```js
6+
// import { Button } from 'smooth-ui'
7+
8+
<Button variant="primary">Hello world!</Button>
9+
```

‎docs/Grid.md‎

Lines changed: 177 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,185 @@
1-
## Responsive breakpoints
1+
Smooth UI has a powerful grid system to layout an align content. It's build with [flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Using_CSS_flexible_boxes), mobile first and fully responsive.
22

3-
Using `xs`, `sm`, `md`, `lg` and `xl` you can set size using responsive breakpoints.
3+
```js
4+
<Row>
5+
<Col sm>One</Col>
6+
<Col sm>Two</Col>
7+
<Col sm>Three</Col>
8+
</Row>
9+
```
10+
11+
The above example creates three equal-width columns on small, medium, large, and extra large devices.
12+
13+
### Breakpoints
14+
15+
This table resume all available breakpoints in grid.
16+
17+
<table>
18+
<thead>
19+
<tr>
20+
<th></th>
21+
<th>
22+
Extra small<br>
23+
<small><576px</small>
24+
</th>
25+
<th>
26+
Small<br>
27+
<small>≥576px</small>
28+
</th>
29+
<th>
30+
Medium<br>
31+
<small>≥768px</small>
32+
</th>
33+
<th>
34+
Large<br>
35+
<small>≥992px</small>
36+
</th>
37+
<th>
38+
Extra large<br>
39+
<small>≥1200px</small>
40+
</th>
41+
</tr>
42+
</thead>
43+
<tbody>
44+
<tr>
45+
<th>Max container width</th>
46+
<td>None (auto)</td>
47+
<td>540px</td>
48+
<td>720px</td>
49+
<td>960px</td>
50+
<td>1140px</td>
51+
</tr>
52+
<tr>
53+
<th>Prop</th>
54+
<td><code>xs</code></td>
55+
<td><code>sm</code></td>
56+
<td><code>md</code></td>
57+
<td><code>lg</code></td>
58+
<td><code>xl</code></td>
59+
</tr>
60+
</tbody>
61+
</table>
62+
63+
### Auto-layout columns
64+
65+
#### Equal-width
66+
67+
For example, here are two grid layouts that apply to every device and viewport, from `xs` to `xl`. Add any number of unit-less props for each breakpoint you need and every column will be the same width.
68+
69+
```js
70+
<Row>
71+
<Col>1 of 2</Col>
72+
<Col>2 of 2</Col>
73+
</Row>
74+
<Row>
75+
<Col>1 of 3</Col>
76+
<Col>2 of 3</Col>
77+
<Col>3 of 3</Col>
78+
</Row>
79+
```
80+
81+
#### Setting one column width
82+
83+
Auto-layout for flexbox grid columns also means you can set the width of one column and have the sibling columns automatically resize around it.
84+
85+
```js
86+
<Row>
87+
<Col>1 of 3</Col>
88+
<Col xs={6}>2 of 3 (wider)</Col>
89+
<Col>3 of 3</Col>
90+
</Row>
91+
<Row>
92+
<Col>1 of 3</Col>
93+
<Col xs={5}>2 of 3 (wider)</Col>
94+
<Col>3 of 3</Col>
95+
</Row>
96+
```
97+
98+
### Responsive classes
99+
100+
Smooth UI's grid includes five tiers of predefined classes for building complex responsive layouts. Customize the size of your columns on extra small, small, medium, large, or extra large devices however you see fit.
101+
102+
#### All breakpoints
103+
104+
For grids that are the same from the smallest of devices to the largest, use the props `xs`, `sm`, `md`, `lg` or `xl`. Specify a number value when you need a particularly sized column; otherwise, feel free to put the prop without a value (`true`).
105+
106+
```js
107+
<Row>
108+
<Col>-</Col>
109+
<Col>-</Col>
110+
<Col>-</Col>
111+
<Col>-</Col>
112+
</Row>
113+
<Row>
114+
<Col xs={8}>{`xs={8}`}</Col>
115+
<Col xs={4}>{`xs={4}`}</Col>
116+
</Row>
117+
```
118+
119+
#### Stacked to horizontal
120+
121+
Using a single set of `sm` props, you can create a basic grid system that starts out stacked before becoming horizontal with at the small breakpoint (`sm`).
122+
123+
```js
124+
<Row>
125+
<Col sm={8}>{`sm={8}`}</Col>
126+
<Col sm={4}>{`sm={4}`}</Col>
127+
</Row>
128+
<Row>
129+
<Col sm>sm</Col>
130+
<Col sm>sm</Col>
131+
<Col sm>sm</Col>
132+
</Row>
133+
```
134+
135+
#### Mix and match
136+
137+
Don’t want your columns to simply stack in some grid tiers? Use a combination of different props for each tier as needed. See the example below for a better idea of how it all works.
138+
139+
**Stack the columns on mobile by making one full-width and the other half-width**
140+
141+
```js
142+
<Row>
143+
<Col xs={12} md={8}>{`xs={12} md={8}`}</Col>
144+
<Col xs={6} md={4}>{`xs={6} md={4}`}</Col>
145+
</Row>
146+
```
147+
148+
**Columns start at 50% wide on mobile and bump up to 33.3% wide on desktop**
4149

5150
```js
6151
<Row>
7-
<Col xs style={{ border: '1px solid black' }}>
8-
1
152+
<Col xs={6} md={4}>
153+
{`xs={6} md={4}`}
9154
</Col>
10-
<Col xs style={{ border: '1px solid black' }}>
11-
2
155+
<Col xs={6} md={4}>
156+
{`xs={6} md={4}`}
12157
</Col>
158+
<Col xs={6} md={4}>
159+
{`xs={6} md={4}`}
160+
</Col>
161+
</Row>
162+
```
163+
164+
**Columns are always 50% wide, on mobile and desktop**
165+
166+
```js
167+
<Row>
168+
<Col xs={6}>{`xs={6}`}</Col>
169+
<Col xs={6}>{`xs={6}`}</Col>
170+
</Row>
171+
```
172+
173+
### Custom gutter
174+
175+
It is possible to specify custom padding (left and right) using `gutter` props on `Row`.
176+
177+
```js
178+
<Row gutter={5}>
179+
<React.Fragment>
180+
<Col>{`5px gutter`}</Col>
181+
<Col>{`5px gutter`}</Col>
182+
<Col>{`5px gutter`}</Col>
183+
</React.Fragment>
13184
</Row>
14185
```

‎docs/Installation.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Install Smooth UI from npm:
2+
3+
```bash static
4+
npm install --save smooth-ui styled-components
5+
```

‎docs/Introduction.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
11
Smooth UI is an open source components library built with [React](https://reactjs.org/) and [Styled Components](https://www.styled-components.com).
22

33
It is focused on developer experience and accessibility. With Smooth UI, it is easy to design beautiful websites and applications.
4-
5-
It is currently in development and a lot of breaking changes could happen. Be careful before using it.

‎docs/UseAnotherComponent.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
Sometimes you may want to use a component but the resulting HTML tag is not the good one. Or you want to use a `Button` with another component like [the `Link` from React Router](https://reacttraining.com/react-router/web/api/Link).
2+
3+
You can do it using two approaches.
4+
5+
### Static approach using `.withComponent`
6+
7+
Styled Components has a magic method called [`.withComponent`](https://www.styled-components.com/docs/api#withcomponent), it gives you the opportunity to keep style and swap the component. All Smooth UI components exposes the same method, this way you can easily create a new component from another without losing the style.
8+
9+
An example of `Button` that will use `a` instead of `button`.
10+
11+
```js
12+
const LinkButton = Button.withComponent('a')
13+
;<LinkButton variant="primary" href="#">
14+
A button as a link
15+
</LinkButton>
16+
```
17+
18+
#### Dynamic approach using `component` property
19+
20+
Every components accept a `component` property, it defines the base component used in each component.
21+
22+
An example of an `Alert` that uses `span` as a component.
23+
24+
```js
25+
<Alert component="span" variant="primary">
26+
A span alert
27+
</Alert>
28+
```

0 commit comments

Comments
 (0)