@adamosuiteservices/ui 2.10.12 → 2.11.13

package/docs/components/layout/full-screen-loader.md

@@ -0,0 +1,500 @@
+# Full Screen Loader Component
+
+## Descripción
+
+Overlay de **carga a pantalla completa** que bloquea la interacción del usuario durante operaciones asíncronas. Incluye un spinner animado y un fondo semi-transparente con efecto de backdrop, ideal para indicar operaciones críticas o procesos de carga inicial.
+
+## Características
+
+- ✅ Overlay a pantalla completa con posicionamiento fijo
+- ✅ Fondo semi-transparente (`bg-black/50`)
+- ✅ Spinner animado en color primario
+- ✅ Control programático con `show()` y `hide()`
+- ✅ Patrón observable para sincronización global
+- ✅ Portal rendering para z-index óptimo (`z-100`)
+- ✅ Centrado automático del spinner
+- ✅ Bloqueo de interacción durante carga
+
+## Importación
+
+```typescript
+import {
+  FullScreenLoader,
+  FullScreenLoaderManager,
+} from "@adamosuiteservices/ui/full-screen-loader";
+```
+
+## Setup Inicial
+
+Agrega el componente `FullScreenLoader` en el nivel más alto de tu aplicación:
+
+```tsx
+import { FullScreenLoader } from "@adamosuiteservices/ui/full-screen-loader";
+
+function App() {
+  return (
+    <>
+      {/* Tu app aquí */}
+      <FullScreenLoader />
+    </>
+  );
+}
+```
+
+**Importante**: Solo necesitas una instancia de `FullScreenLoader` en toda tu aplicación.
+
+## Uso Básico
+
+```tsx
+import { FullScreenLoaderManager } from "@adamosuiteservices/ui/full-screen-loader";
+import { Button } from "@adamosuiteservices/ui/button";
+
+function MyComponent() {
+  const handleAsyncOperation = async () => {
+    // Mostrar loader
+    FullScreenLoaderManager.show();
+
+    try {
+      await someAsyncOperation();
+    } finally {
+      // Ocultar loader siempre, incluso si hay error
+      FullScreenLoaderManager.hide();
+    }
+  };
+
+  return <Button onClick={handleAsyncOperation}>Process Data</Button>;
+}
+```
+
+## Patrones de Uso
+
+### Operación Asíncrona Simple
+
+```tsx
+async function fetchData() {
+  FullScreenLoaderManager.show();
+
+  try {
+    const data = await api.getData();
+    return data;
+  } catch (error) {
+    console.error(error);
+  } finally {
+    FullScreenLoaderManager.hide();
+  }
+}
+```
+
+### Múltiples Operaciones en Secuencia
+
+```tsx
+async function processMultipleSteps() {
+  FullScreenLoaderManager.show();
+
+  try {
+    await step1();
+    await step2();
+    await step3();
+  } catch (error) {
+    console.error("Process failed:", error);
+  } finally {
+    FullScreenLoaderManager.hide();
+  }
+}
+```
+
+### Con Timeout Automático
+
+```tsx
+function showTemporaryLoader() {
+  FullScreenLoaderManager.show();
+
+  // Auto-ocultar después de 3 segundos
+  setTimeout(() => {
+    FullScreenLoaderManager.hide();
+  }, 3000);
+}
+```
+
+### Operaciones Paralelas con Promise.all
+
+```tsx
+async function fetchMultipleResources() {
+  FullScreenLoaderManager.show();
+
+  try {
+    const [users, products, orders] = await Promise.all([
+      api.getUsers(),
+      api.getProducts(),
+      api.getOrders(),
+    ]);
+
+    return { users, products, orders };
+  } finally {
+    FullScreenLoaderManager.hide();
+  }
+}
+```
+
+### Navegación con Next.js Router
+
+```tsx
+import { useRouter } from "next/navigation";
+import { FullScreenLoaderManager } from "@adamosuiteservices/ui/full-screen-loader";
+
+function NavigationComponent() {
+  const router = useRouter();
+
+  const handleNavigation = () => {
+    FullScreenLoaderManager.show();
+    router.push("/dashboard");
+    // El loader se ocultará después de que la página cargue
+    // Puedes usar un useEffect en la página de destino para ocultarlo
+  };
+
+  return <Button onClick={handleNavigation}>Go to Dashboard</Button>;
+}
+```
+
+### Carga Inicial de la Aplicación
+
+```tsx
+import { FullScreenLoaderManager } from "@adamosuiteservices/ui/full-screen-loader";
+import { useEffect } from "react";
+
+function App() {
+  useEffect(() => {
+    // Mostrar loader al inicio
+    FullScreenLoaderManager.show();
+
+    // Inicializar la app
+    initializeApp().then(() => {
+      FullScreenLoaderManager.hide();
+    });
+  }, []);
+
+  return (
+    <>
+      {/* App content */}
+      <FullScreenLoader />
+    </>
+  );
+}
+```
+
+## API Reference
+
+### FullScreenLoaderManager
+
+Clase singleton para controlar el estado del loader globalmente.
+
+#### `show()`
+
+Muestra el loader de pantalla completa.
+
+```tsx
+FullScreenLoaderManager.show();
+```
+
+**Uso**: Llamar antes de iniciar operaciones que requieran bloquear la UI.
+
+#### `hide()`
+
+Oculta el loader de pantalla completa.
+
+```tsx
+FullScreenLoaderManager.hide();
+```
+
+**Uso**: Llamar después de completar operaciones, siempre en un bloque `finally` para garantizar ejecución.
+
+## Comportamiento
+
+### Estado Global
+
+El loader usa un patrón observable que sincroniza el estado en toda la aplicación:
+
+- Una sola instancia de `FullScreenLoader` responde a todos los llamados de `show()`/`hide()`
+- Múltiples componentes pueden controlar el loader sin conflictos
+- El estado se mantiene consistente incluso con navegación
+
+### Z-Index y Posicionamiento
+
+- **z-index**: `z-100` para estar sobre todo el contenido
+- **Posicionamiento**: `fixed` con `inset-0` (cubre toda la ventana)
+- **Centrado**: Flexbox con `items-center` y `justify-center`
+
+### Estilos Visuales
+
+```css
+/* Overlay background */
+bg-black/50  /* Negro con 50% opacidad */
+
+/* Spinner */
+text-4xl      /* Tamaño grande del spinner */
+text-primary  /* Color primario del tema */
+```
+
+## Best Practices
+
+### ✅ DO: Usar `finally` para Garantizar Hide
+
+```tsx
+async function operation() {
+  FullScreenLoaderManager.show();
+  try {
+    await asyncOperation();
+  } finally {
+    // ✅ Siempre se ejecuta, incluso si hay error
+    FullScreenLoaderManager.hide();
+  }
+}
+```
+
+### ❌ DON'T: Olvidar Ocultar el Loader
+
+```tsx
+async function operation() {
+  FullScreenLoaderManager.show();
+  await asyncOperation();
+  // ❌ Si hay error, el loader queda visible
+  FullScreenLoaderManager.hide();
+}
+```
+
+### ✅ DO: Una Sola Instancia en la App
+
+```tsx
+// ✅ En App.tsx o layout principal
+function App() {
+  return (
+    <>
+      <YourApp />
+      <FullScreenLoader />
+    </>
+  );
+}
+```
+
+### ❌ DON'T: Múltiples Instancias
+
+```tsx
+// ❌ No crear múltiples instancias
+function PageA() {
+  return (
+    <>
+      <Content />
+      <FullScreenLoader /> {/* ❌ Redundante */}
+    </>
+  );
+}
+```
+
+### ✅ DO: Operaciones Críticas y Largas
+
+```tsx
+// ✅ Bueno para: autenticación, carga inicial, procesamiento pesado
+async function authenticate() {
+  FullScreenLoaderManager.show();
+  await login();
+  FullScreenLoaderManager.hide();
+}
+```
+
+### ❌ DON'T: Operaciones Rápidas o Menores
+
+```tsx
+// ❌ No usar para operaciones menores de 500ms
+async function quickAction() {
+  FullScreenLoaderManager.show(); // ❌ Muy intrusivo
+  await quickApi(); // < 500ms
+  FullScreenLoaderManager.hide();
+}
+
+// ✅ Mejor usar un spinner local o skeleton
+```
+
+## Casos de Uso
+
+### ✅ Recomendado Para:
+
+- **Autenticación y Login**: Procesos de inicio de sesión
+- **Carga Inicial**: Primera carga de datos de la aplicación
+- **Navegación Crítica**: Cambios de página con carga pesada
+- **Procesamiento Pesado**: Cálculos complejos o batch operations
+- **Uploads Grandes**: Subida de archivos que bloquean la UI
+- **Transacciones Críticas**: Operaciones que no deben interrumpirse
+
+### ❌ No Recomendado Para:
+
+- **Operaciones Rápidas** (< 500ms): Usar spinner local
+- **Búsquedas en Tiempo Real**: Usar loading states inline
+- **Validaciones de Formulario**: Usar feedback local
+- **Acciones Menores**: Usar botones con loading state
+- **Scroll Infinito**: Usar skeleton loaders
+
+## Accesibilidad
+
+El componente incluye consideraciones básicas de accesibilidad:
+
+- **Portal rendering**: Asegura que el loader esté en el nivel superior del DOM
+- **Fixed positioning**: Garantiza visibilidad sobre todo el contenido
+- **Visual feedback**: Spinner animado claramente visible
+
+### Mejoras Sugeridas
+
+Para aplicaciones con requisitos estrictos de accesibilidad, considera agregar:
+
+```tsx
+<div role="dialog" aria-modal="true" aria-label="Loading" aria-busy="true">
+  <Spinner />
+</div>
+```
+
+## Troubleshooting
+
+### El loader no aparece
+
+**Causa**: Falta el componente `<FullScreenLoader />` en la aplicación.
+
+**Solución**: Agregar en el nivel más alto de tu app (App.tsx, layout, etc.).
+
+### El loader queda visible permanentemente
+
+**Causa**: No se llamó `hide()` después de una operación, probablemente debido a un error.
+
+**Solución**: Siempre usar bloque `try/finally` para garantizar que `hide()` se ejecute.
+
+```tsx
+try {
+  await operation();
+} finally {
+  FullScreenLoaderManager.hide(); // ✅ Siempre se ejecuta
+}
+```
+
+### El loader aparece detrás de otros elementos
+
+**Causa**: Algún elemento tiene un `z-index` mayor que 100.
+
+**Solución**: El loader usa `z-100`. Verifica que ningún elemento tenga un z-index mayor. Si es necesario, ajusta el z-index del loader.
+
+### Múltiples loaders aparecen simultáneamente
+
+**Causa**: Múltiples instancias de `<FullScreenLoader />` en la aplicación.
+
+**Solución**: Solo debe haber una instancia en toda la aplicación, en el nivel más alto.
+
+## Integración con Otros Componentes
+
+### Con React Query
+
+```tsx
+import { useMutation } from "@tanstack/react-query";
+import { FullScreenLoaderManager } from "@adamosuiteservices/ui/full-screen-loader";
+
+function MyComponent() {
+  const mutation = useMutation({
+    mutationFn: saveData,
+    onMutate: () => {
+      FullScreenLoaderManager.show();
+    },
+    onSettled: () => {
+      FullScreenLoaderManager.hide();
+    },
+  });
+
+  return <Button onClick={() => mutation.mutate()}>Save</Button>;
+}
+```
+
+### Con Redux/Zustand
+
+```tsx
+// En tu action/slice
+export const fetchData = createAsyncThunk("data/fetch", async () => {
+  FullScreenLoaderManager.show();
+  try {
+    const data = await api.getData();
+    return data;
+  } finally {
+    FullScreenLoaderManager.hide();
+  }
+});
+```
+
+### Con Form Submit
+
+```tsx
+import { useForm } from "react-hook-form";
+import { FullScreenLoaderManager } from "@adamosuiteservices/ui/full-screen-loader";
+
+function FormComponent() {
+  const { handleSubmit } = useForm();
+
+  const onSubmit = async (data) => {
+    FullScreenLoaderManager.show();
+    try {
+      await api.submitForm(data);
+    } finally {
+      FullScreenLoaderManager.hide();
+    }
+  };
+
+  return <form onSubmit={handleSubmit(onSubmit)}>...</form>;
+}
+```
+
+## Componentes Relacionados
+
+- **[Spinner](../../ui/spinner.md)**: Loading indicator usado internamente
+- **[Button](../../ui/button.md)**: Para triggers de operaciones con loading state
+- **[Toaster](./toaster.md)**: Para feedback después de operaciones (combinar con loader)
+
+## Ejemplo Completo
+
+```tsx
+import {
+  FullScreenLoader,
+  FullScreenLoaderManager,
+} from "@adamosuiteservices/ui/full-screen-loader";
+import { ToastManager } from "@adamosuiteservices/ui/toaster";
+import { Button } from "@adamosuiteservices/ui/button";
+
+function App() {
+  return (
+    <>
+      <Dashboard />
+      <FullScreenLoader />
+    </>
+  );
+}
+
+function Dashboard() {
+  const handleSync = async () => {
+    FullScreenLoaderManager.show();
+
+    try {
+      await syncData();
+      ToastManager.show({
+        message: "Data synchronized successfully",
+        variant: "success",
+      });
+    } catch (error) {
+      ToastManager.show({
+        message: "Failed to synchronize data",
+        variant: "destructive",
+      });
+    } finally {
+      FullScreenLoaderManager.hide();
+    }
+  };
+
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <Button onClick={handleSync}>Sync Data</Button>
+    </div>
+  );
+}
+```

