Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FontSizePicker: Refactor stories to use Controls #38727

Merged
merged 7 commits into from
Mar 2, 2022

Conversation

mirka
Copy link
Member

@mirka mirka commented Feb 11, 2022

Part of #35665
In preparation for #38720

Description

Refactors the FontSizePicker stories to use Controls instead of Knobs, and reworks some of the stories for clarity and correctness.

Reworked stories

  • "With Slider"
    • [Bug fix] The fallbackFontSize prop only kicks in when initialValue is 0 or undefined, but this was not set correctly so it wasn't showcasing the fallback behavior.
  • "Different Control By Size"
    • This was split into two stories ("With More Font Sizes" and "With Units") for clarity.
    • [Bug fix] The "With Units" case was setting an initialValue of 8 instead of 8px, thus showcasing a custom value by default.
  • "With Complex CSS Values"
    • Simplified so it doesn't require Storybook-only toggles.

I tried not to drop any of the intent captured in the original stories — let me know if I missed something.

Testing Instructions

  1. npm run storybook:dev and see the stories for FontSizePicker.
  2. Compare with the ones on https://wordpress.github.io/gutenberg/?path=/story/components-fontsizepicker--default

Pro tip: Knobs can be kind of buggy when you click through multiple stories. Click the "Reset" button in the bottom right corner if they get stuck.

Types of changes

Storybook only.

Checklist:

  • My code is tested.
  • My code follows the WordPress code style.
  • My code follows the accessibility standards.
  • I've tested my changes with keyboard and screen readers.
  • My code has proper inline documentation.
  • I've included developer documentation if appropriate.
  • I've updated all React Native files affected by any refactorings/renamings in this PR (please manually search all *.native.js files for terms that need renaming or removal).
  • I've updated related schemas if appropriate.

@mirka mirka added [Package] Components /packages/components Storybook Storybook and its stories for components labels Feb 11, 2022
@mirka mirka self-assigned this Feb 11, 2022
@github-actions
Copy link

github-actions bot commented Feb 11, 2022

Size Change: +1.09 kB (0%)

Total Size: 1.15 MB

