zudoku 0.0.0-f9d5b02 → 0.0.0-fabd0c1

package/src/lib/plugins/openapi/post-processors/removeExtensions.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import { removeExtensions } from "./removeExtensions.js";
+
+const baseDoc = {
+  openapi: "3.1.0",
+  "x-root-ext": "remove me",
+  info: {
+    title: "Test API",
+    version: "1.0.0",
+    "x-info-ext": "remove me",
+  },
+  paths: {
+    "/test": {
+      "x-path-ext": "remove me",
+      parameters: [
+        {
+          name: "param1",
+          in: "query",
+          schema: { type: "string" },
+          "x-param-ext": "remove me",
+        },
+      ],
+      get: {
+        "x-operation-ext": "remove me",
+        responses: {
+          "200": {
+            description: "OK",
+            "x-response-ext": "remove me",
+          },
+        },
+        parameters: [
+          {
+            name: "opParam1",
+            in: "header",
+            schema: { type: "string" },
+            "x-op-param-ext": "remove me",
+          },
+        ],
+      },
+    },
+  },
+  tags: [
+    {
+      name: "example",
+      "x-tag-ext": "remove me",
+    },
+  ],
+  components: {
+    securitySchemes: {
+      ApiKeyAuth: {
+        type: "apiKey",
+        name: "api_key",
+        in: "header",
+        "x-security-ext": "remove me",
+      },
+    },
+  },
+};
+
+describe("removeExtensions", () => {
+  it("removes all x- extensions by default", () => {
+    const processed = removeExtensions()(baseDoc);
+
+    const removedExtensions = [
+      "x-root-ext",
+      "info.x-info-ext",
+      "paths./test.x-path-ext",
+      "paths./test.parameters[0].x-param-ext",
+      "paths./test.get.x-operation-ext",
+      "paths./test.get.responses.200.x-response-ext",
+      "paths./test.get.parameters[0].x-op-param-ext",
+      "tags[0].x-tag-ext",
+      "components.securitySchemes.ApiKeyAuth.x-security-ext",
+    ];
+
+    removedExtensions.forEach((ext) => {
+      expect(processed).not.toHaveProperty(ext.split("."));
+    });
+
+    // Assert that non-x- fields remain unchanged
+    expect(processed.openapi).toBe("3.1.0");
+    expect(processed.info.title).toBe("Test API");
+    expect(processed).toHaveProperty(
+      ["paths", "/test", "get", "responses", "200", "description"],
+      "OK",
+    );
+    expect(processed.tags[0].name).toBe("example");
+  });
+
+  it("removes only specified x- extensions when names are provided", () => {
+    const docWithExtraExtensions = {
+      ...baseDoc,
+      info: { ...baseDoc.info, "x-other-ext": "keep me" },
+    };
+
+    const processed = removeExtensions({
+      keys: ["x-path-ext", "x-param-ext"],
+    })(docWithExtraExtensions);
+
+    // Assert specified extensions are removed
+    expect(processed.paths["/test"]["x-path-ext"]).toBeUndefined();
+    expect(
+      processed.paths["/test"].parameters[0]["x-param-ext"],
+    ).toBeUndefined();
+
+    // Assert other x- fields remain
+    expect(processed["x-root-ext"]).toBe("remove me");
+    expect(processed.info["x-info-ext"]).toBe("remove me");
+    expect(processed.info["x-other-ext"]).toBe("keep me");
+  });
+
+  it("handles deeply nested extensions", () => {
+    const deeplyNested = {
+      a: {
+        b: {
+          c: {
+            "x-deep-ext": "remove me",
+            d: {
+              e: "value",
+              "x-another-ext": "remove me",
+            },
+          },
+        },
+      },
+    };
+
+    const processed = removeExtensions()(deeplyNested);
+
+    expect(processed.a.b.c["x-deep-ext"]).toBeUndefined();
+    expect(processed.a.b.c.d["x-another-ext"]).toBeUndefined();
+    expect(processed.a.b.c.d.e).toBe("value");
+  });
+
+  it("does nothing if no x- extensions are present", () => {
+    const docWithoutExtensions = {
+      openapi: "3.1.0",
+      info: { title: "API without extensions" },
+    };
+
+    const processed = removeExtensions()(docWithoutExtensions);
+
+    expect(processed).toEqual(docWithoutExtensions);
+  });
+});

