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

package/dist/api-page/pipe-usage.d.ts

@@ -0,0 +1,13 @@
+import type { ScannedPipe } from '@ng-prism/core/plugin';
+/**
+ * The snippet that shows how to use a pipe: the imports, the `providers`
+ * entries its setup asks for, the component's `imports` entry and a template
+ * line. Imports and setup are written as for a service.
+ *
+ * Like the service snippet it is generated and says nothing about values: the
+ * template line names the piped value `value` and each argument by its
+ * parameter name. It shows the first signature that is not `@deprecated`, the
+ * way a new template should call the pipe, or the first one when all are.
+ */
+export declare function generatePipeUsage(pipe: ScannedPipe): string;
+//# sourceMappingURL=pipe-usage.d.ts.map

package/dist/api-page/pipe-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipe-usage.d.ts","sourceRoot":"","sources":["../../src/api-page/pipe-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGpE;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAU3D"}

package/dist/api-page/pipe-usage.js

@@ -0,0 +1,35 @@
+import { importLines, joinUsageBlocks, setupBlock, setupImports } from './service-usage.js';
+/**
+ * The snippet that shows how to use a pipe: the imports, the `providers`
+ * entries its setup asks for, the component's `imports` entry and a template
+ * line. Imports and setup are written as for a service.
+ *
+ * Like the service snippet it is generated and says nothing about values: the
+ * template line names the piped value `value` and each argument by its
+ * parameter name. It shows the first signature that is not `@deprecated`, the
+ * way a new template should call the pipe, or the first one when all are.
+ */
+export function generatePipeUsage(pipe) {
+    const { className, pipeName, api } = pipe;
+    const signature = api.transform.find((method) => !method.tags.deprecated) ?? api.transform[0];
+    return joinUsageBlocks([
+        importLines(pipe, setupImports(api.setup)),
+        setupBlock(api.setup),
+        ['// in the component that uses it', `@Component({ imports: [${className}], … })`],
+        ['// in its template', `{{ value | ${pipeName}${pipeArguments(signature)} }}`]
+    ]);
+}
+/**
+ * The arguments of the template line, from a signature's parameters after the
+ * piped value: `: pattern` for each one the call has to pass. Pipe arguments
+ * are positional, so what can be left out is the optional and rest parameters
+ * at the end; one with a default that a required parameter follows stays in.
+ */
+function pipeArguments(signature) {
+    const params = signature?.params.slice(1) ?? [];
+    const lastRequired = params.map((param) => !param.optional && !param.rest).lastIndexOf(true);
+    return params
+        .slice(0, lastRequired + 1)
+        .map((param) => `: ${param.name}`)
+        .join('');
+}

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

@@ -0,0 +1,31 @@
+import type { ApiSetupEntry, ScannedService } from '@ng-prism/core/plugin';
+/** A name an import line brings in, and the module it comes from. */
+export interface UsageImport {
+    name: string;
+    from: string;
+}
+/**
+ * The snippet that shows how to bring a service into an application: the
+ * imports, the `providers` entries its setup asks for, and the `inject()` call.
+ *
+ * It is generated from the scanned API, not taken from the author, so it says
+ * nothing about values: a setup function's arguments and a token's value are
+ * left as `…` for the reader to fill in.
+ */
+export declare function generateServiceUsage(service: ScannedService): string;
+/**
+ * One line per entry point, the class's first, each naming the class before
+ * the `extra` names it shares a module with. Shared with the pipe and the
+ * component snippet.
+ */
+export declare function importLines({ className, importPath }: {
+    className: string;
+    importPath?: string;
+}, extra?: UsageImport[]): string[];
+/** What the setup entries of a service or pipe import. Shared with the pipe snippet. */
+export declare function setupImports(setup: ApiSetupEntry[]): UsageImport[];
+/** The `app.config.ts` block with one `providers` entry per setup entry, or nothing without setup. Shared with the pipe snippet. */
+export declare function setupBlock(setup: ApiSetupEntry[]): string[];
+/** The blocks of a snippet, each a list of lines, with a blank line between them; an empty block is left out. */
+export declare function joinUsageBlocks(blocks: string[][]): string;
+//# sourceMappingURL=service-usage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service-usage.d.ts","sourceRoot":"","sources":["../../src/api-page/service-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE3E,qEAAqE;AACrE,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAmBpE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,GAAE,WAAW,EAAO,GAAG,MAAM,EAAE,CAStI;AAED,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,WAAW,EAAE,CAElE;AAED,oIAAoI;AACpI,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAG3D;AAED,iHAAiH;AACjH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,CAK1D"}

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

