Discussion: Re-design for Plugins

[orta]

👋 - Here's a general direction for where we can take the GraphiQL. It takes design cues from Storybook JS and VSCode. It aims to have quite a few UI chrome entry points for plugins to be able to work from. This ranges from adding a sidebar button which can either control a sidebar or the whole UI, to toolbar items and tabs on request/reponse.

This is roughly how I see each section:

Notes

• This top bar (current query description) is questioned every time I show the design. Its goal is to provide scanability and to give an official "title" to every query. The title is basically either the name of the query + up to 3 vars. If there's no name, we try infer it from the root query/mutation fields. This has 2 main advantages: when you have many tabs with you can know what the page is, when we show summaries of tabs there is a consistent naming.

• I've built out a consistent way to show the different types in GraphQL:

• I've tried to always use one highlight colour which is used in different shades: which means that can be customized by a consumer. Artsy might have used the purple from it's logo. The default value is the turquoise colour from the GrpahQL logo.

• Docs currently lives in the sidebar, as a sub navigation which is pushed on top of whatever is on the left, in a similar stack metaphor to how iOS does navigation. There's a back button and that pops the stack. I'm open to this changing, it can cover useful UI by doing this. The trade-off is that there needs to be a special section just for introspection of the code

• Things missing from design spec:

  • Run button
  • Sure button
  • Error tab?
  • Explorer style query generation

• Things I'm not sold on and can change:

  • The sidebar reference to a query, feels like it needs to be tighter somehow

Example plugins

Ideally most of the chrome in GraphiQL comes from the plugin infra, that means we can be sure to build a scalable plugin API which works with massive schemas.

Schema

The default sidebar tab: provides an entry point into your schema and allows for deeper introspection of your current query. It probably doesn't need to interact with requests or responses. It provides a way to dig into the documentation of the schema.

History

It would listen to every request made, check to see if it was different from the last one and keep track of the diffs. It would add a toolbar item, which when clicked showed a list of the requests and you can click to set the query string to be one you hit in the past

Stored Queries

It can add a tab to the request toolbar to save queries, as well as having a consistent way to access queries at runtime.

For example Artsy keeps all its stored queries in a JSON file, so the configuration for this plugin could have a function to index or search these queries. The same could be done against the Apollo server automatic persisted queries

Playground

Provides a toolbar icon to the requests section of graphiql which shows a tab which lets you eval JavaScript against the response. Extra kudos points if that has type completion for that JSON ;)

---

Sketch file

[domyen]

Awesome work @orta! I support the general direction so will limit my feedback to design for now:

Icons
Icons for technical products can sometimes be tough to understand because they boil down an abstraction to a 14x14 symbol. I wonder if a simpler shape with the first letter inside might be simpler to comprehend at a glance.

Layout
I think there's a visual disconnect between the query panel and the response panel. If they were conjoined (e.g., remove the margin between them) it might make the relationship between them clearer. Same for the query title header and the query/response panel.

Run button It's pretty useful for new users that might be unfamiliar with the UI. I used it in the past and still do.

[orta]

I love this feedback ❤️ - will give that a look

[acao]

I love the idea of adding tabs to each of the three default panes. we will need to make it so that the default tab is overrideable. do you remember my idea of a diagnostics/console area that slides up from the bottom? similar to vscode or codesandbox? gives a nice birds eye view when you're linting large queries, etc. might be nice for things like response headers, though we can just make that a secondary tab on the right pane.

Also for that legend, i like the icons, and the look and feel is close to the official look and feel which is great. For the legend labels, we need to use spec language - for example i think primitive is scalar?

Plugin notes: The side icon bar and panel region will itself be provided via a plugin. Also, I'd like to encapsulate the default layout in a simple layout component that doesn't need to pass any props, because some people want to override the default three pane layout, or we can just encourage them to compose the existing components however they want. We need to make this capability first order, in documentation/etc because it's where a lot of people get stuck very quickly.

[benjie]

This looks incredible, @orta; thanks for sharing your progress!

Here's a couple of questions/notes I have that I couldn't see the answers to in your designs:

One of the popular things in GraphQL Playground was the ability to browse through the docs and keep the previous layer and a bit open for context - effectively keeping a couple of the previous states of the navigation stack that you mention visible. I think we would like to enable this via a plugin; how do you see that fitting into the design?

Another thing that's commonly requested is a header and URL editor. I'm not sure if this would comfortably fit in the sidebar due to lack of width (URL bar especially). Maybe we could address this with plugin hooks to the "Current Query Description" area; I'm thinking a plugin could do something like adding an icon to the left/right that would open a header editing popover/modal. I'm not sure what this means for usage on mobile though. And perhaps that popover/modal should be baked into GraphiQL for all plugins to use rather than having each reinvent the wheel?

