docs(heading): improve heading stories

.changeset/light-chairs-appear.md

@@ -0,0 +1,5 @@
+---
+'@nl-design-system-candidate/heading-react': patch
+---
+
+Props zijn gedocumenteerd zodat de intellisense verbeterd

.changeset/spicy-boxes-attend.md

@@ -0,0 +1,5 @@
+---
+'@nl-design-system-candidate/heading-docs': minor
+---
+
+Stories uitgebreid en props / classes gedocumenteerd

packages/components-react/heading-react/src/heading.ts

@@ -7,7 +7,10 @@ export type HeadingLevel = (typeof headingLevels)[number];
 export type HeadingAppearance = `level-${HeadingLevel}`;
 
 export interface HeadingProps extends HTMLAttributes<HTMLHeadingElement> {
+  /** Sets the semantic level of the heading element */
   level: HeadingLevel;
+
+  /** Allows the appearance of the heading to differ from the semantic level */
   appearance?: HeadingAppearance;
 }
 

packages/docs/heading-docs/docs/description.md

@@ -0,0 +1 @@
+Koptekst die in de koppenstructuur ingesteld kan worden op het juiste niveau.

packages/docs/heading-docs/stories/heading.css.meta.tsx

@@ -2,8 +2,17 @@ import type { Meta } from '@storybook/react-vite';
 import { Heading } from '@nl-design-system-candidate/heading-react/css';
 
 const CLASSES = 'classes';
+const API = 'api';
 
 const meta = {
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Het uiterlijk van de heading hoeft niet overeen te komen met de semantische waarde van de heading. Een heading kan een semantisch level 2 hebben (door het gebruik van een `<h2>` element), maar visueel weer gegeven worden als een level 1 door het gebruik van de class `nl-heading--level-1`',
+      },
+    },
+  },
   argTypes: {
     nlHeading: {
       name: 'nl-heading',
@@ -15,11 +24,94 @@ const meta = {
         type: { summary: undefined },
       },
     },
+    appearance1: {
+      name: 'nl-heading--level-1',
+      description: 'Geeft de heading het uiterlijk van een hoofdkop.',
+      control: 'boolean',
+      table: {
+        category: CLASSES,
+        type: { summary: undefined },
+      },
+    },
+    appearance2: {
+      name: 'nl-heading--level-2',
+      description: 'Geeft de heading het uiterlijk van een koptekst van het tweede niveau.',
+      control: 'boolean',
+      table: {
+        category: CLASSES,
+        type: { summary: undefined },
+      },
+    },
+    appearance3: {
+      name: 'nl-heading--level-3',
+      description: 'Geeft de heading het uiterlijk van een koptekst van het derde niveau.',
+      control: 'boolean',
+      table: {
+        category: CLASSES,
+        type: { summary: undefined },
+      },
+    },
+    appearance4: {
+      name: 'nl-heading--level-4',
+      description: 'Geeft de heading het uiterlijk van een koptekst van het vierde niveau.',
+      control: 'boolean',
+      table: {
+        category: CLASSES,
+        type: { summary: undefined },
+      },
+    },
+    appearance5: {
+      name: 'nl-heading--level-5',
+      description: 'Geeft de heading het uiterlijk van een koptekst van het vijfde niveau.',
+      control: 'boolean',
+      table: {
+        category: CLASSES,
+        type: { summary: undefined },
+      },
+    },
+    appearance6: {
+      name: 'nl-heading--level-6',
+      description: 'Geeft de heading het uiterlijk van een koptekst van het zesde niveau.',
+      control: 'boolean',
+      table: {
+        category: CLASSES,
+        type: { summary: undefined },
+      },
+    },
     children: {
-      table: { disable: true },
+      name: 'content',
+      description: 'De inhoud van de heading.',
+      control: 'text',
+      table: {
+        category: API,
+        type: { summary: undefined },
+      },
+    },
+    level: {
+      name: 'element',
+      control: { type: 'select', labels: { 1: '<h1>', 2: '<h2>', 3: '<h3>', 4: '<h4>', 5: '<h5>', 6: '<h6>' } },
+      description: 'Het element van de heading',
+      options: [1, 2, 3, 4, 5, 6],
+      table: {
+        category: API,
+        type: { summary: undefined },
+      },
     },
   },
