@mehdad67/apitogo 0.1.24

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

@@ -0,0 +1,183 @@
+import { Badge } from "@lukoweb/apitogo/ui/Badge.js";
+import { Separator } from "@lukoweb/apitogo/ui/Separator.js";
+import { useState } from "react";
+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 { renderIf } from "../../util/renderIf.js";
+import { ResponseContent } from "./components/ResponseContent.js";
+import { SelectOnClick } from "./components/SelectOnClick.js";
+import { useOasConfig } from "./context.js";
+import { type FragmentType, useFragment } from "./graphql/index.js";
+import { MCPEndpoint } from "./MCPEndpoint.js";
+import { OperationsFragment } from "./OperationList.js";
+import { ParameterList } from "./ParameterList.js";
+import { SchemaView } from "./schema/SchemaView.js";
+import { Sidecar } from "./Sidecar.js";
+import { methodForColor } from "./util/methodToColor.js";
+
+const PARAM_GROUPS = ["path", "query", "header", "cookie"] as const;
+export type ParameterGroup = (typeof PARAM_GROUPS)[number];
+
+export const OperationListItem = ({
+  operationFragment,
+  globalSelectedServer,
+  shouldLazyHighlight,
+}: {
+  operationFragment: FragmentType<typeof OperationsFragment>;
+  globalSelectedServer?: string;
+  shouldLazyHighlight?: boolean;
+}) => {
+  const operation = useFragment(OperationsFragment, operationFragment);
+  const groupedParameters = Object.groupBy(
+    operation.parameters ?? [],
+    (param) => param.in,
+  );
+  const { options } = useOasConfig();
+
+  // 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 displayServerUrl = globalSelectedServer || operation.servers.at(0)?.url;
+
+  const first = operation.responses.at(0);
+  const [selectedResponse, setSelectedResponse] = useState(first?.statusCode);
+  const isMCPEndpoint = operation.extensions?.["x-mcp-server"] !== undefined;
+
+  return (
+    <div>
+      {operation.deprecated && (
+        <Badge variant="muted" className="text-xs mb-4">
+          deprecated
+        </Badge>
+      )}
+      <div
+        key={operation.operationId}
+        className={cn(
+          "grid grid-cols-1 lg:grid-cols-[minmax(0,4fr)_minmax(0,3fr)] gap-x-8 gap-y-4 items-start",
+          operation.deprecated && "opacity-50 transition hover:opacity-100",
+        )}
+      >
+        <Heading
+          level={2}
+          id={operation.slug}
+          registerNavigationAnchor
+          className="break-all col-span-full"
+        >
+          {operation.summary}
+        </Heading>
+        {!isMCPEndpoint && (
+          <div className="text-sm flex gap-2 font-mono col-span-full">
+            <span className={methodForColor(operation.method)}>
+              {operation.method.toUpperCase()}
+            </span>
+            <SelectOnClick className="max-w-full truncate flex cursor-pointer">
+              {displayServerUrl && (
+                <div className="text-neutral-400 dark:text-neutral-500 truncate">
+                  {displayServerUrl.replace(/\/$/, "")}
+                </div>
+              )}
+              <div className="text-neutral-900 dark:text-neutral-200">
+                {operation.path}
+              </div>
+            </SelectOnClick>
+          </div>
+        )}
+
+        {isMCPEndpoint ? (
+          <div className="col-span-full">
+            <MCPEndpoint
+              serverUrl={displayServerUrl}
+              summary={operation.summary ?? undefined}
+              data={operation.extensions?.["x-mcp-server"]}
+            />
+          </div>
+        ) : (
+          <div
+            className={cn(
+              "flex flex-col gap-4",
+              options?.disableSidecar && "col-span-full",
+            )}
+          >
+            {operation.description && (
+              <Markdown
+                className="max-w-full prose-img:max-w-prose"
+                content={operation.description}
+              />
+            )}
+            {operation.parameters &&
+              operation.parameters.length > 0 &&
+              PARAM_GROUPS.flatMap((group) =>
+                groupedParameters[group]?.length ? (
+                  <ParameterList
+                    key={group}
+                    summary={operation.summary ?? undefined}
+                    id={operation.slug}
+                    parameters={groupedParameters[group]}
+                    group={group}
+                  />
+                ) : (
+                  []
+                ),
+              )}
+            {renderIf(operation.requestBody?.content?.at(0)?.schema, () => (
+              <Separator className="my-4" />
+            ))}
+            {renderIf(
+              operation.requestBody?.content?.at(0)?.schema,
+              (schema) => (
+                <div className="flex flex-col gap-4">
+                  <Heading
+                    level={3}
+                    className="capitalize flex items-center gap-2"
+                    id={`${operation.slug}/request-body`}
+                  >
+                    {operation.summary && (
+                      <PagefindSearchMeta>
+                        {operation.summary} &rsaquo;{" "}
+                      </PagefindSearchMeta>
+                    )}
+                    Request Body{" "}
+                    {operation.requestBody?.required === false ? (
+                      <Badge variant="muted">optional</Badge>
+                    ) : (
+                      ""
+                    )}
+                  </Heading>
+                  <SchemaView schema={schema} />
+                </div>
+              ),
+            )}
+            <Separator className="my-4" />
+            {operation.responses.length > 0 && (
+              <>
+                <Heading level={3} id={`${operation.slug}/responses`}>
+                  {operation.summary && (
+                    <PagefindSearchMeta>
+                      {operation.summary} &rsaquo;{" "}
+                    </PagefindSearchMeta>
+                  )}
+                  Responses
+                </Heading>
+                <ResponseContent
+                  responses={operation.responses}
+                  selectedResponse={selectedResponse}
+                  onSelectResponse={setSelectedResponse}
+                />
+              </>
+            )}
+          </div>
+        )}
+
+        {renderIf(!options?.disableSidecar && !isMCPEndpoint, () => (
+          <Sidecar
+            selectedResponse={selectedResponse}
+            operation={operation}
+            globalSelectedServer={globalSelectedServer}
+            shouldLazyHighlight={shouldLazyHighlight}
+          />
+        ))}
+      </div>
+    </div>
+  );
+};

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

