fix: Fix autodocs for stories (#1149)

Co-authored-by: Vincent Smedinga <[email protected]>

documentation/storybook.md

@@ -2,7 +2,7 @@
 
 # Storybook guidelines
 
-We use Storybook 7 to display all components and allow interaction with them.
+We use Storybook to display all components and allow interaction with them.
 
 We publish each merge to the `main` branch to [amsterdam.github.io/design-system](https://amsterdam.github.io/design-system/).
 
@@ -20,6 +20,11 @@ We write our documentation in English, the stories are Dutch.
 
 ## Best practices for controls
 
+Controls are automatically generated based on the component’s typing.
+If you want to document native HTML attributes, you can use [`argTypes`](https://storybook.js.org/docs/api/arg-types).
+You can also use `argTypes` to override the automatically generated controls.
+Be sure to follow these guidelines when you do:
+
 1. For props offering five options or less, use radio buttons rather than a select.
    This makes it easier to compare the options.
    It saves the user a click to select each option and shows everything up front.
@@ -28,6 +33,21 @@ We write our documentation in English, the stories are Dutch.
 
 More to follow.
 
+By default, we hide the `children` prop from the controls.
+Children of React components are often React components themselves, which isn't very useful to show in Storybook.
+However, sometimes it is useful to add `children` to the controls.
+For example, when the child is a simple string (like in the default Button component story).
+
+To do this, you can override the default like so:
+
+```js
+argTypes: {
+  children: {
+    table: { disable: false },
+  },
+},
+```
+
 ## Best practices for stories
 
 1. Use decorators and / or `args.children` before reaching for `render`. `render` can easily mess up the stories’ code view.

packages/react/src/Accordion/Accordion.tsx

@@ -12,6 +12,7 @@ import { HeadingLevel } from '../Heading/Heading'
 import { useKeyboardFocus } from '../common/useKeyboardFocus'
 
 export type AccordionProps = {
+  /** The hierarchical level of the accordion title within the document. */
   headingLevel: HeadingLevel
   section?: boolean
 } & PropsWithChildren<HTMLAttributes<HTMLDivElement>>

packages/react/src/Accordion/AccordionSection.tsx

@@ -8,7 +8,7 @@ import clsx from 'clsx'
 import { forwardRef, useContext, useId, useState } from 'react'
 import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 import AccordionContext from './AccordionContext'
-import { getHeadingElement } from '../Heading/Heading'
+import { getHeadingElement } from '../Heading/getHeadingElement'
 import { Icon } from '../Icon/Icon'
 
 export type AccordionSectionProps = {

packages/react/src/Heading/Heading.tsx

@@ -7,6 +7,7 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
+import { getHeadingElement } from './getHeadingElement'
 
 export type HeadingLevel = 1 | 2 | 3 | 4
 type HeadingSize = 'level-1' | 'level-2' | 'level-3' | 'level-4' | 'level-5' | 'level-6'
@@ -28,19 +29,6 @@ export type HeadingProps = {
   inverseColor?: boolean
 } & PropsWithChildren<HTMLAttributes<HTMLHeadingElement>>
 
-export function getHeadingElement(level: HeadingLevel) {
-  switch (level) {
-    case 2:
-      return 'h2'
-    case 3:
-      return 'h3'
-    case 4:
-      return 'h4'
-    default:
-      return 'h1'
-  }
-}
-
 export const Heading = forwardRef(
   (
     { children, className, inverseColor, level = 1, size, ...restProps }: HeadingProps,

packages/react/src/Heading/getHeadingElement.ts

@@ -0,0 +1,14 @@
+import { HeadingLevel } from './Heading'
+
+export function getHeadingElement(level: HeadingLevel) {
+  switch (level) {
+    case 2:
+      return 'h2'
+    case 3:
+      return 'h3'
+    case 4:
+      return 'h4'
+    default:
+      return 'h1'
+  }
+}

packages/react/src/Image/Image.tsx

@@ -8,7 +8,7 @@ import { forwardRef } from 'react'
 import type { ForwardedRef, ImgHTMLAttributes } from 'react'
 
 export type ImageProps = {
-  cover?: Boolean
+  cover?: boolean
 } & ImgHTMLAttributes<HTMLImageElement>
 
 export const Image = forwardRef(

plop-templates/storybook.stories.tsx.hbs

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { {{pascalCase name}} } from '@amsterdam/design-system-react'
+import { {{pascalCase name}} } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/config/main.ts

@@ -30,6 +30,9 @@ const config: StorybookConfig = {
   docs: {
     autodocs: true,
   },
+  typescript: {
+    reactDocgen: 'react-docgen-typescript',
+  },
 }
 
 export default config

storybook/src/components/Accordion/Accordion.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Accordion, Paragraph } from '@amsterdam/design-system-react'
+import { Accordion, Paragraph } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 import { exampleParagraph } from '../shared/exampleContent'
 
@@ -17,19 +17,6 @@ const meta = {
   args: {
     headingLevel: 1,
   },
-  argTypes: {
-    headingLevel: {
-      control: {
-        type: 'radio',
-      },
-      options: [1, 2, 3, 4],
-    },
-    section: {
-      control: {
-        type: 'boolean',
-      },
-    },
-  },
 } satisfies Meta<typeof Accordion>
 
 export default meta

storybook/src/components/Alert/Alert.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Alert, Link, Paragraph, UnorderedList } from '@amsterdam/design-system-react'
+import { Alert, Link, Paragraph, UnorderedList } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {
@@ -13,23 +13,6 @@ const meta = {
     title: 'Let op',
     closeable: false,
   },
-  argTypes: {
-    severity: {
-      control: {
-        type: 'radio',
-      },
-      options: ['warning', 'error', 'success', 'info'],
-    },
-    closeable: {
-      control: {
-        type: 'boolean',
-        default: false,
-      },
-    },
-    onClose: {
-      action: 'onClose',
-    },
-  },
 } satisfies Meta<typeof Alert>
 
 export default meta

storybook/src/components/AspectRatio/AspectRatio.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { AspectRatio, Image } from '@amsterdam/design-system-react'
+import { AspectRatio, Image } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/Avatar/Avatar.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Avatar, Header, PageMenu } from '@amsterdam/design-system-react'
+import { Avatar, Header, PageMenu } from '@amsterdam/design-system-react/src'
 import { SearchIcon } from '@amsterdam/design-system-react-icons'
 import { Meta, StoryObj } from '@storybook/react'
 
@@ -14,15 +14,6 @@ const meta = {
     label: 'DS',
     imageSrc: '',
   },
-  argTypes: {
-    color: {
-      control: {
-        type: 'select',
-      },
-      options: ['blue', 'dark-blue', 'dark-green', 'green', 'magenta', 'orange', 'purple', 'red', 'yellow'],
-      selected: 'dark-blue',
-    },
-  },
 } satisfies Meta<typeof Avatar>
 
 export default meta

storybook/src/components/Badge/Badge.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Badge } from '@amsterdam/design-system-react'
+import { Badge } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {
@@ -12,15 +12,6 @@ const meta = {
   args: {
     label: 'Tip',
   },
-  argTypes: {
-    color: {
-      control: {
-        type: 'select',
-      },
-      options: ['blue', 'dark-blue', 'dark-green', 'green', 'magenta', 'orange', 'purple', 'yellow'],
-      selected: 'dark-green',
-    },
-  },
 } satisfies Meta<typeof Badge>
 
 export default meta

storybook/src/components/Blockquote/Blockquote.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Blockquote } from '@amsterdam/design-system-react'
+import { Blockquote } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 import { exampleQuote } from '../shared/exampleContent'
 
@@ -20,7 +20,6 @@ const meta = {
     children: {
       table: { disable: false },
     },
-    inverseColor: { control: 'boolean' },
   },
 } satisfies Meta<typeof Blockquote>
 

storybook/src/components/Breadcrumb/Breadcrumb.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Breadcrumb } from '@amsterdam/design-system-react'
+import { Breadcrumb } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/Button/Button.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Button, Icon } from '@amsterdam/design-system-react'
+import { Button, Icon } from '@amsterdam/design-system-react/src'
 import { ShareIcon } from '@amsterdam/design-system-react-icons'
 import { Meta, StoryObj } from '@storybook/react'
 
