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

package/README.md

@@ -12,13 +12,18 @@ npm install @ng-prism/plugin-jsdoc
 
 ### Peer Dependencies
 
-| Package           | Version    |
-| ----------------- | ---------- |
-| `@ng-prism/core`  | `>=21.0.0` |
-| `@angular/core`   | `>=20.0.0` |
-| `typescript`      | `>=5.5.0`  |
-| `highlight.js`    | `>=11.0.0` |
-| `ngx-highlightjs` | `>=14.0.0` |
+| Package                      | Version               |
+| ---------------------------- | --------------------- |
+| `@ng-prism/core`             | `^<plugin version>-0` |
+| `@angular/common`            | `>=20.0.0`            |
+| `@angular/core`              | `>=20.0.0`            |
+| `@angular/platform-browser`  | `>=20.0.0`            |
+| `@angular-devkit/schematics` | `>=20.0.0`            |
+| `typescript`                 | `>=5.5.0`             |
+| `highlight.js`               | `>=11.0.0`            |
+| `ngx-highlightjs`            | `>=14.0.0`            |
+
+Each release requires the `@ng-prism/core` of its own version (`^22.7.0-0` for 22.7.0), so keep the core and the plugin on the same version.
 
 ## Setup
 
@@ -36,11 +41,9 @@ export default defineConfig({
 
 - Extracts class-level JSDoc description
 - Extracts per-input and per-output JSDoc comments
-- Renders an **API** panel with:
-    - Component description
-    - Inputs table (name, type, default, description)
-    - Outputs table (name, description)
-    - Supported tags: `@deprecated`, `@since`, `@see`, `@example`
+- Draws the API page of every component and directive with `@Showcase`, the same page a service or a pipe gets (since 22.7.0): a generated usage snippet, the examples, the inputs with their types linked to type cards, the outputs with their payload, the documented methods, the types they reach and an "On this page" list. `{@link}` and `@see` jump to a type card, and `@deprecated`, `@since` and `@example` are supported, see [Components and Directives](https://ng-prism.github.io/ng-prism/#/plugins/jsdoc?id=components-and-directives)
+- Draws the API page of every service with `@Showcase` (since 22.7.0): its properties, methods and setup, a generated usage snippet and the types it reaches, see [Services](https://ng-prism.github.io/ng-prism/#/plugins/jsdoc?id=services)
+- Draws the API page of every pipe with `@Showcase` (since 22.7.0): the template name, purity, every `transform()` signature and setup, a generated usage snippet and the types it reaches, see [Pipes](https://ng-prism.github.io/ng-prism/#/plugins/jsdoc?id=pipes)
 
 ## Markdown Support
 
@@ -98,13 +101,13 @@ export class ButtonComponent {
 }
 ```
 
-The API panel shows the class description, a table of inputs with their types and JSDoc, and all supported tags.
+The API tab shows the class description, a usage snippet, the inputs with their types, defaults and JSDoc, and all supported tags.
 
 ## How It Works
 
-**Build time:** The `onComponentScanned` hook uses `ts.createSourceFile` with `setParentNodes: true` and `ts.getJSDocTags()` to extract JSDoc data. The extracted data is injected into `showcaseConfig.meta.jsdoc`.
+**Build time:** The plugin sets `componentApi: true`, which has the core scanner read `ScannedComponent.api` for every component; a config without a plugin that sets it skips that work. The `onComponentScanned` hook uses `ts.createSourceFile` with `setParentNodes: true` and `ts.getJSDocTags()` to extract JSDoc data, keeping each parsed file while its mtime and size stay the same, so a rebuild of `serve` only parses the files that changed. The extracted data is injected into `showcaseConfig.meta.jsdoc`.
 
-**Runtime:** The `JsDocPanelComponent` reads the metadata and renders the documentation. The component is lazy-loaded via `loadComponent`.
+**Runtime:** The `JsDocPanelComponent` is lazy-loaded via `loadComponent`. It builds the API page from `ScannedComponent.api`, which the core scanner fills with the types, payloads, methods and links, and from the JSDoc data in `showcaseConfig.meta.jsdoc`, and renders it. Services and pipes get the same page from their own scanned data.
 
 ## License
 

package/dist/api-page/api-page.helpers.d.ts

@@ -0,0 +1,79 @@
+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 component or directive has inputs, outputs and methods, a service
+ * 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=api-page.helpers.d.ts.map

package/dist/api-page/api-page.helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-page.helpers.d.ts","sourceRoot":"","sources":["../../src/api-page/api-page.helpers.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;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,EAAE,CAgB9D;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/api-page/api-page.helpers.js

@@ -0,0 +1,133 @@
+/** 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 component or directive has inputs, outputs and methods, a service
+ * 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],
+        ['inputs', 'Inputs', !!page.inputs?.length],
+        ['outputs', 'Outputs', !!page.outputs?.length],
+        ['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/api-page/api-page.model.d.ts

@@ -0,0 +1,62 @@
+import type { ApiDocTags, ApiMethod, ApiProperty, ApiSetupEntry, ApiTypeDoc, ApiTypeRef, ScannedComponent, 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 an API page documents. */
+export type ApiPageKind = 'component' | 'directive' | 'service' | 'pipe';
+/** An input of a component or directive, by the name a template binds it by. */
+export interface ApiInputRow {
+    name: string;
+    type: ApiTypeRef;
+    /** As the code writes it: a string in quotes. */
+    defaultValue?: string;
+    required: boolean;
+    description?: string;
+    tags: ApiDocTags;
+}
+/** An output of a component or directive: an `output()`, or the change event of a `model()`. */
+export interface ApiOutputRow {
+    name: string;
+    /** What the event emits. Absent when the scanner did not read it. */
+    payload?: ApiTypeRef;
+    description?: string;
+    tags: ApiDocTags;
+}
+/**
+ * What the API page shows, for a component, a directive, a service or a pipe.
+ * The page renders this alone, so all four kinds share one look; the sections
+ * a kind does not have are left out.
+ *
+ * The entries of `properties`, `methods`, `transform` and `types` are the
+ * scanned objects themselves, not copies: the page caches what it derives from
+ * them by object. The rows of `inputs` and `outputs`, and the `methods` of a
+ * component without `api`, are built anew by every call.
+ */
+export interface ApiPageModel {
+    kind: ApiPageKind;
+    className: string;
+    description?: string;
+    chips: ApiPageChip[];
+    see: string[];
+    usage: string;
+    setup: ApiSetupEntry[];
+    examples: string[];
+    /** Components and directives only. */
+    inputs?: ApiInputRow[];
+    /** Components and directives only. */
+    outputs?: ApiOutputRow[];
+    /** Services only. */
+    properties?: ApiProperty[];
+    /** Services, components and directives: 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;
+export declare function componentApiPage(component: ScannedComponent): ApiPageModel;
+//# sourceMappingURL=api-page.model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api-page.model.d.ts","sourceRoot":"","sources":["../../src/api-page/api-page.model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,UAAU,EACV,SAAS,EACT,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EAEV,gBAAgB,EAChB,WAAW,EACX,cAAc,EACjB,MAAM,uBAAuB,CAAC;AAM/B,4GAA4G;AAC5G,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,IAAI,CAAC;CACrB;AAED,kCAAkC;AAClC,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzE,gFAAgF;AAChF,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,UAAU,CAAC;CACpB;AAED,gGAAgG;AAChG,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,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,sCAAsC;IACtC,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,sCAAsC;IACtC,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,qBAAqB;IACrB,UAAU,CAAC,EAAE,WAAW,EAAE,CAAC;IAC3B,+DAA+D;IAC/D,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;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,gBAAgB,GAAG,YAAY,CAiD1E"}

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

@@ -0,0 +1,122 @@
+import { generateComponentUsage } from './component-usage.js';
+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
+    };
+}
+export function componentApiPage(component) {
+    const { className, importPath, inputs, outputs, componentMeta, showcaseConfig, api } = component;
+    // The jsdoc plugin's own data, for a component that has no `api`: one a plugin hook built, or one from the manifest of an older core.
+    const jsdoc = showcaseConfig.meta?.['jsdoc'];
+    const description = api ? api.description : jsdoc?.classDescription;
+    const tags = api ? api.tags : (jsdoc?.classTags ?? {});
+    const memberTags = jsdoc?.memberTags ?? {};
+    const outputRows = outputs.map((output) => ({
+        name: output.alias ?? output.name,
+        payload: api?.outputTypes[output.name],
+        description: output.doc,
+        tags: memberTags[output.name] ?? {}
+    }));
+    // Angular adds the change event of a `model()` by itself, so the scanner has no output for it.
+    for (const change of api?.modelChanges ?? []) {
+        const input = inputs.find((candidate) => candidate.name === change.input);
+        const publicName = input ? (input.alias ?? input.name) : change.input;
+        outputRows.push({
+            name: change.event,
+            payload: change.type,
+            description: `Emits when \`${publicName}\` changes; bind both ways with \`[(${publicName})]\`.`,
+            tags: memberTags[change.input] ?? {}
+        });
+    }
+    return {
+        kind: componentMeta.isDirective ? 'directive' : 'component',
+        className,
+        description,
+        chips: [...deprecationChip(tags), ...valueChip('Version', tags.version), ...valueChip('Since', tags.since), ...valueChip('Entry point', importPath)],
+        see: tags.see ?? [],
+        usage: generateComponentUsage(component),
+        setup: [],
+        examples: tags.example ?? [],
+        inputs: inputs.map((input) => ({
+            name: input.alias ?? input.name,
+            type: api?.inputTypes[input.name] ?? { text: input.rawType ?? input.type },
+            defaultValue: input.defaultValue === undefined ? undefined : formatDefault(input.defaultValue),
+            required: input.required,
+            description: input.doc,
+            tags: memberTags[input.name] ?? {}
+        })),
+        outputs: outputRows,
+        methods: api ? api.methods : (jsdoc?.methods ?? []).map(methodSignature),
+        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 }] : [];
+}
+/** As the code writes a default: a string in quotes, an array or object as JSON (`String()` would give `a,b` and `[object Object]`), anything else by its `String()`. */
+function formatDefault(value) {
+    if (typeof value === 'string')
+        return `'${value}'`;
+    return typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value);
+}
+/** A method of the jsdoc plugin's data as a signature: it knows no more of the types than their names. */
+function methodSignature(method) {
+    return {
+        name: method.name,
+        params: method.params.map((param) => ({
+            name: param.name,
+            type: { text: param.type ?? 'unknown' },
+            optional: false,
+            description: param.description
+        })),
+        returnType: { text: method.returnType ?? 'void' },
+        description: method.description,
+        tags: method.tags
+    };
+}

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

