Skip to content

Commit a8d80cf

Browse files
chazdeanlaurkim
chazdean
and
laurkim
authored
[Layout foundations] Update AlphaStack component docs and guidance (#7469)
<!-- ☝️How to write a good PR title: - Prefix it with [ComponentName] (if applicable), for example: [Button] - Start with a verb, for example: Add, Delete, Improve, Fix… - Give as much context as necessary and as little as possible - Prefix it with [WIP] while it’s a work in progress --> ### WHY are these changes introduced? Fixes #6904 <!-- link to issue if one exists --> <!-- Context about the problem that’s being addressed. --> ### WHAT is this pull request doing? Updates the `AlphaStack` component docs and guidance ## Examples: ### Default <img width="716" alt="Screen Shot 2022-10-21 at 2 52 38 PM" src="https://user-images.githubusercontent.com/59836805/197200620-ef6b078d-ece3-47b0-889f-429ede170d81.png"> ```jsx function AlphaStackExample() { return ( <AlphaStack> <Placeholder width="320" label="Stack child" /> <Placeholder width="320" /> <Placeholder width="320" /> </AlphaStack> ); } ``` ### Spacing <img width="690" alt="Screen Shot 2022-10-24 at 9 10 18 AM" src="https://user-images.githubusercontent.com/59836805/197535998-baf98888-835d-4fcd-9466-c394ae46a0fe.png"> ```jsx function AlphaStackWithSpacingExample() { return ( <SpacingBackground width="320"> <AlphaStack spacing="5"> <Placeholder width="320" label="Stack child" /> <Placeholder width="320" /> <Placeholder width="320" /> </AlphaStack> </SpacingBackground> ); } ``` ### Full width <img width="707" alt="Screen Shot 2022-10-21 at 2 53 11 PM" src="https://user-images.githubusercontent.com/59836805/197200701-3e5d0226-ea51-4382-b1f4-1b331e20f20c.png"> ```jsx function AlphaStackWithFullWidthChildrenExample() { return ( <AlphaStack fullWidth> <Placeholder label="Stack child" childWidth="100%" /> <Placeholder /> <Placeholder /> </AlphaStack> ); } ``` #### Alignment <img width="528" alt="Screen Shot 2022-10-21 at 2 53 37 PM" src="https://user-images.githubusercontent.com/59836805/197200741-0ced8206-496d-4419-9807-89d0d34d6c98.png"> ```jsx function AlphaStackWithAlignExample() { return ( <Page> <Box paddingBottom="20"> <AlphaStack align="start"> <Placeholder width="320" label="Start" childAlign="start" /> <Placeholder width="320" /> <Placeholder width="320" /> </AlphaStack> </Box> <Box paddingBottom="20"> <AlphaStack align="center"> <AlphaStack> <Placeholder width="320" label="Center" childAlign="center" /> <Placeholder width="320" /> <Placeholder width="320" /> </AlphaStack> </AlphaStack> </Box> <Box> <AlphaStack align="end"> <Placeholder width="320" label="End" childAlign="end" /> <Placeholder width="320" /> <Placeholder width="320" /> </AlphaStack> </Box> </Page> ); } ``` <!-- Summary of the changes committed. Before / after screenshots are appreciated for UI changes. Make sure to include alt text that describes the screenshot. If you include an animated gif showing your change, wrapping it in a details tag is recommended. Gifs usually autoplay, which can cause accessibility issues for people reviewing your PR: <details> <summary>Summary of your gif(s)</summary> <img src="..." alt="Description of what the gif shows"> </details> --> <!-- ℹ️ Delete the following for small / trivial changes --> ### 🎩 checklist - [ ] Tested on [mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing) - [ ] Tested on [multiple browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers) - [ ] Tested for [accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md) - [ ] Updated the component's `README.md` with documentation changes - [ ] [Tophatted documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md) changes in the style guide Co-authored-by: Lo Kim <[email protected]>
1 parent e87330f commit a8d80cf

File tree

6 files changed

+193
-130
lines changed

6 files changed

+193
-130
lines changed

‎.changeset/heavy-eagles-train.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'polaris.shopify.com': patch
3+
---
4+
5+
Updated `AlphaStack` component docs

‎polaris.shopify.com/content/components/alpha-stack.md‎

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Alpha stack
3-
description: Use to lay out a vertical pile of elements sitting on top of each other. A stack is made of flexible items that wrap each of the stack’s children. Options allow different spacing and alignments.
3+
description: Use to display elements vertically with items placed directly below the preceding item.
44
category: Structure
55
keywords:
66
- layout
@@ -10,16 +10,22 @@ status:
1010
examples:
1111
- fileName: alpha-stack-default.tsx
1212
title: Default
13-
- fileName: alpha-stack-with-align.tsx
14-
title: Horizontal alignment
1513
description: >-
16-
Horizontal alignment for children can be set with the align property.
14+
By default, stack is left aligned and stacked items are spaced with 16px in between.
1715
- fileName: alpha-stack-with-spacing.tsx
18-
title: Vertical spacing
16+
title: Spacing
1917
description: >-
20-
Vertical spacing for children can be set with the spacing property. Spacing options are provided using our spacing tokens.
18+
Spacing between stack child can be adjusted using the Space token.
2119
- fileName: alpha-stack-with-full-width-children.tsx
22-
title: Full width children
20+
title: Full width
21+
description: >-
22+
Use a boolean to make Stack full width.
23+
- fileName: alpha-stack-with-align.tsx
24+
title: Alignment
2325
description: >-
24-
Set children to full width
26+
Use to vertically align Stack.
2527
---
28+
29+
## Related components
30+
31+
- To display elements horizontally, use [Inline](https://polaris.shopify.com/components/inline).

‎polaris.shopify.com/pages/examples/alpha-stack-default.tsx‎

Lines changed: 36 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,47 @@
11
import React from 'react';
2-
import {AlphaStack, Badge, Text} from '@shopify/polaris';
2+
import {AlphaStack, Text} from '@shopify/polaris';
33

44
import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
55

66
function AlphaStackExample() {
77
return (
8-
<div style={{width: '100%'}}>
9-
<AlphaStack>
10-
<Text variant="heading4xl" as="h2">
11-
AlphaStack
8+
<AlphaStack>
9+
<Placeholder width="320px" label="Stack child" />
10+
<Placeholder width="320px" />
11+
<Placeholder width="320px" />
12+
</AlphaStack>
13+
);
14+
}
15+
16+
const Placeholder = ({
17+
label = '',
18+
height = 'auto',
19+
width = 'auto',
20+
childWidth = 'auto',
21+
}) => {
22+
return (
23+
<div
24+
style={{
25+
background: '#7B47F1',
26+
padding: '14px var(--p-space-2)',
27+
height: height ?? undefined,
28+
width: width ?? undefined,
29+
}}
30+
>
31+
<div
32+
style={{
33+
display: 'inline-block',
34+
background: 'rgba(255, 255, 255, 0.3)',
35+
color: '#FFFFFF',
36+
width: childWidth ?? undefined,
37+
}}
38+
>
39+
<Text as="h2" variant="bodyMd" fontWeight="medium">
40+
{label}
1241
</Text>
13-
<Badge>One</Badge>
14-
<Badge>Two</Badge>
15-
<Badge>Three</Badge>
16-
</AlphaStack>
42+
</div>
1743
</div>
1844
);
19-
}
45+
};
2046

2147
export default withPolarisExample(AlphaStackExample);

‎polaris.shopify.com/pages/examples/alpha-stack-with-align.tsx‎

Lines changed: 49 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,68 @@
11
import React from 'react';
2-
import {AlphaStack, Badge, Box, Inline, Text} from '@shopify/polaris';
2+
import {AlphaStack, Box, Page, Inline, Text} from '@shopify/polaris';
33

44
import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
55

66
function AlphaStackWithAlignExample() {
77
return (
8-
<div style={{width: '100%'}}>
9-
<Box paddingBottom="2">
10-
<Text variant="bodySm" as="h3">
11-
with align start
12-
</Text>
13-
</Box>
14-
<Box paddingBottom="2">
8+
<Page>
9+
<Box paddingBottom="20">
1510
<AlphaStack align="start">
16-
<Text variant="heading4xl" as="h2">
17-
AlphaStack
18-
</Text>
19-
<Inline>
20-
<Badge>One</Badge>
21-
<Badge>Two</Badge>
22-
<Badge>Three</Badge>
23-
</Inline>
11+
<Placeholder width="320px" label="Start" childAlign="start" />
12+
<Placeholder width="320px" childAlign="start" />
13+
<Placeholder width="320px" childAlign="start" />
2414
</AlphaStack>
2515
</Box>
26-
<hr />
27-
<Box paddingBottom="2">
28-
<Text variant="bodySm" as="h3">
29-
with align center
30-
</Text>
31-
</Box>
32-
<Box paddingBottom="2">
16+
<Box paddingBottom="20">
3317
<AlphaStack align="center">
34-
<Text variant="heading4xl" as="h2">
35-
AlphaStack
36-
</Text>
37-
<Inline>
38-
<Badge>One</Badge>
39-
<Badge>Two</Badge>
40-
<Badge>Three</Badge>
41-
</Inline>
18+
<AlphaStack>
19+
<Placeholder width="320px" label="Center" childAlign="center" />
20+
<Placeholder width="320px" childAlign="center" />
21+
<Placeholder width="320px" childAlign="center" />
22+
</AlphaStack>
4223
</AlphaStack>
4324
</Box>
44-
<hr />
45-
<Box paddingBottom="2">
46-
<Text variant="bodySm" as="h3">
47-
with align end
48-
</Text>
49-
</Box>
50-
<Box paddingBottom="2">
25+
<Box>
5126
<AlphaStack align="end">
52-
<Text variant="heading4xl" as="h2">
53-
AlphaStack
54-
</Text>
55-
<Inline>
56-
<Badge>One</Badge>
57-
<Badge>Two</Badge>
58-
<Badge>Three</Badge>
59-
</Inline>
27+
<Placeholder width="320px" label="End" childAlign="end" />
28+
<Placeholder width="320px" childAlign="center" />
29+
<Placeholder width="320px" childAlign="center" />
6030
</AlphaStack>
6131
</Box>
62-
</div>
32+
</Page>
6333
);
6434
}
6535

36+
const Placeholder = ({
37+
label = '',
38+
height = 'auto',
39+
width = 'auto',
40+
childAlign,
41+
}) => {
42+
return (
43+
<div
44+
style={{
45+
background: '#7B47F1',
46+
padding: '14px var(--p-space-2)',
47+
height: height ?? undefined,
48+
width: width ?? undefined,
49+
}}
50+
>
51+
<Inline align={childAlign}>
52+
<div
53+
style={{
54+
display: 'inline-block',
55+
background: 'rgba(255, 255, 255, 0.3)',
56+
color: '#FFFFFF',
57+
}}
58+
>
59+
<Text as="h2" variant="bodyMd" fontWeight="medium">
60+
{label}
61+
</Text>
62+
</div>
63+
</Inline>
64+
</div>
65+
);
66+
};
67+
6668
export default withPolarisExample(AlphaStackWithAlignExample);

‎polaris.shopify.com/pages/examples/alpha-stack-with-full-width-children.tsx‎

Lines changed: 36 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,47 @@
11
import React from 'react';
2-
import {AlphaStack, Badge, Text} from '@shopify/polaris';
2+
import {AlphaStack, Text} from '@shopify/polaris';
33

44
import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
55

66
function AlphaStackWithFullWidthChildrenExample() {
77
return (
8-
<div style={{width: '100%'}}>
9-
<AlphaStack fullWidth>
10-
<Text variant="heading4xl" as="h2">
11-
AlphaStack
8+
<AlphaStack fullWidth>
9+
<Placeholder label="Stack child" childWidth="100%" />
10+
<Placeholder />
11+
<Placeholder />
12+
</AlphaStack>
13+
);
14+
}
15+
16+
const Placeholder = ({
17+
label = '',
18+
height = 'auto',
19+
width = '100%',
20+
childWidth = 'auto',
21+
}) => {
22+
return (
23+
<div
24+
style={{
25+
background: '#7B47F1',
26+
padding: '14px var(--p-space-2)',
27+
height: height ?? undefined,
28+
width: width ?? undefined,
29+
}}
30+
>
31+
<div
32+
style={{
33+
display: 'inline-block',
34+
background: 'rgba(255, 255, 255, 0.3)',
35+
color: '#FFFFFF',
36+
width: childWidth ?? undefined,
37+
}}
38+
>
39+
<Text as="h2" variant="bodyMd" fontWeight="medium">
40+
{label}
1241
</Text>
13-
<Badge>One</Badge>
14-
<Badge>Two</Badge>
15-
<Badge>Three</Badge>
16-
</AlphaStack>
42+
</div>
1743
</div>
1844
);
19-
}
45+
};
2046

