chore: Implement StyleBlock component for components-specific customi…

…sations (#374)

.storybook/components/docsPage/docsPage.tsx

@@ -0,0 +1,16 @@
+import { Controls, Description, Primary, Stories, Subtitle, Title } from '@storybook/blocks';
+import { StyleBlock } from '../styleBlock';
+
+export const DocsPage: React.FC = () => {
+    return (
+        <>
+            <Title />
+            <Subtitle />
+            <Description />
+            <Primary />
+            <Controls />
+            <Stories />
+            <StyleBlock />
+        </>
+    );
+};

.storybook/components/docsPage/index.ts

@@ -0,0 +1 @@
+export { DocsPage } from './docsPage';

.storybook/components/index.ts

@@ -0,0 +1,2 @@
+export * from './docsPage';
+export * from './styleBlock';

.storybook/components/styleBlock/index.ts

@@ -0,0 +1 @@
+export { StyleBlock, type ICustomisationDoc } from './styleBlock';

.storybook/components/styleBlock/styleBlock.tsx

@@ -0,0 +1,64 @@
+import { Subheading, useOf } from '@storybook/blocks';
+
+export interface ICustomisationDoc {
+    /**
+     * Name of the variable.
+     */
+    name: string;
+    /**
+     * Description of the variable.
+     */
+    description?: string;
+    /**
+     * Default value of the variable.
+     */
+    value: string;
+}
+
+const parseCustomisations = (source = ''): ICustomisationDoc[] => {
+    const customisationRegex = /(?:\/\*\s*(.*?)\s*\*\/\s+)?--([\w-]+):\s*(.*?);/g;
+    const matches = Array.from(source.matchAll(customisationRegex));
+
+    const customisations = matches.map(([, description, name, value]) => ({
+        name: `--${name}`,
+        description: description.trim(),
+        value,
+    }));
+
+    return customisations;
+};
+
+export const StyleBlock: React.FC = () => {
+    const metaInfo = useOf<'meta'>('meta');
+
+    const source = metaInfo.preparedMeta.parameters.style as string | undefined;
+    const customisations = parseCustomisations(source);
+
+    if (!customisations.length) {
+        return null;
+    }
+
+    return (
+        <div className="flex flex-col">
+            <Subheading>Customisations</Subheading>
+            <table>
+                <thead>
+                    <tr>
+                        <td>Name</td>
+                        <td>Description</td>
+                        <td>Default</td>
+                    </tr>
+                </thead>
+                <tbody>
+                    {customisations.map(({ name, value, description }) => (
+                        <tr key={name}>
+                            <td>{name}</td>
+                            <td>{description}</td>
+                            <td>{value}</td>
+                        </tr>
+                    ))}
+                </tbody>
+            </table>
+        </div>
+    );
+};

.storybook/main.ts

@@ -64,6 +64,20 @@ const config: StorybookConfig = {
             use: ['@svgr/webpack'],
         });
 
+        // Retrieve and update css rule to support raw imports of CSS files using "?raw"
+        const cssRule = webpackConfig.module?.rules?.find((rule) => {
+            if (rule != null && typeof rule !== 'string' && (rule as RuleSetRule).test instanceof RegExp) {
+                const testRegExp = (rule as RuleSetRule).test as RegExp;
+                return testRegExp.test('.css');
+            }
+
+            return undefined;
+        });
+
+        if (cssRule) {
+            (cssRule as RuleSetRule).resourceQuery = { not: [/raw/] };
+        }
+
         return webpackConfig;
     },
 };

.storybook/preview.tsx

@@ -1,6 +1,7 @@
 import type { Preview } from '@storybook/react';
 import '../index.css';
 import { GukModulesProvider } from '../src/modules';
+import { DocsPage } from './components';
 import './style.css';
 
 const preview: Preview = {
@@ -35,6 +36,9 @@ const preview: Preview = {
                 },
             ],
         },
