@ploykit/ui 0.2.0 → 0.4.1

package/README.md

@@ -1,41 +1,201 @@
-# @ploykit/ui
-
-React 前端壳：登录/工作区/计费的 Headless Hook + 默认页面。
-
-## 快速使用
-
-```tsx
-import { PloykitProvider, useAuth, useLogin, LoginPage } from '@ploykit/ui'
-
-// App 根部
-<PloykitProvider>
-  <App />
-</PloykitProvider>
-
-// 任意组件中
-const { user, workspaces, loading } = useAuth()
-const { sendCode, submit } = useLogin()
-
-// 或直接用默认登录页
-<LoginPage />
-```
-
-## 核心 API
-
-| 导出 | 说明 |
-|---|---|
-| `PloykitProvider` | 根 Provider（App 根部包裹一次） |
-| `useAuth()` | `{ user, workspaces, loading, refresh, logout }` |
-| `useLogin()` | `{ sendCode, submit, loading, error }` |
-| `useWorkspace()` | `{ current, switchTo, clear }` |
-| `useWorkspaceSwitch()` | `{ current, list, switchTo, create, creating }` |
-| `useBilling()` | `{ subscription, plans, checkout, loading }` |
-| `PlanGate` | 付费门 `<PlanGate plan="pro" denied={<Upgrade/>}>` |
-| `useApi()` | `{ get, post, put, delete }` 带认证 + 工作区上下文 |
-| `LoginPage` | 默认登录页（可拷贝自定义，Hook 不变） |
-
-## 自定义三个层级
-
-1. **换皮**：CSS/Tailwind 覆盖样式
-2. **换壳**：拷贝 `LoginPage.tsx` 到产品 `src/pages/`，改 JSX，Hook 调用不变
-3. **纯逻辑**：只 `import { useLogin } from '@ploykit/ui'`，完全自己画 UI
+# @ploykit/ui
+
+React 前端壳：默认页面 + 组件。逻辑与状态在 [hooks](../hooks) 与 [client](../client) 里，本包是它们的渲染层。
+
+| 包 | 内容 |
+|---|---|
+| `@ploykit/ui` | 组件壳、默认页面、全局组合件（本包） |
+| `@ploykit/hooks` | `PloykitProvider` + headless hooks（认证/工作区/计费） |
+| `@ploykit/client` | typed API client + CSRF（hooks 的底层） |
+
+依赖方向：ui → hooks → client。Peer deps：`react` 19 / `react-dom` 19 / `@tanstack/react-query` 5 / `react-router` 7 / `tailwindcss` 4。产物为 ESM（相对导入无扩展名，需经 vite/esbuild 等打包器解析）。
+
+## 快速使用
+
+```tsx
+import { AppProviders } from '@ploykit/ui'
+import { useAuth, useLogin, useApi } from '@ploykit/hooks'
+import { LoginPage } from '@ploykit/ui'
+
+// 应用根部：一层包完（PloykitProvider > ConfirmProvider > Toaster 三层组合）
+<AppProviders>
+  <App />
+</AppProviders>
+
+// 已有自己的 QueryClient 时透传（不传则内部创建默认 QueryClient）
+<AppProviders queryClient={queryClient}>...</AppProviders>
+
+// 数据 hooks 一律来自 @ploykit/hooks
+const { user, loading } = useAuth()
+const api = useApi()
+
+// 默认页面来自 @ploykit/ui
+<Route path="/login" element={<LoginPage />} />
+```
+
+等价的手动三层挂法（需要插入自定义 Provider 层时用）：
+
+```tsx
+import { PloykitProvider } from '@ploykit/hooks'
+import { ConfirmProvider, Toaster } from '@ploykit/ui'
+
+<PloykitProvider queryClient={queryClient}>
+  <ConfirmProvider>
+    <App />
+    <Toaster />
+  </ConfirmProvider>
+</PloykitProvider>
+```
+
+要复用全局 QueryClient 实例时，自行 `new QueryClient()` 后经 `queryClient` 传给 `PloykitProvider`。默认 QueryClient 的行为：`staleTime` 30s、4xx 不重试、窗口聚焦不重取。
+
+## 全局 Provider 清单
+
+| Provider | 导入自 | 职责 |
+|---|---|---|
+| `PloykitProvider` | `@ploykit/hooks` | 认证会话（`/auth/me`）+ 当前工作区上下文 + react-query `QueryClientProvider` |
+| `ConfirmProvider` | `@ploykit/ui` | 提供 `useConfirm()` 的 Promise 式弹窗确认 |
+| `Toaster` | `@ploykit/ui` | sonner 通知渲染（默认右上角、richColors；`toast.error` 时长 8s） |
+
+漏挂症状：
+
+- 缺 `PloykitProvider`：`useAuth` / `useWorkspace` / `useApi` 等直接 throw `must be used within PloykitProvider`。
+- 缺 `ConfirmProvider`：`useConfirm()` 直接 throw `useConfirm must be used within ConfirmProvider`（fail-fast；旧版曾静默返回 `false`，导致"点了没反应且无报错"，已废弃）。
+- 缺 `Toaster`：不报错，但所有 `toast()` 调用无任何可见提示。
+
+三个 Provider 都不相互依赖，`AppProviders` 的嵌套顺序只是惯例；推荐统一挂最外层，保证登录前页面也能用 `useConfirm` / `toast`。
+
+## Headless hooks（`@ploykit/hooks`）
+
+| 导出 | 契约 |
+|---|---|
+| `useAuth()` | `{ user, workspaces, loading, error, refresh, logout }` |
+| `useLogin()` | `{ sendCode(email), submit(email, code), loading, error }`；`submit` 返回 `{ ok, error? }` |
+| `useWorkspace()` | `{ current, switchTo(id), clear }`；当前工作区 ID 同步进 URL `?ws=` 与 localStorage |
+| `useWorkspaceSwitch()` | `{ current, list, switchTo, create(name, slug), creating, error }`；`create` 失败返回 `null` |
+| `useBilling()` | `{ subscription, plans, checkout(planCode, interval, channel), checkoutError, loading, refresh }` |
+| `useUsagePreview()` | `{ preview, loading }` |
+| `PlanGate` | `<PlanGate plan="pro" denied={...}>{children}</PlanGate>`；按 `plans.sort_no` 做档位判定，`busy` prop 自定义加载态 |
+| `useApi()` | `{ get, post, put, patch, delete }`；自动携带凭据与当前工作区 ID |
+| `ApiError` | 带 `status` 的 API 错误类（可 `instanceof` 判 4xx） |
+| `queryKeys` | react-query query key 常量表（`queryKeys.me`、`queryKeys.billingSubscription(wsId)` 等） |
+
+其余 hooks（`useSessions` / `useTokens` / `useMembers` / `useAudit` / `useSEO` / `useZodForm` / `useWsStatus` 等）见 `packages/hooks/src/index.ts`。
+
+## 组件
+
+### DataTable
+
+```tsx
+import { DataTable, type Column } from '@ploykit/ui'
+
+interface User { id: string; name: string; code: string }
+
+const columns: Column<User>[] = [
+  { key: 'name', header: '名称', render: (u) => <b>{u.name}</b> },
+  {
+    key: 'actions',
+    header: <span className="sr-only">操作</span>, // 别传 ''——空串 th 会塌陷
+    className: 'whitespace-nowrap',                // 操作列防换行惯例
+    render: (u) => <Button size="xs" variant="outline">编辑</Button>,
+  },
+]
+
+<DataTable
+  columns={columns}
+  rows={rows}
+  rowKey={(row) => row.id}          // 同业务键多行（如同 code 多版本）时用下标拼唯一 key：(row, i) => `${row.code}:${i}`
+  onRowClick={(row) => openDetail(row)} // 整行点击；传入后行 hover 显示 pointer
+  renderExpanded={(row) => row.open ? <Detail row={row} /> : null} // 返回非 null 即在该行后插入 colSpan 全宽展开行；展开状态由行数据自行表达
+  loading={isLoading}
+  pagination={{ page, pageSize, total, onPageChange: setPage }}
+/>
+```
+
+- `Column<T>` = `{ key, header: ReactNode, render?(row), className? }`；不传 `render` 时取 `row[key]` 字符串化。
+- `rowKey: (row, index) => string`（第二参可省）。
+- 分页条内置"上一页/下一页"；翻页后数据为空时显示"本页没有数据，可返回上一页"而非空态。
+- `loading` 时表体渲染骨架行；`empty` 可自定义空态（默认 `<PageEmpty />`）。
+
+### Dialog / Sheet 尺寸档位
+
+`DialogContent` 新增 `size` 档位（默认 `sm`，即原有 384px 宽度，现有代码不受影响）：
+
+| size | max-width |
+|---|---|
+| `"sm"`（默认） | `sm:max-w-sm` |
+| `"md"` | `sm:max-w-lg` |
+| `"lg"` | `sm:max-w-2xl` |
+| `"xl"` | `sm:max-w-4xl` |
+
+`SheetContent` 新增 `size?: "sm" | "md" | "lg"`（默认 `sm` = 原有 `sm:max-w-sm`）；`side` 仍为 `"top" | "right" | "bottom" | "left"`（默认右侧），右侧/底部预设自带 `overflow-y-auto`。两者另有 `showCloseButton?: boolean`（默认 `true`）。Sheet 全套组合件从 barrel 导出：`Sheet`（受控 Root）、`SheetTrigger`、`SheetClose`、`SheetHeader`、`SheetFooter`、`SheetTitle`、`SheetDescription`。
+
+```tsx
+<Dialog open={open} onOpenChange={setOpen}>
+  <DialogContent size="lg">...</DialogContent>
+</Dialog>
+```
+
+### Select 使用注意
+
+```tsx
+import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@ploykit/ui'
+
+<Select value={v} onValueChange={(value) => setV(value)}>  {/* value: string，不再是 string | null */}
+```
+
+- `onValueChange` 契约为 `(value: string) => void`：清空/取消选择时收到空串 `''`，不会出现 `string | null`。
+- `SelectTrigger` 自有 `size?: "sm" | "default"`（高度档位：`sm` = h-7，`default` = h-8）。注意与 Button 的 `size` 枚举（`default` / `xs` / `sm` / `lg` / `icon`…）不同名不同义。
+- 其余件（`SelectContent` / `SelectItem` / `SelectGroup` / `SelectLabel` / `SelectSeparator` 等）为 `@base-ui/react` Select 直出。
+
+### SecretModal（仅显示一次的密钥弹窗）
+
+```tsx
+<SecretModal
+  open={open}
+  onOpenChange={setOpen}
+  secretName="My Token"
+  secretValue={token}
+  title="新密钥已生成"  // 可选；不传时默认 `${secretName} 创建成功`
+/>
+```
+
+安全契约：用户勾选"我已将密钥保存到安全的地方"之前，`onOpenChange` **不会收到 `false`**——ESC、遮罩点击、关闭按钮均被拦截，调用方无需自行兜底。内置复制按钮（2s 成功/失败反馈），每次打开重置勾选与复制状态。`title` prop 用于"重置 Key"等非创建成功场景覆盖默认标题。
+
+### ImpactConfirmation（破坏性操作确认）
+
+```tsx
+<ImpactConfirmation
+  open={open}
+  onOpenChange={setOpen}
+  onConfirm={doDelete}
+  title="删除调度"
+  impacts={[
+    '将删除 3 条调度',
+    <>关联的 <b>12</b> 条执行历史将被保留</>,  // impacts: ReactNode[]，可含富文本
+  ]}
+  confirmText="确认删除"
+  danger
+/>
+```
+
+- 勾选"我理解并接受以上影响"前确认按钮禁用；确认后先回调 `onConfirm` 再关闭。
+- 影响列表区自带 `max-h-48 overflow-y-auto`，项多时内部滚动，弹窗不被撑出视口。
+
+### Textarea
+
+与 `Input` 同 token 的多行文本域（`rounded-lg border-input` 等一致），从 barrel 直接导入。
+
+### 其他常用导出
+
+- **布局**：`AppShell` / `SettingsShell` / `AuthShell` / `AdminShell` + 全套 Sidebar。
+- **页面**：`LoginPage`（props：`resetPath` / `registerPath` / `oauthProviders` / `enableFedLogin` / `onSuccess` / `title` / `description`；`resetPath` / `registerPath` **传空串即隐藏对应链接**——产品未挂载 /forgot-password、/register 路由时防止死链 404）、`RegisterPage`、`ForgotPasswordPage`、`ResetPasswordPage`、`VerifyEmailPage`、`InviteAcceptPage`，以及 workspace/account/admin 各默认页面。
+- **反馈与状态**：`StatusBadge`、`PageHeader` / `PageLoading` / `PageEmpty` / `PageError`、`ErrorBoundary`、`ReauthDialog`（step-up sudo 模式弹窗）。
+- **工具**：`cn`、`formatDate` / `formatDateTime` / `shortID`、`statusTone` / `statusLabel`、`apiErrorMessage`、`FormField`、`CronInput`。
+- 基础 UI 件（Button / Input / Card / Tabs / AlertDialog / DropdownMenu / Popover / Switch / Checkbox / Progress / Avatar / Breadcrumb / Empty / Field / Label / Tooltip / Skeleton / Separator…）全部从 barrel 导出；也可走子路径 `import { Button } from '@ploykit/ui/components/ui/button'`（推荐统一走 barrel）。
+
+## 自定义三个层级
+
+1. **换皮**：CSS/Tailwind 覆盖样式（组件全部走 design token：`bg-popover`、`text-muted-foreground` 等）。
+2. **换壳**：拷贝 `LoginPage.tsx` 等默认页面到产品 `src/pages/`，改 JSX，hook 调用不变（hooks 从 `@ploykit/hooks` 导入）。
+3. **纯逻辑**：只 `import { useLogin } from '@ploykit/hooks'`，完全自己画 UI。

