@axzydev/axzy_ui_system 1.3.1 → 1.3.2

package/src/components/organisms/topbar/topbar.props.ts

@@ -1,3 +1,5 @@
+import type { ReactNode } from "react";
+
 export interface ITTopBarNavItem {
   /** Unique identifier for the navigation item. */
   id: string;
@@ -14,6 +16,20 @@ export interface ITTopBarProps {
   logo?: any;
   /** Text displayed next to the logo. */
   logoText?: string;
+  /**
+   * Content rendered in the centered region between the left (logo / nav) and
+   * right (user menu) areas — e.g. a global search box. The region is rendered
+   * only when this prop is provided, and only from the `lg` breakpoint up;
+   * below `lg` the row stays logo + user menu so nothing is squeezed.
+   */
+  centerContent?: ReactNode;
+  /**
+   * Actions rendered in the right area, immediately before the user menu —
+   * e.g. a notification bell, a help link, a theme switcher. The component
+   * decides the placement, so the caller only supplies the controls. The area
+   * is rendered only when this prop or `userMenu` is provided.
+   */
+  children?: ReactNode;
   /** User dropdown configuration including name, email, avatar, and menu items. */
   userMenu?: {
     /** Display name shown in the trigger button and dropdown header. */

package/src/components/organisms/topbar/topbar.tsx

@@ -41,11 +41,28 @@ import ITText from "@/components/atoms/text/text";
  *   showMobileMenuButton
  *   onToggleMobileMenu={() => setSidebarOpen((v) => !v)}
  * />
+ *
+ * @example
+ * // Topbar with a global search box in the centered region (lg and up)
+ * <ITTopBar
+ *   logoText="AXZY"
+ *   centerContent={<SearchBox value={term} onChange={setTerm} />}
+ *   userMenu={{ userName: "Jane Doe", userEmail: "jane@example.com", menuItems: [] }}
+ * />
+ *
+ * @example
+ * // Topbar with a notification bell passed as children, sitting right before
+ * // the user menu. The slot is placed by the component, not by the caller.
+ * <ITTopBar logoText="AXZY" userMenu={userMenu}>
+ *   <NotificationBell count={3} />
+ * </ITTopBar>
  */
 export default function ITTopBar({
   logo,
   logoText,
+  centerContent,
   userMenu,
+  children,
   showMobileMenuButton,
   onToggleMobileMenu,
   navItems,
@@ -131,110 +148,128 @@ export default function ITTopBar({
           )}
         </div>
 
-        {/* RIGHT AREA: User Menu */}
-        {userMenu && (
-          <div className="relative">
-            <button
-              type="button"
-              className="flex items-center gap-3 rounded-full pl-2 pr-4 py-1.5 transition-all duration-200 ease-[cubic-bezier(0.2,0,0,1)] border border-transparent hover:border-secondary-200"
-              style={{
-                backgroundColor: isUserMenuOpen ? "var(--it-topbar-user-hover, #f1f5f9)" : "transparent",
-              }}
-              onMouseEnter={(e) => {
-                if (!isUserMenuOpen) e.currentTarget.style.backgroundColor = "var(--it-topbar-user-hover, #f1f5f9)";
-              }}
-              onMouseLeave={(e) => {
-                if (!isUserMenuOpen) e.currentTarget.style.backgroundColor = "transparent";
-              }}
-              onClick={() => setIsUserMenuOpen(!isUserMenuOpen)}
-            >
-              {/* Avatar */}
+        {/* CENTER AREA: optional slot (e.g. global search) — lg and up only.
+            `flex-1` is basis 0, so it absorbs every pixel of slack and
+            `justify-between` has nothing left to distribute: the logo/nav and
+            the user menu stay flush with the row edges. */}
+        {centerContent && (
+          <div className="hidden lg:flex flex-1 min-w-0 items-center justify-center px-4">
+            <div className="w-full max-w-[420px]">{centerContent}</div>
+          </div>
+        )}
+
+        {/* RIGHT AREA: optional children (e.g. a notification bell) + the user menu.
+            Both share one flex group so `justify-between` on the row keeps the pair
+            flush to the right edge instead of pushing the bell into the middle of
+            the bar. */}
+        {(children || userMenu) && (
+          <div className="flex items-center gap-2">
+            {children}
+            {userMenu && (
               <div className="relative">
-                {userMenu.userImage ? (
-                  <img
-                    className="w-9 h-9 rounded-full object-cover ring-2 ring-white shadow-sm"
-                    src={userMenu.userImage}
-                    alt="Current user"
-                  />
-                ) : (
-                  <div className="w-9 h-9 rounded-full bg-slate-100 flex items-center justify-center ring-2 ring-white shadow-sm">
-                     <FaUserCircle className="w-6 h-6" style={{ color: "var(--it-topbar-icon, #94a3b8)" }} />
+                <button
+                  type="button"
+                  className="flex items-center gap-3 rounded-full pl-2 pr-4 py-1.5 transition-all duration-200 ease-[cubic-bezier(0.2,0,0,1)] border border-transparent hover:border-secondary-200"
+                  style={{
+                    backgroundColor: isUserMenuOpen ? "var(--it-topbar-user-hover, #f1f5f9)" : "transparent",
+                  }}
+                  onMouseEnter={(e) => {
+                    if (!isUserMenuOpen) e.currentTarget.style.backgroundColor = "var(--it-topbar-user-hover, #f1f5f9)";
+                  }}
+                  onMouseLeave={(e) => {
+                    if (!isUserMenuOpen) e.currentTarget.style.backgroundColor = "transparent";
+                  }}
+                  onClick={() => setIsUserMenuOpen(!isUserMenuOpen)}
+                >
+                  {/* Avatar */}
+                  <div className="relative">
+                    {userMenu.userImage ? (
+                      <img
+                        className="w-9 h-9 rounded-full object-cover ring-2 ring-white shadow-sm"
+                        src={userMenu.userImage}
+                        alt="Current user"
+                      />
+                    ) : (
+                      <div className="w-9 h-9 rounded-full bg-slate-100 flex items-center justify-center ring-2 ring-white shadow-sm">
+                         <FaUserCircle className="w-6 h-6" style={{ color: "var(--it-topbar-icon, #94a3b8)" }} />
+                      </div>
+                    )}
+                    {/* Active dot indicator */}
+                    <div className="absolute bottom-0 right-0 w-2.5 h-2.5 bg-green-500 border-2 border-white rounded-full"></div>
                   </div>
-                )}
-                {/* Active dot indicator */}
-                <div className="absolute bottom-0 right-0 w-2.5 h-2.5 bg-green-500 border-2 border-white rounded-full"></div>
-              </div>
 
-              {/* Name Details */}
-              <div className="hidden sm:flex flex-col text-left py-0.5">
-                <ITText as="span" 
-                  className="font-semibold text-[0.85rem] leading-tight"
-                  style={{ color: "var(--it-topbar-user-text, #0f172a)" }}
-                >
-                  {userMenu.userName}
-                </ITText>
-                <ITText as="span" 
-                  className="text-[0.7rem] font-medium"
-                  style={{ color: "var(--it-topbar-user-subtitle, #64748b)" }}
-                >
-                  {userMenu.userEmail}
-                </ITText>
-              </div>
-            </button>
+                  {/* Name Details */}
+                  <div className="hidden sm:flex flex-col text-left py-0.5">
+                    <ITText as="span" 
+                      className="font-semibold text-[0.85rem] leading-tight"
+                      style={{ color: "var(--it-topbar-user-text, #0f172a)" }}
+                    >
+                      {userMenu.userName}
+                    </ITText>
+                    <ITText as="span" 
+                      className="text-[0.7rem] font-medium"
+                      style={{ color: "var(--it-topbar-user-subtitle, #64748b)" }}
+                    >
+                      {userMenu.userEmail}
+                    </ITText>
+                  </div>
+                </button>
 
-            {/* Dropdown Menu */}
-            <div
-              ref={userMenuRef}
-              className={`
-                absolute right-0 mt-3 w-64 rounded-2xl shadow-[0_10px_40px_-10px_rgba(0,0,0,0.15)] z-[70] overflow-hidden transform origin-top-right transition-all duration-200 ease-[cubic-bezier(0.2,0,0,1)]
-                ${isUserMenuOpen ? "scale-100 opacity-100 translate-y-0" : "scale-95 opacity-0 -translate-y-2 pointer-events-none"}
-              `}
-              style={{ 
-                backgroundColor: "var(--it-topbar-user-dropdown-bg, #ffffff)",
-                border: "1px solid var(--it-topbar-user-dropdown-border, #f1f5f9)"
-              }}
-            >
-               {/* Dropdown Header */}
-              <div className="px-5 py-4 border-b" style={{ borderColor: "var(--it-topbar-user-dropdown-border, #f1f5f9)", backgroundColor: "var(--it-topbar-user-bg, #f8fafc)" }}>
-                <ITText as="span" className="block font-bold text-[0.9rem]" style={{ color: "var(--it-topbar-user-text, #0f172a)" }}>
-                  {userMenu.userName}
-                </ITText>
-                <ITText as="span" className="block text-xs font-medium truncate mt-0.5" style={{ color: "var(--it-topbar-user-subtitle, #64748b)" }}>
-                  {userMenu.userEmail}
-                </ITText>
-              </div>
+                {/* Dropdown Menu */}
+                <div
+                  ref={userMenuRef}
+                  className={`
+                    absolute right-0 mt-3 w-64 rounded-2xl shadow-[0_10px_40px_-10px_rgba(0,0,0,0.15)] z-[70] overflow-hidden transform origin-top-right transition-all duration-200 ease-[cubic-bezier(0.2,0,0,1)]
+                    ${isUserMenuOpen ? "scale-100 opacity-100 translate-y-0" : "scale-95 opacity-0 -translate-y-2 pointer-events-none"}
+                  `}
+                  style={{ 
+                    backgroundColor: "var(--it-topbar-user-dropdown-bg, #ffffff)",
+                    border: "1px solid var(--it-topbar-user-dropdown-border, #f1f5f9)"
+                  }}
+                >
+                   {/* Dropdown Header */}
+                  <div className="px-5 py-4 border-b" style={{ borderColor: "var(--it-topbar-user-dropdown-border, #f1f5f9)", backgroundColor: "var(--it-topbar-user-bg, #f8fafc)" }}>
+                    <ITText as="span" className="block font-bold text-[0.9rem]" style={{ color: "var(--it-topbar-user-text, #0f172a)" }}>
+                      {userMenu.userName}
+                    </ITText>
+                    <ITText as="span" className="block text-xs font-medium truncate mt-0.5" style={{ color: "var(--it-topbar-user-subtitle, #64748b)" }}>
+                      {userMenu.userEmail}
+                    </ITText>
+                  </div>
               
-              {/* Dropdown Items */}
-              <ul className="py-2">
-                {userMenu.menuItems.map((m, i) => {
-                  const isDestructive = m.label.toLowerCase().includes('salir') || m.label.toLowerCase().includes('cerrar') || m.label.toLowerCase().includes('logout');
+                  {/* Dropdown Items */}
+                  <ul className="py-2">
+                    {userMenu.menuItems.map((m, i) => {
+                      const isDestructive = m.label.toLowerCase().includes('salir') || m.label.toLowerCase().includes('cerrar') || m.label.toLowerCase().includes('logout');
                   
-                  return (
-                    <li key={i} className="px-2">
-                       {i === userMenu.menuItems.length - 1 && isDestructive && i > 0 && (
-                          <div className="h-px bg-slate-100 my-1 mx-2"></div>
-                       )}
-                      <button
-                        onClick={() => {
-                           m.onClick();
-                           setIsUserMenuOpen(false);
-                        }}
-                        className="block w-full text-left px-3 py-2.5 rounded-xl text-[0.875rem] font-medium transition-colors duration-150"
-                        style={{ color: isDestructive ? 'var(--color-danger-500)' : "var(--it-topbar-user-text, #334155)" }}
-                        onMouseEnter={(e) => {
-                          e.currentTarget.style.backgroundColor = isDestructive ? 'var(--color-danger-50)' : "var(--it-topbar-user-item-hover, #f8fafc)";
-                        }}
-                        onMouseLeave={(e) => {
-                          e.currentTarget.style.backgroundColor = "transparent";
-                        }}
-                      >
-                        <ITText as="span">{m.label}</ITText>
-                      </button>
-                    </li>
-                  )
-                })}
-              </ul>
-            </div>
+                      return (
+                        <li key={i} className="px-2">
+                           {i === userMenu.menuItems.length - 1 && isDestructive && i > 0 && (
+                              <div className="h-px bg-slate-100 my-1 mx-2"></div>
+                           )}
+                          <button
+                            onClick={() => {
+                               m.onClick();
+                               setIsUserMenuOpen(false);
+                            }}
+                            className="block w-full text-left px-3 py-2.5 rounded-xl text-[0.875rem] font-medium transition-colors duration-150"
+                            style={{ color: isDestructive ? 'var(--color-danger-500)' : "var(--it-topbar-user-text, #334155)" }}
+                            onMouseEnter={(e) => {
+                              e.currentTarget.style.backgroundColor = isDestructive ? 'var(--color-danger-50)' : "var(--it-topbar-user-item-hover, #f8fafc)";
+                            }}
+                            onMouseLeave={(e) => {
+                              e.currentTarget.style.backgroundColor = "transparent";
+                            }}
+                          >
+                            <ITText as="span">{m.label}</ITText>
+                          </button>
+                        </li>
+                      )
+                    })}
+                  </ul>
+                </div>
+              </div>
+            )}
           </div>
         )}
       </div>

package/src/components/templates/layout/layout.doc.mdx

@@ -40,7 +40,9 @@ import { ITLayout } from '@axzydev/axzy_ui_system';
 
 - The topbar spans the full viewport width at the top of the page.
 - The sidebar sits under the topbar on the left and floats over content when expanded via hover.
+- Reserved desktop width follows `sidebar.isCollapsed`: omitted/uncontrolled or `true` reserves the 88px rail (hover expands over content); controlled-expanded (`sidebar.isCollapsed={false}`) reserves the full 280px so it never overlays content.
 - Sidebar in collapsed state shows only icons; expanding reveals labels.
+- The collapsed rail expands automatically on hover. Keep global search in `topBar.centerContent` (always visible, `lg` and up) rather than `sidebar.header`, which is expanded-only and disappears in the 88px rail.
 - Themed entirely through CSS custom properties from ITThemeProvider.
 - Includes mobile responsive behavior with a hamburger-style toggle.
 

package/src/components/templates/layout/layout.tsx

@@ -58,7 +58,13 @@ export default function ITLayout({
       >
         {/* DESKTOP SIDEBAR */}
         <div className="hidden lg:block relative z-40 h-full">
-          <div className="w-[88px] h-full flex-shrink-0" />
+          {/* Reserves the sidebar's at-rest width. When the sidebar is collapsed
+              (default), this is the 88px rail and hover expands over the content.
+              When controlled-expanded (`sidebar.isCollapsed === false`), it
+              reserves the full 280px so the sidebar never overlays content. */}
+          <div
+            className={`${desktopCollapsed ? "w-[88px]" : "w-[280px]"} h-full flex-shrink-0`}
+          />
           <div className="absolute top-0 left-0 h-full">
             <ITSidebar
               {...sidebar}

package/src/components/templates/page/page.doc.mdx

@@ -29,7 +29,8 @@ A page template component that wraps an ITPageHeader with content area and built
 | `emptyAction` | `ReactNode` | `undefined` | Custom action element for the empty state. |
 | `children` | `ReactNode` | required | Content rendered when no special state (loading/error/empty) is active. |
 | `maxWidth` | `'2xl' \| '3xl' \| '4xl' \| '5xl' \| '6xl' \| '7xl'` | `'7xl'` | Maximum width of the page content container. |
-| `noPadding` | `boolean` | `false` | When true, removes default padding from the page wrapper. |
+| `noPadding` | `boolean` | `false` | When true, removes default padding from the page wrapper. Overrides `horizontalPadding`. |
+| `horizontalPadding` | `string` | `'px-4 sm:px-6 lg:px-8'` | Tailwind classes for the wrapper's horizontal padding. Use `'px-0'` for edge-to-edge content. Must be a literal — Tailwind scans source, so runtime-assembled values are not generated. |
 | `className` | `string` | `undefined` | Additional CSS classes for the page wrapper. |
 
 ## Usage
@@ -71,7 +72,12 @@ import { ITPage } from '@axzydev/axzy_ui_system';
 - The empty state renders a centered placeholder with optional title, description, and action.
 - All header props (`title`, `description`, `breadcrumbs`, `actions`, `backAction`, `icon`) are forwarded to ITPageHeader.
 - Content maximum width is controlled by Tailwind max-width classes via `maxWidth`.
-- `noPadding` is useful for full-bleed layouts like dashboards.
+- `noPadding` is useful for full-bleed layouts like dashboards. It removes both axes and wins over `horizontalPadding`.
+- `horizontalPadding` tunes only the horizontal gutter, so you can keep the vertical rhythm while going edge-to-edge:
+  ```tsx
+  <ITPage title="Reportes" horizontalPadding="px-0">...</ITPage>
+  ```
+  Because Tailwind scans your source files, write the value as a literal. A value built at runtime (`"px-" + n`) will silently produce no padding.
 
 ## Stories
 

package/src/components/templates/page/page.props.ts

@@ -41,6 +41,16 @@ export interface ITPageProps {
   children: ReactNode;
   /** Maximum width of the page content. Options: "2xl", "3xl", "4xl", "5xl", "6xl", "7xl". Default: "7xl". */
   maxWidth?: "2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "7xl";
-  /** Whether to remove default padding from the page wrapper. */
+  /** Whether to remove default padding from the page wrapper. Overrides `horizontalPadding`. */
   noPadding?: boolean;
+  /**
+   * Tailwind classes for the page wrapper's horizontal padding. Pass `"px-0"`
+   * for edge-to-edge content, or a responsive scale like `"px-2 sm:px-4"`.
+   *
+   * Must be written as a literal: Tailwind scans source files, so a value
+   * assembled at runtime will not be generated into the stylesheet.
+   *
+   * @default "px-4 sm:px-6 lg:px-8"
+   */
+  horizontalPadding?: string;
 }

package/src/components/templates/page/page.tsx

@@ -41,6 +41,14 @@ const renderHeader = (props: ITPageProps) => {
  *   <ITCard>Dashboard content</ITCard>
  * </ITPage>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Edge-to-edge content: no horizontal gutter, vertical padding kept.
+ * <ITPage title="Reportes" horizontalPadding="px-0">
+ *   <ITTable data={rows} columns={columns} />
+ * </ITPage>
+ * ```
  */
 export default function ITPage(props: ITPageProps) {
   const {
@@ -57,11 +65,13 @@ export default function ITPage(props: ITPageProps) {
     children,
     maxWidth = "7xl",
     noPadding = false,
+    horizontalPadding = "px-4 sm:px-6 lg:px-8",
   } = props;
 
   const wrapperClass = clsx(
     "mx-auto w-full",
-    !noPadding && "px-4 sm:px-6 lg:px-8 py-6",
+    !noPadding && horizontalPadding,
+    !noPadding && "py-6",
     `max-w-${maxWidth}`,
     "space-y-8",
     className

package/src/dev.css

@@ -1,2 +1,59 @@
 @import "tailwindcss";
-@import "./index.css";
+@import "./index.css";
+
+/* ──────────────────────────────────────────────
+   SANDBOX-ONLY ANIMATIONS (dev.css)
+   Never shipped: only src/main.tsx imports this file and `pnpm bundle`
+   builds from src/index.ts, so these never reach dist/index.css.
+   ────────────────────────────────────────────── */
+
+@keyframes it-landing-rise {
+  from {
+    opacity: 0;
+    transform: translateY(14px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.it-landing-rise {
+  animation: it-landing-rise 0.6s cubic-bezier(0.2, 0.8, 0.2, 1) both;
+}
+
+@keyframes it-landing-float {
+  0%,
+  100% {
+    transform: translateY(0);
+  }
+  50% {
+    transform: translateY(-18px);
+  }
+}
+
+.it-landing-float {
+  animation: it-landing-float 8s ease-in-out infinite;
+}
+
+.it-landing-grid {
+  background-image: radial-gradient(
+    circle at center,
+    currentColor 1px,
+    transparent 1px
+  );
+  background-size: 22px 22px;
+  -webkit-mask-image: radial-gradient(
+    ellipse at center,
+    black 40%,
+    transparent 78%
+  );
+  mask-image: radial-gradient(ellipse at center, black 40%, transparent 78%);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .it-landing-rise,
+  .it-landing-float {
+    animation: none;
+  }
+}

package/src/hooks/useElementSize.ts

@@ -0,0 +1,46 @@
+import { useLayoutEffect, useRef, useState, type RefObject } from "react";
+
+/**
+ * Observes an element's rendered size with a `ResizeObserver`.
+ *
+ * Used to make container-relative decisions (e.g. a table falling back to its
+ * cards view when the container itself is narrow, regardless of viewport
+ * width). The initial measurement runs in a layout effect so the first paint
+ * already has the real width and no incorrect layout flashes.
+ *
+ * @returns `ref` to attach to the element to measure, plus its current `width`
+ * and `height` in pixels (both `0` until the first measurement).
+ *
+ * @example
+ * const { ref, width } = useElementSize<HTMLDivElement>();
+ * return <div ref={ref}>{width < 640 ? <Cards /> : <Table />}</div>;
+ */
+export function useElementSize<T extends HTMLElement>(): {
+  ref: RefObject<T | null>;
+  width: number;
+  height: number;
+} {
+  const ref = useRef<T>(null);
+  const [size, setSize] = useState({ width: 0, height: 0 });
+
+  useLayoutEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+
+    const update = () => {
+      const rect = element.getBoundingClientRect();
+      setSize({ width: rect.width, height: rect.height });
+    };
+
+    update();
+
+    const observer = new ResizeObserver(update);
+    observer.observe(element);
+
+    return () => observer.disconnect();
+  }, []);
+
+  return { ref, width: size.width, height: size.height };
+}
+
+export default useElementSize;

package/src/hooks/useVirtualRows.ts

@@ -0,0 +1,123 @@
+import { useCallback, useLayoutEffect, useRef, useState, type RefObject } from "react";
+
+/** Options for {@link useVirtualRows}. */
+export interface UseVirtualRowsOptions {
+  /** Total number of rows in the dataset being windowed. */
+  count: number;
+  /** Assumed uniform row height in pixels. Values `<= 0` disable windowing. */
+  rowHeight: number;
+  /** Extra rows rendered above and below the viewport. @default 5 */
+  overscan?: number;
+  /** When `false`, no listeners are attached and the full range is returned. @default true */
+  enabled?: boolean;
+  /**
+   * When this value changes, `scrollTop` is reset to `0` both in state and on
+   * the scroll element. Pass a page/size signature so pagination resets scroll.
+   */
+  resetKey?: string | number;
+}
+
+/** Result of {@link useVirtualRows}. */
+export interface UseVirtualRowsResult {
+  /** Attach to the scrollable container that holds the rows. */
+  scrollRef: RefObject<HTMLDivElement | null>;
+  /** First row index (inclusive) that should be rendered. */
+  startIndex: number;
+  /** Last row index (inclusive) that should be rendered. */
+  endIndex: number;
+  /** Pixel height of the top spacer row. */
+  topSpacerHeight: number;
+  /** Pixel height of the bottom spacer row. */
+  bottomSpacerHeight: number;
+  /** Current scroll offset in pixels. */
+  scrollTop: number;
+  /** Imperatively resets scroll to the top. */
+  scrollToTop: () => void;
+}
+
+/**
+ * Zero-dependency row virtualizer for scroll containers. Tracks the scroll
+ * offset and viewport height of the element referenced by `scrollRef`, then
+ * computes the inclusive index window that must be rendered plus the spacer
+ * heights that preserve the full scroll height.
+ *
+ * @example
+ * const { scrollRef, startIndex, endIndex, topSpacerHeight, bottomSpacerHeight } =
+ *   useVirtualRows({ count: rows.length, rowHeight: 44, overscan: 5, enabled: virtualized, resetKey: page });
+ * // render rows.slice(startIndex, endIndex + 1) between spacer rows of the given heights
+ */
+export function useVirtualRows({
+  count,
+  rowHeight,
+  overscan = 5,
+  enabled = true,
+  resetKey,
+}: UseVirtualRowsOptions): UseVirtualRowsResult {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const [scrollTop, setScrollTop] = useState(0);
+  const [viewportHeight, setViewportHeight] = useState(0);
+
+  const scrollToTop = useCallback(() => {
+    setScrollTop(0);
+    const element = scrollRef.current;
+    if (element) element.scrollTop = 0;
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!enabled) return;
+    const element = scrollRef.current;
+    if (!element) return;
+
+    const onScroll = () => setScrollTop(element.scrollTop);
+    const measure = () => setViewportHeight(element.clientHeight);
+
+    measure();
+    setScrollTop(element.scrollTop);
+
+    element.addEventListener("scroll", onScroll, { passive: true });
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+
+    return () => {
+      element.removeEventListener("scroll", onScroll);
+      observer.disconnect();
+    };
+  }, [enabled]);
+
+  useLayoutEffect(() => {
+    if (!enabled) return;
+    const element = scrollRef.current;
+    if (element) element.scrollTop = 0;
+    setScrollTop(0);
+  }, [resetKey, enabled]);
+
+  const valid = enabled && rowHeight > 0 && count > 0;
+  const safeScrollTop = valid ? scrollTop : 0;
+
+  const startIndex = valid
+    ? Math.min(count - 1, Math.max(0, Math.floor(safeScrollTop / rowHeight) - overscan))
+    : 0;
+  const endIndex = valid
+    ? Math.min(
+        count - 1,
+        Math.ceil((safeScrollTop + viewportHeight) / rowHeight) + overscan
+      )
+    : Math.max(0, count - 1);
+
+  const topSpacerHeight = valid ? startIndex * rowHeight : 0;
+  const bottomSpacerHeight = valid
+    ? Math.max(0, (count - 1 - endIndex) * rowHeight)
+    : 0;
+
+  return {
+    scrollRef,
+    startIndex,
+    endIndex,
+    topSpacerHeight,
+    bottomSpacerHeight,
+    scrollTop: safeScrollTop,
+    scrollToTop,
+  };
+}
+
+export default useVirtualRows;

package/src/index.ts

@@ -115,6 +115,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 { TableDensity } from "./types/table.types";
 
 // UTILS
 import ITDropfile, { UploadStatus, FileTypeEnum } from "./components/organisms/dropfile/dropfile";
@@ -178,6 +179,7 @@ export {
     ITSegmentedControlProps, ITSidebarProps, ITSkeletonProps, ITSlideToggleProps, ITSliderProps,
     ITStackProps, ITStatCardProps, ITStepperProps,
     ITTableProps, ITTabsProps, ITTabItem, ITTextProps, ITTextareaProps,
+    TableDensity,
     ITTripleFilterProps, ITTripleFilterOption, ITThemeConfig, ITThemeProviderProps, ITThemePalette,
     ITTimePickerProps, ITToastProps,
     ITWysiwygProps,