How do you see this mapping to mobile? Storybook is surprisingly good on mobile I discovered a few days ago, so perhaps we could take some inspiration from there.

Just want to say again - absolutely incredible work! 🙌

[acao]

the notes about the navigation trail are critical, agreed thanks @benjie

im thinking the query region itself could have a network tab plugin and thus the url, verb, headers, etc. Or the tab would be on the left. Not sure if its something that needs to change per request, or at least not without toggling the view? but if you are using http against multiple hosts it would be convenient. also keep in mind, much of this might be driven by graphql config with the new default implementation approach. Other plugin implementations would want a dropdown or autocomplete for the graphql endpoints. At my work we have dropdown choices that are used to construct the URL graphiql uses. Either way, a plugin will be providing all of this so we can ship a default plugin for this, but other implementations might not even have a need for a URL. so i think at the core we should refrain from providing anything http fixated, or that assumes that the graphql interface will utilize URIs even. for example our original demo executes client side, not against a url. I know i had the url in both of my react and vanilla examples, but i was just trying to be flexible around the http base case. our default will probably be set up for http and URIs, but the core should be a little more open ended.

[orta]

There's some great explorer ideas here: OneGraph/graphiql-explorer#10

[dwwoelfel]

There's some great explorer ideas here: OneGraph/graphiql-explorer#10

The explorer seems like it would fit really well as a plugin in the leftmost column. I think we've implemented most of the feedback from that issue.

We also have a code exporter plugin that would fit well in the rightmost column.

[acao]

Definitely something we’re planning on!

…

On Thu, Oct 24, 2019 at 12:27 PM Daniel Woelfel ***@***.***> wrote: There's some great explorer ideas here: OneGraph/graphiql-explorer#10 <OneGraph/graphiql-explorer#10> The explorer seems like it would fit really well as a plugin in the leftmost column. We also have a code exporter plugin <https://github.com/OneGraph/graphiql-code-exporter> that would fit well in the rightmost column. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <https://github.com/graphql/graphiql/issues/978?email_source=notifications&email_token=AAKOFFZK3G3B5CUE2CQ4KHDQQHEIHA5CNFSM4I6T4TKKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOECFUG4A#issuecomment-545997680>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKOFFYB3CIXSDDM7JAKWDLQQHEIHANCNFSM4I6T4TKA> .

[orta]

Do peeps have opinions on these sort of type signifiers?

[acao]

There's some great explorer ideas here: OneGraph/graphiql-explorer#10

The explorer seems like it would fit really well as a plugin in the leftmost column. I think we've implemented most of the feedback from that issue.

We also have a code exporter plugin that would fit well in the rightmost column.

I plan on introducing this pretty early on actually. I'd like to make the doc explorer, prettier, query histories into plugins, and a network tab before 1.0.0 as ways of defining what the initial plugin interface should be, as I propose in the roadmap. The idea is to abstract CM and monaco details well enough that, for example, useGraphiqlCommand() or GraphiQL.addCommand() will ideally translate over from extraKeys to monaco editor.addCommand() experience for 1.0.0. So graphql explorer will fit pretty naturally into that plugin framework, and should be able to integrate itself in this way whilst we are still using codemirror and are on a 0.17.x+ release.

[acao]

Do peeps have opinions on these sort of type signifiers?

I feel like the middle ones with the square border box are easier to identify than the ones on the right without a square, but there could be a11y issues I'm not aware of. Thanks for digging in on this today @orta! Happy Birthday!

[orta]

I'm going to make dark-mode request comment as off-topic, there is plans to support theming and dark mode is effectively a theme

[Chhekur]

1. We can actually provide a feature to preview the response in the form of tree like structure for better visualization.
2. We can actually provide a visual programming tool for writing queries, so that user won't actually have to remember the query attributes

[acao]

https://github.com/graphql/graphiql/blob/master/working-group/agendas/2020-03-10.md

heres the agenda for the working group tomorrow! we will be discussing this and other topics please open a pr to add yourself to the agenda!

[alinauroz]

We can add tabs option to Graphiql. This will help help a lot. When we have to switch between different queries multiple times, it becomes a little complicated to use history or commenting. I did a little changes in @orta 's proposed UI.

[acao]

thanks for that! @orta has a design that includes tabs somewhere, and we are working towards tabs support

[alinauroz]

• We can actually provide a feature to preview the response in the form of tree like structure for better visualization.
• We can actually provide a visual programming tool for writing queries, so that user won't actually have to remember the query attributes

@Chhekur dont you think treeview structure is already implemented. Look this image

