npm package: @marlipe/dsze
Description: Design System universal do Zé Delivery - 16 componentes completos extraídos do Figma
Author: Zé Delivery
Latest version: 0.3.7

# @marlipe/dsze

> Design System universal do Zé Delivery para React Native e React Web

[![npm version](https://img.shields.io/npm/v/@marlipe/dsze.svg)](https://www.npmjs.com/package/@marlipe/dsze)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 📦 Instalação

```bash
# Yarn
yarn add @marlipe/dsze

# NPM
npm install @marlipe/dsze
```

### 🎉 Configuração Automática

Após a instalação, execute o setup interativo:

```bash
npx dsze-setup
```

O CLI **detecta automaticamente** seu framework e mostra as instruções de configuração necessárias:

- ✅ **Next.js**: Instruções para configurar `transpilePackages` e Turbopack
- ✅ **Vite**: Instruções para aliases e otimizações
- ✅ **React Native/Expo**: Pronto para uso, sem configuração extra!
- ✅ **Outros frameworks**: Documentação completa disponível

**📖 [Guia de Instalação Completo →](./INSTALACAO.md)**

---

## 🚀 Quick Start

### React Native

```tsx
import { Button, Icon, BeerBottleFilled, tokens } from '@marlipe/dsze'

function App() {
  return (
    <>
      <Button variant="primary" size="medium" onPress={() => console.log('Clicou!')}>
        Pedir Bebida
      </Button>
      
      <Icon icon={BeerBottleFilled} size="medium" color={tokens.color.zeYellow} />
    </>
  )
}
```

### React Web (Next.js, Vite, etc)

```tsx
'use client' // Apenas no Next.js

import { Button, Icon, BeerBottleFilled, tokens } from '@marlipe/dsze'

function App() {
  return (
    <div>
      <Button variant="primary" size="medium" onPress={() => console.log('Clicou!')}>
        Pedir Bebida
      </Button>
      
      <Icon icon={BeerBottleFilled} size="medium" color={tokens.color.zeYellow} />
    </div>
  )
}
```

---

## ⚙️ Configuração por Framework

### Next.js

O Next.js precisa transpilar pacotes React Native. Adicione ao seu arquivo de configuração:

#### next.config.js

```javascript
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Transpilar pacotes React Native para funcionar no Next.js
  transpilePackages: [
    '@marlipe/dsze',
    '@tamagui/core',
    'react-native-svg',
    'react-native-svg-web',
    'react-native-web',
  ],
  
  // Configuração para Turbopack (se usando next dev --turbo)
  experimental: {
    turbo: {
      resolveExtensions: [
        '.web.tsx',
        '.web.ts',
        '.web.jsx',
        '.web.js',
        '.tsx',
        '.ts',
        '.jsx',
        '.js',
      ],
    },
  },
}

module.exports = nextConfig
```

#### next.config.ts (TypeScript)

```typescript
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  transpilePackages: [
    '@marlipe/dsze',
    '@tamagui/core',
    'react-native-svg',
    'react-native-svg-web',
    'react-native-web',
  ],
  
  experimental: {
    turbo: {
      resolveExtensions: [
        '.web.tsx',
        '.web.ts',
        '.web.jsx',
        '.web.js',
        '.tsx',
        '.ts',
        '.jsx',
        '.js',
      ],
    },
  },
}

export default nextConfig
```

**Depois de adicionar a configuração:**

```bash
# Limpar cache
rm -rf .next

# Reiniciar servidor
npm run dev  # ou yarn dev
```

> 💡 **Lembre-se**: Use `'use client'` nos componentes que importam do DSZé quando usar App Router

**📖 [Guia Completo de Troubleshooting Next.js →](../../NEXTJS_TURBOPACK_FIX.md)**

---

## ⚙️ Configuração Vite

Adicione ao seu `vite.config.ts`:

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      'react-native': 'react-native-web',
      'react-native-svg': 'react-native-svg-web',
    },
  },
  optimizeDeps: {
    include: [
      '@marlipe/dsze',
      'react-native-web',
      'react-native-svg-web',
    ],
  },
})
```

**Instale as dependências:**

```bash
npm install react-native-web react-native-svg-web
```

---

## ⚙️ React Native / Expo

✅ **Pronto para uso!** Não precisa de configuração extra.

Basta importar e usar:

```tsx
import { Button, Icon, BeerBottleFilled } from '@marlipe/dsze'

