[Docs] Add callout to selection components with a link to selection c…

…omponents FAQ (#7053) Co-authored-by: Cee Chen <549407+cee-chen@users.noreply.github.com>
elastic · Aug 9, 2023 · 17ad68f · 17ad68f
1 parent d49b59a
commit 17ad68f
Show file tree

Hide file tree

Showing 4 changed files with 71 additions and 38 deletions.
diff --git a/src-docs/src/views/combo_box/combo_box_example.js b/src-docs/src/views/combo_box/combo_box_example.js
@@ -3,13 +3,13 @@ import React from 'react';
 import { Link } from 'react-router-dom';
 
 import { GuideSectionTypes } from '../../components';
-import { EuiCallOut } from '../../../../src';
 
 import {
   EuiLink,
   EuiCode,
   EuiComboBox,
   EuiText,
+  EuiCallOut,
 } from '../../../../src/components';
 
 import { EuiComboBoxOptionOption } from '!!prop-loader!../../../../src/components/combo_box/types';
@@ -245,31 +245,36 @@ const labelledbySnippet = `<EuiComboBox
 export const ComboBoxExample = {
   title: 'Combo box',
   intro: (
-    <>
-      <EuiText>
-        <p>
-          Use a <strong>EuiComboBox</strong> when the input has so many options
-          that the user needs to be able to search them, the user needs to be
-          able to select multiple options, and/or the user should have the
-          ability to specify a custom value in addition to selecting from a
-          predetermined list.
-        </p>
-        <EuiCallOut
-          iconType="accessibility"
-          title={
-            <>
-              You must add an accessible label to each instance of{' '}
-              <strong>EuiComboBox</strong>
-            </>
-          }
+    <EuiText>
+      <p>
+        Use a <strong>EuiComboBox</strong> when the input has so many options
+        that the user needs to be able to search them, the user needs to be able
+        to select multiple options, and/or the user should have the ability to
+        specify a custom value in addition to selecting from a predetermined
+        list. If you're unsure of which selection component to use, see{' '}
+        <EuiLink
+          href="https://github.com/elastic/eui/discussions/7049"
+          target="_blank"
         >
-          Labels can be created by wrapping the combo box in an{' '}
-          <strong>EuiFormRow</strong> with a <EuiCode>label</EuiCode>, adding an{' '}
-          <EuiCode>aria-label</EuiCode> prop, or passing a text node ID to the{' '}
-          <EuiCode>aria-labelledby</EuiCode> prop.
-        </EuiCallOut>
-      </EuiText>
-    </>
+          EUI's in-depth guide to selection components
+        </EuiLink>{' '}
+        for more information.
+      </p>
+      <EuiCallOut
+        iconType="accessibility"
+        title={
+          <>
+            You must add an accessible label to each instance of{' '}
+            <strong>EuiComboBox</strong>
+          </>
+        }
+      >
+        Labels can be created by wrapping the combo box in an{' '}
+        <strong>EuiFormRow</strong> with a <EuiCode>label</EuiCode>, adding an{' '}
+        <EuiCode>aria-label</EuiCode> prop, or passing a text node ID to the{' '}
+        <EuiCode>aria-labelledby</EuiCode> prop.
+      </EuiCallOut>
+    </EuiText>
   ),
   sections: [
     {

diff --git a/src-docs/src/views/form_controls/form_controls_example.js b/src-docs/src/views/form_controls/form_controls_example.js
@@ -321,17 +321,15 @@ export const FormControlsExample = {
             .
           </p>
           <p>
-            If you need more customization for how the options and/or selected
-            values render, you can use an{' '}
-            <Link to="/forms/super-select">
-              <strong>EuiSuperSelect</strong>
-            </Link>{' '}
-            instead. For long lists of options use an{' '}
-            <Link to="/forms/combo-box">
-              <strong>EuiComboBox</strong>
-            </Link>
-            , which has search and multi-select capabilities, but also has
-            restrictions on how items are rendered.
+            If you need more customization for searching or rendering options,
+            see{' '}
+            <EuiLink
+              href="https://github.com/elastic/eui/discussions/7049"
+              target="_blank"
+            >
+              EUI's guide on selection components
+            </EuiLink>{' '}
+            .
           </p>
         </>
       ),

diff --git a/src-docs/src/views/selectable/selectable_example.js b/src-docs/src/views/selectable/selectable_example.js
@@ -9,6 +9,7 @@ import {
   EuiSelectableMessage,
   EuiText,
   EuiCallOut,
+  EuiLink,
 } from '../../../../src';
 
 import {
@@ -69,7 +70,14 @@ export const SelectableExample = {
         </strong>{' '}
         but can be used to simplify the construction of popover navigational
         menus; i.e. the spaces menu in the{' '}
-        <Link to="/layout/header">header</Link>.
+        <Link to="/layout/header">header</Link>. See{' '}
+        <EuiLink
+          href="https://github.com/elastic/eui/discussions/7049"
+          target="_blank"
+        >
+          EUI's in-depth guide on which selection component to use{' '}
+        </EuiLink>{' '}
+        for more information.
       </p>
     </EuiText>
   ),

diff --git a/src-docs/src/views/super_select/super_select_example.js b/src-docs/src/views/super_select/super_select_example.js
@@ -2,7 +2,12 @@ import React from 'react';
 
 import { GuideSectionTypes } from '../../components';
 
-import { EuiCode, EuiSuperSelect } from '../../../../src/components';
+import {
+  EuiCode,
+  EuiSuperSelect,
+  EuiLink,
+  EuiCallOut,
+} from '../../../../src/components';
 
 import SuperSelectBasic from './super_select_basic';
 const superSelectBasicSource = require('!!raw-loader!./super_select_basic');
@@ -54,6 +59,23 @@ const superSelectStatesSnippet = `<EuiSuperSelect
 
 export const SuperSelectExample = {
   title: 'Super select',
+  intro: (
+    <EuiCallOut
+      iconType="questionInCircle"
+      title="Not sure which selection component to use?"
+    >
+      <p>
+        See{' '}
+        <EuiLink
+          href="https://github.com/elastic/eui/discussions/7049"
+          target="_blank"
+        >
+          EUI's in-depth guide to selection components{' '}
+        </EuiLink>{' '}
+        for more information.
+      </p>
+    </EuiCallOut>
+  ),
   sections: [
     {
       source: [