RFC: Improve React Developer Experience

[markacianfrani]

The developer experience for our React users is less than ideal for a number of reasons

1. There are a number of Web Component concepts that may be unfamiliar to React developers. Things like Shadow DOM and slots in particular. While we do briefly document these things on https://astro-components.netlify.app/?path=/story/astro-uxds-welcome-react--page, there are still issues:
   1. The page itself is difficult to find. It's hidden under the Welcome page.
   2. I'm less likely to read an entire page of text when I'm getting started. All I want is to get up and running as fast as possible. I don't care about methods or slots until I actually need to use them.
      1. Instead we might want to sprinkle in some of these concepts or at least call back to them under individual component's API documentation.
2. The minimal starter CodeSandbox can be difficult to find. It's under "Start Here" not "React"
3. The fact that all of our code examples are in html and not JSX is infuriating. It's simple enough to manually convert but it's a huge papercut every time you want to paste them into your application.
   1. Consider something like Shoelace's code examples that have a toggle for React/JSX
      
4. The relationship between our React wrapper and our web components isn't explained very well. It's confusing--are we offering a React library or a web component library?

I really like how Storybook has this context switcher globally for the site.

[micahjones13]

The page itself is difficult to find. It's hidden under the Welcome page.

Agreed. I think the default getting started page should have links to each frameworks docs as part of the first thing someone sees when they come to the site.

The minimal starter CodeSandbox can be difficult to find. It's under "Start Here" not "React"

Agreed. We should put it under React as well as Start Here - same goes for other frameworks.

The fact that all of our code examples are in html and not JSX is infuriating. It's simple enough to manually convert but it's a huge papercut every time you want to paste them into your application.

• Happens to me way too often. The tabs view a-la Shoelace is great - something I think we should add to our component pages when they're ready.
• The codesandbox link that Shoelace uses is great, and I think we should have that for all our components as well, especially for react examples.

The relationship between our React wrapper and our web components isn't explained very well. It's confusing--are we offering a React library or a web component library?

I don't think this is stated anywhere, which is a bad oversight.

[mrclean-oa]

I'm sorry upfront for being so long-winded. Just trying to offer quality feedback.

There are a number of Web Component concepts that may be unfamiliar to React developers. Things like Shadow DOM and slots in particular.

The concepts needed to understand working with Web Components should be carried through all frameworks that you support. However you want to organize it (link to a central location, copy the section into each docsite, etc), it should be one of the first links after "Getting Started" perhaps a "Core Concepts" section that goes over some of the nuances.

Also the design tokens you expose would be important to call out in that section.

One of the things that tripped me up starting out, was how to use those design tokens the CSS file we're told to include contains. So using this as an example, maybe the "Core Concepts" section outlines something to the effect of:

In our storybook you will find call-outs to CSS variables. These can be used by targeting [fill in here] in your CSS to customize the Astro components. These Custom Properties act as a kind of API for modifying the design system ... blah blah example:

rux-input {
  --input-width: fit-content;
}

I'm sure you've already thought of this, or done this, but this is something that's just not clear enough for me to know with certainty. I would typically just dig through the source code, but a lot is left up to interpretation when you're doing that. I've also found myself getting confused on whether the "CSS Shadow Parts" are actually "CSS Custom Properties" contained within the Shadow DOM. I would expect them to have two dashes next to them --error-text verses error-text with the latter being in the Storybook now, and making it seem like it's a prop or something that I should know about but can't connect the dots to use it.

The relationship between our React wrapper and our web components isn't explained very well. It's confusing--are we offering a React library or a web component library?

Yep, Agreed. My experience is when I look at the source and see all this it is intimidating, and also looks like you are offering a web-component library wrapped with React.

I noted that the createReactComponent function dynamically creates all your web components, and that's pretty cool. I also remember seeing you use a similar approach with generateIcons in the web component package. But having some experience with React, I'm left wondering how stable it is to treat every component exactly the same in this way.

When I first saw that massive components.tsx file, my first thoughts were:

1. Intimidation
2. This looks like they just wrapped React around their web component.
3. There is no neat organizational structure, like organizing component groups based on folder. This massive barrel file does not look like it is tree-shakable, so I'm going to have to import the entire component library if I want to use one component.

On a separate occasion, I was expecting to be able to find the props for a component fairly easily, however, I found I had to mentally convert the web-component props into camelCase, and if I wanted a more in-depth look I had to open my editor, find something like JSX.RuxBreadcrumbItem being passed in as props, then ctrl + click it in VS code and be presented with this:

export namespace Components {
    interface RuxBreadcrumbItem {
        /**
          * The href property of the breadcrumb item link
         */
        "href"?: string;
    }
}

Then there are events. I remember a foot-gun about how events are named for React, while doing that mental conversion that didn't work, and since onChange is valid in React, but not called from Stencil, I was left with a change event that was not firing. I'm happy to see you added to the React documentation page.

The page itself is difficult to find. It's hidden under the Welcome page.

The minimal starter CodeSandbox can be difficult to find. It's under "Start Here" not "React"

I didn't know that was there, if that helps you understand how well-hidden.

The fact that all of our code examples are in html and not JSX is infuriating. It's simple enough to manually convert but it's a huge papercut every time you want to paste them into your application.

Agree. When I'm implementing a component, and click "Docs > [example] > Show Code" I'm expecting to see an example with the library I'm using. I like the screenshots you shared.

Also examples of testing with React Testing library, and jest would be helpful. I know it's hard when there are so many options for testing, but one of my issues was understanding how to pierce the Shadow DOM and use React Testing Library events to type. I'm pretty sure @micahjones13 has done some work in this repository that had it working. I'm just looking for more context, "Now we need to include xyz here, because web components use abc and Jest doesn't know about that." That way when something breaks, you can understand the layers of the program better.

