SaaS-FrameWork 0.1.1__py3-none-any.whl

components/primitives/DEx_SectionEyebrow.py

@@ -0,0 +1,22 @@
+import flet as ft
+from components.theme.DEx_Theme import Colors, Spacing
+
+COMPONENT_VERSION = "0.0.1"
+
+
+def DEx_SectionEyebrow(number: str, label: str) -> ft.Row:
+    """Create the versioned numbered cyan section eyebrow."""
+    return ft.Row(
+        controls=[
+            ft.Text(number, size=11, weight=ft.FontWeight.W_700, color=Colors.DATA),
+            ft.Container(width=1, height=12, bgcolor=Colors.BORDER),
+            ft.Text(
+                label.upper(),
+                size=11,
+                weight=ft.FontWeight.W_600,
+                color=Colors.TEXT_MUTED,
+                style=ft.TextStyle(letter_spacing=1.5),
+            ),
+        ],
+        spacing=Spacing.SM,
+    )

components/primitives/DEx_StatusDot.py

@@ -0,0 +1,8 @@
+import flet as ft
+
+COMPONENT_VERSION = "0.0.1"
+
+
+def DEx_StatusDot(color: str) -> ft.Container:
+    """Create the versioned small colored state dot."""
+    return ft.Container(width=8, height=8, bgcolor=color, border_radius=4)

components/project.py

