@ng-doc/builder 22.0.0-beta.1 → 22.0.0

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."
+    },
+    "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/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/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/page-wrapper.ts.nunj

@@ -3,24 +3,43 @@ 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 }}`,
@@ -36,6 +55,10 @@ const routes: Routes = [{
     },
     {%- 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 %}
@@ -58,6 +69,19 @@ export class PageComponent extends NgDocRootPage {
     super();
   }
 }
+{%- 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,
+  title: `{{ metadata.title | toTemplateString }}`,
+}, pageContentSource)]
+{%- else %}
 
 const routes: Routes = [{
     {%- if entryPath %}
@@ -67,6 +91,7 @@ const routes: Routes = [{
   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,11 @@ 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 }}`,
+    {%- if entry.item.apiListSegment is defined %}
+    data: {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 %}

package/templates/symbol/details.html.nunj

@@ -0,0 +1,62 @@
+{#-
+    The details of a declaration as a definition list: decorators, selectors, type parameters and
+    heritage, the same data as `api/details`. The `rail` variant also names the kind, its modifiers
+    and the scope; the page moves it into the right rail.
+-#}
+{% import "helpers/type.html.nunj" as typeMacro %}
+{% import "helpers/tag.html.nunj" as tagMacro %}
+{% import "helpers/declaration-modifiers.html.nunj" as modifiersMacro %}
+{% import "symbol/decorators.html.nunj" as decoratorsMacro %}
+
+{% macro render(declaration, scope, variant) %}
+    {%- set isClass = Node.isClassDeclaration(declaration) %}
+    {%- set decorators = declaration.getDecorators() if isClass else [] %}
+    {%- set selectors = declaration | extractSelectors %}
+    {%- set typeParameters = declaration.getTypeParameters() if declaration.getTypeParameters else [] %}
+    {%- if isClass %}
+        {%- set extends = [declaration.getExtends()] if declaration.getExtends() else [] %}
+        {%- set implements = declaration.getImplements() %}
+    {%- elseif Node.isInterfaceDeclaration(declaration) %}
+        {%- set extends = declaration.getExtends() %}
+        {%- set implements = [] %}
+    {%- else %}
+        {%- set extends = [] %}
+        {%- set implements = [] %}
+    {%- endif %}
+    {%- set declarationType = declaration | getDeclarationType %}
+    {%- set rail = variant == 'rail' %}
+    {%- if rail or decorators.length or selectors.length or typeParameters.length or extends.length or implements.length %}
+        {#- The content copy indexes what the per-section layout did (the selectors); the rail copy is
+            not indexed. #}
+        <dl class="ng-doc-api-details"{% if rail %} data-ng-doc-variant="rail" data-ng-doc-rail-details hidden indexable="false"{% endif %}>
+            {%- if rail and declarationType %}
+                <dt indexable="false">Kind</dt>
+                <dd>{{ tagMacro.render("Type alias" if declarationType == "TypeAlias" else declarationType, declarationType) }}{{ modifiersMacro.render(declaration) }}</dd>
+            {%- endif %}
+            {%- if decorators.length %}
+                <dt indexable="false">Decorators</dt>
+                <dd indexable="false">{{ decoratorsMacro.render(decorators) }}</dd>
+            {%- endif %}
+            {%- if selectors.length %}
+                <dt indexable="false">Selectors</dt>
+                <dd>{% for selector in selectors %}<code>{{ selector }}</code>{% endfor %}</dd>
+            {%- endif %}
+            {%- if typeParameters.length %}
+                <dt indexable="false">Generic types</dt>
+                <dd>{% for typeParameter in typeParameters %}{{ typeMacro.type(typeParameter) }}{% endfor %}</dd>
+            {%- endif %}
+            {%- if extends.length %}
+                <dt indexable="false">Extends</dt>
+                <dd>{% for item in extends %}{{ typeMacro.type(item) }}{% endfor %}</dd>
+            {%- endif %}
+            {%- if implements.length %}
+                <dt indexable="false">Implements</dt>
+                <dd>{% for item in implements %}{{ typeMacro.type(item) }}{% endfor %}</dd>
+            {%- endif %}
+            {%- if rail %}
+                <dt indexable="false">Scope</dt>
+                <dd>{{ scope.name }}</dd>
+            {%- endif %}
+        </dl>
+    {%- endif %}
+{% endmacro %}

package/templates/symbol/extended-by.html.nunj

@@ -0,0 +1,17 @@
+{#-
+    The classes that extend a class, as identifier chips (they no longer sit in See Also). When the
+    page has no `@see` tags, the list keeps
+    the `see-also` anchor that the per-section layout gave the derived classes, so links and
+    keywords to it still resolve.
+-#}
+{% set derived = declaration.getDerivedClasses() if declaration.getDerivedClasses else [] %}
+{% set seeDocs = docNode | getJsDocTags('see') %}
+
+{% if derived.length %}
+    <dl class="ng-doc-api-extended" indexable="false"{% if not seeDocs.length %} dataSlug="See Also" dataSlugType="heading"{% endif %}>
+        <dt>Extended by <span class="ng-doc-members-count">{{ derived.length }}</span></dt>
+        <dd>
+            {%- for cls in derived %}<code>{{ cls.getName() }}</code>{% endfor -%}
+        </dd>
+    </dl>
+{% endif %}

package/templates/symbol/header.html.nunj

@@ -0,0 +1,22 @@
+{#-
+    The header of an API page in the symbol view: the scope, the kind chip and the modifiers, the
+    name and the status callouts. The details follow the description in the page.
+-#}
+{% import "helpers/status.html.nunj" as statusMacro %}
+{% import "helpers/tag.html.nunj" as tagMacro %}
+{% import "helpers/declaration-modifiers.html.nunj" as modifiersMacro %}
+
+<div class="ng-doc-page-tags">
+    {% set declarationType = declaration | getDeclarationType %}
+
+    {{ tagMacro.render(scope.name, "ng-doc-scope") }}
+    <span class="ng-doc-inline-delimiter" indexable="false">/</span>
+    {{ tagMacro.render("Type alias" if declarationType == "TypeAlias" else declarationType, declarationType) if declarationType }}
+    {{ modifiersMacro.render(declaration) }}
+</div>
+
+<h1 class="{{ statusMacro.class(docNode) }}">
+    {{ declaration.getName() }}
+</h1>
+
+{{ statusMacro.render(docNode) }}