@vaadin/vaadin-themable-mixin - npm Package Compare versions

Comparing version 1.4.4 to 1.5.0-alpha1

package.json

@@ -12,3 +12,3 @@ {
   "name": "@vaadin/vaadin-themable-mixin",
-  "version": "1.4.4",
+  "version": "1.5.0-alpha1",
   "main": "vaadin-themable-mixin.js",
@@ -15,0 +15,0 @@ "author": "Vaadin Ltd",

README.md

@@ -7,2 +7,3 @@ # Table of Contents
 1. [Scoping Styles in a Theme Module](#scoping-styles-in-a-theme-module)
+1. [Theme Attribute and Subcomponents](#theme-attribute-and-subcomponents)
 1. [External resources](#external-resources)
@@ -14,3 +15,3 @@
 
-With the addition of Shadow DOM, styles on a webpage can be divided into two groups: 
+With the addition of Shadow DOM, styles on a webpage can be divided into two groups:
 1. Styles affecting elements in the [global scope](#global-style-scope), i.e. traditional styles
@@ -158,5 +159,63 @@ 2. Styles affecting elements inside a [local scope](#local-style-scope-shadow-dom), i.e. styles inside a shadow DOM
 
+> Note: The theme modules are included in an order that enables custom modules to override styles defined by the Vaadin's built-in modules. The built-in theme modules use id's prefixed with `vaadin-`, `lumo-` and `material-` so avoid using these prefixes in your custom theme module `id`'s.
+
 The value of the `theme-for` attribute can be a space-separated list of element names, and can contain wildcard element names as well.</p>
 
-#### Examples of valid `theme-for` attribute values:
+### Styling in JavaScript
+
+When working with ES modules/JavaScript generally, constructing theme modules programmatically might end up producing boilterplace code to the application. Where possible, you should prefer the `registerStyles` utility which provides a convenient abstraction over the declarative API.
+
+Importing the helper (as an HTMLImport)
+```html
+<link rel="import" href="../register-styles.html">
+```
+
+Importing the helper (as an ES module)
+```js
+import { registerStyles, css } from '@vaadin/vaadin-themable-mixin/register-styles.js';
+```
+
+Use the `registerStyles(themeFor, styles)` function to register CSS styles to be included in a component's local scope. The `themeFor` parameter is of type string and is used to identify the component type the styles are applied to. It works the same as with style modules. The `styles` accepts an object or an array of objects built as template literals tagged with `css`, containing CSS style rules to be included in the targeted component's local style.
+
+Using registerStyles imported as an HTMLImport
+```js
+Vaadin.registerStyles('my-element', Vaadin.css`
+  /* Styles which will be included in my-element local scope */
+`);
+```
+Using registerStyles imported as an ES module
+```js
+registerStyles('my-element', css`
+  /* Styles which will be included in my-element local scope */
+`);
+```
+
+> Note: Use `unsafeCSS` to wrap a trusted CSS value for interpolation in a css tagged template literal or as a separate item for the `styles` array.
+
+```js
+Vaadin.registerStyles('my-element', [Vaadin.css`
+  /* Styles which will be included in my-element local scope */
+`, Vaadin.unsafeCSS(trustedCSSValue)]);
+```
+
+> Note: If you need to include styles defined as Polymer style modules with id, you can still pass the module ids as `include` array of the third `options` parameter to the function. Consider this API deprecated.
+
+```js
+// Use of "include" is deprecated!
+Vaadin.registerStyles('my-element', Vaadin.css`
+  /* Styles which will be included in my-element local scope */
+`, {include: ['my-style-module']});
+```
+
+> Note: If you need to get styles defined with `registerStyles` registered as a Polymer style module with a pre-defined id, you can still do so by passing an object with `moduleId` as the third parameter for the function. Consider this API deprecated.
+
+```js
+// Use of "moduleId" is deprecated!
+Vaadin.registerStyles(undefined, Vaadin.css`
+  /* Styles which will be included in the style module */
+`, {moduleId: 'my-extended-style-module'});
+```
+
+
+#### Examples of valid `theme-for` values:
  - `"vaadin-button"`
@@ -320,5 +379,5 @@ - `"vaadin-overlay vaadin-date-picker-overlay"`
 
- 1. **Expose new custom properties**  
+ 1. **Expose new custom properties**
 This is the recommended first option for simple situations. If you end up exposing more than a handful of properties, you should consider the second option.
- 2. **Use scoping selectors**  
+ 2. **Use scoping selectors**
 This approach is used by the built-in variations in Vaadin themes (Valo and Material), i.e. `theme` attribute. The downside of this approach is that you end up adding the selectors and properties to all instances, even though only some instances will need those styles (they won’t apply unless the scoping selector is used on the host element).
@@ -379,3 +438,105 @@
 
+# Theme Attribute and Subcomponents
+
+Sometimes components using `VaadinThemableMixin` are contained in Shadow DOM of other components. In such a case, we propagate the `theme` attribute of the host web component to subcomponents.
+
+For example, Vaadin components using `<vaadin-text-field>` is used as an internal input field subcomponent, including `<vaadin-combo-box>`, `<vaadin-date-picker>`, and so on, propagate the `theme` attribute. You can use theme variants defined for `<vaadin-text-field>` in, e. g., `<vaadin-combo-box>`, and this will affect the internal subcomponent:
+
+#### Example: using `small` Lumo theme variant on `<vaadin-combo-box>`
+
+```html
+<vaadin-combo-box theme="small"></vaadin-combo-box>
+```
+
+If you can define a custom theme variant for `<vaadin-text-field>`, you can use it with other Vaadin components that have an internal `<vaadin-text-field>` too:
+
+#### Example: using a custom text field `theme` variant with `<vaadin-combo-box>`
+
+```html
+<!-- Define the theme module (in index.html or in a separate HTML import) -->
+<dom-module id="special-field-theme" theme-for="vaadin-text-field">
+  <template>
+    <style>
+      :host([theme~="special-field"]) [part="input-field"] {
+        background-color: #000;
+        color: #fff;
+        border: 2px solid #fff;
+        border-radius: 9px;
+        ...
+      }
+    </style>
+  </template>
+</dom-module>
+
+<!-- Apply the theme attribute to <vaadin-combo-box> -->
+<vaadin-combo-box theme="special-field"></vaadin-combo-box>
+```
+
+### How to propagate the `theme` attribute in your components
+
+With your Polymer-based web components you can use `VaadinThemePropertyMixin` to propagate the `theme` to subcomponents. The mixin provides the `theme` property that you can bind to descendant attributes.
+
+#### Example: a Polymer-based element that propagates the `theme` to Vaadin subcomponents:
+
+```js
+class MyFieldElement extends Vaadin.ThemePropertyMixin(Polymer.Element) {
+  static get is() { return 'my-field'; }
+
+  static get template() {
+    return html`<vaadin-text-field theme$="[[theme]]"></vaadin-text-field>`;
+  }
+}
+
+CustomElements.define(MyFieldElement.is, MyFieldElement);
+```
+
+```html
+<my-field theme="small"></my-field>
+```
+
+## List of Vaadin components that propagate `theme` to subcomponents
+
+- `<vaadin-context-menu>`’s theme propagates to internal:
+  - `<vaadin-context-menu-overlay>`
+- `<vaadin-time-picker>`:
+  - `<vaadin-combo-box-light>`
+  - `<vaadin-time-picker-text-field>`
+- `<vaadin-select>`:
+  - `<vaadin-text-field>`
+  - `<vaadin-select-overlay>`
+- `<vaadin-dialog>`:
+  - `<vaadin-dialog-overlay>`
+- `<vaadin-combo-box>`:
+  - `<vaadin-text-field>`
+  - `<vaadin-combo-box-dropdown-wrapper>`
+  - `<vaadin-combo-box-dropdown>`
+  - `<vaadin-combo-box-item>`
+- `<vaadin-combo-box-light>`:
+  - `<vaadin-combo-box-dropdown-wrapper>`
+  - `<vaadin-combo-box-dropdown>`
+  - `<vaadin-combo-box-item>`
+- `<vaadin-crud>`:
+  - `<vaadin-crud-grid>`
+  - `<vaadin-dialog-layout>`
+  - `<vaadin-dialog>`
+  - `<vaadin-confirm-dialog>`
+- `<vaadin-date-picker>`:
+  - `<vaadin-text-field>`
+  - `<vaadin-date-picker-overlay>`
+  - `<vaadin-date-picker-overlay-content>`
+  - `<vaadin-month-calendar>`
+- `<vaadin-date-picker-light>`:
+  - `<vaadin-date-picker-overlay>`
+  - `<vaadin-date-picker-overlay-content>`
+  - `<vaadin-month-calendar>`
+- `<vaadin-notification>`:
+  - `<vaadin-notification-card>`
+- `<vaadin-login-overlay>`:
+  - `<vaadin-login-overlay-wrapper>`
+- `<vaadin-login-form>`:
+  - `<vaadin-login-form-wrapper>`
+
+
+
 # External resources
 - [Polymer styling documentation](https://www.polymer-project.org/2.0/docs/devguide/style-shadow-dom)

vaadin-theme-property-mixin.js

@@ -9,4 +9,15 @@ /**
        * Helper property with theme attribute value facilitating propagation
-       * in shadow DOM. Allows using `theme$="[[theme]]"` in the template.
+       * in shadow DOM.
        *
+       * Enables the component implementation to propagate the `theme`
+       * attribute value to the subcomponents in Shadow DOM by binding
+       * the subcomponent’s "theme" attribute to the `theme` property of
+       * the host.
+       *
+       * **NOTE:** Extending the mixin only provides the property for binding,
+       * and does not make the propagation alone.
+       *
+       * See [Theme Attribute and Subcomponents](https://github.com/vaadin/vaadin-themable-mixin/wiki/5.-Theme-Attribute-and-Subcomponents).
+       * page for more information.
+       *
        * @protected
@@ -13,0 +24,0 @@ */

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

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

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

Improved metrics

Total package byte prevSize

36246

increased by23.47%

Lines of code

108

increased by11.34%

Number of lines in readme file

538

increased by42.71%

Worsened metrics

Number of low quality alerts

1

increased byInfinity%

No dependency changes