@acvl/frontend-components 0.0.72 → 0.0.73

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _mui_material from '@mui/material';
-import { ButtonProps, ButtonGroupProps, IconButtonProps, MenuItemProps, AlertProps, BoxProps, AutocompleteProps, SliderProps, SwitchProps, GridProps, DrawerProps, SxProps, Theme, StackProps, TypographyProps, MenuProps, PaletteColorOptions, TextFieldProps as TextFieldProps$1, InputBaseProps, DialogProps, DialogContentProps } from '@mui/material';
+import { ButtonProps, ButtonGroupProps, IconButtonProps, MenuItemProps, BoxProps, AutocompleteProps, SliderProps, SwitchProps, GridProps, DrawerProps, SxProps, Theme, StackProps, TypographyProps, MenuProps, PaletteColorOptions, TextFieldProps as TextFieldProps$1, InputBaseProps, DialogProps, DialogContentProps } from '@mui/material';
 import * as React from 'react';
 import React__default, { ReactNode, Dispatch, SetStateAction, JSX, RefObject, ReactElement, FC, BaseSyntheticEvent, JSXElementConstructor, ElementType } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -127,13 +127,68 @@ interface ExtraButtonsProps {
 }
 declare const ExtraButtons: (props: ExtraButtonsProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * Los colores de la paleta con los que se puede pintar un estado. Son los mismos que admite el
+ * chip de una tabla (`ChipCell`), y a propósito: así el mapa de colores de un catálogo —el que
+ * dice que el estado "2" es `info`— se declara una vez y sirve en la tabla y en la ficha.
+ */
+type StatusColor = "primary" | "secondary" | "error" | "warning" | "info" | "success";
 interface StatusBadgeProps {
-    severity?: AlertProps['severity'];
+    /**
+     * El color, no la gravedad, aunque se siga llamando así: las cuatro severidades de un
+     * `Alert` son también nombres de la paleta, y esto admite además `primary` y `secondary`.
+     *
+     * Rara vez se escribe a mano —lo normal es sacarlo de {@link resolveStatusColor}, que es
+     * quien sabe qué color le toca a cada estado del catálogo—.
+     */
+    severity?: StatusColor;
     title: string;
     slotProps?: {
         box?: Partial<BoxProps>;
     };
 }
+/**
+ * Los dos colores de un estado: la tinta —texto y contorno— y el relleno.
+ *
+ * Salen del tema y no de una gama fija (`green[800]`, `yellow[100]`…), que es lo que hace que
+ * un mismo estado se vea igual en la pastilla de una ficha que en el chip de una tabla
+ * (`ChipCell`), y que los dos sigan al esquema de color activo en vez de quedarse en los tonos
+ * del claro. `severity` es además el nombre del color en la paleta —`success`, `warning`…—, así
+ * que no hay tabla de equivalencias que mantener: sin severidad se pinta neutro.
+ *
+ * El relleno es el mismo tono al 20%. Va escrito contra el canal (`mainChannel`) porque es la
+ * forma de que una transparencia siga a las variables CSS; `ChipCell` calcula ese mismo 20% con
+ * `alpha()`, que lo resuelve una sola vez y contra el esquema claro. Un tema sin variables se
+ * queda sin relleno —el contorno y el texto siguen en pie—.
+ *
+ * Se exporta porque el rótulo no siempre cabe: donde hay que reducirlo a un punto de color
+ * —un encabezado angosto— ese punto tiene que decir lo mismo, y la única forma de que no se
+ * separen con el tiempo es que el color salga de aquí.
+ */
+declare const statusColors: (severity?: StatusColor) => {
+    /** Texto y contorno. */
+    ink: string;
+    /** Fondo. */
+    fill: string;
+};
+/**
+ * El color que le toca a un estado, según el mapa que declara el proyecto:
+ *
+ *     const coloresDeEstado: Record<string, StatusColor> = { "1": "warning", "2": "info" };
+ *
+ * Es el mismo mapa que recibe `renderChipCell`, y esa es la idea: el estado "2" se ve igual en
+ * la columna de una tabla que en la cabecera de su ficha, sin declararlo dos veces.
+ *
+ * El estado llega como lo manda el backend —`{ value: "2", label: "Nueva" }`—, así que busca
+ * primero por código, que es lo estable, y después por etiqueta sin distinguir mayúsculas, para
+ * los endpoints que sólo mandan el texto. Sin mapa —o sin coincidencia— queda un último intento:
+ * que el propio valor sea ya un nombre de la paleta, que es como se pintaban los estados cuando
+ * el backend mandaba la severidad en vez del código.
+ *
+ * Devuelve `undefined` cuando no encuentra ninguno, y eso es una respuesta: la insignia se pinta
+ * neutra en vez de inventarle un color a un estado que nadie clasificó.
+ */
+declare const resolveStatusColor: (estado: unknown, colors?: Record<string, StatusColor>) => StatusColor | undefined;
 declare const StatusBadge: React__default.FC<StatusBadgeProps>;
 
 interface CoverPageCardProps$1 {
@@ -737,6 +792,12 @@ interface MainDrawerV2Props {
     /** Radio de las esquinas del panel de contenido. Por defecto `theme.shape.borderRadius`. */
     contentBorderRadius?: number;
     slots?: {
+        /**
+         * Lo que califica al título y va pegado a él —el estado de un registro—. No se encoge:
+         * lo que cede ancho cuando el encabezado se queda corto es el título, que ya corta con
+         * elipsis.
+         */
+        badge?: ReactNode;
         /** Acciones del encabezado, a la izquierda del botón de cerrar. */
         headerActions?: ReactNode;
         /** Pie fijo — no scrollea con el cuerpo. Pensado para guardar/cancelar. */
@@ -828,6 +889,16 @@ declare module "@mui/x-data-grid" {
         pageType: PageType;
     }
 }
+/**
+ * Campo del panel de edición. Es el mismo campo de un formulario, salvo que su `display` puede
+ * ser una función: la evalúa contra la fila que se está editando, así una fila pinta sólo los
+ * campos que le tocan según lo que ya tiene capturado —una condición de "primer envío" no lleva
+ * cantidad, y pedirla nada más para ignorarla al guardar confunde a quien la captura.
+ */
+interface ArrayFieldItemProps extends Omit<FieldProps$1, "display"> {
+    /** Por defecto `true`. Como función, recibe la fila en edición y su índice. */
+    display?: boolean | ((row: any, index: number) => boolean);
+}
 interface ArrayFieldProps {
     name: string;
     label: string;
@@ -838,7 +909,7 @@ interface ArrayFieldProps {
     gridProps?: GridProps;
     pageType?: PageType;
     parser?: JSONParserProps;
-    fields: FieldProps$1[];
+    fields: ArrayFieldItemProps[];
     /**
      * What the edit panel's fields resolve their `size` breakpoints against. Defaults to
      * `"container"`: that panel is a drawer, narrow by construction. It needs its own setting
@@ -1803,7 +1874,7 @@ interface DeleteGridColumnsProps {
  */
 declare const deleteColumn: (props: DeleteGridColumnsProps) => GridColDefPropsOverrides[];
 
-type ChipColor = "primary" | "secondary" | "error" | "warning" | "info" | "success";
+type ChipColor = StatusColor;
 type ChipOption = {
     value: string;
     label: string;
@@ -1943,6 +2014,75 @@ declare const ControlledAmountWithCurrency: {
     formatDetail({ fieldData, extraProps, data, name, }: DetailRenderProps): string;
 };
 
+/**
+ * Helpers puros del `ControlledAutocomplete`: los argumentos de la consulta, la
+ * lista que se muestra y las cuentas del "seleccionar todo". Viven fuera del
+ * componente para poder probarlos sin montar MUI ni RTK Query.
+ */
+
+/** Una opción del desplegable, tal como la devuelve `como_opciones`. */
+interface AutocompleteOption {
+    value: any;
+    label: string;
+}
+
+interface ControlledAutocompleteProps {
+    name: string;
+    label?: string;
+    /** Control de react-hook-form; lo inyecta el `EditField` o el panel de filtros. */
+    control?: any;
+    /** Props que se pasan tal cual al `Autocomplete` (ganan sobre las de aquí). */
+    fieldProps?: Partial<AutocompleteProps<any, any, any, any>>;
+    extraProps?: {
+        /** Selección múltiple con casillas y chips. Por defecto, simple. */
+        multiple?: boolean;
+        /** Opciones fijas. Con ellas no se consulta nada y filtra el navegador. */
+        options?: AutocompleteOption[];
+        /** Origen remoto de las opciones (endpoint `como_opciones`). */
+        queryArgs?: ComoOpcionesProps;
+        /** Filtro contra el que se busca el texto. Por defecto `nombre__icontains`. */
+        searchField?: string;
+        /** Retardo del tecleo antes de consultar. Por defecto 400 ms. */
+        debounceMs?: number;
+        /** Caracteres mínimos para consultar. Por defecto 0 (lista completa al abrir). */
+        minChars?: number;
+        /** Fila de "seleccionar todo" en el modo múltiple. Por defecto, sí. */
+        selectAll?: boolean;
+        /** Quita el hueco reservado para el mensaje de error debajo del campo. */
+        disableHT?: boolean;
+    };
+}
+/**
+ * Desplegable de opciones para react-hook-form: simple o múltiple, con opciones
+ * fijas o consultadas a `como_opciones` según lo que se escribe. Unifica los
+ * `ControlledDropdown` (simple) y `ControlledSelect` (múltiple) de v1, que eran
+ * el mismo componente duplicado.
+ *
+ * ```ts
+ * {
+ *     name: "cliente",
+ *     label: "Cliente",
+ *     type: ControlledAutocomplete,
+ *     extraProps: { queryArgs: { endpoint: "clientes" } },
+ * }
+ * ```
+ *
+ * Sobre las peticiones, que era el punto flojo de v1:
+ *
+ * - **Una por apertura.** v1 pedía dos veces al abrir (el `onOpen` disparaba la
+ *   consulta y el efecto la repetía con retardo) y otra vez en cada render del
+ *   padre, porque `queryArgs` llega como objeto literal y su identidad cambiaba.
+ * - **Elegir una opción no consulta.** Al elegir, MUI reescribe el texto del
+ *   campo con la etiqueta; v1 lo trataba como búsqueda nueva y volvía a pedir.
+ * - **Sin parpadeo ni respuestas cruzadas.** La lista es la del hook de RTK
+ *   Query, que siempre corresponde a los últimos argumentos disparados; v1
+ *   guardaba las opciones en estado propio, las vaciaba en cada tecla y una
+ *   respuesta lenta podía pisar a una más nueva.
+ * - **Repetir una búsqueda sale de la caché**, incluido borrar el texto para
+ *   volver al listado completo.
+ */
+declare const ControlledAutocomplete: ControlledInput<ControlledAutocompleteProps>;
+
 interface ControlledColorProps {
     /** Ruta del color en el formulario. */
     name: string;
@@ -1990,8 +2130,16 @@ declare const ControlledColor: ControlledInput<ControlledColorProps>;
 declare const ControlledDate: ControlledInput;
 
 /**
- * `ControlledSelect` de v2. Reutiliza el renderizado de edición de v1 y añade el
- * renderizado de detalle (une las etiquetas de las opciones seleccionadas).
+ * `ControlledSelect` de v2: hoy es un `ControlledAutocomplete` en modo múltiple.
+ *
+ * Se conserva el nombre porque ya lo usan varias pantallas de los dos
+ * proyectos; lo que cambia por dentro es cuándo y cuántas veces se piden las
+ * opciones (ver `ControlledAutocomplete`). `disableHT` viene en `true` para no
+ * mover el alto de esas pantallas: el select de v1 no reservaba el renglón del
+ * mensaje de error. Quien lo necesite puede pasarlo en `false`.
+ *
+ * Para código nuevo conviene usar `ControlledAutocomplete` directamente, que
+ * además cubre el modo simple.
  */
 declare const ControlledSelect: ControlledInput;
 
@@ -2049,6 +2197,17 @@ interface SubsectionProps {
     fields?: FieldProps[];
     arrayFields?: ArrayFieldProps[];
     content?: (data: any) => ReactNode;
+    /**
+     * Acciones de la subsección, alineadas a la derecha en el renglón del título.
+     *
+     * Son de la subsección, no de su contenido: viven fuera del `Collapse`, así que siguen a la
+     * mano con la subsección plegada. Y son hermanas del título, no sus hijas: usarlas no la
+     * pliega —plegar es del título y su flecha, que es donde se declara con el cursor.
+     *
+     * El hueco que les queda a la derecha del título es suyo, así que una barra que sepa medirse
+     * —`ResponsiveActions`— puede encogerse ahí dentro en lugar de desbordar el renglón.
+     */
+    actions?: ReactNode | ((data: any) => ReactNode);
 }
 
 interface SectionProps extends Partial<Omit<MyTab, "children">> {
@@ -2368,6 +2527,13 @@ interface DetailFormDrawerProps {
         saveAndNext?: string;
     };
     slots?: {
+        /**
+         * Ruta al estado del registro —`"estado"`—, la misma que recibe `DetailPage_v2`: se
+         * pinta junto al título, como en la página, y con el mismo mapa de colores.
+         *
+         * @see DetailPageV2Props.slots.badge
+         */
+        badge?: string;
         /** Extra actions rendered in the header, left of the close button (e.g. "open full page"). */
         headerActions?: ReactNode;
     };
@@ -2376,6 +2542,10 @@ interface DetailFormDrawerProps {
         saveButton?: Partial<ButtonProps>;
         cancelButton?: Partial<ButtonProps>;
         saveAndNextButton?: Partial<ButtonProps>;
+        /** @see DetailPageV2Props.slotProps.badge */
+        badge?: {
+            colors?: Record<string, StatusColor>;
+        };
     };
 }
 /**
@@ -2473,6 +2643,23 @@ interface DrawerGridDrawerConfig {
      * de abrirlo en su página.
      */
     extraButtons?: DetailExtraButton[];
+    /**
+     * El estado del registro, junto al título de la cabecera del cajón —igual que en su página
+     * completa—. `path` es la ruta al campo dentro del dato, que el backend manda como
+     * `{ value, label }`, y `colors` dice de qué color va cada código:
+     *
+     *     badge: { path: "estado", colors: { "1": "warning", "2": "info" } }
+     *
+     * `colors` es el mismo mapa que recibe `renderChipCell`, así que lo natural es declararlo
+     * junto al catálogo y pasárselo a los dos: el estado se ve igual en la columna de la tabla
+     * que en el cajón que abre esa misma fila.
+     *
+     * @see DetailPageV2Props.slots.badge
+     */
+    badge?: {
+        path: string;
+        colors?: Record<string, StatusColor>;
+    };
     /** Runs after any successful create/edit (e.g. side effects; the grid refetches via RTK tag invalidation). */
     onSaved?: (response: any) => void;
     /**
@@ -2582,7 +2769,132 @@ interface ConfirmDialogProps {
  *  confirmar puede mostrar estado de carga mientras se resuelve la acción. */
 declare function ConfirmDialog({ open, titulo, mensaje, confirmLabel, cancelLabel, confirmColor, confirmIcon, isLoading, onConfirm, onClose, }: ConfirmDialogProps): react_jsx_runtime.JSX.Element;
 
-interface ActionsMenuProps {
+interface PulseDotProps {
+    /** Cuando es `true`, el punto es verde y parpadea; si no, usa `inactiveColor`. */
+    active: boolean;
+    /** Color cuando no está activo. Por defecto `error.main`. */
+    inactiveColor?: string;
+    /** Tamaño del punto en px. Por defecto 10. */
+    size?: number;
+    /** Título opcional; si se pasa, envuelve el punto en un Tooltip. */
+    title?: ReactNode;
+}
+/** Punto de estado: verde con animación de parpadeo cuando está activo, de lo
+ *  contrario un color fijo. Se usa para indicar conexión/actividad en vivo. */
+declare function PulseDot({ active, inactiveColor, size, title }: PulseDotProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * El contenedor que declara todo renglón que lleve un título y sus adornos: el encabezado de
+ * una página, el de un cajón y el de un diálogo.
+ *
+ * Se llama igual en los tres a propósito. Lo que aterriza en ese renglón —el estado de un
+ * registro, una barra de acciones— tiene que encogerse cuando el renglón se queda corto, y con
+ * un solo nombre esa regla se escribe una vez y sirve en los tres sitios: cada cosa mide contra
+ * el renglón que la contiene, que en una página es el ancho de la página y en un cajón de 460px
+ * es el del cajón. Los breakpoints del viewport no sabrían distinguirlos —la pantalla es la
+ * misma— y `@container` sí.
+ *
+ * No se pisan entre ellos aunque compartan nombre: un cajón y un diálogo se pintan por portal,
+ * fuera del árbol de la página, así que nunca hay uno dentro de otro. Y si lo hubiera, una
+ * `@container` resuelve contra el contenedor ancestro más cercano, que es justo el que manda.
+ */
+declare const HEADER_CONTAINER = "acv-header";
+/**
+ * Debajo de este ancho el renglón se considera angosto y lo que viva en él debería encogerse:
+ * la insignia de estado, por ejemplo, se queda en un punto de color con el rótulo en el globo.
+ *
+ * Se escribe como regla y no como número suelto para que quien la use no tenga que rearmar la
+ * consulta —ni equivocarse al hacerlo—:
+ *
+ *     sx={{ [HEADER_NARROW]: { display: "none" } }}
+ */
+declare const HEADER_NARROW = "@container acv-header (max-width: 600px)";
+/**
+ * Convierte un renglón en el contenedor contra el que se miden sus adornos.
+ *
+ * `inline-size`, nunca `size`: contener también el eje de bloque le fijaría la altura al
+ * encabezado, que crece con lo que lleva dentro —un subtítulo, un título en dos renglones—.
+ */
+declare const headerContainerSx: CSSObject;
+
+/**
+ * Cómo se está dibujando la barra. En orden de lo que ocupa: las acciones a la vista con su
+ * etiqueta, las mismas sólo con el icono, sólo las fijadas, o ninguna.
+ *
+ * El modo dice qué se dibuja *fuera* del menú; lo que quede fuera de eso —y lo que sobre del
+ * tope de `maxVisible`— está siempre dentro de él, así que hasta en `"full"` puede haber menú.
+ *
+ * `"pinned"` sólo es un escalón cuando hay alguna acción fijada; sin ellas la barra pasa de
+ * `"icons"` derecho a `"menu"`.
+ */
+declare const RESPONSIVE_ACTION_MODES: readonly ["full", "icons", "pinned", "menu"];
+type ResponsiveActionsMode = (typeof RESPONSIVE_ACTION_MODES)[number];
+interface ResponsiveAction {
+    /** Texto del botón; también lo que se lee en el menú y en el tooltip del modo icono. */
+    label: string;
+    /** Se dibuja como `startIcon`, como el botón entero, o a la izquierda del renglón del menú. */
+    icon: ReactNode;
+    onClick: () => void;
+    /** Ayuda larga. Sustituye a `label` como tooltip —el modo icono siempre lleva uno. */
+    tooltip?: string;
+    disabled?: boolean;
+    /** Spinner en lugar del icono, y la acción bloqueada mientras tanto. */
+    loading?: boolean;
+    /** También tiñe el renglón del menú, para que la acción se vea igual se dibuje como se dibuje. */
+    color?: ButtonProps["color"];
+    /**
+     * La última en esconderse: cuando el renglón deja de dar para todas, esta se queda a la vista
+     * —como icono— y las demás se van al menú. Es para la que se usa siempre (editar, en una
+     * ficha); fijar media barra no sirve de mucho, porque entonces ese escalón acaba pesando casi
+     * lo mismo que el anterior y se salta solo.
+     */
+    pinned?: boolean;
+}
+interface ResponsiveActionsProps {
+    actions: ResponsiveAction[];
+    /**
+     * Cuántas acciones se dibujan como botón, como mucho. Las demás se van al menú desde el
+     * primer modo, quepan o no: es un tope de cuántas *merecen* estar a la vista, no de cuántas
+     * caben —de eso ya se encarga la medición—. Sin él salen todas.
+     *
+     * Se queda con las primeras, así que el orden manda: lo importante va delante. Fijar una
+     * acción (`pinned`) no la adelanta, sólo la hace la última en esconderse.
+     */
+    maxVisible?: number;
+    /** @default "small" */
+    size?: "small" | "medium";
+    /** Fija el modo y apaga la medición. Para cuando el ancho no es quien debe decidir. */
+    mode?: ResponsiveActionsMode;
+}
+/**
+ * Una barra de acciones que se encoge sola cuando deja de caber: primero pierde las etiquetas y
+ * se queda en iconos, después esconde en un menú de tres puntos todo menos lo fijado, y al final
+ * se mete ahí entera.
+ *
+ * Encogerse es cosa del ancho; cuántas acciones merecen un botón, no. Para eso está `maxVisible`,
+ * que manda al menú lo que pase de la cuenta aunque sobre sitio —una barra de ocho botones cabe
+ * en una pantalla ancha y aun así no hay quien la lea—.
+ *
+ * Mide, no adivina. Los breakpoints del viewport no sirven aquí —la misma barra vive en una
+ * página ancha y en un cajón de 460px, donde la pantalla es grande y el hueco no—, así que
+ * compara el ancho que le dejaron con el que sus botones piden y baja un escalón cuando no
+ * alcanza. Es el mismo motivo por el que el layout de los campos resuelve por `@container`.
+ *
+ * Para que la medición signifique algo, el padre tiene que ser un renglón flex que le deje
+ * crecer al sobrante: la raíz se estira (`flexGrow`) para que su ancho *sea* el hueco, y los
+ * botones van dentro sin encogerse, así que su ancho es lo que piden de verdad.
+ */
+declare const ResponsiveActions: ({ actions, maxVisible, size, mode: forcedMode, }: ResponsiveActionsProps) => react_jsx_runtime.JSX.Element | null;
+
+interface DetailActionsProps {
+    /**
+     * Editar. Va fijada, así que es la última en irse al menú cuando el renglón se estrecha: es
+     * la acción de siempre en una ficha, y la que se busca sin leer. Se lleva consigo el Ctrl+E
+     * que vivía en `EditButton`, el botón suelto que esta barra vino a sustituir.
+     */
+    edit?: {
+        onClick: () => void;
+    };
     delete?: {
         mutation: any;
         disableNavBack?: boolean;
@@ -2599,8 +2911,14 @@ interface ActionsMenuProps {
         icon: ReactNode;
         onClick: () => void;
     }[];
-    /** Tamaño del botón que abre el menú. `"small"` para las cabeceras del cajón. */
+    /** Tamaño de los botones. `"small"` para las cabeceras del cajón. */
     size?: "small" | "medium";
+    /**
+     * Fija cómo se dibuja la barra en vez de dejar que se mida. El cajón lo usa para quedarse
+     * siempre en el menú de tres puntos: su cabecera ya lleva sus propios botones al lado.
+     * @see ResponsiveActionsProps.mode
+     */
+    mode?: ResponsiveActionsMode;
 }
 
 interface DetailPageV2Props {
@@ -2626,13 +2944,19 @@ interface DetailPageV2Props {
     slots?: {
         button?: ReactNode;
         /**
-         * Acciones propias del registro, junto a las del armazón. En `"detail"` viven dentro
-         * del menú de acciones; en alta y edición, como iconos al lado de Guardar.
+         * Acciones propias del registro, junto a las del armazón. En `"detail"` entran en la
+         * barra de acciones; en alta y edición, como iconos al lado de Guardar.
          *
          * Las mismas se le pueden pasar al cajón de `DrawerGrid_v2` (`drawer.extraButtons`),
          * para que el registro traiga sus acciones se abra donde se abra.
          */
         extraButtons?: DetailExtraButton[];
+        /**
+         * Ruta al estado del registro dentro del dato —`"estado"`—, que el backend manda como
+         * `{ value, label }`: se lee la etiqueta y el código decide el color.
+         *
+         * @see DetailPageV2Props.slotProps.badge
+         */
         badge?: string;
     };
     slotProps?: {
@@ -2645,15 +2969,30 @@ interface DetailPageV2Props {
             cancel?: Partial<ButtonProps>;
         };
         /**
-         * The history panel opened from the actions menu. It docks beside the page rather
+         * The history panel opened from the actions bar. It docks beside the page rather
          * than floating over it, so the record stays readable next to what the history says
-         * about it — see `ActionsMenuProps.historial` for how to change that.
+         * about it — see `DetailActionsProps.historial` for how to change that.
          */
-        historial?: ActionsMenuProps["historial"];
+        historial?: DetailActionsProps["historial"];
         permissionsPath?: string;
         deleteButton?: {
             disableNavBack?: boolean;
         };
+        badge?: {
+            /**
+             * De qué color se pinta cada estado, por código:
+             *
+             *     colors: { "1": "warning", "2": "info", "3": "success" }
+             *
+             * Es el mismo mapa que recibe `renderChipCell` en las columnas de una tabla, así que
+             * lo natural es declararlo junto al catálogo y pasarlo a los dos: el estado "2" se ve
+             * igual en la lista que en la ficha.
+             *
+             * Sin mapa la insignia queda neutra —gris—, que es como se veían todos antes de que
+             * hubiera con qué distinguirlos.
+             */
+            colors?: Record<string, StatusColor>;
+        };
     };
 }
 declare function DetailPage(props: DetailPageV2Props): react_jsx_runtime.JSX.Element;
@@ -2684,11 +3023,27 @@ interface DetailFormDialogProps {
         save?: string;
         cancel?: string;
     };
+    slots?: {
+        /**
+         * Ruta al estado del registro —`"estado"`—, la misma que recibe `DetailPage_v2`: se
+         * pinta junto al título, con el mismo mapa de colores.
+         *
+         * Un diálogo es angosto por construcción, así que casi siempre se verá como el punto de
+         * color con el rótulo en el globo.
+         *
+         * @see DetailPageV2Props.slots.badge
+         */
+        badge?: string;
+    };
     slotProps?: {
         dialog?: Partial<DialogProps>;
         content?: Partial<DialogContentProps>;
         saveButton?: Partial<ButtonProps>;
         cancelButton?: Partial<ButtonProps>;
+        /** @see DetailPageV2Props.slotProps.badge */
+        badge?: {
+            colors?: Record<string, StatusColor>;
+        };
     };
 }
 /**
@@ -2697,7 +3052,7 @@ interface DetailFormDialogProps {
  * becomes a `DialogTitle` and the buttons move into `DialogActions`. The save button lives
  * outside the `<form>` tree, so it submits via the native `form={formId}` attribute.
  */
-declare function DetailFormDialog({ open, onClose, title, api, form, sections, pageType, permissionsPath, onSuccess, responsiveTo, containerBreakpoints, labels, slotProps, }: DetailFormDialogProps): react_jsx_runtime.JSX.Element;
+declare function DetailFormDialog({ open, onClose, title, api, form, sections, pageType, permissionsPath, onSuccess, responsiveTo, containerBreakpoints, labels, slots, slotProps, }: DetailFormDialogProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Encabezado por defecto del `PageContainer`: resuelve título y breadcrumbs a
@@ -2706,6 +3061,11 @@ declare function DetailFormDialog({ open, onClose, title, api, form, sections, p
  *
  * El título se lee de `state.header.title` (slice `headerReducer` de la librería)
  * cuando hay un id en la ruta; de lo contrario se deriva del título de la página.
+ *
+ * Pinta la misma estructura que el `PageHeader` de Toolpad —breadcrumbs arriba, título
+ * y barra de acciones abajo— y no aquel componente, porque su título es un `string` y
+ * aquí hace falta poder poner algo a su lado: el hueco donde aterriza la nota de la
+ * página (ver `PageInfo`).
  **/
 /**
  * Página sin entrada en la navegación de Toolpad. Como `useActivePage` no la
@@ -2916,6 +3276,112 @@ interface MainLayoutProps {
 declare const SIDE_PANEL_WIDTH_VAR = "--acv-side-panel-width";
 declare const MainLayout: (props: MainLayoutProps) => react_jsx_runtime.JSX.Element;
 
+interface PageInfoProps {
+    /**
+     * La nota. Admite marcado —negritas, listas, enlaces—, así que puede ser lo mismo
+     * que antes se pintaba en un `Alert` al principio del contenido.
+     */
+    children: ReactNode;
+    /** Nombre accesible del botón. */
+    label?: string;
+    /** Ancho máximo del globo, en px. */
+    maxWidth?: number;
+}
+/**
+ * Explica la página desde un botón junto a su título, en vez de gastar un `Alert` en la
+ * primera pantalla: el que ya sabe cómo funciona no vuelve a leerlo, pero sigue a mano
+ * para el que llega nuevo.
+ *
+ * Se declara dentro de la página —no pinta nada donde se pone— y viaja por portal hasta
+ * el hueco del encabezado (ver `PageInfoHostContext`). Sólo puede haber una nota por
+ * página: dos `<PageInfo>` a la vez dejan los dos botones uno junto al otro.
+ *
+ *     <PageInfo>
+ *         El tope limita la <strong>suma de los porcentajes</strong> del mes.
+ *     </PageInfo>
+ *
+ * El globo se abre al pasar el cursor y también al llegar al botón con el tabulador, y
+ * es interactivo: se puede entrar en él a copiar el texto o a seguir un enlace.
+ **/
+declare const PageInfo: ({ children, label, maxWidth }: PageInfoProps) => react_jsx_runtime.JSX.Element | null;
+
+interface PageInfoHost {
+    /**
+     * El nodo que el encabezado reserva junto al título, o `null` mientras no haya uno
+     * —pantalla completa, o un `pageHeader` propio que no lo reserve—.
+     */
+    element: HTMLElement | null;
+    /** Lo publica el encabezado al montarse, y lo retira (`null`) al desmontarse. */
+    publicar: (element: HTMLElement | null) => void;
+}
+/**
+ * Cómo llega la nota de una página hasta el costado de su título.
+ *
+ * La nota la escribe la página —es texto suyo, no del cascarón— pero se pinta en el
+ * encabezado, que ni siquiera es hijo suyo: `PageContainer` lo dibuja aparte del
+ * `Outlet`. Así que `<PageInfo>` se declara donde se quiera dentro de la página y se
+ * teletransporta (portal) hasta `element`.
+ *
+ * Fuera de un `MainLayout` el contexto es `null` y `<PageInfo>` no pinta nada, en vez de
+ * soltar el botón en medio del contenido.
+ */
+declare const PageInfoHostContext: React.Context<PageInfoHost | null>;
+/** El hueco de la nota del encabezado, o `null` si no hay ninguno arriba. */
+declare const usePageInfoHost: () => PageInfoHost | null;
+
+interface PageActionsHost {
+    /**
+     * El nodo que el encabezado deja libre a la derecha del título, o `null` mientras no haya
+     * uno —pantalla completa, o un `pageHeader` propio que no lo reserve—.
+     */
+    element: HTMLElement | null;
+    /** Lo publica el encabezado al montarse, y lo retira (`null`) al desmontarse. */
+    publicar: (element: HTMLElement | null) => void;
+}
+/**
+ * Cómo llegan las acciones de una página hasta el renglón de su título.
+ *
+ * Mismo viaje que la nota de la página (ver `PageInfoHostContext`) y por la misma razón: las
+ * acciones son de la página, pero se pintan en el encabezado, que ni siquiera es hijo suyo.
+ * La diferencia está en para qué sirve el hueco. La nota sólo necesitaba dónde aterrizar; estas
+ * necesitan además *cuánto espacio hay*, y por eso el hueco se queda con el sobrante del renglón
+ * en vez de ceñirse a su contenido: así una barra que se mide sola (`ResponsiveActions`) puede
+ * comparar lo que piden sus botones contra lo que el título le dejó, y encogerse cuando ya no
+ * alcanza. Es la respuesta que la esquina flotante del `ContentLayout` no sabe dar: al estar
+ * posicionada y ajustarse a su contenido, ahí el hueco y los botones miden siempre lo mismo.
+ *
+ * Fuera de un `MainLayout` el contexto es `null`, y quien lo use se las arregla por su cuenta
+ * —la página de detalle vuelve a la esquina flotante de siempre—.
+ */
+declare const PageActionsHostContext: React.Context<PageActionsHost | null>;
+/** El hueco de las acciones del encabezado, o `null` si no hay ninguno arriba. */
+declare const usePageActionsHost: () => PageActionsHost | null;
+
+interface PageBadgeHost {
+    /**
+     * El nodo que el encabezado reserva al lado del título, o `null` mientras no haya uno
+     * —pantalla completa, o un `pageHeader` propio que no lo reserve—.
+     */
+    element: HTMLElement | null;
+    /** Lo publica el encabezado al montarse, y lo retira (`null`) al desmontarse. */
+    publicar: (element: HTMLElement | null) => void;
+}
+/**
+ * Cómo llega el estado de un registro hasta el lado de su título.
+ *
+ * Mismo viaje que la nota (ver `PageInfoHostContext`) y que las acciones
+ * (`PageActionsHostContext`); lo que cambia es dónde aterriza y por qué. El estado califica al
+ * registro igual que su nombre —"embarque 12345, cerrado"—, así que se lee junto a él y no en
+ * la otra punta del renglón: allí quedaba pegado a los botones, como si fuera uno más, y encima
+ * gastaba el ancho que las acciones necesitan para no encogerse.
+ *
+ * Fuera de un `MainLayout` el contexto es `null` y la página de detalle vuelve a colgar la
+ * insignia de la esquina flotante del `ContentLayout`, que es donde vivía.
+ */
+declare const PageBadgeHostContext: React.Context<PageBadgeHost | null>;
+/** El hueco de la insignia del encabezado, o `null` si no hay ninguno arriba. */
+declare const usePageBadgeHost: () => PageBadgeHost | null;
+
 /**
  * Contenido por defecto de cada snack dentro de `ObjectProgressStack`.
  * Muestra una barra de progreso (determinada si `progress` viene definido,
@@ -3172,19 +3638,5 @@ interface UseColorModeResult {
 }
 declare function useColorMode(): UseColorModeResult;
 
-interface PulseDotProps {
-    /** Cuando es `true`, el punto es verde y parpadea; si no, usa `inactiveColor`. */
-    active: boolean;
-    /** Color cuando no está activo. Por defecto `error.main`. */
-    inactiveColor?: string;
-    /** Tamaño del punto en px. Por defecto 10. */
-    size?: number;
-    /** Título opcional; si se pasa, envuelve el punto en un Tooltip. */
-    title?: ReactNode;
-}
-/** Punto de estado: verde con animación de parpadeo cuando está activo, de lo
- *  contrario un color fijo. Se usa para indicar conexión/actividad en vivo. */
-declare function PulseDot({ active, inactiveColor, size, title }: PulseDotProps): react_jsx_runtime.JSX.Element;
-
-export { APIContext, APIProvider, AccountMenuContent, ActiveCell, ActiveIcon, Base, ButtonWithDrawer, COLOR_SCHEME_SELECTOR, CSVUpload, ChipCell, ConfirmDialog, ContentLayout, ControlledAddressAutocomplete, ControlledAmountWithCurrency, ControlledColor, ControlledDate$1 as ControlledDate, ControlledDate as ControlledDate_v2, ControlledDropdown, ControlledFileField$1 as ControlledFileField, ControlledFileField as ControlledFileField_v2, FileUploadBox as ControlledFileUploadBox, ControlledNumber, ControlledPhoneNumber, ControlledSelect$1 as ControlledSelect, ControlledSelect as ControlledSelect_v2, ControlledSlider as ControlledSimpleSlider, ControlledSlider$1 as ControlledSlider, ControlledSwitch, ControlledText, ControlledTimePicker, ControlledToggleButtons, CoverPage, CreateButtonBase, CreateButtonWithMenuOptions, CrudDropdown, CustomNoRows, DEFAULT_FORM_BREAKPOINTS, DEFAULT_PAGINATION, DeleteButton, DeleteConfirmationDialog, DetailFormDialog as DetailFormDialog_v2, DetailFormDrawer as DetailFormDrawer_v2, DetailForm as DetailForm_v2, DetailPage$1 as DetailPage, DetailPage as DetailPage_v2, DrawerGrid as DrawerGrid_v2, EditButton, ExportCSV$1 as ExportCSV, ExportCSV as ExportCSV_v2, ExtraButtons, FORM_CONTAINER_NAME, GlobalSearch, HistorialDrawer, KpiCard, LAYER_ORDER, ListPage, Loadable, LoadingComponent, Logo, MainDrawer, MainDrawer$1 as MainDrawer_v2, MainLayout, MenuItemWithLoading, ModuleCard, MoreOptions, MyGridEditSingleSelect, NavigationContext, NavigationProvider, NormalOrIcon, NotAllowed, NotFound, NotificationItem, NotificationsBell, ObjectProgressStack, PAGE_SIZE_OPTIONS, Panel, PollingCountdownChip, PulseDot, SIDE_PANEL_WIDTH_VAR, SaveCancelButton, ServerGrid as ServerGrid_v2, SidePanelHostContext, StatusBadge, StyledMenu, Tabs, Transitions, TrueFalse, UncontrolledText, changeTitle, closeProgressSnack, composeGridProps, deleteColumn$1 as deleteColumn, deleteColumn as deleteColumn_v2, editColumn, filterQuery, formContainerSx, formGridSx, formParser, _default as headerReducer, manualCacheRefresh, mergeSettings, openProgressSnack, query, renderChipCell, renderEditCellWithErrorTooltip, resolveChipOption, resolveInitialState, setErrors, _default$1 as snackProgressReducer, tags, theme, togglableFields, updateProgressSnackData, useAPI, useColorMode, useDetailForm, useHasPermission, useHasPermission_v2, useKeyboardShortcut, useMutationHandler, useNavigation, useServerGrid, useSidePanelHost, valueLabel };
-export type { APIcontextProps, AccountMenuContentProps, AccountMenuItem, AddressValue, AppTheme, ChipCellProps, ChipColor, ChipOption, ColorMode, ComoOpcionesProps, ConfirmDialogProps, ControlledInput, CustomFilterDef, CustomToolbarProps, DeleteGridColumnsProps$1 as DeleteGridColumnsProps, DetachedPage, DetailExtraButton, DetailFormApi, DetailFormConfig, DetailFormController, DetailFormDialogProps, DetailFormDrawerNavigation, DetailFormDrawerProps, DetailFormProps, DetailFormStatus, DetailPageV2Props, DetailRenderProps, DrawerGridDrawerConfig, DrawerGridEditConfig, DrawerGridProps, EditGridColumnsProps, EditReadOnlyFields, ExportCSVProps as ExportCSVProps_v2, FieldFilter, FieldProps$1 as FieldProps, FieldValidationProps, FilterInput, FormBreakpoint, FormGridSxOptions, GlobalSearchOption, GlobalSearchProps, GridArgs, GridColDefPropsOverrides, GridLayerContribution, GridLayerId, GridLayerMap, JSONFormProps, JSONParserProps, KeyboardShortcut, KpiCardProps, MainDrawerV2Props, MainLayoutFooterConfig, MainLayoutPageHeaderProps, MainLayoutProps, MainLayoutSidebarFooterProps, MyDataGridProps, MyGridFilterModel, MyTab, MyTabProps, NotificationItemProps, NotificationsApi, NotificationsBellProps, PageType, PanelProps, PollingCountdownChipProps, ProgressStatusProps, PulseDotProps, RowsSnapshot, ServerGridArgs, ServerGridCreateApi, ServerGridDataApi, ServerGridDeleteApi, ServerGridEditApi, ServerGridEditToggleApi, ServerGridHandle, ServerGridProps, ServerGridSnapshot, ServerGridState, SidePanelHost, UseColorModeResult, UseServerGridOptions };
+export { APIContext, APIProvider, AccountMenuContent, ActiveCell, ActiveIcon, Base, ButtonWithDrawer, COLOR_SCHEME_SELECTOR, CSVUpload, ChipCell, ConfirmDialog, ContentLayout, ControlledAddressAutocomplete, ControlledAmountWithCurrency, ControlledAutocomplete, ControlledColor, ControlledDate$1 as ControlledDate, ControlledDate as ControlledDate_v2, ControlledDropdown, ControlledFileField$1 as ControlledFileField, ControlledFileField as ControlledFileField_v2, FileUploadBox as ControlledFileUploadBox, ControlledNumber, ControlledPhoneNumber, ControlledSelect$1 as ControlledSelect, ControlledSelect as ControlledSelect_v2, ControlledSlider as ControlledSimpleSlider, ControlledSlider$1 as ControlledSlider, ControlledSwitch, ControlledText, ControlledTimePicker, ControlledToggleButtons, CoverPage, CreateButtonBase, CreateButtonWithMenuOptions, CrudDropdown, CustomNoRows, DEFAULT_FORM_BREAKPOINTS, DEFAULT_PAGINATION, DeleteButton, DeleteConfirmationDialog, DetailFormDialog as DetailFormDialog_v2, DetailFormDrawer as DetailFormDrawer_v2, DetailForm as DetailForm_v2, DetailPage$1 as DetailPage, DetailPage as DetailPage_v2, DrawerGrid as DrawerGrid_v2, EditButton, ExportCSV$1 as ExportCSV, ExportCSV as ExportCSV_v2, ExtraButtons, FORM_CONTAINER_NAME, GlobalSearch, HEADER_CONTAINER, HEADER_NARROW, HistorialDrawer, KpiCard, LAYER_ORDER, ListPage, Loadable, LoadingComponent, Logo, MainDrawer, MainDrawer$1 as MainDrawer_v2, MainLayout, MenuItemWithLoading, ModuleCard, MoreOptions, MyGridEditSingleSelect, NavigationContext, NavigationProvider, NormalOrIcon, NotAllowed, NotFound, NotificationItem, NotificationsBell, ObjectProgressStack, PAGE_SIZE_OPTIONS, PageActionsHostContext, PageBadgeHostContext, PageInfo, PageInfoHostContext, Panel, PollingCountdownChip, PulseDot, RESPONSIVE_ACTION_MODES, ResponsiveActions, SIDE_PANEL_WIDTH_VAR, SaveCancelButton, ServerGrid as ServerGrid_v2, SidePanelHostContext, StatusBadge, StyledMenu, Tabs, Transitions, TrueFalse, UncontrolledText, changeTitle, closeProgressSnack, composeGridProps, deleteColumn$1 as deleteColumn, deleteColumn as deleteColumn_v2, editColumn, filterQuery, formContainerSx, formGridSx, formParser, headerContainerSx, _default as headerReducer, manualCacheRefresh, mergeSettings, openProgressSnack, query, renderChipCell, renderEditCellWithErrorTooltip, resolveChipOption, resolveInitialState, resolveStatusColor, setErrors, _default$1 as snackProgressReducer, statusColors, tags, theme, togglableFields, updateProgressSnackData, useAPI, useColorMode, useDetailForm, useHasPermission, useHasPermission_v2, useKeyboardShortcut, useMutationHandler, useNavigation, usePageActionsHost, usePageBadgeHost, usePageInfoHost, useServerGrid, useSidePanelHost, valueLabel };
+export type { APIcontextProps, AccountMenuContentProps, AccountMenuItem, AddressValue, AppTheme, AutocompleteOption, ChipCellProps, ChipColor, ChipOption, ColorMode, ComoOpcionesProps, ConfirmDialogProps, ControlledAutocompleteProps, ControlledInput, CustomFilterDef, CustomToolbarProps, DeleteGridColumnsProps$1 as DeleteGridColumnsProps, DetachedPage, DetailExtraButton, DetailFormApi, DetailFormConfig, DetailFormController, DetailFormDialogProps, DetailFormDrawerNavigation, DetailFormDrawerProps, DetailFormProps, DetailFormStatus, DetailPageV2Props, DetailRenderProps, DrawerGridDrawerConfig, DrawerGridEditConfig, DrawerGridProps, EditGridColumnsProps, EditReadOnlyFields, ExportCSVProps as ExportCSVProps_v2, FieldFilter, FieldProps$1 as FieldProps, FieldValidationProps, FilterInput, FormBreakpoint, FormGridSxOptions, GlobalSearchOption, GlobalSearchProps, GridArgs, GridColDefPropsOverrides, GridLayerContribution, GridLayerId, GridLayerMap, JSONFormProps, JSONParserProps, KeyboardShortcut, KpiCardProps, MainDrawerV2Props, MainLayoutFooterConfig, MainLayoutPageHeaderProps, MainLayoutProps, MainLayoutSidebarFooterProps, MyDataGridProps, MyGridFilterModel, MyTab, MyTabProps, NotificationItemProps, NotificationsApi, NotificationsBellProps, PageActionsHost, PageBadgeHost, PageInfoHost, PageInfoProps, PageType, PanelProps, PollingCountdownChipProps, ProgressStatusProps, PulseDotProps, ResponsiveAction, ResponsiveActionsMode, ResponsiveActionsProps, RowsSnapshot, ServerGridArgs, ServerGridCreateApi, ServerGridDataApi, ServerGridDeleteApi, ServerGridEditApi, ServerGridEditToggleApi, ServerGridHandle, ServerGridProps, ServerGridSnapshot, ServerGridState, SidePanelHost, StatusColor, UseColorModeResult, UseServerGridOptions };