@axzydev/axzy_ui_system 1.3.3 → 1.3.5

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

@@ -1,5 +1,6 @@
 import React, { useState, useCallback, useMemo } from 'react';
 import { Meta, StoryObj } from '@storybook/react';
+import { startOfDay, endOfDay } from 'date-fns';
 import ITDataTable from './dataTable';
 import { ITDataTableFetchParams, ITDataTableResponse } from './dataTable.props';
 import ITCard from '@/components/molecules/card/card';
@@ -160,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',
@@ -243,6 +269,78 @@ export const WithRowClick: Story = {
   },
 };
 
+export const WithSearchAndDateFilters: Story = {
+  render: () => {
+    const searchDateFetch = useCallback(
+      async (params: ITDataTableFetchParams): Promise<ITDataTableResponse<any>> => {
+        await new Promise((r) => setTimeout(r, 400));
+        let filtered = [...MOCK_DATA];
+
+        Object.entries(params.filters).forEach(([key, value]) => {
+          if (value === undefined || value === '') return;
+
+          if (key === 'role') {
+            filtered = filtered.filter((item) => item.role === value);
+          } else if (key === 'createdAt') {
+            if (Array.isArray(value)) {
+              const [rangeStart, rangeEnd] = value as [Date | null, Date | null];
+              if (!rangeStart && !rangeEnd) return;
+              filtered = filtered.filter((item) => {
+                const time = new Date(item.createdAt).getTime();
+                if (rangeStart && time < startOfDay(rangeStart).getTime()) return false;
+                if (rangeEnd && time > endOfDay(rangeEnd).getTime()) return false;
+                return true;
+              });
+            } else if (value instanceof Date) {
+              filtered = filtered.filter(
+                (item) => new Date(item.createdAt).toDateString() === value.toDateString()
+              );
+            }
+          }
+        });
+
+        const start = (params.page - 1) * params.limit;
+        return { data: filtered.slice(start, start + params.limit), total: filtered.length };
+      },
+      []
+    );
+
+    const filterColumns = useMemo(
+      () => [
+        { key: 'username', label: 'Usuario', type: 'string' as const, filter: true, sortable: true },
+        {
+          key: 'role',
+          label: 'Rol (ITSearchSelect)',
+          type: 'string' as const,
+          filter: 'search' as const,
+          sortable: true,
+          catalogOptions: { data: ROLES.map((role) => ({ id: role, name: role })) },
+          render: (row: any) => <ITBadget label={row.role} />,
+        },
+        {
+          key: 'createdAt',
+          label: 'Alta (ITDatePicker range)',
+          type: 'date' as const,
+          filter: 'date-range' as const,
+          sortable: true,
+          dateFilterOptions: { maxDate: new Date() },
+          render: (row: any) => new Date(row.createdAt).toLocaleDateString('es-MX'),
+        },
+      ],
+      []
+    );
+
+    return (
+      <ITDataTable
+        title="Filtros: ITSearchSelect + ITDatePicker (rango)"
+        columns={filterColumns as any}
+        fetchData={searchDateFetch}
+        defaultItemsPerPage={8}
+      />
+    );
+  },
+};
+
 export const SkeletonLoading: Story = {
   args: {
     title: 'Cargando Datos...',

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

@@ -1,6 +1,6 @@
 import { ReactNode } from "react";
 import { Column } from "@/components/molecules/table/table.props";
-import { TableDensity } from "@/types/table.types";
+import { ColumnFilters, TableDensity } from "@/types/table.types";
 
 /** Parameters passed to `fetchData` every time pagination, filters, or sorting change. */
 export interface ITDataTableFetchParams {
@@ -8,8 +8,12 @@ export interface ITDataTableFetchParams {
   page: number;
   /** Number of rows requested per page. */
   limit: number;
-  /** Active per-column filter values (from `Column.filter`), keyed by column `key`. */
-  filters: Record<string, string | number | boolean | Date>;
+  /**
+   * Active per-column filter values (from `Column.filter`), keyed by column
+   * `key`. Scalars for text/number/boolean/date filters, a `Date` for
+   * `filter: "date"`, and a `[start, end]` tuple for `filter: "date-range"`.
+   */
+  filters: ColumnFilters;
   /** Active sort, present only when the user has clicked a sortable column header. */
   sort?: {
     /** Column `key` currently sorted by. */
@@ -50,7 +54,7 @@ export interface ITDataTableProps<T extends Record<string, unknown>> {
    * Filters managed outside of the ITDataTable (e.g. a date range picker).
    * These will be merged with the internal column filters before calling fetchData.
    */
-  externalFilters?: Record<string, string | number | boolean | Date>;
+  externalFilters?: ColumnFilters;
 
   /**
    * Custom element to display instead of the default spinner while `isLoading` is true.

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

@@ -9,8 +9,10 @@ import { MdOutlineSwapVert } from "react-icons/md";
 import ITInput from "@/components/atoms/input/input";
 import ITPagination from "@/components/molecules/pagination/pagination";
 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 {
@@ -103,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]";
@@ -253,6 +256,76 @@ export default function ITDataTable<T extends Record<string, unknown>>({
       );
     }
 
+    if (col.filter === "search" && col.catalogOptions) {
+      if (col.catalogOptions.loading) {
+        return <FaSpinner className="animate-spin" aria-label="Cargando opciones" title="Cargando opciones" />;
+      }
+      if (col.catalogOptions.error) {
+        return <ITText as="span" className="text-danger-500 text-xs">Error cargando</ITText>;
+      }
+      const searchValue = filters[col.key];
+      return (
+        <ITSearchSelect
+          name={`filter-${col.key}`}
+          options={col.catalogOptions.data.map((item) => ({
+            value: item.id,
+            label: item.name,
+          }))}
+          value={
+            typeof searchValue === "string" || typeof searchValue === "number"
+              ? searchValue
+              : ""
+          }
+          onChange={(value) => handleFilterChange(col.key, value === "" ? undefined : value)}
+          onSearch={col.catalogOptions.onSearch}
+          isLoading={col.catalogOptions.loading}
+          size="sm"
+          placeholder="Buscar..."
+          clearable
+          className="w-full"
+          onBlur={() => {}}
+          disabled={isLoading}
+        />
+      );
+    }
+
+    if (col.filter === "date") {
+      const dateValue = filters[col.key];
+      return (
+        <ITDatePicker
+          name={`filter-${col.key}`}
+          value={dateValue instanceof Date ? dateValue : undefined}
+          onChange={(e) => handleFilterChange(col.key, e.target.value as Date)}
+          minDate={col.dateFilterOptions?.minDate}
+          maxDate={col.dateFilterOptions?.maxDate}
+          size="sm"
+          placeholder="dd/mm/aaaa"
+          className="w-full"
+          disabled={isLoading}
+        />
+      );
+    }
+
+    if (col.filter === "date-range") {
+      const rangeValue = filters[col.key];
+      return (
+        <ITDatePicker
+          name={`filter-${col.key}`}
+          range
+          value={Array.isArray(rangeValue) ? rangeValue : undefined}
+          onChange={(e) =>
+            handleFilterChange(col.key, e.target.value as [Date | null, Date | null])
+          }
+          minDate={col.dateFilterOptions?.minDate}
+          maxDate={col.dateFilterOptions?.maxDate}
+          size="sm"
+          placeholder="dd/mm/aaaa - dd/mm/aaaa"
+          className="w-full"
+          disabled={isLoading}
+        />
+      );
+    }
+
     return (
       <ITInput
         name={`filter-${col.key}`}
@@ -369,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
               }
@@ -411,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")}>
@@ -444,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();
+  },
+};