u

code/g3soft-libs/CODEBUDDY.md

@@ -8,8 +8,7 @@ G3Soft frontend infrastructure — a pnpm monorepo holding a self-built **Vue 3
 
 - `packages/ui` (`@g3soft/ui`) — component library, published to a private npm registry. One directory per component under `src/<name>/`.
 - `packages/tokens` (`@g3soft/tokens`) — design tokens as plain CSS (`--g3-*` variables), shared by the library and the docs site.
-- `docs` (`@g3soft/docs`) — Docus/Nuxt docs site. `private: true`, never published.
-- `scripts/gen-api.mjs` — generates component API data from source.
+- `docs` (`@g3soft/docs`) — Docus/Nuxt docs site. `private: true`, never published. 组件文档（示例 + API）全部手写在 `docs/content/ui/<分类>/<组件>.md`。
 
 Requires Node >= 20.19 and pnpm 11 (see `packageManager` in root `package.json`).
 
@@ -22,8 +21,6 @@ pnpm dev            # start docs site (http://localhost:3000); live-reloads pack
 pnpm build          # build all packages under packages/** (component lib -> dist)
 pnpm build:docs     # build docs static site -> docs/.output/public
 pnpm preview:docs   # preview the built docs site
-
-pnpm gen:api        # regenerate docs/data/api/*.json from component source (REQUIRED after changing props/events/slots)
 ```
 
 Deploying docs to a subpath:
@@ -46,7 +43,7 @@ pnpm release        # build + publish to the private registry
 
 ### Running a single component's checks
 
-There is no per-component test/lint script. The closest equivalent is `pnpm --filter @g3soft/ui build` (runs `vite build`, which type-checks declarations via `vite-plugin-dts`), and `pnpm gen:api` to verify the docgen extraction still parses a component.
+There is no per-component test/lint script. The closest equivalent is `pnpm --filter @g3soft/ui build` (runs `vite build`, which type-checks declarations via `vite-plugin-dts`).
 
 ## Architecture
 
@@ -78,13 +75,18 @@ Nuxt-related deps appear **only** in `docs/package.json`; the library's dependen
 - `vite.resolve.alias` points `@g3soft/ui` and `@g3soft/tokens` **directly at `packages/*/src`**, so the docs site can develop against the library without building it. Editing `packages/ui` hot-reloads the docs immediately.
 - `site.url` is required (sitemap, llms.txt, OG images) — missing it breaks prerender with a 500.
 - Deploy base path comes from `NUXT_APP_BASE_URL` (Nuxt's env override for `app.baseURL`), never hardcoded.
-- `docs/app/components/content/` holds components usable directly inside Markdown: `Demo.vue` (renders a runnable example + source) and `ApiTable.vue` (renders the generated API tables).
+- `docs/app/components/content/` holds components usable directly inside Markdown: `Demo.vue` (renders a runnable example + source).
 
-### API generation pipeline
+### 组件文档写作约定（手写，不生成）
 
-`scripts/gen-api.mjs` uses `vue-docgen-api` to parse every `.vue` under `packages/ui/src`, extracts props/events/slots and their JSDoc comments, and writes `docs/data/api/<dirName>.json`. `ApiTable.vue` reads those JSON files by component name.
+组件文档在 `docs/content/ui/<分类>/<组件>.md` 里**手写全文**：正文说明 + `:::demo{name="<组件>/<示例>"}:::` + 手写的 API 表格（Props / Events / Slots / Exposed / 类型定义 / 样式变量 / 实现说明）。
 
-Consequence: **API tables are generated from source and must never be hand-written.** The component directory name is the doc key (`src/button/Button.vue` → `button`). After any change to a component's props/events/slots, run `pnpm gen:api`.
+约定：
+
+- **一个功能一个示例**：示例文件按功能命名（`basic` / `variant` / `loading` / `remote` …），不要写「大杂烩」示例；示例内用注释说明「这个功能怎么用」。
+- 示例里**不要在 setup 顶层使用 `window` / `document`**（文档站是 SSR 预渲染的），需要浏览器 API 时放到 `onMounted`。
+- 改组件的 props / events / slots 时，同步改对应 md 的 API 表格——没有生成器兜底，忘改就是文档错误。
+- 分类目录：`1.usage` / `2.general` / `3.form` / `4.overlay` / `5.feedback` / `6.data`，每个分类有 `.navigation.yml`。
 
 ### Design tokens (`packages/tokens`)
 
@@ -100,10 +102,65 @@ Consequence: **API tables are generated from source and must never be hand-writt
 
 - **No `scoped` in component `<style>`.** Isolate with the `g3-` prefix + BEM naming so consumers can override.
 - **Never hardcode colors or sizes** — always reference `--g3-*` variables, and give every variable a fallback value (e.g. `var(--g3-color-primary, #18181b)`) so components render correctly even when `@g3soft/tokens` is not loaded.
-- **Component API docs are generated, not authored** — changes to props/events/slots require `pnpm gen:api`.
-- **Examples** live at `docs/examples/<component>/<example>.vue` and are referenced in Markdown as `::demo{name="<component>/<example>"}`. API tables use `<ApiTable name="<component>" />`.
+- **组件 API 文档手写**：改 props/events/slots 时同步更新 `docs/content/ui/**/<组件>.md` 的 API 表格（没有自动生成器）。
+- **Examples** live at `docs/examples/<component>/<example>.vue` and are referenced in Markdown as `::demo{name="<component>/<example>"}`. 一个功能一个示例；API 表格直接写在 md 里。
 - New components get a `src/<name>/` directory (component `.vue`, `types.ts`, `index.ts`) and must be re-exported from `src/index.ts`.
 
+## 浮层陷阱（踩过，勿重犯）
+
+**`<component :is="X">` 的 `X` 必须是稳定引用。** `useUnwrappedTrigger` 返回的 `InjectedTrigger` 是一个恒定对象（内容由 render 内部读 computed）。早期实现写成 `computed(() => ({ render: () => vnode }))`，每次依赖变化都产出新组件对象，而 Vue patch 用 `n1.type === n2.type` 判断能否复用 —— 对象身份变了就卸载旧组件、挂载新组件。unwrapped 模式的触发器常常是 `<input>`（Select / DatePicker / Dropdown），DOM 一重建焦点就丢、随即派发 focusout，focusout 处理器又改状态触发下一次重算：**重建 → 失焦 → 改状态 → 重建**自我驱动，主线程被打满，表现为「点击 Select 后整机卡死」。规矩：`:is` 的值不能是每次求值都新建的对象/函数。
+
+**不要在 ResizeObserver 回调链里无谓写样式。** `useFloating` 观察浮层自身用于跟随重算，写 `min-width` 前要先比较旧值（见 `updatePosition`），否则样式写入与观察回调会互相喂数据形成反馈环。
+
+**`v-if` 不要和 `v-for` 写在同一元素上。** Vue 3 里 `v-if` 优先级更高，会在 `v-for` 建立作用域之前求值，模板中引用的循环变量此时是 `undefined`（实测直接抛 `Cannot read properties of undefined (reading 'key')` 打断整个渲染）。把 `v-for` 提到外层 `<template>` 上。
+
+**组件子节点是 `{ default: () => [...] }`，不是纯文本。** 声明式容器组件（如要收集 `<G3DropdownItem>编辑</G3DropdownItem>` 文案的 Dropdown）不能只读 `label` prop，也不能假设 children 是字符串：编译器把组件子节点编译成插槽对象，文本藏在 VNode 里。取值要走「字符串 → 数组 → isVNode 递归 → default() 工厂」这条链。
+
+**改 `types.ts` 里的 props 类型后要重启 dev server。** 运行时 props 声明由编译器解析 `defineProps<Props>()` 的 `types.ts` 生成，Vite 会缓存这一步：把必填改成可选后热更不生效，表现是「类型已改但仍报 Missing required prop」。硬刷新不够，重启 `pnpm dev` 才会重新解析。
+
+## 测试与自检（含 AI 使用方式）
+
+三层，按「跑得多快 → 能拦什么」递进，命令都在仓库根执行：
+
+| 层 | 命令 | 范围 |
+|---|---|---|
+| L1 纯函数 + L2 组件 | `pnpm test` | vitest + happy-dom：日期/校验/定位/分层/树算法 + 组件契约，秒级 |
+| L3 真浏览器 | `pnpm test:e2e` | Playwright：弹层层级、命中测试、拖拽、焦点陷阱、DOM 重建检测 |
+| 一把梭 | `pnpm verify` | tokens build → ui build → 单测 → E2E |
+
+- 单测与源码 colocate：`src/**/*.test.ts`；组件测试补丁在 `packages/ui/tests/setup.ts`（happy-dom 缺 ResizeObserver / matchMedia / PointerEvent）。
+- `packages/ui/vitest.config.ts` **刻意不复用** `vite.config.ts`（那份带 lib 构建与 dts 插件）；测试里把 `vue` alias 到完整版，才支持字符串模板挂载。
+- E2E 宿主页面是 `packages/ui/playground`：**新增可交互元素必须挂 `data-testid`**，用例只按 testid 找元素（不依赖文案与结构）。
+- 面向工具/AI 的产物：`packages/ui/test-results/unit.json`、`test-results/e2e.json`；失败自动留 screenshot / trace 于同目录。
+- 单跑一个用例：`pnpm --filter @g3soft/ui exec vitest run src/date/date-utils.test.ts`、`pnpm --filter @g3soft/ui exec playwright test e2e/layer.spec.ts`
+- 手测与探索：`pnpm playground`（http://localhost:5200），可直接用浏览器工具看真实渲染。
+
+**跑 E2E 前先清 `packages/ui/test-results`。** Playwright 启动时会递归删除上次产物，而 IDE 的 safe-delete 守卫会拦截 node 进程的批量删除，直接报 `[safe-delete][SAFE_DELETE_BULK_GUARD_ERROR]` 让整轮测试跑不起来。用 PowerShell 清理（不受该守卫限制）：`Remove-Item packages/ui/test-results -Recurse -Force`。
+
+**E2E 里用 `page.mouse.*` 之前先 `scrollIntoViewIfNeeded()`。** mouse 事件按视口坐标派发，元素在视口外时事件会落到别的元素上，表现为「拖拽/点击完全没反应」，极易误判成组件 bug；同理，`force: true` 只是跳过可点击性检查，事件仍按坐标派发，被遮罩盖住的按钮要点它请用 `dispatchEvent('click')`。
+
+**组件 vnode 收集要处理三种形态**：`label` 这类 camelCase prop、`item-key` 这类 **kebab-case**（`vnode.props` 里保留原样）、以及 `<Comp danger />` 这类**空值布尔属性**（值是 `''` 而非 `true`，用 `if (raw.x)` 会误判为 false，必须 `raw.x != null && raw.x !== false`）。Dropdown / Tabs 都因此踩过坑。
+
+**必须放 E2E 的行为**：层叠上下文与命中测试（`elementFromPoint`）、弹层定位与翻转、拖拽 / 缩放、焦点陷阱、DOM 重建计数、跨组件层级比较。happy-dom 没有布局引擎，这类断言在单测里只会「假装通过」。
+
+**多方向 / 多尺寸的组件，每个方向都要进回归。** Drawer 只验过默认的 `right`，「上下方向宽度不是 100%」就潜伏了很久：容器用 flex 的 `justify-content` / `align-items` 做吸附时，两条轴各只管一个方向，上下面板在主轴（水平）方向没有约束，宽度缩到内容宽。现在按方向定边（上下 `left/right: 0`、左右 `top/bottom: 0`，与 fms 一致），并由 `e2e/drawer.spec.ts` 锁住四方向的几何。
+
+**组件结构元素要显式重置 `margin` / `padding` / `border`。** Drawer 面板是 `<section>`（与 fms 一致），内部还有 `<header>` / `<footer>`，宿主页面里任何 `section { margin: 16px }` 这类**元素选择器**都会命中：实测 `margin-bottom: 16px` 会把「定边撑开」的高度吃掉 16px（720 → 704），表现为「抽屉撑不满」；border 在 border-box 下同样吃高度。组件用类选择器声明这些值为 0（特异性高于元素选择器）即可盖住。同理，**playground / 文档站自己的容器样式要用子选择器**（`.page > section`），不要写裸 `section` —— 这个坑就是这么踩到的（见 `playground/index.html` 注释）。
+
+**CSS 变量写进 `color-mix()` 必须包 `var()`。** `color-mix(in srgb, --g3-color-primary 12%, transparent)` 里少了 `var()`，整个函数解析失败、变量值为空 —— 表现是「树/树节点选中没有背景色」这种看起来像 JS 没生效的样式 bug。SCSS 里要写 `var(#{fn.css-var('color-primary')})`。**并且改完 `packages/tokens/src/scss` 必须 `pnpm --filter @g3soft/tokens build`**：`import '@g3soft/tokens'` 加载的是 `dist/index.css`，只改 src 不重新构建，页面拿到的还是旧值。
+
+**过渡不要包 `width` / `height`；首次定位前不要开过渡。** Segmented 的滑块一度把宽高也放进 `transition`：首次测量时它正从 `100%` 收缩动画中，肉眼是一闪，断言读到的是 104px 而不是 38px。现在宽高瞬时生效、只过渡 `transform` / `opacity`（与 fms 一致），并且首次定位在 `transition: none` 下完成（`thumbReady` 下一帧才置位），否则滑块会从左上角滑到选中项。
+
+**只固定该固定的东西。** Splitter 拖拽曾把**所有**面板都写成 px：那些原本靠 flex 自动分配的面板会被一并冻结成「按下那一刻的实测宽度」，表现为「一拖就整体跳一下」。只更新分隔条两侧的两块（`applySizes(sizes, index)`）。
+
+**Tree 的叶子缩进占位按兄弟判定。** 同一批兄弟里存在可展开节点时，叶子才渲染等宽占位（`placeholderKeys`）；整层都是叶子还空一格就是白占位置。懒加载下「未加载过」的节点算可展开。
+
+**给 Teleport / 多根组件挂 `data-testid` 会触发 Vue 的 attrs 继承警告**，挂在包裹 `<div>` 上（E2E 用 `getByTestId` 定位包裹层即可）。删掉组件上的 testid 前先确认没有 E2E 依赖它。
+
+**E2E 里这几个写法会「假失败」**：① hover 后立刻 `evaluate` 读 `border-color`，读到的是过渡中间值（215 而非 24）—— 用会重试的 `toHaveCSS`；② 跨实例取 locator（页面上有多组同组件时 `.first()` 可能来自别的实例）—— 先锁定父容器再 `locator`；③ `page.mouse` 用视口坐标且**不会自动滚动**，元素在视口外时拖拽直接落空（`scrollIntoViewIfNeeded` 先滚）；④ `offsetWidth` 是整数、`boundingBox()` 是亚像素，尺寸比较要留 1px 容差。
+
+**不要并行跑 `pnpm build` 与 `pnpm test:e2e`。** 两者都会拉起 Vite 并抢占 `packages/ui/dist`，`vite:prepare-out-dir` 会失败报「Build failed with 1 error」，而单独跑又是好的，极易误判成代码问题。
+
 ## Version constraints (do not relax)
 
 `pnpm-workspace.yaml` documents these deliberately — read it before touching dependency versions: