@ceriousdevtech/react-cerious-scroll 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.2] - 2026-06-03
+
+### Added
+- `<CeriousScroll>` now accepts `children`. Rendered children are mounted inside the engine container alongside the engine's scrollbar strip. Combined with a user-supplied `<div data-cerious-scroll-content />`, this lets demos and apps wrap rows in custom DOM (e.g. an `overflow-x: auto` wrapper with a sticky header) without breaking the engine's mobile scrollbar pinning.
+
+### Dependencies
+- Bumped peer dependency `@ceriousdevtech/cerious-scroll` to `^1.0.3` to pick up horizontal flick momentum and the custom scrollbar thumb.
+
 ## [1.0.1] - 2026-06-01
 
 ### Changed

package/dist/cerious-scroll.d.ts

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactElement, Ref } from 'react';
+import { CSSProperties, ReactElement, ReactNode, Ref } from 'react';
 import { CeriousScroll as CeriousScrollEngine, MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
 import { UseCeriousScrollOptions } from './use-cerious-scroll';
 export interface CeriousScrollProps<TItem = unknown> extends UseCeriousScrollOptions<TItem> {
@@ -11,6 +11,13 @@ export interface CeriousScrollProps<TItem = unknown> extends UseCeriousScrollOpt
     style?: CSSProperties;
     /** Forwarded to the scroll container for testing. */
     'data-testid'?: string;
+    /**
+     * Optional custom DOM rendered inside the engine container. Use this when
+     * you need siblings (e.g. a sticky header + horizontal-scroll wrapper) around
+     * the recyclable row area. Include a `<div data-cerious-scroll-content />`
+     * descendant to host the rendered rows; otherwise the engine creates its own.
+     */
+    children?: ReactNode;
 }
 export interface CeriousScrollHandle {
     /** The underlying engine instance (`null` before mount). */

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const J=require("react/jsx-runtime"),r=require("react"),H=require("react-dom"),K=require("react-dom/server"),_=require("@ceriousdevtech/cerious-scroll"),V="data-cerious-scroll-content",Q="data-cerious-scroll-row";function U(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.overflow="hidden",e.appendChild(n),n}function X(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 Y(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,y]=r.useState(null),E=r.useRef(e.renderItem),d=r.useRef(e.items??null),v=r.useRef(e.getItem),S=r.useRef(e.options),h=r.useRef(e.autoRender??!0),p=r.useRef(e.totalElements??null),O=r.useRef(e.onViewportChange),T=r.useRef(e.onMeasuredViewport),I=r.useRef(e.onReady);E.current=e.renderItem,d.current=e.items??null,v.current=e.getItem,S.current=e.options,h.current=e.autoRender??!0,p.current=e.totalElements??null,O.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 g=d.current;return g?g[t]:void 0},[]),s=r.useCallback(()=>{var w;const t=n.current;if(!t)return null;const{scroller:c,contentEl:g,container:C}=t,j=C.clientHeight||C.offsetHeight||0,b=[],i=(f,R)=>{const m=document.createElement("div");m.setAttribute(Q,String(f)),m.innerHTML=K.renderToStaticMarkup(r.createElement(r.Fragment,null,E.current(k(f),f))),R.appendChild(m),a.current.set(f,{el:R,mount:m}),b.push(m)},A=c.renderViewport(j,g,i),M=new Set(c.getRenderedIndices());return a.current.forEach((f,R)=>{M.has(R)||a.current.delete(R)}),b.forEach(f=>{f.textContent=""}),H.flushSync(o),(w=T.current)==null||w.call(T,A),A},[]),B=e.totalElements??((N=e.items)==null?void 0:N.length)??null;r.useEffect(()=>{var w,f;const t=l.current;if(!t)return;const c=U(t),g=S.current??{},C=g.onScroll,j={...g,onScroll:()=>{C==null||C(),h.current&&s()}},b=Y(p.current,((w=d.current)==null?void 0:w.length)??null),i=new _.CeriousScroll(t,b,j);u.current&&(i.currentElement=Math.min(u.current.currentElement,b-1),i.scrollOffset=u.current.scrollOffset,u.current=null),n.current={scroller:i,contentEl:c,container:t},y(i);const A=X(t,R=>{var m;(m=O.current)==null||m.call(O,R)});(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,y(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]),$=r.useCallback(t=>{const c=n.current;return c?(c.scroller.handleScrollPercentage(t),s()):null},[s]),z=r.useCallback(()=>{const t=n.current;return t?(t.scroller.reset(),s()):null},[s]),G=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(E.current(k(c),c),t.mount,String(c)))}),{containerRef:l,portals:L,scroller:q,render:s,jumpToElement:W,scrollToPercentage:$,reset:z,recalculate:G}}function Z(e,l){const{className:n,style:a,"data-testid":u,...o}=e,{containerRef:q,portals:y,scroller:E,render:d,jumpToElement:v,scrollToPercentage:S,reset:h,recalculate:p}=D(o);return r.useImperativeHandle(l,()=>({scroller:E,render:d,jumpToElement:v,scrollToPercentage:S,reset:h,recalculate:p}),[E,d,v,S,h,p]),J.jsx("div",{ref:q,className:n,"data-testid":u,style:{position:"relative",overflow:"hidden",...a},children:y})}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 J=require("react/jsx-runtime"),r=require("react"),H=require("react-dom"),K=require("react-dom/server"),_=require("@ceriousdevtech/cerious-scroll"),V="data-cerious-scroll-content",Q="data-cerious-scroll-row";function U(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.overflow="hidden",e.appendChild(n),n}function X(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 Y(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(Q,String(f)),m.innerHTML=K.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=U(t),R=p.current??{},C=R.onScroll,j={...R,onScroll:()=>{C==null||C(),h.current&&s()}},w=Y(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=X(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]),$=r.useCallback(t=>{const c=n.current;return c?(c.scroller.handleScrollPercentage(t),s()):null},[s]),z=r.useCallback(()=>{const t=n.current;return t?(t.scroller.reset(),s()):null},[s]),G=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:$,reset:z,recalculate:G}}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]),J.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;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { jsx as G } from "react/jsx-runtime";
+import { jsxs as G } from "react/jsx-runtime";
 import { useRef as s, useReducer as J, useState as K, useCallback as S, useEffect as _, createElement as Q, Fragment as U, forwardRef as X, useImperativeHandle as Y } from "react";
 import { flushSync as Z, createPortal as x } from "react-dom";
 import { renderToStaticMarkup as ee } from "react-dom/server";
