zudoku 0.1.1-dev.17 → 0.1.1-dev.19

package/src/lib/Router.tsx

@@ -0,0 +1,28 @@
+import { useMemo } from "react";
+import { createBrowserRouter, RouterProvider } from "react-router-dom";
+import { Layout } from "./components/Layout.js";
+import { DevPortalPlugin, isNavigationPlugin } from "./core/plugins.js";
+
+export function Router({ plugins }: { plugins?: DevPortalPlugin[] }) {
+  const router = useMemo(() => {
+    const routes = (plugins ?? []).flatMap((plugin) =>
+      isNavigationPlugin(plugin) ? plugin.getRoutes() : [],
+    );
+
+    return createBrowserRouter([
+      {
+        path: "/",
+        element: <Layout />,
+        errorElement: (
+          <Layout>
+            <div className="h-[75vh] flex items-center justify-center">
+              Error, look at the console
+            </div>
+          </Layout>
+        ),
+        children: routes,
+      },
+    ]);
+  }, [plugins]);
+  return <RouterProvider router={router} />;
+}

package/src/lib/auth.ts

@@ -0,0 +1 @@
+export { clerkAuth } from "./authentication/clerk.js";

package/src/lib/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/lib/authentication/clerk.ts

@@ -0,0 +1,45 @@
+import { Clerk } from "@clerk/clerk-js";
+import { type AuthProvider } from "./authentication.js";
+
+export const clerkAuth = ({
+  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();
+    },
+  };
+};

package/src/lib/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/lib/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/lib/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/lib/components/Dialog.tsx

@@ -0,0 +1,119 @@
+import * as React from "react"
+import * as DialogPrimitive from "@radix-ui/react-dialog"
+import { XIcon } from "lucide-react"
+import { cn } from "../util/cn.js";
+
+const Dialog = DialogPrimitive.Root
+
+const DialogTrigger = DialogPrimitive.Trigger
+
+const DialogPortal = DialogPrimitive.Portal
+
+const DialogClose = DialogPrimitive.Close
+
+const DialogOverlay = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Overlay
+    ref={ref}
+    className={cn(
+      "fixed inset-0 z-50 bg-black/80  data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      className
+    )}
+    {...props}
+  />
+))
+DialogOverlay.displayName = DialogPrimitive.Overlay.displayName
+
+const DialogContent = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
+>(({ className, children, ...props }, ref) => (
+  <DialogPortal>
+    <DialogOverlay />
+    <DialogPrimitive.Content
+      ref={ref}
+      className={cn(
+        "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
+        <XIcon className="h-4 w-4" />
+        <span className="sr-only">Close</span>
+      </DialogPrimitive.Close>
+    </DialogPrimitive.Content>
+  </DialogPortal>
+))
+DialogContent.displayName = DialogPrimitive.Content.displayName
+
+const DialogHeader = ({
+                        className,
+                        ...props
+                      }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn(
+      "flex flex-col space-y-1.5 text-center sm:text-left",
+      className
+    )}
+    {...props}
+  />
+)
+DialogHeader.displayName = "DialogHeader"
+
+const DialogFooter = ({
+                        className,
+                        ...props
+                      }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn(
+      "flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2",
+      className
+    )}
+    {...props}
+  />
+)
+DialogFooter.displayName = "DialogFooter"
+
+const DialogTitle = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Title>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Title
+    ref={ref}
+    className={cn(
+      "text-lg font-semibold leading-none tracking-tight",
+      className
+    )}
+    {...props}
+  />
+))
+DialogTitle.displayName = DialogPrimitive.Title.displayName
+
+const DialogDescription = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Description>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Description
+    ref={ref}
+    className={cn("text-sm text-muted-foreground", className)}
+    {...props}
+  />
+))
+DialogDescription.displayName = DialogPrimitive.Description.displayName
+
+export {
+  Dialog,
+  DialogPortal,
+  DialogOverlay,
+  DialogTrigger,
+  DialogClose,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+}

package/src/lib/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/lib/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/lib/components/Input.tsx

@@ -0,0 +1,24 @@
+import * as React from "react";
+import { cn } from "../util/cn.js";
+
+export interface InputProps
+  extends React.InputHTMLAttributes<HTMLInputElement> {}
+
+const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type, ...props }, ref) => {
+    return (
+      <input
+        type={type}
+        className={cn(
+          "flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm shadow-sm transition-colors file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+          className,
+        )}
+        ref={ref}
+        {...props}
+      />
+    );
+  },
+);
+Input.displayName = "Input";
+
+export { Input };

package/src/lib/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>
+    </>
+  );
+};