zudoku 0.0.2-dev.0

package/src/app/Heading.tsx

@@ -0,0 +1,60 @@
+import { type ReactNode } from "react";
+import { useRegisterAnchorElement } from "./components/context/ViewportAnchorContext.js";
+import { cn } from "./util/cn.js";
+
+const getComponent = (level: number) => {
+  switch (level) {
+    case 1:
+      return "h1";
+    case 2:
+      return "h2";
+    case 3:
+      return "h3";
+    case 4:
+      return "h4";
+    case 5:
+      return "h5";
+    case 6:
+      return "h6";
+    default:
+      return "h1";
+  }
+};
+
+export type HeadingProps = {
+  children: ReactNode;
+  className?: string;
+  id?: string;
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  registerSidebarAnchor?: boolean;
+};
+
+export const Heading = ({
+  level,
+  children,
+  id,
+  className,
+  registerSidebarAnchor,
+}: HeadingProps) => {
+  const Component = getComponent(level ?? 1);
+  const { ref } = useRegisterAnchorElement();
+
+  return (
+    <Component
+      className={cn("group relative", className)}
+      ref={registerSidebarAnchor ? ref : undefined}
+      id={id}
+    >
+      {id && (
+        <a
+          href={`#${id}`}
+          className="no-underline absolute text-primary -left-[0.8em] pr-2.5 opacity-0 group-hover:opacity-50 hover:!opacity-100 transition-opacity duration-200"
+          aria-label={`Link to ${id}`}
+        >
+          #
+        </a>
+      )}
+      {children}
+    </Component>
+  );
+};

package/src/app/app.tsx

@@ -0,0 +1,85 @@
+import "./main.css";
+
+import DevPortal from "./DevPortal.js";
+import { markdownPlugin } from "./plugins/markdown/index.js";
+import { openApiPlugin } from "./plugins/openapi/index.js";
+
+import config from "./config.js";
+
+// async function getAuthProvider(authConfig: AuthenticationConfig) {
+//   if (authConfig.type === "clerk") {
+//     const clerkProvider = await import("./authentication/clerk.js");
+//     return clerkProvider(authConfig);
+//   } else {
+//     throw new Error(
+//       `The authentication type "${authConfig.type}" is not supported.`,
+//     );
+//   }
+//   //openIdAuth({
+//   //   clientId: oauth.client_id,
+//   //   authorizationEndpoint: oauth.authorize_url,
+//   //   tokenEndpoint: oauth.token_fetch_url,
+//   // })
+// }
+
+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",
+      }}
+      navigation={config.navigation ?? []}
+      // authentication={
+      //   config.authentication
+      //     ? getAuthProvider(config.authentication)
+      //     : undefined
+      // }
+      plugins={[
+        ...(config.docs
+          ? Array.isArray(config.docs)
+            ? config.docs
+            : [config.docs]
+          : []
+        ).map((docs) =>
+          markdownPlugin({
+            markdownFiles: docs?.files ?? {},
+          }),
+        ),
+        ...(config.apis
+          ? Array.isArray(config.apis)
+            ? config.apis
+            : [config.apis]
+          : []
+        ).map((api) => openApiPlugin(api)),
+
+        // apiKeyPlugin({
+        //   // consumerEndpoint:
+        //   //   "https://zudoku-customer-main-b36fa2f.d2.zuplo.dev/v1/developer/api-keys",
+        //   getConsumers: async (ctx) => {
+        //     const accessToken = await ctx.authentication?.getToken?.(ctx);
+
+        //     if (!accessToken) {
+        //       return;
+        //     }
+
+        //     const consumers = await fetch(
+        //       "https://zudoku-customer-main-b36fa2f.d2.zuplo.dev/v1/developer/api-keys",
+        //       {
+        //         headers: {
+        //           Authorization: `Bearer ${accessToken}`,
+        //         },
+        //       },
+        //     );
+
+        //     return { consumers: [await consumers.json()] };
+        //   },
+        // }),
+      ]}
+    />
+  );
+}

package/src/app/authentication/authentication.ts

