sass-cms-template-common 0.0.29 → 0.0.30

package/dist/index.d.ts

@@ -4620,6 +4620,13 @@ declare interface ISectionsServices {
     authentication: Authentication;
 }
 
+/**
+ * `true` si la excepción es una señal interna de control de flujo de Next
+ * (`redirect()`, `notFound()`, `forbidden()`), no un fallo real. Estas NUNCA
+ * deben atraparse: si se tragan, la navegación no ocurre.
+ */
+export declare function isFrameworkControlFlowError(error: unknown): boolean;
+
 declare interface ISitesServices {
     axiosApi: AxiosInstance;
     authentication: Authentication;
@@ -6885,6 +6892,16 @@ export declare interface RecipesPublishCheckResponse extends CmsResponse {
 /** Estilo del texto relativo (`Intl.RelativeTimeFormat`). */
 export declare type RelativeTimeStyle = 'long' | 'short' | 'narrow';
 
+export declare interface ResilientFormActionOptions<S> extends ResilientRunOptions {
+    /**
+     * Estado a devolver cuando la llamada no pudo completarse (se agotaron los
+     * reintentos, o la excepción no era de red). Recibe el error crudo y su
+     * clasificación (`null` si no es un fallo de red) para poder distinguir
+     * "servicio caído" de "error inesperado".
+     */
+    onError: (error: unknown, classified: ClassifiedNetworkError | null) => S;
+}
+
 export declare type ResilientRunner = <T>(fn: () => Promise<T>, options?: ResilientRunOptions) => Promise<T>;
 
 export declare interface ResilientRunOptions {
@@ -8028,6 +8045,37 @@ export declare type UserAvatarProps = {
  */
 export declare function useResilientAction(): ResilientRunner;
 
+/**
+ * Envuelve el server action de un formulario (`useActionState`) para hacerlo
+ * **resiliente a la red** y, sobre todo, para que **jamás propague la excepción**.
+ *
+ * Por qué existe: al invocar un server action desde el navegador, Next hace un
+ * `fetch` interno. Sin internet ese fetch lanza `TypeError: Failed to fetch`
+ * dentro del render de React; como `useActionState` no atrapa nada, el error
+ * sube al error boundary y **tumba la pantalla** ("recargá la página"). Es
+ * inaceptable en pantallas sin shell —el login—, donde no hay nada que degradar:
+ * se cae todo.
+ *
+ * Qué hace, apoyado en `useResilientAction`:
+ * - **Sin internet:** no pierde el envío. Muestra el toast de "sin conexión"
+ *   (vía `CmsNetworkProvider` + `CmsNetworkToaster`), espera la reconexión y
+ *   **retoma el llamado** solo (avisando "reintentando…").
+ * - **Backend caído / 5xx / timeout:** reintenta con backoff exponencial.
+ * - **Agotado o error inesperado:** devuelve el estado de `onError` — la pantalla
+ *   sigue viva y pinta el mensaje en su lugar.
+ *
+ * Requiere estar dentro de `<CmsNetworkProvider>` y `<CmsToastProvider>`.
+ *
+ * ```ts
+ * const resilientLogin = useResilientFormAction(loginAction, {
+ *   service: '/auth/loginValid',
+ *   onError: () => ({ error: 'service', field: 'general' }),
+ * });
+ * const [state, formAction, isPending] = useActionState(resilientLogin, {});
+ * ```
+ */
+export declare function useResilientFormAction<S>(action: (prevState: S, formData: FormData) => Promise<S>, options: ResilientFormActionOptions<S>): (prevState: S, formData: FormData) => Promise<S>;
+
 /** Grupo del sistema devuelto por POST /users/groups/get. */
 export declare interface UserGroup {
     id: string;