@mehdad67/apitogo 0.1.24

package/src/lib/authentication/ui/icons/X.tsx

@@ -0,0 +1,10 @@
+import type { SVGProps } from "react";
+
+const XIcon = (props: SVGProps<SVGSVGElement>) => (
+  <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" {...props}>
+    <title>{"X"}</title>
+    <path d="M14.234 10.162 22.977 0h-2.072l-7.591 8.824L7.251 0H.258l9.168 13.343L.258 24H2.33l8.016-9.318L16.749 24h6.993zm-2.837 3.299-.929-1.329L3.076 1.56h3.182l5.965 8.532.929 1.329 7.754 11.09h-3.182z" />
+  </svg>
+);
+
+export default XIcon;

package/src/lib/authentication/utils/relativeRedirectUrl.ts

@@ -0,0 +1,16 @@
+import { joinUrl } from "../../util/joinUrl.js";
+
+export const getRelativeRedirectUrl = (redirectTo?: string | null) => {
+  if (!redirectTo) {
+    return "/";
+  }
+
+  if (typeof window === "undefined") {
+    return redirectTo;
+  }
+
+  return redirectTo.replace(
+    joinUrl(window.location.origin, import.meta.env.BASE_URL),
+    "",
+  );
+};

package/src/lib/components/AiAssistantMenuItems.tsx

@@ -0,0 +1,102 @@
+import { DropdownMenuItem } from "@lukoweb/apitogo/ui/DropdownMenu.js";
+import type { ReactNode } from "react";
+import type {
+  AiAssistantCustom,
+  AiAssistantsConfig,
+} from "../../config/validators/ZudokuConfig.js";
+import { ChatGPTLogo } from "../plugins/markdown/assets/ChatGPTLogo.js";
+import { ClaudeLogo } from "../plugins/markdown/assets/ClaudeLogo.js";
+
+type AiAssistantContext = {
+  pageUrl: string;
+  type: "docs" | "openapi";
+};
+
+type ResolvedAssistant = {
+  label: string;
+  icon?: ReactNode;
+  getUrl: (context: AiAssistantContext) => string;
+};
+
+const PRESETS: Record<string, ResolvedAssistant> = {
+  claude: {
+    label: "Use in Claude",
+    icon: <ClaudeLogo className="size-4" />,
+    getUrl: ({ pageUrl, type }) => {
+      const contextText =
+        type === "openapi" ? "this API" : "this documentation page";
+      const prompt = encodeURIComponent(
+        `Help me understand ${contextText}: ${pageUrl}`,
+      );
+      return `https://claude.ai/new?q=${prompt}`;
+    },
+  },
+  chatgpt: {
+    label: "Use in ChatGPT",
+    icon: <ChatGPTLogo className="size-4" />,
+    getUrl: ({ pageUrl, type }) => {
+      const contextText =
+        type === "openapi" ? "this API" : "this documentation page";
+      const prompt = encodeURIComponent(
+        `Help me understand ${contextText}: ${pageUrl}`,
+      );
+      return `https://chatgpt.com/?q=${prompt}`;
+    },
+  },
+};
+
+const resolveAssistant = (
+  entry: string | AiAssistantCustom,
+): ResolvedAssistant | undefined => {
+  if (typeof entry === "string") {
+    return PRESETS[entry];
+  }
+
+  return {
+    label: entry.label,
+    icon: entry.icon,
+    getUrl: (context) => {
+      if (typeof entry.url === "function") {
+        return entry.url(context);
+      }
+      return entry.url.replaceAll("{pageUrl}", context.pageUrl);
+    },
+  };
+};
+
+const DEFAULT_ASSISTANTS: AiAssistantsConfig = ["claude", "chatgpt"];
+
+export const AiAssistantMenuItems = ({
+  aiAssistants,
+  getPageUrl,
+  type,
+}: {
+  aiAssistants: AiAssistantsConfig;
+  getPageUrl: () => string;
+  type: "docs" | "openapi";
+}) => {
+  const config = aiAssistants ?? DEFAULT_ASSISTANTS;
+
+  if (config === false) {
+    return null;
+  }
+
+  return config.map((entry, index) => {
+    const assistant = resolveAssistant(entry);
+    if (!assistant) return null;
+
+    return (
+      <DropdownMenuItem
+        key={typeof entry === "string" ? entry : index}
+        className="gap-2"
+        onClick={() => {
+          const url = assistant.getUrl({ pageUrl: getPageUrl(), type });
+          window.open(url, "_blank", "noopener,noreferrer");
+        }}
+      >
+        {assistant.icon}
+        {assistant.label}
+      </DropdownMenuItem>
+    );
+  });
+};

