@acvl/frontend-components 0.0.94 → 0.0.96

package/dist/index.d.ts

@@ -2937,6 +2937,32 @@ interface SubsectionProps {
     bgColor?: string;
     title?: string;
     description?: string;
+    /**
+     * Deja plegar la subsección desde su título: la flecha aparece a su izquierda y el renglón
+     * entero se vuelve el interruptor.
+     *
+     * Apagado por defecto. Plegar es una decisión de la ficha —un bloque largo, o uno que casi
+     * nunca se mira—, no una consecuencia de ponerle título: antes bastaba con titularla para
+     * que apareciera la flecha, así que un clic distraído en el encabezado escondía campos que
+     * nadie pidió esconder.
+     *
+     * Plegada mide sólo su encabezado, así que deja de estirarse a lo alto del renglón que
+     * comparte con sus hermanas: el hueco que ocupaba se lo queda lo que siga.
+     *
+     * Sin `title` no hay de dónde plegar —la flecha vive en su renglón—, así que se ignora.
+     * @default false
+     */
+    collapsible?: boolean;
+    /**
+     * Arranca plegada. Sólo aplica con `collapsible` —si no, no habría flecha con que abrirla—.
+     *
+     * Es el arranque, no una orden: en cuanto el usuario la pliega o la despliega manda su
+     * elección, que se recuerda mientras dure la sesión y para todas las fichas del mismo tipo
+     * (ver `DetailFormProps.storageScope`). Así que esto es para lo que casi nunca se mira
+     * —auditoría, totales de detalle— y no para esconder algo que el usuario va a necesitar.
+     * @default false
+     */
+    defaultCollapsed?: boolean;
     first?: boolean;
     slotProps?: {
         /**
@@ -2945,8 +2971,9 @@ interface SubsectionProps {
          * que un `{ xs: 12, md: 6 }` parte el formulario en dos columnas cuando *el formulario*
          * es ancho, no cuando lo es la pantalla.
          *
-         * La subsección se estira a lo alto del renglón que comparte con sus hermanas; un
-         * `alignSelf: "flex-start"` aquí la devuelve a medir solo lo que su contenido.
+         * La subsección se estira a lo alto del renglón que comparte con sus hermanas —salvo
+         * plegada, que mide su encabezado—; un `alignSelf: "flex-start"` aquí la devuelve a
+         * medir solo lo que su contenido.
          */
         parentGrid?: Partial<GridProps>;
     };
@@ -2966,7 +2993,16 @@ interface SubsectionProps {
     actions?: ReactNode | ((data: any) => ReactNode);
 }
 
-interface SectionProps extends Partial<Omit<MyTab, "children">> {
+/**
+ * Una sección de la ficha. Cuando hay más de una visible se vuelven pestañas, y el número de
+ * cada una lo pone `DetailForm` por su orden entre las visibles —"1", "2", "3"—.
+ *
+ * De ahí que no lleve `value`: la posición en la lista ya es su identidad, y escribirlo a mano
+ * era repetirla con otra letra. Repetida se desincroniza —una sección escondida dejaba huecos
+ * ("1" y "3") y la ficha abría en una pestaña que no estaba; una sección nueva al principio
+ * obligaba a renumerar a las de abajo—.
+ */
+interface SectionProps extends Partial<Omit<MyTab, "children" | "value">> {
     pageType?: PageType;
     display?: boolean;
     subsections: SubsectionProps[];
@@ -2988,6 +3024,20 @@ interface DetailFormApi {
         args?: any;
         disable?: boolean;
         successMessage?: string | ((response: any) => string);
+        /**
+         * Intercepts a 400 before the engine turns it into field errors and the generic
+         * "validation error" notification. Return `true` when the form has handled it.
+         *
+         * For the rejections that are **a question, not a failure** — the server refusing an
+         * action and telling the user how to insist. The case that asked for it: committing a
+         * trip segment over a colleague's soft hold answers 400 naming who holds it, and the
+         * screen has to offer "take it from them"; swallowed into the generic notification, that
+         * second step disappears and with it the whole point of the soft hold.
+         *
+         * `useMutationHandler` already had the hook — this only passes it through, which is what
+         * kept a form that needs it from using this engine at all.
+         */
+        onInvalidParams?: (error: any) => boolean;
         postAction?: {
             after: "create" | "edit" | "both";
             type: string;
@@ -3124,6 +3174,20 @@ interface DetailFormProps {
     formId?: string;
     /** Persist-tab key for multi-section forms. Defaults to `formId`. */
     storageKey?: string;
+    /**
+     * Bajo qué nombre recuerda el formulario lo que el usuario acomoda en él: hoy, cuáles
+     * subsecciones dejó plegadas (ver `SubsectionProps.collapsible`).
+     *
+     * Es a propósito más grueso que `storageKey`: este no lleva el registro, así que plegar una
+     * subsección en un embarque la deja plegada en todos. `DetailPage_v2` lo arma solo, con su
+     * ruta sin los parámetros.
+     *
+     * Sin esto no se recuerda nada —las subsecciones abren como diga `defaultCollapsed` y ya—.
+     * Ese es el default en un cajón o un diálogo, donde el `formId` es generado (`useId`) y la
+     * ruta es la del listado de atrás: ninguno de los dos nombra la ficha. Dales uno estable
+     * aquí —`"/embarques/bultos"`— y sus subsecciones empiezan a recordar.
+     */
+    storageScope?: string;
     /** Height factor passed to the loading spinner. Defaults to `0.7`. */
     loadingHeight?: number;
     /**
@@ -3154,7 +3218,7 @@ interface DetailFormProps {
  * element and the section/tab render tree — no page layout, no header buttons. Compose it
  * inside a page, dialog or drawer shell that supplies the surrounding chrome.
  */
-declare function DetailForm({ controller, formId, storageKey, loadingHeight, responsiveTo, containerBreakpoints, slotProps, }: DetailFormProps): react_jsx_runtime.JSX.Element;
+declare function DetailForm({ controller, formId, storageKey, storageScope, loadingHeight, responsiveTo, containerBreakpoints, slotProps, }: DetailFormProps): react_jsx_runtime.JSX.Element;
 
 /**
  * An action the consumer hangs off a record's chrome — cerrar, revertir, descargar el PDF —
@@ -3779,6 +3843,20 @@ interface DetailFormDrawerProps {
      * página. `display` y `onClick` reciben el registro cargado.
      */
     extraButtons?: DetailExtraButton[];
+    /**
+     * El historial del registro, igual que en su página completa: se ofrece sólo cuando el
+     * registro dice traerlo (`has_history`), abre el mismo panel y atiende el mismo
+     * Ctrl+Shift+H.
+     *
+     * `endpoint` es obligatorio en la práctica aunque el tipo lo deje pasar: el panel lo
+     * adivina de la ruta, y la ruta de un cajón es la del listado de atrás —`/embarques`, no
+     * `/embarques/123`—, así que sin él pediría el historial del listado. Sin `endpoint` no
+     * hay nada que ofrecer. `DrawerGrid_v2` lo arma solo con la ruta del registro.
+     *
+     * El panel hereda la colocación del cajón: acoplado si el cajón lo está, flotando si no
+     * —ver `variant`—.
+     */
+    historial?: DetailActionsProps["historial"];
     /**
      * Footer record navigator: prev/next arrows (Alt+↑ / Alt+↓) that step through a list of
      * sibling records — e.g. the rows of the grid the drawer was opened from — without
@@ -3824,6 +3902,13 @@ interface DetailFormDrawerProps {
     responsiveTo?: DetailFormProps["responsiveTo"];
     /** @see DetailFormProps.containerBreakpoints */
     containerBreakpoints?: DetailFormProps["containerBreakpoints"];
+    /**
+     * Enciende la memoria de las subsecciones plegadas, bajo este nombre. Aquí no hay default
+     * que valga: el `formId` es generado y la ruta es la del listado de atrás, así que la
+     * ficha tiene que nombrarse a mano —`"/embarques/bultos"`—.
+     * @see DetailFormProps.storageScope
+     */
+    storageScope?: DetailFormProps["storageScope"];
     labels?: {
         save?: string;
         cancel?: string;
@@ -3875,7 +3960,7 @@ interface DetailFormDrawerProps {
  * deja el registro en pantalla y editando — para formularios que se capturan de a poco o que
  * llevan una grilla adentro.
  */
-declare function DetailFormDrawer({ open, onClose, title, api, form, sections, pageType, startInEdit, recordKey, permissionsPath, onSuccess, keepOpenOnSave, extraButtons, navigation, width, anchor, variant, resizable, minWidth, maxWidth, widthStorageKey, onWidthChange, responsiveTo, containerBreakpoints, labels, slots, slotProps, }: DetailFormDrawerProps): react_jsx_runtime.JSX.Element;
+declare function DetailFormDrawer({ open, onClose, title, api, form, sections, pageType, startInEdit, recordKey, permissionsPath, onSuccess, keepOpenOnSave, extraButtons, historial, navigation, width, anchor, variant, resizable, minWidth, maxWidth, widthStorageKey, onWidthChange, responsiveTo, containerBreakpoints, storageScope, labels, slots, slotProps, }: DetailFormDrawerProps): react_jsx_runtime.JSX.Element;
 
 interface DrawerGridDrawerConfig {
     /** Shared field layout, used by every mode. Same shape as `DetailPage_v2`'s `form`/`sections`. */
@@ -3957,6 +4042,19 @@ interface DrawerGridDrawerConfig {
      * de abrirlo en su página.
      */
     extraButtons?: DetailExtraButton[];
+    /**
+     * Afina el historial del registro en la cabecera del cajón — el ancho del panel, o la ruta
+     * cuando no es la del registro. No hace falta declararlo para tenerlo: se ofrece solo en
+     * cuanto el registro dice traerlo (`has_history`).
+     *
+     * La ruta sale sola de la del registro, la misma que abre "ver en página completa" — que es
+     * de donde la saca también la página, del `pathname`. En una grilla con
+     * `showOpenFullPage: false` no hay ruta de la que sacarla, así que ahí hay que darla a mano
+     * o el historial no se ofrece.
+     *
+     * @see DetailFormDrawerProps.historial
+     */
+    historial?: DetailFormDrawerProps["historial"];
     /**
      * 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
@@ -4163,6 +4261,25 @@ interface DetailFormDialogProps {
     responsiveTo?: DetailFormProps["responsiveTo"];
     /** @see DetailFormProps.containerBreakpoints */
     containerBreakpoints?: DetailFormProps["containerBreakpoints"];
+    /**
+     * Enciende la memoria de las subsecciones plegadas, bajo este nombre. Aquí no hay default
+     * que valga: el `formId` es generado y la ruta es la del listado de atrás, así que la
+     * ficha tiene que nombrarse a mano —`"/embarques/bultos"`—.
+     * @see DetailFormProps.storageScope
+     */
+    storageScope?: DetailFormProps["storageScope"];
+    /**
+     * El historial del registro, igual que en su página completa: un botón en el renglón del
+     * título, con su Ctrl+Shift+H, que abre el mismo panel. Se ofrece sólo cuando el registro
+     * dice traerlo (`has_history`).
+     *
+     * `endpoint` es obligatorio en la práctica aunque el tipo lo deje pasar: el panel lo adivina
+     * de la ruta, y la ruta de un diálogo es la de la pantalla de atrás, no la del registro.
+     *
+     * El panel va flotando por fuerza: un diálogo es modal, y uno acoplado se pintaría en el
+     * hueco del layout, o sea por debajo de su backdrop.
+     */
+    historial?: DetailActionsProps["historial"];
     labels?: {
         save?: string;
         cancel?: string;
@@ -4196,7 +4313,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, slots, slotProps, }: DetailFormDialogProps): react_jsx_runtime.JSX.Element;
+declare function DetailFormDialog({ open, onClose, title, api, form, sections, pageType, permissionsPath, onSuccess, responsiveTo, containerBreakpoints, storageScope, historial, labels, slots, slotProps, }: DetailFormDialogProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Encabezado por defecto del `PageContainer`: resuelve título y breadcrumbs a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@acvl/frontend-components",
-    "version": "0.0.94",
+    "version": "0.0.96",
     "description": "Component library for ACV frontend projects.",
     "homepage": "https://github.com/ACV-Logistics/acv-frontend-components#readme",
     "access": "public",