@lukoweb/apitogo 0.1.0

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

@@ -0,0 +1,309 @@
+import { useMemo, useState, useTransition } from "react";
+import { useSearchParams } from "react-router";
+import { useZudoku } from "@lukoweb/apitogo/hooks";
+import { Badge } from "@lukoweb/apitogo/ui/Badge.js";
+import { NativeSelect, NativeSelectOption } from "@lukoweb/apitogo/ui/NativeSelect.js";
+import { SyntaxHighlight } from "@lukoweb/apitogo/ui/SyntaxHighlight.js";
+import { useAuthState } from "../../authentication/state.js";
+import { PathRenderer } from "../../components/PathRenderer.js";
+import { cn } from "../../util/cn.js";
+import { useOnScreen } from "../../util/useOnScreen.js";
+import { ColorizedParam } from "./ColorizedParam.js";
+import { NonHighlightedCode } from "./components/NonHighlightedCode.js";
+import { useOasConfig } from "./context.js";
+import { GeneratedExampleSidecarBox } from "./GeneratedExampleSidecarBox.js";
+import type { OperationsFragmentFragment } from "./graphql/graphql.js";
+import { graphql } from "./graphql/index.js";
+import { PlaygroundDialogWrapper } from "./PlaygroundDialogWrapper.js";
+import { RequestBodySidecarBox } from "./RequestBodySidecarBox.js";
+import { ResponsesSidecarBox } from "./ResponsesSidecarBox.js";
+import * as SidecarBox from "./SidecarBox.js";
+import { createHttpSnippet, getConverted } from "./util/createHttpSnippet.js";
+import { generateSchemaExample } from "./util/generateSchemaExample.js";
+import { methodForColor } from "./util/methodToColor.js";
+
+export const GetServerQuery = graphql(/* GraphQL */ `
+  query getServerQuery($input: JSON!, $type: SchemaType!) {
+    schema(input: $input, type: $type) {
+      url
+      servers {
+        url
+      }
+    }
+  }
+`);
+
+const EXAMPLE_LANGUAGES = [
+  { value: "shell", label: "cURL" },
+  { value: "js", label: "JavaScript" },
+  { value: "python", label: "Python" },
+  { value: "java", label: "Java" },
+  { value: "go", label: "Go" },
+  { value: "csharp", label: "C#" },
+  { value: "kotlin", label: "Kotlin" },
+  { value: "objc", label: "Objective-C" },
+  { value: "php", label: "PHP" },
+  { value: "ruby", label: "Ruby" },
+  { value: "swift", label: "Swift" },
+];
+
+export const Sidecar = ({
+  operation,
+  selectedResponse,
+  globalSelectedServer,
+  shouldLazyHighlight,
+}: {
+  operation: OperationsFragmentFragment;
+  selectedResponse?: string;
+  globalSelectedServer?: string;
+  shouldLazyHighlight?: boolean;
+}) => {
+  const { options } = useOasConfig();
+  const auth = useAuthState();
+  const context = useZudoku();
+
+  const methodTextColor = methodForColor(operation.method);
+
+  const [searchParams, setSearchParams] = useSearchParams();
+  const [, startTransition] = useTransition();
+
+  const supportedLanguages = options?.supportedLanguages ?? EXAMPLE_LANGUAGES;
+
+  const preferredLang =
+    searchParams.get("lang") ?? options?.examplesLanguage ?? "shell";
+
+  const selectedLang =
+    supportedLanguages.find((lang) => lang.value === preferredLang)?.value ??
+    supportedLanguages.at(0)?.value ??
+    "shell";
+
+  const requestBodyContent = operation.requestBody?.content;
+  const transformedRequestBodyContent =
+    requestBodyContent && options?.transformExamples
+      ? options.transformExamples({
+          auth,
+          type: "request",
+          operation,
+          content: requestBodyContent,
+          context,
+        })
+      : requestBodyContent;
+
+  const [selectedRequestExample, setSelectedRequestExample] = useState<{
+    contentTypeIndex: number;
+    exampleIndex: number;
+  }>({
+    contentTypeIndex: 0,
+    exampleIndex: 0,
+  });
+
+  const selectedContent = transformedRequestBodyContent?.at(
+    selectedRequestExample.contentTypeIndex,
+  );
+  const currentExample = selectedContent?.examples?.at(
+    selectedRequestExample.exampleIndex,
+  );
+
+  const currentExampleCode = currentExample
+    ? (currentExample?.value ?? currentExample)
+    : selectedContent?.schema
+      ? generateSchemaExample(selectedContent?.schema)
+      : undefined;
+
+  const path = (
+    <PathRenderer
+      path={operation.path}
+      renderParam={({ name }) => (
+        <ColorizedParam
+          name={name}
+          backgroundOpacity="0"
+          className="py-px px-0.5"
+          // same as in `ParameterListItem`
+          slug={`${operation.slug}-${name}`}
+        >
+          {`{${name}}`}
+        </ColorizedParam>
+      )}
+    />
+  );
+
+  // Manual server selection takes precedence over the server hierarchy.
+  // If no manual selection, fall back to operation's first server (already respects operation > path > global hierarchy)
+  const selectedServer =
+    globalSelectedServer || operation.servers.at(0)?.url || "";
+
+  const httpSnippetCode = useMemo<string | undefined>(() => {
+    const converted = options?.generateCodeSnippet?.({
+      selectedLang,
+      selectedServer,
+      context,
+      operation,
+      example: currentExampleCode,
+      auth,
+    });
+
+    if (converted) return converted;
+
+    const snippet = createHttpSnippet({
+      operation,
+      selectedServer,
+      exampleBody: currentExampleCode
+        ? {
+            mimeType: selectedContent?.mediaType ?? "application/json",
+            text: JSON.stringify(currentExampleCode, null, 2),
+          }
+        : { mimeType: selectedContent?.mediaType ?? "application/json" },
+    });
+
+    return getConverted(snippet, selectedLang);
+  }, [
+    currentExampleCode,
+    operation,
+    selectedServer,
+    selectedLang,
+    selectedContent,
+    options,
+    auth,
+    context,
+  ]);
+
+  const [ref, isOnScreen] = useOnScreen({ rootMargin: "200px 0px 200px 0px" });
+
+  const showPlayground =
+    isOnScreen &&
+    (operation.extensions["x-explorer-enabled"] === true ||
+      operation.extensions["x-zudoku-playground-enabled"] === true ||
+      (operation.extensions["x-explorer-enabled"] === undefined &&
+        operation.extensions["x-zudoku-playground-enabled"] === undefined &&
+        !options?.disablePlayground));
+
+  const hasResponseExamples = operation.responses.some((response) =>
+    response.content?.some((content) => (content.examples?.length ?? 0) > 0),
+  );
+
+  return (
+    <aside
+      ref={ref}
+      className="flex flex-col sticky top-(--scroll-padding) gap-4"
+      data-pagefind-ignore="all"
+    >
+      <SidecarBox.Root>
+        <SidecarBox.Head className="py-1.5">
+          <div className="flex items-center flex-wrap gap-2 justify-between w-full">
+            <span className="font-mono wrap-break-word leading-6 space-x-1">
+              <Badge
+                variant="outline"
+                className={cn(
+                  methodTextColor,
+                  "px-1.5 rounded-md border-none bg-current/7 dark:bg-current/15",
+                )}
+              >
+                {operation.method.toUpperCase()}
+              </Badge>
+              {path}
+            </span>
+            <div className="flex items-center gap-1">
+              <NativeSelect
+                className="py-0.5 h-fit max-w-32 truncate bg-background"
+                value={selectedLang}
+                onChange={(e) => {
+                  startTransition(() => {
+                    setSearchParams((prev) => {
+                      prev.set("lang", e.target.value);
+                      return prev;
+                    });
+                  });
+                }}
+              >
+                {supportedLanguages.map((language) => (
+                  <NativeSelectOption
+                    key={language.value}
+                    value={language.value}
+                  >
+                    {language.label}
+                  </NativeSelectOption>
+                ))}
+              </NativeSelect>
+              {showPlayground && (
+                <PlaygroundDialogWrapper
+                  servers={operation.servers.map((server) => server.url)}
+                  operation={operation}
+                  examples={requestBodyContent ?? undefined}
+                />
+              )}
+            </div>
+          </div>
+        </SidecarBox.Head>
+        <SidecarBox.Body>
+          {shouldLazyHighlight && !isOnScreen ? (
+            <NonHighlightedCode code={httpSnippetCode ?? ""} />
+          ) : (
+            <SyntaxHighlight
+              embedded
+              language={selectedLang}
+              className="[--scrollbar-color:gray] rounded-none text-xs max-h-[200px]"
+              // biome-ignore lint/style/noNonNullAssertion: code is guaranteed to be defined
+              code={httpSnippetCode!}
+            />
+          )}
+        </SidecarBox.Body>
+      </SidecarBox.Root>
+
+      {transformedRequestBodyContent && currentExample ? (
+        <RequestBodySidecarBox
+          content={transformedRequestBodyContent}
+          onExampleChange={(selected) => {
+            setSelectedRequestExample(selected);
+          }}
+          selectedContentIndex={selectedRequestExample.contentTypeIndex}
+          selectedExampleIndex={selectedRequestExample.exampleIndex}
+          isOnScreen={isOnScreen}
+          shouldLazyHighlight={shouldLazyHighlight}
+        />
+      ) : transformedRequestBodyContent && currentExampleCode ? (
+        <GeneratedExampleSidecarBox
+          isOnScreen={isOnScreen}
+          shouldLazyHighlight={shouldLazyHighlight}
+          code={JSON.stringify(currentExampleCode, null, 2)}
+        />
+      ) : null}
+
+      {hasResponseExamples ? (
+        <ResponsesSidecarBox
+          isOnScreen={isOnScreen}
+          shouldLazyHighlight={shouldLazyHighlight}
+          selectedResponse={selectedResponse}
+          responses={operation.responses.map((response) => ({
+            ...response,
+            content:
+              response.content && options?.transformExamples
+                ? options.transformExamples({
+                    auth,
+                    type: "response",
+                    context,
+                    operation,
+                    content: response.content,
+                  })
+                : response.content,
+          }))}
+        />
+      ) : (
+        <ResponsesSidecarBox
+          isGenerated
+          isOnScreen={isOnScreen}
+          shouldLazyHighlight={shouldLazyHighlight}
+          selectedResponse={selectedResponse}
+          responses={operation.responses.map((response) => ({
+            ...response,
+            content: response.content?.map((content) => ({
+              ...content,
+              examples: content.schema
+                ? [{ name: "", value: generateSchemaExample(content.schema) }]
+                : content.examples,
+            })),
+          }))}
+        />
+      )}
+    </aside>
+  );
+};

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

