Adds updated examples

Examples/README.md

@@ -0,0 +1,15 @@
+# TypeScript Example Code
+
+The English examples can be found in [`en/`](en/).
+
+# Deployment
+
+There is a table of contents JSON file which contains
+all the useful metadata about the hierarchy and sort
+order for the docs. 
+
+It's likely that we'll need to create this per translation
+in the future, but for now the table of contents will
+default to english.
+
+The script is in [`scripts/generateTOC.js`](scripts/generateTOC.js).

Examples/en/JavaScript/External APIs/TypeScript + Deno.ts

@@ -0,0 +1,36 @@
+//// { order: 3 }
+
+// Deno is a work-in-progress JavaScript and TypeScript
+// runtime based on v8 with a focus on security.
+
+// https://deno.land
+
+// Deno has a sandbox-based permissions system which reduces the
+// access JavaScript has to the file-system or the network and uses
+// http based imports which are downloaded and cached locally.
+
+// Here is an example of using deno for scripting:
+
+import compose from "https://deno.land/x/denofun/lib/compose.ts";
+
+function greet(name: string) {
+  return `Hello, ${name}!`;
+}
+
+function makeLoud(x: string) {
+  return x.toUpperCase();
+}
+
+const greetLoudly = compose(
+  makeLoud,
+  greet
+);
+
+// Echos "HELLO, WORLD!."
+greetLoudly("world");
+
+
+import concat from "https://deno.land/x/denofun/lib/concat.ts";
+
+// Returns "helloworld"
+concat("hello", "world");

Examples/en/JavaScript/External APIs/TypeScript + Node.js

@@ -0,0 +1,50 @@
+// Node is a very popular JavaScript runtime built on v8,
+// the JavaScript engine which powers Chrome. You can use it
+// to build servers, front-end clients and anything in-between.
+
+// https://nodejs.org/en/
+
+// Node comes with a set of core libraries which extend the
+// JavaScript runtime, they range from path handling:
+
+import { join } from "path";
+const myPath = join("~", "downloads", "todo_list.json");
+
+// To file manipulation:
+
+import { readFileSync } from "fs";
+const todoListText = readFileSync(myPath, "utf8");
+
+// You can incrementally add types to your JavaScript projects
+// using JSDoc-style type. We'll make one for our TODO list item
+// based on the JSON structure:
+
+/**
+ * @typedef {Object} TODO a TODO item
+ * @property {string} title The display name for the TODO item
+ * @property {string} body The name used to show the user
+ * @property {boolean} done The name used to show the user
+ */
+
+// Now assign that to the return value of JSON.parse
+// to learn more about this, see: example:jsdoc-support
+
+/** @type {TODO[]} a list of TODOs */
+const todoList = JSON.parse(todoListText);
+
+// And process handling:
+import { spawnSync } from "child_process";
+todoList
+  .filter(todo => !todo.done)
+  .forEach(todo => {
+    // Use the ghi client to create an issue for every todo
+    // list item which hasn't been completed yet.
+
+    // Note that you get correct auto-complete and
+    // docs in JS when you highlight 'todo.title' below
+    spawnSync(`ghi open --message "${todo.title}\n${todo.body}" `);
+  });
+
+// TypeScript has up-to-date type definitions for all of the
+// built in modules via DefinitelyTyped - which means you
+// can write node programs with strong type coverage.

Examples/en/JavaScript/External APIs/TypeScript + React.tsx

