@atlaskit/analytics-next 11.2.2 → 11.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +21 -0
- package/analytics-next.docs.tsx +200 -0
- package/package.json +4 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,26 @@
|
|
|
1
1
|
# @atlaskit/analytics-next
|
|
2
2
|
|
|
3
|
+
## 11.3.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [`f8b3089961cdf`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f8b3089961cdf) -
|
|
8
|
+
Extend `StructuredContentSource` so `*.docs.tsx` files can describe packages whose exports are not
|
|
9
|
+
all renderable React components. The container now accepts optional `package`, `hooks`, and
|
|
10
|
+
`utilities` (function / constant / type) keys alongside the existing `components` key. New
|
|
11
|
+
per-kind schemas: `hookDocsSourceSchema`, `utilityDocsSourceSchema`, plus `packageMetadataSchema`
|
|
12
|
+
for shared package-level metadata.
|
|
13
|
+
|
|
14
|
+
All new fields are optional, so existing components-only `*.docs.tsx` files continue to work
|
|
15
|
+
unchanged — this is an additive, non-breaking extension.
|
|
16
|
+
|
|
17
|
+
Pilots the new shape with `docs.tsx` files for `@atlaskit/analytics-next`, `@atlaskit/layering`,
|
|
18
|
+
`@af/accessibility-testing`, `@af/react-unit-testing`, `@atlaskit/pragmatic-drag-and-drop-hitbox`,
|
|
19
|
+
`@atlaskit/pragmatic-drag-and-drop-live-region`, `@atlaskit/feature-flag-client`,
|
|
20
|
+
`@atlaskit/frontend-utilities`, and `@atlaskit/linking-common`. The last two are non-ADS pilots
|
|
21
|
+
that exercise the new `hooks` and `utilities` kinds in `helpers/` and `linking-platform/`. These
|
|
22
|
+
pilot files are explicitly marked as non-final in their file-level JSDoc.
|
|
23
|
+
|
|
3
24
|
## 11.2.2
|
|
4
25
|
|
|
5
26
|
### Patch Changes
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Structured MCP docs for `@atlaskit/analytics-next`.
|
|
3
|
+
*
|
|
4
|
+
* ⚠️ Pilot / not yet final. This file is part of the libraries-content pilot
|
|
5
|
+
* for the "Libraries, hooks, utilities in structured content" RFC. The
|
|
6
|
+
* container schema and per-kind shapes are still in review — expect breaking
|
|
7
|
+
* changes before this is rolled out broadly. Do not depend on the format yet.
|
|
8
|
+
*
|
|
9
|
+
* This is the canonical mixed-kind example: the package exports React
|
|
10
|
+
* components (`AnalyticsListener`), hooks (`useAnalyticsEvents`), and utility
|
|
11
|
+
* functions (`createAndFireEvent`). Each kind lands in the matching top-level
|
|
12
|
+
* key of the container schema.
|
|
13
|
+
*
|
|
14
|
+
* Contact #dst-structured-content in Slack with questions.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import path from 'path';
|
|
18
|
+
|
|
19
|
+
import type { StructuredContentSource } from '@atlassian/structured-docs-types';
|
|
20
|
+
|
|
21
|
+
import packageJson from './package.json';
|
|
22
|
+
|
|
23
|
+
const packagePath = path.resolve(__dirname);
|
|
24
|
+
|
|
25
|
+
const documentation: StructuredContentSource = {
|
|
26
|
+
package: {
|
|
27
|
+
package: '@atlaskit/analytics-next',
|
|
28
|
+
packagePath,
|
|
29
|
+
packageJson,
|
|
30
|
+
overview:
|
|
31
|
+
'React components, hooks, and helpers for instrumenting user activity. Wrap your app in an `AnalyticsListener` to subscribe to events on a channel, fire events from your components with `useAnalyticsEvents`, and decorate child events with `AnalyticsContext`.',
|
|
32
|
+
},
|
|
33
|
+
components: [
|
|
34
|
+
{
|
|
35
|
+
name: 'AnalyticsListener',
|
|
36
|
+
description:
|
|
37
|
+
'Subscribes to analytics events fired on a given channel from anywhere in its subtree. Mount once near the app root per channel you want to listen on.',
|
|
38
|
+
status: 'general-availability',
|
|
39
|
+
import: {
|
|
40
|
+
name: 'AnalyticsListener',
|
|
41
|
+
package: '@atlaskit/analytics-next',
|
|
42
|
+
type: 'named',
|
|
43
|
+
packagePath,
|
|
44
|
+
packageJson,
|
|
45
|
+
},
|
|
46
|
+
usageGuidelines: [
|
|
47
|
+
'Mount one listener per channel near the app root. Use `channel="*"` to listen to every channel.',
|
|
48
|
+
'Forward received events to your downstream analytics SDK (Segment, GASv3, etc.) inside `onEvent`.',
|
|
49
|
+
],
|
|
50
|
+
keywords: ['analytics', 'listener', 'events', 'analytics-next'],
|
|
51
|
+
categories: ['analytics'],
|
|
52
|
+
examples: [
|
|
53
|
+
{
|
|
54
|
+
name: 'Basic listener',
|
|
55
|
+
description: 'Subscribe to an entire app and log events.',
|
|
56
|
+
source: path.resolve(packagePath, './examples/10-basic-create-and-fire.tsx'),
|
|
57
|
+
},
|
|
58
|
+
],
|
|
59
|
+
},
|
|
60
|
+
{
|
|
61
|
+
name: 'AnalyticsContext',
|
|
62
|
+
description:
|
|
63
|
+
'Decorates every analytics event fired in its subtree with extra context data (e.g. the current page or feature area).',
|
|
64
|
+
status: 'general-availability',
|
|
65
|
+
import: {
|
|
66
|
+
name: 'AnalyticsContext',
|
|
67
|
+
package: '@atlaskit/analytics-next',
|
|
68
|
+
type: 'named',
|
|
69
|
+
packagePath,
|
|
70
|
+
packageJson,
|
|
71
|
+
},
|
|
72
|
+
usageGuidelines: [
|
|
73
|
+
'Nest `AnalyticsContext` providers — context from each one is appended in order, so the closest provider is last in the resulting array.',
|
|
74
|
+
],
|
|
75
|
+
keywords: ['analytics', 'context', 'analytics-next'],
|
|
76
|
+
categories: ['analytics'],
|
|
77
|
+
examples: [
|
|
78
|
+
{
|
|
79
|
+
name: 'Adding context',
|
|
80
|
+
description: 'Attach feature area context to all child events.',
|
|
81
|
+
source: path.resolve(packagePath, './examples/20-adding-analytics-context.tsx'),
|
|
82
|
+
},
|
|
83
|
+
],
|
|
84
|
+
},
|
|
85
|
+
{
|
|
86
|
+
name: 'AnalyticsErrorBoundary',
|
|
87
|
+
description:
|
|
88
|
+
'Error boundary that fires an analytics event when a render error is caught, then optionally renders a fallback UI.',
|
|
89
|
+
status: 'general-availability',
|
|
90
|
+
import: {
|
|
91
|
+
name: 'AnalyticsErrorBoundary',
|
|
92
|
+
package: '@atlaskit/analytics-next',
|
|
93
|
+
type: 'named',
|
|
94
|
+
packagePath,
|
|
95
|
+
packageJson,
|
|
96
|
+
},
|
|
97
|
+
usageGuidelines: [
|
|
98
|
+
'Wrap experiences whose render failures you want to instrument. Provide `ErrorComponent` for a graceful fallback.',
|
|
99
|
+
],
|
|
100
|
+
keywords: ['analytics', 'error-boundary', 'analytics-next'],
|
|
101
|
+
categories: ['analytics', 'error-handling'],
|
|
102
|
+
examples: [
|
|
103
|
+
{
|
|
104
|
+
name: 'Error boundary with fallback',
|
|
105
|
+
description: 'Render a fallback component and fire an analytics event when a child throws.',
|
|
106
|
+
source: path.resolve(packagePath, './examples/11-error-boundary-with-error-component.tsx'),
|
|
107
|
+
},
|
|
108
|
+
],
|
|
109
|
+
},
|
|
110
|
+
],
|
|
111
|
+
hooks: [
|
|
112
|
+
{
|
|
113
|
+
name: 'useAnalyticsEvents',
|
|
114
|
+
description:
|
|
115
|
+
'Returns `createAnalyticsEvent`, a stable callback that produces a `UIAnalyticsEvent` pre-wired with the surrounding analytics context and handlers. Call `.fire(channel)` on the returned event to dispatch it.',
|
|
116
|
+
status: 'general-availability',
|
|
117
|
+
parameters: [],
|
|
118
|
+
returns: {
|
|
119
|
+
type: '{ createAnalyticsEvent: (payload: AnalyticsEventPayload) => UIAnalyticsEvent }',
|
|
120
|
+
description:
|
|
121
|
+
'`createAnalyticsEvent` is referentially stable per nearest `AnalyticsContext`, so it is safe to put in dependency arrays.',
|
|
122
|
+
},
|
|
123
|
+
usageGuidelines: [
|
|
124
|
+
'Use inside any component that needs to fire events. Always pair with a parent `AnalyticsListener`, otherwise events fire into the void.',
|
|
125
|
+
'Build the payload with the smallest information the listener needs — heavy serialisation belongs in the handler, not the call site.',
|
|
126
|
+
],
|
|
127
|
+
keywords: ['analytics', 'hook', 'useAnalyticsEvents', 'analytics-next'],
|
|
128
|
+
categories: ['analytics', 'hooks'],
|
|
129
|
+
examples: [
|
|
130
|
+
{
|
|
131
|
+
name: 'Fire on click',
|
|
132
|
+
description: 'Create and fire a click event from a button handler.',
|
|
133
|
+
source: path.resolve(packagePath, './examples/10-basic-create-and-fire.tsx'),
|
|
134
|
+
},
|
|
135
|
+
],
|
|
136
|
+
},
|
|
137
|
+
],
|
|
138
|
+
utilities: [
|
|
139
|
+
{
|
|
140
|
+
kind: 'function',
|
|
141
|
+
name: 'createAndFireEvent',
|
|
142
|
+
description:
|
|
143
|
+
'Curried helper that builds a `UIAnalyticsEvent` for a payload and fires it on a channel in one go. The original event is also returned so the call site can keep working with it.',
|
|
144
|
+
status: 'general-availability',
|
|
145
|
+
signature:
|
|
146
|
+
'(channel?: string) => (payload: AnalyticsEventPayload) => (createAnalyticsEvent: CreateUIAnalyticsEvent) => UIAnalyticsEvent',
|
|
147
|
+
parameters: [
|
|
148
|
+
{ name: 'channel', type: 'string', description: 'Optional channel to fire on.', isOptional: true },
|
|
149
|
+
{ name: 'payload', type: 'AnalyticsEventPayload' },
|
|
150
|
+
{
|
|
151
|
+
name: 'createAnalyticsEvent',
|
|
152
|
+
type: 'CreateUIAnalyticsEvent',
|
|
153
|
+
description: 'The factory from `useAnalyticsEvents()` or `withAnalyticsEvents`.',
|
|
154
|
+
},
|
|
155
|
+
],
|
|
156
|
+
returns: {
|
|
157
|
+
type: 'UIAnalyticsEvent',
|
|
158
|
+
description: 'The original (un-cloned) consumer event so callers can attach further context.',
|
|
159
|
+
},
|
|
160
|
+
usageGuidelines: [
|
|
161
|
+
'Reach for `createAndFireEvent` when you want a one-liner inside an event handler. For more complex flows, build and fire the event explicitly.',
|
|
162
|
+
],
|
|
163
|
+
keywords: ['analytics', 'utility', 'createAndFireEvent', 'analytics-next'],
|
|
164
|
+
categories: ['analytics', 'utilities'],
|
|
165
|
+
examples: [],
|
|
166
|
+
},
|
|
167
|
+
{
|
|
168
|
+
kind: 'function',
|
|
169
|
+
name: 'isUIAnalyticsEvent',
|
|
170
|
+
description:
|
|
171
|
+
'Type-guard that returns true if the given value is a `UIAnalyticsEvent` (including instances from older copies of `analytics-next`).',
|
|
172
|
+
status: 'general-availability',
|
|
173
|
+
signature: '(obj: unknown) => obj is UIAnalyticsEvent',
|
|
174
|
+
parameters: [{ name: 'obj', type: 'unknown' }],
|
|
175
|
+
returns: { type: 'boolean' },
|
|
176
|
+
usageGuidelines: [
|
|
177
|
+
'Use in listener handlers when you receive events from third-party code and need to narrow before reading `.payload`.',
|
|
178
|
+
],
|
|
179
|
+
keywords: ['analytics', 'guard', 'isUIAnalyticsEvent', 'analytics-next'],
|
|
180
|
+
categories: ['analytics', 'utilities'],
|
|
181
|
+
examples: [],
|
|
182
|
+
},
|
|
183
|
+
{
|
|
184
|
+
kind: 'type',
|
|
185
|
+
name: 'UIAnalyticsEventHandler',
|
|
186
|
+
description:
|
|
187
|
+
'Signature for any function that receives events from an `AnalyticsListener`. Implement to forward events to your analytics SDK.',
|
|
188
|
+
status: 'general-availability',
|
|
189
|
+
definition: '(event: UIAnalyticsEvent, channel?: string) => void',
|
|
190
|
+
usageGuidelines: [
|
|
191
|
+
'Handlers must not throw — analytics must never crash product UI. The runtime swallows handler errors in production and logs them in development.',
|
|
192
|
+
],
|
|
193
|
+
keywords: ['analytics', 'type', 'handler', 'UIAnalyticsEventHandler', 'analytics-next'],
|
|
194
|
+
categories: ['analytics', 'types'],
|
|
195
|
+
examples: [],
|
|
196
|
+
},
|
|
197
|
+
],
|
|
198
|
+
};
|
|
199
|
+
|
|
200
|
+
export default documentation;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@atlaskit/analytics-next",
|
|
3
|
-
"version": "11.
|
|
3
|
+
"version": "11.3.0",
|
|
4
4
|
"description": "React components, HOCs and hooks to assist with tracking user activity with React components",
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"registry": "https://registry.npmjs.org/"
|
|
@@ -51,7 +51,10 @@
|
|
|
51
51
|
"@atlassian/feature-flags-test-utils": "^1.1.0",
|
|
52
52
|
"@atlassian/react-compiler-gating": "workspace:^",
|
|
53
53
|
"@atlassian/ssr-tests": "workspace:^",
|
|
54
|
+
"@atlassian/structured-docs-types": "workspace:^",
|
|
54
55
|
"@testing-library/react": "^16.3.0",
|
|
56
|
+
"react": "^18.2.0",
|
|
57
|
+
"react-dom": "^18.2.0",
|
|
55
58
|
"storybook-addon-performance": "^0.17.3"
|
|
56
59
|
},
|
|
57
60
|
"overrides": {
|