zudoku 0.0.0-fd8f8ad → 0.0.0-feda542

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

@@ -3,166 +3,115 @@ import type { SchemaObject } from "../../../oas/parser/index.js";
 import { Card, CardContent, CardHeader, CardTitle } from "../../../ui/Card.js";
 import { cn } from "../../../util/cn.js";
 import { groupBy } from "../../../util/groupBy.js";
-import { SchemaLogicalGroup, SchemaPropertyItem } from "./SchemaComponents.js";
-import { hasLogicalGroupings } from "./utils.js";
+import { EnumValues } from "../components/EnumValues.js";
+import { ParamInfos } from "../ParamInfos.js";
+import { SchemaExampleAndDefault } from "./SchemaExampleAndDefault.js";
+import {
+  SchemaLogicalGroup,
+  SchemaPropertyItem,
+} from "./SchemaPropertyItem.js";
+import { hasLogicalGroupings, isBasicType } from "./utils.js";
+
+const renderMarkdown = (content?: string) =>
+  content && (
+    <Markdown
+      className={cn(ProseClasses, "text-sm leading-normal line-clamp-4")}
+      content={content}
+    />
+  );
+
+const renderBasicSchema = (schema: SchemaObject) => (
+  <Card className="p-4 space-y-2">
+    <span className="text-sm text-muted-foreground">
+      <ParamInfos schema={schema} />
+    </span>
+    {schema.enum && <EnumValues values={schema.enum} />}
+    {renderMarkdown(schema.description)}
+    <SchemaExampleAndDefault schema={schema} />
+  </Card>
+);
 
 export const SchemaView = ({
   schema,
-  level = 0,
   defaultOpen = false,
 }: {
   schema?: SchemaObject | null;
-  level?: number;
   defaultOpen?: boolean;
 }) => {
   if (!schema || Object.keys(schema).length === 0) {
     return (
       <Card className="p-4">
         <span className="text-sm text-muted-foreground italic">
-          No response specified
+          No schema specified
         </span>
       </Card>
     );
   }
 
-  const renderSchema = (schema: SchemaObject, level: number) => {
-    if (hasLogicalGroupings(schema)) {
-      return <SchemaLogicalGroup schema={schema} level={level} />;
-    }
-
-    // Sometimes items is not defined
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (schema.type === "array" && schema.items) {
-      const itemsSchema = schema.items as SchemaObject;
-
-      if (
-        typeof itemsSchema.type === "string" &&
-        ["string", "number", "boolean", "integer"].includes(itemsSchema.type)
-      ) {
-        return (
-          <Card className="p-4">
-            <span className="text-sm text-muted-foreground">
-              {itemsSchema.type}[]
-            </span>
-            {schema.description && (
-              <Markdown
-                className={cn(
-                  ProseClasses,
-                  "text-sm leading-normal line-clamp-4",
-                )}
-                content={schema.description}
-              />
-            )}
-          </Card>
-        );
-      } else if (itemsSchema.type === "object") {
-        return (
-          <Card className="flex flex-col gap-2 bg-border/30 p-4">
-            <span className="text-sm text-muted-foreground">object[]</span>
-            {renderSchema(itemsSchema, level + 1)}
-          </Card>
-        );
-      } else {
-        return renderSchema(itemsSchema, level + 1);
-      }
-    }
-
-    if (
-      schema.type === "object" &&
-      (!schema.properties || Object.keys(schema.properties).length === 0)
-    ) {
-      return (
-        <Card className="p-4 flex gap-2 items-center">
-          {"name" in schema && <>{schema.name}</>}
-          <span className="text-sm text-muted-foreground">object</span>
-          {schema.description && (
-            <Markdown
-              className={cn(
-                ProseClasses,
-                "text-sm leading-normal line-clamp-4",
-              )}
-              content={schema.description}
-            />
-          )}
-        </Card>
-      );
-    }
-
-    if (schema.properties) {
-      const groupedProperties = groupBy(
-        Object.entries(schema.properties),
-        ([propertyName, property]) => {
-          return property.deprecated
-            ? "deprecated"
-            : schema.required?.includes(propertyName)
-              ? "required"
-              : "optional";
-        },
-      );
+  if (hasLogicalGroupings(schema)) {
+    return <SchemaLogicalGroup schema={schema} />;
+  }
 
-      const groupNames = ["required", "optional", "deprecated"] as const;
+  if (isBasicType(schema.type)) {
+    return renderBasicSchema(schema);
+  }
 
-      return (
-        <Card className="divide-y overflow-hidden">
-          {groupNames.map(
-            (group) =>
-              groupedProperties[group] && (
-                <ul key={group} className="divide-y">
-                  {groupedProperties[group].map(([name, schema]) => (
-                    <SchemaPropertyItem
-                      key={name}
-                      name={name}
-                      schema={schema}
-                      group={group}
-                      level={level}
-                      defaultOpen={defaultOpen}
-                    />
-                  ))}
-                </ul>
-              ),
-          )}
-        </Card>
-      );
-    }
+  if (schema.type === "array" && typeof schema.items === "object") {
+    return (
+      <Card className="p-4 space-y-2 text-sm">
+        <ParamInfos schema={schema} />
+        <SchemaView schema={schema.items as SchemaObject} />
+      </Card>
+    );
+  }
 
-    if (
-      typeof schema.type === "string" &&
-      ["string", "number", "boolean", "integer", "null"].includes(schema.type)
-    ) {
-      return (
-        <Card className="p-4">
-          <span className="text-sm text-muted-foreground">{schema.type}</span>
-          {schema.description && (
-            <Markdown
-              className={cn(
-                ProseClasses,
-                "text-sm leading-normal line-clamp-4",
-              )}
-              content={schema.description}
-            />
-          )}
-        </Card>
-      );
-    }
+  if (schema.type === "object") {
+    const groupedProperties = groupBy(
+      Object.entries(schema.properties ?? {}),
+      ([propertyName, property]) => {
+        return property.deprecated
+          ? "deprecated"
+          : schema.required?.includes(propertyName)
+            ? "required"
+            : "optional";
+      },
+    );
+    const groupNames = ["required", "optional", "deprecated"] as const;
 
-    if (schema.additionalProperties) {
-      return (
-        <Card className="my-2">
-          <CardHeader>
-            <CardTitle>Additional Properties:</CardTitle>
-          </CardHeader>
-          <CardContent>
-            {renderSchema(
-              schema.additionalProperties as SchemaObject,
-              level + 1,
-            )}
-          </CardContent>
-        </Card>
-      );
-    }
+    return (
+      <Card className="divide-y overflow-hidden">
+        {groupNames.map(
+          (group) =>
+            groupedProperties[group] && (
+              <ul key={group} className="divide-y">
+                {groupedProperties[group].map(([name, schema]) => (
+                  <SchemaPropertyItem
+                    key={name}
+                    name={name}
+                    schema={schema}
+                    group={group}
+                    defaultOpen={defaultOpen}
+                  />
+                ))}
+              </ul>
+            ),
+        )}
+      </Card>
+    );
+  }
 
-    return null;
-  };
+  if (schema.additionalProperties) {
+    return (
+      <Card className="my-2">
+        <CardHeader>
+          <CardTitle>Additional Properties:</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <SchemaView schema={schema.additionalProperties as SchemaObject} />
+        </CardContent>
+      </Card>
+    );
+  }
 
-  return renderSchema(schema, level);
+  return null;
 };

