feat(shape): add shape custom properties

PiperOrigin-RevId: 313834996

packages/mdc-button/_mixins.scss

@@ -61,7 +61,7 @@ $ripple-target: ".mdc-button__ripple";
   // postcss-bem-linter: define button
   .mdc-button {
     @include base_($query);
-    @include shape-radius(small, $query: $query);
+    @include shape-radius(variables.$shape-radius, $query: $query);
     @include container-fill-color(transparent, $query);
     @include disabled-container-fill-color(transparent, $query);
     // The icon CSS class overrides styles defined in the .material-icons CSS
@@ -335,22 +335,32 @@ $ripple-target: ".mdc-button__ripple";
   }
 }
 
-@mixin shape-radius($radius,
-$rtl-reflexive: false,
-$density-scale: variables.$density-scale,
-$query: feature-targeting-functions.all()) {
-
+@mixin shape-radius(
+  $radius,
+  $rtl-reflexive: false,
+  $density-scale: variables.$density-scale,
+  $query: feature-targeting-functions.all()
+) {
   $height: density-functions.prop-value(
     $density-config: variables.$density-config,
     $density-scale: $density-scale,
     $property-name: height,
   );
-  $resolved-radius: shape-functions.resolve-percentage-radius($height, $radius);
 
-  @include shape-mixins.radius($resolved-radius, $rtl-reflexive, $query: $query);
+  @include shape-mixins.radius(
+    $radius,
+    $rtl-reflexive,
+    $component-height: $height,
+    $query: $query
+  );
 
   #{$ripple-target} {
-    @include shape-mixins.radius($resolved-radius, $rtl-reflexive, $query: $query);
+    @include shape-mixins.radius(
+      $radius,
+      $rtl-reflexive,
+      $component-height: $height,
+      $query: $query
+    );
   }
 }
 

packages/mdc-card/_mixins.scss

@@ -51,7 +51,7 @@
   @include elevation-mixins.overlay-common($query); // COPYBARA_COMMENT_THIS_LINE
 
   .mdc-card {
-    @include shape-radius(medium, $query: $query);
+    @include shape-radius(variables.$shape-radius, $query: $query);
     @include fill-color(surface, $query);
     @include elevation-mixins.overlay-surface-position($query: $query);
     @include elevation-mixins.overlay-dimensions(100%, $query: $query);

packages/mdc-card/_variables.scss

@@ -27,3 +27,4 @@
 $action-icon-color: rgba(variables.prop-value(on-surface), variables.text-emphasis(medium)) !default;
 $outline-color: color.mix(variables.prop-value(on-surface), variables.prop-value(surface), 12%) !default;
 $outline-width: 1px !default;
+$shape-radius: medium !default;

packages/mdc-chips/_mixins.scss

@@ -63,7 +63,7 @@ $ripple-target: ".mdc-chip__ripple";
   @include elevation-mixins.overlay-common($query); // COPYBARA_COMMENT_THIS_LINE
 
   .mdc-chip {
-    @include shape-radius(50%, $query: $query);
+    @include shape-radius(variables.$shape-radius, $query: $query);
     @include fill-color(variables.$fill-color-default, $query: $query);
     @include ink-color-without-ripple_(variables.$ink-color-default, $query: $query);
     @include typography-mixins.typography(body2, $query: $query);
@@ -345,14 +345,16 @@ $ripple-target: ".mdc-chip__ripple";
   );
 
   @include shape-mixins.radius(
-    shape-functions.resolve-percentage-radius($height, $radius),
+    $radius,
     $rtl-reflexive,
+    $component-height: $height,
     $query: $query);
 
   #{$ripple-target} {
     @include shape-mixins.radius(
-      shape-functions.resolve-percentage-radius($height, $radius),
+      $radius,
       $rtl-reflexive,
+      $component-height: $height,
       $query: $query
     );
   }

packages/mdc-chips/_variables.scss

