@webpieces/docs-site 0.0.1

package/src/spec/ApiSpec.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiSpec = exports.NamedSchema = exports.TagSection = exports.OperationInfo = exports.ResponseInfo = exports.SecuritySchemeInfo = exports.ServerInfo = void 0;
+/**
+ * The model this package renders. It is read from a document STRUCTURALLY (see {@link JsonNode}), so
+ * it is deliberately NOT `@webpieces/openapi-generator`'s document classes even though it looks like
+ * them: a compile-time dependency on the generator would make "generated by us" a precondition for
+ * "renderable by us", and #985 is explicit that any conforming 3.0 or 3.1 document renders here.
+ *
+ * Everything below is data, so everything below is a class (`CLAUDE.md` §1).
+ */
+/** One entry of the document's `servers[]`. The first one is what the code samples call. */
+class ServerInfo {
+    url;
+    description;
+    constructor(url, description) {
+        this.url = url;
+        this.description = description;
+    }
+}
+exports.ServerInfo = ServerInfo;
+/**
+ * One published security scheme. Only the fields a partner has to ACT on are carried: what to send
+ * and where. `headerName` is empty for a scheme that is not sent in a header, and the code samples
+ * then omit it rather than inventing a header name the server never reads.
+ */
+class SecuritySchemeInfo {
+    key;
+    kind;
+    sentIn;
+    headerName;
+    description;
+    constructor(key, kind, sentIn, headerName, description) {
+        this.key = key;
+        this.kind = kind;
+        this.sentIn = sentIn;
+        this.headerName = headerName;
+        this.description = description;
+    }
+}
+exports.SecuritySchemeInfo = SecuritySchemeInfo;
+/** One response of one operation. */
+class ResponseInfo {
+    status;
+    description;
+    schema;
+    constructor(status, description, schema) {
+        this.status = status;
+        this.description = description;
+        this.schema = schema;
+    }
+}
+exports.ResponseInfo = ResponseInfo;
+/**
+ * One rendered page's worth of operation.
+ *
+ * A WEBHOOK carries `isWebhook`, and with it no method, no path and no code samples. The url belongs
+ * to the PARTNER, so a curl of ours against one would invite them to call something that does not
+ * exist — see `responsibilities.md`.
+ */
+class OperationInfo {
+    name;
+    slug;
+    httpMethod;
+    path;
+    description;
+    tag;
+    requestSchema;
+    responses;
+    isWebhook;
+    securityKeys;
+    eventName;
+    constructor(name, slug, httpMethod, path, description, tag, requestSchema, responses, isWebhook, securityKeys, 
+    /**
+     * The event NAME a webhook is keyed by in the document's `webhooks:` block, and the empty
+     * string for an ordinary operation. It is carried separately from `name` because the two
+     * are different published facts — `orderStateChanged` is what we call the method,
+     * `order.state-changed` is what the partner matches on the wire.
+     */
+    eventName) {
+        this.name = name;
+        this.slug = slug;
+        this.httpMethod = httpMethod;
+        this.path = path;
+        this.description = description;
+        this.tag = tag;
+        this.requestSchema = requestSchema;
+        this.responses = responses;
+        this.isWebhook = isWebhook;
+        this.securityKeys = securityKeys;
+        this.eventName = eventName;
+    }
+}
+exports.OperationInfo = OperationInfo;
+/**
+ * One nav section: an OpenAPI tag and the operations under it, webhooks appended after the
+ * operations that share the tag. EVERY tag gets one — a tag missing from the sidebar is an operation
+ * a partner cannot find, which reads exactly like an operation that does not exist.
+ */
+class TagSection {
+    name;
+    description;
+    operations;
+    constructor(name, description, operations) {
+        this.name = name;
+        this.description = description;
+        this.operations = operations;
+    }
+}
+exports.TagSection = TagSection;
+/**
+ * One named schema from `components.schemas`.
+ *
+ * `hasOwnPage` is true for an OBJECT only. A named enum or scalar alias stays inline at every use
+ * site, because a page carrying one line of chips is a click that costs the reader the context they
+ * were reading in.
+ */
+class NamedSchema {
+    name;
+    slug;
+    node;
+    hasOwnPage;
+    constructor(name, slug, node, hasOwnPage) {
+        this.name = name;
+        this.slug = slug;
+        this.node = node;
+        this.hasOwnPage = hasOwnPage;
+    }
+}
+exports.NamedSchema = NamedSchema;
+/** The whole document, read once. */
+class ApiSpec {
+    title;
+    version;
+    description;
+    servers;
+    sections;
+    securitySchemes;
+    schemas;
+    documentSecurityKeys;
+    constructor(title, version, description, servers, sections, securitySchemes, schemas, documentSecurityKeys) {
+        this.title = title;
+        this.version = version;
+        this.description = description;
+        this.servers = servers;
+        this.sections = sections;
+        this.securitySchemes = securitySchemes;
+        this.schemas = schemas;
+        this.documentSecurityKeys = documentSecurityKeys;
+    }
+    /** The named schema `name` refers to, or `undefined` when the document does not define it. */
+    schemaNamed(name) {
+        return this.schemas.find((schema) => schema.name === name);
+    }
+    /** Every operation, across every section, in published order. */
+    operations() {
+        const all = [];
+        for (const section of this.sections) {
+            all.push(...section.operations);
+        }
+        return all;
+    }
+}
+exports.ApiSpec = ApiSpec;
+//# sourceMappingURL=ApiSpec.js.map

