@webpieces/docs-site 0.0.1

package/src/render/NavModel.d.ts

@@ -0,0 +1,47 @@
+import { ApiSpec } from '../spec/ApiSpec';
+import { ProsePage } from '../manifest/DocsManifest';
+import { SiteUrls } from './SiteUrls';
+/** The nav group the prose pages sit in, above the reference. */
+export declare const GUIDES_GROUP = "Guides";
+/** The nav group every named object DTO gets a page under. */
+export declare const SCHEMAS_GROUP = "Schemas";
+/** One line in the nav tree. `badge` is drawn beside the title — `WEBHOOK`, or an HTTP method. */
+export declare class NavLink {
+    readonly title: string;
+    /** Relative to the site ROOT; each page prepends its own `../` prefix. */
+    readonly url: string;
+    readonly badge: string;
+    constructor(title: string, 
+    /** Relative to the site ROOT; each page prepends its own `../` prefix. */
+    url: string, badge: string);
+}
+/** One collapsible section of the nav tree. */
+export declare class NavGroup {
+    readonly title: string;
+    readonly links: readonly NavLink[];
+    constructor(title: string, links: readonly NavLink[]);
+}
+/** The nav tree, as data. {@link NavBuilder} is what puts it in this order. */
+export declare class NavModel {
+    readonly groups: readonly NavGroup[];
+    constructor(groups: readonly NavGroup[]);
+}
+/**
+ * Builds the nav tree: prose first, then ONE SECTION PER OPENAPI TAG in the document's own `tags[]`
+ * order, then the schema pages.
+ *
+ * **Every tag is its own section.** A tag missing from the sidebar is an operation a partner cannot
+ * find, which reads exactly like an operation that does not exist — so the sections come from the
+ * tags rather than from a hand-maintained list a new tag would have to be added to.
+ *
+ * Webhooks appear inside the section of the tag they share, appended after that tag's operations and
+ * badged, because the events are the consequence of the calls above them.
+ */
+export declare class NavBuilder {
+    private readonly urls;
+    constructor(urls: SiteUrls);
+    build(spec: ApiSpec, prose: readonly ProsePage[], overviewTitle: string): NavModel;
+    private guideLinks;
+    private referenceLinks;
+    private schemaLinks;
+}

package/src/render/NavModel.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NavBuilder = exports.NavModel = exports.NavGroup = exports.NavLink = exports.SCHEMAS_GROUP = exports.GUIDES_GROUP = void 0;
+/** The nav group the prose pages sit in, above the reference. */
+exports.GUIDES_GROUP = 'Guides';
+/** The nav group every named object DTO gets a page under. */
+exports.SCHEMAS_GROUP = 'Schemas';
+/** One line in the nav tree. `badge` is drawn beside the title — `WEBHOOK`, or an HTTP method. */
+class NavLink {
+    title;
+    url;
+    badge;
+    constructor(title, 
+    /** Relative to the site ROOT; each page prepends its own `../` prefix. */
+    url, badge) {
+        this.title = title;
+        this.url = url;
+        this.badge = badge;
+    }
+}
+exports.NavLink = NavLink;
+/** One collapsible section of the nav tree. */
+class NavGroup {
+    title;
+    links;
+    constructor(title, links) {
+        this.title = title;
+        this.links = links;
+    }
+}
+exports.NavGroup = NavGroup;
+/** The nav tree, as data. {@link NavBuilder} is what puts it in this order. */
+class NavModel {
+    groups;
+    constructor(groups) {
+        this.groups = groups;
+    }
+}
+exports.NavModel = NavModel;
+/**
+ * Builds the nav tree: prose first, then ONE SECTION PER OPENAPI TAG in the document's own `tags[]`
+ * order, then the schema pages.
+ *
+ * **Every tag is its own section.** A tag missing from the sidebar is an operation a partner cannot
+ * find, which reads exactly like an operation that does not exist — so the sections come from the
+ * tags rather than from a hand-maintained list a new tag would have to be added to.
+ *
+ * Webhooks appear inside the section of the tag they share, appended after that tag's operations and
+ * badged, because the events are the consequence of the calls above them.
+ */
+class NavBuilder {
+    urls;
+    constructor(urls) {
+        this.urls = urls;
+    }
+    build(spec, prose, overviewTitle) {
+        const groups = [
+            new NavGroup(exports.GUIDES_GROUP, this.guideLinks(prose, overviewTitle)),
+        ];
+        for (const section of spec.sections) {
+            groups.push(new NavGroup(section.name, this.referenceLinks(section)));
+        }
+        const schemaLinks = this.schemaLinks(spec);
+        if (schemaLinks.length > 0) {
+            groups.push(new NavGroup(exports.SCHEMAS_GROUP, schemaLinks));
+        }
+        return new NavModel(groups);
+    }
+    guideLinks(prose, overviewTitle) {
+        const links = [new NavLink(overviewTitle, this.urls.home(), '')];
+        for (const page of prose) {
+            links.push(new NavLink(page.title, this.urls.prose(page), ''));
+        }
+        return links;
+    }
+    referenceLinks(section) {
+        return section.operations.map((operation) => new NavLink(operation.name, this.urls.operation(operation), operation.isWebhook ? 'WEBHOOK' : operation.httpMethod));
+    }
+    schemaLinks(spec) {
+        return spec.schemas
+            .filter((schema) => schema.hasOwnPage)
+            .map((schema) => new NavLink(schema.name, this.urls.schema(schema), ''));
+    }
+}
+exports.NavBuilder = NavBuilder;
+//# sourceMappingURL=NavModel.js.map