package/dist/AppProviders.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+import type { QueryClient } from '@tanstack/react-query';
+/**
+ * 框架级全局 Provider 一步到位组合件：PloykitProvider > ConfirmProvider > Toaster。
+ *
+ * 产品侧用它替换"逐个手挂三层 Provider"的样板（example/web/src/routes.tsx 的
+ * AppProviders 即此组合的 historically hand-written 版本）。嵌套顺序即依赖顺序：
+ * confirm 与 toast 均不依赖 auth/workspace 上下文，但统一挂在最外层可保证任何
+ * 页面（含登录前页面）都能调用 useConfirm / toast。
+ */
+export declare function AppProviders({ children, queryClient }: {
+    children: ReactNode;
+    /** 透传给 PloykitProvider；不传时由其内部创建默认 QueryClient。 */
+    queryClient?: QueryClient;
+}): import("react").JSX.Element;

package/dist/AppProviders.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PloykitProvider } from '@ploykit/hooks';
+import { ConfirmProvider } from './components/ConfirmDialog';
+import { Toaster } from './components/toast';
+/**
+ * 框架级全局 Provider 一步到位组合件：PloykitProvider > ConfirmProvider > Toaster。
+ *
+ * 产品侧用它替换"逐个手挂三层 Provider"的样板（example/web/src/routes.tsx 的
+ * AppProviders 即此组合的 historically hand-written 版本）。嵌套顺序即依赖顺序：
+ * confirm 与 toast 均不依赖 auth/workspace 上下文，但统一挂在最外层可保证任何
+ * 页面（含登录前页面）都能调用 useConfirm / toast。
+ */
+export function AppProviders({ children, queryClient }) {
+    return (_jsx(PloykitProvider, { queryClient: queryClient, children: _jsxs(ConfirmProvider, { children: [children, _jsx(Toaster, {})] }) }));
+}

