docs: Octane and much polish and clarification

.eslintrc.js

@@ -5,13 +5,13 @@ module.exports = {
     ecmaVersion: 2017,
     sourceType: 'module',
   },
-  plugins: ['ember', '@typescript-eslint', 'prettier'],
-  extends: ['eslint:recommended', 'plugin:ember/recommended'],
+  plugins: ['ember', '@typescript-eslint'],
+  extends: ['eslint:recommended', 'plugin:ember/recommended', 'prettier/@typescript-eslint'],
   env: {
     browser: true,
   },
   rules: {
-    "prettier/prettier": "error"
+    'prettier/prettier': 'error',
   },
   settings: {
     node: {
@@ -43,14 +43,10 @@ module.exports = {
         node: true,
       },
       plugins: ['node'],
-      rules: Object.assign(
-        {},
-        require('eslint-plugin-node').configs.recommended.rules,
-        {
-          // add your custom rules and overrides for node files here
-          'ember/avoid-leaking-state-in-ember-objects': 'off',
-        }
-      ),
+      rules: Object.assign({}, require('eslint-plugin-node').configs.recommended.rules, {
+        // add your custom rules and overrides for node files here
+        'ember/avoid-leaking-state-in-ember-objects': 'off',
+      }),
     },
 
     // test files

.github/workflows/octane-docs.yml

@@ -0,0 +1,29 @@
+name: Publish Draft Octane Docs
+
+on:
+  push:
+    branches:
+      - octane-docs
+
+jobs:
+  deploy-docs:
+    name: Deploy Docs Preview
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v1
+      - name: Install Node
+        uses: actions/setup-node@v1
+        with:
+          node-version: '^8.12'
+      - name: Install Dependencies
+        run: yarn install --frozen-lockfile
+      - name: Set Git Identity
+        run: |
+          git config --global user.name "Tomster"
+          git config --global user.email "[email protected]"
+      - name: Publish Docs
+        run: yarn ember deploy production
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ADDON_DOCS_VERSION_PATH: 'octane-docs'

config/deploy.js

@@ -4,6 +4,7 @@
 module.exports = function(deployTarget) {
   let ENV = {
     build: {},
+    git: {},
     // include other plugin configuration that applies to all deploy targets here
   };
 
@@ -22,6 +23,11 @@ module.exports = function(deployTarget) {
     // configure other plugins for production deploy target here
   }
 
+  const { GITHUB_ACTOR, GITHUB_TOKEN } = process.env;
+  if (GITHUB_ACTOR && GITHUB_TOKEN) {
+    ENV.git.repo = `https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/typed-ember/ember-cli-typescript.git`;
+  }
+
   // Note: if you need to build some configuration asynchronously, you can return
   // a promise that resolves with the ENV object instead of returning the
   // ENV object synchronously.

package.json

@@ -57,6 +57,8 @@
     "@commitlint/cli": "8.2.0",
     "@commitlint/config-conventional": "8.2.0",
     "@ember/optional-features": "1.2.0",
+    "@glimmer/component": "^1.0.0-beta.3",
+    "@glimmer/tracking": "^1.0.0-beta.3",
     "@typed-ember/renovate-config": "1.2.1",
     "@types/capture-console": "1.0.0",
     "@types/chai": "4.2.7",
@@ -66,6 +68,7 @@
     "@types/debug": "4.1.5",
     "@types/ember": "3.1.1",
     "@types/ember-qunit": "3.4.7",
+    "@types/ember__object": "^3.1.1",
     "@types/esprima": "4.0.2",
     "@types/express": "4.17.1",
     "@types/fs-extra": "8.0.1",
@@ -84,7 +87,7 @@
     "commitlint-azure-pipelines-cli": "1.0.2",
     "conventional-changelog-cli": "2.0.31",
     "ember-cli": "3.14.0",
-    "ember-cli-addon-docs": "ember-learn/ember-cli-addon-docs#4f5bfd11",
+    "ember-cli-addon-docs": "ember-learn/ember-cli-addon-docs#b180220",
     "ember-cli-addon-docs-esdoc": "0.2.3",
     "ember-cli-app-version": "3.2.0",
     "ember-cli-babel": "7.13.2",
@@ -110,6 +113,7 @@
     "ember-source": "3.15.0",
     "ember-try": "1.4.0",
     "eslint": "6.7.2",
+    "eslint-config-prettier": "^6.9.0",
     "eslint-plugin-ember": "7.7.2",
     "eslint-plugin-node": "10.0.0",
     "eslint-plugin-prettier": "3.1.2",
@@ -123,6 +127,7 @@
     "loader.js": "4.7.0",
     "mocha": "6.2.2",
     "prettier": "1.18.2",
+    "prettier-eslint": "^9.0.1",
     "qunit-dom": "0.9.2",
     "testdouble": "3.12.4",
     "tmp": "0.1.0",

tests/dummy/app/components/args-getter.ts

@@ -0,0 +1,9 @@
+// BEGIN-SNIPPET args-getter.ts
+import Component from '@glimmer/component';
+
+export default class ArgsDisplay extends Component {
+  get argNames(): string[] {
+    return Object.keys(this.args);
+  }
+}
+// END-SNIPPET

tests/dummy/app/helpers/show-all.ts

@@ -0,0 +1,30 @@
+interface Dict<T = unknown> {
+  [key: string]: T | undefined;
+}
+
+// BEGIN-SNIPPET show-all.ts
+import { helper } from '@ember/component/helper';
+
+const describe = (entries: string): string => (entries.length > 0 ? entries : '(none)');
+
+export function showAll(positional: unknown[], named: Dict) {
+  // pretty print each item with its index, like `0: { neat: true }` or
+  // `1: undefined`.
+  const positionalEntries = positional
+    .reduce<string[]>((items, arg, index) => items.concat(`${index}: ${JSON.stringify(arg)}`), [])
+    .join(', ');
+
+  // pretty print each item with its name, like `cool: beans` or
+  // `answer: 42`.
+  const namedEntries = Object.keys(named)
+    .reduce<string[]>(
+      (items, key) => items.concat(`${key}: ${JSON.stringify(named[key], undefined, 2)}`),
+      []
+    )
+    .join(', ');
+
+  return `positional: ${describe(positionalEntries)}\nnamed: ${describe(namedEntries)}`;
+}
+
+export default helper(showAll);
+// END-SNIPPET

tests/dummy/app/lib/generate-avatar.ts

@@ -0,0 +1,4 @@
+/** This exists just to support example code. */
+export function generateUrl(): string {
+  return '';
+}

tests/dummy/app/router.js

@@ -8,13 +8,48 @@ const Router = AddonDocsRouter.extend({
 
 Router.map(function() {
   docsRoute(this, function() {
-    this.route('upgrade-notes');
-    this.route('configuration');
-    this.route('ts-guide', function() {
+    this.route('getting-started', function() {
+      this.route('installation');
+      this.route('configuration');
+    });
+
+    this.route('ts', function() {
+      this.route('overview');
+      this.route('decorators');
       this.route('with-addons');
       this.route('using-ts-effectively');
       this.route('current-limitations');
     });
+
+    this.route('ember', function() {
+      this.route('overview');
+      this.route('components');
+      this.route('services');
+      this.route('testing');
+      this.route('routes');
+      this.route('controllers');
+      this.route('helpers');
+      this.route('apps-and-addons');
+    });
+
+    this.route('ember-data', function() {
+      this.route('overview');
+      this.route('models');
+      this.route('adapters');
+      this.route('serializers');
+      this.route('transforms');
+    });
+
+    this.route('legacy', function() {
+      this.route('overview');
+      this.route('ember-object');
+      this.route('computed-properties');
+      this.route('mixins');
+      this.route('ember-component');
+    });
+
+    this.route('upgrade-notes');
+
     this.route('troubleshooting', function() {
       this.route('conflicting-types');
     });

tests/dummy/app/snippets/args-display.ts

@@ -0,0 +1,13 @@
+// BEGIN-SNIPPET args-display.ts
+import Component from '@glimmer/component';
+
+const log = console.log.bind(console);
+
+export default class ArgsDisplay extends Component {
+  constructor(owner: unknown, args: {}) {
+    super(owner, args);
+
+    Object.keys(args).forEach(log);
+  }
+}
+// END-SNIPPET

tests/dummy/app/snippets/belongs-to.ts

@@ -0,0 +1,14 @@
+// BEGIN-SNIPPET belongs-to.ts
+import Model, { belongsTo } from '@ember-data/model';
+import DS from 'ember-data'; // NOTE: this is a workaround, see discussion below!
+import User from './user';
+import Site from './site';
+
+export default class Post extends Model {
+  @belongsTo('user')
+  user!: DS.PromiseObject<User>;
+
+  @belongsTo('site', { async: false })
+  site!: Site;
+}
+// END-SNIPPET

tests/dummy/app/snippets/cart-contents-bad.ts

@@ -0,0 +1,17 @@
+// BEGIN-SNIPPET cart-contents-bad.ts
+import Component from '@glimmer/component';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+
+import ShoppingCartService from 'my-app/services/shopping-cart';
+
+export default class CartContentsComponent extends Component {
+  @service shoppingCart: ShoppingCartService;
+
+  @action
+  remove(item) {
+    // Error: Property 'saveForLater' does not exist on type 'ShoppingCartService'.
+    this.shoppingCart.saveForLater(item);
+  }
+};
+// END-SNIPPET

tests/dummy/app/snippets/cart-contents-lookup.ts

@@ -0,0 +1,18 @@
+// BEGIN-SNIPPET cart-contents-lookup.ts
+import Component from '@glimmer/component';
+import { getOwner } from '@ember/application';
+import { action } from '@ember/object';
+
+import ShoppingCartService from 'my-app/services/shopping-cart';
+
+export default class CartContentsComponent extends Component {
+  get cart() {
+    return getOwner(this).lookup('service:shopping-cart') as ShoppingCartService;
+  }
+
+  @action
+  remove(item) {
+    this.cart.remove(item);
+  }
+};
+// END-SNIPPET

tests/dummy/app/snippets/cart-contents.ts

@@ -0,0 +1,16 @@
+// BEGIN-SNIPPET cart-contents.ts
+import Component from '@glimmer/component';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+
+import ShoppingCartService from 'my-app/services/shopping-cart';
+
+export default class CartContentsComponent extends Component {
+  @service shoppingCart: ShoppingCartService;
+
+  @action
+  remove(item) {
+    this.shoppingCart.remove(item);
+  }
+};
+// END-SNIPPET

tests/dummy/app/snippets/dict-usage.ts

@@ -0,0 +1,8 @@
+// BEGIN-SNIPPET dict-usage.ts
+let ages: Dict<number> = {
+  chris: 32,
+};
+
+let johnAge = ages['john']; // undefined
+let chrisAge = ages['chris']; // 32
+// END-SNIPPET

tests/dummy/app/snippets/dict.ts

@@ -0,0 +1,5 @@
+// BEGIN-SNIPPET dict.ts
+interface Dict<T = unknown> {
+  [key: string]: T | undefined;
+}
+// END-SNIPPET

tests/dummy/app/snippets/function-based-helpers.ts

@@ -0,0 +1,28 @@
+declare module '@ember/debug' {
+  export function assert(message: string, value: unknown): asserts value;
+}
+
+// BEGIN-SNIPPET function-based-helper.ts
+import { helper } from '@ember/component/helper';
+import { assert } from '@ember/debug';
+import { is } from '../../type-utils'
+
+export function join(positional: [unknown, unknown], named: Dict<unknown>) {
+  assert(
+    `'join' requires two 'string' positional parameters`,
+    is<[string, string]>(
+      positional,
+      positional.length === 2 &&
+      positional.every(el => typeof el === 'string')
+    )
+  );
+  assert(`'join' requires argument 'separator'`, typeof named.separator === 'string');
+
+  const joined = positional.join(named.separator);
+  const prefix = typeof named.prefix === 'string' ? named.prefix : '';
+
+  return `${prefix}${joined}`;
+}
+
+export default helper(join);
+// END-SNIPPET

tests/dummy/app/snippets/has-many.ts

@@ -0,0 +1,15 @@
+// BEGIN-SNIPPET has-many.ts
+import Model, { hasMany } from '@ember-data/model';
+import EmberArray from '@ember/array';
+import DS from 'ember-data'; // NOTE: this is a workaround, see discussion below!
+import Comment from './comment';
+import User from './user';
+
+export default class Thread extends Model {
+  @hasMany('comment')
+  comment!: DS.PromiseManyArray<Comment>;
+
+  @hasMany('user', { async: false })
+  participants!: EmberArray<User>;
+}
+// END-SNIPPET

tests/dummy/app/snippets/shopping-cart.ts

@@ -0,0 +1,20 @@
+// BEGIN-SNIPPET shopping-cart.ts
+import { A } from '@ember/array';
+import Service from '@ember/service';
+
+export default class ShoppingCartService extends Service {
+  items = A([]);
+
+  add(item) {
+    this.items.pushObject(item);
+  }
+
+  remove(item) {
+    this.items.removeObject(item);
+  }
+
+  empty() {
+    this.items.clear();
+  }
+}
+// END-SNIPPET

tests/dummy/app/snippets/simplified-glimmer-component.d.ts

@@ -0,0 +1,7 @@
+// BEGIN-SNIPPET simplified-glimmer-component.d.ts
+export default class Component<Args extends {} = {}> {
+  args: Args;
+
+  constructor(owner: unknown, args: Args);
+}
+// END-SNIPPET