zudoku 0.33.1 → 0.33.2-local.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.33.1",
+  "version": "0.33.2-local.4",
   "type": "module",
   "homepage": "https://zudoku.dev",
   "repository": {
@@ -86,6 +86,10 @@
       "import": "./lib/zudoku.plugin-search-inkeep.js",
       "types": "./dist/lib/plugins/search-inkeep/index.d.ts"
     },
+    "./plugins/search-pagefind": {
+      "import": "./lib/zudoku.plugin-search-pagefind.js",
+      "types": "./dist/lib/plugins/search-pagefind/index.d.ts"
+    },
     "./components": {
       "import": "./lib/zudoku.components.js",
       "types": "./dist/lib/components/index.d.ts"
@@ -167,6 +171,7 @@
     "devlop": "^1.1.0",
     "dotenv": "16.4.7",
     "embla-carousel-react": "8.5.2",
+    "esm-loader-css": "^1.0.3",
     "estree-util-value-to-estree": "3.3.2",
     "express": "4.21.2",
     "glob": "11.0.1",
@@ -186,6 +191,7 @@
     "oauth4webapi": "2.17.0",
     "object-hash": "3.0.0",
     "openapi-types": "12.1.3",
+    "pagefind": "1.4.0-alpha.1",
     "picocolors": "1.1.1",
     "piscina": "5.0.0-alpha.1",
     "postcss": "8.5.2",
@@ -226,8 +232,7 @@
     "yargs": "17.7.2",
     "zod": "3.24.2",
     "zod-validation-error": "3.4.0",
-    "zustand": "5.0.3",
-    "esm-loader-css": "^1.0.3"
+    "zustand": "5.0.3"
   },
   "devDependencies": {
     "@graphql-codegen/cli": "5.0.5",

package/src/lib/authentication/hook.ts

@@ -15,7 +15,9 @@ export const useAuth = () => {
         throw new Error("Authentication is not enabled.");
       }
       // TODO: Should handle errors/state
-      await authentication.signIn();
+      await authentication.signIn({
+        redirectTo: window.location.href,
+      });
     },
 
     logout: async () => {
@@ -28,5 +30,14 @@ export const useAuth = () => {
       // Redirect to home
       window.location.href = "/";
     },
+
+    signup: async () => {
+      if (!isAuthEnabled) {
+        throw new Error("Authentication is not enabled.");
+      }
+      await authentication.signUp({
+        redirectTo: window.location.href,
+      });
+    },
   };
 };

package/src/lib/authentication/providers/clerk.tsx

@@ -106,18 +106,22 @@ const clerkAuth: AuthenticationProviderInitializer<
         providerData: null,
       });
     },
