@lukoweb/apitogo 0.1.0

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

@@ -0,0 +1,2 @@
+export * from "./fragment-masking.js";
+export * from "./gql.js";

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

@@ -0,0 +1,218 @@
+import { CirclePlayIcon } from "lucide-react";
+import { type PropsWithChildren, Suspense, lazy } from "react";
+import { matchPath } from "react-router";
+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 { 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 { buildTagCategories } from "./util/buildTagCategories.js";
+import { createNavigationCategory } from "./util/createNavigationCategory.js";
+import { getRoutes, getVersionMetadata } from "./util/getRoutes.js";
+
+const PlaygroundDialog = lazy(() =>
+  import("./playground/PlaygroundDialog.js").then((m) => ({
+    default: m.PlaygroundDialog,
+  })),
+);
+
+export const GetNavigationOperationsQuery = graphql(`
+  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {
+    schema(input: $input, type: $type) {
+      extensions
+      tags {
+        slug
+        name
+        extensions
+        operations {
+          summary
+          slug
+          method
+          operationId
+          path
+        }
+      }
+      components {
+        schemas {
+          __typename
+        }
+      }
+    }
+  }
+`);
+
+export type OperationResult =
+  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.path);
+  const client = new GraphQLClient(config);
+
+  return {
+    getHead: () => {
+      if (config.type === "url" && !config.skipPreload) {
+        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"
+            as="fetch"
+            crossOrigin="anonymous"
+          />
+        ));
+      }
+
+      if (config.server) {
+        return <link rel="preconnect" href={config.server} />;
+      }
+    },
+    getMdxComponents: () => ({
+      OpenPlaygroundButton: ({
+        server,
+        method = "get",
+        url = "/",
+        children,
+        ...props
+      }: PropsWithChildren<Partial<PlaygroundContentProps>>) => {
+        if (!server) {
+          throw new Error("Server is required");
+        }
+
+        return (
+          <Suspense>
+            <PlaygroundDialog
+              url={url}
+              method={method}
+              server={server}
+              {...props}
+            >
+              <Button className="gap-2 items-center" variant="outline">
+                {children ?? (
+                  <>
+                    Open in Playground
+                    <CirclePlayIcon size={16} />
+                  </>
+                )}
+              </Button>
+            </PlaygroundDialog>
+          </Suspense>
+        );
+      },
+    }),
+    getNavigation: async (path, context) => {
+      if (!matchPath({ path: basePath, end: false }, path)) {
+        return [];
+      }
+
+      try {
+        const { versions } = getVersionMetadata(config);
+
+        const versionParam = versions.find((v) =>
+          matchPath({ path: joinUrl(basePath, v), end: false }, path),
+        );
+
+        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 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 categories = buildTagCategories({
+          tagCategories,
+          tagGroups,
+          expandAllTags: config.options?.expandAllTags,
+        });
+
+        if (config.options?.showInfoPage !== false) {
+          categories.unshift({
+            type: "link" as const,
+            to: joinUrl(basePath, versionParam),
+            label: "Information",
+          });
+        }
+
+        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",
+            label: "Schemas",
+            to: joinUrl(basePath, versionParam, "~schemas"),
+          });
+        }
+
+        return categories;
+      } catch {
+        return [];
+      }
+    },
+    getRoutes: () => getRoutes({ basePath, config, client }),
+  };
+};

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

@@ -0,0 +1,100 @@
+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 = string> = {
+  path: string;
+  version?: string;
+  downloadUrl?: string;
+  label?: string;
+  input: T;
+  hasUntaggedOperations?: boolean;
+  tagPages?: string[];
+};
+
+type OasSource =
+  | { type: "url"; input: string | VersionedInput[] }
+  | { type: "file"; input: VersionedInput<DynamicInput>[] }
+  | { type: "raw"; input: string };
+
+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;
+  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;
+    showInfoPage?: boolean;
+    schemaDownload?: {
+      enabled: boolean;
+    };
+    transformExamples?: TransformExamplesFn;
+    generateCodeSnippet?: GenerateCodeSnippetFn;
+  };
+};
+
+export type OasPluginConfig = BaseOasConfig & OasSource;
+
+export type VersionEntry = {
+  path: string;
+  label: string;
+  downloadUrl?: string;
+  tagPages?: string[];
+};
+
+export type OasPluginContext = BaseOasConfig &
+  ContextOasSource & {
+    version?: string;
+    versions: Record<string, VersionEntry>;
+  };

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