package/docs/components/ui/accordion-rounded.md

@@ -107,7 +107,7 @@ Contenedor individual de cada item del accordion.
 **Estilos aplicados**:
 
 - `rounded-2xl`: Bordes muy redondeados
-- `bg-neutrals-50`: Fondo gris claro
+- `bg-muted`: Fondo gris claro
 - `mb-4`: Margen inferior de 1rem
 - `last:mb-0`: Sin margen en el último item
 
@@ -246,7 +246,7 @@ Solo un item abierto a la vez:
     />
     <AccordionContent>
       <div className="p-4 space-y-3">
-        <div className="rounded-lg border border-neutrals-200 p-3">
+        <div className="rounded-lg border p-3">
           <h4 className="text-sm font-semibold text-foreground">Full Name</h4>
           <p className="text-sm text-foreground mt-1">Required field</p>
         </div>
@@ -374,21 +374,21 @@ Varios items pueden estar abiertos simultáneamente:
     />
     <AccordionContent>
       <div className="p-4 space-y-4">
-        <div className="flex items-center justify-between p-3 bg-neutrals-50 rounded-lg">
+        <div className="flex items-center justify-between p-3 bg-muted rounded-lg">
           <div>
             <p className="text-sm font-semibold text-foreground">
               Credit Card
             </p>
             <p className="text-xs text-muted-foreground">•••• 4242</p>
           </div>
