feat(grid-list): Implement mdc-grid-list (#47)

demos/index.html

@@ -33,6 +33,7 @@
           <li><a href="drawer/permanent-drawer-below-toolbar.html">Drawer (permanent, below toolbar)</a></li>
           <li><a href="elevation.html">Elevation</a></li>
           <li><a href="fab.html">FAB</a></li>
+          <li><a href="grid-list.html">Grid List</a></li>
           <li><a href="icon-toggle.html">Icon Toggle</a></li>
           <li><a href="layout-grid.html">Layout grid</a></li>
           <li><a href="list.html">List</a></li>

packages/material-components-web/index.js

@@ -17,6 +17,7 @@
 import * as base from '@material/base';
 import * as checkbox from '@material/checkbox';
 import * as formField from '@material/form-field';
+import * as gridList from '@material/grid-list';
 import * as iconToggle from '@material/icon-toggle';
 import * as radio from '@material/radio';
 import * as ripple from '@material/ripple';
@@ -31,6 +32,7 @@ import autoInit from '@material/auto-init';
 autoInit.register('MDCCheckbox', checkbox.MDCCheckbox);
 autoInit.register('MDCTemporaryDrawer', drawer.MDCTemporaryDrawer);
 autoInit.register('MDCRipple', ripple.MDCRipple);
+autoInit.register('MDCGridList', gridList.MDCGridList);
 autoInit.register('MDCIconToggle', iconToggle.MDCIconToggle);
 autoInit.register('MDCRadio', radio.MDCRadio);
 autoInit.register('MDCSnackbar', snackbar.MDCSnackbar);
@@ -43,6 +45,7 @@ export {
   base,
   checkbox,
   formField,
+  gridList,
   iconToggle,
   radio,
   ripple,

packages/material-components-web/material-components-web.scss

@@ -22,6 +22,7 @@
 @import "@material/elevation/mdc-elevation";
 @import "@material/fab/mdc-fab";
 @import "@material/form-field/mdc-form-field";
+@import "@material/grid-list/mdc-grid-list";
 @import "@material/icon-toggle/mdc-icon-toggle";
 @import "@material/layout-grid/mdc-layout-grid";
 @import "@material/list/mdc-list";

packages/material-components-web/package.json

@@ -23,6 +23,7 @@
     "@material/elevation": "^0.1.3",
     "@material/fab": "^0.3.2",
     "@material/form-field": "^0.2.0",
+    "@material/grid-list": "^0.0.0",
     "@material/icon-toggle": "^0.1.4",
     "@material/layout-grid": "^0.1.1",
     "@material/list": "^0.2.2",

packages/mdc-grid-list/README.md

@@ -0,0 +1,195 @@
+# MDC Grid List
+
+MDC Grid List provides a RTL-aware Material Design Grid Lists component adhering to the
+[Material Design Grid List spec](https://material.io/guidelines/components/grid-lists.html)
+Grid List is best suited to presenting homogenous data, typically images. Each data in
+grid list is called a tile and tile maintains fixed width, height and padding between each
+other as window resizes. Meanwhile, margin changes to keep grid list remain centered.
+
+
+## Installation
+
+```
+npm install --save @material/grid-list
+```
+
+
+## Usage
+
+Basic grid list has the following structure:
+
+```html
+<div class="mdc-grid-list">
+  <ul class="mdc-grid-list__tiles">
+    <li class="mdc-grid-tile">
+      <div class="mdc-grid-tile__primary">
+        <img class="mdc-grid-tile__primary-content" src="images/1-1.jpg" />
+      </div>
+      <span class="mdc-grid-tile__secondary">
+        <span class="mdc-grid-tile__title">Title</span>
+      </span>
+    </li>
+    <li class="mdc-grid-tile">
+      <div class="mdc-grid-tile__primary">
+        <img class="mdc-grid-tile__primary-content" src="images/1-1.jpg" />
+      </div>
+      <span class="mdc-grid-tile__secondary">
+        <span class="mdc-grid-tile__title">Title</span>
+      </span>
+    </li>
+  </ul>
+</div>
+```
+
+The above markup will give you a grid list of tiles that:
+
+- Has with 4px padding in between
+- With 1x1 aspect ratio
+- Has one line footer caption with no icon
+
+You just need to put the content you want to load in `src` of
+`<img class="mdc-grid-tile__primary-content" src="..."/>`. However, if your
+assets don't have the same aspect ratio you as specified in the tile, it will
+distort those assets, we provide a solution of that case in
+[Use div in replace of img](#use-div-in-replace-of-img) section.
+
+Besides default setting, we provide the following modifiers. You can mix and
+match them to modify your grid list.
+
+
+### Change tile padding
+
+Grid list tiles can also have 1px padding instead of 4px by adding
+`mdc-grid-list--tile-gutter-1` modifier.
+
+```html
+<div class="mdc-grid-list mdc-grid-list--tile-gutter-1">
+  <ul class="mdc-grid-list__tiles">
+  ...
+  </ul>
+</div>
+```
+
+### Change aspect ratio of tile
+
+Grid list tiles support all material guideline recommended aspect ratio:
+
+- 1x1
+- 16x9
+- 2x3
+- 3x2
+- 4x3
+- 3x4
+
+```html
+<div class="mdc-grid-list mdc-grid-list--tile-aspect-16x9">
+<!-- or aspect ratio you name it. -->
+  <ul class="mdc-grid-list__tiles">
+  ...
+  </ul>
+</div>
+```
+
+As pointed out in the previous section as well, if your
+assets don't have the same aspect ratio you as specified in the tile, it will
+distort those assets, we provide a solution of that case in
+[Use div in replace of img](#use-div-in-replace-of-img) section.
+
+
+### Add support text to secondary content (caption)
+
+Grid list support one line caption by default. You can also add a line of support
+text if needed by adding `mdc-grid-list--twoline-caption` modifier and additional
+markup
+
+```html
+<div class="mdc-grid-list mdc-grid-list--twoline-caption">
+<!-- or aspect ratio you name it. -->
+  <ul class="mdc-grid-list__tiles">
+    <li class="mdc-grid-tile">
+      <div class="mdc-grid-tile__primary">
+        <img class="mdc-grid-tile__primary-content" src="images/1-1.jpg" />
+      </div>
+      <span class="mdc-grid-tile__secondary">
+        <span class="mdc-grid-tile__title">Title</span>
+        <span class="mdc-grid-tile__support-text">Support text</span>
+      </span>
+    </li>
+  </ul>
+</div>
+```
+
+### Add icon to secondary content (caption)
+
+You can add icon to caption by adding `mdc-grid-list--with-icon-align-start` or
+`mdc-grid-list--with-icon-align-end` and changing the markup.
+
+```html
+<div class="mdc-grid-list mdc-grid-list--with-icon-align-start">
+<!-- or aspect ratio you name it. -->
+  <ul class="mdc-grid-list__tiles">
+    <li class="mdc-grid-tile">
+      <div class="mdc-grid-tile__primary">
+        <img class="mdc-grid-tile__primary-content" src="images/1-1.jpg" />
+      </div>
+      <span class="mdc-grid-tile__secondary">
+        <i class="mdc-grid-tile__icon material-icons">star_border</i>
+        <span class="mdc-grid-tile__title">Title</span>
+      </span>
+    </li>
+  </ul>
+</div>
+```
+
+### Use div in replace of img
+
+In case you cannot ensure all your assets will have the same aspect ratio, you
+can use div instead of img markup. It will resize the assets to cover the tile
+and crop the assets to display the center part.
+
+```html
+<div class="mdc-grid-list mdc-grid-list--header-caption">
+  <ul class="mdc-grid-list__tiles">
+    <li class="mdc-grid-tile">
+      <div class="mdc-grid-tile__primary">
+        <div class="mdc-grid-tile__primary-content demo-grid-tile-content">
+      </div>
+      <span class="mdc-grid-tile__secondary">
+        <span class="mdc-grid-tile__title">Title</span>
+      </span>
+    </li>
+  </ul>
+</div>
+```
+
+In this case, you should set `background-image:url(...)` instead of `src`. However,
+the method results in a less semantic markup, so we don't use this method by
+default.
+
+
+### RTL Support
+
+`mdc-grid-list` is automatically RTL-aware, and will re-position elements whenever
+it, or its ancestors, has a `dir="rtl"` attribute.
+
+
+### Theme
+
+`mdc-grid-list` support theme. Tile primary uses background and text on
+background, secondary uses the primary color and text on primary.
+
+
+### Using the Foundation Class
+
+MDCGridList ships with an `MDCGridListFoundation` class that external frameworks and libraries
+can use to build their own MDCGridList components with minimal effort. As with all foundation
+classes, an adapter object must be provided. The adapter for grid list must provide the following
+functions, with correct signatures:
+
+| Method Signature | Description |
+| --- | --- |
+| `getOffsetWidth() => number` | Get root element offsetWidth. |
+| `getTileOffsetWidthAtIndex(index: number) => number` | Get offsetWidth of tile at specified index. |
+| `setTilesWidth(value: number) => void` | Set tiles container width to value. |
+| `registerResizeHandler(handler: Function) => void` | Registers a handler to be called when the surface (or its viewport) resizes. Our default implementation adds the handler as a listener to the window's `resize()` event. |
+| `deregisterResizeHandler(handler: Function) => void` | Unregisters a handler to be called when the surface (or its viewport) resizes. Our default implementation removes the handler as a listener to the window's `resize()` event. |

packages/mdc-grid-list/constants.js

@@ -0,0 +1,19 @@
+/**
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export const strings = {
+  TILES_SELECTOR: '.mdc-grid-list__tiles',
+  TILE_SELECTOR: '.mdc-grid-tile',
+};

packages/mdc-grid-list/foundation.js

@@ -0,0 +1,50 @@
+/**
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {MDCFoundation} from '@material/base';
+import {strings} from './constants';
+
+export default class MDCGridListFoundation extends MDCFoundation {
+  static get strings() {
+    return strings;
+  }
+
+  static get defaultAdapter() {
+    return {
+      getOffsetWidth: () => /* number */ 0,
+      getTileOffsetWidthAtIndex: (/* index: number | null */) => /* number */ 0,
+      setTilesWidth: (/* value: number | null */) => {},
+      registerResizeHandler: (/* handler: EventListener */) => {},
+      deregisterResizeHandler: (/* handler: EventListener */) => {},
+    };
+  }
+  constructor(adapter) {
+    super(Object.assign(MDCGridListFoundation.defaultAdapter, adapter));
+    this.resizeHandler_ = () => this.alignCenter();
+  }
+  init() {
+    this.alignCenter();
+    this.adapter_.registerResizeHandler(this.resizeHandler_);
+  }
+  destroy() {
+    this.adapter_.deregisterResizeHandler(this.resizeHandler_);
+  }
+  alignCenter() {
+    const gridWidth = this.adapter_.getOffsetWidth();
+    const itemWidth = this.adapter_.getTileOffsetWidthAtIndex(0);
+    this.adapter_.setTilesWidth(itemWidth * Math.floor(gridWidth / itemWidth));
+  }
+}

packages/mdc-grid-list/index.js

@@ -0,0 +1,41 @@
+/**
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {MDCComponent} from '@material/base';
+
+import MDCGridListFoundation from './foundation';
+
+export {MDCGridListFoundation};
+
+export class MDCGridList extends MDCComponent {
+  static attachTo(root) {
+    return new MDCGridList(root);
+  }
+
+  getDefaultFoundation() {
+    return new MDCGridListFoundation({
+      getOffsetWidth: () => this.root_.offsetWidth,
+      getTileOffsetWidthAtIndex: (index) => {
+        return this.root_.querySelectorAll(MDCGridListFoundation.strings.TILE_SELECTOR)[index].offsetWidth;
+      },
+      setTilesWidth: (value) => {
+        this.root_.querySelector(MDCGridListFoundation.strings.TILES_SELECTOR).style.width = value + 'px';
+      },
+      registerResizeHandler: (handler) => window.addEventListener('resize', handler),
+      deregisterResizeHandler: (handler) => window.removeEventListener('resize', handler),
+    });
+  }
+}