sat-ds 0.0.5

Biblioteca de componentes reutilizáveis

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, 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)

pip install sat-ds

Via pip apontando para o repositório Git

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:

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

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, 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)

pip install sat-ds

Via pip pointing to a Git repository

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

Via local file (during development)

Clone the repository and install in editable mode:

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

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