ai-chat-ui-kit 0.1.0

package/docs/guide/themes.md

@@ -0,0 +1,327 @@
+# 主题定制
+
+AI Chat UI Kit 提供了灵活的主题定制功能，支持多种方式来定制聊天界面的外观。
+
+## 内置主题
+
+AI Chat UI Kit 内置了三种主题：
+
+### 1. 默认主题（Default）
+
+蓝色主题，简洁现代。
+
+```typescript
+import '@ai-chat/themes/default';
+```
+
+**特点：**
+- 主色调：蓝色（#1677ff）
+- 用户消息：蓝色背景
+- AI 消息：白色背景，灰色边框
+
+### 2. 气泡主题（Bubble）
+
+仿微信/QQ 气泡风格。
+
+```typescript
+import '@ai-chat/themes/bubble';
+```
+
+**特点：**
+- 主色调：绿色（#07c160）
+- 用户消息：绿色气泡（#95ec69）
+- AI 消息：白色气泡
+- 带气泡箭头
+
+### 3. 扁平主题（Flat）
+
+扁平化设计，无阴影。
+
+```typescript
+import '@ai-chat/themes/flat';
+```
+
+**特点：**
+- 主色调：深蓝色（#2b6cb0）
+- 无阴影
+- 纯色背景
+- 简洁边框
+
+## 使用主题
+
+### 方式一：静态导入（推荐）
+
+在应用入口文件导入主题：
+
+```typescript
+// main.ts / App.tsx / main.tsx
+import '@ai-chat/themes/default'; // 默认主题
+// 或
+import '@ai-chat/themes/bubble'; // 气泡主题
+// 或
+import '@ai-chat/themes/flat'; // 扁平主题
+```
+
+### 方式二：动态切换
+
+```typescript
+import { applyTheme } from '@ai-chat/themes';
+import { defaultTheme } from '@ai-chat/themes/default';
+import { bubbleTheme } from '@ai-chat/themes/bubble';
+import { flatTheme } from '@ai-chat/themes/flat';
+
+// 应用默认主题
+applyTheme(defaultTheme);
+
+// 切换到气泡主题
+applyTheme(bubbleTheme);
+
+// 切换到扁平主题
+applyTheme(flatTheme);
+```
+
+### 方式三：通过 CSS 变量覆盖
+
+所有主题都使用 CSS 变量，您可以在自己的 CSS 中覆盖这些变量：
+
+```css
+/* 全局覆盖 */
+:root {
+  --ai-primary: #your-primary-color;
+  --ai-message-user-bg: #your-user-msg-bg;
+  --ai-message-ai-bg: #your-ai-msg-bg;
+}
+
+/* 针对特定组件覆盖 */
+.ai-chat {
+  --ai-primary: #your-primary-color;
+}
+```
+
+## 自定义主题
+
+### 创建自定义主题
+
+1. 创建主题 CSS 文件：
+
+```css
+/* themes/my-theme/theme.css */
+
+:root {
+  /* 主色 */
+  --ai-primary: #your-primary-color;
+  --ai-primary-hover: #your-primary-hover;
+  --ai-primary-active: #your-primary-active;
+
+  /* 背景色 */
+  --ai-bg-primary: #your-bg-primary;
+  --ai-bg-secondary: #your-bg-secondary;
+  --ai-bg-chat: #your-bg-chat;
+
+  /* 文本色 */
+  --ai-text-primary: #your-text-primary;
+  --ai-text-secondary: #your-text-secondary;
+
+  /* 消息气泡 */
+  --ai-message-user-bg: #your-user-msg-bg;
+  --ai-message-user-text: #your-user-msg-text;
+  --ai-message-ai-bg: #your-ai-msg-bg;
+  --ai-message-ai-text: #your-ai-msg-text;
+
+  /* 输入框 */
+  --ai-input-bg: #your-input-bg;
+  --ai-input-border: #your-input-border;
+
+  /* 圆角 */
+  --ai-radius-sm: 4px;
+  --ai-radius-md: 8px;
+  --ai-radius-lg: 12px;
+
+  /* 间距 */
+  --ai-spacing-xs: 4px;
+  --ai-spacing-sm: 8px;
+  --ai-spacing-md: 12px;
+  --ai-spacing-lg: 16px;
+}
+
+/* 自定义组件样式 */
+.ai-chat {
+  /* 您的自定义样式 */
+}
+
+.ai-message--user .ai-message__content {
+  /* 自定义用户消息样式 */
+}
+
+.ai-message--assistant .ai-message__content {
+  /* 自定义 AI 消息样式 */
+}
+```
+
+2. 创建主题配置：
+
+```typescript
+// themes/my-theme/index.ts
+import themeStyles from './theme.css?raw';
+
+export const myTheme = {
+  name: 'my-theme',
+  variables: {
+    '--ai-primary': '#your-primary-color',
+    '--ai-primary-hover': '#your-primary-hover',
+    '--ai-primary-active': '#your-primary-active',
+    // ... 其他变量
+  },
+  styles: themeStyles,
+};
+```
+
+3. 使用自定义主题：
+
+```typescript
+import { applyTheme } from '@ai-chat/themes';
+import { myTheme } from './themes/my-theme';
+
+applyTheme(myTheme);
+```
+
+## 主题配置详解
+
+### ThemeConfig 接口
+
+```typescript
+interface ThemeConfig {
+  name: string;
+  variables: Record<string, string>;
+  styles: string;
+}
+```
+
+**字段说明：**
+
+- `name`: 主题名称
+- `variables`: CSS 变量键值对
+- `styles`: 主题 CSS 字符串
+
+### 完整 CSS 变量列表
+
+```css
+:root {
+  /* 主色 */
+  --ai-primary: #1677ff;
+  --ai-primary-hover: #4096ff;
+  --ai-primary-active: #0958d9;
+
+  /* 背景色 */
+  --ai-bg-primary: #ffffff;
+  --ai-bg-secondary: #f5f5f5;
+  --ai-bg-tertiary: #fafafa;
+  --ai-bg-chat: #f0f2f5;
+
+  /* 文本色 */
+  --ai-text-primary: rgba(0, 0, 0, 0.88);
+  --ai-text-secondary: rgba(0, 0, 0, 0.65);
+  --ai-text-tertiary: rgba(0, 0, 0, 0.45);
+  --ai-text-inverse: #ffffff;
+
+  /* 消息气泡 */
+  --ai-message-user-bg: #1677ff;
+  --ai-message-user-text: #ffffff;
+  --ai-message-ai-bg: #ffffff;
+  --ai-message-ai-text: rgba(0, 0, 0, 0.88);
+  --ai-message-border: #e8e8e8;
+
+  /* 输入框 */
+  --ai-input-bg: #ffffff;
+  --ai-input-border: #d9d9d9;
+  --ai-input-focus-border: #1677ff;
+  --ai-input-text: rgba(0, 0, 0, 0.88);
+  --ai-input-placeholder: rgba(0, 0, 0, 0.35);
+
+  /* 工具调用 */
+  --ai-tool-call-bg: #f6f8fa;
+  --ai-tool-call-border: #d1d9e0;
+  --ai-tool-call-success: #52c41a;
+  --ai-tool-call-error: #ff4d4f;
+  --ai-tool-call-running: #1677ff;
+
+  /* 阴影 */
+  --ai-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.06);
+  --ai-shadow-md: 0 2px 8px rgba(0, 0, 0, 0.1);
+  --ai-shadow-lg: 0 4px 16px rgba(0, 0, 0, 0.12);
+
+  /* 圆角 */
+  --ai-radius-sm: 4px;
+  --ai-radius-md: 8px;
+  --ai-radius-lg: 12px;
+  --ai-radius-xl: 16px;
+
+  /* 间距 */
+  --ai-spacing-xs: 4px;
+  --ai-spacing-sm: 8px;
+  --ai-spacing-md: 12px;
+  --ai-spacing-lg: 16px;
+  --ai-spacing-xl: 24px;
+}
+```
+
+## 暗黑模式
+
+### 方式一：使用媒体查询
+
+```css
+/* 默认亮色主题 */
+:root {
+  --ai-bg-chat: #f0f2f5;
+  --ai-text-primary: rgba(0, 0, 0, 0.88);
+}
+
+/* 暗黑模式 */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --ai-bg-chat: #141414;
+    --ai-text-primary: rgba(255, 255, 255, 0.88);
+    --ai-message-ai-bg: #1f1f1f;
+    --ai-message-border: #303030;
+  }
+}
+```
+
+### 方式二：手动切换
+
+```typescript
+// 监听暗黑模式切换
+const darkModeMediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+
+darkModeMediaQuery.addEventListener('change', (e) => {
+  if (e.matches) {
+    applyDarkTheme();
+  } else {
+    applyLightTheme();
+  }
+});
+
+// 或手动切换
+function toggleDarkMode() {
+  document.documentElement.classList.toggle('dark');
+}
+
+// CSS
+.dark {
+  --ai-bg-chat: #141414;
+  --ai-text-primary: rgba(255, 255, 255, 0.88);
+}
+```
+
+## 最佳实践
+
+1. **优先使用 CSS 变量覆盖** - 不需要创建完整主题，只需覆盖需要修改的变量
+2. **保持一致性** - 确保主题色彩与您的品牌色一致
+3. **测试可读性** - 确保文本与背景的对比度足够
+4. **支持暗黑模式** - 为用户提供亮色和暗色两种主题
+
+## 下一步
+
+- [插件开发](./plugins.md) - 学习如何扩展功能
+- [API 适配器](./api-adapters.md) - 学习如何兼容不同后端 API
+- [API 参考](../../api/) - 查看完整 API 文档

