Add JSX Types and Docs

[break-stuff]

This PR adds support for JSX with the following changes:

• Added type generator
• Added documentation on how to use types
• Some light API clean-up for some of the components

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
shoelace	✅ Ready (Inspect)	Visit Preview	Jun 5, 2025 2:00pm

[KonnorRogers]

👀 very cool. So with this, React 19+ would get type safety on bare custom elements without needing to use our wrappers. Seems like a win to me...

[claviska]

This is amazing, but I really don't like adding @internal to so many properties. Is there a more ergonomic way we (and or the plugin) can identify properties that should be included? 🤔

[schilchSICKAG]

I did not even realize there is a plugin for this now :). We built our own react 19 type wrapper with a couple of lines of JS, using the original custom element manifest provided by shoelace in our "fork" Synergy.

It even supports autocompletion for all css variables in the styles object. For us there was no need to use any external markings when developing this, so I think it is some configuration option that may be missing in the official cem package.

Could port this to shoelace if you are interested. However, I agree an official version with an external package would still be nicer as it may have better support in the long term.

[break-stuff]

This is amazing, but I really don't like adding @internal to so many properties. Is there a more ergonomic way we (and or the plugin) can identify properties that should be included? 🤔

@claviska are those properties meant to be avaliable for teams to use? Alternatively, you can make the properties private or protected, but I think some of them are being exposed for testing purposes. Technically you can still access them (unless you use the # prefix), but you will get a TS error.

[break-stuff]

I did not even realize there is a plugin for this now :). We built our own react 19 type wrapper with a couple of lines of JS, using the original custom element manifest provided by shoelace in our "fork" Synergy.

It even supports autocompletion for all css variables in the styles object. For us there was no need to use any external markings when developing this, so I think it is some configuration option that may be missing in the official cem package.

Could port this to shoelace if you are interested. However, I agree an official version with an external package would still be nicer as it may have better support in the long term.

@schilchSICKAG Very cool! Great minds think alike, I guess. 😉

CSS variables is coming soon to the packag as well.

I originally went with a type generator similar to what you have, but I needed to open it up so they would work in any JSX environemnt (preact, stenciljs, etc.), so I had to avoid a dependency on react.

[schilchSICKAG]

I originally went with a type generator similar to what you have, but I needed to open it up so they would work in any JSX environemnt (preact, stenciljs, etc.), so I had to avoid a dependency on react.

@break-stuff: Thanks for the explanation. You are right, we currently do not support Preact and this would be difficult to get with react types. Will have a deeper look at your solution, maybe I can port some parts - or even exchange my custom solution.