schema-components 1.20.0 → 1.22.0

package/dist/openapi/ApiCallbacks.d.mts

@@ -1,4 +1,4 @@
-import { T as SchemaMeta } from "../types-C9zw9wbX.mjs";
+import { w as SchemaMeta } from "../types-BrRMV0en.mjs";
 import { CallbackInfo } from "./parser.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/ApiLinks.d.mts

@@ -1,4 +1,4 @@
-import { T as SchemaMeta } from "../types-C9zw9wbX.mjs";
+import { w as SchemaMeta } from "../types-BrRMV0en.mjs";
 import { LinkInfo } from "./parser.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/ApiResponseHeaders.d.mts

@@ -1,4 +1,4 @@
-import { T as SchemaMeta } from "../types-C9zw9wbX.mjs";
+import { w as SchemaMeta } from "../types-BrRMV0en.mjs";
 import { HeaderInfo } from "./parser.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/ApiSecurity.d.mts

@@ -1,4 +1,4 @@
-import { T as SchemaMeta } from "../types-C9zw9wbX.mjs";
+import { w as SchemaMeta } from "../types-BrRMV0en.mjs";
 import { SecurityRequirement, SecurityScheme } from "./parser.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/ApiSecurity.mjs

@@ -1,5 +1,58 @@
+import { isObject } from "../core/guards.mjs";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/openapi/ApiSecurity.tsx
+/**
+* The four OAuth 2 flow keys defined by OpenAPI 3.x. Listed in the
+* canonical specification order so renders are deterministic.
+*/
+const OAUTH_FLOW_KEYS = [
+	"implicit",
+	"password",
+	"clientCredentials",
+	"authorizationCode"
+];
+/**
+* Known Security Scheme `type` values per the OpenAPI 3.0/3.1 spec.
+* Used to flag unknown values in the rendered output so authors can
+* spot typos like `mutalTLS` without consulting the diagnostic sink.
+*/
+const KNOWN_SECURITY_SCHEME_TYPES = new Set([
+	"apiKey",
+	"http",
+	"oauth2",
+	"openIdConnect",
+	"mutualTLS"
+]);
+function readString(source, key) {
+	const value = source[key];
+	return typeof value === "string" ? value : void 0;
+}
+function readScopes(source) {
+	const scopes = source.scopes;
+	const result = /* @__PURE__ */ new Map();
+	if (!isObject(scopes)) return result;
+	for (const [name, description] of Object.entries(scopes)) {
+		if (typeof description !== "string") continue;
+		result.set(name, description);
+	}
+	return result;
+}
+function extractFlows(flows) {
+	if (flows === void 0) return [];
+	const result = [];
+	for (const name of OAUTH_FLOW_KEYS) {
+		const flow = flows[name];
+		if (!isObject(flow)) continue;
+		result.push({
+			name,
+			authorizationUrl: readString(flow, "authorizationUrl"),
+			tokenUrl: readString(flow, "tokenUrl"),
+			refreshUrl: readString(flow, "refreshUrl"),
+			scopes: readScopes(flow)
+		});
+	}
+	return result;
+}
 function ApiSecurity({ requirements, schemes }) {
 	if (requirements.length === 0) return null;
 	return /* @__PURE__ */ jsxs("section", {
@@ -13,13 +66,7 @@ function ApiSecurity({ requirements, schemes }) {
 						"data-security-name": true,
 						children: req.name
 					}),
-					scheme !== void 0 && /* @__PURE__ */ jsxs(Fragment, { children: [scheme.type !== void 0 && /* @__PURE__ */ jsx("span", {
-						"data-security-type": true,
-						children: scheme.type
-					}), scheme.description && /* @__PURE__ */ jsx("span", {
-						"data-security-description": true,
-						children: scheme.description
-					})] }),
+					scheme !== void 0 && /* @__PURE__ */ jsx(SchemeDetails, { scheme }),
 					req.scopes.length > 0 && /* @__PURE__ */ jsx("span", {
 						"data-security-scopes": true,
 						children: req.scopes.join(", ")
@@ -29,5 +76,78 @@ function ApiSecurity({ requirements, schemes }) {
 		})]
 	});
 }
