@atlaskit/primitives 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @atlaskit/primitives
 
+## 0.9.2
+
+### Patch Changes
+
+- [`41fae2c6f68`](https://bitbucket.org/atlassian/atlassian-frontend/commits/41fae2c6f68) - Upgrade Typescript from `4.5.5` to `4.9.5`
+
+## 0.9.1
+
+### Patch Changes
+
+- [`5a9e73494eb`](https://bitbucket.org/atlassian/atlassian-frontend/commits/5a9e73494eb) - Updates to internal documentation.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -4,6 +4,10 @@ Primitives are token-backed low-level building blocks.
 
 ## Usage
 
-`import Primitives from '@atlaskit/primitives';`
+Detailed docs and example usage can be found at:
 
-Detailed docs and example usage can be found [here](https://atlaskit.atlassian.com/packages/design-system/primitives).
+- [Overview](https://staging.atlassian.design/components/primitives/overview)
+- [Box](https://staging.atlassian.design/components/primitives/box)
+- [Inline](https://staging.atlassian.design/components/primitives/inline)
+- [Stack](https://staging.atlassian.design/components/primitives/stack)
+- [xCSS](https://staging.atlassian.design/components/primitives/xcss)

package/box/package.json

@@ -6,9 +6,9 @@
   "sideEffects": false,
   "types": "../dist/types/components/box.d.ts",
   "typesVersions": {
-    ">=4.0 <4.5": {
+    ">=4.5 <4.9": {
       "*": [
-        "../dist/types-ts4.0/components/box.d.ts"
+        "../dist/types-ts4.5/components/box.d.ts"
       ]
     }
   }

package/constellation/box/code.mdx

@@ -1,7 +1,11 @@
 ---
 title: Box
-description: A box is...
+description: Box is a primitive component that leverages the foundations of the Atlassian Design System.
 order: 1
 ---
 
-*Coming soon*
+import BoxProps from '!!extract-react-types-loader!../../extract-react-types/box-props'
+
+## Props
+
+<PropsTable heading="" props={BoxProps} />

package/constellation/box/usage.mdx

@@ -0,0 +1,30 @@
+---
+title: Box
+description: A box is a primitive component that acts as a generic container, and provides managed access to design tokens.
+order: 2
+---
+
+Use box to compose layouts with the valid spacing and background colors. A `Box` is a generic container with convenient and managed access to design tokens, and built-in guidance for the best practices of the Atlassian Design System.
+
+A `Box` is primarily a containment element, with visual props that affect the whitespace available to child elements. 
+
+
+## Use `Box`
+Display behavior is set by using the available props or using `xcss`. Makers can make design decisions for `Box` by setting:
+
+- `padding`
+- `paddingInline`
+- `paddingInlineStart`
+- `paddingInlineEnd`
+- `paddingBlock`
+- `paddingBlockStart`
+- `paddingBlockEnd`
+- `backgroundColor`
+
+To identify usages of `Box` in a given design, look for where a UI element (could be as small as the parent of a button or as a big as the wrapper of an entire section) will receive some visual styles applied to a container.
+
+`Box`, being generic in nature, can be "over-used", so it’s important to consider situations where more specific and expressive primitives could be used, for example: `Inline` and `Stack` to manage horizontal and vertical layouts, respectively.
+
+Related
+- [Learn more about the Inline primitive](/components/primitives/inline/usage)
+- [Learn more about the Stack primitive](/components/primitives/stack/usage)

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/inline/usage.mdx

@@ -0,0 +1,36 @@
+---
+title: Inline
+description: An Inline is a primitive component that is responsible for the horizontal layout of its child elements.
+order: 2
+---
+
+Primitive components are designed to act as building blocks for composing a user experience. An Inline primitive should be used when you want to layout UI elements horizontally, and make use of the built-in design guidance from the Atlassian Design System. 
+
+Inline primitives work as you might expect, aligning content horizontally across a page or layout, as a container that decides the horizontal layout of its children. Inline components also decide the specifics of how the children are displayed, for example, where they are aligned or how much space is between child elements. Inline should be used purely for visual alignment, and should have no opinions about the functionality of its children.  
+
+In its simplest form, `Inline` operates like a flexbox row, however adds the built in design token support and guidance.
+
+```jsx
+<Inline space="space.100" alignInline="center" alignBlock="start">
+  ...
+</Inline>
+```
+It also has a flex-direction: row; but that’s the default, so not explicitly applied.
+
+## Use `Inline`
+The purpose of an Inline is primarily as a container element controlling how child components are displayed and positioned horizontally. Inline should be used any time you wish to layout elements or components horizontally. 
+
+The various Inline props can then be used to customize the spacing and styling on any child elements. These include:
+
+- `alignBlock`
+- `alignInline`
+- `shouldWrap`
+- `spread`
+- `grow`
+- `space`
+- `rowSpace`
+- `separator`
+
+## Related
+- [Learn more about the Box primitive](/components/primitives/box/usage)
+- [Learn more about the Stack primitive](/components/primitives/stack/usage)

package/constellation/overview/index.mdx

@@ -0,0 +1,66 @@
+---
+title: Primitives
+description: Primitives are composable components that solve common layout problems.
+
+order: 1
+---
+
+import SectionMessage from '@atlaskit/section-message';
+import Image from '@atlaskit/image';
+
+import boxUsageExample from './images/box-usage-example.png';
+import inlineUsageExample from './images/inline-usage-example.png';
+import stackUsageExample from './images/stack-usage-example.png';
+
+<SectionMessage title="This is a preview of our new primitive components." appearance="warning">
+Expect frequent changes as we iterate over the coming months. For early access and release updates for Atlassian employees, see details.
+</SectionMessage>
+
+Primitive components are a new type of component for layouts and placement of elements. They act as building blocks to compose different parts of the user experience, from the smallest design decisions (for example, the spacing around an icon) to larger layout decisions (for example, how a page is structured). 
+
+Primitives are designed to work hand in hand with design tokens, to provide opinionated solutions for common low-level design decisions that engineers often have to make. They are designed to reduce cognitive overhead for engineers by providing guardrails around what is recommended within our design system. 
+
+A primitive component is a pre-built solution in that they will only accept values that are valid in the Atlassian Design System, and help to implement common layout patterns. This reduces the need to look up documentation and write custom CSS. 
+
+## Available Primitives
+
+Each primitive is designed to have a single responsibility, and it should be immediately clear where each primitive should be used. However, they are also flexible enough that they should be able to be used to compose complex designs not otherwise covered in the Design Systems. 
+
+Currently, three primitive components are available for use in Closed Beta they are Box, Inline and Stack. These were chosen because a large amount of layout problems can be reduced to laying out content:
+- in a container (see [box](/components/primitives/box))
+- horizontally (see [inline](/components/primitives/inline))
+- vertically (see [stack](/components/primitives/stack))
+
+## Installation
+
+To install primitive components, add @atlaskit/primitives as a dependency on your project:
+```bash
+$ yarn add @atlaskit/primitives
+```
+
+## Using Primitives
+
+Use primitives for general layout styles for components. Primitives are not currently available in Figma, so the first step in implementing primitive components is identifying where they might fit in a given design. This involves breaking down a design into its core layout components to as granular level as is useful.
+
+<SectionMessage appearance="warning">
+Primitives could be skipped where absolute DOM control is required or very specific styling values are needed, however, this approach is more likely to produce visual elements that fail to adhere to the guidelines of the Atlassian Design System.
+</SectionMessage>
+
+You might like to think first about breaking down a page into Box containers, identifying larger pieces of a design that function in a similar manner or fulfill a singular purpose in a layout and grouping them together under a Box. 
+
+<Image src={boxUsageExample} />
+
+The behavior within and around these boxes can then be broken down into their horizontal Inline and vertical Stack components. 
+
+<SectionMessage>
+The ESLint rule use-primitives offers suggestions for possible primitives in a layout.
+</SectionMessage>
+
+<Image src={inlineUsageExample} />
+<Image src={stackUsageExample} />
+
+## Related
+
+- [Learn more about the Box primitive](/components/primitives/box/usage)
+- [Learn more about the Inline primitive](/components/primitives/inline/usage)
+- [Learn more about the Stack primitive](/components/primitives/stack/usage)

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/stack/usage.mdx

@@ -0,0 +1,31 @@
+---
+title: Stack
+description: A Stack is a primitive component that is responsible for the vertical layout of its child elements.
+order: 2
+---
+
+Primitive components are designed to act as building blocks for composing a user experience. A `Stack` primitive should be used when you want to layout UI elements vertically, and make use of the built-in design guidance from the Atlassian Design System. 
+
+`Stack` primitives work by aligning content vertically on a page or layout, as a container that decides the vertical layout of its children. `Stack` components also decide the specifics of how the children are displayed, for example, where they are aligned or how much space is between child elements. `Stack` should be used purely for visual alignment, and should have no opinions about the functionality of its children.  
+
+In its simplest form, `Stack` operates like a flexbox column, however adds the built in design token support and guidance.
+
+```jsx
+<Stack space="space.100" alignInline="center" alignBlock="start">
+  ...
+</Stack>
+```
+
+## Use `Stack`
+The purpose of a `Stack` is primarily as a container element controlling how content is displayed and aligned vertically. `Stack` should be used any time you wish to layout elements or components vertically. 
+
+The various `Stack` props can then be used to customize the spacing and styling on any child elements. These include:
+- `alignBlock`
+- `alignInline`
+- `spread`
+- `grow`
+- `space`
+
+## Related
+- [Learn more about the Box primitive](/primitives/box/usage)
+- [Learn more about the Stack primitive](/primitives/box/usage)

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.2",
 	"sideEffects": false
 }