zudoku 0.0.0-fa903e7 → 0.0.0-fb5b775d

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

@@ -1,70 +1,72 @@
-import { matchPath, type RouteObject } from "react-router-dom";
-import { type ZudokuPlugin } from "../../core/plugins.js";
-import { graphql } from "./graphql/index.js";
-
-import { useQuery } from "@tanstack/react-query";
-import { CirclePlayIcon, LogInIcon } from "lucide-react";
-import type { SidebarItem } from "../../../config/validators/SidebarSchema.js";
-import { useAuth } from "../../authentication/hook.js";
-import { ColorMap } from "../../components/navigation/SidebarBadge.js";
+import { CirclePlayIcon } from "lucide-react";
+import type { PropsWithChildren } from "react";
+import { matchPath } from "react-router";
+import type { NavigationItem } from "../../../config/validators/NavigationSchema.js";
+import type { ZudokuPlugin } from "../../core/plugins.js";
 import { Button } from "../../ui/Button.js";
-import { joinPath } from "../../util/joinPath.js";
+import { joinUrl } from "../../util/joinUrl.js";
 import { GraphQLClient } from "./client/GraphQLClient.js";
-import { OasPluginConfig } from "./interfaces.js";
+import { createQuery } from "./client/useCreateQuery.js";
+import type { GetNavigationOperationsQuery as GetNavigationOperationsQueryResult } from "./graphql/graphql.js";
+import { graphql } from "./graphql/index.js";
+import type { OasPluginConfig } from "./interfaces.js";
 import type { PlaygroundContentProps } from "./playground/Playground.js";
 import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
+import { createNavigationCategory } from "./util/createNavigationCategory.js";
+import { getRoutes, getVersionMetadata } from "./util/getRoutes.js";
 
-const GetCategoriesQuery = graphql(`
-  query GetCategories($input: JSON!, $type: SchemaType!) {
+export const GetNavigationOperationsQuery = graphql(`
+  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {
     schema(input: $input, type: $type) {
-      url
+      extensions
       tags {
-        __typename
+        slug
         name
+        extensions
         operations {
-          __typename
+          summary
           slug
-          deprecated
           method
-          summary
           operationId
           path
         }
       }
+      components {
+        schemas {
+          __typename
+        }
+      }
     }
   }
 `);
 
-type InternalOasPluginConfig = { inMemory?: boolean };
+export type OperationResult =
+  GetNavigationOperationsQueryResult["schema"]["tags"][number]["operations"][number];
 
-const MethodColorMap: Record<string, keyof typeof ColorMap> = {
-  get: "green",
-  post: "blue",
-  put: "yellow",
-  delete: "red",
-  patch: "purple",
-  options: "gray",
-  head: "gray",
-};
-
-export type OpenApiPluginOptions = OasPluginConfig & InternalOasPluginConfig;
+export type OpenApiPluginOptions = OasPluginConfig;
 
-export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
-  const basePath = joinPath(config.navigationId ?? "/reference");
+export const UNTAGGED_PATH = "~endpoints";
 
+export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
+  const basePath = joinUrl(config.path);
   const client = new GraphQLClient(config);
 
   return {
     getHead: () => {
       if (config.type === "url" && !config.skipPreload) {
-        return (
+        const urls = Array.isArray(config.input)
+          ? config.input.map((v) => v.input)
+          : [config.input];
+
+        return urls.map((url) => (
           <link
+            key={url}
+            href={url}
             rel="preload"
-            href={config.input}
             as="fetch"
             crossOrigin="anonymous"
           />
-        );
+        ));
       }
 
       if (config.server) {
@@ -73,118 +75,158 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
     },
     getMdxComponents: () => ({
       OpenPlaygroundButton: ({
-        requireAuth,
         server,
-        method,
-        url,
+        method = "get",
+        url = "/",
+        children,
         ...props
-      }: Partial<PlaygroundContentProps> & { requireAuth: boolean }) => {
-        const auth = useAuth();
-        // We don't have the GraphQL context here
-        const serverQuery = useQuery({
-          queryFn: () =>
-            client.fetch(GetCategoriesQuery, {
-              type: config.type,
-              input: config.input,
-            }),
-          enabled: !server,
-          queryKey: ["playground-server"],
-        });
-
-        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>
-          );
+      }: PropsWithChildren<Partial<PlaygroundContentProps>>) => {
+        if (!server) {
+          throw new Error("Server is required");
         }
 
         return (
           <PlaygroundDialog
-            url={url ?? "/"}
-            method={method ?? "get"}
-            server={
-              server ?? serverQuery.data?.schema.url ?? "https://example.com"
-            }
+            url={url}
+            method={method}
+            server={server}
             {...props}
           >
             <Button className="gap-2 items-center" variant="outline">
-              Open in Playground <CirclePlayIcon size={16} />
+              {children ?? (
+                <>
+                  Open in Playground
+                  <CirclePlayIcon size={16} />
+                </>
+              )}
             </Button>
           </PlaygroundDialog>
         );
       },
     }),
-    getSidebar: async (path: string) => {
+    getNavigation: async (path, context) => {
       if (!matchPath({ path: basePath, end: false }, path)) {
         return [];
       }
 
+      const match = matchPath(
+        { path: `${basePath}/:version?/:tag`, end: true },
+        path,
+      );
+
       try {
-        const data = await client.fetch(GetCategoriesQuery, {
-          type: config.type,
-          input: config.input,
+        const versionParam = match?.params.version;
+        const { versions } = getVersionMetadata(config);
+        const version = versionParam ?? versions.at(0);
+        const { type } = config;
+
+        const input = Array.isArray(config.input)
+          ? (config.input.find((v) => v.path === version)?.input ??
+            config.input[0]?.input)
+          : config.input;
+
+        const query = createQuery(client, GetNavigationOperationsQuery, {
+          type,
+          input,
         });
+        const data = await context.queryClient.ensureQueryData(query);
 
-        const categories = data.schema.tags
-          .filter((tag) => tag.operations.length > 0)
-          .map<SidebarItem>((tag) => ({
-            type: "category",
-            label: tag.name || "Other endpoints",
-            collapsible: true,
-            collapsed: false,
-            items: tag.operations.map((operation) => ({
-              type: "link",
-              label: operation.summary ?? operation.path,
-              href: `#${operation.slug}`,
-              badge: {
-                label: operation.method,
-                color: MethodColorMap[operation.method.toLowerCase()]!,
+        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 groupedTags = new Set(
+          tagGroups.flatMap((group) =>
+            group.tags.filter((name) => tagCategories.has(name)),
+          ),
+        );
+
+        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,
               },
-            })),
-          }));
+            ];
+          },
+        );
 
