docs(*): add better setup & configuration examples

- Update README to provide better explanation of setup and configuration options
- Add examples directory with simple "starter project"

Closes #12

.gitignore

@@ -1,5 +1,4 @@
 /coverage
 /dist
-/node_modules
-/spec/integration/node_modules
-/spec/integration/package-lock.json
+node_modules
+**/package-lock.json

.npmignore

@@ -1,6 +1,7 @@
 /.git
 /.github
 /coverage
+/examples
 /node_modules
 /spec
 /src

examples/README.md

@@ -0,0 +1,7 @@
+### Examples
+
+><img src="https://upload.wikimedia.org/wikipedia/commons/3/39/Cc-public_domain_mark_white.svg" alt="Public Domain Mark" height="48px" align="left" />The contents of this directory are not subject to the licensing terms of the `atom-ts-transpiler` package, and instead are freely released into the public domain by their respective authors. These examples are provided as-is with no warranty of any kind, and under no circumstances shall the author(s) be held liable for damages resulting directly or indirectly from their use.
+
+The following example packages are provided to give you an idea of where to start if you're considering writing a new package in TypeScript:
+
+* **simple:** *A tiny, unopinionated setup with just the bare-minimum requirements, plus tslint. Based on Atom's built-in "Package Generator."*

examples/simple/.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+npm-debug.log
+node_modules

examples/simple/keymaps/my-atom-package.json

@@ -0,0 +1,5 @@
+{
+  "atom-workspace": {
+    "ctrl-alt-o": "my-atom-package:toggle"
+  }
+}

examples/simple/lib/index.ts

@@ -0,0 +1,52 @@
+import { CompositeDisposable } from "atom";
+import MyAtomPackageView from "./views/MyAtomPackageView";
+
+let modalPanel: AtomCore.Panel;
+let myAtomPackageView: MyAtomPackageView;
+let subscriptions: CompositeDisposable;
+
+interface ISerializedState {
+  myAtomPackageViewState?: object;
+}
+
+export default {
+
+  activate(state: ISerializedState): void {
+    myAtomPackageView = new MyAtomPackageView(state.myAtomPackageViewState);
+    modalPanel = atom.workspace.addModalPanel({
+      item: myAtomPackageView.getElement(),
+      visible: false,
+    });
+
+    // Events subscribed to in atom's system can be easily cleaned up with a CompositeDisposable
+    subscriptions = new CompositeDisposable();
+
+    // Register command that toggles this view
+    subscriptions.add(atom.commands.add("atom-workspace", {
+      "my-atom-package:toggle": () => this.toggle(),
+    }));
+  },
+
+  deactivate(): void {
+    modalPanel.destroy();
+    subscriptions.dispose();
+    myAtomPackageView.destroy();
+  },
+
+  serialize(): ISerializedState {
+    return {
+      myAtomPackageViewState: myAtomPackageView.serialize(),
+    };
+  },
+
+  toggle(): void {
+    // tslint:disable-next-line no-console
+    console.log("MyAtomPackage was toggled!");
+    return (
+      modalPanel.isVisible() ?
+      modalPanel.hide() :
+      modalPanel.show()
+    );
+  },
+
+};

examples/simple/lib/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "es6",
+    "lib": [
+      "es6",
+      "dom"
+    ],
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "baseUrl": "../",
+    "removeComments": true,
+    "types": [ "atom", "node" ]
+  }
+}

examples/simple/lib/views/MyAtomPackageView.ts

@@ -0,0 +1,37 @@
+// If your view has data that should persist across sessions, you can put it here:
+// tslint:disable-next-line no-empty-interface
+interface ISerializedState {
+
+}
+
+export default class MyAtomPackageView {
+
+  public element: HTMLDivElement;
+
+  constructor(serializedState: ISerializedState) {
+    // Create root element
+    this.element = document.createElement("div");
+    this.element.classList.add("my-atom-package");
+
+    // Create message element
+    const message = document.createElement("div");
+    message.textContent = "The MyAtomPackage package is Alive! It's ALIVE!";
+    message.classList.add("message");
+    this.element.appendChild(message);
+  }
+
+  // Returns an object that can be retrieved when package is activated
+  public serialize(): ISerializedState {
+    return null;
+  }
+
+  // Tear down any state and detach
+  public destroy() {
+    this.element.remove();
+  }
+
+  public getElement() {
+    return this.element;
+  }
+
+}

examples/simple/menus/my-atom-package.json

@@ -0,0 +1,26 @@
+{
+  "context-menu": {
+    "atom-text-editor": [
+      {
+        "label": "Toggle my-atom-package",
+        "command": "my-atom-package:toggle"
+      }
+    ]
+  },
+  "menu": [
+    {
+      "label": "Packages",
+      "submenu": [
+        {
+          "label": "my-atom-package",
+          "submenu": [
+            {
+              "label": "Toggle",
+              "command": "my-atom-package:toggle"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

examples/simple/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "my-atom-package",
+  "main": "./lib/index.ts",
+  "version": "0.0.0",
+  "description": "A short description of your package",
+  "keywords": [],
+  "activationCommands": {
+    "atom-workspace": "my-atom-package:toggle"
+  },
+  "repository": "https://github.com/atom/my-atom-package",
+  "license": "MIT",
+  "engines": {
+    "atom": ">=1.13.0 <2.0.0"
+  },
+  "scripts": {
+    "lint": "tslint -p lib/tsconfig.json --type-check"
+  },
+  "dependencies": {
+    "@types/atom": "^1.21.4",
+    "atom-ts-transpiler": "^1.2.1",
+    "typescript": "^2.5.3"
+  },
+  "devDependencies": {
+    "tslint": "^5.7.0"
+  }
+}

examples/simple/styles/my-atom-package.less

@@ -0,0 +1,8 @@
+// The ui-variables file is provided by base themes provided by Atom.
+//
+// See https://github.com/atom/atom-dark-ui/blob/master/styles/ui-variables.less
+// for a full listing of what's available.
+@import "ui-variables";
+
+.my-atom-package {
+}

examples/simple/tslint.json

@@ -0,0 +1,3 @@
+{
+  "extends": "tslint:recommended"
+}