@jc-times/business-ui 0.2.43 → 0.2.53

package/docs/agent-guide.md

@@ -1,5 +1,7 @@
 # Agent 公共组件使用指南
 
+级联选择用于右侧窄栏时使用 0.2.48 或以上版本：浮层按可见视口避让，不需要消费方重写定位样式。
+
 本指南面向在业务应用中使用 `@jc-times/business-ui` 的 agent，也适用于维护本库的 agent。先按场景选型，再按需阅读 API 和专题文档，不需要通读历史审计记录。
 
 ## 开始工作前
@@ -21,8 +23,9 @@
 | 页面标题、说明、操作区 | `PageHeader` | 输出页面级 h1；不要用于每个小区块 |
 | 带标题的内容区域 | `SectionCard` | 按页面大纲设置 headingLevel；业务内容放 children |
 | 状态标签 / 单项统计 | `Badge` / `MetricCard` | 业务状态映射、数值计算和格式由应用提供 |
-| 常规操作 / 解释不可用原因 | `Button` / `ExplainableButton` | 图标按钮必须有 aria-label；禁用条件由业务判断 |
-| 导航 / 文件下载 | `LinkButton` | 必须提供 href；输出真实链接并保留浏览器下载语义；跨域/鉴权下载先由业务层取得签名地址或 Blob URL，不用临时 DOM 点击模拟 |
+| 人员标签与只读资料卡 | `UserProfilePopover` | 姓名、编号、部门、身份标签由应用提供；点击或键盘打开资料卡，不在组件内查询人员目录 |
+| 常规操作 / 解释不可用原因 | `Button` / `ExplainableButton` | 图标按钮必须有 aria-label；禁用条件由业务判断 |
+| 导航 / 文件下载 | `LinkButton` | 必须提供 href；输出真实链接并保留浏览器下载语义；跨域/鉴权下载先由业务层取得签名地址或 Blob URL，不用临时 DOM 点击模拟 |
 | 持续提示 / 无数据 / 加载占位 | `Alert` / `EmptyState` / `Skeleton` | 区分错误、空结果和加载，不用空状态掩盖请求失败 |
 | 加载与可重试错误 | `RecoverableAsyncState`（别名 `AsyncState`） | 页面提供状态、文案和重试回调 |
 | 操作完成后的临时通知 | `ToastProvider` 与 `useToast` | 统一队列；关键表单错误仍应在字段或页面呈现 |
@@ -63,7 +66,7 @@
 
 | 需求 | 使用组件或入口 | 边界与选择依据 |
 | --- | --- | --- |
-| 列表表格、排序、行选择 | [DataTable](data-table.md) | 当前源码已采用MRT；旧参数兼容，完整配置用options或useDataTable/DataTableView；长页面可按需开启底部吸附横向滚动条 |
+| 列表表格、排序、行选择 | [DataTable](data-table.md) | 当前源码已采用MRT；旧参数兼容，完整配置用options或useDataTable/DataTableView；固定高度列表优先容器原生滚动，长页面可按需开启底部吸附横向滚动条 |
 | 评估筛选、列管理、主从明细行合并或展开 | [表格能力与 MRT 样例](mrt-poc.md) | productDisplay由调用方选择；同行用rowSpan且按合同分页；仅本地验证，不是已发布API |
 | 页码导航 | `Pagination` | 页面负责取数；窄屏自动简化 |
 | 卡片拖动排序 | `SortableList` | 提供稳定唯一 getKey、getTextValue、renderItem 和 onReorder；应用保存顺序 |
@@ -143,3 +146,23 @@ PDFium Headless 0.2.33 支持搜索、选择、双指缩放及外部受控缩放
 只使用原生 PDF 叠层的页面可从 `@jc-times/business-ui/pdfium-viewer` 导入 `PdfiumViewer`，参数与 Headless 模式一致，但省略 `renderer`。该入口不引入 PDF.js 兼容渲染或完整查看器外壳，适用于独立公开查看页面；引擎仍按需加载。通过 `engineOptions.wasmUrl` 提供本地资源的绝对 URL，保证 Blob worker 可解析；同一 `source.kind/id` 维持会话，文件版本改变时必须改变 `id`。
 
 PDFium 专用入口支持 `initialZoom="fit-width"`（0.2.37）：无受控 zoom 时由官方插件适配页面宽度；旧默认 100% 保持不变。
+
+### PDFium 0.2.44
+PdfiumViewer 支持 defaultRailCollapsed：传 true 默认收起页面侧栏，用户仍可打开。省略保留按视口初始化的行为。双指缩放逐帧提交到 PDFium 的范围和精度约束，松手保持最后比例；Ctrl/Meta+滚轮继续使用官方手势。
+
+### PDFium 0.2.46 — 2026-09-14
+保留官方 ZoomGestureWrapper 的触屏和 Ctrl/Meta+滚轮 CSS 位图预览，结束后只提交一次引擎缩放。移除0.2.44的逐帧触屏实现。修复可见页码回报被当作外部跳页命令导致的缩放后跳页。官方2.15.0预览缺少边界参数，通过精确 pnpm patch 补齐 minZoom/maxZoom 并对齐提交精度；消费方无需自行打补丁，库构建仅内联该 React 手势入口，PDFium/插件状态仍保持外部单例。补丁责任人为公共文档组件维护者，2026-10-14复核；上游具备等价能力并通过同组回归后删除补丁。
+
+### PDFium 0.2.45
+PDFium/Headless 默认显示源 PDF 的已有批注，正文与缩略图一致；无需业务层叠画印章。显示不等于允许编辑，不改变 PDF 的签名或文件字节。
+
+### 拖动到业务容器
+
+复用 `SortableList` 的 `onDropOnItem` / `canDropOnItem`（0.2.49）处理同列表内的目标项接收；目标可以渲染业务容器。鼠标、触屏、键盘排序及拖放高亮由公共组件负责，领域成员关系、价格、权限与保存仍由消费方负责；不要在消费方复制 React Aria 拖放逻辑。
+
+### SortableList 跨区块移动（0.2.50）
+同一业务编辑范围用 `useSortableTransferScope<T>(ownerKey)` 创建并共享 `transferScope`；嵌套列表必须使用同一种 T，范围内每个列表拥有的 key 不重复。ownerKey 改变即隔离旧拖动。`onDropBetweenItems(moving,target,position)` / `canDropBetweenItems` 处理跨列表的 before/after，`onDropOnItem` 处理放入容器，原 `onReorder` 保留同列表排序。消费者一次性更新来源和目标，拖动过程中不移除来源。来源自动保留占位（可用 draggingLabel 修改文案）、目标沿用 React Aria 插入线和目标高亮。未共享同一对象的列表和外部拖入不接受；来源/目标失效、禁用、重复目标键不提交。来源清理和目标注册由组件持有。
+
+For free multiline text with suggestions in the same field, use MultilineAutoComplete (0.2.51). Do not add a second standard-value picker beside a textarea.
+
+AutoComplete/Combobox选项可通过group字符串按组显示灰色标题；标题不可选择，键盘仅导航选项。调用方传入已按搜索条件过滤的items，空分组不显示。

