Units: Custom unit suffix and docs for custom units (#25710)

* Units: Custom units updates and docs

* Fixed codespell

* Update docs/sources/panels/field-configuration-options.md

Co-authored-by: Peter Holmberg <peterholmberg@users.noreply.github.com>

* Update docs/sources/panels/field-configuration-options.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update docs/sources/panels/field-configuration-options.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update docs/sources/panels/field-configuration-options.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

Co-authored-by: Peter Holmberg <peterholmberg@users.noreply.github.com>
Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

docs/sources/panels/field-configuration-options.md

@@ -109,6 +109,7 @@ By default, Grafana automatically chooses display settings. You can override the
 This custom field option applies only to table visualizations.
 
 Choose how Grafana should align cell contents:
+
 - Auto (default)
 - Left
 - Center
@@ -138,7 +139,7 @@ For more information and instructions, refer to [Data links]({{< relref "../link
 
 Lets you set the display title of all fields. You can use [variables]({{< relref "../variables/templates-and-variables.md" >}}) in the field title.
 
-When multiple stats are shown, this field controls the title in each stat. By default this is the series name and field name. You can use expressions like ${__series.name} or ${__field.name} to use only series name or field name in title or ${__cell_2} to refer to other fields (2 being field/column with index 2).
+When multiple stats are shown, this field controls the title in each stat. By default this is the series name and field name. You can use expressions like ${__series.name} or ${**field.name} to use only series name or field name in title or \${**cell_2} to refer to other fields (2 being field/column with index 2).
 
 ### Max
 
@@ -156,6 +157,25 @@ Enter what Grafana should display if the field value is empty or null.
 
 Lets you choose what unit a field should use. Click in the **Unit** field, then drill down until you find the unit you want. The unit you select is applied to all fields except time.
 
+### Custom units
+
+You can use the unit dropdown to also specify custom units, custom prefix or suffix and date time formats.
+
+To select a custom unit enter the unit and select the last `Custom: xxx` option in the dropdown.
+
+- If y u want a space -> If you want a space
+- `suffix:<suffix>` for custom unit that should go after value.
+- `time:<format>` For custom date time formats type for example `time:YYYY-MM-DD`. See [formats](https://momentjs.com/docs/#/displaying/) for the format syntax and options.
+- `si:<base scale><unit characters>` for custom SI units. For example: `si: mF`. This one is a bit more advanced as you can specify both a unit and the
+  source data scale. So if your source data is represented as milli (thousands of) something prefix the unit with that
+  SI scale character.
+- `count:<unit>` for a custom count unit.
+- `currency:<unit>` for custom a currency unit.
+
+You can also paste a native emoji in the unit picker and pick it as a custom unit:
+
+{{< docs-imagebox img="/img/docs/v66/custom_unit_burger2.png" max-width="600px" caption="Custom unit emoji" >}}
+
 ### Thresholds
 
 Thresholds allow you to change the color of a field based on the value.
@@ -180,7 +200,7 @@ Here are some examples of how you might use this feature.
 Let’s assume that our result set is a data frame that consists of two fields: time and temperature.
 
 |        time         | temperature |
-|:--:|:--:|
+| :-----------------: | :---------: |
 | 2020-01-02 03:04:00 |    45.0     |
 | 2020-01-02 03:05:00 |    47.0     |
 | 2020-01-02 03:06:00 |    48.0     |
@@ -188,7 +208,7 @@ Let’s assume that our result set is a data frame that consists of two fields:
 Each field(column) of this structure can have field options applied that alter the way its values are displayed. This means that you can, for example, set the Unit to Temperature > Celsius, resulting in the following table:
 
 |        time         | temperature |
-|:--:|:--:|
+| :-----------------: | :---------: |
 | 2020-01-02 03:04:00 |   45.0 °C   |
 | 2020-01-02 03:05:00 |   47.0 °C   |
 | 2020-01-02 03:06:00 |   48.0 °C   |
@@ -196,7 +216,7 @@ Each field(column) of this structure can have field options applied that alter t
 While we're at it, the decimal place doesn't add anything to this display. You can change the Decimals from `auto` to zero (`0`), resulting in the following table:
 
 |        time         | temperature |
-|:--:|:--:|
+| :-----------------: | :---------: |
 | 2020-01-02 03:04:00 |    45 °C    |
 | 2020-01-02 03:05:00 |    47 °C    |
 | 2020-01-02 03:06:00 |    48 °C    |
@@ -206,7 +226,7 @@ While we're at it, the decimal place doesn't add anything to this display. You c
 Let’s assume that our result set is a data frame that consists of four fields: time, high temp, low temp, and humidity.
 
 | time                | high temp | low temp | humidity |
-|---------------------|-----------|----------|----------|
+| ------------------- | --------- | -------- | -------- |
 | 2020-01-02 03:04:00 | 45.0      | 30.0     | 67       |
 | 2020-01-02 03:05:00 | 47.0      | 34.0     | 68       |
 | 2020-01-02 03:06:00 | 48.0      | 31.0     | 68       |
@@ -214,7 +234,7 @@ Let’s assume that our result set is a data frame that consists of four fields:
 Let's apply the field options from the [field option example](#field-option-example) to apply the Celsius unit and get rid of the decimal place. This results in the following table:
 
 | time                | high temp | low temp | humidity |
-|---------------------|-----------|----------|----------|
+| ------------------- | --------- | -------- | -------- |
 | 2020-01-02 03:04:00 | 45 °C     | 30 °C    | 67 °C    |
 | 2020-01-02 03:05:00 | 47 °C     | 34 °C    | 68 °C    |
 | 2020-01-02 03:06:00 | 48 °C     | 31 °C    | 68 °C    |
@@ -222,7 +242,7 @@ Let's apply the field options from the [field option example](#field-option-exam
 The temperature fields look good, but the humidity is nonsensical. We can fix this by applying a field option override to the humidity field and change the unit to Misc > percent (0-100). This results in a table that makes a lot more sense:
 
 | time                | high temp | low temp | humidity |
-|---------------------|-----------|----------|----------|
+| ------------------- | --------- | -------- | -------- |
 | 2020-01-02 03:04:00 | 45 °C     | 30 °C    | 67%      |
 | 2020-01-02 03:05:00 | 47 °C     | 34 °C    | 68%      |
 | 2020-01-02 03:06:00 | 48 °C     | 31 °C    | 68%      |

packages/grafana-data/src/valueFormats/valueFormats.test.ts

@@ -48,6 +48,7 @@ const formatTests: ValueFormatTest[] = [
 
   // Prefix (unknown units append to the end)
   { id: 'prefix:b', value: 1532.82, result: 'b1533' },
+  { id: 'suffix:d', value: 1532.82, result: '1533 d' },
 
   // SI Units
   { id: 'si:µF', value: 1234, decimals: 2, result: '1.23 mF' },

packages/grafana-data/src/valueFormats/valueFormats.ts

@@ -198,6 +198,10 @@ export function getValueFormat(id?: string | null): ValueFormatter {
         return toFixedUnit(sub, true);
       }
 
+      if (key === 'suffix') {
+        return toFixedUnit(sub, false);
+      }
+
       if (key === 'time') {
         return toDateTimeValueFormatter(sub);
       }