@atlaskit/primitives 0.14.0 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @atlaskit/primitives
 
+## 0.14.1
+
+### Patch Changes
+
+- [`d79b6172a93`](https://bitbucket.org/atlassian/atlassian-frontend/commits/d79b6172a93) - Add documentation for responsive xcss.
+
 ## 0.14.0
 
 ### Minor Changes

package/constellation/xcss/examples.mdx

@@ -6,16 +6,23 @@ order: 1
 
 import xcssBasic from '../../examples/constellation/xcss/basic';
 import xcssInteractive from '../../examples/constellation/xcss/interactivity';
+import xcssResponsive from '../../examples/constellation/xcss/responsiveness';
 
 ## Basic
 
-`xcss` can be used to pull together different types of interactions and UI in a safer more composable way.
+`xcss` can 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`.
+To enable interactivity, use familiar selectors like `:hover` and `:focus-visible`.
 
 <Example Component={xcssInteractive} packageName="@atlaskit/primitives/xcss" />
 
+
+## Responsiveness
+
+xCSS also accepts a subset of media queries at predefined breakpoints:
+
+<Example Component={xcssResponsive} packageName="@atlaskit/primitives/xcss" />

package/constellation/xcss/migration.mdx

@@ -8,8 +8,8 @@ order: 2
 
 ### 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
+There are two key changes to be mindful of when migrating to `xcss`.
+The first is updating callsites to remove any nested styles and
 tokenised values.
 
 ```diff
@@ -26,9 +26,9 @@ tokenised values.
 });
 ```
 
-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.
+The second change is that for the `xcss` function to be applied correctly it must be applied on a
+component with an `xcss` JSXAttribute. This won't work with the `css` or `className`
+JSXAttributes, be aware if you're not seeing your styles appear.
 
 ```diff
 - <div css={someStyles} />
@@ -38,8 +38,7 @@ JSXAttributes - so be aware if you're not seeing your styles appear.
 
 #### 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:
+Why are nested selectors a problem? A key philosophy of `xcss` is encouraging more deterministic style application. Restricting nested styles eliminates side-effects and encourages component encapsulation. Consider the below example:
 
 ```tsx
 const myComponentStyles = css({
@@ -55,12 +54,12 @@ const MyComponent = () => (
 );
 ```
 
-Here the component is applying styles that are implicity meant for the text wrapped in the `p` below.
+Here the component is applying styles that are implicitly 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.
+Styles that are inherited or indirectly apply make a UI vulnerable to change and harder to maintain.
+Instead, if the same styles are applied directly to the affected element this can minimize and in some cases completely eliminate this problem.
 
 ```diff
 const myTextStyles = xcss({
@@ -77,17 +76,15 @@ const MyComponent = () => (
 );
 ```
 
-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.
+There will likely be cases where nesting is the only option. While not desirable, nesting can be used minimally, and when the potential impact is considered.
 
 ### FAQ
 
-Overall migration to `xcss` is fairly simple for the majority of cases. Here are some common strategies for migrations.
+Migration to `xcss` is 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.
+Before migrating to tokens, there are two options. Migrate to tokens first and then on a second pass migrate to `xcss` or make the jump directly to use both tokens and `xcss`.
 
 ```tsx
 const someStyles = css({
@@ -107,9 +104,8 @@ const someStyles = xcss({
 
 #### 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`.
+If currently using the `styled` API there are a few steps to migrate.
+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`

package/constellation/xcss/usage.mdx

@@ -3,26 +3,24 @@ title: xCSS
 description: xCSS is a safer, tokens-first approach to CSS-in-JS.
 order: 0
 ---
+import { MediaQueriesTable } from '@af/design-system-docs-ui';
 
 ![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.
+`xcss` is an Atlassian Design System styling API that natively integrates with Atlassian's [design tokens](/tokens) and [primitives](/components/primitives).
 
-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.
+The `xcss` utility behaves similarly to the `css` utility in libraries like `styled-components`, `@compiled` or `@emotion`. If you've used these libraries, `xcss` will feel familiar, with a few additional features and constraints.
 
-Features that will feel familiar:
+Familiar features:
 
-* `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` generates a `className` that is applied to the components
+* `xcss` provides 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.
+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.
+* `xcss` has type-safety that ensures token name usage for all CSS properties represented by design tokens.
+* `xcss` restricts nested selectors completely from usage
 
 ## Usage
 
@@ -51,17 +49,14 @@ const MyBox = () => {
   return <Box xcss={someStyles} />
 }
 ```
