zudoku 0.3.0-dev.2 → 0.3.0-dev.20

package/lib/zudoku.plugin-redirect.js

@@ -0,0 +1,10 @@
+import { j as a, N as i } from "./index-PyGcnQFX.js";
+const m = (e) => ({
+  getRoutes: () => e.redirects.map(({ from: t, to: r, replace: s }) => ({
+    path: t,
+    element: /* @__PURE__ */ a.jsx(i, { to: r, replace: s })
+  }))
+});
+export {
+  m as redirectPlugin
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.3.0-dev.2",
+  "version": "0.3.0-dev.20",
   "type": "module",
   "files": [
     "dist",
@@ -27,8 +27,17 @@
     "./auth/openid": {
       "import": "./lib/zudoku.auth-openid.js"
     },
-    "./plugins": {
-      "import": "./lib/zudoku.plugins.js"
+    "./plugins/api-keys": {
+      "import": "./lib/zudoku.plugin-api-keys.js"
+    },
+    "./plugins/markdown": {
+      "import": "./lib/zudoku.plugin-markdown.js"
+    },
+    "./plugins/openapi": {
+      "import": "./lib/zudoku.plugin-openapi.js"
+    },
+    "./plugins/redirect": {
+      "import": "./lib/zudoku.plugin-redirect.js"
     },
     "./openapi-worker": {
       "import": "./lib/zudoku.openapi-worker.js"
@@ -53,6 +62,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",
@@ -96,10 +106,12 @@
     "remark-frontmatter": "5.0.0",
     "remark-gfm": "4.0.0",
     "remark-mdx-frontmatter": "5.0.0",
+    "rollup": "^4.18.1",
     "semver": "7.6.2",
     "slugify": "1.6.6",
     "strip-ansi": "7.1.0",
     "tailwindcss": "3.4.4",
+    "tiny-invariant": "1.3.3",
     "ulidx": "^2.3.0",
     "unist-util-visit": "5.0.0",
     "urql": "4.1.0",
@@ -116,12 +128,12 @@
     "@types/express": "^4.17.21",
     "@types/har-format": "^1.2.15",
     "@types/json-schema": "7.0.15",
-    "@types/loglevel": "^1.6.3",
     "@types/mdx": "2.0.13",
     "@types/node": "20.12.10",
     "@types/object-hash": "^3.0.6",
     "@types/react": "18.3.3",
     "@types/react-dom": "18.3.0",
+    "@types/rollup": "^0.54.0",
     "@types/semver": "^7.5.8",
     "@types/yargs": "^17.0.32",
     "@zudoku/httpsnippet": "10.0.9",
@@ -134,6 +146,7 @@
     "react-helmet-async": "2.0.5",
     "react-markdown": "9.0.1",
     "react-router-dom": "6.24.1",
+    "rollup-plugin-visualizer": "^5.12.0",
     "tailwind-merge": "2.3.0",
     "typescript": "5.5.3",
     "zustand": "4.5.4"

package/src/app/App.tsx

@@ -19,21 +19,25 @@ 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}
+      mdxComponents={config.mdx?.components}
       plugins={[
         ...configuredDocsPlugins,
         ...configuredApiPlugins,
-        configuredApiKeysPlugin,
         configuredRedirectPlugin,
+        ...(configuredApiKeysPlugin ? [configuredApiKeysPlugin] : []),
+        ...(configuredAuthProvider ? [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/authentication/hook.ts

@@ -8,6 +8,7 @@ export const useAuth = () => {
 
   return {
     isAuthEnabled,
+    isPending: authState.isPending,
     profile: authState.profile,
     isAuthenticated: authState.profile,
 

package/src/lib/authentication/providers/auth0.tsx

@@ -7,6 +7,7 @@ class Auth0AuthenticationProvider extends OpenIDAuthenticationProvider {
   override async logout(): Promise<void> {
     useAuthState.setState({
       isAuthenticated: false,
+      isPending: false,
       profile: undefined,
     });
     const as = await this.getAuthServer();

package/src/lib/authentication/providers/clerk.tsx

@@ -34,6 +34,7 @@ const clerkAuth: AuthenticationProviderInitializer<
       if (clerkApi.session) {
         useAuthState.setState({
           isAuthenticated: true,
+          isPending: false,
           profile: {
             sub: clerkApi.session.user.id,
             name: clerkApi.session.user.fullName ?? undefined,
@@ -46,6 +47,7 @@ const clerkAuth: AuthenticationProviderInitializer<
       } else {
         useAuthState.setState({
           isAuthenticated: false,
+          isPending: false,
           profile: undefined,
         });
       }

package/src/lib/authentication/providers/openid.tsx

@@ -180,6 +180,7 @@ export class OpenIDAuthenticationProvider implements AuthenticationProvider {
   async logout(): Promise<void> {
     useAuthState.setState({
       isAuthenticated: false,
+      isPending: false,
       profile: undefined,
     });
 
@@ -293,6 +294,7 @@ export class OpenIDAuthenticationProvider implements AuthenticationProvider {
 
     useAuthState.setState({
       isAuthenticated: true,
+      isPending: false,
       profile,
     });
 

package/src/lib/authentication/state.ts

@@ -1,11 +1,13 @@
 import { create } from "zustand";
 
 export const useAuthState = create<AuthState>(() => ({
+  isPending: true,
   isAuthenticated: false,
 }));
 
 export interface AuthState {
   isAuthenticated: boolean;
+  isPending: boolean;
   profile?: UserProfile;
 }
 

package/src/lib/components/DevPortal.tsx

@@ -1,24 +1,17 @@
-/* eslint-disable react/destructuring-assignment */
 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";
@@ -33,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],
@@ -65,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

@@ -1,4 +1,4 @@
-import { MoonStarIcon, SearchIcon, SunIcon } from "lucide-react";
+import { MoonStarIcon, SunIcon } from "lucide-react";
 import { memo } from "react";
 
 import { useAuth } from "../authentication/hook.js";
@@ -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,16 +18,16 @@ 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">
             <div className="w-full max-w-prose">
-              <button className="flex items-center border border-input hover:bg-accent hover:text-accent-foreground p-4 relative h-8 justify-start rounded-lg bg-background text-sm text-muted-foreground shadow-none w-40 sm:w-72">
+              {/*<button className="flex items-center border border-input hover:bg-accent hover:text-accent-foreground p-4 relative h-8 justify-start rounded-lg bg-background text-sm text-muted-foreground shadow-none w-40 sm:w-72">
                 <div className="flex items-center gap-2 flex-grow">
                   <SearchIcon size={14} />
                   Search
@@ -35,26 +35,29 @@ export const Header = memo(function HeaderInner() {
                 <kbd className="absolute right-[0.3rem] top-[0.3rem] hidden h-5 select-none items-center gap-1 rounded border border-border bg-muted px-1.5 font-mono text-[11px] font-medium opacity-100 sm:flex">
                   ⌘K
                 </kbd>
-              </button>
+              </button>*/}
             </div>
 
             <div className="items-center justify-self-end text-sm hidden lg:flex">
-              {isAuthenticated ? (
-                <button
-                  className="cursor-pointer hover:bg-secondary p-1 px-2 mx-2 rounded text-nowrap"
-                  onClick={logout}
-                >
-                  Logout {profile?.email ? `(${profile.email})` : null}
-                </button>
-              ) : (
-                <button
-                  className="cursor-pointer hover:bg-secondary p-1 px-2 mx-2 rounded"
-                  onClick={login}
-                >
-                  Login
-                </button>
+              {isAuthEnabled && (
+                <>
+                  {isAuthenticated ? (
+                    <button
+                      className="cursor-pointer hover:bg-secondary p-1 px-2 mx-2 rounded text-nowrap"
+                      onClick={logout}
+                    >
+                      Logout {profile?.email ? `(${profile.email})` : null}
+                    </button>
+                  ) : (
+                    <button
+                      className="cursor-pointer hover:bg-secondary p-1 px-2 mx-2 rounded"
+                      onClick={login}
+                    >
+                      Login
+                    </button>
+                  )}
+                </>
               )}
-
               <button
                 className="cursor-pointer hover:bg-secondary p-2.5 -m-2.5 rounded-full"
                 onClick={toggleTheme}

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} />
@@ -48,7 +48,7 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
         >
           <SideNavigation />
           <main
-            className="dark:border-white/10 translate-x-0
+            className="dark:border-white/10 translate-x-0 h-full
           lg:overflow-visible
           lg:peer-data-[navigation=true]:w-[calc(100%-var(--side-nav-width))]
           lg:peer-data-[navigation=true]:translate-x-[--side-nav-width] peer-data-[navigation=true]:pl-12"

package/src/lib/components/SyntaxHighlight.tsx

@@ -21,6 +21,10 @@ if (!import.meta.env.SSR) {
   import("prismjs/components/prism-json.min.js");
   // @ts-expect-error This is untyped
   import("prismjs/components/prism-java.min.js");
+  // @ts-expect-error This is untyped
+  import("prismjs/components/prism-csharp.min.js");
+  // @ts-expect-error This is untyped
+  import("prismjs/components/prism-objectivec.min.js");
 }
 
 import { useState } from "react";
@@ -67,7 +71,7 @@ export const SyntaxHighlight = ({
               disabled={isCopied}
               onClick={() => {
                 setIsCopied(true);
-                navigator.clipboard.writeText(
+                void navigator.clipboard.writeText(
                   tokens
                     .map((line) => line.map(({ content }) => content).join(""))
                     .join("\n"),

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/components/index.ts

@@ -1,3 +1,6 @@
+import { Callout } from "../ui/Callout.js";
+
 export { useMDXComponents } from "@mdx-js/react";
 export { DevPortal } from "./DevPortal.js";
 export { Link } from "./Link.js";
+export { Callout };

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,28 +65,59 @@ 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;
   }
 
   initialize = async () => {
-    this.plugins
-      .filter(needsInitialization)
-      .forEach((plugin) => plugin.initialize(this));
+    await Promise.all([
+      this.plugins
+        .filter(needsInitialization)
+        .map((plugin) => plugin.initialize?.(this)),
+    ]);
   };
 
   invalidateCache = async (key: DevPortalCacheKey[]) => {

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/{api-key → api-keys}/CreateApiKey.tsx

@@ -12,17 +12,11 @@ import {
   SelectValue,
 } from "../../components/Select.js";
 import { Button } from "../../ui/Button.js";
-import { type ApiKeyPluginOptions, ApiKeyService } from "./index.js";
+import { ApiKeyService } from "./index.js";
 
 type CreateApiKey = { description: string; expiresOn?: string };
 
-export const CreateApiKey = ({
-  options,
-  service,
-}: {
-  options: ApiKeyPluginOptions;
-  service: ApiKeyService;
-}) => {
+export const CreateApiKey = ({ service }: { service: ApiKeyService }) => {
   const context = useDevPortal();
   const navigate = useNavigate();
   const form = useForm<CreateApiKey>({