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

package/dist/service-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/service-page/pipe-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipe-usage.d.ts","sourceRoot":"","sources":["../../src/service-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/service-page/pipe-usage.js

@@ -0,0 +1,35 @@
+import { importLines, joinUsageBlocks, setupBlock } 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),
+        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/service-page/service-page.model.d.ts

@@ -0,0 +1,78 @@
+import type { ApiParam, ApiSetupEntry, ApiTypeRef } from '@ng-prism/core/plugin';
+import type { ApiPageModel } from './api-page.model.js';
+/** One entry of the API page's "On this page" list. `id` names the section, `level` 2 is a type below "Types". */
+export interface TocEntry {
+    id: string;
+    label: string;
+    level: 1 | 2;
+}
+/** A piece of a type as written; `link` is the TOC id of the documented type the piece names. */
+export interface TypeSegment {
+    text: string;
+    link?: string;
+}
+/** The TOC id of a documented type's card. */
+export declare function typeAnchor(typeId: string): string;
+/**
+ * The sections of an API page in the order the page shows them. Usage is
+ * always there, being generated; any other section only when it has content.
+ * A service has properties and methods, a pipe its transform signatures.
+ */
+export declare function buildApiPageToc(page: ApiPageModel): TocEntry[];
+/** Where the page is scrolled to, and where each anchor of the "On this page" list sits on it. */
+export interface ScrollSpyState {
+    /** The TOC id of each anchor in page order, with its offset from the top of the scrolled content. */
+    anchors: readonly {
+        id: string;
+        top: number;
+    }[];
+    scrollTop: number;
+    clientHeight: number;
+    scrollHeight: number;
+    /** The entry a jump is heading for, for as long as the jump lasts. */
+    jumpTarget: string | null;
+}
+/**
+ * The entry the "On this page" list marks. During a jump, the one the reader
+ * jumped to, whatever the jump scrolls past. Otherwise the last section whose
+ * heading has come up to a line a quarter down the view, except at the bottom
+ * of the page: the sections there can never come up to the line, so the last
+ * one in view is active.
+ */
+export declare function activeTocId({ anchors, scrollTop, clientHeight, scrollHeight, jumpTarget }: ScrollSpyState): string;
+/**
+ * Cut a type as written into plain text and the names of documented types, so
+ * the page can turn those names into links to their cards.
+ *
+ * `ref.links` holds type ids, and an id is the type's name, or
+ * `${name}@${importPath}` when two reachable types share a name. An identifier
+ * in the text is matched against the name part of each id, the id that is the
+ * name itself first. Known limitation: a type imported under another name
+ * (`import { Item as OtherItem }`) appears in the text by its local name, which
+ * no id carries, so it stays unlinked.
+ */
+export declare function typeSegments(ref: ApiTypeRef): TypeSegment[];
+/** A parameter as a signature writes it, `config?: ToastConfig` or `...features: Feature[]`, with its type linked. */
+export declare function paramSegments(param: ApiParam): TypeSegment[];
+/**
+ * A parameter as its declaration writes it, default included:
+ * `config: ToastConfig = {}`. A default makes the parameter optional, so it
+ * goes without the `?`; one without a default reads as in a signature.
+ */
+export declare function declaredParamSegments(param: ApiParam): TypeSegment[];
+/** Whether a parameter list says more than its signature: a `@param` text or a default. */
+export declare function documentsParams(params: readonly ApiParam[] | undefined): boolean;
+/**
+ * What follows a setup entry's name on its signature line: the parameters and
+ * the return type of a function, the type of a token.
+ */
+export declare function setupSignature(entry: ApiSetupEntry): TypeSegment[];
+/**
+ * Split a type's `reachedFrom` (`parameter of show()`, `via options.action`)
+ * into its words and the code they end in, so the page can set the code apart.
+ */
+export declare function splitReachedFrom(reachedFrom: string): {
+    text: string;
+    code?: string;
+};
+//# sourceMappingURL=service-page.model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service-page.model.d.ts","sourceRoot":"","sources":["../../src/service-page/service-page.model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,kHAAkH;AAClH,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;CAChB;AAED,iGAAiG;AACjG,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,8CAA8C;AAC9C,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,EAAE,CAc9D;AAKD,kGAAkG;AAClG,MAAM,WAAW,cAAc;IAC3B,qGAAqG;IACrG,OAAO,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,EAAE,cAAc,GAAG,MAAM,CAYlH;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,WAAW,EAAE,CAsB3D;AAED,sHAAsH;AACtH,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,EAAE,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,EAAE,CAGpE;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,GAAG,OAAO,CAEhF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,WAAW,EAAE,CAMlE;AAiBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAKrF"}

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