@@ -0,0 +1,14 @@
+import { type ScannedComponent } from '@ng-prism/core/plugin';
+/**
+ * The snippet that shows how to use a component or directive: the import, the
+ * `imports` entry of the component that uses it, and one line of template.
+ *
+ * It is generated from the scanned selector and inputs, not taken from the
+ * author, so it shows the minimum that works: the required inputs, bound to a
+ * member of the same name, and nothing else. A directive goes where the
+ * showcase puts it: on the `host` element, or on a plain element of its own.
+ * A `{ template }` host is the exception: the snippet shows the subject inside
+ * that markup, as the first variant that has one renders it.
+ */
+export declare function generateComponentUsage(component: ScannedComponent): string;
+//# sourceMappingURL=component-usage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"component-usage.d.ts","sourceRoot":"","sources":["../../src/api-page/component-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAS9H;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,GAAG,MAAM,CAc1E"}

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

@@ -0,0 +1,120 @@
+import { COMPOSITION_SUBJECT_SLOT } from '@ng-prism/core/plugin';
+import { importLines, joinUsageBlocks } from './service-usage.js';
+/** Elements that have no closing tag. */
+const VOID_ELEMENTS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr']);
+/**
+ * The snippet that shows how to use a component or directive: the import, the
+ * `imports` entry of the component that uses it, and one line of template.
+ *
+ * It is generated from the scanned selector and inputs, not taken from the
+ * author, so it shows the minimum that works: the required inputs, bound to a
+ * member of the same name, and nothing else. A directive goes where the
+ * showcase puts it: on the `host` element, or on a plain element of its own.
+ * A `{ template }` host is the exception: the snippet shows the subject inside
+ * that markup, as the first variant that has one renders it.
+ */
+export function generateComponentUsage(component) {
+    const { className, componentMeta, showcaseConfig } = component;
+    const configured = showcaseConfig.host;
+    const composed = isHostTemplate(configured) ? firstCase(component) : undefined;
+    // A component renders itself; only a directive needs an element to sit on.
+    const host = componentMeta.isDirective && !isHostTemplate(configured) ? configured : undefined;
+    const hostImport = host && typeof host !== 'string' ? host.import : undefined;
+    const extraImports = composed ? (component.composition?.imports ?? []) : hostImport ? [hostImport] : [];
+    return joinUsageBlocks([
+        importLines(component, extraImports),
+        ['// in the component that uses it', `@Component({ imports: [${[className, ...extraImports.map(({ name }) => name)].join(', ')}], … })`],
+        ['// in its template', composed ? compositionLine(component, composed) : templateLine(component, host)]
+    ]);
+}
+/** `null` is no host, though `typeof null` is `'object'`: a config from untyped code may carry one. */
+function isHostTemplate(host) {
+    return !!host && typeof host === 'object' && 'template' in host;
+}
+/** The case of the first variant that has a composition: what the styleguide shows first. */
+function firstCase({ composition }) {
+    const index = composition?.variantCases.find((candidate) => candidate >= 0);
+    return index === undefined ? undefined : composition?.cases[index];
+}
+/**
+ * The template of a case as its author wrote it, with the required inputs on the
+ * subject element in place of the slot. A required input the template sets
+ * itself is not bound a second time.
+ */
+function compositionLine({ inputs }, { template, unbound }) {
+    const owned = new Set(unbound.filter(({ reason }) => reason === 'template').map(({ name }) => name));
+    const bindings = requiredInputs(inputs)
+        .filter(({ member }) => !owned.has(member))
+        .map(binding);
+    // Split and join, not replace: a member name may hold `$`, which `replace` would read as a pattern.
+    return template.split(COMPOSITION_SUBJECT_SLOT).join(bindings.length ? ` ${bindings.join(' ')}` : '');
+}
+function templateLine({ inputs, componentMeta }, host) {
+    const selector = parseSelector(componentMeta.selector);
+    const hostElement = typeof host === 'string' ? parseHostString(host) : host && { element: host.selector, attributes: hostAttributes(host.inputs) };
+    const element = hostElement?.element ?? selector.element ?? 'div';
+    const required = requiredInputs(inputs);
+    // A binding takes the place of the bare attribute the selector asks for.
+    const selectorAttributes = selector.attributes.filter((attribute) => !required.some(({ publicName }) => publicName === attribute.name));
+    const attributes = [
+        ...(hostElement?.attributes ?? []),
+        ...selectorAttributes.map(({ name, value }) => (value === undefined ? name : `${name}="${value}"`)),
+        ...required.map(binding)
+    ];
+    const opening = [element, ...attributes].join(' ');
+    return element.includes('-') || VOID_ELEMENTS.has(element) ? `<${opening} />` : `<${opening}></${element}>`;
+}
+/** The required inputs in source order, each by the name a template binds it under and the member it is bound to. */
+function requiredInputs(inputs) {
+    return inputs.filter((input) => input.required).map((input) => ({ publicName: input.alias ?? input.name, member: input.name }));
+}
+function binding({ publicName, member }) {
+    return `[${publicName}]="${member}"`;
+}
+const SELECTOR_PART = /\[([\w-]+)(?:=(["']?)([^\]"']*)\2)?]|\.([\w-]+)/g;
+/**
+ * The first selector of a list as an element and attributes. A class becomes
+ * the `class` attribute; negations, other attribute operators and pseudo
+ * classes say nothing about what to write, so they are left out.
+ */
+function parseSelector(selector) {
+    const first = selector
+        .split(',')[0]
+        .trim()
+        .replace(/:not\([^)]*\)/g, '');
+    const element = first.match(/^[a-zA-Z][\w-]*/)?.[0];
+    const attributes = [];
+    for (const [, name, , value, className] of first.slice(element?.length ?? 0).matchAll(SELECTOR_PART)) {
+        const classAttribute = attributes.find((attribute) => attribute.name === 'class');
+        if (className === undefined)
+            attributes.push({ name, value });
+        else if (classAttribute)
+            classAttribute.value += ` ${className}`;
+        else
+            attributes.push({ name: 'class', value: className });
+    }
+    return { element, attributes };
+}
+/**
+ * The opening tag a string host starts with and its attributes as written;
+ * undefined when the string does not start with a tag. A host may carry
+ * content and a closing tag (`<button class="btn">Hover me</button>`): the
+ * showcase renders all of it, the snippet only needs the element to put the
+ * directive on.
+ */
+function parseHostString(host) {
+    const match = host.match(/^\s*<\s*([a-zA-Z][\w-]*)([^>]*?)\s*\/?\s*>/);
+    if (!match)
+        return undefined;
+    return { element: match[1], attributes: match[2].trim() ? [match[2].trim()] : [] };
+}
+/** Strings are attributes; numbers and booleans need a binding to stay what they are; anything else is bound to a member of that name. */
+function hostAttributes(inputs) {
+    return Object.entries(inputs ?? {}).map(([name, value]) => {
+        if (typeof value === 'string')
+            return `${name}="${value.replace(/&/g, '&amp;').replace(/"/g, '&quot;')}"`;
+        if (typeof value === 'number' || typeof value === 'boolean')
+            return `[${name}]="${value}"`;
+        return `[${name}]="${name}"`;
+    });
+}

package/dist/api-page/doc-links.d.ts

@@ -0,0 +1,15 @@
+import type { ApiTypeDoc } from '@ng-prism/core/plugin';
+/** Marks the button of a link, so the page can find it in rendered `innerHTML` that Angular does not bind. */
+export declare 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 declare function typeLinkTarget(types: readonly ApiTypeDoc[], target: string): string | undefined;
+/**
+ * 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 declare function resolveDocLinks(text: string, resolve: (target: string) => string | undefined): string;
+//# sourceMappingURL=doc-links.d.ts.map

package/dist/api-page/doc-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-links.d.ts","sourceRoot":"","sources":["../../src/api-page/doc-links.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAWxD,8GAA8G;AAC9G,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK/F;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAAG,MAAM,CAUrG"}