-          <span className="text-xs text-success-600 font-medium">Active</span>
+          <span className="text-xs text-success font-medium">Active</span>
         </div>
-        <div className="flex items-center justify-between p-3 bg-neutrals-50 rounded-lg">
+        <div className="flex items-center justify-between p-3 bg-muted rounded-lg">
           <div>
             <p className="text-sm font-semibold text-foreground">PayPal</p>
             <p className="text-xs text-muted-foreground">user@example.com</p>
           </div>
-          <span className="text-xs text-success-600 font-medium">Active</span>
+          <span className="text-xs text-success font-medium">Active</span>
         </div>
       </div>
     </AccordionContent>
@@ -548,7 +548,7 @@ Sin badges para diseño minimalista:
 | Característica     | Accordion Regular       | Accordion Rounded                 |
 | ------------------ | ----------------------- | --------------------------------- |
 | Bordes             | Esquinas cuadradas      | `rounded-2xl` (muy redondeado)    |
-| Fondo del Item     | Transparente con border | `bg-neutrals-50` (gris claro)     |
+| Fondo del Item     | Transparente con border | `bg-muted` (gris claro)           |
 | Separación         | Border entre items      | Margen `mb-4` entre items         |
 | Badge Support      | No (solo children)      | Sí (prop `badge` dedicada)        |
 | Estilo del Título  | Normal                  | Mayúsculas, compacto, color gris  |

