Improve dividers and allow sidebar positioning when Layout is flowing as row.

.changeset/large-masks-walk.md

@@ -0,0 +1,5 @@
+---
+'@primer/css': patch
+---
+
+Improve dividers and allow sidebar positioning when `Layout` is flowing as row.

docs/content/components/layout.md

@@ -40,7 +40,12 @@ of the sidebar position.
 
 ### Dividers
 
-Add `Layout--divided` to the `Layout` to show the dividers.
+Use `Layout--divided` in conjuction with a `Layout-divider` to show a divider between the main content and the sidebar.
+Flowing as row:
+- default: shows a `1px` line between main and sidebar
+- `Layout-divider--flowRow-shallow`: shows a filled `8px` divider.
+- `Layout-divider--flowRow-hidden`: hides the divider
+
 
 ```html live
 <div class="Layout Layout--divided">
@@ -53,6 +58,16 @@ Add `Layout--divided` to the `Layout` to show the dividers.
   <div class="Layout-divider"></div>
   <div class="Layout-sidebar border">divider hidden</div>
 </div>
+<div class="Layout Layout--divided">
+  <div class="Layout-main border">main content</div>
+  <div class="Layout-divider Layout-divider--flowRow-shallow"></div>
+  <div class="Layout-sidebar border">flowRow shallow divider</div>
+</div>
+<div class="Layout Layout--divided">
+  <div class="Layout-main border">main content</div>
+  <div class="Layout-divider Layout-divider--flowRow-hidden"></div>
+  <div class="Layout-sidebar border">flowRow hidden divider</div>
+</div>
 ```
 
 ### Centered content
@@ -181,6 +196,27 @@ Add `Layout--divided` to the `Layout` to show the dividers.
 </div>
 ```
 
+### Sidebar positioning as rows
+
+- `Layout--sidebarPosition-flowRow-start` (default): when stacked, render the sidebar first
+- `Layout--sidebarPosition-flowRow-end`: when stacked, render the sidebar last
+- `Layout--sidebarPosition-flowRow-none`: when stacked, hide the sidebar
+
+```html live
+<div class="Layout Layout--sidebarPosition-flowRow-start">
+  <div class="Layout-main border">main</div>
+  <div class="Layout-sidebar border">sidebar</div>
+</div>
+<div class="Layout Layout--sidebarPosition-flowRow-end">
+  <div class="Layout-main border">main</div>
+  <div class="Layout-sidebar border">sidebar</div>
+</div>
+<div class="Layout Layout--sidebarPosition-flowRow-none">
+  <div class="Layout-main border">main</div>
+  <div class="Layout-sidebar border">sidebar</div>
+</div>
+```
+
 ### Layout stacking
 
 - Default: stacks when container is `sm`.

src/layout/index.scss

@@ -1,4 +1,6 @@
 @import "../support/index.scss";
+@import "./mixins.scss";
+
 @import "./container.scss";
 @import "./grid.scss";
 @import "./grid-offset.scss";

src/layout/layout.scss

@@ -6,42 +6,18 @@
   --Layout-gutter: 16px;
 
   @media (max-width: calc(#{$width-sm} - 1px)) {
-    grid-auto-flow: row;
-    grid-template-columns: 1fr !important;
-
-    .Layout-sidebar,
-    .Layout-divider,
-    .Layout-main {
-        width: 100% !important;
-        grid-column: 1 !important;
-      }
+    @include flow-as-row;
   }
 
   &.Layout--flowRow-until-md {
     @media (max-width: calc(#{$width-md} - 1px)) {
-      grid-auto-flow: row;
-      grid-template-columns: 1fr !important;
-
-      .Layout-sidebar,
-      .Layout-divider,
-      .Layout-main {
-        width: 100% !important;
-        grid-column: 1 !important;
-      }
+      @include flow-as-row;
     }
   }
 
   &.Layout--flowRow-until-lg {
     @media (max-width: calc(#{$width-lg} - 1px)) {
-      grid-auto-flow: row;
-      grid-template-columns: 1fr !important;
-
-      .Layout-sidebar,
-      .Layout-divider,
-      .Layout-main {
-        width: 100% !important;
-        grid-column: 1 !important;
-      }
+      @include flow-as-row;
     }
   }
 

src/layout/mixins.scss

@@ -0,0 +1,64 @@
+// Layout mixins
+
+@mixin flow-as-row {
+  grid-auto-flow: row;
+  grid-template-columns: 1fr !important;
+
+  .Layout-sidebar,
+  .Layout-divider,
+  .Layout-main {
+      width: 100% !important;
+      grid-column: 1 !important;
+    }
+
+  &.Layout--divided {
+    @include flow-as-row-divider;
+  }
+
+  &.Layout--sidebarPosition-flowRow-start {
+    .Layout-sidebar {
+      grid-row: 1;
+    }
+
+    .Layout-main {
+      grid-row: 2 / span 2;
+    }
+  }
+
+  &.Layout--sidebarPosition-flowRow-end {
+    .Layout-sidebar {
+      grid-row: 2 / span 2;
+    }
+
+    .Layout-main {
+      grid-row: 1;
+    }
+  }
+
+  &.Layout--sidebarPosition-flowRow-none {
+    .Layout-sidebar {
+      display: none;
+    }
+  }
+}
+
+@mixin flow-as-row-divider {
+  --Layout-gutter: 0;
+
+  .Layout-divider {
+    height: 1px;
+
+    &.Layout-divider--flowRow-hidden {
+      display: none;
+    }
+
+    &.Layout-divider--flowRow-shallow {
+      height: 8px;
+      margin-right: 0;
+      background: var(--color-bg-canvas-inset);
+      border-color: var(--color-border-primary);
+      border-style: solid;
+      border-width: $border-width 0;
+    }
+  }
+}