Convert Runner and Editor to widgets (#14)

Fixes #6

Author: kitsonk

Gruntfile.js

@@ -3,6 +3,12 @@ require('ts-node')
 		'compilerOptions': {
 			module: 'commonjs',
 			target: 'es2017',
+			lib: [
+				'es5',
+				'es2015',
+				'es2016',
+				'es2017'
+			],
 			typeRoots: [
 				'node_modules/@types'
 			],

README.md

@@ -18,6 +18,7 @@ The `web-editor` provides three main errors of functionality:
 * Provide an abstraction API to allow editing of those project files in the [`monaco-editor`](https://github.com/Microsoft/monaco-editor)
   in a browser.
 * Provide an API to allow the loaded project to be run in an `iframe`.
+* A router which understands GitHub gists ID for being able to load a project from a gist.
 
 This package is inteded to be integrated into a website which would provide a more rich user interface to allow editing and running
 the project in a browser.  There is a minimal API implemented in `examples/index.html` which allows the loading of example projects
@@ -47,6 +48,8 @@ There are several key methods of `project`:
   in the project, but you can specify as many different file types as arguments and only those types of files will be returned.
 * `.get(): ProjectJson | undefined` - Returns the object representation of the project JSON, including any changes that have been made
   while the project has been loaded.
+* `.getProgram(): Promise<Program>` - Returns an object which contains the properties of `css`, `dependencies`, `html`, and `modules`
+  which are designed to be used with the `Runner` widget as widget properties to specify the program to run.
 
 #### Usage
 
@@ -63,65 +66,97 @@ import project from '@dojo/web-editor/project';
 
 ### Editor
 
-This is a class which wraps `monaco-editor`, allowing the editor to seemlessly integrate with the project.  It will automatically
+This is a widget which wraps `monaco-editor`, allowing the editor to seemlessly integrate with the project.  It will automatically
 display files with the appropriate language intellisense as well as the file is edited, changes will automatically be sent to
 the project to keep it updated.
 
-The `Editor` constructor takes two arguments.  First, you need to provide a DOM element that will serve as the root for the editor.
-The second is an optional argument is a pass through of any options as specified in the `monaco.editor.IEditorOptions` interface.
+The `Editor` has two key properties:
 
-The class has only one method:
+* `filename` - This is the name of the file in the project which the editor should be displaying.  Changing this property will cause the widget to change the file that is currently being displayed.
+* `options` - Passed to the `monaco-editor` when it is created.  Needs to conform to the `monaco.editor.IEditorOptions` interface.
 
-* `.display(filename: string): void` - Displays the file based on the name supplied.  It will throw if the file is not part of the
-  currently loaded project.
+`Editor` is a themeable widget, with the only themeable class being `editor.base`.
 
 #### Usage
 
 Typical usage would be something like this:
 
-```typescript
+```ts
 import project from '@dojo/web-editor/project';
 import Editor from '@dojo/web-editor/Editor';
+import { v, w } from '@dojo/widget-core/d';
+import Projector from '@dojo/widget-core/mixins/Projector';
+import WidgetBase from '@dojo/widget-core/WidgetBase';
 
 (async () => {
     await project.load('some.project.json');
-    const editor = new Editor(document.getElementById('editor'));
-    editor.display('./src/somefile.ts');
+
+    class App extends WidgetBase {
+        render() {
+            return v('div', [
+                w(Editor, {
+                    filename: './src/main.ts'
+                })
+            ]);
+        }
+    }
+
+    const projector = new (Projector(App))();
+    projector.append();
 })();
 ```
 
 ### Runner
 
-This is a class which provides a simple API to run instances of a project within an `iframe` on a page.  It will automatically
-transpile the project and send the transpiled output to the `iframe`.
+A widget _runs_ a program in an `iframe`.  Updating the properties related to the program on the widget will
+cause it to re-render the program.
 
-The `Runner` constructor takes a single arugment, which is the `iframe` it should use to run the project in.
+The `Runner` has several key properties which control its behaviour:
 
-The class has one method of note:
+* `css`, `dependencies`, `html`, and `modules` - Properties that are part of a `Program` obtained from the returned promise of
+  `project.getProgram()`.
+* `loader` - An optional property which specifies the URI for the AMD loader to use with the program.  It defaults to the latest
+  version of the `@dojo/loader`.
+* `src` - An optional URI that will be the `src` of the `iframe` until a program is first run.  This needs to be a relative URI
+  to the host in order to ensure that the run program is not impacted by cross-domain restrictions.
+* `onError` - When a program is running and generates an error, this method would be called, passing a single argument of the error.
+* `onInitIframe` - Called, with an argument of the `iframe` which is called when the `Runner` has configured the `iframe` in the DOM
+* `onRun` - A method that is called when the `Runner` is finished standing up the program.  It does not reflect the actual state
+  of the program.
 
-* `.run(): Promise<void>` - an async function which will resolve when the project has been run.
+`Runner` is a themeable widget, with the only themeable class being `runner.base`.
 
 #### Usage
 
-```html
-<!DOCTYPE html>
-<html>
-<head><title>Example</title></head>
-<body>
-    <iframe src="@dojo/web-editor/support/blank.html" id="runner"></iframe>
-</body>
-</html>
-```
-
-```typescript
-import project from '@dojo/web-editor/project';
-import Runner from '@dojo/web-editor/Runner';
+```ts
+import { assign } from '@dojo/core/lang';
+import project, { Program } from '@dojo/web-editor/project';
+import Runner, { RunnerProperties } from '@dojo/web-editor/Runner';
+import { v, w } from '@dojo/widget-core/d';
+import { WidgetProperties } from '@dojo/widget-core/interfaces';
+import Projector from '@dojo/widget-core/mixins/Projector';
+import WidgetBase from '@dojo/widget-core/WidgetBase';
+
+interface AppProperties extends WidgetProperties {
+    program?: Program
+}
 
 (async () => {
     await project.load('some.project.json');
-    const runner = new Runner(document.getElementById('runner'));
-    await runner.run();
-    console.log('Ran!');
+
+    class App extends WidgetBase<AppProperties> {
+        render() {
+            return v('div', [
+                w(Runner, this.properties.program)
+            ]);
+        }
+    }
+
+    const projector = new (Projector(App))();
+    projector.append();
+
+    const program = await project.getProgram();
+    project.setProperties({ program });
 })();
 ```
 

package.json

@@ -18,12 +18,12 @@
   "homepage": "https://github.com/dojo/web-editor#readme",
   "devDependencies": {
     "@dojo/cli-export-project": ">=2.0.0-alpha.1",
-    "@dojo/i18n": "beta1",
-    "@dojo/interfaces": "beta1",
-    "@dojo/test-extras": ">=2.0.0-alpha.1",
-    "@dojo/widget-core": "beta1",
+    "@dojo/i18n": "next",
+    "@dojo/interfaces": "next",
+    "@dojo/test-extras": "^2.0.0-alpha.4",
     "@types/glob": "^5.0.30",
     "@types/grunt": "^0.4.21",
+    "@types/jsdom": "^2.0.30",
     "@types/node": "^7.0.12",
     "@types/sinon": "^2.1.2",
     "@types/source-map": "^0.5.0",
@@ -37,28 +37,32 @@
     "grunt-contrib-clean": "^1.0.0",
     "grunt-contrib-copy": "^1.0.0",
     "grunt-patcher": "^1.0.0",
+    "grunt-postcss": "^0.8.0",
     "grunt-ts": "^6.0.0-beta.15",
     "grunt-tslint": "^5.0.1",
     "grunt-webpack": "^2.0.1",
     "intern": "^3.4.3",
     "istanbul": "^0.4.5",
-    "maquette": "2.4.3",
     "postcss": "^5.2.17",
     "postcss-cssnext": "^2.10.0",
+    "postcss-import": "^10.0.0",
     "postcss-modules": "^0.6.4",
     "remap-istanbul": "^0.9.5",
     "sinon": "^2.1.0",
     "ts-node": "^3.0.2",
-    "tslint": "^5.0.0",
+    "tslint": "^5.3.2",
+    "typed-css-modules": "^0.2.0",
     "typescript": "^2.3.1",
     "webpack": "^2.4.1"
   },
   "dependencies": {
-    "@dojo/core": "beta1",
-    "@dojo/has": "beta1",
-    "@dojo/loader": "beta1",
-    "@dojo/routing": "beta1",
-    "@dojo/shim": "beta1",
+    "@dojo/core": "next",
+    "@dojo/has": "next",
+    "@dojo/loader": "next",
+    "@dojo/routing": "next",
+    "@dojo/shim": "next",
+    "@dojo/widget-core": "next",
+    "maquette": "kitsonk/maquette#build-master",
     "monaco-editor": "^0.8.3",
     "source-map": "^0.5.6"
   }

src/Editor.ts

@@ -1,47 +1,96 @@
-import Destroyable from '@dojo/core/Destroyable';
 import global from '@dojo/core/global';
 import { createHandle } from '@dojo/core/lang';
+import { queueTask } from '@dojo/core/queue';
 import { debounce } from '@dojo/core/util';
+import { v, w } from '@dojo/widget-core/d';
+import { Constructor, VirtualDomProperties, WidgetProperties } from '@dojo/widget-core/interfaces';
+import WidgetBase from '@dojo/widget-core/WidgetBase';
+import { ThemeableMixin, ThemeableProperties, theme } from '@dojo/widget-core/mixins/Themeable';
+import DomWrapper from '@dojo/widget-core/util/DomWrapper';
 import project from './project';
+import * as css from './styles/editor.m.css';
 
 const globalMonaco: typeof monaco = global.monaco;
 
 /**
- * A class which is a simple abstraction of the `monaco-editor` editor
+ * @type EditorProperties
+ *
+ * Properties that can be set on an `Editor` widget
+ *
+ * @property filename The filename (from the current `project`) that the editor should be displaying for editing
+ * @property options Editor options that should be passed to the monaco editor when it is created
+ * @property onEditorInit Called when the monaco editor is created and initialized by the widget, passing the instance of the monaco editor
+ * @property onEditorLayout Called when the widget calls `.layout()` on the monaco editor
  */
-export default class Editor extends Destroyable {
-	private _currentFile: string;
-	private _editor: monaco.editor.IStandaloneCodeEditor;
+export interface EditorProperties extends WidgetProperties, ThemeableProperties {
+	filename?: string;
+	options?: monaco.editor.IEditorOptions;
 
+	onEditorInit?(editor: monaco.editor.IStandaloneCodeEditor): void;
+	onEditorLayout?(): void;
+}
+
+const EditorBase = ThemeableMixin(WidgetBase);
+
+@theme(css)
+export default class Editor extends EditorBase<EditorProperties> {
+	private _editor: monaco.editor.IStandaloneCodeEditor | undefined;
+	private _EditorDom: Constructor<WidgetBase<VirtualDomProperties & WidgetProperties>>;
+	private _didChangeHandle: monaco.IDisposable;
+	private _onAfterRender = () => {
+		if (!this._editor) {
+			this._editor = globalMonaco.editor.create(this._root, this.properties.options);
+			this._didChangeHandle = this._editor.onDidChangeModelContent(debounce(this._onDidChangeModelContent, 1000));
+			const { onEditorInit } = this.properties;
+			this._setModel();
+			onEditorInit && onEditorInit(this._editor);
+
+			this.own(createHandle(() => {
+				if (this._editor) {
+					this._editor.dispose();
+					this._didChangeHandle.dispose();
+				}
+			}));
+		}
+		this._editor.layout();
+		this._queuedLayout = false;
+		const { onEditorLayout } = this.properties;
+		onEditorLayout && onEditorLayout();
+	}
 	private _onDidChangeModelContent = () => {
-		project.setFileDirty(this._currentFile);
+		if (this.properties.filename) {
+			project.setFileDirty(this.properties.filename);
+		}
 	}
+	private _queuedLayout = false;
+	private _root: HTMLDivElement;
 
-	/**
-	 * A class which is a simple abstraction of the `monaco-editor` editor
-	 * @param element The root HTML element to attach the editor to
-	 */
-	constructor (element: HTMLElement, options?: monaco.editor.IEditorOptions) {
-		super();
-
-		this._editor = globalMonaco.editor.create(element, options);
-		const didChangeHandle = this._editor.onDidChangeModelContent(debounce(this._onDidChangeModelContent, 1000));
+	private _setModel() {
+		const { filename } = this.properties;
+		if (this._editor && filename && project.includes(filename)) {
+			this._editor.setModel(project.getFileModel(filename));
+		}
+	}
 
-		this.own(createHandle(() => {
-			this._editor.dispose();
-			didChangeHandle.dispose();
-		}));
+	constructor() {
+		super();
+		const root = this._root = document.createElement('div');
+		root.style.height = '100%';
+		root.style.width = '100%';
+		this._EditorDom = DomWrapper(root);
 	}
 
-	/**
-	 * Display a file in the editor from the currently loaded project
-	 * @param model The model to display
-	 */
-	display(filename: string): void {
-		if (!project.includes(filename)) {
-			throw new Error(`File "${filename}" is not part of the project.`);
+	public render() {
+		/* TODO: Refactor when https://github.com/dojo/widget-core/pull/548 published */
+		if (!this._queuedLayout) {
+			/* doing this async, during the next major task, to allow the widget to actually render */
+			this._queuedLayout = true;
+			queueTask(this._onAfterRender);
 		}
-		this._currentFile = filename;
-		this._editor.setModel(project.getFileModel(filename));
+		this._setModel();
+		/* TODO: Create single node when https://github.com/dojo/widget-core/issues/553 resolved */
+		return v('div', {
+			classes: this.classes(css.base)
+		}, [ w(this._EditorDom, { key: 'editor' }) ]);
 	}
 }