@simon_he/vue-tui 0.0.3 → 0.0.5

package/README.md

@@ -1,6 +1,7 @@
 # Vue Terminal
 
 用 Vue 组件语法绘制和交互的终端渲染框架。目标是让 “终端” 具备：
+
 - 类终端的写入/删除/更新/尺寸调整能力
 - ANSI 样式渲染（颜色、加粗、下划线等）
 - 事件机制（点击、移动、滚动、拖拽）
@@ -13,7 +14,13 @@
 ```vue
 <script setup lang="ts">
 import { computed, ref } from 'vue'
-import { TerminalProvider, TBox, TInput, TText, useLayout } from '@simon_he/vue-tui'
+import {
+  TerminalProvider,
+  TBox,
+  TInput,
+  TText,
+  useLayout,
+} from '@simon_he/vue-tui'
 
 const layout = useLayout()
 const cols = computed(() => layout.clipRect?.w ?? 80)
@@ -22,8 +29,21 @@ const input = ref('')
 </script>
 
 <template>
-  <TerminalProvider :cols="80" :rows="24" :default-style="{ fg: 'whiteBright' }">
-    <TBox :x="0" :y="0" :w="80" :h="24" border title="Demo" :padding="1" :style="{ fg: 'blueBright' }">
+  <TerminalProvider
+    :cols="80"
+    :rows="24"
+    :default-style="{ fg: 'whiteBright' }"
+  >
+    <TBox
+      :x="0"
+      :y="0"
+      :w="80"
+      :h="24"
+      border
+      title="Demo"
+      :padding="1"
+      :style="{ fg: 'blueBright' }"
+    >
       <TText :x="0" :y="0" :w="78" :value="`cols=${cols} rows=${rows}`" />
       <TInput :x="0" :y="20" :w="78" v-model="input" placeholder="Type..." />
     </TBox>
@@ -31,6 +51,15 @@ const input = ref('')
 </template>
 ```
 
+## 组件文档与验收标准
+
+- VitePress 文档站点（本地）：`bun run --filter '@simon_he/vue-tui' docs:dev`（入口 `docs/index.md`）
+- 组件使用文档：`docs/components.md`
+- 组件 Props/Events（自动生成）：`docs/generated/components-api.md`（脚本：`scripts/generate-component-api-docs.ts`）
+- 组件验收标准（可信赖组件定义 + 测试范围）：`docs/components-acceptance.md`
+- Terminal 兼容性与颜色一致性：`docs/terminal-compatibility.md`
+- 性能关注点与回归策略：`docs/performance.md`
+
 ### 终端（真实 CLI）渲染
 
 内置 `vue-terminal run`，直接在真实终端中跑 UI（stdout renderer + stdin driver）：
@@ -67,11 +96,13 @@ terminal 构建产物会生成 `dist-terminal/terminal.js`，可以直接作为
 GoatChain 示例应用目前用的是 mock LLM，但你可以很快替换成任意 LLM SDK（OpenAI/Anthropic/本地模型）。
 
 建议做法：
+
 1. 用 ACP 风格的流式协议驱动 UI（支持 `text_delta` / `tool_call_delta` / `tool_call_end` / `tool_result` / `done`）。
 2. tool_call 的执行可以交给 agent 侧（推荐，和 GoatChain CLI 一致），UI 只负责渲染与“暂停→继续”的用户输入。
 3. 在 UI 侧维护 token 统计与 context window（真实 tokenizer 或近似估算均可）。
 
 GoatChain 的核心协议定义在：
+
 - `apps/goatchain/src/core/acp.ts`
 - `apps/goatchain/src/core/model.ts`
 - `apps/goatchain/src/core/store.ts`