package/src/lib/components/AnchorLink.tsx

@@ -0,0 +1,24 @@
+import type { MouseEvent } from "react";
+import { NavLink, type NavLinkProps, useHref, useLocation } from "react-router";
+import { useScrollToHash } from "../util/useScrollToAnchor.js";
+
+/**
+ * Link that scrolls to anchor even if the hash is already set in the URL.
+ */
+export const AnchorLink = (props: NavLinkProps) => {
+  const location = useLocation();
+  const scrollToHash = useScrollToHash();
+  const href = useHref(props.to);
+  const [pathname, hash] = href.split("#");
+
+  const handleClick = (event: MouseEvent<HTMLAnchorElement>) => {
+    props.onClick?.(event);
+    if (hash !== location.hash.slice(1) || pathname !== location.pathname)
+      return;
+
+    event.preventDefault();
+    scrollToHash(hash);
+  };
+
+  return <NavLink {...props} onClick={handleClick} />;
+};

package/src/lib/components/Autocomplete.tsx

@@ -0,0 +1,123 @@
+import {
+  Command,
+  CommandInlineInput,
+  CommandItem,
+  CommandList,
+} from "@lukoweb/apitogo/ui/Command.js";
+import { Popover, PopoverContent } from "@lukoweb/apitogo/ui/Popover.js";
+import { PopoverAnchor } from "@radix-ui/react-popover";
+import { useCommandState } from "cmdk";
+import { type KeyboardEvent, type Ref, useRef, useState } from "react";
+import { cn } from "../util/cn.js";
+
+type AutocompleteProps = {
+  value?: string | number | readonly string[] | undefined;
+  options: readonly string[];
+  onChange: (e: string) => void;
+  onSelect?: (e: string) => void;
+  className?: string;
+  placeholder?: string;
+  onEnterPress?: (e: KeyboardEvent<HTMLInputElement>) => void;
+  onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
+  ref?: Ref<HTMLInputElement>;
+  shouldFilter?: boolean;
+};
+
+const AutocompletePopover = ({
+  value,
+  options,
+  onChange,
+  className,
+  placeholder = "Value",
+  onEnterPress,
+  onKeyDown,
+  ref,
+  onSelect,
+}: AutocompleteProps) => {
+  const [open, setOpen] = useState(false);
+  const [dontClose, setDontClose] = useState(false);
+  const count = useCommandState((state) => state.filtered.count);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  return (
+    <Popover open={open}>
+      <PopoverAnchor>
+        <CommandInlineInput
+          autoComplete="off"
+          ref={(el) => {
+            inputRef.current = el;
+            if (typeof ref === "function") {
+              ref(el);
+            } else if (ref) {
+              ref.current = el;
+            }
+          }}
+          value={value ? String(value) : undefined}
+          placeholder={placeholder}
+          className={cn("h-9 bg-transparent", className)}
+          onFocus={() => setOpen(true)}
+          onBlur={() => {
+            if (dontClose) {
+              return;
+            }
+            setOpen(false);
+          }}
+          onKeyDown={(e) => {
+            onKeyDown?.(e);
+
+            if (e.defaultPrevented) return;
+
+            if (e.key === "Enter") {
+              setOpen(false);
+              inputRef.current?.blur();
+              onEnterPress?.(e);
+            }
+          }}
+          onValueChange={(e) => onChange(e)}
+        />
+      </PopoverAnchor>
+      <PopoverContent
+        onMouseEnter={() => setDontClose(true)}
+        onMouseLeave={() => setDontClose(false)}
+        onOpenAutoFocus={(e) => e.preventDefault()}
+        className={cn("p-0 w-(--radix-popover-trigger-width)", {
+          "border-0": count === 0,
+        })}
+        align="start"
+        side="bottom"
+        onWheel={(e) => {
+          // See: https://github.com/radix-ui/primitives/issues/1159
+          e.stopPropagation();
+        }}
+        onTouchMove={(e) => {
+          e.stopPropagation();
+        }}
+      >
+        <CommandList className="max-h-[140px]">
+          {options.map((enumValue) => (
+            <CommandItem
+              key={enumValue}
+              value={enumValue}
+              onSelect={(selected) => {
+                onSelect?.(selected);
+                onChange(selected);
+                setOpen(false);
+              }}
+              className="cursor-pointer"
+            >
+              {enumValue}
+            </CommandItem>
+          ))}
+        </CommandList>
+      </PopoverContent>
+    </Popover>
+  );
+};
+
+export const Autocomplete = ({ shouldFilter, ...props }: AutocompleteProps) => {
+  return (
+    <Command className="bg-transparent" shouldFilter={shouldFilter}>
+      <AutocompletePopover {...props} />
+    </Command>
+  );
+};

