feat(image-list): Add Masonry Image List (#2381)

material-components · Mar 14, 2018 · d368fa7 · d368fa7
1 parent 30a29f6
commit d368fa7
Show file tree

Hide file tree

Showing 6 changed files with 218 additions and 1 deletion.
diff --git a/demos/image-list.html b/demos/image-list.html
@@ -304,6 +304,132 @@ <h1 class="mdc-typography--headline">Standard Image List</h1>
             </div>
           </li>
         </ul>
+
+        <h1 class="mdc-typography--headline">Masonry Image List</h1>
+        <div>
+          <div class="mdc-form-field">
+            <div class="mdc-radio">
+              <input class="mdc-radio__native-control" type="radio" id="masonry-label-below" name="masonry-labels" checked>
+              <div class="mdc-radio__background">
+                <div class="mdc-radio__outer-circle"></div>
+                <div class="mdc-radio__inner-circle"></div>
+              </div>
+            </div>
+            <label for="masonry-label-below">Labels below images</label>
+          </div>
+          <div class="mdc-form-field">
+            <div class="mdc-radio">
+              <input class="mdc-radio__native-control" type="radio" id="masonry-label-protected" name="masonry-labels">
+              <div class="mdc-radio__background">
+                <div class="mdc-radio__outer-circle"></div>
+                <div class="mdc-radio__inner-circle"></div>
+              </div>
+            </div>
+            <label for="masonry-label-protected">Labels over images with text protection</label>
+          </div>
+          <div class="mdc-form-field">
+            <div class="mdc-radio">
+              <input class="mdc-radio__native-control" type="radio" id="masonry-label-none" name="masonry-labels">
+              <div class="mdc-radio__background">
+                <div class="mdc-radio__outer-circle"></div>
+                <div class="mdc-radio__inner-circle"></div>
+              </div>
+            </div>
+            <label for="masonry-label-none">No labels</label>
+          </div>
+        </div>
+        <ul id="masonry-image-list" class="mdc-image-list mdc-image-list--masonry masonry-image-list">
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/1-1.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/16-9.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/4-3.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/16-9.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/4-3.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/16-9.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/1-1.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/16-9.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/1-1.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/16-9.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/1-1.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/4-3.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/1-1.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/16-9.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+          <li class="mdc-image-list__item">
+            <img class="mdc-image-list__image" src="images/4-3.jpg">
+            <div class="mdc-image-list__supporting">
+              <span class="mdc-image-list__label">Text label</span>
+            </div>
+          </li>
+        </ul>
       </section>
     </main>
 
@@ -327,6 +453,7 @@ <h1 class="mdc-typography--headline">Standard Image List</h1>
         });
 
         var standardImageListEl = document.getElementById('standard-image-list');
+        var masonryImageListEl = document.getElementById('masonry-image-list');
 
         document.getElementById('standard-label-below').addEventListener('change', function() {
           standardImageListEl.classList[this.checked ? 'remove' : 'add']('mdc-image-list--with-text-protection');
@@ -342,6 +469,21 @@ <h1 class="mdc-typography--headline">Standard Image List</h1>
           standardImageListEl.classList[this.checked ? 'remove' : 'add']('mdc-image-list--with-text-protection');
           standardImageListEl.classList[this.checked ? 'add' : 'remove']('hide-supporting');
         });
+
+        document.getElementById('masonry-label-below').addEventListener('change', function() {
+          masonryImageListEl.classList[this.checked ? 'remove' : 'add']('mdc-image-list--with-text-protection');
+          masonryImageListEl.classList[this.checked ? 'remove' : 'add']('hide-supporting');
+        });
+
+        document.getElementById('masonry-label-protected').addEventListener('change', function() {
+          masonryImageListEl.classList[this.checked ? 'add' : 'remove']('mdc-image-list--with-text-protection');
+          masonryImageListEl.classList[this.checked ? 'remove' : 'add']('hide-supporting');
+        });
+
+        document.getElementById('masonry-label-none').addEventListener('change', function() {
+          masonryImageListEl.classList[this.checked ? 'remove' : 'add']('mdc-image-list--with-text-protection');
+          masonryImageListEl.classList[this.checked ? 'add' : 'remove']('hide-supporting');
+        });
       });
     </script>
   </body>

diff --git a/demos/image-list.scss b/demos/image-list.scss
@@ -37,6 +37,11 @@
   max-width: 1000px;
 }
 
+.mdc-image-list.masonry-image-list {
+  @include mdc-image-list-masonry-columns(5);
+  max-width: 1000px;
+}
+
 .hide-supporting .mdc-image-list__supporting {
   display: none;
 }
@@ -49,4 +54,8 @@
   .mdc-image-list.standard-image-list {
     @include mdc-image-list-standard-columns(3);
   }
+
+  .mdc-image-list.masonry-image-list {
+    @include mdc-image-list-masonry-columns(3);
+  }
 }
diff --git a/packages/mdc-image-list/README.md b/packages/mdc-image-list/README.md
@@ -71,13 +71,46 @@ columns should be displayed per line:
 Images in a Standard Image list are constrained to 1:1 aspect ratio by default; this can be overridden using the
 `mdc-image-list-aspect` mixin documented below.
 
