zudoku 0.3.0-dev.14 → 0.3.0-dev.140

package/src/lib/core/DevPortalContext.ts

@@ -1,9 +1,10 @@
 import { QueryClient } from "@tanstack/react-query";
-import { type ReactNode } from "react";
-import { create } from "zustand";
+import { NavigateFunction } from "react-router-dom";
+import type { SidebarConfig } from "../../config/validators/SidebarSchema.js";
 import { type AuthenticationProvider } from "../authentication/authentication.js";
 import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
-import { type DevPortalPath } from "../components/DevPortal.js";
+import { Slotlets } from "../components/SlotletProvider.js";
+import { joinPath } from "../util/joinPath.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
 import {
   type DevPortalPlugin,
@@ -19,53 +20,12 @@ export interface ApiIdentity {
   id: string;
 }
 
-type BaseNavigationCategoryItem = {
-  label: ReactNode;
-  title?: string;
-  muted?: boolean;
-  icon?: ReactNode;
-};
-
-export type PathNavigationCategoryItem = BaseNavigationCategoryItem & {
-  path: string;
-  children?: NavigationCategoryItem[];
-};
-
-export type HrefNavigationCategoryItem = BaseNavigationCategoryItem & {
-  href: string;
-};
-
-export type NavigationCategoryItem =
-  | PathNavigationCategoryItem
-  | HrefNavigationCategoryItem;
-
-export type NavigationCategory = {
-  label: string;
-  path?: string;
-  expanded?: boolean;
-  collapsible?: boolean;
-  icon?: ReactNode;
-  children: NavigationCategoryItem[];
-};
-
-export type NavigationItem = {
-  label: string;
-  path: DevPortalPath;
-  categories?: NavigationCategory[];
-};
-
-export type RoutingState = {
-  path?: string;
-};
-
 export const queryClient = new QueryClient();
 
-export const useRoutingState = create<RoutingState>(() => ({}));
-
 export type ApiKeyCache = "api-keys";
 export type DevPortalCacheKey = ApiKeyCache | string;
 
-export type ZudokuContextMetadataOptions = Partial<{
+type Metadata = Partial<{
   title: string;
   description: string;
   logo: string;
@@ -78,46 +38,62 @@ export type ZudokuContextMetadataOptions = Partial<{
   creator: string;
   publisher: string;
 }>;
-export type ZudokuContextPageOptions = Partial<{
+
+type Page = Partial<{
   pageTitle?: string;
-  logo?: string;
+  logo?: {
+    src: {
+      light: string;
+      dark: string;
+    };
+    width?: string;
+    alt?: string;
+  };
 }>;
+
 export type ZudokuContextOptions = {
-  metadata?: ZudokuContextMetadataOptions;
-  page?: ZudokuContextPageOptions;
+  metadata?: Metadata;
+  page?: Page;
   authentication?: AuthenticationProvider;
-  navigation: NavigationItem[];
+  topNavigation?: Array<{ id: string; label: string }>;
+  sidebars?: SidebarConfig;
   plugins?: DevPortalPlugin[];
-  mdxComponents?: MdxComponentsType;
+  slotlets?: Slotlets;
+  mdx?: {
+    components?: MdxComponentsType;
+  };
   overrides?: ComponentsContextType;
 };
 
 export class DevPortalContext {
-  private plugins: DevPortalPlugin[] = [];
-  private navigationPlugins: NavigationPlugin[];
-
-  public navigation: NavigationItem[];
+  public plugins: NonNullable<ZudokuContextOptions["plugins"]>;
+  public sidebars: NonNullable<ZudokuContextOptions["sidebars"]>;
+  public topNavigation: NonNullable<ZudokuContextOptions["topNavigation"]>;
   public meta: ZudokuContextOptions["metadata"];
   public page: ZudokuContextOptions["page"];
-  public authentication?: AuthenticationProvider;
-  public state: typeof useRoutingState;
+  public authentication?: ZudokuContextOptions["authentication"];
+  private navigationPlugins: NavigationPlugin[];
 
   constructor(config: ZudokuContextOptions) {
     this.plugins = config.plugins ?? [];
-    this.navigation = config.navigation;
+    this.topNavigation = config.topNavigation ?? [];
+    this.sidebars = config.sidebars ?? {};
     this.navigationPlugins = this.plugins.filter(isNavigationPlugin);
     this.authentication = config.authentication;
     this.meta = config.metadata;
     this.page = config.page;
-    this.state = useRoutingState;
   }
 
-  initialize = async () => {
-    await Promise.all([
+  initialize = async ({
+    navigate,
+  }: {
+    navigate: NavigateFunction;
+  }): Promise<void> => {
+    await Promise.all(
       this.plugins
         .filter(needsInitialization)
-        .map((plugin) => plugin.initialize?.(this)),
-    ]);
+        .map((plugin) => plugin.initialize?.(this, { navigate })),
+    );
   };
 
   invalidateCache = async (key: DevPortalCacheKey[]) => {
@@ -134,17 +110,17 @@ export class DevPortalContext {
     return keys.flat();
   };
 
-  getNavigation = async (path: string) => {
+  getPluginSidebar = async (path: string) => {
     const navigations = await Promise.all(
-      this.navigationPlugins.map(async (plugin) =>
-        plugin.getNavigation?.(path),
+      this.navigationPlugins.map((plugin) =>
+        plugin.getSidebar?.(joinPath(path)),
       ),
     );
 
     return navigations.flatMap((nav) => nav ?? []);
   };
 
-  async signRequest(request: Request) {
+  signRequest = async (request: Request) => {
     if (!this.authentication) {
       throw new Error("No authentication provider configured");
     }
@@ -154,5 +130,5 @@ export class DevPortalContext {
     request.headers.set("Authorization", `Bearer ${accessToken}`);
 
     return request;
-  }
+  };
 }

package/src/lib/core/plugins.ts

@@ -1,39 +1,66 @@
 import { type ReactElement } from "react";
-import { type RouteObject } from "react-router-dom";
-import {
-  DevPortalContext,
-  type ApiIdentity,
-  type NavigationCategory,
-} from "./DevPortalContext.js";
-
-export type PluginNavigationCategory = {
-  path: string;
-} & NavigationCategory;
+import { NavigateFunction, type RouteObject } from "react-router-dom";
+import type { Sidebar } from "../../config/validators/SidebarSchema.js";
+import { MdxComponentsType } from "../util/MdxComponents.js";
+import { DevPortalContext, type ApiIdentity } from "./DevPortalContext.js";
 
 export type DevPortalPlugin =
   | CommonPlugin
+  | ProfileMenuPlugin
   | NavigationPlugin
-  | ApiIdentityPlugin;
+  | ApiIdentityPlugin
+  | SearchProviderPlugin;
 
 export interface NavigationPlugin {
   getRoutes: () => RouteObject[];
-  getNavigation?: (path: string) => Promise<PluginNavigationCategory[]>;
+  getSidebar?: (path: string) => Promise<Sidebar>;
 }
 
 export interface ApiIdentityPlugin {
   getIdentities: (context: DevPortalContext) => Promise<ApiIdentity[]>;
 }
 
+export interface SearchProviderPlugin {
+  renderSearch: (o: {
+    isOpen: boolean;
+    onClose: () => void;
+  }) => React.JSX.Element | null;
+}
+
+export interface ProfileMenuPlugin {
+  getProfileMenuItems: (context: DevPortalContext) => ProfileNavigationItem[];
+}
+
+export type ProfileNavigationItem = {
+  label: string;
+  path?: string;
+  children?: ProfileNavigationItem[];
+};
+
 export interface CommonPlugin {
-  initialize?: (context: DevPortalContext) => Promise<void> | void;
+  initialize?: (
+    context: DevPortalContext,
+    options: { navigate: NavigateFunction },
+  ) => Promise<void | boolean> | void | boolean;
   getHead?: () => ReactElement | undefined;
+  getMdxComponents?: () => MdxComponentsType;
 }
 
+export const isProfileMenuPlugin = (
+  obj: DevPortalPlugin,
+): obj is ProfileMenuPlugin =>
+  "getProfileMenuItems" in obj && typeof obj.getProfileMenuItems === "function";
+
 export const isNavigationPlugin = (
   obj: DevPortalPlugin,
 ): obj is NavigationPlugin =>
   "getRoutes" in obj && typeof obj.getRoutes === "function";
 
+export const isSearchPlugin = (
+  obj: DevPortalPlugin,
+): obj is SearchProviderPlugin =>
+  "renderSearch" in obj && typeof obj.renderSearch === "function";
+
 export const needsInitialization = (
   obj: DevPortalPlugin,
 ): obj is CommonPlugin =>
@@ -42,6 +69,11 @@ export const needsInitialization = (
 export const hasHead = (obj: DevPortalPlugin): obj is CommonPlugin =>
   "getHead" in obj && typeof obj.getHead === "function";
 
+export const isMdxProviderPlugin = (
+  obj: DevPortalPlugin,
+): obj is CommonPlugin =>
+  "getMdxComponents" in obj && typeof obj.getMdxComponents === "function";
+
 export const isApiIdentityPlugin = (
   obj: DevPortalPlugin,
 ): obj is ApiIdentityPlugin =>

package/src/lib/errors/ErrorAlert.tsx

@@ -0,0 +1,21 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function ErrorAlert({ error }: { error: any }) {
+  const message = error?.message ?? "Something went wrong";
+  const stack = error?.stack;
+
+  return (
+    <div className="flex h-screen max-h-screen min-h-full items-center justify-center bg-primary-background px-4 py-16 lg:px-8">
+      <div className="mx-auto max-w-[85%] sm:max-w-[50%]">
+        <h1 className="text-4xl font-bold tracking-tight text-h1-text sm:text-5xl">
+          Something went wrong
+        </h1>
+        <p className="mt-5 text-h1-text">{message}</p>
+        {stack ? (
+          <pre className="mt-5 max-h-[400px] w-full overflow-scroll rounded-md border border-input-border bg-input-background p-3 text-property-name-text text-red-700">
+            {stack}
+          </pre>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/lib/errors/RouterError.tsx

@@ -0,0 +1,13 @@
+import { isRouteErrorResponse, useRouteError } from "react-router-dom";
+import { NotFoundPage } from "../components/NotFoundPage.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function RouterError() {
+  const error = useRouteError();
+
+  if (isRouteErrorResponse(error) && error.status === 404) {
+    return <NotFoundPage />;
+  }
+
+  return <ErrorAlert error={error} />;
+}

package/src/lib/errors/ServerError.tsx

@@ -0,0 +1,5 @@
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function ServerError({ error }: { error: unknown }) {
+  return <ErrorAlert error={error} />;
+}

package/src/lib/errors/TopLevelError.tsx

@@ -0,0 +1,8 @@
+import { FallbackProps } from "react-error-boundary";
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function TopLevelError({ error, resetErrorBoundary }: FallbackProps) {
+  // Call resetErrorBoundary() to reset the error boundary and retry the render.
+
+  return <ErrorAlert error={error} />;
+}

package/src/lib/oas/graphql/index.ts

@@ -36,11 +36,16 @@ type OperationLike = {
   method: string;
 };
 export const slugifyOperation = (operation: OperationLike, tag?: string) => {
+  const summary =
+    (operation.summary ?? "") +
+    (operation.operationId
+      ? "-" +
+        operation.operationId.slice(0, operation.summary ? Infinity : Infinity)
+      : "");
+
   return slugify(
     (tag ? tag + "-" : "") +
-      (operation.summary ??
-        operation.operationId ??
-        `${operation.method}-${operation.path}`),
+      (summary || `${operation.method}-${operation.path}`),
     { lower: true, trim: true },
   );
 };
@@ -63,6 +68,25 @@ const builder = new SchemaBuilder<{
 const JSONScalar = builder.addScalarType("JSON", GraphQLJSON);
 const JSONObjectScalar = builder.addScalarType("JSONObject", GraphQLJSONObject);
 
+const getAllTags = (schema: OpenAPIDocument): TagObject[] => {
+  const tags = schema.tags ?? [];
+
+  // Extract tags from operations
+  const operationTags = Object.values(schema.paths ?? {})
+    .flatMap((path) => Object.values(path ?? {}))
+    .flatMap((operation) =>
+      typeof operation === "object" && "tags" in operation
+        ? operation.tags ?? []
+        : [],
+    );
+
+  // Remove duplicates and tags that appear in the schema
+  const uniqueOperationTags = [...new Set(operationTags)].filter(
+    (tag) => !tags.some((rootTag) => rootTag.name === tag),
+  );
+  return [...tags, ...uniqueOperationTags.map((tag) => ({ name: tag }))];
+};
+
 const getAllOperations = (paths?: PathsObject, tag?: string) => {
   return Object.entries(paths ?? {}).flatMap(([path, value]) =>
     HttpMethods.flatMap((method) => {
@@ -90,6 +114,7 @@ const getAllOperations = (paths?: PathsObject, tag?: string) => {
         method,
         path,
         parameters,
+        tags: operation.tags ?? [],
         slug: slugifyOperation(
           {
             summary: operation.summary,
@@ -110,12 +135,17 @@ const SchemaTag = builder.objectRef<TagObject>("SchemaTag").implement({
     description: t.exposeString("description", { nullable: true }),
     operations: t.field({
       type: [OperationItem],
-      resolve: (parent, _args, ctx) =>
-        getAllOperations(ctx.schema.paths, parent.name).filter((item) =>
+      resolve: (parent, _args, ctx) => {
+        const rootTags = getAllTags(ctx.schema).map((tag) => tag.name);
+
+        return getAllOperations(ctx.schema.paths, parent.name).filter((item) =>
           parent.name
-            ? item.tags?.includes(parent.name)
-            : !item.tags || item.tags.length === 0,
-        ),
+            ? item.tags.includes(parent.name)
+            : item.tags.length === 0 ||
+              // If none of the tags are present in the root tags, then show them here
+              item.tags.every((tag) => !rootTags.includes(tag)),
+        );
+      },
     }),
   }),
 });
@@ -207,7 +237,7 @@ const MediaTypeItem = builder
   .implement({
     fields: (t) => ({
       mediaType: t.exposeString("mediaType"),
-      schema: t.expose("schema", { type: JSONScalar }),
+      schema: t.expose("schema", { type: JSONScalar, nullable: true }),
       examples: t.expose("examples", { type: [ExampleItem], nullable: true }),
       encoding: t.expose("encoding", { type: [EncodingItem], nullable: true }),
     }),
@@ -235,7 +265,7 @@ const RequestBodyObject = builder
 const ResponseItem = builder
   .objectRef<{
     statusCode: string;
-    description: string;
+    description?: string;
     content: Array<{
       mediaType: string;
       schema: any;
@@ -247,7 +277,7 @@ const ResponseItem = builder
   .implement({
     fields: (t) => ({
       statusCode: t.exposeString("statusCode"),
-      description: t.exposeString("description"),
+      description: t.exposeString("description", { nullable: true }),
       content: t.expose("content", { type: [MediaTypeItem], nullable: true }),
       headers: t.expose("headers", { type: JSONScalar, nullable: true }),
       links: t.expose("links", { type: JSONScalar, nullable: true }),
@@ -352,10 +382,10 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
         name: t.arg.string(),
       },
       type: [SchemaTag],
-      resolve: (root, args) =>
-        [...(root.tags ?? []), { name: "" }].filter(
-          (tag) => !args.name || args.name === tag.name,
-        ),
+      resolve: (root, args) => {
+        const tags = [...getAllTags(root), { name: "" }];
+        return args.name ? tags.filter((tag) => tag.name === args.name) : tags;
+      },
     }),
     operations: t.field({
       type: [OperationItem],
@@ -371,7 +401,7 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
             (!args.operationId || item.operationId === args.operationId) &&
             (!args.path || item.path === args.path) &&
             (!args.method || item.method === args.method) &&
-            (!args.tag || item.tags?.includes(args.tag)),
+            (!args.tag || item.tags.includes(args.tag)),
         ),
     }),
   }),

package/src/lib/oas/parser/index.ts

@@ -1,3 +1,4 @@
+import { GraphQLError } from "graphql/error/index.js";
 import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
 import { dereference, type JSONSchema } from "./dereference/index.js";
 import { upgradeSchema } from "./upgrade/index.js";
@@ -9,10 +10,6 @@ type DeepOmitReference<T> = T extends ReferenceObject
     ? { [K in keyof T]: DeepOmitReference<T[K]> }
     : T;
 
-// type Prettify<T> = {
-//   [K in keyof T]: T[K];
-// } & {};
-
 export type OpenAPIDocument = DeepOmitReference<OpenAPIV3_1.Document>;
 export type ResponseObject = DeepOmitReference<OpenAPIV3_1.ResponseObject>;
 export type OperationObject = DeepOmitReference<OpenAPIV3_1.OperationObject>;
@@ -46,37 +43,63 @@ export const HttpMethods = Object.values(OpenAPIV3.HttpMethods);
 // };
 
 const parseSchemaInput = async (
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  schemaInput: any,
+  schemaInput: unknown,
 ): Promise<JSONSchema & { openapi?: string }> => {
   if (typeof schemaInput === "string") {
     if (schemaInput.trim().startsWith("{")) {
-      return JSON.parse(schemaInput);
+      try {
+        return JSON.parse(schemaInput);
+      } catch (err) {
+        throw new GraphQLError("Invalid JSON schema", {
+          originalError: err,
+        });
+      }
     }
     if (schemaInput.includes("://")) {
-      const response = await fetch(schemaInput, {
-        cache: "force-cache",
-      });
-      return (await response.json()) as JSONSchema;
+      let response;
+      try {
+        response = await fetch(schemaInput, {
+          cache: "force-cache",
+        });
+      } catch (err) {
+        throw new GraphQLError("Failed to fetch schema", {
+          originalError: err,
+        });
+      }
+
+      if (!response.ok) {
+        throw new GraphQLError(
+          `Failed to fetch schema: ${response.statusText}`,
+        );
+      }
+
+      try {
+        return (await response.json()) as JSONSchema;
+      } catch (err) {
+        throw new GraphQLError("Fetched invalid JSON schema", {
+          originalError: err,
+        });
+      }
     }
     const yaml = await import("yaml");
-    return yaml.parse(schemaInput);
+    const parsed = yaml.parse(schemaInput);
+
+    if (typeof parsed === "object") return parsed;
   }
 
-  if (typeof schemaInput === "object") return schemaInput;
+  if (typeof schemaInput === "object") return schemaInput as JSONSchema;
 
-  throw new Error("Unsupported schema input");
+  throw new GraphQLError("Unsupported schema input: " + schemaInput);
 };
 
 /**
  * Validates, dereferences and upgrades the OpenAPI schema (to v3.1) if necessary.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const validate = async (schemaInput: any) => {
+export const validate = async (schemaInput: unknown) => {
   const schema = await parseSchemaInput(schemaInput);
 
   if (!schema.openapi) {
-    throw new Error("OpenAPI version is not defined");
+    throw new GraphQLError("OpenAPI version is not defined");
   }
 
   // const validator = await getValidator(schema.openapi);
@@ -88,9 +111,5 @@ export const validate = async (schemaInput: any) => {
 
   const dereferenced = await dereference(schema);
 
-  const upgraded = upgradeSchema(
-    dereferenced as OpenAPIV3_1.Document | OpenAPIV3.Document,
-  );
-
-  return upgraded;
+  return upgradeSchema(dereferenced);
 };

package/src/lib/plugins/{api-key → api-keys}/CreateApiKey.tsx

@@ -1,8 +1,7 @@
 import { useMutation } from "@tanstack/react-query";
 import { useForm } from "react-hook-form";
 import { Link, useNavigate } from "react-router-dom";
-import { useDevPortal } from "../../components/context/DevPortalProvider.js";
-import { Input } from "../../components/Input.js";
+import { useZudoku } from "../../components/context/ZudokuContext.js";
 import {
   Select,
   SelectContent,
@@ -12,12 +11,13 @@ import {
   SelectValue,
 } from "../../components/Select.js";
 import { Button } from "../../ui/Button.js";
+import { Input } from "../../ui/Input.js";
 import { ApiKeyService } from "./index.js";
 
 type CreateApiKey = { description: string; expiresOn?: string };
 
 export const CreateApiKey = ({ service }: { service: ApiKeyService }) => {
-  const context = useDevPortal();
+  const context = useZudoku();
   const navigate = useNavigate();
   const form = useForm<CreateApiKey>({
     defaultValues: {
@@ -47,7 +47,7 @@ export const CreateApiKey = ({ service }: { service: ApiKeyService }) => {
 
   return (
     <div className="max-w-screen-lg pt-[--padding-content-top] pb-[--padding-content-bottom]">
-      <div className="flex justify-between mb-4 border-b border-border pb-1">
+      <div className="flex justify-between mb-4 border-b pb-1">
         <h1 className="font-medium text-2xl">New API Key</h1>
       </div>
       <form

package/src/lib/plugins/api-keys/ProtectedRoute.tsx

@@ -0,0 +1,29 @@
+import { Outlet } from "react-router-dom";
+import { useAuth } from "../../authentication/hook.js";
+import { DeveloperHint } from "../../components/DeveloperHint.js";
+import { Button } from "../../ui/Button.js";
+
+export const ProtectedRoute = () => {
+  const auth = useAuth();
+
+  // TODO: should we suspend here somehow?
+  if (auth.isAuthEnabled && auth.isPending) {
+    return null;
+  }
+
+  return auth.isAuthenticated ? (
+    <Outlet />
+  ) : !auth.isAuthEnabled ? (
+    <div className="flex flex-col justify-center gap-2 items-center h-1/2">
+      <DeveloperHint className="max-w-[600px]">
+        Authentication needs to be enabled for API keys to work. Enable it in
+        your Zudoku configuration under <code>authentication</code>.
+      </DeveloperHint>
+    </div>
+  ) : (
+    <div className="flex flex-col justify-center gap-2 items-center h-1/2">
+      Please login first to view this page
+      <Button onClick={() => auth.login()}>Login</Button>
+    </div>
+  );
+};