masonry-snap-grid-layout 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,90 @@
+# masonry-snap-grid-layout
+
+A performant masonry grid layout library with smooth animations, customizable gutter, columns, and dynamic item content.
+
+---
+
+## 🚀 Features
+
+- **Dynamic Columns & Gutter**: Automatically adapts to container width.
+- **Smooth Animations**: Transitions when layout changes or items shuffle.
+- **Customizable Item Content**: Pass your own HTML or render functions.
+- **Lightweight & Dependency-Free**: Vanilla TypeScript for easy integration.
+- **Responsive & Accessible**: Works well on all screen sizes.
+
+---
+
+## 🔧 Installation
+
+```bash
+npm install masonry-snap-grid-layout
+# or
+yarn add masonry-snap-grid-layout
+```
+
+---
+
+## 💡 Usage Example
+
+```ts
+import { MasonrySnapGridLayout } from 'masonry-snap-grid-layout';
+
+const container = document.getElementById('masonry-container')!;
+const masonry = new MasonrySnapGridLayout(container, {
+  gutter: 12,
+  minColWidth: 200,
+  initialItems: 20,
+  animate: true,
+  transitionDuration: 350,
+  itemContent: (index) => {
+    const div = document.createElement('div');
+    div.textContent = `Custom Item #${index + 1}`;
+    div.style.padding = '10px';
+    div.style.backgroundColor = '#ddd';
+    div.style.borderRadius = '8px';
+    return div;
+  }
+});
+```
+
+---
+
+## ⚙️ API
+
+### Constructor
+
+`new MasonrySnapGridLayout(container: HTMLElement, options?: MasonrySnapGridLayoutOptions)`
+
+- **container** — The container element where items are rendered.
+- **options** — Configuration options (optional).
+
+### Methods
+
+- `shuffleItems(): void` — Shuffle items randomly with animation.
+- `addItems(count: number): void` — Add more items dynamically.
+
+---
+
+## 🛠️ Options
+
+| Option             | Type                               | Default     | Description                              |
+|--------------------|----------------------------------|-------------|------------------------------------------|
+| `gutter`           | `number`                         | `16`        | Spacing between items in pixels.        |
+| `minColWidth`      | `number`                         | `250`       | Minimum column width in pixels.         |
+| `animate`          | `boolean`                        | `true`      | Enable/disable animations.               |
+| `transitionDuration` | `number`                       | `400`       | Animation duration in milliseconds.     |
+| `initialItems`     | `number`                         | `30`        | Number of items generated initially.    |
+| `classNames`       | `object`                         | Default CSS classes | Override CSS class names for styling.   |
+| `itemContent`      | `string` \| `HTMLElement` \| `(index: number) => HTMLElement \| string` | `null` | Content or content generator callback for items. |
+
+---
+
+## 🎨 Styling
+
+You can customize the styles by overriding the CSS classes defined or by providing your own CSS class names through `classNames` option.
+
+---
+
+## 📄 License
+
+MIT © Aram Khachatryan

package/dist/esm/index.js

@@ -0,0 +1,243 @@
+// src/MasonrySnapGridLayout.ts
+var MasonrySnapGridLayout = class {
+  container;
+  options;
+  classNames;
+  items = [];
+  positions = [];
+  columnHeights = [];
+  columns = 0;
+  lastPositions = [];
+  resizeRaf = null;
+  /**
+   * Constructor initializes the layout with container element and options
+   * @param container HTMLElement container where masonry items are rendered
+   * @param options configuration options for layout and styling
+   */
+  constructor(container, options = {}) {
+    this.container = container;
+    this.options = {
+      gutter: 16,
+      minColWidth: 250,
+      animate: true,
+      transitionDuration: 400,
+      initialItems: 30,
+      itemContent: null,
+      classNames: {
+        container: "masonry-snap-grid-layout-container",
+        item: "masonry-snap-grid-layout-item",
+        itemContent: "item-content",
+        itemHeader: "item-header",
+        itemTitle: "item-title",
+        itemId: "item-id",
+        itemBody: "item-body",
+        progressBar: "progress-bar",
+        progress: "progress",
+        itemFooter: "item-footer"
+      },
+      ...options
+    };
+    this.classNames = {
+      container: "masonry-snap-grid-layout-container",
+      item: "masonry-snap-grid-layout-item",
+      itemContent: "item-content",
+      itemHeader: "item-header",
+      itemTitle: "item-title",
+      itemId: "item-id",
+      itemBody: "item-body",
+      progressBar: "progress-bar",
+      progress: "progress",
+      itemFooter: "item-footer",
+      ...this.options.classNames || {}
+    };
+    this.container.classList.add(this.classNames.container);
+    this.init();
+  }
+  /**
+   * Initialization: set listeners, generate initial items, layout
+   */
+  init() {
+    this.setupEventListeners();
+    this.generateItems(this.options.initialItems);
+    this.calculateLayout();
+    this.applyLayout(false);
+  }
+  /**
+   * Setup event listeners for window resize and container resize observer
+   */
+  setupEventListeners() {
+    const resizeObserver = new ResizeObserver(() => this.handleResize());
+    resizeObserver.observe(this.container);
+    window.addEventListener("resize", () => this.handleResize());
+  }
+  /**
+   * Generate specified number of items, removing excess if any
+   * @param count number of items to generate
+   */
+  generateItems(count) {
+    if (count < this.items.length) {
+      this.items.slice(count).forEach((item) => item.remove());
+      this.items = this.items.slice(0, count);
+      return;
+    }
+    const startIndex = this.items.length;
+    const fragment = document.createDocumentFragment();
+    for (let i = startIndex; i < count; i++) {
+      const item = this.createItem(i);
+      fragment.appendChild(item);
+      this.items.push(item);
+    }
+    this.container.appendChild(fragment);
+  }
+  /**
+   * Create a single masonry item HTMLElement, with content from renderItemContent callback or default template
+   * @param index index of the item
+   * @returns HTMLElement for the item
+   */
+  createItem(index) {
+    const div = document.createElement("div");
+    div.className = this.classNames.item;
+    const contentOption = this.options.itemContent;
+    let content;
+    if (typeof contentOption === "function") {
+      content = contentOption(index);
+    } else if (contentOption instanceof HTMLElement || typeof contentOption === "string") {
+      content = contentOption;
+    } else {
+      content = this.defaultItemContent(index);
+    }
+    if (typeof content === "string") {
+      div.innerHTML = content;
+    } else {
+      div.appendChild(content);
+    }
+    const height = 120 + Math.floor(Math.random() * 180);
+    div.style.height = `${height}px`;
+    const hue = index * 137.508 % 360;
+    div.style.background = `linear-gradient(135deg, hsl(${hue}, 70%, 60%), hsl(${hue + 40}, 70%, 50%))`;
+    return div;
+  }
+  /**
+   * Default item content template string
+   * @param index index of the item
+   * @returns string HTML template for item content
+   */
+  defaultItemContent(index) {
+    return `
+      <div class="${this.classNames.itemContent}">
+        <div class="${this.classNames.itemHeader}">
+          <div class="${this.classNames.itemTitle}">Item ${index + 1}</div>
+          <div class="${this.classNames.itemId}">#${index + 1}</div>
+        </div>
+        <div class="${this.classNames.itemBody}">
+          <div class="${this.classNames.progressBar}">
+            <div class="${this.classNames.progress}"></div>
+          </div>
+        </div>
+        <div class="${this.classNames.itemFooter}">
+          ${this.getRandomEmoji()}
+        </div>
+      </div>
+    `;
+  }
+  /**
+   * Returns a random emoji from a fixed set for item footer
+   */
+  getRandomEmoji() {
+    const emojis = ["\u{1F680}", "\u2728", "\u{1F525}", "\u{1F4A1}", "\u{1F31F}", "\u{1F3AF}", "\u26A1", "\u{1F4BB}", "\u{1F527}", "\u{1F4CA}"];
+    return emojis[Math.floor(Math.random() * emojis.length)];
+  }
+  /**
+   * Calculate positions of each item in masonry grid based on container width, gutter, min column width
+   */
+  calculateLayout() {
+    const { gutter, minColWidth } = this.options;
+    const containerWidth = this.container.clientWidth;
+    this.columns = Math.max(1, Math.floor((containerWidth + gutter) / (minColWidth + gutter)));
+    const colWidth = (containerWidth - (this.columns - 1) * gutter) / this.columns;
+    this.lastPositions = [...this.positions];
+    this.columnHeights = new Array(this.columns).fill(0);
+    this.positions = [];
+    this.items.forEach((item, i) => {
+      const height = item.offsetHeight;
+      let minCol = 0;
+      for (let c = 1; c < this.columns; c++) {
+        if (this.columnHeights[c] < this.columnHeights[minCol]) {
+          minCol = c;
+        }
+      }
+      const x = minCol * (colWidth + gutter);
+      const y = this.columnHeights[minCol];
+      this.positions[i] = { x, y, width: colWidth, height };
+      this.columnHeights[minCol] += height + gutter;
+    });
+    const maxHeight = Math.max(...this.columnHeights);
+    this.container.style.height = `${maxHeight}px`;
+  }
+  /**
+   * Apply calculated positions to each item with optional animation
+   * @param animate whether to animate layout changes (default false)
+   */
+  applyLayout(animate = false) {
+    const duration = this.options.transitionDuration;
+    this.items.forEach((item, i) => {
+      const pos = this.positions[i] || { x: 0, y: 0, width: 0 };
+      const lastPos = this.lastPositions[i] || { x: 0, y: 0 };
+      item.style.width = `${pos.width}px`;
+      if (animate) {
+        const dx = lastPos.x - pos.x;
+        const dy = lastPos.y - pos.y;
+        item.style.transition = "none";
+        item.style.transform = `translate3d(${pos.x + dx}px, ${pos.y + dy}px, 0)`;
+        void item.offsetHeight;
+        item.style.transition = `transform ${duration}ms cubic-bezier(0.4, 0, 0.2, 1)`;
+        item.style.transform = `translate3d(${pos.x}px, ${pos.y}px, 0)`;
+      } else {
+        item.style.transition = "none";
+        item.style.transform = `translate3d(${pos.x}px, ${pos.y}px, 0)`;
+      }
+    });
+  }
+  /**
+   * Handle container resize using RAF to optimize performance
+   */
+  handleResize() {
+    if (this.resizeRaf) cancelAnimationFrame(this.resizeRaf);
+    this.resizeRaf = requestAnimationFrame(() => {
+      this.calculateLayout();
+      this.applyLayout(true);
+    });
+  }
+  /**
+   * Shuffle items randomly and reapply layout with animation
+   */
+  shuffleItems() {
+    for (let i = this.items.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [this.items[i], this.items[j]] = [this.items[j], this.items[i]];
+    }
+    const fragment = document.createDocumentFragment();
+    this.items.forEach((item) => fragment.appendChild(item));
+    this.container.appendChild(fragment);
+    this.calculateLayout();
+    this.applyLayout(true);
+  }
+  /**
+   * Add more items dynamically
+   * @param count number of items to add
+   */
+  addItems(count) {
+    const newCount = this.items.length + count;
+    this.generateItems(newCount);
+    this.calculateLayout();
+    this.applyLayout(true);
+  }
+};
+
+// src/index.ts
+var index_default = MasonrySnapGridLayout;
+export {
+  MasonrySnapGridLayout,
+  index_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/MasonrySnapGridLayout.ts","../../src/index.ts"],"sourcesContent":["/**\r\n * MasonrySnapGridLayout\r\n * A performant masonry grid layout library with smooth animations,\r\n * customizable gutter, columns, and dynamic item content.\r\n *\r\n * Package name: masonry-snap-grid-layout\r\n */\r\n\r\nimport { MasonrySnapGridLayoutClassNames, MasonrySnapGridLayoutOptions } from \"./types\";\r\n\r\nexport default class MasonrySnapGridLayout {\r\n    private readonly container: HTMLElement;\r\n    private readonly options: Required<MasonrySnapGridLayoutOptions>;\r\n    private classNames: Required<MasonrySnapGridLayoutClassNames>;\r\n\r\n    private items: HTMLElement[] = [];\r\n    private positions: { x: number; y: number; width: number; height: number }[] = [];\r\n    private columnHeights: number[] = [];\r\n    private columns: number = 0;\r\n    private lastPositions: typeof this.positions = [];\r\n    private resizeRaf: number | null = null;\r\n\r\n    /**\r\n     * Constructor initializes the layout with container element and options\r\n     * @param container HTMLElement container where masonry items are rendered\r\n     * @param options configuration options for layout and styling\r\n     */\r\n    constructor(container: HTMLElement, options: MasonrySnapGridLayoutOptions = {}) {\r\n        this.container = container;\r\n\r\n        // Set default options with overrides from user\r\n        this.options = {\r\n            gutter: 16,\r\n            minColWidth: 250,\r\n            animate: true,\r\n            transitionDuration: 400,\r\n            initialItems: 30,\r\n            itemContent: null,\r\n            classNames: {\r\n                container: \"masonry-snap-grid-layout-container\",\r\n                item: \"masonry-snap-grid-layout-item\",\r\n                itemContent: \"item-content\",\r\n                itemHeader: \"item-header\",\r\n                itemTitle: \"item-title\",\r\n                itemId: \"item-id\",\r\n                itemBody: \"item-body\",\r\n                progressBar: \"progress-bar\",\r\n                progress: \"progress\",\r\n                itemFooter: \"item-footer\",\r\n            },\r\n            ...options,\r\n        };\r\n\r\n        // Merge default classNames with user provided classNames\r\n        this.classNames = {\r\n            container: \"masonry-snap-grid-layout-container\",\r\n            item: \"masonry-snap-grid-layout-item\",\r\n            itemContent: \"item-content\",\r\n            itemHeader: \"item-header\",\r\n            itemTitle: \"item-title\",\r\n            itemId: \"item-id\",\r\n            itemBody: \"item-body\",\r\n            progressBar: \"progress-bar\",\r\n            progress: \"progress\",\r\n            itemFooter: \"item-footer\",\r\n            ...(this.options.classNames || {}),\r\n        };\r\n\r\n        // Add container class for styling\r\n        this.container.classList.add(this.classNames.container);\r\n\r\n        // Initialize the layout\r\n        this.init();\r\n    }\r\n\r\n    /**\r\n     * Initialization: set listeners, generate initial items, layout\r\n     */\r\n    private init() {\r\n        this.setupEventListeners();\r\n        this.generateItems(this.options.initialItems);\r\n        this.calculateLayout();\r\n        this.applyLayout(false);\r\n    }\r\n\r\n    /**\r\n     * Setup event listeners for window resize and container resize observer\r\n     */\r\n    private setupEventListeners() {\r\n        // Use ResizeObserver to handle container size changes\r\n        const resizeObserver = new ResizeObserver(() => this.handleResize());\r\n        resizeObserver.observe(this.container);\r\n\r\n        window.addEventListener(\"resize\", () => this.handleResize());\r\n    }\r\n\r\n    /**\r\n     * Generate specified number of items, removing excess if any\r\n     * @param count number of items to generate\r\n     */\r\n    private generateItems(count: number) {\r\n        // Remove extra items if reducing count\r\n        if (count < this.items.length) {\r\n            this.items.slice(count).forEach((item) => item.remove());\r\n            this.items = this.items.slice(0, count);\r\n            return;\r\n        }\r\n\r\n        const startIndex = this.items.length;\r\n        const fragment = document.createDocumentFragment();\r\n\r\n        for (let i = startIndex; i < count; i++) {\r\n            const item = this.createItem(i);\r\n            fragment.appendChild(item);\r\n            this.items.push(item);\r\n        }\r\n\r\n        this.container.appendChild(fragment);\r\n    }\r\n\r\n    /**\r\n     * Create a single masonry item HTMLElement, with content from renderItemContent callback or default template\r\n     * @param index index of the item\r\n     * @returns HTMLElement for the item\r\n     */\r\n    private createItem(index: number): HTMLElement {\r\n        const div = document.createElement(\"div\");\r\n        div.className = this.classNames.item;\r\n\r\n        const contentOption = this.options.itemContent;\r\n\r\n        // Determine content type: function, static HTMLElement, static string, or fallback to default\r\n        let content: HTMLElement | string;\r\n\r\n        if (typeof contentOption === \"function\") {\r\n            // Call function with index to get content\r\n            content = contentOption(index);\r\n        } else if (contentOption instanceof HTMLElement || typeof contentOption === \"string\") {\r\n            // Use static content\r\n            content = contentOption;\r\n        } else {\r\n            // Fallback to default item content template string\r\n            content = this.defaultItemContent(index);\r\n        }\r\n\r\n        // Insert content into item element\r\n        if (typeof content === \"string\") {\r\n            div.innerHTML = content;\r\n        } else {\r\n            div.appendChild(content);\r\n        }\r\n\r\n        // Random height to simulate masonry effect\r\n        const height = 120 + Math.floor(Math.random() * 180);\r\n        div.style.height = `${height}px`;\r\n\r\n        // Color with HSL for distinct appearance\r\n        const hue = (index * 137.508) % 360; // golden angle\r\n        div.style.background = `linear-gradient(135deg, hsl(${hue}, 70%, 60%), hsl(${hue + 40}, 70%, 50%))`;\r\n\r\n        return div;\r\n    }\r\n\r\n    /**\r\n     * Default item content template string\r\n     * @param index index of the item\r\n     * @returns string HTML template for item content\r\n     */\r\n    private defaultItemContent(index: number): string {\r\n        return `\r\n      <div class=\"${this.classNames.itemContent}\">\r\n        <div class=\"${this.classNames.itemHeader}\">\r\n          <div class=\"${this.classNames.itemTitle}\">Item ${index + 1}</div>\r\n          <div class=\"${this.classNames.itemId}\">#${index + 1}</div>\r\n        </div>\r\n        <div class=\"${this.classNames.itemBody}\">\r\n          <div class=\"${this.classNames.progressBar}\">\r\n            <div class=\"${this.classNames.progress}\"></div>\r\n          </div>\r\n        </div>\r\n        <div class=\"${this.classNames.itemFooter}\">\r\n          ${this.getRandomEmoji()}\r\n        </div>\r\n      </div>\r\n    `;\r\n    }\r\n\r\n    /**\r\n     * Returns a random emoji from a fixed set for item footer\r\n     */\r\n    private getRandomEmoji(): string {\r\n        const emojis = [\"🚀\", \"✨\", \"🔥\", \"💡\", \"🌟\", \"🎯\", \"⚡\", \"💻\", \"🔧\", \"📊\"];\r\n        return emojis[Math.floor(Math.random() * emojis.length)];\r\n    }\r\n\r\n    /**\r\n     * Calculate positions of each item in masonry grid based on container width, gutter, min column width\r\n     */\r\n    private calculateLayout() {\r\n        const { gutter, minColWidth } = this.options;\r\n        const containerWidth = this.container.clientWidth;\r\n\r\n        // Calculate number of columns that fit\r\n        this.columns = Math.max(1, Math.floor((containerWidth + gutter) / (minColWidth + gutter)));\r\n\r\n        // Calculate each column width\r\n        const colWidth = (containerWidth - (this.columns - 1) * gutter) / this.columns;\r\n\r\n        // Store previous positions for animation\r\n        this.lastPositions = [...this.positions];\r\n\r\n        // Reset column heights array\r\n        this.columnHeights = new Array(this.columns).fill(0);\r\n        this.positions = [];\r\n\r\n        // Calculate position for each item and assign column\r\n        this.items.forEach((item, i) => {\r\n            const height = item.offsetHeight;\r\n\r\n            // Find the shortest column index\r\n            let minCol = 0;\r\n            for (let c = 1; c < this.columns; c++) {\r\n                if (this.columnHeights[c] < this.columnHeights[minCol]) {\r\n                    minCol = c;\r\n                }\r\n            }\r\n\r\n            // Calculate item's x,y position\r\n            const x = minCol * (colWidth + gutter);\r\n            const y = this.columnHeights[minCol];\r\n\r\n            // Save calculated position\r\n            this.positions[i] = { x, y, width: colWidth, height };\r\n\r\n            // Update column height to include this item + gutter\r\n            this.columnHeights[minCol] += height + gutter;\r\n        });\r\n\r\n        // Set container height to max column height for proper scrolling\r\n        const maxHeight = Math.max(...this.columnHeights);\r\n        this.container.style.height = `${maxHeight}px`;\r\n    }\r\n\r\n    /**\r\n     * Apply calculated positions to each item with optional animation\r\n     * @param animate whether to animate layout changes (default false)\r\n     */\r\n    private applyLayout(animate: boolean = false) {\r\n        const duration = this.options.transitionDuration;\r\n\r\n        this.items.forEach((item, i) => {\r\n            const pos = this.positions[i] || { x: 0, y: 0, width: 0 };\r\n            const lastPos = this.lastPositions[i] || { x: 0, y: 0 };\r\n\r\n            // Set item width for responsive columns\r\n            item.style.width = `${pos.width}px`;\r\n\r\n            if (animate) {\r\n                // Calculate differences for smooth animation\r\n                const dx = lastPos.x - pos.x;\r\n                const dy = lastPos.y - pos.y;\r\n\r\n                // Apply initial transform to old position (without transition)\r\n                item.style.transition = \"none\";\r\n                item.style.transform = `translate3d(${pos.x + dx}px, ${pos.y + dy}px, 0)`;\r\n\r\n                // Trigger reflow to apply the style immediately\r\n                void item.offsetHeight;\r\n\r\n                // Animate transform to new position\r\n                item.style.transition = `transform ${duration}ms cubic-bezier(0.4, 0, 0.2, 1)`;\r\n                item.style.transform = `translate3d(${pos.x}px, ${pos.y}px, 0)`;\r\n            } else {\r\n                // Directly set transform without animation\r\n                item.style.transition = \"none\";\r\n                item.style.transform = `translate3d(${pos.x}px, ${pos.y}px, 0)`;\r\n            }\r\n        });\r\n    }\r\n\r\n    /**\r\n     * Handle container resize using RAF to optimize performance\r\n     */\r\n    private handleResize() {\r\n        if (this.resizeRaf) cancelAnimationFrame(this.resizeRaf);\r\n        this.resizeRaf = requestAnimationFrame(() => {\r\n            this.calculateLayout();\r\n            this.applyLayout(true);\r\n        });\r\n    }\r\n\r\n    /**\r\n     * Shuffle items randomly and reapply layout with animation\r\n     */\r\n    public shuffleItems() {\r\n        // Fisher-Yates shuffle algorithm\r\n        for (let i = this.items.length - 1; i > 0; i--) {\r\n            const j = Math.floor(Math.random() * (i + 1));\r\n            [this.items[i], this.items[j]] = [this.items[j], this.items[i]];\r\n        }\r\n\r\n        // Re-append items in new order in DOM\r\n        const fragment = document.createDocumentFragment();\r\n        this.items.forEach((item) => fragment.appendChild(item));\r\n        this.container.appendChild(fragment);\r\n\r\n        // Update layout positions and animate\r\n        this.calculateLayout();\r\n        this.applyLayout(true);\r\n    }\r\n\r\n    /**\r\n     * Add more items dynamically\r\n     * @param count number of items to add\r\n     */\r\n    public addItems(count: number) {\r\n        const newCount = this.items.length + count;\r\n        this.generateItems(newCount);\r\n        this.calculateLayout();\r\n        this.applyLayout(true);\r\n    }\r\n}\r\n","import MasonrySnapGridLayout from './MasonrySnapGridLayout';\nexport default MasonrySnapGridLayout;\nexport { MasonrySnapGridLayout };"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,123 @@
+/**
+ * MasonrySnapGridLayoutClassNames
+ * Optional CSS class names to override default styling selectors.
+ * Enables user to customize CSS classes easily.
+ */
+interface MasonrySnapGridLayoutClassNames {
+    container?: string;
+    item?: string;
+    itemContent?: string;
+    itemHeader?: string;
+    itemTitle?: string;
+    itemId?: string;
+    itemBody?: string;
+    progressBar?: string;
+    progress?: string;
+    itemFooter?: string;
+}
+/**
+ * MasonrySnapGridLayoutOptions
+ * Configuration options accepted by MasonrySnapGridLayout.
+ */
+interface MasonrySnapGridLayoutOptions {
+    /** Spacing between items in pixels (default: 16) */
+    gutter?: number;
+    /** Minimum width for each column in pixels (default: 250) */
+    minColWidth?: number;
+    /** Enable or disable animations (default: true) */
+    animate?: boolean;
+    /** Duration of animation transitions in milliseconds (default: 400) */
+    transitionDuration?: number;
+    /** Initial number of items to generate on init (default: 30) */
+    initialItems?: number;
+    /**
+     * Optional class names object to override default CSS class names
+     */
+    classNames?: MasonrySnapGridLayoutClassNames;
+    /**
+     * Item content can be:
+     * - a callback function that receives the item index and returns an HTMLElement or string (HTML markup),
+     * - a static HTMLElement or string (HTML markup) for all items,
+     * - or null to use the default template.
+     */
+    itemContent?: ((index: number) => HTMLElement | string) | HTMLElement | string | null;
+}
+
+/**
+ * MasonrySnapGridLayout
+ * A performant masonry grid layout library with smooth animations,
+ * customizable gutter, columns, and dynamic item content.
+ *
+ * Package name: masonry-snap-grid-layout
+ */
+
+declare class MasonrySnapGridLayout {
+    private readonly container;
+    private readonly options;
+    private classNames;
+    private items;
+    private positions;
+    private columnHeights;
+    private columns;
+    private lastPositions;
+    private resizeRaf;
+    /**
+     * Constructor initializes the layout with container element and options
+     * @param container HTMLElement container where masonry items are rendered
+     * @param options configuration options for layout and styling
+     */
+    constructor(container: HTMLElement, options?: MasonrySnapGridLayoutOptions);
+    /**
+     * Initialization: set listeners, generate initial items, layout
+     */
+    private init;
+    /**
+     * Setup event listeners for window resize and container resize observer
+     */
+    private setupEventListeners;
+    /**
+     * Generate specified number of items, removing excess if any
+     * @param count number of items to generate
+     */
+    private generateItems;
+    /**
+     * Create a single masonry item HTMLElement, with content from renderItemContent callback or default template
+     * @param index index of the item
+     * @returns HTMLElement for the item
+     */
+    private createItem;
+    /**
+     * Default item content template string
+     * @param index index of the item
+     * @returns string HTML template for item content
+     */
+    private defaultItemContent;
+    /**
+     * Returns a random emoji from a fixed set for item footer
+     */
+    private getRandomEmoji;
+    /**
+     * Calculate positions of each item in masonry grid based on container width, gutter, min column width
+     */
+    private calculateLayout;
+    /**
+     * Apply calculated positions to each item with optional animation
+     * @param animate whether to animate layout changes (default false)
+     */
+    private applyLayout;
+    /**
+     * Handle container resize using RAF to optimize performance
+     */
+    private handleResize;
+    /**
+     * Shuffle items randomly and reapply layout with animation
+     */
+    shuffleItems(): void;
+    /**
+     * Add more items dynamically
+     * @param count number of items to add
+     */
+    addItems(count: number): void;
+}
+
+export { MasonrySnapGridLayout, MasonrySnapGridLayout as default };