@@ -0,0 +1,96 @@
+import { ChevronsLeftRightIcon } from "lucide-react";
+import { isValidElement, useState } from "react";
+import { InlineCode } from "../../components/InlineCode.js";
+import type { SchemaObject } from "../../oas/parser/index.js";
+import { cn } from "../../util/cn.js";
+
+const Pattern = ({ pattern }: { pattern: string }) => {
+  const [isExpanded, setIsExpanded] = useState(false);
+  const isExpandable = pattern.length > 20;
+  const shortPattern = isExpandable ? `${pattern.slice(0, 20)}…` : pattern;
+
+  return (
+    <InlineCode
+      className={cn("text-xs", isExpandable && "cursor-pointer")}
+      onClick={() => setIsExpanded(!isExpanded)}
+    >
+      {isExpanded ? pattern : shortPattern}
+      {isExpandable && (
+        <button type="button" className="p-1 translate-y-[2px]">
+          {!isExpanded && <ChevronsLeftRightIcon size={12} />}
+        </button>
+      )}
+    </InlineCode>
+  );
+};
+
+const getSchemaInfos = (schema?: SchemaObject) => {
+  if (!schema) return [];
+
+  const items =
+    schema.type === "array" && typeof schema.items === "object"
+      ? schema.items
+      : undefined;
+
+  return [
+    items?.type
+      ? Array.isArray(items.type)
+        ? `(${items.type.join(" | ")})[]`
+        : `${items.type}[]`
+      : Array.isArray(schema.type)
+        ? schema.type.join(" | ")
+        : schema.type,
+
+    schema.enum && "enum",
+    schema.const && "const",
+    schema.format,
+    items?.contentMediaType,
+    schema.minimum !== undefined && `min: ${schema.minimum}`,
+    schema.maximum !== undefined && `max: ${schema.maximum}`,
+    schema.minLength !== undefined && `minLength: ${schema.minLength}`,
+    schema.maxLength !== undefined && `maxLength: ${schema.maxLength}`,
+    schema.minItems !== undefined && `minItems: ${schema.minItems}`,
+    schema.maxItems !== undefined && `maxItems: ${schema.maxItems}`,
+    schema.minProperties !== undefined && `minProps: ${schema.minProperties}`,
+    schema.maxProperties !== undefined && `maxProps: ${schema.maxProperties}`,
+    schema.uniqueItems && "unique",
+    schema.readOnly && "readOnly",
+    schema.writeOnly && "writeOnly",
+    schema.deprecated && "deprecated",
+    schema.pattern && (
+      <>
+        pattern: <Pattern pattern={schema.pattern} />
+      </>
+    ),
+  ];
+};
+
+export const ParamInfos = ({
+  schema,
+  extraItems = [],
+  className,
+}: {
+  schema?: SchemaObject;
+  extraItems?: unknown[];
+  className?: string;
+}) => {
+  const filteredItems = [...getSchemaInfos(schema), ...extraItems].flatMap(
+    (item) => (typeof item === "string" || isValidElement(item) ? item : []),
+  );
+
+  return (
+    <span className={className}>
+      {filteredItems.map((item, index) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: index should be stable
+        <span className="text-muted-foreground" key={index}>
+          {item}
+          {index < filteredItems.length - 1 && (
+            <span className="text-muted-foreground/50">
+              &nbsp;&middot;&nbsp;
+            </span>
+          )}
+        </span>
+      ))}
+    </span>
+  );
+};

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

