@trii/components 2.0.103 → 3.0.0

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { IContact, IBusiness, IContactAddress } from '@trii/types/dist/Contacts'
 import { Spaces } from '@trii/types';
 import { SxProps, Theme } from '@mui/material';
 import { IContact as IContact$1, IBusiness as IBusiness$1 } from '@trii/types/dist/Contacts/contacts';
-import React from 'react';
+import React, { ReactNode, ErrorInfo, Component } from 'react';
 import { IConversation } from '@trii/types/dist/Conversations';
 import { ChannelType } from '@trii/types/dist/Common/Channels';
 import * as i18next from 'i18next';
@@ -244,6 +244,333 @@ interface TaskData {
     relatedContactId?: string;
 }
 
+/**
+ * Modelo canónico de estado asíncrono (loading / error / caché remota).
+ *
+ * Unifica cómo los paneles representan el ciclo de vida de un dato remoto:
+ *
+ * - `idle`/`loading` sin datos  → carga inicial (bloqueante: skeleton/spinner).
+ * - `loading` con datos         → revalidación NO bloqueante (`isRevalidating`).
+ * - `rejected` con datos        → error manteniendo datos previos + retry.
+ * - `rejected` sin datos        → error bloqueante con retry.
+ * - `succeeded` sin datos       → estado realmente vacío (`isEmpty`).
+ *
+ * Los literales de `AsyncStatus` coinciden con el `RequestStatus` que usan los
+ * slices de los frontends Trii, para que sean compatibles sin conversión.
+ *
+ * Módulo puro: sin React, sin MUI, sin Redux, sin dominio. Se publica también
+ * por el subpath `@trii/components/async-state` para que un slice pueda
+ * consumirlo sin arrastrar la UI del paquete.
+ *
+ * Guía de uso: docs/ASYNC_STATE.md
+ */
+type AsyncStatus = 'idle' | 'loading' | 'succeeded' | 'rejected';
+/**
+ * Estado "crudo" persistible: es lo que guarda un slice de Redux o el estado
+ * interno de `useAsyncData`. Los flags derivados se calculan con
+ * `deriveAsyncState` (nunca se almacenan, para evitar inconsistencias).
+ */
+interface AsyncData<T> {
+    status: AsyncStatus;
+    /** Últimos datos válidos. Se preservan durante refetches y errores. */
+    data: T | undefined;
+    /** Mensaje del último error (null si la última operación fue exitosa). */
+    error: string | null;
+    /** Timestamp (Date.now()) del último fetch exitoso. Base para staleness. */
+    updatedAt: number | null;
+}
+/** Estado derivado listo para consumir desde la UI. */
+interface AsyncState<T> extends AsyncData<T> {
+    /** true si hay datos utilizables para mostrar (no undefined ni "vacíos"). */
+    hasData: boolean;
+    /** Carga inicial: está cargando y NO hay datos que mostrar → bloqueante. */
+    isInitialLoading: boolean;
+    /** Revalidación: está cargando y SÍ hay datos → no bloquear la UI. */
+    isRevalidating: boolean;
+    /** Vacío real: la última carga fue exitosa y no hay datos que mostrar. */
+    isEmpty: boolean;
+}
+/** Decide si un dato cuenta como "vacío" (p.ej. lista sin elementos). */
+type IsEmptyFn<T> = (data: T) => boolean;
+/**
+ * Vacío por defecto: `null`/`undefined` y arrays sin elementos.
+ * Cada feature puede aportar su propia regla (p.ej. "objeto sin campos").
+ */
+declare const defaultIsEmpty: <T>(data: T) => boolean;
+/** Estado inicial: nunca se hizo un fetch. */
+declare const asyncIdle: <T>() => AsyncData<T>;
+/**
+ * Transición a "request en curso".
+ * Por defecto preserva los datos previos (refetch no bloqueante).
+ * Pasar `clearData: true` solo cuando los datos viejos dejarían de ser
+ * válidos para la nueva request (p.ej. cambio de contacto seleccionado).
+ */
+declare const asyncRequestStarted: <T>(prev: AsyncData<T>, options?: {
+    clearData?: boolean;
+}) => AsyncData<T>;
+/** Transición a éxito: guarda datos, limpia error y sella `updatedAt`. */
+declare const asyncRequestSucceeded: <T>(data: T) => AsyncData<T>;
+/**
+ * Transición a error: guarda el mensaje y PRESERVA los datos previos
+ * para que la UI pueda seguir mostrándolos (error con datos).
+ */
+declare const asyncRequestFailed: <T>(error: string, prev: AsyncData<T>) => AsyncData<T>;
+/**
+ * Deriva los flags de UI a partir del estado crudo. Es la ÚNICA fuente de
+ * verdad para interpretar un estado asíncrono: la usan `useAsyncData`,
+ * los selectores de Redux y `<AsyncContent>`.
+ *
+ * Uso con un slice existente (sin reescribirlo):
+ *
+ * ```ts
+ * const selectChannelsAsyncState = createSelector(
+ *   selectChannelsState,
+ *   (state) =>
+ *     deriveAsyncState({
+ *       status: state.status.fetch,
+ *       data: state.channels,
+ *       error: state.error,
+ *     })
+ * );
+ * ```
+ */
+declare const deriveAsyncState: <T>(input: {
+    status: AsyncStatus;
+    data: T | undefined;
+    error?: string | null;
+    updatedAt?: number | null;
+    isEmpty?: IsEmptyFn<T>;
+}) => AsyncState<T>;
+/** true si el dato tiene más de `staleTime` ms (o nunca se cargó). */
+declare const isStale: (updatedAt: number | null, staleTime: number, now?: number) => boolean;
+
+/**
+ * Extrae un mensaje legible de cualquier error (axios, Error, string...).
+ *
+ * Orden de preferencia:
+ * 1. `error.response.data.message` / `error.response.data.error` (API Trii).
+ * 2. `error.message` (Error estándar, p.ej. "Network Error" de axios).
+ * 3. El string recibido tal cual.
+ * 4. `fallback`.
+ *
+ * No traduce: la traducción de mensajes genéricos ocurre en la UI
+ * (`<ErrorState>`); esto preserva el detalle técnico o del backend.
+ *
+ * Tipa axios por duck-typing a propósito: el módulo no importa axios, así que
+ * sirve igual con fetch o con cualquier cliente HTTP.
+ */
+declare const getErrorMessage: (error: unknown, fallback?: string) => string;
+
+/** Resultado de `useAsyncData`: estado derivado + acciones del ciclo de vida. */
+interface UseAsyncDataResult<T> extends AsyncState<T> {
+    /**
+     * Re-ejecuta el fetcher. Si ya hay datos, NO bloquea la UI
+     * (`isRevalidating` pasa a true y los datos siguen visibles).
+     */
+    refetch: () => Promise<void>;
+    /**
+     * Alias semántico de `refetch` para los estados de error.
+     * Es el callback que debe recibir `<AsyncContent onRetry={...}>`.
+     */
+    retry: () => Promise<void>;
+    /** Vuelve al estado `idle` y cancela cualquier request en curso. */
+    reset: () => void;
+}
+
+/**
+ * Ciclo de vida completo de un dato remoto LOCAL a un panel (sin Redux).
+ *
+ * Comportamiento:
+ * - Fetch al montar (configurable con `fetchOnMount`) y cuando cambian `deps`.
+ * - Carga inicial sin datos → `isInitialLoading` (bloqueante).
+ * - Refetch con datos → `isRevalidating`: los datos siguen visibles.
+ * - Error con datos previos → `status: 'rejected'` + datos preservados.
+ * - Error sin datos → `error` para mostrar un estado de error con `retry`.
+ * - `refetch()`/`retry()` re-ejecutan el fetcher; nunca bloquean si hay datos.
+ * - Cancelación automática (AbortSignal) y guarda de carrera: si se dispara
+ *   una request nueva, las respuestas viejas se descartan.
+ * - `autoRetry` opcional con backoff lineal antes de mostrar el error.
+ *
+ * Usar Redux en su lugar cuando el dato se comparte entre varios paneles o
+ * se actualiza por socket (ver docs/ASYNC_STATE.md §¿Redux o hook?).
+ *
+ * @example
+ * const state = useAsyncData(
+ *   (signal) => reportsService.getReports(url, { signal }),
+ *   { deps: [url] }
+ * );
+ * return (
+ *   <AsyncContent state={state} onRetry={state.retry}>
+ *     {(reports) => <ReportList reports={reports} />}
+ *   </AsyncContent>
+ * );
+ */
+declare function useAsyncData<T>(fetcher: (signal: AbortSignal) => Promise<T>, options?: {
+    /** Regla de "vacío" del dato (default: null/undefined o array vacío). */
+    isEmpty?: IsEmptyFn<T>;
+    /** Disparar el fetch al montar y al cambiar `deps` (default: true). */
+    fetchOnMount?: boolean;
+    /**
+     * Preservar datos previos durante refetches (default: true).
+     * Poner en false solo si los datos viejos serían inválidos/engañosos.
+     */
+    keepPreviousData?: boolean;
+    /**
+     * Reintentos automáticos antes de marcar error (default: sin reintentos;
+     * el usuario decide con el botón de retry).
+     */
+    autoRetry?: {
+        attempts: number;
+        delayMs?: number;
+    };
+    /** Dependencias que re-disparan el fetch (p.ej. un id o filtro). */
+    deps?: ReadonlyArray<unknown>;
+}): UseAsyncDataResult<T>;
+
+interface AsyncContentProps<T> {
+    /** Estado derivado (de `useAsyncData` o de un selector con `deriveAsyncState`). */
+    state: AsyncState<T>;
+    /** Contenido real: se llama solo cuando hay datos utilizables. */
+    children: (data: T) => ReactNode;
+    /**
+     * Callback de reintento (p.ej. `state.retry` del hook o re-dispatch del
+     * thunk). Habilita el botón "Reintentar" en los estados de error.
+     */
+    onRetry?: () => void;
+    /** Fallback de carga inicial (default: spinner centrado). Usar skeletons cuando el layout del contenido es conocido. */
+    loadingFallback?: ReactNode;
+    /** Fallback de vacío (default: `<EmptyState>` con textos i18n). */
+    emptyFallback?: ReactNode;
+    /** Fallback de error sin datos (default: `<ErrorState>` con retry). */
+    errorFallback?: ReactNode;
+    /** Overrides de textos del estado vacío. */
+    emptyTitle?: string;
+    emptyDescription?: string;
+    /** Override del título del estado de error. */
+    errorTitle?: string;
+    /** Mostrar la barra fina de revalidación sobre el contenido (default: true). */
+    showRevalidatingIndicator?: boolean;
+    /** Idioma de los textos por defecto ('es' | 'en'). Opcional: ver useComponentsTranslation. */
+    language?: string;
+}
+/**
+ * Renderiza un dato remoto según su `AsyncState`, con feedback consistente:
+ *
+ * | Situación                        | Render                                        |
+ * |----------------------------------|------------------------------------------------|
+ * | `idle`/`loading` sin datos       | `loadingFallback` (carga inicial bloqueante)   |
+ * | `rejected` sin datos             | `ErrorState` + retry                           |
+ * | `succeeded` sin datos (`isEmpty`)| `EmptyState`                                   |
+ * | datos + `loading`                | contenido + barra de revalidación (no bloquea) |
+ * | datos + `rejected`               | contenido + banner de error con retry          |
+ * | datos                            | contenido                                      |
+ *
+ * La rama "con datos" usa siempre el mismo wrapper para que un refetch o un
+ * error NUNCA desmonte el contenido (conserva scroll, foco y estado interno).
+ *
+ * Para errores de RENDER (excepciones) combinar con `<PanelErrorBoundary>`.
+ * Guía completa: docs/ASYNC_STATE.md
+ */
+declare const AsyncContent: <T>({ state, children, onRetry, loadingFallback, emptyFallback, errorFallback, emptyTitle, emptyDescription, errorTitle, showRevalidatingIndicator, language, }: AsyncContentProps<T>) => react_jsx_runtime.JSX.Element;
+
+interface EmptyStateProps {
+    /** Título principal (default: i18n `asyncState.emptyTitle`). */
+    title?: string;
+    /** Descripción secundaria (default: i18n `asyncState.emptyDescription`). */
+    description?: string;
+    /** Icono personalizado (default: `InboxIcon`). */
+    icon?: ReactNode;
+    /** Acción opcional bajo el texto (p.ej. botón "Crear el primero"). */
+    action?: ReactNode;
+    /** Versión compacta (menos padding e icono más chico). */
+    compact?: boolean;
+    /** Idioma de los textos por defecto ('es' | 'en'). Opcional: ver useComponentsTranslation. */
+    language?: string;
+}
+/**
+ * Estado "vacío real": la carga fue exitosa pero no hay datos que mostrar.
+ * No confundir con "aún no se cargó" (eso es loading) ni con un error.
+ * Presentacional y genérico (ver docs/ASYNC_STATE.md).
+ */
+declare const EmptyState: ({ title, description, icon, action, compact, language, }: EmptyStateProps) => react_jsx_runtime.JSX.Element;
+
+interface ErrorStateProps {
+    /** Título principal (default: i18n `asyncState.errorTitle`). */
+    title?: string;
+    /** Descripción secundaria (default: i18n `asyncState.errorDescription`). */
+    description?: string;
+    /** Detalle técnico o mensaje del backend (se muestra atenuado). */
+    error?: string | null;
+    /** Si se provee, muestra el botón de reintento. */
+    onRetry?: () => void;
+    /** Texto del botón de reintento (default: i18n `asyncState.retry`). */
+    retryLabel?: string;
+    /** Versión compacta (menos padding e icono más chico) para paneles angostos. */
+    compact?: boolean;
+    /** Idioma de los textos por defecto ('es' | 'en'). Opcional: ver useComponentsTranslation. */
+    language?: string;
+}
+/**
+ * Estado de error a nivel panel, con retry opcional.
+ * Presentacional y genérico: no conoce Redux ni fetching
+ * (ver docs/ASYNC_STATE.md).
+ */
+declare const ErrorState: ({ title, description, error, onRetry, retryLabel, compact, language, }: ErrorStateProps) => react_jsx_runtime.JSX.Element;
+
+interface PanelErrorBoundaryProps {
+    children: ReactNode;
+    /**
+     * Fallback custom ante un crash de render. Puede ser un nodo o una función
+     * que recibe el error y `resetErrorBoundary` (para reintentar).
+     */
+    fallback?: ReactNode | ((args: {
+        error: Error | null;
+        resetErrorBoundary: () => void;
+    }) => ReactNode);
+    /** Telemetría/logging del error (p.ej. enviar a un servicio externo). */
+    onError?: (error: Error, info: ErrorInfo) => void;
+    /**
+     * Claves que al cambiar resetean el boundary automáticamente
+     * (p.ej. el id de la ruta actual, para reintentar al navegar).
+     */
+    resetKeys?: ReadonlyArray<unknown>;
+    /** Overrides de textos del fallback por defecto. */
+    title?: string;
+    description?: string;
+    /** Idioma de los textos por defecto ('es' | 'en'). Opcional: ver useComponentsTranslation. */
+    language?: string;
+}
+interface PanelErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Aísla fallos de RENDER por panel: si el contenido explota, el resto de la
+ * UI (hermanos, otros paneles, la navegación) sigue funcionando y el panel
+ * muestra un fallback con reintento.
+ *
+ * ```tsx
+ * <PanelErrorBoundary resetKeys={[conversationId]}>
+ *   <ContactInfoPanel />
+ * </PanelErrorBoundary>
+ * <PanelErrorBoundary>
+ *   <MessagesPanel />
+ * </PanelErrorBoundary>
+ * ```
+ *
+ * NOTA: los boundaries NO capturan errores de fetching (para eso está
+ * `<AsyncContent>`), ni de event handlers, ni de código asíncrono.
+ * Guía completa: docs/ASYNC_STATE.md
+ */
+declare class PanelErrorBoundary extends Component<PanelErrorBoundaryProps, PanelErrorBoundaryState> {
+    state: PanelErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): PanelErrorBoundaryState;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    componentDidUpdate(prevProps: PanelErrorBoundaryProps): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+
 /**
  * Integración con un inbox de chat. Es opcional: sin ella el sidebar funciona
  * en "modo ficha" (sin GroupData, sin abrir conversaciones, sin iniciar una
@@ -293,6 +620,12 @@ interface ChatDetailsSidebarBaseProps {
      * propia instancia de i18n, así que no sigue solo los cambios del host.
      */
     language?: string;
