@atlaskit/primitives 6.5.0 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @atlaskit/primitives
 
+## 7.0.0
+
+### Major Changes
+
+- [#108387](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/108387)
+  [`0f3b7b4c63c6d`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/0f3b7b4c63c6d) -
+  `xcss`: Restrict valid chained pseudo-selectors a limited subset:
+
+  - `:visited:active`
+  - `:active:visited`
+  - `:hover::before`
+  - `:hover::after`
+  - `:focus-visible::before`
+  - `:focus-visible::after`
+
+  Previously, any combination of two pseudo-selectors was allowed. This decision was made to improve
+  performance for TypeScript compilation and IDE type hinting.
+
 ## 6.5.0
 
 ### Minor Changes

package/constellation/anchor/examples.mdx

@@ -22,21 +22,21 @@ import SectionMessage from '@atlaskit/section-message';
   directoryName="primitives"
 />
 
-Anchor is a primitive used for building custom links with Atlassian Design System styling, routing support, and built-in event tracking. Ultimately it renders an anchor `<a>` element.
+Anchor is a primitive for building custom links with Atlassian Design System styling, routing support, and built-in event tracking. It renders an anchor `<a>` element.
 
-Only use anchor when existing components such as [link](/components/link/examples) or [link button](/components/button/link-button/examples) are unsuitable and unable to be customized to fit your needs.
+Only use anchor when existing components such as [link](/components/link/examples) or [link button](/components/button/link-button/examples) can't be customized to fit your needs.
 
 ## Default
 
-Anchor is unstyled besides a default underline. If you are using the [CSS reset](/components/css-reset/examples), it will also inherit some global styles.
+Anchor is unstyled besides a default underline and consistent Atlassian Design System `:focus` styles.
+
+If you are using the [CSS reset](/components/css-reset/examples), anchor will also inherit some global styles.
 
 <Example Component={AnchorDefault} packageName="@atlaskit/primitives/anchor" />
 
 ## Basic styling with XCSS
 
-Anchor can be styled using XCSS. It includes consistent Atlassian Design System `:focus` styles, so it's unnecessary to add your own.
-
-For more information on XCSS, see the [XCSS documentation](/components/primitives/xcss).
+Anchor can be styled further using the design system styling API, [XCSS](/components/primitives/xcss).
 
 <Example Component={AnchorBasic} packageName="@atlaskit/primitives/anchor" />
 
@@ -48,7 +48,7 @@ Use a combination of XCSS and other primitives for more complex designs.
 
 ## HTML attributes
 
-Anchor passes through all valid HTML attributes to the underlying `<a>` element.
+Anchor can pass all valid [anchor HTML attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes), such as `rel` or `download`, to the underlying `<a>` element.
 
 <Example
   Component={AnchorHtmlAttributes}
@@ -57,7 +57,7 @@ Anchor passes through all valid HTML attributes to the underlying `<a>` element.
 
 ## Router links
 
-Routing libraries often supply their own link components enhanced with routing support. This can be configured in the [AppProvider context](/components/app-provider/examples#router-links), and anchor will automatically use it.
+Routing libraries often supply link components enhanced with routing support. You can configure this in the [AppProvider context](/components/app-provider/examples#router-links), and anchor will automatically use it.
 
 This example shows a configuration for [React Resource Router](https://github.com/atlassian-labs/react-resource-router), however any routing library can be used.
 

package/constellation/anchor/usage.mdx

@@ -6,28 +6,30 @@ order: 2
 
 ## Usage
 
-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.
+Use an anchor to make elements that work like hyperlinks. Anchors can navigate to any linkable location such as a web page, a location on a page, a file download, or a `mailto` email address.
 
-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.
 
-## Use anchor when there aren't existing components that work for your experience
+Anchor is based on the HTML `<a>` tag, but with Atlassian focus styles and analytics events built in. You can customize the anchor's appearance further using our styling APIs.
 
-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.
+For example, an anchor could be used to make [a link card](/components/primitives/anchor/examples#advanced-styling) with a larger clickable area than a typical [link](/components/link/examples).
 
-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.
+
+### Use links, link buttons, or other existing components where possible
+
+Anchor is meant for custom elements and styles that aren't possible using other components. For standard links or buttons that navigate users to a new location, use [link](/components/link/examples) or [link button](/components/button/link-button/examples).
+
+Using [existing components](/components) wherever possible makes Atlassian's UI more visually consistent, and these components are faster to use for most basic use cases.
 
 ## Accessibility
 
-### Underline links unless other context already indicates it is a link
+### Show what's clickable using underlines or other affordances
 
-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.
+Anchors have an underline by default. This helps differentiate links from regular text, which is an accessibility requirement. Using color alone to differentiate links isn't accessible, especially if links are surrounded by other text.
 
-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.
+Only remove underlines if the context surrounding the link makes it clear that it's interactive, such as in navigation or a card layout.
 
 Also, don't underline text that isn't a link. This makes the text look clickable because it looks a link.
 
-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).
-
 <!-- TODO: Add do/dont images once designed (if necessary?) -->
 
 <DoDont type="do">
@@ -37,13 +39,27 @@ For more information see ['Understanding Use of Color (Level A)'](https://www.w3
 
 <DoDont type="dont">Use underlined links in navigation.</DoDont>
 
+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).
+
+### Use anchor for links and navigation, not on-page actions
+
+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.
+
+Don't use anchor to make custom actions rather than navigation elements. To build a custom action or button, use the [pressable primitive](/components/primitives/pressable/examples) instead.
+
+More on [when to use links vs buttons](/components/button/usage#use-buttons-for-actions-and-links-for-navigation).
+
+
 ### Use descriptive link text that clarifies the purpose of the link
 
-Don't link vague words or phrases like “here” or “learn more.” Make sure the linked text clearly describes the purpose of the link.
+Don't link vague words or phrases like “here” or “learn more.” Make sure the linked text clearly describes the purpose of the link for assistive technologies.
 
+See [link content guidelines](/components/primitives/anchor/usage#content-guidelines) for details and examples.
+
+<!-- TODO: Crosslink updated link content guidance. Should be info in language and grammar and link component. (snippet time?) -->
 <!-- TODO: Add some Do/Don't images as examples -->
 
-<DoDont type="do">Clearly describe the purpose of the link.</DoDont>
+<DoDont type="do">Link text that describes the purpose of the link.</DoDont>
 
 <DoDont type="dont">Link vague words or phrases.</DoDont>
 
@@ -62,13 +78,6 @@ For more information see ['G200: Opening new windows and tabs from a link only w
 
 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).
 
-## Best practices
-
-### Don't confuse links and buttons
-
-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.
-
-More details on [when to use links and buttons](/components/button/usage#use-buttons-for-actions-and-links-for-navigation).
 
 ## Content guidelines
 
@@ -80,6 +89,8 @@ Try not to repeat the same link text over and over on a page. Make sure link tex
 
 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.
 
+<!-- TODO: add example of this -->
+
 ### Don't include unnecessary links
 
 Using too many links can overwhelm other, more important information on a page.
@@ -106,6 +117,6 @@ These type of links typically follow general button or other label content rules
 
 ## Related
 
-- [Counterpart pressable primitive for buttons](/components/primitives/button/usage)
-- Prefer to use existing components such as the [link component](/components/link/examples) or [link buttons](/components/button/link-button/examples)
-- Anchor is built on the same API as [box](/components/primitives/box/usage)
+- Use existing components such as [link](/components/link/examples) or [link button](/components/button/link-button/examples) wherever possible.
+- Use [pressable primitive for custom buttons](/components/primitives/button/usage).
+- Anchor is built on the same API as [box](/components/primitives/box/usage).

package/dist/cjs/components/anchor.js

@@ -76,7 +76,7 @@ var Anchor = function Anchor(_ref, ref) {
     action: 'clicked',
     componentName: componentName || 'Anchor',
     packageName: "@atlaskit/primitives",
-    packageVersion: "6.5.0",
+    packageVersion: "7.0.0",
     analyticsData: analyticsContext,
     actionSubject: 'link'
   });

package/dist/cjs/components/pressable.js

@@ -78,7 +78,7 @@ var Pressable = /*#__PURE__*/(0, _react.forwardRef)(function (_ref, ref) {
     action: 'clicked',
     componentName: componentName || 'Pressable',
     packageName: "@atlaskit/primitives",
-    packageVersion: "6.5.0",
+    packageVersion: "7.0.0",
     analyticsData: analyticsContext,
     actionSubject: 'button'
   });

package/dist/cjs/xcss/xcss.js

@@ -212,7 +212,7 @@ var parseXcss = exports.parseXcss = function parseXcss(args) {
 
 // Media queries should not contain nested media queries
 
-// Allow chained pseudos, e.g. `:visited:hover`
+// Allow only a specific subset of chained selectors to maintain workable TypeScript performance
 
 // Pseudos should not contain nested pseudos, or media queries
 

package/dist/es2019/components/anchor.js

@@ -62,7 +62,7 @@ const Anchor = ({
     action: 'clicked',
     componentName: componentName || 'Anchor',
     packageName: "@atlaskit/primitives",
-    packageVersion: "6.5.0",
+    packageVersion: "7.0.0",
     analyticsData: analyticsContext,
     actionSubject: 'link'
   });

package/dist/es2019/components/pressable.js

@@ -64,7 +64,7 @@ const Pressable = /*#__PURE__*/forwardRef(({
     action: 'clicked',
     componentName: componentName || 'Pressable',
     packageName: "@atlaskit/primitives",
-    packageVersion: "6.5.0",
+    packageVersion: "7.0.0",
     analyticsData: analyticsContext,
     actionSubject: 'button'
   });

package/dist/es2019/xcss/xcss.js

@@ -190,7 +190,7 @@ export const parseXcss = args => {
 
 // Media queries should not contain nested media queries
 
-// Allow chained pseudos, e.g. `:visited:hover`
+// Allow only a specific subset of chained selectors to maintain workable TypeScript performance
 
 // Pseudos should not contain nested pseudos, or media queries
 

package/dist/esm/components/anchor.js

@@ -66,7 +66,7 @@ var Anchor = function Anchor(_ref, ref) {
     action: 'clicked',
     componentName: componentName || 'Anchor',
     packageName: "@atlaskit/primitives",
-    packageVersion: "6.5.0",
+    packageVersion: "7.0.0",
     analyticsData: analyticsContext,
     actionSubject: 'link'
   });

package/dist/esm/components/pressable.js

@@ -68,7 +68,7 @@ var Pressable = /*#__PURE__*/forwardRef(function (_ref, ref) {
     action: 'clicked',
     componentName: componentName || 'Pressable',
     packageName: "@atlaskit/primitives",
-    packageVersion: "6.5.0",
+    packageVersion: "7.0.0",
     analyticsData: analyticsContext,
     actionSubject: 'button'
   });

package/dist/esm/xcss/xcss.js

@@ -208,7 +208,7 @@ export var parseXcss = function parseXcss(args) {
 
 // Media queries should not contain nested media queries
 
-// Allow chained pseudos, e.g. `:visited:hover`
+// Allow only a specific subset of chained selectors to maintain workable TypeScript performance
 
 // Pseudos should not contain nested pseudos, or media queries
 

package/dist/types/xcss/xcss.d.ts

@@ -1643,7 +1643,7 @@ type AllMedia = MediaQuery | '@media screen and (forced-colors: active), screen
 type CSSMediaQueries = {
     [MQ in AllMedia]?: Omit<SafeCSSObject, AllMedia>;
 };
-type ChainedCSSPseudos = `${CSS.Pseudos}${CSS.Pseudos}`;
+type ChainedCSSPseudos = ':visited:active' | ':active:visited' | ':hover::before' | ':hover::after' | ':focus-visible::before' | ':focus-visible::after';
 type CSSPseudos = {
     [Pseudo in CSS.Pseudos | ChainedCSSPseudos]?: Omit<SafeCSSObject, CSS.Pseudos | AllMedia>;
 };

package/dist/types-ts4.5/xcss/xcss.d.ts

@@ -1643,7 +1643,7 @@ type AllMedia = MediaQuery | '@media screen and (forced-colors: active), screen
 type CSSMediaQueries = {
     [MQ in AllMedia]?: Omit<SafeCSSObject, AllMedia>;
 };
-type ChainedCSSPseudos = `${CSS.Pseudos}${CSS.Pseudos}`;
+type ChainedCSSPseudos = ':visited:active' | ':active:visited' | ':hover::before' | ':hover::after' | ':focus-visible::before' | ':focus-visible::after';
 type CSSPseudos = {
     [Pseudo in CSS.Pseudos | ChainedCSSPseudos]?: Omit<SafeCSSObject, CSS.Pseudos | AllMedia>;
 };

package/extract-react-types/anchor-props.tsx

@@ -35,7 +35,7 @@ export default function Anchor<
 >(
   _: {
     /**
-     * A link can be provided as a string If a router link configuration is set in the [app provider](https://atlassian.design/components/app-provider/examples), this can be mapped to an underlying router link component. For advanced usage an object can be passed. See [the code examples](https://atlassian.design/components/primitives/anchor/examples#router-links) for more information.
+     * The URL or link location, which can be provided as a string if a router link configuration is set in the [app provider](https://atlassian.design/components/app-provider/examples). This can be mapped to an underlying router link component. For advanced usage, an object can be passed. See [routing examples](https://atlassian.design/components/primitives/anchor/examples#router-links) for more information.
      */
     href: string | RouterLinkConfig;
 
@@ -85,7 +85,7 @@ export default function Anchor<
     paddingInlineEnd?: Space;
 
     /**
-     * Handler called on click. You can use the second argument to fire Atlaskit analytics events on custom channels. They could then be routed to GASv3 analytics. See the code examples for information on [firing Atlaskit analytics events](https://atlassian.design/components/primitives/anchor/examples#atlaskit-analytics) or [routing these to GASv3 analytics](https://atlassian.design/components/primitives/anchor/examples#gasv3-analytics).
+     * Handler called on click. You can use the second argument to fire Atlaskit analytics events on custom channels. They could then be routed to GASv3 analytics. See examples for [firing Atlaskit analytics events](https://atlassian.design/components/primitives/anchor/examples#atlaskit-analytics) or [routing these to GASv3 analytics](https://atlassian.design/components/primitives/anchor/examples#gasv3-analytics).
      */
     onClick?: (
       e: React.MouseEvent<HTMLButtonElement>,
@@ -93,23 +93,22 @@ export default function Anchor<
     ) => void;
 
     /**
-     * An optional component name used to identify this component to Atlaskit analytics press listeners. This can be altered if a parent component's name is preferred rather than the default 'Anchor'. See [the code example](https://atlassian.design/components/primitives/anchor/examples#atlaskit-analytics) for more information.
+     * An optional component name used to identify this component to Atlaskit analytics press listeners. This can be altered if a parent component's name is preferred rather than the default 'Anchor'. See [the Atlaskit analytics example](https://atlassian.design/components/primitives/anchor/examples#atlaskit-analytics) for more information.
      */
     componentName?: string;
 
     /**
-     * Additional information to be included in the `context` of Atlaskit analytics events that come from anchor. See [the code example](https://atlassian.design/components/primitives/anchor/examples#atlaskit-analytics) for more information.
+     * Additional information to be included in the `context` of Atlaskit analytics events that come from anchor. See [the analytics example](https://atlassian.design/components/primitives/anchor/examples#atlaskit-analytics) for more information.
      */
     analyticsContext?: Record<string, any>;
 
     /**
-     * An optional name used to identify the anchor to interaction content listeners. By default, anchor fires React UFO (Unified Frontend Observability) press interactions for available listeners. This helps Atlassian measure performance and reliability. See [the code example](https://atlassian.design/components/primitives/anchor/examples#react-ufo-press-interactions) for more information.
+     * An optional name used to identify the anchor to interaction content listeners. By default, anchor fires React UFO (Unified Frontend Observability) press interactions for available listeners. This helps Atlassian measure performance and reliability. See [the React UFO press example](https://atlassian.design/components/primitives/anchor/examples#react-ufo-press-interactions) for more information.
      */
     interactionName?: string;
 
     /**
-     * A token alias for background color. See:<br>
-     * [https://atlassian.design/components/tokens/all-tokens#color-background](https://atlassian.design/components/tokens/all-tokens#color-background)<br>
+     * A token alias for background color ([background color tokens](https://atlassian.design/components/components/tokens/all-tokens#color-background)).
      * When the background color is set to a [surface token](/components/tokens/all-tokens#elevation-surface),
      * the [current surface](/components/tokens/code#current-surface-color) CSS variable will also be set to this value in the Box styles.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaskit/primitives",
-  "version": "6.5.0",
+  "version": "7.0.0",
   "description": "Primitives are token-backed low-level building blocks.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"