@@ -0,0 +1,53 @@
+import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
+import { Fragment } from "react";
+import { Heading } from "../../components/Heading.js";
+import { Frame, FramePanel } from "../../ui/Frame.js";
+import { ItemGroup, ItemSeparator } from "../../ui/Item.js";
+import type { ParameterItem } from "./graphql/graphql.js";
+import type { ParameterGroup } from "./OperationListItem.js";
+import { ParameterListItem } from "./ParameterListItem.js";
+
+export const ParameterList = ({
+  summary,
+  group,
+  parameters,
+  id,
+}: {
+  summary?: string;
+  group: ParameterGroup;
+  parameters: ParameterItem[];
+  id: string;
+}) => {
+  const sortedParameters = parameters.sort((a, b) =>
+    a.required === b.required ? 0 : a.required ? -1 : 1,
+  );
+
+  return (
+    <>
+      <Heading
+        level={3}
+        id={`${id}/${group}-parameters`}
+        className="capitalize"
+      >
+        {summary && <VisuallyHidden>{summary} &rsaquo; </VisuallyHidden>}
+        {group === "header" ? "Headers" : `${group} Parameters`}
+      </Heading>
+      <Frame>
+        <FramePanel className="p-0!">
+          <ItemGroup className="overflow-clip">
+            {sortedParameters.map((parameter, index) => (
+              <Fragment key={`${parameter.name}-${parameter.in}`}>
+                {index > 0 && <ItemSeparator />}
+                <ParameterListItem
+                  parameter={parameter}
+                  id={id}
+                  group={group}
+                />
+              </Fragment>
+            ))}
+          </ItemGroup>
+        </FramePanel>
+      </Frame>
+    </>
+  );
+};

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

