@workday/canvas-kit-docs 6.9.0-next.0 → 6.9.0-next.2

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.
Files changed (190) hide show
  1. package/dist/commonjs/index.js +13 -6
  2. package/dist/commonjs/lib/Specifications.d.ts.map +1 -1
  3. package/dist/commonjs/lib/Specifications.js +3 -1
  4. package/dist/commonjs/lib/docs.js +1 -0
  5. package/dist/commonjs/lib/specs.js +259 -6
  6. package/dist/es6/lib/Specifications.d.ts.map +1 -1
  7. package/dist/es6/lib/specs.js +259 -6
  8. package/dist/mdx/{4.0-MIGRATION-GUIDE.mdx → 4.0-UPGRADE-GUIDE.mdx} +1 -1
  9. package/dist/mdx/{5.0-MIGRATION-GUIDE.mdx → 5.0-UPGRADE-GUIDE.mdx} +3 -3
  10. package/dist/mdx/{6.0-MIGRATION-GUIDE.mdx → 6.0-UPGRADE-GUIDE.mdx} +4 -4
  11. package/dist/mdx/7.0-UPGRADE-GUIDE.mdx +1006 -0
  12. package/dist/mdx/COMPOUND_COMPONENTS.mdx +2 -2
  13. package/dist/mdx/CONTRIBUTING.mdx +2 -2
  14. package/dist/mdx/TESTING.mdx +1 -1
  15. package/dist/mdx/changelog.stories.mdx +1 -0
  16. package/dist/mdx/labs-react/search-form/examples/Basic.tsx +4 -2
  17. package/dist/mdx/labs-react/search-form/examples/CustomTheme.tsx +4 -2
  18. package/dist/mdx/labs-react/search-form/examples/Grow.tsx +4 -2
  19. package/dist/mdx/labs-react/search-form/examples/RTL.tsx +4 -2
  20. package/dist/mdx/labs-react/search-form/examples/Theming.tsx +4 -2
  21. package/dist/mdx/preview-react/_examples/SidePanelWithOverlay.mdx +8 -0
  22. package/dist/mdx/preview-react/_examples/examples/SidePanelWithOverlay.tsx +31 -0
  23. package/dist/mdx/preview-react/_examples/examples/TextInputWithFormik.tsx +3 -3
  24. package/dist/mdx/preview-react/form-field/examples/Custom.tsx +4 -5
  25. package/dist/mdx/preview-react/menu/Menu.mdx +1 -1
  26. package/dist/mdx/preview-react/menu/examples/ContextMenu.tsx +2 -2
  27. package/dist/mdx/preview-react/menu/examples/Icons.tsx +0 -1
  28. package/dist/mdx/preview-react/pill/Pill.mdx +241 -0
  29. package/dist/mdx/preview-react/pill/examples/Basic.tsx +18 -0
  30. package/dist/mdx/preview-react/pill/examples/WithAvatar.tsx +21 -0
  31. package/dist/mdx/preview-react/pill/examples/WithCount.tsx +9 -0
  32. package/dist/mdx/preview-react/pill/examples/WithList.tsx +31 -0
  33. package/dist/mdx/preview-react/pill/examples/WithReadOnly.tsx +15 -0
  34. package/dist/mdx/preview-react/pill/examples/WithRemovable.tsx +25 -0
  35. package/dist/mdx/preview-react/pill/examples/test-avatar.png +0 -0
  36. package/dist/mdx/preview-react/side-panel/SidePanel.mdx +5 -3
  37. package/dist/mdx/preview-react/side-panel/examples/AlwaysOpen.tsx +16 -22
  38. package/dist/mdx/preview-react/side-panel/examples/Basic.tsx +9 -14
  39. package/dist/mdx/preview-react/side-panel/examples/ExternalControl.tsx +9 -13
  40. package/dist/mdx/preview-react/side-panel/examples/HiddenName.tsx +1 -1
  41. package/dist/mdx/preview-react/side-panel/examples/OnExpandedChange.tsx +1 -1
  42. package/dist/mdx/preview-react/side-panel/examples/OnStateTransition.tsx +1 -1
  43. package/dist/mdx/preview-react/side-panel/examples/RightOrigin.tsx +17 -24
  44. package/dist/mdx/preview-react/side-panel/examples/Variant.tsx +9 -14
  45. package/dist/mdx/preview-react/text-area/examples/Alert.tsx +2 -1
  46. package/dist/mdx/preview-react/text-area/examples/HiddenLabel.tsx +6 -4
  47. package/dist/mdx/preview-react/text-area/examples/RefForwarding.tsx +1 -1
  48. package/dist/mdx/preview-react/text-input/examples/Alert.tsx +2 -1
  49. package/dist/mdx/preview-react/text-input/examples/HiddenLabel.tsx +6 -4
  50. package/dist/mdx/preview-react/text-input/examples/RefForwarding.tsx +1 -1
  51. package/dist/mdx/preview-react/text-input/examples/ThemedAlert.tsx +2 -1
  52. package/dist/mdx/react/_examples/SegmentedControlWithText.mdx +12 -0
  53. package/dist/mdx/react/_examples/examples/GlobalHeader.tsx +7 -6
  54. package/dist/mdx/react/_examples/examples/PageHeader.tsx +5 -5
  55. package/dist/mdx/react/_examples/examples/SegmentControlWithText.tsx +119 -0
  56. package/dist/mdx/react/action-bar/ActionBar.mdx +126 -23
  57. package/dist/mdx/react/action-bar/examples/Basic.tsx +7 -4
  58. package/dist/mdx/react/action-bar/examples/DeleteAction.tsx +15 -0
  59. package/dist/mdx/react/action-bar/examples/Icons.tsx +18 -0
  60. package/dist/mdx/react/action-bar/examples/OverflowActionBar.tsx +59 -0
  61. package/dist/mdx/react/banner/Banner.mdx +203 -19
  62. package/dist/mdx/react/banner/PropTables.splitprops.tsx +39 -0
  63. package/dist/mdx/react/banner/examples/ActionText.tsx +8 -1
  64. package/dist/mdx/react/banner/examples/Basic.tsx +8 -1
  65. package/dist/mdx/react/banner/examples/Error.tsx +8 -1
  66. package/dist/mdx/react/banner/examples/RefForwarding.tsx +25 -0
  67. package/dist/mdx/react/banner/examples/Sticky.tsx +12 -7
  68. package/dist/mdx/react/banner/examples/StickyAnimation.tsx +64 -0
  69. package/dist/mdx/react/banner/examples/StickyRTL.tsx +35 -0
  70. package/dist/mdx/react/banner/examples/ThemedAlert.tsx +28 -0
  71. package/dist/mdx/react/banner/examples/ThemedError.tsx +29 -0
  72. package/dist/mdx/react/button/button/Button.mdx +3 -3
  73. package/dist/mdx/react/button/button/Hyperlink.mdx +72 -0
  74. package/dist/mdx/react/button/button/examples/ExternalHyperlink.tsx +7 -0
  75. package/dist/mdx/react/button/button/examples/ExternalHyperlinkInverse.tsx +12 -0
  76. package/dist/mdx/react/button/button/examples/Hyperlink.tsx +5 -0
  77. package/dist/mdx/react/button/button/examples/HyperlinkInverse.tsx +12 -0
  78. package/dist/mdx/react/button/button/examples/Primary.tsx +11 -3
  79. package/dist/mdx/react/button/button/examples/PrimaryInverse.tsx +11 -3
  80. package/dist/mdx/react/button/button/examples/Secondary.tsx +11 -3
  81. package/dist/mdx/react/button/button/examples/SecondaryInverse.tsx +11 -3
  82. package/dist/mdx/react/button/button/examples/Tertiary.tsx +9 -4
  83. package/dist/mdx/react/button/button/examples/TertiaryInverse.tsx +12 -3
  84. package/dist/mdx/react/card/card.mdx +2 -2
  85. package/dist/mdx/react/card/examples/Depth.tsx +1 -1
  86. package/dist/mdx/react/checkbox/Checkbox.mdx +7 -0
  87. package/dist/mdx/react/checkbox/examples/Indeterminate.tsx +1 -1
  88. package/dist/mdx/react/checkbox/examples/Inverse.tsx +22 -0
  89. package/dist/mdx/react/checkbox/examples/RefForwarding.tsx +1 -1
  90. package/dist/mdx/react/collection/Collection.mdx +358 -0
  91. package/dist/mdx/react/collection/Collection.splitprops.tsx +19 -0
  92. package/dist/mdx/react/collection/examples/Basic.tsx +12 -0
  93. package/dist/mdx/react/collection/examples/BasicGrid.tsx +46 -0
  94. package/dist/mdx/react/collection/examples/BasicVirtual.tsx +24 -0
  95. package/dist/mdx/react/collection/examples/DynamicItems.tsx +20 -0
  96. package/dist/mdx/react/collection/examples/IdentifiedItems.tsx +12 -0
  97. package/dist/mdx/react/collection/examples/MultiSelection.tsx +56 -0
  98. package/dist/mdx/react/collection/examples/RovingFocus.tsx +39 -0
  99. package/dist/mdx/react/collection/examples/Selection.tsx +58 -0
  100. package/dist/mdx/react/collection/examples/WrappingGrid.tsx +48 -0
  101. package/dist/mdx/react/color-picker/color-input/ColorInput.mdx +2 -2
  102. package/dist/mdx/react/color-picker/color-preview/ColorPreview.mdx +2 -2
  103. package/dist/mdx/{labs-react/common → react/layout}/Box.mdx +3 -6
  104. package/dist/mdx/{labs-react → react}/layout/Flex.mdx +24 -27
  105. package/dist/mdx/{labs-react → react}/layout/Stack.mdx +98 -146
  106. package/dist/mdx/{labs-react/common → react/layout}/examples/As.tsx +1 -1
  107. package/dist/mdx/{labs-react/common → react/layout}/examples/Border.tsx +1 -1
  108. package/dist/mdx/{labs-react/common → react/layout}/examples/Color.tsx +1 -1
  109. package/dist/mdx/{labs-react/common → react/layout}/examples/Depth.tsx +9 -3
  110. package/dist/mdx/{labs-react → react}/layout/examples/Flex/FlexCard.tsx +2 -3
  111. package/dist/mdx/{labs-react → react}/layout/examples/Flex/FlexLayout.tsx +1 -1
  112. package/dist/mdx/{labs-react → react}/layout/examples/Flex/Usage.tsx +2 -3
  113. package/dist/mdx/{labs-react/common → react/layout}/examples/FlexItem.tsx +1 -2
  114. package/dist/mdx/{labs-react/common → react/layout}/examples/Layout.tsx +1 -1
  115. package/dist/mdx/{labs-react/common → react/layout}/examples/Position.tsx +1 -1
  116. package/dist/mdx/{labs-react → react}/layout/examples/PropTables.splitprops.tsx +1 -1
  117. package/dist/mdx/{labs-react/common → react/layout}/examples/Ref.tsx +1 -1
  118. package/dist/mdx/{labs-react/common → react/layout}/examples/Space.tsx +1 -1
  119. package/dist/mdx/{labs-react → react}/layout/examples/Stack/BasicStack.tsx +1 -1
  120. package/dist/mdx/{labs-react → react}/layout/examples/Stack/HStackCards.tsx +2 -3
  121. package/dist/mdx/{labs-react → react}/layout/examples/Stack/NestedStacks.tsx +1 -1
  122. package/dist/mdx/react/layout/examples/Stack/ShouldWrapChildren.tsx +28 -0
  123. package/dist/mdx/{labs-react → react}/layout/examples/Stack/StackCard.tsx +2 -2
  124. package/dist/mdx/{labs-react → react}/layout/examples/Stack/StackItems.tsx +1 -2
  125. package/dist/mdx/{labs-react → react}/layout/examples/Stack/VStackCards.tsx +2 -2
  126. package/dist/mdx/react/menu/Menu.mdx +123 -0
  127. package/dist/mdx/react/menu/examples/Basic.tsx +26 -0
  128. package/dist/mdx/react/menu/examples/ContextMenu.tsx +25 -0
  129. package/dist/mdx/react/menu/examples/Icons.tsx +41 -0
  130. package/dist/mdx/react/modal/Modal.mdx +34 -11
  131. package/dist/mdx/react/modal/examples/Basic.tsx +4 -2
  132. package/dist/mdx/react/modal/examples/BodyOverflow.tsx +56 -0
  133. package/dist/mdx/react/modal/examples/CustomFocus.tsx +4 -2
  134. package/dist/mdx/react/modal/examples/FullOverflow.tsx +55 -0
  135. package/dist/mdx/react/modal/examples/ReturnFocus.tsx +5 -3
  136. package/dist/mdx/react/modal/examples/WithoutCloseIcon.tsx +4 -2
  137. package/dist/mdx/react/pagination/PropTables.splitprops.tsx +1 -1
  138. package/dist/mdx/react/pagination/pagination.mdx +14 -14
  139. package/dist/mdx/react/popup/Popup.mdx +2 -1
  140. package/dist/mdx/react/popup/examples/Basic.tsx +1 -1
  141. package/dist/mdx/react/popup/examples/FocusRedirect.tsx +3 -2
  142. package/dist/mdx/react/popup/examples/FocusTrap.tsx +1 -1
  143. package/dist/mdx/react/popup/examples/FullScreen.tsx +1 -1
  144. package/dist/mdx/react/popup/examples/InitialFocus.tsx +4 -2
  145. package/dist/mdx/react/popup/examples/MultiplePopups.tsx +1 -1
  146. package/dist/mdx/react/popup/examples/NestedPopups.tsx +18 -18
  147. package/dist/mdx/react/popup/examples/RTL.tsx +6 -3
  148. package/dist/mdx/react/radio/Radio.mdx +7 -0
  149. package/dist/mdx/react/radio/examples/Basic.tsx +11 -2
  150. package/dist/mdx/react/radio/examples/Inverse.tsx +23 -0
  151. package/dist/mdx/react/segmented-control/SegmentedControl.mdx +2 -2
  152. package/dist/mdx/react/segmented-control/examples/Basic.tsx +13 -11
  153. package/dist/mdx/react/skeleton/examples/Basic.tsx +1 -1
  154. package/dist/mdx/react/skeleton/examples/Color.tsx +1 -2
  155. package/dist/mdx/react/skeleton/examples/Simulation.tsx +31 -30
  156. package/dist/mdx/react/status-indicator/StatusIndicator.mdx +12 -0
  157. package/dist/mdx/react/status-indicator/examples/MaxWidth.tsx +30 -0
  158. package/dist/mdx/react/tabs/Tabs.mdx +14 -17
  159. package/dist/mdx/react/tabs/TabsModel.splitprops.tsx +7 -3
  160. package/dist/mdx/react/tabs/examples/DynamicTabs.tsx +6 -13
  161. package/dist/mdx/react/tabs/examples/HoistedModel.tsx +8 -8
  162. package/dist/mdx/react/tabs/examples/Icons.tsx +4 -4
  163. package/dist/mdx/react/tabs/examples/NamedTabs.tsx +10 -10
  164. package/dist/mdx/react/tabs/examples/OverflowTabs.tsx +4 -8
  165. package/dist/mdx/react/tabs/examples/SinglePanel.tsx +3 -3
  166. package/dist/mdx/react/text-input/examples/Basic.tsx +3 -0
  167. package/dist/mdx/react/tooltip/Tooltip.mdx +2 -2
  168. package/dist/mdx/react/tooltip/examples/Default.tsx +2 -2
  169. package/dist/mdx/react/tooltip/examples/UseTooltip.tsx +2 -2
  170. package/package.json +9 -17
  171. package/dist/mdx/labs-react/common/examples/PropTables.splitprops.tsx +0 -91
  172. package/dist/mdx/labs-react/layout/examples/Stack/ShouldWrapChildren.tsx +0 -33
  173. package/dist/mdx/react/button/icon-button/IconButton.mdx +0 -103
  174. package/dist/mdx/react/button/icon-button/examples/Circle.tsx +0 -6
  175. package/dist/mdx/react/button/icon-button/examples/CircleFilled.tsx +0 -8
  176. package/dist/mdx/react/button/icon-button/examples/Inverse.tsx +0 -20
  177. package/dist/mdx/react/button/icon-button/examples/InverseFilled.tsx +0 -20
  178. package/dist/mdx/react/button/icon-button/examples/MirroredIcon.tsx +0 -11
  179. package/dist/mdx/react/button/icon-button/examples/Plain.tsx +0 -8
  180. package/dist/mdx/react/button/icon-button/examples/Square.tsx +0 -8
  181. package/dist/mdx/react/button/icon-button/examples/SquareFilled.tsx +0 -8
  182. package/dist/mdx/react/button/icon-button/examples/Toggleable.tsx +0 -20
  183. package/ts3.5/dist/commonjs/index.d.ts +0 -4
  184. package/ts3.5/dist/commonjs/lib/Specifications.d.ts +0 -6
  185. package/ts3.5/dist/commonjs/lib/docs.d.ts +0 -5
  186. package/ts3.5/dist/commonjs/lib/specs.d.ts +0 -16
  187. package/ts3.5/dist/es6/index.d.ts +0 -4
  188. package/ts3.5/dist/es6/lib/Specifications.d.ts +0 -6
  189. package/ts3.5/dist/es6/lib/docs.d.ts +0 -5
  190. package/ts3.5/dist/es6/lib/specs.d.ts +0 -16
