docs: layer model interactive component

[gillkyle]

Description

In an effort to explain the GraphQL docs better I drew up what I thought would explain some of the "layers of Gatsby" as I thought of them. These are pretty simplified but generally express what happens in Gatsby in an order that shows data going all the way from a source to being consumed in a component.

I did some hacking to make the Content layer have the data be able to cycle through different data sources that all have the same simple content to express that data can come from anywhere and all ends up looking the same in the GraphQL layer.

I petitioned @fk for some design critiquing and used his input to clean up the design to make it less busy.

Added the component to a handful of guides in the Conceptual section where I think it could do the most help expressing what's happening at different places.

Happy to hear any suggestions on how to improve content of each section, design, or whatever it may be.

Related Issues

Related to #15616 about adding more visual aids to docs (though this is about GraphQL, not themes like that issue mentionos)

This came about while working on the GraphQL workflow in #16981, trying to explain these concepts better

[LekoArts]

I did some hacking to make the Content layer have the data be able to cycle through different data sources that all have the same simple content to express that data can come from anywhere and all ends up looking the same in the GraphQL layer.

It took me some time to get what "cycle" actually means in the context, so I'd propose to make the label more descriptive (e.g. "Cycle data source"). Longer text will impact your design, but I think this makes it more clear.

---

Love the general idea and execution, well done!

[gillkyle]

Thanks for the review @LekoArts, I updated the button to say "cycle source" which I think would suffice 👍

[KyleAMathews]

Nifty! Looks great

[DSchau]

Looks great! Left a number of (non-blocking) comments!

[marcysutton]

This is amazing! Thanks so much for working on it. And great job making it accessible! I think this will help a lot of Gatsby learners to get a mental model of how it works. Way to take the initiative 🌮

[marcysutton]

In testing this some more, it's working well with the arrow keys, and with Voiceover and NVDA!

To make the tabs work as a single tab stop though, they need to have what's called roving tabindex, where only one of the tabs is focusable at a time but the arrow keys cycles through them. It would also help solve the issue where if the middle tab is selected by default, tabbing through the page won't put you on the first (inactive) tab. The goal is so that users don't have to tab through all the tabs to get to focusable items in the active tab panel content.

[gillkyle]

Thanks @marcysutton! Awesome feedback! I'll fix that up now!

[muescha]

is there any chance to make this component more generic?

For example:

Cards for the upper big icons row

<cards default=“data” layout=“top-icon”>
  <card name=“data” icon=“data-icon” title=“Data Layer”>
    {children}
   </card>
   <card name=“Source” icon=“Source-icon” title=“Sourcing”>
    {children}
   </card>
</cards>

Tabs for the small code snippets

<tabs default=“Js” layout=“tabs-icon-and-text”>
  <tab name=“Js” icon=“data-icon” title=“Data Layer”>
    {children}
   </tab>
   <tab name=“gql” icon=“gql-icon” title=“GraphQL”>
    {children}
   </tab>
</tabs>

Maybe we can combine the cards and tabs and only differnicate by a laout:

The hole is:

• a Big Icons on top layout.
• Content below

The code snippes:

• small icons (for tech symbols depending on language) and a title
• content below

Benefits:

• reusable. I dreaming all time of a language toggle tab layout to display yarn commands instead of the npm (selected language is stored)
• content stays only in doc document and is available for translation team

[muescha]

As a fast Google search: there also react compontens in the wild, but I don't know how well the fit: all under the keyword:

React content tabs

[gillkyle]

@muescha I wasn't sure it was worth the effort of making it more generic at this point because I couldn't think of many more use cases. Having an npm/yarn toggle could be similar but might have different requirements and could probably happen in a PR for something more specific like that.

[muescha]

Reusable is one side effect

But i18n is on the way - and for this all text should stay in /docs/

gatsbyjs/rfcs#42

[jonniebigodes]

@gillkyle awesome job. i've gone over it and it looks awesome.

@muescha if by more generic you mean abstracting it to allow the content/text of the component to be translated to someone that visits the page. I think it's best to leave it as is for now until we a solid foundation in the translation effort. A mid future goal should be have a good portion of the documentation already translated in some languages. A more end goal would components like this one that was created and possibly others.

[muescha]

Generic i mean that all the localized content is in doc. Presentation is in the component

Like my draft code example: {children} is any content from the mdx doc page

[marcysutton]

@muescha perhaps that could be discussed later for a future enhancement? I'd prefer to keep the scope of this limited so we can move it forward.

[marcysutton]

This is awesome. Nice work, @gillkyle! Thanks for incorporating the feedback 🌻

[alexlobera]

@gillkyle I think this visual representation is a big step to illustrate the process, it's helped me understand the puzzle much better. Although it's very helpful, I got a bit confused with the "build" concept. I see in the text that "build" refers to the process itself and it's also used in one of the tabs as a step in the process as well. It also confuses me a bit to use the GraphQL logo in the tab that displays a JSON and not on the previous one where the GraphQL query is.

What I understood from the examples is that during the build process the "content" is "queried" to get "data" for the "view" to be rendered in the "app", meaning:

Sorry for the late feedback :)

[muescha]

mhh also i miss there a "import data" build step where it is said that data is fetched imported into the gatsby data warehouse in graphql. it says only "can be connected to Gatsby" but not exactly where the data is stored.

i see it is in the build step. but in wrong order.

expect there a more detailed description in this order for build:

• fetch data from all sources and import to GraphQL schema
• transform data to enhance data, optimize images
• compile application
• query data from GraphQL and inject into templates
• then at least optimization, code splitting etc.

[gillkyle]

@alexlbr this is great feedback!

I think in order to resolve that confusion maybe the right move would be to move the information in the build step (those 2 paragraphs on the right in what is currently the build layer) into the initial content step and explain that at that point the content gets pulled from different places and a schema is made all during Gatsby's processing.

I like the idea of moving that up, I wonder if anyone else from @gatsbyjs/learning has any thoughts?

@muescha I think for clarity the build step could be reworded, though if changes are made to resolve what @alexlbr found confusing perhaps that would fix that anyway. I didn't include really granular details about the build on purpose because this is a pretty conceptual thing, though I'm happy to hear how you'd reword it!

[muescha]

@gillkyle 👍

yes you are right, too much granular would be not good. my thing was just an expectation and can be reworded be more short, like the suggested changes in your answer to @alexlbr