@jc-times/business-ui 0.2.43

package/docs/release.md

@@ -0,0 +1,32 @@
+# 内部发布流程
+
+## 发布位置与权限
+
+- Git 仓库：`https://github.com/jc-times/business-ui`
+- npm registry：GitHub Packages，`https://npm.pkg.github.com`
+- npm 包：`@jc-times/business-ui`
+- Release workflow 仅授予 `contents: read` 和 `packages: write`。
+- 发布使用 GitHub Actions 自动提供的仓库级 `GITHUB_TOKEN`，无需创建或保存长期 `NPM_TOKEN`。
+
+仓库不会保存令牌或带令牌的 `.npmrc`。发布脚本只在执行期间创建临时配置，并在成功或失败后删除。消费私有包所需的 `read:packages` 凭据由各消费仓库或开发者环境分别管理。
+
+## 发布规则
+
+1. 更新 `package.json` 版本和 `CHANGELOG.md`。
+2. 合并到 `main`，等待 CI 的类型检查、测试、构建和打包全部通过。
+3. 在已验证的提交上创建并推送注释标签 `v<package.version>`。
+4. Release workflow 再次执行完整验证，校验标签与包版本完全一致后发布。
+5. 消费项目以精确版本安装，并在各自仓库提交 lockfile；不使用 `latest`、范围版本或源码路径。
+
+`workflow_dispatch` 只用于重试同一标签的失败任务；普通分支或无匹配标签的提交会被发布脚本拒绝。
+
+## 本地安全演练
+
+不设置真实令牌时，可验证拒绝路径：
+
+```powershell
+$env:NPM_REGISTRY_URL = "https://npm.pkg.github.com"
+pnpm publish:release
+```
+
+脚本应在发布前因缺少 `NPM_TOKEN` 或标签不匹配而退出。不要把真实令牌写入命令历史、仓库文件或文档。

package/docs/viewport-qa.md

