tt-design-web-vue 0.1.0

package/docs/components/select.md

@@ -0,0 +1,71 @@
+# Select
+
+从根入口导入：
+
+```ts
+import { TtSelect } from 'tt-design-web-vue';
+import type { SelectOption, SelectValue } from 'tt-design-web-vue';
+```
+
+## 示例
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TtSelect } from 'tt-design-web-vue';
+
+const value = ref('a');
+const options = [
+  { label: '选项 A', value: 'a' },
+  { label: '选项 B', value: 'b' },
+  { label: '不可选项', value: 'disabled', disabled: true },
+];
+</script>
+
+<template>
+  <tt-select v-model="value" :options="options" placeholder="请选择" style="width: 240px" />
+</template>
+```
+
+可交互预览、受控值与底部插槽示例见本地 Storybook：`yarn storybook`。
+
+## Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `modelValue` | `SelectValue \| SelectValue[]` | — | 受控值，由 `defineModel` 提供。 |
+| `options` | `SelectOptionItem[]` | `[]` | 无默认插槽内容时渲染的普通选项或分组选项列表。 |
+| `popperClass` | `string` | `''` | 传给浮层的类名。 |
+| `searchable` | `boolean` | `false` | 显示 TT 自定义下拉搜索框；与 Element Plus 的 `filterable` 原生搜索互不冲突。 |
+| `showSelectAll` | `boolean` | `false` | 多选时在下拉面板底部显示全选操作，支持普通和分组选项。 |
+
+```ts
+export type SelectValue = string | number | boolean;
+
+export interface SelectOption {
+  label: string;
+  value: SelectValue;
+  disabled?: boolean;
+}
+
+export interface SelectOptionGroup {
+  label: string;
+  options: SelectOption[];
+  disabled?: boolean;
+}
+
+export type SelectOptionItem = SelectOption | SelectOptionGroup;
+```
+
+## Events、插槽与实例方法
+
+| 类别 | 项目 | 说明 |
+| --- | --- | --- |
+| Event | `update:modelValue` | 由 `defineModel` 提供。 |
+| Slot | `default` | 自定义选项内容；存在时替代 `options` 自动渲染。 |
+| Slot | `footer` | 下拉面板底部内容。 |
+| Expose | `selectRef`、`focus()`、`blur()` | 转发内部选择器实例与焦点控制。 |
+
+其他未显式声明的属性会通过 `$attrs` 透传。
+
+**源码依据**：`src/components/Select/Select.vue:2-71`；`src/components/Select/index.ts:1-4`；`src/index.ts:75-76`。

package/docs/components/table.md

@@ -0,0 +1,44 @@
+# Table
+
+从根入口导入：
+
+```ts
+import { TtTable, TtTableColumn, TtTableOperationColumn } from 'tt-design-web-vue';
+```
+
+## Table
+
+`Table` 未显式声明 props 或 emits；传入的属性通过 `$attrs` 透传给 `ElTable`。
+
+| 类别 | 项目 | 说明 |
+| --- | --- | --- |
+| Slots | `default` | 表格列内容。 |
+| Slots | `empty` | 空状态内容。 |
+| Slots | `append` | 表格末尾附加内容。 |
+| Expose | `tableRef` | 内部 `ElTable` 引用。 |
+| Expose | `clearSelection`、`toggleRowSelection`、`toggleAllSelection`、`toggleRowExpansion`、`setCurrentRow`、`clearSort`、`clearFilter`、`doLayout`、`sort` | 转发底层表格方法。 |
+
+各个底层方法的参数与返回值以 Element Plus 版本文档为准。
+
+## TableColumn
+
+`TableColumn` 未显式声明 props、emits 或 expose；属性透传给 `ElTableColumn`。
+
+| 类别 | 项目 |
+| --- | --- |
+| Slots | `default`、`header` |
+
+## TableOperationColumn
+
+| Prop | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `label` | `string` | `'操作'` | 操作列表头文案。 |
+| `showHeaderTools` | `boolean` | `true` | 是否展示表头工具。 |
+| `fixed` | 未显式收窄 | `'right'` | 固定列位置。 |
+
+| 类别 | 项目 | 说明 |
+| --- | --- | --- |
+| Event | `header-tools-click` | 参数为 `MouseEvent`。 |
+| Slots | `default`、`header` | 操作内容与自定义表头。 |
+
+**源码依据**：`src/components/Table/Table.vue:20-71`；`src/components/Table/TableColumn.vue`；`src/components/Table/TableOperationColumn.vue`；`src/components/Table/index.ts:1-3`；`src/index.ts:87`。

package/docs/components/upload.md

@@ -0,0 +1,40 @@
+# Upload
+
+从根入口导入：
+
+```ts
+import { TtUpload } from 'tt-design-web-vue';
+import type { UploadSize } from 'tt-design-web-vue';
+```
+
+## 示例
+
+```vue
+<template>
+  <tt-upload>
+    选择文件
+  </tt-upload>
+</template>
+```
+
+## Props
+
+| 名称 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `pictureCardWidth` | `number` | `60` | 图片卡片展示宽度。 |
+| `showMetaInfo` | `boolean` | `false` | 是否展示文件元信息。 |
+| `size` | `'large' \| 'small'` | `'large'` | 上传区域尺寸。 |
+
+`UploadSize` 从根入口以类型形式导出。
+
+## Events、插槽与实例方法
+
+| 类别 | 项目 | 说明 |
+| --- | --- | --- |
+| Events | — | 源码未显式声明；其余事件由 `$attrs` 透传。 |
+| Slots | `default`、`tip`、`file` | 上传触发区、提示与文件项内容。 |
+| Expose | `uploadRef`、`submit()`、`abort()`、`clearFiles()`、`handleStart()`、`handleRemove()` | 转发内部上传实例与常用操作。 |
+
+其他属性同样通过 `$attrs` 透传给底层上传组件；方法参数与返回值以 Element Plus 当前版本为准。
+
+**源码依据**：`src/components/Upload/Upload.vue:47-60,108-139`；`src/components/Upload/index.ts:1-3`；`src/index.ts:103,108`。

package/docs/index.md

@@ -0,0 +1,35 @@
+# TT Design Vue
+
+Vue 3 + Element Plus 的 TT Design 风格组件库。
+
+## 开始使用
+
+```bash
+yarn add vue element-plus tt-design-web-vue
+```
+
+```ts
+import 'element-plus/dist/index.css';
+import 'tt-design-web-vue/style.css';
+```
+
+- [主题变量与覆盖方式](./theme)
+- [从 workspace 迁出说明](./migration-from-workspace)
+- [React 基线兼容清单](./component-compatibility)
+- [首批组件 API 文档](./components/)
+
+## 组件展示
+
+组件的交互预览、Props Controls、事件记录与状态示例由 Storybook 提供。本地安装依赖后运行：
+
+```bash
+yarn storybook
+```
+
+VitePress 保留安装、主题、迁出与兼容性等长文档；组件 API 页提供可复制的最小用法和源码边界。
+
+## 文档原则
+
+- 文档以本项目 `src/` 源码为唯一 API 事实来源。
+- 标记为 `exact-name` 的项目仅说明根入口名称一致，不承诺 API 行为一致。
+- 宿主应用应先加载 Element Plus 样式，再加载 TT Design 样式。

package/docs/migration-from-workspace.md

@@ -0,0 +1,79 @@
+# 从 workspace 迁出
+
+## 目标
+
+本项目将原 Vue 组件库从以下 source-first workspace 路径复制到独立 Git 项目：
+
+```text
+/Users/meng/Documents/productcode/platform/apps/frontend/web/packages/tt-design-vue
+```
+
+独立项目位置：
+
+```text
+/Users/meng/Documents/productcode/tt-design-vue
+```
+
+迁出后的包名仍为 `tt-design-web-vue`，首个可安装版本为 `0.1.0-rc.0`。
+
+## 保留的兼容基线
+
+- 完整保留源 `src/`：根入口、全部组件目录、类型导出、服务 API 与全量 SCSS 样式。
+- 保留现有根入口中的基础组件和扩展/组合组件；本次不因 React 基线范围而删除 Vue 现有导出。
+- 主题 token 只保留 `--el-*` 到 `--tt-*` 的 CSS variable fallback；原 `--micro-base-*` / `--micro-app-*` 微前端变量与 `.app-shell` 选择器已移除，宿主主题统一经 Element Plus 变量继承。
+- 保留 `tt-design-web-vue/dist/style.css` 入口作为旧调用方的兼容 CSS 路径。
+
+## 独立化变化
+
+| 项目 | 原 workspace 包 | 独立项目 |
+| --- | --- | --- |
+| JS 入口 | `src/index.ts` | `dist/index.js` / `dist/index.cjs` |
+| 类型入口 | `src/index.ts` | `dist/types/index.d.ts` |
+| CSS 入口 | `src/styles/index.scss` | `dist/style.css` |
+| 解析方式 | Vite alias 直连源码 | 标准 package `exports` |
+| 构建依赖 | 继承 workspace | 自带 Vite、Vue TypeScript、Sass 构建配置 |
+| 包状态 | 私有 source-first | 可用于预发布的独立 package |
+
+## 不在本次范围内的内容
+
+以下对象保持原样，未修改：
+
+- 原 `packages/tt-design-vue` 目录及其中所有文件；
+- platform workspace 的 `package.json`、锁文件、Vite alias、TypeScript paths；
+- `shared-components` 的 peer dependency；
+- Portal、Official、Support、User 等应用的任何消费代码。
+
+因此，独立库构建失败或预发布未通过时，不需要回滚任何业务应用。
+
+## 后续消费者切换建议
+
+独立包验证并发布后，另起迁移任务，按以下顺序切换：
+
+1. 先处理 `shared-components`，明确其 peer dependency 与样式入口；
+2. 逐个切换 Portal、Official、Support、User；
+3. 每个应用仅在安装独立预发布包后删除其对应的 Vite alias / TypeScript path；
+4. 对每个应用单独执行 build、类型检查、E2E 和视觉验证；
+5. 保留旧 workspace 包，直到所有消费者稳定并具备可回退的发布版本。
+
+## 发布前检查
+
+在独立项目根目录运行：
+
+```bash
+yarn lint
+yarn test
+yarn build
+yarn test:package
+npm pack --dry-run
+```
+
+检查包内至少包含：
+
+```text
+dist/index.js
+dist/index.cjs
+dist/types/index.d.ts
+dist/style.css
+```
+
+实际向 registry 发布或变更 `next` 标签属于对外操作，必须在执行前再次获得明确确认。

package/docs/theme.md

@@ -0,0 +1,100 @@
+# 主题
+
+`tt-design-web-vue` 使用 CSS Custom Properties 作为公开主题契约。组件样式从 `src/styles/index.scss` 聚合，构建后由 `tt-design-web-vue/style.css` 提供。
+
+## 主题模式
+
+宿主通过 `html[data-tt-theme]` 选择主题模式：
+
+```ts
+import { applyTheme } from 'tt-design-web-vue';
+
+applyTheme('light'); // light
+applyTheme('dark'); // dark
+applyTheme('system'); // 跟随 prefers-color-scheme
+```
+
+也可以直接设置 HTML 属性：
+
+```html
+<html data-tt-theme="dark">
+```
+
+组件库不保存主题状态，也不依赖路由或业务 store。`system` 模式通过 CSS `prefers-color-scheme` 在浏览器侧切换，弹层和挂载到 `body` 的组件同样继承该主题。
+
+## 加载顺序
+
+Element Plus 负责基础组件的结构与默认变量，TT Design 在其上覆盖视觉细节。宿主应先加载 Element Plus 样式，再加载 TT Design 样式：
+
+```ts
+import 'element-plus/dist/index.css';
+import 'tt-design-web-vue/style.css';
+```
+
+## 主色继承顺序
+
+主色 token 直接继承 Element Plus 主题变量。以 `--tt-color-primary-6` 为例，其值依次来自：
+
+```text
+--el-color-primary
+  → #3388ff
+```
+
+其他主色色阶读取相应的 Element Plus `--el-color-primary-light-*`、`--el-color-primary-dark-2` 变量。没有宿主覆盖时，组件库使用内置 TT 默认色。宿主只需提供 Element Plus 主题（或直接覆盖 `--el-*` 变量）即可联动 TT 组件配色。
+
+## 可覆盖 Token
+
+### 色彩与文本
+
+| 类别 | 常用变量 |
+| --- | --- |
+| 主色 | `--tt-color-primary-1` 至 `--tt-color-primary-7`、`--tt-color-primary`、`--tt-color-primary-hover`、`--tt-color-primary-active` |
+| 状态色 | `--tt-color-success`、`--tt-color-warning`、`--tt-color-error`、`--tt-color-info` |
+| 中性色 | `--tt-color-grey-0` 至 `--tt-color-grey-9` |
+| 文本 | `--tt-text-title`、`--tt-text-body`、`--tt-text-secondary`、`--tt-text-placeholder`、`--tt-text-danger`、`--tt-text-warning`、`--tt-text-success` |
+| 背景与边框 | `--tt-bg-white`、`--tt-bg-light`、`--tt-bg-lighter`、`--tt-bg-lightest`、`--tt-bg-subtle`、`--tt-bg-thead`、`--tt-border-color`、`--tt-border-color-light`、`--tt-border-color-dark` |
+
+组件样式优先使用语义变量：`--tt-bg-page`、`--tt-bg-surface`、`--tt-bg-elevated`、`--tt-bg-hover`、`--tt-bg-disabled`、`--tt-text-disabled`、`--tt-text-inverse`、`--tt-border-color-focus`、`--tt-overlay-color`、`--tt-focus-ring`、`--tt-shadow-sm`、`--tt-shadow-md` 和 `--tt-shadow-lg`。
+
+### 与设计规范对齐的取值
+
+浅色主题下，以下语义变量的取值直接对应设计规范，组件不应再各自硬编码：
+
+| 场景 | 变量 | 浅色取值 |
+| --- | --- | --- |
+| 页面底色 | `--tt-bg-page` | `#f2f2f2` |
+| 表头底色 | `--tt-bg-thead`（别名 `--tt-bg-light`） | `#f7f8fa` |
+| 控件边框 | `--tt-border-color`（别名 `--tt-color-grey-2`） | `#e9ecf2` |
+| 分割线与容器外框 | `--tt-border-color-light`（别名 `--tt-color-grey-1`） | `#f5f7fa` |
+| 成功色 | `--tt-color-success` | `#35d4a7` |
+
+深色主题与 `system` 主题块按同一套语义变量推导，`--tt-bg-light`、`--tt-bg-subtle`、`--tt-bg-thead` 均指向 `--tt-color-grey-1`；`--tt-border-color` / `--tt-border-color-light` 分别指向 `--tt-color-grey-3` / `--tt-color-grey-2`。
+
+### 圆角与排版
+
+| 类别 | 变量 |
+| --- | --- |
+| 圆角 | `--tt-radius-base`、`--tt-radius-lg`、`--tt-radius-round` |
+| 字体 | `--tt-font-size-base`、`--tt-font-size-sm`、`--tt-line-height-base` |
+
+## 覆盖示例
+
+在加载组件库样式后，向应用根节点覆盖需要替换的 token：
+
+```css
+:root {
+  --tt-color-primary-6: #2468d7;
+  --tt-color-primary-hover: #4d86e1;
+  --tt-color-primary-active: #1c50a8;
+  --tt-color-primary-shadow: rgb(36 104 215 / 24%);
+  --tt-radius-base: 6px;
+}
+```
+
+如宿主已维护 Element Plus 主题，更推荐直接提供 `--el-color-primary` 及相关 Element Plus 变量，让 TT token 按既有 fallback 链自动继承。
+
+## 作用域
+
+Token 定义在 `:root`、`[data-tt-theme='light']` 和 `[data-tt-theme='dark']`。需要隔离多应用主题时，可在具体页面容器上覆盖同名变量；如果组件使用 body-mounted overlay，主题属性应设置在 `html` 上。
+
+不要把旧 `platform` 的 Sass、JavaScript alias 或运行时主题模块引入本项目。主题继承只依赖标准 CSS variables（`--el-*`），不依赖旧 workspace 源码，也不再使用 `--micro-base-*` / `--micro-app-*` 微前端变量。

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "tt-design-web-vue",
+  "version": "0.1.0",
+  "description": "Vue 3 + Element Plus component library aligned with TT Design visual tokens.",
+  "type": "module",
+  "author": "mengxiangxin <mengxiangxin@ttpark.cn>",
+  "license": "MIT",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "style": "./dist/style.css",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./style.css": "./dist/style.css",
+    "./rich-text.css": "./dist/rich-text.css",
+    "./dist/style.css": "./dist/style.css",
+    "./dist/rich-text.css": "./dist/rich-text.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "!docs/.vitepress",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "**/*.css",
+    "**/*.scss"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "packageManager": "yarn@1.22.22",
+  "publishConfig": {
+    "tag": "latest"
+  },
+  "resolutions": {
+    "vite-plugin-dts/@vue/language-core": "2.2.12"
+  },
+  "scripts": {
+    "build": "yarn typecheck && vite build",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.build.json",
+    "lint": "vue-tsc --noEmit -p tsconfig.json && vue-tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:package": "node scripts/test-package.mjs",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "storybook": "storybook dev -p 6006",
+    "storybook:build": "storybook build",
+    "prepack": "yarn build && yarn test:package"
+  },
+  "peerDependencies": {
+    "element-plus": "^2.9.10",
+    "vue": "^3.5.14"
+  },
+  "dependencies": {
+    "@element-plus/icons-vue": "^2.3.1",
+    "@wangeditor/editor": "^5.1.23",
+    "@wangeditor/editor-for-vue": "^5.1.12",
+    "echarts": "^6.1.0",
+    "qrcode": "^1.5.4"
+  },
+  "devDependencies": {
+    "@storybook/addon-docs": "9.0.8",
+    "@storybook/vue3-vite": "9.0.8",
+    "@types/node": "^22.15.3",
+    "@types/qrcode": "^1.5.6",
+    "@vitejs/plugin-vue": "^5.2.4",
+    "@vue/test-utils": "^2.4.6",
+    "element-plus": "^2.9.10",
+    "jsdom": "^26.1.0",
+    "sass": "^1.86.3",
+    "storybook": "9.0.8",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vitepress": "^1.6.3",
+    "vitest": "3.1.2",
+    "vue": "^3.5.14",
+    "vue-tsc": "^2.2.10"
+  }
+}