@adamosuiteservices/ui 2.11.17 → 2.11.18

package/docs/components/layout/toaster.md

@@ -1,436 +1,436 @@
-# Toaster Component
-
-## Descripción
-
-Sistema de **notificaciones toast** no intrusivas que aparecen en la parte inferior de la pantalla. Incluye sistema de cola automático para múltiples toasts, 4 variantes de color, auto-cierre configurable, y animaciones suaves de entrada/salida.
-
-## Características
-
-- ✅ 4 variantes visuales (default, success, warning, destructive)
-- ✅ Sistema de cola automático para múltiples toasts
-- ✅ Auto-cierre configurable (por defecto 3000ms)
-- ✅ Toasts persistentes (sin auto-cierre)
-- ✅ Animaciones suaves de entrada y salida
-- ✅ Portal rendering para posicionamiento fijo
-- ✅ IDs únicos automáticos
-- ✅ Cierre manual programático
-
-## Importación
-
-```typescript
-import { Toaster, ToastManager } from "@adamosuiteservices/ui/toaster";
-```
-
-## Setup Inicial
-
-Agrega el componente `Toaster` en el nivel más alto de tu aplicación:
-
-```tsx
-import { Toaster } from "@adamosuiteservices/ui/toaster";
-
-function App() {
-  return (
-    <>
-      {/* Tu app aquí */}
-      <Toaster />
-    </>
-  );
-}
-```
-
-**Importante**: Solo necesitas una instancia de `Toaster` en toda tu aplicación.
-
-## Uso Básico
-
-```tsx
-import { ToastManager } from "@adamosuiteservices/ui/toaster";
-import { Button } from "@adamosuiteservices/ui/button";
-
-function MyComponent() {
-  return (
-    <Button
-      onClick={() => {
-        ToastManager.show({
-          message: "Changes have been saved successfully!",
-          variant: "success",
-        });
-      }}
-    >
-      Save Changes
-    </Button>
-  );
-}
-```
-
-## Variantes
-
-### default
-
-Toast informativo general con fondo azul claro.
-
-```tsx
-ToastManager.show({
-  message: "This is a general informational message",
-  variant: "default",
-});
-```
-
-**Estilos**:
-
-- Fondo: `bg-primary-200`
-- Texto: `text-foreground`
-- Uso: Información general, confirmaciones neutrales
-
-### success
-
-Toast verde para acciones exitosas o confirmaciones positivas.
-
-```tsx
-ToastManager.show({
-  message: "Operation completed successfully!",
-  variant: "success",
-});
-```
-
-**Estilos**:
-
-- Fondo: `bg-success-50` (verde claro)
-- Texto: `text-success`
-- Uso: Guardado exitoso, operaciones completadas, confirmaciones
-
-### warning
-
-Toast amarillo para advertencias importantes.
-
-```tsx
-ToastManager.show({
-  message: "Your session will expire in 5 minutes",
-  variant: "warning",
-});
-```
-
-**Estilos**:
-
-- Fondo: `bg-warning-50` (amarillo claro)
-- Texto: `text-warning`
-- Uso: Advertencias, validaciones, alertas preventivas
-
-### destructive
-
-Toast rojo para errores críticos o acciones destructivas.
-
-```tsx
-ToastManager.show({
-  message: "Error: Unable to complete the operation",
-  variant: "destructive",
-});
-```
-
-**Estilos**:
-
-- Fondo: `bg-destructive-50` (rojo claro)
-- Texto: `text-destructive`
-- Uso: Errores, fallos de operación, acciones destructivas
-
-## Duración y Control
-
-### Auto-cierre Personalizado
-
-Por defecto, los toasts se cierran automáticamente después de 3 segundos (3000ms).
-
-```tsx
-// Toast rápido (1 segundo)
-ToastManager.show({
-  message: "Quick notification",
-  variant: "default",
-  autoClose: 1000,
-});
-
-// Toast normal (3 segundos - default)
-ToastManager.show({
-  message: "Normal duration",
-  variant: "success",
-  autoClose: 3000,
-});
-
-// Toast largo (5 segundos)
-ToastManager.show({
-  message: "Important message - read carefully",
-  variant: "warning",
-  autoClose: 5000,
-});
-```
-
-### Toast Persistente
-
-Para mensajes que requieren confirmación del usuario:
-
-```tsx
-// Mostrar toast sin auto-cierre
-ToastManager.show({
-  message: "This message requires your attention",
-  variant: "destructive",
-  autoClose: undefined, // No se cierra automáticamente
-});
-
-// Los toasts persistentes se pueden cerrar manualmente por el usuario
-// haciendo click en el toast o con acciones específicas de tu app
-```
-
-## API
-
-### ToastManager.show()
-
-Método principal para mostrar toasts desde cualquier parte de tu aplicación.
-
-```tsx
-ToastManager.show({
-  message: "Your message here",
-  variant: "success",
-  autoClose: 3000,
-});
-```
-
-### Toast Type
-
-```typescript
-type Toast = {
-  id?: string;
-  message: string;
-  variant?: "default" | "success" | "warning" | "destructive";
-  autoClose?: number;
-  onClose?: () => void;
-};
-```
-
-## Props
-
-### Toast Options
-
-| Prop      | Tipo                                                   | Default       | Descripción                                                                    |
-| --------- | ------------------------------------------------------ | ------------- | ------------------------------------------------------------------------------ |
-| id        | `string`                                               | Auto-generado | Identificador único del toast (opcional)                                       |
-| message   | `string`                                               | -             | **Requerido**. Texto a mostrar                                                 |
-| variant   | `"default" \| "success" \| "warning" \| "destructive"` | `"default"`   | Variante de color                                                              |
-| autoClose | `number \| undefined`                                  | `3000`        | Duración en ms antes de cerrarse automáticamente. `undefined` para persistente |
-| onClose   | `() => void`                                           | `undefined`   | Callback ejecutado cuando el toast se cierra                                   |
-
-### Toaster Component
-
-El componente `Toaster` no requiere props - simplemente inclúyelo en tu app.
-
-| Prop | Tipo | Descripción |
-| ---- | ---- | ----------- |
-| -    | -    | Sin props   |
-
-## Ejemplos de Uso
-
-### Formulario Enviado con Éxito
-
-```tsx
-const handleSubmit = async (data) => {
-  try {
-    await submitForm(data);
-    ToastManager.show({
-      message: "Form submitted successfully! We'll get back to you soon.",
-      variant: "success",
-      autoClose: 4000,
-    });
-  } catch (error) {
-    ToastManager.show({
-      message: "Error: Failed to submit form. Please try again.",
-      variant: "destructive",
-      autoClose: 5000,
-    });
-  }
-};
-```
-
-### Operación de Eliminación
-
-```tsx
-const handleDelete = async (itemId) => {
-  try {
-    await deleteItem(itemId);
-    ToastManager.show({
-      message: "Item deleted permanently",
-      variant: "destructive",
-      autoClose: 3000,
-    });
-  } catch (error) {
-    ToastManager.show({
-      message: "Error: Unable to delete item",
-      variant: "destructive",
-    });
-  }
-};
-```
-
-### Validación de Formulario
-
-```tsx
-const validateForm = (formData) => {
-  if (!formData.email) {
-    ToastManager.show({
-      message: "Please complete all required fields",
-      variant: "warning",
-      autoClose: 4000,
-    });
-    return false;
-  }
-
-  if (!isValidEmail(formData.email)) {
-    ToastManager.show({
-      message: "Please enter a valid email address",
-      variant: "warning",
-      autoClose: 4000,
-    });
-    return false;
-  }
-
-  return true;
-};
-```
-
-### Múltiples Toasts Automáticos
-
-El sistema de cola maneja múltiples toasts automáticamente:
-
-```tsx
-const showMultipleNotifications = () => {
-  // Los toasts se mostrarán secuencialmente
-  ToastManager.show({
-    message: "Step 1: Processing data...",
-    variant: "default",
-    autoClose: 2000,
-  });
-
-  ToastManager.show({
-    message: "Step 2: Validating information...",
-    variant: "default",
-    autoClose: 2000,
-  });
-
-  ToastManager.show({
-    message: "Step 3: Complete!",
-    variant: "success",
-    autoClose: 3000,
-  });
-};
-```
-
-## Características Avanzadas
-
-### Sistema de Cola Automático
-
-El Toaster incluye un sistema de cola interno que previene solapamientos:
-
-- Múltiples toasts se encolan automáticamente
-- Solo se muestra un toast a la vez
-- Cada toast espera a que el anterior se cierre
-- Transiciones suaves entre toasts
-
-### Animaciones CSS
-
-- **Entrada**: `toast-slide-up` - deslizamiento desde abajo con fade in
-- **Salida**: `toast-slide-down` - deslizamiento hacia abajo con fade out
-- Duración: ~300ms para transiciones suaves
-- Clases CSS personalizadas para máximo control
-
-### ID Único Automático
-
-Cada toast genera un ID único automáticamente:
-
-```tsx
-// ID generado automáticamente basado en timestamp
-ToastManager.show({ message: "Hello" });
-
-// O proporciona tu propio ID personalizado
-ToastManager.show({
-  id: "custom-toast-id",
-  message: "Hello with custom ID",
-});
-```
-
-### Callback onClose
-
-Ejecuta lógica personalizada cuando el toast se cierra:
-
-```tsx
-ToastManager.show({
-  message: "Processing...",
-  variant: "default",
-  onClose: () => {
-    console.log("Toast closed");
-    // Lógica adicional después del cierre
-  },
-});
-```
-
-## Implementación Técnica
-
-### Estructura Interna
-
-- **ToastObservable**: Sistema de eventos para comunicación global
-- **ToastManager**: Singleton para mostrar toasts desde cualquier lugar
-- **Toaster**: Componente React que renderiza y maneja los toasts
-- **Portal**: Renderizado fuera del árbol de componentes para posicionamiento fijo
-
-### Estilos y Posicionamiento
-
-- Prefijo `adm:` para evitar conflictos de CSS
-- Posición: `fixed bottom-0 left-0 right-0 z-50`
-- Full-width responsive con padding horizontal
-- Portal rendering para z-index correcto
-
-### Animaciones Personalizadas
-
-```css
-/* Definidas en CSS del componente */
-@keyframes toast-slide-up {
-  from {
-    transform: translateY(100%);
-    opacity: 0;
-  }
-  to {
-    transform: translateY(0);
-    opacity: 1;
-  }
-}
-
-@keyframes toast-slide-down {
-  from {
-    transform: translateY(0);
-    opacity: 1;
-  }
-  to {
-    transform: translateY(100%);
-    opacity: 0;
-  }
-}
-```
-
-## Limitaciones
-
-- ❌ Solo un toast visible a la vez (cola secuencial)
-- ❌ Sin acciones/botones dentro del toast
-- ❌ Sin títulos separados del mensaje
-- ❌ Posición fija (no configurable)
-- ❌ Sin toasts apilados múltiples
-
-## Accesibilidad
-
-- ✅ Contraste de colores adecuado en todas las variantes
-- ✅ Posicionamiento no intrusivo
-- ✅ Auto-cierre configurable
-- ✅ Cierre manual por click
-- ⚠️ Sin `role="alert"` o `aria-live` (mejora futura)
-- ⚠️ Sin navegación por teclado
-
-## Roadmap Futuro
-
-- Soporte para `role="alert"` y `aria-live`
-- Acciones/botones dentro del toast
-- Múltiples posiciones (top, center, corners)
-- Toasts apilados/múltiples simultáneos
-- Navegación por teclado (Escape para cerrar)
+# Toaster Component
+
+## Descripción
+
+Sistema de **notificaciones toast** no intrusivas que aparecen en la parte inferior de la pantalla. Incluye sistema de cola automático para múltiples toasts, 4 variantes de color, auto-cierre configurable, y animaciones suaves de entrada/salida.
+
+## Características
+
+- ✅ 4 variantes visuales (default, success, warning, destructive)
+- ✅ Sistema de cola automático para múltiples toasts
+- ✅ Auto-cierre configurable (por defecto 3000ms)
+- ✅ Toasts persistentes (sin auto-cierre)
+- ✅ Animaciones suaves de entrada y salida
+- ✅ Portal rendering para posicionamiento fijo
+- ✅ IDs únicos automáticos
+- ✅ Cierre manual programático
+
+## Importación
+
+```typescript
+import { Toaster, ToastManager } from "@adamosuiteservices/ui/toaster";
+```
+
+## Setup Inicial
+
+Agrega el componente `Toaster` en el nivel más alto de tu aplicación:
+
+```tsx
+import { Toaster } from "@adamosuiteservices/ui/toaster";
+
+function App() {
+  return (
+    <>
+      {/* Tu app aquí */}
+      <Toaster />
+    </>
+  );
+}
+```
+
+**Importante**: Solo necesitas una instancia de `Toaster` en toda tu aplicación.
+
+## Uso Básico
+
+```tsx
+import { ToastManager } from "@adamosuiteservices/ui/toaster";
+import { Button } from "@adamosuiteservices/ui/button";
+
+function MyComponent() {
+  return (
+    <Button
+      onClick={() => {
+        ToastManager.show({
+          message: "Changes have been saved successfully!",
+          variant: "success",
+        });
+      }}
+    >
+      Save Changes
+    </Button>
+  );
+}
+```
+
+## Variantes
+
+### default
+
+Toast informativo general con fondo azul claro.
+
+```tsx
+ToastManager.show({
+  message: "This is a general informational message",
+  variant: "default",
+});
+```
+
+**Estilos**:
+
+- Fondo: `bg-primary-200`
+- Texto: `text-foreground`
+- Uso: Información general, confirmaciones neutrales
+
+### success
+
+Toast verde para acciones exitosas o confirmaciones positivas.
+
+```tsx
+ToastManager.show({
+  message: "Operation completed successfully!",
+  variant: "success",
+});
+```
+
+**Estilos**:
+
+- Fondo: `bg-success-50` (verde claro)
+- Texto: `text-success`
+- Uso: Guardado exitoso, operaciones completadas, confirmaciones
+
+### warning
+
+Toast amarillo para advertencias importantes.
+
+```tsx
+ToastManager.show({
+  message: "Your session will expire in 5 minutes",
+  variant: "warning",
+});
+```
+
+**Estilos**:
+
+- Fondo: `bg-warning-50` (amarillo claro)
+- Texto: `text-warning`
+- Uso: Advertencias, validaciones, alertas preventivas
+
+### destructive
+
+Toast rojo para errores críticos o acciones destructivas.
+
+```tsx
+ToastManager.show({
+  message: "Error: Unable to complete the operation",
+  variant: "destructive",
+});
+```
+
+**Estilos**:
+
+- Fondo: `bg-destructive-50` (rojo claro)
+- Texto: `text-destructive`
+- Uso: Errores, fallos de operación, acciones destructivas
+
+## Duración y Control
+
+### Auto-cierre Personalizado
+
+Por defecto, los toasts se cierran automáticamente después de 3 segundos (3000ms).
+
+```tsx
+// Toast rápido (1 segundo)
+ToastManager.show({
+  message: "Quick notification",
+  variant: "default",
+  autoClose: 1000,
+});
+
+// Toast normal (3 segundos - default)
+ToastManager.show({
+  message: "Normal duration",
+  variant: "success",
+  autoClose: 3000,
+});
+
+// Toast largo (5 segundos)
+ToastManager.show({
+  message: "Important message - read carefully",
+  variant: "warning",
+  autoClose: 5000,
+});
+```
+
+### Toast Persistente
+
+Para mensajes que requieren confirmación del usuario:
+
+```tsx
+// Mostrar toast sin auto-cierre
+ToastManager.show({
+  message: "This message requires your attention",
+  variant: "destructive",
+  autoClose: undefined, // No se cierra automáticamente
+});
+
+// Los toasts persistentes se pueden cerrar manualmente por el usuario
+// haciendo click en el toast o con acciones específicas de tu app
+```
+
+## API
+
+### ToastManager.show()
+
+Método principal para mostrar toasts desde cualquier parte de tu aplicación.
+
+```tsx
+ToastManager.show({
+  message: "Your message here",
+  variant: "success",
+  autoClose: 3000,
+});
+```
+
+### Toast Type
+
+```typescript
+type Toast = {
+  id?: string;
+  message: string;
+  variant?: "default" | "success" | "warning" | "destructive";
+  autoClose?: number;
+  onClose?: () => void;
+};
+```
+
+## Props
+
+### Toast Options
+
+| Prop      | Tipo                                                   | Default       | Descripción                                                                    |
+| --------- | ------------------------------------------------------ | ------------- | ------------------------------------------------------------------------------ |
+| id        | `string`                                               | Auto-generado | Identificador único del toast (opcional)                                       |
+| message   | `string`                                               | -             | **Requerido**. Texto a mostrar                                                 |
+| variant   | `"default" \| "success" \| "warning" \| "destructive"` | `"default"`   | Variante de color                                                              |
+| autoClose | `number \| undefined`                                  | `3000`        | Duración en ms antes de cerrarse automáticamente. `undefined` para persistente |
+| onClose   | `() => void`                                           | `undefined`   | Callback ejecutado cuando el toast se cierra                                   |
+
+### Toaster Component
+
+El componente `Toaster` no requiere props - simplemente inclúyelo en tu app.
+
+| Prop | Tipo | Descripción |
+| ---- | ---- | ----------- |
+| -    | -    | Sin props   |
+
+## Ejemplos de Uso
+
+### Formulario Enviado con Éxito
+
+```tsx
+const handleSubmit = async (data) => {
+  try {
+    await submitForm(data);
+    ToastManager.show({
+      message: "Form submitted successfully! We'll get back to you soon.",
+      variant: "success",
+      autoClose: 4000,
+    });
+  } catch (error) {
+    ToastManager.show({
+      message: "Error: Failed to submit form. Please try again.",
+      variant: "destructive",
+      autoClose: 5000,
+    });
+  }
+};
+```
+
+### Operación de Eliminación
+
+```tsx
+const handleDelete = async (itemId) => {
+  try {
+    await deleteItem(itemId);
+    ToastManager.show({
+      message: "Item deleted permanently",
+      variant: "destructive",
+      autoClose: 3000,
+    });
+  } catch (error) {
+    ToastManager.show({
+      message: "Error: Unable to delete item",
+      variant: "destructive",
+    });
+  }
+};
+```
+
+### Validación de Formulario
+
+```tsx
+const validateForm = (formData) => {
+  if (!formData.email) {
+    ToastManager.show({
+      message: "Please complete all required fields",
+      variant: "warning",
+      autoClose: 4000,
+    });
+    return false;
+  }
+
+  if (!isValidEmail(formData.email)) {
+    ToastManager.show({
+      message: "Please enter a valid email address",
+      variant: "warning",
+      autoClose: 4000,
+    });
+    return false;
+  }
+
+  return true;
+};
+```
+
+### Múltiples Toasts Automáticos
+
+El sistema de cola maneja múltiples toasts automáticamente:
+
+```tsx
+const showMultipleNotifications = () => {
+  // Los toasts se mostrarán secuencialmente
+  ToastManager.show({
+    message: "Step 1: Processing data...",
+    variant: "default",
+    autoClose: 2000,
+  });
+
+  ToastManager.show({
+    message: "Step 2: Validating information...",
+    variant: "default",
+    autoClose: 2000,
+  });
+
+  ToastManager.show({
+    message: "Step 3: Complete!",
+    variant: "success",
+    autoClose: 3000,
+  });
+};
+```
+
+## Características Avanzadas
+
+### Sistema de Cola Automático
+
+El Toaster incluye un sistema de cola interno que previene solapamientos:
+
+- Múltiples toasts se encolan automáticamente
+- Solo se muestra un toast a la vez
+- Cada toast espera a que el anterior se cierre
+- Transiciones suaves entre toasts
+
+### Animaciones CSS
+
+- **Entrada**: `toast-slide-up` - deslizamiento desde abajo con fade in
+- **Salida**: `toast-slide-down` - deslizamiento hacia abajo con fade out
+- Duración: ~300ms para transiciones suaves
+- Clases CSS personalizadas para máximo control
+
+### ID Único Automático
+
+Cada toast genera un ID único automáticamente:
+
+```tsx
+// ID generado automáticamente basado en timestamp
+ToastManager.show({ message: "Hello" });
+
+// O proporciona tu propio ID personalizado
+ToastManager.show({
+  id: "custom-toast-id",
+  message: "Hello with custom ID",
+});
+```
+
+### Callback onClose
+
+Ejecuta lógica personalizada cuando el toast se cierra:
+
+```tsx
+ToastManager.show({
+  message: "Processing...",
+  variant: "default",
+  onClose: () => {
+    console.log("Toast closed");
+    // Lógica adicional después del cierre
+  },
+});
+```
+
+## Implementación Técnica
+
+### Estructura Interna
+
+- **ToastObservable**: Sistema de eventos para comunicación global
+- **ToastManager**: Singleton para mostrar toasts desde cualquier lugar
+- **Toaster**: Componente React que renderiza y maneja los toasts
+- **Portal**: Renderizado fuera del árbol de componentes para posicionamiento fijo
+
+### Estilos y Posicionamiento
+
+- Prefijo `adm:` para evitar conflictos de CSS
+- Posición: `fixed bottom-0 left-0 right-0 z-50`
+- Full-width responsive con padding horizontal
+- Portal rendering para z-index correcto
+
+### Animaciones Personalizadas
+
+```css
+/* Definidas en CSS del componente */
+@keyframes toast-slide-up {
+  from {
+    transform: translateY(100%);
+    opacity: 0;
+  }
+  to {
+    transform: translateY(0);
+    opacity: 1;
+  }
+}
+
+@keyframes toast-slide-down {
+  from {
+    transform: translateY(0);
+    opacity: 1;
+  }
+  to {
+    transform: translateY(100%);
+    opacity: 0;
+  }
+}
+```
+
+## Limitaciones
+
+- ❌ Solo un toast visible a la vez (cola secuencial)
+- ❌ Sin acciones/botones dentro del toast
+- ❌ Sin títulos separados del mensaje
+- ❌ Posición fija (no configurable)
+- ❌ Sin toasts apilados múltiples
+
+## Accesibilidad
+
+- ✅ Contraste de colores adecuado en todas las variantes
+- ✅ Posicionamiento no intrusivo
+- ✅ Auto-cierre configurable
+- ✅ Cierre manual por click
+- ⚠️ Sin `role="alert"` o `aria-live` (mejora futura)
+- ⚠️ Sin navegación por teclado
+
+## Roadmap Futuro
+
+- Soporte para `role="alert"` y `aria-live`
+- Acciones/botones dentro del toast
+- Múltiples posiciones (top, center, corners)
+- Toasts apilados/múltiples simultáneos
+- Navegación por teclado (Escape para cerrar)