@autional/ui 0.0.0-stage → 0.1.0-rc.43

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "@autional/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-rc.43",
+  "description": "Autional shared React component library (atoms + molecules) — the canonical home of the component layer",
+  "license": "AGPL-3.0",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./i18n": {
+      "types": "./src/i18n/index.ts",
+      "default": "./src/i18n/index.ts"
+    },
+    "./antd": {
+      "types": "./src/antd/index.ts",
+      "default": "./src/antd/index.ts"
+    },
+    "./rhf": {
+      "types": "./src/rhf/index.ts",
+      "default": "./src/rhf/index.ts"
+    },
+    "./test-setup": {
+      "types": "./src/test-setup.ts",
+      "default": "./src/test-setup.ts"
+    },
+    "./styles/globals.css": "./src/styles/globals.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "!src/test",
+    "!src/__tests__",
+    "!src/**/__tests__"
+  ],
+  "sideEffects": true,
+  "peerDependencies": {
+    "@autional/tokens": ">=0.1.0-rc",
+    "antd": ">=6.0.0",
+    "dayjs": ">=1.11.0",
+    "i18next": ">=26.0.0",
+    "react-hook-form": ">=7.0.0",
+    "react-router": ">=7.0.0",
+    "lucide-react": ">=0.500.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "react-i18next": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "antd": {
+      "optional": true
+    },
+    "dayjs": {
+      "optional": true
+    },
+    "react-hook-form": {
+      "optional": true
+    },
+    "react-router": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "antd": "6.5.0",
+    "dayjs": "1.11.20",
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.2",
+    "@testing-library/user-event": "14.6.1",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "4.4.0",
+    "i18next": "26.0.10",
+    "jsdom": "29.1.1",
+    "lucide-react": "0.509.0",
+    "react-hook-form": "7.78.0",
+    "react-router": "7.15.0",
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "react-i18next": "17.0.7",
+    "typescript": "5.8.3",
+    "vitest": "3.2.0",
+    "@autional/tokens": "0.1.0-rc.11"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/src/antd/AntdThemeProvider.tsx

