Minor update to Navigation docs (mckinsey#190)

vizro-core/changelog.d/20231204_201354_huong_li_nguyen_update_nav_docs.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/docs/pages/user_guides/navigation.md

@@ -174,11 +174,12 @@ Another way to group together pages in the navigation is to use a [`NavBar`][viz
     [NavBar]: ../../assets/user_guides/navigation/nav_bar.png
 
 
-Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion. By default, the icons are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
+Here, the first level of the navigation hierarchy ("Group A" and "Group B") is represented by an icon in a navigation bar, and the second level of the navigation (the pages) is represented by an accordion.
+By default, the set of icons used are the [`filter` icons from the Google Material icons library](https://fonts.google.com/icons?icon.query=filter). The icon label ("Group A" and "Group B") appears as a tooltip on hovering over the icon.
 
 ## Customizing the navigation bar
 
-Under the hood, [`NavBar`][vizro.models.NavBar] uses [`NavLink`][vizro.models.NavLink] to build the icons in the navigation bar. It is possible to customize the navigation further by providing the `NavLink`s yourself.
+Under the hood, [`NavBar`][vizro.models.NavBar] uses [`NavLink`][vizro.models.NavLink] to build the icons in the navigation bar. It is possible to customize the navigation further by providing the `NavLink` models yourself.
 
 ### `NavLink` examples
 
@@ -239,7 +240,7 @@ You can alter the icons used by specifying the name of the icon in the [Google M
                     items=[
                         vm.NavLink(
                             label="Section 1",
-                            icon="bar_chart",
+                            icon="Bar Chart",
                             pages=["My first page", "My second page"],
                         ),
                         vm.NavLink(label="Section 2", icon="pie_chart", pages=["My third page"]),
@@ -259,7 +260,7 @@ You can alter the icons used by specifying the name of the icon in the [Google M
             type: nav_bar
             items:
               - label: Section 1
-                icon: bar_chart
+                icon: Bar Chart
                 pages:
                   - My first page
                   - My second page

vizro-core/schemas/0.1.7.dev0.json

@@ -954,7 +954,7 @@
     },
     "NavLink": {
       "title": "NavLink",
-      "description": "Icon to be used in Navigation Panel of Dashboard.\n\nArgs:\n    ages (Optional[NavPagesType]): See [`NavPagesType`][vizro.models.types.NavPagesType].\n        Defaults to `[]`.\n    label (str): Text description of the icon for use in tooltip.\n    icon (str): Icon name from [Google Material icons library](https://fonts.google.com/icons).\n        Defaults to `\"\"`.",
+      "description": "Icon to be used in Navigation Bar of Dashboard.\n\nArgs:\n    pages (NavPagesType): See [`NavPagesType`][vizro.models.types.NavPagesType]. Defaults to `[]`.\n    label (str): Text description of the icon for use in tooltip.\n    icon (str): Icon name from [Google Material icons library](https://fonts.google.com/icons). Defaults to `\"\"`.",
       "type": "object",
       "properties": {
         "id": {
@@ -1041,7 +1041,7 @@
     },
     "Navigation": {
       "title": "Navigation",
-      "description": "Navigation in [`Dashboard`][vizro.models.Dashboard] to structure [`Pages`][vizro.models.Page].\n\nArgs:\n    pages (Optional[NavPagesType]): See [`NavPagesType`][vizro.models.types.NavPagesType].\n        Defaults to [].\n    nav_selector (Optional[NavSelectorType]): See [`NavSelectorType`][vizro.models.types.NavSelectorType].\n        Defaults to `None`.",
+      "description": "Navigation in [`Dashboard`][vizro.models.Dashboard] to structure [`Pages`][vizro.models.Page].\n\nArgs:\n    pages (NavPagesType): See [`NavPagesType`][vizro.models.types.NavPagesType]. Defaults to `[]`.\n    nav_selector (Optional[NavSelectorType]): See [`NavSelectorType`][vizro.models.types.NavSelectorType].\n        Defaults to `None`.",
       "type": "object",
       "properties": {
         "id": {

vizro-core/schemas/0.1.7.dev1.json

@@ -954,7 +954,7 @@
     },
     "NavLink": {
       "title": "NavLink",
-      "description": "Icon to be used in Navigation Panel of Dashboard.\n\nArgs:\n    ages (Optional[NavPagesType]): See [`NavPagesType`][vizro.models.types.NavPagesType].\n        Defaults to `[]`.\n    label (str): Text description of the icon for use in tooltip.\n    icon (str): Icon name from [Google Material icons library](https://fonts.google.com/icons).\n        Defaults to `\"\"`.",
+      "description": "Icon to be used in Navigation Bar of Dashboard.\n\nArgs:\n    pages (NavPagesType): See [`NavPagesType`][vizro.models.types.NavPagesType]. Defaults to `[]`.\n    label (str): Text description of the icon for use in tooltip.\n    icon (str): Icon name from [Google Material icons library](https://fonts.google.com/icons). Defaults to `\"\"`.",
       "type": "object",
       "properties": {
         "id": {
@@ -1041,7 +1041,7 @@
     },
     "Navigation": {
       "title": "Navigation",
-      "description": "Navigation in [`Dashboard`][vizro.models.Dashboard] to structure [`Pages`][vizro.models.Page].\n\nArgs:\n    pages (Optional[NavPagesType]): See [`NavPagesType`][vizro.models.types.NavPagesType].\n        Defaults to [].\n    nav_selector (Optional[NavSelectorType]): See [`NavSelectorType`][vizro.models.types.NavSelectorType].\n        Defaults to `None`.",
+      "description": "Navigation in [`Dashboard`][vizro.models.Dashboard] to structure [`Pages`][vizro.models.Page].\n\nArgs:\n    pages (NavPagesType): See [`NavPagesType`][vizro.models.types.NavPagesType]. Defaults to `[]`.\n    nav_selector (NavSelectorType): See [`NavSelectorType`][vizro.models.types.NavSelectorType].\n        Defaults to `None`.",
       "type": "object",
       "properties": {
         "id": {

vizro-core/src/vizro/actions/export_data_action.py

@@ -23,7 +23,7 @@ def export_data(
     """Exports visible data of target charts/components on page after being triggered.
 
     Args:
-        targets: List of target component ids to download data from. Defaults to None.
+        targets: List of target component ids to download data from. Defaults to `None`.
         file_format: Format of downloaded files. Defaults to `csv`.
         inputs: Dict mapping action function names with their inputs e.g.
             inputs = {'filters': [], 'parameters': ['gdpPercap'], 'filter_interaction': [], 'theme_selector': True}

vizro-core/src/vizro/actions/filter_interaction_action.py

@@ -25,7 +25,7 @@ def filter_interaction(
 
     Args:
         targets: List of target component ids to filter by chart interaction. If missing, will target all valid
-            components on page. Defaults to None.
+            components on page. Defaults to `None`.
         inputs: Dict mapping action function names with their inputs e.g.
             inputs = {'filters': [], 'parameters': ['gdpPercap'], 'filter_interaction': [], 'theme_selector': True}
 

vizro-core/src/vizro/models/_components/form/_user_input.py

@@ -22,14 +22,14 @@ class UserInput(VizroBaseModel):
         actions (Optional[List[Action]]): Defaults to `[]`.
         title (str): Title to be displayed. Defaults to `""`.
         input_type (Literal["text", "number", "password", "email", "search", "tel", "url", "range", "hidden"]):
-            Type of value to validate user input against. Defaults to 'text'.
+            Type of value to validate user input against. Defaults to `"text"`.
     """
 
     type: Literal["user_input"] = "user_input"
     title: str = Field("", description="Title to be displayed")
     placeholder: str = Field("", description="Default text to display in input field")
     input_type: Literal["text", "number", "password", "email", "search", "tel", "url", "range", "hidden"] = Field(
-        "text", description="Type of value to validate user input against. Defaults to 'text'."
+        "text", description="Type of value to validate user input against."
     )
     actions: List[Action] = []
 

vizro-core/src/vizro/models/_navigation/nav_link.py

@@ -20,14 +20,12 @@
 
 
 class NavLink(VizroBaseModel):
-    """Icon to be used in Navigation Panel of Dashboard.
+    """Icon to be used in Navigation Bar of Dashboard.
 
     Args:
-        ages (Optional[NavPagesType]): See [`NavPagesType`][vizro.models.types.NavPagesType].
-            Defaults to `[]`.
+        pages (NavPagesType): See [`NavPagesType`][vizro.models.types.NavPagesType]. Defaults to `[]`.
         label (str): Text description of the icon for use in tooltip.
-        icon (str): Icon name from [Google Material icons library](https://fonts.google.com/icons).
-            Defaults to `""`.
+        icon (str): Icon name from [Google Material icons library](https://fonts.google.com/icons). Defaults to `""`.
 
     """
 
@@ -40,6 +38,10 @@ class NavLink(VizroBaseModel):
     # Re-used validators
     _validate_pages = validator("pages", allow_reuse=True)(_validate_pages)
 
+    @validator("icon")
+    def validate_icon(cls, icon) -> str:
+        return icon.strip().lower().replace(" ", "_")
+
     @_log_call
     def pre_build(self):
         from vizro.models._navigation.accordion import Accordion

vizro-core/src/vizro/models/_navigation/navigation.py

@@ -18,9 +18,8 @@ class Navigation(VizroBaseModel):
     """Navigation in [`Dashboard`][vizro.models.Dashboard] to structure [`Pages`][vizro.models.Page].
 
     Args:
-        pages (Optional[NavPagesType]): See [`NavPagesType`][vizro.models.types.NavPagesType].
-            Defaults to [].
-        nav_selector (Optional[NavSelectorType]): See [`NavSelectorType`][vizro.models.types.NavSelectorType].
+        pages (NavPagesType): See [`NavPagesType`][vizro.models.types.NavPagesType]. Defaults to `[]`.
+        nav_selector (NavSelectorType): See [`NavSelectorType`][vizro.models.types.NavSelectorType].
             Defaults to `None`.
     """
 
@@ -42,10 +41,11 @@ def pre_build(self):
     @_log_call
     def build(self, *, active_page_id=None) -> _NavBuildType:
         nav_selector = self.nav_selector.build(active_page_id=active_page_id)
+
         if "nav_bar_outer" not in nav_selector:
             # e.g. nav_selector is Accordion and nav_selector.build returns single html.Div with id="nav_panel_outer".
             # This will make it match the case e.g. nav_selector is NavBar and nav_selector.build returns html.Div
             # containing children with id="nav_bar_outer" and id="nav_panel_outer"
-            nav_selector = html.Div([html.Div(className="hidden", id="nav_bar_outer"), nav_selector])
+            nav_selector = html.Div([html.Div(hidden=True, id="nav_bar_outer"), nav_selector])
 
         return nav_selector

vizro-core/tests/unit/vizro/models/_navigation/test_nav_bar.py

@@ -71,7 +71,7 @@ def test_items_with_with_pages_icons(self, pages_as_dict):
         nav_bar = vm.NavBar(pages=pages_as_dict, items=nav_links)
         nav_bar.pre_build()
         assert nav_bar.items == nav_links
-        assert nav_bar.items[0].icon == "Home"
+        assert nav_bar.items[0].icon == "home"
         assert nav_bar.items[1].icon == "filter_2"
 
 

vizro-core/tests/unit/vizro/models/_navigation/test_nav_link.py

@@ -36,6 +36,11 @@ def test_nav_link_mandatory_and_optional(self, pages_as_list):
         assert nav_link.icon == "home"
         assert nav_link.pages == pages_as_list
 
+    @pytest.mark.parametrize("icon", ["Bar Chart", "bar chart", "bar_chart", "Bar_Chart", " bar_chart "])
+    def test_validate_icon(self, icon):
+        nav_link = vm.NavLink(icon=icon, label="Label")
+        assert nav_link.icon == "bar_chart"
+
     def test_nav_link_valid_pages_as_dict(self, pages_as_dict):
         nav_link = vm.NavLink(pages=pages_as_dict, label="Label")
         assert nav_link.pages == pages_as_dict

vizro-core/tests/unit/vizro/models/_navigation/test_navigation.py

@@ -85,9 +85,7 @@ def test_default_nav_selector(self, pages, request):
         navigation.pre_build()
         built_navigation = navigation.build(active_page_id="Page 1")
         assert_component_equal(
-            built_navigation["nav_bar_outer"],
-            html.Div(className="hidden", id="nav_bar_outer"),
-            keys_to_strip={"children"},
+            built_navigation["nav_bar_outer"], html.Div(hidden=True, id="nav_bar_outer"), keys_to_strip={}
         )
         assert_component_equal(
             built_navigation["nav_panel_outer"], html.Div(id="nav_panel_outer"), keys_to_strip={"children", "className"}