@@ -41,43 +41,43 @@ function ce(e, c) {
 }
 function le(e) {
   var q;
-  const c = s(null), r = s(null), a = s(/* @__PURE__ */ new Map()), u = s(null), [, o] = J((t) => t + 1, 0), [L, O] = K(null), p = s(e.renderItem), d = s(e.items ?? null), v = s(e.getItem), w = s(e.options), h = s(e.autoRender ?? !0), C = s(e.totalElements ?? null), b = s(e.onViewportChange), y = s(e.onMeasuredViewport), A = s(e.onReady);
-  p.current = e.renderItem, d.current = e.items ?? null, v.current = e.getItem, w.current = e.options, h.current = e.autoRender ?? !0, C.current = e.totalElements ?? null, b.current = e.onViewportChange, y.current = e.onMeasuredViewport, A.current = e.onReady;
+  const c = s(null), r = s(null), a = s(/* @__PURE__ */ new Map()), u = s(null), [, o] = J((t) => t + 1, 0), [L, b] = K(null), w = 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), y = s(e.onMeasuredViewport), A = s(e.onReady);
+  w.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, y.current = e.onMeasuredViewport, A.current = e.onReady;
   const P = S((t) => {
     const n = v.current;
     if (n) return n(t);
-    const g = d.current;
-    return g ? g[t] : void 0;
+    const E = d.current;
+    return E ? E[t] : void 0;
   }, []), l = S(() => {
-    var I;
+    var O;
     const t = r.current;
     if (!t) return null;
-    const { scroller: n, contentEl: g, container: R } = t, N = R.clientHeight || R.offsetHeight || 0, T = [], i = (f, E) => {
+    const { scroller: n, contentEl: E, container: R } = t, N = R.clientHeight || R.offsetHeight || 0, I = [], i = (f, p) => {
       const m = document.createElement("div");
       m.setAttribute(re, String(f)), m.innerHTML = ee(
-        Q(U, null, p.current(P(f), f))
-      ), E.appendChild(m), a.current.set(f, { el: E, mount: m }), T.push(m);
-    }, M = n.renderViewport(N, g, i), F = new Set(n.getRenderedIndices());
-    return a.current.forEach((f, E) => {
-      F.has(E) || a.current.delete(E);
-    }), T.forEach((f) => {
+        Q(U, null, w.current(P(f), f))
+      ), p.appendChild(m), a.current.set(f, { el: p, mount: m }), I.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);
+    }), I.forEach((f) => {
       f.textContent = "";
-    }), Z(o), (I = y.current) == null || I.call(y, M), M;
+    }), Z(o), (O = y.current) == null || O.call(y, M), M;
   }, []), $ = e.totalElements ?? ((q = e.items) == null ? void 0 : q.length) ?? null;
   _(() => {
-    var I, f;
+    var O, f;
     const t = c.current;
     if (!t) return;
-    const n = ne(t), g = w.current ?? {}, R = g.onScroll, N = {
-      ...g,
+    const n = ne(t), E = C.current ?? {}, R = E.onScroll, N = {
+      ...E,
       onScroll: () => {
         R == null || R(), h.current && l();
       }
-    }, T = ce(C.current, ((I = d.current) == null ? void 0 : I.length) ?? null), i = new te(t, T, N);
-    u.current && (i.currentElement = Math.min(u.current.currentElement, T - 1), i.scrollOffset = u.current.scrollOffset, u.current = null), r.current = { scroller: i, contentEl: n, container: t }, O(i);
-    const M = oe(t, (E) => {
+    }, I = ce(T.current, ((O = d.current) == null ? void 0 : O.length) ?? null), i = new te(t, I, N);
+    u.current && (i.currentElement = Math.min(u.current.currentElement, I - 1), i.scrollOffset = u.current.scrollOffset, u.current = null), r.current = { scroller: i, contentEl: n, container: t }, b(i);
+    const M = oe(t, (p) => {
       var m;
-      (m = b.current) == null || m.call(b, E);
+      (m = g.current) == null || m.call(g, p);
     });
     (f = A.current) == null || f.call(A, i);
     let F = 0;
@@ -85,7 +85,7 @@ function le(e) {
       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);
+      }, a.current.clear(), n.textContent = "", i.detachScrollbar(t), i.dispose(), r.current = null, b(null);
     };
   }, [$, l]), _(() => {
     if (!r.current || !h.current) return;
@@ -113,7 +113,7 @@ function le(e) {
   }, [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(p.current(P(n), n), t.mount, String(n))
+      x(w.current(P(n), n), t.mount, String(n))
     );
   }), {
     containerRef: c,
@@ -127,28 +127,31 @@ function le(e) {
   };
 }
 function se(e, c) {
-  const { className: r, style: a, "data-testid": u, ...o } = e, {
-    containerRef: L,
-    portals: O,
-    scroller: p,
-    render: d,
-    jumpToElement: v,
-    scrollToPercentage: w,
-    reset: h,
-    recalculate: C
-  } = le(o);
+  const { className: r, style: a, "data-testid": u, children: o, ...L } = e, {
+    containerRef: b,
+    portals: w,
+    scroller: d,
+    render: v,
+    jumpToElement: C,
+    scrollToPercentage: h,
+    reset: T,
+    recalculate: g
+  } = le(L);
   return Y(
     c,
-    () => ({ scroller: p, render: d, jumpToElement: v, scrollToPercentage: w, reset: h, recalculate: C }),
-    [p, d, v, w, h, C]
+    () => ({ scroller: d, render: v, jumpToElement: C, scrollToPercentage: h, reset: T, recalculate: g }),
+    [d, v, C, h, T, g]
   ), /* @__PURE__ */ G(
     "div",
     {
-      ref: L,
+      ref: b,
       className: r,
       "data-testid": u,
       style: { position: "relative", overflow: "hidden", ...a },
-      children: O
+      children: [
+        o,
+        w
+      ]
     }
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceriousdevtech/react-cerious-scroll",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "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"
   },
   "peerDependencies": {
-    "@ceriousdevtech/cerious-scroll": "^1.0.1",
+    "@ceriousdevtech/cerious-scroll": "^1.0.3",
     "react": ">=18 <20",
     "react-dom": ">=18 <20"
   },