siesa-ui-kit 1.0.3 → 1.0.5

package/src/views/RecoverPasswordView/README.md

@@ -0,0 +1,269 @@
+# RecoverPasswordView
+
+Vista de recuperación de contraseña del sistema Siesa UI Kit.
+
+## Descripción
+
+Vista completa que permite a los usuarios restablecer su contraseña mediante el envío de instrucciones a su correo electrónico. Incluye formulario de validación, mensajes de estado y navegación al login.
+
+## Características
+
+- ✅ **Responsive Design**: Adapta automáticamente entre mobile y desktop
+- ✅ **Dark Mode**: Soporte completo para modo oscuro
+- ✅ **Validación de Email**: Validación básica del formato de email
+- ✅ **Estados**: Loading, error, success
+- ✅ **Accesibilidad**: ARIA labels y manejo semántico de formulario
+- ✅ **Fondo Decorativo**: Opcional, solo visible en desktop
+- ✅ **TypeScript**: Tipos estrictos para todas las props
+
+## Props
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `onSubmit` | `(email: string) => void` | `undefined` | Función que se ejecuta al enviar el formulario |
+| `onBackToLogin` | `() => void` | `undefined` | Función que se ejecuta al hacer clic en "Iniciar Sesión" |
+| `isLoading` | `boolean` | `false` | Si el formulario está en estado de carga |
+| `errorMessage` | `string` | `undefined` | Mensaje de error general a mostrar |
+| `successMessage` | `string` | `undefined` | Mensaje de éxito cuando el email fue enviado |
+| `className` | `string` | `''` | Clases CSS adicionales |
+| `showBackground` | `boolean` | `true` | Si se muestra el fondo decorativo |
+| `variant` | `'responsive' \| 'mobile' \| 'desktop'` | `'responsive'` | Variante de visualización |
+
+## Composición
+
+Esta vista utiliza los siguientes elementos del sistema:
+
+### Elementos visuales
+- **Logo Siesa**: 200x50px
+- **Card contenedor**: 400px width (desktop), full width (mobile)
+- **Fondo decorativo**: Imagen con overlay azul (#dbeefe)
+
+### Campos de formulario
+- **Input de Email**: Con icono de sobre, validación y estados de error
+
+### Botones
+- **Botón principal**: "Reestablecer Contraseña" (primary blue button)
+- **Botón secundario**: "Iniciar Sesión" (outline button)
+
+## Uso Básico
+
+```tsx
+import { RecoverPasswordView } from '@/views/RecoverPasswordView';
+
+function App() {
+  const handleSubmit = (email: string) => {
+    // Lógica para enviar email de recuperación
+    console.log('Recover password for:', email);
+  };
+
+  const handleBackToLogin = () => {
+    // Navegar al login
+    console.log('Back to login');
+  };
+
+  return (
+    <RecoverPasswordView
+      onSubmit={handleSubmit}
+      onBackToLogin={handleBackToLogin}
+    />
+  );
+}
+```
+
+## Estados
+
+### Loading
+
+```tsx
+<RecoverPasswordView
+  isLoading={true}
+  onSubmit={handleSubmit}
+  onBackToLogin={handleBackToLogin}
+/>
+```
+
+### Con Error
+
+```tsx
+<RecoverPasswordView
+  errorMessage="No se pudo enviar el correo. Por favor, intenta nuevamente."
+  onSubmit={handleSubmit}
+  onBackToLogin={handleBackToLogin}
+/>
+```
+
+### Con Éxito
+
+```tsx
+<RecoverPasswordView
+  successMessage="Se han enviado las instrucciones a tu correo electrónico."
+  onSubmit={handleSubmit}
+  onBackToLogin={handleBackToLogin}
+/>
+```
+
+### Sin Fondo
+
+```tsx
+<RecoverPasswordView
+  showBackground={false}
+  onSubmit={handleSubmit}
+  onBackToLogin={handleBackToLogin}
+/>
+```
+
+## Variantes
+
+### Responsive (Default)
+
+Adapta automáticamente según el viewport:
+- **Mobile** (< 768px): Full width, sin sombras, sin bordes redondeados
+- **Desktop** (≥ 768px): Card de 400px centrado, con sombras y bordes redondeados
+
+```tsx
+<RecoverPasswordView variant="responsive" />
+```
+
+### Mobile (Forzado)
+
+Fuerza la visualización móvil en cualquier viewport:
+
+```tsx
+<RecoverPasswordView variant="mobile" />
+```
+
+### Desktop (Forzado)
+
+Fuerza la visualización desktop en cualquier viewport:
+
+```tsx
+<RecoverPasswordView variant="desktop" />
+```
+
+## Responsive Behavior
+
+### Mobile (< 768px)
+- Sin fondo decorativo
+- Card ocupa 100% del ancho
+- Sin sombras ni bordes redondeados
+- Padding interno: 64px
+
+### Desktop (≥ 768px)
+- Fondo decorativo con imagen
+- Card de 400px centrado
+- Sombra elevada
+- Bordes redondeados (16px)
+- Padding interno: 64px
+
+## Dark Mode
+
+La vista implementa dark mode completo en todos sus elementos:
+
+- **Fondos**: `bg-bg-primary` → `dark:bg-dark-bg-primary`
+- **Textos**: `text-content-primary` → `dark:text-dark-content-primary`
+- **Bordes**: `border-[#e4e4e7]` → `dark:border-dark-border-primary`
+- **Inputs**: Fondos y bordes adaptativos
+- **Botones**: Colores inversos en dark mode
+- **Focus rings**: `ring-primary-custom-400` → `dark:ring-[#93d1fd]`
+
+## Validación
+
+La vista incluye validación básica de email:
+
+1. **Email requerido**: El campo no puede estar vacío
+2. **Formato válido**: Valida usando regex `^[^\s@]+@[^\s@]+\.[^\s@]+$`
+3. **Feedback visual**: Borde rojo y mensaje de error cuando el formato es inválido
+
+## Accesibilidad
+
+- Labels descriptivos con `htmlFor`
+- Campo requerido indicado con asterisco rojo
+- Mensajes de error con `role="alert"`
+- Mensajes de éxito con `role="status"`
+- Focus visible en todos los elementos interactivos
+- `autoComplete="email"` para mejor UX
+
+## Storybook
+
+La vista incluye 5 stories:
+
+1. **Desktop**: Estado normal con fondo
+2. **Loading**: Estado de carga
+3. **WithError**: Con mensaje de error
+4. **WithSuccess**: Con mensaje de éxito
+5. **WithoutBackground**: Sin fondo decorativo
+
+Para ver las stories:
+
+```bash
+npm run storybook
+```
+
+Navega a: `Siesa UI Kit/RecoverPasswordView`
+
+## Integración con Router
+
+### React Router
+
+```tsx
+import { useNavigate } from 'react-router-dom';
+import { RecoverPasswordView } from '@/views/RecoverPasswordView';
+
+function RecoverPasswordPage() {
+  const navigate = useNavigate();
+
+  const handleSubmit = async (email: string) => {
+    try {
+      await api.sendPasswordResetEmail(email);
+      // Mostrar mensaje de éxito
+    } catch (error) {
+      // Mostrar mensaje de error
+    }
+  };
+
+  const handleBackToLogin = () => {
+    navigate('/login');
+  };
+
+  return (
+    <RecoverPasswordView
+      onSubmit={handleSubmit}
+      onBackToLogin={handleBackToLogin}
+    />
+  );
+}
+```
+
+## Mejores Prácticas
+
+1. **Siempre proporciona `onSubmit`**: Para manejar el envío del formulario
+2. **Proporciona `onBackToLogin`**: Para navegación al login
+3. **Usa `successMessage`**: Para confirmar al usuario que el email fue enviado
+4. **Usa `errorMessage`**: Para mostrar errores de red o servidor
+5. **Maneja `isLoading`**: Para feedback visual durante el envío
+
+## Archivos del Componente
+
+```
+RecoverPasswordView/
+├── RecoverPasswordView.tsx         # Componente principal (400 líneas)
+├── RecoverPasswordView.types.ts    # TypeScript types
+├── RecoverPasswordView.stories.tsx # Storybook stories (5 stories)
+├── icons.tsx                       # Icono EnvelopeIcon
+├── index.ts                        # Exports
+└── README.md                       # Documentación
+```
+
+## Referencias
+
+- **Diseño Figma**: [Desktop / Recover Password](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=2015-20750)
+- **Sistema de colores**: `docs/colors.md`
+- **Sistema tipográfico**: `docs/typography.md`
+- **Sistema de espaciado**: `docs/spacing.md`
+- **Sistema de sombras**: `docs/shadows.md`
+
+## Versión
+
+- **Versión**: 1.0.0
+- **Última actualización**: 2025-11-12
+- **Figma node-id**: 2015-20750

package/src/views/RecoverPasswordView/RecoverPasswordView.stories.tsx

@@ -0,0 +1,131 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { RecoverPasswordView } from './RecoverPasswordView';
+
+const meta = {
+  title: 'Siesa UI Kit/RecoverPasswordView',
+  component: RecoverPasswordView,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: 'Vista de recuperación de contraseña con formulario de email y navegación al login.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    onSubmit: {
+      description: 'Función que se ejecuta al enviar el formulario',
+      action: 'onSubmit',
+    },
+    onBackToLogin: {
+      description: 'Función que se ejecuta al hacer clic en "Iniciar Sesión"',
+      action: 'onBackToLogin',
+    },
+    isLoading: {
+      control: 'boolean',
+      description: 'Si el formulario está en estado de carga',
+    },
+    errorMessage: {
+      control: 'text',
+      description: 'Mensaje de error general a mostrar',
+    },
+    successMessage: {
+      control: 'text',
+      description: 'Mensaje de éxito a mostrar',
+    },
+    showBackground: {
+      control: 'boolean',
+      description: 'Si se muestra el fondo decorativo',
+    },
+    variant: {
+      control: 'select',
+      options: ['responsive', 'mobile', 'desktop'],
+      description: 'Variante de visualización',
+    },
+  },
+} satisfies Meta<typeof RecoverPasswordView>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ============================================
+// 1. DESKTOP (DEFAULT)
+// ============================================
+export const Desktop: Story = {
+  args: {
+    onSubmit: (email: string) => {
+      console.log('Recover password for:', email);
+      alert(`Se enviarán instrucciones a: ${email}`);
+    },
+    onBackToLogin: () => {
+      console.log('Back to login');
+      alert('Regresar al login');
+    },
+    showBackground: true,
+  },
+  render: (args) => (
+    <div className="min-h-screen w-full">
+      <RecoverPasswordView {...args} />
+    </div>
+  ),
+};
+
+// ============================================
+// 2. LOADING
+// ============================================
+export const Loading: Story = {
+  args: {
+    isLoading: true,
+    showBackground: true,
+  },
+  render: (args) => (
+    <div className="min-h-screen w-full">
+      <RecoverPasswordView {...args} />
+    </div>
+  ),
+};
+
+// ============================================
+// 3. WITH ERROR
+// ============================================
+export const WithError: Story = {
+  args: {
+    errorMessage: 'No se pudo enviar el correo. Por favor, intenta nuevamente.',
+    showBackground: true,
+  },
+  render: (args) => (
+    <div className="min-h-screen w-full">
+      <RecoverPasswordView {...args} />
+    </div>
+  ),
+};
+
+// ============================================
+// 4. WITH SUCCESS
+// ============================================
+export const WithSuccess: Story = {
+  args: {
+    successMessage: 'Se han enviado las instrucciones a tu correo electrónico.',
+    showBackground: true,
+  },
+  render: (args) => (
+    <div className="min-h-screen w-full">
+      <RecoverPasswordView {...args} />
+    </div>
+  ),
+};
+
+// ============================================
+// 5. WITHOUT BACKGROUND
+// ============================================
+export const WithoutBackground: Story = {
+  args: {
+    showBackground: false,
+  },
+  render: (args) => (
+    <div className="min-h-screen w-full">
+      <RecoverPasswordView {...args} />
+    </div>
+  ),
+};