[POC] Add chart gallery dashboard

pyproject.toml

@@ -27,7 +27,7 @@ target-version = ["py38"]
 [tool.codespell]
 builtin = "clear,rare,en-GB_to_en-US"
 ignore-words-list = "grey,ned,sav"
-skip = "*.min.css.map,*.min.css,.vale/*"
+skip = "*.min.css.map,*.min.css,.vale/*, *assets/*"
 
 [tool.mypy]
 # strict checks : strict = true
@@ -91,3 +91,5 @@ select = [
 "**/tests/**" = ["PLR2004", "S101", "TID252", "D100", "D101", "D102", "D103", "PLC1901", "RUF012"]
 # Ignore import violations in all __init__.py files
 "__init__.py" = ["E402", "F401"]
+# Ignore missing docstrings in chart gallery examples to keep them succinct.
+"vizro-core/examples/_chart-gallery/pages/examples/**" = ["D100", "D103"]

vizro-core/changelog.d/20240712_135610_huong_li_nguyen_chart_gallery.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))
+
+-->

vizro-core/examples/_chart-gallery/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 FT Interactive News
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vizro-core/examples/_chart-gallery/README.md

@@ -0,0 +1,78 @@
+# Chart gallery dashboard
+
+This dashboard shows a gallery of charts. It includes guidance on when to use each chart type and sample Python code
+to create them using [Plotly](https://plotly.com/python/) and [Vizro](https://vizro.mckinsey.com/).
+
+Inspired by the [FT Visual Vocabulary](https://github.com/Financial-Times/chart-doctor/blob/main/visual-vocabulary/README.md):
+FT Graphics: Alan Smith, Chris Campbell, Ian Bott, Liz Faunce, Graham Parrish, Billy Ehrenberg, Paul McCallum, Martin Stabe.
+
+## Chart types
+
+The dashboard is still in development. Below is an overview of the chart types for which a completed page is available.
+
+| Chart Type           | Status | Category                 |
+| -------------------- | ------ | ------------------------ |
+| Arc                  | ❌     | Part-to-whole            |
+| Area                 | ❌     | Time                     |
+| Barcode              | ❌     | Distribution             |
+| Bar                  | ✅     | Magnitude                |
+| Boxplot              | ✅     | Distribution             |
+| Bubble               | ❌     | Correlation, Magnitude   |
+| Bubble Map           | ❌     | Spatial                  |
+| Bubble Timeline      | ❌     | Time                     |
+| Bullet               | ❌     | Magnitude                |
+| Butterfly            | ✅     | Deviation, Distribution  |
+| Chord                | ❌     | Flow                     |
+| Choropleth           | ✅     | Spatial                  |
+| Column               | ✅     | Magnitude, Time          |
+| Column-Line          | ❌     | Correlation, Time        |
+| Cumulative Curve     | ❌     | Distribution             |
+| Diverging Bar        | ❌     | Deviation                |
+| Dot Map              | ❌     | Spatial                  |
+| Dot Plot             | ❌     | Distribution             |
+| Donut                | ✅     | Part-to-whole            |
+| Fan                  | ❌     | Time                     |
+| Flow Map             | ❌     | Spatial                  |
+| Funnel               | ❌     | Part-to-whole            |
+| Gantt                | ❌     | Time                     |
+| Heatmap              | ❌     | Time                     |
+| Heatmap-Matrix       | ❌     | Correlation              |
+| Histogram            | ❌     | Distribution             |
+| Line                 | ✅     | Time                     |
+| Lollipop             | ❌     | Ranking, Magnitude       |
+| Marimekko            | ❌     | Magnitude, Part-to-whole |
+| Ordered Bar          | ✅     | Ranking                  |
+| Ordered Bubble       | ❌     | Ranking                  |
+| Ordered Column       | ✅     | Ranking                  |
+| Parallel Coordinates | ❌     | Magnitude                |
+| Pictogram            | ❌     | Magnitude                |
+| Pie                  | ✅     | Part-to-whole            |
+| Radar                | ❌     | Magnitude                |
+| Radial               | ❌     | Magnitude                |
+| Sankey               | ✅     | Flow                     |
+| Scatter              | ✅     | Correlation              |
+| Scatter Matrix       | ❌     | Correlation              |
+| Slope                | ❌     | Ranking, Time            |
+| Sparkline            | ❌     | Time                     |
+| Stacked Bar          | ❌     | Part-to-whole            |
+| Stacked Column       | ❌     | Part-to-whole            |
+| Stepped Line         | ❌     | Ranking                  |
+| Surplus-Deficit-Line | ❌     | Deviation                |
+| Treemap              | ✅     | Magnitude, Part-to-whole |
+| Venn                 | ❌     | Part-to-whole            |
+| Violin               | ✅     | Distribution             |
+| Waterfall            | ❌     | Part-to-whole, Flow      |
+
+To contribute a chart, follow the steps below:
+
+1. Place an `svg` file named after the chart type in the `assets` folder if not already available.
+2. Create a new page for the chart type in `pages.py` and a code sample in `pages/examples`. Refer to existing pages for guidance.
+3. Add any new datasets to `pages/_page_utils.py`.
+4. Remove the page from `incomplete_pages` in the relevant `ChartGroup`(s) in `chart_groups.py`.
+5. Update this `README.md` with the new chart type.
+
+## How to run the example locally
+
+1. If you have `hatch` set up, run the example with the command `hatch run example _chart-gallery`.
+   Otherwise, with a virtual Python environment activated, run `pip install -r requirements.txt` and then `python app.py`.
+2. You should now be able to access the app locally via http://127.0.0.1:8050/.

vizro-core/examples/_chart-gallery/app.py

@@ -0,0 +1,108 @@
+"""App configuration for chart gallery dashboard."""
+
+from typing import List, Union
+
+import vizro.models as vm
+from chart_groups import ALL_CHART_GROUP, CHART_GROUPS, ChartGroup, IncompletePage
+from custom_components import FlexContainer, Markdown
+from vizro import Vizro
+
+
+def make_chart_card(page: Union[vm.Page, IncompletePage]) -> vm.Card:
+    """Makes a card with svg icon, linked to the right page if page is complete.
+
+    Args:
+        page: page to make card for
+
+    Returns: card with svg icon, linked to the right page if page is complete.
+
+    """
+    # There's one SVG per chart title, so that e.g. pages distribution-butterfly and deviation-butterfly, which both
+    # have title "Butterfly", correspond to butterfly.svg.
+    # Incomplete pages have page.path = "" so won't be linked to here.
+    svg_name = page.title.lower().replace(" ", "-")
+    return vm.Card(
+        text=f"""
+           ![](assets/images/charts/{svg_name}.svg#chart-icon)
+
+           #### {page.title}
+           """,
+        href=page.path,
+    )
+
+
+def make_homepage_container(chart_group: ChartGroup) -> vm.Container:
+    """Makes a container with cards for each completed and incomplete chart in chart_group.
+
+    Args:
+        chart_group: group of charts to make container for.
+
+    Returns: container with cards for each chart in chart_group.
+
+    """
+    # Pages are sorted in title's alphabetical order and deduplicated so that e.g. pages distribution-butterfly and
+    # deviation-butterfly, which both have title "Butterfly", correspond to a single card.
+    return vm.Container(
+        title=chart_group.name,
+        layout=vm.Layout(grid=[[0, 1, 1, 1]], col_gap="40px"),
+        components=[
+            Markdown(text=chart_group.intro_text, classname="intro-text"),
+            FlexContainer(
+                components=[
+                    make_chart_card(page)
+                    for page in sorted(
+                        _remove_duplicates(chart_group.pages + chart_group.incomplete_pages),
+                        key=lambda page: page.title,
+                    )
+                ],
+            ),
+        ],
+    )
+
+
+def _remove_duplicates(pages: List[Union[vm.Page, IncompletePage]]) -> List[Union[vm.Page, IncompletePage]]:
+    # Deduplicate pages that have the same title. Using reversed means that the page that is kept is the first one
+    # in the dashboard. This will be the one that the card on the homepage links to.
+    return list({page.title: page for page in reversed(pages)}.values())
+
+
+def make_navlink(chart_group: ChartGroup) -> vm.NavLink:
+    """Makes a navlink with icon and links to every complete page within chart_group.
+
+    Args:
+        chart_group: chart_group to make a navlink for.
+
+    Returns: navlink for chart_group.
+
+    """
+    # Pages are sorted in alphabetical order within each chart group.
+    return vm.NavLink(
+        label=chart_group.name,
+        pages={chart_group.name: [page.id for page in sorted(chart_group.pages, key=lambda page: page.title)]},
+        icon=chart_group.icon,
+    )
+
+
+homepage = vm.Page(
+    title="Overview",
+    components=[
+        vm.Tabs(tabs=[make_homepage_container(chart_group) for chart_group in [ALL_CHART_GROUP, *CHART_GROUPS]]),
+    ],
+)
+
+
+dashboard = vm.Dashboard(
+    # ALL_CHART_GROUP.pages has duplicated pages, e.g. both distribution-butterfly and deviation-butterfly.
+    pages=[homepage, *ALL_CHART_GROUP.pages],
+    navigation=vm.Navigation(
+        nav_selector=vm.NavBar(
+            items=[
+                vm.NavLink(label="Overview", pages=[homepage.id], icon="Home"),
+            ]
+            + [make_navlink(chart_group) for chart_group in CHART_GROUPS]
+        )
+    ),
+)
+
+if __name__ == "__main__":
+    Vizro().build(dashboard).run()

vizro-core/examples/_chart-gallery/assets/css/custom.css

@@ -0,0 +1,63 @@
+#page-header {
+  padding-left: 8px;
+}
+
+#left-main {
+  width: 288px;
+}
+
+img[src*="#chart-icon"] {
+  width: 100%;
+}
+
+.code-clipboard {
+  font-size: 20px;
+  position: absolute;
+  right: 14px;
+  top: 12px;
+}
+
+.code-clipboard-container {
+  background: var(--surfaces-bg-card);
+  max-height: 500px;
+  overflow: auto;
+  padding: 1rem;
+  position: relative;
+}
+
+.code-clipboard-container::-webkit-scrollbar-thumb {
+  border-color: var(--surfaces-bg-card);
+}
+
+.flex-container .card {
+  height: 208px;
+  opacity: 0.3;
+  width: 176px;
+}
+
+.flex-container {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 20px;
+}
+
+.flex-container h4 {
+  color: var(--text-secondary);
+  margin: 0;
+  padding-top: 12px;
+  text-align: center;
+}
+
+.intro-text {
+  border-left: 4px solid var(--text-secondary);
+  padding: 12px;
+}
+
+.intro-text p {
+  font-size: 16px;
+  line-height: 20px;
+}
+
+.flex-container .card-nav {
+  opacity: 1;
+}