gov-uk-dashboards 21.2.2__py3-none-any.whl → 26.26.0__py3-none-any.whl

gov_uk_dashboards/components/dash/data_quality_banner.py

@@ -0,0 +1,91 @@
+"""data_quality_banner"""
+
+from enum import Enum
+from dataclasses import dataclass
+from dash import html
+from gov_uk_dashboards.components.dash.notification_banner import notification_banner
+from gov_uk_dashboards.formatting.text_functions import create_id_from_string
+from gov_uk_dashboards.constants import (
+    NOTIFICATION_STYLE_GREEN,
+    NOTIFICATION_STYLE_ORANGE,
+    NOTIFICATION_STYLE_RED,
+    NOTIFICATION_STYLE_YELLOW,
+)
+
+
+@dataclass
+class DataQualityConfig:
+    """
+    Configuration class for defining the display and linking details of a data quality metric.
+
+    Attributes:
+        title (str): The title of the data quality metric.
+        text (str): Descriptive text or explanation of the metric.
+        style (str): The visual style or format for displaying the metric.
+        title_color (str, optional): Optional color to use for the title. Defaults to None.
+        glossary_url (str, optional): Optional URL linking to a glossary entry for this metric.
+            If not provided, a URL is automatically generated based on the title.
+
+    Methods:
+        __post_init__(): Automatically generates a glossary URL if none is provided.
+    """
+
+    title: str
+    text: str
+    style: str
+    title_color: str = None
+    glossary_url: str = None
+
+    def __post_init__(self):
+        if not self.glossary_url:
+            slug = create_id_from_string(self.title)
+            self.glossary_url = f"/glossary#data-quality-{slug}"
+
+
+class DataQualityLabels(Enum):
+    """Enumeration of standard labels used to categorize or describe data quality."""
+
+    OFFICIAL = DataQualityConfig(
+        title="OFFICIAL public data",
+        text="Use with confidence.",
+        style=NOTIFICATION_STYLE_GREEN,
+    )
+    MI = DataQualityConfig(
+        title="Management information",
+        text="Use for early insights, but with caution.",
+        style=NOTIFICATION_STYLE_YELLOW,
+        title_color="black",
+    )
+    EXPERIMENTAL_MI = DataQualityConfig(
+        title="Experimental management information",
+        text="Indicative only, requires expert guidance on use.",
+        style=NOTIFICATION_STYLE_ORANGE,
+        title_color="black",
+    )
+    OPERATIONAL = DataQualityConfig(
+        title="Operational data",
+        text="Never use in isolation, always verify independently.",
+        style=NOTIFICATION_STYLE_RED,
+    )
+
+
+def data_quality_notification_banner(label: DataQualityLabels):
+    """Return data quality notification banner based on Gov UK Design component notification
+    banner component."""
+    config = label.value
+    text = [
+        f"{config.text} Read more in our ",
+        html.A(
+            "glossary",
+            href=config.glossary_url,
+            target="_blank",
+            rel="noopener noreferrer",
+        ),
+        ".",
+    ]
+    return notification_banner(
+        title=config.title,
+        text=text,
+        style=config.style,
+        title_color=config.title_color,
+    )

gov_uk_dashboards/components/dash/details.py

@@ -1,4 +1,5 @@
 """details"""
+
 from dash import html
 
 

gov_uk_dashboards/components/dash/download_button.py

@@ -1,60 +1,46 @@
 """download_button"""
-import warnings
+
+from typing import Union
 from dash import html
 
 from gov_uk_dashboards.constants import DOWNLOAD_BUTTON_CLASSES
 
 
