Add theming docs

assets/js/base/components/formatted-monetary-amount/index.js

@@ -51,7 +51,11 @@ const FormattedMonetaryAmount = ( {
 		return null;
 	}
 
-	const classes = classNames( 'wc-block-formatted-money-amount', className );
+	const classes = classNames(
+		'wc-block-formatted-money-amount',
+		'wc-block-components-formatted-money-amount',
+		className
+	);
 	const numberFormatProps = {
 		displayType: 'text',
 		...props,

assets/js/base/components/formatted-monetary-amount/style.scss

@@ -1,3 +1,3 @@
-.wc-block-formatted-money-amount {
+.wc-block-components-formatted-money-amount {
 	white-space: nowrap;
 }

assets/js/base/components/product-sort-select/index.js

@@ -13,7 +13,7 @@ import './style.scss';
 const ProductSortSelect = ( { defaultValue, onChange, readOnly, value } ) => {
 	return (
 		<SortSelect
-			className="wc-block-product-sort-select"
+			className="wc-block-product-sort-select wc-block-components-product-sort-select"
 			defaultValue={ defaultValue }
 			name="orderby"
 			onChange={ onChange }

assets/js/base/components/product-sort-select/style.scss

@@ -1,4 +1,4 @@
-.wc-block-product-sort-select {
+.wc-block-components-product-sort-select {
 	margin-bottom: $gap-large;
 	text-align: left;
 }

assets/js/base/components/reviews/review-sort-select/index.js

@@ -13,7 +13,7 @@ import './style.scss';
 const ReviewSortSelect = ( { defaultValue, onChange, readOnly, value } ) => {
 	return (
 		<SortSelect
-			className="wc-block-review-sort-select"
+			className="wc-block-review-sort-select wc-block-components-review-sort-select"
 			defaultValue={ defaultValue }
 			label={ __( 'Order by', 'woo-gutenberg-products-block' ) }
 			onChange={ onChange }

assets/js/base/components/reviews/review-sort-select/style.scss

@@ -1,3 +1,3 @@
-.wc-block-review-sort-select {
+.wc-block-components-review-sort-select {
 	text-align: right;
 }

assets/js/base/components/sort-select/index.js

@@ -26,22 +26,29 @@ const SortSelect = ( {
 	readOnly,
 	value,
 } ) => {
-	const selectId = `wc-block-sort-select__select-${ instanceId }`;
+	const selectId = `wc-block-components-sort-select__select-${ instanceId }`;
 
 	return (
-		<div className={ classNames( 'wc-block-sort-select', className ) }>
+		<div
+			className={ classNames(
+				'wc-block-sort-select',
+				'wc-block-components-sort-select',
+				className
+			) }
+		>
 			<Label
 				label={ label }
 				screenReaderLabel={ screenReaderLabel }
 				wrapperElement="label"
 				wrapperProps={ {
-					className: 'wc-block-sort-select__label',
+					className:
+						'wc-block-sort-select__label wc-block-components-sort-select__label',
 					htmlFor: selectId,
 				} }
 			/>
 			<select // eslint-disable-line jsx-a11y/no-onchange
 				id={ selectId }
-				className="wc-block-sort-select__select"
+				className="wc-block-sort-select__select wc-block-components-sort-select__select"
 				defaultValue={ defaultValue }
 				onChange={ onChange }
 				readOnly={ readOnly }

assets/js/base/components/sort-select/style.scss

@@ -1,13 +1,13 @@
-.wc-block-sort-select {
+.wc-block-components-sort-select {
 	margin-bottom: $gap-small;
 }
 
-.wc-block-sort-select__label {
+.wc-block-components-sort-select__label {
 	margin-right: $gap-small;
 	display: inline-block;
 	font-weight: normal;
 }
 
-.wc-block-sort-select__select {
+.wc-block-components-sort-select__select {
 	width: max-content;
 }

docs/contributors/coding-guidelines.md

@@ -16,38 +16,48 @@ As a WordPress plugin, Blocks has to play nicely with other plugins and themes,
 
 #### Naming
 
-All class names assigned to an element must be prefixed with the following, each joined by a dash (`-`):
+All class names assigned to an element must be prefixed. We use different prefixes to differentiate frontend and editor elements as well as identifying if they are components or not:
 
--   The `wc-block` plugin prefix.
--   The name of the sub-package (where applicable, e.g. if there was a distributed sub-package called `components` living within the blocks plugin, the prefix would be `wc-block-components-`).
--   The name of the directory in which the component resides.
+-   `wc-block` for classes applied to a single block.
+-   `wc-block-components` for classes applied to a component, which might be used by several blocks.
+-   `wc-block-editor` for classes applied to a single block but only used in the editor UI.
+-   `wc-block-editor-components` for classes applied to an editor component.
 
-Any descendant of the component's root element must append a dash-delimited descriptor, separated from the base by two consecutive underscores `__`.
+As a rule of thumb, this is the relation between location in the source tree and class name used:
+
+| Location in the tree | Class names used | Can be styled by themes?
+| --- | --- | :---: |
+| assets/js/atomic/blocks | `.wc-block-components-` | ✓ |
+| assets/js/base/components | `.wc-block-components-` | ✓ |
+| assets/js/blocks | Frontend: `.wc-block-`<br>Editor: `.wc-block-editor-` | ✓<br>✘ |
+| assets/js/components |  `.wc-block-editor-components-` | ✘ |
 
-    Example, `assets/base/components/checkbox-list` uses the class name: `wc-block-checkbox-list`.
+After the prefix, class names are built using BEM:
 
 A **root element** (or **Block** in BEM notation) is a standalone entity that is meaningful on its own. Whilst they can be nested and interact with each other, semantically they remain equal; there is no precedence or hierarchy.
 
-    Example: `wc-block-package-directory`
+    Example: `wc-block-directory-name`
+
+Any descendant of the component's root element must append a dash-delimited descriptor, separated from the base by two consecutive underscores `__`.
 
 A **child element** (or **Element** in BEM notation) has no standalone meaning and is semantically tied to its block.
 
-    Example: `wc-block-package-directory__descriptor-foo-bar`
+    Example: `wc-block-directory-name__descriptor-foo-bar`
 
 Finally, A **modifier** is a flag on an element which can be used to change appearance, behavior or state.
 
-    Example: `wc-block-package-directory__descriptor-foo-bar--state`
+    Example: `wc-block-directory-name__descriptor-foo-bar--state`
 
 The **root element** is considered to be the highest ancestor element returned by the default export in the index.js. Notably, if your folder contains multiple files, each with their own default exported component, only the element rendered by that of index.js can be considered the root. All others should be treated as **descendants**.
 
 Naming is not strictly tied to the DOM so it **doesn’t matter how many nested levels deep a descendant element is**. The naming convention is there to help you identify relationships with the root element.
 
 **Nesting Example:**
 
--   `wc-block-dropdown-selector` (Root Element/BEM Block)
--   ├── `wc-block-dropdown-selector__input` (Child Element/BEM Element)
--   ├── `wc-block-dropdown-selector__input--hidden` (Modifier)
--   └── `wc-block-dropdown-selector__placeholder` (Child Element/BEM Element)
+-   `wc-block-components-dropdown-selector` (Root Element/BEM Block)
+-   ├── `wc-block-components-dropdown-selector__input` (Child Element/BEM Element)
+-   ├── `wc-block-components-dropdown-selector__input--hidden` (Modifier)
+-   └── `wc-block-components-dropdown-selector__placeholder` (Child Element/BEM Element)
 
 ### RTL Styles
 

docs/readme.md

@@ -20,3 +20,7 @@ The WooCommerce Blocks Handbook provides documentation for designers and develop
 **API documentation**
 
 -   [Store API documentation](../src/RestApi/StoreApi/README.md)
+
+**For themes**
+
+-   [Theming documention](theming/README.md)

docs/theming/README.md

@@ -2,5 +2,75 @@
 
 This page includes all documentation regarding WooCommerce Blocks and themes.
 
+
+## General concepts
+
+### Block and component class names
+
+WooCommerce Blocks follows BEM for class names, as [stated in our coding guidelines](../contributors/coding-guidelines.md). All classes start with one of these two prefixes:
+
+* `.wc-block-`: class names specific to a single block.
+* `.wc-block-components-`: class names specific to a component. The component might be reused by different blocks.
+
+The combination of block class names and component class names allows themes to style each component either globally or only in specific blocks. As an example, you could style all prices to be italics with:
+
+```CSS
+/* This will apply to all block prices */
+.wc-block-components-formatted-money-amount {
+	font-style: italic;
+}
+```
+
+But if you only wanted to make it italic in the Checkout block, that could be done adding the block selector:
+
+```CSS
+/* This will apply to prices in the checkout block */
+.wc-block-checkout .wc-block-components-formatted-money-amount {
+	font-style: italic;
+}
+```
+
+**Note:** for backwards compatibility, some components might have class names with both prefixes (ie: `wc-block-sort-select` and `wc-block-components-sort-select`). In those cases, the class name with `.wc-block-` prefix is deprecated and shouldn't be used in new code. It will be removed in future versions. If an element has both classes always style the one with `.wc-block-components-` prefix.
+
+
+### Container query class names
+
+Some of our components have responsive classes depending on the container width. The reason to use these classes instead of CSS media queries is to adapt to the container where the block is added (CSS media queries only allow reacting to viewport sizes).
+
+Those classes are:
+
+| Container width | Class name |
+| --- | --- |
+| >700px | `is-large` |
+| 521px-700px | `is-medium` |
+| 401px-520px | `is-small` |
+| <=400px | `is-mobile` |
+
+As an example, if we wanted to do the Checkout font size 10% larger when the container has a width of 521px or wider, we could do so with this code:
+
+```CSS
+.wc-block-checkout is-medium,
+.wc-block-checkout is-large {
+	font-size: 1.1em;
+}
+```
+
+
+### WC Blocks _vs._ theme style conflicts for semantic elements
+
+WooCommerce Blocks uses HTML elements according to their semantic meaning, not their default layout. That means that some times blocks might use an anchor link (`<a>`) but display it as a button. Or the other way around, a `<button>` might be displayed as a text link. Similarly, headings might be displayed as regular text.
+
+In these cases, Blocks include some CSS resets to undo most default styles introduced by themes. A `<button>` that is displayed as a text link will probably have resets for the background, border, etc. That will solve most conflicts out-of-the-box but in some occasions those CSS resets might not have effect if the theme has a specific CSS selector with higher specificity. When that happens, we really encourage theme developers to decrease their selectors specificity so Blocks styles have preference, if that's not possible, themes can write CSS resets on top.
+
+
+### Legacy classes from WooCommerce (.price, .star-rating, .button...)
+
+WooCommerce Blocks avoids using legacy unprefixed classes as much as possible. However, you might find some of them that have been added for backwards compatibility. We still encourage themes to use the prefixed classes when possible, this avoids conflicts with other plugins, the editor, etc.
+
+
+## Blocks
 -   [Cart and Checkout](./cart-and-checkout.md)
+
+## Other docs
 -   [Product grid blocks style update in 2.7.0](./product-grid-270.md)
+-   [Class names update in 2.8.0](./class-names-update-280.md)

docs/theming/class-names-update-280.md

@@ -0,0 +1,19 @@
+# Class names update in 2.8.0
+
+In WC Blocks 2.8.0, some class names were updated in order to simplify them, fix inconsistencies, and make it easier to differentiate frontend components from editor components.
+
+## Replaced classes
+
+Some classes that were introduced in 2.6.0 and 2.7.0 and didn't ship in WooCommerce Core have been replaced by new ones. They can be found in this table:
+
+| Removed | New class name |
+| --- | --- |
+
+## Deprecated classes
+
+Some classes that were introduced in previous versions or that have shipped in WooCommerce Core, have not been removed but are deprecated. Those classes will not be removed yet but all themes are encouraged to update to the new ones:
+
+| Deprecated | New class name |
+| --- | --- |
+| `wc-block-product-sort-select` | `wc-block-components-product-sort-select` |
+| `wc-block-formatted-money-amount` | `wc-block-components-formatted-money-amount` |