[EuiIcon]: Add appendIconComponentCache function

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## [`master`](https://github.com/elastic/eui/tree/master)
 
+- Added `appendIconComponentCache` function to allow manual pre-emptive loading of source elements into the `EuiIcon` cache ([#3481](https://github.com/elastic/eui/pull/3481))
 - Added `initialSelected` to `EuiTableSelectionType` properties to set initial selected checkboxes for `EuiBasicTable` ([#3418](https://github.com/elastic/eui/pull/3418))
 - Added exports for `EuiSteps` and related components types ([#3471](https://github.com/elastic/eui/pull/3471))
 - Added `displayName` to components using `React.forwardRef` ([#3451](https://github.com/elastic/eui/pull/3451))

src/components/icon/icon.test.tsx

@@ -22,8 +22,17 @@ import { mount } from 'enzyme';
 import { requiredProps } from '../../test/required_props';
 import cheerio from 'cheerio';
 
-import { EuiIcon, SIZES, TYPES, COLORS, clearIconComponentCache } from './icon';
+import {
+  EuiIcon,
+  SIZES,
+  TYPES,
+  COLORS,
+  clearIconComponentCache,
+  appendIconComponentCache,
+} from './icon';
 import { PropsOf } from '../common';
+// @ts-ignore
+import { icon as EuiIconVideoPlayer } from './assets/videoPlayer.js';
 
 jest.mock('./icon', () => {
   return require.requireActual('./icon');
@@ -126,4 +135,34 @@ describe('EuiIcon', () => {
     const component = mount(<EuiIcon type={CustomIcon} />);
     expect(prettyHtml(component.html())).toMatchSnapshot();
   });
+
+  describe('appendIconComponentCache', () => {
+    it('does nothing if not called', () => {
+      const component = mount(<EuiIcon type="videoPlayer" />);
+      expect(
+        component.find('EuiIcon[type="videoPlayer"] > EuiIconEmpty').length
+      ).toBe(1);
+    });
+
+    it('injects the specified icon', () => {
+      appendIconComponentCache({
+        videoPlayer: EuiIconVideoPlayer,
+      });
+      const component = mount(<EuiIcon type="videoPlayer" />);
+      expect(
+        component.find('EuiIcon[type="videoPlayer"] > EuiIconVideoPlayer')
+          .length
+      ).toBe(1);
+    });
+
+    it('does not impact non-loaded icons', () => {
+      appendIconComponentCache({
+        videoPlayer: EuiIconVideoPlayer,
+      });
+      const component = mount(<EuiIcon type="accessibility" />);
+      expect(
+        component.find('EuiIcon[type="accessibility"] > EuiIconEmpty').length
+      ).toBe(1);
+    });
+  });
 });

src/components/icon/icon.testenv.tsx

@@ -17,11 +17,18 @@
  * under the License.
  */
 
-import React from 'react';
+import React, { ComponentType } from 'react';
+
 export const EuiIcon = ({ type, ...rest }: any) => (
   <div data-euiicon-type={type} {...rest} />
 );
 
+export const appendIconComponentCache = (_: {
+  [iconType: string]: ComponentType;
+}) => {
+  // manually appending to the internal EuiIcon cache is out-of-scope of this test environment
+};
+
 export const TYPES = [];
 export const COLORS = [];
 export const SIZES = [];

src/components/icon/icon.tsx

@@ -534,15 +534,26 @@ function getInitialIcon(icon: EuiIconProps['type']) {
 
 const generateId = htmlIdGenerator();
 
-let iconComponentCache: { [key: string]: ComponentType } = {};
-export const clearIconComponentCache = (icon?: EuiIconType) => {
-  if (icon != null) {
-    delete iconComponentCache[icon];
+let iconComponentCache: { [iconType: string]: ComponentType } = {};
+
+export const clearIconComponentCache = (iconType?: EuiIconType) => {
+  if (iconType != null) {
+    delete iconComponentCache[iconType];
   } else {
     iconComponentCache = {};
   }
 };
 
+export const appendIconComponentCache = (iconTypeToIconComponentMap: {
+  [iconType: string]: ComponentType;
+}) => {
+  for (const iconType in iconTypeToIconComponentMap) {
+    if (iconTypeToIconComponentMap.hasOwnProperty(iconType)) {
+      iconComponentCache[iconType] = iconTypeToIconComponentMap[iconType];
+    }
+  }
+};
+
 export class EuiIcon extends PureComponent<EuiIconProps, State> {
   isMounted = true;
   constructor(props: EuiIconProps) {

wiki/consuming.md

@@ -100,6 +100,23 @@ ReactDOM.render(
 
 If you get an error when importing a React component, you might need to configure Webpack's `resolve.mainFields` to `['webpack', 'browser', 'main']` to import the components from `lib` instead of `src`. See the [Webpack docs](https://webpack.js.org/configuration/resolve/#resolve-mainfields) for more info.
 
+### Failing icon imports
+
+To reduce EUI's impact to application bundle sizes, the icons are dynamically imported on-demand. This is problematic for some bundlers and/or deployments, so a method exists to preload specific icons an application needs.
+
+```javascript
+import { appendIconComponentCache } from '@elastic/eui/es/components/icon/icon';
+
+import { icon as EuiIconArrowDown } from '@elastic/eui/es/components/icon/assets/arrow_down';
+import { icon as EuiIconArrowLeft } from '@elastic/eui/es/components/icon/assets/arrow_left';
+
+// One or more icons are passed in as an object of iconKey (string): IconComponent
+appendIconComponentCache({
+  arrowDown: EuiIconArrowDown,
+  arrowLeft: EuiIconArrowLeft,
+});
+``` 
+
 ## Customizing with `className`
 
 We do not recommend customizing EUI components by applying styles directly to EUI classes, eg. `.euiButton`. All components allow you to pass a custom `className` prop directly to the component which will then append this to the class list. Utilizing the cascade feature of CSS, you can then customize by overriding styles so long as your styles are imported **after** the EUI import.