zudoku 0.3.0-dev.8 → 0.3.0-dev.81

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

@@ -1,26 +1,25 @@
-import logger from "loglevel";
-import { Outlet, useRouteError } from "react-router-dom";
-import invariant from "tiny-invariant";
-import { useAuth } from "../../authentication/hook.js";
+import { type RouteObject } from "react-router-dom";
 import { DevPortalContext } from "../../core/DevPortalContext.js";
 import {
   type ApiIdentityPlugin,
   type DevPortalPlugin,
+  ProfileMenuPlugin,
 } from "../../core/plugins.js";
-import { Button } from "../../ui/Button.js";
+import { RouterError } from "../../errors/RouterError.js";
+import invariant from "../../util/invariant.js";
 import { CreateApiKey } from "./CreateApiKey.js";
+import { ProtectedRoute } from "./ProtectedRoute.js";
 import { SettingsApiKeys } from "./SettingsApiKeys.js";
 
-export type ApiKeyResults = Promise<ApiKey[]>;
 const DEFAULT_API_KEY_ENDPOINT =
   "https://zudoku-rewiringamerica-main-ef9c9c0.d2.zuplo.dev";
 
 export type ApiKeyService = {
-  getKeys: (context: DevPortalContext) => ApiKeyResults;
+  getKeys: (context: DevPortalContext) => Promise<ApiKey[]>;
   rollKey?: (id: string, context: DevPortalContext) => Promise<void>;
   deleteKey?: (id: string, context: DevPortalContext) => Promise<void>;
   updateKeyDescription?: (
-    apiKey: { jd: string; description: string },
+    apiKey: { id: string; description: string },
     context: DevPortalContext,
   ) => Promise<void>;
   getUsage?: (apiKeys: string[], context: DevPortalContext) => Promise<void>;
@@ -82,39 +81,9 @@ const createDefaultHandler = (endpoint: string): ApiKeyService => {
   };
 };
 
