KibanaErrorBoundary initial implementation

.github/CODEOWNERS

@@ -680,6 +680,7 @@ packages/shared-ux/card/no_data/impl @elastic/appex-sharedux
 packages/shared-ux/card/no_data/mocks @elastic/appex-sharedux
 packages/shared-ux/card/no_data/types @elastic/appex-sharedux
 packages/shared-ux/chrome/navigation @elastic/appex-sharedux
+packages/shared-ux/error_boundary @elastic/appex-sharedux
 packages/shared-ux/file/context @elastic/appex-sharedux
 packages/shared-ux/file/image/impl @elastic/appex-sharedux
 packages/shared-ux/file/image/mocks @elastic/appex-sharedux

package.json

@@ -683,6 +683,7 @@
     "@kbn/shared-ux-card-no-data-mocks": "link:packages/shared-ux/card/no_data/mocks",
     "@kbn/shared-ux-card-no-data-types": "link:packages/shared-ux/card/no_data/types",
     "@kbn/shared-ux-chrome-navigation": "link:packages/shared-ux/chrome/navigation",
+    "@kbn/shared-ux-error-boundary": "link:packages/shared-ux/error_boundary",
     "@kbn/shared-ux-file-context": "link:packages/shared-ux/file/context",
     "@kbn/shared-ux-file-image": "link:packages/shared-ux/file/image/impl",
     "@kbn/shared-ux-file-image-mocks": "link:packages/shared-ux/file/image/mocks",

packages/kbn-ui-shared-deps-src/BUILD.bazel

