-
Notifications
You must be signed in to change notification settings - Fork 2.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(grid-list): Implement mdc-grid-list (#47)
- Loading branch information
1 parent
bfac404
commit 5756e9d
Showing
14 changed files
with
1,407 additions
and
0 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,266 @@ | ||
# MDC Grid list | ||
|
||
MDC Grid list provides a RTL-aware Material Design Grid list component adhering to the | ||
[Material Design Grid list spec](https://material.io/guidelines/components/grid-lists.html). | ||
Grid Lists are best suited for presenting homogeneous data, typically images. | ||
Each item in a grid list is called a **tile**. Tiles maintain consistent width, height, and padding | ||
across screen sizes. | ||
|
||
|
||
## 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="my-image.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="my-image.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: | ||
|
||
- Have 4px padding in between themselves | ||
- Have a 1x1 aspect ratio | ||
- Have a 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 | ||
[Using a div in place of an img](#using-a-div-in-place-of-an-img) section. | ||
|
||
|
||
### Set tile width | ||
|
||
The tile width is set to 200px by default. There are three ways that you can | ||
overwrite the default value for your grid list: | ||
|
||
1. Using CSS variables | ||
|
||
```css | ||
.mdc-grid-tile { | ||
--mdc-grid-list-tile-width: 300px; | ||
} | ||
``` | ||
|
||
2. Overwriting SCSS variable | ||
|
||
You can overwrite the scss variable by | ||
|
||
```scss | ||
@import "@material/grid-list/mdc-grid-list"; | ||
|
||
$mdc-grid-list-tile-width: 300px; | ||
|
||
``` | ||
|
||
3. Add own style to tile | ||
|
||
```html | ||
<style> | ||
.my-grid-list .mdc-grid-tile { | ||
width : 300px; | ||
} | ||
</style> | ||
<div class="mdc-grid-list my-grid-list"> | ||
<ul class="mdc-grid-list__tiles"> | ||
<li class="mdc-grid-tile"></li> | ||
... | ||
</ul> | ||
</div> | ||
``` | ||
|
||
### Change tile padding | ||
|
||
Grid list tiles can 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> | ||
``` | ||
|
||
### Image only tile | ||
|
||
Grid lists support image only tile. You can remove `mdc-grid-tile__secondary` | ||
and create a image only grid list. | ||
|
||
```html | ||
<div class="mdc-grid-list mdc-grid-list--tile-gutter-1"> | ||
<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> | ||
</li> | ||
</ul> | ||
</div> | ||
``` | ||
|
||
### Header caption | ||
|
||
Grid lists support header caption. You can change the footer caption to be a | ||
header caption by adding `mdc-grid-list--header-caption` modifier. | ||
|
||
```html | ||
<div class="mdc-grid-list mdc-grid-list--header-caption"> | ||
<ul class="mdc-grid-list__tiles"> | ||
... | ||
</ul> | ||
</div> | ||
``` | ||
|
||
### Add support text to secondary content (caption) | ||
|
||
Grid lists support a one-line caption by default. You can add an additional line of support | ||
text if needed by adding the `mdc-grid-list--twoline-caption` modifier and additional | ||
markup | ||
|
||
```html | ||
<div class="mdc-grid-list mdc-grid-list--twoline-caption"> | ||
<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="my-image.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 an icon to a 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"> | ||
<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="my-image.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> | ||
``` | ||
|
||
### Change aspect ratio of tile | ||
|
||
Grid list tiles support all material guideline recommended aspect ratio: | ||
|
||
- 1x1 | ||
- 16x9 | ||
- 2x3 | ||
- 3x2 | ||
- 4x3 | ||
- 3x4 | ||
|
||
You can use the modifier class `mdc-grid-list--tile-aspect-$ASPECT_RATIO` to apply these aspect | ||
ratios to your grid list. Simply replace `$ASPECT_RATIO` with any of the predefined ratios. | ||
|
||
```html | ||
<!-- Example of 16x9 tile --> | ||
<div class="mdc-grid-list mdc-grid-list--tile-aspect-16x9"> | ||
<ul class="mdc-grid-list__tiles"> | ||
... | ||
</ul> | ||
</div> | ||
``` | ||
|
||
As pointed out in the previous section, 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 | ||
[Using a div in place of an img](#using-a-div-in-place-of-an-img) section. | ||
|
||
### Using a div in place of an 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 | ||
<style> | ||
.my-tile-image { | ||
background-image: url(my-image.jpg); | ||
} | ||
</style> | ||
<div class="mdc-grid-list"> | ||
<ul class="mdc-grid-list__tiles"> | ||
<li class="mdc-grid-tile"> | ||
<div class="mdc-grid-tile__primary"> | ||
<div class="mdc-grid-tile__primary-content my-tile-image"></div> | ||
</div> | ||
<span class="mdc-grid-tile__secondary"> | ||
<span class="mdc-grid-tile__title">Title</span> | ||
</span> | ||
</li> | ||
</ul> | ||
</div> | ||
``` | ||
|
||
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, have a `dir="rtl"` attribute. | ||
|
||
|
||
### Theme | ||
|
||
`mdc-grid-list` supports theming. `mdc-grid-tile__primary` uses the theme's background | ||
color for its background color. `mdc-grid-tile__secondary` uses the theme's primary | ||
color for it's background color, and the theme's `text-primary-on-primary` color for its text color. | ||
|
||
### 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 `mdc-grid-list` offsetWidth. | | ||
| `getTileOffsetWidthAtIndex(index: number) => number` | Get offsetWidth of `mdc-grid-tile` at specified index. | | ||
| `setTilesWidth(value: number) => void` | Set `mdc-grid-list__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. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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', | ||
}; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 */) => /* number */ 0, | ||
setTilesWidth: (/* value: number */) => {}, | ||
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)); | ||
} | ||
} |
Oops, something went wrong.