@atlaskit/analytics-next 11.2.0 → 11.2.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @atlaskit/analytics-next
 
+## 11.2.1
+
+### Patch Changes
+
+- [`35a1309b51bea`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/35a1309b51bea) -
+  Isolate handler errors in `UIAnalyticsEvent.fire()` so a throwing analytics handler never
+  propagates out and crashes the calling product UI.
+
+  Each handler is now wrapped in a `try/catch`. In non-production environments the error is surfaced
+  via `console.error`; in production it is swallowed silently. This prevents analytics from being in
+  the critical path of product UI rendering.
+
+  PIR: PIR-300717 / HOT-301294 (CFIND-6243)
+
 ## 11.2.0
 
 ### Minor Changes

package/afm-cc/tsconfig.json

@@ -1,7 +1,6 @@
 {
 	"extends": "../../../../tsconfig.local-consumption.json",
 	"compilerOptions": {
-		"target": "es5",
 		"outDir": "../../../../../confluence/tsDist/@atlaskit__analytics-next",
 		"rootDir": "../",
 		"composite": true,

package/afm-products/tsconfig.json

@@ -1,7 +1,6 @@
 {
 	"extends": "../../../../tsconfig.local-consumption.json",
 	"compilerOptions": {
-		"target": "es5",
 		"outDir": "../../../../../tsDist/@atlaskit__analytics-next/app",
 		"rootDir": "../",
 		"composite": true,

package/dist/cjs/events/UIAnalyticsEvent.js

@@ -61,7 +61,17 @@ var UIAnalyticsEvent = exports.default = /*#__PURE__*/function (_AnalyticsEvent)
         return;
       }
       _this.handlers.forEach(function (handler) {
-        return handler(_this, channel);
+        try {
+          handler(_this, channel);
+        } catch (e) {
+          // Analytics must never crash product UI. Swallow handler errors in
+          // production; surface them in development so misconfigured events are
+          // caught early.
+          if (process.env.NODE_ENV !== 'production') {
+            // eslint-disable-next-line no-console
+            console.error('[analytics-next] UIAnalyticsEvent handler threw an error:', e);
+          }
+        }
       });
       _this.hasFired = true;
     });

package/dist/es2019/events/UIAnalyticsEvent.js

@@ -42,7 +42,19 @@ export default class UIAnalyticsEvent extends AnalyticsEvent {
         }
         return;
       }
-      this.handlers.forEach(handler => handler(this, channel));
+      this.handlers.forEach(handler => {
+        try {
+          handler(this, channel);
+        } catch (e) {
+          // Analytics must never crash product UI. Swallow handler errors in
+          // production; surface them in development so misconfigured events are
+          // caught early.
+          if (process.env.NODE_ENV !== 'production') {
+            // eslint-disable-next-line no-console
+            console.error('[analytics-next] UIAnalyticsEvent handler threw an error:', e);
+          }
+        }
+      });
       this.hasFired = true;
     });
     this.context = props.context || [];

package/dist/esm/events/UIAnalyticsEvent.js

@@ -55,7 +55,17 @@ var UIAnalyticsEvent = /*#__PURE__*/function (_AnalyticsEvent) {
         return;
       }
       _this.handlers.forEach(function (handler) {
-        return handler(_this, channel);
+        try {
+          handler(_this, channel);
+        } catch (e) {
+          // Analytics must never crash product UI. Swallow handler errors in
+          // production; surface them in development so misconfigured events are
+          // caught early.
+          if (process.env.NODE_ENV !== 'production') {
+            // eslint-disable-next-line no-console
+            console.error('[analytics-next] UIAnalyticsEvent handler threw an error:', e);
+          }
+        }
       });
       _this.hasFired = true;
     });

package/docs/0-intro.tsx

@@ -1,42 +1,73 @@
+/* eslint-disable @atlaskit/design-system/ensure-design-token-usage, @atlaskit/ui-styling-standard/enforce-style-prop, @atlaskit/design-system/use-primitives-text, @atlaskit/design-system/use-heading, @atlaskit/design-system/no-html-anchor -- Legacy analytics-next docs intentionally use plain HTML prose, links, and inline styles after the docs helper cleanup. */
 import React from 'react';
 
