feat: add slot event part docs to foundation

[chrisdholt]

Pull Request

📖 Description

This PR does an initial pass to add jsdocs to enable support for slots, events, and parts in the CEM analyzer.

Two components have some gaps due to how composable they are - Calendar and Data Grid.

🎫 Issues

closes #5904

👩‍💻 Reviewer Notes

📑 Test Plan

✅ Checklist

General

• I have included a change request file using $ yarn change
• I have added tests for my changes.
• I have tested my changes.
• I have updated the project documentation to reflect my changes.
• I have read the CONTRIBUTING documentation and followed the standards for this project.

Component-specific

• I have added a new component
• I have modified an existing component
• I have updated the definition file
• I have updated the configuration file

⏭ Next Steps

[chrisdholt]

@scomea are you able to add this context for data-grid once this PR goes in? I'm did not feel familiar enough with the code to address everything.

[williamw2]

The analyzer uses the hyphen as the separator between the name and the description. These hyphens between @slot and the name should be removed.

[chrisdholt]

Yeah, I did almost all of these manually, I'll do one last check for any time it's not the default slot.

[scomea]

@scomea are you able to add this context for data-grid once this PR goes in? I'm did not feel familiar enough with the code to address everything.

Ok.
#5913

[williamw2]

Typo. Should be "@csspart".

[nicholasrice]

Wow, thanks Chris! I'm so happy we're finally able to get these flags in. One thing that catches my eye here is that it documents the foundation components as if they are a single component, template and class, where in this package those two are never actually combined. For example, the ES6 class conceptually never has css parts or slots because those are template concerns. I don't know if we should change anything now because we would likely need to adjust the CEM code, but to me it would make more sense if the class and templates are both documented w/ their respective TSDoc flags. Any thoughts on that? We can take to an issue if needed.

[chrisdholt]

Wow, thanks Chris! I'm so happy we're finally able to get these flags in. One thing that catches my eye here is that it documents the foundation components as if they are a single component, template and class, where in this package those two are never actually combined. For example, the ES6 class conceptually never has css parts or slots because those are template concerns. I don't know if we should change anything now because we would likely need to adjust the CEM code, but to me it would make more sense if the class and templates are both documented w/ their respective TSDoc flags. Any thoughts on that? We can take to an issue if needed.

I fired this off without much investigation after a few conversations with @williamw2, so I have zero thoughts. Totally open, just going by the initial convention shared. I’ll default to him :)

[williamw2]

@nicholasrice I don't think that's going to work. The problem is in how we declare the templates as a const function that returns a template. The CEM analyzer sees it as just a function and seems to ignore any jsdoc tags that don't apply to functions. Then the markdown generator simply renders it in a "function" table with just a name and description. I'm currently manually excluding the template functions from the markdown output as they didn't seem useful. The plan is to eventually replace the CEM markdown generation with a custom solution. Maybe we can try to address this then.