smart-masonry-grid 0.2.0 → 0.2.1

package/README.md

@@ -1,19 +1,59 @@
-# smart-masonry-grid
-
-[![npm version](https://img.shields.io/npm/v/smart-masonry-grid)](https://www.npmjs.com/package/smart-masonry-grid)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/smart-masonry-grid)](https://bundlephobia.com/package/smart-masonry-grid)
-[![license](https://img.shields.io/npm/l/smart-masonry-grid)](https://github.com/LittleBoy9/smart-masonry-grid/blob/main/LICENSE)
-
-A zero-dependency, virtualized masonry grid layout library for vanilla JS and React.
+<p align="center">
+  <h1 align="center">smart-masonry-grid</h1>
+  <p align="center">
+    A zero-dependency, virtualized masonry grid layout library for vanilla JS and React.
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/smart-masonry-grid"><img src="https://img.shields.io/npm/v/smart-masonry-grid?color=blue&label=npm" alt="npm version" /></a>
+  <a href="https://bundlephobia.com/package/smart-masonry-grid"><img src="https://img.shields.io/bundlephobia/minzip/smart-masonry-grid?color=green&label=size" alt="bundle size" /></a>
+  <a href="https://www.npmjs.com/package/smart-masonry-grid"><img src="https://img.shields.io/npm/dm/smart-masonry-grid?color=orange" alt="downloads" /></a>
+  <a href="https://github.com/LittleBoy9/smart-masonry-grid/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/smart-masonry-grid" alt="license" /></a>
+  <a href="https://github.com/LittleBoy9/smart-masonry-grid"><img src="https://img.shields.io/github/stars/LittleBoy9/smart-masonry-grid?style=social" alt="GitHub stars" /></a>
+</p>
+
+<p align="center">
+  <a href="https://littleboy9.github.io/smart-masonry-grid/"><b>Landing Page</b></a> &nbsp;&middot;&nbsp;
+  <a href="https://smart-masonry-grid-demo-1dkf4r5bx-iamsounak01s-projects.vercel.app/"><b>Live Demo</b></a> &nbsp;&middot;&nbsp;
+  <a href="https://github.com/LittleBoy9/smart-masonry-grid"><b>GitHub</b></a>
+</p>
+
+---
+
+## Highlights
 
 - **Zero dependencies** — uses native `ResizeObserver` and `IntersectionObserver`
-- **Virtualization** — renders only visible items, handles 10,000+ items smoothly
-- **Responsive** — auto columns, fixed count, or breakpoint-based
-- **SSR-compatible** — CSS columns fallback with hydration support
+- **Virtualization** — renders only visible items, handles **10,000+ items** smoothly
+- **Responsive** — auto columns, fixed count, named breakpoints, or custom pixel breakpoints
+- **SSR-compatible** — CSS columns fallback with hydration support for Next.js
 - **TypeScript-first** — full type definitions included
-- **Dual API** — vanilla `MasonryGrid` class + React components
+- **Dual API** — vanilla `MasonryGrid` class + React components (`<Masonry>`, `<VirtualMasonry>`, `useMasonryGrid`)
+- **Animations** — built-in entry animations with configurable duration, easing, and offset
+- **Infinite scroll** — built-in `onReachEnd` callback
+- **Tree-shakeable** — ESM + CommonJS, `sideEffects: false`
+
+---
+
+## Why smart-masonry-grid?
+
+Most masonry libraries are **abandoned**, **React-only**, or **missing critical features**. Here's how `smart-masonry-grid` compares:
+
+| Feature | smart-masonry-grid | masonry-layout | react-masonry-css | masonic | @mui/lab Masonry |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Zero dependencies | **Yes** | No | Yes | No | No (heavy) |
+| Virtualization (10K+ items) | **Yes** | No | No | Yes | No |
+| SSR / Next.js support | **Yes** | No | No | Partial | Buggy |
+| Vanilla JS + React | **Yes** | Vanilla only | React only | React only | React only |
+| Built-in animations | **Yes** | No | No | No | No |
+| Built-in infinite scroll | **Yes** | No | No | Yes | No |
+| TypeScript (built-in) | **Yes** | No (@types) | Partial | Yes | Yes |
+| Responsive breakpoints | **4 modes** | No | Basic | No | Basic |
+| Actively maintained | **Yes** | Barely | No (4yr+) | Partial | Yes |
+
+> **No other library** combines zero-dependency virtualization, SSR support, and multi-framework support in one package.
 
-**[Landing Page](https://littleboy9.github.io/smart-masonry-grid/)** · **[Live Demo](https://smart-masonry-grid-demo-1dkf4r5bx-iamsounak01s-projects.vercel.app/)** · **[GitHub](https://github.com/LittleBoy9/smart-masonry-grid)**
+---
 
 ## Install
 
@@ -21,9 +61,20 @@ A zero-dependency, virtualized masonry grid layout library for vanilla JS and Re
 npm install smart-masonry-grid
 ```
 
-## React
+```bash
+# or
+yarn add smart-masonry-grid
+# or
+pnpm add smart-masonry-grid
+```
+
+---
 
-### `<Masonry>` — renders all children
+## Quick Start
+
+### React
+
+#### `<Masonry>` — renders all children
 
 ```tsx
 import { Masonry } from 'smart-masonry-grid/react';
@@ -39,7 +90,7 @@ function Gallery({ photos }) {
 }
 ```
 
-### `<VirtualMasonry>` — renders only visible items
+#### `<VirtualMasonry>` — for large datasets (1,000+ items)
 
 ```tsx
 import { VirtualMasonry } from 'smart-masonry-grid/react';
@@ -60,7 +111,7 @@ function Gallery({ photos }) {
 }
 ```
 
-### `useMasonryGrid` hook — full control
+#### `useMasonryGrid` hook — full control
 
 ```tsx
 import { useMasonryGrid } from 'smart-masonry-grid/react';
@@ -83,7 +134,7 @@ function CustomGrid({ items }) {
 }
 ```
 
-## Vanilla JS
+### Vanilla JS
 
 ```js
 import { MasonryGrid } from 'smart-masonry-grid';
@@ -107,7 +158,7 @@ grid.on('resize', (width, cols) => console.log(width, cols));
 grid.destroy();
 ```
 
-### Virtualized (vanilla)
+#### Virtualized (vanilla)
 
 ```js
 const grid = new MasonryGrid(container, {
@@ -120,48 +171,87 @@ const grid = new MasonryGrid(container, {
 });
 ```
 
-## Column strategies
+---
+
+## Column Strategies
+
+4 flexible ways to configure columns:
 
 ```tsx
-// Fixed column count
+// 1. Fixed column count
 <Masonry columns={4} />
 
-// Auto: fill based on minimum column width
+// 2. Auto — fill based on minimum column width
 <Masonry columns={{ type: 'auto', minColumnWidth: 250 }} />
 
-// Named breakpoints (sm=640, md=768, lg=1024, xl=1280)
+// 3. Named breakpoints (sm=640, md=768, lg=1024, xl=1280)
 <Masonry columns={{ sm: 2, md: 3, lg: 4, xl: 5 }} />
 
-// Custom pixel breakpoints
+// 4. Custom pixel breakpoints
 <Masonry columns={{ 480: 2, 768: 3, 1200: 4 }} />
 ```
 
-## Props
+---
+
+## API Reference
 
-### `<Masonry>`
+### `<Masonry>` Props
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
+|---|---|---|---|
 | `children` | `ReactNode` | — | Items to lay out |
 | `columns` | `number \| ColumnStrategy \| NamedBreakpoints` | `auto, 250px` | Column configuration |
-| `gap` | `number` | `16` | Gap between items (px) |
+| `gap` | `number` | `16` | Gap between items in pixels |
 | `animate` | `boolean \| AnimationConfig` | `false` | Entry animations |
-| `onLayout` | `(output: LayoutOutput) => void` | — | Layout callback |
-| `onReachEnd` | `() => void` | — | Infinite scroll callback |
+| `onLayout` | `(output: LayoutOutput) => void` | — | Called after each layout computation |
+| `onReachEnd` | `() => void` | — | Called when scrolled near the bottom (infinite scroll) |
 | `reachEndThreshold` | `number` | `200` | Pixels from bottom to trigger `onReachEnd` |
 
-### `<VirtualMasonry>`
+### `<VirtualMasonry>` Props
 
 All `<Masonry>` props except `children`, plus:
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `totalItems` | `number` | — | Total item count |
-| `renderItem` | `(index: number) => ReactElement` | — | Render function per item |
-| `height` | `number` | — | Scroll container height (px) |
-| `overscan` | `number` | `600` | Pre-render buffer (px) |
+|---|---|---|---|
+| `totalItems` | `number` | — | Total number of items |
+| `renderItem` | `(index: number) => ReactElement` | — | Render function for each item |
+| `height` | `number` | — | Scroll container height in pixels |
+| `overscan` | `number` | `600` | Pre-render buffer in pixels |
 | `estimatedItemHeight` | `number` | `300` | Height estimate for unmeasured items |
-| `placeholder` | `ReactElement` | — | Shown while item is unmeasured |
+| `placeholder` | `ReactElement` | — | Shown while an item is being measured |
+
+### `MasonryGrid` (Vanilla JS)
+
+```ts
+const grid = new MasonryGrid(container: HTMLElement, options?: MasonryGridOptions);
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `columns` | `number \| ColumnStrategy` | `auto, 250px` | Column configuration |
+| `gap` | `number` | `16` | Gap between items in pixels |
+| `virtualize` | `boolean` | `true` | Enable virtualization |
+| `totalItems` | `number` | — | Total items (virtualized mode) |
+| `renderItem` | `(index: number) => HTMLElement` | — | Item renderer (virtualized mode) |
+| `ssrFallback` | `boolean` | `false` | Use CSS columns for SSR |
+| `resizeDebounceMs` | `number` | `100` | Debounce delay for resize events |
+
+**Methods:**
+
+| Method | Description |
+|---|---|
+| `append(elements)` | Add elements to the end |
+| `prepend(elements)` | Add elements to the beginning |
+| `remove(id)` | Remove an item by ID |
+| `refresh()` | Force a full relayout |
+| `getLayout()` | Returns current `LayoutOutput` |
+| `getColumnCount()` | Returns current column count |
+| `on(event, callback)` | Subscribe to events |
+| `destroy()` | Clean up observers and DOM |
+
+**Events:** `layout`, `resize`, `scroll`, `itemResize`, `destroy`
+
+---
 
 ## SSR
 
@@ -172,6 +262,23 @@ import { getSSRStyles } from 'smart-masonry-grid';
 const css = getSSRStyles();
 ```
 
+The library provides a CSS columns fallback for the initial server render, then smoothly transitions to the JS-powered masonry layout after hydration.
+
+---
+
+## Browser Support
+
+Uses native browser APIs with excellent coverage:
+
+| API | Support |
+|---|---|
+| `ResizeObserver` | 99%+ |
+| `IntersectionObserver` | 98%+ |
+
+No polyfills needed for modern browsers.
+
+---
+
 ## License
 
 [MIT](LICENSE) — Built by [Sounak Das](https://sounakdas.in)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-masonry-grid",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "homepage": "https://littleboy9.github.io/smart-masonry-grid/",
   "repository": {
     "type": "git",