@ceriousdevtech/react-cerious-scroll 1.0.7 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.1.0] - 2026-08-22
+
+### Added
+- Declarative canonical and dynamic Masonry support. The wrapper supplies the core DOM `renderItem` callback while consumers continue returning React nodes from the existing `renderItem` prop.
+- `jumpToItem(index, screenOffset?)` on the hook result and component ref.
+- `CeriousScrollOptions` now accepts Masonry geometry without requiring the engine's imperative DOM callback.
+- Canonical-height and dynamic-height Masonry demo routes and regression tests for both rendering paths.
+
+### Changed
+- Updated `@ceriousdevtech/cerious-scroll` to `^1.1.0` and re-exported the new Masonry and height-provider types.
+- Masonry card-count changes recreate card-derived segment state; list and table count changes continue updating in place.
+
 ## [1.0.7] - 2026-06-24
 
 ### Changed

package/README.md

@@ -110,7 +110,7 @@ function List() {
 | `totalElements` | `number` | Total item count. Required if `items` is omitted. |
 | `getItem` | `(index) => TItem` | Lazy item getter for large/sparse datasets. |
 | `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. |
+| `options` | `CeriousScrollOptions` | Engine options. Masonry's DOM callback is supplied by the wrapper. 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. |
@@ -122,6 +122,7 @@ function List() {
 ```tsx
 const ref = useRef<CeriousScrollHandle>(null);
 // ref.current?.jumpToElement(500);
+// ref.current?.jumpToItem(500); // Masonry cards
 // ref.current?.scrollToPercentage(50);
 // ref.current?.reset();
 // ref.current?.render();
@@ -131,6 +132,38 @@ const ref = useRef<CeriousScrollHandle>(null);
 
 ---
 
+## Masonry layout
+
+Set `layout: 'masonry'` and provide Masonry geometry without a DOM
+`renderItem`; the wrapper connects your existing React render prop to the core
+renderer. Supplying `getItemHeight` selects canonical placement:
+
+```tsx
+<CeriousScroll
+  ref={ref}
+  className="gallery"
+  totalElements={photos.length}
+  getItem={(index) => photos[index]}
+  options={{
+    layout: 'masonry',
+    masonry: {
+      getItemHeight: (_index, width) => width * 0.75 + 48,
+      targetColumnWidth: 280,
+      gap: 16,
+    },
+  }}
+  renderItem={(photo, index) => <PhotoCard photo={photo} index={index} />}
+/>
+```
+
+Omit `getItemHeight` for dynamic DOM-measured cards. React static markup is
+used for the offscreen measurement probe; visible cards remain normal live
+portals with Context, refs, state, and events.
+
+Use `ref.current?.jumpToItem(index, screenOffset?)` for card navigation and
+`ref.current?.scroller?.masonryDeterminism` to read `'canonical'` or `'local'`.
+The demo gallery includes matching canonical and dynamic Masonry pages.
+
 ## 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:
@@ -173,8 +206,8 @@ import { TABLE_COLUMNS } from './data';
   built-in `ResizeObserver`.
 - **`options` are read at creation.** Changing `options` after mount has no
   effect; remount (e.g. with a `key`) to apply new engine options.
-- **Changing the item count** recreates the engine internally (scroll position
-  is preserved). Mutating items without changing the count just re-renders the
+- **Changing the item count** updates lists/tables in place. Masonry recreates
+  its card-count-derived segment layout. Mutating items without changing the count just re-renders the
   content (cheap, and your row state is preserved) — it does **not** discard
   cached heights, so editable grids that produce a new `items` array on every
   edit don't trigger a full viewport re-measure.

package/dist/cerious-scroll.d.ts

@@ -24,6 +24,7 @@ export interface CeriousScrollHandle {
     scroller: CeriousScrollEngine | null;
     render(): MeasuredViewportRange | null;
     jumpToElement(index: number): MeasuredViewportRange | null;
+    jumpToItem(index: number, screenOffset?: number): MeasuredViewportRange | null;
     scrollToPercentage(percentage: number): MeasuredViewportRange | null;
     reset(): MeasuredViewportRange | null;
     /**

package/dist/index.cjs

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

package/dist/index.d.ts

@@ -8,7 +8,7 @@
 export { CeriousScroll } from './cerious-scroll';
 export type { CeriousScrollProps, CeriousScrollHandle } from './cerious-scroll';
 export { useCeriousScroll } from './use-cerious-scroll';
-export type { UseCeriousScrollOptions, UseCeriousScrollResult, } from './use-cerious-scroll';
+export type { UseCeriousScrollOptions, UseCeriousScrollResult, CeriousScrollOptions, } from './use-cerious-scroll';
 export type { CeriousViewportChangeDetail } from './viewport-change';
 export { CeriousScroll as CeriousScrollEngine } from '@ceriousdevtech/cerious-scroll';
-export type { CeriousScrollOptions, KeyboardNavigationOptions, TouchNavigationOptions, WheelNavigationOptions, ElementRenderer, ElementHeightCalculator, ScrollResult, MeasuredViewportRange, } from '@ceriousdevtech/cerious-scroll';
+export type { KeyboardNavigationOptions, TouchNavigationOptions, WheelNavigationOptions, ElementRenderer, ElementHeightCalculator, ScrollResult, MeasuredViewportRange, HeightProvider, MasonryDeterminism, MasonryOptions, } from '@ceriousdevtech/cerious-scroll';

package/dist/index.js

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

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

@@ -1,6 +1,13 @@
 import { ReactNode, RefObject } from 'react';
-import { CeriousScroll as CeriousScrollEngine, CeriousScrollOptions, MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
+import { CeriousScroll as CeriousScrollEngine, CeriousScrollOptions as CoreCeriousScrollOptions, MasonryOptions, MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
 import { CeriousViewportChangeDetail } from './viewport-change';
+/** Engine options adapted for React-owned Masonry rendering. */
+export type CeriousScrollOptions = Omit<CoreCeriousScrollOptions, 'masonry'> & {
+    masonry?: Omit<MasonryOptions, 'renderItem'> & {
+        /** Accepted for backward compatibility; React supplies the active renderer. */
+        renderItem?: MasonryOptions['renderItem'];
+    };
+};
 export interface UseCeriousScrollOptions<TItem = unknown> {
     /** Total number of items. Falls back to `items.length` when omitted. */
     totalElements?: number | null;
@@ -38,6 +45,8 @@ export interface UseCeriousScrollResult {
     render: () => MeasuredViewportRange | null;
     /** Jump to an element index, then render. */
     jumpToElement: (index: number) => MeasuredViewportRange | null;
+    /** Masonry mode only: jump to a card index, then render. */
+    jumpToItem: (index: number, screenOffset?: number) => MeasuredViewportRange | null;
     /** Scroll to a percentage (0..100), then render. */
     scrollToPercentage: (percentage: number) => MeasuredViewportRange | null;
     /** Reset to the top, then render. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ceriousdevtech/react-cerious-scroll",
-  "version": "1.0.7",
-  "description": "React bindings for CeriousScroll — high-performance virtual scrolling with O(1) memory and no height estimation",
+  "version": "1.1.0",
+  "description": "React bindings for CeriousScroll — virtualized lists, native tables, and Masonry grids",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -44,6 +44,7 @@
     "large-lists",
     "data-grid",
     "variable-height",
+    "masonry",
     "o1-memory",
     "cerious-scroll"
   ],
@@ -56,7 +57,7 @@
     "demo:build": "vite build --config demo/vite.config.ts"
   },
   "dependencies": {
-    "@ceriousdevtech/cerious-scroll": "^1.0.8"
+    "@ceriousdevtech/cerious-scroll": "^1.1.0"
   },
   "peerDependencies": {
     "react": ">=18 <20",