@tabl.io/ui 0.1.1 → 0.2.0

package/README.md

@@ -1,73 +1,311 @@
-# React + TypeScript + Vite
+# 🎨 Tabl UI - Design System Components
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+Sistema de componentes React para as aplicações Tabl (PDV, KDS, Manager).
 
-Currently, two official plugins are available:
+## Storybook
+Acesse a documentação visual dos componentes:
+[README.stories.md](./README.stories.md)
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+## 📦 Estrutura dos Arquivos
 
-## React Compiler
+```
+src/
+├── components/
+│   └── app/
+│       ├── layout/          # Componentes de layout
+│       │   ├── app-header.tsx
+│       │   ├── cart-indicator.tsx
+│       │   ├── quantity-stepper.tsx
+│       │   └── index.ts
+│       ├── table/           # Componentes de mesa
+│       │   ├── table-grid.tsx
+│       │   ├── table-card.tsx
+│       │   ├── table-badge.tsx
+│       │   └── index.ts
+│       ├── category/        # Componentes de categoria
+│       │   ├── category-tabs.tsx
+│       │   ├── category-pill.tsx
+│       │   └── index.ts
+│       ├── product/         # Componentes de produto
+│       │   ├── product-grid.tsx
+│       │   ├── product-card.tsx
+│       │   ├── product-price-display.tsx
+│       │   ├── product-detail-modal.tsx
+│       │   ├── ingredient-list.tsx
+│       │   ├── ingredient-checkbox.tsx
+│       │   ├── extra-checkbox.tsx
+│       │   └── index.ts
+│       ├── cart/            # Componentes de carrinho
+│       │   ├── cart-sheet.tsx
+│       │   ├── cart-item.tsx
+│       │   ├── cart-summary.tsx
+│       │   ├── cart-empty-state.tsx
+│       │   └── index.ts
+│       ├── order/           # Componentes de pedido
+│       │   ├── order-confirmation-modal.tsx
+│       │   ├── order-loading-state.tsx
+│       │   └── index.ts
+│       └── index.ts
+├── lib/
+│   └── format.ts            # Helpers de formatação
+└── foundation/
+    └── tokens.css           # Sistema de tokens modulares
+```
+
+## 🎯 Instalação dos Componentes Shadcn
+
+Execute no terminal do pacote @tabl.io/ui:
+
+```bash
+# Componentes primitivos necessários
+npx shadcn@latest add card
+npx shadcn@latest add badge
+npx shadcn@latest add dialog
+npx shadcn@latest add sheet
+npx shadcn@latest add scroll-area
+npx shadcn@latest add separator
+npx shadcn@latest add skeleton
+npx shadcn@latest add sonner
+npx shadcn@latest add checkbox
+npx shadcn@latest add label
+```
+
+## 🔧 Configuração
+
+### 1. Substituir `src/foundation/tokens.css`
+
+Copie o novo arquivo `tokens.css` para `src/foundation/tokens.css`.
+
+Este arquivo adiciona suporte a temas por módulo usando o atributo `data-module`:
+- `data-module="core"` → Verde (Emerald)
+- `data-module="pdv"` → Laranja (Orange)
+- `data-module="kds"` → Azul (Blue)
+- `data-module="manager"` → Roxo (Violet)
+- `data-module="analytics"` → Âmbar (Amber)
+
+### 2. Adicionar `src/lib/format.ts`
+
+Copie o arquivo `format.ts` para `src/lib/format.ts`.
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+Contém helpers de formatação:
+- `formatCurrency(value)` → "R$ 1.234,56"
+- `formatTime(seconds)` → "01:30"
+- `formatDuration(seconds)` → "1h 30min"
+- `formatPhone(phone)` → "(11) 98765-4321"
+- `truncate(text, maxLength)` → "Lorem ipsu..."
+- `pluralize(count, singular, plural?)` → "2 itens"
 