+        docs: {
+            page: DocsPage,
+        },
     },
 
     decorators: [

CHANGELOG.md

@@ -7,6 +7,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Added
+
+- Implement `StyleBlock` component to document the components-specific customisations
+
 ### Changed
 
 - Remove `hash` property on the `AssetTransfer` module component and add optional `assetAddress` property

src/core/@types/assets.d.ts

@@ -2,3 +2,8 @@ declare module '*.svg' {
     const ReactComponent: React.FC<React.SVGProps<SVGSVGElement>>;
     export default ReactComponent;
 }
+
+declare module '*?raw' {
+    const content: string;
+    export default content;
+}

src/core/components/avatars/avatar/avatar.stories.tsx

@@ -1,10 +1,12 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { Avatar } from './avatar';
+import style from './index.css?raw';
 
 const meta: Meta<typeof Avatar> = {
     title: 'Core/Components/Avatars/Avatar',
     component: Avatar,
     parameters: {
+        style,
         design: {
             type: 'figma',
             url: 'https://www.figma.com/file/jfKRr1V9evJUp1uBeyP3Zz/v1.0.0?node-id=11953-12188&t=RVJHJFTrLMnhgYnJ-4',

src/core/components/avatars/avatar/avatar.tsx

@@ -67,9 +67,6 @@ const responsiveSizeClasses: ResponsiveAttributeClassMap<AvatarSize> = {
     },
 };
 
-/**
- * Avatar component
- */
 export const Avatar: React.FC<IAvatarProps> = (props) => {
     const { alt = 'avatar', className, fallback, responsiveSize, size = 'sm', ...imageProps } = props;
 

src/core/components/collapsible/collapsible.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 import { Collapsible } from './collapsible';
+import style from './index.css?raw';
 
 /**
  * Collapsible component that can wrap any content and visually collapse it for space-saving purposes.
@@ -9,6 +10,7 @@ const meta: Meta<typeof Collapsible> = {
     title: 'Core/Components/Collapsible',
     component: Collapsible,
     parameters: {
+        style,
         design: {
             type: 'figma',
             url: 'https://www.figma.com/file/jfKRr1V9evJUp1uBeyP3Zz/v1.0.0?node-id=10157-27011&t=RVJHJFTrLMnhgYnJ-4',

src/core/components/dialogs/dialog/dialogRoot/dialogRoot.stories.tsx

@@ -2,11 +2,13 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 import { Dialog } from '..';
 import { Button } from '../../../button';
+import style from './index.css?raw';
 
 const meta: Meta<typeof Dialog.Root> = {
     title: 'Core/Components/Dialogs/Dialog/Dialog.Root',
     component: Dialog.Root,
     parameters: {
+        style,
         design: {
             type: 'figma',
             url: 'https://www.figma.com/file/jfKRr1V9evJUp1uBeyP3Zz/v1.0.0?type=design&node-id=13558-17025&mode=design&t=9P6frTNZbQcLyeff-4',

src/core/components/dialogs/dialogAlert/dialogAlertRoot/dialogAlertRoot.stories.tsx

@@ -2,11 +2,13 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 import { DialogAlert } from '..';
 import { Button } from '../../../button';
+import style from './index.css?raw';
 
 const meta: Meta<typeof DialogAlert.Root> = {
     title: 'Core/Components/Dialogs/DialogAlert/DialogAlert.Root',
     component: DialogAlert.Root,
     parameters: {
+        style,
         design: {
             type: 'figma',
             url: 'https://www.figma.com/file/jfKRr1V9evJUp1uBeyP3Zz/v1.0.0?type=design&node-id=13558-17025&mode=design&t=9P6frTNZbQcLyeff-4',

src/core/components/dropdown/dropdownContainer/dropdownContainer.stories.tsx

@@ -1,11 +1,13 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 import { Dropdown, type IDropdownContainerProps } from '../index';
+import style from './index.css?raw';
 
 const meta: Meta<typeof Dropdown.Container> = {
     title: 'Core/Components/Dropdown/Dropdown.Container',
     component: Dropdown.Container,
     parameters: {
+        style,
         design: {
             type: 'figma',
             url: 'https://www.figma.com/file/jfKRr1V9evJUp1uBeyP3Zz/v1.0.0?type=design&node-id=8097-22574&mode=design&t=4o7W5TmAScRx38xw-4',

src/core/components/forms/textAreaRichText/textAreaRichText.stories.tsx

@@ -2,12 +2,14 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 import { Button } from '../../button';
 import { Dialog } from '../../dialogs';
+import style from './index.css?raw';
 import { TextAreaRichText } from './textAreaRichText';
 
 const meta: Meta<typeof TextAreaRichText> = {
     title: 'Core/Components/Forms/TextAreaRichText',
     component: TextAreaRichText,
     parameters: {
+        style,
         design: {
             type: 'figma',
             url: 'https://www.figma.com/file/jfKRr1V9evJUp1uBeyP3Zz/v1.0.0?type=design&node-id=10095-8687&mode=design&t=RRfZug69k5JnpYXM-4',

src/core/components/illustrations/illustrationHuman/illustrationHuman.stories.tsx

@@ -1,10 +1,12 @@
 import type { Meta, StoryObj } from '@storybook/react';
+import style from '../index.css?raw';
 import { IllustrationHuman } from './illustrationHuman';
 
 const meta: Meta<typeof IllustrationHuman> = {
     title: 'Core/Components/Illustrations/IllustrationHuman',
     component: IllustrationHuman,
     parameters: {
+        style,
         design: {
             type: 'figma',
             url: 'https://www.figma.com/file/jfKRr1V9evJUp1uBeyP3Zz/v1.0.0?type=design&node-id=8874-14281&mode=dev',

src/core/components/illustrations/illustrationObject/illustrationObject.stories.tsx

@@ -1,10 +1,12 @@
 import type { Meta, StoryObj } from '@storybook/react';
+import style from '../index.css?raw';
 import { IllustrationObject } from './illustrationObject';
 
 const meta: Meta<typeof IllustrationObject> = {
     title: 'Core/Components/Illustrations/IllustrationObject',
     component: IllustrationObject,
     parameters: {
+        style,
         design: {
             type: 'figma',
             url: 'https://www.figma.com/file/jfKRr1V9evJUp1uBeyP3Zz/v1.0.0?type=design&node-id=8874-14443&mode=dev',

src/core/components/index.css

@@ -3,4 +3,4 @@
 @import "./dialogs";
 @import "./dropdown";
 @import "./forms";
-@import "./illustrations/";
+@import "./illustrations";

src/core/components/progress/progress.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { useEffect, useState } from 'react';
-import { Progress, type IProgressProps } from '.';
+import { Progress } from './progress';
+import type { IProgressProps } from './progress.api';
 
 const meta: Meta<typeof Progress> = {
     title: 'Core/Components/Progress',