+The `xcss` prop and the `xcss` function are direct complements and are designed to be used together.
 
-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.
+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.
+`xcss` uses strongly-typed values generated from design token definitions, making it simpler to apply the right token to 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`
@@ -79,6 +74,10 @@ const someStyles = xcss({
 ```
 
 ### Restricted nesting
+`xcss` is flexible enough 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 the codebase more resilient to change.
+
 
 `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
@@ -106,7 +105,46 @@ const someStyles = xcss({
 ```
 
 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).
+For richer examples of how to use `xcss` please see the [primitives `xcss` documentation](/components/primitives/xcss/examples).
+
+### Media Queries
+xCSS can create responsive layouts at predefined breakpoints that are consistent with the Atlassian Design System. To enable responsive behavior, xCSS exposes the following pre-defined breakpoints:
+<MediaQueriesTable />
+
+Media queries can be applied through keys that can be imported from `@atlaskit/primitives/responsive`.
+For in depth examples on how to enable responsive behavior, please see our [primitive responsiveness documentation](/components/primitives/xcss/examples#responsiveness).
+
+The objects defined at each breakpoint behave in much the same way as a normal xCSS object, and can apply responsiveness to any CSS.
+The only limitation is that a media query can't contain another media query. This is to prevent arbitrary nesting. 
+Additionally, pseudo-selectors can't contain media queries. To use media queries and pseudos, the media query must contain the pseudo.
+
+```
+import { xcss } from '@atlaskit/primitives';
+import { media } from '@atlaskit/primitives/responsive';
+
+const someStyles = xcss({
+  // This is okay, since media queries can contain pseudos
+  [media.above.md]: {
+    ':hover': {
+      backgroundColor: 'color.background.primary.hovered'
+    }
+  },
+
+  // This is not okay, since pseudos can't contain media queries
+  ':hover': {
+    [media.above.md]: {
+      backgroundColor: 'color.background.primary.hovered'
+    }
+  },
+
+  // This is not okay, since media queries can't contain media queries
+  [media.above.md]: {
+    [media.above.xs]: {
+      backgroundColor: 'color.background.primary.hovered'
+    }
+  },
+});
+```
 
 ## Get help
 

package/dist/cjs/index.js

@@ -22,6 +22,18 @@ Object.defineProperty(exports, "Stack", {
     return _stack.default;
   }
 });
