@ng-doc/builder 22.0.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;
@@ -111,6 +148,7 @@ export declare class ViteAdapterLifecycle {
     private reconcile;
     private fail;
     private report;
+    private warn;
     private isCurrent;
     private log;
     private interrupt;

package/generator/vite/prerender-entry.js

@@ -301,13 +301,82 @@ async function runPrerender(request, options = {}) {
     errors.push({ route: current, message: format(...args) });
     log.apply(console, args);
   };
+  const warnings = [];
   try {
-    return { ...await renderRoutes(), errors };
+    const report = await renderRoutes();
+    if (request.demoServerEntry) report.routes = await renderDemoRoutes(report.routes);
+    return { ...report, errors, ...warnings.length ? { warnings } : {} };
   } finally {
     console.error = log;
     restoreWarnings();
     globalThis.fetch = originalFetch;
   }
+  async function renderDemoRoutes(rendered) {
+    const shellFile2 = path2.join(browserDir, DEMO_SHELL);
+    const message = (error) => error instanceof Error ? error.message : String(error);
+    let demoDocument;
+    let demo;
+    let inventory;
+    current = `/${DEMO_SHELL}`;
+    try {
+      demoDocument = await readFile(shellFile2, "utf8");
+      demo = serverEntry(
+        await importModule(pathToFileURL(path2.resolve(request.demoServerEntry)).href)
+      );
+      await withTimeout(
+        demo.renderApplication(
+          async (context) => {
+            const application = await demo.bootstrap(context);
+            const router = application.injector.get(demo.Router);
+            inventory = await enumerateRoutes(Array.isArray(router?.config) ? router.config : [], {
+              invoke: (factory) => demo.runInInjectionContext(application.injector, factory)
+            });
+            return application;
+          },
+          { document: demoDocument, url: url("/"), allowedHosts: [HOST] }
+        ),
+        request.routeTimeoutMs,
+        current
+      );
+    } catch (error) {
+      warnings.push({
+        route: current,
+        message: `[NGDOC_PRERENDER_DEMO_APPLICATION] The demo pages were not prerendered: ${message(error)}`
+      });
+      return rendered;
+    }
+    const taken = new Set(rendered.map((route) => route.path));
+    const result = [...rendered];
+    for (const route of inventory.routes) {
+      if (route.redirectTo !== void 0 || taken.has(route.path)) continue;
+      const file = routeFile(route.path);
+      current = route.path;
+      let html;
+      try {
+        html = await withTimeout(
+          demo.renderApplication(demo.bootstrap, {
+            document: demoDocument,
+            url: url(route.path),
+            allowedHosts: [HOST]
+          }),
+          request.routeTimeoutMs,
+          route.path
+        );
+      } catch (error) {
+        warnings.push({
+          route: route.path,
+          message: `[NGDOC_PRERENDER_DEMO_FALLBACK] The demo page did not render on the server, so it renders in the browser only: ${message(error)}`
+        });
+        html = demoDocument;
+      }
+      await mkdir(path2.dirname(path2.join(browserDir, file)), { recursive: true });
+      await writeFile(path2.join(browserDir, file), html);
+      result.push({ ...route, file });
+    }
+    return result.sort(
+      (left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0
+    );
+  }
   async function renderRoutes() {
     const discovered = [];
     const excluded = [];
@@ -374,13 +443,14 @@ function runPrerenderChild(port, run = runPrerender) {
     );
   });
 }
-var SHELL, HOST;
+var SHELL, DEMO_SHELL, HOST;
 var init_prerender_runtime = __esm({
   "libs/builder/generator/vite/prerender-runtime.ts"() {
     "use strict";
     init_mime();
     init_route_inventory();
     SHELL = "index.csr.html";
+    DEMO_SHELL = "ng-doc-demo.html";
     HOST = "localhost";
   }
 });

package/generator/vite/prerender-runtime.d.ts

