@axzydev/axzy_ui_system 1.4.7 → 1.4.8

package/src/components/organisms/data-table/dataTable.tsx

@@ -85,6 +85,26 @@ export default function ITDataTable<T extends Record<string, unknown>>({
   rowHeight,
   overscan = 5,
   stickyHeader = false,
+  showViewToggle = true,
+  design,
+  colors,
+  containerStyle,
+  cardClassName,
+  cardStyle,
+  toolbarClassName,
+  toolbarStyle,
+  headerClassName,
+  headerStyle,
+  headerCellClassName,
+  headerCellStyle,
+  rowClassName,
+  rowStyle,
+  cellClassName,
+  cellStyle,
+  cardsClassName,
+  cardsStyle,
+  footerClassName,
+  footerStyle,
 }: ITDataTableProps<T>) {
   const [viewMode, setViewMode] = useState<"table" | "cards">(defaultView || "table");
   const { ref: rootRef, width: containerWidth } = useElementSize<HTMLDivElement>();
@@ -92,6 +112,27 @@ export default function ITDataTable<T extends Record<string, unknown>>({
   const [totalItems, setTotalItems] = useState(0);
   const [isLoading, setIsLoading] = useState(fetchOnMount);
 
+  // Per-instance color overrides written as local `--color-table-*` variables.
+  // Declared on the wrapper (an ancestor), they beat the global theme's
+  // `:root` values for this subtree only.
+  const colorVars = {
+    ...(colors?.headerBg ? { "--color-table-headerBg": colors.headerBg } : {}),
+    ...(colors?.headerText ? { "--color-table-headerText": colors.headerText } : {}),
+    ...(colors?.rowBg ? { "--color-table-rowBg": colors.rowBg } : {}),
+    ...(colors?.rowText ? { "--color-table-rowText": colors.rowText } : {}),
+    ...(colors?.rowHover ? { "--color-table-rowHover": colors.rowHover } : {}),
+  } as React.CSSProperties;
+
+  /** Merge a `design` slot with its flat shortcut (flat wins) into className/style. */
+  const mergeSlot = (
+    slot: { className?: string; style?: React.CSSProperties } | undefined,
+    flatClassName?: string,
+    flatStyle?: React.CSSProperties
+  ) => ({
+    className: clsx(slot?.className, flatClassName),
+    style: { ...slot?.style, ...flatStyle } as React.CSSProperties,
+  });
+
   const isFixed = layout === "fixed";
   const forcedCards =
     autoCardBreakpoint > 0 && containerWidth > 0 && containerWidth < autoCardBreakpoint;
@@ -409,6 +450,29 @@ export default function ITDataTable<T extends Record<string, unknown>>({
     onRowClick(row, event);
   };
 
+  const containerSlot = mergeSlot(design?.container, containerClassName, containerStyle);
+  const cardSlot = mergeSlot(design?.card, cardClassName, cardStyle);
+  const toolbarSlot = mergeSlot(design?.toolbar, toolbarClassName, toolbarStyle);
+  const headerSlot = mergeSlot(design?.header, headerClassName, headerStyle);
+  const headerCellSlot = mergeSlot(design?.headerCell, headerCellClassName, headerCellStyle);
+  const rowSlot = mergeSlot(design?.row, rowClassName, rowStyle);
+  const cellSlot = mergeSlot(design?.cell, cellClassName, cellStyle);
+  const cardsSlot = mergeSlot(design?.cards, cardsClassName, cardsStyle);
+  const footerSlot = mergeSlot(design?.footer, footerClassName, footerStyle);
+
+  const viewToggle = (
+    <div className="flex items-center bg-slate-100 dark:bg-slate-800/80 rounded-lg p-0.5 border border-slate-200 dark:border-slate-700/50">
+      <button onClick={() => setViewMode("table")} disabled={forcedCards} className={segCtrlClass("table")}>
+        <FaTable size={11} />
+        Table
+      </button>
+      <button onClick={() => setViewMode("cards")} className={segCtrlClass("cards")}>
+        <FaThLarge size={11} />
+        Cards
+      </button>
+    </div>
+  );
+
   const tableEl = (
     <table
       className={clsx(
@@ -439,7 +503,8 @@ export default function ITDataTable<T extends Record<string, unknown>>({
       )}
       <thead>
         <tr
-          className={clsx(tableHeaderRow, "dark:text-slate-200")}
+          className={clsx(tableHeaderRow, "dark:text-slate-200", headerSlot.className)}
+          style={headerSlot.style}
           aria-rowindex={isTableVirtual ? 1 : undefined}
         >
           {columns.map((col) => {
@@ -455,23 +520,23 @@ export default function ITDataTable<T extends Record<string, unknown>>({
                 isPinned && "sticky",
                 isStickyHeader && "sticky top-0 bg-secondary-50",
                 isPinned ? "z-[15]" : isStickyHeader && "z-10",
-                isPinned && (col.pinned === "left" ? "it-table-pinned-left" : "it-table-pinned-right")
+                isPinned && (col.pinned === "left" ? "it-table-pinned-left" : "it-table-pinned-right"),
+                headerCellSlot.className,
+                col.headerClassName
               )}
-              style={
-                col.minWidth != null || isStickyHeader || isPinned
-                  ? {
-                      ...(col.minWidth != null ? { minWidth: `${col.minWidth}px` } : {}),
-                      ...(isStickyHeader || isPinned
-                        ? { backgroundColor: "var(--color-table-headerBg, #f8fafc)" }
-                        : {}),
-                      ...(isPinned
-                        ? pin.side === "left"
-                          ? { left: pin.offset }
-                          : { right: pin.offset }
-                        : {}),
-                    }
-                  : undefined
-              }
+              style={{
+                ...(col.minWidth != null ? { minWidth: `${col.minWidth}px` } : {}),
+                ...(isStickyHeader || isPinned
+                  ? { backgroundColor: "var(--color-table-headerBg, #f8fafc)" }
+                  : {}),
+                ...(isPinned
+                  ? pin.side === "left"
+                    ? { left: pin.offset }
+                    : { right: pin.offset }
+                  : {}),
+                ...headerCellSlot.style,
+                ...col.headerStyle,
+              }}
             >
               <div className={isFixed ? "flex flex-col gap-3" : "flex flex-col gap-3 min-w-[150px]"}>
                 <div className="flex items-center justify-between gap-2">
@@ -516,8 +581,10 @@ export default function ITDataTable<T extends Record<string, unknown>>({
                   className={clsx(
                     tableRow,
                     variant === "striped" && absoluteIndex % 2 === 0 && "bg-secondary-50/40 dark:bg-slate-800/20",
-                    onRowClick && !isLoading && tableRowClickable
+                    onRowClick && !isLoading && tableRowClickable,
+                    rowSlot.className
                   )}
+                  style={rowSlot.style}
                   tabIndex={onRowClick && !isLoading ? 0 : undefined}
                   onClick={onRowClick && !isLoading ? handleRowClick(row) : undefined}
                   onKeyDown={onRowClick && !isLoading ? handleRowKeyDown(row) : undefined}
@@ -539,20 +606,20 @@ export default function ITDataTable<T extends Record<string, unknown>>({
                           col.align && tableAlignClasses[col.align],
                           isPinned && "sticky bg-[var(--color-table-rowBg,white)] group-hover:bg-[var(--color-table-rowHover,var(--color-secondary-50))]",
                           isPinned && (col.pinned === "left" ? "it-table-pinned-left" : "it-table-pinned-right"),
-                          isPinned && "z-[1]"
+                          isPinned && "z-[1]",
+                          cellSlot.className,
+                          col.cellClassName
                         )}
-                        style={
-                          col.minWidth != null || isPinned
-                            ? {
-                                ...(col.minWidth != null ? { minWidth: `${col.minWidth}px` } : {}),
-                                ...(isPinned
-                                  ? pin.side === "left"
-                                    ? { left: pin.offset }
-                                    : { right: pin.offset }
-                                  : {}),
-                              }
-                            : undefined
-                        }
+                        style={{
+                          ...(col.minWidth != null ? { minWidth: `${col.minWidth}px` } : {}),
+                          ...(isPinned
+                            ? pin.side === "left"
+                              ? { left: pin.offset }
+                              : { right: pin.offset }
+                            : {}),
+                          ...cellSlot.style,
+                          ...col.cellStyle,
+                        }}
                         title={truncateTitle}
                       >
                         {col.type === "actions" ? (
@@ -593,10 +660,20 @@ export default function ITDataTable<T extends Record<string, unknown>>({
   );
 
   return (
-    <div ref={rootRef} className={clsx("space-y-4 w-full relative", containerClassName)}>
-      <div className={tableContainer} style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
+    <div
+      ref={rootRef}
+      className={clsx("space-y-4 w-full relative", containerSlot.className)}
+      style={{ ...colorVars, ...containerSlot.style }}
+    >
+      <div
+        className={clsx(tableContainer, cardSlot.className)}
+        style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)', ...cardSlot.style }}
+      >
         {title && (
-          <div className="px-6 py-5 flex items-center justify-between" style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
+          <div
+            className={clsx("px-6 py-5 flex items-center justify-between", toolbarSlot.className)}
+            style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)', ...toolbarSlot.style }}
+          >
             <ITText as="h2" className="text-xl font-bold text-secondary-900 leading-tight">{title}</ITText>
             <div className="flex items-center gap-3">
               {isLoading && (
@@ -604,32 +681,14 @@ export default function ITDataTable<T extends Record<string, unknown>>({
                   {loadingIndicator || <FaSpinner className="animate-spin text-primary-500 text-xl" />}
                 </div>
               )}
-              <div className="flex items-center bg-slate-100 dark:bg-slate-800/80 rounded-lg p-0.5 border border-slate-200 dark:border-slate-700/50">
-                <button onClick={() => setViewMode("table")} disabled={forcedCards} className={segCtrlClass("table")}>
-                  <FaTable size={11} />
-                  Table
-                </button>
-                <button onClick={() => setViewMode("cards")} className={segCtrlClass("cards")}>
-                  <FaThLarge size={11} />
-                  Cards
-                </button>
-              </div>
+              {showViewToggle && viewToggle}
             </div>
           </div>
         )}
 
-        {!title && (
-          <div className="flex justify-end px-4 pt-3">
-            <div className="flex items-center bg-slate-100 dark:bg-slate-800/80 rounded-lg p-0.5 border border-slate-200 dark:border-slate-700/50">
-              <button onClick={() => setViewMode("table")} disabled={forcedCards} className={segCtrlClass("table")}>
-                <FaTable size={11} />
-                Table
-              </button>
-              <button onClick={() => setViewMode("cards")} className={segCtrlClass("cards")}>
-                <FaThLarge size={11} />
-                Cards
-              </button>
-            </div>
+        {!title && showViewToggle && (
+          <div className={clsx("flex justify-end px-4 pt-3", toolbarSlot.className)} style={toolbarSlot.style}>
+            {viewToggle}
           </div>
         )}
 
@@ -648,7 +707,7 @@ export default function ITDataTable<T extends Record<string, unknown>>({
           )}
 
           {effectiveView === "cards" ? (
-            <div className="p-4 space-y-3 max-h-[400px] overflow-y-auto">
+            <div className={clsx("p-4 space-y-3 max-h-[400px] overflow-y-auto", cardsSlot.className)} style={cardsSlot.style}>
               {data.length > 0 ? (
                 data.map((row, i) => (
                   <div
@@ -685,7 +744,10 @@ export default function ITDataTable<T extends Record<string, unknown>>({
         </div>
       </div>
 
-      <div className="rounded-b-xl px-6 py-4" style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
+      <div
+        className={clsx("rounded-b-xl px-6 py-4", footerSlot.className)}
+        style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)', ...footerSlot.style }}
+      >
         <ITPagination
           currentPage={currentPage}
           totalPages={computedTotalPages}

package/src/index.ts

@@ -119,7 +119,7 @@ import type { ITTripleFilterProps, ITTripleFilterOption } from "./components/org
 import type { ITToastProps } from "./components/organisms/toast/toast.props";
 import type { ITWysiwygProps } from "./components/molecules/wysiwyg/wysiwyg.props";
 import type { FieldConfig, FieldConfigV2 } from "./types/field.types";
-import type { ColumnFilters, ColumnFilterValue, TableDensity } from "./types/table.types";
+import type { ColumnFilters, ColumnFilterValue, TableColors, TableDensity, TableDesign, TableDesignProps, TableDesignSlot } from "./types/table.types";
 
 // UTILS
 import ITDropfile, { UploadStatus, FileTypeEnum } from "./components/organisms/dropfile/dropfile";
@@ -185,7 +185,7 @@ export {
     ITSegmentedControlProps, ITSidebarProps, ITSkeletonProps, ITSlideToggleProps, ITSliderProps,
     ITStackProps, ITStatCardProps, ITStepperProps, ITLineBarChartProps, ITLineBarDatum,
     ITTableProps, ITTabsProps, ITTabItem, ITTextProps, ITTextareaProps,
-    TableDensity,
+    TableColors, TableDensity, TableDesign, TableDesignProps, TableDesignSlot,
     ITTripleFilterProps, ITTripleFilterOption, ITThemeConfig, ITThemeProviderProps, ITThemePalette, ITThemeAppearance,
     ITTimePickerProps, ITToastProps,
     ITWysiwygProps,

package/src/showcases/DataShowcases.tsx

@@ -358,6 +358,9 @@ export const TableShowcase = () => {
           '// ITSearchSelect typeahead (server-side search opcional vía catalogOptions.onSearch)\n{ key: "role", label: "Role", type: "string", filter: "search", catalogOptions: { data: roles } }',
           '// ITDatePicker fecha única\n{ key: "lastLogin", label: "Last login", type: "date", filter: "date", dateFilterOptions: { maxDate: new Date() } }',
           '// ITDatePicker rango\n{ key: "hiredAt", label: "Hired", type: "date", filter: "date-range", dateFilterOptions: { maxDate: new Date() } }',
+          '// Diseño por instancia: colors pisa el tema; design estiliza cada región\n<ITTable columns={cols} data={rows} showViewToggle={false}\n  colors={{ headerBg: "#0f172a", headerText: "#e2e8f0", rowHover: "#e0f2fe" }}\n  design={{ card: { className: "rounded-2xl border-2 border-primary-200" }, headerCell: { className: "py-4" }, cell: { className: "font-semibold" } }} />',
+          '// Atajos planos equivalentes (ganan sobre design)*\n<ITTable columns={cols} data={rows} cardClassName="rounded-2xl" headerCellStyle={{ letterSpacing: "0.1em" }} rowClassName="border-b border-slate-100" cellClassName="font-semibold" />',
+          '// Diseño por columna\n{ key: "sales", label: "Sales", type: "number", headerClassName: "text-right", cellClassName: "text-right", cellStyle: { fontVariantNumeric: "tabular-nums" } }',
         ],
         props: [
           { name: "columns", type: "Column<T>[]", description: "Definiciones de columna: key, label, type, sortable, filter, render, actions." },
@@ -382,11 +385,24 @@ export const TableShowcase = () => {
           { name: "rowHeight", type: "number", default: "getRowHeight(size, density)", description: "Alto de fila asumido (px). Size-aware: baseline size=\"md\" = 33/45/53 según densidad; size lo desplaza por el line box (sm 16 / md 20 / lg 28 px)." },
           { name: "overscan", type: "number", default: "5", description: "Filas extra renderizadas arriba/abajo del viewport." },
           { name: "stickyHeader", type: "boolean", default: "false", description: "Header sticky mientras scrollea el cuerpo virtualizado." },
+          { name: "showViewToggle", type: "boolean", default: "true", description: "Muestra/oculta el switch Table|Cards. Ocultarlo no desactiva defaultView ni autoCardBreakpoint." },
+          { name: "colors", type: "TableColors", description: "Colores por instancia (headerBg, headerText, rowBg, rowText, rowHover); pisan el tema global solo en esta tabla." },
+          { name: "design", type: "TableDesign", description: "Estilo por región: container, card, toolbar, header, headerCell, row, cell, cards, footer. Cada uno con className y style." },
+          { name: "cardClassName / cardStyle", type: "string / CSSProperties", description: "Superficie tipo card (borde, radio, sombra, fondo)." },
+          { name: "toolbarClassName / toolbarStyle", type: "string / CSSProperties", description: "Barra con el título y el switch Table/Cards." },
+          { name: "headerClassName / headerStyle", type: "string / CSSProperties", description: "Fila de títulos (<thead> <tr>)." },
+          { name: "headerCellClassName / headerCellStyle", type: "string / CSSProperties", description: "Cada celda de encabezado (<th>)." },
+          { name: "rowClassName / rowStyle", type: "string / CSSProperties", description: "Cada fila del cuerpo (<tr>)." },
+          { name: "cellClassName / cellStyle", type: "string / CSSProperties", description: "Cada celda del cuerpo (<td>)." },
+          { name: "cardsClassName / cardsStyle", type: "string / CSSProperties", description: "Contenedor de la vista de cards." },
+          { name: "footerClassName / footerStyle", type: "string / CSSProperties", description: "Franja de paginación." },
+          { name: "containerStyle", type: "CSSProperties", description: "Estilos inline del contenedor externo." },
         ],
         notes: [
           "onRowClick funciona en ambas vistas (tabla y cards).",
           "Cuando se omite no se agrega cursor-pointer, foco, tabIndex ni role.",
-          "Column acepta width (number=px | string CSS), minWidth (px), align (left/center/right) y truncate (ellipsis + title nativo).",
+          "Column acepta width (number=px | string CSS), minWidth (px), align (left/center/right) y truncate (ellipsis + title nativo). Diseño por columna: headerClassName, headerStyle, cellClassName y cellStyle (className aplica a th y td).",
+          "Diseño por instancia: design (o los atajos planos <slot>ClassName/<slot>Style) estiliza container, card, toolbar, header, headerCell, row, cell, cards y footer; el atajo plano gana sobre design. colors instala --color-table-* locales y pisa el tema global. showViewToggle controla el switch Table|Cards y autoCardBreakpoint (px) fuerza la vista cards bajo ese ancho.",
           "Columna fija: Column acepta pinned: \"left\" | \"right\" (opt-in; omitir = sin cambios). Los offsets sticky acumulan el width en px de cada columna pinneada previa del mismo lado; una columna sin width en px aporta 0px, así que declara width en px en todas las columnas pinneadas de un lado. La celda pinneada pinta fondo opaco (rowBg + rowHover) y un separador de 1px en el borde congelado. Una columna pinneada por lado es el contrato probado. Limitación: con variant=\"striped\" el fondo opaco tapa el tinte de la franja de esa columna.",
           "Anti scroll horizontal: layout=\"fixed\" + width por columna + truncate + density.",
           "Virtualización: solo vista tabla; rinde con page size grande; filas de alto uniforme; el scroll no se reinicia al cambiar filtros.",
@@ -557,6 +573,58 @@ export const TableShowcase = () => {
               Role uses <code>filter: "search"</code> (ITSearchSelect). Last login uses <code>filter: "date"</code> and Hired uses <code>filter: "date-range"</code> (ITDatePicker), with <code>dateFilterOptions</code> bounds.
             </p>
           </div>
+
+          <div>
+            <h4 className="text-sm font-bold text-slate-700 dark:text-slate-200 mb-3">Design overrides — colors + design slots, sin switch</h4>
+            <div className="border border-slate-200 dark:border-slate-700 rounded-xl overflow-hidden">
+              <ITTable
+                columns={columns}
+                data={TABLE_DATA.slice(0, 5)}
+                title="Custom design"
+                defaultItemsPerPage={5}
+                showViewToggle={false}
+                colors={{
+                  headerBg: "#0f172a",
+                  headerText: "#e2e8f0",
+                  rowBg: "#ffffff",
+                  rowText: "#0f172a",
+                  rowHover: "#e0f2fe",
+                }}
+                design={{
+                  card: { className: "rounded-2xl border-2 border-primary-200 shadow-lg" },
+                  header: { className: "tracking-widest" },
+                  headerCell: { className: "py-4" },
+                  row: { className: "border-b border-slate-100" },
+                  cell: { className: "font-semibold" },
+                }}
+              />
+            </div>
+            <p className="mt-2 text-xs text-slate-500 dark:text-slate-400">
+              <code>colors</code> pisa el tema global solo para esta instancia; <code>design</code> (o los atajos <code>cardClassName</code>, <code>headerCellStyle</code>, <code>rowClassName</code>, <code>cellStyle</code>…) estiliza cada región. <code>showViewToggle=&#123;false&#125;</code> oculta el switch Table/Cards.
+            </p>
+          </div>
+
+          <div>
+            <h4 className="text-sm font-bold text-slate-700 dark:text-slate-200 mb-3">Per-column design — header y celda por columna</h4>
+            <div className="border border-slate-200 dark:border-slate-700 rounded-xl overflow-hidden">
+              <ITTable
+                columns={columns.map((col: any) =>
+                  col.key === "sales"
+                    ? { ...col, headerClassName: "text-right", cellClassName: "text-right", cellStyle: { fontVariantNumeric: "tabular-nums" } }
+                    : col.key === "name"
+                      ? { ...col, headerStyle: { letterSpacing: "0.1em" } }
+                      : col
+                )}
+                data={TABLE_DATA.slice(0, 5)}
+                title="Per-column"
+                defaultItemsPerPage={5}
+                showViewToggle={false}
+              />
+            </div>
+            <p className="mt-2 text-xs text-slate-500 dark:text-slate-400">
+              Cada <code>Column</code> acepta <code>headerClassName</code>, <code>headerStyle</code>, <code>cellClassName</code> y <code>cellStyle</code>, aplicados solo a esa columna.
+            </p>
+          </div>
         </div>
       }
     />
@@ -950,11 +1018,24 @@ export const DataTableShowcase = () => {
           { name: "rowHeight", type: "number", default: "getRowHeight(size, density)", description: "Alto de fila asumido (px). Size-aware: baseline size=\"md\" = 33/45/53 según densidad; size lo desplaza por el line box (sm 16 / md 20 / lg 28 px)." },
           { name: "overscan", type: "number", default: "5", description: "Filas extra renderizadas arriba/abajo del viewport." },
           { name: "stickyHeader", type: "boolean", default: "false", description: "Header sticky mientras scrollea el cuerpo virtualizado." },
+          { name: "showViewToggle", type: "boolean", default: "true", description: "Muestra/oculta el switch Table|Cards. Ocultarlo no desactiva defaultView ni autoCardBreakpoint." },
+          { name: "colors", type: "TableColors", description: "Colores por instancia (headerBg, headerText, rowBg, rowText, rowHover); pisan el tema global solo en esta tabla." },
+          { name: "design", type: "TableDesign", description: "Estilo por región: container, card, toolbar, header, headerCell, row, cell, cards, footer. Cada uno con className y style." },
+          { name: "cardClassName / cardStyle", type: "string / CSSProperties", description: "Superficie tipo card (borde, radio, sombra, fondo)." },
+          { name: "toolbarClassName / toolbarStyle", type: "string / CSSProperties", description: "Barra con el título y el switch Table/Cards." },
+          { name: "headerClassName / headerStyle", type: "string / CSSProperties", description: "Fila de títulos (<thead> <tr>)." },
+          { name: "headerCellClassName / headerCellStyle", type: "string / CSSProperties", description: "Cada celda de encabezado (<th>)." },
+          { name: "rowClassName / rowStyle", type: "string / CSSProperties", description: "Cada fila del cuerpo (<tr>)." },
+          { name: "cellClassName / cellStyle", type: "string / CSSProperties", description: "Cada celda del cuerpo (<td>)." },
+          { name: "cardsClassName / cardsStyle", type: "string / CSSProperties", description: "Contenedor de la vista de cards." },
+          { name: "footerClassName / footerStyle", type: "string / CSSProperties", description: "Franja de paginación." },
+          { name: "containerStyle", type: "CSSProperties", description: "Estilos inline del contenedor externo." },
         ],
         notes: [
           "onRowClick funciona en ambas vistas (tabla y cards).",
           "Interacciones que inician en botones, links o inputs no disparan onRowClick.",
-          "Column acepta width (number=px | string CSS), minWidth (px), align (left/center/right) y truncate (ellipsis + title nativo).",
+          "Column acepta width (number=px | string CSS), minWidth (px), align (left/center/right) y truncate (ellipsis + title nativo). Diseño por columna: headerClassName, headerStyle, cellClassName y cellStyle (className aplica a th y td).",
+          "Diseño por instancia: design (o los atajos planos <slot>ClassName/<slot>Style) estiliza container, card, toolbar, header, headerCell, row, cell, cards y footer; el atajo plano gana sobre design. colors instala --color-table-* locales y pisa el tema global. showViewToggle controla el switch Table|Cards y autoCardBreakpoint (px) fuerza la vista cards bajo ese ancho.",
           "Columna fija: Column acepta pinned: \"left\" | \"right\" (opt-in; omitir = sin cambios). Los offsets sticky acumulan el width en px de cada columna pinneada previa del mismo lado; una columna sin width en px aporta 0px, así que declara width en px en todas las columnas pinneadas de un lado. La celda pinneada pinta fondo opaco (rowBg + rowHover) y un separador de 1px en el borde congelado. Una columna pinneada por lado es el contrato probado. Limitación: con variant=\"striped\" el fondo opaco tapa el tinte de la franja de esa columna.",
           "Anti scroll horizontal: layout=\"fixed\" + width por columna + truncate + density.",
           "Virtualización: solo vista tabla; rinde con page size grande; filas de alto uniforme; el scroll no se reinicia al cambiar filtros.",
@@ -1023,6 +1104,30 @@ export const DataTableShowcase = () => {
             </div>
           </div>
 
+          <div>
+            <h4 className="text-sm font-bold text-slate-700 dark:text-slate-200 mb-3">Design overrides — colors + design slots, sin switch</h4>
+            <div className="border border-slate-200 dark:border-slate-700 rounded-xl overflow-hidden">
+              <ITDataTable
+                columns={userColumns}
+                fetchData={fetchData}
+                title="Custom design"
+                defaultItemsPerPage={4}
+                debounceMs={0}
+                showViewToggle={false}
+                colors={{ headerBg: "#0f172a", headerText: "#e2e8f0", rowHover: "#e0f2fe" }}
+                design={{
+                  card: { className: "rounded-2xl border-2 border-primary-200 shadow-lg" },
+                  headerCell: { className: "py-4" },
+                  row: { className: "border-b border-slate-100" },
+                  cell: { className: "font-semibold" },
+                }}
+              />
+            </div>
+            <p className="mt-2 text-xs text-slate-500 dark:text-slate-400">
+              <code>colors</code> pisa el tema global solo para esta instancia; <code>design</code> (o <code>cardClassName</code>, <code>headerCellStyle</code>, <code>rowClassName</code>, <code>cellStyle</code>…) estiliza cada región. <code>showViewToggle=&#123;false&#125;</code> oculta el switch.
+            </p>
+          </div>
+
           <div>
             <h4 className="text-sm font-bold text-slate-700 dark:text-slate-200 mb-3">Pinned columns — left (ID) &amp; right (Active)</h4>
             <div className="border border-slate-200 dark:border-slate-700 rounded-xl overflow-hidden" style={{ maxWidth: 520 }}>

package/src/types/table.types.ts

@@ -1,5 +1,115 @@
+import type { CSSProperties } from "react";
+
 export type TableVariants = "default" | "striped" | "bordered";
 
+/**
+ * A single, optional style slot for one region of a table. Both fields are
+ * merged *after* the component's built-in values.
+ */
+export interface TableDesignSlot {
+  /**
+   * Extra CSS classes merged after the built-in ones. Note that Tailwind
+   * resolves conflicts by utility order (not class order), so use inline
+   * `style` (or `!` modifiers) when a value must always win.
+   */
+  className?: string;
+  /** Inline CSS merged after the built-in values; wins over classes unless the global theme forces a value with `!important`. */
+  style?: CSSProperties;
+}
+
+/**
+ * Per-instance visual overrides for a table. Every region is optional and, when
+ * present, is applied on top of the built-in styles. The global
+ * `ITThemeProvider` colors (`--color-table-*`) still apply underneath, so use
+ * `TableColors` for this-instance color changes instead of `style`.
+ */
+export interface TableDesign {
+  /** Outermost wrapper (`space-y-4 w-full`). Prefer `containerClassName` for width/spacing. */
+  container?: TableDesignSlot;
+  /** The rounded card surface that wraps the toolbar, table and footer (border, radius, shadow, background). */
+  card?: TableDesignSlot;
+  /** Toolbar strip holding the title and/or the Table|Cards toggle. */
+  toolbar?: TableDesignSlot;
+  /** The `<thead>` row that carries the column titles. */
+  header?: TableDesignSlot;
+  /** Every `<th>` header cell. */
+  headerCell?: TableDesignSlot;
+  /** Every body `<tr>`. */
+  row?: TableDesignSlot;
+  /** Every body `<td>`. */
+  cell?: TableDesignSlot;
+  /** Scroll wrapper of the cards view (the responsive card list). */
+  cards?: TableDesignSlot;
+  /** Pagination footer strip. */
+  footer?: TableDesignSlot;
+}
+
+/**
+ * Per-instance color overrides. They are written as local `--color-table-*`
+ * variables on the table wrapper, so they beat the global theme for this
+ * instance only, without touching `ITThemeProvider`.
+ */
+export interface TableColors {
+  /** Header row background. Overrides the theme's `table.headerBg` for this instance. */
+  headerBg?: string;
+  /** Header text color. Overrides the theme's `table.headerText` for this instance. */
+  headerText?: string;
+  /** Body row background. Overrides the theme's `table.rowBg` for this instance. */
+  rowBg?: string;
+  /** Body text color. Overrides the theme's `table.rowText` for this instance. */
+  rowText?: string;
+  /** Body row hover background. Overrides the theme's `table.rowHover` for this instance. */
+  rowHover?: string;
+}
+
+/**
+ * Shared design props for ITTable and ITDataTable. `design` exposes every
+ * region as an object; the flat `*ClassName` / `*Style` shortcuts are merged
+ * after it, so the flat prop wins when both are provided.
+ */
+export interface TableDesignProps {
+  /** Whether to render the Table|Cards view switcher in the toolbar. Hiding it still honors `defaultView` and `autoCardBreakpoint`. @default true */
+  showViewToggle?: boolean;
+  /** Per-region visual overrides (classes + inline styles). */
+  design?: TableDesign;
+  /** Per-instance color overrides for header and rows, beating the global theme. */
+  colors?: TableColors;
+  /** Inline styles for the outermost wrapper. */
+  containerStyle?: CSSProperties;
+  /** Extra classes for the card surface (the rounded container). */
+  cardClassName?: string;
+  /** Inline styles for the card surface. */
+  cardStyle?: CSSProperties;
+  /** Extra classes for the toolbar strip (title + view toggle). */
+  toolbarClassName?: string;
+  /** Inline styles for the toolbar strip. */
+  toolbarStyle?: CSSProperties;
+  /** Extra classes for the header row. */
+  headerClassName?: string;
+  /** Inline styles for the header row. */
+  headerStyle?: CSSProperties;
+  /** Extra classes for every header cell. */
+  headerCellClassName?: string;
+  /** Inline styles for every header cell. */
+  headerCellStyle?: CSSProperties;
+  /** Extra classes for every body row. */
+  rowClassName?: string;
+  /** Inline styles for every body row. */
+  rowStyle?: CSSProperties;
+  /** Extra classes for every body cell. */
+  cellClassName?: string;
+  /** Inline styles for every body cell. */
+  cellStyle?: CSSProperties;
+  /** Extra classes for the cards-view scroll wrapper. */
+  cardsClassName?: string;
+  /** Inline styles for the cards-view scroll wrapper. */
+  cardsStyle?: CSSProperties;
+  /** Extra classes for the pagination footer strip. */
+  footerClassName?: string;
+  /** Inline styles for the pagination footer strip. */
+  footerStyle?: CSSProperties;
+}
+
 /**
  * Value stored for a single column filter.
  *