@aarintech/consorcio-ui

Biblioteca de componentes React reutilizáveis para interfaces de consórcio, parte do ecossistema Aarin Techfin. Garante padronização visual e produtividade no desenvolvimento de aplicações financeiras.

Índice

• Instalação como dependência
• Uso Básico
• Desenvolvimento local
• Arquitetura do projeto
• Criando um novo componente
• Estilização
• Testes
• Storybook
• Convenção de commits
• Build e publicação

Instalação como dependência

pnpm add @aarintech/consorcio-ui
# ou
npm install @aarintech/consorcio-ui
# ou
yarn add @aarintech/consorcio-ui

Peer dependencies

A biblioteca requer as seguintes dependências no projeto consumidor:

{
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
  "next": "^15.0.0"
}

Uso Básico

import { Chip, Alert, LoadingSpinner } from '@aarintech/consorcio-ui';

function App() {
  return (
    <>
      <Alert severity="info" title="Atenção" />
      <Chip label="Ativo" />
      <LoadingSpinner />
    </>
  );
}

Todos os componentes exportados estão listados em src/index.ts.

Desenvolvimento local

Pré-requisitos

• Node.js ≥ 18
• pnpm ≥ 9

Instalação

pnpm install

Scripts disponíveis

| Comando | Descrição | | ---------------------- | ------------------------------------------------- | | pnpm dev | Inicia o servidor de desenvolvimento Vite | | pnpm build | Gera o build de produção da biblioteca em dist/ | | pnpm preview | Visualiza o build gerado localmente | | pnpm lint | Executa o ESLint em todo o projeto | | pnpm format | Formata o código com Prettier | | pnpm format:check | Verifica a formatação sem alterar arquivos | | pnpm test | Executa os testes unitários | | pnpm test:watch | Executa os testes em modo watch | | pnpm test:coverage | Executa os testes e gera relatório de cobertura | | pnpm test:storybook | Executa os testes de interação do Storybook | | pnpm storybook | Inicia o Storybook na porta 6006 | | pnpm build-storybook | Gera o build estático do Storybook | | pnpm add-component | Gera o scaffold de um novo componente via Plop |

Arquitetura do projeto

consorcio-ui/
├── src/
│   ├── index.ts                  # Ponto de entrada da biblioteca (API pública)
│   ├── types.ts                  # Tipos globais compartilhados
│   ├── components/               # Todos os componentes da biblioteca
│   │   ├── index.ts              # Re-exporta todos os componentes
│   │   ├── locales.ts            # Strings de internacionalização
│   │   └── <nome-do-componente>/ # Cada componente em sua própria pasta
│   ├── config/
│   │   ├── theme/                # Tokens de design (cores, tipografia, breakpoints)
│   │   ├── constants/            # Constantes e mocks reutilizáveis
│   │   └── helpers/              # Funções utilitárias
│   └── stories/                  # Stories do Storybook
│       └── components/
├── plop-templates/               # Templates do gerador de componentes
│   └── Component.tsx.hbs
├── __mocks__/                    # Mocks para testes
│   └── @aarintech/
│       └── assets.tsx
├── vite.config.ts                # Configuração do Vite (build da lib)
├── vitest.workspace.ts           # Workspace com os projetos de teste (unit + storybook)
├── vitest.unit.config.ts         # Configuração dos testes unitários
├── vitest.setup.ts               # Setup global dos testes
├── plopfile.cjs                  # Configuração do gerador de componentes
├── commitlint.config.cjs         # Regras de lint para mensagens de commit
└── eslint.config.js              # Configuração do ESLint

Fluxo de dados (como a biblioteca é distribuída)

src/index.ts  →  vite build  →  dist/
                                ├── @aarintechfin-consorcio-ui.es.js   (ESM)
                                ├── @aarintechfin-consorcio-ui.umd.js  (UMD)
                                └── index.d.ts                          (tipos)

O campo module do package.json aponta para o bundle ESM e main para o UMD. Os tipos são gerados pelo plugin vite-plugin-dts.

Onde cada coisa fica

| O que | Onde criar | | ---------------------------- | ----------------------------------------------- | | Novo componente | src/components/<nome-kebab-case>/ | | Export público do componente | src/index.ts | | Tokens de cor/tipografia | src/config/theme/colors.ts ou typography.ts | | Breakpoints | src/config/theme/breakpoints.ts | | Constantes de máscara | src/config/constants/masks.ts | | Funções utilitárias | src/config/helpers/ | | Story do componente | src/stories/components/ | | Mock para testes | __mocks__/ |

Criando um novo componente

