Metadata-Version: 2.4
Name: dex-framework
Version: 0.1.1
Summary: DEx Framework — sistema de componentes reutilizáveis para apps SaaS construído com Python e Flet
Author-email: Almir Duarte <almir.jg@gmail.com>
License-Expression: MIT
Project-URL: Repository, https://github.com/almir-jg/dex-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"

# DEx Framework v4

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.
