@atlaskit/primitives 0.8.9 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @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
+
+- [`56507598609`](https://bitbucket.org/atlassian/atlassian-frontend/commits/56507598609) - Skip minor dependency bump
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 0.8.9
 
 ### Patch 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.8.9",
+	"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.8.9",
+	"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.8.9",
+	"version": "0.9.1",
 	"sideEffects": false
 }

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

@@ -1,3 +1,4 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
 import _typeof from "@babel/runtime/helpers/typeof";
 /* eslint-disable @atlaskit/design-system/ensure-design-token-usage */
@@ -40,6 +41,9 @@ var tokensMap = {
   minHeight: dimensionMap,
   minInlineSize: dimensionMap,
   minWidth: dimensionMap,
+  outlineOffset: paddingMap,
+  outlineWidth: borderWidthMap,
+  outlineColor: borderColorMap,
   overflow: overflowMap,
   overflowBlock: overflowBlockMap,
   overflowInline: overflowInlineMap,
@@ -61,7 +65,7 @@ var tokensMap = {
   width: dimensionMap,
   zIndex: 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" : _typeof(process)) === 'object' && _typeof(process.env) === 'object' && process.env.NODE_ENV !== 'production';
 };
@@ -115,10 +119,7 @@ var transformStyles = function transformStyles(styleObj) {
 };
 var baseXcss = function baseXcss(style) {
   var transformedStyles = transformStyles(style);
-  return {
-    symbol: uniqueSymbol,
-    styles: cssEmotion(transformedStyles)
-  };
+  return _defineProperty({}, uniqueSymbol, cssEmotion(transformedStyles));
 };
 
 /**
@@ -132,9 +133,8 @@ export var parseXcss = function parseXcss(args) {
       return x && parseXcss(x);
     }).filter(Boolean);
   }
-  var symbol = args.symbol,
-    styles = args.styles;
-  if ((typeof process === "undefined" ? "undefined" : _typeof(process)) && process.env.NODE_ENV === 'development' && symbol !== uniqueSymbol) {
+  var styles = args[uniqueSymbol];
+  if ((typeof process === "undefined" ? "undefined" : _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;
@@ -146,6 +146,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'
+ * })
+ * ```
+ */
 export function xcss(style) {
   return baseXcss(style);
 }

package/dist/types/components/inline.d.ts

@@ -1,6 +1,6 @@
 /** @jsx jsx */
 import { ElementType, ReactNode } from 'react';
-import { type Gap, type RowGap } from '../internal/style-maps.partial';
+import { type Gap, type RowGap } from '../xcss/style-maps.partial';
 export interface InlineProps<T extends ElementType = 'div'> {
     /**
      * The DOM element to render as the Inline. Defaults to `div`.

package/dist/types/components/internal/base-box.d.ts

@@ -1,6 +1,6 @@
 /** @jsx jsx */
 import { ComponentPropsWithoutRef, ComponentPropsWithRef, ElementType, FC, ReactElement, ReactNode } from 'react';
-import { BackgroundColor, Padding, PaddingBlock, PaddingBlockEnd, PaddingBlockStart, PaddingInline, PaddingInlineEnd, PaddingInlineStart } from '../../internal/style-maps.partial';
+import { BackgroundColor, Padding, PaddingBlock, PaddingBlockEnd, PaddingBlockStart, PaddingInline, PaddingInlineEnd, PaddingInlineStart } from '../../xcss/style-maps.partial';
 import type { BasePrimitiveProps } from '../types';
 export declare type BaseBoxProps<T extends ElementType = 'div'> = Omit<ComponentPropsWithoutRef<T>, 'as' | 'className'> & BasePrimitiveProps & BaseBoxPropsFoundation<T>;
 declare type BaseBoxPropsFoundation<T extends ElementType> = {

package/dist/types/components/stack.d.ts

@@ -1,6 +1,6 @@
 /** @jsx jsx */
 import { ElementType, ReactNode } from 'react';
-import { type Gap } from '../internal/style-maps.partial';
+import { type Gap } from '../xcss/style-maps.partial';
 export interface StackProps<T extends ElementType = 'div'> {
     /**
      * The DOM element to render as the Stack. Defaults to `div`.

package/dist/types/components/types.d.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from 'react';
-import { type BoxXCSS } from '../internal/xcss';
+import { type BoxXCSS } from '../xcss/xcss';
 export declare type BasePrimitiveProps = {
     /**
      * A unique string that appears as data attribute `data-testid` in the rendered code, serving as a hook for automated tests.

package/dist/types/index.d.ts

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

package/dist/types/{internal → xcss}/style-maps.partial.d.ts

@@ -458,6 +458,9 @@ export declare type TokenisedProps = {
     minHeight?: MinHeight;
     minInlineSize?: MinInlineSize;
     minWidth?: MinWidth;
+    outlineColor?: BorderColor;
+    outlineOffset?: Padding;
+    outlineWidth?: BorderWidth;
     overflow?: Overflow;
     overflowBlock?: OverflowBlock;
     overflowInline?: OverflowInline;
@@ -476,7 +479,7 @@ export declare type TokenisedProps = {
     zIndex?: Layer;
 };
 declare const spacingProperties: readonly ["padding", "paddingBlock", "paddingBlockStart", "paddingBlockEnd", "paddingInline", "paddingInlineStart", "paddingInlineEnd", "gap", "rowGap", "columnGap"];
-declare type SpacingProperty = typeof spacingProperties[number];
+declare type SpacingProperty = (typeof spacingProperties)[number];
 declare type SpacingToken = keyof typeof paddingMap;
 declare type BackgroundColorToken = keyof typeof backgroundColorMap;
 declare type SpacingStyleMap = Record<SpacingProperty, Record<SpacingToken, SerializedStyles>>;

package/dist/types/{internal → xcss}/xcss.d.ts

@@ -17,34 +17,41 @@ declare type CSSPseudos = {
 declare type SafeCSSObject = CSSPseudos & TokenisedProps & Omit<CSSPropertiesWithMultiValues, keyof TokenisedProps>;
 declare type ScopedSafeCSSObject<T extends keyof SafeCSSObject> = Pick<SafeCSSObject, T>;
 declare const boxWrapper: (style: any) => {
-    readonly symbol: typeof uniqueSymbol;
-    readonly styles: BoxStyles;
+    readonly [uniqueSymbol]: BoxStyles;
 };
 declare const inlineWrapper: (style: any) => {
-    readonly symbol: typeof uniqueSymbol;
-    readonly styles: InlineStyles;
+    readonly [uniqueSymbol]: InlineStyles;
 };
 declare type XCSS = ReturnType<typeof boxWrapper> | ReturnType<typeof inlineWrapper>;
 declare type AllowedBoxStyles = keyof SafeCSSObject;
 declare type AllowedInlineStyles = 'backgroundColor' | 'padding';
+/**
+ * ### 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 declare function xcss<Primitive extends typeof Box | typeof Inline = typeof Box>(style: Primitive extends typeof Box ? ScopedSafeCSSObject<AllowedBoxStyles> | ScopedSafeCSSObject<AllowedBoxStyles>[] : Primitive extends typeof Inline ? ScopedSafeCSSObject<AllowedInlineStyles> | ScopedSafeCSSObject<AllowedInlineStyles>[] : never): {
-    readonly symbol: typeof uniqueSymbol;
-    readonly styles: Primitive extends (<T extends import("react").ElementType<any> = "div">(props: import("../index").BoxProps<T>) => import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>> | null) & import("react").FC<import("../index").BoxProps<"div">> ? BoxStyles : Primitive extends import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<Pick<import("../index").InlineProps<import("react").ElementType<any>>, "as" | "children" | "testId" | "alignInline" | "alignBlock" | "shouldWrap" | "spread" | "grow" | "space" | "rowSpace" | "separator"> & import("react").RefAttributes<any>>> ? InlineStyles : never;
+    readonly [uniqueSymbol]: Primitive extends (<T extends import("react").ElementType<any> = "div">(props: import("../index").BoxProps<T>) => import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>> | null) & import("react").FC<import("../index").BoxProps<"div">> ? BoxStyles : Primitive extends import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<Pick<import("../index").InlineProps<import("react").ElementType<any>>, "as" | "children" | "testId" | "alignInline" | "alignBlock" | "shouldWrap" | "spread" | "grow" | "space" | "rowSpace" | "separator"> & import("react").RefAttributes<any>>> ? InlineStyles : never;
 };
 declare const boxTag: unique symbol;
 export declare type BoxStyles = SerializedStyles & {
     [boxTag]: true;
 };
 export declare type BoxXCSS = {
-    readonly symbol: typeof uniqueSymbol;
-    readonly styles: BoxStyles;
+    readonly [uniqueSymbol]: BoxStyles;
 };
 declare const inlineTag: unique symbol;
 export declare type InlineStyles = SerializedStyles & {
     [inlineTag]: true;
 };
 export declare type InlineXCSS = {
-    readonly symbol: typeof uniqueSymbol;
-    readonly styles: InlineStyles;
+    readonly [uniqueSymbol]: InlineStyles;
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaskit/primitives",
-  "version": "0.8.9",
+  "version": "0.9.1",
   "description": "Primitives are token-backed low-level building blocks.",
   "author": "Atlassian Pty Ltd",
   "license": "Apache-2.0",
@@ -55,6 +55,15 @@
           "status": {
             "type": "alpha"
           }
+        },
+        {
+          "title": "xCSS",
+          "folder": "xcss",
+          "slug": "primitives/xcss",
+          "id": "@atlaskit/primitives/xcss",
+          "status": {
+            "type": "alpha"
+          }
         }
       ]
     }
@@ -76,8 +85,8 @@
     "./responsive": "./src/helpers/responsive/index.tsx"
   },
   "dependencies": {
-    "@atlaskit/ds-lib": "^2.1.2",
-    "@atlaskit/tokens": "^1.2.0",
+    "@atlaskit/ds-lib": "^2.2.0",
+    "@atlaskit/tokens": "^1.3.0",
     "@babel/runtime": "^7.0.0",
     "@emotion/react": "^11.7.1",
     "@emotion/serialize": "^1.1.0"
@@ -98,19 +107,19 @@
     "@atlaskit/icon-object": "*",
     "@atlaskit/logo": "*",
     "@atlaskit/lozenge": "*",
-    "@atlaskit/radio": "^5.4.9",
-    "@atlaskit/range": "^7.0.4",
+    "@atlaskit/radio": "^5.5.0",
+    "@atlaskit/range": "^7.1.0",
     "@atlaskit/ssr": "*",
     "@atlaskit/tag": "*",
     "@atlaskit/theme": "*",
     "@atlaskit/visual-regression": "*",
     "@atlaskit/webdriver-runner": "*",
     "@atlassian/atlassian-frontend-prettier-config-1.0.1": "npm:@atlassian/atlassian-frontend-prettier-config@1.0.1",
-    "@atlassian/codegen": "^0.0.1",
-    "@atlassian/gemini-visual-regression": "^0.0.5",
+    "@atlassian/codegen": "^0.1.0",
+    "@atlassian/gemini-visual-regression": "^0.0.6",
     "@testing-library/react": "^12.1.5",
     "csstype": "^3.1.0",
-    "prettier": "^2.7.0",
+    "prettier": "^2.8.0",
     "react-dom": "^16.8.0",
     "ts-node": "^10.9.1",
     "typescript": "4.5.5",
@@ -142,4 +151,4 @@
     }
   },
   "prettier": "@atlassian/atlassian-frontend-prettier-config-1.0.0"
-}
+}

package/report.api.md

@@ -311,8 +311,7 @@ const boxTag: unique symbol;
 
 // @public (undocumented)
 type BoxXCSS = {
-  readonly symbol: typeof uniqueSymbol;
-  readonly styles: BoxStyles;
+  readonly [uniqueSymbol]: BoxStyles;
 };
 
 // @public (undocumented)
@@ -949,6 +948,9 @@ type TokenisedProps = {
   minHeight?: MinHeight;
   minInlineSize?: MinInlineSize;
   minWidth?: MinWidth;
+  outlineColor?: BorderColor;
+  outlineOffset?: Padding;
+  outlineWidth?: BorderWidth;
   overflow?: Overflow;
   overflowBlock?: OverflowBlock;
   overflowInline?: OverflowInline;
@@ -976,7 +978,7 @@ const uniqueSymbol: unique symbol;
 // @public (undocumented)
 type Width = keyof typeof dimensionMap;
 
-// @public (undocumented)
+// @public
 export function xcss<Primitive extends typeof Box | typeof Inline = typeof Box>(
   style: Primitive extends typeof Box
     ?
@@ -988,8 +990,9 @@ export function xcss<Primitive extends typeof Box | typeof Inline = typeof Box>(
         | ScopedSafeCSSObject<AllowedInlineStyles>[]
     : never,
 ): {
-  readonly symbol: typeof uniqueSymbol;
-  readonly styles: Primitive extends (<T extends ElementType<any> = 'div'>(
+  readonly [uniqueSymbol]: Primitive extends (<
+    T extends ElementType<any> = 'div',
+  >(
     props: BoxProps<T>,
   ) => ReactElement<any, JSXElementConstructor<any> | string> | null) &
     FC<BoxProps<'div'>>

package/tmp/api-report-tmp.d.ts

@@ -273,8 +273,7 @@ const boxTag: unique symbol;
 
 // @public (undocumented)
 type BoxXCSS = {
-    readonly symbol: typeof uniqueSymbol;
-    readonly styles: BoxStyles;
+    readonly [uniqueSymbol]: BoxStyles;
 };
 
 // @public (undocumented)
@@ -635,6 +634,9 @@ type TokenisedProps = {
     minHeight?: MinHeight;
     minInlineSize?: MinInlineSize;
     minWidth?: MinWidth;
+    outlineColor?: BorderColor;
+    outlineOffset?: Padding;
+    outlineWidth?: BorderWidth;
     overflow?: Overflow;
     overflowBlock?: OverflowBlock;
     overflowInline?: OverflowInline;
@@ -662,10 +664,9 @@ const uniqueSymbol: unique symbol;
 // @public (undocumented)
 type Width = keyof typeof dimensionMap;
 
-// @public (undocumented)
+// @public
 export function xcss<Primitive extends typeof Box | typeof Inline = typeof Box>(style: Primitive extends typeof Box ? ScopedSafeCSSObject<AllowedBoxStyles> | ScopedSafeCSSObject<AllowedBoxStyles>[] : Primitive extends typeof Inline ? ScopedSafeCSSObject<AllowedInlineStyles> | ScopedSafeCSSObject<AllowedInlineStyles>[] : never): {
-    readonly symbol: typeof uniqueSymbol;
-    readonly styles: Primitive extends (<T extends ElementType<any> = "div">(props: BoxProps<T>) => ReactElement<any, JSXElementConstructor<any>| string> | null) & FC<BoxProps<"div">> ? BoxStyles : Primitive extends MemoExoticComponent<ForwardRefExoticComponent<Pick<InlineProps<ElementType<any>>, "alignBlock" | "alignInline" | "as" | "children" | "grow" | "rowSpace" | "separator" | "shouldWrap" | "space" | "spread" | "testId"> & RefAttributes<any>>> ? InlineStyles : never;
+    readonly [uniqueSymbol]: Primitive extends (<T extends ElementType<any> = "div">(props: BoxProps<T>) => ReactElement<any, JSXElementConstructor<any>| string> | null) & FC<BoxProps<"div">> ? BoxStyles : Primitive extends MemoExoticComponent<ForwardRefExoticComponent<Pick<InlineProps<ElementType<any>>, "alignBlock" | "alignInline" | "as" | "children" | "grow" | "rowSpace" | "separator" | "shouldWrap" | "space" | "spread" | "testId"> & RefAttributes<any>>> ? InlineStyles : never;
 };
 
 // (No @packageDocumentation comment for this package)

package/dist/cjs/components/internal/extract-react-types/inline-props.js

@@ -1,7 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = Inline;
-function Inline(_) {}

package/dist/cjs/components/internal/extract-react-types/stack-props.js

@@ -1,7 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = Inline;
-function Inline(_) {}

package/dist/es2019/components/internal/extract-react-types/inline-props.js

@@ -1 +0,0 @@
-export default function Inline(_) {}

package/dist/es2019/components/internal/extract-react-types/stack-props.js

@@ -1 +0,0 @@
-export default function Inline(_) {}

package/dist/esm/components/internal/extract-react-types/inline-props.js

@@ -1 +0,0 @@
-export default function Inline(_) {}

package/dist/esm/components/internal/extract-react-types/stack-props.js

@@ -1 +0,0 @@
-export default function Inline(_) {}

package/dist/types/components/internal/extract-react-types/inline-props.d.ts

@@ -1,2 +0,0 @@
-import type { InlineProps } from '../../inline';
-export default function Inline(_: InlineProps): void;

package/dist/types/components/internal/extract-react-types/stack-props.d.ts

@@ -1,2 +0,0 @@
-import type { StackProps } from '../../stack';
-export default function Inline(_: StackProps): void;