Merge pull request #722 from microsoft/js

Start of a JS section

packages/gatsby-remark-shiki-twoslash/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gatsby-remark-shiki-twoslash",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "license": "MIT",
   "homepage": "https://github.com/microsoft/TypeScript-Website/",
   "author": "Orta Therox",
@@ -19,8 +19,8 @@
     "lint": "tsdx lint"
   },
   "dependencies": {
-    "@typescript/twoslash": "0.4.0",
-    "@typescript/vfs": "1.0.0",
+    "@typescript/twoslash": "0.5.0",
+    "@typescript/vfs": "1.0.1",
     "typescript": "*",
     "shiki": "^0.1.6",
     "shiki-languages": "^0.1.6",

packages/gatsby-remark-shiki-twoslash/src/renderer.ts

@@ -164,7 +164,8 @@ export function renderToHTML(lines: Lines, options: Options, twoslash?: TwoSlash
     }
   })
   html = replaceTripleArrowEncoded(html.replace(/\n*$/, "")) // Get rid of final new lines
-  html += `</code></div></pre>`
+  const playgroundLink = `<a href='${twoslash.playgroundURL}'>Try</a>`
+  html += `</code>${playgroundLink}</div></pre>`
 
   return html
 }

packages/gatsby-remark-shiki-twoslash/test/results/exporting.html

@@ -9,7 +9,7 @@ <h2>Relative imports</h2>
 
 <span style="color: #008000">// @filename: index.ts</span>
 <span style="color: #0000FF">import</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='import utils'>utils</data-lsp></span><span style="color: #000000"> </span><span style="color: #0000FF">from</span><span style="color: #000000"> </span><span style="color: #A31515">&apos;./utilFunctions&apos;</span>
-<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='const count: any'>count</data-lsp> </span><span style="color: #000000">= </span><span style="color: #1A1A1A"><data-lsp lsp='import utils'>utils</data-lsp></span><span style="color: #000000">.<data-lsp lsp='(property) getStringLength: (str: any) => any'>getStringLength</data-lsp>(</span><span style="color: #A31515">&apos;Check JS&apos;</span><span style="color: #000000">)</span></code></div></pre>
+<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='const count: any'>count</data-lsp> </span><span style="color: #000000">= </span><span style="color: #1A1A1A"><data-lsp lsp='import utils'>utils</data-lsp></span><span style="color: #000000">.<data-lsp lsp='(property) getStringLength: (str: any) => any'>getStringLength</data-lsp>(</span><span style="color: #A31515">&apos;Check JS&apos;</span><span style="color: #000000">)</span></code><a href='https://www.typescriptlang.org/play/#code/PTAEAEFMCdoe2gZwFygIwCYCsBOAUCBAGYCWANpAHYCGAtpKgK4Au5AYo5QMatyWIA6AFaI8XPomagA5pGYBlZtBKVpAGSrTmAC1ABeUJOj6AfIaUCKqnXlpwAJowoDIADwAOCZon2gA3nigMnKKyqoa1toANHgAvngEYOCkVnQMoCr2bgLeeCS0ntBSLOQ+RPC0oADkAsAlZBzcvPxVYhJS4pxSBvWCsgpKKuqaOgAUVQDC2pBcANagAFLyVQCUQA'>Try</a></div></pre>
 <p>Hello</p>
 
 <style>

packages/gatsby-remark-shiki-twoslash/test/results/highlight.html

@@ -2,7 +2,7 @@ <h2>Hello</h2>
 <pre
   class="shiki twoslash"
 ><div class="language-id">ts</div><div class='code-container'><code><span style="color: #0000FF">let</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='let helloWorld: string'>helloWorld</data-lsp> </span><span style="color: #000000">= </span><span style="color: #A31515">&apos;Hello World&apos;</span>
