@ng-doc/builder 22.0.0-beta.2 → 22.1.0

package/schematics/vite-setup/index.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANGULAR_BUILD_TARGET = exports.ANGULAR_SERVE_BUILDERS = exports.ANGULAR_BUILD_BUILDERS = void 0;
+exports.viteSetup = viteSetup;
+const schematics_1 = require("@angular-devkit/schematics");
+const tasks_1 = require("@angular-devkit/schematics/tasks");
+const analyze_1 = require("../migrate-to-vite/analyze");
+const dependencies_1 = require("../migrate-to-vite/setup/dependencies");
+const source_1 = require("../migrate-to-vite/setup/source");
+const targets_1 = require("../migrate-to-vite/setup/targets");
+const vite_config_1 = require("../migrate-to-vite/setup/vite-config");
+const workspace_1 = require("../migrate-to-vite/setup/workspace");
+/**
+ * The builders whose options the Vite setup reads: Angular's application builder, and Nx's
+ * executor that runs it with the same options and a few of its own, which `analyzeProject`
+ * reports like any other option.
+ */
+exports.ANGULAR_BUILD_BUILDERS = [
+    '@angular/build:application',
+    '@angular-devkit/build-angular:application',
+    '@nx/angular:application',
+];
+/** The development servers that the Vite development server replaces: Angular's and Nx's. */
+exports.ANGULAR_SERVE_BUILDERS = [
+    '@angular/build:dev-server',
+    '@angular-devkit/build-angular:dev-server',
+    '@nx/angular:dev-server',
+];
+/**
+ * The name the Angular build target is kept under. Angular builders such as `unit-test` and
+ * `extract-i18n` read the options of a build target, which the Vite target no longer has.
+ */
+exports.ANGULAR_BUILD_TARGET = 'build-angular';
+const CACHE_IGNORE = '/.cache/ng-doc';
+/**
+ * Findings as Markdown list items, each once: analyze reports some once per configuration.
+ * @param findings - The findings to list.
+ */
+function list(findings) {
+    return [...new Set(findings.map((finding) => `- \`${finding.subject}\`: ${finding.message}`))];
+}
+/**
+ * Sets up the Vite engine for a project that builds with Angular's application builder (or Nx's
+ * executor that runs it): the `vite.config.mjs` of the project, the `vite-application` and
+ * `vite-dev-server` targets, the server entry, the dependencies and `.gitignore`. It reads the build target the same way
+ * `migrate-to-vite` reads a legacy one, and refuses what that schematic refuses. `ng add` runs it
+ * after the NgDoc styles, assets and providers are in place.
+ * @param options - The schematic options.
+ */
+function viteSetup(options) {
+    return (tree, context) => {
+        let projects;
+        try {
+            projects = (0, workspace_1.readWorkspaceProjects)(tree);
+        }
+        catch (error) {
+            throw new schematics_1.SchematicsException(`[NGDOC_VITE_SETUP_WORKSPACE] The workspace file could not be read (${error instanceof Error ? error.message : error}). Fix it, or run \`ng add @ng-doc/add --engine legacy\`.`);
+        }
+        const project = projects.find((item) => item.name === options.project);
+        if (!project) {
+            throw new schematics_1.SchematicsException(`[NGDOC_VITE_SETUP_PROJECT] Project "${options.project}" does not exist.`);
+        }
+        const build = project.targets['build'];
+        const builder = (0, workspace_1.targetBuilder)(build);
+        if (builder === targets_1.VITE_APPLICATION_BUILDER) {
+            context.logger.info(`Project "${project.name}" already builds with the Vite engine (${targets_1.VITE_APPLICATION_BUILDER}); nothing to change.`);
+            return;
+        }
+        const blocked = (findings) => {
+            throw new schematics_1.SchematicsException([
+                `[NGDOC_VITE_SETUP_BLOCKED] Project "${project.name}" was not set up with the Vite engine, and no file of the project was changed:`,
+                ...list(findings),
+                'Resolve these and run `ng add @ng-doc/add` again, or run `ng add @ng-doc/add --engine legacy` to use the legacy builders.',
+            ].join('\n'));
+        };
+        if (!build || !exports.ANGULAR_BUILD_BUILDERS.includes(builder ?? '')) {
+            blocked([
+                {
+                    level: 'blocking',
+                    subject: 'build',
+                    message: build
+                        ? `uses \`${builder ?? 'no builder'}\`, not Angular's application builder (${exports.ANGULAR_BUILD_BUILDERS.map((name) => `\`${name}\``).join(', ')}), whose options the Vite engine reads.`
+                        : 'does not exist.',
+                },
+            ]);
+        }
+        const serveTarget = project.targets['serve'];
+        const serveName = exports.ANGULAR_SERVE_BUILDERS.includes((0, workspace_1.targetBuilder)(serveTarget) ?? '')
+            ? 'serve'
+            : undefined;
+        const plan = (0, analyze_1.analyzeProject)(tree, project, 'build', serveName, { keptBuildName: exports.ANGULAR_BUILD_TARGET }, (0, workspace_1.builderKey)(build));
+        const configFile = plan.setup.configFile;
+        if (tree.exists(configFile)) {
+            plan.findings.push({
+                level: 'blocking',
+                subject: configFile,
+                message: 'already exists. Move it away first.',
+            });
+        }
+        if (project.targets[exports.ANGULAR_BUILD_TARGET]) {
+            plan.findings.push({
+                level: 'blocking',
+                subject: exports.ANGULAR_BUILD_TARGET,
+                message: 'already exists, so the Angular build target cannot be kept under that name.',
+            });
+        }
+        if (serveTarget && !serveName) {
+            plan.findings.push({
+                level: 'manual',
+                subject: 'serve',
+                message: `uses \`${(0, workspace_1.targetBuilder)(serveTarget) ?? 'no builder'}\` and was left as it is. Use \`${targets_1.VITE_DEV_SERVER_BUILDER}\` with \`"configFile": "${configFile}"\` to serve the site.`,
+            });
+        }
+        const blocking = plan.findings.filter((finding) => finding.level === 'blocking');
+        if (blocking.length)
+            blocked(blocking);
+        // The Angular target keeps its options for the builders that read them; the Vite targets take
+        // the names `ng build` and `ng serve` run.
+        (0, workspace_1.writeTarget)(tree, project, exports.ANGULAR_BUILD_TARGET, plan.build.legacy, 'build');
+        (0, workspace_1.writeTarget)(tree, project, 'build', plan.build.next);
+        if (plan.serve)
+            (0, workspace_1.writeTarget)(tree, project, 'serve', plan.serve.next);
+        // The serve target is replaced by the Vite development server, which has no build target: an
+        // explicit `buildTarget` in its options must not turn it back into an Angular target.
+        const retargets = plan.retargets.filter((retarget) => retarget.target !== serveName);
+        for (const retarget of retargets) {
+            const target = project.targets[retarget.target];
+            if (target) {
+                (0, workspace_1.writeTarget)(tree, project, retarget.target, (0, workspace_1.withBuildTarget)(target, retarget.after));
+            }
+        }
+        const changes = [
+            `- \`build\` runs \`${targets_1.VITE_APPLICATION_BUILDER}\`${plan.serve ? ` and \`serve\` runs \`${targets_1.VITE_DEV_SERVER_BUILDER}\`` : ''}, with \`${configFile}\`.`,
+            `- The Angular build options stay in \`${exports.ANGULAR_BUILD_TARGET}\`${retargets.length
+                ? `, which ${retargets.map((retarget) => `\`${retarget.target}\``).join(', ')} now read${retargets.length === 1 ? 's' : ''}`
+                : ''}.`,
+        ];
+        tree.create(configFile, (0, vite_config_1.renderNgDocViteConfig)(plan.setup, [
+            `The Vite configuration of the NgDoc site "${project.name}", generated by \`ng add @ng-doc/add\``,
+            'from its build target. The vite-application and vite-dev-server targets run it. Edit it freely.',
+        ]));
+        changes.push(`- Created \`${configFile}\`.`);
+        // The server entry waits for NgDoc content before a page is prerendered.
+        const serverEntry = plan.setup.server;
+        if (serverEntry && tree.exists(serverEntry)) {
+            const text = tree.readText(serverEntry);
+            const wrapped = (0, source_1.wrapServerEntry)(serverEntry, text);
+            if (wrapped === undefined) {
+                plan.findings.push({
+                    level: 'manual',
+                    subject: serverEntry,
+                    message: "Wrap the default export with `withNgDocContentReady` from '@ng-doc/app/helpers', so prerendering waits for the page content.",
+                });
+            }
+            else if (wrapped !== text) {
+                tree.overwrite(serverEntry, wrapped);
+                changes.push(`- Wrapped the default export of \`${serverEntry}\` with \`withNgDocContentReady\`.`);
+            }
+        }
+        if (!tree.exists('.gitignore')) {
+            plan.findings.push({
+                level: 'manual',
+                subject: '.gitignore',
+                message: `does not exist; keep \`${CACHE_IGNORE}\` out of version control.`,
+            });
+        }
+        else if ((0, dependencies_1.addGitIgnoreLine)(tree, CACHE_IGNORE)) {
+            changes.push(`- Added \`${CACHE_IGNORE}\` to \`.gitignore\`.`);
+        }
+        // A generated folder the engine did not write stops the first build (OUTPUT_UNOWNED_COLLISION).
+        const output = tree.getDir(plan.setup.outputRoot);
+        if (output.subfiles.length || output.subdirs.length) {
+            plan.findings.push({
+                level: 'manual',
+                subject: plan.setup.outputRoot,
+                message: 'already exists. Delete it before the first build: the Vite engine refuses files it did not write.',
+            });
+        }
+        const { added, mismatches } = (0, dependencies_1.addNgDocViteDependencies)(tree);
+        for (const [name, version] of Object.entries(added)) {
+            changes.push(`- Added \`${name}@${version}\` to \`devDependencies\`.`);
+        }
+        for (const mismatch of mismatches) {
+            // A Vite the engine refuses to start with is a warning, not a note among the changes.
+            if ((0, dependencies_1.isEnforced)(mismatch.name))
+                context.logger.warn((0, dependencies_1.dependencyMismatchText)(mismatch));
+            else
+                changes.push(`- ${(0, dependencies_1.dependencyMismatchText)(mismatch)}`);
+        }
+        if (Object.keys(added).length && !options.skipInstall) {
+            context.addTask(new tasks_1.NodePackageInstallTask());
+        }
+        const manual = plan.findings.filter((finding) => finding.level === 'manual');
+        // Options without any effect under Vite; `assets`, for example, is only partly dropped.
+        const used = new Set(plan.findings
+            .filter((finding) => finding.level !== 'dropped')
+            .map((finding) => finding.subject));
+        const dropped = plan.findings
+            .filter((finding) => finding.level === 'dropped' &&
+            finding.subject.startsWith('build.') &&
+            !used.has(finding.subject))
+            .map((finding) => `\`${finding.subject}\``);
+        context.logger.info([`Project "${project.name}" builds with the NgDoc Vite engine:`, ...changes].join('\n'));
+        if (dropped.length) {
+            context.logger.info(`Build options the Vite engine does not use: ${[...new Set(dropped)].join(', ')}.`);
+        }
+        if (manual.length) {
+            context.logger.warn(['Needs a manual change:', ...list(manual)].join('\n'));
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/schematics/vite-setup/index.js.map

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

package/schematics/vite-setup/schema.d.ts

@@ -0,0 +1,7 @@
+/** The options of the `vite-setup` schematic, which `ng add` runs for the Vite engine. */
+export interface NgDocViteSetupSchema {
+    /** The project to set up. */
+    project: string;
+    /** Do not install the added dependencies. */
+    skipInstall?: boolean;
+}

package/schematics/vite-setup/schema.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=schema.js.map

package/schematics/vite-setup/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../../../libs/builder/schematics/vite-setup/schema.ts"],"names":[],"mappings":""}

package/schematics/vite-setup/schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "NgDocViteSetup",
+  "title": "Set up the NgDoc Vite engine for a new project",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The project to set up. Its build target must use Angular's application builder or Nx's @nx/angular:application executor."
+    },
+    "skipInstall": {
+      "type": "boolean",
+      "default": false,
+      "description": "Do not install the added dependencies."
+    }
+  },
+  "required": ["project"],
+  "additionalProperties": false
+}