-  component: (props) => <Heading {...props} />,
+  args: {
+    nlHeading: true,
+    level: 1,
+  },
+  component: (props) => {
+    let appearance = props.appearance1 ? 1 : props.level;
+    appearance = props.appearance2 ? 2 : appearance;
+    appearance = props.appearance3 ? 3 : appearance;
+    appearance = props.appearance4 ? 4 : appearance;
+    appearance = props.appearance5 ? 5 : appearance;
+    appearance = props.appearance6 ? 6 : appearance;
+
+    return <Heading {...props} appearance={`level-${appearance}`} level={props.level} />;
+  },
 } satisfies Meta;
 
 export default meta;

packages/docs/heading-docs/stories/heading.react.meta.tsx

@@ -2,18 +2,35 @@ import type { Meta } from '@storybook/react-vite';
 import { Heading } from '@nl-design-system-candidate/heading-react/css';
 
 const meta = {
-  argTypes: {
-    appearance: {
-      control: { labels: { undefined: '(undefined)' }, type: 'select' },
-      options: [undefined, 'level-1', 'level-2', 'level-3', 'level-4', 'level-5', 'level-6'],
-      table: { category: 'API', type: { summary: 'literal' } },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Het uiterlijk van de heading hoeft niet overeen te komen met de semantische waarde van de heading. Een heading kan een semantisch level 2 hebben (door het gebruik van de `level` prop), maar visueel weer gegeven worden als een level 1 door het gebruik van de `appearance` prop',
+      },
     },
-    children: { table: { category: 'API' } },
+  },
+  argTypes: {
     level: {
       type: { name: 'other', value: 'select', required: true },
+      description: 'Zet het semantische niveau van de heading',
       control: { type: 'select' },
       options: [1, 2, 3, 4, 5, 6],
-      table: { category: 'API', type: { summary: 'unknown[number]' } },
+      table: { category: 'API', type: { summary: '1 | 2 | 3 | 4 | 5 | 6' } },
+    },
+    appearance: {
+      description: 'Geeft de heading een uiterlijk dat afwijkt van het semantische niveau',
+      control: { labels: { undefined: '(undefined)' }, type: 'select' },
+      options: [undefined, 'level-1', 'level-2', 'level-3', 'level-4', 'level-5', 'level-6'],
+      table: {
+        category: 'API',
+        type: { summary: '"level-1" | "level-2" | "level-3" | "level-4" | "level-5" | "level-6"' },
+      },
+    },
+    children: {
+      description: 'De inhoud van de heading',
+      type: { value: 'text', required: true },
+      table: { category: 'API', type: { summary: 'ReactNode' } },
     },
   },
   component: Heading,

packages/docs/heading-docs/stories/heading.stories.tsx

@@ -5,6 +5,104 @@ import { Paragraph } from '@nl-design-system-candidate/paragraph-react/css';
 
 type Story = StoryObj<HeadingProps>;
 
