Typescript development in Cirq and prototype Bloch sphere implementat…

…ion (#4171)

Typescript development in Cirq and prototype Bloch sphere implementation.

### Typescript Development in Cirq

This PR implements the features discussed in the [Typescript Development in Cirq RFC](https://docs.google.com/document/d/16LybO9bNqL3LaIy1pZCJQXSPvKs5g3IqKkkE3efqM8U/edit). 

#### Listed below are the features included in the PR:
 - Infrastructure and directory structure to allow Typescript development in Cirq, including:
   - Bundling Typescript into Javascript, and examples of how to use these bundles
   - Hot reloading development environment for both browser and notebook settings
   - Typescript testing framework using Mocha and Chai, including a test for the bloch sphere.
   - Coverage checks for Typescript unit tests. (100% coverage needed in CI)
   - End-to-end integration between the Python and Javascript (the bloch sphere)
   - Example of full coverage testing of the Python side
   - CI for the Typescript environment for testing and linting. 
   - Check scripts for testing and linting
 - An example 3d bloch sphere implementation. This bloch sphere can be viewed:
   - In the browser (development)
   - In a Jupyter notebook (development and production)
   - Via a generated HTML file. This file can be sent anywhere and be viewed in the browser, regardless of if the recipient has Cirq installed or not. 
 - A [up-to-date package on Test PyPI](https://test.pypi.org/project/cirq-web/0.12.0.dev20210616161134/) representing the state of the cirq-web package as of 6/16/21.
 - Documentation for using cirq-web in the README files.

![colab_web_pr_trial](https://user-images.githubusercontent.com/17647506/122309538-1673ab80-ced4-11eb-96dd-112ea46b6df9.gif)

.github/workflows/ci.yml

@@ -290,3 +290,49 @@ jobs:
         with:
           name: notebook-outputs
           path: out
+  ts-build:
+    name: Bundle file consistency
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          node-version: '14.16.1'
+      - name: Install npm
+        run: check/npm ci
+      - name: Check build matches the current
+        run: check/ts-build-current
+  ts-lint:
+    name: Typescript lint check
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          node-version: '14.16.1'
+      - name: Install npm
+        run: check/npm ci
+      - name: Lint
+        run: check/ts-lint 
+  ts-test:
+    name: Typescript tests
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          node-version: '14.16.1'
+      - name: Install npm dependencies
+        run: check/npm ci
+      - name: Unit tests
+        run: check/ts-test 
+      - name: End to end tests
+        run: check/ts-test-e2e
+  ts-coverage:
+    name: Typescript tests coverage
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          node-version: '14.16.1'
+      - name: Install npm dependencies
+        run: check/npm ci
+      - name: Test
+        run: check/ts-coverage

.gitignore

@@ -48,4 +48,4 @@ docs/api_docs
 .python-version
 
 # notebook test output
-out
+out

check/npm

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+# Copyright 2021 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+################################################################################
+# Allows the user to run npm commands from the top-level Cirq
+# directory.
+#
+# Usage:
+#     check/npm
+################################################################################
+
+# Get the working directory to the repo root.
+cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$(git rev-parse --show-toplevel)"
+
+npm --prefix 'cirq-web/cirq_ts' $@

check/npx

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+# Copyright 2021 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+################################################################################
+# Allows the user to run npx commands from the top-level directory
+#
+# Usage:
+#     check/ts-build
+################################################################################
+
+# Get the working directory to the repo root.
+cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$(git rev-parse --show-toplevel)"
+
+cd 'cirq-web/cirq_ts'
+npx $@

check/ts-build

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+# Copyright 2021 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+################################################################################
+# Build the bundle files for Cirq-web
+#
+# Usage:
+#     check/ts-build
+################################################################################
+
+# Get the working directory to the repo root.
+cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$(git rev-parse --show-toplevel)"
+
+check/npx webpack --mode production $@

check/ts-build-current

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+
+# Copyright 2021 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+################################################################################
+# Checks if all bundled files are up to date. 
+#
+# Usage:
+#     check/ts-build-changes
+################################################################################
+
+check/ts-build 
+
+# Find the changed bundle.js files, if any
+untracked=$(git status --porcelain 2>/dev/null | grep "cirq-web/cirq_ts/dist/" | cut -d " " -f 3)
+
+if [[ ! -z "$untracked" ]]; then
+    echo -e "\033[31mERROR: Uncommitted changes to bundle file(s) found! Please commit these files:\033[0m"
+    for generated in $untracked
+    do
+        echo -e "\033[31m ${generated}\033[0m"
+    done
+    exit 1
+fi
+
+exit 0

check/ts-coverage

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+# Copyright 2021 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+################################################################################
+# Runs the Istanbul coverage checker on the Typescript. Primarily used for CI.
+#
+# Usage:
+#     check/ts-lint
+################################################################################
+
+# Get the working directory to the repo root.
+cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$(git rev-parse --show-toplevel)"
+
+check/npm run coverage $@

check/ts-lint

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+# Copyright 2021 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+################################################################################
+# Runs the linter on the Typescript. Primarily used for CI.
+#
+# Usage:
+#     check/ts-lint
+################################################################################
+
+# Get the working directory to the repo root.
+cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$(git rev-parse --show-toplevel)"
+
+check/npm run lint $@

check/ts-lint-and-format

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+# Copyright 2021 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+################################################################################
+# Runs gts on the Typescript files in the cirq-web package
+#
+# Usage:
+#     check/ts-lint-and-format
+################################################################################
+
+# Get the working directory to the repo root.
+cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$(git rev-parse --show-toplevel)"
+
+check/npm run fix $@

check/ts-test

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+# Copyright 2021 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+################################################################################
+# Runs the test files 
+#
+# Usage:
+#     check/ts-test
+#
+# "npm run test" runs unit tests
+################################################################################
+
+# Get the working directory to the repo root.
+cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$(git rev-parse --show-toplevel)"
+
+check/npm run test $@

check/ts-test-e2e

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+# Copyright 2021 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+################################################################################
+# Runs the end to end tests and ensures that they're all passing
+#
+# Usage:
+#     check/ts-test-e2e
+#
+# "npm run test-e2e" runs end to end tests
+################################################################################
+
+# Get the working directory to the repo root.
+cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$(git rev-parse --show-toplevel)"
+
+check/npm run test-e2e $@

cirq-web/.gitignore

@@ -0,0 +1,12 @@
+# Ignore node modules
+node_modules/
+
+# Pytest files
+.pytest_cache/
+
+# Coverage testing information
+.nyc_output/
+
+# Extras
+build/
+