Evaluate how Web Components work in common React environments

[mattrosno]

This is important for products built with Carbon v10 React, because the AI enhancements (e.g. slug, gradient) are only being built in Carbon v11 (React and Web Components).

If a product is built with Carbon v10 React, and they want an AI-enhanced modal component for example, we'd recommend they use the AI-enhanced Web Component modal (not React).

This POC is not applicable to products built with Carbon v11 React, as they would just use the AI-enhanced React components not the AI-enhanced Web Components.

[mattrosno]

@jeffchew @lee-chase can you populate the tasklist with what needs done in this proof of concept? I imagine it's something like:

• Determine what unique dependency sets needs evaluated in this proof of concept (e.g. what versions of Carbon React? What versions of React?)
• Determine what needs proved
• Prove or disprove it with evidence documented in this issue (e.g. Stackblitz links)

[lee-chase]

Might need to define "common React environments".

If a WebComponent can...

• Be used by a React component
• Host a React component in a slot
• Work with SSR (NextJS).

I can take a look, but give the existence of @lit/react I'd hope to find everything is OK.

• https://www.npmjs.com/package/@lit/react

[mattrosno]

@annawen1 what else should be proved or disproved in this issue?

[lee-chase]

I suppose there is also the Carbon specific stuff

• prefix works
• theming works

[lee-chase]

WRT use of Web components in React. This is relatively simple but the experience is not currently the same as using native components. It is made simpler by with the use of @lit/react but as is outlined here named slots are require a wrapper div element. While this can be hidden from the user with more React wrapping, as in the example, use of "display: content" to hide the '

' has some a11y support issues (see can i use link) with only Safari on IOS working as desired.

https://stackblitz.com/edit/github-skkfec-iddl7r?file=package.json,src%2FApp.jsx https://caniuse.com/css-display-contents

[annawen1]

Currently the @carbon/web-components package isn't using @lit/react, it's using a custom script to generate the React wrappers at the moment. So we'll have to check that this custom script works at the moment with certain things like SSR.

[lee-chase]

@annawen1 presumably has the same issue as @lit/react with regards to named slots hosting React components.

[mattrosno]

@ljcarot I updated the description per the conversation just now in standup.

[jeffchew]

@lee-chase was just chatting with @annawen1 , it might be worth seeing if we should upgrade Carbon Web Components to use the Lit version of the react wrapper implementation so we get a better and more true grasp of web components embedded into React applications using this approach. We would then as preliminary tasks need to 1) upgrade Carbon Web Components to Lit v3, then 2) swap out the react wrapper implementation from the custom one to the @lit/react implementation. It's highly possibly that there are features and considerations in the official package that our homegrown one is not accounting for and may not give the best picture on what the experience will be like.

[lee-chase]

@mattrosno @jeffchew @annawen1 can I check something.

@carbon/web-components - is V2.0.1 and uses Carbon 11. https://github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components

Assuming this is the target for AI enhancements and not V1 this means anybody using Carbon 10 with V2 of WebComponents will be loading both V10 and V11 styles.

[jeffchew]

@lee-chase yes, and one thing we want to also test in this POC is the embedding of CWC v2 (Carbon v11) components on a Carbon v10 can live in harmony, considering and taking advantage of the shadow DOM aspects of this library.

[jeffchew]

@lee-chase also CWC v2 is currently on a feature branch while Carbon for IBM.com is getting upgraded to v2. It will all get squashed down when that upgrade happens (RC is coming out this month).

But for now, you can see the upgraded CWC v2 on this branch: https://github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/feat/cwc-v2

[lee-chase]

Created project to work through some Carbon 10 + Carbon 11 WebComponents use cases.

https://github.com/lee-chase/c4ai-carbon-10-poc https://lee-chase.github.io/c4ai-carbon-10-poc/

It is a work in progress and the notes below will get updated on moving to @lit/react and resolving styling issues.

• CDSOrdered list appears to have no numbering, some CSS is missing
• The dropdown has no background color
• Does not accept className
• Named slots are not used in React normally. So NOT as simple as swapping Carbon/React for Carbon/WebComponent.
• In some cases a slot is used instead of an property.
• Hyphenated property names
• Some props may have different defaults (label-a, label-b checkbox blank by default)
• There is no CDSForm

[lee-chase]

Given the initial notes above @mattrosno the POC demonstrates some of the differences between the React and WebComponents coding style. Use of slots (other than children) and hyphenated property names may feel so alien to a React developer that they'd shy away from using WebComponents. In addition it may feel like they are creating technical debt.

I would recommend we put the POC, when we are happy with it, in front of some React product teams to determine if they would use V11 WebComponents enhanced with AI in a Carbon 10 React project.

[jeffchew]

As mentioned, issues added to track the migration of Carbon Web Components to use @lit/react: https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/11113 And dependency to it: https://github.com/carbon-design-system/carbon-for-ibm-dotcom/issues/11021

As discussed, we may land on having a more concerted push for React teams to migrate to v11 anyway, but will see if the developer experience using Lit's React wrappers will be improved at all, considering that the current React wrappers for Carbon Web Components are a few years old at this point.

[lee-chase]

Added some dropdowns using @lit/React. The three dropdowns are a raw @lit/react and twoversions that look more like the @carbon/react component, the last one using a custom function createComponentPlus instead of createComponent from @lit/react as an example of how we might make it easier for production teams to adopt WebComponents.

