@ng-prism/plugin-jsdoc 22.6.0 → 22.7.0-beta.0

package/dist/api-page/doc-links.js

@@ -0,0 +1,45 @@
+import { typeAnchor } from './api-page.helpers.js';
+/** A `{@link}` tag: the target ends at a space, a bar or the brace, the text follows after a bar or after a space. */
+const LINK_TAG = /\{@(?:link|linkcode|linkplain)\s+([^\s|}]+)\s*(?:\|\s*)?([^}]*)\}/g;
+/** A Markdown code span: a run of backticks up to the next run of the same length. */
+const CODE_SPAN = /(?<!`)(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/g;
+const URL_TARGET = /^[a-z][a-z\d+.-]*:/i;
+/** Marks the button of a link, so the page can find it in rendered `innerHTML` that Angular does not bind. */
+export const TYPE_LINK_ATTRIBUTE = 'data-prism-type-link';
+/**
+ * The TOC anchor of the type card a doc reference names: by id, then by name;
+ * `X.y` and `X#y` name `X`. A page holds two types of one name only under
+ * different ids, so an exact id is what tells them apart.
+ */
+export function typeLinkTarget(types, target) {
+    const named = (name) => (types.find((type) => type.id === name) ?? types.find((type) => type.name === name))?.id;
+    const id = named(target) ?? named(target.split(/[.#]/, 1)[0]);
+    return id === undefined ? undefined : typeAnchor(id);
+}
+/**
+ * Rewrites `{@link}`, `{@linkcode}` and `{@linkplain}` into what the Markdown renderer shows: a button to the type card
+ * `resolve` names, a Markdown link for a URL target, inline code (or the link text) otherwise. Code spans stay as written.
+ */
+export function resolveDocLinks(text, resolve) {
+    let result = '';
+    let end = 0;
+    for (const span of text.matchAll(CODE_SPAN)) {
+        result += rewriteLinks(text.slice(end, span.index), resolve) + span[0];
+        end = span.index + span[0].length;
+    }
+    return result + rewriteLinks(text.slice(end), resolve);
+}
+function rewriteLinks(text, resolve) {
+    return text.replace(LINK_TAG, (_tag, target, linkText) => {
+        const label = linkText.trim();
+        if (URL_TARGET.test(target))
+            return `[${label || target}](${target})`;
+        const anchor = resolve(target);
+        if (anchor === undefined)
+            return label || `\`${target}\``;
+        return `<button type="button" class="prism-jsdoc-api-page__ref" ${TYPE_LINK_ATTRIBUTE}="${escapeHtml(anchor)}">${escapeHtml(label || target)}</button>`;
+    });
+}
+function escapeHtml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}

package/dist/api-page/jsdoc-api-page.component.d.ts

@@ -0,0 +1,98 @@
+import { SafeHtml } from '@angular/platform-browser';
+import type { ApiDocTags, ApiMethod, ApiProperty, ApiTypeDoc } from '@ng-prism/core/plugin';
+import { type ParsedExample } from '../markdown.js';
+import { documentsParams, splitReachedFrom, typeAnchor } from './api-page.helpers.js';
+import type { ApiOutputRow, ApiPageModel } from './api-page.model.js';
+import * as i0 from "@angular/core";
+/**
+ * The API page of a component, a directive, a service or a pipe: what it is,
+ * how to bring it in, what it offers and the types its API reaches, with an
+ * "On this page" list next to it. It renders an `ApiPageModel`, so all four
+ * kinds share one look.
+ *
+ * The host is the scroll container (the panel stylesheet gives it `overflow:
+ * auto`), so every jump scrolls it, never the window or the shell around it.
+ *
+ * It also carries a render marker, the class name of what it shows:
+ * `data-prism-component-rendered` on a component or directive page,
+ * `data-prism-service-rendered` on a service page, `data-prism-pipe-rendered`
+ * on a pipe page. Exactly one of the three is set, the others are absent. Host
+ * bindings update in the same pass as the template, so the marker names a
+ * class only once its page is in the DOM, which is what an outside tool such
+ * as the showcase skill's screenshot script waits for.
+ */
+export declare class JsDocApiPageComponent {
+    readonly page: import("@angular/core").InputSignal<ApiPageModel>;
+    private readonly sanitizer;
+    private readonly host;
+    /** Kind and class name, not the page object: a manifest update during `serve` hands over a new page for the same class. */
+    protected readonly kind: import("@angular/core").Signal<import("./api-page.model.js").ApiPageKind>;
+    protected readonly className: import("@angular/core").Signal<string>;
+    protected readonly inputs: import("@angular/core").Signal<import("./api-page.model.js").ApiInputRow[]>;
+    protected readonly outputs: import("@angular/core").Signal<ApiOutputRow[]>;
+    protected readonly serviceProperties: import("@angular/core").Signal<ApiProperty[]>;
+    protected readonly pageMethods: import("@angular/core").Signal<ApiMethod[]>;
+    protected readonly transformSignatures: import("@angular/core").Signal<ApiMethod[]>;
+    protected readonly toc: import("@angular/core").Signal<import("./api-page.helpers.js").TocEntry[]>;
+    protected readonly renderedDescription: import("@angular/core").Signal<SafeHtml | null>;
+    protected readonly activeId: import("@angular/core").WritableSignal<string>;
+    protected readonly highlightedId: import("@angular/core").WritableSignal<string | null>;
+    protected readonly copied: import("@angular/core").WritableSignal<boolean>;
+    protected readonly segmentsOf: (key: import("@ng-prism/core/plugin").ApiTypeRef) => import("./api-page.helpers.js").TypeSegment[];
+    protected readonly declaredParamSegmentsOf: (key: import("@ng-prism/core/plugin").ApiParam) => import("./api-page.helpers.js").TypeSegment[];
+    protected readonly signatureOf: (key: import("@ng-prism/core/plugin").ApiSetupEntry) => import("./api-page.helpers.js").TypeSegment[];
+    protected readonly documentsParams: typeof documentsParams;
+    protected readonly splitReachedFrom: typeof splitReachedFrom;
+    protected readonly typeAnchor: typeof typeAnchor;
+    /**
+     * The rendered descriptions of the page being shown. A link resolves against
+     * that page's types, so the caches go with the page: this instance outlives
+     * a switch to another component, service or pipe, and the HTML of its
+     * texts must not outlive the page they were rendered for.
+     */
+    private readonly rendered;
+    /**
+     * The entry the reader jumped to, until the jump is over: the smooth scroll
+     * passes other sections on its way, and one near the bottom of the page is
+     * never scrolled up to the activation line.
+     */
+    private jumpTarget;
+    private spyFrame;
+    private jumpTimer?;
+    private highlightTimer?;
+    private copiedTimer?;
+    constructor();
+    /** Scroll to a section or a type card; a type card lights up briefly so the eye finds it. */
+    protected goTo(id: string): void;
+    protected copyUsage(): void;
+    protected isDeprecated(tags: ApiDocTags): boolean;
+    protected deprecatedMessage(tags: ApiDocTags): string | undefined;
+    protected renderBlock(text: string | undefined): SafeHtml | null;
+    protected renderInline(text: string): SafeHtml;
+    /** The TOC anchor of the type card a `@see` reference names, if it is on the page. */
+    protected seeTarget(reference: string): string | undefined;
+    protected parseExample(raw: string): ParsedExample;
+    /** An interface or object type says what may be left out; a class property has nothing to require. */
+    protected isRequired(property: ApiProperty, owner?: ApiTypeDoc): boolean;
+    protected hasDefaults(properties: ApiProperty[]): boolean;
+    /** The scanner reads an output's payload from the source; without it the column would be empty. */
+    protected hasPayloads(outputs: ApiOutputRow[]): boolean;
+    protected hasParams(methods: ApiMethod[]): boolean;
+    protected hasValues(type: ApiTypeDoc): boolean;
+    /** The links inside rendered descriptions are plain HTML, so one listener on the host catches them all. */
+    protected onHostClick(event: MouseEvent): void;
+    private withLinks;
+    private onScroll;
+    /**
+     * The jump is over: from here on the scroll position decides. The entry
+     * stays as it is until the next scroll moves the page, so a frame still
+     * pending from the jump is dropped rather than allowed to overrule it.
+     */
+    private endJump;
+    private anchors;
+    private offsetOf;
+    private sectionInView;
+    static ɵfac: i0.ɵɵFactoryDeclaration<JsDocApiPageComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<JsDocApiPageComponent, "prism-jsdoc-api-page", never, { "page": { "alias": "page"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+//# sourceMappingURL=jsdoc-api-page.component.d.ts.map

package/dist/api-page/jsdoc-api-page.component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsdoc-api-page.component.d.ts","sourceRoot":"","sources":["../../src/api-page/jsdoc-api-page.component.ts"],"names":[],"mappings":"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"}