zudoku 0.0.0-f417aae → 0.0.0-f46233e4

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

@@ -1,82 +1,56 @@
-import { matchPath, useRouteError, type RouteObject } from "react-router-dom";
-import { Client as UrqlClient, cacheExchange, fetchExchange } from "urql";
-import { type DevPortalPlugin } from "../../core/plugins.js";
-import { graphql } from "./graphql/index.js";
-
-import { useQuery } from "@tanstack/react-query";
 import { CirclePlayIcon, LogInIcon } from "lucide-react";
-import { createClient } from "zudoku/openapi-worker";
-import type { SidebarItem } from "../../../config/validators/SidebarSchema.js";
+import type { ReactNode } from "react";
+import { matchPath } from "react-router";
+import type { NavigationItem } from "../../../config/validators/NavigationSchema.js";
 import { useAuth } from "../../authentication/hook.js";
-import { ErrorPage } from "../../components/ErrorPage.js";
-import { ColorMap } from "../../components/navigation/SidebarBadge.js";
-import { SyntaxHighlight } from "../../components/SyntaxHighlight.js";
+import type { ZudokuPlugin } from "../../core/plugins.js";
 import { Button } from "../../ui/Button.js";
-import { joinPath } from "../../util/joinPath.js";
-import { OasPluginConfig } from "./interfaces.js";
+import { joinUrl } from "../../util/joinUrl.js";
+import { GraphQLClient } from "./client/GraphQLClient.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 { GetServerQuery } from "./Sidecar.js";
+import { createNavigationCategory } from "./util/createNavigationCategory.js";
+import { getRoutes, getVersions } 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) {
+      extensions
       tags {
-        __typename
+        slug
         name
+        extensions
         operations {
-          __typename
+          summary
           slug
-          deprecated
           method
-          summary
           operationId
           path
         }
       }
+      components {
+        schemas {
+          __typename
+        }
+      }
     }
   }
 `);
 
-const OpenApiErrorPage = () => {
-  const error = useRouteError();
-  const message =
-    error instanceof Error ? (
-      <SyntaxHighlight code={error.message} />
-    ) : (
-      "An unknown error occurred"
-    );
-
-  return (
-    <ErrorPage category="Error" title="An error occurred" message={message} />
-  );
-};
+export type OperationResult =
+  GetNavigationOperationsQueryResult["schema"]["tags"][number]["operations"][number];
 
-type InternalOasPluginConfig = { inMemory?: boolean };
+export type OpenApiPluginOptions = OasPluginConfig;
 
-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 const openApiPlugin = (
-  config: OpenApiPluginOptions,
-): DevPortalPlugin => {
-  const basePath = joinPath(config.navigationId ?? "/reference");
+export const UNTAGGED_PATH = "~endpoints";
 
-  const client = config.server
-    ? new UrqlClient({
-        url: config.server,
-        exchanges: [cacheExchange, fetchExchange],
-      })
-    : createClient({ useMemoryClient: config.inMemory ?? false });
+export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
+  const basePath = joinUrl(config.path);
+  const client = new GraphQLClient(config);
 
   return {
     getHead: () => {
@@ -101,21 +75,19 @@ export const openApiPlugin = (
         server,
         method,
         url,
+        children,
         ...props
-      }: Partial<PlaygroundContentProps> & { requireAuth: boolean }) => {
+      }: Partial<PlaygroundContentProps> & { children: ReactNode } & Pick<
+          PlaygroundContentProps,
+          "server"
+        > & {
+          requireAuth: boolean;
+        }) => {
         const auth = useAuth();
-        const serverQuery = useQuery({
-          queryFn: async () => {
-            const result = await client.query(GetServerQuery, {
-              type: config.type,
-              input: config.input,
-            });
-
-            return result.data;
-          },
-          enabled: !server,
-          queryKey: ["playground-server"],
-        });
+
+        if (!server) {
+          throw new Error("Server is required");
+        }
 
         if (requireAuth && !auth.isAuthenticated) {
           return (
@@ -133,83 +105,139 @@ export const openApiPlugin = (
           <PlaygroundDialog
             url={url ?? "/"}
             method={method ?? "get"}
-            server={
-              server ?? serverQuery.data?.schema.url ?? "https://example.com"
-            }
+            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 { data } = await client.query(GetCategoriesQuery, {
-        input: config.input,
-        type: config.type,
-      });
-
-      if (!data) return [];
-
-      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()],
-            },
-          })),
-        }));
-
-      categories.unshift({
-        type: "link",
-        label: "Overview",
-        href: "#description",
-      });
-
-      return categories;
-    },
-    getRoutes: () =>
-      [
-        {
-          async lazy() {
-            const { OpenApiRoute } = await import("./Route.js");
-            return {
-              element: <OpenApiRoute client={client} config={config} />,
-            };
+      const match = matchPath(
+        { path: `${basePath}/:version?/:tag`, end: true },
+        path,
+      );
+
+      try {
+        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, GetNavigationOperationsQuery, {
+          type,
+          input,
+        });
+        const data = await context.queryClient.ensureQueryData(query);
+
+        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,
+              },
+            ];
           },
-          errorElement: <OpenApiErrorPage />,
-          children: [
-            {
-              path: basePath,
-              children: [
-                {
-                  index: true,
-                  async lazy() {
-                    const { OperationList } = await import(
-                      "./OperationList.js"
-                    );
-                    return { element: <OperationList /> };
-                  },
-                },
-              ],
-            },
-          ],
-        },
-      ] satisfies RouteObject[],
+        );
+
+        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) {
+          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: () => getRoutes({ basePath, config, client }),
   };
 };

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

@@ -1,10 +1,68 @@
+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>;
+
 type OasSource =
   | { type: "url"; input: string }
-  | { type: "file"; input: any }
+  | { type: "file"; input: { [version: string]: DynamicInput } }
+  | { type: "raw"; input: string };
+
+export type ContextOasSource =
+  | { type: "url"; input: string }
+  | { type: "file"; input: DynamicInput }
   | { type: "raw"; input: string };
 
-export type OasPluginConfig = {
+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[];
+
+type BaseOasConfig = {
   server?: string;
-  navigationId?: string;
+  path?: string;
   skipPreload?: boolean;
-} & OasSource;
+  tagPages?: Array<string>;
+  schemaImports?: SchemaImports;
+  options?: {
+    examplesLanguage?: string;
+    disablePlayground?: boolean;
+    disableSidecar?: boolean;
+    showVersionSelect?: "always" | "if-available" | "hide";
+    expandAllTags?: boolean;
+    expandApiInformation?: boolean;
+    transformExamples?: TransformExamplesFn;
+  };
+};
+
+export type OasPluginConfig = BaseOasConfig & OasSource;
+
+export type OasPluginContext = BaseOasConfig &
+  ContextOasSource & {
+    version?: string;
+    versions: Record<string, string>;
+  };

package/src/lib/plugins/openapi/playground/BodyPanel.tsx

@@ -0,0 +1,55 @@
+import { FileInput } from "lucide-react";
+import { useFormContext } from "react-hook-form";
+import { Collapsible, CollapsibleContent } from "zudoku/ui/Collapsible.js";
+import { Textarea } from "zudoku/ui/Textarea.js";
+import { cn } from "../../../util/cn.js";
+import type { MediaTypeObject } from "../graphql/graphql.js";
+import {
+  CollapsibleHeader,
+  CollapsibleHeaderTrigger,
+} from "./CollapsibleHeader.js";
+import ExamplesDropdown from "./ExamplesDropdown.js";
+import type { PlaygroundForm } from "./Playground.js";
+
+export const BodyPanel = ({ content }: { content?: MediaTypeObject[] }) => {
+  const { register, setValue, watch } = useFormContext<PlaygroundForm>();
+  const examples = (content ?? []).flatMap((e) => e.examples);
+  const headers = watch("headers");
+  return (
+    <Collapsible defaultOpen>
+      <CollapsibleHeaderTrigger>
+        <FileInput size={16} />
+        <CollapsibleHeader>Body</CollapsibleHeader>
+        {content && examples.length > 0 ? (
+          <ExamplesDropdown
+            examples={content}
+            onSelect={(example, mediaType) => {
+              setValue("body", JSON.stringify(example.value, null, 2));
+              setValue("headers", [
+                ...headers.filter((h) => h.name !== "Content-Type"),
+                {
+                  name: "Content-Type",
+                  value: mediaType,
+                  active: true,
+                },
+              ]);
+            }}
+          />
+        ) : (
+          <div />
+        )}
+      </CollapsibleHeaderTrigger>
+      <CollapsibleContent className="flex flex-col gap-2 ">
+        <Textarea
+          {...register("body")}
+          className={cn(
+            "w-full p-2 h-64 font-mono md:text-xs border-none rounded-none focus-visible:ring-0",
+          )}
+          placeholder="Your body here..."
+        />
+      </CollapsibleContent>
+    </Collapsible>
+  );
+};
+
+export default BodyPanel;

package/src/lib/plugins/openapi/playground/CollapsibleHeader.tsx

@@ -0,0 +1,47 @@
+import { ChevronUpIcon } from "lucide-react";
+import { CollapsibleTrigger } from "zudoku/ui/Collapsible.js";
+import { cn } from "../../../util/cn.js";
+
+export const CollapsibleHeaderTrigger = ({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) => {
+  return (
+    <div
+      className={cn(
+        "grid grid-cols-[max-content_1fr_min-content_max-content] items-center gap-4 group bg-muted w-full h-10 ps-4 pe-2 border-b",
+        className,
+      )}
+    >
+      {children}
+      <CollapsibleTrigger
+        className={cn(
+          "flex items-center gap-4 group bg-muted w-full p-2 hover:bg-accent hover:brightness-95 rounded-md",
+          className,
+        )}
+      >
+        <ChevronUpIcon
+          className="group-data-[state=open]:rotate-180 transition-transform flex-shrink-0"
+          size={16}
+        />
+      </CollapsibleTrigger>
+    </div>
+  );
+};
+
+export const CollapsibleHeader = ({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) => {
+  return (
+    <span className={cn("font-semibold w-full text-start", className)}>
+      {children}
+    </span>
+  );
+};

package/src/lib/plugins/openapi/playground/ExamplesDropdown.tsx

@@ -0,0 +1,59 @@
+import { PlusCircleIcon } from "lucide-react";
+import { Button } from "zudoku/ui/Button.js";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "zudoku/ui/DropdownMenu.js";
+import type { ExampleItem, MediaTypeObject } from "../graphql/graphql.js";
+
+const ExamplesDropdown = ({
+  examples,
+  onSelect,
+}: {
+  examples: MediaTypeObject[];
+  onSelect: (example: ExampleItem, mediaType: string) => void;
+}) => {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button
+          variant="ghost"
+          size="sm"
+          className="hover:bg-accent hover:brightness-95"
+        >
+          Use Example <PlusCircleIcon size={16} className="ml-2" />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent className="max-w-72">
+        {examples.map((mediaTypeObject) => (
+          <div key={mediaTypeObject.mediaType}>
+            <DropdownMenuLabel>{mediaTypeObject.mediaType}</DropdownMenuLabel>
+            <DropdownMenuSeparator />
+            <DropdownMenuGroup>
+              {mediaTypeObject.examples?.map((example) => (
+                <DropdownMenuItem
+                  key={example.name}
+                  onSelect={() => onSelect(example, mediaTypeObject.mediaType)}
+                >
+                  <span
+                    className="line-clamp-1"
+                    title={example.summary ?? example.name}
+                  >
+                    {example.summary ?? example.name}
+                  </span>
+                </DropdownMenuItem>
+              ))}
+            </DropdownMenuGroup>
+          </div>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+};
+
+export default ExamplesDropdown;