@yasanchezz/vue-infinite-grid 0.1.10 → 0.2.0

package/README.md

@@ -18,7 +18,7 @@ Register it as a global component in `main.js`
 
 ``` js
 import VueGrid from '@yasanchezz/vue-infinite-grid';
-import '@yasanchezz/vue-infinite-grid/dist/style.css';
+import '@yasanchezz/vue-infinite-grid/dist/vue-infinite-grid.css';
 
 createApp(App)
   .use(VueGrid)
@@ -33,7 +33,7 @@ createApp(App)
     ref="grid"
     :rows="rows"
     :rows-count="10"
-    :height="200"
+    :row-initial-height="200"
     class="my-grid"
   >
     <template #row="{ row }">
@@ -59,17 +59,20 @@ createApp(App)
 ```
 
 Each item in `rows` must have a unique `id: string`, which `VueGrid` uses as
-the `:key` for the row and to track its measured height.
+the `:key` for the row and to track its measured height. A row can also set
+`sticky: true` to stay pinned to the top of the scroll container while it's
+part of the rendered window (see [Styling notes](#styling-notes)).
 
 ## Props
 
 | Prop | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
-| `rows` | `GridRow[]` (`{ id: string }`) | yes | - | The full list of rows. Only a window of these is actually rendered at a time. |
+| `rows` | `GridRow[]` (`{ id: string, sticky?: boolean }`) | yes | - | The full list of rows. Only a window of these is actually rendered at a time. |
 | `rowsCount` | `number` | yes | - | How many rows to render at once (the size of the rendered window). |
-| `height` | `number` | yes | - | Estimated row height in px, used for scroll/offset math before a row has actually been measured. |
+| `rowInitialHeight` | `number` | yes | - | Estimated row height in px, used for scroll/offset math before a row has actually been measured. |
 | `container` | `Element \| null \| ((container: Element \| null) => Element \| null \| undefined)` | no | `document.documentElement` | The scrollable element to listen to. Can be a function that receives the grid's root element (useful for resolving a custom scroll container after mount). |
-| `autoCalculatedRowsCount` | `boolean` | no | `false` | When `true`, grows the rendered window beyond `rowsCount` based on measured row heights so it always covers the viewport (useful when actual row heights are smaller than the estimated `height`). |
+| `autoCalculatedRowsCount` | `boolean` | no | `false` | When `true`, grows the rendered window beyond `rowsCount` based on measured row heights so it always covers the viewport (useful when actual row heights are smaller than the estimated `rowInitialHeight`). |
+| `rowsOffset` | `number` | no | `rowInitialHeight * Math.trunc(rowsCount / 5)` (or `1000` if that's `0`) | Extra px of buffer kept rendered above/below the viewport before the window shifts, to reduce blank space while scrolling fast. |
 
 ## Slots
 
@@ -97,7 +100,12 @@ window.addEventListener('resize', () => grid.value.init()) // recalculate layout
 </script>
 
 <template>
-  <VueGrid ref="grid" :rows="rows" :rows-count="10" :height="200" />
+  <VueGrid
+    ref="grid"
+    :rows="rows"
+    :rows-count="10"
+    :row-initial-height="200"
+  />
 </template>
 ```
 
@@ -107,3 +115,10 @@ window.addEventListener('resize', () => grid.value.init()) // recalculate layout
 column layout on the root element (e.g. `grid-template-columns`) and have
 each row use `display: grid; grid-template-columns: subgrid;` spanning
 `grid-column: 1 / -1` so it inherits those columns.
+
+### Sticky rows
+
+Setting `sticky: true` on a row makes `VueGrid` add a `grid-row--sticky`
+class to it (`position: sticky; top: 0;`) and keep that row rendered and
+pinned to the top of the scroll container even after it scrolls out of the
+regular rendered window, until a later sticky row takes its place.

package/dist/VueGrid.d.ts

@@ -1,12 +1,14 @@
 declare const __VLS_export: <GridRow extends {
     id: string;
+    sticky?: boolean;
 }>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: import('vue').PublicProps & __VLS_PrettifyLocal<{
         autoCalculatedRowsCount?: boolean;
         container?: (Element | null | undefined) | ((container: Element | null) => Element | null | undefined);
+        rowInitialHeight: number;
         rows: GridRow[];
         rowsCount: number;
-        height: number;
+        rowsOffset?: number;
     }> & (typeof globalThis extends {
         __VLS_PROPS_FALLBACK: infer P;
     } ? P : {});

package/dist/vue-infinite-grid.css

@@ -1,2 +1,2 @@
-.infinite-grid[data-v-923e3f26]{overflow-anchor:none;align-content:start;display:grid;overflow:clip}.grid-row[data-v-923e3f26]{grid-column:1/-1;grid-template-columns:subgrid;display:grid}.content[data-v-923e3f26]{display:contents}.before[data-v-923e3f26],.after[data-v-923e3f26]{pointer-events:none;grid-column:1/-1}
+@layer VueGrid{.infinite-grid[data-v-145b839c]{overflow-anchor:none;align-content:start;width:max-content;display:grid;overflow:clip}.grid-row[data-v-145b839c]{grid-column:1/-1;grid-template-columns:subgrid;display:grid}.grid-row--sticky[data-v-145b839c]{position:sticky;top:0}.content[data-v-145b839c]{display:contents}.before[data-v-145b839c],.after[data-v-145b839c]{pointer-events:none;grid-column:1/-1}}
 /*$vite$:1*/

package/dist/vue-infinite-grid.js

@@ -1,6 +1,6 @@
-import { Fragment as e, computed as t, createElementBlock as n, createElementVNode as r, defineComponent as i, normalizeStyle as a, onMounted as o, onUnmounted as s, openBlock as c, ref as l, renderList as u, renderSlot as d, shallowRef as f, useTemplateRef as p, watch as m, watchEffect as h } from "vue";
+import { Fragment as e, computed as t, createElementBlock as n, createElementVNode as r, defineComponent as i, normalizeClass as a, normalizeStyle as o, onMounted as s, onUnmounted as c, openBlock as l, ref as u, renderList as ee, renderSlot as te, shallowRef as d, useTemplateRef as f, watch as p, watchEffect as m } from "vue";
 //#region src/VueGrid.vue?vue&type=script&setup=true&lang.ts
-var g = ["data-index"], _ = /*#__PURE__*/ ((e, t) => {
+var h = ["data-index"], g = /*#__PURE__*/ ((e, t) => {
 	let n = e.__vccOpts || e;
 	for (let [e, r] of t) n[e] = r;
 	return n;
@@ -13,135 +13,169 @@ var g = ["data-index"], _ = /*#__PURE__*/ ((e, t) => {
 		},
 		container: {
 			type: [null, Function],
-			default: document.documentElement
+			default: null
 		},
+		rowInitialHeight: {},
 		rows: {},
 		rowsCount: {},
-		height: {}
+		rowsOffset: { default: 0 }
 	},
-	setup(i, { expose: _ }) {
-		let v = f([]), y = p("grid"), b = p("content"), x = t(() => i.container instanceof Function ? i.container(y.value) ?? document.documentElement : i.container ?? document.documentElement), S = t(() => x.value === document.documentElement || x.value === document.body ? window : x.value), C = /* @__PURE__ */ new Map(), w = i.height * Math.trunc(i.rowsCount / 5) || 1e3, T, E, D = i.rowsCount;
-		function O() {
-			if (i.autoCalculatedRowsCount) {
-				let e = window.innerHeight + i.height, t = P - w, n = t < e ? Math.ceil(e / t * D) : D;
-				D = n < i.rowsCount ? i.rowsCount : n;
-			}
+	setup(i, { expose: g }) {
+		let _ = d([]), v = f("grid"), y = f("content"), b = t(() => i.container instanceof Function ? i.container(v.value) ?? document.documentElement : i.container ?? document.documentElement), x = t(() => b.value === document.documentElement || b.value === document.body ? window : b.value), S = /* @__PURE__ */ new Map(), C = i.rowsOffset || i.rowInitialHeight * Math.trunc(i.rowsCount / 5) || 1e3, w, T, E = /* @__PURE__ */ new Map();
+		function D() {
+			E = new Map(i.rows.map((e, t) => [e.id, t]));
+		}
+		let O = new Float32Array(i.rows.length);
+		function k() {
+			O = new Float32Array(i.rows.map((e) => S.get(e.id) ?? i.rowInitialHeight));
 		}
-		let k = 0;
-		function A() {
-			let e = 0, t = y.value;
-			for (; t instanceof HTMLElement && t != x.value;) e += t.offsetTop, t = t.offsetParent;
-			k = e;
+		function A(e, t) {
+			S.set(e, t);
+			let n = E.get(e);
+			n != null && (O[n] = t);
 		}
-		let j = l({ height: "0px" }), M = 0;
+		function j(e) {
+			return O.at(e) ?? i.rowInitialHeight;
+		}
+		let M = i.rowsCount;
 		function N() {
-			return M = i.rows.map((e) => C.get(e.id) ?? i.height).reduce((e, t) => e + t, 0), j.value.height = `${M}px`, M;
+			if (i.autoCalculatedRowsCount) {
+				let e = window.innerHeight + i.rowInitialHeight, t = z - C, n = t < e ? Math.ceil(e / t * M) : M;
+				M = Number.isFinite(n) && n >= i.rowsCount ? n : i.rowsCount;
+			}
 		}
 		let P = 0;
 		function F() {
-			P = v.value.map((e) => C.get(e.id) ?? i.height).reduce((e, t) => e + t, 0);
+			let e = 0, t = v.value;
+			for (; t instanceof HTMLElement && t != b.value;) e += t.offsetTop, t = t.offsetParent;
+			P = e;
 		}
-		let I = l({ height: "0px" }), L = 0;
+		let I = u({ height: "0px" }), L = 0;
 		function R() {
-			let e = x.value.scrollTop - w - k, t = 0;
-			for (let n of i.rows) {
-				let r = C.get(n.id) ?? i.height;
+			L = O.reduce((e, t) => e + t, 0), I.value.height = `${L}px`;
+		}
+		let z = 0, B = 0, V = M;
+		function H() {
+			z = O.slice(B, V).reduce((e, t) => e + t, 0);
+		}
+		let U = u({ height: "0px" }), W = 0;
+		function G() {
+			let e = b.value.scrollTop - C - P, t = 0;
+			for (let n of i.rows.keys()) {
+				let r = j(n);
 				if (t + r > e) break;
 				t += r;
 			}
-			let n = M - P, r = t > n ? n : t;
-			return L = r, I.value.height = `${r}px`, r;
+			let n = L - z;
+			W = t > n ? n : t;
 		}
-		let z = l({ height: "0px" }), B = 0;
-		function V() {
-			B = M - L - P, z.value.height = `${B}px`;
+		let K = 0;
+		function q() {
+			let e = W - K;
+			e = e < 0 ? 0 : e, U.value.height = `${e}px`;
 		}
-		function H() {
-			cancelAnimationFrame(T), T = requestAnimationFrame(() => {
-				A(), F(), N(), R(), V();
-				let e = 0, t = 0;
-				for (let [n, r] of i.rows.entries()) {
-					let a = C.get(r.id) ?? i.height;
-					if (e += a, !(e <= L)) {
-						t = n;
+		let J = u({ height: "0px" }), Y = 0;
+		function X() {
+			Y = L - W - z, J.value.height = `${Y}px`;
+		}
+		function Z() {
+			cancelAnimationFrame(w), w = requestAnimationFrame(() => {
+				F(), H(), R(), G(), q(), X();
+				let e = 0, t = 0, n, r;
+				for (let [a, o] of i.rows.entries()) {
+					let i = j(a);
+					if (e += i, e > W) {
+						t = a;
 						break;
 					}
+					o.sticky && (n = o, r = a, K = i);
 				}
-				let n = t + D > i.rows.length ? i.rows.slice(i.rows.length - D) : i.rows.slice(t, t + D);
-				B || (n = i.rows.slice(i.rows.length - D)), (n.at(0) !== v.value.at(0) || n.length !== v.value.length) && (v.value = n), F(), N(), V();
+				[B, V] = t + M > i.rows.length || !Y ? [i.rows.length - M, i.rows.length] : [t, t + M];
+				let a = n && r != null && r < B ? [n] : [], o = a.length, s = i.rows.slice(B, V), c = a.concat(s);
+				o || (K = 0), (c.at(o) !== _.value.at(o) || c.length !== _.value.length) && (_.value = c), H(), R(), q(), X();
 			});
 		}
-		let U = new ResizeObserver((e) => {
+		let Q = new ResizeObserver((e) => {
 			for (let t of e) {
-				let e = t.target, n = t.borderBoxSize.at(0)?.blockSize ?? i.height;
+				let e = t.target, n = t.borderBoxSize.at(0)?.blockSize ?? i.rowInitialHeight;
 				if (e instanceof HTMLElement) {
 					let t = e.dataset.index;
-					t != null && C.set(t, n);
+					t != null && A(t, n);
 				}
 			}
-			cancelAnimationFrame(E), E = requestAnimationFrame(() => {
-				F(), O(), H();
+			cancelAnimationFrame(T), T = requestAnimationFrame(() => {
+				H(), N(), Z();
 			});
-		}), W = new MutationObserver((e) => {
-			for (let t of e) t.addedNodes.values().filter((e) => e instanceof HTMLElement).forEach((e) => U.observe(e)), t.removedNodes.values().filter((e) => e instanceof HTMLElement).forEach((e) => U.unobserve(e));
+		}), $ = new MutationObserver((e) => {
+			for (let t of e) t.addedNodes.values().filter((e) => e instanceof HTMLElement).forEach((e) => Q.observe(e)), t.removedNodes.values().filter((e) => e instanceof HTMLElement).forEach((e) => Q.unobserve(e));
 		});
-		return h(() => {
-			W.disconnect(), b.value && W.observe(b.value, { childList: !0 });
-		}), m(() => i.rows, H, { flush: "post" }), m(S, (e, t) => {
-			t?.removeEventListener("scroll", H), e.addEventListener("scroll", H, { passive: !0 });
-		}, { immediate: !0 }), o(() => {
-			H();
-		}), s(() => {
-			S.value.removeEventListener("scroll", H);
-		}), _({
+		m(() => {
+			$.disconnect(), y.value && $.observe(y.value, { childList: !0 });
+		}), p(() => i.rows, () => {
+			D(), k(), Z();
+		}, { flush: "post" }), p(x, (e, t) => {
+			t?.removeEventListener("scroll", Z), e.addEventListener("scroll", Z, { passive: !0 });
+		}, { immediate: !0 }), s(() => {
+			D(), k(), Z();
+		}), c(() => {
+			Q.disconnect(), $.disconnect(), x.value.removeEventListener("scroll", Z), S.clear(), E.clear(), O = /* @__PURE__ */ new Float32Array();
+		}), g({
 			init() {
-				F(), O(), H();
+				H(), N(), Z();
 			},
 			async scrollTo(e) {
 				let t = 0;
-				for (let n of i.rows) {
-					if (n.id === e) break;
-					t += C.get(n.id) ?? i.height;
+				for (let [n, r] of i.rows.entries()) {
+					if (r.id === e) break;
+					t += j(n);
 				}
-				return x.value.scrollTo(0, t + k), new Promise((t) => {
-					let n = x.value.querySelector(`[data-index="${e}"]`);
+				return b.value.scrollTo(0, t + P), new Promise((t) => {
+					let n = b.value.querySelector(`[data-index="${e}"]`);
 					if (n instanceof HTMLElement) return t(n);
 					let r = new MutationObserver((n) => {
 						let i = n.flatMap((e) => Array.from(e.addedNodes)).filter((e) => e instanceof HTMLElement).find((t) => t.dataset.index === e);
 						i && (t(i), r.disconnect());
 					});
-					h(() => {
-						r.disconnect(), b.value && r.observe(b.value, { childList: !0 });
-					}), s(() => r.disconnect());
+					m(() => {
+						r.disconnect(), y.value && r.observe(y.value, { childList: !0 });
+					}), c(() => r.disconnect());
 				});
 			}
-		}), (t, i) => (c(), n("div", {
+		});
+		function ne(e) {
+			let t = "grid-row";
+			return {
+				[t]: !0,
+				[`${t}--sticky`]: e.sticky
+			};
+		}
+		return (t, i) => (l(), n("div", {
 			ref_key: "grid",
-			ref: y,
+			ref: v,
 			class: "infinite-grid",
-			style: a(j.value)
+			style: o(I.value)
 		}, [
 			r("div", {
 				class: "before",
-				style: a(I.value)
+				style: o(U.value)
 			}, null, 4),
 			r("div", {
 				ref_key: "content",
-				ref: b,
+				ref: y,
 				class: "content"
-			}, [(c(!0), n(e, null, u(v.value, (e) => (c(), n("div", {
+			}, [(l(!0), n(e, null, ee(_.value, (e) => (l(), n("div", {
 				key: e.id,
-				class: "grid-row",
+				class: a(ne(e)),
 				"data-index": e.id
-			}, [d(t.$slots, "row", { row: e }, void 0, !0)], 8, g))), 128))], 512),
+			}, [te(t.$slots, "row", { row: e }, void 0, !0)], 10, h))), 128))], 512),
 			r("div", {
 				class: "after",
-				style: a(z.value)
+				style: o(J.value)
 			}, null, 4)
 		], 4));
 	}
-}), [["__scopeId", "data-v-923e3f26"]]), v = { install(e) {
-	e.component("VueGrid", _);
+}), [["__scopeId", "data-v-145b839c"]]), _ = { install(e) {
+	e.component("VueGrid", g);
 } };
 //#endregion
-export { v as default };
+export { _ as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yasanchezz/vue-infinite-grid",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "type": "module",
   "files": [
     "dist"
@@ -16,24 +16,25 @@
     "@stylistic/eslint-plugin": "^5.10.0",
     "@tsconfig/node24": "^24.0.4",
     "@types/node": "^24.13.3",
-    "@typescript-eslint/utils": "^8.65.0",
+    "@typescript-eslint/utils": "^8.67.0",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vue/eslint-config-typescript": "^14.9.0",
     "@vue/tsconfig": "^0.9.1",
-    "eslint": "^10.7.0",
+    "eslint": "^10.8.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-oxlint": "~1.69.0",
     "eslint-plugin-vue": "~10.9.2",
     "jiti": "^2.7.0",
-    "npm-run-all2": "^9.0.2",
+    "npm-run-all2": "^9.0.3",
     "oxfmt": "^0.54.0",
     "oxlint": "~1.69.0",
+    "sass-embedded": "^1.100.0",
     "typescript": "~6.0.3",
-    "vite": "^8.1.5",
+    "vite": "^8.2.1",
     "vite-plugin-dts": "^5.0.3",
-    "vite-plugin-vue-devtools": "^8.1.5",
+    "vite-plugin-vue-devtools": "^8.2.1",
     "vue-eslint-parser": "^10.4.1",
-    "vue-tsc": "^3.3.8"
+    "vue-tsc": "^3.3.9"
   },
   "engines": {
     "node": ">= 24.12.0",