feat: enhance documentation for legend and progress properties

Signed-off-by: Sergej Atamantschuk <[email protected]>

Author: setaman

guide/options/legend.md

@@ -15,15 +15,19 @@ head:
 |------------------|----------------------------------------------------|---------|
 | Number \| String | any number with `.` or `","` as decimals delimiter |         |
 
-The `legend` property can be any Number or String.
-While [`progress`](progress.md) only accepts values between -100 and 100, `legend` lets you go beyond that range. You
-can even use `"."` or `","` as a delimiter for simple formatting, or set an initial counter-placeholder like "0045.00".
-Just make sure it's a valid JavaScript Number.
+The `legend` property is used to display a value inside the circle.
+It accepts any Number or String, allowing for flexible formatting options.
+
+This property is useful when you want to display values beyond the typical
+progress range of -100 to 100, apply custom formatting, or show initial counter values with leading zeros.
+
+You can use `"."` or `","` as a delimiter for simple formatting, or set an initial
+counter-placeholder like "0045.00". Just ensure it's a valid JavaScript Number.
 
 ::: warning Legend vs progress
 The [`progress`](progress.md) property is always required. When both `legend` and [`progress`](progress.md) are defined,
-`legend` will take over as the displayed value inside the circle!
-How you calculate the [`progress`](progress.md) based on the `legend` value is entirely up to you.
+`legend` will take over as the displayed value inside the
+circle. The `progress` property is still required and should be calculated based on the `legend` value as needed.
 :::
 
 ::: tip
@@ -36,7 +40,6 @@ Use the [`hideLegend`](hideLegend.md) property.
 ###### Usage: 📜
 
 ```vue
-
 <ve-progress :legend="150" />
 <ve-progress legend="020" />
 <ve-progress legend="200,50" />
@@ -58,10 +61,10 @@ The `progress` is calculated as a percentage of the `legend` value
 
 ```js-vue
 <template>
-  <ve-progress :legend="{{ slider }}" :progress="{{ progress }}"/>
+  <ve-progress :legend="legend" :progress="{{ progress }}"/>
 </template>
 <script setup>
-  import { ref } from "vue";
+  import { ref, computed } from "vue";
 
   const maxLegendValue = 4000;
   const legend = ref({{ slider }});
@@ -88,7 +91,6 @@ const progress = rating * 100 / 5; // the rating percentage
 And then apply the values:
 
 ```vue
-
 <ve-progress :progress="progress" :legend="rating" />
 ```
 
@@ -99,10 +101,10 @@ As a result, the rating can be displayed as a circle legend, and the progress wi
 
 ```js-vue
 <template>
-  <ve-progress :legend="{{ slider }}" :progress="{{ progress }}"/>
+  <ve-progress :legend="stars" :progress="{{ progress }}"/>
 </template>
 <script setup>
-  import { ref } from "vue";
+  import { ref, computed } from "vue";
 
   const maxStars = 5;
   const stars = ref({{ slider }});
@@ -116,7 +118,7 @@ As a result, the rating can be displayed as a circle legend, and the progress wi
 </template>
 </LegendAndProgress>
 
-With the `legend` as a String, you can use custom decimal delimiters and easily format the displayed value:
+With the `legend` is a String, you can use custom decimal delimiters and easily format the displayed value:
 
 <LegendFormatting class="mb-10">
 <template #code="{ progress }">

guide/options/legendFormatter.md

@@ -1,5 +1,5 @@
 ---
-description: Function that returns formatted value as string.
+description: Function that returns formatted value as string
 aside: false
 head:
   - - meta
@@ -11,20 +11,23 @@ head:
 
 <Badge class="mt-2" type="success" text="Animated" />
 
-| type     | values                                                                    | default |
-|----------|---------------------------------------------------------------------------|---------|
-| Function | `(props: object) => string` Function returning formatted value  as string |         |
+| type     | values                                                                   | default |
+|----------|--------------------------------------------------------------------------|---------|
+| Function | `(props: object) => string` Function returning formatted value as string |         |
 
-You can provide a function to format the circle legend. The function can return any string
-value, even HTML!
-You have full freedom to format the value of the [`legend`](legend.md) or [`progress`](progress.md) as you like.
+The `legendFormatter` property allows you to provide a custom function to format the circle legend displayed in the
+center of the circle.
+This function can
+return any string value, including HTML, giving you full control over the legend's appearance.
 
-The circle legend is animated and counts up and down depending on the circle [`animation`](animation.md) configuration.
-The function takes a counter properties object as an argument and is
-called on every counter tick providing the current value of the counter that can be used to format the legend.
+The circle legend is animated according to the circle's [`animation`](animation.md) configuration.
+The `legendFormatter` will be called on every animation tick, providing the current value of the counter that can be
+used to format the legend.
+The value of the counter at a specific animation tick represents the value that is passed as
+[`legend`](legend.md) or [`progress`](progress.md) to the circle.
 
 ::: tip
-Alternatively you can use [`scoped slot`](../slots/default.md) for custom formatting.
+Alternatively, you can use a [`scoped slot`](../slots/default.md) for custom formatting.
 :::
 
 ### Usage
@@ -35,10 +38,10 @@ Alternatively you can use [`scoped slot`](../slots/default.md) for custom format
 />
 ```
 
