@ceriousdevtech/vue-cerious-scroll 1.0.6 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.1.0] - 2026-08-22
+
+### Added
+- Declarative canonical and dynamic Masonry support through the existing `#item` slot or `render-item` prop.
+- Dynamic-height probe rendering with short-lived Vue trees that are disposed after synchronous measurement.
+- `jumpToItem(index, screenOffset?)` on the composable result and exposed component API.
+- `CeriousScrollOptions` support for wrapper-owned Masonry rendering, canonical/dynamic demo routes, and regression coverage for both modes.
+
+### 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
+
+### Fixed
+- **`provide()` values from the component using `<CeriousScroll>` now reach `inject()` inside rows** ([#1](https://github.com/ceriousdevtech/vue-cerious-scroll/issues/1)). Rows (and the table header) are rendered as detached vnode trees via Vue's `render()`, so injection resolved only against the app context's `provides` — app-level/plugin provides worked, but local `provide()` on the owning component did not. The wrapper now renders rows with the owning component instance's `provides` (which prototype-chains to the app provides), so component-level, plugin, and app-level provide/inject all work inside virtualized rows. When the owner provides nothing, behavior is unchanged.
+
+### Changed
+- Updated the core engine dependency to `@ceriousdevtech/cerious-scroll@^1.0.8` (native-scrollbar drag rendering is now coalesced to one render per frame, with no per-row layout thrash on fast drags).
+
 ## [1.0.6] - 2026-06-11
 
 ### Changed

package/README.md

@@ -109,7 +109,7 @@ const { containerRef } = useCeriousScroll({
 | `totalElements` | `number` | Total item count. Required if `items` is omitted. |
 | `getItem` | `(index) => TItem` | Lazy item getter for large/sparse datasets. |
 | `renderItem` | `(item, index) => VNodeChild` | Render prop alternative to the `#item` scoped slot. |
-| `options` | `CeriousScrollOptions` | Engine options (keyboard/touch/wheel/scrollbar/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`. |
 
 The row is provided by the **`#item` scoped slot** (`{ item, index }`) or the
@@ -130,6 +130,7 @@ component — they fall through onto the scroll container (set a height!).
 ```ts
 const scroll = ref<InstanceType<typeof CeriousScroll> | null>(null);
 // scroll.value?.jumpToElement(500);
+// scroll.value?.jumpToItem(500); // Masonry cards
 // scroll.value?.scrollToPercentage(50);
 // scroll.value?.reset();
 // scroll.value?.render();
@@ -139,6 +140,40 @@ const scroll = ref<InstanceType<typeof CeriousScroll> | null>(null);
 
 ---
 
+## Masonry layout
+
+Set `layout: 'masonry'`; the wrapper renders the `#item` slot into each core
+Masonry card, so no imperative DOM callback is exposed:
+
+```vue
+<CeriousScroll
+  ref="scroll"
+  class="gallery"
+  :total-elements="photos.length"
+  :get-item="(index) => photos[index]"
+  :options="{
+    layout: 'masonry',
+    masonry: {
+      getItemHeight: (_index, width) => width * 0.75 + 48,
+      targetColumnWidth: 280,
+      gap: 16
+    }
+  }"
+>
+  <template #item="{ item: photo, index }">
+    <PhotoCard :photo="photo" :index="index" />
+  </template>
+</CeriousScroll>
+```
+
+Omit `getItemHeight` for dynamic DOM measurement. Vue creates a short-lived
+offscreen render tree for measurement and disposes it after the synchronous
+height read; visible cards remain reactive Vue trees with provide/inject and
+event handling.
+
+Use `scroll.value?.jumpToItem(index, screenOffset?)` for card navigation. The
+demo gallery includes 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. The `#item` slot returns the row's `<td>` cells; a `#header` slot provides the (declarative, reactive) `<thead>` row:
@@ -176,8 +211,8 @@ Pass `:options="{ layout: 'table' }"` to render real `<table>` / `<tr>` / `<td>`
   the engine's 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 in place (cheap; Vue patches each row, so focus/selection survive) — 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

@@ -1,5 +1,6 @@
 import { PropType, VNodeChild } from 'vue';
-import { CeriousScrollOptions, MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
+import { MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
+import { CeriousScrollOptions } from './use-cerious-scroll';
 import { CeriousViewportChangeDetail } from './viewport-change';
 /**
  * High-performance virtual scroll list. Provide `items` (or `total-elements` +
@@ -93,10 +94,10 @@ export declare const CeriousScroll: import('vue').DefineComponent<import('vue').
     "onMeasured-viewport"?: ((_range: MeasuredViewportRange) => any) | undefined;
     onReady?: ((_scroller: unknown) => any) | undefined;
 }>, {
+    renderItem: (item: unknown, index: number) => VNodeChild;
     totalElements: number | null;
     items: readonly unknown[] | null;
     getItem: (index: number) => unknown;
-    renderItem: (item: unknown, index: number) => VNodeChild;
     options: CeriousScrollOptions;
     autoRender: boolean;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

package/dist/index.cjs

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

package/dist/index.d.ts

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

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

@@ -1,6 +1,13 @@
 import { MaybeRefOrGetter, Ref, VNodeChild } from 'vue';
-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 Vue-owned Masonry rendering. */
+export type CeriousScrollOptions = Omit<CoreCeriousScrollOptions, 'masonry'> & {
+    masonry?: Omit<MasonryOptions, 'renderItem'> & {
+        /** Accepted for backward compatibility; Vue supplies the active renderer. */
+        renderItem?: MasonryOptions['renderItem'];
+    };
+};
 export interface UseCeriousScrollOptions<TItem = unknown> {
     /** Total number of items. Falls back to `items.length` when omitted. */
     totalElements?: MaybeRefOrGetter<number | null | undefined>;
@@ -35,6 +42,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. */
@@ -61,6 +70,7 @@ export interface UseCeriousScrollResult {
  *
  * Rows are rendered with the host component's `appContext`, so globally
  * registered components, directives, and installed plugins are available inside
- * each row.
+ * each row — and with the owning component instance's `provides`, so local
+ * `provide()` values reach `inject()` inside rows too (see below).
  */
 export declare function useCeriousScroll<TItem = unknown>(opts: UseCeriousScrollOptions<TItem>): UseCeriousScrollResult;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ceriousdevtech/vue-cerious-scroll",
-  "version": "1.0.6",
-  "description": "Vue 3 bindings for CeriousScroll — high-performance virtual scrolling with O(1) memory and no height estimation",
+  "version": "1.1.0",
+  "description": "Vue 3 bindings for CeriousScroll — virtualized lists, native tables, and Masonry grids",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -45,6 +45,7 @@
     "large-lists",
     "data-grid",
     "variable-height",
+    "masonry",
     "o1-memory",
     "cerious-scroll"
   ],
@@ -57,7 +58,7 @@
     "demo:build": "vite build --config demo/vite.config.ts"
   },
   "dependencies": {
-    "@ceriousdevtech/cerious-scroll": "^1.0.7"
+    "@ceriousdevtech/cerious-scroll": "^1.1.0"
   },
   "peerDependencies": {
     "vue": "^3.3.0"