-## Expanding the ESLint configuration
+### 3. Copiar componentes para `src/components/app/`
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+Copie toda a estrutura de pastas `components/app/` mantendo a hierarquia.
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+### 4. Atualizar `src/lib/utils.ts`
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+Adicione o export do format.ts:
 
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```typescript
+export * from "./format"
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+### 5. Atualizar `src/components/index.ts`
+
+Já deve estar correto:
+
+```typescript
+export * from "./ui"
+export * from "./app"
+```
+
+## 🚀 Uso no PDV
+
+### Configuração do Módulo
+
+No HTML root ou componente principal do PDV, adicione o atributo `data-module`:
+
+```tsx
+// pdv/src/App.tsx ou index.html
+<html data-module="pdv">
+  {/* ... */}
+</html>
+```
+
+Ou via React:
+
+```tsx
+useEffect(() => {
+  document.documentElement.setAttribute('data-module', 'pdv')
+}, [])
 ```
+
+### Exemplo: Página de Mesas
+
+```tsx
+import { AppHeader, TableGrid, TableCard } from "@tabl.io/ui"
+
+function TablesPage() {
+  return (
+    <div className="h-screen flex flex-col">
+      <AppHeader title="Mesas" />
+      
+      <TableGrid>
+        {tables.map(table => (
+          <TableCard
+            key={table.id}
+            number={table.number}
+            status={table.status}
+            onClick={() => handleSelectTable(table)}
+          />
+        ))}
+      </TableGrid>
+    </div>
+  )
+}
+```
+
+### Exemplo: Página de Produtos
+
+```tsx
+import {
+  AppHeader,
+  CartIndicator,
+  CategoryTabs,
+  ProductGrid,
+  ProductCard,
+  ProductDetailModal,
+  CartSheet,
+} from "@tabl.io/ui"
+
+function ProductsPage() {
+  const [selectedProduct, setSelectedProduct] = useState(null)
+  const [isCartOpen, setIsCartOpen] = useState(false)
+  
+  return (
+    <div className="h-screen flex flex-col">
+      <AppHeader
+        title={`Mesa ${tableNumber}`}
+        showBack
+        onBack={() => navigate('/tables')}
+        actions={
+          <CartIndicator
+            count={cartItems.length}
+            total={cartTotal}
+            onClick={() => setIsCartOpen(true)}
+          />
+        }
+      />
+      
+      <CategoryTabs
+        categories={categories}
+        activeCategory={activeCategory}
+        onSelectCategory={setActiveCategory}
+      />
+      
+      <ProductGrid>
+        {products.map(product => (
+          <ProductCard
+            key={product.id}
+            product={product}
+            onClick={() => setSelectedProduct(product)}
+          />
+        ))}
+      </ProductGrid>
+      
+      <ProductDetailModal
+        open={!!selectedProduct}
+        onOpenChange={(open) => !open && setSelectedProduct(null)}
+        product={selectedProduct}
+        removableIngredients={removableIngredients}
+        availableExtras={availableExtras}
+        onAddToCart={handleAddToCart}
+      />
+      
+      <CartSheet
+        open={isCartOpen}
+        onOpenChange={setIsCartOpen}
+        items={cartItems}
+        onQuantityChange={handleUpdateQuantity}
+        onRemoveItem={handleRemoveItem}
+        onConfirmOrder={handleConfirmOrder}
+        loading={isSubmitting}
+      />
+    </div>
+  )
+}
+```
+
+## 📚 Componentes Disponíveis
+
+### Layout
+- `AppHeader` - Cabeçalho padrão com título, voltar e actions
+- `CartIndicator` - Badge flutuante de carrinho
+- `QuantityStepper` - Controle de quantidade
+
+### Table
+- `TableGrid` - Grid responsivo de mesas
+- `TableCard` - Card individual de mesa
+- `TableBadge` - Badge de status
+
+### Category
+- `CategoryTabs` - Navegação horizontal de categorias
+- `CategoryPill` - Pill individual de categoria
+
+### Product
+- `ProductGrid` - Grid responsivo de produtos
+- `ProductCard` - Card de produto com imagem e preço
+- `ProductPriceDisplay` - Exibe cálculo de preço
+- `ProductDetailModal` - Modal de customização
+- `IngredientList` - Wrapper de lista de ingredientes
+- `IngredientCheckbox` - Checkbox de ingrediente removível
+- `ExtraCheckbox` - Checkbox de extra pago
+
+### Cart
+- `CartSheet` - Sheet lateral completo
+- `CartItem` - Item individual no carrinho
+- `CartSummary` - Resumo e botão de confirmar
+- `CartEmptyState` - Estado vazio
+
+### Order
+- `OrderConfirmationModal` - Modal de sucesso
+- `OrderLoadingState` - Estado de loading
+
+## 🎨 Sistema de Cores por Módulo
+
+| Módulo | Cor | Uso |
+|--------|-----|-----|
+| Core | Emerald (#10B981) | Base, configurações, sync |
+| PDV | Orange (#F97316) | Ponto de venda, vendas |
+| KDS | Blue (#3B82F6) | Cozinha, produção |
+| Manager | Violet (#8B5CF6) | Backoffice, cadastros |
+| Analytics | Amber (#F59E0B) | IA, insights (futuro) |
+
+## 🔄 Próximos Passos
+
+1. ✅ Instalar componentes Shadcn
+2. ✅ Copiar arquivos para o pacote
+3. ✅ Configurar `data-module="pdv"` no PDV
+4. 🚧 Implementar páginas do PDV
+5. 🚧 Criar hooks customizados (useCart, useOrder, etc)
+6. 🚧 Adicionar testes
+7. 🚧 Documentar no Storybook
+
+## 📝 Notas Importantes
+
+- Todos os componentes suportam dark mode automático via `prefers-color-scheme`
+- Use `data-module` para trocar entre temas de módulos
+- Componentes são totalmente tipados com TypeScript
+- Helpers de formatação estão em `@tabl.io/ui/lib/format`
+- Siga o padrão de imports: `import { Component } from "@tabl.io/ui"`
+
+## 🐛 Troubleshooting
+
+**Componentes não encontrados?**
+- Verifique se os exports estão corretos nos `index.ts`
+- Confira o `package.json` do @tabl.io/ui
+
+**Cores não mudando?**
+- Verifique se `data-module` está no elemento raiz
+- Confirme que `tokens.css` foi substituído
+
+**Helpers não disponíveis?**
+- Certifique-se que `format.ts` está em `src/lib/`
+- Verifique export em `src/lib/utils.ts`

package/README.stories.md

@@ -0,0 +1,226 @@
+# 📚 Storybook Stories - Tabl UI
+
+Documentação interativa de todos os componentes do design system Tabl.
+
+## 📂 Estrutura dos Arquivos
+
+Copie todos os arquivos `.stories.tsx` para `/.storybook/stories/` mantendo a estrutura de pastas:
+
+```
+/.storybook/stories/
+├── layout/
+│   ├── app-header.stories.tsx
+│   └── cart-indicator.stories.tsx
+├── table/
+│   ├── table-badge.stories.tsx
+│   ├── table-card.stories.tsx
+│   └── table-grid.stories.tsx
+├── category/
+│   ├── category-pill.stories.tsx
+│   └── category-tabs.stories.tsx
+├── product/
+│   ├── product-card.stories.tsx
+│   ├── product-grid.stories.tsx
+│   ├── product-price-display.stories.tsx
+│   ├── product-detail-modal.stories.tsx
+│   └── ingredients.stories.tsx
+├── cart/
+│   ├── cart-item.stories.tsx
+│   ├── cart-states.stories.tsx  (CartEmptyState + CartSummary)
+│   └── cart-sheet.stories.tsx
+├── order/
+│   ├── order-loading-state.stories.tsx
+│   └── order-confirmation-modal.stories.tsx
+├── shared/
+│   └── quantity-stepper.stories.tsx
+└── complete-flow.stories.tsx    (Exemplo de fluxo completo)
+```
+
+## 🚀 Como Usar
+
+### 1. Copiar arquivos
+
+```bash
+# Na raiz do @tabl.io/ui
+cp -r /path/to/storybook-stories/* ./.storybook/stories/
+```
+
+### 2. Iniciar Storybook
+
+```bash
+npm run storybook
+```
+
+### 3. Acessar
+
+Abra o navegador em `http://localhost:6006`
+
+## 📖 Estrutura das Stories
+
+Todas as stories seguem o padrão Storybook CSF 3.0:
+
+```typescript
+import type { Meta, StoryObj } from "@storybook/react"
+import { Component } from "@/components/..."
+
+const meta = {
+  title: "App/Category/Component",
+  component: Component,
+  tags: ["autodocs"],
+  argTypes: {
+    onClick: { action: "clicked" },
+  },
+} satisfies Meta<typeof Component>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    // props aqui
+  },
+}
+```
+
+## 🎨 Stories Criadas (19 arquivos)
+
+### Layout (2)
+- ✅ AppHeader - 5 variações (default, com subtitle, com back, com cart, completo)
+- ✅ CartIndicator - 4 variações (vazio, 1 item, múltiplos, grande)
+
+### Table (3)
+- ✅ TableBadge - 4 variações (available, occupied, reserved, todos)
+- ✅ TableCard - 4 variações (available, occupied, reserved, todos)
+- ✅ TableGrid - 3 variações (default, poucas mesas, muitas mesas)
+
+### Category (2)
+- ✅ CategoryPill - 4 variações (default, ativo, nome longo, múltiplos)
+- ✅ CategoryTabs - 4 variações (default, sem seleção, muitas categorias, interativo)
+
+### Product (5)
+- ✅ ProductCard - 6 variações (default, com imagem, longo, inativo, sem descrição, preço alto)
+- ✅ ProductGrid - 3 variações (default, poucos, muitos)
+- ✅ ProductPriceDisplay - 6 variações (base, com extras, muitos extras, baixo, alto, todas)
+- ✅ Ingredients - 3 variações (remover, adicionar, ambos)
+- ✅ ProductDetailModal - 6 variações (default, sem imagem, só ingredientes, só extras, simples, interativo)
+
+### Cart (3)
+- ✅ CartItem - 7 variações (simples, com extras, removidos, notas, completo, múltipla qtd, alto preço)
+- ✅ CartStates - 6 variações (empty, small, medium, large, loading, empty cart)
+- ✅ CartSheet - 6 variações (com itens, vazio, loading, um item, muitos, interativo)
+
+### Order (2)
+- ✅ OrderLoadingState - 3 variações (default, custom message, long message)
+- ✅ OrderConfirmationModal - 5 variações (default, small, large, sem ID, interativo)
+
+### Shared (1)
+- ✅ QuantityStepper - 8 variações (default, min, max, at max, small, large, interativo, all sizes)
+
+### Examples (1)
+- ✅ Complete PDV Flow - Exemplo de fluxo completo integrado
+
+## 🎯 Funcionalidades
+
+### Documentação Automática
+Todas as stories têm `tags: ["autodocs"]` que gera documentação automática das props.
+
+### Actions
+Componentes com callbacks têm actions configuradas para visualizar eventos no painel Actions do Storybook.
+
+### Interatividade
+Stories marcadas como "Interactive" permitem interação real com estado gerenciado pelo React.
+
+## 📝 Próximos Passos
+
+1. ✅ Copiar arquivos de stories
+2. ✅ Iniciar Storybook
+3. 🚧 Personalizar stories conforme necessário
+4. 🚧 Adicionar mais variações específicas do seu contexto
+5. 🚧 Documentar padrões de uso nos comentários
+
+## 💡 Dicas
+
+### Adicionar Nova Story
+
+```typescript
+export const MinhaNovaVariacao: Story = {
+  args: {
+    // suas props aqui
+  },
+}
+```
+
+### Story com Render Customizado
+
+```typescript
+export const CustomRender: Story = {
+  render: () => {
+    const [state, setState] = useState(...)
+    return <Component {...} />
+  },
+}
+```
+
+### Adicionar Controls Personalizados
+
+```typescript
+const meta = {
+  // ...
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'primary', 'secondary'],
+    },
+  },
+}
+```
+
+## 🐛 Troubleshooting
+
+**Imports não encontrados?**
+- Verifique se os paths do `@/components` estão corretos no tsconfig
+
+**Componentes não renderizam?**
+- Certifique-se que todos os componentes shadcn estão instalados
+- Verifique se o `index.css` está sendo importado
+
+**Estilos não aplicados?**
+- Confirme que o Tailwind está configurado no Storybook preview
+- Verifique se `data-module` está sendo aplicado quando necessário
+
+## 🎨 Temas no Storybook
+
+Para testar os diferentes módulos, adicione no `.storybook/preview.tsx`:
+
+```typescript
+export const decorators = [
+  (Story, context) => {
+    const module = context.parameters.module || 'pdv'
+    return (
+      <div data-module={module}>
+        <Story />
+      </div>
+    )
+  },
+]
+
+export const globalTypes = {
+  module: {
+    name: 'Module',
+    description: 'Tabl module theme',
+    defaultValue: 'pdv',
+    toolbar: {
+      icon: 'paintbrush',
+      items: [
+        { value: 'core', title: 'Core (Verde)' },
+        { value: 'pdv', title: 'PDV (Laranja)' },
+        { value: 'kds', title: 'KDS (Azul)' },
+        { value: 'manager', title: 'Manager (Roxo)' },
+        { value: 'analytics', title: 'Analytics (Âmbar)' },
+      ],
+    },
+  },
+}
+```
+
+Isso adiciona um seletor de módulo na toolbar do Storybook! 🎨