2017-02-01 14:13:56 +00:00
|
|
|
# Dialog
|
|
|
|
|
2017-02-06 14:12:10 +00:00
|
|
|
Dialogs are the high-level component used to render popups such as Preferences,
|
|
|
|
and repository setting as well as error messages. They're built upon the new
|
|
|
|
`dialog` html element and are shown as modals which means that tab navigation
|
|
|
|
are constrained to within the dialog itself.
|
|
|
|
|
2017-02-01 14:13:56 +00:00
|
|
|
## General structure
|
|
|
|
|
2018-01-05 18:50:50 +00:00
|
|
|
```jsx
|
2018-02-01 23:08:53 +00:00
|
|
|
<Dialog title='Title'>
|
2017-02-01 14:13:56 +00:00
|
|
|
<TabBar>...</TabBar>
|
2018-02-01 23:08:53 +00:00
|
|
|
<DialogContent>
|
|
|
|
...
|
|
|
|
</DialogContent>
|
2017-02-01 15:28:46 +00:00
|
|
|
<DialogFooter>
|
|
|
|
<ButtonGroup>
|
2018-02-01 23:08:53 +00:00
|
|
|
<Button type='submit'>Ok</Button>
|
2017-02-01 15:28:46 +00:00
|
|
|
<Button>Cancel</Button>
|
|
|
|
</ButtonGroup>
|
|
|
|
</DialogFooter>
|
2017-02-01 14:13:56 +00:00
|
|
|
</Dialog>
|
|
|
|
```
|
|
|
|
|
2017-02-06 14:10:26 +00:00
|
|
|
## Errors
|
|
|
|
|
|
|
|
Dialogs should, when practical, render errors caused by its actions inline as
|
2018-02-01 23:08:53 +00:00
|
|
|
opposed to opening an error dialog. An example of this is the Preferences dialog.
|
|
|
|
If the dialog fails to write to the `.gitignore` or git config files as part of
|
|
|
|
persisting changes it renders a short error message inline in the dialog using
|
|
|
|
the `DialogError` component.
|
2017-02-06 14:10:26 +00:00
|
|
|
|
|
|
|
The `DialogError` component, if used, must be the first child element of the
|
|
|
|
Dialog itself.
|
|
|
|
|
2018-01-05 18:50:50 +00:00
|
|
|
```jsx
|
2018-02-01 23:08:53 +00:00
|
|
|
<Dialog title='Preferences'>
|
|
|
|
<DialogError>Could not save ignore file. EPERM Something something</DialogError>
|
2017-02-06 14:10:26 +00:00
|
|
|
<TabBar>...</TabBar>
|
2018-02-01 23:08:53 +00:00
|
|
|
<DialogContent>
|
|
|
|
...
|
|
|
|
</DialogContent>
|
2017-02-06 14:10:26 +00:00
|
|
|
<DialogFooter>
|
|
|
|
<ButtonGroup>
|
2018-02-01 23:08:53 +00:00
|
|
|
<Button type='submit'>Ok</Button>
|
2017-02-06 14:10:26 +00:00
|
|
|
<Button>Cancel</Button>
|
|
|
|
</ButtonGroup>
|
|
|
|
</DialogFooter>
|
|
|
|
</Dialog>
|
|
|
|
```
|
|
|
|
|
2018-02-01 23:08:53 +00:00
|
|
|
The content inside of the `DialogError` should be primarily text based. Avoid using
|
|
|
|
the term 'Error' inside the text as that should be evident already based on the
|
|
|
|
styling of the `DialogError` component.
|
2017-02-01 14:13:56 +00:00
|
|
|
|
|
|
|
## Best practices
|
|
|
|
|
2018-01-05 18:50:50 +00:00
|
|
|
### DO: Let children render the `DialogContent` component
|
2017-02-01 14:13:56 +00:00
|
|
|
|
2018-02-01 23:08:53 +00:00
|
|
|
If you're using a one-child-per-tab approach you should render the `DialogContent`
|
|
|
|
as the top-level element in those children instead of wrapping children inside the
|
|
|
|
`DialogContent` element. This avoid needless nesting and lets us leverage generic
|
|
|
|
dialog/form/row styles in a more straightforward way.
|
2017-02-01 14:13:56 +00:00
|
|
|
|
|
|
|
#### Example (good)
|
|
|
|
|
2018-02-01 23:08:53 +00:00
|
|
|
|
2018-01-05 18:50:50 +00:00
|
|
|
```jsx
|
|
|
|
// SomeComponent.tsx
|
2018-02-01 23:08:53 +00:00
|
|
|
<Dialog title='Title'>
|
2017-02-01 14:13:56 +00:00
|
|
|
<TabBar>...</TabBar>
|
2017-02-01 15:28:46 +00:00
|
|
|
{this.renderActiveTab()}
|
|
|
|
<DialogFooter>
|
|
|
|
<ButtonGroup>
|
2018-02-01 23:08:53 +00:00
|
|
|
<Button type='submit'>Ok</Button>
|
2017-02-01 15:28:46 +00:00
|
|
|
<Button>Cancel</Button>
|
|
|
|
</ButtonGroup>
|
|
|
|
</DialogFooter>
|
2017-02-01 14:13:56 +00:00
|
|
|
</Dialog>
|
2018-01-05 18:50:50 +00:00
|
|
|
|
|
|
|
// ChildComponent.tsx
|
2018-02-01 23:08:53 +00:00
|
|
|
<DialogContent>
|
|
|
|
my fancy content
|
|
|
|
</DialogContent>
|
2017-02-01 14:13:56 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
#### Example (bad)
|
|
|
|
|
2018-02-01 23:08:53 +00:00
|
|
|
|
2018-01-05 18:50:50 +00:00
|
|
|
```jsx
|
|
|
|
// SomeComponent.tsx
|
2018-02-01 23:08:53 +00:00
|
|
|
<Dialog title='Title'>
|
2017-02-01 14:13:56 +00:00
|
|
|
<TabBar>...</TabBar>
|
2018-02-01 23:08:53 +00:00
|
|
|
<DialogContent>
|
|
|
|
{this.renderActiveTab()}
|
|
|
|
</DialogContent>
|
2017-02-01 15:28:46 +00:00
|
|
|
<DialogFooter>
|
|
|
|
<ButtonGroup>
|
2018-02-01 23:08:53 +00:00
|
|
|
<Button type='submit'>Ok</Button>
|
2017-02-01 15:28:46 +00:00
|
|
|
<Button>Cancel</Button>
|
|
|
|
</ButtonGroup>
|
|
|
|
</DialogFooter>
|
2017-02-01 14:13:56 +00:00
|
|
|
</Dialog>
|
2018-01-05 18:50:50 +00:00
|
|
|
|
|
|
|
// ChildComponent.tsx
|
2018-02-01 23:08:53 +00:00
|
|
|
<div>
|
|
|
|
my fancy content
|
|
|
|
</div>
|
2017-02-01 14:13:56 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### DO: Use Row components to lay out content
|
|
|
|
|
2018-02-01 23:08:53 +00:00
|
|
|
The `Row` component receives a bottom margin, when used as an immediate
|
|
|
|
child of `DialogContent`, making it an excellent tool for structuring content.
|
2017-02-06 14:10:26 +00:00
|
|
|
|
|
|
|
If the content is primary text, as opposed to form component the `<p>` element
|
|
|
|
should be used instead of the `Row` component.
|