vex-ui-kit 1.0.0

package/README.md

@@ -0,0 +1,830 @@
+<div align="center">
+
+# VexUI
+
+**Sistema completo de feedback visual para a web**
+
+Alerts · Modals · Drawers · Step Flows · Inline Prompts
+
+[![npm version](https://img.shields.io/badge/npm-v1.0.0-4F46E5?style=flat-square)](https://npmjs.com/package/vexui)
+[![license](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)](./LICENSE)
+[![zero deps](https://img.shields.io/badge/deps-zero-06B6D4?style=flat-square)](#)
+[![gzip](https://img.shields.io/badge/gzip-~8kb-f59e0b?style=flat-square)](#)
+
+```bash
+npm install vex-ui-kit
+```
+
+</div>
+
+---
+
+## Índice
+
+- [Visão Geral](#visão-geral)
+- [Por que VexUI?](#por-que-vexui)
+- [Tecnologias](#tecnologias)
+- [Instalação](#instalação)
+- [Estrutura de Arquivos](#estrutura-de-arquivos)
+- [Alerts](#alerts)
+- [Modals](#modals)
+- [Funcionalidades Exclusivas](#funcionalidades-exclusivas)
+- [Sistema de Temas](#sistema-de-temas)
+- [Acessibilidade](#acessibilidade)
+- [Integrações](#integrações)
+- [API Completa](#api-completa)
+- [Roadmap](#roadmap)
+
+---
+
+## Visão Geral
+
+VexUI é uma biblioteca JavaScript de **feedback visual** que substitui completamente soluções fragmentadas — sem precisar de uma lib para toast, outra para modal e outra para drawer. Com uma única instalação e API unificada, você tem acesso a um sistema coeso de comunicação com o usuário.
+
+Os componentes se comportam como **banners visuais ricos** — inspirados nos Alerts do Bootstrap, mas com glassmorphism, animações polidas, suporte a ações, filas de prioridade e muito mais.
+
+```js
+import vex from 'vexui'
+
+// Simples assim
+vex.alert.success('Arquivo salvo com sucesso!')
+
+// Ou com async/await
+const ok = await vex.modal.confirm({ title: 'Excluir projeto?', type: 'danger' })
+if (ok) await deleteProject(id)
+```
+
+---
+
+## Por que VexUI?
+
+| Funcionalidade | VexUI | Concorrentes |
+|---|---|---|
+| Alerts inline + fixed | ✅ Ambos, API única | Geralmente só um |
+| Modals Promise-based | ✅ `await` nativo | Callbacks / eventos |
+| Step Flow (wizard) | ✅ Built-in | ❌ Não existe |
+| Drawer / Side Panel | ✅ Built-in | ❌ Não existe |
+| Inline Prompt | ✅ Built-in | ❌ Não existe |
+| Alert ancorado a elemento | ✅ Built-in | ❌ Não existe |
+| Alert atualizável em tempo real | ✅ Built-in | ❌ Não existe |
+| Fila de prioridade | ✅ Built-in | ❌ Não existe |
+| Histórico de notificações | ✅ Built-in | ❌ Não existe |
+| Glassmorphism nativo | ✅ Padrão | ❌ Estilo genérico |
+| Dark / Light automático | ✅ `prefers-color-scheme` | ⚠️ Manual / limitado |
+| Theming por CSS tokens | ✅ 100% tokens | ⚠️ Parcial |
+| ARIA / Acessibilidade | ✅ Completo | ⚠️ Básico / ausente |
+| Zero dependências | ✅ Pure JS | ⚠️ Variado |
+
+---
+
+## Tecnologias
+
+### Core
+
+| Tecnologia | Versão | Uso |
+|---|---|---|
+| **JavaScript (ES2020+)** | — | Engine principal da biblioteca |
+| **CSS Custom Properties** | — | Sistema de tokens e temas |
+| **Web Animations API** | — | Animações performáticas |
+| **CSS `backdrop-filter`** | — | Efeito glassmorphism |
+| **`prefers-color-scheme`** | — | Dark/light mode automático |
+| **`prefers-reduced-motion`** | — | Respeito às preferências de acessibilidade |
+| **ARIA / WAI-ARIA 1.2** | — | Acessibilidade completa |
+
+### Build & Tooling
+
+| Ferramenta | Uso |
+|---|---|
+| **tsup** | Build e bundling (ESM, CJS, UMD) |
+| **TypeScript** | Tipos e declarações `.d.ts` |
+| **Vitest** | Testes unitários |
+| **Playwright** | Testes de integração / E2E |
+| **Changesets** | Versionamento semântico |
+| **np** | Publicação no npm |
+
+### Adapters (opcionais)
+
+| Adapter | Tecnologia |
+|---|---|
+| `vexui/react` | React 18+ (hook) |
+| `vex-ui-kit/vue` | Vue 3 (plugin + composable) |
+| `vex-ui-kit/svelte` | Svelte (store) |
+
+> **Zero dependências no core.** Os adapters para frameworks são opcionais e separados.
+
+---
+
+## Instalação
+
+```bash
+# npm
+npm install vexui
+
+# yarn
+yarn add vexui
+
+# pnpm
+pnpm add vexui
+```
+
+### Via CDN (sem instalação)
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vexui/dist/vexui.css">
+<script src="https://cdn.jsdelivr.net/npm/vexui/dist/vexui.umd.js"></script>
+
+<script>
+  VexUI.alert.success('Funciona em qualquer projeto!')
+</script>
+```
+
+### Importação no projeto
+
+```js
+// ES Modules (recomendado)
+import vex from 'vexui'
+import 'vexui/dist/vexui.css'
+
+// CommonJS
+const vex = require('vexui')
+```
+
+---
+
+## Estrutura de Arquivos
+
+```
+vexui/
+│
+├── src/                          # Código-fonte
+│   │
+│   ├── core/                     # Engine principal (zero deps)
+│   │   ├── alert.js              # Sistema de alerts
+│   │   ├── modal.js              # Sistema de modals
+│   │   ├── drawer.js             # Drawer / painel lateral
+│   │   ├── flow.js               # Step Flow (wizard)
+│   │   ├── queue.js              # Fila de prioridade
+│   │   ├── history.js            # Histórico de notificações
+│   │   ├── theme.js              # Gerenciador de temas
+│   │   ├── a11y.js               # Utilitários de acessibilidade
+│   │   └── index.js              # Entry point — exporta `vex`
+│   │
+│   ├── themes/                   # Temas prontos (CSS)
+│   │   ├── tokens.css            # CSS custom properties base
+│   │   ├── glass.css             # Glassmorphism (padrão)
+│   │   ├── flat.css              # Flat design
+│   │   ├── outline.css           # Apenas bordas
+│   │   ├── minimal.css           # Ultra-discreto
+│   │   ├── neon.css              # Neon / cyberpunk
+│   │   └── pastel.css            # Soft / tons pastel
+│   │
+│   └── adapters/                 # Integrações com frameworks
+│       ├── react.js              # useVex() hook
+│       ├── vue.js                # $vex plugin + useVex()
+│       └── svelte.js             # vex store
+│
+├── dist/                         # Build gerado (não editar)
+│   ├── vexui.esm.js              # ES Modules
+│   ├── vexui.cjs.js              # CommonJS
+│   ├── vexui.umd.js              # CDN / UMD (global VexUI)
+│   └── vexui.css                 # Estilos compilados
+│
+├── types/
+│   └── index.d.ts                # TypeScript declarations
+│
+├── tests/
+│   ├── unit/                     # Testes unitários (Vitest)
+│   └── e2e/                      # Testes E2E (Playwright)
+│
+├── docs/                         # Documentação
+│   └── README.md
+│
+├── package.json
+├── tsup.config.ts                # Config de build
+├── tsconfig.json
+└── LICENSE
+```
+
+---
+
+## Alerts
+
+O sistema de alerts é o núcleo da VexUI. Diferente de toasts que aparecem em cantos flutuantes, os alerts da VexUI são **banners ricos** — inline no fluxo da página ou fixos na viewport.
+
+### Tipos disponíveis
+
+```js
+vex.alert.success('Salvo com sucesso!')
+vex.alert.error('Falha ao conectar com o servidor')
+vex.alert.warning('Sessão expirando em 5 minutos')
+vex.alert.info('Nova atualização disponível')
+vex.alert.neutral('Rascunho salvo automaticamente')
+vex.alert.loading('Enviando arquivo...')  // com spinner animado
+```
+
+### Modos de posicionamento
+
+#### Inline — renderizado no DOM
+
+```js
+// Dentro de um container específico
+vex.alert.inline('#meu-formulario', {
+  type: 'error',
+  title: 'Erro de validação',
+  message: 'Preencha todos os campos obrigatórios.',
+})
+```
+
+#### Fixed — flutua na viewport
+
+```js
+// Topo da tela
+vex.alert.fixed({ position: 'top', type: 'success', message: 'Deploy finalizado!' })
+
+// Rodapé da tela
+vex.alert.fixed({ position: 'bottom', type: 'info', message: '2 novas mensagens.' })
+```
+
+#### Attached — ancorado a um elemento *(exclusivo)*
+
+```js
+// Aparece colado ao elemento, como um popover rico
+vex.alert.attach('#campo-senha', {
+  type: 'warning',
+  message: 'Senha fraca: use pelo menos 8 caracteres.',
+  placement: 'bottom',  // top | bottom | left | right | auto
+  duration: 0,
+})
+```
+
+### Alerts com botões de ação
+
+```js
+vex.alert.warning('Você tem alterações não salvas.', {
+  duration: 0,
+  actions: [
+    {
+      label: 'Salvar agora',
+      variant: 'primary',
+      onClick: (close) => { save(); close() }
+    },
+    {
+      label: 'Descartar',
+      variant: 'danger',
+      onClick: (close) => { discard(); close() }
+    },
+  ]
+})
+```
+
+### Alert de Loading atualizável *(exclusivo)*
+
+```js
+// Cria o alert e recebe um ID
+const id = vex.alert.loading('Enviando arquivo...')
+
+// Atualiza em tempo real conforme o processo avança
+vex.update(id, { message: 'Processando (45%)...' })
+vex.update(id, { message: 'Processando (90%)...' })
+
+// Transforma em sucesso ao finalizar
+vex.update(id, { type: 'success', message: 'Arquivo enviado com sucesso!' })
+```
+
+### Alert de Upload com progresso *(exclusivo)*
+
+```js
+const id = vex.alert.upload('Enviando documento.pdf', { total: file.size })
+
+upload.onprogress = (e) => {
+  vex.progress(id, { loaded: e.loaded, total: e.total })
+  // Exibe: "Enviando... 4.2 MB / 10 MB · ~8s restantes"
+}
+
+upload.onload = () => {
+  vex.update(id, { type: 'success', message: 'Upload concluído!' })
+}
+```
+
+### Fila de prioridade *(exclusivo)*
+
+```js
+// Alerts críticos entram imediatamente, deslocando os demais
+vex.alert.error('Servidor fora do ar', { priority: 'critical' })
+
+// Prioridade alta — entra na frente da fila
+vex.alert.warning('Sessão expirando', { priority: 'high' })
+
+// Prioridade baixa — só aparece quando a fila esvazia
+vex.alert.info('Dica do dia', { priority: 'low' })
+```
+
+### Todas as opções de Alert
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `type` | `string` | `'info'` | `success` · `error` · `warning` · `info` · `neutral` · `loading` |
+| `message` | `string` | — | Texto principal do alert |
+| `title` | `string` | `null` | Título em negrito acima da mensagem |
+| `duration` | `number` | `6000` | Tempo em ms. `0` = permanente |
+| `dismissible` | `boolean` | `true` | Botão × para fechar manualmente |
+| `icon` | `string \| null` | `auto` | Emoji, SVG string ou `null` para remover |
+| `progress` | `boolean` | `true` | Barra de progresso animada do tempo restante |
+| `actions` | `Action[]` | `[]` | Botões de ação dentro do alert |
+| `priority` | `string` | `'normal'` | `critical` · `high` · `normal` · `low` |
+| `position` | `string` | `'top'` | `top` · `bottom` — apenas para fixed |
+| `align` | `string` | `'center'` | `center` · `left` · `right` |
+| `animate` | `string` | `'slide'` | `slide` · `fade` · `scale` · `bounce` |
+| `maxStack` | `number` | `5` | Máximo de alerts simultâneos |
+| `theme` | `object` | preset | Sobrescreve tokens visuais desta instância |
+| `onClose` | `function` | `null` | Callback chamado ao fechar |
+
+---
+
+## Modals
+
+Todos os modals são **Promise-based** — retornam dados diretamente via `await`, eliminando callbacks aninhados.
+
+### Modal de Confirmação
+
+```js
+const ok = await vex.modal.confirm({
+  type: 'danger',                // danger | warning | info
+  title: 'Excluir projeto?',
+  message: 'Esta ação não pode ser desfeita. Todos os dados serão removidos permanentemente.',
+  confirmLabel: 'Sim, excluir',
+  cancelLabel: 'Cancelar',
+  confirmDelay: 3000,           // botão bloqueado por 3s (segurança extra)
+})
+
+if (ok) await deleteProject(id)
+```
+
+### Modal de Aviso / Informação
+
+```js
+await vex.modal.alert({
+  type: 'info',
+  title: 'Nova política de privacidade',
+  message: 'Atualizamos nossos termos em Janeiro de 2025...',
+  confirmLabel: 'Entendido',
+})
+```
+
+### Modal de Formulário
+
+```js
+const data = await vex.modal.form({
+  title: 'Convidar membro',
+  submitLabel: 'Enviar convite',
+  fields: [
+    { name: 'name',  label: 'Nome completo', type: 'text',     required: true },
+    { name: 'email', label: 'E-mail',         type: 'email',    required: true },
+    { name: 'role',  label: 'Função',         type: 'select',   options: ['Admin', 'Editor', 'Viewer'] },
+    { name: 'msg',   label: 'Mensagem',       type: 'textarea', optional: true },
+  ],
+  validate: (data) => {
+    if (!data.email.includes('@empresa.com'))
+      return { email: 'Use seu e-mail corporativo' }
+  }
+})
+
+if (data) await inviteMember(data)
+```
+
+**Tipos de campo suportados:**
+
+| Tipo | Descrição |
+|---|---|
+| `text`, `email`, `password`, `number`, `url`, `tel` | Inputs nativos |
+| `textarea` | Texto multilinha |
+| `select` | Dropdown |
+| `radio` | Grupo de opções exclusivas |
+| `checkbox` | Múltipla seleção |
+| `date`, `time`, `datetime-local` | Seletores de data/hora |
+| `file` | Upload com preview |
+| `range` | Slider numérico com label de valor |
+| `color` | Seletor de cor nativo |
+
+### Modal de Prompt
+
+```js
+const nome = await vex.modal.prompt({
+  title: 'Renomear arquivo',
+  placeholder: 'Ex: relatorio-final.pdf',
+  defaultValue: 'relatorio.pdf',
+  validate: (v) => v.trim().length < 3 ? 'Nome muito curto' : null
+})
+
+if (nome) await renameFile(nome)
+```
+
+### Modal de Preview de Mídia
+
+```js
+vex.modal.preview({
+  src: '/uploads/foto.jpg',
+  title: 'Foto do Produto',
+  meta: ['PNG · 4K', '3.8 MB', 'Jan 2025'],
+  zoom: true,
+  gallery: ['/img1.jpg', '/img2.jpg', '/img3.jpg'],  // navegação entre imagens
+  actions: [
+    { label: '⬇ Download', onClick: () => downloadFile() }
+  ],
+})
+```
+
+### Modal Customizado
+
+```js
+// Conteúdo completamente livre
+const { close } = vex.modal.custom({
+  title: 'Editor avançado',
+  content: document.getElementById('meu-editor'),  // elemento DOM ou HTML string
+  width: 800,
+  footer: false,
+})
+```
+
+### Opções comuns a todos os Modals
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `title` | `string` | — | Título do modal |
+| `type` | `string` | `'info'` | `danger` · `warning` · `info` · `success` |
+| `width` | `number` | `480` | Largura máxima em pixels |
+| `closeOnBackdrop` | `boolean` | `true` | Fecha ao clicar no backdrop |
+| `closeOnEscape` | `boolean` | `true` | Fecha ao pressionar Escape |
+| `showClose` | `boolean` | `true` | Botão × no canto superior direito |
+| `animate` | `string` | `'scale'` | `scale` · `slide` · `fade` |
+| `scrollLock` | `boolean` | `true` | Bloqueia scroll do body enquanto aberto |
+| `stackable` | `boolean` | `true` | Permite múltiplos modals sobrepostos |
+| `zIndex` | `number` | `9500` | z-index do backdrop |
+| `onOpen` | `function` | `null` | Callback ao abrir |
+| `onClose` | `function` | `null` | Callback ao fechar |
+
+---
+
+## Funcionalidades Exclusivas
+
+### Step Flow — Wizard multi-etapa *(exclusivo)*
+
+Fluxo guiado de múltiplas etapas dentro de um único modal. Cada etapa pode ter formulário próprio, validação e lógica condicional. Retorna todos os dados ao final.
+
+```js
+const result = await vex.flow([
+  {
+    title: 'Bem-vindo!',
+    type: 'info',
+    description: 'Vamos configurar sua conta em 3 passos simples.',
+  },
+  {
+    title: 'Seus dados',
+    fields: [
+      { name: 'name',  label: 'Nome',   type: 'text',  required: true },
+      { name: 'email', label: 'E-mail', type: 'email', required: true },
+    ],
+    // Valida antes de avançar
+    beforeNext: async (data) => {
+      const exists = await checkEmail(data.email)
+      if (exists) return { email: 'E-mail já cadastrado' }
+    }
+  },
+  {
+    title: 'Escolha seu plano',
+    fields: [
+      {
+        name: 'plan',
+        type: 'radio',
+        options: ['Starter (grátis)', 'Pro (R$49/mês)', 'Enterprise']
+      }
+    ]
+  },
+  // Etapa condicional — só aparece se escolheu Enterprise
+  {
+    title: 'Dados da empresa',
+    condition: (data) => data.plan === 'Enterprise',
+    fields: [
+      { name: 'company', label: 'Nome da empresa', type: 'text', required: true },
+      { name: 'cnpj',    label: 'CNPJ',            type: 'text' },
+    ]
+  },
+  {
+    title: 'Tudo pronto! 🎉',
+    type: 'success',
+    description: 'Sua conta foi configurada com sucesso.',
+  },
+])
+
+// result = { name, email, plan, company?, cnpj? }
+if (result) await createAccount(result)
+```
+
+**Funcionalidades do Step Flow:**
+- Barra de progresso visual com número da etapa atual
+- Navegação para frente e para trás livremente
+- Validação por etapa — não avança com erros
+- Dados acumulados e disponíveis em todas as etapas
+- Etapas condicionais baseadas em dados anteriores
+- `beforeNext()` para lógica assíncrona por etapa
+
+---
+
+### Drawer — Painel lateral *(exclusivo)*
+
+Painel deslizante que emerge da lateral sem bloquear a página. Ideal para filtros, formulários longos, detalhes de item e configurações.
+
+```js
+const { close } = vex.drawer({
+  title: 'Filtros avançados',
+  position: 'right',         // right | left | top | bottom
+  width: 420,                // para right/left (height para top/bottom)
+  content: '#filtros-form',  // seletor CSS ou elemento DOM
+  persistent: false,         // fecha ao clicar fora
+  footer: [
+    { label: 'Aplicar filtros', variant: 'primary', onClick: () => { apply(); close() } },
+    { label: 'Limpar tudo',                          onClick: () => clearAll() },
+  ],
+})
+```
+
+---
+
+### Inline Prompt — Edição contextual *(exclusivo)*
+
+Substitui um elemento de texto por um input diretamente no DOM, sem abrir modal. Perfeito para edição inline de títulos e valores.
+
+```js
+// O elemento #titulo vira um <input> na hora
+const novoNome = await vex.prompt.inline('#titulo-projeto', {
+  placeholder: 'Nome do projeto',
+  validate: (v) => v.trim().length > 0 ? null : 'Nome obrigatório'
+})
+
+if (novoNome) await renameProject(novoNome)
+```
+
+---
+
+### Histórico de Notificações *(exclusivo)*
+
+A VexUI mantém um registro interno de todos os alerts. Pode ser exibido como um painel de "sino de notificações".
+
+```js
+// Acesso programático
+const historico = vex.history.get()
+// [{ id, type, title, message, timestamp, read }, ...]
+
+vex.history.markAllRead()
+vex.history.clear()
+
+// Painel visual ancorado a um ícone
+vex.history.open('#icone-notificacoes')
+```
+
+---
+
+### Controle global
+
+```js
+// Remove tudo
+vex.dismissAll()
+
+// Com filtros
+vex.dismissAll({ type: 'error' })
+vex.dismissAll({ position: 'fixed' })
+
+// Fecha um alert/modal específico pelo ID retornado
+const id = vex.alert.loading('Processando...')
+vex.dismiss(id)
+
+// Configuração global padrão
+vex.configure({
+  duration: 5000,
+  position: 'top',
+  maxStack: 3,
+  animate: 'slide',
+})
+```
+
+---
+
+## Sistema de Temas
+
+### CSS Tokens (personalizável)
+
+```css
+/* Cole no seu CSS e sobrescreva o que precisar */
+:root {
+  /* Aparência geral */
+  --vex-radius:        14px;
+  --vex-blur:          20px;
+  --vex-shadow:        0 8px 32px rgba(0, 0, 0, 0.3);
+  --vex-border-width:  1px;
+  --vex-font:          inherit;
+  --vex-progress-h:    3px;
+
+  /* Cores por tipo */
+  --vex-success-bg:      rgba(5, 46, 22, 0.85);
+  --vex-success-border:  rgba(34, 197, 94, 0.35);
+  --vex-success-text:    #4ade80;
+  --vex-success-accent:  #22c55e;
+
+  --vex-error-bg:        rgba(40, 5, 5, 0.85);
+  --vex-error-border:    rgba(239, 68, 68, 0.35);
+  --vex-error-text:      #f87171;
+  --vex-error-accent:    #ef4444;
+
+  /* ... warning, info, neutral ... */
+}
+```
+
+### Temas prontos
+
+```js
+// Importar no seu CSS/JS
+import 'vexui/themes/glass'    // Glassmorphism (padrão)
+import 'vexui/themes/flat'     // Flat design, sem blur
+import 'vexui/themes/outline'  // Apenas bordas
+import 'vexui/themes/minimal'  // Ultra-discreto
+import 'vexui/themes/neon'     // Neon / cyberpunk
+import 'vexui/themes/pastel'   // Tons suaves
+```
+
+### Alternar Dark / Light
+
+```js
+vex.setTheme('dark')   // força dark
+vex.setTheme('light')  // força light
+vex.setTheme('auto')   // respeita o sistema (padrão)
+```
+
+### Tema por instância
+
+```js
+// Sobrescreve o visual apenas desta notificação
+vex.alert.success('Deploy OK!', {
+  theme: {
+    background:    'rgba(5, 46, 22, 0.95)',
+    border:        'rgba(34, 197, 94, 0.6)',
+    progressColor: '#4ade80',
+    borderRadius:  '20px',
+  }
+})
+```
+
+---
+
+## Acessibilidade
+
+Todos os componentes são construídos seguindo **WCAG 2.1 AA** e **WAI-ARIA 1.2**.
+
+| Recurso | Implementação |
+|---|---|
+| `role="alert"` | Alerts anunciados imediatamente por screen readers |
+| `role="dialog"` | Modals e Drawers com `aria-modal="true"` |
+| `aria-live` | Região de alerts com `polite` ou `assertive` por prioridade |
+| `aria-labelledby` | Título do modal vinculado corretamente |
+| `aria-describedby` | Mensagem vinculada ao elemento correto |
+| Focus trap | Foco preso dentro do modal; restaurado ao fechar |
+| Navegação por teclado | `Tab` / `Shift+Tab` entre ações; `Enter` confirma; `Esc` cancela |
+| Contraste | Mínimo de 4.5:1 em todos os temas (WCAG AA) |
+| `prefers-reduced-motion` | Animações desativadas; transições simples de opacidade |
+
+---
+
+## Integrações
+
+### Vanilla JavaScript
+
+```js
+import vex from 'vexui'
+import 'vexui/dist/vexui.css'
+
+vex.alert.success('Pronto!')
+```
+
+### React
+
+```jsx
+import { useVex } from 'vexui/react'
+
+function MeuComponente() {
+  const vex = useVex()
+
+  const handleDelete = async () => {
+    const ok = await vex.modal.confirm({
+      title: 'Excluir item?',
+      type: 'danger',
+    })
+    if (ok) deleteItem()
+  }
+
+  return <button onClick={handleDelete}>Excluir</button>
+}
+```
+
+### Vue 3
+
+```js
+// main.js
+import VexUI from 'vexui/vue'
+app.use(VexUI)
+```
+
+```vue
+<script setup>
+import { useVex } from 'vexui/vue'
+const vex = useVex()
+
+const confirmar = async () => {
+  const ok = await vex.modal.confirm({ title: 'Tem certeza?' })
+  if (ok) executar()
+}
+</script>
+```
+
+### CDN / Script tag
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vexui/dist/vexui.css">
+<script src="https://cdn.jsdelivr.net/npm/vexui/dist/vexui.umd.js"></script>
+
+<script>
+  VexUI.alert.success('Funciona em qualquer projeto!')
+</script>
+```
+
+---
+
+## API Completa
+
+### `vex.alert.*`
+
+| Método | Retorno | Descrição |
+|---|---|---|
+| `vex.alert.success(msg, opts?)` | `string` (id) | Alert de sucesso |
+| `vex.alert.error(msg, opts?)` | `string` (id) | Alert de erro |
+| `vex.alert.warning(msg, opts?)` | `string` (id) | Alert de aviso |
+| `vex.alert.info(msg, opts?)` | `string` (id) | Alert informativo |
+| `vex.alert.neutral(msg, opts?)` | `string` (id) | Alert neutro |
+| `vex.alert.loading(msg, opts?)` | `string` (id) | Alert com spinner; atualizável via `vex.update(id)` |
+| `vex.alert.upload(msg, opts?)` | `string` (id) | Alert com barra de progresso de upload |
+| `vex.alert.inline(selector, opts)` | `string` (id) | Renderiza dentro de um container |
+| `vex.alert.fixed(opts)` | `string` (id) | Renderiza fixo na viewport |
+| `vex.alert.attach(selector, opts)` | `string` (id) | Ancora a um elemento do DOM |
+| `vex.alert.show(opts)` | `string` (id) | Método base — aceita qualquer configuração |
+
+### `vex.modal.*`
+
+| Método | Retorno | Descrição |
+|---|---|---|
+| `vex.modal.confirm(opts)` | `Promise<boolean>` | Sim ou não |
+| `vex.modal.alert(opts)` | `Promise<void>` | Apenas fechar |
+| `vex.modal.form(opts)` | `Promise<object \| null>` | Dados do formulário |
+| `vex.modal.prompt(opts)` | `Promise<string \| null>` | Texto digitado |
+| `vex.modal.preview(opts)` | `void` | Preview de imagem / mídia |
+| `vex.modal.custom(opts)` | `{ close }` | Modal com HTML/DOM livre |
+
+### `vex.*` — Métodos globais
+
+| Método | Descrição |
+|---|---|
+| `vex.flow(steps[])` | Step Flow (wizard) multi-etapa |
+| `vex.drawer(opts)` | Abre painel lateral deslizante |
+| `vex.prompt.inline(selector, opts)` | Input contextual inline no DOM |
+| `vex.update(id, opts)` | Atualiza alert ativo em tempo real |
+| `vex.progress(id, { loaded, total })` | Atualiza progresso de upload |
+| `vex.dismiss(id)` | Fecha alert ou modal específico |
+| `vex.dismissAll(filter?)` | Fecha tudo (com filtro opcional) |
+| `vex.setTheme(theme)` | `'dark'` · `'light'` · `'auto'` |
+| `vex.configure(opts)` | Configura opções padrão globais |
+| `vex.history.get()` | Retorna histórico de notificações |
+| `vex.history.clear()` | Limpa o histórico |
+| `vex.history.markAllRead()` | Marca todas como lidas |
+| `vex.history.open(anchor)` | Abre painel visual de histórico |
+
+---
+
+## Roadmap
+
+| Versão | Nome | Entregas |
+|---|---|---|
+| **v1.0** | Core | Alerts (6 tipos) · Fixed & Inline · Modals (confirm, alert, form, prompt, preview, custom) · Glassmorphism · Progress bar · Queue · Dark/Light auto |
+| **v1.1** | Adapters | React hook · Vue 3 plugin · CDN build · Svelte store |
+| **v1.2** | Power Features | Step Flow · Drawer · Inline Prompt · Attached Alert · Upload progress · Histórico |
+| **v2.0** | Enterprise | 6 temas prontos · Painel de notificações built-in · i18n · TypeScript types completo · Storybook oficial |
+
+---
+
+## Licença
+
+MIT © VexUI
+
+---
+
+<div align="center">
+
+Feito com ❤️ — **[npm](https://npmjs.com/package/vexui)** · **[Documentação](https://vexui.dev)** · **[Changelog](./CHANGELOG.md)**
+
+</div>