schema-components 1.21.0 → 1.23.0

package/dist/openapi/components.mjs

@@ -1,10 +1,12 @@
 import { isObject, toRecordOrUndefined } from "../core/guards.mjs";
+import { emitDiagnostic } from "../core/diagnostics.mjs";
+import { extractRootMetaFromJson } from "../core/adapter.mjs";
 import { walk } from "../core/walker.mjs";
 import { ApiCallbacks } from "./ApiCallbacks.mjs";
 import { ApiLinks } from "./ApiLinks.mjs";
 import { ApiResponseHeaders } from "./ApiResponseHeaders.mjs";
 import { ApiSecurity } from "./ApiSecurity.mjs";
-import { getLinks, getSecurityRequirements, getSecuritySchemes, listCallbacks } from "./parser.mjs";
+import { getExternalDocs, getLinks, getSecurityRequirements, getSecuritySchemes, getXmlInfo, listCallbacks, listWebhooks } from "./parser.mjs";
 import { joinPath, renderField, sanitisePrefix } from "../react/SchemaComponent.mjs";
 import { getParsed, resolveOperationFromParsed, resolveParametersFromParsed, resolveRequestBodyFromParsed, resolveResponseFromParsed, toDoc } from "./resolve.mjs";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -30,10 +32,29 @@ function buildDiagnostics(onDiagnostic, strict) {
 	if (strict === true) opts.strict = true;
 	return opts;
 }
+/**
+* Coerce an `unknown` `schema` prop to a document record. Returns
+* `undefined` when the prop is not a plain object, surfacing a
+* `doc-not-object` diagnostic so silent "empty document" misbehaviour
+* (the historic `toDoc` `{}` fallback) is impossible.
+*
+* Components MUST short-circuit when this returns `undefined` rather
+* than rendering empty operation lists.
+*/
+function resolveRootDoc(doc, diagnostics) {
+	const resolved = toDoc(doc);
+	if (resolved === void 0) emitDiagnostic(diagnostics, {
+		code: "doc-not-object",
+		message: "OpenAPI document prop is not a plain object; nothing to render",
+		pointer: "",
+		detail: { received: typeof doc }
+	});
+	return resolved;
+}
 function noop() {}
 function renderSchema(schema, rootDocument, options) {
 	if (!isObject(schema)) throw new Error("renderSchema received a non-object schema from the resolver.");
-	const rootMeta = extractRootMetaFromSchema(schema);
+	const rootMeta = extractRootMetaFromJson(schema);
 	const componentMeta = {};
 	if (options.readOnly === true) componentMeta.readOnly = true;
 	if (options.meta !== void 0) for (const [k, v] of Object.entries(options.meta)) componentMeta[k] = v;
@@ -49,14 +70,55 @@ function renderSchema(schema, rootDocument, options) {
 	};
 	return renderField(tree, options.value, options.onChange ?? noop, void 0, makeRenderChild(options.rootPath), options.rootPath, options.widgets);
 }