package/dist/components/ConfirmDialog.js

@@ -1,7 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useState } from 'react';
 import { AlertDialog, AlertDialogContent, AlertDialogHeader, AlertDialogTitle, AlertDialogDescription, AlertDialogFooter, AlertDialogCancel, AlertDialogAction, } from './ui/alert-dialog';
-const ConfirmContext = createContext(async () => false);
+// 缺省值必须是 null + useConfirm fail-fast（对齐 hooks 包 useAuthCtx 的行为）：
+// 曾经的缺省值是 `async () => false`，产品忘挂 ConfirmProvider 时 confirm 静默返回
+// false，"重置 Key"之类的按钮点了没反应且无任何报错，排查损耗极大。
+const ConfirmContext = createContext(null);
 export function ConfirmProvider({ children }) {
     const [state, setState] = useState(null);
     const confirm = useCallback((opts) => {
@@ -25,5 +28,8 @@ export function ConfirmProvider({ children }) {
     return (_jsxs(ConfirmContext.Provider, { value: confirm, children: [children, _jsx(AlertDialog, { open: !!state, onOpenChange: (open) => !open && handleClose(false), children: _jsxs(AlertDialogContent, { children: [_jsxs(AlertDialogHeader, { children: [_jsx(AlertDialogTitle, { children: state?.title }), state?.description && _jsx(AlertDialogDescription, { children: state.description })] }), _jsxs(AlertDialogFooter, { children: [_jsx(AlertDialogCancel, { onClick: () => handleClose(false), children: state?.cancelText ?? '取消' }), _jsx(AlertDialogAction, { variant: state?.danger ? 'destructive' : 'default', onClick: () => handleClose(true), children: state?.confirmText ?? '确认' })] })] }) })] }));
 }
 export function useConfirm() {
-    return useContext(ConfirmContext);
+    const confirm = useContext(ConfirmContext);
+    if (!confirm)
+        throw new Error('useConfirm must be used within ConfirmProvider');
+    return confirm;
 }

package/dist/components/DataTable.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 export interface Column<T> {
     key: string;
     header: ReactNode;
@@ -14,9 +14,18 @@ export interface DataTablePagination {
 export interface DataTableProps<T> {
     columns: Column<T>[];
     rows: T[];
-    rowKey: (row: T) => string;
+    /** 行 key 生成器。第二参数是该行在 rows 中的下标，用于同业务键多行（如同 code 多版本）时拼出唯一 key。少参回调仍然兼容。 */
+    rowKey: (row: T, index: number) => string;
     loading?: boolean;
     empty?: ReactNode;
+    /** 整行点击回调。传入后行 hover 显示 pointer 光标。 */
+    onRowClick?: (row: T) => void;
+    /**
+     * 展开行扩展点：对每行调用，返回非 null 时在该行下方插入一个展开行
+     * （单个 td，colSpan 覆盖全部列）。展开/收起状态由调用方用行数据自行表达
+     * （收起的行返回 null 即不渲染）——本组件不持有内部展开状态。
+     */
+    renderExpanded?: (row: T, index: number) => ReactNode;
     pagination?: DataTablePagination;
 }
-export declare function DataTable<T>({ columns, rows, rowKey, loading, empty, pagination }: DataTableProps<T>): import("react").JSX.Element;
+export declare function DataTable<T>({ columns, rows, rowKey, loading, empty, onRowClick, renderExpanded, pagination }: DataTableProps<T>): import("react").JSX.Element;

package/dist/components/DataTable.js

@@ -1,13 +1,17 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment } from 'react';
 import { cn } from '../lib/utils';
 import { PageEmpty } from './Page';
 import { Skeleton } from './ui/skeleton';
 import { Button } from './ui/button';
-export function DataTable({ columns, rows, rowKey, loading = false, empty, pagination }) {
+export function DataTable({ columns, rows, rowKey, loading = false, empty, onRowClick, renderExpanded, pagination }) {
     const stalePage = !!pagination && !loading && rows.length === 0 && (pagination.total > 0 || pagination.page > 1);
     if (!loading && rows.length === 0 && !stalePage) {
         return _jsx(_Fragment, { children: empty ?? _jsx(PageEmpty, {}) });
     }
     const lastPage = pagination ? Math.max(1, Math.ceil(pagination.total / Math.max(1, pagination.pageSize))) : 1;
-    return (_jsxs("div", { className: "bg-card rounded-lg border overflow-hidden", children: [_jsx("div", { className: "overflow-x-auto", children: _jsxs("table", { className: "w-full text-sm", children: [_jsx("thead", { children: _jsx("tr", { className: "border-b bg-muted/50 text-left text-muted-foreground", children: columns.map((col) => (_jsx("th", { className: cn('px-4 py-3 font-medium whitespace-nowrap', col.className), children: col.header }, col.key))) }) }), _jsx("tbody", { children: loading ? (_jsx("tr", { className: "border-b last:border-0", children: columns.map((col) => (_jsx("td", { className: cn('px-4 py-3', col.className), children: _jsx(Skeleton, { className: "h-4 w-full" }) }, col.key))) })) : stalePage ? (_jsx("tr", { children: _jsx("td", { colSpan: columns.length, className: "px-4 py-8 text-center text-sm text-muted-foreground", children: "\u672C\u9875\u6CA1\u6709\u6570\u636E\uFF0C\u53EF\u8FD4\u56DE\u4E0A\u4E00\u9875" }) })) : (rows.map((row) => (_jsx("tr", { className: "border-b last:border-0 hover:bg-muted/30", children: columns.map((col) => (_jsx("td", { className: cn('px-4 py-3', col.className), children: col.render ? col.render(row) : String(row[col.key] ?? '') }, col.key))) }, rowKey(row))))) })] }) }), pagination && (_jsxs("div", { "data-slot": "data-table-pagination", "aria-busy": loading || undefined, className: "flex items-center justify-between border-t px-4 py-3 text-sm text-muted-foreground", children: [loading ? (_jsx("span", { children: "\u52A0\u8F7D\u4E2D\u2026" })) : (_jsxs("span", { children: ["\u5171 ", _jsx("span", { className: "font-medium text-foreground", children: pagination.total }), " \u6761 \u00B7 \u7B2C", ' ', _jsxs("span", { className: "font-medium text-foreground", children: [pagination.page, "/", lastPage] }), ' ', "\u9875"] })), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { size: "sm", variant: "outline", disabled: loading || pagination.page <= 1, onClick: () => pagination.onPageChange(pagination.page - 1), children: "\u4E0A\u4E00\u9875" }), _jsx(Button, { size: "sm", variant: "outline", disabled: loading || pagination.page >= lastPage, onClick: () => pagination.onPageChange(pagination.page + 1), children: "\u4E0B\u4E00\u9875" })] })] }))] }));
+    return (_jsxs("div", { className: "bg-card rounded-lg border overflow-hidden", children: [_jsx("div", { className: "overflow-x-auto", children: _jsxs("table", { className: "w-full text-sm", children: [_jsx("thead", { children: _jsx("tr", { className: "border-b bg-muted/50 text-left text-muted-foreground", children: columns.map((col) => (_jsx("th", { className: cn('px-4 py-3 font-medium whitespace-nowrap', col.className), children: col.header }, col.key))) }) }), _jsx("tbody", { children: loading ? (_jsx("tr", { className: "border-b last:border-0", children: columns.map((col) => (_jsx("td", { className: cn('px-4 py-3', col.className), children: _jsx(Skeleton, { className: "h-4 w-full" }) }, col.key))) })) : stalePage ? (_jsx("tr", { children: _jsx("td", { colSpan: columns.length, className: "px-4 py-8 text-center text-sm text-muted-foreground", children: "\u672C\u9875\u6CA1\u6709\u6570\u636E\uFF0C\u53EF\u8FD4\u56DE\u4E0A\u4E00\u9875" }) })) : (rows.map((row, index) => {
+                                const expanded = renderExpanded ? renderExpanded(row, index) : null;
+                                return (_jsxs(Fragment, { children: [_jsx("tr", { className: cn('border-b last:border-0 hover:bg-muted/30', onRowClick && 'cursor-pointer'), onClick: onRowClick ? () => onRowClick(row) : undefined, children: columns.map((col) => (_jsx("td", { className: cn('px-4 py-3', col.className), children: col.render ? col.render(row) : String(row[col.key] ?? '') }, col.key))) }), expanded !== null && (_jsx("tr", { className: "border-b last:border-0", "data-slot": "data-table-expanded-row", children: _jsx("td", { colSpan: columns.length, className: "px-4 py-3", children: expanded }) }))] }, rowKey(row, index)));
+                            })) })] }) }), pagination && (_jsxs("div", { "data-slot": "data-table-pagination", "aria-busy": loading || undefined, className: "flex items-center justify-between border-t px-4 py-3 text-sm text-muted-foreground", children: [loading ? (_jsx("span", { children: "\u52A0\u8F7D\u4E2D\u2026" })) : (_jsxs("span", { children: ["\u5171 ", _jsx("span", { className: "font-medium text-foreground", children: pagination.total }), " \u6761 \u00B7 \u7B2C", ' ', _jsxs("span", { className: "font-medium text-foreground", children: [pagination.page, "/", lastPage] }), ' ', "\u9875"] })), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { size: "sm", variant: "outline", disabled: loading || pagination.page <= 1, onClick: () => pagination.onPageChange(pagination.page - 1), children: "\u4E0A\u4E00\u9875" }), _jsx(Button, { size: "sm", variant: "outline", disabled: loading || pagination.page >= lastPage, onClick: () => pagination.onPageChange(pagination.page + 1), children: "\u4E0B\u4E00\u9875" })] })] }))] }));
 }