@@ -0,0 +1,18 @@
+import { DevPortalContext } from "../core/DevPortalContext.js";
+
+export interface AuthProvider {
+  initialize(context: DevPortalContext): Promise<unknown>;
+  login(context: DevPortalContext): Promise<unknown>;
+  getToken?: (context: DevPortalContext) => Promise<string | undefined>;
+  handleAuthenticationResponse?: (
+    path: Path,
+    context: DevPortalContext,
+  ) => Promise<unknown>;
+  signOut(context: DevPortalContext): void;
+}
+
+export type Path = {
+  pathname: string;
+  search: string;
+  hash: string;
+};

package/src/app/authentication/clerk.ts

@@ -0,0 +1,47 @@
+import { Clerk } from "@clerk/clerk-js";
+import { type AuthProvider } from "./authentication.js";
+
+const clerkProvider = ({
+  clerkPubKey,
+}: {
+  clerkPubKey: string;
+}): AuthProvider => {
+  const clerkApi = new Clerk(clerkPubKey);
+
+  const clerkIsLoaded = clerkApi.load({});
+
+  return {
+    initialize: async (context) => {
+      await clerkIsLoaded;
+
+      if (clerkApi.session) {
+        await context.setUserProfile({
+          isLoggedIn: true,
+          name: clerkApi.session.user.fullName ?? undefined,
+          email:
+            clerkApi.session.user.emailAddresses.at(0)?.emailAddress ??
+            undefined,
+        });
+      } else {
+        await context.setUserProfile({
+          isLoggedIn: false,
+        });
+      }
+    },
+
+    getToken: async () => {
+      await clerkIsLoaded;
+      const token = await clerkApi.session?.getToken();
+      return token ?? undefined;
+    },
+
+    signOut() {
+      clerkApi.signOut();
+    },
+    login: async () => {
+      await clerkApi.redirectToSignIn();
+    },
+  };
+};
+
+export default clerkProvider;

package/src/app/authentication/openid.ts

