From 40c06258c7fec58ef802c7bc430d3c6f32ce297e Mon Sep 17 00:00:00 2001
From: Rob Phoenix <9257284+robphoenix@users.noreply.github.com>
Date: Thu, 11 Jul 2024 12:48:23 +0100
Subject: [PATCH] update Divider (#417)

---
 .changeset/orange-rivers-wave.md                |  5 +++++
 packages/web-ui/src/Divider/Divider.stories.tsx | 12 ++++++++++++
 packages/web-ui/src/Divider/Divider.tsx         |  4 +++-
 3 files changed, 20 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/orange-rivers-wave.md

diff --git a/.changeset/orange-rivers-wave.md b/.changeset/orange-rivers-wave.md
new file mode 100644
index 000000000..b548b6920
--- /dev/null
+++ b/.changeset/orange-rivers-wave.md
@@ -0,0 +1,5 @@
+---
+'@utilitywarehouse/web-ui': patch
+---
+
+Update `Divider` component & docs
diff --git a/packages/web-ui/src/Divider/Divider.stories.tsx b/packages/web-ui/src/Divider/Divider.stories.tsx
index 117ca2264..d2b96ba44 100644
--- a/packages/web-ui/src/Divider/Divider.stories.tsx
+++ b/packages/web-ui/src/Divider/Divider.stories.tsx
@@ -6,6 +6,7 @@ import { Heading } from '../Heading';
 import { Text } from '../Text';
 import { Strong } from '../Strong';
 import { colors } from '@utilitywarehouse/colour-system';
+import { Box } from '../Box';
 
 const meta: Meta<typeof Divider> = {
   title: 'Web UI / Components / Divider',
@@ -83,3 +84,14 @@ export const CustomColor: Story = {
     );
   },
 };
+
+export const UsageOutsideFlexbox: Story = {
+  render: () => (
+    <Box width="100%" p={4}>
+      <Divider decorative />
+      <Box height={100}>
+        <Divider orientation="vertical" decorative />
+      </Box>
+    </Box>
+  ),
+};
diff --git a/packages/web-ui/src/Divider/Divider.tsx b/packages/web-ui/src/Divider/Divider.tsx
index c3c86893b..c043a49d8 100644
--- a/packages/web-ui/src/Divider/Divider.tsx
+++ b/packages/web-ui/src/Divider/Divider.tsx
@@ -18,6 +18,7 @@ const StyledElement = styled('hr', {
 })<{ color: string }>(({ color }) => {
   return {
     all: 'unset',
+    display: 'block', // explicitly set this so horizontal dividers show inside block elements
     alignSelf: 'stretch',
     flexShrink: 0,
     backgroundColor: color,
@@ -34,7 +35,8 @@ const StyledElement = styled('hr', {
 
 /**
  * Used to provide a visual break and semantically divide content. Supports
- * vertical and horizontal orientations.
+ * vertical and horizontal orientations. Vertical dividers will only be visible
+ * when contained inside an element with display set to `flexbox` or `grid`.
  */
 export const Divider = React.forwardRef<React.ElementRef<'hr'>, DividerProps>(
   (