-import { md } from '@atlaskit/docs';
-import Link from '@atlaskit/link';
-import SectionMessage from '@atlaskit/section-message';
+const warningStyles: React.CSSProperties = {
+	backgroundColor: '#fffae6',
+	border: '1px solid #f5cd47',
+	borderRadius: 3,
+	marginBottom: 16,
+	padding: 16,
+};
 
-const _default_1: any = md`
+export default function Intro(): React.JSX.Element {
+	return (
+		<div>
+			<div style={warningStyles}>
+				<strong>Maintaince Mode: @atlaskit/analytics is in maintenance mode.</strong>
+				<p>
+					This package is officially in maintenance mode, which means only bugfixes or VULN fixes
+					are currently being accepted and no known breaking changes will be approved in the PR
+					process.
+				</p>
+				<p>
+					Please refer to this{' '}
+					<a
+						href="https://hello.atlassian.net/wiki/spaces/APD/pages/2470435075/DACI+analytics-next+in+a+maintenance+mode"
+						target="_blank"
+						rel="noreferrer"
+					>
+						DACI
+					</a>{' '}
+					for more details.
+				</p>
+			</div>
 
-${(
-	<SectionMessage
-		appearance="warning"
-		title="Maintaince Mode: @atlaskit/analytics is in maintenance mode."
-	>
-		This package is officially in maintenance mode, which means only bugfixes or VULN fixes are
-		currently being accepted and no known breaking changes will be approved in the PR process.{' '}
-		<br />
-		Please refer to this
-		<Link
-			href="https://hello.atlassian.net/wiki/spaces/APD/pages/2470435075/DACI+analytics-next+in+a+maintenance+mode"
-			target="_blank"
-		>
-			{' '}
-			DACI{' '}
-		</Link>{' '}
-		for more details.
-	</SectionMessage>
-)}
+			<p>
+				This package aims to help assist consumers track the way their React components are being
+				used.
+			</p>
 
-This package aims to help assist consumers track the way their React components are being used.
-
-### Contents
-
-- [Concepts](./analytics-next/docs/concepts) (Read first!)
-- [Usage with presentational components](./analytics-next/docs/usage-with-presentational-components)
-- [Usage with container components](./analytics-next/docs/usage-for-container-components)
-- [Listeners](./analytics-next/docs/listeners)
-- [Error Boundary](./analytics-next/docs/error-boundary)
-- [Events](./analytics-next/docs/events)
-- [Advanced usage](./analytics-next/docs/advanced-usage)
-- [Ugprade guide](./analytics-next/docs/upgrade-guide)
-`;
-export default _default_1;
+			<h3>Contents</h3>
+			<ul>
+				<li>
+					<a href="./analytics-next/docs/concepts">Concepts</a> (Read first!)
+				</li>
+				<li>
+					<a href="./analytics-next/docs/usage-with-presentational-components">
+						Usage with presentational components
+					</a>
+				</li>
+				<li>
+					<a href="./analytics-next/docs/usage-for-container-components">
+						Usage with container components
+					</a>
+				</li>
+				<li>
+					<a href="./analytics-next/docs/listeners">Listeners</a>
+				</li>
+				<li>
+					<a href="./analytics-next/docs/error-boundary">Error Boundary</a>
+				</li>
+				<li>
+					<a href="./analytics-next/docs/events">Events</a>
+				</li>
+				<li>
+					<a href="./analytics-next/docs/advanced-usage">Advanced usage</a>
+				</li>
+				<li>
+					<a href="./analytics-next/docs/upgrade-guide">Ugprade guide</a>
+				</li>
+			</ul>
+		</div>
+	);
+}

package/docs/10-concepts.tsx

@@ -1,122 +1,148 @@
-import { code, md } from '@atlaskit/docs';
+/* eslint-disable @atlaskit/design-system/use-primitives-text, @atlaskit/design-system/use-heading, @atlaskit/design-system/no-html-anchor -- Legacy analytics-next docs intentionally use plain HTML prose and links instead of ADS docs primitives. */
+import React from 'react';
 
-const _default_1: any = md`
-There are 3 abstract layers as part of \`@atlaskit/analytics-next\`:
+import { CodeBlock } from './DocBlocks';
 
-- [Analytics Listeners](./listeners) (responsible for sending events over the network)
-- [Consumer Components](./usage-with-presentational-components) (target components that are desired to be tracked. They fire events that the listener consumes)
-- [Analytics Contexts](./usage-for-container-components) (provides contextual data to consumer components about the \"container\" they are embeded in. This data is added to the event fired by all consumer components that are its children.)
+const exampleCode = `
+// ---- CONSUMER COMPONENT LAYER ----
 