+    /**
+     * Gate de visibilidad (CSS display) del panel. Para hosts que renderizan
+     * vistas hermanas alternadas por CSS: el panel queda montado (conserva su
+     * estado y sus datos) pero oculto mientras `active` es false. Default: true.
+     */
+    active?: boolean;
 }
 /**
  * Qué mostrar. Hay dos formas y son excluyentes; TypeScript falla si no se pasa
@@ -325,9 +658,17 @@ type ChatDetailsSidebarTarget = {
 };
 type ChatDetailsSidebarProps = ChatDetailsSidebarBaseProps & ChatDetailsSidebarTarget;
 /**
- * Shell del sidebar (en camino al paquete npm): recibe las props del
- * contrato (docs/CONTRATO_CHATDETAILSSIDEBAR.md) y monta los providers
- * internos. La orquestación de UI vive en SidebarContent.
+ * Panel de contacto reutilizable: la ficha completa de un contacto/empresa
+ * (datos, conversaciones, archivos, media, historial, eventos, tareas, shop,
+ * relaciones, grupos de WhatsApp) con su riel vertical de tabs, skeleton y
+ * overlay de carga. Recibe las props del contrato y monta los providers
+ * internos; la orquestación de tabs vive en SidebarContent.
+ *
+ * El shell de vistas (header Contacto/Interacción/Asistente) es del host: este
+ * componente renderiza SOLO la vista de contacto y expone `active` para que el
+ * host lo alterne por CSS con sus vistas hermanas sin desmontarlo. Debe
+ * colocarse dentro de un contenedor flex con `position: relative` (el overlay
+ * y el skeleton se posicionan contra ese contenedor). Ver README.md.
  */
 declare const ChatDetailsSidebar: (props: ChatDetailsSidebarProps) => react_jsx_runtime.JSX.Element;
 