package/src/render/NavModel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavModel.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/render/NavModel.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiSpec, NamedSchema, OperationInfo, TagSection } from '../spec/ApiSpec';\nimport { ProsePage } from '../manifest/DocsManifest';\nimport { SiteUrls } from './SiteUrls';\n\n/** The nav group the prose pages sit in, above the reference. */\nexport const GUIDES_GROUP = 'Guides';\n\n/** The nav group every named object DTO gets a page under. */\nexport const SCHEMAS_GROUP = 'Schemas';\n\n/** One line in the nav tree. `badge` is drawn beside the title — `WEBHOOK`, or an HTTP method. */\nexport class NavLink {\n    constructor(\n        readonly title: string,\n        /** Relative to the site ROOT; each page prepends its own `../` prefix. */\n        readonly url: string,\n        readonly badge: string,\n    ) {}\n}\n\n/** One collapsible section of the nav tree. */\nexport class NavGroup {\n    constructor(\n        readonly title: string,\n        readonly links: readonly NavLink[],\n    ) {}\n}\n\n/** The nav tree, as data. {@link NavBuilder} is what puts it in this order. */\nexport class NavModel {\n    constructor(readonly groups: readonly NavGroup[]) {}\n}\n\n/**\n * Builds the nav tree: prose first, then ONE SECTION PER OPENAPI TAG in the document's own `tags[]`\n * order, then the schema pages.\n *\n * **Every tag is its own section.** A tag missing from the sidebar is an operation a partner cannot\n * find, which reads exactly like an operation that does not exist — so the sections come from the\n * tags rather than from a hand-maintained list a new tag would have to be added to.\n *\n * Webhooks appear inside the section of the tag they share, appended after that tag's operations and\n * badged, because the events are the consequence of the calls above them.\n */\nexport class NavBuilder {\n    constructor(private readonly urls: SiteUrls) {}\n\n    build(spec: ApiSpec, prose: readonly ProsePage[], overviewTitle: string): NavModel {\n        const groups: NavGroup[] = [\n            new NavGroup(GUIDES_GROUP, this.guideLinks(prose, overviewTitle)),\n        ];\n        for (const section of spec.sections) {\n            groups.push(new NavGroup(section.name, this.referenceLinks(section)));\n        }\n        const schemaLinks = this.schemaLinks(spec);\n        if (schemaLinks.length > 0) {\n            groups.push(new NavGroup(SCHEMAS_GROUP, schemaLinks));\n        }\n        return new NavModel(groups);\n    }\n\n    private guideLinks(prose: readonly ProsePage[], overviewTitle: string): readonly NavLink[] {\n        const links = [new NavLink(overviewTitle, this.urls.home(), '')];\n        for (const page of prose) {\n            links.push(new NavLink(page.title, this.urls.prose(page), ''));\n        }\n        return links;\n    }\n\n    private referenceLinks(section: TagSection): readonly NavLink[] {\n        return section.operations.map(\n            (operation: OperationInfo): NavLink =>\n                new NavLink(\n                    operation.name,\n                    this.urls.operation(operation),\n                    operation.isWebhook ? 'WEBHOOK' : operation.httpMethod,\n                ),\n        );\n    }\n\n    private schemaLinks(spec: ApiSpec): readonly NavLink[] {\n        return spec.schemas\n            .filter((schema: NamedSchema): boolean => schema.hasOwnPage)\n            .map(\n                (schema: NamedSchema): NavLink =>\n                    new NavLink(schema.name, this.urls.schema(schema), ''),\n            );\n    }\n}\n"]}

package/src/render/OperationPageRenderer.d.ts

@@ -0,0 +1,44 @@
+import { ApiSpec, OperationInfo } from '../spec/ApiSpec';
+import { CardRenderer } from './CardRenderer';
+import { CodeSampleBuilder } from '../samples/CodeSamples';
+import { ExampleBuilder } from '../spec/ExampleBuilder';
+import { FieldTreeBuilder } from '../spec/FieldTree';
+import { FieldTreeRenderer } from './FieldTreeRenderer';
+import { Layout } from './Layout';
+import { Markdown } from '../markdown/Markdown';
+import { SiteUrls } from './SiteUrls';
+import { SitePage } from './SitePage';
+/** The badge a webhook carries everywhere it appears. */
+export declare const WEBHOOK_BADGE = "WEBHOOK";
+/**
+ * One pre-rendered page per operation, at `reference/<kebab-operation>/index.html`.
+ *
+ * ## What a WEBHOOK page leaves out, and why
+ *
+ * No method, no path, no code samples. The url is the PARTNER's — they host the endpoint wherever
+ * they choose — so a `POST https://api.example.com/...` sample on a webhook page invites them to
+ * call something that does not exist. What it keeps is the payload, because the payload is the part
+ * that IS ours, and the event name, because that is what they match on the wire.
+ */
+export declare class OperationPageRenderer {
+    private readonly spec;
+    private readonly fields;
+    private readonly trees;
+    private readonly markdown;
+    private readonly cards;
+    private readonly samples;
+    private readonly examples;
+    private readonly layout;
+    private readonly urls;
+    private readonly html;
+    constructor(spec: ApiSpec, fields: FieldTreeBuilder, trees: FieldTreeRenderer, markdown: Markdown, cards: CardRenderer, samples: CodeSampleBuilder, examples: ExampleBuilder, layout: Layout, urls: SiteUrls);
+    page(operation: OperationInfo): SitePage;
+    private body;
+    private head;
+    private requestSection;
+    private responseSection;
+    private response;
+    /** A `oneOf` renders as expanded variants; anything else renders as one flat field tree. */
+    private tree;
+    private cardColumn;
+}

