Soma Default Component

Uma biblioteca moderna de componentes React construída com Vite, TypeScript, Storybook e Material-UI.

🚀 Características

• ⚡ Vite - Build tool ultra-rápido
• 🔷 TypeScript - Tipagem estática completa
• 📚 Storybook - Documentação interativa
• 🧪 Vitest - Testes rápidos e modernos
• 🔍 ESLint - Linting configurado
• 📦 ESM + CJS - Suporte a ambos os formatos de módulo
• 🎨 Material-UI - Componentes baseados no MUI

📦 Instalação

npm install soma-default-component

🧩 Componentes Disponíveis

SpButton

Botão genérico baseado no Material-UI Button com props flexíveis.

import { SpButton } from 'soma-default-component';

// Exemplo 1: Botão básico com cor Soma
<SpButton 
  label="Botão Primário" 
  spColor={{ palette: 'spPrimary', shade: 'SPP600' }}
/>

// Exemplo 2: Botão outlined com cor Success
<SpButton 
  label="Confirmar" 
  variant="outlined"
  spColor={{ palette: 'spSuccess', shade: 'SPS300' }}
  startIcon={<CheckIcon />}
/>

// Exemplo 3: Botão com cor Warning específica
<SpButton 
  label="Aviso" 
  variant="contained"
  spColor={{ palette: 'spWarning', shade: 'SPW300' }}
  size="large"
/>

SpButton Props

• label?: string - Texto do botão
• children?: React.ReactNode - Conteúdo customizado (substitui o label)
• variant?: 'text' | 'outlined' | 'contained' - Variante do botão
• color?: 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning' | 'spPrimary' | 'spSecondary' | 'spGrey' | 'spRed' | 'spWarning' | 'spInfo' | 'spSuccess' - Cor do botão
• spColor?: { palette: 'spPrimary' | 'spSecondary' | 'spGrey' | 'spRed' | 'spWarning' | 'spInfo' | 'spSuccess'; shade: string } - Cor específica do Soma com paleta e tom
• size?: 'small' | 'medium' | 'large' - Tamanho do botão
• borderRadius?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full' - Border radius do botão
• disabled?: boolean - Se o botão está desabilitado
• loading?: boolean - Se o botão está em estado de loading
• startIcon?: React.ReactNode - Ícone à esquerda do texto
• endIcon?: React.ReactNode - Ícone à direita do texto
• onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void - Função chamada ao clicar
• Todas as props do MUI Button

SpFab

Floating Action Button baseado no MUI Fab com suporte a cores Soma.

import { SpFab } from 'soma-default-component';

// Exemplo 1: FAB circular com cor Soma primária
<SpFab spColor={{ palette: 'spPrimary', shade: 'SPP600' }}>
  <AddIcon />
</SpFab>

// Exemplo 2: FAB extended com cor Success
<SpFab 
  variant="extended" 
  spColor={{ palette: 'spSuccess', shade: 'SPS300' }}
>
  <CheckIcon />
  Confirmar
</SpFab>

// Exemplo 3: FAB pequeno com cor Info
<SpFab 
  size="small" 
  spColor={{ palette: 'spInfo', shade: 'SPI300' }}
>
  <InfoIcon />
</SpFab>

SpFab Props

• children?: React.ReactNode - Ícone do FAB
• color?: 'default' | 'inherit' | 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning' | 'spPrimary' | 'spSecondary' | 'spGrey' | 'spRed' | 'spWarning' | 'spInfo' | 'spSuccess' - Cor do FAB
• spColor?: { palette: 'spPrimary' | 'spSecondary' | 'spGrey' | 'spRed' | 'spWarning' | 'spInfo' | 'spSuccess'; shade: string } - Cor específica do Soma com paleta e tom
• size?: 'small' | 'medium' | 'large' - Tamanho do FAB
• variant?: 'circular' | 'extended' - Variante do FAB
• disabled?: boolean - Se o FAB está desabilitado
• onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void - Função chamada ao clicar
• Todas as props do MUI Fab

SpIconButton

Botão de ícone baseado no MUI IconButton com cores Soma customizadas.

import { SpIconButton } from 'soma-default-component';