package/dist/components/ErrorBoundary.js

@@ -19,6 +19,6 @@ export class ErrorBoundary extends Component {
         if (fallback !== undefined) {
             return typeof fallback === 'function' ? fallback(error, this.reset) : fallback;
         }
-        return (_jsxs("div", { role: "alert", className: "flex flex-col items-center justify-center py-12 text-center", children: [_jsx("div", { className: "text-4xl mb-3", children: "\u26A0\uFE0F" }), _jsx("p", { className: "text-sm text-red-600", children: "\u51FA\u9519\u4E86" }), error.message && _jsx("p", { className: "mt-1 text-xs text-gray-400", children: error.message }), _jsx("button", { onClick: this.reset, className: "mt-4 px-4 py-2 text-sm border rounded-md hover:bg-gray-50", children: "\u91CD\u8BD5" })] }));
+        return (_jsxs("div", { role: "alert", className: "flex flex-col items-center justify-center py-12 text-center", children: [_jsx("div", { className: "text-4xl mb-3", children: "\u26A0\uFE0F" }), _jsx("p", { className: "text-sm text-destructive", children: "\u51FA\u9519\u4E86" }), error.message && _jsx("p", { className: "mt-1 text-xs text-muted-foreground", children: error.message }), _jsx("button", { onClick: this.reset, className: "mt-4 px-4 py-2 text-sm border rounded-md hover:bg-muted", children: "\u91CD\u8BD5" })] }));
     }
 }