@@ -0,0 +1,80 @@
+'use client';
+
+// AntdThemeProvider —— antd 与设计系统令牌之间的**唯一**桥。
+//
+// 为什么放在这里，而不是让每个站点各写一份：
+//   在此之前，三个控制台各有一份 lib/antd-app.tsx，逻辑相同（ConfigProvider + 中英 locale
+//   + dark 算法 + @autional/tokens/antd-theme 的 token）。四份同构代码就是四份会各自漂移的东西。
+//   这一份是它的唯一实现；站点只挂 Provider，不 import antd。
+//
+// 为什么单独一个子路径入口（@autional/ui/antd）而不是并进根入口：
+//   根入口的消费方里有不吃 antd 的（user 之前是、5 个 Astro 站也是）。
+//   把 antd 并进根入口，等于让所有人替一个他们不用的库付包体积。
+//   所以：antd 是**可选** peerDependency，默认入口 0 处 import antd（有闸门断言）。
+
+import { useEffect, useMemo } from 'react';
+import { App as AntdApp, ConfigProvider, theme as antdAlgorithm } from 'antd';
+import zhCN from 'antd/locale/zh_CN';
+import enUS from 'antd/locale/en_US';
+import { useTranslation } from 'react-i18next';
+// UP-31：antd 的 locale 只提供格式串（如 yearFormat 'YYYY年'），日期面板的月份/星期缩写
+// 由 rc-picker 经 `dayjs().locale(lang.locale).localeData()` 取 —— locale 定义未加载时
+// dayjs 静默回落 'en'，面板呈「2026年 / Oct / Su Mo」中英混排。在此加载 zh-cn 定义
+// （en 为 dayjs 内置默认，无需加载），所有挂本桥的门户日期控件一并生效。
+import 'dayjs/locale/zh-cn';
+// antd 主题由设计系统下发，这里**不写死任何色值**。
+// （控制台此前硬编码过 5 个色值 + borderRadius:6，那是 KI-011：令牌变更传导不到，各控制台各自漂移。）
+import antdTheme from '@autional/tokens/antd-theme';
+import { useTheme } from '../context/ThemeProvider';
+
+export interface AntdThemeProviderProps {
+	children: React.ReactNode;
+	/** 覆盖 locale 判定。默认按 i18n.language 是否以 zh 开头。 */
+	locale?: 'zh-CN' | 'en-US';
+}
+
+/**
+ * 把 antd 接到设计系统上：同一个令牌源、同一个暗色开关、同一个语言。
+ * 必须挂在 `<ThemeProvider>` 之内（它依赖 `useTheme()`）。
+ */
+export function AntdThemeProvider({ children, locale }: AntdThemeProviderProps) {
+	const { theme } = useTheme();
+	const { i18n } = useTranslation();
+
+	const resolved = useMemo(() => {
+		if (locale) return locale;
+		return String(i18n.language || '').toLowerCase().startsWith('zh') ? 'zh-CN' : 'en-US';
+	}, [locale, i18n.language]);
+
+	const isDark = theme === 'dark';
+
+	return (
+		<ConfigProvider
+			locale={resolved === 'zh-CN' ? zhCN : enUS}
+			theme={{
+				algorithm: isDark ? antdAlgorithm.darkAlgorithm : antdAlgorithm.defaultAlgorithm,
+				token: (isDark ? antdTheme.dark : antdTheme.light).token,
+				// 组件级 token 由桥下发（不是在这里手写）。它统一的是「视觉维度」——
+				// 表头底色 / 悬浮态 / 边框 / 行高 —— 而且**对所有 antd Table 生效**，
+				// 包括控制台现存的那些直接使用，它们一行都不用改。
+				components: (isDark ? antdTheme.dark : antdTheme.light).components,
+			}}
+		>
+			<AntdApp>{children}</AntdApp>
+		</ConfigProvider>
+	);
+}
+
+/**
+ * 取 antd 的命令式 API（message / modal / notification）。
+ *
+ * 刻意**不**做模块级可变单例（那是三个控制台现在各自的做法：
+ * `export let message` + 在 useEffect 里赋值）。单例在 SSR、多实例、测试隔离三处都会咬人；
+ * 用 hook 拿，作用域天然正确。
+ */
+export function useAntdApp() {
+	return AntdApp.useApp();
+}
+
+/** `App.useApp()` 的返回类型（message / notification / modal 三个命令式 API）。 */
+export type AntdAppApi = ReturnType<typeof AntdApp.useApp>;

package/src/antd/Breadcrumb.tsx

