zudoku 0.3.0-dev.5 → 0.3.0-dev.50

package/src/lib/components/Bootstrap.tsx

@@ -0,0 +1,37 @@
+import { type HelmetData, HelmetProvider } from "@zudoku/react-helmet-async";
+import { StrictMode } from "react";
+import { createBrowserRouter, RouterProvider } from "react-router-dom";
+import {
+  type StaticHandlerContext,
+  StaticRouterProvider,
+} from "react-router-dom/server.js";
+
+const Bootstrap = ({
+  router,
+}: {
+  router: ReturnType<typeof createBrowserRouter>;
+}) => (
+  <StrictMode>
+    <HelmetProvider>
+      <RouterProvider router={router} />
+    </HelmetProvider>
+  </StrictMode>
+);
+
+const BootstrapStatic = ({
+  router,
+  context,
+  helmetContext,
+}: {
+  helmetContext: HelmetData["context"];
+  context: StaticHandlerContext;
+  router: ReturnType<typeof createBrowserRouter>;
+}) => (
+  <StrictMode>
+    <HelmetProvider context={helmetContext}>
+      <StaticRouterProvider router={router} context={context} />
+    </HelmetProvider>
+  </StrictMode>
+);
+
+export { Bootstrap, BootstrapStatic };

package/src/lib/components/DevPortal.tsx