@@ -459,4 +800,4 @@ declare const selectThemeToggleStatus: (state: ThemeRootState) => "idle" | "togg
 declare const selectedTheme: (state: ThemeRootState) => Theme;
 declare const selectedDarkTheme: (state: ThemeRootState) => boolean;
 
-export { type Calendar, type Contact, ContactInfoPopup, ChatDetailsSidebar as ContactSidebar, type ChatDetailsSidebarProps as ContactSidebarProps, EditContactModal, type EditContactModalProps, type EditContactMode, type EventData, EventsDialog, type EventsDialogProps, type ItemType, type ModalMode, MuiComponentsConfig, type Notification, type SidebarChatIntegration, type StartConversationTarget, type TaskData, type ThemeName, type ThemeRootState, type ThemeState, darkBlack, darkBlue, i18nInstance as i18n, isValidThemeName, lightAmber, lightBlue, lightBlueIndigo, lightBrown, lightGray, lightGreen, lightLime, lightOrange, lightPink, lightPurple, lightRed, lightTeal, lightYellow, selectThemeToggleStatus, selectedDarkTheme, selectedTheme, toggleModeTheme, toggleTheme, updateTheme };
+export { AsyncContent, type AsyncContentProps, type AsyncData, type AsyncState, type AsyncStatus, type Calendar, type Contact, ContactInfoPopup, ChatDetailsSidebar as ContactSidebar, type ChatDetailsSidebarProps as ContactSidebarProps, EditContactModal, type EditContactModalProps, type EditContactMode, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, type EventData, EventsDialog, type EventsDialogProps, type IsEmptyFn, type ItemType, type ModalMode, MuiComponentsConfig, type Notification, PanelErrorBoundary, type PanelErrorBoundaryProps, type SidebarChatIntegration, type StartConversationTarget, type TaskData, type ThemeName, type ThemeRootState, type ThemeState, type UseAsyncDataResult, asyncIdle, asyncRequestFailed, asyncRequestStarted, asyncRequestSucceeded, darkBlack, darkBlue, defaultIsEmpty, deriveAsyncState, getErrorMessage, i18nInstance as i18n, isStale, isValidThemeName, lightAmber, lightBlue, lightBlueIndigo, lightBrown, lightGray, lightGreen, lightLime, lightOrange, lightPink, lightPurple, lightRed, lightTeal, lightYellow, selectThemeToggleStatus, selectedDarkTheme, selectedTheme, toggleModeTheme, toggleTheme, updateTheme, useAsyncData };

