I've made several checks with method shouldUpdate, and property changes inside this method do not trigger an element update, but the parameter changedProperties itself of shouldUpdate is updated synchronously in the same element update.

So I think the field "Updates?" of this method in this doc is wrong. It should says:

Updates? | No | Property changes inside this method will not trigger an element update.

To match our current outline, I'd like to omit link for the directories themselves.

I did this by replacing the index.md in a given directory with a stub that contains only metadata, and rewriting the nav template like this:

      <side-nav>
        {%- set navSections = collections.guide | eleventyNavigation -%}
        {# Uncomment to use prebuilt nav
        {{ navSections | eleventyNavigationToHtml | safe }}
        #}
        <ul>
        {%- for entry in navSections %}
          <li{% if entry.url == page.url %} class="my-active-class"{% endif %}>
            {%- if entry.children | length %}
              <span class="sectionHead">{{ entry.title }}</span>
              {% set navPages = entry.children %}
              <ul>
              {%- for entry in navPages %}
                <li{% if entry.url == page.url %} class="my-active-class"{% endif %}>
                  <a href="{{ entry.url | url }}">{{ entry.title }}</a>
                </li>
              {%- endfor %}
              </ul>  
            {%- else %}
              <a href="{{ entry.url | url }}">{{ entry.title }}</a>
            {%- endif %}
          </li>
        {%- endfor %}
        </ul>
      </side-nav>

Not sure if there's a simpler way to do this.

This has recently broken

E.g. playground.lit.dev

Prove out an inline + editable documentation code snippet, where the preview renders below the code.

There are some janky things about the site right now in terms of layout and nav. Do a minimal pass through to make things more reasonable.

Description

An expression in the child position (aka text position) can return a node or iterable of nodes, something that can be used to integrate the output of other libraries into a Lit template. We don't really cover this at the moment.

Acceptance criteria

Section on working with other libraries that describes, at minimum, using child position expressions to inject nodes into the templated DOM.

Remove concepts doc for now

Maybe add to a new how-it-works section, combined with content from the wiki as well as LitElement content.

https://github.com/Polymer/lit-html/wiki/How-it-Works

Initiative / goal

We now have the lit-html.com domain!
It doesn't point anywhere :/

Scope

Figure out DNS settings to redirect to the current docs site

Acceptance criteria and must have scope

Typing lit-html.com into a browser redirects to the current docs site

Some documentation about what common security issues to be aware of, would be a nice addition

Originally posted by @kenchris in lit/lit-element#474 (comment)

This could be on the home page, introduction, concepts, or all of the above.

Similar to: https://reactjs.org/docs/rendering-elements.html#react-only-updates-whats-necessary

Add a LHS drawer to the playground page with a gallery of examples (similar to https://svelte.dev/examples, but with the playground + examples combined into one page).

Description

• For consistency with lit-html docs.

Acceptance criteria

• Individual pages per-release (for example, /guide/release-notes/2.4.0.html)
• Summary page collecting all release notes. (for example, /guides/release-notes.html) release
• Only document releases going forward; for older releases, we can point to the changelog.

This is placeholder content, need to decide what exactly we want to say here.

Deploying via cloud build/cloud run seems pretty broken. At the moment, cloud build is timing out with no useful error message, while the local lerna build works fine.

Even when it works, it's slower and less intuitive than working with App Engine.

Users shouldn't need to do much if they know how to enable it, but we should at least list this as a feature.

Description

When you rely on an asynchrounous task to complete, if an earlier asynchronous task completes after its next iteration, you get the result of the first task instead of the last.

Steps to Reproduce

1. Use a directive that updates the value in a relatively long time.
2. Update the rendering, making the directive fire again but this time faster.

The same happen if you render something else afterward, your new value is overridden.

Live Reproduction Link

https://stackblitz.com/edit/lit-html-jdv5ml?file=src%2Findex.js

Actual Results

The result from the last directive call show up but shortly after the result from the first directive call show up.

Expected Results

This code obviously miss some order or cancellation management. I do not expect it to work as is.
Should this library support also a conditional rendering at this point ?
A solution would be a pattern to use to fix this behaviour and maybe extend the documentation on Asynchronous Directives

An other solution would be to use a central model such as redux but this would imply a big change to my application that I would better avoid if possible.

Previously LitElement's polyfill support was built in. Now it's opt-in via the platform-support module. Docs should be added for this.

There are platform-support modules in:

• updating-element
• lit-html
• lit-element (includes updating-element and lit-html's platform-support modules)

The idea is that platform-support should be loaded right after loading the webcomponents polyfills.

The default playground theme is a bit drab looking, and doesn't even include colors for a few tokens. Choose a nicer theme for lit.dev, and maybe make it the default playground theme too.

Edit for consistency.
Review for technical accuracy, make any updates required for Lit.

• Add intro, explaining that lit-html can be used independently of web components or LitElement to render DOM anywhere in the page.

• Fill in missing content. In particular, probably restructure a bit to clarify where the context comes from when using lit-html standalone, and how the examples differ from the LitElement based examples.

• Edit & clean up.

• A way to declare redirects for future document moves
• Fragment redirects somehow?
• Redirects from old site to new site

Currently the docs say things like, "When you call render, lit-html only updates the parts of the template that have changed since the last render. This makes lit-html updates very fast."

But they don't say explicitly how this happens. In particular, that lit keeps track of the current value at each binding site (aka "hole in the DOM", aka Part). On render, it compares the new value with the current rendered value, and only re-renders if they're different.

The live() directive is designed to apply different change detection logic (against the live DOM value, instead of the value that lit rendered).

We should be able to preserve docs for each release, and plan for the future with docs in multiple languages. URLs would end up looking like https://polymer.github.io/lit-html/en/1.0/guide or https://polymer.github.io/lit-html/en/latest/guide.

Restructure to place TypeScript/decorators examples first, show JavaScript as an option.

When I was demoing the site today, I realized the alert styles were missing.

It looks like they got dropped as part of one of the big clean-ups:

https://github.com/PolymerLabs/lit.dev/pull/37/files#diff-3b9e86ecc61632ab075bd985e7366ae7f4c151634f65e5e0c100a03383661cb4L288

If that link doesn't work right... Starting on L288 of main.css in that PR, you can see the deleted styles. We need to put these back--not sure if they should go in main.css or guide.css, though. (We use them in both the guides and the tutorial typically, if that helps--although I'm not sure whether that will make sense with the new tutorial format.

Another general design request for post-1.0: I'd like to provide a feedback mechanism. We can easily put one at the bottom of the page, but since some of our pages are quite long, having a "was this page helpful" button at the very end isn't perfect.

Old Polymer site had "Edit on GitHub" buttons, which were nice, but much higher friction, since users had to have a GitHub account, be willing to click through and create a PR, instead of just commenting anonymously.

Options include:

• A sticky footer (see the Sentry docs.
• Something attached to the header.
• A small feedback tab on the side that opens an overlay. I'm not saying this well, but I've seen that implemented somewhere, too.

Information to collect:
Was this page helpful to you? [Yes] {No]
[If no] Comment [ ]
Could also offer "Edit on GitHub" or "Open an Issue" as options.

Currently, the Try LitElement tutorial is only available as StackBlitz examples.

Provide a way for people to do the tutorial and work locally. E.g. put the Try samples on GitHub and provide instructions for doing the tutorial with Polymer CLI

Comments from #14, to handle after larger reorgs are done:

"Since "tag" is used to refer to HTML tags too, do we want to clarify that html is a "template literal tag" the first time we use it? I know that could be a lot of "tagged template literal tagged with the template literal tag" and such... so maybe not a great idea. Maybe there's a way to work the full phrase "tagged template literal" in there. Also thinking if we should emphasize that this is standard plain JS, considering how many other frameworks use some fork of JS.

And should we have a link to MDN on tagged template literals, or would we lose readers to the hyperlink void that way?"

"We don't mention that html is a function prior to this, we just call it a tag, so this could be a bit too much detail on that aspect. Could we say something around a lit-html template being an expression that returns a value that can be stored in variables, passed to and from functions, etc? I think JSX or React docs go into this a bit, for comparison."

"Rather than the specifics of the browser passing things to a tag function, we could describe the end result which is that the html tag captures the template strings and expression values separately, so that on repeated renders is can update only the expressions that changed.

One specific thing I have in mind there is around "re-render only the parts of template that have changed." - depending on our semantics here, the "template" doesn't change, only the values passed to it do. So we could lean more on saying we only update the expressions that change."

When lit/lit-element#607 is merged, the updateComplete promise will be able to be rejected. We need to add documentation explaining that these exceptions need to be handled in any code that awaits the updateComplete promise. This might go in the promises section of the lifecycle.

Edit and make sure language is consistent.
Make samples runnable?

Rumor has it the typescript worker is having some trouble getting served? Need to investigate.

Template currently applies .my-active-class to the active link in the left nav. Need to add something to the CSS to highlight it.

Description

In this article, it mentions that 'lit-html' includes XSS-prevention. That's what lead me to this library.
https://benfrain.com/html-templating-with-vanilla-javascript-es2015-template-literals/

Naturally, I wanted to verify that before using lit-html so I searched for 'escape' and 'XSS' in the documentation, but I wasn't able to find any mention of that functionality anywhere.

By trial and error, I found out that lit-html automatically removes <script></script> tags when using the html tagged template literal.

I also could not find info about the unsafeHTML directive in the docs although it is included in the source code.

Decide if this content goes here or on the main landing page.
Conclusion: probably OK to go here.
Even if it covers similar ground, it'll be in a different form.
Write content.

By default eleventy adds a slash after filenames, but allows users to access the path without the slash. This results in relative URLs failing in some cases.

We need to pick a scheme and possibly add a redirect handler to rewrite the non-canonical form.

I prefer not adding the slash, because it's easier to write hrefs correctly when they match the file system. (When adding the slash, a sibling link from guides/foo to guides/bar needs to be written as ../bar/ instead of just bar.)

Is there any plan to create a component migration guide from PolymerElement to LitElement

We seem to have lost the CSS that formats alerts (aka notes, warnings, "pretty boxes," or asides).