zudoku 0.1.1-dev.9 → 0.3.0-dev.100

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

@@ -0,0 +1,87 @@
+import { useEffect, useRef, type ReactNode } from "react";
+import { useTheme } from "../../components/context/ThemeContext.js";
+import { cn } from "../../util/cn.js";
+import { pastellize } from "../../util/pastellize.js";
+
+export const DATA_ATTR = "data-linked-param";
+
+export const usePastellizedColor = (name: string) => {
+  const [isDark] = useTheme();
+  return pastellize(
+    name,
+    !isDark ? { saturation: 85, lightness: 50 } : undefined,
+  );
+};
+
+export const ColorizedParam = ({
+  name,
+  className,
+  backgroundOpacity = "100%",
+  borderOpacity = "100%",
+  slug,
+  children,
+  onClick,
+}: {
+  name: string;
+  className?: string;
+  backgroundOpacity?: string;
+  borderOpacity?: string;
+  slug?: string;
+  children?: ReactNode;
+  onClick?: () => void;
+}) => {
+  const ref = useRef<HTMLSpanElement>(null);
+  const normalized = name.replace(/[{}]/g, "");
+  const normalizedSlug = slug?.replace(/[{}]/g, "");
+  const color = usePastellizedColor(normalized);
+
+  const borderColor = `hsl(${color} / ${borderOpacity})`;
+  const backgroundColor = `hsl(${color} / ${backgroundOpacity})`;
+
+  useEffect(() => {
+    if (!normalizedSlug) return;
+    if (!ref.current) return;
+
+    const onMouseEnter = () => {
+      document
+        .querySelectorAll(`[${DATA_ATTR}="${normalizedSlug}"]`)
+        .forEach((el) => {
+          if (el instanceof HTMLElement) {
+            el.dataset.active = "true";
+          }
+        });
+    };
+    const onMouseLeave = () => {
+      document
+        .querySelectorAll(`[${DATA_ATTR}="${normalizedSlug}"]`)
+        .forEach((el) => {
+          if (el instanceof HTMLElement) {
+            el.dataset.active = "false";
+          }
+        });
+    };
+
+    ref.current.addEventListener("mouseenter", onMouseEnter);
+    ref.current.addEventListener("mouseleave", onMouseLeave);
+
+    return () => {
+      ref.current?.removeEventListener("mouseenter", onMouseEnter);
+      ref.current?.removeEventListener("mouseleave", onMouseLeave);
+    };
+  }, [normalizedSlug]);
+
+  return (
+    <span
+      className={cn("inline-flex relative rounded group", className)}
+      {...{ [DATA_ATTR]: normalizedSlug }}
+      ref={ref}
+      onClick={onClick}
+    >
+      <span
+        className="absolute inset-0 border-b-2 transition-opacity duration-200 opacity-30 group-data-[active=true]:opacity-100"
+        style={{ borderColor, backgroundColor }}
+      />
+      <span className="relative">{children ?? name}</span>
+    </span>
+  );
+};

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

