zudoku 0.0.0-f3f6db5 → 0.0.0-f40ea27

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

@@ -1,70 +1,53 @@
-import slugify from "@sindresorhus/slugify";
 import { CirclePlayIcon, LogInIcon } from "lucide-react";
-import { matchPath, redirect, RouteObject } from "react-router";
-import type { SidebarItem } from "../../../config/validators/SidebarSchema.js";
+import { type ReactNode } from "react";
+import { matchPath } from "react-router";
 import { useAuth } from "../../authentication/hook.js";
-import { ColorMap } from "../../components/navigation/SidebarBadge.js";
 import { type ZudokuPlugin } from "../../core/plugins.js";
-import type { SchemaImports } from "../../oas/graphql/index.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 { GetNavigationOperationsQuery as GetNavigationOperationsQueryResult } from "./graphql/graphql.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 { 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) {
-      url
       tags {
+        slug
         name
+        extensions
+        operations {
+          summary
+          slug
+          method
+          operationId
+          path
+        }
       }
-    }
-  }
-`);
-
-const GetOperationsQuery = graphql(`
-  query GetOperations(
-    $input: JSON!
-    $type: SchemaType!
-    $tag: String
-    $untagged: Boolean
-  ) {
-    schema(input: $input, type: $type) {
-      operations(tag: $tag, untagged: $untagged) {
-        slug
-        deprecated
-        method
-        summary
-        operationId
-        path
+      components {
+        schemas {
+          __typename
+        }
       }
     }
   }
 `);
 
-type InternalOasPluginConfig = { schemaImports?: SchemaImports };
-
-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 OperationResult =
+  GetNavigationOperationsQueryResult["schema"]["tags"][number]["operations"][number];
 
-const UNTAGGED_PATH = "~endpoints";
+export type OpenApiPluginOptions = OasPluginConfig;
 
-export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
-  const basePath = joinUrl(config.navigationId ?? "/reference");
-  const versions = config.type === "file" ? Object.keys(config.input) : [];
+export const UNTAGGED_PATH = "~endpoints";
 
+export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
+  const basePath = joinUrl(config.path);
   const client = new GraphQLClient(config);
 
   return {
@@ -90,9 +73,12 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
         server,
         method,
         url,
+        children,
         ...props
-      }: Partial<PlaygroundContentProps> &
-        Pick<PlaygroundContentProps, "server"> & {
+      }: Partial<PlaygroundContentProps> & { children: ReactNode } & Pick<
+          PlaygroundContentProps,
+          "server"
+        > & {
           requireAuth: boolean;
         }) => {
         const auth = useAuth();
@@ -121,133 +107,86 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
             {...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 [];
       }
 
-      try {
-        const urlVersion = versions.find((v) =>
-          path.startsWith(joinUrl(basePath, v)),
-        );
-        const version = urlVersion ?? Object.keys(config.input).at(0);
+      const match = matchPath(
+        { path: `${basePath}/:version?/:tag`, end: true },
+        path,
+      );
 
-        const data = await client.fetch(GetCategoriesQuery, {
-          type: config.type,
-          input: config.type === "file" ? config.input[version!] : config.input,
+      try {
+        const versionParam = match?.params.version;
+        const version = versionParam ?? getVersions(config).at(0);
+        const { type } = config;
+        const input = type === "file" ? config.input[version!] : config.input;
+
+        const query = createQuery(client, GetNavigationOperationsQuery, {
+          type,
+          input,
         });
+        const data = await context.queryClient.ensureQueryData(query);
 
-        const tag = config.tagPages?.find(
-          (tag) => path.split("/").at(-1) === slugify(tag),
-        );
+        const categories = data.schema.tags.flatMap((tag) => {
+          if (!tag.name || tag.operations.length === 0) return [];
+
+          const categoryPath = joinUrl(basePath, versionParam, tag.slug);
 
-        const operationsData = await client.fetch(GetOperationsQuery, {
-          type: config.type,
-          input: config.type === "file" ? config.input[version!] : config.input,
-          tag,
-          untagged: tag === undefined,
+          const isCollapsed =
+            tag.extensions?.["x-zudoku-collapsed"] ??
+            !config.options?.expandAllTags;
+          const isCollapsible =
+            tag.extensions?.["x-zudoku-collapsible"] ?? true;
+
+          return createNavigationCategory({
+            label: tag.name,
+            path: categoryPath,
+            operations: tag.operations,
+            collapsed: isCollapsed,
+            collapsible: isCollapsible,
+          });
         });
 
-        const items = operationsData.schema.operations.map((operation) => ({
-          type: "link" as const,
-          label: operation.summary ?? operation.path,
-          href: `#${operation.slug}`,
-          badge: {
-            label: operation.method,
-            color: MethodColorMap[operation.method.toLowerCase()]!,
-            invert: true,
-          } as const,
-        }));
-
-        const categories = data.schema.tags
-          // .filter((tag) => tag.operations.length > 0)
-          .map<SidebarItem>((tag) => {
-            const categoryLink = joinUrl(
-              basePath,
-              urlVersion,
-              tag.name ? slugify(tag.name) : UNTAGGED_PATH,
-            );
-            return {
-              type: "category",
-              label: tag.name || "Other endpoints",
-              link: {
-                type: "doc" as const,
-                id: categoryLink,
-                label: tag.name!,
-              },
-              collapsible: false,
-              collapsed: true,
-              items: path === categoryLink ? items : [],
-            };
+        const untaggedOperations = data.schema.tags.find(
+          (tag) => !tag.name,
+        )?.operations;
+
+        if (untaggedOperations) {
+          categories.push(
+            createNavigationCategory({
+              label: "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: () => {
-      const versionsInPath = [null, ...versions];
-
-      const tagPages = (config.tagPages ?? []).map((tag) => ({
-        tag,
-        path: slugify(tag),
-      }));
-
-      return versionsInPath.map((version) => {
-        const versionPath = joinUrl(basePath, version ? `/${version}` : "");
-
-        return {
-          path: versionPath,
-          async lazy() {
-            const { OpenApiRoute } = await import("./OpenApiRoute.js");
-            return {
-              element: (
-                <OpenApiRoute
-                  version={version ?? undefined}
-                  basePath={basePath}
-                  versions={versions}
-                  client={client}
-                  config={config}
-                />
-              ),
-            };
-          },
-          children: [
-            {
-              index: true,
-              loader: () =>
-                redirect(
-                  joinUrl(versionPath, tagPages.at(0)?.path ?? UNTAGGED_PATH),
-                ),
-            },
-            {
-              path: joinUrl(versionPath, UNTAGGED_PATH),
-              async lazy() {
-                const { OperationList } = await import("./OperationList.js");
-                return { element: <OperationList untagged={true} /> };
-              },
-            },
-            ...tagPages.map<RouteObject>((tag) => {
-              return {
-                path: joinUrl(versionPath, tag.path),
-                async lazy() {
-                  const { OperationList } = await import("./OperationList.js");
-                  return {
-                    element: <OperationList tag={tag.tag} />,
-                  };
-                },
-              };
-            }),
-          ],
-        };
-      });
-    },
+    getRoutes: () => getRoutes({ basePath, config, client }),
   };
 };

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

@@ -1,40 +1,65 @@
+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";
+
+type DynamicInput = () => Promise<unknown>;
+
 type OasSource =
   | { type: "url"; input: string }
-  | {
-      type: "file";
-      input: {
-        [version: string]: () => Promise<unknown>;
-      };
-    }
+  | { type: "file"; input: { [version: string]: DynamicInput } }
   | { type: "raw"; input: string };
 
 export type ContextOasSource =
   | { type: "url"; input: string }
-  | {
-      type: "file";
-      input: () => Promise<unknown>;
-    }
+  | { type: "file"; input: DynamicInput }
   | { type: "raw"; input: string };
 
-export type OasPluginConfig = {
+type Example = {
+  name: string;
+  description?: string | null;
+  externalValue?: string | null;
+  value?: any | null;
+  summary?: string | null;
+};
+
+type Content = {
+  mediaType: string;
+  schema?: any | null;
+  encoding?: Array<{
+    name: string;
+  }> | null;
+  examples?: Array<Example> | null;
+};
+
+export type TransformExamplesFn = (options: {
+  content: Content[];
+  context: ZudokuContext;
+  auth: AuthState;
+  operation: OperationListItemResult;
+  type: "request" | "response";
+}) => Content[];
+
+type BaseOasConfig = {
   server?: string;
-  navigationId?: string;
+  path?: string;
   skipPreload?: boolean;
   tagPages?: Array<string>;
-} & OasPluginConfigOptions &
-  OasSource;
-
-export type OasPluginConfigOptions = {
+  schemaImports?: SchemaImports;
   options?: {
-    examplesDefaultLanguage?: string;
+    examplesLanguage?: string;
+    disablePlayground?: boolean;
+    disableSidecar?: boolean;
+    showVersionSelect?: "always" | "if-available" | "hide";
+    expandAllTags?: boolean;
+    transformExamples?: TransformExamplesFn;
   };
 };
 
-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/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 Content } from "../SidecarExamples.js";
+import {
+  CollapsibleHeader,
+  CollapsibleHeaderTrigger,
+} from "./CollapsibleHeader.js";
+import ExamplesDropdown from "./ExamplesDropdown.js";
+import { type PlaygroundForm } from "./Playground.js";
+
+export const BodyPanel = ({ content }: { content?: Content }) => {
+  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

@@ -1,3 +1,4 @@
+import { PlusCircleIcon } from "lucide-react";
 import { Button } from "zudoku/ui/Button.js";
 import {
   DropdownMenu,
@@ -8,46 +9,50 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "zudoku/ui/DropdownMenu.js";
-import { Content, Example } from "../SidecarExamples.js";
+import type { Content, Example } from "../SidecarExamples.js";
 
 const ExamplesDropdown = ({
   examples,
   onSelect,
 }: {
   examples: Content;
-  onSelect: (example: Example) => void;
+  onSelect: (example: Example, mediaType: string) => void;
 }) => {
   return (
-    <div className="flex flex-col gap-2 mt-2 items-end">
-      <DropdownMenu>
-        <DropdownMenuTrigger asChild>
-          <Button variant="outline">Use Example</Button>
-        </DropdownMenuTrigger>
-        <DropdownMenuContent className="w-56">
-          {examples.map((example) => {
-            return (
-              <div key={example.mediaType}>
-                <DropdownMenuLabel>{example.mediaType}</DropdownMenuLabel>
-                <DropdownMenuSeparator />
-                <DropdownMenuGroup>
-                  {example.examples?.map((example) => {
-                    return (
-                      <DropdownMenuItem
-                        key={example.name}
-                        onSelect={() => onSelect(example)}
-                        className="line-clamp-1"
-                      >
-                        {example.summary ?? example.name}
-                      </DropdownMenuItem>
-                    );
-                  })}
-                </DropdownMenuGroup>
-              </div>
-            );
-          })}
-        </DropdownMenuContent>
-      </DropdownMenu>
-    </div>
+    <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>
   );
 };