@@ -0,0 +1,118 @@
+'use client';
+
+// Breadcrumb —— 三个门户各写了一遍的「把 URL 变成面包屑」。
+//
+// 逐行比对（2026-10-03）：admin 145 行（antd + 78 条路由映射 + 按段累积 + 中间段可点 + 详情页启发式），
+// platform 54 行（antd + 27 条映射 + 按段累积，但**中间段不可点**），
+// user 77 行（**手写 nav + lucide 图标**，且**只认完整路径**、不按段累积、上限两项）。
+// 三份的**业务部分**（路由→文案的映射表）内容完全不同，必须留在站点；
+// 而**机制部分**三份各写一遍、还写出了三种行为：
+//   剥租户段（admin 用 stripTenantPrefix / platform 手写 slice / user 正则 replace）、
+//   按段累积 currentPath、中间段可点、末段纯文本、「只有一项就不渲染」。
+// 这个组件收的就是机制，映射表通过 labels 传进来。
+//
+// 为什么渲染用 antd 的 Breadcrumb：三个门户里两个已经在用它（admin / platform），
+// 而 user 那 77 行是手写的 —— 收敛的方向应该是「少数向多数靠」，而不是反过来。
+// 顺带把 user 的「只认完整路径」也统一成按段累积：路径里若有一段在映射表里，
+// 它会多显示一级（并成为可点的链接），这正是 admin / platform 早就有的行为。
+
+import { Breadcrumb as AntBreadcrumb } from 'antd';
+import { Link } from 'react-router';
+
+export interface BreadcrumbProps {
+	/** 完整 pathname（含租户段）。剥段在本组件里做 —— 三个站点此前各写了一遍。 */
+	pathname: string;
+	/** 当前租户 slug。给了就剥掉首段，没给按原样处理。 */
+	tenantSlug?: string | null;
+	/** 路由段 → 文案。键是**累积路径**（如 '/wallet/withdrawals'）。这段内容各站不同，留在站点。 */
+	labels: Record<string, string>;
+	/** 首页项。不给则不渲染首页项（只渲染映射表命中的段）。 */
+	home?: { label: string; href: string };
+	/** 认不出、但形态像 ID 的段（长度 > 8 的字母数字串）显示成什么。不给则原样显示该段。 */
+	detailLabel?: string;
+	/** 站点的链接构造（各站带租户前缀的方式不同，如 admin 走 buildNavHref）。默认原样返回。 */
+	buildHref?: (path: string) => string;
+	className?: string;
+}
+
+/** 剥租户段：`/acme/users` + slug `acme` → `/users`。 */
+export function stripTenantSegment(pathname: string, tenantSlug?: string | null): string {
+	if (!tenantSlug) return pathname || '/';
+	const prefix = '/' + tenantSlug;
+	if (pathname === prefix) return '/';
+	return pathname.startsWith(prefix + '/') ? pathname.slice(prefix.length) : pathname;
+}
+
+export interface BreadcrumbTrailItem {
+	label: string;
+	/** 有 href 的是可点的中间段；末段没有 href。 */
+	href?: string;
+}
+
+/**
+ * 纯函数：把站内相对路径变成面包屑的「轨迹」。抽出来是因为它才是三份实现真正重复的部分，
+ * 而且是唯一能**脱离 React 单测**的部分（渲染那层用 antd，测试价值低）。
+ */
+export function buildBreadcrumbTrail({
+	path,
+	labels,
+	home,
+	detailLabel,
+	buildHref = (p) => p,
+}: {
+	path: string;
+	labels: Record<string, string>;
+	home?: { label: string; href: string };
+	detailLabel?: string;
+	/** 站点的链接构造（各站带租户前缀的方式不同）。默认原样返回。 */
+	buildHref?: (path: string) => string;
+}): BreadcrumbTrailItem[] {
+	const trail: BreadcrumbTrailItem[] = [];
+	if (home && path !== '/') trail.push({ label: home.label, href: home.href });
+
+	const parts = path.split('/').filter(Boolean);
+	let current = '';
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		current += '/' + part;
+		const isLast = i === parts.length - 1;
+		const known = labels[current];
+		if (known) {
+			trail.push({ label: known, href: isLast ? undefined : buildHref(current) });
+			continue;
+		}
+		// 未命中映射表：像 ID 的段显示成 detailLabel（admin 早就有的启发式），
+		// 其余原样显示 —— **不静默丢掉一段**，否则面包屑会与实际位置不符（platform 之前就是丢掉）。
+		const looksLikeId = /^[a-zA-Z0-9_-]+$/.test(part) && part.length > 8;
+		const label = looksLikeId && detailLabel ? detailLabel : part;
+		trail.push({ label, href: isLast ? undefined : buildHref(current) });
+	}
+	return trail;
+}
+
+export function Breadcrumb({
+	pathname,
+	tenantSlug,
+	labels,
+	home,
+	detailLabel,
+	buildHref,
+	className = 'mb-4',
+}: BreadcrumbProps) {
+	const path = stripTenantSegment(pathname, tenantSlug);
+	if (path === '/') return null;
+
+	const trail = buildBreadcrumbTrail({ path, labels, home, detailLabel, buildHref });
+	// 只有一项（例如首页项）时不渲染 —— 三个门户原本都有这条规则，保留它。
+	if (trail.length <= 1) return null;
+
+	return (
+		<AntBreadcrumb
+			className={className}
+			items={trail.map((item, i) => ({
+				title: item.href ? <Link to={item.href}>{item.label}</Link> : item.label,
+				key: (item.href ?? '') + i,
+			}))}
+		/>
+	);
+}

