From 770ddfbf0090a57bfa936782c3a87c265fcbd857 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Mon, 3 Aug 2020 10:07:30 -0500 Subject: [PATCH] docs(react): update accordion docs with mdx example (#6572) * docs(react): update accordion docs with mdx example * docs(accordion): update table-of-contents * docs(accordion): update default example --- .../components/Accordion/Accordion-story.js | 31 ++-- .../src/components/Accordion/Accordion.mdx | 154 ++++++++++++++++++ 2 files changed, 172 insertions(+), 13 deletions(-) create mode 100644 packages/react/src/components/Accordion/Accordion.mdx diff --git a/packages/react/src/components/Accordion/Accordion-story.js b/packages/react/src/components/Accordion/Accordion-story.js index 70feeef3c50a..cd39ae007e16 100644 --- a/packages/react/src/components/Accordion/Accordion-story.js +++ b/packages/react/src/components/Accordion/Accordion-story.js @@ -22,6 +22,7 @@ import { AccordionSkeleton, } from '../Accordion'; import Button from '../Button'; +import mdx from './Accordion.mdx'; export default { title: 'Accordion', @@ -31,6 +32,11 @@ export default { AccordionSkeleton, }, decorators: [withKnobs], + parameters: { + docs: { + page: mdx, + }, + }, }; export const accordion = () => ( @@ -52,15 +58,14 @@ export const accordion = () => (

- +

+ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod + tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim + veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea + commodo consequat. +

- - Section 4 title (the title can be a node) - - } - {...props}> +

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim @@ -71,11 +76,11 @@ export const accordion = () => ( ); -export const skeleton = () => ( -

- -
-); +export const skeleton = () => ; + +skeleton.story = { + decorators: [(story) =>
{story()}
], +}; const props = { onClick: action('onClick'), diff --git a/packages/react/src/components/Accordion/Accordion.mdx b/packages/react/src/components/Accordion/Accordion.mdx new file mode 100644 index 000000000000..9e8554de5c4c --- /dev/null +++ b/packages/react/src/components/Accordion/Accordion.mdx @@ -0,0 +1,154 @@ +import { Story, Props, Source, Preview } from '@storybook/addon-docs/blocks'; +import { Accordion, AccordionItem, AccordionSkeleton } from '../Accordion'; + +# Accordion + + + + +## Table of Contents + +- [Overview](#overview) +- [Skeleton state](#skeleton-state) +- [Component API](#component-api) +- [References](#references) +- [Feedback](#feedback) + + + +## Overview + +You can build an accordion using a combination of the `Accordion` and +`AccordionItem` components. The `Accordion` components accepts a list of +`AccordionItem` components as `children` and each `AccordionItem` is responsible +for displaying the accordion's heading and panel content. + +You can configure the accordion item's heading using the `title` prop. +Everything you pass in as a child of `AccordionItem` will be rendered in the +accordion's panel. + + + + + +## Skeleton state + +You can use the `AccordionSkeleton` component to render a skeleton variant of an +accordion. This is useful to display while content in your accordion is being +fetched from an external resource like an API. + + + + + +## Component API + + + +Additional props passed into `Accordion` will be forwarded along to the +underlying accordion container. + +### Accordion align + +In rare cases, you may need to specify the alignment of the icon in the +accordion. You can use the `align` prop to specify the side where the icon +should be placed. + +_Note: This prop must not be used to create a tree view or set of nested +accordions._ + +```jsx + + Panel A + Panel B + Panel C + +``` + +### Accordion className + +The `className` prop passed into `Accordion` will be forwarded along to the +underlying accordion container. This is useful for specifying a custom class +name for layout. + +```jsx + + Panel A + Panel B + Panel C + +``` + +### AccordionItem props + +Additional props passed into `AccordionItem`, such as `onClick`, will be passed +through to the underlying accordion header. + +### AccordionItem className + +The `className` prop passed into `AccordionItem` will be forwarded along to the +underlying accordion header. This is useful for specifying a custom class name +for layout. + +```jsx + + + Panel A + + Panel B + Panel C + +``` + +### AccordionItem title + +You can use the `title` prop to specify the accordion item's heading. The +default behavior is to pass in a `string` as the title, however you can also +pass in a `node`. + +_Note: A custom title prop that renders an interactive element is considered an +accessibility violation. For more information, visit our +[reference section](#why-is-interactive-content-in-a-heading-considered-an-accessibility-violation) +below._ + +```jsx + + Panel A}>Panel A + Panel B + Panel C + +``` + +### AccordionSkeleton props + +Additional props passed into `AccordionSkeleton` will be forwarded along to the +underlying skeleton container. + +### AccordionSkeleton className + +The `className` prop passed into `AccordionSkeleton` will be forwarded along to +the underlying skeleton container. This is useful for specifying a custom class +name for layout. + +```jsx + +``` + +## References + +### Why is interactive content in a heading considered an accessibility violation? + +When using the `title` prop from `Accordion`, it is possible to render arbitrary +markup within the accordion header. The accordion header itself is rendered as a +`