@@ -0,0 +1,163 @@
+import { ResultOf } from "@graphql-typed-document-node/core";
+import { CategoryHeading } from "../../components/CategoryHeading.js";
+import { DeveloperHint } from "../../components/DeveloperHint.js";
+import { ErrorPage } from "../../components/ErrorPage.js";
+import { Heading } from "../../components/Heading.js";
+import { InlineCode } from "../../components/InlineCode.js";
+import { Markdown } from "../../components/Markdown.js";
+import { SyntaxHighlight } from "../../components/SyntaxHighlight.js";
+import { cn } from "../../util/cn.js";
+import { OperationListItem } from "./OperationListItem.js";
+import StaggeredRender from "./StaggeredRender.js";
+import { useOasConfig } from "./context.js";
+import { graphql } from "./graphql/index.js";
+import { SchemaProseClasses } from "./util/prose.js";
+import { useQuery } from "./util/urql.js";
+
+export const OperationsFragment = graphql(/* GraphQL */ `
+  fragment OperationsFragment on OperationItem {
+    slug
+    summary
+    method
+    description
+    operationId
+    contentTypes
+    path
+    parameters {
+      name
+      in
+      description
+      required
+      schema
+      style
+      examples {
+        name
+        description
+        externalValue
+        value
+        summary
+      }
+    }
+    requestBody {
+      content {
+        mediaType
+        encoding {
+          name
+        }
+        schema
+      }
+      description
+      required
+    }
+    responses {
+      statusCode
+      links
+      description
+      content {
+        mediaType
+        encoding {
+          name
+        }
+        schema
+      }
+    }
+  }
+`);
+
+export type OperationListItemResult = ResultOf<typeof OperationsFragment>;
+
+const AllOperationsQuery = graphql(/* GraphQL */ `
+  query AllOperations($input: JSON!, $type: SchemaType!) {
+    schema(input: $input, type: $type) {
+      description
+      title
+      url
+      version
+      tags {
+        name
+        description
+        operations {
+          slug
+          ...OperationsFragment
+        }
+      }
+    }
+  }
+`);
+
+const suspenseContext = { suspense: true };
+
+export const OperationList = () => {
+  const { type, input } = useOasConfig();
+
+  const [result] = useQuery({
+    query: AllOperationsQuery,
+    variables: { type, input },
+    context: suspenseContext,
+  });
+
+  const error = result.error?.graphQLErrors.at(0);
+
+  // Looks like there is no Suspense level error handling (yet)?
+  // So we handle the error case in the component directly
+  if (error) {
+    return (
+      <ErrorPage
+        category="Error"
+        title="Schema cannot be displayed"
+        message={
+          <>
+            <DeveloperHint className="mb-4">
+              Check your configuration value <InlineCode>apis.type</InlineCode>{" "}
+              and <InlineCode>apis.input</InlineCode> in the Zudoku config.
+            </DeveloperHint>
+            An error occurred while trying to fetch the API reference:
+            <SyntaxHighlight code={error.toString()} language="plain" />
+          </>
+        }
+      />
+    );
+  }
+
+  if (!result.data) return null;
+
+  return (
+    <div className="pt-[--padding-content-top]">
+      <div
+        className={cn(
+          SchemaProseClasses,
+          "mb-16 max-w-full prose-img:max-w-prose",
+        )}
+      >
+        <CategoryHeading>Overview</CategoryHeading>
+        <Heading level={1} id="description" registerSidebarAnchor>
+          {result.data.schema.title}
+        </Heading>
+        <Markdown content={result.data.schema.description ?? ""} />
+      </div>
+      {result.data.schema.tags
+        .filter((tag) => tag.operations.length > 0)
+        .map((tag) => (
+          <div key={tag.name}>
+            {tag.name && <CategoryHeading>{tag.name}</CategoryHeading>}
+            {tag.description && (
+              <Markdown
+                className={`${SchemaProseClasses} mt-2 mb-12`}
+                content={tag.description}
+              />
+            )}
+            <div className="operation mb-12">
+              <StaggeredRender>
+                {tag.operations.map((fragment) => (
+                  <OperationListItem
+                    key={fragment.slug}
+                    operationFragment={fragment}
+                  />
+                ))}
+              </StaggeredRender>
+            </div>
+          </div>
+        ))}
+    </div>
+  );
+};

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

