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

package/types/ng-doc-app-interfaces.d.ts

@@ -1,5 +1,5 @@
 import { NgDocBaseEntity, JSDocMetadata, NgDocPageIndex } from '@ng-doc/core/interfaces';
-import { Type, Injector } from '@angular/core';
+import { Type, Injector, Signal } from '@angular/core';
 import { InputType } from '@ng-doc/core';
 import { Constructor } from '@ng-doc/core/types/constructor';
 import { ControlValueAccessor } from '@angular/forms';
@@ -32,6 +32,12 @@ interface NgDocContext {
      * List of navigation items
      */
     navigation: NgDocNavigation[];
+    /**
+     * The segments of the site's API lists (`assets/ng-doc/<segment>/api-list.json`, an empty string
+     * for the root list). The new engine generates it, so the search palette requests only these
+     * lists; without it, the palette finds them in the router configuration.
+     */
+    apiLists?: string[];
 }
 
 interface NgDocDemoAssets {
@@ -85,6 +91,11 @@ interface NgDocTocItem {
     level: number;
 }
 
+/**
+ * A field of a page skeleton component. The page sets it through the setInput method of the
+ * component reference, so the component may declare it as a plain property or as a signal input.
+ */
+type NgDocPageSkeletonField<T> = T | Signal<T | undefined>;
 /**
  * Interface for page navigation implementation
  */
@@ -92,11 +103,11 @@ interface NgDocPageNavigation {
     /**
      * Previous page
      */
-    prevPage?: NgDocNavigation;
+    prevPage?: NgDocPageSkeletonField<NgDocNavigation | undefined>;
     /**
      * Next page
      */
-    nextPage?: NgDocNavigation;
+    nextPage?: NgDocPageSkeletonField<NgDocNavigation | undefined>;
 }
 /**
  * Interface for page breadcrumb implementation
@@ -105,7 +116,7 @@ interface NgDocPageBreadcrumbs {
     /**
      * Breadcrumb items
      */
-    breadcrumbs: string[];
+    breadcrumbs: NgDocPageSkeletonField<string[]>;
 }
 /**
  * Interface for page table of content implementation
@@ -114,7 +125,18 @@ interface NgDocPageToc {
     /**
      * Table of content items.
      */
-    tableOfContent: NgDocTocItem[];
+    tableOfContent: NgDocPageSkeletonField<NgDocTocItem[]>;
+    /**
+     * URL where the reader can edit the page source. The page sets it only on components that
+     * declare this input.
+     */
+    editSourceFileUrl?: NgDocPageSkeletonField<string | undefined>;
+    /**
+     * The symbol details of an API page (kind, decorators, heritage, scope) as an element to show
+     * in the rail. The page sets it only on components that declare this input, and moves the
+     * element out of the content; other components leave it hidden in the content.
+     */
+    details?: NgDocPageSkeletonField<Element | undefined>;
 }
 /**
  * Page skeleton that should be used to create different parts of the page.
@@ -137,29 +159,40 @@ interface NgDocPageSkeleton {
 }
 
 /**
- * Interface describing Type Control
+ * A field of a type control that the playground sets: a plain field, or a signal input
+ * (`input()`) of the same name. The playground sets inputs with the `setInput()` method of the
+ * component reference and assigns plain fields.
+ */
+type NgDocTypeControlField<T> = T | Signal<T | undefined>;
+/**
+ * Interface describing Type Control.
+ *
+ * A type control is a `ControlValueAccessor`. The playground sets the fields below before the
+ * control renders; declare them as plain fields or as signal inputs (`name = input<string>()`).
+ * A field declared as an input (a signal input or an `@Input()`) is set as an input, so the
+ * control's `ngOnChanges` reports it; a plain field is assigned and is not reported.
  */
 interface NgDocTypeControl<T = unknown> extends ControlValueAccessor {
     /**
      * The name of the input for which it is created
      */
-    name?: string;
+    name?: NgDocTypeControlField<string>;
     /**
      * The description of the input (based on the comment)
      */
-    description?: string;
+    description?: NgDocTypeControlField<string>;
     /**
      * The default value of the input
      */
-    default?: T;
+    default?: NgDocTypeControlField<T>;
     /**
      * The list of possible values, it usually works only for Type Aliases which has several values
      */
-    options?: string[];
+    options?: NgDocTypeControlField<string[]>;
     /**
      * Determines if the property is manually added by the user using `controls` property in playground config
      */
-    isManual?: boolean;
+    isManual?: NgDocTypeControlField<boolean>;
 }
 
 /**
@@ -172,8 +205,9 @@ interface NgDocTypeControlProviderOptions {
      */
     hideLabel?: boolean;
     /**
-     * You can use this to change the order of the type control
-     * NgDoc's controls start at 5 and go up to 10
+     * You can use this to change the order of the type control.
+     * Controls are sorted by ascending order, and controls without an order come last.
+     * NgDoc's own controls use 10 (type aliases), 20 (`string`), 30 (`number`) and 40 (`boolean`)
      */
     order?: number;
 }
