@atlaskit/analytics-next 11.2.0 → 11.2.1

package/docs/80-upgrade-guide.tsx

@@ -1,113 +1,27 @@
-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`
-## v5 to v6
+import { CodeBlock } from './DocBlocks';
 
-### ✨ TypeScript support
-
-Analytics-next is now completely written in TypeScript
-
-### 🧠 HOC Type inference
-
-In v5, the main problem areas for \`analytics-next\`, with regards to TypeScript, was \`withAnalyticsEvents\` and \`withAnalyticsContext\`.
-These two HOCs never quite worked as expected, often relying on consumers to cast the return value of the
-function back into the component they wish to export. Recently this was partially mitigated by accepting prop types as generics, returning TS type safety
- with one downside, props must be passed into every usage of our HOCs.
-
-Now in v6, support for [type inference](https://www.typescriptlang.org/docs/handbook/type-inference.html) is built-in so you
-no longer have to explicitly pass props as generic types.
-
-### 📝 Renaming types and interfaces
-
-\`analytics-next\` previously provided typings via a module declaration file (index.d.ts), which was actually slightly misaligned
-with the source code. Some interfaces were used to describe classes, and some classes of the same name were also being exported to avoid name clashes.
-v6 removes those discrepancies by renaming and removing misaligned type definitions. See breaking changes for more information.
-
-### 💥 Breaking Changes:
-
-- flow types have been removed
-- \`withAnalyticsEvents\` now infers proptypes automatically, consumers no longer need to provide props as a generic type.
-- \`withAnalyticsContext\` now infers proptypes automatically, consumers no longer need to provide props as a generic type.
-- Type \`WithAnalyticsEventProps\` has been renamed to \`WithAnalyticsEventsProps\` to match source code
-- Type \`CreateUIAnalyticsEventSignature\` has been renamed to \`CreateUIAnalyticsEvent\` to match source code
-- Type \`UIAnalyticsEventHandlerSignature\` has been renamed to \`UIAnalyticsEventHandler\` to match source code
-- Type \`AnalyticsEventsPayload\` has been renamed to \`AnalyticsEventPayload\`
-- Type \`ObjectType\` has been removed, please use \`Record<string, any>\` or \`[key: string]: any\`
-- Type \`UIAnalyticsEventInterface\` has been removed, please use \`UIAnalyticsEvent\`
-- Type \`AnalyticsEventInterface\` has been removed, please use \`AnalyticsEvent\`
-- Type \`CreateAndFireEventFunction\` removed and should now be inferred by TypeScript
-- Type \`AnalyticsEventUpdater\` removed and should now be inferred by TypeScript
-
-<br/>
-
----
-
-### ⬆️ Upgrade guide
-_Applicable to TypeScript users only_
-
-#### Renaming types and interfaces
-
-Most of the breaking changes above can be avoided with a 'find-and-replace' of the following types/interfaces:
-
-- \`WithAnalyticsEventProps\` => \`WithAnalyticsEventsProps\`
-- \`CreateUIAnalyticsEventSignature\` => \`CreateUIAnalyticsEvent\`
-- \`UIAnalyticsEventHandlerSignature\` => \`UIAnalyticsEventHandler\`
-- \`AnalyticsEventsPayload\` => \`AnalyticsEventPayload\`
-
-Some interfaces were used to describe a class instance. This is no longer needed since a class in TypeScript can be used as a type.
-These interfaces should be replaced by their class equivalents:
-
-- \`UIAnalyticsEventInterface\` => \`UIAnalyticsEvent\`
-- \`AnalyticsEventInterface\` => \`AnalyticsEvent\`
-
-The following types have been removed from the library and can either be safely replaced with an alternate type or
-removed entirely in favour of type inference:
-
-- \`ObjectType\` => \`Record<string, any>\` or \`[key: string]: any\`
-- \`CreateAndFireEventFunction\` now inferred by TypeScript
-- \`AnalyticsEventUpdater\` now inferred by TypeScript
-
-#### Using \`withAnalyticsEvents\` and \`withAnalyticsContext\` with type-safety
-
-After upgrading to v6, you might now be greeted with TypeScript errors relating
-to \`withAnalyticsEvents\` and \`withAnalyticsContext\`. As described above, there
-have been a lot of changes to the way types are applied to these HOCs.
-
-Previously, props needed to be explicitly defined and passed in as [generic type arguments](https://www.typescriptlang.org/docs/handbook/generics.html).
-Now, you should be able to remove the generic types and let TypeScript do the heavy lifting.
-
-For example:
-
-**Before…**
-
-${code`
+const beforeCode = `
 withAnalyticsContext<ButtonProps>({})(Button);
 withAnalyticsEvents<ButtonProps>({})(Button);
-`}
-
-**After…**
+`;
 
-${code`
+const afterCode = `
 withAnalyticsContext({})(Button);
 withAnalyticsEvents({})(Button);
-`}
-
-This does however require you to extend your component's props with \`WithAnalyticsEventProps\`.
-A common pattern you’ll find with other HOC implementations, used to ensure you’re passing the correct super type to the HOC.
+`;
 
-${code`
+const propsCode = `
 import { WithAnalyticsEventsProps } from '@atlaskit/analytics-next';
 
 interface ButtonProps extends WithAnalyticsEventsProps {
   appearance: string,
 }
-`}
-
-To provide additional flexibility, you can now opt-out of type inference if needed. It might be necessary in edge-cases
-where TypeScript is not able to infer the prop types of the component you have supplied.
-If that's the case, try passing in the generic type arguments to \`withAnalyticsEvents\`.
+`;
 
-${code`
+const optOutCode = `
 export default withAnalyticsContext({})(
   withAnalyticsEvents({})
   <
@@ -115,8 +29,176 @@ export default withAnalyticsContext({})(
     React.ComponentType<ButtonProps>
   >(Button),
 );
-`}
-
-
 `;
-export default _default_1;
+
+export default function UpgradeGuide(): React.JSX.Element {
+	return (
+		<div>
+			<h2>v5 to v6</h2>
+			<h3>✨ TypeScript support</h3>
+			<p>Analytics-next is now completely written in TypeScript</p>
+			<h3>🧠 HOC Type inference</h3>
+			<p>
+				In v5, the main problem areas for <code>analytics-next</code>, with regards to TypeScript,
+				was <code>withAnalyticsEvents</code> and <code>withAnalyticsContext</code>. These two HOCs
+				never quite worked as expected, often relying on consumers to cast the return value of the
+				function back into the component they wish to export. Recently this was partially mitigated
+				by accepting prop types as generics, returning TS type safety with one downside, props must
+				be passed into every usage of our HOCs.
+			</p>
+			<p>
+				Now in v6, support for{' '}
+				<a href="https://www.typescriptlang.org/docs/handbook/type-inference.html">
+					type inference
+				</a>{' '}
+				is built-in so you no longer have to explicitly pass props as generic types.
+			</p>
+			<h3>📝 Renaming types and interfaces</h3>
+			<p>
+				<code>analytics-next</code> previously provided typings via a module declaration file
+				(index.d.ts), which was actually slightly misaligned with the source code. Some interfaces
+				were used to describe classes, and some classes of the same name were also being exported to
+				avoid name clashes. v6 removes those discrepancies by renaming and removing misaligned type
+				definitions. See breaking changes for more information.
+			</p>
+			<h3>💥 Breaking Changes:</h3>
+			<ul>
+				<li>flow types have been removed</li>
+				<li>
+					<code>withAnalyticsEvents</code> now infers proptypes automatically, consumers no longer
+					need to provide props as a generic type.
+				</li>
+				<li>
+					<code>withAnalyticsContext</code> now infers proptypes automatically, consumers no longer
+					need to provide props as a generic type.
+				</li>
+				<li>
+					Type <code>WithAnalyticsEventProps</code> has been renamed to{' '}
+					<code>WithAnalyticsEventsProps</code> to match source code
+				</li>
+				<li>
+					Type <code>CreateUIAnalyticsEventSignature</code> has been renamed to{' '}
+					<code>CreateUIAnalyticsEvent</code> to match source code
+				</li>
+				<li>
+					Type <code>UIAnalyticsEventHandlerSignature</code> has been renamed to{' '}
+					<code>UIAnalyticsEventHandler</code> to match source code
+				</li>
+				<li>
+					Type <code>AnalyticsEventsPayload</code> has been renamed to{' '}
+					<code>AnalyticsEventPayload</code>
+				</li>
+				<li>
+					Type <code>ObjectType</code> has been removed, please use{' '}
+					<code>Record&lt;string, any&gt;</code> or <code>[key: string]: any</code>
+				</li>
+				<li>
+					Type <code>UIAnalyticsEventInterface</code> has been removed, please use{' '}
+					<code>UIAnalyticsEvent</code>
+				</li>
+				<li>
+					Type <code>AnalyticsEventInterface</code> has been removed, please use{' '}
+					<code>AnalyticsEvent</code>
+				</li>
+				<li>
+					Type <code>CreateAndFireEventFunction</code> removed and should now be inferred by
+					TypeScript
+				</li>
+				<li>
+					Type <code>AnalyticsEventUpdater</code> removed and should now be inferred by TypeScript
+				</li>
+			</ul>
+			<hr role="presentation" />
+			<h3>⬆️ Upgrade guide</h3>
+			<p>
+				<em>Applicable to TypeScript users only</em>
+			</p>
+			<h4>Renaming types and interfaces</h4>
+			<p>
+				Most of the breaking changes above can be avoided with a &apos;find-and-replace&apos; of the
+				following types/interfaces:
+			</p>
+			<ul>
+				<li>
+					<code>WithAnalyticsEventProps</code> =&gt; <code>WithAnalyticsEventsProps</code>
+				</li>
+				<li>
+					<code>CreateUIAnalyticsEventSignature</code> =&gt; <code>CreateUIAnalyticsEvent</code>
+				</li>
+				<li>
+					<code>UIAnalyticsEventHandlerSignature</code> =&gt; <code>UIAnalyticsEventHandler</code>
+				</li>
+				<li>
+					<code>AnalyticsEventsPayload</code> =&gt; <code>AnalyticsEventPayload</code>
+				</li>
+			</ul>
+			<p>
+				Some interfaces were used to describe a class instance. This is no longer needed since a
+				class in TypeScript can be used as a type. These interfaces should be replaced by their
+				class equivalents:
+			</p>
+			<ul>
+				<li>
+					<code>UIAnalyticsEventInterface</code> =&gt; <code>UIAnalyticsEvent</code>
+				</li>
+				<li>
+					<code>AnalyticsEventInterface</code> =&gt; <code>AnalyticsEvent</code>
+				</li>
+			</ul>
+			<p>
+				The following types have been removed from the library and can either be safely replaced
+				with an alternate type or removed entirely in favour of type inference:
+			</p>
+			<ul>
+				<li>
+					<code>ObjectType</code> =&gt; <code>Record&lt;string, any&gt;</code> or{' '}
+					<code>[key: string]: any</code>
+				</li>
+				<li>
+					<code>CreateAndFireEventFunction</code> now inferred by TypeScript
+				</li>
+				<li>
+					<code>AnalyticsEventUpdater</code> now inferred by TypeScript
+				</li>
+			</ul>
+			<h4>
+				Using <code>withAnalyticsEvents</code> and <code>withAnalyticsContext</code> with
+				type-safety
+			</h4>
+			<p>
+				After upgrading to v6, you might now be greeted with TypeScript errors relating to{' '}
+				<code>withAnalyticsEvents</code> and <code>withAnalyticsContext</code>. As described above,
+				there have been a lot of changes to the way types are applied to these HOCs.
+			</p>
+			<p>
+				Previously, props needed to be explicitly defined and passed in as{' '}
+				<a href="https://www.typescriptlang.org/docs/handbook/generics.html">
+					generic type arguments
+				</a>
+				. Now, you should be able to remove the generic types and let TypeScript do the heavy
+				lifting.
+			</p>
+			<p>
+				<strong>Before…</strong>
+			</p>
+			<CodeBlock code={beforeCode} />
+			<p>
+				<strong>After…</strong>
+			</p>
+			<CodeBlock code={afterCode} />
+			<p>
+				This does however require you to extend your component&apos;s props with{' '}
+				<code>WithAnalyticsEventProps</code>. A common pattern you’ll find with other HOC
+				implementations, used to ensure you’re passing the correct super type to the HOC.
+			</p>
+			<CodeBlock code={propsCode} />
+			<p>
+				To provide additional flexibility, you can now opt-out of type inference if needed. It might
+				be necessary in edge-cases where TypeScript is not able to infer the prop types of the
+				component you have supplied. If that&apos;s the case, try passing in the generic type
+				arguments to <code>withAnalyticsEvents</code>.
+			</p>
+			<CodeBlock code={optOutCode} />
+		</div>
+	);
+}

package/docs/DocBlocks.tsx

@@ -0,0 +1,106 @@
+/* eslint-disable @atlaskit/design-system/ensure-design-token-usage, @atlaskit/ui-styling-standard/enforce-style-prop, @atlaskit/design-system/use-heading, @atlaskit/design-system/use-tokens-typography -- Legacy analytics-next docs intentionally use lightweight local HTML doc blocks instead of ADS docs helpers. */
+import React from 'react';
+
+type ExampleBlockProps = {
+	Component: React.ComponentType;
+	source?: string;
+	title?: string;
+};
+
+type PropsBlockProps = {
+	heading?: string;
+	props: unknown;
+};
+
+const codeBlockStyles: React.CSSProperties = {
+	backgroundColor: '#f4f5f7',
+	borderRadius: 3,
+	overflowX: 'auto',
+	padding: 16,
+	whiteSpace: 'pre-wrap',
+};
+
+const cardStyles: React.CSSProperties = {
+	border: '1px solid #dfe1e6',
+	borderRadius: 3,
+	marginBlock: 16,
+	padding: 16,
+};
+
+const summaryStyles: React.CSSProperties = {
+	cursor: 'pointer',
+	fontWeight: 600,
+	marginBottom: 12,
+};
+
+export function CodeBlock({ code }: { code: string }): React.JSX.Element {
+	return (
+		<pre style={codeBlockStyles}>
+			<code>{code}</code>
+		</pre>
+	);
+}
+
+export function ExampleBlock({ Component, title, source }: ExampleBlockProps): React.JSX.Element {
+	return (
+		<section style={cardStyles}>
+			{title ? <h4>{title}</h4> : null}
+			<div style={{ marginBlock: 16 }}>
+				<Component />
+			</div>
+			{source ? (
+				<details>
+					<summary style={summaryStyles}>View source</summary>
+					<CodeBlock code={source} />
+				</details>
+			) : null}
+		</section>
+	);
+}
+
+const serializeValue = (value: unknown): string => {
+	const seen = new WeakSet<object>();
+
+	try {
+		return (
+			JSON.stringify(
+				value,
+				(_key, currentValue) => {
+					if (typeof currentValue === 'function') {
+						return `[Function ${currentValue.name || 'anonymous'}]`;
+					}
+
+					if (typeof currentValue === 'symbol') {
+						return currentValue.toString();
+					}
+
+					if (typeof currentValue === 'undefined') {
+						return '[undefined]';
+					}
+
+					if (currentValue && typeof currentValue === 'object') {
+						if (seen.has(currentValue)) {
+							return '[Circular]';
+						}
+
+						seen.add(currentValue);
+					}
+
+					return currentValue;
+				},
+				2,
+			) ?? ''
+		);
+	} catch {
+		return String(value);
+	}
+};
+
+export function PropsBlock({ heading = 'Props', props }: PropsBlockProps): React.JSX.Element {
+	return (
+		<section style={cardStyles}>
+			<h4>{heading}</h4>
+			<CodeBlock code={serializeValue(props)} />
+		</section>
+	);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/analytics-next",
-	"version": "11.2.0",
+	"version": "11.2.1",
 	"description": "React components, HOCs and hooks to assist with tracking user activity with React components",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -41,7 +41,7 @@
 		"react-dom": "^18.2.0"
 	},
 	"devDependencies": {
-		"@atlassian/feature-flags-test-utils": "^1.0.0",
+		"@atlassian/feature-flags-test-utils": "^1.1.0",
 		"@atlassian/ssr-tests": "workspace:^",
 		"@testing-library/react": "^16.3.0",
 		"storybook-addon-performance": "^0.17.3"

package/afm-jira/tsconfig.json

@@ -1,30 +0,0 @@
-{
-	"extends": "../../../../tsconfig.local-consumption.json",
-	"compilerOptions": {
-		"target": "es5",
-		"outDir": "../../../../../jira/tsDist/@atlaskit__analytics-next/app",
-		"rootDir": "../",
-		"composite": true,
-		"noCheck": true,
-		"isolatedDeclarations": true
-	},
-	"include": ["../src/**/*.ts", "../src/**/*.tsx"],
-	"exclude": [
-		"../src/**/__tests__/*",
-		"../src/**/*.test.*",
-		"../src/**/test.*",
-		"../src/performance/examples.tsx",
-		"../docs/*",
-		"../src/**/examples.*",
-		"../src/**/examples/*",
-		"../src/**/examples/**/*",
-		"../src/**/*.stories.*",
-		"../src/**/stories/*",
-		"../src/**/stories/**/*"
-	],
-	"references": [
-		{
-			"path": "../../../platform/feature-flags/afm-jira/tsconfig.json"
-		}
-	]
-}