@zhin.js/console-contract 1.1.6 → 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
@@ -98,7 +98,17 @@ export type DeclarativeValueExpr = {
98
98
  } | {
99
99
  readonly $coalesce: readonly string[];
100
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;
101
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;
102
112
  export declare function isDeclarativeValueExpr(value: unknown): value is DeclarativeValueExpr;
103
113
  export declare function resolveDataPath(data: unknown, path: string): unknown;
104
114
  export declare function evaluateDeclarativeValue(exprOrKey: unknown, data: unknown, locale?: DeclarativeUiLocale): unknown;
@@ -148,7 +158,14 @@ export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
148
158
  export interface DeclarativeActionFieldSpec {
149
159
  readonly key: string;
150
160
  readonly label: DeclarativeI18nText;
151
- 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')[];
152
169
  readonly options?: readonly {
153
170
  readonly value: string;
154
171
  readonly label: DeclarativeI18nText;
@@ -179,8 +196,23 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
179
196
  readonly params?: Readonly<Record<string, unknown>> | ((data: TData | undefined, values: Readonly<Record<string, string>>) => Readonly<Record<string, unknown>>);
180
197
  readonly disabled?: boolean | ((data: TData | undefined) => boolean);
181
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
+ }[];
182
212
  }
183
- 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';
184
216
  export interface DeclarativeColumnSpec<TRow = Record<string, unknown>, TData = Record<string, unknown>> {
185
217
  readonly key: keyof TRow & string;
186
218
  readonly label: DeclarativeI18nText;
@@ -246,6 +278,14 @@ export interface DeclarativeSectionSpec<TData = Record<string, unknown>, TRow =
246
278
  readonly label: DeclarativeI18nText;
247
279
  readonly value?: DeclarativeRenderable | DeclarativeValueExpr;
248
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
+ };
249
289
  }[] | ((data: TData, ctx: DeclarativePageContext<TData>) => Readonly<Record<string, DeclarativeRenderable>> | readonly {
250
290
  readonly label: DeclarativeRenderable;
251
291
  readonly value: DeclarativeRenderable;
package/lib/page.js CHANGED
@@ -179,6 +179,15 @@ function pageTitleTranslations(value) {
179
179
  }
180
180
  return Object.freeze(output);
181
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
+ }
182
191
  export function isDeclarativeValueExpr(value) {
183
192
  if (!value || typeof value !== 'object' || Array.isArray(value))
184
193
  return false;
@@ -189,7 +198,8 @@ export function isDeclarativeValueExpr(value) {
189
198
  (rec.$format !== undefined && Array.isArray(rec.$args ?? rec.args)) ||
190
199
  (rec.$map !== null && typeof rec.$map === 'object') ||
191
200
  (rec.$join !== null && typeof rec.$join === 'object') ||
192
- Array.isArray(rec.$coalesce));
201
+ Array.isArray(rec.$coalesce) ||
202
+ typeof rec.$i18n === 'string');
193
203
  }
194
204
  export function resolveDataPath(data, path) {
195
205
  if (!data || typeof data !== 'object' || !path)
@@ -293,6 +303,10 @@ export function evaluateDeclarativeValue(exprOrKey, data, locale = 'en') {
293
303
  }
294
304
  return rec.fallback;
295
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
+ }
296
310
  return undefined;
297
311
  }
298
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.6",
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
@@ -272,7 +272,21 @@ export type DeclarativeValueExpr =
272
272
  readonly empty?: DeclarativeI18nText;
273
273
  };
274
274
  }
275
- | { 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
+ }
276
290
 
277
291
  export function isDeclarativeValueExpr(value: unknown): value is DeclarativeValueExpr {
278
292
  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
@@ -284,7 +298,8 @@ export function isDeclarativeValueExpr(value: unknown): value is DeclarativeValu
284
298
  (rec.$format !== undefined && Array.isArray(rec.$args ?? rec.args)) ||
285
299
  (rec.$map !== null && typeof rec.$map === 'object') ||
286
300
  (rec.$join !== null && typeof rec.$join === 'object') ||
287
- Array.isArray(rec.$coalesce)
301
+ Array.isArray(rec.$coalesce) ||
302
+ typeof rec.$i18n === 'string'
288
303
  );
289
304
  }
290
305
 
@@ -392,6 +407,10 @@ export function evaluateDeclarativeValue(
392
407
  }
393
408
  return rec.fallback;
394
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
+ }
395
414
  return undefined;
396
415
  }
397
416
 
@@ -466,7 +485,16 @@ export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
466
485
  export interface DeclarativeActionFieldSpec {
467
486
  readonly key: string;
468
487
  readonly label: DeclarativeI18nText;
469
- 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')[];
470
498
  readonly options?: readonly {
471
499
  readonly value: string;
472
500
  readonly label: DeclarativeI18nText;
@@ -503,6 +531,20 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
503
531
  ) => Readonly<Record<string, unknown>>);
504
532
  readonly disabled?: boolean | ((data: TData | undefined) => boolean);
505
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
+ }[];
506
548
  }
507
549
 
508
550
  export type DeclarativeColumnType =
@@ -516,7 +558,9 @@ export type DeclarativeColumnType =
516
558
  | 'number'
517
559
  | 'progress'
518
560
  | 'tags'
519
- | 'json';
561
+ | 'json'
562
+ /** A conversation key (`["conversation-v1", …]`) or `DeliveryTarget`, shown by its Console display name. */
563
+ | 'conversation';
520
564
 
521
565
  export interface DeclarativeColumnSpec<
522
566
  TRow = Record<string, unknown>,
@@ -627,6 +671,14 @@ export interface DeclarativeSectionSpec<
627
671
  readonly label: DeclarativeI18nText;
628
672
  readonly value?: DeclarativeRenderable | DeclarativeValueExpr;
629
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
+ };
630
682
  }[]
631
683
  | ((
632
684
  data: TData,