@zhin.js/console-contract 1.1.4 → 1.1.6

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/lib/page.d.ts CHANGED
@@ -1,3 +1,13 @@
1
+ /**
2
+ * Console navigation sections (ADR 0052); a Page declares which one its entry belongs to.
3
+ * Kept dependency-free here; `tests/contracts/console-page-sections.test.ts` keeps it equal
4
+ * to the wire vocabulary in `@zhin.js/console-protocol`.
5
+ */
6
+ export declare const CONSOLE_PAGE_SECTIONS: readonly ["overview", "conversations", "features", "plugins", "ops", "access"];
7
+ export type ConsolePageSection = (typeof CONSOLE_PAGE_SECTIONS)[number];
8
+ export declare function isConsolePageSection(value: unknown): value is ConsolePageSection;
9
+ /** Validates an optional `section`; throws for anything outside {@link CONSOLE_PAGE_SECTIONS}. */
10
+ export declare function optionalPageSection(value: unknown): ConsolePageSection | undefined;
1
11
  export interface PageMetadata {
2
12
  readonly title?: string;
3
13
  /** Explicit display titles; missing locales retain title. */
@@ -7,6 +17,13 @@ export interface PageMetadata {
7
17
  readonly hideInNav?: boolean;
8
18
  readonly requiredPermissions?: readonly string[];
9
19
  readonly requiredRoles?: readonly string[];
20
+ /** Presentation hints carried through to the Console entry projection. */
21
+ readonly description?: string;
22
+ readonly group?: string;
23
+ readonly parent?: string;
24
+ readonly fullWidth?: boolean;
25
+ /** Console navigation section (ADR 0052); omitted → the Console's default for plugin pages. */
26
+ readonly section?: ConsolePageSection;
10
27
  }
11
28
  export interface NormalizedPageMetadata {
12
29
  readonly title: string;
@@ -49,6 +66,42 @@ export type DeclarativeButtonVariant = 'primary' | 'secondary' | 'ghost' | 'dang
49
66
  export type DeclarativeUiLocale = 'zh-CN' | 'en';
50
67
  /** Framework-agnostic renderable value (string, number, boolean, null, undefined, or JSX/ReactNode in browser). */
51
68
  export type DeclarativeRenderable = unknown;
69
+ /**
70
+ * Pure JSON-serializable expression descriptor for zero-closure Server-Driven Blueprints.
71
+ * Can be evaluated identically in Web Console, IM Card projection, and CLI TUI panels.
72
+ */
73
+ export type DeclarativeValueExpr = {
74
+ readonly $path: string;
75
+ readonly fallback?: string | number | boolean;
76
+ } | {
77
+ readonly $count: string;
78
+ } | {
79
+ readonly $sum: {
80
+ readonly path: string;
81
+ readonly field: string;
82
+ };
83
+ } | {
84
+ readonly $format: DeclarativeI18nText;
85
+ readonly args: readonly string[];
86
+ } | {
87
+ readonly $map: {
88
+ readonly path: string;
89
+ readonly cases: Readonly<Record<string, DeclarativeI18nText>>;
90
+ readonly default?: DeclarativeI18nText;
91
+ };
92
+ } | {
93
+ readonly $join: {
94
+ readonly path: string;
95
+ readonly sep?: string;
96
+ readonly empty?: DeclarativeI18nText;
97
+ };
98
+ } | {
99
+ readonly $coalesce: readonly string[];
100
+ readonly fallback?: string | number | boolean;
101
+ };
102
+ export declare function isDeclarativeValueExpr(value: unknown): value is DeclarativeValueExpr;
103
+ export declare function resolveDataPath(data: unknown, path: string): unknown;
104
+ export declare function evaluateDeclarativeValue(exprOrKey: unknown, data: unknown, locale?: DeclarativeUiLocale): unknown;
52
105
  export interface DeclarativePageContext<TData = Record<string, unknown>> {
53
106
  readonly pluginId: string;
54
107
  readonly locale: DeclarativeUiLocale;
@@ -68,22 +121,46 @@ export interface DeclarativePageContext<TData = Record<string, unknown>> {
68
121
  }
69
122
  export interface DeclarativeBadgeSpec<TData = Record<string, unknown>> {
70
123
  readonly key?: string;
71
- readonly label: DeclarativeI18nText | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
72
- readonly tone?: DeclarativeBadgeTone | ((data: TData) => DeclarativeBadgeTone);
124
+ readonly label: DeclarativeI18nText | DeclarativeValueExpr | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
125
+ readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr | ((data: TData) => DeclarativeBadgeTone);
73
126
  }
74
127
  export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
75
128
  readonly key?: string;
76
129
  readonly label: DeclarativeI18nText;
77
- readonly value: (keyof TData & string) | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
78
- readonly hint?: DeclarativeI18nText | ((data: TData) => DeclarativeRenderable);
130
+ readonly value: (keyof TData & string) | string | DeclarativeValueExpr | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
131
+ readonly unit?: DeclarativeI18nText;
132
+ readonly icon?: DeclarativeRenderable;
133
+ readonly image?: string;
134
+ readonly watermark?: DeclarativeRenderable | string;
135
+ readonly tone?: DeclarativeBadgeTone | 'primary';
136
+ readonly progress?: number | string | DeclarativeValueExpr;
137
+ readonly sparkline?: string;
138
+ readonly trend?: {
139
+ readonly value: DeclarativeI18nText | DeclarativeValueExpr;
140
+ readonly direction?: 'up' | 'down' | 'flat';
141
+ };
142
+ readonly hint?: DeclarativeI18nText | DeclarativeValueExpr | ((data: TData) => DeclarativeRenderable);
79
143
  readonly badge?: {
80
- readonly label: DeclarativeI18nText | ((data: TData) => DeclarativeRenderable);
81
- readonly tone?: DeclarativeBadgeTone | ((data: TData) => DeclarativeBadgeTone);
144
+ readonly label: DeclarativeI18nText | DeclarativeValueExpr | ((data: TData) => DeclarativeRenderable);
145
+ readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr | ((data: TData) => DeclarativeBadgeTone);
82
146
  };
83
147
  }
84
148
  export interface DeclarativeActionFieldSpec {
85
149
  readonly key: string;
86
150
  readonly label: DeclarativeI18nText;
151
+ readonly type?: 'text' | 'password' | 'number' | 'textarea' | 'select' | 'switch' | 'radio' | 'checkbox-group' | 'segmented';
152
+ readonly options?: readonly {
153
+ readonly value: string;
154
+ readonly label: DeclarativeI18nText;
155
+ readonly description?: DeclarativeI18nText;
156
+ readonly icon?: DeclarativeRenderable;
157
+ readonly badge?: DeclarativeRenderable;
158
+ readonly disabled?: boolean;
159
+ }[];
160
+ readonly variant?: 'default' | 'card' | 'button';
161
+ readonly direction?: 'column' | 'row' | 'grid';
162
+ readonly hint?: DeclarativeI18nText;
163
+ readonly rows?: number;
87
164
  readonly placeholder?: string;
88
165
  readonly required?: boolean;
89
166
  readonly defaultValue?: string;
@@ -94,6 +171,7 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
94
171
  readonly name: string;
95
172
  readonly label: DeclarativeI18nText;
96
173
  readonly description?: DeclarativeI18nText;
174
+ readonly icon?: DeclarativeRenderable;
97
175
  readonly variant?: DeclarativeButtonVariant;
98
176
  readonly confirm?: DeclarativeI18nText;
99
177
  readonly confirmLabel?: DeclarativeI18nText;
@@ -102,16 +180,61 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
102
180
  readonly disabled?: boolean | ((data: TData | undefined) => boolean);
103
181
  readonly successMessage?: DeclarativeI18nText;
104
182
  }
183
+ export type DeclarativeColumnType = 'auto' | 'text' | 'code' | 'badge' | 'boolean' | 'link' | 'datetime' | 'number' | 'progress' | 'tags' | 'json';
105
184
  export interface DeclarativeColumnSpec<TRow = Record<string, unknown>, TData = Record<string, unknown>> {
106
185
  readonly key: keyof TRow & string;
107
186
  readonly label: DeclarativeI18nText;
187
+ readonly icon?: DeclarativeRenderable;
188
+ readonly type?: DeclarativeColumnType;
189
+ readonly align?: 'left' | 'center' | 'right';
190
+ readonly fixed?: 'left' | 'right';
191
+ readonly sortable?: boolean;
192
+ readonly copyable?: boolean;
193
+ readonly width?: string | number;
194
+ readonly toneMap?: Readonly<Record<string, DeclarativeBadgeTone>>;
108
195
  readonly render?: (value: unknown, row: TRow, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable;
109
196
  }
197
+ export interface DeclarativeBatchActionSpec<TRow = Record<string, unknown>, TData = Record<string, unknown>> {
198
+ readonly name: string;
199
+ readonly label: DeclarativeI18nText;
200
+ readonly icon?: DeclarativeRenderable;
201
+ readonly variant?: DeclarativeButtonVariant;
202
+ readonly confirm?: DeclarativeI18nText;
203
+ readonly confirmLabel?: DeclarativeI18nText;
204
+ readonly idsParamKey?: string;
205
+ readonly params?: (selectedRows: readonly TRow[], selectedKeys: readonly string[], data: TData | undefined) => Readonly<Record<string, unknown>>;
206
+ readonly onExecute?: (selectedRows: readonly TRow[], selectedKeys: readonly string[], ctx: DeclarativePageContext<TData>) => unknown;
207
+ readonly successMessage?: DeclarativeI18nText;
208
+ }
209
+ export interface DeclarativeRowActionSpec<TRow = Record<string, unknown>, TData = Record<string, unknown>> {
210
+ readonly name: string;
211
+ readonly label: DeclarativeI18nText;
212
+ readonly icon?: DeclarativeRenderable;
213
+ readonly variant?: DeclarativeButtonVariant;
214
+ readonly confirm?: DeclarativeI18nText;
215
+ readonly confirmLabel?: DeclarativeI18nText;
216
+ readonly idParamKey?: string;
217
+ readonly params?: (row: TRow, rowKey: string, data: TData | undefined) => Readonly<Record<string, unknown>>;
218
+ readonly onExecute?: (row: TRow, rowKey: string, ctx: DeclarativePageContext<TData>) => unknown;
219
+ readonly disabled?: boolean | ((row: TRow) => boolean);
220
+ readonly successMessage?: DeclarativeI18nText;
221
+ }
110
222
  export interface DeclarativeSectionSpec<TData = Record<string, unknown>, TRow = Record<string, unknown>> {
111
223
  readonly id?: string;
112
224
  readonly title?: DeclarativeI18nText;
113
225
  readonly description?: DeclarativeI18nText;
226
+ readonly tab?: DeclarativeI18nText;
227
+ readonly layout?: 'table' | 'cards' | 'kv' | 'timeline' | 'json';
228
+ readonly columnsCount?: 1 | 2 | 3;
229
+ readonly collapsible?: boolean;
230
+ readonly defaultCollapsed?: boolean;
114
231
  readonly emptyText?: DeclarativeI18nText;
232
+ readonly rowKey?: keyof TRow & string;
233
+ readonly selectable?: boolean;
234
+ readonly batchActions?: readonly DeclarativeBatchActionSpec<TRow, TData>[];
235
+ readonly rowActions?: readonly DeclarativeRowActionSpec<TRow, TData>[];
236
+ readonly renderExpandedRow?: (row: TRow, index: number, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable;
237
+ readonly responsiveStack?: boolean;
115
238
  /** Extract rows for a declarative table or list. */
116
239
  readonly items?: (keyof TData & string) | ((data: TData) => readonly TRow[]);
117
240
  /** Columns for a declarative table/card list when `items` is provided. */
@@ -119,10 +242,14 @@ export interface DeclarativeSectionSpec<TData = Record<string, unknown>, TRow =
119
242
  /** Custom row renderer when `items` is provided. */
120
243
  readonly renderItem?: (item: TRow, index: number, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable;
121
244
  /** Key-value description list extractor (`<dl className="zk-dl">`). */
122
- readonly entries?: (data: TData, ctx: DeclarativePageContext<TData>) => Readonly<Record<string, DeclarativeRenderable>> | readonly {
245
+ readonly entries?: readonly {
246
+ readonly label: DeclarativeI18nText;
247
+ readonly value?: DeclarativeRenderable | DeclarativeValueExpr;
248
+ readonly dataKey?: string;
249
+ }[] | ((data: TData, ctx: DeclarativePageContext<TData>) => Readonly<Record<string, DeclarativeRenderable>> | readonly {
123
250
  readonly label: DeclarativeRenderable;
124
251
  readonly value: DeclarativeRenderable;
125
- }[];
252
+ }[]);
126
253
  /** Custom section body renderer. */
127
254
  readonly render?: (data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable;
128
255
  }
@@ -165,6 +292,7 @@ export type ConsolePageBlueprintSection = {
165
292
  readonly value?: unknown;
166
293
  readonly suffix?: string;
167
294
  readonly dataKey?: string;
295
+ readonly expr?: DeclarativeValueExpr;
168
296
  }[];
169
297
  } | {
170
298
  readonly type: 'table';
@@ -180,6 +308,12 @@ export type ConsolePageBlueprintSection = {
180
308
  readonly type: 'entries';
181
309
  readonly id: string;
182
310
  readonly title: string;
311
+ readonly entries?: readonly {
312
+ readonly label: string;
313
+ readonly value: string;
314
+ readonly dataKey?: string;
315
+ readonly expr?: DeclarativeValueExpr;
316
+ }[];
183
317
  } | {
184
318
  readonly type: 'actions';
185
319
  readonly id: string;
@@ -190,6 +324,12 @@ export type ConsolePageBlueprintSection = {
190
324
  readonly name?: string;
191
325
  readonly description?: string;
192
326
  readonly variant?: DeclarativeButtonVariant;
327
+ readonly confirm?: DeclarativeI18nText;
328
+ readonly confirmLabel?: DeclarativeI18nText;
329
+ readonly fields?: readonly DeclarativeActionFieldSpec[];
330
+ readonly params?: DeclarativeActionSpec<any>['params'];
331
+ readonly disabled?: DeclarativeActionSpec<any>['disabled'];
332
+ readonly successMessage?: DeclarativeI18nText;
193
333
  }[];
194
334
  } | {
195
335
  readonly type: 'markdown';
package/lib/page.js CHANGED
@@ -1,3 +1,23 @@
1
+ /**
2
+ * Console navigation sections (ADR 0052); a Page declares which one its entry belongs to.
3
+ * Kept dependency-free here; `tests/contracts/console-page-sections.test.ts` keeps it equal
4
+ * to the wire vocabulary in `@zhin.js/console-protocol`.
5
+ */
6
+ export const CONSOLE_PAGE_SECTIONS = Object.freeze([
7
+ 'overview', 'conversations', 'features', 'plugins', 'ops', 'access',
8
+ ]);
9
+ export function isConsolePageSection(value) {
10
+ return typeof value === 'string' && CONSOLE_PAGE_SECTIONS.includes(value);
11
+ }
12
+ /** Validates an optional `section`; throws for anything outside {@link CONSOLE_PAGE_SECTIONS}. */
13
+ export function optionalPageSection(value) {
14
+ if (value === undefined)
15
+ return undefined;
16
+ if (!isConsolePageSection(value)) {
17
+ throw new TypeError(`Page section must be one of ${CONSOLE_PAGE_SECTIONS.join(', ')}`);
18
+ }
19
+ return value;
20
+ }
1
21
  export function normalizeClientModuleArtifact(value, label) {
2
22
  const input = requireRecord(value, label);
3
23
  const module = optionalString(input.module, `${label} module`);
@@ -13,13 +33,31 @@ export function normalizeClientModuleArtifact(value, label) {
13
33
  });
14
34
  }
15
35
  export function isConsoleBlueprint(value) {
16
- if (!value || typeof value !== 'object')
36
+ if (!value || (typeof value !== 'object' && typeof value !== 'function'))
17
37
  return false;
18
38
  const kind = value.kind;
19
39
  return kind === 'zhin.console.page-blueprint' || kind === 'zhin.console.adapter-page';
20
40
  }
21
41
  export function definePage(metadata = {}) {
22
- return normalizePageInput(metadata);
42
+ // Same optional keys as `@zhin.js/page`; anything else is still rejected below.
43
+ const { description, group, parent, fullWidth, section: rawSection, ...base } = requireRecord(metadata, 'Page metadata');
44
+ const section = optionalPageSection(rawSection);
45
+ for (const [key, value] of [['description', description], ['group', group], ['parent', parent]]) {
46
+ if (value !== undefined && (typeof value !== 'string' || !value.trim())) {
47
+ throw new TypeError(`Page ${key} must be a non-empty string`);
48
+ }
49
+ }
50
+ if (fullWidth !== undefined && typeof fullWidth !== 'boolean') {
51
+ throw new TypeError('Page fullWidth must be boolean');
52
+ }
53
+ return Object.freeze({
54
+ ...normalizePageInput(base),
55
+ ...(description !== undefined ? { description: description } : {}),
56
+ ...(group !== undefined ? { group: group } : {}),
57
+ ...(parent !== undefined ? { parent: parent } : {}),
58
+ ...(fullWidth !== undefined ? { fullWidth } : {}),
59
+ ...(section !== undefined ? { section } : {}),
60
+ });
23
61
  }
24
62
  export function normalizePageMetadata(localName, metadata) {
25
63
  assertPageLocalName(localName);
@@ -141,6 +179,122 @@ function pageTitleTranslations(value) {
141
179
  }
142
180
  return Object.freeze(output);
143
181
  }
182
+ export function isDeclarativeValueExpr(value) {
183
+ if (!value || typeof value !== 'object' || Array.isArray(value))
184
+ return false;
185
+ const rec = value;
186
+ return (typeof rec.$path === 'string' ||
187
+ typeof rec.$count === 'string' ||
188
+ (rec.$sum !== null && typeof rec.$sum === 'object') ||
189
+ (rec.$format !== undefined && Array.isArray(rec.$args ?? rec.args)) ||
190
+ (rec.$map !== null && typeof rec.$map === 'object') ||
191
+ (rec.$join !== null && typeof rec.$join === 'object') ||
192
+ Array.isArray(rec.$coalesce));
193
+ }
194
+ export function resolveDataPath(data, path) {
195
+ if (!data || typeof data !== 'object' || !path)
196
+ return undefined;
197
+ const record = data;
198
+ if (Object.prototype.hasOwnProperty.call(record, path))
199
+ return record[path];
200
+ const segments = path.split('.').filter(Boolean);
201
+ let cursor = data;
202
+ for (const seg of segments) {
203
+ if (cursor === null || cursor === undefined)
204
+ return undefined;
205
+ if (Array.isArray(cursor) && seg === 'length')
206
+ return cursor.length;
207
+ if (typeof cursor !== 'object')
208
+ return undefined;
209
+ cursor = Object.prototype.hasOwnProperty.call(cursor, seg)
210
+ ? cursor[seg]
211
+ : undefined;
212
+ }
213
+ return cursor;
214
+ }
215
+ export function evaluateDeclarativeValue(exprOrKey, data, locale = 'en') {
216
+ if (exprOrKey === null || exprOrKey === undefined)
217
+ return undefined;
218
+ if (typeof exprOrKey === 'string') {
219
+ return resolveDataPath(data, exprOrKey);
220
+ }
221
+ if (!isDeclarativeValueExpr(exprOrKey)) {
222
+ return exprOrKey;
223
+ }
224
+ const rec = exprOrKey;
225
+ if (typeof rec.$path === 'string') {
226
+ const val = resolveDataPath(data, rec.$path);
227
+ return val !== undefined && val !== null && val !== '' ? val : rec.fallback;
228
+ }
229
+ if (typeof rec.$count === 'string') {
230
+ const target = resolveDataPath(data, rec.$count);
231
+ if (Array.isArray(target))
232
+ return target.length;
233
+ if (target && typeof target === 'object')
234
+ return Object.keys(target).length;
235
+ return typeof target === 'number' ? target : 0;
236
+ }
237
+ if (rec.$sum && typeof rec.$sum === 'object') {
238
+ const sumSpec = rec.$sum;
239
+ const list = sumSpec.path ? resolveDataPath(data, sumSpec.path) : undefined;
240
+ if (!Array.isArray(list) || !sumSpec.field)
241
+ return 0;
242
+ return list.reduce((acc, item) => {
243
+ let raw = resolveDataPath(item, sumSpec.field);
244
+ if (raw === undefined && sumSpec.field === 'pendingCount') {
245
+ raw = resolveDataPath(item, 'drafts.length');
246
+ }
247
+ const n = Number(raw);
248
+ return acc + (Number.isFinite(n) ? n : 0);
249
+ }, 0);
250
+ }
251
+ const formatArgs = Array.isArray(rec.args)
252
+ ? rec.args
253
+ : Array.isArray(rec.$args)
254
+ ? rec.$args
255
+ : undefined;
256
+ if (rec.$format !== undefined && formatArgs) {
257
+ const template = resolveDeclarativeText(rec.$format, locale);
258
+ const args = formatArgs.map((p) => resolveDataPath(data, p));
259
+ if (args.length > 0 && args.every((v) => v === undefined || v === null || v === '')) {
260
+ return undefined;
261
+ }
262
+ return template.replace(/\{(\d+)\}/gu, (_m, idx) => {
263
+ const v = args[Number(idx)];
264
+ return v === undefined || v === null ? '' : String(v);
265
+ });
266
+ }
267
+ if (rec.$map && typeof rec.$map === 'object') {
268
+ const mapSpec = rec.$map;
269
+ const rawVal = mapSpec.path ? resolveDataPath(data, mapSpec.path) : undefined;
270
+ if (rawVal !== undefined && rawVal !== null && mapSpec.cases) {
271
+ const key = String(rawVal);
272
+ if (Object.prototype.hasOwnProperty.call(mapSpec.cases, key)) {
273
+ return resolveDeclarativeText(mapSpec.cases[key], locale);
274
+ }
275
+ }
276
+ if (mapSpec.default !== undefined)
277
+ return resolveDeclarativeText(mapSpec.default, locale);
278
+ return rawVal;
279
+ }
280
+ if (rec.$join && typeof rec.$join === 'object') {
281
+ const joinSpec = rec.$join;
282
+ const list = joinSpec.path ? resolveDataPath(data, joinSpec.path) : undefined;
283
+ if (!Array.isArray(list) || list.length === 0) {
284
+ return joinSpec.empty !== undefined ? resolveDeclarativeText(joinSpec.empty, locale) : '—';
285
+ }
286
+ return list.map((item) => String(item ?? '')).join(joinSpec.sep ?? ', ');
287
+ }
288
+ if (Array.isArray(rec.$coalesce)) {
289
+ for (const candidate of rec.$coalesce) {
290
+ const val = resolveDataPath(data, candidate);
291
+ if (val !== undefined && val !== null && val !== '')
292
+ return val;
293
+ }
294
+ return rec.fallback;
295
+ }
296
+ return undefined;
297
+ }
144
298
  export function resolveDeclarativeText(text, preferredLocale = 'en') {
145
299
  if (!text)
146
300
  return '';
@@ -163,6 +317,7 @@ export function buildBlueprintFromSpec(input) {
163
317
  dataSource: Object.freeze({ action: bp.dataSource?.action ?? 'status' }),
164
318
  sections: Object.freeze([...(bp.sections ?? [])]),
165
319
  ...(bp.spec !== undefined ? { spec: bp.spec } : {}),
320
+ ...(bp.reviewSpec !== undefined ? { reviewSpec: bp.reviewSpec } : {}),
166
321
  });
167
322
  }
168
323
  const spec = input;
@@ -185,6 +340,7 @@ export function buildBlueprintFromSpec(input) {
185
340
  key: stat.key ?? (typeof stat.value === 'string' ? stat.value : `stat-${idx}`),
186
341
  label: resolveDeclarativeText(stat.label, 'en'),
187
342
  ...(typeof stat.value === 'string' ? { dataKey: stat.value } : {}),
343
+ ...(isDeclarativeValueExpr(stat.value) ? { expr: stat.value } : {}),
188
344
  }))),
189
345
  }));
