Metadata-Version: 2.4
Name: sat-ds
Version: 0.0.4
Summary: Biblioteca de componentes reutilizáveis
Author: lpozza
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: streamlit>=1.35.0
Dynamic: license-file

# SAT Design System — `sat-ds`

> Biblioteca de componentes reutilizáveis para aplicações Streamlit embarcadas no sistema SAT via MainFrame.

---

## 🇧🇷 Português

### Sobre o projeto

O **SAT Design System** (`sat-ds`) é uma biblioteca de componentes Python construída sobre o [Streamlit](https://streamlit.io), criada para padronizar a interface visual das aplicações embarcadas no sistema **SAT** via MainFrame.

A biblioteca nasceu da necessidade de reutilizar componentes com identidade visual consistente em aplicações subsequentes que são embedadas dentro do sistema principal. Em vez de recriar estilos e lógica de UI em cada projeto, o `sat-ds` centraliza esses elementos em um único pacote instalável via `pip`.

Cada componente foi cuidadosamente redesenhado seguindo as diretrizes do Design System exclusivo do SAT, garantindo coesão visual e experiência de uso uniforme entre todas as aplicações da plataforma.

---

### Instalação

#### Requisitos

- Python >= 3.9
- Streamlit instalado no projeto consumidor

#### Via pip (repositório interno / local)

```bash
pip install sat-ds
```

#### Via pip apontando para o repositório Git

```bash
pip install git+https://github.com/seu-org/sat-ds.git
```

#### Via arquivo local (durante desenvolvimento)

Clone o repositório e instale em modo editável:

```bash
git clone https://github.com/seu-org/sat-ds.git
cd sat-ds
pip install -e .
```

---

### Componentes disponíveis

| Componente | Função principal | Descrição |
|---|---|---|
| `button_ds` | `button_ds(title, bg_color, ...)` | Botão estilizado em formato pílula com ícone SVG opcional |
| `card_dist_ds` | `card_dist_ds(title, value, percent, ...)` | Card de distribuição com valores monetários e percentuais |
| `card_metric_ds` | `card_metric_ds(title, value, icon, ...)` | Card de métrica com suporte a delta, tooltip e variação de tamanho |
| `identification_field_ds` | `identification_field_ds(label, placeholder, ...)` | Campo de texto estilizado para entrada de identificadores |
| `info_bar_ds` | `info_bar_ds(text, bg_color, ...)` | Barra de informação/alerta com cor e borda customizáveis |
| `panel_ds` | `with panel_ds(key, ...)` | Container com borda estilizada, usado como gerenciador de contexto |
| `tabs_ds` | `tabs_ds(["Aba A", "Aba B"])` | Wrapper estilizado sobre `st.tabs()` |
| `accordeon_ds` | `with accordeon(label, expanded)` | Seção expansível estilizada sobre `st.expander()` |

---

### Uso básico

```python
from components import (
    button_ds,
    card_metric_ds,
    panel_ds,
    tabs_ds,
    accordeon_ds,
    info_bar_ds,
)

# Botão
if button_ds("Consultar", bg_color="#375C38", enabled_icon=False, icon="", key="btn_1"):
    st.write("Clicado!")

# Card de métrica
card_metric_ds(
    title="Total Apurado",
    value="R$ 1.250.000,00",
    icon="📊",
    enabled_icon=True,
    category_type="HIGH",
    size="md",
    key="metric_1",
)

# Panel (container com borda)
with panel_ds(key="painel_principal"):
    st.write("Conteúdo dentro do painel")

# Tabs
aba_a, aba_b = tabs_ds(["Resumo", "Detalhes"])
with aba_a:
    st.write("Conteúdo da aba Resumo")

# Accordeon
with accordeon(":material/bar_chart: Distribuição por Ano", expanded=False):
    st.write("Conteúdo expandível")

# Barra de informação
info_bar_ds("Dados referentes ao exercício fiscal vigente.")
```

---

### Estrutura do pacote

```
sat_ds/
├── myproject.toml
└── src/
    └── components/
        ├── __init__.py
        ├── accordeon_ds/
        ├── button_ds/
        ├── card_dist_ds/
        ├── card_metric_ds/
        ├── identification_field_ds/
        ├── info_bar_ds/
        ├── panel_ds/
        └── tabs_ds/
```

Cada componente segue a estrutura:
```
component_name/
├── __init__.py          # exporta a função principal
├── component_name.py    # implementação Python
└── css/
    └── component_name.css  # estilos do componente
```


### Licença

MIT © lpozza

## 🇺🇸 English

### About the project

**SAT Design System** (`sat-ds`) is a Python component library built on top of [Streamlit](https://streamlit.io), created to standardize the visual interface of applications embedded in the **SAT** system via MainFrame.

The library was born from the need to reuse UI components with a consistent visual identity across subsequent applications that are embedded inside the main platform. Instead of recreating styles and UI logic in each individual project, `sat-ds` centralizes these elements into a single pip-installable package.

Each component was carefully redesigned following the exclusive SAT Design System guidelines, ensuring visual cohesion and a uniform user experience across all platform applications.

---

### Installation

#### Requirements

- Python >= 3.9
- Streamlit installed in the consuming project

#### Via pip (internal / local registry)

```bash
pip install sat-ds
```

#### Via pip pointing to a Git repository

```bash
pip install git+https://github.com/your-org/sat-ds.git
```

#### Via local file (during development)

Clone the repository and install in editable mode:

```bash
git clone https://github.com/your-org/sat-ds.git
cd sat-ds
pip install -e .
```

---

### Available components

| Component | Main function | Description |
|---|---|---|
| `button_ds` | `button_ds(title, bg_color, ...)` | Pill-shaped styled button with optional SVG icon |
| `card_dist_ds` | `card_dist_ds(title, value, percent, ...)` | Distribution card showing monetary values and percentages |
| `card_metric_ds` | `card_metric_ds(title, value, icon, ...)` | Metric card with delta, tooltip, and size variation support |
| `identification_field_ds` | `identification_field_ds(label, placeholder, ...)` | Styled text input for identifier entry |
| `info_bar_ds` | `info_bar_ds(text, bg_color, ...)` | Info/alert bar with customizable color and border |
| `panel_ds` | `with panel_ds(key, ...)` | Styled border container, used as a context manager |
| `tabs_ds` | `tabs_ds(["Tab A", "Tab B"])` | Styled wrapper over `st.tabs()` |
| `accordeon_ds` | `with accordeon(label, expanded)` | Styled collapsible section over `st.expander()` |

---

### Basic usage

```python
from components import (
    button_ds,
    card_metric_ds,
    panel_ds,
    tabs_ds,
    accordeon_ds,
    info_bar_ds,
)

# Button
if button_ds("Search", bg_color="#375C38", enabled_icon=False, icon="", key="btn_1"):
    st.write("Clicked!")

# Metric card
card_metric_ds(
    title="Total Collected",
    value="R$ 1,250,000.00",
    icon="📊",
    enabled_icon=True,
    category_type="HIGH",
    size="md",
    key="metric_1",
)

# Panel (bordered container)
with panel_ds(key="main_panel"):
    st.write("Content inside the panel")

# Tabs
tab_a, tab_b = tabs_ds(["Summary", "Details"])
with tab_a:
    st.write("Summary tab content")

# Accordion
with accordeon(":material/bar_chart: Distribution by Year", expanded=False):
    st.write("Expandable content")

# Info bar
info_bar_ds("Data refers to the current fiscal year.")
```

---

### Package structure

```
sat_ds/
├── myproject.toml
└── src/
    └── components/
        ├── __init__.py
        ├── accordeon_ds/
        ├── button_ds/
        ├── card_dist_ds/
        ├── card_metric_ds/
        ├── identification_field_ds/
        ├── info_bar_ds/
        ├── panel_ds/
        └── tabs_ds/
```

Each component follows this structure:
```
component_name/
├── __init__.py          # exports the main function
├── component_name.py    # Python implementation
└── css/
    └── component_name.css  # component styles

Make sure the SAT theme package is installed alongside `sat-ds`.

---

### License

MIT © lpozza
