feat(studio-components): enhance component library with improved documentation and optimizations

package.json

@@ -81,9 +81,10 @@
     "style-loader": "^3.3.1",
     "ts-loader": "^9.4.2",
     "turbo": "^1.8.3",
-    "typescript": "^5.1.6",
-    "webpack": "^5.88.0",
-    "webpack-cli": "^5.0.0"
+    "typescript": "^5.3.3",
+    "webpack": "^5.96.1",
+    "webpack-cli": "^5.1.4",
+    "terser-webpack-plugin": "^5.3.10"
   },
   "publishConfig": {
     "access": "public"

packages/studio-components/ai-coding-prompt.md

@@ -0,0 +1,45 @@
+# AI 辅助组件优化与开发协作 Prompt
+
+## 原始版本
+
+1. 代码结构：尽量避免长代码的出现，可以使用 function 或者 hooks 进行代码拆分。让整体代码清晰易懂。
+2. 性能优化：减少不必要的重渲染。只有涉及复杂逻辑计算，才使用 useMemo 优化，style 等计算请不要使用useMemo
+3. 状态管理：数据流请使用 useState，如果有多个状态，请合并成一个state，使用 setState 更新
+4. 类型推断：请确保 typescript 类型准确，避免 any 出现。
+5. 代码注释：对于复杂难维护的代码，请加上代码注释，如果注释是 /\*\* \*/ 要另起一行，// 则可以追加在代码后面。
+6. 组件文档：文档通过 dumi 运行的，中文文档是 index.md, 英文文档是 index.en-US.md，确保内容一致
+7. 样式优化：请不要使用 CSS 文件，尽量使用 Antd 提供的组件进行组合，要考虑 响应式设计，避免使用固定高度和宽度，要考虑主题色，使用token 进行样式定制
+8. 其他优化细节，你可以自己补充完善
+
+## 开发协作模式
+
+以下是我们与 AI 助手协作开发的有效模式：
+
+### 1. 渐进式优化
+
+- 一次专注于一个方面的优化
+- 每次更改后等待反馈
+- 根据反馈调整优化方向
+
+### 2. 代码审查流程
+
+- AI 提供优化建议
+- 开发者审查并给出反馈
+- AI 根据反馈进行调整
+- 最终确认后提交代码
+
+### 3. 文档同步
+
+- 代码更改与文档更新同步进行
+- 确保中英文文档一致
+- 提供详细的使用示例
+
+### 4. Git 工作流
+
+- 使用清晰的英文提交信息
+- 遵循 angular conventional commits 规范
+- 相关文件一起提交（组件代码、文档等）
+
+```
+
+```

packages/studio-components/src/CollapseCard/index.en-US.md

@@ -0,0 +1,87 @@
+---
+title: CollapseCard
+group:
+  title: Data Display
+  order: 1
+---
+
+# CollapseCard
+
+A collapsible card component that supports custom title, content and styles.
+
+## When To Use
+
+- When you need to display collapsible content areas
+- When you need to save page space while maintaining content accessibility
+- When you need to group related content
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import React from 'react';
+import { CollapseCard } from '@graphscope/studio-components';
+
+const Demo = () => {
+  return (
+    <CollapseCard title="Basic Usage">
+      <div>This is the card content</div>
+    </CollapseCard>
+  );
+};
+
+export default Demo;
+```
+
+### With Tooltip
+
+```tsx
+import React from 'react';
+import { CollapseCard } from '@graphscope/studio-components';
+
+const Demo = () => {
+  return (
+    <CollapseCard title="With Tooltip" tooltip="This is a tooltip">
+      <div>This is the card content</div>
+    </CollapseCard>
+  );
+};
+
+export default Demo;
+```
+
+### With Border
+
+```tsx
+import React from 'react';
+import { CollapseCard } from '@graphscope/studio-components';
+
+const Demo = () => {
+  return (
+    <CollapseCard title="With Border" bordered>
+      <div>This is the card content</div>
+    </CollapseCard>
+  );
+};
+
+export default Demo;
+```
+
+## API
+
+### CollapseCard
+
+| Property        | Description                           | Type                          | Default |
+| --------------- | ------------------------------------- | ----------------------------- | ------- |
+| bordered        | Whether to show border                | `boolean`                     | `false` |
+| ghost           | Whether to use transparent background | `boolean`                     | `true`  |
+| title           | Card title                            | `React.ReactNode`             | -       |
+| children        | Card content                          | `React.ReactNode`             | -       |
+| defaultCollapse | Whether to collapse by default        | `boolean`                     | `false` |
+| tooltip         | Tooltip content                       | `React.ReactNode`             | -       |
+| style           | Custom style                          | `React.CSSProperties`         | -       |
+| className       | Custom class name                     | `string`                      | -       |
+| onChange        | Callback when expand/collapse         | `(isActive: boolean) => void` | -       |
+
+</rewritten_file>

packages/studio-components/src/CollapseCard/index.md

@@ -0,0 +1,89 @@
+---
+title: CollapseCard 可折叠卡片
+group:
+  title: 数据展示
+  order: 1
+---
+
+# CollapseCard 可折叠卡片
+
+一个可折叠的卡片组件，支持自定义标题、内容和样式。
+
+## 何时使用
+
+- 需要展示可折叠的内容区域时
+- 需要节省页面空间，同时保持内容可访问性时
+- 需要分组展示相关内容时
+
+## 代码演示
+
+### 基础用法
+
+```tsx
+import React from 'react';
+import { CollapseCard } from '@graphscope/studio-components';
+
+const Demo = () => {
+  return (
+    <CollapseCard title="基础用法">
+      <div>这是卡片的内容</div>
+    </CollapseCard>
+  );
+};
+
+export default Demo;
+```
+
+### 带提示信息
+
+```tsx
+import React from 'react';
+import { CollapseCard } from '@graphscope/studio-components';
+
+const Demo = () => {
+  return (
+    <CollapseCard title="带提示信息" tooltip="这是一个提示信息">
+      <div>这是卡片的内容</div>
+    </CollapseCard>
+  );
+};
+
+export default Demo;
+```
+
+### 带边框
+
+```tsx
+import React from 'react';
+import { CollapseCard } from '@graphscope/studio-components';
+
+const Demo = () => {
+  return (
+    <CollapseCard title="带边框" bordered>
+      <div>这是卡片的内容</div>
+    </CollapseCard>
+  );
+};
+
+export default Demo;
+```
+
+## API
+
+### CollapseCard
+
+| 参数            | 说明              | 类型                          | 默认值  |
+| --------------- | ----------------- | ----------------------------- | ------- |
+| bordered        | 是否显示边框      | `boolean`                     | `false` |
+| ghost           | 是否透明背景      | `boolean`                     | `true`  |
+| title           | 卡片标题          | `React.ReactNode`             | -       |
+| children        | 卡片内容          | `React.ReactNode`             | -       |
+| defaultCollapse | 默认是否折叠      | `boolean`                     | `false` |
+| tooltip         | 提示信息          | `React.ReactNode`             | -       |
+| style           | 自定义样式        | `React.CSSProperties`         | -       |
+| className       | 自定义类名        | `string`                      | -       |
+| onChange        | 展开/收起时的回调 | `(isActive: boolean) => void` | -       |
+
+```
+
+```

packages/studio-components/src/CollapseCard/index.tsx

@@ -1,47 +1,132 @@
-import React, { useState } from 'react';
+import React, { useMemo, useCallback } from 'react';
 import { CaretRightOutlined, QuestionCircleOutlined } from '@ant-design/icons';
-import { Collapse, theme, Flex, Typography, Select, Space, Tooltip } from 'antd';
+import { Collapse, theme, Flex, Typography, Space, Tooltip } from 'antd';
+import type { CollapseProps } from 'antd';
 import { useDynamicStyle } from '../hooks/useDynamicStyle';
-interface IAdvancedSettingProps {
+
+/**
+ * CollapseCard 组件的属性接口
+ */
+export interface ICollapseCardProps {
+  /** 是否显示边框 */
   bordered?: boolean;
+  /** 是否透明背景 */
   ghost?: boolean;
+  /** 卡片标题 */
   title: React.ReactNode;
+  /** 卡片内容 */
   children: React.ReactNode;
+  /** 默认是否折叠 */
   defaultCollapse?: boolean;
+  /** 提示信息 */
   tooltip?: React.ReactNode;
+  /** 自定义样式 */
   style?: React.CSSProperties;
+  /** 自定义类名 */
+  className?: string;
+  /** 展开/收起时的回调 */
+  onChange?: (isActive: boolean) => void;
 }
 
-const CollapseCard: React.FunctionComponent<IAdvancedSettingProps> = props => {
-  const { bordered, children, title, defaultCollapse, tooltip, style = {} } = props;
+/**
+ * 可折叠卡片组件
+ * @description 一个可折叠的卡片组件，支持自定义标题、内容和样式
+ */
+const CollapseCard: React.FC<ICollapseCardProps> = ({
+  bordered = false,
+  ghost = true,
+  children,
+  title,
+  defaultCollapse = false,
+  tooltip,
+  style = {},
+  className = '',
+  onChange,
+}) => {
+  const { token } = theme.useToken();
   const id = 'Studio-Collapse-Card';
   const defaultActiveKey = defaultCollapse ? [] : [id];
+
+  // 使用 useMemo 优化样式计算
+  const cardStyle = useMemo(
+    () => ({
+      ...style,
+      backgroundColor: token.colorBgContainer,
+      borderRadius: token.borderRadiusLG,
+      boxShadow: bordered ? token.boxShadowTertiary : 'none',
+    }),
+    [style, token, bordered],
+  );
+
+  // 使用 useMemo 优化标题样式
+  const titleStyle = useMemo(
+    () => ({
+      margin: 0,
+      color: token.colorTextHeading,
+      fontSize: token.fontSizeLG,
+      fontWeight: token.fontWeightStrong,
+    }),
+    [token],
+  );
+
+  // 使用 useMemo 优化图标样式
+  const iconStyle = useMemo(
+    () => ({
+      transition: `transform ${token.motionDurationMid} ease`,
+      fontSize: token.fontSizeLG,
+    }),
+    [token],
+  );
+
+  // 动态样式注入
   useDynamicStyle(
-    `.${id} .ant-collapse-header {padding:0px !important;}
-    .${id} .ant-collapse-content-box {padding:12px 0px !important;}
+    `.${id} .ant-collapse-header {
+      padding: ${token.padding}px !important;
+      transition: all ${token.motionDurationMid} ease;
+    }
+    .${id} .ant-collapse-content-box {
+      padding: ${token.padding}px ${token.paddingLG}px !important;
+    }
     `,
     id,
   );