-def download_button(button_text: str, button_id: str = "download-button"):
-    """
-    Return a download button which is aligned to the right
-
-    Args:
-    button_text (str): The text to display on the button.
-    button_id: (str, Optional) = id for dropdown, default to "download-button"
-    """
-    warnings.warn(
-        "Note there is an alternative function to download_button() called "
-        "create_download_button_with_icon() which includes a download icon and improved styling.",
-        Warning,
-        stacklevel=2,
-    )
-
-    return html.Div(
-        [
-            html.Button(
-                button_text,
-                id=button_id,
-                n_clicks=0,
-                className="govuk-button govuk-button--secondary",
-            ),
-        ],
-        className="govuk-button-group",
-        style={"float": "right"},
-    )
-
-
 def create_download_button_with_icon(
-    button_text: str, button_id_name: str
+    button_text: str,
+    button_id_name: str,
+    instance: Union[str, int] = None,
+    download_type: str = None,
 ) -> html.Button:
     """Create a download button with icon, aligned to the left.
 
     Parameters:
+    - button_text (str): Text to display on button.
     - button_id_name (str): A unique identifier for the button.
+    - instance (Union[int,str]): Optional additional id parameter for when button_text is
+        "Download map".
 
     Returns:
     - html.Button: Download button.
     """
