@royaltics/ui 1.8.9 → 1.9.1

package/README.http_query.md

@@ -1,332 +1,87 @@
-# Sistema de Query HTTP Custom
-
-Sistema de gestión de estado HTTP similar a `@tanstack/react-query` pero optimizado, sin dependencias innecesarias y con mejor rendimiento.
-
-## Características
-
-- ✅ **Caché inteligente** con staleTime y gcTime configurables
-- ✅ **Deduplicación automática** de requests simultáneas
-- ✅ **Reintentos automáticos** con backoff exponencial
-- ✅ **Refetch en window focus** configurable
-- ✅ **Infinite queries** con paginación cursor-based
-- ✅ **Optimistic updates** para mutaciones
-- ✅ **TypeScript estricto** sin `any`
-- ✅ **FormData optimizado** con archivos al final
-- ✅ **Garbage collection** automático de queries no usadas
-
-## Instalación
-
-```tsx
-import { HttpProvider } from 'royaltics-libs/providers/http-provider';
-
-function App() {
-  return (
-    <HttpProvider
-      baseUrl="https://api.example.com"
-      debug={false}
-      initialHeaders={{ 'X-App-Version': '1.0.0' }}
-      onNotAuth={(url) => window.location.href = '/login'}
-    >
-      <YourApp />
-    </HttpProvider>
-  );
-}
-```
-
-## Uso Básico
-
-### useQuery - Consultas GET con caché
-
-```tsx
-import useHttpState from 'royaltics-libs/hooks/useHttpState';
-
-function UserProfile({ userId }: { userId: string }) {
-  const http = useHttpState();
-  
-  const { data, isLoading, error, refetch } = http.useQuery<User>(
-    ['users', userId],
-    {
-      cacheOptions: {
-        staleTime: 5 * 60 * 1000, // 5 minutos
-        gcTime: 10 * 60 * 1000,   // 10 minutos
-        refetchOnWindowFocus: true,
-        retry: 3
-      },
-      onSuccess: (user) => console.log('Usuario cargado:', user),
-      onError: (message) => console.error('Error:', message)
-    }
-  );
-
-  if (isLoading) return <div>Cargando...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  
-  return (
-    <div>
-      <h1>{data?.name}</h1>
-      <button onClick={refetch}>Recargar</button>
-    </div>
-  );
-}
-```
-
-### useMutation - Mutaciones POST/PUT/PATCH/DELETE
-
-```tsx
-function CreatePost() {
-  const http = useHttpState();
-  
-  const { mutate, isLoading, data } = http.useMutation<Post>(
-    ['posts'],
-    {
-      method: 'POST',
-      mutationOptions: {
-        invalidateKeys: [['posts'], ['user', 'posts']], // Invalida estas queries
-        optimisticData: { title: 'Nuevo post...', id: 'temp' } // Update optimista
-      },
-      onSuccess: (post) => console.log('Post creado:', post),
-      onError: (message) => console.error('Error:', message)
-    }
-  );
-
-  const handleSubmit = (e: FormEvent) => {
-    e.preventDefault();
-    mutate({
-      title: 'Mi nuevo post',
-      content: 'Contenido del post'
-    });
-  };
-
-  return (
-    <form onSubmit={handleSubmit}>
-      <button type="submit" disabled={isLoading}>
-        {isLoading ? 'Creando...' : 'Crear Post'}
-      </button>
-    </form>
-  );
-}
-```
-
-### useInfiniteQuery - Paginación infinita
-
-```tsx
-function PostList() {
-  const http = useHttpState();
-  
-  const { pages, isLoading, hasNextPage, fetchNextPage, isFetchingNextPage } = 
-    http.useInfiniteQuery<Post[]>(
-      ['posts', 'infinite'],
-      {
-        infiniteOptions: {
-          cursorKey: 'cursor' // Nombre del parámetro de paginación
-        },
-        cacheOptions: {
-          staleTime: 2 * 60 * 1000
-        }
-      }
-    );
-
-  return (
-    <div>
-      {pages.map((page, i) => (
-        <div key={i}>
-          {page.map(post => (
-            <PostCard key={post.id} post={post} />
-          ))}
-        </div>
-      ))}
-      
-      {hasNextPage && (
-        <button onClick={fetchNextPage} disabled={isFetchingNextPage}>
-          {isFetchingNextPage ? 'Cargando...' : 'Cargar más'}
-        </button>
-      )}
-    </div>
-  );
-}
-```
-
-## Métodos Directos (sin caché)
-
-### GET Request
-
-```tsx
-const http = useHttpState();
-
-http.get(['users', userId], {
-  data: { include: 'posts' },
-  onSuccess: (user) => console.log(user),
-  onError: (message) => console.error(message)
-});
-```
-
-### POST Request
-
-```tsx
-http.post(['posts'], {
-  data: { title: 'Nuevo post', content: 'Contenido' },
-  onSuccess: (post) => console.log('Creado:', post)
-});
-```
-
-### Upload de Archivos
-
-```tsx
-// FormData simple
-http.file(['upload'], {
-  method: 'POST',
-  content_type: 'file',
-  data: {
-    title: 'Mi imagen',
-    description: 'Descripción',
-    photo: [fileObject], // Los archivos siempre van al final
-    tags: ['tag1', 'tag2']
-  },
-  onSuccess: (response) => console.log('Subido:', response)
-});
-
-// Upload por chunks (archivos grandes)
-http.fileChunks(['upload', 'large'], {
-  data: { file: largeFile, metadata: { type: 'video' } },
-  chunkSize: 2 * 1024 * 1024, // 2MB por chunk
-  onProgress: (percent, display) => {
-    console.log(`Progreso: ${percent}% - ${display}`);
-  },
-  onSuccess: (response) => console.log('Completado:', response)
-});
-```
-
-## QueryManager API
-
-Acceso directo al query manager:
-
-```tsx
-const http = useHttpState();
-const { queryManager } = http;
-
-// Obtener datos de caché
-const userData = queryManager.getQueryData<User>(['users', userId]);
-
-// Actualizar caché manualmente
-queryManager.setQueryData(['users', userId], updatedUser);
-
-// Invalidar queries (fuerza refetch)
-queryManager.invalidateQueries(['users']);
-
-// Prefetch (cargar en background)
-queryManager.prefetchQuery(
-  ['posts', 'featured'],
-  () => fetch('/api/posts/featured').then(r => r.json())
-);
-
-// Reset queries (limpiar caché)
-queryManager.resetQueries(['users']); // Específica
-queryManager.resetQueries(); // Todas
-```
-
-## Configuración de Headers
-
-```tsx
-const http = useHttpState();
-const { setHeaders } = useHttpContext();
-
-// Actualizar headers globalmente
-setHeaders({ authorization: `Bearer ${token}` });
-
-// O con función
-setHeaders(prev => ({
-  ...prev,
-  'X-Custom-Header': 'value'
-}));
-
-// Headers por request
-http.get(['users'], {
-  headers: { 'X-Request-ID': uuid() }
-});
-```
-
-## buildBody Mejorado
-
-La función `buildBody` ahora garantiza que los archivos siempre vayan al final del FormData:
-
-```tsx
-const data = {
-  title: 'Post con imagen',
-  tags: ['tag1', 'tag2'],
-  metadata: { author: 'John' },
-  photo: [imageFile], // Archivo - irá al final
-  z_attached: [pdfFile] // Archivo - irá al final
-};
-
-// FormData resultante:
-// 1. title: "Post con imagen"
-// 2. tags: ["tag1","tag2"]
-// 3. metadata: {"author":"John"}
-// 4. photo[]: File (imagen)
-// 5. z_attached[]: File (pdf)
-```
-
-Esto soluciona el problema donde algunos backends no recibían los datos regulares si los archivos iban primero.
-
-## Mejoras vs React Query
-
-1. **Menor tamaño**: Sin dependencias innecesarias
-2. **Deduplicación mejorada**: Requests idénticas comparten la misma Promise
-3. **Tipos más estrictos**: Sin `any`, todo tipado con `unknown` o genéricos
-4. **FormData optimizado**: Archivos siempre al final
-5. **API más simple**: Menos configuración, más convenciones
-6. **Retry con backoff**: Espera exponencial entre reintentos (1s, 2s, 3s...)
-7. **Refetch real**: `invalidateQueries` ejecuta el fetch, no solo marca como stale
-
-## Tipos TypeScript
-
-```tsx
-interface UseHttpResult<T> {
-  data: T | null;
-  isLoading: boolean;
-  error: Error | null;
-  refetch?: () => void;
-}
-
-interface UseInfiniteHttpResult<T> extends UseHttpResult<T> {
-  pages: T[];
-  fetchNextPage: () => void;
-  hasNextPage: boolean;
-  isFetchingNextPage: boolean;
-}
-
-interface UseMutationResult<T> {
-  mutate: (data: Record<string, unknown>) => void;
-  isLoading: boolean;
-  error: Error | null;
-  data: T | null;
-}
-```
-
-## Notas de Rendimiento
-
-- **Deduplicación**: Múltiples componentes solicitando la misma query comparten el request
-- **Garbage Collection**: Queries sin suscriptores se eliminan después de `gcTime`
-- **Stale Time**: Datos se consideran frescos durante `staleTime`, evitando refetches innecesarios
-- **Window Focus**: Refetch automático al volver a la pestaña (configurable)
-- **Subscripción eficiente**: Solo notifica a componentes suscritos a cada query específica
-
-## Migración desde React Query
-
-```tsx
-// React Query
-import { useQuery, useMutation } from '@tanstack/react-query';
-
-const { data } = useQuery({
-  queryKey: ['users', id],
-  queryFn: () => fetchUser(id)
-});
-
-// Sistema Custom
-const http = useHttpState();
-
-const { data } = http.useQuery(['users', id], {
-  cacheOptions: { queryKey: ['users', id] }
-});
-```
-
-La API es similar pero más simple y directa.
+# @royaltics/ui - HTTP Store & Hooks
+
+The new HTTP system replaces the previous `<HttpProvider>` component entirely. It leverages a clean `Zustand` vanilla store to allow initialization at the root module level, drastically increasing integration flexibility and making sure subsequent API requests made outside of React bindings (like React Router loaders) can safely reuse context.
+
+## 1. Global Environment Initialization
+To configure your global default `baseUrl`, `headers`, and refresh logic, simply call `initHttpOptions` once before you interact with the system or within your main application entry file (`main.tsx` or `App.tsx` outside of the component render).
+
+```tsx
+import { initHttpOptions } from '@royaltics/ui/hooks';
+
+// Setup at the root of your project
+initHttpOptions({
+  baseUrl: 'https://api.example.com',
+  debug: false,
+  headers: { 'X-App-Version': '1.0.0' },
+  onHttpError: (err) => console.error("Global Catch", err),
+  onNotAuth: (url) => window.location.href = '/login',
+  refreshConfig: {
+    url: '/auth/refresh',
+    maxAttempts: 1,
+    onSuccess: (res) => console.log('Refreshed token!')
+  }
+});
+```
+*Note: Because this modifies the vanilla store, you no longer need to wrap your components in `<HttpProvider>`.*
+
+## 2. Reading State Direct from Store
+Should you need access to the underlying configurations anywhere in a React component, use `useHttpStore`.
+
+```tsx
+import { useHttpStore } from '@royaltics/ui/hooks';
+
+const AppConfigViewer = () => {
+    // Read strictly the properties you need
+    const { online, baseUrl } = useHttpStore();
+
+    return <div>{online ? 'Online' : 'Offline'}</div>
+}
+```
+
+## 3. Data Fetching via useHttpState
+The highly modular `useHttpState` hook powers your data fetching (GET, POST, PATCH, DELETE, FILE) while providing granular component-scoped state properties (`isLoading`, `error`, etc) and automated subscriptions mapping.
+
+```tsx
+import { useHttpState } from '@royaltics/ui/hooks';
+
+const UsersList = () => {
+  const { get, post, isLoading, getInfinite, fetchNextPage } = useHttpState();
+
+  const fetchUsers = () => {
+    get('/users', {
+        // Query param formatting
+        query: { active: true }, 
+        onSuccess: (data, paginate) => {
+            console.log(data, paginate);
+        },
+        onError: (message) => {
+            console.error(message);
+        }
+    });
+  };
+
+  const submitUser = () => {
+      post('/users', {
+          data: { name: 'John Doe' },
+          onSuccess: (data) => console.log('Created!')
+      });
+  }
+
+  return (
+    <div>
+      <button onClick={fetchUsers} disabled={isLoading}>Load Users</button>
+      <button onClick={submitUser} disabled={isLoading}>Create User</button>
+    </div>
+  );
+};
+```
+
+### Supported HTTP verbs in `useHttpState`:
+- `get(api, opts)`
+- `getInfinite(api, opts)`
+- `post(api, opts)`
+- `patch(api, opts)`
+- `postPatch(api, id, opts)`
+- `del(api, opts)`
+- `file(api, opts)`
+- `fileChunks(api, opts)`