@@ -0,0 +1,114 @@
+import { Heading } from "../../components/Heading.js";
+import { Markdown } from "../../components/Markdown.js";
+import { Card } from "../../ui/Card.js";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "../../ui/Tabs.js";
+import { groupBy } from "../../util/groupBy.js";
+import { renderIf } from "../../util/renderIf.js";
+import { OperationsFragment } from "./OperationList.js";
+import { ParameterList } from "./ParameterList.js";
+import { SchemaListView } from "./SchemaListView.js";
+import { Sidecar } from "./Sidecar.js";
+import { FragmentType, useFragment } from "./graphql/index.js";
+import { SchemaProseClasses } from "./util/prose.js";
+
+export const PARAM_GROUPS = ["path", "query", "header", "cookie"] as const;
+export type ParameterGroup = (typeof PARAM_GROUPS)[number];
+
+export const OperationListItem = ({
+  operationFragment,
+}: {
+  operationFragment: FragmentType<typeof OperationsFragment>;
+}) => {
+  const operation = useFragment(OperationsFragment, operationFragment);
+  const groupedParameters = groupBy(
+    operation.parameters ?? [],
+    (param) => param.in,
+  );
+
+  const first = operation.responses.at(0);
+  return (
+    <div
+      key={operation.operationId}
+      className="grid grid-cols-1 lg:grid-cols-[4fr_3fr] gap-8 items-start border-b-2 mb-16 pb-16"
+    >
+      <div className="flex flex-col gap-4">
+        <Heading level={2} id={operation.slug} registerSidebarAnchor>
+          {operation.summary}
+        </Heading>
+        {operation.description && (
+          <Markdown
+            className={SchemaProseClasses}
+            content={operation.description}
+          />
+        )}
+        {operation.parameters && operation.parameters.length > 0 && (
+          <>
+            {PARAM_GROUPS.flatMap((group) =>
+              groupedParameters[group]?.length ? (
+                <ParameterList
+                  key={group}
+                  id={operation.slug}
+                  parameters={groupedParameters[group]}
+                  group={group}
+                />
+              ) : (
+                []
+              ),
+            )}
+          </>
+        )}
+        {renderIf(operation.requestBody?.content?.at(0)?.schema, (schema) => (
+          <div className="mt-4 flex flex-col gap-4">
+            <Heading level={3} className="capitalize">
+              Request Body
+            </Heading>
+            <SchemaListView schema={schema} />
+          </div>
+        ))}
+        {operation.responses.length > 0 && (
+          <>
+            <Heading level={3} className="capitalize mt-8 pt-8 border-t">
+              Responses
+            </Heading>
+            <Tabs defaultValue={`${first?.statusCode}${first?.description}`}>
+              {operation.responses.length > 1 && (
+                <TabsList>
+                  {operation.responses.map((response) => (
+                    <TabsTrigger
+                      value={response.statusCode + response.description}
+                      key={response.statusCode}
+                      title={response.description}
+                    >
+                      {response.statusCode}
+                    </TabsTrigger>
+                  ))}
+                </TabsList>
+              )}
+              <ul className="list-none m-0 px-0 overflow-hidden">
+                {operation.responses.map((response) => (
+                  <TabsContent
+                    value={response.statusCode + response.description}
+                    key={response.statusCode}
+                  >
+                    {renderIf(
+                      response.content?.find((content) => content.schema),
+                      (content) => {
+                        return <SchemaListView schema={content.schema} />;
+                      },
+                    ) ?? (
+                      <Card className="font-mono text-sm p-4">
+                        No response body
+                      </Card>
+                    )}
+                  </TabsContent>
+                ))}
+              </ul>
+            </Tabs>
+          </>
+        )}
+      </div>
+
+      <Sidecar operation={operation} />
+    </div>
+  );
+};

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

