zudoku 0.1.1-dev.9 → 0.3.0-dev.100

package/src/lib/components/navigation/SidebarItem.tsx

@@ -0,0 +1,128 @@
+import { cva } from "class-variance-authority";
+import { ExternalLinkIcon } from "lucide-react";
+import { NavLink } from "react-router-dom";
+
+import type { SidebarItem as SidebarItemType } from "../../../config/validators/SidebarSchema.js";
+import { cn } from "../../util/cn.js";
+import { joinPath } from "../../util/joinPath.js";
+import { AnchorLink } from "../AnchorLink.js";
+import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
+import { useTopNavigationItem } from "../context/ZudokuContext.js";
+import { SidebarBadge } from "./SidebarBadge.js";
+import { SidebarCategory } from "./SidebarCategory.js";
+
+export const navigationListItem = cva(
+  "flex px-[--padding-nav-item] py-1.5 rounded-lg hover:bg-accent transition-colors duration-300",
+  {
+    variants: {
+      isTopLevel: {
+        true: "font-semibold",
+      },
+      isActive: {
+        true: "text-primary font-medium",
+        false: "text-foreground/80",
+      },
+      isMuted: {
+        true: "text-foreground/30",
+        false: "",
+      },
+    },
+  },
+);
+
+export const DATA_ANCHOR_ATTR = "data-anchor";
+
+export const SidebarItem = ({
+  item,
+  level = 0,
+}: {
+  item: SidebarItemType;
+  basePath?: string;
+  level?: number;
+}) => {
+  const topNavItem = useTopNavigationItem();
+  const { activeAnchor } = useViewportAnchor();
+
+  switch (item.type) {
+    case "category":
+      return <SidebarCategory category={item} level={level} />;
+    case "doc":
+      return (
+        <NavLink
+          className={({ isActive }) =>
+            navigationListItem({ isActive, isTopLevel: level === 0 })
+          }
+          to={joinPath(topNavItem?.id, item.id)}
+        >
+          {item.badge ? (
+            <>
+              <span className="truncate" title={item.label}>
+                {item.label}
+              </span>
+              <SidebarBadge {...item.badge} />
+            </>
+          ) : (
+            item.label
+          )}
+        </NavLink>
+      );
+    case "link":
+      return item.href.startsWith("#") ? (
+        <AnchorLink
+          to={item.href}
+          {...{ [DATA_ANCHOR_ATTR]: item.href.slice(1) }}
+          className={cn(
+            "flex gap-2.5 justify-between",
+            level === 0 && "-mx-[--padding-nav-item]",
+            navigationListItem({
+              isActive: item.href.slice(1) === activeAnchor,
+            }),
+          )}
+        >
+          {item.badge ? (
+            <>
+              <span className="truncate" title={item.label}>
+                {item.label}
+              </span>
+              <SidebarBadge {...item.badge} />
+            </>
+          ) : (
+            <span className="break-all">{item.label}</span>
+          )}
+        </AnchorLink>
+      ) : !item.href.startsWith("http") ? (
+        <NavLink
+          className={cn("flex gap-2.5 justify-between", navigationListItem())}
+          to={item.href}
+        >
+          {item.badge ? (
+            <>
+              <span className="truncate" title={item.label}>
+                {item.label}
+              </span>
+              <SidebarBadge {...item.badge} />
+            </>
+          ) : (
+            <span className="break-all">{item.label}</span>
+          )}
+        </NavLink>
+      ) : (
+        <a
+          className={cn(
+            navigationListItem({ isTopLevel: level === 0 }),
+            "block",
+          )}
+          href={item.href}
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          <span className="whitespace-normal">{item.label}</span>
+          {/* This prevents that the icon would be positioned in its own line if the text fills a line entirely */}
+          <span className="whitespace-nowrap">
+            &nbsp;
+            <ExternalLinkIcon className="inline ml-1" size={12} />
+          </span>
+        </a>
+      );
+  }
+};

package/src/lib/components/navigation/SidebarWrapper.tsx

