zudoku 0.0.0-feat-openapi-docs-redesign.dab3fc6a → 0.0.0-feat-navigation-at-property.z8cd07fa5

package/src/lib/plugins/api-keys/settings/RevealApiKey.tsx

@@ -0,0 +1,124 @@
+import { TrashIcon } from "lucide-react";
+import { useState } from "react";
+import { Button } from "zudoku/ui/Button.js";
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "zudoku/ui/Dialog.js";
+import { Secret } from "zudoku/ui/Secret.js";
+import { cn } from "../../../util/cn.js";
+import type { ApiKey } from "../index.js";
+
+export const RevealApiKey = ({
+  apiKey,
+  onDeleteKey,
+  className,
+}: {
+  apiKey: ApiKey;
+  onDeleteKey: () => void;
+  className?: string;
+}) => {
+  const [revealed, setRevealed] = useState(false);
+
+  const { key, createdOn, expiresOn } = apiKey;
+  const isExpired = expiresOn && new Date(expiresOn) < new Date();
+  const daysUntilExpiry = expiresOn
+    ? Math.ceil(
+        (new Date(expiresOn).getTime() - Date.now()) / (1000 * 60 * 60 * 24),
+      )
+    : Infinity;
+  const expiresSoon = daysUntilExpiry <= 7 && !isExpired;
+
+  return (
+    <div className={cn("grid col-span-full grid-cols-subgrid p-6", className)}>
+      <div className="flex flex-col gap-1">
+        <Secret
+          className="max-w-fit w-full"
+          secret={key}
+          status={isExpired ? "expired" : expiresSoon ? "expiring" : "active"}
+          revealed={revealed}
+          onReveal={setRevealed}
+        />
+        <div className="flex gap-1 mt-0.5 text-nowrap">
+          {createdOn && (
+            <span className="text-xs text-muted-foreground">
+              Created {getTimeAgo(createdOn)}.
+            </span>
+          )}{" "}
+          {expiresOn && expiresSoon && (
+            <span className="text-xs text-primary">
+              Expires in {daysUntilExpiry}{" "}
+              {daysUntilExpiry === 1 ? "day" : "days"}.
+            </span>
+          )}
+          {expiresOn && isExpired && (
+            <span className="text-xs text-primary">
+              Expired{" "}
+              {daysUntilExpiry === 0
+                ? "today."
+                : `${daysUntilExpiry * -1} days ago.`}
+            </span>
+          )}
+        </div>
+      </div>
+      <div className="flex justify-end">
+        {expiresOn && onDeleteKey && (
+          <Dialog>
+            <DialogTrigger asChild>
+              <Button variant="ghost" size="icon">
+                <TrashIcon size={16} />
+              </Button>
+            </DialogTrigger>
+            <DialogContent>
+              <DialogHeader>
+                <DialogTitle>Delete API Key</DialogTitle>
+                <DialogDescription>
+                  Are you sure you want to delete this API key?
+                </DialogDescription>
+              </DialogHeader>
+              <DialogFooter>
+                <DialogClose asChild>
+                  <Button variant="outline">Cancel</Button>
+                </DialogClose>
+                <DialogClose asChild>
+                  <Button
+                    onClick={() => {
+                      onDeleteKey();
+                    }}
+                  >
+                    Delete
+                  </Button>
+                </DialogClose>
+              </DialogFooter>
+            </DialogContent>
+          </Dialog>
+        )}
+      </div>
+    </div>
+  );
+};
+
+const getTimeAgo = (date: string) => {
+  const now = new Date();
+  const created = new Date(date);
+  const diffInSeconds = Math.floor((now.getTime() - created.getTime()) / 1000);
+
+  const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
+
+  if (diffInSeconds < 60) return rtf.format(-diffInSeconds, "second");
+  if (diffInSeconds < 3600)
+    return rtf.format(-Math.floor(diffInSeconds / 60), "minute");
+  if (diffInSeconds < 86400)
+    return rtf.format(-Math.floor(diffInSeconds / 3600), "hour");
+  if (diffInSeconds < 2592000)
+    return rtf.format(-Math.floor(diffInSeconds / 86400), "day");
+  if (diffInSeconds < 31536000)
+    return rtf.format(-Math.floor(diffInSeconds / 2592000), "month");
+  return rtf.format(-Math.floor(diffInSeconds / 31536000), "year");
+};

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

