@atlaskit/primitives 1.0.5 → 1.0.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @atlaskit/primitives
 
+## 1.0.6
+
+### Patch Changes
+
+- [`aa8ec75ace3`](https://bitbucket.org/atlassian/atlassian-frontend/commits/aa8ec75ace3) - Simplify types for `Show` and `Hide` components. There should be no difference in behavior.
+
 ## 1.0.5
 
 ### Patch Changes

package/constellation/bleed/example.mdx

@@ -36,11 +36,13 @@ each avatar to overlap its direct sibling and create our desired stack.
 ## Block whitespace
 
 Bleed can be controlled on the block axis (vertical) with the `block` property. The values of this property are tied to our spacing scale.
+Note, in the context of a flex container bleed will collapse the whitespace around its child element.
 
 <Example Component={BleedBlock} packageName="@atlaskit/primitives/bleed" />
 
 ## Inline whitespace
 
 Bleed can also be controlled on the inline axis (horizontal) with the `inline` property. The values of this property are tied to our spacing scale.
+Note, in the context of a flex container bleed will collapse the whitespace around its child element.
 
 <Example Component={BleedInline} packageName="@atlaskit/primitives/bleed" />

package/constellation/box/examples.mdx

@@ -8,6 +8,8 @@ import BoxBasic from '../../examples/constellation/box/basic';
 import BoxPadding from '../../examples/constellation/box/padding';
 import BoxBackgroundColor from '../../examples/constellation/box/background-color';
 import BoxXcss from '../../examples/constellation/box/xcss';
+import PracticalUseCase from '../../examples/constellation/box/practical-use-case';
+
 import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
 <CodeDocsHeader
@@ -43,3 +45,7 @@ Box also exposes an `xcss` prop. This prop can take `xcss` function calls that c
 <Example Component={BoxXcss} packageName="@atlaskit/primitives/box" />
 
 For more information on xCSS, see the dedicated [xCSS](/components/primitives/xcss) documentation.
+
+## Practical Use Case
+
+<Example Component={PracticalUseCase} packageName="@atlaskit/primitives/box" />

package/constellation/flex/examples.mdx

@@ -21,11 +21,16 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
 ## Basic
 
 The `Flex` component is designed as a very basic mapping to the CSS Flexbox API.
-It can be used as a less richly-configured `Inline` or `Stack`.
+It can be used as a less richly-configured `Inline` or `Stack`. Like `Stack` and `Inline`
+`Flex` exclusively supports token-backed `gap` properties to ensure layouts using `Flex` match
+the Atlassian Design System spacing scale.
 
 <Example Component={FlexJustifyContent} packageName="@atlaskit/primitives/flex" />
 
-## Align items
+## Align items and justify content
+
+`Flex` applies the `alignItems` and `justifyContent` properties to align content
+along its cross and main axes respectively.
 
 <Example Component={FlexAlignItems} packageName="@atlaskit/primitives/flex" />
 

package/constellation/grid/examples.mdx

@@ -44,3 +44,6 @@ Grid-prefixed properties in CSS do not have this prefix in the component API. `g
 
 <Example Component={GridAutoFlow} packageName="@atlaskit/primitives/grid" />
 
+You may also be looking for:
+* [responsive layout grid](/components/grid)
+* [legacy page grid](/components/page/grid)

package/constellation/inline/examples.mdx

@@ -14,6 +14,7 @@ import InlineWrap from '../../examples/constellation/inline/wrap';
 import InlineSeparator from '../../examples/constellation/inline/separator';
 import InlineGrow from '../../examples/constellation/inline/grow';
 import InlineAs from '../../examples/constellation/inline/as';
+import InlinePracticalUseCase from '../../examples/constellation/inline/practical-use-case';
 
 import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
@@ -23,6 +24,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
   directoryName="primitives"
 />
 
+
 ## Basic
 
 Inline is an abstraction to efficiently lay-out a group of elements horizontally.
@@ -89,3 +91,7 @@ To control that the `grow` prop can be used with the values:
 It's possible to control the rendered HTML element with the `as` prop.
 
 <Example Component={InlineAs} packageName="@atlaskit/primitives/inline" />
+
+## Practical Use Case
+
+<Example Component={InlinePracticalUseCase} packageName="@atlaskit/primitives/inline" />

package/constellation/overview/index.mdx

@@ -19,19 +19,18 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
   directoryName="primitives"
 />
 
-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,
+Primitives are a new type of component for layouts and the placement of elements.
+They act as simple 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.
+Primitives are a combination of design tokens that go a step further.
+These are component-like abstractions powered by design tokens that add a layer of ergonomics and accessibility. Tokens are great at describing the what of a design decision;
+primitives make it easier to reason about the when and how. This reduces cognitive overhead and prevents accidents or mistakes.
 
 ## 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.
+Each primitive is designed to have a single responsibility, and it should be immediately clear where and when each primitive should be used.
+However, they are also flexible enough that they should be able to be used together to compose complex designs not otherwise implemented directly in the Design Systems.
 
 Currently, three core primitive components are available - Box, Inline and Stack. A large amount of layout problems can be reduced to laying out content:
 - in a container (see [box](/components/primitives/box))
@@ -41,7 +40,7 @@ Currently, three core primitive components are available - Box, Inline and Stack
 Additional layouts not well-expressed by these core primitives can also be composed using:
 - CSS Flexbox (see [flex](/components/primitives/flex))
 - CSS Grid (see [grid](/components/primitives/grid))
-- Divider (see [divider](/components/primitives/divider))
+- Bleed (see [bleed](/components/primitives/bleed))
 
 ## Installation
 
@@ -52,15 +51,13 @@ $ yarn add @atlaskit/primitives
 
 ## Using Primitives
 
-Use primitives for general layout styles for components.
+Use primitives for composing layouts.
 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 should be avoided 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.
+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} />
 

package/constellation/responsive/01-show/code.mdx

@@ -0,0 +1,19 @@
+---
+title: Show
+description: Show is a responsive primitive that displays children at specified breakpoints
+order: 2
+---
+
+import { CodeDocsHeader } from '@af/design-system-docs-ui';
+
+<CodeDocsHeader
+  name="@atlaskit/primitives"
+  repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
+  directoryName="primitives"
+/>
+
+import ShowProps from '!!extract-react-types-loader!../../../extract-react-types/show-props'
+
+## Props
+
+<PropsTable heading="" props={ShowProps} />

package/constellation/responsive/02-hide/code.mdx

@@ -0,0 +1,19 @@
+---
+title: Hide
+description: Hide is a responsive primitive that hides children at specified breakpoints
+order: 2
+---
+
+import { CodeDocsHeader } from '@af/design-system-docs-ui';
+
+<CodeDocsHeader
+  name="@atlaskit/primitives"
+  repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
+  directoryName="primitives"
+/>
+
+import HideProps from '!!extract-react-types-loader!../../../extract-react-types/hide-props'
+
+## Props
+
+<PropsTable heading="" props={HideProps} />

package/constellation/stack/examples.mdx

@@ -5,6 +5,7 @@ order: 0
 ---
 
 import StackBasic from '../../examples/constellation/stack/basic';
+import PracticalUseCase from '../../examples/constellation/stack/practical-use-case';
 import StackSpaceBasic from '../../examples/constellation/stack/space-basic';
 import StackAlignBlock from '../../examples/constellation/stack/align-block';
 import StackAlignInline from '../../examples/constellation/stack/align-inline';
@@ -68,3 +69,7 @@ To control that the `grow` prop can be used with the values:
 It's possible to control the rendered HTML element with the `as` prop.
 
 <Example Component={StackAs} packageName="@atlaskit/primitives/stack" />
+
+## Practical Use Case
+
+<Example Component={PracticalUseCase} packageName="@atlaskit/primitives/stack" />

package/dist/cjs/components/inline.js

@@ -39,8 +39,7 @@ var Separator = function Separator(_ref) {
 /**
  * __Inline__
  *
- * Inline is a primitive component based on flexbox that manages the horizontal layout of direct children.
- *
+ * Inline is a primitive component based on CSS Flexbox that manages the horizontal layout of direct children.
  *
  * @example
  * ```tsx

package/dist/cjs/version.json

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

package/dist/es2019/components/inline.js

@@ -29,8 +29,7 @@ const Separator = ({
 /**
  * __Inline__
  *
- * Inline is a primitive component based on flexbox that manages the horizontal layout of direct children.
- *
+ * Inline is a primitive component based on CSS Flexbox that manages the horizontal layout of direct children.
  *
  * @example
  * ```tsx

package/dist/es2019/version.json

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

package/dist/esm/components/inline.js

@@ -31,8 +31,7 @@ var Separator = function Separator(_ref) {
 /**
  * __Inline__
  *
- * Inline is a primitive component based on flexbox that manages the horizontal layout of direct children.
- *
+ * Inline is a primitive component based on CSS Flexbox that manages the horizontal layout of direct children.
  *
  * @example
  * ```tsx

package/dist/esm/version.json

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

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

@@ -56,8 +56,7 @@ export type Grow = 'hug' | 'fill';
 /**
  * __Inline__
  *
- * Inline is a primitive component based on flexbox that manages the horizontal layout of direct children.
- *
+ * Inline is a primitive component based on CSS Flexbox that manages the horizontal layout of direct children.
  *
  * @example
  * ```tsx

package/dist/types/responsive/hide.d.ts

@@ -6,24 +6,22 @@ type As = 'article' | 'aside' | 'dialog' | 'div' | 'footer' | 'header' | 'li' |
 type ResponsiveHideProps = {
     as?: As;
     children: ReactNode;
-    /**
-     * Apply CSS to hide this specifically **above** this breakpoint.
-     * The smallest breakpoint is not included as it would always be shown and this would not be performant.
-     *
-     * @important do not mix `above` and `below` (TypeScript should prevent this)
-     */
-    above?: Exclude<Breakpoint, 'xxs'>;
+} & ({
+    above?: never;
     /**
      * Apply CSS to hide this specifically **below** this breakpoint.
      * The smallest breakpoint is not included as it would never be shown and this would not be performant.
      *
      * @important do not mix `above` and `below` (TypeScript should prevent this)
      */
-    below?: Exclude<Breakpoint, 'xxs'>;
-} & ({
-    above?: never;
     below: Exclude<Breakpoint, 'xxs'>;
 } | {
+    /**
+     * Apply CSS to hide this specifically **above** this breakpoint.
+     * The smallest breakpoint is not included as it would always be shown and this would not be performant.
+     *
+     * @important do not mix `above` and `below` (TypeScript should prevent this)
+     */
     above: Exclude<Breakpoint, 'xxs'>;
     below?: never;
 });

package/dist/types/responsive/show.d.ts

@@ -6,24 +6,22 @@ type As = 'article' | 'aside' | 'dialog' | 'div' | 'footer' | 'header' | 'li' |
 type ResponsiveShowProps = {
     as?: As;
     children: ReactNode;
-    /**
-     * Apply CSS to show this specifically **above** this breakpoint.
-     * The smallest breakpoint is not included as it would always be shown and this would not be performant.
-     *
-     * @important do not mix `above` and `below` (TypeScript should prevent this)
-     */
-    above?: Exclude<Breakpoint, 'xxs'>;
+} & ({
+    above?: never;
     /**
      * Apply CSS to show this specifically **below** this breakpoint.
      * The smallest breakpoint is not included as it would never be shown and this would not be performant.
      *
      * @important do not mix `above` and `below` (TypeScript should prevent this)
      */
-    below?: Exclude<Breakpoint, 'xxs'>;
-} & ({
-    above?: never;
     below: Exclude<Breakpoint, 'xxs'>;
 } | {
+    /**
+     * Apply CSS to show this specifically **above** this breakpoint.
+     * The smallest breakpoint is not included as it would always be shown and this would not be performant.
+     *
+     * @important do not mix `above` and `below` (TypeScript should prevent this)
+     */
     above: Exclude<Breakpoint, 'xxs'>;
     below?: never;
 });

package/dist/types-ts4.5/components/inline.d.ts

@@ -56,8 +56,7 @@ export type Grow = 'hug' | 'fill';
 /**
  * __Inline__
  *
- * Inline is a primitive component based on flexbox that manages the horizontal layout of direct children.
- *
+ * Inline is a primitive component based on CSS Flexbox that manages the horizontal layout of direct children.
  *
  * @example
  * ```tsx

package/dist/types-ts4.5/responsive/hide.d.ts

@@ -6,24 +6,22 @@ type As = 'article' | 'aside' | 'dialog' | 'div' | 'footer' | 'header' | 'li' |
 type ResponsiveHideProps = {
     as?: As;
     children: ReactNode;
-    /**
-     * Apply CSS to hide this specifically **above** this breakpoint.
-     * The smallest breakpoint is not included as it would always be shown and this would not be performant.
-     *
-     * @important do not mix `above` and `below` (TypeScript should prevent this)
-     */
-    above?: Exclude<Breakpoint, 'xxs'>;
+} & ({
+    above?: never;
     /**
      * Apply CSS to hide this specifically **below** this breakpoint.
      * The smallest breakpoint is not included as it would never be shown and this would not be performant.
      *
      * @important do not mix `above` and `below` (TypeScript should prevent this)
      */
-    below?: Exclude<Breakpoint, 'xxs'>;
-} & ({
-    above?: never;
     below: Exclude<Breakpoint, 'xxs'>;
 } | {
+    /**
+     * Apply CSS to hide this specifically **above** this breakpoint.
+     * The smallest breakpoint is not included as it would always be shown and this would not be performant.
+     *
+     * @important do not mix `above` and `below` (TypeScript should prevent this)
+     */
     above: Exclude<Breakpoint, 'xxs'>;
     below?: never;
 });

package/dist/types-ts4.5/responsive/show.d.ts

@@ -6,24 +6,22 @@ type As = 'article' | 'aside' | 'dialog' | 'div' | 'footer' | 'header' | 'li' |
 type ResponsiveShowProps = {
     as?: As;
     children: ReactNode;
-    /**
-     * Apply CSS to show this specifically **above** this breakpoint.
-     * The smallest breakpoint is not included as it would always be shown and this would not be performant.
-     *
-     * @important do not mix `above` and `below` (TypeScript should prevent this)
-     */
-    above?: Exclude<Breakpoint, 'xxs'>;
+} & ({
+    above?: never;
     /**
      * Apply CSS to show this specifically **below** this breakpoint.
      * The smallest breakpoint is not included as it would never be shown and this would not be performant.
      *
      * @important do not mix `above` and `below` (TypeScript should prevent this)
      */
-    below?: Exclude<Breakpoint, 'xxs'>;
-} & ({
-    above?: never;
     below: Exclude<Breakpoint, 'xxs'>;
 } | {
+    /**
+     * Apply CSS to show this specifically **above** this breakpoint.
+     * The smallest breakpoint is not included as it would always be shown and this would not be performant.
+     *
+     * @important do not mix `above` and `below` (TypeScript should prevent this)
+     */
     above: Exclude<Breakpoint, 'xxs'>;
     below?: never;
 });

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

@@ -0,0 +1,48 @@
+import { ReactNode } from 'react';
+
+import { Breakpoint } from '../src/responsive/types';
+
+type As =
+  | 'article'
+  | 'aside'
+  | 'dialog'
+  | 'div'
+  | 'footer'
+  | 'header'
+  | 'li'
+  | 'main'
+  | 'nav'
+  | 'ol'
+  | 'section'
+  | 'span'
+  | 'ul';
+
+type ResponsiveHideProps = {
+  /**
+   * The DOM element to render as the Box. Defaults to `div`.
+   */
+  as?: As;
+
+  /**
+   * Elements to be rendered inside the primitive.
+   */
+  children: ReactNode;
+
+  /**
+   * Apply CSS to hide this specifically **above** this breakpoint.
+   * The smallest breakpoint is not included as it would always be shown and this would not be performant.
+   *
+   * @important do not mix `above` and `below` (TypeScript should prevent this)
+   */
+  above?: Exclude<Breakpoint, 'xxs'>;
+
+  /**
+   * Apply CSS to hide this specifically **below** this breakpoint.
+   * The smallest breakpoint is not included as it would never be shown and this would not be performant.
+   *
+   * @important do not mix `above` and `below` (TypeScript should prevent this)
+   */
+  below?: Exclude<Breakpoint, 'xxs'>;
+};
+
+export default function Hide(_: ResponsiveHideProps) {}

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

@@ -0,0 +1,48 @@
+import { ReactNode } from 'react';
+
+import { Breakpoint } from '../src/responsive/types';
+
+type As =
+  | 'article'
+  | 'aside'
+  | 'dialog'
+  | 'div'
+  | 'footer'
+  | 'header'
+  | 'li'
+  | 'main'
+  | 'nav'
+  | 'ol'
+  | 'section'
+  | 'span'
+  | 'ul';
+
+type ResponsiveShowProps = {
+  /**
+   * The DOM element to render as the Box. Defaults to `div`.
+   */
+  as?: As;
+
+  /**
+   * Elements to be rendered inside the primitive.
+   */
+  children: ReactNode;
+
+  /**
+   * Apply CSS to show this specifically **above** this breakpoint.
+   * The smallest breakpoint is not included as it would always be shown and this would not be performant.
+   *
+   * @important do not mix `above` and `below` (TypeScript should prevent this)
+   */
+  above?: Exclude<Breakpoint, 'xxs'>;
+
+  /**
+   * Apply CSS to show this specifically **below** this breakpoint.
+   * The smallest breakpoint is not included as it would never be shown and this would not be performant.
+   *
+   * @important do not mix `above` and `below` (TypeScript should prevent this)
+   */
+  below?: Exclude<Breakpoint, 'xxs'>;
+};
+
+export default function Show(_: ResponsiveShowProps) {}

package/package.json

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