@@ -0,0 +1,24 @@
+import { forwardRef, type PropsWithChildren } from "react";
+import { cn } from "../../util/cn.js";
+
+export const SidebarWrapper = forwardRef<
+  HTMLDivElement,
+  PropsWithChildren<{ pushMainContent?: boolean; className?: string }>
+>(function SideNavigation({ children, className, pushMainContent }, ref) {
+  return (
+    <nav
+      // this data attribute is used in `Layout.tsx` to determine if side navigation
+      // is present for the current page so the main content is pushed to the right
+      // it's also important to set `peer` class here.
+      // maybe this could be simplified by adjusting the layout
+      data-navigation={String(pushMainContent)}
+      className={cn(
+        "peer hidden lg:flex flex-col fixed text-sm overflow-y-auto shrink-0 p-[--padding-nav-item] -mx-[--padding-nav-item] pb-20 pt-[--padding-content-top] w-[--side-nav-width] h-[calc(100%-var(--header-height))] scroll-pt-2 gap-2",
+        className,
+      )}
+      ref={ref}
+    >
+      {children}
+    </nav>
+  );
+});

package/src/lib/components/navigation/utils.ts

@@ -0,0 +1,117 @@
+import { useLocation } from "react-router-dom";
+import type {
+  SidebarItem,
+  SidebarItemCategory,
+} from "../../../config/validators/SidebarSchema.js";
+import { joinPath } from "../../util/joinPath.js";
+import { useTopNavigationItem, useZudoku } from "../context/ZudokuContext.js";
+
+export type TraverseCallback<T> = (
+  item: SidebarItem,
+  parentCategories: SidebarItem[],
+) => T | void;
+
+export const traverseSidebar = <T>(
+  sidebar: SidebarItem[],
+  callback: TraverseCallback<T>,
+): T | undefined => {
+  for (const item of sidebar) {
+    const result = traverseSidebarItem(item, callback);
+    if (result !== undefined) return result;
+  }
+};
+
+export const traverseSidebarItem = <T>(
+  item: SidebarItem,
+  callback: TraverseCallback<T>,
+  parentCategories: SidebarItem[] = [],
+): T | undefined => {
+  const result = callback(item, parentCategories);
+  if (result !== undefined) return result;
+
+  if (item.type === "category") {
+    for (const child of item.items) {
+      const childResult = traverseSidebarItem(child, callback, [
+        ...parentCategories,
+        item,
+      ]);
+      if (childResult !== undefined) return childResult;
+    }
+  }
+};
+
+export const useCurrentItem = () => {
+  const location = useLocation();
+  const topNavItem = useTopNavigationItem();
+  const { sidebars } = useZudoku();
+  const currentSidebar = topNavItem?.id ? sidebars[topNavItem.id] : [];
+
+  return traverseSidebar(currentSidebar, (item) => {
+    if (
+      item.type === "doc" &&
+      joinPath(topNavItem?.id, item.id) === location.pathname
+    ) {
+      return item;
+    }
+  });
+};
+
+export const useIsCategoryOpen = (category: SidebarItemCategory) => {
+  const location = useLocation();
+  const topNavItem = useTopNavigationItem();
+
+  return traverseSidebarItem(category, (item) => {
+    if (item.type === "category" && item.link) {
+      const categoryLinkPath = joinPath(topNavItem?.id, item.link.id);
+      if (categoryLinkPath === location.pathname) {
+        return true;
+      }
+    }
+
+    if (item.type === "doc") {
+      const docPath = joinPath(topNavItem?.id, item.id);
+      if (docPath === location.pathname) {
+        return true;
+      }
+    }
+  });
+};
+
+export const usePrevNext = (): {
+  prev?: { label: string; id: string };
+  next?: { label: string; id: string };
+} => {
+  const currentId = useLocation().pathname;
+  const { sidebars } = useZudoku();
+  const topNavItem = useTopNavigationItem();
+  const currentSidebar = topNavItem?.id ? sidebars[topNavItem.id] : [];
+
+  let prev;
+  let next;
+
+  let foundCurrent = false;
+
+  traverseSidebar(currentSidebar, (item) => {
+    const itemId =
+      item.type === "doc"
+        ? joinPath(topNavItem?.id, item.id)
+        : item.type === "category" && item.link
+          ? joinPath(topNavItem?.id, item.link.id)
+          : undefined;
+
+    if (!itemId) return;
+
+    if (foundCurrent) {
+      next = { label: item.label, id: itemId };
+      return true;
+    }
+
+    if (currentId === itemId) {
+      foundCurrent = true;
+    } else {
+      prev = { label: item.label, id: itemId };
+    }
+  });
+
+  return { prev, next };
+};

