From bc0766f7887e39016db3dcf5efa6a3d14bc41097 Mon Sep 17 00:00:00 2001 From: Andrew Holloway Date: Mon, 23 Oct 2023 17:14:46 -0500 Subject: [PATCH 01/14] docs(Accordion): update and improve docs --- .../Accordion/Accordion.stories.tsx | 105 +++---- src/components/Accordion/Accordion.tsx | 18 +- .../__snapshots__/Accordion.test.tsx.snap | 286 ++++++------------ 3 files changed, 151 insertions(+), 258 deletions(-) diff --git a/src/components/Accordion/Accordion.stories.tsx b/src/components/Accordion/Accordion.stories.tsx index 9f169a742..59f28d5c2 100644 --- a/src/components/Accordion/Accordion.stories.tsx +++ b/src/components/Accordion/Accordion.stories.tsx @@ -7,6 +7,8 @@ import Icon from '../Icon'; import NumberIcon from '../NumberIcon'; import Text from '../Text'; +type Args = React.ComponentProps; + export default { title: 'Components/Accordion', component: Accordion, @@ -36,20 +38,27 @@ export default { }, }, }, - decorators: [(Story) =>
{Story()}
], + decorators: [(Story) =>
{Story()}
], } as Meta; -type Args = React.ComponentProps; +type Story = StoryObj; -export const Default: StoryObj = {}; +export const Default: Story = {}; -export const Small: StoryObj = { +/** + * Default `Accordion` using the `small` size. + */ +export const Small: Story = { args: { size: 'sm', }, }; -export const Stacked: StoryObj = { +/** + * This demonstrates how one can combine multiple `Accordion` rows, where any of the rows can + * be defaulted to open (using `defaultOpen`). + */ +export const Stacked: Story = { args: { children: ( <> @@ -102,21 +111,21 @@ export const Stacked: StoryObj = { }, }; -export const StackedSmall: StoryObj = { +export const StackedSmall: Story = { args: { ...Stacked.args, size: 'sm', }, }; -export const StackedOutline: StoryObj = { +export const StackedOutline: Story = { args: { ...Stacked.args, hasOutline: true, }, }; -export const StackedSmallOutline: StoryObj = { +export const StackedSmallOutline: Story = { args: { ...Stacked.args, size: 'sm', @@ -125,27 +134,9 @@ export const StackedSmallOutline: StoryObj = { }; /** - * The following stories are mostly for visual regression testing to capture the open state. + * This demonstrates how to specify that a section is not currently expandable using `isExpandable`. */ -export const DefaultOpen: StoryObj = { - args: { - children: ( - - - Massa quam egestas massa. - - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla amet, - massa ultricies iaculis. Quam lacus maecenas nibh malesuada. At - tristique et ullamcorper rhoncus amet pharetra aliquet tortor. - Suscipit dui, nunc sit dui tellus massa laoreet tellus. - - - ), - }, -}; - -export const EmptyStackedOpen: StoryObj = { +export const EmptyStackedOpen: Story = { args: { children: ( <> @@ -190,14 +181,7 @@ export const EmptyStackedOpen: StoryObj = { }, }; -export const SmallOpen: StoryObj = { - args: { - ...DefaultOpen.args, - size: 'sm', - }, -}; - -export const StackedOpen: StoryObj = { +export const StackedOpen: Story = { args: { children: ( <> @@ -242,21 +226,21 @@ export const StackedOpen: StoryObj = { }, }; -export const StackedSmallOpen: StoryObj = { +export const StackedSmallOpen: Story = { args: { ...StackedOpen.args, size: 'sm', }, }; -export const StackedOutlineOpen: StoryObj = { +export const StackedOutlineOpen: Story = { args: { ...StackedOpen.args, hasOutline: true, }, }; -export const StackedSmallOutlineOpen: StoryObj = { +export const StackedSmallOutlineOpen: Story = { args: { ...StackedOpen.args, size: 'sm', @@ -264,8 +248,13 @@ export const StackedSmallOutlineOpen: StoryObj = { }, }; -// Visual regression testing unhelpful since story value is in interaction and as a code example. -export const UsingRenderProp: StoryObj = { +/** + * + * This shows how to use a render prop for the row, to allow controlling render based on component state. + * + * **NOTE**: Visual regression testing unhelpful since story value is in interaction and as a code example. + */ +export const UsingRenderProp: Story = { render: () => ( @@ -289,7 +278,7 @@ export const UsingRenderProp: StoryObj = { * Although headings should provide limited text, we allow for text to span multiple lines, preserving * the size of the state caret. */ -export const WithLargeHeader: StoryObj = { +export const WithLargeHeader: Story = { parameters: { chromatic: { viewports: [chromaticViewports.ipadMini], @@ -313,7 +302,12 @@ export const WithLargeHeader: StoryObj = { }, }; -export const UsingComplexHeaders: StoryObj = { +/** + * You can use other EDS components within the `Accordion.Button` to allow for custom, non-text headers. + * + * **Example**: using `Text` and `Icon` in the `Accordion.Button`. + */ +export const UsingComplexHeaders: Story = { parameters: { badges: ['1.2', 'implementationExample'], }, @@ -322,7 +316,7 @@ export const UsingComplexHeaders: StoryObj = { <> - + = { - + = { }, }; -export const UsingNumberIconInHeaders: StoryObj = { +/** + * You can use other EDS components within the `Accordion.Button` to allow for custom, non-text headers. + * + * **Example**: using `Text` and `NumberIcon` in the `Accordion.Button`. + */ +export const UsingNumberIconInHeaders: Story = { parameters: { badges: ['1.2', 'implementationExample'], }, @@ -372,11 +371,9 @@ export const UsingNumberIconInHeaders: StoryObj = { <> -
+
- - Step 1 - + Step 1
@@ -388,11 +385,9 @@ export const UsingNumberIconInHeaders: StoryObj = { -
- - - Step 2 - +
+ + Step 2
diff --git a/src/components/Accordion/Accordion.tsx b/src/components/Accordion/Accordion.tsx index 7ed22ad0f..b60de8a98 100644 --- a/src/components/Accordion/Accordion.tsx +++ b/src/components/Accordion/Accordion.tsx @@ -18,15 +18,21 @@ type AccordionProps = { */ className?: string; /** - * Outline variant adds extra padding and a rounded border. + * Outline variant adds adjusts the `Accordion` style by defining a containing border and other layout adjustments. + * + * **Default is `false`.** */ hasOutline?: boolean; /** - * Used to specify which heading element should be rendered for each Accordion.Title child. + * Used to specify which heading element should be rendered for each `Accordion.Title` child. + * + * **Default is `"h2"`**. */ headingAs: HeadingElement; /** - * Various Accordion sizes. Defaults to 'md'. + * Various sizes supported by the `Accordion`. + * + * **Default is `"md"`**. */ size?: Extract; }; @@ -41,7 +47,9 @@ type AccordionButtonProps = { */ className?: string; /** - * Icon override for component. Default is 'expand-more' + * Icon override for component. + * + * **Default is `expand-more`**. */ icon?: Extract; /** @@ -106,7 +114,7 @@ const AccordionRowContext = createContext<{ isExpandable?: boolean }>({ /** * `import {Accordion} from "@chanzuckerberg/eds;` * - * Displays a list of headers stacked on top of one another that can reveal or hide associated content. + * Displays one or more headers stacked on top of one another that can reveal or hide associated content. * This component is based on the [Disclosure](https://headlessui.com/react/disclosure) component, provided by HeadlessUI. * * @see https://headlessui.com/react/disclosure diff --git a/src/components/Accordion/__snapshots__/Accordion.test.tsx.snap b/src/components/Accordion/__snapshots__/Accordion.test.tsx.snap index d477e91c4..a6a0dc0a6 100644 --- a/src/components/Accordion/__snapshots__/Accordion.test.tsx.snap +++ b/src/components/Accordion/__snapshots__/Accordion.test.tsx.snap @@ -2,7 +2,7 @@ exports[` Default story renders snapshot 1`] = `
Default story renders snapshot 1`] = `
`; -exports[` DefaultOpen story renders snapshot 1`] = ` -
-
-
- -
- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla amet, massa ultricies iaculis. Quam lacus maecenas nibh malesuada. At tristique et ullamcorper rhoncus amet pharetra aliquet tortor. Suscipit dui, nunc sit dui tellus massa laoreet tellus. -
-
-
-
-`; - exports[` EmptyStackedOpen story renders snapshot 1`] = `
EmptyStackedOpen story renders snapshot 1`] = ` class="accordion-row" > -
- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla amet, massa ultricies iaculis. Quam lacus maecenas nibh malesuada. At tristique et ullamcorper rhoncus amet pharetra aliquet tortor. Suscipit dui, nunc sit dui tellus massa laoreet tellus. -
-
-
-
-`; - exports[` Stacked story renders snapshot 1`] = `
Stacked story renders snapshot 1`] = ` exports[` StackedOpen story renders snapshot 1`] = `
StackedOpen story renders snapshot 1`] = ` class="accordion-row" >