package/dist/types/asyncState/asyncState.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Modelo canónico de estado asíncrono (loading / error / caché remota).
+ *
+ * Unifica cómo los paneles representan el ciclo de vida de un dato remoto:
+ *
+ * - `idle`/`loading` sin datos  → carga inicial (bloqueante: skeleton/spinner).
+ * - `loading` con datos         → revalidación NO bloqueante (`isRevalidating`).
+ * - `rejected` con datos        → error manteniendo datos previos + retry.
+ * - `rejected` sin datos        → error bloqueante con retry.
+ * - `succeeded` sin datos       → estado realmente vacío (`isEmpty`).
+ *
+ * Los literales de `AsyncStatus` coinciden con el `RequestStatus` que usan los
+ * slices de los frontends Trii, para que sean compatibles sin conversión.
+ *
+ * Módulo puro: sin React, sin MUI, sin Redux, sin dominio. Se publica también
+ * por el subpath `@trii/components/async-state` para que un slice pueda
+ * consumirlo sin arrastrar la UI del paquete.
+ *
+ * Guía de uso: docs/ASYNC_STATE.md
+ */
+export type AsyncStatus = 'idle' | 'loading' | 'succeeded' | 'rejected';
+/**
+ * Estado "crudo" persistible: es lo que guarda un slice de Redux o el estado
+ * interno de `useAsyncData`. Los flags derivados se calculan con
+ * `deriveAsyncState` (nunca se almacenan, para evitar inconsistencias).
+ */
+export interface AsyncData<T> {
+    status: AsyncStatus;
+    /** Últimos datos válidos. Se preservan durante refetches y errores. */
+    data: T | undefined;
+    /** Mensaje del último error (null si la última operación fue exitosa). */
+    error: string | null;
+    /** Timestamp (Date.now()) del último fetch exitoso. Base para staleness. */
+    updatedAt: number | null;
+}
+/** Estado derivado listo para consumir desde la UI. */
+export interface AsyncState<T> extends AsyncData<T> {
+    /** true si hay datos utilizables para mostrar (no undefined ni "vacíos"). */
+    hasData: boolean;
+    /** Carga inicial: está cargando y NO hay datos que mostrar → bloqueante. */
+    isInitialLoading: boolean;
+    /** Revalidación: está cargando y SÍ hay datos → no bloquear la UI. */
+    isRevalidating: boolean;
+    /** Vacío real: la última carga fue exitosa y no hay datos que mostrar. */
+    isEmpty: boolean;
+}
+/** Decide si un dato cuenta como "vacío" (p.ej. lista sin elementos). */
+export type IsEmptyFn<T> = (data: T) => boolean;
+/**
+ * Vacío por defecto: `null`/`undefined` y arrays sin elementos.
+ * Cada feature puede aportar su propia regla (p.ej. "objeto sin campos").
+ */
+export declare const defaultIsEmpty: <T>(data: T) => boolean;
+/** Estado inicial: nunca se hizo un fetch. */
+export declare const asyncIdle: <T>() => AsyncData<T>;
+/**
+ * Transición a "request en curso".
+ * Por defecto preserva los datos previos (refetch no bloqueante).
+ * Pasar `clearData: true` solo cuando los datos viejos dejarían de ser
+ * válidos para la nueva request (p.ej. cambio de contacto seleccionado).
+ */
+export declare const asyncRequestStarted: <T>(prev: AsyncData<T>, options?: {
+    clearData?: boolean;
+}) => AsyncData<T>;
+/** Transición a éxito: guarda datos, limpia error y sella `updatedAt`. */
+export declare const asyncRequestSucceeded: <T>(data: T) => AsyncData<T>;
+/**
+ * Transición a error: guarda el mensaje y PRESERVA los datos previos
+ * para que la UI pueda seguir mostrándolos (error con datos).
+ */
+export declare const asyncRequestFailed: <T>(error: string, prev: AsyncData<T>) => AsyncData<T>;
+/**
+ * Deriva los flags de UI a partir del estado crudo. Es la ÚNICA fuente de
+ * verdad para interpretar un estado asíncrono: la usan `useAsyncData`,
+ * los selectores de Redux y `<AsyncContent>`.
+ *
+ * Uso con un slice existente (sin reescribirlo):
+ *
+ * ```ts
+ * const selectChannelsAsyncState = createSelector(
+ *   selectChannelsState,
+ *   (state) =>
+ *     deriveAsyncState({
+ *       status: state.status.fetch,
+ *       data: state.channels,
+ *       error: state.error,
+ *     })
+ * );
+ * ```
+ */
+export declare const deriveAsyncState: <T>(input: {
+    status: AsyncStatus;
+    data: T | undefined;
+    error?: string | null;
+    updatedAt?: number | null;
+    isEmpty?: IsEmptyFn<T>;
+}) => AsyncState<T>;
+/** true si el dato tiene más de `staleTime` ms (o nunca se cargó). */
+export declare const isStale: (updatedAt: number | null, staleTime: number, now?: number) => boolean;

