Storybook: cleaning up component organization and adding a table of contents for each component section #133

stephiescastle · 2022-02-01T22:43:00Z

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 further refines the Storybook documentation of Explorer 1 and also includes a few bug fixes that were discovered while writing the docs. Fixes #119

Each component section (Base, Blocks, Heroes, Forms, Search) now has a landing page displaying a table of contents with actual rendered components of that section. Building this required adding support for custom React components in MDX, which means we now have the capability to do a lot of fancy things in MDX!
Added some javascript that automatically goes to the first item in a directory group when clicking on a directory in the Storybook sidebar (ux improvement not yet supported by Storybook)
Further explanatory information has been added to the components landing page to illustrate the difference between Base and Block components
Some components have been renamed. These do not introduce breaking changes as there are no custom styles or javascript selectors using the old name (they all use .BaseCarouselCards)
- ArticleCarousel and ArticleCarouselItem have been renamed to BlockArticleCarousel and BlockArticleCarouselItem
- RoboticsDetailFactCards and RoboticsDetailFactCardsItem have been renamed to BlockFactCards and BlockFactCardsItem
The "Blocks" section has been reorganized in Storybook to include BlockArticleCarousel, BlockFactCards and Heroes
"Responsive Design" has been moved to the "Getting Started" section
"Grid & Layout" has been moved to "Base"
Finessed and renamed the TextInput component to FormTextInput and also added a FormTextArea component with similar features (optional label, placeholder, and "required" boolean)
Fixed an issue with the breakpoint configuration of BaseCarouselCard's swiper instance. We now explicitly state the spaceBetween value at each breakpoint in /src/js/vendors/_swiperOptions.js. Previously, the behavior was inconsistent as it was dependent on the initial viewport when loading the page.
Restored docs view for all swiper carousels. Setting inlineStories: false in parameters.docs forces the stories in the DocsPage to load in an iframe, which solved the issue we were having with swiper carousels not initializing correctly on docs pages.

Migration Guide

A change has been made to the BaseCarouselCards template, which affects BlockArticleCarousel and BlockFactCards templates as well. The navigation div, <div class="swiper-navigation lg:block">, should change lg:block to xl:block. This ensures the navigation arrows only appear when the space between each card is 56px (i.e. the 1280px breakpoint).

Instructions to test

Tested in the following environments/browsers:

Operating System

macOS
iOS
iPadOS
Windows

Browser

Scotchester

There's too much here to do a line-by-line code review, but I reviewed the results of this PR throughout my collaboration with @stephiescastle on it. Let's go 1.0!!

…de within an expanded group

…utton and Icons. Requires @babel/preset-react

… cards

…locks. Adding a few component overview docs pages and some form components updating FormInputLabel template adding placeholder for components overview docs finishing up forms docs adding search component docs tweaks to tailwind docs in storybook adding storybook info to introduction

…ting order in preview.js fixing HeroMedia story height in docs view, adds a couple more utility classes to override story height, similar to sbdocs-preview-full-width

… fixes docs view for carousels, tweaks HeroMedia to use the same method to set story height in docs view

Tweak intro and use story names with spaces on Themes page using single story hoisting for components that only have one story Very rough first pass at Components overview reorganizing some storybook docs, and updating other docs to match, adding viewports to storybook that match our tailwind breakpoints (like we have in www-frontend) fixing theme choices for stories that have full width canvas in docs adding some examples to component docs, fixing fancybox caption to strip html improvements to BlockImage documentation and stories Update Components overview Add links to example components in Components overview

…ents. Also adding addon-links to link to other stories from the react components adding custom inline rendering in DocsPages using custom react components. Also adding addon-links to link to other stories from the react components, adding TOC to base components overview page. adding custom doc component to all overview pages

showing all baselink stories on docs page

improvements to react doc blocks components Add block component descriptions, story max-width 1082, etc. setting a max-width on sbdocs-content so full width canvas doc blocks have some kind of boundary, but still a wider than the design system's max-width to allow for demonstrating how the design system's max-width works fixing height on story doc blocks in react components, removing now unnecessary canvasClass values on some doc blocks, adjustments to BlockIframeEmbed story for consistency with BlockVideoEmbed, adding a placeholder div for react doc blocks that hide the story canvas (BlockIframeEmbed) cleaning up overview docs pages, cleaning up comparison between blocks and base components, adding more docs about page layout adjusting max-width of docs divs to a more readable width, changing width of BlockImageGallery story block

updating one more instance of ArticleCarousel in the docs

Scotchester · 2022-02-02T15:27:48Z

Confirmed that everything still looks good after the rebase. Mergin' time!

stephiescastle added documentation Improvements or additions to documentation storybook This issue relates to Storybook.js minor Contains new features or enhancements labels Feb 1, 2022

stephiescastle marked this pull request as draft February 1, 2022 22:43

stephiescastle marked this pull request as ready for review February 1, 2022 22:58

Scotchester approved these changes Feb 1, 2022

View reviewed changes

stephiescastle and others added 13 commits February 1, 2022 17:01

adding a temporary workaround script to automatically expand first no…

4cece19

…de within an expanded group

including primary story in list of all stories on docs page for BaseB…

40e69d5

…utton and Icons. Requires @babel/preset-react

fixing BaseCarouselCards navigation breakpoint to match space between…

e8608b0

… cards

adding an overview for heroes, fixing docs view for some heroes, upda…

bc96661

…ting order in preview.js fixing HeroMedia story height in docs view, adds a couple more utility classes to override story height, similar to sbdocs-preview-full-width

setting inlineStories to false on stories that need to use an iframe,…

4e82e78

… fixes docs view for carousels, tweaks HeroMedia to use the same method to set story height in docs view

removing storyRoot decorator from stories that don't need it

738df96

showing all heading levels on the BaseHeading docs page

ec21022

showing all baselink stories on docs page

Rename ArticleCarousel to BlockArticleCarousel

7d51f3b

updating one more instance of ArticleCarousel in the docs

updating package-lock after rebase

b777605

stephiescastle force-pushed the docs/components-base-vs-block branch from 144980f to b777605 Compare February 2, 2022 01:32

Scotchester merged commit d1550cf into main Feb 2, 2022

Scotchester deleted the docs/components-base-vs-block branch February 2, 2022 15:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Storybook: cleaning up component organization and adding a table of contents for each component section #133

Storybook: cleaning up component organization and adding a table of contents for each component section #133

stephiescastle commented Feb 1, 2022 •

edited

Loading

Scotchester left a comment •

edited

Loading

Scotchester commented Feb 2, 2022

Storybook: cleaning up component organization and adding a table of contents for each component section #133

Storybook: cleaning up component organization and adding a table of contents for each component section #133

Conversation

stephiescastle commented Feb 1, 2022 • edited Loading

Checklist

Description

Migration Guide

Instructions to test

Tested in the following environments/browsers:

Operating System

Browser

Scotchester left a comment • edited Loading

Choose a reason for hiding this comment

Scotchester commented Feb 2, 2022

stephiescastle commented Feb 1, 2022 •

edited

Loading

Scotchester left a comment •

edited

Loading