Merge pull request #11324 from TylerAPfledderer/refactor/storybook-proj-docs-and-unification

refactor: update Storybook docs and usage

Author: wackerow

docs/applying-storybook.md

@@ -18,7 +18,7 @@ It's as easy as running `yarn storybook` to boot up a dedicated localhost to see
 
 ## Setting up a component's stories
 
-> 🚨 NOTE: This project uses Storybook v7. The following documentation outlines preferences in setup as it relates to this version. You can refer to the [main docs](https://storybook.js.org/docs/get-started/install) if you need any additional details
+> 🚨 NOTE: This project uses Storybook v7, using the Component Story Format v3 and the `satisfies` keyword to define the type of the meta object. The following documentation outlines preferences in setup as it relates to this version. You can refer to the [main docs](https://storybook.js.org/docs/get-started) if you need any additional details
 
 A Storybook "story" is an instance of a component in a certain state or with certain parameters applied to show an alternative version of the component.
 
@@ -57,9 +57,11 @@ export const Basic: Story = {
 
 **Note**: with the `title` option, we write this based on the groupings set by the Design System. Groupings are declared with forward slashes. (i.e. `Atoms / Form / Input`). See the Storybook docs for details on [Naming conventions](https://storybook.js.org/docs/7.0/react/writing-stories/naming-components-and-hierarchy)
 
+Also, please view the Figma file for the [proposed structure for the Design System](https://www.figma.com/file/Ne3iAassyfAcJ0AlgqioAP/DS-to-storybook-structure?type=design&node-id=42%3A50&mode=design&t=RGkyouvTilzF42y0-1) to provide the correct groupings.
+
 We will maintain this structure for every story file, regardless of simplicity.
 
-Should the component accept props on all or some renders, you can provide an `args` prop for each story and supply the necessary data. And if there is children, use the `render` prop to pass the args and supply children elements.
+Should the component accept props on all or some renders, you can provide an `args` prop for each story and supply the necessary data. This can be done in place of the render if only a single instance of the given component is needed with no other components. If the `children` prop is used, it can still be used in the `args` prop.
 
 Let's say for a `Button` component with different style variants...
 
@@ -77,15 +79,15 @@ export default meta
 type Story = StoryObj<typeof meta>;
 
 export const Solid: Story = {
-  render: (args) => <Button {...args}>A Button</Button>,
   args: {
     variant: 'solid',
+    children: 'A Button'
   }
 }
 export const Outline: Story = {
-  render: (args) => <Button {...args}>A Button</Button>,
   args: {
     variant: 'outline',
+    children: 'A Button'
   }
 }
 
@@ -94,26 +96,51 @@ export const Outline: Story = {
  * they should be shown under one story, so they can be seen side-by-side in the GUI
  * for reviewers to easily compare.
  * This can also be done for various sizes or other like alterations
+ *
+ * 🚨 If prop content is supplied directly to the component and the `args` prop is not used,
+ * do not use the `StoryObj` type. This is especially important when a story rendering multiple versions
+ * of the component.
  */
 
 // Assuming `solid` is the default variant in the Chakra theme config
-export const Variants = () => (
-  <VStack>
-    <Button>A Solid Button</Button>
-    <Button variant="outline">An Outline Button</Button>
-    <Button variant="unstyled">An Unstyled Button</Button>
-  </VStack>
-)
+export const Variants = {
+  render: () => (
+    <VStack>
+      <Button>A Solid Button</Button>
+      <Button variant="outline">An Outline Button</Button>
+      <Button variant="unstyled">An Unstyled Button</Button>
+    </VStack>
+  )
+}
 ```
 
-If only one story is provided for a component, the name of the exported object should match the name in the `title` meta option. (If the title is `Atoms / Form / Button` then the object should be named `Button`) This will hoist the display name up to the parent level in the Storybook dashboard's sidebar.
+### Story file containing a single story
+
+If only one story is provided for a component, the name of the exported object should match the name in the `title` meta option. (If the title is `Atoms / Form / Button` then the object should be named `Button`) This will hoist the display name up to the parent level in the Storybook dashboard's sidebar. This will also mean you have to rename the import of the component. Call it `ButtonComponent`, say.
+
+```tsx
+import ButtonComponent from "."
+
+const meta = {
+  title: "Atoms / Form / Button",
+  component: ButtonComponent,
+} satisfies Meta<typeof ButtonComponent>
+
+export default meta
+
+export const Button: StoryObj<typeof meta> = {
+  render: () => <ButtonComponent />,
+}
+```
 
 As you go and make adjustments to the component itself or it's variant styles, Storybook will hot reload and those changes will appear in the stories that emphasize them.
 
 ## Storybook Dashboard
 
 The dashboard where you view each story has a number of different addons available to check the story thoroughly.
 
+![Screenshot of Storybook Dashboard for Ethereum.org](https://github.com/ethereum/ethereum-org-website/assets/65234762/7dea7692-6a6d-4f1c-b7cb-db177bcab44d)
+
 Outlined below are each area going from left to right in the selections.
 
 | Toolbar above the preview                | Panel below the preview                                                                                                                                                                                                                                                    |

src/components/Alert/Alert.stories.tsx

@@ -4,9 +4,7 @@ import { Meta, StoryObj } from "@storybook/react"
 
 import Alert from "."
 
-type AlertType = typeof Alert
-
-const meta: Meta<AlertType> = {
+const meta = {
   title: "Molecules / Action Feedback / Alerts",
   component: Alert,
   decorators: [
@@ -16,11 +14,11 @@ const meta: Meta<AlertType> = {
       </Flex>
     ),
   ],
-}
+} satisfies Meta<typeof Alert>
 
 export default meta
 
-type Story = StoryObj<AlertType>
+type Story = StoryObj<typeof meta>
 
 const DEMO_DESC = "This is an alert to be used in the top of the content"
 

src/components/Avatar/Avatar.stories.tsx

@@ -4,16 +4,14 @@ import { Meta, StoryObj } from "@storybook/react"
 
 import Avatar from "."
 
-type AvatarType = typeof Avatar
-
-const meta: Meta<AvatarType> = {
+const meta = {
   title: "Atoms / Media & Icons / Avatars",
   component: Avatar,
-}
+} satisfies Meta<typeof Avatar>
 
 export default meta
 
-type Story = StoryObj<AvatarType>
+type Story = StoryObj<typeof meta>
 
 export const Single: Story = {
   args: {

src/components/BannerNotification/BannerNotification.stories.tsx

@@ -1,28 +1,34 @@
 import React from "react"
 import { useTranslation } from "next-i18next"
 import { Text } from "@chakra-ui/react"
-import { Meta, StoryFn } from "@storybook/react"
+import { Meta, StoryObj } from "@storybook/react"
 
 import BannerNotification from "."
 
-export default {
+const meta = {
+  title: "PostMergeBanner",
   component: BannerNotification,
-  args: {
-    shouldShow: true,
-  },
-  decorators: [(Story) => <Story />],
-} as Meta<typeof BannerNotification>
+} satisfies Meta<typeof BannerNotification>
+
+export default meta
 
 /**
  * Story taken from PostMergeBanner component
  * and content from `../../content/developers/tutorials/hello-world-smart-contract-fullstack/index.md`
  */
-export const PostMergeBanner: StoryFn<typeof BannerNotification> = (args) => {
-  const { t } = useTranslation("page-upgrades")
 
-  return (
-    <BannerNotification {...args}>
-      <Text>{t("page-upgrades-post-merge-banner-tutorial-ood")}</Text>
-    </BannerNotification>
-  )
+export const PostMergeBanner: StoryObj<typeof meta> = {
+  args: {
+    shouldShow: true,
+  },
+  render: (args) => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const { t } = useTranslation("page-upgrades")
+
+    return (
+      <BannerNotification {...args}>
+        <Text>{t("page-upgrades-post-merge-banner-tutorial-ood")}</Text>
+      </BannerNotification>
+    )
+  },
 }

src/components/BannerNotification/DismissableBanner.stories.tsx

@@ -1,28 +1,34 @@
 import React from "react"
 import { Meta, StoryObj } from "@storybook/react"
 
-import DismissableBanner from "../Banners/DismissableBanner"
+import DismissableBannerComponent from "../Banners/DismissableBanner"
 
-export default {
-  component: DismissableBanner,
-} as Meta<typeof DismissableBanner>
+const meta = {
+  component: DismissableBannerComponent,
+  title: "DismissableBanner",
+} satisfies Meta<typeof DismissableBannerComponent>
 
+export default meta
 /**
  * Story taken from DismissableBanner component
  */
 const dismissableBannerStoryPageKey = "dismissableBannerStoryPageKey"
 const bannerText = "This is a dismissable banner"
 
-export const DismissableBannerStory: StoryObj<typeof DismissableBanner> = {
+export const DismissableBanner: StoryObj<typeof meta> = {
+  args: {
+    children: <div>{bannerText}</div>,
+    storageKey: dismissableBannerStoryPageKey,
+  },
   play: () => {
     localStorage.setItem(dismissableBannerStoryPageKey, "false")
   },
   render: () => {
     const children = <div>{bannerText}</div>
     return (
-      <DismissableBanner storageKey={dismissableBannerStoryPageKey}>
+      <DismissableBannerComponent storageKey={dismissableBannerStoryPageKey}>
         {children}
-      </DismissableBanner>
+      </DismissableBannerComponent>
     )
   },
 }

src/components/BaseStories/Checkbox.stories.tsx

@@ -4,11 +4,9 @@ import {
   CheckboxGroup,
   VStack,
 } from "@chakra-ui/react"
-import { Meta, StoryObj } from "@storybook/react"
+import { Meta } from "@storybook/react"
 
-type CheckboxType = typeof CheckboxComponent
-
-const meta: Meta<CheckboxType> = {
+const meta = {
   title: "Atoms / Form / Checkbox",
   component: CheckboxComponent,
   parameters: {
@@ -17,15 +15,13 @@ const meta: Meta<CheckboxType> = {
       expanded: false,
     },
   },
-}
+} satisfies Meta<typeof CheckboxComponent>
 
 export default meta
 
-type Story = StoryObj<CheckboxType>
-
 const DEFAULT_VAL = "checked"
 
-export const Checkbox: Story = {
+export const Checkbox = {
   render: () => (
     <CheckboxGroup defaultValue={[DEFAULT_VAL]}>
       <VStack spacing={4} align="flex-start">

src/components/BaseStories/Heading.stories.tsx

@@ -11,8 +11,6 @@ import { Meta, StoryObj } from "@storybook/react"
 
 import Translation from "../Translation"
 
-type HeadingType = typeof HeadingComponent
-
 const meta = {
   title: "Atoms / Typography / Heading",
   component: HeadingComponent,
@@ -26,7 +24,7 @@ const meta = {
       </Flex>
     ),
   ],
-} satisfies Meta<HeadingType>
+} satisfies Meta<typeof HeadingComponent>
 
 export default meta
 

src/components/BaseStories/Link.stories.tsx

@@ -4,8 +4,6 @@ import { Meta, StoryObj } from "@storybook/react"
 
 import Link from "../Link"
 
-type LinkType = typeof Link
-
 const meta = {
   title: "Molecules / Navigation / Links",
   component: Link,
@@ -16,7 +14,7 @@ const meta = {
       </Center>
     ),
   ],
-} satisfies Meta<LinkType>
+} satisfies Meta<typeof Link>
 
 export default meta
 
@@ -45,7 +43,7 @@ export const ExternalLink: Story = {
   render: (args) => <MockParagraph {...args} />,
 }
 
-export const LinkList: Story = {
+export const LinkList = {
   render: () => (
     <Stack spacing="6">
       <Text>

src/components/BaseStories/Radio.stories.tsx

@@ -2,9 +2,7 @@ import * as React from "react"
 import { Flex, Radio as RadioComponent, RadioGroup } from "@chakra-ui/react"
 import { Meta, StoryObj } from "@storybook/react"
 
-type RadioType = typeof RadioComponent
-
-const meta: Meta<RadioType> = {
+const meta = {
   title: "Atoms / Form / Radio",
   component: RadioComponent,
   argTypes: {
@@ -19,11 +17,11 @@ const meta: Meta<RadioType> = {
       expanded: false,
     },
   },
-}
+} satisfies Meta<typeof RadioComponent>
 
 export default meta
 
-type Story = StoryObj<typeof RadioGroup>
+type Story = StoryObj<typeof meta>
 
 export const Radio: Story = {
   args: {

src/components/BaseStories/Switch.stories.tsx

@@ -1,10 +1,8 @@
 import * as React from "react"
 import { SimpleGrid, Switch as SwitchComponent } from "@chakra-ui/react"
-import { Meta, StoryObj } from "@storybook/react"
+import { Meta } from "@storybook/react"
 
-type SwitchType = typeof SwitchComponent
-
-const meta: Meta<SwitchType> = {
+const meta = {
   title: "Atoms / Form / Switch",
   component: SwitchComponent,
   parameters: {
@@ -13,13 +11,11 @@ const meta: Meta<SwitchType> = {
       expanded: false,
     },
   },
-}
+} satisfies Meta<typeof SwitchComponent>
 
 export default meta
 
-type Story = StoryObj<SwitchType>
-
-export const Switch: Story = {
+export const Switch = {
   render: () => (
     <SimpleGrid columns={{ base: 2, lg: 4 }} columnGap={1} alignItems="center">
       <span>isChecked:</span>