@ceriousdevtech/vue-cerious-scroll 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to vue-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>`. Each row renders into its own `display: contents` wrapper, isolating Vue's renderer from the engine's `<tr>` recycling (so a fast scroll can't tear nodes out from under Vue) while the cells still lay out as the row's columns.
+- **`#header` slot**. Declarative header (a `<tr>` of `<th>`s) rendered into the engine's `<thead>` in its own reactive effect — same `<table>` as the rows, so columns align natively, and interactive headers (sort state, etc.) update on their own.
+
+### 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

@@ -113,8 +113,9 @@ const { containerRef } = useCeriousScroll({
 | `autoRender` | `boolean` | Re-render on scroll/resize/data changes. Default `true`. |
 
 The row is provided by the **`#item` scoped slot** (`{ item, index }`) or the
-`render-item` prop. Apply `class` / `style` directly to the component — they fall
-through onto the scroll container (set a height!).
+`render-item` prop. In table mode, a **`#header` slot** renders the `<thead>` row
+(see [Table layout](#table-layout)). Apply `class` / `style` directly to the
+component — they fall through onto the scroll container (set a height!).
 
 ### Events
 
@@ -138,6 +139,36 @@ const scroll = ref<InstanceType<typeof CeriousScroll> | null>(null);
 
 ---
 
+## Table layout
+
+Pass `:options="{ layout: 'table' }"` to render real `<table>` / `<tr>` / `<td>` rows with a frozen header and native column alignment. The `#item` slot returns the row's `<td>` cells; a `#header` slot provides the (declarative, reactive) `<thead>` row:
+
+```vue
+<CeriousScroll
+  class="my-scroll"
+  :total-elements="100000"
+  :get-item="(i) => i"
+  :options="{ layout: 'table', table: { tableClassName: 'my-table', autoSizeColumns: true } }"
+>
+  <template #header>
+    <tr><th v-for="c in columns" :key="c.key">{{ c.label }}</th></tr>
+  </template>
+
+  <template #item="{ item: index }">
+    <td>{{ row(index).id }}</td>
+    <td>{{ row(index).name }}</td>
+    <td>{{ row(index).email }}</td>
+  </template>
+</CeriousScroll>
+```
+
+- The **`#header` slot** renders into the engine's `<thead>` (same `<table>` as the rows → native column alignment, frozen header) and stays reactive.
+- The **`#item` slot must return `<td>`s**. They render into the row's `<tr>` via a `display: contents` wrapper that isolates Vue's renderer from the engine's row recycling.
+- **`table.autoSizeColumns`** measures column widths once and pins them (auto-sized + stable); 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 Vue's synchronous `render()`

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("vue"),A=require("@ceriousdevtech/cerious-scroll"),V="data-cerious-scroll-content",N="data-cerious-scroll-row";function _(e){const s=e.querySelector(`[${V}]`);if(s)return s;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,s){const n=l=>{const r=l.detail;r&&s({percentage:r.percentage,currentElement:r.currentElement,scrollOffset:r.scrollOffset,result:{element:r.result.element,offset:r.result.offset}})},f=l=>{const r=l.detail;r&&s({percentage:r.percentage,currentElement:r.element,scrollOffset:r.scrollOffset,result:{element:r.element,offset:r.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 I(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 O;const s=(O=o.getCurrentInstance())==null?void 0:O.appContext,n=o.ref(null),f=o.shallowRef(null);let l=null;const r=new Map;let c=null;const C=()=>o.toValue(e.autoRender)??!0,y=t=>{if(e.getItem)return e.getItem(t);const u=o.toValue(e.items);return u?u[t]:void 0},M=(t,u)=>{const i=s??null,m=o.effectScope(!0);return m.run(()=>o.watchEffect(()=>{const E=e.renderItem(y(t),t),d=Array.isArray(E)?E:[E];for(const w of d)o.isVNode(w)&&(w.appContext=i);const a=o.h(o.Fragment,d);a.appContext=i,o.render(a,u)},{flush:"sync"})),()=>m.stop()},b=t=>{t.stop(),o.render(null,t.mount),t.mount.remove()},h=()=>{var w;if(!l)return null;const{scroller:t,contentEl:u,container:i}=l,m=i.clientHeight||i.offsetHeight||0,E=(g,v)=>{const p=document.createElement("div");p.setAttribute(N,String(g)),v.appendChild(p);const S=M(g,p);r.set(g,{el:v,mount:p,stop:S})},d=t.renderViewport(m,u,E),a=new Set(t.getRenderedIndices());return r.forEach((g,v)=>{a.has(v)||(b(g),r.delete(v))}),(w=e.onMeasuredViewport)==null||w.call(e,d),d},R=t=>{if(!l)return;const u=l;l=null,u.unsubscribe(),t&&(c={currentElement:u.scroller.currentElement,scrollOffset:u.scroller.scrollOffset}),r.forEach(i=>b(i)),r.clear(),u.contentEl.textContent="",u.scroller.detachScrollbar(u.container),u.scroller.dispose(),f.value=null},T=t=>{var g,v;const u=_(t),i=e.options??{},m=i.onScroll,E={...i,onScroll:()=>{m==null||m(),C()&&h()}},d=I(o.toValue(e.totalElements),((g=o.toValue(e.items))==null?void 0:g.length)??null),a=new A.CeriousScroll(t,d,E);c&&(a.currentElement=Math.min(c.currentElement,d-1),a.scrollOffset=c.scrollOffset,c=null);const w=q(t,p=>{var S;(S=e.onViewportChange)==null||S.call(e,p)});l={scroller:a,contentEl:u,container:t,unsubscribe:w},f.value=a,(v=e.onReady)==null||v.call(e,a),C()&&requestAnimationFrame(()=>h())},P=()=>{R(!0);const t=n.value;t&&T(t)};return o.onMounted(()=>{const t=n.value;t&&T(t)}),o.onBeforeUnmount(()=>{R(!1)}),o.watch(()=>[o.toValue(e.totalElements),o.toValue(e.items)],()=>{var u;if(!l)return;const t=I(o.toValue(e.totalElements),((u=o.toValue(e.items))==null?void 0:u.length)??null);l.scroller.totalElements!==t&&P()}),{containerRef:n,scroller:f,render:h,jumpToElement:t=>l?(l.scroller.jumpToElement(t),h()):null,scrollToPercentage:t=>l?(l.scroller.handleScrollPercentage(t),h()):null,reset:()=>l?(l.scroller.reset(),h()):null,recalculate:()=>l?(l.scroller.clearAllCaches(),h()):null}}const F=o.defineComponent({name:"CeriousScroll",props:{totalElements:{type:Number,default:null},items:{type:Array,default:null},getItem:{type:Function,default:void 0},renderItem:{type:Function,default:void 0},options:{type:Object,default:void 0},autoRender:{type:Boolean,default:!0}},emits:{"viewport-change":e=>!0,"measured-viewport":e=>!0,ready:e=>!0},setup(e,{slots:s,emit:n,expose:f}){const l=(c,C)=>{var y;return e.renderItem?e.renderItem(c,C):(y=s.item)==null?void 0:y.call(s,{item:c,index:C})},r=j({totalElements:()=>e.totalElements,items:()=>e.items,getItem:e.getItem?c=>e.getItem(c):void 0,renderItem:l,options:e.options,autoRender:()=>e.autoRender,onViewportChange:c=>n("viewport-change",c),onMeasuredViewport:c=>n("measured-viewport",c),onReady:c=>n("ready",c)});return f({scroller:r.scroller,render:r.render,jumpToElement:r.jumpToElement,scrollToPercentage:r.scrollToPercentage,reset:r.reset,recalculate:r.recalculate}),()=>{var c;return o.h("div",{ref:r.containerRef,style:{position:"relative",overflow:"hidden"}},(c=s.default)==null?void 0:c.call(s))}}});Object.defineProperty(exports,"CeriousScrollEngine",{enumerable:!0,get:()=>A.CeriousScroll});exports.CeriousScroll=F;exports.useCeriousScroll=j;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("vue"),N=require("@ceriousdevtech/cerious-scroll"),M="data-cerious-scroll-content",q="data-cerious-scroll-row";function L(e){const u=e.querySelector(`[${M}]`);if(u)return u;const o=document.createElement("div");return o.setAttribute(M,""),o.style.position="relative",o.style.width="100%",o.style.height="100%",o.style.overflowY="clip",o.style.overflowX="auto",e.appendChild(o),o}function B(e,u){const o=l=>{const n=l.detail;n&&u({percentage:n.percentage,currentElement:n.currentElement,scrollOffset:n.scrollOffset,result:{element:n.result.element,offset:n.result.offset}})},g=l=>{const n=l.detail;n&&u({percentage:n.percentage,currentElement:n.element,scrollOffset:n.scrollOffset,result:{element:n.element,offset:n.scrollOffset}})};return e.addEventListener("cerious-viewport-change",o),e.addEventListener("viewport-change",g),()=>{e.removeEventListener("cerious-viewport-change",o),e.removeEventListener("viewport-change",g)}}function j(e,u){const o=typeof e=="number"?e:typeof u=="number"?u:void 0;if(o===void 0||Number.isNaN(o))throw new Error("useCeriousScroll: provide `totalElements` or `items`.");return Math.max(1,Math.floor(o))}function P(e){var I,A;const u=(I=r.getCurrentInstance())==null?void 0:I.appContext,o=r.ref(null),g=r.shallowRef(null);let l=null;const n=new Map;let s=null;const b=((A=e.options)==null?void 0:A.layout)==="table";let d=null;const H=t=>{if(!e.renderHeader)return;d==null||d();const c=u??null,a=r.effectScope(!0);a.run(()=>r.watchEffect(()=>{const f=e.renderHeader(),m=Array.isArray(f)?f:[f];for(const i of m)r.isVNode(i)&&(i.appContext=c);const h=r.h(r.Fragment,m);h.appContext=c,r.render(h,t)},{flush:"sync"})),d=()=>a.stop()},R=()=>r.toValue(e.autoRender)??!0,x=t=>{if(e.getItem)return e.getItem(t);const c=r.toValue(e.items);return c?c[t]:void 0},F=(t,c)=>{const a=u??null,f=r.effectScope(!0);return f.run(()=>r.watchEffect(()=>{const m=e.renderItem(x(t),t),h=Array.isArray(m)?m:[m];for(const p of h)r.isVNode(p)&&(p.appContext=a);const i=r.h(r.Fragment,h);i.appContext=a,r.render(i,c)},{flush:"sync"})),()=>f.stop()},T=t=>{t.stop(),r.render(null,t.mount),t.mount.remove()},y=()=>{var p;if(!l)return null;const{scroller:t,contentEl:c,container:a}=l,f=a.clientHeight||a.offsetHeight||0,m=(v,E)=>{const w=document.createElement("div");b&&(w.style.display="contents"),w.setAttribute(q,String(v)),E.appendChild(w);const C=F(v,w);n.set(v,{el:E,mount:w,stop:C})},h=t.renderViewport(f,c,m),i=new Set(t.getRenderedIndices());return n.forEach((v,E)=>{i.has(E)||(T(v),n.delete(E))}),(p=e.onMeasuredViewport)==null||p.call(e,h),h},V=t=>{if(!l)return;const c=l;l=null,c.unsubscribe(),t&&(s={currentElement:c.scroller.currentElement,scrollOffset:c.scroller.scrollOffset}),n.forEach(a=>T(a)),n.clear(),d==null||d(),d=null,c.contentEl.textContent="",c.scroller.detachScrollbar(c.container),c.scroller.dispose(),g.value=null},O=t=>{var v,E,w;const c=L(t),a=e.options??{},f=a.onScroll,m={...a,onScroll:()=>{f==null||f(),R()&&y()}};if(b&&e.renderHeader){const C=(v=a.table)==null?void 0:v.header;m.table={...a.table,header:S=>{C==null||C(S),H(S)}}}const h=j(r.toValue(e.totalElements),((E=r.toValue(e.items))==null?void 0:E.length)??null),i=new N.CeriousScroll(t,h,m);s&&(i.currentElement=Math.min(s.currentElement,h-1),i.scrollOffset=s.scrollOffset,s=null);const p=B(t,C=>{var S;(S=e.onViewportChange)==null||S.call(e,C)});l={scroller:i,contentEl:c,container:t,unsubscribe:p},g.value=i,(w=e.onReady)==null||w.call(e,i),R()&&requestAnimationFrame(()=>y())},_=()=>{V(!0);const t=o.value;t&&O(t)};return r.onMounted(()=>{const t=o.value;t&&O(t)}),r.onBeforeUnmount(()=>{V(!1)}),r.watch(()=>[r.toValue(e.totalElements),r.toValue(e.items)],()=>{var c;if(!l)return;const t=j(r.toValue(e.totalElements),((c=r.toValue(e.items))==null?void 0:c.length)??null);l.scroller.totalElements!==t&&_()}),{containerRef:o,scroller:g,render:y,jumpToElement:t=>l?(l.scroller.jumpToElement(t),y()):null,scrollToPercentage:t=>l?(l.scroller.handleScrollPercentage(t),y()):null,reset:()=>l?(l.scroller.reset(),y()):null,recalculate:()=>l?(l.scroller.clearAllCaches(),y()):null}}const U=r.defineComponent({name:"CeriousScroll",props:{totalElements:{type:Number,default:null},items:{type:Array,default:null},getItem:{type:Function,default:void 0},renderItem:{type:Function,default:void 0},options:{type:Object,default:void 0},autoRender:{type:Boolean,default:!0}},emits:{"viewport-change":e=>!0,"measured-viewport":e=>!0,ready:e=>!0},setup(e,{slots:u,emit:o,expose:g}){const l=(s,b)=>{var d;return e.renderItem?e.renderItem(s,b):(d=u.item)==null?void 0:d.call(u,{item:s,index:b})},n=P({totalElements:()=>e.totalElements,items:()=>e.items,getItem:e.getItem?s=>e.getItem(s):void 0,renderItem:l,renderHeader:u.header?()=>u.header():void 0,options:e.options,autoRender:()=>e.autoRender,onViewportChange:s=>o("viewport-change",s),onMeasuredViewport:s=>o("measured-viewport",s),onReady:s=>o("ready",s)});return g({scroller:n.scroller,render:n.render,jumpToElement:n.jumpToElement,scrollToPercentage:n.scrollToPercentage,reset:n.reset,recalculate:n.recalculate}),()=>{var s;return r.h("div",{ref:n.containerRef,style:{position:"relative",overflow:"hidden"}},(s=u.default)==null?void 0:s.call(u))}}});Object.defineProperty(exports,"CeriousScrollEngine",{enumerable:!0,get:()=>N.CeriousScroll});exports.CeriousScroll=U;exports.useCeriousScroll=P;

package/dist/index.js

@@ -1,129 +1,156 @@
-import { getCurrentInstance as P, ref as _, shallowRef as x, onMounted as F, onBeforeUnmount as L, watch as $, toValue as v, render as O, effectScope as q, watchEffect as B, isVNode as H, h as M, Fragment as U, defineComponent as W } from "vue";
-import { CeriousScroll as X } from "@ceriousdevtech/cerious-scroll";
-import { CeriousScroll as oe } from "@ceriousdevtech/cerious-scroll";
-const A = "data-cerious-scroll-content", Y = "data-cerious-scroll-row";
-function z(e) {
-  const s = e.querySelector(`[${A}]`);
-  if (s) return s;
+import { getCurrentInstance as U, ref as W, shallowRef as X, onMounted as Y, onBeforeUnmount as z, watch as D, toValue as w, effectScope as N, watchEffect as j, isVNode as H, h as I, Fragment as P, render as T, defineComponent as G } from "vue";
+import { CeriousScroll as J } from "@ceriousdevtech/cerious-scroll";
+import { CeriousScroll as ie } from "@ceriousdevtech/cerious-scroll";
+const _ = "data-cerious-scroll-content", K = "data-cerious-scroll-row";
+function Q(e) {
+  const c = e.querySelector(`[${_}]`);
+  if (c) return c;
   const n = document.createElement("div");
-  return n.setAttribute(A, ""), n.style.position = "relative", n.style.width = "100%", n.style.height = "100%", n.style.overflowY = "clip", n.style.overflowX = "auto", e.appendChild(n), n;
+  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 D(e, s) {
+function Z(e, c) {
   const n = (o) => {
     const r = o.detail;
-    r && s({
+    r && c({
       percentage: r.percentage,
       currentElement: r.currentElement,
       scrollOffset: r.scrollOffset,
       result: { element: r.result.element, offset: r.result.offset }
     });
-  }, a = (o) => {
+  }, h = (o) => {
     const r = o.detail;
-    r && s({
+    r && c({
       percentage: r.percentage,
       currentElement: r.element,
       scrollOffset: r.scrollOffset,
       result: { element: r.element, offset: r.scrollOffset }
     });
   };
-  return e.addEventListener("cerious-viewport-change", n), e.addEventListener("viewport-change", a), () => {
-    e.removeEventListener("cerious-viewport-change", n), e.removeEventListener("viewport-change", a);
+  return e.addEventListener("cerious-viewport-change", n), e.addEventListener("viewport-change", h), () => {
+    e.removeEventListener("cerious-viewport-change", n), e.removeEventListener("viewport-change", h);
   };
 }
-function V(e, s) {
-  const n = typeof e == "number" ? e : typeof s == "number" ? s : void 0;
+function F(e, c) {
+  const n = typeof e == "number" ? e : typeof c == "number" ? c : 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 G(e) {
-  var I;
-  const s = (I = P()) == null ? void 0 : I.appContext, n = _(null), a = x(null);
+function k(e) {
+  var V, x;
+  const c = (V = U()) == null ? void 0 : V.appContext, n = W(null), h = X(null);
   let o = null;
   const r = /* @__PURE__ */ new Map();
-  let l = null;
-  const C = () => v(e.autoRender) ?? !0, y = (t) => {
+  let s = null;
+  const b = ((x = e.options) == null ? void 0 : x.layout) === "table";
+  let f = null;
+  const L = (t) => {
+    if (!e.renderHeader) return;
+    f == null || f();
+    const l = c ?? null, u = N(!0);
+    u.run(
+      () => j(
+        () => {
+          const a = e.renderHeader(), d = Array.isArray(a) ? a : [a];
+          for (const i of d) H(i) && (i.appContext = l);
+          const m = I(P, d);
+          m.appContext = l, T(m, t);
+        },
+        { flush: "sync" }
+      )
+    ), f = () => u.stop();
+  }, O = () => w(e.autoRender) ?? !0, $ = (t) => {
     if (e.getItem) return e.getItem(t);
-    const c = v(e.items);
-    return c ? c[t] : void 0;
-  }, N = (t, c) => {
-    const u = s ?? null, f = q(!0);
-    return f.run(
-      () => B(
+    const l = w(e.items);
+    return l ? l[t] : void 0;
+  }, q = (t, l) => {
+    const u = c ?? null, a = N(!0);
+    return a.run(
+      () => j(
         () => {
-          const E = e.renderItem(y(t), t), m = Array.isArray(E) ? E : [E];
-          for (const w of m)
-            H(w) && (w.appContext = u);
-          const i = M(U, m);
-          i.appContext = u, O(i, c);
+          const d = e.renderItem($(t), t), m = Array.isArray(d) ? d : [d];
+          for (const y of m)
+            H(y) && (y.appContext = u);
+          const i = I(P, m);
+          i.appContext = u, T(i, l);
         },
         { flush: "sync" }
       )
-    ), () => f.stop();
+    ), () => a.stop();
   }, S = (t) => {
-    t.stop(), O(null, t.mount), t.mount.remove();
-  }, h = () => {
-    var w;
+    t.stop(), T(null, t.mount), t.mount.remove();
+  }, p = () => {
+    var y;
     if (!o) return null;
-    const { scroller: t, contentEl: c, container: u } = o, f = u.clientHeight || u.offsetHeight || 0, E = (d, g) => {
-      const p = document.createElement("div");
-      p.setAttribute(Y, String(d)), g.appendChild(p);
-      const R = N(d, p);
-      r.set(d, { el: g, mount: p, stop: R });
-    }, m = t.renderViewport(f, c, E), i = new Set(t.getRenderedIndices());
-    return r.forEach((d, g) => {
-      i.has(g) || (S(d), r.delete(g));
-    }), (w = e.onMeasuredViewport) == null || w.call(e, m), m;
-  }, T = (t) => {
+    const { scroller: t, contentEl: l, container: u } = o, a = u.clientHeight || u.offsetHeight || 0, d = (v, g) => {
+      const E = document.createElement("div");
+      b && (E.style.display = "contents"), E.setAttribute(K, String(v)), g.appendChild(E);
+      const C = q(v, E);
+      r.set(v, { el: g, mount: E, stop: C });
+    }, m = t.renderViewport(a, l, d), i = new Set(t.getRenderedIndices());
+    return r.forEach((v, g) => {
+      i.has(g) || (S(v), r.delete(g));
+    }), (y = e.onMeasuredViewport) == null || y.call(e, m), m;
+  }, A = (t) => {
     if (!o) return;
-    const c = o;
-    o = null, c.unsubscribe(), t && (l = {
-      currentElement: c.scroller.currentElement,
-      scrollOffset: c.scroller.scrollOffset
-    }), r.forEach((u) => S(u)), r.clear(), c.contentEl.textContent = "", c.scroller.detachScrollbar(c.container), c.scroller.dispose(), a.value = null;
-  }, b = (t) => {
-    var d, g;
-    const c = z(t), u = e.options ?? {}, f = u.onScroll, E = {
+    const l = o;
+    o = null, l.unsubscribe(), t && (s = {
+      currentElement: l.scroller.currentElement,
+      scrollOffset: l.scroller.scrollOffset
+    }), r.forEach((u) => S(u)), r.clear(), f == null || f(), f = null, l.contentEl.textContent = "", l.scroller.detachScrollbar(l.container), l.scroller.dispose(), h.value = null;
+  }, M = (t) => {
+    var v, g, E;
+    const l = Q(t), u = e.options ?? {}, a = u.onScroll, d = {
       ...u,
       onScroll: () => {
-        f == null || f(), C() && h();
+        a == null || a(), O() && p();
       }
-    }, m = V(v(e.totalElements), ((d = v(e.items)) == null ? void 0 : d.length) ?? null), i = new X(t, m, E);
-    l && (i.currentElement = Math.min(l.currentElement, m - 1), i.scrollOffset = l.scrollOffset, l = null);
-    const w = D(t, (p) => {
+    };
+    if (b && e.renderHeader) {
+      const C = (v = u.table) == null ? void 0 : v.header;
+      d.table = {
+        ...u.table,
+        header: (R) => {
+          C == null || C(R), L(R);
+        }
+      };
+    }
+    const m = F(w(e.totalElements), ((g = w(e.items)) == null ? void 0 : g.length) ?? null), i = new J(t, m, d);
+    s && (i.currentElement = Math.min(s.currentElement, m - 1), i.scrollOffset = s.scrollOffset, s = null);
+    const y = Z(t, (C) => {
       var R;
-      (R = e.onViewportChange) == null || R.call(e, p);
+      (R = e.onViewportChange) == null || R.call(e, C);
     });
-    o = { scroller: i, contentEl: c, container: t, unsubscribe: w }, a.value = i, (g = e.onReady) == null || g.call(e, i), C() && requestAnimationFrame(() => h());
-  }, j = () => {
-    T(!0);
+    o = { scroller: i, contentEl: l, container: t, unsubscribe: y }, h.value = i, (E = e.onReady) == null || E.call(e, i), O() && requestAnimationFrame(() => p());
+  }, B = () => {
+    A(!0);
     const t = n.value;
-    t && b(t);
+    t && M(t);
   };
-  return F(() => {
+  return Y(() => {
     const t = n.value;
-    t && b(t);
-  }), L(() => {
-    T(!1);
-  }), $(
-    () => [v(e.totalElements), v(e.items)],
+    t && M(t);
+  }), z(() => {
+    A(!1);
+  }), D(
+    () => [w(e.totalElements), w(e.items)],
     () => {
-      var c;
+      var l;
       if (!o) return;
-      const t = V(v(e.totalElements), ((c = v(e.items)) == null ? void 0 : c.length) ?? null);
-      o.scroller.totalElements !== t && j();
+      const t = F(w(e.totalElements), ((l = w(e.items)) == null ? void 0 : l.length) ?? null);
+      o.scroller.totalElements !== t && B();
     }
   ), {
     containerRef: n,
-    scroller: a,
-    render: h,
-    jumpToElement: (t) => o ? (o.scroller.jumpToElement(t), h()) : null,
-    scrollToPercentage: (t) => o ? (o.scroller.handleScrollPercentage(t), h()) : null,
-    reset: () => o ? (o.scroller.reset(), h()) : null,
-    recalculate: () => o ? (o.scroller.clearAllCaches(), h()) : null
+    scroller: h,
+    render: p,
+    jumpToElement: (t) => o ? (o.scroller.jumpToElement(t), p()) : null,
+    scrollToPercentage: (t) => o ? (o.scroller.handleScrollPercentage(t), p()) : null,
+    reset: () => o ? (o.scroller.reset(), p()) : null,
+    recalculate: () => o ? (o.scroller.clearAllCaches(), p()) : null
   };
 }
-const te = W({
+const ce = G({
   name: "CeriousScroll",
   props: {
     /** Total item count. Falls back to `items.length` when omitted. */
@@ -150,24 +177,27 @@ const te = W({
     /** Emitted once the underlying engine instance is ready (and after recreation). */
     ready: (e) => !0
   },
-  setup(e, { slots: s, emit: n, expose: a }) {
-    const o = (l, C) => {
-      var y;
-      return e.renderItem ? e.renderItem(l, C) : (y = s.item) == null ? void 0 : y.call(s, { item: l, index: C });
-    }, r = G({
+  setup(e, { slots: c, emit: n, expose: h }) {
+    const o = (s, b) => {
+      var f;
+      return e.renderItem ? e.renderItem(s, b) : (f = c.item) == null ? void 0 : f.call(c, { item: s, index: b });
+    }, r = k({
       totalElements: () => e.totalElements,
       items: () => e.items,
-      getItem: e.getItem ? (l) => e.getItem(l) : void 0,
+      getItem: e.getItem ? (s) => e.getItem(s) : void 0,
       renderItem: o,
+      // Table mode: declarative header. Render the `#header` slot (a <tr> of
+      // <th>s) into the engine's <thead>. `undefined` when no slot is provided.
+      renderHeader: c.header ? () => c.header() : void 0,
       // Engine options are consumed at creation; reading the prop once matches
       // that contract (remount via `:key` to apply new engine options).
       options: e.options,
       autoRender: () => e.autoRender,
-      onViewportChange: (l) => n("viewport-change", l),
-      onMeasuredViewport: (l) => n("measured-viewport", l),
-      onReady: (l) => n("ready", l)
+      onViewportChange: (s) => n("viewport-change", s),
+      onMeasuredViewport: (s) => n("measured-viewport", s),
+      onReady: (s) => n("ready", s)
     });
-    return a({
+    return h({
       /** The underlying engine instance (`null` before mount). */
       scroller: r.scroller,
       render: r.render,
@@ -176,21 +206,21 @@ const te = W({
       reset: r.reset,
       recalculate: r.recalculate
     }), () => {
-      var l;
-      return M(
+      var s;
+      return I(
         "div",
         {
           ref: r.containerRef,
           // User-supplied class/style/attrs fall through and merge onto this root.
           style: { position: "relative", overflow: "hidden" }
         },
-        (l = s.default) == null ? void 0 : l.call(s)
+        (s = c.default) == null ? void 0 : s.call(c)
       );
     };
   }
 });
 export {
-  te as CeriousScroll,
-  oe as CeriousScrollEngine,
-  G as useCeriousScroll
+  ce as CeriousScroll,
+  ie as CeriousScrollEngine,
+  k as useCeriousScroll
 };

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

@@ -10,6 +10,11 @@ export interface UseCeriousScrollOptions<TItem = unknown> {
     getItem?: (index: number) => TItem;
     /** Renders a single row to a Vue VNode. `item` is `undefined` with no data source. */
     renderItem: (item: TItem, index: number) => VNodeChild;
+    /**
+     * Table mode only: renders the header (a `<tr>` of `<th>`s) into the engine's
+     * `<thead>`. Reactive — re-renders when its dependencies change.
+     */
+    renderHeader?: () => VNodeChild;
     /** 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/vue-cerious-scroll",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Vue 3 bindings for CeriousScroll — high-performance virtual scrolling with O(1) memory and no height estimation",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -57,7 +57,7 @@
     "demo:build": "vite build --config demo/vite.config.ts"
   },
   "dependencies": {
-    "@ceriousdevtech/cerious-scroll": "^1.0.5"
+    "@ceriousdevtech/cerious-scroll": "^1.0.6"
   },
   "peerDependencies": {
     "vue": "^3.3.0"