@@ -1,29 +1,29 @@
-/* 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 { Helmet } from "@zudoku/react-helmet-async";
+import {
+  Fragment,
+  memo,
+  type PropsWithChildren,
+  useEffect,
+  useMemo,
+} from "react";
+import { ErrorBoundary } from "react-error-boundary";
 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 { hasHead } from "../core/plugins.js";
+import { TopLevelError } from "../errors/TopLevelError.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";
 import { ViewportAnchorProvider } from "./context/ViewportAnchorContext.js";
-import { Router } from "./Router.js";
 
 export const DevPortalSystemPaths = {
   Settings: "/settings",
@@ -33,22 +33,10 @@ 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 = ({
+  children,
+  ...props
+}: PropsWithChildren<ZudokuContextOptions>) => {
   const components = useMemo(
     () => ({ ...DEFAULT_COMPONENTS, ...props.overrides }),
     [props.overrides],
@@ -65,39 +53,36 @@ 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>
-        <DevPortalProvider value={devPortalContext}>
-          <MDXProvider components={mdxComponents}>
-            <ThemeProvider>
-              <ComponentsProvider value={components}>
-                <ViewportAnchorProvider>
-                  <Suspense
-                    fallback={
-                      <div className="grid place-items-center h-full">
-                        Loading...
-                      </div>
-                    }
-                  >
-                    <Router
-                      plugins={[
-                        ...(props.plugins ?? []),
-                        ...(props.authentication ? [props.authentication] : []),
-                      ]}
-                    />
-                  </Suspense>
-                </ViewportAnchorProvider>
-              </ComponentsProvider>
-            </ThemeProvider>
-          </MDXProvider>
-        </DevPortalProvider>
-      </HelmetProvider>
+      <Helmet>{heads}</Helmet>
+      <DevPortalProvider value={devPortalContext}>
+        <MDXProvider components={mdxComponents}>
+          <ThemeProvider>
+            <ComponentsProvider value={components}>
+              <ViewportAnchorProvider>{children}</ViewportAnchorProvider>
+            </ComponentsProvider>
+          </ThemeProvider>
+        </MDXProvider>
+      </DevPortalProvider>
     </QueryClientProvider>
   );
 };
 
-const DevPortal = memo(DevPortalInner);
+const Inner = memo(DevPortalInner);
+
+const DevPortal = (props: ZudokuContextOptions) => {
+  return (
+    <ErrorBoundary FallbackComponent={TopLevelError}>
+      <Inner {...props} />
+    </ErrorBoundary>
+  );
+};
 DevPortal.displayName = "DevPortal";
 
 export { DevPortal };

package/src/lib/components/ErrorPage.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import { Link } from "react-router-dom";
+import { CategoryHeading } from "./CategoryHeading.js";
+import { Heading } from "./Heading.js";
+import { ProseClasses } from "./Markdown.js";
+
+export const ErrorPage = ({
+  title = "An error occurred",
+  message,
+  category,
+}: {
+  title?: ReactNode;
+  message?: ReactNode;
+  category?: ReactNode;
+}) => {
+  return (
+    <div className={ProseClasses + " h-full pt-[--padding-content-top]"}>
+      {category && <CategoryHeading>{category}</CategoryHeading>}
+      {title && (
+        <Heading level={1} className="flex gap-3.5 items-center">
+          {title}
+        </Heading>
+      )}
+      <p>{message}</p>
+      <Link to="/">Go back home</Link>
+    </div>
+  );
+};

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,7 +35,7 @@ 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">
@@ -43,6 +43,7 @@ export const Header = memo(function HeaderInner() {
                 <>
                   {isAuthenticated ? (
                     <button
+                      type="button"
                       className="cursor-pointer hover:bg-secondary p-1 px-2 mx-2 rounded text-nowrap"
                       onClick={logout}
                     >
@@ -50,6 +51,7 @@ export const Header = memo(function HeaderInner() {
                     </button>
                   ) : (
                     <button
+                      type="button"
                       className="cursor-pointer hover:bg-secondary p-1 px-2 mx-2 rounded"
                       onClick={login}
                     >
@@ -59,6 +61,10 @@ export const Header = memo(function HeaderInner() {
                 </>
               )}
               <button
+                type="button"
+                aria-label={
+                  isDark ? "Switch to light mode" : "Switch to dark mode"
+                }
                 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/InlineCode.tsx

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+import { cn } from "../util/cn.js";
+
+export const InlineCode = ({
+  className,
+  children,
+}: {
+  className?: string;
+  children: ReactNode;
+}) => (
+  <code
+    className={cn(
+      className,
+      "font-mono border border-border p-1 py-0.5 rounded bg-border/50 dark:bg-border/70 whitespace-nowrap",
+    )}
+  >
+    {children}
+  </code>
+);

package/src/lib/components/Layout.tsx

@@ -1,6 +1,7 @@
+import { Helmet } from "@zudoku/react-helmet-async";
 import { Suspense, useEffect, useRef, type ReactNode } from "react";
 import { Outlet, useLocation } from "react-router-dom";
-import { Helmet } from "../core/helmet.js";
+import { cn } from "../util/cn.js";
 import { useScrollToAnchor } from "../util/useScrollToAnchor.js";
 import { useScrollToTop } from "../util/useScrollToTop.js";
 import { useDevPortal } from "./context/DevPortalProvider.js";
@@ -29,8 +30,7 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
 
   return (
     <>
-      <Helmet titleTemplate={meta?.pageTitle}>
-        <title>Home</title>
+      <Helmet titleTemplate={meta?.title}>
         {meta?.description && (
           <meta name="description" content={meta.description} />
         )}
@@ -48,10 +48,12 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
         >
           <SideNavigation />
           <main
-            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"
+            className={cn(
+              "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] lg:peer-data-[navigation=true]:pl-12",
+            )}
           >
             {children ?? <Outlet />}
           </main>

package/src/lib/components/NotFoundPage.tsx

@@ -0,0 +1,39 @@
+import { UnlinkIcon } from "lucide-react";
+import { Link, useParams } from "react-router-dom";
+import { Callout } from "../ui/Callout.js";
+import { CategoryHeading } from "./CategoryHeading.js";
+import { Heading } from "./Heading.js";
+import { ProseClasses } from "./Markdown.js";
+
+export const NotFoundPage = () => {
+  const params = useParams();
+
+  return (
+    <div className={ProseClasses + " h-full pt-[--padding-content-top]"}>
+      <CategoryHeading>404</CategoryHeading>
+      <Heading level={1} className="flex gap-3.5 items-center">
+        Page not found
+        <UnlinkIcon size={24} />
+      </Heading>
+      {import.meta.env.DEV && (
+        <Callout type="caution" title="Developer hint">
+          Start by adding a file at{" "}
+          <code>
+            {"{PROJECT_ROOT}"}/{params["*"]}.mdx
+          </code>{" "}
+          and add some content to make this error go away.
+          <br />
+          <small className="italic">
+            Note: This hint is only shown in development mode.
+          </small>
+        </Callout>
+      )}
+      <p>
+        It seems that the page you are looking for does not exist or may have
+        been moved. Please check the URL for any typos or use the navigation
+        menu to find the correct page.
+      </p>
+      <Link to="/">Go back home</Link>
+    </div>
+  );
+};

package/src/lib/components/SyntaxHighlight.tsx

@@ -7,21 +7,23 @@ import {
 
 import { CheckIcon, CopyIcon } from "lucide-react";
 
-if (!import.meta.env.SSR) {
-  globalThis.Prism = Prism;
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-bash.min.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-ruby.min.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-markup-templating.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-php.min.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-json.min.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-java.min.js");
-}
+globalThis.Prism = Prism;
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-bash.min.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-ruby.min.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-markup-templating.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-php.min.js");
+// @ts-expect-error This is untyped
+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";
 import { cn } from "../util/cn.js";
@@ -33,10 +35,12 @@ type SyntaxHighlightProps = {
   wrapLines?: boolean;
   copyable?: boolean;
   showLanguageIndicator?: boolean;
-} & Omit<HighlightProps, "children">;
+  language?: string;
+} & Omit<HighlightProps, "children" | "language">;
 
 export const SyntaxHighlight = ({
   copyable = true,
+  language = "plain",
   ...props
 }: SyntaxHighlightProps) => {
   const [isDark] = useTheme();
@@ -47,7 +51,11 @@ export const SyntaxHighlight = ({
   }
 
   return (
-    <Highlight theme={isDark ? themes.vsDark : themes.github} {...props}>
+    <Highlight
+      theme={isDark ? themes.vsDark : themes.github}
+      language={language}
+      {...props}
+    >
       {({ className, style, tokens, getLineProps, getTokenProps }) => (
         <pre
           className={cn(
@@ -67,7 +75,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"),
@@ -84,7 +92,7 @@ export const SyntaxHighlight = ({
           )}
           {props.showLanguageIndicator && (
             <span className="absolute top-1.5 right-3 text-[11px] font-mono text-muted-foreground transition group-hover:opacity-0">
-              {props.language}
+              {language}
             </span>
           )}
           {tokens.map((line, i) => (

package/src/lib/components/TopNavigation.tsx

@@ -6,6 +6,11 @@ import { useDevPortal } from "./context/DevPortalProvider.js";
 export const TopNavigation = () => {
   const { navigation } = useDevPortal();
 
+  // Hide tope nav if there is only one item
+  if (navigation.length <= 1) {
+    return null;
+  }
+
   return (
     <nav className="border-b border-border text-sm px-12 h-[--top-nav-height]">
       <ul className="flex flex-row items-center gap-8">

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,21 @@
-export { useMDXComponents } from "@mdx-js/react";
-export { DevPortal } from "./DevPortal.js";
-export { Link } from "./Link.js";
+import { useMDXComponents as useMDXComponentsImport } from "@mdx-js/react";
+import { Link as LinkImport } from "react-router-dom";
+import { RouterError as RouterErrorImport } from "../errors/RouterError.js";
+import { ServerError as ServerErrorImport } from "../errors/ServerError.js";
+import { Callout as CalloutImport } from "../ui/Callout.js";
+import {
+  Bootstrap as BootstrapImport,
+  BootstrapStatic as BootstrapStaticImport,
+} from "./Bootstrap.js";
+import { DevPortal as DevPortalImport } from "./DevPortal.js";
+import { Layout as LayoutImport } from "./Layout.js";
+
+export const useMDXComponents = /*@__PURE__*/ useMDXComponentsImport;
+export const Callout = /*@__PURE__*/ CalloutImport;
+export const DevPortal = /*@__PURE__*/ DevPortalImport;
+export const Layout = /*@__PURE__*/ LayoutImport;
+export const Link = /*@__PURE__*/ LinkImport;
+export const RouterError = /*@__PURE__*/ RouterErrorImport;
+export const ServerError = /*@__PURE__*/ ServerErrorImport;
+export const Bootstrap = /*@__PURE__*/ BootstrapImport;
+export const BootstrapStatic = /*@__PURE__*/ BootstrapStaticImport;

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,29 +65,59 @@ export const useRoutingState = create<RoutingState>(() => ({}));
 export type ApiKeyCache = "api-keys";
 export type DevPortalCacheKey = ApiKeyCache | string;
 