package/dist/types/asyncState/getErrorMessage.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Extrae un mensaje legible de cualquier error (axios, Error, string...).
+ *
+ * Orden de preferencia:
+ * 1. `error.response.data.message` / `error.response.data.error` (API Trii).
+ * 2. `error.message` (Error estándar, p.ej. "Network Error" de axios).
+ * 3. El string recibido tal cual.
+ * 4. `fallback`.
+ *
+ * No traduce: la traducción de mensajes genéricos ocurre en la UI
+ * (`<ErrorState>`); esto preserva el detalle técnico o del backend.
+ *
+ * Tipa axios por duck-typing a propósito: el módulo no importa axios, así que
+ * sirve igual con fetch o con cualquier cliente HTTP.
+ */
+export declare const getErrorMessage: (error: unknown, fallback?: string) => string;

package/dist/types/asyncState/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Punto de entrada del modelo de estado asíncrono.
+ *
+ * Este módulo NO importa MUI ni react-i18next: se publica además por el
+ * subpath `@trii/components/async-state` para que un slice de Redux o un
+ * servicio pueda usar `deriveAsyncState`/`getErrorMessage` sin arrastrar la
+ * UI del paquete. Los componentes que lo pintan (`AsyncContent`,
+ * `EmptyState`, `ErrorState`, `PanelErrorBoundary`) viven en la entrada
+ * principal.
+ */
+export { defaultIsEmpty, asyncIdle, asyncRequestStarted, asyncRequestSucceeded, asyncRequestFailed, deriveAsyncState, isStale, } from './asyncState';
+export type { AsyncStatus, AsyncData, AsyncState, IsEmptyFn, } from './asyncState';
+export { getErrorMessage } from './getErrorMessage';
+export { useAsyncData } from './useAsyncData';
+export type { UseAsyncDataResult } from './types';

