@atlaskit/analytics-next 11.1.4 → 11.2.1

package/docs/50-error-boundary.tsx

@@ -1,19 +1,9 @@
+/* eslint-disable @atlaskit/design-system/use-primitives-text, @atlaskit/design-system/use-heading -- Legacy analytics-next docs intentionally use plain HTML prose instead of ADS docs primitives. */
 import React from 'react';
 
-import { code, md, Props } from '@atlaskit/docs';
+import { CodeBlock, PropsBlock } from './DocBlocks';
 
-const _default_1: any = md`
-  ${code`import { AnalyticsErrorBoundary } from '@atlaskit/analytics-next';`}
-
-  Wrap part of your tree in \`AnalyticsErrorBoundary\` to provide error boundary track to any events created beneath it.
-
-  When a component is created verifies all of the components above it in the tree and any error will be catched and tracked automatically.
-
-  It's up to the developer pass this information when you're adding the component.
-
-  Usage:
-
-${code`
+const usageCode = `
 import {
   AnalyticsListener,
   AnalyticsErrorBoundary
@@ -43,13 +33,29 @@ class ButtonWithAnalyticsErrorBoundary extends React.Component {
     )
   }
 }
-`}
-
-  ${(
-		<Props
-			heading="AnalyticsErrorBoundary Props"
-			props={require('!!extract-react-types-loader!../src/components/AnalyticsErrorBoundary')}
-		/>
-	)}
 `;
-export default _default_1;
+
+export default function ErrorBoundaryDocs(): React.JSX.Element {
+	return (
+		<div>
+			<CodeBlock code={`import { AnalyticsErrorBoundary } from '@atlaskit/analytics-next';`} />
+			<p>
+				Wrap part of your tree in <code>AnalyticsErrorBoundary</code> to provide error boundary
+				track to any events created beneath it.
+			</p>
+			<p>
+				When a component is created verifies all of the components above it in the tree and any
+				error will be catched and tracked automatically.
+			</p>
+			<p>
+				It&apos;s up to the developer pass this information when you&apos;re adding the component.
+			</p>
+			<h4>Usage</h4>
+			<CodeBlock code={usageCode} />
+			<PropsBlock
+				heading="AnalyticsErrorBoundary Props"
+				props={require('!!extract-react-types-loader!../src/components/AnalyticsErrorBoundary')}
+			/>
+		</div>
+	);
+}

package/docs/60-events.tsx

@@ -1,12 +1,9 @@
-import { code, md } from '@atlaskit/docs';
+/* eslint-disable @atlaskit/design-system/use-primitives-text, @atlaskit/design-system/use-heading -- Legacy analytics-next docs intentionally use plain HTML prose instead of ADS docs primitives. */
+import React from 'react';
 
-const _default_1: any = md`
-  <a name="UIAnalyticsEvent"></a>
-  ### UIAnalyticsEvent
+import { CodeBlock } from './DocBlocks';
 
-  The class can be used to represent an analytics event triggered by a user interaction. It has the following interface:
-
-${code`
+const uiAnalyticsEventCode = `
 /** An array of objects containing data provided by any AnalyticsContext
  * components in the tree above where this event was created. */
 context: Array<{}>;
@@ -40,16 +37,27 @@ update(
       [string]: any,
     }),
 ) => UIAnalyticsEvent;
-`}
-
-  <a name="AnalyticsEvent"></a>
-  ### AnalyticsEvent
-
-  ${code`import { AnalyticsEvent } from '@atlaskit/analytics-next';`}
-
-  A more generic type of event which only contains a payload and an update method.
-  If you want to create an event outside of the UI you can create an instance of this class directly.
-
-  Please see [UIAnalyticsEvent](#UIAnalyticsEvent) for more information.
 `;