-### React Context: !important;
-
-These layers communicate via React context. Historically this package has used [legacy React Context][legacy-context], but
-is now transitioning to use only the new [React Context API][modern-context]. This is to prepare for
-future versions of React in which legacy Context will be dropped, but also partially for performance reasons.
-
-To achieve dropping legacy context we are rolling the drop out in 2 phases:
-
-#### Phase I (version 7.1.0)
-
-Analytics consuming components receive only modern context. Listeners and the Context layer will provide both modern and legacy context by default.
-
-At their own risk, package consumers can opt in to no longer supply legacy context by using the environment variable
-ANALYTICS_NEXT_MODERN_CONTEXT=true.
-
-When doing so, any analytics consumers that rely on legacy context will not receive any, and events may be lost! This would happen when using old atlaskit packages that consume a version of @atlaskit/analytics-next before version 7.1.0.
-
-#### Phase II (future major)
-
-In a future release (TBA) we will remove all legacy context support and clean up the branching around ANALYTICS_NEXT_MODERN_CONTEXT.
-After this point, @atlaskit/analytics-next will not work with components that use a version prior to 7.1.0.
-
-### Example
-
-${code`
-  // ---- CONSUMER COMPONENT LAYER ----
+// We want to add tracking for the 'click' of this button
+const TargetButton = ({ onClick }) => {
+  // this analytics event is given to the callback via the
+  // HOC wrapping of this component below
+  const handler = (clickEvent, analyticsEvent) => {
+    analyticsEvent.fire("myTargetChannel");
+  };
 
-  // We want to add tracking for the 'click' of this button
-  const TargetButton = ({ onClick }) => {
-    // this analytics event is given to the callback via the
-    // HOC wrapping of this component below
-    const handler = (clickEvent, analyticsEvent) => {
-      analyticsEvent.fire("myTargetChannel");
-    };
+  return <button onClick={handler}>Track me</button>
+}
 
-    return <button onClick={handler}>Track me</button>
+// Analytics can be baked into your target components
+// in a number of ways, this is just one of many!
+const AnalyticsWrappedButton = withAnalyticsEvent({
+  onClick: {
+    component: 'button',
+    action: 'clicked'
   }
-
-  // Analytics can be baked into your target components
-  // in a number of ways, this is just one of many!
-  const AnalyticsWrappedButton = withAnalyticsEvent({
-    onClick: {
-      component: 'button',
+})(TargetButton);
+
+// ---- ANALYTICS CONTEXT LAYER ----
+
+// Our target button is going to be used inside of a form
+const FormContainer = ({ children }) => {
+  return (
+    <form>
+      {children}
+    </form>
+  );
+}
+
+// This wrapper gives the container a way of passing to its children
+// components some context about where it is consumed.
+// Again there are a few ways of doing this!
+const AnalyticsWrappedForm = withAnayticsContext({
+  container: 'submissionForm',
+  page: '/invite-a-friend'
+})(FormContainer);
+
+// ---- ANALYTICS LISTENER LAYER ----
+
+// This is our App's listener
+// Note: It is possible to have multiple listeners, all listening
+// on different channels, allowing for different handlers for different
+// kind of events
+const OurAnalyticsListener = ({ children }) => {
+  const onEvent = (event, channel) => {
+    // these components are agnostic to what you want to use
+    // to send events to the network
+    someClient.sendToNetwork(event);
+
+    expect(event.payload).toBe({
       action: 'clicked'
-    }
-  })(TargetButton);
-
-  // ---- ANALYTICS CONTEXT LAYER ----
-
-  // Our target button is going to be used inside of a form
-  const FormContainer = ({ children }) => {
-    return (
-      <form>
-        {children}
-      </form>
-    );
-  }
-
-  // This wrapper gives the container a way of passing to its children
-  // components some context about where it is consumed.
-  // Again there are a few ways of doing this!
-  const AnalyticsWrappedForm = withAnayticsContext({
-    container: 'submissionForm',
-    page: '/invite-a-friend'
-  })(FormContainer);
-
-  // ---- ANALYTICS LISTENER LAYER ----
-
-  // This is our App's listener
-  // Note: It is possible to have multiple listeners, all listening
-  // on different channels, allowing for different handlers for different
-  // kind of events
-  const OurAnalyticsListener = ({ children }) => {
-    const onEvent = (event, channel) => {
-      // these components are agnostic to what you want to use
-      // to send events to the network
-      someClient.sendToNetwork(event);
-
-      expect(event.payload).toBe({
-        action: 'clicked'
-        component: 'button'
-      });
-
-      // an array of contexts (multiple context containers can be nested)
-      expect(event.context).toBe([{
-        container: 'submissionForm',
-        page: '/invite-a-friend'
-      });
-    };
-
-    return (
-      <AnalyticsListener channel="myTargetChannel" onEvent={onEvent}>
-        {children}
-      </AnalyticsListener>
-    )
-  }
-
-  // ---- ALL TOGETHER ----
-
-  export const ExampleApp = () => {
-    return (
-      <OurAnalyticsListener>           // Listener layer in this example
-        <AnalyticsWrappedForm>         // Context layer in this example
-          <AnalyticsWrappedButton/>    // Consumer component layer in this example
-        </AnalyticsWrappedForm>
-      </OurAnalyticsListener>);
+      component: 'button'
+    });
+
+    // an array of contexts (multiple context containers can be nested)
+    expect(event.context).toBe([{
+      container: 'submissionForm',
+      page: '/invite-a-friend'
+    });
   };
-`}
 
