[QA] Add unit tests and examples for kpi_card and `kpi_card_referen…

…ce` (#529) Co-authored-by: Jo Stichbury <[email protected]> Co-authored-by: Antony Milne <[email protected]>
mckinsey · Jun 21, 2024 · c998e8e · c998e8e
1 parent af12fc6
commit c998e8e
Show file tree

Hide file tree

Showing 20 changed files with 730 additions and 245 deletions.
diff --git a/vizro-core/changelog.d/20240607_125345_huong_li_nguyen_create_kpi_cards.md b/vizro-core/changelog.d/20240607_125345_huong_li_nguyen_create_kpi_cards.md
@@ -8,7 +8,7 @@ Uncomment the section that is right (remove the HTML comment wrapper).
 
 - Introduce `Figure` as a new `Page` component, enabling all Dash components to be reactive in
   `Vizro`. See the [user guide on figure](https://vizro.readthedocs.io/en/stable/pages/user-guides/figure/) for more information. ([#493](https://github.com/mckinsey/vizro/pull/493), [#524](https://github.com/mckinsey/vizro/pull/524))
-- Introduce styled KPI cards to be used inside `Figure`. See the [user guide on KPI cards](XXXX) for more information. ([#493](https://github.com/mckinsey/vizro/pull/493))
+- Introduce KPI card functions to be used inside `Figure`. See the [user guide on KPI cards](https://vizro.readthedocs.io/en/stable/pages/user-guides/figure#key-performance-indicator-kpi-cards) for more information. ([#493](https://github.com/mckinsey/vizro/pull/493), [#529](https://github.com/mckinsey/vizro/pull/529))
 
 <!--
 ### Removed

diff --git a/vizro-core/changelog.d/20240620_145740_huong_li_nguyen_add_kpi_card.md b/vizro-core/changelog.d/20240620_145740_huong_li_nguyen_add_kpi_card.md
@@ -0,0 +1,48 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Highlights ✨
+
+- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Removed
+
+- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Changed
+
+- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
diff --git a/vizro-core/docs/assets/user_guides/components/card_icon.png b/vizro-core/docs/assets/user_guides/components/card_icon.png
diff --git a/vizro-core/docs/assets/user_guides/components/nav_card_icon.png b/vizro-core/docs/assets/user_guides/components/nav_card_icon.png
diff --git a/vizro-core/docs/assets/user_guides/figure/kpi_cards.png b/vizro-core/docs/assets/user_guides/figure/kpi_cards.png
diff --git a/vizro-core/docs/pages/user-guides/card-button.md b/vizro-core/docs/pages/user-guides/card-button.md
@@ -326,13 +326,19 @@ and give an attribute selector to select images with that matching URL hash.
 
 ???+ tip
 
-    Use the following pre-defined URL hashes in your image path to have the image float next to the text:
+    Use the following pre-defined URL hashes in your image path to apply Vizro's default styling.
+
+    To float the image next to the text:
 
     - floating-left: `![](my_image.png#floating-left)`
     - floating-right: `![](my_image.png#floating-right)`
     - floating-center: `![](my_image.png#floating-center)`
 
-!!! example "Card with floating image"
+    To apply the default icon styling:
+
+    - icon-top: `![](my_image.png#icon-top)`
+
+??? example "Card with floating image"
     === "app.py"
         ```py
         import vizro.models as vm
@@ -396,62 +402,29 @@ and give an attribute selector to select images with that matching URL hash.
 
     [CardImageFloating]: ../../assets/user_guides/components/card_image_floating.png
 
-### Create a navigation card
-
-!!! note
-
-    This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation
-    card. To configure the navigation panel on the left hand side of the screen, refer to the
-    [guide on navigation](navigation.md).
-
-
-A navigation card enables you to navigate to a different page via a click on the card area.
-To create a navigation card, do the following:
-
-- Insert the [`Card`][vizro.models.Card] into the `components` argument of the [`Page`][vizro.models.Page]
-- Pass your markdown text to the `Card.text`
-- Pass a relative or absolute URL to the `Card.href`
-
-!!! example "Navigation Card"
+??? example "Card with icon"
     === "app.py"
         ```py
         import vizro.models as vm
-        import vizro.plotly.express as px
         from vizro import Vizro
 
-        iris = px.data.iris()
-
-        page_1 = vm.Page(
-            title="Homepage",
+        page = vm.Page(
+            title="Card with icon",
             components=[
                 vm.Card(
                     text="""
-                    ### Filters and parameters
+                    ![](assets/images/icons/hypotheses.svg#icon-top)
 
-                    Leads to the first page on click.
-                    """,
-                    href="/filters-and-parameters",
-                ),
-                vm.Card(
-                    text="""
-                    ### Google - External Link
+                    ### Card Title
 
-                    Leads to an external link on click.
+                    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
+                    Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
                     """,
-                    href="https://google.com",
                 ),
             ],
         )
 
-        page_2 = vm.Page(
-            title="Filters and parameters",
-            components=[
-                vm.Graph(id="scatter", figure=px.scatter(iris, x="sepal_length", y="petal_width", color="sepal_width")),
-            ],
-        )
-
-        dashboard = vm.Dashboard(pages=[page_1, page_2])
-
+        dashboard = vm.Dashboard(pages=[page])
         Vizro().build(dashboard).run()
         ```
     === "app.yaml"
@@ -461,52 +434,57 @@ To create a navigation card, do the following:
         pages:
         - components:
             - text: |
-                ### Filters and parameters
+                ![](assets/images/icons/hypotheses.svg#icon-top)
 
-                Leads to the first page on click
-              href: /filters-and-parameters
-              type: card
-            - text: |
-                ### Google - External Link
+                ### Card Title
 
-                Leads to an external link on click.
-              href: https://google.com
+                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut fringilla dictum lacus eget fringilla.
+                Maecenas in various nibh, quis venenatis nulla. Integer et libero ultrices, scelerisque velit sed.
               type: card
-          title: Homepage
-        - components:
-            - figure:
-                _target_: scatter
-                color: sepal_width
-                data_frame: iris
-                x: sepal_length
-                y: petal_width
-              id: scatter
-              type: graph
-          title: Filters and parameters
+          title: Card with icon
         ```
     === "Result"
-           [![NavCard]][NavCard]
+           [![CardIcon]][CardIcon]
 
-       [NavCard]: ../../assets/user_guides/components/nav_card.png
+       [CardIcon]: ../../assets/user_guides/components/card_icon.png
 
-If you now click on the card area, you should automatically be redirected to the relevant `href`.
 
-???+ note
+### Make an icon responsive to theme switch
 
-    When using the [`Card`][vizro.models.Card], keep the following considerations in mind:
+To make an icon responsive to the theme switch, override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter).
+The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme.
+It uses the  CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code.
+Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
 
-    - If the href given is a relative URL, it should match the `path` of the [`Page`][vizro.models.Page] that the [`Card`][vizro.models.Card] should navigate to.
-    - If the href given is an absolute link, it should start with `https://` or an equivalent protocol.
+```css
+img[src*="#my-image"] {
+  filter: var(--inverse-color);
+}
+```
+
+??? example "Responsive icon"
+    ![responsive icon](../../assets/user_guides/components/responsive_icon.gif)
+
+### Create a navigation card
 
+!!! note
+
+    This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation
+    card. To configure the navigation panel on the left hand side of the screen, refer to the
+    [guide on navigation](navigation.md).
 
-### Add an icon
-If you want to add an icon to your card, add your image as described in the [earlier section](#placing-images)
 
-If you use the image URL hash `icon-top`, the image will be styled according to our default icon styling.
+A navigation card enables you to navigate to a different page via a click on the card area.
 
-!!! example "Navigation Card with Icon"
+To create a navigation card:
+
+1. Insert the [`Card`][vizro.models.Card] into the `components` argument of the [`Page`][vizro.models.Page].
+2. Pass your markdown text to the `Card.text`.
+3. Pass a relative or absolute URL to the `Card.href`.
+
+!!! example "Navigation Card"
     === "app.py"
-        ```py hl_lines="12 23"
+        ```py
         import vizro.models as vm
         import vizro.plotly.express as px
         from vizro import Vizro
@@ -518,19 +496,14 @@ If you use the image URL hash `icon-top`, the image will be styled according to
             components=[
                 vm.Card(
                     text="""
-                    ![](assets/images/icons/content/hypotheses.svg#icon-top)
-
                     ### Filters and parameters
 
                     Leads to the first page on click.
                     """,
                     href="/filters-and-parameters",
                 ),
-
                 vm.Card(
                     text="""
-                    ![](assets/images/icons/content/features.svg#icon-top)
-
                     ### Google - External Link
 
                     Leads to an external link on click.
@@ -552,22 +525,18 @@ If you use the image URL hash `icon-top`, the image will be styled according to
         Vizro().build(dashboard).run()
         ```
     === "app.yaml"
-        ```yaml hl_lines="5 13"
+        ```yaml
         # Still requires a .py to add data to the data manager and parse YAML configuration
         # See from_yaml example
         pages:
         - components:
             - text: |
-                ![](assets/images/icons/content/hypotheses.svg#icon-top)
-
                 ### Filters and parameters
 
                 Leads to the first page on click
               href: /filters-and-parameters
               type: card
             - text: |
-                ![](assets/images/icons/content/features.svg#icon-top)
-
                 ### Google - External Link
 
                 Leads to an external link on click.
@@ -586,32 +555,27 @@ If you use the image URL hash `icon-top`, the image will be styled according to
           title: Filters and parameters
         ```
     === "Result"
-           [![NavCardIcon]][NavCardIcon]
-
-       [NavCardIcon]: ../../assets/user_guides/components/nav_card_icon.png
-
-Note that in the above example the first [`Card`][vizro.models.Card] navigates to an existing [`Page`][vizro.models.Page]
-in the app with `path = filters-and-parameters` and the second one to an external link.
+           [![NavCard]][NavCard]
 
-#### Add an icon responsive to theme switch
+       [NavCard]: ../../assets/user_guides/components/nav_card.png
 
-To add an icon that is responsive to the theme switch, you will need to override the value of the [`filter` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/filter).
+If you now click on the card area, you should automatically be redirected to the relevant `href`.
 
-The `filter` CSS property lets you add visual effects to elements using different functions. In our example, we're using the `--inverse-color` CSS variable from the Vizro theme.
+???+ note
 
-It uses the  CSS `invert()` function to flip the color of the icon when you switch themes. Note that this only works if your initial icon has a white fill color. If your icon is not white, you can change its color by adding `fill="white"` to the SVG code.
+    When using the [`Card`][vizro.models.Card], keep the following in mind:
 
-Assign the predefined CSS variable `--inverse-color` to the `filter` property of your selected icon.
+    - If the href given is a relative URL, it should match the `path` of the [`Page`][vizro.models.Page] that the [`Card`][vizro.models.Card] should navigate to.
+    - If the href given is an absolute link, it should start with `https://` or an equivalent protocol.
 
-```css
-img[src*="#my-image"] {
-  filter: var(--inverse-color);
-}
-```
 
-??? example "Responsive icon"
-    ![responsive icon](../../assets/user_guides/components/responsive_icon.gif)
+### Create a KPI card
+To create a KPI card, you can use the existing KPI card functions from [`vizro.figures`](../API-reference/figure-callables.md).
+Unlike the static text card `vm.Card`, a KPI card must be created using a figure function.
+Unlike the static text card `vm.Card`, a KPI card must be created using a figure function,
+which enables the text content of the KPI to change based on input from controls or actions.
 
+For detailed examples on how to create a KPI card, refer to the [figure user guide on KPI cards](figure.md#create-kpi-cards).
 
 ## Buttons
 

diff --git a/vizro-core/docs/pages/user-guides/custom-figures.md b/vizro-core/docs/pages/user-guides/custom-figures.md
@@ -32,7 +32,7 @@ If you wish to change the design or content of our existing KPI (key performance
 [`vizro.figures`](../API-reference/figure-callables.md), you can do so by following the steps described above.
 
 For instance, to make a KPI card with the icon positioned on the right side of the title instead of the left,
-copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md/#kpi_card) and
+copy and paste the [source code of `kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card) and
 adjust the return statement of the function.
 
 <!-- vale off -->
@@ -67,18 +67,14 @@ adjust the return statement of the function.
             title = title or f"{agg_func} {value_column}".title()
             value = data_frame[value_column].agg(agg_func)
 
-            return dbc.Card(
+            header = dbc.CardHeader(
                 [
-                    dbc.CardHeader(
-                        [
-                            html.H2(title),
-                            html.P(icon, className="material-symbols-outlined") if icon else None,  # (3)!
-                        ],
-                    ),
-                    dbc.CardBody([value_format.format(value=value)]),
-                ],
-                className="card-kpi",
+                    html.H2(title),
+                    html.P(icon, className="material-symbols-outlined") if icon else None,  # (3)!
+                ]
             )
+            body = dbc.CardBody([value_format.format(value=value)])
+            return dbc.Card([header, body], className="card-kpi")
 
 
         page = vm.Page(
@@ -114,7 +110,7 @@ adjust the return statement of the function.
         2. The custom figure function needs to have a `data_frame` argument and return a `Dash` component.
         3. We adjust the return statement to include the icon on the right side of the title. This is achieved by swapping the order of the `html.H2` and `html.P` compared to the original `kpi_card`.
         4. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first two cells, while the remaining cells are empty.
-        5. For more information, refer to the API reference for the  [`kpi_card`](../API-reference/figure-callables.md#kpi_card).
+        5. For more information, refer to the API reference for the  [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
         6. Our custom figure function `custom_kpi_card` now needs to be passed on to the `vm.Figure`.
 
     === "app.yaml"