package/src/lib/plugins/openapi/schema/utils.ts

@@ -1,7 +1,14 @@
+import { CIRCULAR_REF } from "../../../oas/graphql/circular.js";
 import type { SchemaObject } from "../../../oas/parser/index.js";
 
+export const isBasicType = (
+  type: unknown,
+): type is "string" | "number" | "boolean" | "integer" | "null" =>
+  typeof type === "string" &&
+  ["string", "number", "boolean", "integer", "null"].includes(type);
+
 export const isComplexType = (value: SchemaObject) =>
-  value.type === "object" ||
+  (value.type === "object" && Object.keys(value.properties ?? {}).length > 0) ||
   (value.type === "array" &&
     typeof value.items === "object" &&
     (!value.items.type || value.items.type === "object"));
@@ -16,3 +23,6 @@ export const LogicalSchemaTypeMap = {
 } as const;
 
 export type LogicalGroupType = "AND" | "OR" | "ONE";
+
+export const isCircularRef = (schema: unknown): schema is string =>
+  schema === CIRCULAR_REF;

package/src/lib/plugins/openapi/state.ts

@@ -0,0 +1,36 @@
+import { useMemo } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+
+interface SelectedServerState {
+  selectedServer?: string;
+  setSelectedServer: (newServer: string) => void;
+}
+
+export const useSelectedServerStore = create<SelectedServerState>()(
+  persist(
+    (set) => ({
+      selectedServer: undefined,
+      setSelectedServer: (newServer: string) =>
+        set({ selectedServer: newServer }),
+    }),
+    { name: "zudoku-selected-server" },
+  ),
+);
+
+/**
+ * Simple wrapper for `useSelectedServerStore` to fall back to first of the provided servers
+ */
+export const useSelectedServer = (servers: Array<{ url: string }>) => {
+  const { selectedServer, setSelectedServer } = useSelectedServerStore();
+
+  const finalSelectedServer = useMemo(
+    () =>
+      selectedServer && servers.some((s) => s.url === selectedServer)
+        ? selectedServer
+        : (servers.at(0)?.url ?? ""),
+    [selectedServer, servers],
+  );
+
+  return { selectedServer: finalSelectedServer, setSelectedServer };
+};

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

