Masonry: add experimental support for two-column items

docs/integration-test-helpers/masonry/ExampleGridItem.js

@@ -20,6 +20,8 @@ export default function ExampleGridItem({ data = {}, itemIdx, expanded }: Props)
     setCounter((prevCounter) => prevCounter + 1);
   }
 
+  const isTwoColItem = data.columnSpan === 2;
+
   return (
     <div
       style={{
@@ -30,11 +32,13 @@ export default function ExampleGridItem({ data = {}, itemIdx, expanded }: Props)
         style={{
           height: expanded ? data.height + 100 : data.height,
           border: '1px solid #ff0000',
-          background: data.color,
+          background: isTwoColItem ? 'black' : data.color,
+          color: isTwoColItem ? 'white' : undefined,
         }}
       >
         <div>
           {data.name} • {data.height}px
+          {isTwoColItem ? ` • columnSpan: ${data.columnSpan}` : ''}
         </div>
         <div>Slot Index: {itemIdx}</div>
         <div>

docs/integration-test-helpers/masonry/MasonryContainer.js

@@ -1,5 +1,5 @@
 // @flow strict
-import { Component, createRef, type Element, type Node } from 'react';
+import { Component, createRef, type Element } from 'react';
 import { Masonry } from 'gestalt';
 import ExampleGridItem from './ExampleGridItem.js';
 import getClassicGridServerStyles from './getClassicGridServerStyles.js';
@@ -18,6 +18,8 @@ import getRandomNumberGenerator from './items-utils/getRandomNumberGenerator.js'
 // Masonry works, MasonryContainer also supports certain SSR functionality such
 // as generating styles that affect pre-hydration Masonry content.
 
+const TWO_COL_MINDEX = 50;
+
 type Props = {|
   // The actual Masonry component to be used (if using an experimental version of Masonry).
   MasonryComponent: typeof Masonry,
@@ -49,6 +51,8 @@ type Props = {|
   pinHeightsSample?: $ReadOnlyArray<number>,
   // If we should position the grid within a scrollContainer besides the window.
   scrollContainer?: boolean,
+  // Insert two-column items into the feed
+  twoColItems?: boolean,
   // If we should virtualize the grid
   virtualize?: boolean,
   // The relative amount in pixel to extend the virtualized viewport top value.
@@ -206,7 +210,7 @@ export default class MasonryContainer extends Component<Props, State> {
     from = 0,
     force = false,
   }) => {
-    const { collage, manualFetch, pinHeightsSample } = this.props;
+    const { collage, manualFetch, pinHeightsSample, twoColItems } = this.props;
 
     if (manualFetch && !force) {
       return;
@@ -231,13 +235,15 @@ export default class MasonryContainer extends Component<Props, State> {
             previousItemCount: from,
             randomNumberSeed: Math.random(),
             pinHeightsSample,
+            twoColItems: twoColItems && from > TWO_COL_MINDEX,
           })
         : generateExampleItems({
             name,
             numberOfItems: until - from,
             previousItemCount: from,
             baseHeight,
             randomNumberSeed: this.randomNumberSeed,
+            twoColItems: twoColItems && from > TWO_COL_MINDEX,
           });
 
     this.setState(({ items }) => ({
@@ -246,7 +252,7 @@ export default class MasonryContainer extends Component<Props, State> {
   };
 
   loadItems: $ElementType<React$ElementConfig<typeof Masonry>, 'loadItems'> = (props) => {
-    const { collage, manualFetch, pinHeightsSample } = this.props;
+    const { collage, manualFetch, pinHeightsSample, twoColItems } = this.props;
 
     if (manualFetch) {
       return;
@@ -273,22 +279,23 @@ export default class MasonryContainer extends Component<Props, State> {
             previousItemCount: defaultFrom,
             randomNumberSeed: Math.random(),
             pinHeightsSample,
+            twoColItems: twoColItems && defaultFrom > TWO_COL_MINDEX,
           })
         : generateExampleItems({
             name: undefined,
             numberOfItems: until - defaultFrom,
             previousItemCount: defaultFrom,
             baseHeight,
             randomNumberSeed: this.randomNumberSeed,
+            twoColItems: twoColItems && defaultFrom > TWO_COL_MINDEX,
           });
 
     this.setState(({ items }) => ({
       items: [...items, ...newItems],
     }));
   };
 
-  // $FlowFixMe[unclear-type]
-  renderItem: ({| +data: any, +itemIdx: number, +isMeasuring: boolean |}) => Node = ({
+  renderItem: $ElementType<React$ElementConfig<typeof Masonry>, 'renderItem'> = ({
     data,
     itemIdx,
   }) => {

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

@@ -4,30 +4,42 @@ import getRandomNumberGenerator from './getRandomNumberGenerator.js';
 
 type Args = {|
   baseHeight?: number,
-  previousItemCount?: number,
   name?: string,
-  randomNumberSeed?: number,
   numberOfItems?: number,
+  previousItemCount?: number,
+  randomNumberSeed?: number,
+  twoColItems?: boolean,
 |};
 
 type ExampleItem = {|
-  name: string,
-  height: number,
   color: string,
+  columnSpan?: number,
+  height: number,
+  name: string,
 |};
 
 export default function generateExampleItems({
   baseHeight = 200,
-  previousItemCount = 0,
   name = 'Pin',
-  randomNumberSeed = 0,
   numberOfItems = 20,
+  previousItemCount = 0,
+  randomNumberSeed = 0,
+  twoColItems,
 }: Args): $ReadOnlyArray<ExampleItem> {
   const getRandomNumber = getRandomNumberGenerator(randomNumberSeed);
+  const twoColItemIndex = twoColItems ? Math.floor(Math.random() * numberOfItems) : undefined;
 
-  return Array.from({ length: numberOfItems }).map((_, i) => ({
-    name: `${name} ${i + previousItemCount}`,
-    height: baseHeight + previousItemCount + i,
-    color: getRandomColor(getRandomNumber),
-  }));
+  return Array.from({ length: numberOfItems }).map((_, i) => {
+    const pin = {
+      name: `${name} ${i + previousItemCount}`,
+      height: baseHeight + previousItemCount + i,
+      color: getRandomColor(getRandomNumber),
+    };
+    return Boolean(twoColItemIndex) && i === twoColItemIndex
+      ? {
+          ...pin,
+          columnSpan: 2,
+        }
+      : pin;
+  });
 }

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

@@ -3,15 +3,17 @@ import getRandomColor from './getRandomColor.js';
 import getRandomNumberGenerator from './getRandomNumberGenerator.js';
 
 type Args = {|
-  previousItemCount?: number,
   name?: string,
-  randomNumberSeed?: number,
   numberOfItems?: number,
   pinHeightsSample: $ReadOnlyArray<number>,
+  previousItemCount?: number,
+  randomNumberSeed?: number,
+  twoColItems?: boolean,
 |};
 
 type ExampleItem = {|
   color: string,
+  columnSpan?: number,
   height: number,
   name: string,
 |};
@@ -21,20 +23,28 @@ type ExampleItem = {|
  * This approach generates a finite set of pins with realistic heights — a fundamental shift from generating random pins on the fly. We have to take care to ensure that the same pins are generated on the server and the client. This is done by generating an array of random number seeds in `getServerSideProps` in docs/pages/integration-test/masonry.js, which are used to generate the pin heights. We then need to make sure we're pulling from these pin heights in a consistent way on the server and the client. This is where `randomNumberSeed` comes in: we pull the first `numberOfItems` heights from the array for SSR. For subsequent calls on the client, we use a random `randomNumberSeed` to pull random heights from the array. So SSR will always use the first `numberOfItems` heights, and we don't attempt to keep track of "where we are" in the heights array after that.
  */
 export default function generateRealisticExampleItems({
-  previousItemCount = 0,
   name = 'Pin',
-  randomNumberSeed = 0,
   numberOfItems = 20,
   pinHeightsSample,
+  previousItemCount = 0,
+  randomNumberSeed = 0,
+  twoColItems,
 }: Args): $ReadOnlyArray<ExampleItem> {
   const getRandomNumber = getRandomNumberGenerator(randomNumberSeed);
   const baseIndex = Math.ceil(randomNumberSeed * 10);
+  const twoColItemIndex = twoColItems ? Math.floor(Math.random() * numberOfItems) : undefined;
 
-  const pins = Array.from({ length: numberOfItems }).map((_, i) => ({
-    name: `${name} ${i + previousItemCount}`,
-    height: pinHeightsSample[baseIndex + i],
-    color: getRandomColor(getRandomNumber),
-  }));
-
-  return pins;
+  return Array.from({ length: numberOfItems }).map((_, i) => {
+    const pin = {
+      name: `${name} ${i + previousItemCount}`,
+      height: pinHeightsSample[baseIndex + i],
+      color: getRandomColor(getRandomNumber),
+    };
+    return Boolean(twoColItemIndex) && i === twoColItemIndex
+      ? {
+          ...pin,
+          columnSpan: 2,
+        }
+      : pin;
+  });
 }

docs/pages/integration-test/masonry.js

@@ -72,6 +72,7 @@ export default function TestPage({
     offsetTop,
     realisticPinHeights,
     scrollContainer,
+    twoColItems,
     virtualize,
     virtualBoundsTop,
     virtualBoundsBottom,
@@ -115,6 +116,7 @@ export default function TestPage({
           offsetTop={offsetTop}
           pinHeightsSample={realisticPinHeights ? pinHeightsSample : undefined}
           scrollContainer={booleanize(scrollContainer)}
+          twoColItems={booleanize(twoColItems)}
           virtualize={booleanize(virtualize)}
           virtualBoundsTop={virtualBoundsTop}
           virtualBoundsBottom={virtualBoundsBottom}