package/src/spec/ApiSpec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiSpec.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/spec/ApiSpec.ts"],"names":[],"mappings":";;;AAEA;;;;;;;GAOG;AAEH,4FAA4F;AAC5F,MAAa,UAAU;IAEN;IACA;IAFb,YACa,GAAW,EACX,WAA+B;QAD/B,QAAG,GAAH,GAAG,CAAQ;QACX,gBAAW,GAAX,WAAW,CAAoB;IACzC,CAAC;CACP;AALD,gCAKC;AAED;;;;GAIG;AACH,MAAa,kBAAkB;IAEd;IACA;IACA;IACA;IACA;IALb,YACa,GAAW,EACX,IAAY,EACZ,MAAc,EACd,UAAkB,EAClB,WAA+B;QAJ/B,QAAG,GAAH,GAAG,CAAQ;QACX,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAQ;QACd,eAAU,GAAV,UAAU,CAAQ;QAClB,gBAAW,GAAX,WAAW,CAAoB;IACzC,CAAC;CACP;AARD,gDAQC;AAED,qCAAqC;AACrC,MAAa,YAAY;IAER;IACA;IACA;IAHb,YACa,MAAc,EACd,WAAmB,EACnB,MAA4B;QAF5B,WAAM,GAAN,MAAM,CAAQ;QACd,gBAAW,GAAX,WAAW,CAAQ;QACnB,WAAM,GAAN,MAAM,CAAsB;IACtC,CAAC;CACP;AAND,oCAMC;AAED;;;;;;GAMG;AACH,MAAa,aAAa;IAET;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IAOA;IAjBb,YACa,IAAY,EACZ,IAAY,EACZ,UAAkB,EAClB,IAAY,EACZ,WAAmB,EACnB,GAAW,EACX,aAAmC,EACnC,SAAkC,EAClC,SAAkB,EAClB,YAA+B;IACxC;;;;;OAKG;IACM,SAAiB;QAhBjB,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAQ;QACZ,eAAU,GAAV,UAAU,CAAQ;QAClB,SAAI,GAAJ,IAAI,CAAQ;QACZ,gBAAW,GAAX,WAAW,CAAQ;QACnB,QAAG,GAAH,GAAG,CAAQ;QACX,kBAAa,GAAb,aAAa,CAAsB;QACnC,cAAS,GAAT,SAAS,CAAyB;QAClC,cAAS,GAAT,SAAS,CAAS;QAClB,iBAAY,GAAZ,YAAY,CAAmB;QAO/B,cAAS,GAAT,SAAS,CAAQ;IAC3B,CAAC;CACP;AApBD,sCAoBC;AAED;;;;GAIG;AACH,MAAa,UAAU;IAEN;IACA;IACA;IAHb,YACa,IAAY,EACZ,WAAmB,EACnB,UAAoC;QAFpC,SAAI,GAAJ,IAAI,CAAQ;QACZ,gBAAW,GAAX,WAAW,CAAQ;QACnB,eAAU,GAAV,UAAU,CAA0B;IAC9C,CAAC;CACP;AAND,gCAMC;AAED;;;;;;GAMG;AACH,MAAa,WAAW;IAEP;IACA;IACA;IACA;IAJb,YACa,IAAY,EACZ,IAAY,EACZ,IAAc,EACd,UAAmB;QAHnB,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAU;QACd,eAAU,GAAV,UAAU,CAAS;IAC7B,CAAC;CACP;AAPD,kCAOC;AAED,qCAAqC;AACrC,MAAa,OAAO;IAEH;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IARb,YACa,KAAa,EACb,OAAe,EACf,WAAmB,EACnB,OAA8B,EAC9B,QAA+B,EAC/B,eAA8C,EAC9C,OAA+B,EAC/B,oBAAuC;QAPvC,UAAK,GAAL,KAAK,CAAQ;QACb,YAAO,GAAP,OAAO,CAAQ;QACf,gBAAW,GAAX,WAAW,CAAQ;QACnB,YAAO,GAAP,OAAO,CAAuB;QAC9B,aAAQ,GAAR,QAAQ,CAAuB;QAC/B,oBAAe,GAAf,eAAe,CAA+B;QAC9C,YAAO,GAAP,OAAO,CAAwB;QAC/B,yBAAoB,GAApB,oBAAoB,CAAmB;IACjD,CAAC;IAEJ,8FAA8F;IAC9F,WAAW,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAmB,EAAW,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACrF,CAAC;IAED,iEAAiE;IACjE,UAAU;QACN,MAAM,GAAG,GAAoB,EAAE,CAAC;QAChC,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClC,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;CACJ;AAzBD,0BAyBC","sourcesContent":["import { JsonNode } from './JsonNode';\n\n/**\n * The model this package renders. It is read from a document STRUCTURALLY (see {@link JsonNode}), so\n * it is deliberately NOT `@webpieces/openapi-generator`'s document classes even though it looks like\n * them: a compile-time dependency on the generator would make \"generated by us\" a precondition for\n * \"renderable by us\", and #985 is explicit that any conforming 3.0 or 3.1 document renders here.\n *\n * Everything below is data, so everything below is a class (`CLAUDE.md` §1).\n */\n\n/** One entry of the document's `servers[]`. The first one is what the code samples call. */\nexport class ServerInfo {\n    constructor(\n        readonly url: string,\n        readonly description: string | undefined,\n    ) {}\n}\n\n/**\n * One published security scheme. Only the fields a partner has to ACT on are carried: what to send\n * and where. `headerName` is empty for a scheme that is not sent in a header, and the code samples\n * then omit it rather than inventing a header name the server never reads.\n */\nexport class SecuritySchemeInfo {\n    constructor(\n        readonly key: string,\n        readonly kind: string,\n        readonly sentIn: string,\n        readonly headerName: string,\n        readonly description: string | undefined,\n    ) {}\n}\n\n/** One response of one operation. */\nexport class ResponseInfo {\n    constructor(\n        readonly status: string,\n        readonly description: string,\n        readonly schema: JsonNode | undefined,\n    ) {}\n}\n\n/**\n * One rendered page's worth of operation.\n *\n * A WEBHOOK carries `isWebhook`, and with it no method, no path and no code samples. The url belongs\n * to the PARTNER, so a curl of ours against one would invite them to call something that does not\n * exist — see `responsibilities.md`.\n */\nexport class OperationInfo {\n    constructor(\n        readonly name: string,\n        readonly slug: string,\n        readonly httpMethod: string,\n        readonly path: string,\n        readonly description: string,\n        readonly tag: string,\n        readonly requestSchema: JsonNode | undefined,\n        readonly responses: readonly ResponseInfo[],\n        readonly isWebhook: boolean,\n        readonly securityKeys: readonly string[],\n        /**\n         * The event NAME a webhook is keyed by in the document's `webhooks:` block, and the empty\n         * string for an ordinary operation. It is carried separately from `name` because the two\n         * are different published facts — `orderStateChanged` is what we call the method,\n         * `order.state-changed` is what the partner matches on the wire.\n         */\n        readonly eventName: string,\n    ) {}\n}\n\n/**\n * One nav section: an OpenAPI tag and the operations under it, webhooks appended after the\n * operations that share the tag. EVERY tag gets one — a tag missing from the sidebar is an operation\n * a partner cannot find, which reads exactly like an operation that does not exist.\n */\nexport class TagSection {\n    constructor(\n        readonly name: string,\n        readonly description: string,\n        readonly operations: readonly OperationInfo[],\n    ) {}\n}\n\n/**\n * One named schema from `components.schemas`.\n *\n * `hasOwnPage` is true for an OBJECT only. A named enum or scalar alias stays inline at every use\n * site, because a page carrying one line of chips is a click that costs the reader the context they\n * were reading in.\n */\nexport class NamedSchema {\n    constructor(\n        readonly name: string,\n        readonly slug: string,\n        readonly node: JsonNode,\n        readonly hasOwnPage: boolean,\n    ) {}\n}\n\n/** The whole document, read once. */\nexport class ApiSpec {\n    constructor(\n        readonly title: string,\n        readonly version: string,\n        readonly description: string,\n        readonly servers: readonly ServerInfo[],\n        readonly sections: readonly TagSection[],\n        readonly securitySchemes: readonly SecuritySchemeInfo[],\n        readonly schemas: readonly NamedSchema[],\n        readonly documentSecurityKeys: readonly string[],\n    ) {}\n\n    /** The named schema `name` refers to, or `undefined` when the document does not define it. */\n    schemaNamed(name: string): NamedSchema | undefined {\n        return this.schemas.find((schema: NamedSchema): boolean => schema.name === name);\n    }\n\n    /** Every operation, across every section, in published order. */\n    operations(): readonly OperationInfo[] {\n        const all: OperationInfo[] = [];\n        for (const section of this.sections) {\n            all.push(...section.operations);\n        }\n        return all;\n    }\n}\n"]}

