feat(shape): Added new Shape APIs

.travis.yml

@@ -13,6 +13,7 @@ branches:
   # This prevents excessive resource usage and CI slowness.
   only:
     - master
+    - feat/shape
 
 before_install:
   # Source the scripts to export their env vars. See https://superuser.com/a/176788/62792

packages/mdc-shape/README.md

@@ -16,8 +16,7 @@ path: /catalog/shape/
 
 Shapes direct attention, identify components, communicate state, and express brand.
 
-Many MDC Web components include direct support for rounded corners; this package provides additional support for
-applying angled corners to unelevated surfaces.
+> Currently shape system for web only supports rounded corners.
 
 ## Design & API Documentation
 
@@ -38,72 +37,71 @@ npm install @material/shape
 
 ## Basic Usage
 
-### HTML
+### Styles
 
-The markup for angled corners involves a container element, and one element per angled corner.
+```scss
+@import "@material/shape/mixins";
+@import "@material/shape/functions";
+```
 
-The following example demonstrates angled corners applied to a MDC Button, but this technique may be applied to any
-unelevated component.
+## Style Customization
 
-```html
-<div class="mdc-shape-container my-shape-container">
-  <button class="mdc-button mdc-button--unelevated">Button</button>
-  <div class="mdc-shape-container__corner mdc-shape-container__corner--top-left"></div>
-  <div class="mdc-shape-container__corner mdc-shape-container__corner--top-right"></div>
-  <div class="mdc-shape-container__corner mdc-shape-container__corner--bottom-right"></div>
-  <div class="mdc-shape-container__corner mdc-shape-container__corner--bottom-left"></div>
-</div>
-```
+### Sass Variables
 
-> **Note:** Each angled corner should have its own `<div>` element. Any corner that will not be cut (i.e. its size is 0)
-> does not need a dedicated element.
+Components are categorized as small, medium and large in shape system. Overriding below sass variables applies shape (rounded) to respective categories. For example, overriding `$mdc-shape-medium-radius` variable would apply shape to all components that belong to medium category.
 
-### Styles
+Variable | Description
+--- | ---
+`$mdc-shape-small-surface-radius` | Rounded shape radius size for small surface components. Default value `4px`.
+`$mdc-shape-medium-surface-radius` | Rounded shape radius size for medium surface components. Default value `8px`.
+`$mdc-shape-large-surface-radius` | Rounded shape radius size for large surface components. Default value `0`.
 
-```scss
-@import "@material/shape/mdc-shape"; // The base shape styles need to be imported once in the page or application
-@import "@material/shape/mixins";
+Please refer [Material Design guidelines: Shape](https://material.io/go/design-shape) to learn about how components are categorized.
 
-.my-shape-container {
-  @include mdc-shape-angled-corner(#fff, 10px);
-}
-```
+### Sass Mixins
+
+Mixin | Description
+--- | ---
+`mdc-shape-radius($radius, $rtl-reflexive)` | Shape API used by all other components to apply radius to appropriate corners. `$radius` can be single value or list of up to 4 radius corner values. Set `$rtl-reflexive` to true to flip the radius in RTL case, `false` by default.
 
-## Variants
+> Use `mdc-shape-resolve-percentage-radius` sass function to resolve percentage unit value to absolute radius value.
 
-### Outlined Angled Corners
+### Sass Functions
 
-Outlined angled corners involve the same markup and styles/imports as above, with the addition of including a mixin for
-outline:
+Function | Description
+--- | ---
+`mdc-shape-flip-radius($radius)` | Flips the radius values in RTL context. $radius is list of 2-4 corner values.
+`mdc-shape-resolve-percentage-radius($component-height, $radius)` | Calculates the absolute radius value based on its component height. Use this for fixed height components only.
+`mdc-shape-mask-top-radius($radius)` | Accepts radius number or list of 2 radius values and returns 4 value list with top-left value, top-right value, bottom-right 0, bottom-left 0. Throws error when length of radius is more than 2.
+
+### Additional Information
+
+#### Shapes for fixed height components
+
+Styles for applying shape to a fixed height component such as button looks like this:
 
 ```scss
-.my-shape-container {
-  @include mdc-shape-angled-corner(#fff, 10px);
-  @include mdc-shape-angled-corner-outline(2px, blue);
-}
+@include mdc-shape-radius(mdc-shape-resolve-percentage-radius($mdc-button-height, $radius));
 ```
 
-## Style Customization
+Where, `$mdc-button-height` is the height of standard button and `$radius` is the size of shape. `mdc-shape-resolve-percentage-radius` function is used to resolve percentage unit value to absolute `$radius` value based on component height.
 
-### CSS Classes
+#### Shapes for dynamic height components
 
-CSS Class | Description
---- | ---
-`mdc-shape-container` | Mandatory. Parent element containing the component to be masked.
-`mdc-shape-container__corner` | Mandatory. Element for masking a specific corner; there may be up to 4.
-`mdc-shape-container__corner--bottom-left` | Element for masking the bottom left corner of the component.
-`mdc-shape-container__corner--bottom-right` | Element for masking the bottom right corner of the component.
-`mdc-shape-container__corner--top-left` | Element for masking the top left corner of the component.
-`mdc-shape-container__corner--top-right` | Element for masking the top right corner of the component.
+Styles for applying shapes to dynamic height component such as card looks like this:
 
-### Sass Mixins
+```scss
+@include mdc-shape-radius($radius);
+```
 
-Mixin | Description
---- | ---
-`mdc-shape-angled-corner($background-color, $top-left-size[, $top-right-size, $bottom-right-size, $bottom-left-size])` | Applies styles for masking angled corners, using the given background color and corner sizes. If fewer than 4 corner sizes are specified, the mixin automatically determines the other corners similarly to CSS `border-radius`.
-`mdc-shape-angled-corner-background($background-color)` | Sets the background color used to mask angled corners. Useful for styling a subset of components in a section with a different background color.
-`mdc-shape-angled-corner-outline($outline-width, $outline-color[, $outline-style])` | Applies outline styles to angled corners. `$outline-style` defaults to `solid`.
+Where, `$radius` is absolute value only.
+
+#### Shapes for components on specific corners
 
-> **Note:** When mentioned above, "background color" specifically refers to the color of the background behind the surface (_not_ the fill color of the surface). These mixins operate by masking the corners of the surface to match the background.
+Styles for applying shapes for specific corners such as drawer looks like this:
+
+```scss
+@include mdc-shape-radius((0, $radius, $radius, 0), $rtl-reflexive: true);
+```
 
-> **Note:** These mixins should be included in the context of the container element (or an ancestor) in order to apply styles to the corner elements.
+Where, only top-right & bottom-right corners are customizable and it automatically flips radius values based on RTL context when `$rtl-reflexive` is set to true.