search

asyncapi / shape-up-process

This repo contains pitches and the current cycle bets. More info about the Shape Up process: https://basecamp.com/shapeup
https://shapeup.asyncapi.io
11 stars 8 forks source link

Unify HTML template and React component #83

Closed fmvilas closed 3 years ago

fmvilas commented 3 years ago

On This Page

Summary

Problem Overview

We're currently maintaining two HTML documentation views: the HTML template and the React component.

Solution Overview

Improve the React component so it matches the features and look & feel of the HTML template. Once it's done, make the HTML template use the React component to generate the HTML output.

Positive Side-Effects

  1. Less code to maintain.
  2. Studio is using React so we should be able to render the docs on the client-side. That will allow us to get rid of the expensive servers we have for the Playground right now and host it for free on Netlify or similar.

Solution guidelines

While this task may sound easy, there are a bunch of small features/details that are not present in the React component:

  1. It doesn't offer sidebar navigation.
  2. It's using tables to show information. We already saw in the initial versions of the HTML template that it doesn't scale well as usually most of the fields appear empty.
  3. It has a section of messages and schemas but it only shows the ones under components.
  4. It's not using Tailwind.
  5. It's merging objects when it finds allOf, which is incorrect behavior.
  6. It's not handling additionalItems.
  7. It's not rendering correlationId asyncapi/html-template@d77c1c6
  8. It's not rendering info that schema is Circular.
  9. It cannot properly render type for combined schema anyOf, allOf, or anyOf.

We should make sure these features are present in the React component. Otherwise, people will be losing features with the switch from the HTML template to React.

When it comes to making the HTML template render the React component, my suggestion is that we have a look at the following ReactDOMServer and ReactDOM methods:

I found this article very helpful: https://dev.to/marvelouswololo/how-to-server-side-render-react-hydrate-it-on-the-client-and-combine-client-and-server-routes-1a3p

One possible solution here is to make the HTML template an empty template with a generate:after hook where we do all the rendering process.

Boundaries

Don’t go too far refactoring the React component

Don't worry about the architecture of the React component. We'll dedicate time to converting it to a UI library in the next cycles.

Don't support theming

Let's forget about the theme feature of the component for now. It will only have a single "theme" and it's the one matching the styles of the HTML template. We'll add support for themes on the future UI library instead.

Watch out for those little details

Those that may be present on the HTML template but not on the React component.

Watch out for template parameters

The HTML template supports some parameters like singleFile, baseHref, version, sidebarOrganization, and others. We should make sure they still work.

Long-Term Vision

The idea is to start moving towards a single source of truth for our UI components. This is just the first step before we start working on the UI library which will offer many components instead of just a single big one.

In the near future, we'll also have our own design system for those who want to create custom AsyncAPI components that still match our look & feel.

magicmatatjahu commented 3 years ago

@fmvilas Great description for bet!

It's using the term "topics" instead of "channels".

I make search for topics in React component repo and I only found two occurrences but only related to TS typings, while in the rendered part I did not find any topics occurrence.

It's not working with AsyncAPI 2.0.0 (or I can't make it work)

It's very strange 😅 Nobody reported to us that version 2.0.0 does not render. Maybe you have a old revision in forked repo. Please try https://asyncapi.github.io/asyncapi-react/

It's not handling additionalItems.

It's also not handling:

Some things like 3. point should be easy to fix, when we'll go from inlined retrieving schema schema.info.contact.email etc. to parser-js api. We must also remember that in cycle time someone can contribute to our component, so if we decided to merge changes, we should also update "new" version of component.

Maybe this is a implementation details, but I suggest to create separate branch in component repo and contribute to it before merging changes - we can "break" functionality between PRs.

fmvilas commented 3 years ago

Oh yeah, I was looking at https://www.asyncapi.com/asyncapi-react 🤦 We need to get rid of it. Thanks, Maciej!

Maybe this is a implementation details, but I suggest to create separate branch in component repo and contribute to it before merging changes - we can "break" functionality between PRs.

As you feel more comfortable :)

derberg commented 3 years ago

Let's forget about the theme feature of the component for now. It will only have a single "theme" and it's the one matching the styles of the HTML template. We'll add support for themes on the future UI library instead.

Does this mean the current style of react component will go away and nobody will able to apply it as a legacy?

magicmatatjahu commented 3 years ago

@derberg Good point! Kyma for example should use fiori... Hmmm... 🤔 Person working on this task should try to "wrap" Tailwind CSS to existing classes. Problem reached by you should be also addressed here. @fmvilas What do you think?

fmvilas commented 3 years ago

They will not be able to use "this new version of the component" but we'll make it customizable in a future cycle (most probably the next one). In the next version, we can make sure customization is good enough to meet the needs of the Kyma team and others.

derberg commented 3 years ago

definitely, my comment was there to make it explicit, like clear for others what will happen with new version + make sure we all are also familiar and remember what needs to be done next.

I was not thinking about Kyma much as they anyway update once a year when their security tools spot some vulnerability in some dependency 😆 I was thinking here about more active users, like folks from Spotify for example, or WSO2 that I think started integrating recently.

Now I'm thinking that maybe there should be some issue here https://github.com/asyncapi/asyncapi-react/issues, even pinned to the Issues tab so it is clear that next weeks will influence the architecture of the component. Would be great to ask people there if actually anyone is going to miss the current feel and look

fmvilas commented 3 years ago

Would be great to ask people there if actually anyone is going to miss the current feel and look

That would be great indeed. Would you mind asking it yourself? I'm starting to handle many issues 😅

magicmatatjahu commented 3 years ago

I will, on react repo and html-template repo :)

derberg commented 3 years ago

@magicmatatjahu thanks man, keep in mind that in html-template repo there is already an issue about it I think, just reuse and pin this one I guess

magicmatatjahu commented 3 years ago

We should also try to fix issues related to accessibility. Reference issue -> https://github.com/asyncapi/html-template/issues/163

magicmatatjahu commented 3 years ago

@asyncapi/react-component@1.0.0-next.1 is published with @asyncapi/html-template@0.21.0 :) Any bugs/errors should be reported in the mentioned repositories.