@@ -0,0 +1,192 @@
+import * as oauth from "oauth4webapi";
+import { DevPortalContext } from "../core/DevPortalContext.js";
+import { type AuthProvider } from "./authentication.js";
+const algorithm = "oauth2";
+
+const getAuthServerByIssuer = async (issuer: string) => {
+  const authorizationServer = await oauth
+    .discoveryRequest(new URL(issuer), { algorithm })
+    .then((response) =>
+      oauth.processDiscoveryResponse(new URL(issuer), response),
+    );
+
+  return authorizationServer;
+};
+
+export type AuthServerOption = {
+  issuer?: string;
+  authorizationEndpoint?: string;
+  tokenEndpoint?: string;
+};
+
+const getAuthServer = async ({
+  issuer,
+  authorizationEndpoint,
+  tokenEndpoint,
+}: AuthServerOption) => {
+  return issuer
+    ? await getAuthServerByIssuer(issuer)
+    : ({
+        issuer: new URL(authorizationEndpoint!).origin,
+        authorization_endpoint: authorizationEndpoint,
+        token_endpoint: tokenEndpoint,
+        code_challenge_methods_supported: [],
+      } satisfies oauth.AuthorizationServer);
+};
+
+export const openIdAuth = ({
+  clientId,
+  clientSecret,
+  issuer,
+  authorizationEndpoint,
+  tokenEndpoint,
+}: {
+  clientId: string;
+  clientSecret?: string;
+  audience?: string;
+} & AuthServerOption): AuthProvider => {
+  const client: oauth.Client = {
+    client_id: clientId,
+    client_secret: clientSecret,
+    token_endpoint_auth_method: "none",
+  };
+
+  const redirect_uri = "http://localhost:5173/oauth/callback";
+
+  return {
+    initialize() {
+      return Promise.resolve();
+    },
+    signOut() {},
+    login: async (context: DevPortalContext) => {
+      const code_challenge_method = "S256";
+      const authorizationServer = await getAuthServer({
+        issuer,
+        authorizationEndpoint,
+        tokenEndpoint,
+      });
+
+      if (!authorizationServer.authorization_endpoint) {
+        throw new Error("No authorization endpoint");
+      }
+
+      /**
+       * The following MUST be generated for every redirect to the authorization_endpoint. You must store
+       * the codeVerifier and nonce in the end-user session such that it can be recovered as the user
+       * gets redirected from the authorization server back to your application.
+       */
+      const codeVerifier = oauth.generateRandomCodeVerifier();
+      const codeChallenge =
+        await oauth.calculatePKCECodeChallenge(codeVerifier);
+
+      await context.sessionStorage.set("codeVerifier", codeVerifier);
+
+      // redirect user to as.authorization_endpoint
+      const authorizationUrl = new URL(
+        authorizationServer.authorization_endpoint,
+      );
+      authorizationUrl.searchParams.set("client_id", client.client_id);
+      authorizationUrl.searchParams.set("redirect_uri", redirect_uri);
+      authorizationUrl.searchParams.set("response_type", "code");
+      // authorizationUrl.searchParams.set("scope", "api:read");
+      authorizationUrl.searchParams.set("code_challenge", codeChallenge);
+      authorizationUrl.searchParams.set(
+        "code_challenge_method",
+        code_challenge_method,
+      );
+
+      /**
+       * We cannot be sure the AS supports PKCE so we're going to use state too. Use of PKCE is
+       * backwards compatible even if the AS doesn't support it which is why we're using it regardless.
+       */
+      if (
+        authorizationServer.code_challenge_methods_supported?.includes(
+          "S256",
+        ) !== true
+      ) {
+        const state = oauth.generateRandomState();
+        authorizationUrl.searchParams.set("state", state);
+      }
+
+      // now redirect the user to authorizationUrl.href
+      location.href = authorizationUrl.href;
+    },
+
+    handleAuthenticationResponse: async ({ search }, { sessionStorage }) => {
+      const searchParams = new URLSearchParams(search);
+      const state = searchParams.get("state");
+      if (!state) {
+        return;
+      }
+
+      // one eternity later, the user lands back on the redirect_uri
+      // Authorization Code Grant Request & Response
+      const codeVerifier = await sessionStorage.get("codeVerifier");
+
+      if (!codeVerifier) {
+        return;
+      }
+
+      const as = await getAuthServer({
+        issuer,
+        authorizationEndpoint,
+        tokenEndpoint,
+      });
+
+      const params = oauth.validateAuthResponse(
+        as,
+        client,
+        searchParams,
+        state,
+      );
+      if (oauth.isOAuth2Error(params)) {
+        console.error("Error Response", params);
+        throw new Error(); // Handle OAuth 2.0 redirect error
+      }
+
+      const response = await oauth.authorizationCodeGrantRequest(
+        as,
+        client,
+        params,
+        redirect_uri,
+        codeVerifier,
+      );
+
+      // @todo do we need to do these
+      // const challenges = oauth.parseWwwAuthenticateChallenges(response);
+      // if (challenges) {
+      //   for (const challenge of challenges) {
+      //     console.error("WWW-Authenticate Challenge", challenge);
+      //   }
+      //   throw new Error(); // Handle WWW-Authenticate Challenges as needed
+      // }
+
+      const oauthResult = await oauth.processAuthorizationCodeOpenIDResponse(
+        as,
+        client,
+        response,
+      );
+      if (oauth.isOAuth2Error(oauthResult)) {
+        console.error("Error Response", oauthResult);
+        throw new Error(oauthResult.error);
+      }
+
+      const userInfoResponse = await oauth.userInfoRequest(
+        as,
+        client,
+        oauthResult.access_token,
+      );
+      const userInfo = await userInfoResponse.json();
+
+      // void storage.setProfile({
+      //   sub: userInfo.sub,
+      //   email: userInfo.email,
+      //   name: userInfo.name,
+      //   email_verified: userInfo.email_verified ?? false,
+      //   picture: userInfo.picture,
+      //   id_token: oauthResult.id_token,
+      //   access_token: oauthResult.access_token,
+      // });
+    },
+  };
+};

package/src/app/components/AnchorLink.tsx