@@ -0,0 +1,48 @@
1
+ import React from 'react';
2
+
3
+ import {Flex, Box} from '@workday/canvas-kit-react/layout';
4
+ import {
5
+ ListBox,
6
+ useGridModel,
7
+ useListItemSelect,
8
+ useListItemRovingFocus,
9
+ useListItemRegister,
10
+ wrappingNavigationManager,
11
+ } from '@workday/canvas-kit-react/collection';
12
+ import {composeHooks, createSubcomponent} from '@workday/canvas-kit-react/common';
13
+
14
+ const useItem = composeHooks(useListItemSelect, useListItemRovingFocus, useListItemRegister);
15
+
16
+ const Item = createSubcomponent('button')({
17
+ modelHook: useGridModel,
18
+ elemPropsHook: useItem,
19
+ })((elemProps, Element, model) => {
20
+ return (
21
+ <Box
22
+ as={Element}
23
+ {...elemProps}
24
+ width={40}
25
+ border="solid 1px black"
26
+ style={{
27
+ background: model.state.selectedIds.includes(elemProps['data-id']) ? 'gray' : 'white',
28
+ }}
29
+ />
30
+ );
31
+ });
32
+
33
+ export default () => {
34
+ const model = useGridModel({
35
+ columnCount: 5,
36
+ // @ts-ignore Create an array of [{id: 1}, ...{id: n}]
37
+ items: [...Array(25).keys()].map(i => ({id: i + 1})),
38
+ // we don't need virtualization here
39
+ shouldVirtualize: false,
40
+ navigation: wrappingNavigationManager,
41
+ });
42
+
43
+ return (
44
+ <ListBox model={model} as={Flex} flexDirection="row" flexWrap="wrap" width={200}>
45
+ {item => <Item>{item.id}</Item>}
46
+ </ListBox>
47
+ );
48
+ };
@@ -105,12 +105,12 @@ standards.
105
105
 
