sat-ds 0.0.6

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

# 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

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.

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:

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.

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:

# 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.

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:

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.

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:

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.

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:

# 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.

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:

# 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.

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:

# 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.

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:

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

# 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

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.

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.

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.

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.

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.

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.

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.

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.

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