npm package: @lumencrm/design-system
Description: LumenCRM Design System - Atomic Design components with theming support
Author: Multiluz Solar
Latest version: 1.0.0

# @lumencrm/design-system

Design System do LumenCRM construído com **Atomic Design** e suporte completo a **theming via CSS Variables**.

Perfeito para projetos multi-tenant onde cada instância precisa de sua própria identidade visual.

## Instalação

### NPM (Publicado)
```bash
npm install @lumencrm/design-system
```

### Workspace Local (Desenvolvimento)
```bash
# No package.json do seu projeto
{
  "dependencies": {
    "@lumencrm/design-system": "workspace:*"
  }
}
```

### Link Local
```bash
cd packages/design-system
npm link

cd seu-projeto
npm link @lumencrm/design-system
```

## Uso Básico

### 1. Importar Estilos

Importe o CSS no seu arquivo principal (main.tsx, App.tsx, etc):

```typescript
// main.tsx ou App.tsx
import '@lumencrm/design-system/styles'
```

### 2. Usar Componentes

```typescript
import { Button, Card, Input, FormField, Text } from '@lumencrm/design-system'

function App() {
  return (
    <Card title="Bem-vindo" variant="elevated">
      <Text variant="h2">Olá Mundo</Text>

      <FormField label="Nome" id="name">
        <Input
          id="name"
          placeholder="Digite seu nome"
        />
      </FormField>

      <Button variant="primary" size="medium">
        Enviar
      </Button>
    </Card>
  )
}
```

## Componentes Disponíveis

### Atoms (Básicos)

#### Button
```typescript
import { Button } from '@lumencrm/design-system'

<Button variant="primary" size="medium" onClick={() => alert('Clicou!')}>
  Clique Aqui
</Button>
```
**Props**: `variant`, `size`, `disabled`, `onClick`, `children`, `type`

#### Input
```typescript
import { Input } from '@lumencrm/design-system'

<Input
  placeholder="Digite algo"
  type="text"
  value={value}
  onChange={(e) => setValue(e.target.value)}
/>
```
**Props**: `type`, `placeholder`, `value`, `onChange`, `disabled`, `id`

#### Label
```typescript
import { Label } from '@lumencrm/design-system'

<Label htmlFor="email" required>
  E-mail
</Label>
```
**Props**: `htmlFor`, `required`, `children`

#### Text
```typescript
import { Text } from '@lumencrm/design-system'

<Text variant="h1">Título Principal</Text>
<Text variant="body">Texto normal</Text>
<Text variant="caption" color="secondary">Texto pequeno</Text>
```
**Props**: `variant`, `color`, `align`, `children`

#### Icon
```typescript
import { Icon } from '@lumencrm/design-system'

<Icon name="user" size="medium" color="primary" />
```
**Props**: `name`, `size`, `color`

### Molecules (Compostos)

#### FormField
Combina Label + Input com tratamento de erros:

```typescript
import { FormField } from '@lumencrm/design-system'

<FormField
  label="E-mail"
  id="email"
  error="E-mail inválido"
  required
>
  <Input
    id="email"
    type="email"
    placeholder="seu@email.com"
  />
</FormField>
```
**Props**: `label`, `id`, `error`, `required`, `children`

#### Card
Container estilizado com título e ações:

```typescript
import { Card } from '@lumencrm/design-system'

<Card
  title="Informações do Usuário"
  subtitle="Dados pessoais"
  variant="elevated"
  actions={<Button size="small">Editar</Button>}
>
  <p>Conteúdo do card...</p>
</Card>
```
**Props**: `title`, `subtitle`, `variant`, `actions`, `children`

#### SearchBar
Barra de busca com ícone:

```typescript
import { SearchBar } from '@lumencrm/design-system'

<SearchBar
  placeholder="Buscar clientes..."
  value={searchTerm}
  onSearch={(value) => setSearchTerm(value)}
/>
```
**Props**: `placeholder`, `value`, `onSearch`

