zudoku 0.37.0 → 0.38.0

package/src/lib/components/Layout.tsx

@@ -1,7 +1,8 @@
 import { Helmet } from "@zudoku/react-helmet-async";
 import { Suspense, useEffect, type ReactNode } from "react";
-import { Outlet, useNavigation } from "react-router";
+import { Outlet, useLocation, useNavigation } from "react-router";
 import { useSpinDelay } from "spin-delay";
+import { joinUrl } from "../util/joinUrl.js";
 import { useScrollToAnchor } from "../util/useScrollToAnchor.js";
 import { useScrollToTop } from "../util/useScrollToTop.js";
 import { useZudoku } from "./context/ZudokuContext.js";
@@ -17,7 +18,8 @@ const LoadingFallback = () => (
 );
 
 export const Layout = ({ children }: { children?: ReactNode }) => {
-  const { meta, authentication } = useZudoku();
+  const { meta, authentication, options } = useZudoku();
+  const location = useLocation();
 
   useScrollToAnchor();
   useScrollToTop();
@@ -40,6 +42,16 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
         <style>{`:root { --top-nav-height: 0px; }`}</style>
       )}
       <Helmet titleTemplate={meta?.title}>
+        {options.canonicalUrlOrigin && (
+          <link
+            rel="canonical"
+            href={joinUrl(
+              options.canonicalUrlOrigin,
+              options.basePath,
+              location.pathname,
+            )}
+          />
+        )}
         {meta?.description && (
           <meta name="description" content={meta.description} />
         )}

package/src/lib/components/Zudoku.tsx

@@ -11,7 +11,7 @@ import {
   useState,
 } from "react";
 import { ErrorBoundary } from "react-error-boundary";
