Reorganize and rename components

[stephiescastle]

Checklist

• Include a description of your pull request and instructions for the reviewer to verify your work.
• Link to the issue if this PR is issue-specific.
• Create/update the corresponding story if this includes a UI component.
• Create/update documentation. If not included, tell us why.
• List the environments / browsers in which you tested your changes.
• Tests, linting, or other required checks are passing.
• PR has an informative and human-readable title
  • PR titles are used to generate the change log in releases; good ones make that easier to scan.
  • PRs will be broadly categorized in the change log, but for even easier scanning, consider prefixing with a component name or other useful categorization, e.g., "BaseButton: fix layout bug", or "Storybook: Update dependencies".
• PR has been tagged with a SemVer label and a general category label, or skip-changelog.
  • These tags are used to do the aforementioned broad categorization in the change log and determine what the next release's version number should be.
  • Release Drafter will attempt to do the category labeling for you! Please double-check its work.

Description

This PR addresses #130 and #147.

• Added a new Storybook component section called Mixins which now contains:
  • A dedicated overview page
  • AnimationCaret renamed to MixinAnimationCaret
  • BaseVideoBg renamed to MixinVideoBg
  • BaseCarouselCards renamed to MixinCarousel
• Renamed ArticleCarousel to a more generic BlockLinkCarousel, which now has an itemType argument to choose between:
  • ArticleCarouselItem renamed to BlockLinkCard
  • TopicsCarouselItem newly added (Add TopicsCarousel component #147) and renamed to BlockLinkTile
• Renamed BlockFactCards to BlockCardGroup
  • Renamed BlockFactCardsItem to BlockCard
• Renamed the Hero blocks
  • HeroFeature renamed to HeroMedium and referred to as "Medium"
  • HeroFocalPoint renamed to HeroLarge and referred to as "Large"
  • HeroMedia referred to as "Media Only"
• Any task where a component was renamed also included renaming its storybook filenames, CSS class name, SCSS include filename, JavaScript include filename, and any file references, where applicable
• Rebuilt dist folder

Noted follow-up

• If comparing Explorer 1 stories to WWW, you will notice that the compact options are not yet available in Explorer 1 for BlockLinkCard and BlockLinkTile (fka ArticleCarouselItem and TopicsCarouselItem). These will be handled, among other improvements, in Update ArticleCarouselItem and TopicsCarouselItem to include compact versions, headingLevel prop, and improved label #58
• The original task list in Rename and reorganize components #130 mentions "Create a table in our projects that use Explorer 1 that maps data models to design component." I think this should be handled on a per-project basis, perhaps as a recommended action item in the migration notes when updating Explorer 1 in a project.

Questions

Should cards move to a separate section?
I created a "Card types" heading on the Blocks Overview page and listed BlockCard, BlockLinkCard, and BlockLinkTile there. I debated moving them to their own components section, perhaps: Components > Cards, but wanted to get some input before doing so.

I do think it's helpful to see them grouped together, but another option would be to have BlockLinkCard and BlockLinkTile live under BlockLinkCarousel, and BlockCard to live under BlockCardGroup. I liked bringing them more to the foreground however, as they can be reused in different contexts, but I guess none of our components really support swapping them ad lib just yet, except where it's already documented (BlockLinkCarousel).

Migration Notes

Various components have been renamed, including their corresponding SCSS and JavaScript includes. You should check your projects for any of the following and update accordingly. Note that all new names are documented in the table below, but not all new names require action.

Old name	New name	All users	A la carte: SCSS updates	A la carte: JS updates
BaseCarouselCards	MixinCarousel	Update CSS class name in html template	Renamed to _MixinCarousel.scss	Update /src/js/vendors/_swiper.js and /src/js/vendors/_swiperOptions.js. If importing exports directly from _swiperOptions, note that the export name has changed to MixinCarousel
AnimationCaret	MixinAnimationCaret	Update CSS class name in html template	Renamed to _MixinAnimationCaret.scss	N/A
BaseVideoBg	MixinVideoBg	N/A	N/A	N/A
HeroFeature	HeroMedium	Update CSS class name in html template	Renamed to _HeroMedium.scss	N/A
HeroFocalPoint	HeroLarge	Update CSS class name in html template	Renamed to _HeroLarge.scss	N/A
BlockArticleCarousel	BlockLinkCarousel	Update CSS class name in html template	N/A	N/A
BlockArticleCarouselItem	BlockLinkCard	N/A	N/A	N/A
BlockFactCards	BlockCardGroup	Update CSS class name in html template	N/A	N/A
BlockFactCardsItem	BlockCard	N/A	N/A	N/A

Old component names will be supported until the next major release.

New features added to BlockLinkCarousel

Additionally, BlockLinkCarousel has a new "item type" argument. BlockLinkCard, the default selection, replicates what was formerly known as BlockArticleCarousel. A new option, BlockLinkTile, is now available as well.

MixinCarousel improvement

The -tile variant of MixinCarousel now includes pb-5 by default. When used in projects, the -tile variant required adding the pb-5 inline class to work properly with tiles. If this applies to your project, you can now remove the pb-5 inline class from the following selectors: .BaseCarouselCards.-tile or .MixinCarousel.-tile

Recommended

If you are using Explorer 1 with a custom frontend framework, you may want to consider renaming your components, and/or creating a table documenting how your project's components map to the Explorer 1 design system.

---

Instructions to test

1. npm run storybook
2. Check for the new names and organization as detailed in the PR notes!
3. Note that if you are testing swapping between BlockLinkCard and BlockLinkTile in BlockLinkCarousel, it will only work in canvas view, not docs view. This is a known issue: DocsPage controls do not work for iframe stories #145

Tested in the following environments/browsers:

Operating System

• macOS
• iOS
• iPadOS
• Windows

Browser

• Chrome
• Firefox ESR
• Firefox
• Safari
• Edge

[laespinoza]

@stephiescastle great work with the reorg and renaming of components! I tested the build and looked over the code and it all looks good. As far as your question about the Cards, I don't really have much of an opinion on that other than I don't want to create more work for you; but if you found it helpful seeing them grouped together then perhaps others will also find it more helpful with them separated.

[Scotchester]

Should cards move to a separate section? I created a "Card types" heading on the Blocks Overview page and listed BlockCard, BlockLinkCard, and BlockLinkTile there. I debated moving them to their own components section, perhaps: Components > Cards, but wanted to get some input before doing so.

I do think it's helpful to see them grouped together, but another option would be to have BlockLinkCard and BlockLinkTile live under BlockLinkCarousel, and BlockCard to live under BlockCardGroup. I liked bringing them more to the foreground however, as they can be reused in different contexts, but I guess none of our components really support swapping them ad lib just yet, except where it's already documented (BlockLinkCarousel).

Hmm, this is tricky. I do think it's helpful to see these three things grouped together somewhere, but are "tiles" in fact a variation of a card? If not, I think it's potentially confusing to group them under "Card types" or a new Components > Cards section. If they are a variation of a card, then perhaps BlockLinkTile should be renamed BlockLinkTileCard or BlockLinkCardTile?

[Scotchester]

That migration table is 🤌

[stephiescastle]

but are "tiles" in fact a variation of a card? If not, I think it's potentially confusing to group them under "Card types" or a new Components > Cards section. If they are a variation of a card, then perhaps BlockLinkTile should be renamed BlockLinkTileCard or BlockLinkCardTile?

Maybe not a variant, but they are a type of "thing that can be interchangeable with other things in a list context." We never landed on a general term for things like that, one of which could be "card."

I'm hesitant to use something like BlockLinkTileCard because it starts to feel like the same trap we found ourselves in when we embarked on the renaming task.

Hmm.. will continue to think on it.

[Scotchester]

Good points, @stephiescastle. I think I like sticking with what you currently have, just grouping them on the Blocks overview page.

[stephiescastle]

Discussed the SemVer tag with @Scotchester, and we decided to keep this PR slated for a minor release, not major. Specifically: leave the old class names in place with a to-be-deprecated notice.

Example: in src/scss/components/_HeroLarge.scss, don’t replace .HeroFocalPoint with .HeroLarge, just add .HeroLarge as another option in that selector, and give notice that the .HeroFocalPoint class will be deprecated in some future version 2.0.

I'll work on making these changes before merging.

[stephiescastle]

@Scotchester I've pushed a commit that keeps this backwards compatible and updated the migration notes to reflect that. I'll also keep the "cards" as is on the Blocks overview page. I believe this is ready for another review.

[Scotchester]

Looks great, thank you!

[kaelynrichards]

all looks/sounds good to me :) Thanks, Stephanie!!