[Feat] Add Figure model and introduce KPI card functions

vizro-core/changelog.d/20240607_125345_huong_li_nguyen_create_kpi_cards.md

@@ -0,0 +1,48 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+### Highlights ✨
+
+- Introduce `Figure` as a new `Page` component, enabling all dash components to be reactive in
+  `Vizro`. See the [user guide on figure](XXXX) for more information. ([#493](https://github.com/mckinsey/vizro/pull/493))
+- 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))
+
+<!--
+### 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))
+
+-->

vizro-core/docs/pages/API-reference/captured-callables.md

@@ -1,6 +1,5 @@
-# Table functions
-
 <!-- vale off -->
+# Table functions
 
 API reference for all pre-defined [`CapturedCallable`][vizro.models.types.CapturedCallable] table functions to be used in the
 [`AgGrid`][vizro.models.AgGrid] and [`Table`][vizro.models.Table] models. Visit the how-to guide on [tables](../user-guides/table.md)
@@ -10,5 +9,13 @@ for more information.
     options:
       show_source: true
 
+# Figure functions
+API reference for all pre-defined [`CapturedCallable`][vizro.models.types.CapturedCallable] figure functions to be used in the
+[`Figure`][vizro.models.Figure]. Visit the how-to guide on [figures](../user-guides/figure.md)
+for more information.
+
+::: vizro.figures
+    options:
+      show_source: true
 
 <!-- vale on -->

vizro-core/docs/pages/user-guides/components.md

@@ -12,38 +12,46 @@ listed below to fill your dashboard with visuals.
 
     Use graphs to visualize your data with any Plotly chart.
 
-    [:octicons-arrow-right-24: View User Guide](graph.md)
+    [:octicons-arrow-right-24: View user guide](graph.md)
 
 - :material-table-large:{ .lg .middle } __Table__
 
     ---
 
     Use tables to visualize your tabular data.
 
-    [:octicons-arrow-right-24: View User Guide](table.md)
+    [:octicons-arrow-right-24: View user guide](table.md)
 
 - :material-cards-outline:{ .lg .middle } __Card & button__
 
     ---
 
     Use cards and buttons to visualize text, navigate to different URLs or attach any [action](actions.md).
 
-    [:octicons-arrow-right-24: View User Guide](card-button.md)
+    [:octicons-arrow-right-24: View user guide](card-button.md)
+
+- :material-graph:{ .lg .middle } __Figure__
+
+    ---
+
+    Use figure to visualize your make any dash component reactive.
+
+    [:octicons-arrow-right-24: View user guide](figure.md)
 
 - :octicons-table-16:{ .lg .middle } __Container__
 
     ---
 
     Use containers to group your page components into sections and subsections.
 
-    [:octicons-arrow-right-24: View User Guide](container.md)
+    [:octicons-arrow-right-24: View user guide](container.md)
 
 - :material-tab-plus:{ .lg .middle } __Tabs__
 
     ---
 
     Use tabs to group your containers and navigate between them.
 
-    [:octicons-arrow-right-24: View User Guide](tabs.md)
+    [:octicons-arrow-right-24: View user guide](tabs.md)
 
 </div>

vizro-core/docs/pages/user-guides/data.md

@@ -46,7 +46,7 @@ A static data source is the simplest way to send data to your dashboard and shou
 
 ### Supply directly
 
-You can directly supply a pandas DataFrame into components such as [graphs](graph.md) and [tables](table.md).
+You can directly supply a pandas DataFrame into components such as [graphs](graph.md), [tables](table.md) and [figures](figure.md).
 
 The below example uses the Iris data saved to a file `iris.csv` in the same directory as `app.py`. This data can be generated using `px.data.iris()` or [downloaded](../../assets/user_guides/data/iris.csv).
 

vizro-core/docs/pages/user-guides/figure.md

@@ -0,0 +1 @@
+# How to use figures

vizro-core/examples/_dev/app.py

@@ -1,65 +1,100 @@
-"""Example to show dashboard configuration."""
+"""Dev app to try things out."""
 
+import pandas as pd
 import vizro.models as vm
-import vizro.plotly.express as px
 from vizro import Vizro
-from vizro.actions import export_data
-from vizro.models.types import capture
-from vizro.tables import dash_ag_grid
+from vizro.figures import kpi_card, kpi_card_reference
 
-df = px.data.gapminder()
+df = pd.DataFrame([[67434, 65553, "A"], [6434, 6553, "B"], [34, 53, "C"]], columns=["Actual", "Reference", "Category"])
 
