# 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.