@zhin.js/console-ui 0.0.0-stage → 1.1.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.
- package/CHANGELOG.md +54 -0
- package/LICENSE +21 -0
- package/README.md +195 -2
- package/audit/index.mjs +21 -0
- package/audit/layout-audit.mjs +492 -0
- package/audit/mount-page.jsx +90 -0
- package/audit/plugin-pages.mjs +186 -0
- package/dist/cn.d.ts +4 -0
- package/dist/cn.js +6 -0
- package/dist/components/BrandMark.d.ts +16 -0
- package/dist/components/BrandMark.js +21 -0
- package/dist/components/InfoHint.d.ts +12 -0
- package/dist/components/InfoHint.js +13 -0
- package/dist/components/PageHeader.d.ts +18 -0
- package/dist/components/PageHeader.js +11 -0
- package/dist/components/PageShell.d.ts +26 -0
- package/dist/components/PageShell.js +10 -0
- package/dist/components/RefreshControl.d.ts +28 -0
- package/dist/components/RefreshControl.js +68 -0
- package/dist/components/StatCard.d.ts +41 -0
- package/dist/components/StatCard.js +53 -0
- package/dist/components/StatusBadge.d.ts +14 -0
- package/dist/components/StatusBadge.js +19 -0
- package/dist/components/actions.d.ts +53 -0
- package/dist/components/actions.js +50 -0
- package/dist/components/code.d.ts +11 -0
- package/dist/components/code.js +10 -0
- package/dist/components/confirm-dialog-model.d.ts +9 -0
- package/dist/components/confirm-dialog-model.js +20 -0
- package/dist/components/confirm-dialog.d.ts +32 -0
- package/dist/components/confirm-dialog.js +72 -0
- package/dist/components/content-blocks.d.ts +141 -0
- package/dist/components/content-blocks.js +77 -0
- package/dist/components/empty-illustrations.d.ts +15 -0
- package/dist/components/empty-illustrations.js +36 -0
- package/dist/components/empty-state.d.ts +35 -0
- package/dist/components/empty-state.js +43 -0
- package/dist/components/error-alert.d.ts +15 -0
- package/dist/components/error-alert.js +23 -0
- package/dist/components/icon.d.ts +11 -0
- package/dist/components/icon.js +8 -0
- package/dist/components/layout.d.ts +38 -0
- package/dist/components/layout.js +28 -0
- package/dist/components/page-chrome.d.ts +53 -0
- package/dist/components/page-chrome.js +66 -0
- package/dist/components/refresh-control-model.d.ts +9 -0
- package/dist/components/refresh-control-model.js +26 -0
- package/dist/components/ui/accordion.d.ts +7 -0
- package/dist/components/ui/accordion.js +15 -0
- package/dist/components/ui/alert.d.ts +8 -0
- package/dist/components/ui/alert.js +24 -0
- package/dist/components/ui/badge.d.ts +9 -0
- package/dist/components/ui/badge.js +30 -0
- package/dist/components/ui/button.d.ts +20 -0
- package/dist/components/ui/button.js +52 -0
- package/dist/components/ui/card.d.ts +17 -0
- package/dist/components/ui/card.js +17 -0
- package/dist/components/ui/checkbox.d.ts +4 -0
- package/dist/components/ui/checkbox.js +10 -0
- package/dist/components/ui/control-variant.d.ts +10 -0
- package/dist/components/ui/control-variant.js +6 -0
- package/dist/components/ui/date-field-model.d.ts +39 -0
- package/dist/components/ui/date-field-model.js +105 -0
- package/dist/components/ui/date-field.d.ts +33 -0
- package/dist/components/ui/date-field.js +161 -0
- package/dist/components/ui/dialog.d.ts +24 -0
- package/dist/components/ui/dialog.js +27 -0
- package/dist/components/ui/dropdown-menu.d.ts +19 -0
- package/dist/components/ui/dropdown-menu.js +26 -0
- package/dist/components/ui/input.d.ts +8 -0
- package/dist/components/ui/input.js +9 -0
- package/dist/components/ui/list-item-button.d.ts +10 -0
- package/dist/components/ui/list-item-button.js +6 -0
- package/dist/components/ui/popover.d.ts +6 -0
- package/dist/components/ui/popover.js +9 -0
- package/dist/components/ui/radio-group.d.ts +5 -0
- package/dist/components/ui/radio-group.js +10 -0
- package/dist/components/ui/scroll-area.d.ts +5 -0
- package/dist/components/ui/scroll-area.js +13 -0
- package/dist/components/ui/searchable-select-model.d.ts +29 -0
- package/dist/components/ui/searchable-select-model.js +38 -0
- package/dist/components/ui/searchable-select.d.ts +26 -0
- package/dist/components/ui/searchable-select.js +85 -0
- package/dist/components/ui/select.d.ts +29 -0
- package/dist/components/ui/select.js +39 -0
- package/dist/components/ui/separator.d.ts +4 -0
- package/dist/components/ui/separator.js +11 -0
- package/dist/components/ui/sheet.d.ts +27 -0
- package/dist/components/ui/sheet.js +27 -0
- package/dist/components/ui/skeleton.d.ts +3 -0
- package/dist/components/ui/skeleton.js +6 -0
- package/dist/components/ui/switch.d.ts +4 -0
- package/dist/components/ui/switch.js +8 -0
- package/dist/components/ui/table.d.ts +27 -0
- package/dist/components/ui/table.js +47 -0
- package/dist/components/ui/tabs.d.ts +7 -0
- package/dist/components/ui/tabs.js +13 -0
- package/dist/components/ui/textarea.d.ts +8 -0
- package/dist/components/ui/textarea.js +9 -0
- package/dist/components/ui/tooltip.d.ts +7 -0
- package/dist/components/ui/tooltip.js +11 -0
- package/dist/components/use-container-width.d.ts +13 -0
- package/dist/components/use-container-width.js +30 -0
- package/dist/custom-media.css +13 -0
- package/dist/exports.json +178 -0
- package/dist/i18n/index.d.ts +27 -0
- package/dist/i18n/index.js +33 -0
- package/dist/i18n/messages.d.ts +55 -0
- package/dist/i18n/messages.js +110 -0
- package/dist/index.d.ts +56 -0
- package/dist/index.js +55 -0
- package/dist/scale.json +643 -0
- package/dist/shared-module.d.ts +28 -0
- package/dist/shared-module.js +24 -0
- package/dist/styles.css +3399 -0
- package/dist/theme.css +469 -0
- package/dist/tokens.css +652 -0
- package/dist/version.d.ts +6 -0
- package/dist/version.js +2 -0
- package/lint/eslint-plugin.mjs +128 -0
- package/lint/stylelint-config.mjs +43 -0
- package/lint/stylelint-plugin.mjs +195 -0
- package/lint/tailwind-classes.mjs +121 -0
- package/package.json +103 -3
- package/tokens/color.mjs +104 -0
- package/tokens/colors.css +220 -0
- package/tokens/generate.mjs +288 -0
- package/tokens/scale.mjs +137 -0
- package/tokens/tokens.mjs +362 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# @zhin.js/console-ui
|
|
2
|
+
|
|
3
|
+
## 1.1.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 94dcb49: ADR 0063 色板角色与信号色(zhinjs/console#125),外观有意改变:
|
|
8
|
+
|
|
9
|
+
- **令牌**:`tokens/tokens.mjs` 新增与配色无关的颜色角色(深浅两套)——`--console-brand`(`#76EEC6` / `#7FFFD4`,所有者 2026-11-16 决定)、`--console-brand-foreground`、`--console-brand-text`(链接、焦点环、选中态)、`--console-brand-tint`、`--console-signal-{danger,warning,success,info}-{fill,text}`(同色相同饱和度,只调亮度;警告填充为琥珀 `hsl(38 92% 50%)`)、`--console-chart-1`…`-8` / `-other`;Tailwind 主题提供同名颜色类(`bg-brand`、`text-signal-danger-text` 等)。旧名 `--destructive` / `--success` / `--warning` / `--info` 指向对应的 `signal-*-text`,`--chart-*` 指向 `--console-chart-*`,`--ring` 与焦点环改用 `brand-text`。
|
|
10
|
+
- **动效**:`--console-motion-fast` 120ms / `-base` 200ms / `-slow` 280ms,缓动统一 `--console-ease-out`,Tailwind `transition-*` 默认也用它们;`--console-duration-fast`(原 150ms)/ `--console-duration-page` 改为弃用别名。stylelint 新规则 `console/motion-tokens` 禁止写死时长与缓动(`createConsoleStylelintConfig({ motionTokens })` 可降为 `'warning'`)。
|
|
11
|
+
- **组件**:新增 `BrandMark`(favicon 形状,品牌色固定,可带「Zhin Console」)与 `CONSOLE_PRODUCT_NAME`;`Button` 新增 `primary`(品牌底 + 深色字,每个视图最多一个)与 `destructive-solid`(只用于确认对话框),`default` 改名 `soft`(`default` 保留为弃用别名,外观不变),`destructive` 改为幽灵样式(红字、无底);`ConfirmDialog` 的危险确认改用 `destructive-solid`、普通确认用 `primary`;`PageAction` 的 `tone: 'primary'` 渲染为 `primary`。徽标、`StatCard`、`InfoHint`、`ProgressMeter`、`Sparkline`、`Timeline`、`MiniRingGauge` 改用信号 fill / text,danger 比 success 醒目;`StatCard` 数值为 0 时忽略 `tone`(新增 `isZeroValue`)。复选、单选、开关、下拉勾选与输入框焦点边框改用 `brand-text`。`styles.css` 在根上设置 `font-variant-numeric: tabular-nums`。
|
|
12
|
+
- **升级提示**:页面上直接用 `variant="destructive"` 作确认按钮的,改为 `destructive-solid`(或改用 `ConfirmDialog`)。
|
|
13
|
+
|
|
14
|
+
- 9dbddcc: ADR 0063 D28–D33(zhinjs/console#125 第三阶段,组件库一侧),外观有意改变:
|
|
15
|
+
|
|
16
|
+
- **空状态**:`EmptyState` 改为 64px 线稿插画 + 一句说明 + 至多一个操作。新增 `illustration`(`messages`、`tasks`、`logs`、`table`、`record`、`not-found`、`generic`,1.5px 描边、`brand-text` 单色)与 `action`(`{ label, onSelect?, href?, variant?: 'soft' | 'primary', icon? }` 或元素);新增 `EmptyIllustration`、`EMPTY_ILLUSTRATIONS`。原有属性不变;没传 `illustration` 时图标改为 `brand-text`,不再是 opacity 0.3 的灰图标。不再单独显示「暂无数据」:只给 `title` 时只显示标题,`empty.noData` 的文案改为「这里还没有内容」/「Nothing here yet」,新增各插画的默认说明。
|
|
17
|
+
- **表单**:`Input`、`Textarea`、`SelectTrigger` / `SelectField`、`SearchableSelectField` 新增 `variant="ghost"`(平时无边框,悬停、聚焦或展开时才有边框;类型 `ControlVariant`,新增导出类型 `InputProps`、`TextareaProps`、`SelectTriggerProps`)。新增 `DateField`(`YYYY-MM-DD`)与 `DateTimeField`(`YYYY-MM-DDTHH:mm`)替代原生日期框:本地时间 ISO 值、可清空、键盘操作、`min` / `max`,基于 Popover + 月历,不引入新依赖;新增日期纯函数 `parseDateValue`、`parseDateTimeValue`、`formatDateValue`、`formatDateTimeValue`、`calendarMonth`、`addDays`、`addMonths`。
|
|
18
|
+
- **图标**:组件库内的 lucide 图标统一 `strokeWidth 1.75`(原为 2),新增 `CONSOLE_ICON_STROKE_WIDTH`、`CONSOLE_ICON_SIZE`(控件 16、导航 18)。
|
|
19
|
+
- **代码标识**:新增 `InlineCode`(`tone`:`subtle` / `plain`)与 `console-code` 类,等宽、极浅底色、无边框;`CodeText` 外观与之相同。
|
|
20
|
+
- **焦点与动效**:鼠标操作对话框、菜单、下拉与日期选择后不留焦点环(视觉回归检查);抽屉、底部抽屉与骨架屏动画只在 `prefers-reduced-motion: no-preference` 下运行。
|
|
21
|
+
- **字体**:`--console-font-sans` / `--console-font-mono` 字体栈不变(Inter / JetBrains Mono 优先),文档写明本包不打包字体、由宿主加载。
|
|
22
|
+
|
|
23
|
+
- 021d052: ADR 0063 P1b:令牌与组件规则(有意改变外观)。
|
|
24
|
+
|
|
25
|
+
- **三层令牌、单一事实来源**:`tokens/tokens.mjs` 定义基础尺度(字号 `label` / `body` / `section` / `title` / `display`,字重 `regular` / `medium` / `strong`,`space-1`…`space-8`,`r-0`…`r-4` / `r-full`,`hairline` / `focus`,`e-0`…`e-3`,断点 `sm` 40rem / `md` 48rem / `lg` 64rem / `xl` 90rem,内容宽度 `reading` 60rem / `data` 120rem)、语义令牌(`--console-card-padding`、`--console-control-height` 等)和按尺寸取值;由它生成 `tokens.css`、Tailwind 4 主题 `@zhin.js/console-ui/theme.css`(间距只保留 `0`、`px`、`1`、`2`、`3`、`4`、`6`、`8`、`12`、`16`,默认字号、字重、圆角、阴影、断点和颜色清空)、`custom-media.css` 与 `scale.json`。页面级令牌按视口取值,其余令牌按所在 `.console-cq` 容器的宽度取值。
|
|
26
|
+
- **取值变化**:`--console-content-max` 默认为 `data`(120rem,原 90rem),`PageShell width="reading"` 为 60rem;圆角 6 / 10 / 14 / 18px,不再用 `calc(… - Npx)`;静态卡片改为 hairline 描边、无阴影;手机宽度下控件 44px;`--console-radius-sm/md/lg/xl/2xl`、`--console-shadow-*`、`--console-space-page-x/-y`、`--console-space-section/-stack/-card`、`--console-control-height-sm/-lg`、`--console-text-body-sm` 等旧名改为别名,P4 删除。
|
|
27
|
+
- **组件**:`PageShell` 新增 `width`(`reading` / `data` / `full`)与 `inset`,自带页面边距并解析 `--console-content-max`;`PageHeader` 与 `usePageChrome` 新增 `menuActions` / `moreActions`,窄于 40rem 时收进「更多」菜单;`Table` 在窄于 40rem 的容器里每行变卡片(`priority="secondary"` 的列隐藏,单元格标签取自表头或 `label`);下拉、菜单、弹出层和对话框在手机上以底部抽屉出现;`Badge` 的 `success` 与新组件 `StatusBadge` 把「正常」渲染为弱化文字;新增 `Section`、`Grid`、`ListDetail`、`MoreMenu`、`RowActions`、`PageActions`、`useContainerAtLeast`。
|
|
28
|
+
- **约束工具(可被 zhinjs/console 复用)**:`@zhin.js/console-ui/stylelint`(`createConsoleStylelintConfig()`)、`@zhin.js/console-ui/eslint`(`configs.recommended`:禁任意值、尺度外类名、原生控件)、`@zhin.js/console-ui/tailwind-classes`、`@zhin.js/console-ui/audit`(Playwright 布局审计 `auditPage` / `runLayoutAudit` / `auditPluginPages`,豁免写 `data-zhin-ui-ignore="<检查项>: <理由>"`)。
|
|
29
|
+
|
|
30
|
+
- 8941172: ADR 0063 P2:声明式渲染器改用 `@zhin.js/console-ui`,`@zhin.js/client/ui` 弃用。
|
|
31
|
+
|
|
32
|
+
`@zhin.js/client`:
|
|
33
|
+
|
|
34
|
+
- `DeclarativePageView`、`AdapterConsolePage`、`CommentReviewPage` 只渲染内容区块:标题、说明、无表单的动作、状态徽标和 `RefreshControl`(更新于 hh:mm:ss、手动 / 5s / 15s / 30s 自动、刷新)通过 `usePageChrome` 交给 Console 的页面外壳;外层没有 `PageChromeProvider`(旧版 Console)时在内容区内自己画页头。`AdapterConsolePage embedded` 不上报页头。宿主可读 `DECLARATIVE_PAGE_CAPABILITIES` / `ADAPTER_CONSOLE_PAGE_CAPABILITIES` 的 `pageChrome: true` 判断。
|
|
35
|
+
- 删除首字母方块:蓝图与评论审批 spec 的 `mark` 被忽略,使用时控制台告警一次(后续 minor 删除)。
|
|
36
|
+
|
|
37
|
+
`@zhin.js/console-contract`:蓝图与评论审批 spec 的 `mark` 标注为弃用,评论审批 spec 的 `mark` 改为可选,`defineCommentReviewPage` 不再把它写进蓝图。`@zhin.js/adapter-bilibili`、`@zhin.js/adapter-juejin`:评论审批页不再设置 `mark`。
|
|
38
|
+
|
|
39
|
+
- `variant: 'danger'` 的动作(页头、表单、行操作、批量操作)渲染为 `destructive-outline` 描边按钮并弹出确认对话框,没写 `confirm` 时自动补「确认<动作名>?」;实心红色只在确认按钮上;`confirmText` 照常可用。
|
|
40
|
+
- 渲染器里不再有原生 `<select>`(选择字段、自动刷新间隔、适配器页布尔字段与平台动作选项均为 Radix 下拉),也不再注入 `zk-` 样式;删除 `adapter-console/styles.ts`、`review-console/styles.ts`。统计卡片为弹性网格,`DataTable` 基于新表格组件并在窄容器里每行变成一张卡片(列的 `fixed`、`responsiveStack` 不再起作用),原始 ID 与 JSON 默认收起,正常状态的徽标弱化。
|
|
41
|
+
- 非 UI 导出迁到根入口:`usePluginRpc`、`usePluginData`、`useRpcResource`、`useLocale`、`detectLocale`、`translate`、`formatClock`、`resolvePluginId`、`resolveSyncPluginId`、`resolveAdapterConsolePluginId`、`DeclarativePageView`、`createDeclarativePage`、`DataTable` 及类型。`@zhin.js/client/ui` 改为弃用的再导出层(原样再导出这些名字和旧 `zk-` 组件,首次导入告警一次,`zk-` 类名弃用),升级对照见 docs/authoring/console-pages.md「从 @zhin.js/client/ui 升级」。`adapterConsoleStyles`、`conversationPickerStyles` 弃用期内为空字符串。
|
|
42
|
+
- 独立的适配器页与评论审批页的定时刷新改由 `RefreshControl` 驱动(适配器页默认 6 秒、评论审批页默认 10 秒,扫码登录等待时评论审批页仍每 2 秒轮询);嵌入模式与 `AdapterAccountsProvider` 照旧自己轮询。
|
|
43
|
+
|
|
44
|
+
`@zhin.js/console-ui`:新增内容区块 `ContentStack`、`FormField`、`KeyValueList`、`ProgressMeter`、`Sparkline`、`Timeline`、`Disclosure`、`CodeText`、`JsonBlock`、`MediaPreview`、`RecordCard`(由 `Card` + `KeyValueList` 组成)、`LoadingBlock`(按所在 `.console-cq` 容器宽度切换布局,只用语义令牌,样式在 `styles.css` 里);分区、网格、统计卡片与表格卡片直接复用 P1b 的 `Section`、`Grid`、`StatGrid` / `StatCard`、`Table`,不另设组件:`Section`、`Grid` 透传 HTML 属性,`StatGrid` 透传 `data-*`,`StatCard` 新增可选 `unit` / `badge` / `footer`,`icon` 改为可选并接受元素或图片 URL;`usePageChrome` 可上报 `title` / `description`;`RefreshControl` 新增 `onAutoRefresh`(自动刷新与手动刷新做的事不同时使用)。
|
|
45
|
+
|
|
46
|
+
另:`DeclarativePageView` 现在也接受函数形式的蓝图(`definePageBlueprint` / `defineCommentReviewPage` 返回的页面函数本身),评论审批蓝图不再被误当成普通蓝图渲染。
|
|
47
|
+
|
|
48
|
+
## 1.0.0
|
|
49
|
+
|
|
50
|
+
### Patch Changes
|
|
51
|
+
|
|
52
|
+
- 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`。
|
|
53
|
+
|
|
54
|
+
`@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,196 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @zhin.js/console-ui
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Zhin Console 与插件页面共用的组件库([ADR 0063](../../../docs/adr/0063-console-plugin-ui-unification.md)):基于 Radix 的 React 组件、页面外壳、刷新控件,以及一份设计令牌。样式随包发布、已经编译好,使用方不需要 Tailwind。
|
|
4
|
+
|
|
5
|
+
> 状态:P1b(三层令牌、单一事实来源、组件规则、lint 与布局审计;外观有意改变,见 ADR 0063 D15–D22);P2 起 `@zhin.js/client` 的三个声明式渲染器改用本包,并新增「内容区块」(见下文);色板角色、信号色、`primary` 按钮、`BrandMark` 与动效令牌见 ADR 0063 D23–D27(zhinjs/console#125);空状态插画、ghost 控件、日期选择、图标、代码标识、焦点环与字体见 D28–D33(#125 第三阶段)。`@zhin.js/client/ui` 已弃用,升级对照见 [Console 页面与布局](../../../docs/authoring/console-pages.md#upgrade-client-ui)。
|
|
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`:只有令牌(颜色与三层尺寸令牌)。深色由祖先上的 `.dark` 切换,配色由 `<html data-palette>` 切换。
|
|
18
|
+
- `@zhin.js/console-ui/theme.css`:生成的 Tailwind 4 主题,只暴露尺度内的键(见下文「令牌」)。自己用 Tailwind 的使用方(Console)在 `@import "tailwindcss"` 之后引入它。
|
|
19
|
+
- `@zhin.js/console-ui/custom-media.css`:外壳用的 `@custom-media --console-sm` 等(需要 postcss-custom-media)。
|
|
20
|
+
- `@zhin.js/console-ui/scale.json`、`@zhin.js/console-ui/scale`:允许值清单(JSON / ESM),供 lint、`zhin plugin check` 与审计使用。
|
|
21
|
+
- `@zhin.js/console-ui/cn`:只有 `cn()`(`@zhin.js/client` 由此再导出 `cn`)。
|
|
22
|
+
|
|
23
|
+
插件的手写 `.tsx` 页面把本包声明为 `peerDependencies`(例如 `"@zhin.js/console-ui": "^1.0.0"`):`@zhin.js/pagemanager` 不会把它打进插件,页面拿到的是 Console 已加载的那份组件和 CSS;版本不兼容时会明确报错,见下文「共享模块版本」。
|
|
24
|
+
|
|
25
|
+
## 导出
|
|
26
|
+
|
|
27
|
+
| 类别 | 导出 |
|
|
28
|
+
| --- | --- |
|
|
29
|
+
| 基础组件(`components/ui/*`) | `Accordion*`、`Alert`/`AlertTitle`/`AlertDescription`、`Badge`/`badgeVariants`、`Button`/`buttonVariants`、`Card*`、`Checkbox`、`DateField`/`DateTimeField`、`Dialog*`、`DropdownMenu*`、`Input`、`ListItemButton`、`Popover`/`PopoverTrigger`/`PopoverAnchor`/`PopoverContent`、`RadioGroup`/`RadioGroupItem`、`ScrollArea`/`ScrollBar`、`SearchableSelectField`、`Select*`/`SelectField`、`Separator`、`Sheet*`、`Skeleton`、`Switch`、`Table*`、`Tabs*`、`Textarea`、`Tooltip*` |
|
|
30
|
+
| 表单控件(D29) | `variant="ghost"`(`Input`、`Textarea`、`SelectTrigger` / `SelectField`、`SearchableSelectField`、`DateField`、`DateTimeField`,类型 `ControlVariant`);日期纯函数 `parseDateValue`、`parseDateTimeValue`、`formatDateValue`、`formatDateTimeValue`、`calendarMonth`、`addDays`、`addMonths` |
|
|
31
|
+
| 空状态与标识(D28、D31) | `EmptyState`(`illustration`、`action`)、`EmptyIllustration`、`EMPTY_ILLUSTRATIONS`、`InlineCode`(`tone`:`subtle` / `plain`) |
|
|
32
|
+
| 图标(D30) | `CONSOLE_ICON_STROKE_WIDTH`(1.75)、`CONSOLE_ICON_SIZE`(控件 16、导航 18) |
|
|
33
|
+
| 品牌 | `BrandMark`(`size`:`sm` / `md` / `lg` / 像素值,`withText` 显示「Zhin Console」)、`CONSOLE_PRODUCT_NAME` |
|
|
34
|
+
| 页面与通用组件 | `PageShell`(`width`:`reading` / `data` / `full`)、`PageHeader`(`menuActions` / `moreActions`)、`Section`、`Grid`、`ListDetail`、`StatusBadge`/`isAttentionStatus`、`MoreMenu`、`RowActions`、`PageActions`、`ConfirmDialog`/`useConfirm`、`StatCard`/`StatGrid`/`MiniRingGauge`/`isZeroValue`、`EmptyState`、`ErrorAlert`、`InfoHint`、`RefreshControl` |
|
|
35
|
+
| 内容区块(P2) | `ContentStack`、`FormField`、`KeyValueList`、`ProgressMeter`、`Sparkline`、`Timeline`、`Disclosure`、`CodeText`、`JsonBlock`、`MediaPreview`、`RecordCard`(`Card` + `KeyValueList`)、`LoadingBlock`;分区、网格、统计卡片与表格卡片直接用上面的 `Section`、`Grid`、`StatGrid` / `StatCard`、`Table` |
|
|
36
|
+
| 容器宽度 | `useContainerAtLeast`、`CONSOLE_BREAKPOINTS_REM`、`syncTableCellLabels` |
|
|
37
|
+
| 页面外壳接口 | `usePageChrome({ title, description, actions, refresh, menuActions, moreActions })`、`PageChromeProvider`、`createPageChromeStore`、`usePageChromeState`、`PageChromeActions` |
|
|
38
|
+
| 语言 | `ConsoleUiI18nProvider`、`useConsoleUiI18n`、`createConsoleUiI18n`、`ConsoleUiText`、`CONSOLE_UI_MESSAGES`、`CONSOLE_UI_LOCALES` |
|
|
39
|
+
| 纯函数 | `cn`、`groupSelectOptions`、`navigableValues`、`optionMatches`、`optionSearchText`、`canSubmitConfirm`、`confirmTextMatches`、`confirmErrorMessage`、`formatRefreshTime`、`refreshIntervalOptions`、`DEFAULT_REFRESH_INTERVALS` |
|
|
40
|
+
| 共享模块 | `CONSOLE_UI_VERSION`、`CONSOLE_UI_MODULE_ID`、`registerConsoleUiSharedModule`、`CONSOLE_SHARED_MODULE_VERSIONS_KEY`、`CONSOLE_SHARED_MODULE_ISSUES_KEY`、`CONSOLE_SHARED_MODULE_ISSUE_EVENT` |
|
|
41
|
+
|
|
42
|
+
组件的属性与 Console 原来的同名组件一致。`Button` 的变体(ADR 0063 D25):
|
|
43
|
+
|
|
44
|
+
| 变体 | 外观与用途 |
|
|
45
|
+
| --- | --- |
|
|
46
|
+
| `primary` | 品牌色实心底 + 深色字(`brand` / `brand-foreground`),浅色主题下另有一圈 `brand-text` 描边。**每个视图最多一个**:登录、保存、发送、筛选这类「下一步」;`PageAction` 的 `tone: 'primary'` 和非危险的 `ConfirmDialog` 确认按钮也用它 |
|
|
47
|
+
| `soft` | 配色的浅色调(原来的 `default`)。`default` 是它的弃用别名,外观相同、仍是默认变体,保留到 P4 |
|
|
48
|
+
| `outline`、`secondary`、`ghost`、`link` | 不变;`link` 改用 `brand-text` |
|
|
49
|
+
| `destructive` | **幽灵样式**:红字、无底。页面上的危险操作入口 |
|
|
50
|
+
| `destructive-outline` | 描边 + 红字(ADR 0063 决策 5) |
|
|
51
|
+
| `destructive-solid` | 实心红。**只用于确认对话框的确认按钮**(`ConfirmDialog variant="destructive"` 已使用) |
|
|
52
|
+
|
|
53
|
+
## 空状态、ghost 控件、日期选择与代码标识(ADR 0063 D28–D31)
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
import { DateTimeField, EmptyState, InlineCode, SelectField } from '@zhin.js/console-ui';
|
|
57
|
+
|
|
58
|
+
<EmptyState illustration="tasks" action={{ label: '新建定时任务', variant: 'primary', onSelect: create }} />
|
|
59
|
+
<EmptyState illustration="table" compact /> // 「在左侧选择一个数据表」
|
|
60
|
+
<SelectField variant="ghost" aria-label="备用模型" value={fallback} onValueChange={setFallback} options={models} />
|
|
61
|
+
<DateTimeField aria-label="开始时间" value={since} onValueChange={setSince} /> // '2026-11-16T09:30',清空为 ''
|
|
62
|
+
<p>插件 <InlineCode>@zhin.js/plugin-rss</InlineCode> 的 RPC <InlineCode>rss.status</InlineCode></p>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
- **`EmptyState`**:64px 线稿插画 + 一句说明 + 至多一个操作。`illustration` 取 `messages`(无消息)、`tasks`(无任务)、`logs`(无日志)、`table`(未选中数据表)、`record`(未选中记录)、`not-found`(找不到页面)、`generic`(通用空);插画是 `brand-text` 单色、1.5px 描边。不给说明时用插画的默认说明,不再单独显示「暂无数据」。`action` 是 `{ label, onSelect?, href?, variant?: 'soft' | 'primary', icon? }`(默认 `soft`)或一个元素。原有的 `icon` / `title` / `description` / `compact` 不变;没传 `illustration` 时图标改为 `brand-text`,不再是半透明灰色。
|
|
66
|
+
- **ghost 控件**:`variant="ghost"` 平时无边框,悬停、聚焦或展开时才出现边框,用于次要字段。
|
|
67
|
+
- **`DateField` / `DateTimeField`**:替代原生 `date` / `datetime-local` 输入框,值为本地时间的 ISO 字符串(`YYYY-MM-DD` / `YYYY-MM-DDTHH:mm`),空值 `''`;`min`、`max`、`clearable`(默认开)、`weekStartsOn`、`placeholder`、`variant`。键盘:触发器上 Enter / ↓ 打开、Delete / Backspace 清空;月历里方向键按天 / 周、Home / End、PageUp / PageDown 按月(Shift 按年)、Enter 选中、Esc 关闭。
|
|
68
|
+
- **`InlineCode`**(或 `console-code` 类):包名、RPC 名、ID 这类短标识;等宽字体,极浅底色(`tone="plain"` 无底色),不加边框。`CodeText` 外观相同。
|
|
69
|
+
- **图标**:组件里的 lucide 图标统一 `strokeWidth 1.75`,控件里 16px、导航 18px;列表、⌘K、工具栏的图标不放在浅色方块里。宿主可用 `<LucideProvider strokeWidth={CONSOLE_ICON_STROKE_WIDTH}>` 让自己的图标一致。
|
|
70
|
+
- **焦点环**:只在 `:focus-visible` 时出现,鼠标点开再关闭对话框、菜单、下拉和日期选择后不留焦点环。所有动画只在 `prefers-reduced-motion: no-preference` 下运行。
|
|
71
|
+
|
|
72
|
+
`StatCard` 的 `tone`(`danger` / `warning`)只给异常值着色:数值用信号文字色、图标用信号填充色,`danger` 卡片另有红色描边;数值为 0 时不着色(稳态,`isZeroValue`)。
|
|
73
|
+
|
|
74
|
+
## 令牌(ADR 0063 D16、D17)
|
|
75
|
+
|
|
76
|
+
令牌只在 `tokens/tokens.mjs` 定义一次(颜色在 `tokens/colors.css`),`node tokens/generate.mjs` 生成 `client/styles/generated/` 下的 `tokens.css`、`theme.css`、`custom-media.css`、`scale.json`;生成物不得手改(`--check` 和单元测试会核对),构建时复制到 `dist/`。
|
|
77
|
+
|
|
78
|
+
| 层 | 内容 |
|
|
79
|
+
| --- | --- |
|
|
80
|
+
| 第一层:基础尺度 | `--console-text-label/body/section/title/display`(13 / 14 / 16 / 22 / 28px)、`--console-weight-regular/medium/strong`、`--console-space-1`…`-8`(0.25 / 0.5 / 0.75 / 1 / 1.5 / 2 / 3 / 4rem)、`--console-radius-0`…`-4`(0 / 6 / 10 / 14 / 18px)与 `-full`、`--console-border-hairline/focus`、`--console-elevation-0`…`-3`、`--console-bp-sm/md/lg/xl`(40 / 48 / 64 / 90rem)、`--console-content-reading/data`(60 / 120rem) |
|
|
81
|
+
| 第二层:语义令牌(组件只用这一层) | `--console-page-padding-inline`、`--console-page-padding-block`、`--console-section-gap`、`--console-stack-gap`、`--console-inline-gap`、`--console-heading-gap`、`--console-card-padding(-wide)`、`--console-card-radius`、`--console-card-edge-radius`、`--console-card-border`、`--console-card-elevation`、`--console-card-hover-elevation`、`--console-grid-gap`、`--console-list-row-padding(-inline)`、`--console-control-height(-compact)`、`--console-control-radius`、`--console-control-padding-inline`、`--console-control-gap`、`--console-control-border`、`--console-check-radius`、`--console-segment-radius`、`--console-touch-min`、`--console-badge-height/radius/padding-inline`、`--console-popover-radius/item-radius/padding/elevation`、`--console-dialog-radius/padding/elevation/close-clearance`、`--console-sheet-radius`、`--console-focus-ring(-width/-offset)`、`--console-content-max` |
|
|
82
|
+
| 第三层:按尺寸取值 | 小于 40rem / 40–64rem / 64rem 及以上三档,取值见 `tokens.mjs` 的 `semantic`(即 D16 的「按尺寸取值」表)。页面级令牌和浮层令牌按视口取值;其余令牌按所在 `.console-cq` 容器(`PageShell`、`PageHeader`、`Table`、`StatGrid` 等)的宽度取值 |
|
|
83
|
+
|
|
84
|
+
颜色角色(ADR 0063 D23,zhinjs/console#125)在 `tokens.mjs` 的 `color` 中定义,深浅两套,**与配色无关**,生成为 HSL 三元组(`hsl(var(--console-brand))`、`hsl(var(--console-brand) / 0.1)`),Tailwind 主题提供同名颜色类(`bg-brand`、`text-brand-foreground`、`text-signal-danger-text`、`fill-chart-1` 等):
|
|
85
|
+
|
|
86
|
+
| 令牌 | 浅色 | 深色 | 用途 |
|
|
87
|
+
| --- | --- | --- | --- |
|
|
88
|
+
| `--console-brand` | `#76EEC6` | `#7FFFD4` | 品牌标、`primary` 按钮底色(所有者 2026-11-16 决定) |
|
|
89
|
+
| `--console-brand-foreground` | `160 80% 10%` | `160 80% 10%` | 品牌底上的文字 |
|
|
90
|
+
| `--console-brand-text` | `160 84% 25%` | `#7FFFD4` | 链接、焦点环、选中态(品牌色当文字或细线用) |
|
|
91
|
+
| `--console-brand-tint` | `160 60% 94%` | `160 40% 14%` | 选中行等安静的品牌底 |
|
|
92
|
+
| `--console-signal-{danger,warning,success,info}-fill` | 明亮 | 明亮 | 圆点、进度条、图标、徽标底色;不当文字 |
|
|
93
|
+
| `--console-signal-{danger,warning,success,info}-text` | ≥ 4.5:1 | ≥ 4.5:1 | 状态文字;与 fill 同色相、同饱和度,深浅主题只调亮度 |
|
|
94
|
+
| `--console-chart-1`…`-8`、`--console-chart-other` | 分类色 | 分类色 | 一切数据可视化;相邻两色 ΔE2000 ≥ 20 |
|
|
95
|
+
|
|
96
|
+
稳态(运行中、成功、失败数为 0)不用信号色;「失败」「已拒绝」比「成功」醒目。旧颜色名 `--destructive`、`--success`、`--warning`、`--info` 指向对应的 `signal-*-text`,`--chart-*` 指向 `--console-chart-*`,`--ring` 指向 `brand-text`。具体取值与实测对比度见 ADR 0063 D23。
|
|
97
|
+
|
|
98
|
+
字体(D33):`--console-font-sans`(Inter 优先)与 `--console-font-mono`(JetBrains Mono 优先)只定义字体栈,之后回退到系统字体。**本包不打包字体,宿主负责加载字体**(例如 Console 用 `@font-face` 自托管 Inter 与 JetBrains Mono 的拉丁 + 数字子集,`font-display: swap`);没有加载时按字体栈回退。
|
|
99
|
+
|
|
100
|
+
动效(D26):`--console-motion-fast` 120ms、`--console-motion-base` 200ms、`--console-motion-slow` 280ms,缓动统一 `--console-ease-out`;Tailwind 的 `transition-*` 默认也用它们。`styles.css` 在根上设置 `font-variant-numeric: tabular-nums`,数字等宽。
|
|
101
|
+
|
|
102
|
+
旧名(`--console-duration-fast`、`--console-duration-page`、`--console-radius-sm/md/lg/xl/2xl`、`--console-shadow-*`、`--console-space-page-x/-y`、`--console-space-section/-stack/-card(-sm)`、`--console-control-height-sm/-lg`、`--console-border-width`、`--console-focus-width`、`--console-text-caption/-code/-body-sm/-section-sm/-title-compact`、`--radius`)在 P4 之前作为别名保留。
|
|
103
|
+
|
|
104
|
+
Tailwind 主题(`theme.css`):`p-*` / `m-*` / `gap-*` / `space-*` 只有 `0`、`px`、`1`、`2`、`3`、`4`、`6`、`8`、`12`、`16`(`space-5` 对应 `p-6`);尺寸类(`w` / `h` / `size` / `inset` / `min-*` / `max-*` / `translate` / `basis`)保留 Tailwind 的数字键,另有 `control`、`control-compact`、`touch`、`touch-min`、`badge`;`text-*` 只有五个字号,`font-*` 只有三个字重,`rounded-*` 为 `0`–`4`、`full` 和语义键(`control`、`card`、`badge`、`popover`、`dialog` 等),`shadow-*` 为 `e1`–`e3` 和语义键,断点 `sm` / `md` / `lg` / `xl`,颜色只有主题色。
|
|
105
|
+
|
|
106
|
+
## 约束工具(ADR 0063 D20,可在 zhinjs/console 复用)
|
|
107
|
+
|
|
108
|
+
```js
|
|
109
|
+
// stylelint.config.mjs —— 只允许令牌与尺度内取值;@media 只在外壳文件
|
|
110
|
+
import { createConsoleStylelintConfig } from '@zhin.js/console-ui/stylelint';
|
|
111
|
+
export default createConsoleStylelintConfig({ shellFiles: ['src/shell\\.css$'] });
|
|
112
|
+
|
|
113
|
+
// eslint.config.mjs —— 禁任意值类、尺度外类名、原生 <button>/<input>/<select>/<textarea>/<table>/<dialog>
|
|
114
|
+
import consoleUi from '@zhin.js/console-ui/eslint';
|
|
115
|
+
export default [{ files: ['**/*.tsx'], ...consoleUi.configs.recommended }];
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
- `console/scale-values`、`console/no-unknown-tokens`、`console/no-deprecated-tokens`、`console/media-queries`、`console/motion-tokens`(stylelint 插件 `@zhin.js/console-ui/stylelint-plugin`;`motion-tokens` 禁止 `transition` / `animation` 写死时长或缓动,迁移期间可用 `createConsoleStylelintConfig({ motionTokens: 'warning' })` 降级);
|
|
119
|
+
- `console-ui/no-arbitrary-values`、`console-ui/no-off-scale-classes`、`console-ui/no-native-controls`(ESLint);判定逻辑在 `@zhin.js/console-ui/tailwind-classes` 的 `classifyClass()`,`zhin plugin check` 可直接复用。
|
|
120
|
+
|
|
121
|
+
本包自己:`pnpm --filter @zhin.js/console-ui lint:css`(stylelint + 生成物核对,根命令 `pnpm check:console-ui-styles`);ESLint 规则在根 `eslint.config.mjs` 中对 `packages/console/ui/**` 生效(`components/ui/**` 的基础组件本身包装原生元素,不查 `no-native-controls`)。
|
|
122
|
+
|
|
123
|
+
## 布局审计(ADR 0063 D20 第 3 条)
|
|
124
|
+
|
|
125
|
+
`@zhin.js/console-ui/audit`(Node 侧,需要可选 peer `@playwright/test` 与 `esbuild`):
|
|
126
|
+
|
|
127
|
+
- `auditPage(page, options)`:对 Playwright 当前页面逐个元素读取计算样式,返回 `{ violations, exemptions }`;
|
|
128
|
+
- `runLayoutAudit(page, { open })`:在 375 / 768 / 1280 / 1920 × 亮 / 暗下运行;
|
|
129
|
+
- `auditPluginPages({ repoRoot, widths, themes, plugins })`:把插件的 `pages/<名>/index.tsx` 和本包的外壳(`PageShell` + `PageHeader`)一起打包,用 Chromium 打开并审计(`pnpm check:plugin-ui-audit` 使用它)。手写 React 页面直接挂载;声明式蓝图、适配器页和评论审批页由 Console 渲染器渲染,需要在请求里传 `mountModule`(导出 `mountPluginPage(context)` 的模块,见 `audit/mount-page.jsx`),否则返回 `mounted: false` 与 `skipped` 原因、不出违规。
|
|
130
|
+
- `formatAuditReport(report)`:文字摘要。
|
|
131
|
+
|
|
132
|
+
检查项 id:`type-scale`、`spacing`、`radius`、`border`、`shadow`、`consistency`(按 `data-slot` 分组,同一宽度只有一种圆角 / 边框 / 阴影)、`overflow`、`touch-target`、`edge-card`、`static-card`、`bottom-drawer`、`content-width`、`duplicate-text`、`focus-visible`、`contrast`、`shell-overlap`,以及 `auditPluginPages` 的 `mount`(页面构建或渲染失败)。豁免:在元素上写 `data-zhin-ui-ignore="<检查项>[,<检查项>…]: <理由>"`,对该元素及子元素生效,结果的 `exemptions` 列出每一条。
|
|
133
|
+
|
|
134
|
+
本包的组件示例页是门禁:`pnpm --filter @zhin.js/console-ui test:audit`(根命令 `pnpm check:console-ui-audit`,在 Full validation 中运行),四个宽度 × 两种主题全项通过,并在 375px 打开下拉、「更多」菜单和对话框检查底部抽屉;Console 和插件页面先只出报告。
|
|
135
|
+
|
|
136
|
+
## 语言
|
|
137
|
+
|
|
138
|
+
组件不读任何宿主的 i18n。没有 Provider 时使用 zh-CN 默认文案;宿主注入当前语言和可选的覆盖文案:
|
|
139
|
+
|
|
140
|
+
```tsx
|
|
141
|
+
import { ConsoleUiI18nProvider } from '@zhin.js/console-ui';
|
|
142
|
+
|
|
143
|
+
<ConsoleUiI18nProvider locale={locale} messages={{ 'error.retry': '再试一次' }}>
|
|
144
|
+
{children}
|
|
145
|
+
</ConsoleUiI18nProvider>
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`locale` 接受任意 BCP 47 标签(`zh*` → zh-CN,`en*` → en,其余 → zh-CN);`messages` 的键见 `CONSOLE_UI_MESSAGES`。
|
|
149
|
+
|
|
150
|
+
## 刷新控件与页头操作
|
|
151
|
+
|
|
152
|
+
`RefreshControl`:「更新于 hh:mm:ss」+ 自动刷新间隔(Radix 下拉:手动 / 5s / 15s / 30s)+ 刷新按钮。`onRefresh` 返回 Promise 时,按钮在完成前保持忙碌;自动刷新在标签页隐藏或上一次刷新未结束时跳过。
|
|
153
|
+
|
|
154
|
+
手写页面不画自己的页头,而是把操作交给外壳:
|
|
155
|
+
|
|
156
|
+
```tsx
|
|
157
|
+
import { Button, usePageChrome } from '@zhin.js/console-ui';
|
|
158
|
+
|
|
159
|
+
export default function Feeds() {
|
|
160
|
+
const hosted = usePageChrome({
|
|
161
|
+
actions: <Button variant="destructive-outline">移除订阅</Button>,
|
|
162
|
+
refresh: { onRefresh: reload, updatedAt },
|
|
163
|
+
});
|
|
164
|
+
// hosted === false:外层没有外壳(例如旧版 Console),页面可以自己画这些控件
|
|
165
|
+
return <FeedTable />;
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
外壳为每个页面槽创建一个 `createPageChromeStore()`,用 `<PageChromeProvider store>` 包住页面,并在 `PageHeader` 的 `actions` 里放 `<PageChromeActions store />`。`usePageChrome` 还接受 `menuActions`(有文字的操作:页头够宽时是按钮,窄于 40rem 时收进「更多」)和 `moreActions`(始终在「更多」里)。`usePageChromeState(store)` 还能读到页面上报的 `title` / `description`(声明式页面的标题与说明),外壳已有自己的标题区时可以只用作页签名。`RefreshControl` 的 `onAutoRefresh` 用于自动刷新与手动「刷新」做的事不同的页面(例如手动刷新才解除「请先刷新」的锁定)。
|
|
170
|
+
|
|
171
|
+
## 内容区块
|
|
172
|
+
|
|
173
|
+
外壳负责页头,页面只放内容。内容区块补充 P1b 的布局组件而不重复它们:分区用 `Section`,网格用 `Grid`(统计卡片用 `StatGrid` + `StatCard`,`StatCard` 可带 `unit`、`badge`、`footer`),表格用 `Table`(自身宽度小于 40rem 时每行变卡片)。区块按**所在 `.console-cq` 容器**的宽度切换布局(`@container console`,不看视口),只用语义令牌:`KeyValueList` 在窄容器里一列;`RecordCard` 是 `Card` + 一列 `KeyValueList`,用于账号、连接这类记录卡片;`Disclosure` 默认收起,用于原始 ID、JSON 这类默认不显示的内容(D15、D18);`LoadingBlock` 是带 `role="status"` 的骨架行。
|
|
174
|
+
|
|
175
|
+
## 共享模块版本
|
|
176
|
+
|
|
177
|
+
Console 入口在加载插件入口前登记本包:
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
import * as ConsoleUi from '@zhin.js/console-ui';
|
|
181
|
+
ConsoleUi.registerConsoleUiSharedModule(ConsoleUi, sharedModules); // sharedModules: globalThis.__ZHIN_CONSOLE_SHARED_MODULES__
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
它把模块放进 `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 这份没有的具名导出会按名字报出,调用时抛错。
|
|
185
|
+
|
|
186
|
+
## 开发
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
pnpm --filter @zhin.js/console-ui build # 生成令牌 + tsc + Tailwind 编译 dist/styles.css、tokens.css、theme.css、scale.json、exports.json
|
|
190
|
+
pnpm vitest run packages/console/ui # 单元测试(含令牌、lint 规则、颜色对比度与图表色 ΔE)
|
|
191
|
+
pnpm --filter @zhin.js/console-ui lint:css # stylelint + 生成物核对
|
|
192
|
+
pnpm --filter @zhin.js/console-ui test:visual # Playwright 视觉回归(亮 / 暗,1280 与 375,先 build)
|
|
193
|
+
pnpm --filter @zhin.js/console-ui test:audit # 布局审计门禁(先 build)
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
视觉回归打开 `visual/demo.tsx` 的组件示例页(引入 `dist/styles.css`,示例页自己的布局类用 `dist/theme.css` 编译),对页面外壳、按钮、输入框、下拉框、表格和对话框截图比对,并在 375px 检查「更多」菜单、表格变卡片和底部抽屉。基线依赖本机字体;本机已装其它版本的 Chromium 时,用 `PLAYWRIGHT_CHROMIUM_EXECUTABLE` 指过去。改了外观要用 `--update-snapshots` 更新基线并逐张评审。
|
package/audit/index.mjs
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@zhin.js/console-ui/audit` — the Playwright layout audit of ADR 0063 D20 (Node side).
|
|
3
|
+
*
|
|
4
|
+
* auditPage(page, options) audit the page a Playwright `Page` shows now
|
|
5
|
+
* runLayoutAudit(page, options) the same over 375 / 768 / 1280 / 1920 × light / dark
|
|
6
|
+
* auditPluginPages(request) mount plugin pages and audit them (used by `pnpm check:plugin-ui-audit`)
|
|
7
|
+
* formatAuditReport(report) text summary
|
|
8
|
+
*
|
|
9
|
+
* Check ids: AUDIT_CHECKS (plus `mount` from auditPluginPages). Exemptions:
|
|
10
|
+
* `data-zhin-ui-ignore="<check>[,<check>…]: <reason>"` on an element covers it and its subtree.
|
|
11
|
+
*/
|
|
12
|
+
export {
|
|
13
|
+
AUDIT_CHECKS,
|
|
14
|
+
AUDIT_THEMES,
|
|
15
|
+
AUDIT_WIDTHS,
|
|
16
|
+
auditPage,
|
|
17
|
+
formatAuditReport,
|
|
18
|
+
runLayoutAudit,
|
|
19
|
+
setConsoleTheme,
|
|
20
|
+
} from './layout-audit.mjs';
|
|
21
|
+
export { auditPluginPages } from './plugin-pages.mjs';
|