extract doc-explorer plugin from @graphiql/react and publish as @graphiql/plugin-doc-explorer package

.changeset/gentle-houses-add.md

@@ -0,0 +1,29 @@
+---
+'@graphiql/plugin-doc-explorer': patch
+'@graphiql/react': minor
+'graphiql': patch
+---
+
+- remove the following exports from `@graphiql/react` and move them in `@graphiql/plugin-doc-explorer` package:
+  - Argument
+  - DefaultValue
+  - DeprecationReason
+  - Directive
+  - DocExplorer
+  - ExplorerContext
+  - ExplorerContextProvider
+  - ExplorerSection
+  - FieldDocumentation
+  - FieldLink
+  - SchemaDocumentation
+  - Search
+  - TypeDocumentation
+  - TypeLink
+  - useExplorerContext
+  - DOC_EXPLORER_PLUGIN
+  - ExplorerContextType
+  - ExplorerFieldDef
+  - ExplorerNavStack
+  - ExplorerNavStackItem
+
+- add new `referencePlugin` prop on `PluginContextProviderProps` component for plugin which is used to display the reference documentation when selecting a type.

.eslintrc.js

@@ -358,6 +358,7 @@ module.exports = {
         ],
         'unicorn/no-length-as-slice-end': 'error',
         'unicorn/prefer-string-replace-all': 'error',
+        'unicorn/prefer-array-some': 'error',
         'unicorn/no-hex-escape': 'off', // TODO: enable
         // doesn't catch a lot of cases; we use ESLint builtin `no-restricted-syntax` to forbid `.keyCode`
         'unicorn/prefer-keyboard-event-key': 'off',

functions/graphql.ts

@@ -10,7 +10,7 @@ import type {
   HandlerContext as NetlifyHandlerContext,
 } from '@netlify/functions';
 
