@esperanca-ui/componentes 2.1.3 → 2.1.4

package/COMPONENTS.md

@@ -0,0 +1,90 @@
+# Components Guide
+
+Guia rapido para quem instalou `@esperanca-ui/componentes` em outro projeto.
+
+Este arquivo e empacotado junto com o pacote npm para facilitar leitura por desenvolvedores e IAs.
+
+## Onde Ler No Pacote Instalado
+
+Depois de instalar:
+
+```bash
+npm install @esperanca-ui/componentes
+```
+
+voce pode consultar estes arquivos dentro de `node_modules/@esperanca-ui/componentes`:
+
+- `README.md`: visao geral e instalacao
+- `COMPONENTS.md`: este guia
+- `dist/index.d.ts`: exports publicos reais
+- `dist/components/**/*.d.ts`: assinatura detalhada por componente
+- `dist/style.css`: estilos da biblioteca
+
+## Uso Basico
+
+```tsx
+import { Button } from '@esperanca-ui/componentes';
+import '@esperanca-ui/componentes/style.css';
+
+export function Example() {
+  return <Button>Salvar</Button>;
+}
+```
+
+## Componentes Publicos
+
+| Componente | Import | Uso minimo |
+| --- | --- | --- |
+| `Background` | `import { Background } from '@esperanca-ui/componentes'` | `<Background pattern="dots" />` |
+| `Button` | `import { Button } from '@esperanca-ui/componentes'` | `<Button>Salvar</Button>` |
+| `Card` | `import { Card } from '@esperanca-ui/componentes'` | `<Card><Card.Body>Conteudo</Card.Body></Card>` |
+| `MetricCard` | `import { MetricCard } from '@esperanca-ui/componentes'` | `<MetricCard value="42" title="Ativos" />` |
+| `Checkbox` | `import { Checkbox } from '@esperanca-ui/componentes'` | `<Checkbox label="Aceito os termos" />` |
+| `ComboBox` | `import { ComboBox } from '@esperanca-ui/componentes'` | `<ComboBox options={[...]} />` |
+| `ConfirmDialog` | `import { ConfirmDialog } from '@esperanca-ui/componentes'` | `<ConfirmDialog isOpen={open} onClose={...} onConfirm={...} />` |
+| `FormSidebar` | `import { FormSidebar } from '@esperanca-ui/componentes'` | `<FormSidebar isOpen={open} onClose={...}>...</FormSidebar>` |
+| `Grid` | `import { Grid } from '@esperanca-ui/componentes'` | `<Grid columns={{ base: 1, md: 2 }} gap={4}>...</Grid>` |
+| `Input` | `import { Input } from '@esperanca-ui/componentes'` | `<Input label="Email" placeholder="Digite" />` |
+| `Loading` | `import { Loading } from '@esperanca-ui/componentes'` | `<Loading variant="spinner" />` |
+| `Modal` | `import { Modal } from '@esperanca-ui/componentes'` | `<Modal isOpen={open} onClose={...}>...</Modal>` |
+| `PageHeader` | `import { PageHeader } from '@esperanca-ui/componentes'` | `<PageHeader title="Clientes" />` |
+| `Portal` | `import { Portal } from '@esperanca-ui/componentes'` | `<Portal><div>Overlay</div></Portal>` |
+| `Radio` | `import { Radio } from '@esperanca-ui/componentes'` | `<Radio label="Opcao A" />` |
+| `RadioGroup` | `import { RadioGroup } from '@esperanca-ui/componentes'` | `<RadioGroup name="status" options={[...]} />` |
+| `Sidebar` | `import { Sidebar } from '@esperanca-ui/componentes'` | `<Sidebar sections={[...]} />` |
+| `DataTable` | `import { DataTable } from '@esperanca-ui/componentes'` | `<DataTable columns={columns} data={data} />` |
+| `Textarea` | `import { Textarea } from '@esperanca-ui/componentes'` | `<Textarea label="Descricao" />` |
+| `ThemeProvider` | `import { ThemeProvider } from '@esperanca-ui/componentes'` | `<ThemeProvider defaultTheme="system"><App /></ThemeProvider>` |
+| `ToastProvider` + `useToast` | `import { ToastProvider, useToast } from '@esperanca-ui/componentes'` | `<ToastProvider><App /></ToastProvider>` |
+| `Tooltip` | `import { Tooltip } from '@esperanca-ui/componentes'` | `<Tooltip content="Ajuda"><Button>Hover</Button></Tooltip>` |
+
+## Hooks Publicos
+
+| Hook | Uso |
+| --- | --- |
+| `useTheme` | ler/trocar tema atual |
+| `useKeyboardNavigation` | atalhos e navegacao por teclado |
+| `useFocusTrap` | prender foco em modal/dialog |
+| `useAnnouncements` | acessibilidade e mensagens aria |
+| `useMediaQuery` | responsividade por media query |
+| `useBreakpoint` | breakpoint atual |
+
+## Utilitarios Publicos
+
+| Utilitario | Uso |
+| --- | --- |
+| `mergeClasses` | juntar classes condicionais |
+| `createComponentClasses` | gerar classes por variante/modificadores |
+
+## Como Outra IA Deve Ler
+
+Se uma IA estiver trabalhando em um projeto consumidor:
+
+1. abrir `node_modules/@esperanca-ui/componentes/README.md`
+2. abrir `node_modules/@esperanca-ui/componentes/COMPONENTS.md`
+3. abrir `node_modules/@esperanca-ui/componentes/dist/index.d.ts`
+4. abrir os `d.ts` especificos do componente em `node_modules/@esperanca-ui/componentes/dist/components`
+
+## Regra Importante
+
+Para API real, considere `dist/index.d.ts` e `dist/components/**/*.d.ts` como fonte de verdade do pacote instalado.

package/README.md

@@ -1,5 +1,7 @@
 # @esperanca-ui/componentes
 
+Se voce estiver integrando esta biblioteca em outro projeto e quiser um indice rapido dos componentes publicos, leia tambem `COMPONENTS.md`.
+
 Biblioteca de componentes React (DataTable, Sidebar, FormSidebar, Input, ComboBox, Checkbox, Radio, RadioGroup, Textarea e Button) com estilos em CSS puro, build com Vite e documentação via Storybook.
 
 ## TL;DR

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@esperanca-ui/componentes",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "COMPONENTS.md"
   ],
   "main": "./dist/componentes-esperanca.umd.js",
   "module": "./dist/componentes-esperanca.es.js",