@material/shape - npm Package Compare versions

Comparing version 0.39.0 to 0.40.0

package.json

 {
   "name": "@material/shape",
   "description": "Shape utilities for Material Components for the web",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "license": "MIT",
@@ -6,0 +6,0 @@ "keywords": [

README.md

@@ -19,4 +19,3 @@ <!--docs:
 
-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.
 
@@ -42,70 +41,85 @@ ## Design & API Documentation
 
-### 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
+
+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.
+
+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`.
+
+Please refer [Material Design guidelines: Shape](https://material.io/go/design-shape) to learn about how components are categorized.
+
+### 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.
+
+> Use `mdc-shape-resolve-percentage-radius` sass function to resolve percentage unit value to absolute radius value.
+
+### Sass Functions
+
+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-radius($radius, $masked-corners)` | Accepts radius number or list of 2-4 radius values and returns 4 value list with masked corners as mentioned in `$masked-corners`.
+
+### Additional Information
+
+#### Shapes for fixed height components
+
+Styles for applying shape to a fixed height component such as button looks like this:
+
+```scss
+@include mdc-shape-radius(mdc-shape-resolve-percentage-radius($mdc-button-height, $radius));
 ```
 
-> **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.
+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.
 
-### Styles
+#### Shapes for dynamic height components
 
+Styles for applying shapes to dynamic height component such as card looks like this:
+
 ```scss
-@import "@material/shape/mdc-shape"; // The base shape styles need to be imported once in the page or application
-@import "@material/shape/mixins";
-
-.my-shape-container {
-  @include mdc-shape-angled-corner(#fff, 10px);
-}
+@include mdc-shape-radius($radius);
 ```
 
-## Variants
+Where, `$radius` is absolute value only.
 
-### Outlined Angled Corners
+#### Shapes for components on specific corners
 
-Outlined angled corners involve the same markup and styles/imports as above, with the addition of including a mixin for
-outline:
+Styles for applying shapes for specific corners such as drawer 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(0 $radius $radius 0, $rtl-reflexive: true);
 ```
 
-## Style Customization
+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.
 
-### CSS Classes
+#### Component theming
 
-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.
+The styles for applying custom shape to button component instance looks like this:
 
-### Sass Mixins
+```scss
+@import "@material/button/mixins";
 
-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`.
+.my-custom-button {
+  @include mdc-button-shape-radius(50%);
+}
+```
 
-> **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.
+In this example, the above styles applies 50% (pill) shape to button. It can also be absolute value (e.g., `8px`);
 
-> **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.
+> You would indirectly use the Shape API through respective component's mixin which takes care of applying radius to applicable corners for all its variants.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Empty package

Supply chain risk

Package does not contain any code. It may be removed, is name squatting, or the result of a faulty package publish.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

13635

increased by18.03%

Number of lines in readme file

124

increased by12.73%

Worsened metrics

Number of package files

5

decreased by-16.67%

Lines of code

0

decreased by-100%

Number of medium supply chain risk alerts

2

increased by100%

No dependency changes