Metadata-Version: 2.4
Name: sat-ds
Version: 0.0.6
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 centraliza estilos e lógica de UI em um único pacote instalável via `pip`, garantindo coesão visual e experiência uniforme entre todas as aplicações da plataforma.

---

### Instalação

#### Requisitos

- Python >= 3.9
- Streamlit instalado no projeto consumidor

```bash
# PyPI / registro interno
pip install sat-ds

# Direto do repositório Git
pip install git+https://github.com/seu-org/sat-ds.git

# Modo editável (desenvolvimento)
git clone https://github.com/seu-org/sat-ds.git
cd sat-ds
pip install -e .
```

---

### Importação

```python
from components import (
    accordeon,
    button_ds,
    card_dist_ds,
    card_metric_ds,
    identification_field_ds,
    info_bar_ds,
    panel_ds,
    tabs_ds,
)
```

---

## Componentes

---

### `accordeon`

Seção expansível (acordeão) estilizada, construída sobre `st.expander()`. Usa-se como **gerenciador de contexto** — todo conteúdo dentro do `with` aparece ao expandir.

```python
with accordeon(":material/bar_chart: Distribuição por Ano"):
    st.write("Conteúdo que aparece ao expandir")
```

| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| `label` | `str` | — | Título exibido no cabeçalho. Suporta ícones Material (`:material/icon_name:`) |
| `expanded` | `bool` | `False` | Se `True`, o acordeão inicia aberto |

**Exemplo completo:**
```python
with accordeon(":material/table_chart: Tabela de Resultados", expanded=True):
    st.dataframe(df)

with accordeon(":material/info: Observações"):
    st.write("Este relatório considera apenas notas fiscais eletrônicas.")
```

---

### `button_ds`

Botão estilizado em formato pílula com ícone SVG opcional. Retorna `True` quando clicado.

```python
if button_ds("Buscar"):
    st.write("Buscando...")
```

| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| `title_button` | `str` | `"Buscar"` | Texto exibido no botão |
| `bg_color` | `str` | `ACURACIA_HIGH_EMPHASIS` (`#375C38`) | Cor de fundo e borda do botão |
| `enabled_icon` | `bool` | `False` | Se `True`, exibe o ícone SVG à esquerda do texto |
| `icon` | `str` | ícone de lupa (SVG interno) | SVG bruto a ser exibido quando `enabled_icon=True` |
| `key` | `str` | `""` | Chave única — obrigatório quando o mesmo botão aparece mais de uma vez na página |

**Retorno:** `bool` — `True` se clicado naquele ciclo de renderização.

**Exemplos:**
```python
# Botão simples
if button_ds("Consultar", key="btn_consultar"):
    buscar_dados()

# Com ícone e cor customizada
if button_ds("Exportar", bg_color="#1A56DB", enabled_icon=True, key="btn_export"):
    exportar_excel()

# Dois botões na mesma página — key obrigatório
col1, col2 = st.columns(2)
with col1:
    if button_ds("Filtrar", key="btn_filtrar"):
        aplicar_filtros()
with col2:
    if button_ds("Limpar", key="btn_limpar"):
        limpar_filtros()
```

---

### `card_dist_ds`

Card de distribuição por período, ideal para exibir o peso percentual de cada ano/categoria dentro de um total. Mostra título, valor monetário, percentual e contagem de itens/empresas.

```python
card_dist_ds(
    title="2023",
    value="R$ 35.267.179,46",
    percent="30,2%",
    itens="44.178.950",
    companys="3.640",
)
```

| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| `title` | `str` | — | Título do card — geralmente o período (ex: `"2023"`) |
| `value` | `str` | — | Valor monetário principal formatado (ex: `"R$ 35.267.179,46"`) |
| `percent` | `str` | — | Percentual formatado (ex: `"30,2%"`) |
| `itens` | `str` | — | Quantidade de itens formatada (ex: `"44.178.950"`) |
| `companys` | `str` | — | Quantidade de empresas formatada (ex: `"3.640"`) |
| `bb_color` | `str` | `#E8BD00` | Cor da borda inferior do card |
| `percent_color` | `str` | `#E8BD00` | Cor do texto do percentual |