@@ -0,0 +1,161 @@
+import * as Collapsible from "@radix-ui/react-collapsible";
+import { MinusIcon, PlusIcon } from "lucide-react";
+import { useState } from "react";
+import { Markdown } from "../../components/Markdown.js";
+import type { SchemaObject } from "../../oas/graphql/index.js";
+import { Button } from "../../ui/Button.js";
+import { Item, ItemActions, ItemContent, ItemTitle } from "../../ui/Item.js";
+import { cn } from "../../util/cn.js";
+import { ColorizedParam } from "./ColorizedParam.js";
+import { EnumValues } from "./components/EnumValues.js";
+import type { ParameterItem } from "./graphql/graphql.js";
+import type { ParameterGroup } from "./OperationListItem.js";
+import { ParamInfos } from "./ParamInfos.js";
+import { SchemaExampleAndDefault } from "./schema/SchemaExampleAndDefault.js";
+import { SchemaView } from "./schema/SchemaView.js";
+import { isArrayType } from "./schema/utils.js";
+
+const getParameterSchema = (parameter: ParameterItem): SchemaObject => {
+  if (parameter.schema != null && typeof parameter.schema === "object") {
+    return parameter.schema;
+  }
+  return {
+    type: "string",
+  };
+};
+
+export const ParameterListItem = ({
+  parameter,
+  group,
+  id,
+}: {
+  parameter: ParameterItem;
+  group: ParameterGroup;
+  id: string;
+}) => {
+  const paramSchema = getParameterSchema(parameter);
+  const [isOpen, setIsOpen] = useState(false);
+
+  const isCollapsible =
+    paramSchema.type === "object" ||
+    (isArrayType(paramSchema) &&
+      "items" in paramSchema &&
+      paramSchema.items?.type === "object");
+
+  const shouldRenderDescription = Boolean(
+    parameter.description ||
+    paramSchema.description ||
+    (paramSchema.type === "array" && paramSchema.items?.enum) ||
+    paramSchema.enum ||
+    paramSchema.example !== undefined ||
+    paramSchema.default !== undefined,
+  );
+
+  return (
+    <Item>
+      <ItemContent className="gap-y-2">
+        <div>
+          <ItemTitle className="inline me-2">
+            {isCollapsible ? (
+              <button
+                onClick={() => setIsOpen(!isOpen)}
+                type="button"
+                className="hover:underline"
+              >
+                <code>
+                  {group === "path" ? (
+                    <ColorizedParam
+                      name={parameter.name}
+                      backgroundOpacity="15%"
+                      className="px-2"
+                      slug={`${id}-${parameter.name}`}
+                    />
+                  ) : (
+                    parameter.name
+                  )}
+                </code>
+              </button>
+            ) : (
+              <code>
+                {group === "path" ? (
+                  <ColorizedParam
+                    name={parameter.name}
+                    backgroundOpacity="15%"
+                    className="px-2"
+                    slug={`${id}-${parameter.name}`}
+                  />
+                ) : (
+                  parameter.name
+                )}
+              </code>
+            )}
+          </ItemTitle>
+          {"\u200B"}
+          <ParamInfos
+            className="inline"
+            schema={paramSchema}
+            extraItems={[
+              parameter.required && (
+                <span className="text-primary">required</span>
+              ),
+              parameter.style && `style: ${parameter.style}`,
+              parameter.explode && `explode: ${parameter.explode}`,
+            ]}
+          />
+        </div>
+        {shouldRenderDescription && (
+          <div className="flex flex-col gap-1.5">
+            {parameter.description && (
+              <Markdown content={parameter.description} className="prose-sm" />
+            )}
+            {paramSchema.description && (
+              <Markdown
+                content={paramSchema.description}
+                className="prose-sm"
+              />
+            )}
+            {paramSchema.type === "array" && paramSchema.items?.enum ? (
+              <EnumValues values={paramSchema.items.enum} />
+            ) : (
+              paramSchema.enum && <EnumValues values={paramSchema.enum} />
+            )}
+            <SchemaExampleAndDefault schema={paramSchema} />
+          </div>
+        )}
+      </ItemContent>
+
+      {isCollapsible && (
+        <ItemActions className="self-start">
+          <Button
+            variant="ghost"
+            size="icon"
+            className="rounded-full"
+            onClick={() => setIsOpen(!isOpen)}
+            aria-label="Toggle parameter"
+          >
+            {isOpen ? <MinusIcon size={16} /> : <PlusIcon size={16} />}
+          </Button>
+        </ItemActions>
+      )}
+
+      {isCollapsible && (
+        <Collapsible.Root
+          defaultOpen={false}
+          open={isOpen}
+          onOpenChange={setIsOpen}
+          className={cn("w-full", !isOpen && "contents")}
+        >
+          <Collapsible.Content asChild>
+            <ItemContent>
+              <SchemaView
+                schema={
+                  "items" in paramSchema ? paramSchema.items : paramSchema
+                }
+              />
+            </ItemContent>
+          </Collapsible.Content>
+        </Collapsible.Root>
+      )}
+    </Item>
+  );
+};

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

