gutenberg-block-components v0.1.0

Gutenberg Block Components

Gutenberg Block Components is a library of common, reusable components for Gutenberg Blocks. It will later become available as an npm package to be used for Gutenberg block development.

Development

Block components will be created outside of WordPress ( in isolation ), however, there may be some components that do not work outside of WordPress like Media which require upload, for such blocks follow local npm package installation steps under "Usage" below. The development of components is done using storybook.

Install

Clone the repo and run

npm install

During development

Start storybook by running the following command which will also keep watching for changes.

npm run storybook

Production

npm run prod

Linting & Formatting

The following command will fix most errors and show and remaing ones which cannot be fixed automatically.

npm run eslint:fix

We follow the stylelint configuration used in WordPress Gutenberg, run the following command to lint and fix styles.

npm run stylelint:fix

Format code with prettier

npm run format-js

Testing

Run all Jest tests.

npm run test

Debug Jest tests.

npm run test:debug

Check test coverage

npm run test:coverage

Update snapshots

npm run test:update

Watch tests

npm run test:watch

precommit

You should run precommit to check for any eslint, stylint errors/warnings and to ensure all tests are passing before making a PR ready for review.

npm run precommit

Acceptance criteria for a component

You should check that the following requirements have met before making a PR ready for review.

1. There must not be any eslint or stylelint errors ( We will later set up build to lint errors )
2. Each component should have ~100% test coverage, and there should be no failing tests ( See test commands ).
   1. There would be cases when we are not able to reach 100% test coverage, we should comment what attempts we made to solve it and why certain case could not be handled in the test file header itself.
   2. We may refer to Gutenberg plugin to see how tests are written.
3. If a component uses settings, register a dummy block within the storybook and use the component inside the block, as a setting cannot be seen until it's used inside a block.
4. If possible a component should also be usable inside the save method. You may add props like isSave to conditionally use elements.
5. If a component only works inside of WordPress or cannot work as component in isolation, it must not look broken in the storybook.
6. BEM Methodology should be used for class names.
7. There should not be any errors in console during any interaction with the component.
8. Reuse the variables from @wordpress/base-styles, we should not introduce new colours, fonts or breakpoints.
9. Files and folder structure should be as per given below.

Files and Folders

• All development will be made inside src/ folder
• Each componet must have its own folder inside src/components which must contain at least
  • index.js as the main file.
  • stories folder for stories, which will automatically be pulled in the storybook.
  • test folder for wrinting tests ( Setup in progress ).
  • README.md file with details about the component and required attributes for component to work.
  • style.scs which should be imported inside src/components/style.scss not in the component. ( If a component needs styling )
  • save.js which will be used for save component.
  • script.js If your component requires additional javascript to run on front-end ( Should be vanilla javascript )
• If a dummy block needs to be registered for the component, it must be created in its own folder inside src/blocks. src/blocks folder will not be used in production, this is just to work with components in stories.

Adding script for front-end

• If your component requires additional javacript to work on front-end, you may write your script inside components/your-component/script.js, which will become available inside build-script after you run prod, and can be imported from an external plugin or package like the following snippet.

import accordion from 'gutenberg-block-components/build-script/accordion'

Usage

Until this package is published on npm, you can do npm install by cloning it locally ( First run npm run prod )

npm install absolute_path_to_gutenberg-block-components

You can now start using the components like any other package. For example

// Import components
import { Media } from "gutenberg-block-components";

// Import SCSS files.
@import "~gutenberg-block-components/styles/component-name/style";
@import "~gutenberg-block-components/styles/component-name/editor";

• Alternatively node_modules/ can be used in place of ~ for importing scss.