masonry-snap-grid-layout/dist/MasonrySnapGridLayout-CPmdhc_q.d.cts

A performant, responsive masonry layout library with smooth animations, dynamic columns, and zero dependencies.

/**
 * 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 };