From 2b2ae84695e163309529a02325e70c4416b2a5f6 Mon Sep 17 00:00:00 2001
From: Danny Banks <djb@amazon.com>
Date: Tue, 16 Nov 2021 11:35:30 -0800
Subject: [PATCH] Divider fixes and docs (#727)

Co-authored-by: Chenwei Zhang <40295569+zchenwei@users.noreply.github.com>
---
 .changeset/purple-chefs-jump.md               |   8 +
 docs/src/components/DividerPropControls.tsx   |  54 ------
 docs/src/components/useGridContainerProps.tsx |   4 +-
 .../divider/DividerPropControls.tsx           |  51 ++++++
 docs/src/pages/components/divider/demo.tsx    |  45 +++--
 .../examples/DefaultDividerExample.tsx        |   9 +
 .../examples/DividerClassNameExample.tsx      |  12 ++
 .../divider/examples/DividerSizesExample.tsx  |   9 +
 .../examples/DividerStylePropsExample.tsx     |  13 ++
 .../divider/examples/DividerThemeExample.tsx  |  29 ++++
 .../examples/HorizontalDividerExample.tsx     |   9 +
 .../examples/VerticalDividerExample.tsx       |   9 +
 .../components/divider/examples/index.tsx     |   7 +
 .../pages/components/divider/index.page.mdx   |   1 +
 docs/src/pages/components/divider/react.mdx   | 158 +++++++++---------
 .../components/divider}/useDividerProps.tsx   |   0
 .../ui/src/theme/css/component/divider.scss   |   1 -
 17 files changed, 270 insertions(+), 149 deletions(-)
 create mode 100644 .changeset/purple-chefs-jump.md
 delete mode 100644 docs/src/components/DividerPropControls.tsx
 create mode 100644 docs/src/pages/components/divider/DividerPropControls.tsx
 create mode 100644 docs/src/pages/components/divider/examples/DefaultDividerExample.tsx
 create mode 100644 docs/src/pages/components/divider/examples/DividerClassNameExample.tsx
 create mode 100644 docs/src/pages/components/divider/examples/DividerSizesExample.tsx
 create mode 100644 docs/src/pages/components/divider/examples/DividerStylePropsExample.tsx
 create mode 100644 docs/src/pages/components/divider/examples/DividerThemeExample.tsx
 create mode 100644 docs/src/pages/components/divider/examples/HorizontalDividerExample.tsx
 create mode 100644 docs/src/pages/components/divider/examples/VerticalDividerExample.tsx
 create mode 100644 docs/src/pages/components/divider/examples/index.tsx
 rename docs/src/{components => pages/components/divider}/useDividerProps.tsx (100%)

diff --git a/.changeset/purple-chefs-jump.md b/.changeset/purple-chefs-jump.md
new file mode 100644
index 00000000000..47d1255b8af
--- /dev/null
+++ b/.changeset/purple-chefs-jump.md
@@ -0,0 +1,8 @@
+---
+"@aws-amplify/ui-react": patch
+"@aws-amplify/ui": patch
+---
+
+* Divider component has more theming options for the border style, color, and width.
+* Fixing vertical divider
+* Improving Divider docs
diff --git a/docs/src/components/DividerPropControls.tsx b/docs/src/components/DividerPropControls.tsx
deleted file mode 100644
index ff2b85fbaf4..00000000000
--- a/docs/src/components/DividerPropControls.tsx
+++ /dev/null
@@ -1,54 +0,0 @@
-import React from 'react';
-import { DividerOptions } from '@aws-amplify/ui-react';
-import { FieldLabeler } from './FieldLabeler';
-import { DemoBox } from './DemoBox';
-export interface DividerPropControlsProps extends DividerOptions {
-  setSize: (value: React.SetStateAction<DividerOptions['size']>) => void;
-  setOrientation: (
-    value: React.SetStateAction<DividerOptions['orientation']>
-  ) => void;
-}
-
-interface DividerPropControlsInterface {
-  (props: DividerPropControlsProps): JSX.Element;
-}
-
-export const DividerPropControls: DividerPropControlsInterface = ({
-  size,
-  setSize,
-  orientation,
-  setOrientation,
-}) => {
-  return (
-    <DemoBox primitiveName="Divider">
-      <FieldLabeler id="size">
-        <select
-          name="size"
-          id="size"
-          value={size}
-          onChange={(event) =>
-            setSize(event.target.value as DividerOptions['size'])
-          }
-        >
-          <option value="">default</option>
-          <option value="small">small</option>
-          <option value="large">large</option>
-        </select>
-      </FieldLabeler>
-
-      <FieldLabeler id="orientation">
-        <select
-          name="orientation"
-          id="orientation"
-          value={orientation}
-          onChange={(event) =>
-            setOrientation(event.target.value as DividerOptions['orientation'])
-          }
-        >
-          <option value="horizontal">horizontal</option>
-          <option value="vertical">vertical</option>
-        </select>
-      </FieldLabeler>
-    </DemoBox>
-  );
-};
diff --git a/docs/src/components/useGridContainerProps.tsx b/docs/src/components/useGridContainerProps.tsx
index bafdb7ab8d8..cd56a650b02 100644
--- a/docs/src/components/useGridContainerProps.tsx
+++ b/docs/src/components/useGridContainerProps.tsx
@@ -1,6 +1,6 @@
+import * as React from 'react';
+
 import { DividerOptions, GridContainerStyleProps } from '@aws-amplify/ui-react';
