StringMasonry

StringMasonry turns one container into an animated masonry grid. The module owns the positioning of the container's direct children and reacts to width changes, DOM mutations, and image loading.

Public API

Attributes

Attribute	Type	Default	Real runtime effect
`string-masonry-cols`	breakpoint-dimension	`2	640:3
`string-masonry-gap`	breakpoint-dimension	`16	640:24
`string-masonry-mode`	string	`auto`	Chooses automatic layout updates or event-driven manual control.

Child items may also define animation tuning attributes:

string-masonry-position-time
string-masonry-position-easing
string-masonry-size-time
string-masonry-size-easing

These are read from the direct child items, not from the masonry container.

CSS Variables and DOM Output

The module writes inline layout styles.

On the container:

position: relative
animated height

On direct children:

position: absolute
top: 0
left: 0
inline width
inline transform: translate3d(x, y, 0)

The module does not publish CSS variables for masonry geometry.

Events

Channel	Payload	Fired when
`masonry:shuffle:start`	`{ object }`	A masonry shuffle starts
`masonry:shuffle:end`	`{ object }`	A masonry shuffle ends
`masonry:update:<id>`	`{ mode?, cols?, gap? }`	Input channel to change settings and force a relayout

Manual update example:

TypeScript

stringTune.emit('masonry:update:grid', {
  cols: 4,
  gap: 20,
});

Mirror Behavior

This module has no mirror output contract.

Quick Example

HTML

<section 
  string="masonry" 
  string-id="work-grid" 
  string-masonry-mode="manual"
  string-masonry-gap="24" 
  class="work-grid"
>
  <article class="work-item" style="height: 300px;">Project A</article>
  <article class="work-item" style="height: 450px;">Project B</article>
  <article class="work-item" style="height: 280px;">Project C</article>
  <article class="work-item" style="height: 520px;">Project D</article>
  <article class="work-item" style="height: 320px;">Project E</article>
</section>

<button type="button" id="cols-2">2 cols</button>
<button type="button" id="cols-3">3 cols</button>

CSS

.work-grid {
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
  position: relative;
}

.work-item {
  background: #f4f4f4;
  border: 1px solid black;
  display: flex;
  align-items: center;
  justify-content: center;
  font-weight: bold;
  font-size: 1.25rem;
  transition: transform 0.4s cubic-bezier(0.2, 0, 0, 1);
}

.work-item:hover {
  background: black;
  color: white;
}

TypeScript

stringTune.emit('masonry:update:work-grid', { cols: 2, gap: 24 });
stringTune.emit('masonry:update:work-grid', { cols: 3, gap: 24 });

Registration

TypeScript

import StringTune, { StringMasonry } from '@fiddle-digital/string-tune';

const stringTune = StringTune.getInstance();
stringTune.use(StringMasonry);
stringTune.start(60);

Detailed Behavior

The module positions only direct children of the masonry container.
In auto mode it reacts to container resize, child add/remove, and unfinished image loads.
In manual mode you can still trigger relayout through masonry:update:<id>.
Child timing attributes are parsed with parseFloat(). In the current runtime they are plain numeric durations, not documented time-unit strings.
The module also emits a generic resize event internally after certain height updates, but that should be treated as runtime plumbing rather than masonry-specific public API.