@ceriousdevtech/react-cerious-scroll 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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
+- Bumped `@ceriousdevtech/cerious-scroll` to `^1.0.5`. Consumers get the new wheel input classifier (trackpad / free-scroll mice apply input immediately, ratcheted wheel notches still ease smoothly), the new `wheel.wheelBehavior` option (`'auto' | 'immediate' | 'smooth'`), and a fix for horizontal wheel forwarding in layouts where `overflow-x: auto` lives on an ancestor of `[data-cerious-scroll-content]`.
+
 ## [1.0.3] - 2026-06-03
 
 ### 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 z=require("react/jsx-runtime"),r=require("react"),H=require("react-dom"),G=require("react-dom/server"),_=require("@ceriousdevtech/cerious-scroll"),V="data-cerious-scroll-content",J="data-cerious-scroll-row";function K(e){const l=e.querySelector(`[${V}]`);if(l)return l;const n=document.createElement("div");return n.setAttribute(V,""),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 Q(e,l){const n=u=>{const o=u.detail;o&&l({percentage:o.percentage,currentElement:o.currentElement,scrollOffset:o.scrollOffset,result:{element:o.result.element,offset:o.result.offset}})},a=u=>{const o=u.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",a),()=>{e.removeEventListener("cerious-viewport-change",n),e.removeEventListener("viewport-change",a)}}function U(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 D(e){var N;const l=r.useRef(null),n=r.useRef(null),a=r.useRef(new Map),u=r.useRef(null),[,o]=r.useReducer(t=>t+1,0),[q,O]=r.useState(null),S=r.useRef(e.renderItem),d=r.useRef(e.items??null),v=r.useRef(e.getItem),p=r.useRef(e.options),h=r.useRef(e.autoRender??!0),b=r.useRef(e.totalElements??null),g=r.useRef(e.onViewportChange),T=r.useRef(e.onMeasuredViewport),I=r.useRef(e.onReady);S.current=e.renderItem,d.current=e.items??null,v.current=e.getItem,p.current=e.options,h.current=e.autoRender??!0,b.current=e.totalElements??null,g.current=e.onViewportChange,T.current=e.onMeasuredViewport,I.current=e.onReady;const k=r.useCallback(t=>{const c=v.current;if(c)return c(t);const R=d.current;return R?R[t]:void 0},[]),s=r.useCallback(()=>{var y;const t=n.current;if(!t)return null;const{scroller:c,contentEl:R,container:C}=t,j=C.clientHeight||C.offsetHeight||0,w=[],i=(f,E)=>{const m=document.createElement("div");m.setAttribute(J,String(f)),m.innerHTML=G.renderToStaticMarkup(r.createElement(r.Fragment,null,S.current(k(f),f))),E.appendChild(m),a.current.set(f,{el:E,mount:m}),w.push(m)},A=c.renderViewport(j,R,i),M=new Set(c.getRenderedIndices());return a.current.forEach((f,E)=>{M.has(E)||a.current.delete(E)}),w.forEach(f=>{f.textContent=""}),H.flushSync(o),(y=T.current)==null||y.call(T,A),A},[]),B=e.totalElements??((N=e.items)==null?void 0:N.length)??null;r.useEffect(()=>{var y,f;const t=l.current;if(!t)return;const c=K(t),R=p.current??{},C=R.onScroll,j={...R,onScroll:()=>{C==null||C(),h.current&&s()}},w=U(b.current,((y=d.current)==null?void 0:y.length)??null),i=new _.CeriousScroll(t,w,j);u.current&&(i.currentElement=Math.min(u.current.currentElement,w-1),i.scrollOffset=u.current.scrollOffset,u.current=null),n.current={scroller:i,contentEl:c,container:t},O(i);const A=Q(t,E=>{var m;(m=g.current)==null||m.call(g,E)});(f=I.current)==null||f.call(I,i);let M=0;return h.current&&(M=requestAnimationFrame(()=>s())),()=>{cancelAnimationFrame(M),A(),u.current={currentElement:i.currentElement,scrollOffset:i.scrollOffset},a.current.clear(),c.textContent="",i.detachScrollbar(t),i.dispose(),n.current=null,O(null)}},[B,s]),r.useEffect(()=>{if(!n.current||!h.current)return;const t=requestAnimationFrame(()=>s());return()=>cancelAnimationFrame(t)},[e.items,e.getItem]);const W=r.useCallback(t=>{const c=n.current;return c?(c.scroller.jumpToElement(t),s()):null},[s]),X=r.useCallback(t=>{const c=n.current;return c?(c.scroller.handleScrollPercentage(t),s()):null},[s]),Y=r.useCallback(()=>{const t=n.current;return t?(t.scroller.reset(),s()):null},[s]),$=r.useCallback(()=>{const t=n.current;return t?(t.scroller.clearAllCaches(),s()):null},[s]),P=d.current,F=!v.current&&P!=null?P.length:null,L=[];return a.current.forEach((t,c)=>{F!==null&&c>=F||L.push(H.createPortal(S.current(k(c),c),t.mount,String(c)))}),{containerRef:l,portals:L,scroller:q,render:s,jumpToElement:W,scrollToPercentage:X,reset:Y,recalculate:$}}function Z(e,l){const{className:n,style:a,"data-testid":u,children:o,...q}=e,{containerRef:O,portals:S,scroller:d,render:v,jumpToElement:p,scrollToPercentage:h,reset:b,recalculate:g}=D(q);return r.useImperativeHandle(l,()=>({scroller:d,render:v,jumpToElement:p,scrollToPercentage:h,reset:b,recalculate:g}),[d,v,p,h,b,g]),z.jsxs("div",{ref:O,className:n,"data-testid":u,style:{position:"relative",overflow:"hidden",...a},children:[o,S]})}const x=r.forwardRef(Z);Object.defineProperty(exports,"CeriousScrollEngine",{enumerable:!0,get:()=>_.CeriousScroll});exports.CeriousScroll=x;exports.useCeriousScroll=D;
