@ng-doc/app 22.0.0 → 22.2.0

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

@@ -0,0 +1,297 @@
+import * as i0 from '@angular/core';
+import { Provider, EnvironmentProviders, ApplicationConfig, Type } from '@angular/core';
+import { Routes } from '@angular/router';
+import { NgDocDemoProvidersImport } from '@ng-doc/core/interfaces';
+
+/**
+ * The root of the demo application, which shows one demo per page with only Angular and that
+ * demo loaded. In an iframe it reports the height of its content to the page that embeds it (a
+ * `ResizeObserver` on its border box), and it follows the theme the reader picks on the
+ * documentation site, which stores it in `localStorage`, unless its URL fragment sets a theme
+ * (`~theme=dark`, the `theme` option of a demo or a playground, or the theme button beside it).
+ * In an iframe its page is transparent, so the canvas of the documentation page shows through, and
+ * it reports its theme's background, dots and color scheme whenever they change, so that the
+ * embedding page can paint the canvas in the demo's own theme.
+ */
+declare class NgDocDemoAppComponent {
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgDocDemoAppComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<NgDocDemoAppComponent, "ng-doc-demo-app", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * How the demo application starts.
+ * @internal
+ */
+interface ɵNgDocDemoApplicationOptions {
+    /** Change detection with zone.js, when the application's polyfills load it. */
+    readonly zone?: boolean;
+    /**
+     * Hydration of the server-rendered page: always on the server, which then writes the hydration
+     * data, and in the browser only for a page the server rendered (a page without it, such as the
+     * page of a demo that failed to prerender or the development server's, has nothing to hydrate).
+     */
+    readonly hydration?: boolean;
+    /** Providers added after the others, for example server rendering. */
+    readonly providers?: Array<Provider | EnvironmentProviders>;
+}
+/**
+ * The configuration of the demo application: change detection, the router with the demo pages
+ * (and a page for unknown demos), hydration, and the providers of `demoProviders`. The generated entries of
+ * the demo application bootstrap `NgDocDemoAppComponent` with it, in the browser and on the server.
+ * @param routes - The generated demo routes.
+ * @param demoProviders - The generated import of the `demoProviders` module, if any.
+ * @param options - How the application starts.
+ * @internal
+ */
+declare function ɵngDocDemoApplicationConfig(routes: Routes, demoProviders: NgDocDemoProvidersImport | undefined, options?: ɵNgDocDemoApplicationOptions): Promise<ApplicationConfig>;
+
+/**
+ * Shows the demo of a demo page: the component in the route's `ngDocDemo` data, with the inputs
+ * of the `inputs` query parameter (the JSON of the `inputs` option of the `demo` action).
+ *
+ * The demo application hydrates its server-rendered page, but not the demo: a demo is the user's
+ * component and need not be hydration-safe, and the server renders it without the inputs of the
+ * query, which only the browser has. So the host skips hydration, as documentation pages do for
+ * their content, and the browser renders the demo again.
+ */
+declare class NgDocDemoHostComponent {
+    private readonly route;
+    /** The demo component, or undefined on the page of a demo that does not exist. */
+    protected readonly demo: Type<unknown> | undefined;
+    /** The inputs of the demo. */
+    protected readonly inputs: Record<string, unknown>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgDocDemoHostComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<NgDocDemoHostComponent, "ng-doc-demo-host", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * The `source` of every message the demo application sends to the page that embeds it.
+ * @internal
+ */
+declare const ɵNG_DOC_DEMO_MESSAGE_SOURCE = "ng-doc-demo";
+/**
+ * The message an isolated demo sends to the page that shows it in an iframe whenever the height
+ * of its content changes, so that the iframe takes that height.
+ * @internal
+ */
+interface ɵNgDocDemoSizeMessage {
+    readonly source: typeof ɵNG_DOC_DEMO_MESSAGE_SOURCE;
+    readonly version: 1;
+    readonly type: 'size';
+    /** The height of the demo's content, in CSS pixels, rounded up. */
+    readonly height: number;
+}
+/**
+ * Whether a message is a size message of the demo application.
+ * @param value - The data of a `message` event.
+ * @internal
+ */
+declare function ɵisNgDocDemoSizeMessage(value: unknown): value is ɵNgDocDemoSizeMessage;
+/**
+ * The message an isolated demo sends to the page that shows it in an iframe whenever the background
+ * of its page changes, such as when its theme changes, so that the page can paint the canvas
+ * around the iframe in it.
+ * @internal
+ */
+interface ɵNgDocDemoBackgroundMessage {
+    readonly source: typeof ɵNG_DOC_DEMO_MESSAGE_SOURCE;
+    readonly version: 1;
+    readonly type: 'background';
+    /** The computed background color of the demo's page, such as `rgb(24, 24, 27)`. */
+    readonly color: string;
+    /** The color of the dots of the demo canvas in the demo's theme, if the theme sets one. */
+    readonly dots?: string;
+    /** The color scheme of the demo's page (`dark`, for example), if it sets one. */
+    readonly scheme?: string;
+}
+/**
+ * Whether a message is a background message of the demo application.
+ * @param value - The data of a `message` event.
+ * @internal
+ */
+declare function ɵisNgDocDemoBackgroundMessage(value: unknown): value is ɵNgDocDemoBackgroundMessage;
+
+/**
+ * The theme that the URL fragment of a demo page sets, or `undefined` when it sets none and the
+ * page follows the theme of the site.
+ * @param fragment - The fragment, with or without the leading `#`.
+ * @internal
+ */
+declare function ɵdemoThemeFromFragment(fragment: string): string | undefined;
+/**
+ * A fragment (without `#`) with the theme parameter set, after the other parameters, or without it
+ * when there is no theme. `undefined` when nothing is left.
+ * @param fragment - The fragment without the theme, or none.
+ * @param theme - The theme of the demo page, or none to follow the site.
+ * @internal
+ */
+declare function ɵwithDemoTheme(fragment: string | undefined, theme: string | undefined): string | undefined;
+/**
+ * Whether a parameter of a fragment is the theme of the demo page, which the state of a
+ * playground leaves to the demo application.
+ * @param name - The decoded name of the parameter.
+ * @internal
+ */
+declare function ɵisDemoThemeParameter(name: string): boolean;
+
+/**
+ * The state of an isolated playground that its documentation page passes to the frame.
+ * @internal
+ */
+interface ɵNgDocPlaygroundState {
+    /** The names of the target's inputs, in order: a pipe's parameters are positional. */
+    readonly inputs: readonly string[];
+    /** The value of each input, by name. */
+    readonly properties: Readonly<Record<string, unknown>>;
+    /** The content slots that are shown. */
+    readonly content: readonly string[];
+    /** Whether the frame creates the target again for this state. */
+    readonly recreate: boolean;
+    /**
+     * The `data` option of the playground action, which the template of the target reads; the
+     * frame has the configuration's own `data`.
+     */
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A state written as a URL fragment, or why it can't be: the input whose value can't be encoded,
+ * or an empty `path` when the fragment would be too long.
+ * @internal
+ */
+type ɵNgDocPlaygroundFragment = {
+    readonly ok: true;
+    readonly fragment: string;
+} | {
+    readonly ok: false;
+    readonly path: string;
+    readonly reason: string;
+};
+/**
+ * Writes a state as a URL fragment (without `#`). A string, a finite number or a boolean is its
+ * own readable parameter (`label=Save&size=2&disabled=true`; a string that would read as another
+ * type is quoted as JSON). Every other value goes into one `~v` parameter, encoded by
+ * {@link ɵencodePlaygroundValue}. The frame reads the fragment with
+ * {@link ɵplaygroundStateFromFragment}, and the same fragment opens the page in a new tab.
+ * @param state - The state of the playground.
+ * @internal
+ */
+declare function ɵplaygroundStateToFragment(state: ɵNgDocPlaygroundState): ɵNgDocPlaygroundFragment;
+/**
+ * Reads a state that {@link ɵplaygroundStateToFragment} wrote. Throws on a fragment it can't
+ * have written, so a malformed URL never reaches the target half-read.
+ * @param fragment - The fragment, with or without the leading `#`.
+ * @internal
+ */
+declare function ɵplaygroundStateFromFragment(fragment: string): ɵNgDocPlaygroundState;
+
+/**
+ * A value as it crosses from a documentation page to the frame of an isolated playground: JSON
+ * that both `postMessage` and a URL carry unchanged.
+ * @internal
+ */
+type ɵNgDocPlaygroundEncodedValue = string | number | boolean | null | ɵNgDocPlaygroundEncodedValue[] | {
+    [key: string]: ɵNgDocPlaygroundEncodedValue;
+};
+/**
+ * The result of encoding a value: the encoded value, or the path of the first part that can't be
+ * encoded and why.
+ * @internal
+ */
+type ɵNgDocPlaygroundEncoding = {
+    readonly ok: true;
+    readonly value: ɵNgDocPlaygroundEncodedValue;
+} | {
+    readonly ok: false;
+    readonly path: string;
+    readonly reason: string;
+};
+/**
+ * The longest encoded state an "Open in a new tab" URL carries; a longer one is left out.
+ * @internal
+ */
+declare const ɵNG_DOC_PLAYGROUND_STATE_URL_LIMIT = 8192;
+/**
+ * Encodes a value for the frame of an isolated playground. Only plain data is accepted:
+ * strings, numbers (`NaN`, the infinities and `-0` included), booleans, `null`, `undefined`, `Date`s,
+ * arrays and plain objects (prototype `Object.prototype` or `null`, own enumerable data
+ * properties). Anything else (a function, a symbol, a `bigint`, a class instance such as a
+ * `TemplateRef`, a `Map` or a signal, a getter, a cycle) is refused rather than sent changed: a
+ * structured clone would turn a class instance into a plain object without its behaviour, and
+ * the demo would then run with a value that isn't the one the inspector shows.
+ * @param value - The value of a playground input.
+ * @internal
+ */
+declare function ɵencodePlaygroundValue(value: unknown): ɵNgDocPlaygroundEncoding;
+/**
+ * Decodes a value that {@link ɵencodePlaygroundValue} encoded. Throws on anything it can't have
+ * produced, so a malformed message or URL never reaches the demo half-decoded.
+ * @param value - An encoded value.
+ * @internal
+ */
+declare function ɵdecodePlaygroundValue(value: unknown): unknown;
+/**
+ * The encoded values of an "Open in a new tab" URL: base64url of their JSON, or `undefined`
+ * when it would be longer than {@link ɵNG_DOC_PLAYGROUND_STATE_URL_LIMIT}.
+ * @param values - Encoded values, by input name.
+ * @internal
+ */
+declare function ɵplaygroundStateToUrl(values: Record<string, ɵNgDocPlaygroundEncodedValue>): string | undefined;
+/**
+ * The encoded values of an "Open in a new tab" URL, or `undefined` when the parameter isn't one
+ * that {@link ɵplaygroundStateToUrl} wrote.
+ * @param text - The `state` query parameter.
+ * @internal
+ */
+declare function ɵplaygroundStateFromUrl(text: string): Record<string, ɵNgDocPlaygroundEncodedValue> | undefined;
+
+/**
+ * The message the frame of an isolated playground sends once its target exists: the target's
+ * default input values, encoded, and the inputs whose default can't be encoded.
+ * @internal
+ */
+interface ɵNgDocPlaygroundReadyMessage {
+    readonly source: typeof ɵNG_DOC_DEMO_MESSAGE_SOURCE;
+    readonly version: 1;
+    readonly type: 'playground-ready';
+    readonly defaults: Readonly<Record<string, ɵNgDocPlaygroundEncodedValue>>;
+    readonly uncloneable: readonly string[];
+}
+/**
+ * The message the frame of an isolated playground sends once it has applied the state of its URL
+ * fragment.
+ * @internal
+ */
+interface ɵNgDocPlaygroundAppliedMessage {
+    readonly source: typeof ɵNG_DOC_DEMO_MESSAGE_SOURCE;
+    readonly version: 1;
+    readonly type: 'playground-applied';
+    /** The URL fragment of the state it applied, without `#`. */
+    readonly fragment: string;
+}
+/**
+ * The message the frame of an isolated playground sends when its target throws while it is
+ * created or while it takes a state, or when its URL fragment is malformed.
+ * @internal
+ */
+interface ɵNgDocPlaygroundErrorMessage {
+    readonly source: typeof ɵNG_DOC_DEMO_MESSAGE_SOURCE;
+    readonly version: 1;
+    readonly type: 'playground-error';
+    readonly phase: 'create' | 'apply';
+    readonly message: string;
+}
+/**
+ * A message from the frame of an isolated playground to its documentation page.
+ * @internal
+ */
+type ɵNgDocPlaygroundFrameMessage = ɵNgDocPlaygroundReadyMessage | ɵNgDocPlaygroundAppliedMessage | ɵNgDocPlaygroundErrorMessage;
+/**
+ * Whether a message comes from the frame of an isolated playground, and is one it sends.
+ * @param value - The data of a `message` event.
+ * @internal
+ */
+declare function ɵisNgDocPlaygroundFrameMessage(value: unknown): value is ɵNgDocPlaygroundFrameMessage;
+
+export { NgDocDemoAppComponent, NgDocDemoHostComponent, ɵNG_DOC_DEMO_MESSAGE_SOURCE, ɵNG_DOC_PLAYGROUND_STATE_URL_LIMIT, ɵdecodePlaygroundValue, ɵdemoThemeFromFragment, ɵencodePlaygroundValue, ɵisDemoThemeParameter, ɵisNgDocDemoBackgroundMessage, ɵisNgDocDemoSizeMessage, ɵisNgDocPlaygroundFrameMessage, ɵngDocDemoApplicationConfig, ɵplaygroundStateFromFragment, ɵplaygroundStateFromUrl, ɵplaygroundStateToFragment, ɵplaygroundStateToUrl, ɵwithDemoTheme };
+export type { ɵNgDocDemoApplicationOptions, ɵNgDocDemoBackgroundMessage, ɵNgDocDemoSizeMessage, ɵNgDocPlaygroundAppliedMessage, ɵNgDocPlaygroundEncodedValue, ɵNgDocPlaygroundEncoding, ɵNgDocPlaygroundErrorMessage, ɵNgDocPlaygroundFragment, ɵNgDocPlaygroundFrameMessage, ɵNgDocPlaygroundReadyMessage, ɵNgDocPlaygroundState };

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

@@ -1,6 +1,6 @@
 import { InjectionToken, ApplicationRef, ViewContainerRef, Type } from '@angular/core';
 import { Route } from '@angular/router';
-import { NgDocContentSource, NgDocContentModule, NgDocPlaygroundProperty } from '@ng-doc/core/interfaces';
+import { NgDocContentSource, NgDocContentModule, NgDocPlaygroundProperty, NgDocPlaygroundOption } from '@ng-doc/core/interfaces';
 import { NgDocTocItem } from '@ng-doc/app/interfaces';
 import { LocationStrategy } from '@angular/common';
 
@@ -26,7 +26,8 @@ declare const ɵNG_DOC_CONTENT_WAIT: InjectionToken<number>;
  */
 declare function ɵpreloadNgDocContent(source: NgDocContentSource): Promise<NgDocContentModule>;
 /**
- * Returns the payload of a source that `ɵpreloadNgDocContent` has loaded, without waiting.
+ * Returns the payload of a source that `ɵpreloadNgDocContent` has loaded, or that a development
+ * content update delivered, without waiting.
  * @param source - The content source.
  * @returns The payload, or `undefined` when the source has not finished loading.
  * @internal
@@ -73,6 +74,58 @@ type NgDocBootstrap<TArguments extends unknown[], TApplication extends Applicati
 /** Waits for content loading and processing before returning an SSR application. */
 declare function withNgDocContentReady<TArguments extends unknown[], TApplication extends ApplicationRef = ApplicationRef>(bootstrap: NgDocBootstrap<TArguments, TApplication>): NgDocBootstrap<TArguments, TApplication>;
 
+/**
+ * The detail of an `ɵNG_DOC_CONTENT_UPDATE_EVENT` (`@ng-doc/app/constants`).
+ * @internal
+ */
+interface ɵNgDocContentUpdate {
+    /** The new payload of every changed content module the page may have loaded. */
+    readonly payloads: readonly unknown[];
+    /** Whether the search index changed too. */
+    readonly search: boolean;
+}
+/**
+ * What an update tells the code that shows content.
+ * @internal
+ */
+interface ɵNgDocContentChange {
+    /** The ids of the content modules that changed. */
+    readonly ids: ReadonlySet<string>;
+    /** Whether the search index changed. */
+    readonly search: boolean;
+}
+/**
+ * Applies the content updates of the Vite development host in this window. Every NgDoc content
+ * controller calls it in the browser; it listens once per window. Nothing dispatches the event
+ * outside the development host, so it is inert in production builds, and Angular's production
+ * mode (`ngDevMode` false) skips it altogether.
+ * @param view - The window, if any (none on the server).
+ * @internal
+ */
+declare function ɵlistenNgDocContentUpdates(view: Window | null | undefined): void;
+/**
+ * Calls `listener` with every content update applied in this window.
+ * @param listener - The listener.
+ * @returns A function that stops it.
+ * @internal
+ */
+declare function ɵwatchNgDocContentUpdates(listener: (change: ɵNgDocContentChange) => void): () => void;
+/**
+ * The newest payload an update delivered for a content module.
+ * @param id - The content module id.
+ * @returns The payload, or `undefined` when no update changed the module.
+ * @internal
+ */
+declare function ɵupdatedNgDocContent(id: string): NgDocContentModule | undefined;
+/**
+ * Loads a content source: its newest updated payload, if an update delivered one, or the source.
+ * @param source - The content source.
+ * @param signal - Aborts the load.
+ * @returns The payload.
+ * @internal
+ */
+declare function ɵloadNgDocContent(source: NgDocContentSource, signal: AbortSignal): Promise<NgDocContentModule>;
+
 /**
  *
  * @param viewContainer
@@ -166,5 +219,23 @@ declare function ɵngDocRouteUrl(locationStrategy: LocationStrategy, documentUrl
  */
 declare function ɵngDocPageUrl(locationStrategy: LocationStrategy, location: Pick<Location, 'href' | 'origin' | 'pathname'>, fragment?: string): string;
 
-export { asBoolean, createComponent, formatHtml, generateToc, isDarkOsTheme, isExternalLink, isPlaygroundProperty, withNgDocContentReady, ɵNG_DOC_ASYNC_CONTENT_ATTRIBUTE, ɵNG_DOC_CONTENT_WAIT, ɵcaptureNgDocHydrationSnapshots, ɵforgetNgDocContent, ɵngDocPageUrl, ɵngDocRouteContentSources, ɵngDocRouteUrl, ɵpeekNgDocContent, ɵpendingNgDocContent, ɵpreloadNgDocContent, ɵrestoreNgDocHydrationSnapshot, ɵwithNgDocContent };
-export type { NgDocBootstrap };
+/** An option of a playground property, resolved to the value it sets and the text it shows. */
+interface NgDocResolvedPlaygroundOption {
+    /** The text shown for the option. */
+    label: string;
+    /** The value the option sets. */
+    value: unknown;
+}
+/**
+ * Resolves an option of a playground property. A named option (an enum member) carries its
+ * value; a plain value from the playground's `controls` is the value itself; any other option is
+ * the source text of a union member, such as `'small'`, and is evaluated; it throws when that
+ * text can't be evaluated.
+ * @param option - The option.
+ * @param isManual - Whether the options come from the playground's `controls`.
+ * @returns The value of the option and the text that shows it.
+ */
+declare function resolvePlaygroundOption(option: string | NgDocPlaygroundOption, isManual?: boolean): NgDocResolvedPlaygroundOption;
+
+export { asBoolean, createComponent, formatHtml, generateToc, isDarkOsTheme, isExternalLink, isPlaygroundProperty, resolvePlaygroundOption, withNgDocContentReady, ɵNG_DOC_ASYNC_CONTENT_ATTRIBUTE, ɵNG_DOC_CONTENT_WAIT, ɵcaptureNgDocHydrationSnapshots, ɵforgetNgDocContent, ɵlistenNgDocContentUpdates, ɵloadNgDocContent, ɵngDocPageUrl, ɵngDocRouteContentSources, ɵngDocRouteUrl, ɵpeekNgDocContent, ɵpendingNgDocContent, ɵpreloadNgDocContent, ɵrestoreNgDocHydrationSnapshot, ɵupdatedNgDocContent, ɵwatchNgDocContentUpdates, ɵwithNgDocContent };
+export type { NgDocBootstrap, NgDocResolvedPlaygroundOption, ɵNgDocContentChange, ɵNgDocContentUpdate };