package/docs/api.md

@@ -12,6 +12,15 @@
 ## 信息与布局
 
 - `Badge`：原生 `span` 展示组件，`tone` 为 `neutral | info | success | warning | danger`，`size` 为 `small | medium`；透传 span 属性并 forward ref。组件只呈现调用方给出的内容，不包含订单、任务或 ERP 状态映射，也不隐式增加 live-region 语义。在 flex/截断容器内 Badge 保持自身尺寸并按文字基线对齐，长文本的截断策略仍由外层内容容器决定。
+- `UserProfilePopover`：展示人员标签与点击后打开的只读资料卡。必填 `name`；可选 `code`、`department`、`tag`、`avatarUrl`、`avatarColor`，以及 `codeLabel`、`departmentLabel`。默认触发器是可聚焦按钮；`trigger` 可换成自定义单个可转发 ref 的交互元素。支持 `side`、`align`、`open`、`defaultOpen`、`onOpenChange` 和弹层 `className`；沿用 Popover 的 Escape、失焦关闭和视口避让。资料卡宽度随视口在 300–560px 间变化，并受可用空间限制；可用 `--ui-user-profile-width` 调整。组件不加载人员资料、不推断身份或权限，缺失的字段不显示。
+
+详细用法见[人员资料卡](user-profile.md)。
+
+```tsx
+<UserProfilePopover name="章晨露" code="ZhangChenLu"
+  department="示例集团 / 项目管理部 / 运营组" tag="内部成员"
+  avatarColor="#e94b50" />
+```
 - `MetricCard`：用 `label`、`value`、可选 `description`、装饰性 `icon` 与五档 `tone` 呈现单项指标；根节点是由可见 label 命名的 `article`，透传 article 属性并 forward ref。数值格式化、趋势计算、单位和业务文案均由调用方完成。
 - `PageHeader`：用 `eyebrow`、必填 `title`、可选 `description` 和 `actions` 组成页面标题区，固定输出页面级 `h1`；`titleId` 可用于页内关联。根节点是原生 `header`，支持原生属性与 ref，窄屏时操作区自动换行。`copyProps` 与 `actionsProps` 为既有 `.ui-page-header-copy` / `.ui-page-header-actions` 槽透传原生 div 属性，便于消费方挂接稳定的 class、data 与可访问属性；不传 `actions` 时不输出空操作区。
 - `SectionCard`：必填 `title` 和 `children`，可选 `description`、`actions`、`headingId` 与 `headingLevel`（2–6）。根节点是由可见标题自动命名的 `section`，因此不仅是样式包装；消费方应按页面大纲选择标题层级。显式 `aria-label` / `aria-labelledby` 会覆盖自动区域名称。
@@ -28,17 +37,17 @@
 
 ## 表单与选择
 
-- `Button`：执行提交、打开、确认等动作；当 `iconOnly` 为 `true` 时，TypeScript 强制要求 `aria-label`。
-- `LinkButton`：导航或下载使用的真实 `<a>`，必须提供 `href`，支持 `download`、按钮视觉变体和禁用语义；图标链接同样必须提供 `aria-label`。禁用时移除 `href`、退出 Tab 顺序并阻止点击向父级冒泡，同时保留禁用链接的可访问语义。
-
-```tsx
-<LinkButton href="/api/contracts/42/file" download="合同-42.pdf">下载合同（PDF）</LinkButton>
-<LinkButton href={preparedBlobUrl} download="处理后的合同.pdf" iconOnly aria-label="下载处理后的合同">↓</LinkButton>
-```
-
-原生 `download` 只保证同源 URL、`blob:` 与 `data:` URL 的下载提示；跨域响应可能直接导航，并受服务端 `Content-Disposition` 影响。需要自定义鉴权请求头、异步生成或客户端转换时，由业务层完成请求与错误处理，成功后向 `LinkButton` 提供同源签名地址或 Blob URL，并在不再使用时释放 Blob URL。下载或新窗口行为应写入可见文案或可访问名称，不能只靠装饰图标表达。
-
-- `TextInput`：`startAdornment` / `endAdornment` 接受 ReactNode，用于搜索图标、清除按钮、金额单位和百分号。未提供装饰时保持原有 input-only DOM；提供装饰时 ref、className 和原生属性仍落在 input，外框统一呈现 focus/invalid/disabled 状态。点击非交互装饰会聚焦输入框；交互装饰需自行提供可访问名称，并随输入框同步禁用。
+- `Button`：执行提交、打开、确认等动作；当 `iconOnly` 为 `true` 时，TypeScript 强制要求 `aria-label`。
+- `LinkButton`：导航或下载使用的真实 `<a>`，必须提供 `href`，支持 `download`、按钮视觉变体和禁用语义；图标链接同样必须提供 `aria-label`。禁用时移除 `href`、退出 Tab 顺序并阻止点击向父级冒泡，同时保留禁用链接的可访问语义。
+
+```tsx
+<LinkButton href="/api/contracts/42/file" download="合同-42.pdf">下载合同（PDF）</LinkButton>
+<LinkButton href={preparedBlobUrl} download="处理后的合同.pdf" iconOnly aria-label="下载处理后的合同">↓</LinkButton>
+```
+
+原生 `download` 只保证同源 URL、`blob:` 与 `data:` URL 的下载提示；跨域响应可能直接导航，并受服务端 `Content-Disposition` 影响。需要自定义鉴权请求头、异步生成或客户端转换时，由业务层完成请求与错误处理，成功后向 `LinkButton` 提供同源签名地址或 Blob URL，并在不再使用时释放 Blob URL。下载或新窗口行为应写入可见文案或可访问名称，不能只靠装饰图标表达。
+
+- `TextInput`：`startAdornment` / `endAdornment` 接受 ReactNode，用于搜索图标、清除按钮、金额单位和百分号。未提供装饰时保持原有 input-only DOM；提供装饰时 ref、className 和原生属性仍落在 input，外框统一呈现 focus/invalid/disabled 状态。点击非交互装饰会聚焦输入框；交互装饰需自行提供可访问名称，并随输入框同步禁用。
 - `Select`：`triggerRef` 暴露触发按钮；`triggerProps` 透传触发器的 ARIA、data 与事件属性；`portalContainer` 和 `placement` 控制安全的浮层挂载与方向。原生 `SelectInput` 在触屏使用 44px 最小点击高度；自定义 `Select` 在 600px 以下以安全区底部抽屉呈现，并限制候选区高度、内部滚动与滚动链。
 - `Combobox` / `AutoComplete`：`inputRef`、`inputProps` 透传输入框 ARIA、data、`inputMode`、`autoComplete` 与原生事件；`placement` 与 `portalContainer` 控制浮层。
 - `ToggleSwitch`：除受控 `checked/onChange` 外接受原生 checkbox 属性并 forward ref，可使用 `id`、`name`、`value`、`required`、`form`、ARIA 与 data 属性参与原生表单。
