@xyhp915/slack-base-ui 0.0.1

package/AGENTS.md

@@ -0,0 +1,331 @@
+# AGENTS.md - AI 协作指南
+
+> 本文档为 AI 助手提供项目上下文和协作指导
+
+## 📋 项目概览
+
+**项目名称**: Slack Base UI  
+**项目类型**: React UI 组件库 + 演示应用  
+**核心技术**: React 19 + TypeScript + Base UI + TailwindCSS + Vite  
+**设计风格**: Slack Design System
+
+## 🎯 项目目标
+
+1. 使用 Base UI 无样式组件库构建完整的 Slack 风格 UI 组件
+2. 提供可重用、可访问、类型安全的组件库
+3. 展示如何用这些组件构建真实的应用（Slack 克隆）
+4. 支持亮色/暗色主题切换
+
+## 🏗️ 架构设计
+
+### 技术栈
+
+```
+┌─────────────────────────────────────┐
+│         React 19 + TypeScript       │
+├─────────────────────────────────────┤
+│    @base-ui/react (无样式组件)      │
+├─────────────────────────────────────┤
+│  TailwindCSS + CSS Variables (样式) │
+├─────────────────────────────────────┤
+│      React Router (路由管理)        │
+├─────────────────────────────────────┤
+│          Vite (构建工具)            │
+└─────────────────────────────────────┘
+```
+
+### 目录结构
+
+```
+src/
+├── components/           # 核心组件库（可重用）
+│   ├── Button.tsx       # 按钮 - 4 种变体，3 种尺寸
+│   ├── Avatar.tsx       # 头像 - 5 种尺寸，状态指示器
+│   ├── Badge.tsx        # 徽章 - 数字/圆点，2 种风格
+│   ├── Input.tsx        # 输入框 - 标签、错误提示
+│   ├── IconButton.tsx   # 图标按钮 - 紧凑型
+│   ├── Tooltip.tsx      # 工具提示 - 基于 Base UI
+│   └── Dialog.tsx       # 对话框 - 模态对话框，4 种尺寸
+│
+├── pages/               # 展示页面
+│   ├── Dashboard.tsx    # 首页 - 项目介绍和导航
+│   └── ComponentShowcase.tsx  # 组件展示页
+│
+├── examples/            # 完整应用示例
+│   └── slack-clone/     # Slack 克隆
+│       ├── SlackApp.tsx
+│       ├── components/  # Message, Composer, ChannelHeader, UserProfile
+│       └── layout/      # Layout (包含 Sidebar)
+│
+├── context/
+│   └── ThemeContext.tsx # 主题切换 (light/dark)
+│
+├── App.tsx              # 路由配置
+├── main.tsx             # 入口
+└── index.css            # 全局样式和 CSS 变量定义
+```
+
+## 🎨 设计系统
+
+### CSS 变量命名规范
+
+所有颜色和样式变量定义在 `src/index.css`：
+
+```css
+/* 品牌色 */
+--slack-aubergine: #3F0E40;  /* Slack 紫色 */
+--slack-blue: #1164A3;       /* Slack 蓝色 */
+--slack-green: #007a5a;      /* Slack 绿色 */
+--slack-red: #E01E5A;        /* Slack 红色 */
+
+/* 语义化颜色 */
+--bg-primary: #ffffff;       /* 主背景 */
+--bg-secondary: #f8f8f8;     /* 次背景 */
+--bg-hover: #f2f2f2;         /* 悬停背景 */
+--text-primary: #1d1c1d;     /* 主文本 */
+--text-secondary: #616061;   /* 次文本 */
+--text-muted: #868686;       /* 弱化文本 */
+--border-light: #dddddd;     /* 边框 */
+```
+
+### 组件设计原则
+
+1. **基于 Base UI**：所有组件优先使用 Base UI 提供的无样式组件
+2. **样式定制**：使用 TailwindCSS 类和 CSS 变量实现 Slack 风格
+3. **类型安全**：完整的 TypeScript 类型定义
+4. **可访问性**：继承 Base UI 的 ARIA 支持
+5. **主题感知**：所有颜色使用 CSS 变量，自动支持主题切换
+
+### 组件模式
+
+典型组件结构：
+
+```tsx
+import { ComponentName as BaseComponent } from '@base-ui/react';
+import clsx from 'clsx';
+import React from 'react';
+
+export interface ComponentProps extends BaseComponentProps {
+  variant?: 'primary' | 'secondary';
+  size?: 'sm' | 'md' | 'lg';
+  // 自定义 props
+}
+
+export const Component = React.forwardRef<HTMLElement, ComponentProps>(
+  ({ className, variant = 'primary', size = 'md', ...props }, ref) => {
+    // 样式逻辑
+    const baseStyles = '...';
+    const variants = { primary: '...', secondary: '...' };
+    const sizes = { sm: '...', md: '...', lg: '...' };
+    
+    return (
+      <BaseComponent
+        ref={ref}
+        className={clsx(baseStyles, variants[variant], sizes[size], className)}
+        {...props}
+      />
+    );
+  }
+);
+```
+
+## 🔧 开发指南
+
+### 添加新组件
+
+1. **确定需求**：明确组件的功能和 API
+2. **选择基础**：查找 Base UI 是否有对应的无样式组件
+3. **创建文件**：在 `src/components/` 创建 `ComponentName.tsx`
+4. **实现组件**：
+   - 导入 Base UI 组件（如果有）
+   - 定义 TypeScript 接口
+   - 使用 `React.forwardRef`
+   - 实现变体和尺寸逻辑
+   - 使用 CSS 变量实现 Slack 风格
+5. **添加展示**：在 `ComponentShowcase.tsx` 中添加使用示例
+6. **测试主题**：确保在亮色和暗色主题下都正常显示
+
+### 修改现有组件
+
+1. **阅读代码**：理解组件当前实现
+2. **保持一致性**：遵循现有的命名和样式模式
+3. **测试影响**：检查 `ComponentShowcase.tsx` 和 `slack-clone` 中的使用
+4. **更新类型**：如果修改了 props，更新 TypeScript 接口
+
+### 样式开发
+
+- **优先使用 CSS 变量**：`var(--bg-primary)` 而不是硬编码颜色
+- **TailwindCSS 类**：用于布局和常用样式
+- **响应式**：使用 Tailwind 的响应式前缀 `md:`、`lg:` 等
+- **状态变体**：`hover:`、`focus:`、`active:`、`disabled:` 等
+
+### 主题切换
+
+主题通过 `ThemeContext` 管理：
+
+```tsx
+const { theme, toggleTheme } = useTheme();
+// theme: 'light' | 'dark'
+// toggleTheme: () => void
+```
+
+切换主题时，会在 `<html>` 元素上添加/移除 `.dark` 类，CSS 变量自动切换。
+
+## 📦 依赖管理
+
+### 核心依赖
+
+- `@base-ui/react` - 无样式组件库，提供行为和可访问性
+- `react` / `react-dom` - UI 框架
+- `react-router-dom` - 页面路由
+- `tailwindcss` - CSS 工具类
+- `lucide-react` - 图标库
+- `clsx` - 类名拼接
+- `tailwind-merge` - Tailwind 类名合并
+
+### 何时添加新依赖
+
+1. **优先使用现有工具**：Base UI、Tailwind、Lucide 已覆盖大部分需求
+2. **评估必要性**：新功能是否真的需要外部库
+3. **考虑包大小**：避免引入过大的依赖
+4. **类型支持**：优先选择有 TypeScript 类型的库
+
+## 🎯 常见任务
+
+### 任务：添加新组件（例如 Select 下拉选择）
+
+```markdown
+1. 查阅 Base UI 文档，找到 Select 组件
+2. 在 src/components/Select.tsx 创建文件
+3. 导入 Base UI 的 Select 相关组件
+4. 定义 SelectProps 接口
+5. 实现样式：
+   - Trigger: 类似 Input 的样式
+   - Popup: 白色背景，圆角，阴影
+   - Option: hover 背景变为 var(--bg-hover)
+6. 在 ComponentShowcase.tsx 添加展示
+7. 测试亮色/暗色主题
+```
+
+### 任务：修改主题颜色
+
+```markdown
+1. 打开 src/index.css
+2. 修改 :root 和 :root.dark 中的 CSS 变量
+3. 保存后自动热更新，查看效果
+4. 如果是品牌色修改，需要全局替换引用
+```
+
+### 任务：优化 Slack 克隆页面
+
+```markdown
+1. 定位到 src/examples/slack-clone/
+2. 主要文件：
+   - SlackApp.tsx: 页面主入口
+   - layout/Layout.tsx: 整体布局和侧边栏
+   - components/Message.tsx: 消息卡片
+   - components/Composer.tsx: 消息输入框
+   - components/ChannelHeader.tsx: 频道头部
+3. 修改组件，使用 CSS 变量保持主题一致性
+```
+
+### 任务：添加新路由
+
+```markdown
+1. 在 src/pages/ 创建新页面组件
+2. 打开 src/App.tsx
+3. 添加新的 <Route path="/new-path" element={<NewPage />} />
+4. 在 Dashboard.tsx 添加导航链接（如需要）
+```
+
+## 🐛 调试技巧
+
+### 样式问题
+
+1. **检查 CSS 变量**：确认在 light/dark 模式下都有定义
+2. **TailwindCSS 类**：使用浏览器开发工具检查是否生效
+3. **类名冲突**：使用 `tailwind-merge` 合并类名
+4. **主题切换**：检查 `<html>` 是否有 `.dark` 类
+
+### 组件问题
+
+1. **Base UI 文档**：查阅官方文档确认正确用法
+2. **Props 传递**：确认所有必需的 props 都已提供
+3. **Ref 转发**：确保使用了 `React.forwardRef`
+4. **TypeScript 错误**：检查类型定义是否匹配
+
+### 性能问题
+
+1. **避免不必要的重渲染**：使用 `React.memo`、`useMemo`、`useCallback`
+2. **代码分割**：使用 `React.lazy` 和 `Suspense`
+3. **图片优化**：使用合适的尺寸和格式
+
+## 📚 参考资源
+
+- [Base UI 文档](https://base-ui.com/) - 无样式组件库
+- [Slack Design](https://slack.design/) - Slack 官方设计指南
+- [TailwindCSS 文档](https://tailwindcss.com/) - CSS 工具类
+- [Lucide Icons](https://lucide.dev/) - 图标库
+- [React Router](https://reactrouter.com/) - 路由文档
+
+## 🤖 AI 协作建议
+
+### 理解项目时
+
+1. 先阅读本文档了解整体架构
+2. 查看 `package.json` 了解依赖
+3. 阅读 `src/index.css` 了解设计系统
+4. 浏览 `src/components/` 了解组件实现模式
+5. 运行项目，查看实际效果
+
+### 修改代码时
+
+1. **保持一致性**：遵循现有的代码风格和命名规范
+2. **类型安全**：确保 TypeScript 类型正确
+3. **主题感知**：使用 CSS 变量，测试两种主题
+4. **可访问性**：保留 Base UI 的 ARIA 属性
+5. **文档同步**：重大改动时更新本文档
+
+### 添加功能时
+
+1. **评估范围**：是添加新组件还是增强现有组件
+2. **查找基础**：优先使用 Base UI 的无样式组件
+3. **设计 API**：定义清晰的 props 接口
+4. **实现样式**：使用 Slack 的设计语言
+5. **添加示例**：在 ComponentShowcase 中展示用法
+
+### 回答问题时
+
+1. **定位问题**：根据描述找到相关文件
+2. **提供上下文**：解释代码在项目中的作用
+3. **给出方案**：提供具体的代码示例
+4. **考虑影响**：说明改动可能影响的其他部分
+
+## 🚀 快速命令
+
+```bash
+# 开发
+npm run dev          # 启动开发服务器（端口 5173）
+
+# 构建
+npm run build        # 构建生产版本
+npm run preview      # 预览生产构建
+
+# 代码检查
+npm run lint         # ESLint 检查
+```
+
+## 📝 更新日志
+
+当做出重大改动时，请在此记录：
+
+### 2026-02-08
+- 创建初始项目文档
+- 完成核心组件库（Button, Avatar, Badge, Input, IconButton, Tooltip, Dialog）
+- 实现 Slack 克隆演示应用
+- 支持亮色/暗色主题切换
+- 添加 Dialog 组件，支持多种尺寸和自定义布局
+
+---
+
+**记住**：这个项目的目标是展示如何使用 Base UI 构建真实的、美观的、可访问的 UI 组件库。保持代码清晰、注释充分、类型安全。

package/CHANGELOG.md

@@ -0,0 +1,347 @@
+# 更新日志
+
+## [修复] 2026-02-19
+
+### 🐛 Context Menu 修复
+
+#### 修复右键菜单功能
+修复了 ContextMenu 组件的两个关键问题，大幅提升用户体验。
+
+**修复内容：**
+- ✅ **右键点击功能** - 修复了右键点击不起作用的问题，现在右键点击会正确触发菜单
+- ✅ **菜单定位** - 菜单现在显示在鼠标点击位置附近，而不是触发区域的固定位置
+- ✅ **视觉反馈** - 改进了触发区域的悬停效果和视觉提示
+- ✅ **用户引导** - 添加了鼠标图标和更清晰的说明文字
+
+**技术实现：**
+- 使用虚拟锚点元素（Virtual Element）定位菜单到鼠标坐标
+- 通过 Context API 共享锚点位置
+- 正确处理 `onContextMenu` 事件并程序化触发菜单
+- 支持受控和非受控模式
+
+**使用示例：**
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger>
+    <div>右键点击这里</div>
+  </ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>复制</ContextMenuItem>
+    <ContextMenuItem>粘贴</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+详细文档请参考：
+- `/docs/CONTEXTMENU_FIX.md` - 技术实现细节
+- `/docs/CONTEXTMENU_TEST.md` - 测试说明
+
+---
+
+## [新增] 2026-02-10
+
+### 🎉 新增组件
+
+#### Popover - 浮层组件
+一个功能强大的浮层组件，用于显示临时内容和交互界面。
+
+**特性：**
+- ✅ 基于 Base UI Popover 构建
+- ✅ 支持四个方向：`top`、`right`、`bottom`、`left`
+- ✅ 支持三种对齐方式：`start`、`center`、`end`
+- ✅ 提供便捷子组件：`PopoverHeader`、`PopoverBody`、`PopoverFooter`
+- ✅ 支持受控和非受控两种模式
+- ✅ 优雅的进入/退出动画
+- ✅ 完整的无障碍支持
+
+**示例：**
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button>打开设置</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <PopoverHeader>设置选项</PopoverHeader>
+    <PopoverBody>配置内容</PopoverBody>
+    <PopoverFooter>
+      <Button>保存</Button>
+    </PopoverFooter>
+  </PopoverContent>
+</Popover>
+```
+
+#### Menu - 下拉菜单组件
+一个功能完整的下拉菜单组件，支持多种菜单项类型和丰富的交互。
+
+**特性：**
+- ✅ 基于 Base UI Menu 构建
+- ✅ 支持普通菜单项、复选框项、单选组
+- ✅ 支持多级子菜单
+- ✅ 支持菜单分组和标签
+- ✅ 支持图标和快捷键显示
+- ✅ 支持危险操作标记（红色高亮）
+- ✅ 完整的键盘导航支持
+- ✅ 优雅的动画效果
+
+**包含的子组件：**
+- `MenuItem` - 普通菜单项
+- `MenuCheckboxItem` - 复选框菜单项
+- `MenuRadioGroup` / `MenuRadioItem` - 单选组
+- `MenuSub` / `MenuSubTrigger` / `MenuSubContent` - 子菜单
+- `MenuLabel` - 菜单标签
+- `MenuSeparator` - 分隔线
+- `MenuItemWithIcon` - 带图标的菜单项（便捷组件）
+
+**示例：**
+```tsx
+<Menu>
+  <MenuTrigger asChild>
+    <Button>文件</Button>
+  </MenuTrigger>
+  <MenuContent>
+    <MenuItemWithIcon icon={<FileIcon />} shortcut="⌘N">
+      新建文件
+    </MenuItemWithIcon>
+    <MenuSeparator />
+    <MenuItem destructive>删除</MenuItem>
+  </MenuContent>
+</Menu>
+```
+
+#### ContextMenu - 右键菜单组件
+一个右键触发的上下文菜单组件，API 与 Menu 完全一致。
+
+**特性：**
+- ✅ 自动处理右键事件
+- ✅ 与 Menu 组件 API 完全一致
+- ✅ 支持所有 Menu 的功能（复选框、单选、子菜单等）
+- ✅ 完整的键盘导航和无障碍支持
+- ✅ 适用于上下文操作场景
+
+**示例：**
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger>
+    <div>右键点击这里</div>
+  </ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>复制</ContextMenuItem>
+    <ContextMenuItem>粘贴</ContextMenuItem>
+    <ContextMenuSeparator />
+    <ContextMenuItem destructive>删除</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+**文档：**
+详细使用指南请查看 [POPOVER_MENU_CONTEXTMENU.md](./docs/POPOVER_MENU_CONTEXTMENU.md)
+
+---
+
+## [新增] 2026-02-09
+
+### 🎉 新增组件
+
+#### AlertDialog - 警告对话框组件
+一个专注于重要确认和警告场景的对话框组件，提供更好的用户体验。
+
+**特性：**
+- ✅ 四种语义化变体：`info`、`success`、`warning`、`danger`
+- ✅ 每种变体配有专属图标和配色方案
+- ✅ 支持异步确认操作，自动显示加载状态
+- ✅ 可自定义确认/取消按钮文本和样式
+- ✅ 支持自定义内容区域
+
+**使用场景：**
+- 删除操作确认
+- 重要操作警告
+- 成功/失败提示
+- 信息通知
+
+**示例：**
+```tsx
+<AlertDialog
+  open={open}
+  onOpenChange={setOpen}
+  title="Delete Account?"
+  description="This action cannot be undone."
+  variant="danger"
+  confirmText="Delete"
+  onConfirm={async () => {
+    await deleteAccount()
+  }}
+/>
+```
+
+#### Form - 完整表单系统
+一个功能完整的表单管理系统，提供状态管理、验证和多种表单控件。
+
+**特性：**
+- ✅ 完整的表单状态管理（values、errors、touched）
+- ✅ 内置验证系统，支持自定义验证规则
+- ✅ 多种表单控件：Input、Textarea、Select、Checkbox
+- ✅ 自动错误提示和验证反馈
+- ✅ 必填字段自动标记
+- ✅ 灵活的自定义字段支持（render props）
+
+**包含的子组件：**
+- `FormInput` - 文本输入框
+- `FormTextarea` - 多行文本框
+- `FormSelect` - 下拉选择框
+- `FormCheckbox` - 复选框
+- `FormField` - 自定义表单字段（render props）
+- `FormActions` - 表单操作按钮容器
+- `useFormContext` - 表单上下文 Hook
+
+**使用场景：**
+- 用户注册/登录
+- 个人资料编辑
+- 设置页面
+- 数据录入表单
+
+**示例：**
+```tsx
+<Form
+  initialValues={{ name: '', email: '' }}
+  validate={(values) => {
+    const errors = {}
+    if (!values.name) errors.name = 'Name is required'
+    if (!values.email) errors.email = 'Email is required'
+    return errors
+  }}
+  onSubmit={(values) => {
+    console.log(values)
+  }}
+>
+  <FormInput name="name" label="Name" required fullWidth />
+  <FormInput name="email" label="Email" type="email" required fullWidth />
+  <FormActions>
+    <Button type="submit" variant="primary">Submit</Button>
+  </FormActions>
+</Form>
+```
+
+### 📚 新增文档
+
+1. **ALERTDIALOG_AND_FORM_GUIDE.md** - AlertDialog 和 Form 组件的详细使用指南
+   - 完整的 API 文档
+   - 丰富的使用示例
+   - 设计原则说明
+   - 可访问性说明
+
+2. **QUICK_REFERENCE.md** - 快速参考文档
+   - 所有组件的快速使用示例
+   - 常用 Props 速查
+   - CSS 变量参考
+   - 最佳实践
+   - 常见问题解答
+
+### 🔧 改进
+
+1. **统一导出文件** (`src/components/index.ts`)
+   - 添加了统一的组件导出文件
+   - 支持一次性导入多个组件
+   - 包含 TypeScript 类型导出
+
+2. **组件展示页面更新**
+   - 添加了 AlertDialog 展示区域，包含四种变体的完整示例
+   - 添加了 Form 展示区域，包含两个完整的表单示例
+   - 改进了页面布局和说明文字
+
+3. **README 更新**
+   - 更新了组件列表，添加 AlertDialog 和 Form 的说明
+   - 改进了文档结构
+
+### 🎨 设计改进
+
+1. **AlertDialog 视觉设计**
+   - 每种变体都有独特的图标和配色
+   - 图标使用了 lucide-react 的语义化图标
+   - 背景色使用半透明效果，更加柔和
+
+2. **Form 用户体验**
+   - 字段失焦后立即显示验证错误
+   - 必填字段自动显示红色星号标记
+   - 错误信息显示在字段下方，带有警告图标
+
+### 🐛 Bug 修复
+
+1. 修复了 AlertDialog 中 `flex-shrink-0` 应该使用 `shrink-0` 的 Tailwind 警告
+2. 修复了 Form 组件中未使用的 `isSubmitting` 状态变量
+3. 修复了 FormTextarea 中 `min-h-[80px]` 应该使用 `min-h-20` 的 Tailwind 警告
+
+### 📦 依赖
+
+无新增依赖，所有新组件都基于现有依赖构建。
+
+### ⚡️ 性能
+
+- Form 组件使用了 React.useCallback 优化性能
+- AlertDialog 的异步操作使用了适当的加载状态管理
+
+### ♿️ 可访问性
+
+- AlertDialog 继承了 Base UI Dialog 的完整 ARIA 支持
+- Form 组件自动为表单字段添加正确的 label 关联
+- 所有错误信息都使用了适当的语义化标签
+
+---
+
+## 现有组件
+
+### Button - 按钮组件
+基础交互组件，支持多种样式和状态。
+
+### Avatar - 头像组件
+用户头像展示，支持状态指示器。
+
+### Badge - 徽章组件
+通知计数和状态标识。
+
+### Input - 输入框组件
+基础文本输入控件。
+
+### IconButton - 图标按钮
+紧凑的工具栏按钮。
+
+### Tooltip - 工具提示
+上下文信息提示。
+
+### Dialog - 对话框组件
+通用模态对话框，支持自定义布局。
+
+---
+
+## 路线图
+
+### 计划中的组件
+
+1. **Select** - 独立的下拉选择组件（目前只在 Form 中）
+2. **Checkbox** - 独立的复选框组件（目前只在 Form 中）
+3. **Radio** - 单选按钮组件
+4. **Switch** - 开关组件
+5. **Tabs** - 标签页组件
+6. **Dropdown Menu** - 下拉菜单
+7. **Toast** - 轻量级通知提示
+8. **Modal** - 更通用的模态框
+9. **Popover** - 弹出框
+10. **Progress** - 进度条
+
+### 计划中的功能
+
+1. 表单字段级别的异步验证
+2. 更多的表单控件变体
+3. 组件动画效果增强
+4. 暗色主题优化
+5. 响应式断点工具
+
+---
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 许可证
+
+MIT
+