Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Ideas for improving the Developer Experience and Feature Discoverability #10

Open
FluorescentHallucinogen opened this issue Mar 14, 2019 · 11 comments

Comments

Projects
None yet
2 participants
@FluorescentHallucinogen
Copy link

commented Mar 14, 2019

This issue acts as the central place for all discussions of ideas around improving the Developer Experience (DX), Feature Discoverability and UI design.

  1. It would be great to be able to insert all fields of type (check all nested checkboxes at once and then uncheck only unnecessary instead of check them only one by one). This is very useful for types with a large number of fields.

  2. If a field is 1) non-null AND 2) leaf (terminal / uncollapsible / has no child fields), it should be 1) checked AND 2) disabled (so the user could not uncheck it).

I've visualized these two ideas. Here's my vision (a slightly modified version of Explorer tab from Playground v2 concept):

after

Compare it with the original:

before

@FluorescentHallucinogen

This comment has been minimized.

Copy link
Author

commented Mar 14, 2019

@dwwoelfel @sgrove @rofrischmann PTAL. 😉

@FluorescentHallucinogen

This comment has been minimized.

Copy link
Author

commented Apr 2, 2019

Fixed some things:

explorer-fixed

@FluorescentHallucinogen

This comment has been minimized.

Copy link
Author

commented Apr 10, 2019

I've improved some things:

  • It would be great to visually separate the input fields (arguments) from the output (asked) fields by
  1. placing input fields into brackets
  2. using different colors for input and output fields
  • I've used the same colors for the same things in Explorer and Query editor (green for output fields, orange for input fields, etc.).

  • I've realized that "Insert all fields" feature should check nested checkboxes only for all output fields, not for input fileds.

  • If the input field (argument) is required (non-null), it must be 1) checked by default AND 2) disabled (so the user could not uncheck it) to avoid generating invalid query.

  • If the output field is 1) leaf (terminal / uncollapsible / has no child fields) AND 2) the only field of the (parent) type [see the count in the lastMonth on the attached image], it must be 1) checked by default AND 2) disabled (so the user could not uncheck it) to avoid the Field 'xxx' of type 'YYY' must have a sub selection error.

explorer-improved

@FluorescentHallucinogen

This comment has been minimized.

Copy link
Author

commented May 1, 2019

Added one small, but very useful thing — field descriptions on hover:

explorer-final

@FluorescentHallucinogen

This comment has been minimized.

Copy link
Author

commented May 10, 2019

Let me explain some important things about checkboxes and rotating triangles that may not be obvious.

  1. Rotating triangles indicate that a field has child fields. Leaf (terminal) fields has no rotating triangles. In the current implementation there is no visual difference between leaf (terminal) fields and not, the user can't predict what will happen when he clicks on the checkbox (will it expand child fields or just check it).

  2. Only clicking on the checkboxes checks all child fields (checkboxes):

1

Clicking on the rotating triangles and field names only expand child fields without checking (inserting) them:

2
3

This is because inserting all child fileds in GraphQL is, generally speaking, bad practice, and can't be the default behavior. The one of the main ideas of GraphQL is to solve the overfetching problem (when API return additional data that's not needed), it gives you the power to ask (show) for what data you need and get exactly that, nothing more and nothing less. Inserting all child fileds may help to overfetching (if the user doesn't care about removing unnecessary fields). But in some cases the inserting all child fileds feature improves the DX (developer experience), e.g. in the case of very complex (auto-generated) API that has large number of types and large number of fields in each type. In this case, it is faster to check all nested checkboxes at once and then uncheck only unnecessary instead of check them only one by one.

That's why inserting all child fileds should be here, but shouldn't be the default behavior.

@FluorescentHallucinogen FluorescentHallucinogen changed the title [UX] Improve autocompletion: insert all fields of type Ideas for improving the Developer Experience and Feature Discoverability May 10, 2019

@FluorescentHallucinogen

This comment has been minimized.

Copy link
Author

commented May 10, 2019

Here's the updated mockup based on the preview of the new Explorer version:

explorer-v2

Please note that I've added a button for adding fragments along with buttons for adding queries, mutations and subscriptions.

@FluorescentHallucinogen

This comment has been minimized.

Copy link
Author

commented May 11, 2019

Everything is clear with the addition of new queries/mutations/subscriptions/fragments, but what about the deletion?

I've added icons to clone (with all checked fields) and delete queries:

clone-delete-1

clone-delete-2

These icons are displayed when hovering over the query.

@FluorescentHallucinogen

This comment has been minimized.

Copy link
Author

commented May 12, 2019

Have added support for GraphQL aliases:

You can clone any node (with all child field) as GraphQL alias using the "Clone" icon that is displayed when hovering over the node:

aliases-1

You can remove any alias using the "Delete" icon:

aliases-2

You can rename and edit aliases in your own:

aliases-3

@FluorescentHallucinogen

This comment has been minimized.

Copy link
Author

commented May 12, 2019

The preview of the new Explorer version has one interesting feature — "Jump to definition" via Alt+Shift-click on the field in code editor. But, IMO, it has low feature discoverability. How users learn about this hotkeys?

What about a "View" icon that is displayed when hovering over the field in code editor to focus on this field in Explorer, and vice versa? 😉

focus-1
focus-2

@FluorescentHallucinogen

This comment has been minimized.

Copy link
Author

commented May 12, 2019

@JakeDawkins PTAL. What about something like that for Apollo GraphQL for VS Code extension?

@JakeDawkins

This comment has been minimized.

Copy link

commented May 13, 2019

@JakeDawkins PTAL. What about something like that for Apollo GraphQL for VS Code extension?

👋 Yeah! This is beautiful! I'd love to see something like this in the future. We have a bit of work to do in VS Code around stability and service federation before this could be prioritized, but I'll keep it in mind :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.