zudoku 0.0.0-feat-bundled-types.9aa135e → 0.0.0-feat-openapi-docs-redesign.dab3fc6a

package/src/lib/plugins/markdown/MdxPage.tsx

@@ -1,19 +1,37 @@
 import { useMDXComponents } from "@mdx-js/react";
 import slugify from "@sindresorhus/slugify";
 import { Helmet } from "@zudoku/react-helmet-async";
-import { type PropsWithChildren, useEffect } from "react";
+import {
+  CheckIcon,
+  ChevronDownIcon,
+  CopyIcon,
+  EditIcon,
+  ExternalLinkIcon,
+  Link2Icon,
+} from "lucide-react";
+import { type PropsWithChildren, useEffect, useState } from "react";
+import { useLocation } from "react-router";
+import { Button } from "zudoku/ui/Button.js";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "zudoku/ui/DropdownMenu.js";
 import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
-import { ProseClasses } from "../../components/Markdown.js";
-import { Pagination } from "../../components/Pagination.js";
 import { Toc } from "../../components/navigation/Toc.js";
 import {
   useCurrentItem,
   usePrevNext,
 } from "../../components/navigation/utils.js";
+import { Pagination } from "../../components/Pagination.js";
+import { Typography } from "../../components/Typography.js";
+import { joinUrl } from "../../util/joinUrl.js";
 import type { MdxComponentsType } from "../../util/MdxComponents.js";
