chore: remove component usage files

[DitwanP]

Related Issue: #9015

Summary

Removing usage sample files from repo since we now have links to each components page on the doc site for more in depth information and samples.

[driskull]

I'm not sure I agree with removing these at this time.

@jcfranco what about where we are lacking coverage for some of these on the doc site? For example, there is no virtual element info on popover in the doc site.

If we remove some of these usage files I'm concerned we will be losing info on how to do some things.

IMO it would be better to leave these until we can assure we have the same coverage of information on the doc site.

Since Stencil automatically uses these files an generates documentation samples, it would be nice if we could keep these and use them to generate some of the doc site samples. That way, the samples are within the code base and can easily be referenced. A developer who is developing a component or functionality, has the ability to define usage easier if they can do so within the code base.

[DitwanP]

I'm not sure I agree with removing these at this time.

@jcfranco what about where we are lacking coverage for some of these on the doc site? For example, there is no virtual element info on popover in the doc site.

If we remove some of these usage files I'm concerned we will be losing info on how to do some things.

IMO it would be better to leave these until we can assure we have the same coverage of information on the doc site.

So the plan was to go through the components on the doc site and improve coverage, fix descriptions, and make sure things are still accurate.

Maybe we just leave this for now until the doc site work is done, which is what I was thinking to do initially but wasn't sure if it mattered that much.

Since Stencil automatically uses these files an generates documentation samples, it would be nice if we could keep these and use them to generate some of the doc site samples. That way, the samples are within the code base and can easily be referenced. A developer who is developing a component or functionality, has the ability to define usage easier if they can do so within the code base.

I'm uncertain about the advantages here. It seems like the documentation site offers more detailed examples that often encompass most usage scenarios. While the codebase contains numerous usage files with minor differences, such as adding a property or two to a component, the documentation site could likely achieve the same effect with a toggle.

[jcfranco]

what about where we are lacking coverage for some of these on the doc site? For example, there is no virtual element info on popover in the doc site.

Good point on removing usage files that don't have a counter part in the doc site. Can we come up with a list of useful usage files that are missing from the doc site? I have a hunch it will be a small list. In any case, we can prioritize those items for future doc improvements.

Maybe we just leave this for now until the doc site work is done, which is what I was thinking to do initially but wasn't sure if it mattered that much.

This seems like the best path forward. Once we know we've got proper coverage on the doc site, we should be good to remove usage files and possibly provide guidance on how to add/update doc examples that will get referenced in the doc site.

I'm uncertain about the advantages here. It seems like the documentation site offers more detailed examples that often encompass most usage scenarios. While the codebase contains numerous usage files with minor differences, such as adding a property or two to a component, the documentation site could likely achieve the same effect with a toggle.

Agreed. For context, we are removing usage files for a couple of reasons:

1. we aim for the doc site to serve as definitive source of usage examples
2. currently, the doc site does not use/reference usage files
3. generated readmes offer incomplete documentation compared to what the doc site provides

@DitwanP @macandcheese LMK if I missed anything.

[DitwanP]

The list below Is what I've found for usage samples that might need to get recreated on the doc site, not sure if they all need to so @macandcheese feel free to LMK what we should exclude if any.

• Button
  • Internals sample?
• Input
  • Native Events?
• Label
  • Browser Caveat?
• Modal
  • Before close
• Popover
  • Virtual
• Sheet
  • Before close
• Shell Panel
  • With custom element?
• Tooltip
  • Virtual

[macandcheese]

The list below Is what I've found for usage samples that might need to get recreated on the doc site, not sure if they all need to so @macandcheese feel free to LMK what we should exclude if any.

• Button

We can remove this one - this is outdated. We have explicit properties and don't blindly spread anything anymore.

• Input

Defer to others on this one but it's not specific to Input, this could probably be in the core concepts section. Events is pretty sparse now: https://developers.arcgis.com/calcite-design-system/core-concepts/#events

If we expect certain components will have questions about using native events, maybe we can link to the above? Maybe a note on bubbling in certain situations for nested / slotted components?

• Label

Not sure if this applies to our supported browsers anymore. With no more IE support we might be able to drop this?

• Modal

We should definitely add something about this to any component with a beforeClose option - probably in the Best Practices section. We can also add examples with new samples showing a real-world use case, like an "Are you sure" prompt when trying to close a Modal, etc.

• Popover

Defer to @driskull

• Sheet

Same as Modal

• Shell Panel

Let's confirm this class is still needed / if so we can have a note in Recommendations about this.

• Tooltip

Defer to @driskull

[driskull]

We should add the virtual element doc for popover and tooltip.

[jcfranco]

Thanks y'all!

I agree with @macandcheese and @driskull's recommendations.

[github-actions]

This PR has been automatically marked as stale because it has not had recent activity. Please close your PR if it is no longer relevant. Thank you for your contributions.

[DitwanP]

The usage snippets that were not previously represented on the doc site has now been added, everything else was already covered by the existing samples.

[benelan]

This is going the opposite direction of what I had hoped we would do 😭.

It would be great if we could have the usage examples source of truth in the monorepo right next to the source code and API reference.

When I discussed this with @macandcheese before it sounded like there were just some formatting issues/inconsistencies that prevented him from being able to parse the usage example strings and use them in the doc site.

I think we should be standardizing the format of the usage examples, and from there I could write a simple parser to grab the examples, their descriptions, etc. from docsjson for use in the doc site.

Speaking for myself, I'm way more likely to learn from and contribute to usage examples if they are in the monorepo, rather than hidden behind a VPN.

Additionally, people may be using the usage fields of docsjson for something (although we don't have it documented so removing it wouldn't be a breaking change)

https://cdn.jsdelivr.net/npm/@esri/calcite-components@2.8.3/dist/extras/docs-json.json

[jcfranco]

@benelan Thanks for sharing your thoughts. I understand where you're coming from, but at the moment, there's no benefit in having these files in both this repo and the doc site.

IIRC, there were some technical challenges in consuming usage files, and for practical reasons, the doc site was chosen to host them. If we can figure out how to consume usage files from the monorepo on the doc site, I would agree that the monorepo would be the best place for these files as the source of truth. It would also be beneficial to have them reside close to the component source, tests, and demo pages.

Maybe we can start a separate thread with @macandcheese, @geospatialem, and @DitwanP to brainstorm ideas on how to get this working.

[macandcheese]

To me it also comes down to purpose - the doc site samples often contain a mix of components placed together to illustrate common patterns, component layout, etc., and contain js, css, etc., that may not be related to the "root component" being described.

We can access the usage files through the docs-json just fine, but the consuming component sample (which, lives in the doc site now, but may live somewhere else at a later date) relies on frontmatter / metadata in the source markdown that's not relevant or needed in the monorepo (unique id, pretty name, description, etc).

Additionally, in the consuming component sample - we rely on a configEnabled property added to the source code to know which components to allow users to configure via knobs, similar to how in Storybook you need to specify the knobs explicitly in the source code. I don't think we'd want that property to be shown in the monorepo - in the component sample we of course strip it out and don't display it.

[github-actions]

This PR has been automatically marked as stale because it has not had recent activity. Please close your PR if it is no longer relevant. Thank you for your contributions.

[github-actions]

This PR has been automatically marked as stale because it has not had recent activity. Please close your PR if it is no longer relevant. Thank you for your contributions.