package/src/render/OperationPageRenderer.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperationPageRenderer = exports.WEBHOOK_BADGE = void 0;
+const Html_1 = require("./Html");
+const SitePage_1 = require("./SitePage");
+/** The badge a webhook carries everywhere it appears. */
+exports.WEBHOOK_BADGE = 'WEBHOOK';
+/**
+ * One pre-rendered page per operation, at `reference/<kebab-operation>/index.html`.
+ *
+ * ## What a WEBHOOK page leaves out, and why
+ *
+ * No method, no path, no code samples. The url is the PARTNER's — they host the endpoint wherever
+ * they choose — so a `POST https://api.example.com/...` sample on a webhook page invites them to
+ * call something that does not exist. What it keeps is the payload, because the payload is the part
+ * that IS ours, and the event name, because that is what they match on the wire.
+ */
+class OperationPageRenderer {
+    spec;
+    fields;
+    trees;
+    markdown;
+    cards;
+    samples;
+    examples;
+    layout;
+    urls;
+    html = new Html_1.Html();
+    constructor(spec, fields, trees, markdown, cards, samples, examples, layout, urls) {
+        this.spec = spec;
+        this.fields = fields;
+        this.trees = trees;
+        this.markdown = markdown;
+        this.cards = cards;
+        this.samples = samples;
+        this.examples = examples;
+        this.layout = layout;
+        this.urls = urls;
+    }
+    page(operation) {
+        const url = this.urls.operation(operation);
+        const prefix = this.urls.prefixFor(url);
+        return new SitePage_1.SitePage(url, operation.name, this.layout.render(url, operation.name, this.body(operation, prefix), this.cardColumn(operation)));
+    }
+    body(operation, prefix) {
+        const parts = [this.head(operation), `<h1>${this.html.escape(operation.name)}</h1>`];
+        if (operation.description !== '') {
+            parts.push(this.markdown.render(operation.description));
+        }
+        parts.push(this.requestSection(operation, prefix));
+        parts.push(this.responseSection(operation, prefix));
+        return parts.join('\n');
+    }
+    head(operation) {
+        if (operation.isWebhook) {
+            return `<div class="op-head"><span class="badge">${exports.WEBHOOK_BADGE}</span><code class="op-path">${this.html.escape(operation.eventName)}</code></div>`;
+        }
+        return `<div class="op-head"><span class="badge">${this.html.escape(operation.httpMethod)}</span><code class="op-path">${this.html.escape(operation.path)}</code></div>`;
+    }
+    requestSection(operation, prefix) {
+        if (operation.requestSchema === undefined) {
+            return '';
+        }
+        return `<h2>Request body</h2>${this.tree(operation.requestSchema, prefix)}`;
+    }
+    responseSection(operation, prefix) {
+        if (operation.responses.length === 0) {
+            return '';
+        }
+        const blocks = operation.responses
+            .map((response) => this.response(response, prefix))
+            .join('');
+        return `<h2>Responses</h2>${blocks}`;
+    }
+    response(response, prefix) {
+        const summary = `${this.html.escape(response.status)} — ${this.html.escape(response.description)}`;
+        const body = response.schema === undefined
+            ? '<p class="field-doc">No body.</p>'
+            : this.tree(response.schema, prefix);
+        return `<details class="disclosure" open><summary>${summary}</summary>${body}</details>`;
+    }
+    /** A `oneOf` renders as expanded variants; anything else renders as one flat field tree. */
+    tree(schema, prefix) {
+        const variants = this.fields.variantsOf(schema);
+        if (variants.length > 0) {
+            return this.trees.renderVariants(variants, this.fields.discriminatorPropertyOf(schema), prefix);
+        }
+        return this.trees.render(this.fields.fieldsOf(schema), prefix);
+    }
+    cardColumn(operation) {
+        const payload = this.examples.render(this.examples.build(operation.requestSchema));
+        if (operation.isWebhook) {
+            return this.cards.example('EVENT PAYLOAD', payload);
+        }
+        return [
+            this.cards.authorization(operation, this.spec.securitySchemes),
+            this.cards.samples(this.samples.samplesFor(operation)),
+        ].join('\n');
+    }
+}
+exports.OperationPageRenderer = OperationPageRenderer;
+//# sourceMappingURL=OperationPageRenderer.js.map

