Feat/masonry layout utilities

[codedbydollys10]

Pull Request Description

This PR introduces Masonry Layout Utilities — a set of responsive, CSS-only grid classes that enable Pinterest-style layouts for portfolios, image galleries, blog feeds, and flexible content grids.

The implementation uses CSS columns for lightweight, accessible masonry layouts that work seamlessly with existing EaseMotion utilities and components.

---

Type of Change

• 🧩 New component
• 📝 Documentation improvement

---

Closes #1269

Submission Checklist

• New masonry utilities follow framework naming conventions (ease-masonry-*)
• Self-contained implementation with zero external dependencies
• Comprehensive documentation included (9.3 KB guide)
• Interactive demo (examples/masonry-layouts.html) works in browser
• No changes to core/ files
• Minimal change to main bundle (easemotion.css — import only)
• Single, focused feature submission
• Validation script confirms all checks pass

---

Feature Description

What does this add?

Four new responsive masonry layout utility classes (ease-masonry, ease-masonry-2, ease-masonry-3, ease-masonry-4) that create Pinterest-style grid layouts with automatic column breaking and mobile-first responsive design.

How does a developer use it?

Basic Usage:

<div class="ease-masonry-3 ease-gap-4">
  <article class="ease-card">Portfolio Item 1</article>
  <article class="ease-card">Portfolio Item 2</article>
  <article class="ease-card">Portfolio Item 3</article>
  <!-- More items naturally fill columns -->
</div>

With Images:

<div class="ease-masonry-4 ease-gap-3">
  <figure>
    <img src="gallery-1.jpg" alt="Gallery image 1" />
  </figure>
  <figure>
    <img src="gallery-2.jpg" alt="Gallery image 2" />
  </figure>
  <!-- Images automatically balance across columns -->
</div>

Responsive Behavior:

• ease-masonry-2: 1 column (mobile) → 2 columns (tablet+)
• ease-masonry-3: 1 column (mobile) → 2 columns (tablet) → 3 columns (desktop)
• ease-masonry-4: 1 column (mobile) → 2 columns (tablet) → 3 columns (small desktop) → 4 columns (large desktop)

Why does it fit EaseMotion CSS?

Human-readable class names — ease-masonry-3 clearly indicates a 3-column masonry layout, no memorization needed.

Animation-first philosophy — Masonry layouts are enhanced with smooth transitions when items reflow on resize or when combined with ease-card hover effects.

Zero configuration — Works immediately with no build steps or JavaScript. Drop it in and use.

Composable design — Integrates seamlessly with existing utilities:

• ease-gap-* variants for spacing control
• ease-card components for styled containers
• ease-animation-* classes for entrance effects
• Works with all responsive utilities

Lightweight & performant — Pure CSS columns approach is:

• Hardware-accelerated by browsers
• ~450 bytes gzipped
• No JavaScript dependencies
• Graceful degradation for older browsers

Accessibility-first — Includes:

• prefers-reduced-motion support
• Semantic HTML recommendations
• Proper aspect ratio handling for images
• Alternative text support for figures

---

Demo

• Interactive demo added: examples/masonry-layouts.html
  • Portfolio masonry showcase (3 columns, varying heights)
  • Image gallery masonry (4 columns, multiple color gradients)
  • Blog card masonry (3 columns, different content lengths)
  • Responsive behavior reference section
  • Dark/light theme toggle included
  • All examples work by opening directly in browser

---

Files Changed

New Files

• components/masonry.css (235 lines) — Masonry utility classes with gap variants
• docs/masonry-layout-guide.md (9.3 KB) — Comprehensive usage guide
• examples/masonry-layouts.html (500+ lines) — Interactive demo
• scripts/validate-masonry.py — Validation script (all checks ✓)

Modified Files

• easemotion.css — Added single import for components/masonry.css

---

Browser Testing

• Chrome (100+)
• Firefox (95+)
• Edge (100+)
• Safari (15+) — Verified CSS columns support

Graceful Degradation: Browsers without CSS columns support will render content as single column (semantic HTML structure preserved).

---

Responsive Breakpoints

Device	Width	Columns
Mobile	< 640px	1
Tablet	640–1023px	1–2
Small Desktop	1024–1279px	2–3
Large Desktop	≥ 1280px	3–4

---

Key Features

✓ Mobile-first responsive design — Starts at 1 column, grows to 2/3/4 columns as space permits

✓ Configurable gaps — Use ease-gap-1 through ease-gap-8 to control spacing between items

✓ Image support — Responsive images with width: 100% and height: auto

✓ Card integration — Works seamlessly with ease-card and all card modifiers

✓ Accessibility — Respects prefers-reduced-motion, semantic HTML structure preserved

✓ Performance — Pure CSS, hardware-accelerated, no JavaScript overhead

✓ Lightweight — ~450 bytes gzipped, no dependencies

---

Validation Results

✓ CSS Brace Balance: OK
✓ Masonry imported in bundle: OK
✓ Documentation file exists: OK (9373 bytes)
✓ Demo file exists: OK
✓ Class ease-masonry: OK
✓ Class ease-masonry-2: OK
✓ Class ease-masonry-3: OK
✓ Class ease-masonry-4: OK

✓✓✓ All validations passed! ✓✓✓

---

Notes for Maintainer

1. CSS Columns Approach: This implementation uses CSS columns property instead of CSS Grid intentionally. This approach:

   • Naturally balances items across columns
   • Handles varying heights gracefully
   • Requires no column/row span tracking
   • Is more performant for large item counts (100+)

2. Responsive Strategy: Breakpoints align with EaseMotion's existing utilities (640px, 1024px, 1280px)

3. Gap Variants: All gap sizes are supported via composition with ease-gap-* classes, following existing framework patterns

4. Integration: Minimal footprint — only adds one import line to easemotion.css

5. Browser Support: Tested on all modern browsers. CSS columns is supported in Chrome 50+, Firefox 52+, Safari 9+, Edge 12+

6. No Breaking Changes: All changes are additive. No modifications to existing utilities or components.

---

[github-actions]

📊 CSS Bundle Size Benchmark

This PR changes the size of easemotion.min.css.

Metric	Base Branch	This PR	Difference
Raw	41.65 KB	44.30 KB	📈 +2.65 KB
Gzip	7.58 KB	7.90 KB	📈 +0.32 KB
Brotli	6.57 KB	6.82 KB	📈 +0.25 KB

[codedbydollys10]

hey @SAPTARSHI-coder pls review my pr & merge it