siesa-ui-kit 1.0.3 → 1.0.5

package/src/components/POSNumberButton/README.md

@@ -0,0 +1,321 @@
+# POSNumberButton
+
+Botón numérico especializado para sistemas POS (Point of Sale) con tipografía grande y estados touch-friendly.
+
+## 📋 Características
+
+- ✅ Diseñado específicamente para pantallas táctiles y sistemas POS
+- ✅ Tipografía Display Tiny (48px Bold) para excelente legibilidad
+- ✅ Tres tamaños: Small (40x40), Medium (65x65), Large (80x80)
+- ✅ Opción de borde visible o sin borde
+- ✅ Feedback táctil inmediato con `active:scale-95`
+- ✅ Dark mode completo con todos los estados
+- ✅ Focus rings adaptativos para accesibilidad
+- ✅ TypeScript estricto con props validadas
+- ✅ Tokens del sistema de diseño Siesa
+
+## 🎨 Especificaciones de Figma
+
+Basado en el diseño de Figma:
+- **Node ID**: 4348-23818
+- **Estados**: Default, Touched (Hover/Active)
+- **Tamaños**: L (80x80px), M (65x65px), S (40x40px)
+- **Variantes**: Con borde y sin borde
+- **Tipografía**: Display Tiny (48px Bold / text-5xl)
+- **Border Radius**: 8px (rounded-lg)
+
+## 📦 Instalación
+
+```tsx
+import { POSNumberButton } from '@/components/POSNumberButton';
+```
+
+## 🚀 Uso Básico
+
+### Botón Numérico Simple
+
+```tsx
+<POSNumberButton size="l">
+  1
+</POSNumberButton>
+```
+
+### Botón con Borde
+
+```tsx
+<POSNumberButton size="l" border>
+  2
+</POSNumberButton>
+```
+
+### Teclado Numérico Completo
+
+```tsx
+<div className="grid grid-cols-3 gap-2 max-w-[260px]">
+  {[1, 2, 3, 4, 5, 6, 7, 8, 9].map((num) => (
+    <POSNumberButton
+      key={num}
+      size="l"
+      border
+      onClick={() => handleInput(num)}
+    >
+      {num}
+    </POSNumberButton>
+  ))}
+  <POSNumberButton size="l" border>.</POSNumberButton>
+  <POSNumberButton size="l" border>0</POSNumberButton>
+  <POSNumberButton size="l" border>←</POSNumberButton>
+</div>
+```
+
+## 🎛️ Props
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `size` | `'s' \| 'm' \| 'l'` | `'l'` | Tamaño del botón |
+| `border` | `boolean` | `false` | Si el botón tiene borde visible |
+| `children` | `ReactNode` | - | Contenido del botón (número o texto) |
+| `disabled` | `boolean` | `false` | Si el botón está deshabilitado |
+| `className` | `string` | `''` | Clases CSS adicionales |
+| `onClick` | `(event) => void` | - | Handler para evento click |
+| `ariaLabel` | `string` | - | Label para accesibilidad (ARIA) |
+| `htmlType` | `'button' \| 'submit' \| 'reset'` | `'button'` | Tipo del botón HTML |
+
+## 📐 Tamaños
+
+### Small (40x40px)
+```tsx
+<POSNumberButton size="s">1</POSNumberButton>
+```
+- **Uso**: Calculadoras compactas, espacios reducidos
+- **Tipografía**: text-2xl (24px)
+
+### Medium (65x65px)
+```tsx
+<POSNumberButton size="m">2</POSNumberButton>
+```
+- **Uso**: Tablets, interfaces intermedias
+- **Tipografía**: text-5xl (48px)
+
+### Large (80x80px) - Default
+```tsx
+<POSNumberButton size="l">3</POSNumberButton>
+```
+- **Uso**: POS touch screens, pantallas grandes
+- **Tipografía**: text-5xl (48px)
+
+## 🎨 Variantes
+
+### Sin Borde (Default)
+```tsx
+<POSNumberButton size="l">1</POSNumberButton>
+```
+- Fondo blanco en estado default
+- Cambia a primary-custom-600 en hover/active
+- Texto cambia a primary-inverse-content
+
+### Con Borde
+```tsx
+<POSNumberButton size="l" border>2</POSNumberButton>
+```
+- Borde border-primary visible
+- Cambia a primary-inverse-border en hover/active
+- Mejor separación visual entre botones
+
+## 🌓 Dark Mode
+
+Todos los estados se adaptan automáticamente:
+
+```tsx
+// Light Mode:
+// - Fondo: white (#ffffff)
+// - Texto: content-primary (#18181b)
+// - Hover: bg primary-custom-600, texto primary-inverse-content
+
+// Dark Mode:
+// - Fondo: dark-bg-primary (#18181b)
+// - Texto: dark-content-primary (#ffffff)
+// - Hover: bg dark-bg-inverse, texto dark-content-inverse
+```
+
+## 🎯 Estados
+
+### Default
+```tsx
+<POSNumberButton>1</POSNumberButton>
+```
+- Fondo blanco, texto oscuro
+- Cursor pointer
+
+### Hover
+```tsx
+<POSNumberButton>2</POSNumberButton>
+```
+- Fondo cambia a primary-custom-600
+- Texto cambia a primary-inverse-content
+- Transición suave de 150ms
+
+### Active (Presionado)
+```tsx
+<POSNumberButton>3</POSNumberButton>
+```
+- Mismo estilo que hover
+- Efecto scale-95 para feedback táctil
+- Ideal para pantallas touch
+
+### Focus
+```tsx
+<POSNumberButton>4</POSNumberButton>
+```
+- Focus ring primary-custom-400 (light)
+- Focus ring dark-border-custom (dark)
+- Navegable con teclado (Tab)
+
+### Disabled
+```tsx
+<POSNumberButton disabled>5</POSNumberButton>
+```
+- Opacity 50%
+- Cursor not-allowed
+- Pointer events deshabilitados
+
+## 💡 Casos de Uso
+
+### Sistema POS Completo
+```tsx
+function POSKeypad({ onInput }) {
+  return (
+    <div className="grid grid-cols-3 gap-2 max-w-[260px]">
+      {[1, 2, 3, 4, 5, 6, 7, 8, 9].map((num) => (
+        <POSNumberButton
+          key={num}
+          size="l"
+          border
+          onClick={() => onInput(num)}
+        >
+          {num}
+        </POSNumberButton>
+      ))}
+      <POSNumberButton size="l" border onClick={() => onInput('.')}>
+        .
+      </POSNumberButton>
+      <POSNumberButton size="l" border onClick={() => onInput(0)}>
+        0
+      </POSNumberButton>
+      <POSNumberButton size="l" border onClick={() => onInput('backspace')}>
+        ←
+      </POSNumberButton>
+    </div>
+  );
+}
+```
+
+### Calculadora
+```tsx
+function Calculator() {
+  return (
+    <div className="flex gap-4">
+      {/* Números */}
+      <div className="grid grid-cols-3 gap-2">
+        {[7, 8, 9, 4, 5, 6, 1, 2, 3, 0].map((num) => (
+          <POSNumberButton key={num} size="m" border>
+            {num}
+          </POSNumberButton>
+        ))}
+      </div>
+
+      {/* Operadores */}
+      <div className="grid grid-cols-1 gap-2">
+        {['+', '-', '×', '÷', '='].map((op) => (
+          <POSNumberButton key={op} size="m" border>
+            {op}
+          </POSNumberButton>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Teclado Compacto (Tablet)
+```tsx
+function CompactKeypad() {
+  return (
+    <div className="grid grid-cols-3 gap-2 max-w-[211px]">
+      {[1, 2, 3, 4, 5, 6, 7, 8, 9, '.', 0, '←'].map((key, idx) => (
+        <POSNumberButton key={idx} size="m">
+          {key}
+        </POSNumberButton>
+      ))}
+    </div>
+  );
+}
+```
+
+## 🎨 Tokens Utilizados
+
+### Colores (Light Mode)
+- `bg-white` - Fondo default
+- `text-content-primary` (#18181b) - Texto default
+- `bg-primary-custom-600` (#0e79fd) - Fondo hover/active
+- `text-primary-inverse-content` (#eff8ff) - Texto hover/active
+- `border-border-primary` (#e4e4e7) - Borde default
+- `border-primary-inverse-border` (#3c9bf6) - Borde hover/active
+
+### Colores (Dark Mode)
+- `dark:bg-dark-bg-primary` (#18181b) - Fondo default
+- `dark:text-dark-content-primary` (#ffffff) - Texto default
+- `dark:bg-dark-bg-inverse` (#bfe2fe) - Fondo hover/active
+- `dark:text-dark-content-inverse` (#0e79fd) - Texto hover/active
+- `dark:border-dark-border-primary` (#71717a) - Borde default
+
+### Tipografía
+- `text-5xl` (48px) - Display Tiny para tamaños M y L
+- `text-2xl` (24px) - Heading Small para tamaño S
+- `font-bold` (700) - Peso Bold
+- `tracking-tighter` (-2.5%) - Letter spacing para Display
+
+### Espaciado
+- `rounded-lg` (8px) - Border radius según Figma
+- `gap-2` (8px) - Espaciado entre botones en grids
+
+## ✅ Mejores Prácticas
+
+### ✓ Hacer
+- Usa `size="l"` para pantallas táctiles POS
+- Usa `border={true}` para mejor separación visual en grids
+- Implementa feedback visual inmediato (scale-95 está incluido)
+- Usa aria-label para accesibilidad cuando el contenido no es obvio
+- Combina con grids de 3 columnas para teclados numéricos
+
+### ✗ Evitar
+- No uses tamaños muy pequeños para pantallas touch (mínimo size="m")
+- No omitas el handler onClick en contextos interactivos
+- No uses para botones que no sean numéricos u operadores
+- No sobrescribas las transiciones (son optimizadas para touch)
+
+## 🔗 Referencias
+
+- **Diseño Figma**: [POS Number Button](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4348-23818)
+- **Sistema de Colores**: `docs/colors.md`
+- **Sistema Tipográfico**: `docs/typography.md` (Display Tiny)
+- **Componente Base**: `src/components/Button/Button.tsx`
+
+## 📝 Notas de Implementación
+
+1. **Tipografía Display Tiny**: Según `typography.md`, Display Tiny es 48px (text-5xl) con font-bold y tracking-tighter
+2. **Tamaños Exactos**: Los tamaños están basados en las especificaciones exactas de Figma (80x80, 65x65, 40x40)
+3. **Estados Touch**: El efecto `active:scale-95` proporciona feedback táctil inmediato
+4. **Dark Mode**: Todos los colores usan tokens del sistema que se adaptan automáticamente
+5. **Accesibilidad**: Focus rings optimizados y aria-labels por defecto
+
+## 📅 Historial
+
+| Versión | Fecha | Cambios |
+|---------|-------|---------|
+| 1.0.0 | 2025-11-24 | Implementación inicial del componente |
+
+---
+
+**Autor**: Siesa UI Kit Team
+**Última actualización**: 2025-11-24

package/{dist/components/POSNumberButton/index.d.ts → src/components/POSNumberButton/index.ts}

@@ -1,3 +1,3 @@
-export { POSNumberButton } from './POSNumberButton';
-export type { POSNumberButtonProps } from './POSNumberButton.types';
-//# sourceMappingURL=index.d.ts.map
+// index.ts
+export { POSNumberButton } from './POSNumberButton';
+export type { POSNumberButtonProps } from './POSNumberButton.types';

package/src/components/POSProductButton/POSProductButton.stories.tsx

@@ -0,0 +1,318 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { POSProductButton } from './POSProductButton';
+
+// Imagen de ejemplo (placeholder de Unsplash) 
+const exampleImage = 'https://images.unsplash.com/photo-1546069901-ba9599a7e63c?w=300&h=200&fit=crop';
+
+const meta = {
+  title: 'Siesa UI Kit/POSProductButton',
+  component: POSProductButton,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'Botón especializado para sistemas POS que combina una imagen de producto con un label descriptivo. Diseñado para selección rápida de productos en interfaces de punto de venta.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    image: {
+      control: 'text',
+      description: 'URL de la imagen del producto',
+      table: {
+        type: { summary: 'string' },
+        category: 'Contenido',
+      },
+    },
+    label: {
+      control: 'text',
+      description: 'Texto del producto (nombre o descripción)',
+      table: {
+        type: { summary: 'string' },
+        category: 'Contenido',
+      },
+    },
+    active: {
+      control: 'boolean',
+      description: 'Si el botón está en estado activo/seleccionado',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category: 'Estado',
+      },
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Si el botón está deshabilitado',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category: 'Estado',
+      },
+    },
+    onClick: {
+      action: 'clicked',
+      description: 'Handler para evento click',
+      table: {
+        type: { summary: '(event: MouseEvent<HTMLButtonElement>) => void' },
+        category: 'Comportamiento',
+      },
+    },
+    className: {
+      control: 'text',
+      description: 'Clases CSS adicionales',
+      table: {
+        type: { summary: 'string' },
+        category: 'Apariencia',
+      },
+    },
+    ariaLabel: {
+      control: 'text',
+      description: 'Label para accesibilidad (ARIA)',
+      table: {
+        type: { summary: 'string' },
+        category: 'Accesibilidad',
+      },
+    },
+  },
+} satisfies Meta<typeof POSProductButton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ============================================
+// 1. PLAYGROUND INTERACTIVO
+// ============================================
+export const Playground: Story = {
+  args: {
+    image: exampleImage,
+    label: 'A la parrilla',
+    active: false,
+    disabled: false,
+  },
+};
+
+// ============================================
+// 2. TODOS LOS ESTADOS
+// ============================================
+export const TodosLosEstados: Story = {
+  args: {
+    image: exampleImage,
+    label: 'A la parrilla',
+  },
+  render: () => (
+    <div className="space-y-8 p-6">
+      {/* Estado Enabled (Normal) */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Enabled (Normal)
+        </h3>
+        <div className="flex flex-wrap gap-3">
+          <POSProductButton
+            image={exampleImage}
+            label="A la parrilla"
+          />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          Estado normal del botón, listo para ser clickeado
+        </p>
+      </div>
+
+      {/* Estado Actived (Seleccionado) */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Actived (Seleccionado)
+        </h3>
+        <div className="flex flex-wrap gap-3">
+          <POSProductButton
+            image={exampleImage}
+            label="A la parrilla"
+            active={true}
+          />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          Estado activo cuando el producto está seleccionado
+        </p>
+      </div>
+
+      {/* Estado Disabled (Deshabilitado) */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Disabled (Deshabilitado)
+        </h3>
+        <div className="flex flex-wrap gap-3">
+          <POSProductButton
+            image={exampleImage}
+            label="A la parrilla"
+            disabled={true}
+          />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          Estado deshabilitado con opacidad reducida
+        </p>
+      </div>
+
+      {/* Tips */}
+      <div className="mt-6 p-4 bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-lg">
+        <p className="text-xs text-content-secondary dark:text-content-secondary">
+          <strong>💡 Consejos:</strong>
+          <br />• Usa el estado <code className="px-1 bg-white dark:bg-gray-700">active</code> para indicar el producto seleccionado
+          <br />• Usa el estado <code className="px-1 bg-white dark:bg-gray-700">disabled</code> para productos no disponibles
+          <br />• El botón tiene un aspect ratio de 158:80 para la imagen (según diseño de Figma)
+        </p>
+      </div>
+    </div>
+  ),
+};
+
+// ============================================
+// 3. EJEMPLOS DE USO
+// ============================================
+export const EjemplosDeUso: Story = {
+  args: {
+    image: exampleImage,
+    label: 'A la parrilla',
+  },
+  render: () => (
+    <div className="space-y-8 p-6">
+      {/* Grid de productos */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Grid de Productos (Típico en POS)
+        </h3>
+        <div className="grid grid-cols-3 gap-4 max-w-xl">
+          <POSProductButton
+            image={exampleImage}
+            label="A la parrilla"
+            active={true}
+          />
+          <POSProductButton
+            image={exampleImage}
+            label="Al horno"
+          />
+          <POSProductButton
+            image={exampleImage}
+            label="Frito"
+          />
+          <POSProductButton
+            image={exampleImage}
+            label="Al vapor"
+          />
+          <POSProductButton
+            image={exampleImage}
+            label="Asado"
+          />
+          <POSProductButton
+            image={exampleImage}
+            label="Agotado"
+            disabled={true}
+          />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          Configuración típica de 3 columnas para pantallas de punto de venta
+        </p>
+      </div>
+
+      {/* Lista horizontal */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Lista Horizontal (Categorías)
+        </h3>
+        <div className="flex gap-3 overflow-x-auto pb-2 max-w-2xl">
+          <POSProductButton
+            image={exampleImage}
+            label="Carnes"
+            active={true}
+          />
+          <POSProductButton
+            image={exampleImage}
+            label="Pescados"
+          />
+          <POSProductButton
+            image={exampleImage}
+            label="Vegetales"
+          />
+          <POSProductButton
+            image={exampleImage}
+            label="Postres"
+          />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          Navegación horizontal para categorías de productos
+        </p>
+      </div>
+
+      {/* Con handlers */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Con Handlers de Click
+        </h3>
+        <div className="flex gap-3">
+          <POSProductButton
+            image={exampleImage}
+            label="Click aquí"
+            onClick={() => alert('Producto seleccionado: A la parrilla')}
+          />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          Click en el botón para ver la acción
+        </p>
+      </div>
+    </div>
+  ),
+};
+
+// ============================================
+// 4. VARIACIONES DE CONTENIDO
+// ============================================
+export const VariacionesDeContenido: Story = {
+  args: {
+    image: exampleImage,
+    label: 'A la parrilla',
+  },
+  render: () => (
+    <div className="space-y-8 p-6">
+      {/* Labels cortos */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Labels Cortos
+        </h3>
+        <div className="flex gap-3">
+          <POSProductButton
+            image={exampleImage}
+            label="Carne"
+          />
+          <POSProductButton
+            image={exampleImage}
+            label="Pollo"
+          />
+          <POSProductButton
+            image={exampleImage}
+            label="Pez"
+          />
+        </div>
+      </div>
+
+      {/* Labels largos */}
+      <div>
+        <h3 className="text-sm font-bold mb-4 text-content-primary dark:text-dark-content-primary">
+          Labels Largos
+        </h3>
+        <div className="flex gap-3">
+          <POSProductButton
+            image={exampleImage}
+            label="Parrillada de res con vegetales"
+          />
+          <POSProductButton
+            image={exampleImage}
+            label="Pescado a la plancha con limón"
+          />
+        </div>
+        <p className="text-xs text-content-secondary dark:text-content-secondary mt-2">
+          Los labels largos se ajustan automáticamente
+        </p>
+      </div>
+    </div>
+  ),
+};