package/src/antd/DataTable.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+// DataTable —— 四个门户共用的表格。
+//
+// 它是什么：**薄透传**。
+//   统一（本组件 + 上游主题负责）：密度 · 表头 · 悬浮态 · 边框 · 行高 · 分页外观 · 与 DS 令牌一致的配色
+//   透传（本组件不碰）：columns · rowKey · scroll · onRow · rowSelection · expandable
+//                     · sticky · tableLayout · 以及 antd Table 的其余全部 props（...rest）
+//
+// 为什么必须是薄透传：三个控制台现存 156 处 antd Table，用到的 props 面远超「视觉六项」。
+//   若这里改成一套自研的窄 API，等于**用自制 API 取代 antd 的成熟 API** —— 与「antd 比我们手写的成熟」
+//   这个定调相反，而且 156 处都要改造。薄透传下，一致性收益收窄为「视觉六项」，但它是真的、代价可控。
+//
+// 视觉那六项**不在这里写死**：它们在 @autional/tokens 的 antd 桥里（components.Table），
+// 由 AntdThemeProvider 下发给 ConfigProvider。所以即便某个门户暂时没换用 DataTable，
+// 只要挂了 Provider，它的表格外观也已经统一 —— 覆盖面比「只统一换用处」大一个数量级。
+
+import { Table } from 'antd';
+import type { TableProps } from 'antd';
+
+export type DataTableProps<T extends object = Record<string, unknown>> = TableProps<T>;
+
+/**
+ * 列定义类型。单独导出是为了让站点**不必**为了写 columns 去 import antd 的类型 ——
+ * 站点侧一旦 import 了 antd，C5 台账（入口棘轮）就会记上一笔，
+ * 而「一个概念只应有一个入口」正是这一层要守住的东西。
+ */
+export type DataTableColumns<T extends object = Record<string, unknown>> = NonNullable<TableProps<T>['columns']>;
+
+/**
+ * 分页配置类型。站点此前用 antd 的 `TablePaginationConfig`；这个别名是它的替代品 ——
+ * 目标（D10 的 Table 批次）是让控制台**不再从 antd 取任何与表格相关的类型或组件**，
+ * 少一个类型别名，那批就少一处 import antd 的理由。
+ */
+export type DataTablePagination<T extends object = Record<string, unknown>> = Exclude<NonNullable<TableProps<T>['pagination']>, false>;
+
+function DataTableInner<T extends object = Record<string, unknown>>({
+	size = 'middle',
+	pagination,
+	...rest
+}: TableProps<T>) {
+	// 分页外观是 DS 的事（每页条数可切换）；调用方传 pagination 时仍以它为准。
+	const mergedPagination =
+		pagination === false || pagination === undefined
+			? pagination
+			: { showSizeChanger: true, ...pagination };
+
+	return <Table<T> size={size} pagination={mergedPagination} {...rest} />;
+}
+
+/**
+ * 复合成员必须一并透传 —— 这是「薄透传」契约的一部分，不是可选的糖。
+ *
+ * 为什么：antd 的 Table 是**复合组件**（Table.Summary / Column / ColumnGroup / 选择与展开的哨兵）。
+ * 只导出一个函数组件，等于把这些能力从 DS 入口里**删掉** —— 消费方要用汇总行时只剩两条路：
+ *   ① 直接 import antd（C5 台账多一笔，两个入口）；
+ *   ② 自己拼裸 <tr>/<td> 绕过 DS 的表格样式（那就等于没用 DS）。
+ * 两条路都破坏「一个概念一个入口」。
+ * 实测就是这么撞上的：user 的发票明细表需要一行合计（原来的手写表用 <tfoot>）。
+ */
+type DataTableStatics = Pick<
+	typeof Table,
+	| 'Summary'
+	| 'Column'
+	| 'ColumnGroup'
+	| 'SELECTION_COLUMN'
+	| 'SELECTION_ALL'
+	| 'SELECTION_INVERT'
+	| 'SELECTION_NONE'
+	| 'EXPAND_COLUMN'
+>;
+
+export const DataTable = Object.assign(DataTableInner, {
+	Summary: Table.Summary,
+	Column: Table.Column,
+	ColumnGroup: Table.ColumnGroup,
+	SELECTION_COLUMN: Table.SELECTION_COLUMN,
+	SELECTION_ALL: Table.SELECTION_ALL,
+	SELECTION_INVERT: Table.SELECTION_INVERT,
+	SELECTION_NONE: Table.SELECTION_NONE,
+	EXPAND_COLUMN: Table.EXPAND_COLUMN,
+}) as typeof DataTableInner & DataTableStatics;