-# Vizro filter exporting Page --------------------------------------------
-# Solution based on https://vizro.readthedocs.io/en/stable/pages/user-guides/actions/#export-data
-
-page_one = vm.Page(
-    title="Vizro filters exporting",
-    layout=vm.Layout(grid=[[0]] * 5 + [[1]]),
+page = vm.Page(
+    title="KPI Indicators",
+    layout=vm.Layout(grid=[[0, 1, 2], [3, 4, 5], [6, 7, 8], [9, 10, -1]]),
     components=[
-        vm.AgGrid(id="ag_grid_1", title="Equal Title One", figure=dash_ag_grid(data_frame=df)),
-        vm.Button(text="Export data", actions=[vm.Action(function=export_data())]),
-    ],
-    controls=[vm.Filter(column="continent"), vm.Filter(column="year")],
-)
-
-# AgGrid filter exporting Page -------------------------------------------
-# Solution based on https://dash.plotly.com/dash-ag-grid/export-data-csv
-
-
-# More about Vizro Custom Actions -> https://vizro.readthedocs.io/en/stable/pages/user-guides/custom-actions/
-@capture("action")
-def ag_grid_data_exporting():
-    """Custom Action."""
-    return True
-
-
-page_two = vm.Page(
-    title="AgGrid filters exporting",
-    layout=vm.Layout(grid=[[0]] * 5 + [[1]]),  # grid = [[0], [0], [0], [0], [0], [1]]
-    components=[
-        vm.AgGrid(
-            id="ag_grid_2",
-            title="Equal Title One",
-            figure=dash_ag_grid(
-                # underlying_ag_grid_2 is the id of the AgGrid component on the client-side. It is used to reference
-                # it's `exportDataAsCsv` property with the custom action below
-                id="underlying_ag_grid_2",
+        # Style 1: Value Only
+        vm.Figure(figure=kpi_card(data_frame=df, value_column="Actual", title="Value I", agg_func="sum")),
+        vm.Figure(figure=kpi_card(data_frame=df, value_column="Actual", title="Value II", agg_func="mean")),
+        vm.Figure(figure=kpi_card(data_frame=df, value_column="Actual", title="Value III", agg_func="median")),
+        # Style 2: Value and reference value
+        vm.Figure(
+            figure=kpi_card_reference(
+                data_frame=df,
+                value_column="Reference",
+                reference_column="Actual",
+                title="Ref. Value II",
+                agg_func="sum",
+            )
+        ),
+        vm.Figure(
+            figure=kpi_card_reference(
                 data_frame=df,
-                csvExportParams={
-                    "fileName": "ag_grid_2.csv",
-                },
+                value_column="Actual",
+                reference_column="Reference",
+                title="Ref. Value I",
+                agg_func="sum",
+            )
+        ),
+        vm.Figure(
+            id="kpi-card-reverse-coloring",
+            figure=kpi_card_reference(
+                data_frame=df,
+                value_column="Actual",
+                reference_column="Reference",
+                title="Ref. Value III",
+                agg_func="median",
+                icon="shopping_cart",
             ),
         ),
-        vm.Button(
-            id="button_2",
-            text="Export data",
-            actions=[vm.Action(function=ag_grid_data_exporting(), outputs=["underlying_ag_grid_2.exportDataAsCsv"])],
+        # Style 3: Value and icon
+        vm.Figure(
+            figure=kpi_card(
+                data_frame=df,
+                value_column="Actual",
+                icon="shopping_cart",
+                title="Icon I",
+                agg_func="sum",
+                value_format="${value:.2f}",
+            )
+        ),
+        vm.Figure(
+            figure=kpi_card(
+                data_frame=df,
+                value_column="Actual",
+                icon="payment",
+                title="Icon II",
+                agg_func="mean",
+                value_format="{value:.0f}€",
+            )
+        ),
+        vm.Figure(
+            figure=kpi_card(
+                data_frame=df,
+                value_column="Actual",
+                icon="monitoring",
+                title="Icon III",
+                agg_func="median",
+            )
+        ),
+        # This should still work without a figure argument
+        vm.Card(
+            text="""
+                # Text Card
+                Hello, this is a text card.
+            """
+        ),
+        vm.Card(
+            text="""
+                # Nav Card
+                Hello, this is a nav card.
+            """,
+            href="https://www.google.com",
         ),
     ],
-    controls=[vm.Filter(column="continent"), vm.Filter(column="year")],
+    controls=[vm.Filter(column="Category")],
 )
 
-dashboard = vm.Dashboard(pages=[page_one, page_two])
+
+dashboard = vm.Dashboard(pages=[page])
 
 if __name__ == "__main__":
     Vizro().build(dashboard).run()

vizro-core/examples/_dev/assets/css/custom.css

@@ -1,14 +1,4 @@
-#logo {
-  height: 40px;
-  margin-left: -8px;
-}
-
-/* Apply styling to parent */
-.card:has(#my-card) {
-  background-color: white;
-}
-
-/* Apply styling to children */
-#my-card p {
-  color: black;
+/* Apply reverse color logic via CSS */
+#kpi-card-reverse-coloring .card-kpi:has(.color-neg) {
+  border-left: 4px solid #1a85ff;
 }

vizro-core/mkdocs.yml

@@ -15,6 +15,7 @@ nav:
           - Overview: pages/user-guides/components.md
           - Graphs: pages/user-guides/graph.md
           - Tables: pages/user-guides/table.md
+          - Figures: pages/user-guides/figure.md
           - Cards & buttons: pages/user-guides/card-button.md
           - Containers: pages/user-guides/container.md
           - Tabs: pages/user-guides/tabs.md

vizro-core/pyproject.toml

@@ -78,7 +78,9 @@ filterwarnings = [
   # Ignore until pandas 3 is released:
   "ignore:(?s).*Pyarrow will become a required dependency of pandas:DeprecationWarning",
   # Ignore until plotly fixes so the warning is no longer raised:
-  "ignore:When grouping with a length-1 list-like, you will need to pass a length-1 tuple to get_group:FutureWarning"
+  "ignore:When grouping with a length-1 list-like, you will need to pass a length-1 tuple to get_group:FutureWarning",
+  # Ignore warning when providing a custom format string to the KPI Cards:
+  "ignore:Custom format string detected."
 ]
 norecursedirs = ["tests/tests_utils", "tests/js"]
 pythonpath = ["tests/tests_utils", "examples/kpi"]

vizro-core/schemas/0.1.18.dev0.json

@@ -172,6 +172,26 @@
       "required": ["text"],
       "additionalProperties": false
     },
+    "Figure": {
+      "title": "Figure",
+      "description": "Creates a figure-like object that can be displayed in the dashboard and is reactive to controls.\n\nArgs:\n    type (Literal[\"figure\"]): Defaults to `\"figure\"`.\n    figure (CapturedCallable): See [`vizro.figures`][vizro.figures].",
+      "type": "object",
+      "properties": {
+        "id": {
+          "title": "Id",
+          "description": "ID to identify model. Must be unique throughout the whole dashboard.When no ID is chosen, ID will be automatically generated.",
+          "default": "",
+          "type": "string"
+        },
+        "type": {
+          "title": "Type",
+          "default": "figure",
+          "enum": ["figure"],
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
     "Graph": {
       "title": "Graph",
       "description": "Wrapper for `dcc.Graph` to visualize charts in dashboard.\n\nArgs:\n    type (Literal[\"graph\"]): Defaults to `\"graph\"`.\n    figure (CapturedCallable): See [`CapturedCallable`][vizro.models.types.CapturedCallable].\n    actions (List[Action]): See [`Action`][vizro.models.Action]. Defaults to `[]`.",
@@ -344,6 +364,7 @@
                 "button": "#/definitions/Button",
                 "card": "#/definitions/Card",
                 "container": "#/definitions/Container",
+                "figure": "#/definitions/Figure",
                 "graph": "#/definitions/Graph",
                 "table": "#/definitions/Table",
                 "tabs": "#/definitions/Tabs"
@@ -362,6 +383,9 @@
               {
                 "$ref": "#/definitions/Container"
               },
+              {
+                "$ref": "#/definitions/Figure"
+              },
               {
                 "$ref": "#/definitions/Graph"
               },
@@ -1135,6 +1159,7 @@
                 "button": "#/definitions/Button",
                 "card": "#/definitions/Card",
                 "container": "#/definitions/Container",
+                "figure": "#/definitions/Figure",
                 "graph": "#/definitions/Graph",
                 "table": "#/definitions/Table",
                 "tabs": "#/definitions/Tabs"
@@ -1153,6 +1178,9 @@
               {
                 "$ref": "#/definitions/Container"
               },
+              {
+                "$ref": "#/definitions/Figure"
+              },
               {
                 "$ref": "#/definitions/Graph"
               },

vizro-core/schemas/generate.py

@@ -12,7 +12,6 @@
 parser.add_argument("--check", help="check schema is up to date", action="store_true")
 args = parser.parse_args()
 
-# TODO: need to setup alias function to keep lowercase if wanted
 schema_json = Dashboard.schema_json(indent=4, by_alias=False)
 schema_path = Path(__file__).with_name(f"{__version__}.json")
 

vizro-core/src/vizro/figures/__init__.py

@@ -0,0 +1,4 @@
+from vizro.figures.kpi_cards import kpi_card, kpi_card_reference
+
+# Please keep alphabetically ordered
+__all__ = ["kpi_card", "kpi_card_reference"]