zudoku 0.0.0-f2fd45c → 0.0.0-f36627bd

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

@@ -0,0 +1,198 @@
+import { useSuspenseQuery } from "@tanstack/react-query";
+import {
+  generatePath,
+  Navigate,
+  type RouteObject,
+  redirect,
+  useLocation,
+  useParams,
+} from "react-router";
+import { joinUrl } from "../../../util/joinUrl.js";
+import type { GraphQLClient } from "../client/GraphQLClient.js";
+import { useCreateQuery } from "../client/useCreateQuery.js";
+import { useOasConfig } from "../context.js";
+import {
+  GetNavigationOperationsQuery,
+  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} /> };
+  },
+});
+
+const NonTagPagesOperationList = ({
+  render,
+  path,
+}: {
+  render: (tag: string) => React.ReactNode;
+  path: string;
+}) => {
+  const { type, input } = useOasConfig();
+  const { tag: currentTag } = useParams();
+  const location = useLocation();
+  const query = useCreateQuery(GetNavigationOperationsQuery, { type, input });
+  const {
+    data: { schema },
+  } = useSuspenseQuery(query);
+
+  const firstTag = schema.tags.at(0);
+
+  if (!currentTag && firstTag?.slug) {
+    return (
+      <Navigate
+        to={{
+          pathname: generatePath(path, { tag: firstTag.slug }),
+          search: location.search,
+        }}
+      />
+    );
+  }
+
+  if (currentTag && schema.tags.some((t) => t.slug === currentTag)) {
+    return render(currentTag);
+  }
+
+  return null;
+};
+
+const createNonTagPagesRoute = ({ path }: { path: string }): RouteObject => ({
+  path,
+  async lazy() {
+    const { OperationList } = await import("../OperationList.js");
+    return {
+      element: (
+        <NonTagPagesOperationList
+          path={path}
+          render={(tag) => <OperationList tag={tag} />}
+        />
+      ),
+    };
+  },
+});
+
+const createAdditionalRoutes = (basePath: string) => [
+  // Category without tagged operations
+  createRoute({
+    path: joinUrl(basePath, UNTAGGED_PATH),
+    untagged: true,
+  }),
+  // Schema list route
+  {
+    path: joinUrl(basePath, "~schemas"),
+    lazy: async () => {
+      const { SchemaList } = await import("../SchemaList.js");
+      return { element: <SchemaList /> };
+    },
+  },
+];
+
+// 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,
+      }),
+    ),
+    ...createAdditionalRoutes(versionPath),
+  ];
+};
+
+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: [
+          createNonTagPagesRoute({ path: `${basePath}/:tag?` }),
+          ...createAdditionalRoutes(basePath),
+        ],
+        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 type { ColorMap } from "../../../components/navigation/NavigationBadge.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/openapi/util/methodToColor.ts

@@ -0,0 +1,27 @@
+export const TextColorMap = {
+  green: "text-green-600",
+  blue: "text-sky-600",
+  yellow: "text-yellow-600",
+  red: "text-red-600",
+  purple: "text-purple-600",
+  indigo: "text-indigo-600",
+  gray: "text-gray-600",
+};
+
+export const methodToColor = {
+  get: TextColorMap.green,
+  post: TextColorMap.blue,
+  put: TextColorMap.yellow,
+  delete: TextColorMap.red,
+  patch: TextColorMap.purple,
+  options: TextColorMap.indigo,
+  head: TextColorMap.gray,
+  trace: TextColorMap.gray,
+};
+
+export const methodForColor = (method: string) => {
+  return (
+    methodToColor[method.toLocaleLowerCase() as keyof typeof methodToColor] ??
+    TextColorMap.gray
+  );
+};

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

