@axzydev/axzy_ui_system 1.3.0 → 1.3.2

package/src/components/molecules/table/table.props.ts

@@ -1,4 +1,4 @@
-import { TableSize, TableVariants } from "@/types/table.types";
+import { TableDensity, TableSize, TableVariants } from "@/types/table.types";
 
 /** Data type of a table column, controls default rendering, filter UI, and sort comparison. */
 export type ColumnType = "string" | "date" | "number" | "boolean" | "actions" | "catalog";
@@ -46,6 +46,22 @@ export interface Column<T = any> {
     /** Shows an error state in the filter UI when the catalog failed to load. @default false */
     error?: boolean;
   };
+  /**
+   * Fixed column width. A `number` is treated as pixels (`width: 120` → `120px`);
+   * a `string` is passed through as any CSS length (`"20%"`, `"12rem"`).
+   * A `<colgroup>` is only rendered when at least one column defines a width.
+   */
+  width?: number | string;
+  /** Minimum column width in pixels, applied to the header and body cells via inline style. */
+  minWidth?: number;
+  /** Horizontal alignment of this column's header and body cells. @default "left" */
+  align?: "left" | "center" | "right";
+  /**
+   * Truncates overflowing cell content with an ellipsis and exposes the raw
+   * string/number value through the native `title` attribute.
+   * @default false
+   */
+  truncate?: boolean;
 }
 
 export interface ITTableProps<T> {
@@ -55,7 +71,7 @@ export interface ITTableProps<T> {
   containerClassName?: string;
   /** The data array to render in the table body. */
   data: T[];
-  /** Visual variant: "default", "striped", "bordered", "borderless". */
+  /** Visual variant: "default", "striped", "bordered". */
   variant?: TableVariants;
   /** Additional CSS classes for the root table wrapper. */
   className?: string;
@@ -75,4 +91,67 @@ export interface ITTableProps<T> {
   showVerticalBorder?: boolean;
   /** Custom class for vertical borders (overrides the default subtle gray). */
   verticalBorderClassname?: string;
+  /**
+   * Callback fired when a row (table view) or card (cards view) is activated,
+   * receiving the row item and the originating event. The event is a
+   * `MouseEvent` for pointer interaction and a `KeyboardEvent` for Enter/Space
+   * activation. Not fired when the interaction starts inside an interactive
+   * child (button, link, input, or any `[data-row-click-ignore]` element).
+   */
+  onRowClick?: (
+    row: T,
+    event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>
+  ) => void;
+  /**
+   * Table layout algorithm. `"fixed"` respects column `width` values and drops
+   * the `min-w-max` / `min-w-[150px]` floors so content no longer forces
+   * horizontal scrolling; `"auto"` keeps the content-driven layout.
+   * @default "auto"
+   */
+  layout?: "auto" | "fixed";
+  /**
+   * Cell padding and row-height preset. Independent of `size`, which only
+   * controls font-size: `"compact"` | `"normal"` | `"comfortable"`.
+   * @default "normal"
+   */
+  density?: TableDensity;
+  /**
+   * Container width (in px) below which the table automatically falls back to
+   * the cards view. `0` disables the fallback.
+   * @default 0
+   */
+  autoCardBreakpoint?: number;
+  /**
+   * Enables row virtualization for the table view: only the visible window of
+   * rows is rendered, with spacer rows preserving the full scroll height.
+   * The cards view is never virtualized.
+   * @default false
+   */
+  virtualized?: boolean;
+  /**
+   * Max height (px) of the virtualized table's scroll container.
+   * Only used when `virtualized` is true.
+   * @default 400
+   */
+  virtualizedMaxHeight?: number;
+  /**
+   * Assumed uniform row height (px) used by the virtualizer. Defaults to
+   * `getRowHeight(size, density)`, which is size-aware: the `size="md"`
+   * baseline is 33 / 45 / 53 (compact / normal / comfortable) and `size`
+   * shifts it by the font-size line box (sm 16px / md 20px / lg 28px).
+   * Only used when `virtualized` is true.
+   */
+  rowHeight?: number;
+  /**
+   * Number of extra rows rendered above and below the viewport to avoid blank
+   * gaps while scrolling. Only used when `virtualized` is true.
+   * @default 5
+   */
+  overscan?: number;
+  /**
+   * Makes the header cells sticky while the virtualized body scrolls. Only
+   * effective when `virtualized` is true.
+   * @default false
+   */
+  stickyHeader?: boolean;
 }

package/src/components/molecules/table/table.stories.tsx

@@ -21,6 +21,14 @@ const meta: Meta<typeof ITTable> = {
       control: "select",
       options: ["sm", "md", "lg"],
     },
+    density: {
+      control: "select",
+      options: ["compact", "normal", "comfortable"],
+    },
+    layout: {
+      control: "select",
+      options: ["auto", "fixed"],
+    },
   },
 };
 
