@zhin.js/console-ui 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/LICENSE +21 -0
  3. package/README.md +88 -2
  4. package/dist/cn.d.ts +4 -0
  5. package/dist/cn.js +6 -0
  6. package/dist/components/InfoHint.d.ts +12 -0
  7. package/dist/components/InfoHint.js +12 -0
  8. package/dist/components/PageHeader.d.ts +11 -0
  9. package/dist/components/PageHeader.js +8 -0
  10. package/dist/components/PageShell.d.ts +11 -0
  11. package/dist/components/PageShell.js +8 -0
  12. package/dist/components/RefreshControl.d.ts +23 -0
  13. package/dist/components/RefreshControl.js +65 -0
  14. package/dist/components/StatCard.d.ts +27 -0
  15. package/dist/components/StatCard.js +27 -0
  16. package/dist/components/confirm-dialog-model.d.ts +9 -0
  17. package/dist/components/confirm-dialog-model.js +20 -0
  18. package/dist/components/confirm-dialog.d.ts +32 -0
  19. package/dist/components/confirm-dialog.js +71 -0
  20. package/dist/components/empty-state.d.ts +15 -0
  21. package/dist/components/empty-state.js +15 -0
  22. package/dist/components/error-alert.d.ts +15 -0
  23. package/dist/components/error-alert.js +22 -0
  24. package/dist/components/page-chrome.d.ts +41 -0
  25. package/dist/components/page-chrome.js +65 -0
  26. package/dist/components/refresh-control-model.d.ts +9 -0
  27. package/dist/components/refresh-control-model.js +26 -0
  28. package/dist/components/ui/accordion.d.ts +7 -0
  29. package/dist/components/ui/accordion.js +14 -0
  30. package/dist/components/ui/alert.d.ts +8 -0
  31. package/dist/components/ui/alert.js +24 -0
  32. package/dist/components/ui/badge.d.ts +9 -0
  33. package/dist/components/ui/badge.js +29 -0
  34. package/dist/components/ui/button.d.ts +11 -0
  35. package/dist/components/ui/button.js +37 -0
  36. package/dist/components/ui/card.d.ts +11 -0
  37. package/dist/components/ui/card.js +16 -0
  38. package/dist/components/ui/checkbox.d.ts +4 -0
  39. package/dist/components/ui/checkbox.js +9 -0
  40. package/dist/components/ui/dialog.d.ts +24 -0
  41. package/dist/components/ui/dialog.js +26 -0
  42. package/dist/components/ui/dropdown-menu.d.ts +19 -0
  43. package/dist/components/ui/dropdown-menu.js +25 -0
  44. package/dist/components/ui/input.d.ts +3 -0
  45. package/dist/components/ui/input.js +8 -0
  46. package/dist/components/ui/list-item-button.d.ts +10 -0
  47. package/dist/components/ui/list-item-button.js +6 -0
  48. package/dist/components/ui/popover.d.ts +6 -0
  49. package/dist/components/ui/popover.js +9 -0
  50. package/dist/components/ui/radio-group.d.ts +5 -0
  51. package/dist/components/ui/radio-group.js +10 -0
  52. package/dist/components/ui/scroll-area.d.ts +5 -0
  53. package/dist/components/ui/scroll-area.js +13 -0
  54. package/dist/components/ui/searchable-select-model.d.ts +29 -0
  55. package/dist/components/ui/searchable-select-model.js +38 -0
  56. package/dist/components/ui/searchable-select.d.ts +23 -0
  57. package/dist/components/ui/searchable-select.js +84 -0
  58. package/dist/components/ui/select.d.ts +23 -0
  59. package/dist/components/ui/select.js +37 -0
  60. package/dist/components/ui/separator.d.ts +4 -0
  61. package/dist/components/ui/separator.js +11 -0
  62. package/dist/components/ui/sheet.d.ts +27 -0
  63. package/dist/components/ui/sheet.js +26 -0
  64. package/dist/components/ui/skeleton.d.ts +3 -0
  65. package/dist/components/ui/skeleton.js +6 -0
  66. package/dist/components/ui/switch.d.ts +4 -0
  67. package/dist/components/ui/switch.js +8 -0
  68. package/dist/components/ui/table.d.ts +16 -0
  69. package/dist/components/ui/table.js +16 -0
  70. package/dist/components/ui/tabs.d.ts +7 -0
  71. package/dist/components/ui/tabs.js +13 -0
  72. package/dist/components/ui/textarea.d.ts +3 -0
  73. package/dist/components/ui/textarea.js +8 -0
  74. package/dist/components/ui/tooltip.d.ts +7 -0
  75. package/dist/components/ui/tooltip.js +11 -0
  76. package/dist/exports.json +138 -0
  77. package/dist/i18n/index.d.ts +27 -0
  78. package/dist/i18n/index.js +33 -0
  79. package/dist/i18n/messages.d.ts +36 -0
  80. package/dist/i18n/messages.js +72 -0
  81. package/dist/index.d.ts +44 -0
  82. package/dist/index.js +44 -0
  83. package/dist/shared-module.d.ts +28 -0
  84. package/dist/shared-module.js +24 -0
  85. package/dist/styles.css +2316 -0
  86. package/dist/tokens.css +341 -0
  87. package/dist/version.d.ts +6 -0
  88. package/dist/version.js +2 -0
  89. package/package.json +73 -3
