@axzydev/axzy_ui_system 1.3.3 → 1.3.5

package/src/showcases/DataShowcases.tsx

@@ -1,4 +1,5 @@
 import React, { useState, useMemo, useCallback } from "react";
+import { startOfDay, endOfDay } from "date-fns";
 import {
   ITTable,
   ITDataTable,
@@ -47,6 +48,74 @@ const virtualUserColumns: any = [
   { key: "active", label: "Active", type: "boolean", width: "12%" },
 ];
 
+// Demo data for the new column filter modes: adds a `hiredAt` date so the
+// same table can showcase both single-date and date-range filters.
+const filterDemoData = TABLE_DATA.map((row, i) => ({
+  ...row,
+  hiredAt: new Date(2024, (i * 5) % 12, ((i * 7) % 27) + 1).toISOString(),
+}));
+
+// Columns exercising every new filter mode: ITSearchSelect (`"search"`) and
+// ITDatePicker in single (`"date"`) and range (`"date-range"`) modes.
+const filterDemoColumns: any = [
+  {
+    key: "name",
+    label: "Name",
+    type: "string",
+    sortable: true,
+    filter: true,
+    render: (row: Record<string, unknown>) => (
+      <span className="font-semibold text-slate-800 dark:text-white">{row.name as string}</span>
+    ),
+  },
+  {
+    key: "role",
+    label: "Role",
+    type: "string",
+    sortable: true,
+    filter: "search",
+    catalogOptions: {
+      data: [
+        { id: "Admin", name: "Admin" },
+        { id: "Editor", name: "Editor" },
+        { id: "Viewer", name: "Viewer" },
+      ],
+    },
+    render: (row: Record<string, unknown>) => (
+      <span className={`px-2 py-0.5 text-[10px] font-bold uppercase tracking-wider rounded-md ${roleColor(row.role as string)}`}>
+        {row.role as string}
+      </span>
+    ),
+  },
+  {
+    key: "lastLogin",
+    label: "Last login",
+    type: "date",
+    sortable: true,
+    filter: "date",
+    render: (row: Record<string, unknown>) =>
+      new Date(row.lastLogin as string).toLocaleDateString("es-MX", {
+        day: "2-digit",
+        month: "short",
+        year: "numeric",
+      }),
+  },
+  {
+    key: "hiredAt",
+    label: "Hired",
+    type: "date",
+    sortable: true,
+    filter: "date-range",
+    dateFilterOptions: { maxDate: new Date() },
+    render: (row: Record<string, unknown>) =>
+      new Date(row.hiredAt as string).toLocaleDateString("es-MX", {
+        day: "2-digit",
+        month: "short",
+        year: "numeric",
+      }),
+  },
+];
+
 const nameColumn = {
   key: "name",
   label: "Name",
@@ -179,6 +248,15 @@ export const TableShowcase = () => {
     truncate: col.key === "email" || col.key === "name",
   }));
 
