首页

.trellis/spec/frontend/component-guidelines.md

@@ -0,0 +1,121 @@
+# Component Guidelines
+
+> This document defines the standards for creating, naming, and organizing React components in this project.
+
+---
+
+## Overview
+
+We follow a strict functional component pattern with a focus on style isolation, type safety, and clean logic separation. Every component should be modular, self-contained, and well-documented.
+
+---
+
+## Naming Conventions
+
+### 1. File and Folder Naming
+- Use **kebab-case** (`xx-xx`) for component folders and files.
+- If the name is short, a single word is acceptable (e.g., `button.tsx`).
+- Example: `search-bar/reveal.tsx`, `user-list-item.tsx`.
+
+### 2. Function Naming
+- Use **PascalCase** (`XxXx`) for the component function name.
+- Example: `const SearchBar = () => { ... }`.
+
+---
+
+## Component Structure
+
+### 1. Functional Implementation
+All components must be written as **Functional Components**.
+
+### 2. Styling & Isolation
+- **File**: Create an `index.scss` file in the same directory as the component.
+- **Root Class**: The root `div` (or container) of the component must have a **unique class name**.
+- **Isolation**: Use **SCSS nesting** with the unique root class as the parent to ensure style isolation.
+
+```tsx
+// reveal.tsx
+import './index.scss';
+
+export const UserCard = () => {
+    return (
+        <div className="user-card-wrapper">
+            <h1 className="title">User Info</h1>
+        </div>
+    );
+};
+
+```
+```scss
+// index.scss
+.user-card-wrapper {
+    // Nested styles for isolation
+.title {
+        color: blue;
+    }
+}
+```
+
+---
+## Props and Type Safety
+- Props Constraint: Every component with props must define a type/interface to constrain them.
+- Type Location:
+  - Single Interface: If the component only needs one interface (usually the Props), define it at the top of the component file, directly below the import statements.
+  - Multiple Interfaces: If there are 2 or more interfaces/types, create a types.ts file in the same directory. Move all types, including the Props interface, into this file.
+## Logic and Data Management
+### 1. Static Data Extraction
+If a component requires a large amount of static data (e.g., "dead" data for rendering, initialization configs, or constants), do not define them inside the component file.
+- Move the data to a separate .ts file in the same directory.
+- Import it using: import { CONFIG_DATA } from "./config.ts".
+### 2.Commenting Standards
+**Every method, property, interface, and complex logic block MUST be documented.**
+
+- **Language Requirement**: All comments inside the code (JSDoc and internal) **MUST be written in Chinese**.
+- **Public API/Props/Interfaces**: Use JSDoc style `/** ... */` **mandatory** for every interface definition and **every single property** within that interface.
+- **Methods & Functions**: Every function (exported or internal) **must** have a `/** ... */` comment explaining its purpose, parameters, and return value.
+- **Internal Logic**: Use double-slash `//` for step-by-step explanations inside function bodies.
+```tsx
+/**
+ * 用户数据
+ */
+interface UserDetail {
+    id: number;
+    name: string;
+}
+
+interface UserCardProps {
+    /** 用户数据详情 */
+    data: UserDetail;
+}
+
+export const UserCard = ({ data }: UserCardProps) => {
+    /**
+     *点击用户中心
+     */
+    const handleProfileClick = () => {
+        // 检查用户id
+        if (data.id) {
+            console.log('Navigating...');
+        }
+    };
+
+    return <div className="user-card" onClick={handleProfileClick}>...</div>;
+}; 
+```
+
+## Summary Checklist
+
+- [ ] Folder/File name is kebab-case.
+
+- [ ] Function name is PascalCase.
+
+- [ ] Props are constrained by a type/interface.
+
+- [ ] Styles are in index.scss using a unique root class and nesting.
+
+- [ ] Large static data is moved to a separate .ts file.
+
+- [ ] Proper use of /** */ for definitions and // for logic.
+
+- [ ] Types are organized: in-file if single, types.ts if multiple.
+- [ ] **CRITICAL**: Every interface, property, and method must have **Chinese comments** using JSDoc (`/** */`) style.