zudoku 0.0.0-f3f6db5 → 0.0.0-f471fb8

package/src/lib/plugins/openapi/schema/SchemaView.tsx

@@ -3,12 +3,22 @@ import type { SchemaObject } from "../../../oas/parser/index.js";
 import { Card, CardContent, CardHeader, CardTitle } from "../../../ui/Card.js";
 import { cn } from "../../../util/cn.js";
 import { groupBy } from "../../../util/groupBy.js";
+import { EnumValues } from "../components/EnumValues.js";
+import { ParamInfos } from "../ParamInfos.js";
 import {
   SchemaLogicalGroup,
   SchemaPropertyItem,
 } from "./SchemaPropertyItem.js";
 import { hasLogicalGroupings } from "./utils.js";
 
+const renderMarkdown = (content?: string) =>
+  content && (
+    <Markdown
+      className={cn(ProseClasses, "text-sm leading-normal line-clamp-4")}
+      content={content}
+    />
+  );
+
 export const SchemaView = ({
   schema,
   level = 0,
@@ -33,11 +43,33 @@ export const SchemaView = ({
       return <SchemaLogicalGroup schema={schema} level={level} />;
     }
 
-    // Sometimes items is not defined
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (schema.type === "array" && schema.items) {
+    if (Array.isArray(schema.type)) {
+      return (
+        <Card className="p-4 space-y-2">
+          <span className="text-sm text-muted-foreground">
+            <ParamInfos schema={schema} />
+          </span>
+          {schema.enum && <EnumValues values={schema.enum} />}
+          {renderMarkdown(schema.description)}
+        </Card>
+      );
+    }
+
+    if (schema.type === "array" && typeof schema.items === "object") {
       const itemsSchema = schema.items as SchemaObject;
 
+      if (itemsSchema.enum) {
+        return (
+          <Card className="p-4">
+            <span className="text-sm text-muted-foreground">
+              <ParamInfos schema={schema} />
+            </span>
+            <EnumValues values={itemsSchema.enum} />
+            {renderMarkdown(schema.description)}
+          </Card>
+        );
+      }
+
       if (
         typeof itemsSchema.type === "string" &&
         ["string", "number", "boolean", "integer"].includes(itemsSchema.type)
@@ -45,17 +77,9 @@ export const SchemaView = ({
         return (
           <Card className="p-4">
             <span className="text-sm text-muted-foreground">
-              {itemsSchema.type}[]
+              <ParamInfos schema={schema} />
             </span>
-            {schema.description && (
-              <Markdown
-                className={cn(
-                  ProseClasses,
-                  "text-sm leading-normal line-clamp-4",
-                )}
-                content={schema.description}
-              />
-            )}
+            {renderMarkdown(schema.description)}
           </Card>
         );
       } else if (itemsSchema.type === "object") {
@@ -75,18 +99,12 @@ export const SchemaView = ({
       (!schema.properties || Object.keys(schema.properties).length === 0)
     ) {
       return (
-        <Card className="p-4 flex gap-2 items-center">
+        <Card className="p-4 flex gap-2 items-baseline">
           {"name" in schema && <>{schema.name as string}</>}
-          <span className="text-sm text-muted-foreground">object</span>
-          {schema.description && (
-            <Markdown
-              className={cn(
-                ProseClasses,
-                "text-sm leading-normal line-clamp-4",
-              )}
-              content={schema.description}
-            />
-          )}
+          <span className="text-sm text-muted-foreground">
+            <ParamInfos schema={schema} />
+          </span>
+          {renderMarkdown(schema.description)}
         </Card>
       );
     }
@@ -133,17 +151,12 @@ export const SchemaView = ({
       ["string", "number", "boolean", "integer", "null"].includes(schema.type)
     ) {
       return (
-        <Card className="p-4">
-          <span className="text-sm text-muted-foreground">{schema.type}</span>
-          {schema.description && (
-            <Markdown
-              className={cn(
-                ProseClasses,
-                "text-sm leading-normal line-clamp-4",
-              )}
-              content={schema.description}
-            />
-          )}
+        <Card className="p-4 space-y-2">
+          <span className="text-sm text-muted-foreground">
+            <ParamInfos schema={schema} />
+          </span>
+          {schema.enum && <EnumValues values={schema.enum} />}
+          {renderMarkdown(schema.description)}
         </Card>
       );
     }

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/createSidebarCategory.tsx

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

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

@@ -0,0 +1,126 @@
+import { redirect, type RouteObject } from "react-router";
+import { joinUrl } from "../../../util/joinUrl.js";
+import type { GraphQLClient } from "../client/GraphQLClient.js";
+import { 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} /> };
+  },
+});
+
+// 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,
+      }),
+    ),
+    // Category without tagged operations
+    createRoute({
+      path: joinUrl(versionPath, UNTAGGED_PATH),
+      untagged: true,
+    }),
+    {
+      path: joinUrl(versionPath, "~schemas"),
+      lazy: async () => {
+        const { SchemaList } = await import("../SchemaList.js");
+        return { element: <SchemaList /> };
+      },
+    },
+  ];
+};
+
+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: [createRoute({ path: basePath + "/:tag?" })],
+        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 { ColorMap } from "../../../components/navigation/SidebarBadge.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/search-pagefind/PagefindSearch.tsx

@@ -0,0 +1,157 @@
+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 { 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 { data: pagefind, ...result } = useQuery<Pagefind>({
+    queryKey: ["pagefind", options.ranking],
+    retry: false,
+    queryFn: async () => {
+      const pagefind = await importPagefind(options.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],
+    queryFn: async () => {
+      const search = await pagefind?.search(searchTerm);
+      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
+          basePath={options.basePath}
+          searchResults={searchResults ?? []}
+          searchTerm={searchTerm}
+          onClose={onClose}
+          maxSubResults={options.maxSubResults}
+        />
+      )}
+    </CommandDialog>
+  );
+};

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

@@ -0,0 +1,116 @@
+import { BracketsIcon, FileTextIcon } from "lucide-react";
+import { useCallback, useLayoutEffect, useRef } from "react";
+import { Link, useNavigate } from "react-router";
+import { CommandGroup, CommandItem, CommandList } from "zudoku/ui/Command.js";
+import {
+  type PagefindSearchFragment,
+  type PagefindSubResult,
+} from "./types.js";
+
+const sortSubResults = (a: PagefindSubResult, b: PagefindSubResult) => {
+  const aScore = a.weighted_locations.reduce(
+    (sum, loc) => sum + loc.balanced_score,
+    0,
+  );
+  const bScore = b.weighted_locations.reduce(
+    (sum, loc) => sum + loc.balanced_score,
+    0,
+  );
+  return bScore - aScore;
+};
+
+const hoverClassname = `cursor-pointer border border-transparent data-[selected=true]:border-border`;
+
+export const ResultList = ({
+  basePath,
+  searchResults,
+  searchTerm,
+  onClose,
+  maxSubResults = 4,
+}: {
+  basePath?: string;
+  searchResults: PagefindSearchFragment[];
+  searchTerm: string;
+  onClose: () => void;
+  maxSubResults?: number;
+}) => {
+  const navigate = useNavigate();
+  const commandListRef = useRef<HTMLDivElement | null>(null);
+
+  const cleanResultUrl = useCallback(
+    (url: string) => {
+      const clean = url.replace(".html", "");
+      return basePath && clean.startsWith(basePath)
+        ? clean.slice(basePath.length)
+        : clean;
+    },
+    [basePath],
+  );
+
+  useLayoutEffect(() => {
+    requestIdleCallback(() => {
+      commandListRef.current?.scrollTo({ top: 0 });
+    });
+  }, [searchTerm]);
+
+  return (
+    <CommandList className="max-h-[450px]" ref={commandListRef}>
+      {searchTerm && searchResults.length > 0 && (
+        <CommandGroup
+          className="text-sm text-muted-foreground"
+          heading={`${searchResults.length} results for "${searchTerm}"`}
+        />
+      )}
+      {searchTerm &&
+        searchResults.map((result) => (
+          <CommandGroup
+            key={[result.meta.title ?? result.excerpt, result.url].join("-")}
+          >
+            <CommandItem
+              asChild
+              value={`${result.meta.title}-${result.url}`}
+              className={hoverClassname}
+              onSelect={() => {
+                void navigate(cleanResultUrl(result.url));
+                onClose();
+              }}
+            >
+              <Link to={cleanResultUrl(result.url)}>
+                {result.meta.section === "openapi" ? (
+                  <BracketsIcon />
+                ) : (
+                  <FileTextIcon />
+                )}
+                {result.meta.title}
+              </Link>
+            </CommandItem>
+            {result.sub_results
+              .sort(sortSubResults)
+              .slice(0, maxSubResults)
+              .map((subResult) => (
+                <CommandItem
+                  asChild
+                  key={`sub-${result.meta.title}-${subResult.url}`}
+                  value={`sub-${result.meta.title}-${subResult.url}`}
+                  className={hoverClassname}
+                  onSelect={() => {
+                    void navigate(cleanResultUrl(subResult.url));
+                    onClose();
+                  }}
+                >
+                  <Link to={cleanResultUrl(subResult.url)} onClick={onClose}>
+                    <div className="flex flex-col items-start gap-2 ms-2.5 ps-5 border-l border-muted-foreground/50">
+                      <span className="font-bold">{subResult.title}</span>
+                      <span
+                        className="text-[13px] [&_mark]:bg-primary [&_mark]:text-primary-foreground"
+                        dangerouslySetInnerHTML={{ __html: subResult.excerpt }}
+                      />
+                    </div>
+                  </Link>
+                </CommandItem>
+              ))}
+          </CommandGroup>
+        ))}
+    </CommandList>
+  );
+};

package/src/lib/plugins/search-pagefind/get-results.tsx

@@ -0,0 +1,75 @@
+import type { AuthState } from "../../authentication/state.js";
+import type { ZudokuContext } from "../../core/ZudokuContext.js";
+import type { PagefindOptions } from "./index.js";
+import type { PagefindSearchFragment, PagefindSearchResults } from "./types.js";
+
+export const getResults = async ({
+  search,
+  options,
+  auth,
+  context,
+}: {
+  search: PagefindSearchResults;
+  options: PagefindOptions;
+  auth: AuthState;
+  context: ZudokuContext;
+}) => {
+  const maxResults = options.maxResults ?? 10;
+  const transformFn = options.transformResults ?? (() => true);
+
+  const transformedResults: PagefindSearchFragment[] = [];
+
+  const generator = searchResultGenerator({
+    search,
+    transformFn,
+    auth,
+    context,
+  });
+
+  for await (const result of generator) {
+    transformedResults.push(result);
+    if (transformedResults.length >= maxResults) break;
+  }
+
+  return transformedResults;
+};
+
+async function* searchResultGenerator({
+  search,
+  transformFn,
+  auth,
+  context,
+}: {
+  search: PagefindSearchResults;
+  transformFn: NonNullable<PagefindOptions["transformResults"]>;
+  auth: AuthState<unknown>;
+  context: ZudokuContext;
+}) {
+  const batchSize = 5;
+  let processedCount = 0;
+
+  while (processedCount < search.results.length) {
+    const batch = search.results.slice(
+      processedCount,
+      processedCount + batchSize,
+    );
+    processedCount += batch.length;
+
+    const batchData = await Promise.all(batch.map((result) => result.data()));
+
+    for (const result of batchData) {
+      const transformed = transformFn({ result, auth, context });
+
+      if (transformed === false) {
+        // Skip this result
+        continue;
+      } else if (transformed === true || transformed == null) {
+        // Keep the original result
+        yield result;
+      } else {
+        // Return the transformed result
+        yield transformed;
+      }
+    }
+  }
+}