+  // Pixel widths force horizontal overflow inside the 520px demo wrapper, so
+  // the first (Name) and last (Actions) columns can stay pinned while the
+  // middle ones scroll sideways.
+  const pinnedColumns: any = fixedColumns.map((col: any, i: number) => ({
+    ...col,
+    width: [200, 240, 180, 160, 180, 96][i],
+    pinned: i === 0 ? "left" : i === fixedColumns.length - 1 ? "right" : undefined,
+  }));
+
   // Single-line columns for virtualization: no avatar, no actions, no custom
   // render, so every row is a deterministic one-line box.
   const virtualColumns: any = [
@@ -275,7 +353,11 @@ export const TableShowcase = () => {
           '<ITTable columns={columns} data={data} title="Users" />',
           '<ITTable columns={columns} data={data} defaultView="cards" onRowClick={(row) => open(row)} />',
           '<ITTable columns={fixedColumns} data={data} layout="fixed" density="compact" />',
+          '// Columna fija: pinned "left" | "right" (los offsets acumulan width en px)\n{ key: "name", label: "Name", type: "string", width: 200, pinned: "left" },\n{ key: "actions", label: "", type: "actions", width: 96, pinned: "right" }',
           '<ITTable columns={cols} data={rows} virtualized stickyHeader layout="fixed" density="compact" defaultItemsPerPage={300} itemsPerPageOptions={[50, 100, 300]} />',
+          '// ITSearchSelect typeahead (server-side search opcional vía catalogOptions.onSearch)\n{ key: "role", label: "Role", type: "string", filter: "search", catalogOptions: { data: roles } }',
+          '// ITDatePicker fecha única\n{ key: "lastLogin", label: "Last login", type: "date", filter: "date", dateFilterOptions: { maxDate: new Date() } }',
+          '// ITDatePicker rango\n{ key: "hiredAt", label: "Hired", type: "date", filter: "date-range", dateFilterOptions: { maxDate: new Date() } }',
         ],
         props: [
           { name: "columns", type: "Column<T>[]", description: "Definiciones de columna: key, label, type, sortable, filter, render, actions." },
@@ -305,10 +387,12 @@ export const TableShowcase = () => {
           "onRowClick funciona en ambas vistas (tabla y cards).",
           "Cuando se omite no se agrega cursor-pointer, foco, tabIndex ni role.",
           "Column acepta width (number=px | string CSS), minWidth (px), align (left/center/right) y truncate (ellipsis + title nativo).",
+          "Columna fija: Column acepta pinned: \"left\" | \"right\" (opt-in; omitir = sin cambios). Los offsets sticky acumulan el width en px de cada columna pinneada previa del mismo lado; una columna sin width en px aporta 0px, así que declara width en px en todas las columnas pinneadas de un lado. La celda pinneada pinta fondo opaco (rowBg + rowHover) y un separador de 1px en el borde congelado. Una columna pinneada por lado es el contrato probado. Limitación: con variant=\"striped\" el fondo opaco tapa el tinte de la franja de esa columna.",
           "Anti scroll horizontal: layout=\"fixed\" + width por columna + truncate + density.",
           "Virtualización: solo vista tabla; rinde con page size grande; filas de alto uniforme; el scroll no se reinicia al cambiar filtros.",
           "Virtualización exige alto de fila uniforme. El default es size-aware (getRowHeight(size, density)): con size=\"md\" el baseline es compact 33 / normal 45 / comfortable 53 (padding de celda + line box text-sm de 20px + 1px del divide-y); size lo desplaza por el line box (sm 16 / md 20 / lg 28 px, es decir −4 / 0 / +8 px). Una celda de dos líneas (avatar + texto) mide ~50px real, distinto de ese alto asumido, así que los spacers se desalinean: usar celdas de una sola línea o pasar un rowHeight explícito.",
           "ITSearchTable no soporta layout/density/autoCardBreakpoint/virtualized/width — no asumir paridad.",
+          "Nuevos modos de filtro por columna: filter: \"search\" renderiza ITSearchSelect (usa catalogOptions.data; opcional catalogOptions.onSearch para búsqueda en servidor), y filter: \"date\" / \"date-range\" renderizan ITDatePicker (bounds vía dateFilterOptions). El rango se guarda como [start, end] y se considera vacío cuando ambos extremos son null.",
         ],
       }}
       gallery={
@@ -410,6 +494,23 @@ export const TableShowcase = () => {
             </div>
           </div>
 
+          <div>
+            <h4 className="text-sm font-bold text-slate-700 dark:text-slate-200 mb-3">Pinned columns — left (Name) &amp; right (Actions)</h4>
+            <div className="border border-slate-200 dark:border-slate-700 rounded-xl overflow-hidden" style={{ maxWidth: 520 }}>
+              <ITTable
+                columns={pinnedColumns}
+                data={TABLE_DATA}
+                title="Pinned columns"
+                layout="fixed"
+                density="compact"
+                defaultItemsPerPage={5}
+              />
+            </div>
+            <p className="mt-2 text-xs text-slate-500 dark:text-slate-400">
+              Scroll the table sideways: <code>pinned: "left"</code> freezes the Name column, <code>pinned: "right"</code> freezes the Actions column. Offsets accumulate from each preceding pinned column's pixel <code>width</code>.
+            </p>
+          </div>
+
           <div>
             <h4 className="text-sm font-bold text-slate-700 dark:text-slate-200 mb-3">Auto cards fallback (&lt; 640px container)</h4>
             <div className="border border-slate-200 dark:border-slate-700 rounded-xl overflow-hidden" style={{ maxWidth: 420 }}>
@@ -440,6 +541,22 @@ export const TableShowcase = () => {
               />
             </div>
           </div>
+
+          <div>
+            <h4 className="text-sm font-bold text-slate-700 dark:text-slate-200 mb-3">Column filters: ITSearchSelect + ITDatePicker (single &amp; range)</h4>
+            <div className="border border-slate-200 dark:border-slate-700 rounded-xl overflow-hidden">
+              <ITTable
+                columns={filterDemoColumns}
+                data={filterDemoData}
+                title="Filter demo"
+                size="sm"
+                defaultItemsPerPage={8}
+              />
+            </div>
+            <p className="mt-2 text-xs text-slate-500 dark:text-slate-400">
+              Role uses <code>filter: "search"</code> (ITSearchSelect). Last login uses <code>filter: "date"</code> and Hired uses <code>filter: "date-range"</code> (ITDatePicker), with <code>dateFilterOptions</code> bounds.
+            </p>
+          </div>
         </div>
       }
     />
@@ -475,8 +592,15 @@ export const DataTableShowcase = () => {
       key: "role",
       label: "Role",
       type: "string" as const,
-      filter: true,
+      filter: "search" as const,
       sortable: true,
+      catalogOptions: {
+        data: [
+          { id: "Admin", name: "Admin" },
+          { id: "Editor", name: "Editor" },
+          { id: "Viewer", name: "Viewer" },
+        ],
+      },
       render: (row: any) => (
         <span className={`px-2 py-0.5 text-[10px] font-bold uppercase tracking-wider rounded-md ${
           row.role === "Admin" ? "bg-primary-100 text-primary-700 dark:bg-primary-950/40 dark:text-primary-300" :
@@ -485,23 +609,55 @@ export const DataTableShowcase = () => {
         }`}>{row.role}</span>
       )
     },
+    {
+      key: "hiredAt",
+      label: "Hired",
+      type: "date" as const,
+      filter: "date-range" as const,
+      sortable: true,
+      dateFilterOptions: { maxDate: new Date() },
+      render: (row: any) =>
+        new Date(row.hiredAt as string).toLocaleDateString("es-MX", {
+          day: "2-digit",
+          month: "short",
+          year: "numeric",
+        }),
+    },
     { key: "active", label: "Active", type: "boolean" as const, filter: true }
   ], []);
 