@@ -0,0 +1,136 @@
+//// { order: 2, compiler: { jsx: "react" } }
+
+// React is a popular library for creating user interfaces.
+// It provides a JavaScript abstraction for creating view 
+// components using a JavaScript language extension called
+// JSX. 
+
+// TypeScript supports JSX, and provides a rich set of 
+// type tools to richly model how components connect.
+
+// To understand how TypeScript works with React components
+// you may want a primer on generics: 
+
+// - example:generic-functions
+// - example:generic-classes
+
+// First we'll look at how generic interfaces are used to map
+// React components. This is a faux-React functional component:
+
+
+type FauxactFunctionComponent<Props extends {}> =
+  (props: Props, context?: any) => FauxactFunctionComponent | null
+
+
+// Roughly: 
+//
+// FauxactFunctionComponent is a generic function which relies on 
+// another type Props. Props has to be an object (to make sure
+// you don't pass a primitive) and the Props type will be 
+// re-used as the first argument in the function.
+
+// To use it, you need a props type:
+
+interface DateProps { iso8601Date: string }
+
+// We can then create a DateComponent which uses the
+// DateProp interface, and renders the date.
+
+const DateComponent: FauxactFunctionComponent<DateProps> =
+  (props) => <date>{props.iso8601Date}</date>
+
+// This creates a function which is generic with a Props 
+// variable which has to be an object. The component function 
+// returns either another component function or null.
+
+
+// The other component API is a class-based one, here's a
+// simplified version of that API:
+
+interface FauxactClassComponent<Props extends {}, State = {}> {
+  props: Props
+  state: State
+
+  setState: (prevState: State, props: Props) => Props
+  callback?: () => void
+  render(): FauxactClassComponent<any> | null
+
+}
+
+// Because this class can have both Props and State - it has
+// two generic arguments which are used throughout the class.
+
+// The React library comes with it's own type definitions
+// like these but are much more comprehensive. Let's bring
+// those into our playground and explore a few components.
+
+import React from 'react';
+
+// Your props are your public API, so it's worth taking the 
+// time to use JSDoc to explain how it works:
+
+export interface Props {
+  /** The user's name */
+  name: string;
+  /** Should the name be rendered in bold */
+  priority?: boolean
+}
+
+const PrintName: React.FC<Props> = (props) => {
+  return (
+    <div>
+      <p style={{ fontWeight: props.priority ? "bold" : "normal" }}>OK</p>
+    </div>
+  )
+}
+
+// You can play with the new component's usage below:
+
+const ShowUser: React.FC<Props> = (props) => {
+  return <PrintName name="Ned" />
+}
+
+// TypeScript supports providing intellisense inside
+// the {} in an attribute
+
+let username = "Cersei"
+const ShowStoredUser: React.FC<Props> = (props) => {
+  return <PrintName name={username} priority />
+}
+
+// TypeScript works with modern React code too, here you can
+// see that count and setCount have correctly been inferred
+// to use numbers based on the initial value passed into
+// useState.
+
+import { useState, useEffect } from 'react';
+
+const CounterExample = () => {
+  const [count, setCount] = useState(0);
+
+  useEffect(() => {
+    document.title = `You clicked ${count} times`;
+  });
+
+  return (
+    <div>
+      <p>You clicked {count} times</p>
+      <button onClick={() => setCount(count + 1)}>
+        Click me
+      </button>
+    </div>
+  );
+}
+
+// React and TypeScript is a really, really big topic
+// but the fundamentals are pretty small: TypeScript
+// supports JSX, and the rest is handled by the React
+// typings from definitely typed.
+
+// You can learn more about using React with TypeScript
+// from these sites:
+
+// https://github.com/typescript-cheatsheets/react-typescript-cheatsheet
+// https://egghead.io/courses/use-typescript-to-develop-react-applications
+// https://levelup.gitconnected.com/ultimate-react-component-patterns-with-typescript-2-8-82990c516935
+

Examples/en/JavaScript/External APIs/TypeScript + Web.js

@@ -0,0 +1,79 @@
+//// { order: 0 }
+
+// The DOM (Document Object Model) is the underlying API for
+//  working with a webpage, and TypeScript has great support
+// for that API.
+
+// Let's create a popover to show when you press run in
+// the toolbar above.
+
+const popover = document.createElement("div");
+popover.id = "example-popover";
+
+// Note that popover is correctly typed to be a HTMLDivElement
+// specifically because we passed in "div".
+
+// To make it possible to re-run this code, we'll first
+// add a function to remove the popover it it was already there.
+
+const removePopover = () => {
+  const existingPopover = document.getElementById(popover.id);
+  if (existingPopover && existingPopover.parentElement) {
+    existingPopover.parentElement.removeChild(existingPopover);
+  }
+};
+
+// Then call it right away
+
+removePopover();
+
+// We can set the inline styles on the element via the
+// .style property on a HTMLElement - this is fully typed
+
+popover.style.backgroundColor = "#0078D4";
+popover.style.color = "white";
+popover.style.border = "1px solid black";
+popover.style.position = "fixed";
+popover.style.bottom = "10px";
+popover.style.right = "20px";
+popover.style.width = "200px";
+popover.style.height = "100px";
+popover.style.padding = "10px";
+
+// Including more obscure, or deprecated CSS attributes
+popover.style.webkitBorderRadius = "4px";
+
+// To add content to the popover, we'll need to add
+// a paragraph element and use it to add some text
+
+const message = document.createElement("p");
+message.textContent = "Here is an example popover";
+
+// And we'll also add a close button
+
+const closeButton = document.createElement("a");
+closeButton.textContent = "X";
+closeButton.style.position = "absolute";
+closeButton.style.top = "3px";
+closeButton.style.right = "8px";
+closeButton.style.color = "white";
+
+closeButton.onclick = () => {
+  removePopover();
+};
+
+// Then add all of these elements on to the page
+popover.appendChild(message);
+popover.appendChild(closeButton);
+document.body.appendChild(popover);
+
+// If you hit "Run" above, then a popup should appear
+// in the bottom left, which you can close by clicking
+// on the x in the top right of the popup.
+
+// This example shows how you can work with the DOM API
+// in TypeScript - but it only shows a subset of working
+// with the browser's APIs which TypeScript supports
+
+// There is an extended example for TypeScript with the
+// WebGL example available here: example:typescript---webgl