package/dist/types/asyncState/types.d.ts

@@ -0,0 +1,17 @@
+import { AsyncState } from './asyncState';
+export type { AsyncData, IsEmptyFn } from './asyncState';
+/** Resultado de `useAsyncData`: estado derivado + acciones del ciclo de vida. */
+export interface UseAsyncDataResult<T> extends AsyncState<T> {
+    /**
+     * Re-ejecuta el fetcher. Si ya hay datos, NO bloquea la UI
+     * (`isRevalidating` pasa a true y los datos siguen visibles).
+     */
+    refetch: () => Promise<void>;
+    /**
+     * Alias semántico de `refetch` para los estados de error.
+     * Es el callback que debe recibir `<AsyncContent onRetry={...}>`.
+     */
+    retry: () => Promise<void>;
+    /** Vuelve al estado `idle` y cancela cualquier request en curso. */
+    reset: () => void;
+}

package/dist/types/asyncState/useAsyncData.d.ts

@@ -0,0 +1,51 @@
+import { UseAsyncDataResult } from './types';
+import { IsEmptyFn } from './asyncState';
+/**
+ * Ciclo de vida completo de un dato remoto LOCAL a un panel (sin Redux).
+ *
+ * Comportamiento:
+ * - Fetch al montar (configurable con `fetchOnMount`) y cuando cambian `deps`.
+ * - Carga inicial sin datos → `isInitialLoading` (bloqueante).
+ * - Refetch con datos → `isRevalidating`: los datos siguen visibles.
+ * - Error con datos previos → `status: 'rejected'` + datos preservados.
+ * - Error sin datos → `error` para mostrar un estado de error con `retry`.
+ * - `refetch()`/`retry()` re-ejecutan el fetcher; nunca bloquean si hay datos.
+ * - Cancelación automática (AbortSignal) y guarda de carrera: si se dispara
+ *   una request nueva, las respuestas viejas se descartan.
+ * - `autoRetry` opcional con backoff lineal antes de mostrar el error.
+ *
+ * Usar Redux en su lugar cuando el dato se comparte entre varios paneles o
+ * se actualiza por socket (ver docs/ASYNC_STATE.md §¿Redux o hook?).
+ *
+ * @example
+ * const state = useAsyncData(
+ *   (signal) => reportsService.getReports(url, { signal }),
+ *   { deps: [url] }
+ * );
+ * return (
+ *   <AsyncContent state={state} onRetry={state.retry}>
+ *     {(reports) => <ReportList reports={reports} />}
+ *   </AsyncContent>
+ * );
+ */
+export declare function useAsyncData<T>(fetcher: (signal: AbortSignal) => Promise<T>, options?: {
+    /** Regla de "vacío" del dato (default: null/undefined o array vacío). */
+    isEmpty?: IsEmptyFn<T>;
+    /** Disparar el fetch al montar y al cambiar `deps` (default: true). */
+    fetchOnMount?: boolean;
+    /**
+     * Preservar datos previos durante refetches (default: true).
+     * Poner en false solo si los datos viejos serían inválidos/engañosos.
+     */
+    keepPreviousData?: boolean;
+    /**
+     * Reintentos automáticos antes de marcar error (default: sin reintentos;
+     * el usuario decide con el botón de retry).
+     */
+    autoRetry?: {
+        attempts: number;
+        delayMs?: number;
+    };
+    /** Dependencias que re-disparan el fetch (p.ej. un id o filtro). */
+    deps?: ReadonlyArray<unknown>;
+}): UseAsyncDataResult<T>;