package/src/antd/DateRangeFilter.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+// DateRangeFilter —— 日期区间筛选器（antd RangePicker 之上的薄封装）。
+//
+// 它要解决的问题很小、但每个站点都在各自解决一遍：antd 的 RangePicker 收发的值是 dayjs 对象，
+// 而**查询参数要的是字符串**。于是每个调用点都得记住用 onChange 的第二个参数（格式化后的字符串数组），
+// 或者自己 dayjs() 一遍。实测控制台里已经有人这么写了：
+//   onChange={(_, dates) => setDateRange(dates && dates[0] && dates[1] ? (dates as [string,string]) : null)}
+// —— 也就是说这个约定是**既成事实**，只是没人把它固化下来。固化在这里之后：
+//   · 站点不再需要 import dayjs（值进值出都是字符串）；
+//   · 「空区间」只有一种表示（null），不再有 undefined / [] / ['',''] 三种写法；
+//   · 显示格式与产出格式**是同一个** `format`，不会出现「显示带时间、产出只有日期」这种静默丢数据。
+//
+// 与 DataTable 同一条边界：DS 只固定**跨门户必须一致的部分**（值域类型、空值语义、与设计系统同源的
+// 外观/locale），其余（showTime / disabledDate / className / placeholder / presets…）全部透传。
+
+import { DatePicker } from 'antd';
+import dayjs from 'dayjs';
+import type { Dayjs } from 'dayjs';
+import type { RangePickerProps } from 'antd/es/date-picker';
+
+const { RangePicker } = DatePicker;
+
+/** 区间值：ISO 或与 `format` 一致的字符串二元组；`null` 表示未选。 */
+export type DateRangeValue = [string, string] | null;
+
+// 除 value / onChange / format 之外全部透传给 antd RangePicker。
+export interface DateRangeFilterProps extends Omit<RangePickerProps, 'value' | 'onChange' | 'format'> {
+	/** 当前区间。`null` / 省略表示无筛选。 */
+	value?: DateRangeValue;
+	/** 选中区间时回调；清空时回调 `null`（**不是**空数组或空串）。 */
+	onChange?: (value: DateRangeValue) => void;
+	/** 显示格式，同时也是**产出字符串的格式**（默认 `YYYY-MM-DD`）。带 showTime 时应显式给到含时间的格式。 */
+	format?: string;
+}
+
+const DEFAULT_FORMAT = 'YYYY-MM-DD';
+
+const toDayjs = (s: string | undefined): Dayjs | null => {
+	const d = s ? dayjs(s) : null;
+	return d && d.isValid() ? d : null;
+};
+
+export function DateRangeFilter({ value, onChange, format = DEFAULT_FORMAT, ...rest }: DateRangeFilterProps) {
+	const range: [Dayjs | null, Dayjs | null] | null = value ? [toDayjs(value[0]), toDayjs(value[1])] : null;
+
+	return (
+		<RangePicker
+			{...rest}
+			format={format}
+			value={range}
+			onChange={(dates) => {
+				// antd 在清空时给 null（有时是 [null, null]），统一收敛成一种空值表示。
+				const start = dates?.[0];
+				const end = dates?.[1];
+				if (!start || !end) {
+					onChange?.(null);
+					return;
+				}
+				onChange?.([start.format(format), end.format(format)]);
+			}}
+		/>
+	);
+}

package/src/antd/Drawer.tsx