@@ -0,0 +1,19 @@
+import React from "react";
+import { Link, type LinkProps, useLocation } from "react-router-dom";
+
+/**
+ * Link that scrolls to anchor even if the hash is already set in the URL.
+ */
+export const AnchorLink = (props: LinkProps) => {
+  const location = useLocation();
+  const hash = typeof props.to === "string" ? props.to : props.to.hash;
+
+  const handleClick = (event: React.MouseEvent<HTMLAnchorElement>) => {
+    if (!hash?.startsWith("#") || hash !== location.hash) return;
+
+    event.preventDefault();
+    document.getElementById(hash.slice(1))?.scrollIntoView();
+  };
+
+  return <Link onClick={handleClick} {...props} />;
+};

package/src/app/components/CategoryHeading.tsx

@@ -0,0 +1,16 @@
+import type { ReactNode } from "react";
+import { cx } from "class-variance-authority";
+
+export const CategoryHeading = ({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string;
+}) => {
+  return (
+    <div className={cx("text-sm font-semibold text-primary mb-2", className)}>
+      {children}
+    </div>
+  );
+};

package/src/app/components/DynamicIcon.tsx

@@ -0,0 +1,60 @@
+// import { type LucideProps } from "lucide-react";
+// import dynamicIconImports from "lucide-react/dynamicIconImports.js";
+// import { Suspense, lazy, memo } from "react";
+// import { cn } from "../util/cn.js";
+
+// export type IconName = keyof typeof dynamicIconImports;
+
+// const IconNames = Object.keys(dynamicIconImports) as IconName[];
+
+// export const isValidIcon = (name: unknown): name is IconName =>
+//   typeof name === "string" && IconNames.includes(name as IconName);
+
+// type IconProps = Omit<LucideProps, "ref"> & {
+//   name: IconName;
+//   inline?: boolean;
+// };
+
+// const Fallback = ({
+//   inline,
+//   size,
+// }: {
+//   inline?: boolean;
+//   size?: string | number;
+// }) => (
+//   <span
+//     className={cn(inline ? "inline-block" : "block", "bg-background")}
+//     style={{ height: size, width: size }}
+//     role="presentation"
+//   />
+// );
+
+// export const DynamicIcon = memo(function ({
+//   name,
+//   inline,
+//   className,
+//   size = 16,
+//   ...props
+// }: IconProps) {
+//   const LucideIcon = lazy(dynamicIconImports[name]);
+
+//   return (
+//     <Suspense fallback={<Fallback inline={inline} size={size} />}>
+//       <LucideIcon
+//         {...props}
+//         size={size}
+//         className={cn(inline && "inline-block align-[-0.125em]", className)}
+//       />
+//     </Suspense>
+//   );
+// });
+
+export type IconName = string;
+
+export function isValidIcon(name: unknown): name is IconName {
+  return true;
+}
+
+export const DynamicIcon = (props: { name: string; size?: number }) => (
+  <div></div>
+);

package/src/app/components/Header.tsx

