feat: component docs, utils modularization & antd v6 storybook migration

.storybook/preview-head.html

@@ -0,0 +1,6 @@
+<style>
+  #storybook-docs > .sbdocs-wrapper {
+    padding-top: 3rem;
+    padding-bottom: 3rem;
+  }
+</style>

.storybook/preview.tsx

@@ -1,29 +1,21 @@
 import type { ComponentType, PropsWithChildren } from 'react';
 import { useMemo, useState } from 'react';
 import type { Control, DocsContainerProps } from '@storybook/addon-docs/blocks';
-import {
-  Controls,
-  DocsContainer,
-  Markdown,
-  Primary,
-  Stories,
-  Subtitle,
-  Title,
-  useOf,
-} from '@storybook/addon-docs/blocks';
+import { Controls, DocsContainer, Markdown, Primary, Subtitle, Title, useOf } from '@storybook/addon-docs/blocks';
 import type { Preview, ReactRenderer } from '@storybook/react-vite';
-import { App as AntdApp, ConfigProvider as AntdConfigProvider, theme as antThemes } from 'antd';
-import enUS from 'antd/es/locale/en_US';
-import zhCN from 'antd/es/locale/zh_CN';
 import { FORCE_RE_RENDER } from 'storybook/internal/core-events';
 import type { StoryContext, StoryContextForEnhancers } from 'storybook/internal/csf';
 import type { ResolvedModuleExportFromType } from 'storybook/internal/types';
 import { addons, useStoryContext } from 'storybook/preview-api';
 import { themes } from 'storybook/theming';
+import { App as AntdApp, ConfigProvider as AntdConfigProvider, theme as antThemes } from 'antd';
+import enUS from 'antd/es/locale/en_US';
+import zhCN from 'antd/es/locale/zh_CN';
 import ConfigProvider from '../src/components/ConfigProvider';
 import { useRefValue } from '../src/hooks';
 import type { Langs } from '../src/locales';
 import storyI18n, { storyT } from './locales';
+import { pickLangDoc } from './utils/doc';
 import { getGlobalValueFromUrl } from './utils/global';
 import { inferControlFromDocgenType, standardizeJsDocDefaultValue } from './utils/jsdoc';
 
