Commit de1c08c1f82 for woocommerce
commit de1c08c1f8246b551021f075d691188f9a007711
Author: Luigi Teschio <gigitux@gmail.com>
Date: Fri Jul 10 15:13:14 2026 +0200
Update Blocks feature flags and experimental interfaces docs (#66487)
* Update Blocks feature flags documentation
* fix lint
* improve example
* improve doc
* Update plugins/woocommerce/client/blocks/docs/internal-developers/blocks/feature-flags-and-experimental-interfaces.md
Co-authored-by: Albert Juhé Lluveras <contact@albertjuhe.com>
* Update plugins/woocommerce/client/blocks/docs/internal-developers/blocks/feature-flags-and-experimental-interfaces.md
Co-authored-by: Albert Juhé Lluveras <contact@albertjuhe.com>
* remove deprecated blocks
---------
Co-authored-by: Albert Juhé Lluveras <contact@albertjuhe.com>
diff --git a/plugins/woocommerce/client/blocks/docs/internal-developers/blocks/README.md b/plugins/woocommerce/client/blocks/docs/internal-developers/blocks/README.md
index 58312b0f03e..9964536a8a8 100644
--- a/plugins/woocommerce/client/blocks/docs/internal-developers/blocks/README.md
+++ b/plugins/woocommerce/client/blocks/docs/internal-developers/blocks/README.md
@@ -2,7 +2,7 @@
This folder contains documentation for specific Blocks and Blocks functionality.
-| Document | Description |
-| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Stock Reservation during Checkout](stock-reservation.md) | This doc covers the Checkout Stock Reservation system. |
-| [Features Flags and Experimental interfaces](feature-flags-and-experimental-interfaces.md) | This doc outlines all the current features that are gated behind a feature or experimental flag as well as any interfaces that are experimental |
+| Document | Description |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| [Stock Reservation during Checkout](stock-reservation.md) | This doc covers the Checkout Stock Reservation system. |
+| [Feature Flags and Experimental Interfaces](feature-flags-and-experimental-interfaces.md) | This doc describes current Blocks feature flags and experimental interface. |
diff --git a/plugins/woocommerce/client/blocks/docs/internal-developers/blocks/feature-flags-and-experimental-interfaces.md b/plugins/woocommerce/client/blocks/docs/internal-developers/blocks/feature-flags-and-experimental-interfaces.md
index df5981ba9ce..3f11e1416fe 100644
--- a/plugins/woocommerce/client/blocks/docs/internal-developers/blocks/feature-flags-and-experimental-interfaces.md
+++ b/plugins/woocommerce/client/blocks/docs/internal-developers/blocks/feature-flags-and-experimental-interfaces.md
@@ -1,137 +1,110 @@
-# Features Flags and Experimental Interfaces <!-- omit in toc -->
-
-## Table of contents <!-- omit in toc -->
-
-- [Blocks behind flags](#blocks-behind-flags)
- - [Feature plugin flag](#feature-plugin-flag)
- - [Experimental flag](#experimental-flag)
-- [Features behind flags](#features-behind-flags)
- - [Feature plugin flag](#feature-plugin-flag)
-- [Processes and commands that use a flag](#processes-and-commands-that-use-a-flag)
-- [Usages of `__experimental` prefix](#usages-of-__experimental-prefix)
- - [PHP filters and actions](#php-filters-and-actions)
- - [JS methods](#js-methods)
- - [Slots](#slots)
- - [Misc](#misc)
-- [Usages of `experimental` prefix](#usages-of-experimental-prefix)
-
-We also use an `__experimental` prefix for any experimental interfaces. This is a signal to those reading our code that it should not be implemented in for production use. Currently, this prefix is used in the following ways:
-
-- Prefixing references that are experimental. An example would be PHP action or filter slugs.
-- Prefixing functions or methods that are experimental.
-
-## Blocks behind flags
-
-The majority of our feature flagging is blocks, this is a list of them:
-
-### Experimental flag
-
-- Clear (Experimental)
- - [PHP flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce/src/Blocks/BlockTypesController.php#L308)
- - [Webpack flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/bin/webpack-entries.js#L122)
- - [JS flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/assets/js/blocks/product-filter/inner-blocks/clear-button/index.tsx#L15)
-- Product Filter (Experimental)
- - [PHP flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce/src/Blocks/BlockTypesController.php#L301)
- - [Webpack flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/bin/webpack-entries.js#L95)
- - [JS flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/assets/js/blocks/product-filter/index.tsx#L30)
-- Product Filters (Experimental)
- - [PHP flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce/src/Blocks/BlockTypesController.php#L302)
- - [Webpack flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/bin/webpack-entries.js#L98)
- - [JS flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/assets/js/blocks/product-filters/index.tsx#L13)
-- Product Filter: Active Filters (Experimental)
- - [PHP flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce/src/Blocks/BlockTypesController.php#L307)
- - [Webpack flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/bin/webpack-entries.js#L118)
- - [JS flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/assets/js/blocks/product-filter/inner-blocks/active-filters/index.tsx#L16)
-- Product Filter: Attribute (Experimental)
- - [PHP flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce/src/Blocks/BlockTypesController.php#L305)
- - [Webpack flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/bin/webpack-entries.js#L110)
- - [JS flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/assets/js/blocks/product-filter/inner-blocks/attribute-filter/index.tsx#L14)
-- Product Filter: Price (Experimental)
- - [PHP flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce/src/Blocks/BlockTypesController.php#L304)
- - [Webpack flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/bin/webpack-entries.js#L106)
- - [JS flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/assets/js/blocks/product-filter/inner-blocks/price-filter/index.tsx#L15)
-- Product Filter: Rating (Experimental)
- - [PHP flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce/src/Blocks/BlockTypesController.php#L306)
- - [Webpack flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/bin/webpack-entries.js#L114)
- - [JS flag](https://github.com/woocommerce/woocommerce/blob/bad0b61a83c5e86703a985deaab67cbb3a88a06d/plugins/woocommerce-blocks/assets/js/blocks/product-filter/inner-blocks/rating-filter/index.tsx#L14)
-- Product Filter: Stock Status (Experimental)
- - [PHP flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce/src/Blocks/BlockTypesController.php#L303)
- - [Webpack flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/bin/webpack-entries.js#L101)
- - [JS flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/assets/js/blocks/product-filter/inner-blocks/stock-filter/index.tsx#L15)
-- Delayed Account Creation (Experimental)
- - [PHP flag](https://github.com/woocommerce/woocommerce/blob/9897737880dcbef9831ee41799684dab1960d94f/plugins/woocommerce/src/Blocks/BlockTypesController.php#L417)
- - [Webpack flag](https://github.com/woocommerce/woocommerce/blob/9897737880dcbef9831ee41799684dab1960d94f/plugins/woocommerce-blocks/bin/webpack-entries.js#L168)
- - [JS flag](https://github.com/woocommerce/woocommerce/blob/9897737880dcbef9831ee41799684dab1960d94f/plugins/woocommerce-blocks/assets/js/blocks/order-confirmation/create-account/index.tsx#L14)
-- Add to Cart + Options (Experimental)
- - [PHP flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce/src/Blocks/BlockTypesController.php#L456)
- - [Webpack flag](https://github.com/woocommerce/woocommerce/blob/a0f9d159e5196983d93064762fd20a510de57d55/plugins/woocommerce-blocks/bin/webpack-entries.js#L23)
- - [JS flag](https://github.com/woocommerce/woocommerce/blob/9897737880dcbef9831ee41799684dab1960d94f/plugins/woocommerce-blocks/assets/js/blocks/order-confirmation/create-account/index.tsx#L14)
+# Feature Flags and Experimental Interfaces <!-- omit in toc -->
-## Features behind flags
+WooCommerce Blocks uses feature flags to control access to in-progress features and experimental prefixes to identify interfaces that can change without notice. These are separate concepts: a feature can be behind a flag without exposing an experimental interface, and an experimental interface can remain available regardless of a feature flag.
-We also have individual features or code blocks behind a feature flag, this is a list of them:
+This document covers flags used by Blocks and WooCommerce-owned experimental interfaces in the Blocks and Store API code. It does not inventory experimental components, properties, or supports imported from WordPress packages. The source code linked below remains the source of truth.
-### Feature plugin flag
+## Feature flags
-- ⚛️ Product Price new controls ([JS flag](https://github.com/woocommerce/woocommerce-blocks/blob/74badf254ecfe0c7811713a0f847a87f139c69c3/assets/js/atomic/blocks/product-elements/price/supports.ts#L14-L37)).
-- ⚛️ Product Title new controls ([JS flag 1](https://github.com/woocommerce/woocommerce-blocks/blob/fd8eeb7f49f0454d746d581bc892cf3c2d9e30cc/assets/js/atomic/blocks/product-elements/title/attributes.ts#L25-L32) | [JS flag 2-1](https://github.com/woocommerce/woocommerce-blocks/blob/df6d820bb47459d56c1329729ab8c364a1b8fddc/assets/js/atomic/blocks/product-elements/title/block.tsx#L84) | [JS flag 2-2](https://github.com/woocommerce/woocommerce-blocks/blob/df6d820bb47459d56c1329729ab8c364a1b8fddc/assets/js/atomic/blocks/product-elements/title/block.tsx#L88) | [JS flag 2-3](https://github.com/woocommerce/woocommerce-blocks/blob/df6d820bb47459d56c1329729ab8c364a1b8fddc/assets/js/atomic/blocks/product-elements/title/block.tsx#L110) | [JS flag 2-4](https://github.com/woocommerce/woocommerce-blocks/blob/df6d820bb47459d56c1329729ab8c364a1b8fddc/assets/js/atomic/blocks/product-elements/title/block.tsx#L114) | [JS flag 3-1](https://github.com/woocommerce/woocommerce-blocks/blob/c734f3e846b8da7d49a03347d92354efd786251f/assets/js/atomic/blocks/product-elements/title/edit.tsx#L45-L52) | [JS flag 3-2](https://github.com/woocommerce/woocommerce-blocks/blob/c734f3e846b8da7d49a03347d92354efd786251f/assets/js/atomic/blocks/product-elements/title/edit.tsx#L98)).
+WooCommerce currently uses two feature-flag systems in Blocks:
-## Processes and commands that use a flag
+- Build-configured flags are defined for each build environment in the [WooCommerce Admin configuration](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/client/admin/config) and checked with `Automattic\WooCommerce\Admin\Features\Features::is_enabled()`.
+- Runtime feature definitions are registered in [`FeaturesController`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/Features/FeaturesController.php), exposed on the **WooCommerce > Settings > Advanced > Features** screen when applicable, and checked with `FeaturesUtil::feature_is_enabled()`.
-- `npm run build:deploy` uses the feature plugin flag ([env flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/c0de18ec0a798c072420c67a689e4cc4d3ac77c9/package.json#L28)).
-- GitHub actions uses the experimental flag when running automated tests ([env flags 1](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/4cedb65367be0d1c4c1f9dd9c016e3b1325cf92e/.github/workflows/php-js-e2e-tests.yml) | [env flags 2](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/4cedb65367be0d1c4c1f9dd9c016e3b1325cf92e/.github/workflows/unit-tests.yml)).
-- webpack creates a `blocks.ini` when running ([env flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/961c0c476d4228a218859c658c42f9b6eebfdec4/bin/webpack-configs.js#L110-L119)).
-- webpack filters out experimental blocks when building. ([env flag](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/b3a9753d8b7dae18b36025d09fbff835b8365de0/bin/webpack-entries.js#L61-L66)).
-- certain E2E tests are skipped if the environment is not met ([env flag 1](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/961c0c476d4228a218859c658c42f9b6eebfdec4/tests/e2e/specs/backend/cart.test.js#L26) | [env flag 2](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/961c0c476d4228a218859c658c42f9b6eebfdec4/tests/e2e/specs/backend/checkout.test.js#L26) | [env flag 3](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/961c0c476d4228a218859c658c42f9b6eebfdec4/tests/e2e/specs/backend/mini-cart.test.js#L18) | [env flag 4](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/961c0c476d4228a218859c658c42f9b6eebfdec4/tests/e2e/specs/backend/single-product.test.js#L8) | [env flag 5](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/961c0c476d4228a218859c658c42f9b6eebfdec4/tests/e2e/specs/frontend/cart.test.js#L29) | [env flag 6](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/961c0c476d4228a218859c658c42f9b6eebfdec4/tests/e2e/specs/frontend/checkout.test.js#L32)).
+### Build-configured flags
-## Usages of `__experimental` prefix
+| Flag | Defaults | Current Blocks usage |
+| --- | --- | --- |
+| `experimental-blocks` | Enabled in [development](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/admin/config/development.json) and disabled in [core builds](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/admin/config/core.json). | Exposed to the editor through [`isExperimentalBlocksEnabled()`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/assets/js/settings/blocks/feature-flags.ts). It currently gates the **Disable product descriptions** editor control in Checkout Order Summary Cart Items and conditional checkout-field processing in the Store API. It does not determine which block scripts webpack builds or which general block types are registered. |
+| `rest-api-v4` | Disabled in both development and core build configurations. | Exposed through [`isExperimentalWcRestApiV4Enabled()`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/assets/js/settings/blocks/feature-flags.ts). It switches product entities from `/wc/v3/products` to `/wc/v4/products`, registers the settings entity, and enables the v4 product-data paths used by Product Price and Product Button in the editor. |
-### PHP filters and actions
+### Runtime feature flags
-- `__experimental_woocommerce_blocks_payment_gateway_features_list` hook that allows modification of the features supported by PayPal Standard. ([experimental hook](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/4cedb65367be0d1c4c1f9dd9c016e3b1325cf92e/src/Payments/Integrations/PayPal.php#L86)).
-- **Deprecated** - `__experimental_woocommerce_blocks_checkout_update_order_meta` hook when the draft order has been created or updated from the cart and is now ready for extensions to modify the metadata ([experimental hook](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/3686/files#diff-af2c90fa556cc086b780c8fad99b68373d87fd6007e6e2ff1b4c68ebe9ccb551R377-R393)). [Deprecated in PR 5017](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/5017).
-- **Deprecated** - `__experimental_woocommerce_blocks_checkout_update_order_from_request` hook gives extensions the chance to update orders based on the data in the request ([deprecated experimental hook](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/d469a45d572f2c52d7917707c492dfb905ddfac0/src/StoreApi/Routes/Checkout.php#L466-L477)). [Deprecated in PR 5015](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/5015).
-- **Deprecated** - `__experimental_woocommerce_blocks_checkout_order_processed` hook when order has completed processing and is ready for payment ([deprecated experimental hook](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/accd1bbf402e043b9fc322f118ab614ba7437c92/src/StoreApi/Routes/Checkout.php#L237)). [Deprecated in PR 5014](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/5014).
-- `__experimental_woocommerce_blocks_add_data_attributes_to_namespace` hook that allows 3PD to add a namespace of blocks to receive block attributes as `data-` attributes ([experimental property](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/4a1ee97eb97011458174e93e44a9b7ad2f10ca36/src/BlockTypesController.php#L88)).
-- `__experimental_woocommerce_blocks_add_data_attributes_to_block` hook that allows 3PD to add a block to receive block attributes as `data-` attributes ([experimental property](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/4a1ee97eb97011458174e93e44a9b7ad2f10ca36/src/BlockTypesController.php#L97)).
+These flags are experimental, disabled by default, and registered in [`FeaturesController`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/Features/FeaturesController.php).
-### JS methods
+| Flag | Current Blocks usage |
+| --- | --- |
+| `cart_save_for_later` | Registers the `woocommerce/saved-for-later` block through [`BlockTypesController`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/BlockTypesController.php), enables the related shopper-list APIs, and exposes the Save for later action in Cart when the block is present. |
+| `product_wishlist` | Registers the `woocommerce/wishlist` and `woocommerce/add-to-wishlist-button` blocks and enables the related shopper-list APIs and My Account endpoint. |
+| `wc-visual-attribute` | Enables the experimental `wc-visual` product attribute type for block themes. The Product Filters and Add to Cart + Options blocks read the resulting attribute data to display visual variation choices. |
-- `__experimentalDeRegisterPaymentMethod` function used to deregister a payment method, only used in tests ([experimental function](https://github.com/woocommerce/woocommerce-blocks/blob/f27456dd00fa0b21b29a935943defb18351edf48/assets/js/blocks-registry/payment-methods/registry.ts#L110-L114)).
-- `__experimentalDeRegisterExpressPaymentMethod` function used to deregister an express payment method, only used in tests ([experimental function](https://github.com/woocommerce/woocommerce-blocks/blob/f27456dd00fa0b21b29a935943defb18351edf48/assets/js/blocks-registry/payment-methods/registry.ts#L116-L120)).
+The hidden, mature `cart_checkout_blocks` feature definition is a compatibility marker used to report extensions that declared compatibility with Cart and Checkout blocks. It does not enable or disable those blocks.
-### Slots
+## Experimental interfaces
-- `__experimentalOrderMeta` slot that allows extensions to add content to the order meta in the Cart and Checkout blocks ([experimental slot](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/4cedb65367be0d1c4c1f9dd9c016e3b1325cf92e/packages/checkout/order-meta/index.js#L12)).
-- `__experimentalOrderShippingPackages` slot that allows extensions to add content to the shipping packages in the Cart and Checkout blocks ([experimental slot](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/4cedb65367be0d1c4c1f9dd9c016e3b1325cf92e/packages/checkout/order-shipping-packages/index.js#L12)).
-- `__experimentalDiscountsMeta` slot that allows extensions to add content to the shipping packages in the Cart and Checkout blocks ([experimental slot](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/b6a9cc6342696f47cc08686522bdaca7989a6bc7/packages/checkout/discounts-meta/index.js)).
+Names prefixed with `__experimental`, `experimental__`, or `Experimental` are unstable. Extensions using them must expect breaking changes and should migrate when a stable replacement is available.
-### Misc
+### Current PHP hooks
-- `__experimental_woocommerce_blocks_hidden` property allows overwriting the `hidden` property for cart item data. This is useful to make some cart item data visible/hidden depending on whether it needs to be displayed in the Cart Block or the Cart Shortcode ([experimental property](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/9c4288b0ee46960bdc2bf8ef351d05ac23073b0c/src/StoreApi/Schemas/CartItemSchema.php#L439-L441)). This was added in [this PR](https://github.com/woocommerce/woocommerce-blocks/pull/3732) to resolve [this issue with Subscriptions](https://github.com/woocommerce/woocommerce-blocks/issues/3731). This property will not be needed if the blocks replace the shortcode experience, since in that scenario, the `hidden` property would be sufficient.
+| Interface | Type | Purpose |
+| --- | --- | --- |
+| `__experimental_woocommerce_blocks_add_data_attributes_to_namespace` | Filter | Adds block namespaces whose rendered markup should receive block and attribute `data-` attributes. See [`BlockTypesController`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/BlockTypesController.php). |
+| `__experimental_woocommerce_blocks_add_data_attributes_to_block` | Filter | Adds individual blocks whose rendered markup should receive block and attribute `data-` attributes. See [`BlockTypesController`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/BlockTypesController.php). |
+| `__experimental_woocommerce_blocks_payment_gateway_features_list` | Filter | Changes the features exposed by the PayPal Standard Blocks integration. See [`PayPal`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/Payments/Integrations/PayPal.php). |
+| `__experimental_woocommerce_store_api_batch_request_methods` | Filter | Changes the HTTP methods allowed in Store API batch requests. See [`Batch`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/StoreApi/Routes/V1/Batch.php). |
+| `__experimental_woocommerce_{$product_type}_add_to_cart_with_options_block_template_part` | Filter | Allows an extension to provide an Add to Cart + Options template part for a custom product type. See [`AddToCartWithOptions`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/BlockTypes/AddToCartWithOptions/AddToCartWithOptions.php). |
-## Usages of `experimental` prefix
+### Deprecated PHP interfaces
-`useStoreEvents` makes use of an `experimental__` prefix for wp-hook actions (since `__experimental` is not a valid prefix in that context).
+The following compatibility aliases still run but should not be used in new code.
-These are [`@wordpress/hooks`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-hooks/) actions that are fired at certain times while using WooCommerce Blocks. We separate them into "store" events (events that happen in the store, i.e. while browsing the store or cart) and "checkout events" (events that happen on the checkout page)
+| Deprecated interface | Stable replacement |
+| --- | --- |
+| `__experimental_woocommerce_blocks_register_checkout_field()` | `woocommerce_register_additional_checkout_field()` |
+| `__experimental_woocommerce_blocks_sanitize_additional_field` | `woocommerce_sanitize_additional_field` |
+| `__experimental_woocommerce_blocks_validate_additional_field` | `woocommerce_validate_additional_field` |
+| `__experimental_woocommerce_blocks_validate_location_{$location}_fields` | `woocommerce_blocks_validate_location_{$location}_fields` |
+| `__experimental_woocommerce_blocks_checkout_order_processed` | `woocommerce_store_api_checkout_order_processed` |
+| `__experimental_woocommerce_blocks_checkout_update_order_meta` | `woocommerce_store_api_checkout_update_order_meta` |
+| `__experimental_woocommerce_blocks_checkout_update_order_from_request` | `woocommerce_store_api_checkout_update_order_from_request` |
-- `experimental__woocommerce_blocks-` is used for store events.
-- `experimental__woocommerce_blocks-checkout-` is used for checkout events.
+The checkout-field aliases are implemented in [`functions.php`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/Domain/Services/functions.php) and [`CheckoutFields`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/Domain/Services/CheckoutFields.php). The checkout-order aliases are emitted by the [Store API Checkout route](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/StoreApi/Routes/V1/Checkout.php) and [`CheckoutTrait`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/StoreApi/Utilities/CheckoutTrait.php).
-### Current list of events
+### Store API parameters and properties
-#### `experimental__woocommerce_blocks-cart-add-item`
+| Interface | Purpose |
+| --- | --- |
+| `__experimental_calc_totals` | Checkout request parameter that recalculates cart totals before validation. See the [Checkout route](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/StoreApi/Routes/V1/Checkout.php). |
+| `__experimental_visual` | Product attribute terms request parameter that includes experimental visual swatch data. See [`ProductAttributeTerms`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/StoreApi/Routes/V1/ProductAttributeTerms.php). |
+| `__experimental_woocommerce_blocks_hidden` | Cart item data property that overrides the `hidden` value used by Blocks. See [`CartItemSchema`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/StoreApi/Schemas/V1/CartItemSchema.php). |
-Fired when an item is added to the cart.
+### JavaScript methods
-##### Args
+| Interface | Status and purpose |
+| --- | --- |
+| `__experimentalRegisterProductCollection` | Registers a Product Collection collection. It is experimental and can change without notice. See [`register-product-collection.tsx`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/assets/js/blocks-registry/product-collection/register-product-collection.tsx). |
+| `__experimentalDeRegisterPaymentMethod` | Deregisters a payment method. It is primarily used by tests. See [`registry.ts`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/assets/js/blocks-registry/payment-methods/registry.ts). |
+| `__experimentalDeRegisterExpressPaymentMethod` | Deregisters an express payment method. It is primarily used by tests. See [`registry.ts`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/assets/js/blocks-registry/payment-methods/registry.ts). |
+| `__experimentalRegisterCheckoutFilters` | Deprecated alias for `registerCheckoutFilters`. |
+| `__experimentalApplyCheckoutFilter` | Deprecated alias for `applyCheckoutFilter`. |
-| Argument | Type | Description |
-|----------|--------|--------|
-| `product` | `object` | The product that was added to the cart. |
+The deprecated Checkout Filter aliases are implemented in the [`filter-registry`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/packages/checkout/filter-registry/index.ts).
-##### Example
+### SlotFills
+
+| Export | Internal slot name | Placement |
+| --- | --- | --- |
+| `ExperimentalOrderMeta` | `__experimentalOrderMeta` | Below the Checkout summary or above the Cart checkout button. |
+| `ExperimentalOrderShippingPackages` | `__experimentalOrderShippingPackages` | Inside the shipping options shown by Cart and Checkout. |
+| `ExperimentalOrderLocalPickupPackages` | `__experimentalOrderLocalPickupPackages` | Inside the Checkout pickup options. |
+| `ExperimentalDiscountsMeta` | `__experimentalDiscountsMeta` | Below each discount in the Cart and Checkout totals. |
+
+See the [available SlotFills](https://github.com/woocommerce/woocommerce/blob/trunk/docs/block-development/extensible-blocks/cart-and-checkout-blocks/available-slot-fills.md) and the [checkout components source](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/client/blocks/packages/checkout/components) for their current props and placement.
+
+### Store events
+
+[`useStoreEvents`](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/client/blocks/assets/js/base/context/hooks/use-store-events.ts) emits actions through `@wordpress/hooks`. Store events use the `experimental__woocommerce_blocks-` prefix.
+
+| Action | Parameters |
+| --- | --- |
+| `experimental__woocommerce_blocks-cart-add-item` | `product` |
+| `experimental__woocommerce_blocks-cart-view-link` | `product` |
+| `experimental__woocommerce_blocks-cart-remove-item` | `product`, `quantity` |
+| `experimental__woocommerce_blocks-cart-set-item-quantity` | `product`, `quantity` |
+| `experimental__woocommerce_blocks-product-view-link` | `product` |
+| `experimental__woocommerce_blocks-product-list-render` | `products`, `listName` |
+
+Examples:
```js
wp.hooks.addAction(
@@ -141,234 +114,102 @@ wp.hooks.addAction(
console.log( `${ product.name } was added to the cart` );
}
);
-```
-
-#### `experimental__woocommerce_blocks-cart-set-item-quantity`
-
-Fired when cart item quantity is changed by the customer. Fires on the Mini-cart block and the Cart block.
-
-##### Args
-| Argument | Type | Description |
-|------------|----------|-----------------------------------------|
-| `product` | `object` | The product that was added to the cart. |
-| `quantity` | `number` | The new quantity of the product. |
-
-##### Example
-
-```js
wp.hooks.addAction(
'experimental__woocommerce_blocks-cart-set-item-quantity',
'plugin/namespace',
( { product, quantity } ) => {
- console.log( `${ product.name }'s quantity was changed to ${ quantity }` );
+ console.log( `${ product.name } quantity changed to ${ quantity }` );
}
);
-```
-
-#### `experimental__woocommerce_blocks-cart-remove-item`
-Fired when a cart item is removed from the cart. Fires on the Mini-cart block and the Cart block.
-
-##### Args
-
-| Argument | Type | Description |
-|------------|----------|--------------------------------------------------|
-| `product` | `object` | The product that was added to the cart. |
-| `quantity` | `number` | The quantity of the product when it was removed. |
-
-##### Example
-
-```js
wp.hooks.addAction(
'experimental__woocommerce_blocks-cart-remove-item',
'plugin/namespace',
( { product, quantity } ) => {
- console.log( `${ product.name } was removed from the cart. There were ${ quantity } in the cart.` );
+ console.log( `${ quantity } of ${ product.name } were removed` );
}
);
-```
-
-#### `experimental__woocommerce_blocks-product-view-link`
-
-Fired when a product link is clicked.
-
-##### Args
-
-| Argument | Type | Description |
-|------------|----------|-----------------------------------------|
-| `product` | `object` | The product that was added to the cart. |
-##### Example
-
-```js
wp.hooks.addAction(
'experimental__woocommerce_blocks-product-view-link',
'plugin/namespace',
( { product } ) => {
- console.log( `${ product.name } view link clicked.` );
+ console.log( `${ product.name } view link was selected` );
}
);
```
-#### `experimental__woocommerce_blocks-product-list-render`
-
-Fired when a product list is rendered.
-
-This documentation will be amended following a review of this action.
-
-#### `experimental__woocommerce_blocks-store-notice-create`
+### Checkout events
-Fired when a store notice is created.
+Checkout events use the `experimental__woocommerce_blocks-checkout-` prefix. `dispatchCheckoutEvent()` adds the current `storeCart` value to every event payload in addition to the parameters listed below.
-This documentation will be amended following a review of this action.
+| Action | Additional parameters |
+| --- | --- |
+| `experimental__woocommerce_blocks-checkout-submit` | None |
+| `experimental__woocommerce_blocks-checkout-set-selected-shipping-rate` | `shippingRateId` |
+| `experimental__woocommerce_blocks-checkout-set-active-payment-method` | `paymentMethodSlug` |
+| `experimental__woocommerce_blocks-checkout-render-checkout-form` | None |
+| `experimental__woocommerce_blocks-checkout-set-email-address` | None |
+| `experimental__woocommerce_blocks-checkout-set-shipping-address` | None |
+| `experimental__woocommerce_blocks-checkout-set-billing-address` | None |
-#### `experimental__woocommerce_blocks-product-render`
-
-Fired when a single product block is rendered.
-
-This documentation will be amended following a review of this action.
-
-#### `experimental__woocommerce_blocks-checkout-submit`
-
-Fired when the checkout form is submitted.
-
-##### Args
-
-This action has no arguments.
-
-##### Example
+Examples:
```js
wp.hooks.addAction(
'experimental__woocommerce_blocks-checkout-submit',
'plugin/namespace',
- () => {
- console.log( 'The checkout form was submitted.' );
+ ( { storeCart } ) => {
+ console.log( 'The checkout form was submitted', storeCart );
}
);
-```
-
-#### `experimental__woocommerce_blocks-checkout-set-selected-shipping-rate
-
-Fired when a shipping rate is chosen on checkout.
-##### Args
-
-| Argument | Type | Description |
-|------------|----------|--------------------------------|
-| `shippingRateId` | `string` | The selected shipping rate ID. |
-
-##### Example
-
-```js
wp.hooks.addAction(
'experimental__woocommerce_blocks-checkout-set-selected-shipping-rate',
'plugin/namespace',
- ( { shippingRateId } ) => {
- console.log( `Selected shipping rate was changed to ${ shippingRateId }` );
+ ( { shippingRateId, storeCart } ) => {
+ console.log( `Selected shipping rate: ${ shippingRateId }`, storeCart );
}
);
-```
-
-#### `experimental__woocommerce_blocks-checkout-set-active-payment-method`
-
-Fired when a payment method is chosen on checkout.
-
-##### Args
-
-| Argument | Type | Description |
-|------------|----------|----------------------------------|
-| `paymentMethodSlug` | `string` | The payment method slug. |
-
-##### Example
-```js
wp.hooks.addAction(
'experimental__woocommerce_blocks-checkout-set-active-payment-method',
'plugin/namespace',
- ( { paymentMethodSlug } ) => {
- console.log( `The selected payment method was changed to ${ paymentMethodSlug }` );
+ ( { paymentMethodSlug, storeCart } ) => {
+ console.log( `Selected payment method: ${ paymentMethodSlug }`, storeCart );
}
);
-```
-
-#### `experimental__woocommerce_blocks-checkout-render-checkout-form`
-
-Fired when the checkout form is rendered.
-
-##### Args
-This action has no arguments.
-
-##### Example
-
-```js
wp.hooks.addAction(
'experimental__woocommerce_blocks-checkout-render-checkout-form',
'plugin/namespace',
- () => {
- console.log( 'The checkout form was rendered.' );
+ ( { storeCart } ) => {
+ console.log( 'The checkout form was rendered', storeCart );
}
);
-```
-
-#### `experimental__woocommerce_blocks-checkout-set-email-address`
-Fired when the email address is added or changed on the Checkout block.
-
-##### Args
-
-This action has no arguments.
-
-##### Example
-
-```js
wp.hooks.addAction(
'experimental__woocommerce_blocks-checkout-set-email-address',
'plugin/namespace',
- () => {
- console.log( 'The email address was changed.' );
+ ( { storeCart } ) => {
+ console.log( 'The email address changed', storeCart );
}
);
-```
-
-#### `experimental__woocommerce_blocks-checkout-set-shipping-address`
-
-Fired when the shipping address is added or changed on the Checkout block.
-
-##### Args
-
-This action has no arguments.
-##### Example
-
-```js
wp.hooks.addAction(
'experimental__woocommerce_blocks-checkout-set-shipping-address',
'plugin/namespace',
- () => {
- console.log( 'The shipping address was changed.' );
+ ( { storeCart } ) => {
+ console.log( 'The shipping address changed', storeCart );
}
);
-```
-
-#### `experimental__woocommerce_blocks-checkout-set-billing-address`
-
-Fired when the billing address is added or changed on the Checkout block.
-##### Args
-
-This action has no arguments.
-
-##### Example
-
-```js
wp.hooks.addAction(
'experimental__woocommerce_blocks-checkout-set-billing-address',
'plugin/namespace',
- () => {
- console.log( 'The billing address was changed.' );
+ ( { storeCart } ) => {
+ console.log( 'The billing address changed', storeCart );
}
);
```