@zhin.js/console-contract 1.1.4 → 1.1.5

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
@@ -49,6 +49,42 @@ export type DeclarativeButtonVariant = 'primary' | 'secondary' | 'ghost' | 'dang
49
49
  export type DeclarativeUiLocale = 'zh-CN' | 'en';
50
50
  /** Framework-agnostic renderable value (string, number, boolean, null, undefined, or JSX/ReactNode in browser). */
51
51
  export type DeclarativeRenderable = unknown;
52
+ /**
53
+ * Pure JSON-serializable expression descriptor for zero-closure Server-Driven Blueprints.
54
+ * Can be evaluated identically in Web Console, IM Card projection, and CLI TUI panels.
55
+ */
56
+ export type DeclarativeValueExpr = {
57
+ readonly $path: string;
58
+ readonly fallback?: string | number | boolean;
59
+ } | {
60
+ readonly $count: string;
61
+ } | {
62
+ readonly $sum: {
63
+ readonly path: string;
64
+ readonly field: string;
65
+ };
66
+ } | {
67
+ readonly $format: DeclarativeI18nText;
68
+ readonly args: readonly string[];
69
+ } | {
70
+ readonly $map: {
71
+ readonly path: string;
72
+ readonly cases: Readonly<Record<string, DeclarativeI18nText>>;
73
+ readonly default?: DeclarativeI18nText;
74
+ };
75
+ } | {
76
+ readonly $join: {
77
+ readonly path: string;
78
+ readonly sep?: string;
79
+ readonly empty?: DeclarativeI18nText;
80
+ };
81
+ } | {
82
+ readonly $coalesce: readonly string[];
83
+ readonly fallback?: string | number | boolean;
84
+ };
85
+ export declare function isDeclarativeValueExpr(value: unknown): value is DeclarativeValueExpr;
86
+ export declare function resolveDataPath(data: unknown, path: string): unknown;
87
+ export declare function evaluateDeclarativeValue(exprOrKey: unknown, data: unknown, locale?: DeclarativeUiLocale): unknown;
52
88
  export interface DeclarativePageContext<TData = Record<string, unknown>> {
53
89
  readonly pluginId: string;
54
90
  readonly locale: DeclarativeUiLocale;
@@ -68,22 +104,46 @@ export interface DeclarativePageContext<TData = Record<string, unknown>> {
68
104
  }
69
105
  export interface DeclarativeBadgeSpec<TData = Record<string, unknown>> {
70
106
  readonly key?: string;
71
- readonly label: DeclarativeI18nText | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
72
- readonly tone?: DeclarativeBadgeTone | ((data: TData) => DeclarativeBadgeTone);
107
+ readonly label: DeclarativeI18nText | DeclarativeValueExpr | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
108
+ readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr | ((data: TData) => DeclarativeBadgeTone);
73
109
  }
74
110
  export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
75
111
  readonly key?: string;
76
112
  readonly label: DeclarativeI18nText;
77
- readonly value: (keyof TData & string) | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
78
- readonly hint?: DeclarativeI18nText | ((data: TData) => DeclarativeRenderable);
113
+ readonly value: (keyof TData & string) | string | DeclarativeValueExpr | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
114
+ readonly unit?: DeclarativeI18nText;
115
+ readonly icon?: DeclarativeRenderable;
116
+ readonly image?: string;
117
+ readonly watermark?: DeclarativeRenderable | string;
118
+ readonly tone?: DeclarativeBadgeTone | 'primary';
119
+ readonly progress?: number | string | DeclarativeValueExpr;
120
+ readonly sparkline?: string;
121
+ readonly trend?: {
122
+ readonly value: DeclarativeI18nText | DeclarativeValueExpr;
123
+ readonly direction?: 'up' | 'down' | 'flat';
124
+ };
125
+ readonly hint?: DeclarativeI18nText | DeclarativeValueExpr | ((data: TData) => DeclarativeRenderable);
79
126
  readonly badge?: {
80
- readonly label: DeclarativeI18nText | ((data: TData) => DeclarativeRenderable);
81
- readonly tone?: DeclarativeBadgeTone | ((data: TData) => DeclarativeBadgeTone);
127
+ readonly label: DeclarativeI18nText | DeclarativeValueExpr | ((data: TData) => DeclarativeRenderable);
128
+ readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr | ((data: TData) => DeclarativeBadgeTone);
82
129
  };
83
130
  }
84
131
  export interface DeclarativeActionFieldSpec {
85
132
  readonly key: string;
86
133
  readonly label: DeclarativeI18nText;
134
+ readonly type?: 'text' | 'password' | 'number' | 'textarea' | 'select' | 'switch' | 'radio' | 'checkbox-group' | 'segmented';
135
+ readonly options?: readonly {
136
+ readonly value: string;
137
+ readonly label: DeclarativeI18nText;
138
+ readonly description?: DeclarativeI18nText;
139
+ readonly icon?: DeclarativeRenderable;
140
+ readonly badge?: DeclarativeRenderable;
141
+ readonly disabled?: boolean;
142
+ }[];
143
+ readonly variant?: 'default' | 'card' | 'button';
144
+ readonly direction?: 'column' | 'row' | 'grid';
145
+ readonly hint?: DeclarativeI18nText;
146
+ readonly rows?: number;
87
147
  readonly placeholder?: string;
88
148
  readonly required?: boolean;
89
149
  readonly defaultValue?: string;
@@ -94,6 +154,7 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
94
154
  readonly name: string;
95
155
  readonly label: DeclarativeI18nText;
96
156
  readonly description?: DeclarativeI18nText;
157
+ readonly icon?: DeclarativeRenderable;
97
158
  readonly variant?: DeclarativeButtonVariant;
98
159
  readonly confirm?: DeclarativeI18nText;
99
160
  readonly confirmLabel?: DeclarativeI18nText;
@@ -102,16 +163,61 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
102
163
  readonly disabled?: boolean | ((data: TData | undefined) => boolean);
103
164
  readonly successMessage?: DeclarativeI18nText;
104
165
  }