package/src/render/OperationPageRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OperationPageRenderer.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/render/OperationPageRenderer.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiSpec, OperationInfo, ResponseInfo } from '../spec/ApiSpec';\nimport { CardRenderer } from './CardRenderer';\nimport { CodeSampleBuilder } from '../samples/CodeSamples';\nimport { ExampleBuilder } from '../spec/ExampleBuilder';\nimport { FieldTreeBuilder } from '../spec/FieldTree';\nimport { FieldTreeRenderer } from './FieldTreeRenderer';\nimport { Html } from './Html';\nimport { JsonNode } from '../spec/JsonNode';\nimport { Layout } from './Layout';\nimport { Markdown } from '../markdown/Markdown';\nimport { SiteUrls } from './SiteUrls';\nimport { SitePage } from './SitePage';\n\n/** The badge a webhook carries everywhere it appears. */\nexport const WEBHOOK_BADGE = 'WEBHOOK';\n\n/**\n * One pre-rendered page per operation, at `reference/<kebab-operation>/index.html`.\n *\n * ## What a WEBHOOK page leaves out, and why\n *\n * No method, no path, no code samples. The url is the PARTNER's — they host the endpoint wherever\n * they choose — so a `POST https://api.example.com/...` sample on a webhook page invites them to\n * call something that does not exist. What it keeps is the payload, because the payload is the part\n * that IS ours, and the event name, because that is what they match on the wire.\n */\nexport class OperationPageRenderer {\n    private readonly html = new Html();\n\n    constructor(\n        private readonly spec: ApiSpec,\n        private readonly fields: FieldTreeBuilder,\n        private readonly trees: FieldTreeRenderer,\n        private readonly markdown: Markdown,\n        private readonly cards: CardRenderer,\n        private readonly samples: CodeSampleBuilder,\n        private readonly examples: ExampleBuilder,\n        private readonly layout: Layout,\n        private readonly urls: SiteUrls,\n    ) {}\n\n    page(operation: OperationInfo): SitePage {\n        const url = this.urls.operation(operation);\n        const prefix = this.urls.prefixFor(url);\n        return new SitePage(\n            url,\n            operation.name,\n            this.layout.render(\n                url,\n                operation.name,\n                this.body(operation, prefix),\n                this.cardColumn(operation),\n            ),\n        );\n    }\n\n    private body(operation: OperationInfo, prefix: string): string {\n        const parts = [this.head(operation), `<h1>${this.html.escape(operation.name)}</h1>`];\n        if (operation.description !== '') {\n            parts.push(this.markdown.render(operation.description));\n        }\n        parts.push(this.requestSection(operation, prefix));\n        parts.push(this.responseSection(operation, prefix));\n        return parts.join('\\n');\n    }\n\n    private head(operation: OperationInfo): string {\n        if (operation.isWebhook) {\n            return `<div class=\"op-head\"><span class=\"badge\">${WEBHOOK_BADGE}</span><code class=\"op-path\">${this.html.escape(operation.eventName)}</code></div>`;\n        }\n        return `<div class=\"op-head\"><span class=\"badge\">${this.html.escape(operation.httpMethod)}</span><code class=\"op-path\">${this.html.escape(operation.path)}</code></div>`;\n    }\n\n    private requestSection(operation: OperationInfo, prefix: string): string {\n        if (operation.requestSchema === undefined) {\n            return '';\n        }\n        return `<h2>Request body</h2>${this.tree(operation.requestSchema, prefix)}`;\n    }\n\n    private responseSection(operation: OperationInfo, prefix: string): string {\n        if (operation.responses.length === 0) {\n            return '';\n        }\n        const blocks = operation.responses\n            .map((response: ResponseInfo): string => this.response(response, prefix))\n            .join('');\n        return `<h2>Responses</h2>${blocks}`;\n    }\n\n    private response(response: ResponseInfo, prefix: string): string {\n        const summary = `${this.html.escape(response.status)} — ${this.html.escape(response.description)}`;\n        const body =\n            response.schema === undefined\n                ? '<p class=\"field-doc\">No body.</p>'\n                : this.tree(response.schema, prefix);\n        return `<details class=\"disclosure\" open><summary>${summary}</summary>${body}</details>`;\n    }\n\n    /** A `oneOf` renders as expanded variants; anything else renders as one flat field tree. */\n    private tree(schema: JsonNode, prefix: string): string {\n        const variants = this.fields.variantsOf(schema);\n        if (variants.length > 0) {\n            return this.trees.renderVariants(\n                variants,\n                this.fields.discriminatorPropertyOf(schema),\n                prefix,\n            );\n        }\n        return this.trees.render(this.fields.fieldsOf(schema), prefix);\n    }\n\n    private cardColumn(operation: OperationInfo): string {\n        const payload = this.examples.render(this.examples.build(operation.requestSchema));\n        if (operation.isWebhook) {\n            return this.cards.example('EVENT PAYLOAD', payload);\n        }\n        return [\n            this.cards.authorization(operation, this.spec.securitySchemes),\n            this.cards.samples(this.samples.samplesFor(operation)),\n        ].join('\\n');\n    }\n}\n"]}

