@mehdad67/apitogo 0.1.24

package/src/lib/components/Slot.tsx

@@ -0,0 +1,64 @@
+import { type ReactNode, useId, useLayoutEffect } from "react";
+import {
+  type SlotType,
+  useRenderSlot,
+  useSlotContext,
+} from "./context/SlotProvider.js";
+
+// This is to augment the type of the Slot component with custom slot names
+// This is useful for plugins to add custom slots to the Zudoku context
+// and for the user to use them in their own components
+export type CustomSlotNames = never;
+
+type PredefinedSlotNames =
+  | "api-keys-list-page"
+  | "api-keys-list-page-before-keys"
+  | "footer-after"
+  | "footer-before"
+  | "head-navigation-end"
+  | "head-navigation-start"
+  | "layout-after-head"
+  | "layout-before-head"
+  | "top-navigation-after"
+  | "top-navigation-before"
+  | "top-navigation-side"
+  | "content-before"
+  | "content-after"
+  | "navigation-after"
+  | "navigation-before";
+
+export type SlotName = PredefinedSlotNames | CustomSlotNames;
+
+export const Slot = {
+  Source: ({
+    name,
+    children,
+    type = "replace",
+  }: {
+    name: SlotName;
+    type?: "prepend" | "replace" | "append";
+    children: SlotType;
+  }) => {
+    const id = useId();
+    const setSlot = useSlotContext((s) => s.setSlot);
+    const clearSlot = useSlotContext((s) => s.clearSlot);
+
+    if (import.meta.env.SSR) {
+      setSlot(id, name, children, type);
+    }
+
+    useLayoutEffect(() => {
+      setSlot(id, name, children, type);
+      return () => clearSlot(id, name);
+    }, [id, name, children, type, setSlot, clearSlot]);
+
+    return null;
+  },
+
+  Target: ({ name, fallback }: { name: string; fallback?: ReactNode }) => {
+    const slot = useRenderSlot(name);
+
+    if (slot.length === 0) return fallback;
+    return slot;
+  },
+};

package/src/lib/components/Spinner.tsx

@@ -0,0 +1,5 @@
+import { LoaderCircle } from "lucide-react";
+
+export const Spinner = ({ size = 16 }: { size?: number }) => (
+  <LoaderCircle size={size} className="animate-spin" />
+);

package/src/lib/components/StatusPage.tsx

@@ -0,0 +1,96 @@
+import type { ReactNode } from "react";
+import { ErrorPage } from "./ErrorPage.js";
+import { NotFoundPage } from "./NotFoundPage.js";
+
+type StatusPageProps = {
+  statusCode: number;
+  message?: ReactNode;
+};
+
+const getDefaultContent = (
+  statusCode: number,
+): { title: string; message: string } => {
+  switch (statusCode) {
+    case 400:
+      return {
+        title: "Bad Request",
+        message:
+          "The request could not be understood by the server due to malformed syntax.",
+      };
+    case 403:
+      return {
+        title: "Forbidden",
+        message: "You don't have permission to access this resource.",
+      };
+    case 404:
+      return {
+        title: "Not Found",
+        message: "The requested resource could not be found.",
+      };
+    case 405:
+      return {
+        title: "Method Not Allowed",
+        message:
+          "The request method is not supported for the requested resource.",
+      };
+    case 414:
+      return {
+        title: "Request URI Too Large",
+        message: "The request URI is too large.",
+      };
+    case 416:
+      return {
+        title: "Range Not Satisfiable",
+        message: "The server cannot satisfy the request range.",
+      };
+    case 500:
+      return {
+        title: "Internal Server Error",
+        message: "An unexpected error occurred while processing your request.",
+      };
+    case 501:
+      return {
+        title: "Not Implemented",
+        message:
+          "The server does not support the functionality required to fulfill the request.",
+      };
+    case 502:
+      return {
+        title: "Bad Gateway",
+        message:
+          "The server received an invalid response from the upstream server.",
+      };
+    case 503:
+      return {
+        title: "Service Unavailable",
+        message: "The server is temporarily unable to handle the request.",
+      };
+    case 504:
+      return {
+        title: "Gateway Timeout",
+        message:
+          "The server did not receive a timely response from the upstream server.",
+      };
+    default:
+      return {
+        title: "An error occurred",
+        message: "Something went wrong while processing your request.",
+      };
+  }
+};
+
+export const StatusPage = ({ statusCode, message }: StatusPageProps) => {
+  if (statusCode === 404) {
+    return <NotFoundPage />;
+  }
+
+  const defaultContent = getDefaultContent(statusCode);
+
+  return (
+    <ErrorPage
+      title={defaultContent.title}
+      message={message ?? defaultContent.message}
+      category={statusCode}
+    />
+  );
+};