166
+ export type DeclarativeColumnType = 'auto' | 'text' | 'code' | 'badge' | 'boolean' | 'link' | 'datetime' | 'number' | 'progress' | 'tags' | 'json';
105
167
  export interface DeclarativeColumnSpec<TRow = Record<string, unknown>, TData = Record<string, unknown>> {
106
168
  readonly key: keyof TRow & string;
107
169
  readonly label: DeclarativeI18nText;
170
+ readonly icon?: DeclarativeRenderable;
171
+ readonly type?: DeclarativeColumnType;
172
+ readonly align?: 'left' | 'center' | 'right';
173
+ readonly fixed?: 'left' | 'right';
174
+ readonly sortable?: boolean;
175
+ readonly copyable?: boolean;
176
+ readonly width?: string | number;
177
+ readonly toneMap?: Readonly<Record<string, DeclarativeBadgeTone>>;
108
178
  readonly render?: (value: unknown, row: TRow, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable;
109
179
  }
180
+ export interface DeclarativeBatchActionSpec<TRow = Record<string, unknown>, TData = Record<string, unknown>> {
181
+ readonly name: string;
182
+ readonly label: DeclarativeI18nText;
183
+ readonly icon?: DeclarativeRenderable;
184
+ readonly variant?: DeclarativeButtonVariant;
185
+ readonly confirm?: DeclarativeI18nText;
186
+ readonly confirmLabel?: DeclarativeI18nText;
187
+ readonly idsParamKey?: string;
188
+ readonly params?: (selectedRows: readonly TRow[], selectedKeys: readonly string[], data: TData | undefined) => Readonly<Record<string, unknown>>;
189
+ readonly onExecute?: (selectedRows: readonly TRow[], selectedKeys: readonly string[], ctx: DeclarativePageContext<TData>) => unknown;
190
+ readonly successMessage?: DeclarativeI18nText;
191
+ }
192
+ export interface DeclarativeRowActionSpec<TRow = Record<string, unknown>, TData = Record<string, unknown>> {
193
+ readonly name: string;
194
+ readonly label: DeclarativeI18nText;
195
+ readonly icon?: DeclarativeRenderable;
196
+ readonly variant?: DeclarativeButtonVariant;
197
+ readonly confirm?: DeclarativeI18nText;
198
+ readonly confirmLabel?: DeclarativeI18nText;
199
+ readonly idParamKey?: string;
200
+ readonly params?: (row: TRow, rowKey: string, data: TData | undefined) => Readonly<Record<string, unknown>>;
201
+ readonly onExecute?: (row: TRow, rowKey: string, ctx: DeclarativePageContext<TData>) => unknown;
202
+ readonly disabled?: boolean | ((row: TRow) => boolean);
203
+ readonly successMessage?: DeclarativeI18nText;
204
+ }
110
205
  export interface DeclarativeSectionSpec<TData = Record<string, unknown>, TRow = Record<string, unknown>> {
111
206
  readonly id?: string;
112
207
  readonly title?: DeclarativeI18nText;
113
208
  readonly description?: DeclarativeI18nText;
209
+ readonly tab?: DeclarativeI18nText;
210
+ readonly layout?: 'table' | 'cards' | 'kv' | 'timeline' | 'json';
211
+ readonly columnsCount?: 1 | 2 | 3;
212
+ readonly collapsible?: boolean;
213
+ readonly defaultCollapsed?: boolean;
114
214
  readonly emptyText?: DeclarativeI18nText;
215
+ readonly rowKey?: keyof TRow & string;
216
+ readonly selectable?: boolean;
217
+ readonly batchActions?: readonly DeclarativeBatchActionSpec<TRow, TData>[];
218
+ readonly rowActions?: readonly DeclarativeRowActionSpec<TRow, TData>[];
219
+ readonly renderExpandedRow?: (row: TRow, index: number, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable;
220
+ readonly responsiveStack?: boolean;
115
221
  /** Extract rows for a declarative table or list. */
116
222
  readonly items?: (keyof TData & string) | ((data: TData) => readonly TRow[]);
117
223
  /** Columns for a declarative table/card list when `items` is provided. */
@@ -119,10 +225,14 @@ export interface DeclarativeSectionSpec<TData = Record<string, unknown>, TRow =
119
225
  /** Custom row renderer when `items` is provided. */
120
226
  readonly renderItem?: (item: TRow, index: number, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable;
121
227
  /** Key-value description list extractor (`<dl className="zk-dl">`). */
122
- readonly entries?: (data: TData, ctx: DeclarativePageContext<TData>) => Readonly<Record<string, DeclarativeRenderable>> | readonly {
228
+ readonly entries?: readonly {
229
+ readonly label: DeclarativeI18nText;
230
+ readonly value?: DeclarativeRenderable | DeclarativeValueExpr;
231
+ readonly dataKey?: string;
232
+ }[] | ((data: TData, ctx: DeclarativePageContext<TData>) => Readonly<Record<string, DeclarativeRenderable>> | readonly {
123
233
  readonly label: DeclarativeRenderable;
124
234
  readonly value: DeclarativeRenderable;
125
- }[];
235
+ }[]);
126
236
  /** Custom section body renderer. */
127
237
  readonly render?: (data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable;
128
238
  }
@@ -165,6 +275,7 @@ export type ConsolePageBlueprintSection = {
165
275
  readonly value?: unknown;
166
276
  readonly suffix?: string;
167
277
  readonly dataKey?: string;
278
+ readonly expr?: DeclarativeValueExpr;
168
279
  }[];
169
280
  } | {
170
281
  readonly type: 'table';
@@ -180,6 +291,12 @@ export type ConsolePageBlueprintSection = {
180
291
  readonly type: 'entries';
181
292
  readonly id: string;
182
293
  readonly title: string;
294
+ readonly entries?: readonly {
295
+ readonly label: string;
296
+ readonly value: string;
297
+ readonly dataKey?: string;
298
+ readonly expr?: DeclarativeValueExpr;
299
+ }[];
183
300
  } | {
184
301
  readonly type: 'actions';
185
302
  readonly id: string;
@@ -190,6 +307,12 @@ export type ConsolePageBlueprintSection = {
190
307
  readonly name?: string;
191
308
  readonly description?: string;
192
309
  readonly variant?: DeclarativeButtonVariant;
310
+ readonly confirm?: DeclarativeI18nText;
311
+ readonly confirmLabel?: DeclarativeI18nText;
312
+ readonly fields?: readonly DeclarativeActionFieldSpec[];
313
+ readonly params?: DeclarativeActionSpec<any>['params'];
314
+ readonly disabled?: DeclarativeActionSpec<any>['disabled'];
315
+ readonly successMessage?: DeclarativeI18nText;
193
316
  }[];
194
317
  } | {
195
318
  readonly type: 'markdown';
package/lib/page.js CHANGED
@@ -13,7 +13,7 @@ export function normalizeClientModuleArtifact(value, label) {
13
13
  });
14
14
  }
15
15
  export function isConsoleBlueprint(value) {
16
- if (!value || typeof value !== 'object')
16
+ if (!value || (typeof value !== 'object' && typeof value !== 'function'))
17
17
  return false;
18
18
  const kind = value.kind;
19
19
  return kind === 'zhin.console.page-blueprint' || kind === 'zhin.console.adapter-page';
@@ -141,6 +141,122 @@ function pageTitleTranslations(value) {
141
141
  }
142
142
  return Object.freeze(output);
143
143
  }
144
+ export function isDeclarativeValueExpr(value) {
145
+ if (!value || typeof value !== 'object' || Array.isArray(value))
146
+ return false;
147
+ const rec = value;
148
+ return (typeof rec.$path === 'string' ||
149
+ typeof rec.$count === 'string' ||
150
+ (rec.$sum !== null && typeof rec.$sum === 'object') ||
151
+ (rec.$format !== undefined && Array.isArray(rec.$args ?? rec.args)) ||
152
+ (rec.$map !== null && typeof rec.$map === 'object') ||
153
+ (rec.$join !== null && typeof rec.$join === 'object') ||
154
+ Array.isArray(rec.$coalesce));
155
+ }
156
+ export function resolveDataPath(data, path) {
157
+ if (!data || typeof data !== 'object' || !path)
158
+ return undefined;
159
+ const record = data;
160
+ if (Object.prototype.hasOwnProperty.call(record, path))
161
+ return record[path];
162
+ const segments = path.split('.').filter(Boolean);
163
+ let cursor = data;
164
+ for (const seg of segments) {
165
+ if (cursor === null || cursor === undefined)
166
+ return undefined;
167
+ if (Array.isArray(cursor) && seg === 'length')
168
+ return cursor.length;
169
+ if (typeof cursor !== 'object')
170
+ return undefined;
171
+ cursor = Object.prototype.hasOwnProperty.call(cursor, seg)
172
+ ? cursor[seg]
173
+ : undefined;
174
+ }
175
+ return cursor;
176
+ }
177
+ export function evaluateDeclarativeValue(exprOrKey, data, locale = 'en') {
178
+ if (exprOrKey === null || exprOrKey === undefined)
179
+ return undefined;
180
+ if (typeof exprOrKey === 'string') {
181
+ return resolveDataPath(data, exprOrKey);
182
+ }
183
+ if (!isDeclarativeValueExpr(exprOrKey)) {
184
+ return exprOrKey;
185
+ }
186
+ const rec = exprOrKey;
187
+ if (typeof rec.$path === 'string') {
188
+ const val = resolveDataPath(data, rec.$path);
189
+ return val !== undefined && val !== null && val !== '' ? val : rec.fallback;
190
+ }
191
+ if (typeof rec.$count === 'string') {
192
+ const target = resolveDataPath(data, rec.$count);
193
+ if (Array.isArray(target))
194
+ return target.length;
195
+ if (target && typeof target === 'object')
196
+ return Object.keys(target).length;
197
+ return typeof target === 'number' ? target : 0;
198
+ }
199
+ if (rec.$sum && typeof rec.$sum === 'object') {
200
+ const sumSpec = rec.$sum;
201
+ const list = sumSpec.path ? resolveDataPath(data, sumSpec.path) : undefined;
202
+ if (!Array.isArray(list) || !sumSpec.field)
203
+ return 0;
204
+ return list.reduce((acc, item) => {
205
+ let raw = resolveDataPath(item, sumSpec.field);
206
+ if (raw === undefined && sumSpec.field === 'pendingCount') {
207
+ raw = resolveDataPath(item, 'drafts.length');
208
+ }
209
+ const n = Number(raw);
210
+ return acc + (Number.isFinite(n) ? n : 0);
211
+ }, 0);
212
+ }
213
+ const formatArgs = Array.isArray(rec.args)
214
+ ? rec.args
215
+ : Array.isArray(rec.$args)
216
+ ? rec.$args
217
+ : undefined;
218
+ if (rec.$format !== undefined && formatArgs) {
219
+ const template = resolveDeclarativeText(rec.$format, locale);
220
+ const args = formatArgs.map((p) => resolveDataPath(data, p));
221
+ if (args.length > 0 && args.every((v) => v === undefined || v === null || v === '')) {
222
+ return undefined;
223
+ }
224
+ return template.replace(/\{(\d+)\}/gu, (_m, idx) => {
225
+ const v = args[Number(idx)];
226
+ return v === undefined || v === null ? '' : String(v);
227
+ });
228
+ }
229
+ if (rec.$map && typeof rec.$map === 'object') {
230
+ const mapSpec = rec.$map;
231
+ const rawVal = mapSpec.path ? resolveDataPath(data, mapSpec.path) : undefined;
232
+ if (rawVal !== undefined && rawVal !== null && mapSpec.cases) {
233
+ const key = String(rawVal);
234
+ if (Object.prototype.hasOwnProperty.call(mapSpec.cases, key)) {
235
+ return resolveDeclarativeText(mapSpec.cases[key], locale);
236
+ }
237
+ }
238
+ if (mapSpec.default !== undefined)
239
+ return resolveDeclarativeText(mapSpec.default, locale);
240
+ return rawVal;
241
+ }
242
+ if (rec.$join && typeof rec.$join === 'object') {
243
+ const joinSpec = rec.$join;
244
+ const list = joinSpec.path ? resolveDataPath(data, joinSpec.path) : undefined;
245
+ if (!Array.isArray(list) || list.length === 0) {
246
+ return joinSpec.empty !== undefined ? resolveDeclarativeText(joinSpec.empty, locale) : '—';
247
+ }
248
+ return list.map((item) => String(item ?? '')).join(joinSpec.sep ?? ', ');
249
+ }
250
+ if (Array.isArray(rec.$coalesce)) {
251
+ for (const candidate of rec.$coalesce) {
252
+ const val = resolveDataPath(data, candidate);
253
+ if (val !== undefined && val !== null && val !== '')
254
+ return val;
255
+ }
256
+ return rec.fallback;
257
+ }
258
+ return undefined;
259
+ }
144
260
  export function resolveDeclarativeText(text, preferredLocale = 'en') {
145
261
  if (!text)
146
262
  return '';
@@ -163,6 +279,7 @@ export function buildBlueprintFromSpec(input) {
163
279
  dataSource: Object.freeze({ action: bp.dataSource?.action ?? 'status' }),
164
280
  sections: Object.freeze([...(bp.sections ?? [])]),
165
281
  ...(bp.spec !== undefined ? { spec: bp.spec } : {}),
282
+ ...(bp.reviewSpec !== undefined ? { reviewSpec: bp.reviewSpec } : {}),
166
283
  });
167
284
  }
168
285
  const spec = input;
@@ -185,6 +302,7 @@ export function buildBlueprintFromSpec(input) {
185
302
  key: stat.key ?? (typeof stat.value === 'string' ? stat.value : `stat-${idx}`),
186
303
  label: resolveDeclarativeText(stat.label, 'en'),
187
304
  ...(typeof stat.value === 'string' ? { dataKey: stat.value } : {}),
305
+ ...(isDeclarativeValueExpr(stat.value) ? { expr: stat.value } : {}),
188
306
  }))),