package/dist/index.d.ts

@@ -1,3 +1,123 @@
-declare const masonrySnapGridLayout: () => void;
+/**
+ * MasonrySnapGridLayoutClassNames
+ * Optional CSS class names to override default styling selectors.
+ * Enables user to customize CSS classes easily.
+ */
+interface MasonrySnapGridLayoutClassNames {
+    container?: string;
+    item?: string;
+    itemContent?: string;
+    itemHeader?: string;
+    itemTitle?: string;
+    itemId?: string;
+    itemBody?: string;
+    progressBar?: string;
+    progress?: string;
+    itemFooter?: string;
+}
+/**
+ * MasonrySnapGridLayoutOptions
+ * Configuration options accepted by MasonrySnapGridLayout.
+ */
+interface MasonrySnapGridLayoutOptions {
+    /** Spacing between items in pixels (default: 16) */
+    gutter?: number;
+    /** Minimum width for each column in pixels (default: 250) */
+    minColWidth?: number;
+    /** Enable or disable animations (default: true) */
+    animate?: boolean;
+    /** Duration of animation transitions in milliseconds (default: 400) */
+    transitionDuration?: number;
+    /** Initial number of items to generate on init (default: 30) */
+    initialItems?: number;
+    /**
+     * Optional class names object to override default CSS class names
+     */
+    classNames?: MasonrySnapGridLayoutClassNames;
+    /**
+     * Item content can be:
+     * - a callback function that receives the item index and returns an HTMLElement or string (HTML markup),
+     * - a static HTMLElement or string (HTML markup) for all items,
+     * - or null to use the default template.
+     */
+    itemContent?: ((index: number) => HTMLElement | string) | HTMLElement | string | null;
+}
 
