feat: add MasonryLegendList

.github/workflows/masonry-e2e.yml

@@ -0,0 +1,36 @@
+name: Masonry E2E
+
+on:
+  pull_request:
+  push:
+    branches: [main, feat/masonry-list]
+
+permissions:
+  contents: read
+
+jobs:
+  masonry:
+    name: Chromium and WebKit masonry regressions
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.6
+      - run: bun install --frozen-lockfile
+      - run: bun install --frozen-lockfile
+        working-directory: example-web
+      - run: bun test __tests__/components/MasonryLegendList.test.tsx
+      - run: bunx playwright install --with-deps chromium webkit
+        working-directory: example-web
+      - run: bun run typecheck:e2e
+        working-directory: example-web
+      - run: bun run test:e2e
+        working-directory: example-web
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: masonry-browser-failures
+          path: example-web/test-results/
+          if-no-files-found: ignore

.gitignore

@@ -4,3 +4,6 @@ example/android
 example/ios
 legendapp-list.tgz
 tsconfig.tsbuildinfo
+
+example-web/test-results/
+example-web/playwright-report/

CHANGELOG.md

@@ -1,3 +1,8 @@
+## Unreleased
+
+- Feat: Add optional `MasonryLegendList` for vertical, variable-height columns.
+- Fix: Preserve pending column reflow across React render replay.
+
 ## 3.3.11
 
 - Fix: `scrollToEnd` and `maintainScrollAtEnd` keep reaching the end as content changes, while scrolling away or requesting another position cancels automatic following.

README.md

@@ -110,6 +110,26 @@ export default LegendListExample
 
 ```
 
+### Masonry layout
+
+Import `MasonryLegendList` from the optional masonry entrypoint to place each item in the shortest available column without adding the masonry implementation to the core bundle.
+
+```tsx
+import { MasonryLegendList } from "@legendapp/list/masonry"
+
+<MasonryLegendList
+    contentContainerStyle={{ columnGap: 12, rowGap: 12 }}
+    data={photos}
+    estimatedItemSize={180}
+    keyExtractor={(photo) => photo.id}
+    numColumns={2}
+    recycleItems
+    renderItem={({ item }) => <PhotoCard photo={item} />}
+/>
+```
+
+Masonry lists are vertical and support dynamically measured or fixed-size items. Column spans and `overrideItemLayout` are not supported.
+
 ---
 
 ## How to Build
@@ -123,6 +143,29 @@ export default LegendListExample
 2. `bun i`
 3. `bun run ios`
 
+## Masonry regression checks
+
+From the repository root, run `bun install --frozen-lockfile` and `bun test`.
+For browser E2E checks:
+
+```sh
+cd example-web
+bun install --frozen-lockfile
+bunx playwright install chromium webkit
+bun run test:e2e
+```
+
+The runner starts and stops its own fixture server. Chromium and WebKit checks cover
+recycled-card identity, prepend anchoring, append, actual column placement, dynamic
+tall-card visibility during reverse scrolling, and reset at two viewport widths.
+Failures retain screenshots and traces in `example-web/test-results/`. The Masonry E2E
+workflow runs these checks for pull requests.
+
+For native interaction checks, run `bun run ios:fixtures` or `bun run android:fixtures`
+in `example`, then open Masonry. Scroll before tapping a card and check the Selected
+identity; exercise Prepend, Append, Columns, Toggle tall card, Reset, and Back. These
+fixture checks do not establish release performance or app-specific acceptance.
+
 ## PRs gladly accepted!
 
 There's not a ton of code so hopefully it's easy to contribute. If you want to add a missing feature or fix a bug please post an issue to see if development is already in progress so we can make sure to not duplicate work 😀.
@@ -132,7 +175,7 @@ There's not a ton of code so hopefully it's easy to contribute. If you want to a
 - [] Column spans
 - [] overrideItemLayout
 - [] Sticky headers
-- [] Masonry layout
+- [x] Masonry layout
 - [] getItemType
 - [] React DOM implementation