package/src/render/SitePage.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One PRE-RENDERED file at one URL.
+ *
+ * The whole site is a list of these, which is the decision every other property falls out of: a deep
+ * link resolves server-side because the file is already there, the output is a folder any static
+ * host serves, the page reads correctly with JS off, and a JSDoc edit shows up as a diff on the one
+ * page it affects instead of inside a bundle. Client JS is left with disclosure state, the language
+ * tabs and the theme — the three things that are genuinely about this reader, right now.
+ */
+export declare class SitePage {
+    /** Relative to the output root, always ending in `index.html` so `file://` browsing works. */
+    readonly url: string;
+    readonly title: string;
+    readonly html: string;
+    constructor(
+    /** Relative to the output root, always ending in `index.html` so `file://` browsing works. */
+    url: string, title: string, html: string);
+}
+/** One file that is copied out verbatim beside the pages — the stylesheet and the script. */
+export declare class SiteAsset {
+    readonly url: string;
+    readonly contents: string;
+    constructor(url: string, contents: string);
+}
+/** Everything one run produces. */
+export declare class RenderedSite {
+    readonly pages: readonly SitePage[];
+    readonly assets: readonly SiteAsset[];
+    constructor(pages: readonly SitePage[], assets: readonly SiteAsset[]);
+}

package/src/render/SitePage.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RenderedSite = exports.SiteAsset = exports.SitePage = void 0;
+/**
+ * One PRE-RENDERED file at one URL.
+ *
+ * The whole site is a list of these, which is the decision every other property falls out of: a deep
+ * link resolves server-side because the file is already there, the output is a folder any static
+ * host serves, the page reads correctly with JS off, and a JSDoc edit shows up as a diff on the one
+ * page it affects instead of inside a bundle. Client JS is left with disclosure state, the language
+ * tabs and the theme — the three things that are genuinely about this reader, right now.
+ */
+class SitePage {
+    url;
+    title;
+    html;
+    constructor(
+    /** Relative to the output root, always ending in `index.html` so `file://` browsing works. */
+    url, title, html) {
+        this.url = url;
+        this.title = title;
+        this.html = html;
+    }
+}
+exports.SitePage = SitePage;
+/** One file that is copied out verbatim beside the pages — the stylesheet and the script. */
+class SiteAsset {
+    url;
+    contents;
+    constructor(url, contents) {
+        this.url = url;
+        this.contents = contents;
+    }
+}
+exports.SiteAsset = SiteAsset;
+/** Everything one run produces. */
+class RenderedSite {
+    pages;
+    assets;
+    constructor(pages, assets) {
+        this.pages = pages;
+        this.assets = assets;
+    }
+}
+exports.RenderedSite = RenderedSite;
+//# sourceMappingURL=SitePage.js.map

package/src/render/SitePage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SitePage.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/render/SitePage.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,MAAa,QAAQ;IAGJ;IACA;IACA;IAJb;IACI,8FAA8F;IACrF,GAAW,EACX,KAAa,EACb,IAAY;QAFZ,QAAG,GAAH,GAAG,CAAQ;QACX,UAAK,GAAL,KAAK,CAAQ;QACb,SAAI,GAAJ,IAAI,CAAQ;IACtB,CAAC;CACP;AAPD,4BAOC;AAED,6FAA6F;AAC7F,MAAa,SAAS;IAEL;IACA;IAFb,YACa,GAAW,EACX,QAAgB;QADhB,QAAG,GAAH,GAAG,CAAQ;QACX,aAAQ,GAAR,QAAQ,CAAQ;IAC1B,CAAC;CACP;AALD,8BAKC;AAED,mCAAmC;AACnC,MAAa,YAAY;IAER;IACA;IAFb,YACa,KAA0B,EAC1B,MAA4B;QAD5B,UAAK,GAAL,KAAK,CAAqB;QAC1B,WAAM,GAAN,MAAM,CAAsB;IACtC,CAAC;CACP;AALD,oCAKC","sourcesContent":["/**\n * One PRE-RENDERED file at one URL.\n *\n * The whole site is a list of these, which is the decision every other property falls out of: a deep\n * link resolves server-side because the file is already there, the output is a folder any static\n * host serves, the page reads correctly with JS off, and a JSDoc edit shows up as a diff on the one\n * page it affects instead of inside a bundle. Client JS is left with disclosure state, the language\n * tabs and the theme — the three things that are genuinely about this reader, right now.\n */\nexport class SitePage {\n    constructor(\n        /** Relative to the output root, always ending in `index.html` so `file://` browsing works. */\n        readonly url: string,\n        readonly title: string,\n        readonly html: string,\n    ) {}\n}\n\n/** One file that is copied out verbatim beside the pages — the stylesheet and the script. */\nexport class SiteAsset {\n    constructor(\n        readonly url: string,\n        readonly contents: string,\n    ) {}\n}\n\n/** Everything one run produces. */\nexport class RenderedSite {\n    constructor(\n        readonly pages: readonly SitePage[],\n        readonly assets: readonly SiteAsset[],\n    ) {}\n}\n"]}

package/src/render/SiteRenderer.d.ts