@annawen1 createComponentPlus is currently only 33 lines but was written while only considering the Dropdown. It Does not look at hyphenated property names as yet.

There are a number of issues visible on the POC which it would be worth investigating further to see if the error is between keyboard and chair (me) or something that

Further investigation (second opinions sought).

1. CDSOrdered list appears to have no numbering, some CSS is missing
2. Does not accept className
3. There is no CDSForm
4. CDSStack has not working
5. Some styling is off e.g. button (100% width)
6. Select missing a label
7. Chrome dev tools is complaining about duplicate IDs which appear to be in shadow-dom.

Other notes

1. Named slots are not used in React normally. So NOT as simple as swapping Carbon/React for Carbon/WebComponent. See createComponentPlus
2. In some cases a slot is used instead of an property.
3. Hyphenated property names
4. Some props may have different defaults (label-a, label-b checkbox blank by default)
5. Use of CDN to import Carbon 11 styles needed an additional class/selector to be added to the body.

[annawen1]

I'll open issues within the dotcom repo (numbers 1,4, and 7 from the top list).

We didn't create a CDSForm as the component from carbon react looked to just render a form element that the adopter could author themselves? From the web component perspective it seemed redundant.

I'll have to take a closer look at 5 and 6 to determine if those are bugs.

[mattrosno]

@lee-chase @jeffchew @annawen1 @tw15egan what should our acceptance criteria be for this issue? Maybe something like a Stackblitz template so for each AI-enhanced component that we deliver, we provide a demo of the different supported scenarios? E.g. a Stackblitz per component so for the AI-enhanced text input:

1. React text input with Carbon v11
2. Web component text input with Carbon v11
3. Wrapped (or straight up) web component with Carbon React v11
4. Wrapped (or straight up) web component with Carbon React v10

Then product teams could reference these demos? For teams that currently don't use web components, or haven't used web components alongside React, these demos could be a good playbook for them to reference.

[jeffchew]

@lee-chase @annawen1 @ariellalgilmore Resurfacing this. Similar to the documentation given by @tay1orjones regarding the aliasing approach, would like some guidance on what would be the best approach with Web Components in React. If this is to use the CDN approach, would be good to include a stackblitz or two, like an isolated example and then another one with CDN web components in a React setup.

Would like to also call out any pros and cons of the approach, what potential tech debt incurred, any risks to the approach for setup, ongoing maintenance/upgrades, etc.

[lee-chase]

@lee-chase @annawen1 @ariellalgilmore Resurfacing this. Similar to the documentation given by @tay1orjones regarding the aliasing approach, would like some guidance on what would be the best approach with Web Components in React. If this is to use the CDN approach, would be good to include a stackblitz or two, like an isolated example and then another one with CDN web components in a React setup.

Would like to also call out any pros and cons of the approach, what potential tech debt incurred, any risks to the approach for setup, ongoing maintenance/upgrades, etc.

CDN is definitely the way to go for styles. I think React developers would appreciate WebComponents wrapped to look more like React components, but that just creates more maintenance. See createComponentPlus https://github.com/lee-chase/c4ai-carbon-10-poc/blob/main/src/ExampleCWCLitReact/CWCLitReact.js

[jeffchew]

Thanks @lee-chase .

For specifically the task here, we should be focusing on teams that are on either React v10 or another framework like Angular (regardless of Carbon version). Since bringing in CWC v11 into a stack via npm would still run into the package dependency issues, we should probably be recommending the CDN only for v10 teams until they migrate, which then would be a separate question of what they would use. If they are a React team and successfully move to v11, they would just use the React version of Carbon so it would be a non-issue (for core components). For Carbon for AI, yes we should think of the best developer experience for React teams pulling in Carbon for AI components (with React wrappers).

For the exercise of teams using a bridge approach before getting to v11 and documenting that, we should provide guidance there on the CDN urls and how to bring those in. They would essentially be treating the custom elements like they were bringing in a <p> tag or <input> tag into their JSX, but is bringing in a custom element Carbon component instead and should probably be an acceptable bridge until they fully migrate.

[mattrosno]

@jeffchew thinking this would live in a new markdown file (or the same file as PR 44 if that makes more sense) in the /docs directory here:

https://github.com/carbon-design-system/carbon-for-ai/tree/main/docs

like:

https://github.com/carbon-design-system/carbon-for-ai/pull/44

[jeffchew]

Adding notes from slack here regarding content:

Would be great to see a CDN example of pulling in the slug actually, once it's available! But this would be great to include is a stackblitz showing that. We can probably include a basic example to even explain what the CDN urls are (something like this: https://stackblitz.com/edit/web-platform-3ed6eq?file=index.html), how it's different from NPM, and how it differs as an approach compared to aliasing.

We might also need to explain that they are delivered as web components, what that means, how shadow DOM and encapsulation works (and why it can be mixed in seamlessly on their application).

We might also need to explain where it's hosted (IBM Akamai, hosted by corporate webmaster team), can provide the slack channel where they provide support and can answer further questions on how they manage akamai. Watsonx.ai team asked about how they handle caching, and can gather that webmaster team can also answer those questions like TTL configurations, hashing, etc.