-    download_type = button_text.lower().replace(" ", "-")
+    if download_type:
+        download_type = f"download-{download_type}"
+    else:
+        download_type = button_text.lower().replace(" ", "-")
+    if button_text == "Download map":
+        id_dict = {
+            "download-type": download_type,
+            "name": button_id_name,
+            "instance": instance,
+        }
+    else:
+        id_dict = {"download-type": download_type, "name": button_id_name}
     return html.Button(
         [
             html.Div("", className="download-icon"),
             button_text,
         ],
-        id={
-            "download-type": download_type,
-            "name": button_id_name,
-        },
+        id=id_dict,
         n_clicks=0,
         className=DOWNLOAD_BUTTON_CLASSES,
         type="submit",

gov_uk_dashboards/components/dash/filter_panel.py

@@ -1,4 +1,5 @@
 """filter_panel"""
+
 from typing import Optional
 from dash import html
 

gov_uk_dashboards/components/dash/footer.py

@@ -1,9 +1,10 @@
 """footer"""
+
 from typing import Optional
 from dash import html
 
 
-def footer(footer_links: Optional[list[any]]):
+def footer(footer_links: Optional[list[any]], include_logos: bool = False):
     """
     HTML component for a Gov.UK standard footer.
 
@@ -22,34 +23,87 @@ def footer(footer_links: Optional[list[any]]):
                 [
                     html.Div(
                         [
-                            html.H2("Support Links", className="govuk-visually-hidden")
-                            if footer_links
-                            else None,
-                            html.Ul(
-                                children=[
-                                    html.Li(
-                                        item, className="govuk-footer__inline-list-item"
-                                    )
-                                    for item in footer_links
-                                ],
-                                className="govuk-footer__inline-list govuk-!-display-none-print",
-                            )
-                            if footer_links
-                            else None,
-                            html.Span(
+                            (
+                                html.H2(
+                                    "Support Links", className="govuk-visually-hidden"
+                                )
+                                if footer_links
+                                else None
+                            ),
+                            html.Div(
                                 [
-                                    "All content is available under the ",
-                                    html.A(
-                                        "Open Government Licence v3.0",
-                                        rel="license",
-                                        href="https://www.nationalarchives.gov.uk/doc/"
-                                        "open-government-licence/version/3/",
-                                        className="govuk-footer__link",
-                                        target="_blank",
+                                    (
+                                        html.Ul(
+                                            children=[
+                                                html.Li(
+                                                    item,
+                                                    className="govuk-footer__inline-list-item",
+                                                )
+                                                for item in footer_links
+                                            ],
+                                            className=(
+                                                "govuk-footer__inline-list "
+                                                "govuk-!-display-none-print"
+                                            ),
+                                        )
+                                        if footer_links
+                                        else None
+                                    ),
+                                    html.Span(
+                                        [
+                                            "All content is available under the ",
+                                            html.A(
+                                                "Open Government Licence v3.0",
+                                                rel="license",
+                                                href="https://www.nationalarchives.gov.uk/doc/"
+                                                "open-government-licence/version/3/",
+                                                className="govuk-footer__link",
+                                                target="_blank",
+                                            ),
+                                            ", except where otherwise stated",
+                                        ],
+                                        className="govuk-footer__licence-description",
+                                    ),
+                                    (
+                                        (
+                                            html.Div(
+                                                [
+                                                    html.Img(
+                                                        src="assets\\images\\CHASE_icon.svg",
+                                                        className="header-image",
+                                                        style={"maxWidth": "100px"},
+                                                    ),
+                                                    html.Div(
+                                                        [
+                                                            html.B(
+                                                                "CHASE",
+                                                                style={
+                                                                    "font-size": "36px"
+                                                                },
+                                                            ),
+                                                        ],
+                                                        style={
+                                                            "display": "flex",
+                                                            "flex-direction": "column",
+                                                            "align-items": "left",
+                                                            "color": "#707070",
+                                                            "maxWidth": "200px",
+                                                            "padding-bottom": "10px",
+                                                        },
+                                                    ),
+                                                ],
+                                                style={
+                                                    "display": "flex",
+                                                    "flex-direction": "row",
+                                                    "align-items": "center",
+                                                    "padding-top": "30px",
+                                                },
+                                            )
+                                        )
+                                        if include_logos
+                                        else None
                                     ),
-                                    ", except where otherwise stated",
-                                ],
-                                className="govuk-footer__licence-description",
+                                ]
                             ),
                         ],
                         className="govuk-footer__meta-item govuk-footer__meta-item--grow",

gov_uk_dashboards/components/dash/graph.py

@@ -1,4 +1,5 @@
 """Create a graph"""
+
 import warnings
 from dash import dcc
 

gov_uk_dashboards/components/dash/green_button.py

@@ -0,0 +1,25 @@
+"""green_button"""
+
+from dash import html
+
+
+def green_button(button_text: str, button_id: str):
+    """
+    Return a green button which is aligned to the right
+
+    Args:
+    button_text (str): The text to display on the button.
+    button_id: (str) = id for button
+    """
+
+    return html.Div(
+        [
+            html.Button(
+                button_text,
+                id=button_id,
+                n_clicks=0,
+                className="govuk-button",
+            ),
+        ],
+        className="govuk-button-group",
+    )

gov_uk_dashboards/components/dash/header.py

@@ -3,7 +3,12 @@
 from dash import html
 
 
-def header(title: str, strong_class: str = "", background_colour: str = None):
+def header(
+    title: str,
+    strong_class: str = "",
+    background_colour: str = None,
+    show_mobile_menu_button: bool = True,
+):
     """
     The header component, shared across all dashboard views. Includes optional strong_class
     parameter to provide extra styling in the form of a class.
@@ -28,7 +33,7 @@ def header(title: str, strong_class: str = "", background_colour: str = None):
                     ),
                     html.Div(
                         ["Ministry of Housing, Communities & Local Government"],
-                        style={"font-size": "20px", "font-weight": "200px"},
+                        style={"fontSize": "20px", "fontWeight": "200px"},
                     ),
                     html.A(
                         title,
@@ -47,25 +52,73 @@ def header(title: str, strong_class: str = "", background_colour: str = None):
                                 "OFFICIAL",
                                 className="govuk-tag protective-marking",
                                 id="protective-marking",
-                                style={"background-color": "#000000"},
+                                style={"backgroundColor": "#000000"},
                             )
                         ],
                         className=f"{strong_class}",
                     ),
-                    html.Button(
-                        "Menu ▼",
-                        id="mobile-menu-btn",
-                        className="mobile-menu-button govuk-button",
+                    (
+                        html.Button(
+                            "Menu ▼",
+                            id="mobile-menu-btn",
+                            className="mobile-menu-button govuk-button",
+                        )
+                        if show_mobile_menu_button
+                        else None
                     ),
                 ],
                 className="govuk-header__content",
             ),
             className="govuk-header__container govuk-width-container",