**Exemplo — cards lado a lado por ano:**
```python
col1, col2, col3 = st.columns(3)

with col1:
    card_dist_ds(
        title="2021",
        value="R$ 28.100.000,00",
        percent="24,1%",
        itens="38.200.000",
        companys="2.910",
        bb_color="#6A9B53",
        percent_color="#6A9B53",
    )

with col2:
    card_dist_ds(
        title="2022",
        value="R$ 31.500.000,00",
        percent="27,0%",
        itens="41.000.000",
        companys="3.210",
    )

with col3:
    card_dist_ds(
        title="2023",
        value="R$ 35.267.179,46",
        percent="30,2%",
        itens="44.178.950",
        companys="3.640",
    )
```

---

### `card_metric_ds`

Card de métrica com visual personalizado, construído sobre `st.metric()`. Suporta variação de tamanho, nível de acurácia (borda colorida), delta/ação, ícone decorativo e tooltip.

```python
card_metric_ds(
    title="Total Apurado",
    value="R$ 1.250.000,00",
)
```

| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| `title` | `str` | — | Label exibido no topo do card |
| `value` | `str` | — | Valor principal exibido em destaque |
| `icon` | `str` | `""` | Emoji ou caractere exibido à direita do valor (ex: `"📊"`) |
| `enabled_icon` | `bool` | `False` | Se `True`, renderiza o `icon` à direita do valor |
| `action` | `bool` | `False` | Se `True`, exibe o campo `delta` abaixo do valor |
| `delta` | `str` | `""` | Texto do delta/variação — só aparece quando `action=True` |
| `action_color` | `str` | `#4CAF50` | Cor do texto do delta |
| `action_bg_color` | `str` | `""` | Cor de fundo do delta em formato badge/pill. Quando preenchida, aplica padding e borda arredondada |
| `tooltip` | `str` | `""` | Texto exibido no ícone de ajuda (ℹ️) ao passar o mouse |
| `key` | `str` | `""` | Chave única — obrigatório quando o mesmo `title` aparece mais de uma vez |
| `category_type` | `CategoryType` \| `None` | `None` | Nível de acurácia — define a cor da borda inferior do card |
| `size` | `"sm"` \| `"md"` \| `"lg"` | `"sm"` | Tamanho do card: `sm` = padrão, `md` = maior, `lg` = ainda maior |

**`CategoryType` — níveis de acurácia:**

| Valor | Cor da borda | Quando usar |
|---|---|---|
| `CategoryType.HIGH` | `#6A9B53` (verde) | Acurácia alta / resultado positivo |
| `CategoryType.MEDIUM` | `#E8BD00` (amarelo) | Acurácia média / atenção |
| `CategoryType.LOW` | `#D94A48` (vermelho) | Acurácia baixa / alerta |

**Exemplos:**
```python
from components import card_metric_ds, CategoryType

# Card simples
card_metric_ds(title="Total de Itens", value="44.178.950")

# Com nível de acurácia e tamanho médio
card_metric_ds(
    title="Receita Apurada",
    value="R$ 1.250.000,00",
    category_type=CategoryType.HIGH,
    size="md",
    key="receita",
)

# Com delta e badge colorido
card_metric_ds(
    title="Variação Mensal",
    value="R$ 87.500,00",
    action=True,
    delta="+12,3% vs mês anterior",
    action_color="#6A9B53",
    action_bg_color="#DFEED8",
    key="variacao",
)

# Com ícone decorativo e tooltip
card_metric_ds(
    title="Empresas Ativas",
    value="3.640",
    icon="🏢",
    enabled_icon=True,
    tooltip="Empresas com ao menos uma NF-e emitida no período",
    key="empresas",
)

# Múltiplos cards em colunas — key obrigatório
col1, col2, col3 = st.columns(3)
with col1:
    card_metric_ds(title="NF-e", value="38.200", category_type=CategoryType.HIGH, key="nfe")
with col2:
    card_metric_ds(title="NFC-e", value="5.800", category_type=CategoryType.MEDIUM, key="nfce")
with col3:
    card_metric_ds(title="CT-e", value="178", category_type=CategoryType.LOW, key="cte")
```

