@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/src/page.ts CHANGED
@@ -1,3 +1,27 @@
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
+ ] as const);
9
+
10
+ export type ConsolePageSection = (typeof CONSOLE_PAGE_SECTIONS)[number];
11
+
12
+ export function isConsolePageSection(value: unknown): value is ConsolePageSection {
13
+ return typeof value === 'string' && (CONSOLE_PAGE_SECTIONS as readonly string[]).includes(value);
14
+ }
15
+
16
+ /** Validates an optional `section`; throws for anything outside {@link CONSOLE_PAGE_SECTIONS}. */
17
+ export function optionalPageSection(value: unknown): ConsolePageSection | undefined {
18
+ if (value === undefined) return undefined;
19
+ if (!isConsolePageSection(value)) {
20
+ throw new TypeError(`Page section must be one of ${CONSOLE_PAGE_SECTIONS.join(', ')}`);
21
+ }
22
+ return value;
23
+ }
24
+
1
25
  export interface PageMetadata {
2
26
  readonly title?: string;
3
27
  /** Explicit display titles; missing locales retain title. */
@@ -7,6 +31,13 @@ export interface PageMetadata {
7
31
  readonly hideInNav?: boolean;
8
32
  readonly requiredPermissions?: readonly string[];
9
33
  readonly requiredRoles?: readonly string[];
34
+ /** Presentation hints carried through to the Console entry projection. */
35
+ readonly description?: string;
36
+ readonly group?: string;
37
+ readonly parent?: string;
38
+ readonly fullWidth?: boolean;
39
+ /** Console navigation section (ADR 0052); omitted → the Console's default for plugin pages. */
40
+ readonly section?: ConsolePageSection;
10
41
  }
11
42
 
12
43
  export interface NormalizedPageMetadata {
@@ -46,7 +77,7 @@ export function normalizeClientModuleArtifact(
46
77
  export function isConsoleBlueprint(
47
78
  value: unknown,
48
79
  ): value is ConsolePageBlueprint | ConsoleAdapterPageBlueprint {
49
- if (!value || typeof value !== 'object') return false;
80
+ if (!value || (typeof value !== 'object' && typeof value !== 'function')) return false;
50
81
  const kind = (value as { readonly kind?: unknown }).kind;
51
82
  return kind === 'zhin.console.page-blueprint' || kind === 'zhin.console.adapter-page';
52
83
  }
@@ -63,7 +94,25 @@ export interface PageManifest extends NormalizedPageMetadata {
63
94
  }
64
95
 
65
96
  export function definePage(metadata: PageMetadata = {}): Readonly<PageMetadata> {
66
- return normalizePageInput(metadata);
97
+ // Same optional keys as `@zhin.js/page`; anything else is still rejected below.
98
+ const { description, group, parent, fullWidth, section: rawSection, ...base } = requireRecord(metadata, 'Page metadata');
99
+ const section = optionalPageSection(rawSection);
100
+ for (const [key, value] of [['description', description], ['group', group], ['parent', parent]] as const) {
101
+ if (value !== undefined && (typeof value !== 'string' || !value.trim())) {
102
+ throw new TypeError(`Page ${key} must be a non-empty string`);
103
+ }
104
+ }
105
+ if (fullWidth !== undefined && typeof fullWidth !== 'boolean') {
106
+ throw new TypeError('Page fullWidth must be boolean');
107
+ }
108
+ return Object.freeze({
109
+ ...normalizePageInput(base as PageMetadata),
110
+ ...(description !== undefined ? { description: description as string } : {}),
111
+ ...(group !== undefined ? { group: group as string } : {}),
112
+ ...(parent !== undefined ? { parent: parent as string } : {}),
113
+ ...(fullWidth !== undefined ? { fullWidth } : {}),
114
+ ...(section !== undefined ? { section } : {}),
115
+ });
67
116
  }
68
117
 
69
118
  export function normalizePageMetadata(
@@ -200,6 +249,152 @@ export type DeclarativeUiLocale = 'zh-CN' | 'en';
200
249
  /** Framework-agnostic renderable value (string, number, boolean, null, undefined, or JSX/ReactNode in browser). */
201
250
  export type DeclarativeRenderable = unknown;
202
251
 
252
+ /**
253
+ * Pure JSON-serializable expression descriptor for zero-closure Server-Driven Blueprints.
254
+ * Can be evaluated identically in Web Console, IM Card projection, and CLI TUI panels.
255
+ */
256
+ export type DeclarativeValueExpr =
257
+ | { readonly $path: string; readonly fallback?: string | number | boolean }
258
+ | { readonly $count: string }
259
+ | { readonly $sum: { readonly path: string; readonly field: string } }
260
+ | { readonly $format: DeclarativeI18nText; readonly args: readonly string[] }
261
+ | {
262
+ readonly $map: {
263
+ readonly path: string;
264
+ readonly cases: Readonly<Record<string, DeclarativeI18nText>>;
265
+ readonly default?: DeclarativeI18nText;
266
+ };
267
+ }
268
+ | {
269
+ readonly $join: {
270
+ readonly path: string;
271
+ readonly sep?: string;
272
+ readonly empty?: DeclarativeI18nText;
273
+ };
274
+ }
275
+ | { readonly $coalesce: readonly string[]; readonly fallback?: string | number | boolean };
276
+
277
+ export function isDeclarativeValueExpr(value: unknown): value is DeclarativeValueExpr {
278
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
279
+ const rec = value as Record<string, unknown>;
280
+ return (
281
+ typeof rec.$path === 'string' ||
282
+ typeof rec.$count === 'string' ||
283
+ (rec.$sum !== null && typeof rec.$sum === 'object') ||
284
+ (rec.$format !== undefined && Array.isArray(rec.$args ?? rec.args)) ||
285
+ (rec.$map !== null && typeof rec.$map === 'object') ||
286
+ (rec.$join !== null && typeof rec.$join === 'object') ||
287
+ Array.isArray(rec.$coalesce)
288
+ );
289
+ }
290
+
291
+ export function resolveDataPath(data: unknown, path: string): unknown {
292
+ if (!data || typeof data !== 'object' || !path) return undefined;
293
+ const record = data as Record<string, unknown>;
294
+ if (Object.prototype.hasOwnProperty.call(record, path)) return record[path];
295
+ const segments = path.split('.').filter(Boolean);
296
+ let cursor: unknown = data;
297
+ for (const seg of segments) {
298
+ if (cursor === null || cursor === undefined) return undefined;
299
+ if (Array.isArray(cursor) && seg === 'length') return cursor.length;
300
+ if (typeof cursor !== 'object') return undefined;
301
+ cursor = Object.prototype.hasOwnProperty.call(cursor, seg)
302
+ ? (cursor as Record<string, unknown>)[seg]
303
+ : undefined;
304
+ }
305
+ return cursor;
306
+ }
307
+
308
+ export function evaluateDeclarativeValue(
309
+ exprOrKey: unknown,
310
+ data: unknown,
311
+ locale: DeclarativeUiLocale = 'en',
312
+ ): unknown {
313
+ if (exprOrKey === null || exprOrKey === undefined) return undefined;
314
+ if (typeof exprOrKey === 'string') {
315
+ return resolveDataPath(data, exprOrKey);
316
+ }
317
+ if (!isDeclarativeValueExpr(exprOrKey)) {
318
+ return exprOrKey;
319
+ }
320
+ const rec = exprOrKey as Record<string, unknown>;
321
+ if (typeof rec.$path === 'string') {
322
+ const val = resolveDataPath(data, rec.$path);
323
+ return val !== undefined && val !== null && val !== '' ? val : rec.fallback;
324
+ }
325
+ if (typeof rec.$count === 'string') {
326
+ const target = resolveDataPath(data, rec.$count);
327
+ if (Array.isArray(target)) return target.length;
328
+ if (target && typeof target === 'object') return Object.keys(target).length;
329
+ return typeof target === 'number' ? target : 0;
330
+ }
331
+ if (rec.$sum && typeof rec.$sum === 'object') {
332
+ const sumSpec = rec.$sum as { readonly path?: string; readonly field?: string };
333
+ const list = sumSpec.path ? resolveDataPath(data, sumSpec.path) : undefined;
334
+ if (!Array.isArray(list) || !sumSpec.field) return 0;
335
+ return list.reduce((acc: number, item: unknown) => {
336
+ let raw = resolveDataPath(item, sumSpec.field!);
337
+ if (raw === undefined && sumSpec.field === 'pendingCount') {
338
+ raw = resolveDataPath(item, 'drafts.length');
339
+ }
340
+ const n = Number(raw);
341
+ return acc + (Number.isFinite(n) ? n : 0);
342
+ }, 0);
343
+ }
344
+ const formatArgs = Array.isArray(rec.args)
345
+ ? rec.args
346
+ : Array.isArray(rec.$args)
347
+ ? rec.$args
348
+ : undefined;
349
+ if (rec.$format !== undefined && formatArgs) {
350
+ const template = resolveDeclarativeText(rec.$format as DeclarativeI18nText, locale);
351
+ const args = (formatArgs as readonly string[]).map((p) => resolveDataPath(data, p));
352
+ if (args.length > 0 && args.every((v) => v === undefined || v === null || v === '')) {
353
+ return undefined;
354
+ }
355
+ return template.replace(/\{(\d+)\}/gu, (_m, idx) => {
356
+ const v = args[Number(idx)];
357
+ return v === undefined || v === null ? '' : String(v);
358
+ });
359
+ }
360
+ if (rec.$map && typeof rec.$map === 'object') {
361
+ const mapSpec = rec.$map as {
362
+ readonly path?: string;
363
+ readonly cases?: Readonly<Record<string, DeclarativeI18nText>>;
364
+ readonly default?: DeclarativeI18nText;
365
+ };
366
+ const rawVal = mapSpec.path ? resolveDataPath(data, mapSpec.path) : undefined;
367
+ if (rawVal !== undefined && rawVal !== null && mapSpec.cases) {
368
+ const key = String(rawVal);
369
+ if (Object.prototype.hasOwnProperty.call(mapSpec.cases, key)) {
370
+ return resolveDeclarativeText(mapSpec.cases[key]!, locale);
371
+ }
372
+ }
373
+ if (mapSpec.default !== undefined) return resolveDeclarativeText(mapSpec.default, locale);
374
+ return rawVal;
375
+ }
376
+ if (rec.$join && typeof rec.$join === 'object') {
377
+ const joinSpec = rec.$join as {
378
+ readonly path?: string;
379
+ readonly sep?: string;
380
+ readonly empty?: DeclarativeI18nText;
381
+ };
382
+ const list = joinSpec.path ? resolveDataPath(data, joinSpec.path) : undefined;
383
+ if (!Array.isArray(list) || list.length === 0) {
384
+ return joinSpec.empty !== undefined ? resolveDeclarativeText(joinSpec.empty, locale) : '—';
385
+ }
386
+ return list.map((item) => String(item ?? '')).join(joinSpec.sep ?? ', ');
387
+ }
388
+ if (Array.isArray(rec.$coalesce)) {
389
+ for (const candidate of rec.$coalesce as readonly string[]) {
390
+ const val = resolveDataPath(data, candidate);
391
+ if (val !== undefined && val !== null && val !== '') return val;
392
+ }
393
+ return rec.fallback;
394
+ }
395
+ return undefined;
396
+ }
397
+
203
398
  export interface DeclarativePageContext<TData = Record<string, unknown>> {
204
399
  readonly pluginId: string;
205
400
  readonly locale: DeclarativeUiLocale;
@@ -225,8 +420,12 @@ export interface DeclarativeBadgeSpec<TData = Record<string, unknown>> {
225
420
  readonly key?: string;
226
421
  readonly label:
227
422
  | DeclarativeI18nText
423
+ | DeclarativeValueExpr
228
424
  | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
229
- readonly tone?: DeclarativeBadgeTone | ((data: TData) => DeclarativeBadgeTone);
425
+ readonly tone?:
426
+ | DeclarativeBadgeTone
427
+ | DeclarativeValueExpr
428
+ | ((data: TData) => DeclarativeBadgeTone);
230
429
  }
231
430
 
232
431
  export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
@@ -234,17 +433,52 @@ export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
234
433
  readonly label: DeclarativeI18nText;
235
434
  readonly value:
236
435
  | (keyof TData & string)
436
+ | string
437
+ | DeclarativeValueExpr
237
438
  | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
238
- readonly hint?: DeclarativeI18nText | ((data: TData) => DeclarativeRenderable);
439
+ readonly unit?: DeclarativeI18nText;
440
+ readonly icon?: DeclarativeRenderable;
441
+ readonly image?: string;
442
+ readonly watermark?: DeclarativeRenderable | string;
443
+ readonly tone?: DeclarativeBadgeTone | 'primary';
444
+ readonly progress?: number | string | DeclarativeValueExpr;
445
+ readonly sparkline?: string;
446
+ readonly trend?: {
447
+ readonly value: DeclarativeI18nText | DeclarativeValueExpr;
448
+ readonly direction?: 'up' | 'down' | 'flat';
449
+ };
450
+ readonly hint?:
451
+ | DeclarativeI18nText
452
+ | DeclarativeValueExpr
453
+ | ((data: TData) => DeclarativeRenderable);
239
454
  readonly badge?: {
240
- readonly label: DeclarativeI18nText | ((data: TData) => DeclarativeRenderable);
241
- readonly tone?: DeclarativeBadgeTone | ((data: TData) => DeclarativeBadgeTone);
455
+ readonly label:
456
+ | DeclarativeI18nText
457
+ | DeclarativeValueExpr
458
+ | ((data: TData) => DeclarativeRenderable);
459
+ readonly tone?:
460
+ | DeclarativeBadgeTone
461
+ | DeclarativeValueExpr
462
+ | ((data: TData) => DeclarativeBadgeTone);
242
463
  };
243
464
  }
244
465
 
245
466
  export interface DeclarativeActionFieldSpec {
246
467
  readonly key: string;
247
468
  readonly label: DeclarativeI18nText;
469
+ readonly type?: 'text' | 'password' | 'number' | 'textarea' | 'select' | 'switch' | 'radio' | 'checkbox-group' | 'segmented';
470
+ readonly options?: readonly {
471
+ readonly value: string;
472
+ readonly label: DeclarativeI18nText;
473
+ readonly description?: DeclarativeI18nText;
474
+ readonly icon?: DeclarativeRenderable;
475
+ readonly badge?: DeclarativeRenderable;
476
+ readonly disabled?: boolean;
477
+ }[];
478
+ readonly variant?: 'default' | 'card' | 'button';
479
+ readonly direction?: 'column' | 'row' | 'grid';
480
+ readonly hint?: DeclarativeI18nText;
481
+ readonly rows?: number;
248
482
  readonly placeholder?: string;
249
483
  readonly required?: boolean;
250
484
  readonly defaultValue?: string;
@@ -256,6 +490,7 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
256
490
  readonly name: string;
257
491
  readonly label: DeclarativeI18nText;
258
492
  readonly description?: DeclarativeI18nText;
493
+ readonly icon?: DeclarativeRenderable;
259
494
  readonly variant?: DeclarativeButtonVariant;
260
495
  readonly confirm?: DeclarativeI18nText;
261
496
  readonly confirmLabel?: DeclarativeI18nText;
@@ -270,12 +505,33 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
270
505
  readonly successMessage?: DeclarativeI18nText;
271
506
  }
272
507
 
508
+ export type DeclarativeColumnType =
509
+ | 'auto'
510
+ | 'text'
511
+ | 'code'
512
+ | 'badge'
513
+ | 'boolean'
514
+ | 'link'
515
+ | 'datetime'
516
+ | 'number'
517
+ | 'progress'
518
+ | 'tags'
519
+ | 'json';
520
+
273
521
  export interface DeclarativeColumnSpec<
274
522
  TRow = Record<string, unknown>,
275
523
  TData = Record<string, unknown>,
276
524
  > {
277
525
  readonly key: keyof TRow & string;
278
526
  readonly label: DeclarativeI18nText;
527
+ readonly icon?: DeclarativeRenderable;
528
+ readonly type?: DeclarativeColumnType;
529
+ readonly align?: 'left' | 'center' | 'right';
530
+ readonly fixed?: 'left' | 'right';
531
+ readonly sortable?: boolean;
532
+ readonly copyable?: boolean;
533
+ readonly width?: string | number;
534
+ readonly toneMap?: Readonly<Record<string, DeclarativeBadgeTone>>;
279
535
  readonly render?: (
280
536
  value: unknown,
281
537
  row: TRow,
@@ -283,6 +539,55 @@ export interface DeclarativeColumnSpec<
283
539
  ) => DeclarativeRenderable;
284
540
  }
285
541
 
542
+ export interface DeclarativeBatchActionSpec<
543
+ TRow = Record<string, unknown>,
544
+ TData = Record<string, unknown>,
545
+ > {
546
+ readonly name: string;
547
+ readonly label: DeclarativeI18nText;
548
+ readonly icon?: DeclarativeRenderable;
549
+ readonly variant?: DeclarativeButtonVariant;
550
+ readonly confirm?: DeclarativeI18nText;
551
+ readonly confirmLabel?: DeclarativeI18nText;
552
+ readonly idsParamKey?: string;
553
+ readonly params?: (
554
+ selectedRows: readonly TRow[],
555
+ selectedKeys: readonly string[],
556
+ data: TData | undefined,
557
+ ) => Readonly<Record<string, unknown>>;
558
+ readonly onExecute?: (
559
+ selectedRows: readonly TRow[],
560
+ selectedKeys: readonly string[],
561
+ ctx: DeclarativePageContext<TData>,
562
+ ) => unknown;
563
+ readonly successMessage?: DeclarativeI18nText;
564
+ }
565
+
566
+ export interface DeclarativeRowActionSpec<
567
+ TRow = Record<string, unknown>,
568
+ TData = Record<string, unknown>,
569
+ > {
570
+ readonly name: string;
571
+ readonly label: DeclarativeI18nText;
572
+ readonly icon?: DeclarativeRenderable;
573
+ readonly variant?: DeclarativeButtonVariant;
574
+ readonly confirm?: DeclarativeI18nText;
575
+ readonly confirmLabel?: DeclarativeI18nText;
576
+ readonly idParamKey?: string;
577
+ readonly params?: (
578
+ row: TRow,
579
+ rowKey: string,
580
+ data: TData | undefined,
581
+ ) => Readonly<Record<string, unknown>>;
582
+ readonly onExecute?: (
583
+ row: TRow,
584
+ rowKey: string,
585
+ ctx: DeclarativePageContext<TData>,
586
+ ) => unknown;
587
+ readonly disabled?: boolean | ((row: TRow) => boolean);
588
+ readonly successMessage?: DeclarativeI18nText;
589
+ }
590
+
286
591
  export interface DeclarativeSectionSpec<
287
592
  TData = Record<string, unknown>,
288
593
  TRow = Record<string, unknown>,
@@ -290,7 +595,22 @@ export interface DeclarativeSectionSpec<
290
595
  readonly id?: string;
291
596
  readonly title?: DeclarativeI18nText;
292
597
  readonly description?: DeclarativeI18nText;
598
+ readonly tab?: DeclarativeI18nText;
599
+ readonly layout?: 'table' | 'cards' | 'kv' | 'timeline' | 'json';
600
+ readonly columnsCount?: 1 | 2 | 3;
601
+ readonly collapsible?: boolean;
602
+ readonly defaultCollapsed?: boolean;
293
603
  readonly emptyText?: DeclarativeI18nText;
604
+ readonly rowKey?: keyof TRow & string;
605
+ readonly selectable?: boolean;
606
+ readonly batchActions?: readonly DeclarativeBatchActionSpec<TRow, TData>[];
607
+ readonly rowActions?: readonly DeclarativeRowActionSpec<TRow, TData>[];
608
+ readonly renderExpandedRow?: (
609
+ row: TRow,
610
+ index: number,
611
+ ctx: DeclarativePageContext<TData>,
612
+ ) => DeclarativeRenderable;
613
+ readonly responsiveStack?: boolean;
294
614
  /** Extract rows for a declarative table or list. */
295
615
  readonly items?: (keyof TData & string) | ((data: TData) => readonly TRow[]);
296
616
  /** Columns for a declarative table/card list when `items` is provided. */
@@ -302,12 +622,18 @@ export interface DeclarativeSectionSpec<
302
622
  ctx: DeclarativePageContext<TData>,
303
623
  ) => DeclarativeRenderable;
304
624
  /** Key-value description list extractor (`<dl className="zk-dl">`). */
305
- readonly entries?: (
306
- data: TData,
307
- ctx: DeclarativePageContext<TData>,
308
- ) =>
309
- | Readonly<Record<string, DeclarativeRenderable>>
310
- | readonly { readonly label: DeclarativeRenderable; readonly value: DeclarativeRenderable }[];
625
+ readonly entries?:
626
+ | readonly {
627
+ readonly label: DeclarativeI18nText;
628
+ readonly value?: DeclarativeRenderable | DeclarativeValueExpr;
629
+ readonly dataKey?: string;
630
+ }[]
631
+ | ((
632
+ data: TData,
633
+ ctx: DeclarativePageContext<TData>,
634
+ ) =>
635
+ | Readonly<Record<string, DeclarativeRenderable>>
636
+ | readonly { readonly label: DeclarativeRenderable; readonly value: DeclarativeRenderable }[]);
311
637
  /** Custom section body renderer. */
312
638
  readonly render?: (data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable;
313
639
  }
@@ -364,6 +690,7 @@ export type ConsolePageBlueprintSection =
364
690
  readonly value?: unknown;
365
691
  readonly suffix?: string;
366
692
  readonly dataKey?: string;
693
+ readonly expr?: DeclarativeValueExpr;
367
694
  }[];
368
695
  }
369
696
  | {
@@ -378,6 +705,12 @@ export type ConsolePageBlueprintSection =
378
705
  readonly type: 'entries';
379
706
  readonly id: string;
380
707
  readonly title: string;
708
+ readonly entries?: readonly {
709
+ readonly label: string;
710
+ readonly value: string;
711
+ readonly dataKey?: string;
712
+ readonly expr?: DeclarativeValueExpr;
713
+ }[];
381
714
  }
382
715
  | {
383
716
  readonly type: 'actions';
@@ -389,6 +722,12 @@ export type ConsolePageBlueprintSection =
389
722
  readonly name?: string;
390
723
  readonly description?: string;
391
724
  readonly variant?: DeclarativeButtonVariant;
725
+ readonly confirm?: DeclarativeI18nText;
726
+ readonly confirmLabel?: DeclarativeI18nText;
727
+ readonly fields?: readonly DeclarativeActionFieldSpec[];
728
+ readonly params?: DeclarativeActionSpec<any>['params'];
729
+ readonly disabled?: DeclarativeActionSpec<any>['disabled'];
730
+ readonly successMessage?: DeclarativeI18nText;
392
731
  }[];
393
732
  }
