@mlw-packages/react-components 1.6.1 → 1.7.1

package/README.md

@@ -1,114 +1,355 @@
+## @mlw-packages/react-components
 
-# @mlw-packages/react-components
+Biblioteca de componentes React pronta para produção • TypeScript + Tailwind
 
-Biblioteca de componentes React reutilizáveis, focada em acelerar o desenvolvimento de aplicações web modernas, acessíveis e com design consistente. Construída com Tailwind CSS para máxima customização, performance e escalabilidade.
+---
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@mlw-packages/react-components">
+    <img alt="npm version" src="https://img.shields.io/npm/v/@mlw-packages/react-components?style=for-the-badge&label=npm&logo=npm&color=CB3837" />
+  </a>
+  <a href="https://main--68e80310a069c2f10b546ef3.chromatic.com">
+    <img alt="storybook" src="https://img.shields.io/badge/storybook-live-ff4785?style=for-the-badge&logo=storybook" />
+  </a>
+</p>
+
+> Coleção de _building blocks_ UI — pensada para velocidade de desenvolvimento, consistência visual, acessibilidade e performance.
+
+---
+
+## Índice
+
+- [Visão geral](#visão-geral)
+- [Principles (princípios)](#principles-princ%C3%ADpios)
+- [Instalação](#instala%C3%A7%C3%A3o)
+- [Quick start](#quick-start)
+- [Uso e boas práticas](#uso-e-boas-pr%C3%A1ticas)
+- [Storybook (demos)](#storybook-demos)
+- [Componentes principais](#componentes-principais)
+- [Lista completa de componentes (stories)](#lista-completa-de-componentes-stories)
+- [Desenvolvimento local](#desenvolvimento-local)
+- [Testes & Quality Gates](#testes--quality-gates)
+- [Problemas comuns](#problemas-comuns)
+- [Contribuição](#contribui%C3%A7%C3%A3o)
+- [Changelog & Releases](#changelog--releases)
+- [Contato & Licença](#contato--licen%C3%A7a)
+
+---
+
+## Visão geral
+
+`@mlw-packages/react-components` fornece um conjunto coeso de componentes reutilizáveis (Buttons, Cards, Inputs, Modals, Tables, etc.) com foco em:
+
+- API simples e tipada (TypeScript) — documentação via Storybook.
+- Estilos orientados a Tailwind para customização via `className`.
+- Padrões de acessibilidade (aria, keyboard, focus management).
+- Baixas dependências — ícones e extras como _peer deps_.
+
+Use quando precisar padronizar UI e acelerar entregas sem sacrificar qualidade.
+
+---
+
+## Principles (princípios)
+
+1. **Composição sobre herança** — componentes pequenos, combináveis.
+2. **Acessibilidade primeiro** — keyboard-friendly, roles, labels.
+3. **Tailwind como API** — `className` para customização limitada.
+4. **Mínimas dependências** — pacote enxuto para bundles menores.
+5. **Testabilidade** — props determinísticas e `data-testid` opcionais.
 
 ---
 
 ## Instalação
 
-Instale via npm ou yarn:
+Compatível com npm, yarn e pnpm:
 
 ```bash
 npm install @mlw-packages/react-components
 # ou
 yarn add @mlw-packages/react-components
+# ou
+pnpm add @mlw-packages/react-components
 ```
 
----
+> **Peer deps**: React 18+ e Tailwind configurado. Se usar ícones, instale `@phosphor-icons/react` como peer-dep.
 
-##  Uso Básico
+---
 
-Importe os componentes que precisa e use direto no JSX:
+## Quick start
 
 ```tsx
-import { ButtonBase, CardBase } from '@mlw-packages/react-components';
+import React from "react";
+import { CardBase, ButtonBase } from "@mlw-packages/react-components";
+import "@mlw-packages/react-components/style/global.css";
 
 export function App() {
   return (
-    <CardBase>
-      <ButtonBase>Meu botão</ButtonBase>
-    </CardBase>
+    <main className="p-6 max-w-3xl mx-auto">
+      <CardBase className="p-6">
+        <h3 className="text-lg font-semibold">Bem-vindo</h3>
+        <p className="mt-2">Use os componentes para acelerar o layout.</p>
+        <div className="mt-4">
+          <ButtonBase variant="primary">Clique aqui</ButtonBase>
+        </div>
+      </CardBase>
+    </main>
   );
 }
 ```
 
+**Notas rápidas**
+
+- `className` é exposto na maioria dos componentes para customização.
+- Variantes comuns: `primary`, `secondary`, `ghost`.
+
+---
+
+## Uso e boas práticas
+
+- **Composição**: prefira combinar componentes ao invés de alterar internals.
+- **Acessibilidade**: passe `aria-*` quando aplicável (ex.: `aria-label` em botões iconográficos).
+- **SSR**: componentes são compatíveis com server-side rendering; evite acessar `window` direto.
+- **Theming**: use classes utilitárias do Tailwind e tokenize valores em `tailwind.config.js` quando necessário.
+
 ---
 
-## Componentes Disponíveis
+## Storybook (demos)
 
-A biblioteca oferece uma gama completa de componentes UI prontos para produção, todos estilizados com Tailwind CSS e pensados para alta acessibilidade:
+Veja as demos interativas e a documentação de props no Storybook:
 
-- **ButtonBase** — Botões com variantes e estados customizados.
-- **CardBase** — Containers card com estrutura padrão.
-- **InputBase**, **SelectBase**, **ComboboxBase** — Controles de formulário modernos.
-- **CheckboxBase**, **SwitchBase** — Inputs booleanos.
-- **TabsBase**, **TableBase**, **TooltipBase**, **DialogBase**, **DrawerBase** — Navegação e modais.
-- **SidebarBase**, **AvatarBase**, **CalendarBase**, **CarouselBase**, **ProgressBase**, **SkeletonBase** — Componentes utilitários e visuais.
-- **SonnerBase** — Sistema de notificações toast com feedback visual.
+> [Abrir Storybook](https://main--68e80310a069c2f10b546ef3.chromatic.com)
 
-> Para a lista completa, confira a pasta `src/components/ui` no código fonte.
+Use **Controls** para testar props dinamicamente e **Docs** para copiar snippets.
 
 ---
 
-## Estilos e Customização
+### Lista completa de componentes
 
-Todos os componentes são estilizados com **Tailwind CSS**. Para que funcionem corretamente, seu projeto deve estar configurado com Tailwind.
+Abaixo está a lista completa de componentes :
 
-Importe o CSS global para aplicar estilos base da biblioteca:
+- AlertDialog
 
-```tsx
-import '@mlw-packages/react-components/style/global.css';
-```
+- Avatar
 
-A arquitetura dos componentes segue as melhores práticas:
+- Badge
 
-- **Código limpo e DRY** para facilitar manutenção e evolução.
-- **Alta performance** com React 18 e otimizações internas.
-- **Flexibilidade** para customizar via props, classes e hooks.
+- BarChart
 
----
+- Breadcrumb
 
-## Data-testid para Testes Automatizados
+- Button
 
-Todos os componentes aceitam **props opcionais** para customizar `data-testid` nos elementos internos, garantindo que seu time de QA consiga criar testes e2e robustos e confiáveis.
+- Calendar
 
-Exemplo no `ComboboxBase`:
+- Card
 
-```tsx
-<ComboboxBase
-  items={items}
-  renderSelected={renderSelected}
-  handleSelection={handleSelection}
-  checkIsSelected={checkIsSelected}
-  searchPlaceholder="Busque uma opção"
-  testIds={{
-    root: "combobox-root",
-    trigger: "combobox-trigger",
-    popover: "combobox-popover",
-    option: (value) => `combobox-option-${value}`,
-  }}
-/>
+- Carousel
+
+- Chart
+
+- CheckBox
+
+- Collapsible
+
+- Combobox
+
+- ComboboxBase
+
+- Command
+
+- ContextMenu
+
+- DateTimePicker
+
+- DebouncedInput
+
+- DestructiveDialog
+
+- Dialog
+
+- DraggableTooltip
+
+- Drawer
+
+- DropDownMenu
+
+- FileUploader
+
+- Filter
+
+- Home
+
+- HoverCard
+
+- Input
+
+- Input-OTP
+
+- Label
+
+- LineChart
+
+- Loading
+
+- Modal
+
+- ModeToggle
+
+- MultiCombobox
+
+- NavigationMenu
+
+- PieChart
+
+- Popover
+
+- rogress
+
+- RangePicker
+
+- Scrollarea
+
+- Select
+
+- Separator
+
+- Sheet
+
+- Sidebar
+
+- Skeleton
+
+- Slider
+
+- Sonner
+
+- Switch
+
+- Table
+
+- Tabs
+
+- TextArea
+
+- Tooltip
+
+---
+
+## Desenvolvimento local
+
+```bash
+git clone git@github.com:grupo-malwee/react-components.git
+cd react-components
+npm install
+npm run storybook
+# lint/test/build
+npm run lint
+npm run test
+npm run build
 ```
 
+Dica: use `pnpm` para monorepos e instalações mais rápidas.
+
 ---
 
-## Documentação e Exemplos
+## Problemas comuns & diagnóstico
+
+Segue uma versão formatada e mais direta da seção de _Issues_ com passos para diagnóstico e ações rápidas.
+
+### Componente não aparece / tela em branco
+
+- Abra o console do navegador e verifique erros (ex.: export faltando, erro de runtime).
+- Confirme o import na story e que todas as props obrigatórias estão sendo passadas.
+- Se o componente depende de dados remotos, garanta mocks ou dados de exemplo na story.
+
+Checklist rápido:
+
+- [ ] Console limpo
+- [ ] Import correto
+- [ ] Props obrigatórias fornecidas
+- [ ] Dados/mocks presentes
+
+### Componente pisca ou muda de estado sozinho
+
+- Verifique addons do Storybook (Controls, Interactions) que possam disparar updates automaticamente.
+- Revise timers (clearInterval / clearTimeout) e efeitos (`useEffect`) com dependências corretas.
+- Use Actions para inspecionar eventos que dispararam mudanças.
+
+### Estilos incorretos entre temas
 
-Explore exemplos completos e documentação técnica na pasta `src/pages` dentro do repositório, incluindo:
+- Verifique variáveis de tema e classes condicionais.
+- Confirme se o decorator de tema do Storybook está aplicado na preview.
+- Atenção ao purge do Tailwind: classes dinâmicas podem ser removidas. Use `safelist` quando necessário.
 
-- Uso avançado de componentes.
-- Configurações de tema e responsividade.
-- Exemplos de integração com testes e acessibilidade.
+### Dependências / peer deps
+
+Conflitos de peer-deps podem quebrar o build. Para instalar localmente (workaround):
+
+```bash
+npm i @mlw-packages/react-components --legacy-peer-deps
+```
+
+(mesma abordagem pode ser necessária para ícones Phosphor em alguns ambientes.)
+
+### Ícones (Phosphor) não renderam
+
+Instale o pacote se estiver faltando:
+
+```bash
+npm i @phosphor-icons/react
+```
+
+Se ainda não renderizar, confirme se o bundler transpila pacotes ESM/TSX corretamente (Vite normalmente já faz isso; em setups customizados pode ser preciso configurar `optimizeDeps` ou `esbuild` / `babel` transpile).
+
+### Dicas rápidas
+
+- Se uma story funciona localmente mas falha no Storybook hospedado, compare environment vars e versões de dependências.
+- Para problemas de Tailwind, adicione classes dinâmicas ao `safelist` do `tailwind.config.js`.
+- Ao reportar um issue, inclua: versão do pacote, trecho mínimo reproduzível, saída do console e versão do Node/NPM.
+
+## Testes & Quality Gates
+
+- Jest + Testing Library para unit e componentes.
+- ESLint com regras TypeScript estritas.
+- CI deve bloquear merges sem `lint`/`test`/`build` bem-sucedidos.
+
+---
+
+## Problemas comuns
+
+- **Classes Tailwind desaparecendo**: cuidado com classes dinâmicas — adicione `safelist` no `tailwind.config.js`.
+- **Ícones faltando**: instale `@phosphor-icons/react` e verifique transpile ESM.
+- **Peer deps**: resolver explicitamente em CI preferível a `--legacy-peer-deps`.
 
 ---
 
 ## Contribuição
 
-Contribuições são super bem-vindas!
+Siga o fluxo padrão:
+
+1. Fork → branch com `feature/<descrição>` → PR para `main`.
+2. Inclua descrição clara, screenshots quando necessário e testes básicos.
+3. Use `pnpm`/`npm` consistentemente conforme `.github/workflows`.
+
+Sugestão de PR template: mudança, razão, passos para testar, checklist (lint/test/build).
 
 ---
 
-## Licença
+## Changelog & Releases
+
+- Versionamento semântico (SemVer). Releases automatizadas via CI (GitHub Actions + OIDC publishing quando aplicável).
+
+---
+
+## Contato
+
+- Mantido por: **Grupo Malwee**
+
+---
 
-MIT License — sinta-se livre para usar, modificar e distribuir.
+[npm]: https://www.npmjs.com/package/@mlw-packages/react-components
+[ci]: https://github.com/grupo-malwee/react-components/actions
+[storybook]: https://main--68e80310a069c2f10b546ef3.chromatic.com
+[npm version]: https://img.shields.io/npm/v/@mlw-packages/react-components
+[build status]: https://img.shields.io/github/actions/workflow/status/grupo-malwee/react-components/ci.yml
+[storybook badge]: https://img.shields.io/badge/storybook-live-ff4785