@ng-doc/app 22.0.0 → 22.2.0

package/types/ng-doc-app-components-code.d.ts

@@ -1,5 +1,6 @@
 import * as _angular_core from '@angular/core';
 import { AfterViewInit, Signal } from '@angular/core';
+import { NgDocContentTexts } from '@ng-doc/app/interfaces';
 
 /**
  * Renders a code block: a header with the file name, the language and the highlighted lines
@@ -9,6 +10,7 @@ import { AfterViewInit, Signal } from '@angular/core';
  * `code-line-numbers` theme variable to `none` hides them.
  */
 declare class NgDocCodeComponent implements AfterViewInit {
+    protected readonly texts: NgDocContentTexts;
     private readonly elementRef;
     /** Highlighted HTML of the code. When empty, the projected content is shown instead. */
     readonly html: _angular_core.InputSignal<string>;

package/types/ng-doc-app-components-command-palette.d.ts

@@ -1,6 +1,7 @@
 import * as _angular_forms_signals from '@angular/forms/signals';
 import * as _angular_core from '@angular/core';
 import { Signal } from '@angular/core';
+import { NgDocSearchPaletteTexts } from '@ng-doc/app/interfaces';
 import { NgDocShortcutsService } from '@ng-doc/app/services/shortcuts';
 
 /**
@@ -58,7 +59,8 @@ interface Action {
  * slash key.
  */
 declare class NgDocCommandPaletteComponent {
-    protected readonly scopes: readonly {
+    protected readonly texts: NgDocSearchPaletteTexts;
+    protected readonly scopes: {
         id: NgDocCommandPaletteScope;
         label: string;
     }[];

package/types/ng-doc-app-components-copy-button.d.ts

@@ -1,5 +1,6 @@
 import * as _angular_core from '@angular/core';
 import { Clipboard } from '@angular/cdk/clipboard';
+import { NgDocCopyTexts } from '@ng-doc/app/interfaces';
 import { NgDocTooltipDirective } from '@ng-doc/ui-kit';
 
 /** The text a copy button copies, or a function that reads it when the button is pressed. */
@@ -9,9 +10,10 @@ type NgDocCopyButtonText = string | (() => string);
  * icon into it.
  */
 declare class NgDocCopyButtonComponent {
+    protected readonly texts: NgDocCopyTexts;
     /** The text to copy, or a function that returns it when the button is pressed. */
     readonly text: _angular_core.InputSignal<NgDocCopyButtonText>;
-    /** Accessible name of the button, also shown in its tooltip. */
+    /** Accessible name of the button, also shown in its tooltip. Defaults to the `copy.copy` text. */
     readonly label: _angular_core.InputSignal<string>;
     /** The tooltip of the button. */
     readonly tooltip: _angular_core.Signal<NgDocTooltipDirective>;

package/types/ng-doc-app-components-demo-displayer.d.ts

@@ -1,4 +1,5 @@
 import * as _angular_core from '@angular/core';
+import { NgDocDemoTexts, NgDocCopyTexts } from '@ng-doc/app/interfaces';
 import { NgDocContent } from '@ng-doc/ui-kit';
 
 /**
@@ -6,6 +7,8 @@ import { NgDocContent } from '@ng-doc/ui-kit';
  * (the rows of a playground use it).
  */
 declare class NgDocDemoDisplayerComponent {
+    protected readonly texts: NgDocDemoTexts;
+    protected readonly copyTexts: NgDocCopyTexts;
     /** Content shown when the code is revealed; when empty, the highlighted `code` is shown. */
     readonly codeContent: _angular_core.InputSignal<NgDocContent>;
     /** Code of the demo, copied by the copy button and shown when there is no `codeContent`. */
@@ -14,16 +17,25 @@ declare class NgDocDemoDisplayerComponent {
     readonly language: _angular_core.InputSignal<string>;
     /** Whether the demo is shown in the stage with its controls; otherwise it is shown as is. */
     readonly container: _angular_core.InputSignal<boolean>;
+    /**
+     * The background of the canvas, such as the background of an isolated demo that shows a theme
+     * of its own.
+     */
+    readonly canvasBackground: _angular_core.InputSignal<string | undefined>;
+    /** The color of the dots of the canvas, such as the dots of a demo's own theme. */
+    readonly canvasDots: _angular_core.InputSignal<string | undefined>;
     /** Whether the displayer draws its border. */
     readonly border: _angular_core.InputSignal<boolean>;
     /** Whether the code is revealed. */
     readonly expanded: _angular_core.ModelSignal<boolean>;
+    /** A page that shows the demo alone, which the toolbar opens in a new tab. */
+    readonly newTabUrl: _angular_core.InputSignal<string | undefined>;
     /** Id of the region that holds the code, for the toggle's `aria-controls`. */
     protected readonly codeId: string;
     /** Reveals or hides the code. */
     toggle(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgDocDemoDisplayerComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgDocDemoDisplayerComponent, "ng-doc-demo-displayer", never, { "codeContent": { "alias": "codeContent"; "required": false; "isSignal": true; }; "code": { "alias": "code"; "required": false; "isSignal": true; }; "language": { "alias": "language"; "required": false; "isSignal": true; }; "container": { "alias": "container"; "required": false; "isSignal": true; }; "border": { "alias": "border"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; }, { "expanded": "expandedChange"; }, never, ["*", "*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgDocDemoDisplayerComponent, "ng-doc-demo-displayer", never, { "codeContent": { "alias": "codeContent"; "required": false; "isSignal": true; }; "code": { "alias": "code"; "required": false; "isSignal": true; }; "language": { "alias": "language"; "required": false; "isSignal": true; }; "container": { "alias": "container"; "required": false; "isSignal": true; }; "canvasBackground": { "alias": "canvasBackground"; "required": false; "isSignal": true; }; "canvasDots": { "alias": "canvasDots"; "required": false; "isSignal": true; }; "border": { "alias": "border"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; "newTabUrl": { "alias": "newTabUrl"; "required": false; "isSignal": true; }; }, { "expanded": "expandedChange"; }, never, ["[ngDocDemoControl]", "*", "*"], true, never>;
 }
 
 export { NgDocDemoDisplayerComponent };

package/types/ng-doc-app-components-demo-frame.d.ts

@@ -0,0 +1,107 @@
+import * as _angular_core from '@angular/core';
+import { Signal } from '@angular/core';
+import { SafeResourceUrl } from '@angular/platform-browser';
+import { ɵNgDocPlaygroundFrameMessage as _NgDocPlaygroundFrameMessage } from '@ng-doc/app/demo-app';
+import { NgDocDemoTexts } from '@ng-doc/app/interfaces';
+
+/**
+ * Shows a demo page of the demo application in an iframe, as tall as the demo's content: the demo
+ * page reports its height with `postMessage`, and only messages from this iframe's window and
+ * origin are accepted. The iframe is created in the browser after the first render (the server
+ * renders a placeholder with a link to the demo page) and loads lazily. Until the demo reports its
+ * size, a placeholder tells that it is loading; a demo page that loads without reporting it within
+ * 10 seconds is reported as failed, with the link.
+ */
+declare class NgDocDemoFrameComponent {
+    protected readonly texts: NgDocDemoTexts;
+    /** The URL of the demo page, relative to the document or absolute on its origin. */
+    readonly src: _angular_core.InputSignal<string>;
+    /** The accessible title of the iframe. */
+    readonly frameTitle: _angular_core.InputSignal<string>;
+    /** Whether the iframe fills its container instead of taking the demo's height (fullscreen). */
+    readonly fill: _angular_core.InputSignal<boolean>;
+    /**
+     * The URL fragment of the demo page, without `#`: the state of an isolated playground, and the
+     * theme the page shows (`~theme=dark`). The iframe loads with the fragment it has when the
+     * iframe is created; a later fragment replaces the page's location (`location.replace`), which
+     * reloads nothing and adds no history entry.
+     */
+    readonly fragment: _angular_core.InputSignal<string | undefined>;
+    /** Whether the page is the page of an isolated playground, which reports the target. */
+    readonly playground: _angular_core.InputSignal<boolean>;
+    /** The messages of an isolated playground's page, from this iframe only. */
+    readonly playgroundMessage: _angular_core.OutputEmitterRef<_NgDocPlaygroundFrameMessage>;
+    /**
+     * The page of an isolated playground (`playground`) loaded but sent no message of the playground
+     * within 10 seconds, such as a page the build didn't make.
+     */
+    readonly playgroundSilent: _angular_core.OutputEmitterRef<void>;
+    /** The height the demo reported, in pixels. */
+    readonly height: _angular_core.WritableSignal<number | undefined>;
+    /**
+     * The background color the demo's page reported, so that the canvas around the iframe can take
+     * it when the demo shows a theme of its own.
+     */
+    readonly background: _angular_core.WritableSignal<string | undefined>;
+    /** The color of the dots of the demo canvas in the demo's theme, which its page reported. */
+    readonly dots: _angular_core.WritableSignal<string | undefined>;
+    /**
+     * The color scheme of the demo's page, which the iframe takes: the page is transparent, and a
+     * browser paints an opaque backdrop behind an iframe whose color scheme differs from its page's.
+     */
+    readonly scheme: _angular_core.WritableSignal<string | undefined>;
+    /** `loading` until the demo reports its size, then `ready`; `failed` when it never does. */
+    readonly state: Signal<'loading' | 'ready' | 'failed'>;
+    /** Whether the iframe exists: only in the browser, after the first render. */
+    protected readonly created: _angular_core.WritableSignal<boolean>;
+    /** The demo page's URL for the iframe, with the fragment the iframe was created with. */
+    protected readonly frameSrc: Signal<SafeResourceUrl>;
+    private readonly sanitizer;
+    private readonly frame;
+    private readonly failed;
+    private readonly loaded;
+    private initialFragment?;
+    private shownFragment?;
+    private timer?;
+    private silenceTimer?;
+    private answered;
+    constructor();
+    /**
+     * Waits for the demo's size once its page has loaded.
+     * @internal
+     */
+    protected onLoad(): void;
+    /**
+     * Takes the height a demo page reports, from this iframe only.
+     * @param event - A message to the window.
+     * @internal
+     */
+    protected onMessage(event: MessageEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgDocDemoFrameComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgDocDemoFrameComponent, "ng-doc-demo-frame", never, { "src": { "alias": "src"; "required": true; "isSignal": true; }; "frameTitle": { "alias": "frameTitle"; "required": true; "isSignal": true; }; "fill": { "alias": "fill"; "required": false; "isSignal": true; }; "fragment": { "alias": "fragment"; "required": false; "isSignal": true; }; "playground": { "alias": "playground"; "required": false; "isSignal": true; }; }, { "playgroundMessage": "playgroundMessage"; "playgroundSilent": "playgroundSilent"; }, never, never, true, never>;
+}
+
+/**
+ * The button beside an isolated demo that switches the theme of its iframe in turn: the page's
+ * theme, Light and Dark. A `theme` option that is none of them, such as `auto` or the id of a
+ * custom theme, is offered after the page's theme.
+ */
+declare class NgDocDemoThemeButtonComponent {
+    protected readonly texts: NgDocDemoTexts;
+    private readonly themeTexts;
+    /** The theme of the iframe, or `undefined` while it follows the page. */
+    readonly theme: _angular_core.ModelSignal<string | undefined>;
+    /** The `theme` option of the demo, which the button offers too. */
+    readonly configured: _angular_core.InputSignal<string | undefined>;
+    /** The theme the next press switches to. */
+    protected readonly next: Signal<string | undefined>;
+    /**
+     * The name of a theme in the texts.
+     * @param theme - A theme, or `undefined` for the page's.
+     */
+    protected name(theme: string | undefined): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgDocDemoThemeButtonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgDocDemoThemeButtonComponent, "ng-doc-demo-theme-button", never, { "theme": { "alias": "theme"; "required": false; "isSignal": true; }; "configured": { "alias": "configured"; "required": false; "isSignal": true; }; }, { "theme": "themeChange"; }, never, never, true, never>;
+}
+
+export { NgDocDemoFrameComponent, NgDocDemoThemeButtonComponent };

package/types/ng-doc-app-components-demo.d.ts

@@ -1,6 +1,6 @@
 import * as _angular_core from '@angular/core';
-import { Signal, Type } from '@angular/core';
-import { NgDocDemoAsset } from '@ng-doc/app/interfaces';
+import { Signal, Type, WritableSignal } from '@angular/core';
+import { NgDocDemoTexts, NgDocCopyTexts, NgDocDemoAsset } from '@ng-doc/app/interfaces';
 import { NgDocDemoActionOptions } from '@ng-doc/core/interfaces';
 
 /** Widths the demo can be previewed at. */
@@ -11,31 +11,68 @@ type NgDocDemoPreviewWidth = 'full' | '480' | '280';
  * shows the stage fullscreen with the browser Fullscreen API; it is hidden where the browser does
  * not support it.
  *
- * The preview widths set the width of the demo's container; they do not emulate a device, so
- * media queries inside the demo do not respond to them.
+ * When the Vite engine built demo pages for the page (`NgDocRootPage.demoRoute`), the toolbar
+ * opens the demo's page in a new tab, and an isolated demo (the `isolated` option, or
+ * `isolatedDemos`) is shown in an iframe of its page: the preview widths are then the width of the
+ * iframe's viewport, so media queries inside the demo respond to them. Otherwise the demo renders
+ * in the page, and the preview widths set the width of its container only.
  */
 declare class NgDocDemoComponent {
+    protected readonly texts: NgDocDemoTexts;
+    protected readonly copyTexts: NgDocCopyTexts;
     private readonly rootPage;
     private readonly document;
+    private readonly platformLocation;
+    private readonly appBaseHref;
     /** Name of the demo component in the page's `demos`. */
     readonly componentName: _angular_core.InputSignal<string | undefined>;
     /** Options of the `demo` action. */
     readonly options: _angular_core.InputSignal<NgDocDemoActionOptions>;
     /** The demo component. */
     readonly demo: Signal<Type<unknown> | undefined>;
+    /**
+     * The URL of the demo's page, when the page has demo pages and the demo exists: the generated
+     * demo route and the demo's name under the base href, with the `inputs` option as a query
+     * parameter.
+     */
+    readonly demoUrl: Signal<string | undefined>;
+    /** Whether the demo is shown in an iframe of its page. */
+    readonly isolated: Signal<boolean>;
+    /**
+     * The theme of the demo's iframe: the `theme` option, until the reader picks another with the
+     * theme button; `undefined` follows the page.
+     */
+    readonly frameTheme: WritableSignal<string | undefined>;
+    /**
+     * The background of the stage while the demo shows a theme of its own: the background its page
+     * reported, so the whole stage reads in the demo's theme rather than only the iframe.
+     */
+    protected readonly stageBackground: Signal<string | undefined>;
+    /** The dots of the stage while the demo shows a theme of its own, in that theme's color. */
+    protected readonly stageDots: Signal<string | undefined>;
+    /** The URL fragment of the demo's iframe, which carries its theme. */
+    protected readonly frameFragment: Signal<string | undefined>;
+    /** The demo's page as the toolbar opens it in a new tab: in the theme of its iframe. */
+    protected readonly newTabUrl: Signal<string | undefined>;
+    /** The accessible title of the demo's iframe. */
+    protected readonly frameTitle: Signal<string>;
+    /** Whether the stage is fullscreen. */
+    protected readonly fullscreen: Signal<boolean>;
+    private readonly stage;
+    private readonly frame;
     /** Source files of the demo, filtered by the `tabs` option. */
     readonly assets: Signal<NgDocDemoAsset[]>;
     /**
      * The open view: `preview`, or the title of a source file. It starts on the preview, or on the
      * default source file when the `expanded` option is set.
      */
-    readonly view: _angular_core.WritableSignal<string>;
+    readonly view: WritableSignal<string>;
     /** The width the demo is previewed at. */
-    readonly previewWidth: _angular_core.WritableSignal<NgDocDemoPreviewWidth>;
-    protected readonly previewWidths: readonly {
-        readonly width: NgDocDemoPreviewWidth;
-        readonly label: string;
-        readonly readout: string;
+    readonly previewWidth: WritableSignal<NgDocDemoPreviewWidth>;
+    protected readonly previewWidths: {
+        width: NgDocDemoPreviewWidth;
+        label: string;
+        readout: string;
     }[];
     /** Readout of the preview width. */
     protected readonly widthReadout: Signal<string>;

package/types/ng-doc-app-components-fullscreen-button.d.ts

@@ -1,7 +1,9 @@
 import * as i0 from '@angular/core';
+import { NgDocDemoTexts } from '@ng-doc/app/interfaces';
 
 /** A link that opens a demo's fullscreen route in a new tab. */
 declare class NgDocFullscreenButtonComponent {
+    protected readonly texts: NgDocDemoTexts;
     /** Route of the fullscreen demo. */
     readonly route: i0.InputSignal<string>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgDocFullscreenButtonComponent, never>;

package/types/ng-doc-app-components-fullscreen-toggle.d.ts

@@ -1,5 +1,6 @@
 import * as i0 from '@angular/core';
 import { Signal } from '@angular/core';
+import { NgDocDemoTexts } from '@ng-doc/app/interfaces';
 import { NgDocFullscreenDirective } from '@ng-doc/ui-kit';
 
 /**
@@ -13,6 +14,7 @@ import { NgDocFullscreenDirective } from '@ng-doc/ui-kit';
  * ```
  */
 declare class NgDocFullscreenToggleComponent {
+    protected readonly texts: NgDocDemoTexts;
     /** The element to show fullscreen. */
     readonly target: i0.InputSignal<NgDocFullscreenDirective>;
     /** Accessible name and tooltip of the button, which follow the fullscreen state. */

package/types/ng-doc-app-components-heading-anchor.d.ts

@@ -1,10 +1,12 @@
 import * as _angular_core from '@angular/core';
 import { OnInit } from '@angular/core';
+import { NgDocCopyTexts } from '@ng-doc/app/interfaces';
 
 /**
  * Button next to a heading that copies the link to the heading.
  */
 declare class NgDocHeadingAnchorComponent implements OnInit {
+    protected readonly texts: NgDocCopyTexts;
     /** Id of the heading. */
     readonly anchor: _angular_core.InputSignal<string>;
     /** Classes of the host element. */

package/types/ng-doc-app-components-image-viewer.d.ts

@@ -1,5 +1,6 @@
 import * as _angular_core from '@angular/core';
 import { TemplateRef } from '@angular/core';
+import { NgDocContentTexts } from '@ng-doc/app/interfaces';
 import { NgDocOverlayService } from '@ng-doc/ui-kit';
 import { NgDocOverlayRef } from '@ng-doc/ui-kit/classes';
 
@@ -16,6 +17,7 @@ interface ZoomSize {
  * decorative: neither becomes a button.
  */
 declare class NgDocImageViewerComponent {
+    protected readonly texts: NgDocContentTexts;
     /** Source of the image. */
     readonly src: _angular_core.InputSignal<string>;
     /** Alternative text of the image. */

package/types/ng-doc-app-components-navbar.d.ts

@@ -1,4 +1,5 @@
 import * as _angular_core from '@angular/core';
+import { NgDocNavigationTexts } from '@ng-doc/app/interfaces';
 import { NgDocSidebarService } from '@ng-doc/app/services/sidebar';
 
 /**
@@ -18,6 +19,7 @@ import { NgDocSidebarService } from '@ng-doc/app/services/sidebar';
  * ```
  */
 declare class NgDocNavbarComponent {
+    protected readonly texts: NgDocNavigationTexts;
     protected readonly sidebarService: NgDocSidebarService;
     /**
      * Show search input

package/types/ng-doc-app-components-page-navigation.d.ts

@@ -1,10 +1,11 @@
 import * as _angular_core from '@angular/core';
-import { NgDocPageNavigation, NgDocNavigation } from '@ng-doc/app/interfaces';
+import { NgDocPageNavigation, NgDocNavigationTexts, NgDocNavigation } from '@ng-doc/app/interfaces';
 
 /**
  * Links to the previous and the next page, as two cards at the bottom of a guide.
  */
 declare class NgDocPageNavigationComponent implements NgDocPageNavigation {
+    protected readonly texts: NgDocNavigationTexts;
     /** The page before this one in the sidebar. */
     readonly prevPage: _angular_core.InputSignal<NgDocNavigation | undefined>;
     /** The page after this one in the sidebar. */

package/types/ng-doc-app-components-page.d.ts

@@ -3,7 +3,7 @@ import { ElementRef, ChangeDetectorRef } from '@angular/core';
 import { NgDocContentController } from '@ng-doc/app/classes/content-controller';
 import { NgDocRootPage } from '@ng-doc/app/classes/root-page';
 import { NgDocPageWrapperComponent } from '@ng-doc/app/components/page-wrapper';
-import { NgDocPageSkeleton } from '@ng-doc/app/interfaces';
+import { NgDocPageTexts, NgDocPageSkeleton } from '@ng-doc/app/interfaces';
 
 /**
  * A generated page: its rendered content, the page actions (copy link, edit and view the source),
@@ -15,6 +15,7 @@ import { NgDocPageSkeleton } from '@ng-doc/app/interfaces';
  * chrome.
  */
 declare class NgDocPageComponent {
+    protected readonly texts: NgDocPageTexts;
     /** The element that holds the rendered page content. */
     readonly pageContainer: _angular_core.Signal<ElementRef<any> | undefined>;
     protected rootPage: NgDocRootPage;
@@ -35,9 +36,16 @@ declare class NgDocPageComponent {
     private readonly ngZone;
     private readonly location;
     private readonly locationStrategy;
+    private readonly viewportScroller;
     private linkCopiedTimer?;
     /** Removes the server-rendered copy shown while asynchronous content loads. */
     private snapshot?;
+    /**
+     * The scroll position when a development content update of this page arrived, restored once
+     * its content has rendered: the new HTML replaces the old one, and the page may be shorter for
+     * a moment while its processors run.
+     */
+    private updateScroll?;
     constructor();
     /**
      * Shows one of the page's fullscreen routes instead of the page, or the page again. The outlet
@@ -62,6 +70,7 @@ declare class NgDocPageComponent {
      */
     copyLink(): void;
     private connectContent;
+    private restoreUpdateScroll;
     private releaseSnapshot;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgDocPageComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgDocPageComponent, "ng-doc-page", never, {}, {}, never, never, true, never>;