zudoku 0.0.0-e5b3c9b → 0.0.0-e614aaa

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

@@ -262,7 +262,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>
       ) : (
@@ -305,7 +305,7 @@ export const Playground = ({
                 <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 +351,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,139 @@
+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 = (): 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(
+          import.meta.env.BASE_URL,
+          "/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();
+      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
+          searchResults={searchResults ?? []}
+          searchTerm={searchTerm}
+          onClose={onClose}
+          maxSubResults={options.maxSubResults}
+        />
+      )}
+    </CommandDialog>
+  );
+};

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

@@ -0,0 +1,98 @@
+import { FileTextIcon } from "lucide-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`;
+
+const cleanResultUrl = (url: string) => {
+  const clean = url.replace(".html", "");
+  return clean.startsWith(import.meta.env.BASE_URL)
+    ? clean.slice(import.meta.env.BASE_URL.length)
+    : clean;
+};
+
+export const ResultList = ({
+  searchResults,
+  searchTerm,
+  onClose,
+  maxSubResults = 4,
+}: {
+  searchResults: PagefindSearchFragment[];
+  searchTerm: string;
+  onClose: () => void;
+  maxSubResults?: number;
+}) => {
+  const navigate = useNavigate();
+
+  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" }
+>;
+
+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,
+};

package/src/lib/ui/Command.tsx

@@ -2,6 +2,7 @@ import { type DialogProps } from "@radix-ui/react-dialog";
 import { Command as CommandPrimitive } from "cmdk";
 import { Search } from "lucide-react";
 import * as React from "react";
+import { ComponentPropsWithoutRef } from "react";
 import { Dialog, DialogContent } from "zudoku/ui/Dialog.js";
 import { cn } from "../util/cn.js";
 
@@ -20,11 +21,32 @@ const Command = React.forwardRef<
 ));
 Command.displayName = CommandPrimitive.displayName;
 
-const CommandDialog = ({ children, ...props }: DialogProps) => {
+const CommandDialog = ({
+  children,
+  command,
+  content,
+  ...props
+}: DialogProps & {
+  command?: ComponentPropsWithoutRef<typeof CommandPrimitive>;
+  content?: ComponentPropsWithoutRef<typeof DialogContent>;
+}) => {
   return (
     <Dialog {...props}>
-      <DialogContent className="overflow-hidden p-0 shadow-lg">
-        <Command className="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
+      <DialogContent
+        {...content}
+        className={cn(
+          "overflow-hidden p-0 shadow-lg top-[15vh] translate-y-[0%]",
+          content?.className,
+        )}
+        aria-describedby={undefined}
+      >
+        <Command
+          {...command}
+          className={cn(
+            "[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5",
+            command?.className,
+          )}
+        >
           {children}
         </Command>
       </DialogContent>

package/src/lib/ui/Stepper.css

@@ -0,0 +1,43 @@
+@tailwind components;
+
+@layer components {
+  .stepper {
+    /* @apply mb-6; */
+  }
+
+  .stepper > ol {
+    --bullet-size: 1.75rem;
+    --line-spacing: 0.25rem;
+    @apply flex flex-col list-none p-0 m-0;
+    counter-reset: step-counter;
+  }
+
+  .stepper > ol > li {
+    @apply relative ps-12 pb-6 my-0;
+    counter-increment: step-counter;
+  }
+
+  .stepper > ol > li:last-child {
+    @apply pb-0;
+  }
+
+  /* Bullet with number */
+  .stepper > ol > li::before {
+    @apply absolute left-0 flex items-center justify-center size-[--bullet-size];
+    @apply bg-muted/80 border border-border text-muted-foreground text-[calc(var(--bullet-size)/2)] font-semibold rounded-full;
+    content: counter(step-counter);
+  }
+
+  /* Vertical line */
+  .stepper > ol > li::after {
+    @apply absolute content-[''] w-[2px] bg-border -translate-x-1/2;
+    left: calc(var(--bullet-size) / 2);
+    top: calc(var(--bullet-size) + var(--line-spacing));
+    height: calc(100% - var(--bullet-size) - (2 * var(--line-spacing)));
+  }
+
+  .stepper > ol > li > :first-child {
+    @apply mt-0 pt-0;
+    transform: translateY(calc((var(--bullet-size) - 1lh) / 2));
+  }
+}

package/src/lib/ui/Stepper.tsx

@@ -0,0 +1,8 @@
+import type { PropsWithChildren } from "react";
+import "./Stepper.css";
+
+const Stepper = ({ children }: PropsWithChildren) => {
+  return <div className="stepper">{children}</div>;
+};
+
+export { Stepper };

package/src/lib/util/MdxComponents.tsx

@@ -1,8 +1,9 @@
-import { MDXComponents } from "mdx/types.js";
+import { type MDXComponents } from "mdx/types.js";
 import { Link } from "react-router";
 import { Heading } from "../components/Heading.js";
 import { InlineCode } from "../components/InlineCode.js";
 import { Callout } from "../ui/Callout.js";
+import { Stepper } from "../ui/Stepper.js";
 import { SyntaxHighlight } from "../ui/SyntaxHighlight.js";
 
 export type MdxComponentsType = Readonly<MDXComponents> | null | undefined;
@@ -51,6 +52,8 @@ export const MdxComponents = {
       <a href={href} target="_blank" {...props} rel="noreferrer" />
     ),
   Callout,
+  Stepper,
+  SyntaxHighlight,
   tip: (props) => <Callout type="tip" {...props} />,
   info: (props) => <Callout type="info" {...props} />,
   note: (props) => <Callout type="note" {...props} />,

package/src/lib/util/useScrollToAnchor.ts

@@ -9,21 +9,21 @@ export const useScrollToHash = () => {
 
   const scrollToHash = useCallback(
     (hash: string) => {
-      const cleanHash = hash
-        .replace(/^#/, "")
-        // Operation list items might have subdivisions that the sidebar doesn't show.
-        // The subdivisions are separated by a slash so we need to remove everything before the slash to get the sidebar correct item.
-        .split("/")
-        .at(0)!;
+      const cleanHash = hash.replace(/^#/, "");
+
+      // Operation list items might have subdivisions that the sidebar doesn't show.
+      // The subdivisions are separated by a slash so we need to remove everything before the slash to get the sidebar correct item.
+      const linkHash = cleanHash.split("/").at(0)!;
       const element = document.getElementById(decodeURIComponent(cleanHash));
+
       const link = document.querySelector(
-        `[${DATA_ANCHOR_ATTR}="${cleanHash}"]`,
+        `[${DATA_ANCHOR_ATTR}="${linkHash}"]`,
       );
 
       if (element) {
         element.scrollIntoView();
         scrollIntoViewIfNeeded(link);
-        requestIdleCallback(() => setActiveAnchor(cleanHash));
+        requestIdleCallback(() => setActiveAnchor(linkHash));
         return true;
       }