### Organisms (Complexos)

#### Header
Cabeçalho da aplicação:

```typescript
import { Header } from '@lumencrm/design-system'

<Header
  user={{
    name: 'João Silva',
    email: 'joao@empresa.com',
    avatar: '/avatar.jpg'
  }}
  onLogout={() => handleLogout()}
/>
```
**Props**: `user`, `onLogout`

#### Sidebar
Menu lateral de navegação:

```typescript
import { Sidebar } from '@lumencrm/design-system'

<Sidebar
  isCollapsed={false}
  onToggle={() => setCollapsed(!collapsed)}
  items={[
    { label: 'Dashboard', icon: 'home', path: '/' },
    { label: 'Clientes', icon: 'users', path: '/clientes' }
  ]}
/>
```
**Props**: `isCollapsed`, `onToggle`, `items`

#### DataTable
Tabela de dados com ordenação:

```typescript
import { DataTable } from '@lumencrm/design-system'

const columns = [
  { key: 'id', label: 'ID', sortable: true },
  { key: 'name', label: 'Nome', sortable: true },
  { key: 'email', label: 'E-mail' }
]

const data = [
  { id: 1, name: 'João', email: 'joao@teste.com' },
  { id: 2, name: 'Maria', email: 'maria@teste.com' }
]

<DataTable
  columns={columns}
  data={data}
  onSort={(key, direction) => handleSort(key, direction)}
/>
```
**Props**: `columns`, `data`, `onSort`

#### Modal
Modal/Dialog para conteúdo sobreposto:

```typescript
import { Modal } from '@lumencrm/design-system'

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Confirmar Ação"
  actions={
    <>
      <Button variant="secondary" onClick={() => setIsOpen(false)}>
        Cancelar
      </Button>
      <Button variant="primary" onClick={handleConfirm}>
        Confirmar
      </Button>
    </>
  }
>
  <p>Tem certeza que deseja continuar?</p>
</Modal>
```
**Props**: `isOpen`, `onClose`, `title`, `actions`, `children`

### Templates (Layouts)

#### DashboardTemplate
Layout completo com Header + Sidebar:

```typescript
import { DashboardTemplate } from '@lumencrm/design-system'

<DashboardTemplate
  user={{
    name: 'João Silva',
    email: 'joao@empresa.com'
  }}
  onLogout={handleLogout}
  navigationItems={[
    { label: 'Dashboard', icon: 'home', path: '/' },
    { label: 'Clientes', icon: 'users', path: '/clientes' }
  ]}
>
  {/* Conteúdo da página */}
  <h1>Dashboard</h1>
</DashboardTemplate>
```
**Props**: `user`, `onLogout`, `navigationItems`, `children`

#### FormTemplate
Layout centralizado para formulários:

```typescript
import { FormTemplate } from '@lumencrm/design-system'

<FormTemplate
  title="Login"
  subtitle="Entre com suas credenciais"
  logo="/logo.png"
  onSubmit={handleLogin}
>
  <FormField label="E-mail" id="email">
    <Input id="email" type="email" />
  </FormField>

  <FormField label="Senha" id="password">
    <Input id="password" type="password" />
  </FormField>

  <Button type="submit" variant="primary" fullWidth>
    Entrar
  </Button>
</FormTemplate>
```
**Props**: `title`, `subtitle`, `logo`, `onSubmit`, `children`

## Theming (CSS Variables)

O Design System usa **CSS Variables** para permitir customização completa via `.env`.

### Variáveis Disponíveis

```css
/* Cores Principais */
--color-primary
--color-primary-light
--color-primary-dark
--color-secondary
--color-secondary-light
--color-secondary-dark

/* Cores Semânticas */
--color-error
--color-warning
--color-info
--color-success

/* Cores de Interface */
--color-background
--color-surface
--color-text-primary
--color-text-secondary

/* Configurações */
--border-radius
--font-family
```

### Exemplo de Customização