@@ -0,0 +1,130 @@
+/** The TOC id of a documented type's card. */
+export function typeAnchor(typeId) {
+    return `type-${typeId}`;
+}
+/**
+ * The sections of an API page in the order the page shows them. Usage is
+ * always there, being generated; any other section only when it has content.
+ * A service has properties and methods, a pipe its transform signatures.
+ */
+export function buildApiPageToc(page) {
+    const sections = [
+        ['usage', 'Usage', true],
+        ['setup', 'Setup', page.setup.length > 0],
+        ['examples', 'Examples', page.examples.length > 0],
+        ['properties', 'Properties', !!page.properties?.length],
+        ['methods', 'Methods', !!page.methods?.length],
+        ['transform', 'Transform', !!page.transform?.length],
+        ['types', 'Types', page.types.length > 0]
+    ];
+    const toc = sections.filter(([, , present]) => present).map(([id, label]) => ({ id, label, level: 1 }));
+    for (const type of page.types)
+        toc.push({ id: typeAnchor(type.id), label: type.name, level: 2 });
+    return toc;
+}
+/** How far down the view, as a share of its height, a section's heading has to come to make the section active. */
+const ACTIVATION_LINE = 0.25;
+/**
+ * The entry the "On this page" list marks. During a jump, the one the reader
+ * jumped to, whatever the jump scrolls past. Otherwise the last section whose
+ * heading has come up to a line a quarter down the view, except at the bottom
+ * of the page: the sections there can never come up to the line, so the last
+ * one in view is active.
+ */
+export function activeTocId({ anchors, scrollTop, clientHeight, scrollHeight, jumpTarget }) {
+    if (jumpTarget)
+        return jumpTarget;
+    if (scrollTop + clientHeight >= scrollHeight - 1) {
+        const inView = anchors.filter((anchor) => anchor.top >= scrollTop && anchor.top < scrollTop + clientHeight).at(-1);
+        if (inView)
+            return inView.id;
+    }
+    const line = scrollTop + clientHeight * ACTIVATION_LINE;
+    return (anchors.filter((anchor) => anchor.top <= line).at(-1) ?? anchors[0])?.id ?? 'usage';
+}
+const IDENTIFIER = /[A-Za-z_$][\w$]*/g;
+/**
+ * Cut a type as written into plain text and the names of documented types, so
+ * the page can turn those names into links to their cards.
+ *
+ * `ref.links` holds type ids, and an id is the type's name, or
+ * `${name}@${importPath}` when two reachable types share a name. An identifier
+ * in the text is matched against the name part of each id, the id that is the
+ * name itself first. Known limitation: a type imported under another name
+ * (`import { Item as OtherItem }`) appears in the text by its local name, which
+ * no id carries, so it stays unlinked.
+ */
+export function typeSegments(ref) {
+    const links = ref.links ?? [];
+    const segments = [];
+    let plain = '';
+    let last = 0;
+    for (const match of ref.text.matchAll(IDENTIFIER)) {
+        const name = match[0];
+        const id = links.find((candidate) => candidate === name) ?? links.find((candidate) => candidate.split('@')[0] === name);
+        if (!id)
+            continue;
+        plain += ref.text.slice(last, match.index);
+        if (plain)
+            segments.push({ text: plain });
+        segments.push({ text: name, link: typeAnchor(id) });
+        plain = '';
+        last = match.index + name.length;
+    }
+    plain += ref.text.slice(last);
+    if (plain || !segments.length)
+        segments.push({ text: plain });
+    return segments;
+}
+/** A parameter as a signature writes it, `config?: ToastConfig` or `...features: Feature[]`, with its type linked. */
+export function paramSegments(param) {
+    return joinSegments(`${param.rest ? '...' : ''}${param.name}${param.optional ? '?' : ''}: `, typeSegments(param.type));
+}
+/**
+ * A parameter as its declaration writes it, default included:
+ * `config: ToastConfig = {}`. A default makes the parameter optional, so it
+ * goes without the `?`; one without a default reads as in a signature.
+ */
+export function declaredParamSegments(param) {
+    if (param.defaultValue === undefined)
+        return paramSegments(param);
+    return joinSegments(`${param.rest ? '...' : ''}${param.name}: `, typeSegments(param.type), ` = ${param.defaultValue}`);
+}
+/** Whether a parameter list says more than its signature: a `@param` text or a default. */
+export function documentsParams(params) {
+    return !!params?.some((param) => param.description || param.defaultValue !== undefined);
+}
+/**
+ * What follows a setup entry's name on its signature line: the parameters and
+ * the return type of a function, the type of a token.
+ */
+export function setupSignature(entry) {
+    if (entry.kind === 'token')
+        return entry.tokenType ? joinSegments(': ', typeSegments(entry.tokenType)) : [];
+    const params = (entry.params ?? []).flatMap((param, index) => (index ? [', ', paramSegments(param)] : [paramSegments(param)]));
+    return joinSegments('(', ...params, ')', ...(entry.returnType ? [': ', typeSegments(entry.returnType)] : []));
+}
+/** Concatenate text and segments, merging neighbouring plain text into one segment. */
+function joinSegments(...parts) {
+    const joined = [];
+    for (const segment of parts.flatMap((part) => (typeof part === 'string' ? [{ text: part }] : part))) {
+        const previous = joined.at(-1);
+        if (!segment.text)
+            continue;
+        if (previous && !previous.link && !segment.link)
+            previous.text += segment.text;
+        else
+            joined.push({ ...segment });
+    }
+    return joined;
+}
+/**
+ * Split a type's `reachedFrom` (`parameter of show()`, `via options.action`)
+ * into its words and the code they end in, so the page can set the code apart.
+ */
+export function splitReachedFrom(reachedFrom) {
+    const space = reachedFrom.lastIndexOf(' ');
+    if (space < 0)
+        return { text: reachedFrom };
+    return { text: reachedFrom.slice(0, space + 1), code: reachedFrom.slice(space + 1) };
+}

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