394
733
  | {
@@ -510,6 +849,7 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
510
849
  dataSource: Object.freeze({ action: bp.dataSource?.action ?? 'status' }),
511
850
  sections: Object.freeze([...(bp.sections ?? [])]),
512
851
  ...(bp.spec !== undefined ? { spec: bp.spec } : {}),
852
+ ...(bp.reviewSpec !== undefined ? { reviewSpec: bp.reviewSpec } : {}),
513
853
  });
514
854
  }
515
855
 
@@ -538,6 +878,7 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
538
878
  key: stat.key ?? (typeof stat.value === 'string' ? stat.value : `stat-${idx}`),
539
879
  label: resolveDeclarativeText(stat.label, 'en'),
540
880
  ...(typeof stat.value === 'string' ? { dataKey: stat.value } : {}),
881
+ ...(isDeclarativeValueExpr(stat.value) ? { expr: stat.value } : {}),
541
882
  }),
542
883
  ),
543
884
  ),
@@ -549,13 +890,16 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
549
890
  const id = sec.id ?? `section-${idx}`;
550
891
  const secTitle = resolveDeclarativeText(sec.title, 'en');
551
892
  if (sec.columns !== undefined || sec.items !== undefined) {
893
+ const preferredRowKey = sec.columns?.find(
894
+ (c) => c.key === 'id' || c.key === 'key' || c.key === 'ownerKey',
895
+ )?.key ?? 'id';
552
896
  sections.push(
553
897
  Object.freeze({
554
898
  type: 'table',
555
899
  id,
556
900
  title: secTitle,
557
901
  ...(typeof sec.items === 'string' ? { dataKey: sec.items } : {}),
558
- rowKey: sec.columns?.[0]?.key ?? 'id',
902
+ rowKey: preferredRowKey,
559
903
  columns: Object.freeze(
560
904
  (sec.columns ?? []).map((col) =>
561
905
  Object.freeze({
@@ -572,6 +916,26 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
572
916
  type: 'entries',
573
917
  id,
574
918
  title: secTitle,
919
+ ...(Array.isArray(sec.entries)
920
+ ? {
921
+ entries: Object.freeze(
922
+ sec.entries.map((e) => {
923
+ const inferredDataKey =
924
+ e.dataKey ??
925
+ (isDeclarativeValueExpr(e.value) &&
926
+ typeof (e.value as { $path?: unknown }).$path === 'string'
927
+ ? (e.value as { $path: string }).$path
928
+ : undefined);
929
+ return Object.freeze({
930
+ label: resolveDeclarativeText(e.label, 'en'),
931
+ value: isDeclarativeValueExpr(e.value) ? '' : String(e.value ?? ''),
932
+ ...(inferredDataKey ? { dataKey: inferredDataKey } : {}),
933
+ ...(isDeclarativeValueExpr(e.value) ? { expr: e.value } : {}),
934
+ });
935
+ }),
936
+ ),
937
+ }
938
+ : {}),
575
939
  }),
576
940
  );
577
941
  } else {
@@ -601,6 +965,12 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
601
965
  ? { description: resolveDeclarativeText(act.description, 'en') }
602
966
  : {}),
603
967
  ...(act.variant ? { variant: act.variant } : {}),
968
+ ...(act.confirm !== undefined ? { confirm: act.confirm } : {}),
969
+ ...(act.confirmLabel !== undefined ? { confirmLabel: act.confirmLabel } : {}),
970
+ ...(act.fields !== undefined ? { fields: act.fields } : {}),
971
+ ...(act.params !== undefined ? { params: act.params } : {}),
972
+ ...(act.disabled !== undefined ? { disabled: act.disabled } : {}),
973
+ ...(act.successMessage !== undefined ? { successMessage: act.successMessage } : {}),
604
974
  }),
605
975
  ),
606
976
  ),
