@ng-doc/builder 22.1.0 → 22.2.0

package/generator/content/html-worker.js

@@ -387,6 +387,13 @@ var init_kebab_case = __esm({
   }
 });
 
+// libs/core/helpers/playground-target-slugs.ts
+var init_playground_target_slugs = __esm({
+  "libs/core/helpers/playground-target-slugs.ts"() {
+    "use strict";
+  }
+});
+
 // libs/core/helpers/stringify.ts
 var init_stringify = __esm({
   "libs/core/helpers/stringify.ts"() {
@@ -428,6 +435,7 @@ var init_helpers = __esm({
     init_is_same_object();
     init_kebab_case();
     init_object_keys();
+    init_playground_target_slugs();
     init_stringify();
     init_uid();
     init_unique();

package/generator/contracts.d.ts

@@ -178,17 +178,25 @@ export interface GeneratorConfiguration {
      */
     apiProtectedMembers?: false;
     /**
-     * The demo pages (`isolatedDemos`, `demoApplication`, `demoProviders`). Absent when none of them
-     * is set, so every other configuration keeps its digest, and so is every default field:
+     * The demo pages (`isolatedDemos`, `isolatedPlaygrounds`, `demoApplication`, `demoProviders`).
+     * Absent when none of them is set, so every other configuration keeps its digest, and so is every
+     * default field:
      * - `pages`: `all` builds a demo page for every demo, `none` for none; absent, only the guides
      *   with an isolated demo get them.
      * - `isolated`: `true` when `isolatedDemos` is: every `demo` action shows an iframe by default.
+     * - `playgroundPages`: `all` builds the playground pages of every playground
+     *   (`isolatedPlaygrounds`, or `demoApplication` set); absent, only the guides with an isolated playground get them, and
+     *   no guide does when `pages` is `none`.
+     * - `isolatedPlaygrounds`: `true` when `isolatedPlaygrounds` is: every playground shows its demos
+     *   in iframes by default.
      * - `path`: the URL path of the demo pages, absent for `demo-preview`.
      * - `providers`: the module that `demoProviders` imports.
      */
     demoApplication?: {
         pages?: 'all' | 'none';
         isolated?: true;
+        playgroundPages?: 'all';
+        isolatedPlaygrounds?: true;
         path?: string;
         providers?: FilePath;
     };
@@ -358,6 +366,11 @@ export interface PlaygroundDescriptor {
     /** Existing NgDocPlaygroundProperties shape with JSON-safe values, aliases and model inputs. */
     properties: Record<string, JsonValue>;
     content: Record<string, string>;
+    /**
+     * `true` when the playground's configuration in `ng-doc.page.ts` sets `isolated: true`, so its
+     * guide gets playground pages. Absent otherwise, so every other guide keeps its semantics.
+     */
+    isolated?: true;
 }
 export interface GuideSemantics {
     demos: Record<string, DemoAsset[]>;
@@ -647,6 +660,11 @@ export interface RouteRecord {
     demoModulePath?: string;
     /** The names of the guide's demo pages, in the order of `demos`, with `demoModulePath`. */
     demoNames?: string[];
+    /**
+     * The guide's playground pages relative to its demo route (`playground/<id>/<target>`), with
+     * `demoModulePath`. Only written for a guide that has them.
+     */
+    playgroundPages?: string[];
 }
 export interface ApiListRecord {
     apiEntryId: EntryId;

package/generator/kernel/flags.d.ts

@@ -29,7 +29,10 @@ export declare const INCREMENTAL_PROGRAM_FLAG = "NGDOC_INCREMENTAL_PROGRAM";
 export declare const SHAPE_CLOSURE_FLAG = "NGDOC_SHAPE_CLOSURE";
 export declare const ANGULAR_SHARED_PASS_FLAG = "NGDOC_ANGULAR_SHARED_PASS";
 export declare const ANGULAR_STRUCTURAL_PASS_FLAG = "NGDOC_ANGULAR_STRUCTURAL_PASS";
+export declare const ANGULAR_DESCRIPTION_PASS_FLAG = "NGDOC_ANGULAR_DESCRIPTION_PASS";
+export declare const VITE_CONTENT_UPDATE_FLAG = "NGDOC_VITE_CONTENT_UPDATE";
 export declare const VITE_BUILD_HANDOFF_FLAG = "NGDOC_VITE_BUILD_HANDOFF";
+export declare const VITE_MODULELESS_SETTLE_FLAG = "NGDOC_VITE_MODULELESS_SETTLE";
 export declare const TRACKED_PROGRAM_REUSE_FLAG = "NGDOC_TRACKED_PROGRAM_REUSE";
 export declare const FAST_START_FLAG = "NGDOC_FAST_START";
 export declare const PARALLEL_WRITES_FLAG = "NGDOC_PARALLEL_WRITES";

package/generator/outputs/index.d.ts

@@ -57,20 +57,36 @@ export declare class OutputAssemblerImpl implements OutputAssembler {
     aggregate(request: AggregateRequest): AggregateAssembly;
     private guide;
     /**
-     * Writes the guide's demo routes module (one route per demo, under the page's own providers)
-     * when the guide gets demo pages: with `pages: 'all'`, or by default when its content has a demo
-     * with `isolated: true`. Returns its path and the names of the demos that got a page, or
-     * undefined.
+     * Writes the guide's demo routes module when the guide gets demo or playground pages, and
+     * returns its path, the names of the demos that got a page and the playground pages (relative
+     * to the guide's demo route), or undefined.
+     *
+     * - Demo pages: with `pages: 'all'`, by default when its content has a demo with
+     *   `isolated: true`, and whenever the guide gets playground pages: the page then has a demo
+     *   route, and the runtime offers every demo of such a page its demo page.
+     * - Playground pages (`playground/<id>/<target>`, one per target of every playground of the
+     *   guide, under the page's providers and its generated playground classes): with
+     *   `playgroundPages: 'all'`, or by default when a `playground` action of its content or a
+     *   playground of its configuration has `isolated: true`.
      */
     private demoRoutes;
+    /**
+     * The playground pages of a guide, when it gets them (see `demoRoutes`): one per target of each
+     * playground, in the order of the guide's playgrounds and of `playgroundTargets`. A playground
+     * whose ID is no URL segment gets none, with a warning.
+     * @param request - The guide's assembly request.
+     * @param slots - The guide's content.
+     * @param diagnostics - Receives the warnings.
+     */
+    private playgroundRoutes;
     private apiEntry;
     private apiDeclaration;
     private apiLists;
     private addContentSource;
     /**
      * Writes `demo-app.ts`, the routes of the demo application (one lazy route per guide with demo
-     * pages, under its categories' providers) and its `demoProviders` import, when a guide has demo
-     * pages. Returns whether it did.
+     * or playground pages, under its categories' providers), every such page (`NG_DOC_DEMO_PAGES`)
+     * and its `demoProviders` import, when a guide has demo pages. Returns whether it did.
      */
     private demoApplication;
     private renderOutput;

package/generator/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/generator/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() {

package/generator/vite/angular/analog-provenance.json

@@ -858,7 +858,7 @@
     },
     {
       "id": "vite",
-      "owner": "peer vite@8.3.2"
+      "owner": "peer vite@8.3.3"
     }
   ],
   "encounteredStaticExternals": [

package/generator/vite/angular-composition.d.ts

@@ -10,6 +10,17 @@ import { type HostUpdateTicket, type InitialCompilationInventory } from './host-
  * @returns Whether only global style sheets depend on the file.
  */
 export declare function globalStyleSheet(context: Pick<HmrContext, 'file' | 'modules'>): boolean;
+/**
+ * Whether a hot update's hooks hand Vite anything to do once they return: a module to update, or
+ * (for an HTML file without modules) the page reload Vite sends itself. Only such a hot update
+ * has to wait for the newest publication before it returns; a module-less one settles once it is
+ * acknowledged (`HostUpdateCoordinator.settle`).
+ * @param file - The hot update's file.
+ * @param modules - The modules Vite updates after this hook: what the hook returned, or the
+ *   context's modules when it returned nothing.
+ * @returns Whether Vite updates or reloads anything for the hot update.
+ */
+export declare function handsViteModules(file: string, modules: readonly unknown[]): boolean;
 /**
  * The hooks NgDoc's patched Analog compiler exposes as `api.ngDocHost` (the
  * `generation-claimed-filesystem-*` changes): a claimed add or unlink event invalidates the
@@ -31,6 +42,15 @@ export interface AngularCompositionBridge {
     start(file: string, read: () => string | Promise<string>): HostUpdateTicket;
     /** Other TypeScript outputs to compile in this ready ticket's pass (see compilerCompanions). */
     companions?(ticket: HostUpdateTicket): string[];
+    /**
+     * Whether the generation of this committed source update still has a generated TypeScript
+     * update to compile (see HostUpdateCoordinator.generationPass).
+     */
+    generationPass?(ticket: HostUpdateTicket): boolean;
+    /** Whether `file` is a description module the generator watches. */
+    descriptionModule?(file: string): boolean;
+    /** Whether `file` is a generated output. */
+    generated?(file: string): boolean;
     /** A mark of the diagnostics recorded so far (see HostUpdateCoordinator.diagnosticMark). */
     diagnosticMark?(): number;
     /**
@@ -41,7 +61,11 @@ export interface AngularCompositionBridge {
     acknowledge(ticket: HostUpdateTicket, resourceWitness: boolean, compilerPass?: boolean, recoverBefore?: number): Promise<void>;
     diagnostic(ticket: HostUpdateTicket, error: Error): void;
     committed(ticket: HostUpdateTicket): Promise<void>;
-    settle(ticket: HostUpdateTicket): Promise<void>;
+    /**
+     * Settles the hot update (see HostUpdateCoordinator.settle). `modules` is false when its hooks
+     * hand Vite nothing to update ({@link handsViteModules}); omitted, it is true.
+     */
+    settle(ticket: HostUpdateTicket, modules?: boolean): Promise<void>;
     fail(error: Error): void;
 }
 export interface AngularComposition {

package/generator/vite/content-updates.d.ts

@@ -0,0 +1,62 @@
+import type { HtmlTagDescriptor, ViteDevServer, WebSocketClient } from 'vite';
+import type { AnnouncedChange } from './host-updates.js';
+/** The custom HMR event that carries a content update to the NgDoc client of a page. */
+export declare const CONTENT_UPDATE_EVENT = "ng-doc:content-update";
+/** The custom HMR event a page's NgDoc client sends once it listens for content updates. */
+export declare const CONTENT_CLIENT_EVENT = "ng-doc:content-client";
+/** The version of the content update messages; a client announces the version it reads. */
+export declare const CONTENT_UPDATE_VERSION = 1;
+/** A content update as the server sends it to a client. */
+export interface ContentUpdateMessage {
+    readonly version: typeof CONTENT_UPDATE_VERSION;
+    /** The URLs to import the changed content modules from, each with a fresh timestamp. */
+    readonly modules: readonly string[];
+    /** Whether the search index changed. */
+    readonly search: boolean;
+}
+/** What a content-only publication changed. */
+export interface ContentChanges {
+    /** The changed content modules (`*.content.mjs`), absolute, in path order. */
+    readonly modules: readonly string[];
+    /** Whether the search index changed. */
+    readonly search: boolean;
+}
+/**
+ * The page's NgDoc development client, a module script Vite serves with a hot context. It imports
+ * the changed content modules again and hands their payloads to the NgDoc runtime as a cancelable
+ * window event (`@ng-doc/app`'s `ɵNG_DOC_CONTENT_UPDATE_EVENT`, the same name). The runtime
+ * cancels it once it applied them; otherwise (no NgDoc runtime on the page, a payload it cannot
+ * read) and on any failure the client reloads the page, as it did before. Updates apply one at a
+ * time, in the order they arrive.
+ */
+export declare const CONTENT_UPDATE_CLIENT: string;
+/**
+ * The tag that adds the NgDoc development client to a page the development server serves.
+ * Vite turns an inline module script into a module of its own, with a hot context.
+ * @param html The page.
+ * @returns The tag, or none when the page carries the client or the switch is off.
+ */
+export declare function contentUpdateClientTags(html: string): HtmlTagDescriptor[];
+/** Whether content updates are on (`NGDOC_VITE_CONTENT_UPDATE`). */
+export declare function contentUpdatesEnabled(): boolean;
+/**
+ * What a reload announces, when it changes only content: every changed file is an existing
+ * content module (`*.content.mjs`) whose bytes changed, the search index or the keyword map
+ * (which no page reads). Anything else (a TypeScript module, a created or deleted file, another
+ * asset, the API lists) takes a full reload.
+ * @param changes The files that differ from the last announcement.
+ * @param assetDirectory The asset directory, relative to the output root.
+ * @returns The content changes, or `undefined` for a full reload.
+ */
+export declare function contentOnly(changes: readonly AnnouncedChange[] | undefined, assetDirectory: string): ContentChanges | undefined;
+/**
+ * Sends a content update. Each client that announced its NgDoc client gets the changed content
+ * modules it may have loaded (those in the client module graph: a module nobody imported loads
+ * afresh anyway); every other client reloads, as before. Without any client the reload is sent
+ * as Vite buffers it, so a page that connects later reloads.
+ * @param server The development server.
+ * @param clients The clients that announced the NgDoc client.
+ * @param changes The content changes.
+ * @param timestamp A timestamp no earlier update used, so the browser imports new modules.
+ */
+export declare function sendContentUpdate(server: ViteDevServer, clients: WeakSet<WebSocketClient>, changes: ContentChanges, timestamp: number): void;

package/generator/vite/host-updates.d.ts

@@ -4,6 +4,24 @@ export interface PhysicalState {
     digest?: string;
     version: string;
 }
+export interface ManifestFile {
+    digest: string;
+    role: OutputManifest['files'][number]['role'];
+}
+/**
+ * One generated file whose bytes or role differ between the outputs the browser was last told
+ * about and the outputs a reload announces now.
+ */
+export interface AnnouncedChange {
+    /** Relative to the output root, with forward slashes, as the manifest lists it. */
+    readonly path: string;
+    /** The absolute path. */
+    readonly file: string;
+    /** Absent for a created file. */
+    readonly before?: Readonly<ManifestFile>;
+    /** Absent for a deleted file. */
+    readonly after?: Readonly<ManifestFile>;
+}
 export interface HostUpdateTicket {
     readonly ready: Promise<void>;
     readonly token: object;
@@ -57,6 +75,13 @@ export declare function observePhysicalVersion(file: string): string | undefined
  * input is re-observed (`HostUpdateRecovery.rescan`), so the newest edit is published even if
  * its event was lost or its generation failed under the load. A replayed report is matched like
  * any other: one that arrives twice is a repeat, so an edit still reloads once.
+ *
+ * Churn: under a sustained stream of edits a new generation starts before the previous one is
+ * published, again and again. A host update that waits for the current publication follows each
+ * newer generation, so it settles only once the stream stops. That is required of one whose hook
+ * hands Vite modules: Vite updates them when the hook returns, which must not happen before the
+ * newest publication. A module-less one hands Vite nothing, so it settles once it is acknowledged
+ * (see {@link settle}; `NGDOC_VITE_MODULELESS_SETTLE=0` makes it wait as well).
  */
 export declare class HostUpdateCoordinator {
     private readonly notify;
@@ -86,7 +111,21 @@ export declare class HostUpdateCoordinator {
     private burst?;
     /** The start and the hot updates of the current burst-detection window. */
     private window;
-    constructor(notify: () => void, fail: (error: Error) => void, recovery?: HostUpdateRecovery | undefined);
+    /** Whether a module-less host update settles without waiting for the current publication. */
+    private readonly modulelessSettle;
+    /**
+     * Whether the pending reload must reload the page whatever its outputs: an Angular source was
+     * compiled for it, or it repairs an earlier failure (the browser shows the error overlay).
+     */
+    private pendingFull;
+    /**
+     * @param notify Announces the newest settled publication to the browser. `changes` lists the
+     *   generated files that differ from the last announcement, when nothing else asks for a full
+     *   reload; without it, or when the host cannot apply the changes in place, the page reloads.
+     * @param fail Reports a host error.
+     * @param recovery What the host does after a burst.
+     */
+    constructor(notify: (changes?: readonly AnnouncedChange[]) => void, fail: (error: Error) => void, recovery?: HostUpdateRecovery | undefined);
     seed(outputRoot: string, manifest: OutputManifest): void;
     initialCompilationInventory(): InitialCompilationInventory;
     started(generation: number, changes: FileChange[]): void;
@@ -113,7 +152,8 @@ export declare class HostUpdateCoordinator {
      * generated output that a generation claimed. Its host hooks settle only once the newest
      * generation is published and every host obligation is drained, and by then `flush()` has sent
      * that generation's reload (or its outputs equal the last announced ones). A native reload for
-     * the same output would be a second one.
+     * the same output would be a second one. A module-less one settles earlier (see
+     * {@link settle}), but Vite has nothing of it to reload either way.
      */
     announces(read: object): boolean;
     /**
@@ -124,6 +164,16 @@ export declare class HostUpdateCoordinator {
      * `ticket.ready`, which binds the generation.
      */
     compilerCompanions(ticket: HostUpdateTicket): string[];
+    /**
+     * Whether the generation that claimed this TypeScript source update committed and still has a
+     * generated TypeScript module update whose Angular pass has not completed: that pass is still to
+     * come, and the source can join it (`ngDocCompanionFiles`) instead of taking a pass of its own.
+     * False for anything else: a generated output, a source no generation claimed, a generation
+     * that failed, was cancelled or rewrote no TypeScript module, or whose passes all completed.
+     * Call it after `committed(ticket)`, which waits for the generation's result.
+     * @param ticket The source's hot update ticket.
+     */
+    generationPass(ticket: HostUpdateTicket): boolean;
     /**
      * Whether `file` is a generated output: a path below the output root of the published
      * generation. Nothing is generated before the first publication or after disposal.
@@ -136,11 +186,30 @@ export declare class HostUpdateCoordinator {
     /** The diagnostics recorded so far; a pass that starts now can repair exactly these. */
     diagnosticMark(): number;
     private recoverDiagnostics;
-    /** Waits for the current accepted publication and all peer host acknowledgments. */
-    settle(ticket: HostUpdateTicket): Promise<void>;
+    /**
+     * Waits for the current accepted publication and all peer host acknowledgments.
+     *
+     * A module-less hot update does not wait: once its hooks return, Vite has no module to update
+     * and sends nothing, and its acknowledgment has already settled what it obliged (the reload,
+     * sent by `flush()` once every obligation is settled, is this coordinator's own). Waiting made
+     * it follow every generation that started meanwhile, so under sustained churn it settled only
+     * when the churn stopped, and each wait for the host obligations to drain could time out
+     * (`NGDOC_VITE_HOST_TIMEOUT`) while every single obligation was completed in time. Nothing
+     * else changes: obligations, the reload and what is published are the same, so the switch off
+     * (`NGDOC_VITE_MODULELESS_SETTLE=0`) only makes it wait as before.
+     * @param ticket The hot update's ticket, after its acknowledgment.
+     * @param modules Whether its hooks hand Vite any module to update (or a page reload Vite sends
+     *   itself, for an HTML file without modules). Only the caller, which sees Vite's context, knows.
+     */
+    settle(ticket: HostUpdateTicket, modules?: boolean): Promise<void>;
     /** Waits for the candidate's atomic commit boundary, including a failure that kept last-good. */
     committed(ticket: HostUpdateTicket): Promise<void>;
-    complete(ticket: HostUpdateTicket): Promise<void>;
+    /**
+     * Acknowledges a hot update that takes no compiler pass, then settles it.
+     * @param ticket The hot update's ticket.
+     * @param modules See {@link settle}.
+     */
+    complete(ticket: HostUpdateTicket, modules?: boolean): Promise<void>;
     published(result: Extract<BuildResult, {
         status: 'success';
     }>, recovered: boolean): void;
@@ -179,9 +248,20 @@ export declare class HostUpdateCoordinator {
     private hasOutputBlockers;
     private flush;
     private queueCurrentReload;
+    /**
+     * Settles a module-less hot update without waiting (see {@link settle}).
+     * @param token The acknowledged hot update.
+     */
+    private settleModuleless;
     private awaitCurrentPublication;
     private awaitWithoutDiagnostic;
     private delta;
+    /**
+     * The generated files that differ between two manifests, in path order.
+     * @param previousManifest The outputs the browser was last told about.
+     * @param nextManifest The outputs announced now.
+     */
+    private changes;
     private prune;
     private withTimeout;
     /** Counts a hot update towards a burst of file events (see the class description). */