+function SchemeDetails({ scheme }) {
+	const flows = extractFlows(scheme.flows);
+	const isKnownType = scheme.type !== void 0 && KNOWN_SECURITY_SCHEME_TYPES.has(scheme.type);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [
+		scheme.type !== void 0 && /* @__PURE__ */ jsxs("span", {
+			"data-security-type": true,
+			"data-security-type-unknown": isKnownType ? void 0 : "true",
+			children: [scheme.type, !isKnownType && " (unknown type)"]
+		}),
+		scheme.description !== void 0 && /* @__PURE__ */ jsx("span", {
+			"data-security-description": true,
+			children: scheme.description
+		}),
+		scheme.scheme !== void 0 && /* @__PURE__ */ jsx("span", {
+			"data-security-http-scheme": true,
+			children: scheme.scheme
+		}),
+		scheme.bearerFormat !== void 0 && /* @__PURE__ */ jsx("span", {
+			"data-security-bearer-format": true,
+			children: scheme.bearerFormat
+		}),
+		scheme.name !== void 0 && /* @__PURE__ */ jsx("span", {
+			"data-security-apikey-name": true,
+			children: scheme.name
+		}),
+		scheme.location !== void 0 && /* @__PURE__ */ jsx("span", {
+			"data-security-apikey-in": true,
+			children: scheme.location
+		}),
+		scheme.openIdConnectUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+			"data-security-openid-url": true,
+			href: scheme.openIdConnectUrl,
+			children: scheme.openIdConnectUrl
+		}),
+		flows.length > 0 && /* @__PURE__ */ jsx("section", {
+			"data-security-flows": true,
+			children: flows.map((flow) => /* @__PURE__ */ jsx(FlowDetails, { flow }, flow.name))
+		})
+	] });
+}
+function FlowDetails({ flow }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-security-flow": flow.name,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"data-security-flow-name": true,
+				children: flow.name
+			}),
+			flow.authorizationUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+				"data-security-flow-authorization-url": true,
+				href: flow.authorizationUrl,
+				children: flow.authorizationUrl
+			}),
+			flow.tokenUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+				"data-security-flow-token-url": true,
+				href: flow.tokenUrl,
+				children: flow.tokenUrl
+			}),
+			flow.refreshUrl !== void 0 && /* @__PURE__ */ jsx("a", {
+				"data-security-flow-refresh-url": true,
+				href: flow.refreshUrl,
+				children: flow.refreshUrl
+			}),
+			flow.scopes.size > 0 && /* @__PURE__ */ jsx("dl", {
+				"data-security-flow-scopes": true,
+				children: [...flow.scopes.entries()].map(([name, description]) => /* @__PURE__ */ jsxs("div", {
+					"data-security-flow-scope": name,
+					children: [/* @__PURE__ */ jsx("dt", { children: name }), /* @__PURE__ */ jsx("dd", { children: description })]
+				}, name))
+			})
+		]
+	});
+}
 //#endregion
 export { ApiSecurity };

package/dist/openapi/components.d.mts

@@ -1,10 +1,99 @@
-import { T as SchemaMeta, u as FieldOverride } from "../types-C9zw9wbX.mjs";
-import { a as InferResponseFields, i as InferRequestBodyFields, m as UnsafeFields, r as InferParameterOverrides } from "../typeInference-CDoD_LZ_.mjs";
+import { u as FieldOverride, w as SchemaMeta } from "../types-BrRMV0en.mjs";
+import { r as DiagnosticSink } from "../diagnostics-D0QCYGv0.mjs";
+import { a as InferParameterOverrides, g as UnsafeFields, o as InferRequestBodyFields, s as InferResponseFields } from "../typeInference-DkcUHfaM.mjs";
 import { WidgetMap } from "../react/SchemaComponent.mjs";
 import { ReactNode } from "react";
 
 //#region src/openapi/components.d.ts