-    signIn: async () => {
+    signIn: async ({ redirectTo }: { redirectTo?: string }) => {
       await ensureLoaded;
       await clerkApi?.redirectToSignIn({
-        signInForceRedirectUrl: window.location.origin + redirectToAfterSignIn,
-        signUpForceRedirectUrl: window.location.origin + redirectToAfterSignUp,
+        signInForceRedirectUrl:
+          redirectTo ?? window.location.origin + redirectToAfterSignIn,
+        signUpForceRedirectUrl:
+          redirectTo ?? window.location.origin + redirectToAfterSignUp,
       });
     },
-    signUp: async () => {
+    signUp: async ({ redirectTo }: { redirectTo?: string }) => {
       await ensureLoaded;
       await clerkApi?.redirectToSignUp({
-        signInForceRedirectUrl: window.location.origin + redirectToAfterSignIn,
-        signUpForceRedirectUrl: window.location.origin + redirectToAfterSignUp,
+        signInForceRedirectUrl:
+          redirectTo ?? window.location.origin + redirectToAfterSignIn,
+        signUpForceRedirectUrl:
+          redirectTo ?? window.location.origin + redirectToAfterSignUp,
       });
     },
     getAuthenticationPlugin() {

package/src/lib/components/Banner.tsx

@@ -34,6 +34,7 @@ export const Banner = () => {
         "relative text-primary-foreground text-sm font-medium px-4 py-2 flex gap-2 items-center",
         mappedColor,
       )}
+      data-pagefind-ignore="all"
       style={style}
     >
       <div className="w-full">{page.banner.message}</div>

package/src/lib/components/Heading.tsx

@@ -38,7 +38,7 @@ const getComponent = (level: number) => {
   }
 };
 
-export type HeadingProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
+export type HeadingProps = React.HTMLAttributes<HTMLHeadingElement> &
   VariantProps<typeof heading> & {
     children: ReactNode;
     className?: string;

package/src/lib/components/Layout.tsx

@@ -89,6 +89,7 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
                 </DrawerTrigger>
               </div>
               <main
+                data-pagefind-body
                 className={cn(
                   "h-full dark:border-white/10 translate-x-0",
                   "lg:overflow-visible",

package/src/lib/core/RouteGuard.tsx

@@ -27,9 +27,10 @@ export const RouteGuard = () => {
     queryKey: ["login-redirect"],
     queryFn: async () => {
       await new Promise((resolve) => setTimeout(resolve, 1200));
-      return zudoku.authentication?.signIn({
+      await zudoku.authentication?.signIn({
         redirectTo: latestPath.current,
       });
+      return true;
     },
     enabled:
       typeof window !== "undefined" &&

package/src/lib/plugins/api-catalog/Catalog.tsx

@@ -1,6 +1,7 @@
 import { useSuspenseQuery } from "@tanstack/react-query";
+import { Helmet } from "@zudoku/react-helmet-async";
 import { useMatch } from "react-router";
-import { Head, Link } from "zudoku/components";
+import { Link } from "zudoku/components";
 import { useAuthState } from "../../authentication/state.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
@@ -11,7 +12,10 @@ export const Catalog = ({
   items,
   filterCatalogItems = (items) => items,
   label = "API Library",
-}: Omit<ApiCatalogPluginOptions, "navigationId">) => {
+  categoryLabel,
+}: Omit<ApiCatalogPluginOptions, "navigationId"> & {
+  categoryLabel?: string;
+}) => {
   const auth = useAuthState();
   const match = useMatch({ path: "/catalog/:category" });
   const activeCategory = match?.params.category;
@@ -21,13 +25,25 @@ export const Catalog = ({
     queryKey: ["catalogItems", auth],
   });
 
+  // Only index the overview page, ignore the rest
+  const dataSet = activeCategory ? { "data-pagefind-ignore": "all" } : {};
+
   return (
-    <section className="pt-[--padding-content-top] pb-[--padding-content-bottom]">
-      <Head>
-        <title>{label}</title>
-      </Head>
+    <section
+      className="pt-[--padding-content-top] pb-[--padding-content-bottom]"
+      {...dataSet}
+    >
+      <Helmet>
+        <title>
+          {categoryLabel ? `${categoryLabel} - ` : ""}
+          {label}
+        </title>
+      </Helmet>
       <div className="grid gap-4">
-        <Heading level={2}>{label}</Heading>
+        <Heading level={2}>
+          {label}
+          {categoryLabel && ` - ${categoryLabel}`}
+        </Heading>
 
         <div className="grid grid-cols-2 gap-4">
           {catalogItems.data

package/src/lib/plugins/api-catalog/index.tsx

@@ -98,6 +98,7 @@ export const apiCatalogPlugin = ({
           element: (
             <Catalog
               label={label}
+              categoryLabel={tag}
               items={items}
               filterCatalogItems={filterCatalogItems}
               categories={categories}

package/src/lib/plugins/markdown/MdxPage.tsx

@@ -90,7 +90,11 @@ export const MdxPage = ({
   }, [file]);
 
   return (
-    <div className="xl:grid grid-cols-[--sidecar-grid-cols] gap-8 justify-between">
+    <div
+      className="xl:grid grid-cols-[--sidecar-grid-cols] gap-8 justify-between"
+      data-pagefind-filter="section:markdown"
+      data-pagefind-meta="section:markdown"
+    >
       <Helmet>
         <title>{pageTitle}</title>
         {excerpt && <meta name="description" content={excerpt} />}

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

@@ -1,4 +1,4 @@
-import { ResultOf } from "@graphql-typed-document-node/core";
+import { type ResultOf } from "@graphql-typed-document-node/core";
 import { useSuspenseQuery } from "@tanstack/react-query";
 import { Helmet } from "@zudoku/react-helmet-async";
 import { useNavigate } from "react-router";
@@ -152,8 +152,14 @@ export const OperationList = ({
       ? sanitizeMarkdownForMetatag(description)
       : undefined;
 
+  const showVersions = Object.entries(versions).length > 1;
+
   return (
-    <div className="pt-[--padding-content-top]">
+    <div
+      className="pt-[--padding-content-top]"
+      data-pagefind-filter="section:openapi"
+      data-pagefind-meta="section:openapi"
+    >
       <Helmet>
         <title>{title}</title>
         {metaDescription && (
@@ -168,10 +174,16 @@ export const OperationList = ({
             <CategoryHeading>Overview</CategoryHeading>
             <Heading level={1} id="description" registerSidebarAnchor>
               {title}
+              {showVersions && (
+                <span className="text-xl text-muted-foreground">
+                  {" "}
+                  ({version})
+                </span>
+              )}
             </Heading>
           </div>
           <div>
-            {Object.entries(versions).length > 1 && (
+            {showVersions && (
               <Select
                 onValueChange={(version) => navigate(versions[version]!)}
                 defaultValue={version}

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

@@ -1,3 +1,4 @@
+import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
 import { useRef, useState } from "react";
 import { Heading } from "../../components/Heading.js";
 import { Markdown, ProseClasses } from "../../components/Markdown.js";
@@ -84,6 +85,7 @@ export const OperationListItem = ({
               groupedParameters[group]?.length ? (
                 <ParameterList
                   key={group}
+                  summary={operation.summary ?? undefined}
                   id={operation.slug}
                   parameters={groupedParameters[group]}
                   group={group}
@@ -101,6 +103,9 @@ export const OperationListItem = ({
               className="capitalize"
               id={`${operation.slug}/request-body`}
             >
+              {operation.summary && (
+                <VisuallyHidden>{operation.summary} &rsaquo; </VisuallyHidden>
+              )}
               Request Body
             </Heading>
             <SchemaView schema={schema} />
@@ -113,6 +118,9 @@ export const OperationListItem = ({
               className="capitalize mt-8 pt-8 border-t"
               id={`${operation.slug}/responses`}
             >
+              {operation.summary && (
+                <VisuallyHidden>{operation.summary} &rsaquo; </VisuallyHidden>
+              )}
               Responses
             </Heading>
             <Tabs

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

@@ -1,3 +1,4 @@
+import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
 import { Heading } from "../../components/Heading.js";
 import { Card } from "../../ui/Card.js";
 import type { ParameterGroup } from "./OperationListItem.js";
@@ -7,16 +8,19 @@ import {
 } from "./ParameterListItem.js";
 
 export const ParameterList = ({
+  summary,
   group,
   parameters,
   id,
 }: {
+  summary?: string;
   group: ParameterGroup;
   parameters: ParameterListItemResult[];
   id: string;
 }) => (
   <>
     <Heading level={3} id={`${id}/${group}-parameters`} className="capitalize">
+      {summary && <VisuallyHidden>{summary} &rsaquo; </VisuallyHidden>}
       {group === "header" ? "Headers" : `${group} Parameters`}
     </Heading>
     <Card>

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

@@ -1,3 +1,4 @@
+import { useAuth } from "zudoku/components";
 import type { OperationListItemResult } from "./OperationList.js";
 import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
 import { Content } from "./SidecarExamples.js";
@@ -13,6 +14,9 @@ export const PlaygroundDialogWrapper = ({
   operation: OperationListItemResult;
   examples?: Content;
 }) => {
+  const { isAuthEnabled, login, signup, isPending, isAuthenticated } =
+    useAuth();
+
   const headers = operation.parameters
     ?.filter((p) => p.in === "header")
     .sort((a, b) => (a.required && !b.required ? -1 : 1))
@@ -49,6 +53,9 @@ export const PlaygroundDialogWrapper = ({
       queryParams={queryParams}
       pathParams={pathParams}
       examples={examples}
+      requiresLogin={isAuthEnabled && !isAuthenticated && !isPending}
+      onLogin={() => login()}
+      onSignUp={() => signup()}
     />
   );
 };

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

@@ -175,6 +175,7 @@ export const Sidecar = ({
     <aside
       ref={ref}
       className="flex flex-col overflow-hidden sticky top-[--scroll-padding] gap-4"
+      data-pagefind-ignore="all"
     >
       <SidecarBox.Root>
         <SidecarBox.Head className="flex justify-between items-center flex-nowrap py-2.5 gap-2 text-xs">

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

@@ -1,4 +1,4 @@
-import { Control, Controller, useFieldArray } from "react-hook-form";
+import { type Control, Controller, useFieldArray } from "react-hook-form";
 import { Card } from "zudoku/ui/Card.js";
 import { Input } from "../../../ui/Input.js";
 import { ColorizedParam } from "../ColorizedParam.js";
@@ -7,18 +7,24 @@ import type { PlaygroundForm } from "./Playground.js";
 
 export const PathParams = ({
   control,
+  url,
 }: {
   control: Control<PlaygroundForm>;
+  url: string;
 }) => {
   const { fields } = useFieldArray<PlaygroundForm, "pathParams">({
     control,
     name: "pathParams",
   });
 
+  const sortedFields = [...fields].sort(
+    (a, b) => url.indexOf(`{${a.name}}`) - url.indexOf(`{${b.name}}`),
+  );
+
   return (
     <Card className="rounded-lg">
       <ParamsGrid>
-        {fields.map((field, i) => (
+        {sortedFields.map((field, i) => (
           <ParamsGridItem key={field.id}>
             <Controller
               control={control}

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

@@ -1,10 +1,11 @@
 import { useMutation } from "@tanstack/react-query";
 import { InfoIcon } from "lucide-react";
-import { Fragment, useEffect, useRef, useTransition } from "react";
+import { Fragment, useEffect, useRef, useState, useTransition } from "react";
 import { FormProvider, useForm } from "react-hook-form";
 import { Alert, AlertDescription, AlertTitle } from "zudoku/ui/Alert.js";
 import { PathRenderer } from "../../../components/PathRenderer.js";
 
+import { Button } from "zudoku/ui/Button.js";
 import { Label } from "zudoku/ui/Label.js";
 import { RadioGroup, RadioGroupItem } from "zudoku/ui/RadioGroup.js";
 import {
@@ -97,6 +98,9 @@ export type PlaygroundContentProps = {
   pathParams?: PathParam[];
   defaultBody?: string;
   examples?: Content;
+  requiresLogin?: boolean;
+  onLogin?: () => void;
+  onSignUp?: () => void;
 };
 
 export const Playground = ({
@@ -109,11 +113,15 @@ export const Playground = ({
   pathParams = [],
   defaultBody = "",
   examples,
+  requiresLogin = false,
+  onLogin,
+  onSignUp,
 }: PlaygroundContentProps) => {
   const { selectedServer, setSelectedServer } = useSelectedServer(
     servers.map((url) => ({ url })),
   );
   const [, startTransition] = useTransition();
+  const [skipLogin, setSkipLogin] = useState(false);
   const { register, control, handleSubmit, watch, setValue, ...form } =
     useForm<PlaygroundForm>({
       defaultValues: {
@@ -262,7 +270,7 @@ export const Playground = ({
     ));
 
   const serverSelect = (
-    <div className="inline-block opacity-50 hover:opacity-100 transition">
+    <div className="inline-block opacity-50 hover:opacity-100 transition translate-y-[4px]">
       {server ? (
         <span>{server.replace(/^https?:\/\//, "")}</span>
       ) : (
@@ -290,6 +298,8 @@ export const Playground = ({
     </div>
   );
 
+  const showLogin = requiresLogin && !skipLogin;
+
   return (
     <FormProvider
       {...{ register, control, handleSubmit, watch, setValue, ...form }}
@@ -297,15 +307,61 @@ export const Playground = ({
       <form
         onSubmit={handleSubmit((data) => queryMutation.mutateAsync(data))}
         ref={formRef}
+        className="relative"
       >
-        <div className="grid grid-cols-2 text-sm h-full">
+        {showLogin && (
+          <div className="absolute top-1/2 right-1/2  -translate-y-1/2 translate-x-1/2 z-50 max-w-md">
+            <Alert>
+              <AlertTitle className="mb-2">
+                Welcome to the Playground!
+              </AlertTitle>
+              <AlertDescription className="flex flex-col gap-2">
+                <div className="mb-2">
+                  The Playground is a tool for developers to test and explore
+                  our APIs. To use the Playground, you need to login.
+                </div>
+                <div className="flex gap-2 justify-between">
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    onClick={() => setSkipLogin(true)}
+                  >
+                    Skip
+                  </Button>
+                  <div className="flex gap-2">
+                    {onSignUp && (
+                      <Button
+                        type="button"
+                        variant="outline"
+                        onClick={onSignUp}
+                      >
+                        Sign Up
+                      </Button>
+                    )}
+                    {onLogin && (
+                      <Button type="button" variant="default" onClick={onLogin}>
+                        Login
+                      </Button>
+                    )}
+                  </div>
+                </div>
+              </AlertDescription>
+            </Alert>
+          </div>
+        )}
+        <div
+          className={cn(
+            "grid grid-cols-2 text-sm h-full",
+            showLogin && "opacity-30 pointer-events-none",
+          )}
+        >
           <div className="flex flex-col gap-4 p-4 after:bg-muted-foreground/20 relative after:absolute after:w-px after:inset-0 after:left-auto">
             <div className="flex gap-2 items-stretch">
               <div className="flex flex-1 items-center w-full border rounded-md">
                 <div className="border-r p-2 bg-muted rounded-l-md self-stretch font-semibold font-mono flex items-center">
                   {method.toUpperCase()}
                 </div>
-                <div className="items-center p-2 font-mono text-xs break-words">
+                <div className="items-center px-2 py-0.5 font-mono text-xs break-all leading-6">
                   {serverSelect}
                   {path}
                   {urlQueryParams.length > 0 ? "?" : ""}
@@ -351,7 +407,7 @@ export const Playground = ({
                 {pathParams.length > 0 && (
                   <div className="flex flex-col gap-4 my-4">
                     <span className="font-semibold">Path Parameters</span>
-                    <PathParams control={control} />
+                    <PathParams url={url} control={control} />
                   </div>
                 )}
                 <div className="flex flex-col gap-4 my-4">

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>
+  );
+};