@jc-times/business-ui 0.2.43

package/AGENTS.md

@@ -0,0 +1,6 @@
+# 公共组件维护入口
+
+- 开始组件使用、选型或修改前，先读 [Agent 使用指南](docs/agent-guide.md)，再按需读取 API 和专题文档。
+- 公共参数以当前源码和导出为准；消费项目以其安装版本的类型声明为准，不把本地新增能力当成已发布能力。
+- 新增或改变公共能力时，同步指南的场景选型、对应 API/专题和 package.json 发布文件清单。README 保持入口与导航，详细用法集中维护。
+- 通用交互、无障碍与响应式在本库实现；业务权限、接口、领域状态与文案由消费方组合。验证和发布遵循 docs/viewport-qa.md 与 docs/release.md。

package/CHANGELOG.md

@@ -0,0 +1,267 @@
+# 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.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。

package/README.md

@@ -0,0 +1,55 @@
+# @jc-times/business-ui
+
+精诚时代业务应用共用的 React 基础组件与交互标准。公共包负责通用 UI、无障碍与响应式；权限、接口、业务文案和合同、客户、订单、ERP 等领域状态由消费应用提供。
+
+**Agent 从 [docs/agent-guide.md](docs/agent-guide.md) 开始阅读：按需求选组件，再查 API 和专题。** 本仓库 [AGENTS.md](AGENTS.md) 同样指向该入口。
+
+## 安装与引入
+
+内部 registry 为 GitHub Packages（`https://npm.pkg.github.com`）。按 [发布与消费说明](docs/release.md) 配置访问，选择已发布的精确版本并提交锁文件；受控 tarball 消费也必须固定版本和制品。不要复制源码、跨仓库引用源文件或使用目录软链接。
+
+```tsx
+import { Button, ModalShell } from "@jc-times/business-ui";
+import "@jc-times/business-ui/styles.css";
+```
+
+React 等 peer dependencies 按所安装版本的 package.json 配置。应用通过 `--ui-*` 语义令牌提供主题；普通控件默认 40px，粗指针触屏最小 44px。
+
+文档查看器、行政区划数据、纯金额格式化使用独立子入口；对应导入与依赖见专题文档。仓库工作树中的新入口不代表消费方已安装或该能力已发布。
+
+## 文档导航
+
+| 文档 | 用途 |
+| --- | --- |
+| [Agent 使用指南](docs/agent-guide.md) | 场景选型、组件组合、边界和接入检查 |
+| [依赖维护](docs/dependencies.md) | 稳定版本核查、兼容例外、消费迁移要求 |
+| [公共 API](docs/api.md) | 公共行为、参数说明、数字输入与装饰示例；完整签名见安装包类型声明 |
+| [DataTable 与 MRT 迁移](docs/data-table.md) | 公共表格替代、旧参数兼容、完整配置、独立入口与合并明细；0.2.31起提供 |
+| [表格能力与 MRT 样例](docs/mrt-poc.md) | DataTable边界、筛选/列管理、产品行合并/展开、配置及性能；包含业务样例与公共API边界 |
+| [分段控制器](docs/api.md#分段控制器-segmentedcontrol) | 少量互斥选项、浅底/图标/纵向示例、兼容边界 |
+| [组件设计策略](docs/component-strategy.md) | 设计依据、公共能力范围和交互内核策略 |
+| [弹窗迁移](docs/modal-shell-migration.md) | header/content/footer 稳定插槽与历史写法迁移 |
+| [成熟度迁移](docs/maturity-migration.md) | 日期、多选、目录缓存、表格、文件限制及 Toast 行为 |
+| [上传前处理](docs/file-preparation.md) | 文件异步前处理、整批提交与取消 |
+| [文档查看器](docs/document-viewer.md) | PDF.js 与图片查看入口 |
+| [文档与图片查看器 V2](docs/document-viewer-v2.md) | PDFium/WASM、原生页面叠层、图片及 V1 兼容入口与迁移边界 |
+| [多视口验收](docs/viewport-qa.md) | 桌面、移动与交互验证 |
+| [发布流程](docs/release.md) | registry、版本、制品与发布检查 |
+| [变更记录](CHANGELOG.md) | 按版本查看变化 |
+
+详细用法集中于 API 和专题；新增公共能力时同步 Agent 选型表和发布文档清单。历史审计文档保留作证据，不作为当前 API 说明。
+
+## 开发与消费边界
+
+- 通用缺陷、无障碍、响应式及跨项目能力在公共包修复；单项目领域需求通过业务包装实现。
+- 优先兼容既有 API；破坏性修改需要 major 版本及迁移说明。
+- 消费方使用公开插槽和 props，固定弹窗底栏使用 footer；不要依赖内部 DOM 或重复实现焦点管理。
+- 已配置 `business-ui-gate` 的消费项目继续运行门禁；首次接入需要生成并审核基线，不通过扩大 baseline 掩盖新增手写组件。
+
+## 本地验证与发布
+
+`pnpm dev:matrix` 打开组件验收页面；`pnpm verify` 执行类型、单元测试、库和矩阵构建；`pnpm test:browser` 验证真实浏览器交互。详细要求见多视口验收与发布流程。
+
+仓库通过 `v<package.version>` 标签触发受控发布。公共包本地验证、正式发布、消费应用升级和生产部署是不同状态，应分别验证和记录。
+
+- [通用级联选择与部门/地址适配](docs/cascader.md)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# Third-party notices
+
+`@jc-times/business-ui` 使用以下固定版本开源依赖。依赖源码未复制到本仓库；最终安装包由包管理器连同各自许可证一并解析。
+
+| Package | Version | License | Project |
+| --- | --- | --- | --- |
+| `lucide-react` | 1.45.0（开发验证版本） | ISC | https://github.com/lucide-icons/lucide |
+| `pdfjs-dist` | 6.3.289 | Apache-2.0 | https://github.com/mozilla/pdf.js |
+| `material-react-table` | 3.2.1 | MIT | https://github.com/KevinVandy/material-react-table |
+| `@mui/material`, `@mui/icons-material` | 7.3.11 | MIT | https://github.com/mui/material-ui |
+| `@mui/x-date-pickers` | 9.13.0 | MIT | https://github.com/mui/mui-x |
+| `@emotion/react`, `@emotion/styled` | 11.14.0 / 11.14.1 | MIT | https://github.com/emotion-js/emotion |
+| `@embedpdf/react-pdf-viewer` | 2.15.0 | MIT | https://github.com/embedpdf/embed-pdf-viewer |
+| `@embedpdf/core`, `@embedpdf/engines`, `@embedpdf/plugin-document-manager`, `@embedpdf/plugin-viewport`, `@embedpdf/plugin-scroll`, `@embedpdf/plugin-render`, `@embedpdf/plugin-zoom`, `@embedpdf/plugin-rotate`, `@embedpdf/plugin-thumbnail` | 2.15.0 | MIT | https://github.com/embedpdf/embed-pdf-viewer |
+| PDFium（由 `@embedpdf/pdfium` 随查看器分发） | 2.15.0 | BSD-3-Clause / Apache-2.0 等，详见依赖内 `LICENSE.pdfium` | https://pdfium.googlesource.com/pdfium/ |
+| `@radix-ui/react-popover` | 1.1.23 | MIT | https://github.com/radix-ui/primitives |
+| `@radix-ui/react-dialog` | 1.1.23 | MIT | https://github.com/radix-ui/primitives |
+| `@radix-ui/react-toast` | 1.2.23 | MIT | https://github.com/radix-ui/primitives |
+| `@internationalized/date` | 3.12.4 | Apache-2.0 | https://github.com/adobe/react-spectrum |
+| `@radix-ui/react-select` | 2.3.7 | MIT | https://github.com/radix-ui/primitives |
+| `@radix-ui/react-tooltip` | 1.2.16 | MIT | https://github.com/radix-ui/primitives |
+| `react-aria-components` | 1.21.1 | Apache-2.0 | https://github.com/adobe/react-spectrum |
+| `cn-division` | 2026.0.1 | MIT | https://github.com/kk-418/cn-division |
+
+完整许可证文本以各依赖包内的 `LICENSE` 文件为准。
+
+## @rc-component/cascader 1.25.0
+
+MIT, Copyright (c) 2019-present react-component. Source: https://github.com/react-component/cascader. Used as the external Cascader interaction dependency; license reproduced in licenses/rc-cascader-MIT.txt. Transitive dependencies retain their own notices in their installed packages.

package/bin/business-ui-gate.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+const args = process.argv.slice(2);
+const root = process.cwd();
+const sourceRoot = path.resolve(root, value("--root") ?? "src");
+const baselinePath = path.resolve(root, value("--baseline") ?? "scripts/business-ui-gate-baseline.json");
+const only = new Set((value("--only") ?? "").split(",").filter(Boolean));
+const snapshot = filterSnapshot(scan(sourceRoot));
+
+if (args.includes("--snapshot")) {
+  process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
+  process.exit(0);
+}
+if (!fs.existsSync(baselinePath)) {
+  process.stderr.write(`缺少门禁基线：${baselinePath}\n请先使用 --snapshot 生成并审核基线。\n`);
+  process.exit(1);
+}
+
+const baseline = JSON.parse(fs.readFileSync(baselinePath, "utf8"));
+const regressions = [];
+for (const [file, current] of Object.entries(snapshot)) {
+  for (const [kind, count] of Object.entries(current)) {
+    const allowed = baseline[file]?.[kind] ?? 0;
+    if (count > allowed) regressions.push({ file, kind, count, allowed });
+  }
+}
+if (regressions.length) {
+  process.stderr.write(`发现新增的未统一 UI 实现：\n${regressions.map(formatRegression).join("\n")}\n`);
+  process.exit(1);
+}
+process.stdout.write("Business UI gate passed.\n");
+
+function value(flag) {
+  const index = args.indexOf(flag);
+  return index < 0 ? undefined : args[index + 1];
+}
+
+function filterSnapshot(input) {
+  if (!only.size) return input;
+  const output = {};
+  for (const [file, counts] of Object.entries(input)) {
+    const selected = Object.fromEntries(Object.entries(counts).filter(([kind]) => only.has(kind)));
+    if (Object.keys(selected).length) output[file] = selected;
+  }
+  return output;
+}
+
+function formatRegression({ file, kind, count, allowed }) {
+  const base = `- ${file}: ${kind} ${count}（基线 ${allowed}）`;
+  if (kind !== "legacyModalFooter") return base;
+  return `${base}\n  ModalShell 的固定底栏必须改用 footer 属性，并通过 footerClassName 定制；不要把原生 <footer> 直接放在 children 中。`;
+}
+
+function scan(directory) {
+  const result = {};
+  for (const absolute of walk(directory)) {
+    if (!absolute.endsWith(".tsx") || absolute.endsWith(".test.tsx")) continue;
+    const source = fs.readFileSync(absolute, "utf8");
+    const sourceFile = ts.createSourceFile(absolute, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const modalImports = collectModalImports(sourceFile);
+    const counts = {
+      bareButton: 0,
+      bareInput: 0,
+      bareSelect: 0,
+      bareTextarea: 0,
+      handwrittenDialog: 0,
+      handwrittenMenu: 0,
+      handwrittenCombobox: 0,
+      legacyModalFooter: 0,
+    };
+    visit(sourceFile);
+    const used = Object.fromEntries(Object.entries(counts).filter(([, count]) => count));
+    if (Object.keys(used).length) result[path.relative(root, absolute).replaceAll(path.sep, "/")] = used;
+
+    function visit(node) {
+      if (ts.isJsxElement(node) && isImportedModalTag(node.openingElement.tagName, modalImports)
+        && !hasAttribute(node.openingElement, "footer") && node.children.some(rendersDirectFooter)) {
+        counts.legacyModalFooter += 1;
+      }
+      if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+        const tag = node.tagName.getText(sourceFile);
+        const hasClass = hasAttribute(node, "className");
+        if (tag === "button" && !hasClass) counts.bareButton += 1;
+        if (tag === "input" && !exemptInput(node)) counts.bareInput += 1;
+        if (tag === "select") counts.bareSelect += 1;
+        if (tag === "textarea") counts.bareTextarea += 1;
+        const role = stringAttribute(node, "role");
+        if (/^[a-z]/.test(tag) && (role === "dialog" || role === "alertdialog")) counts.handwrittenDialog += 1;
+        if (/^[a-z]/.test(tag) && (role === "menu" || role === "menuitem")) counts.handwrittenMenu += 1;
+        if (/^[a-z]/.test(tag) && (role === "combobox" || role === "listbox" || role === "option")) counts.handwrittenCombobox += 1;
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    function exemptInput(node) {
+      const type = stringAttribute(node, "type");
+      return ["file", "hidden", "range"].includes(type ?? "");
+    }
+
+    function stringAttribute(node, name) {
+      const attribute = node.attributes.properties.find((item) => ts.isJsxAttribute(item) && item.name.getText(sourceFile) === name);
+      return attribute && ts.isJsxAttribute(attribute) && attribute.initializer && ts.isStringLiteral(attribute.initializer)
+        ? attribute.initializer.text : undefined;
+    }
+
+    function hasAttribute(node, name) {
+      return node.attributes.properties.some((item) => ts.isJsxAttribute(item) && item.name.getText(sourceFile) === name);
+    }
+
+    function rendersDirectFooter(node) {
+      if (ts.isJsxElement(node)) return node.openingElement.tagName.getText(sourceFile) === "footer";
+      if (ts.isJsxSelfClosingElement(node)) return node.tagName.getText(sourceFile) === "footer";
+      if (ts.isJsxFragment(node)) return node.children.some(rendersDirectFooter);
+      if (ts.isJsxExpression(node) && node.expression) return expressionRendersFooter(node.expression);
+      return false;
+    }
+
+    function expressionRendersFooter(expression) {
+      if (ts.isParenthesizedExpression(expression)) return expressionRendersFooter(expression.expression);
+      if (ts.isJsxElement(expression) || ts.isJsxSelfClosingElement(expression) || ts.isJsxFragment(expression)) {
+        return rendersDirectFooter(expression);
+      }
+      if (ts.isConditionalExpression(expression)) {
+        return expressionRendersFooter(expression.whenTrue) || expressionRendersFooter(expression.whenFalse);
+      }
+      if (ts.isBinaryExpression(expression) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken,
+        ts.SyntaxKind.QuestionQuestionToken].includes(expression.operatorToken.kind)) {
+        return expressionRendersFooter(expression.left) || expressionRendersFooter(expression.right);
+      }
+      if (ts.isArrayLiteralExpression(expression)) return expression.elements.some(expressionRendersFooter);
+      return false;
+    }
+  }
+  return Object.fromEntries(Object.entries(result).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function collectModalImports(sourceFile) {
+  const names = new Set();
+  const namespaces = new Set();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)
+      || statement.moduleSpecifier.text !== "@jc-times/business-ui") continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const element of bindings.elements) {
+        const importedName = (element.propertyName ?? element.name).text;
+        if (importedName === "ModalShell" || importedName === "Dialog") names.add(element.name.text);
+      }
+    } else if (bindings && ts.isNamespaceImport(bindings)) {
+      namespaces.add(bindings.name.text);
+    }
+  }
+  return { names, namespaces };
+}
+
+function isImportedModalTag(tagName, { names, namespaces }) {
+  if (ts.isIdentifier(tagName)) return names.has(tagName.text);
+  if (!ts.isPropertyAccessExpression(tagName) || !ts.isIdentifier(tagName.expression)) return false;
+  return namespaces.has(tagName.expression.text) && (tagName.name.text === "ModalShell" || tagName.name.text === "Dialog");
+}
+
+function* walk(directory) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const absolute = path.join(directory, entry.name);
+    if (entry.isDirectory()) yield* walk(absolute);
+    else yield absolute;
+  }
+}