package/dist/components/NotificationBell.js

@@ -40,8 +40,8 @@ export function NotificationBell({ onNavigate }) {
         document.addEventListener('mousedown', onClickOutside);
         return () => document.removeEventListener('mousedown', onClickOutside);
     }, []);
-    return (_jsxs("div", { ref: ref, className: "relative", children: [_jsxs("button", { onClick: () => setOpen(!open), className: "relative p-2 text-muted-foreground hover:text-foreground hover:bg-accent rounded-md\n          focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", "aria-label": "\u901A\u77E5", "aria-haspopup": "true", "aria-expanded": open, children: [_jsx("svg", { className: "w-5 h-5", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M15 17h5l-1.405-1.405A2.032 2.032 0 0118 14.158V11a6.002 6.002 0 00-4-5.659V5a2 2 0 10-4 0v.341C7.67 6.165 6 8.388 6 11v3.159c0 .538-.214 1.055-.595 1.436L4 17h5m6 0v1a3 3 0 11-6 0v-1m6 0H9" }) }), unread > 0 && (_jsx("span", { className: "absolute -top-0.5 -right-0.5 flex items-center justify-center min-w-[18px] h-[18px]\n            px-1 text-xs font-bold text-white bg-red-500 rounded-full", children: unread > 99 ? '99+' : unread }))] }), open && (_jsxs("div", { className: "absolute right-0 mt-2 w-80 bg-white rounded-lg shadow-lg border z-50", role: "dialog", "aria-label": "\u901A\u77E5\u5217\u8868", onKeyDown: (e) => { if (e.key === 'Escape')
-                    setOpen(false); }, children: [_jsxs("div", { className: "flex items-center justify-between px-4 py-3 border-b", children: [_jsx("span", { className: "text-sm font-semibold", children: "\u901A\u77E5" }), unread > 0 && (_jsx("button", { onClick: () => markAllReadM.mutate(), disabled: markAllReadM.isPending, className: "text-xs text-blue-600 hover:underline disabled:opacity-50\n                  focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded", children: "\u5168\u90E8\u5DF2\u8BFB" }))] }), _jsx("ul", { className: "max-h-80 overflow-y-auto list-none p-0 m-0", "data-slot": "notification-list", children: listQ.isPending ? (_jsx("li", { className: "py-8 text-center text-sm text-gray-400", "aria-live": "polite", children: "\u52A0\u8F7D\u4E2D\u2026" })) : notifications.length === 0 ? (_jsx("li", { className: "py-8 text-center text-sm text-gray-400", children: "\u6682\u65E0\u901A\u77E5" })) : notifications.map((n) => (_jsx("li", { className: "border-b last:border-0", children: _jsxs("button", { type: "button", onClick: () => { if (n.link)
-                                    onNavigate?.(n.link); markReadM.mutate(n.id); setOpen(false); }, className: cn('w-full text-left px-4 py-3 cursor-pointer hover:bg-gray-50 ' +
-                                    'focus-visible:outline-none focus-visible:bg-gray-50 focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring', !n.read_at && 'bg-blue-50/50'), children: [_jsxs("span", { className: "flex items-start justify-between gap-2", children: [_jsx("span", { className: "text-sm font-medium text-gray-900", children: n.title }), n.count > 1 && (_jsxs("span", { className: "text-xs bg-gray-100 text-gray-600 px-1.5 py-0.5 rounded-full shrink-0", children: ["\u00D7", n.count] }))] }), n.body && _jsx("span", { className: "block mt-0.5 text-xs text-gray-500 line-clamp-2", children: n.body }), _jsx("span", { className: "block mt-1 text-[10px] text-gray-400", children: formatDateTime(n.created_at) })] }) }, n.id))) })] }))] }));
+    return (_jsxs("div", { ref: ref, className: "relative", children: [_jsxs("button", { onClick: () => setOpen(!open), className: "relative p-2 text-muted-foreground hover:text-foreground hover:bg-accent rounded-md\n          focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", "aria-label": "\u901A\u77E5", "aria-haspopup": "true", "aria-expanded": open, children: [_jsx("svg", { className: "w-5 h-5", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M15 17h5l-1.405-1.405A2.032 2.032 0 0118 14.158V11a6.002 6.002 0 00-4-5.659V5a2 2 0 10-4 0v.341C7.67 6.165 6 8.388 6 11v3.159c0 .538-.214 1.055-.595 1.436L4 17h5m6 0v1a3 3 0 11-6 0v-1m6 0H9" }) }), unread > 0 && (_jsx("span", { className: "absolute -top-0.5 -right-0.5 flex items-center justify-center min-w-[18px] h-[18px]\n            px-1 text-xs font-bold text-white bg-destructive rounded-full", children: unread > 99 ? '99+' : unread }))] }), open && (_jsxs("div", { className: "absolute right-0 mt-2 w-80 bg-white rounded-lg shadow-lg border z-50", role: "dialog", "aria-label": "\u901A\u77E5\u5217\u8868", onKeyDown: (e) => { if (e.key === 'Escape')
+                    setOpen(false); }, children: [_jsxs("div", { className: "flex items-center justify-between px-4 py-3 border-b", children: [_jsx("span", { className: "text-sm font-semibold", children: "\u901A\u77E5" }), unread > 0 && (_jsx("button", { onClick: () => markAllReadM.mutate(), disabled: markAllReadM.isPending, className: "text-xs text-primary hover:underline disabled:opacity-50\n                  focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded", children: "\u5168\u90E8\u5DF2\u8BFB" }))] }), _jsx("ul", { className: "max-h-80 overflow-y-auto list-none p-0 m-0", "data-slot": "notification-list", children: listQ.isPending ? (_jsx("li", { className: "py-8 text-center text-sm text-muted-foreground", "aria-live": "polite", children: "\u52A0\u8F7D\u4E2D\u2026" })) : notifications.length === 0 ? (_jsx("li", { className: "py-8 text-center text-sm text-muted-foreground", children: "\u6682\u65E0\u901A\u77E5" })) : notifications.map((n) => (_jsx("li", { className: "border-b last:border-0", children: _jsxs("button", { type: "button", onClick: () => { if (n.link)
+                                    onNavigate?.(n.link); markReadM.mutate(n.id); setOpen(false); }, className: cn('w-full text-left px-4 py-3 cursor-pointer hover:bg-muted ' +
+                                    'focus-visible:outline-none focus-visible:bg-muted focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring', !n.read_at && 'bg-accent/50'), children: [_jsxs("span", { className: "flex items-start justify-between gap-2", children: [_jsx("span", { className: "text-sm font-medium text-foreground", children: n.title }), n.count > 1 && (_jsxs("span", { className: "text-xs bg-muted text-muted-foreground px-1.5 py-0.5 rounded-full shrink-0", children: ["\u00D7", n.count] }))] }), n.body && _jsx("span", { className: "block mt-0.5 text-xs text-muted-foreground line-clamp-2", children: n.body }), _jsx("span", { className: "block mt-1 text-[10px] text-muted-foreground", children: formatDateTime(n.created_at) })] }) }, n.id))) })] }))] }));
 }

package/dist/components/ReauthDialog.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Step-up（sudo mode）两段式协议的第二段（ADR 0011）：敏感操作被
+ * 403 E_REAUTH_REQUIRED 拒绝后，弹本对话框验证密码（POST
+ * /auth/confirm-password），成功后自动重试原请求。
+ *
+ * 用法：页面捕获 isApiError(err, 'E_REAUTH_REQUIRED') 时，把"重试动作"
+ * （通常是 mutation.mutateAsync 绑定原参数）交给 retry，打开对话框即可。
+ */
+export interface ReauthDialogProps {
+    open: boolean;
+    /** 被挑战的原动作；确认成功后重新执行一次。为 null 时对话框只确认不重试。 */
+    retry: (() => Promise<unknown>) | null;
+    onClose: () => void;
+}
+export declare function ReauthDialog({ open, retry, onClose }: ReauthDialogProps): import("react").JSX.Element;

package/dist/components/ReauthDialog.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { ShieldCheck } from 'lucide-react';
+import { useApi } from '@ploykit/hooks';
+import { isApiError } from '@ploykit/client';
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, } from './ui/dialog';
+import { Button } from './ui/button';
+import { Input } from './ui/input';
+import { toast } from './toast';
+export function ReauthDialog({ open, retry, onClose }) {
+    const api = useApi();
+    const [password, setPassword] = useState('');
+    const [error, setError] = useState('');
+    const [busy, setBusy] = useState(false);
+    const confirm = async () => {
+        if (!password || busy)
+            return;
+        setBusy(true);
+        setError('');
+        try {
+            await api.post('/auth/confirm-password', { password });
+            if (retry)
+                await retry();
+            toast.success('已验证，操作已重试');
+            setPassword('');
+            onClose();
+        }
+        catch (err) {
+            if (isApiError(err, 'E_UNAUTHENTICATED')) {
+                setError('密码不正确，请重试');
+                return;
+            }
+            toast.error('操作失败，请稍后重试');
+            onClose();
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    return (_jsx(Dialog, { open: open, onOpenChange: (o) => { if (!o && !busy)
+            onClose(); }, children: _jsxs(DialogContent, { className: "max-w-sm", children: [_jsxs(DialogHeader, { children: [_jsxs(DialogTitle, { className: "flex items-center gap-2", children: [_jsx(ShieldCheck, { className: "size-4" }), "\u9700\u8981\u9A8C\u8BC1\u5BC6\u7801"] }), _jsx(DialogDescription, { children: "\u8FD9\u662F\u654F\u611F\u64CD\u4F5C\uFF0C\u9700\u8981\u786E\u8BA4\u5BC6\u7801\u540E\u81EA\u52A8\u91CD\u8BD5\u3002\u5BC6\u7801\u786E\u8BA4\u5728\u4E00\u6BB5\u65F6\u95F4\u5185\u6709\u6548\u3002" })] }), _jsxs("form", { className: "space-y-1", onSubmit: (e) => { e.preventDefault(); void confirm(); }, children: [_jsx(Input, { type: "password", autoFocus: true, autoComplete: "current-password", "aria-label": "\u5F53\u524D\u5BC6\u7801", placeholder: "\u5F53\u524D\u5BC6\u7801", value: password, onChange: (e) => setPassword(e.target.value), disabled: busy }), error && _jsx("p", { className: "text-sm text-destructive", children: error }), _jsxs(DialogFooter, { className: "mt-4", children: [_jsx(Button, { type: "button", variant: "outline", onClick: onClose, disabled: busy, children: "\u53D6\u6D88" }), _jsx(Button, { type: "submit", disabled: !password || busy, children: busy ? '验证中…' : '验证并继续' })] })] })] }) }));
+}

package/dist/components/SecretModal.d.ts

@@ -1,16 +1,23 @@
+import { type ReactNode } from 'react';
 export declare function SecretModal({ open, onOpenChange, secretName, secretValue, title }: {
     open: boolean;
+    /** 关闭回调。契约：用户勾选"我已保存"之前，本组件不会把 false 传进来——ESC、遮罩点击、关闭按钮均被拦截，调用方无需自行兜底。 */
     onOpenChange: (open: boolean) => void;
+    /** 密钥名称，用于默认标题「{secretName} 创建成功」。 */
     secretName: string;
+    /** 仅显示一次的密钥明文。 */
     secretValue: string;
+    /** 可选标题，覆盖默认的「{secretName} 创建成功」——用于"重置/查看"等非创建成功场景。 */
     title?: string;
 }): import("react").JSX.Element;
 export declare function ImpactConfirmation({ open, onConfirm, onOpenChange, title, impacts, confirmText, danger }: {
     open: boolean;
+    /** 点击确认按钮后回调；回调返回后组件会立即请求关闭。 */
     onConfirm: () => void;
     onOpenChange: (open: boolean) => void;
     title: string;
-    impacts: string[];
+    /** 影响项列表。支持任意 ReactNode（可含链接/加粗等富文本）；key 按下标生成，注意项内容需自行保证可读。 */
+    impacts: ReactNode[];
     confirmText?: string;
     danger?: boolean;
 }): import("react").JSX.Element;

package/dist/components/SecretModal.js

@@ -37,9 +37,12 @@ export function SecretModal({ open, onOpenChange, secretName, secretValue, title
             setCopyFailed(false);
         }, 2000);
     };
-    return (_jsx(Dialog, { open: open, onOpenChange: (o) => confirmed && onOpenChange(o), children: _jsxs(DialogContent, { children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: title ?? `${secretName} 创建成功` }), _jsx(DialogDescription, { children: "\u6B64\u5BC6\u94A5\u53EA\u663E\u793A\u4E00\u6B21\uFF0C\u5173\u95ED\u540E\u65E0\u6CD5\u518D\u6B21\u67E5\u770B\u3002\u8BF7\u7ACB\u5373\u4FDD\u5B58\u5230\u5B89\u5168\u7684\u5730\u65B9\u3002" })] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("code", { className: "flex-1 px-3 py-2 bg-foreground/5 rounded font-mono text-sm break-all", children: secretValue }), _jsx(Button, { variant: "outline", size: "sm", onClick: copy, children: copied ? '已复制' : copyFailed ? '复制失败，请手动复制' : '复制' })] }), _jsxs("label", { className: "flex items-center gap-2 text-sm text-muted-foreground", children: [_jsx("input", { type: "checkbox", checked: confirmed, onChange: (e) => setConfirmed(e.target.checked), className: "rounded border-input" }), "\u6211\u5DF2\u5C06\u5BC6\u94A5\u4FDD\u5B58\u5230\u5B89\u5168\u7684\u5730\u65B9"] }), _jsx(DialogFooter, { children: _jsx(Button, { onClick: () => onOpenChange(false), disabled: !confirmed, children: confirmed ? '我已保存' : '请先确认已保存' }) })] }) }));
+    return (
+    // 契约（见 props JSDoc）：确认勾选前 onOpenChange 不会收到 false——
+    // ESC/遮罩/关闭按钮在此被统一拦截，防止密钥未保存即被关掉。
+    _jsx(Dialog, { open: open, onOpenChange: (o) => confirmed && onOpenChange(o), children: _jsxs(DialogContent, { children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: title ?? `${secretName} 创建成功` }), _jsx(DialogDescription, { children: "\u6B64\u5BC6\u94A5\u53EA\u663E\u793A\u4E00\u6B21\uFF0C\u5173\u95ED\u540E\u65E0\u6CD5\u518D\u6B21\u67E5\u770B\u3002\u8BF7\u7ACB\u5373\u4FDD\u5B58\u5230\u5B89\u5168\u7684\u5730\u65B9\u3002" })] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("code", { className: "flex-1 px-3 py-2 bg-foreground/5 rounded font-mono text-sm break-all", children: secretValue }), _jsx(Button, { variant: "outline", size: "sm", onClick: copy, children: copied ? '已复制' : copyFailed ? '复制失败，请手动复制' : '复制' })] }), _jsxs("label", { className: "flex items-center gap-2 text-sm text-muted-foreground", children: [_jsx("input", { type: "checkbox", checked: confirmed, onChange: (e) => setConfirmed(e.target.checked), className: "rounded border-input" }), "\u6211\u5DF2\u5C06\u5BC6\u94A5\u4FDD\u5B58\u5230\u5B89\u5168\u7684\u5730\u65B9"] }), _jsx(DialogFooter, { children: _jsx(Button, { onClick: () => onOpenChange(false), disabled: !confirmed, children: confirmed ? '我已保存' : '请先确认已保存' }) })] }) }));
 }
 export function ImpactConfirmation({ open, onConfirm, onOpenChange, title, impacts, confirmText, danger }) {
     const [checked, setChecked] = useState(false);
-    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: title }), _jsx(DialogDescription, { children: "\u6B64\u64CD\u4F5C\u5C06\u4EA7\u751F\u4EE5\u4E0B\u5F71\u54CD\uFF1A" })] }), _jsx("ul", { className: "space-y-1.5", children: impacts.map((impact) => (_jsxs("li", { className: "flex items-start gap-2 text-sm text-foreground", children: [_jsx("span", { className: "text-destructive mt-0.5", children: "\u2022" }), " ", impact] }, impact))) }), _jsxs("label", { className: "flex items-center gap-2 text-sm text-muted-foreground pt-2 border-t", children: [_jsx("input", { type: "checkbox", checked: checked, onChange: (e) => setChecked(e.target.checked), className: "rounded border-input" }), "\u6211\u7406\u89E3\u5E76\u63A5\u53D7\u4EE5\u4E0A\u5F71\u54CD"] }), _jsxs(DialogFooter, { children: [_jsx(Button, { variant: "outline", onClick: () => onOpenChange(false), children: "\u53D6\u6D88" }), _jsx(Button, { variant: danger ? 'destructive' : 'default', disabled: !checked, onClick: () => { onConfirm(); onOpenChange(false); }, children: confirmText ?? '确认执行' })] })] }) }));
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: title }), _jsx(DialogDescription, { children: "\u6B64\u64CD\u4F5C\u5C06\u4EA7\u751F\u4EE5\u4E0B\u5F71\u54CD\uFF1A" })] }), _jsx("ul", { className: "max-h-48 space-y-1.5 overflow-y-auto", children: impacts.map((impact, index) => (_jsxs("li", { className: "flex items-start gap-2 text-sm text-foreground", children: [_jsx("span", { className: "text-destructive mt-0.5", children: "\u2022" }), " ", impact] }, index))) }), _jsxs("label", { className: "flex items-center gap-2 text-sm text-muted-foreground pt-2 border-t", children: [_jsx("input", { type: "checkbox", checked: checked, onChange: (e) => setChecked(e.target.checked), className: "rounded border-input" }), "\u6211\u7406\u89E3\u5E76\u63A5\u53D7\u4EE5\u4E0A\u5F71\u54CD"] }), _jsxs(DialogFooter, { children: [_jsx(Button, { variant: "outline", onClick: () => onOpenChange(false), children: "\u53D6\u6D88" }), _jsx(Button, { variant: danger ? 'destructive' : 'default', disabled: !checked, onClick: () => { onConfirm(); onOpenChange(false); }, children: confirmText ?? '确认执行' })] })] }) }));
 }