@@ -33,6 +33,7 @@ webpack_cli(
     "//packages/kbn-peggy",
     "//packages/kbn-peggy-loader",
     "//packages/kbn-rison",
+    "//packages/shared-ux/error-boundary",
   ],
   output_dir = True,
   args = [

packages/kbn-ui-shared-deps-src/src/definitions.js

@@ -92,6 +92,7 @@ const externals = {
   '@kbn/std': '__kbnSharedDeps__.KbnStd',
   '@kbn/safer-lodash-set': '__kbnSharedDeps__.SaferLodashSet',
   '@kbn/rison': '__kbnSharedDeps__.KbnRison',
+  '@kbn/shared-ux-error-boundary': '__kbnSharedDeps__.KibanaErrorBoundary',
   history: '__kbnSharedDeps__.History',
   classnames: '__kbnSharedDeps__.Classnames',
   '@tanstack/react-query': '__kbnSharedDeps__.ReactQuery',

packages/kbn-ui-shared-deps-src/src/entry.js

@@ -67,6 +67,7 @@ export const KbnEsQuery = require('@kbn/es-query');
 export const KbnStd = require('@kbn/std');
 export const SaferLodashSet = require('@kbn/safer-lodash-set');
 export const KbnRison = require('@kbn/rison');
+export const KibanaErrorBoundary = require('@kbn/shared-ux-error-boundary');
 export const History = require('history');
 export const Classnames = require('classnames');
 export const ReactQuery = require('@tanstack/react-query');

packages/shared-ux/error_boundary/README.mdx

@@ -0,0 +1,16 @@
+---
+id: sharedUX/KibanaErrorBoundary
+slug: /shared-ux/error_boundary/kibana_error_boundary
+title: Kibana Error Boundary
+description: Container to catch errors thrown by child component
+tags: ['shared-ux', 'component', 'error', 'error_boundary']
+date: 2023-10-03
+---
+
+## Description
+
+## API
+
+## EUI Promotion Status
+
+This component is specialized for error messages internal to Kibana and is not intended for promotion to EUI.

packages/shared-ux/error_boundary/index.ts

@@ -0,0 +1,10 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export { KibanaErrorBoundary } from './src/ui/error_boundary';
+export { KibanaErrorBoundaryProvider } from './src/services/error_boundary_services';

packages/shared-ux/error_boundary/jest.config.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+module.exports = {
+  preset: '@kbn/test',
+  rootDir: '../../..',
+  roots: ['<rootDir>/packages/shared-ux/error_boundary'],
+};

packages/shared-ux/error_boundary/kibana.jsonc

@@ -0,0 +1,5 @@
+{
+  "type": "shared-common",
+  "id": "@kbn/shared-ux-error-boundary",
+  "owner": "@elastic/appex-sharedux"
+}

packages/shared-ux/error_boundary/mocks/index.ts

@@ -0,0 +1,12 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export { BadComponent } from './src/bad_component';
+export { ChunkLoadErrorComponent } from './src/chunk_load_error_component';
+export { getServicesMock } from './src/jest';
+export { KibanaErrorBoundaryStorybookMock } from './src/storybook';

packages/shared-ux/error_boundary/mocks/src/bad_component.tsx

@@ -0,0 +1,31 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { EuiButton } from '@elastic/eui';
+import { action } from '@storybook/addon-actions';
+import React, { useState } from 'react';
+
+export const BadComponent = () => {
+  const [hasError, setHasError] = useState(false);
+
+  if (hasError) {
+    throw new Error('This is an error to show the test user!'); // custom error
+  }
+
+  const clickedForError = action('clicked for error');
+  const handleClick = () => {
+    clickedForError();
+    setHasError(true);
+  };
+
+  return (
+    <EuiButton onClick={handleClick} data-test-subj="clickForErrorBtn">
+      Click for error
+    </EuiButton>
+  );
+};

packages/shared-ux/error_boundary/mocks/src/chunk_load_error_component.tsx

@@ -0,0 +1,33 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { EuiButton } from '@elastic/eui';
+import { action } from '@storybook/addon-actions';
+import React, { useState } from 'react';
+
+export const ChunkLoadErrorComponent = () => {
+  const [hasError, setHasError] = useState(false);
+
+  if (hasError) {
+    const chunkError = new Error('Could not load chunk');
+    chunkError.name = 'ChunkLoadError'; // specific error known to be recoverable with a click of a refresh button
+    throw chunkError;
+  }
+
+  const clickedForError = action('clicked for error');
+  const handleClick = () => {
+    clickedForError();
+    setHasError(true);
+  };
+
+  return (
+    <EuiButton onClick={handleClick} fill={true} data-test-subj="clickForErrorBtn">
+      Click for error
+    </EuiButton>
+  );
+};

packages/shared-ux/error_boundary/mocks/src/jest.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { KibanaErrorService } from '../../src/services/error_service';
+import { KibanaErrorBoundaryServices } from '../../types';
+
+export const getServicesMock = (): KibanaErrorBoundaryServices => {
+  const reloadWindow = jest.fn().mockResolvedValue(undefined);
+  return {
+    reloadWindow,
+    errorService: new KibanaErrorService(),
+  };
+};

packages/shared-ux/error_boundary/mocks/src/storybook.ts

@@ -0,0 +1,43 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { AbstractStorybookMock } from '@kbn/shared-ux-storybook-mock';
+import { action } from '@storybook/addon-actions';
+import { KibanaErrorService } from '../../src/services/error_service';
+import { KibanaErrorBoundaryServices } from '../../types';
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface Params {}
+
+export class KibanaErrorBoundaryStorybookMock extends AbstractStorybookMock<
+  {},
+  KibanaErrorBoundaryServices
+> {
+  propArguments = {};
+
+  serviceArguments = {};
+
+  dependencies = [];
+
+  getServices(params: Params = {}): KibanaErrorBoundaryServices {
+    const reloadWindowAction = action('Reload window');
+    const reloadWindow = () => {
+      reloadWindowAction();
+    };
+
+    return {
+      ...params,
+      reloadWindow,
+      errorService: new KibanaErrorService(),
+    };
+  }
+
+  getProps(params: Params) {
+    return params;
+  }
+}

packages/shared-ux/error_boundary/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@kbn/shared-ux-error-boundary",
+  "private": true,
+  "version": "1.0.0",
+  "license": "SSPL-1.0 OR Elastic License 2.0"
+}

packages/shared-ux/error_boundary/src/services/error_boundary_services.tsx

@@ -0,0 +1,55 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React, { FC, useContext, useMemo } from 'react';
+
+import { KibanaErrorBoundaryServices } from '../../types';
+import { KibanaErrorService } from './error_service';
+
+const Context = React.createContext<KibanaErrorBoundaryServices | null>(null);
+
+/**
+ * A Context Provider for Jest and Storybooks
+ */
+export const KibanaErrorBoundaryDepsProvider: FC<KibanaErrorBoundaryServices> = ({
+  children,
+  reloadWindow,
+  errorService,
+}) => {
+  return <Context.Provider value={{ reloadWindow, errorService }}>{children}</Context.Provider>;
+};
+
+/**
+ * Kibana-specific Provider that maps dependencies to services.
+ */
+export const KibanaErrorBoundaryProvider: FC = ({ children }) => {
+  // control side-effects of rendering with useMemo
+  const reloadWindow = useMemo(() => () => window.location.reload(), []);
+  const errorService = useMemo(() => new KibanaErrorService(), []);
+
+  const value: KibanaErrorBoundaryServices = {
+    reloadWindow,
+    errorService,
+  };
+
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+};
+
+/**
+ * React hook for accessing pre-wired services.
+ */
+export function useErrorBoundary(): KibanaErrorBoundaryServices {
+  const context = useContext(Context);
+  if (!context) {
+    throw new Error(
+      'Kibana Error Boundary Context is missing. Ensure your component or React root is wrapped with Kibana Error Boundary Context.'
+    );
+  }
+
+  return context;
+}

packages/shared-ux/error_boundary/src/services/error_service.ts

@@ -0,0 +1,79 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React from 'react';
+
+const MATCH_CHUNK_LOADERROR = /ChunkLoadError/;
+
+interface ErrorServiceError {
+  error: Error;
+  errorInfo?: Partial<React.ErrorInfo> | null;
+  name: string | null;
+  isFatal: boolean;
+}
+
+/**
+ * Kibana Error Boundary Services: Error Service
+ * Each Error Boundary tracks an instance of this class
+ * @internal
+ */
+export class KibanaErrorService {
+  /**
+   * Determines if the error fallback UI should appear as an apologetic but promising "Refresh" button,
+   * or treated with "danger" coloring and include a detailed error message.
+   */
+  private getIsFatal(error: Error) {
+    const isChunkLoadError = MATCH_CHUNK_LOADERROR.test(error.name);
+    return !isChunkLoadError; // "ChunkLoadError" is recoverable by refreshing the page
+  }
+
+  /**
+   * Derive the name of the component that threw the error
+   */
+  private getErrorComponentName(errorInfo: Partial<React.ErrorInfo> | null) {
+    let errorComponentName: string | null = null;
+    const stackLines = errorInfo?.componentStack?.split('\n');
+    const errorIndicator = /^    at (\S+).*/;
+
+    if (stackLines) {
+      let i = 0;
+      while (i < stackLines.length - 1) {
+        // scan the stack trace text
+        if (stackLines[i].match(errorIndicator)) {
+          // extract the name of the bad component
+          errorComponentName = stackLines[i].replace(errorIndicator, '$1');
+          if (errorComponentName) {
+            break;
+          }
+        }
+        i++;
+      }
+    }
+
+    return errorComponentName;
+  }
+
+  /**
+   * Creates a decorated error object
+   * TODO: capture telemetry
+   */
+  public registerError(
+    error: Error,
+    errorInfo: Partial<React.ErrorInfo> | null
+  ): ErrorServiceError {
+    const isFatal = this.getIsFatal(error);
+    const name = this.getErrorComponentName(errorInfo);
+
+    return {
+      error,
+      errorInfo,
+      isFatal,
+      name,
+    };
+  }
+}