@@ -608,6 +978,8 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
608
978
  );
609
979
  }
610
980
 
981
+ const rawReviewSpec = (spec as unknown as { readonly reviewSpec?: CommentReviewBlueprintSpec<any, any> }).reviewSpec;
982
+
611
983
  return Object.freeze({
612
984
  kind: 'zhin.console.page-blueprint',
613
985
  version: 1,
@@ -617,6 +989,7 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
617
989
  dataSource,
618
990
  sections: Object.freeze(sections),
619
991
  spec,
992
+ ...(rawReviewSpec !== undefined ? { reviewSpec: rawReviewSpec } : {}),
620
993
  });
621
994
  }
622
995
 
@@ -676,16 +1049,12 @@ export function defineCommentReviewPage<
676
1049
  {
677
1050
  key: 'endpoints',
678
1051
  label: { zh: '账号数', en: 'Accounts' },
679
- value: (data) => (Array.isArray(data?.endpoints) ? data.endpoints.length : 0),
1052
+ value: { $count: 'endpoints' },
680
1053
  },
681
1054
  {
682
1055
  key: 'pendingDrafts',
683
1056
  label: { zh: '待审草稿', en: 'Pending drafts' },
684
- value: (data) =>
685
- (data?.endpoints ?? []).reduce(
686
- (sum, ep) => sum + (typeof ep?.pendingCount === 'number' ? ep.pendingCount : (ep?.drafts?.length ?? 0)),
687
- 0,
688
- ),
1057
+ value: { $sum: { path: 'endpoints', field: 'pendingCount' } },
689
1058
  },