+
+  // 使用 useCallback 优化事件处理函数
+  const handleChange = useCallback(
+    (activeKeys: string | string[]) => {
+      const isActive = Array.isArray(activeKeys) ? activeKeys.includes(id) : activeKeys === id;
+      onChange?.(isActive);
+    },
+    [id, onChange],
+  );
+
+  // 使用 useCallback 优化展开图标渲染函数
+  const renderExpandIcon = useCallback(
+    (props: { isActive?: boolean }) => <CaretRightOutlined rotate={props.isActive ? 90 : 0} style={iconStyle} />,
+    [iconStyle],
+  );
+
   return (
     <Collapse
-      style={style}
-      className={id}
+      style={cardStyle}
+      className={`${id} ${className}`}
       bordered={bordered}
-      ghost
+      ghost={ghost}
       expandIconPosition="end"
       defaultActiveKey={defaultActiveKey}
-      expandIcon={({ isActive }) => <CaretRightOutlined rotate={isActive ? 90 : 0} />}
+      onChange={handleChange}
+      expandIcon={renderExpandIcon}
       items={[
         {
           key: id,
           label: (
             <Space>
-              <Typography.Title level={5} style={{ margin: '0px' }}>
+              <Typography.Title level={5} style={titleStyle}>
                 {title}
               </Typography.Title>
               {tooltip && (
                 <Tooltip title={tooltip}>
-                  <QuestionCircleOutlined />
+                  <QuestionCircleOutlined style={{ color: token.colorTextSecondary }} />
                 </Tooltip>
               )}
             </Space>