package/src/lib/components/Banner.tsx

@@ -0,0 +1,52 @@
+import { CircleXIcon } from "lucide-react";
+import { useState } from "react";
+import { cn } from "../util/cn.js";
+import { useZudoku } from "./context/ZudokuContext.js";
+
+const COLOR_MAP = {
+  info: "bg-blue-500",
+  note: "bg-gray-500",
+  tip: "bg-green-600",
+  caution: "bg-orange-500",
+  danger: "bg-rose-500",
+} as const;
+
+export const Banner = () => {
+  const { options } = useZudoku();
+  const { site } = options;
+  const [isBannerOpen, setIsBannerOpen] = useState(true);
+
+  if (!site?.banner || !isBannerOpen) {
+    return <style>{`:root { --banner-height: 0px; }`}</style>;
+  }
+
+  const mappedColor =
+    site.banner.color && site.banner.color in COLOR_MAP
+      ? COLOR_MAP[site.banner.color as keyof typeof COLOR_MAP]
+      : !site.banner.color
+        ? "bg-primary"
+        : undefined;
+
+  const style = !mappedColor ? { backgroundColor: site.banner.color } : {};
+
+  return (
+    <div
+      className={cn(
+        "relative text-primary-foreground text-sm font-medium px-4 py-2 flex gap-2 items-center lg:h-(--banner-height)",
+        mappedColor,
+      )}
+      style={style}
+    >
+      <div className="w-full">{site.banner.message}</div>
+      {site.banner.dismissible && (
+        <button
+          type="button"
+          className="md:absolute md:end-4 -m-1.5 p-1.5 hover:bg-accent-foreground/10 rounded-md"
+          onClick={() => setIsBannerOpen(false)}
+        >
+          <CircleXIcon size={16} />
+        </button>
+      )}
+    </div>
+  );
+};

package/src/lib/components/Bootstrap.tsx

@@ -0,0 +1,77 @@
+import {
+  HydrationBoundary,
+  QueryClient,
+  QueryClientProvider,
+} from "@tanstack/react-query";
+import { type HelmetData, HelmetProvider } from "@zudoku/react-helmet-async";
+import { StrictMode } from "react";
+import {
+  type createBrowserRouter,
+  type createStaticRouter,
+  type StaticHandlerContext,
+  StaticRouterProvider,
+} from "react-router";
+import { RouterProvider } from "react-router/dom";
+import {
+  RenderContext,
+  type RenderContextValue,
+} from "./context/RenderContext.js";
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5,
+    },
+  },
+});
+
+const Bootstrap = ({
+  router,
+  hydrate = false,
+}: {
+  hydrate?: boolean;
+  router: ReturnType<typeof createBrowserRouter>;
+}) => (
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      {/* biome-ignore lint/suspicious/noExplicitAny: Allow any type */}
+      <HydrationBoundary state={hydrate ? (window as any).DATA : undefined}>
+        <HelmetProvider>
+          <RouterProvider router={router} />
+        </HelmetProvider>
+      </HydrationBoundary>
+    </QueryClientProvider>
+  </StrictMode>
+);
+
+const BootstrapStatic = ({
+  router,
+  context,
+  queryClient,
+  helmetContext,
+  bypassProtection = false,
+  renderContext,
+}: {
+  helmetContext: HelmetData["context"];
+  context: StaticHandlerContext;
+  queryClient: QueryClient;
+  router: ReturnType<typeof createStaticRouter>;
+  bypassProtection?: boolean;
+  renderContext?: RenderContextValue;
+}) => (
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <HelmetProvider context={helmetContext}>
+        <RenderContext
+          value={
+            renderContext ?? { status: 200, bypassProtection: bypassProtection }
+          }
+        >
+          <StaticRouterProvider router={router} context={context} />
+        </RenderContext>
+      </HelmetProvider>
+    </QueryClientProvider>
+  </StrictMode>
+);
+
+export { Bootstrap, BootstrapStatic };

package/src/lib/components/BuildCheck.tsx

