diff --git a/packages/js/components/README.md b/packages/js/components/README.md index 1e82e0f932a..61fac4dfffe 100644 --- a/packages/js/components/README.md +++ b/packages/js/components/README.md @@ -21,14 +21,46 @@ View [the full Component documentation](https://woocommerce.github.io/woocommerc import { Card } from '@woocommerce/components'; export default function MyCard() { - return ( - -

Your stuff in a Card.

-
- ); + return ( + +

Your stuff in a Card.

+
+ ); } ``` Many components include CSS to add style, you will need to add in order to appear correctly. Within WooCommerce, add the `wc-components` stylesheet as a dependency of your plugin's stylesheet. See [wp_enqueue_style documentation](https://developer.wordpress.org/reference/functions/wp_enqueue_style/#parameters) for how to specify dependencies. In non-WordPress projects, link to the `build-style/card/style.css` file directly, it is located at `node_modules/@woocommerce/components/build-style//style.css`. + +## Usage with tests + +If you are using these components in a project that uses Jest for testing, you may get an error that looks like this: + +```bash +Cannot find module '@woocommerce/settings' from 'node_modules/@woocommerce/experimental/node_modules/@woocommerce/navigation/build/index.js' +``` + +To fix this, you will need to mock the `@woocommerce/settings` because it's an alias that points to the `window.wcSettings`, which in turn comes from and is maintained by the [WC Blocks](https://github.com/woocommerce/woocommerce-blocks) package, the front-end code for this is located [here](https://href.li/?https://github.com/woocommerce/woocommerce-gutenberg-products-block/tree/trunk/assets/js/settings/shared). + +This can be done by adding the following to your Jest config: + +```js +module.exports = { + moduleNameMapper: { + '@woocommerce/settings': path.resolve( + __dirname, + './mock/woocommerce-settings' + ), + } + setupFiles: [ + path.resolve( __dirname, 'build/setup-globals.js' ), + ], + // ...other config +} +``` + +Then, you will need to create the following files: + +1. Create a new file called woocommerce-settings.js in the ./mock directory. You can find the content for this file [here](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/internal-js-tests/src/mocks/woocommerce-settings.js#L1). +2. Next, create a file named setup-globals.js. You can find the content for this file [here](https://github.com/woocommerce/woocommerce/blob/trunk/packages/js/internal-js-tests/src/setup-globals.js#L44). The purpose of this file is to mock the wcSettings global variable. diff --git a/packages/js/components/changelog/dev-wc-components-readme b/packages/js/components/changelog/dev-wc-components-readme new file mode 100644 index 00000000000..2f7f60249ec --- /dev/null +++ b/packages/js/components/changelog/dev-wc-components-readme @@ -0,0 +1,4 @@ +Significance: patch +Type: dev + +Add instructions on how to run the tests when using @woocommerce/components