// Exemplo 1: Botão de edição com cor Soma secundária
<SpIconButton spColor={{ palette: 'spSecondary', shade: 'SPS600' }}>
  <EditIcon />
</SpIconButton>

// Exemplo 2: Botão de exclusão com cor Red
<SpIconButton spColor={{ palette: 'spRed', shade: 'SPR300' }}>
  <DeleteIcon />
</SpIconButton>

// Exemplo 3: Botão de configuração com cor Grey
<SpIconButton 
  size="large" 
  spColor={{ palette: 'spGrey', shade: 'SPG500' }}
>
  <SettingsIcon />
</SpIconButton>

SpIconButton Props

• children?: React.ReactNode - Ícone do botão
• color?: 'default' | 'inherit' | 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning' | 'spPrimary' | 'spSecondary' | 'spGrey' | 'spRed' | 'spWarning' | 'spInfo' | 'spSuccess' - Cor do botão
• spColor?: { palette: 'spPrimary' | 'spSecondary' | 'spGrey' | 'spRed' | 'spWarning' | 'spInfo' | 'spSuccess'; shade: string } - Cor específica do Soma com paleta e tom
• size?: 'small' | 'medium' | 'large' - Tamanho do botão
• disabled?: boolean - Se o botão está desabilitado
• onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void - Função chamada ao clicar
• Todas as props do MUI IconButton

SpTypography

Componente de tipografia baseado no MUI Typography com variantes customizadas.

import { SpTypography } from 'soma-default-component';

// Exemplo 1: Título com cor Soma primária
<SpTypography 
  variant="headlineLarge" 
  spColor={{ palette: 'spPrimary', shade: 'SPP800' }}
>
  Título Principal
</SpTypography>

// Exemplo 2: Texto de corpo com cor Info
<SpTypography 
  variant="bodyMedium" 
  spColor={{ palette: 'spInfo', shade: 'SPI300' }}
  gutterBottom
>
  Texto informativo importante
</SpTypography>

// Exemplo 3: Label com cor Success
<SpTypography 
  variant="labelMedium" 
  spColor={{ palette: 'spSuccess', shade: 'SPS300' }}
  align="center"
>
  Status: Ativo
</SpTypography>

SpTypography Props

• children?: React.ReactNode - Conteúdo do texto
• variant?: SomaTypographyVariant - Variante tipográfica do Soma
• gutterBottom?: boolean - Se o texto deve ter margem inferior
• paragraph?: boolean - Se o texto deve ser um parágrafo
• align?: 'inherit' | 'left' | 'center' | 'right' | 'justify' - Alinhamento do texto
• color?: 'inherit' | 'primary' | 'secondary' | 'error' | 'warning' | 'info' | 'success' | 'textPrimary' | 'textSecondary' | 'spPrimary' | 'spSecondary' | 'spGrey' | 'spRed' | 'spWarning' | 'spInfo' | 'spSuccess' - Cor do texto
• spColor?: { palette: 'spPrimary' | 'spSecondary' | 'spGrey' | 'spRed' | 'spWarning' | 'spInfo' | 'spSuccess'; shade: string } - Cor específica do Soma com paleta e tom
• noWrap?: boolean - Se o texto deve ser truncado com reticências
• Todas as props do MUI Typography

🛠️ Desenvolvimento

Pré-requisitos

• Node.js >= 16
• npm ou yarn

Scripts Disponíveis

# Desenvolvimento com hot reload
npm run dev

# Build de produção
npm run build

# Testes em modo watch
npm run test

# Executar testes uma vez
npm run test:run

# Interface de testes
npm run test:ui

# Linting do código
npm run lint

# Documentação interativa
npm run storybook

# Preview do build
npm run preview

Fluxo de Desenvolvimento Recomendado

1. Desenvolvimento da biblioteca:

   npm run dev

   Isso compila para /dist e executa em modo watch.

2. Documentação (em outro terminal):

   npm run storybook

   Abre o Storybook em http://localhost:6006

3. Exemplo de uso (em outro terminal):

   cd example
   npm install
   npm run dev

   Abre o exemplo em http://localhost:3000

🏗️ Estrutura do Projeto