-import { cn } from "../../util/cn.js";
-import { type MarkdownPluginDefaultOptions, type MDXImport } from "./index.js";
+import { ChatGPTLogo } from "./assets/ChatGPTLogo.js";
+import { ClaudeLogo } from "./assets/ClaudeLogo.js";
+import type { MarkdownPluginDefaultOptions, MDXImport } from "./index.js";
 
 declare global {
   interface Window {
@@ -25,12 +43,12 @@ declare global {
 
 const MarkdownHeadings = {
   h2: ({ children, id }) => (
-    <Heading level={2} id={id} registerSidebarAnchor>
+    <Heading level={2} id={id} registerNavigationAnchor>
       {children}
     </Heading>
   ),
   h3: ({ children, id }) => (
-    <Heading level={3} id={id} registerSidebarAnchor>
+    <Heading level={3} id={id} registerNavigationAnchor>
       {children}
     </Heading>
   ),
@@ -38,27 +56,64 @@ const MarkdownHeadings = {
 
 export const MdxPage = ({
   mdxComponent: MdxComponent,
-  file,
+  basePath,
   frontmatter = {},
   defaultOptions,
+  __filepath,
   tableOfContents,
   excerpt,
 }: PropsWithChildren<
   Omit<MDXImport, "default"> & {
-    file: string;
+    basePath: string;
     mdxComponent: MDXImport["default"];
     defaultOptions?: MarkdownPluginDefaultOptions;
   }
 >) => {
   const categoryTitle = useCurrentItem()?.categoryLabel;
+  const location = useLocation();
+  const [isCopied, setIsCopied] = useState(false);
 
   const title = frontmatter.title;
+  const description = frontmatter.description ?? excerpt;
   const category = frontmatter.category ?? categoryTitle;
   const hideToc = frontmatter.toc === false || defaultOptions?.toc === false;
   const pageTitle =
-    tableOfContents.find((item) => item.depth === 1)?.value ?? title;
+    title ?? tableOfContents.find((item) => item.depth === 1)?.value;
   const hidePager =
-    frontmatter.disablePager ?? defaultOptions?.disablePager ?? false;
+    frontmatter.disable_pager ??
+    frontmatter.disablePager ??
+    defaultOptions?.disablePager ??
+    false;
+
+  const showLastModified =
+    frontmatter.showLastModified ?? defaultOptions?.showLastModified ?? true;
+
+  const lastModifiedDate = frontmatter.lastModifiedTime
+    ? new Date(frontmatter.lastModifiedTime)
+    : null;
+
+  const editConfig =
+    frontmatter.suggestEdit !== false &&
+    (frontmatter.suggestEdit ?? defaultOptions?.suggestEdit);
+
+  const editUrl = editConfig
+    ? editConfig.url.replaceAll("{filePath}", __filepath)
+    : null;
+  const editText = editConfig ? editConfig.text || "Edit this page" : null;
+
+  const copyMarkdownConfig =
+    frontmatter.copyPage !== false && defaultOptions?.copyPage !== false;
+
+  const markdownUrl = joinUrl(basePath, `${location.pathname}.md`);
+
+  const handleCopyMarkdown = async () => {
+    const response = await fetch(markdownUrl);
+    if (!response.ok) throw new Error("Failed to fetch markdown");
+    const markdown = await response.text();
+    void navigator.clipboard.writeText(markdown);
+    setIsCopied(true);
+    setTimeout(() => setIsCopied(false), 2000);
+  };
 
   const tocEntries =
     tableOfContents.find((item) => item.depth === 1)?.children ??
@@ -72,7 +127,7 @@ export const MdxPage = ({
   useEffect(() => {
     if (process.env.NODE_ENV === "development") {
       window.__getReactRefreshIgnoredExports = ({ id }) => {
-        if (!id.endsWith(file)) return;
+        if (!id.endsWith(__filepath)) return;
 
         return ["frontmatter", "tableOfContents"];
       };
@@ -81,7 +136,7 @@ export const MdxPage = ({
         window.__getReactRefreshIgnoredExports = undefined;
       };
     }
-  }, [file]);
+  }, [__filepath]);
 
   return (
     <div
@@ -91,39 +146,156 @@ export const MdxPage = ({
     >
       <Helmet>
         <title>{pageTitle}</title>
-        {excerpt && <meta name="description" content={excerpt} />}
+        {description && <meta name="description" content={description} />}
       </Helmet>
-      <div
-        className={cn(
-          ProseClasses,
-          "max-w-full xl:w-full xl:max-w-3xl flex-1 shrink pt-(--padding-content-top)",
-        )}
-      >
+      <Typography className="max-w-full xl:w-full xl:max-w-3xl flex-1 shrink pt-(--padding-content-top)">
         {(category || title) && (
-          <header>
-            {category && <CategoryHeading>{category}</CategoryHeading>}
-            {title && (
-              <Heading level={1} id={slugify(title)}>
-                {title}
-              </Heading>
+          <header className="flex items-start justify-between gap-4">
+            <div className="flex-1">
+              {category && <CategoryHeading>{category}</CategoryHeading>}
+              {title && (
+                <Heading level={1} id={slugify(title)}>
+                  {title}
+                </Heading>
+              )}
+            </div>
+            {copyMarkdownConfig && (
+              <div className="flex items-center border rounded-md">
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={handleCopyMarkdown}
+                  className="rounded-r-none border-r gap-2 h-7"
+                >
+                  {isCopied ? (
+                    <CheckIcon size={14} className="text-emerald-600" />
+                  ) : (
+                    <CopyIcon size={14} />
+                  )}
+                  <span>Copy page</span>
+                </Button>
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <Button
+                      variant="ghost"
+                      size="icon-xs"
+                      className="rounded-l-none"
+                    >
+                      <ChevronDownIcon size={14} />
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent align="end">
+                    <DropdownMenuItem
+                      className="gap-2"
+                      onClick={() =>
+                        void navigator.clipboard.writeText(window.location.href)
+                      }
+                    >
+                      <Link2Icon className="size-4" />
+                      Copy link to page
+                    </DropdownMenuItem>
+                    <DropdownMenuItem className="gap-2" asChild>
+                      <a
+                        href={markdownUrl}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                      >
+                        <ExternalLinkIcon className="size-4" />
+                        Open Markdown page
+                      </a>
+                    </DropdownMenuItem>
+                    <DropdownMenuItem
+                      className="gap-2"
+                      onClick={() => {
+                        const prompt = encodeURIComponent(
+                          `Help me understand this documentation page: ${window.location.href}`,
+                        );
+                        window.open(
+                          `https://claude.ai/new?q=${prompt}`,
+                          "_blank",
+                        );
+                      }}
+                    >
+                      <ClaudeLogo className="size-4" />
+                      Open in Claude
+                    </DropdownMenuItem>
+                    <DropdownMenuItem
+                      className="gap-2"
+                      onClick={() => {
+                        const prompt = encodeURIComponent(
+                          `Help me understand this documentation page: ${window.location.href}`,
+                        );
+                        window.open(
+                          `https://chatgpt.com/?q=${prompt}`,
+                          "_blank",
+                        );
+                      }}
+                    >
+                      <ChatGPTLogo className="size-4" />
+                      Open in ChatGPT
+                    </DropdownMenuItem>
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              </div>
             )}
           </header>
         )}
+
         <MdxComponent
           components={{ ...useMDXComponents(), ...MarkdownHeadings }}
         />
+        <div className="h-16" />
+        {(showLastModified && lastModifiedDate) || editUrl ? (
+          <div className="flex justify-between text-xs text-muted-foreground ">
+            <div />
+            <div className="flex items-center gap-2">
+              <div>
+                {editUrl && (
+                  <Button asChild variant="ghost" size="sm">
+                    <a
+                      href={editUrl}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      className="flex items-center gap-1"
+                    >
+                      <EditIcon size={12} />
+                      {editText}
+                    </a>
+                  </Button>
+                )}
+              </div>
+              <div>
+                {showLastModified && lastModifiedDate && (
+                  <div
+                    title={lastModifiedDate.toLocaleString(undefined, {
+                      dateStyle: "full",
+                      timeStyle: "medium",
+                    })}
+                  >
+                    Last modified on{" "}
+                    <time dateTime={lastModifiedDate.toISOString()}>
+                      {lastModifiedDate.toLocaleDateString("en-US", {
+                        dateStyle: "long",
+                      })}
+                    </time>
+                  </div>
+                )}
+              </div>
+            </div>
+          </div>
+        ) : null}
         {!hidePager && (
           <>
-            <hr className="my-10" />
+            <div className="h-px bg-border mt-2 mb-6" />
             <Pagination
-              prev={prev ? { to: prev.id, label: prev.label } : undefined}
-              next={next ? { to: next.id, label: next.label } : undefined}
-              className="mb-4"
+              prev={prev ? { to: prev.id, label: prev.label ?? "" } : undefined}
+              next={next ? { to: next.id, label: next.label ?? "" } : undefined}
+              className="mb-10"
             />
           </>
         )}
-      </div>
-      <div className="hidden xl:block">
+      </Typography>
+      <div className="hidden xl:block" data-pagefind-ignore="all">
         {showToc && <Toc entries={tocEntries} />}
       </div>
     </div>

package/src/lib/plugins/markdown/assets/ChatGPTLogo.tsx

@@ -0,0 +1,11 @@
+import type { SVGProps } from "react";
+
+export const ChatGPTLogo = (props: SVGProps<SVGSVGElement>) => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 320" {...props}>
+    <title>ChatGPT</title>
+    <path
+      fill="currentColor"
+      d="M297.06 130.97a79.712 79.712 0 0 0-6.85-65.48c-17.46-30.4-52.56-46.04-86.84-38.68A79.747 79.747 0 0 0 143.24 0C108.2-.08 77.11 22.48 66.33 55.82a79.754 79.754 0 0 0-53.31 38.67c-17.59 30.32-13.58 68.54 9.92 94.54a79.712 79.712 0 0 0 6.85 65.48c17.46 30.4 52.56 46.04 86.84 38.68a79.687 79.687 0 0 0 60.13 26.8c35.06.09 66.16-22.49 76.94-55.86a79.754 79.754 0 0 0 53.31-38.67c17.57-30.32 13.55-68.51-9.94-94.51zM176.78 299.08a59.77 59.77 0 0 1-38.39-13.88c.49-.26 1.34-.73 1.89-1.07l63.72-36.8a10.36 10.36 0 0 0 5.24-9.07v-89.83l26.93 15.55c.29.14.48.42.52.74v74.39c-.04 33.08-26.83 59.9-59.91 59.97zM47.94 244.05a59.71 59.71 0 0 1-7.15-40.18c.47.28 1.3.79 1.89 1.13l63.72 36.8c3.23 1.89 7.23 1.89 10.47 0l77.79-44.92v31.1c.02.32-.13.63-.38.83L129.87 266c-28.69 16.52-65.33 6.7-81.92-21.95zM31.17 104.96c7-12.16 18.05-21.46 31.21-26.29 0 .55-.03 1.52-.03 2.2v73.61c-.02 3.74 1.98 7.21 5.23 9.06l77.79 44.91L118.44 224c-.27.18-.61.21-.91.08l-64.42-37.22c-28.63-16.58-38.45-53.21-21.95-81.89zm221.26 51.49-77.79-44.92 26.93-15.54c.27-.18.61-.21.91-.08l64.42 37.19c28.68 16.57 38.51 53.26 21.94 81.94a59.94 59.94 0 0 1-31.2 26.28v-75.81c.03-3.74-1.96-7.2-5.2-9.06zm26.8-40.34c-.47-.29-1.3-.79-1.89-1.13l-63.72-36.8a10.375 10.375 0 0 0-10.47 0l-77.79 44.92V92c-.02-.32.13-.63.38-.83l64.41-37.16c28.69-16.55 65.37-6.7 81.91 22a59.95 59.95 0 0 1 7.15 40.1zm-168.51 55.43-26.94-15.55a.943.943 0 0 1-.52-.74V80.86c.02-33.12 26.89-59.96 60.01-59.94 14.01 0 27.57 4.92 38.34 13.88-.49.26-1.33.73-1.89 1.07L116 72.67a10.344 10.344 0 0 0-5.24 9.06l-.04 89.79zM125.35 140 160 119.99l34.65 20V180L160 200l-34.65-20z"
+    />
+  </svg>
+);

package/src/lib/plugins/markdown/assets/ClaudeLogo.tsx

@@ -0,0 +1,19 @@
+import type { SVGProps } from "react";
+
+export const ClaudeLogo = (props: SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="1em"
+    height="1em"
+    fill="currentColor"
+    fillRule="evenodd"
+    viewBox="0 0 24 24"
+    {...props}
+  >
+    <title>Claude</title>
+    <path
+      fill="#D97757"
+      d="m4.709 15.955 4.72-2.647.08-.23-.08-.128H9.2l-.79-.048-2.698-.073-2.339-.097-2.266-.122-.571-.121L0 11.784l.055-.352.48-.321.686.06 1.52.103 2.278.158 1.652.097 2.449.255h.389l.055-.157-.134-.098-.103-.097-2.358-1.596-2.552-1.688-1.336-.972-.724-.491-.364-.462-.158-1.008.656-.722.881.06.225.061.893.686 1.908 1.476 2.491 1.833.365.304.145-.103.019-.073-.164-.274-1.355-2.446-1.446-2.49-.644-1.032-.17-.619a2.97 2.97 0 0 1-.104-.729L6.283.134 6.696 0l.996.134.42.364.62 1.414 1.002 2.229 1.555 3.03.456.898.243.832.091.255h.158V9.01l.128-1.706.237-2.095.23-2.695.08-.76.376-.91.747-.492.584.28.48.685-.067.444-.286 1.851-.559 2.903-.364 1.942h.212l.243-.242.985-1.306 1.652-2.064.73-.82.85-.904.547-.431h1.033l.76 1.129-.34 1.166-1.064 1.347-.881 1.142-1.264 1.7-.79 1.36.073.11.188-.02 2.856-.606 1.543-.28 1.841-.315.833.388.091.395-.328.807-1.969.486-2.309.462-3.439.813-.042.03.049.061 1.549.146.662.036h1.622l3.02.225.79.522.474.638-.079.485-1.215.62-1.64-.389-3.829-.91-1.312-.329h-.182v.11l1.093 1.068 2.006 1.81 2.509 2.33.127.578-.322.455-.34-.049-2.205-1.657-.851-.747-1.926-1.62h-.128v.17l.444.649 2.345 3.521.122 1.08-.17.353-.608.213-.668-.122-1.374-1.925-1.415-2.167-1.143-1.943-.14.08-.674 7.254-.316.37-.729.28-.607-.461-.322-.747.322-1.476.389-1.924.315-1.53.286-1.9.17-.632-.012-.042-.14.018-1.434 1.967-2.18 2.945-1.726 1.845-.414.164-.717-.37.067-.662.401-.589 2.388-3.036 1.44-1.882.93-1.086-.006-.158h-.055L4.132 18.56l-1.13.146-.487-.456.061-.746.231-.243 1.908-1.312z"
+    />
+  </svg>
+);

package/src/lib/plugins/markdown/index.tsx

@@ -1,17 +1,16 @@
 import type { Toc } from "@stefanprobst/rehype-extract-toc";
 import type { MDXProps } from "mdx/types.js";
-import { type JSX } from "react";
-import type { RouteObject } from "react-router";
+import type { JSX } from "react";
 import type { ZudokuDocsConfig } from "../../../config/validators/validate.js";
 import type { ZudokuPlugin } from "../../core/plugins.js";
-import { DocResolver } from "./resolver.js";
 
 export interface MarkdownPluginOptions extends ZudokuDocsConfig {
+  basePath: string;
   fileImports: Record<string, () => Promise<MDXImport>>;
 }
 export type MarkdownPluginDefaultOptions = Pick<
   Frontmatter,
-  "toc" | "disablePager"
+  "toc" | "disablePager" | "showLastModified" | "suggestEdit" | "copyPage"
 >;
 
 export type Frontmatter = {
@@ -20,57 +19,43 @@ export type Frontmatter = {
   category?: string;
   toc?: boolean;
   disablePager?: boolean;
+  disable_pager?: boolean;
+  showLastModified?: boolean;
+  lastModifiedTime?: number;
+  suggestEdit?: { url: string; text?: string } | false;
+  copyPage?: boolean;
 };
 
 export type MDXImport = {
   tableOfContents: Toc;
   frontmatter: Frontmatter;
   excerpt?: string;
+  __filepath: string;
   default: (props: MDXProps) => JSX.Element;
 };
 
 export const markdownPlugin = (
-  options: MarkdownPluginOptions[],
+  options: MarkdownPluginOptions,
 ): ZudokuPlugin => ({
   getRoutes: () => {
-    const routeMap = new Map<string, RouteObject>();
-    options.forEach(({ fileImports, files, defaultOptions }) =>
-      Object.entries(fileImports).flatMap(([file, importPromise]) => {
-        const routePath = DocResolver.resolveRoutePath({
-          filesGlob: files,
-          fsPath: file,
-        });
-
-        if (!routePath) return [];
-
-        if (routeMap.has(routePath)) {
-          // eslint-disable-next-line no-console
-          console.warn(
-            `Duplicate route path found for ${routePath}. Skipping file at '${file}'.`,
-          );
-          return [];
-        }
-
-        const route: RouteObject = {
-          path: routePath,
-          lazy: async () => {
-            const { MdxPage } = await import("./MdxPage.js");
-            const { default: Component, ...props } = await importPromise();
-            return {
-              element: (
-                <MdxPage
-                  file={file}
-                  mdxComponent={Component}
-                  {...props}
-                  defaultOptions={defaultOptions}
-                />
-              ),
-            };
-          },
-        };
-        routeMap.set(routePath, route);
+    return Object.entries(options.fileImports).map(
+      ([routePath, importPromise]) => ({
+        path: routePath,
+        lazy: async () => {
+          const { MdxPage } = await import("./MdxPage.js");
+          const { default: Component, ...props } = await importPromise();
+          return {
+            element: (
+              <MdxPage
+                basePath={options.basePath}
+                mdxComponent={Component}
+                {...props}
+                defaultOptions={options.defaultOptions}
+              />
+            ),
+          };
+        },
       }),
     );
-    return [...routeMap.values()];
   },
 });

package/src/lib/plugins/openapi/CollapsibleCode.tsx

@@ -9,6 +9,10 @@ import {
 import { cn } from "../../util/cn.js";
 import useIsomorphicLayoutEffect from "../../util/useIsomorphicLayoutEffect.js";
 
+export const OverflowOverlay = () => (
+  <div className="absolute inset-0 bg-linear-to-b from-transparent to-zinc-50/60 dark:to-zinc-950/90 z-10 transition-all group-hover:to-transparent" />
+);
+
 export const CollapsibleCode = ({
   children,
   maxHeight = 250,
@@ -48,9 +52,7 @@ export const CollapsibleCode = ({
           !open && isOverflowing && "max-h-(--max-height)",
         )}
       >
-        {!open && isOverflowing && (
-          <div className=" absolute inset-0 bg-gradient-to-b from-transparent to-zinc-50/60 dark:to-zinc-950/90 z-10 transition-all group-hover:to-transparent"></div>
-        )}
+        {!open && isOverflowing && <OverflowOverlay />}
         <div ref={contentRef}>{children}</div>
         {!open && isOverflowing && (
           <CollapsibleTrigger

package/src/lib/plugins/openapi/ColorizedParam.tsx

@@ -1,5 +1,5 @@
 import { useTheme } from "next-themes";
-import { useEffect, useRef, type CSSProperties, type ReactNode } from "react";
+import { type CSSProperties, type ReactNode, useEffect, useRef } from "react";
 import { cn } from "../../util/cn.js";
 import { pastellize } from "../../util/pastellize.js";
 
@@ -86,6 +86,8 @@ export const ColorizedParam = ({
   }, [normalizedSlug]);
 
   return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: Just passing props through
+    // biome-ignore lint/a11y/useKeyWithClickEvents: Just passing props through
     <span
       {...{ [DATA_ATTR]: normalizedSlug }}
       className={cn(

package/src/lib/plugins/openapi/Endpoint.tsx

@@ -54,9 +54,9 @@ export const Endpoint = () => {
 
   const { servers } = result.data.schema;
 
-  if (servers.length === 0) return null;
+  const firstServer = servers.at(0);
 
-  const firstServer = servers.at(0)!;
+  if (!firstServer) return null;
 
   if (servers.length === 1) {
     return (

package/src/lib/plugins/openapi/GeneratedExampleSidecarBox.tsx

@@ -0,0 +1,52 @@
+import { InfoIcon } from "lucide-react";
+import { SyntaxHighlight } from "zudoku/ui/SyntaxHighlight.js";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "zudoku/ui/Tooltip.js";
+import { NonHighlightedCode } from "./components/NonHighlightedCode.js";
+import * as SidecarBox from "./SidecarBox.js";
+
+export const GeneratedExampleSidecarBox = ({
+  code,
+  isOnScreen,
+  shouldLazyHighlight,
+}: {
+  code: string;
+  isOnScreen: boolean;
+  shouldLazyHighlight?: boolean;
+}) => {
+  return (
+    <SidecarBox.Root>
+      <SidecarBox.Head className="text-xs flex justify-between items-center">
+        <div className="flex items-center gap-1.5">
+          <span className="font-medium">Request Body Example</span>
+          <TooltipProvider>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <InfoIcon size={13} />
+              </TooltipTrigger>
+              <TooltipContent>
+                This example is auto-generated from the schema.
+              </TooltipContent>
+            </Tooltip>
+          </TooltipProvider>
+        </div>
+      </SidecarBox.Head>
+      <SidecarBox.Body className="p-0">
+        {shouldLazyHighlight && !isOnScreen ? (
+          <NonHighlightedCode code={code} />
+        ) : (
+          <SyntaxHighlight
+            embedded
+            language="json"
+            code={code}
+            className="[--scrollbar-color:gray] rounded-none text-xs max-h-[200px]"
+          />
+        )}
+      </SidecarBox.Body>
+    </SidecarBox.Root>
+  );
+};