-interface ApiOperationProps<Doc = unknown, Path extends string = string, Method extends string = string> {
+/**
+ * The canonical set of HTTP method strings recognised by OpenAPI 3.x.
+ * Used to constrain `Method` generics so autocomplete on typed
+ * documents only suggests methods the path item actually declares,
+ * not arbitrary string keys.
+ */
+type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
+/**
+ * Extract the literal path keys from a document type, or the broad
+ * `string` fallback when the document is untyped at compile time.
+ *
+ * The `string extends keyof D["paths"]` guard distinguishes a typed
+ * `as const` document (whose `paths` map has literal keys) from a
+ * runtime `Record<string, unknown>` document (whose `keyof` collapses
+ * to `string`). For the runtime case we surface `string` so callers
+ * pass arbitrary path values without losing the existing freedom.
+ */
+type PathKeysOf<D> = D extends {
+  paths: infer P;
+} ? P extends Record<string, unknown> ? string extends keyof P ? string : Extract<keyof P, string> : string : string;
+/**
+ * Extract the methods declared on a specific path item, restricted to
+ * the OpenAPI-recognised method set so non-method extension keys
+ * (e.g. `summary`, `description`, `parameters`) do not pollute the
+ * autocomplete.
+ *
+ * Runtime documents (typed `Record<string, unknown>`) widen back to
+ * `string` so callers retain the freedom to pass arbitrary method
+ * strings without surfacing an `HttpMethod` constraint at runtime
+ * call sites.
+ */
+type MethodKeysOf<D, P extends string> = IsRuntimeDoc<D> extends true ? string : D extends {
+  paths: infer Paths;
+} ? Paths extends Record<string, unknown> ? P extends keyof Paths ? Extract<keyof Paths[P], HttpMethod> : HttpMethod : HttpMethod : HttpMethod;
+/**
+ * True for the runtime-document sentinel — a `Record<string, unknown>`
+ * (or wider) where `keyof` collapses to `string`. Used to drop
+ * narrow-constraint defaults so runtime callers retain the prior
+ * freedom to pass arbitrary path/method/status values.
+ */
+type IsRuntimeDoc<D> = D extends Record<string, unknown> ? string extends keyof D ? true : false : false;
+/**
+ * Extract the status-code keys declared by an operation's `responses`
+ * map. Includes class wildcards (`2XX`, etc.) and the `default`
+ * sentinel; runtime documents widen to `string`.
+ */
+type StatusKeysOf<D, P extends string, M extends string> = D extends {
+  paths: infer Paths;
+} ? Paths extends Record<string, unknown> ? P extends keyof Paths ? Paths[P] extends Record<string, unknown> ? M extends keyof Paths[P] ? Paths[P][M] extends {
+  responses: infer R;
+} ? R extends Record<string, unknown> ? string extends keyof R ? string : Extract<keyof R, string> : string : string : string : string : string : string : string;
+/**
+ * Extract the content-type keys declared on a request body's
+ * `content` map for the given path and method. Runtime documents
+ * widen to `string`.
+ */
+type RequestContentTypesOf<D, P extends string, M extends string> = D extends {
+  paths: infer Paths;
+} ? Paths extends Record<string, unknown> ? P extends keyof Paths ? Paths[P] extends Record<string, unknown> ? M extends keyof Paths[P] ? Paths[P][M] extends {
+  requestBody: {
+    content: infer C;
+  };
+} ? C extends Record<string, unknown> ? string extends keyof C ? string : Extract<keyof C, string> : string : string : string : string : string : string : string;
+/**
+ * Extract the content-type keys declared on a response entry's
+ * `content` map for the given path, method, and status. Runtime
+ * documents widen to `string`.
+ */
+type ResponseContentTypesOf<D, P extends string, M extends string, S extends string> = D extends {
+  paths: infer Paths;
+} ? Paths extends Record<string, unknown> ? P extends keyof Paths ? Paths[P] extends Record<string, unknown> ? M extends keyof Paths[P] ? Paths[P][M] extends {
+  responses: infer R;
+} ? R extends Record<string, unknown> ? S extends keyof R ? R[S] extends {
+  content: infer C;
+} ? C extends Record<string, unknown> ? string extends keyof C ? string : Extract<keyof C, string> : string : string : string : string : string : string : string : string : string : string;
+/**
+ * Diagnostics props accepted by every top-level OpenAPI component.
+ *
+ * `onDiagnostic` is the sink invoked for each event surfaced by the
+ * normalisation pipeline (duplicate body parameter, dropped Swagger
+ * feature, divisible-by conflict, unknown JSON Schema dialect,
+ * relative-ref resolved, etc.). `strict` converts every emitted
+ * diagnostic into a thrown `SchemaNormalisationError`.
+ */
+interface ApiDiagnosticsProps {
+  onDiagnostic?: DiagnosticSink;
+  strict?: boolean;
+}
+interface ApiOperationProps<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
@@ -12,7 +101,7 @@ interface ApiOperationProps<Doc = unknown, Path extends string = string, Method
   onRequestBodyChange?: (value: unknown) => void;
   responseValue?: unknown;
   meta?: SchemaMeta;
-  requestBodyFields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path, Method> : Record<string, FieldOverride>;
+  requestBodyFields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path & string, Method & string> : Record<string, FieldOverride>;
   /** Escape hatch for recursive schemas where type-level inference fails.
    * Typed as Record<string, FieldOverride> — use when the schema contains
    * deeply nested $ref chains.
@@ -21,7 +110,7 @@ interface ApiOperationProps<Doc = unknown, Path extends string = string, Method
   /** Instance-scoped widgets. */
   widgets?: WidgetMap;
 }
