@visio-io/design-system 1.0.1 → 1.0.2

package/README.md

@@ -1,151 +1,242 @@
 # Visio Design System
 
-Biblioteca de componentes de design system baseada em React e Material-UI.
+Sistema de design unificado da Visio com componentes React reutilizáveis.
 
-## Instalação
+## 📦 Instalação
 
-### Como repositório privado (GitHub/GitLab)
-
-Para usar este repositório como biblioteca privada diretamente do Git:
+### Usando Yalc (desenvolvimento local)
 
 ```bash
-# Com pnpm
-pnpm add git+https://github.com/USUARIO/visio-design-system.git
-# ou com branch/tag específica
-pnpm add git+https://github.com/USUARIO/visio-design-system.git#main
-
-# Com npm
-npm install git+https://github.com/USUARIO/visio-design-system.git
+# No diretório do design system
+pnpm build
+yalc push
 
-# Com yarn
-yarn add git+https://github.com/USUARIO/visio-design-system.git
+# No projeto que vai consumir
+yalc add @visio-io/design-system
 ```
 
-**Para repositórios privados**, você precisará configurar autenticação:
+### Usando npm/pnpm (produção)
 
-1. **Usando SSH** (recomendado):
 ```bash
-pnpm add git+ssh://git@github.com/USUARIO/visio-design-system.git
-```
-
-2. **Usando token de acesso pessoal**:
-```bash
-pnpm add git+https://SEU_TOKEN@github.com/USUARIO/visio-design-system.git
-```
-
-3. **Configurando no `.npmrc`** do projeto que vai usar a lib:
-```
-@visio-io:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=SEU_TOKEN
+npm install @visio-io/design-system
+# ou
+pnpm add @visio-io/design-system
 ```
 
-**Nota:** O script `prepare` executa automaticamente o build quando o pacote é instalado via Git.
-
-## Dependências Peer
-
-Este pacote requer as seguintes dependências no seu projeto:
+## 🚀 Uso básico
 
-- `react` ^19.0.0
-- `react-dom` ^19.0.0
-- `@mui/material` ^5.0.0
-- `@emotion/react` ^11.0.0
-- `@emotion/styled` ^11.0.0
+### 1. Importar o CSS global
 
-## Uso
-
-### Importar componentes
+No arquivo principal da aplicação (ex: `layout.tsx`, `_app.tsx`, `main.tsx`):
 
 ```tsx
-import { Button } from "@visio-io/design-system";
-
-function App() {
-  return <Button variant="contained">Clique aqui</Button>;
-}
+import "@visio-io/design-system/style.css";
 ```
 
-**Nota:** Os estilos CSS são incluídos automaticamente quando você importa qualquer componente. Não é necessário importar o CSS manualmente.
+**⚠️ Importante:** Use `@visio-io/design-system/style.css` (sem `/dist`) porque o `package.json` já mapeia o caminho corretamente.
 
-### Importar temas
+### 2. Importar componentes
 
 ```tsx
-import { ThemeProvider } from "@mui/material/styles";
-import { lightTheme, darkTheme } from "@visio-io/design-system";
+import { Button, VideoPlayer, SearchBar } from "@visio-io/design-system";
 
 function App() {
   return (
-    <ThemeProvider theme={lightTheme}>
-      {/* Seus componentes aqui */}
-    </ThemeProvider>
+    <div>
+      <Button>Click me</Button>
+      <VideoPlayer availableQualities={[...]} />
+    </div>
   );
 }
 ```
 
-### Importar tokens
+### 3. Usar tokens de design (opcional)
 
 ```tsx
-import { spacingTokens, colorsTokens } from "@visio-io/design-system/tokens";
+import { lightColors, darkColors, spacingTokens } from "@visio-io/design-system/tokens";
+
+// Use os tokens nos seus estilos customizados
+const myStyle = {
+  color: lightColors.primary,
+  padding: spacingTokens.md,
+};
 ```
 
-## Desenvolvimento
+## 📚 Componentes disponíveis
 
-```bash
-# Instalar dependências
-pnpm install
+- **Button** - Botão customizável com variantes
+- **VideoPlayer** - Player de vídeo com suporte a WebRTC, controles completos e responsivo
+- **SearchBar** - Barra de busca com autocomplete e filtros
+- **ModuleMenu** - Menu de módulos com estados expandido/colapsado
+- **SidebarMenu** - Menu lateral com subitens
+- **GoogleMap** - Integração com Google Maps
+- **MapSpot** - Marcadores customizados para mapas
+- **CountCard** - Cartão para exibir contadores
+- **FilterButton** - Botão com dropdown de filtros
+- **NotFoundContent** - Tela de conteúdo não encontrado
+- **ZoomControls** - Controles de zoom para mapas
 
-# Executar Storybook
-pnpm dev
+## 🎨 Tema e estilização
 
-# Build da biblioteca
-pnpm build
+O design system usa Material-UI como base. Para personalizar o tema:
 
-# Verificar tipos
-pnpm type-check
+```tsx
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+import { lightTheme, darkTheme } from '@visio-io/design-system';
+
+// Use o tema padrão
+<ThemeProvider theme={lightTheme}>
+  <App />
+</ThemeProvider>
+
+// Ou customize
+const customTheme = createTheme({
+  ...lightTheme,
+  palette: {
+    ...lightTheme.palette,
+    primary: {
+      main: '#your-color',
+    },
+  },
+});
 ```
 
-## Publicação
+## 🔧 Desenvolvimento
 
-O projeto usa [Changesets](https://github.com/changesets/changesets) para gerenciamento de versões e é publicado no GitHub Packages.
+### Executar Storybook
 
-### Publicação Automática (Recomendado)
+```bash
+pnpm dev
+```
 
-O projeto possui um workflow do GitHub Actions que publica automaticamente quando há changesets no branch `main` ou `master`.
+Acesse: http://localhost:6006
+
+### Build
 
-1. Crie um changeset:
 ```bash