@@ -0,0 +1,57 @@
+import type { PropsWithChildren } from "react";
+import { cn } from "../../util/cn.js";
+
+type BaseComponentProps<T = unknown> = PropsWithChildren<
+  T & { className?: string }
+>;
+
+export const Root = ({ children, className }: BaseComponentProps) => (
+  <div
+    data-slot="sidecar-box-root"
+    className={cn(
+      "relative text-xs flex min-w-0 flex-col rounded-xl border bg-muted/50 bg-clip-padding",
+      "before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-xl)-1px)] before:shadow-[0_1px_2px_1px_--theme(--color-black/4%)] after:pointer-events-none after:absolute after:-inset-[5px] after:-z-1 after:rounded-[calc(var(--radius-xl)+4px)] after:border after:border-border/50 after:bg-clip-padding **:data-[slot=particle-wrapper]:w-full **:data-[slot=particle-wrapper]:max-w-64 lg:col-span-1 dark:after:bg-background/72",
+      className,
+    )}
+  >
+    {children}
+  </div>
+);
+
+export const Head = ({ children, className }: BaseComponentProps) => (
+  <div
+    data-slot="sidecar-box-head"
+    className={cn(
+      "flex items-center gap-3 rounded-b-xl p-2.5 data-[slot=head]:rounded-b-none",
+      className,
+    )}
+  >
+    {children}
+  </div>
+);
+
+export const Body = ({ children, className }: BaseComponentProps) => (
+  <div
+    data-slot="sidecar-box-body"
+    className={cn(
+      "overflow-auto -m-px flex min-w-0 flex-1 flex-col overflow-x-auto rounded-t-xl border bg-background",
+      "rounded-b last:rounded-b-xl",
+      "before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-xl)-1px)] dark:before:shadow-[0_-1px_--theme(--color-white/8%)]",
+      className,
+    )}
+  >
+    {children}
+  </div>
+);
+
+export const Footer = ({ children, className }: BaseComponentProps) => (
+  <div
+    data-slot="sidecar-box-footer"
+    className={cn(
+      "p-2 rounded-b-xl data-[slot=sidecar-box-footer]:rounded-b-none",
+      className,
+    )}
+  >
+    {children}
+  </div>
+);

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

