siesa-ui-kit 1.0.2 → 1.0.4

package/src/views/ProductsView/README.md

@@ -1,312 +1,312 @@
-# ProductsView
-
-Vista completa de selección de productos para sistema POS (Punto de Venta).
-
-## Descripción
-
-Vista especializada para sistemas de restaurante que permite a los meseros/administradores:
-
-- Seleccionar menús disponibles
-- Navegar por categorías de productos
-- Visualizar productos con imagen y precio
-- Agregar productos al pedido
-- Gestionar items del pedido (cantidad, eliminar)
-- Ver resumen financiero (subtotal, impuestos, total)
-- Confirmar el pedido final
-
-## Estructura de la Vista
-
-### 1. Navbar Superior (Componente Navbar)
-- Icono de navegación (heredado del componente Navbar)
-- Logo del negocio
-- Información del usuario (avatar, nombre, rol)
-- Logo de Siesa
-- **Nota**: Utiliza el componente `Navbar` del sistema con `hideActionButtons` para ocultar carrito/notificaciones
-
-### 2. Área de Contenido (3 columnas)
-
-#### Columna Izquierda: Categorías
-- Título "Categoría"
-- Lista vertical de botones de categoría con imagen
-- Scroll vertical si hay muchas categorías
-- Estado activo visual para categoría seleccionada
-
-#### Columna Central: Productos
-- Menú de navegación con botones de menús
-- Título "Productos"
-- Grid de productos (4 columnas)
-- Cada producto muestra:
-  - Imagen
-  - Nombre
-  - Precio
-  - Botón "Agregar"
-- Scroll vertical si hay muchos productos
-- Estados: normal, cargando, error, vacío
-
-#### Columna Derecha: Pedido
-- Título de la mesa (ej: "Mesa 1")
-- Tabs: "Productos" | "Cliente"
-- Lista de items del pedido con:
-  - Badge de categoría (color configurable)
-  - Referencia del producto
-  - Nombre del producto
-  - Precio
-  - Descripción opcional con items adicionales
-  - Control de cantidad
-  - Botón eliminar
-- Resumen financiero:
-  - Subtotal
-  - Impuestos
-  - Total
-- Botón "Confirmar Pedido"
-
-## Componentes Utilizados
-
-- **Navbar**: Barra de navegación superior con logo, usuario y logo Siesa
-- **POSProductButton**: Botón de categoría con imagen
-- **POSProductCard**: Card de producto con imagen, nombre, precio y botón
-- **POSProductSidebarItems**: Item de pedido con todos sus datos
-- **Button**: Botones de acción (Cambiar Mesa, Confirmar Pedido, Agregar)
-- **Divider**: Separadores entre items del pedido
-- **Quantity**: Control de cantidad en items del pedido (integrado en POSProductSidebarItems)
-
-## Props Principales
-
-### Datos de Menús
-```typescript
-menus: Menu[]                    // Lista de menús disponibles
-selectedMenuId: string           // ID del menú seleccionado
-onMenuSelect: (id) => void       // Handler selección de menú
-```
-
-### Datos de Categorías
-```typescript
-categories: ProductCategory[]    // Lista de categorías
-selectedCategoryId: string       // ID de categoría seleccionada
-onCategorySelect: (id) => void   // Handler selección de categoría
-```
-
-### Datos de Productos
-```typescript
-products: Product[]              // Lista de productos
-onAddProduct: (id) => void       // Handler agregar producto
-```
-
-### Datos de Pedido
-```typescript
-orderItems: OrderItem[]                          // Items del pedido
-onOrderItemQuantityChange: (id, qty) => void     // Handler cambio cantidad
-onOrderItemDelete: (id) => void                  // Handler eliminar item
-subtotal: string                                  // Subtotal
-taxes: string                                     // Impuestos
-total: string                                     // Total
-onConfirmOrder: () => void                        // Handler confirmar
-```
-
-### Configuración
-```typescript
-tableTitle: string               // Título de la mesa (ej: "Mesa 1")
-activeTab: 'products' | 'client' // Tab activo en sidebar
-onTabChange: (tab) => void       // Handler cambio de tab
-isLoading: boolean               // Estado de carga
-errorMessage: string             // Mensaje de error
-```
-
-## Tipos de Datos
-
-### ProductCategory
-```typescript
-interface ProductCategory {
-  id: string;
-  label: string;
-  image: string;
-}
-```
-
-### Product
-```typescript
-interface Product {
-  id: string;
-  name: string;
-  price: string;
-  image: string;
-  categoryId: string;
-}
-```
-
-### OrderItem
-```typescript
-interface OrderItem {
-  productId: string;
-  productName: string;
-  categoryLabel: string;
-  categoryColor?: string;
-  productRef: string;
-  price: string;
-  quantity: number;
-  descriptionItems?: Array<{
-    description: string;
-    price: string;
-  }>;
-}
-```
-
-### Menu
-```typescript
-interface Menu {
-  id: string;
-  label: string;
-}
-```
-
-## Ejemplos de Uso
-
-### Uso Básico
-```tsx
-<ProductsView
-  tableTitle="Mesa 1"
-  categories={categories}
-  products={products}
-  orderItems={orderItems}
-  onAddProduct={(id) => handleAddProduct(id)}
-  onConfirmOrder={() => handleConfirmOrder()}
-/>
-```
-
-### Con Pedido Vacío
-```tsx
-<ProductsView
-  tableTitle="Mesa 5"
-  categories={categories}
-  products={products}
-  orderItems={[]}
-  subtotal="0.00"
-  taxes="0.00"
-  total="0.00"
-  onAddProduct={(id) => handleAddProduct(id)}
-  onConfirmOrder={() => handleConfirmOrder()}
-/>
-```
-
-### Con Estado de Carga
-```tsx
-<ProductsView
-  tableTitle="Mesa 1"
-  categories={categories}
-  products={[]}
-  isLoading={true}
-  orderItems={orderItems}
-  onAddProduct={(id) => handleAddProduct(id)}
-  onConfirmOrder={() => handleConfirmOrder()}
-/>
-```
-
-### Con Error
-```tsx
-<ProductsView
-  tableTitle="Mesa 1"
-  categories={categories}
-  products={[]}
-  errorMessage="Error al cargar productos. Intente nuevamente."
-  orderItems={orderItems}
-  onAddProduct={(id) => handleAddProduct(id)}
-  onConfirmOrder={() => handleConfirmOrder()}
-/>
-```
-
-### Con Tab Cliente Activo
-```tsx
-<ProductsView
-  tableTitle="Mesa 1"
-  categories={categories}
-  products={products}
-  orderItems={orderItems}
-  activeTab="client"
-  onTabChange={(tab) => setActiveTab(tab)}
-  onAddProduct={(id) => handleAddProduct(id)}
-  onConfirmOrder={() => handleConfirmOrder()}
-/>
-```
-
-## Estados Visuales
-
-### 1. Vista Completa
-- Todos los elementos visibles
-- Productos en el grid
-- Items en el pedido
-- Resumen con valores
-
-### 2. Pedido Vacío
-- Grid de productos visible
-- Sidebar de pedido muestra mensaje "No hay productos en el pedido"
-- Botón "Confirmar Pedido" deshabilitado
-
-### 3. Cargando Productos
-- Mensaje "Cargando productos..." en área de productos
-- Sidebar de pedido funcional
-
-### 4. Error al Cargar
-- Mensaje de error en área de productos
-- Color rojo para destacar el error
-- Sidebar de pedido funcional
-
-### 5. Tab Cliente
-- Sidebar cambia a mostrar información del cliente
-- (Implementación futura)
-
-## Flujo de Interacción
-
-1. **Usuario selecciona menú** → `onMenuSelect(menuId)`
-2. **Usuario selecciona categoría** → `onCategorySelect(categoryId)`
-3. **Usuario hace clic en "Agregar" en producto** → `onAddProduct(productId)`
-4. **Usuario cambia cantidad de item** → `onOrderItemQuantityChange(itemId, quantity)`
-5. **Usuario elimina item** → `onOrderItemDelete(itemId)`
-6. **Usuario confirma pedido** → `onConfirmOrder()`
-7. **Usuario cambia de tab** → `onTabChange(tab)`
-
-## Responsive Design
-
-- **Desktop (≥ 768px)**: Layout de 3 columnas según Figma
-- **Mobile (< 768px)**: Layout adaptativo vertical
-  - Categorías en sidebar izquierdo
-  - Productos en área central con scroll
-  - Pedido en sidebar derecho
-
-## Dark Mode
-
-Soporte completo con tokens del sistema:
-- Fondos: `bg-white` → `dark:bg-dark-bg-primary`
-- Textos: `text-content-primary` → `dark:text-dark-content-primary`
-- Bordes: `border-border-primary` → `dark:border-dark-border-primary`
-
-## Accesibilidad
-
-- Navegación por teclado habilitada
-- ARIA labels en botones de acción
-- Focus rings visibles
-- Contraste de colores según WCAG
-
-## Notas de Implementación
-
-1. **Grid de Productos**: Se organizan automáticamente en filas de 4 productos
-2. **Scroll**: Áreas de categorías, productos y pedido tienen scroll independiente
-3. **Validación**: El botón "Confirmar Pedido" se deshabilita si el pedido está vacío
-4. **Estados**: La vista maneja estados de carga, error y vacío
-5. **Tabs**: El tab "Cliente" está preparado para implementación futura
-
-## Referencias
-
-- **Figma**: [Vista Products / POS](https://www.figma.com/design/peN2etuaXX0pXJgC1yHgGk/Siesa-POS---Comandera?node-id=75-1072)
-- **Componentes**: POSProductButton, POSProductCard, POSProductSidebarItems
-- **Sistema de Diseño**: Siesa UI Kit
-
-## Changelog
-
-### v1.0.0
-- Implementación inicial de ProductsView
-- Soporte para menús, categorías y productos
-- Gestión de pedido con items
-- Resumen financiero
-- Tabs Productos/Cliente
-- Estados de carga y error
-- Dark mode completo
+# ProductsView
+
+Vista completa de selección de productos para sistema POS (Punto de Venta).
+
+## Descripción
+
+Vista especializada para sistemas de restaurante que permite a los meseros/administradores:
+
+- Seleccionar menús disponibles
+- Navegar por categorías de productos
+- Visualizar productos con imagen y precio
+- Agregar productos al pedido
+- Gestionar items del pedido (cantidad, eliminar)
+- Ver resumen financiero (subtotal, impuestos, total)
+- Confirmar el pedido final
+
+## Estructura de la Vista
+
+### 1. Navbar Superior (Componente Navbar)
+- Icono de navegación (heredado del componente Navbar)
+- Logo del negocio
+- Información del usuario (avatar, nombre, rol)
+- Logo de Siesa
+- **Nota**: Utiliza el componente `Navbar` del sistema con `hideActionButtons` para ocultar carrito/notificaciones
+
+### 2. Área de Contenido (3 columnas)
+
+#### Columna Izquierda: Categorías
+- Título "Categoría"
+- Lista vertical de botones de categoría con imagen
+- Scroll vertical si hay muchas categorías
+- Estado activo visual para categoría seleccionada
+
+#### Columna Central: Productos
+- Menú de navegación con botones de menús
+- Título "Productos"
+- Grid de productos (4 columnas)
+- Cada producto muestra:
+  - Imagen
+  - Nombre
+  - Precio
+  - Botón "Agregar"
+- Scroll vertical si hay muchos productos
+- Estados: normal, cargando, error, vacío
+
+#### Columna Derecha: Pedido
+- Título de la mesa (ej: "Mesa 1")
+- Tabs: "Productos" | "Cliente"
+- Lista de items del pedido con:
+  - Badge de categoría (color configurable)
+  - Referencia del producto
+  - Nombre del producto
+  - Precio
+  - Descripción opcional con items adicionales
+  - Control de cantidad
+  - Botón eliminar
+- Resumen financiero:
+  - Subtotal
+  - Impuestos
+  - Total
+- Botón "Confirmar Pedido"
+
+## Componentes Utilizados
+
+- **Navbar**: Barra de navegación superior con logo, usuario y logo Siesa
+- **POSProductButton**: Botón de categoría con imagen
+- **POSProductCard**: Card de producto con imagen, nombre, precio y botón
+- **POSProductSidebarItems**: Item de pedido con todos sus datos
+- **Button**: Botones de acción (Cambiar Mesa, Confirmar Pedido, Agregar)
+- **Divider**: Separadores entre items del pedido
+- **Quantity**: Control de cantidad en items del pedido (integrado en POSProductSidebarItems)
+
+## Props Principales
+
+### Datos de Menús
+```typescript
+menus: Menu[]                    // Lista de menús disponibles
+selectedMenuId: string           // ID del menú seleccionado
+onMenuSelect: (id) => void       // Handler selección de menú
+```
+
+### Datos de Categorías
+```typescript
+categories: ProductCategory[]    // Lista de categorías
+selectedCategoryId: string       // ID de categoría seleccionada
+onCategorySelect: (id) => void   // Handler selección de categoría
+```
+
+### Datos de Productos
+```typescript
+products: Product[]              // Lista de productos
+onAddProduct: (id) => void       // Handler agregar producto
+```
+
+### Datos de Pedido
+```typescript
+orderItems: OrderItem[]                          // Items del pedido
+onOrderItemQuantityChange: (id, qty) => void     // Handler cambio cantidad
+onOrderItemDelete: (id) => void                  // Handler eliminar item
+subtotal: string                                  // Subtotal
+taxes: string                                     // Impuestos
+total: string                                     // Total
+onConfirmOrder: () => void                        // Handler confirmar
+```
+
+### Configuración
+```typescript
+tableTitle: string               // Título de la mesa (ej: "Mesa 1")
+activeTab: 'products' | 'client' // Tab activo en sidebar
+onTabChange: (tab) => void       // Handler cambio de tab
+isLoading: boolean               // Estado de carga
+errorMessage: string             // Mensaje de error
+```
+
+## Tipos de Datos
+
+### ProductCategory
+```typescript
+interface ProductCategory {
+  id: string;
+  label: string;
+  image: string;
+}
+```
+
+### Product
+```typescript
+interface Product {
+  id: string;
+  name: string;
+  price: string;
+  image: string;
+  categoryId: string;
+}
+```
+
+### OrderItem
+```typescript
+interface OrderItem {
+  productId: string;
+  productName: string;
+  categoryLabel: string;
+  categoryColor?: string;
+  productRef: string;
+  price: string;
+  quantity: number;
+  descriptionItems?: Array<{
+    description: string;
+    price: string;
+  }>;
+}
+```
+
+### Menu
+```typescript
+interface Menu {
+  id: string;
+  label: string;
+}
+```
+
+## Ejemplos de Uso
+
+### Uso Básico
+```tsx
+<ProductsView
+  tableTitle="Mesa 1"
+  categories={categories}
+  products={products}
+  orderItems={orderItems}
+  onAddProduct={(id) => handleAddProduct(id)}
+  onConfirmOrder={() => handleConfirmOrder()}
+/>
+```
+
+### Con Pedido Vacío
+```tsx
+<ProductsView
+  tableTitle="Mesa 5"
+  categories={categories}
+  products={products}
+  orderItems={[]}
+  subtotal="0.00"
+  taxes="0.00"
+  total="0.00"
+  onAddProduct={(id) => handleAddProduct(id)}
+  onConfirmOrder={() => handleConfirmOrder()}
+/>
+```
+
+### Con Estado de Carga
+```tsx
+<ProductsView
+  tableTitle="Mesa 1"
+  categories={categories}
+  products={[]}
+  isLoading={true}
+  orderItems={orderItems}
+  onAddProduct={(id) => handleAddProduct(id)}
+  onConfirmOrder={() => handleConfirmOrder()}
+/>
+```
+
+### Con Error
+```tsx
+<ProductsView
+  tableTitle="Mesa 1"
+  categories={categories}
+  products={[]}
+  errorMessage="Error al cargar productos. Intente nuevamente."
+  orderItems={orderItems}
+  onAddProduct={(id) => handleAddProduct(id)}
+  onConfirmOrder={() => handleConfirmOrder()}
+/>
+```
+
+### Con Tab Cliente Activo
+```tsx
+<ProductsView
+  tableTitle="Mesa 1"
+  categories={categories}
+  products={products}
+  orderItems={orderItems}
+  activeTab="client"
+  onTabChange={(tab) => setActiveTab(tab)}
+  onAddProduct={(id) => handleAddProduct(id)}
+  onConfirmOrder={() => handleConfirmOrder()}
+/>
+```
+
+## Estados Visuales
+
+### 1. Vista Completa
+- Todos los elementos visibles
+- Productos en el grid
+- Items en el pedido
+- Resumen con valores
+
+### 2. Pedido Vacío
+- Grid de productos visible
+- Sidebar de pedido muestra mensaje "No hay productos en el pedido"
+- Botón "Confirmar Pedido" deshabilitado
+
+### 3. Cargando Productos
+- Mensaje "Cargando productos..." en área de productos
+- Sidebar de pedido funcional
+
+### 4. Error al Cargar
+- Mensaje de error en área de productos
+- Color rojo para destacar el error
+- Sidebar de pedido funcional
+
+### 5. Tab Cliente
+- Sidebar cambia a mostrar información del cliente
+- (Implementación futura)
+
+## Flujo de Interacción
+
+1. **Usuario selecciona menú** → `onMenuSelect(menuId)`
+2. **Usuario selecciona categoría** → `onCategorySelect(categoryId)`
+3. **Usuario hace clic en "Agregar" en producto** → `onAddProduct(productId)`
+4. **Usuario cambia cantidad de item** → `onOrderItemQuantityChange(itemId, quantity)`
+5. **Usuario elimina item** → `onOrderItemDelete(itemId)`
+6. **Usuario confirma pedido** → `onConfirmOrder()`
+7. **Usuario cambia de tab** → `onTabChange(tab)`
+
+## Responsive Design
+
+- **Desktop (≥ 768px)**: Layout de 3 columnas según Figma
+- **Mobile (< 768px)**: Layout adaptativo vertical
+  - Categorías en sidebar izquierdo
+  - Productos en área central con scroll
+  - Pedido en sidebar derecho
+
+## Dark Mode
+
+Soporte completo con tokens del sistema:
+- Fondos: `bg-white` → `dark:bg-dark-bg-primary`
+- Textos: `text-content-primary` → `dark:text-dark-content-primary`
+- Bordes: `border-border-primary` → `dark:border-dark-border-primary`
+
+## Accesibilidad
+
+- Navegación por teclado habilitada
+- ARIA labels en botones de acción
+- Focus rings visibles
+- Contraste de colores según WCAG
+
+## Notas de Implementación
+
+1. **Grid de Productos**: Se organizan automáticamente en filas de 4 productos
+2. **Scroll**: Áreas de categorías, productos y pedido tienen scroll independiente
+3. **Validación**: El botón "Confirmar Pedido" se deshabilita si el pedido está vacío
+4. **Estados**: La vista maneja estados de carga, error y vacío
+5. **Tabs**: El tab "Cliente" está preparado para implementación futura
+
+## Referencias
+
+- **Figma**: [Vista Products / POS](https://www.figma.com/design/peN2etuaXX0pXJgC1yHgGk/Siesa-POS---Comandera?node-id=75-1072)
+- **Componentes**: POSProductButton, POSProductCard, POSProductSidebarItems
+- **Sistema de Diseño**: Siesa UI Kit
+
+## Changelog
+
+### v1.0.0
+- Implementación inicial de ProductsView
+- Soporte para menús, categorías y productos
+- Gestión de pedido con items
+- Resumen financiero
+- Tabs Productos/Cliente
+- Estados de carga y error
+- Dark mode completo