npm package: @rede-ancora/turbo-ui
Description: <p align="center">   <img src="https://raw.githubusercontent.com/gaqno/turbo-ui/main/src/assets/images/d1661f945a383bb8a130a86f_Frame_2.png" width="100" /> </p> <p align="center">     <h1 align="center">TURBO-UI</h1> </p>
Author: Mauri Costa
Latest version: 4.8.0

<p align="center">
  <img src="https://raw.githubusercontent.com/gaqno/turbo-ui/main/src/assets/images/d1661f945a383bb8a130a86f_Frame_2.png" width="100" />
</p>
<p align="center">
    <h1 align="center">TURBO-UI</h1>
</p>

<p align="center">
	<img src="https://img.shields.io/github/license/gaqno/turbo-ui?style=flat&color=0080ff" alt="license">
	<img src="https://img.shields.io/github/last-commit/gaqno/turbo-ui?style=flat&logo=git&logoColor=white&color=0080ff" alt="last-commit">
	<img src="https://img.shields.io/github/languages/top/gaqno/turbo-ui?style=flat&color=0080ff" alt="repo-top-language">
	<img src="https://img.shields.io/github/languages/count/gaqno/turbo-ui?style=flat&color=0080ff" alt="repo-language-count">
<p>
<p align="center">
		<em>Developed with the software and tools below.</em>
</p>
<p align="center">
	<img src="https://img.shields.io/badge/Storybook-FF4785.svg?style=flat&logo=Storybook&logoColor=white" alt="Storybook">
	<img src="https://img.shields.io/badge/React-61DAFB.svg?style=flat&logo=React&logoColor=black" alt="React">
	<img src="https://img.shields.io/badge/TypeScript-3178C6.svg?style=flat&logo=TypeScript&logoColor=white" alt="TypeScript">
	<img src="https://img.shields.io/badge/npm-CB3837.svg?style=flat&logo=npm&logoColor=white" alt="npm">
</p>
<hr>

## 🔗 Quick Links

