birus-ui 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,233 @@
-# Temporary Holding Version
+# birusUI — Design System & Component Library (Vue 3)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**32 componentes reutilizáveis e acessíveis construídos do zero em JavaScript puro para Vue 3.**  
+Temas reativos em tempo real • Escala tipográfica modular • Zero dependências headless externas • Fácil customização
+
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Apoiar%20o%20Projeto-BD5FFF?style=for-the-badge&logo=buy-me-a-coffee&logoColor=FFDD00)](https://www.buymeacoffee.com/gabrielreis)
+![Vue 3](https://img.shields.io/badge/Vue-3.4+-4FC08D?style=for-the-badge&logo=vuedotjs&logoColor=white)
+![Pure JS](https://img.shields.io/badge/JavaScript-ES%20Modules-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black)
+![MIT License](https://img.shields.io/badge/License-MIT-7C3AED?style=for-the-badge)
+
+---
+
+## 1. Instalação & Configuração Rápida
+
+```bash
+npm install birus-ui
+```
+
+### Opção A: Registro Global (`main.js`)
+Disponibiliza todas as 32 tags `<Birus... />` automaticamente na sua aplicação:
+
+```js
+import { createApp } from 'vue';
+import App from './App.vue';
+
+// 1. Importe o pacote e o CSS pré-compilado (funciona mesmo sem Tailwind!)
+import BirusUI, { initBirusTheme } from 'birus-ui';
+import 'birus-ui/style.css';
+
+// 2. (Opcional) Inicialize o tema da sua aplicação
+initBirusTheme({
+  palette: 'birus',   // 'birus' | 'emerald' | 'ocean' | 'rose' | 'amber' | 'zinc'
+  mode: 'dark',       // 'dark' | 'light'
+  radius: 'md',       // 'none' | 'sm' | 'md' | 'lg' | 'full'
+  font: 'inter',      // 'inter' | 'jakarta' | 'grotesk' | 'editorial' | 'mono'
+});
+
+const app = createApp(App);
+app.use(BirusUI);
+app.mount('#app');
+```
+
+### Opção B: Importação Individual (Tree-Shaking por componente)
+
+```vue
+<script setup>
+import 'birus-ui/style.css';
+import { BirusButton, BirusCard, BirusBadge } from 'birus-ui';
+</script>
+
+<template>
+  <BirusCard title="Bem-vindo ao birusUI" badge="v0.3">
+    <BirusButton variant="glow">Começar Agora</BirusButton>
+  </BirusCard>
+</template>
+```
+
+---
+
+## 2. Como Customizar Temas, Cores, Fontes e Bordas (4 Níveis)
+
+### Nível 1: Trocar Tema em Tempo Real com `useBirusTheme()`
+
+```vue
+<script setup>
+import { useBirusTheme } from 'birus-ui';
+
+const {
+  theme,            // Estado reativo atual: { palette, mode, radius, font, tokens }
+  palettes,         // Lista das 6 paletas disponíveis
+  fonts,            // Lista das 5 famílias de fontes
+  radii,            // Lista dos 5 tamanhos de arredondamento
+  setPalette,       // Ex: setPalette('emerald')
+  setMode,          // Ex: setMode('light') ou setMode('dark')
+  toggleMode,       // Alterna entre 'dark' e 'light'
+  setRadius,        // Ex: setRadius('lg')
+  setFont,          // Ex: setFont('editorial')
+  setCustomTokens,  // Sobrescreve cores em tempo real usando HEX ou HSL
+  resetTheme,       // Restaura para o padrão
+} = useBirusTheme();
+</script>
+
+<template>
+  <BirusButton variant="outline" @click="toggleMode">
+    Modo atual: {{ theme.mode }}
+  </BirusButton>
+</template>
+```
+
+### Nível 2: Passar Suas Próprias Cores em HEX (`#RRGGBB`) via JavaScript
+
+```js
+import { initBirusTheme } from 'birus-ui';
+
+initBirusTheme({
+  palette: 'birus',
+  mode: 'dark',
+  radius: 'lg',
+  tokens: {
+    primary: '#BD5FFF',      // Aceita HEX diretamente!
+    primaryFg: '#FFFFFF',
+    info: '#38BDF8',
+    success: '#10B981',
+    warning: '#F59E0B',
+    destructive: '#EF4444',
+    radius: '14px',
+  },
+});
+```
+
+### Nível 3: Registrar uma Nova Paleta Completa (`registerBirusPalette`)
+
+```js
+import { registerBirusPalette, initBirusTheme, hexToHslChannels } from 'birus-ui';
+
+registerBirusPalette('minha-marca', {
+  name: 'Minha Marca',
+  description: 'Identidade visual corporativa',
+  swatchHex: '#FF3366',
+  dark: {
+    primary: hexToHslChannels('#FF3366'),
+    primaryFg: hexToHslChannels('#FFFFFF'),
+    ring: hexToHslChannels('#FF3366'),
+  },
+  light: {
+    primary: hexToHslChannels('#E11D48'),
+    primaryFg: hexToHslChannels('#FFFFFF'),
+    ring: hexToHslChannels('#E11D48'),
+  },
+});
+
+initBirusTheme({ palette: 'minha-marca', mode: 'dark' });
+```
+
+### Nível 4: Sobrescrever Estilo de Qualquer Componente com a Prop `class`
+
+Todos os 32 componentes usam `cn()` (`clsx` + `tailwind-merge`), permitindo sobrescrever qualquer classe utilitária sem conflito:
+
+```vue
+<BirusButton class="bg-pink-600 hover:bg-pink-500 rounded-none px-10 shadow-xl">
+  Botão Customizado
+</BirusButton>
+```
+
+#### (Opcional) Preset para Tailwind CSS
+
+```js
+// tailwind.config.js
+import { birusTailwindPreset } from 'birus-ui/tailwind-preset';
+
+export default {
+  presets: [birusTailwindPreset],
+  content: [
+    './index.html',
+    './src/**/*.{vue,js,jsx}',
+    './node_modules/birus-ui/dist/**/*.js',
+  ],
+};
+```
+
+---
+
+## 3. Catálogo dos 32 Componentes
+
+### Tipografia & Fundações (3)
+| Componente | Descrição | Props Principais |
+| :--- | :--- | :--- |
+| `<BirusHeading>` | Títulos semânticos (`h1`–`h6`) com escala modular | `as`, `size` (`'xs'`..`'display'`), `weight`, `gradient`, `accentLine`, `align` |
+| `<BirusText>` | Corpo de texto, leads, legendas, citações e código | `variant` (`'body'`, `'lead'`, `'small'`, `'overline'`, `'quote'`, `'code'`), `tone`, `clamp` |
+| `<BirusSeparator>` | Divisor horizontal ou vertical com rótulo opcional | `orientation`, `variant` (`'solid'`, `'dashed'`, `'gradient'`), `label` |
+
+### Ações & Feedback (5)
+| Componente | Descrição | Props Principais |
+| :--- | :--- | :--- |
+| `<BirusButton>` | Botão com 8 variantes, loading, ícones e atalho | `variant` (`'default'`, `'secondary'`, `'outline'`, `'ghost'`, `'destructive'`, `'success'`, `'link'`, `'glow'`), `size`, `loading`, `pill`, `block`, `shortcut` |
+| `<BirusBadge>` | Etiqueta de status com indicador dot e botão remover | `variant`, `size`, `dot`, `removable` (`@remove`) |
+| `<BirusAlert>` | Caixa de alerta semântica com suporte a fechamento | `variant` (`'info'`, `'success'`, `'warning'`, `'destructive'`), `title`, `description`, `dismissible` |
+| `<BirusToaster>` | Sistema global de notificações Toast via `useToast()` | `position` (`'bottom-right'`, `'top-right'`, `'bottom-left'`, `'top-center'`) |
+| `<BirusKbd>` | Visualizador de teclas e atalhos de teclado | `keys` (`'Ctrl + K'`), `variant`, `size` |
+
+### Formulários & Inputs (7)
+| Componente | Descrição | Props Principais |
+| :--- | :--- | :--- |
+| `<BirusInput>` | Campo de texto com prefixo, sufixo, limpar e senha | `v-model`, `type`, `label`, `hint`, `errorMessage`, `state`, `prefixText`, `suffixText`, `clearable` |
+| `<BirusTextarea>` | Área de texto com auto-resize e contador | `v-model`, `label`, `rows`, `maxlength`, `autoResize`, `state` |
+| `<BirusSelect>` | Dropdown customizado com busca embutida e teclado | `v-model`, `options` (`[{ value, label, description }]`), `searchable`, `clearable` |
+| `<BirusRadioGroup>` | Seleção única em formato de cartões ricos ou lista | `v-model`, `options` (`[{ value, label, badge, description }]`), `variant` (`'cards'` \| `'list'`) |
+| `<BirusSlider>` | Controle deslizante com barra preenchida e sufixo | `v-model`, `min`, `max`, `step`, `variant`, `valueSuffix` |
+| `<BirusSwitch>` | Interruptor acessível (`role="switch"`) | `v-model`, `label`, `description`, `size`, `disabled` |
+| `<BirusCheckbox>` | Caixa de seleção com suporte a `indeterminate` | `v-model`, `indeterminate`, `label`, `description`, `size` |
+
+### Layout & Conteúdo (3)
+| Componente | Descrição | Props Principais |
+| :--- | :--- | :--- |
+| `<BirusCard>` | Container modular com 6 superfícies e slots | `variant` (`'default'`, `'elevated'`, `'glass'`, `'interactive'`, `'outline'`, `'featured'`), `accentTop`, `title`, `description`, `badge` |
+| `<BirusAccordion>` | Seções expansíveis no modo único ou múltiplo | `items` (`[{ id, title, subtitle, content }]`), `type` (`'single'` \| `'multiple'`), `variant` |
+| `<BirusEmptyState>` | Placeholder estruturado para listas ou buscas vazias | `title`, `description`, `variant` (`'default'`, `'dashed'`, `'compact'`), slots `#icon`, `#actions` |
+
+### Sobreposição & Navegação (8)
+| Componente | Descrição | Props Principais |
+| :--- | :--- | :--- |
+| `<BirusDialog>` | Janela modal Teleportada com bloqueio de scroll | `v-model`, `size` (`'sm'`..`'xl'`), `title`, `description`, `closeOnOverlay` |
+| `<BirusDrawer>` | Painel lateral/superior/inferior deslizante (Sheet) | `v-model`, `side` (`'right'`, `'left'`, `'top'`, `'bottom'`), `size`, `title` |
+| `<BirusDropdownMenu>` | Menu contextual com cabeçalhos, divisores e atalhos | `items`, `align`, `triggerLabel`, `@select` |
+| `<BirusTabs>` | Abas WAI-ARIA com navegação por setas do teclado | `v-model`, `tabs` (`[{ value, label, badge }]`), `variant` (`'segmented'`, `'underline'`, `'pills'`) |
+| `<BirusStepper>` | Indicador de passos sequenciais (Wizard) | `v-model` (índice `0..N`), `steps` (`[{ title, description }]`), `orientation`, `clickable` |
+| `<BirusBreadcrumb>` | Trilha de navegação hierárquica | `items` (`[{ label, value, current }]`), `separator` (`'chevron'`, `'slash'`, `'dot'`) |
+| `<BirusPagination>` | Paginação com truncamento inteligente | `v-model`, `totalPages`, `siblingCount`, `variant` |
+| `<BirusTooltip>` | Dica flutuante ativada por hover e foco | `content`, `position` (`'top'`, `'bottom'`, `'left'`, `'right'`) |
+
+### Dados & Carregamento (6)
+| Componente | Descrição | Props Principais |
+| :--- | :--- | :--- |
+| `<BirusStatCard>` | Cartão executivo de KPI com tendência e meta | `label`, `value`, `trend` (`'+18%'`), `trendDirection` (`'up'`, `'down'`, `'neutral'`), `progress`, `caption` |
+| `<BirusTable>` | Tabela de dados com ordenação por coluna e slots | `columns` (`[{ key, label, sortable }]`), `rows`, `density`, `striped`, slot `#cell-<key>` |
+| `<BirusTimeline>` | Linha do tempo cronológica com status semânticos | `items` (`[{ title, description, time, badge, status }]`) |
+| `<BirusAvatar>` | Avatar com fallback de iniciais e presença | `src`, `name`, `size` (`'xs'`..`'xl'`), `shape`, `status` (`'online'`, `'busy'`, `'away'`, `'offline'`) |
+| `<BirusProgress>` | Barra de progresso determinada ou indeterminada | `value`, `max`, `variant`, `indeterminate`, `label`, `showValue` |
+| `<BirusSkeleton>` | Placeholders pulsantes para carregamento | `variant` (`'text'`, `'circle'`, `'rect'`, `'card'`), `lines` |
+
+---
+
+## 4. Apoie o Projeto (Buy Me a Coffee) ☕
+
+Criado por **Gabriel Reis**. Se o **birusUI** ajudou no seu projeto ou economizou horas de desenvolvimento, considere apoiar com um café:
+
+👉 **[https://www.buymeacoffee.com/gabrielreis](https://www.buymeacoffee.com/gabrielreis)**
+
+---
+
+## Licença
+
+MIT © Gabriel Reis