Filename Size Change
build/admin-manifest/index.min.js 1.24 kB +114 B (+10%) ⚠️
build/api-fetch/index.min.js 2.27 kB +21 B (+1%)
build/block-directory/index.min.js 6.49 kB +181 B (+3%)
build/block-editor/index.min.js 143 kB +1.32 kB (+1%)
build/block-editor/style-rtl.css 14.8 kB -16 B (0%)
build/block-editor/style.css 14.8 kB -16 B (0%)
build/block-library/blocks/button/editor-rtl.css 445 B -25 B (-5%)
build/block-library/blocks/button/editor.css 445 B -25 B (-5%)
build/block-library/blocks/code/style-rtl.css 103 B +13 B (+14%) ⚠️
build/block-library/blocks/code/style.css 103 B +13 B (+14%) ⚠️
build/block-library/blocks/code/theme-rtl.css 124 B -7 B (-5%)
build/block-library/blocks/code/theme.css 124 B -7 B (-5%)
build/block-library/blocks/cover/style-rtl.css 1.56 kB +10 B (+1%)
build/block-library/blocks/cover/style.css 1.56 kB +10 B (+1%)
build/block-library/blocks/image/editor-rtl.css 731 B -79 B (-10%) 👏
build/block-library/blocks/image/editor.css 730 B -79 B (-10%) 👏
build/block-library/blocks/image/style-rtl.css 518 B +18 B (+4%)
build/block-library/blocks/image/style.css 523 B +20 B (+4%)
build/block-library/blocks/navigation/editor-rtl.css 2.01 kB +33 B (+2%)
build/block-library/blocks/navigation/editor.css 2.02 kB +33 B (+2%)
build/block-library/blocks/navigation/style-rtl.css 1.89 kB +44 B (+2%)
build/block-library/blocks/navigation/style.css 1.88 kB +41 B (+2%)
build/block-library/blocks/page-list/editor-rtl.css 363 B -38 B (-9%)
build/block-library/blocks/page-list/editor.css 363 B -39 B (-10%) 👏
build/block-library/blocks/tag-cloud/style-rtl.css 226 B +12 B (+6%) 🔍
build/block-library/blocks/tag-cloud/style.css 227 B +12 B (+6%) 🔍
build/block-library/blocks/template-part/editor-rtl.css 235 B -325 B (-58%) 🏆
build/block-library/blocks/template-part/editor.css 235 B -324 B (-58%) 🏆
build/block-library/common-rtl.css 934 B +13 B (+1%)
build/block-library/common.css 932 B +13 B (+1%)
build/block-library/editor-rtl.css 9.89 kB -235 B (-2%)
build/block-library/editor.css 9.9 kB -234 B (-2%)
build/block-library/index.min.js 167 kB -347 B (0%)
build/block-library/style-rtl.css 11.4 kB +93 B (+1%)
build/block-library/style.css 11.4 kB +93 B (+1%)
build/block-library/theme-rtl.css 665 B -7 B (-1%)
build/block-library/theme.css 670 B -6 B (-1%)
build/blocks/index.min.js 46.4 kB -1 B (0%)
build/components/index.min.js 215 kB -184 B (0%)
build/components/style-rtl.css 15.6 kB +31 B (0%)
build/components/style.css 15.6 kB +32 B (0%)
build/compose/index.min.js 11.2 kB +16 B (0%)
build/core-data/index.min.js 13.9 kB +549 B (+4%)
build/customize-widgets/index.min.js 11.2 kB -215 B (-2%)
build/customize-widgets/style-rtl.css 1.39 kB -106 B (-7%)
build/customize-widgets/style.css 1.39 kB -105 B (-7%)
build/data/index.min.js 7.57 kB +90 B (+1%)
build/dom/index.min.js 4.53 kB +4 B (0%)
build/edit-navigation/index.min.js 16.2 kB -12 B (0%)
build/edit-post/index.min.js 29.8 kB -202 B (-1%)
build/edit-post/style-rtl.css 7.14 kB -28 B (0%)
build/edit-post/style.css 7.13 kB -28 B (0%)
build/edit-site/index.min.js 42.1 kB +197 B (0%)
build/edit-site/style-rtl.css 7.23 kB +12 B (0%)
build/edit-site/style.css 7.22 kB +13 B (0%)
build/edit-widgets/index.min.js 16.5 kB -178 B (-1%)
build/edit-widgets/style-rtl.css 4.12 kB -44 B (-1%)
build/edit-widgets/style.css 4.13 kB -42 B (-1%)
build/editor/index.min.js 38.5 kB +7 B (0%)
build/element/index.min.js 4.29 kB +971 B (+29%) 🚨
build/nux/style-rtl.css 751 B +4 B (+1%)
build/nux/style.css 749 B +6 B (+1%)
build/reusable-blocks/index.min.js 2.24 kB -11 B (0%)
build/url/index.min.js 1.94 kB +16 B (+1%)
ℹ️ View Unchanged
Filename Size
build/a11y/index.min.js 993 B
build/annotations/index.min.js 2.77 kB
build/autop/index.min.js 2.15 kB
build/blob/index.min.js 487 B
build/block-directory/style-rtl.css 1.01 kB
build/block-directory/style.css 1.01 kB
build/block-editor/default-editor-styles-rtl.css 378 B
build/block-editor/default-editor-styles.css 378 B
build/block-library/blocks/archives/editor-rtl.css 61 B
build/block-library/blocks/archives/editor.css 60 B
build/block-library/blocks/archives/style-rtl.css 65 B
build/block-library/blocks/archives/style.css 65 B
build/block-library/blocks/audio/editor-rtl.css 150 B
build/block-library/blocks/audio/editor.css 150 B
build/block-library/blocks/audio/style-rtl.css 111 B
build/block-library/blocks/audio/style.css 111 B
build/block-library/blocks/audio/theme-rtl.css 125 B
build/block-library/blocks/audio/theme.css 125 B
build/block-library/blocks/block/editor-rtl.css 161 B
build/block-library/blocks/block/editor.css 161 B
build/block-library/blocks/button/style-rtl.css 560 B
build/block-library/blocks/button/style.css 560 B
build/block-library/blocks/buttons/editor-rtl.css 292 B
build/block-library/blocks/buttons/editor.css 292 B
build/block-library/blocks/buttons/style-rtl.css 275 B
build/block-library/blocks/buttons/style.css 275 B
build/block-library/blocks/calendar/style-rtl.css 207 B
build/block-library/blocks/calendar/style.css 207 B
build/block-library/blocks/categories/editor-rtl.css 84 B
build/block-library/blocks/categories/editor.css 83 B
build/block-library/blocks/categories/style-rtl.css 79 B
build/block-library/blocks/categories/style.css 79 B
build/block-library/blocks/columns/editor-rtl.css 108 B
build/block-library/blocks/columns/editor.css 108 B
build/block-library/blocks/columns/style-rtl.css 406 B
build/block-library/blocks/columns/style.css 406 B
build/block-library/blocks/comment-author-avatar/editor-rtl.css 125 B
build/block-library/blocks/comment-author-avatar/editor.css 125 B
build/block-library/blocks/comment-template/style-rtl.css 127 B
build/block-library/blocks/comment-template/style.css 127 B
build/block-library/blocks/comments-pagination-numbers/editor-rtl.css 123 B
build/block-library/blocks/comments-pagination-numbers/editor.css 121 B
build/block-library/blocks/comments-pagination/editor-rtl.css 222 B
build/block-library/blocks/comments-pagination/editor.css 209 B
build/block-library/blocks/comments-pagination/style-rtl.css 235 B
build/block-library/blocks/comments-pagination/style.css 231 B
build/block-library/blocks/comments-query-loop/editor-rtl.css 95 B
build/block-library/blocks/comments-query-loop/editor.css 95 B
build/block-library/blocks/cover/editor-rtl.css 546 B
build/block-library/blocks/cover/editor.css 547 B
build/block-library/blocks/embed/editor-rtl.css 293 B
build/block-library/blocks/embed/editor.css 293 B
build/block-library/blocks/embed/style-rtl.css 417 B
build/block-library/blocks/embed/style.css 417 B
build/block-library/blocks/embed/theme-rtl.css 124 B
build/block-library/blocks/embed/theme.css 124 B
build/block-library/blocks/file/editor-rtl.css 300 B
build/block-library/blocks/file/editor.css 300 B
build/block-library/blocks/file/style-rtl.css 255 B
build/block-library/blocks/file/style.css 255 B
build/block-library/blocks/file/view.min.js 353 B
build/block-library/blocks/freeform/editor-rtl.css 2.44 kB
build/block-library/blocks/freeform/editor.css 2.44 kB
build/block-library/blocks/gallery/editor-rtl.css 965 B
build/block-library/blocks/gallery/editor.css 967 B
build/block-library/blocks/gallery/style-rtl.css 1.61 kB
build/block-library/blocks/gallery/style.css 1.61 kB
build/block-library/blocks/gallery/theme-rtl.css 122 B
build/block-library/blocks/gallery/theme.css 122 B
build/block-library/blocks/group/editor-rtl.css 159 B
build/block-library/blocks/group/editor.css 159 B
build/block-library/blocks/group/style-rtl.css 57 B
build/block-library/blocks/group/style.css 57 B
build/block-library/blocks/group/theme-rtl.css 78 B
build/block-library/blocks/group/theme.css 78 B
build/block-library/blocks/heading/style-rtl.css 114 B
build/block-library/blocks/heading/style.css 114 B
build/block-library/blocks/html/editor-rtl.css 332 B
build/block-library/blocks/html/editor.css 333 B
build/block-library/blocks/image/theme-rtl.css 124 B
build/block-library/blocks/image/theme.css 124 B
build/block-library/blocks/latest-comments/style-rtl.css 284 B
build/block-library/blocks/latest-comments/style.css 284 B
build/block-library/blocks/latest-posts/editor-rtl.css 199 B
build/block-library/blocks/latest-posts/editor.css 198 B
build/block-library/blocks/latest-posts/style-rtl.css 447 B
build/block-library/blocks/latest-posts/style.css 446 B
build/block-library/blocks/list/style-rtl.css 94 B
build/block-library/blocks/list/style.css 94 B
build/block-library/blocks/media-text/editor-rtl.css 266 B
build/block-library/blocks/media-text/editor.css 263 B
build/block-library/blocks/media-text/style-rtl.css 493 B
build/block-library/blocks/media-text/style.css 490 B
build/block-library/blocks/more/editor-rtl.css 431 B
build/block-library/blocks/more/editor.css 431 B
build/block-library/blocks/navigation-link/editor-rtl.css 649 B
build/block-library/blocks/navigation-link/editor.css 650 B
build/block-library/blocks/navigation-link/style-rtl.css 94 B
build/block-library/blocks/navigation-link/style.css 94 B
build/block-library/blocks/navigation-submenu/editor-rtl.css 299 B
build/block-library/blocks/navigation-submenu/editor.css 299 B
build/block-library/blocks/navigation-submenu/view.min.js 375 B
build/block-library/blocks/navigation/view.min.js 2.85 kB
build/block-library/blocks/nextpage/editor-rtl.css 395 B
build/block-library/blocks/nextpage/editor.css 395 B
build/block-library/blocks/page-list/style-rtl.css 175 B
build/block-library/blocks/page-list/style.css 175 B
build/block-library/blocks/paragraph/editor-rtl.css 157 B
build/block-library/blocks/paragraph/editor.css 157 B
build/block-library/blocks/paragraph/style-rtl.css 273 B
build/block-library/blocks/paragraph/style.css 273 B
build/block-library/blocks/post-author/style-rtl.css 175 B
build/block-library/blocks/post-author/style.css 176 B
build/block-library/blocks/post-comments-form/style-rtl.css 446 B
build/block-library/blocks/post-comments-form/style.css 446 B
build/block-library/blocks/post-comments/style-rtl.css 521 B
build/block-library/blocks/post-comments/style.css 521 B
build/block-library/blocks/post-excerpt/editor-rtl.css 73 B
build/block-library/blocks/post-excerpt/editor.css 73 B
build/block-library/blocks/post-excerpt/style-rtl.css 69 B
build/block-library/blocks/post-excerpt/style.css 69 B
build/block-library/blocks/post-featured-image/editor-rtl.css 721 B
build/block-library/blocks/post-featured-image/editor.css 721 B
build/block-library/blocks/post-featured-image/style-rtl.css 153 B
build/block-library/blocks/post-featured-image/style.css 153 B
build/block-library/blocks/post-template/editor-rtl.css 99 B
build/block-library/blocks/post-template/editor.css 98 B
build/block-library/blocks/post-template/style-rtl.css 323 B
build/block-library/blocks/post-template/style.css 323 B
build/block-library/blocks/post-terms/style-rtl.css 73 B
build/block-library/blocks/post-terms/style.css 73 B
build/block-library/blocks/post-title/style-rtl.css 80 B
build/block-library/blocks/post-title/style.css 80 B
build/block-library/blocks/preformatted/style-rtl.css 103 B
build/block-library/blocks/preformatted/style.css 103 B
build/block-library/blocks/pullquote/editor-rtl.css 198 B
build/block-library/blocks/pullquote/editor.css 198 B
build/block-library/blocks/pullquote/style-rtl.css 389 B
build/block-library/blocks/pullquote/style.css 388 B
build/block-library/blocks/pullquote/theme-rtl.css 167 B
build/block-library/blocks/pullquote/theme.css 167 B
build/block-library/blocks/query-pagination-numbers/editor-rtl.css 122 B
build/block-library/blocks/query-pagination-numbers/editor.css 121 B
build/block-library/blocks/query-pagination/editor-rtl.css 221 B
build/block-library/blocks/query-pagination/editor.css 211 B
build/block-library/blocks/query-pagination/style-rtl.css 234 B
build/block-library/blocks/query-pagination/style.css 231 B
build/block-library/blocks/query/editor-rtl.css 131 B
build/block-library/blocks/query/editor.css 132 B
build/block-library/blocks/quote/style-rtl.css 201 B
build/block-library/blocks/quote/style.css 201 B
build/block-library/blocks/quote/theme-rtl.css 223 B
build/block-library/blocks/quote/theme.css 226 B
build/block-library/blocks/read-more/style-rtl.css 132 B
build/block-library/blocks/read-more/style.css 132 B
build/block-library/blocks/rss/editor-rtl.css 202 B
build/block-library/blocks/rss/editor.css 204 B
build/block-library/blocks/rss/style-rtl.css 289 B
build/block-library/blocks/rss/style.css 288 B
build/block-library/blocks/search/editor-rtl.css 165 B
build/block-library/blocks/search/editor.css 165 B
build/block-library/blocks/search/style-rtl.css 397 B
build/block-library/blocks/search/style.css 398 B
build/block-library/blocks/search/theme-rtl.css 64 B
build/block-library/blocks/search/theme.css 64 B
build/block-library/blocks/separator/editor-rtl.css 99 B
build/block-library/blocks/separator/editor.css 99 B
build/block-library/blocks/separator/style-rtl.css 233 B
build/block-library/blocks/separator/style.css 233 B
build/block-library/blocks/separator/theme-rtl.css 172 B
build/block-library/blocks/separator/theme.css 172 B
build/block-library/blocks/shortcode/editor-rtl.css 474 B
build/block-library/blocks/shortcode/editor.css 474 B
build/block-library/blocks/site-logo/editor-rtl.css 744 B
build/block-library/blocks/site-logo/editor.css 744 B
build/block-library/blocks/site-logo/style-rtl.css 181 B
build/block-library/blocks/site-logo/style.css 181 B
build/block-library/blocks/site-tagline/editor-rtl.css 86 B
build/block-library/blocks/site-tagline/editor.css 86 B
build/block-library/blocks/site-title/editor-rtl.css 84 B
build/block-library/blocks/site-title/editor.css 84 B
build/block-library/blocks/social-link/editor-rtl.css 177 B
build/block-library/blocks/social-link/editor.css 177 B
build/block-library/blocks/social-links/editor-rtl.css 674 B
build/block-library/blocks/social-links/editor.css 673 B
build/block-library/blocks/social-links/style-rtl.css 1.37 kB
build/block-library/blocks/social-links/style.css 1.36 kB
build/block-library/blocks/spacer/editor-rtl.css 332 B
build/block-library/blocks/spacer/editor.css 332 B
build/block-library/blocks/spacer/style-rtl.css 48 B
build/block-library/blocks/spacer/style.css 48 B
build/block-library/blocks/table/editor-rtl.css 471 B
build/block-library/blocks/table/editor.css 472 B
build/block-library/blocks/table/style-rtl.css 481 B
build/block-library/blocks/table/style.css 481 B
build/block-library/blocks/table/theme-rtl.css 188 B
build/block-library/blocks/table/theme.css 188 B
build/block-library/blocks/template-part/theme-rtl.css 101 B
build/block-library/blocks/template-part/theme.css 101 B
build/block-library/blocks/text-columns/editor-rtl.css 95 B
build/block-library/blocks/text-columns/editor.css 95 B
build/block-library/blocks/text-columns/style-rtl.css 166 B
build/block-library/blocks/text-columns/style.css 166 B
build/block-library/blocks/verse/style-rtl.css 87 B
build/block-library/blocks/verse/style.css 87 B
build/block-library/blocks/video/editor-rtl.css 571 B
build/block-library/blocks/video/editor.css 572 B
build/block-library/blocks/video/style-rtl.css 173 B
build/block-library/blocks/video/style.css 173 B
build/block-library/blocks/video/theme-rtl.css 124 B
build/block-library/blocks/video/theme.css 124 B
build/block-library/reset-rtl.css 474 B
build/block-library/reset.css 474 B
build/block-serialization-default-parser/index.min.js 1.12 kB
build/block-serialization-spec-parser/index.min.js 2.83 kB
build/data-controls/index.min.js 663 B
build/date/index.min.js 31.9 kB
build/deprecated/index.min.js 518 B
build/dom-ready/index.min.js 336 B
build/edit-navigation/style-rtl.css 3.76 kB
build/edit-navigation/style.css 3.76 kB
build/edit-post/classic-rtl.css 546 B
build/edit-post/classic.css 547 B
build/editor/style-rtl.css 3.71 kB
build/editor/style.css 3.71 kB
build/escape-html/index.min.js 548 B
build/format-library/index.min.js 6.62 kB
build/format-library/style-rtl.css 571 B
build/format-library/style.css 571 B
build/hooks/index.min.js 1.66 kB
build/html-entities/index.min.js 454 B
build/i18n/index.min.js 3.79 kB
build/is-shallow-equal/index.min.js 535 B
build/keyboard-shortcuts/index.min.js 1.83 kB
build/keycodes/index.min.js 1.41 kB
build/list-reusable-blocks/index.min.js 1.75 kB
build/list-reusable-blocks/style-rtl.css 838 B
build/list-reusable-blocks/style.css 838 B
build/media-utils/index.min.js 2.94 kB
build/notices/index.min.js 957 B
build/nux/index.min.js 2.12 kB
build/plugins/index.min.js 1.98 kB
build/preferences/index.min.js 1.2 kB
build/primitives/index.min.js 949 B
build/priority-queue/index.min.js 611 B
build/react-i18n/index.min.js 704 B
build/react-refresh-entry/index.min.js 8.44 kB
build/react-refresh-runtime/index.min.js 7.31 kB
build/redux-routine/index.min.js 2.69 kB
build/reusable-blocks/style-rtl.css 256 B
build/reusable-blocks/style.css 256 B
build/rich-text/index.min.js 11.1 kB
build/server-side-render/index.min.js 1.61 kB
build/shortcode/index.min.js 1.52 kB
build/token-list/index.min.js 668 B
build/viewport/index.min.js 1.08 kB
build/warning/index.min.js 280 B
build/widgets/index.min.js 7.18 kB
build/widgets/style-rtl.css 1.16 kB
build/widgets/style.css 1.16 kB
build/wordcount/index.min.js 1.07 kB

