@zhin.js/console-contract 1.2.0 → 1.3.1
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 +31 -1
- package/lib/page.js +55 -2
- package/package.json +1 -1
- package/src/page.ts +77 -3
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>;
|
|
@@ -298,6 +320,10 @@ export interface DeclarativePageSpec<TData = Record<string, unknown>> {
|
|
|
298
320
|
readonly pluginId?: string;
|
|
299
321
|
readonly title: DeclarativeI18nText;
|
|
300
322
|
readonly description?: DeclarativeI18nText;
|
|
323
|
+
/**
|
|
324
|
+
* @deprecated ADR 0063 P2: the renderer no longer draws a letter tile in the page header; this
|
|
325
|
+
* field is ignored (the Console warns once when it is set) and will be removed in a later minor.
|
|
326
|
+
*/
|
|
301
327
|
readonly mark?: DeclarativeRenderable;
|
|
302
328
|
/** Status RPC method name; defaults to `'status'`. */
|
|
303
329
|
readonly statusMethod?: string;
|
|
@@ -424,7 +450,11 @@ export interface CommentReviewBlueprintSpec<E extends CommentReviewEndpointBase<
|
|
|
424
450
|
readonly zh: string;
|
|
425
451
|
readonly en: string;
|
|
426
452
|
};
|
|
427
|
-
|
|
453
|
+
/**
|
|
454
|
+
* @deprecated ADR 0063 P2: ignored (no letter tile in the page header any more); not copied into
|
|
455
|
+
* the blueprint. Will be removed in a later minor.
|
|
456
|
+
*/
|
|
457
|
+
readonly mark?: string;
|
|
428
458
|
readonly resource: {
|
|
429
459
|
readonly zh: string;
|
|
430
460
|
readonly en: string;
|
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) {
|
|
@@ -479,7 +533,6 @@ export function defineCommentReviewPage(reviewSpec) {
|
|
|
479
533
|
const blueprint = buildBlueprintFromSpec({
|
|
480
534
|
pluginId: reviewSpec.adapter,
|
|
481
535
|
title: { zh: zhTitle, 'zh-CN': zhTitle, en: enTitle },
|
|
482
|
-
mark: reviewSpec.mark,
|
|
483
536
|
statusMethod: 'status',
|
|
484
537
|
pollMs: reviewSpec.pollMs ?? 10_000,
|
|
485
538
|
...(reviewSpec.dictionary ? { dictionary: reviewSpec.dictionary } : {}),
|
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
|
|
|
@@ -695,6 +762,10 @@ export interface DeclarativePageSpec<TData = Record<string, unknown>> {
|
|
|
695
762
|
readonly pluginId?: string;
|
|
696
763
|
readonly title: DeclarativeI18nText;
|
|
697
764
|
readonly description?: DeclarativeI18nText;
|
|
765
|
+
/**
|
|
766
|
+
* @deprecated ADR 0063 P2: the renderer no longer draws a letter tile in the page header; this
|
|
767
|
+
* field is ignored (the Console warns once when it is set) and will be removed in a later minor.
|
|
768
|
+
*/
|
|
698
769
|
readonly mark?: DeclarativeRenderable;
|
|
699
770
|
/** Status RPC method name; defaults to `'status'`. */
|
|
700
771
|
readonly statusMethod?: string;
|
|
@@ -836,7 +907,11 @@ export interface CommentReviewBlueprintSpec<
|
|
|
836
907
|
> {
|
|
837
908
|
readonly adapter: string;
|
|
838
909
|
readonly platform: { readonly zh: string; readonly en: string };
|
|
839
|
-
|
|
910
|
+
/**
|
|
911
|
+
* @deprecated ADR 0063 P2: ignored (no letter tile in the page header any more); not copied into
|
|
912
|
+
* the blueprint. Will be removed in a later minor.
|
|
913
|
+
*/
|
|
914
|
+
readonly mark?: string;
|
|
840
915
|
readonly resource: { readonly zh: string; readonly en: string };
|
|
841
916
|
readonly dictionary?: Readonly<Record<string, string>>;
|
|
842
917
|
readonly openLabel?: string;
|
|
@@ -1093,7 +1168,6 @@ export function defineCommentReviewPage<
|
|
|
1093
1168
|
const blueprint = buildBlueprintFromSpec<{ readonly endpoints?: readonly E[]; readonly updatedAt?: number }>({
|
|
1094
1169
|
pluginId: reviewSpec.adapter,
|
|
1095
1170
|
title: { zh: zhTitle, 'zh-CN': zhTitle, en: enTitle },
|
|
1096
|
-
mark: reviewSpec.mark,
|
|
1097
1171
|
statusMethod: 'status',
|
|
1098
1172
|
pollMs: reviewSpec.pollMs ?? 10_000,
|
|
1099
1173
|
...(reviewSpec.dictionary ? { dictionary: reviewSpec.dictionary } : {}),
|