SaaS-FrameWork 0.1.1__tar.gz

saas_framework-0.1.1/MANIFEST.in

@@ -0,0 +1,16 @@
+include README.md
+include pyproject.toml
+recursive-include components *.py
+recursive-exclude * __pycache__ *.py[cod]
+prune .github
+prune .pytest_cache
+prune .pytest_tmp
+prune _base
+prune build
+prune catalog
+prune *.egg-info
+prune dist
+prune docs
+prune tests
+prune use_cases
+exclude files.zip

saas_framework-0.1.1/PKG-INFO

@@ -0,0 +1,450 @@
+Metadata-Version: 2.4
+Name: SaaS-FrameWork
+Version: 0.1.1
+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
+Project-URL: Repository, https://github.com/DEx-SaaS/FrameWork
+Keywords: flet,saas,framework,ui,components,design-system
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: flet==0.84.0
+Provides-Extra: dev
+Requires-Dist: flet==0.84.0; extra == "dev"
+Requires-Dist: pytest<10,>=9.1; extra == "dev"
+Requires-Dist: build<2,>=1.3; extra == "dev"
+Requires-Dist: twine<7,>=6.2; extra == "dev"
+Provides-Extra: visual
+Requires-Dist: playwright<2,>=1.40; extra == "visual"
+
+# SaaS-FrameWork
+
+Python 3.13 + Flet design framework for reusable SaaS UI components.
+
+The project provides versioned UI components, isolated use cases, and a navigable component catalog.
+
+## Versioning
+
+Library, component, and release branch versions follow the same `vv.rr.bb` rule.
+
+The library version is declared in `pyproject.toml`:
+
+```toml
+[project]
+version = "0.1.1"
+```
+
+Use cases and the catalog header read this version through `components/project.py`. Do not duplicate the project version manually in UI files.
+
+Each public component exposes its own version:
+
+```python
+COMPONENT_VERSION = "0.0.1"
+```
+
+Release branches must use the same format as the branch name:
+
+```text
+0.1.1
+```
+
+Do not prefix release branch names with `v`, `release/`, or any other text.
+
+The accepted format is:
+
+```text
+vv.rr.bb
+0.0.0 through 99.99.99
+```
+
+Segment meaning:
+
+- `vv`: version. Increment for large changes that alter visual form, public API, or how the library/component is used.
+- `rr`: release. Increment for small scoped changes, such as a specific behavior or item adjustment.
+- `bb`: bug correction. Increment when a bug is fixed.
+
+Every library or component change must increment the relevant version. Each segment is incremented by one numeral. When `bb` reaches `99`, the next `bb` increment increments `rr` and resets `bb` to `0`. When `rr` reaches `99`, the next `rr` increment increments `vv` and resets `rr` to `0`.
+
+Version helpers live in `components/versioning.py`:
+
+- `validate_version(version)`
+- `validate_branch_version(branch_name)`
+- `bump_version(version, segment="bugfix")`
+- `ComponentMeta`
+
+Catalog metadata lives in `components/metadata.py` and is the source of truth for component name, group, version, and description.
+
+## Package Boundary
+
+The distributable Python library is the `components` package.
+
+The following folders are repository assets and are intentionally excluded from the wheel:
+
+- `catalog/`: local visual catalog and inspection tool.
+- `use_cases/`: executable examples for development and documentation.
+- `docs/`: component documentation and generated structure images.
+- `_base/`: preserved reference material.
+
+This separation is enforced in `pyproject.toml` through `tool.setuptools.packages.find`.
+
+Adding a public component requires all of the following:
+
+- source file under `components/**/DEx_<Name>.py`
+- `COMPONENT_VERSION` in the source file
+- 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/`
+
+The repository governance tests fail when this contract is broken.
+
+## Folder Structure
+
+```text
+DEx-FW_4/
+|-- _base/                         preserved original reference
+|-- components/
+|   |-- buttons/
+|   |-- cards/
+|   |-- data/
+|   |-- feedback/
+|   |-- inputs/
+|   |-- layout/
+|   |-- primitives/
+|   |-- theme/
+|   |-- metadata.py
+|   |-- project.py
+|   `-- versioning.py
+|-- use_cases/
+|   |-- _uc_template.py
+|   |-- UC_<Component>_<nn>.py
+|   |-- UC_TreeView_01.py
+|   `-- UC_ColorThemes_01.py
+|-- catalog/
+|   `-- main.py
+|-- docs/
+|-- AGENTS.md
+|-- pyproject.toml
+`-- README.md
+```
+
+## Naming Convention
+
+| Type | Pattern | Example |
+|---|---|---|
+| Component file | `DEx_<Name>.py` | `DEx_MetricCard.py` |
+| Component factory/class | `DEx_<Name>` | `DEx_MetricCard()` |
+| Use case | `UC_<Component>_<nn>.py` | `UC_MetricCard_01.py` |
+
+## Environment
+
+Documented local virtual environment:
+
+```cmd
+C:\Python\venv\.venv_313_FW
+```
+
+Run the catalog:
+
+```cmd
+call C:\Python\venv\.venv_313_FW\Scripts\activate.bat
+flet run catalog/main.py
+```
+
+Run as web catalog:
+
+```cmd
+call C:\Python\venv\.venv_313_FW\Scripts\activate.bat
+flet run --web --port 8550 catalog/main.py
+```
+
+Run a use case:
+
+```cmd
+call C:\Python\venv\.venv_313_FW\Scripts\activate.bat
+flet run use_cases/UC_MetricCard_01.py
+```
+
+## Validation
+
+Quick syntax validation:
+
+```cmd
+python -m compileall components use_cases catalog
+```
+
+Run the automated test suite:
+
+```cmd
+C:\Python\venv\.venv_313_FW\Scripts\python.exe -m pytest -q
+```
+
+Run optional visual screenshots:
+
+```powershell
+C:\Python\venv\.venv_313_FW\Scripts\python.exe -m playwright install chromium
+$env:DEX_RUN_VISUAL_TESTS="1"
+C:\Python\venv\.venv_313_FW\Scripts\python.exe -m pytest tests/test_visual_screenshots.py -q
+```
+
+Build and validate package metadata:
+
+```cmd
+C:\Python\venv\.venv_313_FW\Scripts\python.exe -m build
+C:\Python\venv\.venv_313_FW\Scripts\python.exe -m twine check dist/*
+```
+
+Publish the package:
+
+```powershell
+.\tools\publish_package.ps1 --test
+.\tools\publish_package.ps1 --prod
+.\tools\publish_package.ps1 --both
+.\tools\publish_package.ps1
+```
+
+Without flags, the script asks:
+
+1. teste
+2. prod
+3. ambos
+
+The script builds the package, checks the artifacts, and uploads to TestPyPI or PyPI based on the chosen destination.
+
+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)"
+```
+
+## Catalog
+
+The catalog entry point is `catalog/main.py`.
+
+It follows the project window structure:
+
+- header with project name, project version, and current branch
+- left menu with component groups
+- group context area with name and description
+- component cards showing name, group, and component version
+
+The catalog uses `components/metadata.py`; adding a component without adding metadata means it will not appear in the catalog.
+
+## Design System
+
+Main design tokens live in `components/theme/DEx_Theme.py`.
+
+| Token | Hex | Use |
+|---|---:|---|
+| `ACCENT` | `#6C63FF` | Primary actions and active navigation |
+| `DATA` | `#00E5C3` | Data highlights and metric accents |
+| `BG_DEEP` | `#0D0F14` | Root background |
+| `BG_SURFACE` | `#151820` | Cards and sidebar surfaces |
+| `BG_ELEVATED` | `#1C2030` | Hover states, inputs, elevated surfaces |
+| `BORDER` | `#1E2230` | Borders and dividers |
+| `SUCCESS` | `#22C55E` | Positive status |
+| `DANGER` | `#EF4444` | Error or negative status |
+| `WARNING` | `#F59E0B` | Warning status |
+
+Signature elements:
+
+- numbered cyan eyebrows through `DEx_SectionEyebrow`
+- 3px violet active indicator in `DEx_NavItem`
+
+## Color Themes
+
+Accessible 60-30-10 color themes live in `components/theme/DEx_ColorThemes.py`.
+
+Each theme defines:
+
+- `background`: 60% dominant color for windows, frames, and base containers
+- `text`: 30% foreground color for typography, borders, cards, and tables
+- `accent`: 10% highlight color for primary CTAs, badges, critical links, progress, and chart highlights
+- `contrast_ratio`: documented text/background contrast
+- `accessibility`: WCAG target such as `AAA` or `AA`
+
+Available themes:
+
+| Theme | Background | Text | Accent | Contrast | Status |
+|---|---:|---:|---:|---:|---|
+| Minimalismo Corporativo | `#FFFFFF` | `#000000` | `#0071E3` | `21:1` | AAA |
+| Dark Mode de Alta Performance | `#111111` | `#FFFFFF` | `#FF6A13` | `18.88:1` | AAA |
+| Confianca e Fintech | `#141432` | `#F4F5F7` | `#0079C1` | `16.37:1` | AAA |
+| Organico e Bem-Estar | `#006241` | `#FFFFFF` | `#00A86B` | `7.44:1` | AAA |
+| Alimentacao e Food Delivery | `#FAFAFA` | `#222222` | `#EA1D2C` | `15.24:1` | AAA |
+| Area Automotiva | `#1E2229` | `#F3F4F6` | `#FFB800` / `#FF5500` | `14.50:1` | AAA |
+| Tradicao e Robustez | `#F4F6F9` | `#003399` | `#003399` / `#FFFF00` | `10.03:1` | AAA |
+| Modernidade Digital | `#FFFFFF` | `#820AD1` | `#820AD1` | `7.21:1` | AAA |
+| Solidez e Dinamismo | `#FAFAFA` | `#0038A8` | `#FF6200` | `9.44:1` | AAA |
+| Presenca Global e Energia | `#FFFFFF` | `#1C1C1C` | `#EC0000` | `17.04:1` | AAA |
+
+Use:
+
+```python
+from components.theme.DEx_ColorThemes import get_color_theme
+
+theme = get_color_theme("food_delivery")
+page.bgcolor = theme.bg_primary
+button.bgcolor = theme.accent_primary
+```
+
+Export CSS-style variables:
+
+```python
+theme.css_variables()
+```
+
+## Use Case Theme Switcher
+
+The shared use case template in `use_cases/_uc_template.py` adds a palette button to the header.
+
+Each click cycles through the current `DEx_ColorThemes` presets:
+
+```text
+Minimalismo Corporativo -> Dark Mode de Alta Performance -> Confianca e Fintech -> Organico e Bem-Estar -> Alimentacao e Food Delivery -> Area Automotiva -> Tradicao e Robustez -> Modernidade Digital -> Solidez e Dinamismo -> Presenca Global e Energia
+```
+
+The switcher applies the selected 60-30-10 theme to the page and retints mounted controls that use DEx token colors.
+
+## Components
+
+Total registered components: **67**.
+
+### theme
+
+Cores, espaçamento, tipografia e construção de tema compartilhados.
+
+| Component | Version | Description |
+|---|---:|---|
+| `DEx_Theme` | `0.0.1` | Tokens de design e construtor de tema Flet. |
+| `DEx_ColorThemes` | `0.0.1` | Temas de cor acessíveis 60-30-10 para aplicações DEx. |
+
+### primitives
+
+Elementos visuais atômicos para composição de controles maiores.
+
+| Component | Version | Description |
+|---|---:|---|
+| `DEx_Badge` | `0.0.1` | Rótulo compacto de status e categoria. |
+| `DEx_Divider` | `0.0.1` | Separador horizontal sutil. |
+| `DEx_SectionEyebrow` | `0.0.1` | Marcador de seção numerado em ciano. |
+| `DEx_StatusDot` | `0.0.1` | Indicador de estado colorido em miniatura. |
+| `DEx_Avatar` | `0.0.1` | Avatar circular com iniciais coloridas e grupo com overflow. |
+| `DEx_Image` | `0.0.1` | Imagem com bordas arredondadas e placeholder de estado vazio. |
+| `DEx_Icon` | `0.0.1` | Ícone com tokens de tamanho SM/MD/LG/XL e badge overlay. |
+| `DEx_Markdown` | `0.0.1` | Renderizador Markdown com suporte a tabelas e código. |
+
+### cards
+
+Superfícies reutilizáveis para métricas, entidades e conteúdo agrupado.
+
+| Component | Version | Description |
+|---|---:|---|
+| `DEx_Card` | `0.0.1` | Superfície base para conteúdo agrupado. |
+| `DEx_MetricCard` | `0.0.1` | Card de KPI com valor, ícone e variação. |
+| `DEx_ContactCard` | `0.0.1` | Card de entidade com iniciais, metadados e rodapé. |
+
+### buttons
+
+Controles de ação: primário, secundário e somente ícone.
+
+| Component | Version | Description |
+|---|---:|---|
+| `DEx_BtnPrimary` | `0.1.0` | Botão de ação primária. |
+| `DEx_BtnGhost` | `0.0.1` | Botão de ação secundária com borda. |
+| `DEx_BtnIcon` | `0.0.1` | Botão de ação somente com ícone. |
+| `DEx_BtnFilled` | `0.0.1` | Botão preenchido de alta ênfase. |
+| `DEx_BtnTonal` | `0.0.1` | Botão tonal de ênfase secundária. |
+| `DEx_BtnText` | `0.0.1` | Botão textual de menor ênfase. |
+| `DEx_BtnFAB` | `0.0.1` | Botão de ação flutuante para criação de registros. |
+| `DEx_BtnSegmented` | `0.0.1` | Alternador de múltiplas opções mutuamente exclusivas. |
+| `DEx_MenuBar` | `0.0.1` | Barra de menus horizontal com submenus. |
+| `DEx_PopupMenu` | `0.0.1` | Menu de contexto acionado por ícone. |
+
+### inputs
+
+Controles de formulário e busca estilizados para o sistema visual DEx.
+
+| Component | Version | Description |
+|---|---:|---|
+| `DEx_TextField` | `0.0.1` | Campo de texto estilizado. |
+| `DEx_SearchField` | `0.0.1` | Campo de busca com ícone de lupa. |
+| `DEx_Dropdown` | `0.0.1` | Seletor de opções estilizado. |
+| `DEx_Checkbox` | `0.0.1` | Caixa de seleção booleana ou tristate estilizada. |
+| `DEx_Switch` | `0.0.1` | Toggle switch para configurações binárias. |
+| `DEx_Radio` | `0.0.1` | Opção de rádio e grupo para seleção mutuamente exclusiva. |
+| `DEx_Slider` | `0.0.1` | Slider de valor único e de intervalo para entrada numérica. |
+| `DEx_Chip` | `0.0.1` | Chip selecionável para filtros e multi-seleção. |
+| `DEx_AutoComplete` | `0.0.1` | Campo de texto com dropdown de sugestões predefinidas. |
+| `DEx_SearchBar` | `0.0.1` | Barra de pesquisa expansível com overlay de sugestões. |
+| `DEx_DateField` | `0.0.1` | Campo de data estilizado com ícone e range opcional. |
+| `DEx_TimeField` | `0.0.1` | Campo de horário com máscara hh:mm e range opcional. |
+| `DEx_FilePicker` | `0.1.0` | Seletor de arquivo nativo com filtro de extensões. |
+
+### data
+
+Controles para tabelas, pipelines e visualizações de dados operacionais.
+
+| Component | Version | Description |
+|---|---:|---|
+| `DEx_DataTable` | `0.0.1` | Tabela de dados estilizada. |
+| `DEx_PipelineColumn` | `0.0.1` | Coluna de pipeline/Kanban por etapa. |
+| `DEx_TreeView` | `0.0.1` | Árvore hierárquica com busca, expansão e seleção. |
+| `DEx_ListTile` | `0.0.1` | Item de lista com título, subtítulo, leading e trailing. |
+| `DEx_ExpansionTile` | `0.0.1` | Tile expansível que revela controles filhos. |
+| `DEx_ExpansionPanel` | `0.0.1` | Painel acordeão agrupado em ExpansionPanelList. |
+| `DEx_ListView` | `0.0.1` | Lista vertical com scroll e divisores automáticos. |
+| `DEx_GridView` | `0.0.1` | Grade responsiva para cards e itens repetidos. |
+
+### layout
+
+Frame da aplicação, navegação e controles de estrutura de página.
+
+| Component | Version | Description |
+|---|---:|---|
+| `DEx_AppShell` | `0.0.1` | Shell da aplicação com sidebar e área de conteúdo. |
+| `DEx_Sidebar` | `0.0.1` | Sidebar de navegação vertical. |
+| `DEx_Header` | `0.0.1` | Cabeçalho de página com busca e ações. |
+| `DEx_NavItem` | `0.1.0` | Item de navegação com acento de estado ativo. |
+| `DEx_Tabs` | `0.0.1` | Barra de abas horizontal com indicador em ACCENT. |
+| `DEx_NavigationBar` | `0.0.1` | Barra de navegação inferior estilo mobile. |
+| `DEx_NavigationRail` | `0.0.1` | Rail de navegação vertical compacto para desktop. |
+| `DEx_NavigationDrawer` | `0.0.1` | Drawer lateral de navegação secundária. |
+| `DEx_AppBar` | `0.0.1` | Barra superior de aplicação com título e ações. |
+| `DEx_BottomAppBar` | `0.0.1` | Barra inferior com ações e suporte a FAB. |
+| `DEx_Stack` | `0.0.1` | Stack com posicionamento absoluto, overlay e badge. |
+| `DEx_ResponsiveRow` | `0.0.1` | Grade responsiva de 12 colunas com DEx_Col. |
+| `DEx_GestureDetector` | `0.0.1` | Detector de tap, double-tap, long-press, hover e pan. |
+| `DEx_Draggable` | `0.0.1` | Drag-and-drop: Draggable + DragTarget por grupo. |
+| `DEx_AnimatedSwitcher` | `0.0.1` | Troca de conteúdo animada (FADE/SCALE/ROTATION). |
+
+### feedback
+
+Controles de feedback do usuário para estados transitórios.
+
+| Component | Version | Description |
+|---|---:|---|
+| `DEx_Notify` | `0.0.1` | Notificação temporária tipo snackbar. |
+| `DEx_AlertDialog` | `0.0.1` | Diálogo modal para confirmações e alertas. |
+| `DEx_BottomSheet` | `0.0.1` | Painel deslizante que emerge da borda inferior. |
+| `DEx_Banner` | `0.0.1` | Banner persistente abaixo do AppBar para avisos. |
+| `DEx_Tooltip` | `0.0.1` | Dica contextual ao hover ou long-press. |
+| `DEx_ProgressBar` | `0.0.1` | Barra de progresso horizontal determinada ou indeterminada. |
+| `DEx_ProgressRing` | `0.0.1` | Indicador circular de progresso com label opcional. |
+| `DEx_Shimmer` | `0.0.1` | Esqueletos de carregamento: ShimmerCard, ShimmerList. |
+
+## Adding a Component
+
+1. Create the component under the correct `components/<group>/` folder.
+2. Add `COMPONENT_VERSION = "0.0.1"` for a new component.
+3. Add a docstring to the public component factory or class.
+4. Add metadata to `components/metadata.py`.
+5. Create an isolated use case in `use_cases/`.
+6. Run `python -m compileall components use_cases catalog`.
+
+Skipping metadata is not harmless: the component will exist in code but disappear from the catalog.