package/docs/components/ui/accordion.md

@@ -236,7 +236,7 @@ El trigger incluye hover effect con subrayado:
   <AccordionItem value="phase-1">
     <AccordionTrigger>
       <div className="flex items-center gap-2">
-        <CheckCircleIcon className="h-4 w-4" />
+        <Icon symbol="check_circle" className="text-lg" />
         Phase 1: Planning
       </div>
     </AccordionTrigger>
@@ -260,7 +260,7 @@ El trigger incluye hover effect con subrayado:
 
 - Usa Radix UI Accordion internamente
 - Todos los estilos tienen prefijo ``
-- El icono ChevronDown se incluye automáticamente en el trigger
+- El icono keyboard_arrow_down se incluye automáticamente en el trigger
 - Las animaciones son manejadas por CSS y data attributes
 
 ## Referencias

package/docs/components/ui/alert.md

@@ -344,15 +344,15 @@ import { Progress } from "@adamosuiteservices/ui/progress";
       </div>
       <div className="flex gap-4 justify-between">
         <span>Memory usage:</span>
-        <span className="text-green-600">-23%</span>
+        <span className="text-success">-23%</span>
       </div>
       <div className="flex gap-4 justify-between">
         <span>CPU usage:</span>
-        <span className="text-green-600">-31%</span>
+        <span className="text-success">-31%</span>
       </div>
       <div className="flex gap-4 justify-between">
         <span>Battery life:</span>