@@ -0,0 +1,39 @@
+'use client';
+
+import React from 'react';
+import { Drawer as AntDrawer } from 'antd';
+import type { DrawerProps as AntDrawerProps } from 'antd';
+
+// Drawer —— 详情/编辑抽屉（antd Drawer 之上的薄封装）。
+//
+// 与 DataTable 同一条边界：DS 只固定**跨门户必须一致的部分**，其余全部透传。
+//
+// 实测（2026-10-04，21 处直接使用 antd Drawer）暴露的是**词汇**问题，不是外观问题：
+//   admin     size={600} / size="large" / size={500} / size={560} / size={720}
+//   platform  （不写尺寸，落到 antd 默认）
+//   security  width={600} / width={560} / width={700} / width={520} / placement="right" / destroyOnClose
+// 也就是说：同一个东西有**两个属性名**（antd 6 把 width 收成了 size，security 还停在旧名），
+// 尺寸是**八个各写各的数字**，destroyOnClose 在 antd 6.5 里已标 @deprecated（新名 destroyOnHidden）——
+// 那是「改了一半的迁移」留在源码里的样子。
+//
+// 所以这一件固定三样：
+//   ① **尺寸词汇**：sm/md/lg/xl 四档（480 / 560 / 720 / 960），不再接受任意数字；
+//   ② **placement 恒为 right**：本舰队的抽屉都是「右侧详情」，把方向也收进契约；
+//   ③ **不再暴露 width 与 destroyOnClose**：前者是旧名，后者是废弃名（类型上直接 Omit 掉，
+//      写错就编译不过 —— 比在文档里写「请用新名字」有效）。
+//
+// 尺寸阶梯是按现有取值就近归的，不是拍脑袋：
+//   500/520 → sm(480) · 560/600 → md(560) · 700/720/antd-large(736) → lg(720)
+export type DrawerSize = 'sm' | 'md' | 'lg' | 'xl';
+
+const SIZES: Record<DrawerSize, number> = { sm: 480, md: 560, lg: 720, xl: 960 };
+
+export interface DrawerProps
+	extends Omit<AntDrawerProps, 'size' | 'width' | 'destroyOnClose' | 'placement'> {
+	/** 尺寸档位，默认 md(560px)。 */
+	size?: DrawerSize;
+}
+
+export function Drawer({ size = 'md', ...rest }: DrawerProps) {
+	return <AntDrawer {...rest} placement="right" size={SIZES[size]} />;
+}

package/src/antd/Modal.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+import React from 'react';
+import { Modal as AntModal } from 'antd';
+import type { ModalProps as AntModalProps } from 'antd';
+import { useTranslation } from 'react-i18next';
+import { UI_I18N_NS, uiText } from '../i18n';
+
+// Modal —— 对话框（antd Modal 之上的薄封装）。
+//
+// 与 Drawer 同一条边界：DS 只固定**跨门户必须一致的部分**，其余全部透传。
+//
+// 这一件只固定一样：**关闭按钮的无障碍名称**。
+// 按钮的 aria-label 由 rc-dialog 写死为英文 "Close"（Panel 里 `aria-label: "Close"`），
+// antd 的 locale 只把它翻到关闭**图标**元素上、到不了按钮本身 —— 读屏用户听到的恒为 "Close"。
+// 能压过它的只有 closable 对象里的 aria-* 属性（rc-dialog 把它们展开在写死值**之后**），
+// 所以这里默认注入本地化标签；用户显式在 closable 里传了 aria-label 就以用户的为准。
+//
+// 文案走设计系统那套解析链（站点 i18next 注册过就优先，没有就回落内置表），与 PageStatus 同一条。
+
+export type ModalProps = AntModalProps;
+
+export function Modal({ closable, ...rest }: ModalProps) {
+	const { t, i18n } = useTranslation();
+	const closeLabel = t('modal.close', {
+		ns: UI_I18N_NS,
+		defaultValue: uiText(i18n.language, 'modal.close') ?? '关闭',
+	});
+	// closable === false 保持 false（不渲染关闭按钮）；true/undefined/对象统一并入本地化标签。
+	const mergedClosable =
+		closable === false
+			? false
+			: {
+					'aria-label': closeLabel,
+					...(typeof closable === 'object' && closable !== null ? closable : {}),
+				};
+	return <AntModal closable={mergedClosable} {...rest} />;
+}