@@ -0,0 +1,174 @@
+import { ExternalLinkIcon } from "lucide-react";
+import { Badge } from "@lukoweb/apitogo/ui/Badge.js";
+import { NativeSelect, NativeSelectOption } from "@lukoweb/apitogo/ui/NativeSelect.js";
+import { SyntaxHighlight } from "../../ui/SyntaxHighlight.js";
+import { NonHighlightedCode } from "./components/NonHighlightedCode.js";
+import type { MediaTypeObject } from "./graphql/graphql.js";
+import * as SidecarBox from "./SidecarBox.js";
+
+const formatForDisplay = (value: unknown): string | undefined => {
+  if (value == null) return;
+  if (typeof value === "string") return value.trim();
+  return JSON.stringify(value, null, 2);
+};
+
+const getLanguage = (mediaType?: string): string => {
+  if (!mediaType) return "text";
+  if (mediaType.endsWith("+json")) return "json";
+  if (mediaType.endsWith("+xml")) return "xml";
+  if (mediaType.endsWith("+yaml")) return "yaml";
+
+  const languages: Record<string, string> = {
+    "text/html": "html",
+    "application/x-ndjson": "json",
+    "application/json": "json",
+    "application/xml": "xml",
+    "application/x-yaml": "yaml",
+    "text/csv": "csv",
+    "application/javascript": "javascript",
+    "application/graphql": "graphql",
+  };
+  return languages[mediaType] ?? "text";
+};
+
+export type SidecarExamplesProps = {
+  content: MediaTypeObject[];
+  description?: string;
+  selectedContentIndex: number;
+  selectedExampleIndex: number;
+  onExampleChange?: ({
+    contentTypeIndex,
+    exampleIndex,
+  }: {
+    contentTypeIndex: number;
+    exampleIndex: number;
+  }) => void;
+  isOnScreen: boolean;
+  shouldLazyHighlight?: boolean;
+};
+
+export const SidecarExamples = ({
+  content,
+  description,
+  onExampleChange,
+  selectedContentIndex,
+  selectedExampleIndex,
+  isOnScreen,
+  shouldLazyHighlight,
+}: SidecarExamplesProps) => {
+  // Get example value, with fallback to schema-generated example
+  const selectedContent = content[selectedContentIndex];
+  const examples = selectedContent?.examples ?? [];
+  const selectedExample = examples?.[selectedExampleIndex];
+
+  const formattedExample = formatForDisplay(selectedExample?.value);
+  const language = getLanguage(selectedContent?.mediaType);
+
+  return (
+    <>
+      <SidecarBox.Body className="p-0">
+        {selectedExample?.externalValue ? (
+          <div className="p-4">
+            <a
+              href={selectedExample.externalValue}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="text-xs text-primary hover:underline"
+            >
+              View External Example
+              <ExternalLinkIcon className="size-3 inline-block ms-1 align-[-0.125em]" />
+            </a>
+          </div>
+        ) : shouldLazyHighlight && !isOnScreen && formattedExample ? (
+          <NonHighlightedCode code={formattedExample} />
+        ) : formattedExample ? (
+          <SyntaxHighlight
+            embedded
+            language={language}
+            className="[--scrollbar-color:gray] rounded-none max-h-[200px] text-xs overflow-auto"
+            code={formattedExample}
+          />
+        ) : (
+          <div className="grid place-items-center text-xs text-muted-foreground min-h-18">
+            No example specified for this content type
+          </div>
+        )}
+        {selectedExample?.description && (
+          <div className="border-t text-xs px-3 py-1.5 text-muted-foreground">
+            {selectedExample.description}
+          </div>
+        )}
+      </SidecarBox.Body>
+      <SidecarBox.Footer className="text-xs">
+        {description && (
+          <div className="text-muted-foreground text-xs px-1 py-2">
+            {description}
+          </div>
+        )}
+        {(examples.length !== 0 || content.length !== 0) && (
+          <div className="flex items-center gap-2 justify-between min-w-0">
+            <div className="flex items-center gap-2 flex-wrap">
+              {content.length > 1 ? (
+                <NativeSelect
+                  className="text-xs h-fit py-1 truncate bg-background"
+                  value={selectedContentIndex.toString()}
+                  onChange={(e) =>
+                    onExampleChange?.({
+                      contentTypeIndex: Number(e.target.value),
+                      exampleIndex: 0,
+                    })
+                  }
+                >
+                  {content.map((c, index) => (
+                    <NativeSelectOption
+                      key={c.mediaType}
+                      value={index.toString()}
+                    >
+                      {c.mediaType}
+                    </NativeSelectOption>
+                  ))}
+                </NativeSelect>
+              ) : (
+                <Badge
+                  className="text-[11px] font-mono font-normal"
+                  variant="outline"
+                >
+                  {content[0]?.mediaType}
+                </Badge>
+              )}
+            </div>
+            {examples.length > 1 && (
+              <NativeSelect
+                className="text-xs h-fit py-1 truncate bg-background"
+                value={selectedExampleIndex.toString()}
+                onChange={(e) =>
+                  onExampleChange?.({
+                    contentTypeIndex: selectedContentIndex,
+                    exampleIndex: Number(e.target.value),
+                  })
+                }
+              >
+                {examples.map((example, index) => (
+                  <NativeSelectOption
+                    key={
+                      example.summary ||
+                      example.name ||
+                      example.description ||
+                      `Example ${index + 1}`
+                    }
+                    value={index.toString()}
+                  >
+                    {example.summary ||
+                      example.name ||
+                      example.description ||
+                      `Example ${index + 1}`}
+                  </NativeSelectOption>
+                ))}
+              </NativeSelect>
+            )}
+          </div>
+        )}
+      </SidecarBox.Footer>
+    </>
+  );
+};

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