@@ -0,0 +1,23 @@
+"""Project metadata helpers loaded from pyproject.toml."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import tomllib
+from components.versioning import validate_version
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+PYPROJECT_PATH = PROJECT_ROOT / "pyproject.toml"
+
+
+def get_project_version() -> str:
+    """Return the project version declared in pyproject.toml."""
+    with PYPROJECT_PATH.open("rb") as file:
+        data = tomllib.load(file)
+    return validate_version(data["project"]["version"])
+
+
+def get_project_version_label() -> str:
+    """Return the display-ready project version label."""
+    return f"v{get_project_version()}"

components/theme/DEx_ColorThemes.py

@@ -0,0 +1,375 @@
+"""Accessible 60-30-10 color themes for DEx applications."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import flet as ft
+
+
+COMPONENT_VERSION = "0.0.3"
+
+
+def _blend(base: str, overlay: str, amount: float) -> str:
+    """Mix two hex colors by amount (0.0 = base, 1.0 = overlay)."""
+    try:
+        b = base.strip().lstrip("#")[:6]
+        o = overlay.strip().lstrip("#")[:6]
+        if len(b) != 6 or len(o) != 6:
+            return base
+        br, bg_, bb = int(b[0:2], 16), int(b[2:4], 16), int(b[4:6], 16)
+        or_, og, ob = int(o[0:2], 16), int(o[2:4], 16), int(o[4:6], 16)
+        r = max(0, min(255, round(br + (or_ - br) * amount)))
+        g = max(0, min(255, round(bg_ + (og - bg_) * amount)))
+        b_ = max(0, min(255, round(bb + (ob - bb) * amount)))
+        return f"#{r:02X}{g:02X}{b_:02X}"
+    except (ValueError, IndexError):
+        return base
+
+
+def _hex_to_rgb(hex_color: str) -> tuple[int, int, int]:
+    value = hex_color.strip().lstrip("#")[:6]
+    if len(value) != 6:
+        raise ValueError("Invalid hex color")
+    return (int(value[0:2], 16), int(value[2:4], 16), int(value[4:6], 16))
+
+
+def _relative_luminance(hex_color: str) -> float:
+    r, g, b = _hex_to_rgb(hex_color)
+    channels = []
+    for value in (r, g, b):
+        c = value / 255.0
+        channels.append(c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4)
+    return 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2]
+
+
+def _pick_on_color(hex_color: str) -> str:
+    return "#FFFFFF" if _relative_luminance(hex_color) < 0.45 else "#111111"
+
+
+def _secondary_text(background: str) -> str:
+    return "#E2E8F0" if _relative_luminance(background) < 0.35 else "#475569"
+
+
+def _muted_text(background: str) -> str:
+    return "#CBD5E1" if _relative_luminance(background) < 0.35 else "#64748B"
+
+
+def _disabled_text(background: str) -> str:
+    return "#64748B" if _relative_luminance(background) < 0.35 else "#94A3B8"
+
+
+@dataclass(frozen=True)
+class DEx_ColorTheme:
+    """Versioned color theme using 60-30-10 visual distribution."""
+
+    key: str
+    name: str
+    description: str
+    background: str
+    text: str
+    accent: str
+    contrast_ratio: float
+    accessibility: str
+    accent_alt: str | None = None
+
+    @property
+    def bg_primary(self) -> str:
+        """60% dominant background token."""
+        return self.background
+
+    @property
+    def surface(self) -> str:
+        """Primary surface token used for cards and panels."""
+        return _blend(self.background, self.text, 0.05)
+
+    @property
+    def surface_hover(self) -> str:
+        """Hover state surface token."""
+        return _blend(self.background, self.text, 0.09)
+
+    @property
+    def surface_selected(self) -> str:
+        """Selected state surface token."""
+        return _blend(self.background, self.accent, 0.12)
+
+    @property
+    def surface_elevated(self) -> str:
+        """Raised surface token for menus, cards and overlays."""
+        return _blend(self.background, self.text, 0.13)
+
+    @property
+    def surface_pressed(self) -> str:
+        """Pressed state surface token."""
+        return _blend(self.background, self.text, 0.18)
+
+    @property
+    def surface_disabled(self) -> str:
+        """Disabled state surface token."""
+        return _blend(self.background, self.text, 0.03)
+
+    @property
+    def bg_secondary(self) -> str:
+        """Secondary surface token derived from the dominant color."""
+        return self.surface
+
+    @property
+    def text_primary(self) -> str:
+        """Primary foreground text token."""
+        return self.text
+
+    @property
+    def text_secondary(self) -> str:
+        """Secondary foreground text token."""
+        return _secondary_text(self.background)
+
+    @property
+    def text_muted(self) -> str:
+        """Muted foreground text token."""
+        return _muted_text(self.background)
+
+    @property
+    def text_disabled(self) -> str:
+        """Disabled text token."""
+        return _disabled_text(self.background)
+
+    @property
+    def border(self) -> str:
+        """Structural border token."""
+        return _blend(self.background, self.text, 0.22)
+
+    @property
+    def border_soft(self) -> str:
+        """Subtle border token."""
+        return _blend(self.background, self.text, 0.12)
+
+    @property
+    def focus(self) -> str:
+        """Focus ring token."""
+        return self.accent_primary
+
+    @property
+    def accent_primary(self) -> str:
+        """10% accent token for CTA, badges, links, and critical highlights."""
+        return self.accent
+
+    @property
+    def accent_on(self) -> str:
+        """Foreground color that reads on top of the accent token."""
+        return _pick_on_color(self.accent_primary)
+
+    @property
+    def accent_soft(self) -> str:
+        """Soft accent surface token."""
+        return _blend(self.background, self.accent_primary, 0.16)
+
+    @property
+    def overlay(self) -> str:
+        """Modal overlay token."""
+        return "#00000066" if self.is_dark else "#FFFFFF66"
+
+    @property
+    def is_dark(self) -> bool:
+        """Return whether the theme should be treated as dark."""
+        return _relative_luminance(self.background) < 0.35
+
+    @property
+    def theme_mode(self) -> ft.ThemeMode:
+        """Return the preferred Flet theme mode for this palette."""
+        return ft.ThemeMode.DARK if self.is_dark else ft.ThemeMode.LIGHT
+
+    @property
+    def shadow(self) -> str:
+        """Shadow token for elevated surfaces."""
+        return "#00000040" if self.is_dark else "#00000024"
+
+    @property
+    def data(self) -> str:
+        """Data/highlight accent token."""
+        return self.accent_primary
+
+    def css_variables(self, prefix: str = "--dex") -> dict[str, str]:
+        """Return CSS-style variables for Tailwind or Styled Components usage."""
+        return {
+            f"{prefix}-bg-primary": self.bg_primary,
+            f"{prefix}-bg-secondary": self.bg_secondary,
+            f"{prefix}-surface": self.surface,
+            f"{prefix}-surface-hover": self.surface_hover,
+            f"{prefix}-surface-selected": self.surface_selected,
+            f"{prefix}-surface-elevated": self.surface_elevated,
+            f"{prefix}-surface-pressed": self.surface_pressed,
+            f"{prefix}-surface-disabled": self.surface_disabled,
+            f"{prefix}-text-primary": self.text_primary,
+            f"{prefix}-text-secondary": self.text_secondary,
+            f"{prefix}-text-muted": self.text_muted,
+            f"{prefix}-text-disabled": self.text_disabled,
+            f"{prefix}-border": self.border,
+            f"{prefix}-border-soft": self.border_soft,
+            f"{prefix}-focus": self.focus,
+            f"{prefix}-accent": self.accent_primary,
+            f"{prefix}-accent-alt": self.accent_alt or self.accent_primary,
+            f"{prefix}-accent-soft": self.accent_soft,
+            f"{prefix}-accent-on": self.accent_on,
+            f"{prefix}-overlay": self.overlay,
+            f"{prefix}-shadow": self.shadow,
+        }
+
+    def tokens(self) -> dict[str, str]:
+        """Return the semantic color tokens for UI usage."""
+        return {
+            "bg_primary": self.bg_primary,
+            "bg_secondary": self.bg_secondary,
+            "surface": self.surface,
+            "surface_hover": self.surface_hover,
+            "surface_selected": self.surface_selected,
+            "surface_elevated": self.surface_elevated,
+            "surface_pressed": self.surface_pressed,
+            "surface_disabled": self.surface_disabled,
+            "text_primary": self.text_primary,
+            "text_secondary": self.text_secondary,
+            "text_muted": self.text_muted,
+            "text_disabled": self.text_disabled,
+            "border": self.border,
+            "border_soft": self.border_soft,
+            "focus": self.focus,
+            "accent_primary": self.accent_primary,
+            "accent_alt": self.accent_alt or self.accent_primary,
+            "accent_soft": self.accent_soft,
+            "accent_on": self.accent_on,
+            "overlay": self.overlay,
+            "shadow": self.shadow,
+            "is_dark": str(self.is_dark).lower(),
+            "theme_mode": self.theme_mode.name,
+        }
+
+
+COLOR_THEMES = [
+    DEx_ColorTheme(
+        key="minimalismo_corporativo",
+        name="Minimalismo Corporativo",
+        description="Clean admin and documentation interfaces with maximum reading comfort.",
+        background="#FFFFFF",
+        text="#111827",
+        accent="#0071E3",
+        contrast_ratio=21.0,
+        accessibility="AAA",
+    ),
+    DEx_ColorTheme(
+        key="dark_performance",
+        name="Dark Mode de Alta Performance",
+        description="High-contrast dark dashboards for monitoring and performance tools.",
+        background="#111111",
+        text="#FFFFFF",
+        accent="#FF6A13",
+        contrast_ratio=18.88,
+        accessibility="AAA",
+    ),
+    DEx_ColorTheme(
+        key="fintech_trust",
+        name="Confianca e Fintech",
+        description="Structured B2B and finance interfaces with a secure deep-blue base.",
+        background="#141432",
+        text="#F4F5F7",
+        accent="#0079C1",
+        contrast_ratio=16.37,
+        accessibility="AAA",
+    ),
+    DEx_ColorTheme(
+        key="organic_wellness",
+        name="Organico e Bem-Estar",
+        description="Calm ecological interfaces for lifestyle, sustainability, and health contexts.",
+        background="#006241",
+        text="#FFFFFF",
+        accent="#00A86B",
+        contrast_ratio=7.44,
+        accessibility="AAA",
+    ),
+    DEx_ColorTheme(
+        key="food_delivery",
+        name="Alimentacao e Food Delivery",
+        description="Restaurant, POS, order management, and digital menu interfaces.",
+        background="#FAFAFA",
+        text="#222222",
+        accent="#EA1D2C",
+        contrast_ratio=15.24,
+        accessibility="AAA",
+    ),
+    DEx_ColorTheme(
+        key="automotive_service",
+        name="Area Automotiva",
+        description="Service orders, auto parts catalogs, vehicle intake checklists, and workshop dashboards.",
+        background="#1E2229",
+        text="#F3F4F6",
+        accent="#FFB800",
+        accent_alt="#FF5500",
+        contrast_ratio=14.50,
+        accessibility="AAA",
+    ),
+    DEx_ColorTheme(
+        key="banking_tradition",
+        name="Tradicao e Robustez",
+        description="Internet banking, wallets, ATMs, and investment dashboards with a traditional blue/yellow banking base.",
+        background="#F4F6F9",
+        text="#003399",
+        accent="#003399",
+        accent_alt="#FFFF00",
+        contrast_ratio=10.03,
+        accessibility="AAA",
+    ),
+    DEx_ColorTheme(
+        key="banking_digital",
+        name="Modernidade Digital",
+        description="Digital banking and wallet interfaces with a clear, high-contrast purple identity.",
+        background="#FFFFFF",
+        text="#820AD1",
+        accent="#820AD1",
+        contrast_ratio=7.21,
+        accessibility="AAA",
+    ),
+    DEx_ColorTheme(
+        key="banking_dynamic",
+        name="Solidez e Dinamismo",
+        description="Financial dashboards and transaction flows with off-white base, blue text, and orange action emphasis.",
+        background="#FAFAFA",
+        text="#0038A8",
+        accent="#FF6200",
+        contrast_ratio=9.44,
+        accessibility="AAA",
+    ),
+    DEx_ColorTheme(
+        key="banking_global",
+        name="Presenca Global e Energia",
+        description="Banking contracts, account flows, and transaction screens with neutral text and precise red emphasis.",
+        background="#FFFFFF",
+        text="#1C1C1C",
+        accent="#EC0000",
+        contrast_ratio=17.04,
+        accessibility="AAA",
+    ),
+]
+
+
+def get_color_theme(key: str) -> DEx_ColorTheme:
+    """Return a DEx color theme by key."""
+    for theme in COLOR_THEMES:
+        if theme.key == key:
+            return theme
+    raise ValueError(f"Unknown DEx color theme: {key}")
+
+
+def build_color_theme(theme: DEx_ColorTheme) -> ft.Theme:
+    """Build a Flet theme from a DEx 60-30-10 color theme."""
+    return ft.Theme(
+        color_scheme_seed=theme.accent_primary,
+        color_scheme=ft.ColorScheme(
+            primary=theme.accent_primary,
+            on_primary=theme.accent_on,
+            secondary=theme.accent_primary,
+            on_secondary=theme.accent_on,
+            surface=theme.surface,
+            on_surface=theme.text_primary,
+            surface_container_lowest=theme.bg_primary,
+            surface_container=theme.surface,
+            surface_container_high=theme.surface_elevated,
+        ),
+    )

