@jc-times/business-ui 0.2.43

package/dist/types/document-viewer/PdfWorkspace.d.ts

@@ -0,0 +1,5 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export declare const useThumbnailRailCollapsed: () => boolean;
+export declare function PdfWorkspace({ rail, children, className, ...props }: HTMLAttributes<HTMLDivElement> & {
+    rail: ReactNode;
+}): import("react").JSX.Element;

package/dist/types/document-viewer/pdf-render-budget.d.ts

@@ -0,0 +1,2 @@
+export * from "../DocumentRenderBudget";
+export declare function pdfRenderBudgetForWindow(): import("./pdf-render-budget").PdfRenderBudget;

package/dist/types/document-viewer/usePdfCanvas.d.ts

@@ -0,0 +1,22 @@
+import type { PDFDocumentProxy } from "pdfjs-dist";
+type PageOptions = {
+    kind: "page";
+    document: PDFDocumentProxy;
+    page: number;
+    renderWidth: number;
+    zoom: number;
+    rotation: number;
+};
+type ThumbnailOptions = {
+    kind: "thumbnail";
+    document: PDFDocumentProxy;
+    page: number;
+    renderWidth: number;
+};
+/** Serializes PDF.js work for one canvas so cancelled renders cannot race replacements. */
+export declare function usePdfCanvas(options: PageOptions | ThumbnailOptions): {
+    canvasRef: import("react").RefObject<HTMLCanvasElement | null>;
+    ratio: number;
+    error: string;
+};
+export {};

package/dist/types/document-viewer/usePdfViewport.d.ts

@@ -0,0 +1,14 @@
+export declare function usePdfViewport(documentKey: string): {
+    containerRef: import("react").RefObject<HTMLDivElement | null>;
+    zoom: number;
+    setZoom: import("react").Dispatch<import("react").SetStateAction<number>>;
+    rotation: number;
+    setRotation: import("react").Dispatch<import("react").SetStateAction<number>>;
+    fullscreen: boolean;
+    canZoomOut: boolean;
+    canZoomIn: boolean;
+    zoomOut: () => void;
+    zoomIn: () => void;
+    rotate: () => void;
+    toggleFullscreen: () => undefined;
+};

package/dist/types/document-viewer-v2/DocumentViewerV2.d.ts

@@ -0,0 +1,50 @@
+import { type CSSProperties } from "react";
+import type { LoadDocumentBufferOptions, LoadDocumentUrlOptions, PDFViewerConfig, PDFViewerProps } from "@embedpdf/react-pdf-viewer";
+import { type DocumentViewerProps, type DocumentViewerSource } from '../document-viewer/DocumentViewer';
+import type { DocumentViewerV2HeadlessProps } from './HeadlessPdfViewer';
+export declare const DOCUMENT_VIEWER_V2_DISABLED_CATEGORIES: readonly ["annotation", "redaction", "insert", "form"];
+export type DocumentViewerV2UrlSource = Omit<LoadDocumentUrlOptions, "documentId" | "autoActivate"> & {
+    id: string;
+    kind: "url";
+};
+export type DocumentViewerV2BufferSource = Omit<LoadDocumentBufferOptions, "documentId" | "autoActivate"> & {
+    id: string;
+    kind: "buffer";
+};
+export type DocumentViewerV2PdfSource = DocumentViewerV2UrlSource | DocumentViewerV2BufferSource;
+export type DocumentViewerV2ImageSource = Extract<DocumentViewerSource, {
+    kind: 'image';
+}>;
+export type DocumentViewerV2Source = DocumentViewerV2PdfSource | DocumentViewerSource;
+export type DocumentViewerV2Config = Omit<PDFViewerConfig, "src" | "documentManager"> & {
+    documentManager?: Omit<NonNullable<PDFViewerConfig["documentManager"]>, "initialDocuments">;
+};
+type SharedViewerProps = {
+    className?: string;
+    style?: CSSProperties;
+    ariaLabel?: string;
+};
+export type DocumentViewerV2NativeProps = SharedViewerProps & Pick<DocumentViewerProps, 'title' | 'toolbar' | 'footer'> & {
+    renderer?: 'viewer';
+    source: DocumentViewerV2PdfSource;
+    config?: DocumentViewerV2Config;
+    onInit?: PDFViewerProps["onInit"];
+    onReady?: PDFViewerProps["onReady"];
+    currentPage?: never;
+    onCurrentPageChange?: never;
+    pageMode?: never;
+    renderPage?: never;
+};
+export type DocumentViewerV2Props = DocumentViewerV2NativeProps | DocumentViewerV2HeadlessProps | (DocumentViewerProps & SharedViewerProps & {
+    renderer?: never;
+    config?: never;
+    onInit?: never;
+    onReady?: never;
+});
+export declare const DOCUMENT_VIEWER_V2_TOOLBAR_STYLE_ATTRIBUTE = "data-business-ui-document-viewer-v2-toolbar";
+export declare function applyDocumentViewerV2ToolbarStyles(container: {
+    shadowRoot: ShadowRoot | null;
+}): void;
+export declare function createDocumentViewerV2Config(source: DocumentViewerV2PdfSource, config?: DocumentViewerV2Config): PDFViewerConfig;
+export declare function DocumentViewerV2(props: DocumentViewerV2Props): import("react").JSX.Element;
+export {};