package/dist/components/ui/{Badge.d.ts → badge.d.ts}

@@ -1,7 +1,7 @@
 import { useRender } from "@base-ui/react/use-render";
 import { type VariantProps } from "class-variance-authority";
 declare const badgeVariants: (props?: ({
-    variant?: "default" | "outline" | "secondary" | "ghost" | "destructive" | "link" | null | undefined;
+    variant?: "default" | "link" | "outline" | "secondary" | "ghost" | "destructive" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Badge({ className, variant, render, ...props }: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export { Badge, badgeVariants };

package/dist/components/ui/{Button.d.ts → button.d.ts}

@@ -1,7 +1,7 @@
 import { Button as ButtonPrimitive } from "@base-ui/react/button";
 import { type VariantProps } from "class-variance-authority";
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "outline" | "secondary" | "ghost" | "destructive" | "link" | null | undefined;
+    variant?: "default" | "link" | "outline" | "secondary" | "ghost" | "destructive" | null | undefined;
     size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Button({ className, variant, size, ...props }: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>): import("react").JSX.Element;

package/dist/components/ui/dialog.d.ts

@@ -5,7 +5,13 @@ declare function DialogTrigger({ ...props }: DialogPrimitive.Trigger.Props): Rea
 declare function DialogPortal({ ...props }: DialogPrimitive.Portal.Props): React.JSX.Element;
 declare function DialogClose({ ...props }: DialogPrimitive.Close.Props): React.JSX.Element;
 declare function DialogOverlay({ className, ...props }: DialogPrimitive.Backdrop.Props): React.JSX.Element;
-declare function DialogContent({ className, children, showCloseButton, ...props }: DialogPrimitive.Popup.Props & {
+/**
+ * DialogContent 内容面板。size 控制最大宽度档位（经 data-size 落到
+ * Tailwind data-[size=*] 变体）：sm=sm:max-w-sm（默认，历史视觉）/
+ * md=sm:max-w-lg / lg=sm:max-w-2xl / xl=sm:max-w-4xl。
+ */
+declare function DialogContent({ className, children, size, showCloseButton, ...props }: DialogPrimitive.Popup.Props & {
+    size?: "sm" | "md" | "lg" | "xl";
     showCloseButton?: boolean;
 }): React.JSX.Element;
 declare function DialogHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;

package/dist/components/ui/dialog.js

@@ -18,8 +18,13 @@ function DialogClose({ ...props }) {
 function DialogOverlay({ className, ...props }) {
     return (_jsx(DialogPrimitive.Backdrop, { "data-slot": "dialog-overlay", className: cn("fixed inset-0 isolate z-50 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0", className), ...props }));
 }
-function DialogContent({ className, children, showCloseButton = true, ...props }) {
-    return (_jsxs(DialogPortal, { children: [_jsx(DialogOverlay, {}), _jsxs(DialogPrimitive.Popup, { "data-slot": "dialog-content", className: cn("fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl bg-popover p-4 text-sm text-popover-foreground ring-1 ring-foreground/10 duration-100 outline-none sm:max-w-sm data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className), ...props, children: [children, showCloseButton && (_jsxs(DialogPrimitive.Close, { "data-slot": "dialog-close", render: _jsx(Button, { variant: "ghost", className: "absolute top-2 right-2", size: "icon-sm" }), children: [_jsx(XIcon, {}), _jsx("span", { className: "sr-only", children: "Close" })] }))] })] }));
+/**
+ * DialogContent 内容面板。size 控制最大宽度档位（经 data-size 落到
+ * Tailwind data-[size=*] 变体）：sm=sm:max-w-sm（默认，历史视觉）/
+ * md=sm:max-w-lg / lg=sm:max-w-2xl / xl=sm:max-w-4xl。
+ */
+function DialogContent({ className, children, size = "sm", showCloseButton = true, ...props }) {
+    return (_jsxs(DialogPortal, { children: [_jsx(DialogOverlay, {}), _jsxs(DialogPrimitive.Popup, { "data-slot": "dialog-content", "data-size": size, className: cn("fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl bg-popover p-4 text-sm text-popover-foreground ring-1 ring-foreground/10 duration-100 outline-none sm:max-w-sm data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 data-[size=md]:sm:max-w-lg data-[size=lg]:sm:max-w-2xl data-[size=xl]:sm:max-w-4xl", className), ...props, children: [children, showCloseButton && (_jsxs(DialogPrimitive.Close, { "data-slot": "dialog-close", render: _jsx(Button, { variant: "ghost", className: "absolute top-2 right-2", size: "icon-sm" }), children: [_jsx(XIcon, {}), _jsx("span", { className: "sr-only", children: "Close" })] }))] })] }));
 }
 function DialogHeader({ className, ...props }) {
     return (_jsx("div", { "data-slot": "dialog-header", className: cn("flex flex-col gap-2", className), ...props }));

package/dist/components/ui/select.d.ts

@@ -1,8 +1,27 @@
 import * as React from "react";
 import { Select as SelectPrimitive } from "@base-ui/react/select";
-declare const Select: typeof SelectPrimitive.Root;
+/**
+ * Select 根组件：base-ui Select Root 的 string 契约包装。
+ *
+ * 契约：onValueChange 永远收到 string——base-ui 原生回调的 value 可为 null
+ * （清空/取消选择时），包装层统一归一为空串（''），产品侧无需再写
+ * `v ?? ''` 卫语句。受控 value 仍允许 null、类型不收窄（与 base-ui 一致）；
+ * 其余 props（items/defaultValue/children 等）原样透传。
+ * 泛型保留（默认 string）：个别历史调用点用数值 item（如 days），此时
+ * 回调运行时收到的是原始数值——签名仍标为 string，属已知偏差。
+ * 多选（multiple）不在本契约内；如需多选请直接使用
+ * `@base-ui/react/select` 的 Root 原语。
+ */
+declare function Select<Value = string>({ onValueChange, ...props }: Omit<SelectPrimitive.Root.Props<Value, false>, "onValueChange" | "multiple"> & {
+    onValueChange?: (value: string) => void;
+}): React.JSX.Element;
 declare function SelectGroup({ className, ...props }: SelectPrimitive.Group.Props): React.JSX.Element;
 declare function SelectValue({ className, ...props }: SelectPrimitive.Value.Props): React.JSX.Element;
+/**
+ * SelectTrigger 触发按钮。size 控制高度档位（经 data-size 落到 Tailwind
+ * data-[size=*] 变体）：'default' = h-8（表单默认高度）；'sm' = h-7 +
+ * 更小圆角（工具栏/紧凑筛选条）。默认 'default'。
+ */
 declare function SelectTrigger({ className, size, children, ...props }: SelectPrimitive.Trigger.Props & {
     size?: "sm" | "default";
 }): React.JSX.Element;