flask-construct-ui 0.9.5__py3-none-any.whl

flask_construct_ui/components.py

@@ -0,0 +1,812 @@
+from __future__ import annotations
+from typing import List, Dict, Any, Optional, Tuple, Union, Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from abc import ABC, abstractmethod
+from datetime import datetime, date
+import calendar
+import inspect
+import locale
+import uuid
+from copy import copy
+from markupsafe import Markup
+from textwrap import dedent
+import jinja2
+import pygal
+from markdown_it import MarkdownIt
+from flask import current_app, g, url_for
+from flask_construct_ui.language import LOCALE_MAPPING
+from .sanitize import sanitize_html
+
+
+class ChartType(Enum):
+    BAR = "bar"
+    LINE = "line"
+    PIE = "pie"
+    STACKED_BAR = "stacked_bar"
+
+
+# default_for_string=True so from_string templates (MarkupComponent args,
+# LiveComponent content_template) escape interpolated values — they can carry
+# user data, unlike the developer-authored template source itself.
+jinja_env = jinja2.Environment(  # nosemgrep: direct-use-of-jinja2
+    loader=jinja2.PackageLoader("flask_construct_ui", "templates"),
+    autoescape=jinja2.select_autoescape(["html", "xml"], default_for_string=True),
+)
+jinja_env.tests["list"] = lambda x: isinstance(x, list)
+
+
+@dataclass
+class Field:
+    type: str
+    key: str
+    label: str
+    required: bool = False
+    options: Optional[Union[List[str], str, Dict[str, str]]] = None
+    value: Any = None
+    secret: bool = False
+
+
+class FieldRendererRegistry:
+    _registry = {}
+
+    @classmethod
+    def register(cls, field_type, renderer):
+        cls._registry[field_type] = renderer
+
+    @classmethod
+    def get_renderer(cls, field_type):
+        return cls._registry.get(field_type)
+
+
+def render_richtext_field(field_obj, data, theme):
+    value = data.get(field_obj.key, "") if data else ""
+    rt_component = RichTextComponent(
+        name=field_obj.key, label=field_obj.label, content=value
+    )
+    rendered_html = Markup(rt_component.render())  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+    placeholder_field = Field(type="custom", key=field_obj.key, label=field_obj.label)
+    return rendered_html, placeholder_field
+
+
+FieldRendererRegistry.register("richtext", render_richtext_field)
+
+
+@dataclass
+class Trigger:
+    action: str
+    validate: bool = False
+
+
+@dataclass
+class Component(ABC):
+    id: Optional[str] = None
+    css_class: Optional[str] = None
+
+    @abstractmethod
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        """Generate HTML for this component"""
+        pass
+
+    @abstractmethod
+    def get_component_type(self) -> str:
+        """Return the component type identifier"""
+        pass
+
+    def get_children(self) -> list[Component]:
+        """Return a list of child components"""
+        return []
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert component to dictionary representation"""
+        result = {"type": self.get_component_type()}
+        if self.id:
+            result["id"] = self.id
+        return result
+
+
+# Layout components - containers that organize other components
+@dataclass
+class VerticalLayoutComponent(Component):
+    components: List[Component] = field(default_factory=list)
+    spacing: str = "1rem"
+    alignment: str = "stretch"
+
+    def get_component_type(self) -> str:
+        return "vertical_layout"
+
+    def get_children(self) -> list[Component]:
+        return self.components
+
+    def add_component(self, component: Component) -> "VerticalLayoutComponent":
+        self.components.append(component)
+        return self
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        template = jinja_env.get_template(
+            f"themes/{theme}/components/vertical_layout.html"
+        )
+        component_html = Markup("\n".join(comp.render() for comp in self.components))  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+        return template.render(c=self, component_html=component_html)  # nosemgrep: direct-use-of-jinja2
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = super().to_dict()
+        result.update(
+            {
+                "components": [c.to_dict() for c in self.components],
+                "spacing": self.spacing,
+                "alignment": self.alignment,
+            }
+        )
+        return result
+
+
+@dataclass
+class HorizontalLayoutComponent(Component):
+    components: List[Component] = field(default_factory=list)
+    spacing: str = "1rem"
+    wrap: bool = False
+
+    def get_component_type(self) -> str:
+        return "horizontal_layout"
+
+    def get_children(self) -> list[Component]:
+        return self.components
+
+    def add_component(self, component: Component) -> "HorizontalLayoutComponent":
+        self.components.append(component)
+        return self
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        template = jinja_env.get_template(
+            f"themes/{theme}/components/horizontal_layout.html"
+        )
+        component_html = Markup("\n".join(comp.render() for comp in self.components))  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+        return template.render(c=self, component_html=component_html)  # nosemgrep: direct-use-of-jinja2
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = super().to_dict()
+        result.update(
+            {
+                "components": [c.to_dict() for c in self.components],
+                "spacing": self.spacing,
+                "wrap": self.wrap,
+            }
+        )
+        return result
+
+
+@dataclass
+class GridLayoutComponent(Component):
+    components: List[Component] = field(default_factory=list)
+    columns: int = 2
+    gap: str = "1rem"
+
+    def get_component_type(self) -> str:
+        return "grid_layout"
+
+    def get_children(self) -> list[Component]:
+        return self.components
+
+    def add_component(self, component: Component) -> "GridLayoutComponent":
+        self.components.append(component)
+        return self
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        template = jinja_env.get_template(f"themes/{theme}/components/grid_layout.html")
+        component_html = Markup("\n".join(comp.render() for comp in self.components))  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+        return template.render(c=self, component_html=component_html)  # nosemgrep: direct-use-of-jinja2
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = super().to_dict()
+        result.update(
+            {
+                "components": [c.to_dict() for c in self.components],
+                "columns": self.columns,
+                "gap": self.gap,
+            }
+        )
+        return result
+
+
+# Specialized container components
+@dataclass
+class CardComponent(Component):
+    components: List[Component] = field(default_factory=list)
+    title: Optional[str] = None
+    outline: bool = False
+    variant: Optional[str] = None
+
+    def get_component_type(self) -> str:
+        return "card"
+
+    def get_children(self) -> list[Component]:
+        return self.components
+
+    def add_component(self, component: Component) -> "CardComponent":
+        self.components.append(component)
+        return self
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        template = jinja_env.get_template(f"themes/{theme}/components/card.html")
+        component_html = Markup("\n".join(comp.render() for comp in self.components))  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+        return template.render(c=self, component_html=component_html)  # nosemgrep: direct-use-of-jinja2
+
+
+@dataclass
+class TabsComponent(Component):
+    id: str  # Make id mandatory for TabsComponent
+    tabs: List[Dict[str, Union[str, Component]]] = field(default_factory=list)
+    active_tab: int = 0
+
+    def get_param_name(self) -> str:
+        return f"{self.id}_tab"
+
+    def get_tab_url(self, index: int) -> str:
+        from flask import request, has_request_context
+        from urllib.parse import urlencode
+
+        param_name = self.get_param_name()
+        if has_request_context():
+            args = request.args.copy()
+            args[param_name] = str(index)
+            return f"?{urlencode(list(args.items(multi=True)))}"
+        return f"?{param_name}={index}"
+
+    def get_component_type(self) -> str:
+        return "tabs"
+
+    def get_children(self) -> list[Component]:
+        return [
+            tab["component"]
+            for tab in self.tabs
+            if isinstance(tab.get("component"), Component)
+        ]
+
+    def add_tab(self, label: str, component: Component) -> "TabsComponent":
+        self.tabs.append({"label": label, "component": component})
+        return self
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        template = jinja_env.get_template(f"themes/{theme}/components/tabs.html")
+
+        # Ensure active_tab is a valid index, default to 0 if not
+        if not (self.tabs and 0 <= self.active_tab < len(self.tabs)):
+            self.active_tab = 0
+
+        active_tab_content = ""
+        # Render content only if there are tabs
+        if self.tabs:
+            active_tab_component = self.tabs[self.active_tab]["component"]
+            active_tab_content = Markup(active_tab_component.render())  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+
+        return template.render(  # nosemgrep: direct-use-of-jinja2
+            c=self,
+            active_tab_content=active_tab_content,
+        )
+
+
+@dataclass
+class FormComponent(Component):
+    fields: List[Field] = field(default_factory=list)
+    actions: List[ButtonComponent] = field(default_factory=list)
+    data: Optional[Dict[str, Any]] = None
+
+    def get_component_type(self) -> str:
+        return "form"
+
+    def get_children(self) -> list[Component]:
+        return self.actions
+
+    def add_field(self, field: Field) -> "FormComponent":
+        self.fields.append(field)
+        return self
+
+    def add_action(self, action: "ButtonComponent") -> "FormComponent":
+        self.actions.append(action)
+        return self
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        if self.data:
+            for f in self.fields:
+                if f.key in self.data:
+                    f.value = self.data.get(f.key)
+
+        # Resolve and render custom fields via registry
+        custom_rendered_fields = {}
+        fields_to_render = []
+        for f in self.fields:
+            renderer = FieldRendererRegistry.get_renderer(f.type)
+            if renderer:
+                rendered_html, placeholder_field = renderer(f, self.data, theme)
+                custom_rendered_fields[f.key] = rendered_html
+                fields_to_render.append(placeholder_field)
+            else:
+                fields_to_render.append(f)
+
+        template = jinja_env.get_template(f"themes/{theme}/components/form.html")
+        # Create a temporary copy of self to modify fields for rendering
+        render_context = copy(self)
+        render_context.fields = fields_to_render
+
+        # Create new ButtonComponent objects for rendering to avoid modifying originals
+        render_actions = []
+        for action in self.actions:
+            new_action = copy(action)
+            new_action.as_link = False
+            new_action.button_type = "submit"
+            render_actions.append(new_action)
+        render_context.actions = render_actions
+
+        return template.render(  # nosemgrep: direct-use-of-jinja2
+            c=render_context, custom_rendered_fields=custom_rendered_fields
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = super().to_dict()
+        result.update(
+            {
+                "fields": [
+                    {
+                        "type": f.type,
+                        "key": f.key,
+                        "label": f.label,
+                        "required": f.required,
+                        **({"options": f.options} if f.options else {}),
+                    }
+                    for f in self.fields
+                ],
+                "actions": [
+                    {"type": a.type, "label": a.label, "trigger": a.trigger}
+                    for a in self.actions
+                ],
+            }
+        )
+        return result
+
+
+@dataclass
+class ChartComponent(Component):
+    data: List[Tuple[str, List[Any]]] = field(default_factory=list)
+    chart_type: ChartType = None
+    width: Optional[int] = None
+    height: Optional[int] = None
+    datasource: Optional[str] = None
+
+    def get_component_type(self) -> str:
+        return "chart"
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        chart_svg = ""
+        chart = None
+
+        is_timeseries = False
+        if (
+            self.data
+            and self.data[0]
+            and self.data[0][1]
+            and isinstance(self.data[0][1][0], Tuple)
+            and isinstance(self.data[0][1][0][0], (datetime, date))
+        ):
+            is_timeseries = True
+
+        config_kwargs = {}
+        if self.width:
+            config_kwargs["width"] = self.width
+        if self.height:
+            config_kwargs["height"] = self.height
+
+        if is_timeseries:
+            config_kwargs["x_label_rotation"] = 20
+            config_kwargs["truncate_label"] = -1
+        chart_class = None
+
+        if isinstance(self.chart_type, str):
+            # Convert from string to enum.
+            self.chart_type = ChartType(self.chart_type.lower())
+
+        if self.chart_type == ChartType.BAR:
+            chart_class = pygal.Bar
+        elif self.chart_type == ChartType.STACKED_BAR:
+            chart_class = pygal.StackedBar
+        elif self.chart_type == ChartType.LINE:
+            chart_class = pygal.DateTimeLine if is_timeseries else pygal.Line
+        elif self.chart_type == ChartType.PIE:
+            chart_class = pygal.Pie
+
+        if chart_class:
+            chart = chart_class(**config_kwargs)
+        else:
+            chart_svg = f"<p>Unsupported chart type {self.chart_type}</p>"
+
+        if chart:
+            if (
+                self.chart_type in (ChartType.BAR, ChartType.STACKED_BAR)
+                and is_timeseries
+            ):
+                x_labels_set = set()
+                for _, series_data in self.data:
+                    for point in series_data:
+                        x_labels_set.add(point[0])
+
+                sorted_x_labels = sorted(list(x_labels_set))
+                chart.x_labels = [
+                    label.strftime("%Y-%m-%d %H:%M") for label in sorted_x_labels
+                ]
+
+                for series_name, series_data in self.data:
+                    data_map = dict(series_data)
+                    aligned_values = [data_map.get(label) for label in sorted_x_labels]
+                    chart.add(series_name, aligned_values)
+            else:
+                for series_name, series_data in self.data:
+                    if self.chart_type == ChartType.PIE and series_data:
+                        chart.add(series_name, series_data[0])
+                    else:
+                        chart.add(series_name, series_data)
+
+            chart_svg = chart.render(is_unicode=True)
+
+        template = jinja_env.get_template(f"themes/{theme}/components/chart.html")
+        return template.render(c=self, chart_svg=chart_svg)  # nosemgrep: direct-use-of-jinja2
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = super().to_dict()
+        result.update(
+            {
+                "data": self.data,
+                "chart_type": self.chart_type.value,
+                "datasource": self.datasource,
+            }
+        )
+        return result
+
+
+@dataclass
+class TextComponent(Component):
+    content: str = ""
+    tag: str = "p"  # p, h1, h2, span, etc.
+
+    def get_component_type(self) -> str:
+        return "text"
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        template = jinja_env.get_template(f"themes/{theme}/components/text.html")
+        return template.render(c=self)  # nosemgrep: direct-use-of-jinja2
+
+
+@dataclass
+class MarkupComponent(Component):
+    """Renders Markdown/Org/HTML content, with Jinja interpolation of ``args``.
+
+    SECURITY: ``content`` is treated as a developer-authored *template* — after
+    Markdown/Org conversion (and sanitization) it is still rendered with Jinja
+    (``from_string``). Never pass untrusted/user-supplied input as ``content``:
+    even after HTML sanitization it would remain a server-side template
+    injection (SSTI) vector (e.g. ``{{ config }}``). Pass dynamic or
+    user-supplied values through ``args`` instead — those are HTML-escaped and
+    are not re-evaluated as templates. ``format="html"`` is additionally a raw
+    escape hatch (no sanitization) and must only carry trusted markup.
+    """
+
+    content: str = ""
+    format: str = "md"
+    args: Dict[str, Any] = field(default_factory=dict)
+
+    def get_component_type(self) -> str:
+        return "markup"
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        # Dedent content to allow for indented triple-quoted strings
+        dedented_content = dedent(self.content)
+
+        if self.format == "html":
+            # Raw by design: format="html" is a developer escape hatch and
+            # must never carry user-supplied data.
+            html_template_str = dedented_content
+        elif self.format == "md":
+            md = MarkdownIt("js-default", {"html": True})
+            html_template_str = sanitize_html(md.render(dedented_content))
+        elif self.format in ("org", "orgmode"):
+            from .orgmode import org_to_html
+            html_template_str = sanitize_html(org_to_html(dedented_content))
+        else:
+            raise NotImplementedError(
+                f"Format '{self.format}' is not supported. Use 'html', 'md', or 'org'."
+            )
+
+        # Render the HTML with Jinja2 to process any embedded variables
+        template = jinja_env.from_string(html_template_str)
+        rendered_html = template.render(**self.args)
+
+        component_template = jinja_env.get_template(
+            f"themes/{theme}/components/markup.html"
+        )
+        return component_template.render(c=self, content=Markup(rendered_html))  # nosemgrep: direct-use-of-jinja2, explicit-unescape-with-markup  # nosec B704
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = super().to_dict()
+        result.update(
+            {
+                "content": self.content,
+                "format": self.format,
+                "args": self.args,
+            }
+        )
+        return result
+
+
+@dataclass
+class RichTextComponent(Component):
+    name: str = ""
+    content: str = ""
+    label: Optional[str] = None
+    style_tag: bool = True
+
+    def get_component_type(self) -> str:
+        return "rich_text"
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        editor_id = self.id or f"editor_{self.name}"
+        template = jinja_env.get_template(f"themes/{theme}/components/rich_text.html")
+        return template.render(c=self, editor_id=editor_id)  # nosemgrep: direct-use-of-jinja2
+
+
+@dataclass
+class ButtonComponent(Component):
+    label: str = None
+    action: Union[str, Callable] = None
+    action_args: Optional[Dict[str, Any]] = None
+    variant: str = "primary"  # primary, secondary, danger
+    as_link: bool = True
+    button_type: str = "button"
+    target: str = ""
+
+    def get_component_type(self) -> str:
+        return "button"
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+
+        action_url = "#"
+        if self.action:
+            if isinstance(self.action, str):
+                if self.action.startswith("/") or self.action.startswith("http"):
+                    action_url = self.action
+                else:
+                    try:
+                        if self.action_args:
+                            action_url = url_for(self.action, **self.action_args)
+                        else:
+                            action_url = url_for(self.action)
+                    except Exception:
+                        if current_app.debug:
+                            raise
+                        action_url = "#"
+            elif inspect.ismethod(self.action):
+                if hasattr(self.action, "__self__"):
+                    page = self.action.__self__
+                    if hasattr(page, "endpoint"):
+                        endpoint = f"{page.endpoint}.{self.action.__name__}"
+                        try:
+                            if self.action_args:
+                                action_url = url_for(endpoint, **self.action_args)
+                            else:
+                                action_url = url_for(endpoint)
+                        except Exception:
+                            if current_app.debug:
+                                raise
+                            action_url = "#"
+
+        template = jinja_env.get_template(f"themes/{theme}/components/button.html")
+
+        return template.render(c=self, action_url=action_url)  # nosemgrep: direct-use-of-jinja2
+
+
+@dataclass
+class TableComponent(Component):
+    headers: List[str] = None
+    rows: Optional[List[List[Any]]] = None
+    data_source: Optional[str] = None
+    striped: bool = False
+    hover: bool = False
+
+    def get_component_type(self) -> str:
+        return "table"
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        template = jinja_env.get_template(f"themes/{theme}/components/table.html")
+        return template.render(c=self)  # nosemgrep: direct-use-of-jinja2
+
+
+@dataclass
+class CalendarComponent(Component):
+    datasource: Optional[str] = None
+    data: List[Dict[str, Any]] = field(default_factory=list)
+    start_day: str = "monday"  # 'monday' or 'sunday'
+    mini: bool = False
+
+    def get_component_type(self) -> str:
+        return "calendar"
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+
+        if self.start_day.lower() == "sunday":
+            calendar.setfirstweekday(calendar.SUNDAY)
+        else:
+            calendar.setfirstweekday(calendar.MONDAY)
+
+        if self.data:
+            first_date = self.data[0].get("date")
+            if isinstance(first_date, (datetime, date)):
+                year, month = first_date.year, first_date.month
+            else:
+                today = date.today()
+                year, month = today.year, today.month
+        else:
+            today = date.today()
+            year, month = today.year, today.month
+        lang = getattr(g, "language", None)
+        target_locale = LOCALE_MAPPING.get(lang)
+        day_names = calendar.weekheader(3).split()
+        month_name = calendar.month_name[month]
+        if target_locale:
+            original_locale = locale.getlocale(locale.LC_TIME)
+            try:
+                locale.setlocale(locale.LC_TIME, target_locale)
+                # Re-fetch names with the new locale
+                day_names = calendar.weekheader(3).split()
+                month_name = calendar.month_name[month]
+            except locale.Error:
+                # If locale is not installed on the system, it will fail.
+                # We just fall back to the default names.
+                pass
+
+            finally:
+                # Always restore the original locale
+                locale.setlocale(locale.LC_TIME, original_locale)
+
+        month_calendar = calendar.monthcalendar(year, month)
+
+        # Cell content may come from a @datasource carrying user data, and the
+        # API allows HTML snippets — sanitize before the template marks it safe.
+        content_map = {
+            item["date"].day: Markup(sanitize_html(str(item["content"])))  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+            for item in self.data
+            if item.get("date") and item.get("content")
+        }
+
+        if self.mini:
+            template = jinja_env.get_template(
+                f"themes/{theme}/components/calendarmini.html"
+            )
+        else:
+            template = jinja_env.get_template(
+                f"themes/{theme}/components/calendar.html"
+            )
+
+        return template.render(
+            c=self,
+            year=year,
+            month_name=month_name,
+            day_names=day_names,
+            weeks=month_calendar,
+            content=content_map,
+        )
+
+
+@dataclass
+class LiveComponent(Component):
+    """Component that displays live-updating data from a @livesource method or an explicit SSE URL."""
+
+    live_source: Optional[str] = None
+    interval: int = 10
+    title: Optional[str] = None
+    content_template: Optional[str] = None
+    content_style: Optional[str] = None
+    placeholder: str = ""
+    sse_url: Optional[str] = None
+    poll_url: Optional[str] = None
+    format: str = "default"
+    max_lines: Optional[int] = 200
+
+    def __post_init__(self):
+        if not self.live_source and self.sse_url is None:
+            raise ValueError("LiveComponent requires either live_source or sse_url")
+
+        if self.sse_url is not None:
+            self._sse_url = self.sse_url
+            self._poll_url = self.poll_url if self.poll_url is not None else ""
+            if self.id is None:
+                self.id = f"live-{uuid.uuid4().hex[:8]}"
+        else:
+            self._sse_url = ""
+            self._poll_url = ""
+
+        self._resolved_interval = self.interval
+        self._live_data = None
+
+    def get_component_type(self) -> str:
+        return "live"
+
+    def render(self) -> str:
+        theme = getattr(g, "construct_theme", "whitelabel")
+        template = jinja_env.get_template(f"themes/{theme}/components/live.html")
+
+        content_html = None
+        if self._live_data is not None and self.content_template:
+            content_html = Markup(  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+                jinja_env.from_string(self.content_template).render(**self._live_data)
+            )
+
+        construct = getattr(g, "construct", None)
+        not_updating_text = (
+            construct.t("live-not-updating") if construct else "Not updating"
+        )
+
+        return template.render(  # nosemgrep: direct-use-of-jinja2
+            c=self,
+            content_html=content_html,
+            live_data=self._live_data,
+            interval_ms=self._resolved_interval * 1000,
+            not_updating_text=not_updating_text,
+        )
+
+
+class Components:
+    def __init__(self):
+        self.VerticalLayout = VerticalLayoutComponent
+        self.HorizontalLayout = HorizontalLayoutComponent
+        self.GridLayout = GridLayoutComponent
+        self.Card = CardComponent
+        self.Tabs = TabsComponent
+        self.Form = FormComponent
+        self.Chart = ChartComponent
+        self.Text = TextComponent
+        self.Markup = MarkupComponent
+        self.RichText = RichTextComponent
+        self.Button = ButtonComponent
+        self.Table = TableComponent
+        self.Calendar = CalendarComponent
+        self.Live = LiveComponent
+        self.Field = Field
+
+
+components = Components()
+
+
+def find_component(
+    component: Component, condition: Callable[[Component], bool]
+) -> Optional[Component]:
+    """
+    Traverses the component tree and returns the first component that satisfies the condition (DFS).
+    """
+    if condition(component):
+        return component
+    for child in component.get_children():
+        found = find_component(child, condition)
+        if found:
+            return found
+    return None
+
+
+def find_component_by_id(
+    root_component: Component, component_id: str
+) -> Optional[Component]:
+    """
+    Finds a component by its ID.
+    """
+    return find_component(root_component, lambda c: c.id == component_id)