feat: major update to how documentation is fetched and rendered and m…

…ade small fixes to make everything as consistent as possible (#1070)

closes #981 
closes #1010 
also made first steps to use @utrecht/components, but only in storybook
for now (#1009)

- There are a lot of // TODO comments because in a lot of cases the
documentation is not structurized correctly in @utrecht/components.
Wherever it was in the right structure I used the Utrecht documentation
as much as possible (although sometimes they were very lacking in
content, in which cases I skipped them as well)
- I added functionality to packages/storybook/config/preview.tsx to
render links and componentOrigin text that can be added using the
github, figma, nldesignsystem and componentOrigin parameters in
storybook respectively.
- Here is an example of a storybook page where the links are filled with
parameters and the documentation is coming from @utrecht/components:
[Radio
button](https://rijkshuisstijl-community-git-chore-utre-1cc52e-nl-design-system.vercel.app/?path=/docs/rhc-radio--docs)

---------

Co-authored-by: Ruben Smit <[email protected]>

packages/components-css/index.scss

@@ -14,6 +14,7 @@
 @use "src/breadcrumb-nav/index" as breadcrumb;
 @use "src/button/index" as button;
 @use "src/card/index" as card;
+@use "src/code-input/index" as codeInput;
 @use "src/dot-badge/index" as dotBadge;
 @use "src/checkbox/index" as checkbox;
 @use "src/figure/index" as figure;
@@ -32,7 +33,9 @@
 @use "src/navbar/index" as navbar;
 @use "src/message-list/index" as messageList;
 @use "src/navigation-list/index" as navigationList;
+@use "src/number-badge/index" as numberBadge;
 @use "src/ordered-list/index" as orderedList;
+@use "src/pre-heading/index" as preHeading;
 @use "src/radio/index" as radio;
 @use "src/radio-group/index" as radioGroup;
 @use "src/select/index" as select;
@@ -41,11 +44,8 @@
 @use "src/skip-link/index" as skipLink;
 @use "src/table/index" as table;
 @use "src/textarea/index" as textarea;
-@use "src/textinput/index" as textinput;
+@use "src/text-input/index" as textinput;
 @use "src/toggletip/index" as toggletip;
 @use "src/unordered-list/index" as unorderedList;
-@use "src/badgecounter/index" as badgecounter;
-@use "src/pre-heading/index" as preHeading;
-@use "src/code-input/index" as codeInput;
 @use "src/visually-hidden/index" as visually-hidden;
 @use "src/wrapper/index" as wrapper;

packages/components-react/src/Article.tsx

@@ -1,10 +1 @@
-import { Article as UtrechtArticle, ArticleProps as UtrechtArticleProps } from '@utrecht/component-library-react';
-import { ForwardedRef, forwardRef, PropsWithChildren } from 'react';
-
-export const Article = forwardRef(
-  (props: PropsWithChildren<UtrechtArticleProps>, ref: ForwardedRef<HTMLDivElement>) => {
-    return <UtrechtArticle ref={ref} {...props}></UtrechtArticle>;
-  },
-);
-
-Article.displayName = 'Article';
+export { Article, type ArticleProps } from '@utrecht/component-library-react';

packages/components-react/src/FormFieldCheckboxOption.tsx

@@ -1,4 +1,4 @@
-import { FormFieldCheckbox, FormFieldCheckboxProps } from '@utrecht/component-library-react';
+import { FormFieldCheckbox, type FormFieldCheckboxProps } from '@utrecht/component-library-react';
 import clsx from 'clsx';
 import { ForwardedRef, forwardRef, useId } from 'react';
 import { Icon } from './icon/Icon';

packages/components-react/src/FormFieldTextInput.tsx

@@ -1,11 +1,13 @@
 import {
   FormFieldTextboxProps as FormFieldTextInputProps,
-  FormFieldTextbox as TextInput,
+  FormFieldTextbox as UtrechtFormFieldTextInput,
 } from '@utrecht/component-library-react';
 import clsx from 'clsx';
 import { ForwardedRef, forwardRef, PropsWithChildren, useId } from 'react';
 import { Icon } from './icon/Icon';
 
+export { type FormFieldTextInputProps };
+
 export const FormFieldTextInput = forwardRef(
   (
     { invalid, errorMessage, description, status, children, ...restProps }: PropsWithChildren<FormFieldTextInputProps>,
@@ -25,7 +27,7 @@ export const FormFieldTextInput = forwardRef(
       );
 
     return (
-      <TextInput
+      <UtrechtFormFieldTextInput
         description={description}
         errorMessage={errorMsg()}
         id={inputId}
@@ -42,7 +44,7 @@ export const FormFieldTextInput = forwardRef(
         {...restProps}
       >
         {children}
-      </TextInput>
+      </UtrechtFormFieldTextInput>
     );
   },
 );

packages/components-react/src/FormFieldTextarea.tsx

@@ -1,9 +1,12 @@
-import { FormFieldTextareaProps, FormFieldTextarea as Textarea } from '@utrecht/component-library-react';
+import {
+  FormFieldTextareaProps,
+  FormFieldTextarea as UtrechtFormFieldTextarea,
+} from '@utrecht/component-library-react';
 import clsx from 'clsx';
 import { ForwardedRef, forwardRef, PropsWithChildren, useId } from 'react';
 import { Icon } from './icon/Icon';
 
-export { Textarea, type FormFieldTextareaProps };
+export { type FormFieldTextareaProps };
 
 export const FormFieldTextarea = forwardRef(
   (
@@ -24,7 +27,7 @@ export const FormFieldTextarea = forwardRef(
       );
 
     return (
-      <Textarea
+      <UtrechtFormFieldTextarea
         description={description}
         errorMessage={errorMsg()}
         id={inputId}

packages/components-react/src/Textarea.test.tsx

@@ -0,0 +1,15 @@
+import '@testing-library/jest-dom';
+
+import { render } from '@testing-library/react';
+import { Textarea } from '.';
+
+describe('Textarea', () => {
+  it('renders a visible element', () => {
+    const { container } = render(<Textarea />);
+
+    const textarea = container.querySelector(':only-child');
+
+    expect(textarea).toBeInTheDocument();
+    expect(textarea).toBeVisible();
+  });
+});

packages/components-react/src/Textarea.tsx

@@ -0,0 +1 @@
+export { Textarea, type TextareaProps } from '@utrecht/component-library-react';

packages/components-react/src/index.ts

@@ -68,8 +68,8 @@ export { FormFieldErrorMessage, type FormFieldErrorMessageProps } from './FormFi
 export { FormFieldRadio, type FormFieldRadioProps } from './FormFieldRadio';
 export { FormFieldRadioGroup, type FormFieldRadioGroupProps } from './FormFieldRadioGroup';
 export { FormFieldSelect, type FormFieldSelectProps, SelectOption, type SelectOptionProps } from './FormFieldSelect';
-export { FormFieldTextInput } from './FormFieldTextInput';
-export { FormFieldTextarea, type FormFieldTextareaProps, Textarea } from './FormFieldTextarea';
+export { FormFieldTextInput, type FormFieldTextInputProps } from './FormFieldTextInput';
+export { FormFieldTextarea, type FormFieldTextareaProps } from './FormFieldTextarea';
 export { Heading, type HeadingProps } from './Heading';
 export { HeadingGroup, type HeadingGroupProps } from './HeadingGroup';
 export { Hero, type HeroProps } from './Hero';
@@ -121,6 +121,7 @@ export { TableCaption } from './TableCaption';
 export { TableCell, type TableCellProps } from './TableCell';
 export { TableHeaderCell, type TableHeaderCellProps } from './TableHeaderCell';
 export { TextInput, type TextInputProps } from './TextInput';
+export { Textarea, type TextareaProps } from './Textarea';
 export { Toggletip, ToggletipButton, ToggletipContent, type ToggletipProps } from './Toggletip';
 export { UnorderedList, type UnorderedListProps } from './UnorderedList';
 export { UnorderedListItem, type UnorderedListItemProps } from './UnorderedListItem';

packages/storybook/config/preview.tsx

@@ -6,10 +6,13 @@ import '@rijkshuisstijl-community/logius-design-tokens/dist/theme.css';
 import '@rijkshuisstijl-community/mijnoverheid-design-tokens/dist/theme.css';
 import '@rijkshuisstijl-community/rivm-design-tokens/dist/theme.css';
 import '@rijkshuisstijl-community/components-css/dist/index.css';
+import { Paragraph } from '@rijkshuisstijl-community/components-react';
 import { defineCustomElements } from '@rijkshuisstijl-community/web-components-stencil/loader/index';
 import { withThemeByClassName } from '@storybook/addon-themes';
+import { Controls, Description, Primary, Stories, useOf } from '@storybook/blocks';
 import { Preview } from '@storybook/react';
 import { defineCustomElements as defineUtrechtCustomElements } from '@utrecht/web-component-library-stencil/loader/index';
+import { Fragment } from 'react';
 
 // Initialize web components
 defineCustomElements();
@@ -58,6 +61,39 @@ const preview: Preview = {
       },
     },
     docs: {
+      page: () => {
+        const storyParameters: any = useOf<'story'>('story')?.story?.parameters;
+        const parameterLabels = {
+          nldesignsystem: 'NL Design System',
+          figma: 'Figma',
+          github: 'GitHub',
+        };
+        const links = (
+          <>
+            {['nldesignsystem', 'figma', 'github']
+              .filter((parameterKey) => storyParameters?.[parameterKey])
+              .map((parameterKey, index) => (
+                <Fragment key={parameterKey}>
+                  {index > 0 && ' | '}
+                  <a href={storyParameters[parameterKey]}>
+                    {parameterLabels[parameterKey as keyof typeof parameterLabels]}
+                  </a>
+                </Fragment>
+              ))}
+          </>
+        );
+        // Exclude `<Title>` because the title comes from the Markdown file
+        return (
+          <>
+            {links}
+            {storyParameters?.componentOrigin && <Paragraph>{storyParameters.componentOrigin}</Paragraph>}
+            <Description />
+            <Primary />
+            <Controls />
+            <Stories />
+          </>
+        );
+      },
       source: {
         state: 'open',
 

packages/storybook/helpers/merge-markdown.ts

@@ -0,0 +1,5 @@
+import { remark } from 'remark';
+import remarkNormalizeHeadings from 'remark-normalize-headings';
+
+export const mergeMarkdown = (markdown: string[]) =>
+  String(remark().use(remarkNormalizeHeadings).processSync(markdown.join('\n\n')));

packages/storybook/package.json

@@ -64,6 +64,7 @@
     "@types/react-dom": "19.0.1",
     "@types/twig": "1.12.16",
     "@utrecht/component-library-react": "7.3.8",
+    "@utrecht/components": "7.4.0",
     "@utrecht/web-component-library-react": "3.0.0",
     "@utrecht/web-component-library-stencil": "2.2.0",
     "@whitespace/storybook-addon-html": "6.1.1",
@@ -75,6 +76,8 @@
     "react": "19.0.0",
     "react-dom": "19.0.0",
     "react-syntax-highlighter": "15.6.1",
+    "remark": "15.0.1",
+    "remark-normalize-headings": "4.0.0",
     "require-from-string": "2.0.2",
     "rimraf": "6.0.1",
     "storybook": "8.4.7",

packages/storybook/src/community/accordion.stories.tsx

@@ -1,8 +1,9 @@
 import { AccordionProvider, AccordionSectionProps } from '@rijkshuisstijl-community/components-react';
 import { Meta, StoryObj } from '@storybook/react';
+import readme from '@utrecht/components/accordion/README.md?raw';
 import { UtrechtIconChevronDown } from '@utrecht/web-component-library-react';
 import { ReactNode } from 'react';
-import readme from './accordion.md?raw';
+import { mergeMarkdown } from '../../helpers/merge-markdown';
 
 interface AccordionStoryProps {
   label: string;
@@ -77,9 +78,13 @@ const meta = {
     },
     docs: {
       description: {
-        component: readme,
+        // TODO: restructure this, but not until readme is correctly structurized in the Utrecht documentation source
+        component: mergeMarkdown([readme]),
       },
     },
+    // TODO: add Figma, GitHub and NL DesignSystem links
+    componentOrigin:
+      'Dit component is overgenomen van de Gemeente Utrecht, met styling van de Rijkshuisstijl Community.',
   },
   render: AccordionStory,
 } satisfies Meta<AccordionStoryProps>;

packages/storybook/src/community/action-group.stories.tsx

@@ -1,6 +1,8 @@
 import { ActionGroup, Button } from '@rijkshuisstijl-community/components-react';
 import { Meta, StoryObj } from '@storybook/react/*';
 import readme from './action-group.md?raw';
+import { mergeMarkdown } from '../../helpers/merge-markdown';
+
 const meta = {
   title: 'Rijkshuisstijl/ActionGroup',
   id: 'rhc-action-group',
@@ -19,9 +21,13 @@ const meta = {
     },
     docs: {
       description: {
-        component: readme,
+        // TODO: restructure this, but not until readme is correctly structurized in the Utrecht documentation source. Use our own documentation to correctly show its name as "Action Group" instead of "Button Group"
+        component: mergeMarkdown([readme]),
       },
     },
+    // TODO: add Figma, GitHub and NL DesignSystem links
+    componentOrigin:
+      'Dit component is overgenomen van de Gemeente Utrecht (daar heeft het de naam ButtonGroup), met styling van de Rijkshuisstijl Community.',
   },
 } as Meta<typeof ActionGroup>;
 

packages/storybook/src/community/alert.md

@@ -2,8 +2,6 @@
 
 # Rijkshuisstijl Community alert component
 
-[NL design system](https://www.nldesignsystem.nl/alert/) | [Figma](https://www.figma.com/design/txFX5MGRf4O904dtIFcGTF/NLDS---Rijkshuisstijl---Bibliotheek?node-id=1195-4201&t=n1djYpmvDCKmAEUi-0) | [GitHub](https://github.com/nl-design-system/rijkshuisstijl-community/issues/472)
-
 De alert component is er voor berichten die de gebruiker snel moet weten, omdat ze belangrijk zijn voor het uitvoeren van de huidige taak. De alert is alleen voor eenvoudige berichten. Gebruik in de alert geen buttons, geen formulier-componenten en geen complexe opmaak zoals tabellen.
 
 Let op: de alert component gebruiken kan essentieël zijn voor gebruikers van een schermvoorlezer, maar onjuist gebruik kan heel erg vervelend zijn.

packages/storybook/src/community/alert.stories.tsx

@@ -3,6 +3,7 @@
 import { Alert } from '@rijkshuisstijl-community/components-react';
 import type { Meta, StoryObj } from '@storybook/react';
 import readme from './alert.md?raw';
+import { mergeMarkdown } from '../../helpers/merge-markdown';
 
 const meta = {
   title: 'Rijkshuisstijl/Alert',
@@ -57,9 +58,16 @@ const meta = {
     },
     docs: {
       description: {
-        component: readme,
+        // TODO: disconnect "Usage" from the current readme, import the readme from Utrecht afterwards and combine with our own Usage
+        component: mergeMarkdown([readme]),
       },
     },
+    figma:
+      'https://www.figma.com/design/txFX5MGRf4O904dtIFcGTF/NLDS---Rijkshuisstijl---Bibliotheek?node-id=1195-4201&t=n1djYpmvDCKmAEUi-0',
+    github: 'https://github.com/nl-design-system/rijkshuisstijl-community/issues/472',
+    nldesignsystem: 'https://www.nldesignsystem.nl/alert/',
+    componentOrigin:
+      'Dit component is overgenomen van de Gemeente Utrecht, met HTML aanpassingen en styling van de Rijkshuisstijl Community.',
   },
 } as Meta<typeof Alert>;
 

packages/storybook/src/community/article.md

@@ -2,8 +2,6 @@
 
 # Rijkshuisstijl Community article component
 
-[NL design system](https://www.nldesignsystem.nl/article/) | [GitHub](https://github.com/nl-design-system/rijkshuisstijl-community/issues/566)
-
 De article component is er om de breedte van de inhoud ervan te beperken tot de ideale lees-lengte.
 
 ## Usage

packages/storybook/src/community/article.stories.tsx

@@ -3,6 +3,7 @@
 import { Article } from '@rijkshuisstijl-community/components-react';
 import type { Meta, StoryObj } from '@storybook/react';
 import readme from './article.md?raw';
+import { mergeMarkdown } from '../../helpers/merge-markdown';
 
 const meta = {
   title: 'Rijkshuisstijl/Article',
@@ -29,9 +30,15 @@ const meta = {
     },
     docs: {
       description: {
-        component: readme,
+        // TODO: restructure this, but not until readme is correctly structurized in the Utrecht documentation source
+        component: mergeMarkdown([readme]),
       },
     },
+    // TODO: add Figma link
+    github: 'https://github.com/nl-design-system/rijkshuisstijl-community/issues/566',
+    nldesignsystem: 'https://www.nldesignsystem.nl/article/',
+    componentOrigin:
+      'Dit component is overgenomen van de Gemeente Utrecht, met alleen overgeschreven design tokens van de Rijkshuisstijl Community.',
   },
 } as Meta<typeof Article>;