smart-masonry-grid 0.1.0

package/dist/index.cjs

@@ -0,0 +1,694 @@
+'use strict';
+
+// src/layout.ts
+function computeLayout(input) {
+  const { items, containerWidth, columnCount, gap } = input;
+  if (columnCount <= 0 || containerWidth <= 0 || items.length === 0) {
+    return { positions: [], columnHeights: [], totalHeight: 0 };
+  }
+  const columnWidth = (containerWidth - (columnCount - 1) * gap) / columnCount;
+  const columnHeights = new Float64Array(columnCount);
+  const positions = new Array(items.length);
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    let shortestCol = 0;
+    let shortestHeight = columnHeights[0];
+    for (let c = 1; c < columnCount; c++) {
+      if (columnHeights[c] < shortestHeight) {
+        shortestHeight = columnHeights[c];
+        shortestCol = c;
+      }
+    }
+    const left = shortestCol * (columnWidth + gap);
+    const top = columnHeights[shortestCol];
+    positions[i] = {
+      id: item.id,
+      index: item.index,
+      top,
+      left,
+      width: columnWidth,
+      height: item.height,
+      column: shortestCol
+    };
+    columnHeights[shortestCol] = top + item.height + gap;
+  }
+  let maxHeight = 0;
+  for (let c = 0; c < columnCount; c++) {
+    if (columnHeights[c] > maxHeight) {
+      maxHeight = columnHeights[c];
+    }
+  }
+  const totalHeight = maxHeight > 0 ? maxHeight - gap : 0;
+  return {
+    positions,
+    columnHeights: Array.from(columnHeights),
+    totalHeight
+  };
+}
+function resolveColumnCount(containerWidth, strategy, gap) {
+  if (strategy.type === "fixed") {
+    return Math.max(1, strategy.count);
+  }
+  if (strategy.type === "responsive") {
+    return resolveResponsiveColumns(containerWidth, strategy.breakpoints);
+  }
+  const count = Math.floor((containerWidth + gap) / (strategy.minColumnWidth + gap));
+  return Math.max(1, count);
+}
+function resolveResponsiveColumns(containerWidth, breakpoints) {
+  const entries = Object.keys(breakpoints).map((w) => [Number(w), breakpoints[Number(w)]]).sort((a, b) => b[0] - a[0]);
+  for (const [minWidth, cols] of entries) {
+    if (containerWidth >= minWidth) {
+      return Math.max(1, cols);
+    }
+  }
+  return entries.length > 0 ? Math.max(1, entries[entries.length - 1][1]) : 1;
+}
+
+// src/virtualizer.ts
+var DEFAULT_CONFIG = {
+  overscan: 600,
+  estimatedItemHeight: 300
+};
+var Virtualizer = class {
+  constructor(config, onRenderItem, onRecycleItem) {
+    this.positions = [];
+    this.sortedByTop = [];
+    this.renderedIndices = /* @__PURE__ */ new Set();
+    this.heightEstimates = /* @__PURE__ */ new Map();
+    this.scrollTop = 0;
+    this.viewportHeight = 0;
+    this.totalHeight = 0;
+    this.maxMeasuredHeight = 0;
+    this.scrollRafId = null;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.onRenderItem = onRenderItem;
+    this.onRecycleItem = onRecycleItem;
+  }
+  /** Update positions after layout recomputation */
+  updatePositions(positions, totalHeight) {
+    this.positions = positions;
+    this.totalHeight = totalHeight;
+    this.rebuildSortedIndex();
+    this.update();
+  }
+  rebuildSortedIndex() {
+    this.sortedByTop = this.positions.map((_, i) => i);
+    this.sortedByTop.sort((a, b) => this.positions[a].top - this.positions[b].top);
+  }
+  /** Handle scroll event (throttled via rAF) */
+  onScroll(scrollTop, viewportHeight) {
+    this.scrollTop = scrollTop;
+    this.viewportHeight = viewportHeight;
+    if (this.scrollRafId !== null) return;
+    this.scrollRafId = requestAnimationFrame(() => {
+      this.scrollRafId = null;
+      this.update();
+    });
+  }
+  /** Core: diff visible set and mount/unmount items */
+  update() {
+    const { overscan } = this.config;
+    const rangeTop = this.scrollTop - overscan;
+    const rangeBottom = this.scrollTop + this.viewportHeight + overscan;
+    const visibleIndices = this.findVisibleIndices(rangeTop, rangeBottom);
+    const visibleSet = new Set(visibleIndices);
+    for (const idx of this.renderedIndices) {
+      if (!visibleSet.has(idx)) {
+        this.onRecycleItem(idx);
+      }
+    }
+    for (const idx of visibleIndices) {
+      if (!this.renderedIndices.has(idx)) {
+        const position = this.positions[idx];
+        if (position) {
+          this.onRenderItem(idx, position);
+        }
+      }
+    }
+    this.renderedIndices = visibleSet;
+  }
+  /**
+   * Binary search to find items in [rangeTop, rangeBottom].
+   * An item is visible if: item.top + item.height > rangeTop AND item.top < rangeBottom
+   */
+  findVisibleIndices(rangeTop, rangeBottom) {
+    const sorted = this.sortedByTop;
+    const positions = this.positions;
+    if (sorted.length === 0) return [];
+    const searchTop = rangeTop - Math.max(this.maxMeasuredHeight, this.config.estimatedItemHeight);
+    let lo = 0;
+    let hi = sorted.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (positions[sorted[mid]].top < searchTop) {
+        lo = mid + 1;
+      } else {
+        hi = mid;
+      }
+    }
+    const result = [];
+    for (let i = lo; i < sorted.length; i++) {
+      const idx = sorted[i];
+      const pos = positions[idx];
+      if (pos.top >= rangeBottom) break;
+      if (pos.top + pos.height > rangeTop) {
+        result.push(idx);
+      }
+    }
+    return result;
+  }
+  /** Record a measured height */
+  recordMeasurement(id, height) {
+    this.heightEstimates.set(id, height);
+    if (height > this.maxMeasuredHeight) {
+      this.maxMeasuredHeight = height;
+    }
+  }
+  /** Get current visible range */
+  getVisibleRange() {
+    if (this.renderedIndices.size === 0) {
+      return { startIndex: 0, endIndex: 0 };
+    }
+    let min = Infinity;
+    let max = -Infinity;
+    for (const idx of this.renderedIndices) {
+      if (idx < min) min = idx;
+      if (idx > max) max = idx;
+    }
+    return { startIndex: min, endIndex: max };
+  }
+  getTotalHeight() {
+    return this.totalHeight;
+  }
+  destroy() {
+    if (this.scrollRafId !== null) {
+      cancelAnimationFrame(this.scrollRafId);
+    }
+    this.renderedIndices.clear();
+    this.heightEstimates.clear();
+    this.positions = [];
+    this.sortedByTop = [];
+  }
+};
+
+// src/observers.ts
+var ObserverManager = class {
+  constructor(callbacks) {
+    this.containerObserver = null;
+    this.itemObserver = null;
+    this.elementToId = /* @__PURE__ */ new WeakMap();
+    this.pendingItemResizes = /* @__PURE__ */ new Map();
+    this.batchScheduled = false;
+    this.callbacks = callbacks;
+  }
+  /** Observe container for width changes */
+  observeContainer(container) {
+    this.containerObserver = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const width = entry.borderBoxSize?.[0]?.inlineSize ?? entry.contentRect.width;
+        const height = entry.borderBoxSize?.[0]?.blockSize ?? entry.contentRect.height;
+        this.callbacks.onContainerResize(width, height);
+      }
+    });
+    this.containerObserver.observe(container);
+  }
+  /** Initialize the shared item observer (lazy) */
+  initItemObserver() {
+    this.itemObserver = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const element = entry.target;
+        const id = this.elementToId.get(element);
+        if (id === void 0) continue;
+        const height = entry.borderBoxSize?.[0]?.blockSize ?? entry.contentRect.height;
+        const width = entry.borderBoxSize?.[0]?.inlineSize ?? entry.contentRect.width;
+        this.pendingItemResizes.set(id, { element, width, height });
+      }
+      if (!this.batchScheduled) {
+        this.batchScheduled = true;
+        queueMicrotask(() => {
+          this.batchScheduled = false;
+          const batch = new Map(this.pendingItemResizes);
+          this.pendingItemResizes.clear();
+          for (const [id, { element, width, height }] of batch) {
+            this.callbacks.onItemResize(id, element, width, height);
+          }
+        });
+      }
+    });
+  }
+  /** Observe a single item element */
+  observeItem(element, id) {
+    if (!this.itemObserver) this.initItemObserver();
+    this.elementToId.set(element, id);
+    this.itemObserver.observe(element);
+  }
+  /** Stop observing a single item element */
+  unobserveItem(element) {
+    this.elementToId.delete(element);
+    this.itemObserver?.unobserve(element);
+  }
+  /** Clean up everything */
+  destroy() {
+    this.containerObserver?.disconnect();
+    this.itemObserver?.disconnect();
+    this.containerObserver = null;
+    this.itemObserver = null;
+    this.elementToId = /* @__PURE__ */ new WeakMap();
+    this.pendingItemResizes.clear();
+  }
+};
+
+// src/styles.ts
+var STYLE_ID = "smart-masonry-grid-styles";
+function injectBaseStyles(prefix = "smg") {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = `
+    .${prefix}-container--ssr {
+      column-gap: var(--${prefix}-gap, 16px);
+      column-count: var(--${prefix}-columns, 3);
+    }
+    .${prefix}-container--ssr > .${prefix}-item {
+      break-inside: avoid;
+      margin-bottom: var(--${prefix}-gap, 16px);
+    }
+    .${prefix}-container--js {
+      position: relative;
+      overflow: hidden;
+    }
+    .${prefix}-container--js > .${prefix}-item {
+      position: absolute;
+      top: 0;
+      left: 0;
+      will-change: transform;
+    }
+    .${prefix}-container--transitioning > .${prefix}-item {
+      transition: transform 0.2s ease-out, opacity 0.2s ease-out;
+    }
+  `;
+  document.head.appendChild(style);
+}
+function getSSRStyles(prefix = "smg", columns = 3, gap = 16) {
+  return `.${prefix}-container--ssr{column-gap:${gap}px;column-count:${columns}}.${prefix}-container--ssr>.${prefix}-item{break-inside:avoid;margin-bottom:${gap}px}`;
+}
+
+// src/utils.ts
+var idCounter = 0;
+function generateId() {
+  return `smg-${++idCounter}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function debounce(fn, delayMs) {
+  let timeoutId = null;
+  const debounced = function(...args) {
+    if (timeoutId !== null) clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      timeoutId = null;
+      fn.apply(this, args);
+    }, delayMs);
+  };
+  debounced.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+  return debounced;
+}
+
+// src/masonry.ts
+function resolveOptions(options) {
+  const gap = options.gap ?? 16;
+  let columns;
+  if (typeof options.columns === "number") {
+    columns = { type: "fixed", count: options.columns };
+  } else if (options.columns) {
+    columns = options.columns;
+  } else {
+    columns = { type: "auto", minColumnWidth: 250 };
+  }
+  return {
+    columns,
+    gap,
+    virtualize: options.virtualize ?? true,
+    virtualizer: {
+      overscan: options.virtualizer?.overscan ?? 600,
+      estimatedItemHeight: options.virtualizer?.estimatedItemHeight ?? 300
+    },
+    renderItem: options.renderItem ?? null,
+    totalItems: options.totalItems ?? 0,
+    ssrFallback: options.ssrFallback ?? false,
+    classPrefix: options.classPrefix ?? "smg",
+    resizeDebounceMs: options.resizeDebounceMs ?? 100
+  };
+}
+var MasonryGrid = class {
+  constructor(container, options = {}) {
+    // State
+    this.items = [];
+    this.itemMap = /* @__PURE__ */ new Map();
+    this.elementMap = /* @__PURE__ */ new Map();
+    this.indexToElement = /* @__PURE__ */ new Map();
+    this.currentLayout = null;
+    this.containerWidth = 0;
+    this.columnCount = 0;
+    this.isDestroyed = false;
+    // Subsystems
+    this.virtualizer = null;
+    // Events
+    this.listeners = /* @__PURE__ */ new Map();
+    this.boundScrollHandler = null;
+    this.container = container;
+    this.opts = resolveOptions(options);
+    this.prefix = this.opts.classPrefix;
+    injectBaseStyles(this.prefix);
+    this.observers = new ObserverManager({
+      onContainerResize: (width) => this.handleContainerResize(width),
+      onItemResize: (id, _element, _width, height) => this.handleItemResize(id, height)
+    });
+    this.debouncedRelayout = debounce(() => {
+      this.relayout();
+      this.applyPositions();
+    }, this.opts.resizeDebounceMs);
+    this.scrollContainer = this.findScrollParent(container) ?? window;
+    this.init();
+  }
+  // ==================== INITIALIZATION ====================
+  init() {
+    const isSSR = this.container.classList.contains(
+      `${this.prefix}-container--ssr`
+    );
+    this.observers.observeContainer(this.container);
+    this.containerWidth = this.container.offsetWidth;
+    this.columnCount = resolveColumnCount(
+      this.containerWidth,
+      this.opts.columns,
+      this.opts.gap
+    );
+    if (isSSR) {
+      this.hydrateFromSSR();
+    } else if (this.opts.virtualize && this.opts.renderItem && this.opts.totalItems > 0) {
+      this.container.classList.add(`${this.prefix}-container--js`);
+      this.initVirtualized();
+    } else {
+      this.container.classList.add(`${this.prefix}-container--js`);
+      this.initFromExistingChildren();
+    }
+  }
+  hydrateFromSSR() {
+    const children = Array.from(this.container.children);
+    this.collectItems(children);
+    this.relayout();
+    requestAnimationFrame(() => {
+      this.container.classList.add(`${this.prefix}-container--transitioning`);
+      this.container.classList.remove(`${this.prefix}-container--ssr`);
+      this.container.classList.add(`${this.prefix}-container--js`);
+      this.applyPositions();
+      setTimeout(() => {
+        this.container.classList.remove(
+          `${this.prefix}-container--transitioning`
+        );
+      }, 250);
+    });
+  }
+  initFromExistingChildren() {
+    const children = Array.from(this.container.children);
+    if (children.length > 0) {
+      this.collectItems(children);
+      this.relayout();
+      this.applyPositions();
+    }
+  }
+  initVirtualized() {
+    this.virtualizer = new Virtualizer(
+      this.opts.virtualizer,
+      (index, position) => this.renderVirtualItem(index, position),
+      (index) => this.recycleVirtualItem(index)
+    );
+    const estimatedHeight = this.opts.virtualizer.estimatedItemHeight;
+    for (let i = 0; i < this.opts.totalItems; i++) {
+      this.items.push({
+        id: i,
+        index: i,
+        element: null,
+        height: estimatedHeight,
+        measured: false
+      });
+    }
+    this.relayout();
+    this.bindScrollListener();
+  }
+  // ==================== LAYOUT ====================
+  relayout() {
+    if (this.isDestroyed) return;
+    const layoutItems = this.items.map((item) => ({
+      id: item.id,
+      index: item.index,
+      height: item.height
+    }));
+    this.currentLayout = computeLayout({
+      items: layoutItems,
+      containerWidth: this.containerWidth,
+      columnCount: this.columnCount,
+      gap: this.opts.gap
+    });
+    this.container.style.height = `${this.currentLayout.totalHeight}px`;
+    if (this.virtualizer) {
+      this.virtualizer.updatePositions(
+        this.currentLayout.positions,
+        this.currentLayout.totalHeight
+      );
+    }
+    this.emit("layout", this.currentLayout);
+  }
+  applyPositions() {
+    if (!this.currentLayout) return;
+    for (const pos of this.currentLayout.positions) {
+      const element = this.elementMap.get(pos.id);
+      if (!element) continue;
+      element.style.transform = `translate3d(${pos.left}px, ${pos.top}px, 0)`;
+      element.style.width = `${pos.width}px`;
+    }
+  }
+  // ==================== VIRTUAL ITEM LIFECYCLE ====================
+  renderVirtualItem(index, position) {
+    let element = this.indexToElement.get(index);
+    if (!element) {
+      element = this.opts.renderItem(index);
+      element.classList.add(`${this.prefix}-item`);
+      this.container.appendChild(element);
+      this.indexToElement.set(index, element);
+      this.elementMap.set(position.id, element);
+      this.observers.observeItem(element, position.id);
+    }
+    element.style.transform = `translate3d(${position.left}px, ${position.top}px, 0)`;
+    element.style.width = `${position.width}px`;
+    element.style.display = "";
+    requestAnimationFrame(() => {
+      if (this.isDestroyed || !element) return;
+      const measuredHeight = element.offsetHeight;
+      const item = this.items[index];
+      if (item && !item.measured && Math.abs(item.height - measuredHeight) > 1) {
+        item.height = measuredHeight;
+        item.measured = true;
+        this.virtualizer?.recordMeasurement(position.id, measuredHeight);
+        this.relayout();
+      }
+    });
+  }
+  recycleVirtualItem(index) {
+    const element = this.indexToElement.get(index);
+    if (element) {
+      element.style.display = "none";
+      this.observers.unobserveItem(element);
+    }
+  }
+  // ==================== OBSERVER HANDLERS ====================
+  handleContainerResize(width) {
+    if (Math.abs(width - this.containerWidth) < 1) return;
+    this.containerWidth = width;
+    this.columnCount = resolveColumnCount(
+      width,
+      this.opts.columns,
+      this.opts.gap
+    );
+    this.debouncedRelayout();
+    this.emit("resize", width, this.columnCount);
+  }
+  handleItemResize(id, newHeight) {
+    const item = this.itemMap.get(id);
+    if (!item) return;
+    const oldHeight = item.height;
+    if (Math.abs(oldHeight - newHeight) < 1) return;
+    item.height = newHeight;
+    item.measured = true;
+    this.emit("itemResize", id, oldHeight, newHeight);
+    this.debouncedRelayout();
+  }
+  // ==================== SCROLL ====================
+  bindScrollListener() {
+    this.boundScrollHandler = () => {
+      const scrollTop = this.scrollContainer === window ? window.scrollY : this.scrollContainer.scrollTop;
+      const viewportHeight = this.scrollContainer === window ? window.innerHeight : this.scrollContainer.clientHeight;
+      this.virtualizer?.onScroll(scrollTop, viewportHeight);
+      const visibleRange = this.virtualizer?.getVisibleRange() ?? {
+        startIndex: 0,
+        endIndex: 0
+      };
+      this.emit("scroll", scrollTop, visibleRange);
+    };
+    this.scrollContainer.addEventListener("scroll", this.boundScrollHandler, {
+      passive: true
+    });
+    this.boundScrollHandler();
+  }
+  // ==================== PUBLIC API ====================
+  /** Add items to the end of the grid */
+  append(elements) {
+    const startIndex = this.items.length;
+    this.collectItems(elements, startIndex);
+    this.relayout();
+    this.applyPositions();
+  }
+  /** Add items to the beginning of the grid */
+  prepend(elements) {
+    const newItems = [];
+    elements.forEach((el, i) => {
+      const id = generateId();
+      el.classList.add(`${this.prefix}-item`);
+      this.container.prepend(el);
+      const height = el.offsetHeight || this.opts.virtualizer.estimatedItemHeight;
+      const item = {
+        id,
+        index: i,
+        element: el,
+        height,
+        measured: el.offsetHeight > 0
+      };
+      newItems.push(item);
+      this.itemMap.set(id, item);
+      this.elementMap.set(id, el);
+      this.observers.observeItem(el, id);
+    });
+    this.items.forEach((item) => {
+      item.index += elements.length;
+    });
+    this.items = [...newItems, ...this.items];
+    this.relayout();
+    this.applyPositions();
+  }
+  /** Remove an item by ID */
+  remove(id) {
+    const item = this.itemMap.get(id);
+    if (!item) return;
+    const element = this.elementMap.get(id);
+    if (element) {
+      this.observers.unobserveItem(element);
+      element.remove();
+    }
+    this.items = this.items.filter((i) => i.id !== id);
+    this.items.forEach((item2, i) => {
+      item2.index = i;
+    });
+    this.itemMap.delete(id);
+    this.elementMap.delete(id);
+    this.relayout();
+    this.applyPositions();
+  }
+  /** Force a full relayout */
+  refresh() {
+    for (const item of this.items) {
+      const el = this.elementMap.get(item.id);
+      if (el) {
+        item.height = el.offsetHeight;
+        item.measured = true;
+      }
+    }
+    this.relayout();
+    this.applyPositions();
+  }
+  /** Get current layout data */
+  getLayout() {
+    return this.currentLayout;
+  }
+  /** Get the number of columns */
+  getColumnCount() {
+    return this.columnCount;
+  }
+  /** Subscribe to events. Returns an unsubscribe function. */
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(callback);
+    return () => {
+      this.listeners.get(event)?.delete(callback);
+    };
+  }
+  emit(event, ...args) {
+    const callbacks = this.listeners.get(event);
+    if (!callbacks) return;
+    for (const cb of callbacks) {
+      cb(...args);
+    }
+  }
+  /** Tear down everything */
+  destroy() {
+    this.isDestroyed = true;
+    this.emit("destroy");
+    this.observers.destroy();
+    this.virtualizer?.destroy();
+    this.debouncedRelayout.cancel();
+    if (this.boundScrollHandler) {
+      this.scrollContainer.removeEventListener("scroll", this.boundScrollHandler);
+    }
+    this.container.classList.remove(`${this.prefix}-container--js`);
+    this.container.style.height = "";
+    for (const [, element] of this.elementMap) {
+      element.style.transform = "";
+      element.style.width = "";
+    }
+    this.items = [];
+    this.itemMap.clear();
+    this.elementMap.clear();
+    this.indexToElement.clear();
+    this.listeners.clear();
+  }
+  // ==================== HELPERS ====================
+  collectItems(elements, startIndex = 0) {
+    elements.forEach((el, i) => {
+      const id = el.dataset.masonryId ?? generateId();
+      el.classList.add(`${this.prefix}-item`);
+      const height = el.offsetHeight || this.opts.virtualizer.estimatedItemHeight;
+      const item = {
+        id,
+        index: startIndex + i,
+        element: el,
+        height,
+        measured: el.offsetHeight > 0
+      };
+      this.items.push(item);
+      this.itemMap.set(id, item);
+      this.elementMap.set(id, el);
+      this.observers.observeItem(el, id);
+    });
+  }
+  findScrollParent(element) {
+    let parent = element.parentElement;
+    while (parent) {
+      const overflow = getComputedStyle(parent).overflowY;
+      if (overflow === "auto" || overflow === "scroll") return parent;
+      parent = parent.parentElement;
+    }
+    return null;
+  }
+};
+
+exports.MasonryGrid = MasonryGrid;
+exports.computeLayout = computeLayout;
+exports.getSSRStyles = getSSRStyles;
+exports.resolveColumnCount = resolveColumnCount;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map