Allow chart descriptions for Insights

- A `description` field can now be added to the configuration to
  describe the chart in question
- This field is not required so previous configuration without a
  `description` will work as normal

changelogs/unreleased/insights-description-for-chart.yml

+---
+title: Allow chart descriptions for Insights
+merge_request: 25686
+author:
+type: added

doc/user/project/insights/index.md

@@ -61,6 +61,7 @@ bugsCharts:
   title: "Charts for bugs"
   charts:
     - title: "Monthly bugs created"
+      description: "Open bugs created per month"
       type: bar
       query:
         issuable_type: issue
@@ -77,6 +78,7 @@ For example, here's single chart definition:
 
 ```yaml
 - title: "Monthly bugs created"
+  description: "Open bugs created per month"
   type: bar
   query:
     issuable_type: issue
@@ -96,6 +98,7 @@ The following table lists available parameters for charts:
 | Keyword                                            | Description |
 |:---------------------------------------------------|:------------|
 | [`title`](#title)                                  | The title of the chart. This will displayed on the Insights page. |
+| [`description`](#description)                      | A description for the individual chart. This will be displayed above the relevant chart. |
 | [`type`](#type)                                    | The type of chart: `bar`, `line` or `stacked-bar`. |
 | [`query`](#query)                                  | A hash that defines the conditions for issues / merge requests to be part of the chart. |
 
@@ -114,6 +117,17 @@ monthlyBugsCreated:
   title: "Monthly bugs created"
 ```
 
+### `description`
+
+The `description` text is displayed above the chart, but below the title. It's used
+to give extra details regarding the chart, for example:
+
+```yaml
+monthlyBugsCreated:
+  title: "Monthly bugs created"
+  description: "Open bugs created per month"
+```
+
 ### `type`
 
 `type` is the chart type.
@@ -145,6 +159,7 @@ Example:
 ```yaml
 monthlyBugsCreated:
   title: "Monthly bugs created"
+  description: "Open bugs created per month"
   type: bar
   query:
     issuable_type: issue
@@ -283,6 +298,7 @@ a group's insights:
 ```yaml
 monthlyBugsCreated:
   title: "Monthly bugs created"
+  description: "Open bugs created per month"
   type: bar
   query:
     issuable_type: issue
@@ -311,6 +327,7 @@ bugsCharts:
   title: "Charts for bugs"
   charts:
     - title: "Monthly bugs created"
+      description: "Open bugs created per month"
       type: bar
       <<: *projectsOnly
       query:

ee/app/assets/javascripts/insights/components/insights_chart.vue

@@ -31,6 +31,11 @@ export default {
       required: false,
       default: '',
     },
+    description: {
+      type: String,
+      required: false,
+      default: '',
+    },
     data: {
       type: Object,
       required: true,
@@ -111,6 +116,7 @@ export default {
 <template>
   <resizable-chart-container v-if="loaded" class="insights-chart">
     <h5 class="text-center">{{ title }}</h5>
+    <p v-if="description" class="text-center">{{ description }}</p>
     <gl-column-chart
       v-if="isColumnChart"
       v-bind="$attrs"

ee/app/assets/javascripts/insights/components/insights_page.vue

@@ -76,11 +76,12 @@ export default {
       <h4 class="text-center">{{ pageConfig.title }}</h4>
       <div v-if="!pageLoading" class="insights-charts" data-qa-selector="insights_charts">
         <insights-chart
-          v-for="({ loaded, type, data, error }, key, index) in chartData"
+          v-for="({ loaded, type, description, data, error }, key, index) in chartData"
           :key="index"
           :loaded="loaded"
           :type="type"
           :title="key"
+          :description="description"
           :data="data"
           :error="error"
         />

ee/app/assets/javascripts/insights/stores/modules/insights/mutations.js

@@ -21,10 +21,11 @@ export default {
   },
 
   [types.RECEIVE_CHART_SUCCESS](state, { chart, data }) {
-    const { type } = chart;
+    const { type, description } = chart;
 
     state.chartData[chart.title] = {
       type,
+      description,
       data: transformChartDataForGlCharts(chart, data),
       loaded: true,
     };

ee/spec/frontend/insights/stores/insights/mutations_spec.js

@@ -10,6 +10,7 @@ describe('Insights mutations', () => {
   const chart = {
     title: 'Bugs Per Team',
     type: CHART_TYPES.STACKED_BAR,
+    description: 'Chart Description',
     query: {
       name: 'filter_issues_by_label_category',
       filter_label: 'bug',
@@ -136,6 +137,14 @@ describe('Insights mutations', () => {
 
       expect(chartData[chart.title].type).toBe(chart.type);
     });
+
+    it('sets charts description to incoming type on success', () => {
+      mutations[types.RECEIVE_CHART_SUCCESS](state, { chart, data: incomingData });
+
+      const { chartData } = state;
+
+      expect(chartData[chart.title].description).toBe(chart.description);
+    });
   });
 
   describe(types.RECEIVE_CHART_ERROR, () => {