Skip to content

Commit 56fd2be

Browse files
camertroncamertron
committed
Port over draft components
1 parent 61c0d81 commit 56fd2be

File tree

18 files changed

+1416
-283
lines changed

18 files changed

+1416
-283
lines changed

‎content/components/dialog/react/draft.mdx

+190
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
title: Dialog
3+
description:
4+
Dialog is a floating surface used to display transient content such as confirmation actions, selection options, and
5+
more.
6+
reactId: dialog
7+
reactStatus: draft
8+
---
9+
10+
import ReactComponentPage from '~/src/components/react-component-page'
11+
import { graphql } from "gatsby"
12+
13+
export const query = graphql`
14+
query DialogDraftQuery($componentId: String! = "dialog", $parentPath: String! = "/components/dialog", $status: String! = "draft") {
15+
...ReactComponentInfo
16+
}
17+
`
18+
19+
export default function Layout({data, children}) {
20+
return <ReactComponentPage data={data} showExamples={false} showProps={false} showImport={false} tocItems={[{url: "#import", title: "Import"}, {url: "#props", title: "Props"}, {url: "#confirmationdialog", title: "ConfirmationDialog"}]}>
21+
{children}
22+
</ReactComponentPage>
23+
}
24+
25+
The dialog component is the Primer implementation of the ARIA design pattern [Dialog](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal). A dialog is a type of overlay that can be used for confirming actions, asking for disambiguation, and presenting small forms. They generally allow the user to focus on a quick task without having to navigate to a different page.
26+
27+
**Dialogs appear in the page after a direct user interaction**. Don't show dialogs on page load or as system alerts.
28+
29+
**Dialogs appear centered in the page**, with a visible backdrop that dims the rest of the window for focus.
30+
31+
**All dialogs should have a title and a close button**. Use the `title` prop to set the title. The close button is created automatically, but must be handled with an `onClose` prop.
32+
33+
**Dialogs are modal**. Dialogs can be dismissed by clicking on the close button, by interacting with another button in the overlay, or by clicking outside of the overlay.
34+
35+
Dialogs should not be dismissed by clicking outside the dialog's content area if used to add, update, or remove information. This would be the equivalent of a cancel action and may cause accidental data loss.
36+
37+
**(Coming soon) Make sure larger dialogs remain mobile-friendly**. Even large dialogs need to be responsive. A dialog's width and height will be readjusted depending on the screen size and should never exceed the available space. Use responsive solutions to adjust the UI so they behave well on smaller screens.
38+
39+
**(Coming soon) Simple and small dialogs can remain as-is on mobile**. As more elements are added to it, mobile-specific style variations such as **Bottom sheet** and **Full-screen** should be considered.
40+
41+
## Import
42+
43+
```javascript
44+
import {Dialog} from '@primer/react/drafts'
45+
```
46+
47+
### State
48+
49+
The dialog component is completely stateless. The parent component must conditionally render a dialog based on the necessary criteria. The parent component can be notified by a gesture to close the dialog (e.g. by clicking the "X" button or by pressing the Escape key) by passing in the `onClose` prop.
50+
51+
### Accessibility
52+
53+
The dialog component is fully accessible out-of-the-box. The dialog's title is used for `aria-labelledby`, and the dialog's description is used for `aria-describedby`. The `aria-modal="true"` attribute is used to inform screen readers that the rest of the content on the page is inert.
54+
55+
#### Keyboard
56+
57+
The default keyboard API for a dialog employs three mechanisms:
58+
59+
1. The Escape key can be pressed to close the dialog.
60+
2. Focus is trapped within the top-most dialog. When a dialog is opened, the close button receives initial focus by default, or on a button defined with `autoFocus: true`.
61+
3. If there are buttons in the dialog footer, focus can be moved between them with left and right arrow keys or tab/shift+tab.
62+
4. When a dialog is closed, it can optionally handle returning focus to the element that was focused immediately before the dialog was opened. Otherwise, it is the consumer's responsibility to move focus to a suitable element.
63+
64+
### Custom rendering
65+
66+
**Note: using custom rendering allows breaking out of the defined design, UX, and accessibility patterns of the dialog. Use only as a last resort.**
67+
68+
By default, the Dialog component implements the design and interactions defined by the Primer design system. If necessary, you can provide custom renderers for the header, body, or footer using the `renderHeader`, `renderBody`, and `renderFooter` props, respectively. The JSX produced by these render props will render full-bleed into their respective areas of the dialog. If you are using the custom renderers, you should use the provided sub-components `Dialog.Header`, `Dialog.Title`, `Dialog.Subtitle`, `Dialog.CloseButton`, `Dialog.Body`, `Dialog.Footer`, and `Dialog.Buttons` to the extent possible.
69+
70+
### Example
71+
72+
```jsx live drafts
73+
<State default={false}>
74+
{([isOpen, setIsOpen]) => {
75+
const openDialog = React.useCallback(() => setIsOpen(true), [setIsOpen])
76+
const closeDialog = React.useCallback(() => setIsOpen(false), [setIsOpen])
77+
return (
78+
<>
79+
<Button onClick={openDialog}>Open</Button>
80+
{isOpen && (
81+
<Dialog
82+
title="Dialog example"
83+
subtitle={
84+
<>
85+
This is a <b>description</b> of the dialog.
86+
</>
87+
}
88+
footerButtons={[{content: 'Ok', onClick: closeDialog}]}
89+
onClose={closeDialog}
90+
>
91+
<Text fontFamily="sans-serif">Some content</Text>
92+
</Dialog>
93+
)}
94+
</>
95+
)
96+
}}
97+
</State>
98+
```
99+
100+
## Props
101+
102+
### DialogHeaderProps
103+
104+
The `DialogHeaderProps` interface extends `DialogProps` and adds these additional properties:
105+
106+
| Prop name | Type | Description |
107+
| :------------------ | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
108+
| dialogLabelId | `string` | ID of the element that will be used as the `aria-labelledby` attribute on the dialog. This ID should be set to the element that renders the dialog's title. |
109+
| dialogDescriptionId | `string` | ID of the element that will be used as the `aria-describedby` attribute on the dialog. This ID should be set to the element that renders the dialog's subtitle. |
110+
111+
### DialogButtonProps
112+
113+
The `DialogButtonProps` interface extends `ButtonProps` (see Button) and adds these additional properties:
114+
115+
| Prop name | Type | Default | Description |
116+
| :--------- | :-------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
117+
| buttonType | `"normal" │ "primary" │ "danger"` | `Button` | The type of button to render |
118+
| content | `React.ReactNode` | | Required. The button's inner content. |
119+
| autoFocus | `boolean` | false | If true, this button will be automatically focused when the dialog is first rendered. If `autoFocus` is true on subsequent button definitions, it will be ignored. |
120+
121+
## ConfirmationDialog
122+
123+
A `ConfirmationDialog` is a special kind of dialog with more rigid behavior. It is used to confirm a user action. `ConfirmationDialog`s always have exactly two buttons: one to cancel the action and one to confirm it. No custom rendering capabilities are provided for ConfirmationDialog.
124+
125+
### useConfirm hook
126+
127+
An alternate way to use `ConfirmationDialog` is with the `useConfirm()` hook. It takes no parameters and returns an `async` function, `confirm`. When `confirm` is called (see ConfirmOptions below for its argument), it shows the confirmation dialog. When the dialog is dismissed, a promise is resolved with `true` or `false` depending on whether or not the confirm button was used.
128+
129+
### Example (with `useConfirm` hook)
130+
131+
```javascript live noinline
132+
function ShorthandExample2() {
133+
const confirm = useConfirm()
134+
const buttonClick = React.useCallback(
135+
async function (e) {
136+
if (await confirm({title: 'Are you sure?', content: 'You must confirm this action to continue.'})) {
137+
e.target.textContent = 'Confirmed!'
138+
}
139+
},
140+
[confirm],
141+
)
142+
return (
143+
<>
144+
<Button onClick={buttonClick}>Confirmable action</Button>
145+
</>
146+
)
147+
}
148+
render(<ShorthandExample2 />)
149+
```
150+
151+
### Example (using the full `ConfirmationDialog` component)
152+
153+
```jsx live
154+
<State default={false}>
155+
{([isOpen, setIsOpen]) => {
156+
const openDialog = React.useCallback(() => setIsOpen(true), [setIsOpen])
157+
const closeDialog = React.useCallback(() => setIsOpen(false), [setIsOpen])
158+
return (
159+
<>
160+
<Button onClick={openDialog}>Open</Button>
161+
{isOpen && (
162+
<ConfirmationDialog title="Confirm action?" onClose={closeDialog}>
163+
Are you sure you want to confirm this action?
164+
</ConfirmationDialog>
165+
)}
166+
</>
167+
)
168+
}}
169+
</State>
170+
```
171+
172+
### ConfirmationDialogProps
173+
174+
| Prop name | Type | Default | Description |
175+
| :------------------- | :-------------------------------------------------------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------- |
176+
| title | `React.ReactNode` | | Required. Sets the title of the dialog, which by default is also used as the `aria-labelledby` attribute. |
177+
| onClose | `(gesture: 'confirm' │ 'cancel' │ 'close-button' │ 'escape') => void` | | Required. This callback is invoked when a gesture to close the dialog is performed. The first argument indicates the gesture. |
178+
| cancelButtonContent | `React.ReactNode` | `"Cancel"` | The content to use for the cancel button. |
179+
| confirmButtonContent | `React.ReactNode` | `"OK"` | The content to use for the confirm button. |
180+
| confirmButtonType | `"normal" │ "primary" │ "danger"` | `Button` | The type of button to use for the confirm button. |
181+
182+
### ConfirmOptions
183+
184+
| Prop name | Type | Default | Description |
185+
| :------------------- | :-------------------------------- | :--------- | :-------------------------------------------------------------------------------------------------------- |
186+
| title | `React.ReactNode` | | Required. Sets the title of the dialog, which by default is also used as the `aria-labelledby` attribute. |
187+
| content | `React.ReactNode` | | Required. Used as the body of the ConfirmationDialog that is displayed. |
188+
| cancelButtonContent | `React.ReactNode` | `"Cancel"` | The content to use for the cancel button. |
189+
| confirmButtonContent | `React.ReactNode` | `"OK"` | The content to use for the confirm button. |
190+
| confirmButtonType | `"normal" │ "primary" │ "danger"` | `Button` | The type of button to use for the confirm button. |