2147
export default withPolarisExample(AlphaStackWithFullWidthChildrenExample);

‎polaris.shopify.com/pages/examples/alpha-stack-with-spacing.tsx‎

Lines changed: 53 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,64 @@
11
import React from 'react';
2-
import {AlphaStack, Badge, Box, Inline, Text} from '@shopify/polaris';
2+
import {AlphaStack, Text} from '@shopify/polaris';
33

44
import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
55

66
function AlphaStackWithSpacingExample() {
77
return (
8-
<div style={{width: '100%'}}>
9-
<Box paddingBottom="2">
10-
<Text variant="bodySm" as="h3">
11-
with spacing 0
12-
</Text>
13-
</Box>
14-
<Box paddingBottom="2">
15-
<AlphaStack spacing="0">
16-
<Text variant="heading4xl" as="h2">
17-
AlphaStack
18-
</Text>
19-
<Inline>
20-
<Badge>One</Badge>
21-
<Badge>Two</Badge>
22-
<Badge>Three</Badge>
23-
</Inline>
24-
</AlphaStack>
25-
</Box>
26-
<hr />
27-
<Box paddingBottom="2">
28-
<Text variant="bodySm" as="h3">
29-
with spacing 4
30-
</Text>
31-
</Box>
32-
<Box paddingBottom="2">
33-
<AlphaStack spacing="4">
34-
<Text variant="heading4xl" as="h2">
35-
AlphaStack
36-
</Text>
37-
<Inline>
38-
<Badge>One</Badge>
39-
<Badge>Two</Badge>
40-
<Badge>Three</Badge>
41-
</Inline>
42-
</AlphaStack>
43-
</Box>
44-
<hr />
45-
<Box paddingBottom="2">
46-
<Text variant="bodySm" as="h3">
47-
with spacing 10
8+
<SpacingBackground width="320px">
9+
<AlphaStack spacing="5">
10+
<Placeholder width="320px" label="Stack child" />
11+
<Placeholder width="320px" />
12+
<Placeholder width="320px" />
13+
</AlphaStack>
14+
</SpacingBackground>
15+
);
16+
}
17+
18+
const SpacingBackground = ({children, width}) => {
19+
return (
20+
<div
21+
style={{
22+
background:
23+
'repeating-linear-gradient(-45deg, #7B47F1, #7B47F1 1px, #E8D1FA 1px, #E8D1FA 7px)',
24+
width: width ?? '100%',
25+
height: 'auto',
26+
}}
27+
>
28+
{children}
29+
</div>
30+
);
31+
};
32+
33+
const Placeholder = ({
34+
label = '',
35+
height = 'auto',
36+
width = 'auto',
37+
childWidth = 'auto',
38+
}) => {
39+
return (
40+
<div
41+
style={{
42+
background: '#7B47F1',
43+
padding: '14px var(--p-space-2)',
44+
height: height ?? undefined,
45+
width: width ?? undefined,
46+
}}
47+
>
48+
<div
49+
style={{
50+
display: 'inline-block',
51+
background: 'rgba(255, 255, 255, 0.3)',
52+
color: '#FFFFFF',
53+
width: childWidth ?? undefined,
54+
}}
55+
>
56+
<Text as="h2" variant="bodyMd" fontWeight="medium">
57+
{label}
4858
</Text>
49-
</Box>
50-
<Box paddingBottom="2">
51-
<AlphaStack spacing="10">
52-
<Text variant="heading4xl" as="h2">
53-
AlphaStack
54-
</Text>
55-
<Inline>
56-
<Badge>One</Badge>
57-
<Badge>Two</Badge>
58-
<Badge>Three</Badge>
59-
</Inline>
60-
</AlphaStack>
61-
</Box>
59+
</div>
6260
</div>
6361
);
64-
}
62+
};
6563

6664
export default withPolarisExample(AlphaStackWithSpacingExample);

0 commit comments

Comments
 (0)