docs(Button): update format and fix icon docs (#4218)

* docs(Button): update format and fix icon docs * docs(IconButton): update description
cultureamp · Oct 27, 2023 · feca5e7 · feca5e7
1 parent e0bd4a3
commit feca5e7
Show file tree

Hide file tree

Showing 5 changed files with 105 additions and 71 deletions.
diff --git a/.changeset/sharp-years-tan.md b/.changeset/sharp-years-tan.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/components/src/Button/Button/_docs/Button.mdx b/packages/components/src/Button/Button/_docs/Button.mdx
@@ -1,5 +1,5 @@
-import { Canvas, Controls, DocsStory, Meta } from "@storybook/blocks"
-import { ResourceLinks, KaioNotification, Installation } from "~storybook/components"
+import { Canvas, Controls, Meta } from "@storybook/blocks"
+import { ResourceLinks, KaioNotification, Installation, LinkTo } from "~storybook/components"
 import * as ButtonStories from "./Button.stories"
 
 <Meta of={ButtonStories} />
@@ -23,26 +23,75 @@ import * as ButtonStories from "./Button.stories"
 ## Overview
 
 Buttons perform actions.
+If it needs to navigate somewhere and can be opened in a new tab, use a link instead.
 
 <Canvas of={ButtonStories.Playground} />
 <Controls of={ButtonStories.Playground} />
 
 ## API
 
-<DocsStory of={ButtonStories.Variants} />
+### Variants
 
-<DocsStory of={ButtonStories.Reversed} />
+`Default`, `Primary`, `Destructive`, `Secondary`
+If no `variant` is specified, a `Default` button will be rendered.
 
-<DocsStory of={ButtonStories.Disabled} />
+<Canvas of={ButtonStories.Variants} />
 
-<DocsStory of={ButtonStories.Icon} />
+#### Reversed
 
-<DocsStory of={ButtonStories.Badge} />
+<Canvas of={ButtonStories.Reversed} />
 
-<DocsStory of={ButtonStories.FullWidth} />
+### Disabled
 
-<DocsStory of={ButtonStories.Working} />
+A disabled Button prevents user interaction. It doesn't appear in the tab order, can't receive focus, and may not read aloud by a screenreader.
 
-<DocsStory of={ButtonStories.Loading} />
+<Canvas of={ButtonStories.Disabled} />
 
-<DocsStory of={ButtonStories.NativeFormButton} />
+### Icon
+
+Use any <LinkTo pageId="components-icons">Icon</LinkTo> component in the `icon` prop.
+
+<Canvas of={ButtonStories.Icon} />
+
+#### Icon position
+
+Change the icon placement with the `iconPosition` prop.
+Default position is `start`.
+
+<Canvas of={ButtonStories.IconPosition} />
+
+### Badge
+
+You can display a `Badge` component within the button using the `badge` prop.
+
+<Canvas of={ButtonStories.Badge} />
+
+### Full width
+
+Buttons can be stretched to fill the full width of their container.
+
+<Canvas of={ButtonStories.FullWidth} />
+
+### Working
+
+The `working` prop should be used in situations where a button action triggers a change in UI state but needs to wait for a server response, such as submitting a form.
+
+In conjuction use the `workingLabel` prop to update the label of the button when the working state is triggered.
+
+Alternatively use the `workingLabelHidden` prop to hide the button label all together.
+
+<Canvas of={ButtonStories.Working} />
+
+### Loading
+
+Use the <LinkTo pageId="components-loading-states-loadinginput">LoadingInput</LinkTo> component for button placeholders.
+
+<Canvas of={ButtonStories.Loading} />
+
+### Native `form` attribute
+
+Button extends native HTML "form" attributes for `button`.
+
+You can use this to submit a `form` using `Button` with a matching form id.
+
+<Canvas of={ButtonStories.NativeFormButton} />
diff --git a/packages/components/src/Button/Button/_docs/Button.stories.tsx b/packages/components/src/Button/Button/_docs/Button.stories.tsx
@@ -1,8 +1,8 @@
-import React, { ReactNode } from "react"
+import React from "react"
 import { StoryObj, Meta } from "@storybook/react"
 import { TextField } from "@kaizen/draft-form"
-import { LoadingInput } from "@kaizen/loading-skeleton"
 import { AddIcon, ArrowRightIcon } from "~components/Icon"
+import { LoadingInput } from "~components/Loading"
 import { Button } from "../index"
 
 const meta = {
@@ -17,9 +17,6 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
-/**
- * Buttons perform actions. If it needs to navigate somewhere and can be opened in a new tab, use a link instead.
- */
 export const Playground: Story = {
   parameters: {
     docs: {
@@ -30,22 +27,25 @@ export const Playground: Story = {
   },
 }
 
-/**
- * <p>`Default`, `Primary`, `Destructive`, `Secondary`</p>
- * <p>If no `variant` is specified, a `Default` button will be rendered.</p>
- */
 export const Variants: Story = {
   render: ({ reversed }) => (
-    <div style={{ display: "flex", gap: "1rem" }}>
+    <>
       <Button label="Default" reversed={reversed} />
       <Button label="Primary" primary reversed={reversed} />
       <Button label="Destructive" destructive reversed={reversed} />
       <Button label="Secondary" secondary reversed={reversed} />
       {!reversed && (
         <Button label="Secondary Destructive" secondary destructive />
       )}
-    </div>
+    </>
   ),
+  decorators: [
+    Story => (
+      <div style={{ display: "flex", gap: "1rem" }}>
+        <Story />
+      </div>
+    ),
+  ],
   parameters: { controls: { disable: true } },
 }
 
@@ -58,88 +58,70 @@ export const Reversed: Story = {
   },
 }
 
-/**
- * A disabled Button prevents user interaction. It doesn’t appear in the tab order, can’t receive focus, and may not read aloud by a screenreader.
- */
 export const Disabled: Story = {
   args: { disabled: true },
 }
 
-/**
- * <p>When a Button is supplied to the `icon` prop, it displays an icon.</p>
- * <p>`import trashIcon from "@kaizen/component-library/icons/trash.icon.svg"`</p>
- * <p>Once the icons are imported, you can pass them directly into the Button component.</p>
- * <h3>IconPosition</h3>
- * <p>The consumer can specify the icon placement with the iconPosition prop, default position is start.</p>
- */
+const sourceCodeIcon = `
+import { Button, AddIcon } from "@kaizen/components"
+
+<Button label="Label" icon={<AddIcon role="presentation" />} />
+`
+
 export const Icon: Story = {
-  render: () => (
-    <div style={{ display: "flex", gap: "1rem" }}>
-      <Button label="Label" icon={<AddIcon role="presentation" />} />
-      <Button
-        label="Label"
-        icon={<ArrowRightIcon role="presentation" />}
-        iconPosition="end"
-      />
-    </div>
-  ),
-  parameters: { controls: { disable: true } },
+  args: {
+    icon: <AddIcon role="presentation" />,
+  },
+  parameters: {
+    docs: { source: { code: sourceCodeIcon } },
+  },
+}
+
+export const IconPosition: Story = {
+  args: {
+    icon: <ArrowRightIcon role="presentation" />,
+    iconPosition: "end",
+  },
 }
 
-/**
- * You can display a `Badge` component within the button using the `badge` prop.
- */
 export const Badge: Story = {
   args: {
     badge: { text: "3", variant: "active" },
     secondary: true,
   },
 }
 
-/**
- * Buttons can be stretched to fill the full width of their container.
- */
 export const FullWidth: Story = {
   args: { fullWidth: true },
 }
 
-const WorkingWrapper = ({ children }: { children: ReactNode }): JSX.Element => (
-  <div style={{ display: "flex", gap: "1rem" }}>{children}</div>
-)
-
-/**
- * <p>The `working` prop should be used in situations where a button action triggers a change in UI state but needs to wait for a server response, such as submitting a form</p>
- * <p>In conjuction use the `workingLabel` prop to update the label of the button when the working state is triggered.</p>
- * <p>Alternatively use the `workingLabelHidden` prop to hide the button label all together.</p>
- */
 export const Working: Story = {
   render: () => (
-    <WorkingWrapper>
+    <>
       <Button label="Label" working workingLabel="Submitting" />
       <Button
         label="Label"
         working
         workingLabel="Submitting"
         workingLabelHidden
       />
-    </WorkingWrapper>
+    </>
   ),
+  decorators: [
+    Story => (
+      <div style={{ display: "flex", gap: "1rem" }}>
+        <Story />
+      </div>
+    ),
+  ],
   parameters: { controls: { disable: true } },
 }
 
-/**
- * <p>Use the LoadingInput component from the loading-skeleton package. Please refer to the LoadingInput Component guidelines.</p>
- * `import { LoadingInput } from "@kaizen/loading-skeleton"`
- */
 export const Loading: Story = {
   render: () => <LoadingInput isAnimated width={13} />,
   parameters: { controls: { disable: true } },
 }
 
-/**
- * <p>Button extends native HTML "form" attributes for `button`.</p>
- * <p>You can use this to submit a `form` using `Button` with a matching form id.</p>
- */
 export const NativeFormButton: Story = {
   render: () => (
     <>

diff --git a/packages/components/src/Button/IconButton/_docs/IconButton.mdx b/packages/components/src/Button/IconButton/_docs/IconButton.mdx
@@ -1,5 +1,5 @@
 import { Canvas, Controls, Meta } from "@storybook/blocks"
-import { ResourceLinks, KaioNotification, Installation } from "~storybook/components"
+import { ResourceLinks, KaioNotification, Installation, LinkTo } from "~storybook/components"
 import * as IconButtonStories from "./IconButton.stories"
 
 <Meta of={IconButtonStories} />
@@ -22,7 +22,8 @@ import * as IconButtonStories from "./IconButton.stories"
 
 ## Overview
 
-Buttons perform actions.
+A button with an icon and no visible text (a label is required for accessibility).
+Use any <LinkTo pageId="components-icons">Icon</LinkTo> component in the `icon` prop.
 
 <Canvas of={IconButtonStories.Playground} />
 <Controls of={IconButtonStories.Playground} />
diff --git a/storybook/preview.tsx b/storybook/preview.tsx
@@ -45,7 +45,7 @@ const decorators = [
     return <Story />
   },
   (Story, context) =>
-    context.args.isReversed && !IS_CHROMATIC ? (
+    (context.args.isReversed || context.args.reversed) && !IS_CHROMATIC ? (
       <div className="bg-purple-700 p-16 m-[-1rem]">
         <Story />
       </div>