@phoenix-wing/kt-codegen 0.4.2 → 0.5.0

package/doc/KtCodegenTable/345/270/203/345/261/200/344/270/216/346/212/230/345/217/240/345/245/221/347/272/246.md

@@ -0,0 +1,106 @@
+# KtCodegenTable 布局与折叠契约
+
+状态：current
+
+Owner：@phoenix-wing/kt-codegen maintainers
+
+适用版本：0.4.x
+
+最后核验：2026-07-18
+
+## 目标与责任边界
+
+`KtCodegenTable` 同时支持“组件拥有可用高度”和“页面拥有唯一纵向滚动”两种宿主，但不感知 VS Code、Vue、路由或 Host session。表格数据仍只由 `setData()`/`getData()` 与既有 change/dirty 事件交换；布局与折叠是本地展示状态，不进入 `KtCodegenTableData`，也不改变 `documentRevision`。
+
+```text
+Host / Page shell
+├─ layout、collapsible、collapsed（展示状态）
+└─ KtCodegenTable
+   ├─ Header
+   │  ├─ 普通标题或原生 disclosure button
+   │  └─ 既有九个表格工具（始终保留）
+   ├─ table shell（收起时 hidden）
+   └─ statusbar（收起时 hidden）
+```
+
+## 公共 API
+
+| 名称 | 类型 | 默认值 | 契约 |
+|---|---|---|---|
+| `layout` / `layout` attribute | `"contained" \| "page"` | `"contained"` | property 与 attribute 双向反射；未知运行时值归一化为 `contained` |
+| `collapsible` / `collapsible` attribute | `boolean` | `false` | 存在时把 Header 非工具区切换为原生 disclosure button |
+| `collapsed` / `collapsed` attribute | `boolean` | `false` | 保留宿主折叠偏好；只有 `collapsible && collapsed` 才真正隐藏内容 |
+| `kt-codegen-table-collapse-change` | `CustomEvent<{ collapsed: boolean }>` | — | 只由用户点击发出，`bubbles: true`、`composed: true` |
+
+宿主可以按 property 或 attribute 使用同一契约：
+
+```ts
+import type { KtCodegenTable } from "@phoenix-wing/kt-codegen/table";
+
+const table = document.querySelector<KtCodegenTable>("kt-codegen-table")!;
+table.layout = "page";
+table.collapsible = true;
+table.collapsed = false;
+```
+
+```html
+<kt-codegen-table layout="page" collapsible></kt-codegen-table>
+```
+
+程序执行 `table.collapsed = true`、`setAttribute("collapsed", "")` 或恢复持久化偏好时必须保持静默：不发 `kt-codegen-table-collapse-change`，也不发 `kt-codegen-table-change` / `kt-codegen-table-dirty-change`。只有 disclosure button 的用户动作发折叠事件，宿主若需持久化 UI 偏好应监听这一事件。
+
+## 两种布局
+
+### contained（兼容默认）
+
+- Host 提供高度；组件继续使用 `height: 100%` 与兼容的 `min-height`。
+- table shell 保持 `overflow: auto`，长行和长表都在组件内部滚动。
+- 既有 sticky 表头、sticky 行号、状态栏与工具栏行为不变。
+
+### page（页面自然高度）
+
+- Host 高度为 `auto`，table shell 按表头和所有数据行自然撑高。
+- table shell 使用 `overflow-x: auto; overflow-y: hidden`：宽表只产生横向滚动，纵向由外层 Page shell 统一承担。
+- 空表提示从绝对定位改为文档流内容，表头、提示和状态栏共同决定自然高度，不被裁切。
+- Page shell 不应再给组件设置固定 `vh`、内部纵向 `overflow` 或穿透 Shadow DOM 修改高度。
+
+## 折叠、工具与无障碍
+
+- 未设置 `collapsible` 时显示普通“参数表”标题，不暴露无动作的箭头或 button。
+- 设置 `collapsible` 后，Header 非工具区是原生 `<button type="button">`；九个既有工具按钮仍是相邻兄弟节点，收起后可继续操作。
+- disclosure button 维护 `aria-expanded`、`aria-controls`、焦点框和“展开参数表”/“收起参数表”动态标签。
+- 收起只设置 table shell 与 statusbar 的 `hidden`，不销毁表格、选择、剪贴板或 dirty 状态。
+- 若程序或用户收起时焦点位于将隐藏的 shell/statusbar，焦点先移到 disclosure button，避免焦点遗留在不可见控件。
+
+## 验证
+
+自动门禁：
+
+```bash
+pnpm --filter @phoenix-wing/kt-codegen test
+pnpm --filter @phoenix-wing/kt-codegen typecheck
+pnpm --filter @phoenix-wing/kt-codegen build
+pnpm docs:check
+```
+
+`table-view-model.test.ts` 冻结归一化与 disclosure 纯投影；`table-dom.test.ts` 实例化组件并验证点击、属性反射、事件静默、工具保留和焦点转移；`table-style.test.ts` 冻结 contained/page 与空表样式责任。
+
+真实浏览器夹具在构建后使用：
+
+```text
+packages/kt-codegen/test-fixtures/table-runtime.html?layout=page&collapsible
+packages/kt-codegen/test-fixtures/table-runtime.html?layout=page&collapsible&empty
+packages/kt-codegen/test-fixtures/table-runtime.html?layout=page&collapsible&collapsed
+```
+
+夹具公开 `window.__wingTableMetrics()`，用于核对 page 模式 shell 的 `clientHeight === scrollHeight`、横向溢出、页面总高、工具数量、动态 ARIA 与用户事件计数。真实 VS Code 主题、Registry 消费升级和产品 Host 接线属于后续消费者验收；本契约本身不修改包版本、发布标签或 Registry 状态。
+
+2026-07-18 使用构建后的真实 `dist/table/index.js` 在 Chrome 完成以下尺寸点检，控制台无错误：
+
+| 场景 | Page client/scroll | Host client/scroll | Shell 高 client/scroll | Shell 宽 client/scroll | computed overflow x/y |
+|---|---:|---:|---:|---:|---|
+| page，1000×650，24 行 | 650 / 963 | 917 / 917 | 850 / 850 | 720 / 1872 | `auto` / `hidden` |
+| page，560×420，空表 | 420 / 420 | 201 / 201 | 134 / 134 | 528 / 1872 | `auto` / `hidden` |
+| contained，360×260，24 行 | — | 260 / 260 | 193 / 850 | 360 / 1872 | `auto` / `auto` |
+
+空表提示实际高度约 68px，完整位于 shell 内。page 长表点击“收起参数表”后 Host 高度变为 38px，shell/statusbar 均 hidden，九个工具按钮仍保留，`aria-expanded` 变为 `false`、标签变为“展开参数表”，夹具只收到一次 `{ collapsed: true }` 用户事件。