-export { masonrySnapGridLayout };
+/**
+ * MasonrySnapGridLayout
+ * A performant masonry grid layout library with smooth animations,
+ * customizable gutter, columns, and dynamic item content.
+ *
+ * Package name: masonry-snap-grid-layout
+ */
+
+declare class MasonrySnapGridLayout {
+    private readonly container;
+    private readonly options;
+    private classNames;
+    private items;
+    private positions;
+    private columnHeights;
+    private columns;
+    private lastPositions;
+    private resizeRaf;
+    /**
+     * Constructor initializes the layout with container element and options
+     * @param container HTMLElement container where masonry items are rendered
+     * @param options configuration options for layout and styling
+     */
+    constructor(container: HTMLElement, options?: MasonrySnapGridLayoutOptions);
+    /**
+     * Initialization: set listeners, generate initial items, layout
+     */
+    private init;
+    /**
+     * Setup event listeners for window resize and container resize observer
+     */
+    private setupEventListeners;
+    /**
+     * Generate specified number of items, removing excess if any
+     * @param count number of items to generate
+     */
+    private generateItems;
+    /**
+     * Create a single masonry item HTMLElement, with content from renderItemContent callback or default template
+     * @param index index of the item
+     * @returns HTMLElement for the item
+     */
+    private createItem;
+    /**
+     * Default item content template string
+     * @param index index of the item
+     * @returns string HTML template for item content
+     */
+    private defaultItemContent;
+    /**
+     * Returns a random emoji from a fixed set for item footer
+     */
+    private getRandomEmoji;
+    /**
+     * Calculate positions of each item in masonry grid based on container width, gutter, min column width
+     */
+    private calculateLayout;
+    /**
+     * Apply calculated positions to each item with optional animation
+     * @param animate whether to animate layout changes (default false)
+     */
+    private applyLayout;
+    /**
+     * Handle container resize using RAF to optimize performance
+     */
+    private handleResize;
+    /**
+     * Shuffle items randomly and reapply layout with animation
+     */
+    shuffleItems(): void;
+    /**
+     * Add more items dynamically
+     * @param count number of items to add
+     */
+    addItems(count: number): void;
+}
+
+export { MasonrySnapGridLayout, MasonrySnapGridLayout as default };