Add documentation

src-docs/src/views/guidelines/getting_started/getting_started.js

@@ -7,6 +7,7 @@ import { AppSetup } from './_app_setup';
 import { Tokens } from './_tokens';
 import { Customizing } from './_customizing';
 import { ThemeNotice } from '../../../views/theme/_components/_theme_notice.tsx';
+import { euiProviderComponentDefaultsSnippet } from '../../provider/provider_component_defaults';
 
 export const GettingStarted = {
   title: 'Getting started',
@@ -268,5 +269,29 @@ import { findByTestSubject, render, screen } from '@elastic/eui/lib/test/rtl'; /
         </>
       ),
     },
+    {
+      title: 'Customizing component defaults',
+      wrapText: false,
+      text: (
+        <>
+          <EuiText grow={false}>
+            <p>
+              While all props can be individually customized via props, some
+              components can have their default props customized globally via{' '}
+              <strong>EuiProvider's</strong>{' '}
+              <EuiCode>componentDefaults</EuiCode> API.{' '}
+              <Link to="/utilities/provider#component-defaults">
+                Read more in EuiProvider's documentation
+              </Link>
+              .
+            </p>
+          </EuiText>
+          <EuiSpacer />
+          <EuiCodeBlock language="jsx" isCopyable fontSize="m">
+            {euiProviderComponentDefaultsSnippet}
+          </EuiCodeBlock>
+        </>
+      ),
+    },
   ],
 };

src-docs/src/views/provider/provider_component_defaults.tsx

@@ -0,0 +1,22 @@
+import React, { FunctionComponent } from 'react';
+
+import { EuiComponentDefaults } from '../../../../src/components/provider/component_defaults';
+
+// Used to generate a "component" that is parsed for its types
+// and used to generate a prop table
+export const EuiComponentDefaultsProps: FunctionComponent<
+  EuiComponentDefaults
+> = () => <></>;
+
+// Used by both getting started and EuiProvider component documentation pages
+// Exported in one place for DRYness
+export const euiProviderComponentDefaultsSnippet = `<EuiProvider
+  componentDefaults={{
+    EuiTablePagination: { itemsPerPage: 20, },
+    EuiFocusTrap: { crossFrame: true },
+    EuiPortal: { insert },
+  }}
+>
+  <App />
+</EuiProvider>
+`;

src-docs/src/views/provider/provider_example.js

@@ -8,21 +8,25 @@ import {
   EuiCodeBlock,
   EuiLink,
   EuiSpacer,
+  EuiCallOut,
 } from '../../../../src/components';
 
 import { GuideSectionPropsTable } from '../../components/guide_section/guide_section_parts/guide_section_props_table';
 
 import Setup from './provider_setup';
 import GlobalStyles from './provider_styles';
+import {
+  EuiComponentDefaultsProps,
+  euiProviderComponentDefaultsSnippet,
+} from './provider_component_defaults';
 
 export const ProviderExample = {
   title: 'Provider',
   intro: (
     <EuiText>
       <p>
         <strong>EuiProvider</strong> contains all necessary context providers
-        required for full functionality and styling of EUI. It currently
-        includes the{' '}
+        required for full functionality and styling of EUI. It includes{' '}
         <Link to="/theming/theme-provider">
           <strong>EuiThemeProvider</strong>
         </Link>{' '}
@@ -133,6 +137,65 @@ export const ProviderExample = {
         </EuiText>
       ),
     },
+    {
+      title: 'Component defaults',
+      text: (
+        <EuiText>
+          <EuiCallOut title="Beta status" iconType="beta">
+            <p>
+              This functionality is still currently in beta, and the list of
+              components as well as defaults that EUI will be supporting is
+              still under consideration. If you have a component you would like
+              to see added, feel free to{' '}
+              <EuiLink
+                href="https://github.com/elastic/eui/discussions/6922"
+                target="_blank"
+              >
+                discuss that request in EUI's GitHub repo
+              </EuiLink>
+              .
+            </p>
+          </EuiCallOut>
+          <EuiSpacer />
+
+          <p>
+            All EUI components ship with a set of baseline defaults that can
+            usually be configured via props. For example,{' '}
+            <Link to="/utilities/focus-trap">
+              <strong>EuiFocusTrap</strong>
+            </Link>{' '}
+            defaults to <EuiCode>crossFrame={'{false}'}</EuiCode> - i.e., it
+            does not trap focus between iframes. If you wanted to change that
+            behavior in your app across all instances of{' '}
+            <strong>EuiFocusTrap</strong>, you would be stuck manually passing
+            that prop over and over again, including in higher-level components
+            (like modals, popovers, and flyouts) that utilize focus traps.
+          </p>
+          <p>
+            <strong>EuiProvider</strong> allows overriding some component
+            defaults across all component usages globally via the{' '}
+            <EuiCode>componentDefaults</EuiCode> prop like so:
+          </p>
+
+          <EuiCodeBlock language="jsx" isCopyable fontSize="m">
+            {euiProviderComponentDefaultsSnippet}
+          </EuiCodeBlock>
+
+          <p>
+            The above example would override EUI's default table pagination size
+            (50) across all usages of EUI tables and data grids, all EUI focus
+            traps would trap focus even from iframes, and all EUI portals would
+            be inserted at a specified position (instead of the end of the
+            document body).
+          </p>
+          <p>
+            The current list of supported components and the prop defaults they
+            accept are:
+          </p>
+          <GuideSectionPropsTable component={EuiComponentDefaultsProps} />
+        </EuiText>
+      ),
+    },
     {
       title: 'Enforce usage',
       text: (