-import { schema } from '../packages/graphiql/test/schema.js';
+import { testSchema } from '../packages/graphiql/test/schema.js';
 import { customExecute } from '../packages/graphiql/test/execute.js';
 
 /**
@@ -57,4 +57,7 @@ export function createHandler<Context extends OperationContext = undefined>(
   };
 }
 
-export const handler = createHandler({ schema, execute: customExecute });
+export const handler = createHandler({
+  schema: testSchema,
+  execute: customExecute,
+});

packages/graphiql-plugin-doc-explorer/README.md

@@ -0,0 +1 @@
+# `@graphiql/plugin-doc-explorer`

packages/graphiql-plugin-doc-explorer/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@graphiql/plugin-doc-explorer",
+  "version": "0.0.0",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/graphql/graphiql",
+    "directory": "packages/graphiql-plugin-doc-explorer"
+  },
+  "homepage": "https://github.com/graphql/graphiql/tree/master/packages/graphiql-plugin-doc-explorer#readme",
+  "bugs": {
+    "url": "https://github.com/graphql/graphiql/issues?q=issue+label:@graphiql/plugin-doc-explorer"
+  },
+  "license": "MIT",
+  "exports": {
+    "./package.json": "./package.json",
+    "./style.css": "./dist/style.css",
+    ".": "./dist/index.js"
+  },
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "react",
+    "graphql",
+    "graphiql",
+    "plugin",
+    "documentation",
+    "explorer"
+  ],
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build",
+    "test": "vitest",
+    "types:check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19",
+    "graphql": "^15.5.0 || ^16.0.0 || ^17.0.0"
+  },
+  "dependencies": {
+    "react-compiler-runtime": "19.1.0-rc.1",
+    "@graphiql/react": "^0.31.0",
+    "@headlessui/react": "^2.2"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.4.1",
+    "vite-plugin-dts": "^4.5.3",
+    "babel-plugin-react-compiler": "19.1.0-rc.1",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "vite": "^6.3.4",
+    "graphql": "^16.9.0"
+  }
+}

packages/graphiql-react/src/explorer/components/__tests__/doc-explorer.spec.tsx → packages/graphiql-plugin-doc-explorer/src/components/__tests__/doc-explorer.spec.tsx

@@ -2,7 +2,7 @@ import { render } from '@testing-library/react';
 import { GraphQLInt, GraphQLObjectType, GraphQLSchema } from 'graphql';
 import { useContext, useEffect } from 'react';
 
-import { SchemaContext, SchemaContextType } from '../../../schema';
+import { SchemaContext, SchemaContextType } from '@graphiql/react';
 import { ExplorerContext, ExplorerContextProvider } from '../../context';
 import { DocExplorer } from '../doc-explorer';
 

packages/graphiql-react/src/explorer/components/__tests__/type-documentation.spec.tsx → packages/graphiql-plugin-doc-explorer/src/components/__tests__/type-documentation.spec.tsx

@@ -10,7 +10,7 @@ import {
   GraphQLUnionType,
 } from 'graphql';
 
-import { SchemaContext } from '../../../schema';
+import { SchemaContext } from '@graphiql/react';
 import { ExplorerContext } from '../../context';
 import { TypeDocumentation } from '../type-documentation';
 import { mockExplorerContextValue, unwrapType } from './test-utils';

packages/graphiql-react/src/explorer/components/argument.tsx → packages/graphiql-plugin-doc-explorer/src/components/argument.tsx

@@ -4,7 +4,7 @@ import { DefaultValue } from './default-value';
 import { TypeLink } from './type-link';
 
 import './argument.css';
-import { MarkdownContent } from '../../ui';
+import { MarkdownContent } from '@graphiql/react';
 
 type ArgumentProps = {
   /**

packages/graphiql-react/src/explorer/components/deprecation-reason.tsx → packages/graphiql-plugin-doc-explorer/src/components/deprecation-reason.tsx

@@ -1,4 +1,4 @@
-import { MarkdownContent } from '../../ui';
+import { MarkdownContent } from '@graphiql/react';
 
 import './deprecation-reason.css';
 

packages/graphiql-react/src/explorer/components/doc-explorer.tsx → packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.tsx

@@ -1,9 +1,7 @@
 import { isType } from 'graphql';
 import { ReactNode } from 'react';
 
-import { ChevronLeftIcon } from '../../icons';
-import { useSchemaContext } from '../../schema';
-import { Spinner } from '../../ui';
+import { ChevronLeftIcon, Spinner, useSchemaContext } from '@graphiql/react';
 import { useExplorerContext } from '../context';
 import { FieldDocumentation } from './field-documentation';
 import { SchemaDocumentation } from './schema-documentation';

packages/graphiql-react/src/explorer/components/field-documentation.tsx → packages/graphiql-plugin-doc-explorer/src/components/field-documentation.tsx

@@ -1,7 +1,7 @@
 import { GraphQLArgument } from 'graphql';
 import { useState } from 'react';
 
-import { Button, MarkdownContent } from '../../ui';
+import { Button, MarkdownContent } from '@graphiql/react';
 import { ExplorerFieldDef } from '../context';
 import { Argument } from './argument';
 import { DeprecationReason } from './deprecation-reason';

packages/graphiql-plugin-doc-explorer/src/components/index.ts

@@ -0,0 +1,12 @@
+export { Argument } from './argument';
+export { DefaultValue } from './default-value';
+export { DeprecationReason } from './deprecation-reason';
+export { Directive } from './directive';
+export { DocExplorer } from './doc-explorer';
+export { FieldDocumentation } from './field-documentation';
+export { FieldLink } from './field-link';
+export { SchemaDocumentation } from './schema-documentation';
+export { Search } from './search';
+export { ExplorerSection } from './section';
+export { TypeDocumentation } from './type-documentation';
+export { TypeLink } from './type-link';

packages/graphiql-react/src/explorer/components/schema-documentation.tsx → packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.tsx

@@ -1,6 +1,6 @@
 import type { GraphQLSchema } from 'graphql';
 
-import { MarkdownContent } from '../../ui';
+import { MarkdownContent } from '@graphiql/react';
 import { ExplorerSection } from './section';
 import { TypeLink } from './type-link';
 

packages/graphiql-react/src/explorer/components/search.tsx → packages/graphiql-plugin-doc-explorer/src/components/search.tsx

@@ -14,15 +14,17 @@ import {
   ComboboxOptions,
   ComboboxOption,
 } from '@headlessui/react';
-import { MagnifyingGlassIcon } from '../../icons';
-import { useSchemaContext } from '../../schema';
-import debounce from '../../utility/debounce';
+import {
+  isMacOs,
+  useSchemaContext,
+  MagnifyingGlassIcon,
+  debounce,
+} from '@graphiql/react';
 
 import { useExplorerContext } from '../context';
 
 import './search.css';
 import { renderType } from './utils';
-import { isMacOs } from '../../utility/is-macos';
 
 export const Search: FC = () => {
   const { explorerNavStack, push } = useExplorerContext({

packages/graphiql-react/src/explorer/components/section.tsx → packages/graphiql-plugin-doc-explorer/src/components/section.tsx

@@ -11,7 +11,7 @@ import {
   ImplementsIcon,
   RootTypeIcon,
   TypeIcon,
-} from '../../icons';
+} from '@graphiql/react';
 
 import './section.css';
 

packages/graphiql-react/src/explorer/components/type-documentation.tsx → packages/graphiql-plugin-doc-explorer/src/components/type-documentation.tsx

@@ -10,8 +10,7 @@ import {
 } from 'graphql';
 import { useState } from 'react';
 
-import { useSchemaContext } from '../../schema';
-import { Button, MarkdownContent } from '../../ui';
+import { useSchemaContext, Button, MarkdownContent } from '@graphiql/react';
 import { ExplorerFieldDef } from '../context';
 import { Argument } from './argument';
 import { DefaultValue } from './default-value';

packages/graphiql-react/src/explorer/context.tsx → packages/graphiql-plugin-doc-explorer/src/context.tsx

@@ -14,8 +14,11 @@ import {
   isUnionType,
 } from 'graphql';
 import { ReactNode, useEffect, useState } from 'react';
-import { useSchemaContext } from '../schema';
-import { createContextHook, createNullableContext } from '../utility/context';
+import {
+  useSchemaContext,
+  createContextHook,
+  createNullableContext,
+} from '@graphiql/react';
 
 export type ExplorerFieldDef =
   | GraphQLField<unknown, unknown>
@@ -72,7 +75,7 @@ type ExplorerContextProviderProps = {
 };
 
 export function ExplorerContextProvider(props: ExplorerContextProviderProps) {
-  const { schema, validationErrors } = useSchemaContext({
+  const { schema, validationErrors, schemaReference } = useSchemaContext({
     nonNull: true,
     caller: ExplorerContextProvider,
   });
@@ -81,15 +84,16 @@ export function ExplorerContextProvider(props: ExplorerContextProviderProps) {
     initialNavStackItem,
   ]);
 
-  const push = (item: ExplorerNavStackItem) => {
-    setNavStack(currentState => {
-      const lastItem = currentState.at(-1)!;
-      return lastItem.def === item.def
-        ? // Avoid pushing duplicate items
-          currentState
-        : [...currentState, item];
-    });
-  };
+  const push = // eslint-disable-line react-hooks/exhaustive-deps -- false positive, variable is optimized by react-compiler, no need to wrap with useCallback
+    (item: ExplorerNavStackItem) => {
+      setNavStack(currentState => {
+        const lastItem = currentState.at(-1)!;
+        return lastItem.def === item.def
+          ? // Avoid pushing duplicate items
+            currentState
+          : [...currentState, item];
+      });
+    };
 
   const pop = () => {
     setNavStack(currentState =>
@@ -105,6 +109,37 @@ export function ExplorerContextProvider(props: ExplorerContextProviderProps) {
     );
   };
 
+  useEffect(() => {
+    if (!schemaReference) {
+      return;
+    }
+    switch (schemaReference.kind) {
+      case 'Type': {
+        push({ name: schemaReference.type.name, def: schemaReference.type });
+        break;
+      }
+      case 'Field': {
+        push({ name: schemaReference.field.name, def: schemaReference.field });
+        break;
+      }
+      case 'Argument': {
+        if (schemaReference.field) {
+          push({
+            name: schemaReference.field.name,
+            def: schemaReference.field,
+          });
+        }
+        break;
+      }
+      case 'EnumValue': {
+        if (schemaReference.type) {
+          push({ name: schemaReference.type.name, def: schemaReference.type });
+        }
+        break;
+      }
+    }
+  }, [schemaReference, push]);
+
   useEffect(() => {
     // Whenever the schema changes, we must revalidate/replace the nav stack.
     if (schema == null || validationErrors.length > 0) {
@@ -169,10 +204,9 @@ export function ExplorerContextProvider(props: ExplorerContextProviderProps) {
               break;
             } else {
               // lastEntity must be a field (because it's not a named type)
-              const field: GraphQLField<any, any> = lastEntity;
+              const field: GraphQLField<unknown, unknown> = lastEntity;
               // Thus item.def must be an argument, so find the same named argument in the new schema
-              const arg = field.args.find(a => a.name === item.name);
-              if (arg) {
+              if (field.args.some(a => a.name === item.name)) {
                 newNavStack.push({
                   name: item.name,
                   def: field,

packages/graphiql-plugin-doc-explorer/src/index.tsx

@@ -0,0 +1,35 @@
+import {
+  DocsFilledIcon,
+  DocsIcon,
+  GraphiQLPlugin,
+  usePluginContext,
+} from '@graphiql/react';
+import { DocExplorer } from './components';
+
+export * from './components';
+
+export {
+  ExplorerContext,
+  ExplorerContextProvider,
+  useExplorerContext,
+} from './context';
+
+export type {
+  ExplorerContextType,
+  ExplorerFieldDef,
+  ExplorerNavStack,
+  ExplorerNavStackItem,
+} from './context';
+
+export const DOC_EXPLORER_PLUGIN: GraphiQLPlugin = {
+  title: 'Documentation Explorer',
+  icon: function Icon() {
+    const pluginContext = usePluginContext();
+    return pluginContext?.visiblePlugin === DOC_EXPLORER_PLUGIN ? (
+      <DocsFilledIcon />
+    ) : (
+      <DocsIcon />
+    );
+  },
+  content: DocExplorer,
+};

packages/graphiql-plugin-doc-explorer/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../graphiql-react/tsconfig.json"
+}