feat(typography): add container baseline mixins for flexbox

BREAKING CHANGE: `typography.baseline-top()` and `typography.baseline-bottom()` are now private. Use `typography.baseline()` for containers and `typography.text-baseline()` for text with $top and $bottom params.

PiperOrigin-RevId: 297926710

packages/mdc-dialog/_mixins.scss

@@ -124,11 +124,10 @@
   }
 
   .mdc-dialog__title {
-    @include typography-mixins.baseline-top(40px, $query: $query);
+    @include typography-mixins.text-baseline($top: 40px, $display: block, $query: $query);
     @include typography-mixins.typography(headline6, $query: $query);
 
     @include feature-targeting-mixins.targets($feat-structure) {
-      display: block;
       position: relative;
       flex-shrink: 0;
       box-sizing: border-box;

packages/mdc-drawer/_mixins.scss

@@ -141,13 +141,12 @@
 
   .mdc-drawer__title {
     @include typography-mixins.typography(headline6, $query: $query);
-    @include typography-mixins.baseline-top(36px, $query: $query);
-    @include typography-mixins.baseline-bottom(20px, $query: $query);
+    @include typography-mixins.text-baseline($top: 36px, $bottom: 20px, $query: $query);
   }
 
   .mdc-drawer__subtitle {
     @include typography-mixins.typography(body2, $query: $query);
-    @include typography-mixins.baseline-top(20px, $query: $query);
+    @include typography-mixins.text-baseline($top: 20px, $query: $query);
 
     @include feature-targeting-mixins.targets($feat-structure) {
       margin-bottom: 0;
@@ -440,7 +439,7 @@
   // postcss-bem-linter: ignore
   .mdc-list-group__subheader {
     @include typography-mixins.typography(body2, $query: $query);
-    @include typography-mixins.baseline-top(24px, $query: $query);
+    @include typography-mixins.text-baseline($top: 24px, $query: $query);
 
     @include feature-targeting-mixins.targets($feat-structure) {
       margin: 0;

packages/mdc-list/_mixins.scss

@@ -141,34 +141,35 @@
 
   .mdc-list-item__primary-text {
     @include typography-mixins.overflow-ellipsis($query);
-    @include typography-mixins.baseline-top($item-primary-text-baseline-height, $query);
-    @include typography-mixins.baseline-bottom($item-secondary-text-baseline-height, $query);
-
-    @include feature-targeting-mixins.targets($feat-structure) {
-      display: block;
-    }
+    @include typography-mixins.text-baseline(
+      $top: $item-primary-text-baseline-height,
+      $bottom: $item-secondary-text-baseline-height,
+      $display: block,
+      $query: $query
+    );
 
     // stylelint-disable plugin/selector-bem-pattern
     .mdc-list--dense & {
-      @include typography-mixins.baseline-top($dense-item-primary-text-baseline-height, $query);
-      @include typography-mixins.baseline-bottom($item-secondary-text-baseline-height, $query);
+      @include typography-mixins.text-baseline(
+        $top: $dense-item-primary-text-baseline-height,
+        $bottom: $item-secondary-text-baseline-height,
+        $query: $query
+      );
     }
     // stylelint-enable plugin/selector-bem-pattern
   }
 
   .mdc-list-item__secondary-text {
     @include typography-mixins.typography(body2, $query);
     @include typography-mixins.overflow-ellipsis($query);
-    @include typography-mixins.baseline-top($item-secondary-text-baseline-height, $query);
-
-    @include feature-targeting-mixins.targets($feat-structure) {
-      display: block;
-    }
+    @include typography-mixins.text-baseline(
+      $top: $item-secondary-text-baseline-height,
+      $display: block,
+      $query: $query
+    );
 
     // stylelint-disable plugin/selector-bem-pattern
     .mdc-list--dense & {
-      @include typography-mixins.baseline-top($item-secondary-text-baseline-height, $query);
-
       @include feature-targeting-mixins.targets($feat-structure) {
         font-size: inherit;
       }

packages/mdc-select/helper-text/mdc-select-helper-text.scss

@@ -26,7 +26,7 @@
 // postcss-bem-linter: define select-helper-text
 .mdc-select-helper-text {
   @include mixins.typography(caption);
-  @include mixins.baseline-top(16px);
+  @include mixins.text-baseline(16px);
 
   margin: 0;
   transition: functions.transition(opacity);

packages/mdc-textfield/character-counter/_mixins.scss

@@ -35,7 +35,7 @@
 
   .mdc-text-field-character-counter {
     @include typography-mixins.typography(caption, $query: $query);
-    @include typography-mixins.baseline-top(16px, $query: $query);
+    @include typography-mixins.text-baseline($top: 16px, $query: $query);
 
     @include feature-targeting-mixins.targets($feat-structure) {
       // Keep flex item align to trailing side on absence of helper text.

packages/mdc-textfield/helper-text/_mixins.scss

@@ -35,7 +35,7 @@
 
   .mdc-text-field-helper-text {
     @include typography-mixins.typography(caption, $query: $query);
-    @include typography-mixins.baseline-top(16px, $query: $query);
+    @include typography-mixins.text-baseline($top: 16px, $query: $query);
 
     @include feature-targeting-mixins.targets($feat-structure) {
       margin: 0;

packages/mdc-typography/README.md

@@ -118,11 +118,11 @@ CSS Custom property | Description
 Mixin | Description
 --- | ---
 `base` | Sets the font to Roboto
-`mdc-typography($style)` | Applies one of the typography styles, including setting the font to Roboto
+`typography($style)` | Applies one of the typography styles, including setting the font to Roboto
 `smooth-font` | Adds antialiasing for typography
 `overflow-ellipsis` | Truncates overflow text to one line with an ellipsis
-`baseline-top($distance)` | Sets the baseline height of a text element from top.
-`baseline-bottom($distance)` | Sets the distance from text baseline to bottom. This mixin should be combined with `baseline-top` when setting baseline distance to following text element.
+`baseline($top, $bottom, $display)`| Sets a container's baseline that text content will align to.
+`text-baseline($top, $bottom, $display)`| Sets the baseline of flow text content.
 
 > **A note about `overflow-ellipsis`**, `overflow-ellipsis` should only be used if the element is `display: block` or `display: inline-block`.
 

packages/mdc-typography/_mixins.scss

@@ -105,15 +105,94 @@
   }
 }
 
-@mixin baseline-top($distance, $query: feature-targeting-functions.all()) {
+/// Sets a container's baseline that text content will align to.
+///
+/// If the `$display` is set to a flexbox display, only `$top` baseline may be
+/// set. A separate element must be added as a child of the container with a
+/// `$bottom` baseline.
+///
+/// @param {Number} $top - the distance from the top of the container to the
+///     text's baseline.
+/// @param {Number} $bottom - the distance from the text's baseline to the
+///     bottom of the container.
+/// @param {String} $display - the display type of the container. May be `flex`,
+///     `inline-flex`, `block`, or `inline-block`.
+@mixin baseline($top: 0, $bottom: 0, $display: block, $query: feature-targeting-functions.all()) {
+  $validDisplayTypes: (flex, inline-flex, block, inline-block);
+
+  @if list.index($validDisplayTypes, $display) == null {
+    @error "mdc-typography: invalid display specified! #{$display} must be one of #{$validDisplayTypes}";
+  }
+
+  $isFlexbox: $display == "flex" or $display == "inline-flex";
   $feat-structure: feature-targeting-functions.create-target($query, structure);
 
   @include feature-targeting-mixins.targets($feat-structure) {
-    display: block;
-    margin-top: 0;
-    /* @alternate */
-    line-height: normal;
+    display: $display;
+
+    @if $isFlexbox {
+      align-items: baseline;
+    }
+  }
+
+  @if $top > 0 {
+    @include _baseline-top($top, $query: $query);
+  }
+
+  @if $bottom > 0 {
+    @if $isFlexbox {
+      @error "mdc-typography: invalid baseline with display type. #{$display} cannot specifiy $bottom. Add a separate child element with its own $bottom.";
+    }
+
+    @include _baseline-bottom($bottom, $query: $query);
   }
+}
+
+/// Sets the baseline of flow text content.
+///
+/// Separate `$top` and `$bottom` baselines may be specified. You should ensure
+/// that the `$top` baseline matches the previous text content's $bottom
+/// baseline to ensure text is positioned appropriately.
+///
+/// See go/css-baseline for reference on how this mixin works.
+///
+/// This is intended for text flow content only (e.g. `<h1>`, `<p>`, `<span>`,
+/// or `<div>` with only text content). Use `baseline()` to set the baseline of
+/// containers that are flexbox or have non-flow content children.
+///
+/// @param {Number} $top - the distance from the top of the container to the
+///     text's baseline.
+/// @param {Number} $bottom - the distance from the text's baseline to the
+///     bottom of the container.
+/// @param {Boolean} $lineHeight - the line-height to use for the text. This
+///     is the distance between baselines of multiple lines of text.
+/// @param {String} $display - the display type of the container. May be `block`
+///     or `inline-block`.
+@mixin text-baseline($top: 0, $bottom: 0, $display: block, $lineHeight: normal, $query: feature-targeting-functions.all()) {
+  $validDisplayTypes: (block, inline-block);
+
+  @if list.index($validDisplayTypes, $display) == null {
+    @error "mdc-typography: invalid display specified! #{$display} must be one of #{$validDisplayTypes}";
+  }
+
+  $feat-structure: feature-targeting-functions.create-target($query, structure);
+
+  @include baseline($display: $display, $top: $top, $bottom: $bottom, $query: $query);
+  @include feature-targeting-mixins.targets($feat-structure) {
+    @if $top > 0 {
+      margin-top: 0;
+      /* @alternate */
+      line-height: #{$lineHeight};
+    }
+
+    @if $bottom > 0 {
+      margin-bottom: -1 * $bottom;
+    }
+  }
+}
+
+@mixin _baseline-top($distance, $query: feature-targeting-functions.all()) {
+  $feat-structure: feature-targeting-functions.create-target($query, structure);
 
   &::before {
     @include feature-targeting-mixins.targets($feat-structure) {
@@ -124,13 +203,9 @@
   }
 }
 
-@mixin baseline-bottom($distance, $query: feature-targeting-functions.all()) {
+@mixin _baseline-bottom($distance, $query: feature-targeting-functions.all()) {
   $feat-structure: feature-targeting-functions.create-target($query, structure);
 
-  @include feature-targeting-mixins.targets($feat-structure) {
-    margin-bottom: -1 * $distance;
-  }
-
   &::after {
     @include feature-targeting-mixins.targets($feat-structure) {
       @include baseline-strut_($distance);

packages/mdc-typography/test/feature-targeting-any.test.scss

@@ -7,8 +7,8 @@
     @include typography.base($query: $query);
     @include typography.typography(button, $query: $query);
     @include typography.overflow-ellipsis($query: $query);
-    @include typography.baseline-top(0, $query: $query);
-    @include typography.baseline-bottom(0, $query: $query);
+    @include typography.baseline($top: 0, $bottom: 0, $query: $query);
+    @include typography.text-baseline($top: 0, $bottom: 0, $query: $query);
   }
 }