@atlaskit/primitives 1.0.9 → 1.0.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/constellation/box/usage.mdx +3 -0
- package/constellation/flex/examples.mdx +4 -8
- package/constellation/grid/examples.mdx +1 -2
- package/constellation/inline/examples.mdx +14 -13
- package/constellation/inline/usage.mdx +9 -5
- package/constellation/overview/index.mdx +7 -5
- package/constellation/responsive/01-show/examples.mdx +2 -2
- package/constellation/responsive/02-hide/examples.mdx +2 -2
- package/constellation/responsive/usage.mdx +5 -8
- package/constellation/stack/examples.mdx +7 -8
- package/constellation/stack/usage.mdx +9 -5
- package/constellation/xcss/examples.mdx +2 -2
- package/constellation/xcss/logo.png +0 -0
- package/constellation/xcss/migration.mdx +1 -1
- package/constellation/xcss/usage.mdx +2 -8
- package/dist/cjs/components/pressable.js +5 -3
- package/dist/cjs/index.js +0 -7
- package/dist/cjs/version.json +1 -1
- package/dist/cjs/xcss/xcss.js +7 -30
- package/dist/es2019/components/pressable.js +5 -3
- package/dist/es2019/index.js +0 -1
- package/dist/es2019/version.json +1 -1
- package/dist/es2019/xcss/xcss.js +7 -24
- package/dist/esm/components/pressable.js +5 -3
- package/dist/esm/index.js +0 -1
- package/dist/esm/version.json +1 -1
- package/dist/esm/xcss/xcss.js +7 -30
- package/dist/types/components/flex.d.ts +1 -1
- package/dist/types/components/inline.d.ts +1 -1
- package/dist/types/components/pressable.d.ts +5 -3
- package/dist/types/components/stack.d.ts +1 -1
- package/dist/types/components/types.d.ts +4 -3
- package/dist/types/index.d.ts +0 -2
- package/dist/types/xcss/xcss.d.ts +11 -29
- package/dist/types-ts4.5/components/flex.d.ts +1 -1
- package/dist/types-ts4.5/components/inline.d.ts +1 -1
- package/dist/types-ts4.5/components/pressable.d.ts +5 -3
- package/dist/types-ts4.5/components/stack.d.ts +1 -1
- package/dist/types-ts4.5/components/types.d.ts +4 -3
- package/dist/types-ts4.5/index.d.ts +0 -2
- package/dist/types-ts4.5/xcss/xcss.d.ts +11 -29
- package/package.json +14 -13
- package/pressable/package.json +15 -0
- package/report.api.md +23 -115
- package/tmp/api-report-tmp.d.ts +15 -54
- package/constellation/accessibility/examples.mdx +0 -9
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# @atlaskit/primitives
|
|
2
2
|
|
|
3
|
+
## 1.0.11
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [`30fb9fe0ff4`](https://bitbucket.org/atlassian/atlassian-frontend/commits/30fb9fe0ff4) - Mark Pressable exports as unsafe (for internal use only)
|
|
8
|
+
|
|
9
|
+
## 1.0.10
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- [`ac645224013`](https://bitbucket.org/atlassian/atlassian-frontend/commits/ac645224013) - Removes generic for `xcss` fn. Adds support for other `AtTypes`.
|
|
14
|
+
|
|
3
15
|
## 1.0.9
|
|
4
16
|
|
|
5
17
|
### Patch Changes
|
|
@@ -26,3 +26,6 @@ To identify usages of `Box` in a given design, look for where a UI element will
|
|
|
26
26
|
## Related
|
|
27
27
|
- [Learn more about the Inline primitive](/components/primitives/inline/usage)
|
|
28
28
|
- [Learn more about the Stack primitive](/components/primitives/stack/usage)
|
|
29
|
+
- [Learn more about the Grid primitive](/components/primitives/grid/examples)
|
|
30
|
+
- [Learn more about the Bleed primitive](/components/primitives/bleed/examples)
|
|
31
|
+
- [Learn more about the Flex primitive](/components/primitives/flex/examples)
|
|
@@ -20,24 +20,20 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
20
20
|
|
|
21
21
|
## Basic
|
|
22
22
|
|
|
23
|
-
The `Flex` component is
|
|
24
|
-
It can be used as a less richly-configured `Inline` or `Stack`. Like `Stack` and `Inline`
|
|
25
|
-
`Flex` exclusively supports token-backed `gap` properties to ensure layouts using `Flex` match
|
|
26
|
-
the Atlassian Design System spacing scale.
|
|
23
|
+
The `Flex` component is a basic mapping to the CSS Flexbox API. 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.
|
|
27
24
|
|
|
28
25
|
<Example Component={FlexJustifyContent} packageName="@atlaskit/primitives/flex" />
|
|
29
26
|
|
|
30
27
|
## Align items and justify content
|
|
31
28
|
|
|
32
|
-
`Flex` applies the `alignItems` and `justifyContent` properties to align content
|
|
33
|
-
along its cross and main axes respectively.
|
|
29
|
+
`Flex` applies the `alignItems` and `justifyContent` properties to align content along its cross and main axes respectively.
|
|
34
30
|
|
|
35
31
|
<Example Component={FlexAlignItems} packageName="@atlaskit/primitives/flex" />
|
|
36
32
|
|
|
37
33
|
## Wrap
|
|
38
34
|
|
|
39
|
-
Flex-prefixed properties in CSS do not have this prefix in the component API.
|
|
40
|
-
For example `flex-wrap` is instead applied as the `wrap` property.
|
|
35
|
+
Flex-prefixed properties in CSS do not have this prefix in the component API.
|
|
36
|
+
For example, `flex-wrap` is instead applied as the `wrap` property.
|
|
41
37
|
|
|
42
38
|
<Example Component={FlexWrap} packageName="@atlaskit/primitives/flex" />
|
|
43
39
|
|
|
@@ -28,9 +28,8 @@ It can be used as an alternative to [Flex](/components/primitives/flex), [Inline
|
|
|
28
28
|
|
|
29
29
|
## Gap properties
|
|
30
30
|
|
|
31
|
-
Gap properties - `rowGap`, `columnGap` and `gap` only allow token-backed values. This is to aid ergonomics
|
|
32
|
-
and keep the whitespace of the grid harmonious with our spacing system.
|
|
33
31
|
|
|
32
|
+
Gap properties `rowGap`, `columnGap` and `gap` only allow token-backed values. This is to aid ergonomics and keep the whitespace of the grid harmonious with the spacing system.
|
|
34
33
|
<Example Component={GridGap} packageName="@atlaskit/primitives/grid" />
|
|
35
34
|
|
|
36
35
|
## Template syntax
|
|
@@ -27,8 +27,9 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
27
27
|
|
|
28
28
|
## Basic
|
|
29
29
|
|
|
30
|
-
Inline
|
|
31
|
-
|
|
30
|
+
Inline should be used to efficiently lay-out a group of elements horizontally.
|
|
31
|
+
|
|
32
|
+
Use the given props to configure display behaviour using designs tokens, as shown in the more complex examples below.
|
|
32
33
|
|
|
33
34
|
<Example Component={InlineBasic} packageName="@atlaskit/primitives/inline" />
|
|
34
35
|
|
|
@@ -38,16 +39,15 @@ Spacing between items can be controlled with the `space` prop:
|
|
|
38
39
|
|
|
39
40
|
<Example Component={InlineSpaceBasic} packageName="@atlaskit/primitives/inline" />
|
|
40
41
|
|
|
41
|
-
When content is set to wrap the `space` prop applies equal spacing between rows
|
|
42
|
+
When content is set to wrap, the `space` prop applies equal spacing between rows.
|
|
42
43
|
|
|
43
|
-
|
|
44
|
+
For a different space value between rows use the `rowSpace` prop.
|
|
44
45
|
|
|
45
|
-
|
|
46
|
+
<Example Component={InlineSpaceWrap} packageName="@atlaskit/primitives/inline" />
|
|
46
47
|
|
|
47
48
|
## Alignment
|
|
48
49
|
|
|
49
|
-
To control the alignment of items you can use the `alignBlock` and `alignInline` props which control
|
|
50
|
-
alignment in the block and inline directions respectively.
|
|
50
|
+
To control the alignment of items you can use the `alignBlock` and `alignInline` props which control alignment in the vertical and horizontal axis respectively.
|
|
51
51
|
|
|
52
52
|
### Block alignment
|
|
53
53
|
|
|
@@ -59,7 +59,7 @@ alignment in the block and inline directions respectively.
|
|
|
59
59
|
|
|
60
60
|
## Spread
|
|
61
61
|
|
|
62
|
-
Elements can be set to stay together
|
|
62
|
+
Elements can be set to stay together, spaced at the given value (default behaviour) or spread equally in the space available.
|
|
63
63
|
|
|
64
64
|
<Example Component={InlineSpread} packageName="@atlaskit/primitives/inline" />
|
|
65
65
|
|
|
@@ -71,15 +71,14 @@ When the number of items goes beyond the available space `shouldWrap` can be use
|
|
|
71
71
|
|
|
72
72
|
## Separator
|
|
73
73
|
|
|
74
|
-
For logically related elements it's possible to specify a `separator` value.
|
|
74
|
+
For logically related elements it's possible to specify a `separator` character value.
|
|
75
75
|
|
|
76
76
|
<Example Component={InlineSeparator} packageName="@atlaskit/primitives/inline" />
|
|
77
77
|
|
|
78
78
|
## Width control
|
|
79
79
|
|
|
80
|
-
By default an `Inline` will have its width influenced by the context where it appears.
|
|
81
|
-
|
|
82
|
-
To control that the `grow` prop can be used with the values:
|
|
80
|
+
By default an `Inline` will have its width influenced by the context where it appears.
|
|
81
|
+
To control the width, the `grow` prop can be used with the values:
|
|
83
82
|
|
|
84
83
|
* `hug` (default) to use space only as required by its children, or
|
|
85
84
|
* `fill` to take all space provided by the parent element.
|
|
@@ -92,6 +91,8 @@ It's possible to control the rendered HTML element with the `as` prop.
|
|
|
92
91
|
|
|
93
92
|
<Example Component={InlineAs} packageName="@atlaskit/primitives/inline" />
|
|
94
93
|
|
|
95
|
-
## Practical
|
|
94
|
+
## Practical use case
|
|
95
|
+
|
|
96
|
+
An example of how an `Inline` might be used in product, using Atlassian Design System components.
|
|
96
97
|
|
|
97
98
|
<Example Component={InlinePracticalUseCase} packageName="@atlaskit/primitives/inline" />
|
|
@@ -4,9 +4,9 @@ description: Inline is a primitive component based on flexbox that manages the h
|
|
|
4
4
|
order: 2
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
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.
|
|
7
|
+
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.
|
|
8
8
|
|
|
9
|
-
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.
|
|
9
|
+
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.
|
|
10
10
|
|
|
11
11
|
In its simplest form, `Inline` operates like a flexbox row, however adds the built in design token support and guidance.
|
|
12
12
|
|
|
@@ -15,10 +15,11 @@ In its simplest form, `Inline` operates like a flexbox row, however adds the bui
|
|
|
15
15
|
...
|
|
16
16
|
</Inline>
|
|
17
17
|
```
|
|
18
|
-
|
|
18
|
+
|
|
19
|
+
`Inline` also has a flex-direction: row; this is the default for flexbox, so it is not explicitly applied.
|
|
19
20
|
|
|
20
21
|
## Use `Inline`
|
|
21
|
-
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.
|
|
22
|
+
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.
|
|
22
23
|
|
|
23
24
|
The various Inline props can then be used to customize the spacing and styling on any child elements. These include:
|
|
24
25
|
|
|
@@ -31,6 +32,9 @@ The various Inline props can then be used to customize the spacing and styling o
|
|
|
31
32
|
- `rowSpace`
|
|
32
33
|
- `separator`
|
|
33
34
|
|
|
34
|
-
|
|
35
|
+
- [Learn more about the Primitives](/components/primitives/overview)
|
|
35
36
|
- [Learn more about the Box primitive](/components/primitives/box/usage)
|
|
36
37
|
- [Learn more about the Stack primitive](/components/primitives/stack/usage)
|
|
38
|
+
- [Learn more about the Grid primitive](/components/primitives/grid/examples)
|
|
39
|
+
- [Learn more about the Bleed primitive](/components/primitives/bleed/examples)
|
|
40
|
+
- [Learn more about the Flex primitive](/components/primitives/flex/examples)
|
|
@@ -23,9 +23,8 @@ Primitives are a new type of component for layouts and the placement of elements
|
|
|
23
23
|
They act as simple building blocks to compose different parts of the user experience,
|
|
24
24
|
from the smallest design decisions (for example, the spacing around an icon) to larger layout decisions (for example, how a page is structured).
|
|
25
25
|
|
|
26
|
-
Primitives are a
|
|
27
|
-
|
|
28
|
-
primitives make it easier to reason about the when and how. This reduces cognitive overhead and prevents accidents or mistakes.
|
|
26
|
+
Primitives are powered by design tokens and add a layer of ergonomics and accessibility to token application. Tokens are great at describing the what of a design decision;
|
|
27
|
+
primitives make it easier to reason about the when and how. This reduces cognitive overhead, improves productivity and prevents accidents or mistakes.
|
|
29
28
|
|
|
30
29
|
## Available Primitives
|
|
31
30
|
|
|
@@ -57,14 +56,14 @@ This involves breaking down a design into its core layout components to as granu
|
|
|
57
56
|
|
|
58
57
|
You might like to think first about breaking down a page into `Box` containers,
|
|
59
58
|
identifying larger pieces of a design that function in a similar manner or fulfill a singular purpose
|
|
60
|
-
in a layout and grouping them together under a Box
|
|
59
|
+
in a layout and grouping them together under a `Box`.
|
|
61
60
|
|
|
62
61
|
<Image src={boxUsageExample} />
|
|
63
62
|
|
|
64
63
|
The behavior within and around these boxes can then be broken down into their horizontal `Inline` and vertical `Stack` components.
|
|
65
64
|
|
|
66
65
|
<SectionMessage>
|
|
67
|
-
The ESLint rule use-primitives offers suggestions for possible primitives in a layout.
|
|
66
|
+
The ESLint rule <a href="/components/eslint-plugin-design-system/usage#use-primitives">use-primitives</a> offers suggestions for possible primitives to apply in a layout.
|
|
68
67
|
</SectionMessage>
|
|
69
68
|
|
|
70
69
|
<Image src={inlineUsageExample} />
|
|
@@ -75,3 +74,6 @@ The ESLint rule use-primitives offers suggestions for possible primitives in a l
|
|
|
75
74
|
- [Learn more about the Box primitive](/components/primitives/box/usage)
|
|
76
75
|
- [Learn more about the Inline primitive](/components/primitives/inline/usage)
|
|
77
76
|
- [Learn more about the Stack primitive](/components/primitives/stack/usage)
|
|
77
|
+
- [Learn more about the Grid primitive](/components/primitives/grid/examples)
|
|
78
|
+
- [Learn more about the Bleed primitive](/components/primitives/bleed/examples)
|
|
79
|
+
- [Learn more about the Fkex primitive](/components/primitives/flex/examples)
|
|
@@ -18,9 +18,9 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
18
18
|
|
|
19
19
|
### Show
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
Using `Show` allows you to show the children using CSS `display: …` when the viewport size is above a specified breakpoint. By default, unless the breakpoint is met, contents are hidden.
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
Children that are not shown are still rendered into the DOM, so there so there is typically little performance savings — primarily that they are not painted.
|
|
24
24
|
|
|
25
25
|
<Example Component={ShowExample} packageName="@atlaskit/primitives/responsive" />
|
|
26
26
|
|
|
@@ -17,9 +17,9 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
17
17
|
|
|
18
18
|
### Hide
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
Using Hide allows you to Hide the children using CSS `display: none` when the viewport size is above a specified breakpoint. By default, unless the breakpoint is met, contents are hidden.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
Children that are hidden are still rendered into the DOM, so there so there is typically little performance savings — primarily that they are not painted.
|
|
23
23
|
|
|
24
24
|
<Example Component={HideExample} packageName="@atlaskit/primitives/responsive" />
|
|
25
25
|
|
|
@@ -6,12 +6,13 @@ order: 2
|
|
|
6
6
|
|
|
7
7
|
## Media query helpers
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
The media query helper object `media.above[breakpoint]` maps to our [breakpoints](/components/grid/usage#breakpoints) as a media query for use in css-in-js. `media.above[breakpoint]` targets all viewports **above** (larger than) the min-width of a given breakpoint
|
|
10
|
+
|
|
11
|
+
These responsive helpers are designed be used in conjunction with [xcss](/components/primitives/xcss). It is recommended that both are used when available as this uses our media queries to allow for safe, responsive styling.
|
|
11
12
|
|
|
12
13
|
### A basic example:
|
|
13
14
|
|
|
14
|
-
Compose your default styles alongside media overrides in [xcss](/components/primitives/xcss) or `css
|
|
15
|
+
Compose your default styles alongside media overrides in [xcss](/components/primitives/xcss) or `css`.
|
|
15
16
|
|
|
16
17
|
```tsx
|
|
17
18
|
const customStyles = xcss({
|
|
@@ -28,7 +29,7 @@ export const Component = ({ children }: { children: ReactNode }) => (
|
|
|
28
29
|
|
|
29
30
|
### `media.above` usage
|
|
30
31
|
|
|
31
|
-
|
|
32
|
+
It is important to note that the `media.above.xxs` will **always** match, it is explicitly `'@media all'`. This is only included for easy programatic usage, but it has a negative performance impact.
|
|
32
33
|
|
|
33
34
|
```tsx
|
|
34
35
|
const customStyles = css({
|
|
@@ -47,7 +48,3 @@ This is intentionally excluded at the moment as we're shipping our opinion that
|
|
|
47
48
|
We understand this will not scale and we're open to change, but we'd like to change this with feedback.
|
|
48
49
|
|
|
49
50
|
If we do add it back, we'd suggest codebases prefer a single approach (eg. `above` or `below`) and use that consistently. Mixing them results in confusion (though they can be safely used together and can result in better CSS performance when done correctly).
|
|
50
|
-
|
|
51
|
-
### Some notes and suggestions
|
|
52
|
-
|
|
53
|
-
- Please combine this with our [xcss](/components/primitives/xcss) when available as this uses our media queries to allow for safe, responsive styling.
|
|
@@ -23,21 +23,20 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
23
23
|
|
|
24
24
|
## Basic
|
|
25
25
|
|
|
26
|
-
Stack
|
|
27
|
-
Use the given props to configure display behaviour using
|
|
26
|
+
Stack should be used to efficiently lay-out a group of elements vertically.
|
|
27
|
+
Use the given props to configure display behaviour using designs tokens, as shown in the more complex examples below.
|
|
28
28
|
|
|
29
29
|
<Example Component={StackBasic} packageName="@atlaskit/primitives/stack" />
|
|
30
30
|
|
|
31
31
|
## Space
|
|
32
32
|
|
|
33
|
-
Spacing between items can be controlled with the `space` prop
|
|
33
|
+
Spacing between items can be controlled with the `space` prop.
|
|
34
34
|
|
|
35
35
|
<Example Component={StackSpaceBasic} packageName="@atlaskit/primitives/stack" />
|
|
36
36
|
|
|
37
37
|
## Alignment
|
|
38
38
|
|
|
39
|
-
To control the alignment of items you can use the `alignBlock` and `alignInline` props which control
|
|
40
|
-
alignment in the block and inline directions respectively.
|
|
39
|
+
To control the alignment of items you can use the `alignBlock` and `alignInline` props which control alignment in the vertical and horizontal axis respectively.
|
|
41
40
|
|
|
42
41
|
### Block alignment
|
|
43
42
|
|
|
@@ -49,13 +48,13 @@ alignment in the block and inline directions respectively.
|
|
|
49
48
|
|
|
50
49
|
## Spread
|
|
51
50
|
|
|
52
|
-
Elements can be set to stay together
|
|
51
|
+
Elements can be set to stay together, spaced at the given value (default behaviour) or spread equally in the space available.
|
|
53
52
|
|
|
54
53
|
<Example Component={StackSpread} packageName="@atlaskit/primitives/stack" />
|
|
55
54
|
|
|
56
55
|
## Width control
|
|
57
56
|
|
|
58
|
-
By default a `Stack` will have its width influenced by the context where it appears.
|
|
57
|
+
By default a `Stack` will have its width influenced by the context where it appears. To control the width the `grow` prop can be used with the values:
|
|
59
58
|
|
|
60
59
|
To control that the `grow` prop can be used with the values:
|
|
61
60
|
|
|
@@ -70,6 +69,6 @@ It's possible to control the rendered HTML element with the `as` prop.
|
|
|
70
69
|
|
|
71
70
|
<Example Component={StackAs} packageName="@atlaskit/primitives/stack" />
|
|
72
71
|
|
|
73
|
-
## Practical
|
|
72
|
+
## Practical use case
|
|
74
73
|
|
|
75
74
|
<Example Component={PracticalUseCase} packageName="@atlaskit/primitives/stack" />
|
|
@@ -4,9 +4,9 @@ description: Stack is a primitive component based on flexbox that manages the ve
|
|
|
4
4
|
order: 2
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
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.
|
|
7
|
+
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.
|
|
8
8
|
|
|
9
|
-
`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.
|
|
9
|
+
`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.
|
|
10
10
|
|
|
11
11
|
In its simplest form, `Stack` operates like a flexbox column, however adds the built in design token support and guidance.
|
|
12
12
|
|
|
@@ -17,7 +17,7 @@ In its simplest form, `Stack` operates like a flexbox column, however adds the b
|
|
|
17
17
|
```
|
|
18
18
|
|
|
19
19
|
## Use `Stack`
|
|
20
|
-
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.
|
|
20
|
+
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.
|
|
21
21
|
|
|
22
22
|
The various `Stack` props can then be used to customize the spacing and styling on any child elements. These include:
|
|
23
23
|
- `alignBlock`
|
|
@@ -27,5 +27,9 @@ The various `Stack` props can then be used to customize the spacing and styling
|
|
|
27
27
|
- `space`
|
|
28
28
|
|
|
29
29
|
## Related
|
|
30
|
-
- [Learn more about the
|
|
31
|
-
- [Learn more about the
|
|
30
|
+
- [Learn more about the Primitives](/components/primitives/overview)
|
|
31
|
+
- [Learn more about the Box primitive](/components/primitives/box/usage)
|
|
32
|
+
- [Learn more about the Inline primitive](/components/primitives/inline/usage)
|
|
33
|
+
- [Learn more about the Grid primitive](/components/primitives/grid/examples)
|
|
34
|
+
- [Learn more about the Bleed primitive](/components/primitives/bleed/examples)
|
|
35
|
+
- [Learn more about the Flex primitive](/components/primitives/flex/examples)
|
|
@@ -18,7 +18,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
18
18
|
|
|
19
19
|
## Basic
|
|
20
20
|
|
|
21
|
-
`xcss` can pull together different types of interactions and UI in a safer more composable way.
|
|
21
|
+
`xcss` can pull together different types of interactions and UI in a safer, more composable way.
|
|
22
22
|
|
|
23
23
|
<Example Component={xcssBasic} packageName="@atlaskit/primitives/xcss" />
|
|
24
24
|
|
|
@@ -31,6 +31,6 @@ To enable interactivity, use familiar selectors like `:hover` and `:focus-visibl
|
|
|
31
31
|
|
|
32
32
|
## Responsiveness
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
xCSS also accepts a subset of media queries at [predefined breakpoints](/components/primitives/responsive/breakpoints/examples).
|
|
35
35
|
|
|
36
36
|
<Example Component={xcssResponsive} packageName="@atlaskit/primitives/xcss" />
|
|
Binary file
|
|
@@ -105,7 +105,7 @@ const someStyles = xcss({
|
|
|
105
105
|
#### Moving from the `styled` API
|
|
106
106
|
|
|
107
107
|
If currently using the `styled` API there are a few steps to migrate.
|
|
108
|
-
The safest approach is to
|
|
108
|
+
The safest approach is to use object styles, migrate to tokens (optionally) and then migrate to `xcss`.
|
|
109
109
|
|
|
110
110
|
```tsx
|
|
111
111
|
const MyComponent = styled.div`
|
|
@@ -51,7 +51,7 @@ const MyBox = () => {
|
|
|
51
51
|
```
|
|
52
52
|
The `xcss` prop and the `xcss` function are direct complements and are designed to be used together.
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
It is important to note that styles generated from `xcss` cannot be applied directly to the `className` property or `css` as they are with other CSS-in-JS libraries.
|
|
55
55
|
|
|
56
56
|
### Type safety
|
|
57
57
|
|
|
@@ -78,13 +78,6 @@ const someStyles = xcss({
|
|
|
78
78
|
Selectors cannot be nested or target elements beyond the element on which styles are applied.
|
|
79
79
|
This restriction is intended to encourage better component encapsulation, reduce side-effects and make the codebase more resilient to change.
|
|
80
80
|
|
|
81
|
-
|
|
82
|
-
`xcss` is meant to be flexible enough for you to implement any design but it does
|
|
83
|
-
restrict the application of styles in one key way. Selectors cannot be
|
|
84
|
-
nested or target elements beyond the element on which styles are applied.
|
|
85
|
-
This restriction is intended to encourage better component encapsulation, reduce side-effects and make
|
|
86
|
-
your codebase more resilient to change.
|
|
87
|
-
|
|
88
81
|
```tsx
|
|
89
82
|
import { xcss } from '@atlaskit/primitives';
|
|
90
83
|
|
|
@@ -109,6 +102,7 @@ For richer examples of how to use `xcss` please see the [primitives `xcss` docum
|
|
|
109
102
|
|
|
110
103
|
### Media Queries
|
|
111
104
|
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:
|
|
105
|
+
|
|
112
106
|
<MediaQueriesTable />
|
|
113
107
|
|
|
114
108
|
Media queries can be applied through keys that can be imported from `@atlaskit/primitives/responsive`.
|
|
@@ -18,7 +18,9 @@ var defaultStyles = (0, _react2.css)({
|
|
|
18
18
|
});
|
|
19
19
|
|
|
20
20
|
/**
|
|
21
|
-
*
|
|
21
|
+
* __UNSAFE_PRESSABLE__
|
|
22
|
+
*
|
|
23
|
+
* @internal Still under development. Do not use.
|
|
22
24
|
*
|
|
23
25
|
* A Pressable is a primitive component that renders a `<button>`.
|
|
24
26
|
*
|
|
@@ -26,7 +28,7 @@ var defaultStyles = (0, _react2.css)({
|
|
|
26
28
|
* - [Code](https://atlassian.design/components/primitives/pressable/code)
|
|
27
29
|
* - [Usage](https://atlassian.design/components/primitives/pressable/usage)
|
|
28
30
|
*/
|
|
29
|
-
var
|
|
31
|
+
var UNSAFE_PRESSABLE = /*#__PURE__*/(0, _react.forwardRef)(function (_ref, ref) {
|
|
30
32
|
var children = _ref.children,
|
|
31
33
|
backgroundColor = _ref.backgroundColor,
|
|
32
34
|
padding = _ref.padding,
|
|
@@ -58,5 +60,5 @@ var Pressable = /*#__PURE__*/(0, _react.forwardRef)(function (_ref, ref) {
|
|
|
58
60
|
disabled: isDisabled
|
|
59
61
|
}), children));
|
|
60
62
|
});
|
|
61
|
-
var _default =
|
|
63
|
+
var _default = UNSAFE_PRESSABLE;
|
|
62
64
|
exports.default = _default;
|
package/dist/cjs/index.js
CHANGED
|
@@ -34,12 +34,6 @@ Object.defineProperty(exports, "Inline", {
|
|
|
34
34
|
return _inline.default;
|
|
35
35
|
}
|
|
36
36
|
});
|
|
37
|
-
Object.defineProperty(exports, "Pressable", {
|
|
38
|
-
enumerable: true,
|
|
39
|
-
get: function get() {
|
|
40
|
-
return _pressable.default;
|
|
41
|
-
}
|
|
42
|
-
});
|
|
43
37
|
Object.defineProperty(exports, "Stack", {
|
|
44
38
|
enumerable: true,
|
|
45
39
|
get: function get() {
|
|
@@ -71,7 +65,6 @@ Object.defineProperty(exports, "xcss", {
|
|
|
71
65
|
}
|
|
72
66
|
});
|
|
73
67
|
var _box = _interopRequireDefault(require("./components/box"));
|
|
74
|
-
var _pressable = _interopRequireDefault(require("./components/pressable"));
|
|
75
68
|
var _inline = _interopRequireDefault(require("./components/inline"));
|
|
76
69
|
var _xcss = require("./xcss/xcss");
|
|
77
70
|
var _stack = _interopRequireDefault(require("./components/stack"));
|
package/dist/cjs/version.json
CHANGED
package/dist/cjs/xcss/xcss.js
CHANGED
|
@@ -10,7 +10,6 @@ var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/de
|
|
|
10
10
|
var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
|
|
11
11
|
var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
|
|
12
12
|
var _react = require("@emotion/react");
|
|
13
|
-
var _mediaHelper = require("../responsive/media-helper");
|
|
14
13
|
var _styleMaps = require("./style-maps.partial");
|
|
15
14
|
/* eslint-disable @atlaskit/design-system/ensure-design-token-usage */
|
|
16
15
|
|
|
@@ -75,16 +74,7 @@ var isSafeEnvToThrow = function isSafeEnvToThrow() {
|
|
|
75
74
|
return (typeof process === "undefined" ? "undefined" : (0, _typeof2.default)(process)) === 'object' && (0, _typeof2.default)(process.env) === 'object' && process.env.NODE_ENV !== 'production';
|
|
76
75
|
};
|
|
77
76
|
var reNestedSelectors = /(\.|\s|&+|\*\>|#|\[.*\])/;
|
|
78
|
-
var
|
|
79
|
-
var reMediaQuery = /^@media .*$/;
|
|
80
|
-
|
|
81
|
-
/**
|
|
82
|
-
* Reduce our media queries into a safe string for regex comparison.
|
|
83
|
-
*/
|
|
84
|
-
var reValidMediaQuery = new RegExp("^(".concat(Object.values(_mediaHelper.media.above).map(function (mediaQuery) {
|
|
85
|
-
return mediaQuery.replace(/[.()]/g, '\\$&');
|
|
86
|
-
} // Escape the ".", "(", and ")" in the media query syntax.
|
|
87
|
-
).join('|'), ")$"));
|
|
77
|
+
var safeSelectors = /^@media .*$|^::?.*$|^@supports .*$/;
|
|
88
78
|
var transformStyles = function transformStyles(styleObj) {
|
|
89
79
|
if (!styleObj || (0, _typeof2.default)(styleObj) !== 'object') {
|
|
90
80
|
return styleObj;
|
|
@@ -100,23 +90,17 @@ var transformStyles = function transformStyles(styleObj) {
|
|
|
100
90
|
var _ref2 = (0, _slicedToArray2.default)(_ref, 2),
|
|
101
91
|
key = _ref2[0],
|
|
102
92
|
value = _ref2[1];
|
|
103
|
-
if (isSafeEnvToThrow()) {
|
|
104
|
-
// We don't support `.class`, `[data-testid]`, `> *`, `#some-id`
|
|
105
|
-
if (reNestedSelectors.test(key) && !reValidMediaQuery.test(key)) {
|
|
106
|
-
throw new Error("Styles not supported for key '".concat(key, "'."));
|
|
107
|
-
}
|
|
108
|
-
}
|
|
109
|
-
|
|
110
93
|
// If key is a pseudo class or a pseudo element, then value should be an object.
|
|
111
94
|
// So, call transformStyles on the value
|
|
112
|
-
if (
|
|
95
|
+
if ((0, _typeof2.default)(value) === 'object' && safeSelectors.test(key)) {
|
|
113
96
|
styleObj[key] = transformStyles(value);
|
|
114
97
|
return;
|
|
115
98
|
}
|
|
116
|
-
if (
|
|
117
|
-
//
|
|
118
|
-
|
|
119
|
-
|
|
99
|
+
if (isSafeEnvToThrow()) {
|
|
100
|
+
// We don't support `.class`, `[data-testid]`, `> *`, `#some-id`
|
|
101
|
+
if (reNestedSelectors.test(key)) {
|
|
102
|
+
throw new Error("Styles not supported for key '".concat(key, "'."));
|
|
103
|
+
}
|
|
120
104
|
}
|
|
121
105
|
|
|
122
106
|
// We have now dealt with all the special cases, so,
|
|
@@ -157,13 +141,6 @@ var parseXcss = function parseXcss(args) {
|
|
|
157
141
|
|
|
158
142
|
// Pseudos should not contain nested pseudos, or media queries
|
|
159
143
|
exports.parseXcss = parseXcss;
|
|
160
|
-
// unused private functions only so we can extract the return type from a generic function
|
|
161
|
-
var boxWrapper = function boxWrapper(style) {
|
|
162
|
-
return xcss(style);
|
|
163
|
-
};
|
|
164
|
-
var spaceWrapper = function spaceWrapper(style) {
|
|
165
|
-
return xcss(style);
|
|
166
|
-
};
|
|
167
144
|
/**
|
|
168
145
|
* ### xcss
|
|
169
146
|
*
|
|
@@ -9,7 +9,9 @@ const defaultStyles = css({
|
|
|
9
9
|
});
|
|
10
10
|
|
|
11
11
|
/**
|
|
12
|
-
*
|
|
12
|
+
* __UNSAFE_PRESSABLE__
|
|
13
|
+
*
|
|
14
|
+
* @internal Still under development. Do not use.
|
|
13
15
|
*
|
|
14
16
|
* A Pressable is a primitive component that renders a `<button>`.
|
|
15
17
|
*
|
|
@@ -17,7 +19,7 @@ const defaultStyles = css({
|
|
|
17
19
|
* - [Code](https://atlassian.design/components/primitives/pressable/code)
|
|
18
20
|
* - [Usage](https://atlassian.design/components/primitives/pressable/usage)
|
|
19
21
|
*/
|
|
20
|
-
const
|
|
22
|
+
const UNSAFE_PRESSABLE = /*#__PURE__*/forwardRef(({
|
|
21
23
|
children,
|
|
22
24
|
backgroundColor,
|
|
23
25
|
padding,
|
|
@@ -49,4 +51,4 @@ const Pressable = /*#__PURE__*/forwardRef(({
|
|
|
49
51
|
disabled: isDisabled
|
|
50
52
|
}), children));
|
|
51
53
|
});
|
|
52
|
-
export default
|
|
54
|
+
export default UNSAFE_PRESSABLE;
|
package/dist/es2019/index.js
CHANGED
package/dist/es2019/version.json
CHANGED