-import { Outlet, useNavigation } from "react-router";
+import { Outlet, useLocation, useNavigation } from "react-router";
 import { hasHead, isMdxProviderPlugin } from "../core/plugins.js";
 import {
   ZudokuContext,
@@ -37,6 +37,7 @@ const ZudokoInner = memo(
       [props.overrides],
     );
 
+    const location = useLocation();
     const mdxComponents = useMemo(() => {
       const componentsFromPlugins = (props.plugins ?? [])
         .filter(isMdxProviderPlugin)
@@ -74,7 +75,9 @@ const ZudokoInner = memo(
     );
 
     const heads = props.plugins
-      ?.flatMap((plugin) => (hasHead(plugin) ? (plugin.getHead?.() ?? []) : []))
+      ?.flatMap((plugin) =>
+        hasHead(plugin) ? (plugin.getHead?.({ location }) ?? []) : [],
+      )
       // eslint-disable-next-line react/no-array-index-key
       .map((entry, i) => <Helmet key={i}>{entry}</Helmet>);
 

package/src/lib/core/ZudokuContext.ts

@@ -5,6 +5,7 @@ import type { Location } from "react-router";
 import type { TopNavigationItem } from "../../config/validators/common.js";
 import type { SidebarConfig } from "../../config/validators/SidebarSchema.js";
 import type { AuthenticationProvider } from "../authentication/authentication.js";
+import { type AuthState, useAuthState } from "../authentication/state.js";
 import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
 import type { Slotlets } from "../components/SlotletProvider.js";
 import { joinPath } from "../util/joinPath.js";
@@ -21,6 +22,7 @@ import {
 
 export interface ZudokuEvents {
   location: (event: { from?: Location; to: Location }) => void;
+  auth: (auth: { prev: AuthState; next: AuthState }) => void;
 }
 
 export interface ApiIdentity {
@@ -67,6 +69,8 @@ type Page = Partial<{
 }>;
 
 export type ZudokuContextOptions = {
+  basePath?: string;
+  canonicalUrlOrigin?: string;
   metadata?: Metadata;
   page?: Page;
   authentication?: AuthenticationProvider;
@@ -106,7 +110,14 @@ export class ZudokuContext {
       if (!isEventConsumerPlugin(plugin)) return;
 
       objectEntries(plugin.events).forEach(([event, handler]) => {
-        this.emitter.on(event, handler);
+        this.emitter.on(event, handler!);
+      });
+    });
+
+    useAuthState.subscribe((state, prevState) => {
+      this.emitEvent("auth", {
+        prev: prevState,
+        next: state,
       });
     });
   }
@@ -158,10 +169,6 @@ export class ZudokuContext {
       throw new Error("No authentication provider configured");
     }
 
-    const accessToken = await this.authentication.getAccessToken();
-
-    request.headers.set("Authorization", `Bearer ${accessToken}`);
-
-    return request;
+    return await this.authentication.signRequest(request);
   };
 }

package/src/lib/core/plugins.ts

@@ -1,12 +1,12 @@
 import type { LucideIcon } from "lucide-react";
-import { type ReactElement } from "react";
-import { type RouteObject } from "react-router";
+import type { ReactElement } from "react";
+import type { Location, RouteObject } from "react-router";
 import type { Sidebar } from "../../config/validators/SidebarSchema.js";
-import { type MdxComponentsType } from "../util/MdxComponents.js";
-import {
-  type ApiIdentity,
-  type ZudokuContext,
-  type ZudokuEvents,
+import type { MdxComponentsType } from "../util/MdxComponents.js";
+import type {
+  ApiIdentity,
+  ZudokuContext,
+  ZudokuEvents,
 } from "./ZudokuContext.js";
 
 export type ZudokuPlugin =
@@ -60,12 +60,12 @@ export interface CommonPlugin {
   initialize?: (
     context: ZudokuContext,
   ) => Promise<void | boolean> | void | boolean;
-  getHead?: () => ReactElement | undefined;
+  getHead?: ({ location }: { location: Location }) => ReactElement | undefined;
   getMdxComponents?: () => MdxComponentsType;
 }
 
 export type EventConsumerPlugin<Event extends ZudokuEvents = ZudokuEvents> = {
-  events: { [K in keyof Event]: Event[K] };
+  events: { [K in keyof Event]?: Event[K] };
 };
 
 export const isEventConsumerPlugin = (

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

@@ -2,7 +2,7 @@ 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 { Link, useHref } from "react-router";
+import { Link } from "react-router";
 import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
 import { ProseClasses } from "../../components/Markdown.js";
@@ -51,12 +51,6 @@ export const MdxPage = ({
   }
 >) => {
   const categoryTitle = useCurrentItem()?.categoryLabel;
-  let canonicalUrl = null;
-  const path = useHref("");
-  if (typeof window !== "undefined") {
-    const domain = window.location.origin;
-    canonicalUrl = `${domain}${path}`;
-  }
 
   const title = frontmatter.title;
   const category = frontmatter.category ?? categoryTitle;
@@ -98,7 +92,6 @@ export const MdxPage = ({
       <Helmet>
         <title>{pageTitle}</title>
         {excerpt && <meta name="description" content={excerpt} />}
-        {canonicalUrl && <link rel="canonical" href={canonicalUrl} />}
       </Helmet>
       <div
         className={cn(

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

@@ -1,13 +1,13 @@
 import { useSuspenseQuery } from "@tanstack/react-query";
 import { CheckIcon, CopyIcon } from "lucide-react";
 import { useState, useTransition } from "react";
-import { useSelectedServer } from "../../authentication/state.js";
 import { InlineCode } from "../../components/InlineCode.js";
 import { Button } from "../../ui/Button.js";
 import { useCreateQuery } from "./client/useCreateQuery.js";
 import { useOasConfig } from "./context.js";
 import { graphql } from "./graphql/index.js";
 import { SimpleSelect } from "./SimpleSelect.js";
+import { useSelectedServer } from "./state.js";
 
 const ServersQuery = graphql(/* GraphQL */ `
   query ServersQuery($input: JSON!, $type: SchemaType!) {

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

@@ -15,7 +15,6 @@ import {
   SelectTrigger,
   SelectValue,
 } from "zudoku/ui/Select.js";
-import { useSelectedServer } from "../../authentication/state.js";
 import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown, ProseClasses } from "../../components/Markdown.js";
@@ -26,6 +25,7 @@ import { OperationListItem } from "./OperationListItem.js";
 import { useCreateQuery } from "./client/useCreateQuery.js";
 import { useOasConfig } from "./context.js";
 import { graphql } from "./graphql/index.js";
+import { useSelectedServer } from "./state.js";
 import { sanitizeMarkdownForMetatag } from "./util/sanitizeMarkdownForMetatag.js";
 
 export const OperationsFragment = graphql(/* GraphQL */ `

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

@@ -2,7 +2,8 @@ import { useSuspenseQuery } from "@tanstack/react-query";
 import { HTTPSnippet } from "@zudoku/httpsnippet";
 import { useMemo, useState, useTransition } from "react";
 import { useSearchParams } from "react-router";
-import { useSelectedServer } from "../../authentication/state.js";
+import { useZudoku } from "zudoku/components";
+import { useAuthState } from "../../authentication/state.js";
 import { PathRenderer } from "../../components/PathRenderer.js";
 import type { SchemaObject } from "../../oas/parser/index.js";
 import { SyntaxHighlight } from "../../ui/SyntaxHighlight.js";
@@ -19,6 +20,7 @@ import { RequestBodySidecarBox } from "./RequestBodySidecarBox.js";
 import { ResponsesSidecarBox } from "./ResponsesSidecarBox.js";
 import * as SidecarBox from "./SidecarBox.js";
 import { SimpleSelect } from "./SimpleSelect.js";
+import { useSelectedServer } from "./state.js";
 import { generateSchemaExample } from "./util/generateSchemaExample.js";
 import { methodForColor } from "./util/methodToColor.js";
 
@@ -101,8 +103,10 @@ export const Sidecar = ({
   onSelectResponse: (response: string) => void;
 }) => {
   const { input, type, options } = useOasConfig();
+  const auth = useAuthState();
   const query = useCreateQuery(GetServerQuery, { input, type });
   const result = useSuspenseQuery(query);
+  const context = useZudoku();
 
   const methodTextColor = methodForColor(operation.method);
 
@@ -115,6 +119,17 @@ export const Sidecar = ({
 
   const requestBodyContent = operation.requestBody?.content;
 
+  const transformedRequestBodyContent =
+    requestBodyContent && options?.transformExamples
+      ? options.transformExamples({
+          auth,
+          type: "request",
+          operation,
+          content: requestBodyContent,
+          context,
+        })
+      : requestBodyContent;
+
   const path = (
     <PathRenderer
       path={operation.path}
@@ -136,8 +151,10 @@ export const Sidecar = ({
   const code = useMemo(() => {
     const example =
       selectedExample ??
-      (requestBodyContent?.[0]?.schema
-        ? generateSchemaExample(requestBodyContent[0].schema as SchemaObject)
+      (transformedRequestBodyContent?.[0]?.schema
+        ? generateSchemaExample(
+            transformedRequestBodyContent[0].schema as SchemaObject,
+          )
         : undefined);
 
     const snippet = new HTTPSnippet({
@@ -162,7 +179,7 @@ export const Sidecar = ({
     return getConverted(snippet, selectedLang);
   }, [
     selectedExample,
-    requestBodyContent,
+    transformedRequestBodyContent,
     operation.method,
     operation.path,
     selectedServer,
@@ -232,9 +249,9 @@ export const Sidecar = ({
           </>
         )}
       </SidecarBox.Root>
-      {isOnScreen && requestBodyContent && (
+      {isOnScreen && transformedRequestBodyContent && (
         <RequestBodySidecarBox
-          content={requestBodyContent}
+          content={transformedRequestBodyContent}
           onExampleChange={setSelectedExample}
         />
       )}
@@ -242,7 +259,19 @@ export const Sidecar = ({
         <ResponsesSidecarBox
           selectedResponse={selectedResponse}
           onSelectResponse={onSelectResponse}
-          responses={operation.responses}
+          responses={operation.responses.map((response) => ({
+            ...response,
+            content:
+              response.content && options?.transformExamples
+                ? options.transformExamples({
+                    auth,
+                    type: "response",
+                    context,
+                    operation,
+                    content: response.content,
+                  })
+                : response.content,
+          }))}
         />
       )}
     </aside>

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

@@ -1,4 +1,7 @@
+import { AuthState } from "../../authentication/state.js";
+import { ZudokuContext } from "../../core/ZudokuContext.js";
 import type { SchemaImports } from "../../oas/graphql/index.js";
+import { OperationListItemResult } from "./OperationList.js";
 
 type DynamicInput = () => Promise<unknown>;
 
@@ -12,6 +15,31 @@ export type ContextOasSource =
   | { type: "file"; input: DynamicInput }
   | { type: "raw"; input: string };
 
+type Example = {
+  name: string;
+  description?: string | null;
+  externalValue?: string | null;
+  value?: any | null;
+  summary?: string | null;
+};
+
+type Content = {
+  mediaType: string;
+  schema?: any | null;
+  encoding?: Array<{
+    name: string;
+  }> | null;
+  examples?: Array<Example> | null;
+};
+
+export type transformExamples = (options: {
+  content: Content[];
+  context: ZudokuContext;
+  auth: AuthState;
+  operation: OperationListItemResult;
+  type: "request" | "response";
+}) => Content[];
+
 type BaseOasConfig = {
   server?: string;
   navigationId?: string;
@@ -23,6 +51,7 @@ type BaseOasConfig = {
     disablePlayground?: boolean;
     showVersionSelect?: "always" | "if-available" | "hide";
     expandAllTags?: boolean;
+    transformExamples?: transformExamples;
   };
 };
 

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

@@ -13,7 +13,6 @@ import {
   SelectValue,
 } from "zudoku/ui/Select.js";
 import { Textarea } from "zudoku/ui/Textarea.js";
-import { useSelectedServer } from "../../../authentication/state.js";
 import { useApiIdentities } from "../../../components/context/ZudokuContext.js";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "../../../ui/Tabs.js";
 import { cn } from "../../../util/cn.js";
@@ -21,6 +20,7 @@ import { objectEntries } from "../../../util/objectEntries.js";
 import { useLatest } from "../../../util/useLatest.js";
 import { ColorizedParam } from "../ColorizedParam.js";
 import { type Content } from "../SidecarExamples.js";
+import { useSelectedServer } from "../state.js";
 import { createUrl } from "./createUrl.js";
 import ExamplesDropdown from "./ExamplesDropdown.js";
 import { Headers } from "./Headers.js";

package/src/lib/plugins/openapi/playground/result-panel/ResultPanel.tsx

@@ -32,7 +32,7 @@ export const ResultPanel = ({
 }) => {
   const status = ((queryMutation.data?.status ?? 0) / 100).toFixed(0);
   return (
-    <div className="min-w-0 p-4 bg-muted/50">
+    <div className="min-w-0 p-4 py-8 bg-muted/50">
       {queryMutation.error ? (
         <div className="flex flex-col gap-2">
           {showPathParamsWarning && (
@@ -99,6 +99,7 @@ export const ResultPanel = ({
               >
                 Looks like the request is taking longer than expected.
                 <Button
+                  type="button"
                   onClick={onCancel}
                   size="sm"
                   className="w-fit"

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

@@ -0,0 +1,36 @@
+import { useMemo } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+
+interface SelectedServerState {
+  selectedServer?: string;
+  setSelectedServer: (newServer: string) => void;
+}
+
+export const useSelectedServerStore = create<SelectedServerState>()(
+  persist(
+    (set) => ({
+      selectedServer: undefined,
+      setSelectedServer: (newServer: string) =>
+        set({ selectedServer: newServer }),
+    }),
+    { name: "zudoku-selected-server" },
+  ),
+);
+
+/**
+ * Simple wrapper for `useSelectedServerStore` to fall back to first of the provided servers
+ */
+export const useSelectedServer = (servers: Array<{ url: string }>) => {
+  const { selectedServer, setSelectedServer } = useSelectedServerStore();
+
+  const finalSelectedServer = useMemo(
+    () =>
+      selectedServer && servers.some((s) => s.url === selectedServer)
+        ? selectedServer
+        : (servers.at(0)?.url ?? ""),
+    [selectedServer, servers],
+  );
+
+  return { selectedServer: finalSelectedServer, setSelectedServer };
+};

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

@@ -1,6 +1,7 @@
 import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
 import { keepPreviousData, useQuery } from "@tanstack/react-query";
-import { useState } from "react";
+import { useRef, useState } from "react";
+import { Button } from "zudoku/ui/Button.js";
 import { Callout } from "zudoku/ui/Callout.js";
 import {
   CommandDialog,
@@ -8,6 +9,8 @@ import {
   CommandInput,
 } from "zudoku/ui/Command.js";
 import { DialogTitle } from "zudoku/ui/Dialog.js";
+import { useAuthState } from "../../authentication/state.js";
+import { useZudoku } from "../../components/context/ZudokuContext.js";
 import { joinUrl } from "../../util/joinUrl.js";
 import { getResults } from "./get-results.js";
 import type { PagefindOptions } from "./index.js";
@@ -55,7 +58,7 @@ const usePagefind = (options: PagefindOptions) => {
     enabled: typeof window !== "undefined",
   });
 
-  if (result.isError) {
+  if (result.isError && result.error.message !== "NOT_BUILT_YET") {
     // eslint-disable-next-line no-console
     console.error(result.error);
   }
@@ -74,13 +77,16 @@ export const PagefindSearch = ({
 }) => {
   const { pagefind, error, isError } = usePagefind(options);
   const [searchTerm, setSearchTerm] = useState("");
+  const auth = useAuthState();
+  const context = useZudoku();
+  const inputRef = useRef<HTMLInputElement>(null);
 
   const { data: searchResults } = useQuery({
     queryKey: ["pagefind-search", searchTerm],
     queryFn: async () => {
       const search = await pagefind?.search(searchTerm);
       if (!search) return [];
-      return getResults(search, options);
+      return getResults({ search, options, auth, context });
     },
     placeholderData: keepPreviousData,
     enabled: !!pagefind && !!searchTerm,
@@ -97,13 +103,29 @@ export const PagefindSearch = ({
         <DialogTitle>Search</DialogTitle>
       </VisuallyHidden>
       <CommandInput
+        ref={inputRef}
         placeholder="Search..."
         value={searchTerm}
         onValueChange={setSearchTerm}
         disabled={isError}
       />
       <CommandEmpty>
-        {searchTerm ? "No results found." : "Start typing to search"}
+        {searchTerm ? (
+          <div className="flex flex-col items-center">
+            No results found.
+            <Button
+              variant="link"
+              onClick={() => {
+                setSearchTerm("");
+                inputRef.current?.focus();
+              }}
+            >
+              Clear search
+            </Button>
+          </div>
+        ) : (
+          "Start typing to search"
+        )}
       </CommandEmpty>
       {isError ? (
         <div className="p-4 text-sm">

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

@@ -1,5 +1,5 @@
-import { FileTextIcon } from "lucide-react";
-import { useCallback } from "react";
+import { BracketsIcon, FileTextIcon } from "lucide-react";
+import { useCallback, useLayoutEffect, useRef } from "react";
 import { Link, useNavigate } from "react-router";
 import { CommandGroup, CommandItem, CommandList } from "zudoku/ui/Command.js";
 import {
@@ -35,6 +35,7 @@ export const ResultList = ({
   maxSubResults?: number;
 }) => {
   const navigate = useNavigate();
+  const commandListRef = useRef<HTMLDivElement | null>(null);
 
   const cleanResultUrl = useCallback(
     (url: string) => {
@@ -46,59 +47,70 @@ export const ResultList = ({
     [basePath],
   );
 
+  useLayoutEffect(() => {
+    requestIdleCallback(() => {
+      commandListRef.current?.scrollTo({ top: 0 });
+    });
+  }, [searchTerm]);
+
   return (
-    <CommandList className="max-h-[450px]">
+    <CommandList className="max-h-[450px]" ref={commandListRef}>
       {searchTerm && searchResults.length > 0 && (
         <CommandGroup
           className="text-sm text-muted-foreground"
           heading={`${searchResults.length} results for "${searchTerm}"`}
         />
       )}
-      {searchResults.map((result) => (
-        <CommandGroup
-          key={[result.meta.title ?? result.excerpt, result.url].join("-")}
-        >
-          <CommandItem
-            asChild
-            value={`${result.meta.title}-${result.url}`}
-            className={hoverClassname}
-            onSelect={() => {
-              void navigate(cleanResultUrl(result.url));
-              onClose();
-            }}
+      {searchTerm &&
+        searchResults.map((result) => (
+          <CommandGroup
+            key={[result.meta.title ?? result.excerpt, result.url].join("-")}
           >
-            <Link to={cleanResultUrl(result.url)}>
-              <FileTextIcon size={20} className="text-muted-foreground" />
-              {result.meta.title}
-            </Link>
-          </CommandItem>
-          {result.sub_results
-            .sort(sortSubResults)
-            .slice(0, maxSubResults)
-            .map((subResult) => (
-              <CommandItem
-                asChild
-                key={`${result.meta.title}-${subResult.url}`}
-                value={`${result.meta.title}-${subResult.url}`}
-                className={hoverClassname}
-                onSelect={() => {
-                  void navigate(cleanResultUrl(subResult.url));
-                  onClose();
-                }}
-              >
-                <Link to={cleanResultUrl(subResult.url)} onClick={onClose}>
-                  <div className="flex flex-col items-start gap-2 ms-2.5 ps-5 border-l border-muted-foreground/50">
-                    <span className="font-bold">{subResult.title}</span>
-                    <span
-                      className="text-[13px] [&_mark]:bg-primary [&_mark]:text-primary-foreground"
-                      dangerouslySetInnerHTML={{ __html: subResult.excerpt }}
-                    />
-                  </div>
-                </Link>
-              </CommandItem>
-            ))}
-        </CommandGroup>
-      ))}
+            <CommandItem
+              asChild
+              value={`${result.meta.title}-${result.url}`}
+              className={hoverClassname}
+              onSelect={() => {
+                void navigate(cleanResultUrl(result.url));
+                onClose();
+              }}
+            >
+              <Link to={cleanResultUrl(result.url)}>
+                {result.meta.section === "openapi" ? (
+                  <BracketsIcon />
+                ) : (
+                  <FileTextIcon />
+                )}
+                {result.meta.title}
+              </Link>
+            </CommandItem>
+            {result.sub_results
+              .sort(sortSubResults)
+              .slice(0, maxSubResults)
+              .map((subResult) => (
+                <CommandItem
+                  asChild
+                  key={`sub-${result.meta.title}-${subResult.url}`}
+                  value={`sub-${result.meta.title}-${subResult.url}`}
+                  className={hoverClassname}
+                  onSelect={() => {
+                    void navigate(cleanResultUrl(subResult.url));
+                    onClose();
+                  }}
+                >
+                  <Link to={cleanResultUrl(subResult.url)} onClick={onClose}>
+                    <div className="flex flex-col items-start gap-2 ms-2.5 ps-5 border-l border-muted-foreground/50">
+                      <span className="font-bold">{subResult.title}</span>
+                      <span
+                        className="text-[13px] [&_mark]:bg-primary [&_mark]:text-primary-foreground"
+                        dangerouslySetInnerHTML={{ __html: subResult.excerpt }}
+                      />
+                    </div>
+                  </Link>
+                </CommandItem>
+              ))}
+          </CommandGroup>
+        ))}
     </CommandList>
   );
 };