@@ -0,0 +1,99 @@
+# 发布前多视口验收
+
+运行 `pnpm dev:matrix -- --host 127.0.0.1`，在受控浏览器中检查以下矩阵：
+
+| 档位 | 视口 | 核心检查 |
+| --- | --- | --- |
+| 手机 | 390 × 844 | 无水平溢出；按钮与表单可触达；分页正确换行；弹窗占满可用宽度 |
+| 小屏手机 | 320 × 480 | 弹窗固定头尾；正文可独立滚动；底栏操作不被正文吞入 |
+| 平板 | 768 × 1024 | 表单栅格不拥挤；日期浮层不越界；Tabs 可横向滚动 |
+| 桌面 | 1440 × 900 | 内容宽度、按钮组和分页布局合理；弹窗居中且内容可滚动 |
+| 短横屏 | 844 × 390 | 弹窗留有视口边距；头部紧凑；正文滚动且固定底栏始终可见 |
+
+每档需检查默认页及弹窗页，并确认：
+
+- Tab 焦点顺序可预测，焦点环清晰。
+- `Escape` 关闭弹窗并恢复触发按钮焦点。
+- 日期选择器保持在视口内，可选择、清除并用 `Escape` 关闭。
+- 禁用原因可通过键盘聚焦查看。
+- Alert 的操作与关闭按钮在手机端正确换行；EmptyState 和 Skeleton 不挤压容器。
+- PageHeader 与 SectionCard 的说明和 actions 在窄屏正确换行；长标题不造成水平溢出。
+- Badge 五档 tone 和两档 size 可辨识；MetricCard 在四列、两列和单列布局中保持阅读顺序与等高节奏。
+- Tooltip 可由悬停和键盘焦点打开；Popover、Popconfirm 与 Select 在两端均不越界并可用 Escape 关闭。
+- Combobox 与 AutoComplete 可输入、筛选和键盘选择；大列表只渲染可见项。
+- TextInput 的搜索图标、清除按钮及 NumericInput 的单位/百分号与同行控件等高；点击非交互装饰可聚焦，清除按钮可独立操作，错误和禁用外框状态完整。
+- Toast 在手机端贴近底部且左右保留 12px 安全边距；DataTable 只在自身容器内横向滚动。
+- 浏览器控制台无错误。
+
+分段控制器专项：在「表单控件 → 视图切换」及 `e2e/segmented.html` 检查实色/浅底、收缩/等宽、胶囊、纵向、图标和长文字；验证方向键跳过禁用项、组之间互不干扰、焦点环可见，以及粗指针每项至少 44px。自动回归运行 `pnpm exec playwright test e2e/segmented.spec.ts`。
+
+验收结论只记录日期、浏览器、视口和结果，不记录账号、Cookie 或其他会话数据。
+
+## 验收记录
+
+### 2026-09-12 — V2 原生 Headless 页面层候选
+
+- Chromium 桌面/手机查看器 14 项回归通过；原生模式覆盖五档视口，底栏可见、正文可滚动、页面无横向溢出，手机缩放旋转叠层截图目检通过。
+- 验证受控跳页与手动滚动、原生叠层点击、缩放旋转、单页互切、全屏、切换文档与失败恢复；138 项单测、类型和库/矩阵构建通过。未发布；真实多指手势与消费业务印章端到端仍需消费方验收。
+
+### 2026-09-06 — 0.2.13 输入装饰
+
+- 浏览器：Codex 内置 Chromium；桌面验收页实际测得三个装饰组合外框均为 40px、内层 input 为 38px，宽度无溢出。
+- 搜索图标、清除按钮、百分号、货币符号和单位布局与同行 TextInput/SelectInput 对齐；清除按钮点击后输入值清空并按条件移除按钮。
+- 粗指针 44px 外框与内层 input 归零规则由 CSS 契约测试覆盖；类型检查、91 项测试、库构建和视觉矩阵构建通过，控制台无 warning/error。
+
+### 2026-09-05 — 0.2.6 TreeSelect、StructuredAddressInput 与控件高度
+
+- 浏览器：Codex 内置 Chromium。
+- 视口：1440 × 900、390 × 844、320 × 480；桌面双列表单和两档手机单列表单均保持可读。
+- TreeSelect：320px 下使用固定底部候选面板，树层级、当前项、展开状态与 44px 触控高度清晰；修正面板横向滚动后无水平溢出。
+- StructuredAddressInput：桌面三级列并排，390px 下底部面板适配安全区；地区摘要、级联选中、详细地址和数据版本信息均可辨识。
+- 同行控件：TextInput、SelectInput 与 Button 使用显式 40px border-box 默认高度，未再依赖原生 select 的平台内在高度。
+
+### 2026-09-05 — 0.2.6 ModalShell 兼容治理
+
+- 浏览器：Codex 内置 Chromium。
+- 视口：1440 × 900、390 × 844、844 × 390、320 × 480；四档页面均无水平溢出。
+- DOM：`.ui-modal-header`、`.ui-modal-content`、`.ui-modal-footer` 保持面板直接子节点顺序；正文区 `overflow-y:auto` 且存在真实溢出，底栏不在正文中并始终位于视口内。
+- 响应式：桌面弹窗 560px 居中；两档手机全屏；短横屏保留 12px 视口边距、使用 366px 最大高度并压缩头部留白。
+- 透传：验收页的 content ref/role/ARIA/data 契约对应节点正确；控制台无 warning 或 error。
+
+### 2026-09-04 — 0.2.4 候选
+
+- 浏览器：Codex 内置 Chromium 浏览器与 Microsoft Edge headless 截图。
+- 视口：390 × 844、768 × 1024、1440 × 900；三档页面 `scrollWidth` 均等于内容视口宽度，无页面级水平溢出。
+- 新增组件：PageHeader 操作区在手机端改为整行；SectionCard 标题、说明与 actions 正确换行；MetricCard 分别为 1、2、4 列，桌面四卡等高；Badge 五档 tone 与两档 size 可辨识。
+- 语义：页面标题与区域标题保持 `h1` → `h2` 层级，SectionCard 由可见标题命名。
+- 控制台：未发现 warning 或 error。
+
+### 2026-09-04 — 0.2.0 候选
+
+- 浏览器：Codex 内置 Chromium 浏览器。
+- 视口：390 × 844、768 × 1024、1440 × 900。
+- 结果：三档均无水平溢出；表单、按钮组、Tabs 与分页布局正常。
+- 弹窗：手机全屏、桌面 560px 居中；首焦点、Tab 回环、Escape 关闭及触发按钮焦点恢复正常。
+- 日期选择器：手机和平板均保持在视口内，Escape 可关闭。
+- 控制台：未发现 warning 或 error。
+
+数字输入专项：在「表单控件」页检查数量千分位、聚焦取消分组、尾随小数点、Enter/失焦提交；缩放输入聚焦/点击全选；错误提示与禁用态。默认和触屏尺寸应与同行 TextInput 一致，窄屏无横向溢出。消费方既有 bareInput 门禁已覆盖原生数字输入，不新增重复扫描规则；替换本地包装后须缩减基线。
+
+输入装饰专项：在「表单控件」页检查搜索图标、清除按钮、货币符号、金额单位和百分号；桌面组合外框为 40px，粗指针触屏最小 44px。装饰存在与否不应改变标签、帮助、错误或输入值的可访问名称；键盘仍直接进入输入框和清除按钮。
+
+### 2026-09-06 数字输入 0.2.8
+
+- 1440×900、390×844、320×480、768×1024、844×390 的表单页 DOM 边界检查通过，无文档水平溢出；桌面/390px 目检数字、错误和禁用样式一致，输入继承 40px 默认高度。
+- 浏览器确认缩放输入聚焦全选 `1234.56`，输入 `1.005` 回车后显示 `1.01`；数量保留 `1234.` 草稿，失焦后显示 `1,234`。控制台无 warning/error。
+- 本轮新增控件没有修改 CSS；触屏 44px 继续由既有 coarse-pointer 样式契约测试覆盖，未模拟手机软键盘。
+
+
+### 2026-09-11 — SegmentedControl 本地增强
+
+- Chromium 桌面/Pixel 7 模拟：320×480、390×844、768×1024、1440×900、844×390 无页面水平溢出；粗指针全部选项点击高度至少 44px。
+- 原生方向键跳过禁用项、横向/纵向循环选择与独立分组通过；390px 浅底、胶囊、纵向、纯图标、长文字和禁用态截图目检通过。新增 4 项浏览器检查通过，非真实手机验收。
+
+## 2026-09-11 — Cascader 本地接入
+
+- Chromium 桌面与 Pixel 7 模拟，320×480、390×844、768×1024、1440×900、844×390 五档：三级展开无页面横向溢出；窄屏底部面板、44px 触控行、390px/1440px 截图目检通过。
+- 部门父子独立多选、地址路径搜索与叶子选中后详细地址聚焦、弹窗内 portal、键盘选择及 Escape 分层关闭通过。输入占位不与摘要重叠，清空归一与必填搜索未选中由单测覆盖。
+- 新增级联 6 项浏览器测试通过；全量 36 项浏览器、25 文件 133 项单测、类型、库与视觉矩阵构建通过；打包演练包含声明、专题和 MIT 许可。
+- 本地待发布；尚未升级消费项目。触屏测试是浏览器模拟，非真实手机软键盘验收。复测：`pnpm exec playwright test e2e/cascader.spec.ts`。

