@m4l/components 9.3.21-JT15102025.beta.1 → 9.3.21-JT20102025.beta.1

package/components/DataGrid/DataGrid.js

@@ -38,8 +38,8 @@ function DataGrid(props) {
     size,
     externalSortSettings,
     externalFilterSettings,
-    cardSettings,
-    defaultViewMode
+    defaultViewMode,
+    cardsViewConfig
   } = props;
   const {
     withSettings,
@@ -93,8 +93,8 @@ function DataGrid(props) {
           size: currentSize,
           externalSortSettings,
           externalFilterSettings,
-          cardSettings,
           defaultViewMode,
+          cardsViewConfig,
           children: /* @__PURE__ */ jsxs(FilterProvider, { initialActiveFilters: false, children: [
             withActions && actionsProps && /* @__PURE__ */ jsx(
               HeaderActions,
@@ -122,7 +122,7 @@ function DataGrid(props) {
                 onSelectedRowsChange,
                 rowKeyGetter,
                 onRowsChange,
-                cardSettings
+                cardsViewConfig
               }
             ),
             withPager && /* @__PURE__ */ jsx(

package/components/DataGrid/contexts/DataGridContext/index.js

@@ -162,8 +162,8 @@ function DataGridProvider(props) {
     size,
     viewMode,
     onViewModeChange,
-    cardSettings,
-    defaultViewMode
+    defaultViewMode,
+    cardsViewConfig
   } = props;
   const isFirstRender = useFirstRender([columns, id]);
   const isMobile = useIsMobile();
@@ -270,7 +270,50 @@ function DataGridProvider(props) {
         }
       }
     }
-  }, [columns, sortSettings, filterSettings]);
+    if (cardsViewConfig !== void 0) {
+      const hasCustomRender = cardsViewConfig.customRender !== void 0;
+      const hasColumnsConfig = cardsViewConfig.columnsConfig !== void 0 && cardsViewConfig.columnsConfig.length > 0;
+      if (!hasCustomRender && !hasColumnsConfig) {
+        throw new Error(
+          `DataGridProvider: cardsViewConfig.enabled=true requiere configurar al menos una de estas opciones:
+          - cardsViewConfig.customRender (renderizado personalizado)
+          - cardsViewConfig.columnsConfig (configuración de columnas con al menos 1 elemento)
+
+          Configuración actual:
+          - customRender: ${hasCustomRender ? "definido" : "undefined"}
+          - columnsConfig: ${cardsViewConfig.columnsConfig?.length || 0} columnas
+
+          Ejemplo válido con columnsConfig:
+            cardsViewConfig={{
+              enabled: true,
+              columnsConfig: [
+                { columnKey: 'name', showTitle: false },
+                { columnKey: 'email', showTitle: true }
+              ]
+            }}
+
+          Ejemplo válido con customRender:
+            cardsViewConfig={{
+              enabled: true,
+              customRender: {
+                renderContent: (row) => <CustomCard row={row} />,
+                minHeight: 200
+              }
+            }}
+          `
+        );
+      }
+      if (hasColumnsConfig && cardsViewConfig.columnsConfig) {
+        for (const cardCol of cardsViewConfig.columnsConfig) {
+          if (!keys.has(cardCol.columnKey)) {
+            throw new Error(
+              `DataGridProvider: cardsViewConfig.columnsConfig incluye columnKey="${cardCol.columnKey}", pero no existe ninguna columna con key="${cardCol.columnKey}".`
+            );
+          }
+        }
+      }
+    }
+  }, [columns, sortSettings, filterSettings, cardsViewConfig]);
   const finalRowHeights = useMemo(() => rowHeights, [rowHeights]);
   let timerSaveColumns;
   useEffect(() => {
@@ -287,15 +330,29 @@ function DataGridProvider(props) {
           { originalFrozen: false }
         )
       );
+      const finalCardsConfig = (() => {
+        if (defaultUserColumns?.columnsConfigCards) {
+          return defaultUserColumns.columnsConfigCards;
+        }
+        if (cardsViewConfig?.columnsConfig) {
+          return cardsViewConfig.columnsConfig.map((colConfig, index) => ({
+            key: colConfig.columnKey,
+            visible: true,
+            index,
+            showTitle: colConfig.showTitle
+          }));
+        }
+        return void 0;
+      })();
       updateConfigColumns(
         "cards",
         getInitialColumnsConfig(
           id,
           columns,
           "cards",
-          defaultUserColumns?.columnsConfigCards,
-          { showTitle: true },
-          { originalShowTitle: true }
+          finalCardsConfig,
+          { showTitle: false },
+          { originalShowTitle: false }
         )
       );
     }
