zudoku 0.34.4 → 0.35.0

package/src/lib/oas/graphql/index.ts

@@ -88,6 +88,16 @@ const JSONScalar = builder.addScalarType("JSON", GraphQLJSON);
 const JSONObjectScalar = builder.addScalarType("JSONObject", GraphQLJSONObject);
 const JSONSchemaScalar = builder.addScalarType("JSONSchema", GraphQLJSONSchema);
 
+const resolveExtensions = (obj: Record<string, any>) => {
+  const extensions: Record<string, any> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (key.startsWith("x-")) {
+      extensions[key] = value;
+    }
+  }
+  return extensions;
+};
+
 export const getAllTags = (schema: OpenAPIDocument): TagObject[] => {
   const rootTags = schema.tags ?? [];
   const operationTags = new Set(
@@ -191,6 +201,11 @@ const TagItem = builder.objectRef<TagObject>("TagItem").implement({
   fields: (t) => ({
     name: t.exposeString("name"),
     description: t.exposeString("description", { nullable: true }),
+    extensions: t.field({
+      type: JSONObjectScalar,
+      resolve: (parent) => resolveExtensions(parent),
+      nullable: true,
+    }),
   }),
 });
 
@@ -249,6 +264,11 @@ const ParameterItem = builder
         nullable: true,
       }),
       schema: t.expose("schema", { type: JSONSchemaScalar, nullable: true }),
+      extensions: t.field({
+        type: JSONObjectScalar,
+        resolve: (parent) => resolveExtensions(parent),
+        nullable: true,
+      }),
     }),
   });
 
@@ -306,6 +326,11 @@ const ResponseItem = builder
       content: t.expose("content", { type: [MediaTypeItem], nullable: true }),
       headers: t.expose("headers", { type: JSONScalar, nullable: true }),
       links: t.expose("links", { type: JSONScalar, nullable: true }),
+      extensions: t.field({
+        type: JSONObjectScalar,
+        resolve: (parent) => resolveExtensions(parent),
+        nullable: true,
+      }),
     }),
   });
 
@@ -399,6 +424,11 @@ const OperationItem = builder
         nullable: true,
       }),
       deprecated: t.exposeBoolean("deprecated", { nullable: true }),
+      extensions: t.field({
+        type: JSONObjectScalar,
+        resolve: (parent) => resolveExtensions(parent),
+        nullable: true,
+      }),
     }),
   });
 
@@ -462,6 +492,11 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
           );
         }),
     }),
+    extensions: t.field({
+      type: JSONObjectScalar,
+      resolve: (root) => resolveExtensions(root),
+      nullable: true,
+    }),
   }),
 });
 

package/src/lib/plugins/markdown/MdxPage.tsx