@@ -0,0 +1,271 @@
+import {
+  ChevronDownIcon,
+  FileInput,
+  Grid2x2PlusIcon,
+  PaperclipIcon,
+  ScanTextIcon,
+  XIcon,
+} from "lucide-react";
+import { useRef, useState } from "react";
+import { useFormContext } from "react-hook-form";
+import { Button } from "@lukoweb/apitogo/components";
+import { Collapsible, CollapsibleContent } from "@lukoweb/apitogo/ui/Collapsible.js";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@lukoweb/apitogo/ui/DropdownMenu.js";
+import { Textarea } from "@lukoweb/apitogo/ui/Textarea.js";
+import { cn } from "../../../util/cn.js";
+import { humanFileSize } from "../../../util/humanFileSize.js";
+import type { MediaTypeObject } from "../graphql/graphql.js";
+import {
+  CollapsibleHeader,
+  CollapsibleHeaderTrigger,
+} from "./CollapsibleHeader.js";
+import ExamplesDropdown from "./ExamplesDropdown.js";
+import ParamsGrid from "./ParamsGrid.js";
+import type { PlaygroundForm } from "./Playground.js";
+import { MultipartField } from "./request-panel/MultipartField.js";
+import { useKeyValueFieldManager } from "./request-panel/useKeyValueFieldManager.js";
+
+export const BodyPanel = ({ content }: { content?: MediaTypeObject[] }) => {
+  const { register, setValue, watch, control } =
+    useFormContext<PlaygroundForm>();
+  const examples = (content ?? []).flatMap((e) => e.examples);
+  const [headers, file, bodyMode, body, multipartFormFields] = watch([
+    "headers",
+    "file",
+    "bodyMode",
+    "body",
+    "multipartFormFields",
+  ]);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [isDragging, setIsDragging] = useState(false);
+
+  const handleFileSelect = (selectedFile: File | null) => {
+    setValue("file", selectedFile);
+    if (!selectedFile) return;
+    setValue(
+      "headers",
+      headers.filter(
+        (h) => h.name.toLowerCase() !== "content-type" || !h.active,
+      ),
+    );
+  };
+
+  const handleFileInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const selectedFile = e.target.files?.[0] ?? null;
+    handleFileSelect(selectedFile);
+  };
+
+  const handleDragOver = (e: React.DragEvent<HTMLElement>) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setIsDragging(true);
+  };
+
+  const handleDragLeave = (e: React.DragEvent<HTMLElement>) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setIsDragging(false);
+  };
+
+  const handleDrop = (e: React.DragEvent<HTMLElement>) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setIsDragging(false);
+
+    const droppedFile = e.dataTransfer.files?.[0] ?? null;
+    handleFileSelect(droppedFile);
+  };
+
+  const manager = useKeyValueFieldManager<
+    PlaygroundForm,
+    "multipartFormFields"
+  >({
+    control,
+    name: "multipartFormFields",
+    defaultValue: { name: "", value: "", active: false },
+    isEmpty: (item) => {
+      if (item.value instanceof File) return false;
+      return !item.name && !item.value;
+    },
+  });
+
+  return (
+    <Collapsible defaultOpen>
+      <CollapsibleHeaderTrigger className="items-center">
+        <FileInput size={16} />
+        <CollapsibleHeader className="flex items-center justify-between">
+          Body
+          <div className="flex items-center">
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  className="hover:bg-accent hover:brightness-95 gap-2"
+                >
+                  {bodyMode === "text" ? (
+                    <>
+                      <ScanTextIcon size={14} />
+                      Text
+                    </>
+                  ) : bodyMode === "file" ? (
+                    <>
+                      <PaperclipIcon size={14} />
+                      File
+                    </>
+                  ) : (
+                    <>
+                      <Grid2x2PlusIcon size={14} />
+                      Multipart
+                    </>
+                  )}
+                  <ChevronDownIcon size={14} />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent className="min-w-40">
+                <DropdownMenuItem
+                  onSelect={() => setValue("bodyMode", "text")}
+                  className="gap-2"
+                >
+                  <ScanTextIcon size={14} />
+                  <span className="flex-1">Text</span>
+                  <span>
+                    {body.length > 0 && (
+                      <div className="w-1.5 h-1.5 bg-primary rounded-full" />
+                    )}
+                  </span>
+                </DropdownMenuItem>
+                <DropdownMenuItem
+                  onSelect={() => setValue("bodyMode", "file")}
+                  className="gap-2"
+                >
+                  <PaperclipIcon size={14} />
+                  <span className="flex-1">File</span>
+                  <span>
+                    {file && (
+                      <div className="w-1.5 h-1.5 bg-primary rounded-full" />
+                    )}
+                  </span>
+                </DropdownMenuItem>
+                <DropdownMenuItem
+                  onSelect={() => setValue("bodyMode", "multipart")}
+                  className="gap-2"
+                >
+                  <Grid2x2PlusIcon size={14} strokeWidth={1.5} />
+                  <span className="flex-1">Multipart</span>
+                  <span>
+                    {multipartFormFields?.some((field) => field.active) && (
+                      <div className="w-1.5 h-1.5 bg-primary rounded-full" />
+                    )}
+                  </span>
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+            <input
+              ref={fileInputRef}
+              type="file"
+              className="hidden"
+              onChange={handleFileInputChange}
+            />
+            <div className="w-px mx-1 h-5 bg-border" />
+            {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 />
+            )}
+          </div>
+        </CollapsibleHeader>
+      </CollapsibleHeaderTrigger>
+      <CollapsibleContent className="CollapsibleContent flex flex-col gap-2">
+        {bodyMode === "text" && (
+          <Textarea
+            {...register("body")}
+            className={cn(
+              "w-full px-4 py-2.5 h-64 font-mono md:text-xs border-none rounded-none focus-visible:ring-0 transition-colors",
+            )}
+            placeholder="Body content"
+          />
+        )}
+        {bodyMode === "file" && (
+          <div
+            role="region"
+            aria-label="File upload drop zone"
+            className={cn(
+              "flex flex-col items-center justify-center gap-4 min-h-[300px]",
+            )}
+            onDragOver={handleDragOver}
+            onDragLeave={handleDragLeave}
+            onDrop={handleDrop}
+          >
+            <button
+              type="button"
+              onClick={() => fileInputRef.current?.click()}
+              className={cn(
+                "flex items-center justify-center gap-2 rounded-full size-20 p-0 border border-dashed border-muted-foreground/50 hover:bg-accent/75 transition-colors",
+                (file || isDragging) && "border-solid",
+                isDragging && "bg-accent border-primary",
+              )}
+            >
+              <PaperclipIcon
+                className={cn(
+                  "text-muted-foreground",
+                  isDragging && "text-primary",
+                )}
+                size={30}
+              />
+            </button>
+            {file ? (
+              <div className="flex items-center justify-between gap-2 px-2 py-1.5 rounded-md border">
+                <span className="text-sm truncate" title={file.name}>
+                  {file.name}{" "}
+                  <span className="text-muted-foreground">
+                    ({humanFileSize(file.size)})
+                  </span>
+                </span>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon-xs"
+                  onClick={() => handleFileSelect(null)}
+                >
+                  <XIcon size={14} />
+                </Button>
+              </div>
+            ) : (
+              <span className="text-lg font-semibold text-muted-foreground">
+                Select or drop a file
+              </span>
+            )}
+          </div>
+        )}
+        {bodyMode === "multipart" && (
+          <ParamsGrid>
+            {manager.fields.map((field, index) => (
+              <MultipartField key={field.id} index={index} manager={manager} />
+            ))}
+          </ParamsGrid>
+        )}
+      </CollapsibleContent>
+    </Collapsible>
+  );
+};
+
+export default BodyPanel;

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

@@ -0,0 +1,51 @@
+import { ChevronsDownUpIcon, ChevronsUpDownIcon } from "lucide-react";
+import { CollapsibleTrigger } from "@lukoweb/apitogo/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_max-content] items-center gap-2 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 opacity-75 rounded-md",
+          className,
+        )}
+      >
+        <ChevronsDownUpIcon
+          className="group-data-[state=closed]:hidden shrink-0"
+          size={14}
+        />
+        <ChevronsUpDownIcon
+          className="group-data-[state=open]:hidden shrink-0"
+          size={14}
+        />
+      </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,60 @@
+import { PlusCircleIcon } from "lucide-react";
+import { Button } from "@lukoweb/apitogo/ui/Button.js";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@lukoweb/apitogo/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 gap-2"
+        >
+          Use Example
+          <PlusCircleIcon size={14} />
+        </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;