Execute o gerador interativo:

pnpm add-component

O gerador (plopfile.cjs) solicitará o nome em kebab-case e criará o arquivo base em src/components/<nome>/index.tsx a partir do template plop-templates/Component.tsx.hbs.

Após a geração, adicione manualmente os arquivos complementares seguindo a estrutura padrão:

src/components/meu-componente/
├── index.tsx              # Implementação principal do componente
├── styles.ts              # Estilos via hook useStyles()
├── types.ts               # Tipos e interfaces TypeScript (quando necessário)
├── components/            # Sub-componentes internos (quando necessário)
│   └── meu-sub-componente/
│       └── index.tsx
├── hooks/                 # Hooks específicos do componente (quando necessário)
│   └── use-meu-componente.tsx
└── __tests__/             # Testes do componente
    └── meu-componente.client.test.tsx

Por fim, exporte o componente em dois lugares:

1. src/components/index.ts — usado internamente
2. src/index.ts — expõe o componente na API pública da biblioteca

Estilização

A estilização usa o sistema sx do MUI (Material UI) integrado ao tema da biblioteca. O padrão é encapsular os estilos em um hook useStyles() dentro de styles.ts, retornando um objeto tipado com SxThemeProps.

// styles.ts
import type { SxThemeProps } from '@/config/theme';

export const useStyles = () => {
  return {
    container: {
      flexDirection: 'row',
      gap: 1,
      borderRadius: '100px',
      borderColor: 'text.secondary',
      borderStyle: 'solid',
    },
    label: { typography: 'body2', color: 'text.secondary' },
  } satisfies SxThemeProps;
};

// index.tsx
import { useStyles } from './styles';

export const MeuComponente = () => {
  const styles = useStyles();
  return <Stack sx={styles.container} />;
};

Tokens de design

Os tokens ficam em src/config/theme/ e são aplicados via ThemeProvider:

| Arquivo | Responsabilidade | | ----------------------- | ----------------------------------------- | | colors.ts | Paleta de cores | | typography.ts | Escala tipográfica | | breakpoints.ts | Breakpoints responsivos | | font-sizes.ts | Tamanhos de fonte | | font-family-tokens.ts | Famílias tipográficas | | theme.ts | Composição do tema MUI | | overrides/ | Customizações de componentes MUI | | provider/ | ThemeProvider para uso nos consumidores |

Testes

Os testes utilizam Vitest + jsdom + Testing Library.

O workspace de testes (vitest.workspace.ts) define dois projetos:

| Projeto | Comando | Descrição | | ----------- | --------------------- | ------------------------------------------- | | unit | pnpm test | Testes unitários com jsdom | | storybook | pnpm test:storybook | Testes de interação via Playwright/Chromium |

Convenções

• Nomenclatura: <nome>.client.test.tsx dentro de __tests__/
• Cobertura mínima: ≥ 80% (verificada via pnpm test:coverage)
• Alias @ aponta para src/ tanto no código quanto nos testes

# Rodar testes unitários
pnpm test

# Rodar com watch
pnpm test:watch

# Gerar relatório de cobertura (text + lcov)
pnpm test:coverage

Storybook

O Storybook documenta e exibe os componentes visualmente. As stories ficam em src/stories/components/.

# Iniciar em modo desenvolvimento (porta 6006)
pnpm storybook

# Gerar build estático (saída em storybook-static/)
pnpm build-storybook

Convenção de commits

O projeto usa Conventional Commits validado pelo commitlint. Formato obrigatório:

<tipo>(escopo opcional): descrição curta

Exemplos:
feat(chip): adicionar suporte a ícone
fix(alert): corrigir cor no modo escuro
chore: atualizar dependências
docs: melhorar README

Tipos aceitos: feat, fix, docs, style, refactor, test, chore, perf, ci.

O hook de pre-commit (Husky + lint-staged) executa o Prettier automaticamente nos arquivos alterados.

Build e publicação

# Gerar o build da biblioteca
pnpm build

Os artefatos são gerados em dist/:

• @aarintechfin-consorcio-ui.es.js — bundle ESM
• @aarintechfin-consorcio-ui.umd.js — bundle UMD
• index.d.ts — declarações de tipos

A publicação é automatizada via semantic-release na pipeline de CI. O versionamento segue Semantic Versioning derivado das mensagens de commit.

Para executar os testes:

# Execução única
pnpm test

# Modo watch
pnpm test:watch

# Com relatório de cobertura
pnpm test:coverage

Sobre

Esta biblioteca faz parte do ecossistema Aarin Techfin e é mantida pelo time de tecnologia da Aarin.