zudoku 0.0.0-f3f6db5 → 0.0.0-f40ea27

package/src/lib/plugins/openapi/schema/utils.ts

@@ -1,11 +1,25 @@
 import { CIRCULAR_REF } from "../../../oas/graphql/circular.js";
 import type { SchemaObject } from "../../../oas/parser/index.js";
 
-export const isComplexType = (value: SchemaObject) =>
-  value.type === "object" ||
-  (value.type === "array" &&
-    typeof value.items === "object" &&
-    (!value.items.type || value.items.type === "object"));
+export const isBasicType = (
+  type: unknown,
+): type is "string" | "number" | "boolean" | "integer" | "null" =>
+  (typeof type === "string" &&
+    ["string", "number", "boolean", "integer", "null"].includes(type)) ||
+  (Array.isArray(type) && type.every(isBasicType));
+
+export const isArrayType = (value: SchemaObject) =>
+  value.type === "array" ||
+  // schema.type might be an array of types, so we need to check if "array" is one of them
+  (Array.isArray(value.type) && value.type.includes("array"));
+
+export const isComplexType = (value?: SchemaObject) =>
+  value &&
+  ((value.type === "object" &&
+    Object.keys(value.properties ?? {}).length > 0) ||
+    (value.type === "array" &&
+      typeof value.items === "object" &&
+      (!value.items.type || value.items.type === "object")));
 
 export const hasLogicalGroupings = (value: SchemaObject) =>
   Boolean(value.oneOf ?? value.allOf ?? value.anyOf);