106
106
  <ExampleCodeBlock code={Error} />
107
107
 
108
- ## Props
108
+ ## Color Input Props
109
109
 
110
110
  Undocumented props are spread to the underlying `<input type="text">` element.
111
111
 
112
112
  <ArgsTable of={ColorInput} />
113
113
 
114
- ## Specifications
114
+ ## Color Input Specifications
115
115
 
116
116
  <Specifications file="ColorPicker.spec.ts" name="ColorInput" />
@@ -42,12 +42,12 @@ relative to the Color Preview. `labelPosition` accepts the following values:
42
42
 
43
43
  <ExampleCodeBlock code={LabelPosition} />
44
44
 
45
- ## Props
45
+ ## Color Preview Props
46
46
 
47
47
  Undocumented props are spread to the underlying `<input type="text">` element.
48
48
 
49
49
  <ArgsTable of={ColorPreview} />
50
50
 
51
- ## Specifications
51
+ ## Color Preview Specifications
52
52
 
53
53
  <Specifications file="ColorPicker.spec.ts" name="ColorPreview" />
@@ -1,4 +1,4 @@
1
- import {Box} from '@workday/canvas-kit-labs-react/common';
1
+ import {Box} from '@workday/canvas-kit-react/layout';
2
2
  // examples
3
3
  import As from './examples/As';
