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

Storybook: Add and Update Block Editor Components stories #67165

Open
miminari opened this issue Nov 20, 2024 · 12 comments
Open

Storybook: Add and Update Block Editor Components stories #67165

miminari opened this issue Nov 20, 2024 · 12 comments
Labels
Good First Issue An issue that's suitable for someone looking to contribute for the first time Storybook Storybook and its stories for components [Type] Developer Documentation Documentation for developers [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues.

Comments

@miminari
Copy link
Member

miminari commented Nov 20, 2024

What problem does this address?

Most of Block Editor components don't have stories.
Block Editor components's Storybook should also be added and updated like the Components.
related #22891

What is your proposed solution?

We can use this issue to track the addition and updating of the stories for Block Editor.
You can add the link to assign yourself to each component.
As I know, Block Editor Components list has never existed, so at first, we can start to be based on the directory name.
The list was made automatically, and we can ignore the component for native only.

If you cannot edit the list, please comment on which you made the PR for which directory's components.

cc @WordPress/gutenberg-components

Block Editor Components directories List

  • alignment-control Storybook: Add stories for AlignmentToolbar and AlignmentControl components #67046
    • AlignmentControl
    • AlignmentToolbar
  • audio-player (for native only)
  • autocomplete (BlockEditorAutocomplete based on Autocomplete from @wordpress/components. Pending until the Autocomplete component's stories are made.)
  • background-image-control/BackgroundImagePanel Add story for BackgroundImagePanel #67184
  • block-actions
  • block-alignment-control Storybook: Add stories for BlockAlignmentControl and BlockAlignmentToolbar components #67233
    • BlockAlignmentControl
    • BlockAlignmentToolbar
  • block-alignment-matrix-control (Has __experimental prefix) Storybook: Add stories for BlockAlignmentMatrixControl Component #67292
  • block-breadcrumb
  • block-canvas
  • block-caption (for native only)
  • block-card Storybook: Add stories for BlockCard component #67191
  • block-compare
  • block-content-overlay (Has __experimental prefix)
  • block-context
  • block-controls
    • BlockControls
    • BlockFormatControls
  • block-draggable
  • block-edit
  • block-edit-visually-button
  • block-editing-mode (Reack Hook)
  • block-full-height-alignment-control (Has __experimental prefix) Add Storybook story for BlockFullHeightAlignmentControl #67227
  • block-heading-level-dropdown Storybook: Add stories for HeadingLevelDropdown component #67294
  • block-icon Add BlockIcon Storybook stories #67186
  • block-info-slot-fill
  • block-inspector
  • block-list
  • block-list-appender
  • block-lock
  • block-media-update-progress (for native only)
  • block-mover Update BlockMover Stories and README #66519
  • block-navigation
  • block-parent-selector
  • block-pattern-setup (Has __experimental prefix)
  • block-patterns-list (Has __experimental prefix)
  • block-patterns-paging
  • block-popover
  • block-preview
  • block-quick-navigation
  • block-removal-warning-modal
  • block-rename Story Book: Add BlockRenameControl Story #67386
  • block-selection-clearer
  • block-settings (for native only)
  • block-settings-menu
    • BlockSettingsMenu
    • __unstableBlockSettingsMenuFirstItem (Has __unstable prefix)
  • block-settings-menu-controls
  • block-styles
  • block-switcher
  • block-title Storybook: Add stories for BlockTitle Component #67234
  • block-toolbar
    • __unstableBlockToolbarLastItem (Has __unstable prefix)
    • __unstableBlockToolbarLastItem (Has __unstable prefix)
  • block-tools
  • block-types-list
  • block-variation-picker (Has __experimental prefix)
  • block-variation-transforms (Has __experimental prefix)
  • block-vertical-alignment-control
    • BlockVerticalAlignmentToolbar
    • BlockVerticalAlignmentControl
  • border-radius-control (Has __experimental prefix) Storybook: Add BorderRadiusControl story #67383
  • button-block-appender
  • caption (for native only)
  • child-layout-control
  • collab
  • color-palette Storybook: ColorPaletteControl #67846
    • ColorPalette
    • ColorPaletteControl
  • color-style-selector
  • colors
  • colors-gradients (Has __experimental prefix)
    • __experimentalColorGradientControl
    • __experimentalColorGradientSettingsDropdown
    • __experimentalPanelColorGradientSettings
  • content-lock
  • contrast-checker
  • convert-to-group-buttons
  • copy-handler
  • date-format-picker (Has __experimental prefix) Storybook: Add stories for DateFormatPicker Component #67290
  • default-block-appender
  • dimensions-tool
  • duotone
  • duotone-control (Has __experimental prefix)
  • editable-text
  • editor-styles (Has __unstable prefix)
  • floating-toolbar
  • font-appearance-control (Has __experimental prefix)
  • font-family (Has __experimental prefix)
  • font-sizes
  • global-styles
  • gradients
  • grid
  • height-control
  • iframe (Has __unstable prefix)
  • image-editor (Has __experimental prefix)
  • image-link-destinations (for native only)
  • image-size-control (Has __experimental prefix)
  • index.js
  • index.native.js
  • inner-blocks
  • inserter
    • _Inserter
    • __experimentalLibrary (Has __experimental prefix)
  • inserter-button (for native only)
  • inserter-draggable-blocks
  • inserter-list-item
  • inserter-listbox
  • inserter-menu-extension (Has __experimental prefix)
  • inspector-controls
    • InspectorControls
    • InspectorAdvancedControls
  • inspector-controls-tabs
  • inspector-popover-header (Has __experimental prefix)
  • justify-content-control
    • JustifyToolbar
    • JustifyContentControl
  • keyboard-shortcuts
  • letter-spacing-control (Has __experimental prefix) Storybook: Add LetterSpacingControl story #67342
  • line-height-control
  • link-control
    • LinkControl
    • __experimentalLinkControl (Has __experimental prefix)
    • __experimentalLinkControlSearchInput (Has __experimental prefix)
    • __experimentalLinkControlSearchResults (Has __experimental prefix)
    • __experimentalLinkControlSearchItem (Has __experimental prefix)
  • list-view (Has __experimental prefix)
  • media-placeholder
  • media-replace-flow
  • media-upload
    • MediaUpload
    • MediaUploadCheck
  • media-upload-progress (for native only)
  • multi-selection-inspector
  • navigable-toolbar
  • observe-typing
  • panel-color-settings
  • plain-text Storybook: Add PlainText Storybook stories #67341
  • preview-options (Has __experimental prefix)
  • provider
  • publish-date-time-picker (Has __experimental prefix)
  • recursion-provider
  • resizable-box-popover
  • resolution-tool
  • responsive-block-control (Has __experimental prefix)
  • rich-text
    • RichText
    • RichTextShortcut
    • RichTextToolbarButton
  • selection-scroll-into-view
  • skip-to-selected-block
  • spacing-sizes-control (Has __experimental prefix)
  • tabbed-sidebar
  • text-alignment-control Storybook: Add stories for the TextAlignmentControl component #67371
  • text-decoration-control (Has __experimental prefix) Storybook: Add stories for the TextDecorationControl component #67337
  • text-transform-control (Has __experimental prefix) Storybook : Add TextTransformControl stories #67365
  • tool-selector
  • typewriter
  • ungroup-button
  • unit-control (Has __experimental prefix) Storybook: Add UnitControl story #67346
  • unsupported-block-details
  • url-input
    • URLInput
    • URLInputButton
  • url-popover
    • URLPopover
    • __experimentalImageURLInputUI (Has __experimental prefix)
  • use-block-commands (Reack Hook)
  • use-block-display-information (Reack Hook)
  • use-block-drop-zone (Reack Hook)
  • use-flash-editable-blocks (Reack Hook)
  • use-moving-animation (Reack Hook)
  • use-on-block-drop (Reack Hook)
  • use-paste-styles (Reack Hook)
  • ~~use-resize-canvas ~~ (Reack Hook)
  • use-settings (Reack Hook)
  • use-unsupported-block-editor (for native only)
  • video-player (for native only)
  • warning
  • writing-flow
  • writing-mode-control (Has __experimental prefix) Storybook: Add WritingModeControl story #67343
@miminari miminari added [Type] Developer Documentation Documentation for developers [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues. Storybook Storybook and its stories for components labels Nov 20, 2024
@miminari miminari added the Good First Issue An issue that's suitable for someone looking to contribute for the first time label Nov 21, 2024
@miminari
Copy link
Member Author

@imanish003 @Sukhendu2002 @Infinite-Null @SainathPoojary @himanshupathak95 @Sukhendu2002
Thank you all for making PR.
Could you please add links to the list by yourself?
Because it takes time to determine which component is in which directory.
If you cannot edit the list, please comment which you made the PR for which directory's components.

@im3dabasia
Copy link
Contributor

im3dabasia commented Nov 28, 2024

Hey @miminari ,

I have submitted PR for the following components:

@SainathPoojary
Copy link
Contributor

SainathPoojary commented Nov 28, 2024

Hey @miminari,

I have submitted a PR for the following components:

@Infinite-Null
Copy link
Contributor

Hey @miminari,

I have submitted PR for the following components:

@Sukhendu2002
Copy link
Contributor

Sukhendu2002 commented Nov 28, 2024

Hey @miminari,

I have submitted PR for the following components:

@himanshupathak95
Copy link
Contributor

Hey @miminari,

I have submitted a PR for the following components:

@youknowriad
Copy link
Contributor

I'm curious about the reasoning here :). I'm not saying we shouldn't be doing this but curious to lean what value you folks will be receiving from this ?

cc @WordPress/gutenberg-core for awareness.

@mirka
Copy link
Member

mirka commented Nov 29, 2024

I see a couple benefits from the maintainer side:

  • Improve engineering quality. Working in the isolated story when iterating on the component (as opposed to working directly in the Gutenberg app) promotes better engineering standards because it forces you to think about encapsulation, clear interfaces, etc.
  • Increase iteration speed. Having a story is much faster for discovery and testing different states. You don't have to dig around the app to see where the component is used, figure out what states exist, and how to reproduce them.

I honestly don't know if there is pure documentation value for the extenders.

I'd like to emphasize that we should write the stories in a way that keeps maintenance cost at a minimum. It will quickly become a net-negative if the stories incur a maintenance cost. For example, avoid hardcoded values as much as possible, and try to structure things in a way that will not need fixing when the underlying component code changes. Don't write unnecessary descriptions, as those are another thing that need to be updated manually when things change. Let's start with the simplest possible.

@t-hamano
Copy link
Contributor

As a plugin developer, I find Storybook extremely useful.

When implementing a UI for a custom block or block editor, I can see what components are exposed, what props are supported, and how they work.

Without Storybook, it's hard to imagine how something would work unless I actually wrote the code while reading the documentation, or found a place in the Gutenberg repository where the component is actually used.

@t-hamano
Copy link
Contributor

t-hamano commented Dec 2, 2024

I have looked at the PR linked to this issue and I think we need some kind of indicator to unify our implementations and approaches for contributors who are already working on this issue or are planning to work on it.

Below are my thoughts on best practices, but @WordPress/gutenberg-components, if there are any mistakes, please let me know.

Use CSF 3 format

Write stories as objects, not functions

Do

export const Default = {
	render: function Template( { onChange, ...args } ) {
		const [ value, setValue ] = useState();
		return (
			<SomeComponent
				{ ...args }
				onChange={ ( ...changeArgs ) => {
					onChange( ...changeArgs );
					setValue( ...changeArgs );
				} }
				value={ value }
			/>
		);
	},
};

Don't

const Template = ( { onChange, ...args } ) => {
	const [ value, setValue ] = useState();
	return (
		<SomeComponent
			{ ...args }
			onChange={ ( ...changeArgs ) => {
				onChange( ...changeArgs );
				setValue( ...changeArgs );
			} }
			value={ value }
		/>
	);
};

export const Default = Template.bind( {} );

Consists of only one component

I think the purpose of Storybook is to test a single UI component itself. Therefore, unless there is a special reason, we should not include anything other than that component.

Don’t create too many stories

While it's tempting to expose as many variations of a component as possible, the behavior of the component can be changed in the Controls section.

Therefore, I think additional stories should only be included if they involve significant visual or behavioral changes.

@t-hamano
Copy link
Contributor

Additional Tips - To improve code consistency, I would personally be happy to implement the following rules for existing and future PRs:

To display the source panel by default, specify 'shown' in the meta.parameters.docs.canvas.sourceState field.

const meta = {
	// ...
	parameters: {
		docs: {
			canvas: { sourceState: 'shown' },
			// ...
		},
	},
	// ...
};

Define the component description via the meta.parameters.docs.description.component field instead of a comment.

const meta = {
	// ...
	parameters: {
		docs: {
			// ...
			description: {
				component: 'Component description here...',
			},
		},
	},
	// ...
};

Explicitly define the type of props via the meta.argTypes.{propName}.table.type.summary field.

const meta = {
	// ...
	argTypes: {
		// ...
		propName: {
			// ...
			table: {
				type: {
					summary: 'string',
				},
			},
		},
		// ...
	},
};

@t-hamano
Copy link
Contributor

I noticed that some components have the __experimental or __unstable prefix.

I wondered if I should publish these components to Storybook, but some components with these prefix have already been published.

If the component has a proper README and code examples, I believe it's okay to publish it to Storybook.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Good First Issue An issue that's suitable for someone looking to contribute for the first time Storybook Storybook and its stories for components [Type] Developer Documentation Documentation for developers [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues.
Projects
None yet
Development

No branches or pull requests

9 participants