@@ -0,0 +1,115 @@
+import {
+  ChevronDownIcon,
+  CopyIcon,
+  DownloadIcon,
+  ExternalLinkIcon,
+} from "lucide-react";
+import type { MouseEventHandler } from "react";
+import { Button } from "zudoku/components";
+import { ButtonGroup } from "zudoku/ui/ButtonGroup.js";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "zudoku/ui/DropdownMenu.js";
+import { useCopyToClipboard } from "../../util/useCopyToClipboard.js";
+import { ChatGPTLogo } from "../markdown/assets/ChatGPTLogo.js";
+import { ClaudeLogo } from "../markdown/assets/ClaudeLogo.js";
+
+export const DownloadSchemaButton = ({
+  downloadUrl,
+}: {
+  downloadUrl: string;
+}) => {
+  const [, copyToClipboard] = useCopyToClipboard();
+
+  const handleDownload: MouseEventHandler<HTMLAnchorElement> = async (e) => {
+    const isExternal = downloadUrl.includes("://");
+
+    if (!isExternal) return;
+
+    e.preventDefault();
+    try {
+      const response = await fetch(downloadUrl);
+      if (!response.ok)
+        throw new Error(`Failed to fetch: ${response.statusText}`);
+
+      const blob = await response.blob();
+      const url = window.URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = downloadUrl.split("/").pop() || "schema.json";
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      window.URL.revokeObjectURL(url);
+    } catch (error) {
+      // biome-ignore lint/suspicious/noConsole: Logging error
+      console.error("Failed to download schema:", error);
+    }
+  };
+
+  return (
+    <ButtonGroup>
+      <Button
+        variant="outline"
+        size="sm"
+        className="flex items-center gap-1.5"
+        asChild
+      >
+        <a href={downloadUrl} download onClick={handleDownload}>
+          <DownloadIcon size={14} />
+          Download schema
+        </a>
+      </Button>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button size="sm" variant="outline" className="px-1.5">
+            <ChevronDownIcon size={14} />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem asChild>
+            <a href={downloadUrl} target="_blank" rel="noopener noreferrer">
+              <ExternalLinkIcon size={14} />
+              Open in new tab
+            </a>
+          </DropdownMenuItem>
+          <DropdownMenuItem
+            onClick={async () => {
+              const response = await fetch(downloadUrl);
+              const schema = await response.text();
+              copyToClipboard(schema);
+            }}
+          >
+            <CopyIcon size={14} />
+            Copy to clipboard
+          </DropdownMenuItem>
+          <DropdownMenuItem
+            onClick={() => {
+              const prompt = encodeURIComponent(
+                `Help me understand this API: ${new URL(downloadUrl, window.location.href).href}`,
+              );
+              window.open(`https://claude.ai/new?q=${prompt}`, "_blank");
+            }}
+          >
+            <ClaudeLogo className="size-4" />
+            Use in Claude
+          </DropdownMenuItem>
+          <DropdownMenuItem
+            onClick={() => {
+              const prompt = encodeURIComponent(
+                `Help me understand this API: ${new URL(downloadUrl, window.location.href).href}`,
+              );
+              window.open(`https://chatgpt.com/?q=${prompt}`, "_blank");
+            }}
+          >
+            <ChatGPTLogo className="size-4" />
+            Use in ChatGPT
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </ButtonGroup>
+  );
+};

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

@@ -32,7 +32,7 @@ const CopyButton = ({ url }: { url: string }) => {
         });
       }}
       variant="ghost"