-export default _default_1;
+
+export default function EventsDocs(): React.JSX.Element {
+	return (
+		<div>
+			<h3 id="UIAnalyticsEvent">UIAnalyticsEvent</h3>
+			<p>
+				The class can be used to represent an analytics event triggered by a user interaction. It
+				has the following interface:
+			</p>
+			<CodeBlock code={uiAnalyticsEventCode} />
+			<h3 id="AnalyticsEvent">AnalyticsEvent</h3>
+			<CodeBlock code={`import { AnalyticsEvent } from '@atlaskit/analytics-next';`} />
+			<p>
+				A more generic type of event which only contains a payload and an update method. If you want
+				to create an event outside of the UI you can create an instance of this class directly.
+			</p>
+			<p>
+				{/* eslint-disable-next-line @atlaskit/design-system/no-html-anchor -- This legacy docs page keeps plain hash links for local section navigation. */}
+				Please see <a href="#UIAnalyticsEvent">UIAnalyticsEvent</a> for more information.
+			</p>
+		</div>
+	);
+}

package/docs/70-advanced-usage.tsx

@@ -1,38 +1,14 @@
+/* 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 hash links instead of ADS docs primitives. */
 import React from 'react';
 
-import { code, Example, md } from '@atlaskit/docs';
+import { CodeBlock, ExampleBlock } from './DocBlocks';
 
-const _default_1: any = md`
-  ### Contents
-
-  * [Adding more information to an event](#adding-more-information-to-an-event)
-  * [Using a channel](#using-a-channel)
-  * [Passing an event to your consumers](#passing-an-event-to-your-consumers)
-  * [Cloning an event](#cloning-an-event)
-  * [Tracking events outside the UI](#tracking-events-outside-the-ui)
-
-  <a name="adding-more-information-to-an-event"></a>
-  ## Adding more information to an event
-
-  This package provides two methods for adding extra information to analytics events.
-  The first method is by adding data to the analytics events payload. The second method
-  is to provide contextual information to any event.
-
-  <a name="adding-data-to-an-events-payload"></a>
-  ### Adding data to an event's payload
-
-  Before firing an analytics event, you can add data the payload by using the \`update\` method.
-  Here's an example of how that looks:
-
-  ##### SaveButton.js
-
-${code`
+const saveButtonCode = `
 import Button from '@atlaskit/button';
 
 const SaveButton = ({ onClick }) => (
   <Button
     onClick={(e, analytic) => {
-      // update will merge the value into the existing payload
       analytic
         .update({ timestamp: Date.now() })
         .fire();
@@ -44,52 +20,20 @@ const SaveButton = ({ onClick }) => (
     Save
   </Button>
 );
-`}
-
-  In addition to accepting an object, the \`update\` method accepts a function which is called
-  with the event's current payload and is expected to return a new payload.
-
-  Below is a fleshed out example demonstrating how to add extra information to the event's payload.
-
-  ${(
-		<Example
-			packageName="@atlaskit/analytics-next"
-			Component={require('../examples/40-updating-an-event').default}
-			title="Updating an event's payload"
-			source={require('!!raw-loader!../examples/40-updating-an-event')}
-		/>
-	)}
-
-  <a name="using-a-channel"></a>
-  ## Using a channel
-
-  The feature is likey more useful for component authors.
-
-  When calling \`fire\` on an analytics event, you can optionally specify a channel
-  to fire the event on. Only listeners on that channel will recieve the event.
-
-  ##### Button.js (handleClick method)
+`;
 