package/CHANGELOG.md ADDED
@@ -0,0 +1,9 @@
1
+ # @zhin.js/console-ui
2
+
3
+ ## 1.0.0
4
+
5
+ ### Patch Changes
6
+
7
+ - a257dae: 新增 `@zhin.js/console-ui`(ADR 0063 P1a,首发 1.0.0:package.json 记 1.0.0-0,由本 patch 升到 1.0.0):Console 与插件页面共用的组件库。从 Console 迁入 `components/ui/*`(含 `SearchableSelectField`)、`PageShell`、`PageHeader`、`ConfirmDialog` / `useConfirm`、`StatCard`、`EmptyState`、`ErrorAlert`、`InfoHint`,属性与 Console 原组件一致、外观不变;新增 `RefreshControl`(「更新于 hh:mm:ss」+ 手动 / 5s / 15s / 30s 自动刷新 + 刷新按钮)、`usePageChrome({ actions, refresh })` 及外壳侧的 `PageChromeProvider` / `PageChromeActions`、`Button` 的 `variant="destructive-outline"`、语言 Provider `ConsoleUiI18nProvider`(内置 zh-CN / en,宿主可注入语言与覆盖文案)。发布产物带编译好的 `@zhin.js/console-ui/styles.css`(令牌 + 组件样式,使用方不需要 Tailwind)和只含令牌的 `tokens.css`。
8
+
9
+ `@zhin.js/client`:`cn()` 移入 `@zhin.js/console-ui`,`@zhin.js/client` 改为再导出,原有导入不变;`--zk-*` 变量标注为指向 `@zhin.js/console-ui` 令牌的弃用别名(取值不变)。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 凉菜
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,89 @@
1
- # Temporary Holding Version
1
+ # @zhin.js/console-ui
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Zhin Console 与插件页面共用的组件库([ADR 0063](../../../docs/adr/0063-console-plugin-ui-unification.md)):基于 Radix 的 React 组件、页面外壳、刷新控件,以及一份设计令牌。样式随包发布、已经编译好,使用方不需要 Tailwind。
4
+
5
+ > 状态:P1a(从 Console 迁入,外观不变)。插件页面在 P2 之前仍沿用现有写法(声明式蓝图或 `@zhin.js/client/ui`),见 [Console 页面与布局](../../../docs/authoring/console-pages.md)。
6
+
7
+ 只给浏览器用:本包与 `radix-ui`、`class-variance-authority`、`clsx`、`tailwind-merge`、`lucide-react` 不在 `zhin.js` 的依赖树里。React 是 peerDependency。
8
+
9
+ ## 引入
10
+
11
+ ```ts
12
+ import '@zhin.js/console-ui/styles.css'; // 令牌 + 组件样式(含 Tailwind preflight),只需引入一次
13
+ import { Button, PageShell, PageHeader, RefreshControl } from '@zhin.js/console-ui';
14
+ ```
15
+
16
+ - `@zhin.js/console-ui/styles.css`:完整样式,自带 preflight、主题、组件用到的 Tailwind 工具类、令牌和 `console-*` 组件类。和自己的 Tailwind 一起用时,先引入它,再引入自己的样式,同一层(`@layer base` 等)里后者优先。
17
+ - `@zhin.js/console-ui/tokens.css`:只有令牌(颜色、圆角、控件高度、间距、阴影、`--console-content-max`)。深色由祖先上的 `.dark` 切换,配色由 `<html data-palette>` 切换。
18
+ - `@zhin.js/console-ui/cn`:只有 `cn()`(`@zhin.js/client` 由此再导出 `cn`)。
19
+
20
+ 插件的手写 `.tsx` 页面把本包声明为 `peerDependencies`(例如 `"@zhin.js/console-ui": "^1.0.0"`):`@zhin.js/pagemanager` 不会把它打进插件,页面拿到的是 Console 已加载的那份组件和 CSS;版本不兼容时会明确报错,见下文「共享模块版本」。
21
+
22
+ ## 导出
23
+
24
+ | 类别 | 导出 |
25
+ | --- | --- |
26
+ | 基础组件(`components/ui/*`) | `Accordion*`、`Alert`/`AlertTitle`/`AlertDescription`、`Badge`/`badgeVariants`、`Button`/`buttonVariants`、`Card*`、`Checkbox`、`Dialog*`、`DropdownMenu*`、`Input`、`ListItemButton`、`Popover`/`PopoverTrigger`/`PopoverAnchor`/`PopoverContent`、`RadioGroup`/`RadioGroupItem`、`ScrollArea`/`ScrollBar`、`SearchableSelectField`、`Select*`/`SelectField`、`Separator`、`Sheet*`、`Skeleton`、`Switch`、`Table*`、`Tabs*`、`Textarea`、`Tooltip*` |
27
+ | 页面与通用组件 | `PageShell`、`PageHeader`、`ConfirmDialog`/`useConfirm`、`StatCard`/`StatGrid`/`MiniRingGauge`、`EmptyState`、`ErrorAlert`、`InfoHint`、`RefreshControl` |
28
+ | 页面外壳接口 | `usePageChrome({ actions, refresh })`、`PageChromeProvider`、`createPageChromeStore`、`usePageChromeState`、`PageChromeActions` |
29
+ | 语言 | `ConsoleUiI18nProvider`、`useConsoleUiI18n`、`createConsoleUiI18n`、`ConsoleUiText`、`CONSOLE_UI_MESSAGES`、`CONSOLE_UI_LOCALES` |
30
+ | 纯函数 | `cn`、`groupSelectOptions`、`navigableValues`、`optionMatches`、`optionSearchText`、`canSubmitConfirm`、`confirmTextMatches`、`confirmErrorMessage`、`formatRefreshTime`、`refreshIntervalOptions`、`DEFAULT_REFRESH_INTERVALS` |
31
+ | 共享模块 | `CONSOLE_UI_VERSION`、`CONSOLE_UI_MODULE_ID`、`registerConsoleUiSharedModule`、`CONSOLE_SHARED_MODULE_VERSIONS_KEY`、`CONSOLE_SHARED_MODULE_ISSUES_KEY`、`CONSOLE_SHARED_MODULE_ISSUE_EVENT` |
32
+
33
+ 组件的属性与 Console 原来的同名组件一致。新增:`Button` 的 `variant="destructive-outline"`(页面上的危险操作入口,等价于 `variant="outline"` 加 `text-destructive`;实心 `destructive` 只用于确认对话框里的确认按钮)。
34
+
35
+ ## 语言
36
+
37
+ 组件不读任何宿主的 i18n。没有 Provider 时使用 zh-CN 默认文案;宿主注入当前语言和可选的覆盖文案:
38
+
39
+ ```tsx
40
+ import { ConsoleUiI18nProvider } from '@zhin.js/console-ui';
41
+
42
+ <ConsoleUiI18nProvider locale={locale} messages={{ 'error.retry': '再试一次' }}>
43
+ {children}
44
+ </ConsoleUiI18nProvider>
45
+ ```
46
+
47
+ `locale` 接受任意 BCP 47 标签(`zh*` → zh-CN,`en*` → en,其余 → zh-CN);`messages` 的键见 `CONSOLE_UI_MESSAGES`。
48
+
49
+ ## 刷新控件与页头操作
50
+
51
+ `RefreshControl`:「更新于 hh:mm:ss」+ 自动刷新间隔(Radix 下拉:手动 / 5s / 15s / 30s)+ 刷新按钮。`onRefresh` 返回 Promise 时,按钮在完成前保持忙碌;自动刷新在标签页隐藏或上一次刷新未结束时跳过。
52
+
53
+ 手写页面不画自己的页头,而是把操作交给外壳:
54
+
55
+ ```tsx
56
+ import { Button, usePageChrome } from '@zhin.js/console-ui';
57
+
58
+ export default function Feeds() {
59
+ const hosted = usePageChrome({
60
+ actions: <Button variant="destructive-outline">移除订阅</Button>,
61
+ refresh: { onRefresh: reload, updatedAt },
62
+ });
63
+ // hosted === false:外层没有外壳(例如旧版 Console),页面可以自己画这些控件
64
+ return <FeedTable />;
65
+ }
66
+ ```
67
+
68
+ 外壳为每个页面槽创建一个 `createPageChromeStore()`,用 `<PageChromeProvider store>` 包住页面,并在 `PageHeader` 的 `actions` 里放 `<PageChromeActions store />`。P1a 只提供接口;Console 外壳与插件页面的接入在 P2。
69
+
70
+ ## 共享模块版本
71
+
72
+ Console 入口在加载插件入口前登记本包:
73
+
74
+ ```ts
75
+ import * as ConsoleUi from '@zhin.js/console-ui';
76
+ ConsoleUi.registerConsoleUiSharedModule(ConsoleUi, sharedModules); // sharedModules: globalThis.__ZHIN_CONSOLE_SHARED_MODULES__
77
+ ```
78
+
79
+ 它把模块放进 `sharedModules`,并把 `CONSOLE_UI_VERSION` 写进 `globalThis.__ZHIN_CONSOLE_SHARED_MODULE_VERSIONS__`(`Map<模块名, 版本>`)。`@zhin.js/pagemanager` 生成的代理模块拿它和插件 `peerDependencies` 中的范围比对:主版本不兼容时页面导入失败并给出原因;版本偏低时在控制台告警,并把记录追加到 `globalThis.__ZHIN_CONSOLE_SHARED_MODULE_ISSUES__`、派发 `zhin:console-shared-module-issue` 事件(`detail` 为 `ConsoleSharedModuleIssue`),Console 可以据此在页面上提示;插件用到而 Console 这份没有的具名导出会按名字报出,调用时抛错。
80
+
81
+ ## 开发
82
+
83
+ ```bash
84
+ pnpm --filter @zhin.js/console-ui build # tsc + Tailwind 编译 dist/styles.css、dist/tokens.css、dist/exports.json
85
+ pnpm vitest run packages/console/ui # 单元测试
86
+ pnpm --filter @zhin.js/console-ui test:visual # Playwright 视觉回归(亮 / 暗,先 build)
87
+ ```
88
+
89
+ 视觉回归打开 `visual/demo.tsx` 的组件示例页(只引入 `dist/styles.css`),对页面外壳、按钮、输入框、下拉框、表格和对话框截图比对。基线依赖本机字体;本机已装其它版本的 Chromium 时,用 `PLAYWRIGHT_CHROMIUM_EXECUTABLE` 指过去。改了外观要用 `--update-snapshots` 更新基线并逐张评审。
package/dist/cn.d.ts ADDED
@@ -0,0 +1,4 @@
1
+ import { type ClassValue } from 'clsx';
2
+ export type { ClassValue } from 'clsx';
3
+ /** Joins class names and resolves Tailwind conflicts (later classes win). */
4
+ export declare function cn(...inputs: ClassValue[]): string;
package/dist/cn.js ADDED
@@ -0,0 +1,6 @@
1
+ import { clsx } from 'clsx';
2
+ import { twMerge } from 'tailwind-merge';
3
+ /** Joins class names and resolves Tailwind conflicts (later classes win). */
4
+ export function cn(...inputs) {
5
+ return twMerge(clsx(inputs));
6
+ }
@@ -0,0 +1,12 @@
1
+ import type { ReactNode } from 'react';
2
+ /**
3
+ * An ⓘ label whose explanation opens on click, Enter or Space: for statements about how a number
4
+ * was counted, which readers need once and not on every visit. `label` stays visible; `children`
5
+ * is the explanation.
6
+ */
7
+ export declare function InfoHint({ label, children, className, tone }: {
8
+ label: ReactNode;
9
+ children: ReactNode;
10
+ className?: string;
11
+ tone?: 'warning';
12
+ }): import("react").JSX.Element;
@@ -0,0 +1,12 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { Info } from 'lucide-react';
3
+ import { cn } from '../cn.js';
4
+ import { Popover, PopoverContent, PopoverTrigger } from './ui/popover.js';
5
+ /**
6
+ * An ⓘ label whose explanation opens on click, Enter or Space: for statements about how a number
7
+ * was counted, which readers need once and not on every visit. `label` stays visible; `children`
8
+ * is the explanation.
9
+ */
10
+ export function InfoHint({ label, children, className, tone }) {
11
+ return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { type: "button", className: cn('console-info-hint', tone === 'warning' && 'is-warning', className), children: [_jsx("span", { children: label }), _jsx(Info, { "aria-hidden": "true" })] }) }), _jsx(PopoverContent, { className: "console-info-hint-panel", align: "start", children: children })] }));
12
+ }
@@ -0,0 +1,11 @@
1
+ import type { ReactNode } from 'react';
2
+ export interface PageHeaderProps {
3
+ title: string;
4
+ description?: string;
5
+ actions?: ReactNode;
6
+ className?: string;
7
+ }
8
+ /**
9
+ * 统一页面标题区(与各业务页配合使用)
10
+ */
11
+ export declare function PageHeader({ title, description, actions, className }: PageHeaderProps): import("react").JSX.Element;
@@ -0,0 +1,8 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { cn } from '../cn.js';
3
+ /**
4
+ * 统一页面标题区(与各业务页配合使用)
5
+ */
6
+ export function PageHeader({ title, description, actions, className }) {
7
+ return (_jsxs("header", { className: cn('console-page-header', className), children: [_jsxs("div", { className: "min-w-0 space-y-1", children: [_jsx("h1", { className: "console-page-title", children: title }), description ? (_jsx("p", { className: "console-page-description", children: description })) : null] }), actions ? _jsx("div", { className: "console-page-header-actions", children: actions }) : null] }));
8
+ }
@@ -0,0 +1,11 @@
1
+ import type { ReactNode } from 'react';
2
+ export interface PageShellProps {
3
+ children: ReactNode;
4
+ /** 默认 vertical stack;grid 用于卡片栅格页 */
5
+ layout?: 'stack' | 'grid';
6
+ className?: string;
7
+ }
8
+ /**
9
+ * 页面内容区统一外壳:区块间距、纵向节奏与 dashboard main 内边距配合使用。
10
+ */
11
+ export declare function PageShell({ children, layout, className }: PageShellProps): import("react").JSX.Element;
@@ -0,0 +1,8 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { cn } from '../cn.js';
3
+ /**
4
+ * 页面内容区统一外壳:区块间距、纵向节奏与 dashboard main 内边距配合使用。
5
+ */
6
+ export function PageShell({ children, layout = 'stack', className }) {
7
+ return (_jsx("div", { className: cn(layout === 'stack' ? 'console-page' : 'console-page-grid', className), children: children }));
8
+ }
@@ -0,0 +1,23 @@
1
+ export interface RefreshControlProps {
2
+ /** Runs on the refresh button and on every auto-refresh tick; a returned promise keeps the control busy until it settles. */
3
+ onRefresh: () => void | Promise<unknown>;
4
+ /** Time of the last successful load, shown as 「更新于 hh:mm:ss」. */
5
+ updatedAt?: Date | number | string | null;
6
+ /** Auto-refresh interval in ms (0 = manual). Controlled when set. */
7
+ intervalMs?: number;
8
+ /** Initial interval when uncontrolled; defaults to 0 (manual). */
9
+ defaultIntervalMs?: number;
10
+ onIntervalChange?: (intervalMs: number) => void;
11
+ /** Offered intervals in ms; defaults to manual / 5s / 15s / 30s. */
12
+ intervals?: readonly number[];
13
+ /** Busy state owned by the caller (e.g. a data hook); merged with the control's own in-flight state. */
14
+ refreshing?: boolean;
15
+ disabled?: boolean;
16
+ className?: string;
17
+ }
18
+ /**
19
+ * The one refresh control for Console and plugin pages (ADR 0063 D5): 「更新于 hh:mm:ss」, an
20
+ * auto-refresh interval (Radix select: manual / 5s / 15s / 30s) and a refresh button.
21
+ * Auto-refresh skips ticks while the tab is hidden or a refresh is still running.
22
+ */
23
+ export declare function RefreshControl({ onRefresh, updatedAt, intervalMs, defaultIntervalMs, onIntervalChange, intervals, refreshing, disabled, className, }: RefreshControlProps): import("react").JSX.Element;
@@ -0,0 +1,65 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { useCallback, useEffect, useRef, useState } from 'react';
3
+ import { RefreshCw } from 'lucide-react';
4
+ import { cn } from '../cn.js';
5
+ import { useConsoleUiI18n } from '../i18n/index.js';
6
+ import { Button } from './ui/button.js';
7
+ import { SelectField } from './ui/select.js';
8
+ import { DEFAULT_REFRESH_INTERVALS, formatRefreshTime, intervalSeconds, refreshIntervalOptions, } from './refresh-control-model.js';
9
+ /**
10
+ * The one refresh control for Console and plugin pages (ADR 0063 D5): 「更新于 hh:mm:ss」, an
11
+ * auto-refresh interval (Radix select: manual / 5s / 15s / 30s) and a refresh button.
12
+ * Auto-refresh skips ticks while the tab is hidden or a refresh is still running.
13
+ */
14
+ export function RefreshControl({ onRefresh, updatedAt, intervalMs, defaultIntervalMs = 0, onIntervalChange, intervals = DEFAULT_REFRESH_INTERVALS, refreshing, disabled, className, }) {
15
+ const i18n = useConsoleUiI18n();
16
+ const [ownInterval, setOwnInterval] = useState(defaultIntervalMs);
17
+ const [inFlight, setInFlight] = useState(false);
18
+ const inFlightRef = useRef(false);
19
+ const onRefreshRef = useRef(onRefresh);
20
+ onRefreshRef.current = onRefresh;
21
+ const interval = intervalMs ?? ownInterval;
22
+ const busy = Boolean(refreshing) || inFlight;
23
+ const run = useCallback(() => {
24
+ if (inFlightRef.current)
25
+ return;
26
+ let result;
27
+ try {
28
+ result = onRefreshRef.current();
29
+ }
30
+ catch {
31
+ return;
32
+ }
33
+ if (result && typeof result.then === 'function') {
34
+ inFlightRef.current = true;
35
+ setInFlight(true);
36
+ void result.catch(() => undefined).finally(() => {
37
+ inFlightRef.current = false;
38
+ setInFlight(false);
39
+ });
40
+ }
41
+ }, []);
42
+ useEffect(() => {
43
+ if (!(interval > 0) || disabled)
44
+ return;
45
+ const timer = setInterval(() => {
46
+ if (typeof document !== 'undefined' && document.visibilityState === 'hidden')
47
+ return;
48
+ if (refreshing)
49
+ return;
50
+ run();
51
+ }, interval);
52
+ return () => clearInterval(timer);
53
+ }, [interval, disabled, refreshing, run]);
54
+ const options = refreshIntervalOptions(interval, intervals).map(value => ({
55
+ value: String(value),
56
+ label: value === 0 ? i18n.t('refresh.manual') : i18n.t('refresh.auto', [intervalSeconds(value)]),
57
+ }));
58
+ const time = formatRefreshTime(updatedAt);
59
+ return (_jsxs("div", { className: cn('console-refresh-control flex flex-wrap items-center gap-2', className), children: [_jsx("span", { className: "console-refresh-control-time text-[length:var(--console-text-label)] text-muted-foreground tabular-nums", "aria-live": "polite", children: time ? i18n.t('refresh.updatedAt', [time]) : i18n.t('refresh.notYet') }), _jsx(SelectField, { "aria-label": i18n.t('refresh.interval'), className: "h-[var(--console-control-height-sm)] w-auto min-w-[7.5rem] text-[length:var(--console-text-body-sm)]", options: options, value: String(interval), disabled: disabled, onValueChange: next => {
60
+ const value = Number(next);
61
+ if (intervalMs === undefined)
62
+ setOwnInterval(value);
63
+ onIntervalChange?.(value);
64
+ } }), _jsxs(Button, { variant: "outline", size: "sm", onClick: run, disabled: disabled || busy, "aria-busy": busy || undefined, children: [_jsx(RefreshCw, { "aria-hidden": "true", className: cn(busy && 'animate-spin') }), busy ? i18n.t('refresh.refreshing') : i18n.t('refresh.refresh')] })] }));
65
+ }
@@ -0,0 +1,27 @@
1
+ import type { ReactNode } from 'react';
2
+ import type { LucideIcon } from 'lucide-react';
3
+ export interface StatCardProps {
4
+ icon: LucideIcon;
5
+ label: string;
6
+ value: ReactNode;
7
+ sub?: ReactNode;
8
+ tone?: 'danger' | 'warning';
9
+ /** 数值右侧的附加内容,如环形进度 */
10
+ aside?: ReactNode;
11
+ /** 提供时整张卡片可点击(跳转或筛选) */
12
+ onOpen?: () => void;
13
+ /** 作为筛选器使用时的选中状态 */
14
+ pressed?: boolean;
15
+ }
16
+ /**
17
+ * 指标卡:图标 + 标签、大号数值、说明文字。总览页与列表页共用。
18
+ */
19
+ export declare function StatCard({ icon: Icon, label, value, sub, tone, aside, onOpen, pressed }: StatCardProps): import("react").JSX.Element;
20
+ export declare function StatGrid({ children, label }: {
21
+ children: ReactNode;
22
+ label: string;
23
+ }): import("react").JSX.Element;
24
+ export declare function MiniRingGauge({ percent, tone }: {
25
+ percent: number;
26
+ tone?: 'primary' | 'success' | 'warning';
27
+ }): import("react").JSX.Element;
@@ -0,0 +1,27 @@
1
+ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
2
+ import { cn } from '../cn.js';
3
+ /**
4
+ * 指标卡:图标 + 标签、大号数值、说明文字。总览页与列表页共用。
5
+ */
6
+ export function StatCard({ icon: Icon, label, value, sub, tone, aside, onOpen, pressed }) {
7
+ const className = cn('console-stat-card', tone && `is-${tone}`, onOpen && 'is-link', pressed && 'is-pressed');
8
+ const content = (_jsxs(_Fragment, { children: [_jsxs("span", { className: "console-stat-label", children: [_jsx(Icon, { "aria-hidden": "true" }), label] }), _jsxs("span", { className: "console-stat-value-row", children: [_jsx("strong", { className: "console-stat-value", children: value }), aside] }), sub !== undefined ? _jsx("span", { className: "console-stat-sub", children: sub }) : null] }));
9
+ if (!onOpen)
10
+ return _jsx("div", { className: className, children: content });
11
+ return (_jsx("button", { type: "button", className: className, onClick: onOpen, "aria-pressed": pressed, children: content }));
12
+ }
13
+ export function StatGrid({ children, label }) {
14
+ return _jsx("section", { className: "console-stat-grid", "aria-label": label, children: children });
15
+ }
16
+ export function MiniRingGauge({ percent, tone = 'primary' }) {
17
+ const clamped = Math.max(0, Math.min(100, percent));
18
+ const r = 16;
19
+ const c = 2 * Math.PI * r;
20
+ const offset = c - (clamped / 100) * c;
21
+ const stroke = tone === 'success'
22
+ ? 'hsl(var(--success))'
23
+ : tone === 'warning'
24
+ ? 'hsl(var(--warning))'
25
+ : 'hsl(var(--primary))';
26
+ return (_jsxs("span", { className: "console-ring-gauge", "aria-hidden": "true", children: [_jsxs("svg", { viewBox: "0 0 40 40", children: [_jsx("circle", { cx: "20", cy: "20", r: r, fill: "none", stroke: "currentColor", strokeOpacity: 0.12, strokeWidth: "3.5" }), _jsx("circle", { cx: "20", cy: "20", r: r, fill: "none", stroke: stroke, strokeWidth: "3.5", strokeLinecap: "round", strokeDasharray: c, strokeDashoffset: offset })] }), _jsxs("span", { className: "console-ring-gauge-label", children: [clamped, "%"] })] }));
27
+ }
@@ -0,0 +1,9 @@
1
+ /** Message shown inside ConfirmDialog when onConfirm rejects; null means "use the generic fallback". */
2
+ export declare function confirmErrorMessage(error: unknown): string | null;
3
+ /** Typed confirmation for irreversible actions: exact, case-sensitive match; surrounding whitespace is ignored. */
4
+ export declare function confirmTextMatches(typed: string, expected: string | null | undefined): boolean;
5
+ export declare function canSubmitConfirm(state: {
6
+ loading: boolean;
7
+ typed: string;
8
+ confirmText?: string | null;
9
+ }): boolean;
@@ -0,0 +1,20 @@
1
+ /** Message shown inside ConfirmDialog when onConfirm rejects; null means "use the generic fallback". */
2
+ export function confirmErrorMessage(error) {
3
+ if (error instanceof Error)
4
+ return error.message.trim() || null;
5
+ if (typeof error === 'string')
6
+ return error.trim() || null;
7
+ if (error && typeof error === 'object' && typeof error.message === 'string') {
8
+ return error.message.trim() || null;
9
+ }
10
+ return null;
11
+ }
12
+ /** Typed confirmation for irreversible actions: exact, case-sensitive match; surrounding whitespace is ignored. */
13
+ export function confirmTextMatches(typed, expected) {
14
+ if (expected == null || expected === '')
15
+ return true;
16
+ return typeof typed === 'string' && typed.trim() === expected;
17
+ }
18
+ export function canSubmitConfirm(state) {
19
+ return !state.loading && confirmTextMatches(state.typed, state.confirmText);
20
+ }
@@ -0,0 +1,32 @@
1
+ import { type ReactNode } from 'react';
2
+ export interface ConfirmDialogProps {
3
+ open: boolean;
4
+ onOpenChange: (open: boolean) => void;
5
+ title: string;
6
+ description?: string;
7
+ children?: ReactNode;
8
+ confirmLabel?: string;
9
+ cancelLabel?: string;
10
+ variant?: 'default' | 'destructive';
11
+ /**
12
+ * Irreversible actions: the user must type this exact text (e.g. a table name)
13
+ * before the confirm button is enabled.
14
+ */
15
+ confirmText?: string;
16
+ /**
17
+ * May throw or reject: the dialog then stays open, shows the error (role="alert")
18
+ * and lets the user retry or cancel. Resolve to close the dialog.
19
+ */
20
+ onConfirm: () => void | Promise<void>;
21
+ }
22
+ export declare function ConfirmDialog({ open, onOpenChange, title, description, children, confirmLabel, cancelLabel, variant, confirmText, onConfirm, }: ConfirmDialogProps): import("react").JSX.Element;
23
+ /**
24
+ * Hook for imperative confirm dialogs.
25
+ * Usage:
26
+ * const confirm = useConfirm()
27
+ * if (await confirm({ title: '确定删除?', variant: 'destructive' })) { ... }
28
+ */
29
+ export declare function useConfirm(): {
30
+ confirm: (opts: Omit<ConfirmDialogProps, "open" | "onOpenChange" | "onConfirm">) => Promise<boolean>;
31
+ ConfirmDialog: import("react").JSX.Element | null;
32
+ };
@@ -0,0 +1,71 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { useConsoleUiI18n } from '../i18n/index.js';
3
+ import { useState, useCallback, useEffect, useId } from 'react';
4
+ import { AlertTriangle, Info } from 'lucide-react';
5
+ import { cn } from '../cn.js';
6
+ import { Dialog, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription, DialogClose, } from './ui/dialog.js';
7
+ import { Button } from './ui/button.js';
8
+ import { Input } from './ui/input.js';
9
+ import { canSubmitConfirm, confirmErrorMessage } from './confirm-dialog-model.js';
10
+ export function ConfirmDialog({ open, onOpenChange, title, description, children, confirmLabel, cancelLabel, variant = 'default', confirmText, onConfirm, }) {
11
+ const i18n = useConsoleUiI18n();
12
+ const inputId = useId();
13
+ const [loading, setLoading] = useState(false);
14
+ const [error, setError] = useState(null);
15
+ const [typed, setTyped] = useState('');
16
+ const canSubmit = canSubmitConfirm({ loading, typed, confirmText });
17
+ // A closed dialog must not carry a stale error or typed name into its next opening.
18
+ useEffect(() => {
19
+ if (!open) {
20
+ setError(null);
21
+ setTyped('');
22
+ }
23
+ }, [open]);
24
+ const handleConfirm = useCallback(async () => {
25
+ if (!canSubmit)
26
+ return;
27
+ setLoading(true);
28
+ setError(null);
29
+ try {
30
+ await onConfirm();
31
+ onOpenChange(false);
32
+ }
33
+ catch (caught) {
34
+ setError(confirmErrorMessage(caught) ?? i18n.t("confirm.failed"));
35
+ }
36
+ finally {
37
+ setLoading(false);
38
+ }
39
+ }, [canSubmit, onConfirm, onOpenChange, i18n]);
40
+ const Icon = variant === 'destructive' ? AlertTriangle : Info;
41
+ return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { className: "max-w-md", children: [_jsx(DialogHeader, { children: _jsxs("div", { className: "flex items-start gap-3", children: [_jsx("span", { className: cn('console-confirm-icon', variant === 'destructive' && 'is-destructive'), "aria-hidden": "true", children: _jsx(Icon, { className: "h-5 w-5" }) }), _jsxs("div", { className: "min-w-0 flex-1 space-y-1", children: [_jsx(DialogTitle, { children: title }), description && _jsx(DialogDescription, { children: description })] })] }) }), children, confirmText != null && confirmText !== '' && (_jsxs("div", { className: "space-y-1.5", children: [_jsx("label", { htmlFor: inputId, className: "block text-sm text-muted-foreground", children: i18n.t("confirm.typeToConfirm", [confirmText]) }), _jsx(Input, { id: inputId, value: typed, autoComplete: "off", spellCheck: false, disabled: loading, onChange: event => setTyped(event.target.value), onKeyDown: event => {
42
+ if (event.key === 'Enter') {
43
+ event.preventDefault();
44
+ void handleConfirm();
45
+ }
46
+ } })] })), error && (_jsx("p", { role: "alert", className: "text-sm text-destructive break-words", children: i18n.t("confirm.notCompleted", [error]) })), _jsxs(DialogFooter, { className: "gap-2 border-t border-[color:var(--console-border-subtle)] pt-3", children: [_jsx(DialogClose, { asChild: true, children: _jsx(Button, { variant: "outline", size: "sm", children: cancelLabel ?? i18n.t("confirm.cancel") }) }), _jsx(Button, { variant: variant === 'destructive' ? 'destructive' : 'default', size: "sm", onClick: handleConfirm, disabled: !canSubmit, children: loading ? i18n.t("confirm.processing") : (confirmLabel ?? i18n.t("confirm.confirm")) })] })] }) }));
47
+ }
48
+ /**
49
+ * Hook for imperative confirm dialogs.
50
+ * Usage:
51
+ * const confirm = useConfirm()
52
+ * if (await confirm({ title: '确定删除?', variant: 'destructive' })) { ... }
53
+ */
54
+ export function useConfirm() {
55
+ const [state, setState] = useState(null);
56
+ const confirm = useCallback((opts) => {
57
+ return new Promise(resolve => {
58
+ setState({ resolve, opts });
59
+ });
60
+ }, []);
61
+ const ConfirmDialogElement = state ? (_jsx(ConfirmDialog, { open: true, onOpenChange: open => {
62
+ if (!open) {
63
+ state.resolve(false);
64
+ setState(null);
65
+ }
66
+ }, onConfirm: () => {
67
+ state.resolve(true);
68
+ setState(null);
69
+ }, ...state.opts })) : null;
70
+ return { confirm, ConfirmDialog: ConfirmDialogElement };
71
+ }
@@ -0,0 +1,15 @@
1
+ import type { LucideIcon } from 'lucide-react';
2
+ export interface EmptyStateProps {
3
+ icon?: LucideIcon;
4
+ title?: string;
5
+ description?: string;
6
+ className?: string;
7
+ /** 嵌入表格/卡片内时使用更紧凑的样式 */
8
+ compact?: boolean;
9
+ }
10
+ /**
11
+ * 统一空状态组件
12
+ * - 标准化图标大小(w-12 h-12)、透明度(opacity-30)、间距
13
+ * - compact 模式用于表格行/卡片内嵌场景
14
+ */
15
+ export declare function EmptyState({ icon: Icon, title, description, className, compact }: EmptyStateProps): import("react").JSX.Element;
@@ -0,0 +1,15 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { useConsoleUiI18n } from '../i18n/index.js';
3
+ import { cn } from '../cn.js';
4
+ /**
5
+ * 统一空状态组件
6
+ * - 标准化图标大小(w-12 h-12)、透明度(opacity-30)、间距
7
+ * - compact 模式用于表格行/卡片内嵌场景
8
+ */
9
+ export function EmptyState({ icon: Icon, title, description, className, compact }) {
10
+ const i18n = useConsoleUiI18n();
11
+ if (compact) {
12
+ return (_jsxs("div", { className: cn('flex flex-col items-center gap-2 py-8 text-center', className), children: [Icon && _jsx(Icon, { className: "w-8 h-8 text-muted-foreground opacity-30" }), _jsx("p", { className: "console-text-body text-muted-foreground", children: title || i18n.t("empty.noData") }), description && _jsx("p", { className: "console-text-label text-muted-foreground", children: description })] }));
13
+ }
14
+ return (_jsxs("div", { className: cn('flex flex-col items-center gap-3 py-12 text-center', className), children: [Icon && _jsx(Icon, { className: "w-12 h-12 text-muted-foreground opacity-30" }), title && _jsx("h3", { className: "console-section-title", children: title }), _jsx("p", { className: "console-text-body text-muted-foreground max-w-sm", children: description || i18n.t("empty.noData") })] }));
15
+ }
@@ -0,0 +1,15 @@
1
+ export type ErrorAlertKind = 'none' | '404' | '503' | 'other';
2
+ export interface ErrorAlertProps {
3
+ error: string;
4
+ onRetry?: () => void;
5
+ className?: string;
6
+ kind?: ErrorAlertKind;
7
+ /** Raw error text kept behind a collapsible "技术详情" disclosure. */
8
+ technicalDetail?: string;
9
+ }
10
+ /**
11
+ * 统一错误提示组件
12
+ * - 标准化 Alert 样式 + 可选重试按钮
13
+ * - 404 / 503 使用差异化样式
14
+ */
15
+ export declare function ErrorAlert({ error, onRetry, className, kind, technicalDetail }: ErrorAlertProps): import("react").JSX.Element;
@@ -0,0 +1,22 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { useConsoleUiI18n } from '../i18n/index.js';
3
+ import { AlertCircle, RefreshCw, Info } from 'lucide-react';
4
+ import { Alert, AlertDescription } from './ui/alert.js';
5
+ import { Button } from './ui/button.js';
6
+ function variantForKind(kind) {
7
+ if (kind === '503')
8
+ return 'warning';
9
+ if (kind === '404')
10
+ return 'default';
11
+ return 'destructive';
12
+ }
13
+ /**
14
+ * 统一错误提示组件
15
+ * - 标准化 Alert 样式 + 可选重试按钮
16
+ * - 404 / 503 使用差异化样式
17
+ */
18
+ export function ErrorAlert({ error, onRetry, className, kind = 'other', technicalDetail }) {
19
+ const i18n = useConsoleUiI18n();
20
+ const Icon = kind === '404' ? Info : AlertCircle;
21
+ return (_jsxs(Alert, { variant: variantForKind(kind), className: className, children: [_jsx(Icon, { className: "h-4 w-4" }), _jsxs(AlertDescription, { className: "space-y-2", children: [_jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { children: error }), onRetry && (_jsxs(Button, { variant: "outline", size: "sm", onClick: onRetry, className: "shrink-0", children: [_jsx(RefreshCw, { className: "w-3 h-3 mr-1" }), i18n.t("error.retry")] }))] }), technicalDetail ? (_jsxs("details", { className: "text-xs", children: [_jsx("summary", { className: "cursor-pointer", children: i18n.t("error.technicalDetail") }), _jsx("pre", { className: "mt-2 whitespace-pre-wrap break-words", children: technicalDetail })] })) : null] })] }));
22
+ }
@@ -0,0 +1,41 @@
1
+ import { type ReactNode } from 'react';
2
+ import { type RefreshControlProps } from './RefreshControl.js';
3
+ /**
4
+ * Page chrome a page hands to the shell (ADR 0063 决策 2): the shell places the header actions and
5
+ * the refresh control; the page itself renders only its content.
6
+ */
7
+ export interface PageChrome {
8
+ /** Header actions (buttons, menus). */
9
+ readonly actions?: ReactNode;
10
+ /** Shows a RefreshControl in the header. */
11
+ readonly refresh?: RefreshControlProps;
12
+ }
13
+ export interface PageChromeStore {
14
+ get(): PageChrome | undefined;
15
+ /** Replaces the chrome; returns a release function that clears it only if it is still the latest. */
16
+ set(chrome: PageChrome): () => void;
17
+ subscribe(listener: () => void): () => void;
18
+ }
19
+ /** One store per mounted page slot; the shell creates it and passes it to {@link PageChromeProvider}. */
20
+ export declare function createPageChromeStore(): PageChromeStore;
21
+ export interface PageChromeProviderProps {
22
+ /** Store owned by the shell; omit to let the provider create one. */
23
+ readonly store?: PageChromeStore;
24
+ readonly children?: ReactNode;
25
+ }
26
+ /** Wraps a page slot so pages inside can call {@link usePageChrome}. */
27
+ export declare function PageChromeProvider({ store, children }: PageChromeProviderProps): import("react").JSX.Element;
28
+ /**
29
+ * Hands header actions and the refresh control to the shell. Returns `true` when a shell is
30
+ * listening; `false` means the page renders outside a shell (e.g. an older Console) and may draw
31
+ * the controls itself.
32
+ */
33
+ export declare function usePageChrome(chrome: PageChrome): boolean;
34
+ /** The chrome the current page registered; for the shell. */
35
+ export declare function usePageChromeState(store?: PageChromeStore): PageChrome | undefined;
36
+ export interface PageChromeActionsProps {
37
+ readonly store?: PageChromeStore;
38
+ readonly className?: string;
39
+ }
40
+ /** Renders the registered refresh control and actions; the shell puts it into `PageHeader.actions`. */
41
+ export declare function PageChromeActions({ store, className }: PageChromeActionsProps): import("react").JSX.Element | null;