189
307
  }));
190
308
  }
@@ -192,12 +310,13 @@ export function buildBlueprintFromSpec(input) {
192
310
  const id = sec.id ?? `section-${idx}`;
193
311
  const secTitle = resolveDeclarativeText(sec.title, 'en');
194
312
  if (sec.columns !== undefined || sec.items !== undefined) {
313
+ const preferredRowKey = sec.columns?.find((c) => c.key === 'id' || c.key === 'key' || c.key === 'ownerKey')?.key ?? 'id';
195
314
  sections.push(Object.freeze({
196
315
  type: 'table',
197
316
  id,
198
317
  title: secTitle,
199
318
  ...(typeof sec.items === 'string' ? { dataKey: sec.items } : {}),
200
- rowKey: sec.columns?.[0]?.key ?? 'id',
319
+ rowKey: preferredRowKey,
201
320
  columns: Object.freeze((sec.columns ?? []).map((col) => Object.freeze({
202
321
  key: col.key,
203
322
  label: resolveDeclarativeText(col.label, 'en'),
@@ -209,6 +328,23 @@ export function buildBlueprintFromSpec(input) {
209
328
  type: 'entries',
210
329
  id,
211
330
  title: secTitle,
331
+ ...(Array.isArray(sec.entries)
332
+ ? {
333
+ entries: Object.freeze(sec.entries.map((e) => {
334
+ const inferredDataKey = e.dataKey ??
335
+ (isDeclarativeValueExpr(e.value) &&
336
+ typeof e.value.$path === 'string'
337
+ ? e.value.$path
338
+ : undefined);
339
+ return Object.freeze({
340
+ label: resolveDeclarativeText(e.label, 'en'),
341
+ value: isDeclarativeValueExpr(e.value) ? '' : String(e.value ?? ''),
342
+ ...(inferredDataKey ? { dataKey: inferredDataKey } : {}),
343
+ ...(isDeclarativeValueExpr(e.value) ? { expr: e.value } : {}),
344
+ });
345
+ })),
346
+ }
347
+ : {}),
212
348
  }));
213
349
  }
214
350
  else {
@@ -232,9 +368,16 @@ export function buildBlueprintFromSpec(input) {
232
368
  ? { description: resolveDeclarativeText(act.description, 'en') }
233
369
  : {}),
234
370
  ...(act.variant ? { variant: act.variant } : {}),
371
+ ...(act.confirm !== undefined ? { confirm: act.confirm } : {}),
372
+ ...(act.confirmLabel !== undefined ? { confirmLabel: act.confirmLabel } : {}),
373
+ ...(act.fields !== undefined ? { fields: act.fields } : {}),
374
+ ...(act.params !== undefined ? { params: act.params } : {}),
375
+ ...(act.disabled !== undefined ? { disabled: act.disabled } : {}),
376
+ ...(act.successMessage !== undefined ? { successMessage: act.successMessage } : {}),
235
377
  }))),
236
378
  }));
237
379
  }
380
+ const rawReviewSpec = spec.reviewSpec;
238
381
  return Object.freeze({
239
382
  kind: 'zhin.console.page-blueprint',
240
383
  version: 1,
@@ -244,6 +387,7 @@ export function buildBlueprintFromSpec(input) {
244
387
  dataSource,
245
388
  sections: Object.freeze(sections),
246
389
  spec,
390
+ ...(rawReviewSpec !== undefined ? { reviewSpec: rawReviewSpec } : {}),
247
391
  });
248
392
  }
249
393
  export function definePageBlueprint(spec) {
@@ -291,12 +435,12 @@ export function defineCommentReviewPage(reviewSpec) {
291
435
  {
292
436
  key: 'endpoints',
293
437
  label: { zh: '账号数', en: 'Accounts' },
294
- value: (data) => (Array.isArray(data?.endpoints) ? data.endpoints.length : 0),
438
+ value: { $count: 'endpoints' },
295
439
  },
296
440
  {
297
441
  key: 'pendingDrafts',
298
442
  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),
443
+ value: { $sum: { path: 'endpoints', field: 'pendingCount' } },
300
444
  },
301
445
  ],