package/src/spec/ExampleBuilder.d.ts

@@ -0,0 +1,32 @@
+import { JsonNode, JsonValue } from './JsonNode';
+import { SchemaLens } from './SchemaLens';
+/**
+ * Builds the example body a code sample sends, FULLY RESOLVED — every `$ref` followed, because a
+ * hyperlink cannot live inside a JSON sample and a partner copying one needs every nested field.
+ *
+ * ## Cycle safety includes the ROOT
+ *
+ * A schema is marked seen BEFORE its own properties are read, not after. Mark it afterwards and a
+ * self-referential DTO — `Category { parent: Category }`, or any pair that refers to each other —
+ * recurses until the stack dies, and the failure is a crash with no pointer in it rather than a
+ * page. A second visit renders `{}`, which is honest: the sample is showing the shape once.
+ *
+ * The values are DERIVED, never invented prose: an enum's first published value, a `date-time`'s
+ * canonical spelling, the field's own name for a free string. A sample that made up plausible
+ * content would read as data a partner can expect us to return.
+ */
+export declare class ExampleBuilder {
+    private readonly lens;
+    private readonly shape;
+    constructor(lens: SchemaLens);
+    /** The example body for a schema, or `undefined` when there is no schema to build one from. */
+    build(schema: JsonNode | undefined): JsonValue | undefined;
+    private valueOf;
+    private inlineValueOf;
+    private mergedValueOf;
+    private typedValueOf;
+    private objectValueOf;
+    private stringValueOf;
+    /** The sample serialization: two-space JSON, which is what a partner pastes into their client. */
+    render(value: JsonValue | undefined): string;
+}

