feat(b-form-rating): add show-value-max prop to show possible max rating when show-value is true (#5200)

* feat(b-form-rating): add `show-max-value` prop to show possible max rating when `show-value` is `true`

* Update form-rating.js

* Update form-rating.js

* Update package.json

* lint

* Update form-rating.js

* Update form-rating.spec.js

* Update form-rating.js

* Update README.md

* Update README.md

* Update README.md

Co-authored-by: Jacob Müller <jacob.mueller.elz@gmail.com>

Author: tmorehouse

src/components/form-rating/README.md

@@ -12,7 +12,7 @@ inside [input groups](/docs/components/input-group).
 There are two main modes for `<b-form-rating>`: interactive and readonly.
 
 Interactive mode allows the user to chose a rating from `1` to the number of stars (default `5`) in
-whole number increments.
+_whole number_ increments.
 
 **Interactive rating (input mode):**
 
@@ -209,6 +209,39 @@ decimal) simply set the `precision` prop to the number of digits after the decim
 <!-- b-form-rating-value-precision.vue -->
 ```
 
+#### Show maximum value
+
+<span class="badge badge-info small">2.13.0+</span>
+
+Optionally show the maximum rating possible by also setting the prop `show-value-max` to `true`:
+
+```html
+<template>
+  <div>
+    <b-form-rating
+      v-model="value"
+      readonly
+      show-value
+      show-value-max
+      precision="2"
+    ></b-form-rating>
+    <p class="mt-2">Value: {{ value }}</p>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        value: 3.555
+      }
+    }
+  }
+</script>
+
+<!-- b-form-rating-value-max.vue -->
+```
+
 ### Control sizing
 
 Fancy a small or large rating control? Simply set the prop `size` to either `'sm'` or `'lg'`

src/components/form-rating/form-rating.js

@@ -127,6 +127,10 @@ export const BFormRating = /*#__PURE__*/ Vue.extend({
       type: Boolean,
       default: false
     },
+    showValueMax: {
+      type: Boolean,
+      default: false
+    },
     disabled: {
       type: Boolean,
       default: false
@@ -216,15 +220,22 @@ export const BFormRating = /*#__PURE__*/ Vue.extend({
       return isLocaleRTL(this.computedLocale)
     },
     formattedRating() {
-      const value = this.localValue
       const precision = toInteger(this.precision)
-      return isNull(value)
-        ? ''
-        : value.toLocaleString(this.computedLocale, {
-            notation: 'standard',
-            minimumFractionDigits: isNaN(precision) ? 0 : precision,
-            maximumFractionDigits: isNaN(precision) ? 3 : precision
-          })
+      const showValueMax = this.showValueMax
+      const locale = this.computedLocale
+      const formatOptions = {
+        notation: 'standard',
+        minimumFractionDigits: isNaN(precision) ? 0 : precision,
+        maximumFractionDigits: isNaN(precision) ? 3 : precision
+      }
+      const stars = this.computedStars.toLocaleString(locale)
+      let value = this.localValue
+      value = isNull(value)
+        ? showValueMax
+          ? '-'
+          : ''
+        : value.toLocaleString(locale, formatOptions)
+      return showValueMax ? `${value}/${stars}` : value
     }
   },
   watch: {

src/components/form-rating/form-rating.spec.js

@@ -252,6 +252,43 @@ describe('form-rating', () => {
     wrapper.destroy()
   })
 
+  it('has expected structure when prop `show-value` and `show-value-max` are set', async () => {
+    const wrapper = mount(BFormRating, {
+      propsData: {
+        showValue: true,
+        showValueMax: true,
+        value: '3.5',
+        precision: 2
+      }
+    })
+
+    expect(wrapper.isVueInstance()).toBe(true)
+    await waitNT(wrapper.vm)
+
+    const $stars = wrapper.findAll('.b-rating-star')
+    expect($stars.length).toBe(5)
+
+    const $value = wrapper.find('.b-rating-value')
+    expect($value.exists()).toBe(true)
+    expect($value.text()).toEqual('3.50/5')
+
+    wrapper.setProps({
+      value: null
+    })
+    await waitNT(wrapper.vm)
+
+    expect($value.text()).toEqual('-/5')
+
+    wrapper.setProps({
+      value: '1.236'
+    })
+    await waitNT(wrapper.vm)
+
+    expect($value.text()).toEqual('1.24/5')
+
+    wrapper.destroy()
+  })
+
   it('focus and blur methods work', async () => {
     const wrapper = mount(BFormRating, {
       attachToDocument: true,

src/components/form-rating/package.json

@@ -36,6 +36,11 @@
             "prop": "showValue",
             "description": "When `true` shows the current rating value in the control"
           },
+          {
+            "prop": "showValueMax",
+            "version": "2.13.0",
+            "description": "When set to `true` and prop `show-value` is `true`, includes the maximum star rating possible in the formatted value"
+          },
           {
             "prop": "noBorder",
             "description": "When `true` disables the default border"