function App() {
  return (
    <Button variant="primary" size="medium">
      Funciona direto!
    </Button>
  )
}
```

---

## ✨ Componentes Disponíveis

### 📊 Estatísticas

- **16 componentes completos** extraídos 100% do Figma
- **670+ variantes** implementadas
- **585 ícones** SVG (Filled + Outlined)
- **140+ stories** no Storybook
- **100% TypeScript** com type safety completo

---

### 🎯 Fundação (4 componentes)

#### Button
Botão universal com 4 variantes, 2 tamanhos e 5 estados

```tsx
<Button variant="primary" size="medium">Primary</Button>
<Button variant="secondary" size="small">Secondary</Button>
<Button variant="tertiary" disabled>Tertiary Disabled</Button>
<Button variant="danger" loading>Danger Loading</Button>
```

**Variantes:** `primary` | `secondary` | `tertiary` | `danger`  
**Tamanhos:** `medium` (48px) | `small` (40px)  
**Estados:** Normal, Hover, Focus, Active, Disabled

---

#### Icon
Componente de ícone com 6 tamanhos padronizados

```tsx
<Icon icon={BeerBottleFilled} size="medium" />
<Icon icon={CartOutlined} size="large" color={tokens.color.zeYellow} />
```

**Tamanhos:** `xsmall` (12px) | `small` (16px) | `medium` (24px) | `large` (32px) | `xlarge` (48px) | `xxlarge` (64px)

**Biblioteca de Ícones (585 ícones):**

```tsx
import {
  BeerBottleFilled, BeerBottleOutlined,
  CartFilled, CartOutlined,
  ArrowLeftFilled, ArrowRightOutlined,
  // ... 579 outros ícones
} from '@marlipe/dsze'
```

**Características:**
- ✅ Tree-shaking automático
- ✅ Filled + Outlined de cada ícone
- ✅ Otimizados para performance
- ✅ Universal (Native + Web)

---

#### Loading
Indicadores de carregamento com 2 variantes e 3 tamanhos

```tsx
<Loading variant="spinner" size="medium" />
<Loading variant="dots" size="small" color={tokens.color.zeYellow} />
```

**Variantes:** `spinner` | `dots`  
**Tamanhos:** `small` (24px) | `medium` (32px) | `large` (48px)

---

#### DismissButton
Botão de fechar/dismiss com 3 variantes e 2 tamanhos

```tsx
<DismissButton variant="default" size="medium" onPress={handleClose} />
<DismissButton variant="circle" size="small" />
```

**Variantes:** `default` | `circle` | `minimal`  
**Tamanhos:** `medium` (32px) | `small` (24px)

---

### 🎯 Interação (3 componentes)

#### ButtonIcon
Botões apenas com ícone

```tsx
<ButtonIcon 
  variant="primary" 
  size="medium" 
  icon={BeerBottleFilled}
  onPress={() => {}}
/>
```

**Variantes:** `primary` | `secondary` | `tertiary` | `danger`  
**Tamanhos:** `medium` (48px) | `small` (40px)

---

#### LinkAction
Links com ícones opcionais

```tsx
<LinkAction variant="default" size="medium" onPress={() => {}}>
  Ver mais detalhes
</LinkAction>
<LinkAction variant="icon" icon={ArrowRightOutlined}>
  Próximo
</LinkAction>
```

**Variantes:** `default` | `icon` | `underline`  
**Tamanhos:** `medium` | `small`

---

#### DropdownButton
Botões com indicador de dropdown

```tsx
<DropdownButton 
  variant="primary" 
  size="medium"
  onPress={() => {}}
  expanded={isOpen}
>
  Selecione uma opção
</DropdownButton>
```

**Variantes:** `primary` | `secondary` | `tertiary`  
**Estados:** Normal, Expanded, Disabled

---

### 🎯 Formulários (4 componentes)

#### InputSingle
Input de linha única com estados completos

```tsx
<InputSingle
  placeholder="Digite seu nome"
  value={value}
  onChangeText={setValue}
  error={hasError}
  disabled={false}