components/theme/DEx_Theme.py

@@ -0,0 +1,136 @@
+"""
+DEx_Theme.py — Sistema de design do DEx Framework
+Paleta: fundo escuro azulado + violeta elétrico + ciano acento
+"""
+from __future__ import annotations
+
+import flet as ft
+from components.theme.DEx_ColorThemes import DEx_ColorTheme
+
+COMPONENT_VERSION = "0.0.2"
+
+
+class Colors:
+    """Versioned color tokens for the DEx design system."""
+
+    BG_DEEP      = "#0D0F14"
+    BG_SURFACE   = "#151820"
+    BG_ELEVATED  = "#1C2030"
+
+    ACCENT       = "#6C63FF"
+    ACCENT_DARK  = "#4E46CC"
+    DATA         = "#00E5C3"
+    DATA_DARK    = "#00B89C"
+
+    TEXT_PRIMARY   = "#F0F2F8"
+    TEXT_SECONDARY = "#8B90A8"
+    TEXT_MUTED     = "#4A4F66"
+    TEXT_DISABLED  = "#6C738F"
+
+    BORDER         = "#1E2230"
+    BORDER_SOFT    = "#2A3042"
+    BORDER_FOCUS   = "#6C63FF"
+
+    SURFACE_HOVER    = "#1D2230"
+    SURFACE_SELECTED  = "#23293A"
+    SURFACE_PRESSED   = "#11131A"
+    SURFACE_DISABLED  = "#10131A"
+    OVERLAY           = "#00000088"
+
+    ACCENT_SOFT   = "#2B2948"
+    ACCENT_ON     = "#FFFFFF"
+
+    SUCCESS  = "#22C55E"
+    WARNING  = "#F59E0B"
+    DANGER   = "#EF4444"
+    INFO     = "#3B82F6"
+
+
+class Typography:
+    """Versioned typography tokens for the DEx design system."""
+
+    DISPLAY   = ft.TextStyle(size=32, weight=ft.FontWeight.W_700, color=Colors.TEXT_PRIMARY)
+    HEADING_1 = ft.TextStyle(size=24, weight=ft.FontWeight.W_600, color=Colors.TEXT_PRIMARY)
+    HEADING_2 = ft.TextStyle(size=18, weight=ft.FontWeight.W_600, color=Colors.TEXT_PRIMARY)
+    HEADING_3 = ft.TextStyle(size=14, weight=ft.FontWeight.W_600, color=Colors.TEXT_SECONDARY, letter_spacing=1.2)
+    BODY      = ft.TextStyle(size=14, weight=ft.FontWeight.NORMAL, color=Colors.TEXT_PRIMARY)
+    CAPTION   = ft.TextStyle(size=12, weight=ft.FontWeight.NORMAL, color=Colors.TEXT_SECONDARY)
+    METRIC    = ft.TextStyle(size=28, weight=ft.FontWeight.W_700, color=Colors.TEXT_PRIMARY)
+    CODE      = ft.TextStyle(size=13, font_family="monospace", color=Colors.DATA)
+
+
+class Spacing:
+    """Versioned spacing and sizing tokens for the DEx design system."""
+
+    XS  = 4
+    SM  = 8
+    MD  = 16
+    LG  = 24
+    XL  = 32
+    XXL = 48
+
+    SIDEBAR_WIDTH        = 240
+    HEADER_HEIGHT        = 60
+    CARD_BORDER_RADIUS   = 12
+    BUTTON_BORDER_RADIUS = 8
+    INPUT_BORDER_RADIUS  = 10
+    PANEL_BORDER_RADIUS  = 16
+    CHIP_BORDER_RADIUS   = 999
+
+
+def _build_default_theme() -> ft.Theme:
+    return ft.Theme(
+        color_scheme_seed=Colors.ACCENT,
+        color_scheme=ft.ColorScheme(
+            primary=Colors.ACCENT,
+            on_primary=Colors.TEXT_PRIMARY,
+            secondary=Colors.DATA,
+            on_secondary=Colors.ACCENT_ON,
+            surface=Colors.BG_SURFACE,
+            on_surface=Colors.TEXT_PRIMARY,
+            surface_container_lowest=Colors.BG_DEEP,
+            surface_container=Colors.BG_SURFACE,
+            surface_container_high=Colors.BG_ELEVATED,
+            error=Colors.DANGER,
+            on_error=Colors.TEXT_PRIMARY,
+        ),
+        text_theme=ft.TextTheme(
+            display_large=Typography.DISPLAY,
+            headline_medium=Typography.HEADING_1,
+            title_medium=Typography.HEADING_2,
+            body_medium=Typography.BODY,
+            label_small=Typography.CAPTION,
+        ),
+    )
+
+
+def build_theme() -> ft.Theme:
+    """Build the versioned Flet theme from DEx design tokens."""
+    return _build_default_theme()
+
+
+def build_theme_from_color_theme(theme: DEx_ColorTheme) -> ft.Theme:
+    """Build a Flet theme from a DEx color preset."""
+    return ft.Theme(
+        color_scheme_seed=theme.accent_primary,
+        color_scheme=ft.ColorScheme(
+            primary=theme.accent_primary,
+            on_primary=theme.accent_on,
+            secondary=theme.accent_primary,
+            on_secondary=theme.accent_on,
+            surface=theme.surface,
+            on_surface=theme.text_primary,
+            surface_container_lowest=theme.bg_primary,
+            surface_container=theme.surface,
+            surface_container_high=theme.surface_elevated,
+            error=Colors.DANGER,
+            on_error=Colors.TEXT_PRIMARY,
+        ),
+        text_theme=ft.TextTheme(
+            display_large=Typography.DISPLAY,
+            headline_medium=Typography.HEADING_1,
+            title_medium=Typography.HEADING_2,
+            body_medium=Typography.BODY,
+            label_small=Typography.CAPTION,
+        ),
+    )

