@ng-doc/app 22.1.0 → 22.2.0

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

@@ -7,7 +7,11 @@ 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`.
+ * 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();
@@ -84,6 +88,210 @@ interface ɵNgDocDemoSizeMessage {
  * @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, ɵisNgDocDemoSizeMessage, ɵngDocDemoApplicationConfig };
-export type { ɵNgDocDemoApplicationOptions, ɵNgDocDemoSizeMessage };
+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

@@ -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
@@ -184,5 +237,5 @@ interface NgDocResolvedPlaygroundOption {
  */
 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, ɵngDocPageUrl, ɵngDocRouteContentSources, ɵngDocRouteUrl, ɵpeekNgDocContent, ɵpendingNgDocContent, ɵpreloadNgDocContent, ɵrestoreNgDocHydrationSnapshot, ɵwithNgDocContent };
-export type { NgDocBootstrap, 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 };