But i think it would be a better approach if we move expand/collapse button with the nodes. But we have to make this feature optional for users through plugins or extensions

I have a code that implements a relatively better treeview. Im looking for a container to view it. Graphiql is using CodeMirror to show response and we cant render html in CodeMirror.
I will make a pr soon

[acao]

since we are moving to our new monaco-graphql, we will need to implement a code folding capability there that we can provide via a plugin

[acao]

graphql explorer plugin is a great “visual programming tool”. @Chhekur may be referring to a tree view using nodes/edges for json results? we will be providing plugins for handling different result formats , such as json, mdx, xml or yaml (all have been requested), and tabs for displaying reaults visually. any such proposal we can come up with sounds great.

working on the plugin proposal template today!

[Chhekur]

graphql explorer plugin is a great “visual programming tool”. @Chhekur may be referring to a tree view using nodes/edges for json results? we will be providing plugins for handling different result formats , such as json, mdx, xml or yaml (all have been requested), and tabs for displaying reaults visually. any such proposal we can come up with sounds great.

working on the plugin proposal template today!

Yes I was talking about representation of data in the form of node/edges, it'll be very easy to understand for user

[acao]

Who wants to take @orta's sketch or figma files and expand on them?

Also, a dark mode theme would be great!

[timsuchanek]

Hey folks, there are many great ideas in here!
In the last GraphiQL WG meeting in January, I offered to work on the new design together with @julianbauer, who actually designed the GraphQL Playground. For people who don't know, I implemented the GraphQL Playground back in the days.

After the WG meeting in January, @orta , @acao, @julianbauer and I had a call about the design and where it should go.
We mostly aligned around the goals: Keep it simple initially, but extensible as well, to cater to all the awesome plugin ideas that folks have. Then later we can add more stuff (like tabs or all kind of fancy features)

I'd like to present you our GraphiQL 2 design proposal and would love to get your thoughts on this!
Here is the new design.

As it can be a bit complex and needs some explanations of the thoughts we had in the design process, here's a video we recorded to walk you through: https://grain.co/share/story/0546c630-bb5d-4f83-acd6-5688c20cabe8/cGpVhVJt786DedMVrOrfvY0dktFdcmVldC8UkkmI

Besides introducing a fresher, more modern look, we are suggesting a major change, which we believe could significantly improve the developer experience:
Moving Docs and Docs explorer into one. You might know the docs explorer that onegraph pioneered. We believe, that the docs and the explorer, which allows you to construct queries, can be one. This is probably the most ambitious and potentially controversial topic - especially here we'd love to get your thoughts.

Looking forward to your feedback!

[Chhekur]

New designs look really awesome, just a couple of suggestions.

• can we add a button to quickly expand the editor and result window to full screen like just clicking on a button to make the editor full screen instead of dragging the whole way around?
• can we add an option to save the queries and group them into workspaces?

[acao]

The latter option is something we've been planning on for a long time!

Currently, the query history in graphiql@1 just saves every unique query you execute in one collection

[Ambro17]

Are graphql types still visible with this new docs and explorer Merge?
Clickable types that went to definition were really useful and I'm not sure if that feature would remain with this design

[acao]

@Ambro17 agreed!

[timsuchanek]

Thanks everyone for the feedback!

this is looking great! One last thing - we need to add a toggle for the query editor so users can switch between provided modes - graphiql explorer, AST explorer, even some visual exploration tools that have been developed. perhaps just a flyout menu that lets you pick from different displays, rather than more tabs

@acao I'll talk with Julian how we want to make that happen / how we'd want to use the existing icons here on the right side of the query editor.

This look awesome, really love the design here. I'm just not sure about the "Selected only" switch position (maybe it could be under the search input, making it always visible if the sidebar is and the explorer a bit narrower by default too?)

Great feedback @zoontek - we'll play around with that. We also weren't too sure about its location.

For the tooltips - @orta I guess we could at least overwrite some CSS there? Might then have to adjust the design more to Monaco's layout then.

• can we add a button to quickly expand the editor and result window to full screen like just clicking on a button to make the editor full screen instead of dragging the whole way around?

Great idea @Chhekur, we'll look into that.

• can we add an option to save the queries and group them into workspaces?

Also sounds like an interesting idea - sounds like a more advanced version of the history. We'll look into that. For the initial GraphiQL minimal scope we'd probably keep such an IDE feature out, just to be able to ship it.

Clickable types that went to definition were really useful and I'm not sure if that feature would remain with this design
Yes, @Ambro17, types will absolutely be clickable in all areas of the GraphiQL. For that we have designed the detail type view.

Everyone - let's move the discussion over here: #2216
So we have more space for all the threads and replies.