@ng-doc/builder 22.1.0 → 22.2.0

package/generator/vite/lifecycle.d.ts

@@ -26,6 +26,14 @@ export declare class ViteAdapterLifecycle {
      * description modules it read. `read` is computed on demand, once per snapshot.
      */
     private committed?;
+    /** Whether a content-only reload updates the open pages in place (`NGDOC_VITE_CONTENT_UPDATE`). */
+    private readonly contentUpdates;
+    /** The browser clients whose NgDoc client listens for content updates. */
+    private readonly contentClients;
+    /** The timestamp of the last content update: each one imports the modules anew. */
+    private contentStamp;
+    /** Records the clients that announce the NgDoc client. */
+    private readonly contentClient;
     /**
      * @param progress NgDoc's terminal progress: `interrupt` clears its live line before the adapter
      *   logs, and `release` follows each watch result the adapter has logged (or skipped), so the
@@ -38,6 +46,15 @@ export declare class ViteAdapterLifecycle {
     } | undefined);
     attachSession(session: BuildSession): void;
     attachServer(server: ViteDevServer, source: ViteFileEventSource): void;
+    /** Stops recording the clients that announce the NgDoc client. */
+    private stopContentClients;
+    /**
+     * Tells the browser about the newest settled publication: a content update when it changed only
+     * content (see `contentOnly`), else a full reload.
+     * @param changes The generated files that differ from the last announcement, if the reload may
+     *   be applied in place.
+     */
+    private announce;
     attachWatch(watch: WatchHandle): void;
     acceptInitial(result: BuildResult): Extract<BuildResult, {
         status: 'success';
@@ -59,9 +76,24 @@ export declare class ViteAdapterLifecycle {
      */
     private committedDescriptionModule;
     hostUpdateStarted(file: string, type: 'create' | 'update' | 'delete', read: () => string | Promise<string>): HostUpdateTicket;
-    hostUpdateCompleted(ticket: HostUpdateTicket): Promise<void>;
+    /**
+     * See {@link HostUpdateCoordinator.complete}.
+     * @param ticket The hot update's ticket.
+     * @param modules Whether its hooks hand Vite any module to update.
+     */
+    hostUpdateCompleted(ticket: HostUpdateTicket, modules?: boolean): Promise<void>;
     /** The adapter reloads for this settled hot update itself. */
     hostUpdateAnnounced(read: object): boolean;
+    /** See {@link HostUpdateCoordinator.generationPass}. */
+    hostGenerationPass(ticket: HostUpdateTicket): boolean;
+    /**
+     * Whether `file` is a description module (`ng-doc.page.ts`, `ng-doc.category.ts`,
+     * `ng-doc.api.ts`) the generator watches: its edit starts a generation that reads it.
+     * @param file An absolute path.
+     */
+    hostDescriptionModule(file: string): boolean;
+    /** Whether `file` is a generated output (see {@link HostUpdateCoordinator.generated}). */
+    hostGenerated(file: string): boolean;
     /** See {@link HostUpdateCoordinator.compilerCompanions}. */
     hostUpdateCompanions(ticket: HostUpdateTicket): string[];
     /**
@@ -92,7 +124,12 @@ export declare class ViteAdapterLifecycle {
     initialCompilationInventory(): import("./host-updates.js").InitialCompilationInventory;
     hostUpdateAcknowledged(ticket: HostUpdateTicket, resourceWitness?: boolean, compilerPass?: boolean, recoverBefore?: number): Promise<void>;
     hostUpdateDiagnostic(ticket: HostUpdateTicket, error: Error): void;
-    hostUpdateSettled(ticket: HostUpdateTicket): Promise<void>;
+    /**
+     * See {@link HostUpdateCoordinator.settle}.
+     * @param ticket The hot update's ticket.
+     * @param modules Whether its hooks hand Vite any module to update.
+     */
+    hostUpdateSettled(ticket: HostUpdateTicket, modules?: boolean): Promise<void>;
     hostUpdateCommitted(ticket: HostUpdateTicket): Promise<void>;
     hostUpdateFailed(error: Error): void;
     observer(configurationOf: (result: BuildResult) => PublishedGeneratorConfiguration | undefined): (event: BuildEvent) => void;

package/helpers/playground/get-playground-inputs.js

@@ -10,6 +10,7 @@ const get_input_name_1 = require("../angular/get-input-name");
 const get_input_type_1 = require("../angular/get-input-type");
 const get_js_doc_1 = require("../get-js-doc");
 const typescript_1 = require("../typescript");
+const playground_options_1 = require("./playground-options");
 /**
  *
  * @param declaration
@@ -52,9 +53,11 @@ function propOrParamToPlaygroundProperty(propOrParam, inputName) {
                 ts_morph_1.Node.isSetAccessorDeclaration(propOrParam)
                 ? (0, get_js_doc_1.getJsDocDescription)(propOrParam)
                 : (0, get_js_doc_1.getJsDocParam)(propOrParam.getParentIfKindOrThrow(ts_morph_1.SyntaxKind.MethodDeclaration), propOrParam.getName()),
-            options: inputType
-                .getUnionTypes()
-                .map((type) => type.getText(undefined, ts_morph_1.TypeFormatFlags.NoTruncation | ts_morph_1.TypeFormatFlags.UseSingleQuotesForStringLiteralType)),
+            // An array of a union of literals gets the members of its item type, as in the new engine.
+            options: (0, playground_options_1.playgroundArrayOptions)(propOrParam, inputType) ??
+                inputType
+                    .getUnionTypes()
+                    .map((type) => type.getText(undefined, ts_morph_1.TypeFormatFlags.NoTruncation | ts_morph_1.TypeFormatFlags.UseSingleQuotesForStringLiteralType)),
         },
     };
 }

package/helpers/playground/get-playground-inputs.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-playground-inputs.js","sourceRoot":"","sources":["../../../../../libs/builder/helpers/playground/get-playground-inputs.ts"],"names":[],"mappings":";;AAuBA,oEAUC;AAMD,0DAQC;AA9CD,uCAOkB;AAElB,qFAAqF;AACrF,gGAAgG;AAChG,0EAAqE;AACrE,8DAAyD;AACzD,8DAAyD;AAEzD,8CAAmE;AACnE,8CAA2C;AAE3C;;;GAGG;AACH,SAAgB,4BAA4B,CAC1C,WAA6B;IAE7B,OAAO,IAAA,yCAAkB,EAAC,WAAW,CAAC,CAAC,MAAM,CAC3C,CAAC,UAAqC,EAAE,QAA+B,EAAE,EAAE;QACzE,MAAM,SAAS,GAAW,IAAA,6BAAY,EAAC,QAAQ,CAAC,CAAC;QACjD,OAAO,EAAE,GAAG,UAAU,EAAE,GAAG,+BAA+B,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;IACpF,CAAC,EACD,EAAE,CACH,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,uBAAuB,CAAC,WAA6B;IACnE,OAAO,WAAW;SACf,gBAAgB,CAAC,WAAW,CAAC;SAC7B,aAAa,EAAE;SACf,KAAK,CAAC,CAAC,CAAC;SACR,MAAM,CAAC,CAAC,UAAqC,EAAE,SAA+B,EAAE,EAAE;QACjF,OAAO,EAAE,GAAG,UAAU,EAAE,GAAG,+BAA+B,CAAC,SAAS,CAAC,EAAE,CAAC;IAC1E,CAAC,EAAE,EAAE,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,SAAS,+BAA+B,CACtC,WAAyD,EACzD,SAAkB;IAElB,MAAM,SAAS,GAAG,eAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC;QACvD,CAAC,CAAC,IAAA,6BAAY,EAAC,WAAW,CAAC;QAC3B,CAAC,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAW,IAAA,uBAAU,EAC7B,SAAS,EACT,0BAAe,CAAC,YAAY,GAAG,0BAAe,CAAC,mCAAmC,CACnF,CAAC;IAEF,OAAO;QACL,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,EAAE;YACvB,SAAS,EAAE,SAAS,IAAI,WAAW,CAAC,OAAO,EAAE;YAC7C,IAAI;YACJ,WAAW,EACT,eAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC;gBACvC,eAAI,CAAC,wBAAwB,CAAC,WAAW,CAAC;gBAC1C,eAAI,CAAC,wBAAwB,CAAC,WAAW,CAAC;gBACxC,CAAC,CAAC,IAAA,gCAAmB,EAAC,WAAW,CAAC;gBAClC,CAAC,CAAC,IAAA,0BAAa,EACX,WAAW,CAAC,sBAAsB,CAAC,qBAAU,CAAC,iBAAiB,CAAC,EAChE,WAAW,CAAC,OAAO,EAAE,CACtB;YACP,OAAO,EAAE,SAAS;iBACf,aAAa,EAAE;iBACf,GAAG,CAAC,CAAC,IAAU,EAAE,EAAE,CAClB,IAAI,CAAC,OAAO,CACV,SAAS,EACT,0BAAe,CAAC,YAAY,GAAG,0BAAe,CAAC,mCAAmC,CACnF,CACF;SACJ;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"get-playground-inputs.js","sourceRoot":"","sources":["../../../../../libs/builder/helpers/playground/get-playground-inputs.ts"],"names":[],"mappings":";;AAwBA,oEAUC;AAMD,0DAQC;AA/CD,uCAOkB;AAElB,qFAAqF;AACrF,gGAAgG;AAChG,0EAAqE;AACrE,8DAAyD;AACzD,8DAAyD;AAEzD,8CAAmE;AACnE,8CAA2C;AAC3C,6DAA8D;AAE9D;;;GAGG;AACH,SAAgB,4BAA4B,CAC1C,WAA6B;IAE7B,OAAO,IAAA,yCAAkB,EAAC,WAAW,CAAC,CAAC,MAAM,CAC3C,CAAC,UAAqC,EAAE,QAA+B,EAAE,EAAE;QACzE,MAAM,SAAS,GAAW,IAAA,6BAAY,EAAC,QAAQ,CAAC,CAAC;QACjD,OAAO,EAAE,GAAG,UAAU,EAAE,GAAG,+BAA+B,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;IACpF,CAAC,EACD,EAAE,CACH,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,uBAAuB,CAAC,WAA6B;IACnE,OAAO,WAAW;SACf,gBAAgB,CAAC,WAAW,CAAC;SAC7B,aAAa,EAAE;SACf,KAAK,CAAC,CAAC,CAAC;SACR,MAAM,CAAC,CAAC,UAAqC,EAAE,SAA+B,EAAE,EAAE;QACjF,OAAO,EAAE,GAAG,UAAU,EAAE,GAAG,+BAA+B,CAAC,SAAS,CAAC,EAAE,CAAC;IAC1E,CAAC,EAAE,EAAE,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,SAAS,+BAA+B,CACtC,WAAyD,EACzD,SAAkB;IAElB,MAAM,SAAS,GAAG,eAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC;QACvD,CAAC,CAAC,IAAA,6BAAY,EAAC,WAAW,CAAC;QAC3B,CAAC,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAW,IAAA,uBAAU,EAC7B,SAAS,EACT,0BAAe,CAAC,YAAY,GAAG,0BAAe,CAAC,mCAAmC,CACnF,CAAC;IAEF,OAAO;QACL,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,EAAE;YACvB,SAAS,EAAE,SAAS,IAAI,WAAW,CAAC,OAAO,EAAE;YAC7C,IAAI;YACJ,WAAW,EACT,eAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC;gBACvC,eAAI,CAAC,wBAAwB,CAAC,WAAW,CAAC;gBAC1C,eAAI,CAAC,wBAAwB,CAAC,WAAW,CAAC;gBACxC,CAAC,CAAC,IAAA,gCAAmB,EAAC,WAAW,CAAC;gBAClC,CAAC,CAAC,IAAA,0BAAa,EACX,WAAW,CAAC,sBAAsB,CAAC,qBAAU,CAAC,iBAAiB,CAAC,EAChE,WAAW,CAAC,OAAO,EAAE,CACtB;YACP,2FAA2F;YAC3F,OAAO,EACL,IAAA,2CAAsB,EAAC,WAAW,EAAE,SAAS,CAAC;gBAC9C,SAAS;qBACN,aAAa,EAAE;qBACf,GAAG,CAAC,CAAC,IAAU,EAAE,EAAE,CAClB,IAAI,CAAC,OAAO,CACV,SAAS,EACT,0BAAe,CAAC,YAAY,GAAG,0BAAe,CAAC,mCAAmC,CACnF,CACF;SACN;KACF,CAAC;AACJ,CAAC"}

package/helpers/playground/playground-options.d.ts

@@ -0,0 +1,28 @@
+import type { NgDocPlaygroundOption } from '@ng-doc/core';
+import { Node, Type } from 'ts-morph';
+import { NgDocInputDeclaration } from '../angular/is-input';
+/**
+ * An option of a union input. The runtime evaluates the printed text of a member, which works for
+ * literals (`'small'`, `1`) but not for an enum member (`Status.Good`): a member of an enum is the
+ * member's name, which the playground shows, and the literal value the checker resolved for it,
+ * which the playground sets.
+ * @param member - A member of the input's union type.
+ */
+export declare function playgroundOption(member: Type): string | NgDocPlaygroundOption;
+/**
+ * The options of an array input whose items are a union of literals, such as `NgDocSize[]`,
+ * `('a' | 'b')[]`, `Array<'x' | 'y'>` or `Status[]` of an enum, optional or nullable too: the
+ * members of the item type, which the playground's multi-select offers. Both engines call it, so
+ * their options are the same.
+ *
+ * The members are listed in the order the item type is written (`writtenOrder`), and the members
+ * the syntax does not name (the literals of a `boolean` among them) by their printed text, never
+ * in the checker's order, which differs between the engines' programs. `undefined` and `null`
+ * items are left out: the multi-select adds values. An array of booleans only, a tuple, an
+ * array whose items are not all literals, and an alias of an array type (printed by its name, so
+ * the playground can't read it as an array) have no such options.
+ * @param declaration - The input property, accessor or pipe parameter.
+ * @param type - The input's type.
+ * @returns The options, or `undefined` when the input is not such an array.
+ */
+export declare function playgroundArrayOptions(declaration: NgDocInputDeclaration | Node, type: Type): Array<string | NgDocPlaygroundOption> | undefined;

package/helpers/playground/playground-options.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.playgroundOption = playgroundOption;
+exports.playgroundArrayOptions = playgroundArrayOptions;
+const ts_morph_1 = require("ts-morph");
+const text_order_1 = require("../text-order");
+const written_union_order_1 = require("./written-union-order");
+/** How option texts are printed: in full, with the single quotes the runtime evaluates. */
+const OPTION_TEXT_FLAGS = ts_morph_1.TypeFormatFlags.NoTruncation | ts_morph_1.TypeFormatFlags.UseSingleQuotesForStringLiteralType;
+/**
+ * An option of a union input. The runtime evaluates the printed text of a member, which works for
+ * literals (`'small'`, `1`) but not for an enum member (`Status.Good`): a member of an enum is the
+ * member's name, which the playground shows, and the literal value the checker resolved for it,
+ * which the playground sets.
+ * @param member - A member of the input's union type.
+ */
+function playgroundOption(member) {
+    if (member.isEnumLiteral()) {
+        const value = member.getLiteralValue();
+        const name = member.getSymbol()?.getName();
+        if (name && (typeof value === 'string' || typeof value === 'number'))
+            return { label: name, value };
+    }
+    return member.getText(undefined, OPTION_TEXT_FLAGS);
+}
+/**
+ * The options of an array input whose items are a union of literals, such as `NgDocSize[]`,
+ * `('a' | 'b')[]`, `Array<'x' | 'y'>` or `Status[]` of an enum, optional or nullable too: the
+ * members of the item type, which the playground's multi-select offers. Both engines call it, so
+ * their options are the same.
+ *
+ * The members are listed in the order the item type is written (`writtenOrder`), and the members
+ * the syntax does not name (the literals of a `boolean` among them) by their printed text, never
+ * in the checker's order, which differs between the engines' programs. `undefined` and `null`
+ * items are left out: the multi-select adds values. An array of booleans only, a tuple, an
+ * array whose items are not all literals, and an alias of an array type (printed by its name, so
+ * the playground can't read it as an array) have no such options.
+ * @param declaration - The input property, accessor or pipe parameter.
+ * @param type - The input's type.
+ * @returns The options, or `undefined` when the input is not such an array.
+ */
+function playgroundArrayOptions(declaration, type) {
+    const arrays = withoutNullish(type.isUnion() ? type.getUnionTypes() : [type]);
+    const array = arrays.length === 1 ? arrays[0] : undefined;
+    if (!array || !(array.isArray() || array.isReadonlyArray()) || array.getAliasSymbol()) {
+        return undefined;
+    }
+    const item = array.getTypeArguments()[0];
+    const members = item?.isUnion() ? withoutNullish(item.getUnionTypes()) : [];
+    if (!members.length ||
+        !members.every(isLiteral) ||
+        members.every((member) => member.isBooleanLiteral())) {
+        return undefined;
+    }
+    const byText = [...members].sort((a, b) => compareTexts(text(a), text(b)));
+    return (0, written_union_order_1.writtenOrder)(itemTypeNode((0, written_union_order_1.writtenTypeNode)(declaration)), byText).map(playgroundOption);
+}
+/**
+ * The type node of the items of a written array type: `T` of `T[]`, `readonly T[]`, `Array<T>`
+ * and `ReadonlyArray<T>`, alone or in a union with `undefined` or `null`.
+ * @param node - The written type of the input.
+ */
+function itemTypeNode(node) {
+    if (!node)
+        return undefined;
+    if (ts_morph_1.Node.isParenthesizedTypeNode(node))
+        return itemTypeNode(node.getTypeNode());
+    if (ts_morph_1.Node.isUnionTypeNode(node)) {
+        const rest = node.getTypeNodes().filter((member) => !isNullish(member));
+        return rest.length === 1 ? itemTypeNode(rest[0]) : undefined;
+    }
+    if (ts_morph_1.Node.isTypeOperatorTypeNode(node) && node.getOperator() === ts_morph_1.SyntaxKind.ReadonlyKeyword)
+        return itemTypeNode(node.getTypeNode());
+    if (ts_morph_1.Node.isArrayTypeNode(node))
+        return node.getElementTypeNode();
+    if (ts_morph_1.Node.isTypeReference(node) && /^(?:Readonly)?Array$/.test(node.getTypeName().getText()))
+        return node.getTypeArguments()[0];
+    return undefined;
+}
+/**
+ * Whether a written type is `undefined` or `null`.
+ * @param node - A member of a written union.
+ */
+function isNullish(node) {
+    return (node.getKind() === ts_morph_1.SyntaxKind.UndefinedKeyword ||
+        (ts_morph_1.Node.isLiteralTypeNode(node) && node.getLiteral().getKind() === ts_morph_1.SyntaxKind.NullKeyword));
+}
+/**
+ * The types other than `undefined` and `null`.
+ * @param types - The members of a union.
+ */
+function withoutNullish(types) {
+    return types.filter((type) => !type.isUndefined() && !type.isNull());
+}
+/**
+ * Whether a type is a literal the playground can set: a string, number or boolean literal, or an
+ * enum member.
+ * @param type - A member of the item union.
+ */
+function isLiteral(type) {
+    return (type.isStringLiteral() ||
+        type.isNumberLiteral() ||
+        type.isBooleanLiteral() ||
+        type.isEnumLiteral());
+}
+/**
+ * The printed text of a member.
+ * @param type - A member of the item union.
+ */
+function text(type) {
+    return type.getText(undefined, OPTION_TEXT_FLAGS);
+}
+/**
+ * Orders texts in NgDoc's fixed text order, and texts the collator finds equal by code units, so
+ * the order never depends on the program or the machine.
+ * @param a - A text.
+ * @param b - Another text.
+ */
+function compareTexts(a, b) {
+    return (0, text_order_1.compareText)(a, b) || (a < b ? -1 : a > b ? 1 : 0);
+}
+//# sourceMappingURL=playground-options.js.map

package/helpers/playground/playground-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playground-options.js","sourceRoot":"","sources":["../../../../../libs/builder/helpers/playground/playground-options.ts"],"names":[],"mappings":"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"}

package/helpers/playground/written-union-order.d.ts

@@ -0,0 +1,33 @@
+import { Node, Type, TypeNode } from 'ts-morph';
+import { NgDocInputDeclaration } from '../angular/is-input';
+/**
+ * The members of `type`'s union in the order the author wrote them.
+ *
+ * The checker's order is not the author's: without `stableTypeOrdering` it is the creation order
+ * of the member types (which depends on what the checker was asked before), with it literals sort
+ * by value. A playground lists its options from that union, so the list is read from the syntax: the type node written for the input (its annotation, or the type
+ * argument of `input<T>()`, `input.required<T>()` or `model<T>()`), followed through unions,
+ * parentheses, non-generic type aliases and enums, to its literal members. Those members take their
+ * written order, in the positions they hold in the checker's list; every member the syntax does
+ * not name (`undefined` of an optional input, `boolean`'s literals, a generic alias) keeps the
+ * checker's position. Without a written node the checker's order is returned.
+ * @param declaration - The input property, accessor or pipe parameter.
+ * @param type - The input's type.
+ * @param members - The union's members in the order to fall back to (default: the checker's).
+ */
+export declare function writtenUnionOrder(declaration: NgDocInputDeclaration | Node, type: Type, members?: Type[]): Type[];
+/**
+ * The members of a union in the order a written type node names them (see
+ * {@link writtenUnionOrder}): the members the node names, through unions, parentheses,
+ * non-generic type aliases and enums, take their written order in the positions they hold in
+ * `members`; the others keep their positions. Without a node, `members` is returned.
+ * @param node - The type node the author wrote for the union, if any.
+ * @param members - The union's members in the order to fall back to.
+ */
+export declare function writtenOrder(node: TypeNode | undefined, members: Type[]): Type[];
+/**
+ * The type node the author wrote for an input or parameter, if any: its annotation, or the type
+ * argument of `input<T>()`, `input.required<T>()` or `model<T>()`.
+ * @param declaration - The input property, accessor or pipe parameter.
+ */
+export declare function writtenTypeNode(declaration: NgDocInputDeclaration | Node): TypeNode | undefined;

package/helpers/playground/written-union-order.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writtenUnionOrder = writtenUnionOrder;
+exports.writtenOrder = writtenOrder;
+exports.writtenTypeNode = writtenTypeNode;
+const ts_morph_1 = require("ts-morph");
+const is_input_1 = require("../angular/is-input");
+/**
+ * The members of `type`'s union in the order the author wrote them.
+ *
+ * The checker's order is not the author's: without `stableTypeOrdering` it is the creation order
+ * of the member types (which depends on what the checker was asked before), with it literals sort
+ * by value. A playground lists its options from that union, so the list is read from the syntax: the type node written for the input (its annotation, or the type
+ * argument of `input<T>()`, `input.required<T>()` or `model<T>()`), followed through unions,
+ * parentheses, non-generic type aliases and enums, to its literal members. Those members take their
+ * written order, in the positions they hold in the checker's list; every member the syntax does
+ * not name (`undefined` of an optional input, `boolean`'s literals, a generic alias) keeps the
+ * checker's position. Without a written node the checker's order is returned.
+ * @param declaration - The input property, accessor or pipe parameter.
+ * @param type - The input's type.
+ * @param members - The union's members in the order to fall back to (default: the checker's).
+ */
+function writtenUnionOrder(declaration, type, members = type.getUnionTypes()) {
+    return writtenOrder(writtenTypeNode(declaration), members);
+}
+/**
+ * The members of a union in the order a written type node names them (see
+ * {@link writtenUnionOrder}): the members the node names, through unions, parentheses,
+ * non-generic type aliases and enums, take their written order in the positions they hold in
+ * `members`; the others keep their positions. Without a node, `members` is returned.
+ * @param node - The type node the author wrote for the union, if any.
+ * @param members - The union's members in the order to fall back to.
+ */
+function writtenOrder(node, members) {
+    if (!node || members.length < 2)
+        return members;
+    const written = [];
+    collect(node, written, new Set());
+    const slots = new Set(members.map((member) => member.compilerType));
+    const order = written.filter((member, index) => slots.has(member) && written.indexOf(member) === index);
+    const named = new Set(order);
+    let next = 0;
+    const byCompiler = new Map(members.map((member) => [member.compilerType, member]));
+    return members.map((member) => named.has(member.compilerType) ? byCompiler.get(order[next++]) : member);
+}
+/**
+ * The type node the author wrote for an input or parameter, if any: its annotation, or the type
+ * argument of `input<T>()`, `input.required<T>()` or `model<T>()`.
+ * @param declaration - The input property, accessor or pipe parameter.
+ */
+function writtenTypeNode(declaration) {
+    if (ts_morph_1.Node.isPropertyDeclaration(declaration) && (0, is_input_1.isInputSignal)(declaration)) {
+        const initializer = declaration.getInitializer();
+        return ts_morph_1.Node.isCallExpression(initializer) ? initializer.getTypeArguments()[0] : undefined;
+    }
+    if (ts_morph_1.Node.isSetAccessorDeclaration(declaration))
+        return declaration.getParameters()[0]?.getTypeNode();
+    if (ts_morph_1.Node.isGetAccessorDeclaration(declaration))
+        return declaration.getReturnTypeNode();
+    if (ts_morph_1.Node.isPropertyDeclaration(declaration) || ts_morph_1.Node.isParameterDeclaration(declaration))
+        return declaration.getTypeNode();
+    return undefined;
+}
+/** Appends the member types `node` names, in written order. */
+function collect(node, into, seen) {
+    if (seen.has(node))
+        return;
+    seen.add(node);
+    if (ts_morph_1.Node.isUnionTypeNode(node)) {
+        node.getTypeNodes().forEach((member) => collect(member, into, seen));
+        return;
+    }
+    if (ts_morph_1.Node.isParenthesizedTypeNode(node)) {
+        collect(node.getTypeNode(), into, seen);
+        return;
+    }
+    if (ts_morph_1.Node.isTypeReference(node) && !node.getTypeArguments().length) {
+        let symbol = node.getTypeName().getSymbol();
+        if (symbol?.isAlias())
+            symbol = symbol.getAliasedSymbol();
+        const declaration = symbol?.getDeclarations()[0];
+        if (ts_morph_1.Node.isTypeAliasDeclaration(declaration) && !declaration.getTypeParameters().length) {
+            const aliased = declaration.getTypeNode();
+            if (aliased) {
+                collect(aliased, into, seen);
+                return;
+            }
+        }
+        if (ts_morph_1.Node.isEnumDeclaration(declaration)) {
+            // A member's declared type is the fresh literal type; a union holds the regular one.
+            declaration
+                .getMembers()
+                .forEach((member) => into.push(regularType(member.getType().compilerType)));
+            return;
+        }
+    }
+    into.push(node.getType().compilerType);
+}
+/**
+ * The regular type of a fresh literal type, which is the one unions hold; other types as they are.
+ * @param type - A type.
+ */
+function regularType(type) {
+    return type.regularType ?? type;
+}
+//# sourceMappingURL=written-union-order.js.map

package/helpers/playground/written-union-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"written-union-order.js","sourceRoot":"","sources":["../../../../../libs/builder/helpers/playground/written-union-order.ts"],"names":[],"mappings":"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"}

package/interfaces/configuration.d.ts

@@ -52,12 +52,20 @@ export interface NgDocConfiguration {
      * (`false` by default). It also builds a demo page for every demo. Only the Vite engine reads it.
      */
     isolatedDemos?: boolean;
+    /**
+     * Renders the demos of every playground in iframes, as `isolated: true` does for one playground
+     * (`false` by default). It also builds the playground pages of every playground. Only the Vite
+     * engine reads it; the legacy engine renders playgrounds in the page.
+     */
+    isolatedPlaygrounds?: boolean;
     /**
      * The demo pages: one page per demo that loads only Angular and that demo, which isolated demos
-     * show in an iframe and "Open in new tab" opens. Only the Vite engine builds them.
+     * show in an iframe and "Open in new tab" opens, and one page per target of each playground,
+     * which isolated playgrounds show in iframes. Only the Vite engine builds them.
      *
-     * By default only the pages with an isolated demo get them. `true` (or an object) builds them for
-     * every page with demos; `false` never builds them, and isolated demos render in the page.
+     * By default only the pages with an isolated demo or playground get them. `true` (or an object)
+     * builds the demo pages of every page with demos; playground pages are built only for isolated
+     * playgrounds. `false` never builds them, and isolated demos and playgrounds render in the page.
      */
     demoApplication?: boolean | NgDocDemoApplicationConfiguration;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-doc/builder",
-  "version": "22.1.0",
+  "version": "22.2.0",
   "description": "Generates an NgDoc documentation site from your Markdown pages and TypeScript code.",
   "keywords": [
     "angular",
@@ -31,8 +31,8 @@
     ]
   },
   "dependencies": {
-    "@ng-doc/core": "22.1.0",
-    "@ng-doc/utils": "22.1.0",
+    "@ng-doc/core": "22.2.0",
+    "@ng-doc/utils": "22.2.0",
     "@angular-devkit/architect": ">=0.2200.0 <0.2300.0",
     "minimatch": "9.0.9",
     "rxjs": "^7.0.0",
@@ -122,7 +122,7 @@
     "ng-doc": "./generator/bootstrap/bin.js"
   },
   "engines": {
-    "node": ">=24.15.0 <25"
+    "node": ">=24.15.0 <25 || >=26.0.0 <27"
   },
   "author": "Skoropad Aleksandr <alex@skoropad.dev>"
 }

package/templates/demo-routes.ts.nunj

@@ -1,13 +1,25 @@
 // @ts-nocheck
 import {Routes} from '@angular/router';
+{%- if demos.length or not playgrounds.length %}
 import {NgDocDemoHostComponent} from '@ng-doc/app/demo-app';
+{%- endif %}
+{%- if playgrounds.length %}
+import {NgDocPlaygroundHostComponent} from '@ng-doc/app/components/playground';
+{%- endif %}
 import entry from '{{ entryImport }}';
+{%- if playgrounds.length %}
+import {PLAYGROUND_PROVIDERS} from '{{ playgroundsImport }}';
+{%- endif %}
 
 // The demo pages of one guide: one route per demo, under the page's providers, as the demos have
 // them on the page.
+{%- if playgrounds.length %}
+// Its playground pages: one route per target of each playground, which finds the generated
+// playground classes of the page through PLAYGROUND_PROVIDERS, as the page does.
+{%- endif %}
 const routes: Routes = [{
   path: '',
-  providers: [...(entry.providers ?? [])],
+  providers: [{% if playgrounds.length %}PLAYGROUND_PROVIDERS, {% endif %}...(entry.providers ?? [])],
   children: [
     {%- for demo in demos %}
     {
@@ -17,6 +29,14 @@ const routes: Routes = [{
       data: {ngDocDemo: entry.demos?.['{{ demo.name }}']},
     },
     {%- endfor %}
+    {%- for playground in playgrounds %}
+    {
+      path: '{{ playground.path }}',
+      component: NgDocPlaygroundHostComponent,
+      title: `{{ playground.title | toTemplateString }}`,
+      data: {ngDocPlayground: {{ playground.data | dump }}},
+    },
+    {%- endfor %}
   ],
 }];
 

package/templates/page.ts.nunj

@@ -64,12 +64,16 @@ export class PageComponent extends NgDocRootPage {
     {%- if demoAssetsPath %}
   readonly demoAssets: NgDocDemoAssets = demoAssets;
     {%- endif %}
-    {#- The demo pages of the guide (Vite engine), and whether its demos are isolated by default. #}
+    {#- The demo and playground pages of the guide (Vite engine), and whether its demos and
+        playgrounds are isolated by default. #}
     {%- if demoRoute %}
   readonly demoRoute: string = '{{ demoRoute | replace("\\", "\\\\") | replace("'", "\\'") | replace("\n", "\\n") }}';
       {%- if isolatedDemos %}
   readonly isolatedDemos: boolean = true;
       {%- endif %}
+      {%- if isolatedPlaygrounds %}
+  readonly isolatedPlaygrounds: boolean = true;
+      {%- endif %}
     {%- endif %}
 
   constructor() {