302
446
  sections: [
@@ -520,16 +664,20 @@ export function projectBlueprintToImCard(input, data, options = {}) {
520
664
  for (const [idx, s] of rawStats.entries()) {
521
665
  const val = typeof s.value === 'function'
522
666
  ? s.value((data ?? {}), ctx)
523
- : recordData[s.value];
667
+ : evaluateDeclarativeValue(s.value, recordData, locale);
524
668
  const hint = typeof s.hint === 'function'
525
669
  ? formatRenderableValue(s.hint((data ?? {})))
526
- : s.hint
527
- ? resolveDeclarativeText(s.hint, locale)
528
- : undefined;
670
+ : isDeclarativeValueExpr(s.hint)
671
+ ? formatRenderableValue(evaluateDeclarativeValue(s.hint, recordData, locale))
672
+ : s.hint
673
+ ? resolveDeclarativeText(s.hint, locale)
674
+ : undefined;
529
675
  const badge = s.badge
530
676
  ? typeof s.badge.label === 'function'
531
677
  ? formatRenderableValue(s.badge.label((data ?? {})))
532
- : resolveDeclarativeText(s.badge.label, locale)
678
+ : isDeclarativeValueExpr(s.badge.label)
679
+ ? formatRenderableValue(evaluateDeclarativeValue(s.badge.label, recordData, locale))
680
+ : resolveDeclarativeText(s.badge.label, locale)
533
681
  : undefined;
534
682
  stats.push(Object.freeze({
535
683
  key: s.key ?? `stat-${idx}`,
@@ -544,7 +692,11 @@ export function projectBlueprintToImCard(input, data, options = {}) {
544
692
  for (const sec of bp.sections) {
545
693
  if (sec.type === 'stats') {
546
694
  for (const item of sec.items) {
547
- const val = item.dataKey ? recordData[item.dataKey] : item.value;
695
+ const val = item.expr
696
+ ? evaluateDeclarativeValue(item.expr, recordData, locale)
697
+ : item.dataKey
698
+ ? resolveDataPath(recordData, item.dataKey)
699
+ : item.value;
548
700
  stats.push(Object.freeze({
549
701
  key: item.key,
550
702
  label: item.label,
@@ -563,7 +715,7 @@ export function projectBlueprintToImCard(input, data, options = {}) {
563
715
  if (sec.items !== undefined) {
564
716
  const rawItems = typeof sec.items === 'function'
565
717
  ? sec.items((data ?? {}))
566
- : recordData[sec.items];
718
+ : resolveDataPath(recordData, sec.items);
567
719
  const list = Array.isArray(rawItems) ? rawItems : [];
568
720
  const cols = sec.columns && sec.columns.length > 0
569
721
  ? sec.columns.map((c) => ({
@@ -581,9 +733,12 @@ export function projectBlueprintToImCard(input, data, options = {}) {
581
733
  return [formatRenderableValue(sec.renderItem(row, rowIdx, ctx))];
582
734
  }
583
735
  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]));
736
+ return cols.map((c) => {
737
+ const cellVal = resolveDataPath(rec, c.key);
738
+ return c.render
739
+ ? formatRenderableValue(c.render(cellVal, row, ctx))
740
+ : formatRenderableValue(cellVal);
741
+ });
587
742
  });
588
743
  const emptyText = sec.emptyText ? resolveDeclarativeText(sec.emptyText, locale) : undefined;
589
744
  tables.push(Object.freeze({
@@ -596,15 +751,31 @@ export function projectBlueprintToImCard(input, data, options = {}) {
596
751
  }));
597
752
  }
598
753
  else if (sec.entries !== undefined) {
599
- const rawEntries = sec.entries((data ?? {}), ctx);
754
+ const rawEntries = typeof sec.entries === 'function'
755
+ ? sec.entries((data ?? {}), ctx)
756
+ : sec.entries;
600
757
  const items = Array.isArray(rawEntries)
601
- ? rawEntries.map((entry) => Object.freeze({
602
- label: formatRenderableValue(entry.label),
603
- value: formatRenderableValue(entry.value),
604
- }))
758
+ ? rawEntries.map((entry) => {
759
+ const entryRecord = entry;
760
+ const resolvedValue = isDeclarativeValueExpr(entryRecord.expr)
761
+ ? evaluateDeclarativeValue(entryRecord.expr, recordData, locale)
762
+ : isDeclarativeValueExpr(entryRecord.value)
763
+ ? evaluateDeclarativeValue(entryRecord.value, recordData, locale)
764
+ : entryRecord.dataKey
765
+ ? resolveDataPath(recordData, entryRecord.dataKey)
766
+ : entryRecord.value;
767
+ return Object.freeze({
768
+ label: typeof entryRecord.label === 'object' &&
769
+ entryRecord.label !== null &&
770
+ ('zh' in entryRecord.label || 'en' in entryRecord.label || 'zh-CN' in entryRecord.label)
771
+ ? resolveDeclarativeText(entryRecord.label, locale)
772
+ : formatRenderableValue(entryRecord.label),
773
+ value: formatRenderableValue(resolvedValue),
774
+ });
775
+ })
605
776
  : Object.entries(rawEntries ?? {}).map(([k, v]) => Object.freeze({
606
777
  label: k,
607
- value: formatRenderableValue(v),
778
+ value: formatRenderableValue(isDeclarativeValueExpr(v) ? evaluateDeclarativeValue(v, recordData, locale) : v),
608
779
  }));
609
780
  entries.push(Object.freeze({
610
781
  id,
@@ -617,11 +788,11 @@ export function projectBlueprintToImCard(input, data, options = {}) {
617
788
  else {
618
789
  for (const sec of bp.sections) {
619
790
  if (sec.type === 'table') {
620
- const rawItems = sec.dataKey ? recordData[sec.dataKey] : undefined;
791
+ const rawItems = sec.dataKey ? resolveDataPath(recordData, sec.dataKey) : undefined;
621
792
  const list = Array.isArray(rawItems) ? rawItems : [];
622
793
  const rows = list.slice(0, maxRows).map((row) => {
623
794
  const rec = (row && typeof row === 'object' ? row : {});
624
- return sec.columns.map((c) => formatRenderableValue(rec[c.key]));
795
+ return sec.columns.map((c) => formatRenderableValue(resolveDataPath(rec, c.key)));
625
796
  });
626
797
  tables.push(Object.freeze({
627
798
  id: sec.id,
@@ -631,6 +802,25 @@ export function projectBlueprintToImCard(input, data, options = {}) {
631
802
  totalRows: list.length,
632
803
  }));
633
804
  }
805
+ else if (sec.type === 'entries' && Array.isArray(sec.entries)) {
806
+ entries.push(Object.freeze({
807
+ id: sec.id,
808
+ title: sec.title,
809
+ items: Object.freeze(sec.entries.map((entry) => {
810
+ const resolvedValue = entry.expr
811
+ ? evaluateDeclarativeValue(entry.expr, recordData, locale)
812
+ : isDeclarativeValueExpr(entry.value)
813
+ ? evaluateDeclarativeValue(entry.value, recordData, locale)
814
+ : entry.dataKey
815
+ ? resolveDataPath(recordData, entry.dataKey)
816
+ : entry.value;
817
+ return Object.freeze({
818
+ label: formatRenderableValue(entry.label),
819
+ value: formatRenderableValue(resolvedValue),
820
+ });
821
+ })),
822
+ }));
823
+ }
634
824
  }
635
825
  }
636
826
  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.5",
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",
package/src/page.ts CHANGED
@@ -46,7 +46,7 @@ export function normalizeClientModuleArtifact(
46
46
  export function isConsoleBlueprint(
47
47
  value: unknown,
48
48
  ): value is ConsolePageBlueprint | ConsoleAdapterPageBlueprint {
49
- if (!value || typeof value !== 'object') return false;
49
+ if (!value || (typeof value !== 'object' && typeof value !== 'function')) return false;
50
50
  const kind = (value as { readonly kind?: unknown }).kind;
51
51
  return kind === 'zhin.console.page-blueprint' || kind === 'zhin.console.adapter-page';
52
52
  }
@@ -200,6 +200,152 @@ export type DeclarativeUiLocale = 'zh-CN' | 'en';
200
200
  /** Framework-agnostic renderable value (string, number, boolean, null, undefined, or JSX/ReactNode in browser). */
201
201
  export type DeclarativeRenderable = unknown;
202
202
 
203
+ /**
204
+ * Pure JSON-serializable expression descriptor for zero-closure Server-Driven Blueprints.
205
+ * Can be evaluated identically in Web Console, IM Card projection, and CLI TUI panels.
206
+ */
207
+ export type DeclarativeValueExpr =
208
+ | { readonly $path: string; readonly fallback?: string | number | boolean }
209
+ | { readonly $count: string }
210
+ | { readonly $sum: { readonly path: string; readonly field: string } }
211
+ | { readonly $format: DeclarativeI18nText; readonly args: readonly string[] }
212
+ | {
213
+ readonly $map: {
214
+ readonly path: string;
215
+ readonly cases: Readonly<Record<string, DeclarativeI18nText>>;
216
+ readonly default?: DeclarativeI18nText;
217
+ };
218
+ }
219
+ | {
220
+ readonly $join: {
221
+ readonly path: string;
222
+ readonly sep?: string;
223
+ readonly empty?: DeclarativeI18nText;
224
+ };
225
+ }
226
+ | { readonly $coalesce: readonly string[]; readonly fallback?: string | number | boolean };
227
+
228
+ export function isDeclarativeValueExpr(value: unknown): value is DeclarativeValueExpr {
229
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
230
+ const rec = value as Record<string, unknown>;
231
+ return (
232
+ typeof rec.$path === 'string' ||
233
+ typeof rec.$count === 'string' ||
234
+ (rec.$sum !== null && typeof rec.$sum === 'object') ||
235
+ (rec.$format !== undefined && Array.isArray(rec.$args ?? rec.args)) ||
236
+ (rec.$map !== null && typeof rec.$map === 'object') ||
237
+ (rec.$join !== null && typeof rec.$join === 'object') ||
238
+ Array.isArray(rec.$coalesce)
239
+ );
240
+ }
241
+
242
+ export function resolveDataPath(data: unknown, path: string): unknown {
243
+ if (!data || typeof data !== 'object' || !path) return undefined;
244
+ const record = data as Record<string, unknown>;
245
+ if (Object.prototype.hasOwnProperty.call(record, path)) return record[path];
246
+ const segments = path.split('.').filter(Boolean);
247
+ let cursor: unknown = data;
248
+ for (const seg of segments) {
249
+ if (cursor === null || cursor === undefined) return undefined;
250
+ if (Array.isArray(cursor) && seg === 'length') return cursor.length;
251
+ if (typeof cursor !== 'object') return undefined;
252
+ cursor = Object.prototype.hasOwnProperty.call(cursor, seg)
253
+ ? (cursor as Record<string, unknown>)[seg]
254
+ : undefined;
255
+ }
256
+ return cursor;
257
+ }
258
+
259
+ export function evaluateDeclarativeValue(
260
+ exprOrKey: unknown,
261
+ data: unknown,
262
+ locale: DeclarativeUiLocale = 'en',
263
+ ): unknown {
264
+ if (exprOrKey === null || exprOrKey === undefined) return undefined;
265
+ if (typeof exprOrKey === 'string') {
266
+ return resolveDataPath(data, exprOrKey);
267
+ }
268
+ if (!isDeclarativeValueExpr(exprOrKey)) {
269
+ return exprOrKey;
270
+ }
271
+ const rec = exprOrKey as Record<string, unknown>;
272
+ if (typeof rec.$path === 'string') {
273
+ const val = resolveDataPath(data, rec.$path);
274
+ return val !== undefined && val !== null && val !== '' ? val : rec.fallback;
275
+ }
276
+ if (typeof rec.$count === 'string') {
277
+ const target = resolveDataPath(data, rec.$count);
278
+ if (Array.isArray(target)) return target.length;
279
+ if (target && typeof target === 'object') return Object.keys(target).length;
280
+ return typeof target === 'number' ? target : 0;
281
+ }
282
+ if (rec.$sum && typeof rec.$sum === 'object') {
283
+ const sumSpec = rec.$sum as { readonly path?: string; readonly field?: string };
284
+ const list = sumSpec.path ? resolveDataPath(data, sumSpec.path) : undefined;
285
+ if (!Array.isArray(list) || !sumSpec.field) return 0;
286
+ return list.reduce((acc: number, item: unknown) => {
287
+ let raw = resolveDataPath(item, sumSpec.field!);
288
+ if (raw === undefined && sumSpec.field === 'pendingCount') {
289
+ raw = resolveDataPath(item, 'drafts.length');
290
+ }
291
+ const n = Number(raw);
292
+ return acc + (Number.isFinite(n) ? n : 0);
293
+ }, 0);
294
+ }
295
+ const formatArgs = Array.isArray(rec.args)
296
+ ? rec.args
297
+ : Array.isArray(rec.$args)
298
+ ? rec.$args
299
+ : undefined;
300
+ if (rec.$format !== undefined && formatArgs) {
301
+ const template = resolveDeclarativeText(rec.$format as DeclarativeI18nText, locale);
302
+ const args = (formatArgs as readonly string[]).map((p) => resolveDataPath(data, p));
303
+ if (args.length > 0 && args.every((v) => v === undefined || v === null || v === '')) {
304
+ return undefined;
305
+ }
306
+ return template.replace(/\{(\d+)\}/gu, (_m, idx) => {
307
+ const v = args[Number(idx)];
308
+ return v === undefined || v === null ? '' : String(v);
309
+ });
310
+ }
311
+ if (rec.$map && typeof rec.$map === 'object') {
312
+ const mapSpec = rec.$map as {
313
+ readonly path?: string;
314
+ readonly cases?: Readonly<Record<string, DeclarativeI18nText>>;
315
+ readonly default?: DeclarativeI18nText;
316
+ };
317
+ const rawVal = mapSpec.path ? resolveDataPath(data, mapSpec.path) : undefined;
318
+ if (rawVal !== undefined && rawVal !== null && mapSpec.cases) {
319
+ const key = String(rawVal);
320
+ if (Object.prototype.hasOwnProperty.call(mapSpec.cases, key)) {
321
+ return resolveDeclarativeText(mapSpec.cases[key]!, locale);
322
+ }
323
+ }
324
+ if (mapSpec.default !== undefined) return resolveDeclarativeText(mapSpec.default, locale);
325
+ return rawVal;
326
+ }
327
+ if (rec.$join && typeof rec.$join === 'object') {
328
+ const joinSpec = rec.$join as {
329
+ readonly path?: string;
330
+ readonly sep?: string;
331
+ readonly empty?: DeclarativeI18nText;
332
+ };
333
+ const list = joinSpec.path ? resolveDataPath(data, joinSpec.path) : undefined;
334
+ if (!Array.isArray(list) || list.length === 0) {
335
+ return joinSpec.empty !== undefined ? resolveDeclarativeText(joinSpec.empty, locale) : '—';
336
+ }
337
+ return list.map((item) => String(item ?? '')).join(joinSpec.sep ?? ', ');
338
+ }
339
+ if (Array.isArray(rec.$coalesce)) {
340
+ for (const candidate of rec.$coalesce as readonly string[]) {
341
+ const val = resolveDataPath(data, candidate);
342
+ if (val !== undefined && val !== null && val !== '') return val;
343
+ }
344
+ return rec.fallback;
345
+ }
346
+ return undefined;
347
+ }
348
+
203
349
  export interface DeclarativePageContext<TData = Record<string, unknown>> {
204
350
  readonly pluginId: string;
205
351
  readonly locale: DeclarativeUiLocale;
@@ -225,8 +371,12 @@ export interface DeclarativeBadgeSpec<TData = Record<string, unknown>> {
225
371
  readonly key?: string;
226
372
  readonly label:
227
373
  | DeclarativeI18nText
374
+ | DeclarativeValueExpr
228
375
  | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
229
- readonly tone?: DeclarativeBadgeTone | ((data: TData) => DeclarativeBadgeTone);
376
+ readonly tone?:
377
+ | DeclarativeBadgeTone
378
+ | DeclarativeValueExpr
379
+ | ((data: TData) => DeclarativeBadgeTone);
230
380
  }
231
381
 
232
382
  export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
@@ -234,17 +384,52 @@ export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
234
384
  readonly label: DeclarativeI18nText;
235
385
  readonly value:
236
386
  | (keyof TData & string)
387
+ | string
388
+ | DeclarativeValueExpr
237
389
  | ((data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable);
238
- readonly hint?: DeclarativeI18nText | ((data: TData) => DeclarativeRenderable);
390
+ readonly unit?: DeclarativeI18nText;
391
+ readonly icon?: DeclarativeRenderable;
392
+ readonly image?: string;
393
+ readonly watermark?: DeclarativeRenderable | string;
394
+ readonly tone?: DeclarativeBadgeTone | 'primary';
395
+ readonly progress?: number | string | DeclarativeValueExpr;
396
+ readonly sparkline?: string;
397
+ readonly trend?: {
398
+ readonly value: DeclarativeI18nText | DeclarativeValueExpr;
399
+ readonly direction?: 'up' | 'down' | 'flat';
400
+ };
401
+ readonly hint?:
402
+ | DeclarativeI18nText
403
+ | DeclarativeValueExpr
404
+ | ((data: TData) => DeclarativeRenderable);
239
405
  readonly badge?: {
240
- readonly label: DeclarativeI18nText | ((data: TData) => DeclarativeRenderable);
241
- readonly tone?: DeclarativeBadgeTone | ((data: TData) => DeclarativeBadgeTone);
406
+ readonly label:
407
+ | DeclarativeI18nText
408
+ | DeclarativeValueExpr
409
+ | ((data: TData) => DeclarativeRenderable);
410
+ readonly tone?:
411
+ | DeclarativeBadgeTone
412
+ | DeclarativeValueExpr
413
+ | ((data: TData) => DeclarativeBadgeTone);
242
414
  };
243
415
  }
244
416
 
245
417
  export interface DeclarativeActionFieldSpec {
246
418
  readonly key: string;
247
419
  readonly label: DeclarativeI18nText;
420
+ readonly type?: 'text' | 'password' | 'number' | 'textarea' | 'select' | 'switch' | 'radio' | 'checkbox-group' | 'segmented';
421
+ readonly options?: readonly {
422
+ readonly value: string;
423
+ readonly label: DeclarativeI18nText;
424
+ readonly description?: DeclarativeI18nText;
425
+ readonly icon?: DeclarativeRenderable;
426
+ readonly badge?: DeclarativeRenderable;
427
+ readonly disabled?: boolean;
428
+ }[];
429
+ readonly variant?: 'default' | 'card' | 'button';
430
+ readonly direction?: 'column' | 'row' | 'grid';
431
+ readonly hint?: DeclarativeI18nText;
432
+ readonly rows?: number;
248
433
  readonly placeholder?: string;
249
434
  readonly required?: boolean;
250
435
  readonly defaultValue?: string;
@@ -256,6 +441,7 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
256
441
  readonly name: string;
257
442
  readonly label: DeclarativeI18nText;
258
443
  readonly description?: DeclarativeI18nText;
444
+ readonly icon?: DeclarativeRenderable;
259
445
  readonly variant?: DeclarativeButtonVariant;
260
446
  readonly confirm?: DeclarativeI18nText;
261
447
  readonly confirmLabel?: DeclarativeI18nText;
@@ -270,12 +456,33 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
270
456
  readonly successMessage?: DeclarativeI18nText;
271
457
  }
272
458
 
459
+ export type DeclarativeColumnType =
460
+ | 'auto'
461
+ | 'text'
462
+ | 'code'
463
+ | 'badge'
464
+ | 'boolean'
465
+ | 'link'
466
+ | 'datetime'
467
+ | 'number'
468
+ | 'progress'
469
+ | 'tags'
470
+ | 'json';
471
+
273
472
  export interface DeclarativeColumnSpec<
274
473
  TRow = Record<string, unknown>,
275
474
  TData = Record<string, unknown>,
276
475
  > {
277
476
  readonly key: keyof TRow & string;
278
477
  readonly label: DeclarativeI18nText;
478
+ readonly icon?: DeclarativeRenderable;
479
+ readonly type?: DeclarativeColumnType;
480
+ readonly align?: 'left' | 'center' | 'right';
481
+ readonly fixed?: 'left' | 'right';
482
+ readonly sortable?: boolean;
483
+ readonly copyable?: boolean;
484
+ readonly width?: string | number;
485
+ readonly toneMap?: Readonly<Record<string, DeclarativeBadgeTone>>;
279
486
  readonly render?: (
280
487
  value: unknown,
281
488
  row: TRow,
@@ -283,6 +490,55 @@ export interface DeclarativeColumnSpec<
283
490
  ) => DeclarativeRenderable;
284
491
  }
285
492
 
493
+ export interface DeclarativeBatchActionSpec<
494
+ TRow = Record<string, unknown>,
495
+ TData = Record<string, unknown>,
496
+ > {
497
+ readonly name: string;
498
+ readonly label: DeclarativeI18nText;
499
+ readonly icon?: DeclarativeRenderable;
500
+ readonly variant?: DeclarativeButtonVariant;
501
+ readonly confirm?: DeclarativeI18nText;
502
+ readonly confirmLabel?: DeclarativeI18nText;
503
+ readonly idsParamKey?: string;
504
+ readonly params?: (
505
+ selectedRows: readonly TRow[],
506
+ selectedKeys: readonly string[],
507
+ data: TData | undefined,
508
+ ) => Readonly<Record<string, unknown>>;
509
+ readonly onExecute?: (
510
+ selectedRows: readonly TRow[],
511
+ selectedKeys: readonly string[],
512
+ ctx: DeclarativePageContext<TData>,
513
+ ) => unknown;
514
+ readonly successMessage?: DeclarativeI18nText;
515
+ }
516
+
517
+ export interface DeclarativeRowActionSpec<
518
+ TRow = Record<string, unknown>,
519
+ TData = Record<string, unknown>,
520
+ > {
521
+ readonly name: string;
522
+ readonly label: DeclarativeI18nText;
523
+ readonly icon?: DeclarativeRenderable;
524
+ readonly variant?: DeclarativeButtonVariant;
525
+ readonly confirm?: DeclarativeI18nText;
526
+ readonly confirmLabel?: DeclarativeI18nText;
527
+ readonly idParamKey?: string;
528
+ readonly params?: (
529
+ row: TRow,
530
+ rowKey: string,
531
+ data: TData | undefined,
532
+ ) => Readonly<Record<string, unknown>>;
533
+ readonly onExecute?: (
534
+ row: TRow,
535
+ rowKey: string,
536
+ ctx: DeclarativePageContext<TData>,
537
+ ) => unknown;
538
+ readonly disabled?: boolean | ((row: TRow) => boolean);
539
+ readonly successMessage?: DeclarativeI18nText;
540
+ }
541
+
286
542
  export interface DeclarativeSectionSpec<
287
543
  TData = Record<string, unknown>,
288
544
  TRow = Record<string, unknown>,
@@ -290,7 +546,22 @@ export interface DeclarativeSectionSpec<
290
546
  readonly id?: string;
291
547
  readonly title?: DeclarativeI18nText;
292
548
  readonly description?: DeclarativeI18nText;
549
+ readonly tab?: DeclarativeI18nText;
550
+ readonly layout?: 'table' | 'cards' | 'kv' | 'timeline' | 'json';
551
+ readonly columnsCount?: 1 | 2 | 3;
552
+ readonly collapsible?: boolean;
553
+ readonly defaultCollapsed?: boolean;
293
554
  readonly emptyText?: DeclarativeI18nText;
555
+ readonly rowKey?: keyof TRow & string;
556
+ readonly selectable?: boolean;
557
+ readonly batchActions?: readonly DeclarativeBatchActionSpec<TRow, TData>[];
558
+ readonly rowActions?: readonly DeclarativeRowActionSpec<TRow, TData>[];
559
+ readonly renderExpandedRow?: (
560
+ row: TRow,
561
+ index: number,
562
+ ctx: DeclarativePageContext<TData>,
563
+ ) => DeclarativeRenderable;
564
+ readonly responsiveStack?: boolean;
294
565
  /** Extract rows for a declarative table or list. */
295
566
  readonly items?: (keyof TData & string) | ((data: TData) => readonly TRow[]);
296
567
  /** Columns for a declarative table/card list when `items` is provided. */
@@ -302,12 +573,18 @@ export interface DeclarativeSectionSpec<
302
573
  ctx: DeclarativePageContext<TData>,
303
574
  ) => DeclarativeRenderable;
304
575
  /** 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 }[];
576
+ readonly entries?:
577
+ | readonly {
578
+ readonly label: DeclarativeI18nText;
579
+ readonly value?: DeclarativeRenderable | DeclarativeValueExpr;
580
+ readonly dataKey?: string;
581
+ }[]
582
+ | ((
583
+ data: TData,
584
+ ctx: DeclarativePageContext<TData>,
585
+ ) =>
586
+ | Readonly<Record<string, DeclarativeRenderable>>
587
+ | readonly { readonly label: DeclarativeRenderable; readonly value: DeclarativeRenderable }[]);
311
588
  /** Custom section body renderer. */
312
589
  readonly render?: (data: TData, ctx: DeclarativePageContext<TData>) => DeclarativeRenderable;
313
590
  }
@@ -364,6 +641,7 @@ export type ConsolePageBlueprintSection =
364
641
  readonly value?: unknown;
365
642
  readonly suffix?: string;
366
643
  readonly dataKey?: string;
644
+ readonly expr?: DeclarativeValueExpr;
367
645
  }[];
368
646
  }
369
647
  | {
@@ -378,6 +656,12 @@ export type ConsolePageBlueprintSection =
378
656
  readonly type: 'entries';
379
657
  readonly id: string;
380
658
  readonly title: string;
659
+ readonly entries?: readonly {
660
+ readonly label: string;
661
+ readonly value: string;
662
+ readonly dataKey?: string;
663
+ readonly expr?: DeclarativeValueExpr;
664
+ }[];
381
665
  }
382
666
  | {
383
667
  readonly type: 'actions';
@@ -389,6 +673,12 @@ export type ConsolePageBlueprintSection =
389
673
  readonly name?: string;
390
674
  readonly description?: string;
391
675
  readonly variant?: DeclarativeButtonVariant;
676
+ readonly confirm?: DeclarativeI18nText;
677
+ readonly confirmLabel?: DeclarativeI18nText;
678
+ readonly fields?: readonly DeclarativeActionFieldSpec[];
679
+ readonly params?: DeclarativeActionSpec<any>['params'];
680
+ readonly disabled?: DeclarativeActionSpec<any>['disabled'];
681
+ readonly successMessage?: DeclarativeI18nText;
392
682
  }[];
393
683
  }
394
684
  | {
@@ -510,6 +800,7 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
510
800
  dataSource: Object.freeze({ action: bp.dataSource?.action ?? 'status' }),
511
801
  sections: Object.freeze([...(bp.sections ?? [])]),
512
802
  ...(bp.spec !== undefined ? { spec: bp.spec } : {}),
803
+ ...(bp.reviewSpec !== undefined ? { reviewSpec: bp.reviewSpec } : {}),
513
804
  });
514
805
  }
515
806
 
@@ -538,6 +829,7 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
538
829
  key: stat.key ?? (typeof stat.value === 'string' ? stat.value : `stat-${idx}`),
539
830
  label: resolveDeclarativeText(stat.label, 'en'),
540
831
  ...(typeof stat.value === 'string' ? { dataKey: stat.value } : {}),
832
+ ...(isDeclarativeValueExpr(stat.value) ? { expr: stat.value } : {}),
541
833
  }),
542
834
  ),
543
835
  ),
@@ -549,13 +841,16 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
549
841
  const id = sec.id ?? `section-${idx}`;
550
842
  const secTitle = resolveDeclarativeText(sec.title, 'en');
551
843
  if (sec.columns !== undefined || sec.items !== undefined) {
844
+ const preferredRowKey = sec.columns?.find(
845
+ (c) => c.key === 'id' || c.key === 'key' || c.key === 'ownerKey',
846
+ )?.key ?? 'id';
552
847
  sections.push(
553
848
  Object.freeze({
554
849
  type: 'table',
555
850
  id,
556
851
  title: secTitle,
557
852
  ...(typeof sec.items === 'string' ? { dataKey: sec.items } : {}),
558
- rowKey: sec.columns?.[0]?.key ?? 'id',
853
+ rowKey: preferredRowKey,
559
854
  columns: Object.freeze(
560
855
  (sec.columns ?? []).map((col) =>
561
856
  Object.freeze({
@@ -572,6 +867,26 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
572
867
  type: 'entries',
573
868
  id,
574
869
  title: secTitle,
870
+ ...(Array.isArray(sec.entries)
871
+ ? {
872
+ entries: Object.freeze(
873
+ sec.entries.map((e) => {
874
+ const inferredDataKey =
875
+ e.dataKey ??
876
+ (isDeclarativeValueExpr(e.value) &&
877
+ typeof (e.value as { $path?: unknown }).$path === 'string'
878
+ ? (e.value as { $path: string }).$path
879
+ : undefined);
880
+ return Object.freeze({
881
+ label: resolveDeclarativeText(e.label, 'en'),
882
+ value: isDeclarativeValueExpr(e.value) ? '' : String(e.value ?? ''),
883
+ ...(inferredDataKey ? { dataKey: inferredDataKey } : {}),
884
+ ...(isDeclarativeValueExpr(e.value) ? { expr: e.value } : {}),
885
+ });
886
+ }),
887
+ ),
888
+ }
889
+ : {}),
575
890
  }),
576
891
  );
577
892
  } else {
@@ -601,6 +916,12 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
601
916
  ? { description: resolveDeclarativeText(act.description, 'en') }
602
917
  : {}),
603
918
  ...(act.variant ? { variant: act.variant } : {}),
919
+ ...(act.confirm !== undefined ? { confirm: act.confirm } : {}),
920
+ ...(act.confirmLabel !== undefined ? { confirmLabel: act.confirmLabel } : {}),
921
+ ...(act.fields !== undefined ? { fields: act.fields } : {}),
922
+ ...(act.params !== undefined ? { params: act.params } : {}),
923
+ ...(act.disabled !== undefined ? { disabled: act.disabled } : {}),
924
+ ...(act.successMessage !== undefined ? { successMessage: act.successMessage } : {}),
604
925
  }),
605
926
  ),
606
927
  ),
@@ -608,6 +929,8 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
608
929
  );
609
930
  }
610
931
 
932
+ const rawReviewSpec = (spec as unknown as { readonly reviewSpec?: CommentReviewBlueprintSpec<any, any> }).reviewSpec;
933
+
611
934
  return Object.freeze({
612
935
  kind: 'zhin.console.page-blueprint',
613
936
  version: 1,
@@ -617,6 +940,7 @@ export function buildBlueprintFromSpec<TData = Record<string, unknown>>(
617
940
  dataSource,
618
941
  sections: Object.freeze(sections),
619
942
  spec,
943
+ ...(rawReviewSpec !== undefined ? { reviewSpec: rawReviewSpec } : {}),
620
944
  });
621
945
  }
622
946
 
@@ -676,16 +1000,12 @@ export function defineCommentReviewPage<
676
1000
  {
677
1001
  key: 'endpoints',
678
1002
  label: { zh: '账号数', en: 'Accounts' },
679
- value: (data) => (Array.isArray(data?.endpoints) ? data.endpoints.length : 0),
1003
+ value: { $count: 'endpoints' },
680
1004
  },
681
1005
  {
682
1006
  key: 'pendingDrafts',
683
1007
  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
- ),
1008
+ value: { $sum: { path: 'endpoints', field: 'pendingCount' } },
689
1009
  },
690
1010
  ],
691
1011
  sections: [
@@ -992,17 +1312,21 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
992
1312
  const val =
993
1313
  typeof s.value === 'function'
994
1314
  ? s.value((data ?? ({} as TData)), ctx)
995
- : recordData[s.value];
1315
+ : evaluateDeclarativeValue(s.value, recordData, locale);
996
1316
  const hint =
997
1317
  typeof s.hint === 'function'
998
1318
  ? formatRenderableValue(s.hint((data ?? ({} as TData))))
999
- : s.hint
1000
- ? resolveDeclarativeText(s.hint, locale)
1001
- : undefined;
1319
+ : isDeclarativeValueExpr(s.hint)
1320
+ ? formatRenderableValue(evaluateDeclarativeValue(s.hint, recordData, locale))
1321
+ : s.hint
1322
+ ? resolveDeclarativeText(s.hint, locale)
1323
+ : undefined;
1002
1324
  const badge = s.badge
1003
1325
  ? typeof s.badge.label === 'function'
1004
1326
  ? formatRenderableValue(s.badge.label((data ?? ({} as TData))))
1005
- : resolveDeclarativeText(s.badge.label, locale)
1327
+ : isDeclarativeValueExpr(s.badge.label)
1328
+ ? formatRenderableValue(evaluateDeclarativeValue(s.badge.label, recordData, locale))
1329
+ : resolveDeclarativeText(s.badge.label, locale)
1006
1330
  : undefined;
1007
1331
  stats.push(
1008
1332
  Object.freeze({
@@ -1018,7 +1342,11 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1018
1342
  for (const sec of bp.sections) {
1019
1343
  if (sec.type === 'stats') {
1020
1344
  for (const item of sec.items) {
1021
- const val = item.dataKey ? recordData[item.dataKey] : item.value;
1345
+ const val = item.expr
1346
+ ? evaluateDeclarativeValue(item.expr, recordData, locale)
1347
+ : item.dataKey
1348
+ ? resolveDataPath(recordData, item.dataKey)
1349
+ : item.value;
1022
1350
  stats.push(
1023
1351
  Object.freeze({
1024
1352
  key: item.key,
@@ -1042,7 +1370,7 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1042
1370
  const rawItems =
1043
1371
  typeof sec.items === 'function'
1044
1372
  ? sec.items((data ?? ({} as TData)))
1045
- : (recordData[sec.items] as readonly Record<string, unknown>[] | undefined);
1373
+ : (resolveDataPath(recordData, sec.items) as readonly Record<string, unknown>[] | undefined);
1046
1374
  const list = Array.isArray(rawItems) ? rawItems : [];
1047
1375
  const cols: readonly {
1048
1376
  readonly key: string;
@@ -1069,11 +1397,12 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1069
1397
  return [formatRenderableValue(sec.renderItem(row, rowIdx, ctx))];
1070
1398
  }
1071
1399
  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
- );
1400
+ return cols.map((c) => {
1401
+ const cellVal = resolveDataPath(rec, c.key);
1402
+ return c.render
1403
+ ? formatRenderableValue(c.render(cellVal, row, ctx))
1404
+ : formatRenderableValue(cellVal);
1405
+ });
1077
1406
  });
1078
1407
  const emptyText = sec.emptyText ? resolveDeclarativeText(sec.emptyText, locale) : undefined;
1079
1408
  tables.push(
@@ -1087,18 +1416,41 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1087
1416
  }),
1088
1417
  );
1089
1418
  } else if (sec.entries !== undefined) {
1090
- const rawEntries = sec.entries((data ?? ({} as TData)), ctx);
1419
+ const rawEntries =
1420
+ typeof sec.entries === 'function'
1421
+ ? sec.entries((data ?? ({} as TData)), ctx)
1422
+ : sec.entries;
1091
1423
  const items = Array.isArray(rawEntries)
1092
- ? rawEntries.map((entry) =>
1093
- Object.freeze({
1094
- label: formatRenderableValue(entry.label),
1095
- value: formatRenderableValue(entry.value),
1096
- }),
1097
- )
1424
+ ? rawEntries.map((entry) => {
1425
+ const entryRecord = entry as {
1426
+ readonly label: unknown;
1427
+ readonly value: unknown;
1428
+ readonly dataKey?: string;
1429
+ readonly expr?: DeclarativeValueExpr;
1430
+ };
1431
+ const resolvedValue = isDeclarativeValueExpr(entryRecord.expr)
1432
+ ? evaluateDeclarativeValue(entryRecord.expr, recordData, locale)
1433
+ : isDeclarativeValueExpr(entryRecord.value)
1434
+ ? evaluateDeclarativeValue(entryRecord.value, recordData, locale)
1435
+ : entryRecord.dataKey
1436
+ ? resolveDataPath(recordData, entryRecord.dataKey)
1437
+ : entryRecord.value;
1438
+ return Object.freeze({
1439
+ label:
1440
+ typeof entryRecord.label === 'object' &&
1441
+ entryRecord.label !== null &&
1442
+ ('zh' in entryRecord.label || 'en' in entryRecord.label || 'zh-CN' in entryRecord.label)
1443
+ ? resolveDeclarativeText(entryRecord.label as DeclarativeI18nText, locale)
1444
+ : formatRenderableValue(entryRecord.label),
1445
+ value: formatRenderableValue(resolvedValue),
1446
+ });
1447
+ })
1098
1448
  : Object.entries(rawEntries ?? {}).map(([k, v]) =>
1099
1449
  Object.freeze({
1100
1450
  label: k,
1101
- value: formatRenderableValue(v),
1451
+ value: formatRenderableValue(
1452
+ isDeclarativeValueExpr(v) ? evaluateDeclarativeValue(v, recordData, locale) : v,
1453
+ ),
1102
1454
  }),
1103
1455
  );
1104
1456
  entries.push(
@@ -1113,11 +1465,11 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1113
1465
  } else {
1114
1466
  for (const sec of bp.sections) {
1115
1467
  if (sec.type === 'table') {
1116
- const rawItems = sec.dataKey ? recordData[sec.dataKey] : undefined;
1468
+ const rawItems = sec.dataKey ? resolveDataPath(recordData, sec.dataKey) : undefined;
1117
1469
  const list = Array.isArray(rawItems) ? rawItems : [];
1118
1470
  const rows = list.slice(0, maxRows).map((row) => {
1119
1471
  const rec = (row && typeof row === 'object' ? row : {}) as Record<string, unknown>;
1120
- return sec.columns.map((c) => formatRenderableValue(rec[c.key]));
1472
+ return sec.columns.map((c) => formatRenderableValue(resolveDataPath(rec, c.key)));
1121
1473
  });
1122
1474
  tables.push(
1123
1475
  Object.freeze({
@@ -1128,6 +1480,28 @@ export function projectBlueprintToImCard<TData = Record<string, unknown>>(
1128
1480
  totalRows: list.length,
1129
1481
  }),
1130
1482
  );
1483
+ } else if (sec.type === 'entries' && Array.isArray(sec.entries)) {
1484
+ entries.push(
1485
+ Object.freeze({
1486
+ id: sec.id,
1487
+ title: sec.title,
1488
+ items: Object.freeze(
1489
+ sec.entries.map((entry) => {
1490
+ const resolvedValue = entry.expr
1491
+ ? evaluateDeclarativeValue(entry.expr, recordData, locale)
1492
+ : isDeclarativeValueExpr(entry.value)
1493
+ ? evaluateDeclarativeValue(entry.value, recordData, locale)
1494
+ : entry.dataKey
1495
+ ? resolveDataPath(recordData, entry.dataKey)
1496
+ : entry.value;
1497
+ return Object.freeze({
1498
+ label: formatRenderableValue(entry.label),
1499
+ value: formatRenderableValue(resolvedValue),
1500
+ });
1501
+ }),
1502
+ ),
1503
+ }),
1504
+ );
1131
1505
  }
1132
1506
  }
1133
1507
  }