fix(material/tabs): add header divider for m3 (#28244)

* fix(material/tabs): add header divider for m3

* fix(material/tabs): fix inverted header

(cherry picked from commit cb9c222)

Author: andrewseguin

src/dev-app/tabs/tabs-demo.html

@@ -26,3 +26,5 @@ <h3>Inverted Tabs</h3>
 <tab-group-inverted-example></tab-group-inverted-example>
 <h3>Ink bar fit to content</h3>
 <tab-group-ink-bar-example></tab-group-ink-bar-example>
+<h3>Tab group with the headers on the bottom</h3>
+<tab-group-header-below-example></tab-group-header-below-example>

src/material-experimental/theming/_custom-tokens.scss

@@ -509,6 +509,8 @@
   @return mat.private-merge-all(
     _generate-typography-tokens($systems, label-text, title-small),
     (
+      divider-color: map.get($systems, md-sys-color, surface-variant),
+      divider-height: 1px,
       disabled-ripple-color: null, // TODO(mmalerba): Figure out correct value.
       pagination-icon-color: map.get($systems, md-sys-color, on-surface),
       inactive-label-text-color: map.get($systems, md-sys-color, on-surface),

src/material/core/tokens/m2/mat/_tab-header.scss

@@ -8,7 +8,12 @@ $prefix: (mat, tab-header);
 // Tokens that can't be configured through Angular Material's current theming API,
 // but may be in a future version of the theming API.
 @function get-unthemable-tokens() {
-  @return ();
+  @return (
+    // For some period of time, the MDC tabs removed the divider. This has been added back in
+    // and will be present in M3.
+    divider-color: transparent,
+    divider-height: 0,
+  );
 }
 
 // Tokens that can be configured through Angular Material's color theming API.

src/material/tabs/_tabs-common.scss

@@ -338,11 +338,30 @@ $mat-tab-animation-duration: 500ms !default;
 }
 
 // Structural styles for the element that wraps the paginated container's content.
-@mixin paginated-tab-header-container {
+// Include a selector for an inverted header if the header may be optionally positioned on the
+// bottom of the content.
+@mixin paginated-tab-header-container($inverted-header-selector: null) {
   display: flex;
   flex-grow: 1;
   overflow: hidden;
   z-index: 1;
+  @include token-utils.use-tokens(
+    tokens-mat-tab-header.$prefix,
+    tokens-mat-tab-header.get-token-slots()
+  ) {
+    border-bottom-style: solid;
+    @include token-utils.create-token-slot(border-bottom-width, divider-height);
+    @include token-utils.create-token-slot(border-bottom-color, divider-color);
+
+    @if ($inverted-header-selector) {
+      #{$inverted-header-selector} & {
+        border-bottom: none;
+        border-top-style: solid;
+        @include token-utils.create-token-slot(border-top-width, divider-height);
+        @include token-utils.create-token-slot(border-top-color, divider-color);
+      }
+    }
+  }
 }
 
 @mixin paginated-tab-header-with-background($header-selector, $tab-selector) {

src/material/tabs/tab-header.scss

@@ -4,7 +4,7 @@
 @include tabs-common.paginated-tab-header;
 
 .mat-mdc-tab-label-container {
-  @include tabs-common.paginated-tab-header-container;
+  @include tabs-common.paginated-tab-header-container('.mat-mdc-tab-group-inverted-header');
 }
 
 .mat-mdc-tab-labels {