-<span class='query'>//  ^ = let helloWorld: string</span></code></div></pre>
+<span class='query'>//  ^ = let helloWorld: string</span></code><a href='https://www.typescriptlang.org/play/#code/DYUwLgBAFizA9gdXgJ2AEwgXggcgBKwITJrq4BQA9FRBAHoD8QA'>Try</a></div></pre>
 
 <style>
   .shiki {

packages/gatsby-remark-shiki-twoslash/test/results/inline-angle-brackets.html

@@ -3,13 +3,13 @@
   class="shiki twoslash"
 ><div class="language-id">ts</div><div class='code-container'><code><span style="color: #0000FF">let</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='let someValue: any'>someValue</data-lsp></span><span style="color: #000000">:</span><span style="color: #1A1A1A"> any </span><span style="color: #000000">= </span><span style="color: #A31515">"this is a string"</span>
 
-<span style="color: #0000FF">let</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='let strLength: number'>strLength</data-lsp></span><span style="color: #000000">:</span><span style="color: #1A1A1A"> number </span><span style="color: #000000">= (&lt;string&gt;</span><span style="color: #1A1A1A"><data-lsp lsp='let someValue: any'>someValue</data-lsp></span><span style="color: #000000">).<data-lsp lsp='(property) String.length: number'>length</data-lsp></span></code></div></pre>
+<span style="color: #0000FF">let</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='let strLength: number'>strLength</data-lsp></span><span style="color: #000000">:</span><span style="color: #1A1A1A"> number </span><span style="color: #000000">= (&lt;string&gt;</span><span style="color: #1A1A1A"><data-lsp lsp='let someValue: any'>someValue</data-lsp></span><span style="color: #000000">).<data-lsp lsp='(property) String.length: number'>length</data-lsp></span></code><a href='https://www.typescriptlang.org/play/#code/DYUwLgBAzg9gtiAagQ2AVxALgsgdgTwgF4IAiMACwEsoIadowAnK3Ac1IChPRIpmAMiHaVsuNHABGIJsQgAKADz8W7AHywEKdCACUAOlAiKQA'>Try</a></div></pre>
 <p>And the other is the <code>as</code>-syntax:</p>
 <pre
   class="shiki twoslash"
 ><div class="language-id">ts</div><div class='code-container'><code><span style="color: #0000FF">let</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='let someValue: any'>someValue</data-lsp></span><span style="color: #000000">:</span><span style="color: #1A1A1A"> any </span><span style="color: #000000">= </span><span style="color: #A31515">"this is a string"</span>
 
-<span style="color: #0000FF">let</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='let strLength: number'>strLength</data-lsp></span><span style="color: #000000">:</span><span style="color: #1A1A1A"> number </span><span style="color: #000000">= (</span><span style="color: #1A1A1A"><data-lsp lsp='let someValue: any'>someValue</data-lsp></span><span style="color: #000000"> </span><span style="color: #0000FF">as</span><span style="color: #000000"> string).<data-lsp lsp='(property) String.length: number'>length</data-lsp></span></code></div></pre>
+<span style="color: #0000FF">let</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='let strLength: number'>strLength</data-lsp></span><span style="color: #000000">:</span><span style="color: #1A1A1A"> number </span><span style="color: #000000">= (</span><span style="color: #1A1A1A"><data-lsp lsp='let someValue: any'>someValue</data-lsp></span><span style="color: #000000"> </span><span style="color: #0000FF">as</span><span style="color: #000000"> string).<data-lsp lsp='(property) String.length: number'>length</data-lsp></span></code><a href='https://www.typescriptlang.org/play/#code/DYUwLgBAzg9gtiAagQ2AVxALgsgdgTwgF4IAiMACwEsoIadowAnK3Ac1IChPRIpmAMiHaVsuNHABGIJsQgAKWAhToQOWvxbsAlADpQIikA'>Try</a></div></pre>
 <p>
   The two samples are equivalent. Using one over the other is mostly a choice of
   preference; however, when using TypeScript with JSX, only

packages/gatsby-remark-shiki-twoslash/test/results/large-chopped.html

@@ -28,7 +28,7 @@
 <span style="color: #000000">    </span><span style="color: #0000FF">case</span><span style="color: #000000"> </span><span style="color: #A31515">&apos;success&apos;</span><span style="color: #000000">:</span>
 <span style="color: #000000">      </span><span style="color: #0000FF">return</span><span style="color: #000000"> </span><span style="color: #A31515">`Downloaded </span><span style="color: #0000FF">${</span><span style="color: #1A1A1A"><data-lsp lsp='(parameter) state: NetworkSuccessState'>state</data-lsp></span><span style="color: #A31515">.</span><span style="color: #1A1A1A"><data-lsp lsp='(property) response: {&amp;#13;    title: string;&amp;#13;    duration: number;&amp;#13;    summary: string;&amp;#13;}'>response</data-lsp></span><span style="color: #A31515">.<data-lsp lsp='(property) title: string'>title</data-lsp></span><span style="color: #0000FF">}</span><span style="color: #A31515"> - </span><span style="color: #0000FF">${</span><span style="color: #1A1A1A"><data-lsp lsp='(parameter) state: NetworkSuccessState'>state</data-lsp></span><span style="color: #A31515">.</span><span style="color: #1A1A1A"><data-lsp lsp='(property) response: {&amp;#13;    title: string;&amp;#13;    duration: number;&amp;#13;    summary: string;&amp;#13;}'>response</data-lsp></span><span style="color: #A31515">.<data-lsp lsp='(property) summary: string'>summary</data-lsp></span><span style="color: #0000FF">}</span><span style="color: #A31515">`</span>
 <span style="color: #000000">  }</span>