@@ -0,0 +1,34 @@
+import { ApiSpec } from '../spec/ApiSpec';
+import { ProsePage } from '../manifest/DocsManifest';
+import { RenderedSite, SiteAsset } from './SitePage';
+/** The nav title of the generated home page. */
+export declare const OVERVIEW_TITLE = "Overview";
+/**
+ * Turns one {@link ApiSpec} plus its prose into the complete list of files to write.
+ *
+ * Every URL is a FILE — `index.html`, `prose/<slug>/index.html`, `reference/<slug>/index.html`,
+ * `schemas/<slug>/index.html` — so a deep link resolves without JS, the output is a folder any
+ * static host serves, and a JSDoc edit is a diff on the one page it affects.
+ *
+ * ## One page per named object DTO
+ *
+ * Only OBJECTS get pages. A named enum or scalar alias renders inline at each use site with its
+ * chips, because a page holding one line of values costs a reader the context they were reading.
+ * An UNDEFINED `$ref` also stays inline — a link to a page the document never defined is a dead
+ * link, which is strictly worse than the unresolved type name it replaced.
+ */
+export declare class SiteRenderer {
+    private readonly markdown;
+    private readonly cards;
+    private readonly html;
+    private readonly urls;
+    /** @param spec the document. @param prose the manifest's pages, in the manifest's order. */
+    render(spec: ApiSpec, prose: readonly ProsePage[], titleOverride: string): RenderedSite;
+    /** The stylesheet and the script, written beside the pages. */
+    assets(): readonly SiteAsset[];
+    private overview;
+    private sectionIndex;
+    private serversCard;
+    private prosePage;
+    private schemaPage;
+}

package/src/render/SiteRenderer.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SiteRenderer = exports.OVERVIEW_TITLE = void 0;
+const CardRenderer_1 = require("./CardRenderer");
+const CodeSamples_1 = require("../samples/CodeSamples");
+const ExampleBuilder_1 = require("../spec/ExampleBuilder");
+const FieldTree_1 = require("../spec/FieldTree");
+const FieldTreeRenderer_1 = require("./FieldTreeRenderer");
+const Html_1 = require("./Html");
+const Layout_1 = require("./Layout");
+const Markdown_1 = require("../markdown/Markdown");
+const NavModel_1 = require("./NavModel");
+const OperationPageRenderer_1 = require("./OperationPageRenderer");
+const SitePage_1 = require("./SitePage");
+const SchemaLens_1 = require("../spec/SchemaLens");
+const SiteScript_1 = require("../assets/SiteScript");
+const SiteStyles_1 = require("../assets/SiteStyles");
+const SiteUrls_1 = require("./SiteUrls");
+/** The nav title of the generated home page. */
+exports.OVERVIEW_TITLE = 'Overview';
+/**
+ * Turns one {@link ApiSpec} plus its prose into the complete list of files to write.
+ *
+ * Every URL is a FILE — `index.html`, `prose/<slug>/index.html`, `reference/<slug>/index.html`,
+ * `schemas/<slug>/index.html` — so a deep link resolves without JS, the output is a folder any
+ * static host serves, and a JSDoc edit is a diff on the one page it affects.
+ *
+ * ## One page per named object DTO
+ *
+ * Only OBJECTS get pages. A named enum or scalar alias renders inline at each use site with its
+ * chips, because a page holding one line of values costs a reader the context they were reading.
+ * An UNDEFINED `$ref` also stays inline — a link to a page the document never defined is a dead
+ * link, which is strictly worse than the unresolved type name it replaced.
+ */
+class SiteRenderer {
+    markdown = new Markdown_1.Markdown();
+    cards = new CardRenderer_1.CardRenderer();
+    html = new Html_1.Html();
+    urls = new SiteUrls_1.SiteUrls();
+    /** @param spec the document. @param prose the manifest's pages, in the manifest's order. */
+    render(spec, prose, titleOverride) {
+        const lens = new SchemaLens_1.SchemaLens(spec);
+        const fields = new FieldTree_1.FieldTreeBuilder(lens);
+        const trees = new FieldTreeRenderer_1.FieldTreeRenderer(this.markdown, this.urls);
+        const examples = new ExampleBuilder_1.ExampleBuilder(lens);
+        const title = titleOverride === '' ? spec.title : titleOverride;
+        const nav = new NavModel_1.NavBuilder(this.urls).build(spec, prose, exports.OVERVIEW_TITLE);
+        const layout = new Layout_1.Layout(nav, this.urls, title, spec.version);
+        const operations = new OperationPageRenderer_1.OperationPageRenderer(spec, fields, trees, this.markdown, this.cards, new CodeSamples_1.CodeSampleBuilder(spec, examples), examples, layout, this.urls);
+        const pages = [this.overview(spec, layout)];
+        for (const page of prose) {
+            pages.push(this.prosePage(page, layout));
+        }
+        for (const operation of spec.operations()) {
+            pages.push(operations.page(operation));
+        }
+        for (const schema of spec.schemas) {
+            if (schema.hasOwnPage) {
+                pages.push(this.schemaPage(schema, fields, trees, examples, layout));
+            }
+        }
+        return new SitePage_1.RenderedSite(pages, this.assets());
+    }
+    /** The stylesheet and the script, written beside the pages. */
+    assets() {
+        return [
+            new SitePage_1.SiteAsset('styles.css', SiteStyles_1.SiteStyles.CSS),
+            new SitePage_1.SiteAsset('site.js', SiteScript_1.SiteScript.JS),
+        ];
+    }
+    overview(spec, layout) {
+        const parts = [`<h1>${this.html.escape(spec.title)}</h1>`];
+        if (spec.description !== '') {
+            parts.push(this.markdown.render(spec.description));
+        }
+        parts.push(this.sectionIndex(spec));
+        const url = this.urls.home();
+        return new SitePage_1.SitePage(url, exports.OVERVIEW_TITLE, layout.render(url, exports.OVERVIEW_TITLE, parts.join('\n'), this.serversCard(spec)));
+    }
+    sectionIndex(spec) {
+        return spec.sections
+            .map((section) => {
+            const items = section.operations
+                .map((operation) => `<li>${this.html.link(this.urls.operation(operation), operation.name)}</li>`)
+                .join('');
+            return `<h2>${this.html.escape(section.name)}</h2>${this.markdown.render(section.description)}<ul>${items}</ul>`;
+        })
+            .join('\n');
+    }
+    serversCard(spec) {
+        if (spec.servers.length === 0) {
+            return '';
+        }
+        const rows = spec.servers
+            .map((server) => `<div class="field"><div class="field-head"><span class="field-name">${this.html.escape(server.url)}</span></div><div class="field-doc">${this.html.escape(server.description ?? '')}</div></div>`)
+            .join('');
+        return this.cards.panel('SERVERS', rows);
+    }
+    prosePage(page, layout) {
+        const url = this.urls.prose(page);
+        const body = `<h1>${this.html.escape(page.title)}</h1>${this.markdown.render(page.markdown)}`;
+        return new SitePage_1.SitePage(url, page.title, layout.render(url, page.title, body, ''));
+    }
+    schemaPage(schema, fields, trees, examples, layout) {
+        const url = this.urls.schema(schema);
+        const prefix = this.urls.prefixFor(url);
+        const parts = [`<h1>${this.html.escape(schema.name)}</h1>`];
+        const description = schema.node.text('description');
+        if (description !== undefined) {
+            parts.push(this.markdown.render(description));
+        }
+        const variants = fields.variantsOf(schema.node);
+        parts.push(variants.length > 0
+            ? trees.renderVariants(variants, fields.discriminatorPropertyOf(schema.node), prefix)
+            : trees.render(fields.fieldsOf(schema.node), prefix));
+        const sample = examples.render(examples.build(schema.node));
+        return new SitePage_1.SitePage(url, schema.name, layout.render(url, schema.name, parts.join('\n'), this.cards.example('EXAMPLE', sample)));
+    }
+}
+exports.SiteRenderer = SiteRenderer;
+//# sourceMappingURL=SiteRenderer.js.map

