[Masonry] Add comments

mui · Oct 18, 2021 · c6f063c · c6f063c
1 parent 05c406c
commit c6f063c
Show file tree

Hide file tree

Showing 3 changed files with 13 additions and 7 deletions.
diff --git a/docs/translations/api-docs/masonry/masonry.json b/docs/translations/api-docs/masonry/masonry.json
@@ -7,7 +7,7 @@
     "component": "The component used for the root node. Either a string to use a HTML element or a component.",
     "defaultColumns": "The default number of columns of the component. This is provided for server-side rendering.",
     "defaultHeight": "The default height of the component in px. This is provided for server-side rendering.",
-    "defaultSpacing": "The default spacing of the component. This is provided for server-side rendering.",
+    "defaultSpacing": "The default spacing of the component. Like <code>spacing</code>, it is a factor of the theme&#39;s spacing. This is provided for server-side rendering.",
     "spacing": "Defines the space between children. It is a factor of the theme&#39;s spacing.",
     "sx": "Allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/the-sx-prop/\">`sx` page</a> for more details."
   },

diff --git a/packages/mui-lab/src/Masonry/Masonry.d.ts b/packages/mui-lab/src/Masonry/Masonry.d.ts
@@ -27,7 +27,7 @@ export interface MasonryTypeMap<P = {}, D extends React.ElementType = 'div'> {
      */
     defaultHeight?: number;
     /**
-     * The default spacing of the component. This is provided for server-side rendering.
+     * The default spacing of the component. Like `spacing`, it is a factor of the theme's spacing. This is provided for server-side rendering.
      */
     defaultSpacing?: number;
     /**

diff --git a/packages/mui-lab/src/Masonry/Masonry.js b/packages/mui-lab/src/Masonry/Masonry.js
@@ -22,12 +22,14 @@ const useUtilityClasses = (ownerState) => {
   return composeClasses(slots, getMasonryUtilityClass, classes);
 };
 
+// compute base for responsive values; e.g.,
+// [1,2,3] => {xs: true, sm: true, md: true}
+// {xs: 1, sm: 2, md: 3} => {xs: true, sm: true, md: true}
 const computeBreakpointsBase = (breakpoints, prop) => {
   const base = {};
   if (Array.isArray(prop)) {
-    const arrayLen = prop.length;
-    Object.keys(breakpoints.values).forEach((breakpoint, i) => {
-      if (i < arrayLen) {
+    Object.keys(breakpoints.values).forEach((breakpoint, i, arr) => {
+      if (i < arr.length) {
         base[breakpoint] = true;
       }
     });
@@ -41,11 +43,13 @@ const computeBreakpointsBase = (breakpoints, prop) => {
   return base;
 };
 
+// if prop is an array, convert to object; e.g.,
+// (base: {xs: true, sm: true, md: true}, prop: [1,2,3]) => {xs: 1, sm: 2, md: 3}
 const validatePropValues = (base, prop) => {
   const values = {};
   if (Array.isArray(prop)) {
     Object.keys(base).forEach((breakpoint, i) => {
-      values[breakpoint] = Number(prop[i]);
+      values[breakpoint] = prop[i];
     });
     return values;
   }
@@ -285,6 +289,8 @@ const Masonry = React.forwardRef(function Masonry(inProps, ref) {
       {...other}
     >
       {children}
+      {/* columns are likely to have different heights and hence can start to merge;
+           a line break at the end of each column prevents columns from merging */}
       {new Array(numberOfLineBreaks).fill('').map((_, index) => (
         <span key={index} data-class="line-break" style={{ ...lineBreakStyle, order: index + 1 }} />
       ))}
@@ -333,7 +339,7 @@ Masonry.propTypes /* remove-proptypes */ = {
    */
   defaultHeight: PropTypes.number,
   /**
-   * The default spacing of the component. This is provided for server-side rendering.
+   * The default spacing of the component. Like `spacing`, it is a factor of the theme's spacing. This is provided for server-side rendering.
    */
   defaultSpacing: PropTypes.number,
   /**