@jc-times/business-ui 0.2.55 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 0.3.0
+
+- 新增 `@jc-times/business-ui/form-controls` 轻量入口，提供 Alert、Button、LinkButton、FormField、TextInput、TextArea、SelectInput 和 Checkbox，不引入目录、日期、表格或文档查看器依赖图。
+
 # 0.2.55
 
 - 修复 `SortableList` 空列表接收区缺少最小高度、空状态和根节点拖放高亮的问题。
@@ -6,310 +10,310 @@
 - npm 自动发布流程统一改为 npmjs 公共仓库，并从 `publishConfig.access` 读取访问级别。
 
 # 0.2.53
-
-- 新增 `UserProfilePopover`：紧凑的人员标签和只读资料卡，支持姓名、编号、部门、身份标签、头像与受控打开状态；资料卡随视口在 300–560px 间缩放，并保留键盘关闭与焦点归还。
-
-## 0.2.51
-- Add MultilineAutoComplete: a single textarea with React Aria suggestions, explicit selection, free text and newlines. Preserves focus when choosing suggestions with mouse or touch.
-
-## 0.2.50
-- SortableList supports scoped transfers between nested lists, source placeholders and insertion highlights; consumers retain membership and order updates.
-- Fences stale/missing transfer items and resolves nested drop indicators to the unique current owner. Disabling drag remounts the React Aria grid to keep its hook topology stable.
-
-# 0.2.49
-
-- SortableList supports optional internal drop onto eligible items, with controlled domain callbacks and React Aria mouse, touch and keyboard behavior.
-
-# 0.2.47
-
-- 修复表格横向滚动同步条异步事件回写旧位置，避免中断触控板连续滚动；每帧最多同步一次，卸载时取消待执行同步。
-
-# 0.2.45
-
-- PDFium/Headless 正文和缩略图默认渲染 PDF 内已有批注（包括 Stamp 和 FreeText），修复审核文件签章提示缺失；不启用批注编辑，不改写源文件。
-
-# 0.2.43
-
-- 新增语义化 `LinkButton`，以真实链接承载导航和文件下载，并复用 Button 的变体、尺寸、图标无障碍和禁用样式。
-- 收紧 `LinkButton` 的必填 `href` 契约；禁用链接保留可访问语义并隔离父级点击，补充下载属性、可访问名称和真实浏览器下载回归。
-
-# 0.2.42
-
-- DataTable 新增可选底部吸附横向滚动条，在内容溢出时显示并与 MRT 原生滚动区双向同步；支持业务化无障碍名称，默认不改变既有表格布局。
-
-# 0.2.41
-
-- 修复高分屏上 PDFium 左侧缩略图按设备像素尺寸显示而被裁切的问题；缩略图按插件逻辑尺寸完整缩放并保持高清渲染。
-
-# 0.2.40
-
-- 公共 PDF 全屏在 Escape 时退出浏览器原生全屏，由 fullscreenchange 同步状态，避免退出按钮提前消失。
-
-# 0.2.39
-
-- 禁用 PDFium RenderLayer 图片的浏览器原生拖放，避免正文拖选被 dragstart/pointercancel 截断。
-
-# 0.2.38
-
-- Headless 正文选择后 Ctrl/Cmd+C 调用官方 selection.copyToClipboard；保留 PDF CopyContents 权限检查与输入框原生复制。
-
-# Changelog
-
-## 0.2.54
-
-- PDFium Headless 新增 `mobileMode="continuous-reader"`：手机/粗指针连续阅读时恢复原生纵向滚动，收起缩略图与分页底栏，并压缩工具栏；`searchMode="collapsible"` 统一提供搜索开关和手机图标布局。
-
-## 0.2.48
-
-- Cascader：按可见视口处理多列展开的边缘碰撞，修复右侧表单区县列超出屏幕的问题。
-- 回归：1280px 右侧340px表单旧逻辑浮层右边缘为1395px；修正后保持在1280px内。
-
-## 0.2.37
-
-- Headless 新增可选 initialZoom="fit-width"，通过官方缩放插件适配窄屏；既有默认比例与受控 zoom 保持兼容。
-
-## 0.2.36
-
-- Headless 单页/连续模式搜索定位到匹配区域，缩放、旋转和视口变化后保持匹配区域可见。
-
-## 0.2.35
-
-- Headless 初始非零旋转等待文档打开后应用，避免恢复已保存视角时引擎抛出未加载错误。
-## 0.2.34
-
-- 新增 `pdfium-viewer` 专用按需加载入口，避免独立查看页面打包旧渲染器与完整外壳。
-
-- 修复 Headless 页码切换与缩放、旋转后的滚动定位；窄屏切换时同步收起缩略图栏。
-
-## 0.2.33
-
-- PDFium Headless 新增可配置搜索、文本选择和双指缩放，复用官方插件；业务叠层通过 data-pdf-business-control 排除正文选择事件。
-- 新增受控 zoom/rotation、变化回调及 showToolbar，支持消费方保留业务工具栏。
-
-# 0.2.32
-
-- document-viewer-v2 新增 `renderer="headless"`：URL/Buffer 使用 EmbedPDF 原生页面层，支持 React `renderPageOverlay`、受控页码、单页/连续模式、缩略图、缩放旋转和全屏；默认成品工具栏与 V1 对象兼容路径保留。
-- document-viewer-v2 新增图片与 V1 完整调用兼容：同名 DocumentViewer、全部旧参数和底层组合导出；PDFium 仅 URL/Buffer 模式按需加载，图片与旧 PDF 对象不初始化 PDFium。原对象渲染路径仍是 PDF.js，不等同于统一引擎迁移。
-
-- 升级直接依赖至当前最新稳定版或已验证的兼容稳定版，详见 docs/dependencies.md；开发环境使用 React 19.3，保留 React 18 兼容测试。
-- Lucide 升级至 1.45.0，peer 范围兼容 0.x/1.x；MUI 使用 7.3.11（MRT 尚使用 MUI 9 已移除 API），MUI X 日期选择器升级至 9.13.0。
-- PDF.js 可选 peer 升级至 6.3.289，消费方须同步升级引擎与 worker；画布渲染适配新 canvas 参数。Vite 8/Vitest 5 与 TypeScript 6 构建链升级，保留按需打包门禁。
-
-# 0.2.31
-
-- DataTable 使用 MRT 渲染内核并保留原参数兼容；新增完整配置 options、useDataTable/DataTableView、DataTableTheme、通用 DataTableMergedRows 以及 data-table 独立入口。MRT/MUI及配套库转为正式依赖。
-- 构建保留组件模块边界，修复主入口带入未使用日期组件的问题；新增 Button/TextInput 不包含日期与表格实现的消费构建门禁。项目管理实际入口复验 JS 从178.51降至83.31 KiB gzip，但其80 KiB JS/14.5 KiB CSS门禁仍未全部通过，消费方预算验收仍待完成。
-# 0.2.30
-
-- SegmentedControl 新增 soft 浅底、block 收缩宽度、orientation 纵向、shape 胶囊和 icon/选项可访问名称；保留默认实色整行 API，补齐粗指针 44px 点击区域。
-- 优化 SortableList 大列表渲染，将逐行线性索引改为一次性索引，避免 O(n²) 扫描。
-- 优化 MultiSelect 大数据量与选满状态：复用选择、标签和虚拟布局引用，并用 Set 做常数时间成员查询。
-- 新增通用 Cascader、扁平层级转换与 ID 路径索引，支持单选、多选、搜索、独立/联动选择、按需加载、表单、弹窗和窄屏底部面板；聚焦不自动展开。
-- StructuredAddressInput 复用 Cascader，默认取消地址类型选择；海外作为顶级地区，旧模式显式启用时使用公共 Select。
-- 新增基于 EmbedPDF/PDFium 的 `document-viewer-v2` 灰度迁移入口，支持 URL 加载模式配置和 ArrayBuffer；沿用完整响应式工具栏，并用公共令牌统一按钮、缩放组合框、选中/悬停/焦点与触屏尺寸。旧 PDF/图片复合入口作为存量兼容能力继续保留，未来仅在消费迁移和破坏性版本评估完成后考虑移除。固定版本的 PDFium 编排器仍会完整获取 URL 内容，不能将 `range-request` 配置视为已实现分段下载；完整边界见 `docs/document-viewer-v2.md`。
-- 增加 Agent 选型指南、API/专题导航、Cascader/PDF V2 接入文档和多视口验收说明；MRT 合同台账保留为仓库内选型样例，不作为公共导出。
-
-# 0.2.29
-
-- 修复 SortableList 隐藏拖动手柄时卡片按内容缩宽的问题；桌面与触屏保持整行等宽。
-
-# 0.2.27
-
-- 新增整行分段单选 `SegmentedControl`，统一可访问的状态切换、键盘操作、禁用态和触屏尺寸。
-
-# 0.2.26
-
-- MultiSelect 保持空结果菜单，支持按需异步搜索的加载状态及结果展示。
-
-# 0.2.25
-
-- 新增基于 React Aria 的受控可访问排序列表，统一卡片的鼠标、触屏和键盘拖动排序交互。
-
-# 0.2.24
-
-- 新增公共上传前处理组件、取消与错误弹窗及复用 hook；支持异步解密适配、整批成功后提交、资源切换取消和处理后类型/大小复检。
-
-# 0.2.23
-
-- 修复旋转/缩放定位计时器覆盖用户随后跳页的问题；定位仅在原页面仍被选中时执行。补充桌面/手机连续操作回归。
-
-# Changelog
-
-## 0.2.21 - 2026-09-07
-
-- Add `moneyFormat` to numeric inputs: symbol/unit/number resting displays with numeric-only drafts and commits.
-- Export exact decimal and integer money formatting through the React-free `@jc-times/business-ui/amount-format` entry for documents and servers.
-
-## 0.2.20 - 2026-09-06
-
-- Adopt Radix Dialog/Toast and React Aria Calendar; share modal portal ownership and arbitrate Escape across Radix/React Aria overlays.
-- Fix date readOnly, tree IME confirmation/native form ID submission, persistent toast eviction, and replacement toast expiry.
-- Add date constraints/month jump/validation, search MultiSelect and independent TreeSelect multi-selection, directory TTL/refresh/reset semantics, server table sorting/selection summaries/column visibility, and detailed file size/count/type rejection.
-- Mark CSS as a package side effect; add Chromium desktop/mobile integration tests and React 18/19 CI coverage.
-- Migration: TreeSelect submits IDs by default (formValueMode="label" retains label submission); excess toasts queue instead of evicting existing messages. See docs/maturity-migration.md.
-
-## 0.2.19
-
-- Isolate async option and tree row rendering so highlight changes skip unchanged row content; preserve tree expansion and keyboard semantics.
-- Keep TextInput callback refs stable across value updates and reuse address path/search indexes across queries.
-- Bound AsyncDirectoryPicker queries with an LRU cache (default 50, configurable via cacheSize; zero disables caching).
-- Add performance regression coverage for option render counts, ref lifetimes, address index invalidation and cache eviction.
-
-## 0.2.18
-
-- Keep the internal file input out of keyboard and accessibility navigation so each `FileDropzone` exposes one control.
-
-## 0.2.17
-
-- Publish maintained Chinese address regions through an independent subpath so applications can load the dataset only on address-entry routes.
-
-## 0.2.16
-
-- Prevent disabled `FileDropzone` surfaces from handing dropped files to the browser.
-
-## 0.2.15
-
-- Add `FileDropzone` as the single shared file-selection surface for click, keyboard and drag-and-drop input.
-- Let `StructuredAddressInput` use maintained Chinese province/city/district data by default, append an `海外` top-level region, and optionally hide the legacy address-mode selector.
-
-## 0.2.14
-
-- Add `minimumFractionDigits` to numeric inputs for fixed currency and percentage display without padding active drafts or changing committed values. Empty values stay empty.
-
-## 0.2.13
-
-- Add `startAdornment` and `endAdornment` slots to `TextInput`; `NumericInput` and `ScaledNumericInput` inherit the same API.
-- Keep the existing input-only DOM when slots are absent, and preserve the native input ref, attributes, label, help and error associations when slots are present.
-- Keep adorned controls on the shared 40px default and 44px coarse-pointer size contract, with wrapper-level focus and invalid states.
-
-## 0.2.12
-
-- Keep directory inputs editable during searches; suppress focus queries for existing selections and defer IME searches until composition ends.
-- Dismiss async results on selection, outside pointer, blur, Tab and Escape without reopening on late responses.
-- Cancel superseded requests before cache reuse/selection and restore committed text when async selection fails.
-
-## 0.2.11
-
-- Hold directory searches while Backspace or Delete remains pressed, then debounce one search for the final value
-  after key release.
-
-## 0.2.10
-
-- Prevent `AsyncSearchPicker` from reading a stale highlighted item when an async owner clears its result list,
-  avoiding a render crash while typing a new query.
-
-## 0.2.9
-
-- Add `AsyncDirectoryPicker`, a generic remote directory selector with debounced search, request cancellation,
-  stale-result fencing, owner resets, selected-label synchronization, caching, and shared async states.
-
-## 0.2.8 — 2026-09-06
-
-- 新增 NumericInput 精确字符串数字输入与 ScaledNumericInput 安全整数缩放适配；支持自然中间态、十进制舍入、上下限、千分位、失焦/回车提交及显式全选。
-- 复用 TextInput/FormField 的样式、ARIA、ref 与原生属性；补齐交互测试、视觉矩阵及迁移文档。
-- 兼容既有 API；包含 0.2.6–0.2.7 尚未发布的公共能力。
-
-## 0.2.7 - 2026-09-05
-
-- DataTable 的 `mobileLayout="cards"` 改为按表格自身容器宽度响应；嵌入窄浮层、侧栏或分栏时无需等待整个视口缩至 600px，默认 `scroll` 模式保持不变。
-
-## 0.2.6 - 2026-09-05
-
-- 将 ModalShell 的 `.ui-modal-header`、`.ui-modal-content`、`.ui-modal-footer` 面板直接子节点声明为稳定兼容契约；固定底栏必须使用 `footer` / `footerClassName`，不再建议依赖 children 内原生 `<footer>` 或内部层级选择器。
-- ModalShell 新增 `contentClassName` / `contentProps`，允许消费方对正文滚动区透传 ref、data、ARIA 和原生 div 属性，同时保留公共契约 class。
-- 开发环境会警告“直接 footer child 且未传 footer prop”的旧式调用，但不会自动搬运节点或猜测业务结构。
-- `business-ui-gate` 新增 `legacyModalFooter` 检测，覆盖命名别名、`Dialog`、namespace 以及条件/Fragment JSX，并提供明确迁移提示；普通业务组件 footer 不受影响。
-- 补齐 ModalShell DOM、无 footer、自定义正文/底栏、手机全屏与短横屏的消费兼容回归。
-- 新增业务无关的 `TreeSelect`，支持任意层级、受控/非受控状态、路径搜索、键盘树导航、无障碍语义，以及手机底部候选面板。
-- 新增 `StructuredAddressInput`，提供可注入地区树的级联选择、整路径搜索、详细地址和非标准地址回退；区划数据、字符串解析/格式化及业务字段映射由消费方持有。
-- TextInput、SelectInput 与 Button 的默认视觉高度改为显式统一的 border-box 40px，触屏最小操作高度继续提升至 44px，避免原生 select 在不同 WebView/系统缩放下发生同行错位。
-
-## 0.2.5 - 2026-09-04
-
-- 增强公共移动能力：Modal 全屏安全区与固定头尾、Select 手机底部抽屉、Dropdown/Popover 短视口滚动、AsyncSearchPicker 软键盘动态高度、320px 分页简化、DataTable 卡片长文本/选择/操作/空状态，以及 Toast/ConfirmDialog 安全区和长文案堆叠。
-- 触屏原生 SelectInput 与其他表单控件统一使用 44px 最小点击高度；表单错误提示不再拉伸同行控件。
-- DropdownMenu/Menu 新增类型安全的单选/多选状态，分别输出 `menuitemradio` / `menuitemcheckbox` 与 `aria-checked`；菜单项可独立声明 `aria-current`，并提供起始图标、尾部状态和选中图标槽。
-- DropdownMenu 补齐触发器、菜单及菜单项的 ARIA/data 属性与 ref 透传，继续由 React Aria 保证方向键、Home/End、Escape、焦点归还与禁用项行为；触屏菜单项使用 44px 最小高度，短视口菜单可内部滚动。
-- PageHeader 新增稳定的 `copyProps` / `actionsProps` 布局槽，并改善长标题与操作区在窄屏、横屏下的换行；Badge 在 flex/截断容器中保持尺寸并按文字基线对齐。
-- DataTable 新增向后兼容的 `mobileLayout="cards"` 可选契约，以及根节点/表格属性与 ref 透传；默认仍为水平滚动，不改变 0.2.4 调用的 DOM 与布局。
-- MetricCard、SectionCard 与既有 DataTable 调用完成真实消费审计；响应式 ActionMenu/ActionSheet 因没有第二个独立生产场景暂缓，UI 门禁保持现状。
-
-## 0.2.4 - 2026-09-04
-
-- 新增无业务状态映射的 Badge，提供五档语义 tone、两档 size、原生 span 属性与 ref。
-- 新增 MetricCard，以 label、value、description、icon 和 tone 插槽承载已格式化指标，不接管业务计算或格式化。
-- 新增页面级 PageHeader 和带可访问区域名称的 SectionCard，统一标题、说明、操作区、响应式换行与原生属性/ref。
-- 四个展示组件均保持无状态、无 Effect、无布局测量和零新增运行时依赖，并纳入单元测试与多视口验收矩阵。
-
-## 0.2.3 - 2026-09-04
-
-- DataTable 单元格增加自动移动端标签，并允许通过 `mobileLabel` 覆盖复杂表头的标签文本，便于消费项目实现无业务耦合的响应式卡片表格。
-
-## 0.2.2 - 2026-09-04
-
-- 新增泛型 `useDebouncedValue<T>(value, delay)`，支持值/延迟变化时重置计时器和卸载清理，不接管输入或请求生命周期。
-
-## 0.2.1 - 2026-09-04
-
-- ModalShell 内建栈顶焦点陷阱、初始/归还焦点、背景滚动锁与可配置 Escape，关闭按钮复用 Button。
-- Select、Combobox/AutoComplete、ToggleSwitch 和 DateInput 补齐明确的原生属性、ref 与浮层 placement/portal API。
-- DateInput 增加方向键、Home/End、PageUp/PageDown 和按年翻页的日历焦点管理。
-- iconOnly Button 在 TypeScript 层要求 `aria-label`。
-- 新增无业务 DTO 的 AsyncSearchPicker、具备正确 menu 语义的 DropdownMenu/Menu，以及非锚点 ConfirmDialog。
-- UI gate 新增手写 menu、combobox/listbox/option 回归检测，并补充公共 API 文档、示例和交互测试。
-- 缓存 DataTable 排序值并隔离行级重渲染，降低大表排序与选择操作的重复计算。
-- 为 AutoComplete 建立选项索引，并稳定 Combobox 集合引用，改善大列表输入响应。
-- 合并 DateInput 高频滚动/缩放定位测量，避免同一帧内重复布局计算。
-- 将 TypeScript 调整为开发依赖，并声明运行时代码无副作用，减少消费端安装与打包负担。
-
-## 0.2.0 - 2026-09-04
-
-- 新增 Alert、EmptyState、Skeleton 与 SkeletonText 公共反馈组件。
-- 新增 Tooltip、Popover、Popconfirm、Select、Combobox、AutoComplete、ToastProvider/useToast 与 DataTable。
-- 浮层和 Select 采用固定版本 Radix Primitives；Combobox/AutoComplete 采用 React Aria，并支持大列表虚拟化。
-- 建立三档动效时长与缓动令牌，统一按钮忙碌、弹窗、日期浮层和禁用原因提示的状态反馈。
-- 所有新增动画支持 `prefers-reduced-motion`，并补充手机与桌面响应式验收场景。
-- 增加标签与包版本严格匹配、凭据临时注入的内部 registry 发布脚本。
-- 增加 CI 验证、标签发布流水线和发布治理文档。
-- 增加组件多视口验收页面，并完成手机、平板和桌面三档检查。
-
-## 0.1.2 - 2026-09-04
-
-- UI 门禁增加 `--only`，允许已有按钮/控件门禁的项目只启用公共弹层门禁。
-
-## 0.1.1 - 2026-09-04
-
-- ModalShell 统一处理栈顶 Escape 关闭；焦点管理支持指定初始焦点，并在挂载提交后立即建立焦点所有权。
-- UI 门禁只把原生 DOM 弹层计为手写弹层，避免误报组件属性。
-
-## 0.1.0 - 2026-09-04
-
-- 首次发布 Button、ExplainableButton、ModalShell、FormField、DateInput、Pagination、RovingTabs、ToggleSwitch、RecoverableAsyncState 与 useModalFocusTrap。
-- 建立中性语义令牌和跨项目 UI 门禁命令。
-# 0.2.22
-
-- 提供独立 document-viewer 子入口，统一 PDF/图片预览、连续翻页、缩略图、缩放、旋转与全屏；通过组合插槽保留消费方领域交互。
-- 提取有界 PDF 画布渲染与取消队列，增加页级失败反馈和独立 document-render-budget 纯函数入口。
-- PDF.js 4.10.38 为可选 peer；加载、worker、权限和打开密码由消费方管理。见 docs/document-viewer.md。
-# 0.2.28
-
-- PDF toolbar uses compact ghost icon controls, a single-row layout and touch-sized targets.
-
-### 本地待发布：通用 Cascader
-
-- 新增基于 @rc-component/cascader@1.25.0 的 Cascader、扁平层级转换与 ID 路径索引；默认独立多选，保留主题、表单和弹窗约定。
-- StructuredAddressInput 复用级联内核，保留受控数据及详细地址；地区摘要以选择框文本显示，搜索 input.value 不再代表已选摘要。
-- 增加部门/地址接入指南、MIT 许可与桌面/触屏回归。TreeSelect 保持兼容；未升级消费项目。
-
-- Cascader 取消聚焦自动展开：标签点击和 Tab 只聚焦；保留点击、输入搜索与方向键展开。
-
-- StructuredAddressInput 默认取消地址类型，海外使用顶级地区；旧模式显式启用时复用公共 Select，不再手写原生 select。
-
-## 0.2.44 — 2026-09-14
-- PDFium 双指缩放使用统一引擎比例，修复松手边界回跳；增加 defaultRailCollapsed 侧栏初始配置。
-
-## 0.2.45 — 2026-09-14
-- 恢复官方低开销触控缩放；修复可见页码回传造成的跳页，触屏/滚轮预览和提交使用同一缩放边界。
-
-## 0.2.52
-- AutoComplete and Combobox accept grouped options with non-selectable, muted headings and preserve filtering and keyboard selection.
+
+- 新增 `UserProfilePopover`：紧凑的人员标签和只读资料卡，支持姓名、编号、部门、身份标签、头像与受控打开状态；资料卡随视口在 300–560px 间缩放，并保留键盘关闭与焦点归还。
+
+## 0.2.51
+- Add MultilineAutoComplete: a single textarea with React Aria suggestions, explicit selection, free text and newlines. Preserves focus when choosing suggestions with mouse or touch.
+
+## 0.2.50
+- SortableList supports scoped transfers between nested lists, source placeholders and insertion highlights; consumers retain membership and order updates.
+- Fences stale/missing transfer items and resolves nested drop indicators to the unique current owner. Disabling drag remounts the React Aria grid to keep its hook topology stable.
+
+# 0.2.49
+
+- SortableList supports optional internal drop onto eligible items, with controlled domain callbacks and React Aria mouse, touch and keyboard behavior.
+
+# 0.2.47
+
+- 修复表格横向滚动同步条异步事件回写旧位置，避免中断触控板连续滚动；每帧最多同步一次，卸载时取消待执行同步。
+
+# 0.2.45
+
+- PDFium/Headless 正文和缩略图默认渲染 PDF 内已有批注（包括 Stamp 和 FreeText），修复审核文件签章提示缺失；不启用批注编辑，不改写源文件。
+
+# 0.2.43
+
+- 新增语义化 `LinkButton`，以真实链接承载导航和文件下载，并复用 Button 的变体、尺寸、图标无障碍和禁用样式。
+- 收紧 `LinkButton` 的必填 `href` 契约；禁用链接保留可访问语义并隔离父级点击，补充下载属性、可访问名称和真实浏览器下载回归。
+
+# 0.2.42
+
+- DataTable 新增可选底部吸附横向滚动条，在内容溢出时显示并与 MRT 原生滚动区双向同步；支持业务化无障碍名称，默认不改变既有表格布局。
+
+# 0.2.41
+
+- 修复高分屏上 PDFium 左侧缩略图按设备像素尺寸显示而被裁切的问题；缩略图按插件逻辑尺寸完整缩放并保持高清渲染。
+
+# 0.2.40
+
+- 公共 PDF 全屏在 Escape 时退出浏览器原生全屏，由 fullscreenchange 同步状态，避免退出按钮提前消失。
+
+# 0.2.39
+
+- 禁用 PDFium RenderLayer 图片的浏览器原生拖放，避免正文拖选被 dragstart/pointercancel 截断。
+
+# 0.2.38
+
+- Headless 正文选择后 Ctrl/Cmd+C 调用官方 selection.copyToClipboard；保留 PDF CopyContents 权限检查与输入框原生复制。
+
+# Changelog
+
+## 0.2.54
+
+- PDFium Headless 新增 `mobileMode="continuous-reader"`：手机/粗指针连续阅读时恢复原生纵向滚动，收起缩略图与分页底栏，并压缩工具栏；`searchMode="collapsible"` 统一提供搜索开关和手机图标布局。
+
+## 0.2.48
+
+- Cascader：按可见视口处理多列展开的边缘碰撞，修复右侧表单区县列超出屏幕的问题。
+- 回归：1280px 右侧340px表单旧逻辑浮层右边缘为1395px；修正后保持在1280px内。
+
+## 0.2.37
+
+- Headless 新增可选 initialZoom="fit-width"，通过官方缩放插件适配窄屏；既有默认比例与受控 zoom 保持兼容。
+
+## 0.2.36
+
+- Headless 单页/连续模式搜索定位到匹配区域，缩放、旋转和视口变化后保持匹配区域可见。
+
+## 0.2.35
+
+- Headless 初始非零旋转等待文档打开后应用，避免恢复已保存视角时引擎抛出未加载错误。
+## 0.2.34
+
+- 新增 `pdfium-viewer` 专用按需加载入口，避免独立查看页面打包旧渲染器与完整外壳。
+
+- 修复 Headless 页码切换与缩放、旋转后的滚动定位；窄屏切换时同步收起缩略图栏。
+
+## 0.2.33
+
+- PDFium Headless 新增可配置搜索、文本选择和双指缩放，复用官方插件；业务叠层通过 data-pdf-business-control 排除正文选择事件。
+- 新增受控 zoom/rotation、变化回调及 showToolbar，支持消费方保留业务工具栏。
+
+# 0.2.32
+
+- document-viewer-v2 新增 `renderer="headless"`：URL/Buffer 使用 EmbedPDF 原生页面层，支持 React `renderPageOverlay`、受控页码、单页/连续模式、缩略图、缩放旋转和全屏；默认成品工具栏与 V1 对象兼容路径保留。
+- document-viewer-v2 新增图片与 V1 完整调用兼容：同名 DocumentViewer、全部旧参数和底层组合导出；PDFium 仅 URL/Buffer 模式按需加载，图片与旧 PDF 对象不初始化 PDFium。原对象渲染路径仍是 PDF.js，不等同于统一引擎迁移。
+
+- 升级直接依赖至当前最新稳定版或已验证的兼容稳定版，详见 docs/dependencies.md；开发环境使用 React 19.3，保留 React 18 兼容测试。
+- Lucide 升级至 1.45.0，peer 范围兼容 0.x/1.x；MUI 使用 7.3.11（MRT 尚使用 MUI 9 已移除 API），MUI X 日期选择器升级至 9.13.0。
+- PDF.js 可选 peer 升级至 6.3.289，消费方须同步升级引擎与 worker；画布渲染适配新 canvas 参数。Vite 8/Vitest 5 与 TypeScript 6 构建链升级，保留按需打包门禁。
+
+# 0.2.31
+
+- DataTable 使用 MRT 渲染内核并保留原参数兼容；新增完整配置 options、useDataTable/DataTableView、DataTableTheme、通用 DataTableMergedRows 以及 data-table 独立入口。MRT/MUI及配套库转为正式依赖。
+- 构建保留组件模块边界，修复主入口带入未使用日期组件的问题；新增 Button/TextInput 不包含日期与表格实现的消费构建门禁。项目管理实际入口复验 JS 从178.51降至83.31 KiB gzip，但其80 KiB JS/14.5 KiB CSS门禁仍未全部通过，消费方预算验收仍待完成。
+# 0.2.30
+
+- SegmentedControl 新增 soft 浅底、block 收缩宽度、orientation 纵向、shape 胶囊和 icon/选项可访问名称；保留默认实色整行 API，补齐粗指针 44px 点击区域。
+- 优化 SortableList 大列表渲染，将逐行线性索引改为一次性索引，避免 O(n²) 扫描。
+- 优化 MultiSelect 大数据量与选满状态：复用选择、标签和虚拟布局引用，并用 Set 做常数时间成员查询。
+- 新增通用 Cascader、扁平层级转换与 ID 路径索引，支持单选、多选、搜索、独立/联动选择、按需加载、表单、弹窗和窄屏底部面板；聚焦不自动展开。
+- StructuredAddressInput 复用 Cascader，默认取消地址类型选择；海外作为顶级地区，旧模式显式启用时使用公共 Select。
+- 新增基于 EmbedPDF/PDFium 的 `document-viewer-v2` 灰度迁移入口，支持 URL 加载模式配置和 ArrayBuffer；沿用完整响应式工具栏，并用公共令牌统一按钮、缩放组合框、选中/悬停/焦点与触屏尺寸。旧 PDF/图片复合入口作为存量兼容能力继续保留，未来仅在消费迁移和破坏性版本评估完成后考虑移除。固定版本的 PDFium 编排器仍会完整获取 URL 内容，不能将 `range-request` 配置视为已实现分段下载；完整边界见 `docs/document-viewer-v2.md`。
+- 增加 Agent 选型指南、API/专题导航、Cascader/PDF V2 接入文档和多视口验收说明；MRT 合同台账保留为仓库内选型样例，不作为公共导出。
+
+# 0.2.29
+
+- 修复 SortableList 隐藏拖动手柄时卡片按内容缩宽的问题；桌面与触屏保持整行等宽。
+
+# 0.2.27
+
+- 新增整行分段单选 `SegmentedControl`，统一可访问的状态切换、键盘操作、禁用态和触屏尺寸。
+
+# 0.2.26
+
+- MultiSelect 保持空结果菜单，支持按需异步搜索的加载状态及结果展示。
+
+# 0.2.25
+
+- 新增基于 React Aria 的受控可访问排序列表，统一卡片的鼠标、触屏和键盘拖动排序交互。
+
+# 0.2.24
+
+- 新增公共上传前处理组件、取消与错误弹窗及复用 hook；支持异步解密适配、整批成功后提交、资源切换取消和处理后类型/大小复检。
+
+# 0.2.23
+
+- 修复旋转/缩放定位计时器覆盖用户随后跳页的问题；定位仅在原页面仍被选中时执行。补充桌面/手机连续操作回归。
+
+# Changelog
+
+## 0.2.21 - 2026-09-07
+
+- Add `moneyFormat` to numeric inputs: symbol/unit/number resting displays with numeric-only drafts and commits.
+- Export exact decimal and integer money formatting through the React-free `@jc-times/business-ui/amount-format` entry for documents and servers.
+
+## 0.2.20 - 2026-09-06
+
+- Adopt Radix Dialog/Toast and React Aria Calendar; share modal portal ownership and arbitrate Escape across Radix/React Aria overlays.
+- Fix date readOnly, tree IME confirmation/native form ID submission, persistent toast eviction, and replacement toast expiry.
+- Add date constraints/month jump/validation, search MultiSelect and independent TreeSelect multi-selection, directory TTL/refresh/reset semantics, server table sorting/selection summaries/column visibility, and detailed file size/count/type rejection.
+- Mark CSS as a package side effect; add Chromium desktop/mobile integration tests and React 18/19 CI coverage.
+- Migration: TreeSelect submits IDs by default (formValueMode="label" retains label submission); excess toasts queue instead of evicting existing messages. See docs/maturity-migration.md.
+
+## 0.2.19
+
+- Isolate async option and tree row rendering so highlight changes skip unchanged row content; preserve tree expansion and keyboard semantics.
+- Keep TextInput callback refs stable across value updates and reuse address path/search indexes across queries.
+- Bound AsyncDirectoryPicker queries with an LRU cache (default 50, configurable via cacheSize; zero disables caching).
+- Add performance regression coverage for option render counts, ref lifetimes, address index invalidation and cache eviction.
+
+## 0.2.18
+
+- Keep the internal file input out of keyboard and accessibility navigation so each `FileDropzone` exposes one control.
+
+## 0.2.17
+
+- Publish maintained Chinese address regions through an independent subpath so applications can load the dataset only on address-entry routes.
+
+## 0.2.16
+
+- Prevent disabled `FileDropzone` surfaces from handing dropped files to the browser.
+
+## 0.2.15
+
+- Add `FileDropzone` as the single shared file-selection surface for click, keyboard and drag-and-drop input.
+- Let `StructuredAddressInput` use maintained Chinese province/city/district data by default, append an `海外` top-level region, and optionally hide the legacy address-mode selector.
+
+## 0.2.14
+
+- Add `minimumFractionDigits` to numeric inputs for fixed currency and percentage display without padding active drafts or changing committed values. Empty values stay empty.
+
+## 0.2.13
+
+- Add `startAdornment` and `endAdornment` slots to `TextInput`; `NumericInput` and `ScaledNumericInput` inherit the same API.
+- Keep the existing input-only DOM when slots are absent, and preserve the native input ref, attributes, label, help and error associations when slots are present.
+- Keep adorned controls on the shared 40px default and 44px coarse-pointer size contract, with wrapper-level focus and invalid states.
+
+## 0.2.12
+
+- Keep directory inputs editable during searches; suppress focus queries for existing selections and defer IME searches until composition ends.
+- Dismiss async results on selection, outside pointer, blur, Tab and Escape without reopening on late responses.
+- Cancel superseded requests before cache reuse/selection and restore committed text when async selection fails.
+
+## 0.2.11
+
+- Hold directory searches while Backspace or Delete remains pressed, then debounce one search for the final value
+  after key release.
+
+## 0.2.10
+
+- Prevent `AsyncSearchPicker` from reading a stale highlighted item when an async owner clears its result list,
+  avoiding a render crash while typing a new query.
+
+## 0.2.9
+
+- Add `AsyncDirectoryPicker`, a generic remote directory selector with debounced search, request cancellation,
+  stale-result fencing, owner resets, selected-label synchronization, caching, and shared async states.
+
+## 0.2.8 — 2026-09-06
+
+- 新增 NumericInput 精确字符串数字输入与 ScaledNumericInput 安全整数缩放适配；支持自然中间态、十进制舍入、上下限、千分位、失焦/回车提交及显式全选。
+- 复用 TextInput/FormField 的样式、ARIA、ref 与原生属性；补齐交互测试、视觉矩阵及迁移文档。
+- 兼容既有 API；包含 0.2.6–0.2.7 尚未发布的公共能力。
+
+## 0.2.7 - 2026-09-05
+
+- DataTable 的 `mobileLayout="cards"` 改为按表格自身容器宽度响应；嵌入窄浮层、侧栏或分栏时无需等待整个视口缩至 600px，默认 `scroll` 模式保持不变。
+
+## 0.2.6 - 2026-09-05
+
+- 将 ModalShell 的 `.ui-modal-header`、`.ui-modal-content`、`.ui-modal-footer` 面板直接子节点声明为稳定兼容契约；固定底栏必须使用 `footer` / `footerClassName`，不再建议依赖 children 内原生 `<footer>` 或内部层级选择器。
+- ModalShell 新增 `contentClassName` / `contentProps`，允许消费方对正文滚动区透传 ref、data、ARIA 和原生 div 属性，同时保留公共契约 class。
+- 开发环境会警告“直接 footer child 且未传 footer prop”的旧式调用，但不会自动搬运节点或猜测业务结构。
+- `business-ui-gate` 新增 `legacyModalFooter` 检测，覆盖命名别名、`Dialog`、namespace 以及条件/Fragment JSX，并提供明确迁移提示；普通业务组件 footer 不受影响。
+- 补齐 ModalShell DOM、无 footer、自定义正文/底栏、手机全屏与短横屏的消费兼容回归。
+- 新增业务无关的 `TreeSelect`，支持任意层级、受控/非受控状态、路径搜索、键盘树导航、无障碍语义，以及手机底部候选面板。
+- 新增 `StructuredAddressInput`，提供可注入地区树的级联选择、整路径搜索、详细地址和非标准地址回退；区划数据、字符串解析/格式化及业务字段映射由消费方持有。
+- TextInput、SelectInput 与 Button 的默认视觉高度改为显式统一的 border-box 40px，触屏最小操作高度继续提升至 44px，避免原生 select 在不同 WebView/系统缩放下发生同行错位。
+
+## 0.2.5 - 2026-09-04
+
+- 增强公共移动能力：Modal 全屏安全区与固定头尾、Select 手机底部抽屉、Dropdown/Popover 短视口滚动、AsyncSearchPicker 软键盘动态高度、320px 分页简化、DataTable 卡片长文本/选择/操作/空状态，以及 Toast/ConfirmDialog 安全区和长文案堆叠。
+- 触屏原生 SelectInput 与其他表单控件统一使用 44px 最小点击高度；表单错误提示不再拉伸同行控件。
+- DropdownMenu/Menu 新增类型安全的单选/多选状态，分别输出 `menuitemradio` / `menuitemcheckbox` 与 `aria-checked`；菜单项可独立声明 `aria-current`，并提供起始图标、尾部状态和选中图标槽。
+- DropdownMenu 补齐触发器、菜单及菜单项的 ARIA/data 属性与 ref 透传，继续由 React Aria 保证方向键、Home/End、Escape、焦点归还与禁用项行为；触屏菜单项使用 44px 最小高度，短视口菜单可内部滚动。
+- PageHeader 新增稳定的 `copyProps` / `actionsProps` 布局槽，并改善长标题与操作区在窄屏、横屏下的换行；Badge 在 flex/截断容器中保持尺寸并按文字基线对齐。
+- DataTable 新增向后兼容的 `mobileLayout="cards"` 可选契约，以及根节点/表格属性与 ref 透传；默认仍为水平滚动，不改变 0.2.4 调用的 DOM 与布局。
+- MetricCard、SectionCard 与既有 DataTable 调用完成真实消费审计；响应式 ActionMenu/ActionSheet 因没有第二个独立生产场景暂缓，UI 门禁保持现状。
+
+## 0.2.4 - 2026-09-04
+
+- 新增无业务状态映射的 Badge，提供五档语义 tone、两档 size、原生 span 属性与 ref。
+- 新增 MetricCard，以 label、value、description、icon 和 tone 插槽承载已格式化指标，不接管业务计算或格式化。
+- 新增页面级 PageHeader 和带可访问区域名称的 SectionCard，统一标题、说明、操作区、响应式换行与原生属性/ref。
+- 四个展示组件均保持无状态、无 Effect、无布局测量和零新增运行时依赖，并纳入单元测试与多视口验收矩阵。
+
+## 0.2.3 - 2026-09-04
+
+- DataTable 单元格增加自动移动端标签，并允许通过 `mobileLabel` 覆盖复杂表头的标签文本，便于消费项目实现无业务耦合的响应式卡片表格。
+
+## 0.2.2 - 2026-09-04
+
+- 新增泛型 `useDebouncedValue<T>(value, delay)`，支持值/延迟变化时重置计时器和卸载清理，不接管输入或请求生命周期。
+
+## 0.2.1 - 2026-09-04
+
+- ModalShell 内建栈顶焦点陷阱、初始/归还焦点、背景滚动锁与可配置 Escape，关闭按钮复用 Button。
+- Select、Combobox/AutoComplete、ToggleSwitch 和 DateInput 补齐明确的原生属性、ref 与浮层 placement/portal API。
+- DateInput 增加方向键、Home/End、PageUp/PageDown 和按年翻页的日历焦点管理。
+- iconOnly Button 在 TypeScript 层要求 `aria-label`。
+- 新增无业务 DTO 的 AsyncSearchPicker、具备正确 menu 语义的 DropdownMenu/Menu，以及非锚点 ConfirmDialog。
+- UI gate 新增手写 menu、combobox/listbox/option 回归检测，并补充公共 API 文档、示例和交互测试。
+- 缓存 DataTable 排序值并隔离行级重渲染，降低大表排序与选择操作的重复计算。
+- 为 AutoComplete 建立选项索引，并稳定 Combobox 集合引用，改善大列表输入响应。
+- 合并 DateInput 高频滚动/缩放定位测量，避免同一帧内重复布局计算。
+- 将 TypeScript 调整为开发依赖，并声明运行时代码无副作用，减少消费端安装与打包负担。
+
+## 0.2.0 - 2026-09-04
+
+- 新增 Alert、EmptyState、Skeleton 与 SkeletonText 公共反馈组件。
+- 新增 Tooltip、Popover、Popconfirm、Select、Combobox、AutoComplete、ToastProvider/useToast 与 DataTable。
+- 浮层和 Select 采用固定版本 Radix Primitives；Combobox/AutoComplete 采用 React Aria，并支持大列表虚拟化。
+- 建立三档动效时长与缓动令牌，统一按钮忙碌、弹窗、日期浮层和禁用原因提示的状态反馈。
+- 所有新增动画支持 `prefers-reduced-motion`，并补充手机与桌面响应式验收场景。
+- 增加标签与包版本严格匹配、凭据临时注入的内部 registry 发布脚本。
+- 增加 CI 验证、标签发布流水线和发布治理文档。
+- 增加组件多视口验收页面，并完成手机、平板和桌面三档检查。
+
+## 0.1.2 - 2026-09-04
+
+- UI 门禁增加 `--only`，允许已有按钮/控件门禁的项目只启用公共弹层门禁。
+
+## 0.1.1 - 2026-09-04
+
+- ModalShell 统一处理栈顶 Escape 关闭；焦点管理支持指定初始焦点，并在挂载提交后立即建立焦点所有权。
+- UI 门禁只把原生 DOM 弹层计为手写弹层，避免误报组件属性。
+
+## 0.1.0 - 2026-09-04
+
+- 首次发布 Button、ExplainableButton、ModalShell、FormField、DateInput、Pagination、RovingTabs、ToggleSwitch、RecoverableAsyncState 与 useModalFocusTrap。
+- 建立中性语义令牌和跨项目 UI 门禁命令。
+# 0.2.22
+
+- 提供独立 document-viewer 子入口，统一 PDF/图片预览、连续翻页、缩略图、缩放、旋转与全屏；通过组合插槽保留消费方领域交互。
+- 提取有界 PDF 画布渲染与取消队列，增加页级失败反馈和独立 document-render-budget 纯函数入口。
+- PDF.js 4.10.38 为可选 peer；加载、worker、权限和打开密码由消费方管理。见 docs/document-viewer.md。
+# 0.2.28
+
+- PDF toolbar uses compact ghost icon controls, a single-row layout and touch-sized targets.
+
+### 本地待发布：通用 Cascader
+
+- 新增基于 @rc-component/cascader@1.25.0 的 Cascader、扁平层级转换与 ID 路径索引；默认独立多选，保留主题、表单和弹窗约定。
+- StructuredAddressInput 复用级联内核，保留受控数据及详细地址；地区摘要以选择框文本显示，搜索 input.value 不再代表已选摘要。
+- 增加部门/地址接入指南、MIT 许可与桌面/触屏回归。TreeSelect 保持兼容；未升级消费项目。
+
+- Cascader 取消聚焦自动展开：标签点击和 Tab 只聚焦；保留点击、输入搜索与方向键展开。
+
+- StructuredAddressInput 默认取消地址类型，海外使用顶级地区；旧模式显式启用时复用公共 Select，不再手写原生 select。
+
+## 0.2.44 — 2026-09-14
+- PDFium 双指缩放使用统一引擎比例，修复松手边界回跳；增加 defaultRailCollapsed 侧栏初始配置。
+
+## 0.2.45 — 2026-09-14
+- 恢复官方低开销触控缩放；修复可见页码回传造成的跳页，触屏/滚轮预览和提交使用同一缩放边界。
+
+## 0.2.52
+- AutoComplete and Combobox accept grouped options with non-selectable, muted headings and preserve filtering and keyboard selection.