siesa-ui-kit 1.0.2 → 1.0.4

package/src/components/POSLocationButton/README.md

@@ -1,253 +1,253 @@
-# POSLocationButton
-
-Botón especializado para punto de venta (POS) que muestra el estado de disponibilidad de una ubicación física (mesa, salón, terraza, etc.) con indicadores visuales claros.
-
-## 📋 Características
-
-- ✅ **4 estados de disponibilidad**: Available, Occupied, Reserved, Out of Service
-- ✅ **2 estados visuales**: Enabled (normal) y Actived (seleccionado)
-- ✅ **Información de capacidad**: Muestra mesas ocupadas/total
-- ✅ **Iconos visuales**: Cada estado tiene su icono distintivo
-- ✅ **Dark mode completo**: Todos los estados adaptados para modo oscuro
-- ✅ **Tamaño fijo**: 189x68px optimizado para interfaces POS
-- ✅ **Accesibilidad**: ARIA labels y estados semánticos
-- ✅ **TypeScript**: Type safety completo
-
-## 🎨 Estados de Disponibilidad
-
-| Status | Color | Icono | Uso |
-|--------|-------|-------|-----|
-| `available` | Verde/Lime | ✓ | Ubicación disponible para asignar |
-| `occupied` | Naranja/Yellow | ✗ | Ubicación actualmente en uso |
-| `reserved` | Morado/Purple | 📅 | Ubicación reservada para uso futuro |
-| `outOfService` | Gris/Zinc | 🚫 | Ubicación fuera de servicio temporalmente |
-
-## 🔧 Estados Visuales
-
-| State | Descripción | Uso |
-|-------|-------------|-----|
-| `enabled` | Estado normal con fondo blanco/dark | Vista por defecto |
-| `actived` | Estado seleccionado con fondo coloreado | Ubicación actualmente seleccionada en la interfaz |
-
-## 📦 Instalación
-
-```tsx
-import { POSLocationButton } from '@/components/POSLocationButton';
-```
-
-## 🚀 Uso Básico
-
-```tsx
-// Ubicación disponible
-<POSLocationButton
-  locationName="Antejardín"
-  status="available"
-  capacity={{ current: 1, total: 8 }}
-  onClick={() => console.log('Seleccionado')}
-/>
-```
-
-## 📖 Ejemplos
-
-### Dashboard de Restaurante
-
-```tsx
-<div className="grid grid-cols-2 gap-3">
-  <POSLocationButton
-    locationName="Antejardín"
-    status="available"
-    capacity={{ current: 1, total: 8 }}
-  />
-  <POSLocationButton
-    locationName="Terraza"
-    status="occupied"
-    capacity={{ current: 5, total: 8 }}
-  />
-  <POSLocationButton
-    locationName="Salón Principal"
-    status="reserved"
-    capacity={{ current: 3, total: 12 }}
-  />
-  <POSLocationButton
-    locationName="Bar"
-    status="outOfService"
-    disabled
-  />
-</div>
-```
-
-### Ubicación Seleccionada
-
-```tsx
-// Estado normal
-<POSLocationButton
-  locationName="Terraza"
-  status="available"
-  capacity={{ current: 2, total: 10 }}
-/>
-
-// Estado seleccionado (actived)
-<POSLocationButton
-  locationName="Salón VIP"
-  status="available"
-  state="actived"
-  capacity={{ current: 1, total: 6 }}
-/>
-```
-
-### Sin Información de Capacidad
-
-```tsx
-<POSLocationButton
-  locationName="Área de Espera"
-  status="available"
-/>
-```
-
-### Ubicación Deshabilitada
-
-```tsx
-<POSLocationButton
-  locationName="Bar"
-  status="outOfService"
-  disabled
-/>
-```
-
-## 🎯 Props
-
-### POSLocationButtonProps
-
-| Prop | Tipo | Default | Descripción |
-|------|------|---------|-------------|
-| `locationName` | `string` | **requerido** | Nombre de la ubicación (ej: "Antejardín", "Terraza") |
-| `status` | `POSLocationStatus` | `'available'` | Estado de disponibilidad |
-| `state` | `POSLocationState` | `'enabled'` | Estado visual del botón |
-| `capacity` | `POSLocationCapacity` | `undefined` | Información de capacidad (mesas ocupadas/total) |
-| `onClick` | `(event) => void` | `undefined` | Función a ejecutar al hacer clic |
-| `disabled` | `boolean` | `false` | Si el botón está deshabilitado |
-| `className` | `string` | `''` | Clases CSS adicionales |
-| `ariaLabel` | `string` | `undefined` | Label para accesibilidad (ARIA) |
-
-### POSLocationStatus
-
-```typescript
-type POSLocationStatus = 'available' | 'occupied' | 'reserved' | 'outOfService';
-```
-
-### POSLocationState
-
-```typescript
-type POSLocationState = 'enabled' | 'actived';
-```
-
-### POSLocationCapacity
-
-```typescript
-interface POSLocationCapacity {
-  current: number;  // Número actual de mesas/espacios ocupados
-  total: number;    // Total de mesas/espacios disponibles
-}
-```
-
-## 🎨 Especificaciones de Diseño
-
-### Tamaños
-
-- **Ancho**: 189px (fijo)
-- **Alto**: 68px (fijo)
-- **Padding**: 8px
-- **Border radius**: 8px (rounded-lg)
-
-### Tipografía
-
-- **Título (locationName)**: 16px Bold (text-base font-bold), line-height 24px
-- **Capacidad**: 10px Regular, line-height 12px
-- **Badge**: 12px Regular (text-xs), line-height 16px
-
-### Colores (Light Mode)
-
-| Status | Texto | Badge Fondo | Badge Texto |
-|--------|-------|-------------|-------------|
-| `available` | `#4d7c0f` (lime-700) | `#ecfccb` (lime-100) | `#4d7c0f` (lime-700) |
-| `occupied` | `#af460e` (orange-700) | `#fcedc9` (yellow-100) | `#af460e` (orange-700) |
-| `reserved` | `#7e22ce` (purple-700) | `#f3e8ff` (purple-100) | `#7e22ce` (purple-700) |
-| `outOfService` | `#3f3f46` (zinc-700) | `#f4f4f5` (zinc-100) | `#71717a` (zinc-500) |
-
-### Colores (Dark Mode)
-
-| Status | Texto | Badge Fondo | Badge Texto |
-|--------|-------|-------------|-------------|
-| `available` | `#4d7c0f` (lime-700) | `lime-900/30` | `#a3e635` (lime-400) |
-| `occupied` | `#af460e` (orange-700) | `yellow-900/30` | `#facc15` (yellow-400) |
-| `reserved` | `#7e22ce` (purple-700) | `purple-900/30` | `#c084fc` (purple-400) |
-| `outOfService` | `#3f3f46` (zinc-700) | `zinc-800/30` | `#a1a1aa` (zinc-400) |
-
-## ♿ Accesibilidad
-
-- **ARIA labels**: Cada botón incluye un aria-label descriptivo por defecto
-- **Estados semánticos**: Los estados disabled y actived son accesibles
-- **Contraste**: Todos los colores cumplen con WCAG AA
-- **Focus ring**: Anillo de enfoque visible y adaptativo
-
-## 🌓 Dark Mode
-
-El componente se adapta automáticamente al modo oscuro usando la estrategia `class` de Tailwind CSS. Todos los colores tienen variantes dark optimizadas para mantener la legibilidad y el contraste.
-
-## 🔗 Archivos Relacionados
-
-- `POSLocationButton.tsx` - Componente principal
-- `POSLocationButton.types.ts` - TypeScript types
-- `POSLocationButton.stories.tsx` - Stories de Storybook
-- `icons.tsx` - Iconos del componente
-- `index.ts` - Exports
-
-## 📚 Referencias
-
-- **Figma**: [POSLocationButton Specs](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4368-30644)
-- **Documentación**: `docs/colors.md`, `docs/typography.md`, `docs/spacing.md`
-- **Referencia**: `src/components/Button/` - Patrón de implementación
-
-## ✅ Checklist de Implementación
-
-- [x] Componente con JSDoc completo
-- [x] Dark mode en todos los estados
-- [x] TypeScript types estrictos
-- [x] 4 estados de disponibilidad (available, occupied, reserved, outOfService)
-- [x] 2 estados visuales (enabled, actived)
-- [x] Información de capacidad opcional
-- [x] Iconos visuales distintivos
-- [x] Focus rings adaptativos
-- [x] Stories de Storybook completas
-- [x] README con ejemplos
-- [x] Accesibilidad (ARIA)
-- [x] Validación con build
-
-## 🎯 Casos de Uso
-
-### ✅ Ideal para:
-
-- Sistemas POS de restaurantes
-- Gestión de mesas y ubicaciones
-- Dashboards de disponibilidad
-- Interfaces de asignación de recursos
-- Aplicaciones de reservas
-
-### ❌ No usar para:
-
-- Botones de acción genéricos (usar `Button` en su lugar)
-- Navegación principal (usar `NavigationBar` o `NavigationRail`)
-- Formularios (usar `Button` estándar)
-
-## 📝 Notas
-
-- El componente tiene un tamaño fijo de 189x68px optimizado para interfaces POS
-- Si no se proporciona `capacity`, solo se muestra el nombre y el estado
-- El estado `actived` es puramente visual y debe ser manejado por el componente padre
-- Para interfaces responsive, considera usar un grid adaptativo para organizar múltiples botones
-
----
-
-**Versión**: 1.0.0
-**Última actualización**: 2025-11-24
-**Mantenido por**: Equipo Siesa UI Kit
+# POSLocationButton
+
+Botón especializado para punto de venta (POS) que muestra el estado de disponibilidad de una ubicación física (mesa, salón, terraza, etc.) con indicadores visuales claros.
+
+## 📋 Características
+
+- ✅ **4 estados de disponibilidad**: Available, Occupied, Reserved, Out of Service
+- ✅ **2 estados visuales**: Enabled (normal) y Actived (seleccionado)
+- ✅ **Información de capacidad**: Muestra mesas ocupadas/total
+- ✅ **Iconos visuales**: Cada estado tiene su icono distintivo
+- ✅ **Dark mode completo**: Todos los estados adaptados para modo oscuro
+- ✅ **Tamaño fijo**: 189x68px optimizado para interfaces POS
+- ✅ **Accesibilidad**: ARIA labels y estados semánticos
+- ✅ **TypeScript**: Type safety completo
+
+## 🎨 Estados de Disponibilidad
+
+| Status | Color | Icono | Uso |
+|--------|-------|-------|-----|
+| `available` | Verde/Lime | ✓ | Ubicación disponible para asignar |
+| `occupied` | Naranja/Yellow | ✗ | Ubicación actualmente en uso |
+| `reserved` | Morado/Purple | 📅 | Ubicación reservada para uso futuro |
+| `outOfService` | Gris/Zinc | 🚫 | Ubicación fuera de servicio temporalmente |
+
+## 🔧 Estados Visuales
+
+| State | Descripción | Uso |
+|-------|-------------|-----|
+| `enabled` | Estado normal con fondo blanco/dark | Vista por defecto |
+| `actived` | Estado seleccionado con fondo coloreado | Ubicación actualmente seleccionada en la interfaz |
+
+## 📦 Instalación
+
+```tsx
+import { POSLocationButton } from '@/components/POSLocationButton';
+```
+
+## 🚀 Uso Básico
+
+```tsx
+// Ubicación disponible
+<POSLocationButton
+  locationName="Antejardín"
+  status="available"
+  capacity={{ current: 1, total: 8 }}
+  onClick={() => console.log('Seleccionado')}
+/>
+```
+
+## 📖 Ejemplos
+
+### Dashboard de Restaurante
+
+```tsx
+<div className="grid grid-cols-2 gap-3">
+  <POSLocationButton
+    locationName="Antejardín"
+    status="available"
+    capacity={{ current: 1, total: 8 }}
+  />
+  <POSLocationButton
+    locationName="Terraza"
+    status="occupied"
+    capacity={{ current: 5, total: 8 }}
+  />
+  <POSLocationButton
+    locationName="Salón Principal"
+    status="reserved"
+    capacity={{ current: 3, total: 12 }}
+  />
+  <POSLocationButton
+    locationName="Bar"
+    status="outOfService"
+    disabled
+  />
+</div>
+```
+
+### Ubicación Seleccionada
+
+```tsx
+// Estado normal
+<POSLocationButton
+  locationName="Terraza"
+  status="available"
+  capacity={{ current: 2, total: 10 }}
+/>
+
+// Estado seleccionado (actived)
+<POSLocationButton
+  locationName="Salón VIP"
+  status="available"
+  state="actived"
+  capacity={{ current: 1, total: 6 }}
+/>
+```
+
+### Sin Información de Capacidad
+
+```tsx
+<POSLocationButton
+  locationName="Área de Espera"
+  status="available"
+/>
+```
+
+### Ubicación Deshabilitada
+
+```tsx
+<POSLocationButton
+  locationName="Bar"
+  status="outOfService"
+  disabled
+/>
+```
+
+## 🎯 Props
+
+### POSLocationButtonProps
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `locationName` | `string` | **requerido** | Nombre de la ubicación (ej: "Antejardín", "Terraza") |
+| `status` | `POSLocationStatus` | `'available'` | Estado de disponibilidad |
+| `state` | `POSLocationState` | `'enabled'` | Estado visual del botón |
+| `capacity` | `POSLocationCapacity` | `undefined` | Información de capacidad (mesas ocupadas/total) |
+| `onClick` | `(event) => void` | `undefined` | Función a ejecutar al hacer clic |
+| `disabled` | `boolean` | `false` | Si el botón está deshabilitado |
+| `className` | `string` | `''` | Clases CSS adicionales |
+| `ariaLabel` | `string` | `undefined` | Label para accesibilidad (ARIA) |
+
+### POSLocationStatus
+
+```typescript
+type POSLocationStatus = 'available' | 'occupied' | 'reserved' | 'outOfService';
+```
+
+### POSLocationState
+
+```typescript
+type POSLocationState = 'enabled' | 'actived';
+```
+
+### POSLocationCapacity
+
+```typescript
+interface POSLocationCapacity {
+  current: number;  // Número actual de mesas/espacios ocupados
+  total: number;    // Total de mesas/espacios disponibles
+}
+```
+
+## 🎨 Especificaciones de Diseño
+
+### Tamaños
+
+- **Ancho**: 189px (fijo)
+- **Alto**: 68px (fijo)
+- **Padding**: 8px
+- **Border radius**: 8px (rounded-lg)
+
+### Tipografía
+
+- **Título (locationName)**: 16px Bold (text-base font-bold), line-height 24px
+- **Capacidad**: 10px Regular, line-height 12px
+- **Badge**: 12px Regular (text-xs), line-height 16px
+
+### Colores (Light Mode)
+
+| Status | Texto | Badge Fondo | Badge Texto |
+|--------|-------|-------------|-------------|
+| `available` | `#4d7c0f` (lime-700) | `#ecfccb` (lime-100) | `#4d7c0f` (lime-700) |
+| `occupied` | `#af460e` (orange-700) | `#fcedc9` (yellow-100) | `#af460e` (orange-700) |
+| `reserved` | `#7e22ce` (purple-700) | `#f3e8ff` (purple-100) | `#7e22ce` (purple-700) |
+| `outOfService` | `#3f3f46` (zinc-700) | `#f4f4f5` (zinc-100) | `#71717a` (zinc-500) |
+
+### Colores (Dark Mode)
+
+| Status | Texto | Badge Fondo | Badge Texto |
+|--------|-------|-------------|-------------|
+| `available` | `#4d7c0f` (lime-700) | `lime-900/30` | `#a3e635` (lime-400) |
+| `occupied` | `#af460e` (orange-700) | `yellow-900/30` | `#facc15` (yellow-400) |
+| `reserved` | `#7e22ce` (purple-700) | `purple-900/30` | `#c084fc` (purple-400) |
+| `outOfService` | `#3f3f46` (zinc-700) | `zinc-800/30` | `#a1a1aa` (zinc-400) |
+
+## ♿ Accesibilidad
+
+- **ARIA labels**: Cada botón incluye un aria-label descriptivo por defecto
+- **Estados semánticos**: Los estados disabled y actived son accesibles
+- **Contraste**: Todos los colores cumplen con WCAG AA
+- **Focus ring**: Anillo de enfoque visible y adaptativo
+
+## 🌓 Dark Mode
+
+El componente se adapta automáticamente al modo oscuro usando la estrategia `class` de Tailwind CSS. Todos los colores tienen variantes dark optimizadas para mantener la legibilidad y el contraste.
+
+## 🔗 Archivos Relacionados
+
+- `POSLocationButton.tsx` - Componente principal
+- `POSLocationButton.types.ts` - TypeScript types
+- `POSLocationButton.stories.tsx` - Stories de Storybook
+- `icons.tsx` - Iconos del componente
+- `index.ts` - Exports
+
+## 📚 Referencias
+
+- **Figma**: [POSLocationButton Specs](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4368-30644)
+- **Documentación**: `docs/colors.md`, `docs/typography.md`, `docs/spacing.md`
+- **Referencia**: `src/components/Button/` - Patrón de implementación
+
+## ✅ Checklist de Implementación
+
+- [x] Componente con JSDoc completo
+- [x] Dark mode en todos los estados
+- [x] TypeScript types estrictos
+- [x] 4 estados de disponibilidad (available, occupied, reserved, outOfService)
+- [x] 2 estados visuales (enabled, actived)
+- [x] Información de capacidad opcional
+- [x] Iconos visuales distintivos
+- [x] Focus rings adaptativos
+- [x] Stories de Storybook completas
+- [x] README con ejemplos
+- [x] Accesibilidad (ARIA)
+- [x] Validación con build
+
+## 🎯 Casos de Uso
+
+### ✅ Ideal para:
+
+- Sistemas POS de restaurantes
+- Gestión de mesas y ubicaciones
+- Dashboards de disponibilidad
+- Interfaces de asignación de recursos
+- Aplicaciones de reservas
+
+### ❌ No usar para:
+
+- Botones de acción genéricos (usar `Button` en su lugar)
+- Navegación principal (usar `NavigationBar` o `NavigationRail`)
+- Formularios (usar `Button` estándar)
+
+## 📝 Notas
+
+- El componente tiene un tamaño fijo de 189x68px optimizado para interfaces POS
+- Si no se proporciona `capacity`, solo se muestra el nombre y el estado
+- El estado `actived` es puramente visual y debe ser manejado por el componente padre
+- Para interfaces responsive, considera usar un grid adaptativo para organizar múltiples botones
+
+---
+
+**Versión**: 1.0.0
+**Última actualización**: 2025-11-24
+**Mantenido por**: Equipo Siesa UI Kit