> - [📍 O que é o projeto](#-o-que-é-o-projeto)
> - [⚙️ Instalação](#️-instalação)
> - [🚀 Como rodar localmente](#-como-rodar-localmente)
> - [🧪 Como testar](#-como-testar)
> - [🧪 Testando o Pacote Localmente](#-testando-o-pacote-localmente)
> - [📦 Deploy no NPM](#-deploy-no-npm)
> - [🤝 Contribuindo](#-contribuindo)

---

## 📍 O que é o projeto

Turbo-UI é uma biblioteca de componentes de interface de usuário (UI) desenvolvida especificamente para simplificar a construção e personalização de interfaces. A biblioteca fornece uma coleção abrangente de componentes React baseados em Material-UI, oferecendo uma experiência robusta e interativa.

### Características principais

- ⚙️ **Componentes customizados** baseados no MUI/Material
- 🔩 **TypeScript** para segurança de tipos e manutenibilidade
- 🧩 **Modularidade** com componentes React reutilizáveis
- 🧪 **Testes** com Vitest e Testing Library
- ⚡️ **Performance** otimizada com Vite
- 📚 **Storybook** para documentação e visualização de componentes

---

## ⚙️ Instalação

### 1. Instalar o pacote

Na sua aplicação React, instale a dependência:

```sh
npm install @rede-ancora/turbo-ui
```

### 2. Configurar os Providers

Após instalar, configure os Providers necessários na sua aplicação:

```tsx
// App.tsx
import { ProviderComponent } from '@rede-ancora/turbo-ui'
import { ToastProvider } from '@rede-ancora/turbo-ui'

return (
    <ProviderComponent theme={themeShell}>
        <ToastProvider>
            {children}
        </ToastProvider>
    </ProviderComponent>
)
```

### 3. Usar os componentes

```tsx
import { Button } from '@rede-ancora/turbo-ui'

export default function Example() {
    return (
        <Button>Clique aqui</Button>
    )
}
```

---

## 🚀 Como rodar localmente

Para desenvolver e visualizar os componentes localmente, utilize o Storybook:

### Pré-requisitos

- Node.js (versão 10 ou superior)
- npm ou yarn

### Executar o Storybook

```sh
npm install
npm run storybook
```

O Storybook estará disponível em `http://localhost:6006`

### Build do Storybook

Para gerar uma build estática do Storybook:

```sh
npm run build-storybook
```

---

## 🧪 Como testar

Execute os testes unitários do projeto:

```sh
npm test
```

### Executar lint

Verifique o código com ESLint:

```sh
npm run lint
```

### Build do projeto

Para gerar a build de produção:

```sh
npm run build
```

---

## 🧪 Testando o Pacote Localmente

Antes de publicar alterações no NPM, é **essencial** testar o pacote localmente. Existem duas formas principais:

### 🔗 Método 1: Usando `npm link` (Recomendado para desenvolvimento contínuo)

Este método cria um link simbólico entre o pacote local e o projeto que o utiliza, permitindo testar alterações em tempo real.

#### Passo 1: Criar o link no pacote turbo-ui

No diretório raiz do projeto `turbo-ui`:

```sh
npm link
```

#### Passo 2: Linkar no projeto de teste

No diretório do projeto onde você deseja testar:

```sh
npm link @rede-ancora/turbo-ui
```

#### Passo 3: Remover o link (quando terminar)

No projeto de teste:

```sh
npm unlink @rede-ancora/turbo-ui
npm install @rede-ancora/turbo-ui
```

No diretório do `turbo-ui` (opcional):

```sh
npm unlink
```

### 📦 Método 2: Usando `npm pack` (Recomendado para testes finais)

Este método cria um arquivo `.tgz` que simula exatamente como o pacote será publicado no NPM.

#### Passo 1: Criar o pacote

No diretório raiz do projeto `turbo-ui`:

```sh
npm pack
```

Isso criará um arquivo `.tgz` (ex: `rede-ancora-turbo-ui-4.0.0.tgz`).

#### Passo 2: Instalar no projeto de teste

```sh
npm install /caminho/para/turbo-ui/rede-ancora-turbo-ui-4.0.0.tgz
```

Ou usando caminho relativo:

```sh
npm install ../turbo-ui/rede-ancora-turbo-ui-4.0.0.tgz
```

#### Passo 3: Limpar após os testes

```sh
npm uninstall @rede-ancora/turbo-ui
npm install @rede-ancora/turbo-ui
```

E delete o arquivo `.tgz` criado.

### 📝 Qual método usar?

- **`npm link`**: Use quando estiver desenvolvendo ativamente e precisar ver alterações em tempo real
- **`npm pack`**: Use para um teste final antes de publicar, pois simula exatamente como o pacote será instalado do NPM

---

## 📦 Deploy no NPM

Esta seção descreve o processo de publicação do pacote `@rede-ancora/turbo-ui` no NPM.

### 🔹 Versão v3

Para atualizar componentes da **versão v3**:

1. **Trabalhe na branch correta**:
   ```sh
   git checkout turbo-ui-v3
   ```

2. **Faça suas alterações** e teste localmente

3. **Publique no NPM**:
   ```sh
   npm run publish_v3
   ```

4. **Instalação**: Para instalar a versão v3:
   ```sh
   npm i @rede-ancora/turbo-ui@3
   ```

### 🔹 Versão v4

Para atualizar componentes da **versão v4** (versão principal):

1. **Trabalhe na branch principal**:
   ```sh
   git checkout main
   ```

2. **Faça suas alterações** e teste localmente

3. **Escolha o comando de publicação apropriado**:
   
   - **Correções de bugs**: 
     ```sh
     npm run publish_bug
     ```
   
   - **Novas funcionalidades e melhorias**: 
     ```sh
     npm run publish_feature
     ```
   
   - **Nova versão**: 
     ```sh
     npm run publish_version
     ```
   
   - **Versão beta**: 
     ```sh
     npm run publish_beta
     ```

4. **Instalação**: Para instalar a versão v4:
   ```sh
   npm i @rede-ancora/turbo-ui
   ```
   ou
   ```sh
   npm i @rede-ancora/turbo-ui@latest
   ```

### ⚠️ Notas Importantes

- ⚠️ **Sempre verifique a branch correta** antes de fazer alterações e publicar
- ⚠️ **Teste localmente** antes de publicar no NPM (veja seção acima)
- ⚠️ **Use o comando apropriado** conforme o tipo de alteração
- ⚠️ **Versão v3** utiliza a branch `turbo-ui-v3` e o comando `publish_v3`
- ⚠️ **Versão v4** utiliza a branch `main` e os comandos específicos conforme o tipo de publicação

---

## 🤝 Contribuindo

Contribuições são bem-vindas! Para contribuir:

1. **Faça um Fork** do repositório
2. **Clone localmente**:

3. **Crie uma nova branch**:
   ```sh
   git checkout -b new-feature-x
   ```
4. **Faça suas alterações** e teste localmente
5. **Faça o commit** usando Conventional Commits:
   ```sh
   git commit -m 'TSTO32@fix: add turbo-ui package'
   ```
6. **Push** para o repositório:
   ```sh
   git push origin new-feature-x
   ```
7. **Envie um Pull Request** descrevendo claramente as alterações

Após a aprovação do PR, consulte a seção [📦 Deploy no NPM](#-deploy-no-npm) para publicar as alterações.

---

## 👏 Desenvolvido por

- Mauri Costa
- Gabriel Aquino

---

[**Voltar ao topo**](#-quick-links)