masonry-snap-grid-layout 1.0.10 → 1.0.12

package/README.md

@@ -1,196 +1,198 @@
-
-# masonry-snap-grid-layout
-
-[![npm version](https://img.shields.io/npm/v/masonry-snap-grid-layout?color=brightgreen)](https://www.npmjs.com/package/masonry-snap-grid-layout)
-[![CI/CD](https://github.com/khachatryan-dev/masonry-snap-grid-layout/actions/workflows/publish.yml/badge.svg)](https://github.com/khachatryan-dev/masonry-snap-grid-layout/actions)
-[![Demo Vanilla JS](https://img.shields.io/badge/demo-vanilla%20js-blue)](https://codesandbox.io/p/sandbox/l9xl7s)
-[![Demo React](https://img.shields.io/badge/demo-react-blue)](https://codesandbox.io/p/sandbox/rgxsxp)
-
-A performant masonry grid layout library with smooth animations, customizable gutter, columns, and dynamic item content.
-
-![Masonry Grid Demo](https://i.imgur.com/JQZ4L7C.gif)
-
----
-
-## 🚀 Features
-
-- **Dynamic Columns & Gutter**: Automatically adapts to container width
-- **Smooth Animations**: CSS-powered transitions when layout changes
-- **Customizable Items**: Render any content with gradient backgrounds and emojis
-- **Lightweight**: Zero dependencies, pure TypeScript
-- **React & Vanilla JS**: Works with both React and plain JavaScript
-- **Responsive**: Perfect for galleries, dashboards, and card layouts
-
----
-
-## 🔧 Installation
-
-```bash
-npm install masonry-snap-grid-layout
-# or
-yarn add masonry-snap-grid-layout
-# or
-pnpm add masonry-snap-grid-layout
-```
-
----
-
-## 💡 Usage Examples
-
-### Vanilla JavaScript (Live Demo)
-
-```javascript
-import MasonrySnapGridLayout from 'masonry-snap-grid-layout';
-import 'masonry-snap-grid-layout/dist/index.css';
-
-const container = document.getElementById('masonry-container');
-const items = [
-  { id: 1, title: "Sunset", emoji: "🌅", color: "#FF9A9E" },
-  { id: 2, title: "Ocean", emoji: "🌊", color: "#A1C4FD" },
-  // ... more items
-];
-
-const masonry = new MasonrySnapGridLayout(container, {
-  gutter: 16,
-  minColWidth: 200,
-  animate: true,
-  transitionDuration: 300,
-  items: items,
-  renderItem: (item) => {
-    const div = document.createElement('div');
-    div.style.height = `${120 + Math.random() * 200}px`;
-    div.style.background = `linear-gradient(135deg, ${item.color} 0%, #FFFFFF 100%)`;
-    div.style.borderRadius = '12px';
-    div.style.padding = '16px';
-    div.style.color = '#333';
-    div.innerHTML = `
-      <div style="font-size: 2rem">${item.emoji}</div>
-      <h3 style="margin: 8px 0">${item.title}</h3>
-    `;
-    return div;
-  }
-});
-```
-
-[![Open Vanilla Demo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/sandbox/l9xl7s)
-
----
-
-### React (Live Demo)
-
-```jsx
-import MasonrySnapGrid from 'masonry-snap-grid-layout/react';
-import 'masonry-snap-grid-layout/dist/index.css';
-
-const items = Array.from({ length: 20 }, (_, i) => ({
-  id: i,
-  title: `Item ${i + 1}`,
-  emoji: ['🌻', '🌈', '🍕', '🎸', '🚀'][Math.floor(Math.random() * 5)],
-  height: 120 + Math.random() * 200
-}));
-
-export default function Gallery() {
-  return (
-    <MasonrySnapGrid
-      items={items}
-      gutter={16}
-      minColWidth={220}
-      animate
-      transitionDuration={400}
-      renderItem={(item) => (
-        <div style={{
-          height: `${item.height}px`,
-          background: `linear-gradient(135deg, 
-            hsl(${Math.random() * 360}, 70%, 70%) 0%, 
-            hsl(${Math.random() * 360}, 70%, 80%) 100%)`,
-          borderRadius: '12px',
-          padding: '16px',
-          color: 'white'
-        }}>
-          <div style={{ fontSize: '2rem' }}>{item.emoji}</div>
-          <h3 style={{ margin: '8px 0' }}>{item.title}</h3>
-          <small>Height: {Math.round(item.height)}px</small>
-        </div>
-      )}
-    />
-  );
-}
-```
-
-[![Open React Demo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/sandbox/rgxsxp)
-
----
-
-## 🛠️ API Reference
-
-### Configuration Options
-
-| Option               | Type                      | Default | Description                          |
-|----------------------|---------------------------|---------|--------------------------------------|
-| `gutter`             | `number`                  | `16`    | Spacing between items (px)           |
-| `minColWidth`        | `number`                  | `250`   | Minimum column width (px)            |
-| `animate`            | `boolean`                 | `true`  | Enable/disable animations            |
-| `transitionDuration` | `number`                  | `400`   | Animation duration (ms)              |
-| `items`              | `Array<T>`                | `[]`    | Your data items                      |
-| `renderItem`         | `(item: T) => HTMLElement`| -       | Function to render each item         |
-| `classNames`         | `Object`                  | -       | Custom CSS class names               |
-
-### Methods
-
-- `updateItems(newItems: T[])`: Refresh with new items
-- `shuffleItems()`: Randomize item positions
-- `destroy()`: Clean up the instance
-
----
-
-## 🎨 Customization Tips
-
-**1. Gradient Backgrounds**  
-Use CSS gradients for beautiful card backgrounds:
-
-```css
-background: linear-gradient(135deg, #ff9a9e 0%, #fad0c4 100%);
-```
-
-**2. Random Emojis**  
-Add personality with emojis:
-
-```javascript
-const emojis = ['🌻', '🌈', '🍕', '🎸', '🚀'];
-const randomEmoji = emojis[Math.floor(Math.random() * emojis.length)];
-```
-
-**3. Responsive Breakpoints**  
-Adjust columns based on screen size:
-
-```javascript
-minColWidth: window.innerWidth < 768 ? 150 : 250
-```
-
----
-
-## 📦 Package Structure
-
-```
-dist/
-├── index.js       # Vanilla JS bundle
-├── react.js       # React component
-├── index.d.ts     # TypeScript types
-└── index.css      # Base styles
-```
-
----
-
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
----
-
-## 📄 License
-
+
+# masonry-snap-grid-layout
+
+[![npm version](https://img.shields.io/npm/v/masonry-snap-grid-layout?color=brightgreen)](https://www.npmjs.com/package/masonry-snap-grid-layout)
+[![CI/CD](https://github.com/khachatryan-dev/masonry-snap-grid-layout/actions/workflows/publish.yml/badge.svg)](https://github.com/khachatryan-dev/masonry-snap-grid-layout/actions)
+[![Demo Vanilla JS](https://img.shields.io/badge/demo-vanilla%20js-blue)](https://codesandbox.io/p/sandbox/l9xl7s)
+[![Demo React](https://img.shields.io/badge/demo-react-blue)](https://codesandbox.io/p/sandbox/rgxsxp)
+
+A performant masonry grid layout library with smooth animations, customizable gutter, columns, and dynamic item content.
+
+![Masonry Grid Demo](https://i.imgur.com/JQZ4L7C.gif)
+
+---
+
+## 🚀 Features
+
+- **Dynamic Columns & Gutter**: Automatically adapts to container width
+- **Smooth Animations**: CSS-powered transitions when layout changes
+- **Customizable Items**: Render any content with gradient backgrounds and emojis
+- **Lightweight**: Zero dependencies, pure TypeScript
+- **React & Vanilla JS**: Works with both React and plain JavaScript
+- **Responsive**: Perfect for galleries, dashboards, and card layouts
+
+---
+
+## 🔧 Installation
+
+```bash
+npm install masonry-snap-grid-layout
+# or
+yarn add masonry-snap-grid-layout
+# or
+pnpm add masonry-snap-grid-layout
+```
+
+---
+
+## 💡 Usage Examples
+
+### Vanilla JavaScript (Live Demo)
+
+```javascript
+import MasonrySnapGridLayout from 'masonry-snap-grid-layout';
+import 'masonry-snap-grid-layout/dist/index.css';
+
+const container = document.getElementById('masonry-container');
+const items = [
+  { id: 1, title: "Sunset", emoji: "🌅", color: "#FF9A9E" },
+  { id: 2, title: "Ocean", emoji: "🌊", color: "#A1C4FD" },
+  // ... more items
+];
+
+const masonry = new MasonrySnapGridLayout(container, {
+  gutter: 16,
+  minColWidth: 200,
+  animate: true,
+  transitionDuration: 300,
+  items: items,
+  renderItem: (item) => {
+    const div = document.createElement('div');
+    div.style.height = `${120 + Math.random() * 200}px`;
+    div.style.background = `linear-gradient(135deg, ${item.color} 0%, #FFFFFF 100%)`;
+    div.style.borderRadius = '12px';
+    div.style.padding = '16px';
+    div.style.color = '#333';
+    div.innerHTML = `
+      <div style="font-size: 2rem">${item.emoji}</div>
+      <h3 style="margin: 8px 0">${item.title}</h3>
+    `;
+    return div;
+  }
+});
+```
+
+[![Open Vanilla Demo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/sandbox/l9xl7s)
+
+---
+
+### React (Live Demo)
+
+```jsx
+import MasonrySnapGrid from 'masonry-snap-grid-layout/react';
+import 'masonry-snap-grid-layout/dist/index.css';
+
+const items = Array.from({ length: 20 }, (_, i) => ({
+  id: i,
+  title: `Item ${i + 1}`,
+  emoji: ['🌻', '🌈', '🍕', '🎸', '🚀'][Math.floor(Math.random() * 5)],
+  height: 120 + Math.random() * 200
+}));
+
+export default function Gallery() {
+  return (
+    <MasonrySnapGrid
+      items={items}
+      gutter={16}
+      minColWidth={220}
+      animate
+      transitionDuration={400}
+      renderItem={(item) => (
+        <div style={{
+          height: `${item.height}px`,
+          background: `linear-gradient(135deg, 
+            hsl(${Math.random() * 360}, 70%, 70%) 0%, 
+            hsl(${Math.random() * 360}, 70%, 80%) 100%)`,
+          borderRadius: '12px',
+          padding: '16px',
+          color: 'white'
+        }}>
+          <div style={{ fontSize: '2rem' }}>{item.emoji}</div>
+          <h3 style={{ margin: '8px 0' }}>{item.title}</h3>
+          <small>Height: {Math.round(item.height)}px</small>
+        </div>
+      )}
+    />
+  );
+}
+```
+
+[![Open React Demo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/sandbox/rgxsxp)
+
+---
+
+## 🛠️ API Reference
+
+### Configuration Options
+
+| Option               | Type                      | Default | Description                          |
+|----------------------|---------------------------|---------|--------------------------------------|
+| `gutter`             | `number`                  | `16`    | Spacing between items (px)           |
+| `minColWidth`        | `number`                  | `250`   | Minimum column width (px)            |
+| `animate`            | `boolean`                 | `true`  | Enable/disable animations            |
+| `transitionDuration` | `number`                  | `400`   | Animation duration (ms)              |
+| `items`              | `Array<T>`                | `[]`    | Your data items                      |
+| `renderItem`         | `(item: T) => HTMLElement`| -       | Function to render each item         |
+| `classNames`         | `Object`                  | -       | Custom CSS class names               |
+
+### Methods
+
+- `updateItems(newItems: T[])`: Refresh with new items
+- `shuffleItems()`: Randomize item positions
+- `destroy()`: Clean up the instance
+
+---
+
+## 🎨 Customization Tips
+
+**1. Gradient Backgrounds**  
+Use CSS gradients for beautiful card backgrounds:
+
+```css
+background: linear-gradient(135deg, #ff9a9e 0%, #fad0c4 100%);
+```
+
+**2. Random Emojis**  
+Add personality with emojis:
+
+```javascript
+const emojis = ['🌻', '🌈', '🍕', '🎸', '🚀'];
+const randomEmoji = emojis[Math.floor(Math.random() * emojis.length)];
+```
+
+**3. Responsive Breakpoints**  
+Adjust columns based on screen size:
+
+```javascript
+minColWidth: window.innerWidth < 768 ? 150 : 250
+```
+
+---
+
+## 📦 Package Structure
+
+```
+dist/
+├── index.js       # Vanilla JS bundle
+├── react.js       # React component
+├── index.d.ts     # TypeScript types
+└── index.css      # Base styles
+```
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+
+
+---
+
+## 📄 License
+
 MIT © [Aram Khachatryan](https://github.com/khachatryan-dev)

package/dist/MasonrySnapGridLayout-CPmdhc_q.d.cts

@@ -0,0 +1,123 @@
+/**
+ * CSS class names used by MasonrySnapGridLayout for styling.
+ */
+interface MasonrySnapGridLayoutClassNames {
+    /** CSS class applied to the container element. */
+    container?: string;
+    /** CSS class applied to each item element. */
+    item?: string;
+}
+/**
+ * Options for configuring a MasonrySnapGridLayout instance.
+ *
+ * @template T - The type of items being rendered in the masonry grid.
+ */
+interface MasonrySnapGridLayoutOptions<T = unknown> {
+    /**
+     * Space between grid items in pixels.
+     * @default 16
+     */
+    gutter?: number;
+    /**
+     * Minimum width (in pixels) of each column before layout will add another column.
+     * @default 250
+     */
+    minColWidth?: number;
+    /**
+     * Whether to animate item movement when the layout changes.
+     * @default true
+     */
+    animate?: boolean;
+    /**
+     * Duration of the item movement animation (in milliseconds).
+     * Only applies if `animate` is true.
+     * @default 400
+     */
+    transitionDuration?: number;
+    /**
+     * Data items to be rendered in the grid.
+     */
+    items: T[];
+    /**
+     * Function that renders a single item into a DOM element.
+     *
+     * @param item - The data item to render.
+     * @returns A DOM element representing the rendered item.
+     */
+    renderItem: (item: T) => HTMLElement;
+    /**
+     * Optional custom class names for the container and items.
+     */
+    classNames?: MasonrySnapGridLayoutClassNames;
+}
+/**
+ * Ref object shape for accessing a MasonrySnapGridLayout instance
+ * when used inside a React component.
+ */
+interface MasonrySnapGridRef {
+    /** Reference to the underlying MasonrySnapGridLayout instance. */
+    layout: MasonrySnapGridLayout | null;
+}
+
+/**
+ * MasonrySnapGridLayout
+ *
+ * A lightweight, generic TypeScript implementation of a responsive Masonry-style grid layout
+ * with optional animations, custom rendering, and automatic re-layout on resize.
+ *
+ * @template T - The type of data items that will be rendered into grid elements.
+ */
+declare class MasonrySnapGridLayout<T = any> {
+    /** The container element where the Masonry grid will be rendered. */
+    private readonly container;
+    /** Fully resolved options object with defaults merged. */
+    private readonly options;
+    /** A reference to all grid item elements currently rendered. */
+    private items;
+    /** Tracks the current heights of each column to position new items. */
+    private columnHeights;
+    /** Observes container resizing to trigger re-layout. */
+    private resizeObserver;
+    /** Stores requestAnimationFrame ID for layout updates to prevent redundant calls. */
+    private rafId;
+    /**
+     * Creates a new MasonrySnapGridLayout instance.
+     *
+     * @param container - The HTML element that will act as the grid container.
+     * @param options - Partial configuration object for layout behavior and rendering.
+     */
+    constructor(container: HTMLElement, options: MasonrySnapGridLayoutOptions<T>);
+    /**
+     * Renders the provided items into the container.
+     * Clears previous items and re-builds DOM structure.
+     */
+    private renderItems;
+    /**
+     * Sets up a ResizeObserver to re-calculate layout when container size changes.
+     */
+    private setupResizeObserver;
+    /**
+     * Calculates item positions and updates their transforms.
+     * Also adjusts the container height to fit all items.
+     */
+    private updateLayout;
+    /**
+     * Finds the index of the column with the smallest total height.
+     *
+     * @returns Index of the shortest column.
+     */
+    private findShortestColumn;
+    /**
+     * Replaces current items with a new set and re-renders the layout.
+     *
+     * @param newItems - New set of data items to render.
+     */
+    updateItems(newItems: T[]): void;
+    /**
+     * Cleans up event listeners, observers, and DOM modifications.
+     * This should be called before discarding the instance.
+     */
+    destroy(): void;
+}
+
+export { MasonrySnapGridLayout as M, type MasonrySnapGridLayoutOptions as a, type MasonrySnapGridRef as b };

package/dist/MasonrySnapGridLayout-CPmdhc_q.d.ts

@@ -0,0 +1,123 @@
+/**
+ * CSS class names used by MasonrySnapGridLayout for styling.
+ */
+interface MasonrySnapGridLayoutClassNames {
+    /** CSS class applied to the container element. */
+    container?: string;
+    /** CSS class applied to each item element. */
+    item?: string;
+}
+/**
+ * Options for configuring a MasonrySnapGridLayout instance.
+ *
+ * @template T - The type of items being rendered in the masonry grid.
+ */
+interface MasonrySnapGridLayoutOptions<T = unknown> {
+    /**
+     * Space between grid items in pixels.
+     * @default 16
+     */
+    gutter?: number;
+    /**
+     * Minimum width (in pixels) of each column before layout will add another column.
+     * @default 250
+     */
+    minColWidth?: number;
+    /**
+     * Whether to animate item movement when the layout changes.
+     * @default true
+     */
+    animate?: boolean;
+    /**
+     * Duration of the item movement animation (in milliseconds).
+     * Only applies if `animate` is true.
+     * @default 400
+     */
+    transitionDuration?: number;
+    /**
+     * Data items to be rendered in the grid.
+     */
+    items: T[];
+    /**
+     * Function that renders a single item into a DOM element.
+     *
+     * @param item - The data item to render.
+     * @returns A DOM element representing the rendered item.
+     */
+    renderItem: (item: T) => HTMLElement;
+    /**
+     * Optional custom class names for the container and items.
+     */
+    classNames?: MasonrySnapGridLayoutClassNames;
+}
+/**
+ * Ref object shape for accessing a MasonrySnapGridLayout instance
+ * when used inside a React component.
+ */
+interface MasonrySnapGridRef {
+    /** Reference to the underlying MasonrySnapGridLayout instance. */
+    layout: MasonrySnapGridLayout | null;
+}
+
+/**
+ * MasonrySnapGridLayout
+ *
+ * A lightweight, generic TypeScript implementation of a responsive Masonry-style grid layout
+ * with optional animations, custom rendering, and automatic re-layout on resize.
+ *
+ * @template T - The type of data items that will be rendered into grid elements.
+ */
+declare class MasonrySnapGridLayout<T = any> {
+    /** The container element where the Masonry grid will be rendered. */
+    private readonly container;
+    /** Fully resolved options object with defaults merged. */
+    private readonly options;
+    /** A reference to all grid item elements currently rendered. */
+    private items;
+    /** Tracks the current heights of each column to position new items. */
+    private columnHeights;
+    /** Observes container resizing to trigger re-layout. */
+    private resizeObserver;
+    /** Stores requestAnimationFrame ID for layout updates to prevent redundant calls. */
+    private rafId;
+    /**
+     * Creates a new MasonrySnapGridLayout instance.
+     *
+     * @param container - The HTML element that will act as the grid container.
+     * @param options - Partial configuration object for layout behavior and rendering.
+     */
+    constructor(container: HTMLElement, options: MasonrySnapGridLayoutOptions<T>);
+    /**
+     * Renders the provided items into the container.
+     * Clears previous items and re-builds DOM structure.
+     */
+    private renderItems;
+    /**
+     * Sets up a ResizeObserver to re-calculate layout when container size changes.
+     */
+    private setupResizeObserver;
+    /**
+     * Calculates item positions and updates their transforms.
+     * Also adjusts the container height to fit all items.
+     */
+    private updateLayout;
+    /**
+     * Finds the index of the column with the smallest total height.
+     *
+     * @returns Index of the shortest column.
+     */
+    private findShortestColumn;
+    /**
+     * Replaces current items with a new set and re-renders the layout.
+     *
+     * @param newItems - New set of data items to render.
+     */
+    updateItems(newItems: T[]): void;
+    /**
+     * Cleans up event listeners, observers, and DOM modifications.
+     * This should be called before discarding the instance.
+     */
+    destroy(): void;
+}
+
+export { MasonrySnapGridLayout as M, type MasonrySnapGridLayoutOptions as a, type MasonrySnapGridRef as b };

package/dist/esm/index.css.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/index.css"],"sourcesContent":[".masonry-snap-grid-container {\r\n    position: relative;\r\n    width: 100%;\r\n    transition: height 0.4s ease-out;\r\n    overflow: hidden;\r\n}\r\n\r\n.masonry-snap-grid-item {\r\n    position: absolute;\r\n    transition: transform 0.4s cubic-bezier(0.4, 0, 0.2, 1);\r\n    will-change: transform;\r\n    box-sizing: border-box;\r\n    transform-origin: top left;\r\n    backface-visibility: hidden;\r\n    perspective: 1000px;\r\n}"],"mappings":";AAAA,CAAC;AACG,YAAU;AACV,SAAO;AACP,cAAY,OAAO,KAAK;AACxB,YAAU;AACd;AAEA,CAAC;AACG,YAAU;AACV,cAAY,UAAU,KAAK,aAAa,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE;AACrD,eAAa;AACb,cAAY;AACZ,oBAAkB,IAAI;AACtB,uBAAqB;AACrB,eAAa;AACjB;","names":[]}
+{"version":3,"sources":["../../src/index.css"],"sourcesContent":["/* \n====================================================================\nMasonrySnapGridLayout - Base Styles\n====================================================================\nThese styles define the core visual and positional behavior of the \nmasonry grid container and its items. They are minimal to allow \nflexibility for custom themes while ensuring smooth layout animations.\n====================================================================\n*/\n\n/* \nContainer styles:\n- Acts as the positioning context for masonry items (position: relative).\n- Takes full available width.\n- Smoothly animates height changes when items reflow.\n- Hides overflow to prevent content from spilling outside the layout.\n*/\n.masonry-snap-grid-container {\n    position: relative;\n    width: 100%;\n    transition: height 0.4s ease-out;\n    overflow: hidden;\n}\n\n/* \nItem styles:\n- Absolutely positioned within the container.\n- Animates transform changes for smooth reordering.\n- Uses GPU-accelerated transform optimizations (`will-change`, `backface-visibility`).\n- Sets `box-sizing: border-box` for consistent sizing with padding/border.\n- `transform-origin` ensures scaling/rotation pivot from the top-left corner.\n- `perspective` enables subtle 3D rendering improvements on some browsers.\n*/\n.masonry-snap-grid-item {\n    position: absolute;\n    transition: transform 0.4s cubic-bezier(0.4, 0, 0.2, 1);\n    will-change: transform;\n    box-sizing: border-box;\n    transform-origin: top left;\n    backface-visibility: hidden;\n    perspective: 1000px;\n}\n"],"mappings":";AAiBA,CAAC;AACG,YAAU;AACV,SAAO;AACP,cAAY,OAAO,KAAK;AACxB,YAAU;AACd;AAWA,CAAC;AACG,YAAU;AACV,cAAY,UAAU,KAAK,aAAa,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE;AACrD,eAAa;AACb,cAAY;AACZ,oBAAkB,IAAI;AACtB,uBAAqB;AACrB,eAAa;AACjB;","names":[]}