@@ -11,6 +11,11 @@ export interface PrerenderRequest {
     discoverRoutes: boolean;
     /** Fails a route that takes longer to render, in milliseconds. */
     routeTimeoutMs?: number;
+    /**
+     * The server bundle of the demo application (`demo-server.mjs`), when the build has demo pages.
+     * Its routes are rendered into the demo application's page (`ng-doc-demo.html`).
+     */
+    demoServerEntry?: string;
 }
 export interface PrerenderReport {
     /** Every rendered route, in code-unit order, with the file written for it. */
@@ -26,6 +31,14 @@ export interface PrerenderReport {
         route: string;
         message: string;
     }>;
+    /**
+     * Demo pages that failed to render, which got the demo application's client page instead, and
+     * a demo application that could not be prerendered at all. Absent when there are none.
+     */
+    warnings?: Array<{
+        route: string;
+        message: string;
+    }>;
 }
 export interface PrerenderRuntimeOptions {
     /** Imports the server bundle; tests replace it. */

package/generator/vite/prerender.d.ts

@@ -12,6 +12,8 @@ export interface NgDocPrerenderOptions {
     discoverRoutes?: boolean;
     /** Fails a route that takes longer to render, in milliseconds (default: no limit). */
     routeTimeoutMs?: number;
+    /** The demo application's server bundle (`demo-server.mjs`), when the build has demo pages. */
+    demoServerEntry?: string;
     signal?: AbortSignal;
     /** The child process entry; tests replace it. */
     entryUrl?: URL;

package/helpers/format-cache.d.ts

@@ -0,0 +1,34 @@
+import type { Options } from 'prettier';
+/**
+ * A cache that `formatCode` consults while it is installed with {@link withFormatCodeCache}. The
+ * new engine installs one around its own formatting calls; without one (the legacy engine, the
+ * kill switch, the reference path) `formatCode` resolves the configuration and formats every
+ * call, as it always did.
+ */
+export interface FormatCodeCache {
+    /**
+     * The Prettier configuration for `configDirectory`. `resolve` reads it; the cache may call it
+     * once and return that value for later calls. An error of `resolve` is thrown to the caller.
+     */
+    config(configDirectory: string | undefined, resolve: () => Options | null): Options | null;
+    /**
+     * The formatted code. `format` formats it; the cache may return a value it stored for the same
+     * code, parser and configuration instead. An error of `format` is thrown; the cache may store a
+     * Prettier syntax error (deterministic for these inputs) and throw one again on a hit, so
+     * `formatCode` returns the code unformatted in both cases.
+     */
+    format(input: {
+        code: string;
+        parser: string;
+        config: Options | null;
+    }, format: () => string): string;
+}
+/**
+ * Runs `run` with `cache` installed for every `formatCode` call it makes synchronously, and
+ * restores the previous one afterwards.
+ * @param cache The cache to install, or undefined for none.
+ * @param run The synchronous work that formats.
+ */
+export declare function withFormatCodeCache<T>(cache: FormatCodeCache | undefined, run: () => T): T;
+/** The cache installed by {@link withFormatCodeCache}, if any. */
+export declare function activeFormatCodeCache(): FormatCodeCache | undefined;

package/helpers/format-cache.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withFormatCodeCache = withFormatCodeCache;
+exports.activeFormatCodeCache = activeFormatCodeCache;
+let active;
+/**
+ * Runs `run` with `cache` installed for every `formatCode` call it makes synchronously, and
+ * restores the previous one afterwards.
+ * @param cache The cache to install, or undefined for none.
+ * @param run The synchronous work that formats.
+ */
+function withFormatCodeCache(cache, run) {
+    const previous = active;
+    active = cache;
+    try {
+        return run();
+    }
+    finally {
+        active = previous;
+    }
+}
+/** The cache installed by {@link withFormatCodeCache}, if any. */
+function activeFormatCodeCache() {
+    return active;
+}
+//# sourceMappingURL=format-cache.js.map

package/helpers/format-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-cache.js","sourceRoot":"","sources":["../../../../libs/builder/helpers/format-cache.ts"],"names":[],"mappings":";;AAkCA,kDAQC;AAGD,sDAEC;AArBD,IAAI,MAAmC,CAAC;AAExC;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAI,KAAkC,EAAE,GAAY;IACrF,MAAM,QAAQ,GAAG,MAAM,CAAC;IACxB,MAAM,GAAG,KAAK,CAAC;IACf,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC;IACf,CAAC;YAAS,CAAC;QACT,MAAM,GAAG,QAAQ,CAAC;IACpB,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,SAAgB,qBAAqB;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/helpers/format-code.js

@@ -4,6 +4,7 @@ exports.formatCode = formatCode;
 const tslib_1 = require("tslib");
 const sync_1 = tslib_1.__importDefault(require("@prettier/sync"));
 const node_path_1 = require("node:path");
+const format_cache_1 = require("./format-cache");
 /**
  *    Format code with Prettier
  * @param code - Code to format
@@ -14,14 +15,20 @@ function formatCode(code, codeType = 'TypeScript', configDirectory) {
     try {
         if (codeType) {
             const parser = getPrettierParserFromCodeType(codeType);
-            const config = sync_1.default.resolveConfig(
+            // The new engine's cache, when it formats (see `./format-cache`); none in the legacy engine.
+            const cache = (0, format_cache_1.activeFormatCodeCache)();
+            const resolve = () => sync_1.default.resolveConfig(
             // Prettier searches from a file's parent, so use a synthetic path inside the directory.
             configDirectory ? (0, node_path_1.join)(configDirectory, '__ng_doc_format__.ts') : process.cwd(), { editorconfig: true, useCache: false });
-            return sync_1.default.format(code, {
+            const config = cache ? cache.config(configDirectory, resolve) : resolve();
+            const format = () => sync_1.default.format(code, {
                 ...config,
                 parser,
                 embeddedLanguageFormatting: 'auto',
             }).trim();
+            return cache && typeof parser === 'string'
+                ? cache.format({ code, parser, config }, format)
+                : format();
         }
         return code.trim();
     }

package/helpers/format-code.js.map

@@ -1 +1 @@
-{"version":3,"file":"format-code.js","sourceRoot":"","sources":["../../../../libs/builder/helpers/format-code.ts"],"names":[],"mappings":";;AAWA,gCA2BC;;AArCD,kEAA0C;AAC1C,yCAAiC;AAGjC;;;;;GAKG;AACH,SAAgB,UAAU,CACxB,IAAY,EACZ,WAAiC,YAAY,EAC7C,eAAwB;IAExB,IAAI,CAAC;QACH,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,MAAM,GAAkC,6BAA6B,CAAC,QAAQ,CAAC,CAAC;YACtF,MAAM,MAAM,GAAG,cAAY,CAAC,aAAa;YACvC,wFAAwF;YACxF,eAAe,CAAC,CAAC,CAAC,IAAA,gBAAI,EAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,EAC/E,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CACxC,CAAC;YAEF,OACE,cAAY,CAAC,MAAM,CAAC,IAAI,EAAE;gBACxB,GAAG,MAAM;gBACT,MAAM;gBACN,0BAA0B,EAAE,MAAM;aACnC,CACF,CAAC,IAAI,EAAE,CAAC;QACX,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,6BAA6B,CAAC,QAAuB;IAC5D,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,KAAK,CAAC;QACX,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,KAAK,CAAC;QACf,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,YAAY,CAAC;QAClB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}
+{"version":3,"file":"format-code.js","sourceRoot":"","sources":["../../../../libs/builder/helpers/format-code.ts"],"names":[],"mappings":";;AAaA,gCAmCC;;AA/CD,kEAA0C;AAC1C,yCAAiC;AAGjC,iDAAuD;AAEvD;;;;;GAKG;AACH,SAAgB,UAAU,CACxB,IAAY,EACZ,WAAiC,YAAY,EAC7C,eAAwB;IAExB,IAAI,CAAC;QACH,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,MAAM,GAAkC,6BAA6B,CAAC,QAAQ,CAAC,CAAC;YACtF,6FAA6F;YAC7F,MAAM,KAAK,GAAG,IAAA,oCAAqB,GAAE,CAAC;YACtC,MAAM,OAAO,GAAG,GAAG,EAAE,CACnB,cAAY,CAAC,aAAa;YACxB,wFAAwF;YACxF,eAAe,CAAC,CAAC,CAAC,IAAA,gBAAI,EAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,EAC/E,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CACxC,CAAC;YACJ,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;YAC1E,MAAM,MAAM,GAAG,GAAG,EAAE,CAEhB,cAAY,CAAC,MAAM,CAAC,IAAI,EAAE;gBACxB,GAAG,MAAM;gBACT,MAAM;gBACN,0BAA0B,EAAE,MAAM;aACnC,CACF,CAAC,IAAI,EAAE,CAAC;YAEX,OAAO,KAAK,IAAI,OAAO,MAAM,KAAK,QAAQ;gBACxC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC;gBAChD,CAAC,CAAC,MAAM,EAAE,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,6BAA6B,CAAC,QAAuB;IAC5D,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,KAAK,CAAC;QACX,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,KAAK,CAAC;QACf,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,YAAY,CAAC;QAClB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

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;