@zhin.js/console-contract 1.1.5 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/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;
@@ -81,7 +98,17 @@ export type DeclarativeValueExpr = {
81
98
  } | {
82
99
  readonly $coalesce: readonly string[];
83
100
  readonly fallback?: string | number | boolean;
101
+ }
102
+ /**
103
+ * A value the status RPC already localized: `data[path]` is `{ 'zh-CN': …, en: … }` (or a plain
104
+ * string), and the viewer's locale picks one, falling back to `zh-CN` / `zh`.
105
+ */
106
+ | {
107
+ readonly $i18n: string;
108
+ readonly fallback?: string | number | boolean;
84
109
  };
110
+ /** Picks the viewer's locale from a `{ 'zh-CN' | zh | en: … }` record; plain values pass through. */
111
+ export declare function pickLocalizedDataValue(value: unknown, locale: DeclarativeUiLocale): unknown;
85
112
  export declare function isDeclarativeValueExpr(value: unknown): value is DeclarativeValueExpr;
86
113
  export declare function resolveDataPath(data: unknown, path: string): unknown;
87
114
  export declare function evaluateDeclarativeValue(exprOrKey: unknown, data: unknown, locale?: DeclarativeUiLocale): unknown;
@@ -131,7 +158,14 @@ export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
131
158
  export interface DeclarativeActionFieldSpec {
132
159
  readonly key: string;
133
160
  readonly label: DeclarativeI18nText;
134
- readonly type?: 'text' | 'password' | 'number' | 'textarea' | 'select' | 'switch' | 'radio' | 'checkbox-group' | 'segmented';
161
+ /**
162
+ * `date` / `time` render native pickers and submit `YYYY-MM-DD` / `HH:mm`. `conversation`
163
+ * renders the Console conversation picker (accounts and recent conversations, with manual entry
164
+ * as an advanced option) and submits the chosen canonical `DeliveryTarget` as a JSON string.
165
+ */
166
+ readonly type?: 'text' | 'password' | 'number' | 'textarea' | 'select' | 'switch' | 'radio' | 'checkbox-group' | 'segmented' | 'date' | 'time' | 'conversation';
167
+ /** `conversation` fields only: the conversation kinds the action accepts (default: all). */
168
+ readonly conversationKinds?: readonly ('private' | 'group' | 'channel')[];
135
169
  readonly options?: readonly {
136
170
  readonly value: string;
137
171
  readonly label: DeclarativeI18nText;
@@ -162,8 +196,23 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
162
196
  readonly params?: Readonly<Record<string, unknown>> | ((data: TData | undefined, values: Readonly<Record<string, string>>) => Readonly<Record<string, unknown>>);
163
197
  readonly disabled?: boolean | ((data: TData | undefined) => boolean);
164
198
  readonly successMessage?: DeclarativeI18nText;
199
+ /**
200
+ * Shows the RPC's answer inline, right under this action's form, instead of a page-top banner.
201
+ * Expressions read the action's result object (not the page status).
202
+ */
203
+ readonly result?: DeclarativeActionResultSpec;
204
+ }
205
+ export interface DeclarativeActionResultSpec {
206
+ readonly title?: DeclarativeI18nText | DeclarativeValueExpr;
207
+ readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr;
208
+ readonly entries?: readonly {
209
+ readonly label: DeclarativeI18nText;
210
+ readonly value: string | DeclarativeValueExpr;
211
+ }[];
165
212
  }
166
- export type DeclarativeColumnType = 'auto' | 'text' | 'code' | 'badge' | 'boolean' | 'link' | 'datetime' | 'number' | 'progress' | 'tags' | 'json';
213
+ export type DeclarativeColumnType = 'auto' | 'text' | 'code' | 'badge' | 'boolean' | 'link' | 'datetime' | 'number' | 'progress' | 'tags' | 'json'
214
+ /** A conversation key (`["conversation-v1", …]`) or `DeliveryTarget`, shown by its Console display name. */
215
+ | 'conversation';
167
216
  export interface DeclarativeColumnSpec<TRow = Record<string, unknown>, TData = Record<string, unknown>> {
168
217
  readonly key: keyof TRow & string;
169
218
  readonly label: DeclarativeI18nText;
@@ -229,6 +278,14 @@ export interface DeclarativeSectionSpec<TData = Record<string, unknown>, TRow =
229
278
  readonly label: DeclarativeI18nText;
230
279
  readonly value?: DeclarativeRenderable | DeclarativeValueExpr;
231
280
  readonly dataKey?: string;
281
+ readonly hint?: DeclarativeI18nText;
282
+ /** Greys the value out when truthy (e.g. a schedule that is configured but switched off). */
283
+ readonly muted?: boolean | DeclarativeValueExpr;
284
+ /** A badge next to the value, e.g. 「未启用」. An empty label hides it. */
285
+ readonly badge?: {
286
+ readonly label: DeclarativeI18nText | DeclarativeValueExpr;
287
+ readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr;
288
+ };
232
289
  }[] | ((data: TData, ctx: DeclarativePageContext<TData>) => Readonly<Record<string, DeclarativeRenderable>> | readonly {
233
290
  readonly label: DeclarativeRenderable;
234
291
  readonly value: DeclarativeRenderable;
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`);
@@ -19,7 +39,25 @@ export function isConsoleBlueprint(value) {
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,15 @@ function pageTitleTranslations(value) {
141
179
  }
142
180
  return Object.freeze(output);
143
181
  }
182
+ /** Picks the viewer's locale from a `{ 'zh-CN' | zh | en: … }` record; plain values pass through. */
183
+ export function pickLocalizedDataValue(value, locale) {
184
+ if (!value || typeof value !== 'object' || Array.isArray(value))
185
+ return value;
186
+ const record = value;
187
+ return locale === 'en'
188
+ ? record.en ?? record['zh-CN'] ?? record.zh
189
+ : record['zh-CN'] ?? record.zh ?? record.en;
190
+ }
144
191
  export function isDeclarativeValueExpr(value) {
145
192
  if (!value || typeof value !== 'object' || Array.isArray(value))
146
193
  return false;
@@ -151,7 +198,8 @@ export function isDeclarativeValueExpr(value) {
151
198
  (rec.$format !== undefined && Array.isArray(rec.$args ?? rec.args)) ||
152
199
  (rec.$map !== null && typeof rec.$map === 'object') ||
153
200
  (rec.$join !== null && typeof rec.$join === 'object') ||
154
- Array.isArray(rec.$coalesce));
201
+ Array.isArray(rec.$coalesce) ||
202
+ typeof rec.$i18n === 'string');
155
203
  }
156
204
  export function resolveDataPath(data, path) {
157
205
  if (!data || typeof data !== 'object' || !path)
@@ -255,6 +303,10 @@ export function evaluateDeclarativeValue(exprOrKey, data, locale = 'en') {
255
303
  }
256
304
  return rec.fallback;
257
305
  }
306
+ if (typeof rec.$i18n === 'string') {
307
+ const val = pickLocalizedDataValue(resolveDataPath(data, rec.$i18n), locale);
308
+ return val !== undefined && val !== null && val !== '' ? val : rec.fallback;
309
+ }
258
310
  return undefined;
259
311
  }
260
312
  export function resolveDeclarativeText(text, preferredLocale = 'en') {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhin.js/console-contract",
3
- "version": "1.1.5",
3
+ "version": "1.2.0",
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
@@ -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 {
@@ -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(
@@ -223,7 +272,21 @@ export type DeclarativeValueExpr =
223
272
  readonly empty?: DeclarativeI18nText;
224
273
  };
225
274
  }
226
- | { readonly $coalesce: readonly string[]; readonly fallback?: string | number | boolean };
275
+ | { readonly $coalesce: readonly string[]; readonly fallback?: string | number | boolean }
276
+ /**
277
+ * A value the status RPC already localized: `data[path]` is `{ 'zh-CN': …, en: … }` (or a plain
278
+ * string), and the viewer's locale picks one, falling back to `zh-CN` / `zh`.
279
+ */
280
+ | { readonly $i18n: string; readonly fallback?: string | number | boolean };
281
+
282
+ /** Picks the viewer's locale from a `{ 'zh-CN' | zh | en: … }` record; plain values pass through. */
283
+ export function pickLocalizedDataValue(value: unknown, locale: DeclarativeUiLocale): unknown {
284
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
285
+ const record = value as Record<string, unknown>;
286
+ return locale === 'en'
287
+ ? record.en ?? record['zh-CN'] ?? record.zh
288
+ : record['zh-CN'] ?? record.zh ?? record.en;
289
+ }
227
290
 
228
291
  export function isDeclarativeValueExpr(value: unknown): value is DeclarativeValueExpr {
229
292
  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
@@ -235,7 +298,8 @@ export function isDeclarativeValueExpr(value: unknown): value is DeclarativeValu
235
298
  (rec.$format !== undefined && Array.isArray(rec.$args ?? rec.args)) ||
236
299
  (rec.$map !== null && typeof rec.$map === 'object') ||
237
300
  (rec.$join !== null && typeof rec.$join === 'object') ||
238
- Array.isArray(rec.$coalesce)
301
+ Array.isArray(rec.$coalesce) ||
302
+ typeof rec.$i18n === 'string'
239
303
  );
240
304
  }
241
305
 
@@ -343,6 +407,10 @@ export function evaluateDeclarativeValue(
343
407
  }
344
408
  return rec.fallback;
345
409
  }
410
+ if (typeof rec.$i18n === 'string') {
411
+ const val = pickLocalizedDataValue(resolveDataPath(data, rec.$i18n), locale);
412
+ return val !== undefined && val !== null && val !== '' ? val : rec.fallback;
413
+ }
346
414
  return undefined;
347
415
  }
348
416
 
@@ -417,7 +485,16 @@ export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
417
485
  export interface DeclarativeActionFieldSpec {
418
486
  readonly key: string;
419
487
  readonly label: DeclarativeI18nText;
420
- readonly type?: 'text' | 'password' | 'number' | 'textarea' | 'select' | 'switch' | 'radio' | 'checkbox-group' | 'segmented';
488
+ /**
489
+ * `date` / `time` render native pickers and submit `YYYY-MM-DD` / `HH:mm`. `conversation`
490
+ * renders the Console conversation picker (accounts and recent conversations, with manual entry
491
+ * as an advanced option) and submits the chosen canonical `DeliveryTarget` as a JSON string.
492
+ */
493
+ readonly type?:
494
+ | 'text' | 'password' | 'number' | 'textarea' | 'select' | 'switch' | 'radio' | 'checkbox-group' | 'segmented'
495
+ | 'date' | 'time' | 'conversation';
496
+ /** `conversation` fields only: the conversation kinds the action accepts (default: all). */
497
+ readonly conversationKinds?: readonly ('private' | 'group' | 'channel')[];
421
498
  readonly options?: readonly {
422
499
  readonly value: string;
423
500
  readonly label: DeclarativeI18nText;
@@ -454,6 +531,20 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
454
531
  ) => Readonly<Record<string, unknown>>);
455
532
  readonly disabled?: boolean | ((data: TData | undefined) => boolean);
456
533
  readonly successMessage?: DeclarativeI18nText;
534
+ /**
535
+ * Shows the RPC's answer inline, right under this action's form, instead of a page-top banner.
536
+ * Expressions read the action's result object (not the page status).
537
+ */
538
+ readonly result?: DeclarativeActionResultSpec;
539
+ }
540
+
541
+ export interface DeclarativeActionResultSpec {
542
+ readonly title?: DeclarativeI18nText | DeclarativeValueExpr;
543
+ readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr;
544
+ readonly entries?: readonly {
545
+ readonly label: DeclarativeI18nText;
546
+ readonly value: string | DeclarativeValueExpr;
547
+ }[];
457
548
  }
458
549
 
459
550
  export type DeclarativeColumnType =
@@ -467,7 +558,9 @@ export type DeclarativeColumnType =
467
558
  | 'number'
468
559
  | 'progress'
469
560
  | 'tags'
470
- | 'json';
561
+ | 'json'
562
+ /** A conversation key (`["conversation-v1", …]`) or `DeliveryTarget`, shown by its Console display name. */
563
+ | 'conversation';
471
564
 
472
565
  export interface DeclarativeColumnSpec<
473
566
  TRow = Record<string, unknown>,
@@ -578,6 +671,14 @@ export interface DeclarativeSectionSpec<
578
671
  readonly label: DeclarativeI18nText;
579
672
  readonly value?: DeclarativeRenderable | DeclarativeValueExpr;
580
673
  readonly dataKey?: string;
674
+ readonly hint?: DeclarativeI18nText;
675
+ /** Greys the value out when truthy (e.g. a schedule that is configured but switched off). */
676
+ readonly muted?: boolean | DeclarativeValueExpr;
677
+ /** A badge next to the value, e.g. 「未启用」. An empty label hides it. */
678
+ readonly badge?: {
679
+ readonly label: DeclarativeI18nText | DeclarativeValueExpr;
680
+ readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr;
681
+ };
581
682
  }[]
582
683
  | ((
583
684
  data: TData,