Docs

Orta Therox (orta) · Jan 6, 2020 · Dec 26, 2019 · Dec 26, 2019 · Dec 26, 2019 · Dec 26, 2019
commit 10d37651f6c2a6a470be6d94655c619a5f68593e
diff --git a/README.md b/README.md
@@ -10,6 +10,9 @@ yarn bootstrap
 code .
 ```
 
+Working on this repo is done by running `yarn start` - this starts up the website on port `8000` and creates a
+builder worker for every package in the repo, so if you make a change outside of the site it will compile and lint etc.
+
 # Website Packages
 
 ## TypeScriptLang-Org
@@ -20,18 +23,14 @@ The main website for TypeScript, a Gatsby website which is statically deployed.
 yarn start
 ```
 
-## Playground
-
-A React component for the TypeScript playground base component. Not the one available on
-the site, but one you can use in other websites for showing off your APIs.
+## Sandbox
 
-You can work on the playground by running:
+The editor aspect of the TypeScript Playground REPL, useable for all sites which want to show a monaco editor
+with TypeScript or JavaScript code.
 
-```sh
-yarn playground
-```
+## Playground
 
-Then opening: http://localhost:1234 - which is the below package.
+The JS code as an AMD module for the playground which is loaded at runtime in the Playground website.
 
 # Doc Packages
 
@@ -54,7 +53,7 @@ yarn workspace tsconfig-reference run test
 # or to just run the linter without a build
 yarn workspace tsconfig-reference run lint
 
-# or to just one one linter
+# or to just one one linter for a single doc
 yarn workspace tsconfig-reference run lint resolveJson
 ```
 

diff --git a/packages/playground/README.md b/packages/playground/README.md
@@ -1,20 +1,19 @@
-# TypeScript Sandbox
+# TypeScript Playground
 
-The TypeScript Sandbox is the editor part of the TypeScript Playground. It's effectively an opinionated fork of 
-monaco-typescript with extra extension points so that projects like the TypeScript Playground can exist.
+This is the JS tooling which powers the https://www.typescriptlang.org/play/
 
-This project is useful to you if:
+It is more or less vanilla DOM-oriented JavaScript with as few dependencies as possible. Originally based on the
+work by [Artem Tyurin](https://github.com/agentcooper/typescript-play) but now it's pretty far from that fork.
 
-- You want to improve the TypeScript Playground
-- You want to present users of your library with a JS editor which has a typed API (in JS or TS)
+## Architecture
 
-## Goals
-q
-- Support multiple versions of TypeScript (via supporting older builds of monaco-typescript)
-- Easy to use when trying to replace code inline on a website
-- Support extension points required to build Playground
-- High level APIs for things like Automatic Type Acquisition or DTS additions
+The playground library sits above the [TypeScript sandbox](../Sandbox), and provides features like:
 
-## Builds
+- The code samples support
+- The navigation bars, and compiler flags UI
+- The sidebar plugin infrastructure for showing JS/DTS/etc
+- The export to Code Sandbox/TS AST Viewer/etc features
 
-CJS, ESModules, and UMD module formats are supported.
+When deciding where to add a feature to the TypeScript playground, consider if it would be useful to anyone showing
+TypeScript in a REPL. If yes, add it to the playground and expose a function for this library to use. For example
+Automatic Type Acquisition is a feature which lives in the sandbox and not the playground.
diff --git a/packages/playground/src/nav/index.ts b/packages/playground/src/nav/index.ts
@@ -0,0 +1 @@
+export const createNav = () => {}
diff --git a/packages/sandbox/README.md b/packages/sandbox/README.md
@@ -1,20 +1,71 @@
 # TypeScript Sandbox
 
-The TypeScript Sandbox is the editor part of the TypeScript Playground. It's effectively an opinionated fork of 
+The TypeScript Sandbox is the editor part of the TypeScript Playground. It's effectively an opinionated fork of
 monaco-typescript with extra extension points so that projects like the TypeScript Playground can exist.
 
 This project is useful to you if:
 
-- You want to improve the TypeScript Playground
 - You want to present users of your library with a JS editor which has a typed API (in JS or TS)
+- You want to work with monaco at a higher abstraction level
 
 ## Goals
-q
+
 - Support multiple versions of TypeScript (via supporting older builds of monaco-typescript)
 - Easy to use when trying to replace code inline on a website
 - Support extension points required to build Playground
 - High level APIs for things like Automatic Type Acquisition or DTS additions
 
 ## Builds
 
-CJS, ESModules, and UMD module formats are supported.
+This library currently ships as an AMD module. This is the same format that vscode/monaco use, and so you can use
+the same runtime loader patterns for importing into your web page. It is not a goal to provide ESM builds so people
+can run JS packagers over the project. If someone can make that work and have tests which validate it doesn't break,
+we'll accept it.
+
+## Installation
+
+```html
+<html>
+  <div id="loader">Loading...</div>
+  <div id="monaco-editor-embed" />
+  <script>
+    // First set up the VSCode loader in a script tag
+    const getLoaderScript = document.createElement('script');
+    getLoaderScript.src = "https://typescriptlang.org/v2/js/vs.loader.js";
+    getLoaderScript.async = true;
+    getLoaderScript.onload = () => {
+
+      // Now the loader is ready, tell require where it can get the version of monaco, and the sandbox
+      // This version uses the latest version of the sandbox, which is used on the TypeScript website
+      require.config({
+        paths: {
+          vs: "https://tswebinfra.blob.core.windows.net/cdn/3.7.3/monaco/min/vs",
+          sandbox: 'https://typescriptlang.org/v2/js/sandbox'
+        },
+        // This is something you need for monaco to work
+        ignoreDuplicateModules: ["vs/editor/editor.main"],
+      });
+
+      // Grab a copy of monaco, TypeScript and the sandbox
+      require(["vs/editor/editor.main", "vs/language/typescript/tsWorker", "sandbox/index"], async (main, ts, sandbox) => {
+        const initialCode = `import {markdown} from "danger"\n\nmarkdown("OK")`
+
+        const isOK = main && ts && sandbox
+        if (isOK) {
+          document.getElementById("loader")!.parentNode?.removeChild(document.getElementById("loader")!)
+        } else {
+          console.error("Could not get all the dependencies of sandbox set up!")
+          console.error("main", !!main, "ts", !!ts, "sandbox", !!sandbox)
+          return
+        }
+
+        // Create a sandbox and embed it into the the div #monaco-editor-embed
+        const playground = await sandbox.createTypeScriptSandbox({ text: initialCode, compilerOptions: {}, domID: "monaco-editor-embed", useJavaScript: false }, main, ts)
+        playground.editor.focus()
+      });
+    }
+
+    document.body.appendChild(getLoaderScript);
+  </script>
+</html>
+```
diff --git a/packages/typescriptlang-org/src/components/layout/TopNav.scss b/packages/typescriptlang-org/src/components/layout/TopNav.scss
@@ -70,12 +70,12 @@ html,
     svg {
       margin-right: 0.6rem;
       margin-left: 1rem;
-      margin-top: 0.68rem;
+      margin-top: 0.48rem;
     }
 
     span {
       position: relative;
-      top: -0.4rem;
+      top: -0.5rem;
       text-decoration: none;
     }
   }