공식 한국어 문서 · 0.3.0

배치 계산과 렌더링의 책임을 분명하게 나눕니다.

Core는 입력 항목을 논리 좌표로 배치합니다. 호스트 애플리케이션은 렌더링, 콘텐츠 측정 연동, 접근성, 스크롤을 담당합니다.

설치

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

Core, React, Browser 패키지는 모두 0.3.0으로 공개되어 있습니다. 라이선스는 MIT입니다.

Core의 기본 개념

Core는 읽기 전용 항목과 aspectRatio를 받아 컨테이너를 기준으로 한 셀 좌표를 반환합니다. 세로 레이아웃에서는 x 방향의 열이 교차 축이고 y가 진행 축입니다. 가로 레이아웃에서는 y 방향의 행이 교차 축이고 x가 진행 축입니다.

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

입력 배열의 순서가 기준 순서입니다. layout.cells, ID, cell.index도 이 순서를 유지합니다.

배치 규칙

columnSpan과 rowSpan으로 이어진 여러 레인을 차지할 수 있습니다. preferredColumn과 preferredRow는 가능한 경우 우선할 레인을 지정합니다. lockedColumn과 lockedRow는 논리 레인을 제약하지만 다른 항목이나 예약 영역과의 겹침을 허용하지 않습니다.

flowDistribution은 start, end, center, space-between, space-evenly를 지원합니다.

콘텐츠 측정

Core가 교차 축 크기를 먼저 정하면 호스트 애플리케이션이 자연스러운 콘텐츠를 렌더링하고 그 전체 크기를 측정합니다. 측정 결과는 세로에서 { height, forWidth }, 가로에서 { width, forHeight } 형식의 resolvedFootprint으로 전달합니다.

절대 위치를 담당하는 바깥 컨테이너를 콘텐츠 크기로 측정하면 안 됩니다. 기록된 교차 축 크기가 현재 레이아웃과 맞지 않으면 오류를 내지 않고 aspectRatio를 기준으로 크기를 다시 계산합니다.

상태, 스냅샷, 안정적 재배치

createMasonryState는 append, update, remove, reorder, resize, inspect, snapshot, restore를 제공합니다. 스냅샷은 의미가 같은 입력 상태에서 다시 사용할 수 있는 검증된 체크포인트입니다. 작업을 되돌리거나 변경 이력을 보관하는 기능이 아니며, 오래되거나 변조된 체크포인트를 복원하면 현재 상태를 바꾸지 않고 실패합니다.

reflowStrategy: "stable"은 compact 후보와 기존 레인을 유지하는 후보를 전체 이동 거리, 최대 이동 거리, 움직인 항목 수 순으로 비교합니다. 모두 같으면 compact를 선택합니다. 전역 최적화 기능은 아닙니다. calculateFlowAnchorDelta는 진행 축 이동량만 반환하며 스크롤을 직접 변경하지 않습니다.

방향

flowDirection은 진행 축 좌표만, crossDirection은 교차 축 좌표만 반전합니다. 입력 순서나 DOM 순서를 바꾸지 않고 텍스트 RTL도 자동으로 설정하지 않습니다. 세로 RTL 화면이 필요하다면 호스트 애플리케이션이 crossDirection: "reverse"와 DOM·접근성 정책을 각각 선택합니다.

예약 영역

ReservedRegion은 { laneStart, laneSpan, flowStart, flowSize } 형식으로 지정하는 논리적 점유 영역입니다. 영역이 겹치거나 배열 순서가 달라도 배치 결과는 같고, 같은 레인을 사용하는 항목은 진행 축 간격을 지켜야 합니다. 예약 영역은 셀을 만들지 않지만 전체 레이아웃 범위를 늘릴 수 있습니다. dense/backfill은 현재 지원하지 않습니다.

진단, 질의, flowTolerance

calculateMasonryLayoutWithDiagnostics는 일반 배치와 정확히 같은 결과에 항목이 차지하는 레인 수, 선호·고정 레인 제약, resolvedFootprint, 예약 영역, 공간 배분에 관한 관찰 정보를 덧붙입니다. 진단을 사용해도 배치 방식은 달라지지 않습니다.

선형 질의와 색인을 사용하는 질의는 같은 셀을 입력 순서로 반환합니다. 가상화 기능은 화면 밖 여유 범위인 overscan을 적용하지만 스크롤을 직접 관리하지 않습니다.

flowTolerance는 최소 진행 오프셋에 가까운 레인을 후보로 인정하는 범위만 넓힙니다. 선택한 레인의 정확한 좌표, 항목 간 간격, 충돌 방지 규칙은 바뀌지 않습니다.

React와 Browser 어댑터

React 패키지는 MasonryGrid, HorizontalMasonryGrid, 레이아웃 훅, useOrderList, 가상화 훅을 제공합니다. Browser 패키지는 세로·가로 컨트롤러와 가상화 생명주기를 제공합니다. 두 어댑터 모두 Core가 계산한 좌표와 항목의 정체성을 유지하며 DOM과 스크롤 정책은 호스트 애플리케이션에 맡깁니다.

자세한 내용은 GitHub의 React 사용법과 Browser 사용법을 참조하십시오.

제한사항과 출시 상태

dense/backfill은 현재 지원하지 않습니다.
React Native 지원은 보류되어 있습니다.
DOM, 텍스트 방향, 접근성, 스크롤은 호스트 애플리케이션이 담당합니다.
일부 상태 설정에서는 전체 재계산을 사용합니다.
예약 영역이 많아질수록 장애물 검사 비용이 늘어납니다.

0.3.0 패키지와 공식 사이트, v0.3.0 GitHub 릴리스가 공개되어 있습니다.

영문 문서 · MIT 라이선스

감사의 말과 개발 과정 공개

Embla Carousel, Swiper, Keen Slider는 가로 레이아웃에서 스크롤과 표시 영역, 배치 계산의 책임을 분리하기 위한 비교 대상으로 검토했습니다. grid-masonry의 의존성은 아니며, 이 언급이 소스 코드의 복사나 해당 프로젝트에서 갈라져 나온 구현, 해당 프로젝트의 보증을 뜻하지 않습니다.

구현, 테스트, 문서 작성, 분석과 검토 과정에서 AI 기반 개발 도구를 활용했습니다. 공개 API와 구조, 검증 기준, 출시 결정은 사람이 검토하고 확정했으며 게시된 소프트웨어에 대한 최종 책임은 프로젝트 유지관리자에게 있습니다.