@@ -118,23 +149,27 @@ DOM 事件 -> EventManager -> HitTest -> Vue 组件事件回调
 
 ```ts
 type Style = {
-  fg?: string; bg?: string;
-  bold?: boolean; dim?: boolean; italic?: boolean;
-  underline?: boolean; inverse?: boolean;
-};
+  fg?: string
+  bg?: string
+  bold?: boolean
+  dim?: boolean
+  italic?: boolean
+  underline?: boolean
+  inverse?: boolean
+}
 
 type Cell = {
-  ch: string;
-  style: Style;
-  width: 1 | 2; // 宽字符支持
-};
+  ch: string
+  style: Style
+  width: 1 | 2 // 宽字符支持
+}
 
 type Buffer = {
-  rows: Cell[][];
-  cols: number;
-  rowsCount: number;
-  dirtyRows: boolean[];
-};
+  rows: Cell[][]
+  cols: number
+  rowsCount: number
+  dirtyRows: boolean[]
+}
 ```
 
 ## 终端语义范围（初版约束）
@@ -155,18 +190,25 @@ type Buffer = {
 
 ```ts
 interface Terminal {
-  resize(cols: number, rows: number): void;
-  clear(x?: number, y?: number, w?: number, h?: number): void;
-  write(text: string, opts?: { x?: number; y?: number; style?: Style }): void;
-  writeAnsi(text: string, opts?: { x?: number; y?: number }): void;
-  put(x: number, y: number, ch: string, style?: Style): void;
-  fill(x: number, y: number, w: number, h: number, ch?: string, style?: Style): void;
-  scroll(lines: number): void;
-  setCursor(x: number, y: number, visible?: boolean): void;
-  batch(fn: () => void): void;
-  commit(): void;
-  on(event: TerminalEvent, cb: (e: TerminalEventPayload) => void): () => void;
-  dispose(): void;
+  resize(cols: number, rows: number): void
+  clear(x?: number, y?: number, w?: number, h?: number): void
+  write(text: string, opts?: { x?: number; y?: number; style?: Style }): void
+  writeAnsi(text: string, opts?: { x?: number; y?: number }): void
+  put(x: number, y: number, ch: string, style?: Style): void
+  fill(
+    x: number,
+    y: number,
+    w: number,
+    h: number,
+    ch?: string,
+    style?: Style,
+  ): void
+  scroll(lines: number): void
+  setCursor(x: number, y: number, visible?: boolean): void
+  batch(fn: () => void): void
+  commit(): void
+  on(event: TerminalEvent, cb: (e: TerminalEventPayload) => void): () => void
+  dispose(): void
 }
 ```
 
@@ -178,52 +220,67 @@ interface Terminal {
 
 ```ts
 type TerminalEvent =
-  | 'click' | 'dblclick' | 'contextmenu'
-  | 'pointerdown' | 'pointerup' | 'pointermove' | 'pointerenter' | 'pointerleave'
-  | 'mousedown' | 'mouseup' | 'mousemove' | 'mouseenter' | 'mouseleave'
+  | 'click'
+  | 'dblclick'
+  | 'contextmenu'
+  | 'pointerdown'
+  | 'pointerup'
+  | 'pointermove'
+  | 'pointerenter'
+  | 'pointerleave'
+  | 'mousedown'
+  | 'mouseup'
+  | 'mousemove'
+  | 'mouseenter'
+  | 'mouseleave'
   | 'wheel'
-  | 'keydown' | 'keyup'
-  | 'input' | 'change'
-  | 'compositionstart' | 'compositionupdate' | 'compositionend'
-  | 'focus' | 'blur'
-  | 'drag';
+  | 'keydown'
+  | 'keyup'
+  | 'input'
+  | 'change'
+  | 'compositionstart'
+  | 'compositionupdate'
+  | 'compositionend'
+  | 'focus'
+  | 'blur'
+  | 'drag'
 
 type TerminalBaseEvent = {
-  type: TerminalEvent;
-  target: TerminalNode | null;
-  currentTarget: TerminalNode | null;
-  bubbles: boolean;
-  cancelable: boolean;
-  defaultPrevented: boolean;
-  timeStamp: number;
-  stopPropagation(): void;
-  preventDefault(): void;
-  nativeEvent?: Event;
-};
+  type: TerminalEvent
+  target: TerminalNode | null
+  currentTarget: TerminalNode | null
+  bubbles: boolean
+  cancelable: boolean
+  defaultPrevented: boolean
+  timeStamp: number
+  stopPropagation(): void
+  preventDefault(): void
+  nativeEvent?: Event
+}
 
 type TerminalPointerEvent = TerminalBaseEvent & {
-  clientX: number;
-  clientY: number;
-  cellX: number;
-  cellY: number;
-  button?: number;
-  buttons?: number;
-  ctrlKey?: boolean;
-  shiftKey?: boolean;
-  altKey?: boolean;
-  metaKey?: boolean;
-  deltaY?: number;
-};
+  clientX: number
+  clientY: number
+  cellX: number
+  cellY: number
+  button?: number
+  buttons?: number
+  ctrlKey?: boolean
+  shiftKey?: boolean
+  altKey?: boolean
+  metaKey?: boolean
+  deltaY?: number
+}
 
 type TerminalKeyboardEvent = TerminalBaseEvent & {
-  key: string;
-  code: string;
-  ctrlKey?: boolean;
-  shiftKey?: boolean;
-  altKey?: boolean;
-  metaKey?: boolean;
-  repeat?: boolean;
-};
+  key: string
+  code: string
+  ctrlKey?: boolean
+  shiftKey?: boolean
+  altKey?: boolean
+  metaKey?: boolean
+  repeat?: boolean
+}
 ```
 
 ## 事件派发与冒泡（建议）
@@ -308,15 +365,19 @@ const { mount } = useTerminalRuntime()
 function onInputCommit(value: string) {
   if (value.startsWith('/')) {
     mount(TSelect, {
-      x: 2, y: 10, w: 20, h: 6,
+      x: 2,
+      y: 10,
+      w: 20,
+      h: 6,
       options: ['a', 'b', 'c'],
-      onSelect: v => console.log(v),
+      onSelect: (v) => console.log(v),
     })
   }
 }
 ```
 
 约束：
+
 - 动态插入的组件必须显式提供布局 (x/y/w/h) 或依赖父容器布局
 - 插入/卸载会触发局部重绘，不影响其它区域
 
@@ -328,10 +389,10 @@ function onInputCommit(value: string) {
 
 ```ts
 type TerminalHandle = {
-  update: (props: Record<string, unknown>) => void;
-  move: (x: number, y: number) => void;
-  unmount: () => void;
-};
+  update: (props: Record<string, unknown>) => void
+  move: (x: number, y: number) => void
+  unmount: () => void
+}
 ```
 
 ## 组件生命周期与资源管理（建议）
@@ -341,6 +402,7 @@ type TerminalHandle = {
 - 卸载：释放事件节点、清理 buffer 区域、移除焦点/输入绑定
 
 对 `v-if`/`v-show` 的行为约定：
+
 - `v-if`: 触发卸载与资源释放（清 buffer、解绑事件）
 - `v-show`: 仅隐藏渲染，保留节点与状态（不解绑事件）
 
@@ -399,6 +461,7 @@ type TerminalHandle = {
 ## 带边框 Box 的内容保护
 
 当 `TBox` 带边框时，需要保护内容区域不被破坏：
+
 - 外框占 1 cell 边距，内容区域为 `(x+1, y+1, w-2, h-2)`
 - 内容写入必须裁剪到内容区域，避免覆盖边框
 - 当内容超出时，支持 `overflow: clip | scroll`
@@ -425,7 +488,7 @@ type TerminalHandle = {
 ## ANSI 支持
 
 - `writeAnsi()` 接受 ANSI 字符串，解析后写入 Buffer
-- 可先实现轻量解析器，后续切换到 `ansi-styles`/`ansis`
+- 可先实现轻量解析器，后续切换到更完整的 ANSI 样式库（如 `ansis`）
 
 ## 文本分段与宽字符策略（建议）