components/theme/__init__.py

@@ -0,0 +1,4 @@
+"""Theme helpers for the DEx Framework."""
+
+from components.theme.DEx_Theme import Colors, Spacing, build_theme, build_theme_from_color_theme
+from components.theme.DEx_ColorThemes import COLOR_THEMES, DEx_ColorTheme, build_color_theme, get_color_theme

components/versioning.py

@@ -0,0 +1,103 @@
+"""Version helpers for DEx library, components, and release branches."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+
+
+VERSION_PATTERN = re.compile(r"^(?P<version>\d{1,2})\.(?P<release>\d{1,2})\.(?P<bugfix>\d{1,2})$")
+MAX_VERSION_SEGMENT = 99
+SEGMENT_ALIASES = {
+    "version": "version",
+    "vv": "version",
+    "major": "version",
+    "release": "release",
+    "rr": "release",
+    "minor": "release",
+    "bugfix": "bugfix",
+    "bug": "bugfix",
+    "bb": "bugfix",
+    "patch": "bugfix",
+}
+
+
+@dataclass(frozen=True)
+class ComponentMeta:
+    """Catalog metadata for a versioned DEx component."""
+
+    name: str
+    group: str
+    version: str
+    description: str
+
+    def __post_init__(self) -> None:
+        validate_version(self.version)
+
+
+def validate_version(version: str) -> str:
+    """Validate a DEx version in vv.rr.bb format."""
+    match = VERSION_PATTERN.match(version)
+    if not match:
+        raise ValueError("DEx version must use the vv.rr.bb format.")
+
+    segments = [int(value) for value in match.groups()]
+    if any(segment > MAX_VERSION_SEGMENT for segment in segments):
+        raise ValueError("DEx version segments cannot exceed 99.")
+
+    return version
+
+
+def validate_branch_version(branch_name: str) -> str:
+    """Validate a release branch name using the same vv.rr.bb version format."""
+    return validate_version(branch_name)
+
+
+def bump_version(version: str, segment: str = "patch") -> str:
+    """Increment one DEx version segment.
+
+    DEx library, component, and release branch versions use vv.rr.bb:
+    - vv/version: large visual, API, or usage changes.
+    - rr/release: small scoped changes.
+    - bb/bugfix: bug corrections.
+
+    Segments go from 0 to 99. When rr or bb reaches 99 and is incremented,
+    the previous segment is incremented and the current segment returns to 0.
+    """
+    validate_version(version)
+    normalized_segment = SEGMENT_ALIASES.get(segment)
+    if normalized_segment is None:
+        raise ValueError("segment must be 'version', 'release', or 'bugfix'.")
+
+    vv, rr, bb = [int(value) for value in version.split(".")]
+    if normalized_segment == "version":
+        vv = _increment_root_segment(vv)
+        rr = 0
+        bb = 0
+    elif normalized_segment == "release":
+        vv, rr = _increment_with_carry(vv, rr)
+        bb = 0
+    elif normalized_segment == "bugfix":
+        vv, rr, bb = _increment_bugfix(vv, rr, bb)
+    else:
+        raise ValueError("segment must be 'version', 'release', or 'bugfix'.")
+    return f"{vv}.{rr}.{bb}"
+
+
+def _increment_root_segment(value: int) -> int:
+    if value >= MAX_VERSION_SEGMENT:
+        raise ValueError("DEx version cannot exceed 99.99.99.")
+    return value + 1
+
+
+def _increment_with_carry(previous: int, current: int) -> tuple[int, int]:
+    if current >= MAX_VERSION_SEGMENT:
+        return _increment_root_segment(previous), 0
+    return previous, current + 1
+
+
+def _increment_bugfix(vv: int, rr: int, bb: int) -> tuple[int, int, int]:
+    if bb >= MAX_VERSION_SEGMENT:
+        vv, rr = _increment_with_carry(vv, rr)
+        return vv, rr, 0
+    return vv, rr, bb + 1