@@ -0,0 +1,46 @@
+import { ChevronsUpDownIcon } from "lucide-react";
+import type { ChangeEventHandler } from "react";
+import { cn } from "../../util/cn.js";
+
+export const SimpleSelect = ({
+  value,
+  onChange,
+  className,
+  options,
+  showChevrons = true,
+}: {
+  value: string;
+  onChange: ChangeEventHandler<HTMLSelectElement>;
+  className?: string;
+  options: {
+    value: string;
+    label: string;
+  }[];
+  showChevrons?: boolean;
+}) => (
+  <div className="grid">
+    <select
+      className={cn(
+        "w-full row-start-1 col-start-1 border border-input text-foreground px-2 py-1 pe-6",
+        "rounded-md appearance-none bg-zinc-50 hover:bg-white dark:bg-zinc-800 hover:dark:bg-zinc-800/75",
+        className,
+      )}
+      value={value}
+      onChange={onChange}
+    >
+      {options.map((option) => (
+        <option value={option.value} key={option.value}>
+          {option.label}
+        </option>
+      ))}
+    </select>
+    <div
+      className={cn(
+        !showChevrons && "hidden",
+        "row-start-1 col-start-1 self-center justify-self-end relative end-2 pointer-events-none",
+      )}
+    >
+      <ChevronsUpDownIcon size={14} />
+    </div>
+  </div>
+);