-declare function ApiOperation<Doc = unknown, Path extends string = string, Method extends string = string>({
+declare function ApiOperation<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>>({
   schema: doc,
   path,
   method,
@@ -30,37 +119,48 @@ declare function ApiOperation<Doc = unknown, Path extends string = string, Metho
   responseValue,
   meta,
   requestBodyFields,
-  widgets
+  widgets,
+  onDiagnostic,
+  strict
 }: ApiOperationProps<Doc, Path, Method>): ReactNode;
-interface ApiParametersProps<Doc = unknown, Path extends string = string, Method extends string = string> {
+interface ApiParametersProps<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
   meta?: SchemaMeta;
-  overrides?: Doc extends Record<string, unknown> ? InferParameterOverrides<Doc, Path, Method> : Record<string, FieldOverride>;
+  overrides?: Doc extends Record<string, unknown> ? InferParameterOverrides<Doc, Path & string, Method & string> : Record<string, FieldOverride>;
   /** Instance-scoped widgets. */
   widgets?: WidgetMap;
 }
-declare function ApiParameters<Doc = unknown, Path extends string = string, Method extends string = string>({
+declare function ApiParameters<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>>({
   schema: doc,
   path,
   method,
   meta,
   overrides,
-  widgets
+  widgets,
+  onDiagnostic,
+  strict
 }: ApiParametersProps<Doc, Path, Method>): ReactNode;
-interface ApiRequestBodyProps<Doc = unknown, Path extends string = string, Method extends string = string> {
+interface ApiRequestBodyProps<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>, ContentType extends RequestContentTypesOf<Doc, Path, Method> = RequestContentTypesOf<Doc, Path, Method>> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
+  /**
+   * Media type whose schema should be rendered for the request body.
+   * Defaults to the union of declared content types so callers can
+   * omit it; supply explicitly to narrow `fields` inference to a
+   * specific media type via {@link InferRequestBodyFields}.
+   */
+  contentType?: ContentType;
   value?: unknown;
   onChange?: (value: unknown) => void;
   meta?: SchemaMeta;
-  fields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path, Method> : Record<string, FieldOverride>;
+  fields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path & string, Method & string, ContentType & string> : Record<string, FieldOverride>;
   /** Instance-scoped widgets. */
   widgets?: WidgetMap;
 }
-declare function ApiRequestBody<Doc = unknown, Path extends string = string, Method extends string = string>({
+declare function ApiRequestBody<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>, ContentType extends RequestContentTypesOf<Doc, Path, Method> = RequestContentTypesOf<Doc, Path, Method>>({
   schema: doc,
   path,
   method,
@@ -68,20 +168,29 @@ declare function ApiRequestBody<Doc = unknown, Path extends string = string, Met
   onChange,
   meta,
   fields,
-  widgets
-}: ApiRequestBodyProps<Doc, Path, Method>): ReactNode;
-interface ApiResponseProps<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string> {
+  widgets,
+  onDiagnostic,
+  strict
+}: ApiRequestBodyProps<Doc, Path, Method, ContentType>): ReactNode;
+interface ApiResponseProps<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>, Status extends StatusKeysOf<Doc, Path, Method> = StatusKeysOf<Doc, Path, Method>, ContentType extends ResponseContentTypesOf<Doc, Path, Method, Status> = ResponseContentTypesOf<Doc, Path, Method, Status>> extends ApiDiagnosticsProps {
   schema: Doc;
   path: Path;
   method: Method;
   status: Status;
+  /**
+   * Media type whose schema should be rendered. Defaults to the
+   * union of declared content types so callers can omit it;
+   * supply explicitly to narrow `fields` inference via
+   * {@link InferResponseFields}.
+   */
+  contentType?: ContentType;
   value?: unknown;
   meta?: SchemaMeta;
-  fields?: Doc extends Record<string, unknown> ? InferResponseFields<Doc, Path, Method, Status> : Record<string, FieldOverride>;
+  fields?: Doc extends Record<string, unknown> ? InferResponseFields<Doc, Path & string, Method & string, Status & string, ContentType & string> : Record<string, FieldOverride>;
   /** Instance-scoped widgets. */
   widgets?: WidgetMap;
 }
-declare function ApiResponse<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string>({
+declare function ApiResponse<Doc = unknown, Path extends PathKeysOf<Doc> = PathKeysOf<Doc>, Method extends MethodKeysOf<Doc, Path> = MethodKeysOf<Doc, Path>, Status extends StatusKeysOf<Doc, Path, Method> = StatusKeysOf<Doc, Path, Method>, ContentType extends ResponseContentTypesOf<Doc, Path, Method, Status> = ResponseContentTypesOf<Doc, Path, Method, Status>>({
   schema: doc,
   path,
   method,
@@ -89,7 +198,52 @@ declare function ApiResponse<Doc = unknown, Path extends string = string, Method
   value,
   meta,
   fields,
-  widgets
-}: ApiResponseProps<Doc, Path, Method, Status>): ReactNode;
+  widgets,
+  onDiagnostic,
+  strict
+}: ApiResponseProps<Doc, Path, Method, Status, ContentType>): ReactNode;
+/**
+ * Render a single OpenAPI 3.1 webhook by name. A webhook is a Path Item
+ * Object under the document's top-level `webhooks` map; once resolved,
+ * its operations are structurally identical to operations under `paths`.
+ *
+ * Internally, this delegates to `ApiOperation` for each method present
+ * on the webhook's Path Item Object. The parser's `lookupPathItem`
+ * resolves webhook names through the same code path as paths, so
+ * `ApiOperation` works for both with no special-casing in the renderer.
+ */
+interface ApiWebhookProps extends ApiDiagnosticsProps {
+  schema: unknown;
+  /** Webhook name (key under the document's `webhooks` map). */
+  name: string;
+  /** Instance-scoped widgets, forwarded to each rendered operation. */
+  widgets?: WidgetMap;
+  meta?: SchemaMeta;
+}
+declare function ApiWebhook({
+  schema: doc,
+  name,
+  widgets,
+  meta,
+  onDiagnostic,
+  strict
+}: ApiWebhookProps): ReactNode;
+/**
+ * Render every OpenAPI 3.1 webhook declared on the document, one
+ * `<ApiWebhook>` per entry. Returns `null` when the document has no
+ * `webhooks` map or it is empty.
+ */
+interface ApiWebhooksProps extends ApiDiagnosticsProps {
+  schema: unknown;
+  widgets?: WidgetMap;
+  meta?: SchemaMeta;
+}
+declare function ApiWebhooks({
+  schema: doc,
+  widgets,
+  meta,
+  onDiagnostic,
+  strict
+}: ApiWebhooksProps): ReactNode;
 //#endregion
-export { ApiOperation, ApiOperationProps, ApiParameters, ApiParametersProps, ApiRequestBody, ApiRequestBodyProps, ApiResponse, ApiResponseProps };
+export { ApiOperation, ApiOperationProps, ApiParameters, ApiParametersProps, ApiRequestBody, ApiRequestBodyProps, ApiResponse, ApiResponseProps, ApiWebhook, ApiWebhookProps, ApiWebhooks, ApiWebhooksProps };