@@ -0,0 +1,32 @@
+export function sanitizeMarkdownForMetatag(
+  description: string,
+  maxLength: number = 160,
+): string {
+  if (!description) {
+    return "";
+  }
+
+  return (
+    description
+      // Replace Markdown links [text](url) with just "text"
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+      // Remove Markdown image syntax: ![alt](url)
+      .replace(/!\[.*?\]\(.*?\)/g, "")
+      // Remove other Markdown syntax (e.g., **bold**, _italic_, `code`)
+      .replace(/[_*`~]/g, "")
+      // Remove headings (# Heading), blockquotes (> Quote), and horizontal rules (--- or ***)
+      .replace(/^(?:>|\s*#+|-{3,}|\*{3,})/gm, "")
+      // Remove any remaining formatting characters
+      .replace(/[|>{}[\]]/g, "")
+      // Collapse multiple spaces and trim the text
+      .replace(/\s+/g, " ")
+      .trim()
+      // Limit to the specified maximum length
+      .substring(0, maxLength)
+      .replace(/&/g, "&")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#039;")
+  );
+}

package/src/lib/plugins/redirect/index.tsx

@@ -1,10 +1,10 @@
-import { redirect } from "react-router-dom";
-import { ZudokuRedirect } from "../../../config/validators/validate.js";
-import type { DevPortalPlugin } from "../../core/plugins.js";
+import { redirect } from "react-router";
+import type { ZudokuRedirect } from "../../../config/validators/validate.js";
+import type { ZudokuPlugin } from "../../core/plugins.js";
 
 export const redirectPlugin = (options: {
   redirects: ZudokuRedirect[];
-}): DevPortalPlugin => {
+}): ZudokuPlugin => {
   return {
     getRoutes: () =>
       options.redirects.map(({ from, to }) => ({

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

@@ -1,51 +1,102 @@
-import type { InkeepWidgetBaseSettings } from "@inkeep/widgets";
-import { lazy } from "react";
+import type {
+  InkeepBaseSettings,
+  InkeepComponentInstance,
+  InkeepJS,
+  InkeepSettings,
+} from "@inkeep/cxkit-types";
+import { useEffect, useMemo, useState } from "react";
 import { ClientOnly } from "../../components/ClientOnly.js";
-import type { DevPortalPlugin } from "../../core/plugins.js";
-import { aiChatSettings, baseSettings } from "./inkeep.js";
+import type { ZudokuPlugin } from "../../core/plugins.js";
+import {
+  aiChatSettings,
+  baseSettings,
+  modalSettings,
+  searchSettings,
+} from "./inkeep.js";
 
-type PickedPluginInkeepBaseSettings =
-  | "apiKey"
-  | "integrationId"
-  | "organizationId"
-  | "primaryBrandColor"
-  | "organizationDisplayName";
-
-type PluginInkeepBaseSettings = Pick<
-  InkeepWidgetBaseSettings,
-  PickedPluginInkeepBaseSettings
->;
-
-const Inkeep = lazy(() => import("./InkeepCustomTrigger.js"));
+declare global {
+  interface Window {
+    Inkeep: InkeepJS | undefined;
+  }
+}
 
 const InkeepSearch = ({
-  prefilledQuery,
   isOpen,
   onClose,
   settings,
 }: {
   isOpen: boolean;
   onClose: () => void;
-  prefilledQuery?: string | null;
-  settings: PluginInkeepBaseSettings;
+  settings: InkeepBaseSettings;
 }) => {
-  return (
-    <Inkeep
-      isOpen={isOpen}
-      onClose={onClose}
-      baseSettings={{ ...baseSettings, ...settings }}
-      aiChatSettings={aiChatSettings}
-      searchSettings={{
-        prefilledQuery: prefilledQuery || undefined,
-      }}
-    />
+  const config = useMemo<InkeepSettings>(
+    () => ({
+      baseSettings: {
+        ...baseSettings,
+        ...settings,
+        colorMode: {
+          sync: {
+            target: "html",
+            attributes: ["class"],
+            isDarkMode: (attrs) => attrs.class?.includes("dark") ?? false,
+          },
+        },
+      },
+      modalSettings: {
+        ...modalSettings,
+        onOpenChange: (newOpen: boolean) => {
+          if (!newOpen) onClose();
+        },
+      },
+      searchSettings,
+      aiChatSettings,
+    }),
+    [onClose, settings],
+  );
+  const [searchInstance, setSearchInstance] = useState<
+    InkeepComponentInstance | undefined
+  >(
+    typeof window !== "undefined" && window.Inkeep?.ModalSearchAndChat
+      ? window.Inkeep.ModalSearchAndChat(config)
+      : undefined,
   );
+
+  useEffect(() => {
+    if (searchInstance) return;
+
+    const checkInkeep = setInterval(() => {
+      if (typeof window !== "undefined" && window.Inkeep?.ModalSearchAndChat) {
+        const inkeep = window.Inkeep.ModalSearchAndChat(config);
+        setSearchInstance(inkeep);
+        clearInterval(checkInkeep);
+      }
+    }, 100);
+
+    return () => clearInterval(checkInkeep);
+  }, [config, searchInstance]);
+
+  useEffect(() => {
+    if (!searchInstance) return;
+
+    searchInstance.update({ modalSettings: { isOpen } });
+  }, [isOpen, searchInstance]);
+
+  return null;
 };
 
 export const inkeepSearchPlugin = (
-  settings: PluginInkeepBaseSettings,
-): DevPortalPlugin => {
+  settings: InkeepBaseSettings,
+): ZudokuPlugin => {
   return {
+    getHead: () => {
+      return (
+        <script
+          type="module"
+          src="https://cdn.jsdelivr.net/npm/@inkeep/cxkit-js@0.5.90/+esm"
+          defer
+        />
+      );
+    },
     renderSearch: ({
       isOpen,
       onClose,

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

@@ -1,32 +1,24 @@
-import {
+import type {
   InkeepAIChatSettings,
+  InkeepBaseSettings,
   InkeepModalSettings,
   InkeepSearchSettings,
-} from "@inkeep/widgets";
+} from "@inkeep/cxkit-types";
 
-const baseSettings = {
-  theme: {
-    components: {
-      AIChatPageWrapper: {
-        defaultProps: {
-          size: "shrink-vertically",
-          variant: "no-shadow",
-        },
-      },
-      SearchBarTrigger: {
-        defaultProps: {
-          size: "expand",
-          variant: "subtle", // Choose from 'emphasized' or 'subtle'
-        },
-      },
-    },
-  },
-} as const;
+const baseSettings: InkeepBaseSettings = {
+  primaryBrandColor: "#26D6FF",
+};
 
-const modalSettings: InkeepModalSettings = {};
+const modalSettings: InkeepModalSettings = {
+  shortcutKey: "k",
+};
 
-const searchSettings: InkeepSearchSettings = {};
+const searchSettings: InkeepSearchSettings = {
+  placeholder: "Search...",
+};
 
-const aiChatSettings: InkeepAIChatSettings = {};
+const aiChatSettings: InkeepAIChatSettings = {
+  aiAssistantName: "Assistant",
+};
 
 export { aiChatSettings, baseSettings, modalSettings, searchSettings };

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

@@ -0,0 +1,163 @@
+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") {
+    // biome-ignore lint/suspicious/noConsole: Logging allowed here
+    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
+          basePath={context.options.basePath}
+          searchResults={searchResults ?? []}
+          searchTerm={searchTerm}
+          onClose={onClose}
+          maxSubResults={options.maxSubResults}
+        />
+      )}
+    </CommandDialog>
+  );
+};