From 5be186c053d5ae3f430abb6cebf8a1590b2a166b Mon Sep 17 00:00:00 2001 From: Kate Jeffreys Date: Tue, 20 Feb 2018 13:12:52 -0800 Subject: [PATCH 1/8] update shadow dom docs for p3 - first pass --- app/3.0/docs/devguide/shadow-dom.md | 49 ++++++++++++++++++----------- 1 file changed, 30 insertions(+), 19 deletions(-) diff --git a/app/3.0/docs/devguide/shadow-dom.md b/app/3.0/docs/devguide/shadow-dom.md index 6c0b8b5c79..b6d4ddace3 100644 --- a/app/3.0/docs/devguide/shadow-dom.md +++ b/app/3.0/docs/devguide/shadow-dom.md @@ -4,7 +4,7 @@ title: Shadow DOM concepts -Shadow DOM is a new DOM feature that helps you build components. You can think of shadow DOM as a +Shadow DOM is a DOM feature that helps you build components. You can think of shadow DOM as a **scoped subtree** inside your element. **Read more on Web Fundamentals**. This document gives an overview of shadow DOM as it relates to @@ -61,19 +61,30 @@ When you provide a DOM template for an element, Polymer attaches a shadow root f the element and copies the template contents into the shadow tree. -```html - - - +```js +// Import the Polymer library and html helper function +import { Element as PolymerElement, html } from '@polymer/polymer/polymer-element.js'; +// Define the new element as a class +class MyHeader extends PolymerElement { + // Provide a DOM template for the element + static get template (){ + // Tag the returned template literal with the html helper function + // to convert it into an instance of HTMLTemplateElement + return html` + + +
+

I'm a header

+ +
+ + `; + } +} +// Tell the browser about the new tag +customElements.define('my-header', MyHeader); ``` - Note that the template includes a ` -

I'm a shadow DOM child element of x-foo.

+

I'm a shadow DOM child element of custom-element.

So am I.

- - ... - + `; +} +... ``` `index.html` { .caption } ```html - - - - - -

I have nothing to do with x-foo. Because of encapsulation, x-foo's styles won't leak to me.

+ + + + + + + +

I am outside of custom-element. Because of encapsulation, custom-element's styles won't leak to me.

