Flip site to v3 as the latest Lit version

packages/lit-dev-content/samples/base.json

@@ -1,3 +1,3 @@
 {
-  "extends": "/samples/v2-base.json"
+  "extends": "/samples/v3-base.json"
 }

packages/lit-dev-content/site/_includes/default.html

@@ -67,17 +67,12 @@
 
     {% include 'header.html' %}
 
-    {% if selectedVersion !== latestVersion and selectedVersion !== "v3"  %}
+    {% if selectedVersion !== latestVersion %}
       <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-09-27-lit-3.0-prerelease-2/">here</a>.
-      </litdev-banner>
     {% endif %}
 
     <main {% if not page.url.includes('/docs/')

packages/lit-dev-content/site/blog/2023-10-10-lit-3.0.md

@@ -0,0 +1,175 @@
+---
+tags: blogPosts
+layout: blog-post.html
+title: "Lit Launch Day: Lit 3.0, Labs graduations, a compiler and more!"
+summary: "We're launching the next major version of Lit"
+date: 2023-10-10
+author:
+  - lit-team
+---
+
+# Lit Launch Day: Lit 3.0, Labs graduations, a compiler and more!
+
+It's launch day for the Lit team, and we have a bunch of exciting releases to share with the Lit and web components communities!
+
+After several months of development, the Lit team is happy to announce the final release of Lit 3.0 - our fist major version since Lit 2.0 in early 2021 - the first graduating class of Lit Labs packages: `@lit/react`, `@lit/task`, and `@lit/context`, and two bonus releases `@lit-labs/compiler` and `@lit-labs/preact-signals`.
+
+This is a big release, so here are links to the individual announcements:
+- [Lit 3.0](#lit-3.0)
+- [The New Lit Template Compiler](#compiler)
+- [Labs Graduation Day](#labs-graduation)
+- [Preact Signals Integration](#preact-signals)
+
+## Lit 3.0: Bye, Bye IE, Hello TC39 Decorators! { #lit-3.0 }
+
+We value stability for our community. Breaking changes are a cost that every user and the entire ecosystem has to bear: projects have to upgrade, multiple versions can be included in an app, and documents, samples, tutorials, starter kits, etc. have to be updated for every breaking change.
+
+So we want to only make breaking changes when we must, or when the benefits to the community clearly outweigh the costs. For benefits we tend look for decreased code size, increased performance, reduction in maintenance burden, and better alignment with standards.
+
+For Lit 3.0, the biggest change is that we've dropped IE11 support. After surveying our developer community, we feel like now is the right time to say goodbye to IE, and very few customers will be affected.
+
+### Breaking 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 with the Lit 2.0 release have been removed.
+- SSR hydration support modules were moved to the `@lit-labs/ssr-client` package.
+- Decorator behavior has been unified between TypeScript experimental decorators and standard decorators.
+
+### Standard Decorators
+
+
+
+### Upgrading
+
+The upgrade from Lit 2.0 should be seamless for the vast majority of users. You can usually upgrade your npm dependency version with:
+
+```sh
+> npm i lit@latest
+```
+
+You can find more details and how to handle the changes in the [Lit 3 upgrade guide](/docs/v3/releases/upgrade/).
+
+Detailed change logs can be found [on GitHub](https://github.com/lit/lit/releases?q=%22-pre.1%22&expanded=true).
+
+## Even Faster Rendering with the new Lit Template Compiler { #compiler }
+
+The Lit team is excited to announce a new Labs package [`@lit-labs/compiler`](https://www.npmjs.com/package/@lit-labs/compiler), which provides a [TypeScript Transformer](https://github.com/itsdouges/typescript-transformer-handbook#the-basics) that can be run over your JavaScript or TypeScript files to optimize away some of the work that Lit would have to do at runtime!
+
+![Lit Compiler benchmarks](/images/blog/3.0-launch/compiler-benchmarks.png)
+
+In a best case scenario with a template heavy page, we measured a 46% faster first render, and a 21% faster update!
+
+To try out `@lit-labs/compiler` today, you’ll need a build step that accepts a TypeScript transformer. For Rollup.js users, this could be `@rollup/plugin-typescript`. An example `rollup.config.js`  file might look like:
+
+```js
+// File: rollup.config.js
+import typescript from '@rollup/plugin-typescript';
+import {compileLitTemplates} from '@lit-labs/compiler';
+
+export default {
+  // ...
+  plugins: [
+    typescript({
+      transformers: {
+        before: [compileLitTemplates()],
+      },
+    }),
+    // other rollup plugins
+  ],
+};
+```
+
+### What does the transform do?
+
+Given some source code containing an `html` tag function to declare templates:
+
+```ts
+const hi = (name) => html`<h1>Hello ${name}!</h1>`;
+```
+
+The Lit template transform will remove the html tag function and replace it with something similar to the following:
+
+```ts
+const b = (s) => s;
+const lit_template_1 = {h: b`<h1>Hello <?></h1>`, parts: [{type: 2, index: 1}]};
+const hi = (name) => ({_$litType$: lit_template_1, values: [name]});
+```
+
+We call this a compiled template, and it behaves the same as your authored template, except that when Lit renders the compiled template,
+Lit can skip an internal render phase called the Prepare phase, meaning you get a quicker initial render.
+
+As you can see in the above example, there is some additional code generated as part of the transform. We’ve measured that minified and compressed, you may get a 5% increase in file size for the compiled file. This is something we have plans to address.
+
+### Looking forward
+
+We’d love to hear from you and get feedback on your experience using the transform, as well as hear what you’d like to see optimized! Leave that feedback in this [Labs Feedback discussion](https://github.com/lit/lit/discussions/4117). We’d also like to learn more about what build systems Lit is used in, and welcome contributions!
+
+This is just the beginning. With this new package we have a foundation for layering on additional build-time optimizations. Some optimizations we’ve thought about:
+
+- For a Lit app which can be completely compiled, we could vend an import of lit-html that is smaller.
+- Add an option to the compiler transform to also minify the HTML in the templates.
+- Provide domain specific and targeted transforms, such as a standard decorator transform with a smaller emit.
+- Compress the emitted output file by applying domain specific file compression.
+
+
+## Lit Labs Graduation Day { #labs-graduation }
+
+We are also graduating our first set of Lit Labs packages: Context, Task, and React.
+
+These packages have a new home in the `@lit` npm scope, but are otherwise exactly the same as the current labs versions. The labs packages have been updated to depend on and re-export the non-labs versions so that they share a single implementation.
+
+Find them in their new npm homes:
+[`@lit/react`](https://www.npmjs.com/package/@lit/react),
+[`@lit/task`](https://www.npmjs.com/package/@lit/task), and
+[`@lit/context`](https://www.npmjs.com/package/@lit/context)
+
+These packages can now be considered stable, and have documentation and examples on lit.dev!
+
+Current users of these packages under the `@lit-labs` scope can migrate by first updating to the latest version of those packages to test for any breakages, then update the import to use the `@lit` scoped package. The latest `@lit-labs` scoped packages will receive the same updates until the next major version of the `@lit` scoped package.
+
+Thank you so much to everyone in the community who has tested out a Labs package, filed issues, discussed features, and led these packages to graduation! 🎓
+
+### React
+
+While custom elements can be used in React projects as is, there are some rough edges around their usage, namely:
+- Setting properties on elements (rather than attributes)
+- Adding handlers for custom events
+- Type checking custom elements and their props
+
+Some of these are being addressed by React in a future version, but they are currently only present in experimental builds not recommended for production.
+
+`@lit/react` allows creation of React components wrapping the custom element. The created components can be idiomatic to React such that users of the component do not have to worry about the inner web component implementaion.
+
+It is useful for both web component authors who wish to vend React versions of their components for users to reach a wider audience, as well as React developers who wish to use a neat web component that they found in their project more ergonomically.
+
+`@lit-labs/react` has been our most popular labs project by far with over 500k weekly npm downloads and is already being used by many web component libraries to provide React versions of their components to users.
+
+Read more about it at our [React framework integration](/docs/frameworks/react) documentation.
+
+### Task
+
+Rendering asynchronously retrieved data in a Lit component, while not terribly difficult to do, can involve a lot of boiler plate code to do properly with all the edge cases to handle.
+
+Some considerations include:
+- Conditionally rendering different content while the data is pending, retrieved, or the request failed
+- Handling race conditions, ensuring the data for the latest request is kept and previous requests are cancelled or ignored if completed later
+
+`@lit/task` provides a reactive controller to help manage this async workflow.
+
+We've found ourselves, on numerous occasions, starting a barebones example with asynchronous requests and quickly reaching to `@lit-labs/task` for its convenience. We've refined the API and added features like providing an `AbortSignal` while the project was being developed under labs. We are happy to officially graduate and encourage everyone to use it!
+
+Checkout the details with examples and various usages in the [Async Tasks](/docs/data/task/) documentation.
+
+### Context
+
+## Preact Signals Integration { #preact-signals }
+
+**Thanks!,**
+
+**-The Lit Team**

packages/lit-dev-content/site/docs/v2/v2.json

@@ -1,3 +1,4 @@
 {
-  "collection": "docs-v2"
+  "collection": "docs-v2",
+  "selectedVersion": "v2"
 }

packages/lit-dev-content/site/home/1-splash.html

@@ -1,5 +1,5 @@
 <section id="new-banner">
-  <p><span class="emoji">📣</span> Have a question, or looking to chat? Join our <a href="{{site.baseurl}}/discord/">Discord server!</a></p>
+  <p><span class="emoji">📣</span> Lit 3 just landed! Check out the <a href="/blog/2023-10-10-lit-3.0/">Lit 3 release announcement!</a></p>
 </section>
 <section id="intro">
   <div id="splashLogo" role="heading" aria-level="1">

packages/lit-dev-content/site/site.json

@@ -1,13 +1,13 @@
 {
-  "selectedVersion": "v2",
-  "latestVersion": "v2",
+  "selectedVersion": "v3",
+  "latestVersion": "v3",
   "versions": {
     "v3": {
-      "path": "/docs/v3",
+      "path": "/docs",
       "label": "v3"
     },
     "v2": {
-      "path": "/docs",
+      "path": "/docs/v2",
       "label": "v2"
     },
     "v1": {

packages/lit-dev-server/src/redirects.ts

@@ -12,26 +12,29 @@ export const pageRedirects = new Map([
   ['/msg/dev-mode',                   '/docs/tools/development/#development-and-production-builds'],
   // TODO(sorvell) https://github.com/lit/lit.dev/issues/455
   ['/msg/multiple-versions',          '/docs/tools/requirements/'],
-  ['/msg/polyfill-support-missing',   '/docs/tools/requirements/#polyfills'],
+  ['/msg/polyfill-support-missing',   '/docs/v2/tools/requirements/#polyfills'],
   ['/msg/class-field-shadowing',      '/docs/components/properties/#avoiding-issues-with-class-fields'],
   // TODO(aomarks) Should we add something specifically about this issue?
   ['/msg/change-in-update',           '/docs/components/properties/#when-properties-change'],
-  ['/msg/deprecated-import-path',     '/docs/releases/upgrade/#update-packages-and-import-paths'],
-  ['/msg/removed-api',                '/docs/releases/upgrade/#litelement'],
-  ['/msg/renamed-api',                '/docs/releases/upgrade/#update-to-renamed-apis'],
-  ['/msg/undefined-attribute-value',  '/docs/releases/upgrade/#litelement'],
-  ['/msg/request-update-promise',     '/docs/releases/upgrade/#litelement'],
+  ['/msg/deprecated-import-path',     '/docs/v2/releases/upgrade/#update-packages-and-import-paths'],
+  ['/msg/removed-api',                '/docs/v2/releases/upgrade/#litelement'],
+  ['/msg/renamed-api',                '/docs/v2/releases/upgrade/#update-to-renamed-apis'],
+  ['/msg/undefined-attribute-value',  '/docs/v2/releases/upgrade/#litelement'],
+  ['/msg/request-update-promise',     '/docs/v2/releases/upgrade/#litelement'],
   ['/msg/expression-in-template',     '/docs/templates/expressions/#invalid-locations'],
   ['/msg/expression-in-textarea',     '/docs/templates/expressions/#invalid-locations'],
   // Relocated pages
   ['/docs/libraries/localization',    '/docs/localization/overview/'],
   ['/blog/feed.xml',                  '/blog/atom.xml'],
   // Urls not ending with '/' violate CSP policies.
-  ['/docs/releases/release-notes/1.3.0.html', '/docs/releases/release-notes/1.3.0/'],
-  ['/docs/releases/release-notes/1.2.0.html', '/docs/releases/release-notes/1.2.0/'],
+  ['/docs/releases/release-notes/1.3.0.html', '/docs/v2/releases/release-notes/1.3.0/'],
+  ['/docs/releases/release-notes/1.2.0.html', '/docs/v2/releases/release-notes/1.2.0/'],
   // `.0` is treated as a file extension, ensure it resolves correctly.
-  ['/docs/releases/release-notes/1.3.0',      '/docs/releases/release-notes/1.3.0/'],
-  ['/docs/releases/release-notes/1.2.0',      '/docs/releases/release-notes/1.2.0/'],
+  ['/docs/releases/release-notes/1.3.0',      '/docs/v2/releases/release-notes/1.3.0/'],
+  ['/docs/releases/release-notes/1.2.0',      '/docs/v2/releases/release-notes/1.2.0/'],
+  // Old release-notes redirects to new v2 location.
+  ['/docs/releases/release-notes/1.3.0/',      '/docs/v2/releases/release-notes/1.3.0/'],
+  ['/docs/releases/release-notes/1.2.0/',      '/docs/v2/releases/release-notes/1.2.0/'],
   // Old Lit tutorial redirect to new tutorial catalog
   ['/tutorial/', '/tutorials/'],
 ].map(([path, redir]) => [

packages/lit-dev-tests/known-good-urls.txt

@@ -497,3 +497,20 @@ https://docs.astro.build/en/guides/integrations-guide/lit/
 https://rocket.modern-web.dev/
 https://stackblitz.com/edit/lit-ssr-global?file=src/server.js
 https://twitter.com/techytacos
+https://github.com/itsdouges/typescript-transformer-handbook#the-basics
+https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
+https://developer.mozilla.org/en-US/docs/Glossary/Primitive
+https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing_operator
+https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/extends#mix-ins
+https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md
+https://www.w3.org/community/webcomponents/
+https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+https://developer.mozilla.org/en-US/docs/Web/API/AbortController
+https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+https://developer.mozilla.org/en-US/docs/Web/API/fetch
+https://developer.mozilla.org/en-US/docs/Web/CSS/display#box
+https://github.com/google/safe-html-types/blob/master/doc/safehtml-types.md
+https://devblogs.microsoft.com/typescript/announcing-typescript-5-2/#decorator-metadata
+https://preactjs.com/guide/v10/signals/
+https://www.youtube.com/watch?v=l6Gn5uV83sw
+https://github.com/e111077

packages/lit-dev-tests/src/playwright/components-styles.spec.ts

@@ -19,15 +19,15 @@ test.describe('docs/components/styles', () => {
 
     // Wait for the exact playground preview we want to load.
     await page.waitForSelector(
-      'litdev-example[project="v2-docs/components/style/superstyles"] playground-preview [part="preview-loading-indicator"][aria-hidden="true"]'
+      'litdev-example[project="v3-docs/components/style/superstyles"] playground-preview [part="preview-loading-indicator"][aria-hidden="true"]'
     );
     // Wait for the loading bar to fade out.
     await page.waitForTimeout(250);
 
     await expect(
       await page
         .locator(
-          'litdev-example[project="v2-docs/components/style/superstyles"] playground-preview'
+          'litdev-example[project="v3-docs/components/style/superstyles"] playground-preview'
         )
         .screenshot()
     ).toMatchSnapshot('inheritingStylesPlaygroundPreview.png');

packages/lit-dev-tools-esm/src/build-unversioned-docs.ts

@@ -15,7 +15,7 @@ const CONTENT_PKG = pathlib.resolve(REPO_ROOT, 'packages', 'lit-dev-content');
 const SITE_JSON = pathlib.resolve(CONTENT_PKG, 'site', 'site.json');
 
 interface SiteJSON {
-  latestVersion: 'v1' | 'v2';
+  latestVersion: 'v1' | 'v2' | 'v3';
 }
 
 type EleventyFrontMatterData = string[];
@@ -44,7 +44,7 @@ const UNVERSIONED_VERSION_LOCATION = pathlib.resolve(
  *
  * The following transforms are then applied on the files:
  *   - Permalink frontmatter is added to strip the version from the URL. E.g.,
- *     /docs/v2/* becomes /docs/*.
+ *     /docs/v3/* becomes /docs/*.
  *  - `api.html` has frontmatter transformed so base api paths become
  *    unversioned.
  *  - The latest version `v[N].json` file is renamed `unversioned.json` so it