@blocklet/component-studio-cli 0.4.134

package/templates/add/tools/cursor-rules/.cursor/rules/index-tsx.mdc

@@ -0,0 +1,192 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# index.tsx 文件说明
+
+## 概述
+`index.tsx` 是 Component Studio 中组件的实现文件，负责组件的渲染逻辑和交互行为。它与 `@metadata.json` 紧密配合，共同定义了一个完整的可配置组件。
+
+## 工作原理
+`index.tsx` 与 `@metadata.json` 通过属性映射相互关联：
+- `@metadata.json` 定义组件的可配置属性及其元数据
+- `index.tsx` 使用这些属性进行组件渲染和行为控制
+
+
+## 关键部分
+
+### BlockProps 接口
+```typescript
+export interface BlockProps {
+  /** @description id: gs1rn5jmxfvpxptx | type: string | visible: true */
+  title?: string;
+  /** @description id: 9ajrz12ik7esfk1z | type: string | visible: true */
+  description?: string;
+  // ...其他属性
+}
+```
+
+这个接口定义了组件的属性类型，每个属性的注释包含：
+- id 对应的 `@metadata.json` 中的 id
+- key 属性类型
+- visible 可见性
+- 需要保持 `@description` 符号，这是 jsdom 在 ts 类型处理的时候，会被解析到 zod 上 `z.xxx().describe()`
+
+#### BlockProps 最佳实践
+- 所有属性默认应设为可选（使用 `?` 标记），以避免类型错误
+- 保持注释格式的统一性，不要删除或修改 `@description` 内容
+- 为复杂类型（如嵌套对象）定义独立的接口或类型，增强代码可读性
+- 当添加新属性时，确保同步添加对应的注释，包含完整的 metadata 信息
+- 使用语义化的属性名称，与 `@metadata.json` 中的 `key` 保持一致
+
+### 组件实现
+```typescript
+export default function BlockComponent({
+  title = 'Hello World',
+  logo,
+  description,
+  // ...其他属性和默认值
+}: BlockProps) {
+  // 组件实现逻辑
+}
+```
+
+组件函数接收 `BlockProps` 定义的属性，并设置与 `@metadata.json` 中匹配的默认值。
+
+#### 组件实现最佳实践
+- 为常用属性设置默认值，确保组件在无参数时也能正常渲染
+- 默认值应与 `@metadata.json` 中的 `defaultValue` 保持一致
+- 使用解构赋值接收属性，简化代码结构
+- 对于复杂的逻辑处理，考虑使用 React hooks 拆分功能
+- 实现响应式设计，确保组件在不同尺寸下都能正常显示
+- 添加适当的类型守卫检查复杂属性，防止运行时错误
+- 考虑性能优化，避免不必要的重渲染（如使用 useMemo, useCallback）
+
+
+### EditComponent
+```typescript
+export const EditComponent: React.FC<BlockProps & { onChange?: (value: BlockProps) => void }> = ({
+  onChange,
+  ...props
+}) => {
+  // 自定义编辑界面实现
+}
+```
+
+这是组件的特殊编辑接口，提供了编辑器中的自定义控件，增强属性编辑体验。
+
+#### EditComponent 最佳实践
+- 当在 EditComponent 中为某个属性提供自定义控件时，应在 `@metadata.json` 中将该属性的 `visible` 设置为 `false`
+- 使用 onChange 回调时确保传递完整的 props 对象，避免丢失其他属性值
+- 为复杂编辑界面提供直观的 UI 分组和标签
+- 考虑添加表单验证，确保用户输入的值有效
+- 提供即时反馈，让用户知道其操作已被接收
+- 保持编辑控件的样式与 Component Studio 整体风格一致
+- 并不是所有的 Component 都需要这个自定义空间，尤其是 `type: 'url' ｜ ‘yml’` 情况下，不建议替换
+
+### 样式
+组件样式在 Component Studio 中通常通过内联样式对象实现，便于与属性值动态绑定。
+
+```typescript
+// 样式对象分离示例
+const cardStyle = {
+  padding: '1.5rem',
+  borderRadius: '12px',
+  background: 'rgba(255, 255, 255, 0.7)',
+  boxShadow: '0 10px 30px rgba(0, 0, 0, 0.08)'
+};
+
+return <div style={cardStyle}>...</div>;
+```
+
+#### 样式最佳实践
+- **内联样式优先** - 使用内联样式（style对象）便于属性动态控制
+- **样式对象分离** - 对于复杂组件，将样式对象提取到组件函数外，提高可读性
+- **动态样式函数** - 创建函数生成依赖于属性的样式
+  ```typescript
+  const getTitleStyle = (color) => ({
+    color,
+    fontSize: '1.5rem',
+    fontWeight: 600
+  });
+  ```
+- **响应式设计** - 使用条件样式或媒体查询实现适配不同设备
+- **过渡动画** - 添加 transition 属性提升用户体验
+- **交互增强** - 为互动元素添加悬停状态
+- **性能优化** - 使用 useMemo 缓存样式对象，避免不必要的重新计算
+  ```typescript
+  const buttonStyle = useMemo(() => ({
+    background: isActive ? activeColor : inactiveColor
+  }), [isActive, activeColor, inactiveColor]);
+  ```
+- **避免硬编码** - 使用属性传入的样式值，避免硬编码颜色等固定值
+- **主题变量** - 考虑使用 CSS 变量实现主题定制
+- **使用语义化命名** - 如 containerStyle, headerStyle 等增强可读性
+
+## 与 @metadata.json 的关系
+
+### 属性映射
+每个在 `@metadata.json` 中定义的属性，在 `index.tsx` 中都有对应映射：
+
+| @metadata.json | index.tsx |
+|----------------|------------|
+| `properties.[id].data.key` | BlockProps 中的属性名 |
+| `properties.[id].data.type` | TypeScript 类型定义 |
+| `properties.[id].data.locales.[lang].defaultValue` | 组件中的默认值 |
+
+### 类型对应关系
+- `string` → `string`
+- `number` → `number`
+- `boolean` → `boolean`
+- `url` → 自定义对象类型
+- `json` → 自定义对象类型
+- `array` → 数组类型
+- `component` → `any` 或特定组件类型
+
+### 嵌套属性处理
+`@metadata.json` 中的 `subProperties` 在 `index.tsx` 中通过嵌套接口定义映射：
+
+```typescript
+json?: {
+  /** @description id: gpy89bsxc6ovvlsp | type: string | visible: true */
+  foo?: string;
+  /** @description id: 1j34jdhdptp2xm5e | type: string | visible: true */
+  bar?: string;
+};
+```
+
+## 通用最佳实践
+以下是适用于整个组件开发过程的通用最佳实践：
+
+1. **文件同步** - 修改 `@metadata.json` 或 `index.tsx` 时，确保两者保持同步
+2. **版本控制** - 为重要更改添加清晰的注释和版本标记
+3. **组件设计** - 遵循单一职责原则，每个组件只做一件事
+4. **性能考虑** - 针对大型组件或频繁更新的场景进行性能优化
+5. **可维护性** - 使用清晰的命名和注释，便于团队成员理解
+
+## 编辑组件示例
+对于需要特殊编辑体验的属性，可以通过 `EditComponent` 提供自定义编辑界面：
+
+```typescript
+export const EditComponent: React.FC<BlockProps & { onChange?: (value: BlockProps) => void }> = ({
+  onChange,
+  ...props
+}) => {
+  return (
+    <div>
+      <label>自定义编辑器</label>
+      <input 
+        value={props.someProperty || ''} 
+        onChange={(e) => onChange?.({...props, someProperty: e.target.value})}
+      />
+    </div>
+  );
+}
+```
+
+## 组件属性如何生效
+1. 用户在编辑器中配置属性值
+2. 值存储到 `@metadata.json` 对应属性的 `defaultValue`
+3. 运行时，这些值作为 props 传递给 `index.tsx` 中的组件
+4. 组件根据接收到的 props 和默认值渲染界面

