Add Glint / template import docs (#561)

* Add Glint / template import docs

* fix typo

packages/test-app/app/docs/controller.js

@@ -22,7 +22,7 @@ export const TABLE_OF_CONTENTS = [
   { route: 'docs.derived-state', title: 'Derived State' },
   { route: 'docs.events', title: 'Awaiting Events / Conditions' },
   { route: 'docs.testing-debugging', title: 'Testing & Debugging' },
-  { route: 'docs.typescript', title: 'TypeScript' },
+  { route: 'docs.typescript', title: 'TypeScript / Glint' },
   { route: 'docs.faq', title: 'FAQ & Fact Sheet' },
 
   { section: 'Advanced' },

packages/test-app/app/docs/installation/template.hbs

@@ -14,7 +14,6 @@
   <ul>
     <li>At least <code>ember-cli-babel@^7.7.2</code></li>
     <li>At least <code>@babel/core@^7.5.0</code> (as a transitive dependency via <code>ember-cli-babel</code>)</li>
-    <li>At least <code>ember-cli-typescript@^2.0.0</code> and TypeScript 4.2+, if you want to use it with TypeScript</li>
   </ul>
 </p>
 
@@ -29,3 +28,10 @@
 
 <CodeSnippet @name="babel-transform-config.js" />
 
+<h4>Typescript and Glint</h4>
+
+<p>
+  <LinkTo @route="docs.typescript">Typescript and Glint docs</LinkTo> for setting up / using
+  Ember Concurency with TypeScript / Glint.
+</p>
+

packages/test-app/app/docs/typescript/template.hbs

@@ -1,58 +1,66 @@
-<h3>Using ember-concurrency with TypeScript</h3>
+<h3>TypeScript and Glint</h3>
 
 <p>
-  The documentation below covers how to use ember-concurrency v2.3+
-  with Ember Octane. For older versions of ember-concurrency (or pre-Octane Ember),
-  <a href="https://v221.ember-concurrency.com/docs/typescript">please see the old guides</a>.
-</p>
-
-<p>
-  ember-concurrency tasks play nicely with TypeScript and all of the APIs covered in these docs.
-  Here is an example of a TypeScript component with an ember-concurrency task:
+  Ember Concurrency tasks play nicely with TypeScript and all of the APIs
+  covered in these docs. Here is an example of a TypeScript component with an
+  ember-concurrency task:
 </p>
 
 <CodeSnippet @name="ts/basic-example.ts" />
 
-<h4>Typing <code>Task</code> objects</h4>
+<h4>Glint Template Registry</h4>
 
 <p>
-  In most cases, you don't need to provide type annotations for your task, but when you do
-  (such as when <a href="https://docs.ember-cli-typescript.com/ember/components?q=component#giving-args-a-type">
-  specifying the Args of a Glimmer component</a>), you can use the Task type:
+  Ember Concurrency provides a template registry for using the
+  <code>perform</code>,
+  <code>cancel-all</code>, and
+  <code>task</code>
+  helpers within handlebars templates in Glint "loose mode". See the example
+  below for how to include Ember Concurrency's template registry in your Glint
+  configuration.
 </p>
 
-<CodeSnippet @name="ts/typing-task.ts" />
+<CodeSnippet @name="ts/template-registry-example.ts" />
 
-<h4>Version 2.2 and older</h4>
+<h4>Ember Template Imports (.gts/.gts) Files</h4>
 
 <p>
-  Support for TypeScript in ember-concurrency was recently greatly improved and simplified
-  with the release of version 2.3, largely due to the introduction of the new
-  async arrow task function syntax (e.g. <code>myTask = task(async () => {})</code>),
-  which alleviated most / all of the prior challenges with getting ember-concurrency tasks
-  to play nicely with TypeScript.
+  Here is an example of a modern .gts file in "strict mode" which imports the
+  classic
+  <code>perform</code>
+  helper from Ember Concurrency.
 </p>
 
-<ul>
-  <li>
-    <strong>
-      <a href="https://github.com/chancancode/ember-concurrency-async">ember-concurrency-async</a>
-    </strong>
-    is no longer necessary
-  </li>
-    <li>
-    <strong>
-      <a href="https://github.com/chancancode/ember-concurrency-ts">ember-concurrency-ts</a>
-    </strong>
-    and the <code>taskFor()</code> function it provides is no longer necessary
-    for interacting with tasks declared using the new syntax. See <a href="https://github.com/machty/ember-concurrency/releases/tag/2.3.0">v2.3.0</a> and <a href="https://github.com/machty/ember-concurrency/releases/tag/2.3.2">v2.3.2</a> release notes.
-  </li>
-</ul>
+<p>
+  Note: while you can import and use the
+  <code>perform</code>
+  helper, it is actually recommended to use the
+  <code>.perform()</code>
+  method on each task, which is internally bound to the task (similar to methods
+  decorated with
+  <code>@action</code>). One of the benefits of using the
+  <code>.perform()</code>
+  method is that it can be used with modern idiomatic patterns like using the
+  <code>fn</code>
+  helper to curry additional args when performing the task.
+</p>
 
 <p>
-  If you would like to see the TypeScript guides for older versions of ember-concurrency
-  (or pre-Octane Ember), please
-  <a href="https://v221.ember-concurrency.com/docs/typescript">see the old guides</a>.
+  <em>Pardon the lack of syntax! PR's welcome to improve our syntax
+    highlighting!</em>
 </p>
 
+<CodeSnippet @name="ts/template-import-example.txt" />
+
+<h4>Typing <code>Task</code> objects</h4>
+
+<p>
+  In most cases, you don't need to provide type annotations for your task, but
+  when you do (such as when
+  <a
+    href="https://docs.ember-cli-typescript.com/ember/components?q=component#giving-args-a-type"
+  >
+    specifying the Args of a Glimmer component</a>), you can use the Task type:
+</p>
 
+<CodeSnippet @name="ts/typing-task.ts" />

packages/test-app/snippets/ts/template-import-example.txt

@@ -0,0 +1,33 @@
+import GlimmerComponent from "@glimmer/component";
+import { task } from "ember-concurrency";
+import perform from "ember-concurrency/helpers/perform";
+import { on } from "@ember/modifier";
+import { fn } from "@ember/helper";
+
+export default class Demo extends GlimmerComponent {
+  taskNoArgs = task(async () => {
+    console.log("Look ma, no args!");
+  });
+
+  taskWithArgs = task(async (value: string) => {
+    console.log(value);
+  });
+
+  <template>
+    <button type="button" {{on "click" this.taskNoArgs.perform}}>
+      Task with no Params (.perform method) (RECOMMENDED)
+    </button>
+
+    <button type="button" {{on "click" (perform this.taskNoArgs)}}>
+      Task with no Params (with classic perform helper)
+    </button>
+
+    <button type="button" {{on "click" (fn this.taskNoArgs.perform '123')}}>
+      Task with Params (currying with fn helper) (RECOMMENDED)
+    </button>
+
+    <button type="button" {{on "click" (perform this.taskWithArgs '123')}}>
+      Task with Params (currying with classic perform helper)
+    </button>
+  </template>
+}

packages/test-app/snippets/ts/template-registry-example.ts

@@ -0,0 +1,10 @@
+// e.g. types/glint.d.ts
+import '@glint/environment-ember-loose';
+import type EmberConcurrencyRegistry from 'ember-concurrency/template-registry';
+
+declare module '@glint/environment-ember-loose/registry' {
+  export default interface Registry
+    extends EmberConcurrencyRegistry /* other addon registries */ {
+    // local entries
+  }
+}