package/src/spec/ExampleBuilder.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExampleBuilder = void 0;
+const SchemaShape_1 = require("./SchemaShape");
+/**
+ * Builds the example body a code sample sends, FULLY RESOLVED — every `$ref` followed, because a
+ * hyperlink cannot live inside a JSON sample and a partner copying one needs every nested field.
+ *
+ * ## Cycle safety includes the ROOT
+ *
+ * A schema is marked seen BEFORE its own properties are read, not after. Mark it afterwards and a
+ * self-referential DTO — `Category { parent: Category }`, or any pair that refers to each other —
+ * recurses until the stack dies, and the failure is a crash with no pointer in it rather than a
+ * page. A second visit renders `{}`, which is honest: the sample is showing the shape once.
+ *
+ * The values are DERIVED, never invented prose: an enum's first published value, a `date-time`'s
+ * canonical spelling, the field's own name for a free string. A sample that made up plausible
+ * content would read as data a partner can expect us to return.
+ */
+class ExampleBuilder {
+    lens;
+    shape = new SchemaShape_1.SchemaShape();
+    constructor(lens) {
+        this.lens = lens;
+    }
+    /** The example body for a schema, or `undefined` when there is no schema to build one from. */
+    build(schema) {
+        if (schema === undefined) {
+            return undefined;
+        }
+        return this.valueOf(schema, '', new Set());
+    }
+    valueOf(schema, fieldName, seen) {
+        const target = this.lens.refTargetOf(schema);
+        if (target !== undefined) {
+            if (seen.has(target.name)) {
+                return {};
+            }
+            const deeper = new Set(seen);
+            deeper.add(target.name);
+            return this.valueOf(this.lens.resolve(schema), fieldName, deeper);
+        }
+        return this.inlineValueOf(schema, fieldName, seen);
+    }
+    inlineValueOf(schema, fieldName, seen) {
+        const branches = schema.list('oneOf');
+        if (branches.length > 0) {
+            return this.valueOf(branches[0], fieldName, seen);
+        }
+        const merged = schema.list('allOf');
+        if (merged.length > 0) {
+            return this.mergedValueOf(merged, fieldName, seen);
+        }
+        const enumValues = this.lens.enumValuesOf(schema);
+        if (enumValues.length > 0) {
+            return enumValues[0];
+        }
+        return this.typedValueOf(schema, fieldName, seen);
+    }
+    mergedValueOf(branches, fieldName, seen) {
+        const merged = {};
+        for (const branch of branches) {
+            const value = this.valueOf(branch, fieldName, seen);
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                Object.assign(merged, value);
+            }
+        }
+        return merged;
+    }
+    typedValueOf(schema, fieldName, seen) {
+        const declared = this.shape.declaredType(schema);
+        if (declared === 'array') {
+            return [this.valueOf(schema.at('items'), fieldName, seen)];
+        }
+        if (declared === 'object' || schema.at('properties').isObject()) {
+            return this.objectValueOf(schema, seen);
+        }
+        if (declared === 'integer' || declared === 'number') {
+            return 0;
+        }
+        if (declared === 'boolean') {
+            return true;
+        }
+        return this.stringValueOf(schema, fieldName);
+    }
+    objectValueOf(schema, seen) {
+        const body = {};
+        for (const property of schema.at('properties').entries()) {
+            body[property.key] = this.valueOf(property.value, property.key, seen);
+        }
+        if (schema.at('properties').entries().length === 0 &&
+            schema.at('additionalProperties').isObject()) {
+            body['key'] = this.valueOf(schema.at('additionalProperties'), 'value', seen);
+        }
+        return body;
+    }
+    stringValueOf(schema, fieldName) {
+        const format = schema.text('format');
+        if (format === 'date-time') {
+            return '2026-01-31T09:30:00Z';
+        }
+        if (format === 'date') {
+            return '2026-01-31';
+        }
+        if (format === 'uuid') {
+            return '00000000-0000-0000-0000-000000000000';
+        }
+        return fieldName === '' ? 'string' : fieldName;
+    }
+    /** The sample serialization: two-space JSON, which is what a partner pastes into their client. */
+    render(value) {
+        if (value === undefined) {
+            return '';
+        }
+        return JSON.stringify(value, null, 2);
+    }
+}
+exports.ExampleBuilder = ExampleBuilder;
+//# sourceMappingURL=ExampleBuilder.js.map