/>
```

**Estados:** Normal, Focus, Error, Disabled, Success

---

#### InputTextarea
Input multi-linha baseado no InputSingle

```tsx
<InputTextarea
  placeholder="Digite sua mensagem"
  value={message}
  onChangeText={setMessage}
  numberOfLines={4}
/>
```

---

#### InputSelect
Select customizado com dropdown

```tsx
<InputSelect
  placeholder="Selecione uma opção"
  value={selected}
  onValueChange={setSelected}
  options={[
    { label: 'Opção 1', value: '1' },
    { label: 'Opção 2', value: '2' }
  ]}
/>
```

---

#### InputField
Composição de input com label, helper e error

```tsx
<InputField
  label="Email"
  placeholder="seu@email.com"
  value={email}
  onChangeText={setEmail}
  helperText="Digite seu melhor email"
  errorText={emailError}
/>
```

---

### 🎯 Opções de Input (3 componentes)

#### Checkbox
Checkbox customizado com estados

```tsx
<Checkbox
  checked={isChecked}
  onCheckedChange={setIsChecked}
  label="Aceito os termos"
/>
```

**Estados:** Unchecked, Checked, Indeterminate, Disabled

---

#### RadioButton
Radio button para seleção única

```tsx
<RadioButton
  selected={isSelected}
  onPress={() => setSelected(true)}
  label="Opção 1"
/>
```

**Estados:** Unselected, Selected, Disabled

---

#### Toggle
Switch on/off

```tsx
<Toggle
  checked={isEnabled}
  onCheckedChange={setIsEnabled}
  size="medium"
/>
```

**Tamanhos:** `small` (32px) | `medium` (48px)

---

### 🎯 Listas (2 componentes)

#### ListMenuItem
Item individual de lista com variantes

```tsx
<ListMenuItem
  variant="text"
  title="Item de lista"
  description="Descrição do item"
  onPress={() => {}}
/>
```

**Variantes:** `text` | `leading` (com ícone) | `trailing` (com ação)

---

#### ListMenu
Container de lista com suporte a checkbox/radio

```tsx
<ListMenu variant="text">
  <ListMenuItem title="Item 1" />
  <ListMenuItem title="Item 2" />
  <ListMenuItem title="Item 3" />
</ListMenu>
```

**Variantes:** `text` | `leading` | `trailing` | `checkbox` | `radio`

---

### 🎯 Informativo (2 componentes)

#### Tag
Tags e badges informativos

```tsx
<Tag variant="default" size="medium">Nova</Tag>
<Tag variant="success" size="small">Concluído</Tag>
```

**Variantes:** `default` | `success` | `warning` | `error` | `info`  
**Tamanhos:** `small` | `medium` | `large`

---

#### CompoundTag
Tags compostas com ícone e texto

```tsx
<CompoundTag
  icon={BeerBottleFilled}
  label="Bebidas"
  variant="default"
/>
```

---

### 🎯 Tipografia (1 componente)

#### Text
Componente de texto com variants do design system

```tsx
<Text variant="displayLarge">Título Grande</Text>
<Text variant="bodyMedium">Texto do corpo</Text>
<Text variant="labelSmall">Label pequeno</Text>
```

**Variants:** `displayLarge` | `displayMedium` | `displaySmall` | `titleLarge` | `titleMedium` | `bodyLarge` | `bodyMedium` | `bodySmall` | `labelLarge` | `labelMedium` | `labelSmall`

## 🎨 Design Tokens

Todos os componentes usam design tokens extraídos do Figma:

```tsx
import { tokens } from '@marlipe/dsze'

// Cores
tokens.color.zeYellow      // #FFCC00
tokens.color.zeRed         // #DD0031
tokens.color.zeGreen       // #00A868

// Espaçamentos
tokens.space[8]            // 8px
tokens.space[16]           // 16px
tokens.space[24]           // 24px

// Tipografia
tokens.typography.fontSize.body.medium    // 16px
tokens.typography.lineHeight.body.medium  // 24px
tokens.typography.fontFamily.main         // 'Gelada'