package/dist/Alert.js

@@ -0,0 +1,47 @@
+import { AlertCircle as e, CheckCircle2 as t, Info as n, TriangleAlert as r, X as i } from "lucide-react";
+import { jsx as a, jsxs as o } from "react/jsx-runtime";
+//#region src/Alert.tsx
+var s = {
+	info: n,
+	success: t,
+	warning: r,
+	danger: e
+};
+function c({ tone: e = "info", title: t, description: n, action: r, dismissLabel: c = "关闭提示", onDismiss: l, className: u = "", ...d }) {
+	let f = s[e];
+	return /* @__PURE__ */ o("div", {
+		...d,
+		className: `ui-alert ui-alert-${e} ${u}`.trim(),
+		role: e === "danger" ? "alert" : "status",
+		children: [
+			/* @__PURE__ */ a(f, {
+				className: "ui-alert-icon",
+				size: 18,
+				"aria-hidden": "true"
+			}),
+			/* @__PURE__ */ o("div", {
+				className: "ui-alert-content",
+				children: [t === void 0 ? null : /* @__PURE__ */ a("strong", { children: t }), n === void 0 ? null : /* @__PURE__ */ a("div", {
+					className: "ui-alert-description",
+					children: n
+				})]
+			}),
+			r === void 0 ? null : /* @__PURE__ */ a("div", {
+				className: "ui-alert-action",
+				children: r
+			}),
+			l && /* @__PURE__ */ a("button", {
+				type: "button",
+				className: "ui-alert-close",
+				"aria-label": c,
+				onClick: l,
+				children: /* @__PURE__ */ a(i, {
+					size: 16,
+					"aria-hidden": "true"
+				})
+			})
+		]
+	});
+}
+//#endregion
+export { c as Alert };