-  const MOCK_USERS = useMemo(() => [
-    { id: 1, name: "Sofía Castillo", role: "Admin", active: true },
-    { id: 2, name: "Daniela Klein", role: "Editor", active: true },
-    { id: 3, name: "Mariana Reyes", role: "Viewer", active: false },
-    { id: 4, name: "Camila Torres", role: "Admin", active: true },
-    { id: 5, name: "Valentina Méndez", role: "Editor", active: true },
-    { id: 6, name: "Luciana Rivas", role: "Viewer", active: false },
-    { id: 7, name: "Isabella Cruz", role: "Editor", active: true },
-    { id: 8, name: "Gabriela Vargas", role: "Admin", active: true },
-    { id: 9, name: "Ana López", role: "Editor", active: false },
-    { id: 10, name: "Carla Jiménez", role: "Viewer", active: true },
-    { id: 11, name: "Luisa Fernández", role: "Admin", active: true },
-    { id: 12, name: "Renata Morales", role: "Viewer", active: false },
-  ], []);
+  // Pixel widths force horizontal overflow inside the 520px demo wrapper, so
+  // the first (ID) and last (Active) columns stay pinned while the middle
+  // ones scroll sideways.
+  const pinnedColumns = useMemo(
+    () =>
+      userColumns.map((col: any, i: number) => ({
+        ...col,
+        width: [72, 220, 180, 180, 120][i],
+        pinned: i === 0 ? "left" : i === userColumns.length - 1 ? "right" : undefined,
+      })),
+    [userColumns]
+  );
+
+  const MOCK_USERS = useMemo(() =>
+    [
+      { id: 1, name: "Sofía Castillo", role: "Admin", active: true },
+      { id: 2, name: "Daniela Klein", role: "Editor", active: true },
+      { id: 3, name: "Mariana Reyes", role: "Viewer", active: false },
+      { id: 4, name: "Camila Torres", role: "Admin", active: true },
+      { id: 5, name: "Valentina Méndez", role: "Editor", active: true },
+      { id: 6, name: "Luciana Rivas", role: "Viewer", active: false },
+      { id: 7, name: "Isabella Cruz", role: "Editor", active: true },
+      { id: 8, name: "Gabriela Vargas", role: "Admin", active: true },
+      { id: 9, name: "Ana López", role: "Editor", active: false },
+      { id: 10, name: "Carla Jiménez", role: "Viewer", active: true },
+      { id: 11, name: "Luisa Fernández", role: "Admin", active: true },
+      { id: 12, name: "Renata Morales", role: "Viewer", active: false },
+    ].map((row, i) => ({
+      ...row,
+      hiredAt: new Date(2023, (i * 5) % 12, ((i * 7) % 27) + 1).toISOString(),
+    })),
+  []);
 
   const fetchData = useCallback(async (params: ITDataTableFetchParams): Promise<ITDataTableResponse<any>> => {
     const delay = apiState === "loading" ? 8000 : 400;
@@ -517,14 +673,31 @@ export const DataTableShowcase = () => {
 
     let mockData = [...MOCK_USERS];
 
+    const matchesFilter = (itemValue: unknown, filterVal: unknown): boolean => {
+      // Single date (filter: "date")
+      if (filterVal instanceof Date) {
+        const d = new Date(String(itemValue));
+        return !isNaN(d.getTime()) && d.toDateString() === filterVal.toDateString();
+      }
+      // Date range (filter: "date-range") — [start, end]
+      if (Array.isArray(filterVal)) {
+        const [start, end] = filterVal as [Date | null, Date | null];
+        if (!start && !end) return true;
+        const d = new Date(String(itemValue));
+        if (isNaN(d.getTime())) return false;
+        if (start && d.getTime() < startOfDay(start).getTime()) return false;
+        if (end && d.getTime() > endOfDay(end).getTime()) return false;
+        return true;
+      }
+      // Scalar filters (text/number/boolean/catalog/search id)
+      return String(itemValue).toLowerCase().includes(String(filterVal).toLowerCase());
+    };
+
     if (params.filters) {
       Object.keys(params.filters).forEach(key => {
         const filterVal = params.filters[key];
-        if (filterVal) {
-          mockData = mockData.filter(item =>
-            String((item as any)[key]).toLowerCase().includes(String(filterVal).toLowerCase())
-          );
-        }
+        if (filterVal === undefined || filterVal === "") return;
+        mockData = mockData.filter(item => matchesFilter((item as any)[key], filterVal));
       });
     }
 
@@ -743,14 +916,17 @@ export const DataTableShowcase = () => {
           '<ITDataTable columns={columns} fetchData={api.fetchUsers} />',
           '<ITDataTable columns={columns} fetchData={api.fetchUsers} onRowClick={(row) => open(row)} />',
           '<ITDataTable columns={fixedColumns} fetchData={api.fetchUsers} layout="fixed" density="compact" />',
+          '// Columna fija: pinned "left" | "right" (los offsets acumulan width en px)\n{ key: "id", label: "ID", type: "number", width: 72, pinned: "left" },\n{ key: "active", label: "Active", type: "boolean", width: 120, pinned: "right" }',
           '<ITDataTable columns={cols} fetchData={api.page} virtualized stickyHeader defaultItemsPerPage={200} itemsPerPageOptions={[50, 100, 200]} debounceMs={0} />',
           '<ITDataTable columns={cols} fetchData={api.page} layout="fixed" density="compact" autoCardBreakpoint={640} />',
+          '// Filtro de columna tipo ITSearchSelect (typeahead)\n{ key: "role", label: "Role", type: "string", filter: "search", catalogOptions: { data: roles, onSearch: (q) => api.searchRoles(q) } }',
+          '// Filtro de columna tipo ITDatePicker (rango) — params.filters[key] llega como [start, end]\n{ key: "hiredAt", label: "Hired", type: "date", filter: "date-range", dateFilterOptions: { maxDate: new Date() } }',
         ],
         props: [
           { name: "columns", type: "Column<T>[]", description: "Definiciones de columna." },
           { name: "fetchData", type: "(params: ITDataTableFetchParams) => Promise<ITDataTableResponse<T>>", required: true, description: "Callback asíncrono disparado al cambiar página, filtros u orden. Retorna { data, total }." },
           { name: "debounceMs", type: "number", default: "500", description: "Espera antes de refetch tras cambiar filtros." },
-          { name: "externalFilters", type: "Record<string, string | number | boolean | Date>", default: "{}", description: "Filtros externos fusionados con los internos." },
+          { name: "externalFilters", type: "ColumnFilters", default: "{}", description: "Filtros externos fusionados con los internos. Los valores de fecha pueden ser Date o [start, end]." },
           { name: "loadingIndicator", type: "ReactNode", description: "Elemento custom mostrado mientras carga." },
           { name: "fetchOnMount", type: "boolean", default: "true", description: "Dispara fetch al montar." },
           { name: "reloadTrigger", type: "number | string | boolean", description: "Cambiar su valor fuerza un refetch." },
@@ -779,6 +955,7 @@ export const DataTableShowcase = () => {
           "onRowClick funciona en ambas vistas (tabla y cards).",
           "Interacciones que inician en botones, links o inputs no disparan onRowClick.",
           "Column acepta width (number=px | string CSS), minWidth (px), align (left/center/right) y truncate (ellipsis + title nativo).",
+          "Columna fija: Column acepta pinned: \"left\" | \"right\" (opt-in; omitir = sin cambios). Los offsets sticky acumulan el width en px de cada columna pinneada previa del mismo lado; una columna sin width en px aporta 0px, así que declara width en px en todas las columnas pinneadas de un lado. La celda pinneada pinta fondo opaco (rowBg + rowHover) y un separador de 1px en el borde congelado. Una columna pinneada por lado es el contrato probado. Limitación: con variant=\"striped\" el fondo opaco tapa el tinte de la franja de esa columna.",
           "Anti scroll horizontal: layout=\"fixed\" + width por columna + truncate + density.",
           "Virtualización: solo vista tabla; rinde con page size grande; filas de alto uniforme; el scroll no se reinicia al cambiar filtros.",
           "La virtualización server-side hace ventana sobre la PÁGINA ACTUAL (data.length), no sobre total: usar un defaultItemsPerPage grande (p. ej. 200) con itemsPerPageOptions que lo incluya, o el efecto es invisible.",
@@ -787,6 +964,7 @@ export const DataTableShowcase = () => {
           "El toggle interno Table/Cards también desactiva la virtualización; las cards nunca se virtualizan.",
           "debounceMs={0} evita el retardo de refetch en demos.",
           "variant=\"minimal\" se acepta por tipo pero no tiene estilos (igual que default). ITSearchTable no soporta layout/density/autoCardBreakpoint/virtualized/width.",
+          "Modos de filtro por columna: filter: \"search\" renderiza ITSearchSelect (usa catalogOptions.data; catalogOptions.onSearch habilita búsqueda server-side debounced), y filter: \"date\" / \"date-range\" renderizan ITDatePicker con dateFilterOptions { minDate, maxDate }. En fetchData, params.filters[key] llega como Date (date) o [start, end] (date-range).",
         ],
       }}
       gallery={
@@ -845,6 +1023,24 @@ export const DataTableShowcase = () => {
             </div>
           </div>
 
+          <div>
+            <h4 className="text-sm font-bold text-slate-700 dark:text-slate-200 mb-3">Pinned columns — left (ID) &amp; right (Active)</h4>
+            <div className="border border-slate-200 dark:border-slate-700 rounded-xl overflow-hidden" style={{ maxWidth: 520 }}>
+              <ITDataTable
+                columns={pinnedColumns}
+                fetchData={fetchData}
+                title="Pinned columns"
+                layout="fixed"
+                density="compact"
+                defaultItemsPerPage={4}
+                debounceMs={0}
+              />
+            </div>
+            <p className="mt-2 text-xs text-slate-500 dark:text-slate-400">
+              Scroll the table sideways: <code>pinned: "left"</code> freezes the ID column, <code>pinned: "right"</code> freezes the Active column.
+            </p>
+          </div>
+
           <div>
             <h4 className="text-sm font-bold text-slate-700 dark:text-slate-200 mb-3">Server-side virtualization — 240 rows {dtVirtualized ? "(page 200)" : "(page 10)"}</h4>
             <div className="border border-slate-200 dark:border-slate-700 rounded-xl overflow-hidden">

package/src/showcases/StructureShowcases.tsx

@@ -939,10 +939,23 @@ export const LayoutShowcase = () => {
         id: "sales",
         label: "Ventas",
         icon: <FaShoppingCart />,
-        isActive: activeId === "sales" || activeId === "orders",
+        isActive: activeId === "sales" || activeId === "orders" || activeId === "quotes",
         subitems: [
-          { id: "orders", label: "Órdenes", action: () => setActiveId("orders") },
-          { id: "invoices", label: "Facturas", action: () => setActiveId("invoices") },
+          {
+            id: "sales-gestion",
+            label: "Gestión",
+            items: [
+              { id: "orders", label: "Órdenes", action: () => setActiveId("orders") },
+              { id: "invoices", label: "Facturas", action: () => setActiveId("invoices") },
+            ],
+          },
+          {
+            id: "sales-catalogo",
+            label: "Catálogo",
+            items: [
+              { id: "quotes", label: "Cotizaciones", action: () => setActiveId("quotes") },
+            ],
+          },
         ],
       },
       { id: "products", label: "Productos", icon: <FaBoxOpen />, isActive: activeId === "products", action: () => setActiveId("products"), badge: "3" },
@@ -968,7 +981,21 @@ export const LayoutShowcase = () => {
     userMenu: { userName, userEmail, menuItems }
   }}
   sidebar={{
-    navigationItems: [...],
+    navigationItems: [
+      { id: "dashboard", label: "Dashboard", icon: <FaChartLine />, isActive: true },
+      {
+        id: "sales", label: "Ventas", icon: <FaShoppingCart />,
+        subitems: [
+          { id: "sales-gestion", label: "Gestión", items: [
+            { id: "orders", label: "Órdenes" },
+            { id: "invoices", label: "Facturas" },
+          ]},
+          { id: "sales-catalogo", label: "Catálogo", items: [
+            { id: "quotes", label: "Cotizaciones" },
+          ]},
+        ]
+      },
+    ],
     isCollapsed: ${collapsed},
     // Slot opcional sobre la navegación (oculto al colapsar)
     header: <span>AXZY v1.3</span>
@@ -1114,13 +1141,14 @@ export const LayoutShowcase = () => {
         ],
         props: [
           { name: "topBar", type: "ITTopBarProps", required: true, description: "Configuración de la barra superior." },
-          { name: "sidebar", type: "ITSidebarProps", required: true, description: "Configuración del sidebar (navigationItems, isCollapsed, header…)." },
+          { name: "sidebar", type: "ITSidebarProps", required: true, description: "Configuración del sidebar (navigationItems con subítems planos o agrupados, isCollapsed, header…)." },
           { name: "children", type: "React.ReactNode", required: true, description: "Contenido principal." },
           { name: "className", type: "string", description: "Clases del wrapper externo." },
           { name: "contentClassName", type: "string", description: "Clases del contenedor de contenido." },
           { name: "sidebar.header", type: "React.ReactNode", description: "Slot opcional sobre la navegación (ej. wordmark o filtro). Oculto al colapsar." },
         ],
         notes: [
+          "`subitems` acepta entradas planas o grupos con `label`+`items`; el título del grupo no es foco ni un tercer nivel.",
           "El sidebar hereda aria-current/aria-expanded y acepta un slot header opcional.",
           "Con `sidebar.isCollapsed` omitido el contenido reserva 88px (hover expande sobre el contenido). Si lo controlas a `false`, reserva 280px y no tapa el contenido.",
           "El riel colapsado se expande automáticamente al pasar el cursor por encima; no hay botón de colapso.",

package/src/types/table.types.ts

@@ -1,5 +1,22 @@
 export type TableVariants = "default" | "striped" | "bordered";
 
+/**
+ * Value stored for a single column filter.
+ *
+ * - `string | number | boolean` — text/number/boolean filters and catalog ids.
+ * - `Date` — a single-date filter (`Column.filter: "date"`).
+ * - `[Date | null, Date | null]` — a date-range filter (`Column.filter: "date-range"`).
+ */
+export type ColumnFilterValue =
+  | string
+  | number
+  | boolean
+  | Date
+  | [Date | null, Date | null];
+
+/** Map of column `key` to its active filter value. */
+export type ColumnFilters = Record<string, ColumnFilterValue>;
+
 export type TableSize = "sm" | "md" | "lg";
 
 export const variantStyles: Record<TableVariants, string> = {

package/src/utils/table.utils.ts

@@ -39,3 +39,86 @@ export function isInteractiveTarget(
   if (boundary instanceof Node && interactive === boundary) return false;
   return true;
 }
+
+// ──────────────────────────────────────────────
+//   PINNED (FROZEN) TABLE COLUMNS
+// ──────────────────────────────────────────────
+
+/** Horizontal edge a table column can be pinned to, used by `Column.pinned`. */
+export type TablePinnedSide = "left" | "right";
+
+/**
+ * Structural shape required to compute pinned offsets. Kept loose (not tied to
+ * `Column<T>`) so any column-like definition can be passed without importing
+ * the table props module.
+ */
+type PinnableColumn = {
+  /** Unique column key; also the map key in the returned metadata. */
+  key: string;
+  /** Edge the column is frozen to, if any. */
+  pinned?: "left" | "right";
+  /** Declared width; a pixel `number` / `"<n>px"` string drives the offset. */
+  width?: number | string;
+  /** Fallback offset width (px) when `width` is not a pixel value. */
+  minWidth?: number;
+};
+
+/** Sticky metadata for one pinned column. */
+export interface PinnedColumnMeta {
+  /** Edge the column is frozen to. */
+  side: TablePinnedSide;
+  /** Distance (px) from that edge to the column's sticky position. */
+  offset: number;
+}
+
+/**
+ * Pixel width a pinned column contributes to the accumulated sticky offset.
+ * Numbers are pixels; `"<n>px"` strings are parsed; every other length
+ * (`%`, `rem`, `em`, …) falls back to `minWidth ?? 0`.
+ */
+function pinnedColumnWidth(col: PinnableColumn): number {
+  if (typeof col.width === "number") return col.width;
+  if (typeof col.width === "string" && /^\d+(\.\d+)?px$/.test(col.width.trim())) {
+    return parseFloat(col.width);
+  }
+  return col.minWidth ?? 0;
+}
+
+/**
+ * Computes the sticky `offset` for every pinned column in a table.
+ *
+ * Left-pinned columns accumulate forward in document order; right-pinned
+ * columns accumulate backward. Only pinned columns appear in the returned map,
+ * keyed by `col.key`. A column whose width is not resolvable to pixels
+ * contributes `minWidth ?? 0`, so declare a pixel `width` on every pinned
+ * column of the same side to keep offsets aligned.
+ *
+ * @param columns - Column definitions in render order.
+ * @returns Map of pinned column `key` → `{ side, offset }`.
+ */
+export function getPinnedColumnMeta<T extends PinnableColumn>(
+  columns: T[]
+): Record<string, PinnedColumnMeta> {
+  const meta: Record<string, PinnedColumnMeta> = {};
+
+  // Left edge: walk forward, accumulating widths of preceding left-pinned columns.
+  let leftOffset = 0;
+  for (const col of columns) {
+    if (col.pinned === "left") {
+      meta[col.key] = { side: "left", offset: leftOffset };
+      leftOffset += pinnedColumnWidth(col);
+    }
+  }
+
+  // Right edge: walk backward, accumulating widths of preceding right-pinned columns.
+  let rightOffset = 0;
+  for (let i = columns.length - 1; i >= 0; i--) {
+    const col = columns[i];
+    if (col.pinned === "right") {
+      meta[col.key] = { side: "right", offset: rightOffset };
+      rightOffset += pinnedColumnWidth(col);
+    }
+  }
+
+  return meta;
+}