@@ -13,7 +13,7 @@ import {
 import type { MdxComponentsType } from "../../util/MdxComponents.js";
 import { cn } from "../../util/cn.js";
 import { Toc } from "./Toc.js";
-import { MarkdownPluginDefaultOptions, MDXImport } from "./index.js";
+import { type MarkdownPluginDefaultOptions, type MDXImport } from "./index.js";
 
 declare global {
   interface Window {
@@ -91,7 +91,7 @@ export const MdxPage = ({
 
   return (
     <div
-      className="xl:grid grid-cols-[--sidecar-grid-cols] gap-8 justify-between"
+      className="grid grid-cols-1 xl:grid-cols-[--sidecar-grid-cols] gap-8 justify-between"
       data-pagefind-filter="section:markdown"
       data-pagefind-meta="section:markdown"
     >

package/src/lib/plugins/openapi/OperationList.tsx

@@ -38,6 +38,7 @@ export const OperationsFragment = graphql(/* GraphQL */ `
     contentTypes
     path
     deprecated
+    extensions
     parameters {
       name
       in
@@ -248,14 +249,14 @@ export const OperationList = ({
           )}
         </Collapsible>
         {tagDescription && (
-          <p
+          <div
             className={cn(
               ProseClasses,
               "my-4 max-w-full prose-img:max-w-prose",
             )}
           >
             <Markdown content={tagDescription} />
-          </p>
+          </div>
         )}
       </div>
       <hr />

package/src/lib/plugins/openapi/Sidecar.tsx

@@ -111,7 +111,7 @@ export const Sidecar = ({
   const [selectedExample, setSelectedExample] = useState<unknown>();
 
   const selectedLang =
-    searchParams.get("lang") ?? options?.examplesDefaultLanguage ?? "shell";
+    searchParams.get("lang") ?? options?.examplesLanguage ?? "shell";
 
   const requestBodyContent = operation.requestBody?.content;
 
@@ -151,7 +151,7 @@ export const Sidecar = ({
             mimeType: "application/json",
           }
         : ({} as any),
-      headers: [],
+      headers: [{ name: "Content-Type", value: "application/json" }],
       queryString: [],
       httpVersion: "",
       cookies: [],
@@ -166,11 +166,18 @@ export const Sidecar = ({
     operation.method,
     operation.path,
     selectedServer,
-    result.data.schema.url,
     selectedLang,
   ]);
   const [ref, isOnScreen] = useOnScreen({ rootMargin: "200px 0px 200px 0px" });
 
+  const showPlayground =
+    isOnScreen &&
+    (operation.extensions["x-explorer-enabled"] === true ||
+      operation.extensions["x-playground-enabled"] === true ||
+      (operation.extensions["x-explorer-enabled"] === undefined &&
+        operation.extensions["x-playground-enabled"] === undefined &&
+        !options?.disablePlayground));
+
   return (
     <aside
       ref={ref}
@@ -186,7 +193,7 @@ export const Sidecar = ({
             &nbsp;
             {path}
           </span>
-          {isOnScreen && (
+          {showPlayground && (
             <PlaygroundDialogWrapper
               servers={result.data.schema.servers.map((server) => server.url)}
               operation={operation}

package/src/lib/plugins/openapi/SimpleSelect.tsx

@@ -21,7 +21,7 @@ export const SimpleSelect = ({
   <div className="grid">
     <select
       className={cn(
-        "row-start-1 col-start-1 border border-input text-foreground px-2 py-1 pe-6",
+        "w-full row-start-1 col-start-1 border border-input text-foreground px-2 py-1 pe-6",
         "rounded-md appearance-none bg-zinc-50 hover:bg-white dark:bg-zinc-800 hover:dark:bg-zinc-800/75",
         className,
       )}

package/src/lib/plugins/openapi/graphql/gql.ts

@@ -14,7 +14,7 @@ import * as types from "./graphql.js";
  */
 type Documents = {
   "\n  query ServersQuery($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      url\n      servers {\n        url\n      }\n    }\n  }\n": typeof types.ServersQueryDocument;
-  "\n  fragment OperationsFragment on OperationItem {\n    slug\n    summary\n    method\n    description\n    operationId\n    contentTypes\n    path\n    deprecated\n    parameters {\n      name\n      in\n      description\n      required\n      schema\n      style\n      examples {\n        name\n        description\n        externalValue\n        value\n        summary\n      }\n    }\n    requestBody {\n      content {\n        mediaType\n        encoding {\n          name\n        }\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        schema\n      }\n      description\n      required\n    }\n    responses {\n      statusCode\n      links\n      description\n      content {\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        mediaType\n        encoding {\n          name\n        }\n        schema\n      }\n    }\n  }\n": typeof types.OperationsFragmentFragmentDoc;
+  "\n  fragment OperationsFragment on OperationItem {\n    slug\n    summary\n    method\n    description\n    operationId\n    contentTypes\n    path\n    deprecated\n    extensions\n    parameters {\n      name\n      in\n      description\n      required\n      schema\n      style\n      examples {\n        name\n        description\n        externalValue\n        value\n        summary\n      }\n    }\n    requestBody {\n      content {\n        mediaType\n        encoding {\n          name\n        }\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        schema\n      }\n      description\n      required\n    }\n    responses {\n      statusCode\n      links\n      description\n      content {\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        mediaType\n        encoding {\n          name\n        }\n        schema\n      }\n    }\n  }\n": typeof types.OperationsFragmentFragmentDoc;
   "\n  query AllOperations(\n    $input: JSON!\n    $type: SchemaType!\n    $tag: String\n    $untagged: Boolean\n  ) {\n    schema(input: $input, type: $type) {\n      servers {\n        url\n      }\n      description\n      summary\n      title\n      url\n      version\n      tags(name: $tag) {\n        name\n        description\n      }\n      operations(tag: $tag, untagged: $untagged) {\n        slug\n        ...OperationsFragment\n      }\n    }\n  }\n": typeof types.AllOperationsDocument;
   "\n  query getServerQuery($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      url\n      servers {\n        url\n      }\n    }\n  }\n": typeof types.GetServerQueryDocument;
   "\n  query GetCategories($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      url\n      tags {\n        name\n      }\n    }\n  }\n": typeof types.GetCategoriesDocument;
@@ -23,7 +23,7 @@ type Documents = {
 const documents: Documents = {
   "\n  query ServersQuery($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      url\n      servers {\n        url\n      }\n    }\n  }\n":
     types.ServersQueryDocument,
-  "\n  fragment OperationsFragment on OperationItem {\n    slug\n    summary\n    method\n    description\n    operationId\n    contentTypes\n    path\n    deprecated\n    parameters {\n      name\n      in\n      description\n      required\n      schema\n      style\n      examples {\n        name\n        description\n        externalValue\n        value\n        summary\n      }\n    }\n    requestBody {\n      content {\n        mediaType\n        encoding {\n          name\n        }\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        schema\n      }\n      description\n      required\n    }\n    responses {\n      statusCode\n      links\n      description\n      content {\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        mediaType\n        encoding {\n          name\n        }\n        schema\n      }\n    }\n  }\n":
+  "\n  fragment OperationsFragment on OperationItem {\n    slug\n    summary\n    method\n    description\n    operationId\n    contentTypes\n    path\n    deprecated\n    extensions\n    parameters {\n      name\n      in\n      description\n      required\n      schema\n      style\n      examples {\n        name\n        description\n        externalValue\n        value\n        summary\n      }\n    }\n    requestBody {\n      content {\n        mediaType\n        encoding {\n          name\n        }\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        schema\n      }\n      description\n      required\n    }\n    responses {\n      statusCode\n      links\n      description\n      content {\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        mediaType\n        encoding {\n          name\n        }\n        schema\n      }\n    }\n  }\n":
     types.OperationsFragmentFragmentDoc,
   "\n  query AllOperations(\n    $input: JSON!\n    $type: SchemaType!\n    $tag: String\n    $untagged: Boolean\n  ) {\n    schema(input: $input, type: $type) {\n      servers {\n        url\n      }\n      description\n      summary\n      title\n      url\n      version\n      tags(name: $tag) {\n        name\n        description\n      }\n      operations(tag: $tag, untagged: $untagged) {\n        slug\n        ...OperationsFragment\n      }\n    }\n  }\n":
     types.AllOperationsDocument,
@@ -45,7 +45,7 @@ export function graphql(
  * The graphql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.
  */
 export function graphql(
-  source: "\n  fragment OperationsFragment on OperationItem {\n    slug\n    summary\n    method\n    description\n    operationId\n    contentTypes\n    path\n    deprecated\n    parameters {\n      name\n      in\n      description\n      required\n      schema\n      style\n      examples {\n        name\n        description\n        externalValue\n        value\n        summary\n      }\n    }\n    requestBody {\n      content {\n        mediaType\n        encoding {\n          name\n        }\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        schema\n      }\n      description\n      required\n    }\n    responses {\n      statusCode\n      links\n      description\n      content {\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        mediaType\n        encoding {\n          name\n        }\n        schema\n      }\n    }\n  }\n",
+  source: "\n  fragment OperationsFragment on OperationItem {\n    slug\n    summary\n    method\n    description\n    operationId\n    contentTypes\n    path\n    deprecated\n    extensions\n    parameters {\n      name\n      in\n      description\n      required\n      schema\n      style\n      examples {\n        name\n        description\n        externalValue\n        value\n        summary\n      }\n    }\n    requestBody {\n      content {\n        mediaType\n        encoding {\n          name\n        }\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        schema\n      }\n      description\n      required\n    }\n    responses {\n      statusCode\n      links\n      description\n      content {\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        mediaType\n        encoding {\n          name\n        }\n        schema\n      }\n    }\n  }\n",
 ): typeof import("./graphql.js").OperationsFragmentFragmentDoc;
 /**
  * The graphql function is used to parse GraphQL queries into a document that can be used by GraphQL clients.

package/src/lib/plugins/openapi/graphql/graphql.ts

@@ -67,6 +67,7 @@ export type OperationItem = {
   contentTypes: Array<Scalars["String"]["output"]>;
   deprecated?: Maybe<Scalars["Boolean"]["output"]>;
   description?: Maybe<Scalars["String"]["output"]>;
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
   method: Scalars["String"]["output"];
   operationId?: Maybe<Scalars["String"]["output"]>;
   parameters?: Maybe<Array<ParameterItem>>;
@@ -88,6 +89,7 @@ export type ParameterItem = {
   description?: Maybe<Scalars["String"]["output"]>;
   examples?: Maybe<Array<ExampleItem>>;
   explode?: Maybe<Scalars["Boolean"]["output"]>;
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
   in: ParameterIn;
   name: Scalars["String"]["output"];
   required?: Maybe<Scalars["Boolean"]["output"]>;
@@ -122,6 +124,7 @@ export type ResponseItem = {
   __typename?: "ResponseItem";
   content?: Maybe<Array<MediaTypeObject>>;
   description?: Maybe<Scalars["String"]["output"]>;
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
   headers?: Maybe<Scalars["JSON"]["output"]>;
   links?: Maybe<Scalars["JSON"]["output"]>;
   statusCode: Scalars["String"]["output"];
@@ -130,6 +133,7 @@ export type ResponseItem = {
 export type Schema = {
   __typename?: "Schema";
   description?: Maybe<Scalars["String"]["output"]>;
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
   openapi: Scalars["String"]["output"];
   operations: Array<OperationItem>;
   paths: Array<PathItem>;
@@ -171,6 +175,7 @@ export type Server = {
 export type TagItem = {
   __typename?: "TagItem";
   description?: Maybe<Scalars["String"]["output"]>;
+  extensions?: Maybe<Scalars["JSONObject"]["output"]>;
   name: Scalars["String"]["output"];
 };
 
@@ -198,6 +203,7 @@ export type OperationsFragmentFragment = {
   contentTypes: Array<string>;
   path: string;
   deprecated?: boolean | null;
+  extensions?: any | null;
   parameters?: Array<{
     __typename?: "ParameterItem";
     name: string;
@@ -376,6 +382,7 @@ export const OperationsFragmentFragmentDoc = new TypedDocumentString(
   contentTypes
   path
   deprecated
+  extensions
   parameters {
     name
     in
@@ -475,6 +482,7 @@ export const AllOperationsDocument = new TypedDocumentString(`
   contentTypes
   path
   deprecated
+  extensions
   parameters {
     name
     in

package/src/lib/plugins/openapi/index.tsx

@@ -1,7 +1,7 @@
 import type { ResultOf } from "@graphql-typed-document-node/core";
 import slugify from "@sindresorhus/slugify";
 import { CirclePlayIcon, LogInIcon } from "lucide-react";
-import { ReactNode } from "react";
+import { type ReactNode } from "react";
 import { matchPath } from "react-router";
 import { useAuth } from "../../authentication/hook.js";
 import { type ZudokuPlugin } from "../../core/plugins.js";
@@ -10,7 +10,7 @@ import { Button } from "../../ui/Button.js";
 import { joinUrl } from "../../util/joinUrl.js";
 import { GraphQLClient } from "./client/GraphQLClient.js";
 import { graphql } from "./graphql/index.js";
-import { OasPluginConfig } from "./interfaces.js";
+import { type OasPluginConfig } from "./interfaces.js";
 import type { PlaygroundContentProps } from "./playground/Playground.js";
 import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
 import { createSidebarCategory } from "./util/createSidebarCategory.js";
@@ -147,12 +147,11 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
       try {
         const versionParam = match?.params.version;
         const version = versionParam ?? getVersions(config).at(0);
-        const type = config.type;
-        const input =
-          config.type === "file" ? config.input[version!] : config.input;
+        const { type, options } = config;
+        const input = type === "file" ? config.input[version!] : config.input;
 
-        const collapsible = config.loadTags === true || config.type === "url";
-        const collapsed = !config.loadTags && config.type !== "url";
+        const collapsible = options?.loadTags === true || config.type === "url";
+        const collapsed = !options?.loadTags && config.type !== "url";
 
         // find  tag name by slug in config.tagPages
         const tagName = config.tagPages?.find(
@@ -164,7 +163,7 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
           client.fetch(GetOperationsQuery, {
             type,
             input,
-            tag: !config.loadTags ? tagName : undefined,
+            tag: !options?.loadTags ? tagName : undefined,
           }),
         ]);
 
@@ -182,7 +181,7 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
           );
 
           // skip empty categories
-          if (config.loadTags && operations.length === 0) {
+          if (options?.loadTags && operations.length === 0) {
             return [];
           }
 
@@ -190,7 +189,7 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
             label: tag.name,
             path: categoryPath,
             operations:
-              match?.params.tag !== UNTAGGED_PATH || config.loadTags
+              match?.params.tag !== UNTAGGED_PATH || options?.loadTags
                 ? operations
                 : [],
             collapsible,
@@ -204,7 +203,7 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
               label: "Other endpoints",
               path: joinUrl(basePath, versionParam, UNTAGGED_PATH),
               operations:
-                match?.params.tag === UNTAGGED_PATH || config.loadTags
+                match?.params.tag === UNTAGGED_PATH || options?.loadTags
                   ? operationsData.schema.untagged
                   : [],
               collapsible,

package/src/lib/plugins/openapi/interfaces.ts

@@ -10,26 +10,22 @@ export type ContextOasSource =
   | { type: "file"; input: DynamicInput }
   | { type: "raw"; input: string };
 
-export type OasPluginConfig = {
+type BaseOasConfig = {
   server?: string;
   navigationId?: string;
   skipPreload?: boolean;
   tagPages?: Array<string>;
-  loadTags?: boolean;
-} & OasPluginConfigOptions &
-  OasSource;
-
-export type OasPluginConfigOptions = {
   options?: {
-    examplesDefaultLanguage?: string;
+    examplesLanguage?: string;
+    disablePlayground?: boolean;
+    loadTags?: boolean;
   };
 };
 
-export type OasPluginContext = {
-  server?: string;
-  navigationId?: string;
-  skipPreload?: boolean;
-  version?: string;
-  versions: Record<string, string>;
-} & ContextOasSource &
-  OasPluginConfigOptions;
+export type OasPluginConfig = BaseOasConfig & OasSource;
+
+export type OasPluginContext = BaseOasConfig &
+  ContextOasSource & {
+    version?: string;
+    versions: Record<string, string>;
+  };

package/src/lib/ui/Callout.tsx

@@ -56,31 +56,49 @@ type CalloutProps = {
   title?: string;
   children: ReactNode;
   className?: string;
+  icon?: boolean;
 };
 
-export const Callout = ({ type, children, title, className }: CalloutProps) => {
+export const Callout = ({
+  type,
+  children,
+  title,
+  className,
+  icon = true,
+}: CalloutProps) => {
   const { border, bg, iconColor, titleColor, textColor, Icon } =
     stylesMap[type];
 
   return (
     <div
       className={cn(
-        "not-prose grid grid-cols-[min-content_1fr] grid-rows-[fit-content_1fr] gap-x-4 gap-y-2 text-md rounded-md border p-4",
+        "not-prose rounded-md border p-4 text-md my-2",
+        icon &&
+          "grid grid-cols-[min-content_1fr] items-baseline grid-rows-[fit-content_1fr] gap-x-4 gap-y-2",
+        !icon && title && "flex flex-col gap-2",
         "[&_a]:underline [&_a]:decoration-current [&_a]:decoration-from-font [&_a]:underline-offset-4 hover:[&_a]:decoration-1",
-        "[&_code]:!bg-gray-50 [&_code]:dark:!bg-gray-800 [&_code]:!border-none my-2",
-        title && "items-center",
+        "[&_code]:!bg-gray-50 [&_code]:dark:!bg-gray-800 [&_code]:!border-none",
+        icon && title && "items-center",
         border,
         bg,
         className,
       )}
     >
-      <Icon
-        className={cn(!title && "translate-y-px", iconColor)}
-        size={20}
-        aria-hidden="true"
-      />
+      {icon && (
+        <Icon
+          className={cn(!title ? "translate-y-1" : "align-middle", iconColor)}
+          size={20}
+          aria-hidden="true"
+        />
+      )}
       {title && <h3 className={cn("font-medium", titleColor)}>{title}</h3>}
-      <div className={cn("col-start-2", !title && "row-start-1", textColor)}>
+      <div
+        className={cn(
+          icon && "col-start-2",
+          !title && icon && "row-start-1",
+          textColor,
+        )}
+      >
         {children}
       </div>
     </div>