@jc-times/business-ui 0.2.53 → 0.2.54

package/docs/release.md

@@ -1,32 +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` 或标签不匹配而退出。不要把真实令牌写入命令历史、仓库文件或文档。
+# 内部发布流程
+
+## 发布位置与权限
+
+- 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/sortable-list.md

@@ -0,0 +1,43 @@
+# 拖动排序与跨区块移动
+
+本页新增接口为本地未发布能力；消费方先核对安装版本的类型声明。
+
+## 场景与接口
+
+- 同列表排序沿用 `onReorder(items)`。
+- 同一编辑范围共享 `useSortableTransferScope<T>(ownerKey)`；不同范围不接收彼此的拖动。ownerKey 使用稳定的业务身份。
+- 各列表可传稳定的 `listId: string | number`。它用于回调上下文，不代替 scope 隔离；省略时对应上下文字段为 undefined。
+- `onDropOnItem(moving, target, context)`：放到目标项上。
+- `onDropBetweenItems(moving, target, position, context)`：跨列表插入，position 为 before/after。
+- `onDropOnList(moving, context)`：放到集合本身，包括空列表；配合 `canDropOnList(moving)` 限制接收。
+- `context: SortableMoveContext` 包含 `sourceListId`、`targetListId`。原有少参数回调无需修改。
+- `renderEmptyState()` 自定义空状态；默认根据是否可接收显示提示。插入位置、来源占位和目标高亮沿用公共主题。
+
+根区域落点不承诺插入位置，由消费方选择追加或其他规则。需要精确位置时用 before/after。未配置回调的落点不接收拖动。
+
+```tsx
+const scope = useSortableTransferScope<Row>(documentId);
+// 来源列表也传同一 scope，以及自己的 listId。
+<SortableList
+  aria-label="待办区" listId="todo" transferScope={scope}
+  items={rows} getKey={row => row.id} getTextValue={row => row.title}
+  renderItem={row => <Card row={row} />} onReorder={setRows}
+  onDropOnList={(moving, { sourceListId, targetListId }) => {
+    // 通过一次状态更新同时移除来源并添加到目标，持久化由应用处理。
+    moveRows(moving, sourceListId, targetListId);
+  }}
+/>
+```
+
+## 状态与约束
+
+- `disabled` 仅禁用拖放，不卸载列表和卡片，也不禁用卡片中的业务表单。手柄隐藏，但保持拖放 hooks 结构稳定，避免 hook 数量变化和草稿丢失。
+- 同一 scope 内 key 必须唯一，items 更新必须提供新数组；移动项沿来源顺序返回。
+- 拖动过程中保留来源数据；来源删除、禁用、卸载或 ownerKey 改变后不提交旧拖动。目标卸载、目标禁用、键歧义和取消均不提交；一次跨列表拖动只消费一次。
+- 卡片在跨列表移动时的局部状态保留不在本组件承诺内；需跨容器保留的草稿由消费方受控保存。
+- 建立每列表 key 索引供拖动判定使用，避免每次 hover 遍历全部行；scope 歧义检查仍随列表数量增长，不等于已支持虚拟化。
+
+## 验证
+
+`src/SortableList.transfer.test.tsx` 覆盖失效来源/目标、重复键、scope 更换、取消、上下文与 2000 行/500 次 hover 的 key 访问计数。
+`e2e/sortable-drop.spec.ts` 覆盖真实浏览器键盘/鼠标投放、空列表、禁用切换时输入节点/草稿/焦点保留及五档视口；手机项目为模拟视口，不替代实机触屏。

package/licenses/embedpdf-MIT.txt

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 CloudPDF
-
-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.
+MIT License
+
+Copyright (c) 2025 CloudPDF
+
+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

@@ -1,166 +1,168 @@
-{
-  "name": "@jc-times/business-ui",
-  "version": "0.2.53",
-  "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/user-profile.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",
-    "patches",
-    "licenses/embedpdf-MIT.txt"
-  ],
-  "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": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "peerDependenciesMeta": {
-    "@embedpdf/react-pdf-viewer": {
-      "optional": true
-    },
-    "pdfjs-dist": {
-      "optional": true
-    }
-  }
-}
+{
+  "name": "@jc-times/business-ui",
+  "version": "0.2.54",
+  "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/user-profile.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",
+    "patches",
+    "licenses/embedpdf-MIT.txt",
+    "docs/sortable-list.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/pdfium": "2.15.0",
+    "@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": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependenciesMeta": {
+    "@embedpdf/react-pdf-viewer": {
+      "optional": true
+    },
+    "pdfjs-dist": {
+      "optional": true
+    }
+  }
+}