package/src/lib/core/DevPortalContext.ts

@@ -0,0 +1,134 @@
+import { QueryClient } from "@tanstack/react-query";
+import { NavigateFunction } from "react-router-dom";
+import type { SidebarConfig } from "../../config/validators/SidebarSchema.js";
+import { type AuthenticationProvider } from "../authentication/authentication.js";
+import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
+import { Slotlets } from "../components/SlotletProvider.js";
+import { joinPath } from "../util/joinPath.js";
+import type { MdxComponentsType } from "../util/MdxComponents.js";
+import {
+  type DevPortalPlugin,
+  isApiIdentityPlugin,
+  isNavigationPlugin,
+  type NavigationPlugin,
+  needsInitialization,
+} from "./plugins.js";
+
+export interface ApiIdentity {
+  authorizeRequest: (request: Request) => Request;
+  label: string;
+  id: string;
+}
+
+export const queryClient = new QueryClient();
+
+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?: {
+    src: {
+      light: string;
+      dark: string;
+    };
+    width?: string;
+    alt?: string;
+  };
+}>;
+
+export type ZudokuContextOptions = {
+  metadata?: Metadata;
+  page?: Page;
+  authentication?: AuthenticationProvider;
+  topNavigation?: Array<{ id: string; label: string }>;
+  sidebars?: SidebarConfig;
+  plugins?: DevPortalPlugin[];
+  slotlets?: Slotlets;
+  mdx?: {
+    components?: MdxComponentsType;
+  };
+  overrides?: ComponentsContextType;
+};
+
+export class DevPortalContext {
+  public plugins: NonNullable<ZudokuContextOptions["plugins"]>;
+  public sidebars: NonNullable<ZudokuContextOptions["sidebars"]>;
+  public topNavigation: NonNullable<ZudokuContextOptions["topNavigation"]>;
+  public meta: ZudokuContextOptions["metadata"];
+  public page: ZudokuContextOptions["page"];
+  public authentication?: ZudokuContextOptions["authentication"];
+  private navigationPlugins: NavigationPlugin[];
+
+  constructor(config: ZudokuContextOptions) {
+    this.plugins = config.plugins ?? [];
+    this.topNavigation = config.topNavigation ?? [];
+    this.sidebars = config.sidebars ?? {};
+    this.navigationPlugins = this.plugins.filter(isNavigationPlugin);
+    this.authentication = config.authentication;
+    this.meta = config.metadata;
+    this.page = config.page;
+  }
+
+  initialize = async ({
+    navigate,
+  }: {
+    navigate: NavigateFunction;
+  }): Promise<void> => {
+    await Promise.all(
+      this.plugins
+        .filter(needsInitialization)
+        .map((plugin) => plugin.initialize?.(this, { navigate })),
+    );
+  };
+
+  invalidateCache = async (key: DevPortalCacheKey[]) => {
+    await queryClient.invalidateQueries({ queryKey: key });
+  };
+
+  getApiIdentities = async () => {
+    const keys = await Promise.all(
+      this.plugins
+        .filter(isApiIdentityPlugin)
+        .map((plugin) => plugin.getIdentities(this)),
+    );
+
+    return keys.flat();
+  };
+
+  getPluginSidebar = async (path: string) => {
+    const navigations = await Promise.all(
+      this.navigationPlugins.map((plugin) =>
+        plugin.getSidebar?.(joinPath(path)),
+      ),
+    );
+
+    return navigations.flatMap((nav) => nav ?? []);
+  };
+
+  signRequest = async (request: Request) => {
+    if (!this.authentication) {
+      throw new Error("No authentication provider configured");
+    }
+
+    const accessToken = await this.authentication.getAccessToken();
+
+    request.headers.set("Authorization", `Bearer ${accessToken}`);
+
+    return request;
+  };
+}

package/src/lib/core/plugins.ts

