[EuiIcon]: Add appendIconComponentCache function (#3481)

* [EuiIcon]:

* Add appendIconComponentCache function to complement the recently-added clearIconComponentCache function.

Use case is to work around issues with the dynamic loading: if an icon is not in the cache, an attempt is made to fetch it dynamically, however some environments (such as using certain bundlers, like Parcel: parcel-bundler/parcel#112) do not transpile this functionality correctly.

Being able to manually manipulate the icon cache allows a work around for this issue.

* Fix appendIconComponentCache type, lint issues; add tests; add documentation

* [EuiIcon]: Implement suggested change to new appendIconComponentCache function: One or more icon(s) are passed in as an object of iconKey (string): IconComponent

* [EuiIcon]:
* Define an empty no-op mock of the `appendIconComponentCache` function in icon.testenv.tsx
* Update the main CHANGELOG.md with a summary of the new `appendIconComponentCache` EuiIcon feature.

Co-authored-by: Chandler Prall <[email protected]>

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.