SaaS-FrameWork 0.1.2__tar.gz → 0.1.3__tar.gz

{saas_framework-0.1.2 → saas_framework-0.1.3}/MANIFEST.in

@@ -10,7 +10,7 @@ prune build
 prune catalog
 prune *.egg-info
 prune dist
-prune docs
+prune Diretrizes
 prune tests
 prune use_cases
 exclude files.zip

{saas_framework-0.1.2 → saas_framework-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SaaS-FrameWork
-Version: 0.1.2
+Version: 0.1.3
 Summary: SaaS-FrameWork - sistema de componentes reutilizaveis para apps SaaS construido com Python e Flet
 Author-email: Almir Duarte <almir.jg@gmail.com>
 License-Expression: MIT
@@ -13,6 +13,8 @@ Classifier: Topic :: Software Development :: User Interfaces
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 Requires-Dist: flet==0.84.0
+Provides-Extra: web
+Requires-Dist: flet-web==0.84.0; extra == "web"
 Provides-Extra: dev
 Requires-Dist: flet==0.84.0; extra == "dev"
 Requires-Dist: pytest<10,>=9.1; extra == "dev"
@@ -86,7 +88,7 @@ The following folders are repository assets and are intentionally excluded from
 
 - `catalog/`: local visual catalog and inspection tool.
 - `use_cases/`: executable examples for development and documentation.
-- `docs/`: component documentation and generated structure images.
+- `Diretrizes/`: project guidelines — prompts, design/component documentation, management artifacts, and QA evidence.
 - `_base/`: preserved reference material.
 
 This separation is enforced in `pyproject.toml` through `tool.setuptools.packages.find`.
@@ -98,8 +100,8 @@ Adding a public component requires all of the following:
 - entry in `components/metadata.py`
 - public export in `components/__init__.py`
 - use case `use_cases/UC_<Name>_01.py`
-- documentation `docs/components/Documentação/DEx_<Name>.md`
-- four structure images in `docs/components/images/`
+- documentation `Diretrizes/design/components/Documentação/DEx_<Name>.md`
+- four structure images in `Diretrizes/design/components/images/`
 
 The repository governance tests fail when this contract is broken.
 
@@ -126,8 +128,14 @@ SaaS-Framework/
 |   |-- UC_TreeView_01.py
 |   `-- UC_ColorThemes_01.py
 |-- catalog/
-|   `-- main.py
-|-- docs/
+|   `-- catalog.py
+|-- Diretrizes/
+|   |-- Dados/                     data artifacts (DDL, DML, scripts)
+|   |-- Prompt/                    prompt files
+|   |-- design/                    design references and component docs/images
+|   |   `-- components/
+|   |-- gestao/                    roadmap, policies, and management reports
+|   `-- qa/                        QA evidence
 |-- AGENTS.md
 |-- pyproject.toml
 `-- README.md
@@ -153,14 +161,14 @@ Run the catalog as desktop app:
 
 ```cmd
 call C:\Python\venv\.venv_313_FW\Scripts\activate.bat
-flet run catalog/main.py
+flet run catalog/catalog.py
 ```
 
 Run as web catalog only when browser validation is required:
 
 ```cmd
 call C:\Python\venv\.venv_313_FW\Scripts\activate.bat
-flet run --web --port 8550 catalog/main.py
+flet run --web --port 8550 catalog/catalog.py
 ```
 
 Run a use case:
@@ -219,12 +227,12 @@ The script builds the package, checks the artifacts, and uploads to TestPyPI or
 With the documented Flet environment:
 
 ```cmd
-C:\Python\venv\.venv_313_FW\Scripts\python.exe -c "import catalog.main as c; print(c.PROJECT_VERSION)"
+C:\Python\venv\.venv_313_FW\Scripts\python.exe -c "import catalog.constants as c; print(c.PROJECT_VERSION)"
 ```
 
 ## Catalog
 
-The catalog entry point is `catalog/main.py`.
+The catalog entry point is `catalog/catalog.py`.
 
 It follows the project window structure:
 

{saas_framework-0.1.2 → saas_framework-0.1.3}/README.md

@@ -63,7 +63,7 @@ The following folders are repository assets and are intentionally excluded from
 
 - `catalog/`: local visual catalog and inspection tool.
 - `use_cases/`: executable examples for development and documentation.
-- `docs/`: component documentation and generated structure images.
+- `Diretrizes/`: project guidelines — prompts, design/component documentation, management artifacts, and QA evidence.
 - `_base/`: preserved reference material.
 
 This separation is enforced in `pyproject.toml` through `tool.setuptools.packages.find`.
@@ -75,8 +75,8 @@ Adding a public component requires all of the following:
 - entry in `components/metadata.py`
 - public export in `components/__init__.py`
 - use case `use_cases/UC_<Name>_01.py`
-- documentation `docs/components/Documentação/DEx_<Name>.md`
-- four structure images in `docs/components/images/`
+- documentation `Diretrizes/design/components/Documentação/DEx_<Name>.md`
+- four structure images in `Diretrizes/design/components/images/`
 
 The repository governance tests fail when this contract is broken.
 
@@ -103,8 +103,14 @@ SaaS-Framework/
 |   |-- UC_TreeView_01.py
 |   `-- UC_ColorThemes_01.py
 |-- catalog/
-|   `-- main.py
-|-- docs/
+|   `-- catalog.py
+|-- Diretrizes/
+|   |-- Dados/                     data artifacts (DDL, DML, scripts)
+|   |-- Prompt/                    prompt files
+|   |-- design/                    design references and component docs/images
+|   |   `-- components/
+|   |-- gestao/                    roadmap, policies, and management reports
+|   `-- qa/                        QA evidence
 |-- AGENTS.md
 |-- pyproject.toml
 `-- README.md
@@ -130,14 +136,14 @@ Run the catalog as desktop app:
 
 ```cmd
 call C:\Python\venv\.venv_313_FW\Scripts\activate.bat
-flet run catalog/main.py
+flet run catalog/catalog.py
 ```
 
 Run as web catalog only when browser validation is required:
 
 ```cmd
 call C:\Python\venv\.venv_313_FW\Scripts\activate.bat
-flet run --web --port 8550 catalog/main.py
+flet run --web --port 8550 catalog/catalog.py
 ```
 
 Run a use case:
@@ -196,12 +202,12 @@ The script builds the package, checks the artifacts, and uploads to TestPyPI or
 With the documented Flet environment:
 
 ```cmd
-C:\Python\venv\.venv_313_FW\Scripts\python.exe -c "import catalog.main as c; print(c.PROJECT_VERSION)"
+C:\Python\venv\.venv_313_FW\Scripts\python.exe -c "import catalog.constants as c; print(c.PROJECT_VERSION)"
 ```
 
 ## Catalog
 
-The catalog entry point is `catalog/main.py`.
+The catalog entry point is `catalog/catalog.py`.
 
 It follows the project window structure:
 

{saas_framework-0.1.2 → saas_framework-0.1.3}/components/data/DEx_DataTable.py

@@ -1,7 +1,7 @@
 import flet as ft
 from components.theme.DEx_Theme import Colors, Spacing
 
-COMPONENT_VERSION = "0.0.1"
+COMPONENT_VERSION = "0.1.0"
 
 
 def _state_placeholder(state: str, empty_message: str, error_message: str) -> ft.Control:
@@ -44,10 +44,26 @@ def DEx_DataTable(
     state: str | None = None,
     empty_message: str = "Nenhum registro encontrado.",
     error_message: str = "Erro ao carregar os dados.",
+    row_payloads: list | None = None,
 ) -> ft.Control:
-    """Create the versioned data table with DEx headers, borders, and rows."""
+    """Create the versioned data table with DEx headers, borders, and rows.
+
+    row_payloads (BL13 do AutoFlow): um payload por linha; quando presente,
+    on_row_click recebe (evento, payload) — os produtos deixavam de religar
+    o clique linha a linha sobre o ft.DataTable retornado. Sem payloads, o
+    comportamento antigo (on_row_click(evento)) e preservado.
+    """
     if state in ("loading", "empty", "error"):
         return _state_placeholder(state, empty_message, error_message)
+
+    def _handler(indice: int):
+        if on_row_click is None:
+            return None
+        if row_payloads is None:
+            return on_row_click
+        payload = row_payloads[indice] if indice < len(row_payloads) else None
+        return lambda e, p=payload: on_row_click(e, p)
+
     return ft.DataTable(
         columns=[
             ft.DataColumn(
@@ -67,9 +83,9 @@ def DEx_DataTable(
                     ft.DataCell(ft.Text(cell, size=13, color=Colors.TEXT_PRIMARY))
                     for cell in row
                 ],
-                on_select_change=on_row_click,
+                on_select_change=_handler(i),
             )
-            for row in rows
+            for i, row in enumerate(rows)
         ],
         border=ft.Border.all(1, Colors.BORDER),
         border_radius=Spacing.CARD_BORDER_RADIUS,

{saas_framework-0.1.2 → saas_framework-0.1.3}/components/feedback/DEx_AlertDialog.py

@@ -1,7 +1,7 @@
 import flet as ft
 from components.theme.DEx_Theme import Colors, Spacing
 
-COMPONENT_VERSION = "0.0.1"
+COMPONENT_VERSION = "0.1.0"
 
 
 def DEx_AlertDialog(
@@ -9,8 +9,13 @@ def DEx_AlertDialog(
     content: ft.Control | str | None = None,
     actions: list[ft.Control] | None = None,
     on_dismiss=None,
+    modal: bool = False,
 ) -> ft.AlertDialog:
-    """Modal dialog for confirmations, alerts and short forms."""
+    """Modal dialog for confirmations, alerts and short forms.
+
+    modal (BL13 do AutoFlow): bloqueia o fechamento por clique fora — os
+    produtos ajustavam o atributo publico pos-construcao.
+    """
     body = (
         ft.Text(content, size=13, color=Colors.TEXT_SECONDARY)
         if isinstance(content, str)
@@ -21,6 +26,7 @@ def DEx_AlertDialog(
         content=body,
         actions=actions or [],
         on_dismiss=on_dismiss,
+        modal=modal,
         bgcolor=Colors.BG_ELEVATED,
         shape=ft.RoundedRectangleBorder(radius=Spacing.CARD_BORDER_RADIUS),
     )

saas_framework-0.1.3/components/inputs/DEx_Dropdown.py

@@ -0,0 +1,41 @@
+import flet as ft
+from components.theme.DEx_Theme import Colors, Spacing
+
+COMPONENT_VERSION = "0.1.0"
+
+
+def _option(item) -> ft.dropdown.Option:
+    """Aceita opcao como str (key=text) ou par (key, text) — BL13."""
+    if isinstance(item, (tuple, list)) and len(item) == 2:
+        key, text = item
+        return ft.dropdown.Option(key=str(key), text=str(text))
+    return ft.dropdown.Option(str(item))
+
+
+def DEx_Dropdown(
+    label: str,
+    options: list,
+    on_change=None,
+    value: str | None = None,
+    width: int | None = None,
+) -> ft.Dropdown:
+    """Create the versioned styled dropdown selector.
+
+    options aceita list[str] (compat) ou list[(key, text)]; value/width
+    (BL13 do AutoFlow) evitam o ajuste pos-construcao nos produtos.
+    """
+    dd = ft.Dropdown(
+        label=label,
+        options=[_option(o) for o in options],
+        value=value,
+        width=width,
+        border_color=Colors.BORDER,
+        focused_border_color=Colors.ACCENT,
+        label_style=ft.TextStyle(color=Colors.TEXT_SECONDARY, size=12),
+        text_style=ft.TextStyle(color=Colors.TEXT_PRIMARY, size=14),
+        bgcolor=Colors.BG_SURFACE,
+        border_radius=Spacing.BUTTON_BORDER_RADIUS,
+    )
+    if on_change is not None:
+        dd.on_change = on_change
+    return dd

{saas_framework-0.1.2 → saas_framework-0.1.3}/components/inputs/DEx_TextField.py

@@ -1,7 +1,7 @@
 import flet as ft
 from components.theme.DEx_Theme import Colors, Spacing
 
-COMPONENT_VERSION = "0.0.1"
+COMPONENT_VERSION = "0.1.0"
 
 
 def DEx_TextField(
@@ -10,8 +10,18 @@ def DEx_TextField(
     icon=None,
     password: bool = False,
     on_change=None,
+    value: str = "",
+    width: int | None = None,
+    visible: bool = True,
+    multiline: bool = False,
+    min_lines: int | None = None,
+    max_lines: int | None = None,
 ) -> ft.TextField:
-    """Create the versioned DEx text field for forms and filters."""
+    """Create the versioned DEx text field for forms and filters.
+
+    value/width/visible/multiline (BL13 do AutoFlow): os produtos ajustavam
+    esses atributos publicos pos-construcao; agora a fabrica os expoe.
+    """
     return ft.TextField(
         label=label,
         hint_text=hint,
@@ -19,6 +29,12 @@ def DEx_TextField(
         password=password,
         can_reveal_password=password,
         on_change=on_change,
+        value=value,
+        width=width,
+        visible=visible,
+        multiline=multiline,
+        min_lines=min_lines,
+        max_lines=max_lines,
         border_color=Colors.BORDER,
         focused_border_color=Colors.ACCENT,
         label_style=ft.TextStyle(color=Colors.TEXT_SECONDARY, size=12),

saas_framework-0.1.3/components/layout/DEx_AppShell.py

@@ -0,0 +1,137 @@
+import flet as ft
+from components.theme.DEx_Theme import Colors, Spacing
+from components.layout.DEx_Sidebar import DEx_Sidebar
+from components.layout.DEx_Header import DEx_Header
+
+COMPONENT_VERSION = "0.1.0"
+
+
+class DEx_AppShell(ft.Row):
+    """Versioned application shell with sidebar, header, and content host.
+
+    BL12 (demanda AutoFlow): o shell repassa a identidade e a navegacao do
+    produto para o DEx_Sidebar (nav_items, logo, secao, settings, usuario,
+    on_logout) e as opcoes do DEx_Header (busca/sino/ajuda). Defaults
+    reproduzem a vitrine do catalogo — retrocompativel.
+    """
+
+    def __init__(
+        self,
+        page: ft.Page,
+        title: str = "",
+        subtitle: str = "",
+        header_actions: list[ft.Control] | None = None,
+        nav_items: list[tuple] | None = None,
+        initial_route: str = "/dashboard",
+        logo_letter: str = "D",
+        logo_title: str = "DEx",
+        logo_subtitle: str = "Framework v4",
+        section_label: str = "NAVEGACAO",
+        settings_route: str | None = "/settings",
+        user_name: str | None = "Almir Duarte",
+        user_role: str | None = "Admin",
+        on_logout=None,
+        on_navigate=None,
+        show_search: bool = True,
+        on_search=None,
+        show_notifications: bool = True,
+        show_help: bool = True,
+    ):
+        self._page_ref = page
+        self.title = title
+        self.subtitle = subtitle
+        self.header_actions = header_actions or []
+        self.nav_items = nav_items
+        self.logo_letter = logo_letter
+        self.logo_title = logo_title
+        self.logo_subtitle = logo_subtitle
+        self.section_label = section_label
+        self.settings_route = settings_route
+        self.user_name = user_name
+        self.user_role = user_role
+        self.on_logout = on_logout
+        self.on_navigate_produto = on_navigate
+        self.show_search = show_search
+        self.on_search = on_search
+        self.show_notifications = show_notifications
+        self.show_help = show_help
+        self._content = ft.Container(expand=True)
+        self._route = initial_route
+
+        page.bgcolor = Colors.BG_DEEP
+        page.padding = 0
+        page.spacing = 0
+
+        super().__init__(
+            controls=self._build_controls(),
+            spacing=0,
+            expand=True,
+        )
+
+    def set_content(self, control: ft.Control, title: str = None, subtitle: str = None):
+        if title:
+            self.title = title
+        if subtitle:
+            self.subtitle = subtitle
+        self._content = ft.Container(
+            content=ft.Column(
+                [ft.Container(content=control, padding=ft.Padding.all(Spacing.LG))],
+                spacing=0,
+                expand=True,
+                horizontal_alignment=ft.CrossAxisAlignment.START,
+            ),
+            expand=True,
+            bgcolor=Colors.BG_DEEP,
+        )
+        self.controls = self._build_controls()
+        try:
+            self.update()
+        except RuntimeError:
+            pass
+
+    def _on_navigate(self, route: str):
+        self._route = route
+        if self.on_navigate_produto:
+            self.on_navigate_produto(route)
+        self.controls = self._build_controls()
+        self.update()
+
+    def _build_controls(self) -> list[ft.Control]:
+        sidebar = DEx_Sidebar(
+            current_route=self._route,
+            on_navigate=self._on_navigate,
+            nav_items=self.nav_items,
+            logo_letter=self.logo_letter,
+            logo_title=self.logo_title,
+            logo_subtitle=self.logo_subtitle,
+            section_label=self.section_label,
+            settings_route=self.settings_route,
+            user_name=self.user_name,
+            user_role=self.user_role,
+            on_logout=self.on_logout,
+        )
+        header = DEx_Header(
+            self.title,
+            self.subtitle,
+            actions=self.header_actions,
+            show_search=self.show_search,
+            on_search=self.on_search,
+            show_notifications=self.show_notifications,
+            show_help=self.show_help,
+        )
+
+        main_area = ft.Column(
+            [
+                ft.Row([header], spacing=0, expand=True),
+                ft.Container(
+                    content=self._content,
+                    expand=True,
+                    clip_behavior=ft.ClipBehavior.HARD_EDGE,
+                ),
+            ],
+            spacing=0,
+            expand=True,
+            alignment=ft.MainAxisAlignment.START,
+        )
+
+        return [sidebar, main_area]

saas_framework-0.1.3/components/layout/DEx_Header.py

@@ -0,0 +1,80 @@
+import flet as ft
+from components.theme.DEx_Theme import Colors, Spacing
+
+COMPONENT_VERSION = "0.1.0"
+
+
+class DEx_Header(ft.Container):
+    """Versioned page header with title, subtitle, search, and actions.
+
+    BL12 (demanda AutoFlow): busca, sino e ajuda agora sao opcionais e a
+    busca aceita on_search (on_change) — defaults reproduzem a vitrine.
+    """
+
+    def __init__(
+        self,
+        title: str,
+        subtitle: str = "",
+        actions: list[ft.Control] | None = None,
+        show_search: bool = True,
+        on_search=None,
+        show_notifications: bool = True,
+        show_help: bool = True,
+    ):
+        self.title = title
+        self.subtitle = subtitle
+        self.actions = actions or []
+        self.show_search = show_search
+        self.on_search = on_search
+        self.show_notifications = show_notifications
+        self.show_help = show_help
+        super().__init__(
+            content=self._build_content(),
+            height=Spacing.HEADER_HEIGHT,
+            bgcolor=Colors.BG_DEEP,
+            border=ft.Border.only(bottom=ft.BorderSide(1, Colors.BORDER)),
+            padding=ft.Padding.symmetric(horizontal=Spacing.LG),
+        )
+
+    def _build_content(self) -> ft.Row:
+        title_block = ft.Column(
+            [
+                ft.Text(self.title, size=20, weight=ft.FontWeight.W_700, color=Colors.TEXT_PRIMARY),
+                ft.Text(self.subtitle, size=12, color=Colors.TEXT_SECONDARY) if self.subtitle else ft.Container(),
+            ],
+            spacing=2, tight=True,
+        )
+
+        partes: list[ft.Control] = [title_block, ft.Container(expand=True)]
+
+        if self.show_search:
+            partes.append(
+                ft.TextField(
+                    hint_text="Buscar...",
+                    prefix_icon=ft.Icons.SEARCH,
+                    on_change=self.on_search,
+                    border_color=Colors.BORDER,
+                    focused_border_color=Colors.ACCENT,
+                    text_style=ft.TextStyle(color=Colors.TEXT_PRIMARY, size=13),
+                    hint_style=ft.TextStyle(color=Colors.TEXT_MUTED, size=13),
+                    bgcolor=Colors.BG_ELEVATED,
+                    border_radius=8,
+                    height=40,
+                    content_padding=ft.Padding.symmetric(horizontal=12, vertical=8),
+                    width=280,
+                )
+            )
+
+        icones: list[ft.Control] = []
+        if self.show_notifications:
+            icones.append(
+                ft.IconButton(ft.Icons.NOTIFICATIONS_NONE_ROUNDED, icon_color=Colors.TEXT_SECONDARY, icon_size=20)
+            )
+        icones.extend(self.actions)
+        if self.show_help:
+            icones.append(
+                ft.IconButton(ft.Icons.HELP_OUTLINE_ROUNDED, icon_color=Colors.TEXT_SECONDARY, icon_size=20)
+            )
+        partes.append(ft.Row(icones, spacing=0))
+
+        return ft.Row(partes, vertical_alignment=ft.CrossAxisAlignment.CENTER)