schema-components 1.21.0 → 1.23.0

package/dist/openapi/ApiCallbacks.d.mts

@@ -1,4 +1,4 @@
-import { T as SchemaMeta } from "../types-BnxPEElk.mjs";
+import { w as SchemaMeta } from "../types-BTB73MB8.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-BnxPEElk.mjs";
+import { w as SchemaMeta } from "../types-BTB73MB8.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-BnxPEElk.mjs";
+import { w as SchemaMeta } from "../types-BTB73MB8.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-BnxPEElk.mjs";
+import { w as SchemaMeta } from "../types-BTB73MB8.mjs";
 import { SecurityRequirement, SecurityScheme } from "./parser.mjs";
 import { ReactNode } from "react";
 

package/dist/openapi/ApiSecurity.mjs

@@ -11,6 +11,18 @@ const OAUTH_FLOW_KEYS = [
 	"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;
@@ -66,10 +78,12 @@ 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__ */ jsx("span", {
+		scheme.type !== void 0 && /* @__PURE__ */ jsxs("span", {
 			"data-security-type": true,
-			children: scheme.type
+			"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,

package/dist/openapi/components.d.mts

@@ -1,10 +1,160 @@
-import { T as SchemaMeta, u as FieldOverride } from "../types-BnxPEElk.mjs";
-import { r as DiagnosticSink } from "../diagnostics-CbBPsxSt.mjs";
-import { a as InferResponseFields, i as InferRequestBodyFields, m as UnsafeFields, r as InferParameterOverrides } from "../typeInference-Bxw3NOG1.mjs";
+import { u as FieldOverride, w as SchemaMeta } from "../types-BTB73MB8.mjs";
+import { r as DiagnosticSink } from "../diagnostics-BS2kaUyE.mjs";
+import { InferParameterOverrides, InferRequestBodyFields, InferResponseFields } from "../core/typeInference.mjs";
 import { WidgetMap } from "../react/SchemaComponent.mjs";
 import { ReactNode } from "react";
 
 //#region src/openapi/components.d.ts
+/**
+ * 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.
+ *
+ * For OpenAPI 3.1 documents the union includes keys from `webhooks`
+ * alongside `paths`, because `<ApiOperation>` / `<ApiRequestBody>` /
+ * `<ApiResponse>` resolve webhook names through the same code path as
+ * paths (see `lookupPathItem` in `openapi/resolve.ts`). Without the
+ * webhook keys, a typed `as const` 3.1 document that declares only
+ * webhooks would reject every `path` prop value at compile time
+ * ("Type 'string' is not assignable to type 'never'") despite working
+ * at runtime.
+ *
+ * When the document declares neither a `paths` nor a `webhooks` map
+ * the union falls back to `string` so untyped/foreign inputs keep
+ * working — the constraint is informational, not gating.
+ *
+ * The `string extends keyof P` 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> = HasPathsOrWebhooks<D> extends true ? PathsKey<D> | WebhooksKey<D> : string;
+/**
+ * `true` when `D` declares either a `paths` or a `webhooks` object,
+ * so the `PathKeysOf` union can be derived from real document keys
+ * instead of falling back to `string`.
+ */
+type HasPathsOrWebhooks<D> = D extends {
+  paths: Record<string, unknown>;
+} ? true : D extends {
+  webhooks: Record<string, unknown>;
+} ? true : false;
+/**
+ * Literal `paths` keys, or `never` when the document does not declare
+ * a `paths` object. Runtime documents (whose `keyof` collapses to
+ * `string`) widen to `string` so callers retain prior freedom.
+ */
+type PathsKey<D> = D extends {
+  paths: infer P;
+} ? P extends Record<string, unknown> ? string extends keyof P ? string : Extract<keyof P, string> : never : never;
+/**
+ * Literal `webhooks` keys, or `never` when the document does not
+ * declare a `webhooks` object (OpenAPI 3.1 only). Runtime documents
+ * widen to `string`.
+ */
+type WebhooksKey<D> = D extends {
+  webhooks: infer W;
+} ? W extends Record<string, unknown> ? string extends keyof W ? string : Extract<keyof W, string> : never : never;
+/**
+ * Extract the methods declared on a specific path or webhook 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. Untyped documents (`unknown`) also widen to `string` so
+ * consumers with no static doc info can supply extension methods —
+ * the canonical `HttpMethod` set is informational, not gating, when
+ * the document carries no structural information at all.
+ *
+ * When the document declares `paths` or `webhooks` but not the
+ * specific entry `P`, the union falls back to `HttpMethod` so callers
+ * can still target an authored operation that compile-time inference
+ * happens to miss (e.g. behind a deferred conditional type).
+ */
+type MethodKeysOf<D, P extends string> = IsRuntimeDoc<D> extends true ? string : unknown extends D ? string : HasPathsOrWebhooks<D> extends true ? MethodKeysWithFallback<D, P> : HttpMethod;
+/**
+ * Union of literal methods extracted from `paths[P]` and `webhooks[P]`,
+ * falling back to the canonical `HttpMethod` set when neither map
+ * declares the requested entry.
+ */
+type MethodKeysWithFallback<D, P extends string> = [MethodKeysFromPaths<D, P> | MethodKeysFromWebhooks<D, P>] extends [never] ? HttpMethod : MethodKeysFromPaths<D, P> | MethodKeysFromWebhooks<D, P>;
+/**
+ * Methods declared on `paths[P]`, restricted to `HttpMethod`.
+ * Returns `never` when the document has no matching path entry.
+ */
+type MethodKeysFromPaths<D, P extends string> = D extends {
+  paths: infer Paths;
+} ? Paths extends Record<string, unknown> ? P extends keyof Paths ? Extract<keyof Paths[P], HttpMethod> : never : never : never;
+/**
+ * Methods declared on `webhooks[P]`, restricted to `HttpMethod`.
+ * Returns `never` when the document has no matching webhook entry.
+ */
+type MethodKeysFromWebhooks<D, P extends string> = D extends {
+  webhooks: infer Webhooks;
+} ? Webhooks extends Record<string, unknown> ? P extends keyof Webhooks ? Extract<keyof Webhooks[P], HttpMethod> : never : never : never;
+/**
+ * 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;
+/**
+ * Generic "operation under a given map" extractor used by every
+ * downstream `xxKeysOf` helper. Returns the Operation Object for the
+ * given path-or-webhook name and method, or `never` when no such
+ * entry exists.
+ */
+type OperationAt<Map_, P extends string, M extends string> = Map_ extends Record<string, unknown> ? P extends keyof Map_ ? Map_[P] extends Record<string, unknown> ? M extends keyof Map_[P] ? Map_[P][M] : never : never : never : never;
+/**
+ * Locate the Operation Object for `path`/`method` across both `paths`
+ * and `webhooks`. The OpenAPI 3.1 spec assigns webhooks the same
+ * Path Item shape as `paths` entries, so structural inference is
+ * identical once the operation is resolved.
+ */
+type ResolveOperation<D, P extends string, M extends string> = (D extends {
+  paths: infer Paths;
+} ? OperationAt<Paths, P, M> : never) | (D extends {
+  webhooks: infer Webhooks;
+} ? OperationAt<Webhooks, P, M> : never);
+/**
+ * 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> = ResolveOperation<D, P, M> extends {
+  responses: infer R;
+} ? R extends Record<string, unknown> ? string extends keyof R ? string : Extract<keyof R, 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> = ResolveOperation<D, P, M> extends {
+  requestBody: {
+    content: infer C;
+  };
+} ? C extends Record<string, unknown> ? string extends keyof C ? string : Extract<keyof C, 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> = ResolveOperation<D, 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;
 /**
  * Diagnostics props accepted by every top-level OpenAPI component.
  *
@@ -18,7 +168,7 @@ interface ApiDiagnosticsProps {
   onDiagnostic?: DiagnosticSink;
   strict?: boolean;
 }
-interface ApiOperationProps<Doc = unknown, Path extends string = string, Method extends string = string> extends ApiDiagnosticsProps {
+interface ApiOperationProps<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;
@@ -26,16 +176,20 @@ 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>;
-  /** Escape hatch for recursive schemas where type-level inference fails.
-   * Typed as Record<string, FieldOverride> — use when the schema contains
-   * deeply nested $ref chains.
+  /**
+   * Media type whose request body schema drives `requestBodyFields`
+   * inference. Defaults to the union of declared content types so
+   * callers can omit it; supply explicitly to narrow inference to a
+   * specific media type. Mirrors {@link ApiRequestBodyProps.contentType}
+   * so `<ApiOperation>` can target non-JSON request bodies with the
+   * same precision as `<ApiRequestBody>`.
    */
-  unsafeFields?: UnsafeFields;
+  requestBodyContentType?: ContentType;
+  requestBodyFields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path & string, Method & string, ContentType & string> : Record<string, FieldOverride>;
   /** 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>, ContentType extends RequestContentTypesOf<Doc, Path, Method> = RequestContentTypesOf<Doc, Path, Method>>({
   schema: doc,
   path,
   method,
@@ -47,17 +201,17 @@ declare function ApiOperation<Doc = unknown, Path extends string = string, Metho
   widgets,
   onDiagnostic,
   strict
-}: ApiOperationProps<Doc, Path, Method>): ReactNode;
-interface ApiParametersProps<Doc = unknown, Path extends string = string, Method extends string = string> extends ApiDiagnosticsProps {
+}: ApiOperationProps<Doc, Path, Method, ContentType>): ReactNode;
+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,
@@ -67,18 +221,25 @@ declare function ApiParameters<Doc = unknown, Path extends string = string, Meth
   onDiagnostic,
   strict
 }: ApiParametersProps<Doc, Path, Method>): ReactNode;
-interface ApiRequestBodyProps<Doc = unknown, Path extends string = string, Method extends string = string> extends ApiDiagnosticsProps {
+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,
@@ -89,19 +250,26 @@ declare function ApiRequestBody<Doc = unknown, Path extends string = string, Met
   widgets,
   onDiagnostic,
   strict
-}: ApiRequestBodyProps<Doc, Path, Method>): ReactNode;
-interface ApiResponseProps<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string> extends ApiDiagnosticsProps {
+}: 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,
@@ -112,6 +280,49 @@ declare function ApiResponse<Doc = unknown, Path extends string = string, Method
   widgets,
   onDiagnostic,
   strict
-}: ApiResponseProps<Doc, Path, Method, Status>): ReactNode;
+}: 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 };