Visual operation builder

[jonathanawesome]

Now that GraphiQL v2 has had a well-received release, we should discuss re-aligning and rescheduling the bits that didn’t make it into v2. The two primary features that were discussed for v2 but didn’t make it in are the introduction of Monaco for the editors and implementing the new visual operation builder (also known as "the replacement for OneGraph Explorer"). The original Path to GraphiQL v2 issue is here, and the discussion around the design is here, for reference.

As some of you may be aware, I’ve been prototyping these features over the last few months. My experience with Monaco has been mostly around getting it running well across tabs and theming. I haven’t investigated the more complicated interactions around linking keywords in popovers/tooltips/overflow widgets to documentation, so I’m going to leave the Monaco integration discussion out of this thread and focus on the visual operation builder.

While my prototyping work has been solo, I have been soliciting feedback on my work from the community and also paying attention to the existing threads around the initial design proposal. Here is my summary of key points regarding the visual operation builder from the various sources (the Github discussion, Discord, and my own work) along with my proposed solutions.

---

Problem 1

Combining operation building and documentation-viewing inherently presents an overload of visual information. Operation building itself is incredibly complicated, and introducing a full-featured documentation experience only increases the visual noise.

Proposed solution

Provide a “Quick Docs” feature for the visual operation builder that assists a user in discovering specific information to assist them within the operation builder, but leaves a more fully-featured schema reference experience out. GraphiQL deserves a fully-featured schema reference and this can be accomplished with a new plugin infrastructure.

---

Problem 2

There are a number of critical but undesigned components/interactions in the design document. I’ve noted argument handling (input objects!), unions/fragments/inline fragments, deprecated fields, and field aliases…though I’m sure there are additional bits that need attention.

Proposed solution

I’ve explored argument handling, deprecated fields, and unions, but all of these bits need additional attention and consensus. I encourage all to explore the prototype I’ve been building to understand these needs.

---

Problem 3

Multiple operations within an operation editor.

• The status quo here is to allow multiple operations per tab and present a dropdown that asks the user to select which operation they want to run.
• Following executions via keyboard (ctrl + enter) run the first operation in the document.
• OneGraph Explorer provides a separate UI section for each operation in the document and additional UI bits specifically for adding new operations to the editor. This is pretty clunky, but GraphiQL didn't have tabs four years ago.

Proposed solution:

The spec describes that a request can only execute one operation but that multiple operations can be included in the document as long as they all have names (someone please bark at me here if I’m reading the spec incorrectly). While there are some GraphQL servers that allow and handle multiple operations per document, it’s out of spec and GraphiQL should provide hooks of some sort to the allow the functionality but warn about it by default. GraphiQL should warn, via UI, about the multiple-operations-problem and provide a way to split operations out into tabs.

---

Here’s the prototype that implements the above proposed solutions if you’d like to have a look. This prototype is changing rapidly and may not match with the above proposed solutions depending on when you're reading this...please join us on the Discord channel for the latest updates. It's purpose is to provoke discussion and provide a space for the exploration of ideas around the future of GraphiQL...please be courteous in your criticism.

Apologies for the wall of text (👆). Content/writing/markdown is not my specialty...if you've made it this far, I owe you a coffee/beer if you're ever in Austin, Texas.