zudoku 0.0.0-feat-bundled-types.9aa135e → 0.0.0-feat-openapi-docs-redesign.dab3fc6a

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

@@ -1,7 +1,7 @@
 /* eslint-disable */
 import type { DocumentTypeDecoration } from "@graphql-typed-document-node/core";
 export type Maybe<T> = T | null;
-export type InputMaybe<T> = Maybe<T>;
+export type InputMaybe<T> = T | null | undefined;
 export type Exact<T extends { [key: string]: unknown }> = {
   [K in keyof T]: T[K];
 };
@@ -79,6 +79,7 @@ export type OperationItem = {
   path: Scalars["String"]["output"];
   requestBody?: Maybe<RequestBodyObject>;
   responses: Array<ResponseItem>;
+  servers: Array<Server>;
   slug: Scalars["String"]["output"];
   summary?: Maybe<Scalars["String"]["output"]>;
   tags?: Maybe<Array<TagItem>>;
@@ -225,6 +226,11 @@ export type OperationsFragmentFragment = {
   path: string;
   deprecated?: boolean | null;
   extensions?: any | null;
+  servers: Array<{
+    __typename?: "Server";
+    url: string;
+    description?: string | null;
+  }>;
   parameters?: Array<{
     __typename?: "ParameterItem";
     name: string;
@@ -315,6 +321,7 @@ export type OperationsForTagQuery = {
       __typename?: "SchemaTag";
       name?: string | null;
       description?: string | null;
+      extensions?: any | null;
       operations: Array<
         { __typename?: "OperationItem"; slug: string } & {
           " $fragmentRefs"?: {
@@ -326,11 +333,13 @@ export type OperationsForTagQuery = {
         __typename?: "SchemaTag";
         name?: string | null;
         slug?: string | null;
+        extensions?: any | null;
       } | null;
       prev?: {
         __typename?: "SchemaTag";
         name?: string | null;
         slug?: string | null;
+        extensions?: any | null;
       } | null;
     } | null;
   };
@@ -374,15 +383,16 @@ export type GetServerQueryQuery = {
   };
 };
 
-export type GetSidebarOperationsQueryVariables = Exact<{
+export type GetNavigationOperationsQueryVariables = Exact<{
   input: Scalars["JSON"]["input"];
   type: SchemaType;
 }>;
 
-export type GetSidebarOperationsQuery = {
+export type GetNavigationOperationsQuery = {
   __typename?: "Query";
   schema: {
     __typename?: "Schema";
+    extensions?: any | null;
     tags: Array<{
       __typename?: "SchemaTag";
       slug?: string | null;
@@ -408,7 +418,9 @@ export class TypedDocumentString<TResult, TVariables>
   extends String
   implements DocumentTypeDecoration<TResult, TVariables>
 {
-  __apiType?: DocumentTypeDecoration<TResult, TVariables>["__apiType"];
+  __apiType?: NonNullable<
+    DocumentTypeDecoration<TResult, TVariables>["__apiType"]
+  >;
   private value: string;
   public __meta__?: Record<string, any> | undefined;
 
@@ -418,7 +430,7 @@ export class TypedDocumentString<TResult, TVariables>
     this.__meta__ = __meta__;
   }
 
-  toString(): string & DocumentTypeDecoration<TResult, TVariables> {
+  override toString(): string & DocumentTypeDecoration<TResult, TVariables> {
     return this.value;
   }
 }
@@ -434,6 +446,10 @@ export const OperationsFragmentFragmentDoc = new TypedDocumentString(
   path
   deprecated
   extensions
+  servers {
+    url
+    description
+  }
   parameters {
     name
     in
@@ -532,13 +548,16 @@ export const OperationsForTagDocument = new TypedDocumentString(`
         slug
         ...OperationsFragment
       }
+      extensions
       next {
         name
         slug
+        extensions
       }
       prev {
         name
         slug
+        extensions
       }
     }
   }
@@ -553,6 +572,10 @@ export const OperationsForTagDocument = new TypedDocumentString(`
   path
   deprecated
   extensions
+  servers {
+    url
+    description
+  }
   parameters {
     name
     in
@@ -642,9 +665,10 @@ export const GetServerQueryDocument = new TypedDocumentString(`
   GetServerQueryQuery,
   GetServerQueryQueryVariables
 >;
-export const GetSidebarOperationsDocument = new TypedDocumentString(`
-    query GetSidebarOperations($input: JSON!, $type: SchemaType!) {
+export const GetNavigationOperationsDocument = new TypedDocumentString(`
+    query GetNavigationOperations($input: JSON!, $type: SchemaType!) {
   schema(input: $input, type: $type) {
+    extensions
     tags {
       slug
       name
@@ -665,6 +689,6 @@ export const GetSidebarOperationsDocument = new TypedDocumentString(`
   }
 }
     `) as unknown as TypedDocumentString<
-  GetSidebarOperationsQuery,
-  GetSidebarOperationsQueryVariables
+  GetNavigationOperationsQuery,
+  GetNavigationOperationsQueryVariables
 >;

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

@@ -1,23 +1,24 @@
-import { CirclePlayIcon, LogInIcon } from "lucide-react";
-import { type ReactNode } from "react";
+import { CirclePlayIcon } from "lucide-react";
+import type { PropsWithChildren } from "react";
 import { matchPath } from "react-router";
-import { useAuth } from "../../authentication/hook.js";
-import { type ZudokuPlugin } from "../../core/plugins.js";
+import type { NavigationItem } from "../../../config/validators/NavigationSchema.js";
+import type { ZudokuPlugin } from "../../core/plugins.js";
 import { Button } from "../../ui/Button.js";
 import { joinUrl } from "../../util/joinUrl.js";
 import { GraphQLClient } from "./client/GraphQLClient.js";
 import { createQuery } from "./client/useCreateQuery.js";
-import type { GetSidebarOperationsQuery as GetSidebarOperationsQueryResult } from "./graphql/graphql.js";
+import type { GetNavigationOperationsQuery as GetNavigationOperationsQueryResult } from "./graphql/graphql.js";
 import { graphql } from "./graphql/index.js";
-import { type 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";
+import { createNavigationCategory } from "./util/createNavigationCategory.js";
 import { getRoutes, getVersions } from "./util/getRoutes.js";
 
-export const GetSidebarOperationsQuery = graphql(`
-  query GetSidebarOperations($input: JSON!, $type: SchemaType!) {
+export const GetNavigationOperationsQuery = graphql(`
+  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {
     schema(input: $input, type: $type) {
+      extensions
       tags {
         slug
         name
@@ -40,14 +41,14 @@ export const GetSidebarOperationsQuery = graphql(`
 `);
 
 export type OperationResult =
-  GetSidebarOperationsQueryResult["schema"]["tags"][number]["operations"][number];
+  GetNavigationOperationsQueryResult["schema"]["tags"][number]["operations"][number];
 
 export type OpenApiPluginOptions = OasPluginConfig;
 
 export const UNTAGGED_PATH = "~endpoints";
 
 export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
-  const basePath = joinUrl(config.navigationId ?? "/reference");
+  const basePath = joinUrl(config.path);
   const client = new GraphQLClient(config);
 
   return {
@@ -69,47 +70,28 @@ export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
     },
     getMdxComponents: () => ({
       OpenPlaygroundButton: ({
-        requireAuth,
         server,
-        method,
-        url,
+        method = "get",
+        url = "/",
         children,
         ...props
-      }: Partial<PlaygroundContentProps> & { children: ReactNode } & Pick<
-          PlaygroundContentProps,
-          "server"
-        > & {
-          requireAuth: boolean;
-        }) => {
-        const auth = useAuth();
-
+      }: PropsWithChildren<Partial<PlaygroundContentProps>>) => {
         if (!server) {
           throw new Error("Server is required");
         }
 
-        if (requireAuth && !auth.isAuthenticated) {
-          return (
-            <Button
-              className="gap-2 items-center"
-              variant="outline"
-              onClick={auth.login}
-            >
-              Login to open in Playground <LogInIcon size={16} />
-            </Button>
-          );
-        }
-
         return (
           <PlaygroundDialog
-            url={url ?? "/"}
-            method={method ?? "get"}
+            url={url}
+            method={method}
             server={server}
             {...props}
           >
             <Button className="gap-2 items-center" variant="outline">
               {children ?? (
                 <>
-                  Open in Playground <CirclePlayIcon size={16} />
+                  Open in Playground
+                  <CirclePlayIcon size={16} />
                 </>
               )}
             </Button>
@@ -117,7 +99,7 @@ export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
         );
       },
     }),
-    getSidebar: async (path, context) => {
+    getNavigation: async (path, context) => {
       if (!matchPath({ path: basePath, end: false }, path)) {
         return [];
       }
@@ -131,42 +113,91 @@ export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
         const versionParam = match?.params.version;
         const version = versionParam ?? getVersions(config).at(0);
         const { type } = config;
+        // biome-ignore lint/style/noNonNullAssertion: version is guaranteed to be defined
         const input = type === "file" ? config.input[version!] : config.input;
 
-        const query = createQuery(client, GetSidebarOperationsQuery, {
+        const query = createQuery(client, GetNavigationOperationsQuery, {
           type,
           input,
         });
         const data = await context.queryClient.ensureQueryData(query);
 
-        const categories = data.schema.tags.flatMap((tag) => {
-          if (!tag.name || tag.operations.length === 0) return [];
+        const tagCategories = new Map(
+          data.schema.tags
+            .filter((tag) => tag.name && tag.operations.length > 0)
+            .map((tag) => {
+              if (!tag.name) {
+                throw new Error(`Tag ${tag.slug} has no name`);
+              }
+
+              const categoryPath = joinUrl(basePath, versionParam, tag.slug);
+
+              const isCollapsed =
+                tag.extensions?.["x-zudoku-collapsed"] ??
+                !config.options?.expandAllTags;
+              const isCollapsible =
+                tag.extensions?.["x-zudoku-collapsible"] ?? true;
+
+              return [
+                tag.name,
+                createNavigationCategory({
+                  label: tag.extensions?.["x-displayName"] ?? tag.name,
+                  path: categoryPath,
+                  operations: tag.operations,
+                  collapsed: isCollapsed,
+                  collapsible: isCollapsible,
+                }),
+              ];
+            }),
+        );
+
+        const tagGroups =
+          (data.schema.extensions?.["x-tagGroups"] as
+            | { name: string; tags: string[] }[]
+            | undefined) ?? [];
 
-          const categoryPath = joinUrl(basePath, versionParam, tag.slug);
+        const groupedTags = new Set(
+          tagGroups.flatMap((group) =>
+            group.tags.filter((name) => tagCategories.has(name)),
+          ),
+        );
 
-          const isCollapsed =
-            tag.extensions?.["x-zudoku-collapsed"] ??
-            !config.options?.expandAllTags;
-          const isCollapsible =
-            tag.extensions?.["x-zudoku-collapsible"] ?? true;
+        const groupedCategories: NavigationItem[] = tagGroups.flatMap(
+          (group) => {
+            const items = group.tags
+              .map((name) => tagCategories.get(name))
+              .filter(Boolean) as NavigationItem[];
+
+            if (items.length === 0) {
+              return [];
+            }
+            return [
+              {
+                type: "category",
+                label: group.name,
+                items,
+                collapsible: true,
+                collapsed: !config.options?.expandAllTags,
+              },
+            ];
+          },
+        );
 
-          return createSidebarCategory({
-            label: tag.name,
-            path: categoryPath,
-            operations: tag.operations,
-            collapsed: isCollapsed,
-            collapsible: isCollapsible,
-          });
-        });
+        const categories: NavigationItem[] = [
+          ...groupedCategories,
+          ...Array.from(tagCategories.entries())
+            .filter(([name]) => !groupedTags.has(name))
+            .map(([, cat]) => cat),
+        ];
 
         const untaggedOperations = data.schema.tags.find(
           (tag) => !tag.name,
         )?.operations;
 
-        if (untaggedOperations) {
+        if (untaggedOperations && untaggedOperations.length > 0) {
           categories.push(
-            createSidebarCategory({
-              label: "Other endpoints",
+            createNavigationCategory({
+              label: categories.length === 0 ? "Endpoints" : "Other endpoints",
               path: joinUrl(basePath, versionParam, UNTAGGED_PATH),
               operations: untaggedOperations,
               collapsed: !config.options?.expandAllTags,
@@ -178,7 +209,7 @@ export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
           categories.push({
             type: "link" as const,
             label: "Schemas",
-            href: joinUrl(basePath, versionParam, "~schemas"),
+            to: joinUrl(basePath, versionParam, "~schemas"),
           });
         }
 

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

@@ -1,7 +1,7 @@
-import { type AuthState } from "../../authentication/state.js";
-import { type ZudokuContext } from "../../core/ZudokuContext.js";
+import type { AuthState } from "../../authentication/state.js";
+import type { ZudokuContext } from "../../core/ZudokuContext.js";
 import type { SchemaImports } from "../../oas/graphql/index.js";
-import { type OperationListItemResult } from "./OperationList.js";
+import type { OperationsFragmentFragment } from "./graphql/graphql.js";
 
 type DynamicInput = () => Promise<unknown>;
 
@@ -19,12 +19,14 @@ type Example = {
   name: string;
   description?: string | null;
   externalValue?: string | null;
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
   value?: any | null;
   summary?: string | null;
 };
 
 type Content = {
   mediaType: string;
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
   schema?: any | null;
   encoding?: Array<{
     name: string;
@@ -32,27 +34,40 @@ type Content = {
   examples?: Array<Example> | null;
 };
 
-export type transformExamples = (options: {
+export type TransformExamplesFn = (options: {
   content: Content[];
   context: ZudokuContext;
   auth: AuthState;
-  operation: OperationListItemResult;
+  operation: OperationsFragmentFragment;
   type: "request" | "response";
 }) => Content[];
 
+export type GenerateCodeSnippetFn = (options: {
+  selectedLang: string;
+  selectedServer: string;
+  context: ZudokuContext;
+  auth: AuthState;
+  operation: OperationsFragmentFragment;
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+  example?: any | null;
+}) => string | false;
+
 type BaseOasConfig = {
   server?: string;
-  navigationId?: string;
+  path?: string;
   skipPreload?: boolean;
   tagPages?: Array<string>;
   schemaImports?: SchemaImports;
   options?: {
     examplesLanguage?: string;
+    supportedLanguages?: { value: string; label: string }[];
     disablePlayground?: boolean;
     disableSidecar?: boolean;
     showVersionSelect?: "always" | "if-available" | "hide";
     expandAllTags?: boolean;
-    transformExamples?: transformExamples;
+    expandApiInformation?: boolean;
+    transformExamples?: TransformExamplesFn;
+    generateCodeSnippet?: GenerateCodeSnippetFn;
   };
 };