‎content/components/hidden.mdx

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: Hidden
3+
description: Use Hidden to responsively hide or show content in narrow, regular and wide viewports.
4+
reactId: hidden
5+
---
6+
7+
import ComponentLayout from '~/src/layouts/component-layout'
8+
import {Link, Text} from '@primer/react'
9+
import {Link as GatsbyLink} from 'gatsby'
10+
export default ComponentLayout
11+
import {AccessibilityLink} from '~/src/components/accessibility-link'
12+
13+
<Note variant="warning">
14+
<Text sx={{display: 'block', fontWeight: 'bold', mb: 2}}>Guidelines for this component are in progress</Text>
15+
<Text>Interested in contributing? Review the guidelines for <Link as={GatsbyLink} to="/guides/contribute/documentation#documenting-components">writing component documentation</Link> and open a pull request in our <Link as={GatsbyLink} to="https://github.com/primer/design">documentation repository.</Link></Text>
16+
</Note>
17+
18+
## Accessibility
19+
20+
### Known accessibility issues (GitHub staff only)
21+
22+
<AccessibilityLink label="Hidden"/>

‎content/components/hidden/react/draft.mdx

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Hidden
3+
description: Use Hidden to responsively hide or show content in narrow, regular and wide viewports.
4+
reactId: hidden
5+
reactStatus: draft
6+
---
7+
8+
import ReactComponentPage from '~/src/components/react-component-page'
9+
import { graphql } from "gatsby"
10+
11+
export const query = graphql`
12+
query HiddenDraftQuery($componentId: String! = "hidden", $parentPath: String! = "/components/hidden", $status: String! = "draft") {
13+
...ReactComponentInfo
14+
}
15+
`
16+
17+
export default function Layout({data, children}) {
18+
return <ReactComponentPage data={data}>{children}</ReactComponentPage>
19+
}
20+
21+
The `Hidden` component is a utility component that helps hide or show content/components in different viewports.
22+
23+
<Note>Use Hidden only to control behaviour in a responsive manner. It does not take any `sx` props.</Note>
24+
25+
## Examples
26+
27+
### Single viewport value provided
28+
29+
```jsx drafts
30+
<Hidden when="narrow">
31+
<Placeholder height="80px" label="This is not visible in narrow viewport" />
32+
</Hidden>
33+
```
34+
35+
### Multiple viewport values provided
36+
37+
```jsx drafts
38+
<Hidden when={['narrow', 'wide']}>
39+
<Placeholder height="80px" label="This is not visible in narrow and wide viewport" />
40+
</Hidden>
41+
```

0 commit comments

Comments
 (0)