-${code`
+const usingChannelCode = `
 handleClick = e => {
-  // Create our analytics event
   const analyticsEvent = this.props.createAnalyticsEvent({ action: 'click' });
-
-  // Fire our analytics event on the 'atlaskit' channel
   analyticsEvent.fire('atlaskit');
 
   if (this.props.onClick) {
     this.props.onClick(e);
   }
 };
-`}
-
-  In the above example, we fire events on the \`'atlaskit'\` channel. To listen
-  on this channel we would set up our App like:
-
-  ##### App.js (render method)
+`;
 
-${code`
+const appRenderCode = `
 render() {
   return (
     <AnalyticsListener channel="atlaskit" onEvent={this.handleEvent}>
@@ -97,147 +41,53 @@ render() {
     </AnalyticsListener>
   );
 }
-`}
-
-  The \`AnalyticsListener\` component accepts \`channel\` and \`onEvent\` props. When an event is fired on this Listener's channel its onEvent function will be called.
-
-  <a name="passing-an-event-to-your-consumers"></a>
-  ## Passing an event to your consumers
-
-  The features described in this section are likey to be more useful to component
-  authors.
-
-  If you are building components, you might not want to fire an event as
-  soon as it's created - instead it is better to provide the event to the consumer
-  of your component. The consumer then has a chance to add more information and fire
-  the event when they're ready.
-
-  This is exactly the approach we took to instrument our own Atlaskit components.
-  This section will show you how we did it and how to use the same approach in
-  your components.
-
-  The most straight forward way is to pass the event as an extra argument to the
-  corresponding callback prop. Here's our updated Button component:
-
-  ##### Button.js (handleClick method)
+`;
 
-${code`
+const passingEventCode = `
 handleClick = e => {
-  // Create our analytics event
   const analyticsEvent = this.props.createAnalyticsEvent({ action: 'click' });
 
   if (this.props.onClick) {
-    // Pass the event through the corresponding callback prop
     this.props.onClick(e, analyticsEvent);
   }
 };
-`}
-
-  This is a pretty common pattern for component authors, so \`withAnalyticsEvents\`
-  provides a shortcut:
-
-  ##### Button.js
+`;
 
-${code`
+const shortcutCode = `
 const ButtonWithAnalytics = withAnalyticsEvents({
-  // simply provide a payload we'll automatically create an event for you
   onClick: { action: 'click' }
 })(Button);
-`}
-
-  \`withAnalyticsEvents\` accepts an optional object mapping callback prop names to payloads.
-  This event will be automatically added as a final argument to the callback prop.
-  If the analytics event payload needs to include some information from the components
-  props, \`withAnalyticsEvents\` also accepts a function.
-
-  ##### Button.js
+`;
 
-${code`
+const propsFunctionCode = `
 const ButtonWithAnalytics = withAnalyticsEvents({
-  // this function should return an analytics event
   onClick: (createEvent, props) => {
     return createEvent({ action: 'click', appearance: props.appearance });
   },
 })(Button);
-`}
-
-  ${(
-		<Example
-			packageName="@atlaskit/analytics-next"
-			Component={require('../examples/30-passing-events-to-a-callback').default}
-			title="Passing events through callbacks"
-			source={require('!!raw-loader!../examples/30-passing-events-to-a-callback')}
-		/>
-	)}
-
-  <a name="cloning-an-event"></a>
-  ## Cloning an event
-
-  The features described in this section are likey to be more useful to component
-  authors.
-
-  Once an event has been fired it cannot be updated or fired again. This poses a
-  problem for library component authors who want to record their own analytics
-  events, while also exposing analytics events to their consumers.
-
-  That's where \`.clone\` comes in.
-
-  Let's imagine a Form component. If it accepted an \`onSubmit\` callback prop we could do something like this:
-
-  ##### Form.js (onSubmit method):
+`;
 
-${code`
+const cloningCode = `
 onSubmit = analyticsEvent => {
   const { value } = this.state;
-
-  // Clone the analytics event
   const publicEvent = analyticsEvent.clone();
-
-  // Add whatever data we want to know about to our event and fire it
   analyticsEvent.update({ value }).fire('atlaskit');
 
   if (this.props.onSubmit) {
-    // Pass the cloned event to the callback prop for consumers to use
     this.props.onSubmit(value, publicEvent);
   }
 };
-`}
-
-  This is a common enough usecase that we have built a helper to make this
-  easier to do.
-
-  ##### Form.js (onSubmit method):
+`;
 
-${code`
+const cloningShortcutCode = `
 import { withAnalyticsEvents, createAndFireEvent } from '@atlaskit/analytics-next';
 
 const FormWithAnalytics = withAnalyticsEvents({
   onSubmit: createAndFireEvent('atlaskit')({ action: 'submit' })
 })(Form);
-`}
-
-  This will create the event with the payload, fire it on the specified channel
-  and return a clone of the event.
-
-  ${(
-		<Example
-			packageName="@atlaskit/analytics-next"
-			Component={require('../examples/50-cloning-an-event').default}
-			title="Cloning an event"
-			source={require('!!raw-loader!../examples/50-cloning-an-event')}
-		/>
-	)}
-
-  <a name="tracking-events-outside-the-ui"></a>
-  ## Tracking events outside the UI
-
-  This library provides tools for tracking interactions with UI components, and makes it really easy to capture the UI context and state when these events occur. But what if the event you're tracking doesn't care about the UI? Can you still use this library to track it?
-
-  Well, sure - but you might not need to. An event has to be created by a UI component to get \`context\` and a \`.fire\` method. Without these properties an analytics event is basically a payload! It might be simpler to just create an object and pass it directly to the function that handles your events.
-
-  In case it is useful for you to have a consistent interface for your events, even if they're not coming from the UI, we do export the base \`AnalyticsEvent\` class. Here's an example of how you might use it:
+`;
 
-${code`
+const outsideUiCode = `
 import { AnalyticsEvent } from '@atlaskit/analytics-next';
 import sendAnalyticsEventToBackend from './sendAnalyticsEventToBackend';
 
@@ -250,22 +100,175 @@ const fetchBacon = async () => {
 
   const responseTime = performance.now() - startTime;
 
-  /** This event records server response time. This function doesn't live inside
-   * a component and we don't care what state the UI is in when it runs. It
-   * would be annoying if we had to create the event inside a component, then
-   * pass it to this function. We can create a generic AnalyticsEvent and handle
-   * it all inside this function instead. */
   const analyticsEvent = new AnalyticsEvent({
     payload: { action: 'server-request', data, responseTime },
   });
 
-  /** Because we're not in the UI this event doesn't have any
-   * AnalyticsListeners, which means it doesn't have a .fire method. We need to
-   * explicitly pass it to the function that will handle it. */
   sendAnalyticsEventToBackend(analyticsEvent);
 
   return data;
 };
-`}
 `;
-export default _default_1;
+
+export default function AdvancedUsage(): React.JSX.Element {
+	return (
+		<div>
+			<h3>Contents</h3>
+			<ul>
+				<li>
+					<a href="#adding-more-information-to-an-event">Adding more information to an event</a>
+				</li>
+				<li>
+					<a href="#using-a-channel">Using a channel</a>
+				</li>
+				<li>
+					<a href="#passing-an-event-to-your-consumers">Passing an event to your consumers</a>
+				</li>
+				<li>
+					<a href="#cloning-an-event">Cloning an event</a>
+				</li>
+				<li>
+					<a href="#tracking-events-outside-the-ui">Tracking events outside the UI</a>
+				</li>
+			</ul>
+
+			<h2 id="adding-more-information-to-an-event">Adding more information to an event</h2>
+			<p>
+				This package provides two methods for adding extra information to analytics events. The
+				first method is by adding data to the analytics events payload. The second method is to
+				provide contextual information to any event.
+			</p>
+			<h3>Adding data to an event&apos;s payload</h3>
+			<p>
+				Before firing an analytics event, you can add data the payload by using the{' '}
+				<code>update</code> method. Here&apos;s an example of how that looks:
+			</p>
+			<h5>SaveButton.js</h5>
+			<CodeBlock code={saveButtonCode} />
+			<p>
+				In addition to accepting an object, the <code>update</code> method accepts a function which
+				is called with the event&apos;s current payload and is expected to return a new payload.
+			</p>
+			<p>
+				Below is a fleshed out example demonstrating how to add extra information to the
+				event&apos;s payload.
+			</p>
+			<ExampleBlock
+				Component={require('../examples/40-updating-an-event').default}
+				title="Updating an event's payload"
+				source={require('!!raw-loader!../examples/40-updating-an-event')}
+			/>
+
+			<h2 id="using-a-channel">Using a channel</h2>
+			<p>The feature is likey more useful for component authors.</p>
+			<p>
+				When calling <code>fire</code> on an analytics event, you can optionally specify a channel
+				to fire the event on. Only listeners on that channel will recieve the event.
+			</p>
+			<h5>Button.js (handleClick method)</h5>
+			<CodeBlock code={usingChannelCode} />
+			<p>
+				In the above example, we fire events on the <code>&apos;atlaskit&apos;</code> channel. To
+				listen on this channel we would set up our App like:
+			</p>
+			<h5>App.js (render method)</h5>
+			<CodeBlock code={appRenderCode} />
+			<p>
+				The <code>AnalyticsListener</code> component accepts <code>channel</code> and{' '}
+				<code>onEvent</code> props. When an event is fired on this Listener&apos;s channel its
+				onEvent function will be called.
+			</p>
+
+			<h2 id="passing-an-event-to-your-consumers">Passing an event to your consumers</h2>
+			<p>
+				The features described in this section are likey to be more useful to component authors.
+			</p>
+			<p>
+				If you are building components, you might not want to fire an event as soon as it&apos;s
+				created - instead it is better to provide the event to the consumer of your component. The
+				consumer then has a chance to add more information and fire the event when they&apos;re
+				ready.
+			</p>
+			<p>
+				This is exactly the approach we took to instrument our own Atlaskit components. This section
+				will show you how we did it and how to use the same approach in your components.
+			</p>
+			<p>
+				The most straight forward way is to pass the event as an extra argument to the corresponding
+				callback prop. Here&apos;s our updated Button component:
+			</p>
+			<h5>Button.js (handleClick method)</h5>
+			<CodeBlock code={passingEventCode} />
+			<p>
+				This is a pretty common pattern for component authors, so <code>withAnalyticsEvents</code>{' '}
+				provides a shortcut:
+			</p>
+			<h5>Button.js</h5>
+			<CodeBlock code={shortcutCode} />
+			<p>
+				<code>withAnalyticsEvents</code> accepts an optional object mapping callback prop names to
+				payloads. This event will be automatically added as a final argument to the callback prop.
+				If the analytics event payload needs to include some information from the components props,{' '}
+				<code>withAnalyticsEvents</code> also accepts a function.
+			</p>
+			<h5>Button.js</h5>
+			<CodeBlock code={propsFunctionCode} />
+			<ExampleBlock
+				Component={require('../examples/30-passing-events-to-a-callback').default}
+				title="Passing events through callbacks"
+				source={require('!!raw-loader!../examples/30-passing-events-to-a-callback')}
+			/>
+
+			<h2 id="cloning-an-event">Cloning an event</h2>
+			<p>
+				The features described in this section are likey to be more useful to component authors.
+			</p>
+			<p>
+				Once an event has been fired it cannot be updated or fired again. This poses a problem for
+				library component authors who want to record their own analytics events, while also exposing
+				analytics events to their consumers.
+			</p>
+			<p>
+				That&apos;s where <code>.clone</code> comes in.
+			</p>
+			<p>
+				Let&apos;s imagine a Form component. If it accepted an <code>onSubmit</code> callback prop
+				we could do something like this:
+			</p>
+			<h5>Form.js (onSubmit method):</h5>
+			<CodeBlock code={cloningCode} />
+			<p>This is a common enough usecase that we have built a helper to make this easier to do.</p>
+			<h5>Form.js (onSubmit method):</h5>
+			<CodeBlock code={cloningShortcutCode} />
+			<p>
+				This will create the event with the payload, fire it on the specified channel and return a
+				clone of the event.
+			</p>
+			<ExampleBlock
+				Component={require('../examples/50-cloning-an-event').default}
+				title="Cloning an event"
+				source={require('!!raw-loader!../examples/50-cloning-an-event')}
+			/>
+
+			<h2 id="tracking-events-outside-the-ui">Tracking events outside the UI</h2>
+			<p>
+				This library provides tools for tracking interactions with UI components, and makes it
+				really easy to capture the UI context and state when these events occur. But what if the
+				event you&apos;re tracking doesn&apos;t care about the UI? Can you still use this library to
+				track it?
+			</p>
+			<p>
+				Well, sure - but you might not need to. An event has to be created by a UI component to get{' '}
+				<code>context</code> and a <code>.fire</code> method. Without these properties an analytics
+				event is basically a payload! It might be simpler to just create an object and pass it
+				directly to the function that handles your events.
+			</p>
+			<p>
+				In case it is useful for you to have a consistent interface for your events, even if
+				they&apos;re not coming from the UI, we do export the base <code>AnalyticsEvent</code>{' '}
+				class. Here&apos;s an example of how you might use it:
+			</p>
+			<CodeBlock code={outsideUiCode} />
+		</div>
+	);
+}