-[legacy-context]: https://reactjs.org/docs/legacy-context.html
-[modern-context]: https://reactjs.org/docs/context.html
+  return (
+    <AnalyticsListener channel="myTargetChannel" onEvent={onEvent}>
+      {children}
+    </AnalyticsListener>
+  )
+}
+
+// ---- ALL TOGETHER ----
+
+export const ExampleApp = () => {
+  return (
+    <OurAnalyticsListener>
+      <AnalyticsWrappedForm>
+        <AnalyticsWrappedButton/>
+      </AnalyticsWrappedForm>
+    </OurAnalyticsListener>);
+};
 `;
-export default _default_1;
+
+export default function Concepts(): React.JSX.Element {
+	return (
+		<div>
+			<p>
+				There are 3 abstract layers as part of <code>@atlaskit/analytics-next</code>:
+			</p>
+			<ul>
+				<li>
+					<a href="./listeners">Analytics Listeners</a> (responsible for sending events over the
+					network)
+				</li>
+				<li>
+					<a href="./usage-with-presentational-components">Consumer Components</a> (target
+					components that are desired to be tracked. They fire events that the listener consumes)
+				</li>
+				<li>
+					<a href="./usage-for-container-components">Analytics Contexts</a> (provides contextual
+					data to consumer components about where it is embeded in the &quot;container&quot; they
+					are embeded in. This data is added to the event fired by all consumer components that are
+					its children.)
+				</li>
+			</ul>
+
+			<h3>React Context: !important;</h3>
+			<p>
+				These layers communicate via React context. Historically this package has used{' '}
+				<a href="https://reactjs.org/docs/legacy-context.html">legacy React Context</a>, but is now
+				transitioning to use only the new{' '}
+				<a href="https://reactjs.org/docs/context.html">React Context API</a>. This is to prepare
+				for future versions of React in which legacy Context will be dropped, but also partially for
+				performance reasons.
+			</p>
+			<p>To achieve dropping legacy context we are rolling the drop out in 2 phases:</p>
+			<h4>Phase I (version 7.1.0)</h4>
+			<p>
+				Analytics consuming components receive only modern context. Listeners and the Context layer
+				will provide both modern and legacy context by default.
+			</p>
+			<p>
+				At their own risk, package consumers can opt in to no longer supply legacy context by using
+				the environment variable ANALYTICS_NEXT_MODERN_CONTEXT=true.
+			</p>
+			<p>
+				When doing so, any analytics consumers that rely on legacy context will not receive any, and
+				events may be lost! This would happen when using old atlaskit packages that consume a
+				version of @atlaskit/analytics-next before version 7.1.0.
+			</p>
+			<h4>Phase II (future major)</h4>
+			<p>
+				In a future release (TBA) we will remove all legacy context support and clean up the
+				branching around ANALYTICS_NEXT_MODERN_CONTEXT. After this point, @atlaskit/analytics-next
+				will not work with components that use a version prior to 7.1.0.
+			</p>
+			<h3>Example</h3>
+			<CodeBlock code={exampleCode} />
+		</div>
+	);
+}