+ ``` For a detailed explanation of shadow DOM as it applies to Polymer, see [Shadow DOM concepts](shadow-dom). @@ -99,47 +90,54 @@ For an exploration of the shadow DOM v1 API, see [Shadow DOM v1: Self-Contained When used in an HTML document, your element will still inherit any styling information that applies to its parent element: -[See it on Plunker](http://plnkr.co/edit/7ugStflqbexg2dNqmtDQ?p=preview) +[See it on Plunker](http://plnkr.co/edit/jziXon?p=preview) -`x-foo.html` { .caption} -```html - - - + `; +} +... ``` -`index.html` { .caption} +`index.html` { .caption } ```html - - - - - -

I'm sans-serif and blue.

+ + + + + + + +

I'm sans-serif and blue.

- -

+ +

+ ``` Styles declared inside shadow DOM will override styles declared outside of it: -[See it on Plunker](http://plnkr.co/edit/0Fid1Gupd0jk9jggAKuv?p=preview) +[See it on Plunker](http://plnkr.co/edit/XDCXXG?p=preview) -`x-foo.html` { .caption} -```html - - - + `; +} +... ``` -`index.html` { .caption} +`index.html` { .caption } ```html - - - -

I'm blue.

-

+ + + + + + +

I'm blue.

+

+ ``` ### Style the host element @@ -172,102 +175,108 @@ The element to which shadow DOM is attached is known as the host. To style the h Inheritable properties of the host element will inherit down the shadow tree, where they apply to the shadow children. -[See it on Plunker](http://plnkr.co/edit/7771DvsQ3iPWnn2gEIf8?p=preview) +[See it on Plunker](http://plnkr.co/edit/BByXie?p=preview) -`x-foo.html` { .caption} -```html - - - + `; +} +... ``` -`index.html` { .caption} +`index.html` { .caption } ```html - - -``` - -You can also style the host element from outside - for example, using a type selector: - -[See it on Plunker](http://plnkr.co/edit/AHXFX0zeQTbO2rGELTbS?p=preview) - -```css -x-foo { - background-color: blue; -} + + + + +

+ ``` #### Use CSS selectors to style the host element You can use CSS selectors to determine when and how to style the host. In this code sample: -* The selector `:host` matches any `` element -* The selector `:host(.blue)` matches `` elements of class `blue` -* The selector `:host(.red)` matches `` elements of class `red` -* The selector `:host(:hover)` matches `` elements when they are hovered over +* The selector `:host` matches any `` element +* The selector `:host(.blue)` matches `` elements of class `blue` +* The selector `:host(.red)` matches `` elements of class `red` +* The selector `:host(:hover)` matches `` elements when they are hovered over -[See it on Plunker](http://plnkr.co/edit/FsXnCAz65SR6fZ7YKuy6?p=preview) +[See it on Plunker](http://plnkr.co/edit/tbPBVG?p=preview) -`x-foo.html` { .caption} -```html - - - +

Hi, from custom-element!

+ `; +} +... ``` -`index.html` { .caption} +`index.html` { .caption } ```html - - - - + + + + + + + ``` Descendant selectors after `:host` match elements in the shadow tree. In this example, the CSS selector applies to any `p` element in the shadow tree if the host has class "warning": -[See it on Plunker](http://plnkr.co/edit/MRN9blKg6A3w8G0RkyJD?p=preview) +[See it on Plunker](http://plnkr.co/edit/U7BG6S?p=preview) -`x-foo.html` { .caption} -```html - - - + `; +} +... ``` -`index.html` { .caption} +`index.html` { .caption } ```html - - - - + + + + + + + ``` Styling with the `:host` selector is one of two instances where rules inside a shadow tree can affect an element outside a shadow tree. The second instance uses the `::slotted()` syntax to apply styling rules to distributed children. See [*Composition and slots* in Eric Bidelman's article on shadow DOM](https://developers.google.com/web/fundamentals/getting-started/primers/shadowdom#composition_slot) for more information. @@ -278,27 +287,27 @@ You can create **slots** in an element's template that are populated at runtime. The basic syntax for incorporating slotted content looks like this: -[See it on Plunker](http://plnkr.co/edit/bNvOvQqCEmC4DaoeNtwZ?p=preview) +[See it on Plunker](http://plnkr.co/edit/e6m48f?p=preview) -`x-foo.html` { .caption} -```html - - - ... - +`custom-element.js` { .caption} +```js +... +static get template() { + return html` +

+ `; +} +... ``` -`index.html` { .caption} +`index.html` { .caption } ```html - - - - I'm a heading! - + + + + + I'm a heading! + ``` To style slotted content, use the `::slotted()` syntax. @@ -307,81 +316,87 @@ To style slotted content, use the `::slotted()` syntax. `::slotted(*)` selects all slotted content: -[See it on Plunker](http://plnkr.co/edit/pb0D6r15jvvxYVWsZ95U?p=preview) +[See it on Plunker](http://plnkr.co/edit/jMjMAY?p=preview) -`x-foo.html` { .caption} -```html - - - ... - +

+

+ `; +} +... ``` -`index.html` { .caption} +`index.html` { .caption } ```html - - -
Heading 1. I'm green.
-
Paragraph text. I'm green too.
- + + + + + +
Heading 1. I'm green.
+
Paragraph text. I'm green too.
+ + ``` -[See it on Plunker](http://plnkr.co/edit/Xb4j1r4wEgGuyUM9huFV?p=preview) - You can select by element type: -`x-foo.html` { .caption} -```html - - - ... - + `; +} +... ``` -`index.html` { .caption} +`index.html` { .caption } ```html - - - -

Heading 1. I'm green.

-

Paragraph text. I'm blue.

- + + + + + +

Heading 1. I'm green.

+

Paragraph text. I'm blue.

+ + ``` You can select by class: -[See it on Plunker](http://plnkr.co/edit/Ep8AVOHgiwQjtv8x5kwd?p=preview) +[See it on Plunker](http://plnkr.co/edit/po4cN3?p=preview) -`x-foo.html` { .caption} -```html - - - -``` +To create a style module: -When you create the element that will use the styles, include the style module in the opening tag of the style block: - -```html - - - -``` +1. Use JavaScript to create a `` element: -You'll most likely want to package the style module in its own html file. In that case, the element that uses the styles will need to import that file. + ```js + const styleElement = document.createElement('dom-module'); + ``` -Here's an example: +2. Set the `` element's `innerHTML` property to contain a ``; + ``` -`my-colors.html` { .caption} -```html - - - - -``` +3. Register your style module as an element: -`x-foo.html` { .caption} -```html - - - - - ... - -``` + ```js + styleElement.register('style-element'); + ``` -`index.html` { .caption} -```html - +You'll most likely want to package the style module in its own JavaScript file. The element that uses the styles will need to import that file. For example: - +```js +import './style-element.js'; ``` +When you create the element that will use the styles, include the style module in the opening tag of the style block: -### Use external stylesheets (deprecated) {#external-stylesheets} - -**Deprecated feature.** This experimental feature is now deprecated in favor of -[style modules](#style-modules). It is still supported, but support will -be removed in the future. -{.alert .alert-info} - -Polymer includes an experimental feature to support loading external stylesheets -that will be applied to the local DOM of an element. This is typically -convenient for developers who like to separate styles, share common styles -between elements, or use style pre-processing tools. The syntax is slightly -different from how stylesheets are typically loaded, as the feature leverages -HTML Imports (or the HTML Imports polyfill, where appropriate) to load the -stylesheet text such that it may be properly shimmed and/or injected as an -inline style. +```js + static template get() { + return html` + + + `; + } +} +``` -To include a remote stylesheet that applies to your Polymer element's local DOM, -place a special HTML import `` tag with `type="css"` in your -`` that refers to the external stylesheet to load. +Here's a complete example: -For example: +[See it on Plunker](http://plnkr.co/edit/PNsZA1?p=preview) -[See it on Plunker](http://plnkr.co/edit/7AvgX9jQApbJoWHbdPkI?p=preview) +index.html { .caption } -`style.css` { .caption} -```css -.red { color: red; } -.green { color: green; } -.blue { color: blue; } +```html + + + + + + +

Style modules

+ +

are useful

+ + ``` -`x-foo.html` { .caption} -```html - - - - - ... - +custom-element.js { .caption } + +```js +import { Element as PolymerElement, html } from "@polymer/polymer/polymer-element"; +import "./style-element.js"; + +class CustomElement extends PolymerElement { + static get template() { + return html` + + + + +
+

Some styles for custom-element.js are defined in style-element.js, which is a style module.

+

Additional styles are defined in custom-element.js.

+
+ `; + } +} +customElements.define('custom-element', CustomElement); ``` -`index.html` { .caption} -```html - +style-element.js { .caption } - +```js +const styleElement = document.createElement('dom-module'); +styleElement.innerHTML = + ``; +styleElement.register('style-element'); ``` ## Use `custom-style` in document-level styles {#custom-style} @@ -607,104 +604,110 @@ Some browsers have not implemented the Shadow DOM v1 specifications. To make sur `custom-style` enables a set of polyfills that ensure that styles in your apps and elements behave as you would expect from the Shadow DOM v1 specifications, even in browsers that don't implement these specifications. -To ensure that your styles behave according to the Shadow DOM v1 specifications in all browsers, use `custom-style` when you define *document-level* styles. `custom-style` is not included with `Polymer.Element` and must be imported separately. -`custom-style` is included with the legacy `polymer.html` import. +To ensure that your styles behave according to the Shadow DOM v1 specifications in all browsers, use `custom-style` when you define *document-level* styles: -*Note: You should only use `custom-style` to define styles for the main document. To define styles for an element's local DOM, just use a ` + +``` -In the first code sample, the style for the `p` element “leaks” into Paragraph B in browsers that haven’t implemented the Shadow DOM v1 specs. In the second code sample, the developer has used `custom-style` to wrap the style block, preventing this leak. +`custom-style` is not included in the `@polymer/polymer/polymer-element` package. Import `custom-style` from `@polymer/polymer/lib/elements/custom-style`: -[See it on Plunker](http://plnkr.co/edit/0o1zuMHgmt4novf2DS8z?p=preview) +index.html { .caption } -`x-foo.html` { .caption} ```html - - - ... - + + - -

Paragraph A: I am in the main DOM. I am red.

- + + +

Paragraph A: I am in the main document. I am red.

+ + ``` -### Syntax and compatibility +In the following code sample, the developer has used `custom-style` to wrap the document-level style block in index.html, preventing the leak. -The syntax of `custom-style` has changed. In Polymer 2.x, `` is a wrapper element. You can use a hybrid syntax to ensure compatibility between Polymer 1.x and other versions. +[See it on Plunker](http://plnkr.co/edit/M6RsuM?p=preview) -Polymer 2.x { .caption} -```html - - - +`custom-element.js` { .caption} +```js +... +static get template() { + return html` +

+ Paragraph B: I am in the shadow DOM of custom-element. Document-level styles in index.html are wrapped in a custom-style block to prevent them from leaking to me. +

+ `; +} +... ``` -Hybrid (compatible with 1.x and 2.x) { .caption} +`index.html` { .caption} ```html - - - -``` + + + -Polymer 1.x { .caption} -```html - -``` + + + + + +

Paragraph A: I am in the main document. I am red.

+ + +``` \ No newline at end of file From 8bba339a8cc123b06fb82a1fe3f893fd150c16a7 Mon Sep 17 00:00:00 2001 From: Kate Jeffreys Date: Tue, 27 Feb 2018 21:49:43 -0800 Subject: [PATCH 4/8] custom props update for 3.0 --- .../docs/devguide/custom-css-properties.md | 632 ++++++++++-------- 1 file changed, 354 insertions(+), 278 deletions(-) diff --git a/app/3.0/docs/devguide/custom-css-properties.md b/app/3.0/docs/devguide/custom-css-properties.md index 765c56c9d2..95d05063c1 100644 --- a/app/3.0/docs/devguide/custom-css-properties.md +++ b/app/3.0/docs/devguide/custom-css-properties.md @@ -4,314 +4,407 @@ title: Use custom properties -The author of a Polymer element can provide custom CSS properties that you can use to style the appearance of the element in your application. +Custom CSS properties allow you to define a CSS variable and use it in your styles. -Custom properties allow CSS authors to define cascading CSS variables, which are accepted by all CSS properties. +## Basic syntax for custom CSS properties -CSS variables can be used outside the context of custom elements, simply as a way to avoid scattering style data throughout a stylesheet. A CSS author assigns values to a custom property, and then uses the `var()` function to use these values elsewhere in the stylesheet. +To set the value of a custom CSS property: -This makes editing your CSS much easier and less prone to author error. +```css +element { + --custom-color: blue; +} +``` -For example, the [`` element](https://www.webcomponents.org/element/PolymerElements/paper-checkbox) provides custom properties for styling the colors, spacing and size of the checkbox and its label. +To use the custom CSS property to create a style: -As a developer, you can use these properties to style `` elements in your applications. +```css +element { + color: var(--custom-color); +} +``` -When you create your own custom elements, you can use custom properties to build an interface for the users of your element so they can style it. +You can use custom CSS properties outside of the context of custom elements, simply as a way to avoid scattering style data throughout a stylesheet. For example: -### Use a custom properties API to style an element +[See it on Plunker](http://plnkr.co/edit/AjZm3o?p=preview) -To use the interface of custom properties provided by an element author, look at the element's API documentation. +```html + + + + + +

Demonstrating basic use of custom properties

+ + +``` -For a good example, visit the [`` API documentation](https://www.webcomponents.org/element/PolymerElements/paper-checkbox/paper-checkbox) +In the code sample above, the visual theme can be changed by editing the values of the custom properties. This makes it easier to create consistent themes, and your code will be less prone to error. -This code sample inserts a `` element with its default styling: +## Use the custom CSS properties provided by a Polymer element -[See it on Plunker](http://plnkr.co/edit/if8IardvWBwZ2uMZIlgI?p=preview) +The author of a Polymer element can provide custom CSS properties that you can use to style the appearance of the element in your application. This way, you don't need to know how the element's code works. -```html - - - - +For example, suppose someone has authored two elements, `` and ``, which can be used together to create layouts in columns or rows, like so: -Check me +```html + + flex item 1 + flex item 2 + flex item 3 + ``` -Notice that: - -* The checkbox label defaults to Times New Roman. This is true of any web page with no style info. -* The checkbox receives default colors from the paper-element theme. +In the documentation for `flex-container`, you notice that the author has provided a custom CSS property, `--flex-direction`, to control whether the `flex-items` are laid out in a column or a row. You can assign your own value to `--flex-direction` in your app: -The style properties of the `` element are configurable with the custom CSS properties that the element author has provided for us. +[See it in Plunker](http://plnkr.co/edit/7eZqv8?p=preview) -To use a custom property of a custom element, create a style rule using this syntax: +index.html { .caption} ```html -paper-checkbox { - --paper-checkbox-checked-color: red; -} + + + + + + + + + + + + flex item 1 + + flex item n + + + ``` -[See it on Plunker](http://plnkr.co/edit/u41sHRHAWtYiYyjWnFlP?p=preview) +**Custom CSS properties inherit.** In the code sample above, the value of `--flex-direction` is set in the `html` CSS rule. Since `flex-container` is a child of `html`, `flex-container` inherits this value. +{.alert} + +To find out about the custom CSS properties an element provides, see the element's documentation. -The paper elements provide a consistent way to configure styles across elements when using the paper element set, with variables. +For examples of Polymer elements that provide extensive styling options with custom CSS properties, see the [API documentation for the `paper-ui-elements`](https://www.webcomponents.org/collection/PolymerElements/paper-ui-elements). -We can use variables to configure the custom CSS properties in ``: +## Provide custom CSS properties to users of your elements + +When you create Polymer elements, you can use custom CSS properties in your style rules. Users of your elements can then set values for the custom CSS properties, and control the appearance of your elements without needing to know how your code works. + +For example, suppose you are creating two elements, `` and ``, which can be used together to create layouts in columns or rows: ```html - + + flex item 1 + flex item 2 + flex item 3 + ``` -## Create custom properties +You can use a custom CSS property to control the flex direction of ``: -Rather than exposing the details of an element's internal implementation for -theming, an element author defines one or more custom CSS -properties as part of the element's API. +[See it in Plunker](http://plnkr.co/edit/7eZqv8?p=preview) -These custom properties can be defined similarly to other standard CSS properties -and will inherit from the point of definition down the composed DOM tree, -similar to the effect of `color` and `font-family`. +flex-container.js (your code) { .caption } -In the simple example below, the author of `` identified the need for -users of the toolbar to be able to change the color of the toolbar title. The -author exposed a custom property called `--my-toolbar-title-color` which is -assigned to the `color` property of the selector for the title element. Users -of the toolbar may define this variable in a CSS rule anywhere up the tree, and -the value of the property will inherit down to the toolbar where it is used if -defined, similar to other standard inheriting CSS properties. +```js +/* ... */ +class FlexContainer extends PolymerElement { + static get template () { + return html` + + + `; + } +} +/* ... */ +``` -Example: { .caption } +Users can then assign their own value to `--flex-direction` like so: + +index.html (user's code) { .caption } ```html - - - - +... + +... ``` -Example usage of ``: { .caption } +If you provide documentation for the custom properties your element provides, users won't need to know any implementation details. See [Documenting your elements](/{{{polymer_version_dir}}}/docs/tools/documentation) for more information, or take a look at the [documentation for the Polymer `paper-ui-elements`](https://www.webcomponents.org/collection/PolymerElements/paper-ui-elements) for examples. -```html - - - - -``` +### Create default values for your CSS properties -The `--my-toolbar-title-color` property only affects the color of the title -element encapsulated in ``'s internal implementation. In the -future the `` author can rename the `title` class or -restructure the internal details of `` without changing the custom -property exposed to users. +You may want to provide default values for the CSS properties you use in your styles. -You can also include a default value in the `var()` function, to use in case the user -doesn't set the custom property: +To set a default value for a CSS property, use the following syntax: ```css -color: var(--my-toolbar-title-color, blue); +div { + background-color: var(--theme-background, #e3f2fd); +} ``` -To include a default value that is a custom property, use this syntax: +To use a default value that is itself a custom property, use the following syntax: ```css -color: var(--my-color, var(--my-default-color)) +div { + background-color: var(--theme-background, var(--default-light-blue)); +} ``` -Thus, custom CSS properties are a powerful way for element authors to -expose a theming API to their users in a way that naturally fits right alongside -normal CSS styling. +## Inheritance and global styles -### Use custom CSS mixins +Custom CSS properties inherit down the DOM hierarchy. In the code sample below, `` will inherit the custom properties defined for `div`, but not the custom properties defined for `span`. -It may be tedious (or impossible) for an element author to predict every -CSS property that may be important for theming, let alone expose every -property individually. +[See it on Plunker](http://plnkr.co/edit/mHpf7L?p=preview) -CSS mixins are a proposal to fill this gap in functionality. To use CSS mixins, import the CSS mixins polyfill: +```html + + + + + + + + + + + +
+ + flex item 1 + flex item 2 + flex item 3 + +
+ +

hello i am in a span

+ + + +``` + +You can use inheritance to define global custom CSS properties. In the code sample below, all nodes inherit the custom CSS properties defined for the top-level `html` element: + +[See it on Plunker](http://plnkr.co/edit/7rbXJY?p=preview) + +index.html { .caption} ```html - - +... + + + +... +
+ + flex item 1 + flex item 2 + flex item 3 + +
+ +

hello i am in a span

+ +... ``` -For backward compatibility, the `polymer.html` import includes the CSS mixins polyfill. No extra import is required when defining hybrid elements. +Child elements that inherit global CSS properties can override them. For example, in the code sample above, `` inherited its custom CSS properties and fonts from the document-level styles for `html`. `` can override these properties: -Using CSS mixins, an element author can define a set of CSS properties as a single custom property and then allow all properties in the set to be applied to a specific CSS rule -in an element's shadow DOM. The extension enables this with a mixin capability -that is analogous to `var`, but which allows an entire set of properties -to be mixed in. +[See it on Plunker](http://plnkr.co/edit/vlO7GV?p=preview) -Use `@apply` to apply a mixin: +flex-item.js {.caption} + +```js +static get template () { + return html` + + `; +} +``` -
@apply --mixin-name;
+## Use custom CSS mixins -Defining a mixin is just like defining a custom property, but the -value is an object that defines one or more rules: +Using CSS mixins, you can define a set of CSS properties as a single custom property. -
selector {
-  --mixin-name: {
+This is similar to defining a custom property with `var()`, but the value of the property is an object that defines one or more rules:
+
+```css
+selector {
+  --mixin-name: {
     /* rules */
   };
-}
+} +``` -Example: { .caption } +Use `@apply` to apply a mixin: -```html - - - ... - + ... + `; +} ``` -Example usage of `my-toolbar`: { .caption } +flex-item.js { .caption} -```html - - - - + ... + `; +} ``` -## Use CSS inheritance +Users of `flex-item` can set values for the properties in the mixin: -If an element doesn't override styling information, that element inherits styles from its parent: +index.html {.caption} ```html - + + + + - -

Check me

- ``` -## Create global styles - -Create global styles by styling the the html element of your document: +Note that any element using the `@apply` syntax must import the `@apply` polyfill: -```html - - - - +```js +// import CSS mixins polyfill +import './node_modules/@webcomponents/shadycss/entrypoints/apply-shim.js'; ``` -Note that the font family is inherited, but the text color is not. This is because `` overrides the text color. +[See an example in Plunker](http://plnkr.co/edit/glgUKv?p=preview). ### Custom property API for Polymer elements {#style-api} Polymer's custom property shim evaluates and applies custom property values once at element creation time. In order to have an element (and its subtree) re- evaluate custom property values due to dynamic changes such as application of -CSS classes, call the [`updateStyles`](/2.0/docs/api/elements/Polymer.Element#method-updateStyles) +CSS classes, call the [`updateStyles`](/3.0/docs/api/elements/Polymer.Element#method-updateStyles) method on the element. To update _all_ elements on the page, you can also call `Polymer.updateStyles`. @@ -320,39 +413,28 @@ custom properties. Example: { .caption } -```html - - - - -``` - -```html -this.updateStyles({ - '--some-custom-style': 'green', - '--another-custom-style': 'blue' -}); + } + static template get (){ + return html` + + My awesome app + + `; + } +} +customElements.define('x-custom', XCustom); ``` Occasionally an element needs to get the value of a custom property at runtime. This is handled @@ -367,10 +449,9 @@ if (ShadyCSS) { ``` Elements using the legacy API can use the -[`getComputedStyleValue`](/2.0/docs/api/mixins/Polymer.LegacyElementMixin#method-getComputedStyleValue) +[`getComputedStyleValue`](/3.0/docs/api/mixins/Polymer.LegacyElementMixin#method-getComputedStyleValue) instance method instead of testing for `ShadyCSS`. - ### Custom properties shim limitations Cross-platform support for custom properties is provided in Polymer by a @@ -449,37 +530,32 @@ only have a single value.** Calculating property changes within a scope would b prohibitively expensive for the shim and is not required to achieve cross-scope styling for custom elements, which is the primary goal of the shim. -```html - - - - + .container { + /* Setting the custom property here will not change */ + /* the value of the property for other elements in */ + /* this scope. */ + --custom-color: blue; + } + .child { + /* This will be always be red. */ + color: var(--custom-color); + } + +
+
I will be red
+
+ `; + } + customElements.define('my-element', MyElement); +} ``` #### Styling distributed elements not supported From 459269a04c1ebe93a7a69aad6095a9201c92fc10 Mon Sep 17 00:00:00 2001 From: Kate Jeffreys Date: Fri, 30 Mar 2018 14:38:06 -0700 Subject: [PATCH 5/8] proofread --- .../docs/devguide/custom-css-properties.md | 40 +++--- app/3.0/docs/devguide/shadow-dom.md | 4 +- app/3.0/docs/devguide/style-shadow-dom.md | 128 +++++++++++------- 3 files changed, 101 insertions(+), 71 deletions(-) diff --git a/app/3.0/docs/devguide/custom-css-properties.md b/app/3.0/docs/devguide/custom-css-properties.md index 95d05063c1..f8b957ea04 100644 --- a/app/3.0/docs/devguide/custom-css-properties.md +++ b/app/3.0/docs/devguide/custom-css-properties.md @@ -26,8 +26,6 @@ element { You can use custom CSS properties outside of the context of custom elements, simply as a way to avoid scattering style data throughout a stylesheet. For example: -[See it on Plunker](http://plnkr.co/edit/AjZm3o?p=preview) - ```html @@ -55,6 +53,8 @@ You can use custom CSS properties outside of the context of custom elements, sim ``` +[See it on Plunker](http://plnkr.co/edit/AjZm3o?p=preview) + In the code sample above, the visual theme can be changed by editing the values of the custom properties. This makes it easier to create consistent themes, and your code will be less prone to error. ## Use the custom CSS properties provided by a Polymer element @@ -73,8 +73,6 @@ For example, suppose someone has authored two elements, `` and ` In the documentation for `flex-container`, you notice that the author has provided a custom CSS property, `--flex-direction`, to control whether the `flex-items` are laid out in a column or a row. You can assign your own value to `--flex-direction` in your app: -[See it in Plunker](http://plnkr.co/edit/7eZqv8?p=preview) - index.html { .caption} ```html @@ -83,7 +81,7 @@ index.html { .caption} + @@ -105,6 +103,8 @@ index.html { .caption} ``` +[See it in Plunker](http://plnkr.co/edit/7eZqv8?p=preview) + **Custom CSS properties inherit.** In the code sample above, the value of `--flex-direction` is set in the `html` CSS rule. Since `flex-container` is a child of `html`, `flex-container` inherits this value. {.alert} @@ -128,8 +128,6 @@ For example, suppose you are creating two elements, `` and ``: -[See it in Plunker](http://plnkr.co/edit/7eZqv8?p=preview) - flex-container.js (your code) { .caption } ```js @@ -150,6 +148,8 @@ class FlexContainer extends PolymerElement { /* ... */ ``` +[See it in Plunker](http://plnkr.co/edit/7eZqv8?p=preview) + Users can then assign their own value to `--flex-direction` like so: index.html (user's code) { .caption } @@ -190,8 +190,6 @@ div { Custom CSS properties inherit down the DOM hierarchy. In the code sample below, `` will inherit the custom properties defined for `div`, but not the custom properties defined for `span`. -[See it on Plunker](http://plnkr.co/edit/mHpf7L?p=preview) - ```html @@ -233,9 +231,9 @@ Custom CSS properties inherit down the DOM hierarchy. In the code sample below, ``` -You can use inheritance to define global custom CSS properties. In the code sample below, all nodes inherit the custom CSS properties defined for the top-level `html` element: +[See it on Plunker](http://plnkr.co/edit/mHpf7L?p=preview) -[See it on Plunker](http://plnkr.co/edit/7rbXJY?p=preview) +You can use inheritance to define global custom CSS properties. In the code sample below, all nodes inherit the custom CSS properties defined for the top-level `html` element: index.html { .caption} @@ -270,9 +268,9 @@ index.html { .caption} ... ``` -Child elements that inherit global CSS properties can override them. For example, in the code sample above, `` inherited its custom CSS properties and fonts from the document-level styles for `html`. `` can override these properties: +[See it on Plunker](http://plnkr.co/edit/7rbXJY?p=preview) -[See it on Plunker](http://plnkr.co/edit/vlO7GV?p=preview) +Child elements that inherit global CSS properties can override them. For example, in the code sample above, `` inherited its custom CSS properties and fonts from the document-level styles for `html`. `` can override these properties: flex-item.js {.caption} @@ -290,6 +288,8 @@ static get template () { } ``` +[See it on Plunker](http://plnkr.co/edit/vlO7GV?p=preview) + ## Use custom CSS mixins Using CSS mixins, you can define a set of CSS properties as a single custom property. @@ -314,8 +314,6 @@ Suppose we have two custom elements, `` and ``, which The author of the two elements uses a CSS mixin to apply theming information to both elements: -[See it on Plunker](http://plnkr.co/edit/glgUKv?p=preview) - flex-container.js {.caption} ```js @@ -356,13 +354,15 @@ static get template() { } ``` +[See it on Plunker](http://plnkr.co/edit/glgUKv?p=preview) + Users of `flex-item` can set values for the properties in the mixin: index.html {.caption} ```html - + @@ -397,7 +397,7 @@ Note that any element using the `@apply` syntax must import the `@apply` polyfil import './node_modules/@webcomponents/shadycss/entrypoints/apply-shim.js'; ``` -[See an example in Plunker](http://plnkr.co/edit/glgUKv?p=preview). +[See it in Plunker](http://plnkr.co/edit/glgUKv?p=preview) ### Custom property API for Polymer elements {#style-api} @@ -411,7 +411,7 @@ method on the element. To update _all_ elements on the page, you can also call `updateStyles` can take a object with property/value pairs to update the current values of custom properties. -Example: { .caption } +Example { .caption } ```js class XCustom extends PolymerElement { @@ -477,7 +477,7 @@ styles. For example, given this markup inside an element: -HTML: { .caption } +HTML { .caption } ```html
@@ -485,7 +485,7 @@ HTML: { .caption }
``` -CSS: { .caption } +CSS { .caption } ```css /* applies */ diff --git a/app/3.0/docs/devguide/shadow-dom.md b/app/3.0/docs/devguide/shadow-dom.md index b6d4ddace3..2ef1c9454c 100644 --- a/app/3.0/docs/devguide/shadow-dom.md +++ b/app/3.0/docs/devguide/shadow-dom.md @@ -63,11 +63,11 @@ the element and copies the template contents into the shadow tree. ```js // Import the Polymer library and html helper function -import { Element as PolymerElement, html } from '@polymer/polymer/polymer-element.js'; +import { PolymerElement, html } from '@polymer/polymer/polymer-element.js'; // Define the new element as a class class MyHeader extends PolymerElement { // Provide a DOM template for the element - static get template (){ + static get template () { // Tag the returned template literal with the html helper function // to convert it into an instance of HTMLTemplateElement return html` diff --git a/app/3.0/docs/devguide/style-shadow-dom.md b/app/3.0/docs/devguide/style-shadow-dom.md index dc7a4e5c47..84c7050931 100644 --- a/app/3.0/docs/devguide/style-shadow-dom.md +++ b/app/3.0/docs/devguide/style-shadow-dom.md @@ -10,9 +10,8 @@ Polymer supports DOM templating and the shadow DOM API. When you provide a DOM t Here's an example: -[See it on Plunker](http://plnkr.co/edit/JooAma?p=preview) +custom-element.js { .caption } -`custom-element.js` { .caption } ```js ... static get template() { @@ -24,7 +23,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -34,6 +34,9 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/JooAma?p=preview) + + The HTML elements in your template become children in your custom element's shadow DOM. Shadow DOM provides a mechanism for encapsulation, meaning that elements inside the shadow DOM don't match selectors outside the shadow DOM. Likewise, styling rules in side the shadow DOM can't "leak" out to affect elements outside the shadow DOM. @@ -42,9 +45,8 @@ Shadow DOM permits encapsulation of styling rules for custom elements. You can f Here's an example: -[See it on Plunker](http://plnkr.co/edit/NKuNTD?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -65,7 +67,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -82,6 +85,8 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/NKuNTD?p=preview) + For a detailed explanation of shadow DOM as it applies to Polymer, see [Shadow DOM concepts](shadow-dom). For an exploration of the shadow DOM v1 API, see [Shadow DOM v1: Self-Contained Web Components](https://developers.google.com/web/fundamentals/getting-started/primers/shadowdom). @@ -90,9 +95,8 @@ For an exploration of the shadow DOM v1 API, see [Shadow DOM v1: Self-Contained When used in an HTML document, your element will still inherit any styling information that applies to its parent element: -[See it on Plunker](http://plnkr.co/edit/jziXon?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -106,7 +110,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -127,11 +132,12 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/jziXon?p=preview) + Styles declared inside shadow DOM will override styles declared outside of it: -[See it on Plunker](http://plnkr.co/edit/XDCXXG?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -150,7 +156,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -168,6 +175,8 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/XDCXXG?p=preview) + ### Style the host element @@ -175,9 +184,8 @@ The element to which shadow DOM is attached is known as the host. To style the h Inheritable properties of the host element will inherit down the shadow tree, where they apply to the shadow children. -[See it on Plunker](http://plnkr.co/edit/BByXie?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -199,7 +207,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -209,6 +218,8 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/BByXie?p=preview) + #### Use CSS selectors to style the host element You can use CSS selectors to determine when and how to style the host. In this code sample: @@ -218,9 +229,8 @@ You can use CSS selectors to determine when and how to style the host. In this c * The selector `:host(.red)` matches `` elements of class `red` * The selector `:host(:hover)` matches `` elements when they are hovered over -[See it on Plunker](http://plnkr.co/edit/tbPBVG?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -237,7 +247,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -248,11 +259,12 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/tbPBVG?p=preview) + Descendant selectors after `:host` match elements in the shadow tree. In this example, the CSS selector applies to any `p` element in the shadow tree if the host has class "warning": -[See it on Plunker](http://plnkr.co/edit/U7BG6S?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -268,7 +280,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -279,6 +292,8 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/U7BG6S?p=preview) + Styling with the `:host` selector is one of two instances where rules inside a shadow tree can affect an element outside a shadow tree. The second instance uses the `::slotted()` syntax to apply styling rules to distributed children. See [*Composition and slots* in Eric Bidelman's article on shadow DOM](https://developers.google.com/web/fundamentals/getting-started/primers/shadowdom#composition_slot) for more information. ### Style slotted content (distributed children) @@ -287,9 +302,8 @@ You can create **slots** in an element's template that are populated at runtime. The basic syntax for incorporating slotted content looks like this: -[See it on Plunker](http://plnkr.co/edit/e6m48f?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -300,7 +314,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -310,15 +325,16 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/e6m48f?p=preview) + To style slotted content, use the `::slotted()` syntax. **Note:** To work within the Shady CSS scoping shim limitations, and to ensure consistent cross-browser behavior, add a selector to the left of the `::slotted(.classname)` notation (for example, `p ::slotted(.classname)`. `::slotted(*)` selects all slotted content: -[See it on Plunker](http://plnkr.co/edit/jMjMAY?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -336,7 +352,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -349,11 +366,12 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/jMjMAY?p=preview) + You can select by element type: -[See it on Plunker](http://plnkr.co/edit/rt0jDx?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -375,7 +393,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -388,11 +407,12 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/rt0jDx?p=preview) + You can select by class: -[See it on Plunker](http://plnkr.co/edit/po4cN3?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -413,7 +433,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -428,11 +449,13 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/po4cN3?p=preview) + + And you can select by slot name: -[See it on Plunker](http://plnkr.co/edit/hR3I4w?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -453,7 +476,8 @@ static get template() { ... ``` -`index.html` { .caption } +index.html { .caption } + ```html @@ -466,6 +490,8 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/hR3I4w?p=preview) + ## Share styles between elements ### Use style modules {#style-modules} @@ -522,8 +548,6 @@ When you create the element that will use the styles, include the style module i Here's a complete example: -[See it on Plunker](http://plnkr.co/edit/PNsZA1?p=preview) - index.html { .caption } ```html @@ -543,8 +567,8 @@ index.html { .caption } custom-element.js { .caption } ```js -import { Element as PolymerElement, html } from "@polymer/polymer/polymer-element"; -import "./style-element.js"; +import { PolymerElement, html } from '@polymer/polymer/polymer-element.js'; +import './style-element.js'; class CustomElement extends PolymerElement { static get template() { @@ -596,7 +620,9 @@ styleElement.innerHTML = styleElement.register('style-element'); ``` -## Use `custom-style` in document-level styles {#custom-style} +[See it on Plunker](http://plnkr.co/edit/PNsZA1?p=preview) + +## Use custom-style in document-level styles {#custom-style} Browsers that implement the current Shadow DOM v1 specifications will automatically encapsulate styles, scoping them to the elements in which they were defined. @@ -616,7 +642,7 @@ index.html { .caption } ``` -`custom-style` is not included in the `@polymer/polymer/polymer-element` package. Import `custom-style` from `@polymer/polymer/lib/elements/custom-style`: +`custom-style` is not included in the `@polymer/polymer/polymer-element.js` package. Import `custom-style` from `@polymer/polymer/lib/elements/custom-style.js`: index.html { .caption } @@ -642,9 +668,8 @@ index.html { .caption } In the following code sample, the document-level style in index.html "leaks" into the shadow DOM of `` in browsers that haven’t implemented the Shadow DOM v1 specs. -[See it on Plunker](http://plnkr.co/edit/FJEC5C?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -659,7 +684,8 @@ static get template() { ... ``` -`index.html` { .caption} +index.html { .caption} + ```html @@ -675,11 +701,12 @@ static get template() { ``` +[See it on Plunker](http://plnkr.co/edit/FJEC5C?p=preview) + In the following code sample, the developer has used `custom-style` to wrap the document-level style block in index.html, preventing the leak. -[See it on Plunker](http://plnkr.co/edit/M6RsuM?p=preview) +custom-element.js { .caption} -`custom-element.js` { .caption} ```js ... static get template() { @@ -692,7 +719,8 @@ static get template() { ... ``` -`index.html` { .caption} +index.html { .caption} + ```html @@ -710,4 +738,6 @@ static get template() {

Paragraph A: I am in the main document. I am red.

-``` \ No newline at end of file +``` + +[See it on Plunker](http://plnkr.co/edit/M6RsuM?p=preview) \ No newline at end of file From d6be16e7f80ca4e32a0a19897d7217c4de038db5 Mon Sep 17 00:00:00 2001 From: Kate Jeffreys Date: Fri, 30 Mar 2018 15:00:37 -0700 Subject: [PATCH 6/8] proofread --- app/3.0/docs/devguide/custom-css-properties.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/app/3.0/docs/devguide/custom-css-properties.md b/app/3.0/docs/devguide/custom-css-properties.md index f8b957ea04..faf032b834 100644 --- a/app/3.0/docs/devguide/custom-css-properties.md +++ b/app/3.0/docs/devguide/custom-css-properties.md @@ -402,7 +402,7 @@ import './node_modules/@webcomponents/shadycss/entrypoints/apply-shim.js'; ### Custom property API for Polymer elements {#style-api} Polymer's custom property shim evaluates and applies custom property values once -at element creation time. In order to have an element (and its subtree) re- +at element creation time. In order to have an element (and its subtree) re- evaluate custom property values due to dynamic changes such as application of CSS classes, call the [`updateStyles`](/3.0/docs/api/elements/Polymer.Element#method-updateStyles) method on the element. To update _all_ elements on the page, you can also call @@ -456,7 +456,7 @@ instance method instead of testing for `ShadyCSS`. Cross-platform support for custom properties is provided in Polymer by a JavaScript library that **approximates** the capabilities of the CSS Variables -specification *for the specific use case of theming custom elements*, while +specification *for the specific use case of theming custom elements*, while also extending it to add the capability to mixin property sets to rules as described above. For performance reasons, Polymer **does not attempt to replicate all aspects of native custom properties.** @@ -525,8 +525,8 @@ have the desired effect, since the dynamism is related to *application* of a cus Unlike normal CSS inheritance which flows from parent to child, custom properties in Polymer's shim can only change when inherited by a custom element from rules that set properties in scope(s) above it, or in a `:host` rule for -that scope. **Within a given element's local DOM scope, a custom property can -only have a single value.** Calculating property changes within a scope would be +that scope. **Within a given element's local DOM scope, a custom property can +only have a single value.** Calculating property changes within a scope would be prohibitively expensive for the shim and is not required to achieve cross-scope styling for custom elements, which is the primary goal of the shim. From 1ebff40b54caaa5a95b19658e7e1362c3ec7a9c8 Mon Sep 17 00:00:00 2001 From: Kate Jeffreys Date: Thu, 12 Apr 2018 17:26:37 -0700 Subject: [PATCH 7/8] feedback --- .../docs/devguide/custom-css-properties.md | 32 +++++++++---------- app/3.0/docs/devguide/shadow-dom.md | 10 +++--- app/3.0/docs/devguide/style-shadow-dom.md | 10 +++--- 3 files changed, 27 insertions(+), 25 deletions(-) diff --git a/app/3.0/docs/devguide/custom-css-properties.md b/app/3.0/docs/devguide/custom-css-properties.md index faf032b834..2e9ec47335 100644 --- a/app/3.0/docs/devguide/custom-css-properties.md +++ b/app/3.0/docs/devguide/custom-css-properties.md @@ -80,12 +80,12 @@ index.html { .caption} - + -

@@ -535,7 +535,7 @@ import './style-element.js'; When you create the element that will use the styles, include the style module in the opening tag of the style block: ```js - static template get() { + static get template() { return html` +``` + +Finally, remove the `unresolved` attribute in the element's `ready` callback: + +```js +class MyElement extends PolymerElement(){ + ... + ready(){ + super.ready(); + this.removeAttribute('unresolved'); + ... + } + ... +} +``` + +### Style directional text with the :dir() selector + +The `:dir()` CSS selector allows for styling text specific to its orientation +(right-to-left or left-to-right). See the [documentation on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir) for more information on the `:dir()` +selector. + +The `DirMixin` provides limited support for the `:dir()` selector. Use of `:dir()` requires the +application to set the `dir` attribute on ``. All elements will use the same direction. + +Individual elements can opt-out of the global direction by setting the `dir` attribute +in HTML or in the `ready` callback, but the text direction of these elements must from then on be handled +manually. + +Setting `dir` on an ancestor (other than `html`) has no effect. + +For elements that extend `PolymerElement`, add `DirMixin` to use +`:dir()` styling. + +Here's an example use of the `:dir()` selector: + +`using-dir-selector.js` { .caption } + +```js +import { PolymerElement, html } from '@polymer/polymer/polymer-element.js'; +import DirMixin from '@polymer/polymer/lib/mixins/dir-mixin.js'; + +class UsingDirSelector extends DirMixin(PolymerElement) { + static get template() { + return html` + + ... + `; + } +} +customElements.define('using-dir-selector', UsingDirSelector); +``` + +`index.html` { .caption } + +```html + + + + + + + + +``` + ## Share styles between elements ### Use style modules {#style-modules}