@axzydev/axzy_ui_system 1.3.4 → 1.3.5

package/package.json

@@ -4,7 +4,7 @@
   "packageManager": "pnpm@10.34.0",
   "private": false,
   "license": "MIT",
-  "version": "1.3.4",
+  "version": "1.3.5",
   "type": "module",
   "sideEffects": [
     "*.css"
@@ -38,7 +38,11 @@
     "bundle": "tsup src/index.ts && node scripts/build-css.mjs",
     "watch": "tsup src/index.ts --watch",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "ext:catalog": "node vscode-extension/scripts/generate-catalog.mjs",
+    "ext:build": "node vscode-extension/esbuild.mjs",
+    "ext:typecheck": "tsc --noEmit -p vscode-extension/tsconfig.json",
+    "ext:package": "node vscode-extension/esbuild.mjs && cd vscode-extension && npx --yes @vscode/vsce package --no-dependencies"
   },
   "dependencies": {
     "clsx": "^2.1.1",
@@ -81,6 +85,8 @@
     "vitest": "^4.0.18",
     "playwright": "^1.58.0",
     "@vitest/browser-playwright": "^4.0.18",
-    "@vitest/coverage-v8": "^4.0.18"
+    "@vitest/coverage-v8": "^4.0.18",
+    "@types/vscode": "1.85.0",
+    "esbuild": "^0.25.0"
   }
 }

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

@@ -11,7 +11,7 @@ Basic data table with column definitions, sorting, and configurable visual varia
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `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`). |
+| `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"`), `truncate` (ellipsis + native `title`), and `pinned` (`"left" \| "right"`). |
 | `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). |
@@ -42,6 +42,7 @@ Basic data table with column definitions, sorting, and configurable visual varia
 | `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. |
+| `pinned` | `"left" \| "right"` | `undefined` | Freezes the column to the given horizontal edge while the table scrolls sideways. `"left"` keeps it flush to the left edge, `"right"` to the right edge. Omit to leave the column unpinned (identical to the previous behavior). Offsets accumulate from each preceding pinned column's pixel `width` / `minWidth`, so give every pinned column of a side a pixel `width`. The pinned cell gets an opaque background (row background + row hover) and a 1px separator shadow on its frozen edge. One pinned column per side is the supported contract. |
 | `filter` | `true \| "catalog" \| "search" \| "date" \| "date-range"` | `false` | Filter control rendered in the header. `true` = text/number input (or boolean toggle when `type: "boolean"`); `"catalog"` = `ITSelect` fed by `catalogOptions.data`; `"search"` = `ITSearchSelect` typeahead fed by `catalogOptions.data` (optional `catalogOptions.onSearch` for server-side search); `"date"` / `"date-range"` = `ITDatePicker` single/range, bounded by `dateFilterOptions`. |
 
 ## Usage
@@ -85,6 +86,15 @@ const fixedColumns = [
 ];
 
 <ITTable columns={fixedColumns} data={data} layout="fixed" density="compact" />
+
+// Pinned columns: freeze the first column left and the last one right
+const pinnedColumns = [
+  { key: 'id',      label: 'ID',      type: 'number',  width: 72,  pinned: 'left' },
+  { key: 'name',    label: 'Name',    type: 'string',  width: 240, truncate: true },
+  { key: 'actions', label: 'Actions', type: 'actions', width: 104, pinned: 'right' },
+];
+
+<ITTable columns={pinnedColumns} data={data} layout="fixed" density="compact" />
 ```
 
 ## Notes
@@ -97,6 +107,7 @@ const fixedColumns = [
 - 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`.
+- **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]`; 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/molecules/table/table.props.ts

@@ -90,6 +90,23 @@ export interface Column<T = any> {
    * @default false
    */
   truncate?: boolean;
+  /**
+   * Pins this column to a horizontal edge so it stays visible while the table
+   * scrolls sideways.
+   *
+   * - `"left"` — freezes the column flush to the left edge.
+   * - `"right"` — freezes the column flush to the right edge.
+   *
+   * Omit to leave the column unpinned. When more than one column shares a side,
+   * sticky offsets accumulate from each preceding pinned column's `width` /
+   * `minWidth`; a column without a pixel width resolves to `0px`, so declare a
+   * pixel `width` on every pinned column of that side to avoid overlap. The
+   * pinned cell renders an opaque background (row background + row hover) and a
+   * 1px separator shadow on its frozen edge.
+   *
+   * @default undefined (column not pinned)
+   */
+  pinned?: "left" | "right";
 }
 
 export interface ITTableProps<T> {

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

@@ -272,6 +272,51 @@ export const FixedLayoutWithWidths: Story = {
   } as any,
 };
 
+// Pixel widths force the total past the 520px wrapper, so the ID (left) and
+// Actions (right) columns stay frozen while the middle scrolls sideways.
+const pinnedColumns: Column<User>[] = [
+  { key: "id", label: "ID", type: "number", width: 72, minWidth: 56, align: "center", pinned: "left" },
+  { key: "name", label: "Name", type: "string", width: 240, truncate: true },
+  { key: "email", label: "Email", type: "string", width: 280, truncate: true },
+  { key: "balance", label: "Balance", type: "number", width: 160, currencyMX: true },
+  { key: "lastLogin", label: "Last login", type: "string", width: 160, truncate: true },
+  {
+    key: "isActive",
+    label: "Status",
+    type: "boolean",
+    width: 104,
+    align: "center",
+  },
+  {
+    key: "actions",
+    label: "Actions",
+    type: "actions",
+    width: 104,
+    pinned: "right",
+    actions: () => (
+      <ITButton size="sm" variant="text" color="danger" ariaLabel="Delete">
+        <FaTrash />
+      </ITButton>
+    ),
+  },
+];
+
+export const PinnedColumns: Story = {
+  render: (args: any) => (
+    <div style={{ width: 520 }} className="rounded-lg border border-dashed border-slate-300">
+      <ITTable {...args} />
+    </div>
+  ),
+  args: {
+    columns: pinnedColumns,
+    data: mockData.slice(0, 6),
+    title: "Pinned left (ID) & right (Actions)",
+    layout: "fixed",
+    density: "compact",
+    defaultItemsPerPage: 6,
+  } as any,
+};
+
 export const AutoCardsNarrowContainer: Story = {
   render: (args: any) => (
     <div style={{ width: 420 }} className="rounded-lg border border-dashed border-slate-300">

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

@@ -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[]` | Plain sub-items or titled groups. |
 | `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
@@ -70,6 +82,28 @@ const items = [
 />
 ```
 
+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: () => {} },
+        ],
+      },
+    ],
+  },
+];
+```
+
 ## 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.
@@ -83,6 +117,10 @@ const items = [
 - `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"`.
+- `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();
+  },
+};