package/doc//350/207/252/345/212/250/344/273/243/347/240/201/346/240/207/350/256/260/346/211/253/346/217/217.md

@@ -56,7 +56,7 @@ Renderer 后续产生 artifact 时，可使用区域的绝对偏移建立候选
 - Start 行从最后一个 `//` 之前提取的 `linePrefix`，兼容旧 VB `_prefix` 行为；
 - LF、CRLF 或末行无换行时仍可直接对原始字符串切片验证的范围。
 
-扫描只把“当前 Param 中存在的 `NameSuffix` + 本次 block key 白名单”作为候选。没有打开当前块时，其他类和未请求 block 的合法标记保持原样，允许一个文件中存在多套参数生成代码。
+扫描只把“当前 Param 中存在的 `NameSuffix` + 本次 block key 白名单”作为候选。没有打开当前块时，其他类和未请求 block 的合法标记保持原样，允许一个文件中存在多套参数生成代码。任何语法完整 marker 都是同级边界，但未选择的正常 Start/End 对不会因此产生诊断。
 
 ## 比旧实现更严格的安全检查
 
@@ -64,21 +64,20 @@ Renderer 后续产生 artifact 时，可使用区域的绝对偏移建立候选
 
 | 诊断代码 | 含义 | 结果 |
 | --- | --- | --- |
-| `marker.orphan-end` | End 前没有对应 Start | error，不产生区域 |
-| `marker.missing-end` | 文件结束仍未找到对应 End | error，不产生区域 |
-| `marker.nested-start` | 一个块未结束又出现 Start | error，涉及块不产生区域 |
-| `marker.mismatched-end` | End 的类身份或 block key 与 Start 不同 | error，涉及块不产生区域 |
+| `marker.missing-end` | 文件结束或下一条语法完整 marker 前仍未找到对应 End | error；上一块不产生区域，边界行写入 message，并清空旧状态 |
+| `marker.orphan-end` | End 前没有对应 Start，或错配 End 已与旧 Start 分开诊断 | error；End 不产生区域，后续块仍可恢复 |
 | `marker.ambiguous-line` | 同一行同时含 Start 和 End | error |
 | `marker.malformed` | 标记固定文本与类身份之间格式错误 | error |
-| `marker.missing-class-id` | block key 前没有类身份 | error |
-| `marker.unknown-block` | 不属于归档32块的控制标记 | warning，保留原文 |
+| `marker.malformed-payload` | 缺少类身份或 block 区分词 | error |
 
-这些检查不自动修复源码。UI 可以用文件、行、列定位提示用户；只有标记结构无 error、目标 Renderer 已迁移并产生 artifact 时，计划才可能进入 Apply。
+控制块严格同级、不允许嵌套。遇到下一 Start 时，旧 Start 只报一次 `missing-end`，随后把新 Start 作为新块起点；遇到错配 End 时，旧 Start 报 `missing-end`，该 End 独立报 `orphan-end`，旧状态立即清空。扫描器绝不会把边界 marker 当成缺失 End，也不会把两个 marker 之间的手写代码纳入替换区域。
+
+不属于归档32块的语法完整控制标记不是错误，扫描器静默保留原文；它只在已有已选块打开时充当边界。上述检查不自动修复源码。UI 可以用文件、行、列定位提示用户；只有标记结构无 error、目标 Renderer 已迁移并产生 artifact 时，计划才可能进入 Apply。
 
 ## 当前阶段限制
 
 - 已完成旧标记构造、扫描、配对、偏移和 Analyze Plan 接口；
-- 已覆盖多区域、LF/CRLF、孤立、缺失、嵌套、错配和其他类共存测试；
+- 已覆盖多区域、LF/CRLF、孤立、连续缺失、下一 marker 恢复、错配 End 独立化和其他类共存测试；
 - 普通 C++ Parameter、CAA 与 Qt 的32块归档旧生成能力均可产生关联 `regionId` 的 artifact；
 - `plan.canApply` 只表示计划满足基本条件，本包仍不执行真实写回；
 - 不在本原型中实现真实文件写入，也不修改 Phoenix Wing、`kt-auto-code` 或 `phoenix-desk-tools`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phoenix-wing/kt-codegen",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "CAA、Qt 与普通 C++ 的参数驱动代码生成核心",
   "type": "module",
   "sideEffects": false,
@@ -23,6 +23,10 @@
       "types": "./dist/table/index.d.ts",
       "import": "./dist/table/index.js"
     },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "import": "./dist/ui/index.js"
+    },
     "./fixtures/*": "./tests/fixtures/contracts/*"
   },
   "files": [