@atlaskit/primitives 7.0.1 → 7.0.2

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.
Files changed (12) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/constellation/pressable/examples.mdx +23 -20
  3. package/constellation/pressable/usage.mdx +35 -33
  4. package/dist/cjs/components/anchor.js +4 -4
  5. package/dist/cjs/components/pressable.js +1 -1
  6. package/dist/es2019/components/anchor.js +4 -4
  7. package/dist/es2019/components/pressable.js +1 -1
  8. package/dist/esm/components/anchor.js +4 -4
  9. package/dist/esm/components/pressable.js +1 -1
  10. package/dist/types/components/anchor.d.ts +4 -4
  11. package/dist/types-ts4.5/components/anchor.d.ts +4 -4
  12. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # @atlaskit/primitives
2
2
 
3
+ ## 7.0.2
4
+
5
+ ### Patch Changes
6
+
7
+ - [#110867](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/110867)
8
+ [`dc7e72da70ef7`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/dc7e72da70ef7) -
9
+ Migrating instances of `UNSAFE_ANCHOR` primitive imports to the new safe import `Anchor`, in
10
+ preparation of Anchor open beta and removal of the unsafe export from `@atlaskit/primitives`
11
+
3
12
  ## 7.0.1
4
13
 
5
14
  ### Patch Changes
package/constellation/pressable/examples.mdx CHANGED
@@ -23,25 +23,22 @@ import SectionMessage from '@atlaskit/section-message';
23
23
  directoryName="primitives"
24
24
  />
25
25
 
26
- Pressable is a primitive used for building custom buttons with Atlassian Design System styling and
27
- built-in event tracking. It renders a `<button>` element.
28
-
29
- Only use Pressable when existing components such as [button](/components/button/examples) are
30
- unsuitable and unable to be customized to fit your needs.
26
+ Pressable is a primitive for building custom buttons with Atlassian Design System styling and
27
+ built-in event tracking. It renders a `<button>` element. Use pressable when existing
28
+ [buttons](/components/button/examples) can't be customized to fit your needs.
31
29
 
32
30
  ## Default
33
31
 
34
- Pressable is unstyled by default.
32
+ Pressable is unstyled by default, aside from basic focus styles.
35
33
 
36
34
  <Example Component={PressableDefault} packageName="@atlaskit/primitives/pressable" />
37
35
 
38
36
  ## Basic styling with XCSS
39
37
 
40
- Pressable can be styled using XCSS. Ensure styling indicates the interaction state using `:hover`
41
- and `:active` pseudo-classes. Pressable includes consistent Atlassian Design System `:focus` styles,
42
- so it's unnecessary to add your own.
38
+ Pressable can be styled further using the design system styling API,
39
+ [XCSS](/components/primitives/xcss).
43
40
 
44
- For more information on XCSS, see the [XCSS documentation](/components/primitives/xcss).
41
+ Make sure styling indicates the interaction state using `:hover` and `:active` pseudo-classes.
45
42
 
46
43
  <Example Component={PressableBasic} packageName="@atlaskit/primitives/pressable" />
47
44
 
@@ -57,20 +54,26 @@ Use a combination of XCSS and other primitives for more complex designs.
57
54
 
58
55
  ## Disabled
59
56
 
60
- Pressable can be disabled using the `isDisabled` prop. Disabled styles should be conditionally
61
- applied and defined using XCSS.
57
+ You can disable pressable buttons with the `isDisabled` prop. Disabled styles should be applied and
58
+ defined conditionally using XCSS.
59
+
60
+ Disabled buttons can cause accessibility issues (disabled elements are not in the tab order) so
61
+ wherever possible, avoid using `isDisabled`. Instead, use validation or other techniques to show
62
+ users how to proceed.
63
+
64
+ <!-- todo: snippet for disabled a11y warnings? -->
62
65
 
63
66
  <Example Component={PressableDisabled} packageName="@atlaskit/primitives/pressable" />
64
67
 
65
68
  ## Buttons without visible labels
66
69
 
67
- For buttons without visible labels such as icon buttons, ensure an accessible label is still
68
- available by using [the visually hidden component](/components/visually-hidden/examples). This will
69
- render hidden text inside the button, which is preferable over the `aria-label` attribute because
70
- not all screen readers translate this between languages.
70
+ For buttons without visible labels such as icon buttons, make an accessible label available using
71
+ the [visually hidden component](/components/visually-hidden/examples). This renders hidden text
72
+ inside the button for assistive technologies, which is preferable to an `aria-label` attribute
73
+ because not all screen readers translate these between languages.
71
74
 
72
- Provide a tooltip to help sighted users understand the button's purpose rather than relying on
73
- iconography alone.
75
+ Also, consider providing a [tooltip](/components/tooltip) to help sighted users understand the
76
+ button's purpose.
74
77
 
75
78
  <Example
76
79
  Component={PressableWithoutVisibleLabels}
@@ -80,8 +83,8 @@ iconography alone.
80
83
 
81
84
  ## HTML attributes
82
85
 
83
- Pressable passes through all valid HTML attributes to the underlying `<button>` element. It will
84
- default the `type` attribute to `button` to prevent buttons unintentionally submitting forms.
86
+ Pressable passes all valid HTML attributes to the underlying `<button>` element. The `type`
87
+ attribute defaults to `button` to prevent unintentionally submitting forms.
85
88
 
86
89
  <Example Component={PressableHtmlAttributes} packageName="@atlaskit/primitives/pressable" />
87
90
 
package/constellation/pressable/usage.mdx CHANGED
@@ -9,10 +9,11 @@ import pressablePrimaryDont from './images/pressable-01b-dont.png';
9
9
 
10
10
  ## Usage
11
11
 
12
- Pressable is a button with consistent focus styles and analytics built in. Pressable works with
13
- design tokens to make it easy to compose Atlassian-styled clickable elements that aren't possible
14
- using existing [buttons](/components/button/examples), [menus](/components/menu/examples), or other
15
- existing design system components.
12
+ Use pressable to make custom-styled buttons and other pressable elements. Pressable works similarly
13
+ to an HTML `<button>`, but with Atlassian focus styles, analytics events, and styling APIs built in.
14
+
15
+ For example, you could use pressable to make a colored square button that opens a color picker, or a
16
+ basic card that shows more details when selected.
16
17
 
17
18
  ![Pressable anatomy](./images/pressable-anatomy.png)
18
19
 
@@ -23,18 +24,19 @@ existing design system components.
23
24
  3. **Accessible label:** Pressable should always include a clear label for accessibility. Use this
24
25
  to communicate the action that occurs when the button is pressed.
25
26
 
26
- ### Use pressable when there aren't existing components that work for your experience
27
+ ### Use existing buttons and other components whenever possible
28
+
29
+ Only use pressable when existing components such as [buttons](/components/button/examples) or
30
+ [menus](/components/menu/examples) can't be customized to fit your case.
27
31
 
28
- Only use pressable when existing components such as
29
- [the button component](/components/button/examples), menus, or other existing design system
30
- components can't be customized to fit your case. Using existing components with safe customizations
31
- will prevent inconsistency as Atlassian UI evolves.
32
+ Using [existing components](/components) with safe customizations is usually faster and keeps
33
+ Atlassian UI more visually consistent as things change.
32
34
 
33
35
  <DoDont
34
36
  type="do"
35
37
  image={{
36
38
  url: pressablePrimaryDo,
37
- alt: "A set of custom buttons built with pressable that aren't possible using existing design system components",
39
+ alt: 'A set of custom buttons built with pressable that are not possible using existing design system components',
38
40
  }}
39
41
  >
40
42
  Use pressable to create buttons when there isn't an existing design system component to achieve
@@ -48,47 +50,47 @@ will prevent inconsistency as Atlassian UI evolves.
48
50
  alt: 'A custom button build with Pressable that looks similar to Button, an existing design system component',
49
51
  }}