@@ -65,9 +74,9 @@ TextInput（含装饰组合外框）、原生 SelectInput 与默认 Button 的
 
 合同业务展示、搜索记忆与列设置组合见 [MRT样例](mrt-poc.md)。`productDisplay` 属于合同包装参数，不是公共DataTable旧参数。
 
-`DataTable` 默认 `mobileLayout="scroll"`，保持 0.2.4 及更早版本的横向滚动行为。真实调用需要标签化卡片行时可显式传 `mobileLayout="cards"`；在 600px 及以下，表头保持对辅助技术可用但视觉隐藏，单元格通过 `mobileLabel` 或字符串表头生成的 `data-label` 呈现标签。复杂表头应显式提供 `mobileLabel`。卡片布局允许长文本换行，并为选择列、尾部操作列和空状态提供独立布局。`rootRef` / `rootProps` 与 `tableRef` / `tableProps` 可用于稳定挂接原生属性，不需要依赖结构位置选择器。
-
-长页面或宽表格可显式传 `stickyHorizontalScrollbar`，让底部横向滚动条在内容溢出时吸附于可视区域并与原生表格滚动同步；通过 `horizontalScrollbarLabel` 提供当前业务表格的可访问名称。该能力默认关闭，也适用于完整 `options` 入口和 `DataTableView`。
+`DataTable` 默认 `mobileLayout="scroll"`，保持 0.2.4 及更早版本的横向滚动行为。真实调用需要标签化卡片行时可显式传 `mobileLayout="cards"`；在 600px 及以下，表头保持对辅助技术可用但视觉隐藏，单元格通过 `mobileLabel` 或字符串表头生成的 `data-label` 呈现标签。复杂表头应显式提供 `mobileLabel`。卡片布局允许长文本换行，并为选择列、尾部操作列和空状态提供独立布局。`rootRef` / `rootProps` 与 `tableRef` / `tableProps` 可用于稳定挂接原生属性，不需要依赖结构位置选择器。
+
+长页面或宽表格可显式传 `stickyHorizontalScrollbar`，让底部横向滚动条在内容溢出时吸附于可视区域并与原生表格滚动同步；通过 `horizontalScrollbarLabel` 提供当前业务表格的可访问名称。该能力默认关闭，也适用于完整 `options` 入口和 `DataTableView`。
 
 `Pagination` 在 360px 及以下自动只保留上一页、当前页摘要和下一页，调用方仍可用 `compact` 在更宽视口显式简化。`ToastProvider` 的连续通知栈限制在动态视口与底部安全区内，超出时内部滚动；长文案和操作按钮会在窄屏换行。
 
@@ -218,3 +227,19 @@ features.search/textSelection/pinchZoom 均默认开启。zoom/rotation 可受
 只使用原生 PDF 叠层的页面可从 `@jc-times/business-ui/pdfium-viewer` 导入 `PdfiumViewer`，参数与 Headless 模式一致，但省略 `renderer`。该入口不引入 PDF.js 兼容渲染或完整查看器外壳，适用于独立公开查看页面；引擎仍按需加载。通过 `engineOptions.wasmUrl` 提供本地资源的绝对 URL，保证 Blob worker 可解析；同一 `source.kind/id` 维持会话，文件版本改变时必须改变 `id`。
 
 PDFium 专用入口支持 `initialZoom="fit-width"`（0.2.37）：无受控 zoom 时由官方插件适配页面宽度；旧默认 100% 保持不变。
+
+### PDFium 0.2.44
+PdfiumViewer 支持 defaultRailCollapsed：传 true 默认收起页面侧栏，用户仍可打开。省略保留按视口初始化的行为。双指缩放逐帧提交到 PDFium 的范围和精度约束，松手保持最后比例；Ctrl/Meta+滚轮继续使用官方手势。
+
+### PDFium 0.2.46 — 2026-09-14
+保留官方 ZoomGestureWrapper 的触屏和 Ctrl/Meta+滚轮 CSS 位图预览，结束后只提交一次引擎缩放。移除0.2.44的逐帧触屏实现。修复可见页码回报被当作外部跳页命令导致的缩放后跳页。官方2.15.0预览缺少边界参数，通过精确 pnpm patch 补齐 minZoom/maxZoom 并对齐提交精度；消费方无需自行打补丁，库构建仅内联该 React 手势入口，PDFium/插件状态仍保持外部单例。补丁责任人为公共文档组件维护者，2026-10-14复核；上游具备等价能力并通过同组回归后删除补丁。
+
+### SortableList 目标项接收（0.2.49）
+
+可选 `onDropOnItem(moving, target)` 启用同一列表内拖到目标项；`canDropOnItem(moving, target)` 决定哪些目标可接收。组件保留前后排序、鼠标/触屏/键盘交互、目标高亮与取消行为，不接收外部拖入的数据，不自行变更分组或请求接口。输入均来自当前受控 items；自投、缺失来源、目标或禁用状态不回调。消费方在回调中用当前文档所有者与业务规则重新核验，再更新分组与持久化。
+
+### SortableList 跨区块移动（0.2.50）
+同一业务编辑范围用 `useSortableTransferScope<T>(ownerKey)` 创建并共享 `transferScope`；嵌套列表必须使用同一种 T，范围内每个列表拥有的 key 不重复。ownerKey 改变即隔离旧拖动。`onDropBetweenItems(moving,target,position)` / `canDropBetweenItems` 处理跨列表的 before/after，`onDropOnItem` 处理放入容器，原 `onReorder` 保留同列表排序。消费者一次性更新来源和目标，拖动过程中不移除来源。来源自动保留占位（可用 draggingLabel 修改文案）、目标沿用 React Aria 插入线和目标高亮。未共享同一对象的列表和外部拖入不接受；来源/目标失效、禁用、重复目标键不提交。来源清理和目标注册由组件持有。
+
+## MultilineAutoComplete (0.2.51)
+Controlled value/onChange, items/onSelect, label or aria-label, placeholder, disabled/loading, onFocus/onBlur, helpText and portalContainer. Composes React Aria Autocomplete, TextField/TextArea, Popover and ListBox. Async items open while focused; selection is explicit. Free text and unmatched Enter newlines are retained. Network cancellation and domain mapping belong to the consumer.

package/docs/cascader.md

@@ -1,5 +1,7 @@
 # 通用级联选择
 
+0.2.48 起，桌面展开多列时按可见视口避让边缘，避免右侧窄栏的区县列越界；继续使用 RC 的定位与碰撞处理。
+
 当前本地新增能力；消费方必须先核对安装版本导出，不能将本地源码视为已发布。
 
 `Cascader` 使用固定 `@rc-component/cascader@1.25.0` 内核，外观使用 `--ui-*` 令牌。桌面多列浮层，600px 以下底部面板，列过多时面板内部横向滚动；手机软键盘仍需真实设备验收。浮层归属最近 ModalShell，Escape 先关闭选择面板。

