@atlaskit/primitives 6.2.0 → 6.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 +12 -0
- package/constellation/anchor/examples.mdx +9 -21
- package/constellation/anchor/usage.mdx +91 -27
- package/constellation/pressable/examples.mdx +9 -21
- package/constellation/pressable/usage.mdx +5 -2
- package/dist/cjs/components/anchor.js +1 -1
- package/dist/cjs/components/pressable.js +1 -1
- package/dist/es2019/components/anchor.js +1 -1
- package/dist/es2019/components/pressable.js +1 -1
- package/dist/esm/components/anchor.js +1 -1
- package/dist/esm/components/pressable.js +1 -1
- package/package.json +3 -3
- /package/constellation/bleed/{example.mdx → examples.mdx} +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# @atlaskit/primitives
|
|
2
2
|
|
|
3
|
+
## 6.3.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#95202](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/95202)
|
|
8
|
+
[`b28e3d55ab88`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/b28e3d55ab88) -
|
|
9
|
+
Adds "Fill" to the set of exported style map types
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- Updated dependencies
|
|
14
|
+
|
|
3
15
|
## 6.2.0
|
|
4
16
|
|
|
5
17
|
### Minor Changes
|
|
@@ -75,39 +75,27 @@ Anchor will only render a router link if:
|
|
|
75
75
|
appearance="source-only"
|
|
76
76
|
/>
|
|
77
77
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
### Track events for any analytics provider
|
|
83
|
-
|
|
84
|
-
Anchor comes with built-in Atlaskit analytics support using the [Analytics next package](https://atlaskit.atlassian.com/packages/analytics/analytics-next), and fires events for available listeners. Currently this is only available for `onClick`.
|
|
85
|
-
|
|
86
|
-
It always fires events on the `atlaskit` channel. To also fire events on other channels, use the provided `analyticsEvent` in `onClick`. To configure event data, use `componentName` (defaults to 'Anchor') and `analyticsContext` for passing other metadata.
|
|
87
|
-
|
|
88
|
-
See the event data in the console.
|
|
78
|
+
<Snippet
|
|
79
|
+
name="primitives-event-tracking-header"
|
|
80
|
+
variables={{ componentName: 'anchor' }}
|
|
81
|
+
/>
|
|
89
82
|
|
|
90
83
|
<Example
|
|
91
84
|
Component={AnchorAnalytics}
|
|
92
85
|
packageName="@atlaskit/primitives/anchor"
|
|
93
86
|
/>
|
|
94
87
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
#### GASv3 analytics
|
|
98
|
-
|
|
99
|
-
The Atlassian analytics bridge makes Atlaskit analytics events compatible with GASv3 (Global Analytics Service). This can also inject an `actionSubjectId` to the event if required.
|
|
100
|
-
|
|
101
|
-
See the event data in the console.
|
|
88
|
+
<Snippet name="primitives-event-tracking-gasv3" />
|
|
102
89
|
|
|
103
90
|
<Example
|
|
104
91
|
Component={AnchorAnalyticsGASv3}
|
|
105
92
|
packageName="@atlaskit/primitives/anchor"
|
|
106
93
|
/>
|
|
107
94
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
95
|
+
<Snippet
|
|
96
|
+
name="primitives-event-tracking-ufo"
|
|
97
|
+
variables={{ componentName: 'anchor' }}
|
|
98
|
+
/>
|
|
111
99
|
|
|
112
100
|
<Example
|
|
113
101
|
Component={AnchorPressTracing}
|
|
@@ -4,44 +4,108 @@ description: An anchor is a primitive for building custom links.
|
|
|
4
4
|
order: 2
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Usage
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Anchors help users navigate to another page or sections of a page. They can also download files or provide contact information such as phone numbers or email addresses.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Anchor has consistent focus styles and analytics built in. It works with design tokens to make it easy to compose Atlassian-styled links that aren't possible using the [link component](/components/link/examples), [link buttons](/components/button/link-button/examples), or other existing design system components.
|
|
12
12
|
|
|
13
|
-
##
|
|
13
|
+
## Use anchor when there aren't existing components that work for your experience
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Existing components such as the [link component](/components/link/examples) (for text-based links) should be used whenever possible for links to maintain visual consistency. Only use anchor when building custom links beyond the capabilities of the the link component.
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
Do not use anchor to perform actions rather than navigation. Use the equivalent [pressable primitive](/components/primitives/pressable/examples) to build a custom button instead.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
## Accessibility
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
### Underline links unless other context already indicates it is a link
|
|
22
22
|
|
|
23
|
-
Anchor
|
|
23
|
+
Anchor has an underline by default but it can be disabled in some circumstances. Underlines help differentiate links from regular text and addresses a WCAG-A recommendation. Using color alone isn't accessible, especially if links are surrounded by other text.
|
|
24
24
|
|
|
25
|
-
|
|
26
|
-
<Anchor<MyRouterLinkConfig>
|
|
27
|
-
href={{
|
|
28
|
-
to: '/home',
|
|
29
|
-
replace: true
|
|
30
|
-
}}
|
|
31
|
-
>
|
|
32
|
-
Home
|
|
33
|
-
</Anchor>
|
|
34
|
-
```
|
|
25
|
+
Only remove underlines if the context surrounding the link makes it clear that it is interactive, such as in navigation. Anhor may also be used to create linkable areas such as a card, in which case the underline may be omitted.
|
|
35
26
|
|
|
36
|
-
|
|
27
|
+
Also, don't underline text that isn't a link. This makes the text look clickable because it looks a link.
|
|
37
28
|
|
|
38
|
-
|
|
29
|
+
For more information see ['Understanding Use of Color (Level A)'](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) and ['Failure of Success Criterion 1.4.1 due to creating links that are not visually evident without color vision'](https://www.w3.org/WAI/WCAG22/Techniques/failures/F73).
|
|
30
|
+
|
|
31
|
+
<!-- TODO: Add do/dont images once designed (if necessary?) -->
|
|
32
|
+
|
|
33
|
+
<DoDont type="do">
|
|
34
|
+
Use underlined links in body copy. Only omit an underline if the context makes
|
|
35
|
+
it clear the link is selectable.
|
|
36
|
+
</DoDont>
|
|
37
|
+
|
|
38
|
+
<DoDont type="dont">Use underlined links in navigation.</DoDont>
|
|
39
|
+
|
|
40
|
+
### Use descriptive link text that clarifies the purpose of the link
|
|
41
|
+
|
|
42
|
+
Don't link vague words or phrases like “here” or “learn more.” Make sure the linked text clearly describes the purpose of the link.
|
|
43
|
+
|
|
44
|
+
<!-- TODO: Add some Do/Don't images as examples -->
|
|
45
|
+
|
|
46
|
+
<DoDont type="do">Clearly describe the purpose of the link.</DoDont>
|
|
47
|
+
|
|
48
|
+
<DoDont type="dont">Link vague words or phrases.</DoDont>
|
|
49
|
+
|
|
50
|
+
### Only open links in a new window or tab when necessary
|
|
51
|
+
|
|
52
|
+
Opening links in a new window can be disorienting for people, so only do it when necessary.
|
|
53
|
+
|
|
54
|
+
It might make sense for a link to open in a new window if:
|
|
55
|
+
|
|
56
|
+
- There's a risk of someone losing their current place or task
|
|
57
|
+
- The link takes the person out of the current product or to an external website
|
|
58
|
+
|
|
59
|
+
For more information see ['G200: Opening new windows and tabs from a link only when necessary'](https://www.w3.org/TR/WCAG20-TECHS/G200.html).
|
|
60
|
+
|
|
61
|
+
### Keep links large enough to interact with
|
|
62
|
+
|
|
63
|
+
Make link text size at least 12px. Smaller text is harder to read and interact with. If anchor is not used for text-based links, ensure the clickable area is at least 24 by 24 pixels for accessibility unless exempt from [Target Size (Minimum) (Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).
|
|
64
|
+
|
|
65
|
+
## Best practices
|
|
66
|
+
|
|
67
|
+
### Don't confuse links and buttons
|
|
68
|
+
|
|
69
|
+
Anchors are for navigation and URL changes, while buttons are for on-page actions such as form submissions or opening modals. These elements are treated differently by assistive technologies, so avoid using one in place of the other.
|
|
70
|
+
|
|
71
|
+
More details on [when to use links and buttons](/components/button/button-new/usage#use-buttons-for-actions-and-links-for-navigation).
|
|
72
|
+
|
|
73
|
+
## Content guidelines
|
|
74
|
+
|
|
75
|
+
### Use clear and unique link text
|
|
76
|
+
|
|
77
|
+
Try not to repeat the same link text over and over on a page. Make sure link text is clear about where the link will go.
|
|
78
|
+
|
|
79
|
+
### Specify download links, including file type and size
|
|
80
|
+
|
|
81
|
+
Always specify if a link triggers a download, and make the linked text clear about what exactly will be downloaded. Include file type and size as well.
|
|
82
|
+
|
|
83
|
+
### Don't include unnecessary links
|
|
84
|
+
|
|
85
|
+
Using too many links can overwhelm other, more important information on a page.
|
|
86
|
+
|
|
87
|
+
Anchors take people to a new page or location. Be mindful of whether or not the linked resource is helpful or distracting to the current task.
|
|
88
|
+
|
|
89
|
+
### Links in sentences or body copy
|
|
90
|
+
|
|
91
|
+
Only link the words that are necessary to clarify where the link goes. Don't link the entire sentence. (Linking smaller phrases can be better for internationalization when sentence structures change across languages.)
|
|
92
|
+
|
|
93
|
+
Only include the verb in the linked text if it better describes the purpose the link or differentiates it from other links and actions on the page.
|
|
94
|
+
|
|
95
|
+
For example:
|
|
96
|
+
|
|
97
|
+
> Update [Jira settings](https://atlassian.design/components/button/button-new/usage#use-buttons-for-actions-and-links-for-navigation) to turn off notifications. To upgrade, [sign up for Jira](https://atlassian.design/components/button/button-new/usage#use-buttons-for-actions-and-links-for-navigation).
|
|
98
|
+
|
|
99
|
+
If only Jira was linked, it wouldn't be clear that this was a sign up page.
|
|
100
|
+
|
|
101
|
+
### Links on their own (UI elements or navigation)
|
|
102
|
+
|
|
103
|
+
For standalone links, link the whole phrase. Don't add punctuation.
|
|
104
|
+
|
|
105
|
+
These type of links typically follow general button or other label content rules (sentence case capitalization, no punctuation, etc.)
|
|
39
106
|
|
|
40
107
|
## Related
|
|
41
108
|
|
|
42
|
-
- [
|
|
43
|
-
-
|
|
44
|
-
-
|
|
45
|
-
- [Manage horizontal layout using an inline component](/components/primitives/inline/usage)
|
|
46
|
-
- [Manage vertical layout using a stack component](/components/primitives/stack/usage)
|
|
47
|
-
- [Use design tokens in code with XCSS](/components/primitives/XCSS/usage)
|
|
109
|
+
- [Counterpart pressable primitive for buttons](/components/primitives/button/usage)
|
|
110
|
+
- Prefer to use existing components such as the [link component](/components/link/examples) or [link buttons](/components/button/link-button/examples)
|
|
111
|
+
- Anchor is built on the same API as [box](/components/primitives/box/usage)
|
|
@@ -87,39 +87,27 @@ Pressable passes through all valid HTML attributes to the underlying `<button>`
|
|
|
87
87
|
packageName="@atlaskit/primitives/pressable"
|
|
88
88
|
/>
|
|
89
89
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
### Track events for any analytics provider
|
|
95
|
-
|
|
96
|
-
Pressable comes with built-in Atlaskit analytics support using the [Analytics next package](https://atlaskit.atlassian.com/packages/analytics/analytics-next), and fires events for available listeners. Currently this is only available for `onClick`.
|
|
97
|
-
|
|
98
|
-
It always fires events on the `atlaskit` channel. To also fire events on other channels, use the provided `analyticsEvent` in `onClick`. To configure event data, use `componentName` (defaults to 'Pressable') and `analyticsContext` for passing other metadata.
|
|
99
|
-
|
|
100
|
-
See the event data in the console.
|
|
90
|
+
<Snippet
|
|
91
|
+
name="primitives-event-tracking-header"
|
|
92
|
+
variables={{ componentName: 'pressable' }}
|
|
93
|
+
/>
|
|
101
94
|
|
|
102
95
|
<Example
|
|
103
96
|
Component={PressableAnalytics}
|
|
104
97
|
packageName="@atlaskit/primitives/pressable"
|
|
105
98
|
/>
|
|
106
99
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
#### GASv3 analytics
|
|
110
|
-
|
|
111
|
-
The Atlassian analytics bridge makes Atlaskit analytics events compatible with GASv3 (Global Analytics Service). This can also inject an `actionSubjectId` to the event if required.
|
|
112
|
-
|
|
113
|
-
See the event data in the console.
|
|
100
|
+
<Snippet name="primitives-event-tracking-gasv3" />
|
|
114
101
|
|
|
115
102
|
<Example
|
|
116
103
|
Component={PressableAnalyticsGASv3}
|
|
117
104
|
packageName="@atlaskit/primitives/pressable"
|
|
118
105
|
/>
|
|
119
106
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
107
|
+
<Snippet
|
|
108
|
+
name="primitives-event-tracking-ufo"
|
|
109
|
+
variables={{ componentName: 'pressable' }}
|
|
110
|
+
/>
|
|
123
111
|
|
|
124
112
|
<Example
|
|
125
113
|
Component={PressablePressTracing}
|
|
@@ -7,6 +7,8 @@ order: 2
|
|
|
7
7
|
import pressablePrimaryDo from './images/pressable-01a-do.png';
|
|
8
8
|
import pressablePrimaryDont from './images/pressable-01b-dont.png';
|
|
9
9
|
|
|
10
|
+
## Usage
|
|
11
|
+
|
|
10
12
|
Pressable is a button with consistent focus styles and analytics built in. Pressable works with design tokens to make it easy to compose Atlassian-styled clickable elements that aren't possible using existing [buttons](/components/button/examples), [menus](/components/menu/examples), or other existing design system components.
|
|
11
13
|
|
|
12
14
|
|
|
@@ -15,7 +17,7 @@ Pressable is a button with consistent focus styles and analytics built in. Press
|
|
|
15
17
|
2. **Focus ring**: This is included in pressable and appears on keyboard focus.
|
|
16
18
|
3. **Accessible label:** Pressable should always include a clear label for accessibility. Use this to communicate the action that occurs when the button is pressed.
|
|
17
19
|
|
|
18
|
-
|
|
20
|
+
### Use pressable when there aren't existing components that work for your experience
|
|
19
21
|
|
|
20
22
|
Only use pressable when existing components such as [the button component](/components/button/examples), menus, or other existing design system components can't be customized to fit your case. Using existing components with safe customizations will prevent inconsistency as Atlassian UI evolves.
|
|
21
23
|
|
|
@@ -95,5 +97,6 @@ Follow label and content guidelines for [buttons](/components/button/button-new/
|
|
|
95
97
|
|
|
96
98
|
## Related
|
|
97
99
|
|
|
98
|
-
-
|
|
100
|
+
- [Counterpart anchor primitive for links](/components/primitives/button/usage)
|
|
101
|
+
- Prefer to use existing components such as [buttons](/components/button/examples) or [menus](/components/menu/examples) for most actions in Atlassian products
|
|
99
102
|
- Pressable is built on the same API as [box](/components/primitives/box/usage)
|
|
@@ -76,7 +76,7 @@ var Anchor = function Anchor(_ref, ref) {
|
|
|
76
76
|
action: 'clicked',
|
|
77
77
|
componentName: componentName || 'Anchor',
|
|
78
78
|
packageName: "@atlaskit/primitives",
|
|
79
|
-
packageVersion: "6.
|
|
79
|
+
packageVersion: "6.3.0",
|
|
80
80
|
analyticsData: analyticsContext,
|
|
81
81
|
actionSubject: 'link'
|
|
82
82
|
});
|
|
@@ -78,7 +78,7 @@ var Pressable = /*#__PURE__*/(0, _react.forwardRef)(function (_ref, ref) {
|
|
|
78
78
|
action: 'clicked',
|
|
79
79
|
componentName: componentName || 'Pressable',
|
|
80
80
|
packageName: "@atlaskit/primitives",
|
|
81
|
-
packageVersion: "6.
|
|
81
|
+
packageVersion: "6.3.0",
|
|
82
82
|
analyticsData: analyticsContext,
|
|
83
83
|
actionSubject: 'button'
|
|
84
84
|
});
|
|
@@ -64,7 +64,7 @@ const Pressable = /*#__PURE__*/forwardRef(({
|
|
|
64
64
|
action: 'clicked',
|
|
65
65
|
componentName: componentName || 'Pressable',
|
|
66
66
|
packageName: "@atlaskit/primitives",
|
|
67
|
-
packageVersion: "6.
|
|
67
|
+
packageVersion: "6.3.0",
|
|
68
68
|
analyticsData: analyticsContext,
|
|
69
69
|
actionSubject: 'button'
|
|
70
70
|
});
|
|
@@ -66,7 +66,7 @@ var Anchor = function Anchor(_ref, ref) {
|
|
|
66
66
|
action: 'clicked',
|
|
67
67
|
componentName: componentName || 'Anchor',
|
|
68
68
|
packageName: "@atlaskit/primitives",
|
|
69
|
-
packageVersion: "6.
|
|
69
|
+
packageVersion: "6.3.0",
|
|
70
70
|
analyticsData: analyticsContext,
|
|
71
71
|
actionSubject: 'link'
|
|
72
72
|
});
|
|
@@ -68,7 +68,7 @@ var Pressable = /*#__PURE__*/forwardRef(function (_ref, ref) {
|
|
|
68
68
|
action: 'clicked',
|
|
69
69
|
componentName: componentName || 'Pressable',
|
|
70
70
|
packageName: "@atlaskit/primitives",
|
|
71
|
-
packageVersion: "6.
|
|
71
|
+
packageVersion: "6.3.0",
|
|
72
72
|
analyticsData: analyticsContext,
|
|
73
73
|
actionSubject: 'button'
|
|
74
74
|
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@atlaskit/primitives",
|
|
3
|
-
"version": "6.
|
|
3
|
+
"version": "6.3.0",
|
|
4
4
|
"description": "Primitives are token-backed low-level building blocks.",
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"registry": "https://registry.npmjs.org/"
|
|
@@ -112,7 +112,7 @@
|
|
|
112
112
|
"slug": "primitives/anchor",
|
|
113
113
|
"id": "@atlaskit/primitives/anchor",
|
|
114
114
|
"status": {
|
|
115
|
-
"type": "
|
|
115
|
+
"type": "closed-beta"
|
|
116
116
|
}
|
|
117
117
|
}
|
|
118
118
|
]
|
|
@@ -128,7 +128,7 @@
|
|
|
128
128
|
"@atlaskit/css": "^0.1.0",
|
|
129
129
|
"@atlaskit/ds-lib": "^2.3.0",
|
|
130
130
|
"@atlaskit/interaction-context": "^2.1.0",
|
|
131
|
-
"@atlaskit/tokens": "^1.
|
|
131
|
+
"@atlaskit/tokens": "^1.49.0",
|
|
132
132
|
"@atlaskit/visually-hidden": "^1.3.0",
|
|
133
133
|
"@babel/runtime": "^7.0.0",
|
|
134
134
|
"@emotion/react": "^11.7.1",
|
|
File without changes
|