From 8a0af411bf23e4a5c727a25a7f5209bf87e3ebcb Mon Sep 17 00:00:00 2001
From: Lene Gadewoll <lene.gadewoll@elastic.co>
Date: Wed, 4 Sep 2024 13:47:12 +0200
Subject: [PATCH] styles: enhance component prop JSDoc to add information about
 valid usage

---
 packages/eui/src/components/text/text.tsx       | 5 ++++-
 packages/eui/src/components/text/text_align.tsx | 3 +++
 packages/eui/src/components/text/text_color.tsx | 3 +++
 3 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/packages/eui/src/components/text/text.tsx b/packages/eui/src/components/text/text.tsx
index 06f3a8eb02b..3ccb7052e4f 100644
--- a/packages/eui/src/components/text/text.tsx
+++ b/packages/eui/src/components/text/text.tsx
@@ -23,7 +23,10 @@ export type TextSize = (typeof TEXT_SIZES)[number];
 export type EuiTextProps = CommonProps &
   Omit<HTMLAttributes<HTMLDivElement>, 'color'> & {
     /**
-     * The HTML element/tag to render
+     * The HTML element/tag to render.
+     * Use with care when nesting multiple components to ensure valid html.
+     * Block elements can't be nested inside inline elements: `<p>` and `<div>` are not valid inside `<span>`.
+     * Additionally `<div>` is not valid to use inside `<p>`.
      */
     component?: 'div' | 'span' | 'p';
     textAlign?: TextAlignment;
diff --git a/packages/eui/src/components/text/text_align.tsx b/packages/eui/src/components/text/text_align.tsx
index c775360fc8f..e6cee796be6 100644
--- a/packages/eui/src/components/text/text_align.tsx
+++ b/packages/eui/src/components/text/text_align.tsx
@@ -23,6 +23,9 @@ export type EuiTextAlignProps = CommonProps &
   HTMLAttributes<HTMLDivElement> & {
     /**
      * The HTML element/tag to render
+     * Use with care when nesting multiple components to ensure valid html.
+     * Block elements can't be nested inside inline elements. (<p> and <div> are not valid inside <span>)
+     * Additionally <div> is not valid to use inside <p>.
      */
     component?: 'div' | 'span' | 'p';
     textAlign?: TextAlignment;
diff --git a/packages/eui/src/components/text/text_color.tsx b/packages/eui/src/components/text/text_color.tsx
index e76cf54207b..2a04509bf3c 100644
--- a/packages/eui/src/components/text/text_color.tsx
+++ b/packages/eui/src/components/text/text_color.tsx
@@ -43,6 +43,9 @@ export type EuiTextColorProps = CommonProps &
     color?: TextColor | CSSProperties['color'];
     /**
      * The HTML element/tag to render
+     * Use with care when nesting multiple components to ensure valid html.
+     * Block elements can't be nested inside inline elements. (<p> and <div> are not valid inside <span>)
+     * Additionally <div> is not valid to use inside <p>.
      */
     component?: 'div' | 'span' | 'p';
     /**