refactor: clean up Storybook stories and improve prop documentation

Author: shijistar

.storybook/locales/index.ts

@@ -17,16 +17,16 @@ storyI18n.init({
   resources,
 });
 
-export const t: i18n['t'] = ((...args) => {
+export const storyT: i18n['t'] = ((...args) => {
   return storyI18n.t(...args);
 }) as i18n['t'];
 
 export const useStoryT = () => {
   const context = useContext(ReactEasyContext);
   const lang = context.lang;
 
-  // eslint-disable-next-line @tiny-codes/react-hooks/exhaustive-deps
-  return useMemo(() => ((...args: unknown) => t(...args)) as typeof t, [lang]);
+  // eslint-disable-next-line @tiny-codes/react-hooks/exhaustive-deps, @typescript-eslint/no-explicit-any
+  return useMemo(() => ((...args: any) => storyT(...args)) as typeof storyT, [lang]);
 };
 
 export default storyI18n;

.storybook/preview.tsx

@@ -1,5 +1,5 @@
 import { type ComponentType, type PropsWithChildren, useMemo } from 'react';
-import { DocsContainer, type DocsContainerProps } from '@storybook/addon-docs/blocks';
+import { type Control, DocsContainer, type DocsContainerProps } from '@storybook/addon-docs/blocks';
 import type { Preview, ReactRenderer } from '@storybook/react-vite';
 import { App as AntdApp, ConfigProvider as AntdConfigProvider, theme } from 'antd';
 import enUS from 'antd/es/locale/en_US';
@@ -8,6 +8,7 @@ import type { StoryContext, StoryContextForEnhancers } from 'storybook/internal/
 import { themes } from 'storybook/theming';
 import ConfigProvider from '../src/components/ConfigProvider';
 import storyI18n from './locales';
+import { inferControlFromDocgenType, standardizeJsDocDefaultValue } from './utils/jsdoc';
 import './preview.css';
 
 const isPreferDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
@@ -97,33 +98,37 @@ function stripExampleBlock(input = '') {
   );
 }
 
+/** Enhances the argTypes of a story based on JSDoc comments. */
 function jsdocArgTypesEnhancer(context: StoryContextForEnhancers) {
   const component = context.component;
   const docProps = component?.__docgenInfo?.props;
   if (!docProps) return context.argTypes;
 
-  const next = { ...(context.argTypes || {}) };
+  const newArgTypes = { ...(context.argTypes || {}) };
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  Object.entries(docProps).forEach(([propName, propInfo]: [string, any]) => {
-    next[propName] = {
-      ...(next[propName] || {}),
-      // control: ?
+  Object.entries(docProps).forEach(([name, docProp]: [string, any]) => {
+    const inferred = inferControlFromDocgenType(docProp?.type);
+    const argType = newArgTypes[name];
+
+    newArgTypes[name] = {
+      ...argType,
+      control: { type: argType?.control ?? inferred.control } as Control,
+      options: argType?.options ?? inferred.options,
       // The handwritten description will not be overwritten.
-      description: next[propName]?.description ?? propInfo?.description ?? '',
+      description: argType?.description ?? docProp?.description ?? '',
       table: {
-        ...(next[propName]?.table || {}),
-        type: next[propName]?.table?.type ?? {
-          summary: propInfo?.type?.name || '',
+        ...(argType?.table || {}),
+        defaultValue: {
+          ...docProp?.defaultValue,
+          summary:
+            docProp?.defaultValue?.summary ?? standardizeJsDocDefaultValue(String(docProp.defaultValue?.value ?? '-')),
         },
-        defaultValue:
-          next[propName]?.table?.defaultValue ??
-          (propInfo?.defaultValue?.value ? { summary: String(propInfo.defaultValue.value) } : undefined),
       },
     };
   });
-  console.log(next);
-  return next;
+  console.log('newArgTypes', newArgTypes);
+  return newArgTypes;
 }
 
 export default preview;

.storybook/stories/BreakLines.stories.tsx

@@ -11,52 +11,11 @@ const meta: Meta<typeof BreakLines> = {
     tagName: 'div',
     className: '',
   } satisfies Partial<BreakLinesProps>,
-  argTypes: {
-    //     value: {
-    //       control: 'text',
-    //       description: `- **EN:** Text content
-    // - **CN:** 文本内容`,
-    //       table: {
-    //         defaultValue: { summary: '第一行\\n第二行\\n第三行（demo）' },
-    //       },
-    //     },
-    //     enabled: {
-    //       control: 'boolean',
-    //       description: `- **EN:** Whether the line break conversion is enabled.
-    // - **CN:** 是否启用换行转换。`,
-    //       table: {
-    //         defaultValue: { summary: 'true' },
-    //       },
-    //     },
-    //     EOL: {
-    //       control: 'text',
-    //       description: `- **EN:** The end-of-line character to use for splitting lines.
-    // - **CN:** 用于分割行的行结束字符。`,
-    //       table: {
-    //         defaultValue: { summary: '\\n' },
-    //       },
-    //     },
-    //     tagName: {
-    //       control: 'select',
-    //       options: [false, 'span', 'div', 'i', 'pre'],
-    //       description: `- **EN:** The HTML tag to use for rendering the content.
-    // - **CN:** 用于渲染内容的 HTML 标签。`,
-    //       table: {
-    //         defaultValue: { summary: 'false（组件默认） / div（demo）' },
-    //       },
-    //     },
-    //     className: {
-    //       control: 'text',
-    //       description: `- **EN:** The CSS class name of the dom node, if \`tagName\` is set to false, this property is invalid.
-    // - **CN:** dom 节点的 css 类名，如果 \`tagName\` 设置为 false，则此属性无效。`,
-    //       table: {
-    //         defaultValue: { summary: '""（demo）' },
-    //       },
-    //     },
-  },
+  argTypes: {},
 };
+type BreakLinesStoryArgs = BreakLinesProps;
 
 export default meta;
-type Story = StoryObj<typeof BreakLines>;
+type Story = StoryObj<BreakLinesStoryArgs>;
 
 export const Playground: Story = {};

.storybook/stories/ColumnSetting.stories.tsx

@@ -3,8 +3,8 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Table } from 'antd';
 import type { ColumnsType } from 'antd/es/table';
 import ColumnSetting from '../../src/components/ColumnSetting';
-import type { ColumnSettingItem } from '../../src/components/ColumnSetting';
-import { useStoryT } from '../locales';
+import type { ColumnSettingItem, ColumnSettingProps } from '../../src/components/ColumnSetting';
+import { storyT, useStoryT } from '../locales';
 
 interface User {
   id: number;
@@ -13,11 +13,7 @@ interface User {
   city: string;
   role: string;
 }
-
-interface ColumnSettingStoryArgs {
-  storageKey: string;
-  useStorage: boolean;
-}
+type ColumnSettingStoryArgs = ColumnSettingProps;
 
 const buildBaseColumns = (t: ReturnType<typeof useStoryT>): ColumnSettingItem<User>[] => [
   { title: 'ID', dataIndex: 'id', key: 'id', width: 80, disabled: true },
@@ -29,24 +25,12 @@ const buildBaseColumns = (t: ReturnType<typeof useStoryT>): ColumnSettingItem<Us
 
 const meta: Meta<ColumnSettingStoryArgs> = {
   title: 'Components/ColumnSetting',
+  component: ColumnSetting,
   args: {
-    useStorage: false,
     storageKey: 'storybook:column-setting',
+    columns: buildBaseColumns(storyT),
   },
-  argTypes: {
-    useStorage: {
-      control: 'boolean',
-      description: `- **EN:** Whether to enable local storage persistence in this demo.
-- **CN:** 当前示例中是否启用本地存储持久化。`,
-      table: { defaultValue: { summary: 'false（demo）' } },
-    },
-    storageKey: {
-      control: 'text',
-      description: `- **EN:** Local storage key for persisting column settings.
-- **CN:** 用于持久化列设置的本地存储键。`,
-      table: { defaultValue: { summary: 'storybook:column-setting（demo）' } },
-    },
-  },
+  argTypes: {},
 };
 
 export default meta;
@@ -87,7 +71,7 @@ export const Playground: Story = {
         <div style={{ marginBottom: 12, display: 'flex', justifyContent: 'flex-end' }}>
           <ColumnSetting<ColumnSettingItem<User>>
             columns={columns}
-            storageKey={args.useStorage ? args.storageKey : undefined}
+            storageKey={args.storageKey}
             onChange={setColumns}
             triggerProps={{ children: t('storybook.stories.ColumnSetting.trigger') }}
           />

.storybook/stories/ConfigProvider.stories.tsx

@@ -1,42 +1,21 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { App as AntdApp, Space, Typography } from 'antd';
-import ConfigProvider from '../../src/components/ConfigProvider';
+import ConfigProvider, { type ConfigProviderProps } from '../../src/components/ConfigProvider';
 import ConfirmAction from '../../src/components/ConfirmAction';
 
-interface ConfigProviderStoryArgs {
-  lang: 'en' | 'zh-CN';
-  defaultTitle: string;
-  defaultContent: string;
-}
+type ConfigProviderStoryArgs = ConfigProviderProps;
 
 const meta: Meta<ConfigProviderStoryArgs> = {
   title: 'Components/ConfigProvider',
+  component: ConfigProvider,
   args: {
     lang: 'zh-CN',
-    defaultTitle: '全局确认标题',
-    defaultContent: '这是由 ConfigProvider 注入的全局默认内容。',
-  },
-  argTypes: {
-    lang: {
-      control: 'radio',
-      options: ['en', 'zh-CN'],
-      description: `- **EN:** Language of the component for global configuration.
-- **CN:** 组件语言（全局配置）。`,
-      table: { defaultValue: { summary: 'en（组件默认） / zh-CN（demo）' } },
-    },
-    defaultTitle: {
-      control: 'text',
-      description: `- **EN:** Global default title for \`ConfirmAction\` in this demo.
-- **CN:** 当前示例中 \`ConfirmAction\` 的全局默认标题。`,
-      table: { defaultValue: { summary: '全局确认标题（demo）' } },
-    },
-    defaultContent: {
-      control: 'text',
-      description: `- **EN:** Global default content for \`ConfirmAction\` in this demo.
-- **CN:** 当前示例中 \`ConfirmAction\` 的全局默认内容。`,
-      table: { defaultValue: { summary: '这是由 ConfigProvider 注入的全局默认内容。（demo）' } },
+    ConfirmAction: {
+      title: '全局确认标题',
+      content: '这是由 ConfigProvider 注入的全局默认内容。',
     },
   },
+  argTypes: {},
 };
 
 export default meta;
@@ -45,13 +24,7 @@ type Story = StoryObj<ConfigProviderStoryArgs>;
 export const Playground: Story = {
   render: (args: ConfigProviderStoryArgs) => (
     <AntdApp>
-      <ConfigProvider
-        lang={args.lang}
-        ConfirmAction={{
-          title: args.defaultTitle,
-          content: args.defaultContent,
-        }}
-      >
+      <ConfigProvider {...args}>
         <Space direction="vertical" size={12}>
           <Typography.Text>下面按钮未传 title/content，将使用全局默认值：</Typography.Text>
           <ConfirmAction.Button onOk={async () => Promise.resolve()}>打开确认框</ConfirmAction.Button>

.storybook/stories/ConfirmAction.stories.tsx

@@ -1,24 +1,23 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { App as AntdApp, message } from 'antd';
+import type { ButtonProps, SwitchProps } from 'antd';
+import { App as AntdApp } from 'antd';
+import type { LinkProps } from 'antd/es/typography/Link';
+import type { ConfirmActionProps } from '../../src/components/ConfirmAction';
 import ConfirmAction from '../../src/components/ConfirmAction';
 
-type TriggerType = 'button' | 'switch' | 'link';
+type TriggerType = 'Button' | 'Switch' | 'Link';
 
-interface ConfirmActionStoryArgs {
+type ConfirmActionStoryArgs = ConfirmActionProps<object, never> & {
   triggerType: TriggerType;
-  triggerText: string;
-  title: string;
-  content: string;
-  danger: boolean;
-  okText: string;
-  cancelText: string;
-}
+};
 
 const meta: Meta<ConfirmActionStoryArgs> = {
   title: 'Components/ConfirmAction',
   args: {
-    triggerType: 'button',
-    triggerText: '执行操作',
+    triggerType: 'Button',
+    triggerProps: {
+      children: '执行操作',
+    },
     title: '确认执行该操作？',
     content: '这是一个可交互的 ConfirmAction demo。',
     danger: false,
@@ -28,46 +27,10 @@ const meta: Meta<ConfirmActionStoryArgs> = {
   argTypes: {
     triggerType: {
       control: 'radio',
-      options: ['button', 'switch', 'link'],
+      options: ['Button', 'Switch', 'Link'],
       description: `- **EN:** Demo-only option to switch trigger component type.
 - **CN:** 示例专用：切换触发器组件类型。`,
-      table: { defaultValue: { summary: 'button（demo）' } },
-    },
-    triggerText: {
-      control: 'text',
-      description: `- **EN:** Custom trigger content.
-- **CN:** 自定义触发器内容。`,
-      table: { defaultValue: { summary: '执行操作（demo）' } },
-    },
-    title: {
-      control: 'text',
-      description: `- **EN:** Confirm box title.
-- **CN:** 确认框标题。`,
-      table: { defaultValue: { summary: '确认执行该操作？（demo）' } },
-    },
-    content: {
-      control: 'text',
-      description: `- **EN:** Confirm box content text.
-- **CN:** 确认框内容文本。`,
-      table: { defaultValue: { summary: '这是一个可交互的 ConfirmAction demo。（demo）' } },
-    },
-    danger: {
-      control: 'boolean',
-      description: `- **EN:** Whether to display in red danger mode.
-- **CN:** 是否显示为红色危险模式。`,
-      table: { defaultValue: { summary: 'false' } },
-    },
-    okText: {
-      control: 'text',
-      description: `- **EN:** Confirm button text.
-- **CN:** 确认按钮文本。`,
-      table: { defaultValue: { summary: '确认（demo）' } },
-    },
-    cancelText: {
-      control: 'text',
-      description: `- **EN:** Cancel button text.
-- **CN:** 取消按钮文本。`,
-      table: { defaultValue: { summary: '取消（demo）' } },
+      table: { defaultValue: { summary: '"Button"' } },
     },
   },
 };
@@ -77,36 +40,27 @@ type Story = StoryObj<ConfirmActionStoryArgs>;
 
 export const Playground: Story = {
   render: (args: ConfirmActionStoryArgs) => {
-    const commonProps = {
-      title: args.title,
-      content: args.content,
-      danger: args.danger,
-      okText: args.okText,
-      cancelText: args.cancelText,
-      onOk: async () => {
-        message.success('操作成功');
-      },
-    };
+    const { triggerType, ...props } = args;
 
-    if (args.triggerType === 'switch') {
+    if (triggerType === 'Switch') {
       return (
         <AntdApp>
-          <ConfirmAction.Switch {...commonProps} />
+          <ConfirmAction.Switch {...(props as ConfirmActionProps<SwitchProps, 'onChange'>)} />
         </AntdApp>
       );
     }
 
-    if (args.triggerType === 'link') {
+    if (triggerType === 'Link') {
       return (
         <AntdApp>
-          <ConfirmAction.Link {...commonProps}>{args.triggerText}</ConfirmAction.Link>
+          <ConfirmAction.Link {...(props as ConfirmActionProps<LinkProps, 'onClick'>)} />
         </AntdApp>
       );
     }
 
     return (
       <AntdApp>
-        <ConfirmAction.Button {...commonProps}>{args.triggerText}</ConfirmAction.Button>
+        <ConfirmAction.Button {...(props as ConfirmActionProps<ButtonProps, 'onClick'>)} />
       </AntdApp>
     );
   },