@axzydev/axzy_ui_system 1.3.1 → 1.3.3

package/src/components/organisms/data-table/dataTable.props.ts

@@ -1,5 +1,6 @@
 import { ReactNode } from "react";
 import { Column } from "@/components/molecules/table/table.props";
+import { TableDensity } from "@/types/table.types";
 
 /** Parameters passed to `fetchData` every time pagination, filters, or sorting change. */
 export interface ITDataTableFetchParams {
@@ -91,4 +92,67 @@ export interface ITDataTableProps<T extends Record<string, unknown>> {
   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/organisms/data-table/dataTable.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, useEffect, useCallback, useRef } from "react";
 import { FaCheck, FaSpinner, FaTimes, FaTable, FaThLarge } from "react-icons/fa";
@@ -8,12 +10,14 @@ import ITInput from "@/components/atoms/input/input";
 import ITPagination from "@/components/molecules/pagination/pagination";
 import ITSelect from "@/components/molecules/select/select";
 import { Column } from "@/components/molecules/table/table.props";
-import { formatCurrencyMX } from "@/utils/table.utils";
+import { formatCurrencyMX, isInteractiveTarget } from "@/utils/table.utils";
 import { ITDataTableProps } from "./dataTable.props";
 import ITText from "@/components/atoms/text/text";
 import {
   tableActionsCell,
   tableBody,
+  tableCardClickable,
+  tableCardHover,
   tableCell,
   tableCellText,
   tableContainer,
@@ -21,6 +25,7 @@ import {
   tableHeaderCell,
   tableHeaderRow,
   tableRow,
+  tableRowClickable,
 } from "@/utils/styles";
 
 const getNestedValue = (obj: unknown, path: string) => {
@@ -69,12 +74,39 @@ export default function ITDataTable<T extends Record<string, unknown>>({
   defaultView,
   showVerticalBorder = true,
   verticalBorderClassname,
+  onRowClick,
+  layout = "auto",
+  density = "normal",
+  autoCardBreakpoint = 0,
+  virtualized = false,
+  virtualizedMaxHeight = 400,
+  rowHeight,
+  overscan = 5,
+  stickyHeader = false,
 }: ITDataTableProps<T>) {
   const [viewMode, setViewMode] = useState<"table" | "cards">(defaultView || "table");
+  const { ref: rootRef, width: containerWidth } = useElementSize<HTMLDivElement>();
   const [data, setData] = useState<T[]>([]);
   const [totalItems, setTotalItems] = useState(0);
   const [isLoading, setIsLoading] = useState(fetchOnMount);
 
+  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 transition-opacity duration-300"
+    : "min-w-max w-full text-sm text-left text-secondary-600 transition-opacity duration-300";
+
+  const isTableVirtual = virtualized && effectiveView === "table";
+  const isStickyHeader = stickyHeader && isTableVirtual;
+  const resolvedRowHeight = rowHeight ?? getRowHeight(size, density);
+  const columnCount = columns.length;
+  const scrollOuterClass = isTableVirtual
+    ? "relative min-h-[200px]"
+    : "overflow-x-auto relative min-h-[200px]";
+
   const {
     currentPage,
     itemsPerPage,
@@ -86,6 +118,22 @@ export default function ITDataTable<T extends Record<string, unknown>>({
     handleItemsPerPageChange,
   } = useTableState({ defaultItemsPerPage });
 
+  const {
+    scrollRef,
+    startIndex,
+    endIndex,
+    topSpacerHeight,
+    bottomSpacerHeight,
+  } = useVirtualRows({
+    count: data.length,
+    rowHeight: resolvedRowHeight,
+    overscan,
+    enabled: isTableVirtual,
+    resetKey: `${currentPage}-${itemsPerPage}`,
+  });
+
+  const windowData = isTableVirtual ? data.slice(startIndex, endIndex + 1) : data;
+
   const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hasFetchedRef = useRef(false);
   const fetchDataRef = useRef(fetchData);
@@ -270,13 +318,181 @@ export default function ITDataTable<T extends Record<string, unknown>>({
 
   const segCtrlClass = (mode: "table" | "cards") =>
     `flex items-center gap-1.5 px-3 py-1.5 rounded-md text-xs font-semibold transition-all ${
-      viewMode === mode
+      effectiveView === mode
         ? "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"
     }`;
 
+  const handleRowClick = (row: T) => (event: React.MouseEvent<HTMLElement>) => {
+    if (!onRowClick || isLoading || isInteractiveTarget(event.target, event.currentTarget)) return;
+    onRowClick(row, event);
+  };
+
+  const handleRowKeyDown = (row: T) => (event: React.KeyboardEvent<HTMLElement>) => {
+    if (!onRowClick || isLoading) return;
+    if (event.target !== event.currentTarget) return;
+    if (event.key !== "Enter" && event.key !== " ") return;
+    event.preventDefault();
+    onRowClick(row, event);
+  };
+
+  const tableEl = (
+    <table
+      className={clsx(
+        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"),
+        isLoading ? "opacity-50" : "opacity-100",
+        variantStyles[variant],
+        sizeStyles[size],
+        className
+      )}
+      style={isFixed ? { tableLayout: "fixed" } : undefined}
+      aria-rowcount={isTableVirtual ? data.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")}
+          aria-rowindex={isTableVirtual ? 1 : undefined}
+        >
+          {columns.map((col) => (
+            <th
+              key={col.key}
+              scope="col"
+              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={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" && (
+                    <button
+                      onClick={() => handleSort(col.key)}
+                      disabled={isLoading}
+                      className={`p-1 rounded-md transition-colors ${
+                        sortConfig?.key === col.key
+                          ? "bg-secondary-200 text-secondary-900"
+                          : "hover:bg-secondary-200 text-secondary-400 hover:text-secondary-700"
+                      } disabled:opacity-50`}
+                      title={`Ordenar por ${col.label}`}
+                    >
+                      <MdOutlineSwapVert className="w-4 h-4" aria-hidden="true" />
+                    </button>
+                  )}
+                </div>
+
+                <div className="w-full">{col.filter ? renderFilterInput(col) : null}</div>
+              </div>
+            </th>
+          ))}
+        </tr>
+      </thead>
+      <tbody className={clsx(tableBody, "dark:divide-slate-700/30")}>
+        {data.length > 0 ? (
+          <>
+            {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 && !isLoading && tableRowClickable
+                  )}
+                  tabIndex={onRowClick && !isLoading ? 0 : undefined}
+                  onClick={onRowClick && !isLoading ? handleRowClick(row) : undefined}
+                  onKeyDown={onRowClick && !isLoading ? 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">
+              {!isLoading && (
+                <div className={tableEmptyContent}>
+                  <ITText as="span" className="text-lg">No se encontraron resultados</ITText>
+                  <ITText as="span" className="text-sm mt-1">Intenta ajustar los filtros</ITText>
+                </div>
+              )}
+            </td>
+          </tr>
+        )}
+      </tbody>
+    </table>
+  );
+
   return (
-    <div className={clsx("space-y-4 w-full relative", containerClassName)}>
+    <div ref={rootRef} className={clsx("space-y-4 w-full relative", containerClassName)}>
       <div className={tableContainer} style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
         {title && (
           <div className="px-6 py-5 flex items-center justify-between" style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
@@ -288,7 +504,7 @@ export default function ITDataTable<T extends Record<string, unknown>>({
                 </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")} className={segCtrlClass("table")}>
+                <button onClick={() => setViewMode("table")} disabled={forcedCards} className={segCtrlClass("table")}>
                   <FaTable size={11} />
                   Table
                 </button>
@@ -304,7 +520,7 @@ export default function ITDataTable<T extends Record<string, unknown>>({
         {!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")} className={segCtrlClass("table")}>
+              <button onClick={() => setViewMode("table")} disabled={forcedCards} className={segCtrlClass("table")}>
                 <FaTable size={11} />
                 Table
               </button>
@@ -316,7 +532,7 @@ export default function ITDataTable<T extends Record<string, unknown>>({
           </div>
         )}
 
-        <div className="overflow-x-auto relative min-h-[200px]">
+        <div className={scrollOuterClass}>
           {isLoading && (
             <div className="absolute inset-0 z-20 flex items-center justify-center bg-white/40 backdrop-blur-[2px] transition-all duration-300">
              <div className="flex flex-col items-center gap-3 p-6 rounded-2xl shadow-xl border border-secondary-100 animate-in fade-in zoom-in duration-300" style={{ backgroundColor: 'var(--color-table-rowBg, #ffffff)' }}>
@@ -330,11 +546,18 @@ export default function ITDataTable<T extends Record<string, unknown>>({
             </div>
           )}
 
-          {viewMode === "cards" ? (
+          {effectiveView === "cards" ? (
             <div className="p-4 space-y-3 max-h-[400px] overflow-y-auto">
               {data.length > 0 ? (
                 data.map((row, i) => (
-                  <div key={i}>
+                  <div
+                    key={i}
+                    className={clsx(tableCardHover, onRowClick && !isLoading && tableCardClickable)}
+                    role={onRowClick && !isLoading ? "button" : undefined}
+                    tabIndex={onRowClick && !isLoading ? 0 : undefined}
+                    onClick={onRowClick && !isLoading ? handleRowClick(row) : undefined}
+                    onKeyDown={onRowClick && !isLoading ? handleRowKeyDown(row) : undefined}
+                  >
                     {renderCard ? renderCard(row) : renderDefaultCard(row)}
                   </div>
                 ))
@@ -347,80 +570,16 @@ export default function ITDataTable<T extends Record<string, unknown>>({
                 )
               )}
             </div>
-          ) : (
-            <table
-              className={clsx(
-                "min-w-max w-full text-sm text-left text-secondary-600 transition-opacity duration-300",
-                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"),
-                isLoading ? "opacity-50" : "opacity-100",
-                variantStyles[variant],
-                sizeStyles[size],
-                className
-              )}
+          ) : isTableVirtual ? (
+            <div
+              ref={scrollRef}
+              className="overflow-x-auto overflow-y-auto"
+              style={{ maxHeight: virtualizedMaxHeight }}
             >
-              <thead>
-                <tr className={clsx(tableHeaderRow, "dark:text-slate-200")}>
-                  {columns.map((col) => (
-                    <th key={col.key} scope="col" className={tableHeaderCell(col.className)}>
-                      <div className="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" && (
-                            <button
-                              onClick={() => handleSort(col.key)}
-                              disabled={isLoading}
-                              className={`p-1 rounded-md transition-colors ${
-                                sortConfig?.key === col.key
-                                  ? "bg-secondary-200 text-secondary-900"
-                                  : "hover:bg-secondary-200 text-secondary-400 hover:text-secondary-700"
-                              } disabled:opacity-50`}
-                              title={`Ordenar por ${col.label}`}
-                            >
-                              <MdOutlineSwapVert className="w-4 h-4" aria-hidden="true" />
-                            </button>
-                          )}
-                        </div>
-
-                        <div className="w-full">{col.filter ? renderFilterInput(col) : null}</div>
-                      </div>
-                    </th>
-                  ))}
-                </tr>
-              </thead>
-              <tbody className={clsx(tableBody, "dark:divide-slate-700/30")}>
-                {data.length > 0 ? (
-                  data.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>
-                          )}
-                        </td>
-                      ))}
-                    </tr>
-                  ))
-                ) : (
-                  <tr>
-                    <td colSpan={columns.length} className="px-6 py-12 text-center">
-                      {!isLoading && (
-                        <div className={tableEmptyContent}>
-                          <ITText as="span" className="text-lg">No se encontraron resultados</ITText>
-                          <ITText as="span" className="text-sm mt-1">Intenta ajustar los filtros</ITText>
-                        </div>
-                      )}
-                    </td>
-                  </tr>
-                )}
-              </tbody>
-            </table>
+              {tableEl}
+            </div>
+          ) : (
+            tableEl
           )}
         </div>
       </div>

package/src/components/organisms/sidebar/sidebar.doc.mdx

@@ -19,6 +19,7 @@ Vertical navigation sidebar with collapsible submenus, tooltips when collapsed,
 | `onSubItemClick` | `(subitem: ITNavigationSubItem) => void` | — | Callback when a sub-navigation item is clicked. |
 | `subitemConnector` | `"dot" \| "\|" \| "none"` | `"dot"` | Visual connector style for sub-items. |
 | `className` | `string` | — | Additional CSS classes on the sidebar `<aside>`. |
+| `header` | `ReactNode` | — | Optional content rendered above the navigation list (e.g. a wordmark). Hidden while the sidebar is collapsed, and independent of the collapse toggle button, which is always visible in both states. |
 
 ### ITNavigationItem
 
@@ -71,6 +72,9 @@ const items = [
 
 ## Notes
 
+- The button lives above the scrollable `<nav>` (never inside it), so it stays in the tab order and visible in both states; it is centered in the 88px rail when collapsed and right-aligned when expanded.
+- The toggle is a real `<button type="button">` with `aria-expanded`, `aria-controls` pointing at the `<nav>` it controls, and a state-dependent `aria-label`/`title` ("Expandir/Colapsar barra lateral"). Its chevron rotates 180° when the sidebar is expanded, so one icon signals both directions.
+- There is no collapse toggle button: the collapsed rail expands and collapses automatically on pointer hover.
 - Collapsed mode shrinks to icon-only; tooltips show labels on hover with glassmorphism style.
 - Submenus expand/collapse with smooth transitions when a parent item is clicked.
 - Active item highlighting uses a colored left-border accent and subtle background tint.
@@ -78,6 +82,7 @@ const items = [
 - `subitemConnector` styles the visual link between parent and sub-items: `dot` (default), `|` (vertical bar), or `none`.
 - `visibleOnMobile` forces sidebar visibility on smaller screens for responsive layouts.
 - Themed via CSS variables for consistent colors, shadows, and glassmorphism effects across light and dark modes.
+- Accessible by default: the `<nav>` is labelled and carries the `id` referenced by the toggle's `aria-controls`, the toggle exposes `aria-expanded` plus a visible `focus-visible` ring, group toggles expose `aria-expanded`/`aria-controls` and respond to Enter/Space, submenus are labelled `role="group"`, and the active sub-item carries `aria-current="page"`.
 
 ## Stories
 

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

@@ -46,5 +46,10 @@ export interface ITSidebarProps {
   subitemConnector?: 'dot' | '|' | 'none';
   /** Additional CSS classes on the sidebar `<aside>`. */
   className?: string;
+  /**
+   * Optional content rendered above the navigation list (e.g. a wordmark).
+   * Hidden while the sidebar is collapsed, so it only shows on hover.
+   */
+  header?: React.ReactNode;
 }
 

package/src/components/organisms/sidebar/sidebar.stories.tsx

@@ -71,7 +71,7 @@ export const Default: Story = {
   render: (args) => (
     <div className="h-screen bg-gray-50 flex">
       <ITSidebar {...args} />
-      <div className="flex-1 p-8 text-zinc-500 font-medium">Contenido principal simulado. Juega con el botón de colapsar para ver las transiciones suaves.</div>
+      <div className="flex-1 p-8 text-zinc-500 font-medium">Contenido principal simulado. Pasa el cursor por los íconos para ver el efecto de glassmorphism en los tooltips flotantes.</div>
     </div>
   ),
 };

package/src/components/organisms/sidebar/sidebar.tsx

@@ -5,7 +5,8 @@ import ITText from "@/components/atoms/text/text";
 
 /**
  * Vertical navigation sidebar with submenu expand/collapse, hover tooltips in collapsed mode,
- * and glassmorphism styling.
+ * and glassmorphism styling. The collapsed rail expands automatically on pointer hover — there
+ * is no toggle button; the hover is the only way to expand and collapse it.
  *
  * @example
  * ```tsx
@@ -20,8 +21,7 @@ import ITText from "@/components/atoms/text/text";
  *       ],
  *     },
  *   ]}
- *   isCollapsed={collapsed}
- *   onToggleCollapse={() => setCollapsed(!collapsed)}
+ *   isCollapsed
  * />
  * ```
  */
@@ -33,6 +33,7 @@ export default function ITSidebar({
   onItemClick,
   onSubItemClick,
   subitemConnector = 'dot',
+  header,
 }: ITSidebarProps) {
   const [expandedItems, setExpandedItems] = useState<Set<string>>(new Set());
   const [isHovering, setIsHovering] = useState(false);
@@ -133,12 +134,24 @@ export default function ITSidebar({
         backdropFilter: 'blur(12px)',
       }}
     >
+      {header && !isSidebarCollapsed && (
+        <div className="px-4 pt-4 pb-1 flex-shrink-0">{header}</div>
+      )}
+
       {/* Navigation Items */}
-      <nav className="flex-1 py-4 overflow-y-auto overflow-x-hidden custom-scrollbar px-4">
+      <nav aria-label="Componentes de la librería" className="flex-1 py-4 overflow-y-auto overflow-x-hidden custom-scrollbar px-4">
         <ul className="space-y-1">
-          {navigationItems.map((item) => (
+          {navigationItems.map((item) => {
+            const hasSubmenu = !!item.subitems && item.subitems.length > 0;
+            const submenuId = `it-sidebar-submenu-${item.id}`;
+            return (
             <li key={item.id} className="relative group/navitem">
               <div
+                role="button"
+                tabIndex={0}
+                aria-label={item.label}
+                aria-expanded={hasSubmenu ? expandedItems.has(item.id) : undefined}
+                aria-controls={hasSubmenu ? submenuId : undefined}
                 className={`flex items-center cursor-pointer 
                   transition-all duration-300 ease-[cubic-bezier(0.2,0,0,1)]
                   rounded-xl relative overflow-visible
@@ -156,6 +169,12 @@ export default function ITSidebar({
                   if (!item.isActive) e.currentTarget.style.backgroundColor = 'transparent';
                 }}
                 onClick={() => handleItemClick(item)}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter" || e.key === " ") {
+                    e.preventDefault();
+                    handleItemClick(item);
+                  }
+                }}
               >
                 {item.isActive && !isSidebarCollapsed && (
                   <div
@@ -264,7 +283,7 @@ export default function ITSidebar({
 
               {/* Submenu - smooth height/opacity when not collapsed */}
               {!isSidebarCollapsed && item.subitems && item.subitems.length > 0 && (
-                <div className={`overflow-hidden transition-all duration-400 ease-[cubic-bezier(0.2,0,0,1)] ${expandedItems.has(item.id) ? "max-h-[500px] opacity-100 mt-1" : "max-h-0 opacity-0"}`}>
+                <div id={submenuId} role="group" aria-label={item.label} className={`overflow-hidden transition-all duration-400 ease-[cubic-bezier(0.2,0,0,1)] ${expandedItems.has(item.id) ? "max-h-[500px] opacity-100 mt-1" : "max-h-0 opacity-0"}`}>
                   <ul
                     className="ml-4 flex flex-col gap-0 py-0.5"
                     style={{
@@ -276,6 +295,7 @@ export default function ITSidebar({
                     {item.subitems.map((subitem) => (
                       <li key={subitem.id} className="relative">
                         <button
+                          aria-current={subitem.isActive ? "page" : undefined}
                           onClick={() => {
                             if (subitem.action) subitem.action();
                             if (onSubItemClick) onSubItemClick(subitem);
@@ -329,7 +349,7 @@ export default function ITSidebar({
                 </div>
               )}
             </li>
-          ))}
+          );})}
         </ul>
       </nav>
     </aside>

package/src/components/organisms/topbar/topbar.doc.mdx

@@ -13,6 +13,8 @@ Sticky top navigation bar with glassmorphism effect, logo, breadcrumb-style nav
 |------|------|---------|-------------|
 | `logo` | `ReactNode` | — | Optional logo element (e.g. an `<img>` or SVG component). |
 | `logoText` | `string` | — | Text displayed next to the logo as the brand/title. |
+| `centerContent` | `ReactNode` | — | Content rendered in the centered region between the left (logo / nav) and right (user menu) areas — e.g. a global search box. Rendered only when provided, and only from the `lg` breakpoint up. |
+| `children` | `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 owns the placement; the caller only supplies the controls. The area renders only when this prop or `userMenu` is provided. |
 | `userMenu` | `object` | — | User dropdown configuration with name, email, avatar, and menu items. |
 | `userMenu.userName` | `string` | — | Display name shown in the trigger button and dropdown header. |
 | `userMenu.userEmail` | `string` | — | User email shown in the trigger button and dropdown header. |
@@ -53,6 +55,7 @@ import { FaChartBar, FaUserCog } from 'react-icons/fa';
 
 ## Notes
 
+- The `centerContent` slot renders in a centered `flex-1` (basis 0) region that absorbs all the slack, so the left and right areas stay flush with the row edges. It is `hidden` below `lg`, which leaves the below-`lg` layout exactly as before (logo + user menu).
 - The bar uses a **glassmorphism** backdrop blur effect (`backdrop-blur-xl`), giving it a translucent appearance over scrolling content.
 - Navigation items support **icons** and highlight the active item with the primary color and an underline indicator.
 - The **user menu** dropdown opens on avatar click and closes on outside click (via `useClickOutside` hook).