@@ -0,0 +1,87 @@
+import { useQuery } from "@tanstack/react-query";
+import { CircleFadingArrowUpIcon, LoaderCircleIcon } from "lucide-react";
+import { useEffect } from "react";
+import { z } from "zod/mini";
+import { Button } from "../ui/Button.js";
+
+const BuildStatusSchema = z.object({
+  buildId: z.string(),
+  timestamp: z.string(),
+  status: z.enum(["in-progress", "success", "failed"]),
+});
+
+export const BuildCheck = ({
+  buildId,
+  environmentType,
+  endpoint = "/__zuplo/docs",
+}: {
+  buildId?: string;
+  environmentType?: string;
+  endpoint?: string;
+}) => {
+  const buildStatusQuery = useQuery({
+    queryKey: ["zuplo-build-check", buildId, endpoint],
+    refetchInterval: 3000,
+    enabled: buildId !== undefined && environmentType === "WORKING_COPY",
+    retry: false,
+    queryFn: async () => {
+      const res = await fetch(endpoint, { signal: AbortSignal.timeout(2000) });
+      if (!res.ok) throw new Error("Failed to fetch build status");
+      const data: unknown = await res.json();
+      return BuildStatusSchema.parse(data);
+    },
+  });
+
+  useEffect(() => {
+    if (
+      buildStatusQuery.data?.status === "success" &&
+      buildStatusQuery.data.buildId
+    ) {
+      // biome-ignore lint/suspicious/noDocumentCookie: CookieStore too new to use
+      document.cookie = `zuplo-build=${buildStatusQuery.data.buildId}; path=/; max-age=300; secure; SameSite=None`;
+    }
+  }, [buildStatusQuery.data]);
+
+  if (
+    buildStatusQuery.isError ||
+    !buildStatusQuery.data ||
+    buildStatusQuery.data.buildId === buildId
+  ) {
+    return null;
+  }
+
+  const isCompleted = buildStatusQuery.data.status === "success";
+
+  return (
+    <div className="fixed flex flex-col gap-3 p-4 rounded-xl w-96 border z-20 bg-background left-0 right-0 top-4 mx-auto shadow-lg">
+      {isCompleted ? (
+        <div className="flex flex-row items-center gap-2">
+          <CircleFadingArrowUpIcon size={16} />
+          <span className="text-sm">New version available</span>
+        </div>
+      ) : (
+        <div className="flex flex-row items-center gap-2">
+          <LoaderCircleIcon size={16} className="animate-spin" />
+          <span className="text-sm">Building new version...</span>
+        </div>
+      )}
+      <span className="text-xs">
+        {!isCompleted
+          ? "A new version of the developer portal will be available soon."
+          : "To see the new version, reload the page now."}
+      </span>
+      {isCompleted && (
+        <Button
+          variant="outline"
+          size="sm"
+          className="w-full"
+          onClick={() => {
+            window.location.reload();
+          }}
+        >
+          Reload
+        </Button>
+      )}
+    </div>
+  );
+};

package/src/lib/components/CategoryHeading.tsx

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

package/src/lib/components/ClientOnly.tsx

@@ -0,0 +1,19 @@
+import { type ReactNode, useSyncExternalStore } from "react";
+
+const noop = () => () => {};
+
+export const useIsClient = () => {
+  const value = useSyncExternalStore(
+    noop,
+    () => "client",
+    () => "server",
+  );
+  return value === "client";
+};
+
+export const ClientOnly = (props: {
+  children: ReactNode;
+  fallback?: ReactNode;
+}) => {
+  return useIsClient() ? props.children : props.fallback;
+};

package/src/lib/components/DeveloperHint.tsx

@@ -0,0 +1,39 @@
+import {
+  Alert,
+  AlertDescription,
+  AlertTitle,
+} from "@lukoweb/apitogo/ui/Alert.js";
+import { InfoIcon } from "lucide-react";
+import { type ReactNode, Suspense, lazy } from "react";
+
+// Lazy: Markdown imports shiki.ts — keeping it out of the entry chunk.
+const Markdown = lazy(() =>
+  import("./Markdown.js").then((m) => ({ default: m.Markdown })),
+);
+
+export const DeveloperHint = ({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string;
+}) => {
+  if (process.env.NODE_ENV !== "development") return null;
+
+  return (
+    <Alert variant="info" className={className}>
+      <InfoIcon />
+      <AlertTitle>Developer hint</AlertTitle>
+      <AlertDescription>
+        {typeof children === "string" ? (
+          <Suspense>
+            <Markdown content={children} />
+          </Suspense>
+        ) : (
+          <div>{children}</div>
+        )}
+        <small className="italic">Only shown in development mode.</small>
+      </AlertDescription>
+    </Alert>
+  );
+};

package/src/lib/components/ErrorPage.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+import { CategoryHeading } from "./CategoryHeading.js";
+import { Heading } from "./Heading.js";
+import { Typography } from "./Typography.js";
+
+export const ErrorPage = ({
+  title = "An error occurred",
+  message,
+  category,
+}: {
+  title?: ReactNode;
+  message?: ReactNode;
+  category?: ReactNode;
+}) => {
+  return (
+    <Typography className={"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>
+    </Typography>
+  );
+};