package/docs/component-strategy.md

@@ -91,4 +91,4 @@
 
 ## 2026-09-11 Cascader 内核采用
 
-新增固定 @rc-component/cascader@1.25.0（MIT），公共包装提供业务主题、表单元信息、空值归一、最近弹窗 portal、窄屏底部面板与默认独立多选。StructuredAddressInput 复用通用组件；TreeSelect 保留兼容。无 antd 依赖；依赖外置，发行包保留 RC 许可证。当前为本地实现，消费接入与发布独立验证。
+新增固定 @rc-component/cascader@1.25.0（MIT），公共包装提供业务主题、表单元信息、空值归一、最近弹窗 portal、窄屏底部面板与默认独立多选。StructuredAddressInput 复用通用组件；TreeSelect 保留兼容。无 antd 依赖；依赖外置，发行包保留 RC 许可证。当前为本地实现，消费接入与发布独立验证。

package/docs/data-table.md

@@ -1,123 +1,127 @@
-# DataTable：MRT 公共表格与迁移
-
-0.2.31采用MRT替代原表格渲染内核；消费服务需单独升级验收。实际安装版本必须包含本文列出的导出；不能用旧版本直接导入新增入口。
-
-## 导入与按需加载
-
-```tsx
-import { DataTable } from '@jc-times/business-ui/data-table';
-import '@jc-times/business-ui/styles.css';
-```
-
-主入口仍导出DataTable以兼容旧调用。独立 `data-table` 入口导出DataTable、useDataTable、DataTableView、DataTableTheme、DataTableMergedRows及相关类型。组件库采用ESM并将MRT/MUI作为外部依赖交给业务构建器处理；这些依赖已列为正式dependencies。
-
-页面懒加载仍由消费服务负责。推荐把完整列表页面或业务表格包装作为动态import边界；仅换成独立入口不等于浏览器自动延迟加载。样式仍为共享CSS。构建验证已确认仅导入Button的消费产物不包含MRT/MUI实现，但使用DataTable的页面必然需要表格依赖。
-
-## 旧参数兼容
-
-```tsx
-<DataTable rows={rows} columns={columns} getRowId={row => row.id}
-  selectedRowIds={selectedIds} onSelectedRowIdsChange={setSelectedIds}/>
-```
-
-旧DataTableProps和DataTableColumn保留：columns使用id/header/cell，排序使用sortValue或服务端sortable；sort/defaultSort/onSortChange、跨页选择、禁选、hiddenColumnIds、加载/空态、caption、ref与原生属性保持兼容。mobileLayout仍支持scroll/cards。
-
-此入口已通过MRT_Table渲染表格，兼容层保留旧排序语义及memo行渲染。为避免旧页面行为改变，不自动增加工具栏、筛选或分页；也不自动把旧cell返回的ReactNode当作可搜索原始值。需要完整MRT交互时改用下述options入口。
-
-## 完整表格配置
-
-```tsx
-import { DataTable, type DataTableOptions } from '@jc-times/business-ui/data-table';
-type Order = { id: string; customer: string; amount: number };
-
-const options: DataTableOptions<Order> = {
-  data: orders,
-  columns: [
-    { accessorKey: 'id', header: '编号' },
-    { accessorKey: 'customer', header: '客户' },
-    { accessorKey: 'amount', header: '金额' },
-  ],
-  getRowId: row => row.id,
-  enableColumnOrdering: true,
-  enableColumnResizing: true,
-  enableColumnPinning: true,
-  enableRowSelection: true,
-};
-<DataTable options={options}/>;
-```
-
-表格列较多且页面本身纵向滚动较长时，可显式开启底部吸附横向滚动条。它仅在内容确实超出表格容器时显示，并与 MRT 原生滚动容器双向同步；固定列仍通过 MRT 的 `columnPinning` 配置：
-
-```tsx
-<DataTable options={options} stickyHorizontalScrollbar
-  horizontalScrollbarLabel="订单表横向滚动" />
-```
-
-`horizontalScrollbarLabel` 应描述当前业务表格，供键盘和辅助技术用户辨认。该能力同样可传给 `DataTableView`；默认关闭，以避免改变既有页面的滚动布局。
-
-options与旧rows/columns参数是两种互斥调用形式，不要混传。DataTableOptions、DataTableColumnDef、DataTableInstance分别对应MRT的options/column/instance类型；目前公开此底层契约，没有假称跨组件库兼容。默认中文文案和公共Lucide图标，可由options覆盖。
-
-需要从工具栏、列设置等多个位置操作实例时：
-
-```tsx
-const table = useDataTable(options); // 在React组件内部调用
-return <DataTableView table={table}/>;
-```
-
-DataTableView与DataTable的配置入口共用MRT渲染和DataTableTheme；主题使用--ui-*，嵌套浮层继承OverlayContainer。独立放在表格外的MRT工具栏控件可用DataTableTheme包裹。ModalShell中的Escape层级仍由业务组合协调，参考合同样例；公共表格不会替业务关闭弹窗。
-
-## 合并行与展开明细
-
-模式由业务服务选择，不固化合同/产品字段，也不要求最终用户看到切换器。
-
-- 展开：options.renderDetailPanel渲染调用方提供的明细，沿用MRT展开状态。
-- 合并：options使用layoutMode='semantic'、enableRowVirtualization=false，在muiTableBodyProps中调用DataTableMergedRows。按主记录分页，每条明细生成真实tr，其他可见列使用rowSpan跨行。
-
-```tsx
-const table = useDataTable({
-  ...options,
-  layoutMode: 'semantic',
-  enableRowVirtualization: false,
-  muiTableBodyProps: ({ table }) => ({ children:
-    <DataTableMergedRows table={table}
-      getDetails={row => row.lines}
-      detailColumnIds={['product', 'quantity']}
-      getDetailValue={(line, id) => id === 'product' ? line?.name ?? '暂无产品' : line?.quantity ?? '—'}/>
-  }),
-});
-```
-
-上述示意要求业务Row包含lines，并在columns定义product/quantity这两个明细列。getDetails返回只读数组，getDetailValue接受空明细null。主行用getRowId稳定标识；列的排序、筛选应基于主记录定义，明细列应关闭没有明确语义的排序/筛选。隐藏所有明细列时每主记录一行。合并不支持跨主记录、任意colSpan、分组/树形/行固定组合；不与虚拟化同时使用。
-
-合同样例已通过公共DataTableMergedRows生成合并行；合同字段、金额区间弹层、搜索记忆及列设置布局仍由业务包装组合，详见 [合同样例](mrt-poc.md)。这些业务特定能力不会作为DataTable旧参数静默启用。
-
-## 迁移与验收
-
-1. 旧页面可保留DataTable旧参数，先验证布局、排序、选择及加载状态。
-2. 复杂页面改用options或useDataTable/DataTableView，明确服务端查询和分页，不同时使用旧排序参数。
-3. 为重型页面设置动态import边界，验证仅使用按钮的页面不含MRT/MUI代码。
-4. 长页面可启用stickyHorizontalScrollbar；确认无溢出时隐藏，拖动吸附滚动条和原生滚动区时位置同步。
-5. 合并模式按主记录分页；虚拟化只减少DOM，不减少全量数据筛选开销。
-6. 发布新版本后，消费服务精确升级并验证真实接口、权限、用户隔离和设备；本地完成不等于生产已替换。
-
+# DataTable：MRT 公共表格与迁移
+
+0.2.31采用MRT替代原表格渲染内核；消费服务需单独升级验收。实际安装版本必须包含本文列出的导出；不能用旧版本直接导入新增入口。
+
+## 导入与按需加载
+
+```tsx
+import { DataTable } from '@jc-times/business-ui/data-table';
+import '@jc-times/business-ui/styles.css';
+```
+
+主入口仍导出DataTable以兼容旧调用。独立 `data-table` 入口导出DataTable、useDataTable、DataTableView、DataTableTheme、DataTableMergedRows及相关类型。组件库采用ESM并将MRT/MUI作为外部依赖交给业务构建器处理；这些依赖已列为正式dependencies。
+
+页面懒加载仍由消费服务负责。推荐把完整列表页面或业务表格包装作为动态import边界；仅换成独立入口不等于浏览器自动延迟加载。样式仍为共享CSS。构建验证已确认仅导入Button的消费产物不包含MRT/MUI实现，但使用DataTable的页面必然需要表格依赖。
+
+## 旧参数兼容
+
+```tsx
+<DataTable rows={rows} columns={columns} getRowId={row => row.id}
+  selectedRowIds={selectedIds} onSelectedRowIdsChange={setSelectedIds}/>
+```
+
+旧DataTableProps和DataTableColumn保留：columns使用id/header/cell，排序使用sortValue或服务端sortable；sort/defaultSort/onSortChange、跨页选择、禁选、hiddenColumnIds、加载/空态、caption、ref与原生属性保持兼容。mobileLayout仍支持scroll/cards。
+
+此入口已通过MRT_Table渲染表格，兼容层保留旧排序语义及memo行渲染。为避免旧页面行为改变，不自动增加工具栏、筛选或分页；也不自动把旧cell返回的ReactNode当作可搜索原始值。需要完整MRT交互时改用下述options入口。
+
+## 完整表格配置
+
+```tsx
+import { DataTable, type DataTableOptions } from '@jc-times/business-ui/data-table';
+type Order = { id: string; customer: string; amount: number };
+
+const options: DataTableOptions<Order> = {
+  data: orders,
+  columns: [
+    { accessorKey: 'id', header: '编号' },
+    { accessorKey: 'customer', header: '客户' },
+    { accessorKey: 'amount', header: '金额' },
+  ],
+  getRowId: row => row.id,
+  enableColumnOrdering: true,
+  enableColumnResizing: true,
+  enableColumnPinning: true,
+  enableRowSelection: true,
+};
+<DataTable options={options}/>;
+```
+
+表格列较多且页面本身纵向滚动较长时，可显式开启底部吸附横向滚动条。它仅在内容确实超出表格容器时显示，并与 MRT 原生滚动容器双向同步；固定列仍通过 MRT 的 `columnPinning` 配置：
+
+```tsx
+<DataTable options={options} stickyHorizontalScrollbar
+  horizontalScrollbarLabel="订单表横向滚动" />
+```
+
+`horizontalScrollbarLabel` 应描述当前业务表格，供键盘和辅助技术用户辨认。该能力同样可传给 `DataTableView`；默认关闭，以避免改变既有页面的滚动布局。
+
+options与旧rows/columns参数是两种互斥调用形式，不要混传。DataTableOptions、DataTableColumnDef、DataTableInstance分别对应MRT的options/column/instance类型；目前公开此底层契约，没有假称跨组件库兼容。默认中文文案和公共Lucide图标，可由options覆盖。
+
+需要从工具栏、列设置等多个位置操作实例时：
+
+```tsx
+const table = useDataTable(options); // 在React组件内部调用
+return <DataTableView table={table}/>;
+```
+
+DataTableView与DataTable的配置入口共用MRT渲染和DataTableTheme；主题使用--ui-*，嵌套浮层继承OverlayContainer。独立放在表格外的MRT工具栏控件可用DataTableTheme包裹。ModalShell中的Escape层级仍由业务组合协调，参考合同样例；公共表格不会替业务关闭弹窗。
+
+## 合并行与展开明细
+
+模式由业务服务选择，不固化合同/产品字段，也不要求最终用户看到切换器。
+
+- 展开：options.renderDetailPanel渲染调用方提供的明细，沿用MRT展开状态。
+- 合并：options使用layoutMode='semantic'、enableRowVirtualization=false，在muiTableBodyProps中调用DataTableMergedRows。按主记录分页，每条明细生成真实tr，其他可见列使用rowSpan跨行。
+
+```tsx
+const table = useDataTable({
+  ...options,
+  layoutMode: 'semantic',
+  enableRowVirtualization: false,
+  muiTableBodyProps: ({ table }) => ({ children:
+    <DataTableMergedRows table={table}
+      getDetails={row => row.lines}
+      detailColumnIds={['product', 'quantity']}
+      getDetailValue={(line, id) => id === 'product' ? line?.name ?? '暂无产品' : line?.quantity ?? '—'}/>
+  }),
+});
+```
+
+上述示意要求业务Row包含lines，并在columns定义product/quantity这两个明细列。getDetails返回只读数组，getDetailValue接受空明细null。主行用getRowId稳定标识；列的排序、筛选应基于主记录定义，明细列应关闭没有明确语义的排序/筛选。隐藏所有明细列时每主记录一行。合并不支持跨主记录、任意colSpan、分组/树形/行固定组合；不与虚拟化同时使用。
+
+合同样例已通过公共DataTableMergedRows生成合并行；合同字段、金额区间弹层、搜索记忆及列设置布局仍由业务包装组合，详见 [合同样例](mrt-poc.md)。这些业务特定能力不会作为DataTable旧参数静默启用。
+
+## 迁移与验收
+
+1. 旧页面可保留DataTable旧参数，先验证布局、排序、选择及加载状态。
+2. 复杂页面改用options或useDataTable/DataTableView，明确服务端查询和分页，不同时使用旧排序参数。
+3. 为重型页面设置动态import边界，验证仅使用按钮的页面不含MRT/MUI代码。
+4. 长页面可启用stickyHorizontalScrollbar；确认无溢出时隐藏，拖动吸附滚动条和原生滚动区时位置同步。
+5. 合并模式按主记录分页；虚拟化只减少DOM，不减少全量数据筛选开销。
+6. 发布新版本后，消费服务精确升级并验证真实接口、权限、用户隔离和设备；本地完成不等于生产已替换。
+
 不修改业务数据，不自动迁移所有服务，不提供旧包版本的新能力。MRT3.2.1和MUI7.3.11及配套依赖已固定在package.json/锁文件中。