@@ -0,0 +1,69 @@
+import { MoonStarIcon, SearchIcon, SunIcon } from "lucide-react";
+import { memo } from "react";
+import { useDevPortalState } from "../core/DevPortalContext.js";
+import { TopNavigation } from "./TopNavigation.js";
+import { useDevPortal } from "./context/DevPortalProvider.js";
+import { useTheme } from "./context/ThemeContext.js";
+
+export const Header = memo(() => {
+  const [isDark, toggleTheme] = useTheme();
+  const { isLoggedIn, email } = useDevPortalState();
+  const { login, logout, meta } = useDevPortal();
+
+  const ThemeIcon = isDark ? MoonStarIcon : SunIcon;
+
+  return (
+    <header className="fixed top-0 w-full z-10 bg-background/80 backdrop-blur">
+      <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" />
+            )}
+            <span className="font-bold text-2xl text-foreground/85 tracking-wide">
+              {meta?.headerTitle}
+            </span>
+          </div>
+          <div className="grid grid-cols-[--sidecar-grid-cols] items-center gap-8">
+            <div className="w-full max-w-prose mx-auto">
+              <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
+                </div>
+                <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>
+            </div>
+            <div className="items-center justify-self-end text-sm hidden lg:flex">
+              {!isLoggedIn ? (
+                <button
+                  className="cursor-pointer hover:bg-secondary p-1 px-2 mx-2 rounded"
+                  onClick={logout}
+                >
+                  Logout {email ? `(${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}
+              >
+                <ThemeIcon size={18} />
+              </button>
+            </div>
+          </div>
+        </div>
+        <TopNavigation />
+      </div>
+    </header>
+  );
+});

package/src/app/components/Layout.tsx

@@ -0,0 +1,56 @@
+import { Suspense, useEffect, useRef, type ReactNode } from "react";
+import { Outlet, useLocation } from "react-router-dom";
+import { Helmet } from "../core/helmet.js";
+import { useScrollToAnchor } from "../util/useScrollToAnchor.js";
+import { useScrollToTop } from "../util/useScrollToTop.js";
+import { Header } from "./Header.js";
+import { useDevPortal } from "./context/DevPortalProvider.js";
+import { useViewportAnchor } from "./context/ViewportAnchorContext.js";
+import { SideNavigation } from "./navigation/SideNavigation.js";
+import { SideNavigationWrapper } from "./navigation/SideNavigationWrapper.js";
+
+export const Layout = ({ children }: { children?: ReactNode }) => {
+  const location = useLocation();
+  const { setActiveAnchor } = useViewportAnchor();
+  const { meta, handleAuthenticationResponse } = useDevPortal();
+
+  useEffect(() => {
+    void handleAuthenticationResponse(location);
+  }, [handleAuthenticationResponse, location]);
+
+  useScrollToAnchor();
+  useScrollToTop();
+
+  const previousLocationPath = useRef(location.pathname);
+
+  useEffect(() => {
+    // always reset on location change
+    if (location.pathname !== previousLocationPath.current) {
+      setActiveAnchor("");
+    }
+    previousLocationPath.current = location.pathname;
+  }, [location.pathname, setActiveAnchor]);
+
+  return (
+    <>
+      <Helmet titleTemplate={meta?.pageTitle}>
+        <title>Home</title>
+        {meta?.description && (
+          <meta name="description" content={meta.description} />
+        )}
+        {meta?.favicon && <link rel="icon" href={meta.favicon} />}
+      </Helmet>
+      <Header />
+      <div className="max-w-screen-2xl mx-auto pt-[--header-height] px-10 lg:px-12">
+        <Suspense
+          fallback={<SideNavigationWrapper>Loading...</SideNavigationWrapper>}
+        >
+          <SideNavigation />
+        </Suspense>
+        <main className="dark:border-white/10 lg:overflow-visible translate-x-0 lg:w-[calc(100%-var(--side-nav-width))] lg:translate-x-[--side-nav-width] pl-12">
+          {children ?? <Outlet />}
+        </main>
+      </div>
+    </>
+  );
+};

package/src/app/components/Markdown.tsx

@@ -0,0 +1,37 @@
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import { visit } from "unist-util-visit";
+import { MdxComponents } from "../util/MdxComponents.js";
+
+// same as in packages/dev-portal/framework/vite.ts
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const rehypeCodeBlockPlugin = () => (tree: any) => {
+  visit(tree, "element", (node, _index, parent) => {
+    if (node.tagName === "code") {
+      node.properties.inline = parent?.tagName !== "pre";
+    }
+  });
+};
+
+const remarkPlugins = [remarkGfm];
+const rehypePlugins = [rehypeCodeBlockPlugin];
+
+// other styles are defined in main.css .prose
+export const ProseClasses = "prose dark:prose-invert prose-neutral";
+
+export const Markdown = ({
+  content,
+  className,
+}: {
+  content: string;
+  className?: string;
+}) => (
+  <ReactMarkdown
+    remarkPlugins={remarkPlugins}
+    rehypePlugins={rehypePlugins}
+    components={MdxComponents}
+    className={className}
+  >
+    {content}
+  </ReactMarkdown>
+);