From b15edc74ee8a76d0d494f7099c6833bd7605c381 Mon Sep 17 00:00:00 2001 From: Arno V Date: Tue, 17 Dec 2024 17:44:37 -0500 Subject: [PATCH] docs: custom docs rendering instead of autodocs for API (#756) ## 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. --- packages/api/.storybook/main.js | 3 - .../.storybook/{preview.js => preview.jsx} | 1 + packages/api/package.json | 1 + .../api/src/getting-started/Changelogs.mdx | 2 +- .../api/src/getting-started/Configuration.mdx | 6 +- .../api/src/getting-started/Installation.mdx | 10 ++-- packages/api/src/getting-started/Overview.mdx | 2 +- .../api/src/getting-started/ReleaseTags.mdx | 4 +- packages/api/src/getting-started/Usage.mdx | 6 +- packages/api/src/helpers/AutoDoc.tsx | 57 ++++++++++++++++++ .../helpers/Highlight.tsx | 2 +- .../helpers/Navigators.tsx | 0 .../{getting-started => }/helpers/Table.tsx | 0 .../helpers/codeBlocks.ts | 0 .../helpers/tableData.ts | 0 packages/api/src/stories/Button.mdx | 7 +++ packages/api/src/stories/Button.stories.tsx | 60 ++++++++++++------- packages/api/src/stories/ButtonIcon.mdx | 7 +++ .../api/src/stories/ButtonIcon.stories.tsx | 20 +++++-- 19 files changed, 139 insertions(+), 49 deletions(-) rename packages/api/.storybook/{preview.js => preview.jsx} (99%) create mode 100644 packages/api/src/helpers/AutoDoc.tsx rename packages/api/src/{getting-started => }/helpers/Highlight.tsx (93%) rename packages/api/src/{getting-started => }/helpers/Navigators.tsx (100%) rename packages/api/src/{getting-started => }/helpers/Table.tsx (100%) rename packages/api/src/{getting-started => }/helpers/codeBlocks.ts (100%) rename packages/api/src/{getting-started => }/helpers/tableData.ts (100%) create mode 100644 packages/api/src/stories/Button.mdx create mode 100644 packages/api/src/stories/ButtonIcon.mdx diff --git a/packages/api/.storybook/main.js b/packages/api/.storybook/main.js index d901734e..be614a11 100644 --- a/packages/api/.storybook/main.js +++ b/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: { diff --git a/packages/api/.storybook/preview.js b/packages/api/.storybook/preview.jsx similarity index 99% rename from packages/api/.storybook/preview.js rename to packages/api/.storybook/preview.jsx index 0f079e7a..c0a53d7a 100644 --- a/packages/api/.storybook/preview.js +++ b/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, diff --git a/packages/api/package.json b/packages/api/package.json index 7139bc3d..07a8f5c9 100644 --- a/packages/api/package.json +++ b/packages/api/package.json @@ -4,6 +4,7 @@ "license": "MIT", "author": "Arno Versini", "private": true, + "type": "module", "scripts": { "clean": "rimraf dist", "dev": "nodemon", diff --git a/packages/api/src/getting-started/Changelogs.mdx b/packages/api/src/getting-started/Changelogs.mdx index 7a8de1f9..9936d2de 100644 --- a/packages/api/src/getting-started/Changelogs.mdx +++ b/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"; diff --git a/packages/api/src/getting-started/Configuration.mdx b/packages/api/src/getting-started/Configuration.mdx index 8caf7198..838a09b5 100644 --- a/packages/api/src/getting-started/Configuration.mdx +++ b/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"; diff --git a/packages/api/src/getting-started/Installation.mdx b/packages/api/src/getting-started/Installation.mdx index 6bb970d3..3176eb64 100644 --- a/packages/api/src/getting-started/Installation.mdx +++ b/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"; diff --git a/packages/api/src/getting-started/Overview.mdx b/packages/api/src/getting-started/Overview.mdx index 4d955f1b..245a503a 100644 --- a/packages/api/src/getting-started/Overview.mdx +++ b/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"; diff --git a/packages/api/src/getting-started/ReleaseTags.mdx b/packages/api/src/getting-started/ReleaseTags.mdx index 3faaf59b..b377ab2b 100644 --- a/packages/api/src/getting-started/ReleaseTags.mdx +++ b/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"; diff --git a/packages/api/src/getting-started/Usage.mdx b/packages/api/src/getting-started/Usage.mdx index bf5a4490..f2aae41b 100644 --- a/packages/api/src/getting-started/Usage.mdx +++ b/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"; diff --git a/packages/api/src/helpers/AutoDoc.tsx b/packages/api/src/helpers/AutoDoc.tsx new file mode 100644 index 00000000..4bc37f0a --- /dev/null +++ b/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 ( + <> + +
+ + +

{titleHeader}

+ + + + + + +
+ +
+
+ + + + + ); +}; diff --git a/packages/api/src/getting-started/helpers/Highlight.tsx b/packages/api/src/helpers/Highlight.tsx similarity index 93% rename from packages/api/src/getting-started/helpers/Highlight.tsx rename to packages/api/src/helpers/Highlight.tsx index 0ea6f7bd..c82d419e 100644 --- a/packages/api/src/getting-started/helpers/Highlight.tsx +++ b/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 }) => ( {({ style, tokens, getLineProps, getTokenProps }) => ( diff --git a/packages/api/src/getting-started/helpers/Navigators.tsx b/packages/api/src/helpers/Navigators.tsx similarity index 100% rename from packages/api/src/getting-started/helpers/Navigators.tsx rename to packages/api/src/helpers/Navigators.tsx diff --git a/packages/api/src/getting-started/helpers/Table.tsx b/packages/api/src/helpers/Table.tsx similarity index 100% rename from packages/api/src/getting-started/helpers/Table.tsx rename to packages/api/src/helpers/Table.tsx diff --git a/packages/api/src/getting-started/helpers/codeBlocks.ts b/packages/api/src/helpers/codeBlocks.ts similarity index 100% rename from packages/api/src/getting-started/helpers/codeBlocks.ts rename to packages/api/src/helpers/codeBlocks.ts diff --git a/packages/api/src/getting-started/helpers/tableData.ts b/packages/api/src/helpers/tableData.ts similarity index 100% rename from packages/api/src/getting-started/helpers/tableData.ts rename to packages/api/src/helpers/tableData.ts diff --git a/packages/api/src/stories/Button.mdx b/packages/api/src/stories/Button.mdx new file mode 100644 index 00000000..a07f4e5c --- /dev/null +++ b/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"; + + + diff --git a/packages/api/src/stories/Button.stories.tsx b/packages/api/src/stories/Button.stories.tsx index 647d8464..7d121ed4 100644 --- a/packages/api/src/stories/Button.stories.tsx +++ b/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; + const meta: Meta = { 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) => ( -
- - - -
-); -export const Truncate = (args: React.ComponentProps) => { - args.className = "w-44 sm:w-52"; - return ( - <> -

For text to truncate, you need to limit the width of the buttons.

-

This can be done by using Tailwind width classes, for example

- className={args.className} +export const Basic: Story = { + render: (args) => ( +
+ + + +
+ ), +}; -
- - - -
- - ); +export const Truncate: Story = { + args: { className: "w-44 sm:w-52" }, + render: (args) => { + return ( + <> +
+ + + +
+
+

+ For text to truncate, you need to limit the width of the buttons. +

+

This can be done by using Tailwind width classes, for example

+ className={args.className} +
+ + ); + }, }; diff --git a/packages/api/src/stories/ButtonIcon.mdx b/packages/api/src/stories/ButtonIcon.mdx new file mode 100644 index 00000000..ac38bf43 --- /dev/null +++ b/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"; + + + diff --git a/packages/api/src/stories/ButtonIcon.stories.tsx b/packages/api/src/stories/ButtonIcon.stories.tsx index 262af01d..c236a3a4 100644 --- a/packages/api/src/stories/ButtonIcon.stories.tsx +++ b/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; + const meta: Meta = { parameters: { layout: "centered", + docs: { + controls: { exclude: ["spacing"] }, + }, }, title: "Components/ButtonIcon", + component: ButtonIcon, args: { onClick: fn() }, }; export default meta; -export const Basic = (args: React.ComponentProps) => ( - - - -); +export const Basic: Story = { + render: (args) => ( + + + + ), +};