package/src/render/SiteRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SiteRenderer.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/render/SiteRenderer.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiSpec, NamedSchema, OperationInfo, ServerInfo, TagSection } from '../spec/ApiSpec';\nimport { CardRenderer } from './CardRenderer';\nimport { CodeSampleBuilder } from '../samples/CodeSamples';\nimport { ExampleBuilder } from '../spec/ExampleBuilder';\nimport { FieldTreeBuilder } from '../spec/FieldTree';\nimport { FieldTreeRenderer } from './FieldTreeRenderer';\nimport { Html } from './Html';\nimport { Layout } from './Layout';\nimport { Markdown } from '../markdown/Markdown';\nimport { NavBuilder } from './NavModel';\nimport { OperationPageRenderer } from './OperationPageRenderer';\nimport { ProsePage } from '../manifest/DocsManifest';\nimport { RenderedSite, SiteAsset, SitePage } from './SitePage';\nimport { SchemaLens } from '../spec/SchemaLens';\nimport { SiteScript } from '../assets/SiteScript';\nimport { SiteStyles } from '../assets/SiteStyles';\nimport { SiteUrls } from './SiteUrls';\n\n/** The nav title of the generated home page. */\nexport const OVERVIEW_TITLE = 'Overview';\n\n/**\n * Turns one {@link ApiSpec} plus its prose into the complete list of files to write.\n *\n * Every URL is a FILE — `index.html`, `prose/<slug>/index.html`, `reference/<slug>/index.html`,\n * `schemas/<slug>/index.html` — so a deep link resolves without JS, the output is a folder any\n * static host serves, and a JSDoc edit is a diff on the one page it affects.\n *\n * ## One page per named object DTO\n *\n * Only OBJECTS get pages. A named enum or scalar alias renders inline at each use site with its\n * chips, because a page holding one line of values costs a reader the context they were reading.\n * An UNDEFINED `$ref` also stays inline — a link to a page the document never defined is a dead\n * link, which is strictly worse than the unresolved type name it replaced.\n */\nexport class SiteRenderer {\n    private readonly markdown = new Markdown();\n    private readonly cards = new CardRenderer();\n    private readonly html = new Html();\n    private readonly urls = new SiteUrls();\n\n    /** @param spec the document. @param prose the manifest's pages, in the manifest's order. */\n    render(spec: ApiSpec, prose: readonly ProsePage[], titleOverride: string): RenderedSite {\n        const lens = new SchemaLens(spec);\n        const fields = new FieldTreeBuilder(lens);\n        const trees = new FieldTreeRenderer(this.markdown, this.urls);\n        const examples = new ExampleBuilder(lens);\n        const title = titleOverride === '' ? spec.title : titleOverride;\n        const nav = new NavBuilder(this.urls).build(spec, prose, OVERVIEW_TITLE);\n        const layout = new Layout(nav, this.urls, title, spec.version);\n        const operations = new OperationPageRenderer(\n            spec,\n            fields,\n            trees,\n            this.markdown,\n            this.cards,\n            new CodeSampleBuilder(spec, examples),\n            examples,\n            layout,\n            this.urls,\n        );\n        const pages: SitePage[] = [this.overview(spec, layout)];\n        for (const page of prose) {\n            pages.push(this.prosePage(page, layout));\n        }\n        for (const operation of spec.operations()) {\n            pages.push(operations.page(operation));\n        }\n        for (const schema of spec.schemas) {\n            if (schema.hasOwnPage) {\n                pages.push(this.schemaPage(schema, fields, trees, examples, layout));\n            }\n        }\n        return new RenderedSite(pages, this.assets());\n    }\n\n    /** The stylesheet and the script, written beside the pages. */\n    assets(): readonly SiteAsset[] {\n        return [\n            new SiteAsset('styles.css', SiteStyles.CSS),\n            new SiteAsset('site.js', SiteScript.JS),\n        ];\n    }\n\n    private overview(spec: ApiSpec, layout: Layout): SitePage {\n        const parts = [`<h1>${this.html.escape(spec.title)}</h1>`];\n        if (spec.description !== '') {\n            parts.push(this.markdown.render(spec.description));\n        }\n        parts.push(this.sectionIndex(spec));\n        const url = this.urls.home();\n        return new SitePage(\n            url,\n            OVERVIEW_TITLE,\n            layout.render(url, OVERVIEW_TITLE, parts.join('\\n'), this.serversCard(spec)),\n        );\n    }\n\n    private sectionIndex(spec: ApiSpec): string {\n        return spec.sections\n            .map((section: TagSection): string => {\n                const items = section.operations\n                    .map(\n                        (operation: OperationInfo): string =>\n                            `<li>${this.html.link(this.urls.operation(operation), operation.name)}</li>`,\n                    )\n                    .join('');\n                return `<h2>${this.html.escape(section.name)}</h2>${this.markdown.render(section.description)}<ul>${items}</ul>`;\n            })\n            .join('\\n');\n    }\n\n    private serversCard(spec: ApiSpec): string {\n        if (spec.servers.length === 0) {\n            return '';\n        }\n        const rows = spec.servers\n            .map(\n                (server: ServerInfo): string =>\n                    `<div class=\"field\"><div class=\"field-head\"><span class=\"field-name\">${this.html.escape(server.url)}</span></div><div class=\"field-doc\">${this.html.escape(server.description ?? '')}</div></div>`,\n            )\n            .join('');\n        return this.cards.panel('SERVERS', rows);\n    }\n\n    private prosePage(page: ProsePage, layout: Layout): SitePage {\n        const url = this.urls.prose(page);\n        const body = `<h1>${this.html.escape(page.title)}</h1>${this.markdown.render(page.markdown)}`;\n        return new SitePage(url, page.title, layout.render(url, page.title, body, ''));\n    }\n\n    private schemaPage(\n        schema: NamedSchema,\n        fields: FieldTreeBuilder,\n        trees: FieldTreeRenderer,\n        examples: ExampleBuilder,\n        layout: Layout,\n    ): SitePage {\n        const url = this.urls.schema(schema);\n        const prefix = this.urls.prefixFor(url);\n        const parts = [`<h1>${this.html.escape(schema.name)}</h1>`];\n        const description = schema.node.text('description');\n        if (description !== undefined) {\n            parts.push(this.markdown.render(description));\n        }\n        const variants = fields.variantsOf(schema.node);\n        parts.push(\n            variants.length > 0\n                ? trees.renderVariants(\n                      variants,\n                      fields.discriminatorPropertyOf(schema.node),\n                      prefix,\n                  )\n                : trees.render(fields.fieldsOf(schema.node), prefix),\n        );\n        const sample = examples.render(examples.build(schema.node));\n        return new SitePage(\n            url,\n            schema.name,\n            layout.render(\n                url,\n                schema.name,\n                parts.join('\\n'),\n                this.cards.example('EXAMPLE', sample),\n            ),\n        );\n    }\n}\n"]}

