@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 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
- readonly mark: string;
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhin.js/console-contract",
3
- "version": "1.2.0",
3
+ "version": "1.3.1",
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
@@ -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
- readonly mark: string;
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 } : {}),