package/dist/types/document-viewer-v2/HeadlessPdfViewer.d.ts

@@ -0,0 +1,39 @@
+import { type ReactNode } from 'react';
+import { type PluginRegistry } from '@embedpdf/core';
+import { usePdfiumEngine } from '@embedpdf/engines/react';
+import type { DocumentViewerProps } from '../document-viewer/DocumentViewer';
+import type { DocumentViewerV2PdfSource } from './DocumentViewerV2';
+/** Coordinates use the unscaled page, origin at its top-left. Rotation/scale are applied by the viewer. */
+export type DocumentViewerV2OverlayContext = {
+    documentId: string;
+    page: number;
+    pageIndex: number;
+    width: number;
+    height: number;
+    zoom: number;
+    rotation: number;
+};
+export type DocumentViewerV2HeadlessProps = Omit<DocumentViewerProps, 'source'> & {
+    renderer: 'headless';
+    zoom?: number;
+    initialZoom?: number | "fit-width";
+    rotation?: number;
+    showToolbar?: boolean;
+    focusTarget?: {
+        page: number;
+        y: number;
+        token: string;
+    } | null;
+    onZoomChange?: (zoom: number) => void;
+    onRotationChange?: (rotation: number) => void;
+    features?: {
+        search?: boolean;
+        textSelection?: boolean;
+        pinchZoom?: boolean;
+    };
+    source: DocumentViewerV2PdfSource;
+    renderPageOverlay?: (context: DocumentViewerV2OverlayContext) => ReactNode;
+    engineOptions?: Parameters<typeof usePdfiumEngine>[0];
+    onReady?: (registry: PluginRegistry) => void;
+};
+export default function HeadlessPdfViewer(props: DocumentViewerV2HeadlessProps): import("react").JSX.Element;

package/dist/types/document-viewer-v2/HeadlessSearch.d.ts

@@ -0,0 +1,9 @@
+export declare function HeadlessSearch({ documentId, onPageChange, enabled, onClear }: {
+    documentId: string;
+    onPageChange(page: number, point?: {
+        x: number;
+        y: number;
+    }): void;
+    enabled: boolean;
+    onClear?(): void;
+}): import("react").JSX.Element;

package/dist/types/index.d.ts

@@ -0,0 +1,41 @@
+import "./styles.css";
+export * from "./Button";
+export * from "./Alert";
+export * from "./EmptyState";
+export * from "./Skeleton";
+export * from "./FloatingControls";
+export * from "./Select";
+export * from "./Combobox";
+export * from "./AutoComplete";
+export * from "./Toast";
+export * from "./DataTable";
+export * from "./ExplainableButton";
+export * from "./ModalShell";
+export * from "./FormField";
+export * from "./DateInput";
+export * from "./Pagination";
+export * from "./RovingTabs";
+export * from "./ToggleSwitch";
+export * from "./SegmentedControl";
+export * from "./RecoverableAsyncState";
+export * from "./useModalFocusTrap";
+export * from "./AsyncSearchPicker";
+export * from "./AsyncDirectoryPicker";
+export * from "./DropdownMenu";
+export * from "./ConfirmDialog";
+export * from "./useDebouncedValue";
+export * from "./Badge";
+export * from "./MetricCard";
+export * from "./PageHeader";
+export * from "./SectionCard";
+export * from "./SortableList";
+export * from "./TreeSelect";
+export * from "./StructuredAddressInput";
+export * from "./FileDropzone";
+export * from "./useFilePreparation";
+export * from "./FilePreparationDialog";
+export * from "./PreparedFileDropzone";
+export * from "./NumericInput";
+export * from "./AmountFormat";
+export * from "./MultiSelect";
+export * from "./Cascader";