@@ -0,0 +1,35 @@
+import { Heading } from "../../components/Heading.js";
+import { Card } from "../../ui/Card.js";
+import type { ParameterGroup } from "./OperationListItem.js";
+import {
+  ParameterListItem,
+  type ParameterListItemResult,
+} from "./ParameterListItem.js";
+
+export const ParameterList = ({
+  group,
+  parameters,
+  id,
+}: {
+  group: ParameterGroup;
+  parameters: ParameterListItemResult[];
+  id: string;
+}) => (
+  <>
+    <Heading level={3} id={`${id}/${group}-parameters`} className="capitalize">
+      {group === "header" ? "Headers" : `${group} Parameters`}
+    </Heading>
+    <Card>
+      <ul className="list-none m-0 px-0 divide-y ">
+        {parameters.map((parameter) => (
+          <ParameterListItem
+            key={`${parameter.name}-${parameter.in}`}
+            parameter={parameter}
+            id={id}
+            group={group}
+          />
+        ))}
+      </ul>
+    </Card>
+  </>
+);

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

@@ -0,0 +1,62 @@
+import { Markdown } from "../../components/Markdown.js";
+import { type SchemaObject } from "../../oas/graphql/index.js";
+import { ColorizedParam } from "./ColorizedParam.js";
+import type { OperationListItemResult } from "./OperationList.js";
+import type { ParameterGroup } from "./OperationListItem.js";
+
+const getParameterSchema = (
+  parameter: ParameterListItemResult,
+): SchemaObject => {
+  if (parameter.schema != null && typeof parameter.schema === "object") {
+    return parameter.schema;
+  }
+  return {
+    type: "string",
+  };
+};
+
+export type ParameterListItemResult = NonNullable<
+  OperationListItemResult["parameters"]
+>[number];
+
+export const ParameterListItem = ({
+  parameter,
+  group,
+  id,
+}: {
+  parameter: ParameterListItemResult;
+  group: ParameterGroup;
+  id: string;
+}) => (
+  <li className="p-4 bg-border/20 text-sm flex flex-col gap-1">
+    <div className="flex items-center gap-2">
+      <code>
+        {group === "path" ? (
+          <ColorizedParam
+            name={parameter.name}
+            backgroundOpacity="15%"
+            slug={id + "-" + parameter.name.toLocaleLowerCase()}
+          />
+        ) : (
+          parameter.name
+        )}
+      </code>
+      {parameter.required && (
+        <span className="py-px px-1.5 font-medium bg-primary/75 text-muted rounded-lg">
+          required
+        </span>
+      )}
+      {getParameterSchema(parameter).type && (
+        <span className="text-muted-foreground">
+          {getParameterSchema(parameter).type}
+        </span>
+      )}
+    </div>
+    {parameter.description && (
+      <Markdown
+        content={parameter.description}
+        className="text-sm prose-p:my-1"
+      />
+    )}
+  </li>
+);

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

@@ -0,0 +1,39 @@
+import type { OperationListItemResult } from "./OperationList.js";
+import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
+
+export const PlaygroundDialogWrapper = ({
+  server,
+  operation,
+}: {
+  server: string;
+  operation: OperationListItemResult;
+}) => {
+  const headers = operation.parameters
+    ?.filter((p) => p.in === "header")
+    .map((p) => ({
+      name: p.name,
+      defaultValue: p.examples?.find((x) => x.value)?.value ?? "",
+    }));
+  const queryParams = operation.parameters
+    ?.filter((p) => p.in === "query")
+    .sort((a, b) => (a.required && !b.required ? -1 : 1))
+    .map((p) => ({
+      name: p.name,
+      defaultActive: p.required ?? false,
+      isRequired: p.required ?? false,
+    }));
+  const pathParams = operation.parameters
+    ?.filter((p) => p.in === "path")
+    .map((p) => ({ name: p.name }));
+
+  return (
+    <PlaygroundDialog
+      server={server}
+      method={operation.method}
+      url={operation.path}
+      headers={headers}
+      queryParams={queryParams}
+      pathParams={pathParams}
+    />
+  );
+};

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