@@ -170,3 +178,150 @@ export const EmptyState: Story = {
       title: "No Data Available",
     } as any,
 };
+
+// Wrapper for clickable rows/cards
+const RowClickWrapper = (args: any) => {
+    const [selected, setSelected] = useState<User | null>(null);
+
+    return (
+      <div className="space-y-3">
+        <p className="text-sm font-medium text-slate-500">
+          {selected
+            ? `Selected: ${selected.name} (id ${selected.id})`
+            : "Click a row/card or press Enter/Space while focused"}
+        </p>
+        <ITTable
+          {...args}
+          onRowClick={(row: User) => setSelected(row)}
+        />
+      </div>
+    );
+};
+
+export const WithRowClick: Story = {
+    render: (args) => <RowClickWrapper {...args} />,
+    args: {
+      columns: basicColumns,
+      data: mockData.slice(0, 5),
+      title: "Clickable Rows",
+    } as any,
+};
+
+export const WithRowClickCards: Story = {
+    render: (args) => <RowClickWrapper {...args} />,
+    args: {
+      columns: basicColumns,
+      data: mockData.slice(0, 5),
+      title: "Clickable Cards",
+      defaultView: "cards",
+    } as any,
+};
+
+// --- CONFIGURABLE LAYOUT / DENSITY ---
+
+const longCellData: User[] = [
+  {
+    id: 1,
+    name: "Extraordinariamente Largo Nombre de Usuario Que No Cabe",
+    email: "usuario.con.un.correo.extremadamente.largo@example-enterprise-domain.com",
+    roleId: 1,
+    balance: 28400,
+    isActive: true,
+    lastLogin: "2026-07-18T09:30:00",
+  },
+  {
+    id: 2,
+    name: "Otra Persona Con Un Nombre Bastante Extenso Para Probar",
+    email: "otra.persona.con.correo.extenso@example-enterprise-domain.com",
+    roleId: 2,
+    balance: 15200,
+    isActive: false,
+    lastLogin: "2026-07-17T14:22:00",
+  },
+];
+
+const fixedColumns: Column<User>[] = [
+  { key: "id", label: "ID", type: "number", width: 64, minWidth: 48, align: "center" },
+  { key: "name", label: "Name", type: "string", width: "35%", truncate: true },
+  { key: "email", label: "Email", type: "string", width: "45%", truncate: true },
+];
+
+export const CompactDensity: Story = {
+  args: {
+    columns: advancedColumns.map(col => ({ ...col, render: undefined })),
+    data: mockData,
+    title: "Compact Density",
+    density: "compact",
+    defaultItemsPerPage: 8,
+  } as any,
+};
+
+export const FixedLayoutWithWidths: Story = {
+  render: (args: any) => (
+    <div style={{ width: 480 }} className="rounded-lg border border-dashed border-slate-300">
+      <ITTable {...args} />
+    </div>
+  ),
+  args: {
+    columns: fixedColumns,
+    data: longCellData,
+    title: "Fixed layout · no horizontal scroll",
+    layout: "fixed",
+    density: "compact",
+    defaultItemsPerPage: 5,
+  } as any,
+};
+
+export const AutoCardsNarrowContainer: Story = {
+  render: (args: any) => (
+    <div style={{ width: 420 }} className="rounded-lg border border-dashed border-slate-300">
+      <ITTable {...args} />
+    </div>
+  ),
+  args: {
+    columns: basicColumns,
+    data: mockData.slice(0, 6),
+    title: "Auto cards under 640px",
+    autoCardBreakpoint: 640,
+    defaultItemsPerPage: 6,
+  } as any,
+};
+
+// --- VIRTUALIZATION ---
+
+const virtualColumns: Column<User>[] = [
+  { key: "id", label: "ID", type: "number", width: 72, minWidth: 56, align: "center" },
+  { key: "name", label: "Name", type: "string", width: "30%", truncate: true },
+  { key: "email", label: "Email", type: "string", width: "40%", truncate: true },
+  {
+    key: "roleId",
+    label: "Role",
+    type: "catalog",
+    width: "30%",
+    truncate: true,
+    catalogOptions: { data: mockRoles },
+  },
+];
+
+export const VirtualizedLargeDataset: Story = {
+  render: (args: any) => (
+    <div className="space-y-2">
+      <p className="text-xs text-slate-500">
+        250 rows · only the visible window is mounted (~10–20 &lt;tr&gt; + at most 2 spacer rows)
+      </p>
+      <ITTable {...args} />
+    </div>
+  ),
+  args: {
+    columns: virtualColumns,
+    data: generateMockData(250),
+    title: "Virtualized · 250 rows",
+    virtualized: true,
+    stickyHeader: true,
+    layout: "fixed",
+    density: "compact",
+    virtualizedMaxHeight: 360,
+    defaultItemsPerPage: 250,
+    itemsPerPageOptions: [50, 100, 250],
+  } as any,
+};