-<span style="color: #000000">}</span></code></div></pre>
+<span style="color: #000000">}</span></code><a href='https://www.typescriptlang.org/play/#code/PTAEAEFMCdoe2gZwFygEwGYME4BQAXATwAdJQA5SfAdwQGsAZOAQwBMBLAOwHMBlfZvjIBeUAG9coUIgFDUAcgA2LDj3m4AvrgIkylGvQBizdosit+gkeMnTZkBQDMTZ1uqkBjOKwehOAVwBbACMYTW0iUgoqWmg6Xn8PD0hEREshUFEJKRkrBURE5NT3UGgU4jhORF9sqVB8dnwzVBloLm5bKVZ-aEF2StQAkLC66SDA5mhCFvw2nlstLRBQAFo1j398NZWdKP1Y+PtM6IM4pjZ29LIAHxOD41NzK9Bb-foEpJS0+21Hf04PA1Kn4Yu9ZP5EAAKXJyO5gqwAShmc24NikywASuxuAALfB+ODUUAAFV0vA8bWI+NYcBSBPxdE4hNA1Bx7A8ONAcEc9RxZHwOLKkFsywqQk4DWYinqukQdisoC8-kUrFAoQAdNp0WBiVN2vU4KBmJ9UkbQMR4KRoEQWWyOaB2IhOPJ8YgcZNzCKwMb4KapdLInTqKZpb1HWRmJxQDB4NBbDDIOqvD4taBlgAhQjSYP4Dn64EJgA0JLJFPYVMVkb8k3gRIFZH+-U4XtANOoUa4iu8ZEcyiJkalhEQjvjOft0Ps6oTCLRdQ8zGqoCUKna8mQnTqZXwPSj8gAIoTOMoLjx1WeSp4F2R5M5Hm516NtSS+TKooEIfjQnC4g9XM8+WUhYbk+iCGsaRTDjwvJkAABsmkAwaAjjsJAKoOnKiDMI4wqPqUVA7qAMEAKKwAgoAACRiAmSbdhoraHseqjcDBG7zou8gFCaiBrsBeHbtAUYwQe7aMeYFFUZOZSIBUVSJg0TSQHRKzidRUkydUU7jJMhAaCxUiLEAA'>Try</a></div></pre>
 <h1>Intersection Types</h1>
 <p>
   Intersection types are closely related to union types, but they are used very

packages/gatsby-remark-shiki-twoslash/test/results/one.html

@@ -1,7 +1,7 @@
 <h2>One liner with multiple IDs</h2>
 <pre
   class="shiki twoslash"