@@ -19,11 +19,6 @@ const meta = {
     children: {
       table: { disable: false },
     },
-    disabled: { control: 'boolean' },
-    variant: {
-      control: 'select',
-      options: ['primary', 'secondary', 'tertiary'],
-    },
   },
 } satisfies Meta<typeof Button>
 

storybook/src/components/Card/Card.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { AspectRatio, Card, Heading, Image, Paragraph } from '@amsterdam/design-system-react'
+import { AspectRatio, Card, Heading, Image, Paragraph } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const dateFormat = new Intl.DateTimeFormat('nl', {

storybook/src/components/Checkbox/Checkbox.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Checkbox } from '@amsterdam/design-system-react'
+import { Checkbox } from '@amsterdam/design-system-react/src'
 import { useArgs } from '@storybook/preview-api'
 import { Meta, StoryObj } from '@storybook/react'
 

storybook/src/components/Column/Column.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Card, Column, Heading, Paragraph } from '@amsterdam/design-system-react'
+import { Card, Column, Heading, Paragraph } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const ThreeBoxes = Array.from(Array(3).keys()).map((i) => (
@@ -19,13 +19,6 @@ const meta = {
     children: ThreeBoxes,
   },
   argTypes: {
-    as: {
-      control: { type: 'radio' },
-      options: ['article', 'div', 'section'],
-    },
-    children: {
-      table: { disable: true },
-    },
     gap: {
       control: 'radio',
       options: ['extra-small', 'small', 'medium', 'large', 'extra-large'],

storybook/src/components/Dialog/Dialog.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Button, Dialog, Heading, Paragraph } from '@amsterdam/design-system-react'
+import { Button, Dialog, Heading, Paragraph } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/Fieldset/Fieldset.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Checkbox, Fieldset } from '@amsterdam/design-system-react'
+import { Checkbox, Fieldset } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/Footer/Footer.stories.tsx

@@ -3,7 +3,15 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Footer, Grid, Heading, LinkList, PageMenu, Paragraph, VisuallyHidden } from '@amsterdam/design-system-react'
+import {
+  Footer,
+  Grid,
+  Heading,
+  LinkList,
+  PageMenu,
+  Paragraph,
+  VisuallyHidden,
+} from '@amsterdam/design-system-react/src'
 import { EmailIcon, PhoneIcon } from '@amsterdam/design-system-react-icons'
 import { Meta, StoryObj } from '@storybook/react'
 

storybook/src/components/FormFieldCharacterCounter/FormFieldCharacterCounter.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { FormFieldCharacterCounter } from '@amsterdam/design-system-react'
+import { FormFieldCharacterCounter } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {

storybook/src/components/FormLabel/FormLabel.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { FormLabel } from '@amsterdam/design-system-react'
+import { FormLabel } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {