Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Provide a detailed summary of your PR. Explain how you arrived at your solution.
- [ ] Check against **all themes** for compatibility in both light and dark modes
- [ ] Checked in **mobile**
- [ ] Checked in **Chrome**, **Safari**, **Edge**, and **Firefox**
- [ ] Props have proper **autodocs**
- [ ] Props have proper **autodocs** and **playground** toggles
Comment thread
cchaos marked this conversation as resolved.
Outdated
- [ ] Added **[documentation](https://github.com/elastic/eui/blob/master/wiki/documentation-guidelines.md)**
- [ ] Checked **[Code Sandbox](https://codesandbox.io/)** works for the any docs examples
- [ ] Added or updated **[jest tests](https://github.com/elastic/eui/blob/master/wiki/testing.md)**
Expand Down
40 changes: 40 additions & 0 deletions wiki/documentation-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,46 @@ There are a couple themes to keep in mind when adding snippets:
/>
```

## Adding playground toggles

Most documentation pages include a [playground section](https://elastic.github.io/eui/#/layout/accordion/playground) where consumers can interact with the component's props to see in real time how different configurations affect visual and functional output. Generally, the playground system will automatically generate the correct toggle type; for instance, a text input for props that accept string values, and a switch input for props that accept boolean values.

### Toggles for required props

Props marked required for a component typically do not have default values and therefore need to be set for the playground to work well. For example, the `children` prop, which can be set in the component's [`playground.js` file](https://github.com/elastic/eui/blob/master/src-docs/src/views/accordion/playground.js):

```js
propsToUse.children = {
value: `<EuiText>
<p>
Any content inside of <strong>EuiAccordion</strong> will appear here.
</p>
</EuiText>`,
type: PropTypes.ReactNode,
hidden: false,
};
```
### Custom or altered toggles

Some props accept values that are difficult to parse or require knowledge about how the prop should be used to determine the type of toggle to use. For example, callback function props such as `onToggle`. For cases like this we may provide utility functions to help:

```js
propsToUse.onToggle = simulateFunction(propsToUse.onToggle);
```

Or perhaps the prop accepts a wide range of values and the best user experience would be to limit the value to a simpler input:

```js
propsToUse.valueAppend = {
...propsToUse.valueAppend,
type: PropTypes.String,
};
```

### Toggles for complex or markup-heavy props

Not all props lend themselves to becoming helpful playground toggles. For instance, optional "action" props that require the consumer to provide a fully configured button or link element. In cases such as this, it is acceptable to omit the toggle and rely on prop table documentation to convey how the prop is best used.

## Changelog

Any updates to the `src/` folder require an entry in the [CHANGELOG.md](../CHANGELOG.md) file. Documentation-only changes do not. Here are our guidelines for updating the file:
Expand Down