-        <span className="text-green-600">+18%</span>
+        <span className="text-success">+18%</span>
       </div>
     </div>
   </AlertDescription>

package/docs/components/ui/avatar.md

@@ -378,16 +378,16 @@ Para mostrar estado online/offline/busy:
     <AvatarFallback>JD</AvatarFallback>
   </Avatar>
   {/* Indicador de estado */}
-  <span className="absolute bottom-0 right-0 block h-3 w-3 rounded-full bg-green-500 ring-2 ring-background" />
+  <span className="absolute bottom-0 right-0 block h-3 w-3 rounded-full bg-success ring-2 ring-background" />
 </div>
 ```
 
 **Variantes de estado**:
 
-- `bg-green-500`: Online
+- `bg-success`: Online
 - `bg-gray-400`: Offline
-- `bg-yellow-500`: Away/Idle
-- `bg-red-500`: Busy/Do Not Disturb
+- `bg-warning`: Away/Idle
+- `bg-destructive`: Busy/Do Not Disturb
 
 ### Avatar con Badge
 
@@ -525,7 +525,7 @@ Mantén tamaños consistentes por contexto:
 ```tsx
 <Avatar>
   <AvatarImage src={url} alt="User" />
-  <AvatarFallback className="bg-blue-500 text-white">AB</AvatarFallback>
+  <AvatarFallback className="bg-primary text-primary-foreground">AB</AvatarFallback>
 </Avatar>
 ```
 
@@ -534,11 +534,11 @@ Mantén tamaños consistentes por contexto:
 ```typescript
 function getAvatarColor(name: string): string {
   const colors = [
-    "bg-red-500",
-    "bg-blue-500",
-    "bg-green-500",
-    "bg-yellow-500",
-    "bg-purple-500",
+    "bg-destructive",
+    "bg-primary",
+    "bg-success",
+    "bg-warning",
+    "bg-primary",
   ];
   const index = name.charCodeAt(0) % colors.length;
   return colors[index];