-const ProtectedRoute = () => {
-  const auth = useAuth();
-
-  // TODO: should we suspend here somehow?
-  if (auth.isPending) {
-    return null;
-  }
-
-  return auth.isAuthenticated ? (
-    <Outlet />
-  ) : (
-    <div className="flex flex-col justify-center gap-2 items-center h-1/2 my-12">
-      Please login first to view this page
-      <Button onClick={() => auth.login()}>Login</Button>
-    </div>
-  );
-};
-
-const SettingsErrorBoundary = () => {
-  const error = useRouteError();
-  logger.error(String(error));
-
-  return (
-    <div className="flex flex-col justify-center gap-2 items-center h-1/2 my-12">
-      <h1>Something went wrong</h1>
-      {error instanceof Error && <p>{error.message}</p>}
-    </div>
-  );
-};
-
 export const apiKeyPlugin = (
   options: ApiKeyPluginOptions,
-): DevPortalPlugin & ApiIdentityPlugin => {
+): DevPortalPlugin & ApiIdentityPlugin & ProfileMenuPlugin => {
   const endpoint =
     "endpoint" in options ? options.endpoint : DEFAULT_API_KEY_ENDPOINT;
 
@@ -122,6 +91,12 @@ export const apiKeyPlugin = (
     "getKeys" in options ? options : createDefaultHandler(endpoint);
 
   return {
+    getProfileMenuItems: () => [
+      {
+        label: "API Keys",
+        path: "/settings/api-keys",
+      },
+    ],
     getIdentities: async (context) => {
       try {
         const keys = await service.getKeys(context);
@@ -138,11 +113,12 @@ export const apiKeyPlugin = (
         return [];
       }
     },
-    getRoutes: () => {
+    getRoutes: (): RouteObject[] => {
+      // TODO: Make lazy
       return [
         {
           element: <ProtectedRoute />,
-          errorElement: <SettingsErrorBoundary />,
+          errorElement: <RouterError />,
           children: [
             {
               path: "/settings/api-keys",

package/src/lib/plugins/custom-page/index.tsx

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+import type { RouteObject } from "react-router-dom";
+import { ProseClasses } from "../../components/Markdown.js";
+import type { DevPortalPlugin, NavigationPlugin } from "../../core/plugins.js";
+
+type CustomPageConfig = Array<{
+  path: string;
+  element: ReactNode;
+}>;
+
+export const customPagePlugin = (
+  config: CustomPageConfig,
+): DevPortalPlugin & NavigationPlugin => {
+  return {
+    getRoutes: (): RouteObject[] =>
+      config.map(({ path, element }) => ({
+        path,
+        // TODO: we should componentize prose pages
+        element: <div className={ProseClasses + " max-w-full"}>{element}</div>,
+      })),
+  };
+};

package/src/lib/plugins/markdown/MdxPage.tsx

@@ -1,18 +1,18 @@
 import { useMDXComponents } from "@mdx-js/react";
+import { Helmet } from "@zudoku/react-helmet-async";
 import { useMemo, type PropsWithChildren, type ReactNode } from "react";
+import { Link, useLocation } from "react-router-dom";
 import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
 import { ProseClasses } from "../../components/Markdown.js";
 import { useTopNavigationItem } from "../../components/context/DevPortalProvider.js";
 import { isPathItem } from "../../components/navigation/util.js";
-import { Helmet } from "../../core/helmet.js";
-import { Link, useLocation } from "../../core/router.js";
 import type { MdxComponentsType } from "../../util/MdxComponents.js";
 import { cn } from "../../util/cn.js";
 import slugify from "../../util/slugify.js";
 import { traverseNavigation } from "../../util/traverseNavigation.js";
 import { Toc } from "./Toc.js";
-import type { MDXImport } from "./index.js";
+import { MarkdownPluginDefaultOptions, MDXImport } from "./index.js";
 
 const MarkdownHeadings = {
   h2: ({ children, id }) => (
@@ -31,10 +31,12 @@ const MarkdownHeadings = {
 export const MdxPage = ({
   mdxComponent: MdxComponent,
   frontmatter = {},
+  defaultOptions,
   tableOfContents,
 }: PropsWithChildren<
   Omit<MDXImport, "default"> & {
     mdxComponent: MDXImport["default"];
+    defaultOptions?: MarkdownPluginDefaultOptions;
   }
 >) => {
   const navItem = useTopNavigationItem();
@@ -50,10 +52,11 @@ export const MdxPage = ({
 
   const title = frontmatter.title;
   const category = frontmatter.category ?? categoryTitle;
-  const hideToc = frontmatter.toc === false;
-
+  const hideToc = frontmatter.toc === false || defaultOptions?.toc === false;
   const pageTitle =
     tableOfContents.find((item) => item.depth === 1)?.value ?? title;
+  const hidePager =
+    frontmatter.disablePager ?? defaultOptions?.disablePager ?? false;
 
   const tocEntries =
     tableOfContents.find((item) => item.depth === 1)?.children ??
@@ -112,35 +115,49 @@ export const MdxPage = ({
         <MdxComponent
           components={{ ...useMDXComponents(), ...MarkdownHeadings }}
         />
-        <hr />
-        <div className="not-prose flex items-center justify-between gap-8">
-          {prev.path ? (
-            <Link
-              to={prev.path}
-              className="flex flex-col items-stretch gap-2 flex-1 truncate border border-border rounded px-6 py-4 text-start hover:border-primary/85 transition shadow-sm hover:shadow-md"
-              title={typeof prev.label === "string" ? prev.label : undefined}
-            >
-              <div className="text-sm text-muted-foreground">
-                ← Previous page
-              </div>
-              <div className="text-lg text-primary truncate">{prev.label}</div>
-            </Link>
-          ) : (
-            <div className="flex-1" />
-          )}
-          {next.path ? (
-            <Link
-              to={next.path}
-              className="flex flex-col items-stretch gap-2 flex-1 truncate border border-border rounded px-6 py-4 text-end hover:border-primary/85 transition shadow-sm hover:shadow-md"
-              title={typeof next.label === "string" ? next.label : undefined}
-            >
-              <div className="text-sm text-muted-foreground">Next page →</div>
-              <div className="text-lg text-primary truncate">{next.label}</div>
-            </Link>
-          ) : (
-            <div className="flex-1" />
-          )}
-        </div>
+        {!hidePager && (
+          <>
+            <hr />
+            <div className="not-prose flex items-center justify-between gap-8">
+              {prev.path ? (
+                <Link
+                  to={prev.path}
+                  className="flex flex-col items-stretch gap-2 flex-1 truncate border rounded px-6 py-4 text-start hover:border-primary/85 transition shadow-sm hover:shadow-md"
+                  title={
+                    typeof prev.label === "string" ? prev.label : undefined
+                  }
+                >
+                  <div className="text-sm text-muted-foreground">
+                    ← Previous page
+                  </div>
+                  <div className="text-lg text-primary truncate">
+                    {prev.label}
+                  </div>
+                </Link>
+              ) : (
+                <div className="flex-1" />
+              )}
+              {next.path ? (
+                <Link
+                  to={next.path}
+                  className="flex flex-col items-stretch gap-2 flex-1 truncate border rounded px-6 py-4 text-end hover:border-primary/85 transition shadow-sm hover:shadow-md"
+                  title={
+                    typeof next.label === "string" ? next.label : undefined
+                  }
+                >
+                  <div className="text-sm text-muted-foreground">
+                    Next page →
+                  </div>
+                  <div className="text-lg text-primary truncate">
+                    {next.label}
+                  </div>
+                </Link>
+              ) : (
+                <div className="flex-1" />
+              )}
+            </div>
+          </>
+        )}
       </div>
       <div className="hidden xl:block">
         {showToc && <Toc entries={tocEntries} />}

package/src/lib/plugins/markdown/Toc.tsx

@@ -1,4 +1,5 @@
 import type { TocEntry } from "@stefanprobst/rehype-extract-toc";
+import { ListTreeIcon } from "lucide-react";
 import {
   useEffect,
   useRef,
@@ -8,7 +9,6 @@ import {
 } from "react";
 import { AnchorLink } from "../../components/AnchorLink.js";
 import { useViewportAnchor } from "../../components/context/ViewportAnchorContext.js";
-import { ListTreeIcon } from "../../core/icons.js";
 import { cn } from "../../util/cn.js";
 
 const DATA_ANCHOR_ATTR = "data-active";
@@ -53,7 +53,11 @@ const TocItem = ({
 export const Toc = ({ entries }: { entries: TocEntry[] }) => {
   const { activeAnchor } = useViewportAnchor();
   const listWrapperRef = useRef<HTMLUListElement>(null);
-  const [indicatorStyle, setIndicatorStyles] = useState<CSSProperties>({});
+  const paintedOnce = useRef(false);
+  const [indicatorStyle, setIndicatorStyles] = useState<CSSProperties>({
+    top: 0,
+    opacity: 0,
+  });
 
   // synchronize active anchor indicator with the scroll position
   useEffect(() => {
@@ -64,10 +68,7 @@ export const Toc = ({ entries }: { entries: TocEntry[] }) => {
     );
 
     if (!activeElement) {
-      setIndicatorStyles({
-        "--indicator-top": "0",
-        "--indicator-opacity": 0,
-      } as CSSProperties);
+      setIndicatorStyles({ top: 0, opacity: 0 });
       return;
     }
 
@@ -75,9 +76,16 @@ export const Toc = ({ entries }: { entries: TocEntry[] }) => {
     const topElement = activeElement.getBoundingClientRect().top;
 
     setIndicatorStyles({
-      "--indicator-top": `${topElement - topParent}px`,
-      "--indicator-opacity": 1,
-    } as CSSProperties);
+      opacity: 1,
+      top: `${topElement - topParent}px`,
+    });
+
+    if (paintedOnce.current) return;
+
+    // after all is painted, the indicator should animate
+    requestIdleCallback(() => {
+      paintedOnce.current = true;
+    });
   }, [activeAnchor]);
 
   return (
@@ -86,37 +94,42 @@ export const Toc = ({ entries }: { entries: TocEntry[] }) => {
         <ListTreeIcon size={16} />
         On this page
       </div>
-
-      <ul
-        ref={listWrapperRef}
-        style={indicatorStyle}
-        className={cn(
-          "relative ms-2 ps-4 font-medium list-none mt-0 space-y-2",
-          "before:absolute before:inset-0 before:right-auto before:bg-border before:w-[2px]",
-          "after:absolute after:-left-px after:-translate-y-1 after:top-[--indicator-top] after:opacity-[--indicator-opacity] after:h-6 after:bg-primary after:w-[4px] after:rounded after:ease-out after:[transition:top__150ms,opacity_325ms]",
-        )}
-      >
-        {entries.map((item) => (
-          <TocItem
-            isActive={item.id === activeAnchor}
-            key={item.id}
-            item={item}
-            className="pl-0"
-          >
-            {item.children && (
-              <ul className="list-none pl-4 pt-2 space-y-2">
-                {item.children.map((child) => (
-                  <TocItem
-                    item={child}
-                    isActive={child.id === activeAnchor}
-                    key={child.id}
-                  />
-                ))}
-              </ul>
-            )}
-          </TocItem>
-        ))}
-      </ul>
+      <div className="relative ms-2 ps-4">
+        <div className="absolute inset-0 right-auto bg-border w-[2px]" />
+        <div
+          className={cn(
+            "absolute -left-px -translate-y-1 h-6 w-[4px] rounded bg-primary",
+            paintedOnce.current &&
+              "ease-out [transition:top_150ms,opacity_325ms]",
+          )}
+          style={indicatorStyle}
+        />
+        <ul
+          ref={listWrapperRef}
+          className="relative font-medium list-none space-y-2"
+        >
+          {entries.map((item) => (
+            <TocItem
+              isActive={item.id === activeAnchor}
+              key={item.id}
+              item={item}
+              className="pl-0"
+            >
+              {item.children && (
+                <ul className="list-none pl-4 pt-2 space-y-2">
+                  {item.children.map((child) => (
+                    <TocItem
+                      item={child}
+                      isActive={child.id === activeAnchor}
+                      key={child.id}
+                    />
+                  ))}
+                </ul>
+              )}
+            </TocItem>
+          ))}
+        </ul>
+      </div>
     </aside>
   );
 };

package/src/lib/plugins/markdown/generateRoutes.tsx

@@ -1,12 +1,16 @@
+import { Navigate, type RouteObject } from "react-router-dom";
 import { useTopNavigationItem } from "../../components/context/DevPortalProvider.js";
 import { isPathItem } from "../../components/navigation/util.js";
-import { Navigate, type RouteObject } from "../../core/router.js";
 import { traverseNavigation } from "../../util/traverseNavigation.js";
-import { MdxPage } from "./MdxPage.js";
-import type { MarkdownPluginOptions } from "./index.js";
+
+import {
+  MarkdownPluginDefaultOptions,
+  MarkdownPluginOptions,
+} from "./index.js";
 
 export const generateRoutes = (
   markdownFiles: MarkdownPluginOptions["markdownFiles"],
+  defaultOptions?: MarkdownPluginDefaultOptions,
 ): RouteObject[] => {
   const routes = Object.entries(markdownFiles).flatMap(
     ([file, importPromise]) => {
@@ -25,17 +29,23 @@ export const generateRoutes = (
       return {
         path: routePath,
         lazy: async () => {
+          const { MdxPage } = await import("./MdxPage.js");
           const { default: Component, ...props } = await importPromise();
-
           return {
-            element: <MdxPage mdxComponent={Component} {...props} />,
+            element: (
+              <MdxPage
+                mdxComponent={Component}
+                {...props}
+                defaultOptions={defaultOptions}
+              />
+            ),
           };
         },
       } satisfies RouteObject;
     },
   );
 
-  const rootRoutes = Array.from(
+  const rootRoutes: RouteObject[] = Array.from(
     new Set(routes.map((route) => route.path.split("/").at(0))),
   ).map((dir) => ({
     path: `/${dir}`,

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

@@ -5,13 +5,19 @@ import { generateRoutes } from "./generateRoutes.js";
 
 export type MarkdownPluginOptions = {
   markdownFiles: Record<string, () => Promise<MDXImport>>;
+  defaultOptions?: MarkdownPluginDefaultOptions;
 };
+export type MarkdownPluginDefaultOptions = Pick<
+  Frontmatter,
+  "toc" | "disablePager"
+>;
 
 export type Frontmatter = {
   title?: string;
   description?: string;
   category?: string;
   toc?: boolean;
+  disablePager?: boolean;
 };
 
 export type MDXImport = {
@@ -22,10 +28,7 @@ export type MDXImport = {
 
 export const markdownPlugin = ({
   markdownFiles,
-}: MarkdownPluginOptions): DevPortalPlugin => {
-  return {
-    getRoutes() {
-      return generateRoutes(markdownFiles);
-    },
-  };
-};
+  defaultOptions,
+}: MarkdownPluginOptions): DevPortalPlugin => ({
+  getRoutes: () => generateRoutes(markdownFiles, defaultOptions),
+});

package/src/lib/plugins/openapi/ColorizedParam.tsx

@@ -9,7 +9,7 @@ export const usePastellizedColor = (name: string) => {
   const [isDark] = useTheme();
   return pastellize(
     name,
-    !isDark ? { saturation: 100, lightness: 70 } : undefined,
+    !isDark ? { saturation: 85, lightness: 50 } : undefined,
   );
 };
 
@@ -17,6 +17,7 @@ export const ColorizedParam = ({
   name,
   className,
   backgroundOpacity = "100%",
+  borderOpacity = "100%",
   slug,
   children,
   onClick,
@@ -24,34 +25,40 @@ export const ColorizedParam = ({
   name: string;
   className?: string;
   backgroundOpacity?: string;
+  borderOpacity?: string;
   slug?: string;
   children?: ReactNode;
   onClick?: () => void;
 }) => {
   const ref = useRef<HTMLSpanElement>(null);
-  const normalized = name.replace("{", "").replace("}", "");
+  const normalized = name.replace(/[{}]/g, "");
+  const normalizedSlug = slug?.replace(/[{}]/g, "");
   const color = usePastellizedColor(normalized);
 
-  const borderColor = `hsl(${color})`;
+  const borderColor = `hsl(${color} / ${borderOpacity})`;
   const backgroundColor = `hsl(${color} / ${backgroundOpacity})`;
 
   useEffect(() => {
-    if (!slug) return;
+    if (!normalizedSlug) return;
     if (!ref.current) return;
 
     const onMouseEnter = () => {
-      document.querySelectorAll(`[${DATA_ATTR}="${slug}"]`).forEach((el) => {
-        if (el instanceof HTMLElement) {
-          el.dataset.active = "true";
-        }
-      });
+      document
+        .querySelectorAll(`[${DATA_ATTR}="${normalizedSlug}"]`)
+        .forEach((el) => {
+          if (el instanceof HTMLElement) {
+            el.dataset.active = "true";
+          }
+        });
     };
     const onMouseLeave = () => {
-      document.querySelectorAll(`[${DATA_ATTR}="${slug}"]`).forEach((el) => {
-        if (el instanceof HTMLElement) {
-          el.dataset.active = "false";
-        }
-      });
+      document
+        .querySelectorAll(`[${DATA_ATTR}="${normalizedSlug}"]`)
+        .forEach((el) => {
+          if (el instanceof HTMLElement) {
+            el.dataset.active = "false";
+          }
+        });
     };
 
     ref.current.addEventListener("mouseenter", onMouseEnter);
@@ -61,12 +68,12 @@ export const ColorizedParam = ({
       ref.current?.removeEventListener("mouseenter", onMouseEnter);
       ref.current?.removeEventListener("mouseleave", onMouseLeave);
     };
-  }, [slug]);
+  }, [normalizedSlug]);
 
   return (
     <span
       className={cn("inline-flex relative rounded group", className)}
-      {...{ [DATA_ATTR]: slug }}
+      {...{ [DATA_ATTR]: normalizedSlug }}
       ref={ref}
       onClick={onClick}
     >

package/src/lib/plugins/openapi/OperationList.tsx

@@ -1,11 +1,17 @@
 import { ResultOf } from "@graphql-typed-document-node/core";
 import { CategoryHeading } from "../../components/CategoryHeading.js";
+import { DeveloperHint } from "../../components/DeveloperHint.js";
+import { ErrorPage } from "../../components/ErrorPage.js";
 import { Heading } from "../../components/Heading.js";
-import { Markdown, ProseClasses } from "../../components/Markdown.js";
+import { InlineCode } from "../../components/InlineCode.js";
+import { Markdown } from "../../components/Markdown.js";
+import { SyntaxHighlight } from "../../components/SyntaxHighlight.js";
 import { cn } from "../../util/cn.js";
 import { OperationListItem } from "./OperationListItem.js";
+import StaggeredRender from "./StaggeredRender.js";
+import { useOasConfig } from "./context.js";
 import { graphql } from "./graphql/index.js";
-import { useOasConfig } from "./index.js";
+import { SchemaProseClasses } from "./util/prose.js";
 import { useQuery } from "./util/urql.js";
 
 export const OperationsFragment = graphql(/* GraphQL */ `
@@ -90,11 +96,39 @@ export const OperationList = () => {
     context: suspenseContext,
   });
 
+  const error = result.error?.graphQLErrors.at(0);
+
+  // Looks like there is no Suspense level error handling (yet)?
+  // So we handle the error case in the component directly
+  if (error) {
+    return (
+      <ErrorPage
+        category="Error"
+        title="Schema cannot be displayed"
+        message={
+          <>
+            <DeveloperHint className="mb-4">
+              Check your configuration value <InlineCode>apis.type</InlineCode>{" "}
+              and <InlineCode>apis.input</InlineCode> in the Zudoku config.
+            </DeveloperHint>
+            An error occurred while trying to fetch the API reference:
+            <SyntaxHighlight code={error.toString()} language="plain" />
+          </>
+        }
+      />
+    );
+  }
+
   if (!result.data) return null;
 
   return (
     <div className="pt-[--padding-content-top]">
-      <div className={cn(ProseClasses, "mb-16")}>
+      <div
+        className={cn(
+          SchemaProseClasses,
+          "mb-16 max-w-full prose-img:max-w-prose",
+        )}
+      >
         <CategoryHeading>Overview</CategoryHeading>
         <Heading level={1} id="description" registerSidebarAnchor>
           {result.data.schema.title}
@@ -108,17 +142,19 @@ export const OperationList = () => {
             {tag.name && <CategoryHeading>{tag.name}</CategoryHeading>}
             {tag.description && (
               <Markdown
-                className={`${ProseClasses} mt-2 mb-12`}
+                className={`${SchemaProseClasses} mt-2 mb-12`}
                 content={tag.description}
               />
             )}
             <div className="operation mb-12">
-              {tag.operations.map((fragment) => (
-                <OperationListItem
-                  key={fragment.slug}
-                  operationFragment={fragment}
-                />
-              ))}
+              <StaggeredRender>
+                {tag.operations.map((fragment) => (
+                  <OperationListItem
+                    key={fragment.slug}
+                    operationFragment={fragment}
+                  />
+                ))}
+              </StaggeredRender>
             </div>
           </div>
         ))}