-
Notifications
You must be signed in to change notification settings - Fork 318
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Refine API and refactor #132
Changes from 57 commits
94d4e48
f8f8862
df3c39d
dc5d931
5861e0e
8f83306
e18819e
da54543
b39b480
5ef504e
10fdf29
f131d96
3b5611c
82be06b
3637c1e
bbd3267
3f0315c
85f4cf2
a8d888d
e97392e
00d9d5c
f2f908d
8160de8
e4c7d91
e6a3c70
b39b979
fed3307
5f3cffd
05ba1e4
4361daf
baaf296
f2865de
d4edcd8
9f1a709
25f4ca6
9f8e145
59cd15e
bf6da1d
f684c63
1953a79
f3f28b8
234dff0
24ac381
13e48e6
d708572
9a9aced
4bab118
88a1ad9
10edcc6
a447927
ec02fd8
b77ee89
b0c7428
9341ae2
d3a781b
af1c542
e9d400e
bb6d73d
55bc308
b611732
d11ba45
a85f4bb
c312464
84180cd
49cc74c
ffbfead
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,17 @@ | ||
/node_modules | ||
/bower_components | ||
*.js | ||
*.js.map | ||
*.d.ts | ||
/node_modules/ | ||
/lib/ | ||
|
||
#Compiler Output | ||
lit-element.js | ||
lit-element.js.map | ||
lit-element.d.ts | ||
|
||
/test/**/*.d.ts | ||
/test/**/*.js | ||
/test/**/*.js.map | ||
|
||
/demo/**/*.d.ts | ||
/demo/**/*.js | ||
/demo/**/*.js.map | ||
|
||
!custom_typings/ |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -10,11 +10,47 @@ | |
|
||
LitElement uses [lit-html](https://github.com/Polymer/lit-html) to render into the | ||
element's [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) | ||
and [Polymer's](https://github.com/Polymer/polymer) | ||
[PropertiesMixin](https://github.com/Polymer/polymer/blob/master/lib/mixins/properties-mixin.js) | ||
to help manage element properties and attributes. LitElement reacts to changes in properties | ||
and adds API to help manage element properties and attributes. LitElement reacts to changes in properties | ||
and renders declaratively using `lit-html`. | ||
|
||
* **Setup properties:** LitElement supports observable properties that cause the element to update. | ||
These properties can be declared in a few ways: | ||
|
||
* As class fields with the `@property()` [decorator](https://github.com/tc39/proposal-decorators#decorators), | ||
if you're using a compiler that supports them, like TypeScript or Babel. | ||
* With a static `properties` getter. | ||
* By manually writing getters and setters. This can be useful if tasks should | ||
be performed when a property is set, for example validation. Call `invalidateProperty(name, oldValue)` | ||
in the setter to trigger an update and use any configured property options. | ||
|
||
Properties can be given an options argument which is an object that describes how to | ||
process the property. This can be done either in the `@property({...})` decorator or in the | ||
object returned from the `properties` getter, e.g. `static get properties { return { foo: {...} }`. | ||
|
||
Property options include: | ||
|
||
* `attribute`: Describes how and whether the property becomes an observed attribute. | ||
If the value is `false`, the property is not added to `observedAttributes`. | ||
If true or absent, the lowercased property name is observed (e.g. `fooBar` becomes `foobar`). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. same with true There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done |
||
If a string, the string value is observed (e.g `attribute: 'foo-bar'`). | ||
* `type`: Describes how to serialize and deserialize the attribute to/from a property. | ||
If this value is a function, it is used to deserialize the attribute value | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. So how does it get serialized in that case? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fixed |
||
a the property value. If it's an object, it can have keys for `fromAttribute` and | ||
`toAttribute` where `fromAttribute` is the deserialize function and `toAttribute` | ||
is a serialize function used to set the property to an attribute. If no `toAttribute` | ||
function is provided and `reflect` is set to `true`, the property value is set | ||
directly to the attribute. | ||
* `reflect`: Describes if the property should reflect to an attribute. | ||
If `true`, when the property is set, the attribute is set using the | ||
attribute name determined according to the rules for the `attribute` | ||
propety option and the value of the property serialized using the rules from | ||
the `type` property option. | ||
* `shouldInvalidate`: Describes if setting a property should trigger | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think this name might be a bit confusing, because as a dev I would think "why shouldn't it invalidade?" But when I read here it is more understandable that for complex objects equality is much more complex. Maybe I would turn it around and call it
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Going to leave it as is for now to get some more feedback but will consider changing it. |
||
invalidation and updating. This function takes the `newValue` and `oldValue` and | ||
returns `true` if invalidation should occur. If not present, a strict identity | ||
check is used. This is useful if a property should be considered dirty only | ||
if some condition is met, like if a key of an object value changes. | ||
|
||
* **React to changes:** LitElement reacts to changes in properties and attributes by | ||
asynchronously rendering, ensuring changes are batched. This reduces overhead | ||
and maintains consistent state. | ||
|
@@ -27,8 +63,9 @@ and renders declaratively using `lit-html`. | |
|
||
* static elements: ``` html`<div>Hi</div>` ``` | ||
* expression: ``` html`<div>${disabled ? 'Off' : 'On'}</div>` ``` | ||
* attribute: ``` html`<div class$="${color} special"></div>` ``` | ||
* event handler: ``` html`<button on-click="${(e) => this._clickHandler(e)}"></button>` ``` | ||
* property: ``` html`<x-foo .bar="${bar}"></x-foo>` ``` | ||
* attribute: ``` html`<div class="${color} special"></div>` ``` | ||
* event handler: ``` html`<button @click="${(e) => this._clickHandler(e)}"></button>` ``` | ||
|
||
## Getting started | ||
|
||
|
@@ -68,24 +105,25 @@ and renders declaratively using `lit-html`. | |
## Minimal Example | ||
|
||
1. Create a class that extends `LitElement`. | ||
1. Implement a static `properties` getter that returns the element's properties | ||
(which automatically become observed attributes). | ||
1. Then implement a `_render(props)` method and use the element's | ||
current properties (props) to return a `lit-html` template result to render | ||
1. Use a `@property` decorator to create a property (or implement a static `properties` | ||
getter that returns the element's properties). (which automatically become observed attributes). | ||
1. Then implement a `render()` method and use the element's | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think a minimal TypeScript example should be right up top to sell things a little. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done |
||
current properties to return a `lit-html` template result to render | ||
into the element. This is the only method that must be implemented by subclasses. | ||
|
||
```html | ||
<script src="node_modules/@webcomponents/webcomponents-bundle.js"></script> | ||
<script type="module"> | ||
import {LitElement, html} from '@polymer/lit-element'; | ||
import {LitElement, html, property} from '@polymer/lit-element'; | ||
|
||
class MyElement extends LitElement { | ||
|
||
static get properties() { return { mood: String }} | ||
@property({type: String}) | ||
mood = 'happy'; | ||
|
||
_render({mood}) { | ||
render() { | ||
return html`<style> .mood { color: green; } </style> | ||
Web Components are <span class="mood">${mood}</span>!`; | ||
Web Components are <span class="mood">${this.mood}</span>!`; | ||
} | ||
|
||
} | ||
|
@@ -98,69 +136,101 @@ into the element. This is the only method that must be implemented by subclasses | |
|
||
## API Documentation | ||
|
||
See the [source](https://github.com/PolymerLabs/lit-element/blob/master/src/lit-element.ts#L90) | ||
for detailed API info, here are some highlights. Note, the leading underscore | ||
is used to indicate that these methods are | ||
[protected](https://en.wikipedia.org/wiki/Class_(computer_programming)#Member_accessibility); | ||
they are not private and can and should be implemented by subclasses. | ||
These methods generally are called as part of the rendering lifecycle and should | ||
not be called in user code unless otherwise indicated. | ||
* `render()` (protected): Implement to describe the element's DOM using `lit-html`. Ideally, | ||
the `render` implementation is a [pure function](https://en.wikipedia.org/wiki/Pure_function) using only the element's current properties | ||
to describe the element template. This is the only method that must be implemented by subclasses. | ||
Note, since `render()` is called by `update()`, setting properties does not trigger | ||
`invalidate()`, allowing property values to be computed and validated. | ||
|
||
* `_createRoot()`: Implement to customize where the | ||
* `shouldUpdate(changedProperties)` (protected): Implement to control if updating and rendering | ||
should occur when property values change or `invalidate` is called. The `changedProperties` | ||
argument is an object with keys for the changed properties pointing to their previous values. | ||
By default, this method always returns true, but this can be customized as | ||
an optimization to avoid updating work when changes occur, which should not be rendered. | ||
|
||
* `update()` (protected): This method calls `render()` and then uses `lit-html` in order to | ||
render the template DOM. Implement to directly control rendered DOM. | ||
Typically this is not needed as `lit-html` can be used in the `render` method | ||
to set properties, attributes, and event listeners. However, it is sometimes useful | ||
for calling methods on rendered elements, for example focusing an input: | ||
`this.shadowRoot.querySelector('input').focus()`. The `changedProperties` argument is a Map | ||
with keys for the changed properties pointing to their previous values. | ||
Note, calling `super.update()` is required. Before calling `super.update()`, | ||
changes made to properties do not trigger `invalidate()`, after calling `super.update()`, | ||
changes do trigger `invalidate()`. | ||
|
||
* `firstRendered()`: (protected) Called after the element's DOM has been | ||
updated the first time. This method can be useful for capturing references to rendered static | ||
nodes that must be directly acted upon, for example in `update()`. | ||
|
||
* `updateComplete`: Returns a Promise that resolves when the element has completed | ||
updating that resolves to a boolean value that is `true` if the element completed the | ||
update without triggering another update. This can happen if a property is set in | ||
`update()` after the call to `super.update()` for example. This getter can be | ||
implemented to await additional state. For example, it is sometimes useful to | ||
await a rendered element before fulfilling this promise. To do this, first | ||
await `super.updateComplete` then any subsequent state. | ||
|
||
* `invalidate`: Call to request the element to asynchronously update regardless | ||
of whether or not any property changes are pending. This should only be called | ||
when an element should update based on some state not stored in properties, | ||
since setting properties automically calls `invalidate`. | ||
|
||
* `invalidateProperty(name, oldValue)` (protected): Triggers an invalidation for | ||
a specific property. This is useful when manually implementing a property setter. | ||
Call `invalidateProperty` instead of `invalidate` to ensure that any configured | ||
property options are honored. | ||
|
||
* `createRenderRoot()` (protected): Implement to customize where the | ||
element's template is rendered by returning an element into which to | ||
render. By default this creates a shadowRoot for the element. | ||
To render into the element's childNodes, return `this`. | ||
|
||
* `_firstRendered()`: Called after the element DOM is rendered for the first time. | ||
|
||
* `_shouldRender(props, changedProps, prevProps)`: Implement to control if rendering | ||
should occur when property values change or `invalidate` is called. | ||
By default, this method always returns true, but this can be customized as | ||
an optimization to avoid rendering work when changes occur which should not be rendered. | ||
|
||
* `_render(props)`: Implement to describe the element's DOM using `lit-html`. Ideally, | ||
the `_render` implementation is a pure function using only `props` to describe | ||
the element template. This is the only method that must be implemented by subclasses. | ||
|
||
* `_didRender(props, changedProps, prevProps)`: Called after element DOM has been rendered. | ||
Implement to directly control rendered DOM. Typically this is not needed as `lit-html` | ||
can be used in the `_render` method to set properties, attributes, and | ||
event listeners. However, it is sometimes useful for calling methods on | ||
rendered elements, for example focusing an input: | ||
`this.shadowRoot.querySelector('input').focus()`. | ||
|
||
* `renderComplete`: Returns a promise which resolves after the element next renders. | ||
|
||
* `_requestRender`: Call to request the element to asynchronously re-render regardless | ||
of whether or not any property changes are pending. | ||
## Advanced: Update Lifecycle | ||
|
||
* When the element is first connected or a property is set (e.g. `element.foo = 5`) | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I find the nesting here to make this visually more complicated than it is. Also the "thens", "Notes" and other connector words. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Rewrote |
||
and the property's `shouldInvalidate(value, oldValue)` returns true. | ||
* `invalidate()`: Updates the element after waiting a [microtask](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules/) (at the end | ||
of the event loop, before the next paint). | ||
* `shouldUpdate(changedProperties)`: The update proceeds if this returns true, which | ||
it does by default. | ||
* `update(changedProperties)`: Updates the element. Setting properties inside | ||
update is handled specially. Before calling `super.update()`, setting properties | ||
will *not* trigger an update. After calling `super.update()` setting properties will | ||
trigger an update. | ||
* `render()`: Returns a `lit-html` TemplateResult (e.g. <code>html\`Hello ${world}\`</code>) | ||
to render element DOM. Setting properties in `render()` does not trigger an update. | ||
* `firstRendered()`: Called after the DOM is rendered the first time. | ||
Setting properties in `firstRendered()` does trigger an update. | ||
* `updateComplete` promise is resolved with a boolean that is `true` if the | ||
element is not pending another update, and any code awaiting the element's | ||
`updateComplete` promise runs and observes the element in the updated state. | ||
|
||
## Bigger Example | ||
|
||
```JavaScript | ||
import {LitElement, html} from '@polymer/lit-element'; | ||
import {LitElement, html, property} from '@polymer/lit-element'; | ||
|
||
class MyElement extends LitElement { | ||
|
||
// Public property API that triggers re-render (synced with attributes) | ||
static get properties() { | ||
return { | ||
foo: String, | ||
whales: Number | ||
} | ||
} | ||
@property() | ||
foo = 'foo'; | ||
|
||
@property({type: Number}) | ||
whales = 5; | ||
|
||
constructor() { | ||
super(); | ||
this.foo = 'foo'; | ||
this.addEventListener('click', async (e) => { | ||
this.whales++; | ||
await this.renderComplete; | ||
await this.updateComplete; | ||
this.dispatchEvent(new CustomEvent('whales', {detail: {whales: this.whales}})) | ||
}); | ||
} | ||
|
||
// Render method should return a `TemplateResult` using the provided lit-html `html` tag function | ||
_render({foo, whales}) { | ||
render() { | ||
return html` | ||
<style> | ||
:host { | ||
|
@@ -170,8 +240,8 @@ class MyElement extends LitElement { | |
display: none; | ||
} | ||
</style> | ||
<h4>Foo: ${foo}</h4> | ||
<div>whales: ${'🐳'.repeat(whales)}</div> | ||
<h4>Foo: ${this.foo}</h4> | ||
<div>whales: ${'🐳'.repeat(this.whales)}</div> | ||
<slot></slot> | ||
`; | ||
} | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It can render into light DOM as well, so maybe clarify