@atlaskit/primitives 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @atlaskit/primitives
 
+## 0.9.1
+
+### Patch Changes
+
+- [`5a9e73494eb`](https://bitbucket.org/atlassian/atlassian-frontend/commits/5a9e73494eb) - Updates to internal documentation.
+
 ## 0.9.0
 
 ### Minor Changes

package/constellation/inline/code.mdx

@@ -4,7 +4,7 @@ description: Inline is a primitive component based on flexbox that manages the h
 order: 1
 ---
 
-import InlineProps from '!!extract-react-types-loader!../../src/components/internal/extract-react-types/inline-props'
+import InlineProps from '!!extract-react-types-loader!../../extract-react-types/inline-props'
 
 ## Props
 

package/constellation/stack/code.mdx

@@ -4,7 +4,7 @@ description: Stack is a primitive component based on flexbox that manages the ve
 order: 1
 ---
 
-import StackProps from '!!extract-react-types-loader!../../src/components/internal/extract-react-types/stack-props'
+import StackProps from '!!extract-react-types-loader!../../extract-react-types/stack-props'
 
 ## Props
 

package/constellation/xcss/examples.mdx

@@ -0,0 +1,21 @@
+---
+title: xCSS
+description: xCSS is a safer, tokens-first approach to CSS-in-JS.
+order: 1
+---
+
+import xcssBasic from '../../examples/constellation/xcss/basic';
+import xcssInteractive from '../../examples/constellation/xcss/interactivity';
+
+## Basic
+
+`xcss` can be used to pull together different types of interactions and UI in a safer more composable way.
+
+<Example Component={xcssBasic} packageName="@atlaskit/primitives/xcss" />
+
+## Interactivity
+
+To enable interactivity you can lean on familiar selectors like `:hover` and `:focus-visible`.
+
+<Example Component={xcssInteractive} packageName="@atlaskit/primitives/xcss" />
+

package/constellation/xcss/migration.mdx

@@ -0,0 +1,142 @@
+---
+title: Migrating your app to xCSS
+description: xCSS is a safer, tokens-first approach to CSS-in-JS.
+order: 2
+---
+
+## Summary of changes
+
+### Changes for developers
+
+There are two key changes to be mindful of when migrating to use `xcss`.
+The first is needing to update callsites to remove any nested styles and
+tokenised values.
+
+```diff
+- import { css } from '@emotion/react';
++ import { xcss } from '@atlaskit/primitives';
+
+- const someStyles = css({
++ const someStyles = xcss({
+  // token based properties will no longer need to be wrapped
+- padding: token('space.100'),
++ padding: 'space.100'
+  // no change is required for non-tokenised values
+  transform: 'scale(2)'
+});
+```
+
+The second is that for the `xcss` function to be applied correctly it must be applied on a
+component with an `xcss` JSXAttribute. By default this won't work with the `css` or `className`
+JSXAttributes - so be aware if you're not seeing your styles appear.
+
+```diff
+- <div css={someStyles} />
++ <Box xcss={someStyles} />
+```
+
+
+#### Changing the way you express styles
+
+Why are nested selectors a problem? A key philosophy of `xcss` is encouraging more deterministic style application. This restriction is designed to eliminate side-effects and
+encourage component encapsulation. Consider the below example:
+
+```tsx
+const myComponentStyles = css({
+  '> *': {
+    color: 'color.text.danger',
+  }
+});
+
+const MyComponent = () => (
+  <div css={myComponentStyles}>
+    <p>Text here</p>
+  </div>
+);
+```
+
+Here the component is applying styles that are implicity meant for the text wrapped in the `p` below.
+In this simple example, it may seem okay, desirable even, but cases like these often occur across module or component boundaries.
+
+This makes the visibility of these dependencies harder to capture or reason about.
+Styles that are inherited or indirectly apply make a UI brittle to change and hard to evolve.
+Instead, if the same styles are applied directly on the affected element we can minimize and in some cases completely eliminate this problem.
+
+```diff
+const myTextStyles = xcss({
+-  '> *': {
+   color: 'color.text.danger',
+-  }
+});
+
+const MyComponent = () => (
+-  <div xcss={myComponentStyles}>
++  <Box
++    <Text xcss={myTextStyles}>Text here</Text>
+   </Box>
+);
+```
+
+There are likely to be cases where nesting is the only option. While not desirable, this is fine as long as it's considered
+a last resort.
+
+### FAQ
+
+Overall migration to `xcss` is fairly simple for the majority of cases. Here are some common strategies for migrations.
+
+#### Non-tokenised values
+
+If you're yet to migrate to tokens, you have two options. You can migrate to tokens first and then on a second pass
+migrate to `xcss` or you can make the jump directly.
+
+```tsx
+const someStyles = css({
+  color: 'red',
+});
+
+// ->>> Optional middle step
+const someStyles = css({
+  color: token('color.text.danger'),
+});
+
+// ->>> The final state
+const someStyles = xcss({
+  color: 'color.text.danger',
+});
+```
+
+#### Moving from the `styled` API
+
+If you're currently using the `styled` API there are a few steps required to migration.
+The safest approach is to a step change to use object styles, migrate to tokens (optionally)
+and then migrate to `xcss`.
+
+```tsx
+const MyComponent = styled.div`
+  color: red;
+`;
+
+// ->>> move to object styles
+const MyComponent = styled.div({
+  color: 'red';
+});
+
+// ->>> move to tokens
+const MyComponent = styled.div({
+  color: token('color.text.danger'),
+});
+
+// ->>> move to Box
+const myComponentStyles = xcss({
+  color: 'color.text.danger',
+});
+
+const MyComponent = () => <Box xcss={myComponentStyles} />
+```
+
+
+## Get help
+
+* Atlassians can reach out in [Slack](slack://channel?team=TFCUTJ0G5&id=CFJ9DU39U) for help with `xcss` migration.
+* Other developers who need help with tokens or the `xcss` utility can post in the [public developer community](https://community.developer.atlassian.com/).
+* For general help with the Atlassian Design System, [contact us](/resources/contact-us).

package/constellation/xcss/usage.mdx

@@ -0,0 +1,115 @@
+---
+title: xCSS
+description: xCSS is a safer, tokens-first approach to CSS-in-JS.
+order: 0
+---
+
+![xcss Logo](logo.png "xcss Logo")
+
+`xcss` is an Atlassian Design System styling API designed to natively integrate with
+Atlassian's [design tokens](/tokens) and [primitives](/components/primitives) in a safer, more resilient and evolvable way.
+
+The `xcss` utility behaves similarly to the `css` utility in libraries
+like `styled-components`, `@compiled` or `@emotion` - so if you've used those libraries before
+it will feel very familiar, with a few additional features and some constraints.
+
+Features that will feel familiar:
+
+* `xcss` will generate a `className` to be applied on your components
+* `xcss` will provide key-value pairs of CSS properties in an object format
+* `xcss` supports style precedence and conditional styles
+
+But it also has a few key differences.
+
+* `xcss` has type-safety that uses token names for all CSS properties that are represented by design tokens.
+* `xcss` restricts nested selectors completely from usage.
+
+## Usage
+
+To get started, import the function from `@atlaskit/primitives` and create a style:
+
+```tsx
+import { xcss } from '@atlaskit/primitives';
+
+// Creates a basic style
+const someStyles = xcss({
+  display: 'block',
+});
+```
+
+Apply this style to a component through the `xcss` prop:
+
+```tsx
+import { Box, xcss } from '@atlaskit/primitives';
+
+// Creates a basic style
+const someStyles = xcss({
+  display: 'block',
+});
+
+const MyBox = () => {
+  return <Box xcss={someStyles} />
+}
+```
+
+The prop and the `xcss` function are direct complements and are meant
+to be used together. Note: styles generated from `xcss` cannot be applied directly
+to the `className` property or `css` as they are with other CSS-in-JS libraries.
+
+### Type safety
+
+`xcss` uses strongly-typed values generated from design token
+definitions to make it simpler to apply the right token for the right CSS property.
+This is intended to be more ergonomic and intuitive but also prevent the misapplication of tokens
+to the wrong properties.
+
+Any [valid token name](/components/tokens/all-tokens) is available to be applied against its
+matching CSS property. For example, the token name `space.200`
+is a valid value below for `padding` but will not appear
+as a color, or a font.
+
+```tsx
+import { xcss } from '@atlaskit/primitives';
+
+const someStyles = xcss({
+  padding: 'space.200', // <--- works
+  color: 'space.200',   // <--- invalid and will error
+  borderRadius: 'radius.100' // <--- also valid
+});
+```
+
+### Restricted nesting
+
+`xcss` is meant to be flexible enough for you to implement any design but it does
+restrict the application of styles in one key way. Selectors cannot be
+nested or target elements beyond the element on which styles are applied.
+This restriction is intended to encourage better component encapsulation, reduce side-effects and make
+your codebase more resilient to change.
+
+```tsx
+import { xcss } from '@atlaskit/primitives';
+
+const someStyles = xcss({
+  ':hover': {
+    transform: 'scale(1)' // this is okay
+  },
+  // This is not okay as this selector affects any nested div in
+  // the component tree.
+  'div:hover': {
+    transform: 'scale(1)'
+  },
+  // Neither is this
+  '> * > div:hover': {
+    transform: 'scale(1)'
+  },
+});
+```
+
+These unsafe selectors will throw a type error if applied.
+For richer examples of how to use `xcss` please see our [documentation here](/components/primitives/xcss/examples).
+
+## Get help
+
+* Atlassians can reach out in [Slack](slack://channel?team=TFCUTJ0G5&id=CFJ9DU39U) for help with `xcss` migration.
+* Other developers who need help with tokens or the `xcss` utility can post in the [public developer community](https://community.developer.atlassian.com/).
+* For general help with the Atlassian Design System, [contact us](/resources/contact-us).

package/dist/cjs/components/box.js

@@ -9,7 +9,7 @@ var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends")
 var _objectWithoutProperties2 = _interopRequireDefault(require("@babel/runtime/helpers/objectWithoutProperties"));
 var _react = require("react");
 var _react2 = require("@emotion/react");
-var _xcss = require("../internal/xcss");
+var _xcss = require("../xcss/xcss");
 var _baseBox = require("./internal/base-box");
 var _excluded = ["as", "children", "backgroundColor", "padding", "paddingBlock", "paddingBlockStart", "paddingBlockEnd", "paddingInline", "paddingInlineStart", "paddingInlineEnd", "style", "testId", "xcss"],
   _excluded2 = ["className"];

package/dist/cjs/components/inline.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _react = require("react");
 var _react2 = require("@emotion/react");
-var _styleMaps = require("../internal/style-maps.partial");
+var _styleMaps = require("../xcss/style-maps.partial");
 /* eslint-disable @repo/internal/styles/no-exported-styles */
 /** @jsx jsx */
 

package/dist/cjs/components/internal/base-box.js

@@ -9,7 +9,7 @@ var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends")
 var _objectWithoutProperties2 = _interopRequireDefault(require("@babel/runtime/helpers/objectWithoutProperties"));
 var _react = require("react");
 var _react2 = require("@emotion/react");
-var _styleMaps = require("../../internal/style-maps.partial");
+var _styleMaps = require("../../xcss/style-maps.partial");
 var _excluded = ["as", "className", "children", "backgroundColor", "padding", "paddingBlock", "paddingBlockStart", "paddingBlockEnd", "paddingInline", "paddingInlineStart", "paddingInlineEnd", "style", "testId"];
 /* eslint-disable @repo/internal/styles/no-exported-styles */
 /** @jsx jsx */

package/dist/cjs/components/stack.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _react = require("react");
 var _react2 = require("@emotion/react");
-var _styleMaps = require("../internal/style-maps.partial");
+var _styleMaps = require("../xcss/style-maps.partial");
 /* eslint-disable @repo/internal/styles/no-exported-styles */
 /** @jsx jsx */
 

package/dist/cjs/index.js

@@ -30,5 +30,5 @@ Object.defineProperty(exports, "xcss", {
 });
 var _box = _interopRequireDefault(require("./components/box"));
 var _inline = _interopRequireDefault(require("./components/inline"));
-var _xcss = require("./internal/xcss");
+var _xcss = require("./xcss/xcss");
 var _stack = _interopRequireDefault(require("./components/stack"));

package/dist/cjs/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/primitives",
-	"version": "0.9.0",
+	"version": "0.9.1",
 	"sideEffects": false
 }

package/dist/cjs/{internal → xcss}/xcss.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.parseXcss = void 0;
 exports.xcss = xcss;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
 var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
 var _react = require("@emotion/react");
@@ -49,6 +50,9 @@ var tokensMap = {
   minHeight: _styleMaps.dimensionMap,
   minInlineSize: _styleMaps.dimensionMap,
   minWidth: _styleMaps.dimensionMap,
+  outlineOffset: _styleMaps.paddingMap,
+  outlineWidth: _styleMaps.borderWidthMap,
+  outlineColor: _styleMaps.borderColorMap,
   overflow: _styleMaps.overflowMap,
   overflowBlock: _styleMaps.overflowBlockMap,
   overflowInline: _styleMaps.overflowInlineMap,
@@ -70,7 +74,7 @@ var tokensMap = {
   width: _styleMaps.dimensionMap,
   zIndex: _styleMaps.layerMap
 };
-var uniqueSymbol = Symbol('Internal symbol to verify xcss function is called safely');
+var uniqueSymbol = Symbol('UNSAFE_INTERNAL_styles');
 var isSafeEnvToThrow = function isSafeEnvToThrow() {
   return (typeof process === "undefined" ? "undefined" : (0, _typeof2.default)(process)) === 'object' && (0, _typeof2.default)(process.env) === 'object' && process.env.NODE_ENV !== 'production';
 };
@@ -124,10 +128,7 @@ var transformStyles = function transformStyles(styleObj) {
 };
 var baseXcss = function baseXcss(style) {
   var transformedStyles = transformStyles(style);
-  return {
-    symbol: uniqueSymbol,
-    styles: (0, _react.css)(transformedStyles)
-  };
+  return (0, _defineProperty2.default)({}, uniqueSymbol, (0, _react.css)(transformedStyles));
 };
 
 /**
@@ -141,9 +142,8 @@ var parseXcss = function parseXcss(args) {
       return x && parseXcss(x);
     }).filter(Boolean);
   }
-  var symbol = args.symbol,
-    styles = args.styles;
-  if ((typeof process === "undefined" ? "undefined" : (0, _typeof2.default)(process)) && process.env.NODE_ENV === 'development' && symbol !== uniqueSymbol) {
+  var styles = args[uniqueSymbol];
+  if ((typeof process === "undefined" ? "undefined" : (0, _typeof2.default)(process)) && process.env.NODE_ENV === 'development' && typeof styles === 'undefined') {
     throw new Error('Styles generated from unsafe source, use the `xcss` export from `@atlaskit/primitives`.');
   }
   return styles;
@@ -156,6 +156,18 @@ var boxWrapper = function boxWrapper(style) {
 var inlineWrapper = function inlineWrapper(style) {
   return xcss(style);
 };
+/**
+ * ### xcss
+ *
+ * `xcss` is a safer, tokens-first approach to CSS-in-JS. It allows token-backed values for
+ * CSS application.
+ *
+ * ```tsx
+ * const styles = xcss({
+ *   padding: 'space.100'
+ * })
+ * ```
+ */
 function xcss(style) {
   return baseXcss(style);
 }

package/dist/es2019/components/box.js

@@ -2,7 +2,7 @@ import _extends from "@babel/runtime/helpers/extends";
 /** @jsx jsx */
 import { forwardRef } from 'react';
 import { jsx } from '@emotion/react';
-import { parseXcss } from '../internal/xcss';
+import { parseXcss } from '../xcss/xcss';
 import { BaseBox } from './internal/base-box';
 /**
  * __Box__

package/dist/es2019/components/inline.js

@@ -2,7 +2,7 @@
 /** @jsx jsx */
 import { Children, forwardRef, Fragment, memo } from 'react';
 import { css, jsx } from '@emotion/react';
-import { spaceStylesMap } from '../internal/style-maps.partial';
+import { spaceStylesMap } from '../xcss/style-maps.partial';
 const alignItemsMap = {
   center: css({
     alignItems: 'center'

package/dist/es2019/components/internal/base-box.js

@@ -3,7 +3,7 @@ import _extends from "@babel/runtime/helpers/extends";
 /** @jsx jsx */
 import { forwardRef } from 'react';
 import { css, jsx } from '@emotion/react';
-import { backgroundColorStylesMap, paddingStylesMap } from '../../internal/style-maps.partial';
+import { backgroundColorStylesMap, paddingStylesMap } from '../../xcss/style-maps.partial';
 
 // Without this type annotation on Box we don't get autocomplete for props due to forwardRef types
 

package/dist/es2019/components/stack.js

@@ -2,7 +2,7 @@
 /** @jsx jsx */
 import { forwardRef, memo } from 'react';
 import { css, jsx } from '@emotion/react';
-import { spaceStylesMap } from '../internal/style-maps.partial';
+import { spaceStylesMap } from '../xcss/style-maps.partial';
 const justifyContentMap = {
   start: css({
     justifyContent: 'start'

package/dist/es2019/index.js

@@ -1,4 +1,4 @@
 export { default as Box } from './components/box';
 export { default as Inline } from './components/inline';
-export { xcss } from './internal/xcss';
+export { xcss } from './xcss/xcss';
 export { default as Stack } from './components/stack';

package/dist/es2019/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/primitives",
-	"version": "0.9.0",
+	"version": "0.9.1",
 	"sideEffects": false
 }

package/dist/es2019/{internal → xcss}/xcss.js

@@ -38,6 +38,9 @@ const tokensMap = {
   minHeight: dimensionMap,
   minInlineSize: dimensionMap,
   minWidth: dimensionMap,
+  outlineOffset: paddingMap,
+  outlineWidth: borderWidthMap,
+  outlineColor: borderColorMap,
   overflow: overflowMap,
   overflowBlock: overflowBlockMap,
   overflowInline: overflowInlineMap,
@@ -59,7 +62,7 @@ const tokensMap = {
   width: dimensionMap,
   zIndex: layerMap
 };
-const uniqueSymbol = Symbol('Internal symbol to verify xcss function is called safely');
+const uniqueSymbol = Symbol('UNSAFE_INTERNAL_styles');
 const isSafeEnvToThrow = () => typeof process === 'object' && typeof process.env === 'object' && process.env.NODE_ENV !== 'production';
 const reNestedSelectors = /(\.|\s|&+|\*\>|#|\[.*\])/;
 const rePseudos = /^::?.*$/;
@@ -109,8 +112,7 @@ const transformStyles = styleObj => {
 const baseXcss = style => {
   const transformedStyles = transformStyles(style);
   return {
-    symbol: uniqueSymbol,
-    styles: cssEmotion(transformedStyles)
+    [uniqueSymbol]: cssEmotion(transformedStyles)
   };
 };
 
@@ -124,10 +126,9 @@ export const parseXcss = args => {
     return args.map(x => x && parseXcss(x)).filter(Boolean);
   }
   const {
-    symbol,
-    styles
+    [uniqueSymbol]: styles
   } = args;
-  if (typeof process && process.env.NODE_ENV === 'development' && symbol !== uniqueSymbol) {
+  if (typeof process && process.env.NODE_ENV === 'development' && typeof styles === 'undefined') {
     throw new Error('Styles generated from unsafe source, use the `xcss` export from `@atlaskit/primitives`.');
   }
   return styles;
@@ -135,6 +136,18 @@ export const parseXcss = args => {
 // unused private functions only so we can extract the return type from a generic function
 const boxWrapper = style => xcss(style);
 const inlineWrapper = style => xcss(style);
+/**
+ * ### xcss
+ *
+ * `xcss` is a safer, tokens-first approach to CSS-in-JS. It allows token-backed values for
+ * CSS application.
+ *
+ * ```tsx
+ * const styles = xcss({
+ *   padding: 'space.100'
+ * })
+ * ```
+ */
 export function xcss(style) {
   return baseXcss(style);
 }

package/dist/esm/components/box.js

@@ -5,7 +5,7 @@ var _excluded = ["as", "children", "backgroundColor", "padding", "paddingBlock",
 /** @jsx jsx */
 import { forwardRef } from 'react';
 import { jsx } from '@emotion/react';
-import { parseXcss } from '../internal/xcss';
+import { parseXcss } from '../xcss/xcss';
 import { BaseBox } from './internal/base-box';
 /**
  * __Box__

package/dist/esm/components/inline.js

@@ -2,7 +2,7 @@
 /** @jsx jsx */
 import { Children, forwardRef, Fragment, memo } from 'react';
 import { css, jsx } from '@emotion/react';
-import { spaceStylesMap } from '../internal/style-maps.partial';
+import { spaceStylesMap } from '../xcss/style-maps.partial';
 var alignItemsMap = {
   center: css({
     alignItems: 'center'

package/dist/esm/components/internal/base-box.js

@@ -5,7 +5,7 @@ var _excluded = ["as", "className", "children", "backgroundColor", "padding", "p
 /** @jsx jsx */
 import { forwardRef } from 'react';
 import { css, jsx } from '@emotion/react';
-import { backgroundColorStylesMap, paddingStylesMap } from '../../internal/style-maps.partial';
+import { backgroundColorStylesMap, paddingStylesMap } from '../../xcss/style-maps.partial';
 
 // Without this type annotation on Box we don't get autocomplete for props due to forwardRef types
 

package/dist/esm/components/stack.js

@@ -2,7 +2,7 @@
 /** @jsx jsx */
 import { forwardRef, memo } from 'react';
 import { css, jsx } from '@emotion/react';
-import { spaceStylesMap } from '../internal/style-maps.partial';
+import { spaceStylesMap } from '../xcss/style-maps.partial';
 var justifyContentMap = {
   start: css({
     justifyContent: 'start'

package/dist/esm/index.js

@@ -1,4 +1,4 @@
 export { default as Box } from './components/box';
 export { default as Inline } from './components/inline';
-export { xcss } from './internal/xcss';
+export { xcss } from './xcss/xcss';
 export { default as Stack } from './components/stack';

package/dist/esm/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/primitives",
-	"version": "0.9.0",
+	"version": "0.9.1",
 	"sideEffects": false
 }