@axzydev/axzy_ui_system 1.3.3 → 1.3.5

package/package.json

@@ -4,7 +4,7 @@
   "packageManager": "pnpm@10.34.0",
   "private": false,
   "license": "MIT",
-  "version": "1.3.3",
+  "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,8 @@ 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
 
@@ -67,6 +69,15 @@ const data = [
   onRowClick={(row, event) => console.log(row, event.type)}
 />
 
+// Filter modes: ITSearchSelect typeahead + ITDatePicker single / range
+const filterColumns = [
+  { key: 'role', label: 'Role', type: 'string', filter: 'search', catalogOptions: { data: roles } },
+  { key: 'lastLogin', label: 'Last login', type: 'date', filter: 'date', dateFilterOptions: { maxDate: new Date() } },
+  { key: 'hiredAt', label: 'Hired', type: 'date', filter: 'date-range', dateFilterOptions: { maxDate: new Date() } },
+];
+
+<ITTable columns={filterColumns} data={data} />
+
 // No horizontal scroll: fixed layout + per-column widths + truncation
 const fixedColumns = [
   { key: 'name',  label: 'Name',  type: 'string', width: '30%', truncate: true },
@@ -75,17 +86,28 @@ 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
 
 - `columns[].render` provides custom cell rendering via render function
 - `columns[].sortable` enables column header sort toggles
+- `columns[].filter` supports `true` (text/number input, or boolean toggle for `type: "boolean"`), `"catalog"` (`ITSelect`), `"search"` (`ITSearchSelect` typeahead; add `catalogOptions.onSearch` for server-side search), and `"date"` / `"date-range"` (`ITDatePicker`; bound with `dateFilterOptions: { minDate, maxDate }`). Filtering is client-side: `"date"` matches the whole day, `"date-range"` includes both ends (`startOfDay` / `endOfDay`).
 - `onRowClick` fires in **both** the table and cards views. The event is a `MouseEvent` for pointer interaction and a `KeyboardEvent` for Enter/Space activation.
 - Clicks/keys that start inside an interactive child (`button`, `a`, `input`, `select`, `textarea`, `[role="button"]`, `[role="link"]`, `[data-row-click-ignore]`) do **not** trigger `onRowClick`.
 - 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

@@ -3,6 +3,18 @@ import { TableDensity, TableSize, TableVariants } from "@/types/table.types";
 /** Data type of a table column, controls default rendering, filter UI, and sort comparison. */
 export type ColumnType = "string" | "date" | "number" | "boolean" | "actions" | "catalog";
 
+/**
+ * Per-column filter mode, set through `Column.filter`.
+ *
+ * - `true` — text/number input (or boolean toggle when `type: "boolean"`).
+ * - `"catalog"` — `ITSelect` dropdown populated from `catalogOptions`.
+ * - `"search"` — `ITSearchSelect` typeahead populated from `catalogOptions`
+ *   (respects `catalogOptions.onSearch` for server-side search).
+ * - `"date"` — `ITDatePicker` single-date filter.
+ * - `"date-range"` — `ITDatePicker` in range mode.
+ */
+export type ColumnFilterMode = boolean | "catalog" | "search" | "date" | "date-range";
+
 /** A single selectable entry for a `"catalog"`-type column's filter/value lookup. */
 export interface CatalogOption {
   /** Unique identifier matched against the row's field value. */
@@ -23,8 +35,8 @@ export interface Column<T = any> {
   currencyMX?: boolean;
   /** Custom action buttons/content rendered for a `"actions"`-type column. Receives the full row object. */
   actions?: (row: T) => React.ReactNode;
-  /** Enables per-column filtering. Pass `true` for a text/number/boolean filter matching `type`, or `"catalog"` to filter against `catalogOptions`. @default false */
-  filter?: boolean | "catalog";
+  /** Enables per-column filtering. Pass `true` for a text/number/boolean filter matching `type`, `"catalog"` for an `ITSelect` fed by `catalogOptions`, `"search"` for an `ITSearchSelect` typeahead, or `"date"` / `"date-range"` for an `ITDatePicker`. @default false */
+  filter?: ColumnFilterMode;
   /** Column data type. Drives default cell rendering, filter UI, and sort comparison. */
   type: ColumnType;
   /** Whether clicking the header sorts by this column. Ignored for `type: "actions"`. @default false */
@@ -45,6 +57,22 @@ export interface Column<T = any> {
     loading?: boolean;
     /** Shows an error state in the filter UI when the catalog failed to load. @default false */
     error?: boolean;
+    /**
+     * Server-side search handler for a `filter: "search"` column. When provided,
+     * `ITSearchSelect` delegates filtering to this callback (debounced) instead
+     * of filtering `data` locally; the parent is expected to update `data`.
+     */
+    onSearch?: (query: string) => void;
+  };
+  /**
+   * Date bounds applied by the `"date"` and `"date-range"` filters, forwarded to
+   * the underlying `ITDatePicker`. Ignored by every other filter mode.
+   */
+  dateFilterOptions?: {
+    /** Earliest selectable date. */
+    minDate?: Date;
+    /** Latest selectable date. */
+    maxDate?: Date;
   };
   /**
    * Fixed column width. A `number` is treated as pixels (`width: 120` → `120px`);
@@ -62,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">
@@ -325,3 +370,33 @@ export const VirtualizedLargeDataset: Story = {
     itemsPerPageOptions: [50, 100, 250],
   } as any,
 };
+
+// --- COLUMN FILTER MODES ---
+
+const filterModeColumns: Column<User>[] = [
+  { key: "name", label: "Name", type: "string", filter: true },
+  {
+    key: "roleId",
+    label: "Role (ITSearchSelect)",
+    type: "catalog",
+    filter: "search",
+    catalogOptions: { data: mockRoles },
+  },
+  {
+    key: "lastLogin",
+    label: "Last login (ITDatePicker range)",
+    type: "date",
+    filter: "date-range",
+    dateFilterOptions: { maxDate: new Date() },
+    render: (row) => new Date(row.lastLogin).toLocaleDateString("es-MX"),
+  },
+];
+
+export const WithSearchAndDateFilters: Story = {
+  args: {
+    columns: filterModeColumns,
+    data: generateMockData(25),
+    title: "Filtros: ITSearchSelect + ITDatePicker (rango)",
+    defaultItemsPerPage: 8,
+  } as any,
+};

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

@@ -15,6 +15,9 @@ 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 { isSameDay, startOfDay, endOfDay } from "date-fns";
 import { Column, ITTableProps } from "./table.props";
 import ITText from "@/components/atoms/text/text";
 import {
@@ -31,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,
@@ -146,21 +149,39 @@ export default function ITTable<T extends Record<string, unknown>>({
 
   const filteredData = sortedData.filter((row) =>
     columns.every((col) => {
-      if (
-        !col.filter ||
-        filters[col.key] === undefined ||
-        filters[col.key] === ""
-      )
+      const rawFilter = filters[col.key];
+      if (!col.filter || rawFilter === undefined || rawFilter === "") return true;
+      // A date range with both ends empty means "no filter".
+      if (Array.isArray(rawFilter) && rawFilter[0] == null && rawFilter[1] == null) {
         return true;
+      }
 
       const value = getNestedValue(row, col.key);
-      const filterValue = String(filters[col.key]).toLowerCase();
+
+      if (col.filter === "date" || col.filter === "date-range") {
+        const rowDate = value instanceof Date ? value : new Date(String(value));
+        if (isNaN(rowDate.getTime())) return false;
+        if (col.filter === "date") {
+          return isSameDay(rowDate, rawFilter as Date);
+        }
+        const [start, end] = rawFilter as [Date | null, Date | null];
+        if (start && rowDate.getTime() < startOfDay(start).getTime()) return false;
+        if (end && rowDate.getTime() > endOfDay(end).getTime()) return false;
+        return true;
+      }
+
+      if (col.filter === "search") {
+        // The search-select stores the exact option value (id).
+        return String(value) === String(rawFilter);
+      }
+
+      const filterValue = String(rawFilter).toLowerCase();
 
       switch (col.type) {
         case "number":
           return String(value).includes(filterValue);
         case "boolean":
-          return value === filters[col.key];
+          return value === rawFilter;
         case "catalog": {
           if (!col.catalogOptions) return true;
           const catalogItem = col.catalogOptions.data.find(
@@ -187,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,
@@ -283,6 +305,81 @@ export default function ITTable<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={() => { }}
+        />
+      );
+    }
+
+    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"
+        />
+      );
+    }
+
+    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"
+        />
+      );
+    }
+
     return (
       <ITInput
         name={`filter-${col.key}`}
@@ -494,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
                       }
@@ -535,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")}>
@@ -568,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,10 +11,10 @@ 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` | `Record<string, string \| number \| boolean \| Date>` | `{}` | Filters managed outside the table (e.g., date pickers) merged with internal column filters. |
+| `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. |
 | `loadingIndicator` | `ReactNode` | `<FaSpinner />` | Custom element shown while loading. |
 | `fetchOnMount` | `boolean` | `true` | Whether to fetch data on initial mount. |
 | `reloadTrigger` | `number \| string \| boolean` | — | Changing this value forces a re-fetch. Use after mutations. |
@@ -56,6 +56,15 @@ import { ITDataTable } from '@axzydev/axzy_ui_system';
   variant="bordered"
 />
 
+// Search + date filters (values arrive in params.filters)
+<ITDataTable
+  columns={[
+    { key: 'role', label: 'Role', type: 'string', filter: 'search', catalogOptions: { data: roles, onSearch: (q) => api.searchRoles(q) } },
+    { key: 'hiredAt', label: 'Hired', type: 'date', filter: 'date-range', dateFilterOptions: { maxDate: new Date() } },
+  ]}
+  fetchData={async (params) => api.fetchItems(params)}
+/>
+
 // No horizontal scroll: fixed layout + per-column widths + truncation
 <ITDataTable
   columns={[
@@ -67,11 +76,23 @@ 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
 
-- Column filters support `"catalog"` (dropdown), `true` (text input), and `boolean` (tri-state toggle).
+- Column filters support `true` (text/number input, or boolean tri-state toggle for `type: "boolean"`), `"catalog"` (`ITSelect`), `"search"` (`ITSearchSelect` typeahead; add `catalogOptions.onSearch` for server-side search), and `"date"` / `"date-range"` (`ITDatePicker`, bounded by `dateFilterOptions`). In `fetchData(params)`, `params.filters[key]` is a `Date` for `"date"`, a `[start, end]` tuple for `"date-range"`, and the scalar/id otherwise.
 - The `externalFilters` prop allows integrating external filter controls like date pickers without building filter UI into the table itself.
 - Debounce prevents excessive API calls while the user types in filter inputs.
 - A loading skeleton overlay covers the table body while fetching, keeping the header visible.
@@ -79,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.