-      size="icon"
+      size="icon-xs"
     >
       {isCopied ? (
         <CheckIcon className="text-green-600" size={14} />
@@ -53,40 +53,33 @@ export const Endpoint = () => {
   );
 
   const { servers } = result.data.schema;
-
   const firstServer = servers.at(0);
 
   if (!firstServer) return null;
 
-  if (servers.length === 1) {
-    return (
-      <div className="flex items-center gap-2">
-        <span className="font-medium text-sm">Endpoint:</span>
+  return (
+    <div className="flex items-center gap-1.5 flex-nowrap">
+      <span className="font-medium text-sm">Endpoint</span>
+      {servers.length > 1 ? (
+        <SimpleSelect
+          className="font-mono text-xs border-input bg-transparent dark:bg-input/30 dark:hover:bg-input/50 py-1.5 max-w-[450px] truncate"
+          onChange={(e) =>
+            startTransition(() => setSelectedServer(e.target.value))
+          }
+          value={selectedServer}
+          showChevrons={servers.length > 1}
+          options={servers.map((server) => ({
+            value: server.url,
+            label: server.url,
+          }))}
+        />
+      ) : (
         <InlineCode className="text-xs px-2 py-1.5" selectOnClick>
           {firstServer.url}
         </InlineCode>
-        <CopyButton url={firstServer.url} />
-      </div>
-    );
-  }
-
-  return (
-    <div className="flex flex-wrap items-center gap-2">
-      <span className="font-medium text-sm">Endpoint</span>
+      )}
 
-      <SimpleSelect
-        className="font-mono text-xs bg-border/50 dark:bg-border/70 py-1.5 max-w-[450px] truncate"
-        onChange={(e) =>
-          startTransition(() => setSelectedServer(e.target.value))
-        }
-        value={selectedServer}
-        showChevrons={servers.length > 1}
-        options={servers.map((server) => ({
-          value: server.url,
-          label: server.url,
-        }))}
-      />
-      <CopyButton url={selectedServer} />
+      <CopyButton url={servers.length > 1 ? selectedServer : firstServer.url} />
     </div>
   );
 };

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

@@ -22,7 +22,7 @@ export const GeneratedExampleSidecarBox = ({
     <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>
+          <span className="font-medium">Example Request Body</span>
           <TooltipProvider>
             <Tooltip>
               <TooltipTrigger asChild>

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

@@ -1,11 +1,11 @@
 import { useMemo } from "react";
 import { Outlet } from "react-router";
-import { joinPath } from "../../util/joinPath.js";
+import { joinUrl } from "../../util/joinUrl.js";
 import type { GraphQLClient } from "./client/GraphQLClient.js";
 import { GraphQLProvider } from "./client/GraphQLContext.js";
 import { OasConfigProvider } from "./context.js";
 import type { OasPluginConfig } from "./interfaces.js";
-import { getVersions } from "./util/getRoutes.js";
+import { getVersionMetadata } from "./util/getRoutes.js";
 
 export const OasProvider = ({
   basePath,
@@ -19,25 +19,46 @@ export const OasProvider = ({
   client: GraphQLClient;
 }) => {
   const value = useMemo(() => {
-    const versions = getVersions(config);
-    const firstVersion = Object.values(config.input).at(0);
-    const input =
-      config.type === "file"
-        ? {
-            type: config.type,
-            // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
-            input: version ? config.input[version]! : firstVersion!,
-          }
-        : { type: config.type, input: config.input };
+    const {
+      versions: availableVersions,
+      labels,
+      downloadUrls,
+    } = getVersionMetadata(config);
+    const currentVersion = version ?? availableVersions.at(0);
+
+    const versionLinks = Object.fromEntries(
+      availableVersions.map((id) => [
+        id,
+        {
+          path: joinUrl(basePath, id),
+          label: labels[id] ?? id,
+          downloadUrl: downloadUrls[id],
+        },
+      ]),
+    );
+
+    const resolveInput = (): string | (() => Promise<unknown>) => {
+      if (!Array.isArray(config.input)) {
+        return config.input;
+      }
+
+      const versionConfig = currentVersion
+        ? config.input.find((v) => v.path === currentVersion)
+        : config.input[0];
+
+      if (!versionConfig) {
+        throw new Error(`No input found for version: ${currentVersion}`);
+      }
+
+      return versionConfig.input;
+    };
 
     return {
       config: {
         ...config,
-        version: version ?? versions.at(0),
-        versions: Object.fromEntries(
-          versions.map((version) => [version, joinPath(basePath, version)]),
-        ),
-        ...input,
+        version: currentVersion,
+        versions: versionLinks,
+        input: resolveInput(),
       },
     };
   }, [config, basePath, version]);

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

@@ -18,9 +18,12 @@ import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { useApiIdentities } from "../../components/context/ZudokuContext.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
+import { usePrevNext } from "../../components/navigation/utils.js";
+import { PagefindSearchMeta } from "../../components/PagefindSearchMeta.js";
 import { Pagination } from "../../components/Pagination.js";
 import { useCreateQuery } from "./client/useCreateQuery.js";
 import { useOasConfig } from "./context.js";
+import { DownloadSchemaButton } from "./DownloadSchemaButton.js";
 import { Endpoint } from "./Endpoint.js";
 import { graphql } from "./graphql/index.js";
 import { UNTAGGED_PATH } from "./index.js";
@@ -163,11 +166,7 @@ export const OperationList = ({
     tag: tag ?? tagFromParams,
     untagged,
   });
-  const result = useSuspenseQuery(query);
-  const {
-    data: { schema },
-  } = result;
-  // Global server selection for the dropdown UI
+  const schema = useSuspenseQuery(query).data.schema;
   const { selectedServer: globalSelectedServer } = useSelectedServer(
     schema.servers,
   );
@@ -175,6 +174,7 @@ export const OperationList = ({
   const summary = schema.summary;
   const description = schema.description;
   const navigate = useNavigate();
+  const { prev: navPrev, next: navNext } = usePrevNext();
 
   // This is to warmup (i.e. load the schema in the background) the schema on the client, if the page has been rendered on the server
   const warmupQuery = useCreateQuery(SchemaWarmupQuery, { input, type });
@@ -229,7 +229,9 @@ export const OperationList = ({
           to: `../${prev.slug}`,
           label: prev.extensions?.["x-displayName"] ?? prev.name,
         }
-      : undefined,
+      : navPrev
+        ? { to: navPrev.id, label: navPrev.label }
+        : undefined,
     next: next
       ? {
           to: `../${next.slug ?? UNTAGGED_PATH}`,
@@ -238,18 +240,29 @@ export const OperationList = ({
             next.name ??
             "Other endpoints",
         }
-      : undefined,
+      : navNext
+        ? { to: navNext.id, label: navNext.label }
+        : undefined,
   };
 
   const tagTitle = schema.tag.extensions?.["x-displayName"] ?? schema.tag.name;
   const helmetTitle = [tagTitle, title].filter(Boolean).join(" - ");
 
+  const currentVersion = version != null ? versions[version] : undefined;
+  const downloadUrl =
+    typeof input === "string"
+      ? type === "url"
+        ? input
+        : currentVersion?.downloadUrl
+      : undefined;
+
   return (
     <div
       className="pt-(--padding-content-top)"
       data-pagefind-filter="section:openapi"
       data-pagefind-meta="section:openapi"
     >
+      <PagefindSearchMeta name="category">{title}</PagefindSearchMeta>
       <Helmet>
         {helmetTitle && <title>{helmetTitle}</title>}
         {metaDescription && (
@@ -262,7 +275,7 @@ export const OperationList = ({
           className="w-full"
           defaultOpen={options?.expandApiInformation}
         >
-          <div className="flex flex-col gap-y-4 sm:flex-row justify-around items-start sm:items-end">
+          <div className="flex flex-col gap-4 sm:flex-row justify-around items-start sm:items-end">
             <div className="flex flex-col flex-1 gap-2">
               <CategoryHeading>{title}</CategoryHeading>
               <Heading
@@ -275,32 +288,39 @@ export const OperationList = ({
                 {showVersions && (
                   <span className="text-xl text-muted-foreground ms-1.5">
                     {" "}
-                    ({version})
+                    ({schema.version})
                   </span>
                 )}
               </Heading>
               <Endpoint />
             </div>
             <div className="flex flex-col gap-4 sm:items-end">
-              {showVersions && (
-                <Select
-                  // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
-                  onValueChange={(version) => navigate(versions[version]!)}
-                  defaultValue={version}
-                  disabled={!hasMultipleVersions}
-                >
-                  <SelectTrigger className="w-[180px]">
-                    <SelectValue placeholder="Select version" />
-                  </SelectTrigger>
-                  <SelectContent>
-                    {Object.entries(versions).map(([version]) => (
-                      <SelectItem key={version} value={version}>
-                        {version}
-                      </SelectItem>
-                    ))}
-                  </SelectContent>
-                </Select>
-              )}
+              <div className="flex gap-2 items-center">
+                {showVersions && (
+                  <Select
+                    onValueChange={(version) =>
+                      // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
+                      navigate(versions[version]!.path)
+                    }
+                    defaultValue={version}
+                    disabled={!hasMultipleVersions}
+                  >
+                    <SelectTrigger className="w-[180px]" size="sm">
+                      <SelectValue placeholder="Select version" />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {Object.entries(versions).map(([version, { label }]) => (
+                        <SelectItem key={version} value={version}>
+                          {label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                )}
+                {options?.schemaDownload?.enabled && downloadUrl && (
+                  <DownloadSchemaButton downloadUrl={downloadUrl} />
+                )}
+              </div>
               {schema.description && (
                 <CollapsibleTrigger className="flex items-center gap-1 text-sm font-medium text-muted-foreground group">
                   <span>API information</span>

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

@@ -1,9 +1,9 @@
-import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
 import { useState } from "react";
 import { Badge } from "zudoku/ui/Badge.js";
 import { Separator } from "zudoku/ui/Separator.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
+import { PagefindSearchMeta } from "../../components/PagefindSearchMeta.js";
 import { cn } from "../../util/cn.js";
 import { groupBy } from "../../util/groupBy.js";
 import { renderIf } from "../../util/renderIf.js";
@@ -134,9 +134,9 @@ export const OperationListItem = ({
                     id={`${operation.slug}/request-body`}
                   >
                     {operation.summary && (
-                      <VisuallyHidden>
+                      <PagefindSearchMeta>
                         {operation.summary} &rsaquo;{" "}
-                      </VisuallyHidden>
+                      </PagefindSearchMeta>
                     )}
                     Request Body{" "}
                     {operation.requestBody?.required === false ? (
@@ -154,9 +154,9 @@ export const OperationListItem = ({
               <>
                 <Heading level={3} id={`${operation.slug}/responses`}>
                   {operation.summary && (
-                    <VisuallyHidden>
+                    <PagefindSearchMeta>
                       {operation.summary} &rsaquo;{" "}
-                    </VisuallyHidden>
+                    </PagefindSearchMeta>
                   )}
                   Responses
                 </Heading>

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

@@ -40,6 +40,7 @@ const getSchemaInfos = (schema?: SchemaObject) => {
     schema.enum && "enum",
     schema.const && "const",
     schema.format,
+    schema.type === "array" && schema.items?.contentMediaType,
     schema.minimum !== undefined && `min: ${schema.minimum}`,
     schema.maximum !== undefined && `max: ${schema.maximum}`,
     schema.minLength !== undefined && `minLength: ${schema.minLength}`,

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

@@ -35,14 +35,14 @@ export const ParameterList = ({
       <Frame>
         <FramePanel className="p-0!">
           <ItemGroup className="overflow-clip">
-            {sortedParameters.map((parameter) => (
+            {sortedParameters.map((parameter, index) => (
               <Fragment key={`${parameter.name}-${parameter.in}`}>
+                {index > 0 && <ItemSeparator />}
                 <ParameterListItem
                   parameter={parameter}
                   id={id}
                   group={group}
                 />
-                <ItemSeparator />
               </Fragment>
             ))}
           </ItemGroup>