docs: custom docs rendering instead of autodocs for API (#756)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Introduced new documentation pages for the Button and ButtonIcon
components in Storybook.
- Enhanced control configuration in Storybook for better customization
and usability.
- Added a new `AutoDoc` component for generating structured
documentation for UI components.

- **Bug Fixes**
- Updated import paths for several helper modules across multiple
documentation files to ensure correct resolution.

- **Refactor**
- Improved structure and organization of story definitions for the
Button and ButtonIcon components.
- Simplified Storybook configuration by removing unnecessary properties.

- **Chores**
	- Updated the package configuration to support ECMAScript modules.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

packages/api/.storybook/main.js

@@ -12,9 +12,6 @@ const config = {
 		name: "@storybook/react-vite",
 		options: {},
 	},
-	docs: {
-		// autodocs: true,
-	},
 	typescript: {
 		reactDocgen: "react-docgen-typescript",
 		reactDocgenTypescriptOptions: {

packages/api/.storybook/preview.js → packages/api/.storybook/preview.jsx

@@ -17,6 +17,7 @@ const preview = {
 				],
 			},
 		},
+
 		controls: {
 			// show description and default values in the individual stories (basic, etc.)
 			expanded: true,

packages/api/package.json

@@ -4,6 +4,7 @@
 	"license": "MIT",
 	"author": "Arno Versini",
 	"private": true,
+	"type": "module",
 	"scripts": {
 		"clean": "rimraf dist",
 		"dev": "nodemon",

packages/api/src/getting-started/Changelogs.mdx

@@ -1,7 +1,7 @@
 import { Meta, Markdown, Unstyled } from "@storybook/blocks";
 import { Card } from "@versini/ui-card";
 
-import Navigators from "./helpers/Navigators";
+import Navigators from "../helpers/Navigators";
 import ComponentsChangelog from "../../../ui-components/CHANGELOG.md?raw";
 import StylesChangelog from "../../../ui-styles/CHANGELOG.md?raw";
 import FormComponentsChangelog from "../../../ui-form/CHANGELOG.md?raw";

packages/api/src/getting-started/Configuration.mdx

@@ -1,8 +1,8 @@
 import { Meta } from "@storybook/blocks";
 
-import Navigators from "./helpers/Navigators";
-import Highlight from "./helpers/Highlight";
-import codeBlocks from "./helpers/codeBlocks";
+import Navigators from "../helpers/Navigators";
+import Highlight from "../helpers/Highlight";
+import codeBlocks from "../helpers/codeBlocks";
 
 <Meta title="Configuration" />
 

packages/api/src/getting-started/Installation.mdx

@@ -4,11 +4,11 @@ import { ButtonIcon } from "@versini/ui-button";
 import { IconNext, IconPrevious } from "@versini/ui-icons";
 import { Flexgrid, FlexgridItem } from "@versini/ui-system";
 
-import Highlight from "./helpers/Highlight";
-import Navigators from "./helpers/Navigators";
-import Table from "./helpers/Table";
-import codeBlocks from "./helpers/codeBlocks";
-import tableData from "./helpers/tableData";
+import Highlight from "../helpers/Highlight";
+import Navigators from "../helpers/Navigators";
+import Table from "../helpers/Table";
+import codeBlocks from "../helpers/codeBlocks";
+import tableData from "../helpers/tableData";
 
 <Meta title="Installation" />
 

packages/api/src/getting-started/Overview.mdx

@@ -5,7 +5,7 @@ import { Flexgrid, FlexgridItem } from "@versini/ui-system";
 import { linkTo } from "@storybook/addon-links";
 
 import Hero from "../stories/assets/hero-14.jpg";
-import Navigators from "./helpers/Navigators";
+import Navigators from "../helpers/Navigators";
 
 <Meta title="Overview" />
 

packages/api/src/getting-started/ReleaseTags.mdx

@@ -2,9 +2,7 @@ import { Meta } from "@storybook/blocks";
 import { Pill } from "@versini/ui-pill";
 import { Flexgrid, FlexgridItem } from "@versini/ui-system";
 
-import Navigators from "./helpers/Navigators";
-import Highlight from "./helpers/Highlight";
-import codeBlocks from "./helpers/codeBlocks";
+import Navigators from "../helpers/Navigators";
 
 <Meta title="Release Tags" />
 

packages/api/src/getting-started/Usage.mdx

@@ -2,9 +2,9 @@ import { Meta } from "@storybook/blocks";
 import { Button, ButtonIcon } from "@versini/ui-button";
 import { Card } from "@versini/ui-card";
 
-import Navigators from "./helpers/Navigators";
-import Highlight from "./helpers/Highlight";
-import codeBlocks from "./helpers/codeBlocks";
+import Navigators from "../helpers/Navigators";
+import Highlight from "../helpers/Highlight";
+import codeBlocks from "../helpers/codeBlocks";
 
 <Meta title="Usage" />
 

packages/api/src/helpers/AutoDoc.tsx

@@ -0,0 +1,57 @@
+import { Controls, Primary, Unstyled } from "@storybook/blocks";
+import { Pill } from "@versini/ui-pill";
+import { Flexgrid, FlexgridItem } from "@versini/ui-system";
+
+import Highlight from "./Highlight";
+
+interface AutoDocProps {
+	importName: string;
+
+	header?: string;
+	importPackage?: string;
+	stage?: "alpha" | "beta" | "stable";
+}
+
+export default ({ importName, importPackage, stage, header }: AutoDocProps) => {
+	const packageName = importPackage || `ui-${importName.toLowerCase()}`;
+	const titleHeader = header || importName;
+	let variant: "information" | "warning" | "success", releaseTag;
+	switch (stage) {
+		case "beta":
+			variant = "information";
+			releaseTag = "beta";
+			break;
+		case "stable":
+			variant = "success";
+			releaseTag = "stable";
+			break;
+		default:
+			variant = "warning";
+			releaseTag = "alpha";
+			break;
+	}
+	return (
+		<>
+			<Unstyled>
+				<div className="prose">
+					<Flexgrid alignVertical="center" className="mb-2" columnGap={3}>
+						<FlexgridItem>
+							<h1 className="m-0">{titleHeader}</h1>
+						</FlexgridItem>
+						<FlexgridItem>
+							<Pill label={releaseTag} variant={variant} className="mt-2" />
+						</FlexgridItem>
+					</Flexgrid>
+
+					<div className="prose">
+						<Highlight
+							codeBlock={`import { ${importName} } from "@versini/${packageName}";`}
+						/>
+					</div>
+				</div>
+			</Unstyled>
+			<Primary />
+			<Controls />
+		</>
+	);
+};

packages/api/src/getting-started/helpers/Highlight.tsx → packages/api/src/helpers/Highlight.tsx

@@ -7,7 +7,7 @@ await import("prismjs/components/prism-bash" as string);
 export default ({
 	codeBlock,
 	language = "jsx",
-}: { codeBlock: string; language: string }) => (
+}: { codeBlock: string; language?: string }) => (
 	<Unstyled>
 		<Highlight theme={themes.vsDark} code={codeBlock} language={language}>
 			{({ style, tokens, getLineProps, getTokenProps }) => (

packages/api/src/stories/Button.mdx

@@ -0,0 +1,7 @@
+import { Meta } from "@storybook/blocks";
+
+import AutoDoc from "../helpers/AutoDoc";
+import * as Stories from "./Button.stories";
+
+<Meta title="Components/Button" of={Stories} />
+<AutoDoc importName="Button" stage="stable" />

packages/api/src/stories/Button.stories.tsx

@@ -1,39 +1,53 @@
-import type { Meta } from "@storybook/react";
+import type { Meta, StoryObj } from "@storybook/react";
 import { fn } from "@storybook/test";
 
 import { Button } from "@versini/ui-button/src/components";
 
+type Story = StoryObj<typeof Button>;
+
 const meta: Meta<typeof Button> = {
 	parameters: {
 		layout: "centered",
+		docs: {
+			controls: { exclude: ["spacing"] },
+		},
 	},
 	title: "Components/Button",
+
 	component: Button,
-	args: { children: "Button", onClick: fn() },
+	args: { onClick: fn() },
 };
 
 export default meta;
-export const Basic = (args: React.ComponentProps<typeof Button>) => (
-	<div className="flex flex-wrap gap-2">
-		<Button {...args}>Button lorem ipsum</Button>
-		<Button {...args}>Button lorem ipsum dolor</Button>
-		<Button {...args}>Button lorem ipsum dolor sit amet</Button>
-	</div>
-);
 
-export const Truncate = (args: React.ComponentProps<typeof Button>) => {
-	args.className = "w-44 sm:w-52";
-	return (
-		<>
-			<p>For text to truncate, you need to limit the width of the buttons.</p>
-			<p>This can be done by using Tailwind width classes, for example</p>
-			<code>className={args.className}</code>
+export const Basic: Story = {
+	render: (args) => (
+		<div className="flex flex-wrap gap-2">
+			<Button {...args}>Button lorem ipsum</Button>
+			<Button {...args}>Button lorem ipsum dolor</Button>
+			<Button {...args}>Button lorem ipsum dolor sit amet</Button>
+		</div>
+	),
+};
 
-			<div className="flex flex-wrap gap-2">
-				<Button {...args}>Button lorem ipsum</Button>
-				<Button {...args}>Button lorem ipsum dolor</Button>
-				<Button {...args}>Button lorem ipsum dolor sit amet</Button>
-			</div>
-		</>
-	);
+export const Truncate: Story = {
+	args: { className: "w-44 sm:w-52" },
+	render: (args) => {
+		return (
+			<>
+				<div className="flex flex-wrap gap-2">
+					<Button {...args}>Button lorem ipsum</Button>
+					<Button {...args}>Button lorem ipsum dolor</Button>
+					<Button {...args}>Button lorem ipsum dolor sit amet</Button>
+				</div>
+				<div className="pt-4">
+					<p>
+						For text to truncate, you need to limit the width of the buttons.
+					</p>
+					<p>This can be done by using Tailwind width classes, for example</p>
+					<code>className={args.className}</code>
+				</div>
+			</>
+		);
+	},
 };

packages/api/src/stories/ButtonIcon.mdx

@@ -0,0 +1,7 @@
+import { Meta } from "@storybook/blocks";
+
+import AutoDoc from "../helpers/AutoDoc";
+import * as Stories from "./ButtonIcon.stories";
+
+<Meta title="Components/ButtonIcon" of={Stories} />
+<AutoDoc importName="ButtonIcon" importPackage="ui-button" stage="stable" />

packages/api/src/stories/ButtonIcon.stories.tsx

@@ -1,21 +1,29 @@
-import type { Meta } from "@storybook/react";
+import type { Meta, StoryObj } from "@storybook/react";
 import { fn } from "@storybook/test";
 
 import { ButtonIcon } from "@versini/ui-button/src/components";
 import { IconSettings } from "@versini/ui-icons";
 
+type Story = StoryObj<typeof ButtonIcon>;
+
 const meta: Meta<typeof ButtonIcon> = {
 	parameters: {
 		layout: "centered",
+		docs: {
+			controls: { exclude: ["spacing"] },
+		},
 	},
 	title: "Components/ButtonIcon",
+
 	component: ButtonIcon,
 	args: { onClick: fn() },
 };
 
 export default meta;
-export const Basic = (args: React.ComponentProps<typeof ButtonIcon>) => (
-	<ButtonIcon {...args}>
-		<IconSettings />
-	</ButtonIcon>
-);
+export const Basic: Story = {
+	render: (args) => (
+		<ButtonIcon {...args}>
+			<IconSettings />
+		</ButtonIcon>
+	),
+};