masonry-snap-grid-layout 1.0.19 → 1.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +199 -223
- package/dist/MasonrySnapGridLayout-D7ctVJaF.d.cts +34 -0
- package/dist/MasonrySnapGridLayout-D7ctVJaF.d.ts +34 -0
- package/dist/esm/index.css +1 -0
- package/dist/esm/index.css.map +1 -1
- package/dist/esm/index.js +16 -173
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/react.js +37 -282
- package/dist/esm/react.js.map +1 -1
- package/dist/index.css +1 -0
- package/dist/index.css.map +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +20 -173
- package/dist/index.js.map +1 -1
- package/dist/react.d.cts +1 -14
- package/dist/react.d.ts +1 -14
- package/dist/react.js +35 -279
- package/dist/react.js.map +1 -1
- package/package.json +105 -76
- package/dist/MasonrySnapGridLayout-CGay5M_v.d.cts +0 -136
- package/dist/MasonrySnapGridLayout-CGay5M_v.d.ts +0 -136
package/README.md
CHANGED
|
@@ -1,223 +1,199 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
[
|
|
222
|
-
|
|
223
|
-
|
|
1
|
+
# masonry-snap-grid-layout
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/masonry-snap-grid-layout)
|
|
4
|
+
[](https://github.com/khachatryan-dev/masonry-snap-grid-layout/actions)
|
|
5
|
+
[](https://codesandbox.io/p/sandbox/l9xl7s)
|
|
6
|
+
[](https://codesandbox.io/p/sandbox/rgxsxp)
|
|
7
|
+
[](#angular-service-based-integration)
|
|
8
|
+
[](#vue-3-wrapper-drop-in-component)
|
|
9
|
+
|
|
10
|
+
A **performant, SSR-friendly** masonry grid layout library with smooth animations, customizable gutter, columns, and dynamic item content.
|
|
11
|
+
|
|
12
|
+
> **Next-generation, SSR-safe Masonry layout library** for **Vanilla JS**, **React**, **Vue 3**, and **Angular**, with zero dependencies and smooth animations.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# 🌟 Highlights
|
|
17
|
+
|
|
18
|
+
| Feature | Description |
|
|
19
|
+
| ---------------------- | --------------------------------------------------------------------- |
|
|
20
|
+
| ✅ CSS-First Masonry | Uses native browser CSS masonry if available for **best performance** |
|
|
21
|
+
| ✅ JS Fallback Engine | Battle-tested JS layout engine for unsupported browsers |
|
|
22
|
+
| ✅ SSR-Friendly React | Server renders static HTML, client hydrates smoothly |
|
|
23
|
+
| ✅ Vue 3 Drop-in | Scoped slot support for full flexibility |
|
|
24
|
+
| ✅ Angular Lifecycle | Works inside `ngAfterViewInit` |
|
|
25
|
+
| ✅ Zero Dependencies | Lightweight, fast, and modern |
|
|
26
|
+
| ✅ TypeScript-First | Full type safety |
|
|
27
|
+
| ✅ Smooth Animations | Works with dynamic content and transitions |
|
|
28
|
+
| ✅ Responsive & Dynamic | Automatic columns & gutter based on container width |
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
# 🎬 Demo Video
|
|
33
|
+
|
|
34
|
+
[](https://www.youtube.com/watch?v=mHK_6z9WEWs)
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
# 🖼 Live Demos
|
|
39
|
+
|
|
40
|
+
| Vanilla JS | React | Vue 3 |
|
|
41
|
+
| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
42
|
+
| [](https://codesandbox.io/p/sandbox/l9xl7s) | [](https://codesandbox.io/p/sandbox/rgxsxp) | [](https://codesandbox.io/p/sandbox/xyz123) |
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
# 🚀 Quick Start
|
|
47
|
+
|
|
48
|
+
### Install
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npm install masonry-snap-grid-layout
|
|
52
|
+
# or
|
|
53
|
+
yarn add masonry-snap-grid-layout
|
|
54
|
+
# or
|
|
55
|
+
pnpm add masonry-snap-grid-layout
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
### Vanilla JS Example
|
|
61
|
+
|
|
62
|
+
```js
|
|
63
|
+
import MasonrySnapGridLayout from 'masonry-snap-grid-layout';
|
|
64
|
+
import 'masonry-snap-grid-layout/dist/index.css';
|
|
65
|
+
|
|
66
|
+
const masonry = new MasonrySnapGridLayout(container, {
|
|
67
|
+
layoutMode: 'auto',
|
|
68
|
+
gutter: 16,
|
|
69
|
+
minColWidth: 240,
|
|
70
|
+
animate: true,
|
|
71
|
+
items,
|
|
72
|
+
renderItem: (item) => {
|
|
73
|
+
const el = document.createElement('div');
|
|
74
|
+
el.style.height = item.height + 'px';
|
|
75
|
+
el.style.background = `linear-gradient(135deg, ${item.color} 0%, #fff 100%)`;
|
|
76
|
+
el.textContent = item.title;
|
|
77
|
+
return el;
|
|
78
|
+
},
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
### React (SSR-Friendly)
|
|
85
|
+
|
|
86
|
+
```tsx
|
|
87
|
+
import MasonrySnapGrid from 'masonry-snap-grid-layout/react';
|
|
88
|
+
import 'masonry-snap-grid-layout/dist/index.css';
|
|
89
|
+
|
|
90
|
+
<MasonrySnapGrid
|
|
91
|
+
items={items}
|
|
92
|
+
layoutMode="auto"
|
|
93
|
+
gutter={16}
|
|
94
|
+
minColWidth={240}
|
|
95
|
+
animate
|
|
96
|
+
renderItem={(item) => (
|
|
97
|
+
<div style={{ height: item.height, borderRadius: '12px', padding: '16px' }}>
|
|
98
|
+
{item.title}
|
|
99
|
+
</div>
|
|
100
|
+
)}
|
|
101
|
+
/>
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
### Vue 3 Drop-in Component
|
|
107
|
+
|
|
108
|
+
```vue
|
|
109
|
+
<template>
|
|
110
|
+
<MasonrySnapGrid :items="items" :gutter="16" :minColWidth="240">
|
|
111
|
+
<template #default="{ item }">
|
|
112
|
+
<div :style="{ height: item.height + 'px', borderRadius: '12px', padding: '16px' }">
|
|
113
|
+
{{ item.title }}
|
|
114
|
+
</div>
|
|
115
|
+
</template>
|
|
116
|
+
</MasonrySnapGrid>
|
|
117
|
+
</template>
|
|
118
|
+
|
|
119
|
+
<script setup lang="ts">
|
|
120
|
+
import MasonrySnapGrid from 'masonry-snap-grid-layout/vue';
|
|
121
|
+
</script>
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
# ⚡ Engine Comparison
|
|
128
|
+
|
|
129
|
+
| Feature | CSS Masonry | JS Masonry |
|
|
130
|
+
| ----------------- | ----------- | ---------- |
|
|
131
|
+
| Browser Native | ✅ | ❌ |
|
|
132
|
+
| Animation Support | Limited | ✅ Smooth |
|
|
133
|
+
| SSR Support | ✅ (React) | ✅ |
|
|
134
|
+
| Zero Dependencies | ✅ | ✅ |
|
|
135
|
+
| Performance | ⚡ Fast | ⚡ Fast |
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
# 🧩 API Overview
|
|
140
|
+
|
|
141
|
+
| Option | Type | Default | Description |
|
|
142
|
+
| -------------------- | -------------------------- | -------- | -------------------- |
|
|
143
|
+
| `layoutMode` | `'auto' \| 'css' \| 'js'` | `'auto'` | Engine strategy |
|
|
144
|
+
| `gutter` | `number` | 16 | Space between items |
|
|
145
|
+
| `minColWidth` | `number` | 250 | Minimum column width |
|
|
146
|
+
| `animate` | `boolean` | true | Enable JS animations |
|
|
147
|
+
| `transitionDuration` | `number` | 400 | Duration (ms) |
|
|
148
|
+
| `items` | `Array<T>` | required | Data items |
|
|
149
|
+
| `renderItem` | `(item: T) => HTMLElement` | required | Render function |
|
|
150
|
+
|
|
151
|
+
**Methods**:
|
|
152
|
+
|
|
153
|
+
```ts
|
|
154
|
+
updateItems(newItems: T[])
|
|
155
|
+
destroy()
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
# 🧪 Testing
|
|
161
|
+
|
|
162
|
+
Built with **Vitest**. Covers:
|
|
163
|
+
|
|
164
|
+
* Core layout engine
|
|
165
|
+
* React SSR hydration
|
|
166
|
+
* Vue 3 wrapper
|
|
167
|
+
* Lifecycle & Angular usage
|
|
168
|
+
* Zero-width container handling
|
|
169
|
+
|
|
170
|
+
``` bash
|
|
171
|
+
npm test
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
# 📈 Performance & Best Practices
|
|
177
|
+
|
|
178
|
+
* Minimal DOM thrashing using `transform`
|
|
179
|
+
* `ResizeObserver` for responsive layout
|
|
180
|
+
* Optimized for dashboards, galleries, and dynamic content
|
|
181
|
+
* Handles zero-width containers gracefully
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
# 🤝 Contributing
|
|
186
|
+
|
|
187
|
+
1. Fork the repo
|
|
188
|
+
2. Create a feature branch (`git checkout -b feature/awesome-feature`)
|
|
189
|
+
3. Commit your changes
|
|
190
|
+
4. Open a Pull Request
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
# 📄 License
|
|
195
|
+
|
|
196
|
+
MIT © [Aram Khachatryan](https://github.com/khachatryan-dev)
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
interface MasonrySnapGridLayoutClassNames {
|
|
2
|
+
container?: string;
|
|
3
|
+
item?: string;
|
|
4
|
+
}
|
|
5
|
+
interface MasonrySnapGridLayoutOptions<T = unknown> {
|
|
6
|
+
gutter?: number;
|
|
7
|
+
minColWidth?: number;
|
|
8
|
+
animate?: boolean;
|
|
9
|
+
transitionDuration?: number;
|
|
10
|
+
items: T[];
|
|
11
|
+
renderItem: (item: T) => HTMLElement;
|
|
12
|
+
classNames?: MasonrySnapGridLayoutClassNames;
|
|
13
|
+
}
|
|
14
|
+
interface MasonrySnapGridRef {
|
|
15
|
+
layout: MasonrySnapGridLayout | null;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
declare class MasonrySnapGridLayout<T = any> {
|
|
19
|
+
private readonly container;
|
|
20
|
+
private readonly options;
|
|
21
|
+
private items;
|
|
22
|
+
private columnHeights;
|
|
23
|
+
private resizeObserver;
|
|
24
|
+
private rafId;
|
|
25
|
+
constructor(container: HTMLElement, options: MasonrySnapGridLayoutOptions<T>);
|
|
26
|
+
private renderItems;
|
|
27
|
+
private setupResizeObserver;
|
|
28
|
+
private updateLayout;
|
|
29
|
+
private findShortestColumn;
|
|
30
|
+
updateItems(newItems: T[]): void;
|
|
31
|
+
destroy(): void;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export { MasonrySnapGridLayout as M, type MasonrySnapGridLayoutOptions as a, type MasonrySnapGridRef as b };
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
interface MasonrySnapGridLayoutClassNames {
|
|
2
|
+
container?: string;
|
|
3
|
+
item?: string;
|
|
4
|
+
}
|
|
5
|
+
interface MasonrySnapGridLayoutOptions<T = unknown> {
|
|
6
|
+
gutter?: number;
|
|
7
|
+
minColWidth?: number;
|
|
8
|
+
animate?: boolean;
|
|
9
|
+
transitionDuration?: number;
|
|
10
|
+
items: T[];
|
|
11
|
+
renderItem: (item: T) => HTMLElement;
|
|
12
|
+
classNames?: MasonrySnapGridLayoutClassNames;
|
|
13
|
+
}
|
|
14
|
+
interface MasonrySnapGridRef {
|
|
15
|
+
layout: MasonrySnapGridLayout | null;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
declare class MasonrySnapGridLayout<T = any> {
|
|
19
|
+
private readonly container;
|
|
20
|
+
private readonly options;
|
|
21
|
+
private items;
|
|
22
|
+
private columnHeights;
|
|
23
|
+
private resizeObserver;
|
|
24
|
+
private rafId;
|
|
25
|
+
constructor(container: HTMLElement, options: MasonrySnapGridLayoutOptions<T>);
|
|
26
|
+
private renderItems;
|
|
27
|
+
private setupResizeObserver;
|
|
28
|
+
private updateLayout;
|
|
29
|
+
private findShortestColumn;
|
|
30
|
+
updateItems(newItems: T[]): void;
|
|
31
|
+
destroy(): void;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export { MasonrySnapGridLayout as M, type MasonrySnapGridLayoutOptions as a, type MasonrySnapGridRef as b };
|
package/dist/esm/index.css
CHANGED
package/dist/esm/index.css.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/index.css"],"sourcesContent":["
|
|
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":[]}
|