package/dist/types/useDebouncedValue.d.ts

@@ -0,0 +1,2 @@
+/** Returns the latest value after it has remained unchanged for the requested delay. */
+export declare function useDebouncedValue<T>(value: T, delay: number): T;

package/dist/types/useFilePreparation.d.ts

@@ -0,0 +1,28 @@
+export type FilePreparationState = {
+    kind: "idle";
+} | {
+    kind: "preparing";
+    fileName: string;
+    index: number;
+    total: number;
+} | {
+    kind: "failed";
+    fileName: string;
+    message: string;
+};
+export type FilePreparationOptions = {
+    /** Include every resource identity/version that changes the meaning of the selection. */
+    ownerKey: string;
+    disabled?: boolean;
+    prepareFile(file: File, signal: AbortSignal): Promise<File>;
+    onFilesSelected(files: readonly File[]): void;
+    errorMessage(error: unknown): string;
+};
+/** Prepares a whole selection before invoking the business callback once. */
+export declare function useFilePreparation(options: FilePreparationOptions): {
+    state: FilePreparationState;
+    busy: boolean;
+    cancel: () => void;
+    selectFiles: (files: readonly File[]) => Promise<void>;
+};
+export type FilePreparation = ReturnType<typeof useFilePreparation>;

package/dist/types/useModalFocusTrap.d.ts

@@ -0,0 +1,3 @@
+import { type RefObject } from "react";
+export type FocusTarget = HTMLElement | null | RefObject<HTMLElement | null>;
+export declare function useModalFocusTrap(active: boolean, dialogRef?: RefObject<HTMLElement | null>, returnFocus?: FocusTarget | false, initialFocus?: FocusTarget): void;

package/dist/useDebouncedValue.js

@@ -0,0 +1,16 @@
+import { useEffect as e, useState as t } from "react";
+//#region src/useDebouncedValue.ts
+function n(n, r) {
+	let [i, a] = t(n);
+	return e(() => {
+		let e = Number.isFinite(r) ? Math.max(0, r) : 0;
+		if (e === 0) {
+			a(n);
+			return;
+		}
+		let t = window.setTimeout(() => a(n), e);
+		return () => window.clearTimeout(t);
+	}, [r, n]), i;
+}
+//#endregion
+export { n as useDebouncedValue };

package/dist/useFilePreparation.js

@@ -0,0 +1,51 @@
+import { useCallback as e, useLayoutEffect as t, useRef as n, useState as r } from "react";
+//#region src/useFilePreparation.ts
+function i(i) {
+	let a = n(i);
+	a.current = i;
+	let o = n(null), [s, c] = r({ kind: "idle" }), l = e(() => {
+		o.current?.abort(), o.current = null, c({ kind: "idle" });
+	}, []);
+	t(() => (l(), () => {
+		o.current?.abort(), o.current = null;
+	}), [
+		i.ownerKey,
+		i.disabled,
+		l
+	]);
+	let u = e(async (e) => {
+		if (!e.length || a.current.disabled || o.current) return;
+		let t = a.current.ownerKey, n = new AbortController();
+		o.current = n;
+		let r = () => o.current === n && !n.signal.aborted && a.current.ownerKey === t && !a.current.disabled, i = [], s = e[0].name;
+		try {
+			for (let [t, o] of e.entries()) {
+				s = o.name, c({
+					kind: "preparing",
+					fileName: s,
+					index: t + 1,
+					total: e.length
+				});
+				let l = await a.current.prepareFile(o, n.signal);
+				if (!r()) return;
+				i.push(l);
+			}
+		} catch (e) {
+			r() && (o.current = null, c({
+				kind: "failed",
+				fileName: s,
+				message: a.current.errorMessage(e)
+			}));
+			return;
+		}
+		r() && (o.current = null, c({ kind: "idle" }), a.current.onFilesSelected(i));
+	}, []);
+	return {
+		state: s,
+		busy: s.kind === "preparing",
+		cancel: l,
+		selectFiles: u
+	};
+}
+//#endregion
+export { i as useFilePreparation };