@@ -204,18 +238,4 @@ interface NgDocTab {
     active?: boolean;
 }
 
-/**
- * Interface describing a custom theme for the application
- */
-interface NgDocTheme {
-    /**
-     * Theme ID that you can use to set theme (e.g. `CustomTheme`)
-     */
-    id: string;
-    /**
-     * Path that will be used to load theme dynamically (e.g. `/assets/themes/custom.css`)
-     */
-    path: string;
-}
-
-export type { NgDocContext, NgDocDemoAsset, NgDocDemoAssets, NgDocNavigation, NgDocPageBreadcrumbs, NgDocPageNavigation, NgDocPageProcessor, NgDocPageSkeleton, NgDocPageToc, NgDocProcessorOptions, NgDocProvidedTypeControl, NgDocSearchResult, NgDocTab, NgDocTheme, NgDocTocItem, NgDocTypeControl, NgDocTypeControlProviderOptions };
+export type { NgDocContext, NgDocDemoAsset, NgDocDemoAssets, NgDocNavigation, NgDocPageBreadcrumbs, NgDocPageNavigation, NgDocPageProcessor, NgDocPageSkeleton, NgDocPageSkeletonField, NgDocPageToc, NgDocProcessorOptions, NgDocProvidedTypeControl, NgDocSearchResult, NgDocTab, NgDocTocItem, NgDocTypeControl, NgDocTypeControlField, NgDocTypeControlProviderOptions };

package/types/ng-doc-app-pipes-decode-uri-component.d.ts

@@ -1,6 +1,9 @@
 import * as i0 from '@angular/core';
 import { PipeTransform } from '@angular/core';
 
