zudoku 0.65.3 → 0.66.0

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 { PagefindSearchMeta } from "../../components/PagefindSearchMeta.js";
 import { Pagination } from "../../components/Pagination.js";
+import { joinUrl } from "../../util/joinUrl.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";
@@ -155,7 +158,7 @@ export const OperationList = ({
   tag?: string;
   untagged?: boolean;
 }) => {
-  const { input, type, versions, version, options } = useOasConfig();
+  const { path, input, type, versions, version, options } = useOasConfig();
   const { tag: tagFromParams } = useParams<"tag">();
   const query = useCreateQuery(OperationsForTagQuery, {
     input,
@@ -244,12 +247,20 @@ export const OperationList = ({
   const tagTitle = schema.tag.extensions?.["x-displayName"] ?? schema.tag.name;
   const helmetTitle = [tagTitle, title].filter(Boolean).join(" - ");
 
+  const downloadUrl =
+    typeof input === "string"
+      ? type === "url"
+        ? input
+        : joinUrl(path, version, input.split("/").pop())
+      : 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 +273,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
@@ -282,25 +293,32 @@ export const OperationList = ({
               <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/SchemaList.tsx

@@ -16,6 +16,7 @@ import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
 import { Toc } from "../../components/navigation/Toc.js";
+import { PagefindSearchMeta } from "../../components/PagefindSearchMeta.js";
 import { useCreateQuery } from "./client/useCreateQuery.js";
 import { useOasConfig } from "./context.js";
 import { graphql } from "./graphql/gql.js";
@@ -70,6 +71,9 @@ export function SchemaList() {
       data-pagefind-filter="section:openapi"
       data-pagefind-meta="section:openapi"
     >
+      <PagefindSearchMeta name="category">
+        {data.schema.title}
+      </PagefindSearchMeta>
       <Helmet>
         <title>Schemas {showVersions ? version : ""}</title>
         <meta name="description" content="List of schemas used by the API." />

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

@@ -13,7 +13,7 @@ import type { OasPluginConfig } from "./interfaces.js";
 import type { PlaygroundContentProps } from "./playground/Playground.js";
 import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
 import { createNavigationCategory } from "./util/createNavigationCategory.js";
-import { getRoutes, getVersions } from "./util/getRoutes.js";
+import { getRoutes, getVersionMetadata } from "./util/getRoutes.js";
 
 export const GetNavigationOperationsQuery = graphql(`
   query GetNavigationOperations($input: JSON!, $type: SchemaType!) {
@@ -54,14 +54,19 @@ export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
   return {
     getHead: () => {
       if (config.type === "url" && !config.skipPreload) {
-        return (
+        const urls = Array.isArray(config.input)
+          ? config.input.map((v) => v.input)
+          : [config.input];
+
+        return urls.map((url) => (
           <link
+            key={url}
+            href={url}
             rel="preload"
-            href={config.input}
             as="fetch"
             crossOrigin="anonymous"
           />
-        );
+        ));
       }
 
       if (config.server) {
@@ -111,10 +116,14 @@ export const openApiPlugin = (config: OasPluginConfig): ZudokuPlugin => {
 
       try {
         const versionParam = match?.params.version;
-        const version = versionParam ?? getVersions(config).at(0);
+        const { versions } = getVersionMetadata(config);
+        const version = versionParam ?? versions.at(0);
         const { type } = config;
-        // biome-ignore lint/style/noNonNullAssertion: version is guaranteed to be defined
-        const input = type === "file" ? config.input[version!] : config.input;
+
+        const input = Array.isArray(config.input)
+          ? (config.input.find((v) => v.path === version)?.input ??
+            config.input[0]?.input)
+          : config.input;
 
         const query = createQuery(client, GetNavigationOperationsQuery, {
           type,

package/src/lib/plugins/openapi/interfaces.ts

@@ -5,15 +5,21 @@ import type { OperationsFragmentFragment } from "./graphql/graphql.js";
 
 type DynamicInput = () => Promise<unknown>;
 
+export type VersionedInput<T> = Array<{
+  path: string;
+  label?: string;
+  input: T;
+}>;
+
 type OasSource =
-  | { type: "url"; input: string }
-  | { type: "file"; input: { [version: string]: DynamicInput } }
+  | { type: "url"; input: string | VersionedInput<string> }
+  | { type: "file"; input: VersionedInput<DynamicInput> }
   | { type: "raw"; input: string };
 
-export type ContextOasSource =
-  | { type: "url"; input: string }
-  | { type: "file"; input: DynamicInput }
-  | { type: "raw"; input: string };
+export type ContextOasSource = {
+  type: "url" | "file" | "raw";
+  input: string | DynamicInput;
+};
 
 type Example = {
   name: string;
@@ -66,6 +72,9 @@ type BaseOasConfig = {
     showVersionSelect?: "always" | "if-available" | "hide";
     expandAllTags?: boolean;
     expandApiInformation?: boolean;
+    schemaDownload?: {
+      enabled: boolean;
+    };
     transformExamples?: TransformExamplesFn;
     generateCodeSnippet?: GenerateCodeSnippetFn;
   };
@@ -76,5 +85,5 @@ export type OasPluginConfig = BaseOasConfig & OasSource;
 export type OasPluginContext = BaseOasConfig &
   ContextOasSource & {
     version?: string;
-    versions: Record<string, string>;
+    versions: Record<string, { path: string; label: string }>;
   };

package/src/lib/plugins/openapi/playground/Playground.tsx

@@ -387,7 +387,7 @@ export const Playground = ({
             value={selectedServer}
             defaultValue={selectedServer}
           >
-            <SelectTrigger className="p-0 border-none flex-row-reverse bg-transparent text-xs gap-0.5 h-auto translate-y-[4px]">
+            <SelectTrigger className="p-0 h-fit shadow-none border-none flex-row-reverse bg-transparent text-xs gap-0.5 translate-y-[4px]">
               <SelectValue />
             </SelectTrigger>
             <SelectContent>

package/src/lib/plugins/openapi/schema/SchemaView.tsx

@@ -17,7 +17,7 @@ import { ParamInfos } from "../ParamInfos.js";
 import { SchemaExampleAndDefault } from "./SchemaExampleAndDefault.js";
 import { SchemaPropertyItem } from "./SchemaPropertyItem.js";
 import { UnionView } from "./UnionView.js";
-import { isBasicType } from "./utils.js";
+import { isArrayType, isBasicType } from "./utils.js";
 
 const renderMarkdown = (content?: string) =>
   content && (
@@ -91,10 +91,20 @@ export const SchemaView = ({
     return renderBasicSchema(schema, cardHeader, embedded);
   }
 
-  if (schema.type === "array" && typeof schema.items === "object") {
-    return <SchemaView schema={schema.items} cardHeader={cardHeader} />;
+  if (isArrayType(schema) && typeof schema.items === "object") {
+    const wrappedSchema: SchemaObject = {
+      type: "object",
+      properties: { "": schema },
+    };
+
+    return (
+      <SchemaView schema={wrappedSchema} cardHeader={cardHeader} defaultOpen />
+    );
   }
 
+  const additionalObjectProperties = typeof schema.additionalProperties ===
+    "object" && <SchemaView schema={schema.additionalProperties} embedded />;
+
   if (schema.type === "object") {
     const groupedProperties = groupBy(
       Object.entries(schema.properties ?? {}),
@@ -106,32 +116,31 @@ export const SchemaView = ({
             : "optional";
       },
     );
+
     const groupNames = ["required", "optional", "deprecated"] as const;
+    const groups = groupNames.flatMap((group) => {
+      const properties = groupedProperties[group];
+      return properties ? { group, properties } : [];
+    });
 
-    const additionalObjectProperties = typeof schema.additionalProperties ===
-      "object" && <SchemaView schema={schema.additionalProperties} embedded />;
-
-    const itemsList = groupNames.map(
-      (group, index) =>
-        groupedProperties[group] && (
-          <Fragment key={group}>
-            {index > 0 && <ItemSeparator />}
-            <ItemGroup className="overflow-clip">
-              {groupedProperties[group].map(([name, schema], index) => (
-                <Fragment key={name}>
-                  {index > 0 && <ItemSeparator />}
-                  <SchemaPropertyItem
-                    name={name}
-                    schema={schema}
-                    group={group}
-                    defaultOpen={defaultOpen}
-                  />
-                </Fragment>
-              ))}
-            </ItemGroup>
-          </Fragment>
-        ),
-    );
+    const itemsList = groups.map(({ group, properties }, index) => (
+      <Fragment key={group}>
+        {index > 0 && <ItemSeparator />}
+        <ItemGroup className="overflow-clip">
+          {properties.map(([name, schema], index) => (
+            <Fragment key={name}>
+              {index > 0 && <ItemSeparator />}
+              <SchemaPropertyItem
+                name={name}
+                schema={schema}
+                group={group}
+                defaultOpen={defaultOpen}
+              />
+            </Fragment>
+          ))}
+        </ItemGroup>
+      </Fragment>
+    ));
 
     if (embedded) {
       return itemsList;

package/src/lib/plugins/openapi/schema/utils.ts

@@ -1,5 +1,8 @@
 import { CIRCULAR_REF } from "../../../oas/graphql/circular.js";
-import type { SchemaObject } from "../../../oas/parser/index.js";
+import type {
+  ArraySchemaObject,
+  SchemaObject,
+} from "../../../oas/parser/index.js";
 
 export const isBasicType = (
   type: unknown,
@@ -8,7 +11,7 @@ export const isBasicType = (
     ["string", "number", "boolean", "integer", "null"].includes(type)) ||
   (Array.isArray(type) && type.every(isBasicType));
 
-export const isArrayType = (value: SchemaObject) =>
+export const isArrayType = (value: SchemaObject): value is ArraySchemaObject =>
   value.type === "array" ||
   // schema.type might be an array of types, so we need to check if "array" is one of them
   (Array.isArray(value.type) && value.type.includes("array"));

package/src/lib/plugins/openapi/util/getRoutes.tsx

@@ -148,8 +148,18 @@ const createVersionRoutes = (
   ];
 };
 
-export const getVersions = (config: OasPluginConfig) =>
-  config.type === "file" ? Object.keys(config.input) : [];
+export const getVersionMetadata = (config: OasPluginConfig) => {
+  if (config.type === "raw" || !Array.isArray(config.input)) {
+    return { versions: [], labels: {} };
+  }
+
+  return {
+    versions: config.input.map((v) => v.path),
+    labels: Object.fromEntries(
+      config.input.map((v) => [v.path, v.label ?? v.path]),
+    ),
+  };
+};
 
 export const getRoutes = ({
   basePath,
@@ -161,10 +171,33 @@ export const getRoutes = ({
   basePath: string;
 }): RouteObject[] => {
   const tagPages = config.tagPages;
+  const { versions } = getVersionMetadata(config);
 
   // If the config does not provide tag pages the catch-all
   // route handles all operations on a single page
   if (!tagPages) {
+    // If there are versions, create versioned routes even without tag pages
+    if (versions.length > 0) {
+      const versionsInPath =
+        versions.length > 1 ? [undefined, ...versions] : [undefined];
+
+      return versionsInPath.map((version) => {
+        const versionPath = joinUrl(basePath, version);
+        return createOasProvider({
+          basePath,
+          version,
+          routePath: versionPath,
+          routes: [
+            createNonTagPagesRoute({ path: `${versionPath}/:tag?` }),
+            ...createAdditionalRoutes(versionPath),
+          ],
+          client,
+          config,
+        });
+      });
+    }
+
+    // No versions, single route
     return [
       createOasProvider({
         basePath,
@@ -179,7 +212,6 @@ export const getRoutes = ({
     ];
   }
 
-  const versions = getVersions(config);
   // The latest version always is added as index path
   const versionsInPath =
     versions.length > 1 ? [undefined, ...versions] : [undefined];

package/src/lib/plugins/search-pagefind/IndexingDialog.tsx

@@ -0,0 +1,163 @@
+import { DialogTrigger } from "@radix-ui/react-dialog";
+import {
+  type PropsWithChildren,
+  useCallback,
+  useEffect,
+  useState,
+} from "react";
+import { Button } from "zudoku/ui/Button.js";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "zudoku/ui/Dialog.js";
+
+type IndexingState =
+  | { status: "idle" }
+  | { status: "indexing"; total: number; current: number; path: string }
+  | { status: "complete"; indexed: number }
+  | { status: "error"; message: string };
+
+const ProgressBar = ({
+  total,
+  current,
+  barLength = 25,
+  emptyChar = "░",
+  filledChar = "█",
+}: {
+  total: number;
+  current: number;
+  barLength?: number;
+  emptyChar?: string;
+  filledChar?: string;
+}) => {
+  const percent = Math.round((current / total) * 100);
+  const filled = Math.round((percent / 100) * barLength);
+  const empty = barLength - filled;
+
+  return (
+    <>
+      {filledChar.repeat(filled)}
+      {emptyChar.repeat(empty)} {percent}% ({current}/{total})
+    </>
+  );
+};
+
+const IndexingDialog = ({ children }: PropsWithChildren) => {
+  const [indexingState, setIndexingState] = useState<IndexingState>({
+    status: "idle",
+  });
+
+  const startIndexing = useCallback(() => {
+    setIndexingState({ status: "indexing", total: 0, current: 0, path: "" });
+
+    const eventSource = new EventSource("/__z/pagefind-reindex");
+
+    eventSource.onmessage = (event) => {
+      const data = JSON.parse(event.data);
+
+      if (data.type === "progress") {
+        setIndexingState({
+          status: "indexing",
+          total: data.total,
+          current: data.current,
+          path: data.path,
+        });
+      } else if (data.type === "complete") {
+        eventSource.close();
+        if (data.success) {
+          setIndexingState({ status: "complete", indexed: data.indexed });
+        } else {
+          setIndexingState({
+            status: "error",
+            message: data.error ?? "Indexing failed",
+          });
+        }
+      }
+    };
+
+    eventSource.onerror = () => {
+      eventSource.close();
+      setIndexingState({
+        status: "error",
+        message: "Connection lost during indexing",
+      });
+    };
+
+    return () => eventSource.close();
+  }, []);
+
+  useEffect(() => {
+    if (indexingState.status !== "idle") return;
+    return startIndexing();
+  }, [indexingState.status, startIndexing]);
+
+  const handleDone = () => {
+    if (indexingState.status !== "complete") return;
+    window.location.reload();
+  };
+
+  return (
+    <Dialog>
+      <DialogTrigger asChild>{children}</DialogTrigger>
+      <DialogContent
+        className="max-w-sm! top-1/3"
+        showCloseButton={false}
+        onInteractOutside={(e) => e.preventDefault()}
+      >
+        <DialogHeader>
+          <DialogTitle>
+            {indexingState.status === "indexing" && "Building Search Index"}
+            {indexingState.status === "complete" && "Indexing Complete"}
+            {indexingState.status === "error" && "Indexing Failed"}
+            {indexingState.status === "idle" && "Build Search Index"}
+          </DialogTitle>
+          <DialogDescription>
+            {indexingState.status === "indexing" && (
+              <>
+                {indexingState.total > 0 && (
+                  <div className="font-mono text-sm mb-2">
+                    <ProgressBar {...indexingState} />
+                  </div>
+                )}
+                {indexingState.path && (
+                  <span className="block text-xs truncate">
+                    {indexingState.path}
+                  </span>
+                )}
+              </>
+            )}
+            {indexingState.status === "complete" && (
+              <>Successfully indexed {indexingState.indexed} pages.</>
+            )}
+            {indexingState.status === "error" && (
+              <span className="text-destructive">{indexingState.message}</span>
+            )}
+          </DialogDescription>
+        </DialogHeader>
+        <DialogFooter>
+          <div className="flex justify-end gap-2">
+            {indexingState.status === "complete" && (
+              <Button size="sm" onClick={handleDone}>
+                Close and reload
+              </Button>
+            )}
+            {indexingState.status === "error" && (
+              <>
+                <Button variant="outline" onClick={handleDone}>
+                  Cancel
+                </Button>
+                <Button onClick={startIndexing}>Retry</Button>
+              </>
+            )}
+          </div>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+};
+
+export default IndexingDialog;