Add more details to the TypeScript docs

packages/lit-dev-content/site/css/global.css

@@ -80,3 +80,13 @@ a {
   height: 1px;
   overflow: hidden;
 }
+
+body[code-language-preference="ts"] [code-language]:not([code-language="ts"]) {
+  /* Hide JS content when preference is TS. */
+  display: none;
+}
+
+body[code-language-preference="js"] [code-language]:not([code-language="js"]) {
+  /* Hide TS content when preference is JS. */
+  display: none;
+}

packages/lit-dev-content/site/docs/v3/components/overview.md

@@ -26,3 +26,15 @@ Creating a Lit component involves a number of concepts:
 Here's a sample component:
 
 {% playground-example "v3-docs/components/overview/simple-greeting" "simple-greeting.ts" %}
+
+<div code-language="ts">
+
+{% aside "info"%}
+
+This example uses TypeScript decorators.
+
+See the [Decorators](/docs/v3/components/decorators) documentation for more information on configuring TypeScript for decorators.
+
+{% endaside %}
+
+</div>

packages/lit-dev-content/site/docs/v3/tools/development.md

@@ -202,12 +202,23 @@ For full installation and usage instructions, see the [Web Dev Server documentat
 
 ## TypeScript { #typescript }
 
-TypeScript extends the Javascript language by adding support for types. Types are useful for catching errors early and making code more readable and understandable.
+Lit support developing components in TypeScript, including full type declarations for the Lit APIs, standard and experimental decorators, and community tools for template type-checking and linting.
+
+Because Lit is just a library, and doesn't require a compiler or use non-standard langauge syntax, there are no specific TypeScript tools that are required. Lit works with the official TypeScript compiler, `tsc`, with TypeScript wrappers such as those for Rollup, Vite, or Webpack, and alternate compilers like `esbuild`.
+
+The main requirements of a TypeScript project are:
+- Enabling a modern JavaScript language level, like with the `"ES2021"` [lib](https://www.typescriptlang.org/tsconfig/#lib).
+- Enabling the DOM types with the `"DOM"` [lib](https://www.typescriptlang.org/tsconfig/#lib).
+- Optionally [enabling experimental decorators](https://www.typescriptlang.org/tsconfig/#experimentalDecorators) and [disabling "define" semantics for class fields](https://www.typescriptlang.org/tsconfig/#useDefineForClassFields), if you choose to use TypeScript's experimental decorators.
+
+These options are generally set in your project's tsconfig.
+
+### Installation
 
 To install TypeScript in your project:
 
 ```bash
-npm install typescript --save-dev
+npm i -D typescript
 ```
 
 To build the code:
@@ -218,6 +229,10 @@ npx tsc --watch
 
 For full installation and usage instructions, see the [TypeScript site](https://www.typescriptlang.org/). To get started, the sections on [installing TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-tooling-in-5-minutes.html) and [using its features](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html) are particularly helpful.
 
+### Decorators
+
+TypeScript supports two versions of decorators: experimental and standard. See our [Decorators](/docs/v3/components/decorators/#decorators-typescript) documentation for more information.
+
 ## JavaScript and TypeScript linting { #linting }
 
 Linting can help catch errors in your code. We recommend using [ESLint](https://eslint.org) for linting Lit code.