50
52
  >
51
- Don't use pressable in place of an element that already has a design system representation, such
52
- as <a href="/components/button/examples">the button component</a>. This can cause visual and
53
- behavioral inconsistencies in Atlassian products.
53
+ Don't use pressable to redesign elements that already exists in the Atlassian design system, such
54
+ as <a href="/components/button/examples">buttons</a>. This can cause visual and behavioral
55
+ inconsistency in products.
54
56
  </DoDont>
55
57
 
56
58
  ## Accessibility
57
59
 
58
60
  ### Use clear labels for assistive technology
59
61
 
60
- Pressable should always announce what action will happen once pressed.
62
+ Pressable elements should always announce what action will happen once pressed, especially for
63
+ elements with no visible label, such as icon buttons.
61
64
 
62
65
  ![Pressable labels](./images/pressable-labels.png)
63
66
 
64
- #### When no visible label is present
67
+ Use [the visually hidden component](/components/visually-hidden/examples) to provide an accessible
68
+ label. This will render hidden text inside the button, which is preferable over the `aria-label`
69
+ attribute because not all screen readers translate this between languages.
65
70
 
66
- - Ensure an accessible label is still available by using
67
- [the visually hidden component](/components/visually-hidden/examples) which will render hidden
68
- text inside the button. This is preferable over the `aria-label` attribute because not all screen
69
- readers translate this between languages.
70
- - Use [a tooltip](/components/tooltip/examples) to provide sighted users with the same information.
71
+ Also consider [a tooltip](/components/tooltip/examples) to provide sighted users with the same
72
+ information.
71
73
 
