@axzydev/axzy_ui_system 1.3.4 → 1.3.6

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

@@ -34,7 +34,7 @@ import {
   tableRow,
   tableRowClickable,
 } from "@/utils/styles";
-import { formatCurrencyMX, getNestedValue, isInteractiveTarget } from "@/utils/table.utils";
+import { formatCurrencyMX, getNestedValue, getPinnedColumnMeta, isInteractiveTarget } from "@/utils/table.utils";
 
 /**
  * A feature-rich data table with per-column filtering, sortable columns,
@@ -208,6 +208,7 @@ export default function ITTable<T extends Record<string, unknown>>({
   const isStickyHeader = stickyHeader && isTableVirtual;
   const resolvedRowHeight = rowHeight ?? getRowHeight(size, density);
   const columnCount = columns.length;
+  const pinnedMeta = React.useMemo(() => getPinnedColumnMeta(columns), [columns]);
 
   const {
     scrollRef,
@@ -590,22 +591,33 @@ export default function ITTable<T extends Record<string, unknown>>({
                   className={clsx(tableHeaderRow, "dark:text-slate-200")}
                   aria-rowindex={isTableVirtual ? 1 : undefined}
                 >
-                  {columns.map((col) => (
+                  {columns.map((col) => {
+                    const pin = pinnedMeta[col.key];
+                    const isPinned = pin != null;
+                    return (
                     <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"
+                        isPinned && "sticky",
+                        isStickyHeader && "sticky top-0 bg-secondary-50",
+                        isPinned ? "z-[15]" : isStickyHeader && "z-10",
+                        isPinned && (col.pinned === "left" ? "it-table-pinned-left" : "it-table-pinned-right")
                       )}
                       style={
-                        col.minWidth != null || isStickyHeader
+                        col.minWidth != null || isStickyHeader || isPinned
                           ? {
                               ...(col.minWidth != null ? { minWidth: `${col.minWidth}px` } : {}),
-                              ...(isStickyHeader
+                              ...(isStickyHeader || isPinned
                                 ? { backgroundColor: "var(--color-table-headerBg, #f8fafc)" }
                                 : {}),
+                              ...(isPinned
+                                ? pin.side === "left"
+                                  ? { left: pin.offset }
+                                  : { right: pin.offset }
+                                : {}),
                             }
                           : undefined
                       }
@@ -631,7 +643,8 @@ export default function ITTable<T extends Record<string, unknown>>({
                         </div>
                       </div>
                     </th>
-                  ))}
+                    );
+                  })}
                 </tr>
               </thead>
               <tbody className={clsx(tableBody, "dark:divide-slate-700/30")}>
@@ -664,14 +677,30 @@ export default function ITTable<T extends Record<string, unknown>>({
                               (typeof rawValue === "string" || typeof rawValue === "number")
                                 ? String(rawValue)
                                 : undefined;
+                            const pin = pinnedMeta[col.key];
+                            const isPinned = pin != null;
                             return (
                               <td
                                 key={`${absoluteIndex}-${col.key}`}
                                 className={clsx(
                                   tableCell(col.className, density),
-                                  col.align && tableAlignClasses[col.align]
+                                  col.align && tableAlignClasses[col.align],
+                                  isPinned && "sticky bg-[var(--color-table-rowBg,white)] group-hover:bg-[var(--color-table-rowHover,var(--color-secondary-50))]",
+                                  isPinned && (col.pinned === "left" ? "it-table-pinned-left" : "it-table-pinned-right"),
+                                  isPinned && "z-[1]"
                                 )}
-                                style={col.minWidth != null ? { minWidth: `${col.minWidth}px` } : undefined}
+                                style={
+                                  col.minWidth != null || isPinned
+                                    ? {
+                                        ...(col.minWidth != null ? { minWidth: `${col.minWidth}px` } : {}),
+                                        ...(isPinned
+                                          ? pin.side === "left"
+                                            ? { left: pin.offset }
+                                            : { right: pin.offset }
+                                          : {}),
+                                      }
+                                    : undefined
+                                }
                                 title={truncateTitle}
                               >
                                 {col.type === "actions" ? (

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, plus layout fields: `width` (`number` px or CSS `string`), `minWidth` (px), `align` (`"left" \| "center" \| "right"`), and `truncate` (ellipsis + native `title`). |
+| `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"`), `truncate` (ellipsis + native `title`), and `pinned` (`"left" \| "right"`). |
 | `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` | `ColumnFilters` | `{}` | Filters managed outside the table (e.g., date pickers) merged with internal column filters. Values may be scalars, a `Date`, or a `[start, end]` tuple. |
@@ -76,6 +76,18 @@ import { ITDataTable } from '@axzydev/axzy_ui_system';
   layout="fixed"
   density="compact"
 />
+
+// Pinned columns: freeze ID left and the last column right during horizontal scroll
+<ITDataTable
+  columns={[
+    { key: 'id',     label: 'ID',     type: 'number',  width: 72,  pinned: 'left' },
+    { key: 'name',   label: 'Name',   type: 'string',  width: 240, truncate: true },
+    { key: 'active', label: 'Active', type: 'boolean', width: 120, pinned: 'right' },
+  ]}
+  fetchData={async (params) => api.fetchItems(params)}
+  layout="fixed"
+  density="compact"
+/>
 ```
 
 ## Notes
@@ -88,6 +100,7 @@ import { ITDataTable } from '@axzydev/axzy_ui_system';
 - `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`.
+- **Pinned columns:** set `columns[].pinned: "left" | "right"` to freeze a column to that edge during horizontal scroll (`position: sticky`; the wrapper needs no `relative`). Omitting `pinned` renders exactly as before. Sticky offsets accumulate from each preceding pinned column's pixel `width` / `minWidth`; a non-px width contributes `minWidth ?? 0`, so give every pinned column of a side a pixel `width`. The pinned cell gets an opaque background (`--color-table-rowBg`, row hover `--color-table-rowHover`) and a 1px separator shadow on its frozen edge. Z-layering: pinned body cell `z-[1]` < sticky header `z-10` < pinned header `z-[15]` < the loading overlay `z-20`; it composes with `stickyHeader` and `virtualized`. One pinned column per side is the supported contract. Known limitation: with `variant="striped"` the opaque pinned background covers that column's stripe tint.
 - 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.

package/src/components/organisms/data-table/ITDataTable.stories.tsx

@@ -161,6 +161,31 @@ export const FixedLayoutCompact: Story = {
   },
 };
 
+// Pixel widths push the total past the 520px wrapper: the first column stays
+// frozen left and the last one frozen right while the middle scrolls sideways.
+const pinnedColumns = columns.map((col, i) => ({
+  ...col,
+  width: [72, 240, 280, 160, 120][i],
+  pinned: i === 0 ? 'left' : i === columns.length - 1 ? 'right' : undefined,
+  truncate: col.type === 'string' || col.type === 'catalog',
+})) as any;
+
+export const PinnedColumns: Story = {
+  render: (args) => (
+    <div style={{ width: 520 }}>
+      <ITDataTable {...args} />
+    </div>
+  ),
+  args: {
+    title: 'Pinned left & right columns',
+    columns: pinnedColumns,
+    fetchData: mockFetchItems,
+    defaultItemsPerPage: 10,
+    layout: 'fixed',
+    density: 'compact',
+  },
+};
+
 export const VirtualizedLargeDataset: Story = {
   args: {
     title: 'Virtualized · 100 rows',

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

@@ -12,7 +12,7 @@ import ITSelect from "@/components/molecules/select/select";
 import ITSearchSelect from "@/components/molecules/search-select/search-select";
 import ITDatePicker from "@/components/molecules/date-picker/datePicker";
 import { Column } from "@/components/molecules/table/table.props";
-import { formatCurrencyMX, isInteractiveTarget } from "@/utils/table.utils";
+import { formatCurrencyMX, getPinnedColumnMeta, isInteractiveTarget } from "@/utils/table.utils";
 import { ITDataTableProps } from "./dataTable.props";
 import ITText from "@/components/atoms/text/text";
 import {
@@ -105,6 +105,7 @@ export default function ITDataTable<T extends Record<string, unknown>>({
   const isStickyHeader = stickyHeader && isTableVirtual;
   const resolvedRowHeight = rowHeight ?? getRowHeight(size, density);
   const columnCount = columns.length;
+  const pinnedMeta = React.useMemo(() => getPinnedColumnMeta(columns), [columns]);
   const scrollOuterClass = isTableVirtual
     ? "relative min-h-[200px]"
     : "overflow-x-auto relative min-h-[200px]";
@@ -441,22 +442,33 @@ export default function ITDataTable<T extends Record<string, unknown>>({
           className={clsx(tableHeaderRow, "dark:text-slate-200")}
           aria-rowindex={isTableVirtual ? 1 : undefined}
         >
-          {columns.map((col) => (
+          {columns.map((col) => {
+            const pin = pinnedMeta[col.key];
+            const isPinned = pin != null;
+            return (
             <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"
+                isPinned && "sticky",
+                isStickyHeader && "sticky top-0 bg-secondary-50",
+                isPinned ? "z-[15]" : isStickyHeader && "z-10",
+                isPinned && (col.pinned === "left" ? "it-table-pinned-left" : "it-table-pinned-right")
               )}
               style={
-                col.minWidth != null || isStickyHeader
+                col.minWidth != null || isStickyHeader || isPinned
                   ? {
                       ...(col.minWidth != null ? { minWidth: `${col.minWidth}px` } : {}),
-                      ...(isStickyHeader
+                      ...(isStickyHeader || isPinned
                         ? { backgroundColor: "var(--color-table-headerBg, #f8fafc)" }
                         : {}),
+                      ...(isPinned
+                        ? pin.side === "left"
+                          ? { left: pin.offset }
+                          : { right: pin.offset }
+                        : {}),
                     }
                   : undefined
               }
@@ -483,7 +495,8 @@ export default function ITDataTable<T extends Record<string, unknown>>({
                 <div className="w-full">{col.filter ? renderFilterInput(col) : null}</div>
               </div>
             </th>
-          ))}
+            );
+          })}
         </tr>
       </thead>
       <tbody className={clsx(tableBody, "dark:divide-slate-700/30")}>
@@ -516,14 +529,30 @@ export default function ITDataTable<T extends Record<string, unknown>>({
                       (typeof rawValue === "string" || typeof rawValue === "number")
                         ? String(rawValue)
                         : undefined;
+                    const pin = pinnedMeta[col.key];
+                    const isPinned = pin != null;
                     return (
                       <td
                         key={`${absoluteIndex}-${col.key}`}
                         className={clsx(
                           tableCell(col.className, density),
-                          col.align && tableAlignClasses[col.align]
+                          col.align && tableAlignClasses[col.align],
+                          isPinned && "sticky bg-[var(--color-table-rowBg,white)] group-hover:bg-[var(--color-table-rowHover,var(--color-secondary-50))]",
+                          isPinned && (col.pinned === "left" ? "it-table-pinned-left" : "it-table-pinned-right"),
+                          isPinned && "z-[1]"
                         )}
-                        style={col.minWidth != null ? { minWidth: `${col.minWidth}px` } : undefined}
+                        style={
+                          col.minWidth != null || isPinned
+                            ? {
+                                ...(col.minWidth != null ? { minWidth: `${col.minWidth}px` } : {}),
+                                ...(isPinned
+                                  ? pin.side === "left"
+                                    ? { left: pin.offset }
+                                    : { right: pin.offset }
+                                  : {}),
+                              }
+                            : undefined
+                        }
                         title={truncateTitle}
                       >
                         {col.type === "actions" ? (

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

@@ -13,13 +13,13 @@ Vertical navigation sidebar with collapsible submenus, tooltips when collapsed,
 |------|------|---------|-------------|
 | `navigationItems` | `ITNavigationItem[]` | — | Navigation structure: top-level items with optional sub-items. |
 | `isCollapsed` | `boolean` | `false` | Whether the sidebar is collapsed to icon-only mode. |
-| `onToggleCollapse` | `() => void` | — | Callback when the user toggles collapse via the toggle button. |
-| `visibleOnMobile` | `boolean` | `false` | Force sidebar visible on mobile breakpoints. |
+| `onToggleCollapse` | `() => void` | — | Accepted for API compatibility but never invoked by `ITSidebar`: the component renders no collapse toggle button (the rail expands on pointer hover). `ITLayout` still passes it through. |
+| `visibleOnMobile` | `boolean` | `false` | When `true`, the sidebar is always fully expanded (the collapsed 88px rail is disabled) and visible at every breakpoint. |
 | `onItemClick` | `(item: ITNavigationItem) => void` | — | Callback when a top-level navigation item is clicked. |
 | `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. |
+| `header` | `ReactNode` | — | Optional content rendered above the navigation list (e.g. a wordmark). Hidden while the sidebar is collapsed, so it only appears when the hover-expanded rail is shown. |
 
 ### ITNavigationItem
 
@@ -30,7 +30,7 @@ Vertical navigation sidebar with collapsible submenus, tooltips when collapsed,
 | `icon` | `ReactNode` | Icon rendered left of the label. |
 | `action` | `() => void` | Click handler for top-level items without submenus. |
 | `isActive` | `boolean` | Whether this item is active/highlighted. |
-| `subitems` | `ITNavigationSubItem[]` | Nested sub-navigation items. |
+| `subitems` | `ITNavigationSubItemEntry[]` | Array of entries: plain sub-items or titled groups (`ITNavigationSubItemGroup`). |
 | `badge` | `string` | Badge text (e.g. notification count). |
 
 ### ITNavigationSubItem
@@ -42,6 +42,18 @@ Vertical navigation sidebar with collapsible submenus, tooltips when collapsed,
 | `action` | `() => void` | Click handler. |
 | `isActive` | `boolean` | Whether this sub-item is active/highlighted. |
 
+### ITNavigationSubItemGroup
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Unique identifier for the group (used for the React key and the heading id). |
+| `label` | `string` | Heading text rendered above the group's items. |
+| `items` | `ITNavigationSubItem[]` | Sub-items belonging to this group. Nesting a group inside a group is not supported. |
+
+### ITNavigationSubItemEntry
+
+A submenu entry is either a plain `ITNavigationSubItem` or a titled `ITNavigationSubItemGroup`; narrow it with `"items" in entry`.
+
 ## Usage
 
 ```tsx
@@ -65,24 +77,50 @@ const items = [
 <ITSidebar
   navigationItems={items}
   isCollapsed={false}
-  onToggleCollapse={toggleCollapse}
   subitemConnector="dot"
 />
 ```
 
+To group sub-items under a heading, replace a plain sub-item with a group object (`label` + `items`):
+
+```tsx
+const items = [
+  {
+    id: 'sales',
+    label: 'Sales',
+    subitems: [
+      { id: 'summary', label: 'Summary', action: () => {} },
+      {
+        id: 'gestion',
+        label: 'Management',
+        items: [
+          { id: 'orders', label: 'Orders', action: () => {} },
+          { id: 'invoices', label: 'Invoices', action: () => {} },
+        ],
+      },
+    ],
+  },
+];
+```
+
+Discriminate entries with `"items" in entry`. The heading style (uppercase, `0.68rem`, weight 700, `0.08em` tracking, `var(--it-sidebar-icon-color, var(--color-secondary-400))`) is applied by the component and cannot be overridden per group.
+
 ## 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.
+- There is no collapse toggle button: the collapsed 88px rail expands and collapses automatically on pointer hover (300 ms leave delay).
+- Collapsed mode shrinks to icon-only; a glassmorphism panel shows the item's sub-items on hover. For an item whose `subitems` contain groups, that panel **flattens** every group into one plain list and renders **no** group headings.
+- Submenus expand/collapse with smooth transitions when a parent item is clicked; the expanded submenu is animated with a `max-h` transition (cap `1000px`).
 - Active item highlighting uses a colored left-border accent and subtle background tint.
 - Badge support renders a notification-style counter on the item.
-- `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.
+- `subitemConnector` styles the visual link between parent and sub-items: `dot` (default), `|` (vertical bar), or `none`. Grouping does not change it: the `|` guide is a single `border-left` on the outer submenu `<ul>` only.
+- An active sub-item inside a group still auto-expands its parent, because auto-expand flattens groups the same way the collapsed flyout does.
+- `visibleOnMobile` forces the sidebar visible at every breakpoint and disables the collapsed rail, so it stays fully expanded.
 - 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"`.
+- `subitems` accepts plain sub-items or titled groups (`label` + `items`); the group heading is rendered as a plain `<span>` inside a non-focusable `<div>`, so it is non-interactive and stays out of the tab order.
+- Each group's inner `<ul>` keeps list semantics and is named by its heading through `aria-labelledby`, so it is reachable as a named list.
+- Groups are purely visual: they add no third nesting level (the sidebar supports exactly one level of nesting).
+- Consumers that introspect `navigationItems[].subitems` must narrow each entry first, e.g. `"items" in entry ? entry.items : [entry]`, because entries are typed as `ITNavigationSubItemEntry`.
 
 ## Stories
 

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

@@ -10,6 +10,28 @@ export interface ITNavigationSubItem {
   isActive?: boolean;
 }
 
+/**
+ * A titled group of sub-navigation items rendered under a parent menu.
+ * Groups only add a visual heading: they are never clickable and never open
+ * a third level (the sidebar supports exactly one level of nesting).
+ */
+export interface ITNavigationSubItemGroup {
+  /** Unique identifier for the group. Used for the React key and the heading id. */
+  id: string;
+  /** Heading text rendered above the group's items. */
+  label: string;
+  /** Sub-items belonging to this group. Nesting a group inside a group is not supported. */
+  items: ITNavigationSubItem[];
+}
+
+/**
+ * A submenu entry: either a plain {@link ITNavigationSubItem} or a titled
+ * {@link ITNavigationSubItemGroup}. Discriminate with `"items" in entry`.
+ */
+export type ITNavigationSubItemEntry =
+  | ITNavigationSubItem
+  | ITNavigationSubItemGroup;
+
 /** A top-level navigation item, optionally with sub-items. */
 export interface ITNavigationItem {
   /** Unique identifier. */
@@ -22,8 +44,12 @@ export interface ITNavigationItem {
   action?: () => void;
   /** Whether this item is currently active/highlighted. */
   isActive?: boolean;
-  /** Nested sub-navigation items (renders as expandable submenu). */
-  subitems?: ITNavigationSubItem[];
+  /**
+   * Nested sub-navigation entries (renders as an expandable submenu).
+   * Each entry is either a plain sub-item or a titled group of sub-items.
+   * The field `items` is reserved for {@link ITNavigationSubItemGroup}.
+   */
+  subitems?: ITNavigationSubItemEntry[];
   /** Badge text displayed on the item (e.g. notification count). */
   badge?: string;
 }

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

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import ITSidebar from '@/components/organisms/sidebar/sidebar';
-import { FaHome, FaUsers, FaCog, FaChartBar, FaShieldAlt } from 'react-icons/fa';
+import { FaHome, FaUsers, FaCog, FaChartBar, FaShieldAlt, FaShoppingCart } from 'react-icons/fa';
+import { expect, fn, userEvent, waitFor } from 'storybook/test';
 
 const meta: Meta<typeof ITSidebar> = {
   title: 'Components/Layout & Navigation/ITSidebar',
@@ -114,3 +115,62 @@ export const WithActiveSubmenu: Story = {
     </div>
   ),
 };
+
+const groupedSubItemActionSpy = fn();
+
+export const Grouped: Story = {
+  args: {
+    navigationItems: [
+      { id: 'dashboard', label: 'Dashboard', icon: <FaHome />, isActive: false },
+      {
+        id: 'ventas',
+        label: 'Ventas',
+        icon: <FaShoppingCart />,
+        subitems: [
+          { id: 'ventas-resumen', label: 'Resumen', action: fn() },
+          {
+            id: 'gestion',
+            label: 'Gestión',
+            items: [
+              { id: 'ordenes', label: 'Órdenes', action: groupedSubItemActionSpy },
+              { id: 'facturas', label: 'Facturas', action: fn() },
+            ],
+          },
+          {
+            id: 'catalogo',
+            label: 'Catálogo',
+            items: [
+              { id: 'productos', label: 'Productos', action: fn() },
+              { id: 'cotizaciones', label: 'Cotizaciones', action: fn() },
+            ],
+          },
+        ],
+      },
+      { id: 'settings', label: 'Configuración', icon: <FaCog />, action: fn() },
+    ],
+    isCollapsed: false,
+    visibleOnMobile: true,
+  },
+  render: (args) => (
+    <div className="h-screen bg-gray-50 flex">
+      <ITSidebar {...args} />
+      <div className="flex-1 p-8 text-zinc-500 font-medium">Los subítems de Ventas se agrupan bajo los títulos “Gestión” y “Catálogo”; los títulos no son interactivos.</div>
+    </div>
+  ),
+  play: async ({ canvas }) => {
+    await userEvent.click(canvas.getByRole('button', { name: 'Ventas' }));
+
+    const heading = canvas.getByText('Gestión');
+    // Wait out the 400ms expand transition before asserting visibility.
+    await waitFor(() => expect(heading).toBeVisible());
+
+    // The group <ul> is named by its heading via aria-labelledby.
+    await expect(canvas.getByRole('list', { name: 'Gestión' })).toBeInTheDocument();
+
+    // The heading is not focusable and is not inside anything with a tabindex.
+    await expect(heading.closest('[tabindex]')).toBeNull();
+
+    await userEvent.click(canvas.getByRole('button', { name: 'Órdenes' }));
+    await expect(groupedSubItemActionSpy).toHaveBeenCalled();
+  },
+};