-
-## 按需打包回归与项目管理复验（2026-09-12）
-
-构建现使用preserveModules保留组件边界。原合并产物中工厂调用等初始化代码会阻止整段未用组件被删除；仅保留ESM导出和sideEffects声明不足以确保合并模块内部纯度。修复后消费构建可跳过完整未使用模块，不在业务端改写包代码。
-
-`pnpm test:tree-shaking` 在 `pnpm build` 后对真实dist产物构建Button、TextInput、DateInput、DataTable四个消费者。前两者必须没有日期/MRT/MUI实现；后两者为正向对照。该检查已纳入pnpm verify。门禁统计传递模块，不仅检查包文件名或入口长度。
-
-读取项目管理0.1.103当前工作树（依赖正式business-ui0.2.30），以相同Vite配置、同一业务入口构建隔离产物，未修改其package/lockfile/源码、未写其dist：
-
-| 入口静态依赖闭包 | 正式0.2.30 | 本地候选 |
-| --- | ---: | ---: |
-| JS gzip | 178.51 KiB | 83.31 KiB |
-| CSS gzip | 17.17 KiB | 17.17 KiB |
-| 日期组件/Calendar模块 | 17 | 0 |
-| MRT模块 | 0 | 0 |
-
-证据在本库忽略产物 `artifacts/project-ui-check/results.json`。这是候选dist别名复验，不是消费服务正式安装、完整验收或部署。项目门禁JS80 KiB、CSS14.5 KiB仍失败；不得提高预算或把日期泄漏修复记作整项发布阻塞解除。剩余首屏代码与共享CSS需另行按真实使用拆分。MRT替代带来的路由体积也需在消费方完整门禁中验收。
-
+
+## 按需打包回归与项目管理复验（2026-09-12）
+
+构建现使用preserveModules保留组件边界。原合并产物中工厂调用等初始化代码会阻止整段未用组件被删除；仅保留ESM导出和sideEffects声明不足以确保合并模块内部纯度。修复后消费构建可跳过完整未使用模块，不在业务端改写包代码。
+
+`pnpm test:tree-shaking` 在 `pnpm build` 后对真实dist产物构建Button、TextInput、DateInput、DataTable四个消费者。前两者必须没有日期/MRT/MUI实现；后两者为正向对照。该检查已纳入pnpm verify。门禁统计传递模块，不仅检查包文件名或入口长度。
+
+读取项目管理0.1.103当前工作树（依赖正式business-ui0.2.30），以相同Vite配置、同一业务入口构建隔离产物，未修改其package/lockfile/源码、未写其dist：
+
+| 入口静态依赖闭包 | 正式0.2.30 | 本地候选 |
+| --- | ---: | ---: |
+| JS gzip | 178.51 KiB | 83.31 KiB |
+| CSS gzip | 17.17 KiB | 17.17 KiB |
+| 日期组件/Calendar模块 | 17 | 0 |
+| MRT模块 | 0 | 0 |
+
+证据在本库忽略产物 `artifacts/project-ui-check/results.json`。这是候选dist别名复验，不是消费服务正式安装、完整验收或部署。项目门禁JS80 KiB、CSS14.5 KiB仍失败；不得提高预算或把日期泄漏修复记作整项发布阻塞解除。剩余首屏代码与共享CSS需另行按真实使用拆分。MRT替代带来的路由体积也需在消费方完整门禁中验收。
+
 公共库136项测试、14项MRT浏览器回归、类型/公共库/矩阵/样例构建和按需打包门禁通过。本地候选已可打包；对应公共库版本为0.2.31，不能覆盖已经发布的0.2.30。
 
