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

Comparing version 1.3.2 to 1.3.3

package.json

@@ -12,3 +12,3 @@ {
   "name": "@vaadin/vaadin-themable-mixin",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "main": "vaadin-themable-mixin.js",
@@ -33,3 +33,3 @@ "author": "Vaadin Ltd",
   "devDependencies": {
-    "@polymer/iron-test-helpers": "^3.0.0-pre.18",
+    "@polymer/iron-test-helpers": "^3.0.0",
     "@webcomponents/webcomponentsjs": "^2.0.0",
@@ -36,0 +36,0 @@ "wct-browser-legacy": "^1.0.1"

README.md

@@ -1,1 +0,376 @@
-# vaadin-themable-mixin
+# Table of Contents
+
+1. [Style Scopes](#style-scopes)
+1. [Adding Styles to Local Scope](#adding-styles-to-local-scope)
+1. [Stylable Shadow Parts](#stylable-shadow-parts)
+1. [Scoping Styles in a Theme Module](#scoping-styles-in-a-theme-module)
+1. [External resources](#external-resources)
+
+
+
+# Style Scopes
+
+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
+2. Styles affecting elements inside a [local scope](#local-style-scope-shadow-dom), i.e. styles inside a shadow DOM
+
+## Global Style Scope
+
+On a regular website, all elements are inside the same global style scope, and can be styled with global stylesheets (either `<link rel="stylesheet">` or `<style>` elements), using regular CSS selectors.
+
+#### Example: Global stylesheet
+![](https://www.dropbox.com/s/4nxndstebfjhu4z/vaadin-text-field-light-dom.png?raw=1)
+
+The only thing we can style using global styles is the whole `<vaadin-text-field>` element, but nothing inside it, like the *label* or the *input field*.
+
+For example, we could have the following styles in an imported stylesheet:
+
+```css
+vaadin-text-field {
+  border: 1px solid gray;
+}
+```
+
+And it would produce the following result:
+
+![](https://www.dropbox.com/s/4lkvmuudludhey4/vaadin-text-field-border.png?raw=1)
+
+## Local Style Scope (Shadow DOM)
+
+Styling Web Components (or custom elements to be more precise), which use shadow DOM, is different from styling regular websites.
+
+When a custom element has its own shadow DOM, the browser creates a new style scope for the elements that are placed inside the shadow DOM hierarchy, and CSS selectors in global stylesheets can’t affect those elements.
+
+The only CSS selectors that can affect the elements inside a shadow DOM need to be in a `<style>` element which is somewhere inside the shadow DOM hierarchy. At the same time, the styles inside a shadow DOM can’t affect elements outside the shadow DOM. The styles are placed in the “local style scope” of the shadow DOM.
+
+#### Example: Local style
+
+![](https://www.dropbox.com/s/dtl7ha54xnb7un1/vaadin-text-field-shadow-dom.png?raw=1)
+
+Only the `<style>` element highlighted in the inspector can affect the elements inside the `<vaadin-text-field>` element’s shadow DOM.
+
+For example, if we move the same styles from the previous example inside the `<style>` element inside the shadow DOM, the result is the same as without the style rules:
+
+```html
+#shadow-root (open)
+  <style>
+    vaadin-text-field {
+      border: 1px solid gray;
+    }
+  </style>
+```
+
+![](https://www.dropbox.com/s/66af3mw26grxdc3/vaadin-text-field.png?raw=1)
+
+That is because there are no `<vaadin-text-field>` elements inside the shadow DOM. If we want the same result as with the global stylesheet, we need to use the `:host` selector to match the element which is the “host” for this shadow DOM or style scope:
+
+```html
+#shadow-root (open)
+  <style>
+    :host {
+      border: 1px solid gray;
+    }
+  </style>
+```
+
+Then we get the same result as with the global stylesheet:
+
+![](https://www.dropbox.com/s/4lkvmuudludhey4/vaadin-text-field-border.png?raw=1)
+
+If we wanted to move the border to the actual text input element, we would need to inspect the shadow DOM hierarchy and see which selector would match that particular element. For `<vaadin-text-field>`, the correct selector would be `[part="input-field"]`:
+
+```html
+#shadow-root
+  <style>
+    [part="input-field"] {
+      border: 1px solid gray;
+    }
+  </style>
+```
+![](https://www.dropbox.com/s/9zo4te8pz74oe9q/vaadin-text-field-input-border.png?raw=1)
+
+
+# Adding Styles to Local Scope
+
+*Read the documentation about [Styles Scopes](https://github.com/vaadin/vaadin-themable-mixin/wiki/1.-Style-Scopes) before continuing.*
+
+
+## Property inheritance
+
+Currently, the only global CSS that can affect styles inside a shadow DOM’s local scope are properties that are inherited. Properties can be inherited by default, like `font-family` or all [CSS Custom Properties](https://www.w3.org/TR/css-variables/), or explicitly by the custom element, using the `inherit` property value.
+
+
+#### Example: using a custom property to affect the styles in a local scope
+```html
+<custom-style>
+  <style>
+    vaadin-combo-box {
+      --vaadin-combo-box-overlay-max-height: 50vh;
+    }
+  </style>
+</custom-style>
+```
+
+> Note: for cross-browser compatibility, [use the `<custom-style>` element](https://www.polymer-project.org/2.0/docs/devguide/style-shadow-dom#custom-style).
+
+> Note: check the API documentation of each element for the custom properties they expose. See the [API documentation for vaadin-combo-box](https://vaadin.com/elements/vaadin-combo-box/html-api/elements/Vaadin.ComboBoxElement#styling) for example.
+
+
+#### Example: explicitly inheriting a property value from the global scope into local scope
+```html
+#shadow-root
+  <style>
+    :host {
+      background-color: inherit;
+    }
+  </style
+```
+
+
+## Selector matching
+
+The web platform doesn’t currently provide a way to write selectors in the global scope that would match elements in a local scope (Oct 2017). There’s a [CSS spec proposal](http://tabatkins.github.io/specs/css-shadow-parts/) that will add that, but for now, we need to work around this limitation using proprietary solutions, like Vaadin’s [`ThemableMixin`](https://github.com/vaadin/vaadin-themable-mixin).
+
+
+## Theme modules
+
+Custom elements extending [`ThemableMixin`](https://github.com/vaadin/vaadin-themable-mixin) allow you to inject styles into their local scope by defining new [style modules](https://www.polymer-project.org/2.0/docs/devguide/style-shadow-dom#style-modules) in the global scope. You specify the targeted element using the `theme-for` attribute.
+
+```html
+<!-- Define a theme module (in index.html or in a separate HTML import) -->
+<dom-module id="my-theme-module" theme-for="my-element">
+  <template>
+    <style>
+      /* Styles which will be included in my-element local scope */
+    </style>
+  </template>
+</dom-module>
+```
+
+You can place these “theme module” definitions directly in your `index.html` or in a separate HTML import.
+
+> Note: a theme module needs to be imported and registered in the DOM before the element(s), which the module targets with the `theme-for` attribute, are registered and upgraded (before the first instantiation of the component).
+
+The `id` attribute of the theme module should be unique. You can also re-use an existing id if you want to override a previously defined/imported module.
+
+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:
+ - `"vaadin-button"`
+ - `"vaadin-overlay vaadin-date-picker-overlay"`
+ - `"vaadin-*"`
+
+
+### Theme modules are global
+
+When creating a theme module for an element, the styles in that theme module will apply to all instances of that element. The styles are always “global” in that sense and can’t be scoped by default with anything.
+
+
+
+# Stylable Shadow Parts
+
+*Read the documentation about [Styles Scopes](https://github.com/vaadin/vaadin-themable-mixin/wiki/1.-Style-Scopes) and [Adding Styles to Local Scope](https://github.com/vaadin/vaadin-themable-mixin/wiki/2.-Adding-Styles-to-Local-Scope) before continuing.*
+
+
+## Stylable elements
+
+### Host element
+
+The host element is the main element which has a shadow DOM, for example `<vaadin-text-field>`.
+
+### Named parts
+
+In addition to the host element, only certain elements inside a themable element (i.e. an element extending [`ThemableMixin`](https://github.com/vaadin/vaadin-themable-mixin)) should be styled.
+
+Other elements should be **considered as internal implementation details**, and you should not expect these elements to remain constant or be available in the future.
+
+The stylable elements have the `part` attribute, which gives the elements a descriptive name.
+
+#### Example: stylable parts of vaadin-text-field
+![](https://www.dropbox.com/s/g6l4xzujk8k7wda/vaadin-text-field-parts.png?raw=1)
+
+You can expect these part names to remain constant and rely on the hierarchy of these parts (i.e. the `value` part will always be contained within `input-field`).
+
+
+## How do I know what parts are available?
+
+The stylable parts of each Vaadin component are listed in their API documentation. See the [API documentation for vaadin-text-field](https://vaadin.com/components/vaadin-text-field/html-api/elements/Vaadin.TextFieldElement#styling) for example.
+
+
+## Supported selectors
+
+### :host
+
+The host element can be targeted using the `:host` selector.
+
+```html
+<dom-module id="my-button" theme-for="vaadin-button">
+  <template>
+    <style>
+      :host {
+        /* Styles for vaadin-button element */
+      }
+    </style>
+  </template>
+</dom-module>
+```
+
+
+### [part="..."]
+
+The stylable elements (marked with a `part` attribute) should only be targeted using the `[part="..."]` attribute selector.
+
+```html
+<dom-module id="my-text-field" theme-for="vaadin-text-field">
+  <template>
+    <style>
+      [part="input-field"] {
+        /* Styles for vaadin-text-field's input-field part */
+      }
+    </style>
+  </template>
+</dom-module>
+```
+
+### [part~="..."]
+
+Use `part~="..."` to match a part which might have multiple names, for example the cells inside a `<vaadin-grid>` which can have multiple names like `"cell"` and `"body-cell"`.
+
+You can use this kind of attribute selector in all cases, if you want to be safe. It will work for parts with only one name as well.
+
+```html
+<dom-module id="my-grid" theme-for="vaadin-grid">
+  <template>
+    <style>
+      [part~="cell"] {
+        /* Styles that affect all grid cells, including header, body and footer cells */
+      }
+
+      [part~="body-cell"] {
+        /* Styles that only affect all body cells */
+      }
+    </style>
+  </template>
+</dom-module>
+```
+
+**Do not rely on the element type** which a part applies to. For example, given `<input type="text" part="value">`, you should not rely on the information that the element is actually a native `<input>` element. This is considered as an internal implementation detail, and the element type could change in the future (while the part name stays the same), for example to `<div contenteditable="true" part="value">`.
+
+### State attributes
+
+Some custom elements expose some of their internal state as top-level attributes for styling purposes. You can find these attributes in the elements API documentation.
+
+For example, you can target styles for a disabled `<vaadin-button>` using the `disabled` attribute in combination with the `:host` selector:
+
+```html
+<dom-module id="my-button" theme-for="vaadin-button">
+  <template>
+    <style>
+      :host([disabled]) {
+        /* Styles for disabled vaadin-button element */
+      }
+    </style>
+  </template>
+</dom-module>
+```
+
+You can also target any named parts in a specific state of the host. For example, you can add a red border for the `input-field` part of a `<vaadin-text-field>` which is marked `invalid`:
+
+```html
+<dom-module id="my-text-field" theme-for="vaadin-text-field">
+  <template>
+    <style>
+      :host([invalid]) [part="input-field"] {
+        border: 1px solid red;
+      }
+    </style>
+  </template>
+</dom-module>
+```
+
+
+
+Similarly to the host element, the named parts can also expose state attributes for themselves, which can be used for styling. These are also listed in the element’s API documentation.
+
+For example, you can target a selected date in a `<vaadin-date-picker>`:
+
+```html
+<dom-module id="my-month-calendar-styles" theme-for="vaadin-month-calendar">
+  <template>
+    <style>
+     [part~="date"][selected] {
+       /* Styles for a selected date */
+     }
+   </style>
+  </template>
+</dom-module>
+```
+
+
+
+# Scoping Styles in a Theme Module
+
+The styles defined in a “theme module” affect all the instances of the element the module targets with the `theme-for` attribute.
+
+There are two ways to scope the styles that you write in a theme module.
+
+ 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**  
+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).
+
+#### Example: expose new custom properties
+```html
+<!-- Define the theme module (in index.html or in a separate HTML import) -->
+<dom-module id="my-text-field-theme" theme-for="vaadin-text-field">
+  <template>
+    <style>
+      [part="input-field"] {
+        background-color: var(--input-field-background-color, #fff);
+      }
+    </style>
+  </template>
+</dom-module>
+
+<!-- Use the new custom property -->
+<custom-style>
+  <style>
+    .some-part-of-my-app vaadin-text-field {
+     --input-field-background-color: #eee;
+    }
+  </style>
+</custom-style>
+
+<div class="some-part-of-my-app">
+  <vaadin-text-field></vaadin-text-field>
+</div>
+```
+
+#### Example: use scoping selectors
+
+```html
+<!-- Define the theme module (in index.html or in a separate HTML import) -->
+<dom-module id="my-text-field-theme" theme-for="vaadin-text-field">
+  <template>
+    <style>
+      :host(.special-field) [part="input-field"] {
+        background-color: #000;
+        color: #fff;
+        border: 2px solid #fff;
+        border-radius: 9px;
+        ...
+      }
+    </style>
+  </template>
+</dom-module>
+
+<!-- Use the new scoping selector anywhere in your app -->
+<div>
+  <vaadin-text-field class="special-field"></vaadin-text-field>
+</div>
+```
+
+
+
+# External resources
+- [Polymer styling documentation](https://www.polymer-project.org/2.0/docs/devguide/style-shadow-dom)

vaadin-themable-mixin.js

@@ -56,3 +56,3 @@ import { DomModule } from '@polymer/polymer/lib/elements/dom-module.js';
   static _includeStyle(moduleName, template) {
-    if (template && !template.content.querySelector(`style[include=${moduleName}]`)) {
+    if (template && !template.content.querySelector(`style[include="${moduleName}"]`)) {
       const styleEl = document.createElement('style');
@@ -59,0 +59,0 @@ styleEl.setAttribute('include', moduleName);

vaadin-theme-property-mixin.js

@@ -0,0 +0,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

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

28384

increased by92.81%

Number of lines in readme file

377

increased by18750%

No dependency changes