-            style={"border-bottom": "10px solid #000000"},
+            style={"borderBottom": "10px solid #000000"},
         ),
         className="govuk-header",
         role="banner",
         style=header_style
-        | {"border-color": "#000000", "background-color": "rgb(0,98,94)"},
+        | {"borderColor": "#000000", "backgroundColor": "rgb(0,98,94)"},
         **{"data-module": "govuk-header"},
     )
+
+
+def logo_header():
+    """
+    Create and return the application header containing the Explore Data logo.
+
+    This component renders a GOV.UK–styled header with an SVG logo.
+    The logo is loaded from the Dash assets directory and constrained
+    to a maximum height for consistent layout.
+
+    Returns
+    -------
+    dash.html.Header
+        A Dash Header component containing the styled logo container.
+    """
+    return html.Header(
+        html.Div(
+            html.Div(
+                [
+                    html.Div(
+                        [
+                            html.Img(
+                                src="/assets/images/explore_data_logo.svg",
+                                className="header-image",
+                                style={"maxHeight": "100px"},
+                            ),
+                        ],
+                        style={
+                            "display": "flex",
+                            "flexDirection": "column",
+                            "color": "#00625e",
+                            "alignItems": "center",
+                            "paddingBottom": "2px",
+                        },
+                    ),
+                ],
+                className="govuk-header__content",
+            ),
+            style={"borderBottom": "0px solid #000000", "borderColor": "#f3f2f1"},
+            className="govuk-header__container govuk-width-container",
+        ),
+        className="govuk-header",
+        style={"backgroundColor": "#f3f2f1", "borderColor": "#f3f2f1"},
+    )

gov_uk_dashboards/components/dash/heading.py

@@ -1,7 +1,9 @@
 """heading components"""
+
 from enum import Enum
 
 from dash import html
+from gov_uk_dashboards.formatting.text_functions import create_id_from_string
 
 
 class HeadingSizes(str, Enum):
@@ -15,16 +17,17 @@ class HeadingSizes(str, Enum):
 
 def heading1(text: str, size: HeadingSizes = HeadingSizes.LARGE) -> html.H1:
     """Return a H1 dash component"""
-    return html.H1(text, className=size)
+    heading_id = f"heading1-{create_id_from_string(text)}"
+    return html.H1(text, className=size, id=heading_id)
 
 
 def heading2(text: str, size: HeadingSizes = HeadingSizes.MEDIUM) -> html.H2:
     """Return a H2 dash component"""
-
-    return html.H2(text, className=size)
+    heading_id = f"heading2-{create_id_from_string(text)}"
+    return html.H2(text, className=size, id=heading_id)
 
 
 def heading3(text: str, size: HeadingSizes = HeadingSizes.SMALL) -> html.H3:
     """Return a H3 dash component"""
-
-    return html.H3(text, className=size)
+    heading_id = f"heading3-{create_id_from_string(text)}"
+    return html.H3(text, className=size, id=heading_id)

gov_uk_dashboards/components/dash/home_page_link_button.py

@@ -1,4 +1,5 @@
 """home_page_link_button"""
+
 from typing import Optional
 from dash import html
 
@@ -43,9 +44,9 @@ def home_page_link_button(
                         [
                             html.Div(
                                 [title],
-                                className="govuk-heading-l"
-                                if info is not None
-                                else None,
+                                className=(
+                                    "govuk-heading-l" if info is not None else None
+                                ),
                             ),
                             (
                                 html.Div(
@@ -56,17 +57,17 @@ def home_page_link_button(
                             ),
                         ],
                         style={
-                            "text-align": "left",
-                            "text-decoration": "none",
-                            "padding-left": "5%",
+                            "textAlign": "left",
+                            "textDecoration": "none",
+                            "paddingLeft": "5%",
                         },
                     ),
                     html.Img(src=image_path, style={"width": "100%"}),
                 ],
                 style={
                     "display": "grid",
-                    "grid-template-columns": "5fr 1fr",
-                    "align-items": "center",
+                    "gridTemplateColumns": "5fr 1fr",
+                    "alignItems": "center",
                 },
             )
         ],