@@ -0,0 +1,37 @@
+import type { SidebarItem } from "../../../../config/validators/SidebarSchema.js";
+import type { OperationResult } from "../index.js";
+import { MethodColorMap } from "./methodColorMap.js";
+
+export const createSidebarCategory = ({
+  label,
+  path,
+  operations,
+  collapsible,
+  collapsed,
+}: {
+  label: string;
+  path: string;
+  operations: OperationResult[];
+  collapsible?: boolean;
+  collapsed?: boolean;
+}): SidebarItem => ({
+  type: "category",
+  label,
+  link: {
+    type: "doc" as const,
+    id: path,
+    label,
+  },
+  collapsible,
+  collapsed,
+  items: operations.map((operation) => ({
+    type: "link" as const,
+    label: operation.summary ?? operation.path,
+    href: `${path}#${operation.slug}`,
+    badge: {
+      label: operation.method,
+      color: MethodColorMap[operation.method.toLowerCase()]!,
+      invert: true,
+    },
+  })),
+});

package/src/lib/plugins/openapi/util/generateSchemaExample.ts

@@ -5,24 +5,35 @@ export const generateSchemaExample = (
   name?: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ): any => {
-  // Directly return the example or default if they exist
+  // Check for schema-level example first
   if (schema.example !== undefined) {
     return schema.example;
-  } else if (schema.examples) {
-    return Object.values(schema.examples)[0];
-  } else if (schema.default !== undefined) {
-    return schema.default;
   }
 
-  if (schema.properties || schema.type === "object") {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const example: any = {};
+  // Then check for schema-level examples
+  if (
+    schema.examples &&
+    typeof schema.examples === "object" &&
+    "default" in schema.examples
+  ) {
+    const defaultExample = schema.examples.default;
+    if (defaultExample !== null) {
+      return typeof defaultExample === "object" && "value" in defaultExample
+        ? defaultExample.value
+        : defaultExample;
+    }
+  }
+
+  // For object schemas with properties
+  if (schema.type === "object" && schema.properties) {
+    const example: Record<string, any> = {};
 
-    if (schema.properties) {
-      for (const [key, propSchema] of Object.entries(schema.properties)) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      if (typeof propSchema === "object") {
         example[key] = generateSchemaExample(propSchema as SchemaObject, key);
       }
     }
+
     return example;
   }
 
@@ -31,7 +42,9 @@ export const generateSchemaExample = (
       return schema.items.map((itemSchema) =>
         generateSchemaExample(itemSchema as SchemaObject),
       );
-    } else if (schema.items) {
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- OpenAPI schemas don't always adhere to spec
+    if (schema.items) {
       return [generateSchemaExample(schema.items as SchemaObject)];
     }
     return [];
@@ -51,6 +64,8 @@ export const generateSchemaExample = (
       return true;
     case "null":
       return null;
+    case "object":
+      return {};
     case undefined:
     default:
       return {};

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

@@ -0,0 +1,126 @@
+import { redirect, type RouteObject } from "react-router";
+import { joinUrl } from "../../../util/joinUrl.js";
+import type { GraphQLClient } from "../client/GraphQLClient.js";
+import { 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} /> };
+  },
+});
+
+// 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,
+      }),
+    ),
+    // Category without tagged operations
+    createRoute({
+      path: joinUrl(versionPath, UNTAGGED_PATH),
+      untagged: true,
+    }),
+    {
+      path: joinUrl(versionPath, "~schemas"),
+      lazy: async () => {
+        const { SchemaList } = await import("../SchemaList.js");
+        return { element: <SchemaList /> };
+      },
+    },
+  ];
+};
+
+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: [createRoute({ path: basePath + "/:tag?" })],
+        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 { ColorMap } from "../../../components/navigation/SidebarBadge.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,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: {