package/docs/index.html

@@ -0,0 +1,256 @@
+<!--
+  @generated-by AI: edenxpzhang
+  @generated-date 2026-05-13
+-->
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>AI Chat UI Kit · 主题预览</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: #f5f5f7; color: #333; }
+    .header { text-align: center; padding: 60px 20px 40px; background: white; border-bottom: 1px solid #e5e5ea; }
+    .header h1 { font-size: 36px; font-weight: 700; margin-bottom: 12px; }
+    .header p { font-size: 16px; color: #86868b; max-width: 760px; margin: 0 auto; line-height: 1.6; }
+    .header .badge {
+      display: inline-block; margin-top: 16px;
+      padding: 6px 14px; background: #e8f2ff; color: #0071e3;
+      font-size: 12px; border-radius: 12px; font-weight: 600;
+    }
+    .theme-grid {
+      max-width: 1480px; margin: 0 auto;
+      padding: 40px 20px 80px;
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(420px, 1fr));
+      gap: 32px;
+    }
+    .theme-card {
+      background: white; border-radius: 20px;
+      box-shadow: 0 4px 20px rgba(0,0,0,0.08);
+      overflow: hidden;
+      transition: transform 0.3s, box-shadow 0.3s;
+    }
+    .theme-card:hover { transform: translateY(-6px); box-shadow: 0 12px 40px rgba(0,0,0,0.15); }
+    .compare-row {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      border-bottom: 1px solid #f0f0f0;
+    }
+    .compare-cell {
+      height: 360px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      overflow: hidden;
+      position: relative;
+    }
+    .compare-cell + .compare-cell { border-left: 1px solid #f0f0f0; }
+    .compare-cell iframe {
+      border: none;
+      transform-origin: top center;
+      pointer-events: none;
+    }
+    .compare-cell .label {
+      position: absolute;
+      top: 8px; left: 8px;
+      padding: 3px 8px;
+      background: rgba(0,0,0,0.55);
+      color: #fff;
+      font-size: 11px;
+      border-radius: 6px;
+      letter-spacing: 0.5px;
+      z-index: 2;
+    }
+    .compare-cell.real .label { background: #0071e3; }
+    .theme-info {
+      padding: 18px 22px;
+      display: flex;
+      flex-direction: column;
+      gap: 6px;
+    }
+    .theme-info h3 { font-size: 18px; font-weight: 600; }
+    .theme-info p { font-size: 13px; color: #86868b; line-height: 1.5; }
+    .theme-info .actions {
+      margin-top: 10px;
+      display: flex;
+      gap: 10px;
+    }
+    .theme-info .actions a {
+      display: inline-block;
+      padding: 6px 12px;
+      font-size: 12px;
+      text-decoration: none;
+      border-radius: 6px;
+      border: 1px solid #e0e0e0;
+      color: #555;
+      transition: all 0.15s;
+    }
+    .theme-info .actions a:hover { border-color: #0071e3; color: #0071e3; }
+    .theme-info .actions a.primary { background: #0071e3; border-color: #0071e3; color: #fff; }
+    .theme-info .actions a.primary:hover { background: #0077ed; }
+    .theme-tag {
+      display: inline-block;
+      padding: 3px 10px;
+      border-radius: 12px;
+      font-size: 11px;
+      font-weight: 600;
+      align-self: flex-start;
+    }
+    .footer { text-align: center; padding: 40px 20px; color: #86868b; font-size: 13px; }
+    .footer a { color: #0071e3; text-decoration: none; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>🎨 AI Chat UI Kit</h1>
+    <p>6 套精心设计的聊天界面主题。每一行展示「设计稿 demo」与「真实组件 + 主题渲染」的并排对比，确认两者视觉一致。</p>
+    <span class="badge">基于 Web Components · 兼容 React / Vue / 原生 HTML</span>
+  </div>
+
+  <div class="theme-grid">
+    <!-- 01 Minimal -->
+    <div class="theme-card">
+      <div class="compare-row">
+        <div class="compare-cell" style="background: #f5f5f7;">
+          <span class="label">设计稿</span>
+          <iframe src="chat-style-1-minimal.html" style="width: 400px; height: 700px; transform: scale(0.5);"></iframe>
+        </div>
+        <div class="compare-cell real" style="background: #f5f5f7;">
+          <span class="label">真实组件 + 主题</span>
+          <iframe src="theme-preview-1-minimal.html" style="width: 400px; height: 700px; transform: scale(0.5);"></iframe>
+        </div>
+      </div>
+      <div class="theme-info">
+        <h3>01 · Minimal Clean</h3>
+        <p>极简苹果风，圆角气泡 + 蓝白配色，适合移动端和桌面端通用场景。</p>
+        <span class="theme-tag" style="background: #e8f2ff; color: #0071e3;">Apple Style</span>
+        <div class="actions">
+          <a href="chat-style-1-minimal.html" target="_blank">设计稿</a>
+          <a class="primary" href="theme-preview-1-minimal.html" target="_blank">主题预览</a>
+        </div>
+      </div>
+    </div>
+
+    <!-- 02 Neon -->
+    <div class="theme-card">
+      <div class="compare-row">
+        <div class="compare-cell" style="background: #0a0a0a;">
+          <span class="label">设计稿</span>
+          <iframe src="chat-style-2-neon.html" style="width: 450px; height: 700px; transform: scale(0.45);"></iframe>
+        </div>
+        <div class="compare-cell real" style="background: #0a0a0a;">
+          <span class="label">真实组件 + 主题</span>
+          <iframe src="theme-preview-2-neon.html" style="width: 450px; height: 700px; transform: scale(0.45);"></iframe>
+        </div>
+      </div>
+      <div class="theme-info">
+        <h3>02 · Dark Neon</h3>
+        <p>赛博朋克深色主题，霓虹发光效果，适合科技感强的 AI 产品。</p>
+        <span class="theme-tag" style="background: #1a1a2e; color: #00ffff;">Cyberpunk</span>
+        <div class="actions">
+          <a href="chat-style-2-neon.html" target="_blank">设计稿</a>
+          <a class="primary" href="theme-preview-2-neon.html" target="_blank">主题预览</a>
+        </div>
+      </div>
+    </div>
+
+    <!-- 03 Glass -->
+    <div class="theme-card">
+      <div class="compare-row">
+        <div class="compare-cell" style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);">
+          <span class="label">设计稿</span>
+          <iframe src="chat-style-3-glass.html" style="width: 420px; height: 700px; transform: scale(0.48);"></iframe>
+        </div>
+        <div class="compare-cell real" style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);">
+          <span class="label">真实组件 + 主题</span>
+          <iframe src="theme-preview-3-glass.html" style="width: 420px; height: 700px; transform: scale(0.48);"></iframe>
+        </div>
+      </div>
+      <div class="theme-info">
+        <h3>03 · Glassmorphism</h3>
+        <p>毛玻璃拟态风格，半透明模糊效果，适合现代化 SaaS 产品。</p>
+        <span class="theme-tag" style="background: rgba(102,126,234,0.15); color: #667eea;">Glass</span>
+        <div class="actions">
+          <a href="chat-style-3-glass.html" target="_blank">设计稿</a>
+          <a class="primary" href="theme-preview-3-glass.html" target="_blank">主题预览</a>
+        </div>
+      </div>
+    </div>
+
+    <!-- 04 Terminal -->
+    <div class="theme-card">
+      <div class="compare-row">
+        <div class="compare-cell" style="background: #0a0a0a;">
+          <span class="label">设计稿</span>
+          <iframe src="chat-style-4-terminal.html" style="width: 650px; height: 720px; transform: scale(0.32);"></iframe>
+        </div>
+        <div class="compare-cell real" style="background: #0a0a0a;">
+          <span class="label">真实组件 + 主题</span>
+          <iframe src="theme-preview-4-terminal.html" style="width: 650px; height: 720px; transform: scale(0.32);"></iframe>
+        </div>
+      </div>
+      <div class="theme-info">
+        <h3>04 · Retro Terminal</h3>
+        <p>复古终端风格，绿色配色 + 扫描线效果，适合开发者工具 / CLI 产品。</p>
+        <span class="theme-tag" style="background: #e8fff0; color: #00aa00;">Terminal</span>
+        <div class="actions">
+          <a href="chat-style-4-terminal.html" target="_blank">设计稿</a>
+          <a class="primary" href="theme-preview-4-terminal.html" target="_blank">主题预览</a>
+        </div>
+      </div>
+    </div>
+
+    <!-- 05 Gradient -->
+    <div class="theme-card">
+      <div class="compare-row">
+        <div class="compare-cell" style="background: linear-gradient(135deg, #f093fb 0%, #f5576c 25%, #4facfe 50%, #00f2fe 75%, #43e97b 100%); background-size: 400% 400%;">
+          <span class="label">设计稿</span>
+          <iframe src="chat-style-5-gradient.html" style="width: 420px; height: 720px; transform: scale(0.48);"></iframe>
+        </div>
+        <div class="compare-cell real" style="background: linear-gradient(135deg, #f093fb 0%, #f5576c 25%, #4facfe 50%, #00f2fe 75%, #43e97b 100%); background-size: 400% 400%;">
+          <span class="label">真实组件 + 主题</span>
+          <iframe src="theme-preview-5-gradient.html" style="width: 420px; height: 720px; transform: scale(0.48);"></iframe>
+        </div>
+      </div>
+      <div class="theme-info">
+        <h3>05 · Gradient Bubbles</h3>
+        <p>多彩渐变气泡，弹出动画 + emoji，适合年轻化 / 社交类产品。</p>
+        <span class="theme-tag" style="background: linear-gradient(135deg,#f093fb,#f5576c); color: white;">Gradient</span>
+        <div class="actions">
+          <a href="chat-style-5-gradient.html" target="_blank">设计稿</a>
+          <a class="primary" href="theme-preview-5-gradient.html" target="_blank">主题预览</a>
+        </div>
+      </div>
+    </div>
+
+    <!-- 06 Corporate -->
+    <div class="theme-card">
+      <div class="compare-row">
+        <div class="compare-cell" style="background: #f0f2f5;">
+          <span class="label">设计稿</span>
+          <iframe src="chat-style-6-corporate.html" style="width: 480px; height: 720px; transform: scale(0.42);"></iframe>
+        </div>
+        <div class="compare-cell real" style="background: #f0f2f5;">
+          <span class="label">真实组件 + 主题</span>
+          <iframe src="theme-preview-6-corporate.html" style="width: 480px; height: 720px; transform: scale(0.42);"></iframe>
+        </div>
+      </div>
+      <div class="theme-info">
+        <h3>06 · Corporate Professional</h3>
+        <p>企业商务风格，蓝色主题 + 头像时间戳，适合 B 端 / 企业级应用。</p>
+        <span class="theme-tag" style="background: #e6f7ff; color: #1890ff;">Enterprise</span>
+        <div class="actions">
+          <a href="chat-style-6-corporate.html" target="_blank">设计稿</a>
+          <a class="primary" href="theme-preview-6-corporate.html" target="_blank">主题预览</a>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <div class="footer">
+    <p>AI Chat UI Kit · Built with Web Components · <a href="https://github.com/edenxpzhang/ai-chat-ui-kit" target="_blank">View on GitHub</a></p>
+  </div>
+</body>
+</html>

package/docs/theme-preview-1-minimal.html

@@ -0,0 +1,74 @@
+<!--
+  @generated-by AI: edenxpzhang
+  @generated-date 2026-05-13
+
+  Theme Preview · Minimal —— 真实组件 DOM + minimal 主题
+-->
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>主题预览 · 01 Minimal Clean | AI Chat UI Kit</title>
+  <link rel="stylesheet" href="../packages/themes/src/minimal/theme.css" />
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { height: 100%; }
+    body {
+      background: #f5f5f7;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 24px;
+    }
+    .stage { width: 400px; height: 700px; }
+  </style>
+</head>
+<body data-theme="minimal">
+  <div class="stage">
+    <div class="ai-chat" data-theme="minimal">
+      <header class="ai-chat__header">
+        <div class="ai-chat__avatar">🤖</div>
+        <div class="ai-chat__title-group">
+          <h3 class="ai-chat__title">AI Assistant</h3>
+          <p class="ai-chat__subtitle">在线 · 随时为您服务</p>
+        </div>
+      </header>
+      <div class="ai-chat__messages">
+        <div class="ai-message ai-message--assistant">
+          <div class="ai-message__avatar">AI</div>
+          <div class="ai-message__body">
+            <div class="ai-message__content">您好！我是 AI 助手，有什么可以帮您的吗？😊</div>
+            <div class="ai-message__time">14:30</div>
+          </div>
+        </div>
+        <div class="ai-message ai-message--user">
+          <div class="ai-message__avatar">我</div>
+          <div class="ai-message__body">
+            <div class="ai-message__content">这个 UI 看起来不错</div>
+            <div class="ai-message__time">14:31</div>
+          </div>
+        </div>
+        <div class="ai-message ai-message--assistant">
+          <div class="ai-message__avatar">AI</div>
+          <div class="ai-message__body">
+            <div class="ai-message__content">谢谢！这是基于 Web Components 的真实组件渲染效果。</div>
+            <div class="ai-message__time">14:31</div>
+          </div>
+        </div>
+        <div class="ai-typing-indicator">
+          <span class="ai-typing-indicator__dot"></span>
+          <span class="ai-typing-indicator__dot"></span>
+          <span class="ai-typing-indicator__dot"></span>
+        </div>
+      </div>
+      <div class="ai-input">
+        <div class="ai-input__wrapper">
+          <textarea class="ai-input__textarea" placeholder="输入消息..." rows="1"></textarea>
+          <button class="ai-input__send">↑</button>
+        </div>
+      </div>
+    </div>
+  </div>
+</body>
+</html>