package/src/lib/components/ThemeSwitch.tsx

@@ -0,0 +1,49 @@
+import { MoonIcon, SunIcon } from "lucide-react";
+import { useTheme } from "next-themes";
+import { focusRing } from "../ui/util.js";
+import { cn } from "../util/cn.js";
+import { useIsClient } from "./ClientOnly.js";
+
+export const ThemeSwitch = () => {
+  const { resolvedTheme, setTheme } = useTheme();
+  const isClient = useIsClient();
+
+  const theme = isClient ? resolvedTheme : undefined;
+
+  return (
+    <button
+      type="button"
+      className={cn("flex rounded-full border p-0.5 gap-0.5 group", focusRing)}
+      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
+      aria-label={
+        !isClient
+          ? "Toggle theme"
+          : theme === "dark"
+            ? "Switch to light mode"
+            : "Switch to dark mode"
+      }
+    >
+      <div
+        className={cn(
+          "rounded-full p-0.5 border border-transparent [&>svg>circle]:transition-colors [&>svg>path]:transition-transform transition-all [&>svg>path]:duration-200 [&>svg>circle]:duration-500 [&>svg>circle]:fill-transparent",
+          theme === "light" && "border-border bg-muted",
+          theme === "dark" &&
+            "group-hover:[&>svg>path]:scale-110 group-hover:[&>svg>path]:-translate-x-px group-hover:[&>svg>path]:-translate-y-px group-hover:rotate-15",
+        )}
+      >
+        <SunIcon size={16} />
+      </div>
+      <div
+        className={cn(
+          "rounded-full p-0.5 border border-transparent transition-transform transform-gpu duration-500",
+          theme === "dark" &&
+            "border-border bg-muted [&>svg>path]:fill-white [&>svg>path]:stroke-transparent",
+          theme === "light" &&
+            "group-hover:rotate-[-10deg] [&>svg>path]:stroke-currentColor",
+        )}
+      >
+        <MoonIcon size={16} />
+      </div>
+    </button>
+  );
+};

package/src/lib/components/TopNavigation.tsx