@@ -0,0 +1,39 @@
+import { SyntaxHighlight } from "../../components/SyntaxHighlight.js";
+import { type SchemaObject } from "../../oas/graphql/index.js";
+import type { OperationListItemResult } from "./OperationList.js";
+import * as SidecarBox from "./SidecarBox.js";
+import { generateSchemaExample } from "./util/generateSchemaExample.js";
+
+type Content = NonNullable<
+  NonNullable<OperationListItemResult["requestBody"]>["content"]
+>;
+
+// @todo should we handle multiple content types?
+export const RequestBodySidecarBox = ({ content }: { content: Content }) => {
+  if (!content.length) return null;
+
+  return (
+    <>
+      <SidecarBox.Root>
+        <SidecarBox.Head className="text-xs flex justify-between items-center">
+          <span className="font-mono">Request Body Example</span>
+        </SidecarBox.Head>
+        <SidecarBox.Body>
+          <SyntaxHighlight
+            language="json"
+            noBackground
+            copyable
+            className="text-xs"
+            code={JSON.stringify(
+              content.at(0)?.schema
+                ? generateSchemaExample(content[0].schema as SchemaObject)
+                : "",
+              null,
+              2,
+            )}
+          />
+        </SidecarBox.Body>
+      </SidecarBox.Root>
+    </>
+  );
+};

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

@@ -0,0 +1,60 @@
+import { useState } from "react";
+import { SyntaxHighlight } from "../../components/SyntaxHighlight.js";
+import { type SchemaObject } from "../../oas/graphql/index.js";
+import { cn } from "../../util/cn.js";
+import type { OperationListItemResult } from "./OperationList.js";
+import * as SidecarBox from "./SidecarBox.js";
+import { generateSchemaExample } from "./util/generateSchemaExample.js";
+
+type Responses = OperationListItemResult["responses"];
+export const ResponsesSidecarBox = ({
+  responses,
+}: {
+  responses: Responses;
+}) => {
+  const [tabIndex, setTabIndex] = useState(0);
+
+  const activeTab = responses[tabIndex];
+  const schema = activeTab.content?.[0]?.schema as SchemaObject | undefined;
+
+  return (
+    <SidecarBox.Root>
+      <SidecarBox.Head className="text-xs grid grid-rows-2 pb-0">
+        <span className="font-mono">Example Responses</span>
+        <div className="flex gap-2">
+          {responses.map((response, index) => (
+            <div
+              key={response.statusCode}
+              onClick={() => setTabIndex(index)}
+              className={cn(
+                "text-xs font-mono px-1.5 py-1 pb-px translate-y-px border-b-2 border-transparent rounded-t cursor-pointer",
+                tabIndex === index
+                  ? "text-primary dark:text-inherit border-primary"
+                  : "hover:border-accent-foreground/25",
+              )}
+            >
+              {response.statusCode}
+            </div>
+          ))}
+        </div>
+      </SidecarBox.Head>
+      <SidecarBox.Body>
+        {schema ? (
+          <SyntaxHighlight
+            language="json"
+            noBackground
+            className="text-xs"
+            code={JSON.stringify(generateSchemaExample(schema), null, 2)}
+          />
+        ) : (
+          <span className="text-muted-foreground font-mono italic text-xs">
+            Empty Response
+          </span>
+        )}
+      </SidecarBox.Body>
+      <SidecarBox.Footer className="flex justify-end text-xs">
+        {responses[tabIndex].description}
+      </SidecarBox.Footer>
+    </SidecarBox.Root>
+  );
+};

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

@@ -0,0 +1,21 @@
+import { Outlet } from "react-router-dom";
+import { OasConfigProvider } from "./context.js";
+import { OasPluginConfig } from "./interfaces.js";
+
+import { Provider, Client as UrqlClient } from "./util/urql.js";
+
+export function OpenApiRoute({
+  config,
+  client,
+}: {
+  config: OasPluginConfig;
+  client: typeof UrqlClient;
+}) {
+  return (
+    <Provider value={client}>
+      <OasConfigProvider value={{ config }}>
+        <Outlet />
+      </OasConfigProvider>
+    </Provider>
+  );
+}