package/README.socket.md

@@ -0,0 +1,126 @@
+# @royaltics/ui - WebSocket Store & Hooks
+
+The WebSocket system has been refactored to use a global `Zustand` store, entirely removing the need for a `<WebSocketProviderContext>` React wrapper. This allows you to initialize socket connections anywhere in your application (even outside of React components) and strictly ties connections to the `socket.io-client` lifecycle.
+
+## 1. Global Socket Initialization
+To initialize your socket connection globally, call `initSocketOptions`. You should only do this once, typically in your application's entry file or authentication hook.
+
+```tsx
+import { initSocketOptions } from '@royaltics/ui/hooks';
+
+// Call this when the user logs in or app initializes
+initSocketOptions({
+  socketUrl: 'https://socket.example.com',
+  token: 'YOUR_AUTH_TOKEN_HERE',
+  options: {
+    // Standard socket.io ManagerOptions & SocketOptions
+    reconnection: true,
+    reconnectionAttempts: 5,
+  },
+  onAuthError: (err) => {
+      // Triggered when socket.io 'connect_error' is fired. 
+      // You can implement token refreshing mechanisms and then re-call `initSocketOptions({ ...newConfig })`
+      console.error("Socket authentication failed", err);
+  }
+});
+```
+*Note: If you call `initSocketOptions` with an empty `socketUrl` or `token`, it will automatically disconnect the socket.*
+
+## 2. Reading Global Socket State
+You can read the socket connection status directly using the `useSocketStore` hook anywhere in your component tree.
+
+```tsx
+import { useSocketState } from '@royaltics/ui/socket';
+
+export const ConnectionStatus = () => {
+    // You can read the status ('connected', 'disconnected', 'error', 'connecting')
+    const { status, isConnected } = useSocketState();
+
+    return <div>Socket is {isConnected ? 'Online' : 'Offline'}</div>
+}
+```
+
+## 3. Emitting Events
+The store gives you direct access to the `emit` function, completely sidestepping standard React context constraints.
+
+```tsx
+import { useSocketState } from '@royaltics/ui/socket';
+
+export const ChatInput = () => {
+    // Destructure what you need!
+    const { emit, isConnected } = useSocketState();
+
+    const sendMessage = () => {
+        if (!isConnected) return;
+        emit('chat:message', { text: 'Hello, world!' });
+    };
+
+    return <button onClick={sendMessage}>Send</button>;
+};
+```
+
+### `setToken(token)`
+If you only need to update the authentication token without changing the `socketUrl` or other options, you can use `setToken`. This will automatically disconnect the current socket and reconnect with the new token.
+
+```tsx
+import { useSocketState } from '@royaltics/ui/socket';
+
+export const ProfileSettings = () => {
+    const { setToken } = useSocketState();
+
+    const handleSessionRefresh = (newToken: string) => {
+        setToken(newToken);
+    };
+
+    return <button onClick={() => handleSessionRefresh('NEW_TOKEN')}>Refresh Socket Token</button>;
+};
+```
+
+## 4. Tree-Shaking & Bundle Optimization
+To ensure that `socket.io-client` is only bundled when you actually use WebSockets, the socket logic is isolated in `@royaltics/ui/socket`. 
+
+> [!IMPORTANT]
+> Do **NOT** import socket hooks from `@royaltics/ui/hooks`. Always use the dedicated entry point:
+> `import { useSocketState } from '@royaltics/ui/socket';`
+
+## 5. Listening to Events
+We provide two tailored hooks for listening to specific Socket.io events and managing standard React lifecycles.
+
+### `useSocketEvent` 
+Used for managing a single distinct event listener. 
+
+```tsx
+import { useSocketEvent } from '@royaltics/ui/socket';
+
+export const NotificationToast = () => {
+    // Automatically binds/unbinds on mount/unmount
+    useSocketEvent('notification:new', (data) => {
+        console.log('Got new notification', data);
+    });
+
+    return null;
+}
+```
+
+### `useSocketEvents`
+Used when a component needs to mount a dense array of closely related events. You can easily toggle individual events using the `enabled` flag.
+
+```tsx
+import { useSocketEvents } from '@royaltics/ui/socket';
+
+export const ChatRoom = () => {
+    useSocketEvents([
+        {
+            event: 'chat:message',
+            onData: (message) => console.log('New Message:', message)
+        },
+        {
+            event: 'chat:typing',
+            enabled: false, // You can toggle this dynamically!
+            onData: (user) => console.log(`${user} is typing...`)
+        }
+    ]);
+
+    return <div>Chat UI</div>
+}
+```