package/licenses/rc-cascader-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-present react-component
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,163 @@
+{
+  "name": "@jc-times/business-ui",
+  "version": "0.2.43",
+  "packageManager": "pnpm@11.19.0",
+  "description": "Shared accessible business UI components for JC Times applications",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jc-times/business-ui.git"
+  },
+  "homepage": "https://github.com/jc-times/business-ui#readme",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "bin/business-ui-gate.mjs",
+    "AGENTS.md",
+    "docs/agent-guide.md",
+    "docs/api.md",
+    "docs/mrt-poc.md",
+    "docs/cascader.md",
+    "licenses/rc-cascader-MIT.txt",
+    "docs/component-strategy.md",
+    "docs/release.md",
+    "docs/viewport-qa.md",
+    "docs/modal-shell-migration.md",
+    "docs/maturity-migration.md",
+    "README.md",
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md",
+    "docs/document-viewer.md",
+    "docs/document-viewer-v2.md",
+    "docs/file-preparation.md",
+    "docs/data-table.md",
+    "docs/dependencies.md"
+  ],
+  "main": "./dist/business-ui.js",
+  "module": "./dist/business-ui.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    "./amount-format": {
+      "types": "./dist/types/AmountFormat.d.ts",
+      "import": "./dist/amount-format.js"
+    },
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/business-ui.js"
+    },
+    "./chinese-address-regions": {
+      "types": "./dist/types/ChineseAddressRegions.d.ts",
+      "import": "./dist/chinese-address-regions.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./document-viewer": {
+      "types": "./dist/types/DocumentViewer.d.ts",
+      "import": "./dist/document-viewer.js"
+    },
+    "./document-viewer-v2": {
+      "types": "./dist/types/DocumentViewerV2.d.ts",
+      "import": "./dist/document-viewer-v2.js"
+    },
+    "./document-render-budget": {
+      "types": "./dist/types/DocumentRenderBudget.d.ts",
+      "import": "./dist/document-render-budget.js"
+    },
+    "./data-table": {
+      "import": "./dist/data-table.js",
+      "types": "./dist/types/DataTable.d.ts"
+    },
+    "./pdfium-viewer": {
+      "types": "./dist/types/PdfiumViewer.d.ts",
+      "import": "./dist/pdfium-viewer.js"
+    }
+  },
+  "bin": {
+    "business-ui-gate": "./bin/business-ui-gate.mjs"
+  },
+  "scripts": {
+    "dev:cascader": "vite --host 127.0.0.1 --port 4187 --strictPort",
+    "dev:mrt": "vite --config examples/mrt-poc/vite.config.ts",
+    "build:mrt": "vite build --config examples/mrt-poc/vite.config.ts",
+    "test:mrt": "playwright test --config examples/mrt-poc/playwright.config.ts",
+    "build": "vite build && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build:matrix": "vite build --config examples/visual-matrix/vite.config.ts",
+    "dev:matrix": "vite examples/visual-matrix",
+    "test": "vitest run",
+    "test:browser": "playwright test",
+    "typecheck": "tsc --noEmit",
+    "verify": "pnpm typecheck && pnpm test && pnpm build && pnpm test:tree-shaking && pnpm build:matrix",
+    "pack:release": "pnpm verify && pnpm pack",
+    "publish:release": "node scripts/publish-release.mjs",
+    "test:tree-shaking": "node scripts/check-tree-shaking.mjs"
+  },
+  "peerDependencies": {
+    "@embedpdf/react-pdf-viewer": "2.15.0",
+    "lucide-react": ">=0.468.0 <2",
+    "pdfjs-dist": "6.3.289",
+    "react": ">=18 <20",
+    "react-dom": ">=18 <20"
+  },
+  "dependencies": {
+    "@embedpdf/core": "2.15.0",
+    "@embedpdf/engines": "2.15.0",
+    "@embedpdf/plugin-document-manager": "2.15.0",
+    "@embedpdf/plugin-interaction-manager": "2.15.0",
+    "@embedpdf/plugin-render": "2.15.0",
+    "@embedpdf/plugin-rotate": "2.15.0",
+    "@embedpdf/plugin-scroll": "2.15.0",
+    "@embedpdf/plugin-search": "2.15.0",
+    "@embedpdf/plugin-selection": "2.15.0",
+    "@embedpdf/plugin-thumbnail": "2.15.0",
+    "@embedpdf/plugin-viewport": "2.15.0",
+    "@embedpdf/plugin-zoom": "2.15.0",
+    "@emotion/react": "11.14.0",
+    "@emotion/styled": "11.14.1",
+    "@internationalized/date": "3.12.4",
+    "@mui/icons-material": "7.3.11",
+    "@mui/material": "7.3.11",
+    "@mui/x-date-pickers": "9.13.0",
+    "@radix-ui/react-dialog": "1.1.23",
+    "@radix-ui/react-popover": "1.1.23",
+    "@radix-ui/react-select": "2.3.7",
+    "@radix-ui/react-toast": "1.2.23",
+    "@radix-ui/react-tooltip": "1.2.16",
+    "@rc-component/cascader": "1.25.0",
+    "cn-division": "2026.0.1",
+    "material-react-table": "3.2.1",
+    "react-aria-components": "1.21.1"
+  },
+  "devDependencies": {
+    "@embedpdf/react-pdf-viewer": "2.15.0",
+    "@playwright/test": "1.63.0",
+    "@testing-library/jest-dom": "7.0.1",
+    "@testing-library/react": "16.3.3",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "dayjs": "1.11.23",
+    "jsdom": "30.0.1",
+    "lucide-react": "1.45.0",
+    "pdfjs-dist": "6.3.289",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "6.0.3",
+    "vite": "8.3.0",
+    "vitest": "5.0.0"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "@embedpdf/react-pdf-viewer": {
+      "optional": true
+    },
+    "pdfjs-dist": {
+      "optional": true
+    }
+  }
+}