-import { useState } from 'react';
-import { DividerPropControlsProps } from './DividerPropControls';
 import { GridContainerPropControlsProps } from './GridContainerPropControls';
 
 interface UseGridContainerProps {
diff --git a/docs/src/pages/components/divider/DividerPropControls.tsx b/docs/src/pages/components/divider/DividerPropControls.tsx
new file mode 100644
index 00000000000..3abe837a811
--- /dev/null
+++ b/docs/src/pages/components/divider/DividerPropControls.tsx
@@ -0,0 +1,51 @@
+import * as React from 'react';
+import { DividerOptions, Flex, SelectField } from '@aws-amplify/ui-react';
+
+export interface DividerPropControlsProps extends DividerOptions {
+  setSize: (value: React.SetStateAction<DividerOptions['size']>) => void;
+  setOrientation: (
+    value: React.SetStateAction<DividerOptions['orientation']>
+  ) => void;
+}
+
+interface DividerPropControlsInterface {
+  (props: DividerPropControlsProps): JSX.Element;
+}
+
+export const DividerPropControls: DividerPropControlsInterface = ({
+  size,
+  setSize,
+  orientation,
+  setOrientation,
+}) => {
+  return (
+    <Flex direction="column">
+      <SelectField
+        name="size"
+        id="size"
+        label="Size"
+        value={size}
+        onChange={(event) =>
+          setSize(event.target.value as DividerOptions['size'])
+        }
+      >
+        <option value="">default</option>
+        <option value="small">small</option>
+        <option value="large">large</option>
+      </SelectField>
+
+      <SelectField
+        name="orientation"
+        id="orientation"
+        label="Orientation"
+        value={orientation}
+        onChange={(event) =>
+          setOrientation(event.target.value as DividerOptions['orientation'])
+        }
+      >
+        <option value="horizontal">horizontal</option>
+        <option value="vertical">vertical</option>
+      </SelectField>
+    </Flex>
+  );
+};
diff --git a/docs/src/pages/components/divider/demo.tsx b/docs/src/pages/components/divider/demo.tsx
index 13996d7e54d..9dfa8e83a04 100644
--- a/docs/src/pages/components/divider/demo.tsx
+++ b/docs/src/pages/components/divider/demo.tsx
@@ -1,8 +1,21 @@
-import React from 'react';
+import * as React from 'react';
 import { Divider, Flex, Text } from '@aws-amplify/ui-react';
-import { DividerPropControls } from '@/components/DividerPropControls';
-import { useDividerProps } from '@/components/useDividerProps';
-import { Example } from '@/components/Example';
+import { DividerPropControls } from './DividerPropControls';
+import { useDividerProps } from './useDividerProps';
+import { Demo } from '@/components/Demo';
+
+const propsToCode = (props) => {
+  return (
+    `<Flex direction=${JSON.stringify(props.direction)}>
+  <Text>Before</Text>
+  <Divider` +
+    (props.size ? `\n    size=${JSON.stringify(props.size)}` : '') +
+    `
+    orientation=${JSON.stringify(props.orientation)} />
+  <Text>After</Text>
+</Flex>`
+  );
+};
 
 export const DividerDemo = () => {
   const dividerProps = useDividerProps({
@@ -12,18 +25,18 @@ export const DividerDemo = () => {
     dividerProps.orientation === 'horizontal' ? 'column' : 'row';
 
   return (
-    <div>
-      <DividerPropControls {...dividerProps} />
-      <Flex direction={direction} className="pt-2">
-        <Example>
-          <Text>Before</Text>
-          <Divider
-            size={dividerProps.size}
-            orientation={dividerProps.orientation}
-          />
-          <Text>After</Text>
-        </Example>
+    <Demo
+      propControls={<DividerPropControls {...dividerProps} />}
+      code={propsToCode({ direction, ...dividerProps })}
+    >
+      <Flex direction={direction}>
+        <Text>Before</Text>
+        <Divider
+          size={dividerProps.size}
+          orientation={dividerProps.orientation}
+        />
+        <Text>After</Text>
       </Flex>
-    </div>
+    </Demo>
   );
 };
diff --git a/docs/src/pages/components/divider/examples/DefaultDividerExample.tsx b/docs/src/pages/components/divider/examples/DefaultDividerExample.tsx
new file mode 100644
index 00000000000..c4ab97f94bf
--- /dev/null
+++ b/docs/src/pages/components/divider/examples/DefaultDividerExample.tsx
@@ -0,0 +1,9 @@
+import { Flex, Text, Divider } from '@aws-amplify/ui-react';
+
+export const DefaultDividerExample = () => (
+  <Flex direction="column">
+    <Text>Before</Text>
+    <Divider />
+    <Text>After</Text>
+  </Flex>
+);
diff --git a/docs/src/pages/components/divider/examples/DividerClassNameExample.tsx b/docs/src/pages/components/divider/examples/DividerClassNameExample.tsx
new file mode 100644
index 00000000000..efbdf73ab04
--- /dev/null
+++ b/docs/src/pages/components/divider/examples/DividerClassNameExample.tsx
@@ -0,0 +1,12 @@
+import { Flex, Divider } from '@aws-amplify/ui-react';
+
+const css = `.custom-divider {
+  border-style: dashed;
+}`;
+
+export const DividerClassNameExample = () => (
+  <Flex direction="column">
+    <style>{css}</style>
+    <Divider className="custom-divider" />
+  </Flex>
+);
diff --git a/docs/src/pages/components/divider/examples/DividerSizesExample.tsx b/docs/src/pages/components/divider/examples/DividerSizesExample.tsx
new file mode 100644
index 00000000000..a390b5bcacf
--- /dev/null
+++ b/docs/src/pages/components/divider/examples/DividerSizesExample.tsx
@@ -0,0 +1,9 @@
+import { Flex, Divider } from '@aws-amplify/ui-react';
+
+export const DividerSizesExample = () => (
+  <Flex direction="column">
+    <Divider size="small" />
+    <Divider />
+    <Divider size="large" />
+  </Flex>
+);
diff --git a/docs/src/pages/components/divider/examples/DividerStylePropsExample.tsx b/docs/src/pages/components/divider/examples/DividerStylePropsExample.tsx
new file mode 100644
index 00000000000..3e18b7b55fd
--- /dev/null
+++ b/docs/src/pages/components/divider/examples/DividerStylePropsExample.tsx
@@ -0,0 +1,13 @@
+import { Flex, Divider, useTheme } from '@aws-amplify/ui-react';
+
+export const DividerStylePropsExample = () => {
+  const { tokens } = useTheme();
+  return (
+    <Flex direction="column">
+      <Divider
+        border={`${tokens.borderWidths.large} solid ${tokens.colors.brand.primary[80]}`}
+      />
+      <Divider border="5px solid pink" borderRadius="10px" />
+    </Flex>
+  );
+};
diff --git a/docs/src/pages/components/divider/examples/DividerThemeExample.tsx b/docs/src/pages/components/divider/examples/DividerThemeExample.tsx
new file mode 100644
index 00000000000..5d3d8439a13
--- /dev/null
+++ b/docs/src/pages/components/divider/examples/DividerThemeExample.tsx
@@ -0,0 +1,29 @@
+import { Flex, Text, Divider, AmplifyProvider } from '@aws-amplify/ui-react';
+
+const theme = {
+  name: 'divider-theme',
+  tokens: {
+    borderWidths: {
+      // This will affect the large divider and other components that reference this
+      large: { value: '20px' },
+    },
+    components: {
+      divider: {
+        borderStyle: { value: 'dotted' },
+        // You can reference other theme tokens:
+        borderColor: { value: '{colors.brand.secondary.80.value}' },
+      },
+    },
+  },
+};
+
+export const DividerThemeExample = () => (
+  <AmplifyProvider theme={theme}>
+    <Flex direction="column">
+      <Text>Before</Text>
+      <Divider />
+      <Text>After</Text>
+      <Divider size="large" />
+    </Flex>
+  </AmplifyProvider>
+);
diff --git a/docs/src/pages/components/divider/examples/HorizontalDividerExample.tsx b/docs/src/pages/components/divider/examples/HorizontalDividerExample.tsx
new file mode 100644
index 00000000000..d4f0ff5c79e
--- /dev/null
+++ b/docs/src/pages/components/divider/examples/HorizontalDividerExample.tsx
@@ -0,0 +1,9 @@
+import { Flex, Text, Divider } from '@aws-amplify/ui-react';
+
+export const HorizontalDividerExample = () => (
+  <Flex direction="column">
+    <Text>Before</Text>
+    <Divider orientation="horizontal" />
+    <Text>After</Text>
+  </Flex>
+);
diff --git a/docs/src/pages/components/divider/examples/VerticalDividerExample.tsx b/docs/src/pages/components/divider/examples/VerticalDividerExample.tsx
new file mode 100644
index 00000000000..1333b78c515
--- /dev/null
+++ b/docs/src/pages/components/divider/examples/VerticalDividerExample.tsx
@@ -0,0 +1,9 @@
+import { Flex, Text, Divider } from '@aws-amplify/ui-react';
+
+export const VerticalDividerExample = () => (
+  <Flex direction="row" justifyContent="space-around">
+    <Text>Before</Text>
+    <Divider orientation="vertical" />
+    <Text>After</Text>
+  </Flex>
+);
diff --git a/docs/src/pages/components/divider/examples/index.tsx b/docs/src/pages/components/divider/examples/index.tsx
new file mode 100644
index 00000000000..4b9d93a13d5
--- /dev/null
+++ b/docs/src/pages/components/divider/examples/index.tsx
@@ -0,0 +1,7 @@
+export { HorizontalDividerExample } from './HorizontalDividerExample';
+export { VerticalDividerExample } from './VerticalDividerExample';
+export { DividerSizesExample } from './DividerSizesExample';
+export { DividerStylePropsExample } from './DividerStylePropsExample';
+export { DividerClassNameExample } from './DividerClassNameExample';
+export { DefaultDividerExample } from './DefaultDividerExample';
+export { DividerThemeExample } from './DividerThemeExample';
diff --git a/docs/src/pages/components/divider/index.page.mdx b/docs/src/pages/components/divider/index.page.mdx
index 36af783271f..270b960eadc 100644
--- a/docs/src/pages/components/divider/index.page.mdx
+++ b/docs/src/pages/components/divider/index.page.mdx
@@ -1,5 +1,6 @@
 ---
 title: Divider
+description: A Divider creates separations in content. Dividers can help organize content and establish visual rhythm.
 ---
 
 import { Fragment } from '@/components/Fragment';
diff --git a/docs/src/pages/components/divider/react.mdx b/docs/src/pages/components/divider/react.mdx
index 8a2a80ca6a7..fd779a6cf27 100644
--- a/docs/src/pages/components/divider/react.mdx
+++ b/docs/src/pages/components/divider/react.mdx
@@ -1,8 +1,15 @@
 import { Divider, View, Flex, Text } from '@aws-amplify/ui-react';
 import { DividerDemo } from './demo';
-import { Example } from '@/components/Example';
-
-A Divider creates separations in content.
+import { Example, ExampleCode } from '@/components/Example';
+import {
+  DefaultDividerExample,
+  HorizontalDividerExample,
+  VerticalDividerExample,
+  DividerSizesExample,
+  DividerStylePropsExample,
+  DividerClassNameExample,
+  DividerThemeExample,
+} from './examples';
 
 ## Demo
 
@@ -10,86 +17,90 @@ A Divider creates separations in content.
 
 ## Usage
 
-Import the Divider component and styles.
+Import the Divider component and place it between components you want separated. Most of the time you will want to use the divider in a [`<Flex>`](/components/flex) component.
+
+<Example>
+  <DefaultDividerExample />
+  <ExampleCode>
 
-```jsx
-import { Divider } from '@aws-amplify/ui-react';
-import '@aws-amplify/ui-react/styles.css';
+```jsx file=./examples/DefaultDividerExample.tsx
 
-<Divider />;
 ```
 
-<Example>
-  <Divider />
+  </ExampleCode>
 </Example>
 
 ### Orientation
 
 **Horizontal (default)**
 
-```jsx
-<View>
-  <Text>Before</Text>
-  <Divider orientation="horizontal" />
-  <Text>After</Text>
-</View>
+<Example>
+  <HorizontalDividerExample />
+  <ExampleCode>
+
+```jsx file=./examples/HorizontalDividerExample.tsx
+
 ```
 
-<Example>
-  <View>
-    <Text>Before</Text>
-    <Divider orientation="horizontal" />
-    <Text>After</Text>
-  </View>
+  </ExampleCode>
 </Example>
 
 **Vertical**
 
-```jsx
-<Flex height="100px" justifyContent="space-around">
-  <Text>Before</Text>
-  <Divider orientation="vertical" />
-  <Text>After</Text>
-</Flex>
+<Example>
+  <VerticalDividerExample />
+  <ExampleCode>
+
+```jsx file=./examples/VerticalDividerExample.tsx
+
 ```
 
-<Example>
-  <Flex height="100px" justifyContent="space-around">
-    <Text>Before</Text>
-    <Divider orientation="vertical" />
-    <Text>After</Text>
-  </Flex>
+  </ExampleCode>
 </Example>
 
 ### Sizes
 
 Available options are `small`, `large`, and none (default).
 
-```jsx
-<Flex direction="column" gap="20px">
-  <Divider size="small" />
-  <Divider />
-  <Divider size="large" />
-</Flex>
+<Example>
+  <DividerSizesExample />
+  <ExampleCode>
+
+```jsx file=./examples/DividerSizesExample.tsx
+
 ```
 
+  </ExampleCode>
+</Example>
+
+## Customization
+
+### Theme
+
+You can customize the appearance of all Dividers in your application with a [Theme](/theming).
+
 <Example>
-  <Flex direction="column" gap="20px">
-    <Divider size="small" />
-    <Divider />
-    <Divider size="large" />
-  </Flex>
+  <DividerThemeExample />
+  <ExampleCode>
+
+```jsx file=./examples/DividerThemeExample.tsx
+
+```
+
+  </ExampleCode>
 </Example>
 
-## CSS Styling
+### CSS
 
-### Global styling
+You can set the Amplify CSS variables or use the built-in `.amplify-divider` class to customize all Dividers in your application as well.
 
-To override styling on all Dividers, you can set the Amplify CSS variables or use the built-in `.amplify-divider` class.
+<Example>
+  <Divider className="border-style-override" />
+  <ExampleCode>
 
 ```css
 /* styles.css */
-:root {
+[data-amplify-theme] {
   --amplify-components-divider-border-style: dashed;
 }
 /* OR */
@@ -98,11 +109,10 @@ To override styling on all Dividers, you can set the Amplify CSS variables or us
 }
 ```
 
-<Example>
-  <Divider className="border-style-override" />
+</ExampleCode>
 </Example>
 
-To replace the Divider styling, unset it:
+To replace _all_ the Divider styling, unset it:
 
 ```css
 .amplify-divider {
@@ -117,36 +127,32 @@ To override styling on a specific Divider, you can use (in order of increasing s
 
 _Using a class selector:_
 
-(Example needed)
+<Example>
+  <DividerClassNameExample />
+  <ExampleCode>
 
-_Using data attributes:_
+```jsx file=./examples/DividerClassNameExample.tsx
 
-```css
-/* styles.css */
-.amplify-divider[data-size='small'] {
-  border-width: 2px;
-}
-.amplify-divider[data-size='large'] {
-  border-width: 6px;
-}
 ```
 
-```jsx
-<Flex direction="column" gap="20px">
-  <Divider size="small" />
-  <Divider />
-  <Divider size="large" />
-</Flex>
-```
+  </ExampleCode>
+</Example>
+
+_Using style props:_
 
 <Example>
-  <Flex direction="column" gap="20px">
-    <Divider className="border-width-override" size="small" />
-    <Divider className="border-width-override" />
-    <Divider className="border-width-override" size="large" />
-  </Flex>
+  <DividerStylePropsExample />
+  <ExampleCode>
+
+```jsx file=./examples/DividerStylePropsExample.tsx
+
+```
+
+  </ExampleCode>
 </Example>
 
-_Using style props:_
+### Default theme
 
-(Example needed)
+```js file=../../../../../packages/ui/src/theme/tokens/components/divider.js
+
+```
diff --git a/docs/src/components/useDividerProps.tsx b/docs/src/pages/components/divider/useDividerProps.tsx
similarity index 100%
rename from docs/src/components/useDividerProps.tsx
rename to docs/src/pages/components/divider/useDividerProps.tsx
diff --git a/packages/ui/src/theme/css/component/divider.scss b/packages/ui/src/theme/css/component/divider.scss
index ad117ed6fcc..0ecb497399b 100644
--- a/packages/ui/src/theme/css/component/divider.scss
+++ b/packages/ui/src/theme/css/component/divider.scss
@@ -21,7 +21,6 @@
   }
 
   &[aria-orientation='vertical'] {
-    height: 100%;
     border-left-width: var(--amplify-components-divider-border-width);
 
     &[data-size='small'] {