zudoku 0.3.0-dev.10 → 0.3.0-dev.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.3.0-dev.10",
+  "version": "0.3.0-dev.12",
   "type": "module",
   "files": [
     "dist",
@@ -53,6 +53,7 @@
     }
   },
   "dependencies": {
+    "@envelop/core": "5.0.1",
     "@graphql-typed-document-node/core": "3.2.0",
     "@lekoarts/rehype-meta-as-attributes": "3.0.1",
     "@mdx-js/react": "3.0.1",

package/src/app/App.tsx

@@ -19,13 +19,15 @@ import { DevPortal } from "zudoku/components";
 export default function App() {
   return (
     <DevPortal
-      meta={{
-        headerTitle: config.ui?.headerTitle ?? "Developer Portal",
-        pageTitle: config.ui?.pageTitle ?? "%s | Dev Portal",
-        logo: config.ui?.logo ?? "https://cdn.zuplo.com/www/favicon.png",
-        favicon:
-          config.ui?.metadata?.favicon ??
-          "https://cdn.zuplo.com/www/favicon.png",
+      page={{
+        logo: config.page?.logo ?? "https://cdn.zuplo.com/www/favicon.png",
+        pageTitle: "Developer Portal",
+        ...config.page,
+      }}
+      metadata={{
+        favicon: "https://cdn.zuplo.com/www/favicon.png",
+        title: "%s | Developer Portal",
+        ...config.metadata,
       }}
       navigation={config.navigation ?? []}
       authentication={configuredAuthProvider}

package/src/lib/authentication/authentication.ts

@@ -1,9 +1,6 @@
-import {
-  InitializationPlugin,
-  NavigationPlugin,
-} from "../../lib/core/plugins.js";
+import { CommonPlugin, NavigationPlugin } from "../../lib/core/plugins.js";
 
-type AuthenticationPlugin = NavigationPlugin & InitializationPlugin;
+type AuthenticationPlugin = NavigationPlugin & CommonPlugin;
 
 export interface AuthenticationProvider extends AuthenticationPlugin {
   login(): Promise<void>;

package/src/lib/components/DevPortal.tsx

@@ -1,23 +1,17 @@
 import { MDXProvider } from "@mdx-js/react";
 import { QueryClientProvider } from "@tanstack/react-query";
-import { memo, Suspense, useEffect, useMemo } from "react";
+import { Fragment, memo, Suspense, useEffect, useMemo } from "react";
 import {
   DevPortalContext,
   queryClient,
-  type NavigationItem,
+  ZudokuContextOptions,
 } from "../core/DevPortalContext.js";
-import { HelmetProvider } from "../core/helmet.js";
-import { type DevPortalPlugin } from "../core/plugins.js";
-
-import { AuthenticationProvider } from "../authentication/authentication.js";
-import {
-  MdxComponents,
-  type MdxComponentsType,
-} from "../util/MdxComponents.js";
+import { Helmet, HelmetProvider } from "../core/helmet.js";
+import { hasHead } from "../core/plugins.js";
+import { MdxComponents } from "../util/MdxComponents.js";
 import {
   ComponentsProvider,
   DEFAULT_COMPONENTS,
-  type ComponentsContextType,
 } from "./context/ComponentsContext.js";
 import { DevPortalProvider } from "./context/DevPortalProvider.js";
 import { ThemeProvider } from "./context/ThemeContext.js";
@@ -32,22 +26,7 @@ export type DevPortalPath =
   | string
   | (typeof DevPortalSystemPaths)[keyof typeof DevPortalSystemPaths];
 
-export type DevPortalProps = {
-  meta?: Partial<{
-    headerTitle: string;
-    pageTitle: string;
-    description: string;
-    logo: string;
-    favicon: string;
-  }>;
-  authentication?: AuthenticationProvider;
-  navigation: NavigationItem[];
-  plugins?: DevPortalPlugin[];
-  mdxComponents?: MdxComponentsType;
-  overrides?: ComponentsContextType;
-};
-
-const DevPortalInner = (props: DevPortalProps) => {
+const DevPortalInner = (props: ZudokuContextOptions) => {
   const components = useMemo(
     () => ({ ...DEFAULT_COMPONENTS, ...props.overrides }),
     [props.overrides],
@@ -64,9 +43,15 @@ const DevPortalInner = (props: DevPortalProps) => {
     void devPortalContext.initialize();
   }, [devPortalContext]);
 
+  const heads = props.plugins
+    ?.filter(hasHead)
+    // eslint-disable-next-line react/no-array-index-key
+    .map((plugin, i) => <Fragment key={i}>{plugin.getHead?.()}</Fragment>);
+
   return (
     <QueryClientProvider client={queryClient}>
       <HelmetProvider>
+        <Helmet>{heads}</Helmet>
         <DevPortalProvider value={devPortalContext}>
           <MDXProvider components={mdxComponents}>
             <ThemeProvider>

package/src/lib/components/Header.tsx

@@ -9,7 +9,7 @@ import { useTheme } from "./context/ThemeContext.js";
 export const Header = memo(function HeaderInner() {
   const [isDark, toggleTheme] = useTheme();
   const { isAuthenticated, profile, isAuthEnabled, login, logout } = useAuth();
-  const { meta } = useDevPortal();
+  const { page } = useDevPortal();
 
   const ThemeIcon = isDark ? MoonStarIcon : SunIcon;
 
@@ -18,11 +18,11 @@ export const Header = memo(function HeaderInner() {
       <div className="max-w-screen-2xl mx-auto">
         <div className="grid grid-cols-[calc(var(--side-nav-width))_1fr] lg:gap-12 items-center border-b border-border px-12 h-[--top-header-height]">
           <div className="flex items-center gap-3.5">
-            {meta?.logo && (
-              <img src={meta.logo} alt="My Dev Portal" className="h-10" />
+            {page?.logo && (
+              <img src={page.logo} alt={page.pageTitle} className="h-10" />
             )}
             <span className="font-bold text-2xl text-foreground/85 tracking-wide">
-              {meta?.headerTitle}
+              {page?.pageTitle}
             </span>
           </div>
           <div className="grid grid-cols-[--sidecar-grid-cols] items-center gap-8">

package/src/lib/components/Heading.tsx

@@ -1,7 +1,24 @@
-import { type ReactNode } from "react";
-import { cn } from "../util/cn.js";
+import React, { type ReactNode } from "react";
 import { useRegisterAnchorElement } from "./context/ViewportAnchorContext.js";
 
+import { cva, type VariantProps } from "class-variance-authority";
+
+const heading = cva("group relative", {
+  variants: {
+    level: {
+      6: "text-md",
+      5: "text-lg",
+      4: "text-xl",
+      3: "text-xl font-semibold",
+      2: "text-2xl font-bold",
+      1: "text-4xl font-extrabold",
+    },
+  },
+  defaultVariants: {
+    level: 1,
+  },
+});
+
 const getComponent = (level: number) => {
   switch (level) {
     case 1:
@@ -21,27 +38,29 @@ const getComponent = (level: number) => {
   }
 };
 
-export type HeadingProps = {
+export interface HeadingProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof heading> {
   children: ReactNode;
   className?: string;
   id?: string;
   level?: 1 | 2 | 3 | 4 | 5 | 6;
   registerSidebarAnchor?: boolean;
-};
+}
 
-export const Heading = ({
+export const Heading: React.FC<HeadingProps> = ({
   level,
   children,
   id,
   className,
   registerSidebarAnchor,
-}: HeadingProps) => {
+}) => {
   const Component = getComponent(level ?? 1);
   const { ref } = useRegisterAnchorElement();
 
   return (
     <Component
-      className={cn("group relative", className)}
+      className={heading({ className, level })}
       ref={registerSidebarAnchor ? ref : undefined}
       id={id}
     >

package/src/lib/components/Layout.tsx

@@ -29,7 +29,7 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
 
   return (
     <>
-      <Helmet titleTemplate={meta?.pageTitle}>
+      <Helmet titleTemplate={meta?.title}>
         <title>Home</title>
         {meta?.description && (
           <meta name="description" content={meta.description} />

package/src/lib/components/context/DevPortalProvider.ts

@@ -1,4 +1,4 @@
-import { useSuspenseQuery } from "@tanstack/react-query";
+import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
 import { createContext, useContext } from "react";
 import { matchPath, useLocation } from "react-router-dom";
 import { DevPortalContext } from "../../core/DevPortalContext.js";
@@ -21,7 +21,7 @@ export const useDevPortal = () => {
 
 export const useApiIdentities = () => {
   const { getApiIdentities } = useDevPortal();
-  return useSuspenseQuery({
+  return useQuery({
     queryFn: getApiIdentities,
     queryKey: ["api-identities"],
   });

package/src/lib/core/DevPortalContext.ts

@@ -2,16 +2,15 @@ import { QueryClient } from "@tanstack/react-query";
 import { type ReactNode } from "react";
 import { create } from "zustand";
 import { type AuthenticationProvider } from "../authentication/authentication.js";
+import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
+import { type DevPortalPath } from "../components/DevPortal.js";
+import type { MdxComponentsType } from "../util/MdxComponents.js";
 import {
-  type DevPortalPath,
-  type DevPortalProps,
-} from "../components/DevPortal.js";
-import {
+  type DevPortalPlugin,
   isApiIdentityPlugin,
   isNavigationPlugin,
-  needsInitialization,
-  type DevPortalPlugin,
   type NavigationPlugin,
+  needsInitialization,
 } from "./plugins.js";
 
 export interface ApiIdentity {
@@ -66,21 +65,50 @@ export const useRoutingState = create<RoutingState>(() => ({}));
 export type ApiKeyCache = "api-keys";
 export type DevPortalCacheKey = ApiKeyCache | string;
 
+export type ZudokuContextMetadataOptions = Partial<{
+  title: string;
+  description: string;
+  logo: string;
+  favicon: string;
+  generator: string;
+  applicationName: string;
+  referrer: string;
+  keywords: string[];
+  authors: string[];
+  creator: string;
+  publisher: string;
+}>;
+export type ZudokuContextPageOptions = Partial<{
+  pageTitle?: string;
+  logo?: string;
+}>;
+export type ZudokuContextOptions = {
+  metadata?: ZudokuContextMetadataOptions;
+  page?: ZudokuContextPageOptions;
+  authentication?: AuthenticationProvider;
+  navigation: NavigationItem[];
+  plugins?: DevPortalPlugin[];
+  mdxComponents?: MdxComponentsType;
+  overrides?: ComponentsContextType;
+};
+
 export class DevPortalContext {
   private plugins: DevPortalPlugin[] = [];
   private navigationPlugins: NavigationPlugin[];
 
   public navigation: NavigationItem[];
-  public meta: DevPortalProps["meta"];
+  public meta: ZudokuContextOptions["metadata"];
+  public page: ZudokuContextOptions["page"];
   public authentication?: AuthenticationProvider;
   public state: typeof useRoutingState;
 
-  constructor(config: DevPortalProps) {
+  constructor(config: ZudokuContextOptions) {
     this.plugins = config.plugins ?? [];
     this.navigation = config.navigation;
     this.navigationPlugins = this.plugins.filter(isNavigationPlugin);
     this.authentication = config.authentication;
-    this.meta = config.meta;
+    this.meta = config.metadata;
+    this.page = config.page;
     this.state = useRoutingState;
   }
 
@@ -88,7 +116,7 @@ export class DevPortalContext {
     await Promise.all([
       this.plugins
         .filter(needsInitialization)
-        .map((plugin) => plugin.initialize(this)),
+        .map((plugin) => plugin.initialize?.(this)),
     ]);
   };
 

package/src/lib/core/plugins.ts

@@ -1,3 +1,4 @@
+import { type ReactElement } from "react";
 import { type RouteObject } from "react-router-dom";
 import {
   DevPortalContext,
@@ -10,9 +11,9 @@ export type PluginNavigationCategory = {
 } & NavigationCategory;
 
 export type DevPortalPlugin =
+  | CommonPlugin
   | NavigationPlugin
-  | ApiIdentityPlugin
-  | InitializationPlugin;
+  | ApiIdentityPlugin;
 
 export interface NavigationPlugin {
   getRoutes: () => RouteObject[];
@@ -23,8 +24,9 @@ export interface ApiIdentityPlugin {
   getIdentities: (context: DevPortalContext) => Promise<ApiIdentity[]>;
 }
 
-export interface InitializationPlugin {
-  initialize: (context: DevPortalContext) => Promise<void> | void;
+export interface CommonPlugin {
+  initialize?: (context: DevPortalContext) => Promise<void> | void;
+  getHead?: () => ReactElement | undefined;
 }
 
 export const isNavigationPlugin = (
@@ -34,9 +36,12 @@ export const isNavigationPlugin = (
 
 export const needsInitialization = (
   obj: DevPortalPlugin,
-): obj is InitializationPlugin =>
+): obj is CommonPlugin =>
   "initialize" in obj && typeof obj.initialize === "function";
 
+export const hasHead = (obj: DevPortalPlugin): obj is CommonPlugin =>
+  "getHead" in obj && typeof obj.getHead === "function";
+
 export const isApiIdentityPlugin = (
   obj: DevPortalPlugin,
 ): obj is ApiIdentityPlugin =>

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

@@ -45,7 +45,7 @@ export const slugifyOperation = (operation: OperationLike, tag?: string) => {
   );
 };
 
-const cache = new LRUCache<string, OpenAPIDocument>({
+const cache = new LRUCache<string, Promise<OpenAPIDocument>>({
   ttl: 60 * 10 * 1000,
   ttlAutopurge: true,
 });
@@ -384,7 +384,7 @@ const loadOpenAPISchema = async (input: NonNullable<unknown>) => {
     return cache.get(hash)!;
   }
 
-  const schema = await validate(input);
+  const schema = validate(input);
 
   cache.set(hash, schema);
 

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

@@ -54,7 +54,9 @@ const parseSchemaInput = async (
       return JSON.parse(schemaInput);
     }
     if (schemaInput.includes("://")) {
-      const response = await fetch(schemaInput);
+      const response = await fetch(schemaInput, {
+        cache: "force-cache",
+      });
       return (await response.json()) as JSONSchema;
     }
     const yaml = await import("yaml");

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

@@ -12,7 +12,7 @@ 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 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>
+          </>
+        )}
       </div>
       <div className="hidden xl:block">
         {showToc && <Toc entries={tocEntries} />}

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

@@ -3,10 +3,14 @@ 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]) => {
@@ -28,7 +32,13 @@ export const generateRoutes = (
           const { default: Component, ...props } = await importPromise();
 
           return {
-            element: <MdxPage mdxComponent={Component} {...props} />,
+            element: (
+              <MdxPage
+                mdxComponent={Component}
+                {...props}
+                defaultOptions={defaultOptions}
+              />
+            ),
           };
         },
       } satisfies RouteObject;

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,11 @@ export type MDXImport = {
 
 export const markdownPlugin = ({
   markdownFiles,
+  defaultOptions,
 }: MarkdownPluginOptions): DevPortalPlugin => {
   return {
     getRoutes() {
-      return generateRoutes(markdownFiles);
+      return generateRoutes(markdownFiles, defaultOptions);
     },
   };
 };

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

@@ -1,11 +1,12 @@
 import { ResultOf } from "@graphql-typed-document-node/core";
 import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
-import { Markdown, ProseClasses } from "../../components/Markdown.js";
+import { Markdown } from "../../components/Markdown.js";
 import { cn } from "../../util/cn.js";
 import { OperationListItem } from "./OperationListItem.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 */ `
@@ -94,7 +95,12 @@ export const OperationList = () => {
 
   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,7 +114,7 @@ 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}
               />
             )}