package/src/render/SiteUrls.d.ts

@@ -0,0 +1,24 @@
+import { NamedSchema, OperationInfo } from '../spec/ApiSpec';
+import { ProsePage } from '../manifest/DocsManifest';
+/**
+ * Every URL the site has, in ONE place.
+ *
+ * Each is a real FILE ending in `index.html`, and each is stated RELATIVE to the site root; a page
+ * prepends its own `../` prefix with {@link prefixFor}. Root-relative links (`/reference/…`) only
+ * work when the site is the whole host, and a generated reference is routinely served under a path —
+ * GitHub Pages does it by default — where a root-relative link 404s on every page but the home one.
+ * Ending each href in `index.html` rather than a bare directory is the same argument one level down:
+ * a directory URL needs a server willing to serve the index, and `file://` is not one.
+ */
+export declare class SiteUrls {
+    /** The generated home page. */
+    home(): string;
+    /** `reference/<kebab-operation>/index.html` — one file per operation URL. */
+    operation(operation: OperationInfo): string;
+    /** `schemas/<kebab-name>/index.html` — one file per named object DTO. */
+    schema(schema: NamedSchema): string;
+    /** `prose/<kebab-title>/index.html`. */
+    prose(page: ProsePage): string;
+    /** `../` once per directory between a page and the site root. */
+    prefixFor(url: string): string;
+}