@@ -29,6 +29,7 @@ $fill-color-default: color.mix(theme-variables.prop-value(on-surface), theme-var
 $ink-color-default: rgba(theme-variables.prop-value(on-surface), .87) !default;
 $horizontal-padding: 12px !default;
 $height: 32px !default;
+$shape-radius: 50% !default;
 
 $minimum-height: 24px !default;
 $maximum-height: $height !default;

packages/mdc-dialog/_mixins.scss

@@ -67,7 +67,7 @@
     @include min-width(variables.$min-width, $query: $query);
     @include max-width(variables.$max-width, variables.$margin, $query: $query);
     @include max-height(null, variables.$margin, $query: $query);
-    @include shape-radius(medium, $query: $query);
+    @include shape-radius(variables.$shape-radius, $query: $query);
 
     @include feature-targeting-mixins.targets($feat-structure) {
       // Use `display: none` instead of `visibility: hidden` to avoid recalculating layout when the dialog is closed.

packages/mdc-dialog/_variables.scss

@@ -33,6 +33,7 @@ $scroll-divider-opacity: .12 !default;
 $min-width: 280px !default;
 $max-width: 560px !default;
 $margin: 16px !default;
+$shape-radius: medium !default;
 $title-bottom-padding: 9px !default;
 $actions-padding: 8px !default;
 

packages/mdc-drawer/_mixins.scss

@@ -21,6 +21,7 @@
 //
 
 @use "sass:list";
+@use "sass:meta";
 @use "@material/feature-targeting/functions";
 @use "@material/feature-targeting/mixins" as feature-targeting-mixins;
 @use "@material/animation/functions" as functions2;
@@ -54,8 +55,8 @@
     @include item-text-ink-color(variables.$item-inactive-ink-color, $query: $query);
     @include item-activated-icon-ink-color(variables.$item-activated-ink-color, $query: $query);
     @include item-activated-text-ink-color(variables.$item-activated-ink-color, $query: $query);
-    @include shape-radius(large, $query: $query);
-    @include item-shape-radius(4px, $query: $query);
+    @include shape-radius(variables.$shape-radius, $query: $query);
+    @include item-shape-radius(variables.$item-shape-radius, $query: $query);
     @include z-index(variables.$z-index, $query: $query);
     @include width(variables.$width, $query: $query);
 
@@ -281,9 +282,11 @@
 }
 
 @mixin shape-radius($radius, $query: functions.all()) {
-  @if list.length($radius) > 2 {
+  // Check type since $radius may be a custom property Map
+  $is-list: meta.type-of($radius) == "list";
+  @if $is-list and list.length($radius) > 2 {
     @error "Invalid radius: '#{$radius}' component doesn't allow customizing all corners";
-  } @else if list.length($radius) == 2 {
+  } @else if $is-list and list.length($radius) == 2 {
     $radius: 0 list.nth($radius, 1) list.nth($radius, 2) 0;
   } @else {
     $radius: 0 $radius $radius 0;

packages/mdc-drawer/_variables.scss

@@ -43,6 +43,8 @@ $divider-opacity: .12 !default;
 $width: 256px !default;
 $list-item-spacing: 4px !default;
 $surface-padding: 16px !default;
+$shape-radius: large !default;
+$item-shape-radius: small !default;
 
 // Animations
 $animation-enter: 250ms !default;

packages/mdc-fab/_mixins.scss

@@ -213,6 +213,9 @@ $ripple-target: ".mdc-fab__ripple";
 
 @mixin shape-radius($radius, $rtl-reflexive: false, $query: feature-targeting-functions.all()) {
   &:not(.mdc-fab--extended) {
+    // Do not specify $component-height for shape radius. FABs are circular,
+    // which means they can use percentage border radius without resolving to
+    // a component height.
     @include shape-mixins.radius($radius, $rtl-reflexive, $query: $query);
 
     #{$ripple-target} {
@@ -222,16 +225,20 @@ $ripple-target: ".mdc-fab__ripple";
 }
 
 @mixin extended-shape-radius($radius, $rtl-reflexive: false, $query: feature-targeting-functions.all()) {
+  // Extended FABs _do_ need a $component-height since they are not circular.
+  // Percentage radii must be resolved.
   @include shape-mixins.radius(
-    shape-functions.resolve-percentage-radius(variables.$extended-height, $radius),
+    $radius,
     $rtl-reflexive,
+    $component-height: variables.$extended-height,
     $query: $query
   );
 
   #{$ripple-target} {
     @include shape-mixins.radius(
-      shape-functions.resolve-percentage-radius(variables.$extended-height, $radius),
+      $radius,
       $rtl-reflexive,
+      $component-height: variables.$extended-height,
       $query: $query
     );
   }
@@ -244,7 +251,7 @@ $icon-enter-duration_: 180ms;
   @include elevation-mixins.overlay-surface-position($query: $query);
   @include elevation-mixins.overlay-dimensions(100%, $query: $query);
   @include elevation-mixins.elevation(6, $query: $query);
-  @include shape-radius(50%, $query: $query);
+  @include shape-radius(variables.$shape-radius, $query: $query);
 
   $feat-animation: feature-targeting-functions.create-target($query, animation);
   $feat-structure: feature-targeting-functions.create-target($query, structure);
@@ -334,7 +341,7 @@ $icon-enter-duration_: 180ms;
 
 @mixin extended_($query: feature-targeting-functions.all()) {
   @include typography-mixins.typography(button, $query: $query);
-  @include extended-shape-radius(50%, $query: $query);
+  @include extended-shape-radius(variables.$shape-radius, $query: $query);
   @include extended-padding(variables.$extended-icon-padding, variables.$extended-label-padding, $query: $query);
 
   $feat-structure: feature-targeting-functions.create-target($query, structure);

packages/mdc-fab/_variables.scss

@@ -25,3 +25,4 @@ $extended-label-padding: 20px !default;
 $height: 56px !default;
 $mini-height: 40px !default;
 $extended-height: 48px !default;
+$shape-radius: 50% !default;

packages/mdc-image-list/_mixins.scss

@@ -79,7 +79,7 @@
   }
 
   @include aspect(1, $query: $query);
-  @include shape-radius(0, $query: $query);
+  @include shape-radius(variables.$shape-radius, $query: $query);
 
   .mdc-image-list__supporting {
     @include feature-targeting-mixins.targets($feat-color) {

packages/mdc-image-list/_variables.scss

@@ -24,3 +24,4 @@ $icon-size: 24px !default;
 $text-protection-background-color: rgba(0, 0, 0, .6) !default;
 $text-protection-height: 48px !default;
 $text-protection-horizontal-padding: 16px !default;
+$shape-radius: 0 !default;

packages/mdc-list/_mixins.scss

@@ -398,10 +398,13 @@
     $property-name: height,
   );
 
-  $resolved-radius: shape-functions.resolve-percentage-radius($height, $radius);
-
   .mdc-list-item {
-    @include shape-mixins.radius($resolved-radius, $rtl-reflexive, $query: $query);
+    @include shape-mixins.radius(
+      $radius,
+      $rtl-reflexive,
+      $component-height: $height,
+      $query: $query
+    );
   }
 }
 

packages/mdc-menu-surface/_mixins.scss

@@ -42,7 +42,7 @@
     @include elevation-mixins.elevation($z-value: 8, $query: $query);
     @include fill-color(surface, $query);
     @include ink-color(on-surface, $query);
-    @include shape-radius(medium, false, $query);
+    @include shape-radius(variables.$shape-radius, false, $query);
 
     @include feature-targeting-mixins.targets($feat-structure) {
       @include rtl-mixins.reflexive-property(transform-origin, top left, top right);

packages/mdc-menu-surface/_variables.scss

@@ -25,3 +25,4 @@ $fade-out-duration: .075s !default;
 $scale-duration: .12s !default;
 $min-distance-from-edge: 32px !default;
 $z-index: 8 !default; // One above mdc-dialog
+$shape-radius: medium !default;

packages/mdc-shape/README.md

@@ -38,7 +38,7 @@ npm install @material/shape
 
 ### Sass Variables
 
-Components are categorized as small, medium and large in shape system. Overriding below sass variables applies shape (rounded) to respective categories. For example, overriding `$medium-radius` variable would apply shape to all components that belong to medium category.
+Components are categorized as small, medium, and large in the Material shape system. Overriding the below Sass variables will change all components in their respective categories.
 
 Variable | Description
 --- | ---
@@ -48,22 +48,32 @@ Variable | Description
 
 Please refer [Material Design guidelines: Shape](https://material.io/go/design-shape) to learn about how components are categorized.
 
+**Note: Only rounded shape designs are currently supported.**
+
+### CSS Custom Properties
+
+CSS Custom Property | Description
+--- | ---
+`--mdc-shape-small` | Rounded shape radius size for small components. Default value `4px`.
+`--mdc-shape-medium` | Rounded shape radius size for small components. Default value `4px`.
+`--mdc-shape-large` | Rounded shape radius size for small components. Default value `0`.
+
+**Note: Do not use percentage values with custom properties, since they cannot be resolved by `shape.radius()` at runtime.**
+
 ### Sass Mixins
 
 Mixin | Description
 --- | ---
 `radius($radius, $rtl-reflexive)` | Shape API used by all other components to apply radius to appropriate corners. `$radius` can be single value or list of up to 4 radius corner values. Set `$rtl-reflexive` to true to flip the radius in RTL case, `false` by default.
 
-> Use `resolve-percentage-radius` sass function to resolve percentage unit value to absolute radius value.
-
 ### Sass Functions
 
 Function | Description
 --- | ---
+`resolve-radius($radius, $component-height)` | Returns the resolved radius value of a shape category - `large`, `medium`, or `small`. If $radius is not a category, this function returns the value itself if valid. Valid values are numbers or percentages. `$component-height` should be provided if `$radius` may be a percentage.
 `flip-radius($radius)` | Flips the radius values in RTL context. `$radius` is list of 2-4 corner values.
-`resolve-percentage-radius($component-height, $radius)` | Calculates the absolute radius value based on its component height. Use this for fixed height components only.
 `mask-radius($radius, $masked-corners)` | Accepts radius number or list of 2-4 radius values and returns 4 value list with masked corners as mentioned in `$masked-corners`.
-`prop-value($radius)` | Returns `$radius` value of shape category - `large`, `medium` or `small`. Otherwise, it returns the `$radius` itself if valid. `$radius` can be a single value or list of up to 4.
+`unpack-radius($radius)` | Unpacks shorthand values for border-radius (i.e. lists of 1-3 values). If a list of 4 values is given, it is returned as-is.
 
 ### Additional Information
 
@@ -74,10 +84,10 @@ Styles for applying shape to a fixed height component such as button looks like
 ```scss
 @use "@material/button";
 
-@include shape.radius(shape.resolve-percentage-radius(button.$height, $radius));
+@include shape.radius($radius, $component-height: button.$height);
 ```
 
-Where, `button.$height` is the height of standard button and `$radius` is the size of shape. `resolve-percentage-radius` function is used to resolve percentage unit value to absolute `$radius` value based on component height.
+Where `button.$height` is the height of standard button and `$radius` is the size of the shape. `shape.radius()` will resolve any percentage unit value to an absolute radius value based on the component's height.
 
 #### Shapes for dynamic height components
 
@@ -87,7 +97,7 @@ Styles for applying shapes to dynamic height component such as card looks like t
 @include shape.radius($radius);
 ```
 
-Where, `$radius` is absolute value only.
+Where `$radius` is an absolute value only.
 
 #### Shapes for components on specific corners
 
@@ -97,11 +107,11 @@ Styles for applying shapes for specific corners such as drawer looks like this:
 @include shape.radius(0 $radius $radius 0, $rtl-reflexive: true);
 ```
 
-Where, only top-right & bottom-right corners are customizable and it automatically flips radius values based on RTL context when `$rtl-reflexive` is set to true.
+Where only top-right & bottom-right corners are customizable. `shape.radius()` will automatically flip radius values based on RTL context if `$rtl-reflexive` is set to true.
 
 #### Component theming
 
-The styles for applying custom shape to button component instance looks like this:
+The styles for applying custom shape to a button component looks like this:
 
 ```scss
 @use "@material/button";
@@ -111,6 +121,6 @@ The styles for applying custom shape to button component instance looks like thi
 }
 ```
 
-In this example, the above styles applies 50% (pill) shape to button. It can also be absolute value (e.g., `8px`);
+In this example, the above style applies a 50% pill shape to the button. It could also be an absolute value (e.g., `8px`);
 
-> You would indirectly use the Shape API through respective component's mixin which takes care of applying radius to applicable corners for all its variants.
+> The Shape API is typically used indirectly through each respective component's mixin, which takes care of setting height and applying radius to applicable corners for all of its variants.