package/dist/core/http/http-actions.d.ts

@@ -0,0 +1,9 @@
+import { HttpStateOptionsProps, QueryKey } from "./http.types.js";
+export declare const executeGet: <T = any>(core: any, api: string | string[], opts: HttpStateOptionsProps<T>) => Promise<T | undefined>;
+export declare const executeGetInfinite: <T = any[]>(core: any, api: string | string[], opts: HttpStateOptionsProps<T>) => Promise<void>;
+export declare const fetchNextPageAction: (core: any, queryKey: QueryKey) => Promise<void>;
+export declare const executeMutation: <T = any>(core: any, api: string | string[], opts: HttpStateOptionsProps<T>, method: "POST" | "PATCH" | "DELETE") => Promise<T | undefined>;
+export declare const refetchAction: (core: any, queryKey: QueryKey, api: string | string[], opts: HttpStateOptionsProps<any>) => Promise<void>;
+export declare const fileAction: <T = any>(core: any, api: string | string[], opts: HttpStateOptionsProps<T>) => Promise<T | undefined>;
+export declare const fileChunksAction: <T = any>(core: any, api: string | string[], opts: HttpStateOptionsProps<T>) => Promise<void>;
+//# sourceMappingURL=http-actions.d.ts.map

package/dist/core/http/http-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-actions.d.ts","sourceRoot":"","sources":["../../../src/core/http/http-actions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAoB,MAAM,iBAAiB,CAAC;AAQpF,eAAO,MAAM,UAAU,GAAU,CAAC,GAAG,GAAG,EACvC,MAAM,GAAG,EACT,KAAK,MAAM,GAAG,MAAM,EAAE,EACtB,MAAM,qBAAqB,CAAC,CAAC,CAAC,2BAqD9B,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAU,CAAC,GAAG,GAAG,EAAE,EACjD,MAAM,GAAG,EACT,KAAK,MAAM,GAAG,MAAM,EAAE,EACtB,MAAM,qBAAqB,CAAC,CAAC,CAAC,kBA2C9B,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAU,MAAM,GAAG,EAAE,UAAU,QAAQ,kBA6BtE,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,CAAC,GAAG,GAAG,EAC5C,MAAM,GAAG,EACT,KAAK,MAAM,GAAG,MAAM,EAAE,EACtB,MAAM,qBAAqB,CAAC,CAAC,CAAC,EAC9B,QAAQ,MAAM,GAAG,OAAO,GAAG,QAAQ,2BA0CnC,CAAC;AAEF,eAAO,MAAM,aAAa,GAAU,MAAM,GAAG,EAAE,UAAU,QAAQ,EAAE,KAAK,MAAM,GAAG,MAAM,EAAE,EAAE,MAAM,qBAAqB,CAAC,GAAG,CAAC,kBAoB1H,CAAC;AAEF,eAAO,MAAM,UAAU,GAAU,CAAC,GAAG,GAAG,EAAE,MAAM,GAAG,EAAE,KAAK,MAAM,GAAG,MAAM,EAAE,EAAE,MAAM,qBAAqB,CAAC,CAAC,CAAC,2BAgB1G,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAU,CAAC,GAAG,GAAG,EAAE,MAAM,GAAG,EAAE,KAAK,MAAM,GAAG,MAAM,EAAE,EAAE,MAAM,qBAAqB,CAAC,CAAC,CAAC,kBAUhH,CAAC"}