package/src/lib/plugins/openapi/post-processors/removeExtensions.ts

@@ -0,0 +1,24 @@
+import { type RecordAny, traverse } from "./traverse.js";
+
+interface RemoveExtensionsOptions {
+  keys?: string[];
+}
+
+// Remove all `x-` prefixed key/value pairs, or filter by names if provided
+export const removeExtensions =
+  ({ keys }: RemoveExtensionsOptions = {}) =>
+  (doc: RecordAny): RecordAny =>
+    traverse(doc, (spec) => {
+      const result: RecordAny = {};
+
+      for (const [key, value] of Object.entries(spec)) {
+        const isExtension = key.startsWith("x-");
+        const shouldRemove =
+          isExtension && (keys === undefined || keys.includes(key));
+
+        if (shouldRemove) continue;
+
+        result[key] = value;
+      }
+      return result;
+    });

package/src/lib/plugins/openapi/post-processors/removePaths.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+import { removePaths } from "./removePaths.js";
+
+const baseDoc = {
+  openapi: "3.0.3",
+  paths: {
+    "/example": {
+      get: { summary: "Get example" },
+      post: { summary: "Post example" },
+    },
+    "/remove-me": {
+      delete: { summary: "Delete example" },
+    },
+    "/another": {
+      get: { summary: "Another example" },
+    },
+  },
+};
+
+describe("removePaths", () => {
+  it("removes paths specified in the paths option", () => {
+    const processed = removePaths({
+      paths: {
+        "/remove-me": true,
+      },
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeUndefined();
+    expect(processed.paths["/example"]).toBeDefined();
+    expect(processed.paths["/another"]).toBeDefined();
+  });
+
+  it("removes specific methods in the paths option", () => {
+    const processed = removePaths({
+      paths: {
+        "/example": ["get"],
+      },
+    })(baseDoc);
+
+    expect(processed.paths["/example"].get).toBeUndefined();
+    expect(processed.paths["/example"].post).toBeDefined();
+    expect(processed.paths["/remove-me"]).toBeDefined();
+  });
+
+  it("removes paths and methods using paths and shouldRemove together", () => {
+    const processed = removePaths({
+      paths: {
+        "/example": ["post"],
+      },
+      shouldRemove: ({ path }) => path.startsWith("/remove"),
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeUndefined();
+    expect(processed.paths["/example"].get).toBeDefined();
+    expect(processed.paths["/example"].post).toBeUndefined();
+    expect(processed.paths["/another"]).toBeDefined();
+  });
+
+  it("removes paths based on shouldRemove callback", () => {
+    const processed = removePaths({
+      shouldRemove: ({ path }) => path.startsWith("/remove"),
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeUndefined();
+    expect(processed.paths["/example"]).toBeDefined();
+    expect(processed.paths["/another"]).toBeDefined();
+  });
+
+  it("removes methods based on shouldRemove callback", () => {
+    const processed = removePaths({
+      shouldRemove: ({ method }) => method === "post",
+    })(baseDoc);
+
+    expect(processed.paths["/example"].post).toBeUndefined();
+    expect(processed.paths["/example"].get).toBeDefined();
+    expect(processed.paths["/remove-me"]).toBeDefined();
+  });
+
+  it("removes both paths and methods based on shouldRemove callback", () => {
+    const processed = removePaths({
+      shouldRemove: ({ path, method }) =>
+        path.startsWith("/remove") || method === "post",
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeUndefined();
+    expect(processed.paths["/example"].post).toBeUndefined();
+    expect(processed.paths["/example"].get).toBeDefined();
+    expect(processed.paths["/another"]).toBeDefined();
+  });
+
+  it("does nothing if shouldRemove always returns false", () => {
+    const processed = removePaths({
+      shouldRemove: () => false,
+    })(baseDoc);
+
+    expect(processed).toEqual(baseDoc);
+  });
+
+  it("removes everything if shouldRemove always returns true", () => {
+    const processed = removePaths({
+      shouldRemove: () => true,
+    })(baseDoc);
+
+    expect(processed.paths).toEqual({});
+  });
+
+  it("removes entire paths via shouldRemove callback", () => {
+    const processed = removePaths({
+      shouldRemove: ({ path, method }) =>
+        method === true && path === "/remove-me",
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeUndefined();
+    expect(processed.paths["/example"]).toBeDefined();
+    expect(processed.paths["/another"]).toBeDefined();
+  });
+
+  it("removes specific methods while keeping paths", () => {
+    const processed = removePaths({
+      shouldRemove: ({ method }) => method === "delete",
+    })(baseDoc);
+
+    expect(processed.paths["/remove-me"]).toBeDefined();
+    expect(processed.paths["/remove-me"].delete).toBeUndefined();
+  });
+});

package/src/lib/plugins/openapi/post-processors/removePaths.ts

@@ -0,0 +1,55 @@
+import { type RecordAny, traverse } from "./traverse.js";
+
+interface RemovePathsOptions {
+  // Path definitions, e.g., { '/path': true, '/path-2': ['get'] }
+  paths?: Record<string, true | string[]>;
+  shouldRemove?: (options: {
+    path: string;
+    method: true | string;
+    operation: RecordAny;
+  }) => boolean;
+}
+
+export const removePaths =
+  ({ paths = {}, shouldRemove }: RemovePathsOptions) =>
+  (doc: RecordAny): RecordAny =>
+    traverse(doc, (spec) => {
+      if (!spec.paths) return spec;
+
+      const updatedPaths: RecordAny = {};
+
+      for (const [path, methods] of Object.entries(spec.paths)) {
+        const operations = spec.paths[path];
+
+        // If the path is explicitly marked for removal in `paths`
+        if (paths[path] === true) continue;
+
+        // If the path should be removed via `shouldRemove`
+        if (shouldRemove?.({ path, method: true, operation: operations }))
+          continue;
+
+        if (typeof methods === "object" && methods !== null) {
+          const filteredPath = Object.fromEntries(
+            Object.entries(methods).filter(([method]) => {
+              const operations = spec.paths[path][method];
+              const isMethodToRemove =
+                Array.isArray(paths[path]) && paths[path].includes(method);
+
+              const isMethodFiltered = shouldRemove?.({
+                path,
+                method,
+                operation: operations,
+              });
+
+              return !isMethodToRemove && !isMethodFiltered;
+            }),
+          );
+
+          updatedPaths[path] = filteredPath;
+        } else {
+          updatedPaths[path] = methods;
+        }
+      }
+
+      return { ...spec, paths: updatedPaths };
+    });

package/src/lib/plugins/openapi/post-processors/traverse.ts

@@ -0,0 +1 @@
+export { traverse, type RecordAny } from "../../../util/traverse.js";

package/src/lib/plugins/openapi/schema/SchemaView.tsx

@@ -73,7 +73,7 @@ export const SchemaView = ({
     ) {
       return (
         <Card className="p-4 flex gap-2 items-center">
-          {"name" in schema && <>{schema.name}</>}
+          {"name" in schema && <>{schema.name as string}</>}
           <span className="text-sm text-muted-foreground">object</span>
           {schema.description && (
             <Markdown

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,5 +1,5 @@
-import { redirect } from "react-router-dom";
-import { ZudokuRedirect } from "../../../config/validators/validate.js";
+import { redirect } from "react-router";
+import { ZudokuRedirect } from "../../../config/validators/common.js";
 import type { ZudokuPlugin } from "../../core/plugins.js";
 
 export const redirectPlugin = (options: {

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/util/MdxComponents.tsx

@@ -1,17 +1,13 @@
-import { MDXProvider } from "@mdx-js/react";
-import type { ComponentProps } from "react";
-import { Link } from "react-router-dom";
+import { MDXComponents } from "mdx/types.js";
+import { Link } from "react-router";
 import { Heading } from "../components/Heading.js";
 import { InlineCode } from "../components/InlineCode.js";
 import { SyntaxHighlight } from "../components/SyntaxHighlight.js";
 import { Callout } from "../ui/Callout.js";
 
-export type MdxComponentsType = ComponentProps<
-  typeof MDXProvider
->["components"];
+export type MdxComponentsType = Readonly<MDXComponents> | null | undefined;
 
 export const MdxComponents = {
-  // @ts-expect-error Node is not in types but still gets passed
   img: ({ node, ...props }) => {
     if (/\.(mp4|webm|mov|avi)$/.test(props.src ?? "")) {
       return <video src={props.src} controls playsInline autoPlay loop />;
@@ -48,7 +44,6 @@ export const MdxComponents = {
       {children}
     </Heading>
   ),
-  // @ts-expect-error Node is not in types but still gets passed
   a: ({ href, node, ...props }) =>
     href && !href.startsWith("http") ? (
       <Link to={href} relative="path" {...props} />

package/src/lib/util/createVariantComponent.tsx

@@ -2,11 +2,11 @@ import { Slot } from "@radix-ui/react-slot";
 import { cva } from "class-variance-authority";
 import type { ClassValue } from "clsx";
 import * as React from "react";
-import type { JSX } from "react/jsx-runtime";
+import { type HTMLElementType, type JSX } from "react";
 import { cn } from "./cn.js";
 
 const createVariantComponent = <
-  E extends keyof React.ReactHTML,
+  E extends HTMLElementType,
   C extends ReturnType<typeof cva>,
 >(
   tag: E,

package/src/lib/util/traverse.ts

@@ -0,0 +1,25 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type RecordAny = Record<string, any>;
+
+export const traverse = (
+  specification: RecordAny,
+  transform: (specification: RecordAny) => RecordAny,
+) => {
+  const result: RecordAny = {};
+
+  for (const [key, value] of Object.entries(specification)) {
+    if (Array.isArray(value)) {
+      result[key] = value.map((item) =>
+        typeof item === "object" && item !== null
+          ? traverse(item, transform)
+          : item,
+      );
+    } else if (typeof value === "object" && value !== null) {
+      result[key] = traverse(value, transform);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return transform(result);
+};

package/src/lib/util/useExposedProps.tsx

@@ -3,7 +3,7 @@ import {
   useNavigate,
   useParams,
   useSearchParams,
-} from "react-router-dom";
+} from "react-router";
 import type { ExposedComponentProps } from "../components/SlotletProvider.js";
 
 export const useExposedProps = (): ExposedComponentProps => {

package/src/lib/util/useScrollToAnchor.ts

@@ -1,5 +1,5 @@
 import { useEffect } from "react";
-import { useLocation } from "react-router-dom";
+import { useLocation } from "react-router";
 import { useViewportAnchor } from "../components/context/ViewportAnchorContext.js";
 import { DATA_ANCHOR_ATTR } from "../components/navigation/SidebarItem.js";
 

package/src/lib/util/useScrollToTop.ts

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from "react";
-import { useLocation } from "react-router-dom";
+import { useLocation } from "react-router";
 
 export const useScrollToTop = () => {
   const location = useLocation();

package/dist/lib/plugins/search-inkeep/InkeepCustomTrigger.d.ts

@@ -1,2 +0,0 @@
-import { InkeepCustomTrigger } from "@inkeep/widgets";
-export default InkeepCustomTrigger;