package/src/spec/ExampleBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExampleBuilder.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/spec/ExampleBuilder.ts"],"names":[],"mappings":"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","sourcesContent":["import { JsonMap, JsonNode, JsonValue } from './JsonNode';\nimport { SchemaLens } from './SchemaLens';\nimport { SchemaShape } from './SchemaShape';\n\n/**\n * Builds the example body a code sample sends, FULLY RESOLVED — every `$ref` followed, because a\n * hyperlink cannot live inside a JSON sample and a partner copying one needs every nested field.\n *\n * ## Cycle safety includes the ROOT\n *\n * A schema is marked seen BEFORE its own properties are read, not after. Mark it afterwards and a\n * self-referential DTO — `Category { parent: Category }`, or any pair that refers to each other —\n * recurses until the stack dies, and the failure is a crash with no pointer in it rather than a\n * page. A second visit renders `{}`, which is honest: the sample is showing the shape once.\n *\n * The values are DERIVED, never invented prose: an enum's first published value, a `date-time`'s\n * canonical spelling, the field's own name for a free string. A sample that made up plausible\n * content would read as data a partner can expect us to return.\n */\nexport class ExampleBuilder {\n    private readonly shape = new SchemaShape();\n\n    constructor(private readonly lens: SchemaLens) {}\n\n    /** The example body for a schema, or `undefined` when there is no schema to build one from. */\n    build(schema: JsonNode | undefined): JsonValue | undefined {\n        if (schema === undefined) {\n            return undefined;\n        }\n        return this.valueOf(schema, '', new Set<string>());\n    }\n\n    private valueOf(schema: JsonNode, fieldName: string, seen: ReadonlySet<string>): JsonValue {\n        const target = this.lens.refTargetOf(schema);\n        if (target !== undefined) {\n            if (seen.has(target.name)) {\n                return {};\n            }\n            const deeper = new Set<string>(seen);\n            deeper.add(target.name);\n            return this.valueOf(this.lens.resolve(schema), fieldName, deeper);\n        }\n        return this.inlineValueOf(schema, fieldName, seen);\n    }\n\n    private inlineValueOf(\n        schema: JsonNode,\n        fieldName: string,\n        seen: ReadonlySet<string>,\n    ): JsonValue {\n        const branches = schema.list('oneOf');\n        if (branches.length > 0) {\n            return this.valueOf(branches[0]!, fieldName, seen);\n        }\n        const merged = schema.list('allOf');\n        if (merged.length > 0) {\n            return this.mergedValueOf(merged, fieldName, seen);\n        }\n        const enumValues = this.lens.enumValuesOf(schema);\n        if (enumValues.length > 0) {\n            return enumValues[0]!;\n        }\n        return this.typedValueOf(schema, fieldName, seen);\n    }\n\n    private mergedValueOf(\n        branches: readonly JsonNode[],\n        fieldName: string,\n        seen: ReadonlySet<string>,\n    ): JsonValue {\n        const merged: JsonMap = {};\n        for (const branch of branches) {\n            const value = this.valueOf(branch, fieldName, seen);\n            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {\n                Object.assign(merged, value);\n            }\n        }\n        return merged;\n    }\n\n    private typedValueOf(\n        schema: JsonNode,\n        fieldName: string,\n        seen: ReadonlySet<string>,\n    ): JsonValue {\n        const declared = this.shape.declaredType(schema);\n        if (declared === 'array') {\n            return [this.valueOf(schema.at('items'), fieldName, seen)];\n        }\n        if (declared === 'object' || schema.at('properties').isObject()) {\n            return this.objectValueOf(schema, seen);\n        }\n        if (declared === 'integer' || declared === 'number') {\n            return 0;\n        }\n        if (declared === 'boolean') {\n            return true;\n        }\n        return this.stringValueOf(schema, fieldName);\n    }\n\n    private objectValueOf(schema: JsonNode, seen: ReadonlySet<string>): JsonValue {\n        const body: JsonMap = {};\n        for (const property of schema.at('properties').entries()) {\n            body[property.key] = this.valueOf(property.value, property.key, seen);\n        }\n        if (\n            schema.at('properties').entries().length === 0 &&\n            schema.at('additionalProperties').isObject()\n        ) {\n            body['key'] = this.valueOf(schema.at('additionalProperties'), 'value', seen);\n        }\n        return body;\n    }\n\n    private stringValueOf(schema: JsonNode, fieldName: string): JsonValue {\n        const format = schema.text('format');\n        if (format === 'date-time') {\n            return '2026-01-31T09:30:00Z';\n        }\n        if (format === 'date') {\n            return '2026-01-31';\n        }\n        if (format === 'uuid') {\n            return '00000000-0000-0000-0000-000000000000';\n        }\n        return fieldName === '' ? 'string' : fieldName;\n    }\n\n    /** The sample serialization: two-space JSON, which is what a partner pastes into their client. */\n    render(value: JsonValue | undefined): string {\n        if (value === undefined) {\n            return '';\n        }\n        return JSON.stringify(value, null, 2);\n    }\n}\n"]}

package/src/spec/FieldTree.d.ts

@@ -0,0 +1,75 @@
+import { JsonNode } from './JsonNode';
+import { NamedSchema } from './ApiSpec';
+import { SchemaLens } from './SchemaLens';
+/**
+ * One row of the parameter tree: the field name, the type label, the prose, and — for an enum — the
+ * COMPLETE list of possible values. All four are read from the spec; none is authored here.
+ */
+export declare class FieldNode {
+    readonly name: string;
+    readonly typeLabel: string;
+    readonly description: string;
+    readonly required: boolean;
+    readonly possibleValues: readonly string[];
+    /** The named object this field's type is, when it has a page of its own. Else `undefined`. */
+    readonly linkTo: NamedSchema | undefined;
+    readonly children: readonly FieldNode[];
+    constructor(name: string, typeLabel: string, description: string, required: boolean, possibleValues: readonly string[], 
+    /** The named object this field's type is, when it has a page of its own. Else `undefined`. */
+    linkTo: NamedSchema | undefined, children: readonly FieldNode[]);
+}
+/**
+ * One branch of a `oneOf` request body, keyed by its discriminator value.
+ *
+ * Every branch renders EXPANDED, one after another, rather than behind tabs. A partner writing one
+ * handler needs every shape at once — and a tab is invisible to Ctrl-F and to print, so the shapes
+ * behind the unselected tabs are, for a reader searching the page, simply not documented.
+ */
+export declare class SchemaVariant {
+    readonly label: string;
+    readonly discriminatorValue: string;
+    readonly fields: readonly FieldNode[];
+    constructor(label: string, discriminatorValue: string, fields: readonly FieldNode[]);
+}
+/**
+ * Builds the parameter tree.
+ *
+ * ## Two trees on purpose: links here, full resolution in the example
+ *
+ * Every reference to a named OBJECT renders as a LINK to that object's own page, and the field's
+ * children are NOT inlined underneath it — the link IS the expansion. The generated example body
+ * (see `ExampleBuilder`) resolves the same references fully instead.
+ *
+ * Sharing one tree between them is the tempting simplification and it is wrong in both directions.
+ * A hyperlink cannot live inside a JSON sample, so a shared tree that links prints `"data": {}` on a
+ * partner's page; a shared tree that inlines gives every DTO as many copies as it has use sites, and
+ * none of them is the page a reader can link to.
+ *
+ * A named ENUM or scalar alias is NOT linked — it renders inline with its chips, because a page
+ * carrying one line of values costs the reader the context they were already reading.
+ */
+export declare class FieldTreeBuilder {
+    private readonly lens;
+    private readonly shape;
+    constructor(lens: SchemaLens);
+    /** The fields of a schema — its own, plus every `allOf` branch's, in declaration order. */
+    fieldsOf(schema: JsonNode): readonly FieldNode[];
+    /**
+     * The `oneOf` branches of a schema, labelled by the discriminator value that selects each one.
+     * Empty when the schema is not a union, which is what tells a renderer to draw one flat tree.
+     */
+    variantsOf(schema: JsonNode): readonly SchemaVariant[];
+    /** The `propertyName` a discriminated union switches on, or the empty string when there is none. */
+    discriminatorPropertyOf(schema: JsonNode): string;
+    private discriminatorValueOf;
+    private fieldOf;
+    /** For `array<Order>`, the page `Order` lives on — the row links, the array bracket does not. */
+    private linkedItemOf;
+    /**
+     * The nested rows of an INLINE shape — an anonymous object, or an array of one. A named object
+     * never gets children here; it got a link instead, which is what stops this recursing forever
+     * on a self-referential DTO.
+     */
+    private childrenOf;
+    private requiredNamesOf;
+}