```typescript
// ThemeProvider.tsx (seu projeto)
import { useEffect } from 'react'

export const ThemeProvider = ({ children }) => {
  useEffect(() => {
    const root = document.documentElement

    // Cores do .env
    root.style.setProperty('--color-primary', '#1d3b9e')
    root.style.setProperty('--color-secondary', '#F97316')
    root.style.setProperty('--border-radius', '8px')
    // ... outras variáveis
  }, [])

  return <>{children}</>
}
```

### Usar no CSS

```css
.meu-componente {
  background-color: var(--color-primary);
  color: white;
  border-radius: var(--border-radius);
}

.meu-botao:hover {
  background-color: var(--color-primary-dark);
}
```

## Build da Biblioteca

### Desenvolvimento (watch mode)
```bash
cd packages/design-system
npm run dev
```

### Build de Produção
```bash
npm run build
```

Isso gera:
- `dist/index.mjs` - Build ESM
- `dist/index.js` - Build CommonJS
- `dist/index.d.ts` - TypeScript types
- `dist/style.css` - Estilos compilados

## Publicação

### NPM Registry
```bash
cd packages/design-system

# Login no NPM
npm login

# Publicar
npm publish --access public
```

### Registry Privado (Verdaccio)
```bash
npm publish --registry http://seu-registry.com
```

### GitHub Packages
```bash
npm publish --registry https://npm.pkg.github.com
```

## TypeScript

A biblioteca inclui **type definitions completas**. O autocomplete funcionará automaticamente:

```typescript
import { Button, Card, type ButtonProps } from '@lumencrm/design-system'

const props: ButtonProps = {
  variant: 'primary', // ✅ Autocomplete funciona
  size: 'large',
  onClick: () => {}
}

<Button {...props}>Click</Button>
```

## Peer Dependencies

A biblioteca requer:
- `react: ^19.0.0`
- `react-dom: ^19.0.0`

Certifique-se de tê-los instalados no seu projeto.

## Estrutura do Pacote

```
@lumencrm/design-system/
├── dist/
│   ├── index.mjs          # ESM build
│   ├── index.js           # CommonJS build
│   ├── index.d.ts         # TypeScript types
│   └── style.css          # Estilos compilados
├── src/
│   ├── atoms/             # Componentes básicos
│   ├── molecules/         # Compostos simples
│   ├── organisms/         # Componentes complexos
│   ├── templates/         # Layouts
│   └── index.ts           # Exports centralizados
└── package.json
```

## Exemplos de Uso

### Micro Frontend 1 - Clientes
```typescript
// clientes-app/src/main.tsx
import '@lumencrm/design-system/styles'
import { DashboardTemplate, Card, DataTable } from '@lumencrm/design-system'

function ClientesApp() {
  return (
    <DashboardTemplate {...layoutProps}>
      <Card title="Lista de Clientes">
        <DataTable columns={columns} data={clientes} />
      </Card>
    </DashboardTemplate>
  )
}
```

### Micro Frontend 2 - Vendas
```typescript
// vendas-app/src/main.tsx
import '@lumencrm/design-system/styles'
import { DashboardTemplate, Card, Button } from '@lumencrm/design-system'

function VendasApp() {
  return (
    <DashboardTemplate {...layoutProps}>
      <Card title="Painel de Vendas">
        <Button variant="primary">Nova Venda</Button>
      </Card>
    </DashboardTemplate>
  )
}
```

Ambos os apps compartilham o mesmo Design System e theming!

## Vantagens

✅ **Consistência**: Mesmos componentes em todos os micro projetos
✅ **Theming**: CSS Variables para customização total
✅ **Type-Safe**: TypeScript completo com autocomplete
✅ **Tree-Shaking**: Importa apenas o que usar
✅ **Performance**: Build otimizado com Vite
✅ **Multi-Tenant**: Cada Docker com suas cores

## Licença

MIT

## Suporte

Para dúvidas ou problemas, abra uma issue no repositório.