package/src/lib/plugins/openapi/client/GraphQLClient.tsx

@@ -0,0 +1,73 @@
+import type { GraphQLError } from "graphql/error/index.js";
+import type { SchemaImports } from "../../../oas/graphql/index.js";
+import { ZudokuError } from "../../../util/invariant.js";
+import type { TypedDocumentString } from "../graphql/graphql.js";
+import type { OpenApiPluginOptions } from "../index.js";
+import type { LocalServer } from "./createServer.js";
+
+let localServerPromise: Promise<LocalServer> | undefined;
+const sharedSchemaImports: SchemaImports = {};
+
+type GraphQLResponse<TResult> = {
+  errors?: GraphQLError[];
+  data: TResult;
+};
+
+const throwIfError = (response: GraphQLResponse<unknown>) => {
+  if (!response.errors?.[0]) return;
+
+  throw new ZudokuError(response.errors[0].message, {
+    developerHint:
+      "Check your configuration value `apis.type` and `apis.input` in the Zudoku config.",
+  });
+};
+
+export class GraphQLClient {
+  private readonly config: OpenApiPluginOptions;
+  constructor(config: OpenApiPluginOptions) {
+    if (config.schemaImports) {
+      Object.assign(sharedSchemaImports, config.schemaImports);
+    }
+    this.config = config;
+  }
+
+  #getLocalServer = async () => {
+    if (!localServerPromise) {
+      localServerPromise = import("./createServer.js").then((m) =>
+        m.createServer({ ...this.config, schemaImports: sharedSchemaImports }),
+      );
+    }
+    return localServerPromise;
+  };
+
+  #executeFetch = async (init: RequestInit): Promise<Response> => {
+    if (this.config.server) {
+      return fetch(this.config.server, init);
+    }
+
+    const localServer = await this.#getLocalServer();
+    return localServer.fetch("http://localhost/graphql", init);
+  };
+
+  fetch = async <TResult, TVariables>(
+    query: TypedDocumentString<TResult, TVariables>,
+    variables?: TVariables,
+  ): Promise<TResult> => {
+    const operationName = query.match(/query (\w+)/)?.[1];
+
+    const response = await this.#executeFetch({
+      method: "POST",
+      body: JSON.stringify({ query, variables, operationName }),
+      headers: { "Content-Type": "application/json" },
+    });
+
+    if (!response.ok) {
+      throw new Error("Network response was not ok");
+    }
+
+    const result = (await response.json()) as GraphQLResponse<TResult>;
+    throwIfError(result);
+
+    return result.data;
+  };
+}

package/src/lib/plugins/openapi/client/GraphQLContext.tsx

@@ -0,0 +1,16 @@
+import { createContext, type ReactNode } from "react";
+import type { GraphQLClient } from "./GraphQLClient.js";
+
+export const GraphQLContext = createContext<GraphQLClient | undefined>(
+  undefined,
+);
+
+export const GraphQLProvider = ({
+  children,
+  client,
+}: {
+  children: ReactNode;
+  client: GraphQLClient;
+}) => (
+  <GraphQLContext.Provider value={client}>{children}</GraphQLContext.Provider>
+);