feat: add ProgressBar component with customizable styles

Author: m-xim

textcompose/core/types.py

@@ -6,4 +6,4 @@
     from textcompose.core.component import Component  # type: ignore[unused-import]
 
 Value = Union[MagicFilter, str, Callable[[Mapping[str, Any]], str | None], "Component"]
-Condition = Union[MagicFilter, Callable[[Mapping[str, Any]], bool], bool, "Component"]
+Condition = Union[MagicFilter, Callable[[Mapping[str, Any]], bool], bool, str, "Component"]

textcompose/elements/progress_bar.py

@@ -0,0 +1,64 @@
+from textcompose.core import Condition, Value, resolve_value
+from textcompose.elements.base import Element
+from textcompose.styles.progress_bar import PROGRESS_BAR_STYLES, ProgressBarStyle
+
+
+class ProgressBar(Element):
+    def __init__(
+        self,
+        current: Value,
+        total: Value = 100,
+        width: Value | int = 20,
+        style: Value | ProgressBarStyle = "emoj_square",
+        when: Condition | None = None,
+    ):
+        super().__init__(when=when)
+        self.current = current
+        self.total = total
+        self.width = width
+        self.style = style
+        self.when = when
+
+    def render(self, context, **kwargs) -> str | None:
+        if not self._check_when(context, **kwargs):
+            return None
+
+        if isinstance(self.style, str):
+            style_obj = PROGRESS_BAR_STYLES.get(self.style, None)
+        else:
+            style_obj = ProgressBarStyle(
+                left=resolve_value(self.style.left, context),
+                fill=resolve_value(self.style.fill, context),
+                empty=resolve_value(self.style.empty, context),
+                right=resolve_value(self.style.right, context),
+            )
+            if self.style.template is not None:
+                style_obj.template = resolve_value(self.style.template, context)
+
+        if style_obj is None:
+            raise ValueError(f"Unknown style: {self.style}. Available styles: {', '.join(PROGRESS_BAR_STYLES.keys())}")
+
+        length = int(resolve_value(self.width, context))
+        if length <= 0:
+            raise ValueError("Progress bar length must be a positive integer.")
+        current = float(resolve_value(self.current, context))
+        if current < 0:
+            raise ValueError("Current value must be non-negative.")
+        total = float(resolve_value(self.total, context))
+        if total <= 0:
+            raise ValueError("Total value must be greater than zero.")
+
+        percent = min(max(current / total, 0), 1)
+        filled_len = int(round(length * percent))
+        empty_len = length - filled_len
+
+        bar_str = (style_obj.fill * filled_len) + (style_obj.empty * empty_len)
+
+        return style_obj.template.format(
+            left=style_obj.left,
+            bar=bar_str,
+            right=style_obj.right,
+            percent=f"{int(percent * 100)}%",
+            total=total,
+            current=current,
+        )

textcompose/styles/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["ProgressBarStyle"]
+
+from textcompose.styles.progress_bar import ProgressBarStyle

textcompose/styles/progress_bar.py

@@ -0,0 +1,62 @@
+from dataclasses import dataclass
+
+from textcompose.core import Value
+
+
+@dataclass
+class ProgressBarStyle:
+    """
+    Configuration for customizing the appearance of a progress bar.
+
+    Attributes:
+        left (str | Value): Character or value for the left border.
+        fill (str | Value): Character or value for the filled portion.
+        empty (str | Value): Character or value for the empty portion.
+        right (str | Value): Character or value for the right border.
+        template (str): Format string for rendering the progress bar.
+
+            Defaults to "{left}{bar}{right} {percent}".
+
+            Supported placeholders:
+                - {left}: Left border.
+                - {bar}: Combined filled and empty segments.
+                - {right}: Right border.
+                - {percent}: Progress percentage (e.g., "50%").
+                - {total}: Total number of steps.
+                - {current}: Current step number.
+
+    Built-in styles:
+        Several built-in progress bar styles are available in the `PROGRESS_BAR_STYLES` dictionary
+        defined in this file. To use a built-in style, simply specify its name (string key).
+        For example:
+
+            style = "symbol_square"
+
+        See the `PROGRESS_BAR_STYLES` dictionary in this file for the full list of available style names.
+    """
+
+    left: str | Value
+    fill: str | Value
+    empty: str | Value
+    right: str | Value
+    template: str = "{left}{bar}{right} {percent}"
+
+
+PROGRESS_BAR_STYLES = {
+    # Symbol styles
+    "symbol_square": ProgressBarStyle(left="[", fill="■", empty=" ", right="]"),
+    "symbol_simple": ProgressBarStyle(left="[", fill="=", empty=" ", right="]"),
+    "symbol_modern": ProgressBarStyle(left="|", fill="█", empty=" ", right="|"),
+    "symbol_classic": ProgressBarStyle(left="[", fill="#", empty="-", right="]"),
+    "symbol_block": ProgressBarStyle(left="[", fill="█", empty="░", right="]"),
+    "symbol_arrow": ProgressBarStyle(left="|", fill="=", empty="-", right=">"),
+    "symbol_circle": ProgressBarStyle(left="(", fill="●", empty="○", right=")"),
+    "symbol_bracket": ProgressBarStyle(left="<", fill="#", empty=".", right=">"),
+    "symbol_star": ProgressBarStyle(left="[", fill="★", empty="☆", right="]"),
+    "symbol_magic": ProgressBarStyle(left="{", fill="▓", empty="░", right="}"),
+    "symbol_line": ProgressBarStyle(left="[", fill="=", empty=" ", right="]"),
+    "symbol_pipe": ProgressBarStyle(left="|", fill="█", empty=" ", right="|"),
+    # Emoji styles
+    "emoj_square": ProgressBarStyle(left="", fill="🟩", empty="⬜", right=""),
+    "emoji_circle": ProgressBarStyle(left="", fill="🟢", empty="⚪", right=""),
+}