SaaS-FrameWork 0.1.1__py3-none-any.whl

components/data/DEx_TreeView.py

@@ -0,0 +1,536 @@
+"""Hierarchical tree view with search, selection, and expand/collapse controls."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Callable
+
+import flet as ft
+
+from components.theme.DEx_Theme import Colors, Spacing
+
+
+COMPONENT_VERSION = "0.0.1"
+
+
+class DEx_TreeView(ft.Column):
+    """Versioned hierarchical tree with recursive search and single-node selection.
+
+    `DEx_TreeView` accepts data as a Python list, a dict with a `menu` key, a JSON
+    string, or a JSON file path. Each node supports `label`, `type`, `icon`, and
+    `children`. Labels using the format `(ID) - Text` render the ID separately so
+    menus and module trees stay scannable.
+    """
+
+    def __init__(
+        self,
+        menu_path: str | Path | None = None,
+        menu_data: dict | list | str | None = None,
+        *,
+        on_select: Callable[["_DEx_TreeNode"], None] | None = None,
+        on_insert: Callable[["DEx_TreeView"], None] | None = None,
+        show_icon: bool = True,
+        indent_step: int = 15,
+        toggle_size: int = 18,
+        dex_id: str = "",
+        on_dex_ready: Callable[["DEx_TreeView"], None] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.menu_path = Path(menu_path) if menu_path else None
+        self._menu_data_provided = menu_data is not None
+        self.menu_data = [] if menu_data is None else menu_data
+        self.external_on_select = on_select
+        self.external_on_insert = on_insert
+        self.show_icon = show_icon
+        self.indent_step = indent_step
+        self.toggle_size = toggle_size
+        self.dex_id = dex_id
+        self._on_dex_ready = on_dex_ready
+
+        self.selected_node: dict[str, _DEx_TreeNode | None] = {"node": None}
+        self.root_nodes: list[_DEx_TreeNode] = []
+        self.tree_col = ft.Column(spacing=0, scroll=ft.ScrollMode.AUTO, expand=True)
+        self.tree_view = ft.Row([self.tree_col], scroll=ft.ScrollMode.AUTO, expand=True)
+
+        self.search_field = self._build_search_field()
+        self._build_ui()
+        self.reload()
+
+    def reload(self) -> None:
+        """Reload tree data from `menu_data` or `menu_path` and rebuild root nodes."""
+        data = self._load_data()
+        menu_items = self._extract_menu_list(data)
+        self.root_nodes = self._build_tree(menu_items, level=0)
+        self.tree_col.controls = [node.control for node in self.root_nodes]
+        self.selected_node["node"] = None
+        self._update_tree()
+
+    def collapse_all(self, e: ft.ControlEvent | None = None) -> None:
+        """Collapse every tree node."""
+        for node in self.root_nodes:
+            _set_expanded_node(node, False)
+        self._update_tree()
+
+    def expand_all(self, e: ft.ControlEvent | None = None) -> None:
+        """Expand every tree node."""
+        for node in self.root_nodes:
+            _set_expanded_node(node, True)
+        self._update_tree()
+
+    def collapse_selected(self, e: ft.ControlEvent | None = None) -> None:
+        """Collapse the currently selected node."""
+        node = self.selected_node["node"]
+        if node is None:
+            return
+        node.expanded = False
+        node.refresh()
+        self._update_tree()
+
+    def expand_selected(self, e: ft.ControlEvent | None = None) -> None:
+        """Expand the currently selected node."""
+        node = self.selected_node["node"]
+        if node is None:
+            return
+        node.expanded = True
+        node.refresh()
+        self._update_tree()
+
+    def refresh_selected(self, e: ft.ControlEvent | None = None) -> None:
+        """Refresh visual state for the currently selected node."""
+        node = self.selected_node["node"]
+        if node is None:
+            return
+        node.refresh()
+        self._update_tree()
+
+    def insert(self, e: ft.ControlEvent | None = None) -> None:
+        """Run the optional insert callback for the host application."""
+        if self.external_on_insert:
+            self.external_on_insert(self)
+
+    def on_keyboard_event(self, e: ft.KeyboardEvent) -> None:
+        """Move selection with arrow up/down and page up/down keys."""
+        key = (e.key or "").lower()
+        if key in ("arrow up", "up"):
+            self._move_selection(-1)
+        elif key in ("arrow down", "down"):
+            self._move_selection(1)
+        elif key in ("page up", "pageup"):
+            self._move_selection(-10)
+        elif key in ("page down", "pagedown"):
+            self._move_selection(10)
+
+    def did_mount(self) -> None:
+        """Notify the host when Flet mounts the component."""
+        super().did_mount()
+        if self._on_dex_ready:
+            self._on_dex_ready(self)
+
+    def _build_ui(self) -> None:
+        self.controls = [
+            ft.Container(
+                content=ft.Row(
+                    [
+                        self.search_field,
+                        self._icon_button(ft.Icons.CLEAR_ROUNDED, "Limpar busca", self._clear_search),
+                    ],
+                    spacing=Spacing.SM,
+                    vertical_alignment=ft.CrossAxisAlignment.CENTER,
+                ),
+                padding=ft.Padding(Spacing.SM, Spacing.SM, Spacing.SM, Spacing.XS),
+            ),
+            ft.Container(height=1, bgcolor=Colors.BORDER),
+            ft.Container(
+                content=self.tree_view,
+                alignment=ft.Alignment(-1, -1),
+                bgcolor=Colors.BG_DEEP,
+                expand=True,
+            ),
+            ft.Container(height=1, bgcolor=Colors.BORDER),
+            ft.Container(
+                content=ft.Row(
+                    [
+                        self._icon_button(ft.Icons.UNFOLD_LESS_ROUNDED, "Contrair tudo", self.collapse_all),
+                        self._icon_button(ft.Icons.KEYBOARD_ARROW_UP_ROUNDED, "Contrair selecionado", self.collapse_selected),
+                        self._icon_button(ft.Icons.REFRESH_ROUNDED, "Atualizar selecionado", self.refresh_selected),
+                        self._icon_button(ft.Icons.KEYBOARD_ARROW_DOWN_ROUNDED, "Expandir selecionado", self.expand_selected),
+                        self._icon_button(ft.Icons.UNFOLD_MORE_ROUNDED, "Expandir tudo", self.expand_all),
+                        ft.Container(expand=True),
+                        self._icon_button(ft.Icons.ADD_ROUNDED, "Novo registro", self.insert, size=24, box_size=40),
+                    ],
+                    spacing=Spacing.SM,
+                    vertical_alignment=ft.CrossAxisAlignment.CENTER,
+                ),
+                padding=ft.Padding(Spacing.SM, Spacing.XS, Spacing.SM, Spacing.SM),
+            ),
+        ]
+        self.spacing = 0
+        self.expand = True
+
+    def _build_search_field(self) -> ft.TextField:
+        return ft.TextField(
+            hint_text="Faca uma pesquisa...",
+            height=34,
+            text_size=12,
+            text_style=ft.TextStyle(color=Colors.TEXT_PRIMARY, size=12),
+            hint_style=ft.TextStyle(color=Colors.TEXT_MUTED, size=12),
+            content_padding=ft.Padding(8, 0, 8, 0),
+            prefix_icon=ft.Icons.SEARCH_ROUNDED,
+            border_color=Colors.BORDER,
+            focused_border_color=Colors.ACCENT,
+            bgcolor=Colors.BG_ELEVATED,
+            border_radius=8,
+            on_change=lambda e: self._apply_search(),
+            expand=True,
+        )
+
+    def _icon_button(
+        self,
+        icon: ft.IconData,
+        tooltip: str,
+        on_click: Callable | None,
+        *,
+        size: int = 16,
+        box_size: int = 28,
+    ) -> ft.Container:
+        return ft.Container(
+            width=box_size,
+            height=box_size,
+            content=ft.IconButton(
+                icon=icon,
+                icon_size=size,
+                icon_color=Colors.TEXT_SECONDARY,
+                tooltip=tooltip,
+                on_click=on_click,
+                style=ft.ButtonStyle(padding=0),
+            ),
+        )
+
+    def _load_data(self) -> dict | list:
+        if self._menu_data_provided:
+            return self._normalize_menu_data(self.menu_data)
+        if self.menu_path:
+            return json.loads(self.menu_path.read_text(encoding="utf-8-sig"))
+        return []
+
+    def _normalize_menu_data(self, menu_data: dict | list | str) -> dict | list:
+        if isinstance(menu_data, str):
+            try:
+                return json.loads(menu_data)
+            except json.JSONDecodeError as exc:
+                raise ValueError("menu_data must be valid JSON.") from exc
+        if isinstance(menu_data, (dict, list)):
+            return menu_data
+        raise TypeError("menu_data must be a dict, list, or JSON string.")
+
+    def _extract_menu_list(self, data: dict | list) -> list:
+        if isinstance(data, list):
+            return data
+        if isinstance(data, dict):
+            return data.get("menu", [])
+        raise TypeError("Tree data must be a list or a dict with a menu key.")
+
+    def _build_tree(self, data: list, level: int = 0) -> list["_DEx_TreeNode"]:
+        nodes: list[_DEx_TreeNode] = []
+        for item in data:
+            children = self._build_tree(item.get("children", []), level + 1)
+            nodes.append(
+                _DEx_TreeNode(
+                    label=item["label"],
+                    node_type=item.get("type", "file"),
+                    icon=item.get("icon"),
+                    children=children,
+                    level=level,
+                    on_select=self._on_select,
+                    show_icon=self.show_icon,
+                    indent_step=self.indent_step,
+                    toggle_size=self.toggle_size,
+                )
+            )
+        return nodes
+
+    def _get_visible_nodes(self) -> list["_DEx_TreeNode"]:
+        nodes: list[_DEx_TreeNode] = []
+
+        def walk(items: list[_DEx_TreeNode]) -> None:
+            for node in items:
+                nodes.append(node)
+                if node.expanded and node.children:
+                    walk(node.children)
+
+        walk(self.root_nodes)
+        return nodes
+
+    def _on_select(self, node: "_DEx_TreeNode") -> None:
+        current = self.selected_node["node"]
+        if current is not None and current is not node:
+            current.is_selected = False
+            current.refresh()
+        node.is_selected = True
+        self.selected_node["node"] = node
+        node.refresh()
+        if self.external_on_select:
+            self.external_on_select(node)
+
+    def _move_selection(self, delta: int) -> None:
+        if self.search_field.value:
+            return
+        visible = self._get_visible_nodes()
+        if not visible:
+            return
+        current = self.selected_node["node"]
+        index = visible.index(current) if current in visible else 0
+        next_index = max(0, min(len(visible) - 1, index + delta))
+        self._on_select(visible[next_index])
+        self._update_tree()
+
+    def _apply_search(self) -> None:
+        self.tree_col.controls = _filter_tree(self.root_nodes, self.search_field.value)
+        self._update_tree()
+
+    def _clear_search(self, e: ft.ControlEvent | None = None) -> None:
+        self.search_field.value = ""
+        self._apply_search()
+        if _is_mounted(self.search_field):
+            self.search_field.update()
+
+    def _update_tree(self) -> None:
+        if _is_mounted(self.tree_col):
+            self.tree_col.update()
+
+
+class _DEx_TreeNode:
+    """Internal node model used by `DEx_TreeView`."""
+
+    def __init__(
+        self,
+        label: str,
+        node_type: str,
+        icon: str | ft.IconData | None = None,
+        children: list["_DEx_TreeNode"] | None = None,
+        level: int = 0,
+        on_select: Callable[["_DEx_TreeNode"], None] | None = None,
+        show_icon: bool = True,
+        indent_step: int = 15,
+        toggle_size: int = 18,
+    ) -> None:
+        self.label = label
+        self.node_type = node_type
+        self.icon = icon
+        self.children = children or []
+        self.level = level
+        self.on_select = on_select
+        self.expanded = level == 0
+        self.is_selected = False
+        self.show_icon = show_icon
+        self.indent_step = indent_step
+        self.toggle_size = toggle_size
+
+        self._children_column = ft.Column(spacing=0)
+        self._toggle_icon: ft.Icon | None = None
+        self._item_icon: ft.Icon | None = None
+        self._label_text_controls: list[tuple[ft.Text, str]] = []
+        self.control = self._build()
+
+    def toggle(self, e: ft.ControlEvent | None = None) -> None:
+        self.expanded = not self.expanded
+        self.refresh()
+
+    def select(self, e: ft.ControlEvent | None = None) -> None:
+        if self.on_select:
+            self.on_select(self)
+
+    def refresh(self, update: bool = True) -> None:
+        self._children_column.controls = [child.control for child in self.children] if self.expanded else []
+        self._sync_visuals()
+        if update and _is_mounted(self.control):
+            self.control.update()
+
+    def _build(self) -> ft.Column:
+        header = ft.Container(
+            height=28,
+            content=ft.Row(
+                self._build_row_controls(),
+                spacing=3,
+                vertical_alignment=ft.CrossAxisAlignment.CENTER,
+            ),
+            bgcolor=_selected_node_bgcolor() if self.is_selected else None,
+            border_radius=6,
+            padding=ft.Padding(0, 0, 6, 0),
+            on_click=self.select,
+            ink=True,
+        )
+        self._children_column.controls = [child.control for child in self.children] if self.expanded else []
+        return ft.Column([header, self._children_column], spacing=0)
+
+    def _build_row_controls(self) -> list[ft.Control]:
+        has_children = bool(self.children)
+        controls: list[ft.Control] = [ft.Container(width=self.indent_step * self.level)]
+
+        if has_children:
+            self._toggle_icon = ft.Icon(self._toggle_icon_name(), size=15, color=Colors.TEXT_SECONDARY)
+            controls.append(
+                ft.Container(
+                    width=self.toggle_size,
+                    height=self.toggle_size,
+                    alignment=ft.Alignment(0, 0),
+                    content=self._toggle_icon,
+                    on_click=self.toggle,
+                )
+            )
+        else:
+            controls.append(ft.Container(width=self.toggle_size, height=self.toggle_size))
+
+        if self.show_icon:
+            self._item_icon = ft.Icon(self._resolve_item_icon(has_children), size=15, color=Colors.DATA)
+            controls.append(self._item_icon)
+
+        controls.append(self._build_label_control())
+        return controls
+
+    def _build_label_control(self) -> ft.Control:
+        match = re.match(r"^\(([^)]+)\)\s*-\s*(.*)$", self.label)
+        if match:
+            id_text = ft.Text(f"({match.group(1)})", size=11, color=Colors.DATA, font_family="monospace")
+            label_text = ft.Text(match.group(2), size=13, color=Colors.TEXT_PRIMARY)
+            self._label_text_controls = [(id_text, "id"), (label_text, "label")]
+            return ft.Row(
+                [id_text, label_text],
+                spacing=5,
+                vertical_alignment=ft.CrossAxisAlignment.CENTER,
+            )
+        label_text = ft.Text(self.label, size=13, color=Colors.TEXT_PRIMARY)
+        self._label_text_controls = [(label_text, "label")]
+        return label_text
+
+    def _toggle_icon_name(self) -> ft.IconData:
+        return ft.Icons.KEYBOARD_ARROW_DOWN_ROUNDED if self.expanded else ft.Icons.CHEVRON_RIGHT_ROUNDED
+
+    def _resolve_item_icon(self, has_children: bool) -> ft.IconData:
+        if self.icon:
+            if isinstance(self.icon, str):
+                icon_key = self.icon.strip().lower()
+                if icon_key == "folder":
+                    return ft.Icons.FOLDER_OPEN_OUTLINED if self.expanded else ft.Icons.FOLDER_OUTLINED
+                if icon_key == "docs":
+                    return ft.Icons.DESCRIPTION_OUTLINED
+
+                resolved = getattr(ft.Icons, self.icon.strip().upper(), None)
+                if resolved is not None:
+                    return resolved
+            return self.icon
+
+        if has_children:
+            return ft.Icons.FOLDER_OPEN_OUTLINED if self.expanded else ft.Icons.FOLDER_OUTLINED
+        return ft.Icons.DESCRIPTION_OUTLINED
+
+    def _sync_visuals(self) -> None:
+        has_children = bool(self.children)
+        selected_bgcolor = _selected_node_bgcolor()
+        selected_color = _readable_text_color(selected_bgcolor)
+        if self._toggle_icon is not None:
+            self._toggle_icon.name = self._toggle_icon_name()
+            self._toggle_icon.color = selected_color if self.is_selected else Colors.TEXT_SECONDARY
+        if self._item_icon is not None:
+            self._item_icon.name = self._resolve_item_icon(has_children)
+            self._item_icon.color = selected_color if self.is_selected else Colors.DATA
+
+        header = self.control.controls[0]
+        header.bgcolor = selected_bgcolor if self.is_selected else None
+        header.border = ft.Border.all(1, Colors.ACCENT) if self.is_selected else None
+
+        for text_control, role in self._label_text_controls:
+            if self.is_selected:
+                text_control.color = selected_color
+            elif role == "id":
+                text_control.color = Colors.DATA
+            else:
+                text_control.color = Colors.TEXT_PRIMARY
+
+
+def _is_mounted(control: ft.Control) -> bool:
+    return getattr(control, "_Control__uid", None) is not None
+
+
+def _selected_node_bgcolor() -> str:
+    return Colors.ACCENT
+
+
+def _readable_text_color(bgcolor: str) -> str:
+    black_ratio = _contrast_ratio(bgcolor, "#000000")
+    white_ratio = _contrast_ratio(bgcolor, "#FFFFFF")
+    return "#000000" if black_ratio >= white_ratio else "#FFFFFF"
+
+
+def _contrast_ratio(color_a: str, color_b: str) -> float:
+    lum_a = _relative_luminance(color_a)
+    lum_b = _relative_luminance(color_b)
+    lighter = max(lum_a, lum_b)
+    darker = min(lum_a, lum_b)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def _relative_luminance(hex_color: str) -> float:
+    red, green, blue = _hex_to_rgb(hex_color)
+    values = []
+    for channel in (red, green, blue):
+        value = channel / 255
+        values.append(value / 12.92 if value <= 0.03928 else ((value + 0.055) / 1.055) ** 2.4)
+    return 0.2126 * values[0] + 0.7152 * values[1] + 0.0722 * values[2]
+
+
+def _hex_to_rgb(hex_color: str) -> tuple[int, int, int]:
+    value = hex_color.strip().lstrip("#")[:6]
+    if len(value) != 6:
+        return (0, 0, 0)
+    return (int(value[0:2], 16), int(value[2:4], 16), int(value[4:6], 16))
+
+
+def _set_expanded_node(node: _DEx_TreeNode, expanded: bool) -> None:
+    node.expanded = expanded
+    for child in node.children:
+        _set_expanded_node(child, expanded)
+    node.refresh(update=False)
+
+
+def _filter_tree(nodes: list[_DEx_TreeNode], query: str | None) -> list[ft.Control]:
+    query = (query or "").strip().lower()
+    if not query:
+        for node in nodes:
+            _reset_node(node)
+        return [node.control for node in nodes]
+
+    matches: list[ft.Control] = []
+    for node in nodes:
+        if _apply_filter(node, query):
+            matches.append(node.control)
+    return matches
+
+
+def _reset_node(node: _DEx_TreeNode) -> None:
+    for child in node.children:
+        _reset_node(child)
+    node._children_column.controls = [child.control for child in node.children] if node.expanded else []
+    node._sync_visuals()
+
+
+def _apply_filter(node: _DEx_TreeNode, query: str) -> bool:
+    matched_children = [child for child in node.children if _apply_filter(child, query)]
+    is_match = query in node.label.lower()
+
+    if matched_children:
+        node.expanded = True
+        node._children_column.controls = [child.control for child in matched_children]
+        node._sync_visuals()
+        return True
+
+    if is_match:
+        node.expanded = False
+        node._children_column.controls = []
+        node._sync_visuals()
+        return True
+
+    return False

components/feedback/DEx_AlertDialog.py

@@ -0,0 +1,26 @@
+import flet as ft
+from components.theme.DEx_Theme import Colors, Spacing
+
+COMPONENT_VERSION = "0.0.1"
+
+
+def DEx_AlertDialog(
+    title: str,
+    content: ft.Control | str | None = None,
+    actions: list[ft.Control] | None = None,
+    on_dismiss=None,
+) -> ft.AlertDialog:
+    """Modal dialog for confirmations, alerts and short forms."""
+    body = (
+        ft.Text(content, size=13, color=Colors.TEXT_SECONDARY)
+        if isinstance(content, str)
+        else content
+    )
+    return ft.AlertDialog(
+        title=ft.Text(title, size=16, weight=ft.FontWeight.W_600, color=Colors.TEXT_PRIMARY),
+        content=body,
+        actions=actions or [],
+        on_dismiss=on_dismiss,
+        bgcolor=Colors.BG_ELEVATED,
+        shape=ft.RoundedRectangleBorder(radius=Spacing.CARD_BORDER_RADIUS),
+    )

components/feedback/DEx_Banner.py

@@ -0,0 +1,19 @@
+import flet as ft
+from components.theme.DEx_Theme import Colors, Spacing
+
+COMPONENT_VERSION = "0.0.1"
+
+
+def DEx_Banner(
+    message: str,
+    icon: str = ft.Icons.INFO_OUTLINE_ROUNDED,
+    actions: list[ft.Control] | None = None,
+    bgcolor: str | None = None,
+) -> ft.Banner:
+    """Persistent informational banner displayed below the AppBar."""
+    return ft.Banner(
+        content=ft.Text(message, size=13, color=Colors.TEXT_PRIMARY),
+        leading=ft.Icon(icon, color=Colors.ACCENT, size=20),
+        actions=actions or [],
+        bgcolor=bgcolor or Colors.BG_ELEVATED,
+    )

components/feedback/DEx_BottomSheet.py

@@ -0,0 +1,37 @@
+import flet as ft
+from components.theme.DEx_Theme import Colors, Spacing
+
+COMPONENT_VERSION = "0.0.2"
+
+
+def DEx_BottomSheet(
+    content: ft.Control,
+    on_dismiss=None,
+) -> ft.BottomSheet:
+    """Bottom sheet that slides up from the bottom edge of the screen."""
+    return ft.BottomSheet(
+        content=ft.Container(
+            content=content,
+            bgcolor=Colors.BG_ELEVATED,
+            border_radius=ft.BorderRadius(
+                top_left=Spacing.CARD_BORDER_RADIUS,
+                top_right=Spacing.CARD_BORDER_RADIUS,
+                bottom_left=0,
+                bottom_right=0,
+            ),
+            padding=ft.Padding.symmetric(horizontal=Spacing.LG, vertical=Spacing.MD),
+        ),
+        bgcolor=Colors.BG_ELEVATED,
+        dismissible=True,
+        draggable=True,
+        show_drag_handle=True,
+        scrollable=True,
+        clip_behavior=ft.ClipBehavior.ANTI_ALIAS,
+        shape=ft.RoundedRectangleBorder(
+            radius=ft.BorderRadius(
+                top_left=Spacing.CARD_BORDER_RADIUS,
+                top_right=Spacing.CARD_BORDER_RADIUS,
+            )
+        ),
+        on_dismiss=on_dismiss,
+    )

components/feedback/DEx_Notify.py

@@ -0,0 +1,15 @@
+import flet as ft
+from components.theme.DEx_Theme import Colors
+
+COMPONENT_VERSION = "0.0.1"
+
+
+def DEx_Notify(page: ft.Page, message: str, success: bool = True) -> None:
+    """Show the versioned DEx snackbar notification on the current page."""
+    page.snack_bar = ft.SnackBar(
+        content=ft.Text(message, color=Colors.TEXT_PRIMARY, size=13),
+        bgcolor=Colors.SUCCESS if success else Colors.DANGER,
+        duration=3000,
+    )
+    page.snack_bar.open = True
+    page.update()

components/feedback/DEx_ProgressBar.py

@@ -0,0 +1,34 @@
+import flet as ft
+from components.theme.DEx_Theme import Colors, Spacing
+
+COMPONENT_VERSION = "0.0.1"
+
+
+def DEx_ProgressBar(
+    value: float | None = None,
+    label: str = "",
+    show_percent: bool = False,
+    color: str | None = None,
+    bgcolor: str | None = None,
+    height: int = 6,
+) -> ft.Column:
+    """Horizontal progress bar with optional label and percentage."""
+    bar = ft.ProgressBar(
+        value=value,
+        color=color or Colors.ACCENT,
+        bgcolor=bgcolor or Colors.BG_ELEVATED,
+        height=height,
+        border_radius=height,
+    )
+    if not label and not show_percent:
+        return ft.Column([bar], spacing=0, tight=True)
+
+    pct_text = f"{int((value or 0) * 100)}%" if show_percent and value is not None else ""
+    header = ft.Row(
+        [
+            ft.Text(label, size=12, color=Colors.TEXT_SECONDARY) if label else ft.Container(),
+            ft.Text(pct_text, size=12, color=Colors.TEXT_MUTED) if pct_text else ft.Container(),
+        ],
+        alignment=ft.MainAxisAlignment.SPACE_BETWEEN,
+    )
+    return ft.Column([header, bar], spacing=Spacing.XS, tight=True)