@@ -0,0 +1,67 @@
+import type {
+  MediaTypeObject,
+  OperationsFragmentFragment,
+} from "./graphql/graphql.js";
+import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
+
+export const PlaygroundDialogWrapper = ({
+  server,
+  servers,
+  operation,
+  examples,
+}: {
+  server?: string;
+  servers?: string[];
+  operation: OperationsFragmentFragment;
+  examples?: MediaTypeObject[];
+}) => {
+  const headers = operation.parameters
+    ?.filter((p) => p.in === "header")
+    .sort((a, b) => (a.required && !b.required ? -1 : 1))
+    .map((p) => ({
+      name: p.name,
+      defaultValue:
+        p.schema?.default ?? p.examples?.find((x) => x.value)?.value ?? "",
+      defaultActive: p.required ?? false,
+      isRequired: p.required ?? false,
+      enum: p.schema?.type === "array" ? p.schema?.items?.enum : p.schema?.enum,
+      type: p.schema?.type ?? "string",
+    }));
+
+  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,
+      enum: p.schema?.type === "array" ? p.schema?.items?.enum : p.schema?.enum,
+      type: p.schema?.type ?? "string",
+      defaultValue: Array.isArray(p.schema?.default)
+        ? JSON.stringify(p.schema.default)
+        : p.schema?.default,
+      style: p.style ?? undefined,
+      explode: p.explode ?? undefined,
+      allowReserved: p.allowReserved ?? undefined,
+    }));
+
+  const pathParams = operation.parameters
+    ?.filter((p) => p.in === "path")
+    .map((p) => ({
+      name: p.name,
+      defaultValue: p.schema?.default,
+    }));
+
+  return (
+    <PlaygroundDialog
+      server={server}
+      servers={servers}
+      method={operation.method}
+      url={operation.path}
+      headers={headers}
+      queryParams={queryParams}
+      pathParams={pathParams}
+      examples={examples}
+    />
+  );
+};

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

@@ -0,0 +1,63 @@
+import { Button } from "@lukoweb/apitogo/components";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@lukoweb/apitogo/ui/Collapsible.js";
+import { ChevronsDownUpIcon, ChevronsUpDownIcon } from "lucide-react";
+import type { MediaTypeObject } from "./graphql/graphql.js";
+import * as SidecarBox from "./SidecarBox.js";
+import { SidecarExamples } from "./SidecarExamples.js";
+
+export const RequestBodySidecarBox = ({
+  content,
+  onExampleChange,
+  isOnScreen,
+  shouldLazyHighlight,
+  selectedContentIndex,
+  selectedExampleIndex,
+}: {
+  content: MediaTypeObject[];
+  onExampleChange?: (selected: {
+    contentTypeIndex: number;
+    exampleIndex: number;
+  }) => void;
+  isOnScreen: boolean;
+  shouldLazyHighlight?: boolean;
+  selectedContentIndex: number;
+  selectedExampleIndex: number;
+}) => {
+  if (content.length === 0) return null;
+
+  return (
+    <Collapsible className="group/collapsible" defaultOpen>
+      <SidecarBox.Root>
+        <SidecarBox.Head className="text-xs flex justify-between items-center">
+          <span className="flex items-center gap-1 font-medium">
+            <CollapsibleTrigger asChild>
+              <Button
+                variant="ghost"
+                className="size-fit px-1 py-1 -my-1"
+                aria-label="Toggle request body examples"
+              >
+                <ChevronsDownUpIcon className="size-[1em] group-data-[state=closed]/collapsible:hidden" />
+                <ChevronsUpDownIcon className="size-[1em] group-data-[state=open]/collapsible:hidden" />
+              </Button>
+            </CollapsibleTrigger>
+            Example Request Body
+          </span>
+        </SidecarBox.Head>
+        <CollapsibleContent>
+          <SidecarExamples
+            selectedContentIndex={selectedContentIndex}
+            selectedExampleIndex={selectedExampleIndex}
+            content={content}
+            onExampleChange={onExampleChange}
+            isOnScreen={isOnScreen}
+            shouldLazyHighlight={shouldLazyHighlight}
+          />
+        </CollapsibleContent>
+      </SidecarBox.Root>
+    </Collapsible>
+  );
+};