@zhin.js/console-contract 1.1.5 → 1.1.6

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
@@ -1,3 +1,13 @@
1
+ /**
2
+ * Console navigation sections (ADR 0052); a Page declares which one its entry belongs to.
3
+ * Kept dependency-free here; `tests/contracts/console-page-sections.test.ts` keeps it equal
4
+ * to the wire vocabulary in `@zhin.js/console-protocol`.
5
+ */
6
+ export declare const CONSOLE_PAGE_SECTIONS: readonly ["overview", "conversations", "features", "plugins", "ops", "access"];
7
+ export type ConsolePageSection = (typeof CONSOLE_PAGE_SECTIONS)[number];
8
+ export declare function isConsolePageSection(value: unknown): value is ConsolePageSection;
9
+ /** Validates an optional `section`; throws for anything outside {@link CONSOLE_PAGE_SECTIONS}. */
10
+ export declare function optionalPageSection(value: unknown): ConsolePageSection | undefined;
1
11
  export interface PageMetadata {
2
12
  readonly title?: string;
3
13
  /** Explicit display titles; missing locales retain title. */
@@ -7,6 +17,13 @@ export interface PageMetadata {
7
17
  readonly hideInNav?: boolean;
8
18
  readonly requiredPermissions?: readonly string[];
9
19
  readonly requiredRoles?: readonly string[];
20
+ /** Presentation hints carried through to the Console entry projection. */
21
+ readonly description?: string;
22
+ readonly group?: string;
23
+ readonly parent?: string;
24
+ readonly fullWidth?: boolean;
25
+ /** Console navigation section (ADR 0052); omitted → the Console's default for plugin pages. */
26
+ readonly section?: ConsolePageSection;
10
27
  }
11
28
  export interface NormalizedPageMetadata {
12
29
  readonly title: string;
package/lib/page.js CHANGED
@@ -1,3 +1,23 @@
1
+ /**
2
+ * Console navigation sections (ADR 0052); a Page declares which one its entry belongs to.
3
+ * Kept dependency-free here; `tests/contracts/console-page-sections.test.ts` keeps it equal
4
+ * to the wire vocabulary in `@zhin.js/console-protocol`.
5
+ */
6
+ export const CONSOLE_PAGE_SECTIONS = Object.freeze([
7
+ 'overview', 'conversations', 'features', 'plugins', 'ops', 'access',
8
+ ]);
9
+ export function isConsolePageSection(value) {
10
+ return typeof value === 'string' && CONSOLE_PAGE_SECTIONS.includes(value);
11
+ }
12
+ /** Validates an optional `section`; throws for anything outside {@link CONSOLE_PAGE_SECTIONS}. */
13
+ export function optionalPageSection(value) {
14
+ if (value === undefined)
15
+ return undefined;
16
+ if (!isConsolePageSection(value)) {
17
+ throw new TypeError(`Page section must be one of ${CONSOLE_PAGE_SECTIONS.join(', ')}`);
18
+ }
19
+ return value;
20
+ }
1
21
  export function normalizeClientModuleArtifact(value, label) {
2
22
  const input = requireRecord(value, label);
3
23
  const module = optionalString(input.module, `${label} module`);
@@ -19,7 +39,25 @@ export function isConsoleBlueprint(value) {
19
39
  return kind === 'zhin.console.page-blueprint' || kind === 'zhin.console.adapter-page';
20
40
  }
21
41
  export function definePage(metadata = {}) {
22
- return normalizePageInput(metadata);
42
+ // 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');
44
+ const section = optionalPageSection(rawSection);
45
+ for (const [key, value] of [['description', description], ['group', group], ['parent', parent]]) {
46
+ if (value !== undefined && (typeof value !== 'string' || !value.trim())) {
47
+ throw new TypeError(`Page ${key} must be a non-empty string`);
48
+ }
49
+ }
50
+ if (fullWidth !== undefined && typeof fullWidth !== 'boolean') {
51
+ throw new TypeError('Page fullWidth must be boolean');
52
+ }
53
+ return Object.freeze({
54
+ ...normalizePageInput(base),
55
+ ...(description !== undefined ? { description: description } : {}),
56
+ ...(group !== undefined ? { group: group } : {}),
57
+ ...(parent !== undefined ? { parent: parent } : {}),
58
+ ...(fullWidth !== undefined ? { fullWidth } : {}),
59
+ ...(section !== undefined ? { section } : {}),
60
+ });
23
61
  }
24
62
  export function normalizePageMetadata(localName, metadata) {
25
63
  assertPageLocalName(localName);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhin.js/console-contract",
3
- "version": "1.1.5",
3
+ "version": "1.1.6",
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
@@ -1,3 +1,27 @@
1
+ /**
2
+ * Console navigation sections (ADR 0052); a Page declares which one its entry belongs to.
3
+ * Kept dependency-free here; `tests/contracts/console-page-sections.test.ts` keeps it equal
4
+ * to the wire vocabulary in `@zhin.js/console-protocol`.
5
+ */
6
+ export const CONSOLE_PAGE_SECTIONS = Object.freeze([
7
+ 'overview', 'conversations', 'features', 'plugins', 'ops', 'access',
8
+ ] as const);
9
+
10
+ export type ConsolePageSection = (typeof CONSOLE_PAGE_SECTIONS)[number];
11
+
12
+ export function isConsolePageSection(value: unknown): value is ConsolePageSection {
13
+ return typeof value === 'string' && (CONSOLE_PAGE_SECTIONS as readonly string[]).includes(value);
14
+ }
15
+
16
+ /** Validates an optional `section`; throws for anything outside {@link CONSOLE_PAGE_SECTIONS}. */
17
+ export function optionalPageSection(value: unknown): ConsolePageSection | undefined {
18
+ if (value === undefined) return undefined;
19
+ if (!isConsolePageSection(value)) {
20
+ throw new TypeError(`Page section must be one of ${CONSOLE_PAGE_SECTIONS.join(', ')}`);
21
+ }
22
+ return value;
23
+ }
24
+
1
25
  export interface PageMetadata {
2
26
  readonly title?: string;
3
27
  /** Explicit display titles; missing locales retain title. */
@@ -7,6 +31,13 @@ export interface PageMetadata {
7
31
  readonly hideInNav?: boolean;
8
32
  readonly requiredPermissions?: readonly string[];
9
33
  readonly requiredRoles?: readonly string[];
34
+ /** Presentation hints carried through to the Console entry projection. */
35
+ readonly description?: string;
36
+ readonly group?: string;
37
+ readonly parent?: string;
38
+ readonly fullWidth?: boolean;
39
+ /** Console navigation section (ADR 0052); omitted → the Console's default for plugin pages. */
40
+ readonly section?: ConsolePageSection;
10
41
  }
11
42
 
12
43
  export interface NormalizedPageMetadata {
@@ -63,7 +94,25 @@ export interface PageManifest extends NormalizedPageMetadata {
63
94
  }
64
95
 
65
96
  export function definePage(metadata: PageMetadata = {}): Readonly<PageMetadata> {
66
- return normalizePageInput(metadata);
97
+ // 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');
99
+ const section = optionalPageSection(rawSection);
100
+ for (const [key, value] of [['description', description], ['group', group], ['parent', parent]] as const) {
101
+ if (value !== undefined && (typeof value !== 'string' || !value.trim())) {
102
+ throw new TypeError(`Page ${key} must be a non-empty string`);
103
+ }
104
+ }
105
+ if (fullWidth !== undefined && typeof fullWidth !== 'boolean') {
106
+ throw new TypeError('Page fullWidth must be boolean');
107
+ }
108
+ return Object.freeze({
109
+ ...normalizePageInput(base as PageMetadata),
110
+ ...(description !== undefined ? { description: description as string } : {}),
111
+ ...(group !== undefined ? { group: group as string } : {}),
112
+ ...(parent !== undefined ? { parent: parent as string } : {}),
113
+ ...(fullWidth !== undefined ? { fullWidth } : {}),
114
+ ...(section !== undefined ? { section } : {}),
115
+ });
67
116
  }
68
117
 
69
118
  export function normalizePageMetadata(