+export const Heading: Story = {
+  name: 'Heading',
+  args: {
+    children: 'Heading',
+    level: 1,
+  },
+};
+
+export const HeadingLevel1: Story = {
+  name: 'Heading level 1',
+  args: {
+    children: 'Heading level 1',
+    level: 1,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `Hoofdkop van een pagina.`,
+      },
+    },
+  },
+};
+
+export const HeadingLevel2: Story = {
+  name: 'Heading level 2',
+  args: {
+    children: 'Heading level 2',
+    level: 2,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `Koptekst die volgt na de hoofdkop en in de koppenstructuur op het tweede niveau staat.`,
+      },
+    },
+  },
+};
+
+export const HeadingLevel3: Story = {
+  name: 'Heading level 3',
+  args: {
+    children: 'Heading level 3',
+    level: 3,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `Koptekst die in de koppenstructuur op het derde niveau staat.`,
+      },
+    },
+  },
+};
+
+export const HeadingLevel4: Story = {
+  name: 'Heading level 4',
+  args: {
+    children: 'Heading level 4',
+    level: 4,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `Koptekst die in de koppenstructuur op het vierde niveau staat.`,
+      },
+    },
+  },
+};
+
+export const HeadingLevel5: Story = {
+  name: 'Heading level 5',
+  args: {
+    children: 'Heading level 5',
+    level: 5,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `Hoofdkop van een pagina.Koptekst die in de koppenstructuur op het vijfde niveau staat.`,
+      },
+    },
+  },
+};
+
+export const HeadingLevel6: Story = {
+  name: 'Heading level 6',
+  args: {
+    children: 'Heading level 6',
+    level: 6,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `Koptekst die in de koppenstructuur op het zesde niveau staat.`,
+      },
+    },
+  },
+};
+
 export const Heading1MetMeerdereRegelsTekst: Story = {
   name: 'Heading 1 met meerdere regels tekst',
   args: {

packages/storybook-shared/src/DocsHeader.tsx

@@ -12,10 +12,13 @@ export function DocsHeader() {
 
   return (
     <div style={{ display: 'flex', gap: '1rem', marginBlock: '1rem' }}>
-      {(externalLinks as ExternalLink[]).map(({ name, url }) => (
-        <a key={url} href={url} target="_blank" rel="noreferrer">
-          {name}
-        </a>
+      {(externalLinks as ExternalLink[]).map(({ name, url }, index, list) => (
+        <>
+          <a key={url} href={url} target="_blank" rel="noreferrer">
+            {name}
+          </a>
+          {index < list.length - 1 ? <span>⋅</span> : <></>}
+        </>
       ))}
     </div>
   );

packages/storybook/stories/heading.css.stories.tsx

@@ -5,15 +5,33 @@ import headingMeta from '@nl-design-system-candidate/heading-docs/stories/headin
 import * as Stories from '@nl-design-system-candidate/heading-docs/stories/heading.stories';
 import { mergeCssMeta } from '../src/helpers/merge-css-meta';
 import { getExternalLinks } from '../src/helpers/external-links';
+import description from '@nl-design-system-candidate/heading-docs/docs/description.md?raw';
 
-const externalLinks = getExternalLinks('https://nldesignsystem.nl/heading', packageJSON.homepage);
+const externalLinks = getExternalLinks(
+  'https://nldesignsystem.nl/heading',
+  packageJSON.homepage,
+  'https://www.npmjs.com/package/@nl-design-system-candidate/heading-css',
+);
 
 const meta = {
-  ...mergeCssMeta(headingMeta, externalLinks),
+  ...mergeCssMeta(headingMeta, externalLinks, {
+    parameters: {
+      docs: {
+        subtitle: description,
+      },
+    },
+  }),
   title: 'CSS Componenten/Heading',
   id: 'css-heading',
 } satisfies Meta<typeof HeadingComponent>;
 
 export default meta;
 
+export const Heading = Stories.Heading;
+export const HeadingLevel1 = Stories.HeadingLevel1;
+export const HeadingLevel2 = Stories.HeadingLevel2;
+export const HeadingLevel3 = Stories.HeadingLevel3;
+export const HeadingLevel4 = Stories.HeadingLevel4;
+export const HeadingLevel5 = Stories.HeadingLevel5;
+export const HeadingLevel6 = Stories.HeadingLevel6;
 export const Heading1MetMeerdereRegelsTekst = Stories.Heading1MetMeerdereRegelsTekst;

packages/storybook/stories/heading.react.stories.tsx

@@ -1,19 +1,37 @@
+import { merge } from 'lodash-es';
 import type { Meta } from '@storybook/react-vite';
 import packageJSON from '../../components-react/heading-react/package.json';
 import { Heading as HeadingComponent } from '@nl-design-system-candidate/heading-react';
 import headingMeta from '@nl-design-system-candidate/heading-docs/stories/heading.react.meta';
 import * as Stories from '@nl-design-system-candidate/heading-docs/stories/heading.stories';
 import { getExternalLinks } from '../src/helpers/external-links';
+import description from '@nl-design-system-candidate/heading-docs/docs/description.md?raw';
 
-const externalLinks = getExternalLinks('https://nldesignsystem.nl/heading', packageJSON.homepage);
+const externalLinks = getExternalLinks(
+  'https://nldesignsystem.nl/heading',
+  packageJSON.homepage,
+  'https://www.npmjs.com/package/@nl-design-system-candidate/heading-react',
+);
 
 const meta = {
-  ...headingMeta,
-  ...externalLinks,
+  ...merge(headingMeta, externalLinks, {
+    parameters: {
+      docs: {
+        subtitle: description,
+      },
+    },
+  }),
   title: 'React Componenten/Heading',
   id: 'heading',
 } satisfies Meta<typeof HeadingComponent>;
 
 export default meta;
 
+export const Heading = Stories.Heading;
+export const HeadingLevel1 = Stories.HeadingLevel1;
+export const HeadingLevel2 = Stories.HeadingLevel2;
+export const HeadingLevel3 = Stories.HeadingLevel3;
+export const HeadingLevel4 = Stories.HeadingLevel4;
+export const HeadingLevel5 = Stories.HeadingLevel5;
+export const HeadingLevel6 = Stories.HeadingLevel6;
 export const Heading1MetMeerdereRegelsTekst = Stories.Heading1MetMeerdereRegelsTekst;