+
+## 0.2.47 横向滚动性能
+
+同步条忽略程序写入产生的异步回传，每帧最多镜像一次滚动位置，保留浏览器原生滚动惯性；卸载取消待执行帧。对于带固定高度的业务列表，优先通过 MRT 的 `muiTableContainerProps.sx.maxHeight` 和 `enableStickyHeader` 使用容器原生滚动条，避免额外吸附条覆盖长表格数据行。

package/docs/dependencies.md

@@ -1,57 +1,57 @@
-# 依赖维护与升级
-
-核查日期：2026-09-12。以下为当前工作树的未发布候选；正式 0.2.31 不包含本次升级。版本来自 npm 官方 registry 的 `latest` 标签，并排除 prerelease。直接依赖使用精确版本，传递依赖遵守上游范围，不用全局 override 强行跨主版本。
-
-## 版本清单
-
-| 依赖 | 当前候选 | 上游最新稳定版 | 结论 |
-| --- | --- | --- | --- |
-| lucide-react | 1.45.0 | 1.45.0 | 升级；消费 peer 仍允许已有 0.x |
-| react / react-dom | 19.3.0 | 19.3.0 | 默认开发版本；继续验证 18.3.1 |
-| @types/react / @types/react-dom | 19.3.0 | 19.3.0 | 与开发版本配套 |
-| material-react-table | 3.2.1 | 3.2.1 | 已是最新 |
-| @mui/material / @mui/icons-material | 7.3.11 | 9.4.0 | 最新兼容分支，原因见下文 |
-| @mui/x-date-pickers | 9.13.0 | 9.13.0 | 升级；支持 MUI 7.3+ |
-| @emotion/react | 11.14.0 | 11.14.0 | 已是最新 |
-| @emotion/styled | 11.14.1 | 11.14.1 | 升级 |
-| @embedpdf/react-pdf-viewer | 2.15.0 | 2.15.0 | 已是最新 |
-| @embedpdf/core / engines / plugin-document-manager / plugin-viewport / plugin-scroll / plugin-render / plugin-zoom / plugin-rotate / plugin-thumbnail | 2.15.0 | 2.15.0 | Headless 原生模式使用的精确版本依赖；仅选择该模式时加载 |
-| pdfjs-dist | 6.3.289 | 6.3.289 | 升级；可选 peer 有迁移要求 |
-| @internationalized/date | 3.12.4 | 3.12.4 | 已是最新 |
-| @radix-ui/react-dialog / react-popover | 1.1.23 | 1.1.23 | 已是最新 |
-| @radix-ui/react-select | 2.3.7 | 2.3.7 | 已是最新 |
-| @radix-ui/react-toast | 1.2.23 | 1.2.23 | 已是最新 |
-| @radix-ui/react-tooltip | 1.2.16 | 1.2.16 | 已是最新 |
-| @rc-component/cascader | 1.25.0 | 1.25.0 | 已是最新 |
-| react-aria-components | 1.21.1 | 1.21.1 | 升级 |
-| cn-division | 2026.0.1 | 2026.0.1 | 升级 |
-| @playwright/test | 1.63.0 | 1.63.0 | 已是最新 |
-| @testing-library/jest-dom | 7.0.1 | 7.0.1 | 升级 |
-| @testing-library/react | 16.3.3 | 16.3.3 | 固定最新版本 |
-| jsdom | 30.0.1 | 30.0.1 | 升级；本地 Node 24.19 |
-| typescript | 6.0.3 | 7.0.2 | 最新兼容分支，原因见下文 |
-| vite | 8.3.0 | 8.3.0 | 升级至 Rolldown/Oxc 构建链 |
-| vitest | 5.0.0 | 5.0.0 | 升级 |
-| dayjs | 1.11.23 | 1.11.23 | 仅新增为日期筛选回归的开发依赖 |
-
-## 兼容例外
-
-**MUI 7.3.11。** MRT 3.2.1 的 peer 声明为 `@mui/material >=6`，安装器允许 MUI 9，但其内部编辑字段、选择框及部分控件仍使用 `InputProps`、`SelectProps`、`inputProps` 等旧 API。[MUI 9 迁移指南](https://mui.com/material-ui/migration/upgrade-to-v9/) 已删除这些 API。不能把宽松 peer 范围当成完成适配的证据；待 MRT 正式迁移后再升级，避免自行维护第三方分支。MUI X 是独立版本线，9.13.0 支持 MUI 7.3+，无需与 Material 同主版本。
-
-**TypeScript 6.0.3。** 实测 7.0.2 的主入口只暴露版本信息，不再提供门禁 CLI 依赖的 `createSourceFile`、`ScriptTarget` 等传统 Compiler API，导致四项门禁测试失败。其新 API 位于 `unstable/*`；本库暂保留提供稳定 Compiler API 的最新 6.x。不要在消费项目用 TypeScript 7 执行当前 `business-ui-gate`；先保留 6.x 工具环境或等待门禁解析器迁移。类型构建显式设置 `rootDir: src`，CSS 副作用导入有类型声明。
-
-## 消费与按需加载
-
-- PDF.js 4→6 是跨主版本变更：消费旧查看器的项目须同步更新 `pdfjs-dist`、worker 和文档对象类型，详见 [查看器迁移](document-viewer.md)。本次未修改或部署消费服务。
-- Lucide 1.x 已本地验证；peer 范围保留 `>=0.468.0 <2`。消费者继续使用具名导入，避免导入完整图标字典。
-- 不要求消费项目跟随升级 React 19。CI 保留 React 18/19 两条验证线；开发/测试环境采用 Node 24.15+。
-- 公共库继续保留组件模块边界；Button/TextInput 消费构建中日期与 MRT/MUI 实现模块均为零。MRT 的日期实现由其自身静态依赖引入，不因安装 Day.js 测试依赖就进入轻量组件入口。
-- 新增日期选择/清除的桌面和手机浏览器回归，使用 `LocalizationProvider` 和消费方提供的 adapter；日期适配器不是公共库强制运行依赖。
-
-## 已知上游开发警告
-
-React 19 开发模式下，Cascader 的传递依赖 `@rc-component/select@1.11.0` 仍读取 `InputComponent.ref`，触发弃用警告；两者已是上游最新稳定版。禁用的 SortableList 在 React Aria 中触发缺少拖动按钮提示。现有交互回归通过，但不能宣称控制台完全无警告；未屏蔽警告或修改第三方源码。
-
-2026-09-12 本地验证：React 18.3.1 / 19.3.0 均通过 136 项单测、类型检查、库构建、按需打包门禁和视觉矩阵构建。React 19 的 38 项公共浏览器回归及新增 2 项日期回归、React 18 的完整 40 项浏览器回归通过；React 19 的 MRT 14 项浏览器回归和样例构建通过。日期回归 fixture 另经严格 TypeScript 检查。尚未提交、执行远端 CI 或发布，消费服务未升级。
-
-后续运行 `pnpm verify`、`pnpm test:browser`、`pnpm test:mrt`，并检查 `pnpm pack` 的声明、子入口和文档清单。最新版本可从 [npm 官方 registry](https://registry.npmjs.org/) 重新核查，具体迁移参考 [Vite 8](https://vite.dev/guide/migration) 与 [MUI X 9](https://mui.com/x/migration/migration-pickers-v8/)。
+# 依赖维护与升级
+
+核查日期：2026-09-12。以下为当前工作树的未发布候选；正式 0.2.31 不包含本次升级。版本来自 npm 官方 registry 的 `latest` 标签，并排除 prerelease。直接依赖使用精确版本，传递依赖遵守上游范围，不用全局 override 强行跨主版本。
+
+## 版本清单
+
+| 依赖 | 当前候选 | 上游最新稳定版 | 结论 |
+| --- | --- | --- | --- |
+| lucide-react | 1.45.0 | 1.45.0 | 升级；消费 peer 仍允许已有 0.x |
+| react / react-dom | 19.3.0 | 19.3.0 | 默认开发版本；继续验证 18.3.1 |
+| @types/react / @types/react-dom | 19.3.0 | 19.3.0 | 与开发版本配套 |
+| material-react-table | 3.2.1 | 3.2.1 | 已是最新 |
+| @mui/material / @mui/icons-material | 7.3.11 | 9.4.0 | 最新兼容分支，原因见下文 |
+| @mui/x-date-pickers | 9.13.0 | 9.13.0 | 升级；支持 MUI 7.3+ |
+| @emotion/react | 11.14.0 | 11.14.0 | 已是最新 |
+| @emotion/styled | 11.14.1 | 11.14.1 | 升级 |
+| @embedpdf/react-pdf-viewer | 2.15.0 | 2.15.0 | 已是最新 |
+| @embedpdf/core / engines / plugin-document-manager / plugin-viewport / plugin-scroll / plugin-render / plugin-zoom / plugin-rotate / plugin-thumbnail | 2.15.0 | 2.15.0 | Headless 原生模式使用的精确版本依赖；仅选择该模式时加载 |
+| pdfjs-dist | 6.3.289 | 6.3.289 | 升级；可选 peer 有迁移要求 |
+| @internationalized/date | 3.12.4 | 3.12.4 | 已是最新 |
+| @radix-ui/react-dialog / react-popover | 1.1.23 | 1.1.23 | 已是最新 |
+| @radix-ui/react-select | 2.3.7 | 2.3.7 | 已是最新 |
+| @radix-ui/react-toast | 1.2.23 | 1.2.23 | 已是最新 |
+| @radix-ui/react-tooltip | 1.2.16 | 1.2.16 | 已是最新 |
+| @rc-component/cascader | 1.25.0 | 1.25.0 | 已是最新 |
+| react-aria-components | 1.21.1 | 1.21.1 | 升级 |
+| cn-division | 2026.0.1 | 2026.0.1 | 升级 |
+| @playwright/test | 1.63.0 | 1.63.0 | 已是最新 |
+| @testing-library/jest-dom | 7.0.1 | 7.0.1 | 升级 |
+| @testing-library/react | 16.3.3 | 16.3.3 | 固定最新版本 |
+| jsdom | 30.0.1 | 30.0.1 | 升级；本地 Node 24.19 |
+| typescript | 6.0.3 | 7.0.2 | 最新兼容分支，原因见下文 |
+| vite | 8.3.0 | 8.3.0 | 升级至 Rolldown/Oxc 构建链 |
+| vitest | 5.0.0 | 5.0.0 | 升级 |
+| dayjs | 1.11.23 | 1.11.23 | 仅新增为日期筛选回归的开发依赖 |
+
+## 兼容例外
+
+**MUI 7.3.11。** MRT 3.2.1 的 peer 声明为 `@mui/material >=6`，安装器允许 MUI 9，但其内部编辑字段、选择框及部分控件仍使用 `InputProps`、`SelectProps`、`inputProps` 等旧 API。[MUI 9 迁移指南](https://mui.com/material-ui/migration/upgrade-to-v9/) 已删除这些 API。不能把宽松 peer 范围当成完成适配的证据；待 MRT 正式迁移后再升级，避免自行维护第三方分支。MUI X 是独立版本线，9.13.0 支持 MUI 7.3+，无需与 Material 同主版本。
+
+**TypeScript 6.0.3。** 实测 7.0.2 的主入口只暴露版本信息，不再提供门禁 CLI 依赖的 `createSourceFile`、`ScriptTarget` 等传统 Compiler API，导致四项门禁测试失败。其新 API 位于 `unstable/*`；本库暂保留提供稳定 Compiler API 的最新 6.x。不要在消费项目用 TypeScript 7 执行当前 `business-ui-gate`；先保留 6.x 工具环境或等待门禁解析器迁移。类型构建显式设置 `rootDir: src`，CSS 副作用导入有类型声明。
+
+## 消费与按需加载
+
+- PDF.js 4→6 是跨主版本变更：消费旧查看器的项目须同步更新 `pdfjs-dist`、worker 和文档对象类型，详见 [查看器迁移](document-viewer.md)。本次未修改或部署消费服务。
+- Lucide 1.x 已本地验证；peer 范围保留 `>=0.468.0 <2`。消费者继续使用具名导入，避免导入完整图标字典。
+- 不要求消费项目跟随升级 React 19。CI 保留 React 18/19 两条验证线；开发/测试环境采用 Node 24.15+。
+- 公共库继续保留组件模块边界；Button/TextInput 消费构建中日期与 MRT/MUI 实现模块均为零。MRT 的日期实现由其自身静态依赖引入，不因安装 Day.js 测试依赖就进入轻量组件入口。
+- 新增日期选择/清除的桌面和手机浏览器回归，使用 `LocalizationProvider` 和消费方提供的 adapter；日期适配器不是公共库强制运行依赖。
+
+## 已知上游开发警告
+
+React 19 开发模式下，Cascader 的传递依赖 `@rc-component/select@1.11.0` 仍读取 `InputComponent.ref`，触发弃用警告；两者已是上游最新稳定版。禁用的 SortableList 在 React Aria 中触发缺少拖动按钮提示。现有交互回归通过，但不能宣称控制台完全无警告；未屏蔽警告或修改第三方源码。
+
+2026-09-12 本地验证：React 18.3.1 / 19.3.0 均通过 136 项单测、类型检查、库构建、按需打包门禁和视觉矩阵构建。React 19 的 38 项公共浏览器回归及新增 2 项日期回归、React 18 的完整 40 项浏览器回归通过；React 19 的 MRT 14 项浏览器回归和样例构建通过。日期回归 fixture 另经严格 TypeScript 检查。尚未提交、执行远端 CI 或发布，消费服务未升级。
+
+后续运行 `pnpm verify`、`pnpm test:browser`、`pnpm test:mrt`，并检查 `pnpm pack` 的声明、子入口和文档清单。最新版本可从 [npm 官方 registry](https://registry.npmjs.org/) 重新核查，具体迁移参考 [Vite 8](https://vite.dev/guide/migration) 与 [MUI X 9](https://mui.com/x/migration/migration-pickers-v8/)。

package/docs/document-viewer-v2.md

@@ -129,6 +129,8 @@ export function ContractPreview({ fileVersion, pdfUrl, token }: Props) {
 
 需要业务印章、定位标记、受控页码或单页显示时，显式选择 `renderer="headless"`。它通过 EmbedPDF 的 `Viewport`、`Scroller`、`RenderLayer`、`Rotate` 和原生缩略图插件渲染 URL/Buffer，仍使用 PDFium；React 叠层直接组合在每页上。
 
+从 0.2.45 起，Headless 与 PdfiumViewer 的正文、缩略图默认渲染源 PDF 已有批注（例如 Stamp 印章、FreeText 盖章提示）。这只控制显示，不开放编辑或修改文件；源 PDF 自身的隐藏标志仍由引擎遵守。消费方无需重新下载或自行重建签章叠层。
+
 ```tsx
 <DocumentViewerV2
   renderer="headless"
@@ -257,3 +259,9 @@ EmbedPDF 原生支持页面叠加：[Headless 入门](https://www.embedpdf.com/d
 0.2.39：原生 PDF 页面图片设为 draggable=false，防止浏览器图片拖放抢占官方文本选择手势。
 
 0.2.40 修复公共 PDF 全屏状态：Escape 调用浏览器 exitFullscreen，fullscreenchange 同步工具栏；CSS 全屏回退仍在 Escape 时退出。浏览器拒绝退出时保留真实全屏状态和退出按钮。
+
+### PDFium 0.2.44
+PdfiumViewer 支持 defaultRailCollapsed：传 true 默认收起页面侧栏，用户仍可打开。省略保留按视口初始化的行为。双指缩放逐帧提交到 PDFium 的范围和精度约束，松手保持最后比例；Ctrl/Meta+滚轮继续使用官方手势。
+
+### PDFium 0.2.46 — 2026-09-14
+保留官方 ZoomGestureWrapper 的触屏和 Ctrl/Meta+滚轮 CSS 位图预览，结束后只提交一次引擎缩放。移除0.2.44的逐帧触屏实现。修复可见页码回报被当作外部跳页命令导致的缩放后跳页。官方2.15.0预览缺少边界参数，通过精确 pnpm patch 补齐 minZoom/maxZoom 并对齐提交精度；消费方无需自行打补丁，库构建仅内联该 React 手势入口，PDFium/插件状态仍保持外部单例。补丁责任人为公共文档组件维护者，2026-10-14复核；上游具备等价能力并通过同组回归后删除补丁。