@axzydev/axzy_ui_system 1.3.4 → 1.3.5

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

@@ -1,8 +1,30 @@
 import { useEffect, useRef, useState } from "react";
 import { FaChevronDown } from "react-icons/fa";
-import { ITNavigationItem, ITSidebarProps } from "./sidebar.props";
+import {
+  ITNavigationItem,
+  ITNavigationSubItem,
+  ITNavigationSubItemEntry,
+  ITNavigationSubItemGroup,
+  ITSidebarProps,
+} from "./sidebar.props";
 import ITText from "@/components/atoms/text/text";
 
+/** Narrows a submenu entry to a titled group. */
+function isSubItemGroup(
+  entry: ITNavigationSubItemEntry,
+): entry is ITNavigationSubItemGroup {
+  return "items" in entry;
+}
+
+/** Flattens a parent's entries (plain items + groups) into a single list. */
+function flattenSubItems(
+  entries: ITNavigationSubItemEntry[],
+): ITNavigationSubItem[] {
+  return entries.flatMap((entry) =>
+    isSubItemGroup(entry) ? entry.items : [entry],
+  );
+}
+
 /**
  * Vertical navigation sidebar with submenu expand/collapse, hover tooltips in collapsed mode,
  * and glassmorphism styling. The collapsed rail expands automatically on pointer hover — there
@@ -76,7 +98,7 @@ export default function ITSidebar({
   useEffect(() => {
     const activeParents = new Set<string>();
     navigationItems.forEach(item => {
-      if (item.subitems && item.subitems.some(sub => sub.isActive)) {
+      if (item.subitems && flattenSubItems(item.subitems).some(sub => sub.isActive)) {
         activeParents.add(item.id);
       }
     });
@@ -115,6 +137,86 @@ export default function ITSidebar({
   const isSidebarCollapsed = visibleOnMobile ? false : (!isHovering && isCollapsed);
   const sidebarWidth = isSidebarCollapsed ? "w-[88px]" : "w-[280px]";
 
+  const renderSubItem = (subitem: ITNavigationSubItem) => (
+    <li key={subitem.id} className="relative">
+      <button
+        aria-current={subitem.isActive ? "page" : undefined}
+        onClick={() => {
+          if (subitem.action) subitem.action();
+          if (onSubItemClick) onSubItemClick(subitem);
+        }}
+        className={`flex items-center gap-2 w-full text-left px-3 py-1.5 rounded-xl transition-all duration-300`}
+        style={{
+          color: subitem.isActive ? "var(--it-sidebar-active-color, var(--color-secondary-900))" : "var(--it-sidebar-label-color, var(--color-secondary-600))",
+          backgroundColor: subitem.isActive ? "var(--it-sidebar-active-bg, var(--color-secondary-50))" : 'transparent',
+          fontSize: '0.78rem',
+          fontWeight: subitem.isActive ? 600 : 500,
+          letterSpacing: '0.01em',
+          marginLeft: subitemConnector === '|' ? '-1px' : '0',
+        }}
+        onMouseEnter={(e) => {
+          if (!subitem.isActive) {
+            e.currentTarget.style.backgroundColor = "var(--it-sidebar-hover-bg, var(--color-secondary-100))";
+            e.currentTarget.style.transform = 'translateX(3px)';
+          }
+        }}
+        onMouseLeave={(e) => {
+          if (!subitem.isActive) {
+            e.currentTarget.style.backgroundColor = 'transparent';
+            e.currentTarget.style.transform = 'translateX(0)';
+          }
+        }}
+      >
+        {subitem.isActive && subitemConnector === '|' && (
+          <div
+            className="absolute left-0 top-1/3 bottom-1/3 w-[2.5px] rounded-r-full transition-all"
+            style={{
+              backgroundColor: "var(--it-sidebar-active-icon, var(--color-primary-500))",
+              boxShadow: "0 0 6px color-mix(in srgb, var(--it-sidebar-active-icon, var(--color-primary-500)) 25%, transparent)",
+            }}
+          />
+        )}
+        {subitemConnector === 'dot' && (
+          <span
+            className={`w-1.5 h-1.5 rounded-full flex-shrink-0 transition-all duration-300 ${subitem.isActive ? 'scale-125' : ''}`}
+            style={{
+              backgroundColor: subitem.isActive
+                ? "var(--it-sidebar-active-icon, var(--color-primary-500))"
+                : "var(--it-sidebar-icon-color, var(--color-secondary-400))"
+            }}
+          />
+        )}
+        <ITText as="span" className="truncate">{subitem.label}</ITText>
+      </button>
+    </li>
+  );
+
+  const renderSubItemGroup = (group: ITNavigationSubItemGroup, itemId: string) => {
+    const headingId = `it-sidebar-subgroup-${itemId}-${group.id}`;
+    return (
+      <li key={group.id} className="relative">
+        <div id={headingId} className="px-3 pt-2.5 pb-1 mt-1">
+          <ITText
+            as="span"
+            className="block"
+            style={{
+              color: "var(--it-sidebar-icon-color, var(--color-secondary-400))",
+              fontSize: "0.68rem",
+              fontWeight: 700,
+              letterSpacing: "0.08em",
+              textTransform: "uppercase",
+            }}
+          >
+            {group.label}
+          </ITText>
+        </div>
+        <ul aria-labelledby={headingId} className="flex flex-col gap-0">
+          {group.items.map(renderSubItem)}
+        </ul>
+      </li>
+    );
+  };
+
   return (
     <aside
       ref={sidebarRef}
@@ -256,7 +358,7 @@ export default function ITSidebar({
 
                   {item.subitems && item.subitems.length > 0 ? (
                     <div className="py-2">
-                      {item.subitems.map((subitem) => (
+                      {flattenSubItems(item.subitems).map((subitem) => (
                         <div
                           key={subitem.id}
                           className={`px-5 py-2.5 text-sm flex items-center gap-3 transition-colors relative`}
@@ -283,7 +385,7 @@ export default function ITSidebar({
 
               {/* Submenu - smooth height/opacity when not collapsed */}
               {!isSidebarCollapsed && item.subitems && item.subitems.length > 0 && (
-                <div id={submenuId} role="group" aria-label={item.label} className={`overflow-hidden transition-all duration-400 ease-[cubic-bezier(0.2,0,0,1)] ${expandedItems.has(item.id) ? "max-h-[500px] opacity-100 mt-1" : "max-h-0 opacity-0"}`}>
+                <div id={submenuId} role="group" aria-label={item.label} className={`overflow-hidden transition-all duration-400 ease-[cubic-bezier(0.2,0,0,1)] ${expandedItems.has(item.id) ? "max-h-[1000px] opacity-100 mt-1" : "max-h-0 opacity-0"}`}>
                   <ul
                     className="ml-4 flex flex-col gap-0 py-0.5"
                     style={{
@@ -292,59 +394,11 @@ export default function ITSidebar({
                         : 'none'
                     }}
                   >
-                    {item.subitems.map((subitem) => (
-                      <li key={subitem.id} className="relative">
-                        <button
-                          aria-current={subitem.isActive ? "page" : undefined}
-                          onClick={() => {
-                            if (subitem.action) subitem.action();
-                            if (onSubItemClick) onSubItemClick(subitem);
-                          }}
-                          className={`flex items-center gap-2 w-full text-left px-3 py-1.5 rounded-xl transition-all duration-300`}
-                          style={{
-                            color: subitem.isActive ? "var(--it-sidebar-active-color, var(--color-secondary-900))" : "var(--it-sidebar-label-color, var(--color-secondary-600))",
-                            backgroundColor: subitem.isActive ? "var(--it-sidebar-active-bg, var(--color-secondary-50))" : 'transparent',
-                            fontSize: '0.78rem',
-                            fontWeight: subitem.isActive ? 600 : 500,
-                            letterSpacing: '0.01em',
-                            marginLeft: subitemConnector === '|' ? '-1px' : '0',
-                          }}
-                          onMouseEnter={(e) => {
-                            if (!subitem.isActive) {
-                              e.currentTarget.style.backgroundColor = "var(--it-sidebar-hover-bg, var(--color-secondary-100))";
-                              e.currentTarget.style.transform = 'translateX(3px)';
-                            }
-                          }}
-                          onMouseLeave={(e) => {
-                            if (!subitem.isActive) {
-                              e.currentTarget.style.backgroundColor = 'transparent';
-                              e.currentTarget.style.transform = 'translateX(0)';
-                            }
-                          }}
-                        >
-                          {subitem.isActive && subitemConnector === '|' && (
-                            <div
-                              className="absolute left-0 top-1/3 bottom-1/3 w-[2.5px] rounded-r-full transition-all"
-                              style={{
-                                backgroundColor: "var(--it-sidebar-active-icon, var(--color-primary-500))",
-                                boxShadow: "0 0 6px color-mix(in srgb, var(--it-sidebar-active-icon, var(--color-primary-500)) 25%, transparent)",
-                              }}
-                            />
-                          )}
-                          {subitemConnector === 'dot' && (
-                            <span
-                              className={`w-1.5 h-1.5 rounded-full flex-shrink-0 transition-all duration-300 ${subitem.isActive ? 'scale-125' : ''}`}
-                              style={{
-                                backgroundColor: subitem.isActive
-                                  ? "var(--it-sidebar-active-icon, var(--color-primary-500))"
-                                  : "var(--it-sidebar-icon-color, var(--color-secondary-400))"
-                              }}
-                            />
-                          )}
-                          <ITText as="span" className="truncate">{subitem.label}</ITText>
-                        </button>
-                      </li>
-                    ))}
+                    {item.subitems.map((entry) =>
+                      isSubItemGroup(entry)
+                        ? renderSubItemGroup(entry, item.id)
+                        : renderSubItem(entry),
+                    )}
                   </ul>
                 </div>
               )}

package/src/index.css

@@ -160,4 +160,14 @@
   .it-stepper-slide-in-left {
     animation: it-slide-in-left 320ms cubic-bezier(0.2, 0.8, 0.2, 1) both;
   }
+
+  /* Pinned (frozen) table columns: 1px edge separator on the frozen side.
+     Background + hover live in the component as Tailwind arbitrary utilities so
+     the cell matches --color-table-rowBg / --color-table-rowHover. */
+  :where(.it-table-pinned-left) {
+    box-shadow: inset -1px 0 0 0 var(--color-secondary-200);
+  }
+  :where(.it-table-pinned-right) {
+    box-shadow: inset 1px 0 0 0 var(--color-secondary-200);
+  }
 }

package/src/index.ts

@@ -101,7 +101,7 @@ import type { ITSearchSelectProps } from "./components/molecules/search-select/s
 import type { ITSelectProps } from "./components/molecules/select/select.props";
 import type { ITSearchTableProps } from "./components/organisms/searchTable/searchTable.props";
 import type { ITSegmentedControlProps } from "./components/atoms/segmented-control/segmented-control.props";
-import type { ITSidebarProps, ITNavigationItem, ITNavigationSubItem } from "./components/organisms/sidebar/sidebar.props";
+import type { ITSidebarProps, ITNavigationItem, ITNavigationSubItem, ITNavigationSubItemEntry, ITNavigationSubItemGroup } from "./components/organisms/sidebar/sidebar.props";
 import type { ITSkeletonProps } from "./components/atoms/skeleton/skeleton.props";
 import type { ITSlideToggleProps } from "./components/atoms/slide/slide.props";
 import type { ITSliderProps } from "./components/atoms/slider/slider.props";
@@ -173,6 +173,7 @@ export {
     ITLayoutProps, ITLoaderProps, ITNavbarProps,
     ITPageProps, ITPageHeaderProps,
     ITNavigationItem, ITNavigationSubItem,
+    ITNavigationSubItemEntry, ITNavigationSubItemGroup,
     ITPaginationProps, ITPopoverProps, ITProgressProps,
     ITRadioGroupProps, ITRadioOption, ITSelectProps, ITSearchSelectProps,
     ITSearchTableProps,

package/src/showcases/DataShowcases.tsx

@@ -248,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 = [
@@ -344,6 +353,7 @@ 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() } }',
@@ -377,6 +387,7 @@ 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.",
@@ -483,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 }}>
@@ -598,6 +626,19 @@ export const DataTableShowcase = () => {
     { key: "active", label: "Active", type: "boolean" as const, filter: true }
   ], []);
 
+  // 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 },
@@ -875,6 +916,7 @@ 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) } }',
@@ -913,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.",
@@ -980,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/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;
+}