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

package/dist/jsdoc-plugin.browser.js

@@ -7,8 +7,8 @@ export function jsDocPlugin() {
                 label: 'API',
                 icon: 'file-text',
                 loadComponent: () => import('./jsdoc-panel.component.js').then((m) => m.JsDocPanelComponent),
-                position: 'bottom',
-                placement: 'view'
+                placement: 'view',
+                appliesTo: ['component', 'service', 'pipe']
             }
         ]
     };

package/dist/jsdoc-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsdoc-plugin.d.ts","sourceRoot":"","sources":["../src/jsdoc-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,wBAAgB,WAAW,IAAI,aAAa,CAyB3C"}
+{"version":3,"file":"jsdoc-plugin.d.ts","sourceRoot":"","sources":["../src/jsdoc-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,wBAAgB,WAAW,IAAI,aAAa,CA4B3C"}

package/dist/jsdoc-plugin.js

@@ -2,6 +2,8 @@ import { extractJsDocData } from './jsdoc-extractor.js';
 export function jsDocPlugin() {
     return {
         name: '@ng-prism/plugin-jsdoc',
+        // The API page reads `ScannedComponent.api`, which the scan only reads for a plugin that asks for it.
+        componentApi: true,
         async onComponentScanned(component) {
             const jsdoc = extractJsDocData(component.filePath, component.className, component.baseClasses);
             if (!jsdoc)
@@ -20,7 +22,8 @@ export function jsDocPlugin() {
                 label: 'API',
                 icon: 'file-text',
                 loadComponent: () => import('./jsdoc-panel.component.js').then((m) => m.JsDocPanelComponent),
-                position: 'bottom'
+                placement: 'view',
+                appliesTo: ['component', 'service', 'pipe']
             }
         ]
     };

package/dist/service-page/api-page.model.d.ts

@@ -0,0 +1,35 @@
+import type { ApiMethod, ApiProperty, ApiSetupEntry, ApiTypeDoc, ScannedPipe, ScannedService } from '@ng-prism/core/plugin';
+/** A chip under the description, `Since: 1.2.0` or a bare `Pure`; the deprecation is a badge of its own. */
+export interface ApiPageChip {
+    label: string;
+    value?: string;
+    deprecated?: true;
+}
+/**
+ * What the API page shows, for a service or a pipe. The page renders this
+ * alone, so a pipe page and a service page share one look; the sections a
+ * kind does not have are left out.
+ *
+ * The entries are the scanned objects themselves, not copies: the page caches
+ * what it derives from them by object.
+ */
+export interface ApiPageModel {
+    kind: 'service' | 'pipe';
+    className: string;
+    description?: string;
+    chips: ApiPageChip[];
+    see: string[];
+    usage: string;
+    setup: ApiSetupEntry[];
+    examples: string[];
+    /** Services only. */
+    properties?: ApiProperty[];
+    /** Services: the public methods. */
+    methods?: ApiMethod[];
+    /** Pipes: one entry per transform signature. */
+    transform?: ApiMethod[];
+    types: ApiTypeDoc[];
+}
+export declare function servicePage(service: ScannedService): ApiPageModel;
+export declare function pipePage(pipe: ScannedPipe): ApiPageModel;
+//# sourceMappingURL=api-page.model.d.ts.map

package/dist/service-page/api-page.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-page.model.d.ts","sourceRoot":"","sources":["../../src/service-page/api-page.model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAIxI,4GAA4G;AAC5G,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,IAAI,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,qBAAqB;IACrB,UAAU,CAAC,EAAE,WAAW,EAAE,CAAC;IAC3B,oCAAoC;IACpC,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IACtB,gDAAgD;IAChD,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;IACxB,KAAK,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,CAqBjE;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,YAAY,CAsBxD"}

package/dist/service-page/api-page.model.js

@@ -0,0 +1,54 @@
+import { generatePipeUsage } from './pipe-usage.js';
+import { generateServiceUsage } from './service-usage.js';
+export function servicePage(service) {
+    const { className, importPath, provision, api } = service;
+    return {
+        kind: 'service',
+        className,
+        description: api.description,
+        chips: [
+            ...deprecationChip(api.tags),
+            ...valueChip('Since', api.tags.since),
+            { label: 'Provided in', value: provision === 'auto' ? 'root/automatically' : 'providers' },
+            ...valueChip('Entry point', importPath)
+        ],
+        see: api.tags.see ?? [],
+        usage: generateServiceUsage(service),
+        setup: api.setup,
+        examples: api.tags.example ?? [],
+        properties: api.properties,
+        methods: api.methods,
+        types: api.types
+    };
+}
+export function pipePage(pipe) {
+    const { className, importPath, pipeName, pure, api } = pipe;
+    return {
+        kind: 'pipe',
+        className,
+        description: api.description,
+        chips: [
+            ...deprecationChip(api.tags),
+            { label: 'Pipe', value: pipeName },
+            // Unreadable purity is no reason to guess: the chip goes.
+            ...(pure === undefined ? [] : [{ label: pure ? 'Pure' : 'Impure' }]),
+            ...valueChip('Since', api.tags.since),
+            ...valueChip('Entry point', importPath)
+        ],
+        see: api.tags.see ?? [],
+        usage: generatePipeUsage(pipe),
+        setup: api.setup,
+        examples: api.tags.example ?? [],
+        transform: api.transform,
+        types: api.types
+    };
+}
+/** The deprecation leads the chips, with its message when the tag has one. */
+function deprecationChip({ deprecated }) {
+    if (!deprecated)
+        return [];
+    return [{ label: 'Deprecated', ...(typeof deprecated === 'string' ? { value: deprecated } : {}), deprecated: true }];
+}
+function valueChip(label, value) {
+    return value ? [{ label, value }] : [];
+}

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

@@ -0,0 +1,82 @@
+import { SafeHtml } from '@angular/platform-browser';
+import type { ApiDocTags, ApiMethod, ApiProperty, ApiTypeDoc } from '@ng-prism/core/plugin';
+import { type ParsedExample } from '../markdown.js';
+import type { ApiPageModel } from './api-page.model.js';
+import { documentsParams, splitReachedFrom, typeAnchor } from './service-page.model.js';
+import * as i0 from "@angular/core";
+/**
+ * The API page of 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 both 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-service-rendered` on a service page, `data-prism-pipe-rendered`
+ * on a pipe page, the other one 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 JsDocServicePageComponent {
+    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<"service" | "pipe">;
+    protected readonly className: import("@angular/core").Signal<string>;
+    protected readonly serviceProperties: import("@angular/core").Signal<ApiProperty[]>;
+    protected readonly serviceMethods: import("@angular/core").Signal<ApiMethod[]>;
+    protected readonly transformSignatures: import("@angular/core").Signal<ApiMethod[]>;
+    protected readonly toc: import("@angular/core").Signal<import("./service-page.model.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("./service-page.model.js").TypeSegment[];
+    protected readonly declaredParamSegmentsOf: (key: import("@ng-prism/core/plugin").ApiParam) => import("./service-page.model.js").TypeSegment[];
+    protected readonly signatureOf: (key: import("@ng-prism/core/plugin").ApiSetupEntry) => import("./service-page.model.js").TypeSegment[];
+    protected readonly documentsParams: typeof documentsParams;
+    protected readonly splitReachedFrom: typeof splitReachedFrom;
+    protected readonly typeAnchor: typeof typeAnchor;
+    private readonly blockHtml;
+    private readonly inlineHtml;
+    /**
+     * 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;
+    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;
+    protected hasParams(methods: ApiMethod[]): boolean;
+    protected hasValues(type: ApiTypeDoc): boolean;
+    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<JsDocServicePageComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<JsDocServicePageComponent, "prism-jsdoc-service-page", never, { "page": { "alias": "page"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+//# sourceMappingURL=jsdoc-service-page.component.d.ts.map

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

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