@yasanchezz/vue-infinite-grid 0.1.9 → 0.1.11

package/README.md

@@ -1,3 +1,109 @@
-# component
-that placeholder will be replaced by some content soon
+# @yasanchezz/vue-infinite-grid
 
+> An infinite (virtualized) grid component for Vue 3.5+
+
+`VueGrid` renders only the rows that fit near the visible viewport (plus a
+buffer) and keeps scroll height consistent by measuring each rendered row
+with a `ResizeObserver`. It relies on CSS Grid + [`subgrid`](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Subgrid),
+so your rows must be laid out as a grid that spans the full width of the
+component.
+
+## Installation
+
+Install the npm package
+
+`npm install @yasanchezz/vue-infinite-grid --save`
+
+Register it as a global component in `main.js`
+
+``` js
+import VueGrid from '@yasanchezz/vue-infinite-grid';
+import '@yasanchezz/vue-infinite-grid/dist/vue-infinite-grid.css';
+
+createApp(App)
+  .use(VueGrid)
+  .mount('#app');
+```
+
+## Usage
+
+``` vue
+<template>
+  <VueGrid
+    ref="grid"
+    :rows="rows"
+    :rows-count="10"
+    :height="200"
+    class="my-grid"
+  >
+    <template #row="{ row }">
+      <SubgridComponent
+        class="my-subgrid"
+        :row="row"
+      />
+    </template>
+  </VueGrid>
+</template>
+
+<style lang="scss" scoped>
+.my-grid {
+  grid-template-columns: repeat(4, 1fr);
+}
+
+.my-subgrid {
+  grid-column: 1 / -1;
+  display: grid;
+  grid-template-columns: subgrid;
+}
+</style>
+```
+
+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.
+
+## 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. |
+| `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. |
+| `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`). |
+
+## Slots
+
+| Slot | Props | Description |
+| --- | --- | --- |
+| `row` | `{ row: GridRow }` | Renders a single row. Required. |
+
+## Exposed methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `init` | `() => void` | Recalculates the rendered window and layout. Call this after something outside of `rows`/`height` changes the available space, e.g. on window `resize`. |
+| `scrollTo` | `(id: string) => Promise<HTMLElement>` | Scrolls the container to the row with the given `id` and resolves with that row's DOM element once it has been rendered. |
+
+### Usage as a ref
+
+``` vue
+<script setup>
+import { useTemplateRef } from 'vue'
+
+const grid = useTemplateRef('grid')
+
+grid.value.scrollTo(rowId) // scroll to a specific row
+window.addEventListener('resize', () => grid.value.init()) // recalculate layout on resize
+</script>
+
+<template>
+  <VueGrid ref="grid" :rows="rows" :rows-count="10" :height="200" />
+</template>
+```
+
+## Styling notes
+
+`VueGrid` only controls vertical layout - you're expected to define the
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yasanchezz/vue-infinite-grid",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "files": [
     "dist"
@@ -15,12 +15,12 @@
   "devDependencies": {
     "@stylistic/eslint-plugin": "^5.10.0",
     "@tsconfig/node24": "^24.0.4",
-    "@types/node": "^24.13.2",
-    "@typescript-eslint/utils": "^8.63.0",
-    "@vitejs/plugin-vue": "^6.0.7",
+    "@types/node": "^24.13.3",
+    "@typescript-eslint/utils": "^8.65.0",
+    "@vitejs/plugin-vue": "^6.0.8",
     "@vue/eslint-config-typescript": "^14.9.0",
     "@vue/tsconfig": "^0.9.1",
-    "eslint": "^10.6.0",
+    "eslint": "^10.7.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-oxlint": "~1.69.0",
     "eslint-plugin-vue": "~10.9.2",
@@ -29,11 +29,11 @@
     "oxfmt": "^0.54.0",
     "oxlint": "~1.69.0",
     "typescript": "~6.0.3",
-    "vite": "^8.1.3",
+    "vite": "^8.1.5",
     "vite-plugin-dts": "^5.0.3",
     "vite-plugin-vue-devtools": "^8.1.5",
     "vue-eslint-parser": "^10.4.1",
-    "vue-tsc": "^3.3.6"
+    "vue-tsc": "^3.3.8"
   },
   "engines": {
     "node": ">= 24.12.0",