package/src/spec/FieldTree.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldTreeBuilder = exports.SchemaVariant = exports.FieldNode = void 0;
+const SchemaShape_1 = require("./SchemaShape");
+/**
+ * One row of the parameter tree: the field name, the type label, the prose, and — for an enum — the
+ * COMPLETE list of possible values. All four are read from the spec; none is authored here.
+ */
+class FieldNode {
+    name;
+    typeLabel;
+    description;
+    required;
+    possibleValues;
+    linkTo;
+    children;
+    constructor(name, typeLabel, description, required, possibleValues, 
+    /** The named object this field's type is, when it has a page of its own. Else `undefined`. */
+    linkTo, children) {
+        this.name = name;
+        this.typeLabel = typeLabel;
+        this.description = description;
+        this.required = required;
+        this.possibleValues = possibleValues;
+        this.linkTo = linkTo;
+        this.children = children;
+    }
+}
+exports.FieldNode = FieldNode;
+/**
+ * One branch of a `oneOf` request body, keyed by its discriminator value.
+ *
+ * Every branch renders EXPANDED, one after another, rather than behind tabs. A partner writing one
+ * handler needs every shape at once — and a tab is invisible to Ctrl-F and to print, so the shapes
+ * behind the unselected tabs are, for a reader searching the page, simply not documented.
+ */
+class SchemaVariant {
+    label;
+    discriminatorValue;
+    fields;
+    constructor(label, discriminatorValue, fields) {
+        this.label = label;
+        this.discriminatorValue = discriminatorValue;
+        this.fields = fields;
+    }
+}
+exports.SchemaVariant = SchemaVariant;
+/**
+ * Builds the parameter tree.
+ *
+ * ## Two trees on purpose: links here, full resolution in the example
+ *
+ * Every reference to a named OBJECT renders as a LINK to that object's own page, and the field's
+ * children are NOT inlined underneath it — the link IS the expansion. The generated example body
+ * (see `ExampleBuilder`) resolves the same references fully instead.
+ *
+ * Sharing one tree between them is the tempting simplification and it is wrong in both directions.
+ * A hyperlink cannot live inside a JSON sample, so a shared tree that links prints `"data": {}` on a
+ * partner's page; a shared tree that inlines gives every DTO as many copies as it has use sites, and
+ * none of them is the page a reader can link to.
+ *
+ * A named ENUM or scalar alias is NOT linked — it renders inline with its chips, because a page
+ * carrying one line of values costs the reader the context they were already reading.
+ */
+class FieldTreeBuilder {
+    lens;
+    shape = new SchemaShape_1.SchemaShape();
+    constructor(lens) {
+        this.lens = lens;
+    }
+    /** The fields of a schema — its own, plus every `allOf` branch's, in declaration order. */
+    fieldsOf(schema) {
+        const resolved = this.lens.resolve(schema);
+        const fields = [];
+        for (const branch of resolved.list('allOf')) {
+            fields.push(...this.fieldsOf(branch));
+        }
+        const required = this.requiredNamesOf(resolved);
+        for (const property of resolved.at('properties').entries()) {
+            fields.push(this.fieldOf(property, required.includes(property.key)));
+        }
+        return fields;
+    }
+    /**
+     * The `oneOf` branches of a schema, labelled by the discriminator value that selects each one.
+     * Empty when the schema is not a union, which is what tells a renderer to draw one flat tree.
+     */
+    variantsOf(schema) {
+        const branches = this.lens.branchesOf(schema);
+        if (branches.length === 0) {
+            return [];
+        }
+        const mapping = this.lens.resolve(schema).at('discriminator').at('mapping');
+        const variants = [];
+        for (const branch of branches) {
+            const label = this.lens.label(branch);
+            variants.push(new SchemaVariant(label, this.discriminatorValueOf(mapping, label), this.fieldsOf(branch)));
+        }
+        return variants;
+    }
+    /** The `propertyName` a discriminated union switches on, or the empty string when there is none. */
+    discriminatorPropertyOf(schema) {
+        return this.lens.resolve(schema).at('discriminator').text('propertyName') ?? '';
+    }
+    discriminatorValueOf(mapping, typeName) {
+        for (const entry of mapping.entries()) {
+            const pointer = entry.value.asText();
+            if (pointer !== undefined && pointer.endsWith(`/${typeName}`)) {
+                return entry.key;
+            }
+        }
+        return '';
+    }
+    fieldOf(property, required) {
+        const named = this.lens.named(property.value);
+        const linked = named !== undefined && named.hasOwnPage ? named : undefined;
+        return new FieldNode(property.key, this.lens.label(property.value), this.lens.describe(property.value), required, this.lens.enumValuesOf(property.value), linked ?? this.linkedItemOf(property.value), linked === undefined ? this.childrenOf(property.value) : []);
+    }
+    /** For `array<Order>`, the page `Order` lives on — the row links, the array bracket does not. */
+    linkedItemOf(property) {
+        if (this.shape.declaredType(this.lens.resolve(property)) !== 'array') {
+            return undefined;
+        }
+        const named = this.lens.named(this.lens.resolve(property).at('items'));
+        return named !== undefined && named.hasOwnPage ? named : undefined;
+    }
+    /**
+     * The nested rows of an INLINE shape — an anonymous object, or an array of one. A named object
+     * never gets children here; it got a link instead, which is what stops this recursing forever
+     * on a self-referential DTO.
+     */
+    childrenOf(property) {
+        const resolved = this.lens.resolve(property);
+        if (this.shape.declaredType(resolved) === 'array') {
+            const items = resolved.at('items');
+            return this.lens.named(items) === undefined ? this.fieldsOf(items) : [];
+        }
+        if (resolved.at('properties').isObject()) {
+            return this.fieldsOf(resolved);
+        }
+        return [];
+    }
+    requiredNamesOf(schema) {
+        const names = [];
+        for (const entry of schema.list('required')) {
+            const name = entry.asText();
+            if (name !== undefined) {
+                names.push(name);
+            }
+        }
+        return names;
+    }
+}
+exports.FieldTreeBuilder = FieldTreeBuilder;
+//# sourceMappingURL=FieldTree.js.map