+/**
+ * Decodes a URI component, and returns the value unchanged when it is not a valid encoding.
+ */
 declare class NgDocDecodeUriComponentPipe implements PipeTransform {
     transform(value: string): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgDocDecodeUriComponentPipe, never>;

package/types/ng-doc-app-pipes-extract-value.d.ts

@@ -2,6 +2,9 @@ import * as i0 from '@angular/core';
 import { PipeTransform } from '@angular/core';
 import { NgDocExtractedValue } from '@ng-doc/core/types/extracted-value';
 
+/**
+ * Parses the string form of a value (for example a default value of a playground property).
+ */
 declare class NgDocExtractValuePipe implements PipeTransform {
     transform(value: string): NgDocExtractedValue;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgDocExtractValuePipe, never>;

package/types/ng-doc-app-pipes-filter-by-text.d.ts

@@ -1,6 +1,10 @@
 import * as i0 from '@angular/core';
 import { PipeTransform } from '@angular/core';
 
+/**
+ * Keeps the items that match a search term. By default an item matches when its string form
+ * equals the term.
+ */
 declare class NgDocFilterByTextPipe<T> implements PipeTransform {
     transform(items: readonly T[], searchTerm: string, matcher?: (item: T, searchTerm: string) => boolean): readonly T[];
     static ɵfac: i0.ɵɵFactoryDeclaration<NgDocFilterByTextPipe<any>, never>;

package/types/ng-doc-app-pipes-sanitize-html.d.ts

@@ -2,10 +2,12 @@ import * as i0 from '@angular/core';
 import { PipeTransform } from '@angular/core';
 import { SafeHtml } from '@angular/platform-browser';
 
+/**
+ * Marks HTML as trusted, so it can be bound to `innerHTML` without sanitization. Use it only for
+ * HTML that NgDoc generated.
+ */
 declare class NgDocSanitizeHtmlPipe implements PipeTransform {
     private readonly sanitizer;
-    /** Inserted by Angular inject() migration for backwards compatibility */
-    constructor(...args: unknown[]);
     transform(value: string): SafeHtml;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgDocSanitizeHtmlPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<NgDocSanitizeHtmlPipe, "ngDocSanitizeHtml", true>;

package/types/ng-doc-app-processors-page-processor.d.ts

@@ -1,15 +1,38 @@
-import * as i0 from '@angular/core';
-import { OnChanges, EventEmitter, ElementRef, ViewContainerRef, ApplicationRef, Injector, Renderer2, SimpleChanges } from '@angular/core';
+import * as _angular_core from '@angular/core';
+import { OutputRef, ElementRef, ViewContainerRef, ApplicationRef, Injector, Renderer2, ErrorHandler } from '@angular/core';
 import { SafeHtml } from '@angular/platform-browser';
+import { NgDocContentRenderFailure } from '@ng-doc/app/classes/content-controller';
 import { NgDocPageProcessor } from '@ng-doc/app/interfaces';
 
 /**
- * Base processor class to create a processor directive that will be used to replace
- * html nodes with an Angular component.
+ * Renders HTML into its host element and replaces the nodes that the page processors
+ * (`NG_DOC_PAGE_PROCESSOR`, `NG_DOC_PAGE_CUSTOM_PROCESSOR`) select with Angular components.
+ *
+ * Each change of the HTML or of `contentVersion` destroys the components of the previous pass
+ * and schedules a new pass for the next microtask, after the HTML is in the DOM. A pass that a
+ * newer change superseded, or that ends after the component is destroyed, emits nothing.
  */
-declare class NgDocPageProcessorComponent implements OnChanges {
-    html: SafeHtml;
-    afterRender: EventEmitter<void>;
+declare class NgDocPageProcessorComponent {
+    /** The HTML to render and process. */
+    readonly html: _angular_core.InputSignal<SafeHtml>;
+    /** Version of the HTML. A new version processes the HTML again, even when it is unchanged. */
+    readonly contentVersion: _angular_core.InputSignal<number>;
+    /**
+     * Emits the version of a pass after its components are created and before they render, in the
+     * same task, so that a listener can reveal the content they will measure.
+     * @internal
+     */
+    readonly beforeRender: _angular_core.OutputEmitterRef<number>;
+    /** Emits after a pass has created its components and rendered them. */
+    readonly afterRender: _angular_core.OutputEmitterRef<void>;
+    /** Emits the version of each pass that completed. */
+    readonly contentProcessed: _angular_core.OutputEmitterRef<number>;
+    private readonly processingErrors;
+    /**
+     * Emits the version and the error of a pass that a processor failed. Without a listener, the
+     * error goes to the `ErrorHandler` instead.
+     */
+    readonly processingError: OutputRef<NgDocContentRenderFailure>;
     processors: Array<NgDocPageProcessor<unknown>>;
     customProcessors: Array<NgDocPageProcessor<unknown>>;
     protected readonly elementRef: ElementRef<HTMLElement>;
@@ -17,10 +40,16 @@ declare class NgDocPageProcessorComponent implements OnChanges {
     protected readonly applicationRef: ApplicationRef;
     protected readonly injector: Injector;
     protected readonly renderer: Renderer2;
-    ngOnChanges({ html }: SimpleChanges): void;
+    protected readonly errorHandler: ErrorHandler;
+    private readonly sanitizer;
+    private scheduledVersion;
+    private scheduledHtml?;
+    private destroyed;
+    constructor();
+    private schedule;
     private process;
-    static ɵfac: i0.ɵɵFactoryDeclaration<NgDocPageProcessorComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<NgDocPageProcessorComponent, "[ngDocPageProcessor]", never, { "html": { "alias": "ngDocPageProcessor"; "required": true; }; }, { "afterRender": "afterRender"; }, never, ["*"], true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgDocPageProcessorComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgDocPageProcessorComponent, "[ngDocPageProcessor]", never, { "html": { "alias": "ngDocPageProcessor"; "required": false; "isSignal": true; }; "contentVersion": { "alias": "contentVersion"; "required": false; "isSignal": true; }; }, { "beforeRender": "beforeRender"; "afterRender": "afterRender"; "contentProcessed": "contentProcessed"; "processingError": "processingError"; }, never, ["*"], true, never>;
 }
 
 export { NgDocPageProcessorComponent };

package/types/ng-doc-app-processors-processors-tooltip.d.ts

@@ -1,17 +1,18 @@
-import * as i0 from '@angular/core';
-import { AfterViewInit } from '@angular/core';
+import * as _angular_core from '@angular/core';
 import { NgDocPageProcessor } from '@ng-doc/app/interfaces';
 
-declare class NgDocTooltipWrapperComponent implements AfterViewInit {
-    private readonly changeDetectorRef;
-    content?: string;
-    protected tooltipElement: HTMLElement | null;
-    private contentProjection?;
+declare class NgDocTooltipWrapperComponent {
+    readonly content: _angular_core.InputSignal<string | undefined>;
+    protected readonly tooltipElement: _angular_core.WritableSignal<HTMLElement | null>;
+    private readonly contentProjection;
     constructor();
-    ngAfterViewInit(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<NgDocTooltipWrapperComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<NgDocTooltipWrapperComponent, "ng-doc-tooltip-wrapper", never, { "content": { "alias": "content"; "required": false; }; }, {}, never, ["*"], true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgDocTooltipWrapperComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgDocTooltipWrapperComponent, "ng-doc-tooltip-wrapper", never, { "content": { "alias": "content"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
+/**
+ * Wraps an element with an `ngDocTooltip` attribute in a component that shows the attribute's
+ * value as a tooltip.
+ */
 declare const tooltipProcessor: NgDocPageProcessor<NgDocTooltipWrapperComponent>;
 
 export { tooltipProcessor };

package/types/ng-doc-app-processors-processors.d.ts

@@ -5,6 +5,7 @@ import { NgDocDemoComponent } from '@ng-doc/app/components/demo';
 import { NgDocDemoPaneComponent } from '@ng-doc/app/components/demo-pane';
 import { NgDocHeadingAnchorComponent } from '@ng-doc/app/components/heading-anchor';
 import { NgDocImageViewerComponent } from '@ng-doc/app/components/image-viewer';
+import { NgDocMembersComponent } from '@ng-doc/app/components/members';
 import { NgDocMermaidViewerComponent } from '@ng-doc/app/components/mermaid-viewer';
 import { NgDocPlaygroundComponent } from '@ng-doc/app/components/playground';
 import { NgDocTabsComponent } from '@ng-doc/app/components/tabs';
@@ -25,10 +26,13 @@ declare const iconProcessor: NgDocPageProcessor<NgDocIconComponent>;
 
 declare const imageProcessor: NgDocPageProcessor<NgDocImageViewerComponent>;
 
+/** Adds the member filter to the members table of an API page (`<ng-doc-members>`). */
+declare const membersProcessor: NgDocPageProcessor<NgDocMembersComponent>;
+
 declare const mermaidProcessor: NgDocPageProcessor<NgDocMermaidViewerComponent>;
 
 declare const playgroundProcessor: NgDocPageProcessor<NgDocPlaygroundComponent>;
 
 declare const tabsProcessor: NgDocPageProcessor<NgDocTabsComponent>;
 
-export { blockquoteProcessor, codeProcessor, demoPaneProcessor, demoProcessor, headingAnchorProcessor, iconProcessor, imageProcessor, mermaidProcessor, playgroundProcessor, tabsProcessor };
+export { blockquoteProcessor, codeProcessor, demoPaneProcessor, demoProcessor, headingAnchorProcessor, iconProcessor, imageProcessor, membersProcessor, mermaidProcessor, playgroundProcessor, tabsProcessor };

package/types/ng-doc-app-providers-ng-doc-app.d.ts

@@ -1,11 +1,22 @@
 import { EnvironmentProviders, Provider } from '@angular/core';
 import { NgDocHighlighterConfig } from '@ng-doc/app/services/highlighter';
+import { NgDocContentScrollPositionRestoration } from '@ng-doc/app/tokens';
 import { NgDocUiConfig } from '@ng-doc/ui-kit';
 
 /**
  * NgDoc application config.
  */
 interface NgDocApplicationConfig {
+    /**
+     * Replays a router anchor scroll once asynchronous NgDoc content has been processed.
+     * Enable this beside Angular router anchor scrolling.
+     */
+    contentAnchorScrolling?: boolean;
+    /**
+     * Replays a saved router position after asynchronous NgDoc content is processed.
+     * Select the same intent as Angular router scroll position restoration.
+     */
+    contentScrollPositionRestoration?: NgDocContentScrollPositionRestoration;
     /**
      * UI Kit configuration.
      */
@@ -14,6 +25,12 @@ interface NgDocApplicationConfig {
      * Shiki theme.
      */
     shiki?: NgDocHighlighterConfig;
+    /**
+     * Whether single-key shortcuts (slash, the square brackets, F, L and T) are on for readers who
+     * have not turned them on or off themselves. Readers can always change it with the switch in
+     * the search palette. Command+K (Control+K) opens the search either way. Defaults to true.
+     */
+    shortcuts?: boolean;
 }
 /**
  * Provides the NgDoc application configuration.

package/types/ng-doc-app-providers-playground-demo.d.ts

@@ -1,4 +1,4 @@
-import { Provider, InjectionToken } from '@angular/core';
+import { InjectionToken, Provider } from '@angular/core';
 import { Constructor } from '@ng-doc/core/types';
 
 /**

package/types/ng-doc-app-providers-type-control.d.ts

@@ -1,5 +1,5 @@
-import { Provider, InjectionToken } from '@angular/core';
-import { NgDocTypeControl, NgDocTypeControlProviderOptions, NgDocProvidedTypeControl } from '@ng-doc/app/interfaces';
+import { InjectionToken, Provider } from '@angular/core';
+import { NgDocProvidedTypeControl, NgDocTypeControl, NgDocTypeControlProviderOptions } from '@ng-doc/app/interfaces';
 import { Constructor } from '@ng-doc/core/types';
 
 /**

package/types/ng-doc-app-services-content-scroll-intent.d.ts

@@ -0,0 +1,52 @@
+import * as i0 from '@angular/core';
+import { Signal } from '@angular/core';
+
+/** The fragment of the application's first navigation, kept until a page replays or drops it. */
+interface NgDocInitialContentScrollIntent {
+    /** The decoded fragment of the navigation. */
+    readonly anchor: string;
+    /** Id of the navigation that produced the fragment. */
+    readonly navigationId: number;
+    /** The URL after redirects. */
+    readonly url: string;
+}
+/** Captures the public initial-navigation facts that are unavailable after component activation. */
+declare class NgDocContentScrollIntent {
+    private readonly browser;
+    private readonly router;
+    private candidate?;
+    private intent?;
+    private readonly listeners;
+    private started;
+    private successful;
+    private subscription?;
+    private readonly intentState;
+    /**
+     * The pending initial intent as a signal, the same value `subscribe()` listeners receive.
+     */
+    readonly currentIntent: Signal<NgDocInitialContentScrollIntent | undefined>;
+    constructor();
+    /** Starts following router events. Does nothing on the server or when already started. */
+    start(): void;
+    /**
+     * Calls the listener with every change of the intent, and at once with the pending one.
+     * @param listener - Receives the intent, or `undefined` once it is consumed or cancelled.
+     * @returns A function that removes the listener.
+     */
+    subscribe(listener: (intent: NgDocInitialContentScrollIntent | undefined) => void): () => void;
+    /**
+     * Consumes the current fallback after its page has either replayed or explicitly yielded it.
+     * @param navigationId - The navigation of the intent to consume.
+     */
+    settle(navigationId: number): void;
+    private navigationStarted;
+    private navigationEnded;
+    private scrolled;
+    private publish;
+    private destroy;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgDocContentScrollIntent, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+
+export { NgDocContentScrollIntent };
+export type { NgDocInitialContentScrollIntent };

package/types/ng-doc-app-services-content-state.d.ts

@@ -0,0 +1,40 @@
+import * as i0 from '@angular/core';
+import { Signal } from '@angular/core';
+
+/** A content source that failed to load or to render. */
+interface NgDocContentFailure {
+    /** Id of the content source that failed. */
+    readonly contentId: string;
+    /** The error it failed with. */
+    readonly error: unknown;
+}
+/** Request-local content failures observed by the SSR readiness boundary. */
+declare class NgDocContentState {
+    private readonly failures;
+    private readonly failureState;
+    /**
+     * The failure `currentFailure()` returns, as a signal. It changes with every
+     * `report()` and `clear()` call.
+     */
+    readonly failure: Signal<NgDocContentFailure | undefined>;
+    /**
+     * Records the failure of one content owner, replacing its previous failure.
+     * @param owner - The object that owns the content source.
+     * @param failure - The failure.
+     */
+    report(owner: object, failure: NgDocContentFailure): void;
+    /**
+     * Forgets the failure of one content owner.
+     * @param owner - The object that owns the content source.
+     */
+    clear(owner: object): void;
+    /** Returns the oldest failure that is still recorded, if any. */
+    currentFailure(): NgDocContentFailure | undefined;
+    /** Throws the error of `currentFailure()`, if there is one. */
+    throwIfFailed(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgDocContentState, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+
+export { NgDocContentState };
+export type { NgDocContentFailure };

package/types/ng-doc-app-services-fullscreen-route.d.ts

@@ -0,0 +1,35 @@
+import * as i0 from '@angular/core';
+import { Signal } from '@angular/core';
+
+/**
+ * Tells whether a page shows one of its fullscreen routes: a child route of the page (see
+ * `route.children` of `NgDocPage`), which `ng-doc-page` shows on its own, on the canvas of demos,
+ * instead of the page. Pages with `disableFullscreenRoutes` never report one.
+ *
+ * While one is shown, `ng-doc-root` hides the navbar, the sidebar and the footer, and
+ * `ng-doc-page-wrapper` hides the breadcrumbs, the page header, the page links and the table of
+ * contents, so the route opens as a standalone page without changes to the application's template.
+ */
+declare class NgDocFullscreenRouteService {
+    private readonly pages;
+    /**
+     * Whether the server rendered a fullscreen route, until the first navigation in the browser
+     * settles. `ng-doc-root` renders before its page does, and it must render the server's markup
+     * (and hide the same chrome) until the page tells again.
+     */
+    private readonly serverRendered;
+    /** Whether a page shows one of its fullscreen routes. */
+    readonly active: Signal<boolean>;
+    constructor();
+    /**
+     * Records whether a page shows one of its fullscreen routes.
+     * @param page - The page.
+     * @param shown - Whether the page shows a fullscreen route.
+     * @internal
+     */
+    set(page: object, shown: boolean): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgDocFullscreenRouteService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+
+export { NgDocFullscreenRouteService };

package/types/ng-doc-app-services-highlighter.d.ts

@@ -1,27 +1,62 @@
 import * as _ng_doc_app_tokens from '@ng-doc/app/tokens';
-import { ThemeInput } from 'shiki';
 import * as i0 from '@angular/core';
+import { OnDestroy, Signal } from '@angular/core';
+import { ThemeInput } from 'shiki';
 
+/** Shiki configuration of the code highlighter. */
 interface NgDocHighlighterConfig {
     /**
      * Themes sources.
      */
     themes?: ThemeInput[];
     /**
-     * Theme that will be used for rendering the code blocks.
+     * Has no effect, and is reported in development mode.
+     *
+     * The theme names come from `shiki.themes` in `ng-doc.config.ts`: NgDoc highlights code blocks
+     * with them when it builds the site, and passes them to the application (`NG_DOC_SHIKI_THEME`),
+     * so the code that the browser highlights matches the code blocks.
+     * @deprecated Set the theme names in `shiki.themes` of `ng-doc.config.ts` instead, and load
+     * other themes with `themes`. This field will be removed in a future major release.
      */
     theme?: {
         light: string;
         dark: string;
     };
 }
-declare class NgDocHighlighterService {
-    private static highlighter?;
+/**
+ * Highlights code with Shiki. `provideNgDocApp` initializes it before the application renders.
+ */
+declare class NgDocHighlighterService implements OnDestroy {
+    private static defaultInitialization?;
+    private highlighter?;
+    private initialization?;
+    private ownsHighlighter;
+    private destroyed;
+    private readonly readyState;
     protected readonly theme: _ng_doc_app_tokens.NgDocShikiTheme;
+    /**
+     * Whether `highlight()` can highlight: `true` once `initialize()` has finished, and
+     * `false` again after the service is destroyed.
+     */
+    readonly ready: Signal<boolean>;
+    /**
+     * Loads Shiki with the built-in themes (`github-light`, `ayu-dark` and NgDoc's `css-variables`)
+     * and the given ones. Concurrent and repeated calls share one initialization; a failed one can
+     * be retried.
+     * @param config - Custom Shiki themes to load.
+     */
     initialize(config?: NgDocHighlighterConfig): Promise<void>;
+    /** Disposes the highlighter this service created for custom themes. */
+    ngOnDestroy(): void;
+    private static create;
+    /**
+     * Returns the code as highlighted HTML, or an empty string before `initialize()` has
+     * finished. It reads `ready()`, so a `computed` over it updates once Shiki is loaded.
+     * @param code - Angular HTML to highlight.
+     */
     highlight(code: string): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgDocHighlighterService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<NgDocHighlighterService>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
 
 export { NgDocHighlighterService };