190
346
  }
@@ -192,12 +348,13 @@ export function buildBlueprintFromSpec(input) {
192
348
  const id = sec.id ?? `section-${idx}`;
193
349
  const secTitle = resolveDeclarativeText(sec.title, 'en');
194
350
  if (sec.columns !== undefined || sec.items !== undefined) {
351
+ const preferredRowKey = sec.columns?.find((c) => c.key === 'id' || c.key === 'key' || c.key === 'ownerKey')?.key ?? 'id';
195
352
  sections.push(Object.freeze({
196
353
  type: 'table',
197
354
  id,
198
355
  title: secTitle,
199
356
  ...(typeof sec.items === 'string' ? { dataKey: sec.items } : {}),
200
- rowKey: sec.columns?.[0]?.key ?? 'id',
357
+ rowKey: preferredRowKey,
201
358
  columns: Object.freeze((sec.columns ?? []).map((col) => Object.freeze({
202
359
  key: col.key,
203
360
  label: resolveDeclarativeText(col.label, 'en'),
@@ -209,6 +366,23 @@ export function buildBlueprintFromSpec(input) {
209
366
  type: 'entries',
210
367
  id,
211
368
  title: secTitle,
369
+ ...(Array.isArray(sec.entries)
370
+ ? {
371
+ entries: Object.freeze(sec.entries.map((e) => {
372
+ const inferredDataKey = e.dataKey ??
373
+ (isDeclarativeValueExpr(e.value) &&
374
+ typeof e.value.$path === 'string'
375
+ ? e.value.$path
376
+ : undefined);
377
+ return Object.freeze({
378
+ label: resolveDeclarativeText(e.label, 'en'),
379
+ value: isDeclarativeValueExpr(e.value) ? '' : String(e.value ?? ''),
380
+ ...(inferredDataKey ? { dataKey: inferredDataKey } : {}),
381
+ ...(isDeclarativeValueExpr(e.value) ? { expr: e.value } : {}),
382
+ });
383
+ })),
384
+ }
385
+ : {}),
212
386
  }));
213
387
  }
214
388
  else {
@@ -232,9 +406,16 @@ export function buildBlueprintFromSpec(input) {
232
406
  ? { description: resolveDeclarativeText(act.description, 'en') }
233
407
  : {}),
234
408
  ...(act.variant ? { variant: act.variant } : {}),
409
+ ...(act.confirm !== undefined ? { confirm: act.confirm } : {}),
410
+ ...(act.confirmLabel !== undefined ? { confirmLabel: act.confirmLabel } : {}),
411
+ ...(act.fields !== undefined ? { fields: act.fields } : {}),
412
+ ...(act.params !== undefined ? { params: act.params } : {}),
413
+ ...(act.disabled !== undefined ? { disabled: act.disabled } : {}),
414
+ ...(act.successMessage !== undefined ? { successMessage: act.successMessage } : {}),
235
415
  }))),
236
416
  }));
