@graphql-markdown/printer-legacy 1.13.1 → 1.15.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/dist/const/options.d.ts +15 -2
- package/dist/const/options.d.ts.map +1 -1
- package/dist/const/options.js +20 -6
- package/dist/const/strings.d.ts +15 -0
- package/dist/const/strings.d.ts.map +1 -1
- package/dist/const/strings.js +9 -0
- package/dist/directive.d.ts +3 -3
- package/dist/directive.d.ts.map +1 -1
- package/dist/directive.js +8 -4
- package/dist/events.d.ts +77 -0
- package/dist/events.d.ts.map +1 -0
- package/dist/events.js +85 -0
- package/dist/example.d.ts.map +1 -1
- package/dist/example.js +12 -7
- package/dist/format-helpers.d.ts +9 -0
- package/dist/format-helpers.d.ts.map +1 -1
- package/dist/format-helpers.js +10 -1
- package/dist/formatter.js +1 -1
- package/dist/graphql/directive.d.ts +3 -3
- package/dist/graphql/directive.d.ts.map +1 -1
- package/dist/graphql/directive.js +3 -3
- package/dist/graphql/enum.d.ts +3 -3
- package/dist/graphql/enum.d.ts.map +1 -1
- package/dist/graphql/enum.js +2 -2
- package/dist/graphql/input.d.ts +13 -0
- package/dist/graphql/input.d.ts.map +1 -1
- package/dist/graphql/input.js +8 -0
- package/dist/graphql/object.d.ts +3 -3
- package/dist/graphql/object.d.ts.map +1 -1
- package/dist/graphql/object.js +4 -4
- package/dist/graphql/operation.d.ts +6 -7
- package/dist/graphql/operation.d.ts.map +1 -1
- package/dist/graphql/operation.js +41 -8
- package/dist/graphql/scalar.d.ts +5 -5
- package/dist/graphql/scalar.d.ts.map +1 -1
- package/dist/graphql/scalar.js +7 -7
- package/dist/graphql/union.d.ts +3 -3
- package/dist/graphql/union.d.ts.map +1 -1
- package/dist/graphql/union.js +2 -2
- package/dist/group.d.ts.map +1 -1
- package/dist/group.js +7 -6
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -1
- package/dist/link.d.ts +2 -2
- package/dist/link.d.ts.map +1 -1
- package/dist/link.js +54 -13
- package/dist/mdx/index.js +2 -2
- package/dist/printer.d.ts +67 -22
- package/dist/printer.d.ts.map +1 -1
- package/dist/printer.js +270 -117
- package/dist/section.d.ts +3 -3
- package/dist/section.d.ts.map +1 -1
- package/dist/section.js +34 -13
- package/package.json +19 -10
package/dist/printer.js
CHANGED
|
@@ -20,7 +20,22 @@ const PrintTypeEvents = {
|
|
|
20
20
|
AFTER_PRINT_CODE: "print:afterPrintCode",
|
|
21
21
|
BEFORE_PRINT_TYPE: "print:beforePrintType",
|
|
22
22
|
AFTER_PRINT_TYPE: "print:afterPrintType",
|
|
23
|
+
BEFORE_COMPOSE_PAGE_TYPE: "print:beforeComposePageType",
|
|
23
24
|
};
|
|
25
|
+
const TYPE_PAGE_HEADER_ORDER = [
|
|
26
|
+
"header",
|
|
27
|
+
"metatags",
|
|
28
|
+
"mdxDeclaration",
|
|
29
|
+
];
|
|
30
|
+
const TYPE_PAGE_SECTION_ORDER = [
|
|
31
|
+
"tags",
|
|
32
|
+
"description",
|
|
33
|
+
"code",
|
|
34
|
+
"customDirectives",
|
|
35
|
+
"metadata",
|
|
36
|
+
"example",
|
|
37
|
+
"relations",
|
|
38
|
+
];
|
|
24
39
|
const graphql_1 = require("@graphql-markdown/graphql");
|
|
25
40
|
const utils_1 = require("@graphql-markdown/utils");
|
|
26
41
|
const relation_1 = require("./relation");
|
|
@@ -33,6 +48,7 @@ const strings_1 = require("./const/strings");
|
|
|
33
48
|
const formatter_1 = require("./formatter");
|
|
34
49
|
const options_1 = require("./const/options");
|
|
35
50
|
const example_1 = require("./example");
|
|
51
|
+
const events_1 = require("./events");
|
|
36
52
|
/**
|
|
37
53
|
* Default initialization options for the Printer class.
|
|
38
54
|
* @internal
|
|
@@ -40,6 +56,7 @@ const example_1 = require("./example");
|
|
|
40
56
|
const DEFAULT_INIT_OPTIONS = {
|
|
41
57
|
customDirectives: undefined,
|
|
42
58
|
groups: undefined,
|
|
59
|
+
sectionHeaderId: true,
|
|
43
60
|
};
|
|
44
61
|
/**
|
|
45
62
|
* The Printer class implements the core functionality for generating Markdown documentation
|
|
@@ -60,16 +77,6 @@ const DEFAULT_INIT_OPTIONS = {
|
|
|
60
77
|
* ```
|
|
61
78
|
*/
|
|
62
79
|
class Printer {
|
|
63
|
-
/**
|
|
64
|
-
* Global printer configuration options
|
|
65
|
-
*/
|
|
66
|
-
static options;
|
|
67
|
-
/**
|
|
68
|
-
* Optional event emitter for print events.
|
|
69
|
-
* When set, the printer will emit events before/after printCode and printType,
|
|
70
|
-
* allowing external code to intercept and modify the output.
|
|
71
|
-
*/
|
|
72
|
-
static eventEmitter;
|
|
73
80
|
/**
|
|
74
81
|
* Prints type descriptions
|
|
75
82
|
*/
|
|
@@ -82,10 +89,47 @@ class Printer {
|
|
|
82
89
|
* Prints custom tags
|
|
83
90
|
*/
|
|
84
91
|
static printCustomTags = directive_1.printCustomTags;
|
|
92
|
+
static _eventEmitter;
|
|
93
|
+
static _options;
|
|
94
|
+
static _deprecatedOptions;
|
|
95
|
+
static _mdxDeclaration;
|
|
96
|
+
/**
|
|
97
|
+
* Global printer configuration options
|
|
98
|
+
*/
|
|
99
|
+
static get options() {
|
|
100
|
+
return Printer._options;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Backward-compat section toggles extracted from legacy config options.
|
|
104
|
+
*
|
|
105
|
+
* These flags are applied only during section order composition.
|
|
106
|
+
*/
|
|
107
|
+
static get deprecatedOptions() {
|
|
108
|
+
return Printer._deprecatedOptions;
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Optional event emitter for print events.
|
|
112
|
+
* When set, the printer will emit events before/after printCode and printType,
|
|
113
|
+
* allowing external code to intercept and modify the output.
|
|
114
|
+
*/
|
|
115
|
+
static get eventEmitter() {
|
|
116
|
+
return Printer._eventEmitter;
|
|
117
|
+
}
|
|
85
118
|
/**
|
|
86
119
|
* Prints mdx modules import declaration
|
|
87
120
|
*/
|
|
88
|
-
static mdxDeclaration
|
|
121
|
+
static get mdxDeclaration() {
|
|
122
|
+
return Printer._mdxDeclaration;
|
|
123
|
+
}
|
|
124
|
+
static set options(options) {
|
|
125
|
+
Printer._options = options;
|
|
126
|
+
}
|
|
127
|
+
static set eventEmitter(eventEmitter) {
|
|
128
|
+
Printer._eventEmitter = eventEmitter;
|
|
129
|
+
}
|
|
130
|
+
static set mdxDeclaration(mdxDeclaration) {
|
|
131
|
+
Printer._mdxDeclaration = mdxDeclaration;
|
|
132
|
+
}
|
|
89
133
|
/**
|
|
90
134
|
* Initializes the printer with the given schema and configuration.
|
|
91
135
|
*
|
|
@@ -97,37 +141,54 @@ class Printer {
|
|
|
97
141
|
* @param mdxDeclaration - Optional MDX import declaration
|
|
98
142
|
* @param eventEmitter - Optional event emitter for print events interception
|
|
99
143
|
*/
|
|
100
|
-
static async init(schema, baseURL = "schema", linkRoot = "/", { customDirectives, groups, meta, metatags, onlyDocDirectives, printTypeOptions, skipDocDirectives, } = DEFAULT_INIT_OPTIONS, formatter, mdxDeclaration, eventEmitter) {
|
|
144
|
+
static async init(schema, baseURL = "schema", linkRoot = "/", { customDirectives, groups, meta, metatags, onlyDocDirectives, printTypeOptions, skipDocDirectives, sectionHeaderId, } = DEFAULT_INIT_OPTIONS, formatter, mdxDeclaration, eventEmitter) {
|
|
101
145
|
// Always update eventEmitter regardless of initialization state
|
|
102
146
|
Printer.eventEmitter = eventEmitter ?? null;
|
|
103
|
-
if (Printer.options
|
|
104
|
-
|
|
147
|
+
if (Printer.options === undefined) {
|
|
148
|
+
Printer.options = {
|
|
149
|
+
...options_1.DEFAULT_OPTIONS,
|
|
150
|
+
basePath: utils_1.pathUrl.join(linkRoot ?? "", baseURL ?? ""),
|
|
151
|
+
customDirectives,
|
|
152
|
+
exampleSection: typeof printTypeOptions?.exampleSection === "object"
|
|
153
|
+
? printTypeOptions.exampleSection
|
|
154
|
+
: undefined,
|
|
155
|
+
groups,
|
|
156
|
+
parentTypePrefix: printTypeOptions?.parentTypePrefix ??
|
|
157
|
+
options_1.PRINT_TYPE_DEFAULT_OPTIONS.parentTypePrefix,
|
|
158
|
+
deprecated: printTypeOptions?.deprecated ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.deprecated,
|
|
159
|
+
schema,
|
|
160
|
+
onlyDocDirectives: onlyDocDirectives ?? [],
|
|
161
|
+
skipDocDirectives: skipDocDirectives ?? [],
|
|
162
|
+
sectionHeaderId: sectionHeaderId ?? options_1.DEFAULT_OPTIONS.sectionHeaderId,
|
|
163
|
+
typeBadges: printTypeOptions?.typeBadges ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.typeBadges,
|
|
164
|
+
metatags: metatags ?? [],
|
|
165
|
+
hierarchy: printTypeOptions?.hierarchy ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.hierarchy,
|
|
166
|
+
meta: meta,
|
|
167
|
+
// Merge formatter functions: default formatter with any overrides
|
|
168
|
+
...(0, formatter_1.createDefaultFormatter)(),
|
|
169
|
+
...formatter,
|
|
170
|
+
};
|
|
171
|
+
const initExampleSection = printTypeOptions?.exampleSection;
|
|
172
|
+
let deprecatedExampleSection;
|
|
173
|
+
if (typeof initExampleSection === "boolean") {
|
|
174
|
+
deprecatedExampleSection = initExampleSection;
|
|
175
|
+
}
|
|
176
|
+
else if (initExampleSection === undefined) {
|
|
177
|
+
deprecatedExampleSection =
|
|
178
|
+
options_1.PRINT_TYPE_DEFAULT_DEPRECATED_OPTIONS.exampleSection;
|
|
179
|
+
}
|
|
180
|
+
else {
|
|
181
|
+
deprecatedExampleSection = true;
|
|
182
|
+
}
|
|
183
|
+
Printer._deprecatedOptions = {
|
|
184
|
+
codeSection: printTypeOptions?.codeSection ??
|
|
185
|
+
options_1.PRINT_TYPE_DEFAULT_DEPRECATED_OPTIONS.codeSection,
|
|
186
|
+
exampleSection: deprecatedExampleSection,
|
|
187
|
+
relatedTypeSection: printTypeOptions?.relatedTypeSection ??
|
|
188
|
+
options_1.PRINT_TYPE_DEFAULT_DEPRECATED_OPTIONS.relatedTypeSection,
|
|
189
|
+
};
|
|
190
|
+
Printer.mdxDeclaration = mdxDeclaration ?? "";
|
|
105
191
|
}
|
|
106
|
-
Printer.options = {
|
|
107
|
-
...options_1.DEFAULT_OPTIONS,
|
|
108
|
-
basePath: utils_1.pathUrl.join(linkRoot ?? "", baseURL ?? ""),
|
|
109
|
-
codeSection: printTypeOptions?.codeSection ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.codeSection,
|
|
110
|
-
customDirectives,
|
|
111
|
-
exampleSection: printTypeOptions?.exampleSection ??
|
|
112
|
-
options_1.PRINT_TYPE_DEFAULT_OPTIONS.exampleSection,
|
|
113
|
-
groups,
|
|
114
|
-
parentTypePrefix: printTypeOptions?.parentTypePrefix ??
|
|
115
|
-
options_1.PRINT_TYPE_DEFAULT_OPTIONS.parentTypePrefix,
|
|
116
|
-
deprecated: printTypeOptions?.deprecated ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.deprecated,
|
|
117
|
-
relatedTypeSection: printTypeOptions?.relatedTypeSection ??
|
|
118
|
-
options_1.PRINT_TYPE_DEFAULT_OPTIONS.relatedTypeSection,
|
|
119
|
-
schema,
|
|
120
|
-
onlyDocDirectives: onlyDocDirectives ?? [],
|
|
121
|
-
skipDocDirectives: skipDocDirectives ?? [],
|
|
122
|
-
typeBadges: printTypeOptions?.typeBadges ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.typeBadges,
|
|
123
|
-
metatags: metatags ?? [],
|
|
124
|
-
hierarchy: printTypeOptions?.hierarchy ?? options_1.PRINT_TYPE_DEFAULT_OPTIONS.hierarchy,
|
|
125
|
-
meta: meta,
|
|
126
|
-
// Merge formatter functions: default formatter with any overrides
|
|
127
|
-
...(0, formatter_1.createDefaultFormatter)(),
|
|
128
|
-
...formatter,
|
|
129
|
-
};
|
|
130
|
-
Printer.mdxDeclaration = mdxDeclaration ?? "";
|
|
131
192
|
}
|
|
132
193
|
/**
|
|
133
194
|
* Prints the header section of a type documentation
|
|
@@ -152,9 +213,6 @@ class Printer {
|
|
|
152
213
|
* @returns Formatted code block string with type definition
|
|
153
214
|
*/
|
|
154
215
|
static printCode = (type, options) => {
|
|
155
|
-
if (options.codeSection === undefined || options.codeSection !== true) {
|
|
156
|
-
return "";
|
|
157
|
-
}
|
|
158
216
|
let code = "";
|
|
159
217
|
switch (true) {
|
|
160
218
|
case (0, graphql_1.isOperation)(type):
|
|
@@ -212,14 +270,7 @@ class Printer {
|
|
|
212
270
|
// Create mutable event data - handlers can modify options
|
|
213
271
|
const eventData = { type, typeName, options: { ...options } };
|
|
214
272
|
// Emit BEFORE event - handlers can modify inputs or prevent default
|
|
215
|
-
const beforeEvent =
|
|
216
|
-
data: eventData,
|
|
217
|
-
output: "",
|
|
218
|
-
defaultPrevented: false,
|
|
219
|
-
preventDefault() {
|
|
220
|
-
this.defaultPrevented = true;
|
|
221
|
-
},
|
|
222
|
-
};
|
|
273
|
+
const beforeEvent = new events_1.PrintCodeEvent(eventData, "");
|
|
223
274
|
await Printer.eventEmitter.emitAsync(PrintTypeEvents.BEFORE_PRINT_CODE, beforeEvent);
|
|
224
275
|
// If prevented, handlers should have set the output they want
|
|
225
276
|
if (beforeEvent.defaultPrevented) {
|
|
@@ -228,10 +279,7 @@ class Printer {
|
|
|
228
279
|
// Generate code using the (potentially modified) options from event data
|
|
229
280
|
const output = Printer.printCode(type, eventData.options);
|
|
230
281
|
// Emit AFTER event - handlers can modify the output
|
|
231
|
-
const afterEvent =
|
|
232
|
-
data: eventData,
|
|
233
|
-
output,
|
|
234
|
-
};
|
|
282
|
+
const afterEvent = new events_1.PrintCodeEvent(eventData, output);
|
|
235
283
|
await Printer.eventEmitter.emitAsync(PrintTypeEvents.AFTER_PRINT_CODE, afterEvent);
|
|
236
284
|
return afterEvent.output;
|
|
237
285
|
};
|
|
@@ -240,27 +288,24 @@ class Printer {
|
|
|
240
288
|
*
|
|
241
289
|
* @param type - GraphQL type to generate example for
|
|
242
290
|
* @param options - Printer configuration options
|
|
243
|
-
* @returns
|
|
291
|
+
* @returns Example page section or undefined when no example is available
|
|
244
292
|
*/
|
|
245
293
|
static printExample = (type, options) => {
|
|
246
|
-
if (options.exampleSection === undefined ||
|
|
247
|
-
options.exampleSection === null ||
|
|
248
|
-
options.exampleSection === false) {
|
|
249
|
-
return "";
|
|
250
|
-
}
|
|
251
294
|
const example = (0, example_1.printExample)(type, options);
|
|
252
295
|
if (!example) {
|
|
253
|
-
return
|
|
296
|
+
return undefined;
|
|
254
297
|
}
|
|
255
|
-
return
|
|
298
|
+
return {
|
|
299
|
+
content: `${strings_1.MARKDOWN_SOC}${example}${strings_1.MARKDOWN_EOC}${strings_1.MARKDOWN_EOP}`,
|
|
300
|
+
title: "Example",
|
|
301
|
+
};
|
|
256
302
|
};
|
|
257
303
|
/**
|
|
258
304
|
* Prints metadata information for a GraphQL type
|
|
259
305
|
*
|
|
260
306
|
* @param type - GraphQL type to print metadata for
|
|
261
307
|
* @param options - Printer configuration options
|
|
262
|
-
* @returns
|
|
263
|
-
* @throws When type is not supported
|
|
308
|
+
* @returns Metadata section (or section list) for supported types, otherwise undefined
|
|
264
309
|
*/
|
|
265
310
|
static printTypeMetadata = (type, options) => {
|
|
266
311
|
switch (true) {
|
|
@@ -281,7 +326,7 @@ class Printer {
|
|
|
281
326
|
case (0, graphql_1.isOperation)(type):
|
|
282
327
|
return (0, graphql_2.printOperationMetadata)(type, options);
|
|
283
328
|
default:
|
|
284
|
-
return
|
|
329
|
+
return undefined;
|
|
285
330
|
}
|
|
286
331
|
};
|
|
287
332
|
/**
|
|
@@ -292,9 +337,6 @@ class Printer {
|
|
|
292
337
|
* @returns Formatted relations section as MDX or plain string
|
|
293
338
|
*/
|
|
294
339
|
static printRelations = (type, options) => {
|
|
295
|
-
if (options.relatedTypeSection !== true) {
|
|
296
|
-
return "";
|
|
297
|
-
}
|
|
298
340
|
return (0, relation_1.printRelations)(type, options);
|
|
299
341
|
};
|
|
300
342
|
/**
|
|
@@ -327,8 +369,7 @@ class Printer {
|
|
|
327
369
|
* @example
|
|
328
370
|
* ```typescript
|
|
329
371
|
* const doc = await Printer.printType('User', UserType, {
|
|
330
|
-
* frontMatter: true
|
|
331
|
-
* codeSection: true
|
|
372
|
+
* frontMatter: true
|
|
332
373
|
* });
|
|
333
374
|
* ```
|
|
334
375
|
*
|
|
@@ -345,6 +386,7 @@ class Printer {
|
|
|
345
386
|
*
|
|
346
387
|
* When an event emitter is configured, emits events:
|
|
347
388
|
* - `print:beforePrintType` - Before generating documentation
|
|
389
|
+
* - `print:beforeComposePageType` - Before composing section order and final page output
|
|
348
390
|
* - `print:afterPrintType` - After generating documentation (output can be modified)
|
|
349
391
|
*/
|
|
350
392
|
static printType = async (name, type, options) => {
|
|
@@ -353,6 +395,12 @@ class Printer {
|
|
|
353
395
|
...Printer.options,
|
|
354
396
|
...options,
|
|
355
397
|
};
|
|
398
|
+
const deprecatedOptions = {
|
|
399
|
+
...Printer.deprecatedOptions,
|
|
400
|
+
exampleSection: printTypeOptions.exampleSection
|
|
401
|
+
? true
|
|
402
|
+
: Printer.deprecatedOptions?.exampleSection,
|
|
403
|
+
};
|
|
356
404
|
if (!name || !(0, link_1.hasPrintableDirective)(type, printTypeOptions)) {
|
|
357
405
|
return undefined;
|
|
358
406
|
}
|
|
@@ -360,21 +408,7 @@ class Printer {
|
|
|
360
408
|
const eventData = { type, name, options: printTypeOptions };
|
|
361
409
|
// Emit BEFORE_PRINT_TYPE event if emitter is configured
|
|
362
410
|
if (Printer.eventEmitter) {
|
|
363
|
-
const beforeEvent =
|
|
364
|
-
data: eventData,
|
|
365
|
-
output: undefined,
|
|
366
|
-
defaultPrevented: false,
|
|
367
|
-
propagationStopped: false,
|
|
368
|
-
preventDefault() {
|
|
369
|
-
this.defaultPrevented = true;
|
|
370
|
-
},
|
|
371
|
-
stopPropagation() {
|
|
372
|
-
this.propagationStopped = true;
|
|
373
|
-
},
|
|
374
|
-
async runDefaultAction() {
|
|
375
|
-
return void 0;
|
|
376
|
-
},
|
|
377
|
-
};
|
|
411
|
+
const beforeEvent = new events_1.PrintTypeEvent(eventData, undefined);
|
|
378
412
|
await Printer.eventEmitter.emitAsync(PrintTypeEvents.BEFORE_PRINT_TYPE, beforeEvent);
|
|
379
413
|
// If prevented, return the output set by handlers (or undefined)
|
|
380
414
|
if (beforeEvent.defaultPrevented) {
|
|
@@ -384,50 +418,169 @@ class Printer {
|
|
|
384
418
|
const header = Printer.printHeader(name, (0, graphql_1.getTypeName)(type), printTypeOptions);
|
|
385
419
|
const metatags = Printer.printMetaTags(type, printTypeOptions);
|
|
386
420
|
const description = Printer.printDescription(type, printTypeOptions);
|
|
387
|
-
//
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
421
|
+
// Generate all sections unconditionally to support event hooks that might re-add
|
|
422
|
+
// sections excluded by deprecated toggles. This is a performance trade-off:
|
|
423
|
+
// sections excluded by deprecated flags (codeSection, exampleSection, relatedTypeSection)
|
|
424
|
+
// are still generated and print events emitted, even if they won't be rendered.
|
|
425
|
+
// TODO(perf): Implement lazy section generation based on final composed order
|
|
426
|
+
// when no BEFORE_COMPOSE_PAGE_TYPE listeners are registered.
|
|
427
|
+
const code = await Printer.printCodeAsync(type, name, printTypeOptions);
|
|
391
428
|
const customDirectives = Printer.printCustomDirectives(type, printTypeOptions);
|
|
392
429
|
const tags = Printer.printCustomTags(type, printTypeOptions);
|
|
393
430
|
const metadata = Printer.printTypeMetadata(type, printTypeOptions);
|
|
394
431
|
const relations = Printer.printRelations(type, printTypeOptions);
|
|
395
432
|
const example = Printer.printExample(type, printTypeOptions);
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
433
|
+
// Create sections map for composition events
|
|
434
|
+
const sections = {
|
|
435
|
+
header: { content: header },
|
|
436
|
+
metatags: { content: metatags },
|
|
437
|
+
mdxDeclaration: { content: Printer.mdxDeclaration ?? "" },
|
|
438
|
+
tags: Printer.normalizePageSection(tags),
|
|
439
|
+
description: Printer.normalizePageSection(description),
|
|
440
|
+
code: Printer.normalizePageSection(code),
|
|
441
|
+
customDirectives: Printer.normalizePageSection(customDirectives),
|
|
442
|
+
metadata: Printer.normalizePageSection(metadata),
|
|
443
|
+
example: Printer.normalizePageSection(example),
|
|
444
|
+
relations: Printer.normalizePageSection(relations),
|
|
445
|
+
};
|
|
446
|
+
let sectionOrder = Printer.getDeprecatedTypePageSectionOrder([...TYPE_PAGE_SECTION_ORDER], deprecatedOptions);
|
|
447
|
+
// Emit BEFORE_COMPOSE_PAGE_TYPE event if emitter is configured
|
|
448
|
+
if (Printer.eventEmitter) {
|
|
449
|
+
const beforeComposeEvent = new events_1.BeforeComposePageTypeEvent({ type, name, options: printTypeOptions, sections }, sectionOrder);
|
|
450
|
+
await Printer.eventEmitter.emitAsync(PrintTypeEvents.BEFORE_COMPOSE_PAGE_TYPE, beforeComposeEvent);
|
|
451
|
+
sectionOrder = Printer.sanitizeTypePageSectionOrder(beforeComposeEvent.output, sections);
|
|
452
|
+
}
|
|
453
|
+
// Compose output based on section order
|
|
454
|
+
const pageSections = [
|
|
455
|
+
...TYPE_PAGE_HEADER_ORDER,
|
|
456
|
+
...sectionOrder,
|
|
457
|
+
];
|
|
458
|
+
let output = pageSections
|
|
459
|
+
.map((key) => {
|
|
460
|
+
return Printer.renderPageSection(sections[key]);
|
|
461
|
+
})
|
|
462
|
+
.filter((section) => {
|
|
463
|
+
return section.length > 0;
|
|
464
|
+
})
|
|
408
465
|
.join(strings_1.MARKDOWN_EOP)
|
|
409
466
|
.trim();
|
|
410
467
|
// Emit AFTER_PRINT_TYPE event if emitter is configured
|
|
411
468
|
if (Printer.eventEmitter) {
|
|
412
|
-
const afterEvent =
|
|
413
|
-
data: eventData,
|
|
414
|
-
output,
|
|
415
|
-
defaultPrevented: false,
|
|
416
|
-
propagationStopped: false,
|
|
417
|
-
preventDefault() {
|
|
418
|
-
this.defaultPrevented = true;
|
|
419
|
-
},
|
|
420
|
-
stopPropagation() {
|
|
421
|
-
this.propagationStopped = true;
|
|
422
|
-
},
|
|
423
|
-
async runDefaultAction() {
|
|
424
|
-
return void 0;
|
|
425
|
-
},
|
|
426
|
-
};
|
|
469
|
+
const afterEvent = new events_1.PrintTypeEvent(eventData, output);
|
|
427
470
|
await Printer.eventEmitter.emitAsync(PrintTypeEvents.AFTER_PRINT_TYPE, afterEvent);
|
|
428
|
-
output = afterEvent.output;
|
|
471
|
+
output = afterEvent.output ?? output;
|
|
429
472
|
}
|
|
430
473
|
return output;
|
|
431
474
|
};
|
|
475
|
+
/**
|
|
476
|
+
* Renders a page section, optionally prefixing a heading when a title is present.
|
|
477
|
+
*/
|
|
478
|
+
static renderPageSection = (section) => {
|
|
479
|
+
if (!section ||
|
|
480
|
+
typeof section !== "object" ||
|
|
481
|
+
Array.isArray(section) ||
|
|
482
|
+
(!("content" in section) && !("title" in section))) {
|
|
483
|
+
return "";
|
|
484
|
+
}
|
|
485
|
+
let content;
|
|
486
|
+
if (!("content" in section) || !section.content) {
|
|
487
|
+
content = "";
|
|
488
|
+
}
|
|
489
|
+
else if (Array.isArray(section.content)) {
|
|
490
|
+
content = section.content
|
|
491
|
+
.map((entry) => {
|
|
492
|
+
return Printer.renderPageSection(entry);
|
|
493
|
+
})
|
|
494
|
+
.filter((entry) => {
|
|
495
|
+
return entry.length > 0;
|
|
496
|
+
})
|
|
497
|
+
.join(strings_1.MARKDOWN_EOP);
|
|
498
|
+
}
|
|
499
|
+
else if (typeof section.content === "string") {
|
|
500
|
+
content = section.content;
|
|
501
|
+
}
|
|
502
|
+
else {
|
|
503
|
+
content = Printer.renderPageSection(section.content);
|
|
504
|
+
}
|
|
505
|
+
if (!("title" in section) || typeof section.title !== "string") {
|
|
506
|
+
if (!content || content.trim().length === 0) {
|
|
507
|
+
return "";
|
|
508
|
+
}
|
|
509
|
+
return content;
|
|
510
|
+
}
|
|
511
|
+
if (!section.title || section.title.trim().length === 0) {
|
|
512
|
+
if (!content || content.trim().length === 0) {
|
|
513
|
+
return "";
|
|
514
|
+
}
|
|
515
|
+
return content;
|
|
516
|
+
}
|
|
517
|
+
const level = Math.max(1, section.level ?? 3);
|
|
518
|
+
const title = `${options_1.SectionLevels.LEVEL.repeat(level)} ${section.title}${strings_1.MARKDOWN_EOP}`;
|
|
519
|
+
if (!content || content.trim().length === 0) {
|
|
520
|
+
return title;
|
|
521
|
+
}
|
|
522
|
+
return `${title}${content}`;
|
|
523
|
+
};
|
|
524
|
+
/**
|
|
525
|
+
* Returns the default content section order for type pages.
|
|
526
|
+
*
|
|
527
|
+
* Applies backward-compatibility toggles from deprecated section flags.
|
|
528
|
+
*/
|
|
529
|
+
static getDeprecatedTypePageSectionOrder = (sections, deprecatedOptions) => {
|
|
530
|
+
return sections.filter((section) => {
|
|
531
|
+
if (section === "code") {
|
|
532
|
+
return deprecatedOptions.codeSection !== false;
|
|
533
|
+
}
|
|
534
|
+
if (section === "example") {
|
|
535
|
+
return deprecatedOptions.exampleSection !== false;
|
|
536
|
+
}
|
|
537
|
+
if (section === "relations") {
|
|
538
|
+
return deprecatedOptions.relatedTypeSection !== false;
|
|
539
|
+
}
|
|
540
|
+
return true;
|
|
541
|
+
});
|
|
542
|
+
};
|
|
543
|
+
/**
|
|
544
|
+
* Runtime guard for built-in page content section keys.
|
|
545
|
+
*/
|
|
546
|
+
static isTypePageContentSection = (section) => {
|
|
547
|
+
return (typeof section === "string" &&
|
|
548
|
+
TYPE_PAGE_SECTION_ORDER.includes(section));
|
|
549
|
+
};
|
|
550
|
+
/**
|
|
551
|
+
* Runtime guard for header-only page section keys.
|
|
552
|
+
*/
|
|
553
|
+
static isTypePageHeaderSection = (section) => {
|
|
554
|
+
return (typeof section === "string" &&
|
|
555
|
+
TYPE_PAGE_HEADER_ORDER.includes(section));
|
|
556
|
+
};
|
|
557
|
+
/**
|
|
558
|
+
* Normalizes event-driven section order, allowing built-in section keys and
|
|
559
|
+
* any custom keys that were added to the sections map by an event handler.
|
|
560
|
+
* Keys that are neither built-in nor present in the sections map are dropped.
|
|
561
|
+
*/
|
|
562
|
+
static sanitizeTypePageSectionOrder = (sectionOrder, sections) => {
|
|
563
|
+
if (!Array.isArray(sectionOrder)) {
|
|
564
|
+
return [];
|
|
565
|
+
}
|
|
566
|
+
return sectionOrder.filter((section) => {
|
|
567
|
+
return (typeof section === "string" &&
|
|
568
|
+
!Printer.isTypePageHeaderSection(section) &&
|
|
569
|
+
(Printer.isTypePageContentSection(section) ||
|
|
570
|
+
Object.hasOwn(sections, section)));
|
|
571
|
+
});
|
|
572
|
+
};
|
|
573
|
+
/**
|
|
574
|
+
* Normalizes mixed section value shapes to the internal PageSection format.
|
|
575
|
+
*/
|
|
576
|
+
static normalizePageSection = (section) => {
|
|
577
|
+
if (!section) {
|
|
578
|
+
return undefined;
|
|
579
|
+
}
|
|
580
|
+
if (typeof section === "string" || Array.isArray(section)) {
|
|
581
|
+
return { content: section };
|
|
582
|
+
}
|
|
583
|
+
return section;
|
|
584
|
+
};
|
|
432
585
|
}
|
|
433
586
|
exports.Printer = Printer;
|
package/dist/section.d.ts
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* Handles the printing of section items, metadata, and structured documentation content.
|
|
4
4
|
* @module section
|
|
5
5
|
*/
|
|
6
|
-
import type { MDXString, PrintTypeOptions } from "@graphql-markdown/types";
|
|
6
|
+
import type { Maybe, MDXString, PageSection, PrintTypeOptions } from "@graphql-markdown/types";
|
|
7
7
|
/**
|
|
8
8
|
* Prints a single section item with its associated metadata.
|
|
9
9
|
*
|
|
@@ -34,7 +34,7 @@ export declare const printSectionItems: <V>(values: V | V[], options: PrintTypeO
|
|
|
34
34
|
*
|
|
35
35
|
* @template V - Type of the values being printed
|
|
36
36
|
*/
|
|
37
|
-
export declare const printSection: <V>(values: V[] | readonly V[], section: string, options: PrintTypeOptions) =>
|
|
37
|
+
export declare const printSection: <V>(values: V[] | readonly V[], section: string, options: PrintTypeOptions) => Maybe<PageSection>;
|
|
38
38
|
/**
|
|
39
39
|
* Prints a metadata section with special handling for deprecated items.
|
|
40
40
|
*
|
|
@@ -47,5 +47,5 @@ export declare const printSection: <V>(values: V[] | readonly V[], section: stri
|
|
|
47
47
|
* @template T - Type of the parent element
|
|
48
48
|
* @template V - Type of the values being printed
|
|
49
49
|
*/
|
|
50
|
-
export declare const printMetadataSection: <T, V>(type: T, values: V | V[] | readonly V[], section: string, options: PrintTypeOptions) =>
|
|
50
|
+
export declare const printMetadataSection: <T, V>(type: T, values: V | V[] | readonly V[], section: string, options: PrintTypeOptions) => Maybe<PageSection>;
|
|
51
51
|
//# sourceMappingURL=section.d.ts.map
|
package/dist/section.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../src/section.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,SAAS,EACT,gBAAgB,EAEjB,MAAM,yBAAyB,CAAC;
|
|
1
|
+
{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../src/section.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,KAAK,EACL,SAAS,EACT,WAAW,EACX,gBAAgB,EAEjB,MAAM,yBAAyB,CAAC;AAuBjC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,2DAmDjC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,mEAoBlC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,+FAyC7B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EAAE,CAAC,4GA0ExC,CAAC"}
|
package/dist/section.js
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
*/
|
|
7
7
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
8
8
|
exports.printMetadataSection = exports.printSection = exports.printSectionItems = exports.printSectionItem = void 0;
|
|
9
|
+
const utils_1 = require("@graphql-markdown/utils");
|
|
9
10
|
const graphql_1 = require("@graphql-markdown/graphql");
|
|
10
11
|
const common_1 = require("./common");
|
|
11
12
|
const badge_1 = require("./badge");
|
|
@@ -27,14 +28,19 @@ const printSectionItem = (type, options) => {
|
|
|
27
28
|
if (!(0, link_1.hasPrintableDirective)(type, options)) {
|
|
28
29
|
return "";
|
|
29
30
|
}
|
|
30
|
-
const
|
|
31
|
+
const link = (0, link_1.toLink)(type, (0, graphql_1.getTypeName)(type, (0, utils_1.toString)(type)), undefined, options);
|
|
32
|
+
const typeNameLink = (0, link_1.printLink)(link, {
|
|
31
33
|
...options,
|
|
32
34
|
withAttributes: false,
|
|
33
35
|
});
|
|
34
36
|
const badges = (0, badge_1.printBadges)(type, options);
|
|
35
37
|
const tags = (0, directive_1.printCustomTags)(type, options);
|
|
36
38
|
const parentTypeLink = (0, link_1.printParentLink)(type, options);
|
|
37
|
-
const
|
|
39
|
+
const permalink = options.sectionHeaderId && link.id
|
|
40
|
+
? String.raw `\{#${link.id}\}`
|
|
41
|
+
: undefined; // use raw string to prevent MDX from interpreting the curly braces as JSX
|
|
42
|
+
const metadata = [badges, tags, permalink].filter(Boolean).join(" ");
|
|
43
|
+
const title = `${options_1.SectionLevels.LEVEL.repeat(level)} ${typeNameLink}${parentTypeLink} ${metadata} ${strings_1.MARKDOWN_EOL}`;
|
|
38
44
|
const description = (0, common_1.printDescription)(type, options, "")
|
|
39
45
|
.trim()
|
|
40
46
|
.replaceAll("\n", `${strings_1.MARKDOWN_EOL}`);
|
|
@@ -66,11 +72,7 @@ const printSectionItems = (values, options) => {
|
|
|
66
72
|
return "";
|
|
67
73
|
}
|
|
68
74
|
const level = ("level" in options && typeof options.level === "number" ? options.level : 4);
|
|
69
|
-
const items = values
|
|
70
|
-
.filter((v) => {
|
|
71
|
-
return v;
|
|
72
|
-
})
|
|
73
|
-
.map((v) => {
|
|
75
|
+
const items = values.filter(Boolean).map((v) => {
|
|
74
76
|
return (0, exports.printSectionItem)(v, {
|
|
75
77
|
...options,
|
|
76
78
|
level,
|
|
@@ -91,7 +93,7 @@ exports.printSectionItems = printSectionItems;
|
|
|
91
93
|
*/
|
|
92
94
|
const printSection = (values, section, options) => {
|
|
93
95
|
if (!Array.isArray(values) || values.length === 0) {
|
|
94
|
-
return
|
|
96
|
+
return undefined;
|
|
95
97
|
}
|
|
96
98
|
const level = ("level" in options && typeof options.level === "number" ? options.level : 3);
|
|
97
99
|
const [openSection, closeSection] = (() => {
|
|
@@ -99,7 +101,7 @@ const printSection = (values, section, options) => {
|
|
|
99
101
|
typeof options.collapsible.dataClose === "string") {
|
|
100
102
|
return options.formatMDXDetails(options.collapsible).split(`\r`);
|
|
101
103
|
}
|
|
102
|
-
return [
|
|
104
|
+
return ["", strings_1.MARKDOWN_EOP];
|
|
103
105
|
})();
|
|
104
106
|
const items = (0, exports.printSectionItems)(values, {
|
|
105
107
|
...options,
|
|
@@ -107,9 +109,13 @@ const printSection = (values, section, options) => {
|
|
|
107
109
|
level: level >= 3 && level <= 5 ? (level + 1) : undefined,
|
|
108
110
|
});
|
|
109
111
|
if (items === "") {
|
|
110
|
-
return
|
|
112
|
+
return undefined; // do not print section is no items printed
|
|
111
113
|
}
|
|
112
|
-
return
|
|
114
|
+
return {
|
|
115
|
+
title: section,
|
|
116
|
+
content: `${openSection}${items}${closeSection}`,
|
|
117
|
+
level,
|
|
118
|
+
};
|
|
113
119
|
};
|
|
114
120
|
exports.printSection = printSection;
|
|
115
121
|
/**
|
|
@@ -130,7 +136,7 @@ const printMetadataSection = (type, values, section, options) => {
|
|
|
130
136
|
!("name" in type) ||
|
|
131
137
|
!Array.isArray(values) ||
|
|
132
138
|
values.length === 0) {
|
|
133
|
-
return
|
|
139
|
+
return undefined;
|
|
134
140
|
}
|
|
135
141
|
switch (options.deprecated) {
|
|
136
142
|
case "group": {
|
|
@@ -156,7 +162,22 @@ const printMetadataSection = (type, values, section, options) => {
|
|
|
156
162
|
dataClose: strings_1.DEPRECATED,
|
|
157
163
|
},
|
|
158
164
|
});
|
|
159
|
-
|
|
165
|
+
const content = [meta?.content, deprecatedMeta?.content]
|
|
166
|
+
.filter((entry) => {
|
|
167
|
+
return typeof entry === "string";
|
|
168
|
+
})
|
|
169
|
+
.join("");
|
|
170
|
+
if (content.trim().length === 0) {
|
|
171
|
+
return undefined;
|
|
172
|
+
}
|
|
173
|
+
const level = ("level" in options && typeof options.level === "number"
|
|
174
|
+
? options.level
|
|
175
|
+
: 3);
|
|
176
|
+
return {
|
|
177
|
+
title: section,
|
|
178
|
+
content,
|
|
179
|
+
level,
|
|
180
|
+
};
|
|
160
181
|
}
|
|
161
182
|
case "default":
|
|
162
183
|
default:
|