Masonry Layout

/**
 * Pinterest-style masonry layout component
 * @param props - Masonry configuration props
 * @returns Masonry layout container
 */
function Masonry(props: MasonryProps): JSX.Element;

interface MasonryProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>> {
  /** Child elements to arrange in masonry layout (required) */
  children: NonNullable<React.ReactNode>;
  /** CSS classes for styling customization */
  classes?: Partial<MasonryClasses>;
  /** Number of columns or responsive breakpoint object (default: 4) */
  columns?: ResponsiveStyleValue<number | string>;
  /** Default number of columns for SSR (server-side rendering) */
  defaultColumns?: number;
  /** Default height for SSR calculations */
  defaultHeight?: number;
  /** Default spacing for SSR calculations */
  defaultSpacing?: number;
  /** Spacing between items or responsive spacing object (default: 1) */
  spacing?: ResponsiveStyleValue<number | string>;
  /** Use sequential column assignment instead of shortest column (default: false) */
  sequential?: boolean;
  /** System prop for styling */
  sx?: SxProps<Theme>;
}

interface MasonryClasses {
  /** Class applied to the root element */
  root: string;
}

import React from 'react';
import { Masonry } from '@mui/lab';
import { Card, CardContent, Typography } from '@mui/material';

// Basic masonry layout
function BasicMasonry() {
  const items = [
    { height: 150, title: 'Item 1' },
    { height: 200, title: 'Item 2' },
    { height: 100, title: 'Item 3' },
    // ... more items
  ];

  return (
    <Masonry columns={3} spacing={2}>
      {items.map((item, index) => (
        <Card key={index} sx={{ height: item.height }}>
          <CardContent>
            <Typography variant="h6">{item.title}</Typography>
          </CardContent>
        </Card>
      ))}
    </Masonry>
  );
}

// Responsive masonry with breakpoint-specific columns
function ResponsiveMasonry() {
  return (
    <Masonry
      columns={{
        xs: 1,
        sm: 2,
        md: 3,
        lg: 4,
        xl: 5
      }}
      spacing={{
        xs: 1,
        sm: 2,
        md: 3
      }}
    >
      {children}
    </Masonry>
  );
}

// Sequential column assignment (left-to-right instead of shortest-first)
function SequentialMasonry() {
  return (
    <Masonry columns={4} spacing={2} sequential={true}>
      {children}
    </Masonry>
  );
}

// Responsive value type supporting Material-UI breakpoints
type ResponsiveStyleValue<T> = T | {
  xs?: T;  // 0px and up
  sm?: T;  // 600px and up  
  md?: T;  // 900px and up
  lg?: T;  // 1200px and up
  xl?: T;  // 1536px and up
};

function SSRMasonry() {
  return (
    <Masonry
      columns={{ xs: 1, sm: 2, md: 3 }}
      spacing={2}
      defaultColumns={2}
      defaultHeight={200}
      defaultSpacing={16}
    >
      {children}
    </Masonry>
  );
}

/**
 * Parse string or number value to number for calculations
 * @param val - String or number value to parse
 * @returns Parsed number value
 */
function parseToNumber(val: string | number): number;

/**
 * Generate CSS styles for masonry layout
 * @param options - Style generation options
 * @returns CSS style object
 */
function getStyle(options: {
  ownerState: MasonryProps;
  theme: Theme;
}): React.CSSProperties;

// Balanced height distribution (default)
<Masonry columns={3} sequential={false}>

// Preserves left-to-right order
<Masonry columns={3} sequential={true}>

// Available CSS classes for Masonry
const masonryClasses: {
  root: string;
};