4
4
  import Border from './examples/Border';
@@ -33,9 +33,6 @@ import {
33
33
 
34
34
  # Box
35
35
 
36
- [![LABS: Beta](https://img.shields.io/badge/LABS-beta-orange)](https://github.com/Workday/canvas-kit/tree/master/modules/labs-react/README.md)
37
- This component is work in progress and currently in pre-release.
38
-
39
36
  `Box` is a primitive component that provides a common, ergonomic API around Canvas design tokens. It
40
37
  is highly flexible, and its primary purpose is to build other components.
41
38
 
@@ -85,14 +82,14 @@ is highly flexible, and its primary purpose is to build other components.
85
82
  ## Usage
86
83
 
87
84
  ```tsx
88
- import {Box, BoxProps} from '@workday/canvas-kit-labs-react/common';
85
+ import {Box, BoxProps} from '@workday/canvas-kit-react/layout';
89
86
 
90
87
  interface CardProps extends BoxProps {
91
88
  // custom Card props go here
92
89
  }
93
90
 
94
91
  const Card = (props: CardProps) => {
95
- return <Box borderRadius="m" depth={2} padding="m" {...props} />;
92
+ return <Box borderRadius="m" depth={1} padding="m" {...props} />;
96
93
  };
97
94
  ```
98
95
 
@@ -1,35 +1,43 @@
1
- import {Flex} from '@workday/canvas-kit-labs-react/layout';
1
+ import {Flex} from '@workday/canvas-kit-react/layout';
2
2
  // examples
3
3
  import FlexCard from './examples/Flex/FlexCard';
4
4
  import FlexLayout from './examples/Flex/FlexLayout';
5
5
  import Usage from './examples/Flex/Usage';
6
- import FlexStyle from './examples/PropTables.splitprops.tsx';
6
+ import {FlexStyle} from './examples/PropTables.splitprops.tsx';
7
7
 
8
8
 
9
- # Flex
10
-
11
- [![LABS: Beta](https://img.shields.io/badge/LABS-beta-orange)](https://github.com/Workday/canvas-kit/tree/master/modules/labs-react/README.md)
12
- This component is work in progress and currently in pre-release.
9
+ # Canvas Kit Flex
13
10
 
14
11
  `Flex` is a low-level layout component that provides a common, ergonomic API for building
15
12
  one-dimensional layouts with
16
13
  [CSS Flexbox](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox).
17
14
 
18
- ## Table of Contents
15
+ ## Installation
19
16
 
20
- - [Flex](#flex)
21
- - [Table of Contents](#table-of-contents)
22
- - [Usage](#usage)
23
- - [What's the difference between `Flex` and `Box`?](#whats-the-difference-between-flex-and-box)
24
- - [Flex Props](#flex-props)
25
- - [Examples](#examples)
26
- - [Exhaustive Prop List](#exhaustive-prop-list)
17
+ ```sh
18
+ yarn add @workday/canvas-kit-react
19
+ ```
27
20
 
28
21
  ## Usage
29
22
 
23
+ ### Basic Example
24
+
30
25
  <ExampleCodeBlock code={Usage} />
31
26
 
32
- ## What's the difference between `Flex` and `Box`?
27
+ ### Rows and Columns
28
+
29
+ You can nest `Flex` components to build layouts with rows and columns.
30
+
31
+ <ExampleCodeBlock code={FlexLayout} />
32
+
33
+ ### Small Containers
34
+
35
+ You can also use `Flex` to create layouts within smaller containers, such as this card example
36
+ below:
37
+
38
+ <ExampleCodeBlock code={FlexCard} />
39
+
40
+ ### Flex vs. Box
33
41
 
34
42
  `Flex` is built with `Box` and has access to all `BoxProps`. The main differences between `Box` and
35
43
  `Flex` are:
@@ -52,17 +60,6 @@ through style props as well. There are seven flex container props:
52
60
 
53
61
  <ArgsTable of={FlexStyle} />
54
62
 
55
- ## Examples
56
-
57
- You can nest `Flex` components to build layouts with rows and columns.
58
-
59
- <ExampleCodeBlock code={FlexLayout} />
60
-
61
- You can also use `Flex` to create layouts within smaller containers, such as this card example
62
- below:
63
-
64
- <ExampleCodeBlock code={FlexCard} />
65
-
66
- ## Exhaustive Prop List
63
+ ### Flex Props (Exhaustive List)
67
64
 
68
65
  <ArgsTable of={Flex} />
@@ -1,4 +1,4 @@
1
- import {Stack} from '@workday/canvas-kit-labs-react/layout';
1
+ import {Stack} from '@workday/canvas-kit-react/layout';
2
2
  // examples
3
3
  import BasicStack from './examples/Stack/BasicStack';
4
4
  import ShouldWrapChildren from './examples/Stack/ShouldWrapChildren';
@@ -9,10 +9,7 @@ import HStackCards from './examples/Stack/HStackCards';
9
9
  import VStackCards from './examples/Stack/VStackCards';
10
10
 
11
11
 
12
- # Stack, HStack, and VStack
13
-
14
- [![LABS: Beta](https://img.shields.io/badge/LABS-beta-orange)](https://github.com/Workday/canvas-kit/tree/master/modules/labs-react/README.md)
15
- This component is work in progress and currently in pre-release.
12
+ # Canvas Kit Stack
16
13
 
17
14
  `Stack`, `HStack`, and `VStack` are higher-level layout components that provide an ergonomic API for
18
15
  building one-dimensional layouts with consistent spacing between elements. They're built on top of
@@ -20,48 +17,13 @@ building one-dimensional layouts with consistent spacing between elements. They'
20
17
  horizontal or vertical orientation. `HStack` and `VStack` will only align items in a horizontal or
21
18
  vertical orientation, respectively.
22
19
 
23
- ## Table of Contents
24
-
25
- - [Stack, HStack, and VStack](#stack-hstack-and-vstack)
26
- - [Table of Contents](#table-of-contents)
27
- - [Stack](#stack)
28
- - [Usage](#usage)
29
- - [What Stack Is & Isn't](#what-stack-is--isnt)
30
- - [Setting Direction](#setting-direction)
31
- - [Setting Space](#setting-space)
32
- - [Managing Child Elements](#managing-child-elements)
33
- - [Basic Usage](#basic-usage)
34
- - [Using `shouldWrapChildren`](#using-shouldwrapchildren)
35
- - [Using `Stack.Item`](#using-stackitem)
36
- - [Valid Children](#valid-children)
37
- - [Examples](#examples)
38
- - [HStack](#hstack)
39
- - [Usage](#usage-1)
40
- - [Example](#example)
41
- - [VStack](#vstack)
42
- - [Usage](#usage-2)
43
- - [Example](#example-1)
44
- - [Exhaustive Prop List](#exhaustive-prop-list)
45
-
46
- ## Stack
47
-
48
- `Stack` is a composable component that's helpful for creating layouts with equal spacing between
49
- elements. It can create horizontal or vertical stacks of elements.
50
-
51
- ### Usage
20
+ ## Installation
52
21
 
53
- ```tsx
54
- import {Stack, StackStyleProps} from '@workday/canvas-kit-labs-react/layout';
22
+ ```sh
23
+ yarn add @workday/canvas-kit-react
55
24
  ```
56
25
 
57
- ### What Stack Is & Isn't
58
-
59
- The most important distinction to make with `Stack` is that it is _not a grid._ Grid components are
60
- able to align items along two dimensions (rows and columns), and `Stack` is only built to support
61
- one dimension (rows _or_ columns). That said, you can nest horizontal and vertical `Stack`
62
- components to create grid-like layouts.
63
-
64
- ### Thinking in Stacks
26
+ ## Usage
65
27
 
66
28
  `Stack` is a higher-level layout component, meaning:
67
29
 
@@ -70,14 +32,39 @@ components to create grid-like layouts.
70
32
 
71
33
  `Stack` has three core opinions that guide its API:
72
34
 
73
- - space should be equal between child elements
74
- - space should only exist between child elements
75
- - children should be semantic elements
35
+ - Space should be equal between child elements
36
+ - Space should only exist between child elements
37
+ - Children should be semantic elements
76
38
 
77
39
  Much of layout design is founded on these opinions. Whether its creating lists of navigation links,
78
40
  groups of cards, or collections of buttons, once you think in stacks, you'll see them everywhere.
79
41
 
80
- ### Setting Direction
42
+ ### Basic Example
43
+
44
+ `Stack` is a composable component that's helpful for creating layouts with equal spacing between
45
+ elements. It can create horizontal or vertical stacks of elements.
46
+
47
+ > The most important distinction to make with `Stack` is that it is _not a grid._ Grid components
48
+ > are able to align items along two dimensions (rows and columns), and `Stack` is only built to
49
+ > support one dimension (rows _or_ columns). That said, you can nest horizontal and vertical `Stack`
50
+ > components to create grid-like layouts.
51
+
52
+ `Stack` uses CSS pseudo-classes to apply margin to child elements. This makes it really simple to
53
+ get consistent spacing between child elements without much manual effort. Below is a basic example.
54
+ Note that `Stack` does not add any space above or below the child elements. This helps your element
55
+ fit nicely within their containers.
56
+
57
+ <ExampleCodeBlock code={BasicStack} />
58
+
59
+ Use this approach when:
60
+
61
+ - You want consistent space between child elements
62
+ - You don't need to apply custom margin to child elements
63
+ - Specifically `marginLeft`/`marginInlineStart` for horizontal stacks and `marginTop` for vertical
64
+ stacks
65
+ - You don't want to add extra markup to wrap child elements
66
+
67
+ #### Setting Direction
81
68
 
82
69
  The direction of the child elements is set with the `flexDirection` prop. This prop supports four
83
70
  directions: `column`, `column-reverse`, `row`, and `row-reverse`. By default, it will set the
@@ -89,7 +76,7 @@ direction to `row` as is consistent with the CSS Flexbox spec.
89
76
  > Note: `spacing` also supports bidirectionality automatically. This means you don't need to think
90
77
  > about it for localization as long as you properly pass the `direction` to the `theme` object un
91
78
 
92
- ### Setting Space
79
+ #### Setting Space
93
80
 
94
81
  The space between child elements is set with the `spacing` prop, which supports all space token and
95
82
  string values. `Stack` intentionally only sets space between elements and never outside. For
@@ -97,13 +84,13 @@ example: a vertical stack of three elements would only have margin added to the
97
84
  and third child elements. Keeping space between elements makes building layouts more block-like and
98
85
  predictable.
99
86
 
100
- ### Managing Child Elements
87
+ #### Managing Child Elements
101
88
 
102
89
  There are three ways to manage space between child elements with `Stack`.
103
90
 
104
- - implicit spacing applied directly to child elements (default behavior)
105
- - implicit wrapping child elements with `shouldWrapChildren`
106
- - explicit wrapping child elements with `Stack.Item`s.
91
+ - Implicit spacing applied directly to child elements (default behavior)
92
+ - Implicit wrapping child elements with `shouldWrapChildren`
93
+ - Explicit wrapping child elements with `Stack.Item`s.
107
94
 
108
95
  Each approach has its own benefits and limitations, which are discussed in further detail below. We
109
96
  chose to implicitly apply spacing to child elements as the default behavior because it requires the
@@ -112,80 +99,6 @@ hatches for when the default behavior becomes forced. Should you find none of th
112
99
  for your use case, we recommend using `Flex` instead of `Stack`, which will provide you with more
113
100
  flexibility.
114
101
 
115
- #### Basic Usage
116
-
117
- `Stack` uses CSS pseudo-classes to apply margin to child elements. This makes it really simple to
118
- get consistent spacing between child elements without much manual effort. Below is a basic example.
119
- Note that `Stack` does not add any space above or below the child elements. This helps your element
120
- fit nicely within their containers.
121
-
122
- <ExampleCodeBlock code={BasicStack} />
123
-
124
- Use this approach when:
125
-
126
- - you want consistent space between child elements
127
- - you don't need to apply custom margin to child elements
128
- - specifically `marginLeft`/`marginInlineStart` for horizontal stacks and `marginTop` for vertical
129
- stacks
130
- - you don't want to add extra markup to wrap child elements
131
-
132
- A side-effect of `Stack`'s pseduo-classes is an increased style specificity. This specificity can
133
- override the child element's margin styles. If that creates a problem, there are two recommended
134
- options available:
135
-
136
- - Use the `shouldWrapChildren` prop (implicit option)
137
- - Use `Stack.Item` (explicit option)
138
-
139
- Both are discussed below.
140
-
141
- #### Using `shouldWrapChildren`
142
-
143
- The `shouldWrapChildren` prop will implicitly wrap each child in a `Stack.Item` component (which is
144
- a `Box`) and apply the margin to it instead of the child element provided. This allows you to
145
- control the margin of the child elements you provide and avoiding style collisions. The trade-off is
146
- that you do not have direct access to the `Stack.Item` being rendered. If having access to that
147
- element is necessary, using `Stack.Item` explicitly (as described below) could be the best solution.
148
-
149
- The example below is a bit contrived but has enough information to convey the point. In this
150
- scenario, we have a horizontal stack of `IconButtons`, but they are visually divided into separate
151
- groupings. The navigational buttons are on the left, and the additional actions are spaced slightly
152
- further to the right. You could use two separate horizontal stacks here to achieve the same result,
153
- but you could also use `shouldWrapChildren` and then put additional margin only where needed. Either
154
- approach would be fine; it's a matter of personal preference.
155
-
156
- > Note: `shouldWrapChildren` implicitly passes the child element's index as a unique `key` prop to
157
- > the `Stack.Item`, which works well for static lists. If you have dynamic lists with child elements
158
- > that change over time, you'll want to provide a unique `id` prop to each child element for the
159
- > `Stack.Item` to use as a key instead.
160
-
161
- <ExampleCodeBlock code={ShouldWrapChildren} />
162
-
163
- Use this approach when:
164
-
165
- - you want consistent space between child elements
166
- - you need to apply custom margin to particular children
167
- - wrapping each child element won't create issues with other semantic elements
168
- - you don't want to explicitly add extra markup to wrap child elements
169
-
170
- #### Using `Stack.Item`
171
-
172
- Sometimes inserting implicit wrapper elements can be problematic when you need access to those
173
- elements. In those situations, `shouldWrapChildren` is not the best choice, and you should opt for
174
- wrapping children in `Stack.Item`s. A `Stack.Item` is a `Box` with some preset styles which can be
175
- overridden if needed.
176
-
177
- In the example below, we wanted to keep our `li` elements as direct children of the `ul` stack. So
178
- we're wrapping each of the links with `Stack.Item`s, casting them as `li`s and applying custom
179
- styles to each. This would not be possible with `shouldWrapChildren`.
180
-
181
- <ExampleCodeBlock code={StackItems} />
182
-
183
- Use this approach when:
184
-
185
- - you want consistent space between child elements
186
- - you need to have direct access to `Stack.Item` wrappers
187
- - wrapping each child element won't create issues with other semantic elements
188
-
189
102
  ### Valid Children
190
103
 
191
104
  Because `Stack` applies styles to children, it requires its immediate children to be valid child
@@ -204,18 +117,20 @@ const ValidChildrenExample = () => {
204
117
  };
205
118
  ```
206
119
 
207
- ### Examples
120
+ ### Grid-like Layouts
208
121
 
209
122
  You can nest vertical and horizontal `Stack`s to create grid-like layouts. Here are three horizontal
210
123
  `Stack`s nested within a vertical `Stack`. The fourth row is a single `Flex` component.
211
124
 
212
125
  <ExampleCodeBlock code={NestedStacks} />
213
126
 
127
+ ### Small Containers
128
+
214
129
  You can also use `Stack` to manage smaller layouts, such as within Cards.
215
130
 
216
131
  <ExampleCodeBlock code={StackCard} />
217
132
 
218
- ## HStack
133
+ ### HStack
219
134
 
220
135
  `HStack` works identically to `Stack` but is limited to only `row` and `row-reverse` directions. It
221
136
  defaults to `row` if no `flexDirection` is provided.
@@ -224,35 +139,72 @@ defaults to `row` if no `flexDirection` is provided.
224
139
  > the direction or spacing for localization. The direction switching is handled by the CSS Flexbox
225
140
  > spec, and the spacing will flip direction based on the `direction` provided in the `theme` object.
226
141
 
227
- ### Usage
228
-
229
- ```tsx
230
- import {HStack, HStackStyleProps} from '@workday/canvas-kit-labs-react/layout';
231
- ```
232
-
233
- ### Example
234
-
235
142
  In this example, `HStack` is placing three cards in a row with small spacing between them.
236
143
 
237
144
  <ExampleCodeBlock code={HStackCards} />
238
145
 
239
- ## VStack
146
+ ### VStack
240
147
 
241
148
  `VStack` works identically to `Stack` but is limited to only `column` and `column-reverse`
242
149
  directions. It defaults to `column` if no `flexDirection` is provided.
243
150
 
244
- ### Usage
151
+ In this example, `VStack` is placing three cards in a column with small spacing between them.
245
152
 
246
- ```tsx
247
- import {VStack, VStackStyleProps} from '@workday/canvas-kit-labs-react/layout';
248
- ```
153
+ <ExampleCodeBlock code={VStackCards} />
249
154
 
250
- ### Example
155
+ ### shouldWrapChildren and Stack.Item
251
156
 
252
- In this example, `VStack` is placing three cards in a column with small spacing between them.
157
+ A side-effect of `Stack`'s pseudo-classes is an increased style specificity. This specificity can
158
+ override the child element's margin styles. If that creates a problem, there are two recommended
159
+ options available:
253
160
 
254
- <ExampleCodeBlock code={VStackCards} />
161
+ - Use the `shouldWrapChildren` prop (implicit option)
162
+ - Use `Stack.Item` (explicit option)
163
+
164
+ #### shouldWrapChildren
165
+
166
+ The `shouldWrapChildren` prop will implicitly wrap each child in a `Stack.Item` component (which is
167
+ a `Box`) and apply the margin to it instead of the child element provided. This allows you to
168
+ control the margin of the child elements you provide and avoiding style collisions. The trade-off is
169
+ that you do not have direct access to the `Stack.Item` being rendered. If having access to that
170
+ element is necessary, using `Stack.Item` explicitly (as described below) could be the best solution.
171
+
172
+ The example below is a bit contrived but has enough information to convey the point. In this
173
+ scenario, we have a horizontal stack of `SecondaryButton`s that render an icon, but they are
174
+ visually divided into separate groupings. The navigational buttons are on the left, and the
175
+ additional actions are spaced slightly further to the right. You could use two separate horizontal
176
+ stacks here to achieve the same result, but you could also use `shouldWrapChildren` and then put
177
+ additional margin only where needed. Either approach would be fine; it's a matter of personal
178
+ preference.
179
+
180
+ <ExampleCodeBlock code={ShouldWrapChildren} />
181
+
182
+ Use this approach when:
183
+
184
+ - You want consistent space between child elements
185
+ - You need to apply custom margin to particular children
186
+ - Wrapping each child element won't create issues with other semantic elements
187
+ - You don't want to explicitly add extra markup to wrap child elements
188
+
189
+ #### Stack.Item
190
+
191
+ Sometimes inserting implicit wrapper elements can be problematic when you need access to those
192
+ elements. In those situations, `shouldWrapChildren` is not the best choice, and you should opt for
193
+ wrapping children in `Stack.Item`s. A `Stack.Item` is a `Box` with some preset styles which can be
194
+ overridden if needed.
195
+
196
+ In the example below, we wanted to keep our `li` elements as direct children of the `ul` stack. So
197
+ we're wrapping each of the links with `Stack.Item`s, casting them as `li`s and applying custom
198
+ styles to each. This would not be possible with `shouldWrapChildren`.
199
+
200
+ <ExampleCodeBlock code={StackItems} />
201
+
202
+ Use this approach when:
203
+
204
+ - You want consistent space between child elements
205
+ - You need to have direct access to `Stack.Item` wrappers
206
+ - Wrapping each child element won't create issues with other semantic elements
255
207
 
256
- ## Exhaustive Prop List
208
+ ## Stack Props
257
209
 
258
210
  <ArgsTable of={Stack} />
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
- import {Box} from '@workday/canvas-kit-labs-react/common';
2
+ import {Box} from '@workday/canvas-kit-react/layout';
3
3
 
4
4
  export default () => {
5
5
  return (
@@ -1,6 +1,6 @@
1
1
  import * as React from 'react';
2
2
  import {colors, borderRadius, space} from '@workday/canvas-kit-react/tokens';
3
- import {Box} from '@workday/canvas-kit-labs-react/common';
3
+ import {Box} from '@workday/canvas-kit-react/layout';
4
4
 
5
5
  export default () => (
6
6
  <Box>
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
- import {Box} from '@workday/canvas-kit-labs-react/common';
2
+ import {Box} from '@workday/canvas-kit-react/layout';
3
3
 
4
4
  export default () => (
5
5
  <>
@@ -1,10 +1,10 @@
1
1
  import * as React from 'react';
2
- import {Box} from '@workday/canvas-kit-labs-react/common';
2
+ import {Box} from '@workday/canvas-kit-react/layout';
3
3
 
4
4
  export default () => (
5
5
  <>
6
- <Box depth="inset" display="inline-block" margin="xxxs" padding="xs">
7
- Depth Inset
6
+ <Box depth="none" display="inline-block" margin="xxxs" padding="xs">
7
+ Depth None
8
8
  </Box>
9
9
  <Box depth={1} display="inline-block" margin="xxxs" padding="xs">
10
10
  Depth 1
@@ -18,5 +18,11 @@ export default () => (
18
18
  <Box depth={4} display="inline-block" margin="xxxs" padding="xs">
19
19
  Depth 4
20
20
  </Box>
21
+ <Box depth={5} display="inline-block" margin="xxxs" padding="xs">
22
+ Depth 5
23
+ </Box>
24
+ <Box depth={6} display="inline-block" margin="xxxs" padding="xs">
25
+ Depth 6
26
+ </Box>
21
27
  </>
22
28
  );
@@ -1,7 +1,6 @@
1
1
  import * as React from 'react';
2
- import {Flex} from '@workday/canvas-kit-labs-react/layout';
3
- import {Box} from '@workday/canvas-kit-labs-react/common';
4
- import {PrimaryButton, SecondaryButton, IconButton} from '@workday/canvas-kit-react/button';
2
+ import {Flex, Box} from '@workday/canvas-kit-react/layout';
3
+ import {PrimaryButton, SecondaryButton} from '@workday/canvas-kit-react/button';
5
4
  import {type} from '@workday/canvas-kit-react/tokens';
6
5
 
7
6
  // temporary placeholder until type components are added to canvas-kit
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
- import {Flex} from '@workday/canvas-kit-labs-react/layout';
2
+ import {Flex} from '@workday/canvas-kit-react/layout';
3
3
 
4
4
  const Cell = (props: {children: React.ReactNode}) => {
5
5
  return (
@@ -1,6 +1,5 @@
1
1
  import * as React from 'react';
2
- import {Flex, FlexProps} from '@workday/canvas-kit-labs-react/layout';
3
- import {Box} from '@workday/canvas-kit-labs-react/common';
2
+ import {Flex, FlexProps, Box} from '@workday/canvas-kit-react/layout';
4
3
  import {type} from '@workday/canvas-kit-react/tokens';
5
4
 
6
5
  // temporary placeholder until type components are added to canvas-kit
@@ -24,7 +23,7 @@ const Card = ({children, ...props}: FlexProps) => (
24
23
  <Flex
25
24
  backgroundColor="frenchVanilla100"
26
25
  borderRadius="m"
27
- depth={2}
26
+ depth={1}
28
27
  flexDirection="column"
29
28
  margin="xs"
30
29
  flex="1 1 300px"
@@ -1,6 +1,5 @@
1
1
  import * as React from 'react';
2
- import {Flex} from '@workday/canvas-kit-labs-react/layout';
3
- import {Box} from '@workday/canvas-kit-labs-react/common';
2
+ import {Box, Flex} from '@workday/canvas-kit-react/layout';
4
3
 
5
4
  export default () => (
6
5
  <Flex padding="xs">
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
- import {Box} from '@workday/canvas-kit-labs-react/common';
2
+ import {Box} from '@workday/canvas-kit-react/layout';
3
3
 
4
4
  export default () => (
5
5
  <Box
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
- import {Box} from '@workday/canvas-kit-labs-react/common';
2
+ import {Box} from '@workday/canvas-kit-react/layout';
3
3
 
4
4
  export default () => {
5
5
  const boxRef = React.useRef(null);
@@ -1,6 +1,6 @@
1
1
  import React from 'react';
2
2
 
3
- import {FlexStyleProps, StackStyleProps} from '@workday/canvas-kit-labs-react/layout';
3
+ import {FlexStyleProps, StackStyleProps} from '@workday/canvas-kit-react/layout';
4
4
 
5
5
  export const FlexStyle = (props: FlexStyleProps) => <div />;
6
6
 
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
- import {Box} from '@workday/canvas-kit-labs-react/common';
2
+ import {Box} from '@workday/canvas-kit-react/layout';
3
3
 
4
4
  export default () => {
5
5
  const boxRef = React.useRef(null);
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
- import {Box} from '@workday/canvas-kit-labs-react/common';
2
+ import {Box} from '@workday/canvas-kit-react/layout';
3
3
  import {colors, space, spaceNumbers} from '@workday/canvas-kit-react/tokens';
4
4
 
5
5
  export default () => (