+/**
+* Render a Schema Object or Operation Object's `externalDocs` as a
+* simple anchor with optional descriptive text. Returns `null` when no
+* externalDocs are attached so callers can drop it into JSX without an
+* extra guard.
+*/
+function ExternalDocsLink({ externalDocs }) {
+	if (externalDocs === void 0) return null;
+	return /* @__PURE__ */ jsx("p", {
+		"data-external-docs": true,
+		children: /* @__PURE__ */ jsx("a", {
+			href: externalDocs.url,
+			children: externalDocs.description ?? externalDocs.url
+		})
+	});
+}
+/**
+* Render a Schema Object's `xml` metadata as a footnote. The library
+* does not render XML payloads natively, but the metadata still
+* carries author intent (namespaces, element names, wrapping rules).
+* Surface it so consumers can audit the dropped feature without
+* losing the underlying information.
+*/
+function SchemaXmlFootnote({ xml }) {
+	if (xml === void 0) return null;
+	return /* @__PURE__ */ jsx("aside", {
+		"data-schema-xml": true,
+		children: /* @__PURE__ */ jsxs("small", { children: [
+			"XML representation",
+			xml.name !== void 0 && ` — name: ${xml.name}`,
+			xml.namespace !== void 0 && ` — namespace: ${xml.namespace}`,
+			xml.prefix !== void 0 && ` — prefix: ${xml.prefix}`,
+			xml.attribute && " — attribute",
+			xml.wrapped && " — wrapped"
+		] })
+	});
+}
 function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBodyChange, responseValue, meta, requestBodyFields, widgets, onDiagnostic, strict }) {
-	const rootDoc = toDoc(doc);
-	const parsed = getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict));
-	const resolved = resolveOperationFromParsed(parsed, path, method);
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
+	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const parsed = getParsed(rootDoc, diagnostics);
+	const resolved = resolveOperationFromParsed(parsed, path, method, diagnostics);
 	const securityReqs = getSecurityRequirements(parsed, path, method);
 	const securitySchemes = getSecuritySchemes(parsed);
 	const callbacks = listCallbacks(parsed, path, method);
-	const instancePrefix = sanitisePrefix(useId());
+	const operationExternalDocs = getExternalDocs(resolved.operation.operation);
+	const requestBodyXml = resolved.requestBody?.schema !== void 0 ? getXmlInfo(resolved.requestBody.schema) : void 0;
 	return /* @__PURE__ */ jsxs("section", {
 		"data-operation": `${method.toUpperCase()} ${path}`,
 		children: [
@@ -64,6 +126,7 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 				operation: resolved.operation,
 				pathItem: resolved.pathItem
 			}),
+			/* @__PURE__ */ jsx(ExternalDocsLink, { externalDocs: operationExternalDocs }),
 			/* @__PURE__ */ jsx(ApiSecurity, {
 				requirements: securityReqs,
 				schemes: securitySchemes
@@ -76,7 +139,9 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 					rootDoc,
 					meta,
 					widgets,
-					idPrefix: joinPath(instancePrefix, "params")
+					idPrefix: joinPath(instancePrefix, "params"),
+					diagnostics,
+					pointerPrefix: operationPointer(path, method)
 				})]
 			}),
 			resolved.requestBody?.schema !== void 0 && /* @__PURE__ */ jsxs("section", {
@@ -98,7 +163,8 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 						meta,
 						widgets,
 						rootPath: joinPath(instancePrefix, "requestBody")
-					})
+					}),
+					/* @__PURE__ */ jsx(SchemaXmlFootnote, { xml: requestBodyXml })
 				]
 			}),
 			resolved.responses.length > 0 && /* @__PURE__ */ jsxs("section", {
@@ -119,9 +185,11 @@ function ApiOperation({ schema: doc, path, method, requestBodyValue, onRequestBo
 	});
 }
 function ApiParameters({ schema: doc, path, method, meta, overrides, widgets, onDiagnostic, strict }) {
-	const rootDoc = toDoc(doc);
-	const params = resolveParametersFromParsed(getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict)), path, method);
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
 	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const params = resolveParametersFromParsed(getParsed(rootDoc, diagnostics), path, method);
 	if (params.length === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
 		"data-parameters": true,
@@ -131,15 +199,20 @@ function ApiParameters({ schema: doc, path, method, meta, overrides, widgets, on
 			overrides,
 			meta,
 			widgets,
-			idPrefix: instancePrefix
+			idPrefix: instancePrefix,
+			diagnostics,
+			pointerPrefix: operationPointer(path, method)
 		})]
 	});
 }
 function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fields, widgets, onDiagnostic, strict }) {
-	const rootDoc = toDoc(doc);
-	const requestBody = resolveRequestBodyFromParsed(getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict)), path, method);
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
 	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const requestBody = resolveRequestBodyFromParsed(getParsed(rootDoc, diagnostics), path, method);
 	if (requestBody?.schema === void 0) return null;