+## Variants
+
+### Masonry Image List
+
+The Masonry Image List variant presents images vertically arranged into several columns, using
+[CSS Columns](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Columns). In this layout, images may be any
+combination of aspect ratios.
+
+```html
+<ul class="mdc-image-list mdc-image-list--masonry my-masonry-image-list">
+  <li class="mdc-image-list__item">
+    <img class="mdc-image-list__image" src="...">
+    <div class="mdc-image-list__supporting">
+      <span class="mdc-image-list__label">Text label</span>
+    </div>
+  </li>
+  ...
+</ul>
+```
+
+> **Note:** Masonry Image List items _do not_ include the `mdc-image-list__image-aspect-container` element, since
+images in the list are not expected to be locked to a common aspect ratio.
+
+This would be combined with an invocation of the `mdc-image-list-masonry-columns` mixin, to establish how many columns
+should be displayed:
+
+```scss
+.my-masonry-image-list {
+  @include mdc-image-list-masonry-columns(5);
+}
+```
+
 ## Style Customization
 
 ### CSS Classes
 
 CSS Class | Description
 --- | ---
 `mdc-image-list` | Mandatory. Indicates the root Image List element.
+`mdc-image-list--masonry` | Optional. Indicates that this Image List should use the Masonry variant.
 `mdc-image-list--with-text-protection` | Optional. Indicates that supporting content should be positioned in a scrim overlaying each image (instead of positioned separately under each image).
 `mdc-image-list__item` | Mandatory. Indicates each item in an Image List.
 `mdc-image-list__image-aspect-container` | Optional. Parent of each item's image element, responsible for constraining aspect ratio. This element may be omitted entirely if images are already sized to the correct aspect ratio.
@@ -92,12 +125,16 @@ Mixin | Description
 `mdc-image-list-aspect($width-height-ratio)` | Styles the aspect container elements within an Image List to conform to the given ratio, where 1 is 1:1, greater than 1 is wider, and less than 1 is taller.
 `mdc-image-list-corner-radius($radius)` | Styles the image and supporting content elements within an Image List to have rounded corners with the given radius.
 `mdc-image-list-standard-columns($column-count, $gutter-size)` | Styles a Standard Image List to display the given number of columns. `$gutter-size` is optional and overrides the default amount of space between items.
+`mdc-image-list-masonry-columns($column-count, $gutter-size)` | Styles a Masonry Image List to display the given number of columns. `$gutter-size` is optional and overrides the default amount of space between items.
+
+> **Note:** Only one of the `mdc-image-list-...-columns` mixins should be used for any given Image List.
+> Use the mixin appropriate to the variant being used.
 
 ### Additional Information
 
 #### Constraining width
 
-The `mdc-image-list-standard-columns` mixin will grow and shrink items based on the Image List's overall width. Depending on
+The `mdc-image-list-...-columns` mixins will grow and shrink items based on the Image List's overall width. Depending on
 placement, this could be directly related to the viewport width, and images could become exceedingly large compared to
 their actual rendered size. This can be restricted by using any of `min-width`, `width`, or `max-width` on the Image
 List:
@@ -131,6 +168,8 @@ needs to be changed are styles:
 
 #### Using div in place of img to enforce aspect ratio
 
+> **Note:** This advice is not applicable to Masonry Image List, where images do not share a common aspect ratio.
+
 Images in an Image List typically use the `img` element. However, if your assets don't have the same aspect ratio as
 specified for list items, they will become distorted. In these cases, you can use a `div` element in place of `img`,
 and set the `background-image` of each.

diff --git a/packages/mdc-image-list/_mixins.scss b/packages/mdc-image-list/_mixins.scss
@@ -41,3 +41,14 @@
     margin: $gutter-size / 2;
   }
 }
+
+// Masonry Image List
+
+@mixin mdc-image-list-masonry-columns($column-count, $gutter-size: $mdc-image-list-masonry-gutter-size) {
+  column-count: $column-count;
+  column-gap: $gutter-size;
+
+  .mdc-image-list__item {
+    margin-bottom: $gutter-size;
+  }
+}
diff --git a/packages/mdc-image-list/_variables.scss b/packages/mdc-image-list/_variables.scss
@@ -13,6 +13,7 @@
 // limitations under the License.
 
 $mdc-image-list-standard-gutter-size: 4px;
+$mdc-image-list-masonry-gutter-size: 16px;
 $mdc-image-list-icon-size: 24px;
 $mdc-image-list-text-protection-background-color: rgba(0, 0, 0, .6);
 $mdc-image-list-text-protection-height: 48px;

diff --git a/packages/mdc-image-list/mdc-image-list.scss b/packages/mdc-image-list/mdc-image-list.scss
@@ -85,3 +85,18 @@
   background: $mdc-image-list-text-protection-background-color;
   color: #fff;
 }
+
+// Masonry Image List, using CSS columns (i.e. renders down then across)
+
+.mdc-image-list--masonry {
+  display: block; // Override flex
+
+  .mdc-image-list__item {
+    break-inside: avoid-column;
+  }
+
+  .mdc-image-list__image {
+    display: block;
+    height: auto;
+  }
+}