package/src/components/molecules/table/table.tsx

@@ -1,5 +1,7 @@
 import { useTableState } from "@/hooks/useTableState";
-import { sizeStyles, variantStyles } from "@/types/table.types";
+import { useElementSize } from "@/hooks/useElementSize";
+import { useVirtualRows } from "@/hooks/useVirtualRows";
+import { getRowHeight, sizeStyles, tableAlignClasses, variantStyles } from "@/types/table.types";
 import clsx from "clsx";
 import React, { useState } from "react";
 import {
@@ -18,6 +20,7 @@ import ITText from "@/components/atoms/text/text";
 import {
   tableActionsCell,
   tableBody,
+  tableCardClickable,
   tableCell,
   tableCellText,
   tableContainer,
@@ -25,8 +28,9 @@ import {
   tableHeaderCell,
   tableHeaderRow,
   tableRow,
+  tableRowClickable,
 } from "@/utils/styles";
-import { formatCurrencyMX, getNestedValue } from "@/utils/table.utils";
+import { formatCurrencyMX, getNestedValue, isInteractiveTarget } from "@/utils/table.utils";
 
 /**
  * A feature-rich data table with per-column filtering, sortable columns,
@@ -57,8 +61,27 @@ export default function ITTable<T extends Record<string, unknown>>({
   defaultView = "table",
   showVerticalBorder = true,
   verticalBorderClassname,
+  onRowClick,
+  layout = "auto",
+  density = "normal",
+  autoCardBreakpoint = 0,
+  virtualized = false,
+  virtualizedMaxHeight = 400,
+  rowHeight,
+  overscan = 5,
+  stickyHeader = false,
 }: ITTableProps<T>) {
   const [viewMode, setViewMode] = useState<"table" | "cards">(defaultView);
+  const { ref: rootRef, width: containerWidth } = useElementSize<HTMLDivElement>();
+
+  const isFixed = layout === "fixed";
+  const forcedCards =
+    autoCardBreakpoint > 0 && containerWidth > 0 && containerWidth < autoCardBreakpoint;
+  const effectiveView: "table" | "cards" = forcedCards ? "cards" : viewMode;
+  const hasColumnWidths = columns.some((col) => col.width != null);
+  const tableLayoutClass = isFixed
+    ? "w-full text-sm text-left text-secondary-600"
+    : "min-w-max w-full text-sm text-left text-secondary-600";
 
   const {
     currentPage,
@@ -159,6 +182,29 @@ export default function ITTable<T extends Record<string, unknown>>({
     currentPage * itemsPerPage
   );
 
+  const isTableVirtual = virtualized && effectiveView === "table";
+  const isStickyHeader = stickyHeader && isTableVirtual;
+  const resolvedRowHeight = rowHeight ?? getRowHeight(size, density);
+  const columnCount = columns.length;
+
+  const {
+    scrollRef,
+    startIndex,
+    endIndex,
+    topSpacerHeight,
+    bottomSpacerHeight,
+  } = useVirtualRows({
+    count: currentData.length,
+    rowHeight: resolvedRowHeight,
+    overscan,
+    enabled: isTableVirtual,
+    resetKey: `${currentPage}-${itemsPerPage}`,
+  });
+
+  const windowData = isTableVirtual
+    ? currentData.slice(startIndex, endIndex + 1)
+    : currentData;
+
   const renderFilterInput = (col: Column<T>) => {
     if (!col.filter) return null;
 
@@ -311,8 +357,21 @@ export default function ITTable<T extends Record<string, unknown>>({
     );
   };
 
+  const handleRowClick = (row: T) => (event: React.MouseEvent<HTMLElement>) => {
+    if (!onRowClick || isInteractiveTarget(event.target, event.currentTarget)) return;
+    onRowClick(row, event);
+  };
+
+  const handleRowKeyDown = (row: T) => (event: React.KeyboardEvent<HTMLElement>) => {
+    if (!onRowClick) return;
+    if (event.target !== event.currentTarget) return;
+    if (event.key !== "Enter" && event.key !== " ") return;
+    event.preventDefault();
+    onRowClick(row, event);
+  };
+
   return (
-    <div className={clsx("space-y-4 w-full", containerClassName)}>
+    <div ref={rootRef} className={clsx("space-y-4 w-full", containerClassName)}>
       <div className={tableContainer} style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
         {/* Header outside overflow */}
         {title && (
@@ -321,8 +380,9 @@ export default function ITTable<T extends Record<string, unknown>>({
             <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={`flex items-center gap-1.5 px-3 py-1.5 rounded-md text-xs font-semibold transition-all ${
-                  viewMode === "table"
+                  effectiveView === "table"
                     ? "bg-white dark:bg-slate-900 text-slate-900 dark:text-white shadow-sm border border-slate-200/50 dark:border-slate-700"
                     : "text-slate-500 dark:text-slate-400 hover:text-slate-700 dark:hover:text-slate-200"
                 }`}
@@ -333,7 +393,7 @@ export default function ITTable<T extends Record<string, unknown>>({
               <button
                 onClick={() => setViewMode("cards")}
                 className={`flex items-center gap-1.5 px-3 py-1.5 rounded-md text-xs font-semibold transition-all ${
-                  viewMode === "cards"
+                  effectiveView === "cards"
                     ? "bg-white dark:bg-slate-900 text-slate-900 dark:text-white shadow-sm border border-slate-200/50 dark:border-slate-700"
                     : "text-slate-500 dark:text-slate-400 hover:text-slate-700 dark:hover:text-slate-200"
                 }`}
@@ -350,8 +410,9 @@ export default function ITTable<T extends Record<string, unknown>>({
             <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={`flex items-center gap-1.5 px-3 py-1.5 rounded-md text-xs font-semibold transition-all ${
-                  viewMode === "table"
+                  effectiveView === "table"
                     ? "bg-white dark:bg-slate-900 text-slate-900 dark:text-white shadow-sm border border-slate-200/50 dark:border-slate-700"
                     : "text-slate-500 dark:text-slate-400 hover:text-slate-700 dark:hover:text-slate-200"
                 }`}
@@ -362,7 +423,7 @@ export default function ITTable<T extends Record<string, unknown>>({
               <button
                 onClick={() => setViewMode("cards")}
                 className={`flex items-center gap-1.5 px-3 py-1.5 rounded-md text-xs font-semibold transition-all ${
-                  viewMode === "cards"
+                  effectiveView === "cards"
                     ? "bg-white dark:bg-slate-900 text-slate-900 dark:text-white shadow-sm border border-slate-200/50 dark:border-slate-700"
                     : "text-slate-500 dark:text-slate-400 hover:text-slate-700 dark:hover:text-slate-200"
                 }`}
@@ -374,11 +435,18 @@ export default function ITTable<T extends Record<string, unknown>>({
           </div>
         )}
 
-        {viewMode === "cards" ? (
+        {effectiveView === "cards" ? (
           <div className="p-4 space-y-3 max-h-[400px] overflow-y-auto">
             {currentData.length > 0 ? (
               currentData.map((row, i) => (
-                <div key={i}>
+                <div
+                  key={i}
+                  className={clsx(onRowClick && tableCardClickable)}
+                  role={onRowClick ? "button" : undefined}
+                  tabIndex={onRowClick ? 0 : undefined}
+                  onClick={onRowClick ? handleRowClick(row) : undefined}
+                  onKeyDown={onRowClick ? handleRowKeyDown(row) : undefined}
+                >
                   {renderCard ? renderCard(row) : renderDefaultCard(row)}
                 </div>
               ))
@@ -390,25 +458,62 @@ export default function ITTable<T extends Record<string, unknown>>({
             )}
           </div>
         ) : (
-          <div className="overflow-x-auto">
+          <div
+            ref={isTableVirtual ? scrollRef : undefined}
+            className={isTableVirtual ? "overflow-x-auto overflow-y-auto" : "overflow-x-auto"}
+            style={isTableVirtual ? { maxHeight: virtualizedMaxHeight } : undefined}
+          >
             <table
               className={clsx(
-                "min-w-max w-full text-sm text-left text-secondary-600",
+                tableLayoutClass,
                 showVerticalBorder && "[&_th]:border-r [&_th:last-child]:border-r-0 [&_td]:border-r [&_td:last-child]:border-r-0",
                 showVerticalBorder && (verticalBorderClassname || "[&_th]:border-slate-100 dark:[&_th]:border-slate-700/30 [&_td]:border-slate-100 dark:[&_td]:border-slate-700/30"),
                 variantStyles[variant],
                 sizeStyles[size]
               )}
+              style={isFixed ? { tableLayout: "fixed" } : undefined}
+              aria-rowcount={isTableVirtual ? currentData.length + 1 : undefined}
             >
+              {hasColumnWidths && (
+                <colgroup>
+                  {columns.map((col) => (
+                    <col
+                      key={col.key}
+                      style={
+                        col.width != null
+                          ? { width: typeof col.width === "number" ? `${col.width}px` : col.width }
+                          : undefined
+                      }
+                    />
+                  ))}
+                </colgroup>
+              )}
               <thead>
-                <tr className={clsx(tableHeaderRow, "dark:text-slate-200")}>
+                <tr
+                  className={clsx(tableHeaderRow, "dark:text-slate-200")}
+                  aria-rowindex={isTableVirtual ? 1 : undefined}
+                >
                   {columns.map((col) => (
                     <th
                       key={col.key}
                       scope="col"
-                      className={tableHeaderCell(col.className)}
+                      className={clsx(
+                        tableHeaderCell(col.className, density),
+                        col.align && tableAlignClasses[col.align],
+                        isStickyHeader && "sticky top-0 z-10 bg-secondary-50"
+                      )}
+                      style={
+                        col.minWidth != null || isStickyHeader
+                          ? {
+                              ...(col.minWidth != null ? { minWidth: `${col.minWidth}px` } : {}),
+                              ...(isStickyHeader
+                                ? { backgroundColor: "var(--color-table-headerBg, #f8fafc)" }
+                                : {}),
+                            }
+                          : undefined
+                      }
                     >
-                      <div className="flex flex-col gap-3 min-w-[150px]">
+                      <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">
                             <ITText as="span" className="text-slate-900 dark:text-white font-bold">{col.label}</ITText>
                           {col.sortable && col.type !== "actions" && (
@@ -434,29 +539,65 @@ export default function ITTable<T extends Record<string, unknown>>({
               </thead>
               <tbody className={clsx(tableBody, "dark:divide-slate-700/30")}>
                 {currentData.length > 0 ? (
-                  currentData.map((row, rowIndex) => (
-                    <tr
-                      key={rowIndex}
-                      className={clsx(tableRow, variant === "striped" && "odd:bg-secondary-50/40 dark:odd:bg-slate-800/20")}
-                    >
-                      {columns.map((col) => (
-                        <td
-                          key={`${rowIndex}-${col.key}`}
-                          className={tableCell(col.className)}
-                        >
-                          {col.type === "actions" ? (
-                            <div className={tableActionsCell}>
-                              {renderCellContent(col, row) as React.ReactNode}
-                            </div>
-                          ) : (
-                            <div className={tableCellText}>
-                              {renderCellContent(col, row) as React.ReactNode}
-                            </div>
+                  <>
+                    {isTableVirtual && topSpacerHeight > 0 && (
+                      <tr aria-hidden="true" style={{ height: topSpacerHeight }}>
+                        <td colSpan={columnCount} style={{ padding: 0, border: 0 }} />
+                      </tr>
+                    )}
+                    {windowData.map((row, windowIndex) => {
+                      const absoluteIndex = isTableVirtual ? startIndex + windowIndex : windowIndex;
+                      return (
+                        <tr
+                          key={absoluteIndex}
+                          aria-rowindex={isTableVirtual ? absoluteIndex + 2 : undefined}
+                          className={clsx(
+                            tableRow,
+                            variant === "striped" && absoluteIndex % 2 === 0 && "bg-secondary-50/40 dark:bg-slate-800/20",
+                            onRowClick && tableRowClickable
                           )}
-                        </td>
-                      ))}
-                    </tr>
-                  ))
+                          tabIndex={onRowClick ? 0 : undefined}
+                          onClick={onRowClick ? handleRowClick(row) : undefined}
+                          onKeyDown={onRowClick ? handleRowKeyDown(row) : undefined}
+                        >
+                          {columns.map((col) => {
+                            const rawValue = getNestedValue(row, col.key);
+                            const truncateTitle =
+                              col.truncate &&
+                              (typeof rawValue === "string" || typeof rawValue === "number")
+                                ? String(rawValue)
+                                : undefined;
+                            return (
+                              <td
+                                key={`${absoluteIndex}-${col.key}`}
+                                className={clsx(
+                                  tableCell(col.className, density),
+                                  col.align && tableAlignClasses[col.align]
+                                )}
+                                style={col.minWidth != null ? { minWidth: `${col.minWidth}px` } : undefined}
+                                title={truncateTitle}
+                              >
+                                {col.type === "actions" ? (
+                                  <div className={tableActionsCell}>
+                                    {renderCellContent(col, row) as React.ReactNode}
+                                  </div>
+                                ) : (
+                                  <div className={clsx(tableCellText, col.truncate && "truncate")}>
+                                    {renderCellContent(col, row) as React.ReactNode}
+                                  </div>
+                                )}
+                              </td>
+                            );
+                          })}
+                        </tr>
+                      );
+                    })}
+                    {isTableVirtual && bottomSpacerHeight > 0 && (
+                      <tr aria-hidden="true" style={{ height: bottomSpacerHeight }}>
+                        <td colSpan={columnCount} style={{ padding: 0, border: 0 }} />
+                      </tr>
+                    )}
+                  </>
                 ) : (
                   <tr>
                     <td colSpan={columns.length} className="px-6 py-12 text-center">

package/src/components/organisms/data-table/ITDataTable.doc.mdx

@@ -11,7 +11,7 @@ Advanced server-side data table with automatic pagination, column sorting, and f
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `columns` | `Column<T>[]` | — | Column definitions with key, label, type, sortable, filter, render, and width. |
+| `columns` | `Column<T>[]` | — | Column definitions with key, label, type, sortable, filter, render, plus layout fields: `width` (`number` px or CSS `string`), `minWidth` (px), `align` (`"left" \| "center" \| "right"`), and `truncate` (ellipsis + native `title`). |
 | `fetchData` | `(params: ITDataTableFetchParams) => Promise<ITDataTableResponse<T>>` | — | Async callback triggered on pagination, filter, or sort change. Must return `{ data, total }`. |
 | `debounceMs` | `number` | `500` | Delay in ms before firing fetch after filter state changes. |
 | `externalFilters` | `Record<string, string \| number \| boolean \| Date>` | `{}` | Filters managed outside the table (e.g., date pickers) merged with internal column filters. |
@@ -20,11 +20,24 @@ Advanced server-side data table with automatic pagination, column sorting, and f
 | `reloadTrigger` | `number \| string \| boolean` | — | Changing this value forces a re-fetch. Use after mutations. |
 | `containerClassName` | `string` | — | CSS classes for the outer wrapper. |
 | `className` | `string` | — | CSS classes applied to the `<table>` element. |
-| `variant` | `"default" \| "striped" \| "bordered" \| "minimal"` | `"default"` | Visual style variant. |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Row density preset. |
+| `variant` | `"default" \| "striped" \| "bordered" \| "minimal"` | `"default"` | Visual style variant. `"minimal"` is accepted by the type but has no styles (renders like `"default"`). |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Font-size preset (does not change padding; use `density` for that). |
 | `itemsPerPageOptions` | `number[]` | `[5, 10, 20]` | Selectable page-size options. |
 | `defaultItemsPerPage` | `number` | `10` | Initial rows per page. |
 | `title` | `string \| ReactNode` | — | Heading displayed above the table. |
+| `renderCard` | `(row: T) => ReactNode` | — | Custom card renderer for the cards view. |
+| `defaultView` | `"table" \| "cards"` | `"table"` | Initial view mode. |
+| `showVerticalBorder` | `boolean` | `true` | Show vertical borders between columns. |
+| `verticalBorderClassname` | `string` | — | Custom class for the vertical borders. |
+| `onRowClick` | `(row: T, event: MouseEvent<HTMLElement> \| KeyboardEvent<HTMLElement>) => void` | — | Row/card activation. `MouseEvent` for pointer, `KeyboardEvent` for Enter/Space. Skipped when the interaction starts inside an interactive child. |
+| `layout` | `"auto" \| "fixed"` | `"auto"` | Table layout algorithm. `"fixed"` honors column `width` values and drops the `min-w-max` / `min-w-[150px]` floors so content no longer forces horizontal scrolling. |
+| `density` | `"compact" \| "normal" \| "comfortable"` | `"normal"` | Cell padding / row-height preset. Independent of `size`, which only controls font-size. |
+| `autoCardBreakpoint` | `number` | `0` | Container width (px) below which the table automatically falls back to the cards view. `0` disables the fallback. |
+| `virtualized` | `boolean` | `false` | Renders only the visible row window with spacer rows preserving scroll height. Table view only; cards view is never virtualized. |
+| `virtualizedMaxHeight` | `number` | `400` | Max height (px) of the virtualized scroll container. Only used when `virtualized` is true. |
+| `rowHeight` | `number` | `getRowHeight(size, density)` | Assumed uniform row height (px). Size-aware: `size="md"` baseline is 33 / 45 / 53 for compact / normal / comfortable; `size` shifts it by the font-size line box (sm 16px / md 20px / lg 28px). |
+| `overscan` | `number` | `5` | Extra rows rendered above and below the viewport to avoid blank gaps. |
+| `stickyHeader` | `boolean` | `false` | Keeps header cells sticky while the virtualized body scrolls. Only effective when `virtualized` is true. |
 
 ## Usage
 
@@ -42,6 +55,18 @@ import { ITDataTable } from '@axzydev/axzy_ui_system';
   fetchData={async (params) => api.fetchItems(params)}
   variant="bordered"
 />
+
+// No horizontal scroll: fixed layout + per-column widths + truncation
+<ITDataTable
+  columns={[
+    { key: 'name',  label: 'Name',  type: 'string', width: '30%', truncate: true },
+    { key: 'email', label: 'Email', type: 'string', width: 220,    truncate: true },
+    { key: 'role',  label: 'Role',  type: 'string', width: 140,    align: 'center' },
+  ]}
+  fetchData={async (params) => api.fetchItems(params)}
+  layout="fixed"
+  density="compact"
+/>
 ```
 
 ## Notes
@@ -51,6 +76,15 @@ import { ITDataTable } from '@axzydev/axzy_ui_system';
 - Debounce prevents excessive API calls while the user types in filter inputs.
 - A loading skeleton overlay covers the table body while fetching, keeping the header visible.
 - Empty state is shown automatically when no results match the current filters.
+- `onRowClick` fires in **both** the table and cards views. The event is a `MouseEvent` for pointer interaction and a `KeyboardEvent` for Enter/Space activation. It is not fired while `isLoading`, and interactions that start inside an interactive child (button, link, input, or `[data-row-click-ignore]`) are ignored.
+- `density` controls padding/row height (`compact` 33px / `normal` 45px / `comfortable` 53px at `size="md"`); `size` changes font-size and shifts the row height by the line box (sm 16px / md 20px / lg 28px).
+- **Anti horizontal scroll recipe:** `layout="fixed"` + a `width` on every column + `truncate` on long text + `density="compact"`. `width` accepts a `number` (px) or any CSS length string (`"20%"`, `"12rem"`). A `<colgroup>` is only emitted when at least one column defines a `width`.
+- With the default `layout="auto"`, `min-w-max` stays active so column widths can still reflow as different cell content enters the window during vertical scroll. Use `layout="fixed"` + column `width` for stable widths.
+- `autoCardBreakpoint` swaps to the cards view when the container (not the viewport) is narrower than the given px value; the Table toggle is disabled while forced, the Cards toggle stays enabled.
+- **Virtualization** applies to the **table view only** — the cards view is never virtualized. It only pays off with a large page size: raise `defaultItemsPerPage` and `itemsPerPageOptions` (defaults are `10` and `[5, 10, 20]`). Rows are assumed to have a uniform `rowHeight`; use `truncate` + `layout="fixed"` for predictable heights.
+- Scroll resets to the top on page or items-per-page change, but **not** on filter change (known limitation). `aria-rowcount` reflects the current page (+1), not the whole dataset, because pagination is independent.
+- `virtualizedMaxHeight`, `rowHeight`, `overscan`, and `stickyHeader` only take effect when `virtualized` is true. `stickyHeader` makes each `<th>` sticky using the `--color-table-headerBg` token (fallback `#f8fafc`).
+- `TableDensity` is exported from the package. `ITSearchTable` does **not** support `layout`, `density`, `autoCardBreakpoint`, `virtualized`, or per-column `width` — do not assume parity.
 
 ## Stories