package/src/spec/FieldTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldTree.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/spec/FieldTree.ts"],"names":[],"mappings":"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","sourcesContent":["import { JsonEntry, JsonNode } from './JsonNode';\nimport { NamedSchema } from './ApiSpec';\nimport { SchemaLens } from './SchemaLens';\nimport { SchemaShape } from './SchemaShape';\n\n/**\n * One row of the parameter tree: the field name, the type label, the prose, and — for an enum — the\n * COMPLETE list of possible values. All four are read from the spec; none is authored here.\n */\nexport class FieldNode {\n    constructor(\n        readonly name: string,\n        readonly typeLabel: string,\n        readonly description: string,\n        readonly required: boolean,\n        readonly possibleValues: readonly string[],\n        /** The named object this field's type is, when it has a page of its own. Else `undefined`. */\n        readonly linkTo: NamedSchema | undefined,\n        readonly children: readonly FieldNode[],\n    ) {}\n}\n\n/**\n * One branch of a `oneOf` request body, keyed by its discriminator value.\n *\n * Every branch renders EXPANDED, one after another, rather than behind tabs. A partner writing one\n * handler needs every shape at once — and a tab is invisible to Ctrl-F and to print, so the shapes\n * behind the unselected tabs are, for a reader searching the page, simply not documented.\n */\nexport class SchemaVariant {\n    constructor(\n        readonly label: string,\n        readonly discriminatorValue: string,\n        readonly fields: readonly FieldNode[],\n    ) {}\n}\n\n/**\n * Builds the parameter tree.\n *\n * ## Two trees on purpose: links here, full resolution in the example\n *\n * Every reference to a named OBJECT renders as a LINK to that object's own page, and the field's\n * children are NOT inlined underneath it — the link IS the expansion. The generated example body\n * (see `ExampleBuilder`) resolves the same references fully instead.\n *\n * Sharing one tree between them is the tempting simplification and it is wrong in both directions.\n * A hyperlink cannot live inside a JSON sample, so a shared tree that links prints `\"data\": {}` on a\n * partner's page; a shared tree that inlines gives every DTO as many copies as it has use sites, and\n * none of them is the page a reader can link to.\n *\n * A named ENUM or scalar alias is NOT linked — it renders inline with its chips, because a page\n * carrying one line of values costs the reader the context they were already reading.\n */\nexport class FieldTreeBuilder {\n    private readonly shape = new SchemaShape();\n\n    constructor(private readonly lens: SchemaLens) {}\n\n    /** The fields of a schema — its own, plus every `allOf` branch's, in declaration order. */\n    fieldsOf(schema: JsonNode): readonly FieldNode[] {\n        const resolved = this.lens.resolve(schema);\n        const fields: FieldNode[] = [];\n        for (const branch of resolved.list('allOf')) {\n            fields.push(...this.fieldsOf(branch));\n        }\n        const required = this.requiredNamesOf(resolved);\n        for (const property of resolved.at('properties').entries()) {\n            fields.push(this.fieldOf(property, required.includes(property.key)));\n        }\n        return fields;\n    }\n\n    /**\n     * The `oneOf` branches of a schema, labelled by the discriminator value that selects each one.\n     * Empty when the schema is not a union, which is what tells a renderer to draw one flat tree.\n     */\n    variantsOf(schema: JsonNode): readonly SchemaVariant[] {\n        const branches = this.lens.branchesOf(schema);\n        if (branches.length === 0) {\n            return [];\n        }\n        const mapping = this.lens.resolve(schema).at('discriminator').at('mapping');\n        const variants: SchemaVariant[] = [];\n        for (const branch of branches) {\n            const label = this.lens.label(branch);\n            variants.push(\n                new SchemaVariant(\n                    label,\n                    this.discriminatorValueOf(mapping, label),\n                    this.fieldsOf(branch),\n                ),\n            );\n        }\n        return variants;\n    }\n\n    /** The `propertyName` a discriminated union switches on, or the empty string when there is none. */\n    discriminatorPropertyOf(schema: JsonNode): string {\n        return this.lens.resolve(schema).at('discriminator').text('propertyName') ?? '';\n    }\n\n    private discriminatorValueOf(mapping: JsonNode, typeName: string): string {\n        for (const entry of mapping.entries()) {\n            const pointer = entry.value.asText();\n            if (pointer !== undefined && pointer.endsWith(`/${typeName}`)) {\n                return entry.key;\n            }\n        }\n        return '';\n    }\n\n    private fieldOf(property: JsonEntry, required: boolean): FieldNode {\n        const named = this.lens.named(property.value);\n        const linked = named !== undefined && named.hasOwnPage ? named : undefined;\n        return new FieldNode(\n            property.key,\n            this.lens.label(property.value),\n            this.lens.describe(property.value),\n            required,\n            this.lens.enumValuesOf(property.value),\n            linked ?? this.linkedItemOf(property.value),\n            linked === undefined ? this.childrenOf(property.value) : [],\n        );\n    }\n\n    /** For `array<Order>`, the page `Order` lives on — the row links, the array bracket does not. */\n    private linkedItemOf(property: JsonNode): NamedSchema | undefined {\n        if (this.shape.declaredType(this.lens.resolve(property)) !== 'array') {\n            return undefined;\n        }\n        const named = this.lens.named(this.lens.resolve(property).at('items'));\n        return named !== undefined && named.hasOwnPage ? named : undefined;\n    }\n\n    /**\n     * The nested rows of an INLINE shape — an anonymous object, or an array of one. A named object\n     * never gets children here; it got a link instead, which is what stops this recursing forever\n     * on a self-referential DTO.\n     */\n    private childrenOf(property: JsonNode): readonly FieldNode[] {\n        const resolved = this.lens.resolve(property);\n        if (this.shape.declaredType(resolved) === 'array') {\n            const items = resolved.at('items');\n            return this.lens.named(items) === undefined ? this.fieldsOf(items) : [];\n        }\n        if (resolved.at('properties').isObject()) {\n            return this.fieldsOf(resolved);\n        }\n        return [];\n    }\n\n    private requiredNamesOf(schema: JsonNode): readonly string[] {\n        const names: string[] = [];\n        for (const entry of schema.list('required')) {\n            const name = entry.asText();\n            if (name !== undefined) {\n                names.push(name);\n            }\n        }\n        return names;\n    }\n}\n"]}