-        categories.unshift({
-          type: "link",
-          label: "Overview",
-          href: "#description",
-        });
+        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 && untaggedOperations.length > 0) {
+          categories.push(
+            createNavigationCategory({
+              label: categories.length === 0 ? "Endpoints" : "Other endpoints",
+              path: joinUrl(basePath, versionParam, UNTAGGED_PATH),
+              operations: untaggedOperations,
+              collapsed: !config.options?.expandAllTags,
+            }),
+          );
+        }
+
+        if (data.schema.components?.schemas?.length) {
+          categories.push({
+            type: "link" as const,
+            label: "Schemas",
+            to: joinUrl(basePath, versionParam, "~schemas"),
+          });
+        }
 
         return categories;
       } catch {
         return [];
       }
     },
-    getRoutes: () =>
-      [
-        {
-          async lazy() {
-            const { OpenApiRoute } = await import("./Route.js");
-            return {
-              element: <OpenApiRoute client={client} config={config} />,
-            };
-          },
-          children: [
-            {
-              path: basePath,
-              children: [
-                {
-                  index: true,
-                  async lazy() {
-                    const { OperationList } = await import(
-                      "./OperationList.js"
-                    );
-                    return { element: <OperationList /> };
-                  },
-                },
-              ],
-            },
-          ],
-        },
-      ] satisfies RouteObject[],
+    getRoutes: () => getRoutes({ basePath, config, client }),
   };
 };

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

@@ -1,10 +1,89 @@
+import type { AuthState } from "../../authentication/state.js";
+import type { ZudokuContext } from "../../core/ZudokuContext.js";
+import type { SchemaImports } from "../../oas/graphql/index.js";
+import type { OperationsFragmentFragment } from "./graphql/graphql.js";
+
+type DynamicInput = () => Promise<unknown>;
+
+export type VersionedInput<T> = Array<{
+  path: string;
+  label?: string;
+  input: T;
+}>;
+
 type OasSource =
-  | { type: "url"; input: string }
-  | { type: "file"; input: () => Promise<unknown> }
+  | { type: "url"; input: string | VersionedInput<string> }
+  | { type: "file"; input: VersionedInput<DynamicInput> }
   | { type: "raw"; input: string };
 
-export type OasPluginConfig = {
+export type ContextOasSource = {
+  type: "url" | "file" | "raw";
+  input: string | DynamicInput;
+};
+
+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;
+  }> | null;
+  examples?: Array<Example> | null;
+};
+
+export type TransformExamplesFn = (options: {
+  content: Content[];
+  context: ZudokuContext;
+  auth: AuthState;
+  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;
-} & OasSource;
+  tagPages?: Array<string>;
+  schemaImports?: SchemaImports;
+  options?: {
+    examplesLanguage?: string;
+    supportedLanguages?: { value: string; label: string }[];
+    disablePlayground?: boolean;
+    disableSidecar?: boolean;
+    showVersionSelect?: "always" | "if-available" | "hide";
+    expandAllTags?: boolean;
+    expandApiInformation?: boolean;
+    schemaDownload?: {
+      enabled: boolean;
+    };
+    transformExamples?: TransformExamplesFn;
+    generateCodeSnippet?: GenerateCodeSnippetFn;
+  };
+};
+
+export type OasPluginConfig = BaseOasConfig & OasSource;
+
+export type OasPluginContext = BaseOasConfig &
+  ContextOasSource & {
+    version?: string;
+    versions: Record<string, { path: string; label: string }>;
+  };