compressed-size-action

Copy link
Contributor

@ciampo ciampo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @mirka , this is a great refactor!

Not directly a consequence of this PR, but I got confused when toggling the withReset prop — even when true, the reset button is only shown when enabling a custom size while not showing a slider:

  • the docs for the prop are not very clear to me: "If true, a reset button will be displayed alongside the predefined and custom font size fields.". Should we update them?
  • We should probably add a similar sentence as a note to the Storybook toggle, to avoid further confusion

Also looking forward to having @ntsekouras and @aaronrobertshaw take a look at this too.

Copy link
Contributor

@ntsekouras ntsekouras left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the PR @mirka !

the docs for the prop are not very clear to me: "If true, a reset button will be displayed alongside the predefined and custom font size fields.". Should we update them?

Yes, we should do that! It through me off at first and had to carefully read the code again to see what is expected and what's not 😄

In general I like the direction of this, but I'm wondering if we should revisit what stories we should show now. Previously with the knobs, not all properties were editable and were there to show case some combinations - thus @ciampo 's confusion (and mine) with the reset or disableCustomFontSizes, etc..

I think we can reduce the stories shown here and combine them by changing some names. For example WithoutCustomSizes story is identical with the default except on property, but by being able to edit the props it starts being confusing.

Maybe it makes sense to always show the fewer/more font sizes? 🤔
Alternatively we could disable some controls to mimic the previous behavior.

