@zhin.js/console-contract 1.2.0 → 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 +22 -0
- package/lib/page.js +55 -1
- package/package.json +1 -1
- package/src/page.ts +68 -1
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>;
|
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) {
|
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
|
|