package/dist/useModalFocusTrap.js

@@ -0,0 +1,71 @@
+import { useEffect as e } from "react";
+//#region src/useModalFocusTrap.ts
+var t = [
+	"button:not([disabled])",
+	"a[href]",
+	"input:not([disabled])",
+	"select:not([disabled])",
+	"textarea:not([disabled])",
+	"[contenteditable]:not([contenteditable='false'])",
+	"[tabindex]:not([tabindex='-1'])"
+].join(",");
+function n(n, r, i, a) {
+	e(() => {
+		if (!n || r?.current?.hasAttribute("data-ui-focus-managed")) return;
+		let e = o(), d = i === !1 ? null : s(i) ?? (document.activeElement instanceof HTMLElement ? document.activeElement : null), f = () => {
+			let e = c(r), n = s(a);
+			e && l(e) && !e.contains(document.activeElement) && (n?.isConnected && !n.hasAttribute("disabled") ? n : e.querySelector(t) ?? e).focus();
+		};
+		f();
+		let p = requestAnimationFrame(f), m = (e) => {
+			if (e.key !== "Tab") return;
+			let n = c(r);
+			if (!n || !l(n)) return;
+			let i = [...n.querySelectorAll(t)], a = i.filter((e) => e.getClientRects().length > 0), o = a.length ? a : i;
+			if (!o.length) return;
+			let s = o[0], u = o.at(-1);
+			e.shiftKey && document.activeElement === s ? (e.preventDefault(), u.focus()) : !e.shiftKey && document.activeElement === u && (e.preventDefault(), s.focus());
+		}, h = (e) => {
+			let n = c(r);
+			n && l(n) && !n.contains(e.target) && (n.querySelector(t) ?? n).focus();
+		};
+		return document.addEventListener("keydown", m), document.addEventListener("focusin", h), () => {
+			cancelAnimationFrame(p), document.removeEventListener("keydown", m), document.removeEventListener("focusin", h), e();
+			let t = u(r?.current);
+			d && (!t || t.contains(d)) && d.focus();
+		};
+	}, [
+		n,
+		r,
+		i,
+		a
+	]);
+}
+var r = 0, i = "", a = "";
+function o() {
+	if (r === 0) {
+		i = document.body.style.overflow, a = document.body.style.paddingRight;
+		let e = document.documentElement.clientWidth, t = e > 0 ? Math.max(0, window.innerWidth - e) : 0;
+		document.body.style.overflow = "hidden", t > 0 && (document.body.style.paddingRight = `${t}px`);
+	}
+	r += 1;
+	let e = !1;
+	return () => {
+		e || (e = !0, r = Math.max(0, r - 1), r === 0 && (document.body.style.overflow = i, document.body.style.paddingRight = a));
+	};
+}
+function s(e) {
+	return e && "current" in e ? e.current : e || null;
+}
+function c(e) {
+	let t = e?.current ?? u();
+	return !t || t.getAttribute("aria-modal") !== "true" || t.inert ? null : t;
+}
+function l(e) {
+	return u() === e;
+}
+function u(e) {
+	return [...document.querySelectorAll("[role='dialog'][aria-modal='true'],[role='alertdialog'][aria-modal='true']")].filter((t) => t !== e && !t.inert && t.getAttribute("aria-hidden") !== "true").at(-1);
+}
+//#endregion
+export { n as useModalFocusTrap };

package/docs/agent-guide.md