> **Atenção:** quando o mesmo `title` aparece mais de uma vez na página (ex: dois cards com `"Total"`), passe um `key` único para cada um, caso contrário o Streamlit gerará um erro de chave duplicada.

---

### `identification_field_ds`

Campo de texto estilizado para entrada de identificadores como CNPJ, Inscrição Estadual etc.

```python
cnpj = identification_field_ds(
    label="CNPJ",
    placeholder="00.000.000/0000-00",
)
```

| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| `label` | `str` | — | Label exibido acima do campo |
| `placeholder` | `str` | `""` | Texto de placeholder exibido quando o campo está vazio |
| `value` | `str` | `""` | Valor inicial pré-preenchido |
| `key` | `str` | `""` | Chave única — obrigatório quando o mesmo campo aparece mais de uma vez na página |

**Retorno:** `str` — valor digitado pelo usuário.

**Exemplos:**
```python
# Campo de CNPJ
cnpj = identification_field_ds(
    label="CNPJ do Contribuinte",
    placeholder="00.000.000/0000-00",
    key="campo_cnpj",
)

# Campo de IE com valor inicial
ie = identification_field_ds(
    label="Inscrição Estadual",
    placeholder="000.000.000.000",
    value=st.session_state.get("ie_anterior", ""),
    key="campo_ie",
)

if button_ds("Buscar", key="btn_buscar"):
    buscar_contribuinte(cnpj=cnpj, ie=ie)
```

---

### `info_bar_ds`

Barra de informação ou alerta com cor de fundo, borda e texto customizáveis. Útil para comunicar contexto, avisos ou instruções ao usuário.

```python
info_bar_ds("Dados referentes ao exercício fiscal vigente.")
```

| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| `text` | `str` | — | Texto exibido na barra. Suporta HTML |
| `bg_color` | `str` | `#D9EDF7` | Cor de fundo da barra |
| `border` | `str` | `1.5px solid #BCE8F1` | Borda da barra (valor CSS completo) |
| `margin_bottom` | `str` | `""` | Espaço abaixo da barra (ex: `"16px"`) |

**Exemplos:**
```python
# Informativo padrão (azul)
info_bar_ds("Selecione um período para iniciar a consulta.")

# Alerta (amarelo)
info_bar_ds(
    "Atenção: os dados exibidos são preliminares e estão sujeitos a revisão.",
    bg_color="#FFF8E1",
    border="1.5px solid #FFD54F",
)

# Erro / destaque vermelho
info_bar_ds(
    "Nenhum resultado encontrado para os filtros informados.",
    bg_color="#FDECEA",
    border="1.5px solid #F5C6CB",
    margin_bottom="24px",
)

# Com HTML inline
info_bar_ds(
    "Competência: <strong>Janeiro/2024</strong> — Fonte: SEFAZ-MT",
    bg_color="#EDF7ED",
    border="1.5px solid #A5D6A7",
)
```

---

### `panel_ds`

Container com borda estilizada que se adapta ao conteúdo interno. Usado como **gerenciador de contexto** — todo conteúdo dentro do `with` fica encapsulado no painel.

```python
with panel_ds(key="painel_principal"):
    st.write("Conteúdo dentro do painel")
```

| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| `key` | `str` | — | Chave única do container. **Obrigatório** |
| `border_color` | `str` | `#DDD` | Cor da borda |
| `border_radius` | `str` | `"12px"` | Raio dos cantos (ex: `"8px"`, `"0"`) |
| `gap` | `str` | `""` | Espaço entre elementos filhos (ex: `"10px"`) |
| `padding` | `str` | `""` | Padding interno (ex: `"0"` para remover o padrão do Streamlit) |
| `overflow` | `str` | `""` | Comportamento de overflow (ex: `"hidden"`) |

**Exemplos:**
```python
# Painel simples
with panel_ds(key="resumo"):
    st.metric("Total", "R$ 1.250.000,00")

# Painel com borda colorida e cantos menores
with panel_ds(key="filtros", border_color="#6A9B53", border_radius="8px"):
    cnpj = identification_field_ds(label="CNPJ", placeholder="00.000.000/0000-00")
    if button_ds("Buscar", key="btn"):
        buscar(cnpj)

# Painel sem padding interno
with panel_ds(key="tabela_completa", padding="0", overflow="hidden"):
    st.dataframe(df, use_container_width=True)

# Múltiplos painéis na mesma página — key único para cada
col1, col2 = st.columns(2)
with col1:
    with panel_ds(key="painel_a"):
        st.write("Painel A")
with col2:
    with panel_ds(key="painel_b"):
        st.write("Painel B")
```