package/src/antd/PageStatus.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+// 控制台的整页占位：加载中 / 加载失败（可重试）。
+//
+// 为什么把它收进设计系统：admin 与 platform 此前**各有一份**
+// src/components/ui/page-status.tsx，内容逐字相同（同一个居中 Spin、同一个
+// Empty.PRESENTED_IMAGE_SIMPLE、同一个重试按钮），唯一差别是 admin 走 react-i18next、
+// platform 把中文写死在组件里 —— 于是同一件事有了两份实现，而且其中一份永远只能是中文。
+// 实测用量：admin 70 个文件 import 它 / <PageError> 96 处；platform 13 个文件 /
+// <PageError> 43 处 + <PageLoading> 13 处。抄成两份的东西必然有一份先坏，这里留唯一一份。
+//
+// 文案走设计系统那套解析链（站点 i18next 注册过就优先，没有就回落内置表），与 PortalSwitcher 同一条。
+// 重试图标用 lucide 而不是 @ant-design/icons：设计系统已有的组件（ErrorState）就是 lucide，
+// 而 antd 的图标包是本包**没有**声明的依赖 —— 为了一个重试图标去给所有人加一条 peer 不划算。
+
+import { Button, Empty, Spin } from 'antd';
+import { RefreshCw } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { UI_I18N_NS, uiText } from '../i18n';
+
+export interface PageLoadingProps {
+	/** 覆盖默认的「加载中…」。 */
+	tip?: string;
+	className?: string;
+}
+
+export interface PageErrorProps {
+	/** 覆盖默认的「数据加载失败」。 */
+	message?: string;
+	retry?: () => void;
+	className?: string;
+}
+
+function useStatusText() {
+	const { t, i18n } = useTranslation();
+	return (key: string, lastResort: string): string => {
+		const builtin = uiText(i18n.language, key);
+		return t(key, { ns: UI_I18N_NS, defaultValue: builtin ?? lastResort });
+	};
+}
+
+/** 整页加载占位（居中 Spin）。 */
+export function PageLoading({ tip, className = '' }: PageLoadingProps) {
+	const text = useStatusText();
+	return (
+		<div className={`flex h-64 items-center justify-center ${className}`}>
+			<Spin size="large" description={tip ?? text('pageStatus.loading', '加载中…')} />
+		</div>
+	);
+}
+
+/** 整页错误占位（带重试按钮）。 */
+export function PageError({ message, retry, className = '' }: PageErrorProps) {
+	const text = useStatusText();
+	return (
+		<div className={`flex h-64 flex-col items-center justify-center gap-4 ${className}`}>
+			<Empty
+				description={message ?? text('pageStatus.loadError', '数据加载失败')}
+				image={Empty.PRESENTED_IMAGE_SIMPLE}
+			/>
+			{retry && (
+				<Button icon={<RefreshCw className="h-4 w-4" />} onClick={retry}>
+					{text('pageStatus.retry', '重试')}
+				</Button>
+			)}
+		</div>
+	);
+}

package/src/antd/index.ts

@@ -0,0 +1,27 @@
+// 数据密集入口 —— 消费方从这里取 antd 能力，不直接 import 'antd'。
+//
+// 这一句不是形式主义：四站各自 import antd，同一个概念就会长出四种用法（实测控制台侧
+// 152 处直接 import，user 侧 0 处、手写 13 个表格）。统一入口之后，一致性才来自 API 而不是巧合。
+
+export { AntdThemeProvider, useAntdApp } from './AntdThemeProvider';
+export type { AntdThemeProviderProps, AntdAppApi } from './AntdThemeProvider';
+export { Breadcrumb, buildBreadcrumbTrail, stripTenantSegment } from './Breadcrumb';
+export type { BreadcrumbProps, BreadcrumbTrailItem } from './Breadcrumb';
+export { DateRangeFilter } from './DateRangeFilter';
+export type { DateRangeFilterProps, DateRangeValue } from './DateRangeFilter';
+export { Drawer } from './Drawer';
+export type { DrawerProps, DrawerSize } from './Drawer';
+export { Modal } from './Modal';
+export type { ModalProps } from './Modal';
+
+// 整页占位：控制台的加载 / 加载失败。与 DataTable 同一个入口，站点一次 import 拿全。
+export { PageLoading, PageError } from './PageStatus';
+export type { PageLoadingProps, PageErrorProps } from './PageStatus';
+export { DataTable } from './DataTable';
+export type { DataTableProps, DataTableColumns, DataTablePagination } from './DataTable';
+
+// 类型再导出：站点侧的命令式 API 门面（`export let message` 那类）需要这些类型，
+// 若让它们各自 `import type ... from 'antd/es/message/interface'`，
+// 「站点不直接依赖 antd 的内部路径」这条就破了——antd 只是本包的可选 peer。
+export type { MessageInstance } from 'antd/es/message/interface';
+export type { NotificationInstance } from 'antd/es/notification/interface';