feat: @deprecated decorator

[arvindanta]

Prerequisites

• I have read the Contributing Guidelines.
• I agree to follow the Code of Conduct.
• I have searched for existing issues that already include this feature request, without success.

Describe the Feature Request

Add @decorator option to denote deprecated attributes, events and methods.
Show a console warn when these deprecated items are used by the component consumer

Describe the Use Case

Provide a way to denote deprecated attributes, events and methods.
Show a console warn when these deprecated items are used by the component consumer

Describe Preferred Solution

No response

Describe Alternatives

No response

Related Code

No response

Additional Information

No response

[rwaskiewicz]

Hey @arvindanta 👋

This is an interesting idea! We think that this could be useful for consumers using components in HTML files quite a bit. I think there's some alignment here between Stencil adopting Custom Elements Manifest and this. Although it doesn't support a @Deprecated flag yet, I do believe there is an active feature request for it.

I'd like to see how that flag plays out in the Custom Elements Manifest, as that's something we're keeping an eye on & considering implementing in Stencil. If possible, we would love to leverage that work. I'm going to mark this feature request as something we'd like the community to vote on, and will continue to monitor. Thanks!

PS In the case of TypeScript/JavaScript consumers, the @Deprecated JSDoc may be of help there

[driskull]

Adding onto this request...

We are documenting our slots and our CSS custom properties for our design system. We would love a way to be able to flag deprecated slots and CSS vars somehow. It would be super helpful if Stencil provided a helpful way to do this.

We can handle the props, method, and events with JSDoc but need something better for slots and CSS vars.

cc @rwaskiewicz