package/scripts/restore-theme.js

@@ -1,6 +1,13 @@
+// Restores the reader's theme before the application starts. An empty stored id is the light
+// theme: it removes a `data-theme` that index.html sets by default.
 const themeId = localStorage.getItem('ng-doc-theme-id');
 
-if (themeId) {
+if (themeId !== null) {
   const documentElement = document.documentElement;
-  documentElement.setAttribute('data-theme', themeId);
+
+  if (themeId) {
+    documentElement.setAttribute('data-theme', themeId);
+  } else {
+    documentElement.removeAttribute('data-theme');
+  }
 }

package/templates/api/class-declaration.html.nunj

@@ -7,10 +7,12 @@
 {% import "helpers/modifier.html.nunj" as modifierMacro %}
 
 {% block overview %}
+    {#- The new engine sets `hideProtectedMembers` for `api.protectedMembers: false`; the legacy engine never does. #}
+    {%- set memberScopes = ["public"] if hideProtectedMembers else ["public", "protected"] -%}
     {%- set constructors = declaration.getConstructors() | filterByScope("public") | excludeByJsDocTags('internal') -%}
-    {%- set allProperties = declaration | getClassProperties | excludeByJsDocTags('internal') | filterByScope(["public", "protected"]) | filterUselessMembers | sortByNodesName -%}
-    {%- set allMethods = declaration | getClassMethods | excludeByJsDocTags('internal') | filterByScope(["public", "protected"]) | filterUselessMembers | sortByNodesName -%}
-    {%- set allAccessors = declaration | getClassAccessors | excludeByJsDocTags('internal') | filterByScope(["public", "protected"]) | filterUselessMembers | sortByNodesName -%}
+    {%- set allProperties = declaration | getClassProperties | excludeByJsDocTags('internal') | filterByScope(memberScopes) | filterUselessMembers | sortByNodesName -%}
+    {%- set allMethods = declaration | getClassMethods | excludeByJsDocTags('internal') | filterByScope(memberScopes) | filterUselessMembers | sortByNodesName -%}
+    {%- set allAccessors = declaration | getClassAccessors | excludeByJsDocTags('internal') | filterByScope(memberScopes) | filterUselessMembers | sortByNodesName -%}
 
     {%- set staticProperties = allProperties | filterByStatic(true) -%}
     {%- set staticAccessors = allAccessors | filterByStatic(true) -%}

package/templates/context.ts.nunj

@@ -38,6 +38,9 @@ export function provideNgDocContext(): Provider[] {
           {%- endif %}
           {%- endfor %}
       ],
+      {%- if apiLists is defined %}
+      apiLists: {{ apiLists | dump }},
+      {%- endif %}
     },
   }, {
     provide: NG_DOC_ROUTE_PREFIX,

package/templates/demo-app.ts.nunj

@@ -0,0 +1,37 @@
+// @ts-nocheck
+import {Routes} from '@angular/router';
+{%- for category in categories %}
+import {{ category[0] }} from '{{ category[1] }}';
+{%- endfor %}
+
+// The URL path of the demo pages, which the Vite host serves the demo application's page under.
+export const NG_DOC_DEMO_PATH = '{{ demoPath }}';
+
+// Every demo page, which a build without prerendering writes as a copy of the demo application's
+// page, so that static hosts serve it without a fallback.
+export const NG_DOC_DEMO_PAGES: string[] = {{ demoPages | dump }};
+
+// The routes of the demo application: one lazy route per guide with demo pages, under the
+// providers of its categories, as on the documentation pages.
+export const NG_DOC_DEMO_ROUTES: Routes = [
+  {%- for page in pages %}
+  {
+    path: '{{ page.path | replace("\\", "\\\\") | replace("'", "\\'") | replace("\n", "\\n") }}',
+    {%- if page.categories.length %}
+    providers: [
+      {%- for id in page.categories %}
+      ...({{ id }}.providers ?? []),
+      {%- endfor %}
+    ],
+    {%- endif %}
+    loadChildren: () => import('{{ page.importPath }}'),
+  },
+  {%- endfor %}
+];
+
+// The module of `demoProviders`, which only the demo application imports.
+{%- if providersImport %}
+export const NG_DOC_DEMO_PROVIDERS = () => import('{{ providersImport }}');
+{%- else %}
+export const NG_DOC_DEMO_PROVIDERS = undefined;
+{%- endif %}

package/templates/demo-routes.ts.nunj

@@ -0,0 +1,23 @@
+// @ts-nocheck
+import {Routes} from '@angular/router';
+import {NgDocDemoHostComponent} from '@ng-doc/app/demo-app';
+import entry from '{{ entryImport }}';
+
+// The demo pages of one guide: one route per demo, under the page's providers, as the demos have
+// them on the page.
+const routes: Routes = [{
+  path: '',
+  providers: [...(entry.providers ?? [])],
+  children: [
+    {%- for demo in demos %}
+    {
+      path: '{{ demo.name }}',
+      component: NgDocDemoHostComponent,
+      title: `{{ demo.title | toTemplateString }}`,
+      data: {ngDocDemo: entry.demos?.['{{ demo.name }}']},
+    },
+    {%- endfor %}
+  ],
+}];
+
+export default routes;

package/templates/helpers/badge.html.nunj

@@ -1,4 +1,4 @@
 {%- macro render(content, attributeOverride) -%}
     <span class="ng-doc-badge" indexable="false"
-          data-content="{{ attributeOverride if attributeOverride else content }}">{{ content[0] }}</span>
+          data-content="{{ attributeOverride if attributeOverride else content }}">{{ content }}</span>
 {%- endmacro -%}

package/templates/helpers/status.html.nunj

@@ -1,32 +1,28 @@
 {% macro render(member) %}
     {% set deprecated = member | getJsDocTag('deprecated') %}
     {% if deprecated %}
-        <ng-doc-blockquote type="warning" icon="activity">
-            <b>Deprecated</b>
+        <ng-doc-blockquote type="warning" icon="activity" label="Deprecated">
             {{ deprecated }}
         </ng-doc-blockquote>
     {% endif %}
 
     {% set experimental = member | getJsDocTag('experimental') %}
     {% if experimental %}
-        <ng-doc-blockquote type="alert" icon="activity">
-            <b>Experimental</b>
+        <ng-doc-blockquote type="alert" icon="activity" label="Experimental">
             {{ experimental }}
         </ng-doc-blockquote>
     {% endif %}
 
     {% set alpha = member | getJsDocTag('alpha') %}
     {% if alpha %}
-        <ng-doc-blockquote type="alert" icon="activity">
-            <b>Alpha</b>
+        <ng-doc-blockquote type="alert" icon="activity" label="Alpha">
             {{ alpha }}
         </ng-doc-blockquote>
     {% endif %}
 
     {% set beta = member | getJsDocTag('beta') %}
     {% if beta %}
-        <ng-doc-blockquote type="warning" icon="activity">
-            <b>Beta</b>
+        <ng-doc-blockquote type="warning" icon="activity" label="Beta">
             {{ beta }}
         </ng-doc-blockquote>
     {% endif %}

package/templates/index.ts.nunj

@@ -1,2 +1,7 @@
 export * from './context';
 export * from './routes';
+{% if demoApplication -%}
+// Keeps the demo application's modules, the demo routes and the module of `demoProviders`, in the
+// application's Angular compilation, which compiles them: only the demo application imports them.
+import type {} from './demo-app';
+{% endif -%}

package/templates/page-wrapper.ts.nunj

@@ -3,27 +3,50 @@ import {ChangeDetectionStrategy, Component} from '@angular/core';
 import {Routes} from '@angular/router';
 import {NgDocPageWrapperComponent} from '@ng-doc/app';
 import {NgDocPageType} from '@ng-doc/core';
+{%- if headerContentSourceImport %}
+import {ɵwithNgDocContent} from '@ng-doc/app';
+import headerContentSource from '{{ headerContentSourceImport }}';
+{%- endif %}
 
+{%- if headerContentSourceImport %}
+const headerContent: string = '';
+{%- else %}
 const headerContent: string = `{{ headerContent | toTemplateString }}`
+{%- endif %}
 
 @Component({
   selector: 'ng-doc-page-wrapper-{{ id }}',
-  template: `<ng-doc-page-wrapper [routes]="routes" [headerContent]="headerContent" [hasBreadcrumb]="hasBreadcrumb" [pageType]="pageType"></ng-doc-page-wrapper>`,
+  template: `<ng-doc-page-wrapper [routes]="routes" [headerContent]="headerContent"{%- if headerContentSourceImport %} [headerContentSource]="headerContentSource"{%- endif %} [hasBreadcrumb]="hasBreadcrumb" [pageType]="pageType"></ng-doc-page-wrapper>`,
   imports: [NgDocPageWrapperComponent],
   changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class PageWrapperComponent {
     routes = routes[0].children!;
     headerContent = headerContent;
+    {%- if headerContentSourceImport %}
+    headerContentSource = headerContentSource;
+    {%- endif %}
     pageType: NgDocPageType = '{{ pageType }}';
     hasBreadcrumb = {{ hasBreadcrumb }};
 }
+{%- if headerContentSourceImport %}
+
+
+// The router shows the page only once its header has loaded, so the previous page stays on
+// screen instead of an empty page.
+const routes: Routes = [ɵwithNgDocContent({
+{%- else %}
 
 
 const routes: Routes = [{
+{%- endif %}
   path: '',
   component: PageWrapperComponent,
-  title: `{{ metadata.title | toTemplateString }}`,
+  {#- No title: the route inherits the page's title from the route that loads it, and a second
+      copy of it would repeat it in a title strategy that joins the titles of the route. #}
+  data: {
+    ngDocPageType: '{{ pageType }}',
+  },
   children: [
     {%- for importPath, entry in entries  %}
     {
@@ -32,10 +55,15 @@ const routes: Routes = [{
       title: `{{ entry.title | toTemplateString }}`,
       data: {
         icon: '{{ entry.entry.icon }}',
+        ngDocTitle: 'tab',
       }
     },
     {%- endfor %}
   ]
+{%- if headerContentSourceImport %}
+}, headerContentSource)]
+{%- else %}
 }]
+{%- endif %}
 
 export default routes;

package/templates/page.ts.nunj

@@ -12,8 +12,16 @@ import {PLAYGROUND_COMPONENTS, PLAYGROUND_PROVIDERS} from '{{ metadata.outDir |
 {%- if demoAssetsPath %}
 import demoAssets from '{{ metadata.outDir | createImportPath(demoAssetsPath) }}';
 {%- endif %}
+{%- if contentSourceImport %}
+import {ɵwithNgDocContent} from '@ng-doc/app';
+import pageContentSource from '{{ contentSourceImport }}';
+{%- endif %}
 
+{%- if contentSourceImport %}
+const pageContent: string = '';
+{%- else %}
 const pageContent: string = `{{ content | toTemplateString }}`
+{%- endif %}
 
 @Component({
   selector: 'ng-doc-page-{{ id }}',
@@ -41,6 +49,9 @@ const pageContent: string = `{{ content | toTemplateString }}`
 export class PageComponent extends NgDocRootPage {
   readonly pageType: NgDocPageType = '{{ pageType }}';
   readonly pageContent: string = pageContent;
+    {%- if contentSourceImport %}
+  readonly pageContentSource = pageContentSource;
+    {%- endif %}
     {%- if editSourceFileUrl %}
   readonly editSourceFileUrl: string = '{{ editSourceFileUrl }}';
     {%- endif %}
@@ -53,11 +64,32 @@ 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. #}
+    {%- if demoRoute %}
+  readonly demoRoute: string = '{{ demoRoute | replace("\\", "\\\\") | replace("'", "\\'") | replace("\n", "\\n") }}';
+      {%- if isolatedDemos %}
+  readonly isolatedDemos: boolean = true;
+      {%- endif %}
+    {%- endif %}
 
   constructor() {
     super();
   }
 }
+{#- The route has no title of its own: it inherits the title of its tab route, so a page's own
+    `route.title` is the only title here and wins over the generated one. #}
+{%- if contentSourceImport %}
+
+// The router shows the page only once its content has loaded, so the previous page stays on
+// screen instead of an empty page.
+const routes: Routes = [ɵwithNgDocContent({
+    {%- if entryPath %}
+  ...(isRoute(entry.route) ? entry.route : {}),
+    {%- endif %}
+  path: '',
+  component: PageComponent,
+}, pageContentSource)]
+{%- else %}
 
 const routes: Routes = [{
     {%- if entryPath %}
@@ -65,8 +97,8 @@ const routes: Routes = [{
     {%- endif %}
   path: '',
   component: PageComponent,
-  title: `{{ metadata.title | toTemplateString }}`,
 }]
+{%- endif %}
 
 export default routes;
 

package/templates/parts/page-tags.html.nunj

@@ -5,6 +5,6 @@
 
     {{ tagMacro.render(scope.name, "ng-doc-scope") }}
     <span class="ng-doc-inline-delimiter" indexable="false">/</span>
-    {{ tagMacro.render(declarationType) if declarationType }}
+    {{ tagMacro.render("Type alias" if declarationType == "TypeAlias" else declarationType, declarationType) if declarationType }}
 </div>
 

package/templates/playgrounds.ts.nunj

@@ -1,5 +1,5 @@
 // @ts-nocheck
-import {ChangeDetectionStrategy, Component, Type, ViewChild, ViewContainerRef} from '@angular/core';
+import {ChangeDetectionStrategy, Component, viewChild, ViewContainerRef} from '@angular/core';
 import {NgDocBasePlayground, providePlaygroundDemo} from '@ng-doc/app';
 // noinspection ES6UnusedImports
 import pageEntity from '{{ entryImportPath }}';
@@ -18,6 +18,9 @@ import {CommonModule} from '@angular/common';
 
 @Component({
     selector: 'ng-doc-playground-{{ index }}',
+    {#- Two pages with the same playground would otherwise compile to identical components, which
+        Angular gives the same component ID (NG0912). The page route keeps them apart. #}
+    host: {'data-ng-doc-playground-page': '{{ pageRoute }}'},
     template: `
 		{{ template }}
 	`,
@@ -35,17 +38,13 @@ import {CommonModule} from '@angular/common';
 export class {{ comp.name }} extends NgDocBasePlayground {
     static readonly selector: string = '{{ comp.selector }}';
 
-    @ViewChild(pageEntity.playgrounds['{{ id }}'].target, {static: true})
-    readonly playground: Type<any>;
+    readonly target = pageEntity.playgrounds['{{ id }}'].target;
 
-    @ViewChild(pageEntity.playgrounds['{{ id }}'].target, {static: true, read: ViewContainerRef})
-    readonly viewContainerRef: ViewContainerRef;
+    readonly playground = viewChild(pageEntity.playgrounds['{{ id }}'].target);
 
-    readonly configData: any = pageEntity.playgrounds['{{ id }}'].data;
+    readonly viewContainerRef = viewChild(pageEntity.playgrounds['{{ id }}'].target, {read: ViewContainerRef});
 
-    constructor() {
-        super(pageEntity.playgrounds['{{ id }}'].target);
-    }
+    readonly configData: any = pageEntity.playgrounds['{{ id }}'].data;
 }
 {%- set index = index + 1 -%}
 {%- endfor %}

package/templates/routes.ts.nunj

@@ -1,5 +1,7 @@
 // @ts-nocheck
 import {Routes} from '@angular/router';
+{#- Route strings are single-quoted string literals: backslashes, quotes and line breaks are
+    escaped, so a route or segment with one cannot end the literal. -#}
 {%- macro categoryImport(entry) -%}
 {%- if entry.item.isCategory %}
 import {{ entry.item.id }} from '{{ curDir | createImportPath(entry.item.path) }}';
@@ -16,8 +18,15 @@ import {{ entry.item.id }} from '{{ curDir | createImportPath(entry.item.path) }
 export const NG_DOC_ROUTING: Routes = [
 	{%- macro route(entry) %}
 	{
-		path: '{{ entry.item.route }}',
+		path: '{{ entry.item.route | replace("\\", "\\\\") | replace("'", "\\'") | replace("\n", "\\n") }}',
 		title: `{{ entry.item.title | toTemplateString }}`,
+    {#- `ngDocTitle` names what the title belongs to, so a title strategy can compose the titles of
+        the route without repeating one (`provideNgDocTitle`). #}
+    data: {ngDocTitle: '{{ 'category' if entry.item.isCategory else 'page' }}'
+    {%- if entry.item.apiListSegment is defined -%}
+    , ngDocApiListSegment: '{{ entry.item.apiListSegment | replace("\\", "\\\\") | replace("'", "\\'") | replace("\n", "\\n") }}'
+    {%- endif -%}
+    },
     {%- if entry.item.isCategory %}
     providers: [
       ...({{ entry.item.id }}.providers ?? []),

package/templates/symbol/decorators.html.nunj

@@ -0,0 +1,12 @@
+{#-
+    Decorator chips with the per-decorator colour hook: `data-ng-doc-decorator` names the
+    decorator, so a site colours `@Component`, `@Injectable` or `@Input` chips from their
+    `--ng-doc-*-decorator-background` variables.
+-#}
+{% macro chip(name) -%}
+    <code data-ng-doc-decorator="{{ name | escape }}">{{ '@' + name | escape }}</code>
+{%- endmacro %}
+
+{% macro render(decorators) -%}
+    <span class="ng-doc-decorators-group">{% for decorator in decorators %}{{ chip(decorator.getName()) }}{% endfor %}</span>
+{%- endmacro %}