package/src/spec/JsonNode.d.ts

@@ -0,0 +1,53 @@
+/** Everything an OpenAPI document can hold. It is JSON, so this is the whole value space. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | JsonMap;
+/** The object case of {@link JsonValue}, named so the recursive alias can refer to it. */
+export type JsonMap = {
+    [key: string]: JsonValue;
+};
+/**
+ * A READER over one JSON value, and the reason this package can render a document it did not
+ * generate.
+ *
+ * The alternative — importing `@webpieces/openapi-generator`'s document classes, which are
+ * structurally identical — would make "generated by us" a precondition for "renderable by us"
+ * (issue #985). So the document is read STRUCTURALLY: every accessor asks "is there a string at this
+ * key", never "is this an instance of our class", and a key that is absent or the wrong shape comes
+ * back `undefined` instead of throwing. A conforming document written by any other tool reads the
+ * same way.
+ *
+ * It is deliberately total rather than validating. A docs site that refuses to render because one
+ * optional `description` was a number is worse than one that renders the rest: the reader loses a
+ * whole reference over a field they were not looking at.
+ */
+export declare class JsonNode {
+    readonly raw: unknown;
+    constructor(raw: unknown);
+    /** True when this node is a JSON object (and not an array, and not null). */
+    isObject(): boolean;
+    /** The keys of this object, in document order. Empty for anything that is not an object. */
+    keys(): readonly string[];
+    /** The child at `key`, always a node — an absent key reads as a node over `undefined`. */
+    at(key: string): JsonNode;
+    /** The string at `key`, or `undefined` when it is absent or is not a string. */
+    text(key: string): string | undefined;
+    /** This node itself as a string, or `undefined`. */
+    asText(): string | undefined;
+    /** The boolean at `key`, or `undefined`. A missing flag is not `false`; the caller decides. */
+    flag(key: string): boolean | undefined;
+    /** The number at `key`, or `undefined`. */
+    number(key: string): number | undefined;
+    /** The array at `key` as nodes. Empty when absent or not an array. */
+    list(key: string): readonly JsonNode[];
+    /** This node itself as an array of nodes. Empty when it is not an array. */
+    asList(): readonly JsonNode[];
+    /** Every own entry of this object as `[key, node]`, in document order. */
+    entries(): readonly JsonEntry[];
+    /** True when this node holds nothing at all — an absent key, or an explicit `null`. */
+    isAbsent(): boolean;
+}
+/** One `[key, value]` pair of a JSON object, as a class because it is data. */
+export declare class JsonEntry {
+    readonly key: string;
+    readonly value: JsonNode;
+    constructor(key: string, value: JsonNode);
+}