// Border Radius
tokens.radius[8]           // 8px
tokens.radius.full         // 9999px
```

## 🎯 Características

- ✅ **16 Componentes Completos** - Todos extraídos 100% do Figma
- ✅ **Universal:** Funciona em React Native (iOS/Android) e React Web
- ✅ **TypeScript:** Totalmente tipado com inferência completa
- ✅ **Design Tokens:** 100% baseado no Figma (670+ variantes)
- ✅ **Tree-shaking:** Bundle otimizado (apenas o que você usa)
- ✅ **Acessível:** Props de acessibilidade em todos os componentes
- ✅ **Performático:** Otimizado com Tamagui
- ✅ **Documentado:** 140+ stories no Storybook
- ✅ **Fontes Inclusas:** Gelada RC3 + Roboto Flex
- ✅ **585 Ícones:** Biblioteca completa com tree-shaking

## 📐 Arquitetura

Este Design System é construído com:

- **[Tamagui](https://tamagui.dev/)** - Styled components universal
- **[React Native SVG](https://github.com/software-mansion/react-native-svg)** - Ícones universais
- **[React Native Web](https://necolas.github.io/react-native-web/)** - Compatibilidade web
- **TypeScript** - Type safety completo
- **Design Tokens** - Sistema único de tokens do Figma
- **Storybook** - Documentação interativa

## 📚 Documentação Completa

- **[Storybook](https://dsze-storybook.vercel.app)** - Playground interativo com 140+ stories
- **[Guia de Instalação](./INSTALACAO.md)** - Setup detalhado para Next.js, Vite e outros
- **[Changelog](./CHANGELOG.md)** - Histórico de versões
- **[Documentação Técnica](https://github.com/Design-for-Designers-Projects/DSZe/tree/main/_docs)** - Specs de cada componente

## 🔧 Configuração Avançada

### Tamagui Config (Next.js / React Web)

Para usar os componentes do DSZé com Tamagui, você precisa:

**1. Criar `tamagui.config.ts` na raiz do seu projeto:**

```typescript
import { defaultConfig } from '@tamagui/config/v4'
import { createTamagui } from 'tamagui'

const config = createTamagui(defaultConfig)

export default config

export type Conf = typeof config

declare module 'tamagui' {
  interface TamaguiCustomConfig extends Conf {}
}
```

**2. Criar `app/providers.tsx` (Next.js App Router):**

```typescript
'use client'

import { TamaguiProvider } from '@tamagui/core'
import config from '../tamagui.config'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <TamaguiProvider config={config}>
      {children}
    </TamaguiProvider>
  )
}
```

**3. Atualizar `app/layout.tsx`:**

```typescript
import { Providers } from './providers'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  )
}
```

> 📝 **Nota**: React Native/Expo não precisa de TamaguiProvider, funciona direto!

### Peer Dependencies

```json
{
  "react": ">=18.0.0",
  "react-native": ">=0.72.0"
}
```

## 🤝 Contribuindo

Contributions, issues e feature requests são bem-vindos!

1. Fork o projeto
2. Crie uma branch: `git checkout -b feature/nova-feature`
3. Commit suas mudanças: `git commit -m 'feat: adiciona nova feature'`
4. Push para a branch: `git push origin feature/nova-feature`
5. Abra um Pull Request

Veja o [Guia de Contribuição](https://github.com/ze-delivery/ds-ze#contributing) para mais detalhes.

## 📝 Changelog

Veja o [CHANGELOG.md](./CHANGELOG.md) para histórico de versões.

## 📄 Licença

MIT © [Zé Delivery](https://www.ze.delivery)

---

## 🔗 Links Úteis

- [Repositório no GitHub](https://github.com/Design-for-Designers-Projects/DSZe)
- [Pacote no NPM](https://www.npmjs.com/package/@marlipe/dsze)
- [Storybook](https://dsze-storybook.vercel.app)
- [Documentação Técnica](https://github.com/Design-for-Designers-Projects/DSZe/tree/main/_docs)

---

Feito com ❤️ pelo time Zé Delivery