diff --git a/demos/image-list.html b/demos/image-list.html new file mode 100644 index 00000000000..2fd980cbf02 --- /dev/null +++ b/demos/image-list.html @@ -0,0 +1,326 @@ + + + + + + Image List - Material Components Catalog + + + + + + + + + +
+
+
+ + Image List +
+
+
+
+
+
+ +
+ +
+
+
+ +
+ + + +
+
+
+ +
+ +

Standard Image List

+
+
+
+ +
+
+
+
+
+ +
+
+
+ +
+
+
+
+
+ +
+
+
+ +
+
+
+
+
+ +
+
+ +
+
+ + + + + diff --git a/demos/image-list.scss b/demos/image-list.scss new file mode 100644 index 00000000000..b2830b51484 --- /dev/null +++ b/demos/image-list.scss @@ -0,0 +1,45 @@ +// +// Copyright 2018 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 "./common"; +@import "../packages/mdc-checkbox/mdc-checkbox"; +@import "../packages/mdc-form-field/mdc-form-field"; +@import "../packages/mdc-image-list/mdc-image-list"; +@import "../packages/mdc-radio/mdc-radio"; + +.mdc-image-list.hero-image-list { + @include mdc-image-list-standard-columns(5); + width: 300px; +} + +.hero-image-list .mdc-image-list__image { + background-color: #000; +} + +.mdc-image-list.standard-image-list { + @include mdc-image-list-standard-columns(5); + max-width: 1000px; +} + +.hide-supporting .mdc-image-list__supporting { + display: none; +} + +@media (max-width: 599px) { + .mdc-image-list.standard-image-list { + @include mdc-image-list-standard-columns(3); + } +} diff --git a/demos/index.html b/demos/index.html index 0bf64e1c46a..dc3b2706196 100644 --- a/demos/index.html +++ b/demos/index.html @@ -111,6 +111,14 @@ + + + + Image list + Displays a collection of images in a repeated pattern + + + diff --git a/package.json b/package.json index 7b14c3a1313..70de0440818 100644 --- a/package.json +++ b/package.json @@ -134,6 +134,7 @@ "form-field", "grid-list", "icon-toggle", + "image-list", "layout-grid", "line-ripple", "linear-progress", diff --git a/packages/material-components-web/material-components-web.scss b/packages/material-components-web/material-components-web.scss index 65f2a08f5da..e9176a6d93d 100644 --- a/packages/material-components-web/material-components-web.scss +++ b/packages/material-components-web/material-components-web.scss @@ -26,6 +26,7 @@ @import "@material/form-field/mdc-form-field"; @import "@material/grid-list/mdc-grid-list"; @import "@material/icon-toggle/mdc-icon-toggle"; +@import "@material/image-list/mdc-image-list"; @import "@material/layout-grid/mdc-layout-grid"; @import "@material/line-ripple/mdc-line-ripple"; @import "@material/linear-progress/mdc-linear-progress"; diff --git a/packages/material-components-web/package.json b/packages/material-components-web/package.json index 97a6cfdc2e7..ef60e8e2ae4 100644 --- a/packages/material-components-web/package.json +++ b/packages/material-components-web/package.json @@ -28,6 +28,7 @@ "@material/form-field": "^0.32.0", "@material/grid-list": "^0.30.0", "@material/icon-toggle": "^0.32.0", + "@material/image-list": "^0.0.0", "@material/layout-grid": "^0.24.0", "@material/line-ripple": "^0.32.0", "@material/linear-progress": "^0.30.0", diff --git a/packages/mdc-image-list/README.md b/packages/mdc-image-list/README.md new file mode 100644 index 00000000000..4033f41b3f5 --- /dev/null +++ b/packages/mdc-image-list/README.md @@ -0,0 +1,139 @@ + + +# Image List + + + +MDC Image List provides a RTL-aware Material Design image list component, representing an evolution of the +[Material Design Grid List spec](https://material.io/guidelines/components/grid-lists.html). +An Image List consists of several items, each containing an image and optionally supporting content (i.e. a text label). + +## Design & API Documentation + + + +## Installation + +``` +npm install --save @material/image-list +``` + +## Basic Usage + +### HTML Structure + +The HTML structure for a Standard Image List is as follows: + +```html + +``` + +### Styles + +The structure above would be combined with an invocation of the `mdc-image-list-standard-columns` mixin, to establish how many +columns should be displayed per line: + +```scss +.my-image-list { + @include mdc-image-list-standard-columns(5); +} +``` + +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. + +## Style Customization + +### CSS Classes + +CSS Class | Description +--- | --- +`mdc-image-list` | Mandatory. Indicates the root Image List element. +`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. +`mdc-image-list__image` | Mandatory. Indicates the image element in each item. +`mdc-image-list__supporting` | Optional. Indicates the area within each item containing the supporting text label, if the Image List contains text labels. +`mdc-image-list__label` | Optional. Indicates the text label in each item, if the Image List contains text labels. + +### Sass Mixins + +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-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. + +### 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 +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: + +```scss +.my-image-list { + @include mdc-image-list-standard-columns(5); + max-width: 960px; +} +``` + +> **Note:** Remember that any specified width will apply to the _entire_ list, so be sure to account for the gutters +as well. + +#### Changing number of columns across breakpoints + +Presenting a different number of columns for different viewport sizes is straightforward, since the only thing that +needs to be changed are styles: + +```scss +.my-image-list { + @include mdc-image-list-standard-columns(5); +} + +@media (max-width: 599px) { + .my-image-list { + @include mdc-image-list-standard-columns(3); + } +} +``` + +#### Using div in place of img to enforce 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. + +> **Note:** Ensuring your images are appropriately-sized prior to serving them to browsers is the most efficient and +ideal approach to using MDC Image List. The `div` alternative is provided as a convenience. If you use this alternative, +make sure to also include the `mdc-image-list__image-aspect-container` element around each item's image. diff --git a/packages/mdc-image-list/_mixins.scss b/packages/mdc-image-list/_mixins.scss new file mode 100644 index 00000000000..75811730d11 --- /dev/null +++ b/packages/mdc-image-list/_mixins.scss @@ -0,0 +1,33 @@ +// Copyright 2018 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 "./variables"; + +@mixin mdc-image-list-aspect($width-height-ratio) { + .mdc-image-list__image-aspect-container { + padding-bottom: calc(100% / #{$width-height-ratio}); + } +} + +// Standard Image List + +@mixin mdc-image-list-standard-columns($column-count, $gutter-size: $mdc-image-list-standard-gutter-size) { + // This uses margin rather than padding to facilitate properly positioning the supporting content element when + // --with-text-protection is used. + .mdc-image-list__item { + // Subtract extra fraction from each item's width to ensure correct wrapping in IE and Edge which round differently + width: calc(100% / #{$column-count} - #{$gutter-size + 1 / $column-count}); + margin: $gutter-size / 2; + } +} diff --git a/packages/mdc-image-list/_variables.scss b/packages/mdc-image-list/_variables.scss new file mode 100644 index 00000000000..1b3b50ba789 --- /dev/null +++ b/packages/mdc-image-list/_variables.scss @@ -0,0 +1,19 @@ +// Copyright 2018 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. + +$mdc-image-list-standard-gutter-size: 4px; +$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; +$mdc-image-list-text-protection-horizontal-padding: 16px; diff --git a/packages/mdc-image-list/mdc-image-list.scss b/packages/mdc-image-list/mdc-image-list.scss new file mode 100644 index 00000000000..d74e89b9d00 --- /dev/null +++ b/packages/mdc-image-list/mdc-image-list.scss @@ -0,0 +1,87 @@ +// Copyright 2018 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 "./mixins"; +@import "./variables"; +@import "@material/theme/mixins"; +@import "@material/typography/mixins"; + +.mdc-image-list { + display: flex; + flex-wrap: wrap; + // Margin and padding are set to override default user agent styles for lists, and also to center the Image List + margin: 0 auto; + padding: 0; +} + +.mdc-image-list__item, +.mdc-image-list__image-aspect-container { + // Supports absolute positioning of protected supporting content for item, and image for image-aspect-container + position: relative; + box-sizing: border-box; +} + +.mdc-image-list__item { + list-style-type: none; +} + +.mdc-image-list__image { + width: 100%; +} + +// Descendant selector allows image-aspect-container to be optional in DOM structure +.mdc-image-list__image-aspect-container .mdc-image-list__image { + position: absolute; + top: 0; + right: 0; + bottom: 0; + left: 0; + height: 100%; + // Background styles to support div instead of img + background-repeat: no-repeat; + background-position: center; + background-size: cover; +} + +@at-root { + @include mdc-image-list-aspect(1); +} + +.mdc-image-list__supporting { + @include mdc-theme-prop(color, text-primary-on-background); + + display: flex; + align-items: center; + justify-content: space-between; + box-sizing: border-box; + padding: 8px 0; + line-height: $mdc-image-list-icon-size; +} + +.mdc-image-list__label { + @include mdc-typography(subheading2); + @include mdc-typography-overflow-ellipsis; +} + +// Modifier for labels/icons with text protection, overlaying images. + +.mdc-image-list--with-text-protection .mdc-image-list__supporting { + position: absolute; + bottom: 0; + width: 100%; + height: $mdc-image-list-text-protection-height; + padding: 0 $mdc-image-list-text-protection-horizontal-padding; + background: $mdc-image-list-text-protection-background-color; + color: #fff; +} diff --git a/packages/mdc-image-list/package.json b/packages/mdc-image-list/package.json new file mode 100644 index 00000000000..d8cee71369c --- /dev/null +++ b/packages/mdc-image-list/package.json @@ -0,0 +1,22 @@ +{ + "name": "@material/image-list", + "version": "0.0.0", + "description": "The Material Components for the web image list component", + "license": "Apache-2.0", + "repository": { + "type": "git", + "url": "https://github.com/material-components/material-components-web.git" + }, + "keywords": [ + "material components", + "material design", + "image list" + ], + "dependencies": { + "@material/theme": "^0.30.0", + "@material/typography": "^0.28.0" + }, + "publishConfig": { + "access": "public" + } +} diff --git a/scripts/webpack/css-bundle-factory.js b/scripts/webpack/css-bundle-factory.js index b7a156896eb..04ec70bb7dc 100644 --- a/scripts/webpack/css-bundle-factory.js +++ b/scripts/webpack/css-bundle-factory.js @@ -147,6 +147,7 @@ module.exports = class { 'mdc.form-field': getAbsolutePath('/packages/mdc-form-field/mdc-form-field.scss'), 'mdc.grid-list': getAbsolutePath('/packages/mdc-grid-list/mdc-grid-list.scss'), 'mdc.icon-toggle': getAbsolutePath('/packages/mdc-icon-toggle/mdc-icon-toggle.scss'), + 'mdc.image-list': getAbsolutePath('/packages/mdc-image-list/mdc-image-list.scss'), 'mdc.layout-grid': getAbsolutePath('/packages/mdc-layout-grid/mdc-layout-grid.scss'), 'mdc.line-ripple': getAbsolutePath('/packages/mdc-line-ripple/mdc-line-ripple.scss'), 'mdc.linear-progress': getAbsolutePath('/packages/mdc-linear-progress/mdc-linear-progress.scss'), diff --git a/test/build/goldens/build-config-dev-env.golden.json b/test/build/goldens/build-config-dev-env.golden.json index e3b021d47a6..9ca47f7ed1b 100644 --- a/test/build/goldens/build-config-dev-env.golden.json +++ b/test/build/goldens/build-config-dev-env.golden.json @@ -50,6 +50,7 @@ "fab": "/demos/fab.scss", "grid-list": "/demos/grid-list.scss", "icon-toggle": "/demos/icon-toggle.scss", + "image-list": "/demos/image-list.scss", "index": "/demos/index.scss", "layout-grid": "/demos/layout-grid.scss", "linear-progress": "/demos/linear-progress.scss", diff --git a/test/build/goldens/build-config-no-env.golden.json b/test/build/goldens/build-config-no-env.golden.json index d19266b9192..9be4a006fc8 100644 --- a/test/build/goldens/build-config-no-env.golden.json +++ b/test/build/goldens/build-config-no-env.golden.json @@ -175,6 +175,7 @@ "mdc.form-field": "/packages/mdc-form-field/mdc-form-field.scss", "mdc.grid-list": "/packages/mdc-grid-list/mdc-grid-list.scss", "mdc.icon-toggle": "/packages/mdc-icon-toggle/mdc-icon-toggle.scss", + "mdc.image-list": "/packages/mdc-image-list/mdc-image-list.scss", "mdc.layout-grid": "/packages/mdc-layout-grid/mdc-layout-grid.scss", "mdc.line-ripple": "/packages/mdc-line-ripple/mdc-line-ripple.scss", "mdc.linear-progress": "/packages/mdc-linear-progress/mdc-linear-progress.scss", diff --git a/test/build/goldens/build-config-prod-env.golden.json b/test/build/goldens/build-config-prod-env.golden.json index 8a6a01cbc80..9ddd5025a48 100644 --- a/test/build/goldens/build-config-prod-env.golden.json +++ b/test/build/goldens/build-config-prod-env.golden.json @@ -175,6 +175,7 @@ "mdc.form-field": "/packages/mdc-form-field/mdc-form-field.scss", "mdc.grid-list": "/packages/mdc-grid-list/mdc-grid-list.scss", "mdc.icon-toggle": "/packages/mdc-icon-toggle/mdc-icon-toggle.scss", + "mdc.image-list": "/packages/mdc-image-list/mdc-image-list.scss", "mdc.layout-grid": "/packages/mdc-layout-grid/mdc-layout-grid.scss", "mdc.line-ripple": "/packages/mdc-line-ripple/mdc-line-ripple.scss", "mdc.linear-progress": "/packages/mdc-linear-progress/mdc-linear-progress.scss",