+Object.defineProperty(exports, "UNSAFE_BREAKPOINTS_CONFIG", {
+  enumerable: true,
+  get: function get() {
+    return _responsive.UNSAFE_BREAKPOINTS_CONFIG;
+  }
+});
+Object.defineProperty(exports, "UNSAFE_media", {
+  enumerable: true,
+  get: function get() {
+    return _responsive.UNSAFE_media;
+  }
+});
 Object.defineProperty(exports, "xcss", {
   enumerable: true,
   get: function get() {
@@ -31,4 +43,5 @@ Object.defineProperty(exports, "xcss", {
 var _box = _interopRequireDefault(require("./components/box"));
 var _inline = _interopRequireDefault(require("./components/inline"));
 var _xcss = require("./xcss/xcss");
-var _stack = _interopRequireDefault(require("./components/stack"));
+var _stack = _interopRequireDefault(require("./components/stack"));
+var _responsive = require("./helpers/responsive");

package/dist/cjs/version.json

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

package/dist/es2019/index.js

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

package/dist/es2019/version.json

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

package/dist/esm/index.js

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

package/dist/esm/version.json

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

package/dist/types/index.d.ts

@@ -2,3 +2,4 @@ export { default as Box, type BoxProps } from './components/box';
 export { default as Inline, type InlineProps } from './components/inline';
 export { xcss } from './xcss/xcss';
 export { default as Stack, type StackProps } from './components/stack';
+export { UNSAFE_media, UNSAFE_BREAKPOINTS_CONFIG, type Breakpoint, } from './helpers/responsive';

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

@@ -2,3 +2,4 @@ export { default as Box, type BoxProps } from './components/box';
 export { default as Inline, type InlineProps } from './components/inline';
 export { xcss } from './xcss/xcss';
 export { default as Stack, type StackProps } from './components/stack';
+export { UNSAFE_media, UNSAFE_BREAKPOINTS_CONFIG, type Breakpoint, } from './helpers/responsive';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaskit/primitives",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Primitives are token-backed low-level building blocks.",
   "author": "Atlassian Pty Ltd",
   "license": "Apache-2.0",
@@ -132,7 +132,7 @@
     "@atlaskit/visual-regression": "*",
     "@atlassian/atlassian-frontend-prettier-config-1.0.1": "npm:@atlassian/atlassian-frontend-prettier-config@1.0.1",
     "@atlassian/codegen": "^0.1.0",
-    "@atlassian/gemini-visual-regression": "^0.0.33",
+    "@atlassian/gemini-visual-regression": "^0.0.34",
     "@testing-library/react": "^12.1.5",
     "@testing-library/react-hooks": "^8.0.1",
     "csstype": "^3.1.0",

package/report.api.md

@@ -297,7 +297,7 @@ type BoxXCSS = {
 };
 
 // @public
-type Breakpoint = 'lg' | 'md' | 'sm' | 'xl' | 'xs' | 'xxs';
+export type Breakpoint = 'lg' | 'md' | 'sm' | 'xl' | 'xs' | 'xxs';
 
 // @public (undocumented)
 type CSSMediaQueries = {
@@ -622,6 +622,73 @@ type TokenisedProps = {
 // @public (undocumented)
 const uniqueSymbol: unique symbol;
 
+// @public
+export const UNSAFE_BREAKPOINTS_CONFIG: {
+  readonly xxs: {
+    readonly gridItemGutter: 'var(--ds-space-200)';
+    readonly gridMargin: 'var(--ds-space-200)';
+    readonly min: '0rem';
+    readonly max: '29.99rem';
+  };
+  readonly xs: {
+    readonly gridItemGutter: 'var(--ds-space-200)';
+    readonly gridMargin: 'var(--ds-space-200)';
+    readonly min: '30rem';
+    readonly max: '47.99rem';
+  };
+  readonly sm: {
+    readonly gridItemGutter: 'var(--ds-space-200)';
+    readonly gridMargin: 'var(--ds-space-300)';
+    readonly min: '48rem';
+    readonly max: '63.99rem';
+  };
+  readonly md: {
+    readonly gridItemGutter: 'var(--ds-space-300)';
+    readonly gridMargin: 'var(--ds-space-400)';
+    readonly min: '64rem';
+    readonly max: '89.99rem';
+  };
+  readonly lg: {
+    readonly gridItemGutter: 'var(--ds-space-400)';
+    readonly gridMargin: 'var(--ds-space-400)';
+    readonly min: '90rem';
+    readonly max: '109.99rem';
+  };
+  readonly xl: {
+    readonly gridItemGutter: 'var(--ds-space-400)';
+    readonly gridMargin: 'var(--ds-space-500)';
+    readonly min: '110rem';
+    readonly max: null;
+  };
+};
+
+// @internal
+export const UNSAFE_media: {
+  above: {
+    readonly xxs: '@media all';
+    readonly xs: '@media (min-width: 30rem)';
+    readonly sm: '@media (min-width: 48rem)';
+    readonly md: '@media (min-width: 64rem)';
+    readonly lg: '@media (min-width: 90rem)';
+    readonly xl: '@media (min-width: 110rem)';
+  };
+  below: {
+    readonly xs: '@media not all and (min-width: 30rem)';
+    readonly sm: '@media not all and (min-width: 48rem)';
+    readonly md: '@media not all and (min-width: 64rem)';
+    readonly lg: '@media not all and (min-width: 90rem)';
+    readonly xl: '@media not all and (min-width: 110rem)';
+  };
+  only: {
+    readonly xxs: '@media (min-width: 0rem) and (max-width: 29.99rem)';
+    readonly xs: '@media (min-width: 30rem) and (max-width: 47.99rem)';
+    readonly sm: '@media (min-width: 48rem) and (max-width: 63.99rem)';
+    readonly md: '@media (min-width: 64rem) and (max-width: 89.99rem)';
+    readonly lg: '@media (min-width: 90rem) and (max-width: 109.99rem)';
+    readonly xl: '@media (min-width: 110rem)';
+  };
+};
+
 // @public
 export function xcss<Primitive extends typeof Box | typeof Inline = typeof Box>(
   style: Primitive extends typeof Box

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

@@ -259,7 +259,7 @@ type BoxXCSS = {
 };
 
 // @public
-type Breakpoint = 'lg' | 'md' | 'sm' | 'xl' | 'xs' | 'xxs';
+export type Breakpoint = 'lg' | 'md' | 'sm' | 'xl' | 'xs' | 'xxs';
 
 // @public (undocumented)
 type CSSMediaQueries = {
@@ -515,6 +515,73 @@ type TokenisedProps = {
 // @public (undocumented)
 const uniqueSymbol: unique symbol;
 
+// @public
+export const UNSAFE_BREAKPOINTS_CONFIG: {
+    readonly xxs: {
+        readonly gridItemGutter: "var(--ds-space-200)";
+        readonly gridMargin: "var(--ds-space-200)";
+        readonly min: "0rem";
+        readonly max: "29.99rem";
+    };
+    readonly xs: {
+        readonly gridItemGutter: "var(--ds-space-200)";
+        readonly gridMargin: "var(--ds-space-200)";
+        readonly min: "30rem";
+        readonly max: "47.99rem";
+    };
+    readonly sm: {
+        readonly gridItemGutter: "var(--ds-space-200)";
+        readonly gridMargin: "var(--ds-space-300)";
+        readonly min: "48rem";
+        readonly max: "63.99rem";
+    };
+    readonly md: {
+        readonly gridItemGutter: "var(--ds-space-300)";
+        readonly gridMargin: "var(--ds-space-400)";
+        readonly min: "64rem";
+        readonly max: "89.99rem";
+    };
+    readonly lg: {
+        readonly gridItemGutter: "var(--ds-space-400)";
+        readonly gridMargin: "var(--ds-space-400)";
+        readonly min: "90rem";
+        readonly max: "109.99rem";
+    };
+    readonly xl: {
+        readonly gridItemGutter: "var(--ds-space-400)";
+        readonly gridMargin: "var(--ds-space-500)";
+        readonly min: "110rem";
+        readonly max: null;
+    };
+};
+
+// @internal
+export const UNSAFE_media: {
+    above: {
+        readonly xxs: "@media all";
+        readonly xs: "@media (min-width: 30rem)";
+        readonly sm: "@media (min-width: 48rem)";
+        readonly md: "@media (min-width: 64rem)";
+        readonly lg: "@media (min-width: 90rem)";
+        readonly xl: "@media (min-width: 110rem)";
+    };
+    below: {
+        readonly xs: "@media not all and (min-width: 30rem)";
+        readonly sm: "@media not all and (min-width: 48rem)";
+        readonly md: "@media not all and (min-width: 64rem)";
+        readonly lg: "@media not all and (min-width: 90rem)";
+        readonly xl: "@media not all and (min-width: 110rem)";
+    };
+    only: {
+        readonly xxs: "@media (min-width: 0rem) and (max-width: 29.99rem)";
+        readonly xs: "@media (min-width: 30rem) and (max-width: 47.99rem)";
+        readonly sm: "@media (min-width: 48rem) and (max-width: 63.99rem)";
+        readonly md: "@media (min-width: 64rem) and (max-width: 89.99rem)";
+        readonly lg: "@media (min-width: 90rem) and (max-width: 109.99rem)";
+        readonly xl: "@media (min-width: 110rem)";
+    };
+};
+
 // @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<Spacing> | ScopedSafeCSSObject<Spacing>[] : 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" | "xcss"> & RefAttributes<any>>> ? InlineStyles : never;