-| Exposed props           |                                                                                                                                                                                             |
-|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `currentValue`          | The current value of the counter at specific animation tick. It's always a Number and represents a value that is passed as [`legend`](legend.md) or [`progress`](progress.md) to the circle |
-| `currentFormattedValue` | Current value formatted as a String. It's a String representation of the `currentValue` including the formatting wich may be applied with [`legend`](legend.md)                             |
+| Exposed props           | Description                                                                                                                                                                                      |
+|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `currentValue`          | The current value of the counter at a specific animation tick. It's always a Number and represents the value that is passed as [`legend`](legend.md) or [`progress`](progress.md) to the circle. |
+| `currentFormattedValue` | The current value formatted as a String. It's a String representation of the `currentValue`, including any formatting applied with [`legend`](legend.md).                                        |
 
 ### Examples
 
@@ -48,7 +51,7 @@ Alternatively you can use [`scoped slot`](../slots/default.md) for custom format
   import LegendFormatterProps from "../../.vitepress/theme/Guide/LegendFormatter/LegendFormatterProps.vue";
 </script>
 
-In the following example, we take the raw `currentValue` value and format it as a string
+In the following example, we take the raw `currentValue` and format it as a string:
 
 <LegendFormatterBasic class="mb-10">
 <template #code="{ progress }">
@@ -63,8 +66,8 @@ In the following example, we take the raw `currentValue` value and format it as
 </template>
 </LegendFormatterBasic>
 
-The formatting function can return HTML as a string to customize the styles of the rendered circle legend.
-You can add more elements, images and pretty much anything here
+The formatting function can return HTML as a string to customize the styles of the rendered circle legend. You can add
+more elements, images, and pretty much anything here:
 
 <LegendFormatterHtml class="mb-10">
 <template #code>
@@ -91,8 +94,8 @@ You can add more elements, images and pretty much anything here
 </template>
 </LegendFormatterHtml>
 
-The internal counter component provides additional properties that might be useful. The properties are calculated for
-each counter tick.
+The internal counter component provides additional properties that might be useful. These properties are calculated for
+each counter tick:
 
 <LegendFormatterProps>
 <template #code="{ progress, legend }">

guide/options/progress.md

@@ -1,5 +1,5 @@
 ---
-description: The progress property takes a Number value in the range [-100, 100] and defines the filled area from progress circle line in percent.
+description: The progress property takes a Number value in the range [-100, 100] and defines the filled area from progress circle line in percent. It is used to visually represent the progress of a task or process.
 aside: false
 head:
   - - meta
@@ -15,20 +15,25 @@ head:
 |--------|-------------|---------|
 | Number | [-100, 100] |         |
 
-The `progress` property takes a Number value in the range \[-100, 100] and defines the filled area from progress circle
-line in percent. By default, `progress` is shown as the **legend** in the middle of the circle. 
-`progress` is animated
-and counts up or down on any value changes with duration defined in **[`animation.duration`](animation.md)** property. 
+The `progress` property takes a Number value in the range \[-100, 100] and defines the filled area from the progress
+circle line in percent. 
+By default, `progress` is shown as the **legend** in the middle of the circle.
 
-A negative value can be used to fill the progress line counterclockwise. Alternatively the same effect can be achieved
+`progress` is animated and counts up or down on any value changes with duration defined in 
+**[`animation.duration`](animation.md)** property.
+
+A negative value can be used to fill the progress line counterclockwise. 
+Alternatively, the same effect can be achieved
 with the **[`reverse`](reverse.md)** property.
 
 ::: warning Progress and Legend
-The `progress` is always used to fill the progress circle line, it should be always in the range [-100, 100] and
-not valid Numbers lead to **[`noData`](noData)** state. For advanced use cases please use **[`legend`](legend.md)**
+The `progress` is always used to fill the progress circle line, it should always be in the range [-100, 100] and invalid
+Numbers lead to **[`noData`](noData)** state. 
+If you want to customize and style what the circle legend displays, you can use the **[`legend`](legend.md)** property,
+For advanced use cases, please use **[`legend`](legend.md)** 
 and take a look at **[`legendFormatter`](legendFormatter.md)** or the **[`default slot`](../slots/default.md)**.
 
-If **[`legend`](legend.md)** is defined the `progress` will **not** be displayed as the circle legend.
+If **[`legend`](legend.md)** is defined, the `progress` will **not** be displayed as the circle legend.
 :::
 
 ###### Usage: 📜