72
74
  ### Focus ring behavior
73
75
 
74
- Pressable creates buttons that are available in focus order, and provides a visual ring to clarify
75
- what is in focus. Adding additional focus styles is unnecessary.
76
+ Pressable buttons are available in focus order, and include a visual ring to clarify what is in
77
+ focus by default. Adding additional focus styles is unnecessary.
76
78
 
77
79
  ### Avoid disabling buttons
78
80
 
79
81
  Disabled buttons can cause accessibility problems. Avoid disabling buttons and
80
- [follow our disabled and tooltip button guidance](/components/button/usage#avoid-disabling-buttons).
82
+ [follow our disabled button and tooltip guidance](/components/button/usage#avoid-disabling-buttons).
81
83
 
82
84
  ## Best practices
83
85
 
84
86
  ### Make it clear what can be pressed
85
87
 
86
- Custom buttons should be obviously interactable. Make sure they are clearly identifiable through
87
- styles, surrounding context, labels, or other cues.
88
+ Custom buttons should look interactive. Make sure clickable elements are clearly identifiable
89
+ through styles, surrounding context, labels, and other cues.
88
90
 
89
- ### Don't use pressable for navigation
91
+ ### Use pressable for on-page actions, not navigation
90
92
 
91
- Pressable is meant for on-page actions such as opening modals, or submitting forms. If you're making
93
+ Pressable is meant for on-page actions such as opening modals or submitting forms. If you're making
92
94
  something that navigates to a new page, use a component that renders a semantically correct HTML
93
95
  `<a>` element such as:
94
96
 
@@ -112,12 +114,12 @@ For example, _Change issue color to yellow_ instead of _yellow_.
112
114
  ### Follow other label and UI content guidance
113
115
 
114
116
  Follow label and content guidelines for [buttons](/components/button/usage#content-guidelines).
115
- Review our [general UI text guidance](/foundations/accessibility/#meaningful-text) for specific
116
- question.
117
+ Review the [general UI text guidance](/foundations/accessibility/#meaningful-text) for specific
118
+ questions.
117
119
 
118
120
  ## Related
119
121
 
120
- - [Counterpart anchor primitive for links](/components/primitives/button/usage)
121
- - Prefer to use existing components such as [buttons](/components/button/examples) or
122
- [menus](/components/menu/examples) for most actions in Atlassian products
123
- - Pressable is built on the same API as [box](/components/primitives/box/usage)
122
+ - Use existing components such as [buttons](/components/button/examples) or
123
+ [menus](/components/menu/examples) for most actions in Atlassian products.
124
+ - Use the [anchor primitive for custom links](/components/primitives/button/usage).
125
+ - Pressable is built on the same API as [box](/components/primitives/box/usage).
package/dist/cjs/components/anchor.js CHANGED
@@ -46,7 +46,7 @@ var focusRingStyles = (0, _xcss.xcss)({
46
46
  });
47
47
  var IS_EXTERNAL_LINK_REGEX = /^(?:(http|https):\/\/)/;
48
48
  var IS_NON_HTTP_BASED = /^(((mailto|tel|sms):)|(#))/;
49
- var Anchor = function Anchor(_ref, ref) {
49
+ var AnchorNoRef = function AnchorNoRef(_ref, ref) {
50
50
  var href = _ref.href,
51
51
  children = _ref.children,
52
52
  backgroundColor = _ref.backgroundColor,
@@ -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: "7.0.1",
79
+ packageVersion: "7.0.2",
80
80
  analyticsData: analyticsContext,
81
81
  actionSubject: 'link'
82
82
  });
@@ -138,5 +138,5 @@ var Anchor = function Anchor(_ref, ref) {
138
138
  * - [Code](https://atlassian.design/components/primitives/anchor/code)
139
139
  * - [Usage](https://atlassian.design/components/primitives/anchor/usage)
140
140
  */
141
- var UNSAFE_ANCHOR = /*#__PURE__*/(0, _react.forwardRef)(Anchor);
142
- var _default = exports.default = UNSAFE_ANCHOR;
141
+ var Anchor = /*#__PURE__*/(0, _react.forwardRef)(AnchorNoRef);
142
+ var _default = exports.default = Anchor;
package/dist/cjs/components/pressable.js CHANGED
@@ -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: "7.0.1",
81
+ packageVersion: "7.0.2",
82
82
  analyticsData: analyticsContext,
83
83
  actionSubject: 'button'
84
84
  });
package/dist/es2019/components/anchor.js CHANGED
@@ -32,7 +32,7 @@ const focusRingStyles = xcss({
32
32
  });
33
33
  const IS_EXTERNAL_LINK_REGEX = /^(?:(http|https):\/\/)/;
34
34
  const IS_NON_HTTP_BASED = /^(((mailto|tel|sms):)|(#))/;
35
- const Anchor = ({
35
+ const AnchorNoRef = ({
36
36
  href,
37
37
  children,
38
38
  backgroundColor,
@@ -62,7 +62,7 @@ const Anchor = ({
62
62
  action: 'clicked',
63
63
  componentName: componentName || 'Anchor',
64
64
  packageName: "@atlaskit/primitives",
65
- packageVersion: "7.0.1",
65
+ packageVersion: "7.0.2",
66
66
  analyticsData: analyticsContext,
67
67
  actionSubject: 'link'
68
68
  });
@@ -124,5 +124,5 @@ const Anchor = ({
124
124
  * - [Code](https://atlassian.design/components/primitives/anchor/code)
125
125
  * - [Usage](https://atlassian.design/components/primitives/anchor/usage)
126
126
  */
127
- const UNSAFE_ANCHOR = /*#__PURE__*/forwardRef(Anchor);
128
- export default UNSAFE_ANCHOR;
127
+ const Anchor = /*#__PURE__*/forwardRef(AnchorNoRef);
128
+ export default Anchor;
package/dist/es2019/components/pressable.js CHANGED
@@ -64,7 +64,7 @@ const Pressable = /*#__PURE__*/forwardRef(({
64
64
  action: 'clicked',
65
65
  componentName: componentName || 'Pressable',
66
66
  packageName: "@atlaskit/primitives",
67
- packageVersion: "7.0.1",
67
+ packageVersion: "7.0.2",
68
68
  analyticsData: analyticsContext,
69
69
  actionSubject: 'button'
70
70
  });
package/dist/esm/components/anchor.js CHANGED
@@ -36,7 +36,7 @@ var focusRingStyles = xcss({
36
36
  });
37
37
  var IS_EXTERNAL_LINK_REGEX = /^(?:(http|https):\/\/)/;
38
38
  var IS_NON_HTTP_BASED = /^(((mailto|tel|sms):)|(#))/;
39
- var Anchor = function Anchor(_ref, ref) {
39
+ var AnchorNoRef = function AnchorNoRef(_ref, ref) {
40
40
  var href = _ref.href,
41
41
  children = _ref.children,
42
42
  backgroundColor = _ref.backgroundColor,
@@ -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: "7.0.1",
69
+ packageVersion: "7.0.2",
70
70
  analyticsData: analyticsContext,
71
71
  actionSubject: 'link'
72
72
  });
@@ -128,5 +128,5 @@ var Anchor = function Anchor(_ref, ref) {
128
128
  * - [Code](https://atlassian.design/components/primitives/anchor/code)
129
129
  * - [Usage](https://atlassian.design/components/primitives/anchor/usage)
130
130
  */
131
- var UNSAFE_ANCHOR = /*#__PURE__*/forwardRef(Anchor);
132
- export default UNSAFE_ANCHOR;
131
+ var Anchor = /*#__PURE__*/forwardRef(AnchorNoRef);
132
+ export default Anchor;
package/dist/esm/components/pressable.js CHANGED
@@ -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: "7.0.1",
71
+ packageVersion: "7.0.2",
72
72
  analyticsData: analyticsContext,
73
73
  actionSubject: 'button'
74
74
  });
package/dist/types/components/anchor.d.ts CHANGED
@@ -26,7 +26,7 @@ export type AnchorProps<RouterLinkConfig extends Record<string, any> = never> =
26
26
  */
27
27
  analyticsContext?: Record<string, any>;
28
28
  };
29
- declare const Anchor: <RouterLinkConfig extends Record<string, any> = never>({ href, children, backgroundColor, padding, paddingBlock, paddingBlockStart, paddingBlockEnd, paddingInline, paddingInlineStart, paddingInlineEnd, testId, xcss: xcssStyles, target, onClick: providedOnClick, interactionName, componentName, analyticsContext, ...htmlAttributes }: AnchorProps<RouterLinkConfig>, ref: Ref<HTMLAnchorElement>) => JSX.Element;
29
+ declare const AnchorNoRef: <RouterLinkConfig extends Record<string, any> = never>({ href, children, backgroundColor, padding, paddingBlock, paddingBlockStart, paddingBlockEnd, paddingInline, paddingInlineStart, paddingInlineEnd, testId, xcss: xcssStyles, target, onClick: providedOnClick, interactionName, componentName, analyticsContext, ...htmlAttributes }: AnchorProps<RouterLinkConfig>, ref: Ref<HTMLAnchorElement>) => JSX.Element;
30
30
  /**
31
31
  * __Anchor__
32
32
  *
@@ -40,7 +40,7 @@ declare const Anchor: <RouterLinkConfig extends Record<string, any> = never>({ h
40
40
  * - [Code](https://atlassian.design/components/primitives/anchor/code)
41
41
  * - [Usage](https://atlassian.design/components/primitives/anchor/usage)
42
42
  */
43
- declare const UNSAFE_ANCHOR: <RouterLinkConfig extends Record<string, any> = never>(props: AnchorProps<RouterLinkConfig> & {
43
+ declare const Anchor: <RouterLinkConfig extends Record<string, any> = never>(props: AnchorProps<RouterLinkConfig> & {
44
44
  ref?: Ref<HTMLAnchorElement>;
45
- }) => ReturnType<typeof Anchor>;
46
- export default UNSAFE_ANCHOR;
45
+ }) => ReturnType<typeof AnchorNoRef>;
46
+ export default Anchor;
package/dist/types-ts4.5/components/anchor.d.ts CHANGED
@@ -26,7 +26,7 @@ export type AnchorProps<RouterLinkConfig extends Record<string, any> = never> =
26
26
  */
27
27
  analyticsContext?: Record<string, any>;
28
28
  };
29
- declare const Anchor: <RouterLinkConfig extends Record<string, any> = never>({ href, children, backgroundColor, padding, paddingBlock, paddingBlockStart, paddingBlockEnd, paddingInline, paddingInlineStart, paddingInlineEnd, testId, xcss: xcssStyles, target, onClick: providedOnClick, interactionName, componentName, analyticsContext, ...htmlAttributes }: AnchorProps<RouterLinkConfig>, ref: Ref<HTMLAnchorElement>) => JSX.Element;
29
+ declare const AnchorNoRef: <RouterLinkConfig extends Record<string, any> = never>({ href, children, backgroundColor, padding, paddingBlock, paddingBlockStart, paddingBlockEnd, paddingInline, paddingInlineStart, paddingInlineEnd, testId, xcss: xcssStyles, target, onClick: providedOnClick, interactionName, componentName, analyticsContext, ...htmlAttributes }: AnchorProps<RouterLinkConfig>, ref: Ref<HTMLAnchorElement>) => JSX.Element;
30
30
  /**
31
31
  * __Anchor__
32
32
  *
@@ -40,7 +40,7 @@ declare const Anchor: <RouterLinkConfig extends Record<string, any> = never>({ h
40
40
  * - [Code](https://atlassian.design/components/primitives/anchor/code)
41
41
  * - [Usage](https://atlassian.design/components/primitives/anchor/usage)
42
42
  */
43
- declare const UNSAFE_ANCHOR: <RouterLinkConfig extends Record<string, any> = never>(props: AnchorProps<RouterLinkConfig> & {
43
+ declare const Anchor: <RouterLinkConfig extends Record<string, any> = never>(props: AnchorProps<RouterLinkConfig> & {
44
44
  ref?: Ref<HTMLAnchorElement>;
45
- }) => ReturnType<typeof Anchor>;
46
- export default UNSAFE_ANCHOR;
45
+ }) => ReturnType<typeof AnchorNoRef>;
46
+ export default Anchor;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atlaskit/primitives",
3
- "version": "7.0.1",
3
+ "version": "7.0.2",
4
4
  "description": "Primitives are token-backed low-level building blocks.",
5
5
  "publishConfig": {
6
6
  "registry": "https://registry.npmjs.org/"