+type Metadata = Partial<{
+  title: string;
+  description: string;
+  logo: string;
+  favicon: string;
+  generator: string;
+  applicationName: string;
+  referrer: string;
+  keywords: string[];
+  authors: string[];
+  creator: string;
+  publisher: string;
+}>;
+type Page = Partial<{
+  pageTitle?: string;
+  logo?: string;
+}>;
+export type ZudokuContextOptions = {
+  metadata?: Metadata;
+  page?: Page;
+  authentication?: AuthenticationProvider;
+  navigation: NavigationItem[];
+  plugins?: DevPortalPlugin[];
+  mdxComponents?: MdxComponentsType;
+  overrides?: ComponentsContextType;
+};
+
 export class DevPortalContext {
-  private plugins: DevPortalPlugin[] = [];
-  private navigationPlugins: NavigationPlugin[];
+  private plugins: NonNullable<ZudokuContextOptions["plugins"]> = [];
+  public navigation: ZudokuContextOptions["navigation"];
+  public meta: ZudokuContextOptions["metadata"];
+  public page: ZudokuContextOptions["page"];
+  public authentication?: ZudokuContextOptions["authentication"];
 
-  public navigation: NavigationItem[];
-  public meta: DevPortalProps["meta"];
-  public authentication?: AuthenticationProvider;
   public state: typeof useRoutingState;
+  private navigationPlugins: NavigationPlugin[];
 
-  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));
-    this.authentication?.initialize(this);
+    await Promise.all([
+      this.plugins
+        .filter(needsInitialization)
+        .map((plugin) => plugin.initialize?.(this)),
+    ]);
   };
 
   invalidateCache = async (key: DevPortalCacheKey[]) => {