237
417
  }
418
+ const rawReviewSpec = spec.reviewSpec;
238
419
  return Object.freeze({
239
420
  kind: 'zhin.console.page-blueprint',
240
421
  version: 1,
@@ -244,6 +425,7 @@ export function buildBlueprintFromSpec(input) {
244
425
  dataSource,
245
426
  sections: Object.freeze(sections),
246
427
  spec,
428
+ ...(rawReviewSpec !== undefined ? { reviewSpec: rawReviewSpec } : {}),
247
429
  });
248
430
  }
249
431
  export function definePageBlueprint(spec) {
@@ -291,12 +473,12 @@ export function defineCommentReviewPage(reviewSpec) {
291
473
  {
292
474
  key: 'endpoints',
293
475
  label: { zh: '账号数', en: 'Accounts' },
294
- value: (data) => (Array.isArray(data?.endpoints) ? data.endpoints.length : 0),
476
+ value: { $count: 'endpoints' },
295
477
  },
296
478
  {
297
479
  key: 'pendingDrafts',
298
480
  label: { zh: '待审草稿', en: 'Pending drafts' },
299
- value: (data) => (data?.endpoints ?? []).reduce((sum, ep) => sum + (typeof ep?.pendingCount === 'number' ? ep.pendingCount : (ep?.drafts?.length ?? 0)), 0),
481
+ value: { $sum: { path: 'endpoints', field: 'pendingCount' } },
300
482
  },
301
483
  ],
302
484
  sections: [
@@ -520,16 +702,20 @@ export function projectBlueprintToImCard(input, data, options = {}) {
520
702
  for (const [idx, s] of rawStats.entries()) {
521
703
  const val = typeof s.value === 'function'
522
704
  ? s.value((data ?? {}), ctx)
523
- : recordData[s.value];
705
+ : evaluateDeclarativeValue(s.value, recordData, locale);
524
706
  const hint = typeof s.hint === 'function'
525
707
  ? formatRenderableValue(s.hint((data ?? {})))
526
- : s.hint
527
- ? resolveDeclarativeText(s.hint, locale)
528
- : undefined;
708
+ : isDeclarativeValueExpr(s.hint)
709
+ ? formatRenderableValue(evaluateDeclarativeValue(s.hint, recordData, locale))
710
+ : s.hint
711
+ ? resolveDeclarativeText(s.hint, locale)
712
+ : undefined;
529
713
  const badge = s.badge
530
714
  ? typeof s.badge.label === 'function'
531
715
  ? formatRenderableValue(s.badge.label((data ?? {})))
532
- : resolveDeclarativeText(s.badge.label, locale)
716
+ : isDeclarativeValueExpr(s.badge.label)
717
+ ? formatRenderableValue(evaluateDeclarativeValue(s.badge.label, recordData, locale))
718
+ : resolveDeclarativeText(s.badge.label, locale)
533
719
  : undefined;
534
720
  stats.push(Object.freeze({
535
721
  key: s.key ?? `stat-${idx}`,
@@ -544,7 +730,11 @@ export function projectBlueprintToImCard(input, data, options = {}) {
544
730
  for (const sec of bp.sections) {
545
731
  if (sec.type === 'stats') {
546
732
  for (const item of sec.items) {
547
- const val = item.dataKey ? recordData[item.dataKey] : item.value;
733
+ const val = item.expr
734
+ ? evaluateDeclarativeValue(item.expr, recordData, locale)
735
+ : item.dataKey
736
+ ? resolveDataPath(recordData, item.dataKey)
737
+ : item.value;
548
738
  stats.push(Object.freeze({
549
739
  key: item.key,
550
740
  label: item.label,
@@ -563,7 +753,7 @@ export function projectBlueprintToImCard(input, data, options = {}) {
563
753
  if (sec.items !== undefined) {
564
754
  const rawItems = typeof sec.items === 'function'
565
755
  ? sec.items((data ?? {}))
566
- : recordData[sec.items];
756
+ : resolveDataPath(recordData, sec.items);
567
757
  const list = Array.isArray(rawItems) ? rawItems : [];
568
758
  const cols = sec.columns && sec.columns.length > 0
569
759
  ? sec.columns.map((c) => ({
@@ -581,9 +771,12 @@ export function projectBlueprintToImCard(input, data, options = {}) {
581
771
  return [formatRenderableValue(sec.renderItem(row, rowIdx, ctx))];
582
772
  }
583
773
  const rec = (row && typeof row === 'object' ? row : { value: row });
584
- return cols.map((c) => c.render
585
- ? formatRenderableValue(c.render(rec[c.key], row, ctx))
586
- : formatRenderableValue(rec[c.key]));
774
+ return cols.map((c) => {
775
+ const cellVal = resolveDataPath(rec, c.key);
776
+ return c.render
777
+ ? formatRenderableValue(c.render(cellVal, row, ctx))
778
+ : formatRenderableValue(cellVal);
779
+ });
587
780
  });
588
781
  const emptyText = sec.emptyText ? resolveDeclarativeText(sec.emptyText, locale) : undefined;
589
782
  tables.push(Object.freeze({
@@ -596,15 +789,31 @@ export function projectBlueprintToImCard(input, data, options = {}) {
596
789
  }));
597
790
  }
598
791
  else if (sec.entries !== undefined) {
599
- const rawEntries = sec.entries((data ?? {}), ctx);
792
+ const rawEntries = typeof sec.entries === 'function'
793
+ ? sec.entries((data ?? {}), ctx)
794
+ : sec.entries;
600
795
  const items = Array.isArray(rawEntries)
601
- ? rawEntries.map((entry) => Object.freeze({
602
- label: formatRenderableValue(entry.label),
603
- value: formatRenderableValue(entry.value),
604
- }))
796
+ ? rawEntries.map((entry) => {
797
+ const entryRecord = entry;
798
+ const resolvedValue = isDeclarativeValueExpr(entryRecord.expr)
799
+ ? evaluateDeclarativeValue(entryRecord.expr, recordData, locale)
800
+ : isDeclarativeValueExpr(entryRecord.value)
801
+ ? evaluateDeclarativeValue(entryRecord.value, recordData, locale)
802
+ : entryRecord.dataKey
803
+ ? resolveDataPath(recordData, entryRecord.dataKey)
804
+ : entryRecord.value;
805
+ return Object.freeze({
806
+ label: typeof entryRecord.label === 'object' &&
807
+ entryRecord.label !== null &&
808
+ ('zh' in entryRecord.label || 'en' in entryRecord.label || 'zh-CN' in entryRecord.label)
809
+ ? resolveDeclarativeText(entryRecord.label, locale)
810
+ : formatRenderableValue(entryRecord.label),
811
+ value: formatRenderableValue(resolvedValue),
812
+ });
813
+ })
605
814
  : Object.entries(rawEntries ?? {}).map(([k, v]) => Object.freeze({
606
815
  label: k,
607
- value: formatRenderableValue(v),
816
+ value: formatRenderableValue(isDeclarativeValueExpr(v) ? evaluateDeclarativeValue(v, recordData, locale) : v),
608
817
  }));
609
818
  entries.push(Object.freeze({
610
819
  id,
@@ -617,11 +826,11 @@ export function projectBlueprintToImCard(input, data, options = {}) {
617
826
  else {
618
827
  for (const sec of bp.sections) {
619
828
  if (sec.type === 'table') {
620
- const rawItems = sec.dataKey ? recordData[sec.dataKey] : undefined;
829
+ const rawItems = sec.dataKey ? resolveDataPath(recordData, sec.dataKey) : undefined;
621
830
  const list = Array.isArray(rawItems) ? rawItems : [];
622
831
  const rows = list.slice(0, maxRows).map((row) => {
623
832
  const rec = (row && typeof row === 'object' ? row : {});
624
- return sec.columns.map((c) => formatRenderableValue(rec[c.key]));
833
+ return sec.columns.map((c) => formatRenderableValue(resolveDataPath(rec, c.key)));
625
834
  });
626
835
  tables.push(Object.freeze({
627
836
  id: sec.id,
@@ -631,6 +840,25 @@ export function projectBlueprintToImCard(input, data, options = {}) {
631
840
  totalRows: list.length,
632
841
  }));
633
842
  }
843
+ else if (sec.type === 'entries' && Array.isArray(sec.entries)) {
844
+ entries.push(Object.freeze({
845
+ id: sec.id,
846
+ title: sec.title,
847
+ items: Object.freeze(sec.entries.map((entry) => {
848
+ const resolvedValue = entry.expr
849
+ ? evaluateDeclarativeValue(entry.expr, recordData, locale)
850
+ : isDeclarativeValueExpr(entry.value)
851
+ ? evaluateDeclarativeValue(entry.value, recordData, locale)
852
+ : entry.dataKey
853
+ ? resolveDataPath(recordData, entry.dataKey)
854
+ : entry.value;
855
+ return Object.freeze({
856
+ label: formatRenderableValue(entry.label),
857
+ value: formatRenderableValue(resolvedValue),
858
+ });
859
+ })),
860
+ }));
861
+ }
634
862
  }
635
863
  }
636
864
  const actions = [];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhin.js/console-contract",
3
- "version": "1.1.4",
3
+ "version": "1.1.6",
4
4
  "description": "Zero-dependency Page, Layout, route and navigation contracts for Zhin.js plugins",
5
5
  "type": "module",
6
6
  "main": "./lib/index.js",