From e6e0ea8906c0fb01ea132e3386d5e42172614ba9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Greg=20Zi=C3=B3=C5=82kowski?= <grzegorz@gziolo.pl>
Date: Mon, 24 May 2021 16:35:53 +0200
Subject: [PATCH] Components: Mark all experimental components in the handbook
 (#32147)

Inspired by the alert for Global Settings and Styles (theme.json):
https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/
---
 packages/components/src/box-control/README.md        |  4 ++++
 packages/components/src/dimension-control/README.md  |  4 ++++
 packages/components/src/divider/README.md            |  4 ++++
 packages/components/src/elevation/README.md          |  6 +++++-
 packages/components/src/flex/flex-block/README.md    |  4 +++-
 packages/components/src/flex/flex-item/README.md     |  4 +++-
 packages/components/src/flex/flex/README.md          |  4 +++-
 packages/components/src/grid/README.md               |  6 ++++--
 packages/components/src/h-stack/README.md            |  6 ++++--
 packages/components/src/heading/README.md            |  4 +++-
 packages/components/src/input-control/README.md      |  4 ++++
 packages/components/src/navigation/README.md         |  4 ++++
 packages/components/src/number-control/README.md     |  4 ++++
 packages/components/src/radio-group/README.md        |  4 ++++
 packages/components/src/spacer/README.md             | 10 +++++-----
 packages/components/src/text/README.md               |  4 +++-
 packages/components/src/tree-grid/README.md          |  5 ++++-
 packages/components/src/truncate/README.md           |  4 +++-
 packages/components/src/ui/card/README.md            |  4 ++++
 packages/components/src/ui/control-group/README.md   |  4 ++++
 packages/components/src/ui/control-label/README.md   |  4 ++++
 packages/components/src/ui/form-group/README.md      |  4 ++++
 packages/components/src/ui/popover/README.md         |  4 ++++
 packages/components/src/ui/scrollable/README.md      |  4 ++++
 packages/components/src/ui/spinner/README.md         |  4 ++++
 packages/components/src/ui/surface/README.md         |  4 ++++
 packages/components/src/ui/tooltip/README.md         |  4 ++++
 packages/components/src/ui/visually-hidden/README.md |  4 ++++
 packages/components/src/unit-control/README.md       |  4 ++++
 packages/components/src/v-stack/README.md            |  6 ++++--
 packages/components/src/view/README.md               |  6 ++++--
 packages/components/src/z-stack/README.md            |  4 +++-
 32 files changed, 123 insertions(+), 22 deletions(-)

diff --git a/packages/components/src/box-control/README.md b/packages/components/src/box-control/README.md
index 80cfce66896421..77543aa0fba68a 100644
--- a/packages/components/src/box-control/README.md
+++ b/packages/components/src/box-control/README.md
@@ -1,5 +1,9 @@
 # BoxControl
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 BoxControl components let users set values for Top, Right, Bottom, and Left. This can be used as an input control for values like `padding` or `margin`.
 
 ## Usage
diff --git a/packages/components/src/dimension-control/README.md b/packages/components/src/dimension-control/README.md
index 6eda6430a488c0..7c627b7fbe2666 100644
--- a/packages/components/src/dimension-control/README.md
+++ b/packages/components/src/dimension-control/README.md
@@ -1,5 +1,9 @@
 # DimensionControl
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `DimensionControl` is a component designed to provide a UI to control spacing and/or dimensions.
 
 ## Usage
diff --git a/packages/components/src/divider/README.md b/packages/components/src/divider/README.md
index a793646650ee1d..ae9b961dad5e54 100644
--- a/packages/components/src/divider/README.md
+++ b/packages/components/src/divider/README.md
@@ -1,5 +1,9 @@
 # Divider
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `Divider` is a layout component that separates groups of related content.
 
 ## Usage
diff --git a/packages/components/src/elevation/README.md b/packages/components/src/elevation/README.md
index 134948c4e801d2..0e61fe7db0a750 100644
--- a/packages/components/src/elevation/README.md
+++ b/packages/components/src/elevation/README.md
@@ -1,5 +1,9 @@
 # Elevation
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `Elevation` is a core component that renders shadow, using the component system's shadow system.
 
 ## Usage
@@ -10,7 +14,7 @@ The shadow effect is generated using the `value` prop.
 import {
 	__experimentalElevation as Elevation,
 	__experimentalSurface as Surface,
-	__experimentalText as Text
+	__experimentalText as Text,
 } from '@wordpress/components';
 
 function Example() {
diff --git a/packages/components/src/flex/flex-block/README.md b/packages/components/src/flex/flex-block/README.md
index b5cbe861f6d669..691f1b0ad33c0e 100644
--- a/packages/components/src/flex/flex-block/README.md
+++ b/packages/components/src/flex/flex-block/README.md
@@ -1,6 +1,8 @@
 # FlexBlock
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 A layout component to contain items of a fixed width within `Flex`.
 
diff --git a/packages/components/src/flex/flex-item/README.md b/packages/components/src/flex/flex-item/README.md
index 6a6fc038263270..2aec78afe35c29 100644
--- a/packages/components/src/flex/flex-item/README.md
+++ b/packages/components/src/flex/flex-item/README.md
@@ -1,6 +1,8 @@
 # FlexItem
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 A layout component to contain items of a fixed width within `Flex`.
 
diff --git a/packages/components/src/flex/flex/README.md b/packages/components/src/flex/flex/README.md
index 2ca42bb44baa58..55a7b8b15ecc55 100644
--- a/packages/components/src/flex/flex/README.md
+++ b/packages/components/src/flex/flex/README.md
@@ -1,6 +1,8 @@
 # Flex
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 `Flex` is a primitive layout component that adaptively aligns child content horizontally or vertically. `Flex` powers components like `HStack` and `VStack`.
 
diff --git a/packages/components/src/grid/README.md b/packages/components/src/grid/README.md
index 6765ff856b3d0d..27695353d54c2a 100644
--- a/packages/components/src/grid/README.md
+++ b/packages/components/src/grid/README.md
@@ -1,6 +1,8 @@
 # Grid
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 `Grid` is a primitive layout component that can arrange content in a grid configuration.
 
@@ -9,7 +11,7 @@
 ```jsx
 import {
 	__experimentalGrid as Grid,
-	__experimentalText as Text
+	__experimentalText as Text,
 } from '@wordpress/components';
 
 function Example() {
diff --git a/packages/components/src/h-stack/README.md b/packages/components/src/h-stack/README.md
index 99182bb3e7b9ae..a0b63c7521fcb1 100644
--- a/packages/components/src/h-stack/README.md
+++ b/packages/components/src/h-stack/README.md
@@ -1,6 +1,8 @@
 # HStack
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 `HStack` (Horizontal Stack) arranges child elements in a horizontal line.
 
@@ -93,7 +95,7 @@ function Example() {
 		<HStack>
 			<Text>Code</Text>
 			<Spacer>
-			<Text>is</Text>
+				<Text>is</Text>
 			</Spacer>
 			<Text>Poetry</Text>
 		</HStack>
diff --git a/packages/components/src/heading/README.md b/packages/components/src/heading/README.md
index c686ccf49b9715..f96fe871add758 100644
--- a/packages/components/src/heading/README.md
+++ b/packages/components/src/heading/README.md
@@ -1,6 +1,8 @@
 # Heading
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 `Heading` renders headings and titles using the library's typography system.
 
diff --git a/packages/components/src/input-control/README.md b/packages/components/src/input-control/README.md
index fef516a7a3f187..63a0c509010144 100644
--- a/packages/components/src/input-control/README.md
+++ b/packages/components/src/input-control/README.md
@@ -1,5 +1,9 @@
 # InputControl
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 InputControl components let users enter and edit text. This is an experimental component intended to (in time) merge with or replace [TextControl](../text-control).
 
 ## Usage
diff --git a/packages/components/src/navigation/README.md b/packages/components/src/navigation/README.md
index b793489d5a0002..1128874463d574 100644
--- a/packages/components/src/navigation/README.md
+++ b/packages/components/src/navigation/README.md
@@ -1,5 +1,9 @@
 # Navigation
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 Render a navigation list with optional groupings and hierarchy.
 
 ## Usage
diff --git a/packages/components/src/number-control/README.md b/packages/components/src/number-control/README.md
index efb77dd18a40a8..b233502f92f6a1 100644
--- a/packages/components/src/number-control/README.md
+++ b/packages/components/src/number-control/README.md
@@ -1,5 +1,9 @@
 # NumberControl
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 NumberControl is an enhanced HTML [`input[type="number]`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number) element.
 
 ## Usage
diff --git a/packages/components/src/radio-group/README.md b/packages/components/src/radio-group/README.md
index 6c3b0d84633a26..721ff07d33a9f1 100644
--- a/packages/components/src/radio-group/README.md
+++ b/packages/components/src/radio-group/README.md
@@ -1,5 +1,9 @@
 # RadioGroup
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 Use a RadioGroup component when you want users to select one option from a small set of options.
 
 ![RadioGroup component](https://wordpress.org/gutenberg/files/2018/12/s_96EC471FE9C9D91A996770229947AAB54A03351BDE98F444FD3C1BF0CED365EA_1541792995815_ButtonGroup.png)
diff --git a/packages/components/src/spacer/README.md b/packages/components/src/spacer/README.md
index 1aad9670c082f5..7bc5b01abf42d3 100644
--- a/packages/components/src/spacer/README.md
+++ b/packages/components/src/spacer/README.md
@@ -1,6 +1,8 @@
 # Spacer
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 `Spacer` is a primitive layout component that providers inner (`padding`) or outer (`margin`) space in-between components. It can also be used to adaptively provide space within an `HStack` or `VStack`.
 
@@ -14,7 +16,7 @@
 import {
 	__experimentalSpacer as Spacer,
 	__experimentalHeading as Heading,
-	__experimentalView as View
+	__experimentalView as View,
 } from '@wordpress/components';
 
 function Example() {
@@ -23,9 +25,7 @@ function Example() {
 			<Spacer>
 				<Heading>WordPress.org</Heading>
 			</Spacer>
-			<Text>
-				Code is Poetry
-			</Text>
+			<Text>Code is Poetry</Text>
 		</View>
 	);
 }
diff --git a/packages/components/src/text/README.md b/packages/components/src/text/README.md
index 72a1831a251914..7747ec9cbc7277 100644
--- a/packages/components/src/text/README.md
+++ b/packages/components/src/text/README.md
@@ -1,6 +1,8 @@
 # Text
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 `Text` is a core component that renders text in the library, using the library's typography system.
 
diff --git a/packages/components/src/tree-grid/README.md b/packages/components/src/tree-grid/README.md
index eaedacdfe6f55c..3806d7cc66fd34 100644
--- a/packages/components/src/tree-grid/README.md
+++ b/packages/components/src/tree-grid/README.md
@@ -1,5 +1,8 @@
-# TreeGrid (experimental)
+# TreeGrid
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 ## Table of contents
 
 1. [Development guidelines](#development-guidelines)
diff --git a/packages/components/src/truncate/README.md b/packages/components/src/truncate/README.md
index 494c99dd9720cf..f7c72f53f884a1 100644
--- a/packages/components/src/truncate/README.md
+++ b/packages/components/src/truncate/README.md
@@ -1,6 +1,8 @@
 # Truncate
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 `Truncate` is a typography primitive that trims text content. For almost all cases, it is recommended that `Text`, `Heading`, or `Subheading` is used to render text content. However, `Truncate` is available for custom implementations.
 
diff --git a/packages/components/src/ui/card/README.md b/packages/components/src/ui/card/README.md
index 447a2b10bfcc42..56c2bef2af5cee 100644
--- a/packages/components/src/ui/card/README.md
+++ b/packages/components/src/ui/card/README.md
@@ -1,5 +1,9 @@
 # Card
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `Card` groups similar concepts and tasks together. `Card`'s background is rendered with a `Surface`.
 
 ## Usage
diff --git a/packages/components/src/ui/control-group/README.md b/packages/components/src/ui/control-group/README.md
index 3e7f9760fb9c9a..122a6a612a32c1 100644
--- a/packages/components/src/ui/control-group/README.md
+++ b/packages/components/src/ui/control-group/README.md
@@ -1,5 +1,9 @@
 # ControlGroup
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `ControlGroup` is a layout-based component for rendering a group of control-based components, such as `Button`, `Select` or `TextInput`. Control components that render within `ControlGroup` automatically have their borders offset and border-radii rounded.
 
 ## Usage
diff --git a/packages/components/src/ui/control-label/README.md b/packages/components/src/ui/control-label/README.md
index ee6dd9a31329d6..d4e31e034dfd80 100644
--- a/packages/components/src/ui/control-label/README.md
+++ b/packages/components/src/ui/control-label/README.md
@@ -1,5 +1,9 @@
 # ControlLabel
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `ControlLabel` is a form component that works with `FormGroup` to provide a label for form elements (e.g. `Switch` or `TextInput`).
 
 ## Usage
diff --git a/packages/components/src/ui/form-group/README.md b/packages/components/src/ui/form-group/README.md
index 69b65aabc638ca..fec4316caf3553 100644
--- a/packages/components/src/ui/form-group/README.md
+++ b/packages/components/src/ui/form-group/README.md
@@ -1,5 +1,9 @@
 # FormGroup
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `FormGroup` is a form component that groups a label with a form element (e.g. `Switch` or `TextInput`).
 
 ## Usage
diff --git a/packages/components/src/ui/popover/README.md b/packages/components/src/ui/popover/README.md
index 294d43a0380d1d..028d093818749d 100644
--- a/packages/components/src/ui/popover/README.md
+++ b/packages/components/src/ui/popover/README.md
@@ -1,5 +1,9 @@
 # Popover
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `Popover` is a component to render a floating content modal. It is similar in purpose to a tooltip, but renders content of any sort, not only simple text.
 
 ## Usage
diff --git a/packages/components/src/ui/scrollable/README.md b/packages/components/src/ui/scrollable/README.md
index a3996eab2dcc05..e098a2683d7c4f 100644
--- a/packages/components/src/ui/scrollable/README.md
+++ b/packages/components/src/ui/scrollable/README.md
@@ -1,5 +1,9 @@
 # Scrollable
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `Scrollable` is a layout component that content in a scrollable container.
 
 ## Usage
diff --git a/packages/components/src/ui/spinner/README.md b/packages/components/src/ui/spinner/README.md
index 7f611ea6c88325..5e25f9992d0c32 100644
--- a/packages/components/src/ui/spinner/README.md
+++ b/packages/components/src/ui/spinner/README.md
@@ -1,5 +1,9 @@
 # Spinner
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `Spinner` is a component that notify users that their action is being processed.
 
 ## Usage
diff --git a/packages/components/src/ui/surface/README.md b/packages/components/src/ui/surface/README.md
index c3481f0ffa9426..3e82138864cf45 100644
--- a/packages/components/src/ui/surface/README.md
+++ b/packages/components/src/ui/surface/README.md
@@ -1,5 +1,9 @@
 # Surface
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `Surface` is a core component that renders a primary background color.
 
 ## Usage
diff --git a/packages/components/src/ui/tooltip/README.md b/packages/components/src/ui/tooltip/README.md
index ac9e3789c84520..424da79828a487 100644
--- a/packages/components/src/ui/tooltip/README.md
+++ b/packages/components/src/ui/tooltip/README.md
@@ -1,5 +1,9 @@
 # Tooltip
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `Tooltip` is a component to render floating help text relative to a node when it receives focus or when the user places the mouse cursor atop it.
 
 ## Usage
diff --git a/packages/components/src/ui/visually-hidden/README.md b/packages/components/src/ui/visually-hidden/README.md
index 6200eed80dacb1..756311c8043cac 100644
--- a/packages/components/src/ui/visually-hidden/README.md
+++ b/packages/components/src/ui/visually-hidden/README.md
@@ -1,5 +1,9 @@
 # VisuallyHidden
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 `VisuallyHidden` is a component used to render text intended to be visually hidden, but will show for alternate devices, for example a screen reader.
 
 ## Usage
diff --git a/packages/components/src/unit-control/README.md b/packages/components/src/unit-control/README.md
index b024e6aaf5e5ee..5c681ff2ca40a8 100644
--- a/packages/components/src/unit-control/README.md
+++ b/packages/components/src/unit-control/README.md
@@ -1,5 +1,9 @@
 # UnitControl
 
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
 UnitControl allows the user to set a value as well as a unit (e.g. `px`).
 
 ## Usage
diff --git a/packages/components/src/v-stack/README.md b/packages/components/src/v-stack/README.md
index ba2132804f78f2..e1fbba7f90d165 100644
--- a/packages/components/src/v-stack/README.md
+++ b/packages/components/src/v-stack/README.md
@@ -1,6 +1,8 @@
 # VStack
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 `VStack` (or Vertical Stack) is a layout component that arranges child elements in a vertical line.
 
@@ -93,7 +95,7 @@ function Example() {
 		<VStack>
 			<Text>Code</Text>
 			<Spacer>
-			<Text>is</Text>
+				<Text>is</Text>
 			</Spacer>
 			<Text>Poetry</Text>
 		</VStack>
diff --git a/packages/components/src/view/README.md b/packages/components/src/view/README.md
index f991f2d95c7334..794d7b49a0d386 100644
--- a/packages/components/src/view/README.md
+++ b/packages/components/src/view/README.md
@@ -1,6 +1,8 @@
 # View
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 `View` is a core component that renders everything in the library. It is the principle component in the entire library.
 
@@ -11,7 +13,7 @@
 ```jsx
 import {
 	__experimentalText as Text,
-	__experimentalView as View
+	__experimentalView as View,
 } from '@wordpress/components';
 
 function Example() {
diff --git a/packages/components/src/z-stack/README.md b/packages/components/src/z-stack/README.md
index 6a4a31fb38b9f9..7f07104b0654fc 100644
--- a/packages/components/src/z-stack/README.md
+++ b/packages/components/src/z-stack/README.md
@@ -1,6 +1,8 @@
 # ZStack
 
-> **Experimental!**
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
 ## Usage