-><div class="language-id">ts</div><div class='code-container'><code><span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='const getStringLength: (str: string) => number'>getStringLength</data-lsp> </span><span style="color: #000000">= (</span><span style="color: #1A1A1A"><data-lsp lsp='(parameter) str: string'>str</data-lsp></span><span style="color: #000000">: string) </span><span style="color: #0000FF">=&gt;</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='(parameter) str: string'>str</data-lsp></span><span style="color: #000000">.<data-lsp lsp='(property) String.length: number'>length</data-lsp></span></code></div></pre>
+><div class="language-id">ts</div><div class='code-container'><code><span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='const getStringLength: (str: string) => number'>getStringLength</data-lsp> </span><span style="color: #000000">= (</span><span style="color: #1A1A1A"><data-lsp lsp='(parameter) str: string'>str</data-lsp></span><span style="color: #000000">: string) </span><span style="color: #0000FF">=&gt;</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='(parameter) str: string'>str</data-lsp></span><span style="color: #000000">.<data-lsp lsp='(property) String.length: number'>length</data-lsp></span></code><a href='https://www.typescriptlang.org/play/#code/MYewdgzgLgBA5gUygZSgJwJZjgGQdqACxgF4YAKaNALhiqzgEpSA+O9AOgBt84ig'>Try</a></div></pre>
 
 <style>
   .shiki {

packages/gatsby-remark-shiki-twoslash/test/results/simple-interface.html

@@ -4,7 +4,7 @@ <h2>The { should not dissapear</h2>
 ><div class="language-id">ts</div><div class='code-container'><code><span style="color: #0000FF">interface</span><span style="color: #000000"> <data-lsp lsp='interface User'>User</data-lsp> {</span>
 <span style="color: #000000">  </span><span style="color: #1A1A1A"><data-lsp lsp='(property) User.name: string'>name</data-lsp></span><span style="color: #000000">: string</span>
 <span style="color: #000000">  </span><span style="color: #1A1A1A"><data-lsp lsp='(property) User.id: number'>id</data-lsp></span><span style="color: #000000">: number</span>
-<span style="color: #000000">}</span></code></div></pre>
+<span style="color: #000000">}</span></code><a href='https://www.typescriptlang.org/play/#code/JYOwLgpgTgZghgYwgAgKoGdrIN4ChnIhwC2EAXMumFKAOb7LAAmFIArsQEbS4C+QA'>Try</a></div></pre>
 
 <style>
   .shiki {

packages/gatsby-remark-shiki-twoslash/test/results/simple.html

@@ -5,7 +5,7 @@ <h2>A simple example with some identifiers</h2>
 <span style="color: #000000">  <data-lsp lsp='(property) b: string'>b</data-lsp>: </span><span style="color: #A31515">&apos;1234&apos;</span><span style="color: #000000">,</span>
 <span style="color: #000000">}</span>
 
-<span style="color: #1A1A1A"><data-lsp lsp='const a: {&amp;#13;    b: string;&amp;#13;}'>a</data-lsp></span></code></div></pre>
+<span style="color: #1A1A1A"><data-lsp lsp='const a: {&amp;#13;    b: string;&amp;#13;}'>a</data-lsp></span></code><a href='https://www.typescriptlang.org/play/#code/MYewdgzgLgBAhjAvDA3gKBjARgLhgcgEYAmAZgBZ8AaNAXzTTiA'>Try</a></div></pre>
 
 <style>
   .shiki {

packages/gatsby-remark-shiki-twoslash/test/results/twoliner.html

@@ -5,7 +5,7 @@ <h2>Two liner with multiple IDs</h2>
 <span style="color: #0000FF">export</span><span style="color: #000000"> </span><span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='const getStringLength: (str: string) => number'>getStringLength</data-lsp> </span><span style="color: #000000">= (</span><span style="color: #1A1A1A"><data-lsp lsp='(parameter) str: string'>str</data-lsp></span><span style="color: #000000">: string) </span><span style="color: #0000FF">=&gt;</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='(parameter) str: string'>str</data-lsp></span><span style="color: #000000">.<data-lsp lsp='(property) String.length: number'>length</data-lsp></span>
 <span style="color: #008000">// @filename: index.ts</span>
 <span style="color: #0000FF">import</span><span style="color: #000000"> { </span><span style="color: #1A1A1A"><data-lsp lsp='(alias) const getStringLength: (str: string) => number&amp;#13;import getStringLength'>getStringLength</data-lsp></span><span style="color: #000000"> } </span><span style="color: #0000FF">from</span><span style="color: #000000"> </span><span style="color: #A31515">&apos;./getStringLength&apos;</span>
-<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='const b: number'>b</data-lsp> </span><span style="color: #000000">= <data-lsp lsp='(alias) getStringLength(str: string): number&amp;#13;import getStringLength'>getStringLength</data-lsp>(</span><span style="color: #A31515">&apos;string&apos;</span><span style="color: #000000">)</span></code></div></pre>
+<span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #1A1A1A"><data-lsp lsp='const b: number'>b</data-lsp> </span><span style="color: #000000">= <data-lsp lsp='(alias) getStringLength(str: string): number&amp;#13;import getStringLength'>getStringLength</data-lsp>(</span><span style="color: #A31515">&apos;string&apos;</span><span style="color: #000000">)</span></code><a href='https://www.typescriptlang.org/play/#code/PTAEAEDMEsBsFMB2BDAtvAXKA5vALgMp4BO0i2AMktngBYB0eAzgFDwAeADgPbF6gBjboib9chEmUrU6oALygAFKOJYVUgJTyAfKBX0E5OixAQYhtJlBkAJh0atoqHn1ABvHPiKlyVI7VAAX1BIYm5UUAByemBxbyk-GlpIliERfgAjeU8JH2l-RUj1ckiNIA'>Try</a></div></pre>
 
 <style>
   .shiki {

packages/handbook-v1/en/Intro to JS with TS.md

@@ -0,0 +1,69 @@
+---
+title: JS Projects Utilizing TypeScript
+layout: docs
+permalink: /docs/handbook/intro-to-js-ts.html
+oneline: How to add type checking to JavaScript files using TypeScript
+---
+
+The type system in TypeScript has different levels of strictness when working with a codebase:
+
+- A type-system based only on inference with JavaScript code
+- Incremental typing in JavaScript [via JSDoc](/docs/handbook/jsdoc-supported-types.html)
+- Using `// @ts-check` in a JavaScript file
+- TypeScript code
+- TypeScript with [`strict`](/tsconfig#strict) enabled
+
+Each step represents a move towards a safer type-system, but not every project needs that level of verification.
+
+## TypeScript with JavaScript
+
+This is when you use an editor which uses TypeScript to provide tooling like auto-complete, jump to symbol and refactoring tools like rename.
+The [homepage](/) has a list of editors which have TypeScript plugins.
+
+## Providing Type Hints in JS via JSDoc
+
+In a `.js` file, types can often be inferred. When types can't be inferred, they can be specified using JSDoc syntax.
+
+JSDoc annotations come before a declaration will be used to set the type of that declaration. For example:
+
+```js twoslash
+/** @type {number} */
+var x;
+
+x = 0; // OK
+x = false; // OK?!
+```
+
+You can find the full list of supported JSDoc patterns [in JSDoc Supported Types](/docs/handbook/jsdoc-supported-types.html).
+
+## `@ts-check`
+
+The last line of the previous code sample would raise an error in TypeScript, but it doesn't by default in a JS project.
+To enable errors in your JavaScript files add: `// @ts-check` to the first line in your `.js` files to have TypeScript raise it as an error.
+
+```js twoslash
+// @ts-check
+// @errors: 2322
+/** @type {number} */
+var x;
+
+x = 0; // OK
+x = false; // Not OK
+```
+
+If you have a lot of JavaScript files you want to add errors to then you can switch to using a [`jsconfig.json`](/docs/handbook/tsconfig-json.html).
+You can skip checking some files by adding a `// @ts-nocheck` comment to files.
+
+TypeScript may offer you errors which you disagree with, in those cases you can ignore errors on specific lines by adding `// @ts-ignore` or `// @ts-expect-error` on the preceding line.
+
+```js twoslash
+// @ts-check
+/** @type {number} */
+var x;
+
+x = 0; // OK
+// @ts-expect-error
+x = false; // Not OK
+```
+
+To learn more about how JavaScript is interpreted by TypeScript read [How TS Type Checks JS](/docs/handbook/type-checking-javascript-files.html)