Skip to content

Commit

Permalink
Improve documentation (#1)
Browse files Browse the repository at this point in the history 
* Update README.md

* Improve documentation

* Update README.md
  • Loading branch information
@cheton
cheton authored Mar 28, 2019
1 parent eea9aba commit 911060d
Show file tree
Hide file tree
Showing 8 changed files with 97 additions and 105 deletions.
22 changes: 19 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,11 @@ Demo: https://trendmicro-frontend.github.io/react-form-control
import '@trendmicro/react-form-control/dist/react-form-control.css';
```

## Usage
## Overview

### Form controls

The `<FormControl>` component renders a form control with block-level styling (`display: block` and `width: 100%`). Supported textual form controls includes `<Input>`, `<Select>`, and `<Textarea>`.

```jsx
<FormGroup>
Expand All @@ -32,7 +36,7 @@ Demo: https://trendmicro-frontend.github.io/react-form-control
</FormGroup>
<FormGroup>
<label>Example select</label>
<Select>
<Select defaultValue="1">
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
Expand All @@ -42,7 +46,7 @@ Demo: https://trendmicro-frontend.github.io/react-form-control
</FormGroup>
<FormGroup>
<label>Example multiple select</label>
<Select multiple>
<Select multiple defaultValue="1">
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
Expand All @@ -56,6 +60,18 @@ Demo: https://trendmicro-frontend.github.io/react-form-control
</FormGroup>
```

### Form groups

Using the `<FormGroup>` component is the easiest way to add some structure to forms, it provides a flexible way that encourages proper grouping of labels, controls, and form validation messaging.

The `<FormGroup>` component is not provided here, but you can use [styled-components](https://github.com/styled-components/styled-components) to style with plain CSS styles. By default, it only applies `margin-bottom` as below:

```jsx
const FormGroup = styled.div`
margin-bottom: 12px;
`;
```

## API

### Properties
Expand Down
10 changes: 5 additions & 5 deletions docs/build/bundle.bef7c920.js → docs/build/bundle.26055c75.js
View file

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/index.html
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
<!DOCTYPE html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta http-equiv="X-UA-Compatible" content="ie=edge"><title>React Form Control v0.1.0</title><link href="main.css" rel="stylesheet"></head><body><div id="rsg-root"></div><script src="build/bundle.bef7c920.js"></script></body></html>
<!DOCTYPE html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta http-equiv="X-UA-Compatible" content="ie=edge"><title>React Form Control v0.1.0</title><link href="main.css" rel="stylesheet"></head><body><div id="rsg-root"></div><script src="build/bundle.26055c75.js"></script></body></html>
50 changes: 20 additions & 30 deletions styleguide/examples/FormControl.md
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,34 @@
### Sizing

```jsx
<FormGroup>
<FormControl fcSize="lg">
Large
</FormControl>
</FormGroup>
<FormGroup>
<FormControl fcSize="md">
Medium
</FormControl>
</FormGroup>
<FormGroup>
<FormControl fcSize="sm">
Small
</FormControl>
</FormGroup>
<FormGroup>
<FormControl fcSize="xs">
Extra small
</FormControl>
</FormGroup>
<FormControl fcSize="lg">
Large
</FormControl>
<FormControl fcSize="md">
Medium
</FormControl>
<FormControl fcSize="sm">
Small
</FormControl>
<FormControl fcSize="xs">
Extra small
</FormControl>
```

### Plain text

If you want to have form controls styled as plain text, use inline style to override the default form control styling and preserve the correct margin and padding.

```jsx
<FormGroup>
<FormControl style={{ borderColor: 'transparent', height: 'auto' }}>
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
</FormControl>
</FormGroup>
<FormControl style={{ borderColor: 'transparent', height: 'auto' }}>
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
</FormControl>
```
### Text Overflow
```jsx
<FormGroup>
<FormControl style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
</FormControl>
</FormGroup>
<FormControl style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
</FormControl>
```
32 changes: 8 additions & 24 deletions styleguide/examples/Input.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,10 @@
### Sizing

```jsx
<FormGroup>
<Input type="text" fcSize="lg" placeholder="Large input" />
</FormGroup>
<FormGroup>
<Input type="text" fcSize="md" placeholder="Medium input" />
</FormGroup>
<FormGroup>
<Input type="text" fcSize="sm" placeholder="Small input" />
</FormGroup>
<FormGroup>
<Input type="text" fcSize="xs" placeholder="Extra small input" />
</FormGroup>
<Input type="text" fcSize="lg" placeholder="Large input" />
<Input type="text" fcSize="md" placeholder="Medium input" />
<Input type="text" fcSize="sm" placeholder="Small input" />
<Input type="text" fcSize="xs" placeholder="Extra small input" />
```

### Attributes
Expand All @@ -26,12 +18,8 @@ The `disabled` attribute specifies whether the control is disabled for user inpu
* Disabled controls are skipped in tabbing navigation.

```jsx
<FormGroup>
<Input type="text" placeholder="[placeholder] Disabled input" disabled />
</FormGroup>
<FormGroup>
<Input type="text" value="[value] Disabled input" disabled />
</FormGroup>
<Input type="text" placeholder="[placeholder] Disabled input" disabled />
<Input type="text" value="[value] Disabled input" disabled />
```

#### Read-only
Expand All @@ -43,10 +31,6 @@ The `readOnly` attribute specifies whether the control may be modified by the us
* Read-only controls are included in tabbing navigation.

```jsx
<FormGroup>
<Input type="text" placeholder="[placeholder] Read-only input" readOnly />
</FormGroup>
<FormGroup>
<Input type="text" value="[value] Read-only input" readOnly />
</FormGroup>
<Input type="text" placeholder="[placeholder] Read-only input" readOnly />
<Input type="text" value="[value] Read-only input" readOnly />
```
50 changes: 23 additions & 27 deletions styleguide/examples/Select.md
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,34 @@
### Sizing

```jsx
<FormGroup>
<Select fcSize="lg">
<option>Large select</option>
</Select>
</FormGroup>
<FormGroup>
<Select fcSize="md">
<option>Medium select</option>
</Select>
</FormGroup>
<FormGroup>
<Select fcSize="sm">
<option>Small select</option>
</Select>
</FormGroup>
<FormGroup>
<Select fcSize="xs">
<option>Extra small select</option>
</Select>
</FormGroup>
<Select fcSize="lg">
<option>Large select</option>
</Select>
<Select fcSize="md">
<option>Medium select</option>
</Select>
<Select fcSize="sm">
<option>Small select</option>
</Select>
<Select fcSize="xs">
<option>Extra small select</option>
</Select>
```

### Attributes

#### Disabled

The `disabled` attribute specifies whether the control is disabled for user input.

* Disabled controls will not get passed to the form processor.
* Disabled controls do not receive focus.
* Disabled controls are skipped in tabbing navigation.

```jsx
<FormGroup>
<Select disabled>
<option>Disabled select</option>
</Select>
</FormGroup>
<Select disabled>
<option>Disabled select</option>
</Select>
```

#### Read-only
Expand All @@ -45,7 +41,7 @@ The `multiple` attribute specifies that multiple options can be selected at once

```jsx
<Select multiple>
<option selected>Open this select menu</option>
<option>Open this select menu</option>
<option value="1">One</option>
<option value="2">Two</option>
<option value="3">Three</option>
Expand All @@ -58,7 +54,7 @@ The `size` attribute specifies the number of visible options in the list.

```jsx
<Select size="3">
<option selected>Open this select menu</option>
<option>Open this select menu</option>
<option value="1">One</option>
<option value="2">Two</option>
<option value="3">Three</option>
Expand Down
32 changes: 17 additions & 15 deletions styleguide/examples/Textarea.md
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,31 @@
```jsx
<FormGroup>
<Textarea placeholder="Enter a message in the textarea" rows={3} />
</FormGroup>
<Textarea placeholder="Enter a message in the textarea" rows={3} />
```

### Attributes

### Disabled

The `disabled` attribute specifies whether the control is disabled for user input.

* Disabled controls will not get passed to the form processor.
* Disabled controls do not receive focus.
* Disabled controls are skipped in tabbing navigation.

```jsx
<FormGroup>
<Textarea placeholder="[placeholder] Disabled textarea" disabled />
</FormGroup>
<FormGroup>
<Textarea value="[value] Disabled textarea" disabled />
</FormGroup>
<Textarea placeholder="[placeholder] Disabled textarea" disabled />
<Textarea value="[value] Disabled textarea" disabled />
```

### Read-only

The `readOnly` attribute specifies whether the control may be modified by the user.

* Read-only controls will get passed to the form processor.
* Read-only controls receive the focus but cannot be modified by the user.
* Read-only controls are included in tabbing navigation.

```jsx
<FormGroup>
<Textarea placeholder="[placeholder] Read-only textarea" readOnly />
</FormGroup>
<FormGroup>
<Textarea value="[value] Read-only textarea" readOnly />
</FormGroup>
<Textarea placeholder="[placeholder] Read-only textarea" readOnly />
<Textarea value="[value] Read-only textarea" readOnly />
```
4 changes: 4 additions & 0 deletions styleguide/styles.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,7 @@ html {
font-family: Arial, "Helvetica Neue", Helvetica, sans-serif;
font-size: 13px;
}

#example [class^="form-control---"] + [class^="form-control---"] {
margin-top: 12px;
}

0 comments on commit 911060d

Please sign in to comment.