package/dist/types/components/AsyncContent/AsyncContent.d.ts

@@ -0,0 +1,48 @@
+import { ReactNode } from 'react';
+import type { AsyncState } from '../../asyncState';
+export interface AsyncContentProps<T> {
+    /** Estado derivado (de `useAsyncData` o de un selector con `deriveAsyncState`). */
+    state: AsyncState<T>;
+    /** Contenido real: se llama solo cuando hay datos utilizables. */
+    children: (data: T) => ReactNode;
+    /**
+     * Callback de reintento (p.ej. `state.retry` del hook o re-dispatch del
+     * thunk). Habilita el botón "Reintentar" en los estados de error.
+     */
+    onRetry?: () => void;
+    /** Fallback de carga inicial (default: spinner centrado). Usar skeletons cuando el layout del contenido es conocido. */
+    loadingFallback?: ReactNode;
+    /** Fallback de vacío (default: `<EmptyState>` con textos i18n). */
+    emptyFallback?: ReactNode;
+    /** Fallback de error sin datos (default: `<ErrorState>` con retry). */
+    errorFallback?: ReactNode;
+    /** Overrides de textos del estado vacío. */
+    emptyTitle?: string;
+    emptyDescription?: string;
+    /** Override del título del estado de error. */
+    errorTitle?: string;
+    /** Mostrar la barra fina de revalidación sobre el contenido (default: true). */
+    showRevalidatingIndicator?: boolean;
+    /** Idioma de los textos por defecto ('es' | 'en'). Opcional: ver useComponentsTranslation. */
+    language?: string;
+}
+/**
+ * Renderiza un dato remoto según su `AsyncState`, con feedback consistente:
+ *
+ * | Situación                        | Render                                        |
+ * |----------------------------------|------------------------------------------------|
+ * | `idle`/`loading` sin datos       | `loadingFallback` (carga inicial bloqueante)   |
+ * | `rejected` sin datos             | `ErrorState` + retry                           |
+ * | `succeeded` sin datos (`isEmpty`)| `EmptyState`                                   |
+ * | datos + `loading`                | contenido + barra de revalidación (no bloquea) |
+ * | datos + `rejected`               | contenido + banner de error con retry          |
+ * | datos                            | contenido                                      |
+ *
+ * La rama "con datos" usa siempre el mismo wrapper para que un refetch o un
+ * error NUNCA desmonte el contenido (conserva scroll, foco y estado interno).
+ *
+ * Para errores de RENDER (excepciones) combinar con `<PanelErrorBoundary>`.
+ * Guía completa: docs/ASYNC_STATE.md
+ */
+declare const AsyncContent: <T>({ state, children, onRetry, loadingFallback, emptyFallback, errorFallback, emptyTitle, emptyDescription, errorTitle, showRevalidatingIndicator, language, }: AsyncContentProps<T>) => import("react/jsx-runtime").JSX.Element;
+export default AsyncContent;

package/dist/types/components/AsyncContent/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './AsyncContent';
+export type { AsyncContentProps } from './AsyncContent';