@@ -0,0 +1,66 @@
+/**
+ * The snippet that shows how to bring a service into an application: the
+ * imports, the `providers` entries its setup asks for, and the `inject()` call.
+ *
+ * It is generated from the scanned API, not taken from the author, so it says
+ * nothing about values: a setup function's arguments and a token's value are
+ * left as `…` for the reader to fill in.
+ */
+export function generateServiceUsage(service) {
+    const { className, provision, api } = service;
+    const variable = className.charAt(0).toLowerCase() + className.slice(1);
+    const blocks = [importLines(service, setupImports(api.setup)), setupBlock(api.setup)];
+    // A setup function of a service provided by hand normally provides it; a token never does.
+    if (provision === 'manual' && !api.setup.some((entry) => entry.kind === 'function')) {
+        blocks.push([
+            '// the component that uses it',
+            `@Component({ …, providers: [${className}] })`,
+            'export class MyComponent {',
+            `    private readonly ${variable} = inject(${className});`,
+            '}'
+        ]);
+    }
+    else {
+        blocks.push(['// in a component or service', `private readonly ${variable} = inject(${className});`]);
+    }
+    return joinUsageBlocks(blocks);
+}
+/**
+ * One line per entry point, the class's first, each naming the class before
+ * the `extra` names it shares a module with. Shared with the pipe and the
+ * component snippet.
+ */
+export function importLines({ className, importPath }, extra = []) {
+    const groups = new Map();
+    const add = (path, name) => groups.set(path, [...(groups.get(path) ?? []), name]);
+    // A class the scanner could not place has no import path; there is nothing true to write for it.
+    if (importPath)
+        add(importPath, className);
+    for (const { name, from } of extra)
+        add(from, name);
+    return [...groups].map(([path, names]) => `import { ${names.join(', ')} } from '${path}';`);
+}
+/** What the setup entries of a service or pipe import. Shared with the pipe snippet. */
+export function setupImports(setup) {
+    return setup.map(({ name, importPath }) => ({ name, from: importPath }));
+}
+/** The `app.config.ts` block with one `providers` entry per setup entry, or nothing without setup. Shared with the pipe snippet. */
+export function setupBlock(setup) {
+    if (!setup.length)
+        return [];
+    return ['// app.config.ts', `providers: [${setup.map(providerEntry).join(', ')}]`];
+}
+/** The blocks of a snippet, each a list of lines, with a blank line between them; an empty block is left out. */
+export function joinUsageBlocks(blocks) {
+    return blocks
+        .filter((lines) => lines.length)
+        .map((lines) => lines.join('\n'))
+        .join('\n\n');
+}
+function providerEntry(entry) {
+    if (entry.kind === 'token')
+        return `{ provide: ${entry.name}, useValue: … }`;
+    // A rest parameter can be left out as well as an optional one.
+    const callableBare = (entry.params ?? []).every((param) => param.optional || param.rest);
+    return `${entry.name}(${callableBare ? '' : '…'})`;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"jsdoc-extractor.d.ts","sourceRoot":"","sources":["../src/jsdoc-extractor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAkC,MAAM,kBAAkB,CAAC;AAElF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAO,GAAG,SAAS,GAAG,IAAI,CAyBnJ"}
+{"version":3,"file":"jsdoc-extractor.d.ts","sourceRoot":"","sources":["../src/jsdoc-extractor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAkC,MAAM,kBAAkB,CAAC;AAElF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAO,GAAG,SAAS,GAAG,IAAI,CAenJ"}

package/dist/jsdoc-extractor.js

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
 import ts from 'typescript';
 /**
  * `baseClasses` come from the scanner, nearest first. Members are read from
@@ -6,15 +6,7 @@ import ts from 'typescript';
  * member decides its tags, as a redeclaration replaces the inherited one.
  */
 export function extractJsDocData(filePath, className, baseClasses = []) {
-    const sourceFiles = new Map();
-    const findClass = (path, name) => {
-        let sourceFile = sourceFiles.get(path);
-        if (!sourceFile) {
-            sourceFile = ts.createSourceFile(path, readFileSync(path, 'utf-8'), ts.ScriptTarget.ES2022, true);
-            sourceFiles.set(path, sourceFile);
-        }
-        return findClassByName(sourceFile, name);
-    };
+    const findClass = (path, name) => findClassByName(parseFile(path), name);
     const classDecl = findClass(filePath, className);
     if (!classDecl)
         return null;
@@ -26,6 +18,21 @@ export function extractJsDocData(filePath, className, baseClasses = []) {
         methods: extractPublicMethods(hierarchy)
     };
 }
+/**
+ * The files parsed so far, with the size and modification time they had then.
+ * `serve` runs the hook for every component again on each change in the
+ * library, so a file that has not changed since is neither read nor parsed again.
+ */
+const parsedFiles = new Map();
+function parseFile(path) {
+    const { mtimeMs, size } = statSync(path);
+    const cached = parsedFiles.get(path);
+    if (cached?.mtimeMs === mtimeMs && cached.size === size)
+        return cached.sourceFile;
+    const sourceFile = ts.createSourceFile(path, readFileSync(path, 'utf-8'), ts.ScriptTarget.ES2022, true);
+    parsedFiles.set(path, { mtimeMs, size, sourceFile });
+    return sourceFile;
+}
 function findClassByName(sourceFile, className) {
     let found = null;
     function visit(node) {

package/dist/jsdoc-panel.component.d.ts

@@ -1,31 +1,14 @@
-import { SafeHtml } from '@angular/platform-browser';
-import type { InputMeta, OutputMeta } from '@ng-prism/core/plugin';
-import type { JsDocData, MethodDoc } from './jsdoc.types.js';
-import { type ParsedExample } from './markdown.js';
+import { type ApiPageModel } from './api-page/api-page.model.js';
 import * as i0 from "@angular/core";
 export declare class JsDocPanelComponent {
     readonly activeComponent: import("@angular/core").InputSignal<unknown>;
-    private readonly sanitizer;
-    protected readonly jsdocData: import("@angular/core").Signal<JsDocData | null>;
-    protected readonly inputs: import("@angular/core").Signal<InputMeta[]>;
-    protected readonly outputs: import("@angular/core").Signal<OutputMeta[]>;
-    protected readonly classDescription: import("@angular/core").Signal<string | undefined>;
-    protected readonly renderedClassDescription: import("@angular/core").Signal<SafeHtml | null>;
-    protected readonly classTags: import("@angular/core").Signal<import("./jsdoc.types.js").JsDocTags>;
-    protected readonly isDeprecated: import("@angular/core").Signal<boolean>;
-    protected readonly deprecatedMessage: import("@angular/core").Signal<string | undefined>;
-    protected readonly since: import("@angular/core").Signal<string | undefined>;
-    protected readonly version: import("@angular/core").Signal<string | undefined>;
-    protected readonly seeRefs: import("@angular/core").Signal<string[]>;
-    protected readonly examples: import("@angular/core").Signal<string[]>;
-    protected readonly methods: import("@angular/core").Signal<MethodDoc[]>;
-    protected readonly hasTags: import("@angular/core").Signal<boolean>;
-    protected isMemberDeprecated(name: string): boolean;
-    protected getMemberSince(name: string): string | undefined;
-    protected renderInline(text: string | undefined): SafeHtml;
-    protected parseExample(raw: string): ParsedExample;
-    protected formatDefault(value: unknown): string;
+    /** Set on a service page, where `activeComponent` is `null`. */
+    readonly activeService: import("@angular/core").InputSignal<unknown>;
+    /** Set on a pipe page, where `activeComponent` is `null`. */
+    readonly activePipe: import("@angular/core").InputSignal<unknown>;
+    /** The API page of whatever is on screen; `null` when nothing is selected. */
+    protected readonly apiPage: import("@angular/core").Signal<ApiPageModel | null>;
     static ɵfac: i0.ɵɵFactoryDeclaration<JsDocPanelComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<JsDocPanelComponent, "prism-jsdoc-panel", never, { "activeComponent": { "alias": "activeComponent"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<JsDocPanelComponent, "prism-jsdoc-panel", never, { "activeComponent": { "alias": "activeComponent"; "required": false; "isSignal": true; }; "activeService": { "alias": "activeService"; "required": false; "isSignal": true; }; "activePipe": { "alias": "activePipe"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 //# sourceMappingURL=jsdoc-panel.component.d.ts.map

package/dist/jsdoc-panel.component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsdoc-panel.component.d.ts","sourceRoot":"","sources":["../src/jsdoc-panel.component.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,KAAK,aAAa,EAA2D,MAAM,eAAe,CAAC;;AAE5G,qBAQa,mBAAmB;IAC5B,QAAQ,CAAC,eAAe,+CAAwB;IAEhD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAElD,SAAS,CAAC,QAAQ,CAAC,SAAS,mDAIzB;IAEH,SAAS,CAAC,QAAQ,CAAC,MAAM,8CAItB;IAEH,SAAS,CAAC,QAAQ,CAAC,OAAO,+CAIvB;IAEH,SAAS,CAAC,QAAQ,CAAC,gBAAgB,qDAAsD;IAIzF,SAAS,CAAC,QAAQ,CAAC,wBAAwB,kDAIxC;IAEH,SAAS,CAAC,QAAQ,CAAC,SAAS,uEAAqD;IAEjF,SAAS,CAAC,QAAQ,CAAC,YAAY,0CAAiD;IAEhF,SAAS,CAAC,QAAQ,CAAC,iBAAiB,qDAIjC;IAEH,SAAS,CAAC,QAAQ,CAAC,KAAK,qDAA0C;IAElE,SAAS,CAAC,QAAQ,CAAC,OAAO,qDAA4C;IAEtE,SAAS,CAAC,QAAQ,CAAC,OAAO,2CAA8C;IAExE,SAAS,CAAC,QAAQ,CAAC,QAAQ,2CAAkD;IAE7E,SAAS,CAAC,QAAQ,CAAC,OAAO,8CAAgE;IAE1F,SAAS,CAAC,QAAQ,CAAC,OAAO,0CAA0G;IAEpI,SAAS,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAInD,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI1D,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ;IAI1D,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa;IAIlD,SAAS,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;yCAvEtC,mBAAmB;2CAAnB,mBAAmB;CA2E/B"}
+{"version":3,"file":"jsdoc-panel.component.d.ts","sourceRoot":"","sources":["../src/jsdoc-panel.component.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,YAAY,EAA2C,MAAM,8BAA8B,CAAC;;AAG1G,qBAQa,mBAAmB;IAC5B,QAAQ,CAAC,eAAe,+CAAwB;IAChD,gEAAgE;IAChE,QAAQ,CAAC,aAAa,+CAAwB;IAC9C,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,+CAAwB;IAE3C,8EAA8E;IAC9E,SAAS,CAAC,QAAQ,CAAC,OAAO,sDAQvB;yCAhBM,mBAAmB;2CAAnB,mBAAmB;CAiB/B"}