@@ -0,0 +1,28 @@
+import type { ApiSetupEntry, ScannedService } from '@ng-prism/core/plugin';
+/** What the import lines read: a scanned service or pipe. */
+export interface UsageSubject {
+    className: string;
+    importPath?: string;
+    api: {
+        setup: ApiSetupEntry[];
+    };
+}
+/**
+ * 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 subject's first, each naming the subject
+ * before its setup entries. Shared with the pipe snippet.
+ */
+export declare function importLines({ className, importPath, api }: UsageSubject): string[];
+/** 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/service-page/service-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-usage.d.ts","sourceRoot":"","sources":["../../src/service-page/service-usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE3E,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE;QAAE,KAAK,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAmBpE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,EAAE,EAAE,YAAY,GAAG,MAAM,EAAE,CASlF;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/service-page/service-usage.js

@@ -0,0 +1,61 @@
+/**
+ * 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), 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 subject's first, each naming the subject
+ * before its setup entries. Shared with the pipe snippet.
+ */
+export function importLines({ className, importPath, api }) {
+    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 entry of api.setup)
+        add(entry.importPath, entry.name);
+    return [...groups].map(([path, names]) => `import { ${names.join(', ')} } from '${path}';`);
+}
+/** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-prism/plugin-jsdoc",
-  "version": "22.6.0",
+  "version": "22.7.0-beta.0",
   "description": "JSDoc API documentation panel for ng-prism.",
   "ng-add": {
     "save": "devDependencies"
@@ -35,8 +35,9 @@
     "!**/*.tsbuildinfo"
   ],
   "peerDependencies": {
+    "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
-    "@ng-prism/core": "^22.6.0-0",
+    "@ng-prism/core": "^22.7.0-0",
     "highlight.js": ">=11.0.0",
     "ngx-highlightjs": ">=14.0.0",
     "typescript": ">=5.5.0",