@ceriousdevtech/react-cerious-scroll 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to react-cerious-scroll will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.5] - 2026-06-08
+
+### Added
+- **Table mode support** (`options={{ layout: 'table' }}`). Rows render as real `<td>` cells into the engine's `<tr>`. React renders each row into its own `display: contents` wrapper, which keeps the reconciler isolated from the engine's `<tr>` recycling (so a fast scroll can't trip a `removeChild` on cells the engine already cleared) while the cells still lay out as the row's columns.
+- **`tableHeader`** prop. Declarative header (provide a `<tr>` of `<th>`s) rendered into the engine's `<thead>` via a portal — same `<table>` as the rows, so columns align natively. Reactive like any other portal.
+
+### Dependencies
+- Bumped `@ceriousdevtech/cerious-scroll` to `^1.0.6`: native table layout, `table.autoSizeColumns` (auto-sized but stable columns), trackpad-only wheel inertia, overlay-scrollbar gutter fix, and exact bottom snap.
+
 ## [1.0.4] - 2026-06-04
 
 ### Dependencies

package/README.md

@@ -109,7 +109,8 @@ function List() {
 | `items` | `readonly TItem[]` | Optional data array. `totalElements` defaults to `items.length`. |
 | `totalElements` | `number` | Total item count. Required if `items` is omitted. |
 | `getItem` | `(index) => TItem` | Lazy item getter for large/sparse datasets. |
-| `options` | `CeriousScrollOptions` | Engine options (keyboard/touch/wheel/scrollbar/etc.). Read once at creation. |
+| `tableHeader` | `ReactNode` | Table mode only. A `<tr>` of `<th>`s rendered into the engine's `<thead>` (see [Table layout](#table-layout)). |
+| `options` | `CeriousScrollOptions` | Engine options (keyboard/touch/wheel/scrollbar/`layout`/etc.). Read once at creation. |
 | `autoRender` | `boolean` | Re-render on scroll/resize/data changes. Default `true`. |
 | `onViewportChange` | `(detail) => void` | Normalized viewport-change callback. |
 | `onMeasuredViewport` | `(range) => void` | Measured range after each render pass. |
@@ -130,6 +131,41 @@ const ref = useRef<CeriousScrollHandle>(null);
 
 ---
 
+## Table layout
+
+Pass `options={{ layout: 'table' }}` to render real `<table>` / `<tr>` / `<td>` rows with a frozen header and native column alignment. Your `renderItem` returns the row's `<td>` cells, and `tableHeader` provides the (declarative, reactive) `<thead>` row:
+
+```tsx
+import { TABLE_COLUMNS } from './data';
+
+<CeriousScroll
+  className="my-scroll"            // give it a height
+  totalElements={100_000}
+  getItem={(i) => i}
+  options={{ layout: 'table', table: { tableClassName: 'my-table', autoSizeColumns: true } }}
+  tableHeader={
+    <tr>{TABLE_COLUMNS.map((c) => <th key={c.key}>{c.label}</th>)}</tr>
+  }
+  renderItem={(index) => {
+    const row = makeRow(index);
+    return (
+      <>
+        <td>{row.id}</td>
+        <td>{row.name}</td>
+        <td>{row.email}</td>
+      </>
+    );
+  }}
+/>
+```
+
+- **`tableHeader`** is portaled into the engine's `<thead>` — the same `<table>` as the rows, so columns align natively and the header stays frozen.
+- **`renderItem` must return `<td>`s** (a fragment of cells). They're rendered into the row's `<tr>` via a `display: contents` wrapper, so React fully owns them and the engine's row recycling can't tear them out.
+- **`table.autoSizeColumns`** measures column widths once and pins them — auto-sized but stable (no jitter, no manual widths). Or use `table.columnWidths`. Variable row heights work as usual.
+- CSS: `border-collapse: separate` and an **opaque `<thead>` background** (see the core README's [Table Layout](https://github.com/ceriousdevtech/cerious-scroll#-table-layout-layout-table) notes).
+
+---
+
 ## Notes
 
 - **No height estimation.** Rows are committed with `flushSync` so the engine

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const Q=require("react/jsx-runtime"),r=require("react"),D=require("react-dom"),U=require("react-dom/server"),W=require("@ceriousdevtech/cerious-scroll"),B="data-cerious-scroll-content",Z="data-cerious-scroll-row";function x(e){const l=e.querySelector(`[${B}]`);if(l)return l;const n=document.createElement("div");return n.setAttribute(B,""),n.style.position="relative",n.style.width="100%",n.style.height="100%",n.style.overflowY="clip",n.style.overflowX="auto",e.appendChild(n),n}function ee(e,l){const n=d=>{const o=d.detail;o&&l({percentage:o.percentage,currentElement:o.currentElement,scrollOffset:o.scrollOffset,result:{element:o.result.element,offset:o.result.offset}})},i=d=>{const o=d.detail;o&&l({percentage:o.percentage,currentElement:o.element,scrollOffset:o.scrollOffset,result:{element:o.element,offset:o.scrollOffset}})};return e.addEventListener("cerious-viewport-change",n),e.addEventListener("viewport-change",i),()=>{e.removeEventListener("cerious-viewport-change",n),e.removeEventListener("viewport-change",i)}}function te(e,l){const n=typeof e=="number"?e:typeof l=="number"?l:void 0;if(n===void 0||Number.isNaN(n))throw new Error("useCeriousScroll: provide `totalElements` or `items`.");return Math.max(1,Math.floor(n))}function X(e){var z;const l=r.useRef(null),n=r.useRef(null),i=r.useRef(new Map),d=r.useRef(new Map),o=r.useRef(null),g=r.useRef(null),[,j]=r.useReducer(t=>t+1,0),[k,b]=r.useState(null),p=r.useRef(e.renderItem),R=r.useRef(e.items??null),S=r.useRef(e.getItem),w=r.useRef(e.options),E=r.useRef(e.autoRender??!0),L=r.useRef(e.totalElements??null),O=r.useRef(e.onViewportChange),T=r.useRef(e.onMeasuredViewport),M=r.useRef(e.onReady);p.current=e.renderItem,R.current=e.items??null,S.current=e.getItem,w.current=e.options,E.current=e.autoRender??!0,L.current=e.totalElements??null,O.current=e.onViewportChange,T.current=e.onMeasuredViewport,M.current=e.onReady;const N=r.useCallback(t=>{const c=S.current;if(c)return c(t);const a=R.current;return a?a[t]:void 0},[]),s=r.useCallback(()=>{var I;const t=n.current;if(!t)return null;const{scroller:c,contentEl:a,container:u}=t,F=u.clientHeight||u.offsetHeight||0,y=[],f=(m,C)=>{const h=document.createElement("div");h.setAttribute(Z,String(m)),h.innerHTML=U.renderToStaticMarkup(r.createElement(r.Fragment,null,p.current(N(m),m))),C.appendChild(h),i.current.set(m,{el:C,mount:h}),y.push(h)},A=c.renderViewport(F,a,f),q=new Set(c.getRenderedIndices());return i.current.forEach((m,C)=>{q.has(C)||i.current.delete(C)}),y.forEach(m=>{m.textContent=""}),D.flushSync(j),(I=T.current)==null||I.call(T,A),A},[]),Y=e.totalElements??((z=e.items)==null?void 0:z.length)??null;r.useEffect(()=>{var I,m;const t=l.current;if(!t)return;const c=x(t),a=w.current??{},u=a.onScroll,F={...a,onScroll:()=>{u==null||u(),E.current&&s()}},y=te(L.current,((I=R.current)==null?void 0:I.length)??null),f=new W.CeriousScroll(t,y,F);g.current&&(f.currentElement=Math.min(g.current.currentElement,y-1),f.scrollOffset=g.current.scrollOffset,g.current=null),n.current={scroller:f,contentEl:c,container:t},b(f);const A=ee(t,C=>{var h;(h=O.current)==null||h.call(O,C)});(m=M.current)==null||m.call(M,f);let q=0;return E.current&&(q=requestAnimationFrame(()=>s())),()=>{cancelAnimationFrame(q),A(),g.current={currentElement:f.currentElement,scrollOffset:f.scrollOffset},i.current.clear(),d.current.clear(),o.current=null,c.textContent="",f.detachScrollbar(t),f.dispose(),n.current=null,b(null)}},[Y,s]),r.useEffect(()=>{if(!n.current||!E.current)return;const t=requestAnimationFrame(()=>s());return()=>cancelAnimationFrame(t)},[e.items,e.getItem]);const $=r.useCallback(t=>{const c=n.current;return c?(c.scroller.jumpToElement(t),s()):null},[s]),G=r.useCallback(t=>{const c=n.current;return c?(c.scroller.handleScrollPercentage(t),s()):null},[s]),J=r.useCallback(()=>{const t=n.current;return t?(t.scroller.reset(),s()):null},[s]),K=r.useCallback(()=>{const t=n.current;return t?(t.scroller.clearAllCaches(),s()):null},[s]),H=R.current,V=!S.current&&H!=null?H.length:null,P=p.current,v=d.current;o.current!==P&&(v.clear(),o.current=P);const _=[];return i.current.forEach((t,c)=>{if(V!==null&&c>=V){v.delete(c);return}const a=N(c);let u=v.get(c);(!u||u.item!==a||u.mount!==t.mount)&&(u={item:a,mount:t.mount,node:D.createPortal(P(a,c),t.mount,String(c))},v.set(c,u)),_.push(u.node)}),v.size>i.current.size&&v.forEach((t,c)=>{i.current.has(c)||v.delete(c)}),{containerRef:l,portals:_,scroller:k,render:s,jumpToElement:$,scrollToPercentage:G,reset:J,recalculate:K}}function re(e,l){const{className:n,style:i,"data-testid":d,children:o,...g}=e,{containerRef:j,portals:k,scroller:b,render:p,jumpToElement:R,scrollToPercentage:S,reset:w,recalculate:E}=X(g);return r.useImperativeHandle(l,()=>({scroller:b,render:p,jumpToElement:R,scrollToPercentage:S,reset:w,recalculate:E}),[b,p,R,S,w,E]),Q.jsxs("div",{ref:j,className:n,"data-testid":d,style:{position:"relative",overflow:"hidden",...i},children:[o,k]})}const ne=r.forwardRef(re);Object.defineProperty(exports,"CeriousScrollEngine",{enumerable:!0,get:()=>W.CeriousScroll});exports.CeriousScroll=ne;exports.useCeriousScroll=X;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const ee=require("react/jsx-runtime"),r=require("react"),z=require("react-dom"),te=require("react-dom/server"),G=require("@ceriousdevtech/cerious-scroll"),$="data-cerious-scroll-content",re="data-cerious-scroll-row";function ne(e){const s=e.querySelector(`[${$}]`);if(s)return s;const n=document.createElement("div");return n.setAttribute($,""),n.style.position="relative",n.style.width="100%",n.style.height="100%",n.style.overflowY="clip",n.style.overflowX="auto",e.appendChild(n),n}function ce(e,s){const n=h=>{const l=h.detail;l&&s({percentage:l.percentage,currentElement:l.currentElement,scrollOffset:l.scrollOffset,result:{element:l.result.element,offset:l.result.offset}})},f=h=>{const l=h.detail;l&&s({percentage:l.percentage,currentElement:l.element,scrollOffset:l.scrollOffset,result:{element:l.element,offset:l.scrollOffset}})};return e.addEventListener("cerious-viewport-change",n),e.addEventListener("viewport-change",f),()=>{e.removeEventListener("cerious-viewport-change",n),e.removeEventListener("viewport-change",f)}}function le(e,s){const n=typeof e=="number"?e:typeof s=="number"?s:void 0;if(n===void 0||Number.isNaN(n))throw new Error("useCeriousScroll: provide `totalElements` or `items`.");return Math.max(1,Math.floor(n))}function J(e){var Y;const s=r.useRef(null),n=r.useRef(null),f=r.useRef(new Map),h=r.useRef(new Map),l=r.useRef(null),R=r.useRef(null),S=r.useRef(null),T=r.useRef(e.tableHeader),[,M]=r.useReducer(t=>t+1,0),[A,p]=r.useState(null),b=r.useRef(e.renderItem),g=r.useRef(e.items??null),v=r.useRef(e.getItem),L=r.useRef(e.options),q=r.useRef(e.autoRender??!0),D=r.useRef(e.totalElements??null),H=r.useRef(e.onViewportChange),P=r.useRef(e.onMeasuredViewport),j=r.useRef(e.onReady);b.current=e.renderItem,g.current=e.items??null,v.current=e.getItem,T.current=e.tableHeader,L.current=e.options,q.current=e.autoRender??!0,D.current=e.totalElements??null,H.current=e.onViewportChange,P.current=e.onMeasuredViewport,j.current=e.onReady;const B=r.useCallback(t=>{const c=v.current;if(c)return c(t);const o=g.current;return o?o[t]:void 0},[]),u=r.useCallback(()=>{var I,O;const t=n.current;if(!t)return null;const{scroller:c,contentEl:o,container:a}=t,k=a.clientHeight||a.offsetHeight||0,w=[],m=((I=L.current)==null?void 0:I.layout)==="table",_=(i,d)=>{const C=document.createElement("div");m&&(C.style.display="contents"),C.setAttribute(re,String(i)),C.innerHTML=te.renderToStaticMarkup(r.createElement(r.Fragment,null,b.current(B(i),i))),d.appendChild(C),f.current.set(i,{el:d,mount:C}),w.push(C)},y=c.renderViewport(k,o,_),F=new Set(c.getRenderedIndices());return f.current.forEach((i,d)=>{F.has(d)||f.current.delete(d)}),w.forEach(i=>{i.textContent=""}),z.flushSync(M),(O=P.current)==null||O.call(P,y),y},[]),K=e.totalElements??((Y=e.items)==null?void 0:Y.length)??null;r.useEffect(()=>{var F,I,O;const t=s.current;if(!t)return;const c=ne(t),o=L.current??{},a=o.onScroll,k={...o,onScroll:()=>{a==null||a(),q.current&&u()}};if(o.layout==="table"&&T.current!=null){const i=(F=o.table)==null?void 0:F.header;k.table={...o.table,header:d=>{S.current=d,i==null||i(d)}}}const w=le(D.current,((I=g.current)==null?void 0:I.length)??null),m=new G.CeriousScroll(t,w,k);R.current&&(m.currentElement=Math.min(R.current.currentElement,w-1),m.scrollOffset=R.current.scrollOffset,R.current=null),n.current={scroller:m,contentEl:c,container:t},p(m);const _=ce(t,i=>{var d;(d=H.current)==null||d.call(H,i)});(O=j.current)==null||O.call(j,m);let y=0;return q.current&&(y=requestAnimationFrame(()=>u())),()=>{cancelAnimationFrame(y),_(),R.current={currentElement:m.currentElement,scrollOffset:m.scrollOffset},f.current.clear(),h.current.clear(),l.current=null,c.textContent="",m.detachScrollbar(t),m.dispose(),n.current=null,p(null)}},[K,u]),r.useEffect(()=>{if(!n.current||!q.current)return;const t=requestAnimationFrame(()=>u());return()=>cancelAnimationFrame(t)},[e.items,e.getItem]);const Q=r.useCallback(t=>{const c=n.current;return c?(c.scroller.jumpToElement(t),u()):null},[u]),U=r.useCallback(t=>{const c=n.current;return c?(c.scroller.handleScrollPercentage(t),u()):null},[u]),Z=r.useCallback(()=>{const t=n.current;return t?(t.scroller.reset(),u()):null},[u]),x=r.useCallback(()=>{const t=n.current;return t?(t.scroller.clearAllCaches(),u()):null},[u]),W=g.current,X=!v.current&&W!=null?W.length:null,N=b.current,E=h.current;l.current!==N&&(E.clear(),l.current=N);const V=[];return f.current.forEach((t,c)=>{if(X!==null&&c>=X){E.delete(c);return}const o=B(c);let a=E.get(c);(!a||a.item!==o||a.mount!==t.mount)&&(a={item:o,mount:t.mount,node:z.createPortal(N(o,c),t.mount,String(c))},E.set(c,a)),V.push(a.node)}),E.size>f.current.size&&E.forEach((t,c)=>{f.current.has(c)||E.delete(c)}),e.tableHeader!=null&&S.current&&V.push(z.createPortal(e.tableHeader,S.current,"cerious-thead")),{containerRef:s,portals:V,scroller:A,render:u,jumpToElement:Q,scrollToPercentage:U,reset:Z,recalculate:x}}function oe(e,s){const{className:n,style:f,"data-testid":h,children:l,...R}=e,{containerRef:S,portals:T,scroller:M,render:A,jumpToElement:p,scrollToPercentage:b,reset:g,recalculate:v}=J(R);return r.useImperativeHandle(s,()=>({scroller:M,render:A,jumpToElement:p,scrollToPercentage:b,reset:g,recalculate:v}),[M,A,p,b,g,v]),ee.jsxs("div",{ref:S,className:n,"data-testid":h,style:{position:"relative",overflow:"hidden",...f},children:[l,T]})}const se=r.forwardRef(oe);Object.defineProperty(exports,"CeriousScrollEngine",{enumerable:!0,get:()=>G.CeriousScroll});exports.CeriousScroll=se;exports.useCeriousScroll=J;

package/dist/index.js

@@ -1,175 +1,185 @@
-import { jsxs as K } from "react/jsx-runtime";
-import { useRef as c, useReducer as Q, useState as U, useCallback as S, useEffect as B, createElement as Z, Fragment as x, forwardRef as ee, useImperativeHandle as te } from "react";
-import { flushSync as re, createPortal as ne } from "react-dom";
-import { renderToStaticMarkup as oe } from "react-dom/server";
-import { CeriousScroll as ce } from "@ceriousdevtech/cerious-scroll";
-import { CeriousScroll as we } from "@ceriousdevtech/cerious-scroll";
-const D = "data-cerious-scroll-content", le = "data-cerious-scroll-row";
-function se(e) {
-  const l = e.querySelector(`[${D}]`);
-  if (l) return l;
+import { jsxs as ee } from "react/jsx-runtime";
+import { useRef as o, useReducer as te, useState as re, useCallback as w, useEffect as Y, createElement as ne, Fragment as ce, forwardRef as oe, useImperativeHandle as le } from "react";
+import { flushSync as se, createPortal as G } from "react-dom";
+import { renderToStaticMarkup as ue } from "react-dom/server";
+import { CeriousScroll as ae } from "@ceriousdevtech/cerious-scroll";
+import { CeriousScroll as ye } from "@ceriousdevtech/cerious-scroll";
+const J = "data-cerious-scroll-content", ie = "data-cerious-scroll-row";
+function fe(e) {
+  const s = e.querySelector(`[${J}]`);
+  if (s) return s;
   const r = document.createElement("div");
-  return r.setAttribute(D, ""), r.style.position = "relative", r.style.width = "100%", r.style.height = "100%", r.style.overflowY = "clip", r.style.overflowX = "auto", e.appendChild(r), r;
+  return r.setAttribute(J, ""), r.style.position = "relative", r.style.width = "100%", r.style.height = "100%", r.style.overflowY = "clip", r.style.overflowX = "auto", e.appendChild(r), r;
 }
-function ue(e, l) {
-  const r = (d) => {
-    const o = d.detail;
-    o && l({
-      percentage: o.percentage,
-      currentElement: o.currentElement,
-      scrollOffset: o.scrollOffset,
-      result: { element: o.result.element, offset: o.result.offset }
+function me(e, s) {
+  const r = (h) => {
+    const c = h.detail;
+    c && s({
+      percentage: c.percentage,
+      currentElement: c.currentElement,
+      scrollOffset: c.scrollOffset,
+      result: { element: c.result.element, offset: c.result.offset }
     });
-  }, i = (d) => {
-    const o = d.detail;
-    o && l({
-      percentage: o.percentage,
-      currentElement: o.element,
-      scrollOffset: o.scrollOffset,
-      result: { element: o.element, offset: o.scrollOffset }
+  }, f = (h) => {
+    const c = h.detail;
+    c && s({
+      percentage: c.percentage,
+      currentElement: c.element,
+      scrollOffset: c.scrollOffset,
+      result: { element: c.element, offset: c.scrollOffset }
     });
   };
-  return e.addEventListener("cerious-viewport-change", r), e.addEventListener("viewport-change", i), () => {
-    e.removeEventListener("cerious-viewport-change", r), e.removeEventListener("viewport-change", i);
+  return e.addEventListener("cerious-viewport-change", r), e.addEventListener("viewport-change", f), () => {
+    e.removeEventListener("cerious-viewport-change", r), e.removeEventListener("viewport-change", f);
   };
 }
-function ie(e, l) {
-  const r = typeof e == "number" ? e : typeof l == "number" ? l : void 0;
+function de(e, s) {
+  const r = typeof e == "number" ? e : typeof s == "number" ? s : void 0;
   if (r === void 0 || Number.isNaN(r))
     throw new Error("useCeriousScroll: provide `totalElements` or `items`.");
   return Math.max(1, Math.floor(r));
 }
-function ae(e) {
-  var $;
-  const l = c(null), r = c(null), i = c(/* @__PURE__ */ new Map()), d = c(/* @__PURE__ */ new Map()), o = c(null), g = c(null), [, N] = Q((t) => t + 1, 0), [P, I] = U(null), w = c(e.renderItem), E = c(e.items ?? null), C = c(e.getItem), T = c(e.options), p = c(e.autoRender ?? !0), V = c(e.totalElements ?? null), y = c(e.onViewportChange), A = c(e.onMeasuredViewport), M = c(e.onReady);
-  w.current = e.renderItem, E.current = e.items ?? null, C.current = e.getItem, T.current = e.options, p.current = e.autoRender ?? !0, V.current = e.totalElements ?? null, y.current = e.onViewportChange, A.current = e.onMeasuredViewport, M.current = e.onReady;
-  const _ = S((t) => {
-    const n = C.current;
+function he(e) {
+  var X;
+  const s = o(null), r = o(null), f = o(/* @__PURE__ */ new Map()), h = o(/* @__PURE__ */ new Map()), c = o(null), g = o(null), C = o(null), M = o(e.tableHeader), [, A] = te((t) => t + 1, 0), [H, S] = re(null), v = o(e.renderItem), E = o(e.items ?? null), R = o(e.getItem), _ = o(e.options), F = o(e.autoRender ?? !0), $ = o(e.totalElements ?? null), L = o(e.onViewportChange), N = o(e.onMeasuredViewport), P = o(e.onReady);
+  v.current = e.renderItem, E.current = e.items ?? null, R.current = e.getItem, M.current = e.tableHeader, _.current = e.options, F.current = e.autoRender ?? !0, $.current = e.totalElements ?? null, L.current = e.onViewportChange, N.current = e.onMeasuredViewport, P.current = e.onReady;
+  const B = w((t) => {
+    const n = R.current;
     if (n) return n(t);
-    const a = E.current;
-    return a ? a[t] : void 0;
-  }, []), s = S(() => {
-    var b;
+    const l = E.current;
+    return l ? l[t] : void 0;
+  }, []), u = w(() => {
+    var T, O;
     const t = r.current;
     if (!t) return null;
-    const { scroller: n, contentEl: a, container: u } = t, H = u.clientHeight || u.offsetHeight || 0, O = [], f = (m, R) => {
-      const h = document.createElement("div");
-      h.setAttribute(le, String(m)), h.innerHTML = oe(
-        Z(x, null, w.current(_(m), m))
-      ), R.appendChild(h), i.current.set(m, { el: R, mount: h }), O.push(h);
-    }, F = n.renderViewport(H, a, f), L = new Set(n.getRenderedIndices());
-    return i.current.forEach((m, R) => {
-      L.has(R) || i.current.delete(R);
-    }), O.forEach((m) => {
-      m.textContent = "";
-    }), re(N), (b = A.current) == null || b.call(A, F), F;
-  }, []), W = e.totalElements ?? (($ = e.items) == null ? void 0 : $.length) ?? null;
-  B(() => {
-    var b, m;
-    const t = l.current;
+    const { scroller: n, contentEl: l, container: a } = t, j = a.clientHeight || a.offsetHeight || 0, y = [], m = ((T = _.current) == null ? void 0 : T.layout) === "table", z = (i, d) => {
+      const b = document.createElement("div");
+      m && (b.style.display = "contents"), b.setAttribute(ie, String(i)), b.innerHTML = ue(
+        ne(ce, null, v.current(B(i), i))
+      ), d.appendChild(b), f.current.set(i, { el: d, mount: b }), y.push(b);
+    }, I = n.renderViewport(j, l, z), V = new Set(n.getRenderedIndices());
+    return f.current.forEach((i, d) => {
+      V.has(d) || f.current.delete(d);
+    }), y.forEach((i) => {
+      i.textContent = "";
+    }), se(A), (O = N.current) == null || O.call(N, I), I;
+  }, []), K = e.totalElements ?? ((X = e.items) == null ? void 0 : X.length) ?? null;
+  Y(() => {
+    var V, T, O;
+    const t = s.current;
     if (!t) return;
-    const n = se(t), a = T.current ?? {}, u = a.onScroll, H = {
-      ...a,
+    const n = fe(t), l = _.current ?? {}, a = l.onScroll, j = {
+      ...l,
       onScroll: () => {
-        u == null || u(), p.current && s();
+        a == null || a(), F.current && u();
       }
-    }, O = ie(V.current, ((b = E.current) == null ? void 0 : b.length) ?? null), f = new ce(t, O, H);
-    g.current && (f.currentElement = Math.min(g.current.currentElement, O - 1), f.scrollOffset = g.current.scrollOffset, g.current = null), r.current = { scroller: f, contentEl: n, container: t }, I(f);
-    const F = ue(t, (R) => {
-      var h;
-      (h = y.current) == null || h.call(y, R);
+    };
+    if (l.layout === "table" && M.current != null) {
+      const i = (V = l.table) == null ? void 0 : V.header;
+      j.table = {
+        ...l.table,
+        header: (d) => {
+          C.current = d, i == null || i(d);
+        }
+      };
+    }
+    const y = de($.current, ((T = E.current) == null ? void 0 : T.length) ?? null), m = new ae(t, y, j);
+    g.current && (m.currentElement = Math.min(g.current.currentElement, y - 1), m.scrollOffset = g.current.scrollOffset, g.current = null), r.current = { scroller: m, contentEl: n, container: t }, S(m);
+    const z = me(t, (i) => {
+      var d;
+      (d = L.current) == null || d.call(L, i);
     });
-    (m = M.current) == null || m.call(M, f);
-    let L = 0;
-    return p.current && (L = requestAnimationFrame(() => s())), () => {
-      cancelAnimationFrame(L), F(), g.current = {
-        currentElement: f.currentElement,
-        scrollOffset: f.scrollOffset
-      }, i.current.clear(), d.current.clear(), o.current = null, n.textContent = "", f.detachScrollbar(t), f.dispose(), r.current = null, I(null);
+    (O = P.current) == null || O.call(P, m);
+    let I = 0;
+    return F.current && (I = requestAnimationFrame(() => u())), () => {
+      cancelAnimationFrame(I), z(), g.current = {
+        currentElement: m.currentElement,
+        scrollOffset: m.scrollOffset
+      }, f.current.clear(), h.current.clear(), c.current = null, n.textContent = "", m.detachScrollbar(t), m.dispose(), r.current = null, S(null);
     };
-  }, [W, s]), B(() => {
-    if (!r.current || !p.current) return;
-    const t = requestAnimationFrame(() => s());
+  }, [K, u]), Y(() => {
+    if (!r.current || !F.current) return;
+    const t = requestAnimationFrame(() => u());
     return () => cancelAnimationFrame(t);
   }, [e.items, e.getItem]);
-  const X = S(
+  const Q = w(
     (t) => {
       const n = r.current;
-      return n ? (n.scroller.jumpToElement(t), s()) : null;
+      return n ? (n.scroller.jumpToElement(t), u()) : null;
     },
-    [s]
-  ), Y = S(
+    [u]
+  ), U = w(
     (t) => {
       const n = r.current;
-      return n ? (n.scroller.handleScrollPercentage(t), s()) : null;
+      return n ? (n.scroller.handleScrollPercentage(t), u()) : null;
     },
-    [s]
-  ), G = S(() => {
+    [u]
+  ), Z = w(() => {
     const t = r.current;
-    return t ? (t.scroller.reset(), s()) : null;
-  }, [s]), J = S(() => {
+    return t ? (t.scroller.reset(), u()) : null;
+  }, [u]), x = w(() => {
     const t = r.current;
-    return t ? (t.scroller.clearAllCaches(), s()) : null;
-  }, [s]), q = E.current, k = !C.current && q != null ? q.length : null, j = w.current, v = d.current;
-  o.current !== j && (v.clear(), o.current = j);
-  const z = [];
-  return i.current.forEach((t, n) => {
-    if (k !== null && n >= k) {
-      v.delete(n);
+    return t ? (t.scroller.clearAllCaches(), u()) : null;
+  }, [u]), D = E.current, W = !R.current && D != null ? D.length : null, q = v.current, p = h.current;
+  c.current !== q && (p.clear(), c.current = q);
+  const k = [];
+  return f.current.forEach((t, n) => {
+    if (W !== null && n >= W) {
+      p.delete(n);
       return;
     }
-    const a = _(n);
-    let u = v.get(n);
-    (!u || u.item !== a || u.mount !== t.mount) && (u = {
-      item: a,
+    const l = B(n);
+    let a = p.get(n);
+    (!a || a.item !== l || a.mount !== t.mount) && (a = {
+      item: l,
       mount: t.mount,
-      node: ne(j(a, n), t.mount, String(n))
-    }, v.set(n, u)), z.push(u.node);
-  }), v.size > i.current.size && v.forEach((t, n) => {
-    i.current.has(n) || v.delete(n);
-  }), {
-    containerRef: l,
-    portals: z,
-    scroller: P,
-    render: s,
-    jumpToElement: X,
-    scrollToPercentage: Y,
-    reset: G,
-    recalculate: J
+      node: G(q(l, n), t.mount, String(n))
+    }, p.set(n, a)), k.push(a.node);
+  }), p.size > f.current.size && p.forEach((t, n) => {
+    f.current.has(n) || p.delete(n);
+  }), e.tableHeader != null && C.current && k.push(G(e.tableHeader, C.current, "cerious-thead")), {
+    containerRef: s,
+    portals: k,
+    scroller: H,
+    render: u,
+    jumpToElement: Q,
+    scrollToPercentage: U,
+    reset: Z,
+    recalculate: x
   };
 }
-function fe(e, l) {
-  const { className: r, style: i, "data-testid": d, children: o, ...g } = e, {
-    containerRef: N,
-    portals: P,
-    scroller: I,
-    render: w,
-    jumpToElement: E,
-    scrollToPercentage: C,
-    reset: T,
-    recalculate: p
-  } = ae(g);
-  return te(
-    l,
-    () => ({ scroller: I, render: w, jumpToElement: E, scrollToPercentage: C, reset: T, recalculate: p }),
-    [I, w, E, C, T, p]
-  ), /* @__PURE__ */ K(
+function ge(e, s) {
+  const { className: r, style: f, "data-testid": h, children: c, ...g } = e, {
+    containerRef: C,
+    portals: M,
+    scroller: A,
+    render: H,
+    jumpToElement: S,
+    scrollToPercentage: v,
+    reset: E,
+    recalculate: R
+  } = he(g);
+  return le(
+    s,
+    () => ({ scroller: A, render: H, jumpToElement: S, scrollToPercentage: v, reset: E, recalculate: R }),
+    [A, H, S, v, E, R]
+  ), /* @__PURE__ */ ee(
     "div",
     {
-      ref: N,
+      ref: C,
       className: r,
-      "data-testid": d,
-      style: { position: "relative", overflow: "hidden", ...i },
+      "data-testid": h,
+      style: { position: "relative", overflow: "hidden", ...f },
       children: [
-        o,
-        P
+        c,
+        M
       ]
     }
   );
 }
-const pe = ee(fe);
+const we = oe(ge);
 export {
-  pe as CeriousScroll,
-  we as CeriousScrollEngine,
-  ae as useCeriousScroll
+  we as CeriousScroll,
+  ye as CeriousScrollEngine,
+  he as useCeriousScroll
 };

package/dist/use-cerious-scroll.d.ts

@@ -10,6 +10,12 @@ export interface UseCeriousScrollOptions<TItem = unknown> {
     getItem?: (index: number) => TItem;
     /** Renders a single row. `item` is `undefined` when no data source is given. */
     renderItem: (item: TItem, index: number) => ReactNode;
+    /**
+     * Table mode only: declarative header content rendered into the engine's
+     * `<thead>` (provide a `<tr>` of `<th>`s). It lives in the same `<table>` as
+     * the rows, so columns align natively. Reactive — re-renders like any portal.
+     */
+    tableHeader?: ReactNode;
     /** Options forwarded to `new CeriousScroll(...)` (read once, at creation). */
     options?: CeriousScrollOptions;
     /** Automatically render after scroll/resize/data changes. Default: `true`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceriousdevtech/react-cerious-scroll",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "React bindings for CeriousScroll — high-performance virtual scrolling with O(1) memory and no height estimation",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -56,7 +56,7 @@
     "demo:build": "vite build --config demo/vite.config.ts"
   },
   "dependencies": {
-    "@ceriousdevtech/cerious-scroll": "^1.0.5"
+    "@ceriousdevtech/cerious-scroll": "^1.0.6"
   },
   "peerDependencies": {
     "react": ">=18 <20",