+	const requestBodyXml = getXmlInfo(requestBody.schema);
 	return /* @__PURE__ */ jsxs("section", {
 		"data-request-body": true,
 		children: [
@@ -159,15 +232,18 @@ function ApiRequestBody({ schema: doc, path, method, value, onChange, meta, fiel
 				meta,
 				widgets,
 				rootPath: instancePrefix
-			})
+			}),
+			/* @__PURE__ */ jsx(SchemaXmlFootnote, { xml: requestBodyXml })
 		]
 	});
 }
 function ApiResponse({ schema: doc, path, method, status, value, meta, fields, widgets, onDiagnostic, strict }) {
-	const rootDoc = toDoc(doc);
-	const parsed = getParsed(rootDoc, buildDiagnostics(onDiagnostic, strict));
-	const response = resolveResponseFromParsed(parsed, path, method, status);
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
 	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const parsed = getParsed(rootDoc, diagnostics);
+	const response = resolveResponseFromParsed(parsed, path, method, status);
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
 		"data-status": status,
 		children: [
@@ -189,6 +265,49 @@ function ApiResponse({ schema: doc, path, method, status, value, meta, fields, w
 		idPrefix: instancePrefix
 	});
 }
+function ApiWebhook({ schema: doc, name, widgets, meta, onDiagnostic, strict }) {
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
+	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const webhook = listWebhooks(getParsed(rootDoc, diagnostics)).find((w) => w.name === name);
+	if (webhook === void 0) return null;
+	return /* @__PURE__ */ jsxs("section", {
+		"data-webhook": name,
+		"data-instance": instancePrefix,
+		children: [/* @__PURE__ */ jsxs("h3", { children: ["Webhook: ", name] }), webhook.operations.map((op) => {
+			const opProps = {
+				schema: rootDoc,
+				path: name,
+				method: op.method
+			};
+			if (widgets !== void 0) opProps.widgets = widgets;
+			if (meta !== void 0) opProps.meta = meta;
+			return /* @__PURE__ */ jsx(ApiOperation, { ...opProps }, `${name}-${op.method}`);
+		})]
+	});
+}
+function ApiWebhooks({ schema: doc, widgets, meta, onDiagnostic, strict }) {
+	const diagnostics = buildDiagnostics(onDiagnostic, strict);
+	const instancePrefix = sanitisePrefix(useId());
+	const rootDoc = resolveRootDoc(doc, diagnostics);
+	if (rootDoc === void 0) return null;
+	const webhooks = listWebhooks(getParsed(rootDoc, diagnostics));
+	if (webhooks.length === 0) return null;
+	return /* @__PURE__ */ jsxs("section", {
+		"data-webhooks": true,
+		"data-instance": instancePrefix,
+		children: [/* @__PURE__ */ jsx("h2", { children: "Webhooks" }), webhooks.map((webhook) => {
+			const props = {
+				schema: rootDoc,
+				name: webhook.name
+			};
+			if (widgets !== void 0) props.widgets = widgets;
+			if (meta !== void 0) props.meta = meta;
+			return /* @__PURE__ */ jsx(ApiWebhook, { ...props }, webhook.name);
+		})]
+	});
+}
 function OperationHeader({ operation, pathItem }) {
 	return /* @__PURE__ */ jsxs("header", { children: [
 		(pathItem.summary !== void 0 || pathItem.description !== void 0) && /* @__PURE__ */ jsxs("div", {
@@ -217,25 +336,39 @@ function OperationHeader({ operation, pathItem }) {
 		})
 	] });
 }
-function ParameterList({ parameters, rootDoc, overrides, meta, widgets, idPrefix }) {
-	return /* @__PURE__ */ jsx(Fragment, { children: parameters.map((param) => /* @__PURE__ */ jsxs("div", {
-		"data-parameter": param.name,
-		children: [
-			/* @__PURE__ */ jsxs("label", { children: [param.name, param.required && /* @__PURE__ */ jsx("span", {
-				"data-required": true,
-				children: "*"
-			})] }),
-			param.description && /* @__PURE__ */ jsx("span", {
-				"data-description": true,
-				children: param.description
-			}),
-			renderSchema(param.schema ?? { type: "string" }, rootDoc, {
-				meta: buildParamMeta(param, overrides, meta),
-				widgets,
-				rootPath: joinPath(idPrefix, param.name)
-			})
-		]
-	}, param.name)) });
+function ParameterList({ parameters, rootDoc, overrides, meta, widgets, idPrefix, diagnostics, pointerPrefix }) {
+	return /* @__PURE__ */ jsx(Fragment, { children: parameters.map((param) => {
+		if (param.schema === void 0) {
+			emitDiagnostic(diagnostics, {
+				code: "parameter-missing-schema",
+				message: `Parameter "${param.name}" has no schema; rendering skipped`,
+				pointer: `${pointerPrefix}/parameters/${param.name}`,
+				detail: {
+					name: param.name,
+					location: param.location
+				}
+			});
+			return null;
+		}
+		return /* @__PURE__ */ jsxs("div", {
+			"data-parameter": param.name,
+			children: [
+				/* @__PURE__ */ jsxs("label", { children: [param.name, param.required && /* @__PURE__ */ jsx("span", {
+					"data-required": true,
+					children: "*"
+				})] }),
+				param.description && /* @__PURE__ */ jsx("span", {
+					"data-description": true,
+					children: param.description
+				}),
+				renderSchema(param.schema, rootDoc, {
+					meta: buildParamMeta(param, overrides, meta),
+					widgets,
+					rootPath: joinPath(idPrefix, param.name)
+				})
+			]
+		}, param.name);
+	}) });
 }
 function ResponseCard({ response, rootDoc, parsed, value, fields, meta, widgets, path, method, idPrefix }) {
 	if (response.schema === void 0) return /* @__PURE__ */ jsxs("div", {
@@ -268,6 +401,19 @@ function ResponseCard({ response, rootDoc, parsed, value, fields, meta, widgets,
 		]
 	});
 }
+/**
+* Compose the JSON Pointer prefix for an operation's Parameter Object
+* map. Paths conventionally begin with `/` so they live under
+* `#/paths/<escaped path>/<method>`; OpenAPI 3.1 webhook names (which
+* have no leading slash) live under `#/webhooks/<name>/<method>`.
+*
+* JSON Pointer (RFC 6901) requires `~` → `~0` and `/` → `~1`. The
+* escape order matters: `~` first to avoid double-escaping the `~1`
+* produced for `/`.
+*/
+function operationPointer(path, method) {
+	return `/${path.startsWith("/") ? "paths" : "webhooks"}/${path.replace(/~/g, "~0").replace(/\//g, "~1")}/${method}`;
+}
 function buildParamMeta(param, overrides, meta) {
 	const result = {};
 	if (param.description !== void 0) result.description = param.description;
@@ -277,20 +423,5 @@ function buildParamMeta(param, overrides, meta) {
 	if (meta !== void 0) for (const [k, v] of Object.entries(meta)) result[k] = v;
 	return Object.keys(result).length > 0 ? result : void 0;
 }
-/**
-* Extract root-level meta (title, description, readOnly, etc.) from a
-* JSON Schema node. Mirrors `extractRootMetaFromJson` in the adapter so
-* pre-normalised schemas (extracted from `getParsed`) still surface root
-* meta to the walker without an extra adapter round-trip.
-*/
-function extractRootMetaFromSchema(jsonSchema) {
-	const meta = {};
-	if (jsonSchema.readOnly === true) meta.readOnly = true;
-	if (jsonSchema.writeOnly === true) meta.writeOnly = true;
-	if (typeof jsonSchema.description === "string") meta.description = jsonSchema.description;
-	if (typeof jsonSchema.title === "string") meta.title = jsonSchema.title;
-	if (typeof jsonSchema.deprecated === "boolean") meta.deprecated = jsonSchema.deprecated;
-	return Object.keys(meta).length > 0 ? meta : void 0;
-}
 //#endregion
-export { ApiOperation, ApiParameters, ApiRequestBody, ApiResponse };
+export { ApiOperation, ApiParameters, ApiRequestBody, ApiResponse, ApiWebhook, ApiWebhooks };

package/dist/openapi/parser.d.mts

@@ -1,4 +1,5 @@
-import { m as JsonObject } from "../types-BnxPEElk.mjs";
+import { m as JsonObject } from "../types-BTB73MB8.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-BS2kaUyE.mjs";
 
 //#region src/openapi/parser.d.ts
 interface OpenApiDocument {
@@ -86,17 +87,17 @@ interface LinkInfo {
 }
 declare function parseOpenApiDocument(doc: JsonObject): OpenApiDocument;
 declare function getSchema(parsed: OpenApiDocument, ref: string): JsonObject | undefined;
-declare function listOperations(parsed: OpenApiDocument): OperationInfo[];
-declare function getParameters(parsed: OpenApiDocument, path: string, method: string): ParameterInfo[];
+declare function listOperations(parsed: OpenApiDocument, diagnostics?: DiagnosticsOptions): OperationInfo[];
+declare function getParameters(parsed: OpenApiDocument, path: string, method: string, diagnostics?: DiagnosticsOptions): ParameterInfo[];
 declare function getRequestBody(parsed: OpenApiDocument, path: string, method: string): RequestBodyInfo | undefined;
-declare function getResponses(parsed: OpenApiDocument, path: string, method: string): ResponseInfo[];
+declare function getResponses(parsed: OpenApiDocument, path: string, method: string, diagnostics?: DiagnosticsOptions): ResponseInfo[];
 declare function getSecurityRequirements(parsed: OpenApiDocument, path: string, method: string): SecurityRequirement[];
 declare function getSecuritySchemes(parsed: OpenApiDocument): Map<string, SecurityScheme>;
-declare function getResponseHeaders(response: JsonObject, doc?: JsonObject): Map<string, HeaderInfo>;
-declare function listWebhooks(parsed: OpenApiDocument): WebhookInfo[];
+declare function getResponseHeaders(response: JsonObject, doc?: JsonObject, diagnostics?: DiagnosticsOptions): Map<string, HeaderInfo>;
+declare function listWebhooks(parsed: OpenApiDocument, diagnostics?: DiagnosticsOptions): WebhookInfo[];
 declare function getExternalDocs(obj: JsonObject): ExternalDocs | undefined;
 declare function getXmlInfo(schema: JsonObject): XmlInfo | undefined;
-declare function listCallbacks(parsed: OpenApiDocument, path: string, method: string): CallbackInfo[];
-declare function getLinks(parsed: OpenApiDocument, path: string, method: string, statusCode: string): LinkInfo[];
+declare function listCallbacks(parsed: OpenApiDocument, path: string, method: string, diagnostics?: DiagnosticsOptions): CallbackInfo[];
+declare function getLinks(parsed: OpenApiDocument, path: string, method: string, statusCode: string, diagnostics?: DiagnosticsOptions): LinkInfo[];
 //#endregion
 export { CallbackInfo, ExternalDocs, HeaderInfo, LinkInfo, OpenApiDocument, OperationInfo, ParameterInfo, ParameterLocation, RequestBodyInfo, ResponseInfo, SecurityRequirement, SecurityScheme, WebhookInfo, XmlInfo, getExternalDocs, getLinks, getParameters, getRequestBody, getResponseHeaders, getResponses, getSchema, getSecurityRequirements, getSecuritySchemes, getXmlInfo, listCallbacks, listOperations, listWebhooks, parseOpenApiDocument };