@@ -0,0 +1,80 @@
+import { type ReactElement } from "react";
+import { NavigateFunction, type RouteObject } from "react-router-dom";
+import type { Sidebar } from "../../config/validators/SidebarSchema.js";
+import { MdxComponentsType } from "../util/MdxComponents.js";
+import { DevPortalContext, type ApiIdentity } from "./DevPortalContext.js";
+
+export type DevPortalPlugin =
+  | CommonPlugin
+  | ProfileMenuPlugin
+  | NavigationPlugin
+  | ApiIdentityPlugin
+  | SearchProviderPlugin;
+
+export interface NavigationPlugin {
+  getRoutes: () => RouteObject[];
+  getSidebar?: (path: string) => Promise<Sidebar>;
+}
+
+export interface ApiIdentityPlugin {
+  getIdentities: (context: DevPortalContext) => Promise<ApiIdentity[]>;
+}
+
+export interface SearchProviderPlugin {
+  renderSearch: (o: {
+    isOpen: boolean;
+    onClose: () => void;
+  }) => React.JSX.Element | null;
+}
+
+export interface ProfileMenuPlugin {
+  getProfileMenuItems: (context: DevPortalContext) => ProfileNavigationItem[];
+}
+
+export type ProfileNavigationItem = {
+  label: string;
+  path?: string;
+  children?: ProfileNavigationItem[];
+};
+
+export interface CommonPlugin {
+  initialize?: (
+    context: DevPortalContext,
+    options: { navigate: NavigateFunction },
+  ) => Promise<void | boolean> | void | boolean;
+  getHead?: () => ReactElement | undefined;
+  getMdxComponents?: () => MdxComponentsType;
+}
+
+export const isProfileMenuPlugin = (
+  obj: DevPortalPlugin,
+): obj is ProfileMenuPlugin =>
+  "getProfileMenuItems" in obj && typeof obj.getProfileMenuItems === "function";
+
+export const isNavigationPlugin = (
+  obj: DevPortalPlugin,
+): obj is NavigationPlugin =>
+  "getRoutes" in obj && typeof obj.getRoutes === "function";
+
+export const isSearchPlugin = (
+  obj: DevPortalPlugin,
+): obj is SearchProviderPlugin =>
+  "renderSearch" in obj && typeof obj.renderSearch === "function";
+
+export const needsInitialization = (
+  obj: DevPortalPlugin,
+): 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 isMdxProviderPlugin = (
+  obj: DevPortalPlugin,
+): obj is CommonPlugin =>
+  "getMdxComponents" in obj && typeof obj.getMdxComponents === "function";
+
+export const isApiIdentityPlugin = (
+  obj: DevPortalPlugin,
+): obj is ApiIdentityPlugin =>
+  "getIdentities" in obj && typeof obj.getIdentities === "function";

package/src/lib/errors/ErrorAlert.tsx

@@ -0,0 +1,21 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function ErrorAlert({ error }: { error: any }) {
+  const message = error?.message ?? "Something went wrong";
+  const stack = error?.stack;
+
+  return (
+    <div className="flex h-screen max-h-screen min-h-full items-center justify-center bg-primary-background px-4 py-16 lg:px-8">
+      <div className="mx-auto max-w-[85%] sm:max-w-[50%]">
+        <h1 className="text-4xl font-bold tracking-tight text-h1-text sm:text-5xl">
+          Something went wrong
+        </h1>
+        <p className="mt-5 text-h1-text">{message}</p>
+        {stack ? (
+          <pre className="mt-5 max-h-[400px] w-full overflow-scroll rounded-md border border-input-border bg-input-background p-3 text-property-name-text text-red-700">
+            {stack}
+          </pre>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/lib/errors/RouterError.tsx

@@ -0,0 +1,13 @@
+import { isRouteErrorResponse, useRouteError } from "react-router-dom";
+import { NotFoundPage } from "../components/NotFoundPage.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function RouterError() {
+  const error = useRouteError();
+
+  if (isRouteErrorResponse(error) && error.status === 404) {
+    return <NotFoundPage />;
+  }
+
+  return <ErrorAlert error={error} />;
+}

package/src/lib/errors/ServerError.tsx

@@ -0,0 +1,5 @@
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function ServerError({ error }: { error: unknown }) {
+  return <ErrorAlert error={error} />;
+}

package/src/lib/errors/TopLevelError.tsx

@@ -0,0 +1,8 @@
+import { FallbackProps } from "react-error-boundary";
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function TopLevelError({ error, resetErrorBoundary }: FallbackProps) {
+  // Call resetErrorBoundary() to reset the error boundary and retry the render.
+
+  return <ErrorAlert error={error} />;
+}