gov_uk_dashboards/components/dash/html_list.py

@@ -1,4 +1,5 @@
 """html list component"""
+
 from dash import html
 
 

gov_uk_dashboards/components/dash/key_value_pair.py

@@ -1,4 +1,5 @@
 """key_value_pair"""
+
 import numpy as np
 from dash import html
 

gov_uk_dashboards/components/dash/main_content.py

@@ -1,8 +1,11 @@
 """main_content"""
+
+import warnings
+import re
 from dash import html
 
 
-def main_content(children):
+def main_content(children, id_fragment=None, include_feedback_banner_div: bool = False):
     """
     Wrapper for the main content of the dashboard, containing visualisations.
 
@@ -13,4 +16,24 @@ def main_content(children):
 
     See https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML for more guidance.
     """
-    return html.Main(children, className="main", id="main-content", role="main")
+    if id_fragment:
+        parts = re.split(r"\W+", id_fragment.lower())
+        slug = "main-content-" + "-".join(filter(None, parts))
+    else:
+        slug = ""
+        warnings.warn(
+            "WARNING: No id_fragment provided to main_content(). This is usually the page heading "
+            "and helps create a unique and consistent id attribute. Providing an id_fragment "
+            "improves accessibility, aids automated testing, and prevents issues with duplicate or "
+            "missing page headings.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    if not isinstance(children, list):
+        children = [children]
+
+    if include_feedback_banner_div:
+        children.append(html.Div(id="feedback-banner"))
+
+    return html.Main(children, className="main", id=slug, role="main")

gov_uk_dashboards/components/dash/notification_banner.py

@@ -1,9 +1,14 @@
 """notification_banner"""
+
 from dash import html
 
 
 def notification_banner(
-    text: str, text_class_name: str = "govuk-warning-text__text", style: dict = None
+    text: list,
+    title: str = "Important",
+    text_class_name: str = "govuk-notification-banner__heading",
+    style: dict = None,
+    title_color: str = None,
 ):
     """
     Return Gov UK Design component notification banner component.
@@ -13,9 +18,10 @@ def notification_banner(
             html.Div(
                 [
                     html.H2(
-                        ["Important"],
+                        [title],
                         className="govuk-notification-banner__title",
                         id="govuk-notification-banner-title",
+                        style={"color": title_color} if title_color else None,
                     )
                 ],
                 className="govuk-notification-banner__header",
@@ -23,9 +29,7 @@ def notification_banner(
             html.Div(
                 [
                     html.P(
-                        [
-                            text,
-                        ],
+                        text,
                         className=text_class_name,
                     )
                 ],

gov_uk_dashboards/components/dash/paragraph.py

@@ -1,4 +1,5 @@
 """paragraph component"""
+
 from enum import Enum
 from typing import Union
 

gov_uk_dashboards/components/dash/phase_banner.py

@@ -1,10 +1,11 @@
 """phase_banner"""
+
 from dash import html
 
 
 def phase_banner_with_feedback(
     phase: str,
-    feedback_link: str,
+    feedback_link: str = None,
     link_id: str = "feedback-link",
     link_target: str = "_self",
 ):
@@ -31,9 +32,11 @@ def phase_banner_with_feedback(
                                 className="govuk-link",
                                 id=link_id,
                                 target=link_target,
-                                rel="noopener noreferrer"
-                                if link_target == "_blank"
-                                else "",  # conditional attribute for security
+                                rel=(
+                                    "noopener noreferrer"
+                                    if link_target == "_blank"
+                                    else ""
+                                ),  # conditional attribute for security
                             ),
                             " will help us to improve it.",
                         ],

gov_uk_dashboards/components/dash/row_component.py

@@ -1,4 +1,5 @@
 """row_component"""
+
 from dash import html