package/templates/add/tools/cursor-rules/@template.json

@@ -0,0 +1,4 @@
+{
+  "name": "Cursor Rules",
+  "description": "The cursor rules to improve coding experience in cursor editor"
+}

package/templates/init/0-basic/@template.json

@@ -0,0 +1,4 @@
+{
+  "name": "Basic Project",
+  "description": "A basic component studio project, with a simple `HelloWorld` component example"
+}

package/templates/init/0-basic/README.md

@@ -0,0 +1,30 @@
+# Basic Component Studio Project
+
+This is a basic component studio project created with Component Studio.
+
+## Project Structure
+
+```
+{your-project-name}/
+  ├── src/
+  │   ├── HelloWorld             # A basic component example
+  │   │   ├── index.tsx          # Main entry point
+  │   │   └── @metadata.json     # Component metadata
+  │   └── {your-component-name}  # Your component name
+  |     └── index.tsx            # Main entry point
+  ├──  package.json              # Project dependencies and scripts
+  ├──  .gitignore                # Git ignore
+  └──  README.md                 # README
+```
+
+## Getting Started
+
+Start development server:
+
+```bash
+pnpm run dev
+```
+
+## License
+
+MIT

package/templates/init/0-basic/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "basic-component-studio-project",
+  "version": "0.1.0",
+  "description": "A basic component studio project",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "start": "component-studio dev",
+    "dev": "component-studio dev",
+    "update:deps": "npx -y taze -r -n '/arcblock|ocap|abtnode|blocklet|did-connect|did-comment|nedb/' -w -f && pnpm install && pnpm run deduplicate",
+    "deduplicate": "pnpm dedupe"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
+  },
+  "license": "MIT"
+}