├── src/                           # Código fonte da biblioteca
│   ├── components/                # Componentes organizados
│   │   └── spButton/             # Componente SpButton
│   │       ├── index.tsx         # Implementação do componente
│   │       └── test/             # Testes específicos do componente
│   │           └── spButton.test.tsx
│   └── index.tsx                 # Exportações principais
├── stories/                       # Stories do Storybook
│   ├── Thing.stories.tsx         # Story do componente Thing
│   └── SpButton.stories.tsx     # Story do componente SpButton
├── example/                       # Exemplo de uso
│   ├── index.html               # HTML do exemplo
│   ├── index.tsx                # App de exemplo
│   └── vite.config.ts           # Configuração do Vite
├── test/                         # Testes globais
│   ├── setup.ts                 # Configuração dos testes
│   └── blah.test.tsx            # Testes do componente Thing
├── dist/                         # Build de produção
├── vite.config.ts                # Configuração principal do Vite
├── eslint.config.js              # Configuração do ESLint
└── tsconfig.json                 # Configuração do TypeScript

🧪 Testes

O projeto usa Vitest para testes rápidos e modernos com estrutura organizada:

# Executar todos os testes
npm run test:run

# Testes em modo watch
npm run test

# Interface visual dos testes
npm run test:ui

Estrutura de Testes

• Testes globais: /test/ - Testes de componentes gerais
• Testes específicos: /src/components/[componente]/test/ - Testes organizados por componente
• Configuração: Vitest configurado para encontrar testes em ambas as estruturas

Configuração de Testes

• Vitest - Framework de testes
• @testing-library/react - Utilitários para testes React
• @testing-library/jest-dom - Matchers customizados
• jsdom - Ambiente DOM para testes

📚 Storybook

Documentação interativa dos componentes:

npm run storybook
yarn storybook

Características do Storybook

• v9.1.10 - Versão mais recente
• Vite Builder - Build rápido
• Auto-docs - Documentação automática
• Controls - Controles interativos
• Actions - Log de eventos

🔧 Configuração

Vite

O projeto usa Vite para:

• Build ultra-rápido
• Hot Module Replacement (HMR)
• Suporte a TypeScript nativo
• Geração automática de tipos (.d.ts)
• Minificação com Terser

TypeScript

Configuração moderna com:

• Target: ES2020
• JSX: react-jsx (sem necessidade de importar React)
• Strict mode habilitado
• Source maps para debugging

ESLint

Linting configurado com:

• ESLint v9 - Configuração moderna
• @typescript-eslint - Regras TypeScript
• eslint-plugin-react - Regras React
• eslint-plugin-react-hooks - Regras para hooks

📦 Build

Formatos Suportados

• ESM (dist/soma-default-component.esm.js)
• CJS (dist/soma-default-component.cjs.js)
• Types (dist/index.d.ts)
• Source Maps (.map files)

Configuração de Build

// vite.config.ts
export default defineConfig({
  build: {
    lib: {
      entry: 'src/index.tsx',
      name: 'SomaDefaultComponent',
      formats: ['es', 'cjs'],
    },
    rollupOptions: {
      external: ['react', 'react-dom'],
    },
  },
});

🚀 Deploy

Exemplo

O exemplo pode ser deployado em qualquer plataforma:

cd example
npm run build
# Deploy da pasta dist/

Biblioteca

Para publicar no NPM:

npm run build
npm publish

🤝 Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

Padrões de Código

• Use TypeScript para tipagem
• Siga as regras do ESLint
• Escreva testes para novos componentes
• Adicione stories no Storybook
• Use named exports

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🧑‍💻 Autor

Rafael Nascimento

🔄 Migração do TSDX

Este projeto foi migrado do TSDX para Vite para aproveitar:

• ⚡ Performance superior - Build até 10x mais rápido
• 🔧 Configuração moderna - Ferramentas atualizadas
• 🛠️ Melhor DX - Hot reload mais rápido
• 📦 Flexibilidade - Configuração granular
• 🔮 Futuro - Ferramentas mantidas ativamente
• 🎨 Material-UI - Componentes baseados no MUI

Principais Mudanças

• TSDX → Vite (build tool)
• Jest → Vitest (testes)
• Parcel → Vite (exemplo)
• Storybook v6 → Storybook v9
• TypeScript v4 → TypeScript v5
• ESLint v8 → ESLint v9
• Adicionado Material-UI para componentes base