---

### `tabs_ds`

Wrapper estilizado sobre `st.tabs()`. Retorna a mesma lista de contextos de aba do Streamlit nativo, com visual padronizado pelo Design System.

```python
aba_resumo, aba_detalhes = tabs_ds(["Resumo", "Detalhes"])

with aba_resumo:
    st.write("Conteúdo da aba Resumo")

with aba_detalhes:
    st.write("Conteúdo da aba Detalhes")
```

| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| `titulo` | `list[str]` | — | Lista com os títulos das abas. Suporta texto, emoji e ícones Material |

**Retorno:** lista de contextos de aba, idêntica ao retorno de `st.tabs()`.

**Exemplos:**
```python
# Duas abas simples
aba_a, aba_b = tabs_ds(["Análise", "Dados Brutos"])
with aba_a:
    exibir_graficos()
with aba_b:
    st.dataframe(df)

# Com ícones Material
aba_1, aba_2, aba_3 = tabs_ds([
    ":material/bar_chart: Distribuição",
    ":material/table_chart: Tabela",
    ":material/info: Sobre",
])
```

---

## Estrutura do pacote

```
sat_ds/
├── pyproject.toml
└── src/
    └── components/
        ├── __init__.py
        ├── accordeon_ds/
        │   ├── __init__.py
        │   ├── accordeon_ds.py
        │   └── css/accordeon_ds.css
        ├── 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/context manager 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 centralizes UI styles and logic into a single pip-installable package, ensuring visual cohesion and a uniform experience across all platform applications.

---

### Installation

```bash
# PyPI / internal registry
pip install sat-ds

# Directly from Git repository
pip install git+https://github.com/your-org/sat-ds.git

# Editable mode (development)
git clone https://github.com/your-org/sat-ds.git
cd sat-ds
pip install -e .
```

---

### Import

```python
from components import (
    accordeon,
    button_ds,
    card_dist_ds,
    card_metric_ds,
    identification_field_ds,
    info_bar_ds,
    panel_ds,
    tabs_ds,
)
```

---

## Components

---

### `accordeon`

Styled collapsible section built on `st.expander()`. Used as a **context manager** — all content inside the `with` block appears when expanded.

```python
with accordeon(":material/bar_chart: Distribution by Year"):
    st.write("Content shown when expanded")
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `label` | `str` | — | Title shown in the header. Supports Material icons (`:material/icon_name:`) |
| `expanded` | `bool` | `False` | If `True`, the accordion starts open |

---

### `button_ds`

Pill-shaped styled button with optional SVG icon. Returns `True` when clicked.

```python
if button_ds("Search"):
    st.write("Searching...")
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `title_button` | `str` | `"Buscar"` | Button label |
| `bg_color` | `str` | `#375C38` | Background and border color |
| `enabled_icon` | `bool` | `False` | If `True`, renders the SVG icon to the left of the text |
| `icon` | `str` | magnifier SVG | Raw SVG shown when `enabled_icon=True` |
| `key` | `str` | `""` | Unique key — required when the same button appears more than once on the page |

**Returns:** `bool` — `True` if clicked on that render cycle.

---

### `card_dist_ds`

Distribution card ideal for showing the weight of each year/category within a total. Displays title, monetary value, percentage, and item/company counts.

```python
card_dist_ds(
    title="2023",
    value="R$ 35,267,179.46",
    percent="30.2%",
    itens="44,178,950",
    companys="3,640",
)
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `title` | `str` | — | Card title — usually the period (e.g. `"2023"`) |
| `value` | `str` | — | Formatted monetary value |
| `percent` | `str` | — | Formatted percentage |
| `itens` | `str` | — | Formatted item count |
| `companys` | `str` | — | Formatted company count |
| `bb_color` | `str` | `#E8BD00` | Bottom border color |
| `percent_color` | `str` | `#E8BD00` | Percentage text color |