@@ -0,0 +1,103 @@
+import { Separator } from "@lukoweb/apitogo/ui/Separator.js";
+import { cx } from "class-variance-authority";
+import { deepEqual } from "fast-equals";
+import { Suspense } from "react";
+import { NavLink, type NavLinkProps } from "react-router";
+import type { NavigationItem } from "../../config/validators/NavigationSchema.js";
+import { useAuth } from "../authentication/hook.js";
+import { useCurrentNavigation, useZudoku } from "./context/ZudokuContext.js";
+import { getFirstMatchingPath, shouldShowItem } from "./navigation/utils.js";
+import { Slot } from "./Slot.js";
+
+export const TopNavigation = () => {
+  const context = useZudoku();
+  const {
+    options: { navigation = [] },
+  } = context;
+  const auth = useAuth();
+  const filteredItems = navigation.filter(shouldShowItem({ auth, context }));
+
+  if (filteredItems.length === 0 || import.meta.env.MODE === "standalone") {
+    return <style>{`:root { --top-nav-height: 0px; }`}</style>;
+  }
+
+  return (
+    <Suspense>
+      <div className="items-center justify-between px-8 h-(--top-nav-height) hidden lg:flex text-sm relative">
+        <nav className="text-sm">
+          <ul className="flex flex-row items-center gap-8">
+            {filteredItems.map((item) =>
+              item.type === "separator" ? (
+                <li key={item.label} className="-mx-4 h-7">
+                  <Separator orientation="vertical" />
+                </li>
+              ) : item.type !== "section" && item.type !== "filter" ? (
+                <li key={item.label + item.type}>
+                  <TopNavItem {...item} />
+                </li>
+              ) : null,
+            )}
+          </ul>
+        </nav>
+        <Slot.Target name="top-navigation-side" />
+      </div>
+      {/* <PageProgress /> */}
+    </Suspense>
+  );
+};
+
+export const TopNavLink = ({
+  isActive,
+  children,
+  ...props
+}: {
+  isActive?: boolean;
+  children: React.ReactNode;
+} & NavLinkProps) => {
+  return (
+    <NavLink
+      viewTransition
+      className={({ isActive: isActiveNavLink, isPending }) => {
+        const isActiveReal = isActiveNavLink || isActive;
+        return cx(
+          "flex items-center gap-2 lg:py-3.5 font-medium -mb-px transition duration-150 delay-75 relative",
+          isActiveReal || isPending
+            ? [
+                "text-foreground",
+                // underline with view transition animation
+                "after:content-[''] after:absolute after:bottom-0 after:left-0 after:right-0",
+                "after:h-0.5 after:bg-primary",
+                isActiveReal &&
+                  "after:[view-transition-name:top-nav-underline]",
+                isPending && "after:bg-primary/25",
+              ]
+            : "text-foreground/75 hover:text-foreground",
+        );
+      }}
+      {...props}
+    >
+      {children}
+    </NavLink>
+  );
+};
+
+export const TopNavItem = (
+  item: Exclude<
+    NavigationItem,
+    { type: "separator" } | { type: "section" } | { type: "filter" }
+  >,
+) => {
+  const currentNav = useCurrentNavigation();
+  const isActiveTopNavItem = deepEqual(currentNav.topNavItem, item);
+
+  const path = getFirstMatchingPath(item);
+
+  return (
+    // We don't use isActive here because it has to be inside the navigation,
+    // the top nav id doesn't necessarily start with the navigation id
+    <TopNavLink to={path} isActive={isActiveTopNavItem}>
+      {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
+      {item.label}
+    </TopNavLink>
+  );
+};

package/src/lib/components/Typography.tsx

@@ -0,0 +1,12 @@
+import type { AllHTMLAttributes } from "react";
+import { cn } from "../util/cn.js";
+
+// other styles are defined in main.css .prose
+export const ProseClasses = "prose dark:prose-invert prose-neutral typography";
+
+export const Typography = ({
+  className,
+  ...props
+}: AllHTMLAttributes<HTMLDivElement>) => {
+  return <div className={cn(ProseClasses, className)} {...props} />;
+};

package/src/lib/components/Zudoku.tsx

@@ -0,0 +1,106 @@
+import { MDXProvider } from "@mdx-js/react";
+import { useQueryClient } from "@tanstack/react-query";
+import { ThemeProvider } from "next-themes";
+import {
+  memo,
+  type PropsWithChildren,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import { ErrorBoundary } from "react-error-boundary";
+import { Outlet, useLocation, useNavigation } from "react-router";
+import { isMdxProviderPlugin } from "../core/plugins.js";
+import {
+  ZudokuContext,
+  type ZudokuContextOptions,
+} from "../core/ZudokuContext.js";
+import { TopLevelError } from "../errors/TopLevelError.js";
+import { MdxComponents } from "../util/MdxComponents.js";
+import { RouterEventsEmitter } from "./context/RouterEventsEmitter.js";
+import { SlotProvider } from "./context/SlotProvider.js";
+import { ViewportAnchorProvider } from "./context/ViewportAnchorContext.js";
+import { ApitogoProvider } from "./context/ZudokuProvider.js";
+import { PluginHeads } from "./PluginHeads.js";
+
+let apitogoContext: ZudokuContext | undefined;
+
+const ZudokuInner = memo(
+  ({
+    children,
+    env,
+    ...props
+  }: PropsWithChildren<
+    ZudokuContextOptions & { env: Record<string, string> }
+  >) => {
+    const location = useLocation();
+    const mdxComponents = useMemo(() => {
+      const componentsFromPlugins = (props.plugins ?? [])
+        .filter(isMdxProviderPlugin)
+        .flatMap((plugin) =>
+          plugin.getMdxComponents ? [plugin.getMdxComponents()] : [],
+        );
+
+      return {
+        ...componentsFromPlugins.reduce(
+          (acc, curr) => ({ ...acc, ...curr }),
+          {},
+        ),
+        ...MdxComponents,
+        ...props.mdx?.components,
+      };
+    }, [props.mdx?.components, props.plugins]);
+    const [didNavigate, setDidNavigate] = useState(false);
+    const navigation = useNavigation();
+    const queryClient = useQueryClient();
+
+    useEffect(() => {
+      if (didNavigate || !navigation.location) {
+        return;
+      }
+      setDidNavigate(true);
+    }, [didNavigate, navigation.location]);
+
+    apitogoContext ??= new ZudokuContext(props, queryClient, env);
+
+    return (
+      <>
+        <PluginHeads plugins={props.plugins ?? []} location={location} />
+        <ApitogoProvider context={apitogoContext}>
+          <RouterEventsEmitter />
+          <SlotProvider slots={props.slots ?? props.UNSAFE_slotlets}>
+            <MDXProvider components={mdxComponents}>
+              <ThemeProvider attribute="class" disableTransitionOnChange>
+                <ViewportAnchorProvider>
+                  {children ?? <Outlet />}
+                </ViewportAnchorProvider>
+              </ThemeProvider>
+            </MDXProvider>
+          </SlotProvider>
+        </ApitogoProvider>
+      </>
+    );
+  },
+);
+
+ZudokuInner.displayName = "ZudokuInner";
+
+const Apitogo = (
+  props: PropsWithChildren<
+    ZudokuContextOptions & { env?: Record<string, string> }
+  >,
+) => {
+  return (
+    <ErrorBoundary FallbackComponent={TopLevelError}>
+      <ZudokuInner {...props} env={props.env ?? {}} />
+    </ErrorBoundary>
+  );
+};
+Apitogo.displayName = "Apitogo";
+
+/**
+ * @deprecated Use {@link Apitogo} instead.
+ */
+const Zudoku = Apitogo;
+
+export { Apitogo, Zudoku };

package/src/lib/components/cache.ts

@@ -0,0 +1,27 @@
+import { useQueryClient } from "@tanstack/react-query";
+import { useCallback } from "react";
+
+export const CACHE_KEYS = Object.freeze({
+  API_IDENTITIES: ["api-identities"],
+});
+
+type CacheKey = keyof typeof CACHE_KEYS;
+
+export const useCache = () => {
+  const queryClient = useQueryClient();
+  const invalidateCache = useCallback(
+    (key: CacheKey) =>
+      queryClient.invalidateQueries({ queryKey: CACHE_KEYS[key] }),
+    [queryClient],
+  );
+
+  return { invalidateCache };
+};
+
+/**
+ * If a query has this key in its queryKey, it will not put its result in the dehydrated state in the SSR.
+ *
+ * This is useful if the query should only be suspended and not included in the initial HTML response.
+ * (e.g. too large in size, or not needed for the initial page load)
+ */
+export const NO_DEHYDRATE = "no-dehydrate";

package/src/lib/components/context/RenderContext.ts

@@ -0,0 +1,11 @@
+import { createContext } from "react";
+
+export type RenderContextValue = {
+  status: number;
+  bypassProtection: boolean;
+};
+
+export const RenderContext = createContext<RenderContextValue>({
+  status: 200,
+  bypassProtection: false,
+});

package/src/lib/components/context/RouterEventsEmitter.tsx

@@ -0,0 +1,19 @@
+import { useEffect, useRef } from "react";
+import { type Location, useLocation } from "react-router";
+import { useZudoku } from "./ZudokuContext.js";
+
+export const RouterEventsEmitter = () => {
+  const location = useLocation();
+  const zudoku = useZudoku();
+  const previousLocation = useRef<Location | undefined>(undefined);
+
+  useEffect(() => {
+    zudoku.emitEvent("location", {
+      from: previousLocation.current,
+      to: location,
+    });
+    previousLocation.current = location;
+  }, [zudoku, location]);
+
+  return null;
+};

package/src/lib/components/context/SlotProvider.tsx

@@ -0,0 +1,149 @@
+import {
+  type ComponentType,
+  createContext,
+  Fragment,
+  type PropsWithChildren,
+  type ReactNode,
+  use,
+  useMemo,
+  useRef,
+} from "react";
+import { createStore, useStore } from "zustand";
+import {
+  type ExposedComponentProps,
+  useExposedProps,
+} from "../../util/useExposedProps.js";
+
+export type SlotType = ReactNode | ComponentType<ExposedComponentProps>;
+
+type SlotItem = {
+  id: string;
+  content: SlotType;
+  type: "prepend" | "replace" | "append";
+  sequence: number;
+};
+
+type SlotStoreState = {
+  items: Map<string, SlotItem[]>;
+  // to guarantee the order of the items when appending/prepending
+  sequences: Map<string, number>;
+  getItems: (name: string) => SlotItem[];
+  setSlot: (
+    id: string,
+    name: string,
+    content: SlotType,
+    type: "prepend" | "replace" | "append",
+  ) => void;
+  clearSlot: (id: string, name: string) => void;
+};
+
+export type SlotStore = ReturnType<typeof createSlotStore>;
+
+const createSlotStore = ({
+  slots = {},
+}: {
+  slots?: Record<string, SlotType>;
+} = {}) => {
+  const initialItems = new Map(
+    Object.entries(slots).map(([id, content]) => [
+      id,
+      [{ id, content, type: "replace", sequence: 0 } satisfies SlotItem],
+    ]),
+  );
+  const EMPTY_ITEMS: SlotItem[] = [];
+
+  return createStore<SlotStoreState>()((set, get) => ({
+    items: initialItems,
+    sequences: new Map(),
+    getItems: (name) => get().items.get(name) ?? EMPTY_ITEMS,
+    setSlot: (id, name, content, type) =>
+      set((state) => {
+        if (content == null) return state;
+
+        const items = new Map(state.items);
+        const sequences = new Map(state.sequences);
+        const existing = items.get(name) ?? [];
+        const filtered = existing.filter((item) => item.id !== id);
+
+        const currentSequence = sequences.get(name) ?? 0;
+        const newSequence = currentSequence + 1;
+        sequences.set(name, newSequence);
+
+        const newItem = {
+          id,
+          content,
+          type,
+          // Use negative sequence values for "prepend" to ensure they are sorted before positive values for "append".
+          sequence: type === "prepend" ? -newSequence : newSequence,
+        } satisfies SlotItem;
+
+        if (type === "replace") {
+          const nonReplaceItems = filtered.filter(
+            (item) => item.type !== "replace",
+          );
+          items.set(name, [...nonReplaceItems, newItem]);
+        } else {
+          items.set(name, [...filtered, newItem]);
+        }
+
+        return { items, sequences };
+      }),
+    clearSlot: (id, name) =>
+      set((state) => {
+        const items = new Map(state.items);
+        const sequences = new Map(state.sequences);
+        const existing = items.get(name) ?? [];
+        const filtered = existing.filter((item) => item.id !== id);
+
+        if (filtered.length === 0) {
+          items.delete(name);
+          sequences.delete(name);
+        } else {
+          items.set(name, filtered);
+        }
+        return { items, sequences };
+      }),
+  }));
+};
+
+const SlotContext = createContext(createSlotStore());
+
+export const SlotProvider = ({
+  children,
+  slots,
+}: PropsWithChildren<{
+  slots?: Record<string, SlotType>;
+}>) => {
+  const store = useRef<SlotStore>(createSlotStore({ slots })).current;
+  return <SlotContext value={store}>{children}</SlotContext>;
+};
+
+export function useSlotContext<T>(selector: (state: SlotStoreState) => T): T {
+  const store = use(SlotContext);
+  return useStore(store, selector);
+}
+
+const ORDER = ["prepend", "replace", "append"] as const;
+
+export const useRenderSlot = (name: string) => {
+  const exposedProps = useExposedProps();
+  const items = useSlotContext((s) => s.getItems(name));
+
+  return useMemo(() => {
+    if (items.length === 0) return [];
+
+    return items
+      .toSorted((a, b) => {
+        const typeOrder = ORDER.indexOf(a.type) - ORDER.indexOf(b.type);
+        if (typeOrder !== 0) return typeOrder;
+        return a.sequence - b.sequence;
+      })
+      .map((item) =>
+        typeof item.content === "function" ? (
+          <item.content key={item.id} {...exposedProps} />
+        ) : (
+          <Fragment key={item.id}>{item.content}</Fragment>
+        ),
+      );
+  }, [items, exposedProps]);
+};