@@ -335,9 +392,14 @@ function DataGridProvider(props) {
         );
         if (newColumnsForView.length > 0) {
           const colLength = currentConfig.length;
-          const viewSpecific = getViewSpecificConfig(viewModeParam);
-          const viewSpecificDefaults = viewSpecific.defaults;
-          const originalViewSpecificDefaults = viewSpecific.originalDefaults;
+          const viewSpecificDefaults = viewModeParam === "cards" ? { showTitle: false } : {
+            frozen: false
+          };
+          const originalViewSpecificDefaults = viewModeParam === "cards" ? {
+            originalShowTitle: false
+          } : {
+            originalFrozen: false
+          };
           const newColConfig = getInitialColumnsConfig(
             id,
             newColumnsForView,
@@ -473,7 +535,7 @@ function DataGridProvider(props) {
         size,
         viewMode: viewModeState,
         onViewModeChange: handleViewModeChange,
-        cardSettings
+        cardsViewConfig
       },
       children
     }

package/components/DataGrid/contexts/DataGridContext/types.d.ts

@@ -79,7 +79,7 @@ export interface IGridConfig {
 export interface IGridConfigExtended extends IGridConfig {
     columnsConfigCards?: BaseConfigColumnCards[];
 }
-export interface DataGridProviderProps<TRow, TSummaryRow, TKey extends RowKey = RowKey> extends Pick<GridProps<TRow, TSummaryRow, TKey>, 'rows' | 'columns' | 'rowActionsGetter' | 'rowHeaderHeights' | 'rowHeights' | 'initialRowHeightVariant' | 'checkedRows' | 'onCheckedRowsChange' | 'rowKeyGetter' | 'onChangeUserColumns' | 'defaultUserColumns' | 'externalSortSettings' | 'externalFilterSettings' | 'cardSettings' | 'defaultViewMode'> {
+export interface DataGridProviderProps<TRow, TSummaryRow, TKey extends RowKey = RowKey> extends Pick<GridProps<TRow, TSummaryRow, TKey>, 'rows' | 'columns' | 'rowActionsGetter' | 'rowHeaderHeights' | 'rowHeights' | 'initialRowHeightVariant' | 'checkedRows' | 'onCheckedRowsChange' | 'rowKeyGetter' | 'onChangeUserColumns' | 'defaultUserColumns' | 'externalSortSettings' | 'externalFilterSettings' | 'defaultViewMode' | 'cardsViewConfig'> {
     id: number | string;
     children: ReactNode;
     rowsCount: number;
@@ -92,7 +92,7 @@ export type RowHeightState = {
     rowHeight: number;
     rowHeaderHeight: number;
 };
-export interface DataGridContextProps<TRow, TSummaryRow, TKey extends RowKey = RowKey> extends Pick<DataGridProviderProps<TRow, TSummaryRow, TKey>, 'rows' | 'checkedRows' | 'onCheckedRowsChange' | 'rowHeights' | 'rowsCount' | 'rowActionsGetter' | 'rowKeyGetter' | 'onChangeUserColumns' | 'externalSortSettings' | 'externalFilterSettings' | 'viewMode' | 'onViewModeChange' | 'cardSettings' | 'defaultViewMode'> {
+export interface DataGridContextProps<TRow, TSummaryRow, TKey extends RowKey = RowKey> extends Pick<DataGridProviderProps<TRow, TSummaryRow, TKey>, 'rows' | 'checkedRows' | 'onCheckedRowsChange' | 'rowHeights' | 'rowsCount' | 'rowActionsGetter' | 'rowKeyGetter' | 'onChangeUserColumns' | 'externalSortSettings' | 'externalFilterSettings' | 'viewMode' | 'onViewModeChange' | 'defaultViewMode' | 'cardsViewConfig'> {
     getConfigColumns: (viewMode: ViewMode) => IViewConfig[];
     onChangeColumnsConfig: (viewMode: ViewMode, config: IViewConfig[]) => void;
     onChangeColumnsOrder: (viewMode: ViewMode, sourceKey: string, targetKey: string) => void;

package/components/DataGrid/subcomponents/Cards/index.js

@@ -11,7 +11,7 @@ function Cards(props) {
     selectedRows,
     onSelectedRowsChange,
     onRowsChange,
-    cardSettings
+    cardsViewConfig
   } = props;
   const processedColumns = useProcessedColumns(columns);
   const allProcessedColumns = useProcessedColumns(columns, {
@@ -30,7 +30,7 @@ function Cards(props) {
       selectedRows,
       onSelectedRowsChange,
       onRowsChange,
-      cardSettings
+      customRender: cardsViewConfig?.customRender
     },
     rowKeyGetter(row)
   )) }) });

package/components/DataGrid/subcomponents/Cards/subcomponents/CardRow/index.d.ts

@@ -3,4 +3,4 @@ import { CardRowProps } from '../../types';
 /**
  * Componente que muestra una fila de tarjetas.
  */
-export declare function CardRow<TRow, TKey extends RowKey = RowKey>({ row, columns, originalColumns, rowKeyGetter, selectedRows, onSelectedRowsChange, onRowsChange, cardSettings, }: CardRowProps<TRow, TKey>): import("react/jsx-runtime").JSX.Element;
+export declare function CardRow<TRow, TKey extends RowKey = RowKey>({ row, columns, originalColumns, rowKeyGetter, selectedRows, onSelectedRowsChange, onRowsChange, customRender, }: CardRowProps<TRow, TKey>): import("react/jsx-runtime").JSX.Element;

package/components/DataGrid/subcomponents/Cards/subcomponents/CardRow/index.js

@@ -13,10 +13,10 @@ function CardRow({
   selectedRows,
   onSelectedRowsChange,
   onRowsChange,
-  cardSettings
+  customRender
 }) {
   const { checkedRows } = useDataGrid();
-  const render = cardSettings !== void 0 && cardSettings.renderContent !== void 0;
+  const hasCustomRender = customRender !== void 0;
   const { cardContent, columnsCount, onOpenDetail } = useCardContent({
     row,
     columns,
@@ -28,14 +28,14 @@ function CardRow({
     [checkedRows, rowKeyGetter, row]
   );
   const content = useMemo(() => {
-    if (render) {
-      return cardSettings?.renderContent(row);
+    if (hasCustomRender) {
+      return customRender.renderContent(row);
     }
     return /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsx(CardHeader, { row, onOpenDetail }),
       cardContent
     ] });
-  }, [render, cardSettings, row, cardContent, onOpenDetail]);
+  }, [hasCustomRender, customRender, row, cardContent, onOpenDetail]);
   const onCardClick = () => {
     if (selectedRows && onSelectedRowsChange) {
       if (selectedRows.has(rowKeyGetter(row))) {
@@ -46,11 +46,11 @@ function CardRow({
     }
   };
   const dynamicMinHeight = useMemo(() => {
-    if (render) {
-      return cardSettings?.minHeight;
+    if (hasCustomRender) {
+      return customRender.minHeight;
     }
     return Math.max(120, columnsCount * 32 + 40);
-  }, [render, cardSettings?.minHeight, columnsCount]);
+  }, [hasCustomRender, customRender, columnsCount]);
   return /* @__PURE__ */ jsx(LazyLoadCard, { threshold: 200, minHeight: dynamicMinHeight, children: /* @__PURE__ */ jsx(
     CardStyled,
     {

package/components/DataGrid/subcomponents/Cards/types.d.ts

@@ -1,5 +1,5 @@
 import { Column, RowsChangeData } from 'react-data-grid';
-import { CardSettings, RowKey } from '../../types';
+import { CardsViewConfig, RowKey } from '../../types';
 import { Maybe } from '@m4l/core';
 import { IViewConfig } from '../../contexts/DataGridContext/types';
 import { Sizes } from '@m4l/styles';
@@ -95,9 +95,9 @@ export interface CardRowProps<TRow, TKey extends RowKey = RowKey> {
      */
     onRowsChange?: Maybe<(rows: TRow[], data: RowsChangeData<TRow, any>) => void>;
     /**
-     * Configuración personalizada para renderizado de cards
+     * Indica si se debe renderizar el contenido personalizado de la tarjeta
      */
-    cardSettings?: CardSettings<TRow>;
+    customRender?: CardsViewConfig<TRow>['customRender'];
 }
 /**
  * Props para el componente CardDetails

package/components/DataGrid/subcomponents/HeaderActions/index.js

@@ -17,11 +17,10 @@ function HeaderActions(props) {
     rightActions,
     withPager,
     size,
-    columns,
-    withViewMode = true
+    columns
   } = props;
   const isMobile = useIsMobile();
-  const { rowHeights, viewMode, cardSettings } = useDataGrid();
+  const { rowHeights, viewMode, cardsViewConfig } = useDataGrid();
   const { currentSize } = useComponentSize(size);
   return /* @__PURE__ */ jsx(ActionsRootStyled, { ownerState: { size: currentSize }, children: isMobile ? /* @__PURE__ */ jsxs(Fragment, { children: [
     leftActions,
@@ -32,8 +31,8 @@ function HeaderActions(props) {
       leftActions,
       typeof rowHeights !== "number" && /* @__PURE__ */ jsx(Density, {}),
       withLocalFilters && /* @__PURE__ */ jsx(Filter, {}),
-      withSettings && !(viewMode === "cards" && !!cardSettings) && /* @__PURE__ */ jsx(Settings, { ...settingsProps, columns }),
-      withViewMode && /* @__PURE__ */ jsx(ViewMode, {})
+      withSettings && !(viewMode === "cards" && cardsViewConfig?.customRender) && /* @__PURE__ */ jsx(Settings, { ...settingsProps, columns }),
+      cardsViewConfig !== void 0 && /* @__PURE__ */ jsx(ViewMode, {})
     ] }),
     rightActions && /* @__PURE__ */ jsx(ContainerRightActionsStyled, { children: rightActions })
   ] }) });

package/components/DataGrid/tests/helpers/useCardsViewConfig.d.ts

@@ -0,0 +1,24 @@
+import { CardsViewConfig } from '../../types';
+interface UseCardsViewConfigProps {
+    /**
+     * Si es true, retorna cardsViewConfig con columnsConfig básica
+     */
+    withBasicConfig?: boolean;
+    /**
+     * Si es true, retorna cardsViewConfig con customRender
+     */
+    withCustomRender?: boolean;
+    /**
+     * Si es true, retorna cardsViewConfig solo con enabled=true (para demostrar error)
+     */
+    withEnabledOnly?: boolean;
+    /**
+     * Si es true, retorna cardsViewConfig con columnKey inválido (para demostrar error)
+     */
+    withInvalidColumnKey?: boolean;
+}
+/**
+ * Hook helper que genera configuraciones de cardsViewConfig para testing
+ */
+export declare const useCardsViewConfigHelper: <TRow = any>(props?: UseCardsViewConfigProps) => CardsViewConfig<TRow> | undefined;
+export {};

package/components/DataGrid/types.d.ts

@@ -150,14 +150,15 @@ export interface GridProps<TRow, TSummaryRow, TKey extends RowKey = RowKey> exte
      * @default 'medium'
      */
     size?: Extract<Sizes, 'small' | 'medium'>;
-    /**
-     * Configuración personalizada para renderizado de cards
-     */
-    cardSettings?: CardSettings<TRow>;
     /**
      * Modo por defecto de visualización
      */
     defaultViewMode?: ViewMode;
+    /**
+     * Configuración de la vista de "cards"
+     * Incluye habilitación, configuración de columnas y renderizado personalizado
+     */
+    cardsViewConfig?: CardsViewConfig<TRow>;
 }
 export declare const DATAGRID_TEST_ID = "m4ldatagrid";
 export declare const PREFIX_TEST_ATTRIBUTE = "data-testid";
@@ -177,7 +178,6 @@ export interface ActionsProps {
     withLocalFilters?: boolean;
     leftActions?: React.ReactNode;
     rightActions?: React.ReactNode;
-    withViewMode?: boolean;
 }
 /**
  * Props para el hook useModalDetail
@@ -189,12 +189,44 @@ export interface UseModalDetailProps<TRow> {
     onRowsChange?: Maybe<(rows: TRow[], data: RowsChangeData<TRow, any>) => void>;
 }
 /**
- * Configuración personalizada para renderizado de cards
+ * Configuración de una columna específica en vista "cards"
  */
-export interface CardSettings<TRow> {
-    renderContent: (row: TRow) => React.ReactNode;
-    minHeight: number;
+export interface CardColumnConfig {
+    /**
+     * Key de la columna (debe coincidir con la key de la columna)
+     */
+    columnKey: string;
+    /**
+     * Si se debe mostrar el título/label de esta columna en la card (Solo si no existe una config previa)
+     */
+    showTitle: boolean;
 }
+/**
+ * Cards con columnsConfig
+ */
+export interface CardsViewConfigWithColumns {
+    columnsConfig: CardColumnConfig[];
+    customRender?: never;
+}
+/**
+ * Cards con customRender
+ */
+export interface CardsViewConfigWithCustomRender<TRow> {
+    columnsConfig?: never;
+    customRender: {
+        renderContent: (row: TRow) => React.ReactNode;
+        minHeight: number;
+    };
+}
+/**
+ * Configuración para la vista de "cards"
+ *
+ * IMPORTANTE:
+ * Es OBLIGATORIO configurar al menos 1 columna cuando customRender=undefined
+ * Se ignora completamente si customRender está definido
+ * @throws Error si customRender=undefined y array está vacío
+ */
+export type CardsViewConfig<TRow> = CardsViewConfigWithColumns | CardsViewConfigWithCustomRender<TRow>;
 /**
  * Opciones para el procesamiento de columnas
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l/components",
-  "version": "9.3.21-JT15102025.beta.1",
+  "version": "9.3.21-JT20102025.beta.1",
   "license": "UNLICENSED",
   "description": "M4L Components",
   "lint-staged": {