Masonry: add experimental support for two-column items #2955

dangerismycat · 2023-05-19T20:48:50Z

Summary

This PR introduces a proof-of-concept to support rendering 2-column modules in the Masonry grid. See the project doc for a comprehensive summary of the project.

This PR adds an undocumented experimental prop to Masonry. When this prop is true (and using layout is "basic" or "basicCentered", Masonry will use a new layout algorithm. When a batch of pins to be laid out contains a 2-col module, we switch from the classic layout algorithm ("put the item in the shortest column") to a graph-based approach. This approach takes inspiration from the seminal Knuth+Plass text layout algorithm for TeX to explore every possible layout using the 1-col items in the batch, looking for the layout that will yield two adjacent columns of very similar height. The 2-col module will be inserted in this location, and the remaining 1-col items will be laid out normally.

A major conceptual change for this is that when using the new algorithm, we cache the column heights array and item positions (by item data reference). In the classic algorithm, we throw away heights and positions on each render and lay out the entire grid from scratch each time. This depends on a major assumption: that grid items will always be laid out in the order given. Since we now break that assumption in the batch of items containing the 2-col module we need to be able to directly associate position with a specific item, not just an items index.

This PR does not yet implement pin leveling to minimize whitespace above the 2-col module. That technique may not be necessary for an MVP for this project — and if it is, it can be implemented in a future PR.

Testing these changes

Since this is an experimental POC, the changes are not represented on the Masonry docs page. Here's how to test locally:

pull down this branch locally
run yarn start
visit http://localhost:8888/integration-test/masonry?realisticPinHeights=1&twoColItems=1 (realisticPinHeights is optional)

Demo

Screen.Recording.2023-06-22.at.2.47.18.PM.mov

A note about this demo: this is using the "realistic pin heights" option introduced back in #2823. Though based on actual pin data, the "realism" here is questionable. There seems to be a lot more variation in heights than I've ever seen in a grid. So the whitespace above 2-col modules is possibly (probably?) worse than it will be in a "real world" grid.

netlify · 2023-05-19T20:51:53Z

✅ Deploy Preview for gestalt ready!

Name	Link
🔨 Latest commit	`cf3ce21`
🔍 Latest deploy log	https://app.netlify.com/sites/gestalt/deploys/649610a4d11a740008f18fde
😎 Deploy Preview	https://deploy-preview-2955--gestalt.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

packages/gestalt/src/Masonry/defaultLayout.js

liuyenwei · 2023-06-23T00:41:54Z

packages/gestalt/src/Masonry/defaultTwoColumnModuleLayout.js

+      // Combine winning positions and 2-col item position, add to cache
+      const finalPositions = [
+        ...winningPositions,
+        { item: twoColItem, position: twoColItemPosition },


thinking ahead, once we integrate this into Pinboard it would be good to somehow have access to this so we can log data on average number of whitespace we end up with per pass. maybe something like a callback prop could help with that e.g. onTwoColumnLayout(position, heights)

Yeah I was thinking about that as well. I think I'll add that in a future PR so we can start playing around with these changes in Pinboard

liuyenwei · 2023-06-23T00:43:17Z

packages/gestalt/src/Masonry.js

-const layoutNumberToCssDimension = (n: ?number) => (n !== Infinity ? n : undefined);
+// When there's a 2-col item in the most recently fetched batch of items, we need to measure more items to ensure we have enough possible layouts to find a suitable one
+// The number of items measured at a time is the number of columns * this multiplier
+const TWO_COL_ITEMS_MEASURE_BATCH_SIZE = 6;


maybe a comment around why this is static and why we're doing 6

Ah good call, I didn't update that comment

liuyenwei · 2023-06-23T00:43:56Z

packages/gestalt/src/Masonry.js

   */
  renderItem: ({|
    +data: T,
    +itemIdx: number,
    +isMeasuring: boolean,
+    +heightAdjustment?: number,


do we need this atm?

Sorry, I'd left a comment explaining and then forgot to submit 🤦 We don't need it yet, so it could be removed. This will be used for future pin leveling work.

liuyenwei · 2023-06-23T00:46:09Z

packages/gestalt/src/Masonry.js

+
+      const itemsWithoutPositions = items.filter((item) => item && !positionStore.has(item));
+      // $FlowFixMe[prop-missing] We're assuming `columnSpan` exists
+      const hasTwoColumnItems = itemsWithoutPositions.some((item) => item.columnSpan === 2);


const hasTwoColumnItems = _twoColItems && itemsWithout....?

Good catch!

dangerismycat · 2023-06-22T22:40:54Z

docs/integration-test-helpers/masonry/items-utils/generateExampleItems.js

  numberOfItems?: number,
+  previousItemCount?: number,
+  randomNumberSeed?: number,
+  twoColItems?: boolean,


This is new, the rest is alphabetizing

dangerismycat · 2023-06-22T22:41:03Z

docs/integration-test-helpers/masonry/items-utils/generateExampleItems.js

  color: string,
+  columnSpan?: number,


This is new, the rest is alphabetizing

dangerismycat · 2023-06-22T22:41:07Z

docs/integration-test-helpers/masonry/items-utils/generateExampleItems.js

  numberOfItems = 20,
+  previousItemCount = 0,
+  randomNumberSeed = 0,
+  twoColItems,


This is new, the rest is alphabetizing

dangerismycat · 2023-06-22T22:41:25Z

docs/integration-test-helpers/masonry/items-utils/generateRealisticExampleItems.js

  numberOfItems?: number,
  pinHeightsSample: $ReadOnlyArray<number>,
+  previousItemCount?: number,
+  randomNumberSeed?: number,
+  twoColItems?: boolean,


This is new, the rest is alphabetizing

dangerismycat · 2023-06-22T22:41:35Z

docs/integration-test-helpers/masonry/items-utils/generateRealisticExampleItems.js

  numberOfItems = 20,
  pinHeightsSample,
+  previousItemCount = 0,
+  randomNumberSeed = 0,
+  twoColItems,


This is new, the rest is alphabetizing

dangerismycat · 2023-06-22T22:42:24Z

packages/gestalt/src/Masonry.js

   */
  renderItem: ({|
    +data: T,
    +itemIdx: number,
    +isMeasuring: boolean,
+    +heightAdjustment?: number,


This will be for future pin leveling support. Could possibly be removed for now, not used yet

dangerismycat · 2023-06-22T22:42:50Z

packages/gestalt/src/Masonry.js

+   *
+   * This is an experimental prop and may be removed in the future.
+   */
+  _twoColItems?: boolean,


Props prefixed with _ are automatically filtered out of the autogen Props tables in the docs

dangerismycat · 2023-06-22T22:43:13Z

packages/gestalt/src/Masonry.js

@@ -201,6 +179,52 @@ export default class Masonry<T: { ... }> extends ReactComponent<Props<T>, State<
    };
  }

+  containerHeight: number;


None of these changed, just organizing

dangerismycat · 2023-06-22T22:46:41Z

packages/gestalt/src/Masonry/GraphNode.js

+
+type Edge<T> = {|
+  score: number,
+  // eslint-disable-next-line no-use-before-define


This is circular, can't be avoided

dangerismycat · 2023-06-22T22:47:12Z

packages/gestalt/src/Masonry/MeasurementStore.js

@@ -1,7 +1,6 @@
 // @flow strict
 import { type Cache } from './Cache.js';

-// replace V with "number"


This old note to myself was wrong, I needed to fix the generic type used in Masonry

dangerismycat added 8 commits May 19, 2023 13:44

add graph classes

ad44bd5

add support for twoColItems query param

147afce

remove unneeded comment

8376d62

add support for generating two column items

dcf0865

fix MasonryContainer.renderItem type

d2ad8e2

add support in MasonryContainer for two-column items

6cc22dd

add renderItem arg for eventual item height adjustments

ab4e5c4

the bizness, WIP

aea4bcf

dangerismycat added 15 commits May 19, 2023 14:00

add support for edge scores

1ef3af9

get offscreen positions earlier

9d35ad6

insert 2-col items later in the batches

50d1f69

WIP

b9c4369

s/isNotNil/isNil

28f525e

fix measurementStore type

8036604

sort class fields

be130d7

add Masonry.numColumns

29c47f4

s/itemsToRender/itemsWithMeasurements for clarity

325b399

refactor defaultLayout to return the number of columns

ce46866

determine batch of items to measure using number of columns

90e4189

WIP

2f20988

WIP

9b9cd7b

WIP

edeadf7

holy crap it works

a101d4e

liuyenwei reviewed Jun 22, 2023

View reviewed changes

packages/gestalt/src/Masonry/defaultLayout.js Outdated Show resolved Hide resolved

dangerismycat added 2 commits June 22, 2023 14:19

Fork defaultLayout for 2-col support, use experimental prop

cb05c60

Merge branch 'master' into masonry-two-column-items

cc3929f

dangerismycat added the minor release Minor release label Jun 22, 2023

dangerismycat added 2 commits June 22, 2023 14:34

fix Flow issues

72718d0

remove Position.column (not needed)

7f5ce86

dangerismycat added 2 commits June 22, 2023 14:49

remove unneeded suppression

98a8d81

remove prettyPrintGraph method (it never worked well anyway)

2e1ea79

dangerismycat changed the title ~~[WIP] Masonry: add experimental support for two-column items~~ Masonry: add experimental support for two-column items Jun 22, 2023

dangerismycat marked this pull request as ready for review June 22, 2023 22:25

dangerismycat requested a review from a team as a code owner June 22, 2023 22:25

dangerismycat added 2 commits June 22, 2023 15:49

cleanup

456853d

readonlyarray in graphnode

8d08231

liuyenwei approved these changes Jun 23, 2023

View reviewed changes

dangerismycat commented Jun 23, 2023

View reviewed changes

dangerismycat added 3 commits June 23, 2023 14:17

update comment

03e802d

improve hasTwoColumnItems check

512087b

guh

cf3ce21

dangerismycat merged commit 116ced6 into pinterest:master Jun 23, 2023
15 checks passed

dangerismycat deleted the masonry-two-column-items branch June 23, 2023 22:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Masonry: add experimental support for two-column items #2955

Masonry: add experimental support for two-column items #2955

dangerismycat commented May 19, 2023 •

edited

netlify bot commented May 19, 2023 •

edited

liuyenwei Jun 23, 2023

dangerismycat Jun 23, 2023

liuyenwei Jun 23, 2023

dangerismycat Jun 23, 2023

liuyenwei Jun 23, 2023

dangerismycat Jun 23, 2023

liuyenwei Jun 23, 2023

dangerismycat Jun 23, 2023

dangerismycat Jun 22, 2023

dangerismycat Jun 22, 2023

dangerismycat Jun 22, 2023

dangerismycat Jun 22, 2023

dangerismycat Jun 22, 2023

dangerismycat Jun 22, 2023

dangerismycat Jun 22, 2023

dangerismycat Jun 22, 2023

dangerismycat Jun 22, 2023

dangerismycat Jun 22, 2023

Masonry: add experimental support for two-column items #2955

Masonry: add experimental support for two-column items #2955

Conversation

dangerismycat commented May 19, 2023 • edited

Summary

Testing these changes

Demo

netlify bot commented May 19, 2023 • edited

✅ Deploy Preview for gestalt ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dangerismycat commented May 19, 2023 •

edited

netlify bot commented May 19, 2023 •

edited