overhaul READMEs and add migratio guide for graphiql@2 (#2687)

* [redesign]: editor in new design (#2513) * add postcss config to allow nesting * avoid processing css from `@graphiql/react` with postcss * add css files for default fonts * add long description with markdown to dev schema * rewrite completion tooltip * move editor css to @graphiql/react * git mv editor components to `@graphiql/react` * adjust editor components after moving to `@graphiql/react` * move styles for auto-inserted leads * make dynamic padding more resilient and add explanatory comment * add extra color to avoid conflicts * colocate markdown and deprecation styles * add changesets * fix spell checking * add changeset for graphiql@2 * don't enter pre-release mode in changeset * more elaborate changeset message * [redesign] layout for editor components (#2515) * add icons to `@graphiql/react` * add `UnstyledButton` ui component * implement new design for editors layout * rename `Unstyled` to `UnStyled` for spell checking * remove unused class and whitespace in `className` * make tiny change for deploy preview 🤞 * this will do it, i think? Co-authored-by: Rikki Schulte <[email protected]> * set default background color for editors (#2528) * set default background colors via css variables (#2530) * move editor styles to `@graphiql/react` (#2532) * refresh editor after hiding (#2537) * add caller argument to editor hooks (#2538) * implement footer in new design (#2540) * [redesign] implement new toolbar design (#2524) * implement new toolbar design * add `caller` argument for better errors * [redesign] implement sidebar (#2543) * implement sidebar in new design * simplify callback * [redesign] implement new design for history plugin (#2571) * add icons * don't invoce callback when programmatically change resizable element * implement history in new design * visually separate favourite history items * add save button when editing history label * add changeset * add missing changesets in retrospect * fix typos * fix e2e tests * remove input outline * add prerelease versions * fix opening doc explorer when clicking references (#2578) * extract loading spinner to `@graphiql/react` (#2581) * [redesign] move docs components to `@graphiql/react` (#2582) * move explorer context into folder * move `TypeLink` component to `@graphiql/react` * move `FieldLink` component to `@graphiql/react` * move `DefaultValue` component to `@graphiql/react` * move `Directive` component to `@graphiql/react` * extract `MarkdownContent` component in `@gaphiql/react` * move `Argument` component to `@graphiql/react` * combine and extend changesets * add `Search` component to `@graphiql/react` (#2586) * move remaining doc explorer component to `@graphiql/react` (#2587) * [redesign] docs (#2588) * add icons * add `Button` component to `@graphiql/react` * add explorer section component * redesign `SchemaDocumentation` component * redesign `TypeDocumentation` component * redesign `FieldDocumentation` component * redesign `DocExplorer` component * extend changeset message * move tab components to `@graphiql/react` (#2591) * [redesign] implement new design for tabs (#2592) * implement new design for tabs * add back `tab` role * increment versions from release * [redesign] add settings dialog (#2595) * add `Dialog` component to `@graphiql/react` * add a `clear` method to the `Storage` type * add success and failure states to `Button` component * add settings dialog * make sure to show dialog above editor scrollbars * [redesign] add dark mode (#2596) * add `ButtonGroup` component to `@graphiql/react` * dark mode * add back styles for editor search (#2599) * add a dialog that shows all available shortkeys (#2601) * add a dialog that shows all available shortkeys * use table in short key dialog * add shortkey for introspection * add link to codemirror keymaps * make dropdown menu accessible (#2627) * fix doc explorer style regressions (#2630) * fix selector specificity for link styling * leverage nesting * fix hiding the headline on focus * ensure correct focus outlines and remove visited styles * increment next versions * adds styles to contain the result window above any footer content (#2621) * adds styles to contain the result window above any footer content * simplifies flex value * use hsl values and reduce number of CSS variables (#2637) * rename CSS variables for colors (#2641) * forward refs and props for UI components (#2628) * [redesign] implement toolbar menu and select in new design (#2631) * implement toolbar menu in new design * implement `ToolbarListbox` in new design * better tooltips * [v2] cleanup `GraphiQL` component (#2632) * remove deprecated class methods * remove utilities * remove ref forwarding * refactor inner class component to a function component * merge main component with context consumer component * remove component statics * refactor outer component to be a class component * remove comments * add changeset * remove legacy exports * [v2] add provider component and deduplicate prop type definitions (#2650) * add `GraphiQLProvider` to `@graphiql/react` and include `StorageContextProvider` * add `HistoryContextProvider` to `GraphiQLProvider` * add `EditorContextProvider` to `GraphiQLProvider` * add `SchemaContextProvider` to `GraphiQLProvider` * add `ExecutionContextProvider` to `GraphiQLProvider` * move `ExplorerContextProvider` to `GraphiQLProvider` * declare props for `GraphiQLInterface` * reuse prop definitions from editor components * merge props for default state of editor tools * rename prop for toggling headers editor * re-export GraphiQL provider * add documention for `@graphiql/react` (#2657) * add JSDocs for component props and hooks * add JSDocs for context types * add README for `@graphiql/react` * [v2] add plugin api for docs and history (#2674) * add plugin api for docs and history * throw error when plugin has no title * make popover styles look good in dark mode (#2682) * add example for `graphiql-explorer` (#2683) * don't pass `shouldPersistHeaders` to fetcher anymore (#2684) * bump preview versions * overhaul READMEs and add migratio guide for `graphiql@2` Co-authored-by: Rikki Schulte <[email protected]> Co-authored-by: Jonathan Brennan <[email protected]>
graphql · Aug 24, 2022 · 8cfb56d · 8cfb56d
1 parent 7371157
commit 8cfb56d
Show file tree

Hide file tree

Showing 7 changed files with 258 additions and 172 deletions.
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 # GraphQL IDE Monorepo
 
-> **Security Notice:** All versions of `graphiql` < `1.4.7` are vulnerable to an XSS attack in cases where the GraphQL server to which the GraphiQL web app connects is not trusted. Learn more [in the graphiql `security` docs directory](https://github.com/graphql/graphiql/blob/main/docs/security)
+> **Security Notice:** All versions of `graphiql` < `1.4.7` are vulnerable to an XSS attack in cases where the GraphQL server to which the GraphiQL web app connects is not trusted. Learn more [in the graphiql `security` docs directory](docs/security)
 
 > **Looking for the [GraphiQL Docs?](packages/graphiql/README.md)**: This is the root of the monorepo! The full GraphiQL docs are located at [`packages/graphiql`](packages/graphiql)
 
@@ -31,22 +31,8 @@ The purpose of this monorepo is to give the GraphQL Community:
 - an example of how to use this ecosystem with GraphiQL.
 - examples of how to implement or extend GraphiQL.
 
-### Latest Stable Ecosystem
-
-`[email protected]` and ecosystem are organized as below. Any further changes to `[email protected]` are made against `1.0.0` branch
-
-![Diagram of the current Monorepo and third party ecosystem](https://raw.githubusercontent.com/graphql/graphiql/main/resources/images/current-ecosystem.jpg)
-
-### Proposed Ecosystem
-
-As we re-write for `[email protected]` ecosystem, this monorepo will contain a sdk and plugins.
-
-![Diagram of the proposed Monorepo and third party ecosystem](https://raw.githubusercontent.com/graphql/graphiql/main/resources/images/proposed-ecosystem.jpg)
-
 ## [`graphiql`](packages/graphiql#readme)
 
-> **Breaking Changes & Improvements:** several interfaces are being dropped for new ones are arriving for GraphiQL 1.0.0! Read more in [this issue](https://github.com/graphql/graphiql/issues/1165)
-
 <!-- prettier-ignore -->
 > [![NPM](https://img.shields.io/npm/v/graphiql.svg)](https://npmjs.com/graphiql)
 > ![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/graphiql)
@@ -55,21 +41,14 @@ As we re-write for `[email protected]` ecosystem, this monorepo will contain a sdk an
 > ![npm bundle size (version)](https://img.shields.io/bundlephobia/min/graphiql/latest)
 > ![npm bundle size (version)](https://img.shields.io/bundlephobia/minzip/graphiql/latest)
 
-![Screenshot of GraphiQL with Doc Explorer Open](https://raw.githubusercontent.com/graphql/graphiql/main/packages/graphiql/resources/graphiql.jpg)
+![Screenshot of GraphiQL with Doc Explorer Open](packages/graphiql/resources/graphiql.jpg)
 
 _/ˈɡrafək(ə)l/_ A graphical interactive in-browser GraphQL IDE. [Try the live demo](http://graphql.org/swapi-graphql). We also have [a demo using our latest netlify build](http://graphiql-test.netlify.com) for the `main` branch.
 
 The GraphiQL IDE, implemented in React, currently using [GraphQL mode for CodeMirror](packages/codemirror-graphql#readme) & [GraphQL Language Service](packages/graphql-language-service#readme).
 
 **Learn more about [GraphiQL in `packages/graphiql/README.md`](packages/graphiql#readme)**
 
-### How To Setup/Implement GraphiQL
-
-[codesandbox.io graphiql example](https://codesandbox.io/s/graphiql-js-example-oc851)
-[stackblitz.com graphiql example](https://stackblitz.com/edit/react-ts-jpnmod)
-
-**The [GraphiQL Readme](packages/graphiql#readme) explains** some of the ways to implement GraphiQL, and we also have the [examples](examples) directory as well!
-
 ## [`monaco-graphql`](packages/monaco-graphql#readme)
 
 [![NPM](https://img.shields.io/npm/v/monaco-graphql.svg)](https://npmjs.com/monaco-graphql)

diff --git a/docs/migration/graphiql-2.0.0.md b/docs/migration/graphiql-2.0.0.md
@@ -0,0 +1,186 @@
+# Upgrading `graphiql` from `1.x` to `2.0.0`
+
+Hello GraphiQL user and thanks for upgrading!
+
+This migration guide walks you through all changes that come with `[email protected]`, in particular the breaking ones, and will show you how to upgrade your `1.x` implementation.
+
+> If you encounter any issues while upgrading that are not covered in here, please open an issue or PR on this repo and we will extend this guide.
+
+## Design refresh including dark theme
+
+Arguably the biggest change in `graphiql@2` is the new design of the UI. It has been reworked from scratch to look more modern while keeping its simplistic look and feel. We also finally added a built-in dark theme. Theme selection is based on system defaults and can be changed in the new settings dialog (available by clicking on the gear icon at the bottom of the sidebar on the left of the screen).
+
+Starting with `graphiql@2`, the only officially supported way of customizing the CSS that make up the looks of GraphiQL is by overriding the design tokens defined using CSS variables. In particular, changes to class names are no longer considered breaking changes. If you use class-name based selectors to change styles your overrides might break with minor or patch version bumps.
+
+A list of all CSS variables that can be customized can be found in the [`root.css`](../../packages/graphiql-react/src/style/root.css) file of the `@graphiql/react` package. The variables for colors use a list of values that can be passed into the [`hsl`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl) function in CSS that defines colors by hue, saturation and lightness.
+
+## Changes to `GraphiQL` component props
+
+A couple of props of the `GraphiQL` have undergone breaking changes:
+
+- The props `defaultVariableEditorOpen` and `defaultSecondaryEditorOpen` have been merged into one prop `defaultEditorToolsVisibility`. The default behavior if this prop is not passed is that the editor tools are shown if at least one of the secondary editors has contents. You can pass the following values to the prop:
+  - Passing `false` hides the editor tools.
+  - Passing `true` shows the editor tools.
+  - Passing `"variables"` explicitly shows the variables editor.
+  - Passing `"headers"` explicitly shows the headers editor.
+- The props `docExplorerOpen`, `onToggleDocs` and `onToggleHistory` have been removed. They are replaced by the more generic props `visiblePlugin` (for controlling which plugin is visible) and `onTogglePluginVisibility` (which is called each time the visibility of any plugin changes).
+- The `headerEditorEnabled` prop has been renamed to `isHeadersEditorEnabled`.
+- The `ResultsTooltip` prop has been renamed to `responseTooltip`.
+
+### Tabs enabled by default
+
+Tabs were supported opt-in starting with `@[email protected]`. With `graphiql@2` tabs are now always enabled. The `tabs` prop (which previously toggled if tabs were enabled or not) has therefore been replaced with a prop `onTabChange`. If you used the `tabs` prop before to pass this function you can change your implementation like so:
+
+```diff
+<GraphiQL
+-  tabs={{ onTabChange: (tabState) => {/* do something */} }}
++  onTabChange={(tabState) => {/* do something */}}
+/>
+```
+
+As long as only one session is open, the tab bar above the editors is hidden. A plus icon next to the logo on the top right allows the user to open more tabs. With at least two tabs opened, the tab bar appears above the editors.
+
+## Removed package exports
+
+All React components apart from the `GraphiQL` component have been moved to the `@graphiql/react` package. That's why we removed most of the exports with `graphiql@2`. Here is a list of all exported components and functions that have been removed and where you can find them now:
+
+- `QueryEditor`, `VariableEditor` and `DocExplorer`: Now exported from `@graphiql/react` under the same names
+  - Note that the `schema` prop of the `DocExplorer` no longer exists, the component now uses the schema provided by the `ExplorerContext`.
+- `ToolbarMenu`: Now exported from `@graphiql/react` as `ToolbarMenu`
+- `ToolbarMenuItem`: Now exported from `@graphiql/react` as `ToolbarMenu.Item`
+- `ToolbarSelect`: Now exported from `@graphiql/react` as `ToolbarListbox`
+- `ToolbarSelectOption`: Now exported from `@graphiql/react` as `ToolbarListbox.Option`
+- `onHasCompletion`: This function is only meant to be used internally, it is no longer being exported
+- `fillLeafs`, `getSelectedOperationName` and `mergeAst`: Now exported from `@graphiql/toolkit` under the same names
+- types `Fetcher`, `FetcherOpts`, `FetcherParams`, `FetcherResult`, `FetcherReturnType`, `Observable`, `Storage` and `SyncFetcherResult`: Exported from `@graphiql/toolkit` under the same names (previously just re-exported by `graphiql`)
+
+## `GraphiQL` is now a function component
+
+The `GraphiQL` component in `[email protected]` was a class component. That allowed easy access to its props, state and methods by attaching a ref to it like so:
+
+```jsx
+import { createGraphiQLFetcher } from '@graphiql/toolkit';
+import { GraphiQL } from 'graphiql';
+import React from 'react';
+
+const fetcher = createGraphiQLFetcher({ url: 'https://my.endpoint' });
+
+class MyComponent extends React.Component {
+  _graphiql: GraphiQL;
+
+  componentDidMount() {
+    const query = this._graphiql.getQueryEditor().getValue();
+  }
+
+  render() {
+    return <GraphiQL ref={r => (this._graphiql = r)} fetcher={fetcher} />;
+  }
+}
+```
+
+With `graphiql@2` we refactored the codebase to more "modern" React. This also meant replacing all class components with function components. The code above no longer works in `graphiql@2` as attaching refs to function components is not possible in React.
+
+All logic and state management now lives in multiple React contexts, provided by the `@graphiql/react` package. The `GraphiQL` component is now basically combining two other components, both of which are also exported by the package.
+
+- `GraphiQLProvider` (originally coming from `@graphiql/react`) will render all context providers and takes care of state management
+- `GraphiQLInterface` is defined in the `graphiql` package and renders the UI
+
+If you want to read or modify GraphiQL state from your custom implementation you need to render both the above components separately as the hooks for consuming the context values only work in components that are rendered inside the provider component.
+
+With all that, the example above can be refactored a such:
+
+```jsx
+import { useEditorContext } from '@graphiql/react';
+import { createGraphiQLFetcher } from '@graphiql/toolkit';
+import { GraphiQLInterface, GraphiQLProvider } from 'graphiql';
+import { useEffect } from 'react';
+
+const fetcher = createGraphiQLFetcher({ url: 'https://my.endpoint' });
+
+function MyComponent() {
+  return (
+    <GraphiQLProvider fetcher={fetcher}>
+      <InsideContext />
+    </GraphiQLProvider>
+  );
+}
+
+function InsideContext() {
+  // Calling this hook would not work in `MyComponent` (it would return `null`)
+  const { queryEditor } = useEditorContext();
+
+  useEffect(() => {
+    const query = queryEditor.getValue();
+  }, []);
+
+  return <GraphiQLInterface />;
+}
+```
+
+Here is a list of all public class methods that existed in `graphiql@1` and its replacement in `graphiql@2`. All the contexts mentioned below can be accessed using a hook exported by `@graphiql/react`.
+
+- `getQueryEditor`: Use the `queryEditor` property from the `EditorContext`.
+- `getVariableEditor`: Use the `variableEditor` property from the `EditorContext`.
+- `getHeaderEditor`: Use the `headerEditor` property from the `EditorContext`.
+- `refresh`: Calling this method should no longer be necessary, all editors will refresh automatically after resizing. If you really need to refresh manually you have to call the `refresh` method on all editor instances individually.
+- `autoCompleteLeafs`: Use the `useAutoCompleteLeafs` hook provided by `@graphiql/react` that returns this function.
+
+There are a couple more class methods that were intended to be private and were already removed starting in `[email protected]`. Since they were not actually marked with `private`, here's an extension to the above list for these methods:
+
+- `handleClickReference`: This was a callback method triggered when clicking on a type or field. It would open the doc explorer for the clicked reference. If you want to manually mimic this behavior you can use the `push` method from the `ExplorerContext` to add an item to the navigation stack of the doc explorer, and you can use the `setVisiblePlugin` method of the `PluginContext` to show the doc explorer plugin (by passing the `DOC_EXPLORER_PLUGIN` object provided by `@graphiql/react`).
+- `handleRunQuery`: To execute a query, use the `run` method of the `ExecutionContext`. If you want to explicitly set an operation name, call the `setOperationName` method of the `EditorContext` provider before that (passing in the operation name string as argument).
+- `handleEditorRunQuery`: Use the `run` method of the `ExecutionContext`.
+- `handleStopQuery`: Use the `stop` method from the `ExecutionContext`.
+- `handlePrettifyQuery`: Use the `usePrettifyQuery` hook provided by `@graphiql/react` that returns this function.
+- `handleMergeQuery`: Use the `useMergeQuery` hook provided by `@graphiql/react` that returns this function.
+- `handleCopyQuery`: Use the `useCopyQuery` hook provided by `@graphiql/react` that returns this function.
+- `handleToggleDocs` and `handleToggleHistory`: Use the `setVisiblePlugin` method of the `PluginContext`.
+
+Some class methods were callbacks to modify state which are not intended to be called manually. All these methods don't have a successor: `handleEditQuery`, `handleEditVariables`, `handleEditHeaders`, `handleEditOperationName`, `handleSelectHistoryQuery`, `handleResetResize` and `handleHintInformationRender`
+
+### Static properties have been removed
+
+In `[email protected]` the `GraphiQL` component included a bunch of static properties that exposed utility functions and other components. Most of these have been removed in `graphiql@2` since the components and functions have been moved to the `@graphiql/react` and `@graphiql/toolkit` packages.
+
+The properties that remain on the `GraphiQL` function component are `GraphiQL.Logo`, `GraphiQL.Toolbar` and `GraphiQL.Footer`. All three are React components that can be passed as children to the `GraphiQL` components and override certain parts of the UI:
+
+- `GraphiQL.Logo`: Overrides the "logo" at the top right of the screen. By default it contains the text "Graph*i*QL".
+- `GraphiQL.Toolbar`: Overrides the toolbar next to the query editor. By default if contains buttons for prettifying the current editor contents, merging fragment definitions into the operation definition and copying the contents of the query editor to the clipboard. Note that the default buttons will not be shown when passing this component as child to `GraphiQL`, instead it will show the children you pass to `GraphiQL.Toolbar`. The execute button will always be shown. If you want to keep the default buttons and add additional buttons you can use the `toolbar` prop.
+- `GraphiQL.Footer`: Adds a section below the response editor. By default this won't show up in the UI.
+
+Here is a list of all the static properties that have been removed and their replacements:
+
+- `GraphiQL.formatResult` and `GraphiQL.formatError`: Replaced by equally named functions from `@graphiql/toolkit`
+- `GraphiQL.QueryEditor`, `GraphiQL.VariableEditor` and `GraphiQL.HeaderEditor`: Replaced by equally named components from `@graphiql/react`
+- `GraphiQL.ResultViewer`: Replaced by the `ResponseEditor` component from `@graphiql/react`
+- `GraphiQL.Button`: Replaced by the `ToolbarButton` component from `@graphiql/react`
+- `GraphiQL.ToolbarButton`: This exposed the same component as `GraphiQL.Button`.
+- `GraphiQL.Menu`: Replaced by the `ToolbarMenu` component from `@graphiql/react`
+- `GraphiQL.MenuItem`: Replaced by the `ToolbarMenu.Item` component from `@graphiql/react`
+- `GraphiQL.Group`: Grouping multiple buttons side-by-side is not provided out-of-the box anymore in the new GraphiQL UI. If you want to implement a similar feature in the new vertical toolbar you can do so by adding your own styles for your custom toolbar elements. Example:
+
+  ```jsx
+  import { createGraphiQLFetcher } from '@graphiql/toolkit';
+  import { GraphiQL } from 'graphiql';
+
+  const fetcher = createGraphiQLFetcher({ url: 'https://my.endpoint' });
+
+  function MyComponent() {
+    return (
+      <GraphiQL fetcher={fetcher}>
+        <GraphiQL.Toolbar>
+          {/* Add custom styles for your buttons using the given class */}
+          <div className="button-group">
+            <button>1</button>
+            <button>2</button>
+            <button>3</button>
+          </div>
+        </GraphiQL.Toolbar>
+      </GraphiQL>
+    );
+  }
+  ```
+
+### `window.g` has been removed
+
+In `[email protected]` the `GraphiQL` class component stored a reference to itself on a global property named `g`. This property has been removed as refs don't exist for function components. (Also, the property was only intended for internal use like testing in the first place.)