zudoku 0.0.0-fd8f8ad → 0.0.0-feda542

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

@@ -1,22 +1,31 @@
-import type { InkeepWidgetBaseSettings } from "@inkeep/widgets";
-import { lazy } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { ClientOnly } from "../../components/ClientOnly.js";
 import type { ZudokuPlugin } from "../../core/plugins.js";
 import { aiChatSettings, baseSettings } from "./inkeep.js";
 
-type PickedPluginInkeepBaseSettings =
-  | "apiKey"
-  | "integrationId"
-  | "organizationId"
-  | "primaryBrandColor"
-  | "organizationDisplayName";
+interface PluginInkeepBaseSettings {
+  apiKey?: string;
+  integrationId: string;
+  organizationId: string;
+  organizationDisplayName?: string;
+  primaryBrandColor: string;
+}
 
-type PluginInkeepBaseSettings = Pick<
-  InkeepWidgetBaseSettings,
-  PickedPluginInkeepBaseSettings
->;
+interface InkeepEmbedConfig {
+  componentType: string;
+  targetElement: HTMLElement;
+  properties: unknown;
+}
 
-const Inkeep = lazy(() => import("./InkeepCustomTrigger.js"));
+interface InkeepWidget {
+  render: (config: InkeepEmbedConfig & { isOpen: boolean }) => void;
+}
+
+declare global {
+  let Inkeep: () => {
+    embed: (config: InkeepEmbedConfig) => InkeepWidget;
+  };
+}
 
 const InkeepSearch = ({
   prefilledQuery,
@@ -29,23 +38,69 @@ const InkeepSearch = ({
   prefilledQuery?: string | null;
   settings: PluginInkeepBaseSettings;
 }) => {
-  return (
-    <Inkeep
-      isOpen={isOpen}
-      onClose={onClose}
-      baseSettings={{ ...baseSettings, ...settings }}
-      aiChatSettings={aiChatSettings}
-      searchSettings={{
-        prefilledQuery: prefilledQuery || undefined,
-      }}
-    />
+  const ref = useRef<HTMLDivElement>(null);
+  const widgetRef = useRef<InkeepWidget | null>(null);
+  const [isInkeepAvailable, setIsInkeepAvailable] = useState(
+    typeof Inkeep !== "undefined",
+  );
+
+  const config: InkeepEmbedConfig = useMemo(
+    () => ({
+      componentType: "CustomTrigger",
+      targetElement: ref.current!,
+      properties: {
+        isOpen,
+        onClose,
+        onOpen: undefined,
+        baseSettings: { ...baseSettings, ...settings },
+        searchSettings: {
+          prefilledQuery: prefilledQuery || undefined,
+        },
+        aiChatSettings,
+      },
+    }),
+    [isOpen, onClose, prefilledQuery, settings, ref],
   );
+
+  useEffect(() => {
+    if (isInkeepAvailable) return;
+
+    const checkInkeep = setInterval(() => {
+      if (typeof Inkeep !== "undefined") {
+        setIsInkeepAvailable(true);
+        clearInterval(checkInkeep);
+      }
+    }, 100);
+
+    return () => clearInterval(checkInkeep);
+  }, [isInkeepAvailable]);
+
+  useEffect(() => {
+    if (!isInkeepAvailable || widgetRef.current) return;
+
+    widgetRef.current = Inkeep().embed(config);
+  }, [config, isInkeepAvailable]);
+
+  useEffect(() => {
+    widgetRef.current?.render({ ...config, isOpen });
+  }, [config, isOpen]);
+
+  return <div ref={ref} />;
 };
 
 export const inkeepSearchPlugin = (
   settings: PluginInkeepBaseSettings,
 ): ZudokuPlugin => {
   return {
+    getHead: () => {
+      return (
+        <script
+          type="module"
+          src="https://unpkg.com/@inkeep/uikit-js@0.3.19/dist/embed.js"
+          defer
+        />
+      );
+    },
     renderSearch: ({
       isOpen,
       onClose,

package/src/lib/plugins/search-inkeep/inkeep.ts

@@ -1,9 +1,3 @@
-import {
-  InkeepAIChatSettings,
-  InkeepModalSettings,
-  InkeepSearchSettings,
-} from "@inkeep/widgets";
-
 const baseSettings = {
   theme: {
     components: {
@@ -23,10 +17,10 @@ const baseSettings = {
   },
 } as const;
 
-const modalSettings: InkeepModalSettings = {};
+const modalSettings = {};
 
-const searchSettings: InkeepSearchSettings = {};
+const searchSettings = {};
 
-const aiChatSettings: InkeepAIChatSettings = {};
+const aiChatSettings = {};
 
 export { aiChatSettings, baseSettings, modalSettings, searchSettings };

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

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

@@ -0,0 +1,105 @@
+import { BracketsIcon, FileTextIcon } from "lucide-react";
+import { 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 = ({
+  searchResults,
+  searchTerm,
+  onClose,
+  maxSubResults = 4,
+}: {
+  basePath?: string;
+  searchResults: PagefindSearchFragment[];
+  searchTerm: string;
+  onClose: () => void;
+  maxSubResults?: number;
+}) => {
+  const navigate = useNavigate();
+  const commandListRef = useRef<HTMLDivElement | null>(null);
+
+  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(result.url);
+                onClose();
+              }}
+            >
+              <Link to={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(subResult.url);
+                    onClose();
+                  }}
+                >
+                  <Link to={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;
+      }
+    }
+  }
+}

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

@@ -4,7 +4,7 @@ import * as React from "react";
 import { cn } from "../util/cn.js";
 
 const badgeVariants = cva(
-  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
+  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-medium transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
   {
     variants: {
       variant: {
@@ -12,6 +12,7 @@ const badgeVariants = cva(
           "border-transparent bg-primary text-primary-foreground hover:bg-primary/80",
         secondary:
           "border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        muted: "bg-muted text-muted-foreground ",
         destructive:
           "border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80",
         outline: "text-foreground",

package/src/lib/ui/Button.tsx

@@ -1,10 +1,10 @@
 import { Slot } from "@radix-ui/react-slot";
-import { cva, VariantProps } from "class-variance-authority";
+import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
 import { cn } from "../util/cn.js";
 
 export const buttonVariants = cva(
-  "not-prose inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+  "not-prose inline-flex shrink-0 items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
   {
     variants: {
       variant: {
@@ -18,6 +18,8 @@ export const buttonVariants = cva(
           "bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80",
         ghost: "hover:bg-accent hover:text-accent-foreground",
         link: "text-primary underline-offset-4 hover:underline",
+        expand:
+          "flex gap-1.5 border bg-transparent rounded-xl text-muted-foreground hover:text-foreground",
       },
       size: {
         default: "h-9 px-4 py-2",