package/templates/init/0-basic/src/HelloWorld/@metadata.json

@@ -0,0 +1,433 @@
+{
+  "id": "KEHGy3vdflE8JGrV",
+  "createdAt": "2025-03-20T16:01:56.655Z",
+  "updatedAt": "2025-03-21T01:24:04.008Z",
+  "name": "HelloWorld",
+  "description": "",
+  "properties": {
+    "gs1rn5jmxfvpxptx": {
+      "index": 0,
+      "data": {
+        "id": "gs1rn5jmxfvpxptx",
+        "key": "title",
+        "type": "string",
+        "visible": true,
+        "locales": {
+          "zh": {
+            "name": "标题",
+            "defaultValue": "Hello World"
+          },
+          "en": {
+            "name": "Title",
+            "defaultValue": "Hello World"
+          }
+        }
+      }
+    },
+    "9ajrz12ik7esfk1z": {
+      "index": 1,
+      "data": {
+        "id": "9ajrz12ik7esfk1z",
+        "key": "description",
+        "type": "string",
+        "visible": true,
+        "locales": {
+          "zh": {
+            "name": "描述",
+            "defaultValue": "这是你的创意实验室，在这里可以:\n- 设计和构建各类强大组件\n- 将创意转化为可复用代码\n- 打造专属于您的组件库\n释放你的开发潜能，开始创作吧！"
+          },
+          "en": {
+            "name": "Description",
+            "defaultValue": "This is your creative lab, where you can:\n- Design and build powerful components\n- Transform ideas into reusable code\n- Create your own component library\nUnleash your development potential and start creating!"
+          }
+        }
+      }
+    },
+    "3ckcfvf6b7zyskk8": {
+      "index": 2,
+      "data": {
+        "id": "3ckcfvf6b7zyskk8",
+        "key": "logo",
+        "type": "url",
+        "visible": true,
+        "locales": {
+          "zh": {
+            "defaultValue": {
+              "url": "/.well-known/service/blocklet/logo?imageFilter=convert&f=png&h=80",
+              "mediaKitUrl": "/.well-known/service/blocklet/logo?imageFilter=convert&f=png&h=80"
+            },
+            "name": "Logo"
+          },
+          "en": {
+            "defaultValue": {
+              "url": "/.well-known/service/blocklet/logo?imageFilter=convert&f=png&h=80",
+              "mediaKitUrl": "/.well-known/service/blocklet/logo?imageFilter=convert&f=png&h=80"
+            },
+            "name": "Logo"
+          }
+        },
+        "subProperties": {
+          "ML-CDw7LvtlhM_cl": {
+            "index": 0,
+            "data": {
+              "id": "ML-CDw7LvtlhM_cl",
+              "key": "url",
+              "locales": {
+                "en": {
+                  "name": "url"
+                },
+                "zh": {
+                  "name": "url"
+                }
+              }
+            }
+          },
+          "K-HYgPHtAsmO_mer": {
+            "index": 1,
+            "data": {
+              "id": "K-HYgPHtAsmO_mer",
+              "key": "mediaKitUrl",
+              "locales": {
+                "en": {
+                  "name": "mediaKitUrl"
+                },
+                "zh": {
+                  "name": "mediaKitUrl"
+                }
+              }
+            }
+          },
+          "evequmAWgWEWZLex": {
+            "index": 2,
+            "data": {
+              "id": "evequmAWgWEWZLex",
+              "key": "width",
+              "locales": {
+                "en": {
+                  "name": "width"
+                },
+                "zh": {
+                  "name": "width"
+                }
+              }
+            }
+          },
+          "poeAwflRHJeUmfLa": {
+            "index": 3,
+            "data": {
+              "id": "poeAwflRHJeUmfLa",
+              "key": "height",
+              "locales": {
+                "en": {
+                  "name": "height"
+                },
+                "zh": {
+                  "name": "height"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "x3lqht8ikble1itx": {
+      "index": 3,
+      "data": {
+        "id": "x3lqht8ikble1itx",
+        "key": "copyright",
+        "type": "string",
+        "visible": false,
+        "locales": {
+          "zh": {
+            "name": "版权信息",
+            "defaultValue": "由 Component Studio 提供支持"
+          },
+          "en": {
+            "name": "Copyright",
+            "defaultValue": "Powered by Component Studio"
+          }
+        }
+      }
+    },
+    "q0ezdj81v0m14y5m": {
+      "index": 4,
+      "data": {
+        "id": "q0ezdj81v0m14y5m",
+        "key": "number",
+        "type": "number",
+        "visible": true,
+        "locales": {
+          "zh": {
+            "name": "整数",
+            "defaultValue": 42
+          },
+          "en": {
+            "name": "Integer",
+            "defaultValue": 42
+          }
+        }
+      }
+    },
+    "bl0rimfebwbencoj": {
+      "index": 5,
+      "data": {
+        "id": "bl0rimfebwbencoj",
+        "key": "decimal",
+        "type": "decimal",
+        "visible": true,
+        "locales": {
+          "zh": {
+            "name": "小数",
+            "defaultValue": 3.14
+          },
+          "en": {
+            "name": "Decimal",
+            "defaultValue": 3.14
+          }
+        }
+      }
+    },
+    "gioetxz8d13jabz6": {
+      "index": 6,
+      "data": {
+        "id": "gioetxz8d13jabz6",
+        "key": "showCopyright",
+        "type": "boolean",
+        "visible": true,
+        "locales": {
+          "zh": {
+            "name": "是否展示 Copyright",
+            "defaultValue": true
+          },
+          "en": {
+            "name": "Show Description",
+            "defaultValue": true
+          }
+        }
+      }
+    },
+    "yi1oj4rq1eziup1d": {
+      "index": 7,
+      "data": {
+        "id": "yi1oj4rq1eziup1d",
+        "key": "titleColor",
+        "type": "color",
+        "visible": true,
+        "locales": {
+          "zh": {
+            "defaultValue": "rgb(45, 36, 45)",
+            "name": "标题颜色"
+          },
+          "en": {
+            "defaultValue": "rgb(44, 39, 44)",
+            "name": "Title Color"
+          }
+        }
+      }
+    },
+    "4f49q5uidkcp5ak4": {
+      "index": 8,
+      "data": {
+        "id": "4f49q5uidkcp5ak4",
+        "key": "json",
+        "type": "json",
+        "visible": true,
+        "locales": {
+          "zh": {
+            "name": "JSON 数据",
+            "defaultValue": {
+              "foo": "-",
+              "bar": "-"
+            }
+          },
+          "en": {
+            "name": "JSON Data",
+            "defaultValue": {
+              "foo": "foo",
+              "bar": "bar"
+            }
+          }
+        },
+        "subProperties": {
+          "gpy89bsxc6ovvlsp": {
+            "index": 0,
+            "data": {
+              "id": "gpy89bsxc6ovvlsp",
+              "key": "foo",
+              "type": "string",
+              "visible": true,
+              "locales": {
+                "zh": {
+                  "name": "名称",
+                  "defaultValue": "-"
+                },
+                "en": {
+                  "name": "Foo",
+                  "defaultValue": "foo"
+                }
+              }
+            }
+          },
+          "1j34jdhdptp2xm5e": {
+            "index": 1,
+            "data": {
+              "id": "1j34jdhdptp2xm5e",
+              "key": "bar",
+              "type": "string",
+              "visible": true,
+              "locales": {
+                "zh": {
+                  "name": "属性",
+                  "defaultValue": "-"
+                },
+                "en": {
+                  "name": "Bar",
+                  "defaultValue": "bar"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "lbclpm6mxrp10w2k": {
+      "index": 9,
+      "data": {
+        "id": "lbclpm6mxrp10w2k",
+        "key": "array",
+        "type": "array",
+        "visible": true,
+        "locales": {
+          "zh": {
+            "name": "数组数据",
+            "defaultValue": [
+              {
+                "name": "示例用户",
+                "bio": "这是一个示例用户"
+              }
+            ]
+          },
+          "en": {
+            "name": "Array Data",
+            "defaultValue": [
+              {
+                "name": "Example User",
+                "bio": "This is an example user"
+              }
+            ]
+          }
+        },
+        "subProperties": {
+          "1c5vl2p9cn9ryvgh": {
+            "index": 0,
+            "data": {
+              "id": "1c5vl2p9cn9ryvgh",
+              "key": "name",
+              "type": "string",
+              "visible": true,
+              "locales": {
+                "zh": {
+                  "name": "姓名",
+                  "defaultValue": ""
+                },
+                "en": {
+                  "name": "Name",
+                  "defaultValue": ""
+                }
+              }
+            }
+          },
+          "c5whnccwzqqzaa0w": {
+            "index": 1,
+            "data": {
+              "id": "c5whnccwzqqzaa0w",
+              "key": "bio",
+              "type": "multiline",
+              "visible": true,
+              "locales": {
+                "zh": {
+                  "name": "简介",
+                  "defaultValue": ""
+                },
+                "en": {
+                  "name": "Bio",
+                  "defaultValue": ""
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "s0tund4p07bzizgv": {
+      "index": 10,
+      "data": {
+        "id": "s0tund4p07bzizgv",
+        "key": "yaml",
+        "type": "yaml",
+        "visible": true,
+        "locales": {
+          "zh": {
+            "name": "YAML 配置",
+            "defaultValue": ""
+          },
+          "en": {
+            "name": "YAML Configuration",
+            "defaultValue": "ya: ya\nml: ml\n"
+          }
+        },
+        "subProperties": {
+          "1q8tsreh4k2mhbgs": {
+            "index": 0,
+            "data": {
+              "id": "1q8tsreh4k2mhbgs",
+              "key": "ya",
+              "type": "string",
+              "visible": true,
+              "locales": {
+                "en": {
+                  "name": "Ya",
+                  "defaultValue": "ya"
+                }
+              }
+            }
+          },
+          "09w8sncxwrj6tldi": {
+            "index": 1,
+            "data": {
+              "id": "09w8sncxwrj6tldi",
+              "key": "ml",
+              "type": "string",
+              "visible": true,
+              "locales": {
+                "en": {
+                  "name": "Ml",
+                  "defaultValue": "ml"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "8e7g6c61pxcy0q4w": {
+      "index": 11,
+      "data": {
+        "id": "8e7g6c61pxcy0q4w",
+        "key": "children",
+        "type": "component",
+        "visible": true,
+        "locales": {
+          "zh": {
+            "name": "子组件",
+            "defaultValue": {}
+          },
+          "en": {
+            "name": "Children Components",
+            "defaultValue": {}
+          }
+        }
+      }
+    }
+  }
+}