+"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,163 +1,185 @@
-import { jsxs as Y } from "react/jsx-runtime";
-import { useRef as s, useReducer as z, useState as G, useCallback as R, useEffect as _, createElement as J, Fragment as K, forwardRef as Q, useImperativeHandle as U } from "react";
-import { flushSync as Z, createPortal as x } from "react-dom";
-import { renderToStaticMarkup as ee } from "react-dom/server";
-import { CeriousScroll as te } from "@ceriousdevtech/cerious-scroll";
-import { CeriousScroll as Ee } from "@ceriousdevtech/cerious-scroll";
-const k = "data-cerious-scroll-content", re = "data-cerious-scroll-row";
-function ne(e) {
-  const c = e.querySelector(`[${k}]`);
-  if (c) return c;
+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(k, ""), 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 oe(e, c) {
-  const r = (u) => {
-    const o = u.detail;
-    o && c({
-      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 }
     });
-  }, a = (u) => {
-    const o = u.detail;
-    o && c({
-      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", a), () => {
-    e.removeEventListener("cerious-viewport-change", r), e.removeEventListener("viewport-change", a);
+  return e.addEventListener("cerious-viewport-change", r), e.addEventListener("viewport-change", f), () => {
+    e.removeEventListener("cerious-viewport-change", r), e.removeEventListener("viewport-change", f);
   };
 }
-function ce(e, c) {
-  const r = typeof e == "number" ? e : typeof c == "number" ? c : 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 le(e) {
-  var q;
-  const c = s(null), r = s(null), a = s(/* @__PURE__ */ new Map()), u = s(null), [, o] = z((t) => t + 1, 0), [L, O] = G(null), S = s(e.renderItem), d = s(e.items ?? null), v = s(e.getItem), C = s(e.options), h = s(e.autoRender ?? !0), T = s(e.totalElements ?? null), g = s(e.onViewportChange), b = s(e.onMeasuredViewport), A = s(e.onReady);
-  S.current = e.renderItem, d.current = e.items ?? null, v.current = e.getItem, C.current = e.options, h.current = e.autoRender ?? !0, T.current = e.totalElements ?? null, g.current = e.onViewportChange, b.current = e.onMeasuredViewport, A.current = e.onReady;
-  const P = R((t) => {
-    const n = v.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 E = d.current;
-    return E ? E[t] : void 0;
-  }, []), l = R(() => {
-    var I;
+    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: E, container: w } = t, N = w.clientHeight || w.offsetHeight || 0, y = [], i = (f, p) => {
-      const m = document.createElement("div");
-      m.setAttribute(re, String(f)), m.innerHTML = ee(
-        J(K, null, S.current(P(f), f))
-      ), p.appendChild(m), a.current.set(f, { el: p, mount: m }), y.push(m);
-    }, M = n.renderViewport(N, E, i), F = new Set(n.getRenderedIndices());
-    return a.current.forEach((f, p) => {
-      F.has(p) || a.current.delete(p);
-    }), y.forEach((f) => {
-      f.textContent = "";
-    }), Z(o), (I = b.current) == null || I.call(b, M), M;
-  }, []), $ = e.totalElements ?? ((q = e.items) == null ? void 0 : q.length) ?? null;
-  _(() => {
-    var I, f;
-    const t = c.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 = ne(t), E = C.current ?? {}, w = E.onScroll, N = {
-      ...E,
+    const n = fe(t), l = _.current ?? {}, a = l.onScroll, j = {
+      ...l,
       onScroll: () => {
-        w == null || w(), h.current && l();
+        a == null || a(), F.current && u();
       }
-    }, y = ce(T.current, ((I = d.current) == null ? void 0 : I.length) ?? null), i = new te(t, y, N);
-    u.current && (i.currentElement = Math.min(u.current.currentElement, y - 1), i.scrollOffset = u.current.scrollOffset, u.current = null), r.current = { scroller: i, contentEl: n, container: t }, O(i);
-    const M = oe(t, (p) => {
-      var m;
-      (m = g.current) == null || m.call(g, p);
+    };
+    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);
     });
-    (f = A.current) == null || f.call(A, i);
-    let F = 0;
-    return h.current && (F = requestAnimationFrame(() => l())), () => {
-      cancelAnimationFrame(F), M(), u.current = {
-        currentElement: i.currentElement,
-        scrollOffset: i.scrollOffset
-      }, a.current.clear(), n.textContent = "", i.detachScrollbar(t), i.dispose(), r.current = null, O(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);
     };
-  }, [$, l]), _(() => {
-    if (!r.current || !h.current) return;
-    const t = requestAnimationFrame(() => l());
+  }, [K, u]), Y(() => {
+    if (!r.current || !F.current) return;
+    const t = requestAnimationFrame(() => u());
     return () => cancelAnimationFrame(t);
   }, [e.items, e.getItem]);
-  const B = R(
+  const Q = w(
     (t) => {
       const n = r.current;
-      return n ? (n.scroller.jumpToElement(t), l()) : null;
+      return n ? (n.scroller.jumpToElement(t), u()) : null;
     },
-    [l]
-  ), D = R(
+    [u]
+  ), U = w(
     (t) => {
       const n = r.current;
-      return n ? (n.scroller.handleScrollPercentage(t), l()) : null;
+      return n ? (n.scroller.handleScrollPercentage(t), u()) : null;
     },
-    [l]
-  ), W = R(() => {
+    [u]
+  ), Z = w(() => {
     const t = r.current;
-    return t ? (t.scroller.reset(), l()) : null;
-  }, [l]), X = R(() => {
+    return t ? (t.scroller.reset(), u()) : null;
+  }, [u]), x = w(() => {
     const t = r.current;
-    return t ? (t.scroller.clearAllCaches(), l()) : null;
-  }, [l]), j = d.current, H = !v.current && j != null ? j.length : null, V = [];
-  return a.current.forEach((t, n) => {
-    H !== null && n >= H || V.push(
-      x(S.current(P(n), n), t.mount, String(n))
-    );
-  }), {
-    containerRef: c,
-    portals: V,
-    scroller: L,
-    render: l,
-    jumpToElement: B,
-    scrollToPercentage: D,
-    reset: W,
-    recalculate: X
+    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 l = B(n);
+    let a = p.get(n);
+    (!a || a.item !== l || a.mount !== t.mount) && (a = {
+      item: l,
+      mount: t.mount,
+      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 se(e, c) {
-  const { className: r, style: a, "data-testid": u, children: o, ...L } = e, {
-    containerRef: O,
-    portals: S,
-    scroller: d,
-    render: v,
-    jumpToElement: C,
-    scrollToPercentage: h,
-    reset: T,
-    recalculate: g
-  } = le(L);
-  return U(
-    c,
-    () => ({ scroller: d, render: v, jumpToElement: C, scrollToPercentage: h, reset: T, recalculate: g }),
-    [d, v, C, h, T, g]
-  ), /* @__PURE__ */ Y(
+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: O,
+      ref: C,
       className: r,
-      "data-testid": u,
-      style: { position: "relative", overflow: "hidden", ...a },
+      "data-testid": h,
+      style: { position: "relative", overflow: "hidden", ...f },
       children: [
-        o,
-        S
+        c,
+        M
       ]
     }
   );
 }
-const de = Q(se);
+const we = oe(ge);
 export {
-  de as CeriousScroll,
-  Ee as CeriousScrollEngine,
-  le 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.3",
+  "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.4"
+    "@ceriousdevtech/cerious-scroll": "^1.0.6"
   },
   "peerDependencies": {
     "react": ">=18 <20",