---

### `card_metric_ds`

Metric card with custom visuals, built on `st.metric()`. Supports size variants, accuracy levels (colored border), delta/action, decorative icon, and tooltip.

```python
card_metric_ds(
    title="Total Collected",
    value="R$ 1,250,000.00",
)
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `title` | `str` | — | Label at the top of the card |
| `value` | `str` | — | Main value displayed prominently |
| `icon` | `str` | `""` | Emoji or character displayed to the right of the value |
| `enabled_icon` | `bool` | `False` | If `True`, renders the `icon` to the right of the value |
| `action` | `bool` | `False` | If `True`, shows the `delta` field below the value |
| `delta` | `str` | `""` | Delta/variation text — only shown when `action=True` |
| `action_color` | `str` | `#4CAF50` | Delta text color |
| `action_bg_color` | `str` | `""` | Delta background color as a badge/pill. When set, applies padding and rounded corners |
| `tooltip` | `str` | `""` | Text shown in the help icon (ℹ️) on hover |
| `key` | `str` | `""` | Unique key — required when the same `title` appears more than once |
| `category_type` | `CategoryType` \| `None` | `None` | Accuracy level — defines the bottom border color |
| `size` | `"sm"` \| `"md"` \| `"lg"` | `"sm"` | Card size: `sm` = default, `md` = larger, `lg` = largest |

**`CategoryType` — accuracy levels:**

| Value | Border color | When to use |
|---|---|---|
| `CategoryType.HIGH` | `#6A9B53` (green) | High accuracy / positive result |
| `CategoryType.MEDIUM` | `#E8BD00` (yellow) | Medium accuracy / caution |
| `CategoryType.LOW` | `#D94A48` (red) | Low accuracy / alert |

---

### `identification_field_ds`

Styled text input for identifiers such as CNPJ, State Registration, etc.

```python
cnpj = identification_field_ds(
    label="CNPJ",
    placeholder="00.000.000/0000-00",
)
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `label` | `str` | — | Label shown above the field |
| `placeholder` | `str` | `""` | Placeholder text shown when the field is empty |
| `value` | `str` | `""` | Pre-filled initial value |
| `key` | `str` | `""` | Unique key — required when the same field appears more than once |

**Returns:** `str` — the value typed by the user.

---

### `info_bar_ds`

Information or alert bar with customizable background color, border, and text. Useful for communicating context, warnings, or instructions.

```python
info_bar_ds("Data refers to the current fiscal year.")
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `text` | `str` | — | Text displayed in the bar. Supports inline HTML |
| `bg_color` | `str` | `#D9EDF7` | Bar background color |
| `border` | `str` | `1.5px solid #BCE8F1` | Bar border (full CSS value) |
| `margin_bottom` | `str` | `""` | Space below the bar (e.g. `"16px"`) |

---

### `panel_ds`

Styled border container that adapts to its content. Used as a **context manager** — all content inside the `with` block is encapsulated in the panel.

```python
with panel_ds(key="main_panel"):
    st.write("Content inside the panel")
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `key` | `str` | — | Unique container key. **Required** |
| `border_color` | `str` | `#DDD` | Border color |
| `border_radius` | `str` | `"12px"` | Corner radius (e.g. `"8px"`, `"0"`) |
| `gap` | `str` | `""` | Space between child elements (e.g. `"10px"`) |
| `padding` | `str` | `""` | Inner padding (e.g. `"0"` to remove Streamlit's default) |
| `overflow` | `str` | `""` | Overflow behavior (e.g. `"hidden"`) |

---

### `tabs_ds`

Styled wrapper over `st.tabs()`. Returns the same list of tab contexts as native Streamlit, with Design System visual standards applied.

```python
tab_summary, tab_details = tabs_ds(["Summary", "Details"])

with tab_summary:
    st.write("Summary tab content")

with tab_details:
    st.write("Details tab content")
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `titulo` | `list[str]` | — | List of tab titles. Supports text, emoji, and Material icons |

**Returns:** list of tab contexts, identical to the return of `st.tabs()`.

---

## Package structure

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

---

### License

MIT © lpozza