@@ -19,4 +33,14 @@ export const LogicalSchemaTypeMap = {
 export type LogicalGroupType = "AND" | "OR" | "ONE";
 
 export const isCircularRef = (schema: unknown): schema is string =>
-  schema === CIRCULAR_REF;
+  typeof schema === "string" && schema.startsWith(CIRCULAR_REF);
+
+export const isArrayCircularRef = (
+  schema: SchemaObject,
+): schema is SchemaObject & { items: SchemaObject } =>
+  isArrayType(schema) && "items" in schema && isCircularRef(schema.items);
+
+export const extractCircularRefInfo = (
+  ref?: string | SchemaObject,
+): string | undefined =>
+  typeof ref === "string" ? ref.split(":")[1] : undefined;

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

@@ -0,0 +1,36 @@
+import { useMemo } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+
+interface SelectedServerState {
+  selectedServer?: string;
+  setSelectedServer: (newServer: string) => void;
+}
+
+export const useSelectedServerStore = create<SelectedServerState>()(
+  persist(
+    (set) => ({
+      selectedServer: undefined,
+      setSelectedServer: (newServer: string) =>
+        set({ selectedServer: newServer }),
+    }),
+    { name: "zudoku-selected-server" },
+  ),
+);
+
+/**
+ * Simple wrapper for `useSelectedServerStore` to fall back to first of the provided servers
+ */
+export const useSelectedServer = (servers: Array<{ url: string }>) => {
+  const { selectedServer, setSelectedServer } = useSelectedServerStore();
+
+  const finalSelectedServer = useMemo(
+    () =>
+      selectedServer && servers.some((s) => s.url === selectedServer)
+        ? selectedServer
+        : (servers.at(0)?.url ?? ""),
+    [selectedServer, servers],
+  );
+
+  return { selectedServer: finalSelectedServer, setSelectedServer };
+};

package/src/lib/plugins/openapi/util/createHttpSnippet.ts

@@ -0,0 +1,107 @@
+import { HTTPSnippet } from "@zudoku/httpsnippet";
+import type { OperationsFragmentFragment } from "../graphql/graphql.js";
+
+export const createHttpSnippet = ({
+  operation,
+  selectedServer,
+  exampleBody,
+}: {
+  operation: OperationsFragmentFragment;
+  selectedServer: string;
+  exampleBody: {
+    mimeType: string;
+    text?: string;
+  };
+}) => {
+  return new HTTPSnippet({
+    method: operation.method.toUpperCase(),
+    url:
+      selectedServer + operation.path.replaceAll("{", ":").replaceAll("}", ""),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    postData: exampleBody,
+    headers: [
+      ...(exampleBody.text
+        ? [{ name: "Content-Type", value: exampleBody.mimeType }]
+        : []),
+      ...(operation.parameters
+        ?.filter((p) => p.in === "header" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? []),
+    ],
+    queryString:
+      operation.parameters
+        ?.filter((p) => p.in === "query" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? [],
+    httpVersion: "",
+    cookies: [],
+    headersSize: 0,
+    bodySize: 0,
+  });
+};
+
+export const getConverted = (snippet: HTTPSnippet, option: string) => {
+  let converted;
+  switch (option) {
+    case "shell":
+      converted = snippet.convert("shell", "curl");
+      break;
+    case "js":
+      converted = snippet.convert("javascript", "fetch");
+      break;
+    case "python":
+      converted = snippet.convert("python", "requests");
+      break;
+    case "java":
+      converted = snippet.convert("java", "okhttp");
+      break;
+    case "go":
+      converted = snippet.convert("go", "native");
+      break;
+    case "csharp":
+      converted = snippet.convert("csharp", "httpclient");
+      break;
+    case "kotlin":
+      converted = snippet.convert("kotlin", "okhttp");
+      break;
+    case "objc":
+      converted = snippet.convert("objc", "nsurlsession");
+      break;
+    case "php":
+      converted = snippet.convert("php", "http2");
+      break;
+    case "ruby":
+      converted = snippet.convert("ruby");
+      break;
+    case "swift":
+      converted = snippet.convert("swift");
+      break;
+    default:
+      converted = snippet.convert("shell");
+      break;
+  }
+
+  return converted ? converted[0] : "";
+};

package/src/lib/plugins/openapi/util/createNavigationCategory.tsx

@@ -0,0 +1,38 @@
+import type { NavigationItem } from "../../../../config/validators/NavigationSchema.js";
+import type { OperationResult } from "../index.js";
+import { MethodColorMap } from "./methodColorMap.js";
+
+export const createNavigationCategory = ({
+  label,
+  path,
+  operations,
+  collapsible,
+  collapsed,
+}: {
+  label: string;
+  path: string;
+  operations: OperationResult[];
+  collapsible?: boolean;
+  collapsed?: boolean;
+}): NavigationItem => ({
+  type: "category",
+  label,
+  link: {
+    type: "doc" as const,
+    path,
+    file: path,
+    label,
+  },
+  collapsible,
+  collapsed,
+  items: operations.map((operation) => ({
+    type: "link" as const,
+    label: operation.summary ?? operation.path,
+    to: `${path}#${operation.slug}`,
+    badge: {
+      label: operation.method,
+      color: MethodColorMap[operation.method.toLowerCase()]!,
+      invert: true,
+    },
+  })),
+});

package/src/lib/plugins/openapi/util/generateSchemaExample.ts

@@ -1,10 +1,15 @@
 import { type SchemaObject } from "../../../oas/graphql/index.js";
+import { isCircularRef } from "../schema/utils.js";
 
 export const generateSchemaExample = (
-  schema: SchemaObject,
+  schema?: SchemaObject,
   name?: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ): any => {
+  if (!schema || isCircularRef(schema)) {
+    return null;
+  }
+
   // Check for schema-level example first
   if (schema.example !== undefined) {
     return schema.example;
@@ -24,6 +29,11 @@ export const generateSchemaExample = (
     }
   }
 
+  // No example needed for const values
+  if (schema.const !== undefined) {
+    return schema.const;
+  }
+
   // For object schemas with properties
   if (schema.type === "object" && schema.properties) {
     const example: Record<string, any> = {};
@@ -50,10 +60,50 @@ export const generateSchemaExample = (
     return [];
   }
 
+  if (schema.format !== undefined) {
+    // Partial implementation of JSON Schema format examples
+    // https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7.3
+    switch (schema.format) {
+      case "date-time":
+        return "2024-08-25T15:00:00Z";
+      case "date":
+        return "2024-08-25";
+      case "time":
+        return "15:00:00";
+      case "email":
+        return "test@example.com";
+      case "uri":
+        return "https://www.example.com/path/to/resource";
+      case "uri-reference":
+        return "/path/to/resource";
+      case "uuid":
+        return "00000000-0000-0000-0000-000000000000";
+    }
+  }
+
   if (schema.enum) {
     return schema.enum[0];
   }
 
+  if (schema.oneOf) {
+    const randomIndex = Math.floor(Math.random() * schema.oneOf.length);
+    return generateSchemaExample(schema.oneOf[randomIndex] as SchemaObject);
+  }
+
+  if (schema.anyOf) {
+    // Should likely be expanded to return a partial set of values, but it would require
+    // detection if being used within an array or a string type.
+    const randomIndex = Math.floor(Math.random() * schema.anyOf.length);
+    return generateSchemaExample(schema.anyOf[randomIndex] as SchemaObject);
+  }
+
+  if (schema.allOf) {
+    // https://swagger.io/docs/specification/v3_0/data-models/oneof-anyof-allof-not/#allof
+    return schema.allOf.reduce((acc, allOfSchema) => {
+      return { ...acc, ...generateSchemaExample(allOfSchema as SchemaObject) };
+    }, {});
+  }
+
   switch (schema.type) {
     case "string":
       return name || "string";

package/src/lib/plugins/openapi/util/getRoutes.tsx

@@ -0,0 +1,198 @@
+import { useSuspenseQuery } from "@tanstack/react-query";
+import {
+  generatePath,
+  Navigate,
+  redirect,
+  type RouteObject,
+  useLocation,
+  useParams,
+} from "react-router";
+import { joinUrl } from "../../../util/joinUrl.js";
+import type { GraphQLClient } from "../client/GraphQLClient.js";
+import { useCreateQuery } from "../client/useCreateQuery.js";
+import { useOasConfig } from "../context.js";
+import {
+  GetNavigationOperationsQuery,
+  type OpenApiPluginOptions,
+  UNTAGGED_PATH,
+} from "../index.js";
+import type { OasPluginConfig } from "../interfaces.js";
+
+// Creates the main provider route that wraps operation routes.
+const createOasProvider = (opts: {
+  routePath: string;
+  basePath: string;
+  version?: string;
+  routes: RouteObject[];
+  client: GraphQLClient;
+  config: OpenApiPluginOptions;
+}): RouteObject => ({
+  path: opts.routePath,
+  async lazy() {
+    const { OasProvider } = await import("../OasProvider.js");
+    return {
+      element: (
+        <OasProvider
+          basePath={opts.basePath}
+          version={opts.version}
+          client={opts.client}
+          config={opts.config}
+        />
+      ),
+    };
+  },
+  children: opts.routes,
+});
+
+// Creates a route for displaying the operation list used for both tagged and untagged operations.
+const createRoute = ({
+  path,
+  tag,
+  untagged,
+}: {
+  path: string;
+  tag?: string;
+  untagged?: boolean;
+}): RouteObject => ({
+  path,
+  async lazy() {
+    const { OperationList } = await import("../OperationList.js");
+    return { element: <OperationList tag={tag} untagged={untagged} /> };
+  },
+});
+
+const NonTagPagesOperationList = ({
+  render,
+  path,
+}: {
+  render: (tag: string) => React.ReactNode;
+  path: string;
+}) => {
+  const { type, input } = useOasConfig();
+  const { tag: currentTag } = useParams();
+  const location = useLocation();
+  const query = useCreateQuery(GetNavigationOperationsQuery, { type, input });
+  const {
+    data: { schema },
+  } = useSuspenseQuery(query);
+
+  const firstTag = schema.tags.at(0);
+
+  if (!currentTag && firstTag?.slug) {
+    return (
+      <Navigate
+        to={{
+          pathname: generatePath(path, { tag: firstTag.slug }),
+          search: location.search,
+        }}
+      />
+    );
+  }
+
+  if (currentTag && schema.tags.some((t) => t.slug === currentTag)) {
+    return render(currentTag);
+  }
+
+  return null;
+};
+
+const createNonTagPagesRoute = ({ path }: { path: string }): RouteObject => ({
+  path,
+  async lazy() {
+    const { OperationList } = await import("../OperationList.js");
+    return {
+      element: (
+        <NonTagPagesOperationList
+          path={path}
+          render={(tag) => <OperationList tag={tag} />}
+        />
+      ),
+    };
+  },
+});
+
+const createAdditionalRoutes = (basePath: string) => [
+  // Category without tagged operations
+  createRoute({
+    path: joinUrl(basePath, UNTAGGED_PATH),
+    untagged: true,
+  }),
+  // Schema list route
+  {
+    path: joinUrl(basePath, "~schemas"),
+    lazy: async () => {
+      const { SchemaList } = await import("../SchemaList.js");
+      return { element: <SchemaList /> };
+    },
+  },
+];
+
+// Creates routes for a specific version, including tag-based routes and the untagged operations route.
+const createVersionRoutes = (
+  versionPath: string,
+  tagPages: string[],
+): RouteObject[] => {
+  const firstTagRoute = joinUrl(versionPath, tagPages.at(0) ?? UNTAGGED_PATH);
+
+  return [
+    // Redirect to first tag on the index route
+    { index: true, loader: () => redirect(firstTagRoute) },
+    // Create routes for each tag
+    ...tagPages.map((tag) =>
+      createRoute({
+        path: joinUrl(versionPath, tag),
+        tag,
+      }),
+    ),
+    ...createAdditionalRoutes(versionPath),
+  ];
+};
+
+export const getVersions = (config: OasPluginConfig) =>
+  config.type === "file" ? Object.keys(config.input) : [];
+
+export const getRoutes = ({
+  basePath,
+  config,
+  client,
+}: {
+  client: GraphQLClient;
+  config: OpenApiPluginOptions;
+  basePath: string;
+}): RouteObject[] => {
+  const tagPages = config.tagPages;
+
+  // If the config does not provide tag pages the catch-all
+  // route handles all operations on a single page
+  if (!tagPages) {
+    return [
+      createOasProvider({
+        basePath,
+        routePath: basePath,
+        routes: [
+          createNonTagPagesRoute({ path: basePath + "/:tag?" }),
+          ...createAdditionalRoutes(basePath),
+        ],
+        client,
+        config,
+      }),
+    ];
+  }
+
+  const versions = getVersions(config);
+  // The latest version always is added as index path
+  const versionsInPath =
+    versions.length > 1 ? [undefined, ...versions] : [undefined];
+
+  return versionsInPath.map((version) => {
+    const versionPath = joinUrl(basePath, version);
+    return createOasProvider({
+      basePath,
+      version,
+      routePath: versionPath,
+      routes: createVersionRoutes(versionPath, tagPages),
+      client,
+      config,
+    });
+  });
+};

package/src/lib/plugins/openapi/util/methodColorMap.tsx

@@ -0,0 +1,11 @@
+import { type ColorMap } from "../../../components/navigation/NavigationBadge.js";
+
+export const MethodColorMap: Record<string, keyof typeof ColorMap> = {
+  get: "green",
+  post: "blue",
+  put: "yellow",
+  delete: "red",
+  patch: "purple",
+  options: "gray",
+  head: "gray",
+};

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

@@ -1,5 +1,5 @@
 import { redirect } from "react-router";
-import { ZudokuRedirect } from "../../../config/validators/common.js";
+import type { ZudokuRedirect } from "../../../config/validators/validate.js";
 import type { ZudokuPlugin } from "../../core/plugins.js";
 
 export const redirectPlugin = (options: {

package/src/lib/plugins/search-pagefind/PagefindSearch.tsx

@@ -0,0 +1,164 @@
+import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import { useRef, useState } from "react";
+import { Button } from "zudoku/ui/Button.js";
+import { Callout } from "zudoku/ui/Callout.js";
+import {
+  CommandDialog,
+  CommandEmpty,
+  CommandInput,
+} from "zudoku/ui/Command.js";
+import { DialogTitle } from "zudoku/ui/Dialog.js";
+import { useAuthState } from "../../authentication/state.js";
+import { useZudoku } from "../../components/context/ZudokuContext.js";
+import { SEARCH_PROTECTED_SECTION } from "../../core/RouteGuard.js";
+import { joinUrl } from "../../util/joinUrl.js";
+import { getResults } from "./get-results.js";
+import type { PagefindOptions } from "./index.js";
+import { ResultList } from "./ResultList.js";
+import type { Pagefind } from "./types.js";
+
+const DEFAULT_RANKING = {
+  // Slightly lower than default because API docs tend to have repetitive terms (parameter names, HTTP methods, etc.)
+  termFrequency: 0.8,
+  // Lower than default because API documentation pages tend to be longer due to comprehensive endpoint documentation
+  pageLength: 0.6,
+  // Slightly higher than default because in technical documentation, exact matches should be prioritized
+  termSimilarity: 1.2,
+  // Slightly lower than default because API docs might have legitimate repetition of terms
+  termSaturation: 1.2,
+};
+
+const importPagefind = (basePath?: string): Promise<Pagefind> =>
+  import.meta.env.DEV
+    ? // @ts-expect-error TypeScript can't resolve the import
+      import(/* @vite-ignore */ "/pagefind/pagefind.js")
+    : import(/* @vite-ignore */ joinUrl(basePath, "/pagefind/pagefind.js"));
+
+const usePagefind = (options: PagefindOptions) => {
+  const {
+    options: { basePath },
+  } = useZudoku();
+  const { data: pagefind, ...result } = useQuery<Pagefind>({
+    queryKey: ["pagefind", options.ranking],
+    retry: false,
+    queryFn: async () => {
+      const pagefind = await importPagefind(basePath);
+      await pagefind.init();
+      await pagefind.options({
+        ranking: {
+          termFrequency:
+            options.ranking?.termFrequency ?? DEFAULT_RANKING.termFrequency,
+          pageLength: options.ranking?.pageLength ?? DEFAULT_RANKING.pageLength,
+          termSimilarity:
+            options.ranking?.termSimilarity ?? DEFAULT_RANKING.termSimilarity,
+          termSaturation:
+            options.ranking?.termSaturation ?? DEFAULT_RANKING.termSaturation,
+        },
+      });
+
+      return pagefind;
+    },
+    enabled: typeof window !== "undefined",
+  });
+
+  if (result.isError && result.error.message !== "NOT_BUILT_YET") {
+    // eslint-disable-next-line no-console
+    console.error(result.error);
+  }
+
+  return { ...result, pagefind };
+};
+
+export const PagefindSearch = ({
+  isOpen,
+  onClose,
+  options,
+}: {
+  isOpen: boolean;
+  onClose: () => void;
+  options: PagefindOptions;
+}) => {
+  const { pagefind, error, isError } = usePagefind(options);
+  const [searchTerm, setSearchTerm] = useState("");
+  const auth = useAuthState();
+  const context = useZudoku();
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const { data: searchResults } = useQuery({
+    queryKey: ["pagefind-search", searchTerm, auth.isAuthenticated],
+    queryFn: async () => {
+      const filters = auth.isAuthenticated
+        ? undefined
+        : { not: { section: SEARCH_PROTECTED_SECTION } };
+
+      const search = await pagefind?.search(searchTerm, { filters });
+      if (!search) return [];
+      return getResults({ search, options, auth, context });
+    },
+    placeholderData: keepPreviousData,
+    enabled: !!pagefind && !!searchTerm,
+  });
+
+  return (
+    <CommandDialog
+      command={{ shouldFilter: false }}
+      content={{ className: "max-w-[750px]" }}
+      open={isOpen}
+      onOpenChange={onClose}
+    >
+      <VisuallyHidden>
+        <DialogTitle>Search</DialogTitle>
+      </VisuallyHidden>
+      <CommandInput
+        ref={inputRef}
+        placeholder="Search..."
+        value={searchTerm}
+        onValueChange={setSearchTerm}
+        disabled={isError}
+      />
+      <CommandEmpty>
+        {searchTerm ? (
+          <div className="flex flex-col items-center">
+            No results found.
+            <Button
+              variant="link"
+              onClick={() => {
+                setSearchTerm("");
+                inputRef.current?.focus();
+              }}
+            >
+              Clear search
+            </Button>
+          </div>
+        ) : (
+          "Start typing to search"
+        )}
+      </CommandEmpty>
+      {isError ? (
+        <div className="p-4 text-sm">
+          {error.message === "NOT_BUILT_YET" ? (
+            <Callout type="info">
+              Search is currently not available in development mode by default.
+              <br />
+              To still use search in development, run <code>
+                zudoku build
+              </code>{" "}
+              and copy the <code>dist/pagefind</code> directory to your{" "}
+              <code>public</code> directory.
+            </Callout>
+          ) : (
+            "An error occurred while loading search."
+          )}
+        </div>
+      ) : (
+        <ResultList
+          searchResults={searchResults ?? []}
+          searchTerm={searchTerm}
+          onClose={onClose}
+          maxSubResults={options.maxSubResults}
+        />
+      )}
+    </CommandDialog>
+  );
+};