690
1059
  ],
691
1060
  sections: [
@@ -992,17 +1361,21 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
992
1361
  const val =
993
1362
  typeof s.value === 'function'
994
1363
  ? s.value((data ?? ({} as TData)), ctx)
995
- : recordData[s.value];
1364
+ : evaluateDeclarativeValue(s.value, recordData, locale);
996
1365
  const hint =
997
1366
  typeof s.hint === 'function'
998
1367
  ? formatRenderableValue(s.hint((data ?? ({} as TData))))
999
- : s.hint
1000
- ? resolveDeclarativeText(s.hint, locale)
1001
- : undefined;
1368
+ : isDeclarativeValueExpr(s.hint)
1369
+ ? formatRenderableValue(evaluateDeclarativeValue(s.hint, recordData, locale))
1370
+ : s.hint
1371
+ ? resolveDeclarativeText(s.hint, locale)
1372
+ : undefined;
1002
1373
  const badge = s.badge
1003
1374
  ? typeof s.badge.label === 'function'
1004
1375
  ? formatRenderableValue(s.badge.label((data ?? ({} as TData))))
1005
- : resolveDeclarativeText(s.badge.label, locale)
1376
+ : isDeclarativeValueExpr(s.badge.label)
1377
+ ? formatRenderableValue(evaluateDeclarativeValue(s.badge.label, recordData, locale))
1378
+ : resolveDeclarativeText(s.badge.label, locale)
1006
1379
  : undefined;
1007
1380
  stats.push(
1008
1381
  Object.freeze({
@@ -1018,7 +1391,11 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1018
1391
  for (const sec of bp.sections) {
1019
1392
  if (sec.type === 'stats') {
1020
1393
  for (const item of sec.items) {
1021
- const val = item.dataKey ? recordData[item.dataKey] : item.value;
1394
+ const val = item.expr
1395
+ ? evaluateDeclarativeValue(item.expr, recordData, locale)
1396
+ : item.dataKey
1397
+ ? resolveDataPath(recordData, item.dataKey)
1398
+ : item.value;
1022
1399
  stats.push(
1023
1400
  Object.freeze({
1024
1401
  key: item.key,
@@ -1042,7 +1419,7 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1042
1419
  const rawItems =
1043
1420
  typeof sec.items === 'function'
1044
1421
  ? sec.items((data ?? ({} as TData)))
1045
- : (recordData[sec.items] as readonly Record<string, unknown>[] | undefined);
1422
+ : (resolveDataPath(recordData, sec.items) as readonly Record<string, unknown>[] | undefined);
1046
1423
  const list = Array.isArray(rawItems) ? rawItems : [];
1047
1424
  const cols: readonly {
1048
1425
  readonly key: string;
@@ -1069,11 +1446,12 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1069
1446
  return [formatRenderableValue(sec.renderItem(row, rowIdx, ctx))];
1070
1447
  }
1071
1448
  const rec = (row && typeof row === 'object' ? row : { value: row }) as Record<string, unknown>;
1072
- return cols.map((c) =>
1073
- c.render
1074
- ? formatRenderableValue(c.render(rec[c.key], row, ctx))
1075
- : formatRenderableValue(rec[c.key]),
1076
- );
1449
+ return cols.map((c) => {
1450
+ const cellVal = resolveDataPath(rec, c.key);
1451
+ return c.render
1452
+ ? formatRenderableValue(c.render(cellVal, row, ctx))
1453
+ : formatRenderableValue(cellVal);
1454
+ });
1077
1455
  });
1078
1456
  const emptyText = sec.emptyText ? resolveDeclarativeText(sec.emptyText, locale) : undefined;
1079
1457
  tables.push(
@@ -1087,18 +1465,41 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1087
1465
  }),
1088
1466
  );
1089
1467
  } else if (sec.entries !== undefined) {
1090
- const rawEntries = sec.entries((data ?? ({} as TData)), ctx);
1468
+ const rawEntries =
1469
+ typeof sec.entries === 'function'
1470
+ ? sec.entries((data ?? ({} as TData)), ctx)
1471
+ : sec.entries;
1091
1472
  const items = Array.isArray(rawEntries)
1092
- ? rawEntries.map((entry) =>
1093
- Object.freeze({
1094
- label: formatRenderableValue(entry.label),
1095
- value: formatRenderableValue(entry.value),
1096
- }),
1097
- )
1473
+ ? rawEntries.map((entry) => {
1474
+ const entryRecord = entry as {
1475
+ readonly label: unknown;
1476
+ readonly value: unknown;
1477
+ readonly dataKey?: string;
1478
+ readonly expr?: DeclarativeValueExpr;
1479
+ };
1480
+ const resolvedValue = isDeclarativeValueExpr(entryRecord.expr)
1481
+ ? evaluateDeclarativeValue(entryRecord.expr, recordData, locale)
1482
+ : isDeclarativeValueExpr(entryRecord.value)
1483
+ ? evaluateDeclarativeValue(entryRecord.value, recordData, locale)
1484
+ : entryRecord.dataKey
1485
+ ? resolveDataPath(recordData, entryRecord.dataKey)
1486
+ : entryRecord.value;
1487
+ return Object.freeze({
1488
+ label:
1489
+ typeof entryRecord.label === 'object' &&
1490
+ entryRecord.label !== null &&
1491
+ ('zh' in entryRecord.label || 'en' in entryRecord.label || 'zh-CN' in entryRecord.label)
1492
+ ? resolveDeclarativeText(entryRecord.label as DeclarativeI18nText, locale)
1493
+ : formatRenderableValue(entryRecord.label),
1494
+ value: formatRenderableValue(resolvedValue),
1495
+ });
1496
+ })
1098
1497
  : Object.entries(rawEntries ?? {}).map(([k, v]) =>
1099
1498
  Object.freeze({
1100
1499
  label: k,
1101
- value: formatRenderableValue(v),
1500
+ value: formatRenderableValue(
1501
+ isDeclarativeValueExpr(v) ? evaluateDeclarativeValue(v, recordData, locale) : v,
1502
+ ),
1102
1503
  }),
1103
1504
  );
1104
1505
  entries.push(
@@ -1113,11 +1514,11 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1113
1514
  } else {
1114
1515
  for (const sec of bp.sections) {
1115
1516
  if (sec.type === 'table') {
1116
- const rawItems = sec.dataKey ? recordData[sec.dataKey] : undefined;
1517
+ const rawItems = sec.dataKey ? resolveDataPath(recordData, sec.dataKey) : undefined;
1117
1518
  const list = Array.isArray(rawItems) ? rawItems : [];
1118
1519
  const rows = list.slice(0, maxRows).map((row) => {
1119
1520
  const rec = (row && typeof row === 'object' ? row : {}) as Record<string, unknown>;
1120
- return sec.columns.map((c) => formatRenderableValue(rec[c.key]));
1521
+ return sec.columns.map((c) => formatRenderableValue(resolveDataPath(rec, c.key)));
1121
1522
  });
1122
1523
  tables.push(
1123
1524
  Object.freeze({
@@ -1128,6 +1529,28 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1128
1529
  totalRows: list.length,
1129
1530
  }),
1130
1531
  );
1532
+ } else if (sec.type === 'entries' && Array.isArray(sec.entries)) {
1533
+ entries.push(
1534
+ Object.freeze({
1535
+ id: sec.id,
1536
+ title: sec.title,
1537
+ items: Object.freeze(
1538
+ sec.entries.map((entry) => {
1539
+ const resolvedValue = entry.expr
1540
+ ? evaluateDeclarativeValue(entry.expr, recordData, locale)
1541
+ : isDeclarativeValueExpr(entry.value)
1542
+ ? evaluateDeclarativeValue(entry.value, recordData, locale)
1543
+ : entry.dataKey
1544
+ ? resolveDataPath(recordData, entry.dataKey)
1545
+ : entry.value;
1546
+ return Object.freeze({
1547
+ label: formatRenderableValue(entry.label),
1548
+ value: formatRenderableValue(resolvedValue),
1549
+ });
1550
+ }),
1551
+ ),
1552
+ }),
1553
+ );
1131
1554
  }
1132
1555
  }
1133
1556
  }