@zhin.js/console-contract 1.1.6 → 1.3.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 +64 -2
- package/lib/page.js +70 -2
- package/package.json +1 -1
- package/src/page.ts +124 -5
package/lib/page.d.ts
CHANGED
|
@@ -8,6 +8,20 @@ export type ConsolePageSection = (typeof CONSOLE_PAGE_SECTIONS)[number];
|
|
|
8
8
|
export declare function isConsolePageSection(value: unknown): value is ConsolePageSection;
|
|
9
9
|
/** Validates an optional `section`; throws for anything outside {@link CONSOLE_PAGE_SECTIONS}. */
|
|
10
10
|
export declare function optionalPageSection(value: unknown): ConsolePageSection | undefined;
|
|
11
|
+
/** Locales `keywords` can be given per language for (same as `titleI18n`). */
|
|
12
|
+
export type PageKeywordLocale = 'zh-CN' | 'en';
|
|
13
|
+
/**
|
|
14
|
+
* Search aliases of a page for the Console command palette (ADR 0063 决策 3 第 3 条): one list for
|
|
15
|
+
* every language, or lists per language (e.g. `{ 'zh-CN': ['抽奖'], en: ['lottery'] }`).
|
|
16
|
+
*/
|
|
17
|
+
export type PageKeywords = readonly string[] | Readonly<Partial<Record<PageKeywordLocale, readonly string[]>>>;
|
|
18
|
+
/**
|
|
19
|
+
* Validates an optional `keywords` value and returns it trimmed, de-duplicated and frozen;
|
|
20
|
+
* throws for anything else. Per-language objects accept only `zh-CN` and `en`.
|
|
21
|
+
*/
|
|
22
|
+
export declare function optionalPageKeywords(value: unknown): PageKeywords | undefined;
|
|
23
|
+
/** Keywords for one locale: a plain list applies to every locale; missing locales give `[]`. */
|
|
24
|
+
export declare function pageKeywordsFor(keywords: PageKeywords | undefined, locale: PageKeywordLocale): readonly string[];
|
|
11
25
|
export interface PageMetadata {
|
|
12
26
|
readonly title?: string;
|
|
13
27
|
/** Explicit display titles; missing locales retain title. */
|
|
@@ -24,6 +38,8 @@ export interface PageMetadata {
|
|
|
24
38
|
readonly fullWidth?: boolean;
|
|
25
39
|
/** Console navigation section (ADR 0052); omitted → the Console's default for plugin pages. */
|
|
26
40
|
readonly section?: ConsolePageSection;
|
|
41
|
+
/** Search aliases for the Console command palette, optionally per language (ADR 0063). */
|
|
42
|
+
readonly keywords?: PageKeywords;
|
|
27
43
|
}
|
|
28
44
|
export interface NormalizedPageMetadata {
|
|
29
45
|
readonly title: string;
|
|
@@ -51,6 +67,12 @@ export interface PageManifest extends NormalizedPageMetadata {
|
|
|
51
67
|
readonly hash: string;
|
|
52
68
|
readonly route: string;
|
|
53
69
|
readonly blueprint?: ConsolePageBlueprint | ConsoleAdapterPageBlueprint;
|
|
70
|
+
/** Command-palette aliases from `definePage({ keywords })` (ADR 0063). */
|
|
71
|
+
readonly keywords?: PageKeywords;
|
|
72
|
+
/** npm package of the owning plugin (for the command palette's plugin entries). */
|
|
73
|
+
readonly packageName?: string;
|
|
74
|
+
/** `description` from the owning plugin's package.json. */
|
|
75
|
+
readonly pluginDescription?: string;
|
|
54
76
|
}
|
|
55
77
|
export declare function definePage(metadata?: PageMetadata): Readonly<PageMetadata>;
|
|
56
78
|
export declare function normalizePageMetadata(localName: string, metadata: unknown): Readonly<NormalizedPageMetadata>;
|
|
@@ -98,7 +120,17 @@ export type DeclarativeValueExpr = {
|
|
|
98
120
|
} | {
|
|
99
121
|
readonly $coalesce: readonly string[];
|
|
100
122
|
readonly fallback?: string | number | boolean;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* A value the status RPC already localized: `data[path]` is `{ 'zh-CN': …, en: … }` (or a plain
|
|
126
|
+
* string), and the viewer's locale picks one, falling back to `zh-CN` / `zh`.
|
|
127
|
+
*/
|
|
128
|
+
| {
|
|
129
|
+
readonly $i18n: string;
|
|
130
|
+
readonly fallback?: string | number | boolean;
|
|
101
131
|
};
|
|
132
|
+
/** Picks the viewer's locale from a `{ 'zh-CN' | zh | en: … }` record; plain values pass through. */
|
|
133
|
+
export declare function pickLocalizedDataValue(value: unknown, locale: DeclarativeUiLocale): unknown;
|
|
102
134
|
export declare function isDeclarativeValueExpr(value: unknown): value is DeclarativeValueExpr;
|
|
103
135
|
export declare function resolveDataPath(data: unknown, path: string): unknown;
|
|
104
136
|
export declare function evaluateDeclarativeValue(exprOrKey: unknown, data: unknown, locale?: DeclarativeUiLocale): unknown;
|
|
@@ -148,7 +180,14 @@ export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
|
|
|
148
180
|
export interface DeclarativeActionFieldSpec {
|
|
149
181
|
readonly key: string;
|
|
150
182
|
readonly label: DeclarativeI18nText;
|
|
151
|
-
|
|
183
|
+
/**
|
|
184
|
+
* `date` / `time` render native pickers and submit `YYYY-MM-DD` / `HH:mm`. `conversation`
|
|
185
|
+
* renders the Console conversation picker (accounts and recent conversations, with manual entry
|
|
186
|
+
* as an advanced option) and submits the chosen canonical `DeliveryTarget` as a JSON string.
|
|
187
|
+
*/
|
|
188
|
+
readonly type?: 'text' | 'password' | 'number' | 'textarea' | 'select' | 'switch' | 'radio' | 'checkbox-group' | 'segmented' | 'date' | 'time' | 'conversation';
|
|
189
|
+
/** `conversation` fields only: the conversation kinds the action accepts (default: all). */
|
|
190
|
+
readonly conversationKinds?: readonly ('private' | 'group' | 'channel')[];
|
|
152
191
|
readonly options?: readonly {
|
|
153
192
|
readonly value: string;
|
|
154
193
|
readonly label: DeclarativeI18nText;
|
|
@@ -179,8 +218,23 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
|
|
|
179
218
|
readonly params?: Readonly<Record<string, unknown>> | ((data: TData | undefined, values: Readonly<Record<string, string>>) => Readonly<Record<string, unknown>>);
|
|
180
219
|
readonly disabled?: boolean | ((data: TData | undefined) => boolean);
|
|
181
220
|
readonly successMessage?: DeclarativeI18nText;
|
|
221
|
+
/**
|
|
222
|
+
* Shows the RPC's answer inline, right under this action's form, instead of a page-top banner.
|
|
223
|
+
* Expressions read the action's result object (not the page status).
|
|
224
|
+
*/
|
|
225
|
+
readonly result?: DeclarativeActionResultSpec;
|
|
226
|
+
}
|
|
227
|
+
export interface DeclarativeActionResultSpec {
|
|
228
|
+
readonly title?: DeclarativeI18nText | DeclarativeValueExpr;
|
|
229
|
+
readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr;
|
|
230
|
+
readonly entries?: readonly {
|
|
231
|
+
readonly label: DeclarativeI18nText;
|
|
232
|
+
readonly value: string | DeclarativeValueExpr;
|
|
233
|
+
}[];
|
|
182
234
|
}
|
|
183
|
-
export type DeclarativeColumnType = 'auto' | 'text' | 'code' | 'badge' | 'boolean' | 'link' | 'datetime' | 'number' | 'progress' | 'tags' | 'json'
|
|
235
|
+
export type DeclarativeColumnType = 'auto' | 'text' | 'code' | 'badge' | 'boolean' | 'link' | 'datetime' | 'number' | 'progress' | 'tags' | 'json'
|
|
236
|
+
/** A conversation key (`["conversation-v1", …]`) or `DeliveryTarget`, shown by its Console display name. */
|
|
237
|
+
| 'conversation';
|
|
184
238
|
export interface DeclarativeColumnSpec<TRow = Record<string, unknown>, TData = Record<string, unknown>> {
|
|
185
239
|
readonly key: keyof TRow & string;
|
|
186
240
|
readonly label: DeclarativeI18nText;
|
|
@@ -246,6 +300,14 @@ export interface DeclarativeSectionSpec<TData = Record<string, unknown>, TRow =
|
|
|
246
300
|
readonly label: DeclarativeI18nText;
|
|
247
301
|
readonly value?: DeclarativeRenderable | DeclarativeValueExpr;
|
|
248
302
|
readonly dataKey?: string;
|
|
303
|
+
readonly hint?: DeclarativeI18nText;
|
|
304
|
+
/** Greys the value out when truthy (e.g. a schedule that is configured but switched off). */
|
|
305
|
+
readonly muted?: boolean | DeclarativeValueExpr;
|
|
306
|
+
/** A badge next to the value, e.g. 「未启用」. An empty label hides it. */
|
|
307
|
+
readonly badge?: {
|
|
308
|
+
readonly label: DeclarativeI18nText | DeclarativeValueExpr;
|
|
309
|
+
readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr;
|
|
310
|
+
};
|
|
249
311
|
}[] | ((data: TData, ctx: DeclarativePageContext<TData>) => Readonly<Record<string, DeclarativeRenderable>> | readonly {
|
|
250
312
|
readonly label: DeclarativeRenderable;
|
|
251
313
|
readonly value: DeclarativeRenderable;
|
package/lib/page.js
CHANGED
|
@@ -18,6 +18,58 @@ export function optionalPageSection(value) {
|
|
|
18
18
|
}
|
|
19
19
|
return value;
|
|
20
20
|
}
|
|
21
|
+
const PAGE_KEYWORD_LOCALES = ['zh-CN', 'en'];
|
|
22
|
+
const MAX_PAGE_KEYWORDS = 32;
|
|
23
|
+
const MAX_PAGE_KEYWORD_LENGTH = 64;
|
|
24
|
+
function keywordList(value, label) {
|
|
25
|
+
if (!Array.isArray(value))
|
|
26
|
+
throw new TypeError(`${label} must be an array of strings`);
|
|
27
|
+
const out = [];
|
|
28
|
+
for (const item of value) {
|
|
29
|
+
if (typeof item !== 'string' || !item.trim())
|
|
30
|
+
throw new TypeError(`${label} must contain non-empty strings`);
|
|
31
|
+
const keyword = item.trim();
|
|
32
|
+
if (keyword.length > MAX_PAGE_KEYWORD_LENGTH) {
|
|
33
|
+
throw new TypeError(`${label} entries must be at most ${MAX_PAGE_KEYWORD_LENGTH} characters`);
|
|
34
|
+
}
|
|
35
|
+
if (!out.includes(keyword))
|
|
36
|
+
out.push(keyword);
|
|
37
|
+
}
|
|
38
|
+
if (out.length > MAX_PAGE_KEYWORDS)
|
|
39
|
+
throw new TypeError(`${label} may list at most ${MAX_PAGE_KEYWORDS} keywords`);
|
|
40
|
+
return Object.freeze(out);
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Validates an optional `keywords` value and returns it trimmed, de-duplicated and frozen;
|
|
44
|
+
* throws for anything else. Per-language objects accept only `zh-CN` and `en`.
|
|
45
|
+
*/
|
|
46
|
+
export function optionalPageKeywords(value) {
|
|
47
|
+
if (value === undefined)
|
|
48
|
+
return undefined;
|
|
49
|
+
if (Array.isArray(value))
|
|
50
|
+
return keywordList(value, 'Page keywords');
|
|
51
|
+
if (!value || typeof value !== 'object') {
|
|
52
|
+
throw new TypeError('Page keywords must be an array of strings or an object keyed by zh-CN / en');
|
|
53
|
+
}
|
|
54
|
+
const input = value;
|
|
55
|
+
const unknownLocales = Object.keys(input).filter((key) => !PAGE_KEYWORD_LOCALES.includes(key));
|
|
56
|
+
if (unknownLocales.length > 0)
|
|
57
|
+
throw new TypeError(`Unknown Page keywords locale: ${unknownLocales.sort().join(', ')}`);
|
|
58
|
+
const out = {};
|
|
59
|
+
for (const locale of PAGE_KEYWORD_LOCALES) {
|
|
60
|
+
if (input[locale] !== undefined)
|
|
61
|
+
out[locale] = keywordList(input[locale], `Page keywords.${locale}`);
|
|
62
|
+
}
|
|
63
|
+
return Object.freeze(out);
|
|
64
|
+
}
|
|
65
|
+
/** Keywords for one locale: a plain list applies to every locale; missing locales give `[]`. */
|
|
66
|
+
export function pageKeywordsFor(keywords, locale) {
|
|
67
|
+
if (!keywords)
|
|
68
|
+
return [];
|
|
69
|
+
if (Array.isArray(keywords))
|
|
70
|
+
return keywords;
|
|
71
|
+
return keywords[locale] ?? [];
|
|
72
|
+
}
|
|
21
73
|
export function normalizeClientModuleArtifact(value, label) {
|
|
22
74
|
const input = requireRecord(value, label);
|
|
23
75
|
const module = optionalString(input.module, `${label} module`);
|
|
@@ -40,8 +92,9 @@ export function isConsoleBlueprint(value) {
|
|
|
40
92
|
}
|
|
41
93
|
export function definePage(metadata = {}) {
|
|
42
94
|
// 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');
|
|
95
|
+
const { description, group, parent, fullWidth, section: rawSection, keywords: rawKeywords, ...base } = requireRecord(metadata, 'Page metadata');
|
|
44
96
|
const section = optionalPageSection(rawSection);
|
|
97
|
+
const keywords = optionalPageKeywords(rawKeywords);
|
|
45
98
|
for (const [key, value] of [['description', description], ['group', group], ['parent', parent]]) {
|
|
46
99
|
if (value !== undefined && (typeof value !== 'string' || !value.trim())) {
|
|
47
100
|
throw new TypeError(`Page ${key} must be a non-empty string`);
|
|
@@ -57,6 +110,7 @@ export function definePage(metadata = {}) {
|
|
|
57
110
|
...(parent !== undefined ? { parent: parent } : {}),
|
|
58
111
|
...(fullWidth !== undefined ? { fullWidth } : {}),
|
|
59
112
|
...(section !== undefined ? { section } : {}),
|
|
113
|
+
...(keywords !== undefined ? { keywords } : {}),
|
|
60
114
|
});
|
|
61
115
|
}
|
|
62
116
|
export function normalizePageMetadata(localName, metadata) {
|
|
@@ -179,6 +233,15 @@ function pageTitleTranslations(value) {
|
|
|
179
233
|
}
|
|
180
234
|
return Object.freeze(output);
|
|
181
235
|
}
|
|
236
|
+
/** Picks the viewer's locale from a `{ 'zh-CN' | zh | en: … }` record; plain values pass through. */
|
|
237
|
+
export function pickLocalizedDataValue(value, locale) {
|
|
238
|
+
if (!value || typeof value !== 'object' || Array.isArray(value))
|
|
239
|
+
return value;
|
|
240
|
+
const record = value;
|
|
241
|
+
return locale === 'en'
|
|
242
|
+
? record.en ?? record['zh-CN'] ?? record.zh
|
|
243
|
+
: record['zh-CN'] ?? record.zh ?? record.en;
|
|
244
|
+
}
|
|
182
245
|
export function isDeclarativeValueExpr(value) {
|
|
183
246
|
if (!value || typeof value !== 'object' || Array.isArray(value))
|
|
184
247
|
return false;
|
|
@@ -189,7 +252,8 @@ export function isDeclarativeValueExpr(value) {
|
|
|
189
252
|
(rec.$format !== undefined && Array.isArray(rec.$args ?? rec.args)) ||
|
|
190
253
|
(rec.$map !== null && typeof rec.$map === 'object') ||
|
|
191
254
|
(rec.$join !== null && typeof rec.$join === 'object') ||
|
|
192
|
-
Array.isArray(rec.$coalesce)
|
|
255
|
+
Array.isArray(rec.$coalesce) ||
|
|
256
|
+
typeof rec.$i18n === 'string');
|
|
193
257
|
}
|
|
194
258
|
export function resolveDataPath(data, path) {
|
|
195
259
|
if (!data || typeof data !== 'object' || !path)
|
|
@@ -293,6 +357,10 @@ export function evaluateDeclarativeValue(exprOrKey, data, locale = 'en') {
|
|
|
293
357
|
}
|
|
294
358
|
return rec.fallback;
|
|
295
359
|
}
|
|
360
|
+
if (typeof rec.$i18n === 'string') {
|
|
361
|
+
const val = pickLocalizedDataValue(resolveDataPath(data, rec.$i18n), locale);
|
|
362
|
+
return val !== undefined && val !== null && val !== '' ? val : rec.fallback;
|
|
363
|
+
}
|
|
296
364
|
return undefined;
|
|
297
365
|
}
|
|
298
366
|
export function resolveDeclarativeText(text, preferredLocale = 'en') {
|
package/package.json
CHANGED
package/src/page.ts
CHANGED
|
@@ -22,6 +22,63 @@ export function optionalPageSection(value: unknown): ConsolePageSection | undefi
|
|
|
22
22
|
return value;
|
|
23
23
|
}
|
|
24
24
|
|
|
25
|
+
/** Locales `keywords` can be given per language for (same as `titleI18n`). */
|
|
26
|
+
export type PageKeywordLocale = 'zh-CN' | 'en';
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Search aliases of a page for the Console command palette (ADR 0063 决策 3 第 3 条): one list for
|
|
30
|
+
* every language, or lists per language (e.g. `{ 'zh-CN': ['抽奖'], en: ['lottery'] }`).
|
|
31
|
+
*/
|
|
32
|
+
export type PageKeywords =
|
|
33
|
+
| readonly string[]
|
|
34
|
+
| Readonly<Partial<Record<PageKeywordLocale, readonly string[]>>>;
|
|
35
|
+
|
|
36
|
+
const PAGE_KEYWORD_LOCALES: readonly PageKeywordLocale[] = ['zh-CN', 'en'];
|
|
37
|
+
const MAX_PAGE_KEYWORDS = 32;
|
|
38
|
+
const MAX_PAGE_KEYWORD_LENGTH = 64;
|
|
39
|
+
|
|
40
|
+
function keywordList(value: unknown, label: string): readonly string[] {
|
|
41
|
+
if (!Array.isArray(value)) throw new TypeError(`${label} must be an array of strings`);
|
|
42
|
+
const out: string[] = [];
|
|
43
|
+
for (const item of value) {
|
|
44
|
+
if (typeof item !== 'string' || !item.trim()) throw new TypeError(`${label} must contain non-empty strings`);
|
|
45
|
+
const keyword = item.trim();
|
|
46
|
+
if (keyword.length > MAX_PAGE_KEYWORD_LENGTH) {
|
|
47
|
+
throw new TypeError(`${label} entries must be at most ${MAX_PAGE_KEYWORD_LENGTH} characters`);
|
|
48
|
+
}
|
|
49
|
+
if (!out.includes(keyword)) out.push(keyword);
|
|
50
|
+
}
|
|
51
|
+
if (out.length > MAX_PAGE_KEYWORDS) throw new TypeError(`${label} may list at most ${MAX_PAGE_KEYWORDS} keywords`);
|
|
52
|
+
return Object.freeze(out);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Validates an optional `keywords` value and returns it trimmed, de-duplicated and frozen;
|
|
57
|
+
* throws for anything else. Per-language objects accept only `zh-CN` and `en`.
|
|
58
|
+
*/
|
|
59
|
+
export function optionalPageKeywords(value: unknown): PageKeywords | undefined {
|
|
60
|
+
if (value === undefined) return undefined;
|
|
61
|
+
if (Array.isArray(value)) return keywordList(value, 'Page keywords');
|
|
62
|
+
if (!value || typeof value !== 'object') {
|
|
63
|
+
throw new TypeError('Page keywords must be an array of strings or an object keyed by zh-CN / en');
|
|
64
|
+
}
|
|
65
|
+
const input = value as Record<string, unknown>;
|
|
66
|
+
const unknownLocales = Object.keys(input).filter((key) => !(PAGE_KEYWORD_LOCALES as readonly string[]).includes(key));
|
|
67
|
+
if (unknownLocales.length > 0) throw new TypeError(`Unknown Page keywords locale: ${unknownLocales.sort().join(', ')}`);
|
|
68
|
+
const out: Partial<Record<PageKeywordLocale, readonly string[]>> = {};
|
|
69
|
+
for (const locale of PAGE_KEYWORD_LOCALES) {
|
|
70
|
+
if (input[locale] !== undefined) out[locale] = keywordList(input[locale], `Page keywords.${locale}`);
|
|
71
|
+
}
|
|
72
|
+
return Object.freeze(out);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Keywords for one locale: a plain list applies to every locale; missing locales give `[]`. */
|
|
76
|
+
export function pageKeywordsFor(keywords: PageKeywords | undefined, locale: PageKeywordLocale): readonly string[] {
|
|
77
|
+
if (!keywords) return [];
|
|
78
|
+
if (Array.isArray(keywords)) return keywords as readonly string[];
|
|
79
|
+
return (keywords as Readonly<Partial<Record<PageKeywordLocale, readonly string[]>>>)[locale] ?? [];
|
|
80
|
+
}
|
|
81
|
+
|
|
25
82
|
export interface PageMetadata {
|
|
26
83
|
readonly title?: string;
|
|
27
84
|
/** Explicit display titles; missing locales retain title. */
|
|
@@ -38,6 +95,8 @@ export interface PageMetadata {
|
|
|
38
95
|
readonly fullWidth?: boolean;
|
|
39
96
|
/** Console navigation section (ADR 0052); omitted → the Console's default for plugin pages. */
|
|
40
97
|
readonly section?: ConsolePageSection;
|
|
98
|
+
/** Search aliases for the Console command palette, optionally per language (ADR 0063). */
|
|
99
|
+
readonly keywords?: PageKeywords;
|
|
41
100
|
}
|
|
42
101
|
|
|
43
102
|
export interface NormalizedPageMetadata {
|
|
@@ -91,12 +150,19 @@ export interface PageManifest extends NormalizedPageMetadata {
|
|
|
91
150
|
readonly hash: string;
|
|
92
151
|
readonly route: string;
|
|
93
152
|
readonly blueprint?: ConsolePageBlueprint | ConsoleAdapterPageBlueprint;
|
|
153
|
+
/** Command-palette aliases from `definePage({ keywords })` (ADR 0063). */
|
|
154
|
+
readonly keywords?: PageKeywords;
|
|
155
|
+
/** npm package of the owning plugin (for the command palette's plugin entries). */
|
|
156
|
+
readonly packageName?: string;
|
|
157
|
+
/** `description` from the owning plugin's package.json. */
|
|
158
|
+
readonly pluginDescription?: string;
|
|
94
159
|
}
|
|
95
160
|
|
|
96
161
|
export function definePage(metadata: PageMetadata = {}): Readonly<PageMetadata> {
|
|
97
162
|
// 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');
|
|
163
|
+
const { description, group, parent, fullWidth, section: rawSection, keywords: rawKeywords, ...base } = requireRecord(metadata, 'Page metadata');
|
|
99
164
|
const section = optionalPageSection(rawSection);
|
|
165
|
+
const keywords = optionalPageKeywords(rawKeywords);
|
|
100
166
|
for (const [key, value] of [['description', description], ['group', group], ['parent', parent]] as const) {
|
|
101
167
|
if (value !== undefined && (typeof value !== 'string' || !value.trim())) {
|
|
102
168
|
throw new TypeError(`Page ${key} must be a non-empty string`);
|
|
@@ -112,6 +178,7 @@ export function definePage(metadata: PageMetadata = {}): Readonly<PageMetadata>
|
|
|
112
178
|
...(parent !== undefined ? { parent: parent as string } : {}),
|
|
113
179
|
...(fullWidth !== undefined ? { fullWidth } : {}),
|
|
114
180
|
...(section !== undefined ? { section } : {}),
|
|
181
|
+
...(keywords !== undefined ? { keywords } : {}),
|
|
115
182
|
});
|
|
116
183
|
}
|
|
117
184
|
|
|
@@ -272,7 +339,21 @@ export type DeclarativeValueExpr =
|
|
|
272
339
|
readonly empty?: DeclarativeI18nText;
|
|
273
340
|
};
|
|
274
341
|
}
|
|
275
|
-
| { readonly $coalesce: readonly string[]; readonly fallback?: string | number | boolean }
|
|
342
|
+
| { readonly $coalesce: readonly string[]; readonly fallback?: string | number | boolean }
|
|
343
|
+
/**
|
|
344
|
+
* A value the status RPC already localized: `data[path]` is `{ 'zh-CN': …, en: … }` (or a plain
|
|
345
|
+
* string), and the viewer's locale picks one, falling back to `zh-CN` / `zh`.
|
|
346
|
+
*/
|
|
347
|
+
| { readonly $i18n: string; readonly fallback?: string | number | boolean };
|
|
348
|
+
|
|
349
|
+
/** Picks the viewer's locale from a `{ 'zh-CN' | zh | en: … }` record; plain values pass through. */
|
|
350
|
+
export function pickLocalizedDataValue(value: unknown, locale: DeclarativeUiLocale): unknown {
|
|
351
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
|
|
352
|
+
const record = value as Record<string, unknown>;
|
|
353
|
+
return locale === 'en'
|
|
354
|
+
? record.en ?? record['zh-CN'] ?? record.zh
|
|
355
|
+
: record['zh-CN'] ?? record.zh ?? record.en;
|
|
356
|
+
}
|
|
276
357
|
|
|
277
358
|
export function isDeclarativeValueExpr(value: unknown): value is DeclarativeValueExpr {
|
|
278
359
|
if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
|
|
@@ -284,7 +365,8 @@ export function isDeclarativeValueExpr(value: unknown): value is DeclarativeValu
|
|
|
284
365
|
(rec.$format !== undefined && Array.isArray(rec.$args ?? rec.args)) ||
|
|
285
366
|
(rec.$map !== null && typeof rec.$map === 'object') ||
|
|
286
367
|
(rec.$join !== null && typeof rec.$join === 'object') ||
|
|
287
|
-
Array.isArray(rec.$coalesce)
|
|
368
|
+
Array.isArray(rec.$coalesce) ||
|
|
369
|
+
typeof rec.$i18n === 'string'
|
|
288
370
|
);
|
|
289
371
|
}
|
|
290
372
|
|
|
@@ -392,6 +474,10 @@ export function evaluateDeclarativeValue(
|
|
|
392
474
|
}
|
|
393
475
|
return rec.fallback;
|
|
394
476
|
}
|
|
477
|
+
if (typeof rec.$i18n === 'string') {
|
|
478
|
+
const val = pickLocalizedDataValue(resolveDataPath(data, rec.$i18n), locale);
|
|
479
|
+
return val !== undefined && val !== null && val !== '' ? val : rec.fallback;
|
|
480
|
+
}
|
|
395
481
|
return undefined;
|
|
396
482
|
}
|
|
397
483
|
|
|
@@ -466,7 +552,16 @@ export interface DeclarativeStatSpec<TData = Record<string, unknown>> {
|
|
|
466
552
|
export interface DeclarativeActionFieldSpec {
|
|
467
553
|
readonly key: string;
|
|
468
554
|
readonly label: DeclarativeI18nText;
|
|
469
|
-
|
|
555
|
+
/**
|
|
556
|
+
* `date` / `time` render native pickers and submit `YYYY-MM-DD` / `HH:mm`. `conversation`
|
|
557
|
+
* renders the Console conversation picker (accounts and recent conversations, with manual entry
|
|
558
|
+
* as an advanced option) and submits the chosen canonical `DeliveryTarget` as a JSON string.
|
|
559
|
+
*/
|
|
560
|
+
readonly type?:
|
|
561
|
+
| 'text' | 'password' | 'number' | 'textarea' | 'select' | 'switch' | 'radio' | 'checkbox-group' | 'segmented'
|
|
562
|
+
| 'date' | 'time' | 'conversation';
|
|
563
|
+
/** `conversation` fields only: the conversation kinds the action accepts (default: all). */
|
|
564
|
+
readonly conversationKinds?: readonly ('private' | 'group' | 'channel')[];
|
|
470
565
|
readonly options?: readonly {
|
|
471
566
|
readonly value: string;
|
|
472
567
|
readonly label: DeclarativeI18nText;
|
|
@@ -503,6 +598,20 @@ export interface DeclarativeActionSpec<TData = Record<string, unknown>> {
|
|
|
503
598
|
) => Readonly<Record<string, unknown>>);
|
|
504
599
|
readonly disabled?: boolean | ((data: TData | undefined) => boolean);
|
|
505
600
|
readonly successMessage?: DeclarativeI18nText;
|
|
601
|
+
/**
|
|
602
|
+
* Shows the RPC's answer inline, right under this action's form, instead of a page-top banner.
|
|
603
|
+
* Expressions read the action's result object (not the page status).
|
|
604
|
+
*/
|
|
605
|
+
readonly result?: DeclarativeActionResultSpec;
|
|
606
|
+
}
|
|
607
|
+
|
|
608
|
+
export interface DeclarativeActionResultSpec {
|
|
609
|
+
readonly title?: DeclarativeI18nText | DeclarativeValueExpr;
|
|
610
|
+
readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr;
|
|
611
|
+
readonly entries?: readonly {
|
|
612
|
+
readonly label: DeclarativeI18nText;
|
|
613
|
+
readonly value: string | DeclarativeValueExpr;
|
|
614
|
+
}[];
|
|
506
615
|
}
|
|
507
616
|
|
|
508
617
|
export type DeclarativeColumnType =
|
|
@@ -516,7 +625,9 @@ export type DeclarativeColumnType =
|
|
|
516
625
|
| 'number'
|
|
517
626
|
| 'progress'
|
|
518
627
|
| 'tags'
|
|
519
|
-
| 'json'
|
|
628
|
+
| 'json'
|
|
629
|
+
/** A conversation key (`["conversation-v1", …]`) or `DeliveryTarget`, shown by its Console display name. */
|
|
630
|
+
| 'conversation';
|
|
520
631
|
|
|
521
632
|
export interface DeclarativeColumnSpec<
|
|
522
633
|
TRow = Record<string, unknown>,
|
|
@@ -627,6 +738,14 @@ export interface DeclarativeSectionSpec<
|
|
|
627
738
|
readonly label: DeclarativeI18nText;
|
|
628
739
|
readonly value?: DeclarativeRenderable | DeclarativeValueExpr;
|
|
629
740
|
readonly dataKey?: string;
|
|
741
|
+
readonly hint?: DeclarativeI18nText;
|
|
742
|
+
/** Greys the value out when truthy (e.g. a schedule that is configured but switched off). */
|
|
743
|
+
readonly muted?: boolean | DeclarativeValueExpr;
|
|
744
|
+
/** A badge next to the value, e.g. 「未启用」. An empty label hides it. */
|
|
745
|
+
readonly badge?: {
|
|
746
|
+
readonly label: DeclarativeI18nText | DeclarativeValueExpr;
|
|
747
|
+
readonly tone?: DeclarativeBadgeTone | DeclarativeValueExpr;
|
|
748
|
+
};
|
|
630
749
|
}[]
|
|
631
750
|
| ((
|
|
632
751
|
data: TData,
|