-pnpm changeset
+pnpm build
 ```
 
-2. Commit e push:
+### Publicar (yalc)
+
 ```bash
-git add .
-git commit -m "feat: nova funcionalidade"
-git push
+pnpm build && yalc push
 ```
 
-3. O workflow irá:
-   - Detectar o changeset
-   - Criar um PR com a atualização de versão
-   - Após merge, publicar automaticamente no GitHub Packages
+## 📖 Documentação
 
-### Publicação Manual
+Acesse o Storybook para ver a documentação completa de cada componente com exemplos interativos:
 
 ```bash
-# Build do projeto
-pnpm build
+pnpm dev
+```
+
+## 🐛 Troubleshooting
+
+### Erro: "Module not found: Can't resolve '@visio-io/design-system/dist/style.css'"
+
+**Causa:** Import incorreto do CSS.
+
+**Solução:** Use `@visio-io/design-system/style.css` (sem `/dist`):
 
-# Publicar no GitHub Packages
-pnpm publish
+```tsx
+// ❌ Errado
+import "@visio-io/design-system/dist/style.css";
+
+// ✅ Correto
+import "@visio-io/design-system/style.css";
+```
+
+### Erro: "Cannot find module '@visio-io/design-system'"
+
+**Causa:** Pacote não instalado.
+
+**Solução:** Execute `yalc add @visio-io/design-system` no projeto receptor.
+
+### Estilos não aplicados
+
+**Causa:** CSS não importado ou ordem de importação incorreta.
+
+**Solução:** 
+1. Certifique-se de importar o CSS antes dos componentes
+2. Verifique se o CSS está sendo importado no arquivo raiz da aplicação
+
+```tsx
+// ✅ Ordem correta
+import "@/app/styles/globals.css";
+import "@visio-io/design-system/style.css";
+import { Button } from "@visio-io/design-system";
 ```
 
-**Nota:** Você precisará configurar autenticação. Veja o arquivo `TUTORIAL_GITHUB_PACKAGES.md` para instruções completas.
+## 📝 Estrutura de exports
+
+O `package.json` exporta:
+
+```json
+{
+  ".": "./dist/index.es.js",           // Componentes
+  "./style.css": "./dist/style.css",   // Estilos
+  "./tokens": "./src/styles/tokens"    // Tokens de design
+}
+```
+
+## 🤝 Contribuindo
+
+1. Clone o repositório
+2. Instale as dependências: `pnpm install`
+3. Faça suas alterações
+4. Execute o Storybook: `pnpm dev`
+5. Build: `pnpm build`
+6. Teste localmente com yalc: `yalc push`
 
-### Instalação do Pacote Publicado
+## 📦 Publicando nova versão
 
-Para instalar o pacote publicado no GitHub Packages:
+### Usando Changesets (recomendado)
 
-1. Configure autenticação (veja `TUTORIAL_GITHUB_PACKAGES.md`)
-2. Instale o pacote:
 ```bash
-pnpm add @visio-io/design-system
+# 1. Criar um changeset documentando as mudanças
+pnpm changeset
+
+# 2. Atualizar versão e CHANGELOG
+pnpm changeset version
+
+# 3. Build e publicar
+pnpm release
 ```
 
+### Publicação manual
+
+```bash
+# 1. Atualizar versão no package.json
+# Edite manualmente ou use:
+npm version patch  # 1.0.1 -> 1.0.2
+npm version minor  # 1.0.1 -> 1.1.0
+npm version major  # 1.0.1 -> 2.0.0
+
+# 2. Build
+pnpm build
+
+# 3. Publicar no npm
+npm publish --access public
+
+# 4. Push das tags
+git push --follow-tags
+```
+
+### Versionamento semântico
+
+- **PATCH** (1.0.x): Correções de bugs, pequenas melhorias
+- **MINOR** (1.x.0): Novas funcionalidades, backward compatible
+- **MAJOR** (x.0.0): Breaking changes
+
+### ⚠️ Antes de publicar
+
+- ✅ Certifique-se de estar autenticado no npm: `npm login`
+- ✅ Verifique se tem permissões no package `@visio-io/design-system`
+- ✅ Atualize o CHANGELOG.md com as mudanças
+- ✅ Teste a build localmente: `pnpm build`
+- ✅ Verifique os arquivos que serão publicados: `npm pack --dry-run`
+
+## 📄 Licença
+
+Proprietary - Visio.io