zudoku 0.33.1 → 0.34.0

package/src/lib/plugins/openapi/playground/result-panel/ResponseTab.tsx

@@ -1,6 +1,7 @@
 import { useQuery } from "@tanstack/react-query";
 import { ChevronRightIcon } from "lucide-react";
 import { Fragment, useState } from "react";
+import { Callout } from "zudoku/ui/Callout.js";
 import {
   Collapsible,
   CollapsibleContent,
@@ -30,6 +31,14 @@ const statusCodeMap: Record<number, string> = {
   500: "Internal Server Error",
 };
 
+const humanFileSize = (bytes: number) => {
+  const exponent = Math.floor(Math.log(bytes) / Math.log(1000.0));
+  const decimal = (bytes / Math.pow(1000.0, exponent)).toFixed(
+    exponent ? 2 : 0,
+  );
+  return `${decimal} ${exponent ? `${"kMGTPEZY"[exponent - 1]}B` : "B"}`;
+};
+
 const mimeTypeToLanguage = (mimeType: string) => {
   const mimeTypeMapping = {
     "application/json": "json",
@@ -83,6 +92,8 @@ const sortHeadersByRelevance = (
   });
 };
 
+const SYNTAX_HIGHLIGHT_MAX_SIZE_THRESHOLD = 64_000;
+
 export const ResponseTab = ({
   body = "",
   headers,
@@ -114,9 +125,10 @@ export const ResponseTab = ({
   });
 
   const sortedHeaders = sortHeadersByRelevance([...headers]);
+  const shouldDisableHighlighting = size > SYNTAX_HIGHLIGHT_MAX_SIZE_THRESHOLD;
 
   return (
-    <div className="flex flex-col gap-2 h-full overflow-y-scroll max-h-[calc(100vh-220px)] py-4">
+    <div className="flex flex-col gap-2 h-full overflow-auto max-h-[calc(100vh-220px)] ">
       <Collapsible defaultOpen>
         <CollapsibleTrigger className="flex items-center gap-2 hover:text-primary group">
           <ChevronRightIcon className="h-4 w-4 transition-transform duration-200 group-data-[state=open]:rotate-[90deg]" />
@@ -151,6 +163,12 @@ export const ResponseTab = ({
       </Collapsible>
 
       <Card className="shadow-none">
+        {shouldDisableHighlighting && (
+          <Callout type="info" className="my-0 p-2">
+            Code highlight is disabled for responses larger than{" "}
+            {humanFileSize(SYNTAX_HIGHLIGHT_MAX_SIZE_THRESHOLD)}
+          </Callout>
+        )}
         <SyntaxHighlight
           language={
             view === "types"
@@ -161,8 +179,9 @@ export const ResponseTab = ({
                   : detectedLanguage
                 : "json"
           }
+          showCopy="always"
+          disabled={shouldDisableHighlighting}
           noBackground
-          // playground dialog has h-5/6 ≈ 83.333vh
           className="overflow-x-auto p-4 text-xs max-h-[calc(83.333vh-180px)]"
           code={
             (view === "raw"
@@ -173,7 +192,7 @@ export const ResponseTab = ({
           }
         />
       </Card>
-      <div className="flex gap-2 justify-between">
+      <div className="flex gap-2 justify-between items-center">
         <div className="flex text-xs gap-2 border bg-muted rounded-md p-2 items-center h-8 font-mono divide-x">
           <div>
             <span className="text-muted-foreground">Status</span> {status}{" "}
@@ -184,7 +203,8 @@ export const ResponseTab = ({
             {time.toFixed(0)}ms
           </div>
           <div>
-            <span className="text-muted-foreground">Size</span> {size}B
+            <span className="text-muted-foreground">Size</span>{" "}
+            {humanFileSize(size)}
           </div>
         </div>
         {jsonContent && (

package/src/lib/plugins/openapi/playground/result-panel/ResultPanel.tsx

@@ -1,5 +1,6 @@
-import { UseMutationResult } from "@tanstack/react-query";
+import { type UseMutationResult } from "@tanstack/react-query";
 import { Spinner } from "../../../../components/Spinner.js";
+import { Button } from "../../../../ui/Button.js";
 import { Callout } from "../../../../ui/Callout.js";
 import {
   Card,
@@ -14,20 +15,24 @@ import {
   TabsTrigger,
 } from "../../../../ui/Tabs.js";
 import { cn } from "../../../../util/cn.js";
-import { PlaygroundResult } from "../Playground.js";
+import { type PlaygroundResult } from "../Playground.js";
 import { RequestTab } from "./RequestTab.js";
 import { ResponseTab } from "./ResponseTab.js";
 
 export const ResultPanel = ({
   queryMutation,
   showPathParamsWarning,
+  showLongRunningWarning,
+  onCancel,
 }: {
-  queryMutation: UseMutationResult<PlaygroundResult, Error, any, unknown>;
+  queryMutation: UseMutationResult<PlaygroundResult, Error, any>;
   showPathParamsWarning: boolean;
+  showLongRunningWarning?: boolean;
+  onCancel?: () => void;
 }) => {
   const status = ((queryMutation.data?.status ?? 0) / 100).toFixed(0);
   return (
-    <div className="min-w-0 p-8 bg-muted/70 overflow-y-auto">
+    <div className="min-w-0 p-4 bg-muted/50">
       {queryMutation.error ? (
         <div className="flex flex-col gap-2">
           {showPathParamsWarning && (
@@ -49,49 +54,65 @@ export const ResultPanel = ({
           </Card>
         </div>
       ) : queryMutation.data ? (
-        <div className="flex flex-col gap-2">
-          <Tabs defaultValue="response">
-            <TabsList>
-              <TabsTrigger value="request">Request</TabsTrigger>
-              <TabsTrigger value="response">
-                Response
-                <span
-                  className={cn(
-                    "text-xs font-mono ml-1",
-                    status === "2" && "text-green-500",
-                    status === "3" && "text-blue-500",
-                    status === "4" && "text-yellow-500",
-                    status === "5" && "text-red-500",
-                  )}
-                >
-                  ({queryMutation.data.status})
-                </span>
-              </TabsTrigger>
-            </TabsList>
-            <TabsContent value="request">
-              <RequestTab {...queryMutation.data.request} />
-            </TabsContent>
-            <TabsContent value="response">
-              <ResponseTab
-                status={queryMutation.data.status}
-                time={queryMutation.data.time}
-                size={queryMutation.data.size}
-                headers={queryMutation.data.headers}
-                body={queryMutation.data.body}
-                url={queryMutation.data.request.url}
-              />
-            </TabsContent>
-          </Tabs>
-        </div>
+        <Tabs defaultValue="response">
+          <TabsList>
+            <TabsTrigger value="request">Request</TabsTrigger>
+            <TabsTrigger value="response">
+              Response
+              <span
+                className={cn(
+                  "text-xs font-mono ml-1",
+                  status === "2" && "text-green-500",
+                  status === "3" && "text-blue-500",
+                  status === "4" && "text-yellow-500",
+                  status === "5" && "text-red-500",
+                )}
+              >
+                ({queryMutation.data.status})
+              </span>
+            </TabsTrigger>
+          </TabsList>
+          <TabsContent value="request">
+            <RequestTab {...queryMutation.data.request} />
+          </TabsContent>
+          <TabsContent value="response">
+            <ResponseTab
+              status={queryMutation.data.status}
+              time={queryMutation.data.time}
+              size={queryMutation.data.size}
+              headers={queryMutation.data.headers}
+              body={queryMutation.data.body}
+              url={queryMutation.data.request.url}
+            />
+          </TabsContent>
+        </Tabs>
       ) : (
         <div className="grid place-items-center h-full">
-          <span className="text-[16px] font-semibold text-muted-foreground">
-            {queryMutation.isPending ? (
-              <Spinner />
-            ) : (
-              "Send a request first to see the response here"
-            )}
-          </span>
+          {queryMutation.isPending ? (
+            <div className="flex flex-col gap-2 items-center mt-20">
+              <Spinner size={20} />
+              <div
+                className={cn(
+                  "opacity-0 pointer-events-none transition-opacity h-20 text-sm text-muted-foreground duration-300 flex flex-col gap-2 items-center",
+                  showLongRunningWarning && "opacity-100 pointer-events-auto",
+                )}
+              >
+                Looks like the request is taking longer than expected.
+                <Button
+                  onClick={onCancel}
+                  size="sm"
+                  className="w-fit"
+                  variant="outline"
+                >
+                  Cancel
+                </Button>
+              </div>
+            </div>
+          ) : (
+            <span className="text-[16px] font-semibold text-muted-foreground">
+              Send a request first to see the response here
+            </span>
+          )}
         </div>
       )}
     </div>

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

@@ -0,0 +1,135 @@
+import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import { useState } from "react";
+import { Callout } from "zudoku/ui/Callout.js";
+import {
+  CommandDialog,
+  CommandEmpty,
+  CommandInput,
+} from "zudoku/ui/Command.js";
+import { DialogTitle } from "zudoku/ui/Dialog.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) {
+    // 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 { data: searchResults } = useQuery({
+    queryKey: ["pagefind-search", searchTerm],
+    queryFn: async () => {
+      const search = await pagefind?.search(searchTerm);
+      if (!search) return [];
+      return getResults(search, options);
+    },
+    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
+        placeholder="Search..."
+        value={searchTerm}
+        onValueChange={setSearchTerm}
+        disabled={isError}
+      />
+      <CommandEmpty>
+        {searchTerm ? "No results found." : "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,104 @@
+import { FileTextIcon } from "lucide-react";
+import { useCallback } 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 cleanResultUrl = useCallback(
+    (url: string) => {
+      const clean = url.replace(".html", "");
+      return basePath && clean.startsWith(basePath)
+        ? clean.slice(basePath.length)
+        : clean;
+    },
+    [basePath],
+  );
+
+  return (
+    <CommandList className="max-h-[450px]">
+      {searchTerm && searchResults.length > 0 && (
+        <CommandGroup
+          className="text-sm text-muted-foreground"
+          heading={`${searchResults.length} results for "${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)}>
+              <FileTextIcon size={20} className="text-muted-foreground" />
+              {result.meta.title}
+            </Link>
+          </CommandItem>
+          {result.sub_results
+            .sort(sortSubResults)
+            .slice(0, maxSubResults)
+            .map((subResult) => (
+              <CommandItem
+                asChild
+                key={`${result.meta.title}-${subResult.url}`}
+                value={`${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,54 @@
+import type { PagefindOptions } from "./index.js";
+import type { PagefindSearchFragment, PagefindSearchResults } from "./types.js";
+
+export const getResults = async (
+  search: PagefindSearchResults,
+  options: PagefindOptions,
+) => {
+  const maxResults = options.maxResults ?? 10;
+  const transformFn = options.transformResults ?? (() => true);
+
+  const transformedResults: PagefindSearchFragment[] = [];
+
+  const generator = searchResultGenerator(search, transformFn);
+
+  for await (const result of generator) {
+    transformedResults.push(result);
+    if (transformedResults.length >= maxResults) break;
+  }
+
+  return transformedResults;
+};
+
+async function* searchResultGenerator(
+  search: PagefindSearchResults,
+  transformFn: NonNullable<PagefindOptions["transformResults"]>,
+) {
+  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);
+
+      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;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,21 @@
+import type { ZudokuConfig } from "../../../config/validators/validate.js";
+import { ClientOnly } from "../../components/ClientOnly.js";
+import type { ZudokuPlugin } from "../../core/plugins.js";
+import { PagefindSearch } from "./PagefindSearch.js";
+
+export type PagefindOptions = Extract<
+  ZudokuConfig["search"],
+  { type: "pagefind" }
+> & { basePath?: string };
+
+export const pagefindSearchPlugin = (
+  options: PagefindOptions,
+): ZudokuPlugin => {
+  return {
+    renderSearch: ({ isOpen, onClose }) => (
+      <ClientOnly>
+        <PagefindSearch isOpen={isOpen} onClose={onClose} options={options} />
+      </ClientOnly>
+    ),
+  };
+};

package/src/lib/plugins/search-pagefind/types.ts

@@ -0,0 +1,118 @@
+interface PagefindIndexOptions {
+  basePath?: string;
+  baseUrl?: string;
+  excerptLength?: number;
+  indexWeight?: number;
+  mergeFilter?: Record<string, unknown>;
+  highlightParam?: string;
+  language?: string;
+  primary?: boolean;
+  ranking?: PagefindRankingWeights;
+}
+
+interface PagefindRankingWeights {
+  termSimilarity?: number;
+  pageLength?: number;
+  termSaturation?: number;
+  termFrequency?: number;
+}
+
+interface PagefindSearchOptions {
+  preload?: boolean;
+  verbose?: boolean;
+  filters?: Record<string, unknown>;
+  sort?: Record<string, unknown>;
+}
+
+type PagefindFilterCounts = Record<string, Record<string, number>> & {};
+
+interface PagefindSearchResults {
+  results: PagefindSearchResult[];
+  unfilteredResultCount: number;
+  filters: PagefindFilterCounts;
+  totalFilters: PagefindFilterCounts;
+  timings: {
+    preload: number;
+    search: number;
+    total: number;
+  };
+}
+
+interface PagefindSearchResult {
+  id: string;
+  score: number;
+  words: number[];
+  data: () => Promise<PagefindSearchFragment>;
+}
+
+interface PagefindSearchFragment {
+  url: string;
+  raw_url?: string;
+  content: string;
+  raw_content?: string;
+  excerpt: string;
+  sub_results: PagefindSubResult[];
+  word_count: number;
+  locations: number[];
+  weighted_locations: PagefindWordLocation[];
+  filters: Record<string, string[]>;
+  meta: Record<string, string>;
+  anchors: PagefindSearchAnchor[];
+}
+
+interface PagefindSubResult {
+  title: string;
+  url: string;
+  locations: number[];
+  weighted_locations: PagefindWordLocation[];
+  excerpt: string;
+  anchor?: PagefindSearchAnchor;
+}
+
+interface PagefindWordLocation {
+  weight: number;
+  balanced_score: number;
+  location: number;
+}
+
+interface PagefindSearchAnchor {
+  element: string;
+  id: string;
+  text?: string;
+  location: number;
+}
+
+interface Pagefind {
+  debouncedSearch: (
+    query: string,
+    options?: PagefindSearchOptions,
+    duration?: number,
+  ) => Promise<PagefindSearchResults>;
+  destroy: () => Promise<void>;
+  filters: () => Promise<PagefindFilterCounts>;
+  init: () => Promise<void>;
+  mergeIndex: (
+    indexPath: string,
+    options?: Record<string, unknown>,
+  ) => Promise<void>;
+  options: (options: PagefindIndexOptions) => Promise<void>;
+  preload: (term: string, options?: PagefindIndexOptions) => Promise<void>;
+  search: (
+    term: string,
+    options?: PagefindSearchOptions,
+  ) => Promise<PagefindSearchResults>;
+}
+
+export type {
+  Pagefind,
+  PagefindFilterCounts,
+  PagefindIndexOptions,
+  PagefindRankingWeights,
+  PagefindSearchAnchor,
+  PagefindSearchFragment,
+  PagefindSearchOptions,
+  PagefindSearchResult,
+  PagefindSearchResults,
+  PagefindSubResult,
+  PagefindWordLocation,
+};