What do you think?

Copy link
Contributor

@aaronrobertshaw aaronrobertshaw left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for getting this refactor started @mirka 👍

All the font size picker examples work as advertised for me.

@ntsekouras raises some good points though. I think for a lot of components we could combine examples however for others it makes sense to demonstrate a certain configuration and behaviour. Allowing all props to be edited in these scenarios definitely adds confusion and doesn't seem right.

I'd also like to see some examples being clearer in what they are supposed to demonstrate. One example of this could be "With Complex CSS Values". I'm not sure someone looking at these for the first time would pick that the difference between this example and "With Units" is the labelling of the segmented control. Could we communicate this better within the example even if just with some help text below it explaining/highlighting the demonstrated behaviour?

These aren't issues specifically with this PR of course however it would be good to form a consensus plan here so it can be followed for other components.

@mirka
Copy link
Member Author

mirka commented Feb 18, 2022

Thanks for all the feedback, you all raise very good points — the main sentiment being that it's hard to understand what the props do or what the stories are trying to demonstrate. I went back and did some thinking on how we should be approaching Storybook, and the ideas are discussed in #38842.

Based on that, I think the direction we’ll be pursuing is to make Docs view (instead of Canvas view) the primary focus of our Storybook. Once a component is written in TypeScript, the docgen will not only extract all the prop data into a table, but also auto-generate the Controls for every prop. That is super convenient, but also that alone would perhaps make some stories overwhelming to understand.

