@axzydev/axzy_ui_system 1.3.1 → 1.3.3

package/package.json

@@ -4,7 +4,7 @@
   "packageManager": "pnpm@10.34.0",
   "private": false,
   "license": "MIT",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "type": "module",
   "sideEffects": [
     "*.css"

package/src/App.tsx

@@ -7,7 +7,8 @@ import {
   FaSlidersH,
   FaTable,
 } from "react-icons/fa";
-import { ITLayout, ITThemeProvider } from "./index";
+import { ITLayout, ITThemeProvider, useDebouncedSearch } from "./index";
+import type { ITNavigationItem } from "./index";
 import "./index.css";
 
 // Import Showcases
@@ -69,187 +70,165 @@ import {
   ThemeProviderShowcase,
 } from "./showcases/FeedbackShowcases";
 
-type ViewMode = "home" | "ui-system";
+// Sandbox routing / landing (dev-only, never published)
+import {
+  SANDBOX_GROUPS,
+  firstItemOf,
+} from "./sandbox/navigation";
+import { useHashRoute } from "./sandbox/useHashRoute";
+import TopbarSearch from "./sandbox/TopbarSearch";
+import { LandingShowcase } from "./sandbox/LandingShowcase";
+import NotFoundShowcase from "./sandbox/NotFoundShowcase";
 
-// Group definitions for the sidebar (UI System showroom). Estático: se define
-// fuera del componente para que su referencia sea estable en los deps del memo.
-const categories = [
-  {
-    id: "general",
-    label: "General",
-    icon: <FaHome />,
-    subitems: [
-      { id: "getting-started", label: "Getting Started" },
-      { id: "sizes", label: "Medidas · sm / md / lg" },
-    ],
-  },
-  {
-    id: "struc",
-    label: "Estructura & Layout",
-    icon: <FaCreditCard />,
-    subitems: [
-      { id: "layout", label: "ITLayout & ITNavbar" },
-      { id: "stack", label: "ITStack" },
-      { id: "flex", label: "ITFlex" },
-      { id: "grid", label: "ITGrid" },
-      { id: "card", label: "ITCard" },
-      { id: "text", label: "ITText" },
-      { id: "accordion", label: "ITAccordion" },
-      { id: "pageheader", label: "ITPageHeader" },
-      { id: "page", label: "ITPage" },
-      { id: "screen-dashboard", label: "Dashboard Ejemplo" },
-      { id: "screen-form", label: "Formulario Ejemplo" },
-    ],
-  },
-  {
-    id: "forms",
-    label: "Formularios & Inputs",
-    icon: <FaKeyboard />,
-    subitems: [
-      { id: "button", label: "ITButton" },
-      { id: "input", label: "ITInput" },
-      { id: "select", label: "ITSelect" },
-      { id: "searchselect", label: "ITSearchSelect" },
-      { id: "multiselect", label: "ITMultiSelect" },
-      { id: "chipinput", label: "ITChipInput" },
-      { id: "field", label: "ITField" },
-      { id: "datepicker", label: "ITDatePicker" },
-      { id: "timepicker", label: "ITTimePicker" },
-      { id: "maskedinput", label: "ITMaskedInput" },
-      { id: "calendar", label: "ITCalendar" },
-      { id: "slidetoggle", label: "ITSlideToggle" },
-      { id: "dropfile", label: "ITDropfile" },
-      { id: "wysiwyg", label: "ITWysiwyg" },
-      { id: "formbuilder", label: "ITFormBuilder" },
-    ],
-  },
-  {
-    id: "data",
-    label: "Visualización Datos",
-    icon: <FaTable />,
-    subitems: [
-      { id: "table", label: "ITTable" },
-      { id: "datatable", label: "ITDataTable" },
-      { id: "badget", label: "ITBadget" },
-      { id: "chip", label: "ITChip" },
-      { id: "image", label: "ITImage" },
-    ],
-  },
-  {
-    id: "nav",
-    label: "Navegación & Control",
-    icon: <FaSlidersH />,
-    subitems: [
-      { id: "tabs", label: "ITTabs" },
-      { id: "stepper", label: "ITStepper" },
-      { id: "pagination", label: "ITPagination" },
-      { id: "triplefilter", label: "ITTripleFilter" },
-      { id: "dropdownmenu", label: "ITDropdownMenu" },
-    ],
-  },
-  {
-    id: "feed",
-    label: "Feedback & Sistema",
-    icon: <FaRegBell />,
-    subitems: [
-      { id: "dialog", label: "ITDialog" },
-      { id: "toast", label: "ITToast" },
-      { id: "loader", label: "ITLoader" },
-      { id: "themeprovider", label: "ITThemeProvider" },
-    ],
-  },
-];
+// Icons per sandbox group (icons stay here; navigation.ts is plain data).
+const GROUP_ICONS: Record<string, React.ReactNode> = {
+  general: <FaHome />,
+  struc: <FaCreditCard />,
+  forms: <FaKeyboard />,
+  data: <FaTable />,
+  nav: <FaSlidersH />,
+  feed: <FaRegBell />,
+};
 
 function App() {
-  const [view, setView] = useState<ViewMode>(() => {
-    const hash = window.location.hash.replace("#", "");
-    return hash.startsWith("ui-system") ? "ui-system" : "home";
-  });
-  const [showroomActive, setShowroomActive] = useState("screen-form");
-  const [searchTerm] = useState("");
-  const [subitemConnector] = useState<
-    "dot" | "|" | "none"
-  >("dot");
+  const { route, goToItem, goToLanding, goToPortfolio } = useHashRoute();
+  const [subitemConnector] = useState<"dot" | "|" | "none">("dot");
 
-  useEffect(() => {
-    const onHashChange = () => {
-      const hash = window.location.hash.replace("#", "");
-      setView(hash.startsWith("ui-system") ? "ui-system" : "home");
-    };
-    window.addEventListener("hashchange", onHashChange);
-    return () => window.removeEventListener("hashchange", onHashChange);
-  }, []);
+  // Debounced term drives filtering; `searchValue` is the live input value.
+  const [debouncedTerm, setDebouncedTerm] = useState("");
+  const {
+    searchTerm: searchValue,
+    handleSearchChange,
+    handleClearSearch,
+  } = useDebouncedSearch({ debounceMs: 250, onSearch: setDebouncedTerm });
 
-  // Filter sidebar navigation items based on search term
-  const filteredNavigationItems = useMemo(() => {
-    return categories
-      .map((cat) => {
-        if (!cat.subitems) {
-          const matches =
-            cat.label.toLowerCase().includes(searchTerm.toLowerCase()) ||
-            cat.id.toLowerCase().includes(searchTerm.toLowerCase());
-          if (matches) {
-            return {
-              ...cat,
-              isActive: showroomActive === cat.id,
-              action: () => setShowroomActive(cat.id),
-            };
-          }
-          return null;
-        }
+  // The active component page (group-only routes fall back to the first item).
+  const showroomActive =
+    route.view === "ui-system" && route.valid
+      ? route.item ?? (route.group ? firstItemOf(route.group) : null)
+      : null;
 
-        const matchingSubitems = cat.subitems.filter(
-          (sub) =>
-            sub.label.toLowerCase().includes(searchTerm.toLowerCase()) ||
-            sub.id.toLowerCase().includes(searchTerm.toLowerCase()),
-        );
+  // Redirect `#ui-system/<group>` to the group's first item (replace, no history spam).
+  useEffect(() => {
+    if (route.view === "ui-system" && route.valid && route.group && !route.item) {
+      const first = firstItemOf(route.group);
+      if (first) goToItem(route.group, first, { replace: true });
+    }
+  }, [route, goToItem]);
 
-        const mappedSubitems = matchingSubitems.map((sub) => ({
+  // Sidebar navigation: grouped when idle, flat filtered leaves when searching.
+  const navigationItems = useMemo<ITNavigationItem[]>(() => {
+    const term = debouncedTerm.trim().toLowerCase();
+
+    if (!term) {
+      return SANDBOX_GROUPS.map((group) => {
+        const subitems = group.subitems.map((sub) => ({
           id: sub.id,
           label: sub.label,
           isActive: showroomActive === sub.id,
-          action: () => setShowroomActive(sub.id),
+          action: () => goToItem(group.id, sub.id),
         }));
-
-        const isAnySubitemActive = mappedSubitems.some((sub) => sub.isActive);
-
         return {
-          ...cat,
-          isActive: isAnySubitemActive,
-          subitems: mappedSubitems,
+          id: group.id,
+          label: group.label,
+          icon: GROUP_ICONS[group.id],
+          isActive: subitems.some((sub) => sub.isActive),
+          subitems,
         };
-      })
-      .filter((cat): cat is Exclude<typeof cat, null> => {
-        if (!cat) return false;
-        if (cat.subitems) return cat.subitems.length > 0;
-        return true;
       });
-  }, [searchTerm, showroomActive]);
+    }
+
+    const flat: ITNavigationItem[] = [];
+    SANDBOX_GROUPS.forEach((group) => {
+      const groupMatches =
+        group.label.toLowerCase().includes(term) ||
+        group.id.toLowerCase().includes(term);
+      const groupBadge = group.label.split(" ")[0];
+
+      group.subitems
+        .filter(
+          (sub) =>
+            groupMatches ||
+            sub.label.toLowerCase().includes(term) ||
+            sub.id.toLowerCase().includes(term),
+        )
+        .forEach((sub) => {
+          flat.push({
+            id: sub.id,
+            label: sub.label,
+            icon: GROUP_ICONS[group.id],
+            badge: groupBadge,
+            isActive: showroomActive === sub.id,
+            action: () => goToItem(group.id, sub.id),
+          });
+        });
+    });
+    return flat;
+  }, [debouncedTerm, showroomActive, goToItem]);
 
+  // Sidebar is UNCONTROLLED: ITLayout's internal default is the 88px rail and the
+  // rail expands automatically on hover. No toggle button — the hover is the control.
+  // The component search lives in the topbar because a hover-only rail can't host it.
   const sidebarProps = {
-    navigationItems: filteredNavigationItems,
+    navigationItems,
     subitemConnector,
   };
 
   const topBarProps = {
     logoText: "AXZY UI System",
+    centerContent: (
+      <TopbarSearch
+        value={searchValue}
+        onChange={handleSearchChange}
+        onClear={handleClearSearch}
+        resultCount={navigationItems.length}
+        pending={searchValue.trim() !== debouncedTerm.trim()}
+      />
+    ),
+    // The topbar places `children` in its right area, right before the user menu.
+    children: (
+      <button
+        type="button"
+        aria-label="Notificaciones"
+        title="Notificaciones"
+        className="relative flex items-center justify-center p-2.5 rounded-xl transition-colors duration-200 hover:bg-[var(--it-topbar-user-hover,#f1f5f9)] focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-400"
+        style={{ color: "var(--it-topbar-icon, #94a3b8)" }}
+      >
+        <FaRegBell className="w-5 h-5" aria-hidden="true" />
+        <span className="absolute top-1.5 right-1.5 w-2 h-2 rounded-full bg-red-500 ring-2 ring-white" />
+      </button>
+    ),
+    navItems: [
+      {
+        id: "ui-system",
+        label: "UI System",
+        action: () => goToLanding(),
+      },
+      {
+        id: "portfolio",
+        label: "Portafolio",
+        action: () => goToPortfolio(),
+      },
+    ],
+    onNavItemClick: (id: string) => {
+      if (id === "ui-system") goToLanding();
+      else if (id === "portfolio") goToPortfolio();
+    },
     userMenu: {
       userName: "Alex Dev",
       userEmail: "alex@axzy.dev",
       menuItems: [
         {
           label: "Ir al Portafolio",
-          onClick: () => {
-            window.location.hash = "home";
-          },
+          onClick: () => goToPortfolio(),
         },
       ],
     },
   };
 
   // Render correct component based on active showroom navigation
-  const renderShowcase = () => {
-    switch (showroomActive) {
+  const renderShowcase = (itemId: string | null) => {
+    switch (itemId) {
       case "getting-started":
         return <GettingStartedShowcase />;
       // Structure
@@ -340,13 +319,19 @@ function App() {
       case "themeprovider":
         return <ThemeProviderShowcase />;
       default:
-        return <GettingStartedShowcase />;
+        return (
+          <NotFoundShowcase
+            attempted={route.raw}
+            onGoLanding={() => goToLanding()}
+            onGoPortfolio={goToPortfolio}
+          />
+        );
     }
   };
 
   return (
     <ITThemeProvider showFab={false} density={0.98} radius={10} shadow={2}>
-      {view === "home" ? (
+      {route.view === "home" ? (
         <div className="min-h-screen bg-slate-50 dark:bg-slate-950 py-10 px-4 sm:px-6 lg:px-8">
           <div className="max-w-6xl mx-auto">
             <HomeShowcase />
@@ -354,9 +339,20 @@ function App() {
         </div>
       ) : (
         <ITLayout sidebar={sidebarProps} topBar={topBarProps}>
-          <div className="max-w-7xl mx-auto">
-            {renderShowcase()}
-          </div>
+          {!route.valid ? (
+            <NotFoundShowcase
+              attempted={route.raw}
+              onGoLanding={() => goToLanding()}
+              onGoPortfolio={goToPortfolio}
+            />
+          ) : !route.group && !route.item ? (
+            <LandingShowcase
+              onOpenItem={goToItem}
+              onOpenPortfolio={goToPortfolio}
+            />
+          ) : (
+            renderShowcase(showroomActive)
+          )}
         </ITLayout>
       )}
     </ITThemeProvider>

package/src/components/molecules/table/table.doc.mdx

@@ -11,15 +11,37 @@ Basic data table with column definitions, sorting, and configurable visual varia
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `columns` | `{ key: string; label: string; render?: (value, row) => ReactNode; sortable?: boolean; width?: string }[]` | — | Column definitions |
-| `data` | `Record<string, any>[]` | — | Row data array |
-| `variant` | `'default' \| 'striped' \| 'bordered'` | `'default'` | Visual style variant |
-| `sortKey` | `string` | — | Current sort column key |
-| `sortDirection` | `'asc' \| 'desc'` | — | Current sort direction |
-| `onSort` | `(key: string, direction: 'asc' \| 'desc') => void` | — | Sort handler |
-| `onRowClick` | `(row: Record<string, any>) => void` | — | Row click handler |
-| `loading` | `boolean` | `false` | Show loading state |
-| `emptyMessage` | `string` | `'No data'` | Empty state message |
+| `columns` | `Column<T>[]` | — | Column definitions: key, label, type, sortable, filter, render, actions, plus layout fields `width` (`number` px or CSS `string`), `minWidth` (px), `align` (`"left" \| "center" \| "right"`), and `truncate` (ellipsis + native `title`). |
+| `data` | `T[]` | `[]` | Row data array. |
+| `variant` | `"default" \| "striped" \| "bordered"` | `"default"` | Visual style variant. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Font-size preset (does not change padding). |
+| `containerClassName` | `string` | — | CSS classes for the outermost container. |
+| `className` | `string` | — | Declared for API compatibility but **currently not applied** by ITTable. Use `containerClassName` for the outer wrapper. |
+| `itemsPerPageOptions` | `number[]` | `[5, 10, 20]` | Page-size options shown in the paginator. |
+| `defaultItemsPerPage` | `number` | `10` | Initial rows per page. |
+| `title` | `string` | — | Optional heading rendered 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. |
+
+### Column fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `width` | `number \| string` | — | Fixed column width. `number` = px, `string` = any CSS length (e.g. `"20%"`). A `<colgroup>` is only emitted when at least one column sets it. |
+| `minWidth` | `number` | — | Minimum column width in px, applied to header and body cells via inline style. |
+| `align` | `"left" \| "center" \| "right"` | `"left"` | Horizontal alignment of the column's header and cells. |
+| `truncate` | `boolean` | `false` | Truncates overflowing cell content with an ellipsis and exposes the raw string/number via the native `title` attribute. |
 
 ## Usage
 
@@ -27,28 +49,49 @@ Basic data table with column definitions, sorting, and configurable visual varia
 import { ITTable } from '@axzydev/axzy_ui_system';
 
 const columns = [
-  { key: 'name', label: 'Name', sortable: true },
-  { key: 'role', label: 'Role' },
-  { key: 'status', label: 'Status', render: (v) => <ITBadge>{v}</ITBadge> },
+  { key: 'name', label: 'Name', type: 'string', sortable: true, filter: true },
+  { key: 'role', label: 'Role', type: 'string', filter: 'catalog', catalogOptions: { data: roles } },
+  { key: 'status', label: 'Status', type: 'boolean', filter: true },
 ];
 const data = [
-  { name: 'Alice', role: 'Admin', status: 'Active' },
-  { name: 'Bob', role: 'Editor', status: 'Inactive' },
+  { name: 'Alice', role: 'ADMIN', status: true },
+  { name: 'Bob', role: 'EDITOR', status: false },
+];
+
+<ITTable columns={columns} data={data} title="Users" />
+<ITTable columns={columns} data={data} variant="striped" size="sm" defaultItemsPerPage={5} />
+<ITTable
+  columns={columns}
+  data={data}
+  defaultView="cards"
+  onRowClick={(row, event) => console.log(row, event.type)}
+/>
+
+// No horizontal scroll: fixed layout + per-column widths + truncation
+const fixedColumns = [
+  { 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' },
 ];
 
-<ITTable columns={columns} data={data} />
-<ITTable columns={columns} data={data} variant="striped" sortKey="name" sortDirection="asc" />
-<ITTable columns={columns} data={data} variant="bordered" onRowClick={(row) => console.log(row)} />
-<ITTable columns={columns} data={[]} emptyMessage="No records found" />
-<ITTable columns={columns} data={data} loading />
+<ITTable columns={fixedColumns} data={data} layout="fixed" density="compact" />
 ```
 
 ## Notes
 
 - `columns[].render` provides custom cell rendering via render function
 - `columns[].sortable` enables column header sort toggles
-- Sorting controlled via `sortKey`, `sortDirection`, and `onSort`
-- `onRowClick` fires with the row data on click
+- `onRowClick` fires in **both** the table and cards views. The event is a `MouseEvent` for pointer interaction and a `KeyboardEvent` for Enter/Space activation.
+- Clicks/keys that start inside an interactive child (`button`, `a`, `input`, `select`, `textarea`, `[role="button"]`, `[role="link"]`, `[data-row-click-ignore]`) do **not** trigger `onRowClick`.
+- When `onRowClick` is omitted no `cursor-pointer`, focus ring, `tabIndex`, or `role` is added.
+- `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.
 - Three visual variants: default (no borders), striped (alternating rows), bordered (full grid)
 
 ## Stories

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;
 }