@@ -0,0 +1,145 @@
+# Agent 公共组件使用指南
+
+本指南面向在业务应用中使用 `@jc-times/business-ui` 的 agent，也适用于维护本库的 agent。先按场景选型，再按需阅读 API 和专题文档，不需要通读历史审计记录。
+
+## 开始工作前
+
+依赖升级、兼容版本与消费迁移边界见 [依赖维护](dependencies.md)。
+
+1. 查看消费项目的 `AGENTS.md`、`package.json` 和锁文件，确认实际安装的精确版本、现有业务包装和主题入口。仓库当前源码不代表消费项目已安装该能力。
+2. 在下表选择公共组件；已有组件能覆盖时优先复用，业务差异通过 props、插槽或薄包装表达。不要复制本库源码或另写同类焦点、菜单、日期及选择交互。
+3. 阅读 [API 与使用示例](api.md) 及相关专题。完整参数和导出以实际安装包的 `dist/types` 类型声明为准；在本仓库维护时核对 `src/index.ts`、`package.json` 的 `exports` 和组件源码。不要根据其他组件库猜测本包参数。
+4. 主入口导入常规组件，应用统一导入 `@jc-times/business-ui/styles.css`；通过 `--ui-*` 令牌接入主题。文档查看、行政区划和服务端金额格式使用独立子入口。
+5. 核对新能力所需版本及 peer dependencies；升级使用已发布的精确版本并提交锁文件。未发布工作树、文档中出现的历史版本号均不能作为安装最新版的依据。
+
+## 按需求选择组件
+
+### 页面、信息与反馈
+
+| 需求 | 使用组件 | 边界与选择依据 |
+| --- | --- | --- |
+| 页面标题、说明、操作区 | `PageHeader` | 输出页面级 h1；不要用于每个小区块 |
+| 带标题的内容区域 | `SectionCard` | 按页面大纲设置 headingLevel；业务内容放 children |
+| 状态标签 / 单项统计 | `Badge` / `MetricCard` | 业务状态映射、数值计算和格式由应用提供 |
+| 常规操作 / 解释不可用原因 | `Button` / `ExplainableButton` | 图标按钮必须有 aria-label；禁用条件由业务判断 |
+| 导航 / 文件下载 | `LinkButton` | 必须提供 href；输出真实链接并保留浏览器下载语义；跨域/鉴权下载先由业务层取得签名地址或 Blob URL，不用临时 DOM 点击模拟 |
+| 持续提示 / 无数据 / 加载占位 | `Alert` / `EmptyState` / `Skeleton` | 区分错误、空结果和加载，不用空状态掩盖请求失败 |
+| 加载与可重试错误 | `RecoverableAsyncState`（别名 `AsyncState`） | 页面提供状态、文案和重试回调 |
+| 操作完成后的临时通知 | `ToastProvider` 与 `useToast` | 统一队列；关键表单错误仍应在字段或页面呈现 |
+| 切换内容面板 | `RovingTabList` + `RovingTabPanel` | 配对 groupId/value；不要把字段枚举选项当内容页签 |
+
+### 表单与选项
+
+| 需求 | 使用组件 | 边界与选择依据 |
+| --- | --- | --- |
+| 文本 / 多行文本 | `TextInput` / `TextArea` | 自带 label、helpText、error；自定义控件用 `FormField` 关联标签 |
+| 勾选 / 开关 | `Checkbox` / `ToggleSwitch` | 分别表达勾选项与开启/关闭；请求和持久化留在应用 |
+| 少量互斥选项，全部平铺可见 | [SegmentedControl](api.md#分段控制器-segmentedcontrol) | 受控字符串 value/options/onChange；支持实色/浅底、图标、纵向和收缩宽度；原生 radio 语义，须提供 aria-label，新增参数先核对安装版本 |
+| 数量、精确十进制 | `NumericInput` | value 为字符串；提交用 onValueCommit，不能用草稿计算 |
+| 金额等以最小单位整数存储的数值 | `ScaledNumericInput` | value 为安全整数或 null；scale=100 表示分，不是元 |
+| 原生下拉单选 | `SelectInput` | 简单固定候选，使用浏览器原生选择体验 |
+| 定制单选浮层 | `Select` | 需要公共浮层、定制选项或手机抽屉体验 |
+| 搜索已有选项 / 允许自由文本 | `Combobox` / `AutoComplete` | 必须选已有项用前者；允许新文本用后者 |
+| 多选与已选标签 | `MultiSelect` | values/onValuesChange；异步候选之外的标签通过 selectedItems 补足 |
+| 部门、分类、省市区等多列级联选择 | `Cascader` | RC 内核；单选路径、多选路径数组；默认父子独立多选；扁平数据用 buildCascaderOptions 转换 |
+| 部门、分类等树形单选或多选 | `TreeSelect` | 应用映射 id/label/parentId；父子独立选择，不自动级联 |
+| 远程目录搜索，需防抖、取消、缓存 | `AsyncDirectoryPicker` | 提供 loadItems(query, signal) 和 ownerKey；网络适配器必须传递 signal |
+| 页面已有查询状态和请求生命周期 | `AsyncSearchPicker` | 页面提供 query/items/status/onSearch/onSelect；组件不发请求 |
+| 日期输入与日历 | `DateInput` | 用 minDate/maxDate/isDateUnavailable 约束；业务时区和日期转换由应用负责 |
+| 省市区与详细地址 | `StructuredAddressInput` | 默认无地址类型，海外作为顶级地区；内部复用 Cascader；独立行政区划入口提供数据；地址解析、拼接和字段映射由应用负责 |
+
+### 弹窗、浮层与操作
+
+| 需求 | 使用组件 | 边界与选择依据 |
+| --- | --- | --- |
+| 编辑表单、详情等模态内容 | `ModalShell`（别名 `Dialog`） | 正文用 children，固定操作区用 footer；不重复安装焦点陷阱 |
+| 独立、强层级确认 | `ConfirmDialog` | 例如删除确认；应用决定危险级别、busy 和提交逻辑 |
+| 触发器旁的轻量确认 | `Popconfirm` | 依附锚点；长表单使用 ModalShell |
+| 更多操作、分组操作、可勾选菜单 | `DropdownMenu`（别名 `Menu`） | 统一 menu 键盘行为；导航当前位置用 current，选中配置用 selectionMode |
+| 补充信息或小型表单浮层 | `Popover` | 不代替操作菜单 |
+| 简短悬浮解释 | `Tooltip` | 不承载必填信息或交互表单 |
+
+### 表格、排序、文件与查看
+
+| 需求 | 使用组件或入口 | 边界与选择依据 |
+| --- | --- | --- |
+| 列表表格、排序、行选择 | [DataTable](data-table.md) | 当前源码已采用MRT；旧参数兼容，完整配置用options或useDataTable/DataTableView；长页面可按需开启底部吸附横向滚动条 |
+| 评估筛选、列管理、主从明细行合并或展开 | [表格能力与 MRT 样例](mrt-poc.md) | productDisplay由调用方选择；同行用rowSpan且按合同分页；仅本地验证，不是已发布API |
+| 页码导航 | `Pagination` | 页面负责取数；窄屏自动简化 |
+| 卡片拖动排序 | `SortableList` | 提供稳定唯一 getKey、getTextValue、renderItem 和 onReorder；应用保存顺序 |
+| 点击、键盘或拖入选择文件 | `FileDropzone` | accept/maxFileSize/maxFiles 与拒绝反馈；不负责上传请求 |
+| 上传前异步转换、校验或解密适配 | `PreparedFileDropzone` | prepareFile(file, signal)，整批成功后提交；必须提供 ownerKey |
+| 非文件选择器入口需要同一前处理流程 | `useFilePreparation` + `FilePreparationDialog` | 复用取消、进度、错误处理；密钥和服务端策略不进入 UI 包 |
+| 图片、已有 PDF.js 对象或旧业务叠层 | V2 兼容 `DocumentViewer`，`document-viewer-v2` 子入口 | 未发布候选保留全部 V1 参数及底层组合；PDF 加载和销毁仍由调用方负责；旧包继续原入口 |
+| PDFium/WASM PDF 查看迁移 | `DocumentViewerV2`，`document-viewer-v2` 子入口 | URL/Buffer 使用 PDFium；兼容分支不是引擎替换，核对安装版本与专题文档 |
+| PDFium 原生 React 叠层、受控页码、单页显示 | V2 的 `renderer="headless"` | 未发布候选；用 `renderPageOverlay` 追加业务层，基础工具栏与默认成品 UI 的能力不同 |
+| 服务端或文档中的金额格式化 | `amount-format` 子入口 | 无 React 依赖；formatDecimalAmount/formatScaledMoney 不负责汇率或中文大写 |
+| 中国省市区数据 | `chinese-address-regions` 子入口 | 按需加载，核对数据版本；不跨仓库引用源码 |
+
+## 组合示例
+
+以下示例可用于已有 React 页面；请求、权限和保存由页面外层业务代码管理。
+
+```tsx
+import { useId, useState } from "react";
+import { Button, ModalShell, NumericInput, TextInput } from "@jc-times/business-ui";
+import "@jc-times/business-ui/styles.css";
+
+export function EditQuantity() {
+  const titleId = useId();
+  const [open, setOpen] = useState(false);
+  const [name, setName] = useState("");
+  const [quantity, setQuantity] = useState("");
+  return <>
+    <Button onClick={() => setOpen(true)}>编辑数量</Button>
+    {open && <ModalShell titleId={titleId} closeLabel="关闭" onClose={() => setOpen(false)} title="编辑数量"
+      footer={<Button onClick={() => setOpen(false)}>关闭</Button>}>
+      <TextInput label="名称" value={name}
+        onChange={event => setName(event.currentTarget.value)} />
+      <NumericInput label="数量" value={quantity} onValueCommit={setQuantity}
+        decimalPlaces={3} min="0" />
+    </ModalShell>}
+  </>;
+}
+```
+
+更多数字和输入装饰示例见 [API](api.md)；多选、日期与服务端表格见 [成熟度迁移](maturity-migration.md)；文件前处理见 [上传前处理](file-preparation.md)；查看器分别见 [现有入口](document-viewer.md) 和 [V2 迁移](document-viewer-v2.md)。
+
+## 必须保持的契约
+
+- 通用交互缺陷、无障碍和响应式问题在公共包修复；权限、接口、领域状态、业务文案在消费项目组合。只有一个项目需要的领域封装不进入公共包。
+- 默认控件高度 40px，粗指针触屏最小 44px。统一使用主题令牌，不单独为金额框、搜索框重写高度、字体或 padding。
+- 使用公开插槽、ref 和原生属性透传，不依赖未承诺的内部 DOM 层级；弹窗内浮层保持在最近 ModalShell 的 portal 容器。
+- 数字空值保留为空字符串或 null，空值归零由应用决定；原生 FormData 可能包含格式化显示文本，业务提交使用受控数值状态。
+- ownerKey 包含会改变数据范围或上传目标的身份；上下文变化时更新。目录查询和文件适配器传递 AbortSignal，避免旧请求覆盖新页面。
+- 大列表提供稳定数据/回调引用和唯一 ID，更新数据时使用新引用。不能假设所有组件都有虚拟化；用真实规模验证长列表、长 PDF 和大量已选项。
+- 客户端文件限制和隐藏按钮不能替代服务端校验及权限控制。
+
+## 完成接入前的验证
+
+1. 运行消费项目要求的类型检查、构建及相关测试，验证实际业务回调、空值、禁用、错误、重试和资源切换。
+2. 检查桌面与手机视口、长文字、弹窗嵌套下拉、键盘操作和焦点归还；需要软键盘的流程做真实手机验收。视口模拟不等于真实手机通过。
+3. 已配置 `business-ui-gate` 的项目运行现有门禁；不要扩大 baseline 掩盖新增手写组件。首次接入的基线按项目规则生成并审核。
+4. 修改公共实现时运行本库相关检查，并按 [多视口验收](viewport-qa.md) 和 [发布流程](release.md) 处理。区分本地验证、包已发布、消费方升级与生产部署状态。
+
+## 文档分工与维护
+
+- [README](../README.md)：包入口、安装与文档导航。
+- 本指南：按场景选型、组合原则和接入检查。
+- [API](api.md)：公共行为、参数说明和代码示例；完整类型由安装包提供。
+- [组件策略](component-strategy.md)：设计依据与公共能力边界，历史选型不作为当前参数契约。
+- 专题与迁移文档：弹窗、成熟交互、文件处理、查看器的详细契约。
+- [变更记录](../CHANGELOG.md)：按版本查变化；历史审计是当时证据，不作为当前能力清单。
+
+新增或改变公共能力时，同步选型表、对应 API/专题及发布文件清单，避免在多处复制完整参数表。消费项目可在自己的 AGENTS.md 中加入：
+
+> 修改 UI 前，先阅读已安装的 @jc-times/business-ui 包中的 docs/agent-guide.md，并按需阅读其 API 和专题文档；优先复用公共组件，按安装版本的类型声明实现。
+
+PDFium Headless 0.2.33 支持搜索、选择、双指缩放及外部受控缩放/旋转；详见 V2 专题，业务叠层控件标记 data-pdf-business-control。
+
+
+### PDFium 专用构建入口（0.2.34）
+
+只使用原生 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% 保持不变。