However, in Docs view we can show descriptions and actual code snippets for each story, which is actually more useful to most devs than having just a curated set of Controls to tinker with. The Canvas view would instead be more of a place to do advanced tinkering, with all the Controls present.

While FontSizePicker is not in TypeScript yet, I made some changes with that eventuality in mind:

  • Make code snippets visible in Docs view, and checked that they were understandable.
  • Manually added descriptions to confusing props. (This will be automatic when the component is converted to TS)
  • Added descriptions to some stories to clarify what they were trying to demonstrate.

How does it feel now?

CleanShot.2022-02-19.at.03.58.59.mp4

Comment on lines 99 to 105
WithCustomSizesDisabled.parameters = {
docs: {
description: {
story:
'When disabled, the user will only be able to pick one of the predefined sizes passed in `fontSizes`.',
},
] );
return (
<FontSizePickerWithState
fontSizes={ fontSizes }
disableCustomFontSizes
/>
);
},
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is kind of verbose for just wanting to set a story description, so I'm thinking of using a webpack loader that lets you write the description as a normal JSDoc comment.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think there's any chance of breaking our story description in case Storybook updates their APIs? The webpack loader that you linked to hasn't been updated in more than a year

Anyway, we can definitely experiment with it in a separate PR! (although definitely not high priority as it's just a minor improvement)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The loader code is pretty trivial and there's a reasonable chance that it will become a built-in feature, so I'm not too concerned about that. I might even try keeping the loader code local, rather than as an external dep.

Copy link
Contributor

@ciampo ciampo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the direction we’ll be pursuing is to make Docs view (instead of Canvas view) the primary focus of our Storybook.
...
The Canvas view would instead be more of a place to do advanced tinkering, with all the Controls present.

I also think that this is the right direction to take

Once a component is written in TypeScript, the docgen will not only extract all the prop data into a table, but also auto-generate the Controls for every prop. That is super convenient, but also that alone would perhaps make some stories overwhelming to understand.

Those considerations are all correct, and (as discussed in #38842) I think we can mitigate the potentially overwhelming amount of props / controls in a few ways (e.g. sorting, grouping..)

While FontSizePicker is not in TypeScript yet, I made some changes with that eventuality in mind:

  • Make code snippets visible in Docs view, and checked that they were understandable.
  • Manually added descriptions to confusing props. (This will be automatic when the component is converted to TS)
  • Added descriptions to some stories to clarify what they were trying to demonstrate.

How does it feel now?

I think it's much better already! Although it's probably wiser to hear at least @ntsekouras 's opinion too before merging (I know Aaron may be AFK for a while)

Also, is it expected that the header hint in the "With Units" Story only has the unit (px) in the toggle-group version of the picker, but has the quantity + the unit (12px) in the dropdown-version?

Screenshot 2022-02-23 at 19 10 54

Finally — should we mention the stories rework (and the couple of bug fixes) in a CHANGELOG entry?

packages/components/src/font-size-picker/stories/index.js Outdated Show resolved Hide resolved
Comment on lines 99 to 105
WithCustomSizesDisabled.parameters = {
docs: {
description: {
story:
'When disabled, the user will only be able to pick one of the predefined sizes passed in `fontSizes`.',
},
] );
return (
<FontSizePickerWithState
fontSizes={ fontSizes }
disableCustomFontSizes
/>
);
},
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think there's any chance of breaking our story description in case Storybook updates their APIs? The webpack loader that you linked to hasn't been updated in more than a year

Anyway, we can definitely experiment with it in a separate PR! (although definitely not high priority as it's just a minor improvement)

@ntsekouras
Copy link
Contributor

Also, is it expected that the header hint in the "With Units" Story only has the unit (px) in the toggle-group version of the picker, but has the quantity + the unit (12px) in the dropdown-version?

Yes. The same information is displayed in different places (hint, labels, etc..).

Copy link
Contributor

@ntsekouras ntsekouras left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @mirka! That's so much better now with all the descriptions and hints! Great work 🚀

Co-authored-by: Marco Ciampini <marco.ciampo@gmail.com>
@mirka mirka merged commit 3041b45 into trunk Mar 2, 2022
@mirka mirka deleted the refactor/font-size-picker-story branch March 2, 2022 11:35
@github-actions github-actions bot added this to the Gutenberg 12.8 milestone Mar 2, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Package] Components /packages/components Storybook Storybook and its stories for components
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants