결정적 배치 계산을 명확하게 조합합니다.

설치

npm install grid-masonry-core
npm install grid-masonry-react react
npm install grid-masonry-browser

세 package는 함께 0.3.0으로 게시되었습니다. 라이선스는 MIT입니다.

Core 개념

Core는 변경하지 않는 item과 aspectRatio를 받아 컨테이너 기준 cell을 반환합니다. 세로 레이아웃에서는 x와 column이 교차 축이고 y가 진행 축이며, 가로 레이아웃에서는 y와 row가 교차 축이고 x가 진행 축입니다.

const layout = calculateMasonryLayout(items, {
  containerWidth: 960,
  minColumnWidth: 220,
  gap: 8,
});

입력 순서가 기준(canonical) 순서입니다. layout.cells, ID, cell.index는 입력 순서를 유지합니다.

배치

서로 이어진 columnSpan과 rowSpan을 사용합니다. preferred lane은 부드러운 배치 의도이고 locked lane은 논리적 레인을 지정하는 제약입니다. flowDistribution은 start, end, center, space-between, space-evenly를 지원합니다.

실제 콘텐츠 전체를 측정한 footprint는 세로에서 { height, forWidth }, 가로에서 { width, forHeight } 형태입니다. ReservedRegion은 논리 좌표 { laneStart, laneSpan, flowStart, flowSize }로 지정하는 점유 영역이며, synthetic cell을 만들지 않습니다.

측정 수명 주기

Core가 교차 축 크기를 정하고, 호스트가 자연스러운 콘텐츠를 렌더링하고 측정한 다음, 교차 축 크기에 묶인 resolvedFootprint을 Core에 전달합니다. absolute-positioning shell을 측정하지 마십시오. 오래된 binding은 비율로 계산한 배치 정보로 대체합니다.

상태, snapshot, stable reflow

createMasonryState는 append, update, remove, reorder, resize, inspect, snapshot, restore를 제공합니다. Snapshot은 동일한 semantic 상태를 위한 검증된 checkpoint이며 undo나 history가 아닙니다. 오래되었거나 변조된 snapshot을 restore하면 원자적으로 실패합니다.

reflowStrategy: "stable"은 compact와 retained-lane 후보를 total displacement, maximum displacement, moved count 순으로 비교하고 동률이면 compact를 선택합니다. 전역 optimizer가 아닙니다. calculateFlowAnchorDelta는 geometry만 반환하며 스크롤을 변경하지 않습니다.

방향

flowDirection은 진행 축만, crossDirection은 교차 축만 반전합니다. source/DOM 순서를 바꾸거나 text RTL을 자동으로 적용하지 않습니다. 세로 RTL 방식의 화면에서는 host가 cross reverse와 별도의 DOM·접근성 정책을 선택할 수 있습니다.

예약 영역

Reserved region은 논리적인 hard obstacle입니다. 영역이 겹치거나 입력 배열 순서가 달라도 geometry는 달라지지 않으며, 같은 레인을 사용하는 item은 flow gap을 지킵니다. region이 layout extent를 늘릴 수 있습니다. Dense/backfill은 구현하지 않았습니다.

진단, 질의, tolerance

calculateMasonryLayoutWithDiagnostics는 opt-in 기능이며 일반 layout과 동일한 layout 및 span/lane/footprint/obstacle/distribution 정보를 반환합니다. 선형 질의와 index 질의는 동등하고, virtualization은 overscan을 제공하지만 스크롤을 소유하지 않습니다.

flowTolerance는 후보 레인을 선택하는 범위만 넓힙니다. 선택된 레인의 정확한 좌표와 gap·collision 규칙은 바뀌지 않습니다.

React와 Browser adapter

React는 MasonryGrid, HorizontalMasonryGrid, layout hook, useOrderList, virtualization hook을 제공합니다. Browser는 세로·가로 controller와 virtualized lifecycle을 제공합니다. 두 adapter 모두 Core geometry를 사용하며 DOM과 스크롤 정책은 host에 둡니다.

제한과 현재 상태

• Dense/backfill과 React Native는 deferred 상태입니다.
• Core는 DOM, text direction, 접근성, 스크롤을 소유하지 않습니다.
• 일부 state 설정은 전체 재계산을 사용합니다.
• Reserved region이 많으면 장애물 처리 비용이 증가합니다.

English docs · MIT License

감사의 말과 개발 공개

Embla Carousel, Swiper, Keen Slider는 가로 통합 대안으로 검토했지만 grid-masonry dependency로 채택하지 않았습니다. 선행 사례를 언급하는 것은 소스 복사, fork, endorsement를 뜻하지 않습니다. AI-assisted engineering tools는 구현, 테스트, 문서 작성, 분석, 검토를 지원했으며 contract와 release 결정은 사람이 주도했습니다.