So to sum up my thoughts, for now, it would be:

1. Create a "Core Concepts" page that explains to the implementer what to do when they come across a slot. Since developers are skimmers, and definitely will not follow a top-down approach to your docs, you should also reference these core concepts when applicable. Something like, "For more information on how to use slots in general, refer to the Core Concepts (link) part of the documentation." As well as the CSS Custom Properties, you don't need to re-explain what they are, simply where to scope them when using your design system. You can also link to an MDN article about them for people who aren't familiar.
2. Make props and events easier to grep in the documentation, this may be through the proposed code switcher that was mentioned or some other way.
3. Testing Explainers/Examples - I thought I saw some cool stuff you all did with puppeteer/playwright in your CI pipelines/Github workflows and testing your web components in isolation, but it's been too long. I really took a deep dive into your repos when I was dealing with that issue last year.

[mrclean-oa]

We did do some testing work, and actually have a section here about testing with RTL

Whoa! This is packed full of really good information. I didn't even know that was there. I'll leaf through it. Looks like you have the design token stuff in there that I was commenting about. It's very cool to know you offer them in JSON too, because that would integrate nicely with a system like Tailwinds.

[micahjones13]

Whoa! This is packed full of really good information. I didn't even know that was there. I'll leaf through it.

Hopefully it's helpful, some of it may be a bit outdated at this point. Let me know if you have any questions!

t's very cool to know you offer them in JSON too, because that would integrate nicely with a system like Tailwinds.

We also have a tailwind theme! You can find that in this repo https://github.com/RocketCommunicationsInc/astro-tailwind

[mrclean-oa]

I had a thought. I'm starting to think that y'all should start with discoverability of the Astro UXDS features, and work backwards from there when you are working this RFC.

I'd say maybe start a list like:

1. Key Feature 1
2. Key Feature 2
   • Lesser known feature 1
3. Key Feature 3
   • Lesser known feature 1
   • Lesser known feature 2
   • Lesser known feature 3

Then get feedback, I can help from an implementer standpoint if desired, and decide the best way to expose these features using the documentation.

Example:

1. Themes
   • Astro Tailwind CSS
   • Astro AG Grid
   • Make your own theme using Astro

[mrclean-oa]

One discussion we had today was our designer went through and audited our usage/compliance with Astro's Design System.

One of the things we were discussing is what does it mean to "follow a design system" does it mean we can only strictly use your components? Or as you mentioned in your documentation:

While our components may solve 60% of your UI needs, you will inevitably find yourself needing to create your own custom UI in the style of Astro.

Our Astro Web Components are powered by our Design Tokens under the hood. These are imported and made available to you when you import astro-web-components.css in the form of CSS Custom Properties. Our Design Tokens include everything from our color palette to our spacing system.

So I think having the theming section would go along way to close that gap of "are we doing it right?" What I call the "designer docs" at https://www.astrouxds.com do a really good job of this. It would be nice to have some Do's and Don'ts on the developer side for the design tokens when creating your own theme.

[markacianfrani]

That's something we've been asking ourselves internally. This is such good feedback. The short answer is, no you don't have to use our web components to be compliant.

We have a ton of new updates to astrouxds.com coming and one of them is the introduction of component spec pages. We realized some components are trivial to style yourself (container, for example). With component tokens, you can easily create your own Container, and have it stay in sync as the design system evolves. For example, if we decide to change the background color slightly for better contrast, you only have to update your tokens, no change necessary.

I'd also love to get your feedback on Tailwind, I'll create a new discussion for that.

Our tokens are our newest addition so our docs still are catching up.

[jarod-oa]

I am trying to replicate this test and am having a few problems. For the RuxInput, the setInput is not a prop to RuxInput, I changed this to onRuxinput and that resolved the issue with syntax. When I run this test, the userEvent.type(shadowInput, 'User input!') does not seem to fire the onRuxinput which makes it hard to test functionality that would go this RuxInput. Any tips or advice would be appreciated.

[micahjones13]

Hey @jarod-oa, I've converted this to an issue and created a ticket to start work on it. I'll let you know when I have updates on it!

[micahjones13]

@mrclean-oa @jarod-oa we're updating our Storybook site to better convey web component usage and framework specific documentation as well. There's a deploy preview up, and we'd love your thoughts on it if you have the time!

[mrclean-oa]

This all looks really good! Great work. I noticed you used TypeScript in the Listening to Events section. That might be nice to include JavaScript verses TypeScript sections where applicable, if you haven't already. I do particularly like how you did this with Listening to Events because knowing which event type in TypeScript/React is usually a pain point---it's the simple things that make it feel much nicer. Especially this advice:

It is highly encouraged to listen to these custom events rather than default React events such as onChange. Because some React events are different from their native JS counterparts, some bugs can arise from using default React events.

As a seasoned React developer, I didn't realize this would be an issue.

Will you include a section about boolean attribute values using React? I know in the past we had to do something like:

const MyComponent = ({isDisabled}) => {
  const [disabled, setDisabled] = useState({})
  useEffect(() => {
    if (isDisabled) {
      setDisabled({disabled: ''})
    } else {
      setDisabled({})
    }
  }, [isDisabled])

  return <RuxButton {...disabled}
}

Because Stencil/React/Web Components something didn't like disabled={false} because "Hey the attribute is there, so it's disabled!" so we had to use that workaround.

I'm pretty sure you mentioned that was fixed a while ago, but it may still be nice to include in the docs.

Overall, great work on the new docs! I'll have to peruse them more, but there are no glaring issues I'm seeing.