lit · AndrewJakubowicz · May 15, 2023 · May 9, 2023 · May 10, 2023 · May 10, 2023
diff --git a/packages/lit-dev-content/.eleventy.js b/packages/lit-dev-content/.eleventy.js
@@ -445,6 +445,14 @@ ${content}
     });
   };
 
+  addApiShortcode(
+    'api-v3',
+    '/docs/v3/api',
+    JSON.parse(
+      fsSync.readFileSync('../lit-dev-api/api-data/lit-3/symbols.json', 'utf8')
+    )
+  );
+
   addApiShortcode(
     'api',
     '/docs/v2/api',

diff --git a/packages/lit-dev-content/site/_includes/default.html b/packages/lit-dev-content/site/_includes/default.html
@@ -28,8 +28,10 @@
     {% endif %}
     {% inlinejs "global/dsd-polyfill.js" %}
 
-    {% if selectedVersion !== latestVersion %}
+    {% if selectedVersion == "v1" %}
       <link rel="canonical" href="{{ versions[latestVersion].path }}/{{ versionLinks[latestVersion] }}">
+    {% endif %}
+    {% if selectedVersion !== latestVersion %}
       {% inlinejs "components/litdev-banner.js" %}
     {% endif %}
 
@@ -65,12 +67,17 @@
 
     {% include 'header.html' %}
 
-    {% if selectedVersion !== latestVersion %}
+    {% if selectedVersion !== latestVersion and selectedVersion !== "v3"  %}
       <litdev-banner>
         You're viewing docs for an older version of Lit. Click
         <a href="{{ versions[latestVersion].path }}/{{ versionLinks[latestVersion] }}">
         here</a> for the latest version.
       </litdev-banner>
+    {% elif selectedVersion === "v3" %}
+      <litdev-banner>
+        You're viewing docs for a pre-release version of Lit. Read the Lit 3.0 pre-releases
+        announcement <a href="/blog/2023-05-15-lit-3.0-prerelease/">here</a>.
+      </litdev-banner>
     {% endif %}
 
     <main {% if not page.url.includes('/docs/')

diff --git a/packages/lit-dev-content/site/blog/2023-05-15-lit-3.0-prerelease.md b/packages/lit-dev-content/site/blog/2023-05-15-lit-3.0-prerelease.md
@@ -0,0 +1,66 @@
+---
+tags: blogPosts
+layout: blog-post.html
+title: "Announcing Lit 3.0 Pre-releases"
+summary: "Get an early look at the upcoming Lit 3.0 release."
+date: 2023-05-15
+author:
+  - justin-fagnani
+---
+
+# Announcing Lit 3.0 Pre-releases
+
+The Lit team is excited to announce the first pre-releases of Lit 3.0!
+
+Lit 3.0 is our first major version since [introducing the unified Lit project and Lit 2.0](https://lit.dev/blog/2021-04-21-lit-2.0-meet-lit-all-over-again/) two years ago. We really value stability and backwards compatibility for our community, so we've focused on adding new features with minor versions of the core libraries and new labs packages, and not making any breaking changes.
+
+But the time is right for just a few breaking changes that will improve development velocity and testing stability on the core Lit project.
+
+## Changes
+
+Lit 3.0 adds no new features, because new features are generally not breaking changes and can be added in minor versions, according to semver. The Lit 3.0 release is an opportunity to make a few breaking changes that trim out some technical debt to unlock new features we have scheduled for our 3.x release series.
+
+The Lit 3.0 changes are mostly in browser support, removing deprecated APIs, and how packages are published. If you run Lit 2.x with no deprecation warnings, this should be a seamless upgrade!
+
+Here are the biggest things Lit 3.0 changes:
+- IE11 is no longer supported.
+- Lit's npm modules are now published as ES2021.
+- APIs deprecated during the Lit 1.x release timeframe have been removed.
+- SSR hydration support modules were moved to the `@lit-labs/ssr-client` package.
+
+A preview of the [Lit v2 to v3 upgrade guide](/docs/v3/releases/upgrade/) is available on the site.
+
+Detailed change logs can be found [on GitHub](https://github.com/lit/lit/releases?q=%22-pre.0%22&expanded=true).
+
+## Trying the Pre-releases
+
+We would love your help testing the new versions, to ensure a smooth upgrade process with the final releases. We're especially interested in making sure the new language version works with your toolchains. We expect some users may need to upgrade their tooling to the latest versions.
+
+You can try the pre-releases out by updating your package.json file to include the following:
+
+```json
+  "lit": "^3.0.0-pre.0"
+  "lit-html": "^3.0.0-pre.0"
+  "lit-element": "^4.0.0-pre.0"
+  "@lit/reactive-element": "^2.0.0-pre.0"
+```
+
+You can also use the `pre` npm tag, like `npm i lit@pre`.
+
+All other packages, like labs packages, have pre-release versions too that depend on the pre-release core libraries. If you depend on those you'll have to update them too. If you're more daring you can use npm overrides to select the pre-releases even for dependencies. This should work for most dependencies.
+
+Even if dependencies are using Lit 2.x, the good news is that Lit 2.x and Lit 3.x are interoperable, because:
+1. The inherent interoperability web components: components built with different libraries work together, including those build with different versions of Lit.
+2. We made interop of core features like templates and directives a priority for Lit 2. You can share templates, directives, decorators, etc., across Lit versions.
+
+## Docs
+
+We are preparing new docs for 3.0 on [lit.dev](https://lit.dev). Even though these will be mostly the same as 2.x, we are clarifying the browser and toolchain support, and want to make it easy to select the right docs set for the version you're using to enable future changes specific to to 3.x. At the 3.0 launch, we’ll archive the 2.x docs (but they will remain available in the doc version dropdown, as will 1.x). During the 3.0 pre-release phase, 2.x will remain the default, and you can select v3 from the dropdown next to the Documentation tab.
+
+## Feedback
+
+We hope you enjoy Lit 3.0! If you have questions or feedback, please let us know in [GitHub issues](https://github.com/lit/lit/issues) or on our [Lit and Friends Discord](https://lit.dev/discord/).
+
+**Thanks!,**
+
+**-The Lit Team**
diff --git a/packages/lit-dev-content/site/docs/v2/components/decorators.md b/packages/lit-dev-content/site/docs/v2/components/decorators.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 8
 versionLinks:
   v1: components/decorators/
+  v3: components/decorators/
 ---
 
 Decorators are special functions that can modify the behavior of classes, class methods, and class fields. Lit uses decorators to provide declarative APIs for things like registering elements, reactive properties, and queries.

diff --git a/packages/lit-dev-content/site/docs/v2/components/defining.md b/packages/lit-dev-content/site/docs/v2/components/defining.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 1
 versionLinks:
   v1: components/templates/
+  v3: components/defining/
 ---
 
 Define a Lit component by creating a class extending `LitElement` and registering your class with the browser:

diff --git a/packages/lit-dev-content/site/docs/v2/components/events.md b/packages/lit-dev-content/site/docs/v2/components/events.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 7
 versionLinks:
   v1: components/events/
+  v3: components/events/
 ---
 
 Events are the standard way that elements communicate changes. These changes typically occur due to user interaction. For example, a button dispatches a click event when a user clicks on it; an input dispatches a change event when the user enters a value in it.

diff --git a/packages/lit-dev-content/site/docs/v2/components/lifecycle.md b/packages/lit-dev-content/site/docs/v2/components/lifecycle.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 5
 versionLinks:
   v1: components/lifecycle/
+  v3: components/lifecycle/
 ---
 
 Lit components use the standard custom element lifecycle methods. In addition Lit introduces a reactive update cycle that renders changes to DOM when reactive properties change.

diff --git a/packages/lit-dev-content/site/docs/v2/components/overview.md b/packages/lit-dev-content/site/docs/v2/components/overview.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 0
 versionLinks:
   v1: components/templates/
+  v3: components/overview/
 ---
 
 A Lit component is a reusable piece of UI. You can think of a Lit component as a container that has some state and that displays a UI based on its state. It can also react to user input, fire events—anything you'd expect a UI component to do. And a Lit component is an HTML element, so it has all of the standard element APIs.

diff --git a/packages/lit-dev-content/site/docs/v2/components/properties.md b/packages/lit-dev-content/site/docs/v2/components/properties.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 3
 versionLinks:
   v1: components/properties/
+  v3: components/properties/
 ---
 
 Lit components receive input and store their state as JavaScript class fields or properties. *Reactive properties* are properties that can trigger the reactive update cycle when changed, re-rendering the component, and optionally be read or written to attributes.

diff --git a/packages/lit-dev-content/site/docs/v2/components/rendering.md b/packages/lit-dev-content/site/docs/v2/components/rendering.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 2
 versionLinks:
   v1: components/templates/
+  v3: components/rendering/
 ---
 
 Add a template to your component to define what it should render. Templates can include _expressions_, which are placeholders for dynamic content.

diff --git a/packages/lit-dev-content/site/docs/v2/components/shadow-dom.md b/packages/lit-dev-content/site/docs/v2/components/shadow-dom.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 6
 versionLinks:
   v1: components/templates/#accessing-nodes-in-the-shadow-dom
+  v3: components/shadow-dom/
 ---
 
 Lit components use [shadow DOM](https://developers.google.com/web/fundamentals/web-components/shadowdom) to encapsulate their DOM. Shadow DOM provides a way to add a separate isolated and encapsulated DOM tree to an element. DOM encapsulation is the key to unlocking interoperability with any other code—including other web components or Lit components—functioning on the page.

diff --git a/packages/lit-dev-content/site/docs/v2/components/styles.md b/packages/lit-dev-content/site/docs/v2/components/styles.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 4
 versionLinks:
   v1: components/styles/
+  v3: components/styles/
 ---
 
 Your component's template is rendered to its shadow root. The styles you add to your component are automatically _scoped_ to the shadow root and only affect elements in the component's shadow root.

diff --git a/packages/lit-dev-content/site/docs/v2/composition/component-composition.md b/packages/lit-dev-content/site/docs/v2/composition/component-composition.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   parent: Composition
   key: Component composition
   order: 2
+versionLinks:
+  v3: composition/component-composition/
 ---
 
 The most common way to handle complexity and factor Lit code into separate units is _component composition_: that is, the process of building a large, complex component out of smaller, simpler components. Imagine you've been tasked with implementing a screen of UI:

diff --git a/packages/lit-dev-content/site/docs/v2/composition/controllers.md b/packages/lit-dev-content/site/docs/v2/composition/controllers.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   parent: Composition
   key: Controllers
   order: 4
+versionLinks:
+  v3: composition/controllers/
 ---
 
 Lit 2 introduces a new concept for code reuse and composition called _reactive controllers_.

diff --git a/packages/lit-dev-content/site/docs/v2/composition/mixins.md b/packages/lit-dev-content/site/docs/v2/composition/mixins.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   parent: Composition
   key: Mixins
   order: 3
+versionLinks:
+  v3: composition/mixins/
 ---
 
 Class mixins are a pattern for sharing code between classes using standard JavaScript. As opposed to "has-a" composition patterns like [reactive

diff --git a/packages/lit-dev-content/site/docs/v2/composition/overview.md b/packages/lit-dev-content/site/docs/v2/composition/overview.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   parent: Composition
   key: Overview
   order: 1
+versionLinks:
+  v3: composition/overview/
 ---
 
 Composition is a strategy for managing complexity and organizing code into reusable pieces. Lit provides a few options for composition and code reuse:

diff --git a/packages/lit-dev-content/site/docs/v2/data/context.md b/packages/lit-dev-content/site/docs/v2/data/context.md
@@ -5,6 +5,8 @@ eleventyNavigation:
   parent: Managing Data
   order: 1
   labs: true
+versionLinks:
+  v3: data/context/
 ---
 
 {% labs-disclaimer %}

diff --git a/packages/lit-dev-content/site/docs/v2/frameworks/react.md b/packages/lit-dev-content/site/docs/v2/frameworks/react.md
@@ -5,6 +5,8 @@ eleventyNavigation:
   parent: Frameworks
   order: 1
   labs: true
+versionLinks:
+  v3: frameworks/react/
 ---
 
 {% labs-disclaimer %}

diff --git a/packages/lit-dev-content/site/docs/v2/getting-started.md b/packages/lit-dev-content/site/docs/v2/getting-started.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 3
 versionLinks:
   v1: getting-started/
+  v3: getting-started/
 ---
 
 There are many ways to get started using Lit, from our Playground and interactive tutorial to installing into an existing project.

diff --git a/packages/lit-dev-content/site/docs/v2/index.md b/packages/lit-dev-content/site/docs/v2/index.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 1
 versionLinks:
   v1:
+  v3:
 ---
 
 ![Lit Logo]({{ site.baseurl }}/images/logo.svg){.logo width="425" height="200"}

diff --git a/packages/lit-dev-content/site/docs/v2/libraries/labs.md b/packages/lit-dev-content/site/docs/v2/libraries/labs.md
@@ -5,6 +5,8 @@ eleventyNavigation:
   parent: Related libraries
   order: 3
   labs: true
+versionLinks:
+  v3: libraries/labs/
 ---
 
 Lit Labs is an umbrella for Lit packages under development that we are actively seeking feedback on. While we encourage real-world use in order to help the feedback process, please note:

diff --git a/packages/lit-dev-content/site/docs/v2/libraries/standalone-templates.md b/packages/lit-dev-content/site/docs/v2/libraries/standalone-templates.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Standalone lit-html
   parent: Related libraries
   order: 1
+versionLinks:
+  v3: libraries/standalone-templates/
 ---
 
 Lit combines the component model of LitElement with JavaScript template literal-based rendering into an easy-to-use package. However, the templating portion of Lit is factored into a standalone library called `lit-html`, which can be used outside of the Lit component model anywhere you need to efficiently render and update HTML.

diff --git a/packages/lit-dev-content/site/docs/v2/localization/best-practices.md b/packages/lit-dev-content/site/docs/v2/localization/best-practices.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Best practices
   parent: Localization
   order: 5
+versionLinks:
+  v3: localization/best-practices/
 ---
 
 

diff --git a/packages/lit-dev-content/site/docs/v2/localization/cli-and-config.md b/packages/lit-dev-content/site/docs/v2/localization/cli-and-config.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: CLI and config
   parent: Localization
   order: 4
+versionLinks:
+  v3: localization/cli-and-config/
 ---
 
 ## CLI

diff --git a/packages/lit-dev-content/site/docs/v2/localization/overview.md b/packages/lit-dev-content/site/docs/v2/localization/overview.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Overview
   parent: Localization
   order: 1
+versionLinks:
+  v3: localization/overview/
 ---
 
 Localization is the process of supporting multiple languages and regions in your

diff --git a/packages/lit-dev-content/site/docs/v2/localization/runtime-mode.md b/packages/lit-dev-content/site/docs/v2/localization/runtime-mode.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Runtime mode
   parent: Localization
   order: 2
+versionLinks:
+  v3: localization/runtime-mode/
 ---
 
 In Lit Localize runtime mode, one JavaScript or TypeScript module is generated

diff --git a/packages/lit-dev-content/site/docs/v2/localization/transform-mode.md b/packages/lit-dev-content/site/docs/v2/localization/transform-mode.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Transform mode
   parent: Localization
   order: 3
+versionLinks:
+  v3: localization/transform-mode/
 ---
 
 In Lit Localize transform mode, a separate folder is generated for each locale.

diff --git a/packages/lit-dev-content/site/docs/v2/releases/upgrade.md b/packages/lit-dev-content/site/docs/v2/releases/upgrade.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Upgrade guide
   parent: Releases
   order: 3
+versionLinks:
+  v3: releases/upgrade/
 ---
 
 ## Overview

diff --git a/packages/lit-dev-content/site/docs/v2/resources/community.md b/packages/lit-dev-content/site/docs/v2/resources/community.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 1
 versionLinks:
   v1: resources/community/
+  v3: resources/community/
 ---
 
 There are many great resources and locations to learn about Lit,

diff --git a/packages/lit-dev-content/site/docs/v2/ssr/authoring.md b/packages/lit-dev-content/site/docs/v2/ssr/authoring.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Authoring components
   parent: Server rendering
   order: 4
+versionLinks:
+  v3: ssr/authoring/
 ---
 
 {% labs-disclaimer %}

diff --git a/packages/lit-dev-content/site/docs/v2/ssr/client-usage.md b/packages/lit-dev-content/site/docs/v2/ssr/client-usage.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Client usage
   parent: Server rendering
   order: 3
+versionLinks:
+  v3: ssr/client-usage/
 ---
 
 {% labs-disclaimer %}

diff --git a/packages/lit-dev-content/site/docs/v2/ssr/dom-emulation.md b/packages/lit-dev-content/site/docs/v2/ssr/dom-emulation.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: DOM emulation
   parent: Server rendering
   order: 5
+versionLinks:
+  v3: ssr/dom-emulation/
 ---
 
 {% labs-disclaimer %}

diff --git a/packages/lit-dev-content/site/docs/v2/ssr/overview.md b/packages/lit-dev-content/site/docs/v2/ssr/overview.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Overview
   parent: Server rendering
   order: 1
+versionLinks:
+  v3: ssr/overview/
 ---
 
 {% labs-disclaimer %}

diff --git a/packages/lit-dev-content/site/docs/v2/ssr/server-usage.md b/packages/lit-dev-content/site/docs/v2/ssr/server-usage.md
@@ -4,6 +4,8 @@ eleventyNavigation:
   key: Server usage
   parent: Server rendering
   order: 2
+versionLinks:
+  v3: ssr/server-usage/
 ---
 
 {% labs-disclaimer %}

diff --git a/packages/lit-dev-content/site/docs/v2/templates/conditionals.md b/packages/lit-dev-content/site/docs/v2/templates/conditionals.md
@@ -6,6 +6,7 @@ eleventyNavigation:
   order: 3
 versionLinks:
   v1: components/templates/#use-properties-loops-and-conditionals-in-a-template
+  v3: templates/conditionals/
 ---
 
 Since Lit leverages normal Javascript expressions, you can use standard Javascript control flow constructs like [conditional operators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator), function calls, and `if` or `switch` statements to render conditional content.

diff --git a/packages/lit-dev-content/site/docs/v2/templates/custom-directives.md b/packages/lit-dev-content/site/docs/v2/templates/custom-directives.md
@@ -7,6 +7,7 @@ eleventyNavigation:
   order: 6
 versionLinks:
   v1: lit-html/creating-directives/
+  v3: templates/custom-directives/
 ---
 
 Directives are functions that can extend Lit by customizing how a template expression renders. Directives are useful and powerful because they can be stateful, access the DOM, be notified when templates are disconnected and reconnected, and independently update expressions outside of a render call.
-Original file line number
+Diff line change
@@ Expand Up / @@ -6,6 +6,7 @@ eleventyNavigation: @@
       order: 1
     versionLinks:
       v1:
+      v3:
     ---
     ![Lit Logo]({{ site.baseurl }}/images/logo.svg){.logo width="425" height="200"}
@@ Expand Down @@