RustUI/CONVENTIONS.md

# Pika 开发约定

## 目录结构

- 组件目录使用 **kebab-case**：`display/avatar/`、`entry/tree-select/`
- 组件文件使用 **PascalCase**：`Avatar.tsx`
- 每个组件目录包含：`*.tsx`、`*.module.css`、`index.ts`、`*.test.tsx`

## 导出规范

- 组件 TSX 使用 **named export**
- barrel `index.ts` 统一 re-export 类型与组件

## Props 规范

- 接口中只声明**已实现**的 props，避免 AI 生成无效代码
- 暂未实现的 API 不要提前写入类型定义

## 样式规范

| 层级 | 前缀 | 示例 |
|------|------|------|
| 全局 token | `--nv-` | `--nv-color-primary` |
| 组件动态值 | `--_*` | `--_height`、`--_padding` |

- 优先使用 CSS Module + `var(--nv-*)`
- className 拼接使用 `cn()` from `shared/utils/classNames`

## 共享层

| 模块 | 用途 |
|------|------|
| `shared/hooks/useControllableState` | 受控/非受控状态 |
| `shared/hooks/usePikaContext` | ConfigProvider 上下文 |
| `shared/hooks/useClickOutside` | 下拉/浮层点击外部关闭 |
| `shared/overlay/useOverlay` | Tooltip/Popover 浮层逻辑 |
| `shared/utils/cn` | className 合并 |
| `shared/utils/getSemanticProps` | semantic DOM 样式 |

## 类型

- 统一使用 `PikaSize`、`PikaStatus`（`shared/types/common.ts`）
- Entry 组件通过 `DataEntrySize` / `DataEntryStatus` 别名引用

## 测试

- 每个主组件至少一个 `*.test.tsx`
- 测试交互行为，而非实现细节