@@ -35,7 +27,7 @@ const isPreferDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
 
 const preview: Preview = {
   initialGlobals: {
-    lang: 'en-US',
+    lang: '',
     backgrounds: {
       value: themeFromUrl ?? (isPreferDark ? 'dark' : 'light'),
       grid: false,
@@ -85,23 +77,27 @@ const preview: Preview = {
       extractComponentDescription: (
         component: ComponentType & {
           __docgenInfo?: { description?: string };
-        }
+        },
       ) => {
         const raw = component?.__docgenInfo?.description ?? '';
         let result = stripExampleBlock(raw);
-        result = removeOtherLang(result);
+        result = pickLangDoc(result);
         return result;
       },
-      page: () => (
-        <>
-          <Title />
-          <Subtitle />
-          <CustomComponentDescription />
-          <Primary />
-          <Controls />
-          <Stories />
-        </>
-      ),
+      page: () => {
+        const langFromUrl = getGlobalValueFromUrl('lang');
+        return (
+          <>
+            <Title />
+            <Subtitle />
+            <CustomComponentDescription />
+            <h2>{langFromUrl === 'zh-CN' ? '演示' : 'Demo'}</h2>
+            <Primary />
+            <Controls />
+            {/* <Stories /> */}
+          </>
+        );
+      },
     },
   },
   tags: ['autodocs'],
@@ -117,15 +113,15 @@ const preview: Preview = {
       const isDark = theme === 'dark' || (!theme && isPreferDark);
       // Reload the page if the theme changes.
       useMemo(() => {
-        if (themeFromGlobal !== prevTheme) {
+        if (themeFromGlobal && themeFromGlobal !== prevTheme) {
           setPrevTheme(themeFromGlobal);
           (window.top ?? window.parent ?? window).location.reload();
         }
       }, [themeFromGlobal, prevTheme]);
 
       // Reload the page if the language changes.
       useMemo(() => {
-        if (storyI18n.language !== lang) {
+        if (lang && storyI18n.language !== lang) {
           storyI18n.changeLanguage(lang).then(() => {
             if (viewModeRef.current === 'docs') {
               addons.getChannel().emit(FORCE_RE_RENDER);
@@ -153,74 +149,6 @@ const preview: Preview = {
   argTypesEnhancers: [jsdocArgTypesEnhancer],
 };
 
-function removeOtherLang(input = '') {
-  const langFromUrl = getGlobalValueFromUrl('lang');
-  const currentLang = langFromUrl === 'zh-CN' ? 'zh-CN' : 'en-US';
-  return keepCurrentLangContent(input, currentLang);
-}
-
-function keepCurrentLangContent(input = '', lang: Langs = 'en-US') {
-  const targetLang = lang === 'zh-CN' ? 'CN' : 'EN';
-
-  // Compatible with JSDoc original text (with *) and plain text extracted by docgen
-  const lines = input.split(/\r?\n/).map((line) => line.replace(/^\s*\*\s?/, ''));
-
-  const result: string[] = [];
-  let blockLang: 'EN' | 'CN' | null = null;
-  let blockLines: string[] = [];
-
-  // Language block: - **EN:** xxx or - **CN:** xxx
-  const langHeaderReg = /^-\s*\*\*(EN|CN):\*\*\s*(.*)$/;
-  // JSDoc 标签：@param @returns ...
-  const jsdocTagReg = /^@\w+/;
-
-  const flushBlock = () => {
-    if (blockLang === targetLang) {
-      result.push(...blockLines);
-    }
-    blockLang = null;
-    blockLines = [];
-  };
-
-  for (const line of lines) {
-    const headerMatch = line.match(langHeaderReg);
-
-    if (headerMatch) {
-      if (blockLang) {
-        flushBlock();
-      }
-      const [, langFlag, firstContent = ''] = headerMatch;
-      blockLang = langFlag as 'EN' | 'CN';
-      blockLines = firstContent ? [firstContent] : [];
-      continue;
-    }
-
-    if (blockLang) {
-      // Encounter @param/@returns indicating the end of the language block, tag content should be retained
-      if (jsdocTagReg.test(line)) {
-        flushBlock();
-        result.push(line);
-      } else {
-        blockLines.push(line);
-      }
-      continue;
-    }
-
-    // Non-internationalized content remains unchanged.
-    result.push(line);
-  }
-
-  if (blockLang) {
-    flushBlock();
-  }
-
-  // 压缩多余空行
-  return result
-    .join('\n')
-    .replace(/\n{3,}/g, '\n\n')
-    .trim();
-}
-
 function stripExampleBlock(input = '') {
   return (
     input
@@ -248,7 +176,7 @@ function jsdocArgTypesEnhancer(context: StoryContextForEnhancers) {
       control: { type: argType?.control ?? inferred.control } as Control,
       options: argType?.options ?? inferred.options,
       // The handwritten description will not be overwritten.
-      description: argType?.description ?? docProp?.description ?? '',
+      description: pickLangDoc(argType?.description ?? docProp?.description ?? ''),
       table: {
         ...(argType?.table || {}),
         defaultValue: {
@@ -285,7 +213,7 @@ function CustomComponentDescription() {
 function processDescription(content: string | undefined) {
   const raw = content ?? '';
   let result = stripExampleBlock(raw);
-  result = removeOtherLang(result);
+  result = pickLangDoc(result);
   return result;
 }
 

.storybook/stories/components/BreakLines/api-doc.en-US.md

@@ -0,0 +1,13 @@
+## API
+
+| Prop        | Description                                                                                | Type                                                        | Default |
+| ----------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | ------- |
+| `value`     | Text content to render                                                                     | `string \| undefined`                                       | -       |
+| `enabled`   | Whether line-break conversion is enabled                                                   | `boolean`                                                   | `true`  |
+| `EOL`       | The end-of-line character used to split lines                                              | `string`                                                    | `'\n'`  |
+| `tagName`   | HTML tag used to render the content. When `false`, content is rendered as a React fragment | `false \| 'span' \| 'div' \| 'i' \| 'pre' \| (string & {})` | `false` |
+| `className` | CSS class of the DOM node. Ignored when `tagName` is `false`                               | `string`                                                    | -       |
+
+## Notes
+
+When `tagName` is `false` (default), the content is returned as a fragment with `<br/>` between segments, so it can be embedded inline.

.storybook/stories/components/BreakLines/api-doc.zh-CN.md

@@ -0,0 +1,13 @@
+## API
+
+| Prop        | Description                                                                                | Type                                                        | Default |
+| ----------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | ------- |
+| `value`     | Text content to render                                                                     | `string \| undefined`                                       | -       |
+| `enabled`   | Whether line-break conversion is enabled                                                   | `boolean`                                                   | `true`  |
+| `EOL`       | The end-of-line character used to split lines                                              | `string`                                                    | `'\n'`  |
+| `tagName`   | HTML tag used to render the content. When `false`, content is rendered as a React fragment | `false \| 'span' \| 'div' \| 'i' \| 'pre' \| (string & {})` | `false` |
+| `className` | CSS class of the DOM node. Ignored when `tagName` is `false`                               | `string`                                                    | -       |
+
+## 说明
+
+`tagName` 为 `false`（默认）时，内容以 React fragment 返回，段间用 `<br/>`，可内联嵌入其它文本中。

.storybook/stories/components/BreakLines/index.stories.tsx

@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import BreakLines, { type BreakLinesProps } from '../../../../src/components/BreakLines';
+import storyI18n, { storyT } from '../../../locales';
+import apiDocEN from './api-doc.en-US.md?raw';
+import apiDocCN from './api-doc.zh-CN.md?raw';
+import introduceEN from './introduce.en-US.md?raw';
+import introduceCN from './introduce.zh-CN.md?raw';
+
+const meta: Meta<typeof BreakLines> = {
+  title: 'Components/BreakLines',
+  component: BreakLines,
+  parameters: {
+    docs: {
+      description: {
+        component: storyI18n.language === 'zh-CN' ? `${introduceCN}\n${apiDocCN}` : `${introduceEN}\n${apiDocEN}`,
+      },
+    },
+  },
+  args: {
+    value: storyT('storybook.stories.BreakLines.args.value'),
+    enabled: true,
+    EOL: '\n',
+    tagName: 'div',
+    className: '',
+  },
+  argTypes: {},
+};
+type BreakLinesStoryArgs = BreakLinesProps;
+
+export default meta;
+type Story = StoryObj<BreakLinesStoryArgs>;
+
+export const Playground: Story = {};

.storybook/stories/components/BreakLines/introduce.en-US.md

@@ -0,0 +1,29 @@
+Renders plain text with preserved line breaks by splitting with a configurable EOL marker and output tag.
+
+## When to use
+
+Display backend-provided text that contains `\n` (or another EOL marker) and you want it shown as multiple visual lines instead of a single wrapped paragraph. This is common for multi-line addresses, log snippets, poetry, or any string whose line structure carries meaning.
+
+## Key features
+
+- **Line break preservation** — splits the input by a configurable end-of-line character and renders each segment on its own line, joined by `<br />`.
+- **Pluggable output tag** — when `tagName` is set, the whole content is wrapped in that HTML element (e.g. `div`, `span`, `pre`); when `tagName` is `false` (default) it renders a React fragment so it can be embedded inline.
+- **Toggle at runtime** — the `enabled` prop turns conversion on/off without changing the source value.
+- **Custom EOL** — `EOL` lets you split on any delimiter (e.g. `\r\n`, `|`, a custom token), not just `\n`.
+
+## Sample code
+
+```tsx
+import { BreakLines } from '@tiny-codes/react-easy';
+
+export function Demo() {
+  const text = 'Line 1\nLine 2\nLine 3';
+  return <BreakLines value={text} tagName="div" />;
+}
+```
+
+## Usage notes
+
+- When `tagName` is `false` (default), the result is a fragment with `<br />` between segments, so it can be placed inside running text without introducing an extra DOM node. `className` is ignored in this mode.
+- `EOL` only affects splitting; it is not stripped from the rendered output — each segment keeps its own content.
+- Long lines are still subject to the parent container's normal text wrapping; `BreakLines` does not force horizontal overflow.

.storybook/stories/components/BreakLines/introduce.zh-CN.md

@@ -0,0 +1,29 @@
+按指定换行符拆分文本并保留换行展示，可自定义输出标签。
+
+## 适用场景
+
+展示后端返回、包含 `\n`（或其它换行符）的文本，希望按原换行分段显示，而不是被当作一整段自动折行。常见于多行地址、日志片段、诗文，或任何"换行本身具有语义"的字符串。
+
+## 核心特性
+
+- **保留换行** —— 按可配置的换行符拆分输入，并将每一段渲染为独立的一行，段间以 `<br />` 连接。
+- **可选输出标签** —— 设置 `tagName` 后，整段内容会被包裹到该 HTML 元素中（如 `div`、`span`、`pre`）；为 `false`（默认）时以 React 片段渲染，可内联嵌入。
+- **运行时可切换** —— `enabled` 属性可在不修改源数据的情况下开关换行转换。
+- **自定义换行符** —— `EOL` 支持任意分隔符（如 `\r\n`、`|`、自定义标记），不局限于 `\n`。
+
+## 示例代码
+
+```tsx
+import { BreakLines } from '@tiny-codes/react-easy';
+
+export function Demo() {
+  const text = '第一行\n第二行\n第三行';
+  return <BreakLines value={text} tagName="div" />;
+}
+```
+
+## 使用注意
+
+- 当 `tagName` 为 `false`（默认）时，结果为片段且段间使用 `<br />`，可放入行内文本而不会额外产生 DOM 节点；此模式下 `className` 不生效。
+- `EOL` 仅影响拆分，不会被从渲染结果中剔除——每段保留自身内容。
+- 长行仍受父容器正常文本折行约束，`BreakLines` 不会强制横向溢出。

.storybook/stories/components/ColumnSetting/api-doc.en-US.md

@@ -0,0 +1,27 @@
+## API
+
+| Prop                | Description                                                                         | Type                                                   | Default |
+| ------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------ | ------- |
+| `columns`           | Column definitions including visibility, ordering, and `disabled` state             | `ColumnSettingItem<T>[]`                               | -       |
+| `onChange`          | Called when the selected columns change; returns columns with `hidden` updated      | `(nextColumns: T[]) => void`                           | -       |
+| `storageKey`        | Local storage key for persisting column settings. If unset, persistence is disabled | `string`                                               | -       |
+| `renderColumnTitle` | Custom renderer for column titles                                                   | `(col: ColumnSettingItem, index: number) => ReactNode` | -       |
+| `triggerProps`      | Props for the button that opens the dropdown                                        | `ButtonProps`                                          | -       |
+| `dropdownProps`     | Props for the dropdown component                                                    | `DropdownProps`                                        | -       |
+| `popupProps`        | Props for the dropdown popup container                                              | `React.HTMLAttributes<HTMLDivElement>`                 | -       |
+| `checkAllProps`     | Props for the "Check All" button                                                    | `ButtonProps`                                          | -       |
+| `resetProps`        | Props for the "Reset" button                                                        | `ButtonProps`                                          | -       |
+| `prefixCls`         | Custom CSS class prefix                                                             | `string`                                               | -       |
+
+### `ColumnSettingItem`
+
+Extends Ant Design `ColumnType<T>` and adds:
+
+| Field      | Description                                 | Type      |
+| ---------- | ------------------------------------------- | --------- |
+| `disabled` | Disable toggling visibility for this column | `boolean` |
+
+## Notes
+
+At least one column always remains visible — the last visible column's checkbox is disabled to prevent hiding everything.
+When `storageKey` is set, the selection is read from `localStorage` on mount and written back on every change.